@mettlecast/domain-cdk-packer 0.2.60 → 0.2.62

package/dist/registry.d.ts

@@ -5,7 +5,7 @@ export type SchemaSnapshot = Record<string, unknown>;
 /**
  * Kind discriminant for registry entries.
  */
-export type RegistryEntryKind = 'api' | 'webhook' | 'subscriber' | 'schedule' | 'job' | 'action' | 'integration' | 'event' | 'domain';
+export type RegistryEntryKind = 'webhook' | 'subscriber' | 'schedule' | 'job' | 'action' | 'integration' | 'event' | 'domain';
 /** Controls whether a VPC-attached handler may use NAT-backed public internet egress. */
 export type RegistryOutboundAccess = 'internal' | 'internet';
 /**
@@ -38,47 +38,6 @@ export interface BaseRegistryEntry {
     /** Optional human-readable description of this primitive. */
     description?: string;
 }
-/**
- * Schema snapshot for a single API version.
- */
-export interface ApiVersionSnapshot {
-    /** Semver-style version string, e.g. '1'. */
-    version: string;
-    /** JSON Schema for the request body of this version. */
-    requestSchema?: SchemaSnapshot;
-    /** JSON Schema for the successful response body of this version. */
-    responseSchema?: SchemaSnapshot;
-}
-/**
- * API registry entry for HTTP endpoint handlers.
- */
-export interface ApiRegistryEntry extends BaseRegistryEntry {
-    /** Discriminant. */
-    kind: 'api';
-    /** Handler file path (required for API). */
-    handlerFile: string;
-    /** HTTP route path, e.g. '/users/:id'. */
-    path: string;
-    /** HTTP method. */
-    method: string;
-    /** Authentication type. */
-    authType: 'jwt' | 'api-key' | 'none';
-    /** Optional deployment overrides. */
-    deployment?: SerialDeploymentConfig;
-    /** Whether this handler may use NAT-backed public internet egress. */
-    outboundAccess?: RegistryOutboundAccess;
-    /** JSON Schema snapshot for the HTTP request body. */
-    requestSchema?: SchemaSnapshot;
-    /** JSON Schema snapshot for the HTTP response body. */
-    responseSchema?: SchemaSnapshot;
-    /** Per-version request/response schema snapshots. */
-    versions?: ApiVersionSnapshot[];
-    /** Example request/response payloads for documentation (no runtime impact). */
-    examples?: {
-        request?: Record<string, unknown>;
-        response?: Record<string, unknown>;
-    };
-}
 /**
  * Webhook registry entry for webhook handlers.
  */
@@ -153,16 +112,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. */
@@ -213,7 +266,7 @@ export interface DomainRegistryEntry extends BaseRegistryEntry {
 /**
  * Union type of all registry entry kinds.
  */
-export type RegistryEntry = ApiRegistryEntry | WebhookRegistryEntry | SubscriberRegistryEntry | ScheduleRegistryEntry | JobRegistryEntry | ActionRegistryEntry | IntegrationRegistryEntry | EventRegistryEntry | DomainRegistryEntry;
+export type RegistryEntry = WebhookRegistryEntry | SubscriberRegistryEntry | ScheduleRegistryEntry | JobRegistryEntry | ActionRegistryEntry | IntegrationRegistryEntry | EventRegistryEntry | DomainRegistryEntry;
 /**
  * Top-level domain registry — the compiled snapshot for CDK packer.
  */
@@ -224,8 +277,6 @@ export interface DomainRegistry {
     domainRoot: string;
     /** The domain itself. */
     domain: DomainRegistryEntry;
-    /** All API endpoints. */
-    apis: ApiRegistryEntry[];
     /** All webhook receivers. */
     webhooks: WebhookRegistryEntry[];
     /** All event subscribers. */

package/package.json

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