cdk-local 0.5.1 → 0.6.0

package/README.md

@@ -22,7 +22,7 @@ cdk-local deliberately does NOT emulate AWS managed services. The bet is: keep d
 It also picks up where `sam local` leaves off:
 
 - **CDK-native** — point it at your CDK app's `cdk.json`. No SAM templates, no extra config files.
-- **Wider coverage** — Lambda (ZIP + container image), API Gateway REST v1 / HTTP v2 / Function URL / WebSocket API, ECS run-task, ECS service with Service Connect + Cloud Map.
+- **Wider coverage** — Lambda (ZIP + container image, plus Function URL), API Gateway REST v1 / HTTP v2 / WebSocket API, ECS run-task, ECS service with Service Connect + Cloud Map.
 - **Real container images** — Lambda code runs in the real `public.ecr.aws/lambda/*` base image via Lambda Runtime Interface Emulator (RIE). ECS tasks run as real Docker containers. The only dependency is Docker.
 
 ## What runs locally, what doesn't
@@ -32,7 +32,7 @@ cdk-local runs your **application compute** locally in Docker, using your CDK ap
 **Runs locally (application compute):**
 
 - **Lambda functions** — your code in a real `public.ecr.aws/lambda/*` container via the Lambda Runtime Interface Emulator
-- **API Gateway** — REST v1 / HTTP v2 / Function URL / WebSocket served by a local HTTP server
+- **HTTP APIs & Function URLs** — API Gateway REST v1 / HTTP v2 / WebSocket and Lambda Function URLs served by a local HTTP server
 - **ECS** — tasks and services as real Docker containers (awsvpc / Service Connect / Cloud Map registry)
 - **Authorizers** — Lambda authorizers, Cognito User Pool JWT verification, IAM SigV4 verification
 
@@ -66,14 +66,31 @@ cdkl invoke MyStack/MyFunction --event ./event.json
 
 ![cdkl invoke against a local sample CDK app — no AWS account, no deploy](assets/cdkl-invoke.gif)
 
-#### API Gateway — `start-api`
+#### HTTP APIs & Function URLs — `start-api`
 
-Serve your API Gateway routes (REST v1 / HTTP v2 / Function URL / WebSocket) on a local HTTP server.
+Serve your app's HTTP surface locally — API Gateway routes (REST v1 / HTTP v2 / WebSocket) and Lambda Function URLs — on a local HTTP server.
 
 ```bash
+# Single-stack app: serve every API in the stack (each on its own port)
+cdkl start-api
+
+# Or target one API
 cdkl start-api MyStack/MyApi
 ```
 
