@go-to-k/cdkd 0.128.0 → 0.129.0

package/dist/cli.js

@@ -39795,6 +39795,398 @@ function resolveFnSubInvokeArn(arg) {
 	};
 }
 
+//#endregion
+//#region src/local/httpv2-service-integration.ts
+const logger = getLogger();
+/**
+* Full list of subtypes cdkd recognizes as supported. Mirrors AWS docs.
+*/
+const SUPPORTED_SUBTYPES = [
+	"EventBridge-PutEvents",
+	"SQS-SendMessage",
+	"SQS-ReceiveMessage",
+	"SQS-DeleteMessage",
+	"SQS-PurgeQueue",
+	"Kinesis-PutRecord",
+	"StepFunctions-StartExecution",
+	"StepFunctions-StartSyncExecution",
+	"StepFunctions-StopExecution",
+	"AppConfig-GetConfiguration"
+];
+/**
+* Type guard: is the string an AWS-recognized service-integration subtype?
+*
+* Used by route discovery to classify routes — recognized subtypes go
+* through dispatch, anything else (typo, future-AWS-subtype-not-yet-supported)
+* falls back to deferred-501.
+*/
+function isSupportedSubtype(value) {
+	return typeof value === "string" && SUPPORTED_SUBTYPES.includes(value);
+}
+/**
+* Lazy-loaded SDK clients keyed by `<service>:<region>`. SDK packages
+* are heavyweight (~5-10 MB each); per-process per-region caching
+* avoids re-instantiating the AWS Signer + middleware stack on every
+* request.
+*/
+const clientCache = /* @__PURE__ */ new Map();
+async function getClient(service, region) {
+	const key = `${service}:${region}`;
+	const cached = clientCache.get(key);
+	if (cached) return cached;
+	let client;
+	switch (service) {
+		case "sqs":
+			client = new (await (import("@aws-sdk/client-sqs"))).SQSClient({ region });
+			break;
+		case "sns":
+			client = new (await (import("@aws-sdk/client-sns"))).SNSClient({ region });
+			break;
+		case "eventbridge":
+			client = new (await (import("@aws-sdk/client-eventbridge"))).EventBridgeClient({ region });
+			break;
+		case "kinesis":
+			client = new (await (import("@aws-sdk/client-kinesis"))).KinesisClient({ region });
+			break;
+		case "sfn":
+			client = new (await (import("@aws-sdk/client-sfn"))).SFNClient({ region });
+			break;
+		case "ssm":
+			client = new (await (import("@aws-sdk/client-ssm"))).SSMClient({ region });
+			break;
+		default: throw new Error(`unknown service '${service}'`);
+	}
+	clientCache.set(key, client);
+	return client;
+}
+/**
+* Dispatch a service integration: build the SDK input from the
+* pre-resolved parameter map, invoke the SDK, translate the response
+* to HTTP shape.
+*
+* `defaultRegion` is the cdkd process's default AWS region (from
+* `AWS_REGION` / profile / `--region`). When the resolved parameter
+* map includes a non-empty `Region`, that value overrides the default
+* for this single call — matches AWS API Gateway behavior.
+*
+* Returns a `ServiceIntegrationResult` for the HTTP server to write
+* to the client. SDK-level errors are caught and translated to
+* HTTP 4xx / 5xx — never thrown.
+*/
+async function dispatchServiceIntegration(subtype, resolvedParameters, defaultRegion) {
+	const region = (resolvedParameters["Region"] || defaultRegion).trim();
+	if (!region) return errorResponse(400, "No AWS region configured. Set --region, AWS_REGION, or pass a 'Region' RequestParameter.");
+	try {
+		switch (subtype) {
+			case "EventBridge-PutEvents": return await dispatchEventBridgePutEvents(resolvedParameters, region);
+			case "SQS-SendMessage": return await dispatchSqsSendMessage(resolvedParameters, region);
+			case "SQS-ReceiveMessage": return await dispatchSqsReceiveMessage(resolvedParameters, region);
+			case "SQS-DeleteMessage": return await dispatchSqsDeleteMessage(resolvedParameters, region);
+			case "SQS-PurgeQueue": return await dispatchSqsPurgeQueue(resolvedParameters, region);
+			case "Kinesis-PutRecord": return await dispatchKinesisPutRecord(resolvedParameters, region);
+			case "StepFunctions-StartExecution": return await dispatchSfnStartExecution(resolvedParameters, region);
+			case "StepFunctions-StartSyncExecution": return await dispatchSfnStartSyncExecution(resolvedParameters, region);
+			case "StepFunctions-StopExecution": return await dispatchSfnStopExecution(resolvedParameters, region);
+			case "AppConfig-GetConfiguration": return await dispatchAppConfigGetConfiguration(resolvedParameters, region);
+		}
+	} catch (err) {
+		return translateSdkError(subtype, err);
+	}
+}
+async function dispatchEventBridgePutEvents(params, region) {
+	requireParams(params, [
+		"Detail",
+		"DetailType",
+		"Source"
+	]);
+	const mod = await import("@aws-sdk/client-eventbridge");
+	const client = await getClient("eventbridge", region);
+	const entry = {
+		Detail: params["Detail"],
+		DetailType: params["DetailType"],
+		Source: params["Source"]
+	};
+	if (params["Time"]) entry["Time"] = new Date(params["Time"]);
+	if (params["EventBusName"]) entry["EventBusName"] = params["EventBusName"];
+	if (params["Resources"]) entry["Resources"] = splitCsv(params["Resources"]);
+	if (params["TraceHeader"]) entry["TraceHeader"] = params["TraceHeader"];
+	return okJson(await client.send(new mod.PutEventsCommand({ Entries: [entry] })));
+}
+async function dispatchSqsSendMessage(params, region) {
+	requireParams(params, ["QueueUrl", "MessageBody"]);
+	const mod = await import("@aws-sdk/client-sqs");
+	const client = await getClient("sqs", region);
+	const input = {
+		QueueUrl: params["QueueUrl"],
+		MessageBody: params["MessageBody"]
+	};
+	if (params["DelaySeconds"]) input["DelaySeconds"] = Number(params["DelaySeconds"]);
+	if (params["MessageDeduplicationId"]) input["MessageDeduplicationId"] = params["MessageDeduplicationId"];
+	if (params["MessageGroupId"]) input["MessageGroupId"] = params["MessageGroupId"];
+	if (params["MessageAttributes"]) input["MessageAttributes"] = parseJsonOrEmpty(params["MessageAttributes"]);
+	if (params["MessageSystemAttributes"]) input["MessageSystemAttributes"] = parseJsonOrEmpty(params["MessageSystemAttributes"]);
+	return okJson(await client.send(new mod.SendMessageCommand(input)));
+}
+async function dispatchSqsReceiveMessage(params, region) {
+	requireParams(params, ["QueueUrl"]);
+	const mod = await import("@aws-sdk/client-sqs");
+	const client = await getClient("sqs", region);
+	const input = { QueueUrl: params["QueueUrl"] };
+	if (params["AttributeNames"]) input["AttributeNames"] = splitCsv(params["AttributeNames"]);
+	if (params["MaxNumberOfMessages"]) input["MaxNumberOfMessages"] = Number(params["MaxNumberOfMessages"]);
+	if (params["MessageAttributeNames"]) input["MessageAttributeNames"] = splitCsv(params["MessageAttributeNames"]);
+	if (params["ReceiveRequestAttemptId"]) input["ReceiveRequestAttemptId"] = params["ReceiveRequestAttemptId"];
+	if (params["VisibilityTimeout"]) input["VisibilityTimeout"] = Number(params["VisibilityTimeout"]);
+	if (params["WaitTimeSeconds"]) input["WaitTimeSeconds"] = Number(params["WaitTimeSeconds"]);
+	return okJson(await client.send(new mod.ReceiveMessageCommand(input)));
+}
+async function dispatchSqsDeleteMessage(params, region) {
+	requireParams(params, ["QueueUrl", "ReceiptHandle"]);
+	const mod = await import("@aws-sdk/client-sqs");
+	return okJson(await (await getClient("sqs", region)).send(new mod.DeleteMessageCommand({
+		QueueUrl: params["QueueUrl"],
+		ReceiptHandle: params["ReceiptHandle"]
+	})));
+}
+async function dispatchSqsPurgeQueue(params, region) {
+	requireParams(params, ["QueueUrl"]);
+	const mod = await import("@aws-sdk/client-sqs");
+	return okJson(await (await getClient("sqs", region)).send(new mod.PurgeQueueCommand({ QueueUrl: params["QueueUrl"] })));
+}
+async function dispatchKinesisPutRecord(params, region) {
+	requireParams(params, [
+		"StreamName",
+		"Data",
+		"PartitionKey"
+	]);
+	const mod = await import("@aws-sdk/client-kinesis");
+	const client = await getClient("kinesis", region);
+	const dataBytes = decodeBase64OrUtf8(params["Data"] ?? "");
+	const input = {
+		StreamName: params["StreamName"],
+		Data: dataBytes,
+		PartitionKey: params["PartitionKey"]
+	};
+	if (params["SequenceNumberForOrdering"]) input["SequenceNumberForOrdering"] = params["SequenceNumberForOrdering"];
+	if (params["ExplicitHashKey"]) input["ExplicitHashKey"] = params["ExplicitHashKey"];
+	return okJson(await client.send(new mod.PutRecordCommand(input)));
+}
+async function dispatchSfnStartExecution(params, region) {
+	requireParams(params, ["StateMachineArn"]);
+	const mod = await import("@aws-sdk/client-sfn");
+	const client = await getClient("sfn", region);
+	const input = { stateMachineArn: params["StateMachineArn"] };
+	if (params["Name"]) input["name"] = params["Name"];
+	if (params["Input"]) input["input"] = params["Input"];
+	return okJson(await client.send(new mod.StartExecutionCommand(input)));
+}
+async function dispatchSfnStartSyncExecution(params, region) {
+	requireParams(params, ["StateMachineArn"]);
+	const mod = await import("@aws-sdk/client-sfn");
+	const client = await getClient("sfn", region);
+	const input = { stateMachineArn: params["StateMachineArn"] };
+	if (params["Name"]) input["name"] = params["Name"];
+	if (params["Input"]) input["input"] = params["Input"];
+	if (params["TraceHeader"]) input["traceHeader"] = params["TraceHeader"];
+	return okJson(await client.send(new mod.StartSyncExecutionCommand(input)));
+}
+async function dispatchSfnStopExecution(params, region) {
+	requireParams(params, ["ExecutionArn"]);
+	const mod = await import("@aws-sdk/client-sfn");
+	const client = await getClient("sfn", region);
+	const input = { executionArn: params["ExecutionArn"] };
+	if (params["Cause"]) input["cause"] = params["Cause"];
+	if (params["Error"]) input["error"] = params["Error"];
+	return okJson(await client.send(new mod.StopExecutionCommand(input)));
+}
+async function dispatchAppConfigGetConfiguration(params, region) {
+	return errorResponse(501, "AppConfig-GetConfiguration is recognized but cdkd does not yet bundle @aws-sdk/client-appconfig. Use the deployed API for this subtype, or open an issue if you need local emulation.");
+}
+function requireParams(params, required) {
+	const missing = required.filter((k) => !params[k] || params[k].trim() === "");
+	if (missing.length > 0) {
+		const err = /* @__PURE__ */ new Error(`missing required RequestParameter(s): ${missing.join(", ")}`);
+		err.statusCode = 400;
+		throw err;
+	}
+}
+function splitCsv(value) {
+	return value.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+}
+function parseJsonOrEmpty(value) {
+	try {
+		const parsed = JSON.parse(value);
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+		return {};
+	} catch {
+		return {};
+	}
+}
+function decodeBase64OrUtf8(value) {
+	const trimmed = value.trim();
+	if (/^[A-Za-z0-9+/]+=*$/.test(trimmed) && trimmed.length % 4 === 0 && trimmed.length > 0) try {
+		return Buffer.from(trimmed, "base64");
+	} catch {}
+	return Buffer.from(value, "utf8");
+}
+function okJson(response) {
+	const stripped = stripSdkMetadata(response);
+	return {
+		statusCode: 200,
+		body: JSON.stringify(stripped),
+		headers: { "content-type": "application/json" }
+	};
+}
+function stripSdkMetadata(obj) {
+	if (obj === null || obj === void 0 || typeof obj !== "object") return obj;
+	if (Array.isArray(obj)) return obj;
+	const { $metadata: _meta, ...rest } = obj;
+	return rest;
+}
+function errorResponse(statusCode, message) {
+	return {
+		statusCode,
+		body: JSON.stringify({ message }),
+		headers: { "content-type": "application/json" }
+	};
+}
+/**
+* Translate an AWS SDK error to an HTTP response. AWS SDK v3 surfaces
+* errors as instances carrying `$metadata.httpStatusCode` + `name`;
+* we honor the status code when present, default to 500.
+*/
+function translateSdkError(subtype, err) {
+	if (err && typeof err === "object") {
+		const e = err;
+		const status = typeof e.statusCode === "number" && e.statusCode >= 100 && e.statusCode < 600 ? e.statusCode : e.$metadata?.httpStatusCode ?? 500;
+		const body = {
+			message: e.message ?? "AWS SDK call failed",
+			code: e.name ?? "UnknownError"
+		};
+		logger.debug(`[${subtype}] SDK error (${status}): ${stringifyValue(body)}`);
+		return {
+			statusCode: status,
+			body: JSON.stringify(body),
+			headers: { "content-type": "application/json" }
+		};
+	}
+	return errorResponse(500, `Unexpected error invoking ${subtype}: ${String(err)}`);
+}
+/**
+* Apply HTTP API v2 `ResponseParameters` mapping (per AWS docs:
+* https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-parameter-mapping.html#http-api-mapping-supported-values).
+*
+* Keys are `<op>:header.<name>` or `overwrite:statuscode`. Values can
+* carry `$response.header.<name>`, `$context.<X>`, `$stageVariables.<X>`,
+* or be a static literal. JSONPath against `$response.body.X` is NOT
+* supported (would require SDK response parsing into the same shape
+* every subtype produces; deferred). Reserved headers (per AWS docs)
+* are rejected at this layer with a single-line debug log.
+*
+* Status-code lookup is by the SDK-returned `statusCode`. When the
+* exact code has no entry, the wildcard `'default'` entry is applied
+* if present (matches AWS deployed behavior).
+*/
+function applyResponseParameters(base, responseParameters, responseCtx) {
+	if (!responseParameters) return base;
+	const overlay = responseParameters[String(base.statusCode)] ?? responseParameters["default"] ?? void 0;
+	if (!overlay) return base;
+	let statusCode = base.statusCode;
+	const headers = { ...base.headers };
+	for (const [key, value] of Object.entries(overlay)) {
+		if (typeof value !== "string") continue;
+		const resolved = resolveResponseValue(value, responseCtx, base);
+		if (key === "overwrite:statuscode") {
+			const next = Number(resolved);
+			if (Number.isInteger(next) && next >= 100 && next < 600) statusCode = next;
+			continue;
+		}
+		const headerMatch = /^(append|overwrite|remove):header\.(.+)$/i.exec(key);
+		if (!headerMatch || !headerMatch[1] || !headerMatch[2]) continue;
+		const op = headerMatch[1].toLowerCase();
+		const name = headerMatch[2].toLowerCase();
+		if (isReservedHeader(name)) {
+			logger.debug(`ResponseParameters: header '${name}' is reserved by API Gateway and was skipped`);
+			continue;
+		}
+		if (op === "remove") delete headers[name];
+		else if (op === "overwrite") headers[name] = resolved;
+		else if (op === "append") headers[name] = headers[name] ? `${headers[name]},${resolved}` : resolved;
+	}
+	return {
+		statusCode,
+		body: base.body,
+		headers
+	};
+}
+function resolveResponseValue(value, ctx, base) {
+	if (value.startsWith("$") && !value.includes("${")) {
+		const r = resolveSingleResponseRef(value, ctx, base);
+		return r !== void 0 ? r : value;
+	}
+	if (value.includes("${")) {
+		let out = "";
+		let i = 0;
+		while (i < value.length) {
+			const next = value.indexOf("${", i);
+			if (next === -1) {
+				out += value.slice(i);
+				break;
+			}
+			out += value.slice(i, next);
+			const end = value.indexOf("}", next + 2);
+			if (end === -1) return value;
+			const r = resolveSingleResponseRef("$" + value.slice(next + 2, end), ctx, base);
+			out += r ?? "";
+			i = end + 1;
+		}
+		return out;
+	}
+	return value;
+}
+function resolveSingleResponseRef(ref, ctx, base) {
+	if (ref.startsWith("$response.header.")) {
+		const name = ref.substring(17).toLowerCase();
+		return base.headers[name] ?? "";
+	}
+	if (ref.startsWith("$context.")) return ctx.context[ref.substring(9)] ?? "";
+	if (ref.startsWith("$stageVariables.")) return ctx.stageVariables[ref.substring(16)] ?? "";
+}
+/**
+* Subset of AWS's reserved-headers list relevant to response mapping.
+* https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-parameter-mapping.html#http-api-mapping-reserved-headers
+*/
+const RESERVED_HEADER_PREFIXES = [
+	"access-control-",
+	"apigw-",
+	"x-amz-",
+	"x-amzn-"
+];
+const RESERVED_HEADER_EXACT = [
+	"authorization",
+	"connection",
+	"content-encoding",
+	"content-length",
+	"content-location",
+	"forwarded",
+	"keep-alive",
+	"origin",
+	"proxy-authenticate",
+	"proxy-authorization",
+	"te",
+	"trailers",
+	"transfer-encoding",
+	"upgrade",
+	"x-forwarded-for",
+	"x-forwarded-host",
+	"x-forwarded-proto",
+	"via"
+];
+function isReservedHeader(lowerName) {
+	if (RESERVED_HEADER_EXACT.includes(lowerName)) return true;
+	return RESERVED_HEADER_PREFIXES.some((p) => lowerName.startsWith(p));
+}
+
 //#endregion
 //#region src/local/route-discovery.ts
 /**
@@ -40090,11 +40482,7 @@ function discoverHttpApiRoute(logicalId, resource, template, stackName) {
 		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.).` }
-	}];
+	if (integrationProps["IntegrationSubtype"] !== void 0) return [classifyServiceIntegrationRoute(baseRoute, integrationProps, stackName, logicalId, integrationLogicalId)];
 	const arnOutcome = resolveLambdaArnOutcome(integrationProps["IntegrationUri"]);
 	if (arnOutcome.kind === "unsupported") return [{
 		...baseRoute,
@@ -40107,6 +40495,45 @@ function discoverHttpApiRoute(logicalId, resource, template, stackName) {
 	}];
 }
 /**
+* Classify an HTTP API v2 route whose `IntegrationSubtype` is set
+* (service integration, no Lambda backing). Recognized subtypes
+* become `serviceIntegration` routes the HTTP server dispatches via
+* the SDK adapter table in `httpv2-service-integration.ts`;
+* unrecognized subtypes (typo / future-AWS-subtype-cdkd-doesn't-bundle
+* an SDK for) become deferred-501 unsupported routes.
+*
+* `RequestParameters` is the load-bearing field for dispatch — it
+* carries the SDK input as a flat map keyed by SDK parameter name.
+* Missing / non-object RequestParameters surfaces as unsupported (the
+* SDK call would have nothing to send).
+*/
+function classifyServiceIntegrationRoute(baseRoute, integrationProps, stackName, routeLogicalId, integrationLogicalId) {
+	const subtypeRaw = integrationProps["IntegrationSubtype"];
+	const declaredAt = `${stackName}/${routeLogicalId}`;
+	if (!isSupportedSubtype(subtypeRaw)) return {
+		...baseRoute,
+		lambdaLogicalId: "",
+		unsupported: { reason: `${declaredAt}: HTTP API v2 service integration subtype '${stringifyValue(subtypeRaw)}' is not supported by cdkd local start-api (see https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-aws-services-reference.html for the supported list).` }
+	};
+	const requestParameters = integrationProps["RequestParameters"];
+	if (!requestParameters || typeof requestParameters !== "object" || Array.isArray(requestParameters)) return {
+		...baseRoute,
+		lambdaLogicalId: "",
+		unsupported: { reason: `${stackName}/${integrationLogicalId}: HTTP API v2 service integration '${subtypeRaw}' is missing RequestParameters or it is not an object — cannot dispatch to the SDK without input mapping.` }
+	};
+	const responseParameters = integrationProps["ResponseParameters"];
+	const validatedResponseParameters = responseParameters && typeof responseParameters === "object" && !Array.isArray(responseParameters) ? responseParameters : void 0;
+	return {
+		...baseRoute,
+		lambdaLogicalId: "",
+		serviceIntegration: {
+			subtype: subtypeRaw,
+			requestParameters,
+			...validatedResponseParameters && { responseParameters: validatedResponseParameters }
+		}
+	};
+}
+/**
 * Discover the synthetic `ANY /{proxy+}` route from an
 * `AWS::Lambda::Url` resource.
 *
@@ -41761,7 +42188,7 @@ function attachAuthorizers(stacks, routes) {
 	const out = [];
 	const errors = [];
 	for (const route of routes) {
-		if (route.unsupported || route.mockCors) {
+		if (route.unsupported || route.mockCors || route.serviceIntegration) {
 			out.push({ route });
 			continue;
 		}
@@ -41791,6 +42218,45 @@ function attachAuthorizers(stacks, routes) {
 	return out;
 }
 /**
+* Walk every discovered route and return the service-integration routes
+* whose source CFn resource declares an authorizer (HTTP API v2 routes
+* with `AuthorizationType !== 'NONE'`). Service-integration routes only
+* exist on `AWS::ApiGatewayV2::Route`; REST v1 service integrations are
+* a different shape and not yet supported.
+*/
+function findIgnoredServiceIntegrationAuthorizers(stacks, routes) {
+	const stackByRoute = /* @__PURE__ */ new Map();
+	for (const stack of stacks) {
+		const prefix = `${stack.stackName}/`;
+		for (const route of routes) if (route.declaredAt.startsWith(prefix)) stackByRoute.set(route.declaredAt, stack);
+	}
+	const out = [];
+	for (const route of routes) {
+		if (!route.serviceIntegration) continue;
+		const stack = stackByRoute.get(route.declaredAt);
+		if (!stack) continue;
+		const slash = route.declaredAt.indexOf("/");
+		if (slash < 0) continue;
+		const logicalId = route.declaredAt.slice(slash + 1);
+		const resource = stack.template.Resources?.[logicalId];
+		if (!resource || resource.Type !== "AWS::ApiGatewayV2::Route") continue;
+		const props = resource.Properties ?? {};
+		const authType = props["AuthorizationType"];
+		if (typeof authType !== "string" || authType === "" || authType.toUpperCase() === "NONE") continue;
+		let authorizerName;
+		if (authType === "AWS_IAM") authorizerName = "AWS_IAM";
+		else {
+			const ref = props["AuthorizerId"];
+			authorizerName = (ref && typeof ref === "object" && "Ref" in ref && typeof ref.Ref === "string" ? ref.Ref : void 0) ?? `<authType=${authType}, AuthorizerId malformed>`;
+		}
+		out.push({
+			declaredAt: route.declaredAt,
+			authorizerName
+		});
+	}
+	return out;
+}
+/**
 * Detect the authorizer (if any) attached to a discovered route.
 * Walks the original CFn resource for the route in `stack.template`.
 */
