@mettlecast/domain-runtime 0.2.59 → 0.2.61

package/dist/schema/rls.js

@@ -9,6 +9,20 @@
  * if a query is made outside a request context — those queries return zero rows
  * instead of throwing.
  *
+ * **Session variable contract.** This policy reads `app.current_tenant`, which
+ * is bound by `createDb` (Wave 5 Task 5.1) via
+ * `SELECT set_config('app.current_tenant', $1, false)` on every per-request
+ * client checkout. The bound value comes from `ctx.tenant.id` (see
+ * `hydrate.ts`). Any domain code that issues raw SQL against a RLS-protected
+ * table therefore relies on the runtime having already bound that variable;
+ * if a query is made before `createDb` finishes binding (or after the client
+ * is released back to the pool), the policy falls back to a zero-row result
+ * because the setting is unset and `current_setting(..., true)` returns NULL.
+ *
+ * For sys-admin / cross-tenant queries, callers must additionally run
+ * `SELECT set_config('app.bypass_rls', 'true', false)` on the same client.
+ * This contract is enforced by `tenantAdminBypassSql` below.
+ *
  * @param opts - Table and tenant column configuration.
  * @returns A multi-statement SQL string suitable for inclusion in a migration.
  */
@@ -25,6 +39,36 @@ export function tenantIsolationSql(opts) {
         `  WITH CHECK (${tenantColumn} = current_setting('app.current_tenant', true)::uuid);`,
     ].join('\n');
 }
+/**
+ * Generate the SQL to add a permissive RLS bypass policy that fires when
+ * `current_setting('app.bypass_rls', true) = 'true'`. Intended to be added
+ * alongside `tenantIsolationSql` for sys-admin / cross-tenant queries that
+ * must read rows belonging to any tenant (for example, the data-management
+ * domain's schema explorer). The runtime sets `app.bypass_rls` via
+ * `SELECT set_config('app.bypass_rls', 'true', false)` on the same per-request
+ * client that hydrates with the sys-admin role.
+ *
+ * The generated policy is idempotent: it only creates the policy if no policy
+ * with the same name already exists.
+ *
+ * @param opts - Table and tenant column configuration (same shape as
+ *   `tenantIsolationSql` so the two helpers compose cleanly).
+ * @returns A multi-statement SQL string suitable for inclusion in a migration.
+ */
+export function tenantAdminBypassSql(opts) {
+    const schema = opts.schema ?? 'public';
+    const policyName = `tenant_admin_bypass_${opts.table}`;
+    const qualified = `"${schema}"."${opts.table}"`;
+    return [
+        `DO $$ BEGIN`,
+        `  IF NOT EXISTS (SELECT 1 FROM pg_policies WHERE policyname = '${policyName}') THEN`,
+        `    CREATE POLICY "${policyName}" ON ${qualified}`,
+        `      AS PERMISSIVE FOR ALL`,
+        `      USING (current_setting('app.bypass_rls', true) = 'true');`,
+        `  END IF;`,
+        `END $$;`,
+    ].join('\n');
+}
 /**
  * Generate the SQL to drop a tenant isolation policy and disable RLS.
  * Useful for down-migrations.

package/dist/types/tenant.d.ts

@@ -8,6 +8,18 @@ export interface Actor {
     email?: string;
     /** Tenant the actor belongs to. */
     tenantId?: string;
