@go-to-k/cdkd 0.124.0 → 0.126.0

package/dist/cli.js

@@ -19,9 +19,9 @@ import { CloudFrontClient, CreateCloudFrontOriginAccessIdentityCommand, CreateDi
 import { CloudWatchClient, DeleteAlarmsCommand, DescribeAlarmsCommand, ListTagsForResourceCommand as ListTagsForResourceCommand$4, PutMetricAlarmCommand, TagResourceCommand as TagResourceCommand$6, UntagResourceCommand as UntagResourceCommand$6 } from "@aws-sdk/client-cloudwatch";
 import { CloudWatchLogsClient, CreateLogGroupCommand, DeleteDataProtectionPolicyCommand, DeleteIndexPolicyCommand, DeleteLogGroupCommand, DeleteRetentionPolicyCommand, DescribeIndexPoliciesCommand, DescribeLogGroupsCommand, GetDataProtectionPolicyCommand, ListTagsForResourceCommand as ListTagsForResourceCommand$5, PutBearerTokenAuthenticationCommand, PutDataProtectionPolicyCommand, PutIndexPolicyCommand, PutLogGroupDeletionProtectionCommand, PutRetentionPolicyCommand, ResourceAlreadyExistsException, ResourceNotFoundException as ResourceNotFoundException$4, TagResourceCommand as TagResourceCommand$7, UntagResourceCommand as UntagResourceCommand$7 } from "@aws-sdk/client-cloudwatch-logs";
 import { BedrockAgentCoreControlClient, CreateAgentRuntimeCommand, DeleteAgentRuntimeCommand, GetAgentRuntimeCommand, ResourceNotFoundException as ResourceNotFoundException$5, UpdateAgentRuntimeCommand } from "@aws-sdk/client-bedrock-agentcore-control";
-import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { cpSync, createWriteStream, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import * as path from "node:path";
-import { dirname, isAbsolute, resolve } from "node:path";
+import { dirname, isAbsolute, join, normalize, resolve } from "node:path";
 import { execFile, spawn } from "node:child_process";
 import { tmpdir } from "node:os";
 import { AssociateVPCWithHostedZoneCommand, ChangeResourceRecordSetsCommand, ChangeTagsForResourceCommand, CreateHostedZoneCommand, CreateQueryLoggingConfigCommand, DeleteHostedZoneCommand, DeleteQueryLoggingConfigCommand, DisassociateVPCFromHostedZoneCommand, GetHostedZoneCommand, ListHostedZonesByNameCommand, ListHostedZonesCommand, ListQueryLoggingConfigsCommand, ListResourceRecordSetsCommand, ListTagsForResourceCommand as ListTagsForResourceCommand$6, Route53Client, UpdateHostedZoneCommentCommand } from "@aws-sdk/client-route-53";
@@ -57,11 +57,15 @@ import { CreateNamespaceCommand, CreateTableBucketCommand, CreateTableCommand as
 import { AttachTrafficSourcesCommand, AutoScalingClient, CreateAutoScalingGroupCommand, DeleteAutoScalingGroupCommand, DeleteLifecycleHookCommand, DeleteNotificationConfigurationCommand, DescribeAutoScalingGroupsCommand, DescribeLifecycleHooksCommand, DescribeNotificationConfigurationsCommand, DescribeTrafficSourcesCommand, DetachTrafficSourcesCommand, DisableMetricsCollectionCommand, EnableMetricsCollectionCommand, PutLifecycleHookCommand, PutNotificationConfigurationCommand, UpdateAutoScalingGroupCommand } from "@aws-sdk/client-auto-scaling";
 import * as readline from "node:readline/promises";
 import { Document, Pair, Scalar, YAMLMap, YAMLSeq, parse as parse$1, stringify } from "yaml";
+import { mkdir, mkdtemp } from "node:fs/promises";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
 import { createServer } from "node:net";
 import { promisify } from "node:util";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { readFile } from "fs/promises";
 import { createServer as createServer$1 } from "node:http";
+import { createServer as createServer$2 } from "node:https";
 import * as chokidar from "chokidar";
 
 //#region src/cli/options.ts
@@ -36687,16 +36691,23 @@ function resolveAssetCodePath$1(stack, logicalId, resource) {
 * bind mounts at the same target so cdkd cannot rely on overlay
 * layering.
 *
-* **Out of scope (hard-errors)**:
+* **Same-stack handling** (`{Ref: <Id>}` / `{Fn::GetAtt: [<Id>, 'Ref']}`):
 *
-*   - Literal ARN strings (`arn:aws:lambda:...`) — these are external /
-*     pre-existing layers (no asset on disk to mount) including
-*     cross-account / cross-region.
-*   - Same-stack refs that don't point at an `AWS::Lambda::LayerVersion`
-*     resource — almost always a typo'd logical ID.
-*   - Same-stack refs to a `LayerVersion` whose `Metadata['aws:asset:path']`
-*     is missing — the layer's content is `S3Bucket` / `S3Key` from
-*     outside cdk.out and there's no local directory to bind-mount.
+*   - Refs that don't point at an `AWS::Lambda::LayerVersion` resource
+*     hard-error — almost always a typo'd logical ID.
+*   - Refs to a `LayerVersion` whose `Metadata['aws:asset:path']` is
+*     missing hard-error — the layer's content is `S3Bucket` / `S3Key`
+*     from outside cdk.out and there's no local directory to bind-mount.
+*
+* **Literal-ARN handling** (issue #448): entries shaped like the string
+* `arn:aws:lambda:<region>:<account>:layer:<name>:<version>` are parsed
+* into a `{kind: 'arn', ...}` resolved layer. The actual
+* `lambda:GetLayerVersion` + presigned-URL download + unzip happens
+* later in the CLI (`materializeLayerFromArn(...)`), which can optionally
+* `sts:AssumeRole` into the layer's account when the dev's default
+* credentials cannot read it. Covers AWS-published public layers (Lambda
+* Powertools, Datadog Extension, etc.) and cross-account / cross-region
+* shared layers.
 */
 function resolveLambdaLayers(stack, logicalId, props) {
 	const layers = props["Layers"];
@@ -36707,13 +36718,24 @@ function resolveLambdaLayers(stack, logicalId, props) {
 	const out = [];
 	for (let i = 0; i < layers.length; i++) {
 		const entry = layers[i];
+		if (typeof entry === "string") {
+			const parsed = parseLayerVersionArn(entry);
+			if (!parsed) throw new LocalInvokeResolutionError(`Lambda '${logicalId}' has a Layers entry [${i}] cdkd cannot resolve locally: literal string '${entry}'. Expected a same-stack Ref / Fn::GetAtt to an AWS::Lambda::LayerVersion OR a literal layer-version ARN of the form arn:aws:lambda:<region>:<account>:layer:<name>:<version>.`);
+			out.push({
+				kind: "arn",
+				logicalId: parsed.arn,
+				...parsed
+			});
+			continue;
+		}
 		const layerLogicalId = pickLayerLogicalId(entry);
-		if (!layerLogicalId) throw new LocalInvokeResolutionError(`Lambda '${logicalId}' has a Layers entry [${i}] cdkd cannot resolve locally: ${describeLayerEntry(entry)}. Only same-stack Ref / Fn::GetAtt to an AWS::Lambda::LayerVersion are supported in v1; cross-account / cross-region / pre-existing-ARN layers are deferred to a follow-up PR.`);
+		if (!layerLogicalId) throw new LocalInvokeResolutionError(`Lambda '${logicalId}' has a Layers entry [${i}] cdkd cannot resolve locally: ${describeLayerEntry(entry)}. Expected a same-stack Ref / Fn::GetAtt to an AWS::Lambda::LayerVersion OR a literal layer-version ARN of the form arn:aws:lambda:<region>:<account>:layer:<name>:<version>.`);
 		const layerResource = resources[layerLogicalId];
 		if (!layerResource) throw new LocalInvokeResolutionError(`Lambda '${logicalId}' Layers entry [${i}] references '${layerLogicalId}', but no resource with that logical ID exists in stack '${stack.stackName}'.`);
 		if (layerResource.Type !== "AWS::Lambda::LayerVersion") throw new LocalInvokeResolutionError(`Lambda '${logicalId}' Layers entry [${i}] references '${layerLogicalId}' (${layerResource.Type}), which is not an AWS::Lambda::LayerVersion.`);
 		const assetPath = resolveAssetCodePath$1(stack, layerLogicalId, layerResource);
 		out.push({
+			kind: "asset",
 			logicalId: layerLogicalId,
 			assetPath
 		});
@@ -36721,6 +36743,29 @@ function resolveLambdaLayers(stack, logicalId, props) {
 	return out;
 }
 /**
+* Parse a Lambda layer-version ARN string into its segments.
+*
+* Returns `undefined` for anything that does not match the strict
+* `arn:aws:lambda:<region>:<account>:layer:<name>:<version>` shape so
+* the caller can produce a clearer error than a silent
+* misinterpretation of hand-edited templates. The partition segment
+* accepts `aws` / `aws-cn` / `aws-us-gov` so GovCloud / China-region
+* ARNs work without code changes.
+*
+* Exported for unit testing.
+*/
+function parseLayerVersionArn(input) {
+	const m = /^arn:(aws|aws-cn|aws-us-gov):lambda:([a-z]{2}-(?:[a-z]+-){1,2}\d+):(\d{12}):layer:([A-Za-z0-9_-]+):(\d+)$/.exec(input);
+	if (!m) return void 0;
+	return {
+		arn: input,
+		region: m[2],
+		accountId: m[3],
+		name: m[4],
+		version: m[5]
+	};
+}
+/**
 * Walk a single Layers-array entry and return the referenced layer's
 * logical ID — or `undefined` for shapes we don't try to resolve in v1.
 *
@@ -36789,6 +36834,195 @@ function notFoundError$1(target, stack, resources) {
 	return new LocalInvokeResolutionError(msg.trimEnd());
 }
 
+//#endregion
+//#region src/local/layer-arn-materializer.ts
+var LayerMaterializationError = class LayerMaterializationError extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "LayerMaterializationError";
+		Object.setPrototypeOf(this, LayerMaterializationError.prototype);
+	}
+};
+async function materializeLayerFromArn(layer, options = {}) {
+	const logger = getLogger();
+	let credentials;
+	if (options.roleArn) try {
+		credentials = await assumeRoleForLayer(options.roleArn, layer.region, options);
+		logger.debug(`Layer ${layer.arn}: assumed role ${options.roleArn} for GetLayerVersion`);
+	} catch (err) {
+		throw new LayerMaterializationError(`Layer ${layer.arn}: STS AssumeRole(${options.roleArn}) failed: ${errMsg(err)}. Check the role trust policy permits your principal and sts:AssumeRole is allowed.`);
+	}
+	let presignedUrl;
+	try {
+		presignedUrl = await fetchLayerContentUrl(layer, credentials, options);
+	} catch (err) {
+		const hint = looksLikeAccessDenied(err) ? " GetLayerVersion access denied; check the credentials / role can read the layer (grant lambda:GetLayerVersion on the layer ARN, or pass --layer-role-arn <arn> to assume a role in the layer account)." : "";
+		throw new LayerMaterializationError(`Layer ${layer.arn}: GetLayerVersion failed in region ${layer.region}: ${errMsg(err)}.${hint}`);
+	}
+	let zipBytes;
+	try {
+		zipBytes = await downloadPresignedZip(presignedUrl, options);
+	} catch (err) {
+		throw new LayerMaterializationError(`Layer ${layer.arn}: failed to download layer ZIP from the presigned URL: ${errMsg(err)}.`);
+	}
+	const dir = await mkdtemp(join(tmpdir(), `cdkd-local-arn-layer-${layer.name}-${layer.version}-`));
+	try {
+		await unzipBufferToDirectory(zipBytes, dir);
+	} catch (err) {
+		try {
+			rmSync(dir, {
+				recursive: true,
+				force: true
+			});
+		} catch {}
+		throw new LayerMaterializationError(`Layer ${layer.arn}: failed to unzip layer contents into '${dir}': ${errMsg(err)}.`);
+	}
+	return dir;
+}
+async function fetchLayerContentUrl(layer, credentials, options) {
+	const client = (options.lambdaClientFactory ?? await defaultLambdaClientFactory())(layer.region, credentials);
+	try {
+		const command = await buildGetLayerVersionCommand(`arn:aws:lambda:${layer.region}:${layer.accountId}:layer:${layer.name}`, Number(layer.version));
+		const url = (await client.send(command))?.Content?.Location;
+		if (!url || typeof url !== "string") throw new Error("GetLayerVersion response did not include Content.Location (presigned ZIP URL)");
+		return url;
+	} finally {
+		client.destroy?.();
+	}
+}
+async function assumeRoleForLayer(roleArn, region, options) {
+	const client = (options.stsClientFactory ?? await defaultStsClientFactory())(region);
+	try {
+		const command = await buildAssumeRoleCommand(roleArn);
+		const creds = (await client.send(command))?.Credentials;
+		if (!creds?.AccessKeyId || !creds.SecretAccessKey) throw new Error("AssumeRole returned no Credentials");
+		return {
+			accessKeyId: creds.AccessKeyId,
+			secretAccessKey: creds.SecretAccessKey,
+			...creds.SessionToken !== void 0 && { sessionToken: creds.SessionToken }
+		};
+	} finally {
+		client.destroy?.();
+	}
+}
+async function defaultLambdaClientFactory() {
+	const { LambdaClient } = await import("@aws-sdk/client-lambda");
+	return (region, credentials) => new LambdaClient({
+		region,
+		...credentials && { credentials: {
+			accessKeyId: credentials.accessKeyId,
+			secretAccessKey: credentials.secretAccessKey,
+			...credentials.sessionToken !== void 0 && { sessionToken: credentials.sessionToken }
+		} }
+	});
+}
+async function defaultStsClientFactory() {
+	const { STSClient } = await import("@aws-sdk/client-sts");
+	return (region) => new STSClient({ region });
+}
+async function buildGetLayerVersionCommand(layerArn, versionNumber) {
+	const { GetLayerVersionCommand } = await import("@aws-sdk/client-lambda");
+	return new GetLayerVersionCommand({
+		LayerName: layerArn,
+		VersionNumber: versionNumber
+	});
+}
+async function buildAssumeRoleCommand(roleArn) {
+	const { AssumeRoleCommand } = await import("@aws-sdk/client-sts");
+	return new AssumeRoleCommand({
+		RoleArn: roleArn,
+		RoleSessionName: `cdkd-local-layer-${Date.now()}`,
+		DurationSeconds: 3600
+	});
+}
+async function downloadPresignedZip(presignedUrl, options) {
+	if (options.fetchZip) return options.fetchZip(presignedUrl);
+	const response = await fetch(presignedUrl);
+	if (!response.ok) throw new Error(`HTTP ${response.status} ${response.statusText} from layer Content.Location URL`);
+	const buf = await response.arrayBuffer();
+	return new Uint8Array(buf);
+}
+/**
+* Minimal ZIP unzipper that handles the subset of the ZIP format Lambda
+* layer ZIPs ever use (DEFLATE compression method 8, STORE method 0).
+* Avoids bringing in a heavyweight dep for a 50-line task.
+*
+* Path-traversal guard: every entry's relative path is `normalize()`d
+* and rejected if the resulting absolute path escapes `destDir` (the
+* "Zip Slip" CVE class). Symlinks inside the ZIP are also rejected for
+* the same reason — they could point at arbitrary host paths.
+*/
+async function unzipBufferToDirectory(zipBytes, destDir) {
+	const view = new DataView(zipBytes.buffer, zipBytes.byteOffset, zipBytes.byteLength);
+	const eocdSig = 101010256;
+	const minScan = Math.max(0, zipBytes.byteLength - 65535 - 22);
+	let eocdOffset = -1;
+	for (let i = zipBytes.byteLength - 22; i >= minScan; i--) if (view.getUint32(i, true) === eocdSig) {
+		eocdOffset = i;
+		break;
+	}
+	if (eocdOffset < 0) throw new Error("Not a ZIP file (no End of Central Directory record found)");
+	const totalEntries = view.getUint16(eocdOffset + 10, true);
+	const cdSize = view.getUint32(eocdOffset + 12, true);
+	const cdOffset = view.getUint32(eocdOffset + 16, true);
+	const destAbsolute = resolve(destDir);
+	let cursor = cdOffset;
+	const cdEnd = cdOffset + cdSize;
+	let parsed = 0;
+	while (cursor < cdEnd && parsed < totalEntries) {
+		if (view.getUint32(cursor, true) !== 33639248) throw new Error(`Corrupt ZIP: missing Central Directory header at offset ${cursor}`);
+		const compressionMethod = view.getUint16(cursor + 10, true);
+		const compressedSize = view.getUint32(cursor + 20, true);
+		const uncompressedSize = view.getUint32(cursor + 24, true);
+		const fileNameLength = view.getUint16(cursor + 28, true);
+		const extraFieldLength = view.getUint16(cursor + 30, true);
+		const fileCommentLength = view.getUint16(cursor + 32, true);
+		const externalAttrs = view.getUint32(cursor + 38, true);
+		const localHeaderOffset = view.getUint32(cursor + 42, true);
+		const fileName = new TextDecoder("utf-8").decode(zipBytes.subarray(cursor + 46, cursor + 46 + fileNameLength));
+		cursor += 46 + fileNameLength + extraFieldLength + fileCommentLength;
+		parsed++;
+		const targetPath = resolve(destAbsolute, normalize(fileName));
+		if (!targetPath.startsWith(destAbsolute + (destAbsolute.endsWith("/") ? "" : "/"))) throw new Error(`Refusing to extract entry '${fileName}' — path escapes the destination directory`);
+		if ((externalAttrs >>> 16 & 61440) === 40960) throw new Error(`Refusing to extract symlink entry '${fileName}' from layer ZIP (security)`);
+		if (fileName.endsWith("/")) {
+			await mkdir(targetPath, { recursive: true });
+			continue;
+		}
+		await mkdir(dirname(targetPath), { recursive: true });
+		if (view.getUint32(localHeaderOffset, true) !== 67324752) throw new Error(`Corrupt ZIP: missing Local File Header for '${fileName}'`);
+		const lfhFileNameLength = view.getUint16(localHeaderOffset + 26, true);
+		const lfhExtraFieldLength = view.getUint16(localHeaderOffset + 28, true);
+		const dataOffset = localHeaderOffset + 30 + lfhFileNameLength + lfhExtraFieldLength;
+		const compressedData = zipBytes.subarray(dataOffset, dataOffset + compressedSize);
+		let payload;
+		if (compressionMethod === 0) payload = compressedData;
+		else if (compressionMethod === 8) payload = await inflateRaw(compressedData);
+		else throw new Error(`Unsupported ZIP compression method ${compressionMethod} for entry '${fileName}' (only STORE and DEFLATE supported)`);
+		if (payload.length !== uncompressedSize && compressionMethod !== 0) throw new Error(`ZIP entry '${fileName}': inflate produced ${payload.length} bytes, expected ${uncompressedSize}`);
+		await pipeline(Readable.from(payload), createWriteStream(targetPath));
+	}
+}
+async function inflateRaw(data) {
+	const { inflateRaw: inflate } = await import("node:zlib");
+	return new Promise((resolveP, rejectP) => {
+		inflate(data, (err, out) => {
+			if (err) rejectP(err);
+			else resolveP(out);
+		});
+	});
+}
+function errMsg(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+function looksLikeAccessDenied(err) {
+	if (!(err instanceof Error)) return false;
+	const name = err.name ?? "";
+	const code = err.Code ?? "";
+	const message = err.message ?? "";
+	return name === "AccessDeniedException" || code === "AccessDeniedException" || /access denied/i.test(message) || /not authorized/i.test(message);
+}
+
 //#endregion
 //#region src/local/env-resolver.ts
 /**
@@ -40329,7 +40563,7 @@ function buildHttpApiV2Event(req, ctx, opts = {}) {
 			stage: ctx.route.stage,
 			time: formatRequestTime(now),
 			timeEpoch: now.getTime(),
-			authentication: null,
+			authentication: req.clientCert ? { clientCert: req.clientCert } : null,
 			authorizer: null
 		},
 		body,
@@ -40379,7 +40613,8 @@ function buildRestV1Event(req, ctx, opts = {}) {
 			httpMethod: req.method.toUpperCase(),
 			identity: {
 				sourceIp: req.sourceIp ?? "127.0.0.1",
-				userAgent: headers["user-agent"] ?? ""
+				userAgent: headers["user-agent"] ?? "",
+				...req.clientCert && { clientCert: req.clientCert }
 			},
 			path: `/${ctx.route.stage}${ctx.matchedPath}`,
 			protocol: "HTTP/1.1",
@@ -42571,12 +42806,20 @@ function amzDateOutsideSkew(amzDate, now) {
 async function startApiServer(opts) {
 	const logger = getLogger().child("start-api");
 	let currentState = opts.state;
-	const server = createServer$1((req, res) => {
+	const requestHandler = (req, res) => {
 		handleRequest(req, res, currentState, opts).catch((err) => {
 			logger.error(`Unhandled request error: ${err instanceof Error ? err.stack ?? err.message : String(err)}`);
 			if (!res.headersSent) writeError(res, 502);
 		});
-	});
+	};
+	const server = opts.mtls ? createServer$2({
+		requestCert: true,
+		rejectUnauthorized: true,
+		ca: opts.mtls.caPem,
+		cert: opts.mtls.certPem,
+		key: opts.mtls.keyPem
+	}, requestHandler) : createServer$1(requestHandler);
+	const scheme = opts.mtls ? "https" : "http";
 	server.on("connection", (socket) => {
 		socket.setNoDelay(true);
 	});
@@ -42598,6 +42841,7 @@ async function startApiServer(opts) {
 	return {
 		port: actualPort,
 		host: actualHost,
+		scheme,
 		server,
 		close: async () => {
 			if (closed) return;
@@ -42653,12 +42897,14 @@ async function handleRequest(req, res, state, 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 = {
 		method,
 		rawUrl,
 		headers: collectHeaders(req),
 		body: bodyBuf,
-		...req.socket.remoteAddress !== void 0 && { sourceIp: req.socket.remoteAddress }
+		...req.socket.remoteAddress !== void 0 && { sourceIp: req.socket.remoteAddress },
+		...clientCert && { clientCert }
 	};
 	const matchCtx = {
 		route: match.route,
@@ -43124,6 +43370,135 @@ function writeMockCorsPreflight(res, preflight) {
 	for (const [name, value] of Object.entries(preflight.headers)) res.setHeader(name, value);
 	res.end();
 }
+/**
+* Extract the verified client certificate from a request's TLS socket.
+*
+* Pre-conditions (load-bearing — caller MUST gate on `opts.mtls`):
+*   - The server was started with `https.createServer({requestCert: true,
+*     rejectUnauthorized: true, ...})`, so the TLS handshake has
+*     already rejected unknown-CA / self-signed / missing-cert clients
+*     by the time `handleRequest` runs. Any peer cert we see here is
+*     structurally valid against the supplied CA bundle — we do NOT
+*     re-verify in code.
+*
+* Returns `undefined` when the request was not over a TLS socket (the
+* caller should NOT call this on plain-HTTP requests; the gate is the
+* `opts.mtls` check in `handleRequest`).
+*
+* The returned shape is the AWS-canonical
+* `requestContext.identity.clientCert` per
+* https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mutual-tls.html#api-gateway-mutual-tls-event-shape:
+*
+*   {
+*     clientCertPem: "-----BEGIN CERTIFICATE-----\n...",
+*     subjectDN:     "CN=client,O=example,C=US",
+*     issuerDN:      "CN=My CA,O=example,C=US",
+*     serialNumber:  "01:23:45:67:...",
+*     validity:      { notBefore: "May 22 03:30:00 2026 GMT",
+*                      notAfter:  "May 22 03:30:00 2027 GMT" }
+*   }
+*
+* Exported for unit testing — the helper is pure-functional given a
+* cert object and never touches the network.
+*/
+function extractClientCert(req) {
+	const socket = req.socket;
+	if (typeof socket.getPeerCertificate !== "function") return void 0;
+	return peerCertificateToAws(socket.getPeerCertificate(false));
+}
+/**
+* Convert Node's `PeerCertificate` object to the AWS-canonical
+* `clientCert` event shape. Exported separately from
+* {@link extractClientCert} so the conversion can be unit-tested
+* against a synthetic cert object without a real TLS socket.
+*
+* Returns `undefined` when the cert is empty (`getPeerCertificate`
+* returns `{}` when there is no peer cert). Otherwise emits every
+* field defined by the AWS shape, falling back to `''` for missing
+* subject / issuer DN segments so handlers do not need to null-check.
+*/
+function peerCertificateToAws(cert) {
+	if (!cert || typeof cert !== "object") return void 0;
+	if (Object.keys(cert).length === 0) return void 0;
+	const c = cert;
+	const subject = c["subject"];
+	const issuer = c["issuer"];
+	const raw = c["raw"];
+	const subjectDN = formatDN(subject);
+	const issuerDN = formatDN(issuer);
+	const serialNumber = typeof c["serialNumber"] === "string" ? c["serialNumber"] : "";
+	const validity = {
+		notBefore: typeof c["valid_from"] === "string" ? c["valid_from"] : "",
+		notAfter: typeof c["valid_to"] === "string" ? c["valid_to"] : ""
+	};
+	return {
+		clientCertPem: Buffer.isBuffer(raw) ? derBufferToPem(raw) : "",
+		subjectDN,
+		issuerDN,
+		serialNumber,
+		validity
+	};
+}
+/**
+* Format a Node `subject` / `issuer` object (e.g.
+* `{C: 'US', O: 'example', CN: 'client'}`) as the canonical
+* comma-separated DN string AWS emits (`CN=client,O=example,C=US`).
+*
+* Ordering follows AWS / OpenSSL convention: CN first, then OU, O, L,
+* ST, C. Fields the cert does not declare are skipped silently.
+*/
+function formatDN(dn) {
+	if (!dn || typeof dn !== "object") return "";
+	const obj = dn;
+	const order = [
+		"CN",
+		"OU",
+		"O",
+		"L",
+		"ST",
+		"C"
+	];
+	const parts = [];
+	for (const key of order) {
+		const v = obj[key];
+		if (typeof v === "string" && v.length > 0) parts.push(`${key}=${v}`);
+	}
+	return parts.join(",");
+}
+/**
+* Encode a DER-encoded certificate Buffer as PEM. We wrap the base64
+* in 64-char-per-line segments the way `openssl x509` does so the
+* round-trip looks like what AWS API Gateway emits.
+*/
+function derBufferToPem(der) {
+	const b64 = der.toString("base64");
+	const lines = [];
+	for (let i = 0; i < b64.length; i += 64) lines.push(b64.slice(i, i + 64));
+	return `-----BEGIN CERTIFICATE-----\n${lines.join("\n")}\n-----END CERTIFICATE-----\n`;
+}
+/**
+* Read mTLS materials from disk. Each path is a PEM file. The function
+* throws a wrapped error naming the offending path on `ENOENT` /
+* permission failures so the CLI surfaces a clear error before the
+* server starts.
+*
+* Exported for the CLI's resolve-then-construct flow + for unit tests.
+*/
+function readMtlsMaterialsFromDisk(opts) {
+	return {
+		caPem: readPemOrThrow(opts.truststorePath, "--mtls-truststore"),
+		certPem: readPemOrThrow(opts.certPath, "--mtls-cert"),
+		keyPem: readPemOrThrow(opts.keyPath, "--mtls-key")
+	};
+}
+function readPemOrThrow(path, flagName) {
+	try {
+		return readFileSync(path);
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		throw new Error(`${flagName}: cannot read PEM file at '${path}': ${msg}`);
+	}
+}
 
 //#endregion
 //#region src/local/api-server-grouping.ts
@@ -43667,7 +44042,8 @@ async function localStartApiCommand(target, options) {
 				stsRegion: options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"],
 				inlineTmpDirs,
 				layerTmpDirs,
-				stateByStack
+				stateByStack,
+				...options.layerRoleArn !== void 0 && { layerRoleArn: options.layerRoleArn }
 			});
 			specs.set(logicalId, spec);
 		}
@@ -43721,6 +44097,8 @@ async function localStartApiCommand(target, options) {
 	const rieTimeoutMs = Math.max(3e4, maxTimeoutSec * 2 * 1e3);
 	const basePort = parseInt(options.port, 10);
 	if (!Number.isFinite(basePort) || basePort < 0 || basePort > 65535) throw new Error(`--port must be 0..65535 (got ${options.port}).`);
+	const mtlsConfig = resolveMtlsConfig(options);
+	if (mtlsConfig) logger.info("mTLS enabled: client certificates required (chain check against --mtls-truststore at TLS handshake).");
 	const initialGroups = groupRoutesByServer(initialMaterial.routes);
 	const servers = [];
 	let nextPort = basePort;
@@ -43742,6 +44120,7 @@ async function localStartApiCommand(target, options) {
 			state: groupState,
 			rieTimeoutMs,
 			host: options.host,
+			...mtlsConfig && { mtls: mtlsConfig },
 			port: basePort === 0 ? 0 : nextPort,
 			authorizerCache,
 			jwksCache,
@@ -43759,7 +44138,7 @@ async function localStartApiCommand(target, options) {
 	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`);
+	for (const { group, server } of servers) process.stdout.write(`Server listening on ${server.scheme}://${server.host}:${server.port}  (${group.displayName})\n`);
 	process.stdout.write("^C to stop and clean up containers.\n");
 	let watcher;
 	let reloadChain = Promise.resolve();
@@ -43977,10 +44356,10 @@ function warnIamRoutes(routesWithAuth) {
 * missing, runtime not supported).
 */
 async function buildContainerSpec(args) {
-	const { logicalId, stacks, overrides, assumeRole, containerHost, debugPort, stsRegion, inlineTmpDirs, layerTmpDirs, stateByStack } = args;
+	const { logicalId, stacks, overrides, assumeRole, containerHost, debugPort, stsRegion, inlineTmpDirs, layerTmpDirs, stateByStack, layerRoleArn } = args;
 	const lambda = resolveLambdaByLogicalId(logicalId, stacks);
 	const codeDir = lambda.codePath ?? materializeInlineCode$1(lambda.handler, lambda.inlineCode ?? "", resolveRuntimeFileExtension(lambda.runtime), inlineTmpDirs);
-	const optDir = materializeLambdaLayers$1(lambda.layers, layerTmpDirs);
+	const optDir = await materializeLambdaLayers$1(lambda.layers, layerTmpDirs, layerRoleArn);
 	let templateEnv = getTemplateEnv$1(lambda.resource);
 	const stateBundle = stateByStack.get(lambda.stack.stackName);
 	let stateAudit;
@@ -44039,22 +44418,46 @@ async function buildContainerSpec(args) {
 *
 * Three branches:
 *   - 0 layers → `undefined` (no `/opt` mount).
-*   - 1 layer → bind-mount the layer's asset dir directly (no copy).
+*   - 1 layer → bind-mount the layer's asset dir directly (no copy)
+*     when the entry is a same-stack asset. Literal-ARN entries always
+*     pre-materialize first.
 *   - 2+ layers → copy each into a fresh tmpdir IN ORDER (later
 *     layers overwrite earlier files via `cpSync({force: true})`),
 *     bind-mount the tmpdir at `/opt`. Records the tmpdir in
 *     `layerTmpDirs` so `shutdown(...)` removes it.
 *
+* Issue #448: literal-ARN entries (`{kind: 'arn', ...}`) are downloaded
+* + unzipped via `lambda:GetLayerVersion` BEFORE the cpSync-merge
+* branches run. Every per-ARN tmpdir is also recorded in `layerTmpDirs`
+* so the same shutdown path cleans it up — even for the single-layer
+* fast path that bind-mounts the dir directly.
+*
 * AWS Lambda's actual runtime extracts every layer ZIP into `/opt`
 * in template order — the merge mirrors that. Docker rejects multiple
 * `-v ...:/opt:ro` entries at the same target, so cdkd can't rely on
 * overlay layering and must produce a single merged dir on the host.
 */
-function materializeLambdaLayers$1(layers, layerTmpDirs) {
+async function materializeLambdaLayers$1(layers, layerTmpDirs, layerRoleArn) {
 	if (layers.length === 0) return void 0;
-	if (layers.length === 1) return layers[0].assetPath;
+	const flat = [];
+	for (const layer of layers) {
+		if (layer.kind === "asset") {
+			flat.push({
+				logicalId: layer.logicalId,
+				assetPath: layer.assetPath
+			});
+			continue;
+		}
+		const dir = await materializeLayerFromArn(layer, { ...layerRoleArn !== void 0 && { roleArn: layerRoleArn } });
+		layerTmpDirs.add(dir);
+		flat.push({
+			logicalId: layer.arn,
+			assetPath: dir
+		});
+	}
+	if (flat.length === 1) return flat[0].assetPath;
 	const dir = mkdtempSync(path.join(tmpdir(), "cdkd-local-start-api-layers-"));
-	for (const layer of layers) cpSync(layer.assetPath, dir, {
+	for (const layer of flat) cpSync(layer.assetPath, dir, {
 		recursive: true,
 		force: true
 	});
@@ -44456,10 +44859,36 @@ function parseDebugPort(raw) {
 	return parsed;
 }
 /**
+* Resolve the mTLS configuration from CLI options. Returns `undefined`
+* when none of the three `--mtls-*` flags is set (the server stays
+* plain-HTTP). When any of the three is set, ALL THREE must be set —
+* partial configurations are rejected at parse time so the server
+* never boots in a half-configured state.
+*
+* Exported for unit testing.
+*/
+function resolveMtlsConfig(options) {
+	const present = [];
+	const absent = [];
+	if (options.mtlsTruststore !== void 0 && options.mtlsTruststore !== "") present.push("--mtls-truststore");
+	else absent.push("--mtls-truststore");
+	if (options.mtlsCert !== void 0 && options.mtlsCert !== "") present.push("--mtls-cert");
+	else absent.push("--mtls-cert");
+	if (options.mtlsKey !== void 0 && options.mtlsKey !== "") present.push("--mtls-key");
+	else absent.push("--mtls-key");
+	if (present.length === 0) return void 0;
+	if (absent.length > 0) throw new Error(`mTLS configuration is incomplete: ${present.join(", ")} set but ${absent.join(", ")} missing. All three of --mtls-truststore, --mtls-cert, and --mtls-key must be set together to enable mTLS, or all three left unset for plain HTTP.`);
+	return readMtlsMaterialsFromDisk({
+		truststorePath: options.mtlsTruststore,
+		certPath: options.mtlsCert,
+		keyPath: options.mtlsKey
+	});
+}
+/**
 * Builder for the `start-api` subcommand. Wired up by `local.ts`.
 */
 function createLocalStartApiCommand() {
-	const startApi = new Command("start-api").description("Run a long-running local HTTP server that maps API Gateway routes (REST v1, HTTP API, Function URL) to Lambda invocations against the AWS Lambda Runtime Interface Emulator (Docker required). Supports Lambda TOKEN/REQUEST authorizers, Cognito User Pool / HTTP v2 JWT authorizers, and REST v1 AWS_IAM (SigV4 signature verification only — IAM policy evaluation is NOT emulated; see docs/local-emulation.md). When JWKS is unreachable, JWT authorizers fall back to pass-through (every token accepted) with a warn line — local dev fallback. VPC-config Lambdas run locally and surface a warn line at startup; their containers do NOT get attached to the deployed VPC subnets, so calls to private RDS / ElastiCache will fail.").argument("[target]", "Optional API filter. Accepts the bare CDK logical id ('MyHttpApi'; single-stack apps only), stack-qualified logical id ('MyStack:MyHttpApi'), full CDK Construct path ('MyStack/MyHttpApi/Resource'), or an ancestor Construct path that prefix-matches ('MyStack/MyHttpApi'). When omitted, every discovered API gets its own server. Mirrors `cdkd local invoke` / `cdkd local run-task` target syntax.").addOption(new Option("--port <port>", "HTTP server port (default: auto-allocate)").default("0")).addOption(new Option("--host <host>", "Bind address").default("127.0.0.1")).addOption(new Option("--stack <name>", "Stack to start (single-stack apps auto-detect)")).addOption(new Option("--warm", "Pre-start one container per Lambda at server boot").default(false)).addOption(new Option("--per-lambda-concurrency <n>", "Pool size cap per Lambda (default 2, max 4)").default("2")).addOption(new Option("--no-pull", "Skip docker pull (cached image)")).addOption(new Option("--container-host <host>", "IP the host uses to bind/probe the RIE port (must be a numeric IP — `docker run -p <ip>:<port>:8080` rejects hostnames). Defaults to 127.0.0.1.").default("127.0.0.1")).addOption(new Option("--debug-port-base <port>", "Reserve a contiguous --debug-port range (one per Lambda)")).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}, \"Parameters\": {...}})")).addOption(new Option("--assume-role <arn-or-pair>", "Assume the Lambda's execution role and forward STS-issued temp creds. Bare <arn> = global default; <LogicalId>=<arn> = per-Lambda override (repeatable). Per-Lambda > global > unset (developer creds passed through).").argParser((raw, prev) => parseAssumeRoleToken(raw, prev))).addOption(new Option("--watch", "Hot-reload: re-synth + re-discover routes when cdk.out/ or asset directories change. Off by default; the server keeps the previous version serving when synth fails mid-reload.").default(false)).addOption(new Option("--stage <name>", "Select an API Gateway Stage by its 'StageName'. Default: the first Stage attached to each API. Drives event.stageVariables for both REST v1 and HTTP API v2. NOTE: For HTTP API v2 routes, requestContext.stage is always '$default' regardless of this flag (AWS-side limitation — HTTP API only exposes one stage to the integration event); only event.stageVariables is affected for v2 routes. For REST v1 routes the selected StageName is also threaded into requestContext.stage.")).addOption(new Option("--api <id>", "DEPRECATED — use the positional <target> argument instead. Same accepted forms (bare logical id, stack-qualified, Construct path, ancestor prefix). Will be removed in a future major release.")).addOption(new Option("--from-state", "Read cdkd S3 state for every routed stack and substitute Ref / Fn::GetAtt / Fn::Sub / Fn::Join (and AWS pseudo parameters) in Lambda env vars with the deployed physical IDs / attributes. Off by default — pre-PR warn-and-drop semantics are preserved. Turn on for stacks already deployed via cdkd deploy. Mirrors `cdkd local invoke --from-state` / `cdkd local run-task --from-state`. Re-runs against fresh state on every hot-reload firing (--watch).").default(false)).addOption(new Option("--stack-region <region>", "Region of the cdkd state record to read (used with --from-state when the same stack name has state in multiple regions).")).addOption(new Option("--allow-unverified-sigv4", "Opt-in: allow AWS_IAM SigV4 requests that cannot be cryptographically verified (foreign access-key-id, OR no local AWS credentials configured) to pass through with a placeholder principalId. DEFAULT off — fail-closed so unauthenticated bypass is impossible against `event.requestContext.identity.accessKey`-trusting handler code. Use only in dev loops where you understand the risk.").default(false)).action(withErrorHandling(localStartApiCommand));
+	const startApi = new Command("start-api").description("Run a long-running local HTTP server that maps API Gateway routes (REST v1, HTTP API, Function URL) to Lambda invocations against the AWS Lambda Runtime Interface Emulator (Docker required). Supports Lambda TOKEN/REQUEST authorizers, Cognito User Pool / HTTP v2 JWT authorizers, and REST v1 AWS_IAM (SigV4 signature verification only — IAM policy evaluation is NOT emulated; see docs/local-emulation.md). When JWKS is unreachable, JWT authorizers fall back to pass-through (every token accepted) with a warn line — local dev fallback. VPC-config Lambdas run locally and surface a warn line at startup; their containers do NOT get attached to the deployed VPC subnets, so calls to private RDS / ElastiCache will fail.").argument("[target]", "Optional API filter. Accepts the bare CDK logical id ('MyHttpApi'; single-stack apps only), stack-qualified logical id ('MyStack:MyHttpApi'), full CDK Construct path ('MyStack/MyHttpApi/Resource'), or an ancestor Construct path that prefix-matches ('MyStack/MyHttpApi'). When omitted, every discovered API gets its own server. Mirrors `cdkd local invoke` / `cdkd local run-task` target syntax.").addOption(new Option("--port <port>", "HTTP server port (default: auto-allocate)").default("0")).addOption(new Option("--host <host>", "Bind address").default("127.0.0.1")).addOption(new Option("--stack <name>", "Stack to start (single-stack apps auto-detect)")).addOption(new Option("--warm", "Pre-start one container per Lambda at server boot").default(false)).addOption(new Option("--per-lambda-concurrency <n>", "Pool size cap per Lambda (default 2, max 4)").default("2")).addOption(new Option("--no-pull", "Skip docker pull (cached image)")).addOption(new Option("--container-host <host>", "IP the host uses to bind/probe the RIE port (must be a numeric IP — `docker run -p <ip>:<port>:8080` rejects hostnames). Defaults to 127.0.0.1.").default("127.0.0.1")).addOption(new Option("--debug-port-base <port>", "Reserve a contiguous --debug-port range (one per Lambda)")).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}, \"Parameters\": {...}})")).addOption(new Option("--assume-role <arn-or-pair>", "Assume the Lambda's execution role and forward STS-issued temp creds. Bare <arn> = global default; <LogicalId>=<arn> = per-Lambda override (repeatable). Per-Lambda > global > unset (developer creds passed through).").argParser((raw, prev) => parseAssumeRoleToken(raw, prev))).addOption(new Option("--watch", "Hot-reload: re-synth + re-discover routes when cdk.out/ or asset directories change. Off by default; the server keeps the previous version serving when synth fails mid-reload.").default(false)).addOption(new Option("--stage <name>", "Select an API Gateway Stage by its 'StageName'. Default: the first Stage attached to each API. Drives event.stageVariables for both REST v1 and HTTP API v2. NOTE: For HTTP API v2 routes, requestContext.stage is always '$default' regardless of this flag (AWS-side limitation — HTTP API only exposes one stage to the integration event); only event.stageVariables is affected for v2 routes. For REST v1 routes the selected StageName is also threaded into requestContext.stage.")).addOption(new Option("--api <id>", "DEPRECATED — use the positional <target> argument instead. Same accepted forms (bare logical id, stack-qualified, Construct path, ancestor prefix). Will be removed in a future major release.")).addOption(new Option("--layer-role-arn <arn>", "Role to sts:AssumeRole before calling lambda:GetLayerVersion on every literal-ARN entry in Properties.Layers (issue #448). Use only when the dev credentials cannot read the layer — typically cross-account layers. AWS-published public layers (e.g. Lambda Powertools) are readable from every account and need no role.")).addOption(new Option("--from-state", "Read cdkd S3 state for every routed stack and substitute Ref / Fn::GetAtt / Fn::Sub / Fn::Join (and AWS pseudo parameters) in Lambda env vars with the deployed physical IDs / attributes. Off by default — pre-PR warn-and-drop semantics are preserved. Turn on for stacks already deployed via cdkd deploy. Mirrors `cdkd local invoke --from-state` / `cdkd local run-task --from-state`. Re-runs against fresh state on every hot-reload firing (--watch).").default(false)).addOption(new Option("--stack-region <region>", "Region of the cdkd state record to read (used with --from-state when the same stack name has state in multiple regions).")).addOption(new Option("--mtls-truststore <path>", "PEM-encoded CA bundle for client-certificate verification (mutual TLS). When set, the local server switches from HTTP to HTTPS and the TLS handshake rejects clients whose certificate doesn't chain to one of these CAs. Verified certs are surfaced on the Lambda event under requestContext.identity.clientCert (REST v1) / requestContext.authentication.clientCert (HTTP API v2). Must be set together with --mtls-cert + --mtls-key; partial flag sets are rejected. Generate a CA + server + client cert for local dev: openssl req -x509 -newkey rsa:2048 -nodes -keyout ca-key.pem -out ca.pem -subj \"/CN=cdkd-local-ca\" -days 365; openssl req -newkey rsa:2048 -nodes -keyout server-key.pem -out server-csr.pem -subj \"/CN=localhost\"; openssl x509 -req -in server-csr.pem -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out server-cert.pem -days 365; openssl req -newkey rsa:2048 -nodes -keyout client-key.pem -out client-csr.pem -subj \"/CN=client\"; openssl x509 -req -in client-csr.pem -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out client-cert.pem -days 365; curl --cacert ca.pem --cert client-cert.pem --key client-key.pem https://localhost:<port>/...")).addOption(new Option("--mtls-cert <path>", "PEM-encoded server certificate for mutual TLS. Self-signed is fine for local dev. Must be set together with --mtls-truststore + --mtls-key.")).addOption(new Option("--mtls-key <path>", "PEM-encoded server private key matching --mtls-cert. Must be set together with --mtls-truststore + --mtls-cert.")).addOption(new Option("--allow-unverified-sigv4", "Opt-in: allow AWS_IAM SigV4 requests that cannot be cryptographically verified (foreign access-key-id, OR no local AWS credentials configured) to pass through with a placeholder principalId. DEFAULT off — fail-closed so unauthenticated bypass is impossible against `event.requestContext.identity.accessKey`-trusting handler code. Use only in dev loops where you understand the risk.").default(false)).action(withErrorHandling(localStartApiCommand));
 	[
 		...commonOptions,
 		...appOptions,
@@ -45562,6 +45991,14 @@ async function localInvokeCommand(target, options) {
 		} catch (err) {
 			getLogger().debug(`Failed to remove merged-layers tmpdir ${imagePlan.layersTmpDir}: ${err instanceof Error ? err.message : String(err)}`);
 		}
+		if (imagePlan?.layerArnTmpDirs) for (const dir of imagePlan.layerArnTmpDirs) try {
+			rmSync(dir, {
+				recursive: true,
+				force: true
+			});
+		} catch (err) {
+			getLogger().debug(`Failed to remove ARN-layer tmpdir ${dir}: ${err instanceof Error ? err.message : String(err)}`);
+		}
 	}, (err) => {
 		getLogger().debug(`cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
 	});
@@ -45747,7 +46184,7 @@ async function resolveZipImagePlan(lambda, options) {
 	}
 	const image = resolveRuntimeImage(lambda.runtime);
 	await pullImage(image, options.pull === false);
-	const layerPlan = materializeLambdaLayers(lambda.layers);
+	const layerPlan = await materializeLambdaLayersIncludingArns(lambda.layers, options);
 	const containerCodePath = resolveRuntimeCodeMountPath(lambda.runtime);
 	const tmpfs = resolveTmpfsForLambda(lambda);
 	return {
@@ -45761,10 +46198,48 @@ async function resolveZipImagePlan(lambda, options) {
 		cmd: [lambda.handler],
 		...inlineTmpDir !== void 0 && { inlineTmpDir },
 		...layerPlan.tmpDir !== void 0 && { layersTmpDir: layerPlan.tmpDir },
+		...layerPlan.extraTmpDirs.length > 0 && { layerArnTmpDirs: layerPlan.extraTmpDirs },
 		...tmpfs !== void 0 && { tmpfs }
 	};
 }
 /**
+* Two-stage layer materialization (issue #448).
+*
+*   - Stage 1: every `{kind: 'arn'}` entry is downloaded + unzipped
+*     into its own tmpdir via `materializeLayerFromArn`. The per-ARN
+*     tmpdirs are tracked in `extraTmpDirs` so the outer cleanup can
+*     remove them.
+*   - Stage 2: the resulting `{logicalId, assetPath}[]` list (in
+*     template order — ARN entries surface their `arn` as the
+*     `logicalId` for log lines) is handed to the existing
+*     `materializeLambdaLayers` `cpSync`-merge path. AWS's "last layer
+*     wins" file-collision semantic is preserved across both layer
+*     kinds because the merge step is unchanged.
+*/
+async function materializeLambdaLayersIncludingArns(layers, options) {
+	const extraTmpDirs = [];
+	const flat = [];
+	for (const layer of layers) {
+		if (layer.kind === "asset") {
+			flat.push({
+				logicalId: layer.logicalId,
+				assetPath: layer.assetPath
+			});
+			continue;
+		}
+		const dir = await materializeLayerFromArn(layer, { ...options.layerRoleArn !== void 0 && { roleArn: options.layerRoleArn } });
+		extraTmpDirs.push(dir);
+		flat.push({
+			logicalId: layer.arn,
+			assetPath: dir
+		});
+	}
+	return {
+		...materializeLambdaLayers(flat),
+		extraTmpDirs
+	};
+}
+/**
 * Build the `--tmpfs /tmp:rw,size=<N>m` plan for a Lambda (issue #440).
 *
 * The shape is identical for ZIP and IMAGE Lambdas — `--tmpfs` overlays
@@ -46172,7 +46647,7 @@ function pickReferencedLogicalId(intrinsic) {
 */
 function createLocalCommand() {
 	const local = new Command("local").description("Local execution of Lambda functions (RIE) and ECS task definitions (Docker required)");
-	const invoke = new Command("invoke").description("Run a Lambda function locally in a Docker container (RIE-backed). Target accepts a CDK display path (MyStack/MyApi/Handler) or stack-qualified logical ID (MyStack:MyApiHandler1234ABCD). Single-stack apps may omit the stack prefix.").argument("<target>", "CDK display path or stack-qualified logical ID of the Lambda to invoke").addOption(new Option("-e, --event <file>", "JSON event payload file (default: {})")).addOption(new Option("--event-stdin", "Read event JSON from stdin").default(false)).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}})")).addOption(new Option("--no-pull", "Skip docker pull (use cached image) — no-op for IMAGE local-build path; `docker build` does not pull base layers by default")).addOption(new Option("--no-build", "Skip docker build on the IMAGE local-build path (use the previously-built tag). Requires the deterministic tag to already be in the local registry; errors with an actionable message when missing. No-op for ZIP Lambdas and the IMAGE ECR-pull path. Compatible with --no-pull.")).addOption(new Option("--debug-port <port>", "Node --inspect-brk port (default: off)")).addOption(new Option("--container-host <host>", "Host to bind the RIE port to").default("127.0.0.1")).addOption(new Option("--assume-role [arn]", "Assume the Lambda's deployed execution role and forward STS-issued temp credentials to the container so the handler runs with the deployed function's narrow permissions (closes the \"developer admin / function narrow\" skew). Three forms: (1) `--assume-role <arn>` assumes the explicit ARN; (2) `--assume-role` (bare) auto-resolves the function's execution role ARN from cdkd state (requires --from-state); (3) `--no-assume-role` explicitly opts out (forces dev creds even with --from-state). Off by default — when omitted, the developer's shell credentials are forwarded unchanged (SAM-compatible default). STS failures degrade to a warn + dev-creds fallback.")).addOption(new Option("--ecr-role-arn <arn>", "Role ARN to assume before authenticating against ECR for cross-account / centralized registries (#455). Issues sts:AssumeRole via the default credential chain and uses the temporary credentials for ecr:GetAuthorizationToken + docker pull. Required when the caller does not have direct cross-account access to the target repository. Same-account / same-region pulls do not need this flag.")).addOption(new Option("--from-state", "Read cdkd S3 state for the target stack and substitute Ref / Fn::GetAtt / Fn::Sub in env vars with the deployed physical IDs / attributes. Off by default — keep PR 1 warn-and-drop semantics; turn on for stacks already deployed via cdkd deploy.").default(false)).addOption(new Option("--stack-region <region>", "Region of the cdkd state record to read (used with --from-state when the same stack name has state in multiple regions).")).action(withErrorHandling(localInvokeCommand));
+	const invoke = new Command("invoke").description("Run a Lambda function locally in a Docker container (RIE-backed). Target accepts a CDK display path (MyStack/MyApi/Handler) or stack-qualified logical ID (MyStack:MyApiHandler1234ABCD). Single-stack apps may omit the stack prefix.").argument("<target>", "CDK display path or stack-qualified logical ID of the Lambda to invoke").addOption(new Option("-e, --event <file>", "JSON event payload file (default: {})")).addOption(new Option("--event-stdin", "Read event JSON from stdin").default(false)).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}})")).addOption(new Option("--no-pull", "Skip docker pull (use cached image) — no-op for IMAGE local-build path; `docker build` does not pull base layers by default")).addOption(new Option("--no-build", "Skip docker build on the IMAGE local-build path (use the previously-built tag). Requires the deterministic tag to already be in the local registry; errors with an actionable message when missing. No-op for ZIP Lambdas and the IMAGE ECR-pull path. Compatible with --no-pull.")).addOption(new Option("--debug-port <port>", "Node --inspect-brk port (default: off)")).addOption(new Option("--container-host <host>", "Host to bind the RIE port to").default("127.0.0.1")).addOption(new Option("--assume-role [arn]", "Assume the Lambda's deployed execution role and forward STS-issued temp credentials to the container so the handler runs with the deployed function's narrow permissions (closes the \"developer admin / function narrow\" skew). Three forms: (1) `--assume-role <arn>` assumes the explicit ARN; (2) `--assume-role` (bare) auto-resolves the function's execution role ARN from cdkd state (requires --from-state); (3) `--no-assume-role` explicitly opts out (forces dev creds even with --from-state). Off by default — when omitted, the developer's shell credentials are forwarded unchanged (SAM-compatible default). STS failures degrade to a warn + dev-creds fallback.")).addOption(new Option("--layer-role-arn <arn>", "Role to sts:AssumeRole before calling lambda:GetLayerVersion on every literal-ARN entry in Properties.Layers (issue #448). Use only when the dev credentials cannot read the layer — typically cross-account layers. AWS-published public layers (e.g. Lambda Powertools) are readable from every account and need no role.")).addOption(new Option("--ecr-role-arn <arn>", "Role ARN to assume before authenticating against ECR for cross-account / centralized registries (#455). Issues sts:AssumeRole via the default credential chain and uses the temporary credentials for ecr:GetAuthorizationToken + docker pull. Required when the caller does not have direct cross-account access to the target repository. Same-account / same-region pulls do not need this flag.")).addOption(new Option("--from-state", "Read cdkd S3 state for the target stack and substitute Ref / Fn::GetAtt / Fn::Sub in env vars with the deployed physical IDs / attributes. Off by default — keep PR 1 warn-and-drop semantics; turn on for stacks already deployed via cdkd deploy.").default(false)).addOption(new Option("--stack-region <region>", "Region of the cdkd state record to read (used with --from-state when the same stack name has state in multiple regions).")).action(withErrorHandling(localInvokeCommand));
 	[
 		...commonOptions,
 		...appOptions,
@@ -47464,7 +47939,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.124.0");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.126.0");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());