@mettlecast/domain-runtime 0.2.59 → 0.2.61

package/README.md

@@ -1,6 +1,8 @@
 # @mettlecast/domain-runtime
 
-Type-safe runtime types, factory functions, and context interface for TIB Domain Module handlers. Zero AWS dependencies in the main export — all infrastructure concerns are delegated to the CDK packer.
+Type-safe runtime types, factory functions, and context interface for TIB
+Domain Module handlers. Zero AWS dependencies in the main export — all
+infrastructure concerns are delegated to the CDK packer.
 
 ## Install
 
@@ -10,14 +12,13 @@ npm install @mettlecast/domain-runtime
 
 ## Quick Start
 
-Define a domain with an API handler:
+Define a domain with a public action handler:
 
 ```typescript
 import {
   defineDomain,
-  defineApi,
-  defineEvent,
-  type DomainContext,
+  defineAction,
+  z,
 } from '@mettlecast/domain-runtime';
 
 const domain = defineDomain({
@@ -25,74 +26,90 @@ const domain = defineDomain({
   version: '1.0.0',
 });
 
-const paymentCreated = defineEvent({
-  name: 'payment.created',
-  schema: {
-    type: 'object',
-    properties: {
-      paymentId: { type: 'string' },
-      amount: { type: 'number' },
-    },
+// Public HTTP endpoint — equivalent of the legacy `defineApi({ tenancy: 'required' })`.
+// The `exposure` block is mandatory: path/method/auth/tenancy are validated at
+// construction time and at registry build, so unsafe configurations never ship.
+export const chargeCard = defineAction({
+  id: 'charge-card',
+  backendAccess: 'domain',
+  exposure: {
+    type: 'api',
+    path: '/v1/tenants/{tenantId}/payments/charge',
+    method: 'POST',
+    auth: 'required',
+    tenancy: 'required',
   },
-});
-
-export const chargeHandler = defineApi({
-  domain,
-  path: '/charge',
-  method: 'POST',
-  handler: async (event, ctx: DomainContext) => {
-    const amount = event.body.amount;
-    
-    // Use context surfaces
+  input: z.object({ amount: z.number().positive() }),
+  output: z.object({ id: z.string().uuid(), status: z.literal('charged') }),
+  idempotent: true,
+  handler: async (input, ctx) => {
     await ctx.db.query('INSERT INTO charges ...');
-    await ctx.publish(paymentCreated, { paymentId: '123', amount });
-    await ctx.cache.set('last_charge', amount);
-    
-    return { statusCode: 200, body: { success: true } };
+    await ctx.publish('payment.charged', { amount: input.amount });
+    return { id: crypto.randomUUID(), status: 'charged' as const };
   },
 });
 ```
 
+The action-first contract (introduced in #4619, hardened in
+`feat/4625-action-auth-hardening`):
+
+| `exposure.type` | Reachable through | Notes |
+|---|---|---|
+| `'api'` | API Gateway route | Path, method, auth, tenancy all required and validated. Generates one method on the consumer SDK. |
+| `'internal'` | `ctx.actions[domainId].<id>(input)` from inside the platform | Never reachable via HTTP. Use for in-process cross-domain calls. |
+
+> **Anti-pattern.** Do NOT use the legacy `defineApi` factory for new
+> public handlers. It is no longer scaffolded for public HTTP endpoints —
+> every public handler must go through `defineAction({ exposure: { type: 'api', ... } })`
+> so the registry can enforce the auth/tenancy contract at build time
+> (see `validate-domain`).
+
 ## Factory Functions
 