@@ -42920,6 +43386,191 @@ function amzDateOutsideSkew(amzDate, now) {
 	return Math.abs(ts.getTime() - now.getTime()) > 900 * 1e3;
 }
 
+//#endregion
+//#region src/local/parameter-mapping.ts
+/**
+* Parameter-mapping resolver for HTTP API v2 service integrations
+* (`IntegrationSubtype` set, no Lambda).
+*
+* AWS API Gateway HTTP APIs let you wire a route directly to an AWS
+* SDK call via `RequestParameters` — a flat map whose KEY is the SDK
+* input parameter name (`QueueUrl`, `MessageBody`, `Source`, ...) and
+* whose VALUE is either a literal string or one of the dollar-prefixed
+* "selection expression" forms documented at
+* https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-parameter-mapping.html
+*
+* Supported value forms (all bare and `${...}`-wrapped variants):
+*   - `$request.header.<name>`    — case-insensitive header lookup; multi-values comma-joined
+*   - `$request.querystring.<key>` — case-SENSITIVE; multi-values comma-joined
+*   - `$request.path.<param>`     — path parameter from `{param}` route patterns
+*   - `$request.path`             — full request path (without stage)
+*   - `$request.body`             — entire request body as a string
+*   - `$request.body.<jsonpath>`  — JSONPath against the parsed JSON body
+*                                   (recursive descent `..` and filter `?()` are NOT supported)
+*   - `$context.<key>`            — supported context variables
+*                                   (requestId / accountId / domainName / identity.sourceIp / etc.)
+*   - `$stageVariables.<key>`     — values from the route's selected stage
+*
+* `${X} ${Y}` interpolation: any string containing `${...}` is treated
+* as a template literal — each placeholder is resolved independently
+* and the surrounding literal characters are preserved.
+*
+* Anything that is not a recognized selection expression AND does not
+* contain `${...}` is returned as a literal string.
+*
+* This module is **pure-functional and async-free** — every input is
+* derived from the HTTP request snapshot, route match, and the
+* pre-discovered route state. SDK invocation happens in the dispatcher
+* (see `httpv2-service-integration.ts`).
+*
+* Unresolved references (e.g. `$request.querystring.url` against a
+* request with no `url` parameter) resolve to the empty string —
+* matches deployed API Gateway behavior, which treats absent values
+* as `""` and passes them to the SDK call. The dispatcher's
+* per-subtype validator then surfaces the SDK's typed rejection.
+*/
+/**
+* Resolve a `RequestParameters` map (HTTP API v2 service integration
+* shape) against the incoming HTTP request. Keys are passed through
+* verbatim (they identify the SDK input parameter); only the VALUES
+* go through selection-expression resolution.
+*/
+function resolveServiceIntegrationParameters(parameters, ctx) {
+	const resolved = {};
+	for (const [key, rawValue] of Object.entries(parameters)) {
+		if (typeof rawValue !== "string") return {
+			kind: "error",
+			reason: `RequestParameters[${JSON.stringify(key)}] must be a string (got ${typeof rawValue}: ${stringifyValue(rawValue)}).`
+		};
+		try {
+			resolved[key] = resolveSelectionExpression(rawValue, ctx);
+		} catch (err) {
+			return {
+				kind: "error",
+				reason: `RequestParameters[${JSON.stringify(key)}]: ${err instanceof Error ? err.message : String(err)}`
+			};
+		}
+	}
+	return {
+		kind: "ok",
+		resolved
+	};
+}
+/**
+* Resolve a single selection-expression string. Public for unit
+* testing — production callers use {@link resolveServiceIntegrationParameters}.
+*
+* Three shapes:
+*   1. Pure bare reference (`$request.querystring.url`) — resolved
+*      and returned as-is. Whole-string match.
+*   2. Embedded `${...}` interpolation — every placeholder is resolved
+*      and concatenated with the surrounding literals.
+*   3. Anything else — returned verbatim as a literal.
+*/
+function resolveSelectionExpression(input, ctx) {
+	if (input.startsWith("$") && !input.includes("${")) {
+		const resolved = resolveSingleReference(input, ctx);
+		if (resolved !== void 0) return resolved;
+		return input;
+	}
+	if (input.includes("${")) return interpolate(input, ctx);
+	return input;
+}
+/**
+* Walk a `${...}`-templated string and emit the concatenated result.
+* Per AWS docs, `${X}` may contain any of the selection-expression
+* forms recognized in bare form.
+*/
+function interpolate(input, ctx) {
+	let out = "";
+	let i = 0;
+	while (i < input.length) {
+		const next = input.indexOf("${", i);
+		if (next === -1) {
+			out += input.slice(i);
+			break;
+		}
+		out += input.slice(i, next);
+		const end = input.indexOf("}", next + 2);
+		if (end === -1) throw new Error(`unclosed '\${...}' interpolation in selection expression`);
+		const resolved = resolveSingleReference("$" + input.slice(next + 2, end), ctx);
+		out += resolved ?? "";
+		i = end + 1;
+	}
+	return out;
+}
+/**
+* Resolve one selection-expression reference (without `${...}`
+* wrapping). Returns `undefined` when the reference's PREFIX is not
+* a recognized form (so the bare-form caller can fall through to
+* literal-pass-through); returns `""` when the prefix matched but
+* the referenced datum was absent (AWS-deployed behavior).
+*/
+function resolveSingleReference(ref, ctx) {
+	if (ref === "$request.body") return ctx.body;
+	if (ref === "$request.path") return ctx.requestPath;
+	if (ref.startsWith("$request.body.")) {
+		const path = ref.substring(14);
+		return resolveBodyJsonPath(ctx.body, path);
+	}
+	if (ref.startsWith("$request.header.")) {
+		const name = ref.substring(16).toLowerCase();
+		return ctx.headers[name] ?? "";
+	}
+	if (ref.startsWith("$request.querystring.")) {
+		const key = ref.substring(21);
+		return ctx.queryString[key] ?? "";
+	}
+	if (ref.startsWith("$request.path.")) {
+		const key = ref.substring(14);
+		return ctx.pathParameters[key] ?? "";
+	}
+	if (ref.startsWith("$context.")) {
+		const key = ref.substring(9);
+		return ctx.context[key] ?? "";
+	}
+	if (ref.startsWith("$stageVariables.")) {
+		const key = ref.substring(16);
+		return ctx.stageVariables[key] ?? "";
+	}
+}
+/**
+* Resolve a simple JSON path against the request body. Per AWS docs:
+*
+*   - The body is JSON-parsed (best-effort; non-JSON → empty string).
+*   - Path segments are `.`-separated. Array indexing via `[N]` is
+*     supported.
+*   - Recursive descent `..` and filter expressions `?()` are NOT
+*     supported and produce `""` (matches AWS rejection at deploy
+*     time, but we degrade gracefully at runtime).
+*
+* Non-string leaves are stringified with `JSON.stringify` so they can
+* round-trip into the SDK call's string-typed input fields.
+*/
+function resolveBodyJsonPath(body, path) {
+	if (path.startsWith(".") || path.includes("..") || path.includes("?(")) return "";
+	let parsed;
+	try {
+		parsed = JSON.parse(body);
+	} catch {
+		return "";
+	}
+	const segments = path.split(/\.|\[(\d+)\]/).filter((s) => s !== void 0 && s !== "");
+	let cursor = parsed;
+	for (const seg of segments) {
+		if (cursor === null || cursor === void 0) return "";
+		if (typeof cursor !== "object") return "";
+		if (Array.isArray(cursor)) {
+			const idx = Number(seg);
+			if (!Number.isInteger(idx)) return "";
+			cursor = cursor[idx];
+		} else cursor = cursor[seg];
+	}
+	if (cursor === void 0 || cursor === null) return "";
+	if (typeof cursor === "string") return cursor;
+	return JSON.stringify(cursor);
+}
+
 //#endregion
 //#region src/local/http-server.ts
 /**
@@ -43020,6 +43671,10 @@ async function handleRequest(req, res, state, opts) {
 		writeNotImplemented(res, match.route.unsupported.reason);
 		return;
 	}
+	if (match.route.serviceIntegration) {
+		await handleServiceIntegrationRequest(req, res, match, bodyBuf, opts);
+		return;
+	}
 	const authorizer = state.routes.find((r) => r.route.declaredAt === match.route.declaredAt && r.route.method === match.route.method)?.authorizer;
 	const clientCert = opts.mtls ? extractClientCert(req) : void 0;
 	const snapshot = {
@@ -43397,9 +44052,12 @@ function lowercaseSingularHeaders(raw) {
 	return out;
 }
 /**
-* Parse query string into a singular (last-wins) map. Used by the
-* authorizer pass — separate from api-gateway-event because the
-* authorizer needs raw header values too.
+* Parse query string into a singular map. Multi-value keys are
+* comma-joined in order of appearance (`?foo=a&foo=b` -> `foo: 'a,b'`)
+* — matches the contract documented at
+* `src/local/parameter-mapping.ts:14` ("multi-values comma-joined")
+* AND deployed API Gateway behavior. Used by both the authorizer pass
+* and the HTTP API v2 service-integration parameter mapper.
 */
 function parseQueryStringSingular(rawUrl) {
 	const q = rawUrl.indexOf("?");
@@ -43420,7 +44078,8 @@ function parseQueryStringSingular(rawUrl) {
 		try {
 			value = decodeURIComponent(rawValue);
 		} catch {}
-		out[key] = value;
+		const prev = out[key];
+		out[key] = prev === void 0 ? value : `${prev},${value}`;
 	}
 	return out;
 }
