feat: enhance API and middleware functionality: add public API routes, implement program and course member checks, and improve rate limiting for invite acceptance. Update OpenAPI spec generation to focus on public API endpoints and add new middleware for automation key scopes. Include new documentation for lesson AI features and public API tests.

apps/api/src/middlewares/automation-key-scopes.ts

@@ -0,0 +1,35 @@
+import { Context, Next } from 'hono';
+import type { TOrganizationApiKeyScope } from '@cio/utils/validation/organization';
+
+import { ErrorCodes } from '@api/utils/errors';
+import { organizationApiKeyHasScopes } from '@api/services/organization/automation-key';
+
+export const automationKeyScopesMiddleware =
+  (requiredScopes: readonly TOrganizationApiKeyScope[] = []) =>
+  async (c: Context, next: Next) => {
+    const automationKey = c.get('automationKey');
+
+    if (!automationKey) {
+      return c.json(
+        {
+          success: false,
+          error: 'Unauthorized',
+          code: ErrorCodes.UNAUTHORIZED
+        },
+        401
+      );
+    }
+
+    if (!organizationApiKeyHasScopes(automationKey.scopes ?? [], requiredScopes)) {
+      return c.json(
+        {
+          success: false,
+          error: 'Automation key is missing required scopes',
+          code: ErrorCodes.FORBIDDEN
+        },
+        403
+      );
+    }
+
+    return next();
+  };

apps/api/src/middlewares/course-member.ts

@@ -2,6 +2,7 @@ import { Context, Next } from 'hono';
 
 import { ErrorCodes } from '@api/utils/errors';
 import { isUserCourseMemberOrOrgAdmin } from '@cio/db/queries/group';
+import { ensureProgramCourseAccess } from '@api/services/course/course';
 
 /**
  * Middleware to check if the authenticated user is a member of a course's group
@@ -39,6 +40,11 @@ export const courseMemberMiddleware = async (c: Context, next: Next) => {
       return next();
     }
 
+    const backfilledFromProgram = await ensureProgramCourseAccess(courseId, user.id);
+    if (backfilledFromProgram) {
+      return next();
+    }
+
     return c.json(
       {
         success: false,

apps/api/src/middlewares/program-member.ts

@@ -0,0 +1,64 @@
+import { Context, Next } from 'hono';
+
+import { ErrorCodes } from '@api/utils/errors';
+import { isOrgAdminByProgramId, isProgramMember } from '@cio/db/queries/program';
+
+/**
+ * Middleware to check if the authenticated user is a member of the program
+ * or an org admin for the program's organization.
+ */
+export const programMemberMiddleware = async (c: Context, next: Next) => {
+  try {
+    const user = c.get('user');
+    if (!user) {
+      return c.json(
+        {
+          success: false,
+          error: 'Unauthorized',
+          code: 'UNAUTHORIZED'
+        },
+        401
+      );
+    }
+
+    const programId = c.req.param('programId');
+    if (!programId) {
+      return c.json(
+        {
+          success: false,
+          error: 'Program ID is required',
+          code: 'PROGRAM_ID_REQUIRED'
+        },
+        400
+      );
+    }
+
+    const [member, isOrgAdmin] = await Promise.all([
+      isProgramMember(programId, user.id),
+      isOrgAdminByProgramId(programId, user.id)
+    ]);
+
+    if (member || isOrgAdmin) {
+      return next();
+    }
+
+    return c.json(
+      {
+        success: false,
+        error: 'You must be a member of this program to perform this action',
+        code: ErrorCodes.PROGRAM_FORBIDDEN
+      },
+      403
+    );
+  } catch (error) {
+    console.error('Error in programMemberMiddleware:', error);
+    return c.json(
+      {
+        success: false,
+        error: 'Failed to verify program membership',
+        code: ErrorCodes.PROGRAM_MEMBER_CHECK_FAILED
+      },
+      500
+    );
+  }
+};

apps/api/src/middlewares/program-newsfeed-comment-author-or-team.ts