-9 factory functions help you define domain primitives with schema validation and type safety:
+Nine factory functions help you define domain primitives with schema
+validation and type safety. The action-first migration (#4619) folded
+`defineApi` into `defineAction` so every primitive is a callable
+`ActionDefinition` regardless of where it is reached from.
 
 | Function | Purpose | Produces |
 |---|---|---|
 | `defineDomain()` | Declare a domain and version | Domain metadata |
-| `defineApi()` | HTTP handler with route + method | API handler + EventBridge integration |
+| `defineAction()` | Public API endpoint OR internal callable | Action handler + (optional) API Gateway route |
 | `defineEvent()` | Event type with schema | Typed event publisher |
-| `defineWebhook()` | Inbound GitHub webhook handler | Webhook + validation |
+| `defineWebhook()` | Inbound webhook handler | Webhook + validation |
 | `defineSubscriber()` | Event subscriber handler | EventBridge rule + Lambda |
 | `defineSchedule()` | Cron-triggered handler | EventBridge Scheduler rule |
 | `defineJob()` | Async queue-based task | SQS queue + Lambda consumer |
-| `defineAction()` | Flow Designer action | Workspace-invoked handler |
 | `defineIntegration()` | External service integration | Async integration handler |
+| `defineFlow()` | Multi-step orchestration flow | Step Functions state machine |
 
 ## Context Surfaces
 
-14 surfaces available in `DomainContext`:
+The unified `DomainContext` injected into every handler exposes 14
+surfaces:
 
 | Surface | Purpose |
 |---|---|
-| `ctx.db` | PostgreSQL connection pool via drizzle-orm |
+| `ctx.db` | PostgreSQL connection pool via drizzle-orm (auto tenant-scoped) |
 | `ctx.publish()` | Publish an event to EventBridge |
-| `ctx.actions` | Invoke other domain actions |
+| `ctx.actions` | Invoke other domain actions (`ctx.actions[domainId].<id>(input)`) |
 | `ctx.integrations` | Call external integrations |
 | `ctx.jobs` | Enqueue async tasks to SQS |
-| `ctx.flows` | Trigger TIB Flow Designer flows |
-| `ctx.cache` | In-memory or distributed cache (Redis) |
+| `ctx.flows` | Trigger multi-step flows |
+| `ctx.cache` | In-memory or distributed cache |
 | `ctx.secrets` | Fetch AWS Secrets Manager values |
-| `ctx.fetch()` | HTTP client with request/response tracing |
+| `ctx.fetch()` | HTTP client with retry + circuit breaker |
 | `ctx.idempotency` | Deduplication by request ID |
 | `ctx.logger` | Pino JSON logger |
 | `ctx.tracer` | AWS X-Ray tracing |
-| `ctx.request` | Original HTTP request object |
-| `ctx.requestId` | Unique request UUID |
+| `ctx.actor` | Caller identity (sub, email, tenantId, roles, scopes) |
+| `ctx.tenant` | Resolved tenant (`{ id, workspaceId, orgId }`) |
 
 ## Design Principles
 
-This package is **intentionally framework-agnostic**. It exports types and factory functions only — all infrastructure (Lambdas, API Gateway, EventBridge, SQS, etc.) is provisioned by `@mettlecast/domain-cdk-packer`.
+This package is **intentionally framework-agnostic**. It exports types
+and factory functions only — all infrastructure (Lambdas, API Gateway,
+EventBridge, SQS, etc.) is provisioned by `@mettlecast/domain-cdk-packer`.
 
 **Exports by concern:**
 

package/dist/primitives/action.d.ts

@@ -1,36 +1,108 @@
 import { type ZodSchema } from 'zod';
 import type { DomainContext } from '../ctx/context.js';
 import type { OutboundAccess } from '../types/index.js';
-/** Who can call this action. */
-export type ActionVisibility = 'private' | 'domain' | 'workspace';
+/**
+ * Backend access scope for an action.
+ * - `private`  — callable only inside the defining domain.
+ * - `domain`   — callable by any domain in the same workspace.
+ * - `platform` — callable by platform-level services (cross-workspace).
+ */
+export type BackendAccess = 'private' | 'domain' | 'platform';
+/**
+ * Authentication posture for an API-exposed action.
+ * - `required` — caller's identity must be authenticated.
+ * - `none`     — anonymous endpoint; requires a `securityException.reason`.
+ * - `service`  — service-to-service only (no end-user identity).
+ */
+export type ApiAuthMode = 'required' | 'none' | 'service';
+/**
+ * Tenancy posture for an API-exposed action.
+ */
+export type ApiTenancyMode = 'required' | 'none' | 'system';
+/**
+ * Recorded justification for relaxing the default auth/tenancy posture.
+ * Required when `auth: 'none'` and when `tenancy: 'system'` is combined with
+ * `auth: 'required'` without role narrowing.
+ */
+export interface SecurityException {
+    /** Human-readable reason captured alongside the primitive. */
+    reason: string;
+}
+/**
+ * Action reachable only through in-process proxies (no HTTP route).
+ * Carries no path, method, auth, or tenancy fields.
+ */
+export interface InternalExposure {
+    type: 'internal';
+}
+/**
+ * Action exposed as an HTTP endpoint. The downstream CDK/registry
+ * pipeline generates API Gateway routes from this shape.
+ */
+export interface ApiExposure {
+    type: 'api';
+    /** HTTP route path relative to the domain base. Must start with `/`. */
+    path: string;
+    /** Explicit HTTP method. Never `ANY`. */
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+    /** Authentication posture for the HTTP route. */
+    auth: ApiAuthMode;
+    /** Tenancy posture for the HTTP route. */
+    tenancy: ApiTenancyMode;
+    /** Required role claims (only meaningful when `auth` is `required`). */
+    roles?: string[];
+    /** Required justification when the auth/tenancy posture is relaxed. */
+    securityException?: SecurityException;
+}
+/** Discriminated union of every legal exposure for an action. */
+export type ActionExposure = InternalExposure | ApiExposure;
 /** Configuration for an action primitive. */
 export interface ActionConfig {
     /** Machine-readable identifier (kebab-case). */
     id: string;
-    /** Visibility scope. 'private' = only within the same domain. */
-    visibility: ActionVisibility;
+    /** Backend access scope. `private` = only within the same domain. */
+    backendAccess: BackendAccess;
+    /** How this action is reachable — internal proxy or HTTP route. */
+    exposure: ActionExposure;
     /** Zod schema for validated input. */
     input: ZodSchema<any>;
     /** Zod schema for return type. */
     output: ZodSchema<any>;
     /**
      * Whether to enforce idempotency for this action.
-     * If true, the runtime checks ctx.idempotency before executing.
+     * If true, the runtime checks `ctx.idempotency` before executing.
      */
     idempotent?: boolean;
-    /** Whether this handler may use NAT-backed public internet egress. Defaults to internal. */
+    /**
+     * Optional caller allowlist for sensitive `backendAccess: 'platform'`
+     * actions. When present and non-empty, `executeAction` denies internal
+     * callers whose `callerDomain` is not in the list. This narrows broad
+     * platform-scoped primitives — for example, an internal "rotate
+     * encryption key" action — without forcing every caller into the more
+     * restrictive `private`/`domain` scopes.
+     *
+     * - `undefined` or `[]` — fall back to the `backendAccess` policy.
+     * - non-empty list — callerDomain MUST appear in the list.
+     *
+     * API-exposed calls (`source.type === 'api'`) skip this check; the
+     * allowlist only governs the in-process / cross-Lambda proxy path,
+     * which is the channel a runaway backend can otherwise exploit.
+     */
+    allowedCallers?: string[];
+    /** Whether this handler may use NAT-backed public internet egress. Defaults to `internal`. */
     outboundAccess?: OutboundAccess;
     /** Handler implementation. */
     handler: (input: any, ctx: DomainContext) => Promise<any>;
 }
-/** Return type of defineAction. */
+/** Return type of `defineAction`. */
 export interface ActionDefinition extends ActionConfig {
     /** Discriminant. */
     _kind: 'action';
 }
 /**
  * Register a callable domain action.
- * Actions with visibility 'domain' or 'workspace' are exposed via ctx.actions proxy.
+ * The runtime validates `backendAccess` and the discriminated `exposure`
+ * against the action-first contract before accepting the primitive.
  * @throws {ZodError} if config is invalid
  */
 export declare function defineAction(config: ActionConfig): ActionDefinition;

package/dist/primitives/action.js

@@ -1,16 +1,83 @@
 import { z } from 'zod';
+// Native enum objects — Zod v4's recommended pattern over `z.enum([...])`.
+// Each `as const` object is the source of truth; `z.nativeEnum(...)` derives
+// the inferred string-literal union from the keys.
+const BackendAccessLiteral = { private: 'private', domain: 'domain', platform: 'platform' };
+const ApiAuthModeLiteral = { required: 'required', none: 'none', service: 'service' };
+const ApiTenancyModeLiteral = { required: 'required', none: 'none', system: 'system' };
+const ApiMethodLiteral = {
+    GET: 'GET',
+    POST: 'POST',
+    PUT: 'PUT',
+    PATCH: 'PATCH',
+    DELETE: 'DELETE',
+    HEAD: 'HEAD',
+    OPTIONS: 'OPTIONS',
+};
+// Internal exposure — only `type` is allowed; any additional field is a bug.
+const InternalExposureSchema = z
+    .object({
+    type: z.literal('internal'),
+})
+    .strict();
+// API exposure — required fields present, optional fields allowed, then
+// three cross-field refinements encode the action-first contract.
+const ApiExposureSchema = z
+    .object({
+    type: z.literal('api'),
+    path: z.string().startsWith('/'),
+    method: z.nativeEnum(ApiMethodLiteral),
+    auth: z.nativeEnum(ApiAuthModeLiteral),
+    tenancy: z.nativeEnum(ApiTenancyModeLiteral),
+    roles: z.array(z.string().min(1)).optional(),
+    securityException: z.object({ reason: z.string().min(1) }).optional(),
+})
+    .strict()
+    // auth: 'none' requires a non-empty securityException.reason
+    .refine((e) => e.auth !== 'none' || (e.securityException?.reason?.length ?? 0) > 0, {
+    message: "exposure.auth 'none' requires exposure.securityException.reason",
+    path: ['securityException'],
+})
+    // tenancy: 'required' → path must include '/v1/tenants/{tenantId}/'
+    .refine((e) => e.tenancy !== 'required' || e.path.includes('/v1/tenants/{tenantId}/'), {
+    message: "exposure.tenancy 'required' requires exposure.path to include '/v1/tenants/{tenantId}/'",
+    path: ['path'],
+})
+    // tenancy: 'system' requires auth 'required' or 'service'. When auth is
+    // 'service' the exposure is service-only and no roles are required;
+    // when auth is 'required' a non-empty roles array is mandatory.
+    .refine((e) => {
+    if (e.tenancy !== 'system')
+        return true;
+    if (e.auth !== 'required' && e.auth !== 'service')
+        return false;
+    if (e.auth === 'service')
+        return true;
+    return Array.isArray(e.roles) && e.roles.length > 0;
+}, {
+    message: "exposure.tenancy 'system' requires exposure.auth 'required' or 'service'; when auth is 'required' a non-empty roles array is mandatory",
+    path: ['tenancy'],
+});
+const ActionExposureSchema = z.discriminatedUnion('type', [
+    InternalExposureSchema,
+    ApiExposureSchema,
+]);
+const ZodSchemaRefinement = z.custom((v) => typeof v === 'object' && v !== null && typeof v.parse === 'function', { message: 'input/output must be Zod schema objects' });
 const ActionConfigSchema = z.object({
     id: z.string().min(1),
-    visibility: z.enum(['private', 'domain', 'workspace']),
-    input: z.unknown(),
-    output: z.unknown(),
+    backendAccess: z.nativeEnum(BackendAccessLiteral),
+    exposure: ActionExposureSchema,
+    input: ZodSchemaRefinement,
+    output: ZodSchemaRefinement,
     idempotent: z.boolean().optional(),
+    allowedCallers: z.array(z.string().min(1)).optional(),
     outboundAccess: z.enum(['internal', 'internet']).default('internal'),
     handler: z.function(),
 });
 /**
  * Register a callable domain action.
- * Actions with visibility 'domain' or 'workspace' are exposed via ctx.actions proxy.
+ * The runtime validates `backendAccess` and the discriminated `exposure`
+ * against the action-first contract before accepting the primitive.
  * @throws {ZodError} if config is invalid
  */
 export function defineAction(config) {

package/dist/primitives/index.d.ts

@@ -1,5 +1,4 @@
 export * from './domain.js';
-export * from './api.js';
 export * from './webhook.js';
 export * from './define-outbound-webhook.js';
 export * from './events.js';

package/dist/primitives/index.js

@@ -1,5 +1,4 @@
 export * from './domain.js';
-export * from './api.js';
 export * from './webhook.js';
 export * from './define-outbound-webhook.js';
 export * from './events.js';

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

@@ -0,0 +1,164 @@
+/**
+ * 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 type { DomainContext } from '../ctx/context.js';
+import type { ActionDefinition, BackendAccess } from '../primitives/action.js';
+import { TibError } from './error-formatter.js';
+/** Action invocation originating from an API Gateway route. */
+export interface ApiActionSource {
+    type: 'api';
+    /**
+     * Tenant ID extracted from the route path (e.g. `/v1/tenants/{tenantId}/...`).
+     * When provided, must match `ctx.tenant.id`. Optional to keep the executor
+     * usable when path-param extraction is delegated to the adapter.
+     */
+    pathTenantId?: string;
+    /**
+     * Role claims attached to the inbound request (e.g. parsed from JWT scopes
+     * or custom claims). Only consulted when the action's exposure requires
+     * roles (auth 'required' + tenancy 'system').
+     */
+    actorRoles?: string[];
+}
+/** Action invocation originating from a same-process or cross-process backend call. */
+export interface InternalActionSource {
+    type: 'internal';
+    /** Domain ID of the caller. Used for backendAccess enforcement. */
+    callerDomain?: string;
+    /** Tenant ID the caller claims to operate under (must match ctx.tenant.id). */
+    callerTenantId?: string;
+}
+/** Discriminated union of every legal invocation source for an action. */
+export type ActionSource = ApiActionSource | InternalActionSource;
+/**
+ * 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 declare function isCallerAllowed(opts: {
+    action: Pick<ActionDefinition, 'id' | 'backendAccess' | 'allowedCallers'>;
+    callerDomain?: string;
+    definingDomain?: string;
+}): boolean;
+/**
+ * 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 declare function assertOrThrow(condition: unknown, message: string, code: string): asserts condition;
+/**
+ * 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 declare function ensureTenantMatches(ctx: DomainContext, expectedTenantId?: string): void;
+/**
+ * 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 declare function actorHasRequiredRoles(actorRoles: string[] | undefined, requiredRoles: string[] | undefined): boolean;
+/**
+ * Optional metadata that adapters may attach so audit/log lines can carry
+ * `traceId`, `domainId`, and the action's defining-domain identifier. The
+ * executor never requires these — when omitted it falls back to safe
+ * defaults — but supplying them produces much richer observability.
+ */
+export interface ExecuteActionMeta {
+    /** Domain ID that owns the action being executed. */
+    definingDomain?: string;
+    /** Trace ID for the current request. */
+    traceId?: string;
+}
+/**
+ * Result envelope returned by `executeAction`. Adapters translate this into
+ * transport-specific responses (HTTP status, Lambda payload, etc.).
+ *
+ * - `ok: true` — handler returned a value that passed the output schema.
+ * - `ok: false` — the failure carried a domain-meaningful error code that
+ *   the adapter can map to a status. The executor never returns HTTP
+ *   response objects.
+ */
+export type ExecuteActionResult = {
+    ok: true;
+    value: unknown;
+    replayed: boolean;
+} | {
+    ok: false;
+    error: TibError | ZodError;
+    code: string;
+};
+/**
+ * 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 declare function executeAction(action: ActionDefinition, input: unknown, ctx: DomainContext, source: ActionSource, meta?: ExecuteActionMeta): Promise<ExecuteActionResult>;
+/**
+ * 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 declare function releaseDbSafely(ctx: DomainContext): Promise<void>;
+/**
+ * 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 declare function withActionExecution(action: ActionDefinition, input: unknown, ctx: DomainContext, source: ActionSource, meta?: ExecuteActionMeta, options?: {
+    ownDbLifecycle?: boolean;
+}): Promise<ExecuteActionResult>;
+export type { BackendAccess };