@@ -43466,6 +44125,120 @@ function writeError(res, statusCode, body = "{\"message\":\"Internal server erro
 	res.end(body);
 }
 /**
+* Handle an HTTP API v2 service-integration route (#458). The route
+* carries `serviceIntegration: { subtype, requestParameters, responseParameters? }`
+* — no Lambda backs it. Flow:
+*
+*   1. Build a {@link RequestParameterContext} from the HTTP request +
+*      route match (path parameters, query string, headers, context
+*      variables, stage variables).
+*   2. Resolve every `RequestParameters` value against that context via
+*      `parameter-mapping.ts`. Per-parameter unresolved refs degrade to
+*      `""` (matches AWS deployed behavior).
+*   3. Dispatch to the per-subtype SDK adapter in
+*      `httpv2-service-integration.ts`. Per-request `Region` parameter
+*      overrides the server's `opts.defaultRegion`; absent both surfaces
+*      a 400.
+*   4. Apply per-status-code `ResponseParameters` overlay (header /
+*      statuscode overwrites).
+*   5. Write the result to the HTTP client.
+*
+* Authorizer pass: NOT yet wired (current scope is dispatch only). When
+* a service-integration route carries an authorizer, the discovery layer
+* leaves it in place but the server short-circuits to dispatch BEFORE the
+* auth pass. A follow-up PR can hoist the auth pass earlier — keeping it
+* out of this PR limits the blast radius.
+*/
+async function handleServiceIntegrationRequest(req, res, match, bodyBuf, opts) {
+	const route = match.route;
+	const svc = route.serviceIntegration;
+	if (!svc) {
+		writeError(res, 500);
+		return;
+	}
+	const rawUrl = req.url ?? "/";
+	const headersFlat = flattenHeadersForMapping(req);
+	const queryString = parseQueryStringSingular(rawUrl);
+	const requestPath = rawUrl.split("?")[0] ?? "/";
+	const context = buildServiceIntegrationContextVars(req, route);
+	const ctx = {
+		headers: headersFlat,
+		queryString,
+		pathParameters: match.pathParameters,
+		requestPath,
+		body: bodyBuf.toString("utf8"),
+		context,
+		stageVariables: route.stageVariables ?? {}
+	};
+	const outcome = resolveServiceIntegrationParameters(svc.requestParameters, ctx);
+	if (outcome.kind === "error") {
+		getLogger().warn(`[${route.declaredAt}] ${outcome.reason}`);
+		const body = JSON.stringify({
+			message: "Invalid integration mapping",
+			reason: outcome.reason
+		});
+		res.statusCode = 500;
+		res.setHeader("content-type", "application/json");
+		res.setHeader("content-length", String(Buffer.byteLength(body, "utf-8")));
+		res.end(body);
+		return;
+	}
+	const result = await dispatchServiceIntegration(svc.subtype, outcome.resolved, opts.defaultRegion ?? "");
+	const responseCtx = {
+		context,
+		stageVariables: route.stageVariables ?? {}
+	};
+	const finalResult = applyResponseParameters(result, svc.responseParameters, responseCtx);
+	res.statusCode = finalResult.statusCode;
+	for (const [name, value] of Object.entries(finalResult.headers)) res.setHeader(name, value);
+	res.setHeader("content-length", String(Buffer.byteLength(finalResult.body, "utf-8")));
+	res.end(finalResult.body);
+}
+/**
+* Flatten Node's `req.headers` to the single-string-per-key shape the
+* parameter-mapping resolver expects (`$request.header.<name>` is
+* documented as comma-joined multi-value). Header NAMES are lowercased
+* because AWS docs document `$request.header.<name>` as case-insensitive.
+*/
+function flattenHeadersForMapping(req) {
+	const out = {};
+	for (const [name, value] of Object.entries(req.headers)) {
+		const lower = name.toLowerCase();
+		if (Array.isArray(value)) out[lower] = value.join(", ");
+		else if (typeof value === "string") out[lower] = value;
+	}
+	return out;
+}
+/**
+* Build the subset of AWS context variables the service-integration
+* parameter-mapping resolver needs to surface (per AWS docs
+* https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-logging-variables.html).
+*
+* We populate the most-commonly-referenced fields with realistic values
+* (`requestId` is fresh per call, `accountId` / `domainName` are mock
+* but stable). Selection expressions against context variables we
+* don't model resolve to `""` — matches the AWS-deployed behavior of
+* absent values.
+*/
+function buildServiceIntegrationContextVars(req, route) {
+	const requestId = `cdkd-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+	const sourceIp = req.socket.remoteAddress ?? "127.0.0.1";
+	return {
+		requestId,
+		accountId: "123456789012",
+		apiId: route.apiLogicalId ?? "local",
+		stage: route.stage,
+		"identity.sourceIp": sourceIp,
+		"identity.userAgent": Array.isArray(req.headers["user-agent"]) || typeof req.headers["user-agent"] === "string" ? String(req.headers["user-agent"]) : "",
+		domainName: "localhost",
+		httpMethod: req.method ?? "GET",
+		path: (req.url ?? "/").split("?")[0] ?? "/",
+		protocol: "HTTP/1.1",
+		requestTime: (/* @__PURE__ */ new Date()).toISOString(),
+		requestTimeEpoch: String(Date.now())
+	};
+}
+/**
 * 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
@@ -44227,6 +45000,7 @@ async function localStartApiCommand(target, options) {
 	warnVpcConfigLambdas(initialMaterial.routes, initialMaterial.stacks ?? []);
 	sigV4CredentialsLoader = defaultCredentialsLoader();
 	warnIamRoutes(initialMaterial.routes);
+	warnIgnoredServiceIntegrationAuthorizers(initialMaterial.routes, initialMaterial.stacks ?? []);
 	let maxTimeoutSec = 0;
 	for (const spec of initialMaterial.specs.values()) if (spec.lambda.timeoutSec > maxTimeoutSec) maxTimeoutSec = spec.lambda.timeoutSec;
 	const rieTimeoutMs = Math.max(3e4, maxTimeoutSec * 2 * 1e3);
@@ -44251,6 +45025,7 @@ async function localStartApiCommand(target, options) {
 			for (const result of handles) if (result.status === "fulfilled") groupPool.release(result.value);
 			else logger.warn(`Pre-warm failed for one Lambda in ${group.displayName} (cold start cost will apply on first request): ${result.reason instanceof Error ? result.reason.message : String(result.reason)}`);
 		}
+		const defaultRegion = options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"] ?? void 0;
 		const started = await startApiServer({
 			state: groupState,
 			rieTimeoutMs,
@@ -44262,7 +45037,8 @@ async function localStartApiCommand(target, options) {
 			jwksWarnedUrls,
 			sigV4CredentialsLoader,
 			sigV4WarnedForeignIds,
-			sigV4AllowUnverified: options.allowUnverifiedSigv4 === true
+			sigV4AllowUnverified: options.allowUnverifiedSigv4 === true,
+			...defaultRegion && { defaultRegion }
 		});
 		servers.push({
 			group,
@@ -44391,7 +45167,7 @@ function uniqueLambdaIds(routes, routesWithAuth) {
 	const seen = /* @__PURE__ */ new Set();
 	const out = [];
 	for (const r of routes) {
-		if (r.unsupported || r.mockCors) continue;
+		if (r.unsupported || r.mockCors || r.serviceIntegration) continue;
 		if (r.lambdaLogicalId.length === 0) continue;
 		if (!seen.has(r.lambdaLogicalId)) {
 			seen.add(r.lambdaLogicalId);
@@ -44399,7 +45175,7 @@ function uniqueLambdaIds(routes, routesWithAuth) {
 		}
 	}
 	for (const entry of routesWithAuth) {
-		if (entry.route.unsupported || entry.route.mockCors) continue;
+		if (entry.route.unsupported || entry.route.mockCors || entry.route.serviceIntegration) continue;
 		const auth = entry.authorizer;
 		if (!auth) continue;
 		if (auth.kind === "lambda-token" || auth.kind === "lambda-request") {
@@ -44484,6 +45260,27 @@ function warnIamRoutes(routesWithAuth) {
 	return true;
 }
 /**
+* #458 / PR #500 review: emit a one-line warn naming every service-
+* integration route whose source CFn resource declares an authorizer
+* (HTTP API v2 routes with `AuthorizationType !== 'NONE'`). The
+* dispatcher in `http-server.ts` runs the SDK call BEFORE the
+* authorizer pass would fire, so without this warn a CDK app that
+* wires JWT / Lambda / Cognito / IAM authorizers onto service
+* integrations would silently let every local request reach the SDK
+* call without auth. Threading the auth pass through the
+* service-integration dispatcher is a follow-up issue. Returns the
+* number of warned routes so tests can assert the firing path; the
+* value is otherwise unused.
+*/
+function warnIgnoredServiceIntegrationAuthorizers(routesWithAuth, stacks) {
+	const logger = getLogger();
+	const ignored = findIgnoredServiceIntegrationAuthorizers(stacks, routesWithAuth.map((entry) => entry.route));
+	if (ignored.length === 0) return 0;
+	logger.warn(`${ignored.length} HTTP API v2 service-integration route(s) declare an authorizer but cdkd local start-api dispatches the SDK call BEFORE the authorizer pass — every local request reaches the SDK call WITHOUT authentication. This is a deferred feature; see https://github.com/go-to-k/cdkd/issues/502 for the follow-up tracking issue.`);
+	for (const entry of ignored) logger.warn(`  - ${entry.declaredAt}: authorizer '${entry.authorizerName}' is configured but ignored`);
+	return ignored.length;
+}
+/**
 * Build the per-Lambda container spec — code dir, env vars (template +
 * --env-vars overlay), STS-issued creds when --assume-role names this
 * Lambda, optional --debug-port reservation. Errors out with a clear
@@ -44799,7 +45596,7 @@ 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";
-		const target = r.mockCors ? "[MOCK CORS preflight]" : r.unsupported ? "[501 Not Implemented]" : r.lambdaLogicalId;
+		const target = r.mockCors ? "[MOCK CORS preflight]" : r.unsupported ? "[501 Not Implemented]" : r.serviceIntegration ? `[${r.serviceIntegration.subtype}]` : r.lambdaLogicalId;
 		process.stdout.write(`  ${r.method.padEnd(methodWidth)}  ${r.pathPattern.padEnd(pathWidth)}  -> ${target}  (${sourceLabel})\n`);
 	}
 	process.stdout.write("\n");
@@ -48297,7 +49094,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.128.0");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.129.0");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());