create-aws-project 1.2.1

package/templates/apps/api/src/middleware/cognito-auth.ts

@@ -0,0 +1,90 @@
+import { CognitoJwtVerifier } from 'aws-jwt-verify';
+import type { CognitoJwtPayload } from 'aws-jwt-verify/jwt-model';
+import { errorResponse } from '../utils/response';
+import { ERROR_CODES, HTTP_STATUS } from '{{PACKAGE_SCOPE}}/common-types';
+
+/**
+ * Authenticated user information extracted from JWT token
+ */
+export interface AuthUser {
+  /** Cognito user ID (subject claim) */
+  sub: string;
+  /** User's email address (if available in token) */
+  email?: string;
+  /** Cognito groups the user belongs to */
+  groups?: string[];
+  /** Full JWT payload for additional claims access */
+  tokenPayload: CognitoJwtPayload;
+}
+
+// Verifier instantiated outside handler for JWKS caching across Lambda invocations
+const verifier = CognitoJwtVerifier.create({
+  userPoolId: process.env['COGNITO_USER_POOL_ID']!,
+  tokenUse: 'access',
+  clientId: process.env['COGNITO_CLIENT_ID']!,
+});
+
+/**
+ * Verify a JWT access token from the Authorization header
+ *
+ * @param authHeader - The Authorization header value (e.g., "Bearer <token>")
+ * @returns The authenticated user if token is valid, null otherwise
+ */
+export async function verifyToken(authHeader: string | undefined): Promise<AuthUser | null> {
+  if (!authHeader || !authHeader.startsWith('Bearer ')) {
+    return null;
+  }
+
+  const token = authHeader.slice(7); // Remove 'Bearer ' prefix
+
+  try {
+    const payload = await verifier.verify(token);
+    return {
+      sub: payload.sub,
+      email: payload.email as string | undefined,
+      groups: payload['cognito:groups'] as string[] | undefined,
+      tokenPayload: payload,
+    };
+  } catch (error) {
+    console.error('Token verification failed:', error);
+    return null;
+  }
+}
+
+/**
+ * Middleware wrapper that requires authentication for a handler
+ *
+ * Wraps a handler function to automatically verify the JWT token
+ * and pass the authenticated user to the handler.
+ *
+ * @example
+ * ```typescript
+ * export const handler = requireAuth(async (event, user) => {
+ *   console.log('User ID:', user.sub);
+ *   return successResponse({ userId: user.sub });
+ * });
+ * ```
+ *
+ * @param handler - Handler function that receives the event and authenticated user
+ * @returns Wrapped handler that validates authentication first
+ */
+export function requireAuth<T>(
+  handler: (event: T, user: AuthUser) => Promise<unknown>
+): (event: T) => Promise<unknown> {
+  return async (event: T) => {
+    const authHeader = (event as Record<string, Record<string, string>>).headers?.authorization ||
+                       (event as Record<string, Record<string, string>>).headers?.Authorization;
+
+    const user = await verifyToken(authHeader);
+
+    if (!user) {
+      return errorResponse(
+        ERROR_CODES.UNAUTHORIZED,
+        'Invalid or missing authentication token',
+        HTTP_STATUS.UNAUTHORIZED
+      );
+    }
+
+    return handler(event, user);
+  };
+}

package/templates/apps/api/src/models/UserModel.ts

