@mettlecast/domain-runtime 0.2.59 → 0.2.60

package/dist/runtime/action-executor.js

@@ -0,0 +1,408 @@
+/**
+ * Shared action executor.
+ *
+ * Wave 2 of #4619 — used by both API-exposed actions and internal action
+ * invocations. Centralises the validation, auth/tenant checks, idempotency,
+ * audit, handler execution, output validation, and DB cleanup steps so the
+ * downstream API and internal adapters can stay thin and uniform.
+ *
+ * This module does NOT format HTTP responses — transport-specific adapters
+ * own response shaping. The executor returns parsed output (or throws a
+ * `TibError`) and is responsible only for the in-process pipeline.
+ */
+import { ZodError } from 'zod';
+import { TibError } from './error-formatter.js';
+import { extractObservabilityBindings } from './observability-bindings.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// backendAccess helper
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Resolve whether a given caller domain may invoke an action based on its
+ * declared `backendAccess` scope and optional `allowedCallers` allowlist.
+ *
+ * Rules:
+ * - `allowedCallers` (if non-empty) takes precedence: callerDomain MUST be
+ *   in the list regardless of `backendAccess`. Used to narrow broad
+ *   platform-scoped primitives for sensitive handlers (issue #4662,
+ *   Task A hardening).
+ * - `'private'`  — only the defining domain may call it. When
+ *                  `definingDomain` is missing we fail CLOSED (deny) —
+ *                  the in-process proxy must always pass defining-domain
+ *                  metadata now that Wave 7 Task 7.1 has plumbed it
+ *                  through `createActionsProxy` / `invokeInProcess`.
+ * - `'domain'`   — any caller whose domain is non-platform is allowed (the
+ *                  callerDomain is just recorded for audit; the policy here
+ *                  is "callable by other domains").
+ * - `'platform'` — reserved for platform-level services. We currently allow
+ *                  any non-undefined callerDomain through; finer-grained
+ *                  allowlists are out of scope for Wave 2 and will be wired
+ *                  in once the action registry exposes the defining domain.
+ */
+export function isCallerAllowed(opts) {
+    const { action, callerDomain, definingDomain } = opts;
+    if (callerDomain === undefined) {
+        // Defensive: refuse calls that arrive without a caller identity. Internal
+        // adapters always populate this; this guard catches programmer errors.
+        return false;
+    }
+    // Narrow allowlist (issue #4662). When `allowedCallers` is non-empty,
+    // membership in the list is required regardless of `backendAccess`.
+    // An empty/undefined list falls through to the backendAccess policy.
+    const allowlist = action.allowedCallers;
+    if (Array.isArray(allowlist) && allowlist.length > 0) {
+        return allowlist.includes(callerDomain);
+    }
+    switch (action.backendAccess) {
+        case 'private':
+            // Only the defining domain may call. When the defining domain is
+            // unknown we fail closed — previously this was permissive ("treat
+            // as allowed") but that let cross-domain in-process calls bypass
+            // the privacy gate when adapters hadn't yet plumbed metadata. The
+            // in-process path in `actions.ts` now always supplies `definingDomain`
+            // so well-behaved adapters are unaffected; only the unguarded
+            // fallback returns false.
+            if (!definingDomain)
+                return false;
+            return callerDomain === definingDomain;
+        case 'domain':
+            // Any domain in the workspace may invoke. callerDomain is present
+            // and non-platform — accept.
+            return true;
+        case 'platform':
+            // Platform scope is reserved; for Wave 2 we accept any callerDomain.
+            return true;
+        default: {
+            // Exhaustiveness guard — should never run.
+            const _exhaustive = action.backendAccess;
+            void _exhaustive;
+            return false;
+        }
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Pipeline helpers (exported so individual tests can pin behaviour)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Throws `TibError` when `condition` is falsy. Used to enforce preconditions
+ * before any handler work begins; the resulting error carries a stable `code`
+ * so adapters can map it to the appropriate HTTP status without parsing
+ * the message.
+ */
+export function assertOrThrow(condition, message, code) {
+    if (!condition) {
+        throw new TibError(message, code);
+    }
+}
+/**
+ * Lightweight tenant scoping check. Centralised so the API and internal
+ * adapters share the same wording and codes.
+ *
+ * - `ctx.tenant.id` must be a non-empty string other than `'unknown'`.
+ * - When `expectedTenantId` is provided (path or caller claim), it must
+ *   match `ctx.tenant.id`.
+ */
+export function ensureTenantMatches(ctx, expectedTenantId) {
+    assertOrThrow(typeof ctx.tenant.id === 'string' && ctx.tenant.id.length > 0 && ctx.tenant.id !== 'unknown', 'Tenant context required', 'TENANT_REQUIRED');
+    if (expectedTenantId !== undefined && expectedTenantId !== ctx.tenant.id) {
+        throw new TibError('Tenant mismatch', 'TENANT_MISMATCH');
+    }
+}
+/**
+ * Check role claims against an action's required role list. Only meaningful
+ * when `auth === 'required'` AND `tenancy === 'system'`.
+ *
+ * Returns `true` when `requiredRoles` is empty/undefined (no narrowing).
+ */
+export function actorHasRequiredRoles(actorRoles, requiredRoles) {
+    if (!requiredRoles || requiredRoles.length === 0)
+        return true;
+    if (!actorRoles || actorRoles.length === 0)
+        return false;
+    return requiredRoles.some(role => actorRoles.includes(role));
+}
+/**
+ * Run an action through the shared pipeline.
+ *
+ * Pipeline:
+ *   1. Validate input with `action.input.parse(input)`.
+ *   2. Enforce auth/tenancy preconditions based on `source`.
+ *   3. Enforce `backendAccess` for internal calls.
+ *   4. Check `ctx.idempotency` when `action.idempotent` is true.
+ *   5. Invoke `action.handler(parsedInput, ctx)`.
+ *   6. Validate output with `action.output.parse(result)`.
+ *   7. Mark idempotency after successful handler execution.
+ *   8. Audit-log the invocation.
+ *   9. Release `ctx.db` (only if ownership flag is set).
+ *
+ * The executor does NOT throw for application-level failures — it returns
+ * a `TibError`-bearing `ExecuteActionResult` so the caller can render it
+ * consistently. Truly unexpected throws propagate to the caller.
+ */
+export async function executeAction(action, input, ctx, source, meta = {}) {
+    const traceId = meta.traceId ?? 'unknown';
+    // Issue #4662 Task D — bind a child logger to the canonical
+    // observability fields (tenantId, orgId, actorSub, actionId,
+    // callerDomain, traceId) so every pipeline step in this function
+    // emits structured logs that CloudWatch Logs Insights can filter
+    // without re-deriving the identity from each log line. Falls back
+    // to the raw logger when `child` is missing or returns nothing
+    // (test doubles occasionally stub `child` with `vi.fn()` which
+    // returns `undefined`).
+    const baseLog = ctx.logger;
+    const bindings = extractObservabilityBindings(ctx, {
+        traceId,
+        definingDomain: meta.definingDomain,
+        envelope: source.type === 'internal'
+            ? { callerDomain: source.callerDomain, actionId: action.id }
+            : { actionId: action.id },
+    });
+    let log = baseLog;
+    if (typeof baseLog.child === 'function') {
+        const child = baseLog.child(bindings);
+        if (child && typeof child.debug === 'function') {
+            log = child;
+        }
+    }
+    // ── 1. Validate input ────────────────────────────────────────────────────
+    let parsedInput;
+    try {
+        parsedInput = action.input.parse(input);
+    }
+    catch (err) {
+        log.warn('Action input validation failed', {
+            actionId: action.id,
+            code: 'VALIDATION_ERROR',
+            traceId,
+        });
+        return { ok: false, error: err instanceof ZodError ? err : new TibError('Invalid input', 'VALIDATION_ERROR'), code: 'VALIDATION_ERROR' };
+    }
+    // ── 2. Auth/tenancy preconditions (API source) ───────────────────────────
+    if (source.type === 'api') {
+        const exposure = action.exposure;
+        if (exposure.type !== 'api') {
+            // An action invoked via API source must be API-exposed. Internal-only
+            // actions should never be reachable through API routes.
+            log.warn('Internal action reached through API source', {
+                actionId: action.id,
+                code: 'INTERNAL_ACTION_NOT_EXPOSABLE',
+                traceId,
+            });
+            return { ok: false, error: new TibError('Action not exposed', 'NOT_EXPOSED'), code: 'NOT_EXPOSED' };
+        }
+        if (exposure.auth === 'required') {
+            try {
+                assertOrThrow(typeof ctx.actor.sub === 'string' && ctx.actor.sub.length > 0, 'Authenticated actor required', 'AUTH_REQUIRED');
+            }
+            catch (err) {
+                const tibErr = err instanceof TibError ? err : new TibError('Auth check failed', 'AUTH_REQUIRED');
+                log.warn(tibErr.message, { actionId: action.id, code: tibErr.code, traceId });
+                return { ok: false, error: tibErr, code: tibErr.code };
+            }
+        }
+        if (exposure.tenancy === 'required') {
+            try {
+                ensureTenantMatches(ctx, source.pathTenantId);
+            }
+            catch (err) {
+                const tibErr = err instanceof TibError ? err : new TibError('Tenant check failed', 'TENANT_REQUIRED');
+                log.warn(tibErr.message, { actionId: action.id, code: tibErr.code, traceId });
+                return { ok: false, error: tibErr, code: tibErr.code };
+            }
+        }
+        else if (exposure.tenancy === 'system') {
+            // System tenancy: require an actor and (when configured) roles.
+            try {
+                assertOrThrow(typeof ctx.actor.sub === 'string' && ctx.actor.sub.length > 0, 'Authenticated actor required', 'AUTH_REQUIRED');
+                if (exposure.roles && exposure.roles.length > 0) {
+                    assertOrThrow(actorHasRequiredRoles(source.actorRoles, exposure.roles), `Required role missing: ${exposure.roles.join(',')}`, 'FORBIDDEN');
+                }
+            }
+            catch (err) {
+                const tibErr = err instanceof TibError ? err : new TibError('Auth check failed', 'AUTH_REQUIRED');
+                log.warn(tibErr.message, { actionId: action.id, code: tibErr.code, traceId });
+                return { ok: false, error: tibErr, code: tibErr.code };
+            }
+        }
+    }
+    else {
+        // ── 3. backendAccess enforcement (internal source) ──────────────────────
+        if (!isCallerAllowed({ action, callerDomain: source.callerDomain, definingDomain: meta.definingDomain })) {
+            log.warn('Internal caller denied by backendAccess', {
+                actionId: action.id,
+                callerDomain: source.callerDomain,
+                backendAccess: action.backendAccess,
+                code: 'FORBIDDEN',
+                traceId,
+            });
+            return { ok: false, error: new TibError('Caller not permitted', 'FORBIDDEN'), code: 'FORBIDDEN' };
+        }
+        // Tenant scoping for internal calls — non-internal exposures still
+        // require a tenant. Pure internal actions may legitimately run with
+        // 'unknown' tenants (e.g. system jobs), so we only enforce when the
+        // action declares any tenancy posture that demands it.
+        if (action.exposure.type === 'api' && action.exposure.tenancy === 'required') {
+            try {
+                ensureTenantMatches(ctx, source.callerTenantId);
+            }
+            catch (err) {
+                const tibErr = err instanceof TibError ? err : new TibError('Tenant check failed', 'TENANT_REQUIRED');
+                log.warn(tibErr.message, { actionId: action.id, code: tibErr.code, traceId });
+                return { ok: false, error: tibErr, code: tibErr.code };
+            }
+        }
+    }
+    // ── 4. Idempotency check (when configured) ───────────────────────────────
+    let replayed = false;
+    if (action.idempotent) {
+        try {
+            if (await ctx.idempotency.isProcessed()) {
+                replayed = true;
+                log.info('Action idempotent replay short-circuit', {
+                    actionId: action.id,
+                    idempotencyKey: ctx.idempotency.key,
+                    traceId,
+                });
+                // We don't have the cached output value here — adapters can look it
+                // up via ctx.cache if they need to. For Wave 2 we just signal
+                // `replayed: true` and skip re-execution.
+                return { ok: true, value: undefined, replayed: true };
+            }
+        }
+        catch (err) {
+            log.warn('Idempotency check failed; proceeding without dedupe', {
+                actionId: action.id,
+                err: err instanceof Error ? err.message : String(err),
+                traceId,
+            });
+        }
+    }
+    // ── 5. Run the handler ───────────────────────────────────────────────────
+    let result;
+    let handlerRejected;
+    const handlerStart = Date.now();
+    try {
+        result = await action.handler(parsedInput, ctx);
+    }
+    catch (err) {
+        // Domain-meaningful errors (TibError) carry a stable code that adapters
+        // map to an HTTP status. Returning them as `ok: false` lets the adapter
+        // render the correct status without the executor reaching for message
+        // parsing. Non-TibError throws are unexpected and propagate so callers
+        // (adapters, tests) can distinguish "domain rejected" from "executor
+        // rejected" — preserves the Wave 7 Task 7.2 contract that handler
+        // regressions still surface loudly.
+        if (err instanceof TibError) {
+            handlerRejected = err;
+            log.warn('Action handler rejected with TibError', {
+                actionId: action.id,
+                code: err.code,
+                traceId,
+            });
+        }
+        else {
+            log.error('Action handler threw', {
+                actionId: action.id,
+                err: err instanceof Error ? err.message : String(err),
+                traceId,
+            });
+            throw err;
+        }
+    }
+    finally {
+        log.debug('Action handler completed', {
+            actionId: action.id,
+            durationMs: Date.now() - handlerStart,
+            traceId,
+        });
+    }
+    if (handlerRejected) {
+        return { ok: false, error: handlerRejected, code: handlerRejected.code };
+    }
+    // ── 6. Validate output ───────────────────────────────────────────────────
+    let parsedOutput;
+    try {
+        parsedOutput = action.output.parse(result);
+    }
+    catch (err) {
+        log.error('Action output validation failed', {
+            actionId: action.id,
+            traceId,
+        });
+        return {
+            ok: false,
+            error: err instanceof ZodError ? err : new TibError('Output validation failed', 'OUTPUT_VALIDATION_ERROR'),
+            code: 'OUTPUT_VALIDATION_ERROR',
+        };
+    }
+    // ── 7. Mark idempotency after successful execution ───────────────────────
+    if (action.idempotent && !replayed) {
+        try {
+            await ctx.idempotency.markProcessed();
+        }
+        catch (err) {
+            log.warn('Idempotency markProcessed failed', {
+                actionId: action.id,
+                err: err instanceof Error ? err.message : String(err),
+                traceId,
+            });
+        }
+    }
+    // ── 8. Audit-log the invocation (best-effort) ────────────────────────────
+    try {
+        await ctx.audit.log(action.id, `${source.type === 'api' ? source.pathTenantId ?? ctx.tenant.id : ctx.tenant.id}`, {
+            backendAccess: action.backendAccess,
+            exposureType: action.exposure.type,
+            sourceType: source.type,
+            replayed,
+        });
+    }
+    catch (err) {
+        // Audit failures should never block a successful invocation — log and
+        // continue.
+        log.warn('Audit log failed', {
+            actionId: action.id,
+            err: err instanceof Error ? err.message : String(err),
+            traceId,
+        });
+    }
+    return { ok: true, value: parsedOutput, replayed };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// DB lifecycle helper
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Release the DB client associated with `ctx`. Safe to call multiple times —
+ * each `DbContext.release()` implementation is idempotent (see `createDb`).
+ *
+ * The executor does NOT auto-release by default because most adapters
+ * (api-handler, action-handler) already own the DB lifecycle for the
+ * surrounding request scope. Use `withActionExecution` when the executor
+ * is the top-level owner of the request (e.g. standalone scripts, tests,
+ * or any future one-shot action runner).
+ */
+export async function releaseDbSafely(ctx) {
+    try {
+        await ctx.db.release();
+    }
+    catch {
+        // Swallow — adapters already log release failures at their boundary.
+    }
+}
+/**
+ * Wrap `executeAction` so the caller can opt the executor into owning the
+ * DB lifecycle. When `ownDbLifecycle: true` the executor runs `ctx.db.release()`
+ * in a `finally` block. Existing adapters (api-handler, action-handler)
+ * continue to own the DB themselves and should call `executeAction` directly
+ * — there is no double-release because the existing `createDb`/`createMockDb`
+ * release paths are themselves idempotent.
+ */
+export async function withActionExecution(action, input, ctx, source, meta = {}, options = {}) {
+    try {
+        return await executeAction(action, input, ctx, source, meta);
+    }
+    finally {
+        if (options.ownDbLifecycle) {
+            await releaseDbSafely(ctx);
+        }
+    }
+}

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

@@ -1,23 +1,127 @@
 import type { Handler } from 'aws-lambda';
 import type { ActionRegistry } from './actions.js';
+import type { ActionDefinition } from '../primitives/action.js';
+/**
+ * Actor payload carried inside an {@link ActionInvocationEnvelope}.
+ *
+ * Mirrors {@link import('../types/tenant.js').Actor} but is a wire-format
+ * type — callers serialise it as JSON when crossing the Lambda invoke
+ * boundary, so the envelope must remain stable across runtime versions.
+ *
+ * Added in Wave 3 of #4619 to replace the legacy flat `actorId: string`
+ * field. New callers populate the structured form; old callers still
+ * work because the legacy field is honoured as a fallback.
+ */
+export interface ActionActorEnvelope {
+    /** Actor classification (mirrors `Actor.type`). */
+    type: 'user' | 'system' | 'action' | 'schedule' | 'webhook';
+    /** Subject identifier (JWT `sub` claim or system ID). */
+    sub?: string;
+    /** Email address for user actors. */
+    email?: string;
+    /** Role claims attached to the actor. */
+    roles?: string[];
+    /** OAuth/Cognito scope claims. */
+    scopes?: string[];
+}
+/**
+ * Structured envelope propagated across the cross-domain action boundary.
+ *
+ * Added in Wave 3 of #4619. Producers (`createActionsProxy`) emit this
+ * shape for every Lambda-backed cross-domain call. Consumers
+ * (`createActionLambdaHandler`) hydrate `ctx` from it and route through
+ * `executeAction` when a full `ActionDefinition` is available.
+ *
+ * Migration note — the previous envelope carried a flat `actorId: string`
+ * field. That field is still parsed as a fallback when `actor.sub` is not
+ * present so in-flight invocations from older callers don't drop context
+ * during the upgrade window. New code MUST emit the structured `actor`
+ * block; `actorId` is deprecated and will be removed in a later wave.
+ */
 export interface ActionInvocationEnvelope {
     input: unknown;
     envelope: {
+        /** Tenant ID under which the action is being invoked. */
         tenantId: string;
+        /** Organisation ID from the caller's JWT (optional). */
         orgId?: string;
-        actorId: string;
-        traceId: string;
+        /** Caller identity (subject, email, roles, scopes). */
+        actor: ActionActorEnvelope;
+        /** Domain ID of the caller (used by `executeAction` for backendAccess). */
         callerDomain: string;
+        /** Target domain being invoked. Optional — derived from the ARN when omitted. */
+        targetDomain?: string;
+        /** Action ID being invoked within the target domain. */
         actionId: string;
+        /** Distributed trace ID propagated for observability. */
+        traceId: string;
+        /** Per-invocation request ID (correlates with the caller's Lambda log). */
+        requestId?: string;
+        /**
+         * @deprecated Legacy flat identifier — use `actor.sub` instead. Kept so
+         * older emitters don't drop caller identity mid-migration. When both
+         * are present the structured `actor` block wins.
+         */
+        actorId?: string;
     };
 }
 /**
- * Creates the Lambda handler for an action-class Lambda.
- * Receives cross-domain invocations via Lambda invoke and runs the action handler.
+ * Options for {@link createActionLambdaHandler}.
  */
-export declare function createActionLambdaHandler(registry: ActionRegistry, options: {
+export interface CreateActionHandlerOptions {
+    /** Domain ID that owns this handler. Used as the `definingDomain` for backendAccess checks. */
     domainId: string;
+    /** EventBridge event bus name (optional, used by the publisher). */
     eventBusName?: string;
+    /** Database connection string (optional, used by `createDb`). */
     databaseUrl?: string;
+    /** DynamoDB table name for idempotency (optional). */
     idempotencyTableName?: string;
-}): Handler<ActionInvocationEnvelope, unknown>;
+}
+/**
+ * Creates the Lambda handler for an action-class Lambda.
+ *
+ * Receives cross-domain invocations via Lambda invoke and routes the
+ * action through the shared `executeAction` pipeline so the full set of
+ * checks (input validation, auth/tenancy, backendAccess, idempotency,
+ * audit, output validation) applies uniformly with API-exposed actions.
+ *
+ * Behaviour:
+ * - Hydrates `ctx` from the structured envelope (`actor` block takes
+ *   precedence over the legacy `actorId` fallback).
+ * - Looks up the registered action by `domainId + actionId`.
+ * - If the registered entry is an `ActionDefinition`, runs it through
+ *   `executeAction` with an `InternalActionSource` carrying the caller
+ *   domain. This enables backendAccess enforcement on every cross-domain
+ *   invocation.
+ * - If only the legacy handler-function form is registered, calls it
+ *   directly — preserves migration compatibility for callers that have
+ *   not yet supplied full definitions. The narrow migration-compatible
+ *   path skips the executor pipeline (no Zod validation, no idempotency,
+ *   no audit log) so legacy callers keep working while Wave 3 rolls out.
+ *   New callers should register `ActionDefinition` instances.
+ *
+ * @param registry - Map of `domainId → actionId → ActionDefinition | handler`.
+ * @param options - Domain identification and runtime options.
+ * @returns AWS Lambda handler for the action-class Lambda.
+ */
+export declare function createActionLambdaHandler(registry: ActionRegistry, options: CreateActionHandlerOptions): Handler<ActionInvocationEnvelope, unknown>;
+/**
+ * Shape of an entry inside {@link ActionRegistry}. The runtime supports two
+ * registrations side-by-side during the Wave 3 migration:
+ *
+ * 1. A full `ActionDefinition` (returned by `defineAction(...)`). Preferred —
+ *    routes through `executeAction` so backendAccess, idempotency, audit,
+ *    and output validation all apply.
+ * 2. A bare handler function. Legacy form — kept so callers that have not
+ *    yet migrated continue to work. NOT routed through `executeAction`;
+ *    receives `ctx` directly.
+ *
+ * New code MUST register the `ActionDefinition` form.
+ */
+export type ActionRegistryEntry = ActionDefinition | ActionHandlerFn;
+/**
+ * Function signature for the legacy handler-only registration form.
+ * Mirrors the previous `ActionRegistry` value type for back-compat.
+ */
+export type ActionHandlerFn = (input: unknown, ctx: any) => Promise<unknown>;