@valentine-efagene/qshelter-common 2.0.61 → 2.0.64

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

@@ -0,0 +1,2 @@
+export * from './policy-evaluator';
+export * from './types';

package/dist/src/auth/index.js

@@ -0,0 +1,2 @@
+export * from './policy-evaluator';
+export * from './types';

package/dist/src/auth/permission-cache.d.ts

@@ -0,0 +1,56 @@
+/**
+ * In-memory permission cache for fast role → scopes resolution
+ *
+ * This module provides caching for role permissions to avoid DynamoDB calls
+ * on every authorization request. The cache is warmed on Lambda cold start
+ * and refreshed based on TTL.
+ *
+ * @example
+ * ```typescript
+ * import { resolveScopes, warmCache } from '@valentine-efagene/qshelter-common';
+ *
+ * // Warm cache on cold start (optional but recommended)
+ * await warmCache();
+ *
+ * // Resolve scopes for user's roles
+ * const scopes = await resolveScopes(['admin', 'customer']);
+ * // Returns: ['contract:*', 'payment:*', 'user:read', ...]
+ * ```
+ */
+/**
+ * Resolve all scopes for a list of roles (deduped)
+ *
+ * @param roles - Array of role IDs/names
+ * @returns Deduplicated array of all scopes from all roles
+ */
+export declare function resolveScopes(roles: string[]): Promise<string[]>;
+/**
+ * Warm the permission cache on cold start
+ * Loads all active roles from DynamoDB into memory
+ *
+ * @returns Promise that resolves when cache is warmed
+ */
+export declare function warmCache(): Promise<void>;
+/**
+ * Check if cache has been warmed
+ */
+export declare function isCacheWarmed(): boolean;
+/**
+ * Invalidate a specific role in the cache
+ * Call this when role permissions are updated
+ *
+ * @param roleId - Role ID to invalidate
+ */
+export declare function invalidateRole(roleId: string): void;
+/**
+ * Clear the entire permission cache
+ * Call this for full refresh or testing
+ */
+export declare function clearCache(): void;
+/**
+ * Get cache statistics for monitoring
+ */
+export declare function getCacheStats(): {
+    size: number;
+    warmed: boolean;
+};

package/dist/src/auth/permission-cache.js

