cdk-local 0.3.0 → 0.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 Local runner for your CDK app's Lambda functions, API Gateway, and ECS tasks/services. Run it with no AWS account, or bind it to your deployed stack to hit real AWS resources and data. A native, CDK-first alternative to `sam local`.
 
-![cdkl invoke against a local sample CDK app — no AWS account, no deploy](assets/cdkl-invoke.gif)
+![cdkl start-api serving a local CDK app's HTTP API; curl in the right pane reaches the local Lambda](assets/cdkl-start-api.gif)
 
 ## Why cdk-local
 
@@ -64,6 +64,8 @@ Invoke a single Lambda function with an event payload.
 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`
 
 Serve your API Gateway routes (REST v1 / HTTP v2 / Function URL / WebSocket) on a local HTTP server.
@@ -81,6 +83,8 @@ cdkl run-task MyStack/MyTask
 cdkl start-service MyStack/MyService
 ```
 
+There is no cluster command — locally, Docker is the placement target a cluster abstracts away, so there is nothing to run. Both commands accept an optional `--cluster <name>` to set the cluster name surfaced to `ECS_CONTAINER_METADATA_URI_V4` (also used as the local Docker network prefix). See [docs/cli-reference.md](docs/cli-reference.md) for the full ECS option list.
+
 Use this for fast iteration on Lambda code, API routing checks, and container task smoke tests.
 
 ### 2. Bound to a deployed stack
@@ -119,6 +123,21 @@ cdkl start-service MyStack/MyService --from-cfn-stack MyStack
 
 Use this for production debugging, integration verification with real AWS resources, and validating real IAM permissions before deploy.
 
+## `--watch` (hot reload)
+
+Pass `--watch` to `cdkl start-api` and the server hot-reloads when your CDK app's synth output (or any routed Lambda's asset directory) changes:
+
+```bash
+cdkl start-api MyStack/MyApi --watch
+```
+
+- 500 ms debounced [chokidar](https://github.com/paulmillr/chokidar) file watcher on `cdk.out/` + every routed Lambda's asset dir.
+- Re-synths and re-discovers routes on each firing — adding a new route to your CDK app shows up locally on save.
+- Synth failures keep the previous version serving (warn-and-continue, never crashes the server).
+- Compatible with `--from-cfn-stack`: each reload re-reads the deployed CloudFormation stack so a deploy event picks up new ARNs without restarting the server.
+
+See [docs/local-emulation.md](docs/local-emulation.md#hot-reload---watch) for the full lifecycle, file-list update semantics, and known limitations.
+
 ## Override env vars without a state source
 
 When env-var values in your CDK template are CloudFormation intrinsics (`Ref`, `Fn::GetAtt`, `Fn::ImportValue`), cdk-local cannot resolve them without a state source — it drops them with a warning that names the affected key. To inject literal values instead, use `--env-vars <file>` (SAM-compatible JSON shape):

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-C3Y-nNM3.js";
+import { i as createLocalInvokeCommand, n as createLocalRunTaskCommand, r as createLocalStartApiCommand, t as createLocalStartServiceCommand } from "./local-start-service-zoDos4zT.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.3.0");
+program.name("cdkl").description("Run AWS CDK stacks locally with Docker.").version("0.4.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/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":";;;;UAuLiB,aAAA;EAEf,UAAA;EAGA,YAAA;EAGA,UAAA,EAAY,MAAA;EAcZ,kBAAA,GAAqB,MAAA;EAGrB,UAAA,GAAa,MAAA;EAGb,YAAA;EAGA,QAAA,GAAW,MAAA;EAmBX,cAAA;EAMA,mBAAA;EAyBA,aAAA;AAAA;;;UCxIe,gBAAA;EACf,SAAA;EACA,MAAA;EACA,SAAA;EACA,SAAA;AAAA;AAAA,UAqBe,kBAAA;EAOf,aAAA,CAAc,UAAA,WAAqB,OAAA;EAQnC,qBAAA,CACE,aAAA,UACA,cAAA,UACA,UAAA,WACC,OAAA;AAAA;AAAA,UAGY,mBAAA;EAEf,SAAA,EAAW,MAAA,SAAe,aAAA;EAE1B,gBAAA,GAAmB,gBAAA;EAOnB,kBAAA,GAAqB,kBAAA;EAOrB,cAAA;AAAA;;;UCrJe,gBAAA;EAQf,SAAA,EAAW,MAAA,SAAe,aAAA;EAO1B,OAAA,EAAS,MAAA;EAOT,MAAA;AAAA;AAAA,UAsBe,kBAAA;EAAA,SAMN,KAAA;EAQT,IAAA,CAAK,SAAA,UAAmB,WAAA,uBAAkC,OAAA,CAAQ,gBAAA;EAalE,uBAAA,CAAwB,cAAA,WAAyB,OAAA,CAAQ,kBAAA;EAKzD,OAAA;AAAA;;;UC/Ee,uBAAA;EAOf,YAAA;EAEA,MAAA;EAEA,OAAA;EAMA,WAAA;EAAA,CAEC,GAAA;AAAA;AAAA,KAQS,yBAAA,IAA6B,OAAA,EAAS,uBAAA,KAA4B,kBAAA;AAAA,KAUlE,mBAAA,GAAsB,MAAA,SAAe,yBAAA;AAAA,iBAUjC,mBAAA,CAAoB,YAAA,oBAAgC,SAAA;AAAA,iBAapD,gBAAA,CAAiB,IAAA,EAAM,IAAA,CAAK,uBAAA;AAAA,iBAgB5B,gBAAA,CACd,OAAA,EAAS,IAAA,CAAK,uBAAA,6BACd,WAAA;AAAA,cAqBW,qBAAA,SAA8B,KAAA;cAC7B,OAAA;AAAA;AAAA,iBAkBE,wCAAA,CACd,OAAA,EAAS,IAAA,CAAK,uBAAA,mBACd,gBAAA;AAAA,iBAiCc,wBAAA,CACd,OAAA,EAAS,uBAAA,EACT,SAAA,UACA,WAAA,sBACA,mBAAA,GAAsB,mBAAA,GACrB,kBAAA;;;UCtEc,+BAAA;EACf,mBAAA,GAAsB,mBAAA;AAAA;AAAA,iBAu2BR,wBAAA,CAAyB,IAAA,GAAM,+BAAA,GAAuC,OAAA;;;UC5vBrE,iCAAA;EACf,mBAAA,GAAsB,mBAAA;AAAA;AAAA,iBA2tFR,0BAAA,CAA2B,IAAA,GAAM,iCAAA,GAAyC,OAAA;;;UC52FzE,gCAAA;EACf,mBAAA,GAAsB,mBAAA;AAAA;AAAA,iBAkeR,yBAAA,CAA0B,IAAA,GAAM,gCAAA,GAAwC,OAAA;;;UCtevE,qCAAA;EACf,mBAAA,GAAsB,mBAAA;AAAA;AAAA,iBA+oBR,8BAAA,CACd,IAAA,GAAM,qCAAA,GACL,OAAA;;;UC5qBc,4BAAA;EAOf,YAAA;EAKA,MAAA;EAiBA,OAAA;AAAA;AAAA,cAGW,qBAAA,YAAiC,kBAAA;EAAA,SAG5B,KAAA;EAAA,iBACC,YAAA;EAAA,iBACA,MAAA;EAAA,QAKT,MAAA;EAAA,iBACS,aAAA;EAAA,QAQT,QAAA;cAEI,IAAA,EAAM,4BAAA;EAAA,QAOV,SAAA;EA+BK,IAAA,CACX,UAAA,UACA,YAAA,uBACC,OAAA,CAAQ,gBAAA;EA8DE,uBAAA,CACX,eAAA,WACC,OAAA,CAAQ,kBAAA;EAiEJ,OAAA,CAAA;AAAA"}
+{"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/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":";;;;UAuLiB,aAAA;EAEf,UAAA;EAGA,YAAA;EAGA,UAAA,EAAY,MAAA;EAcZ,kBAAA,GAAqB,MAAA;EAGrB,UAAA,GAAa,MAAA;EAGb,YAAA;EAGA,QAAA,GAAW,MAAA;EAmBX,cAAA;EAMA,mBAAA;EAyBA,aAAA;AAAA;;;UCxIe,gBAAA;EACf,SAAA;EACA,MAAA;EACA,SAAA;EACA,SAAA;AAAA;AAAA,UAqBe,kBAAA;EAOf,aAAA,CAAc,UAAA,WAAqB,OAAA;EAQnC,qBAAA,CACE,aAAA,UACA,cAAA,UACA,UAAA,WACC,OAAA;AAAA;AAAA,UAGY,mBAAA;EAEf,SAAA,EAAW,MAAA,SAAe,aAAA;EAE1B,gBAAA,GAAmB,gBAAA;EAOnB,kBAAA,GAAqB,kBAAA;EAOrB,cAAA;AAAA;;;UCrJe,gBAAA;EAQf,SAAA,EAAW,MAAA,SAAe,aAAA;EAO1B,OAAA,EAAS,MAAA;EAOT,MAAA;AAAA;AAAA,UAsBe,kBAAA;EAAA,SAMN,KAAA;EAQT,IAAA,CAAK,SAAA,UAAmB,WAAA,uBAAkC,OAAA,CAAQ,gBAAA;EAalE,uBAAA,CAAwB,cAAA,WAAyB,OAAA,CAAQ,kBAAA;EAKzD,OAAA;AAAA;;;UC/Ee,uBAAA;EAOf,YAAA;EAEA,MAAA;EAEA,OAAA;EAMA,WAAA;EAAA,CAEC,GAAA;AAAA;AAAA,KAQS,yBAAA,IAA6B,OAAA,EAAS,uBAAA,KAA4B,kBAAA;AAAA,KAUlE,mBAAA,GAAsB,MAAA,SAAe,yBAAA;AAAA,iBAUjC,mBAAA,CAAoB,YAAA,oBAAgC,SAAA;AAAA,iBAapD,gBAAA,CAAiB,IAAA,EAAM,IAAA,CAAK,uBAAA;AAAA,iBAgB5B,gBAAA,CACd,OAAA,EAAS,IAAA,CAAK,uBAAA,6BACd,WAAA;AAAA,cAqBW,qBAAA,SAA8B,KAAA;cAC7B,OAAA;AAAA;AAAA,iBAkBE,wCAAA,CACd,OAAA,EAAS,IAAA,CAAK,uBAAA,mBACd,gBAAA;AAAA,iBAiCc,wBAAA,CACd,OAAA,EAAS,uBAAA,EACT,SAAA,UACA,WAAA,sBACA,mBAAA,GAAsB,mBAAA,GACrB,kBAAA;;;UCtEc,+BAAA;EACf,mBAAA,GAAsB,mBAAA;AAAA;AAAA,iBAu2BR,wBAAA,CAAyB,IAAA,GAAM,+BAAA,GAAuC,OAAA;;;UC5vBrE,iCAAA;EACf,mBAAA,GAAsB,mBAAA;AAAA;AAAA,iBA+xFR,0BAAA,CAA2B,IAAA,GAAM,iCAAA,GAAyC,OAAA;;;UCh7FzE,gCAAA;EACf,mBAAA,GAAsB,mBAAA;AAAA;AAAA,iBAkeR,yBAAA,CAA0B,IAAA,GAAM,gCAAA,GAAwC,OAAA;;;UCtevE,qCAAA;EACf,mBAAA,GAAsB,mBAAA;AAAA;AAAA,iBA+oBR,8BAAA,CACd,IAAA,GAAM,qCAAA,GACL,OAAA;;;UC5qBc,4BAAA;EAOf,YAAA;EAKA,MAAA;EAiBA,OAAA;AAAA;AAAA,cAGW,qBAAA,YAAiC,kBAAA;EAAA,SAG5B,KAAA;EAAA,iBACC,YAAA;EAAA,iBACA,MAAA;EAAA,QAKT,MAAA;EAAA,iBACS,aAAA;EAAA,QAQT,QAAA;cAEI,IAAA,EAAM,4BAAA;EAAA,QAOV,SAAA;EA+BK,IAAA,CACX,UAAA,UACA,YAAA,uBACC,OAAA,CAAQ,gBAAA;EA8DE,uBAAA,CACX,eAAA,WACC,OAAA,CAAQ,kBAAA;EAiEJ,OAAA,CAAA;AAAA"}

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

package/dist/{local-start-service-C3Y-nNM3.js → local-start-service-zoDos4zT.js}

@@ -10515,6 +10515,72 @@ function buildCorsConfigFromCloudFrontChain(template) {
 	return out;
 }
 /**
+* Determine whether a Function URL (`AWS::Lambda::Url`, identified by its
+* logical id) is fronted by a CloudFront Distribution origin that uses
+* Origin Access Control (OAC) to SIGN origin requests.
+*
+* Production-correct CDK pattern (`FunctionUrlOrigin.withOriginAccessControl`):
+* the Function URL declares `AuthType: AWS_IAM`, but the END client never
+* signs as the IAM principal — CloudFront re-signs the origin request with
+* its own SigV4 credentials (service `lambda`) via the OAC, and the Function
+* URL's auto-generated resource policy trusts `cloudfront.amazonaws.com`.
+* Locally there is no CloudFront in the path, so no client signature can
+* reproduce CloudFront's. Callers use this to relax SigV4 verification
+* (warn-and-pass) for these Function URLs without forcing
+* `--allow-unverified-sigv4`.
+*
+* Detection: a CloudFront origin whose `DomainName` matches the canonical
+* `Fn::GetAtt[<fnUrlLogicalId>, 'FunctionUrl']` chain (see
+* {@link pickFnUrlLogicalIdFromOriginDomainName}) AND carries an
+* `OriginAccessControlId`. When that id resolves to an
+* `AWS::CloudFront::OriginAccessControl` whose `SigningBehavior` is
+* explicitly `never`, CloudFront does NOT sign — so we do NOT relax (the
+* AWS_IAM + never-sign combination is non-functional in production too).
+* Any other signing behavior (`always` — the CDK default — or `no-override`)
+* counts as OAC-fronted. An `OriginAccessControlId` that can't be resolved
+* to a local resource (imported literal id) also counts — its presence on a
+* Function URL origin is the signal.
+*/
+function isFunctionUrlOacFronted(template, fnUrlLogicalId) {
+	const resources = template.Resources ?? {};
+	for (const [, resource] of Object.entries(resources)) {
+		if (resource.Type !== "AWS::CloudFront::Distribution") continue;
+		const distConfig = (resource.Properties ?? {})["DistributionConfig"];
+		if (!distConfig || typeof distConfig !== "object") continue;
+		const origins = Array.isArray(distConfig["Origins"]) ? distConfig["Origins"] : [];
+		for (const origin of origins) {
+			if (!origin || typeof origin !== "object") continue;
+			const o = origin;
+			if (pickFnUrlLogicalIdFromOriginDomainName(o["DomainName"]) !== fnUrlLogicalId) continue;
+			const oacRef = o["OriginAccessControlId"];
+			if (oacRef === void 0 || oacRef === "") continue;
+			const oacLogicalId = pickOacRefLogicalId(oacRef);
+			if (!oacLogicalId) return true;
+			const oac = resources[oacLogicalId];
+			if (!oac || oac.Type !== "AWS::CloudFront::OriginAccessControl") return true;
+			const oacConfig = (oac.Properties ?? {})["OriginAccessControlConfig"];
+			if ((oacConfig && typeof oacConfig === "object" ? oacConfig["SigningBehavior"] : void 0) === "never") continue;
+			return true;
+		}
+	}
+	return false;
+}
+/**
+* Unwrap an origin's `OriginAccessControlId` to the referenced
+* `AWS::CloudFront::OriginAccessControl` logical id. CDK synthesizes this
+* as `{ "Fn::GetAtt": [<id>, "Id"] }`; `{ Ref: <id> }` is also accepted.
+* Returns undefined for a literal id string (imported OAC) or any other
+* shape.
+*/
+function pickOacRefLogicalId(value) {
+	if (!value || typeof value !== "object") return void 0;
+	const obj = value;
+	const ref = obj["Ref"];
+	if (typeof ref === "string" && ref.length > 0) return ref;
+	const getAtt = obj["Fn::GetAtt"];
+	if (Array.isArray(getAtt) && getAtt.length === 2 && typeof getAtt[0] === "string") return getAtt[0];
+}
+/**
 * Detect the canonical CDK 2.x `DomainName` shape that points a
 * CloudFront Origin at a Function URL:
 *   {Fn::Select: [2, {Fn::Split: ['/', {Fn::GetAtt: [<id>, 'FunctionUrl']}]}]}
@@ -11151,7 +11217,8 @@ function detectFunctionUrlAuthorizer(urlResource, urlLogicalId, stack) {
 	return {
 		kind: "iam",
 		logicalId: "AWS_IAM",
-		declaredAt: `${stack.stackName}/${urlLogicalId}`
+		declaredAt: `${stack.stackName}/${urlLogicalId}`,
+		...isFunctionUrlOacFronted(stack.template, urlLogicalId) && { oacFronted: true }
 	};
 }
 function detectRestV1Authorizer(methodResource, methodLogicalId, stack) {
@@ -11919,11 +11986,16 @@ function defaultCredentialsLoader() {
 *   - **Signature mismatch** under the dev's own credentials → `{allow: false}`.
 *     The http-server maps this to 403 (REST v1 `policy-deny`).
 *   - **Different `Credential` access-key-id than the dev has** →
-*     `{allow: true}` plus a one-line warn (warn-and-pass; we can't
-*     reproduce a signing key we don't have).
+*     `{allow: false}` by default (we can't reproduce a signing key we
+*     don't have). With `allowUnverified` (the `--allow-unverified-sigv4`
+*     flag, or `oacFronted` routes) → `{allow: true}` plus a one-line warn
+*     (warn-and-pass).
 *   - **Valid signature with the dev's credentials** → `{allow: true}`.
 *     The principal id surfaced to the handler is the parsed
 *     `Credential` access-key-id.
+*   - **`oacFronted` route** → the caller forces `allowUnverified` on, so
+*     foreign / no-creds requests pass through (CloudFront re-signs origin
+*     requests in production) and the warn lines reference CloudFront OAC.
 */
 async function verifySigV4(req, loadCredentials, opts = {}) {
 	const logger = getLogger();
@@ -11990,7 +12062,7 @@ async function verifySigV4(req, loadCredentials, opts = {}) {
 				identityHash: void 0
 			};
 		}
-		logger.warn(`AWS_IAM authorizer: failed to resolve local AWS credentials (${reason}). --allow-unverified-sigv4 is set; passing through with unverified principalId 'unverified-no-creds'. Do NOT trust event.requestContext.identity.accessKey in handler code.`);
+		logger.warn(opts.oacFronted ? `AWS_IAM authorizer: Function URL is fronted by CloudFront OAC (CloudFront re-signs origin requests in production), and local AWS credentials could not be resolved (${reason}). Passing through with unverified principalId 'unverified-no-creds'. Do NOT trust event.requestContext.identity.accessKey in handler code.` : `AWS_IAM authorizer: failed to resolve local AWS credentials (${reason}). --allow-unverified-sigv4 is set; passing through with unverified principalId 'unverified-no-creds'. Do NOT trust event.requestContext.identity.accessKey in handler code.`);
 		return {
 			allow: true,
 			principalId: "unverified-no-creds",
@@ -12011,7 +12083,7 @@ async function verifySigV4(req, loadCredentials, opts = {}) {
 			};
 		}
 		if (!warned || !warned.has(dedupKey)) {
-			logger.warn(`AWS_IAM authorizer: request signed with foreign access-key-id '${parsed.credentialAccessKeyId}'. --allow-unverified-sigv4 is set; passing through with unverified principalId 'unverified-foreign-identity'. Do NOT trust event.requestContext.authorizer.principalId in handler code.`);
+			logger.warn(opts.oacFronted ? `AWS_IAM authorizer: Function URL is fronted by CloudFront OAC — in production CloudFront re-signs the origin request, so the local client's signature (access-key-id '${parsed.credentialAccessKeyId}') cannot be verified. Passing through with unverified principalId 'unverified-foreign-identity'. Do NOT trust event.requestContext.authorizer.principalId in handler code.` : `AWS_IAM authorizer: request signed with foreign access-key-id '${parsed.credentialAccessKeyId}'. --allow-unverified-sigv4 is set; passing through with unverified principalId 'unverified-foreign-identity'. Do NOT trust event.requestContext.authorizer.principalId in handler code.`);
 			warned?.add(dedupKey);
 		}
 		return {
@@ -12974,6 +13046,7 @@ async function runAuthorizerPass(authorizer, snapshot, matchCtx, state, opts, re
 				denyKind: "policy-deny"
 			};
 		}
+		const oacFronted = authorizer.oacFronted === true;
 		const sigResult = await verifySigV4({
 			method: snapshot.method,
 			rawUrl: snapshot.rawUrl,
@@ -12981,7 +13054,8 @@ async function runAuthorizerPass(authorizer, snapshot, matchCtx, state, opts, re
 			body: snapshot.body
 		}, opts.sigV4CredentialsLoader, {
 			...opts.sigV4WarnedForeignIds && { warnedForeignIds: opts.sigV4WarnedForeignIds },
-			...opts.sigV4AllowUnverified !== void 0 && { allowUnverified: opts.sigV4AllowUnverified }
+			allowUnverified: oacFronted || opts.sigV4AllowUnverified === true,
+			...oacFronted && { oacFronted: true }
 		});
 		if (!sigResult.allow) return {
 			result: { allow: false },
@@ -13936,6 +14010,7 @@ async function localStartApiCommand(target, options, extraStateProviders) {
 	const jwksWarnedUrls = /* @__PURE__ */ new Set();
 	let sigV4CredentialsLoader;
 	const sigV4WarnedForeignIds = /* @__PURE__ */ new Set();
+	const fromCfnTipEmitted = { value: false };
 	/**
 	* One synth + discover + build pass. Returns the next-state
 	* material. Reused on initial boot AND every hot-reload firing.
@@ -13964,7 +14039,9 @@ async function localStartApiCommand(target, options, extraStateProviders) {
 		const targetStacks = pickTargetStacks(stacks, options.stack, cfnStackFallback, targetStackPrefix);
 		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);
-		if (shouldEmitFromCfnRedundancyTip(options.fromCfnStack, routedStackNames) && routedStackNames[0] !== void 0) logger.info(`tip: --from-cfn-stack value matches the routed stack name (${routedStackNames[0]}); you can omit the value: \`cdkl start-api ... --from-cfn-stack\` (bare flag) resolves to the same value.`);
+		tryEmitFromCfnRedundancyTipOnce(options.fromCfnStack, routedStackNames, fromCfnTipEmitted, (routedStackName) => {
+			logger.info(`tip: --from-cfn-stack value matches the routed stack name (${routedStackName}); you can omit the value: \`cdkl start-api ... --from-cfn-stack\` (bare flag) resolves to the same value.`);
+		});
 		const routes = discoverRoutes(targetStacks);
 		const wsDiscovery = discoverWebSocketApis(targetStacks);
 		if (wsDiscovery.errors.length > 0) for (const e of wsDiscovery.errors) logger.warn(`WebSocket discovery: ${e}`);
@@ -14367,6 +14444,33 @@ function shouldEmitFromCfnRedundancyTip(fromCfnStack, routedStackNames) {
 	return fromCfnStack === routedStackNames[0];
 }
 /**
+* One-shot wrapper around `shouldEmitFromCfnRedundancyTip` for the
+* `--watch` hot-reload path. `synthesizeAndBuild` re-runs on every
+* reload firing, so without a gate the tip would re-emit on every
+* reload — noisy. This helper consults the caller-supplied ref:
+*  - If the predicate fires AND the ref is still `false`, calls `emit`
+*    and flips the ref to `true`.
+*  - On subsequent invocations the ref is `true` and the helper is a
+*    no-op for the rest of the ref's lifetime.
+*  - When the predicate does NOT fire (no `--from-cfn-stack` value /
+*    intentionally-different value / multi-stack run), the ref stays
+*    `false` so a future reload whose synthesized stacks change in a
+*    way that DOES make the value redundant still emits the tip once.
+*
+* The ref is owned by `localStartApiCommand` (one per server boot), so
+* independent server invocations get independent flags.
+*
+* @internal exported for unit tests.
+*/
+function tryEmitFromCfnRedundancyTipOnce(fromCfnStack, routedStackNames, emittedRef, emit) {
+	if (emittedRef.value) return;
+	if (!shouldEmitFromCfnRedundancyTip(fromCfnStack, routedStackNames)) return;
+	const routedStackName = routedStackNames[0];
+	if (routedStackName === void 0) return;
+	emit(routedStackName);
+	emittedRef.value = true;
+}
+/**
 * Distinct, stable list of Lambda logical IDs reachable through any
 * discovered route OR referenced by a Lambda authorizer attached to one
 * of those routes. Stable order = first-occurrence order in the routes
@@ -14467,10 +14571,21 @@ function warnVpcConfigLambdas(routesWithAuth, stacks) {
 function warnIamRoutes(routesWithAuth) {
 	const logger = getLogger();
 	const iamRoutes = [];
-	for (const entry of routesWithAuth) if (entry.authorizer?.kind === "iam") iamRoutes.push(entry.route.declaredAt);
-	if (iamRoutes.length === 0) return false;
-	logger.warn(`${iamRoutes.length} route(s) declare AuthorizationType: AWS_IAM — cdkl start-api verifies SigV4 signatures against your local AWS credentials, but does NOT emulate IAM policy evaluation (resource / action / condition rules). Signature-verified callers reach the handler under their own identity; downstream authorization is the dev's responsibility.`);
-	for (const declaredAt of iamRoutes) logger.warn(`  - ${declaredAt}`);
+	const oacRoutes = [];
+	for (const entry of routesWithAuth) {
+		if (entry.authorizer?.kind !== "iam") continue;
+		if (entry.authorizer.oacFronted === true) oacRoutes.push(entry.route.declaredAt);
+		else iamRoutes.push(entry.route.declaredAt);
+	}
+	if (iamRoutes.length === 0 && oacRoutes.length === 0) return false;
+	if (iamRoutes.length > 0) {
+		logger.warn(`${iamRoutes.length} route(s) declare AuthorizationType: AWS_IAM — cdkl start-api verifies SigV4 signatures against your local AWS credentials, but does NOT emulate IAM policy evaluation (resource / action / condition rules). Signature-verified callers reach the handler under their own identity; downstream authorization is the dev's responsibility.`);
+		for (const declaredAt of iamRoutes) logger.warn(`  - ${declaredAt}`);
+	}
+	if (oacRoutes.length > 0) {
+		logger.warn(`${oacRoutes.length} Function URL route(s) with AuthType: AWS_IAM are fronted by a CloudFront Origin Access Control. In production CloudFront re-signs the origin request, so no local client signature can be verified — cdkl start-api passes these through (warn-and-pass) WITHOUT requiring --allow-unverified-sigv4. Do NOT trust the request identity in handler code.`);
+		for (const declaredAt of oacRoutes) logger.warn(`  - ${declaredAt}`);
+	}
 	return true;
 }
 /**
@@ -17858,4 +17973,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-C3Y-nNM3.js.map
+//# sourceMappingURL=local-start-service-zoDos4zT.js.map