@@ -0,0 +1,109 @@
+import { DynamoModel, BaseModel, generateUUID } from '../lib/dynamo';
+import type { User as UserType } from '{{PACKAGE_SCOPE}}/common-types';
+
+/**
+ * User interface extending BaseModel for DynamoDB
+ */
+export interface UserModel extends BaseModel {
+  email: string;
+  name: string;
+}
+
+/**
+ * User Model for DynamoDB operations
+ * Extends DynamoModel to provide user-specific functionality
+ */
+export class UserDynamoModel extends DynamoModel<UserModel> {
+  constructor(tableName?: string, region?: string) {
+    super(
+      tableName || process.env['DYNAMODB_TABLE'] || '{{PROJECT_NAME}}-table',
+      region || process.env['AWS_REGION'] || 'us-east-1'
+    );
+  }
+
+  /**
+   * Get entity name for logging
+   */
+  protected getEntityName(): string {
+    return 'User';
+  }
+
+  /**
+   * Generate unique ID for new users
+   */
+  protected async generateId(data: UserModel): Promise<string> {
+    return generateUUID();
+  }
+
+  /**
+   * Set GSI keys for user queries
+   * GSI1: Query users by email
+   * GSI2: Query users by creation date
+   */
+  protected setGSIKeys(entity: UserModel, now: string): void {
+    // GSI1: For email lookups
+    entity.pk1 = 'USER';
+    entity.sk1 = `EMAIL#${entity.email}`;
+
+    // GSI2: For time-based queries
+    entity.pk2 = 'USER';
+    entity.sk2 = `CREATED#${now}`;
+  }
+
+  /**
+   * Transform UserModel to User type for API responses
+   */
+  toUserType(userModel: UserModel): UserType {
+    return {
+      id: userModel.id,
+      email: userModel.email,
+      name: userModel.name,
+      createdAt: userModel.createdAt,
+      updatedAt: userModel.updatedAt,
+    };
+  }
+
+  /**
+   * Get user by email
+   */
+  async getByEmail(email: string): Promise<UserModel | null> {
+    try {
+      this.logger.info(`Getting user by email: ${email}`);
+
+      const results = await this.queryByGSI(
+        'GSI1',
+        'pk1 = :pk AND sk1 = :sk',
+        {
+          ':pk': 'USER',
+          ':sk': `EMAIL#${email}`,
+        }
+      );
+
+      return results.length > 0 ? results[0] : null;
+    } catch (error) {
+      this.logger.error('Error getting user by email', { email, error });
+      throw error;
+    }
+  }
+
+  /**
+   * Get users created after a specific date
+   */
+  async getByCreatedAfter(date: string): Promise<UserModel[]> {
+    try {
+      this.logger.info(`Getting users created after: ${date}`);
+
+      return await this.queryByGSI(
+        'GSI2',
+        'pk2 = :pk AND sk2 > :sk',
+        {
+          ':pk': 'USER',
+          ':sk': `CREATED#${date}`,
+        }
+      );
+    } catch (error) {
+      this.logger.error('Error getting users by created date', { date, error });
+      throw error;
+    }
+  }
+}

package/templates/apps/api/src/schemas/user.schema.ts

@@ -0,0 +1,44 @@
+import { JSONSchemaType } from 'ajv';
+import type { CreateUserRequest, UpdateUserRequest } from '{{PACKAGE_SCOPE}}/common-types';
+
+/**
+ * JSON Schema for CreateUserRequest
+ */
+export const createUserSchema: JSONSchemaType<CreateUserRequest> = {
+  type: 'object',
+  properties: {
+    email: {
+      type: 'string',
+      format: 'email',
+      minLength: 3,
+      maxLength: 255,
+    },
+    name: {
+      type: 'string',
+      minLength: 1,
+      maxLength: 255,
+      pattern: '^(?!\\s*$)(?!.*\\s$)(?!^\\s).*$', // No leading/trailing whitespace, not empty
+    },
+  },
+  required: ['email', 'name'],
+  additionalProperties: false,
+};
+
+/**
+ * JSON Schema for UpdateUserRequest
+ */
+export const updateUserSchema: JSONSchemaType<UpdateUserRequest> = {
+  type: 'object',
+  properties: {
+    name: {
+      type: 'string',
+      minLength: 1,
+      maxLength: 255,
+      pattern: '^(?!\\s*$)(?!.*\\s$)(?!^\\s).*$', // No leading/trailing whitespace, not empty
+      nullable: true,
+    },
+  },
+  required: [],
+  additionalProperties: false,
+  minProperties: 1, // At least one property must be present
+};

package/templates/apps/api/src/services/user-service.ts

