@go-to-k/cdkd 0.114.1 → 0.115.1

package/README.md

@@ -459,8 +459,18 @@ One server per discovered API — authorizers, CORS configs, and stage
 variables stay scoped to the owning API. Supports REST v1 + HTTP API +
 Function URL with AWS_PROXY integrations; Lambda TOKEN / REQUEST,
 Cognito User Pool, and HTTP v2 JWT authorizers (JWKS-verified); CORS
-preflight; hot reload via `--watch`; deploy-state-backed env var
-substitution via `--from-state`.
+preflight (HTTP API v2 `CorsConfiguration` + REST v1 OPTIONS MOCK
+preflight from `defaultCorsPreflightOptions`); hot reload via `--watch`;
+deploy-state-backed env var substitution via `--from-state`.
+
+Routes whose integration cdkd cannot emulate (non-AWS_PROXY REST v1
+types other than the MOCK CORS preflight subset, HTTP API v2 service
+integrations, WebSocket APIs, Function URLs with IAM auth or
+RESPONSE_STREAM, cross-stack Lambda Arn references) **do not block
+boot** — the server starts with a per-route `[warn]` summary and
+returns HTTP 501 + the reason in the JSON body if and when the route is
+hit. This lets you run the rest of your API surface locally while the
+unsupported routes stay on the deployed API.
 
 ### `local run-task`
 

package/dist/cli.js

@@ -38192,7 +38192,7 @@ const INVOKE_ARN_MARKER = ":lambda:path/2015-03-31/functions/";
 * names the surface-level problem (the caller's location prefix +
 * `shortJson` rendering is layered on top). Never throws.
 */
