@mettlecast/domain-cdk-packer 0.2.60 → 0.2.61

package/dist/grouped-lambda-factory.js

@@ -10,7 +10,60 @@ function camelCase(str) {
 function toPascalCase(str) {
     return str.charAt(0).toUpperCase() + camelCase(str).slice(1);
 }
-function generateDedicatedEntry(handlerImportPath, entry, primitiveType) {
+/**
+ * Per-primitive-type default adapter exported from `@mettlecast/domain-runtime`.
+ *
+ * Exported (Wave 7 Task 7.3, #4619) so unit tests can pin the adapter
+ * selection logic without instantiating CDK or esbuild. The mapping here
+ * is the source of truth for the default wrap used by
+ * `buildDedicatedEntryContent`; it does NOT cover the per-entry override
+ * used by API-exposed actions (see `EXPOSED_ACTION_ADAPTER`).
+ */
+export const ADAPTER_BY_PRIMITIVE = {
+    api: 'createApiLambdaHandler',
+    subscriber: 'createSubscriberLambdaHandler',
+    job: 'createJobLambdaHandler',
+    webhook: 'createWebhookLambdaHandler',
+    action: 'createActionLambdaHandler',
+};
+/**
+ * Adapter used for API-exposed actions (Wave 4 Task 4.1, #4619).
+ *
+ * API-exposed actions receive raw HTTP API v2 events, so they must wrap
+ * with `createExposedActionApiHandler` instead of the envelope-based
+ * `createActionLambdaHandler` that internal actions use.
+ *
+ * Exported (Wave 7 Task 7.3) so tests can assert the override behaviour
+ * without depending on the published runtime's barrel.
+ */
+export const EXPOSED_ACTION_ADAPTER = 'createExposedActionApiHandler';
+/**
+ * Pure, side-effect-free entry-content generator for a single dedicated-mode
+ * Lambda handler.
+ *
+ * Returns the TypeScript source string that `NodejsFunction` will bundle.
+ * Exported (Wave 7 Task 7.3, #4619) so unit tests can assert adapter
+ * selection and import wiring without paying the cost of esbuild bundling
+ * on every `DomainStack` synth.
+ *
+ * Note: Wave 7 Task 7.1 may extend this signature with `domainId` (and
+ * rewrite the action-adapter wrappers) so the runtime can plumb
+ * `definingDomain` / `domainId` into the dedicated Lambda. The narrow
+ * tests in `grouped-lambda-factory.test.ts` deliberately target only the
+ * parts that are stable across that change so they keep passing through
+ * the merge.
+ *
+ * @param handlerImportPath  Relative path from the temp entry directory
+ *                           to the handler file. Must already be normalised
+ *                           to start with `./` or `../`.
+ * @param entry              The handler entry whose `id` and `adapter`
+ *                           drive the export name and adapter choice.
+ * @param primitiveType      The primitive type — selects the default
+ *                           adapter when `entry.adapter` is unset, and
+ *                           switches to the `hydrateCtx` envelope for
+ *                           schedules.
+ */
+export function buildDedicatedEntryContent(handlerImportPath, entry, primitiveType, domainId) {
     const exportName = camelCase(entry.id);
     if (primitiveType === 'schedule') {
         return [
@@ -26,14 +79,50 @@ function generateDedicatedEntry(handlerImportPath, entry, primitiveType) {
             `};`,
         ].join('\n');
     }
-    const adapterMap = {
-        api: 'createApiLambdaHandler',
-        subscriber: 'createSubscriberLambdaHandler',
-        job: 'createJobLambdaHandler',
-        webhook: 'createWebhookLambdaHandler',
-        action: 'createActionLambdaHandler',
-    };
-    const adapter = adapterMap[primitiveType] ?? 'createApiLambdaHandler';
+    // Per-handler adapter override (Wave 4 Task 4.1) takes precedence over the
+    // primitive-type default. Used so API-exposed actions wrap with
+    // `createExposedActionApiHandler` while internal actions in the same domain
+    // continue to use `createActionLambdaHandler`.
+    const adapter = entry.adapter ?? ADAPTER_BY_PRIMITIVE[primitiveType] ?? 'createApiLambdaHandler';
+    // Wave 7 Task 7.1 (#4619): the action adapters take a (registry, options)
+    // pair / (action, options) pair, NOT a bare handler export. Generating
+    // `${adapter}(${exportName})` would produce invalid JS for actions — the
+    // bundles were silently broken (esbuild succeeded but the runtime crashed
+    // on first invocation). We now emit the correct wrapper for each adapter:
+    //   * internal action  → `createActionLambdaHandler(registry, options)`
+    //   * api-exposed action → `createExposedActionApiHandler(action, options)`
+    if (primitiveType === 'action' && adapter !== 'createExposedActionApiHandler') {
+        return [
+            `import { createActionLambdaHandler } from '@mettlecast/domain-runtime';`,
+            `import { ${exportName} } from '${handlerImportPath}';`,
+            '',
+            `const registry = { ${JSON.stringify(domainId)}: { ${JSON.stringify(entry.id)}: ${exportName} } };`,
+            '',
+            `export const handler = createActionLambdaHandler(registry, {`,
+            `  domainId: ${JSON.stringify(domainId)},`,
+            `  databaseUrl: process.env.DATABASE_URL,`,
+            `  eventBusName: process.env.EVENT_BUS_NAME,`,
+            `  idempotencyTableName: process.env.IDEMPOTENCY_TABLE,`,
+            `});`,
+        ].join('\n');
+    }
+    if (primitiveType === 'action' && adapter === 'createExposedActionApiHandler') {
+        return [
+            `import { createExposedActionApiHandler } from '@mettlecast/domain-runtime';`,
+            `import { ${exportName} } from '${handlerImportPath}';`,
+            '',
+            // Build a single-action registry so the public handler can call its
+            // own action via `ctx.actions[domainId][actionId]` (Wave 7 Task 7.1).
+            `const actionRegistry = { ${JSON.stringify(domainId)}: { ${JSON.stringify(entry.id)}: ${exportName} } };`,
+            '',
+            `export const handler = createExposedActionApiHandler(${exportName}, {`,
+            `  definingDomain: ${JSON.stringify(domainId)},`,
+            `  domainId: ${JSON.stringify(domainId)},`,
+            `  actionRegistry,`,
+            `  callerDomainId: ${JSON.stringify(domainId)},`,
+            `});`,
+        ].join('\n');
+    }
     return [
         `import { ${adapter} } from '@mettlecast/domain-runtime';`,
         `import { ${exportName} } from '${handlerImportPath}';`,
@@ -76,7 +165,7 @@ export function createGroupedLambdas(scope, props) {
             const entryDir = createTempEntryDir();
             const entryPath = join(entryDir, 'entry.ts');
             const handlerImportPath = relative(entryDir, join(domainRoot, entry.handlerFile)).replace(/\\/g, '/');
-            const entryContent = generateDedicatedEntry(handlerImportPath.startsWith('.') ? handlerImportPath : `./${handlerImportPath}`, entry, props.primitiveType);
+            const entryContent = buildDedicatedEntryContent(handlerImportPath.startsWith('.') ? handlerImportPath : `./${handlerImportPath}`, entry, props.primitiveType, props.domainId);
             writeFileSync(entryPath, entryContent, 'utf8');
             return new lambdaNode.NodejsFunction(scope, `${props.domainId}-${props.primitiveType}${groupSuffix}-${entry.id}`, {
                 runtime: lambda.Runtime.NODEJS_22_X,

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-export type { DomainRegistry, RegistryEntry, RegistryEntryKind, BaseRegistryEntry, SerialDeploymentConfig, ApiRegistryEntry, ApiVersionSnapshot, WebhookRegistryEntry, SubscriberRegistryEntry, ScheduleRegistryEntry, JobRegistryEntry, ActionRegistryEntry, IntegrationRegistryEntry, EventRegistryEntry, DomainRegistryEntry, SchemaSnapshot, } from './registry.js';
+export type { DomainRegistry, RegistryEntry, RegistryEntryKind, BaseRegistryEntry, SerialDeploymentConfig, ApiRegistryEntry, ApiVersionSnapshot, WebhookRegistryEntry, SubscriberRegistryEntry, ScheduleRegistryEntry, JobRegistryEntry, ActionRegistryEntry, ActionBackendAccess, ActionExposure, ActionApiExposure, IntegrationRegistryEntry, EventRegistryEntry, DomainRegistryEntry, SchemaSnapshot, } from './registry.js';
 export { LambdaFactory } from './lambda-factory.js';
 export type { LambdaFactoryProps } from './lambda-factory.js';
-export { createGroupedLambdas } from './grouped-lambda-factory.js';
+export { createGroupedLambdas, buildDedicatedEntryContent, ADAPTER_BY_PRIMITIVE, EXPOSED_ACTION_ADAPTER } from './grouped-lambda-factory.js';
 export type { PrimitiveType, HandlerEntry, GroupedLambdaProps } from './grouped-lambda-factory.js';
 export { IamPolicyBuilder } from './iam/iam-policy-builder.js';
 export type { WebhookPolicyParams, QueuePolicyParams } from './iam/iam-policy-builder.js';

package/dist/index.js

@@ -1,5 +1,5 @@
 export { LambdaFactory } from './lambda-factory.js';
-export { createGroupedLambdas } from './grouped-lambda-factory.js';
+export { createGroupedLambdas, buildDedicatedEntryContent, ADAPTER_BY_PRIMITIVE, EXPOSED_ACTION_ADAPTER } from './grouped-lambda-factory.js';
 export { IamPolicyBuilder } from './iam/iam-policy-builder.js';
 export { ApiConstruct } from './constructs/api-construct.js';
 export { WebhookConstruct } from './constructs/webhook-construct.js';

package/dist/registry.d.ts

@@ -63,6 +63,20 @@ export interface ApiRegistryEntry extends BaseRegistryEntry {
     method: string;
     /** Authentication type. */
     authType: 'jwt' | 'api-key' | 'none';
+    /**
+     * Required for `authType: 'none'` (anonymous) APIs. Carries a free-text
+     * reason that documents the security exception so reviewers can audit
+     * the relaxation. The CDK synth-time aspect and the CLI validator both
+     * refuse to synthesize anonymous APIs without this field.
+     *
+     * Added in #4662 Task D — the legacy `defineApi` surface did not
+     * require a reason because early projects had only a handful of
+     * public routes; that did not scale and the runtime needs the
+     * documentation alongside the route.
+     */
+    securityException?: {
+        reason: string;
+    };
     /** Optional deployment overrides. */
     deployment?: SerialDeploymentConfig;
     /** Whether this handler may use NAT-backed public internet egress. */
@@ -153,16 +167,110 @@ export interface JobRegistryEntry extends BaseRegistryEntry {
     /** Whether this handler may use NAT-backed public internet egress. */
     outboundAccess?: RegistryOutboundAccess;
 }
+/**
+ * Backend invocation permission for an action.
+ *
+ * Controls who can call the action through `ctx.actions` (cross-domain
+ * Lambda invocation or runtime action calls).
+ *
+ * - `private`  = only same-domain/internal generated adapters
+ * - `domain`   = callable by other domains through ctx.actions, subject to policy
+ * - `platform` = callable by system jobs, flows, admin tooling
+ */
+export type ActionBackendAccess = 'private' | 'domain' | 'platform';
+/**
+ * API-exposure metadata for an action.
+ *
+ * Present only when `exposure.type === 'api'`. Carries the route, method,
+ * auth, tenancy, and any required role or documented security exception
+ * that downstream CDK/contract generation needs to wire the route safely.
+ *
+ * The optional `authDeclared` and `tenancyDeclared` flags are populated by
+ * the registry builder to record whether the source code explicitly declared
+ * each field, or whether the builder fell back to the safe default. They are
+ * consumed by the domain CLI's validate command (Wave 6 Task 6.1) to enforce
+ * the action-first security model (#4619).
+ */
+export interface ActionApiExposure {
+    /** Discriminant. */
+    type: 'api';
+    /** HTTP route path, e.g. '/v1/tenants/{tenantId}/billing/invoices'. */
+    path: string;
+    /** HTTP method. One of: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS. */
+    method: string;
+    /** Authentication requirement for the route. */
+    auth: 'required' | 'none' | 'service';
+    /** Tenancy requirement for the route. */
+    tenancy: 'required' | 'none' | 'system';
+    /** Required role(s) for `auth: 'required'` routes (system tenancy requires this). */
+    roles?: string[];
+    /** Documented exception when auth or tenancy is intentionally not required. */
+    securityException?: {
+        reason: string;
+    };
+    /**
+     * True if the source code explicitly declared `auth`. False if the
+     * builder fell back to the safe default (`'required'`). Validation-only.
+     */
+    authDeclared?: boolean;
+    /**
+     * True if the source code explicitly declared `tenancy`. False if the
+     * builder fell back to the safe default (`'required'`). Validation-only.
+     */
+    tenancyDeclared?: boolean;
+}
+/**
+ * Discriminated union of all supported action exposure shapes.
+ *
+ * `internal` actions are not exposed externally; they are reachable only
+ * through `ctx.actions`. `api` actions are exposed via API Gateway and
+ * carry the route + auth metadata needed for safe route generation.
+ */
+export type ActionExposure = ActionApiExposure | {
+    type: 'internal';
+};
 /**
  * Action registry entry for callable domain actions.
+ *
+ * `backendAccess` is the canonical permission field for backend invocation
+ * and replaces the legacy `visibility` field during the
+ * action-first migration (#4619). `visibility` is preserved as an optional
+ * deprecated field so existing CDK constructs continue to compile until
+ * they are updated to consume `backendAccess` directly.
  */
 export interface ActionRegistryEntry extends BaseRegistryEntry {
     /** Discriminant. */
     kind: 'action';
     /** Handler file path (required for action). */
     handlerFile: string;
-    /** Visibility scope: 'private', 'domain', or 'workspace'. */
-    visibility: 'private' | 'domain' | 'workspace';
+    /**
+     * Backend invocation permission for the action.
+     * Replaces legacy `visibility` for the action-first migration.
+     */
+    backendAccess: ActionBackendAccess;
+    /**
+     * External exposure shape for the action. New-style actions must declare
+     * an exposure; legacy actions default to `{ type: 'internal' }` during
+     * migration to preserve existing behavior.
+     */
+    exposure: ActionExposure;
+    /**
+     * True if the source code explicitly declared `exposure`. False (or
+     * omitted) if the builder fell back to the default `{ type: 'internal' }`
+     * because the source did not opt in. Consumed by the domain CLI's
+     * validate command (Wave 6 Task 6.1) to enforce `ACTION_EXPOSURE_REQUIRED`.
+     */
+    exposureDeclared?: boolean;
+    /**
+     * Legacy visibility scope. Retained during the action-first migration so
+     * CDK constructs that still read this field (e.g. action-construct.ts)
+     * keep compiling. New source code should set `backendAccess` instead;
+     * the registry builder maps legacy `visibility` -> `backendAccess` with
+     * `workspace` collapsing to `domain` per the migration spec.
+     *
+     * @deprecated Use `backendAccess` instead.
+     */
+    visibility?: 'private' | 'domain' | 'workspace';
     /** Whether the action enforces idempotency. */
     idempotent: boolean;
     /** Optional deployment overrides. */

package/package.json

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