@@ -0,0 +1,108 @@
+import type { User, CreateUserRequest, UpdateUserRequest } from '{{PACKAGE_SCOPE}}/common-types';
+import { UserDynamoModel } from '../models/UserModel';
+
+/**
+ * User Service
+ * Handles all business logic for user management with DynamoDB backend
+ */
+export class UserService {
+  private userModel: UserDynamoModel;
+
+  constructor() {
+    this.userModel = new UserDynamoModel();
+  }
+
+  /**
+   * Get all users
+   */
+  async getAllUsers(): Promise<User[]> {
+    const users = await this.userModel.scanAll();
+    return users.map(user => this.userModel.toUserType(user));
+  }
+
+  /**
+   * Get user by ID
+   */
+  async getUserById(id: string): Promise<User | null> {
+    const user = await this.userModel.getById(id);
+    return user ? this.userModel.toUserType(user) : null;
+  }
+
+  /**
+   * Get user by email
+   */
+  async getUserByEmail(email: string): Promise<User | null> {
+    const user = await this.userModel.getByEmail(email);
+    return user ? this.userModel.toUserType(user) : null;
+  }
+
+  /**
+   * Create a new user
+   */
+  async createUser(request: CreateUserRequest): Promise<User> {
+    // Check if user with email already exists
+    const existingUser = await this.userModel.getByEmail(request.email);
+    if (existingUser) {
+      throw new Error(`User with email ${request.email} already exists`);
+    }
+
+    const user = await this.userModel.create({
+      email: request.email,
+      name: request.name,
+    });
+
+    return this.userModel.toUserType(user);
+  }
+
+  /**
+   * Update an existing user
+   */
+  async updateUser(id: string, request: UpdateUserRequest): Promise<User | null> {
+    const updatedUser = await this.userModel.update(id, {
+      ...(request.name && { name: request.name }),
+    });
+
+    return updatedUser ? this.userModel.toUserType(updatedUser) : null;
+  }
+
+  /**
+   * Delete a user
+   */
+  async deleteUser(id: string): Promise<boolean> {
+    return await this.userModel.delete(id);
+  }
+
+  /**
+   * Delete multiple users
+   */
+  async batchDeleteUsers(ids: string[]): Promise<{ success: string[]; failed: Array<{ id: string; error: string }> }> {
+    return await this.userModel.batchDelete(ids);
+  }
+
+  /**
+   * Check if user exists
+   */
+  async userExists(id: string): Promise<boolean> {
+    const user = await this.userModel.getById(id);
+    return user !== null;
+  }
+
+  /**
+   * Get user count
+   */
+  async getUserCount(): Promise<number> {
+    const users = await this.userModel.scanAll();
+    return users.length;
+  }
+
+  /**
+   * Get users created after a specific date
+   */
+  async getUsersCreatedAfter(date: string): Promise<User[]> {
+    const users = await this.userModel.getByCreatedAfter(date);
+    return users.map(user => this.userModel.toUserType(user));
+  }
+}
+
+// Export singleton instance
+export const userService = new UserService();

package/templates/apps/api/src/utils/auth-context.ts

@@ -0,0 +1,60 @@
+import type { APIGatewayProxyEvent } from 'aws-lambda';
+import type { AuthUser } from '../middleware/cognito-auth';
+
+/**
+ * Get auth user from request context
+ * Used when auth is handled by API Gateway authorizer instead of middleware
+ *
+ * @param event - API Gateway proxy event with authorizer claims
+ * @returns AuthUser if claims present in context, null otherwise
+ */
+export function getAuthUserFromContext(event: APIGatewayProxyEvent): AuthUser | null {
+  const claims = event.requestContext?.authorizer?.claims;
+
+  if (!claims) {
+    return null;
+  }
+
+  return {
+    sub: claims.sub,
+    email: claims.email,
+    groups: claims['cognito:groups']?.split(','),
+    tokenPayload: claims as AuthUser['tokenPayload'],
+  };
+}
+
+/**
+ * Check if user has required group membership
+ *
+ * @param user - Authenticated user
+ * @param groupName - Name of the Cognito group to check
+ * @returns true if user belongs to the specified group
+ *
+ * @example
+ * ```typescript
+ * if (hasGroup(user, 'admins')) {
+ *   // User is an admin
+ * }
+ * ```
+ */
+export function hasGroup(user: AuthUser, groupName: string): boolean {
+  return user.groups?.includes(groupName) ?? false;
+}
+
+/**
+ * Check if user is the owner of a resource
+ *
+ * @param user - Authenticated user
+ * @param resourceOwnerId - The owner ID stored on the resource
+ * @returns true if the user's sub matches the resource owner ID
+ *
+ * @example
+ * ```typescript
+ * if (!isOwner(user, document.ownerId)) {
+ *   return errorResponse(ERROR_CODES.FORBIDDEN, 'Not authorized');
+ * }
+ * ```
+ */
+export function isOwner(user: AuthUser, resourceOwnerId: string): boolean {
+  return user.sub === resourceOwnerId;
+}

