@noony-serverless/core 0.1.1 → 0.2.0

package/build/middlewares/authenticationMiddleware.js

@@ -169,6 +169,93 @@ async function verifyToken(tokenVerificationPort, context, options = {}) {
         throw new errors_1.AuthenticationError('Invalid authentication');
     }
 }
+/**
+ * Class-based authentication middleware with comprehensive security features.
+ * Provides JWT validation, rate limiting, token blacklisting, and security logging.
+ *
+ * @template T - The type of user data returned by the token verification port
+ *
+ * @example
+ * Basic JWT authentication:
+ * ```typescript
+ * import { Handler, AuthenticationMiddleware } from '@noony-serverless/core';
+ * import jwt from 'jsonwebtoken';
+ *
+ * interface User {
+ *   id: string;
+ *   email: string;
+ *   roles: string[];
+ * }
+ *
+ * class JWTVerifier implements CustomTokenVerificationPort<User> {
+ *   async verifyToken(token: string): Promise<User> {
+ *     const payload = jwt.verify(token, process.env.JWT_SECRET!) as any;
+ *     return {
+ *       id: payload.sub,
+ *       email: payload.email,
+ *       roles: payload.roles || []
+ *     };
+ *   }
+ * }
+ *
+ * const protectedHandler = new Handler()
+ *   .use(new AuthenticationMiddleware(new JWTVerifier()))
+ *   .handle(async (request, context) => {
+ *     const user = context.user as User;
+ *     return {
+ *       success: true,
+ *       data: { message: `Hello ${user.email}`, userId: user.id }
+ *     };
+ *   });
+ * ```
+ *
+ * @example
+ * Advanced authentication with security options:
+ * ```typescript
+ * const secureAuthMiddleware = new AuthenticationMiddleware(
+ *   new JWTVerifier(),
+ *   {
+ *     maxTokenAge: 1800, // 30 minutes
+ *     rateLimiting: {
+ *       maxAttempts: 5,
+ *       windowMs: 15 * 60 * 1000 // 15 minutes
+ *     },
+ *     isTokenBlacklisted: async (tokenId) => {
+ *       return await redis.sismember('revoked_tokens', tokenId);
+ *     },
+ *     requiredClaims: {
+ *       issuer: 'my-auth-server',
+ *       audience: 'my-api'
+ *     }
+ *   }
+ * );
+ *
+ * const secureHandler = new Handler()
+ *   .use(secureAuthMiddleware)
+ *   .handle(async (request, context) => {
+ *     // Only authenticated users reach here
+ *     return { success: true, data: 'Secure data' };
+ *   });
+ * ```
+ *
+ * @example
+ * Google Cloud Functions integration:
+ * ```typescript
+ * import { http } from '@google-cloud/functions-framework';
+ *
+ * const userProfileHandler = new Handler()
+ *   .use(new AuthenticationMiddleware(new JWTVerifier()))
+ *   .handle(async (request, context) => {
+ *     const user = context.user as User;
+ *     const profile = await getUserProfile(user.id);
+ *     return { success: true, data: profile };
+ *   });
+ *
+ * export const getUserProfile = http('getUserProfile', (req, res) => {
+ *   return userProfileHandler.execute(req, res);
+ * });
+ * ```
+ */
 class AuthenticationMiddleware {
     tokenVerificationPort;
     options;
@@ -181,6 +268,135 @@ class AuthenticationMiddleware {
     }
 }
 exports.AuthenticationMiddleware = AuthenticationMiddleware;
