@mettlecast/domain-runtime 0.2.59 → 0.2.60

package/dist/runtime/error-formatter.js

@@ -1,4 +1,27 @@
 import { ZodError } from 'zod';
+/**
+ * Stable error codes that domain handlers can throw via `TibError`. The
+ * exposed-action API adapter (`createExposedActionApiHandler`) maps each
+ * of these to a fixed HTTP status — adding a new code without updating
+ * the map will fall through to 500.
+ *
+ * The set is intentionally small: every code here resolves to exactly one
+ * HTTP status, so the contract between runtime and frontend is one-to-one.
+ */
+export const TIB_ERROR_CODES = [
+    'VALIDATION_ERROR',
+    'AUTH_REQUIRED',
+    'FORBIDDEN',
+    'NOT_FOUND',
+    'CONFLICT',
+    'GONE',
+    'UNPROCESSABLE_ENTITY',
+    'INTERNAL_ERROR',
+    'TENANT_REQUIRED',
+    'TENANT_MISMATCH',
+    'NOT_EXPOSED',
+    'OUTPUT_VALIDATION_ERROR',
+];
 /**
  * Formats any caught error into the standard TIB error envelope.
  * Contract locked with frontend scaffolder (#1975).
@@ -26,14 +49,42 @@ export function formatError(err, traceId, logger) {
         logger.error('Unhandled handler error', { err, traceId });
     return { error: 'Internal error', code: 'INTERNAL_ERROR', traceId };
 }
+/**
+ * Domain error thrown by action handlers and adapter internals. Carries a
+ * stable `code` so adapters can render it to a deterministic HTTP status
+ * without parsing the message.
+ *
+ * Handlers should construct one via `domainError(...)` instead of the raw
+ * constructor so the compiler enforces the allowed-code union.
+ *
+ * The previous action-handler pattern — `throw Object.assign(new Error(),
+ * { status: 404 })` — survives end-to-end as long as the throwing code
+ * passes through `executeAction`, which translates `TibError` into an
+ * `ExecuteActionResult` carrying the same code. See
+ * `runtime/action-executor.ts` for the conversion point.
+ */
 export class TibError extends Error {
     code;
+    status;
     constructor(message, code) {
         super(message);
-        this.code = code;
         this.name = 'TibError';
+        this.code = code;
+        this.status = undefined;
     }
 }
+/**
+ * Build a {@link TibError} with a stable, typed code. Domain handlers
+ * import this instead of `new TibError(...)` so the compiler refuses
+ * unknown codes.
+ *
+ * ```ts
+ * throw domainError('User not found', 'NOT_FOUND');
+ * ```
+ */
+export function domainError(message, code) {
+    return new TibError(message, code);
+}
 /**
  * Extracts a trace ID from X-Ray header or X-Request-Id, or generates a fallback.
  */
