@mettlecast/domain-cdk-packer 0.2.59 → 0.2.61

package/dist/aspects/security-assertion-aspect.d.ts

@@ -0,0 +1,191 @@
+import * as cdk from 'aws-cdk-lib';
+import { IConstruct } from 'constructs';
+import type { DomainRegistry } from '../registry.js';
+/**
+ * Properties for {@link SecurityAssertionAspect}.
+ *
+ * The aspect reads the `DomainRegistry` exactly once at synthesis time and
+ * then walks every CDK construct for violations. All checks are read-only —
+ * the aspect never modifies the synthesized graph, only emits annotations.
+ *
+ * Issue #4662 Task D — deployment-time assertions. The CLI validator at
+ * `packages/domain-cli` already enforces the same rules against the
+ * `DomainRegistry` before synth, but the aspect is the last line of defence:
+ * it runs even if the CLI was skipped, and it can catch regressions in the
+ * synthesized graph itself (e.g. a route accidentally wired without an
+ * authorizer, or a Lambda exposed via Function URL).
+ */
+export interface SecurityAssertionAspectProps {
+    /** The compiled domain registry — source of truth for what was declared. */
+    registry: DomainRegistry;
+    /**
+     * When true, missing JWT authorizer on a JWT-required route is reported
+     * as a synth-blocking error rather than a warning. Default: true.
+     *
+     * Set to false during the Wave 4 Task 4.1 roll-out so we could ship
+     * fix-ups one stack at a time. New deployments should leave it on.
+     */
+    failOnMissingAuthorizer?: boolean;
+    /**
+     * When true, an API-exposed action whose handler Lambda is reachable
+     * through a `Lambda::Url` resource is a synth-blocking error rather
+     * than a warning. Default: true — Function URLs create public, IAM-
+     * or NONE-authenticated endpoints that bypass API Gateway entirely.
+     */
+    failOnFunctionUrl?: boolean;
+}
+/**
+ * Result codes emitted by the aspect. Mirrored in the CLI validator so
+ * downstream tooling can correlate synth-time annotations with build-time
+ * validation errors. Each code corresponds to a single, narrowly-scoped
+ * invariant — see the per-method docstrings for the exact contract.
+ */
+export declare const SECURITY_ASSERTION_CODES: {
+    /**
+     * A JWT-required route (api.authType='jwt' or action.exposure.auth='required')
+     * was synthesised without an attached `CfnAuthorizer` ID. Synth blocks.
+     */
+    readonly MISSING_JWT_AUTHORIZER: "SECURITY_MISSING_JWT_AUTHORIZER";
+    /**
+     * A tenancy-required route (api requiring a tenant, or action.exposure.tenancy='required')
+     * does not include the canonical tenant placeholder
+     * (`/v1/tenants/{tenantId}/`) in its path. The runtime cannot bind
+     * `ctx.tenant.id` from a path that does not carry the placeholder, so
+     * this would silently produce a tenant-less route. Synth blocks.
+     */
+    readonly MISSING_TENANT_PATH: "SECURITY_MISSING_TENANT_PATH";
+    /**
+     * An action Lambda is reachable through a `Lambda::Url` resource. This
+     * creates a public-or-IAM endpoint that bypasses API Gateway, the JWT
+     * authorizer, and the registry's exposure metadata. Synth blocks.
+     */
+    readonly ACTION_FUNCTION_URL: "SECURITY_ACTION_FUNCTION_URL";
+    /**
+     * An API route is declared `auth: 'none'` or `authType: 'none'` without
+     * a `securityException.reason`. Public routes must document the
+     * exception so security reviewers can audit the relaxation. Synth
+     * blocks — anonymous routes are the exception, not the default.
+     */
+    readonly MISSING_SECURITY_EXCEPTION: "SECURITY_MISSING_SECURITY_EXCEPTION";
+};
+export type SecurityAssertionCode = typeof SECURITY_ASSERTION_CODES[keyof typeof SECURITY_ASSERTION_CODES];
+/**
+ * CDK Aspect that performs deployment-time security assertions against
+ * the synthesised {@link DomainStack}.
+ *
+ * The aspect complements the CLI validator at `packages/domain-cli`. Both
+ * layers run from the same source of truth (`DomainRegistry`), but they
+ * fail at different points in the pipeline:
+ *
+ *   - The CLI validator fails the build BEFORE synth, so the developer
+ *     gets a structured error code in their terminal and CI fails on
+ *     `mc-domain-module validate`.
+ *   - The aspect fails synth AFTER the stack has been assembled. It can
+ *     detect runtime regressions (e.g. a route accidentally synthesised
+ *     without an authorizer because a feature flag silently skipped the
+ *     wiring) that the CLI cannot see.
+ *
+ * Adding the aspect to a stack is a one-liner:
+ *
+ * ```ts
+ * cdk.Aspects.of(stack).add(new SecurityAssertionAspect({ registry }));
+ * ```
+ *
+ * The {@link DomainStack} constructor already wires this aspect in for
+ * every domain, so most code does not need to interact with the class
+ * directly.
+ */
+export declare class SecurityAssertionAspect implements cdk.IAspect {
+    private readonly props;
+    constructor(props: SecurityAssertionAspectProps);
+    /**
+     * CDK calls this for every node in the construct tree. The aspect is
+     * intentionally narrow: it inspects the synthesised graph for the
+     * specific invariants listed above. It does NOT validate the registry
+     * itself — the CLI owns that responsibility and emitting duplicate
+     * errors here would be noisy.
+     *
+     * @param node - The CDK construct being visited.
+     */
+    visit(node: IConstruct): void;
+    /**
+     * Walk every `CfnRoute` in the construct tree and verify the security
+     * invariants in one pass:
+     *
+     * 1. Routes declared as JWT-protected actually carry an `AuthorizerId`.
+     *    Covers both legacy `defineApi` entries (`authType: 'jwt'`) and
+     *    new-style action API exposures (`exposure.auth === 'required'`).
+     * 2. Routes declared as tenant-required include the canonical
+     *    `/v1/tenants/{tenantId}/` placeholder in their path.
+     *
+     * Both checks fail synth by default; the authorizer check can be
+     * downgraded to a warning via {@link SecurityAssertionAspectProps.failOnMissingAuthorizer}
+     * for incremental rollouts.
+     */
+    private assertRouteSecurity;
+    /**
+     * Walk every `CfnUrl` in the construct tree and verify no action
+     * Lambda is reachable through a `Lambda::Url`. Wave 4 Task 4.2 (#4619)
+     * explicitly removed Function URL exposure because the resulting
+     * endpoints bypass API Gateway, the JWT authorizer, and the
+     * `backendAccess` / `exposure` policy gates.
+     *
+     * Health and readiness probes are explicitly exempted — they use
+     * `Lambda::Url` for cheap internal polling and the runtime never
+     * routes tenant traffic through them.
+     */
+    private assertNoFunctionUrls;
+    /**
+     * Walk every `CfnRoute` whose registry counterpart declares
+     * `auth: 'none'` or `authType: 'none'` and verify that the registry
+     * entry carries a `securityException.reason`. Public routes must
+     * document the exception so security reviewers can audit the
+     * relaxation.
+     */
+    private assertAnonymousRoutesHaveException;
+    /**
+     * Find the registry API entry that corresponds to a synthesised route.
+     * DomainStack prefixes every route with `/<domainId>`, so we strip that
+     * prefix before comparing paths.
+     *
+     * @param path - The route path including the domain prefix.
+     * @param method - Upper-case HTTP method.
+     * @returns The matching {@link ApiRegistryEntry} or `undefined`.
+     */
+    private findApiRegistryEntryForRoute;
+    /**
+     * Find the registry action whose `exposure.path` matches a synthesised
+     * route. Mirrors {@link findApiRegistryEntryForRoute} but for action API
+     * exposures.
+     */
+    private findActionRegistryEntryForRoute;
+    /**
+     * Predicate — does the registry entry imply that the route must
+     * include `/v1/tenants/{tenantId}/`?
+     *
+     * The legacy `defineApi` surface does not carry an explicit tenancy
+     * marker; we treat any non-anonymous API as tenant-required because
+     * the only legitimate JWT-protected routes are tenant-scoped. Routes
+     * with `authType: 'none'` are exempted — they are explicitly public.
+     */
+    private registryEntryRequiresTenant;
+    /**
+     * Predicate — does the API registry entry carry a securityException?
+     * Legacy `defineApi` rows do not have this field; we accept the
+     * registry absence and rely on the CLI validator to catch it before
+     * synth.
+     */
+    private hasSecurityException;
+    /**
+     * Predicate — does the action registry entry carry a securityException
+     * on its exposure block?
+     */
+    private hasActionSecurityException;
+    /**
+     * Predicate — does the path contain `/v1/tenants/{tenantId}/`?
+     *
+     * We do not use a regex because the placeholder is a literal string
+     * and the runtime extractor performs an identical literal match.
+     */
+    private hasTenantPlaceholder;
+}

