@valentine-efagene/qshelter-common 2.0.60 → 2.0.63

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

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

package/dist/src/auth/index.js

@@ -0,0 +1,3 @@
+export * from './permission-cache';
+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/dist/src/prisma/tenant.js

@@ -1,42 +1,47 @@
 /**
- * Models that require tenant scoping.
+ * INVERTED APPROACH: All models are tenant-scoped by default.
+ * Only list models that are explicitly GLOBAL (no tenant scoping).
  *
- * IMPORTANT: When adding a new model with tenantId to the schema,
- * add it to this list so queries are automatically filtered by tenant.
- *
- * Models with nullable tenantId (for global templates) should also be
- * added to OPTIONAL_TENANT_MODELS below.
+ * This reduces the risk of accidentally omitting a new model from tenant scoping.
+ */
+/**
+ * Models that are intentionally GLOBAL and should NOT be tenant-scoped.
+ * These models either:
+ * - Don't have a tenantId field (system tables)
+ * - Have optional tenantId but are designed to work across tenants (User)
  */
-const TENANT_SCOPED_MODELS = [
-    // Property domain
-    "property",
-    "propertyPaymentMethod",
-    // Payment plan domain
-    "paymentPlan",
-    // Contract domain
-    "contract",
-    "contractTermination",
-    // Document domain
-    "documentTemplate",
-    "offerLetter",
-    "documentRequirementRule",
-    // Prequalification & underwriting domain
-    "prequalification",
-    "underwritingDecision",
-    // Payment method changes
-    "paymentMethodChangeRequest",
+const GLOBAL_MODELS = [
+    // User can exist across tenants or without a tenant
+    "user",
+    // System/infrastructure tables without tenantId
+    "tenant",
+    "role",
+    "permission",
+    "rolePermission",
+    "userRole",
+    "refreshToken",
+    "passwordReset",
+    "wallet",
+    "domainEvent",
 ];
 /**
- * Models that can optionally have tenant scoping (nullable tenantId)
- * PaymentPlan has nullable tenantId for global templates
+ * Models that have OPTIONAL tenant scoping (nullable tenantId).
+ * These can be global templates (tenantId = null) or tenant-specific.
+ * Queries will return both global AND tenant-specific records.
  */
 const OPTIONAL_TENANT_MODELS = ["paymentPlan"];
-function isTenantScopedModel(model) {
-    return TENANT_SCOPED_MODELS.includes(model);
+function isGlobalModel(model) {
+    return GLOBAL_MODELS.includes(model);
 }
 function isOptionalTenantModel(model) {
     return OPTIONAL_TENANT_MODELS.includes(model);
 }
+/**
+ * A model is tenant-scoped by default unless explicitly listed as global.
+ */
+function isTenantScopedModel(model) {
+    return !isGlobalModel(model);
+}
 /**
  * Creates a tenant-scoped Prisma client that automatically:
  * 1. Filters all queries on tenant-scoped models by tenantId

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valentine-efagene/qshelter-common",
-  "version": "2.0.60",
+  "version": "2.0.63",
   "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"