@valentine-efagene/qshelter-common 2.0.50 → 2.0.51

package/dist/src/middleware/auth-context.d.ts

@@ -0,0 +1,71 @@
+import { Request, Response, NextFunction } from 'express';
+/**
+ * Authentication context injected by API Gateway Lambda Authorizer.
+ * Services should NEVER trust client-supplied user IDs directly.
+ *
+ * In production:
+ * - API Gateway calls Lambda Authorizer with JWT
+ * - Authorizer validates token and returns context
+ * - Gateway injects context into event.requestContext.authorizer
+ * - serverless-http makes this available as req.requestContext.authorizer
+ *
+ * In tests:
+ * - We simulate the authorizer by setting x-authorizer-* headers
+ * - These headers are ONLY set by test harness, never by real clients
+ */
+export interface AuthContext {
+    userId: string;
+    tenantId: string;
+    email?: string;
+    roles?: string[];
+}
+/**
+ * Extracts auth context from API Gateway authorizer.
+ *
+ * Priority:
+ * 1. Production: requestContext.authorizer (set by API Gateway)
+ * 2. Test/Dev: x-authorizer-* headers (set by test harness)
+ *
+ * @param req Express request object
+ * @returns AuthContext or null if not authenticated
+ */
+export declare function extractAuthContext(req: Request): AuthContext | null;
+/**
+ * Middleware that requires authenticated context.
+ * Rejects requests without valid authorizer context.
+ *
+ * @example
+ * ```typescript
+ * app.use('/api', requireAuth, apiRouter);
+ * ```
+ */
+export declare function requireAuth(req: Request, res: Response, next: NextFunction): Response<any, Record<string, any>> | undefined;
+/**
+ * Helper to get auth context from request (after requireAuth middleware).
+ * Throws if auth context is missing.
+ *
+ * @example
+ * ```typescript
+ * router.get('/profile', (req, res) => {
+ *     const { userId, tenantId } = getAuthContext(req);
+ *     // ...
+ * });
+ * ```
+ */
+export declare function getAuthContext(req: Request): AuthContext;
+/**
+ * Test helper to generate authorizer headers.
+ * Use this in tests to simulate API Gateway authorizer context.
+ *
+ * @example
+ * ```typescript
+ * const response = await request(app)
+ *     .post('/users')
+ *     .set(authHeaders(userId, tenantId))
+ *     .send({ name: 'John' });
+ * ```
+ */
+export declare function authHeaders(userId: string, tenantId: string, extras?: {
+    email?: string;
+    roles?: string[];
+}): Record<string, string>;

package/dist/src/middleware/auth-context.js

@@ -0,0 +1,100 @@
+/**
+ * Extracts auth context from API Gateway authorizer.
+ *
+ * Priority:
+ * 1. Production: requestContext.authorizer (set by API Gateway)
+ * 2. Test/Dev: x-authorizer-* headers (set by test harness)
+ *
+ * @param req Express request object
+ * @returns AuthContext or null if not authenticated
+ */
+export function extractAuthContext(req) {
+    const lambdaReq = req;
+    // Production: API Gateway Lambda integration populates requestContext
+    const authorizer = lambdaReq.requestContext?.authorizer;
+    if (authorizer?.userId && authorizer?.tenantId) {
+        return {
+            userId: authorizer.userId,
+            tenantId: authorizer.tenantId,
+            email: authorizer.email,
+            roles: authorizer.roles ? JSON.parse(authorizer.roles) : [],
+        };
+    }
+    // Test/Development: Simulated authorizer headers
+    // These headers should only be set by test harness or local dev proxy
+    const userId = req.headers['x-authorizer-user-id'];
+    const tenantId = req.headers['x-authorizer-tenant-id'];
+    if (userId && tenantId) {
+        const rolesHeader = req.headers['x-authorizer-roles'];
+        return {
+            userId,
+            tenantId,
+            email: req.headers['x-authorizer-email'],
+            roles: rolesHeader ? JSON.parse(rolesHeader) : [],
+        };
+    }
+    return null;
+}
+/**
+ * Middleware that requires authenticated context.
+ * Rejects requests without valid authorizer context.
+ *
+ * @example
+ * ```typescript
+ * app.use('/api', requireAuth, apiRouter);
+ * ```
+ */
+export function requireAuth(req, res, next) {
+    const auth = extractAuthContext(req);
+    if (!auth) {
+        return res.status(401).json({ error: 'Unauthorized - missing auth context' });
+    }
+    // Attach to request for downstream use
+    req.auth = auth;
+    next();
+}
+/**
+ * Helper to get auth context from request (after requireAuth middleware).
+ * Throws if auth context is missing.
+ *
+ * @example
+ * ```typescript
+ * router.get('/profile', (req, res) => {
+ *     const { userId, tenantId } = getAuthContext(req);
+ *     // ...
+ * });
+ * ```
+ */
+export function getAuthContext(req) {
+    const lambdaReq = req;
+    // First check if middleware attached it
+    if (lambdaReq.auth) {
+        return lambdaReq.auth;
+    }
+    // Otherwise try to extract it
+    const auth = extractAuthContext(req);
+    if (!auth) {
+        throw new Error('Auth context not found. Ensure requireAuth middleware is applied or request has valid auth headers.');
+    }
+    return auth;
+}
+/**
+ * Test helper to generate authorizer headers.
+ * Use this in tests to simulate API Gateway authorizer context.
+ *
+ * @example
+ * ```typescript
+ * const response = await request(app)
+ *     .post('/users')
+ *     .set(authHeaders(userId, tenantId))
+ *     .send({ name: 'John' });
+ * ```
+ */
+export function authHeaders(userId, tenantId, extras) {
+    return {
+        'x-authorizer-user-id': userId,
+        'x-authorizer-tenant-id': tenantId,
+        ...(extras?.email && { 'x-authorizer-email': extras.email }),
+        ...(extras?.roles && { 'x-authorizer-roles': JSON.stringify(extras.roles) }),
+    };
+}

package/dist/src/middleware/index.d.ts

@@ -1,3 +1,4 @@
 export * from './error-handler';
 export * from './request-logger';
 export * from './tenant';
+export * from './auth-context';

package/dist/src/middleware/index.js

@@ -1,3 +1,4 @@
 export * from './error-handler';
 export * from './request-logger';
 export * from './tenant';
+export * from './auth-context';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valentine-efagene/qshelter-common",
-  "version": "2.0.50",
+  "version": "2.0.51",
   "description": "Shared database schemas and utilities for QShelter services",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",