package/dist/aspects/security-assertion-aspect.js

@@ -0,0 +1,297 @@
+import * as cdk from 'aws-cdk-lib';
+import { CfnRoute as Apigwv2CfnRoute } from 'aws-cdk-lib/aws-apigatewayv2';
+import { CfnUrl as LambdaCfnUrl } from 'aws-cdk-lib/aws-lambda';
+/**
+ * Result codes emitted by the aspect. Mirrored in the CLI validator so
+ * downstream tooling can correlate synth-time annotations with build-time
+ * validation errors. Each code corresponds to a single, narrowly-scoped
+ * invariant — see the per-method docstrings for the exact contract.
+ */
+export const SECURITY_ASSERTION_CODES = {
+    /**
+     * A JWT-required route (api.authType='jwt' or action.exposure.auth='required')
+     * was synthesised without an attached `CfnAuthorizer` ID. Synth blocks.
+     */
+    MISSING_JWT_AUTHORIZER: 'SECURITY_MISSING_JWT_AUTHORIZER',
+    /**
+     * A tenancy-required route (api requiring a tenant, or action.exposure.tenancy='required')
+     * does not include the canonical tenant placeholder
+     * (`/v1/tenants/{tenantId}/`) in its path. The runtime cannot bind
+     * `ctx.tenant.id` from a path that does not carry the placeholder, so
+     * this would silently produce a tenant-less route. Synth blocks.
+     */
+    MISSING_TENANT_PATH: 'SECURITY_MISSING_TENANT_PATH',
+    /**
+     * An action Lambda is reachable through a `Lambda::Url` resource. This
+     * creates a public-or-IAM endpoint that bypasses API Gateway, the JWT
+     * authorizer, and the registry's exposure metadata. Synth blocks.
+     */
+    ACTION_FUNCTION_URL: 'SECURITY_ACTION_FUNCTION_URL',
+    /**
+     * An API route is declared `auth: 'none'` or `authType: 'none'` without
+     * a `securityException.reason`. Public routes must document the
+     * exception so security reviewers can audit the relaxation. Synth
+     * blocks — anonymous routes are the exception, not the default.
+     */
+    MISSING_SECURITY_EXCEPTION: 'SECURITY_MISSING_SECURITY_EXCEPTION',
+};
+/**
+ * CDK Aspect that performs deployment-time security assertions against
+ * the synthesised {@link DomainStack}.
+ *
+ * The aspect complements the CLI validator at `packages/domain-cli`. Both
+ * layers run from the same source of truth (`DomainRegistry`), but they
+ * fail at different points in the pipeline:
+ *
+ *   - The CLI validator fails the build BEFORE synth, so the developer
+ *     gets a structured error code in their terminal and CI fails on
+ *     `mc-domain-module validate`.
+ *   - The aspect fails synth AFTER the stack has been assembled. It can
+ *     detect runtime regressions (e.g. a route accidentally synthesised
+ *     without an authorizer because a feature flag silently skipped the
+ *     wiring) that the CLI cannot see.
+ *
+ * Adding the aspect to a stack is a one-liner:
+ *
+ * ```ts
+ * cdk.Aspects.of(stack).add(new SecurityAssertionAspect({ registry }));
+ * ```
+ *
+ * The {@link DomainStack} constructor already wires this aspect in for
+ * every domain, so most code does not need to interact with the class
+ * directly.
+ */
+export class SecurityAssertionAspect {
+    props;
+    constructor(props) {
+        this.props = {
+            registry: props.registry,
+            failOnMissingAuthorizer: props.failOnMissingAuthorizer ?? true,
+            failOnFunctionUrl: props.failOnFunctionUrl ?? true,
+        };
+    }
+    /**
+     * CDK calls this for every node in the construct tree. The aspect is
+     * intentionally narrow: it inspects the synthesised graph for the
+     * specific invariants listed above. It does NOT validate the registry
+     * itself — the CLI owns that responsibility and emitting duplicate
+     * errors here would be noisy.
+     *
+     * @param node - The CDK construct being visited.
+     */
+    visit(node) {
+        this.assertNoFunctionUrls(node);
+        this.assertRouteSecurity(node);
+        this.assertAnonymousRoutesHaveException(node);
+    }
+    /**
+     * Walk every `CfnRoute` in the construct tree and verify the security
+     * invariants in one pass:
+     *
+     * 1. Routes declared as JWT-protected actually carry an `AuthorizerId`.
+     *    Covers both legacy `defineApi` entries (`authType: 'jwt'`) and
+     *    new-style action API exposures (`exposure.auth === 'required'`).
+     * 2. Routes declared as tenant-required include the canonical
+     *    `/v1/tenants/{tenantId}/` placeholder in their path.
+     *
+     * Both checks fail synth by default; the authorizer check can be
+     * downgraded to a warning via {@link SecurityAssertionAspectProps.failOnMissingAuthorizer}
+     * for incremental rollouts.
+     */
+    assertRouteSecurity(node) {
+        if (!(node instanceof Apigwv2CfnRoute))
+            return;
+        // CDK's generated L1 `CfnRoute` keeps the constructor-supplied `routeKey`
+        // on a private field that is not exposed via the public `.d.ts`. We
+        // reach it through a typed bracket cast so we get strong typing on
+        // everything else while still being able to inspect the synthesised
+        // route key during the aspect's visit.
+        const routeKey = node._routeKey ?? '';
+        const spaceIndex = routeKey.indexOf(' ');
+        if (spaceIndex === -1)
+            return;
+        const path = routeKey.slice(spaceIndex + 1);
+        const method = routeKey.slice(0, spaceIndex).toUpperCase();
+        const authorizerId = node.authorizerId;
+        const api = this.findApiRegistryEntryForRoute(path, method);
+        if (api) {
+            // Invariant 1a: JWT-required API has an authorizer
+            if (api.authType === 'jwt' && !authorizerId) {
+                const message = `[SecurityAssertionAspect] ${SECURITY_ASSERTION_CODES.MISSING_JWT_AUTHORIZER}: ` +
+                    `API '${api.id}' declares authType='jwt' but the synthesised route ${routeKey} ` +
+                    `has no AuthorizerId. Provide a Cognito user pool via DomainStackProps.userPoolArn + userPoolClientId.`;
+                if (this.props.failOnMissingAuthorizer) {
+                    cdk.Annotations.of(node).addError(message);
+                }
+                else {
+                    cdk.Annotations.of(node).addWarning(message);
+                }
+            }
+            // Invariant 2: tenant-required API path includes placeholder
+            if (this.registryEntryRequiresTenant(api) && !this.hasTenantPlaceholder(path)) {
+                cdk.Annotations.of(node).addError(`[SecurityAssertionAspect] ${SECURITY_ASSERTION_CODES.MISSING_TENANT_PATH}: ` +
+                    `API '${api.id}' (${method} ${path}) is tenant-required but its path does not include ` +
+                    `the canonical '/v1/tenants/{tenantId}/' placeholder. Synth will fail.`);
+            }
+        }
+        const action = this.findActionRegistryEntryForRoute(path, method);
+        if (action && action.exposure.type === 'api') {
+            const exposure = action.exposure;
+            // Invariant 1b: action with required auth has an authorizer
+            if (exposure.auth === 'required' && !authorizerId) {
+                cdk.Annotations.of(node).addError(`[SecurityAssertionAspect] ${SECURITY_ASSERTION_CODES.MISSING_JWT_AUTHORIZER}: ` +
+                    `Action '${action.id}' declares exposure.auth='required' but the synthesised route ${routeKey} ` +
+                    `has no AuthorizerId. Provide a Cognito user pool via DomainStackProps.userPoolArn + userPoolClientId.`);
+            }
+            // Invariant 2b: action with required tenancy has tenant placeholder
+            if (exposure.tenancy === 'required' && !this.hasTenantPlaceholder(path)) {
+                cdk.Annotations.of(node).addError(`[SecurityAssertionAspect] ${SECURITY_ASSERTION_CODES.MISSING_TENANT_PATH}: ` +
+                    `Action '${action.id}' declares exposure.tenancy='required' but its path (${path}) ` +
+                    `does not include '/v1/tenants/{tenantId}/'. Synth will fail.`);
+            }
+        }
+    }
+    /**
+     * Walk every `CfnUrl` in the construct tree and verify no action
+     * Lambda is reachable through a `Lambda::Url`. Wave 4 Task 4.2 (#4619)
+     * explicitly removed Function URL exposure because the resulting
+     * endpoints bypass API Gateway, the JWT authorizer, and the
+     * `backendAccess` / `exposure` policy gates.
+     *
+     * Health and readiness probes are explicitly exempted — they use
+     * `Lambda::Url` for cheap internal polling and the runtime never
+     * routes tenant traffic through them.
+     */
+    assertNoFunctionUrls(node) {
+        if (!(node instanceof LambdaCfnUrl))
+            return;
+        const targetFn = node.targetFunctionArn
+            ?? node.props?.targetFunction?.functionArn;
+        if (!targetFn)
+            return;
+        // Health & readiness probes have a function name suffix; if the
+        // synthesised target is a recognised health/ready function, skip.
+        // The aspect's intent is to block *tenant-facing* endpoints.
+        const fnName = String(targetFn).split(':').pop() ?? '';
+        if (/health|ready/i.test(fnName))
+            return;
+        cdk.Annotations.of(node).addWarning(`[SecurityAssertionAspect] ${SECURITY_ASSERTION_CODES.ACTION_FUNCTION_URL}: ` +
+            `Lambda::Url attached to '${fnName}'. Function URLs bypass API Gateway and the registry's ` +
+            `exposure policy. Only health/ready probes are permitted to use them; verify the target ` +
+            `function name explicitly.`);
+        if (this.props.failOnFunctionUrl) {
+            cdk.Annotations.of(node).addError(`[SecurityAssertionAspect] ${SECURITY_ASSERTION_CODES.ACTION_FUNCTION_URL}: ` +
+                `Lambda::Url attached to '${fnName}'. Synth will fail. See registry's action.exposure for the canonical route surface.`);
+        }
+    }
+    /**
+     * Walk every `CfnRoute` whose registry counterpart declares
+     * `auth: 'none'` or `authType: 'none'` and verify that the registry
+     * entry carries a `securityException.reason`. Public routes must
+     * document the exception so security reviewers can audit the
+     * relaxation.
+     */
+    assertAnonymousRoutesHaveException(node) {
+        if (!(node instanceof Apigwv2CfnRoute))
+            return;
+        const routeKey = node._routeKey ?? '';
+        const spaceIndex = routeKey.indexOf(' ');
+        if (spaceIndex === -1)
+            return;
+        const path = routeKey.slice(spaceIndex + 1);
+        const method = routeKey.slice(0, spaceIndex).toUpperCase();
+        const api = this.findApiRegistryEntryForRoute(path, method);
+        if (api && api.authType === 'none' && !this.hasSecurityException(api)) {
+            cdk.Annotations.of(node).addError(`[SecurityAssertionAspect] ${SECURITY_ASSERTION_CODES.MISSING_SECURITY_EXCEPTION}: ` +
+                `API '${api.id}' (${method} ${path}) is anonymous (authType='none') but does not declare ` +
+                `a securityException.reason. Public routes must document the exception.`);
+        }
+        const action = this.findActionRegistryEntryForRoute(path, method);
+        if (action
+            && action.exposure.type === 'api'
+            && action.exposure.auth === 'none'
+            && !this.hasActionSecurityException(action)) {
+            cdk.Annotations.of(node).addError(`[SecurityAssertionAspect] ${SECURITY_ASSERTION_CODES.MISSING_SECURITY_EXCEPTION}: ` +
+                `Action '${action.id}' declares exposure.auth='none' but does not declare ` +
+                `exposure.securityException.reason. Public routes must document the exception.`);
+        }
+    }
+    /**
+     * Find the registry API entry that corresponds to a synthesised route.
+     * DomainStack prefixes every route with `/<domainId>`, so we strip that
+     * prefix before comparing paths.
+     *
+     * @param path - The route path including the domain prefix.
+     * @param method - Upper-case HTTP method.
+     * @returns The matching {@link ApiRegistryEntry} or `undefined`.
+     */
+    findApiRegistryEntryForRoute(path, method) {
+        const domainId = this.props.registry.domain.id;
+        if (!path.startsWith(`/${domainId}`))
+            return undefined;
+        const trimmed = path.slice(`/${domainId}`.length) || '/';
+        return this.props.registry.apis.find(api => api.path === trimmed && api.method.toUpperCase() === method);
+    }
+    /**
+     * Find the registry action whose `exposure.path` matches a synthesised
+     * route. Mirrors {@link findApiRegistryEntryForRoute} but for action API
+     * exposures.
+     */
+    findActionRegistryEntryForRoute(path, method) {
+        const domainId = this.props.registry.domain.id;
+        if (!path.startsWith(`/${domainId}`))
+            return undefined;
+        const trimmed = path.slice(`/${domainId}`.length) || '/';
+        return this.props.registry.actions.find(action => {
+            if (action.exposure.type !== 'api')
+                return false;
+            const exposure = action.exposure;
+            return exposure.path === trimmed && exposure.method.toUpperCase() === method;
+        });
+    }
+    /**
+     * Predicate — does the registry entry imply that the route must
+     * include `/v1/tenants/{tenantId}/`?
+     *
+     * The legacy `defineApi` surface does not carry an explicit tenancy
+     * marker; we treat any non-anonymous API as tenant-required because
+     * the only legitimate JWT-protected routes are tenant-scoped. Routes
+     * with `authType: 'none'` are exempted — they are explicitly public.
+     */
+    registryEntryRequiresTenant(api) {
+        if (api.authType === 'none')
+            return false;
+        return true;
+    }
+    /**
+     * Predicate — does the API registry entry carry a securityException?
+     * Legacy `defineApi` rows do not have this field; we accept the
+     * registry absence and rely on the CLI validator to catch it before
+     * synth.
+     */
+    hasSecurityException(api) {
+        const entry = api;
+        const reason = entry.securityException?.reason;
+        return typeof reason === 'string' && reason.trim().length > 0;
+    }
+    /**
+     * Predicate — does the action registry entry carry a securityException
+     * on its exposure block?
+     */
+    hasActionSecurityException(action) {
+        if (action.exposure.type !== 'api')
+            return false;
+        const exposure = action.exposure;
+        const reason = exposure.securityException?.reason;
+        return typeof reason === 'string' && reason.trim().length > 0;
+    }
+    /**
+     * Predicate — does the path contain `/v1/tenants/{tenantId}/`?
+     *
+     * We do not use a regex because the placeholder is a literal string
+     * and the runtime extractor performs an identical literal match.
+     */
+    hasTenantPlaceholder(path) {
+        return path.includes('/v1/tenants/{tenantId}/');
+    }
+}

