cdk-local 0.147.19 → 0.147.21

package/dist/{local-studio-DOdzcjkE.js → local-studio-J8BtocsI.js}

@@ -42,124 +42,6 @@ import { CloudFrontClient, paginateListKeyValueStores } from "@aws-sdk/client-cl
 import { CloudFrontKeyValueStoreClient, GetKeyCommand, ResourceNotFoundException } from "@aws-sdk/client-cloudfront-keyvaluestore";
 import { EventEmitter } from "node:events";
 
-//#region src/cli/options.ts
-/**
-* Parse context key=value pairs from CLI arguments into a Record.
-*/
-function parseContextOptions(contextArgs) {
-	const context = {};
-	if (contextArgs) for (const arg of contextArgs) {
-		const eqIndex = arg.indexOf("=");
-		if (eqIndex > 0) context[arg.substring(0, eqIndex)] = arg.substring(eqIndex + 1);
-	}
-	return context;
-}
-/**
-* Options shared across every cdk-local command. Built per-call (not a
-* module-level const) so the `--role-arn` env-var hint reflects the active
-* embed config, which the command factory installs before calling this.
-*
-* `--region` is intentionally NOT in `commonOptions` — it is registered
-* separately via {@link regionOption} so a host CLI (cdkd) can swap the
-* shared option block once without losing the `--region` flag.
-*/
-function commonOptions() {
-	const { envPrefix } = getEmbedConfig();
-	return [
-		new Option("--verbose", "Enable verbose logging").default(false),
-		new Option("--profile <profile>", "AWS profile"),
-		new Option("--role-arn <arn>", `IAM role ARN to assume for AWS API calls (env: ${envPrefix}_ROLE_ARN)`),
-		new Option("-y, --yes", "Automatically answer interactive prompts with the recommended response").default(false)
-	];
-}
-/**
-* `--region` option attached to every command. The value drives both
-* host-side AWS SDK calls (STS `GetCallerIdentity` for
-* `${AWS::AccountId}` resolution, `AssumeRole` for `--assume-role`, etc.)
-* and the container's `AWS_REGION` env var. When omitted, region
-* precedence falls back to `AWS_REGION` / `AWS_DEFAULT_REGION` env,
-* then the synthesized stack region, then the `--profile`'s configured
-* region — same shape as the AWS CLI's `--region` flag (issue #245).
-*
-* Kept as a standalone export rather than baked into `commonOptions`
-* so a host CLI (cdkd) can swap the shared option block once without
-* losing this flag.
-*/
-const regionOption = new Option("--region <region>", "AWS region for SDK calls; defaults to AWS_REGION env, the synthesized stack region, or the resolved profile region");
-/**
-* App options. Built per-call (not a module-level const) so the `--app`
-* env-var hint reflects the active embed config.
-*
-* `--app` is optional: falls back to `${envPrefix}_APP` env var, then
-* `cdk.json` `app` field. Accepts either a shell command (e.g.
-* `"node app.ts"`) or a path to a pre-synthesized cloud assembly directory
-* (e.g. `"cdk.out"`).
-*/
-function appOptions() {
-	const { envPrefix } = getEmbedConfig();
-	return [new Option("-a, --app <command>", `CDK app command (e.g., "node app.ts") or path to a pre-synthesized cloud assembly directory. Falls back to cdk.json or ${envPrefix}_APP env`), new Option("--output <path>", "Output directory for synthesis").default("cdk.out")];
-}
-/**
-* Context options.
-*/
-const contextOptions = [new Option("-c, --context <key=value...>", "Set context values (can be specified multiple times)")];
-const IAM_ROLE_ARN_REGEX = /^arn:[^:]+:iam::\d+:role\//;
-function parseAssumeRoleToken(raw, previous) {
-	const acc = previous ?? { perLambda: {} };
-	if (!acc.perLambda) acc.perLambda = {};
-	const eqIndex = raw.indexOf("=");
-	if (eqIndex === -1) {
-		if (!IAM_ROLE_ARN_REGEX.test(raw)) throw new Error(`Invalid --assume-role value "${raw}": expected an IAM role ARN like arn:aws:iam::123456789012:role/MyRole, or LogicalId=<arn>.`);
-		acc.globalArn = raw;
-		return acc;
-	}
-	const logicalId = raw.substring(0, eqIndex).trim();
-	const arn = raw.substring(eqIndex + 1).trim();
-	if (!/^[A-Za-z][A-Za-z0-9]*$/.test(logicalId)) throw new Error(`Invalid --assume-role value "${raw}": left-hand side "${logicalId}" must be a CloudFormation logical ID (alphanumeric, leading letter).`);
-	if (!IAM_ROLE_ARN_REGEX.test(arn)) throw new Error(`Invalid --assume-role value "${raw}": right-hand side "${arn}" must be an IAM role ARN like arn:aws:iam::123456789012:role/MyRole.`);
-	acc.perLambda[logicalId] = arn;
-	return acc;
-}
-/**
-* Compose `--assume-role` (value-form accumulator) and the separate
-* `--assume-role-auto` boolean flag into the in-process
-* representation `localStartApiCommand` consumes downstream.
-*
-*   - both unset -> `undefined` (pass dev creds through)
-*   - only `--assume-role-auto` -> `{ perLambda: {}, bareAutoResolve: true }`
-*     (per-Lambda auto-resolve for every routed Lambda)
-*   - only `--assume-role` -> the value-form accumulator (global ARN
-*     and/or per-Lambda map) as-is
-*   - both -> accumulator with `bareAutoResolve = true` overlaid;
-*     the per-Lambda map still wins for named Lambdas, auto-resolve
-*     fills in for every Lambda the map does NOT name
-*
-* Enforces the mutual-exclusion guard: `--assume-role-auto` and a
-* global ARN (`--assume-role <arn>`) both occupy the "default for
-* every other Lambda" slot, so the combination is ambiguous and
-* rejected at boot with a clear error. The per-Lambda map IS
-* compatible with either side.
-*/
-function normalizeStartApiAssumeRole(raw, autoResolve) {
-	if (raw === void 0) return autoResolve ? {
-		perLambda: {},
-		bareAutoResolve: true
-	} : void 0;
-	if (autoResolve && raw.globalArn) throw new Error(`--assume-role-auto auto-resolves EACH routed Lambda's own execution role, but --assume-role ${raw.globalArn} also names a single global default. These are mutually exclusive on the global slot. Either drop the global ARN to keep --assume-role-auto for every Lambda, or drop --assume-role-auto to keep the global default. Per-Lambda overrides (--assume-role <LogicalId>=<arn>) are compatible with either side.`);
-	if (autoResolve) raw.bareAutoResolve = true;
-	return raw;
-}
-/**
-* Resolve the effective IAM role ARN for a given Lambda. Per-Lambda
-* override wins; otherwise the global default; otherwise `undefined`
-* (no role to assume — pass developer creds through).
-*/
-function effectiveAssumeRoleArn(logicalId, opt) {
-	if (!opt) return void 0;
-	return opt.perLambda?.[logicalId] ?? opt.globalArn;
-}
-
-//#endregion
 //#region src/utils/profile-resolver.ts
 /**
 * Resolve `--profile <p>` to a concrete credential set AND the profile's
@@ -705,6 +587,118 @@ function describeAwsFailureForWarn(err, operation) {
 //#endregion
 //#region src/utils/role-arn.ts
 /**
+* Upper bound on a value this module is willing to treat as a role ARN.
+*
+* NOT invented here: it is the length constraint the receiving API itself
+* documents for the field this value ends up in — STS `AssumeRole`'s
+* `RoleArn` (AWS STS API Reference: "Length Constraints: Minimum length of
+* 20. Maximum length of 2048."). Bounding at the receiver's own limit is the
+* defensible number because anything above it is a value STS would reject
+* anyway, so the cap can never turn a working configuration into a broken one.
+*
+* It is deliberately far above what a real role ARN needs — IAM's own entity
+* limits put the ceiling near 600 characters (`arn:<partition>:iam::<12
+* digits>:role/` plus a path of at most 512 and a name of at most 64) — because
+* the job here is stopping an UNBOUNDED wire value from being sent and printed,
+* not re-deriving IAM's schema. A tighter guess would be this module's own
+* opinion; 2048 is the receiver's.
+*
+* The MINIMUM (20) is deliberately NOT enforced. The grammar below already
+* implies a floor one character under it (`arn:a:iam::1:role/X` is 19), so
+* enforcing it would reject a synthetic-but-well-shaped value for no security
+* gain — length amplification is the half that matters here.
+*
+* The comparison is on UTF-16 units, which is exact for every value the
+* grammar can ACCEPT (it admits printable ASCII only, where units, code points
+* and bytes coincide) and a safe over-approximation for the rest.
+*/
+const IAM_ROLE_ARN_MAX_LENGTH = 2048;
+/**
+* The shape an IAM role ARN must have.
+*
+* Extracted from `src/cli/options.ts`, which validated `--assume-role` with
+* `/^arn:[^:]+:iam::\d+:role\//` while three WIRE resolution points asked the
+* same question with `startsWith('arn:')` (issue #607). Two spellings of one
+* question regenerate: this is the single site that owns it, and every other
+* site calls {@link isIamRoleArn} rather than paraphrasing it.
+*
+* Deliberate strictness decisions, in both directions:
+*
+*   - The PARTITION is `[A-Za-z0-9-]+`, so `aws`, `aws-cn`, `aws-us-gov` and
+*     the iso partitions all pass. Tighter than the extracted `[^:]+` (which
+*     admitted spaces and slashes), and still open-ended enough that a
+*     partition AWS has not launched yet is not rejected by name.
+*   - The ACCOUNT stays `[0-9]+` rather than `[0-9]{12}`. Real account ids are
+*     12 digits, but this is a SHAPE bound, not a schema validator — AWS
+*     rejects a wrong account id far better than cdk-local can — and this
+*     repo's own fixtures use short ids (`arn:aws:iam::111:role/...`).
+*   - The role tail is `[!-~]+`: at least one character, printable ASCII, no
+*     spaces. That accepts every path-shaped role name
+*     (`role/service-role/Foo`, `role/aws-service-role/x.amazonaws.com/Bar`)
+*     because IAM's own path grammar is exactly printable-ASCII segments.
+*   - The pattern is ANCHORED AT BOTH ENDS, which the extracted one was not.
+*     That is the half that matters for a hostile endpoint: an unanchored
+*     `role\/` accepts a value carrying a newline and a forged second line
+*     after it, and it is the value's PRINTED half that the flatten at the log
+*     sites was left holding on its own.
+*
+* LINEARITY: every quantified class is disjoint from the literal that follows
+* it (`[A-Za-z0-9-]+` then `:`, `[0-9]+` then `:`), and the one class that is
+* not (`[!-~]+`) is the last element before `$`. There is no alternation and
+* no nested quantifier, so there is no input on which this backtracks
+* super-linearly — which matters because it runs on values off the wire.
+* {@link isIamRoleArn} also applies the length bound BEFORE the match, so the
+* pattern never sees an unbounded string at all.
+*/
+const IAM_ROLE_ARN_PATTERN = /^arn:[A-Za-z0-9-]+:iam::[0-9]+:role\/[!-~]+$/;
+function isIamRoleArn(value) {
+	if (typeof value !== "string") return false;
+	if (value.length > 2048) return false;
+	return IAM_ROLE_ARN_PATTERN.test(value);
+}
+/**
+* Longest prefix of a rejected value {@link describeRejectedRoleArn} will show.
+*
+* 128 rather than 64: `arn:aws:iam::123456789012:role/` is 31 characters on
+* its own, so 64 left only 33 for the part that actually distinguishes one
+* role from another — a CDK-generated name
+* (`Stack-HandlerServiceRole1234ABCD-XXXXXXXXXXXX`) does not fit in that, and
+* a preview that elides exactly the informative half is not a diagnosis. 128
+* still leaves the rendered line well inside the 400-character bound its
+* callers' tests assert.
+*/
+const REJECTED_ARN_PREVIEW_MAX = 128;
+/**
+* Render a value {@link isIamRoleArn} REJECTED so it can go on a warn line.
+*
+* A rejection has two very different causes and the log line has to serve
+* both: an ordinary misconfiguration (a role NAME where an ARN was expected,
+* an ARN of the wrong resource type), where seeing the value is the whole
+* diagnosis; and a hostile or broken endpoint returning something unbounded,
+* where printing the value is the thing being prevented. So the value is
+* shown, flattened and clamped, with its true length named — the same shape
+* `sanitizeServiceExceptionMessage` uses, and for the same reason: a clamped
+* preview must never be mistakable for the whole value.
+*
+* The cut is on CODE POINTS so it cannot emit half of a surrogate pair, and
+* the reported count is the code-point count of the FLATTENED string, which is
+* the string the preview is a prefix of.
+*/
+function describeRejectedRoleArn(value) {
+	if (typeof value !== "string") return `a non-string ${typeof value} value`;
+	const points = [...flattenToOneLine(value)];
+	return `"${points.length <= REJECTED_ARN_PREVIEW_MAX ? points.join("") : `${points.slice(0, REJECTED_ARN_PREVIEW_MAX).join("")}...`}" (${points.length} characters)`;
+}
+/**
+* The sentence a guarded send throws when a value is refused before it leaves
+* the process. One spelling, exported, so every guarded send words the refusal
+* identically — including `local-invoke-agentcore.ts`'s own inline
+* `AssumeRoleCommand`, which is not routed through this module.
+*/
+function refusedRoleArnMessage(value) {
+	return `AssumeRole refused: the role ARN is not a well-formed IAM role ARN (expected arn:<partition>:iam::<account>:role/<name>, at most ${IAM_ROLE_ARN_MAX_LENGTH} characters): ${describeRejectedRoleArn(value)}. Nothing was sent to STS.`;
+}
+/**
 * {@link assumeRoleCredentials} failed, and the failure is cdk-local's OWN
 * rendering of it rather than a raw SDK error.
 *
@@ -796,6 +790,11 @@ var AssumeRoleFailure = class AssumeRoleFailure extends Error {
 * {@link AssumeRoleFailure} is for, and why BOTH throws below use it.
 */
 async function assumeRoleCredentials(opts) {
+	if (!isIamRoleArn(opts.roleArn)) {
+		const detail = `the role ARN is not well-formed: ${describeRejectedRoleArn(opts.roleArn)}`;
+		const message = refusedRoleArnMessage(opts.roleArn);
+		throw opts.makeError ? opts.makeError(message) : new AssumeRoleFailure(message, detail);
+	}
 	const sts = new STSClient(buildStsClientConfig({
 		region: opts.region,
 		profile: opts.profile
@@ -854,6 +853,7 @@ async function assumeRoleCredentials(opts) {
 async function applyRoleArnIfSet(opts) {
 	const roleArn = opts.roleArn || process.env[`${getEmbedConfig().envPrefix}_ROLE_ARN`];
 	if (!roleArn) return;
+	if (!isIamRoleArn(roleArn)) throw new Error(refusedRoleArnMessage(roleArn));
 	const logger = getLogger().child("role-arn");
 	const shownArn = flattenToOneLine(roleArn);
 	logger.debug(`Assuming role ${shownArn}...`);
@@ -882,6 +882,134 @@ async function applyRoleArnIfSet(opts) {
 	logger.info(`Assumed role ${shownArn} (session expires ${Expiration?.toISOString() ?? "unknown"})`);
 }
 
+//#endregion
+//#region src/cli/options.ts
+/**
+* Parse context key=value pairs from CLI arguments into a Record.
+*/
+function parseContextOptions(contextArgs) {
+	const context = {};
+	if (contextArgs) for (const arg of contextArgs) {
+		const eqIndex = arg.indexOf("=");
+		if (eqIndex > 0) context[arg.substring(0, eqIndex)] = arg.substring(eqIndex + 1);
+	}
+	return context;
+}
+/**
+* Options shared across every cdk-local command. Built per-call (not a
+* module-level const) so the `--role-arn` env-var hint reflects the active
+* embed config, which the command factory installs before calling this.
+*
+* `--region` is intentionally NOT in `commonOptions` — it is registered
+* separately via {@link regionOption} so a host CLI (cdkd) can swap the
+* shared option block once without losing the `--region` flag.
+*/
+function commonOptions() {
+	const { envPrefix } = getEmbedConfig();
+	return [
+		new Option("--verbose", "Enable verbose logging").default(false),
+		new Option("--profile <profile>", "AWS profile"),
+		new Option("--role-arn <arn>", `IAM role ARN to assume for AWS API calls (env: ${envPrefix}_ROLE_ARN)`),
+		new Option("-y, --yes", "Automatically answer interactive prompts with the recommended response").default(false)
+	];
+}
+/**
+* `--region` option attached to every command. The value drives both
+* host-side AWS SDK calls (STS `GetCallerIdentity` for
+* `${AWS::AccountId}` resolution, `AssumeRole` for `--assume-role`, etc.)
+* and the container's `AWS_REGION` env var. When omitted, region
+* precedence falls back to `AWS_REGION` / `AWS_DEFAULT_REGION` env,
+* then the synthesized stack region, then the `--profile`'s configured
+* region — same shape as the AWS CLI's `--region` flag (issue #245).
+*
+* Kept as a standalone export rather than baked into `commonOptions`
+* so a host CLI (cdkd) can swap the shared option block once without
+* losing this flag.
+*/
+const regionOption = new Option("--region <region>", "AWS region for SDK calls; defaults to AWS_REGION env, the synthesized stack region, or the resolved profile region");
+/**
+* App options. Built per-call (not a module-level const) so the `--app`
+* env-var hint reflects the active embed config.
+*
+* `--app` is optional: falls back to `${envPrefix}_APP` env var, then
+* `cdk.json` `app` field. Accepts either a shell command (e.g.
+* `"node app.ts"`) or a path to a pre-synthesized cloud assembly directory
+* (e.g. `"cdk.out"`).
+*/
+function appOptions() {
+	const { envPrefix } = getEmbedConfig();
+	return [new Option("-a, --app <command>", `CDK app command (e.g., "node app.ts") or path to a pre-synthesized cloud assembly directory. Falls back to cdk.json or ${envPrefix}_APP env`), new Option("--output <path>", "Output directory for synthesis").default("cdk.out")];
+}
+/**
+* Context options.
+*/
+const contextOptions = [new Option("-c, --context <key=value...>", "Set context values (can be specified multiple times)")];
+/**
+* Shape-checks both forms against {@link isIamRoleArn}.
+*
+* This file used to own a private `IAM_ROLE_ARN_REGEX`, while three WIRE
+* resolution points asked the same question with `startsWith('arn:')` (issue
+* #607) — so "is this a role ARN?" had two answers depending on whether the
+* value came from the flag or off a `GetFunctionConfiguration` response. The
+* predicate now lives in `src/utils/role-arn.ts`, beside the AssumeRole call
+* that consumes it, and this site calls it rather than keeping a copy.
+*/
+function parseAssumeRoleToken(raw, previous) {
+	const acc = previous ?? { perLambda: {} };
+	if (!acc.perLambda) acc.perLambda = {};
+	const eqIndex = raw.indexOf("=");
+	if (eqIndex === -1) {
+		const bare = raw.trim();
+		if (!isIamRoleArn(bare)) throw new Error(`Invalid --assume-role value "${raw}": expected an IAM role ARN like arn:aws:iam::123456789012:role/MyRole, or LogicalId=<arn>.`);
+		acc.globalArn = bare;
+		return acc;
+	}
+	const logicalId = raw.substring(0, eqIndex).trim();
+	const arn = raw.substring(eqIndex + 1).trim();
+	if (!/^[A-Za-z][A-Za-z0-9]*$/.test(logicalId)) throw new Error(`Invalid --assume-role value "${raw}": left-hand side "${logicalId}" must be a CloudFormation logical ID (alphanumeric, leading letter).`);
+	if (!isIamRoleArn(arn)) throw new Error(`Invalid --assume-role value "${raw}": right-hand side "${arn}" must be an IAM role ARN like arn:aws:iam::123456789012:role/MyRole.`);
+	acc.perLambda[logicalId] = arn;
+	return acc;
+}
+/**
+* Compose `--assume-role` (value-form accumulator) and the separate
+* `--assume-role-auto` boolean flag into the in-process
+* representation `localStartApiCommand` consumes downstream.
+*
+*   - both unset -> `undefined` (pass dev creds through)
+*   - only `--assume-role-auto` -> `{ perLambda: {}, bareAutoResolve: true }`
+*     (per-Lambda auto-resolve for every routed Lambda)
+*   - only `--assume-role` -> the value-form accumulator (global ARN
+*     and/or per-Lambda map) as-is
+*   - both -> accumulator with `bareAutoResolve = true` overlaid;
+*     the per-Lambda map still wins for named Lambdas, auto-resolve
+*     fills in for every Lambda the map does NOT name
+*
+* Enforces the mutual-exclusion guard: `--assume-role-auto` and a
+* global ARN (`--assume-role <arn>`) both occupy the "default for
+* every other Lambda" slot, so the combination is ambiguous and
+* rejected at boot with a clear error. The per-Lambda map IS
+* compatible with either side.
+*/
+function normalizeStartApiAssumeRole(raw, autoResolve) {
+	if (raw === void 0) return autoResolve ? {
+		perLambda: {},
+		bareAutoResolve: true
+	} : void 0;
+	if (autoResolve && raw.globalArn) throw new Error(`--assume-role-auto auto-resolves EACH routed Lambda's own execution role, but --assume-role ${raw.globalArn} also names a single global default. These are mutually exclusive on the global slot. Either drop the global ARN to keep --assume-role-auto for every Lambda, or drop --assume-role-auto to keep the global default. Per-Lambda overrides (--assume-role <LogicalId>=<arn>) are compatible with either side.`);
+	if (autoResolve) raw.bareAutoResolve = true;
+	return raw;
+}
+/**
+* Resolve the effective IAM role ARN for a given Lambda. Per-Lambda
+* override wins; otherwise the global default; otherwise `undefined`
+* (no role to assume — pass developer creds through).
+*/
+function effectiveAssumeRoleArn(logicalId, opt) {
+	if (!opt) return void 0;
+	return opt.perLambda?.[logicalId] ?? opt.globalArn;
+}
+
 //#endregion
 //#region src/utils/error-handler.ts
 /**
@@ -5112,7 +5240,8 @@ var CfnLocalStateProvider = class {
 		const client = this.getLambdaClient();
 		try {
 			const resp = await client.send(new GetFunctionConfigurationCommand({ FunctionName: functionPhysicalId }));
-			if (typeof resp.Role === "string" && resp.Role.startsWith("arn:")) return resp.Role;
+			if (isIamRoleArn(resp.Role)) return resp.Role;
+			if (resp.Role !== void 0) logger.warn(`${this.label}: GetFunctionConfiguration(${flattenToOneLine(functionPhysicalId)}) returned a Role that is not a well-formed IAM role ARN: ${describeRejectedRoleArn(resp.Role)}. Ignoring it. Pass the ARN explicitly: --assume-role <arn>.`);
 			return;
 		} catch (err) {
 			logger.warn(`${this.label}: GetFunctionConfiguration(${flattenToOneLine(functionPhysicalId)}) for --assume-role auto-resolve failed: ${formatAwsErrorForWarn(err, "Lambda GetFunctionConfiguration (--assume-role auto-resolve)")}. Pass the ARN explicitly: --assume-role <arn>.`);
@@ -5135,7 +5264,8 @@ var CfnLocalStateProvider = class {
 		const client = this.getAgentCoreControlClient();
 		try {
 			const resp = await client.send(new GetAgentRuntimeCommand({ agentRuntimeId: runtimePhysicalId }));
-			if (typeof resp.roleArn === "string" && resp.roleArn.startsWith("arn:")) return resp.roleArn;
+			if (isIamRoleArn(resp.roleArn)) return resp.roleArn;
+			if (resp.roleArn !== void 0) logger.warn(`${this.label}: GetAgentRuntime(${flattenToOneLine(runtimePhysicalId)}) returned a roleArn that is not a well-formed IAM role ARN: ${describeRejectedRoleArn(resp.roleArn)}. Ignoring it. Pass the ARN explicitly: --assume-role <arn>.`);
 			return;
 		} catch (err) {
 			logger.warn(`${this.label}: GetAgentRuntime(${flattenToOneLine(runtimePhysicalId)}) for --assume-role auto-resolve failed: ${formatAwsErrorForWarn(err, "bedrock-agentcore-control GetAgentRuntime (--assume-role auto-resolve)")}. Pass the ARN explicitly: --assume-role <arn>.`);
@@ -7772,6 +7902,7 @@ async function pullEcrImage(imageUri, options) {
 * mirrors the convention used by `src/utils/role-arn.ts`.
 */
 async function assumeRoleForEcr(roleArn, callerRegion, profile, logger) {
+	if (!isIamRoleArn(roleArn)) throw new LocalInvokeBuildError(refusedRoleArnMessage(roleArn));
 	logger.debug(`Assuming role ${roleArn} for ECR pull...`);
 	const sts = new STSClient(buildStsClientConfig({
 		region: callerRegion,
@@ -16358,6 +16489,7 @@ async function fetchLayerContentUrl(layer, credentials, options) {
 	}
 }
 async function assumeRoleForLayer(roleArn, region, options) {
+	if (!isIamRoleArn(roleArn)) throw new LayerMaterializationError(refusedRoleArnMessage(roleArn));
 	const client = (options.stsClientFactory ?? await defaultStsClientFactory())(region);
 	try {
 		const command = await buildAssumeRoleCommand(roleArn);
@@ -17724,7 +17856,10 @@ function resolveStartApiAssumeRoleArn(args) {
 	if (explicit) return explicit;
 	if (!assumeRole.bareAutoResolve) return void 0;
 	const roleProp = (lambdaResource.Properties ?? {})["Role"];
-	if (typeof roleProp === "string" && roleProp.startsWith("arn:")) return roleProp;
+	if (typeof roleProp === "string") {
+		if (isIamRoleArn(roleProp)) return roleProp;
+		getLogger().warn(`--assume-role: the template Role for '${logicalId}' is not a well-formed IAM role ARN: ${describeRejectedRoleArn(roleProp)}. Ignoring it.`);
+	}
 	if (stateBundle) {
 		const fromState = resolveExecutionRoleArnFromState(stateBundle.state, logicalId);
 		if (fromState) {
@@ -19263,23 +19398,56 @@ async function resolveAssumeRoleArnForLambda(assumeRole, stateForRoleHint, state
 	const fnPhysicalId = stateForRoleHint.resources[lambdaLogicalId]?.physicalId;
 	if (stateProvider?.resolveLambdaExecutionRoleArn && fnPhysicalId) {
 		const liveArn = await stateProvider.resolveLambdaExecutionRoleArn(fnPhysicalId);
-		if (liveArn) {
+		if (liveArn !== void 0 && !isIamRoleArn(liveArn)) logger.warn(`--assume-role: GetFunctionConfiguration for '${lambdaLogicalId}' produced a value that is not a well-formed IAM role ARN: ${describeRejectedRoleArn(liveArn)}. Ignoring it.`);
+		else if (liveArn) {
 			logger.info(`--assume-role: auto-resolved execution role from GetFunctionConfiguration: ${flattenToOneLine(liveArn)}`);
 			return liveArn;
 		}
 	}
 	logger.warn(`--assume-role: could not resolve the execution role ARN for '${lambdaLogicalId}'. Pass the ARN explicitly: --assume-role <arn>. Falling back to the developer's shell credentials.`);
 }
+/**
+* Pull a resource's execution-role ARN out of deployed stack state.
+*
+* Both reads below are WIRE-derived — `properties` / `observedProperties` and
+* the referenced role's cached `Arn` attribute all come from a
+* CloudFormation-backed state record — and the value is handed to
+* `AssumeRoleCommand.RoleArn`, so each is shape-checked with
+* {@link isIamRoleArn} rather than the `startsWith('arn:')` it used to carry
+* (issue #607).
+*
+* A value that is PRESENT and rejected warns, because a caller that gets
+* `undefined` cannot distinguish "state names no role" from "state names
+* something that is not a role ARN", and the second is a real misconfiguration
+* a user needs to see. Rejection still returns `undefined`, so the existing
+* fallback order (state -> live `GetFunctionConfiguration` -> shell
+* credentials) is unchanged.
+*
+* The warns are worded WITHOUT a `--assume-role:` prefix on purpose. An
+* earlier revision carried one, on the belief that every caller ends in that
+* flag's "could not resolve the execution role ARN" line. It does not:
+* {@link suggestAssumeRoleFromState} calls this function on a plain
+* `cdkl invoke --from-cfn-stack` with NO role flag at all (its caller is
+* guarded on `options.assumeRole === undefined`) and is silent on a miss — so
+* the prefix named a flag the user had not passed, on the one path where the
+* whole point is to SUGGEST it.
+*/
 function resolveExecutionRoleArnFromState(state, logicalId, roleProperty = "Role") {
 	const lambda = state.resources[logicalId];
 	if (!lambda) return void 0;
+	const logger = getLogger();
 	const roleRef = lambda.properties?.[roleProperty] ?? lambda.observedProperties?.[roleProperty];
-	if (typeof roleRef === "string" && roleRef.startsWith("arn:")) return roleRef;
+	if (typeof roleRef === "string") {
+		if (isIamRoleArn(roleRef)) return roleRef;
+		logger.warn(`Deployed state for '${logicalId}' carries a ${roleProperty} that is not a well-formed IAM role ARN: ${describeRejectedRoleArn(roleRef)}. Ignoring it.`);
+		return;
+	}
 	if (typeof roleRef === "object" && roleRef !== null) {
 		const refLogicalId = pickReferencedLogicalId(roleRef);
 		if (refLogicalId) {
 			const cached = state.resources[refLogicalId]?.attributes?.["Arn"];
-			if (typeof cached === "string" && cached.startsWith("arn:")) return cached;
+			if (isIamRoleArn(cached)) return cached;
+			if (typeof cached === "string" && cached.length > 0) logger.warn(`The cached Arn attribute of '${refLogicalId}' is not a well-formed IAM role ARN: ${describeRejectedRoleArn(cached)}. Ignoring it.`);
 		}
 	}
 }
@@ -21203,9 +21371,15 @@ async function applyAgentCoreCredentialEnv(dockerEnv, args) {
 * when all of those miss.
 */
 async function resolveAssumeRoleArn(options, resolved, loaded, stateProvider) {
-	if (typeof options.assumeRole === "string") return options.assumeRole;
+	if (typeof options.assumeRole === "string") {
+		if (!isIamRoleArn(options.assumeRole)) throw new CdkLocalError(`Invalid --assume-role value: expected an IAM role ARN like arn:aws:iam::123456789012:role/MyRole, got ${describeRejectedRoleArn(options.assumeRole)}.`, "LOCAL_INVOKE_AGENTCORE_ASSUME_ROLE_INVALID");
+		return options.assumeRole;
+	}
 	if (options.assumeRole !== true) return void 0;
-	if (resolved.roleArn) return resolved.roleArn;
+	if (resolved.roleArn !== void 0) {
+		if (isIamRoleArn(resolved.roleArn)) return resolved.roleArn;
+		getLogger().warn(`--assume-role: the template RoleArn for '${resolved.logicalId}' is not a well-formed IAM role ARN: ${describeRejectedRoleArn(resolved.roleArn)}. Ignoring it.`);
+	}
 	if (loaded) {
 		const fromState = resolveExecutionRoleArnFromState(loaded, resolved.logicalId, "RoleArn");
 		if (fromState) {
@@ -21215,7 +21389,8 @@ async function resolveAssumeRoleArn(options, resolved, loaded, stateProvider) {
 		const runtimePhysicalId = loaded.resources[resolved.logicalId]?.physicalId;
 		if (stateProvider?.resolveAgentCoreRuntimeRoleArn && runtimePhysicalId) {
 			const liveArn = await stateProvider.resolveAgentCoreRuntimeRoleArn(runtimePhysicalId);
-			if (liveArn) {
+			if (liveArn !== void 0 && !isIamRoleArn(liveArn)) getLogger().warn(`--assume-role: GetAgentRuntime for '${resolved.logicalId}' produced a value that is not a well-formed IAM role ARN: ${describeRejectedRoleArn(liveArn)}. Ignoring it.`);
+			else if (liveArn) {
 				getLogger().info(`--assume-role: auto-resolved execution role from GetAgentRuntime: ${flattenToOneLine(liveArn)}`);
 				return liveArn;
 			}
@@ -21327,6 +21502,7 @@ function forwardAwsEnv$1(env) {
 	}
 }
 async function assumeAgentCoreExecutionRole(roleArn, region, profile) {
+	if (!isIamRoleArn(roleArn)) throw new AssumeRoleFailure(refusedRoleArnMessage(roleArn), `the role ARN is not well-formed: ${describeRejectedRoleArn(roleArn)}`);
 	const { STSClient, AssumeRoleCommand } = await import("@aws-sdk/client-sts");
 	const sts = new STSClient(buildStsClientConfig({
 		region,
@@ -39452,4 +39628,4 @@ function addStudioSpecificOptions(cmd) {
 
 //#endregion
 export { applyEdgeResponseResult as $, buildJwksUrlFromIssuer as $n, resolveCfnStackName as $r, buildCloudMapIndex as $t, startAgentCoreHttpServer as A, describeCredentialLoadFailure as Ai, classifySourceChange as An, ConnectionRegistry as Ar, addRunTaskSpecificOptions as At, idFromArn as B, buildStageMap as Bn, resolveRuntimeFileExtension as Br, resolveEcsAssumeRoleOption as Bt, addListSpecificOptions as C, resolveAgentCoreTarget as Ci, waitForAgentCorePing as Cn, tryParseStatus as Cr, parseLbPortOverrides as Ct, createLocalStartAgentCoreCommand as D, tryResolveImageFnJoin as Di, computeCodeImageTag as Dn, probeHostGatewaySupport as Dr, addStartServiceSpecificOptions as Dt, addStartAgentCoreSpecificOptions as E, substituteImagePlaceholders as Ei, buildAgentCoreCodeImage as En, HOST_GATEWAY_MIN_VERSION as Er, resolveAlbFrontDoor as Et, createLocalStartCloudFrontCommand as F, createWatchPredicates as Fn, buildDisconnectEvent as Fr, addImageOverrideOptions as Ft, classifyS3Error as G, filterRoutesByApiIdentifiers as Gn, substituteEnvVarsFromState as Gr, enforceImageOverrideOrphans as Gt, createDeployedKvsDataSource as H, resolveEnvVars$1 as Hn, EcsTaskResolutionError as Hr, runEcsServiceEmulator as Ht, normalizeKvsFileKeys as I, resolveApiTargetSubset as In, buildMessageEvent as Ir, buildEcsImageResolutionContext$1 as It, startCloudFrontServer as J, startApiServer as Jn, createLocalStateProvider as Jr, resolveImageOverrides as Jt, createS3OriginReader as K, groupRoutesByServer as Kn, substituteEnvVarsFromStateAsync as Kr, mergeForService as Kt, parseKvsFileOverrides as L, createAuthorizerCache as Ln, architectureToPlatform as Lr, ecsClusterOption as Lt, startAgentCoreWsBridge as M, resolveProfileCredentials as Mi, createLocalInvokeCommand as Mn, handleConnectionsRequest as Mr, MAX_TASKS_SUBNET_RANGE_CAP as Mt, LocalStartCloudFrontError as N, addStartApiSpecificOptions as Nn, parseConnectionsPath as Nr, addCommonEcsServiceOptions as Nt, buildAgentCoreServeAuthCheck as O, LocalInvokeBuildError as Oi, renderCodeDockerfile as On, resolveHostGatewayExtraHosts as Or, createLocalStartServiceCommand as Ot, addStartCloudFrontSpecificOptions as P, createLocalStartApiCommand as Pn, buildConnectEvent as Pr, addEcsAssumeRoleOptions as Pt, applyEdgeRequestResult as Q, buildCognitoJwksUrl as Qn, resolveCfnRegion as Qr, listPinnedTargets as Qt, parseOriginOverrides as R, createFileWatcher as Rn, buildContainerImage as Rr, parseMaxTasks as Rt, StudioEventBus as S, pickAgentCoreCandidateStack as Si, waitForAgentCoreHttpReady as Sn, selectIntegrationResponse as Sr, createLocalStartAlbCommand as St, formatTargetListing as T, formatStateRemedy as Ti, SUPPORTED_CODE_RUNTIMES as Tn, HOST_DOCKER_INTERNAL_GATEWAY as Tr, isApplicationLoadBalancer as Tt, resolveDeployedKvsArnByName as U, availableApiIdentifiers as Un, substituteAgainstState as Ur, ImageOverrideError as Ut, resolveKvsModulesForDistribution as V, materializeLayerFromArn as Vn, resolveRuntimeImage as Vr, resolveSharedSidecarCredentials as Vt, resolveDeployedOriginBucket as W, filterRoutesByApiIdentifier as Wn, substituteAgainstStateAsync as Wr, buildImageOverrideTag as Wt, serveFromStaticOrigin as X, resolveServiceIntegrationParameters as Xn, rejectExplicitCfnStackWithMultipleStacks as Xr, describePinnedImageUri as Xt, resolveErrorResponseCandidates as Y, resolveSelectionExpression as Yn, isCfnFlagPresent as Yr, runImageOverrideBuilds as Yt, serveLambdaUrlOrigin as Z, defaultCredentialsLoader as Zn, resolveCfnFallbackRegion as Zr, isLocalCdkAssetImage as Zt, filterStudioTargetGroups as _, AGENTCORE_AGUI_PROTOCOL as _i, parseSseForJsonRpc as _n, applyAuthorizerOverlay as _r, createCloudFrontModule as _t, createLocalStudioCommand as a, countTargets as ai, attachContainerLogStreamer as an, computeRequestIdentityHash as ar, describeS3OriginDomain as at, renderStudioHtml as b, AGENTCORE_RUNTIME_TYPE as bi, AGENTCORE_SESSION_ID_HEADER as bn, evaluateResponseParameters as br, addAlbSpecificOptions as bt, startStudioProxy as c, discoverWebSocketApis as ci, bridgeAgentCoreWs as cn, invokeTokenAuthorizer as cr, pickFunctionUrlLogicalIdFromOrigin as ct, createStudioDispatcher as d, parseSelectionExpressionPath as di, A2A_PATH as dn, buildCorsConfigByApiId as dr, pickTargetFunctionLogicalId as dt, CfnLocalStateProvider as ei, CloudMapRegistry as en, createJwksCache as er, buildEdgeRequestEvent as et, filterStudioCustomResources as f, webSocketApiMatchesIdentifier as fi, a2aInvokeOnce as fn, buildCorsConfigFromCloudFrontChain as fr, resolveCloudFrontDistribution as ft, annotatePinnedEcsTargets as g, AGENTCORE_A2A_PROTOCOL as gi, mcpInvokeOnce as gn, translateLambdaResponse as gr, stripCloudFrontImport as gt, annotateEcsTaskPinnedTargets as h, resolveLambdaArnIntrinsic as hi, MCP_PROTOCOL_VERSION as hn, matchRoute as hr, runViewerResponse as ht, coerceStopRequest as i, resolveSingleTarget as ii, getContainerNetworkIp as in, buildMethodArn as ir, CLOUDFRONT_DISTRIBUTION_TYPE as it, attachAgentCoreWsBridge as j, buildStsClientConfig as ji, addInvokeSpecificOptions as jn, buildMgmtEndpointEnvUrl as jr, createLocalRunTaskCommand as jt, selectServeInboundAuth as k, describeAwsFailureForWarn as ki, toCmdArgv as kn, bufferToBody as kr, serviceStrategy as kt, relayServeRequest as l, discoverWebSocketApisOrThrow as li, invokeAgentCoreWs as ln, attachAuthorizers as lr, pickKvsLogicalIdFromArn as lt, annotateAlbPinnedBackingServices as m, pickRefLogicalId as mi, MCP_PATH as mn, matchPreflight as mr, runViewerRequest as mt, coerceRunRequest as n, resolveSsmParameters as ni, SOFT_RELOAD_COMPLETION_LOG_SUFFIX as nn, verifyJwtAuthorizer as nr, edgeHeadersToHttp as nt, resolveServeBaseUrl as o, listTargets as oi, addInvokeAgentCoreSpecificOptions as on, evaluateCachedLambdaPolicy as or, extractKvsAssociations as ot, isCustomResourceLambdaTarget as p, discoverRoutes as pi, MCP_CONTAINER_PORT as pn, isFunctionUrlOacFronted as pr, compileCloudFrontFunction as pt, matchBehavior as q, readMtlsMaterialsFromDisk as qn, LocalStateSourceError as qr, parseImageOverrideFlags as qt, coerceServeRequest as r, resolveWatchConfig as ri, setShadowReadyTimeoutMs as rn, verifyJwtViaDiscovery as rr, httpHeadersToEdge as rt, createStudioServeManager as s, availableWebSocketApiIdentifiers as si, createLocalInvokeAgentCoreCommand as sn, invokeRequestAuthorizer as sr, isCloudFrontDistribution as st, addStudioSpecificOptions as t, collectSsmParameterRefs as ti, DEFAULT_SHADOW_READY_TIMEOUT_MS as tn, verifyCognitoJwt as tr, buildEdgeResponseEvent as tt, reinvoke as u, filterWebSocketApisByIdentifiers as ui, A2A_CONTAINER_PORT as un, applyCorsResponseHeaders as ur, pickLambdaEdgeFunctionLogicalId as ut, startStudioServer as v, AGENTCORE_HTTP_PROTOCOL as vi, AGENTCORE_SIGV4_SERVICE as vn, buildHttpApiV2Event as vr, createLocalFileKvsDataSource as vt, createLocalListCommand as w, derivePseudoParametersFromRegion as wi, downloadAndExtractS3Bundle as wn, VtlEvaluationError as wr, resolveAlbTarget as wt, createStudioStore as x, AgentCoreResolutionError as xi, invokeAgentCore as xn, pickResponseTemplate as xr, albStrategy as xt, toStudioTargetGroups as y, AGENTCORE_MCP_PROTOCOL as yi, signAgentCoreInvocation as yn, buildRestV1Event as yr, createUnboundCloudFrontModule as yt, resolveCloudFrontTarget as z, attachStageContext as zn, resolveRuntimeCodeMountPath as zr, parseRestartPolicy as zt };
-//# sourceMappingURL=local-studio-DOdzcjkE.js.map
+//# sourceMappingURL=local-studio-J8BtocsI.js.map