@go-to-k/cdkd 0.125.0 → 0.126.0

package/dist/cli.js

@@ -65,6 +65,7 @@ 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
@@ -40562,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,
@@ -40612,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",
@@ -42804,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);
 	});
@@ -42831,6 +42841,7 @@ async function startApiServer(opts) {
 	return {
 		port: actualPort,
 		host: actualHost,
+		scheme,
 		server,
 		close: async () => {
 			if (closed) return;
@@ -42886,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,
@@ -43357,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
@@ -43955,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;
@@ -43976,6 +44120,7 @@ async function localStartApiCommand(target, options) {
 			state: groupState,
 			rieTimeoutMs,
 			host: options.host,
+			...mtlsConfig && { mtls: mtlsConfig },
 			port: basePort === 0 ? 0 : nextPort,
 			authorizerCache,
 			jwksCache,
@@ -43993,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();
@@ -44714,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("--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("--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,
@@ -47768,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.125.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());