+In a multi-stack app, a bare `cdkl start-api` errors out rather than serving every stack's API at once (so a side-stack's API is never booted by accident). Either serve them all explicitly, or pick one stack with the first selector you supply:
+
+```bash
+# Serve every stack's API (each on its own port)
+cdkl start-api --all-stacks
+```
+
+- `--stack <name>` — the synth stack name, matched against your CDK app.
+- `--from-cfn-stack <name>` — the deployed CloudFormation stack name; doubles as the stack selector (see [section 2](#2-bound-to-a-deployed-stack)).
+- a stack-qualified target like `MyStack/MyApi` — the `MyStack` prefix selects the stack.
+
+`--all-stacks` is mutually exclusive with those single-target selectors (the bare `--from-cfn-stack` flag stays compatible). See [docs/cli-reference.md](docs/cli-reference.md) for the full precedence rules.
+
 #### ECS — `run-task` / `start-service`
 
 Run an ECS task definition once, or start a long-running service with Service Connect / Cloud Map registry.
@@ -91,7 +108,7 @@ Use this for fast iteration on Lambda code, API routing checks, and container ta
 
 Once your stack is deployed to AWS (via the AWS CDK CLI or any other tool), pass `--from-cfn-stack <StackName>` and cdk-local reads the deployed CloudFormation stack to inject real ARNs, Secrets values, and IAM credentials (resolved from your current AWS profile) into the local execution.
 
-#### API Gateway — `start-api` (the headline use case)
+#### HTTP APIs & Function URLs — `start-api` (the headline use case)
 
 A local API talking to real AWS — point a frontend at it for end-to-end debugging, including real Cognito JWT verification.
 

package/dist/cli.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
-import { i as createLocalInvokeCommand, n as createLocalRunTaskCommand, r as createLocalStartApiCommand, t as createLocalStartServiceCommand } from "./local-start-service-gYRarUgM.js";
+import { i as createLocalInvokeCommand, n as createLocalRunTaskCommand, r as createLocalStartApiCommand, t as createLocalStartServiceCommand } from "./local-start-service-irdy6U57.js";
 import { Command } from "commander";
 
 //#region src/cli/index.ts
 const program = new Command();
-program.name("cdkl").description("Run AWS CDK stacks locally with Docker.").version("0.5.1");
+program.name("cdkl").description("Run AWS CDK stacks locally with Docker.").version("0.6.0");
 program.addCommand(createLocalInvokeCommand());
 program.addCommand(createLocalStartApiCommand());
 program.addCommand(createLocalRunTaskCommand());

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types/state.ts","../src/local/state-resolver.ts","../src/local/local-state-provider.ts","../src/cli/commands/local-state-source.ts","../src/local/embed-config.ts","../src/cli/commands/local-invoke.ts","../src/cli/commands/local-start-api.ts","../src/cli/commands/local-run-task.ts","../src/cli/commands/local-start-service.ts","../src/local/cfn-local-state-provider.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types/state.ts","../src/local/state-resolver.ts","../src/local/local-state-provider.ts","../src/cli/commands/local-state-source.ts","../src/local/embed-config.ts","../src/cli/commands/local-invoke.ts","../src/cli/commands/local-start-api.ts","../src/cli/commands/local-run-task.ts","../src/cli/commands/local-start-service.ts","../src/local/cfn-local-state-provider.ts"],"mappings":"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"}

package/dist/index.js

@@ -1,3 +1,3 @@
-import { a as LocalStateSourceError, c as rejectExplicitCfnStackWithMultipleStacks, d as CfnLocalStateProvider, i as createLocalInvokeCommand, l as resolveCfnRegion, n as createLocalRunTaskCommand, o as createLocalStateProvider, r as createLocalStartApiCommand, s as isCfnFlagPresent, t as createLocalStartServiceCommand, u as resolveCfnStackName } from "./local-start-service-gYRarUgM.js";
+import { a as LocalStateSourceError, c as rejectExplicitCfnStackWithMultipleStacks, d as CfnLocalStateProvider, i as createLocalInvokeCommand, l as resolveCfnRegion, n as createLocalRunTaskCommand, o as createLocalStateProvider, r as createLocalStartApiCommand, s as isCfnFlagPresent, t as createLocalStartServiceCommand, u as resolveCfnStackName } from "./local-start-service-irdy6U57.js";
 
 export { CfnLocalStateProvider, LocalStateSourceError, createLocalInvokeCommand, createLocalRunTaskCommand, createLocalStartApiCommand, createLocalStartServiceCommand, createLocalStateProvider, isCfnFlagPresent, rejectExplicitCfnStackWithMultipleStacks, resolveCfnRegion, resolveCfnStackName };

package/dist/{local-start-service-gYRarUgM.js → local-start-service-irdy6U57.js}

@@ -3802,7 +3802,7 @@ async function runDetached(opts) {
 		const ro = mount.readOnly ? ":ro" : "";
 		args.push("-v", `${mount.hostPath}:${mount.containerPath}${ro}`);
 	}
-	for (const [k, v] of Object.entries(opts.env)) args.push("-e", `${k}=${v}`);
+	const passthroughEnv = appendEnvFlags(args, opts.env, SENSITIVE_ENV_KEYS);
 	if (opts.tmpfs) args.push("--tmpfs", `${opts.tmpfs.target}:rw,size=${opts.tmpfs.sizeMb}m`);
 	if (opts.workingDir) args.push("--workdir", opts.workingDir);
 	let entryPointTail = [];
@@ -3813,7 +3813,10 @@ async function runDetached(opts) {
 	args.push(opts.image, ...entryPointTail, ...opts.cmd);
 	getLogger().child("docker").debug(`${getDockerCmd()} ${redactAwsCredentialsInArgs(args).join(" ")}`);
 	try {
-		const { stdout } = await execFileAsync$3(getDockerCmd(), args, { maxBuffer: 10 * 1024 * 1024 });
+		const { stdout } = await execFileAsync$3(getDockerCmd(), args, {
+			maxBuffer: 10 * 1024 * 1024,
+			...execEnvForSecrets(passthroughEnv)
+		});
 		return stdout.trim();
 	} catch (error) {
 		const err = error;
@@ -3908,23 +3911,66 @@ function pickFreePort() {
 	});
 }
 /**
-* AWS credential keys whose values must NOT be written to the debug log.
-* `forwardAwsEnv` / `assumeLambdaExecutionRole` (in `local-invoke.ts`)
-* push these via `-e <KEY>=<value>` flags into `runDetached`'s args
-* array, and `cdkl invoke --verbose` would otherwise leak them
-* into stdout / log files. Only the matching `-e <KEY>=<value>` pair is
-* redacted; non-credential `-e KEY=val` entries pass through unchanged.
+* Env keys whose VALUES are sensitive (AWS credentials). These are
+* routed through docker's value-from-process-env form by
+* {@link appendEnvFlags} so the value never appears in `docker run`'s
+* argv (`ps` / `/proc/<pid>/cmdline`), and they are also redacted by
+* {@link redactAwsCredentialsInArgs} as a defense for any path that
+* still emits the inline `-e <KEY>=<value>` form into the debug log.
 */
-const REDACTED_ENV_KEYS = new Set([
+const SENSITIVE_ENV_KEYS = new Set([
 	"AWS_ACCESS_KEY_ID",
 	"AWS_SECRET_ACCESS_KEY",
 	"AWS_SESSION_TOKEN"
 ]);
 /**
+* Append `-e` flags for `env` to `args`, routing keys in `sensitiveKeys`
+* through docker's value-from-process-env form (`-e KEY`, with NO
+* `=value`). Docker reads the value from its OWN environment at run time,
+* so the secret never lands in `docker run`'s argv — invisible to
+* `ps aux` / `/proc/<pid>/cmdline` (other users on a shared host) and to
+* shell history. Non-sensitive keys keep the inline `-e KEY=VALUE` form
+* (fine for non-secret config, and keeps `--debug` output readable).
+*
+* Returns the `{ KEY: value }` map of routed-through keys; the caller MUST
+* merge it into the spawned docker process's `env` (see
+* {@link execEnvForSecrets}) so docker can resolve each passed-through
+* key. Values still appear in `docker inspect` Config.Env — that is
+* inherent to container env and matches production behavior.
+*
+* Unlike `--env-file`, this handles multi-line values (e.g. PEM secrets)
+* and needs no temp file on disk.
+*/
+function appendEnvFlags(args, env, sensitiveKeys) {
+	const passthrough = {};
+	for (const [k, v] of Object.entries(env)) if (sensitiveKeys.has(k)) {
+		args.push("-e", k);
+		passthrough[k] = v;
+	} else args.push("-e", `${k}=${v}`);
+	return passthrough;
+}
+/**
+* Build the `env` option for an `execFile` / `spawn` call that runs a
+* `docker run` whose args include passed-through sensitive keys (from
+* {@link appendEnvFlags}). Returns `{ env: {...process.env, ...passthrough} }`
+* so docker inherits the normal environment PLUS the sensitive values it
+* must resolve, or `{}` when there is nothing to pass through (preserving
+* the default inherited-environment behavior).
+*/
+function execEnvForSecrets(passthrough) {
+	if (Object.keys(passthrough).length === 0) return {};
+	return { env: {
+		...process.env,
+		...passthrough
+	} };
+}
+/**
 * Returns a copy of `args` with any `-e <KEY>=<value>` pair whose KEY is
-* in {@link REDACTED_ENV_KEYS} replaced with `-e <KEY>=***`. The actual
+* in {@link SENSITIVE_ENV_KEYS} replaced with `-e <KEY>=***`. The actual
 * `args` passed to `spawn` are never mutated — this is for log output
-* only.
+* only. With {@link appendEnvFlags} routing credentials through the
+* value-less `-e KEY` form this rarely fires, but it stays as defense for
+* any inline-form credential that slips into a logged command.
 */
 function redactAwsCredentialsInArgs(args) {
 	const out = [];
@@ -3935,7 +3981,7 @@ function redactAwsCredentialsInArgs(args) {
 			const eqIdx = next.indexOf("=");
 			if (eqIdx > 0) {
 				const key = next.substring(0, eqIdx);
-				if (REDACTED_ENV_KEYS.has(key)) {
+				if (SENSITIVE_ENV_KEYS.has(key)) {
 					out.push("-e", `${key}=***`);
 					i++;
 					continue;
@@ -14155,6 +14201,8 @@ async function localStartApiCommand(target, options, extraStateProviders) {
 		logger.warn(`[deprecated] --api <id> will be removed in a future major release. Use the positional argument instead: '${getEmbedConfig().cliName} start-api <id>'.`);
 		apiFilter = options.api;
 	}
+	const allStacksConflictList = allStacksConflicts(options, target, apiFilter);
+	if (allStacksConflictList.length > 0) throw new Error(`--all-stacks serves every stack's API and cannot be combined with a single-target selector (${allStacksConflictList.join(", ")}). Drop --all-stacks to target one stack, or drop the selector to serve them all. The bare --from-cfn-stack flag (no value) IS compatible with --all-stacks.`);
 	warnIfDeprecatedRegion(options);
 	await applyRoleArnIfSet({
 		roleArn: options.roleArn,
@@ -14201,7 +14249,7 @@ async function localStartApiCommand(target, options, extraStateProviders) {
 		const { stacks } = await synthesizer.synthesize(synthOpts);
 		const cfnStackFallback = typeof options.fromCfnStack === "string" ? options.fromCfnStack : void 0;
 		const targetStackPrefix = target?.includes("/") === true ? target.slice(0, target.indexOf("/")) : void 0;
-		const targetStacks = pickTargetStacks(stacks, options.stack, cfnStackFallback, targetStackPrefix);
+		const targetStacks = pickTargetStacks(stacks, options.stack, cfnStackFallback, targetStackPrefix, options.allStacks);
 		if (targetStacks.length === 0) throw new Error("No stacks matched. Pass --stack <name> (or --from-cfn-stack <name>) or run from a single-stack app.");
 		const routedStackNames = targetStacks.map((s) => s.stackName);
 		tryEmitFromCfnRedundancyTipOnce(options.fromCfnStack, routedStackNames, fromCfnTipEmitted, (routedStackName) => {
@@ -14583,12 +14631,37 @@ async function localStartApiCommand(target, options, extraStateProviders) {
 * routing rules.
 */
 /** @internal exported for unit tests. */
-function pickTargetStacks(stacks, pattern, cfnStackFallback, targetFallback) {
+function pickTargetStacks(stacks, pattern, cfnStackFallback, targetFallback, allStacks) {
+	if (allStacks) return stacks;
 	const effective = pattern ?? cfnStackFallback ?? targetFallback;
 	if (effective) return matchStacks(stacks, [effective]);
 	if (stacks.length === 1) return stacks;
 	if (stacks.length === 0) return [];
-	throw new Error(`Multi-stack app: pass --stack <name>, --from-cfn-stack <name>, or a stack-qualified target like "<StackName>/<construct>" to pick a target. Available stacks: ${stacks.map((s) => s.stackName).join(", ")}.`);
+	throw new Error(`Multi-stack app: pass --stack <name>, --from-cfn-stack <name>, a stack-qualified target like "<StackName>/<construct>", or --all-stacks to serve every stack. Available stacks: ${stacks.map((s) => s.stackName).join(", ")}.`);
+}
+/**
+* Issue #55: `--all-stacks` serves every stack's API as a union, so it
+* cannot be combined with a selector that names exactly ONE target.
+* Returns the human-readable list of conflicting selectors (empty when
+* `--all-stacks` is off or there is no conflict).
+*
+* The bare `--from-cfn-stack` flag (Commander maps it to boolean `true`)
+* is NOT a conflict — it binds each routed stack to its own CFn stack,
+* which is exactly the multi-stack union case. Only an explicit
+* `--from-cfn-stack <name>` (a string) names a single stack and conflicts.
+*
+* Extracted as a pure function so it can be unit-tested without booting
+* the full server.
+*
+* @internal exported for unit tests.
+*/
+function allStacksConflicts(options, target, apiFilter) {
+	if (!options.allStacks) return [];
+	const conflicts = [];
+	if (apiFilter !== void 0) conflicts.push(target !== void 0 ? `target '${target}'` : `--api '${options.api}'`);
+	if (options.stack !== void 0) conflicts.push(`--stack '${options.stack}'`);
+	if (typeof options.fromCfnStack === "string") conflicts.push(`--from-cfn-stack '${options.fromCfnStack}'`);
+	return conflicts;
 }
 /**
 * Decide whether the `--from-cfn-stack <name>` redundancy tip should
@@ -15586,7 +15659,7 @@ function resolveMtlsConfig(options) {
 */
 function createLocalStartApiCommand(opts = {}) {
 	setEmbedConfig(opts.embedConfig);
-	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 AWS_IAM auth (REST v1 `AuthorizationType: AWS_IAM` and Function URL `AuthType: AWS_IAM` — SigV4 signature verification only; IAM policy evaluation is NOT emulated). 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 \`${getEmbedConfig().cliName} invoke\` / \`${getEmbedConfig().cliName} 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-cfn-stack [cfn-stack-name]", "Read a deployed CloudFormation stack via ListStackResources and substitute Ref / Fn::ImportValue in Lambda env vars with the deployed physical IDs / exports. Use for CDK apps deployed via the upstream CDK CLI (`cdk deploy`). Bare form uses the resolved stack name per routed stack; pass an explicit value when a single CFn stack should serve every routed stack. Fn::GetAtt is warn-and-dropped in v1 (CFn ListStackResources does not return per-attribute values).")).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-cfn-stack as the CFn client region.")).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=${getEmbedConfig().resourceNamePrefix}-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(async (target, options) => {
+	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 AWS_IAM auth (REST v1 `AuthorizationType: AWS_IAM` and Function URL `AuthType: AWS_IAM` — SigV4 signature verification only; IAM policy evaluation is NOT emulated). 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 \`${getEmbedConfig().cliName} invoke\` / \`${getEmbedConfig().cliName} 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("--all-stacks", "Serve every stack's API in a multi-stack app (each API on its own port) instead of erroring out. Mutually exclusive with a positional target, --stack, and an explicit --from-cfn-stack <name>; the bare --from-cfn-stack flag stays compatible (binds each routed stack to its own CFn stack).").default(false)).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-cfn-stack [cfn-stack-name]", "Read a deployed CloudFormation stack via ListStackResources and substitute Ref / Fn::ImportValue in Lambda env vars with the deployed physical IDs / exports. Use for CDK apps deployed via the upstream CDK CLI (`cdk deploy`). Bare form uses the resolved stack name per routed stack; pass an explicit value when a single CFn stack should serve every routed stack. Fn::GetAtt is warn-and-dropped in v1 (CFn ListStackResources does not return per-attribute values).")).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-cfn-stack as the CFn client region.")).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=${getEmbedConfig().resourceNamePrefix}-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(async (target, options) => {
 		await localStartApiCommand(target, options, opts.extraStateProviders);
 	}));
 	[
@@ -15731,11 +15804,14 @@ async function createNetworkAndSidecar(args) {
 		if (credentials.sessionToken) sidecarEnv["AWS_SESSION_TOKEN"] = credentials.sessionToken;
 	}
 	if (cluster) sidecarEnv["CLUSTER"] = cluster;
-	for (const [k, v] of Object.entries(sidecarEnv)) sidecarArgs.push("-e", `${k}=${v}`);
+	const sidecarPassthroughEnv = appendEnvFlags(sidecarArgs, sidecarEnv, SENSITIVE_ENV_KEYS);
 	sidecarArgs.push(METADATA_ENDPOINT_IMAGE);
 	logger.info(`Starting ECS local-container-endpoints sidecar at ${sidecarIp}...`);
 	try {
-		const { stdout } = await execFileAsync$2(getDockerCmd(), sidecarArgs, { maxBuffer: 10 * 1024 * 1024 });
+		const { stdout } = await execFileAsync$2(getDockerCmd(), sidecarArgs, {
+			maxBuffer: 10 * 1024 * 1024,
+			...execEnvForSecrets(sidecarPassthroughEnv)
+		});
 		return stdout.trim();
 	} catch (err) {
 		await destroyNetworkOnly(networkName);
@@ -16068,11 +16144,14 @@ async function runEcsTask(task, options, state) {
 	for (const containerName of startOrder) {
 		const container = task.containers.find((c) => c.name === containerName);
 		await awaitDependencies(container, startedByName);
-		const args = dockerCmds.get(container.name);
+		const { args, sensitiveEnv } = dockerCmds.get(container.name);
 		logger.info(`Starting container '${container.name}' (image=${imagePlan.get(container.name)})`);
 		let id;
 		try {
-			const { stdout } = await execFileAsync$1(getDockerCmd(), args, { maxBuffer: 10 * 1024 * 1024 });
+			const { stdout } = await execFileAsync$1(getDockerCmd(), args, {
+				maxBuffer: 10 * 1024 * 1024,
+				...execEnvForSecrets(sensitiveEnv)
+			});
 			id = stdout.trim();
 		} catch (err) {
 			const e = err;
@@ -16426,7 +16505,9 @@ function buildDockerRunArgs(opts) {
 		applyOverrideMap(finalEnv, overrides["Parameters"]);
 		applyOverrideMap(finalEnv, overrides[container.name]);
 	}
-	for (const [k, v] of Object.entries(finalEnv)) args.push("-e", `${k}=${v}`);
+	const sensitiveEnvKeys = new Set(SENSITIVE_ENV_KEYS);
+	for (const s of secrets) sensitiveEnvKeys.add(s.name);
+	const sensitiveEnv = appendEnvFlags(args, finalEnv, sensitiveEnvKeys);
 	if (container.user) args.push("--user", container.user);
 	if (container.privileged) args.push("--privileged");
 	if (container.readonlyRootFilesystem) args.push("--read-only");
@@ -16446,7 +16527,10 @@ function buildDockerRunArgs(opts) {
 		entryPointTail = container.entryPoint.slice(1);
 	}
 	args.push(image, ...entryPointTail, ...container.command ?? []);
-	return args;
+	return {
+		args,
+		sensitiveEnv
+	};
 }
 function applyOverrideMap(acc, map) {
 	if (!map) return;
@@ -18142,4 +18226,4 @@ function createLocalStartServiceCommand(opts = {}) {
 
 //#endregion
 export { LocalStateSourceError as a, rejectExplicitCfnStackWithMultipleStacks as c, CfnLocalStateProvider as d, createLocalInvokeCommand as i, resolveCfnRegion as l, createLocalRunTaskCommand as n, createLocalStateProvider as o, createLocalStartApiCommand as r, isCfnFlagPresent as s, createLocalStartServiceCommand as t, resolveCfnStackName as u };
-//# sourceMappingURL=local-start-service-gYRarUgM.js.map
+//# sourceMappingURL=local-start-service-irdy6U57.js.map