-function resolveLambdaArnIntrinsic$1(value) {
+function resolveLambdaArnIntrinsic(value) {
 	if (!value || typeof value !== "object" || Array.isArray(value)) return {
 		kind: "unsupported",
 		detail: "expected an object intrinsic"
@@ -38319,8 +38319,16 @@ function resolveFnSubInvokeArn(arg) {
 * lambdaLogicalId, stage) tuple is identical — different stacks may
 * legitimately host different APIs that mount the same path.
 *
-* Throws {@link RouteDiscoveryError} on any unsupported shape with every
-* offending route named in a single message.
+* Each route is one of three classes (see {@link DiscoveredRoute}):
+*   - normal (no flag set);
+*   - synthetic CORS preflight (`mockCors` set);
+*   - deferred-error unsupported (`unsupported` set).
+*
+* Throws {@link RouteDiscoveryError} only on template-structural failures
+* the discovery layer cannot generate a meaningful route from (e.g.
+* missing Integration property, ParentId cycle, non-Ref RestApiId). Per-
+* route integration unsupportedness now flows through `unsupported` and
+* is surfaced as HTTP 501 at request time.
 */
 function discoverRoutes(stacks) {
 	const routes = [];
@@ -38345,7 +38353,7 @@ function discoverRoutes(stacks) {
 			errors.push(err instanceof Error ? err.message : String(err));
 		}
 	}
-	if (errors.length > 0) throw new RouteDiscoveryError(`cdkd local start-api: ${errors.length} unsupported route(s) in the synthesized template:\n` + errors.map((e) => `  - ${e}`).join("\n"));
+	if (errors.length > 0) throw new RouteDiscoveryError(`cdkd local start-api: ${errors.length} malformed route(s) in the synthesized template:\n` + errors.map((e) => `  - ${e}`).join("\n"));
 	return routes;
 }
 /**
@@ -38355,8 +38363,18 @@ function discoverRoutes(stacks) {
 * the full path, then looks up the corresponding Stage (when one is
 * attached to the same RestApi) so `requestContext.stage` is realistic.
 *
-* Returns `[]` when the Method's integration is non-AWS_PROXY (e.g. MOCK,
-* AWS, HTTP) — that is a hard error, raised by the caller's catch.
+* Per-integration classification (see {@link DiscoveredRoute}):
+*   - `Integration.Type === 'AWS_PROXY'` → normal route.
+*   - `HttpMethod === 'OPTIONS'` + `Type === 'MOCK'` + `IntegrationResponses`
+*     contain literal `method.response.header.*` mapping params → synthetic
+*     CORS preflight (`mockCors` set). Emulates CDK's
+*     `defaultCorsPreflightOptions` output.
+*   - All other `Integration.Type` values (`MOCK` without CORS shape,
+*     `AWS`, `HTTP`, `HTTP_PROXY`) → unsupported route. The HTTP server
+*     returns 501 when the route is hit; boot proceeds.
+*
+* Hard-errors on template-structural problems (missing Integration,
+* non-Ref RestApiId, ParentId-chain failures).
 *
 * Method.HttpMethod values of `'ANY'` are returned as a single route with
 * `method='ANY'`; the matcher routes any HTTP method to the Lambda.
@@ -38365,10 +38383,6 @@ function discoverRestV1Method(logicalId, resource, template, stackName) {
 	const props = resource.Properties ?? {};
 	const integration = props["Integration"];
 	if (!integration) throw new Error(`${stackName}/${logicalId} (AWS::ApiGateway::Method): missing Integration property`);
-	const integrationType = integration["Type"];
-	if (integrationType !== "AWS_PROXY") throw new Error(`${stackName}/${logicalId} (AWS::ApiGateway::Method): integration type '${String(integrationType)}' is not supported (only AWS_PROXY). MOCK / AWS / HTTP / HTTP_PROXY require mapping templates that cdkd cannot emulate.`);
-	const integrationUri = integration["Uri"];
-	const lambdaLogicalId = resolveLambdaArnIntrinsic(integrationUri, `${stackName}/${logicalId}.Integration.Uri`);
 	const restApiId = props["RestApiId"];
 	const restApiLogicalId = pickRefLogicalId$2(restApiId);
 	if (!restApiLogicalId) throw new Error(`${stackName}/${logicalId} (AWS::ApiGateway::Method): RestApiId must be a { Ref: '...' } reference (got ${shortJson$1(restApiId)}).`);
@@ -38377,10 +38391,7 @@ function discoverRestV1Method(logicalId, resource, template, stackName) {
 	const httpMethod = stringifyValue(props["HttpMethod"] ?? "ANY");
 	const stage = pickRestV1Stage(restApiLogicalId, template);
 	const restApiCdkPath = readApiCdkPath(restApiLogicalId, template);
-	return [{
-		method: httpMethod,
-		pathPattern: path,
-		lambdaLogicalId,
+	const baseRoute = {
 		source: "rest-v1",
 		apiVersion: "v1",
 		stage,
@@ -38388,9 +38399,100 @@ function discoverRestV1Method(logicalId, resource, template, stackName) {
 		apiStackName: stackName,
 		...restApiCdkPath !== void 0 && { apiCdkPath: restApiCdkPath },
 		declaredAt: `${stackName}/${logicalId}`
+	};
+	const integrationType = integration["Type"];
+	if (integrationType === "MOCK") {
+		const preflight = httpMethod === "OPTIONS" ? extractRestV1MockCorsConfig(integration) : void 0;
+		if (preflight) return [{
+			...baseRoute,
+			method: "OPTIONS",
+			pathPattern: path,
+			lambdaLogicalId: "",
+			mockCors: preflight
+		}];
+		return [{
+			...baseRoute,
+			method: httpMethod,
+			pathPattern: path,
+			lambdaLogicalId: "",
+			unsupported: { reason: `${stackName}/${logicalId}: MOCK integration is not emulated (only the CORS preflight subset, where HttpMethod=OPTIONS and IntegrationResponses carry literal method.response.header.* values, is supported).` }
+		}];
+	}
+	if (integrationType !== "AWS_PROXY") return [{
+		...baseRoute,
+		method: httpMethod,
+		pathPattern: path,
+		lambdaLogicalId: "",
+		unsupported: { reason: `${stackName}/${logicalId}: REST v1 integration type '${String(integrationType)}' is not supported (only AWS_PROXY and the MOCK CORS preflight subset).` }
+	}];
+	const integrationUri = integration["Uri"];
+	const arnOutcome = resolveLambdaArnOutcome(integrationUri);
+	if (arnOutcome.kind === "unsupported") return [{
+		...baseRoute,
+		method: httpMethod,
+		pathPattern: path,
+		lambdaLogicalId: "",
+		unsupported: { reason: `${stackName}/${logicalId}.Integration.Uri: ${arnOutcome.detail} (got ${shortJson$1(integrationUri)}). Lambda Arn intrinsics on cross-stack / imported references are not resolvable locally; deploy the producer stack and use \`cdkd local invoke --from-state\` shapes if you need it.` }
+	}];
+	return [{
+		...baseRoute,
+		method: httpMethod,
+		pathPattern: path,
+		lambdaLogicalId: arnOutcome.logicalId
 	}];
 }
 /**
+* Extract the canonical CORS-preflight headers from a REST v1 MOCK
+* Method's `Integration.IntegrationResponses[0]`. Returns `undefined`
+* when the shape isn't a CORS preflight (no IntegrationResponses, no
+* `method.response.header.*` mapping parameters, or any individual
+* mapping parameter we could not evaluate locally — see below).
+*
+* AWS represents header literals in `ResponseParameters` with surrounding
+* single-quotes (e.g. `"'*'"` for `*`). The single-quote wrappers are
+* stripped to produce the canonical header value the local server emits.
+*
+* **All-or-nothing**: if any `method.response.header.*` entry is
+* intrinsic-valued (`Fn::Sub`, `Ref` etc.), unquoted, or otherwise
+* not a string-literal-with-quotes, the WHOLE preflight falls through
+* to the unsupported class. Emitting a partial preflight with some
+* headers missing would silently break CORS in the browser (the
+* preflight succeeds, then the actual request hits a CORS error the
+* user has to debug through Network panel) — caller's the better
+* place to surface the underlying VTL-requirement via the 501 path.
+*
+* Only the first `IntegrationResponses` entry is consulted. CDK's
+* `defaultCorsPreflightOptions` emits exactly one entry; hand-rolled
+* multi-status MOCK preflights are an unsupported v1 limitation.
+*/
+function extractRestV1MockCorsConfig(integration) {
+	const responses = integration["IntegrationResponses"];
+	if (!Array.isArray(responses) || responses.length === 0) return void 0;
+	const first = responses[0];
+	if (!first || typeof first !== "object") return void 0;
+	const entry = first;
+	const responseParameters = entry["ResponseParameters"];
+	if (!responseParameters || typeof responseParameters !== "object" || Array.isArray(responseParameters)) return;
+	const headers = {};
+	let sawAnyHeader = false;
+	for (const [key, raw] of Object.entries(responseParameters)) {
+		const m = /^method\.response\.header\.(.+)$/.exec(key);
+		if (!m) continue;
+		sawAnyHeader = true;
+		const headerName = m[1];
+		if (typeof raw !== "string") return void 0;
+		if (raw.length < 2 || raw[0] !== "'" || raw[raw.length - 1] !== "'") return void 0;
+		headers[headerName] = raw.slice(1, -1);
+	}
+	if (!sawAnyHeader) return void 0;
+	const statusCodeRaw = entry["StatusCode"];
+	const parsed = typeof statusCodeRaw === "string" ? Number.parseInt(statusCodeRaw, 10) : NaN;
+	return {
+		statusCode: Number.isFinite(parsed) ? parsed : 204,
+		headers
+	};
+}
+/**
 * Walk a chain of `AWS::ApiGateway::Resource` parent pointers up to the
 * `RestApi` root to build the full path. Each `Resource` contributes a
 * `PathPart` segment; the `RestApi` itself contributes the leading `/`.
@@ -38462,27 +38564,29 @@ function discoverHttpApiRoute(logicalId, resource, template, stackName) {
 	const apiId = props["ApiId"];
 	const apiLogicalId = pickRefLogicalId$2(apiId);
 	if (!apiLogicalId) throw new Error(`${stackName}/${logicalId} (AWS::ApiGatewayV2::Route): ApiId must be { Ref: '...' } (got ${shortJson$1(apiId)}).`);
+	const routeKey = props["RouteKey"];
+	if (typeof routeKey !== "string" || routeKey.length === 0) throw new Error(`${stackName}/${logicalId} (AWS::ApiGatewayV2::Route): RouteKey must be a string`);
+	const apiCdkPath = readApiCdkPath(apiLogicalId, template);
 	const apiResource = template.Resources?.[apiLogicalId];
 	if (apiResource?.Type === "AWS::ApiGatewayV2::Api") {
-		if ((apiResource.Properties ?? {})["ProtocolType"] === "WEBSOCKET") throw new Error(`${stackName}/${logicalId} (AWS::ApiGatewayV2::Route): WebSocket APIs are not supported in cdkd local start-api (deferred follow-up PR).`);
+		if ((apiResource.Properties ?? {})["ProtocolType"] === "WEBSOCKET") return [{
+			method: "ANY",
+			pathPattern: routeKey,
+			lambdaLogicalId: "",
+			source: "http-api",
+			apiVersion: "v2",
+			stage: "$default",
+			apiLogicalId,
+			apiStackName: stackName,
+			...apiCdkPath !== void 0 && { apiCdkPath },
+			declaredAt: `${stackName}/${logicalId}`,
+			unsupported: { reason: `${stackName}/${logicalId}: WebSocket APIs are not supported in cdkd local start-api.` }
+		}];
 	}
-	const routeKey = props["RouteKey"];
-	if (typeof routeKey !== "string" || routeKey.length === 0) throw new Error(`${stackName}/${logicalId} (AWS::ApiGatewayV2::Route): RouteKey must be a string`);
-	const target = props["Target"];
-	const integrationLogicalId = parseHttpApiTargetIntegration(target, `${stackName}/${logicalId}.Target`);
-	const integration = template.Resources?.[integrationLogicalId];
-	if (!integration || integration.Type !== "AWS::ApiGatewayV2::Integration") throw new Error(`${stackName}/${logicalId} (AWS::ApiGatewayV2::Route): Target points at '${integrationLogicalId}' which is not an AWS::ApiGatewayV2::Integration`);
-	const integrationProps = integration.Properties ?? {};
-	const integrationType = integrationProps["IntegrationType"];
-	if (integrationType !== "AWS_PROXY") throw new Error(`${stackName}/${logicalId} (AWS::ApiGatewayV2::Route): integration type '${String(integrationType)}' is not supported (only AWS_PROXY).`);
-	if (integrationProps["IntegrationSubtype"] !== void 0) throw new Error(`${stackName}/${logicalId} (AWS::ApiGatewayV2::Route): IntegrationSubtype '${stringifyValue(integrationProps["IntegrationSubtype"])}' is not supported (ApiGatewayV2 service integrations like SQS/EventBridge cannot run locally).`);
-	const lambdaLogicalId = resolveLambdaArnIntrinsic(integrationProps["IntegrationUri"], `${stackName}/${integrationLogicalId}.IntegrationUri`);
 	const { method, pathPattern } = parseRouteKey(routeKey);
-	const apiCdkPath = readApiCdkPath(apiLogicalId, template);
-	return [{
+	const baseRoute = {
 		method,
 		pathPattern,
-		lambdaLogicalId,
 		source: "http-api",
 		apiVersion: "v2",
 		stage: "$default",
@@ -38490,35 +38594,82 @@ function discoverHttpApiRoute(logicalId, resource, template, stackName) {
 		apiStackName: stackName,
 		...apiCdkPath !== void 0 && { apiCdkPath },
 		declaredAt: `${stackName}/${logicalId}`
+	};
+	const target = props["Target"];
+	const integrationLogicalId = parseHttpApiTargetIntegration(target, `${stackName}/${logicalId}.Target`);
+	const integration = template.Resources?.[integrationLogicalId];
+	if (!integration || integration.Type !== "AWS::ApiGatewayV2::Integration") throw new Error(`${stackName}/${logicalId} (AWS::ApiGatewayV2::Route): Target points at '${integrationLogicalId}' which is not an AWS::ApiGatewayV2::Integration`);
+	const integrationProps = integration.Properties ?? {};
+	const integrationType = integrationProps["IntegrationType"];
+	if (integrationType !== "AWS_PROXY") return [{
+		...baseRoute,
+		lambdaLogicalId: "",
+		unsupported: { reason: `${stackName}/${logicalId}: HTTP API v2 integration type '${String(integrationType)}' is not supported (only AWS_PROXY).` }
+	}];
+	if (integrationProps["IntegrationSubtype"] !== void 0) return [{
+		...baseRoute,
+		lambdaLogicalId: "",
+		unsupported: { reason: `${stackName}/${logicalId}: HTTP API v2 service integration with IntegrationSubtype '${stringifyValue(integrationProps["IntegrationSubtype"])}' is not supported (cdkd cannot proxy directly to SQS / EventBridge / etc.).` }
+	}];
+	const arnOutcome = resolveLambdaArnOutcome(integrationProps["IntegrationUri"]);
+	if (arnOutcome.kind === "unsupported") return [{
+		...baseRoute,
+		lambdaLogicalId: "",
+		unsupported: { reason: `${stackName}/${integrationLogicalId}.IntegrationUri: ${arnOutcome.detail} (got ${shortJson$1(integrationProps["IntegrationUri"])}). Lambda Arn intrinsics on cross-stack / imported references are not resolvable locally.` }
+	}];
+	return [{
+		...baseRoute,
+		lambdaLogicalId: arnOutcome.logicalId
 	}];
 }
 /**
 * Discover the synthetic `ANY /{proxy+}` route from an
 * `AWS::Lambda::Url` resource.
 *
-* C12: keep only `AuthType === 'NONE' && InvokeMode !== 'RESPONSE_STREAM'`.
-* Other shapes hard-fail at discovery — IAM auth needs SigV4 verification
-* we cannot do locally, and RESPONSE_STREAM uses a streaming response shape
-* (`InvokeWithResponseStream`) the RIE container does not implement.
+* Per-shape classification:
+*   - `AuthType === 'NONE'` + `InvokeMode !== 'RESPONSE_STREAM'` → normal route.
+*   - `AuthType !== 'NONE'` (e.g. `AWS_IAM`) → deferred-error
+*     unsupported. Boot proceeds; HTTP 501 + `reason` at request time.
+*     IAM auth would need SigV4 verification cdkd cannot emulate.
+*   - `InvokeMode === 'RESPONSE_STREAM'` → deferred-error unsupported.
+*     The RIE container does not implement `InvokeWithResponseStream`.
+*
+* The Lambda Arn intrinsic resolution still **hard-errors** when it
+* cannot pin down a same-template Lambda — Function URLs have no other
+* identifying info (no RouteKey / RestApi parent), so the route would
+* be uninformative as a deferred-501 entry.
 */
 function discoverFunctionUrl(logicalId, resource, template, stackName) {
 	const props = resource.Properties ?? {};
-	const authType = props["AuthType"];
-	if (authType !== "NONE") throw new Error(`${stackName}/${logicalId} (AWS::Lambda::Url): AuthType '${String(authType)}' is not supported (only NONE — IAM auth requires SigV4 verification cdkd cannot emulate locally; deferred follow-up PR).`);
-	if (props["InvokeMode"] === "RESPONSE_STREAM") throw new Error(`${stackName}/${logicalId} (AWS::Lambda::Url): InvokeMode RESPONSE_STREAM is not supported (deferred follow-up PR).`);
 	const targetArn = props["TargetFunctionArn"];
-	const lambdaLogicalId = resolveLambdaArnIntrinsic(targetArn, `${stackName}/${logicalId}.TargetFunctionArn`);
+	const arnOutcome = resolveLambdaArnOutcome(targetArn);
+	if (arnOutcome.kind === "unsupported") throw new Error(`${stackName}/${logicalId}.TargetFunctionArn: ${arnOutcome.detail} (got ${shortJson$1(targetArn)}).`);
+	const lambdaLogicalId = arnOutcome.logicalId;
 	const lambdaCdkPath = readApiCdkPath(lambdaLogicalId, template);
-	return [{
+	const baseRoute = {
 		method: "ANY",
 		pathPattern: "/{proxy+}",
-		lambdaLogicalId,
 		source: "function-url",
 		apiVersion: "v2",
 		stage: "$default",
 		apiStackName: stackName,
 		...lambdaCdkPath !== void 0 && { apiCdkPath: lambdaCdkPath },
 		declaredAt: `${stackName}/${logicalId}`
+	};
+	const authType = props["AuthType"];
+	if (authType !== "NONE") return [{
+		...baseRoute,
+		lambdaLogicalId,
+		unsupported: { reason: `${stackName}/${logicalId}: AuthType '${String(authType)}' is not supported (only NONE — IAM auth requires SigV4 verification cdkd cannot emulate locally).` }
+	}];
+	if (props["InvokeMode"] === "RESPONSE_STREAM") return [{
+		...baseRoute,
+		lambdaLogicalId,
+		unsupported: { reason: `${stackName}/${logicalId}: InvokeMode RESPONSE_STREAM is not supported (cdkd's RIE container does not implement InvokeWithResponseStream).` }
+	}];
+	return [{
+		...baseRoute,
+		lambdaLogicalId
 	}];
 }
 /**
@@ -38541,13 +38692,11 @@ function readApiCdkPath(logicalId, template) {
 * invoke-ARN `Fn::Join` wrapper / the `Fn::Sub` invoke-ARN wrapper (both
 * 1-arg and 2-arg forms).
 *
-* Any other shape hard-errors with the offending route + raw intrinsic
-* named, preserving the pre-extraction error message intent ("requires
-* deploy-state and is not supported in cdkd local start-api"). The
-* shared helper returns a discriminated union so the caller wraps the
-* unsupported case with its own error class; this site uses bare `Error`
-* so the top-level catch in `discoverRoutes` re-wraps it as
-* `RouteDiscoveryError` along with sibling errors.
+* Non-throwing: returns the shared resolver's discriminated union
+* unchanged so each call site can decide whether to surface the
+* unsupported case as a per-route `unsupported` flag (the new default)
+* or as a hard error (Function URLs, which lack route-level identity
+* without their Lambda).
 *
 * **Why we don't reuse `src/deployment/intrinsic-function-resolver.ts`**:
 * that resolver is deploy-state-coupled — it pulls in STS / EC2 / Secrets
@@ -38555,10 +38704,8 @@ function readApiCdkPath(logicalId, template) {
 * `cdkd local start-api` runs purely against the synthesized template
 * and doesn't have any of that.
 */
-function resolveLambdaArnIntrinsic(value, location) {
-	const outcome = resolveLambdaArnIntrinsic$1(value);
-	if (outcome.kind === "resolved") return outcome.logicalId;
-	throw new Error(`${location}: ${outcome.detail} (got ${shortJson$1(value)}). Only { Ref: <LambdaLogicalId> }, { 'Fn::GetAtt': [<LambdaLogicalId>, 'Arn'] }, the REST v1 invoke-ARN Fn::Join wrapper, and the Fn::Sub invoke-ARN wrapper are supported. Other intrinsics (Fn::Sub against arbitrary templates, etc.) require deploy-state and are not supported in cdkd local start-api.`);
+function resolveLambdaArnOutcome(value) {
+	return resolveLambdaArnIntrinsic(value);
 }
 /**
 * Parse an HTTP API Route's `Target` into the integration's logical ID.
@@ -39840,19 +39987,52 @@ function resolveHttpApiAuthorizer(authorizerLogicalId, routeAuthorizationScopes,
 	throw new RouteDiscoveryError(`${stackName}/${authorizerLogicalId}: AWS::ApiGatewayV2::Authorizer.AuthorizerType '${String(authType)}' is not supported by cdkd local start-api (only REQUEST / JWT).`);
 }
 /**
+* Thrown by {@link resolveLambdaArn} when the authorizer's
+* `AuthorizerUri` intrinsic does not resolve to a same-template Lambda
+* (cross-stack reference, imported Lambda, hand-rolled `Fn::Sub` outside
+* the invoke-ARN wrapper).
+*
+* Caught by {@link attachAuthorizers} and converted into a per-route
+* `unsupported` flag — symmetric with how `route-discovery.ts` handles
+* an unresolvable `IntegrationUri`. The route appears in the route
+* table as `[501 Not Implemented]` and returns HTTP 501 + the
+* `reason` at request time. The alternative ("attach no authorizer,
+* leave route normal") would be **unsafe** — it would let a request
+* hit a user-protected route without any auth check just because the
+* authorizer Lambda lives in another stack.
+*
+* Private to this module: `attachAuthorizers` is the only legitimate
+* consumer.
+*/
+var AuthorizerLambdaUnresolvableError = class AuthorizerLambdaUnresolvableError extends RouteDiscoveryError {
+	reason;
+	constructor(reason) {
+		super(reason);
+		this.reason = reason;
+		this.name = "AuthorizerLambdaUnresolvableError";
+		Object.setPrototypeOf(this, AuthorizerLambdaUnresolvableError.prototype);
+	}
+};
+/**
 * Resolve a Lambda ARN intrinsic to its logical ID. Delegates to the
 * shared `resolveLambdaArnIntrinsic` in `intrinsic-lambda-arn.ts`
 * (extracted in issue #286 Gaps 3 / 4); accepts `Ref` /
 * `Fn::GetAtt: [..., 'Arn']` / the REST v1 invoke-ARN `Fn::Join` wrapper
 * (now also used by CDK 2.x's `HttpLambdaAuthorizer` for HTTP API v2 —
 * verified via real `cdk synth` 2026-05-12) / the `Fn::Sub` invoke-ARN
-* wrapper (both 1-arg and 2-arg forms). Any other shape hard-errors with
-* the offending route + raw intrinsic named.
+* wrapper (both 1-arg and 2-arg forms).
+*
+* On an unresolvable intrinsic throws {@link AuthorizerLambdaUnresolvableError}
+* (caught by `attachAuthorizers` and converted into a per-route
+* deferred-501) instead of the generic `RouteDiscoveryError`, so
+* `cdkd local start-api` can boot against an app with a cross-stack
+* authorizer Lambda — symmetric with the route-level `IntegrationUri`
+* unresolvable case (issue #431).
 */
 function resolveLambdaArn(value, location) {
-	const outcome = resolveLambdaArnIntrinsic$1(value);
+	const outcome = resolveLambdaArnIntrinsic(value);
 	if (outcome.kind === "resolved") return outcome.logicalId;
-	throw new RouteDiscoveryError(`${location}: ${outcome.detail} (got ${shortJson(value)}). Only { Ref }, { Fn::GetAtt: [..., 'Arn'] }, the REST v1 invoke-ARN Fn::Join wrapper, and the Fn::Sub invoke-ARN wrapper are supported.`);
+	throw new AuthorizerLambdaUnresolvableError(`${location}: ${outcome.detail} (got ${shortJson(value)}). Only { Ref }, { Fn::GetAtt: [..., 'Arn'] }, the REST v1 invoke-ARN Fn::Join wrapper, and the Fn::Sub invoke-ARN wrapper are supported.`);
 }
 /**
 * REST v1 IdentitySource for TOKEN authorizers must be exactly one
@@ -40024,6 +40204,10 @@ function attachAuthorizers(stacks, routes) {
 	const out = [];
 	const errors = [];
 	for (const route of routes) {
+		if (route.unsupported || route.mockCors) {
+			out.push({ route });
+			continue;
+		}
 		const stack = stackByRoute.get(route.declaredAt);
 		if (!stack) {
 			out.push({ route });
@@ -40036,6 +40220,13 @@ function attachAuthorizers(stacks, routes) {
 				...authorizer && { authorizer }
 			});
 		} catch (err) {
+			if (err instanceof AuthorizerLambdaUnresolvableError) {
+				out.push({ route: {
+					...route,
+					unsupported: { reason: `${route.declaredAt}: authorizer Lambda Arn unresolvable — ${err.reason}` }
+				} });
+				continue;
+			}
 			errors.push(err instanceof Error ? err.message : String(err));
 		}
 	}
@@ -40778,6 +40969,14 @@ async function handleRequest(req, res, state, opts) {
 		writeError(res, 404, "{\"message\":\"Not Found\"}");
 		return;
 	}
+	if (match.route.mockCors) {
+		writeMockCorsPreflight(res, match.route.mockCors);
+		return;
+	}
+	if (match.route.unsupported) {
+		writeNotImplemented(res, match.route.unsupported.reason);
+		return;
+	}
 	const authorizer = state.routes.find((r) => r.route.declaredAt === match.route.declaredAt && r.route.method === match.route.method)?.authorizer;
 	const snapshot = {
 		method,
@@ -41191,6 +41390,35 @@ function writeError(res, statusCode, body = "{\"message\":\"Internal server erro
 	res.setHeader("content-length", String(Buffer.byteLength(body, "utf-8")));
 	res.end(body);
 }
+/**
+* Write the 501 Not Implemented response surfaced for routes the
+* discovery layer flagged as `unsupported`. The integration's reason
+* (e.g. "MOCK integration is not emulated", "WebSocket APIs are not
+* supported") is echoed in the body so the user gets a precise pointer
+* at first hit instead of a generic 502.
+*/
+function writeNotImplemented(res, reason) {
+	const body = JSON.stringify({
+		message: "Not Implemented",
+		reason
+	});
+	res.statusCode = 501;
+	res.setHeader("content-type", "application/json");
+	res.setHeader("content-length", String(Buffer.byteLength(body, "utf-8")));
+	res.end(body);
+}
+/**
+* Write the canonical CORS preflight response derived from a REST v1
+* MOCK Method's `Integration.IntegrationResponses[0].ResponseParameters`.
+* Headers are emitted verbatim — the discovery layer already stripped
+* AWS's literal single-quote wrappers and dropped any non-literal
+* (intrinsic-valued) entries.
+*/
+function writeMockCorsPreflight(res, preflight) {
+	res.statusCode = preflight.statusCode;
+	for (const [name, value] of Object.entries(preflight.headers)) res.setHeader(name, value);
+	res.end();
+}
 
 //#endregion
 //#region src/local/api-server-grouping.ts
@@ -41817,6 +42045,7 @@ async function localStartApiCommand(target, options) {
 		if (basePort !== 0) nextPort += 1;
 	}
 	printPerServerRouteTables(servers);
+	warnUnsupportedRoutes(servers.flatMap((s) => s.group.routes.map((r) => r.route)), logger);
 	logger.info(`Per-Lambda concurrency: ${perLambdaConcurrency} (override with --per-lambda-concurrency)`);
 	for (const { group, server } of servers) process.stdout.write(`Server listening on http://${server.host}:${server.port}  (${group.displayName})\n`);
 	process.stdout.write("^C to stop and clean up containers.\n");
@@ -41935,11 +42164,16 @@ function pickTargetStacks(stacks, pattern) {
 function uniqueLambdaIds(routes, routesWithAuth) {
 	const seen = /* @__PURE__ */ new Set();
 	const out = [];
-	for (const r of routes) if (!seen.has(r.lambdaLogicalId)) {
-		seen.add(r.lambdaLogicalId);
-		out.push(r.lambdaLogicalId);
+	for (const r of routes) {
+		if (r.unsupported || r.mockCors) continue;
+		if (r.lambdaLogicalId.length === 0) continue;
+		if (!seen.has(r.lambdaLogicalId)) {
+			seen.add(r.lambdaLogicalId);
+			out.push(r.lambdaLogicalId);
+		}
 	}
 	for (const entry of routesWithAuth) {
+		if (entry.route.unsupported || entry.route.mockCors) continue;
 		const auth = entry.authorizer;
 		if (!auth) continue;
 		if (auth.kind === "lambda-token" || auth.kind === "lambda-request") {
@@ -42138,6 +42372,13 @@ function resolveAssetCodePath(stack, logicalId, resource) {
 /**
 * Print the discovered route table to stdout. Format mirrors the spec
 * doc's example so verify.sh / users can read it at a glance.
+*
+* Routes with `unsupported` or `mockCors` are annotated so the user can
+* tell at a glance which routes will dispatch to a Lambda vs which
+* return 501 / 204 directly:
+*   - normal:        `GET /items -> Handler  (HTTP API)`
+*   - mockCors:      `OPTIONS /items -> [MOCK CORS preflight]  (REST v1, stage 'prod')`
+*   - unsupported:   `POST /admin -> [501 Not Implemented]  (HTTP API)`
 */
 function printRouteTable(routes) {
 	const sorted = [...routes.map((r) => r.route)].sort((a, b) => {
@@ -42149,7 +42390,8 @@ function printRouteTable(routes) {
 	process.stdout.write("Discovered routes:\n");
 	for (const r of sorted) {
 		const sourceLabel = r.source === "http-api" ? "HTTP API" : r.source === "rest-v1" ? `REST v1, stage '${r.stage}'` : "Function URL";
-		process.stdout.write(`  ${r.method.padEnd(methodWidth)}  ${r.pathPattern.padEnd(pathWidth)}  -> ${r.lambdaLogicalId}  (${sourceLabel})\n`);
+		const target = r.mockCors ? "[MOCK CORS preflight]" : r.unsupported ? "[501 Not Implemented]" : r.lambdaLogicalId;
+		process.stdout.write(`  ${r.method.padEnd(methodWidth)}  ${r.pathPattern.padEnd(pathWidth)}  -> ${target}  (${sourceLabel})\n`);
 	}
 	process.stdout.write("\n");
 }
@@ -42292,6 +42534,21 @@ function printPerServerRouteTables(servers) {
 	}
 }
 /**
+* Surface every `unsupported` route (deferred 501) as a startup warn so
+* the user sees what isn't reachable BEFORE they try to curl it. One
+* warn line per route — the route's `unsupported.reason` already names
+* the offender + the underlying limitation, so we just prefix with
+* method + path. Returns the number of unsupported routes so the caller
+* can emit a single-line summary header above the list.
+*/
+function warnUnsupportedRoutes(routes, logger) {
+	const unsupported = routes.filter((r) => r.unsupported);
+	if (unsupported.length === 0) return 0;
+	logger.warn(`${unsupported.length} route(s) will respond HTTP 501 Not Implemented when hit (boot continued):`);
+	for (const r of unsupported) logger.warn(`  - ${r.method} ${r.pathPattern}: ${r.unsupported.reason}`);
+	return unsupported.length;
+}
+/**
 * One reload cycle for the multi-server topology (issue #260). The
 * watcher serializes calls via a chain promise; this function:
 *
@@ -42331,13 +42588,16 @@ async function reloadAllServers(args) {
 			pool: newPool,
 			corsConfigByApiId: material.corsConfigByApiId
 		};
-		booted.server.setServerState(newState).pool.dispose().catch((err) => {
+		const previousState = booted.server.setServerState(newState);
+		booted.group = group;
+		previousState.pool.dispose().catch((err) => {
 			logger.debug(`Previous pool dispose() failed for ${group.displayName}: ${err instanceof Error ? err.message : String(err)}`);
 		});
 	}
 	lastAssetPaths.value = computeAssetPaths(material.specs);
 	if (watcher) watcher.update([output, ...lastAssetPaths.value]);
 	printPerServerRouteTables(servers);
+	warnUnsupportedRoutes(servers.flatMap((s) => s.group.routes.map((r) => r.route)), logger);
 }
 /**
 * Returns true when any value in the function's template env map is a
@@ -45300,7 +45560,7 @@ function reorderArgs(argv) {
 */
 async function main() {
 	const program = new Command();
-	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.114.1");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.115.1");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());