package/templates/apps/api/src/utils/common/helpers.ts

@@ -0,0 +1,26 @@
+/**
+ * Common utility functions
+ */
+
+/**
+ * Remove GSI (Global Secondary Index) fields from an entity
+ * Useful for cleaning data before returning to clients
+ */
+export function removeGSIFields<T extends Record<string, any>>(entity: T): Omit<T, 'pk1' | 'sk1' | 'pk2' | 'sk2' | 'pk3' | 'sk3' | 'pk4' | 'sk4' | 'pk5' | 'sk5' | 'pk6' | 'sk6'> {
+  const { pk1, sk1, pk2, sk2, pk3, sk3, pk4, sk4, pk5, sk5, pk6, sk6, ...rest } = entity;
+  return rest as Omit<T, 'pk1' | 'sk1' | 'pk2' | 'sk2' | 'pk3' | 'sk3' | 'pk4' | 'sk4' | 'pk5' | 'sk5' | 'pk6' | 'sk6'>;
+}
+
+/**
+ * Generate a unique ID
+ */
+export function generateUUID(): string {
+  return crypto.randomUUID();
+}
+
+/**
+ * Get current ISO timestamp
+ */
+export function getCurrentTimestamp(): string {
+  return new Date().toISOString();
+}

package/templates/apps/api/src/utils/lambda-handler.ts