@@ -0,0 +1,101 @@
+import { Context, Next } from 'hono';
+import { ErrorCodes } from '@api/utils/errors';
+import {
+  getProgramMemberByProfileId,
+  getProgramMemberRole,
+  getProgramNewsfeedById,
+  getProgramNewsfeedCommentById,
+  isOrgAdminByProgramId
+} from '@cio/db/queries/program';
+import { ROLE } from '@cio/utils/constants';
+
+export const programNewsfeedCommentAuthorOrTeamMiddleware = async (c: Context, next: Next) => {
+  try {
+    const user = c.get('user');
+    if (!user) {
+      return c.json(
+        {
+          success: false,
+          error: 'Unauthorized',
+          code: 'UNAUTHORIZED'
+        },
+        401
+      );
+    }
+
+    const commentId = c.req.param('commentId');
+    if (!commentId) {
+      return c.json(
+        {
+          success: false,
+          error: 'Comment ID is required',
+          code: 'COMMENT_ID_REQUIRED'
+        },
+        400
+      );
+    }
+
+    const comment = await getProgramNewsfeedCommentById(Number(commentId));
+    if (!comment?.programNewsfeedId) {
+      return c.json(
+        {
+          success: false,
+          error: 'Comment not found',
+          code: ErrorCodes.PROGRAM_NEWSFEED_COMMENT_NOT_FOUND
+        },
+        404
+      );
+    }
+
+    const feed = await getProgramNewsfeedById(comment.programNewsfeedId);
+    if (!feed?.programId) {
+      return c.json(
+        {
+          success: false,
+          error: 'Program newsfeed item not found',
+          code: ErrorCodes.PROGRAM_NEWSFEED_NOT_FOUND
+        },
+        404
+      );
+    }
+
+    const member = await getProgramMemberByProfileId(feed.programId, user.id);
+    const isAuthor = comment.authorId === member?.id;
+    if (isAuthor) {
+      await next();
+      return;
+    }
+
+    const isOrgAdmin = await isOrgAdminByProgramId(feed.programId, user.id);
+    if (isOrgAdmin) {
+      await next();
+      return;
+    }
+
+    const roleId = await getProgramMemberRole(feed.programId, user.id);
+    const isTeamMember = roleId === ROLE.ADMIN || roleId === ROLE.TUTOR;
+    if (isTeamMember) {
+      await next();
+      return;
+    }
+
+    return c.json(
+      {
+        success: false,
+        error: 'Only the author or program team members can perform this action',
+        code: ErrorCodes.ORG_TEAM_NOT_AUTHORIZED
+      },
+      403
+    );
+  } catch (error) {
+    console.error('Error in programNewsfeedCommentAuthorOrTeamMiddleware:', error);
+    return c.json(
+      {
+        success: false,
+        error: 'Failed to verify comment authorization',
+        code: 'COMMENT_AUTH_CHECK_FAILED'
+      },
+      500
+    );
+  }
+};

apps/api/src/middlewares/program-team-member.ts

@@ -0,0 +1,65 @@
+import { Context, Next } from 'hono';
+
+import { ErrorCodes } from '@api/utils/errors';
+import { getProgramMemberRole, isOrgAdminByProgramId } from '@cio/db/queries/program';
+import { ROLE } from '@cio/utils/constants';
+
+/**
+ * Middleware to check if the authenticated user is a program teacher or org admin.
+ * Mirrors the course-team-member pattern for program routes.
+ */
+export const programTeamMemberMiddleware = async (c: Context, next: Next) => {
+  try {
+    const user = c.get('user');
+    if (!user) {
+      return c.json(
+        {
+          success: false,
+          error: 'Unauthorized',
+          code: 'UNAUTHORIZED'
+        },
+        401
+      );
+    }
+
+    const programId = c.req.param('programId');
+    if (!programId) {
+      return c.json(
+        {
+          success: false,
+          error: 'Program ID is required',
+          code: 'PROGRAM_ID_REQUIRED'
+        },
+        400
+      );
+    }
+
+    const [roleId, isOrgAdmin] = await Promise.all([
+      getProgramMemberRole(programId, user.id),
+      isOrgAdminByProgramId(programId, user.id)
+    ]);
+
+    if (roleId === ROLE.TUTOR || roleId === ROLE.ADMIN || isOrgAdmin) {
+      return next();
+    }
+
+    return c.json(
+      {
+        success: false,
+        error: 'Unauthorized',
+        code: ErrorCodes.UNAUTHORIZED
+      },
+      403
+    );
+  } catch (error) {
+    console.error('Error in programTeamMemberMiddleware:', error);
+    return c.json(
+      {
+        success: false,
+        error: 'Failed to verify program team membership',
+        code: 'PROGRAM_TEAM_MEMBER_CHECK_FAILED'
+      },
+      500
+    );
+  }
+};

apps/api/src/middlewares/rate-limiter.ts

@@ -88,8 +88,5 @@ export const createRateLimiter = (options: RateLimiterOptions = {}): MiddlewareH
 
 // Default rate limiter middleware with standard configuration
 export default createRateLimiter({
-  maxRequests: (c) =>
-    c.req.path === '/api/auth/get-session'
-      ? DEFAULT_RATE_LIMITER_OPTIONS.maxRequests * 3
-      : DEFAULT_RATE_LIMITER_OPTIONS.maxRequests
+  maxRequests: (c) => (c.req.path === '/api/auth/get-session' ? 1000 : DEFAULT_RATE_LIMITER_OPTIONS.maxRequests)
 });