+    /**
+     * Role claims attached to the actor (e.g. `['sys_admin']`).
+     * Populated from JWT `cognito:groups` / `custom:roles` claims.
+     * Optional — actors from non-user sources (system, action, schedule)
+     * may not carry roles.
+     */
+    roles?: string[];
+    /**
+     * Scope claims attached to the actor (e.g. Cognito OAuth scopes).
+     * Optional — system/derived actors may not carry scopes.
+     */
+    scopes?: string[];
 }
 /** Tenant record. Always populated; never null in a valid request. */
 export interface Tenant {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mettlecast/domain-runtime",
-  "version": "0.2.59",
+  "version": "0.2.61",
   "type": "module",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/dist/primitives/api.d.ts

@@ -1,44 +0,0 @@
-import type { AuthConfig, RateLimitConfig, TenancyMode, DeploymentConfig, ObservabilityConfig, ApiVersion, OutboundAccess } from '../types/index.js';
-/** Configuration for an API primitive. */
-export interface ApiConfig {
-    /** Machine-readable API identifier (kebab-case). */
-    id: string;
-    /** HTTP route path relative to domain base, e.g. '/users/:id'. */
-    path: string;
-    /** HTTP method. Defaults to ANY. */
-    method?: string;
-    /** Tenancy requirement for this API. */
-    tenancy: TenancyMode;
-    /**
-     * Version map. Keys are version strings (e.g. 'v1', 'v2').
-     * At least one version is required.
-     */
-    versions: Record<string, ApiVersion<any, any>>;
-    /** Authentication configuration. Defaults to jwt. */
-    auth?: AuthConfig;
-    /** Rate limiting configuration. */
-    rateLimit?: RateLimitConfig;
-    /** Deployment overrides. */
-    deployment?: DeploymentConfig;
-    /** Whether this handler may use NAT-backed public internet egress. Defaults to internal. */
-    outboundAccess?: OutboundAccess;
-    /** Observability thresholds. */
-    observability?: ObservabilityConfig;
-    /** Example request/response payloads for documentation (no runtime impact). */
-    examples?: {
-        request?: Record<string, unknown>;
-        response?: Record<string, unknown>;
-    };
-}
-/** Return type of defineApi. */
-export interface ApiDefinition extends ApiConfig {
-    /** Discriminant. */
-    _kind: 'api';
-}
-/**
- * Register an API primitive with versioned handlers.
- * Validates that deprecated versions have a sunset date and that input/output
- * schemas are wrapped with `.default(...)` (the Zod v4 example-data pattern).
- * @throws {ZodError} if config is invalid
- */
-export declare function defineApi(config: ApiConfig): ApiDefinition;

package/dist/primitives/api.js

@@ -1,70 +0,0 @@
-import { z } from 'zod';
-// Native enum objects — Zod v4's recommended pattern over `z.enum([...])`.
-// Each `as const` object becomes the source of truth; `z.nativeEnum(...)`
-// derives the inferred string-literal union from the keys.
-const TenancyModeLiteral = { required: 'required', none: 'none', system: 'system' };
-const VersionStatusLiteral = { preview: 'preview', stable: 'stable', deprecated: 'deprecated', sunset: 'sunset' };
-const AuthTypeLiteral = { jwt: 'jwt', 'api-key': 'api-key', none: 'none' };
-const DeploymentTargetLiteral = { single: 'single', split: 'split' };
-const OutboundAccessLiteral = { internal: 'internal', internet: 'internet' };
-/**
- * Returns true when a Zod schema has been wrapped with `.default(...)` (Zod v4
- * pattern). The wrapped schema exposes a `_def.typeName` of `ZodDefault`.
- * `defineApi` requires every version's `input` and `output` to be wrapped this
- * way so that the runtime has a concrete example payload for documentation and
- * schema-publish tooling.
- */
-const hasDefault = (schema) => {
-    if (typeof schema !== 'object' || schema === null)
-        return false;
-    const def = schema._def;
-    if (!def)
-        return false;
-    if (def.typeName === 'ZodDefault' || def.type === 'default')
-        return true;
-    // Unwrap ZodOptional / ZodNullable — e.g. z.object({}).default({}).optional()
-    if (def.type === 'optional' || def.type === 'nullable') {
-        return hasDefault(schema._def.innerType);
-    }
-    return false;
-};
-const ApiConfigSchema = z.object({
-    id: z.string().min(1),
-    path: z.string().startsWith('/'),
-    method: z.string().optional(),
-    tenancy: z.nativeEnum(TenancyModeLiteral),
-    versions: z.record(z.string(), z.object({
-        status: z.nativeEnum(VersionStatusLiteral),
-        sunset: z.string().optional(),
-        input: z.unknown().refine(hasDefault, { message: 'input schema must have .default()' }),
-        output: z.unknown().refine(hasDefault, { message: 'output schema must have .default()' }),
-        handler: z.function(),
-    }).refine(v => v.status !== VersionStatusLiteral.deprecated || v.sunset !== undefined, {
-        message: 'sunset date is required when status is deprecated',
-    })),
-    auth: z.object({
-        type: z.nativeEnum(AuthTypeLiteral),
-        roles: z.array(z.string()).optional(),
-    }).optional(),
-    rateLimit: z.object({
-        perTenant: z.string().optional(),
-        perApiKey: z.string().optional(),
-        perIp: z.string().optional(),
-    }).optional(),
-    deployment: z.object({ target: z.nativeEnum(DeploymentTargetLiteral) }).passthrough().optional(),
-    outboundAccess: z.nativeEnum(OutboundAccessLiteral).default(OutboundAccessLiteral.internal),
-    observability: z.object({
-        sloP99Ms: z.number().positive().optional(),
-        alertOnErrorRate: z.number().min(0).max(1).optional(),
-    }).optional(),
-}).refine(c => Object.keys(c.versions).length > 0, { message: 'at least one version required' });
-/**
- * Register an API primitive with versioned handlers.
- * Validates that deprecated versions have a sunset date and that input/output
- * schemas are wrapped with `.default(...)` (the Zod v4 example-data pattern).
- * @throws {ZodError} if config is invalid
- */
-export function defineApi(config) {
-    ApiConfigSchema.parse(config);
-    return { ...config, outboundAccess: config.outboundAccess ?? 'internal', _kind: 'api' };
-}

package/dist/runtime/api-handler.d.ts

@@ -1,29 +0,0 @@
-import type { APIGatewayProxyEventV2WithJWTAuthorizer, APIGatewayProxyStructuredResultV2 } from 'aws-lambda';
-import type { ApiDefinition } from '../primitives/api.js';
-/**
- * Options for createApiLambdaHandler.
- */
-export interface CreateApiHandlerOptions {
-    /** Default version when no Accept-Version header. Defaults to highest stable. */
-    defaultVersion?: number;
-}
-/**
- * Wrap an ApiDefinition into an AWS Lambda HTTP API v2 handler with full
- * version negotiation, sunset enforcement, validation, ctx hydration, tenancy
- * guard, and error formatting.
- *
- * The handler performs the following steps in order:
- * 1. Version negotiation from Accept-Version or Accept headers
- * 2. Sunset check and response header decoration
- * 3. Tenancy validation (if required)
- * 4. Input validation via Zod schema
- * 5. Context hydration with actor, tenant, DB, secrets, etc.
- * 6. Handler invocation with typed input and ctx
- * 7. Output validation via Zod schema
- * 8. DB connection release
- *
- * @param api - ApiDefinition with versioned handlers.
- * @param options - Options for version negotiation and defaults.
- * @returns AWS Lambda HTTP API v2 handler function.
- */
-export declare function createApiLambdaHandler(api: ApiDefinition, options?: CreateApiHandlerOptions): (event: APIGatewayProxyEventV2WithJWTAuthorizer) => Promise<APIGatewayProxyStructuredResultV2>;

package/dist/runtime/api-handler.js

@@ -1,212 +0,0 @@
-import { negotiateVersion } from './version-negotiator.js';
-import { checkSunset, applySunsetHeaders } from './sunset-guard.js';
-import { hydrateCtx } from './hydrate.js';
-import { extractActorFromApiGatewayEvent, extractTenantFromApiGatewayEvent } from './extractors.js';
-import { formatError, extractTraceId, TibError } from './error-formatter.js';
-import { createMetrics } from './metrics.js';
-import { checkRateLimit } from './rate-limiter.js';
-/**
- * Wrap an ApiDefinition into an AWS Lambda HTTP API v2 handler with full
- * version negotiation, sunset enforcement, validation, ctx hydration, tenancy
- * guard, and error formatting.
- *
- * The handler performs the following steps in order:
- * 1. Version negotiation from Accept-Version or Accept headers
- * 2. Sunset check and response header decoration
- * 3. Tenancy validation (if required)
- * 4. Input validation via Zod schema
- * 5. Context hydration with actor, tenant, DB, secrets, etc.
- * 6. Handler invocation with typed input and ctx
- * 7. Output validation via Zod schema
- * 8. DB connection release
- *
- * @param api - ApiDefinition with versioned handlers.
- * @param options - Options for version negotiation and defaults.
- * @returns AWS Lambda HTTP API v2 handler function.
- */
-export function createApiLambdaHandler(api, options) {
-    return async (event) => {
-        const responseHeaders = { 'Content-Type': 'application/json' };
-        // G7: Extract W3C traceparent header and propagate as traceId
-        const traceparent = event.headers?.['traceparent'];
-        const traceId = traceparent ?? extractTraceId(event.headers ?? {});
-        // G6: Initialize EMF metrics (TODO: extract domainId from api definition or context)
-        const metrics = createMetrics({
-            domainId: api.id, // TODO: domainId should come from api definition or deployment context
-            endpointId: api.id,
-            primitiveClass: 'api',
-            // tenantId will be added after tenant is extracted
-        });
-        const requestStart = Date.now();
-        metrics.recordColdStart();
-        try {
-            // 1. Version negotiation
-            const versionKeys = Object.keys(api.versions).sort();
-            const stableVersions = versionKeys.filter(k => api.versions[k].status === 'stable');
-            const defaultVersionKey = options?.defaultVersion !== undefined
-                ? `v${options.defaultVersion}`
-                : (stableVersions[stableVersions.length - 1] ?? versionKeys[versionKeys.length - 1] ?? 'v1');
-            const defaultVersionNum = parseInt(defaultVersionKey.replace(/^v/, ''), 10);
-            const negotiation = negotiateVersion(event.headers ?? {}, isNaN(defaultVersionNum) ? 1 : defaultVersionNum);
-            const versionKey = `v${negotiation.requestedVersion}`;
-            const apiVersion = api.versions[versionKey];
-            if (!apiVersion) {
-                // G1: Use standard error envelope for unsupported version
-                return {
-                    statusCode: 406,
-                    headers: responseHeaders,
-                    body: JSON.stringify(formatError(new TibError('Unsupported version', 'UNSUPPORTED_VERSION'), traceId)),
-                };
-            }
-            // 2. Sunset check
-            const lifecycle = {
-                version: negotiation.requestedVersion,
-                status: apiVersion.status,
-                ...(apiVersion.sunset && { sunsetAt: apiVersion.sunset }),
-            };
-            const sunsetResult = checkSunset(lifecycle, new Date());
-            applySunsetHeaders(responseHeaders, sunsetResult);
-            if (sunsetResult.blocked) {
-                // G1: Use standard error envelope
-                return {
-                    statusCode: 410,
-                    headers: responseHeaders,
-                    body: JSON.stringify(formatError(new TibError('Version sunset', 'VERSION_SUNSET'), traceId)),
-                };
-            }
-            // 3. Tenancy guard (before validation, before hydrate — fail fast)
-            const actor = extractActorFromApiGatewayEvent(event);
-            const tenant = extractTenantFromApiGatewayEvent(event);
-            if (api.tenancy === 'required') {
-                if (tenant.id === 'unknown') {
-                    // G1: Use standard error envelope for auth errors
-                    return {
-                        statusCode: 401,
-                        headers: responseHeaders,
-                        body: JSON.stringify(formatError(new TibError('Tenant context required', 'TENANT_REQUIRED'), traceId)),
-                    };
-                }
-                const pathTenantId = event.pathParameters?.tenantId;
-                if (pathTenantId && pathTenantId !== tenant.id) {
-                    // G1: Use standard error envelope for auth errors
-                    return {
-                        statusCode: 403,
-                        headers: responseHeaders,
-                        body: JSON.stringify(formatError(new TibError('Tenant mismatch', 'TENANT_MISMATCH'), traceId)),
-                    };
-                }
-            }
-            // Rate limiting — per-tenant token bucket (in-memory, resets on cold start)
-            if (api.rateLimit?.perTenant) {
-                const tenantId = extractTenantFromApiGatewayEvent(event)?.id ?? 'anonymous';
-                const rateLimitKey = `${api.id}:tenant:${tenantId}`;
-                const allowed = checkRateLimit(rateLimitKey, api.rateLimit.perTenant);
-                if (!allowed) {
-                    return {
-                        statusCode: 429,
-                        headers: { ...responseHeaders, 'Retry-After': '60' },
-                        body: JSON.stringify(formatError(new TibError('Rate limit exceeded', 'RATE_LIMIT_EXCEEDED'), traceId)),
-                    };
-                }
-            }
-            if (api.rateLimit?.perIp) {
-                const sourceIp = event.requestContext?.http?.sourceIp ?? 'unknown';
-                const rateLimitKey = `${api.id}:ip:${sourceIp}`;
-                const allowed = checkRateLimit(rateLimitKey, api.rateLimit.perIp);
-                if (!allowed) {
-                    return {
-                        statusCode: 429,
-                        headers: { ...responseHeaders, 'Retry-After': '60' },
-                        body: JSON.stringify(formatError(new TibError('Rate limit exceeded', 'RATE_LIMIT_EXCEEDED'), traceId)),
-                    };
-                }
-            }
-            // 4. Validate input
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            let parsedInput;
-            try {
-                const rawBody = event.body ? (event.isBase64Encoded ? Buffer.from(event.body, 'base64').toString('utf8') : event.body) : undefined;
-                const inputJson = rawBody ? JSON.parse(rawBody) : undefined;
-                parsedInput = apiVersion.input.parse(inputJson);
-            }
-            catch (err) {
-                // G1: Use standard error envelope for validation errors
-                return {
-                    statusCode: 400,
-                    headers: responseHeaders,
-                    body: JSON.stringify(formatError(err, traceId)),
-                };
-            }
-            // G5: Auto-trigger idempotency check for POST/PUT/PATCH
-            const idempotencyKey = event.headers?.['idempotency-key'] ?? event.headers?.['Idempotency-Key'];
-            const httpMethod = event.requestContext?.http?.method ?? '';
-            // 5. Hydrate context
-            const { tenantId: _tenantId, ...remainingPathParams } = event.pathParameters ?? {};
-            const ctx = await hydrateCtx(event, {
-                actor,
-                tenant,
-                databaseUrl: process.env['DATABASE_URL'],
-                eventBusName: process.env['EVENT_BUS_NAME'],
-                traceId,
-                pathParams: remainingPathParams,
-            });
-            // G5: After hydration, check idempotency cache for POST/PUT/PATCH
-            if (idempotencyKey && ['POST', 'PUT', 'PATCH'].includes(httpMethod)) {
-                const cached = await ctx.idempotency.isProcessed();
-                if (cached) {
-                    // Return cached response — for now return 200 with a replay indicator
-                    return {
-                        statusCode: 200,
-                        headers: { ...responseHeaders, 'Idempotency-Replayed': 'true' },
-                        body: JSON.stringify({ replayed: true, idempotencyKey }),
-                    };
-                }
-            }
-            try {
-                // 6. Call handler
-                const result = await apiVersion.handler(parsedInput, ctx);
-                // 7. Validate output
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                let parsedOutput;
-                try {
-                    parsedOutput = apiVersion.output.parse(result);
-                }
-                catch (err) {
-                    ctx.logger.error('Output validation failed');
-                    // G1: Use standard error envelope for output validation errors
-                    return {
-                        statusCode: 500,
-                        headers: responseHeaders,
-                        body: JSON.stringify(formatError(err, traceId, ctx.logger)),
-                    };
-                }
-                // G5: Mark as processed after successful handler completion
-                if (idempotencyKey && ['POST', 'PUT', 'PATCH'].includes(httpMethod)) {
-                    await ctx.idempotency.markProcessed();
-                }
-                return { statusCode: 200, headers: responseHeaders, body: JSON.stringify(parsedOutput) };
-            }
-            finally {
-                // 8. Always release DB
-                try {
-                    await ctx.db.release();
-                }
-                catch { /* swallow */ }
-                // G6: Record latency and flush metrics
-                metrics.recordLatency(Date.now() - requestStart);
-                metrics.flush();
-            }
-        }
-        catch (err) {
-            // Last-resort error handler
-            // G1: Use standard error envelope for unhandled errors
-            // eslint-disable-next-line no-console
-            console.error('Unhandled handler error', err);
-            return {
-                statusCode: 500,
-                headers: responseHeaders,
-                body: JSON.stringify(formatError(err, traceId)),
-            };
-        }
-    };
-}