@@ -0,0 +1,148 @@
+import type {
+  ApiGatewayProxyEvent,
+  ApiGatewayProxyResult,
+} from '{{PACKAGE_SCOPE}}/common-types';
+import { HTTP_STATUS, ERROR_CODES } from '{{PACKAGE_SCOPE}}/common-types';
+import { errorResponse } from './response';
+
+/**
+ * Parsed request data from API Gateway event
+ */
+export interface ParsedRequest<TBody = unknown> {
+  pathParameters: Record<string, string>;
+  queryParameters: Record<string, string>;
+  headers: Record<string, string>;
+  body: TBody | null;
+  rawBody: string | null;
+  httpMethod: string;
+  path: string;
+}
+
+/**
+ * Handler function type that receives parsed request data
+ */
+export type HandlerFunction<TBody = unknown, TResponse = unknown> = (
+  request: ParsedRequest<TBody>
+) => Promise<TResponse>;
+
+/**
+ * Parse the API Gateway event into a more convenient format
+ */
+export function parseRequest<TBody = unknown>(
+  event: ApiGatewayProxyEvent
+): ParsedRequest<TBody> {
+  const pathParameters = event.pathParameters || {};
+  const queryParameters = event.queryStringParameters || {};
+  const headers = event.headers || {};
+  const rawBody = event.body;
+
+  let body: TBody | null = null;
+  if (rawBody) {
+    try {
+      body = JSON.parse(rawBody) as TBody;
+    } catch (error) {
+      // Body parsing will be handled by validation in handlers
+      body = null;
+    }
+  }
+
+  return {
+    pathParameters,
+    queryParameters,
+    headers,
+    body,
+    rawBody,
+    httpMethod: event.httpMethod,
+    path: event.path,
+  };
+}
+
+/**
+ * Validate that required path parameters are present
+ */
+export function validatePathParameters(
+  pathParameters: Record<string, string>,
+  required: string[]
+): { valid: boolean; missing?: string[] } {
+  const missing = required.filter(param => !pathParameters[param]);
+
+  if (missing.length > 0) {
+    return { valid: false, missing };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Validate that request body is present
+ */
+export function validateBodyPresent(
+  body: unknown,
+  rawBody: string | null
+): { valid: boolean; error?: string } {
+  if (!rawBody) {
+    return { valid: false, error: 'Request body is required' };
+  }
+
+  if (!body) {
+    return { valid: false, error: 'Invalid JSON in request body' };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Wrapper for Lambda handlers that handles common request parsing and error handling
+ *
+ * @param handlerFn - The handler function to execute
+ * @param handlerName - Name of the handler for logging purposes
+ */
+export function createLambdaHandler<TBody = unknown, TResponse = unknown>(
+  handlerFn: HandlerFunction<TBody, TResponse>,
+  handlerName: string
+) {
+  return async (event: ApiGatewayProxyEvent): Promise<ApiGatewayProxyResult> => {
+    console.log(`[${handlerName}] Event:`, JSON.stringify(event, null, 2));
+
+    try {
+      const parsedRequest = parseRequest<TBody>(event);
+
+      console.log(`[${handlerName}] Parsed request:`, {
+        pathParameters: parsedRequest.pathParameters,
+        queryParameters: parsedRequest.queryParameters,
+        httpMethod: parsedRequest.httpMethod,
+        path: parsedRequest.path,
+        hasBody: !!parsedRequest.body,
+      });
+
+      const result = await handlerFn(parsedRequest);
+      return result as ApiGatewayProxyResult;
+    } catch (error) {
+      console.error(`[${handlerName}] Error:`, error);
+
+      // If error is already an ApiGatewayProxyResult, return it
+      if (error && typeof error === 'object' && 'statusCode' in error && 'body' in error) {
+        return error as ApiGatewayProxyResult;
+      }
+
+      // Otherwise, return a generic error
+      return errorResponse(
+        ERROR_CODES.INTERNAL_ERROR,
+        `Failed to process request in ${handlerName}`,
+        HTTP_STATUS.INTERNAL_SERVER_ERROR
+      );
+    }
+  };
+}
+
+/**
+ * Create an error result that can be thrown and caught by the handler wrapper
+ */
+export function createErrorResult(
+  code: string,
+  message: string,
+  statusCode: (typeof HTTP_STATUS)[keyof typeof HTTP_STATUS],
+  details?: Record<string, unknown>
+): ApiGatewayProxyResult {
+  return errorResponse(code, message, statusCode, details);
+}

package/templates/apps/api/src/utils/response.ts

@@ -0,0 +1,52 @@
+import type {
+  ApiGatewayProxyResult,
+  ApiResponse,
+  HTTP_STATUS,
+} from '{{PACKAGE_SCOPE}}/common-types';
+
+const defaultHeaders = {
+  'Content-Type': 'application/json',
+  'Access-Control-Allow-Origin': process.env['ALLOWED_ORIGINS'] || '*',
+  'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
+  'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+};
+
+export function successResponse<T>(
+  data: T,
+  statusCode: (typeof HTTP_STATUS)[keyof typeof HTTP_STATUS] = 200,
+  message?: string
+): ApiGatewayProxyResult {
+  const response: ApiResponse<T> = {
+    success: true,
+    data,
+    message,
+  };
+
+  return {
+    statusCode,
+    headers: defaultHeaders,
+    body: JSON.stringify(response),
+  };
+}
+
+export function errorResponse(
+  code: string,
+  message: string,
+  statusCode: (typeof HTTP_STATUS)[keyof typeof HTTP_STATUS] = 500,
+  details?: Record<string, unknown>
+): ApiGatewayProxyResult {
+  const response: ApiResponse = {
+    success: false,
+    error: {
+      code,
+      message,
+      details,
+    },
+  };
+
+  return {
+    statusCode,
+    headers: defaultHeaders,
+    body: JSON.stringify(response),
+  };
+}