cdk-local 0.5.1 → 0.5.2

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,26 @@ 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). Pick the synth stack with the first of these you supply:
+
+- `--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.
+
+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 +103,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-2tcrICJq.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.5.2");
 program.addCommand(createLocalInvokeCommand());
 program.addCommand(createLocalStartApiCommand());
 program.addCommand(createLocalRunTaskCommand());

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-2tcrICJq.js";
 
 export { CfnLocalStateProvider, LocalStateSourceError, createLocalInvokeCommand, createLocalRunTaskCommand, createLocalStartApiCommand, createLocalStartServiceCommand, createLocalStateProvider, isCfnFlagPresent, rejectExplicitCfnStackWithMultipleStacks, resolveCfnRegion, resolveCfnStackName };

package/dist/{local-start-service-gYRarUgM.js → local-start-service-2tcrICJq.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;
@@ -15731,11 +15777,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 +16117,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 +16478,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 +16500,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 +18199,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-2tcrICJq.js.map