package/dist/constructs/action-construct.d.ts

@@ -5,6 +5,12 @@ import { IamPolicyBuilder } from '../iam/iam-policy-builder.js';
 import type { DomainRegistry } from '../registry.js';
 /**
  * Configuration properties for ActionConstruct.
+ *
+ * NOTE: Action Lambdas are NEVER exposed directly via Lambda Function URL.
+ * Per Wave 4 Task 4.2 (#4619), `backendAccess` / `exposure` are the canonical
+ * permissions model. External reachability for actions is granted only via
+ * API Gateway routes synthesized from the `exposure` field — never through
+ * an unauthenticated Function URL.
  */
 export interface ActionConstructProps {
     /** Domain registry containing all action entries. */
@@ -13,14 +19,18 @@ export interface ActionConstructProps {
     lambdaFactory: LambdaFactory;
     /** IAM policy builder for granting permissions to Lambda roles. */
     iamBuilder: IamPolicyBuilder;
-    /**
-     * Allowed origins for Function URL CORS on workspace-visible actions.
-     * Defaults to ['*']. Set to specific dashboard URLs + localhost for production.
-     */
-    corsAllowedOrigins?: string[];
 }
 /**
- * CDK Construct that synthesises one Lambda per registered action, with optional Function URL for workspace-visible actions.
+ * CDK Construct that synthesises one Lambda per registered action.
+ *
+ * Action Lambdas are intentionally internal-only. They are invoked by:
+ *   - `ctx.actions` (same-domain or cross-domain) — backed by `lambda:InvokeFunction`
+ *   - API Gateway routes — synthesized by DomainStack from the action's
+ *     `exposure.type === 'api'` metadata.
+ *
+ * They MUST NOT be exposed through Lambda Function URL with `authType: NONE`
+ * because that would create a public, unauthenticated endpoint bypassing
+ * API Gateway auth (JWT / IAM / Lambda authorizer) and tenant scoping.
  */
 export declare class ActionConstruct extends Construct {
     /** Lambda function per action id. */

package/dist/constructs/action-construct.js

@@ -1,7 +1,15 @@
-import * as lambda from 'aws-cdk-lib/aws-lambda';
 import { Construct } from 'constructs';
 /**
- * CDK Construct that synthesises one Lambda per registered action, with optional Function URL for workspace-visible actions.
+ * CDK Construct that synthesises one Lambda per registered action.
+ *
+ * Action Lambdas are intentionally internal-only. They are invoked by:
+ *   - `ctx.actions` (same-domain or cross-domain) — backed by `lambda:InvokeFunction`
+ *   - API Gateway routes — synthesized by DomainStack from the action's
+ *     `exposure.type === 'api'` metadata.
+ *
+ * They MUST NOT be exposed through Lambda Function URL with `authType: NONE`
+ * because that would create a public, unauthenticated endpoint bypassing
+ * API Gateway auth (JWT / IAM / Lambda authorizer) and tenant scoping.
  */
 export class ActionConstruct extends Construct {
     /** Lambda function per action id. */
@@ -21,15 +29,6 @@ export class ActionConstruct extends Construct {
             props.iamBuilder.forAction().forEach((statement) => {
                 fn.addToRolePolicy(statement);
             });
-            if (entry.visibility === 'workspace') {
-                fn.addFunctionUrl({
-                    authType: lambda.FunctionUrlAuthType.NONE,
-                    cors: {
-                        allowedOrigins: props.corsAllowedOrigins ?? ['*'],
-                        allowedMethods: [lambda.HttpMethod.ALL],
-                    },
-                });
-            }
         }
     }
 }

package/dist/grouped-lambda-factory.d.ts

@@ -9,6 +9,27 @@ export interface HandlerEntry {
     id: string;
     /** Path to the handler file relative to the domain's dist directory. */
     handlerFile: string;
+    /**
+     * Optional override for the runtime adapter exported from
+     * `@mettlecast/domain-runtime` that wraps this handler's default export
+     * into a Lambda handler.
+     *
+     * When omitted, the adapter is inferred from `primitiveType`:
+     * - `api`        → `createApiLambdaHandler`
+     * - `subscriber` → `createSubscriberLambdaHandler`
+     * - `job`        → `createJobLambdaHandler`
+     * - `webhook`    → `createWebhookLambdaHandler`
+     * - `action`     → `createActionLambdaHandler`
+     * - `schedule`   → uses the inline `hydrateCtx` envelope (no adapter factory).
+     *
+     * Only honoured in `dedicated: true` mode — grouped mode bundles all
+     * entries behind a single dispatcher and assumes a uniform adapter.
+     *
+     * Wave 4 Task 4.1: API-exposed actions set this to
+     * `'createExposedActionApiHandler'` so their dedicated Lambda receives raw
+     * HTTP API v2 events instead of the action envelope.
+     */
+    adapter?: string;
 }
 /** Props for creating grouped or dedicated Lambdas for a primitive type. */
 export interface GroupedLambdaProps {
@@ -39,6 +60,54 @@ export interface GroupedLambdaProps {
     /** Log retention in days. Default: 30. */
     logRetentionDays?: number;
 }
+/**
+ * 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 declare const ADAPTER_BY_PRIMITIVE: Record<Exclude<PrimitiveType, 'schedule'>, string>;
+/**
+ * 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 declare 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 declare function buildDedicatedEntryContent(handlerImportPath: string, entry: HandlerEntry, primitiveType: PrimitiveType, domainId: string): string;
 /**
  * Creates either a single grouped Lambda (default) or per-handler dedicated Lambdas.
  *