@mettlecast/domain-runtime 0.2.59 → 0.2.61

package/dist/runtime/files.js

@@ -1,16 +1,72 @@
 import { S3Client, GetObjectCommand, PutObjectCommand, DeleteObjectCommand, ListObjectsV2Command } from '@aws-sdk/client-s3';
 import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
 import { getTenantCredentials } from './tenant-credentials.js';
+/**
+ * Reject missing, empty, or 'unknown' tenant IDs at construction time.
+ *
+ * Mirrors the same guard in `createStore`: the runtime must fail loudly when
+ * a wrapper is instantiated with an unsafe tenant rather than silently
+ * writing/reading under a shared prefix named "unknown".
+ */
+function assertRuntimeTenantId(tenantId) {
+    if (typeof tenantId !== 'string' || tenantId.length === 0 || tenantId === 'unknown') {
+        throw new Error(`createFiles: a valid runtime tenantId is required (got ${JSON.stringify(tenantId)})`);
+    }
+}
+/**
+ * Normalise an S3 key and reject any input that would let a caller escape the
+ * tenant prefix or reach outside the bucket's logical root.
+ *
+ * S3 treats keys as opaque flat strings, so `..` and `.` segments are NOT
+ * resolved by the service — but the runtime contract is that keys are relative
+ * to the tenant's namespace and that path-traversal-style inputs are a
+ * developer error (and a likely injection vector if any layer ever resolves
+ * them). Reject early.
+ *
+ * Rules:
+ * - Must be a non-empty string.
+ * - Must not start with `/` (absolute paths are meaningless inside a bucket).
+ * - Must not equal `.` or `..`.
+ * - Must not contain any segment equal to `.` or `..` after splitting on `/`.
+ */
+function normalizeAndValidateKey(rawKey, op) {
+    if (typeof rawKey !== 'string' || rawKey.length === 0) {
+        throw new Error(`${op}: key must be a non-empty string (got ${typeof rawKey === 'string' ? JSON.stringify(rawKey) : typeof rawKey})`);
+    }
+    if (rawKey.startsWith('/')) {
+        throw new Error(`${op}: key must not start with '/': ${JSON.stringify(rawKey)}`);
+    }
+    if (rawKey === '.' || rawKey === '..') {
+        throw new Error(`${op}: key must not be '.' or '..': ${JSON.stringify(rawKey)}`);
+    }
+    for (const seg of rawKey.split('/')) {
+        if (seg === '.' || seg === '..') {
+            throw new Error(`${op}: key contains path-traversal segment '${seg}': ${JSON.stringify(rawKey)}`);
+        }
+    }
+    return rawKey;
+}
+/**
+ * Tenant-scoped S3 wrapper. All keys are automatically prefixed with
+ * `{tenantId}/` — developers supply only the path after the tenant prefix.
+ *
+ * Path-traversal patterns (`../`, `./`, leading `/`, empty keys) are rejected
+ * before the tenant prefix is applied, so every object operation is scoped to
+ * the runtime tenant regardless of caller input.
+ */
 export function createFiles(opts) {
+    assertRuntimeTenantId(opts.tenantId);
     const client = new S3Client({
         credentials: () => getTenantCredentials(opts.tenantRoleArn, opts.tenantId),
     });
     const { bucketName, tenantId } = opts;
-    const prefix = (key) => `${tenantId}/${key}`;
+    const tenantPrefix = `${tenantId}/`;
+    const prefix = (key) => `${tenantPrefix}${key}`;
     return {
         async get(key) {
+            const safeKey = normalizeAndValidateKey(key, 'files.get');
             try {
-                const res = await client.send(new GetObjectCommand({ Bucket: bucketName, Key: prefix(key) }));
+                const res = await client.send(new GetObjectCommand({ Bucket: bucketName, Key: prefix(safeKey) }));
                 const chunks = [];
                 for await (const chunk of res.Body) {
                     chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
@@ -24,28 +80,40 @@ export function createFiles(opts) {
             }
         },
         async put(key, body, putOpts) {
+            const safeKey = normalizeAndValidateKey(key, 'files.put');
             await client.send(new PutObjectCommand({
                 Bucket: bucketName,
-                Key: prefix(key),
+                Key: prefix(safeKey),
                 Body: body,
                 ContentType: putOpts?.contentType,
                 Metadata: putOpts?.metadata,
             }));
         },
         async delete(key) {
-            await client.send(new DeleteObjectCommand({ Bucket: bucketName, Key: prefix(key) }));
+            const safeKey = normalizeAndValidateKey(key, 'files.delete');
+            await client.send(new DeleteObjectCommand({ Bucket: bucketName, Key: prefix(safeKey) }));
         },
         async list(listPrefix) {
-            const fullPrefix = listPrefix ? `${tenantId}/${listPrefix}` : `${tenantId}/`;
+            // listPrefix is optional. When provided it must be a tenant-relative
+            // path under the same rules; when omitted, we list everything in the
+            // tenant's namespace.
+            let fullPrefix;
+            if (listPrefix === undefined || listPrefix === '') {
+                fullPrefix = tenantPrefix;
+            }
+            else {
+                const safePrefix = normalizeAndValidateKey(listPrefix, 'files.list');
+                fullPrefix = prefix(safePrefix);
+            }
             const res = await client.send(new ListObjectsV2Command({ Bucket: bucketName, Prefix: fullPrefix }));
-            const tenantPrefixLen = `${tenantId}/`.length;
             return {
-                keys: (res.Contents ?? []).map(o => (o.Key ?? '').slice(tenantPrefixLen)),
+                keys: (res.Contents ?? []).map(o => (o.Key ?? '').slice(tenantPrefix.length)),
                 cursor: res.NextContinuationToken,
             };
         },
         async getSignedUrl(key, expiresIn = 3600) {
-            const cmd = new GetObjectCommand({ Bucket: bucketName, Key: prefix(key) });
+            const safeKey = normalizeAndValidateKey(key, 'files.getSignedUrl');
+            const cmd = new GetObjectCommand({ Bucket: bucketName, Key: prefix(safeKey) });
             return getSignedUrl(client, cmd, { expiresIn });
         },
     };

package/dist/runtime/hydrate.js

@@ -12,6 +12,7 @@ import { createFlowsProxy } from './flows.js';
 import { createIntegrationsProxy, createEmptyIntegrationsProxy } from './integrations.js';
 import { createFeatureFlags } from './feature-flags.js';
 import { createAudit } from './audit.js';
+import { extractObservabilityBindings } from './observability-bindings.js';
 import { createStore, createNoopStore } from './store.js';
 import { createFiles, createNoopFiles } from './files.js';
 /**
@@ -40,9 +41,14 @@ export async function hydrateCtx(_event, options = {}) {
     const lambdaName = options.lambdaName ?? process.env['AWS_LAMBDA_FUNCTION_NAME'] ?? 'unknown';
     const actor = options.actor ?? { type: 'system' };
     const tenant = options.tenant ?? { id: 'unknown', workspaceId: 'unknown' };
+    // Issue #4662 Task D — every log line carries the canonical
+    // observability bindings (tenantId, orgId, actorSub, actorRoles,
+    // traceId, …) as Powertools persistent attributes so CloudWatch
+    // Logs Insights filters can reliably match by tenant without
+    // checking for both the key and the literal string 'unknown'.
+    const observabilityBindings = extractObservabilityBindings({ tenant, actor, traceId: options.traceId }, { definingDomain: options.domainId });
     const logger = options.logger ?? createLogger({
-        tenantId: tenant.id,
-        workspaceId: tenant.workspaceId,
+        ...observabilityBindings,
         lambda: lambdaName,
     });
     const tracer = options.tracer ?? createTracer(lambdaName);
@@ -81,6 +87,11 @@ export async function hydrateCtx(_event, options = {}) {
             connectionString: options.databaseUrl,
             tenantId: tenant.id,
             orgId: tenant.orgId,
+            // Bind the authenticated actor's subject so DB-side triggers and audit
+            // helpers can read `current_setting('app.actor_id', true)`. Falls back
+            // to undefined for system/schedule actors that don't carry a sub claim;
+            // createDb skips the set_config call when actorId is absent.
+            actorId: actor.sub,
         });
         // TODO: Wire proper teardown to call await db.release() after handler completes.
         // For now, callers must manually call await ctx.db.release() in a try/finally block.
@@ -145,6 +156,10 @@ export async function hydrateCtx(_event, options = {}) {
         actorId: actor?.sub,
         traceId: options.traceId ?? 'unknown',
         publish,
+        // Issue #4662 Task D — emit the canonical observability bindings
+        // alongside the audit envelope so SOC2 / forensics consumers can
+        // filter by any of the canonical fields (tenant, actor, action).
+        bindings: extractObservabilityBindings({ tenant, actor, traceId: options.traceId }, { definingDomain: options.domainId }),
     });
     const store = options.store ?? ((options.domainTableName ?? process.env['DOMAIN_TABLE_NAME'])
         ? createStore({ tableName: options.domainTableName ?? process.env['DOMAIN_TABLE_NAME'], tenantId: tenant.id, tenantRoleArn: process.env['DOMAIN_TENANT_ROLE_ARN'] })

package/dist/runtime/index.d.ts

@@ -1,6 +1,8 @@
 export { createLogger } from './logger.js';
 export { createTracer, noopTracer, initOtel } from './tracer.js';
 export { createCache } from './cache.js';
+export { extractObservabilityBindings, requireObservabilityBindings, } from './observability-bindings.js';
+export type { ObservabilityBindings, ExtractBindingsOptions, } from './observability-bindings.js';
 /**
  * @deprecated Use `createKyClient` instead. The `createFetch` name is kept
  * as a backward-compatible alias for callers that imported it before the
@@ -15,6 +17,8 @@ export { ok, err, notFound } from '../types/result.js';
 export type { AppError, Result } from '../types/result.js';
 export { safeFetch, safeDb, wrapHandler, captureStack } from './typed-errors.js';
 export type { SafeResult } from './typed-errors.js';
+export { TibError, TIB_ERROR_CODES, domainError, readLegacyHttpStatus, } from './error-formatter.js';
+export type { TibErrorCode, StandardError, HttpStatusCarrier } from './error-formatter.js';
 export { createSecrets, createEmptySecrets } from './secrets.js';
 export type { SecretsOptions } from './secrets.js';
 export { createIdempotency, createNoopIdempotency } from './idempotency.js';
@@ -33,6 +37,8 @@ export { createIntegrationsProxy, createEmptyIntegrationsProxy } from './integra
 export type { IntegrationsProxyOptions } from './integrations.js';
 export { hydrateCtx } from './hydrate.js';
 export type { HydrateOptions } from './hydrate.js';
+export { executeAction, withActionExecution, releaseDbSafely } from './action-executor.js';
+export type { ApiActionSource, InternalActionSource, ActionSource, ExecuteActionMeta, ExecuteActionResult, } from './action-executor.js';
 export { negotiateVersion } from './version-negotiator.js';
 export type { VersionNegotiation } from './version-negotiator.js';
 export { checkSunset, applySunsetHeaders } from './sunset-guard.js';
@@ -41,8 +47,10 @@ export { eventVersionMatches } from './event-version-matcher.js';
 export { extractActorFromApiGatewayEvent, extractTenantFromApiGatewayEvent } from './extractors.js';
 export { parseQuery, encodeCursor, decodeCursor, DEFAULT_LIMIT, MAX_LIMIT } from './query-parser.js';
 export type { ParsedQuery } from './query-parser.js';
-export { createApiLambdaHandler } from './api-handler.js';
-export type { CreateApiHandlerOptions } from './api-handler.js';
+export { createExposedActionApiHandler } from './exposed-action-api-handler.js';
+export type { CreateExposedActionHandlerOptions } from './exposed-action-api-handler.js';
+export { createActionLambdaHandler } from './action-handler.js';
+export type { CreateActionHandlerOptions, ActionInvocationEnvelope, ActionActorEnvelope, ActionRegistryEntry, ActionHandlerFn, } from './action-handler.js';
 export { createSubscriberLambdaHandler } from './subscriber-handler.js';
 export type { CreateSubscriberHandlerOptions } from './subscriber-handler.js';
 export { createJobLambdaHandler } from './job-handler.js';

package/dist/runtime/index.js

@@ -2,6 +2,11 @@
 export { createLogger } from './logger.js';
 export { createTracer, noopTracer, initOtel } from './tracer.js';
 export { createCache } from './cache.js';
+// Issue #4662 Task D — observability bindings. Used by hydrateCtx,
+// the action executor, and the cross-domain ActionsProxy so every log
+// line, audit event, and Lambda envelope carries the same canonical
+// tenant / actor / action identity fields.
+export { extractObservabilityBindings, requireObservabilityBindings, } from './observability-bindings.js';
 /**
  * @deprecated Use `createKyClient` instead. The `createFetch` name is kept
  * as a backward-compatible alias for callers that imported it before the
@@ -15,6 +20,8 @@ export { checkRateLimit, clearRateLimitBuckets } from './rate-limiter.js';
 // single barrel.  The full type definitions live in `../types/result.js`.
 export { ok, err, notFound } from '../types/result.js';
 export { safeFetch, safeDb, wrapHandler, captureStack } from './typed-errors.js';
+// Domain error helper — preferred throwing primitive for action handlers.
+export { TibError, TIB_ERROR_CODES, domainError, readLegacyHttpStatus, } from './error-formatter.js';
 // AWS SDK implementations
 export { createSecrets, createEmptySecrets } from './secrets.js';
 export { createIdempotency, createNoopIdempotency } from './idempotency.js';
@@ -28,6 +35,15 @@ export { createFlowsProxy, createCapturingFlowsProxy } from './flows.js';
 export { createIntegrationsProxy, createEmptyIntegrationsProxy } from './integrations.js';
 // Master factory
 export { hydrateCtx } from './hydrate.js';
+// Shared action executor (Wave 2 of #4619). Consumed by both the API-exposed
+// action adapter and the internal cross-domain action Lambda handler. The
+// helper functions exported alongside (`withActionExecution`,
+// `releaseDbSafely`) cover the standalone-script / test case where the
+// executor owns the DB lifecycle. Lower-level pipeline helpers
+// (`isCallerAllowed`, `ensureTenantMatches`, `actorHasRequiredRoles`) stay
+// private to the file — they're exported there only so unit tests can pin
+// behaviour against a single import surface.
+export { executeAction, withActionExecution, releaseDbSafely } from './action-executor.js';
 // Versioning middleware
 export { negotiateVersion } from './version-negotiator.js';
 export { checkSunset, applySunsetHeaders } from './sunset-guard.js';
@@ -37,7 +53,8 @@ export { extractActorFromApiGatewayEvent, extractTenantFromApiGatewayEvent } fro
 // Query parsing
 export { parseQuery, encodeCursor, decodeCursor, DEFAULT_LIMIT, MAX_LIMIT } from './query-parser.js';
 // Lambda handler wrappers
-export { createApiLambdaHandler } from './api-handler.js';
+export { createExposedActionApiHandler } from './exposed-action-api-handler.js';
+export { createActionLambdaHandler } from './action-handler.js';
 export { createSubscriberLambdaHandler } from './subscriber-handler.js';
 export { createJobLambdaHandler } from './job-handler.js';
 export { createWebhookLambdaHandler } from './webhook-handler.js';

package/dist/runtime/observability-bindings.d.ts

@@ -0,0 +1,110 @@
+import type { DomainContext } from '../ctx/context.js';
+/**
+ * Canonical observability bindings attached to every log line and audit
+ * event in the runtime (#4662 Task D).
+ *
+ * These fields mirror the JWT contract:
+ *   - `tenantId`, `orgId` come from `ctx.tenant`
+ *   - `actorSub`, `actorEmail`, `actorRoles` come from `ctx.actor`
+ *   - `actionId`, `callerDomain`, `traceId` come from the executing
+ *     action's runtime context (`meta.definingDomain`, `meta.traceId`,
+ *     and the inbound `ActionInvocationEnvelope` for cross-domain calls)
+ *
+ * Every key is optional — the helper intentionally omits empty values so
+ * structured logs stay compact and CloudWatch Insights filters can
+ * reliably match on `tenantId` without checking for both the key and
+ * the literal string `'unknown'`.
+ */
+export interface ObservabilityBindings {
+    /** Tenant ID from the request context. Omitted when unknown. */
+    tenantId?: string;
+    /** Org ID from the request context. Omitted when absent. */
+    orgId?: string;
+    /** Workspace ID from the request context. Omitted when unknown. */
+    workspaceId?: string;
+    /** JWT `sub` claim of the acting principal. Omitted when absent. */
+    actorSub?: string;
+    /** Email address of the acting principal. Omitted when absent. */
+    actorEmail?: string;
+    /** Role claims (e.g. `['sys_admin']`). Omitted when empty. */
+    actorRoles?: string[];
+    /** Action ID being executed (e.g. `'charge-card'`). Omitted when absent. */
+    actionId?: string;
+    /** Domain that owns the action being executed. Omitted when absent. */
+    callerDomain?: string;
+    /** Domain that invoked this call (cross-domain only). Omitted when same-domain. */
+    targetDomain?: string;
+    /** Distributed trace ID for the current request. Omitted when absent. */
+    traceId?: string;
+}
+/**
+ * Options for {@link extractObservabilityBindings}.
+ */
+export interface ExtractBindingsOptions {
+    /** Domain ID of the executing action (`meta.definingDomain`). */
+    definingDomain?: string;
+    /** Trace ID for the current request (`meta.traceId`). */
+    traceId?: string;
+    /** Inbound action invocation envelope (cross-domain only). */
+    envelope?: {
+        callerDomain?: string;
+        targetDomain?: string;
+        actionId?: string;
+        actorSub?: string;
+    };
+    /**
+     * When false (default), `callerDomain` is omitted when the caller is
+     * the same domain as `definingDomain`. Set to true to always include
+     * it (useful for cross-domain debugging).
+     */
+    alwaysIncludeCaller?: boolean;
+}
+/**
+ * Minimal input the binding extractor needs from the runtime context.
+ * Keeps callers from having to pass the full {@link DomainContext}
+ * (which carries DB, secrets, integrations proxies that have nothing
+ * to do with observability).
+ */
+interface ObservabilityContext {
+    tenant?: {
+        id?: string;
+        workspaceId?: string;
+        orgId?: string;
+    };
+    actor?: {
+        sub?: string;
+        email?: string;
+        roles?: string[];
+    };
+    /** Optional inline trace id when callers don't pass it via `options.traceId`. */
+    traceId?: string;
+}
+/**
+ * Project the runtime `DomainContext` (plus a few optional metadata
+ * fields) onto the canonical {@link ObservabilityBindings} shape.
+ *
+ * Used by:
+ *
+ * - `createLogger({...bindings})` so every log line carries the
+ *   bindings as Powertools persistent attributes.
+ * - `createAudit(...)` so audit events on the EventBridge bus carry the
+ *   same shape.
+ * - The cross-domain `ActionsProxy` envelope so receiving handlers
+ *   observe the same identity the caller had.
+ *
+ * The function is pure and side-effect free — it does NOT mutate `ctx`,
+ * does NOT log, and does NOT publish. Callers compose the bindings into
+ * whatever observability sink they need.
+ */
+export declare function extractObservabilityBindings(ctx: ObservabilityContext, options?: ExtractBindingsOptions): ObservabilityBindings;
+/**
+ * Convenience helper: extract bindings and assert at least one
+ * tenant identity is present. Used by entrypoints that should never
+ * run without a tenant (e.g. API-exposed actions with `tenancy:
+ * 'required'`) — it produces a structured error before any side
+ * effects occur.
+ *
+ * @throws TibError when neither tenant nor trace id is present.
+ */
+export declare function requireObservabilityBindings(ctx: Pick<DomainContext, 'tenant' | 'actor'>, options?: ExtractBindingsOptions): ObservabilityBindings;
+export {};

package/dist/runtime/observability-bindings.js

@@ -0,0 +1,94 @@
+import { TibError } from './error-formatter.js';
+/**
+ * Project the runtime `DomainContext` (plus a few optional metadata
+ * fields) onto the canonical {@link ObservabilityBindings} shape.
+ *
+ * Used by:
+ *
+ * - `createLogger({...bindings})` so every log line carries the
+ *   bindings as Powertools persistent attributes.
+ * - `createAudit(...)` so audit events on the EventBridge bus carry the
+ *   same shape.
+ * - The cross-domain `ActionsProxy` envelope so receiving handlers
+ *   observe the same identity the caller had.
+ *
+ * The function is pure and side-effect free — it does NOT mutate `ctx`,
+ * does NOT log, and does NOT publish. Callers compose the bindings into
+ * whatever observability sink they need.
+ */
+export function extractObservabilityBindings(ctx, options = {}) {
+    const out = {};
+    const { tenant, actor } = ctx;
+    if (tenant) {
+        if (tenant.id && tenant.id !== 'unknown')
+            out.tenantId = tenant.id;
+        if (tenant.orgId && tenant.orgId !== 'unknown')
+            out.orgId = tenant.orgId;
+        if (tenant.workspaceId && tenant.workspaceId !== 'unknown') {
+            out.workspaceId = tenant.workspaceId;
+        }
+    }
+    if (actor) {
+        if (actor.sub)
+            out.actorSub = actor.sub;
+        if (actor.email)
+            out.actorEmail = actor.email;
+        if (Array.isArray(actor.roles) && actor.roles.length > 0)
+            out.actorRoles = actor.roles;
+    }
+    // `ctx.traceId` is set by `createExposedActionApiHandler` /
+    // `createActionLambdaHandler` from the inbound envelope or header. We
+    // prefer the explicit `options.traceId` so callers can override (e.g.
+    // when replaying a cached invocation).
+    const traceId = options.traceId ?? ctx.traceId;
+    if (traceId && traceId !== 'unknown')
+        out.traceId = traceId;
+    if (options.envelope) {
+        const { callerDomain, targetDomain, actionId } = options.envelope;
+        if (actionId)
+            out.actionId = actionId;
+        if (callerDomain)
+            out.callerDomain = callerDomain;
+        if (targetDomain && targetDomain !== callerDomain) {
+            out.targetDomain = targetDomain;
+        }
+    }
+    else if (options.definingDomain) {
+        // Same-domain invocations: surface the executing action's domain so
+        // downstream logs always carry a `callerDomain` for filtering —
+        // the strip below removes it again unless `alwaysIncludeCaller`
+        // is set.
+        out.callerDomain = options.definingDomain;
+    }
+    // Strip the `callerDomain` when it equals `definingDomain` (the
+    // common in-process case where the only metadata we have is the
+    // executing action's defining domain) so the field only adds noise
+    // for genuinely cross-domain calls. `alwaysIncludeCaller` overrides
+    // this for debugging. Skipped when an envelope was supplied —
+    // explicit cross-domain metadata always wins over the redundancy
+    // heuristic.
+    if (!options.alwaysIncludeCaller
+        && !options.envelope
+        && out.callerDomain
+        && options.definingDomain
+        && out.callerDomain === options.definingDomain) {
+        delete out.callerDomain;
+    }
+    return out;
+}
+/**
+ * Convenience helper: extract bindings and assert at least one
+ * tenant identity is present. Used by entrypoints that should never
+ * run without a tenant (e.g. API-exposed actions with `tenancy:
+ * 'required'`) — it produces a structured error before any side
+ * effects occur.
+ *
+ * @throws TibError when neither tenant nor trace id is present.
+ */
+export function requireObservabilityBindings(ctx, options = {}) {
+    const bindings = extractObservabilityBindings(ctx, options);
+    if (!bindings.tenantId) {
+        throw new TibError('Observability bindings missing tenantId', 'OBSERVABILITY_BINDINGS_INCOMPLETE');
+    }
+    return bindings;
+}

package/dist/runtime/store.d.ts

@@ -1,4 +1,12 @@
 import type { DomainStoreContext } from '../ctx/store.js';
+/**
+ * Tenant-scoped DynamoDB wrapper. PK is always the current tenant — developers
+ * supply only the SK. All operations are automatically scoped to ctx.tenant.id.
+ *
+ * The runtime tenant ID supplied at construction time is the SOLE source of
+ * the partition key. Caller-supplied `tenantId` fields in `put` items or
+ * `update` payloads are dropped/overridden before reaching DynamoDB.
+ */
 export declare function createStore(opts: {
     tableName: string;
     tenantId: string;

package/dist/runtime/store.js

@@ -1,7 +1,30 @@
 import { DynamoDBClient, GetItemCommand, PutItemCommand, DeleteItemCommand, QueryCommand, UpdateItemCommand } from '@aws-sdk/client-dynamodb';
 import { marshall, unmarshall } from '@aws-sdk/util-dynamodb';
 import { getTenantCredentials } from './tenant-credentials.js';
+/**
+ * Reject missing, empty, or 'unknown' tenant IDs at construction time.
+ *
+ * The runtime layer (hydrateCtx, api-handler, action-executor) already
+ * surfaces tenant failures upstream, but the wrapper itself must fail loudly
+ * if it is ever instantiated with an unsafe tenant — otherwise it would
+ * silently write to a single shared partition named "unknown". This is the
+ * last line of defence for DynamoDB tenant isolation (#4619 Wave 5 Task 5.2).
+ */
+function assertRuntimeTenantId(tenantId) {
+    if (typeof tenantId !== 'string' || tenantId.length === 0 || tenantId === 'unknown') {
+        throw new Error(`createStore: a valid runtime tenantId is required (got ${JSON.stringify(tenantId)})`);
+    }
+}
+/**
+ * Tenant-scoped DynamoDB wrapper. PK is always the current tenant — developers
+ * supply only the SK. All operations are automatically scoped to ctx.tenant.id.
+ *
+ * The runtime tenant ID supplied at construction time is the SOLE source of
+ * the partition key. Caller-supplied `tenantId` fields in `put` items or
+ * `update` payloads are dropped/overridden before reaching DynamoDB.
+ */
 export function createStore(opts) {
+    assertRuntimeTenantId(opts.tenantId);
     const client = new DynamoDBClient({
         credentials: () => getTenantCredentials(opts.tenantRoleArn, opts.tenantId),
     });
@@ -15,6 +38,9 @@ export function createStore(opts) {
             return res.Item ? unmarshall(res.Item) : null;
         },
         async put(sk, item, putOpts) {
+            // Caller-supplied tenantId/sk in `item` is always overridden by the
+            // runtime values. This is structural, not just a behavioural note —
+            // the spread order makes it impossible for caller fields to win.
             const record = { ...item, tenantId, sk };
             if (putOpts?.ttl) {
                 record['expiresAt'] = Math.floor(Date.now() / 1000) + putOpts.ttl;
@@ -52,6 +78,9 @@ export function createStore(opts) {
             };
         },
         async update(sk, updates) {
+            // Defensive: even if a caller tries to write `tenantId` or `sk` via the
+            // updates map, those keys are filtered before reaching DynamoDB. The
+            // partition key and sort key are owned by the runtime.
             const entries = Object.entries(updates).filter(([k]) => k !== 'tenantId' && k !== 'sk');
             if (entries.length === 0)
                 return;

package/dist/runtime/tracer.d.ts

@@ -20,7 +20,7 @@ export declare const noopTracer: Tracer;
  *
  * **Opt-in by design.** This function is NOT called automatically by the
  * runtime; domain handler templates must call `initOtel()` at module
- * scope if they want OTel-exported spans. The `tib doctor` gate
+ * scope if they want OTel-exported spans. The `mc-domain-module doctor` gate
  * (`checkOtelInitInLambdas`) enforces this convention by scanning
  * `domains/.../api/-.ts` for an `initOtel(...)` call.
  *

package/dist/runtime/tracer.js

@@ -68,7 +68,7 @@ let initialised = false;
  *
  * **Opt-in by design.** This function is NOT called automatically by the
  * runtime; domain handler templates must call `initOtel()` at module
- * scope if they want OTel-exported spans. The `tib doctor` gate
+ * scope if they want OTel-exported spans. The `mc-domain-module doctor` gate
  * (`checkOtelInitInLambdas`) enforces this convention by scanning
  * `domains/.../api/-.ts` for an `initOtel(...)` call.
  *

package/dist/schema/index.d.ts

@@ -1,6 +1,6 @@
 export { z } from 'zod';
 export * from './helpers.js';
-export { tenantIsolationSql, dropTenantIsolationSql, tenantRoleSql } from './rls.js';
+export { tenantIsolationSql, dropTenantIsolationSql, tenantRoleSql, tenantAdminBypassSql, } from './rls.js';
 export type { TenantIsolationOptions } from './rls.js';
 export { generateRlsMigration } from './migration.js';
 export type { RlsMigrationOptions, RlsMigrationTable } from './migration.js';

package/dist/schema/index.js

@@ -1,4 +1,4 @@
 export { z } from 'zod';
 export * from './helpers.js';
-export { tenantIsolationSql, dropTenantIsolationSql, tenantRoleSql } from './rls.js';
+export { tenantIsolationSql, dropTenantIsolationSql, tenantRoleSql, tenantAdminBypassSql, } from './rls.js';
 export { generateRlsMigration } from './migration.js';

package/dist/schema/rls.d.ts

@@ -22,10 +22,41 @@ export interface TenantIsolationOptions {
  * 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.
  */
 export declare function tenantIsolationSql(opts: TenantIsolationOptions): string;
+/**
+ * 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 declare function tenantAdminBypassSql(opts: TenantIsolationOptions): string;
 /**
  * Generate the SQL to drop a tenant isolation policy and disable RLS.
  * Useful for down-migrations.