@@ -49,3 +100,19 @@ export function extractTraceId(headers) {
 function generateId() {
     return `${Date.now().toString(16)}-${Math.random().toString(16).slice(2, 10)}`;
 }
+/**
+ * Best-effort detector for an error object that carries a numeric
+ * `status` property (the legacy pattern that pre-dates {@link TibError}).
+ *
+ * Used by the exposed-action API adapter's outer try/catch to render a
+ * domain-meaningful HTTP status for callers that have not migrated to
+ * {@link domainError} yet. Once all built-in handlers are migrated this
+ * function becomes dead code; until then it acts as the migration safety
+ * net so a runtime upgrade does not regress behaviour.
+ */
+export function readLegacyHttpStatus(err) {
+    if (typeof err !== 'object' || err === null)
+        return undefined;
+    const candidate = err;
+    return typeof candidate.status === 'number' ? candidate.status : undefined;
+}

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

@@ -0,0 +1,88 @@
+/**
+ * Runtime API Gateway adapter for API-exposed actions.
+ *
+ * Wave 3 of #4619 — wraps an `ActionDefinition` whose `exposure.type === 'api'`
+ * into an AWS Lambda HTTP API v2 handler. The adapter is intentionally thin:
+ * it owns the HTTP-shaped concerns (body parsing, status code mapping,
+ * response envelope, DB release) and delegates the action-shaped concerns
+ * (validation, auth/tenancy, idempotency, output validation, audit) to
+ * `executeAction`.
+ *
+ * Mirrors the structure of `createApiLambdaHandler` (api-handler.ts) so the
+ * two adapters stay visually parallel — but trades versioning/sunset/rate
+ * limiting for action-specific concerns (exposure precondition, actor role
+ * claims, output-as-action semantics).
+ *
+ * DB lifecycle: the adapter owns `ctx.db.release()` in a `finally` block, just
+ * like `createApiLambdaHandler`. `executeAction` does not auto-release by
+ * default, so there is no double-release.
+ */
+import type { APIGatewayProxyEventV2WithJWTAuthorizer, APIGatewayProxyStructuredResultV2 } from 'aws-lambda';
+import type { ActionDefinition } from '../primitives/action.js';
+import type { ActionRegistry } from './actions.js';
+/**
+ * Options for `createExposedActionApiHandler`.
+ *
+ * Wave 7 Task 7.1 (#4619): the adapter now accepts the same
+ * plumbing fields that the in-process action proxy uses so that
+ * `ctx.actions` is populated inside the public action handler and
+ * `executeAction` can enforce `backendAccess` against in-handler
+ * action invocations.
+ */
+export interface CreateExposedActionHandlerOptions {
+    /**
+     * Domain ID that owns the action being executed. Forwarded to
+     * `executeAction`'s `meta.definingDomain` so backendAccess enforcement
+     * can tighten once the registry plumbs it through.
+     */
+    definingDomain?: string;
+    /**
+     * The domain ID of THIS running handler. Used as the
+     * `callerDomainId`/`definingDomain` for the ActionsProxy built inside
+     * the handler so that public handlers can call their own (and only
+     * their own) in-domain private actions.
+     */
+    domainId?: string;
+    /**
+     * In-process action registry for the running domain. When provided,
+     * the adapter builds an `ActionsProxy` whose `ctx.actions[domainId]`
+     * namespace contains the public action itself so handlers can do
+     * `ctx.actions[domainId].myAction(input)` without leaving the process.
+     */
+    actionRegistry?: ActionRegistry;
+    /**
+     * Map of `domainId → action Lambda ARN` for cross-domain calls. Same
+     * shape consumed by `createActionsProxy` directly.
+     */
+    lambdaArns?: Record<string, string>;
+    /**
+     * Caller-domain override for the ActionsProxy. Defaults to
+     * `options.domainId` when omitted so generated wrappers do not have
+     * to populate it explicitly.
+     */
+    callerDomainId?: string;
+}
+/**
+ * Wrap an API-exposed `ActionDefinition` into an AWS Lambda HTTP API v2
+ * handler.
+ *
+ * Pipeline:
+ *   1. Extract trace ID from W3C / X-Ray / X-Request-Id headers.
+ *   2. Extract actor and tenant from JWT claims + path params.
+ *   3. Parse request input (body for non-GET/HEAD, query string for GET/HEAD).
+ *   4. Hydrate `ctx` with actor, tenant, DB, event bus, path params.
+ *   5. Call `executeAction(action, parsedInput, ctx, { type: 'api', pathTenantId })`.
+ *   6. Translate the executor result into an HTTP-shaped response.
+ *   7. Release `ctx.db` in `finally` (adapter owns the lifecycle).
+ *
+ * Construction-time validation (`action.exposure.type === 'api'`) runs
+ * before the returned handler closes over any request data, so a misrouted
+ * internal action throws immediately at startup rather than 500-ing on the
+ * first request.
+ *
+ * @param action - The API-exposed action to wrap. Must declare
+ *                 `exposure.type === 'api'`.
+ * @param options - Optional overrides (e.g. definingDomain for audit).
+ * @returns An AWS Lambda HTTP API v2 handler function.
+ */
+export declare function createExposedActionApiHandler(action: ActionDefinition, options?: CreateExposedActionHandlerOptions): (event: APIGatewayProxyEventV2WithJWTAuthorizer) => Promise<APIGatewayProxyStructuredResultV2>;

package/dist/runtime/exposed-action-api-handler.js

@@ -0,0 +1,288 @@
+/**
+ * Runtime API Gateway adapter for API-exposed actions.
+ *
+ * Wave 3 of #4619 — wraps an `ActionDefinition` whose `exposure.type === 'api'`
+ * into an AWS Lambda HTTP API v2 handler. The adapter is intentionally thin:
+ * it owns the HTTP-shaped concerns (body parsing, status code mapping,
+ * response envelope, DB release) and delegates the action-shaped concerns
+ * (validation, auth/tenancy, idempotency, output validation, audit) to
+ * `executeAction`.
+ *
+ * Mirrors the structure of `createApiLambdaHandler` (api-handler.ts) so the
+ * two adapters stay visually parallel — but trades versioning/sunset/rate
+ * limiting for action-specific concerns (exposure precondition, actor role
+ * claims, output-as-action semantics).
+ *
+ * DB lifecycle: the adapter owns `ctx.db.release()` in a `finally` block, just
+ * like `createApiLambdaHandler`. `executeAction` does not auto-release by
+ * default, so there is no double-release.
+ */
+import { hydrateCtx } from './hydrate.js';
+import { extractActorFromApiGatewayEvent, extractTenantFromApiGatewayEvent, } from './extractors.js';
+import { formatError, extractTraceId, TibError, readLegacyHttpStatus } from './error-formatter.js';
+import { executeAction } from './action-executor.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// Construction-time validation
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Throw a configuration error if `action` cannot be wrapped by the API
+ * adapter. Internal-only actions must never be reachable through an HTTP
+ * route — that would silently bypass `backendAccess`.
+ */
+function assertApiExposed(action) {
+    if (action.exposure.type !== 'api') {
+        throw new TibError(`createExposedActionApiHandler: action '${action.id}' has exposure.type '${action.exposure.type}'; only 'api' is supported`, 'INVALID_ACTION_EXPOSURE');
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Body / input parsing
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * HTTP methods whose input must come from the URL query string rather than
+ * the request body. Matches HTTP semantics: GET/HEAD have no semantic body
+ * and proxies commonly strip them.
+ */
+const QUERY_BASED_METHODS = new Set(['GET', 'HEAD']);
+/**
+ * Parse the action input from an API Gateway HTTP API v2 event.
+ *
+ * - Non-GET/HEAD requests: parse `event.body` as JSON. A missing body
+ *   becomes `undefined` (the Zod schema then decides what to do with it).
+ * - GET/HEAD requests: decode `event.rawQueryString` into a flat
+ *   `Record<string, string>` object.
+ *
+ * NOTE (v1 limitation): the GET/HEAD path uses a minimal query decoder.
+ * List-style pagination/filter helpers from `query-parser.ts`
+ * (cursor/limit/sort) are intentionally NOT applied here because action
+ * inputs are typed Zod schemas, not the generic list contract. Callers
+ * wanting pagination over a GET action should declare the relevant fields
+ * on `action.input`.
+ *
+ * @returns Parsed input suitable for `action.input.parse(...)`.
+ * @throws TibError when the body is present but not valid JSON.
+ */
+function parseEventInput(event) {
+    const method = event.requestContext?.http?.method?.toUpperCase() ?? '';
+    if (QUERY_BASED_METHODS.has(method)) {
+        return parseQueryString(event.rawQueryString ?? '');
+    }
+    if (!event.body)
+        return undefined;
+    const raw = event.isBase64Encoded
+        ? Buffer.from(event.body, 'base64').toString('utf8')
+        : event.body;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        // Surface a structured error so the adapter can render a 400 envelope.
+        throw new TibError('Invalid JSON body', 'VALIDATION_ERROR');
+    }
+}
+/**
+ * Decode an `application/x-www-form-urlencoded` style query string into a
+ * flat `Record<string, string>`. Repeated keys collapse to the last value,
+ * matching the behaviour of the standard TIB query-parser helpers.
+ */
+function parseQueryString(raw) {
+    const out = {};
+    if (!raw)
+        return out;
+    for (const part of raw.split('&')) {
+        if (!part)
+            continue;
+        const eq = part.indexOf('=');
+        const key = eq === -1 ? part : part.slice(0, eq);
+        const value = eq === -1 ? '' : part.slice(eq + 1);
+        try {
+            out[decodeURIComponent(key)] = decodeURIComponent(value);
+        }
+        catch {
+            // Skip malformed entries rather than failing the whole request.
+        }
+    }
+    return out;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Actor role extraction
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Extract role claims from the JWT authorizer payload. Returns undefined
+ * when no scopes are attached so `executeAction` interprets the absence as
+ * "no role narrowing evidence" — i.e. the auth check will reject system-
+ * tenancy actions that require specific roles.
+ */
+function extractActorRoles(event) {
+    const scopes = event.requestContext?.authorizer?.jwt?.scopes;
+    if (!Array.isArray(scopes) || scopes.length === 0)
+        return undefined;
+    return scopes.filter((s) => typeof s === 'string');
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Status code mapping
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Map the executor's domain-meaningful error codes to HTTP status codes.
+ *
+ * Centralised so the mapping is documented in one place and easy to audit.
+ * Unknown codes (e.g. custom domain errors) fall through to 500. Codes
+ * listed here MUST exist on `TIB_ERROR_CODES` in `./error-formatter.ts`
+ * so adding a new code requires a paired mapping.
+ */
+function statusForErrorCode(code) {
+    switch (code) {
+        case 'VALIDATION_ERROR':
+            return 400;
+        case 'AUTH_REQUIRED':
+        case 'TENANT_REQUIRED':
+            return 401;
+        case 'FORBIDDEN':
+        case 'TENANT_MISMATCH':
+            return 403;
+        case 'NOT_FOUND':
+        case 'NOT_EXPOSED':
+            return 404;
+        case 'CONFLICT':
+            return 409;
+        case 'GONE':
+            return 410;
+        case 'UNPROCESSABLE_ENTITY':
+            return 422;
+        case 'INTERNAL_ERROR':
+        case 'OUTPUT_VALIDATION_ERROR':
+            return 500;
+        default:
+            return 500;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Factory
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Wrap an API-exposed `ActionDefinition` into an AWS Lambda HTTP API v2
+ * handler.
+ *
+ * Pipeline:
+ *   1. Extract trace ID from W3C / X-Ray / X-Request-Id headers.
+ *   2. Extract actor and tenant from JWT claims + path params.
+ *   3. Parse request input (body for non-GET/HEAD, query string for GET/HEAD).
+ *   4. Hydrate `ctx` with actor, tenant, DB, event bus, path params.
+ *   5. Call `executeAction(action, parsedInput, ctx, { type: 'api', pathTenantId })`.
+ *   6. Translate the executor result into an HTTP-shaped response.
+ *   7. Release `ctx.db` in `finally` (adapter owns the lifecycle).
+ *
+ * Construction-time validation (`action.exposure.type === 'api'`) runs
+ * before the returned handler closes over any request data, so a misrouted
+ * internal action throws immediately at startup rather than 500-ing on the
+ * first request.
+ *
+ * @param action - The API-exposed action to wrap. Must declare
+ *                 `exposure.type === 'api'`.
+ * @param options - Optional overrides (e.g. definingDomain for audit).
+ * @returns An AWS Lambda HTTP API v2 handler function.
+ */
+export function createExposedActionApiHandler(action, options = {}) {
+    assertApiExposed(action);
+    return async (event) => {
+        const responseHeaders = { 'Content-Type': 'application/json' };
+        // 1. Trace ID — prefer W3C traceparent when present.
+        const traceparent = event.headers?.['traceparent'];
+        const traceId = traceparent ?? extractTraceId(event.headers ?? {});
+        // ctx is declared outside the try block so the `finally` clause can
+        // always reach it (it may be unset if hydration itself throws).
+        let ctx;
+        try {
+            // 2. Actor / tenant extraction — uses the same helpers as
+            //    createApiLambdaHandler so JWT/path behaviour stays uniform.
+            const actor = extractActorFromApiGatewayEvent(event);
+            const tenant = extractTenantFromApiGatewayEvent(event);
+            // 3. Input parsing.
+            let parsedInput;
+            try {
+                parsedInput = parseEventInput(event);
+            }
+            catch (err) {
+                return {
+                    statusCode: 400,
+                    headers: responseHeaders,
+                    body: JSON.stringify(formatError(err, traceId)),
+                };
+            }
+            // 4. Hydrate ctx. tenantId is excluded from pathParams because it is
+            //    already surfaced on ctx.tenant.id (and on the executor source).
+            const pathTenantId = event.pathParameters?.tenantId;
+            const { tenantId: _tenantId, ...remainingPathParams } = event.pathParameters ?? {};
+            // Wave 7 Task 7.1 (#4619): forward domain/registry plumbing so
+            // `ctx.actions[domainId].myAction(...)` works inside the handler.
+            // `domainId` is derived from `options.definingDomain` (preferred —
+            // matches what `executeAction` sees) and falls back to the explicit
+            // `options.domainId` for callers that want to distinguish the
+            // "domain that owns the runtime" from "domain that owns the
+            // action being executed". For generated wrappers both values are
+            // typically the same.
+            const proxyDomainId = options.domainId ?? options.definingDomain;
+            const proxyCallerDomainId = options.callerDomainId ?? options.domainId ?? options.definingDomain;
+            ctx = await hydrateCtx(event, {
+                actor,
+                tenant,
+                databaseUrl: process.env['DATABASE_URL'],
+                eventBusName: process.env['EVENT_BUS_NAME'],
+                traceId,
+                pathParams: remainingPathParams,
+                domainId: proxyDomainId,
+                ...(options.actionRegistry ? { actionRegistry: options.actionRegistry } : {}),
+                ...(options.lambdaArns ? { lambdaArns: options.lambdaArns } : {}),
+                ...(proxyCallerDomainId ? { callerDomainId: proxyCallerDomainId } : {}),
+            });
+            const actorRoles = extractActorRoles(event);
+            // 5. Execute the action through the shared pipeline.
+            const result = await executeAction(action, parsedInput, ctx, { type: 'api', pathTenantId, actorRoles }, { definingDomain: options.definingDomain, traceId });
+            // 6. Translate executor result → HTTP response.
+            if (result.ok) {
+                return {
+                    statusCode: 200,
+                    headers: responseHeaders,
+                    body: JSON.stringify(result.value ?? null),
+                };
+            }
+            return {
+                statusCode: statusForErrorCode(result.code),
+                headers: responseHeaders,
+                body: JSON.stringify(formatError(result.error, traceId, ctx.logger)),
+            };
+        }
+        catch (err) {
+            // Truly unexpected throws (e.g. handler threw a non-TibError, or
+            // hydration itself blew up). Render as a 500 using the standard
+            // envelope; ctx.logger may be undefined here so fall back gracefully.
+            //
+            // Legacy status carrier: handlers that still throw the
+            // `Object.assign(new Error(), { status: N })` shape get one free
+            // pass so the runtime upgrade is non-breaking. Once every built-in
+            // handler is migrated to `domainError(...)` this branch becomes
+            // dead code and can be removed.
+            // eslint-disable-next-line no-console
+            console.error('Unhandled exposed-action handler error', err);
+            const legacyStatus = readLegacyHttpStatus(err);
+            return {
+                statusCode: legacyStatus ?? 500,
+                headers: responseHeaders,
+                body: JSON.stringify(formatError(err, traceId, ctx?.logger)),
+            };
+        }
+        finally {
+            // 7. Adapter owns the DB lifecycle. `executeAction` does not release
+            //    by default, so this single release is the only owner. If a
+            //    request throws before hydration completes, ctx is undefined and
+            //    we have nothing to release.
+            if (ctx) {
+                try {
+                    await ctx.db.release();
+                }
+                catch {
+                    /* swallow — release failures are logged at the boundary */
+                }
+            }
+        }
+    };
+}

package/dist/runtime/extractors.d.ts

@@ -4,6 +4,12 @@ import type { Actor, Tenant } from '../types/index.js';
  * Extract the Actor from API Gateway HTTP API v2 event with JWT authorizer.
  * Returns a user actor with claims from the JWT token.
  *
+ * Empty-string claims are treated as missing for the same reason documented
+ * on {@link extractTenantFromApiGatewayEvent} — the Cognito Pre-Token-Generation
+ * Lambda writes empty strings as "no value" placeholders, and the runtime must
+ * not surface a stray empty `sub` or `tenantId` to downstream code that uses
+ * them as map keys or DB identifiers.
+ *
  * @param event - API Gateway HTTP API v2 event with JWT authorizer.
  * @returns Actor extracted from JWT claims.
  */
@@ -14,6 +20,12 @@ export declare function extractActorFromApiGatewayEvent(event: APIGatewayProxyEv
  * workspaceId comes from custom:workspaceId claim or defaults to 'unknown'.
  * orgId comes from custom:orgId claim if present.
  *
+ * Empty-string claims are treated as missing — the Cognito Pre-Token-Generation
+ * Lambda (see `scaffold-src/modules/auth/infra/modules/auth/PreTokenLambda.ts.tpl`)
+ * intentionally writes `custom:orgId: ''` for users with no org membership, and
+ * downstream consumers must not see a stray empty-string ID slip into RLS
+ * bindings or audit logs. The runtime ignores those the same as a missing key.
+ *
  * @param event - API Gateway HTTP API v2 event with JWT authorizer.
  * @returns Tenant extracted from claims and path parameters.
  */

package/dist/runtime/extractors.js

@@ -2,18 +2,23 @@
  * Extract the Actor from API Gateway HTTP API v2 event with JWT authorizer.
  * Returns a user actor with claims from the JWT token.
  *
+ * Empty-string claims are treated as missing for the same reason documented
+ * on {@link extractTenantFromApiGatewayEvent} — the Cognito Pre-Token-Generation
+ * Lambda writes empty strings as "no value" placeholders, and the runtime must
+ * not surface a stray empty `sub` or `tenantId` to downstream code that uses
+ * them as map keys or DB identifiers.
+ *
  * @param event - API Gateway HTTP API v2 event with JWT authorizer.
  * @returns Actor extracted from JWT claims.
  */
 export function extractActorFromApiGatewayEvent(event) {
     const claims = event.requestContext?.authorizer?.jwt?.claims ?? {};
+    const nonEmpty = (v) => typeof v === 'string' && v.length > 0 ? v : undefined;
     return {
         type: 'user',
-        sub: typeof claims.sub === 'string' ? claims.sub : undefined,
-        email: typeof claims.email === 'string' ? claims.email : undefined,
-        tenantId: typeof claims['custom:tenantId'] === 'string'
-            ? claims['custom:tenantId']
-            : undefined,
+        sub: nonEmpty(claims.sub),
+        email: nonEmpty(claims.email),
+        tenantId: nonEmpty(claims['custom:tenantId']),
     };
 }
 /**
@@ -22,19 +27,22 @@ export function extractActorFromApiGatewayEvent(event) {
  * workspaceId comes from custom:workspaceId claim or defaults to 'unknown'.
  * orgId comes from custom:orgId claim if present.
  *
+ * Empty-string claims are treated as missing — the Cognito Pre-Token-Generation
+ * Lambda (see `scaffold-src/modules/auth/infra/modules/auth/PreTokenLambda.ts.tpl`)
+ * intentionally writes `custom:orgId: ''` for users with no org membership, and
+ * downstream consumers must not see a stray empty-string ID slip into RLS
+ * bindings or audit logs. The runtime ignores those the same as a missing key.
+ *
  * @param event - API Gateway HTTP API v2 event with JWT authorizer.
  * @returns Tenant extracted from claims and path parameters.
  */
 export function extractTenantFromApiGatewayEvent(event) {
     const claims = event.requestContext?.authorizer?.jwt?.claims ?? {};
-    const tenantId = (typeof claims['custom:tenantId'] === 'string' ? claims['custom:tenantId'] : undefined)
-        ?? event.pathParameters?.tenantId
+    const nonEmpty = (v) => typeof v === 'string' && v.length > 0 ? v : undefined;
+    const tenantId = nonEmpty(claims['custom:tenantId'])
+        ?? nonEmpty(event.pathParameters?.tenantId)
         ?? 'unknown';
-    const workspaceId = typeof claims['custom:workspaceId'] === 'string'
-        ? claims['custom:workspaceId']
-        : 'unknown';
-    const orgId = typeof claims['custom:orgId'] === 'string'
-        ? claims['custom:orgId']
-        : undefined;
+    const workspaceId = nonEmpty(claims['custom:workspaceId']) ?? 'unknown';
+    const orgId = nonEmpty(claims['custom:orgId']);
     return { id: tenantId, workspaceId, orgId };
 }

package/dist/runtime/files.d.ts

@@ -1,4 +1,12 @@
 import type { DomainFilesContext } from '../ctx/files.js';
+/**
+ * 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 declare function createFiles(opts: {
     bucketName: string;
     tenantId: string;