+/**
+ * Factory function that creates an authentication middleware with token verification.
+ * Provides a functional approach for authentication setup.
+ *
+ * @template T - The type of user data returned by the token verification port
+ * @param tokenVerificationPort - The token verification implementation
+ * @param options - Authentication configuration options
+ * @returns A BaseMiddleware object with authentication logic
+ *
+ * @example
+ * Simple JWT authentication:
+ * ```typescript
+ * import { Handler, verifyAuthTokenMiddleware } from '@noony-serverless/core';
+ *
+ * class SimpleJWTVerifier implements CustomTokenVerificationPort<{ userId: string }> {
+ *   async verifyToken(token: string): Promise<{ userId: string }> {
+ *     // Simple token verification logic
+ *     if (token === 'valid-token') {
+ *       return { userId: 'user-123' };
+ *     }
+ *     throw new Error('Invalid token');
+ *   }
+ * }
+ *
+ * const handler = new Handler()
+ *   .use(verifyAuthTokenMiddleware(new SimpleJWTVerifier()))
+ *   .handle(async (request, context) => {
+ *     const user = context.user as { userId: string };
+ *     return { success: true, userId: user.userId };
+ *   });
+ * ```
+ *
+ * @example
+ * API key authentication with rate limiting:
+ * ```typescript
+ * interface APIKeyUser {
+ *   keyId: string;
+ *   permissions: string[];
+ *   organization: string;
+ * }
+ *
+ * class APIKeyVerifier implements CustomTokenVerificationPort<APIKeyUser> {
+ *   async verifyToken(token: string): Promise<APIKeyUser> {
+ *     const keyData = await this.validateAPIKey(token);
+ *     if (!keyData) {
+ *       throw new Error('Invalid API key');
+ *     }
+ *     return keyData;
+ *   }
+ *
+ *   private async validateAPIKey(key: string): Promise<APIKeyUser | null> {
+ *     // Database lookup or external validation
+ *     return {
+ *       keyId: 'key-123',
+ *       permissions: ['read', 'write'],
+ *       organization: 'org-456'
+ *     };
+ *   }
+ * }
+ *
+ * const apiHandler = new Handler()
+ *   .use(verifyAuthTokenMiddleware(
+ *     new APIKeyVerifier(),
+ *     {
+ *       rateLimiting: {
+ *         maxAttempts: 100,
+ *         windowMs: 60 * 1000 // 1 minute
+ *       }
+ *     }
+ *   ))
+ *   .handle(async (request, context) => {
+ *     const apiUser = context.user as APIKeyUser;
+ *     return {
+ *       success: true,
+ *       data: { organization: apiUser.organization }
+ *     };
+ *   });
+ * ```
+ *
+ * @example
+ * Express-style middleware chain:
+ * ```typescript
+ * import { Handler, verifyAuthTokenMiddleware, errorHandler } from '@noony-serverless/core';
+ *
+ * const authMiddleware = verifyAuthTokenMiddleware(
+ *   new JWTVerifier(),
+ *   {
+ *     maxTokenAge: 3600,
+ *     requiredClaims: {
+ *       issuer: 'my-app',
+ *       audience: 'api-users'
+ *     }
+ *   }
+ * );
+ *
+ * const protectedEndpoint = new Handler()
+ *   .use(authMiddleware)
+ *   .use(errorHandler())
+ *   .handle(async (request, context) => {
+ *     // Authenticated user available in context.user
+ *     return { success: true, data: 'Protected resource' };
+ *   });
+ * ```
+ *
+ * @example
+ * Multiple authentication strategies:
+ * ```typescript
+ * // Different handlers for different auth types
+ * const jwtHandler = new Handler()
+ *   .use(verifyAuthTokenMiddleware(new JWTVerifier()))
+ *   .handle(jwtLogic);
+ *
+ * const apiKeyHandler = new Handler()
+ *   .use(verifyAuthTokenMiddleware(new APIKeyVerifier()))
+ *   .handle(apiKeyLogic);
+ *
+ * // Route based on authentication type
+ * export const handleRequest = (req: any, res: any) => {
+ *   const authHeader = req.headers.authorization;
+ *   if (authHeader?.startsWith('Bearer jwt.')) {
+ *     return jwtHandler.execute(req, res);
+ *   } else if (authHeader?.startsWith('Bearer ak_')) {
+ *     return apiKeyHandler.execute(req, res);
+ *   } else {
+ *     res.status(401).json({ error: 'Authentication required' });
+ *   }
+ * };
+ * ```
+ */
 const verifyAuthTokenMiddleware = (tokenVerificationPort, options = {}) => ({
     async before(context) {
         await verifyToken(tokenVerificationPort, context, options);

package/build/middlewares/bodyParserMiddleware.d.ts

@@ -10,6 +10,58 @@ import { BaseMiddleware, Context } from '../core';
  *
  * @template T - The expected type of the parsed body. Defaults to unknown if not specified.
  * @implements {BaseMiddleware}
+ *
+ * @example
+ * Basic usage with typed body parsing:
+ * ```typescript
+ * import { Handler, BodyParserMiddleware } from '@noony-serverless/core';
+ *
+ * interface UserRequest {
+ *   name: string;
+ *   email: string;
+ *   age: number;
+ * }
+ *
+ * const createUserHandler = new Handler()
+ *   .use(new BodyParserMiddleware<UserRequest>())
+ *   .handle(async (context) => {
+ *     const userData = context.req.parsedBody as UserRequest;
+ *     console.log('User data:', userData.name, userData.email);
+ *     return { success: true, data: userData };
+ *   });
+ * ```
+ *
+ * @example
+ * Custom size limit configuration:
+ * ```typescript
+ * const largeBodyParser = new BodyParserMiddleware<any>(2 * 1024 * 1024); // 2MB limit
+ *
+ * const uploadHandler = new Handler()
+ *   .use(largeBodyParser)
+ *   .handle(async (context) => {
+ *     const uploadData = context.req.parsedBody;
+ *     return { success: true, size: JSON.stringify(uploadData).length };
+ *   });
+ * ```
+ *
+ * @example
+ * Google Cloud Pub/Sub message handling:
+ * ```typescript
+ * interface PubSubData {
+ *   eventType: string;
+ *   timestamp: string;
+ *   payload: any;
+ * }
+ *
+ * const pubSubHandler = new Handler()
+ *   .use(new BodyParserMiddleware<PubSubData>())
+ *   .handle(async (context) => {
+ *     // Automatically decodes base64 Pub/Sub message data
+ *     const messageData = context.req.parsedBody as PubSubData;
+ *     console.log('Event type:', messageData.eventType);
+ *     return { success: true, processed: true };
+ *   });
+ * ```
  */
 export declare class BodyParserMiddleware<T = unknown> implements BaseMiddleware {
     private maxSize;
@@ -25,7 +77,54 @@ export declare class BodyParserMiddleware<T = unknown> implements BaseMiddleware
  * - Size validation
  *
  * @template T - The expected type of the parsed request body.
+ * @param maxSize - Maximum allowed body size in bytes (default: 1MB)
  * @returns {BaseMiddleware} A middleware object containing a `before` hook.
+ *
+ * @example
+ * Basic body parsing with default settings:
+ * ```typescript
+ * import { Handler, bodyParser } from '@noony-serverless/core';
+ *
+ * const apiHandler = new Handler()
+ *   .use(bodyParser<{ name: string; email: string }>())
+ *   .handle(async (context) => {
+ *     const body = context.req.parsedBody;
+ *     return { success: true, received: body };
+ *   });
+ * ```
+ *
+ * @example
+ * Custom size limit for large uploads:
+ * ```typescript
+ * const uploadHandler = new Handler()
+ *   .use(bodyParser<any>(5 * 1024 * 1024)) // 5MB limit
+ *   .handle(async (context) => {
+ *     const uploadData = context.req.parsedBody;
+ *     console.log('Upload size:', JSON.stringify(uploadData).length);
+ *     return { success: true, uploadId: generateId() };
+ *   });
+ * ```
+ *
+ * @example
+ * Combining with validation middleware:
+ * ```typescript
+ * import { z } from 'zod';
+ * import { bodyParser, validationMiddleware } from '@noony-serverless/core';
+ *
+ * const userSchema = z.object({
+ *   name: z.string().min(1),
+ *   email: z.string().email(),
+ *   age: z.number().int().min(18)
+ * });
+ *
+ * const createUserHandler = new Handler()
+ *   .use(bodyParser<z.infer<typeof userSchema>>())
+ *   .use(validationMiddleware(userSchema))
+ *   .handle(async (context) => {
+ *     const validatedUser = context.req.validatedBody;
+ *     return { success: true, user: validatedUser };
+ *   });
+ * ```
  */
 export declare const bodyParser: <T = unknown>(maxSize?: number) => BaseMiddleware;
 //# sourceMappingURL=bodyParserMiddleware.d.ts.map

package/build/middlewares/bodyParserMiddleware.js

@@ -159,6 +159,58 @@ const parseBody = async (body) => {
  *
  * @template T - The expected type of the parsed body. Defaults to unknown if not specified.
  * @implements {BaseMiddleware}
+ *
+ * @example
+ * Basic usage with typed body parsing:
+ * ```typescript
+ * import { Handler, BodyParserMiddleware } from '@noony-serverless/core';
+ *
+ * interface UserRequest {
+ *   name: string;
+ *   email: string;
+ *   age: number;
+ * }
+ *
+ * const createUserHandler = new Handler()
+ *   .use(new BodyParserMiddleware<UserRequest>())
+ *   .handle(async (context) => {
+ *     const userData = context.req.parsedBody as UserRequest;
+ *     console.log('User data:', userData.name, userData.email);
+ *     return { success: true, data: userData };
+ *   });
+ * ```
+ *
+ * @example
+ * Custom size limit configuration:
+ * ```typescript
+ * const largeBodyParser = new BodyParserMiddleware<any>(2 * 1024 * 1024); // 2MB limit
+ *
+ * const uploadHandler = new Handler()
+ *   .use(largeBodyParser)
+ *   .handle(async (context) => {
+ *     const uploadData = context.req.parsedBody;
+ *     return { success: true, size: JSON.stringify(uploadData).length };
+ *   });
+ * ```
+ *
+ * @example
+ * Google Cloud Pub/Sub message handling:
+ * ```typescript
+ * interface PubSubData {
+ *   eventType: string;
+ *   timestamp: string;
+ *   payload: any;
+ * }
+ *
+ * const pubSubHandler = new Handler()
+ *   .use(new BodyParserMiddleware<PubSubData>())
+ *   .handle(async (context) => {
+ *     // Automatically decodes base64 Pub/Sub message data
+ *     const messageData = context.req.parsedBody as PubSubData;
+ *     console.log('Event type:', messageData.eventType);
+ *     return { success: true, processed: true };
+ *   });
+ * ```
  */
 class BodyParserMiddleware {
     maxSize;
@@ -190,7 +242,54 @@ exports.BodyParserMiddleware = BodyParserMiddleware;
  * - Size validation
  *
  * @template T - The expected type of the parsed request body.
+ * @param maxSize - Maximum allowed body size in bytes (default: 1MB)
  * @returns {BaseMiddleware} A middleware object containing a `before` hook.
+ *
+ * @example
+ * Basic body parsing with default settings:
+ * ```typescript
+ * import { Handler, bodyParser } from '@noony-serverless/core';
+ *
+ * const apiHandler = new Handler()
+ *   .use(bodyParser<{ name: string; email: string }>())
+ *   .handle(async (context) => {
+ *     const body = context.req.parsedBody;
+ *     return { success: true, received: body };
+ *   });
+ * ```
+ *
+ * @example
+ * Custom size limit for large uploads:
+ * ```typescript
+ * const uploadHandler = new Handler()
+ *   .use(bodyParser<any>(5 * 1024 * 1024)) // 5MB limit
+ *   .handle(async (context) => {
+ *     const uploadData = context.req.parsedBody;
+ *     console.log('Upload size:', JSON.stringify(uploadData).length);
+ *     return { success: true, uploadId: generateId() };
+ *   });
+ * ```
+ *
+ * @example
+ * Combining with validation middleware:
+ * ```typescript
+ * import { z } from 'zod';
+ * import { bodyParser, validationMiddleware } from '@noony-serverless/core';
+ *
+ * const userSchema = z.object({
+ *   name: z.string().min(1),
+ *   email: z.string().email(),
+ *   age: z.number().int().min(18)
+ * });
+ *
+ * const createUserHandler = new Handler()
+ *   .use(bodyParser<z.infer<typeof userSchema>>())
+ *   .use(validationMiddleware(userSchema))
+ *   .handle(async (context) => {
+ *     const validatedUser = context.req.validatedBody;
+ *     return { success: true, user: validatedUser };
+ *   });
+ * ```
  */
 const bodyParser = (maxSize = MAX_JSON_SIZE) => ({
     before: async (context) => {

package/build/middlewares/bodyValidationMiddleware.d.ts

@@ -1,12 +1,78 @@
 import { BaseMiddleware } from '../core/handler';
 import { Context } from '../core/core';
 import { z } from 'zod';
-export declare class BodyValidationMiddleware<T = unknown> implements BaseMiddleware {
+/**
+ * Body validation middleware using Zod schemas for runtime type checking.
+ * Validates the parsed request body against a provided Zod schema and sets
+ * the validated result in context.req.validatedBody.
+ *
+ * @template T - The expected type of the validated body data
+ * @implements {BaseMiddleware}
+ *
+ * @example
+ * Simple user creation with type safety:
+ * ```typescript
+ * import { z } from 'zod';
+ * import { Handler, BodyValidationMiddleware } from '@noony-serverless/core';
+ *
+ * const userSchema = z.object({
+ *   name: z.string().min(1),
+ *   email: z.string().email(),
+ *   age: z.number().min(18)
+ * });
+ *
+ * type UserRequest = z.infer<typeof userSchema>;
+ *
+ * async function handleCreateUser(context: Context<UserRequest>) {
+ *   const user = context.req.validatedBody!; // Fully typed
+ *   const authenticatedUser = context.user; // User type inferred from auth middleware
+ *   return { success: true, user: { id: '123', ...user } };
+ * }
+ *
+ * const createUserHandler = new Handler<UserRequest>()
+ *   .use(new BodyValidationMiddleware<UserRequest>(userSchema))
+ *   .handle(handleCreateUser);
+ * ```
+ */
+export declare class BodyValidationMiddleware<T = unknown> implements BaseMiddleware<T> {
     private readonly schema;
     constructor(schema: z.ZodSchema<T>);
-    before(context: Context): Promise<void>;
+    before(context: Context<T>): Promise<void>;
 }
+/**
+ * Factory function that creates a body validation middleware with Zod schema validation.
+ * This function validates and parses the request body, setting the result in context.req.parsedBody.
+ *
+ * @template T - The expected type of the validated body data
+ * @param schema - Zod schema to validate against
+ * @returns A BaseMiddleware object with validation logic
+ *
+ * @example
+ * Simple login validation:
+ * ```typescript
+ * import { z } from 'zod';
+ * import { Handler, bodyValidatorMiddleware } from '@noony-serverless/core';
+ *
+ * const loginSchema = z.object({
+ *   username: z.string().min(3),
+ *   password: z.string().min(8)
+ * });
+ *
+ * type LoginRequest = z.infer<typeof loginSchema>;
+ *
+ * async function handleLogin(context: Context<LoginRequest>) {
+ *   const credentials = context.req.parsedBody as LoginRequest;
+ *   const token = await authenticate(credentials.username, credentials.password);
+ *   const authenticatedUser = context.user; // User type from auth middleware
+ *   return { success: true, token };
+ * }
+ *
+ * const loginHandler = new Handler<LoginRequest>()
+ *   .use(bodyValidatorMiddleware<LoginRequest>(loginSchema))
+ *   .handle(handleLogin);
+ * ```
+ */
 export declare const bodyValidatorMiddleware: <T>(schema: z.ZodType<T>) => {
-    before: (context: Context) => Promise<void>;
+    before: (context: Context<T>) => Promise<void>;
 };
 //# sourceMappingURL=bodyValidationMiddleware.d.ts.map

package/build/middlewares/bodyValidationMiddleware.js

@@ -9,11 +9,44 @@ const validateBody = async (schema, data) => {
     }
     catch (error) {
         if (error instanceof zod_1.z.ZodError) {
-            throw new errors_1.ValidationError('Validation error', error.errors);
+            throw new errors_1.ValidationError('Validation error', error.issues);
         }
         throw error;
     }
 };
+/**
+ * Body validation middleware using Zod schemas for runtime type checking.
+ * Validates the parsed request body against a provided Zod schema and sets
+ * the validated result in context.req.validatedBody.
+ *
+ * @template T - The expected type of the validated body data
+ * @implements {BaseMiddleware}
+ *
+ * @example
+ * Simple user creation with type safety:
+ * ```typescript
+ * import { z } from 'zod';
+ * import { Handler, BodyValidationMiddleware } from '@noony-serverless/core';
+ *
+ * const userSchema = z.object({
+ *   name: z.string().min(1),
+ *   email: z.string().email(),
+ *   age: z.number().min(18)
+ * });
+ *
+ * type UserRequest = z.infer<typeof userSchema>;
+ *
+ * async function handleCreateUser(context: Context<UserRequest>) {
+ *   const user = context.req.validatedBody!; // Fully typed
+ *   const authenticatedUser = context.user; // User type inferred from auth middleware
+ *   return { success: true, user: { id: '123', ...user } };
+ * }
+ *
+ * const createUserHandler = new Handler<UserRequest>()
+ *   .use(new BodyValidationMiddleware<UserRequest>(userSchema))
+ *   .handle(handleCreateUser);
+ * ```
+ */
 class BodyValidationMiddleware {
     schema;
     constructor(schema) {
@@ -24,7 +57,40 @@ class BodyValidationMiddleware {
     }
 }
 exports.BodyValidationMiddleware = BodyValidationMiddleware;
-// Modified to fix type instantiation error
+/**
+ * Factory function that creates a body validation middleware with Zod schema validation.
+ * This function validates and parses the request body, setting the result in context.req.parsedBody.
+ *
+ * @template T - The expected type of the validated body data
+ * @param schema - Zod schema to validate against
+ * @returns A BaseMiddleware object with validation logic
+ *
+ * @example
+ * Simple login validation:
+ * ```typescript
+ * import { z } from 'zod';
+ * import { Handler, bodyValidatorMiddleware } from '@noony-serverless/core';
+ *
+ * const loginSchema = z.object({
+ *   username: z.string().min(3),
+ *   password: z.string().min(8)
+ * });
+ *
+ * type LoginRequest = z.infer<typeof loginSchema>;
+ *
+ * async function handleLogin(context: Context<LoginRequest>) {
+ *   const credentials = context.req.parsedBody as LoginRequest;
+ *   const token = await authenticate(credentials.username, credentials.password);
+ *   const authenticatedUser = context.user; // User type from auth middleware
+ *   return { success: true, token };
+ * }
+ *
+ * const loginHandler = new Handler<LoginRequest>()
+ *   .use(bodyValidatorMiddleware<LoginRequest>(loginSchema))
+ *   .handle(handleLogin);
+ * ```
+ */
+// Simplified factory function for body validation middleware
 const bodyValidatorMiddleware = (schema) => ({
     before: async (context) => {
         context.req.parsedBody = await validateBody(schema, context.req.body);