@@ -0,0 +1,268 @@
+/**
+ * In-memory permission cache for fast role → scopes resolution
+ *
+ * This module provides caching for role permissions to avoid DynamoDB calls
+ * on every authorization request. The cache is warmed on Lambda cold start
+ * and refreshed based on TTL.
+ *
+ * @example
+ * ```typescript
+ * import { resolveScopes, warmCache } from '@valentine-efagene/qshelter-common';
+ *
+ * // Warm cache on cold start (optional but recommended)
+ * await warmCache();
+ *
+ * // Resolve scopes for user's roles
+ * const scopes = await resolveScopes(['admin', 'customer']);
+ * // Returns: ['contract:*', 'payment:*', 'user:read', ...]
+ * ```
+ */
+import { DynamoDBClient, GetItemCommand, ScanCommand } from '@aws-sdk/client-dynamodb';
+import { unmarshall } from '@aws-sdk/util-dynamodb';
+/** Cache TTL in milliseconds (5 minutes) */
+const CACHE_TTL_MS = 5 * 60 * 1000;
+/** In-memory LRU cache for role → scopes */
+const cache = new Map();
+/** DynamoDB client (lazy initialized) */
+let dynamoClient = null;
+/** Flag to track if cache has been warmed */
+let cacheWarmed = false;
+/**
+ * Get or create DynamoDB client
+ */
+function getClient() {
+    if (!dynamoClient) {
+        dynamoClient = new DynamoDBClient({
+            region: process.env.AWS_REGION || 'us-east-1',
+            endpoint: process.env.LOCALSTACK_ENDPOINT || undefined,
+        });
+    }
+    return dynamoClient;
+}
+/**
+ * Get the roles table name from environment
+ */
+function getTableName() {
+    return process.env.ROLES_TABLE || process.env.ROLE_POLICIES_TABLE_NAME || 'qshelter-roles';
+}
+/**
+ * Get scopes for a single role (cache-first)
+ *
+ * @param roleId - Role ID or name
+ * @returns Array of scopes for the role
+ */
+async function getRoleScopes(roleId) {
+    const now = Date.now();
+    const cached = cache.get(roleId);
+    // Return cached value if not expired
+    if (cached && cached.expiresAt > now) {
+        return cached.scopes;
+    }
+    try {
+        // Try to fetch from DynamoDB using the existing schema (PK/SK pattern)
+        const result = await getClient().send(new GetItemCommand({
+            TableName: getTableName(),
+            Key: {
+                PK: { S: `ROLE#${roleId}` },
+                SK: { S: 'POLICY' },
+            },
+        }));
+        if (!result.Item) {
+            // Role not found, cache empty scopes
+            cache.set(roleId, { scopes: [], expiresAt: now + CACHE_TTL_MS });
+            return [];
+        }
+        const item = unmarshall(result.Item);
+        // Extract scopes from the policy structure
+        // The existing schema stores policies with statements containing resources
+        // We need to convert this to scopes
+        const scopes = extractScopesFromPolicy(item);
+        // Update cache
+        cache.set(roleId, {
+            scopes,
+            expiresAt: now + CACHE_TTL_MS,
+        });
+        return scopes;
+    }
+    catch (error) {
+        console.error(`[PermissionCache] Error fetching role ${roleId}:`, error);
+        return [];
+    }
+}
+/**
+ * Extract scopes from the existing policy structure
+ *
+ * Converts path-based policies to scope format:
+ * - /contracts/* GET → contract:read
+ * - /contracts/* POST → contract:create
+ * - /contracts/* PUT,PATCH → contract:update
+ * - /contracts/* DELETE → contract:delete
+ * - /* * → * (superuser)
+ */
+function extractScopesFromPolicy(item) {
+    // If the item already has scopes array, use it directly
+    if (item.scopes && Array.isArray(item.scopes)) {
+        return item.scopes;
+    }
+    // Otherwise, check if isActive is false
+    if (item.isActive === false) {
+        return [];
+    }
+    // Convert path-based policy to scopes
+    const scopes = new Set();
+    const policy = item.policy;
+    if (!policy?.statements) {
+        return [];
+    }
+    for (const statement of policy.statements) {
+        if (statement.effect !== 'Allow')
+            continue;
+        for (const resource of statement.resources || []) {
+            const path = resource.path || '';
+            const methods = resource.methods || [];
+            // Extract resource name from path
+            const resourceName = extractResourceName(path);
+            for (const method of methods) {
+                const action = methodToAction(method);
+                if (resourceName === '*' || action === '*') {
+                    scopes.add('*');
+                }
+                else if (resourceName && action) {
+                    scopes.add(`${resourceName}:${action}`);
+                }
+            }
+        }
+    }
+    return Array.from(scopes);
+}
+/**
+ * Extract resource name from path pattern
+ * /contracts/* → contract
+ * /users/:id → user
+ * /* → *
+ */
+function extractResourceName(path) {
+    if (path === '/*' || path === '*') {
+        return '*';
+    }
+    // Remove leading slash and get first segment
+    const segments = path.replace(/^\//, '').split('/');
+    const firstSegment = segments[0] || '';
+    // Singularize common resources
+    const singularMap = {
+        'contracts': 'contract',
+        'users': 'user',
+        'properties': 'property',
+        'payments': 'payment',
+        'tenants': 'tenant',
+        'documents': 'document',
+        'phases': 'phase',
+        'installments': 'installment',
+    };
+    return singularMap[firstSegment] || firstSegment.replace(/s$/, '');
+}
+/**
+ * Convert HTTP method to action
+ * GET → read
+ * POST → create
+ * PUT/PATCH → update
+ * DELETE → delete
+ * * → *
+ */
+function methodToAction(method) {
+    const upper = method.toUpperCase();
+    const methodMap = {
+        'GET': 'read',
+        'POST': 'create',
+        'PUT': 'update',
+        'PATCH': 'update',
+        'DELETE': 'delete',
+        '*': '*',
+    };
+    return methodMap[upper] || 'read';
+}
+/**
+ * Resolve all scopes for a list of roles (deduped)
+ *
+ * @param roles - Array of role IDs/names
+ * @returns Deduplicated array of all scopes from all roles
+ */
+export async function resolveScopes(roles) {
+    if (!roles || roles.length === 0) {
+        return [];
+    }
+    const scopeSets = await Promise.all(roles.map(getRoleScopes));
+    const allScopes = scopeSets.flat();
+    // Dedupe and return
+    return [...new Set(allScopes)];
+}
+/**
+ * Warm the permission cache on cold start
+ * Loads all active roles from DynamoDB into memory
+ *
+ * @returns Promise that resolves when cache is warmed
+ */
+export async function warmCache() {
+    if (cacheWarmed) {
+        return;
+    }
+    try {
+        const result = await getClient().send(new ScanCommand({
+            TableName: getTableName(),
+            FilterExpression: 'SK = :sk',
+            ExpressionAttributeValues: {
+                ':sk': { S: 'POLICY' },
+            },
+        }));
+        const now = Date.now();
+        for (const item of result.Items || []) {
+            const unmarshalled = unmarshall(item);
+            const roleName = unmarshalled.roleName || unmarshalled.PK?.replace('ROLE#', '');
+            if (roleName && unmarshalled.isActive !== false) {
+                const scopes = extractScopesFromPolicy(unmarshalled);
+                cache.set(roleName, {
+                    scopes,
+                    expiresAt: now + CACHE_TTL_MS,
+                });
+            }
+        }
+        cacheWarmed = true;
+        console.log(`[PermissionCache] Cache warmed with ${cache.size} roles`);
+    }
+    catch (error) {
+        console.error('[PermissionCache] Failed to warm cache:', error);
+        // Don't throw - allow fallback to per-request fetching
+    }
+}
+/**
+ * Check if cache has been warmed
+ */
+export function isCacheWarmed() {
+    return cacheWarmed;
+}
+/**
+ * Invalidate a specific role in the cache
+ * Call this when role permissions are updated
+ *
+ * @param roleId - Role ID to invalidate
+ */
+export function invalidateRole(roleId) {
+    cache.delete(roleId);
+}
+/**
+ * Clear the entire permission cache
+ * Call this for full refresh or testing
+ */
+export function clearCache() {
+    cache.clear();
+    cacheWarmed = false;
+}
+/**
+ * Get cache statistics for monitoring
+ */
+export function getCacheStats() {
+    return {
+        size: cache.size,
+        warmed: cacheWarmed,
+    };
+}

package/dist/src/auth/policy-evaluator.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Policy evaluation utilities for scope-based authorization
+ *
+ * Scopes follow a resource:action pattern with wildcard support:
+ * - "contract:read" - specific action on specific resource
+ * - "contract:*" - all actions on contracts
+ * - "*" - superuser access
+ *
+ * @example
+ * ```typescript
+ * import { hasScope, requireScope } from '@valentine-efagene/qshelter-common';
+ *
+ * const scopes = ['contract:read', 'payment:*'];
+ *
+ * hasScope(scopes, 'contract:read');  // true
+ * hasScope(scopes, 'payment:create'); // true (wildcard match)
+ * hasScope(scopes, 'user:read');      // false
+ *
+ * requireScope(scopes, 'contract:read'); // passes
+ * requireScope(scopes, 'user:read');     // throws 403 error
+ * ```
+ */
+/**
+ * Check if scopes array contains the required scope
+ * Supports wildcards: "resource:*" matches "resource:action"
+ *
+ * @param scopes - Array of scopes the principal has
+ * @param required - The scope required for the operation
+ * @returns true if the required scope is present (exact or wildcard match)
+ */
+export declare function hasScope(scopes: string[], required: string): boolean;
+/**
+ * Throws a 403 Forbidden error if the required scope is missing
+ *
+ * @param scopes - Array of scopes the principal has
+ * @param required - The scope required for the operation
+ * @throws AppError with status 403 if scope is missing
+ */
+export declare function requireScope(scopes: string[], required: string): void;
+/**
+ * Check if ALL required scopes are present (AND logic)
+ *
+ * @param scopes - Array of scopes the principal has
+ * @param required - Array of scopes required (all must be present)
+ * @returns true if all required scopes are present
+ */
+export declare function hasAllScopes(scopes: string[], required: string[]): boolean;
+/**
+ * Check if ANY required scope is present (OR logic)
+ *
+ * @param scopes - Array of scopes the principal has
+ * @param required - Array of scopes (any one must be present)
+ * @returns true if at least one required scope is present
+ */
+export declare function hasAnyScope(scopes: string[], required: string[]): boolean;
+/**
+ * Throws a 403 Forbidden error if none of the required scopes are present
+ *
+ * @param scopes - Array of scopes the principal has
+ * @param required - Array of scopes (any one must be present)
+ * @throws AppError with status 403 if no required scope is present
+ */
+export declare function requireAnyScope(scopes: string[], required: string[]): void;
+/**
+ * Throws a 403 Forbidden error if not all required scopes are present
+ *
+ * @param scopes - Array of scopes the principal has
+ * @param required - Array of scopes (all must be present)
+ * @throws AppError with status 403 if any required scope is missing
+ */
+export declare function requireAllScopes(scopes: string[], required: string[]): void;

package/dist/src/auth/policy-evaluator.js

@@ -0,0 +1,107 @@
+/**
+ * Policy evaluation utilities for scope-based authorization
+ *
+ * Scopes follow a resource:action pattern with wildcard support:
+ * - "contract:read" - specific action on specific resource
+ * - "contract:*" - all actions on contracts
+ * - "*" - superuser access
+ *
+ * @example
+ * ```typescript
+ * import { hasScope, requireScope } from '@valentine-efagene/qshelter-common';
+ *
+ * const scopes = ['contract:read', 'payment:*'];
+ *
+ * hasScope(scopes, 'contract:read');  // true
+ * hasScope(scopes, 'payment:create'); // true (wildcard match)
+ * hasScope(scopes, 'user:read');      // false
+ *
+ * requireScope(scopes, 'contract:read'); // passes
+ * requireScope(scopes, 'user:read');     // throws 403 error
+ * ```
+ */
+import { AppError } from '../utils/errors';
+/**
+ * Check if scopes array contains the required scope
+ * Supports wildcards: "resource:*" matches "resource:action"
+ *
+ * @param scopes - Array of scopes the principal has
+ * @param required - The scope required for the operation
+ * @returns true if the required scope is present (exact or wildcard match)
+ */
+export function hasScope(scopes, required) {
+    if (!scopes || scopes.length === 0) {
+        return false;
+    }
+    return scopes.some((s) => {
+        // Superuser wildcard
+        if (s === '*')
+            return true;
+        // Exact match
+        if (s === required)
+            return true;
+        // Wildcard match: "contract:*" matches "contract:read"
+        if (s.endsWith(':*')) {
+            const prefix = s.slice(0, -1); // "contract:"
+            return required.startsWith(prefix);
+        }
+        return false;
+    });
+}
+/**
+ * Throws a 403 Forbidden error if the required scope is missing
+ *
+ * @param scopes - Array of scopes the principal has
+ * @param required - The scope required for the operation
+ * @throws AppError with status 403 if scope is missing
+ */
+export function requireScope(scopes, required) {
+    if (!hasScope(scopes, required)) {
+        throw new AppError(403, `Forbidden: missing required scope '${required}'`);
+    }
+}
+/**
+ * Check if ALL required scopes are present (AND logic)
+ *
+ * @param scopes - Array of scopes the principal has
+ * @param required - Array of scopes required (all must be present)
+ * @returns true if all required scopes are present
+ */
+export function hasAllScopes(scopes, required) {
+    return required.every((r) => hasScope(scopes, r));
+}
+/**
+ * Check if ANY required scope is present (OR logic)
+ *
+ * @param scopes - Array of scopes the principal has
+ * @param required - Array of scopes (any one must be present)
+ * @returns true if at least one required scope is present
+ */
+export function hasAnyScope(scopes, required) {
+    return required.some((r) => hasScope(scopes, r));
+}
+/**
+ * Throws a 403 Forbidden error if none of the required scopes are present
+ *
+ * @param scopes - Array of scopes the principal has
+ * @param required - Array of scopes (any one must be present)
+ * @throws AppError with status 403 if no required scope is present
+ */
+export function requireAnyScope(scopes, required) {
+    if (!hasAnyScope(scopes, required)) {
+        throw new AppError(403, `Forbidden: requires at least one of scopes: ${required.join(', ')}`);
+    }
+}
+/**
+ * Throws a 403 Forbidden error if not all required scopes are present
+ *
+ * @param scopes - Array of scopes the principal has
+ * @param required - Array of scopes (all must be present)
+ * @throws AppError with status 403 if any required scope is missing
+ */
+export function requireAllScopes(scopes, required) {
+    if (!hasAllScopes(scopes, required)) {
+        const missing = required.filter((r) => !hasScope(scopes, r));
+        throw new AppError(403, `Forbidden: missing required scopes: ${missing.join(', ')}`);
+    }
+}

package/dist/src/auth/types.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Auth types for JWT payloads and authorization context
+ */
+export interface JwtPayload {
+    /** User ID or API Key ID */
+    sub: string;
+    /** User email (for user principals) */
+    email?: string;
+    /** Tenant ID for multi-tenancy */
+    tenantId: string;
+    /** Type of principal: user or apiKey */
+    principalType: 'user' | 'apiKey';
+    /** Role IDs/names (resolved to scopes via cache) */
+    roles: string[];
+    /** Issued at timestamp */
+    iat: number;
+    /** Expiration timestamp */
+    exp: number;
+}
+/**
+ * Authorization context passed to downstream services via API Gateway
+ * All values must be strings for API Gateway context
+ *
+ * @deprecated Use AuthContext from middleware/auth-context.ts for Express services
+ */
+export interface AuthorizerResultContext {
+    /** User ID or API Key ID */
+    principalId: string;
+    /** Tenant ID */
+    tenantId: string;
+    /** Type of principal: user or apiKey */
+    principalType: 'user' | 'apiKey';
+    /** JSON stringified array of role names */
+    roles: string;
+    /** JSON stringified array of resolved scopes */
+    scopes: string;
+    /** User email (optional) */
+    email?: string;
+}
+/**
+ * Parsed auth context with scopes (after JSON parsing)
+ */
+export interface ParsedAuthContextWithScopes {
+    principalId: string;
+    tenantId: string;
+    principalType: 'user' | 'apiKey';
+    roles: string[];
+    scopes: string[];
+    email?: string;
+}
+/**
+ * Role definition stored in DynamoDB
+ */
+export interface RoleDefinition {
+    /** Role ID (partition key) */
+    id: string;
+    /** Human-readable role name */
+    name: string;
+    /** Description of the role */
+    description?: string;
+    /** Scopes granted by this role */
+    scopes: string[];
+    /** Whether the role is active */
+    isActive: boolean;
+    /** Tenant ID (null for global roles) */
+    tenantId?: string;
+    /** Last updated timestamp */
+    updatedAt: string;
+}

package/dist/src/auth/types.js

@@ -0,0 +1,4 @@
+/**
+ * Auth types for JWT payloads and authorization context
+ */
+export {};

package/dist/src/index.d.ts

@@ -8,3 +8,4 @@ export * from './prisma/user';
 export * from './prisma/tenant';
 export * from './middleware';
 export * from './events';
+export * from './auth';

package/dist/src/index.js

@@ -8,3 +8,4 @@ export * from './prisma/user';
 export * from './prisma/tenant';
 export * from './middleware';
 export * from './events';
+export * from './auth';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valentine-efagene/qshelter-common",
-  "version": "2.0.61",
+  "version": "2.0.64",
   "description": "Shared database schemas and utilities for QShelter services",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -28,9 +28,11 @@
     "prisma"
   ],
   "dependencies": {
+    "@aws-sdk/client-dynamodb": "^3.962.0",
     "@aws-sdk/client-secrets-manager": "^3.500.0",
     "@aws-sdk/client-sns": "^3.500.0",
     "@aws-sdk/client-ssm": "^3.500.0",
+    "@aws-sdk/util-dynamodb": "^3.962.0",
     "@prisma/client": "^7.0.0",
     "dotenv": "^17.2.3",
     "prisma": "^7.0.0"

package/prisma/migrations/20260105130633_add_api_keys/migration.sql

@@ -0,0 +1,26 @@
+-- CreateTable
+CREATE TABLE `api_keys` (
+    `id` VARCHAR(191) NOT NULL,
+    `tenantId` VARCHAR(191) NOT NULL,
+    `name` VARCHAR(191) NOT NULL,
+    `description` TEXT NULL,
+    `provider` VARCHAR(191) NOT NULL,
+    `secretRef` VARCHAR(191) NOT NULL,
+    `scopes` JSON NOT NULL,
+    `enabled` BOOLEAN NOT NULL DEFAULT true,
+    `expiresAt` DATETIME(3) NULL,
+    `lastUsedAt` DATETIME(3) NULL,
+    `revokedAt` DATETIME(3) NULL,
+    `revokedBy` VARCHAR(191) NULL,
+    `createdBy` VARCHAR(191) NULL,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `updatedAt` DATETIME(3) NOT NULL,
+
+    INDEX `api_keys_tenantId_idx`(`tenantId`),
+    INDEX `api_keys_provider_idx`(`provider`),
+    INDEX `api_keys_enabled_idx`(`enabled`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- AddForeignKey
+ALTER TABLE `api_keys` ADD CONSTRAINT `api_keys_tenantId_fkey` FOREIGN KEY (`tenantId`) REFERENCES `tenants`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;

package/prisma/schema.prisma

@@ -321,10 +321,67 @@ model Tenant {
   documentTemplates DocumentTemplate[]
   offerLetters      OfferLetter[]
 
+  // API keys for third-party integrations
+  apiKeys ApiKey[]
+
   @@index([subdomain])
   @@map("tenants")
 }
 
+// =============================================================================
+// API KEYS - Third-party integration credentials
+// =============================================================================
+// ApiKey enables partners/integrations to authenticate via token exchange.
+// 
+// Flow:
+// 1. Admin creates API key for a partner (POST /api-keys)
+// 2. System generates secret, stores in Secrets Manager, returns id.secret ONCE
+// 3. Partner calls token endpoint with id.secret (POST /api-keys/:id/token)
+// 4. Token endpoint validates via Secrets Manager, returns short-lived JWT
+// 5. Partner uses JWT for API requests; authorizer validates + resolves scopes
+//
+// Security:
+// - Raw secret stored ONLY in AWS Secrets Manager (secretRef = ARN)
+// - Secret returned only once at creation; admin must rotate if lost
+// - Scopes define allowed operations (e.g., ["contract:read", "payment:read"])
+// - Short-lived JWTs (5-15 min) minimize exposure on key compromise
+// =============================================================================
+
+model ApiKey {
+  id          String    @id @default(cuid())
+  tenantId    String
+  tenant      Tenant    @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+
+  // Identification
+  name        String                // Human-readable name (e.g., "Paystack Integration")
+  description String?   @db.Text    // Optional description
+  provider    String                // Partner/vendor name (e.g., "paystack", "flutterwave")
+
+  // Secret management (NEVER store raw secret in DB)
+  secretRef   String                // AWS Secrets Manager ARN or name
+
+  // Permissions - scopes this API key is allowed to request
+  // Examples: ["contract:read", "payment:*", "property:read"]
+  scopes      Json                  // JSON array of scope strings
+
+  // Lifecycle
+  enabled     Boolean   @default(true)
+  expiresAt   DateTime?             // Optional expiration date
+  lastUsedAt  DateTime?             // Updated on each token exchange
+  revokedAt   DateTime?             // Set when key is revoked
+  revokedBy   String?               // User ID who revoked
+
+  // Audit
+  createdBy   String?               // User ID who created
+  createdAt   DateTime  @default(now())
+  updatedAt   DateTime  @updatedAt
+
+  @@index([tenantId])
+  @@index([provider])
+  @@index([enabled])
+  @@map("api_keys")
+}
+
 model RefreshToken {
   id        String   @id @default(cuid())
   // Use the JWT `jti` for indexed lookups and keep the raw JWT (optional)