@vib-rato/ai 0.16.0

package/src/providers/aws-credential-config.d.ts

@@ -0,0 +1,19 @@
+import type { AwsCredentials } from "./aws-sigv4";
+export type AwsIniFile = Record<string, Record<string, string>>;
+export interface AwsCredentialSourceOptions {
+    profile?: string;
+}
+export interface AwsCredentialSource {
+    profile: string;
+    credentialsPath: string;
+    configPath: string;
+}
+export type AwsProfileCapability = "static" | "process" | "sso" | undefined;
+export declare function parseAwsIni(text: string): AwsIniFile;
+export declare function resolveAwsCredentialSource(options?: AwsCredentialSourceOptions): AwsCredentialSource;
+export declare function readAwsStaticEnvironmentCredentials(): AwsCredentials | undefined;
+export declare function classifyAwsProfileCapability(profile: string, credentialsIni: AwsIniFile | undefined, configIni: AwsIniFile | undefined): AwsProfileCapability;
+export declare function hasResolvableAwsProfileSource(options?: AwsCredentialSourceOptions & {
+    onScan?: () => void;
+}, now?: number): boolean;
+export declare function isValidBedrockBearerToken(token: string | undefined): token is string;

package/src/providers/aws-credential-config.ts

@@ -0,0 +1,179 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { $credentialEnv, getTrustedHomeDir } from "@vib-rato/utils";
+import type { AwsCredentials } from "./aws-sigv4";
+
+export type AwsIniFile = Record<string, Record<string, string>>;
+
+export interface AwsCredentialSourceOptions {
+	profile?: string;
+}
+
+export interface AwsCredentialSource {
+	profile: string;
+	credentialsPath: string;
+	configPath: string;
+}
+
+export type AwsProfileCapability = "static" | "process" | "sso" | undefined;
+
+const AVAILABILITY_CACHE_MAX_AGE_MS = 1_000;
+const MAX_AWS_INI_FILE_BYTES = 1024 * 1024;
+
+interface FileFingerprint {
+	exists: boolean;
+	size?: number;
+	mtimeMs?: number;
+	ctimeMs?: number;
+	ino?: number;
+}
+
+interface AvailabilityCacheEntry {
+	source: AwsCredentialSource;
+	credentials: FileFingerprint;
+	config: FileFingerprint;
+	value: boolean;
+	checkedAt: number;
+}
+
+let availabilityCache: AvailabilityCacheEntry | undefined;
+
+export function parseAwsIni(text: string): AwsIniFile {
+	const out: AwsIniFile = {};
+	let current: Record<string, string> | undefined;
+	for (const rawLine of text.split(/\r?\n/)) {
+		const line = rawLine.trim();
+		if (!line || line.startsWith("#") || line.startsWith(";")) continue;
+		if (line.startsWith("[") && line.endsWith("]")) {
+			let name = line.slice(1, -1).trim();
+			if (name.startsWith("profile ")) name = name.slice(8).trim();
+			if (name.startsWith("sso-session ")) name = `sso-session:${name.slice(12).trim()}`;
+			current = out[name] ??= {};
+			continue;
+		}
+		if (!current) continue;
+		const equals = line.indexOf("=");
+		if (equals === -1) continue;
+		const key = line.slice(0, equals).trim();
+		const value = line.slice(equals + 1).trim();
+		if (key) current[key] = value;
+	}
+	return out;
+}
+
+export function resolveAwsCredentialSource(options: AwsCredentialSourceOptions = {}): AwsCredentialSource {
+	const profile = options.profile || $credentialEnv("AWS_PROFILE") || "default";
+	const home = getTrustedHomeDir();
+	return {
+		profile,
+		credentialsPath: path.resolve(
+			$credentialEnv("AWS_SHARED_CREDENTIALS_FILE") || path.join(home, ".aws", "credentials"),
+		),
+		configPath: path.resolve($credentialEnv("AWS_CONFIG_FILE") || path.join(home, ".aws", "config")),
+	};
+}
+
+export function readAwsStaticEnvironmentCredentials(): AwsCredentials | undefined {
+	const accessKeyId = $credentialEnv("AWS_ACCESS_KEY_ID");
+	const secretAccessKey = $credentialEnv("AWS_SECRET_ACCESS_KEY");
+	if (!accessKeyId || !secretAccessKey) return undefined;
+	const sessionToken = $credentialEnv("AWS_SESSION_TOKEN");
+	return sessionToken ? { accessKeyId, secretAccessKey, sessionToken } : { accessKeyId, secretAccessKey };
+}
+
+export function classifyAwsProfileCapability(
+	profile: string,
+	credentialsIni: AwsIniFile | undefined,
+	configIni: AwsIniFile | undefined,
+): AwsProfileCapability {
+	const merged = { ...(configIni?.[profile] ?? {}), ...(credentialsIni?.[profile] ?? {}) };
+	if (merged.aws_access_key_id && merged.aws_secret_access_key) return "static";
+	if (merged.sso_account_id && merged.sso_role_name) {
+		if (merged.sso_start_url && merged.sso_region) return "sso";
+		const session = merged.sso_session ? configIni?.[`sso-session:${merged.sso_session}`] : undefined;
+		if (session?.sso_start_url && session.sso_region) return "sso";
+	}
+	if (merged.credential_process) return "process";
+	return undefined;
+}
+
+export function hasResolvableAwsProfileSource(
+	options: AwsCredentialSourceOptions & { /** @internal Test-only cache scan observer. */ onScan?: () => void } = {},
+	now = Date.now(),
+): boolean {
+	const source = resolveAwsCredentialSource(options);
+	const credentials = fingerprint(source.credentialsPath);
+	const config = fingerprint(source.configPath);
+	if (
+		availabilityCache &&
+		now >= availabilityCache.checkedAt &&
+		now - availabilityCache.checkedAt < AVAILABILITY_CACHE_MAX_AGE_MS &&
+		sameSource(availabilityCache.source, source) &&
+		sameFingerprint(availabilityCache.credentials, credentials) &&
+		sameFingerprint(availabilityCache.config, config)
+	) {
+		return availabilityCache.value;
+	}
+	options.onScan?.();
+	const credentialsIni = readAwsIniSync(source.credentialsPath);
+	const configIni = readAwsIniSync(source.configPath);
+	const value = classifyAwsProfileCapability(source.profile, credentialsIni, configIni) !== undefined;
+	availabilityCache = { source, credentials, config, value, checkedAt: now };
+	return value;
+}
+
+export function isValidBedrockBearerToken(token: string | undefined): token is string {
+	if (!token) return false;
+	return !/[\x00-\x1f\x7f]/.test(token);
+}
+
+function readAwsIniSync(filePath: string): AwsIniFile | undefined {
+	let fd: number | undefined;
+	try {
+		fd = fs.openSync(filePath, fs.constants.O_RDONLY | fs.constants.O_NONBLOCK);
+		const stat = fs.fstatSync(fd);
+		if (!stat.isFile() || stat.size > MAX_AWS_INI_FILE_BYTES) return undefined;
+		const contents = Buffer.allocUnsafe(MAX_AWS_INI_FILE_BYTES + 1);
+		let bytesRead = 0;
+		while (bytesRead < contents.length) {
+			const count = fs.readSync(fd, contents, bytesRead, contents.length - bytesRead, bytesRead);
+			if (count === 0) break;
+			bytesRead += count;
+		}
+		if (bytesRead > MAX_AWS_INI_FILE_BYTES) return undefined;
+		return parseAwsIni(contents.toString("utf8", 0, bytesRead));
+	} catch {
+		return undefined;
+	} finally {
+		if (fd !== undefined) {
+			try {
+				fs.closeSync(fd);
+			} catch {
+				// Ignore close errors because file availability has already been determined.
+			}
+		}
+	}
+}
+
+function fingerprint(filePath: string): FileFingerprint {
+	try {
+		const stat = fs.statSync(filePath);
+		return { exists: true, size: stat.size, mtimeMs: stat.mtimeMs, ctimeMs: stat.ctimeMs, ino: stat.ino };
+	} catch {
+		return { exists: false };
+	}
+}
+
+function sameSource(a: AwsCredentialSource, b: AwsCredentialSource): boolean {
+	return a.profile === b.profile && a.credentialsPath === b.credentialsPath && a.configPath === b.configPath;
+}
+
+function sameFingerprint(a: FileFingerprint, b: FileFingerprint): boolean {
+	return (
+		a.exists === b.exists &&
+		a.size === b.size &&
+		a.mtimeMs === b.mtimeMs &&
+		a.ctimeMs === b.ctimeMs &&
+		a.ino === b.ino
+	);
+}

package/src/providers/aws-credentials.d.ts

@@ -0,0 +1,43 @@
+/**
+ * AWS credential resolution for the Bedrock provider.
+ *
+ * Chain (first hit wins):
+ *  1. Static credentials from the environment
+ *     (`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` [+ `AWS_SESSION_TOKEN`]).
+ *  2. Profile in `~/.aws/credentials` (and `~/.aws/config` for SSO):
+ *      - static `aws_access_key_id` / `aws_secret_access_key` / `aws_session_token`
+ *      - SSO profile referencing a cached token in `~/.aws/sso/cache/*.json`,
+ *        which we exchange for short-lived role credentials via
+ *        `https://portal.sso.{region}.amazonaws.com/federation/credentials`.
+ *      - `credential_process` — an external command emitting the AWS SDK
+ *        `Version: 1` JSON envelope on stdout. Used by `aws-vault`, `granted`,
+ *        in-house brokers, etc.
+ *  3. EC2 IMDSv2 (only when `AWS_EC2_METADATA_DISABLED` is unset / falsey and
+ *     `169.254.169.254` is reachable within a 1 s timeout).
+ *
+ * Resolved credentials are cached process-wide per profile and refreshed
+ * 60 s before `Expiration` to absorb clock skew.
+ */
+import type { AwsCredentials } from "./aws-sigv4";
+export interface ResolvedCredentials extends AwsCredentials {
+    /** Absolute expiration timestamp in ms. `undefined` for non-expiring static creds. */
+    expiresAt?: number;
+}
+export interface CredentialResolveOptions {
+    /** Named profile from `~/.aws/credentials` / `~/.aws/config`. */
+    profile?: string;
+    /** Falls back to env (`AWS_REGION` / `AWS_DEFAULT_REGION`) and finally `us-east-1`. */
+    region?: string;
+    signal?: AbortSignal;
+}
+export declare function resolveAwsCredentials(opts?: CredentialResolveOptions): Promise<ResolvedCredentials>;
+/** POSIX-shell-style tokenizer used by the AWS CLI for `credential_process`.
+ *
+ * Outside quotes a backslash escapes the next character. Inside single quotes
+ * everything is literal (no escapes, cannot contain `'`). Inside double quotes
+ * a backslash only escapes `$`, `` ` ``, `"`, and `\` — every other backslash
+ * is preserved verbatim, which is what makes Windows paths like
+ * `"C:\Program Files\tool\auth.exe"` survive tokenization. */
+export declare function tokenizeCredentialProcessCommand(cmd: string): string[];
+/** Test/diagnostic helper — drops cached credentials. */
+export declare function clearAwsCredentialCache(): void;

package/src/providers/aws-credentials.ts

@@ -0,0 +1,457 @@
+/**
+ * AWS credential resolution for the Bedrock provider.
+ *
+ * Chain (first hit wins):
+ *  1. Static credentials from the environment
+ *     (`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` [+ `AWS_SESSION_TOKEN`]).
+ *  2. Profile in `~/.aws/credentials` (and `~/.aws/config` for SSO):
+ *      - static `aws_access_key_id` / `aws_secret_access_key` / `aws_session_token`
+ *      - SSO profile referencing a cached token in `~/.aws/sso/cache/*.json`,
+ *        which we exchange for short-lived role credentials via
+ *        `https://portal.sso.{region}.amazonaws.com/federation/credentials`.
+ *      - `credential_process` — an external command emitting the AWS SDK
+ *        `Version: 1` JSON envelope on stdout. Used by `aws-vault`, `granted`,
+ *        in-house brokers, etc.
+ *  3. EC2 IMDSv2 (only when `AWS_EC2_METADATA_DISABLED` is unset / falsey and
+ *     `169.254.169.254` is reachable within a 1 s timeout).
+ *
+ * Resolved credentials are cached process-wide per profile and refreshed
+ * 60 s before `Expiration` to absorb clock skew.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { $env, getTrustedHomeDir, isEnoent, logger } from "@vib-rato/utils";
+import {
+	type AwsIniFile,
+	classifyAwsProfileCapability,
+	parseAwsIni,
+	readAwsStaticEnvironmentCredentials,
+	resolveAwsCredentialSource,
+} from "./aws-credential-config";
+import type { AwsCredentials } from "./aws-sigv4";
+
+export interface ResolvedCredentials extends AwsCredentials {
+	/** Absolute expiration timestamp in ms. `undefined` for non-expiring static creds. */
+	expiresAt?: number;
+}
+
+export interface CredentialResolveOptions {
+	/** Named profile from `~/.aws/credentials` / `~/.aws/config`. */
+	profile?: string;
+	/** Falls back to env (`AWS_REGION` / `AWS_DEFAULT_REGION`) and finally `us-east-1`. */
+	region?: string;
+	signal?: AbortSignal;
+}
+
+const REFRESH_SKEW_MS = 60_000;
+
+interface CacheEntry {
+	creds: ResolvedCredentials;
+	expiresAt: number;
+}
+
+const cache: Map<string, CacheEntry> = new Map();
+
+export async function resolveAwsCredentials(opts: CredentialResolveOptions = {}): Promise<ResolvedCredentials> {
+	const profile = resolveAwsCredentialSource({ profile: opts.profile }).profile;
+	const region = opts.region || $env.AWS_REGION || $env.AWS_DEFAULT_REGION || "us-east-1";
+	const cacheKey = `${profile}\x00${region}`;
+
+	const hit = cache.get(cacheKey);
+	if (hit && hit.expiresAt - REFRESH_SKEW_MS > Date.now()) return hit.creds;
+
+	const creds = await resolveFresh(profile, region, opts.signal);
+	cache.set(cacheKey, { creds, expiresAt: creds.expiresAt ?? Number.POSITIVE_INFINITY });
+	return creds;
+}
+
+async function resolveFresh(profile: string, region: string, signal?: AbortSignal): Promise<ResolvedCredentials> {
+	// 1. Environment first — matches the AWS SDK chain order.
+	const envCreds = readAwsStaticEnvironmentCredentials();
+	if (envCreds) return envCreds;
+
+	// 2. Profile (static or SSO).
+	const profileCreds = await readProfileCredentials(profile, region, signal);
+	if (profileCreds) return profileCreds;
+
+	// 3. EC2 IMDSv2.
+	if ($env.AWS_EC2_METADATA_DISABLED?.toLowerCase() !== "true") {
+		const imdsCreds = await readImdsCredentials(signal);
+		if (imdsCreds) return imdsCreds;
+	}
+
+	throw new Error(
+		`Unable to resolve AWS credentials. Set AWS_ACCESS_KEY_ID+AWS_SECRET_ACCESS_KEY, ` +
+			`or configure profile '${profile}' in ~/.aws/credentials (or ~/.aws/config for SSO).`,
+	);
+}
+
+async function readIniFile(p: string): Promise<AwsIniFile | undefined> {
+	try {
+		const text = await fs.promises.readFile(p, "utf8");
+		return parseAwsIni(text);
+	} catch (err) {
+		if (isEnoent(err)) return undefined;
+		throw err;
+	}
+}
+
+// ---------- Profile / SSO ----------
+
+async function readProfileCredentials(
+	profile: string,
+	region: string,
+	signal: AbortSignal | undefined,
+): Promise<ResolvedCredentials | undefined> {
+	const { credentialsPath, configPath } = resolveAwsCredentialSource({ profile });
+
+	const credentialsIni = await readIniFile(credentialsPath);
+	const configIni = await readIniFile(configPath);
+
+	// Static credentials live in ~/.aws/credentials; SSO config lives in
+	// ~/.aws/config under `[profile foo]`. Merge into a single view.
+	const merged: Record<string, string> = { ...(configIni?.[profile] ?? {}), ...(credentialsIni?.[profile] ?? {}) };
+	if (Object.keys(merged).length === 0) return undefined;
+
+	const capability = classifyAwsProfileCapability(profile, credentialsIni, configIni);
+	if (capability === "static") {
+		const { aws_access_key_id: accessKeyId, aws_secret_access_key: secretAccessKey } = merged;
+		if (!accessKeyId || !secretAccessKey) return undefined;
+		const out: ResolvedCredentials = { accessKeyId, secretAccessKey };
+		if (merged.aws_session_token) out.sessionToken = merged.aws_session_token;
+		return out;
+	}
+	if (capability === "sso") return readSsoCredentials(merged, configIni, region, signal);
+	if (capability === "process") return readCredentialProcess(profile, merged.credential_process, signal);
+
+	return undefined;
+}
+
+interface SsoCachedToken {
+	accessToken?: string;
+	expiresAt?: string;
+	startUrl?: string;
+	region?: string;
+}
+
+async function readSsoCredentials(
+	profileCfg: Record<string, string>,
+	configIni: AwsIniFile | undefined,
+	defaultRegion: string,
+	signal: AbortSignal | undefined,
+): Promise<ResolvedCredentials | undefined> {
+	// Two SSO profile shapes:
+	//   - legacy: `sso_start_url` + `sso_region` directly on the profile
+	//   - sso-session: `sso_session = my-session` references a `[sso-session my-session]` block
+	let startUrl = profileCfg.sso_start_url;
+	let ssoRegion = profileCfg.sso_region;
+	const sessionName = profileCfg.sso_session;
+	if (sessionName && configIni) {
+		const session = configIni[`sso-session:${sessionName}`];
+		if (session) {
+			startUrl = startUrl || session.sso_start_url;
+			ssoRegion = ssoRegion || session.sso_region;
+		}
+	}
+	if (!startUrl || !ssoRegion) return undefined;
+
+	const token = await loadSsoCachedToken(startUrl, sessionName);
+	if (!token?.accessToken) {
+		throw new Error(`AWS SSO token for ${startUrl} not found in ~/.aws/sso/cache. Run 'aws sso login' first.`);
+	}
+	const expiresAt = token.expiresAt ? Date.parse(token.expiresAt) : Number.POSITIVE_INFINITY;
+	if (Number.isFinite(expiresAt) && expiresAt <= Date.now()) {
+		throw new Error(`AWS SSO token for ${startUrl} has expired. Run 'aws sso login' to refresh.`);
+	}
+
+	const url =
+		`https://portal.sso.${ssoRegion}.amazonaws.com/federation/credentials` +
+		`?account_id=${encodeURIComponent(profileCfg.sso_account_id)}` +
+		`&role_name=${encodeURIComponent(profileCfg.sso_role_name)}`;
+	const response = await fetch(url, {
+		method: "GET",
+		headers: { "x-amz-sso_bearer_token": token.accessToken },
+		signal,
+	});
+	if (!response.ok) {
+		const body = await response.text().catch(() => "");
+		throw new Error(`AWS SSO GetRoleCredentials failed: ${response.status} ${body.slice(0, 200)}`);
+	}
+	const json = (await response.json()) as {
+		roleCredentials?: { accessKeyId: string; secretAccessKey: string; sessionToken: string; expiration: number };
+	};
+	const role = json.roleCredentials;
+	if (!role) throw new Error("AWS SSO GetRoleCredentials: missing roleCredentials in response");
+
+	// region is honored at the caller; we only consume defaultRegion to keep the
+	// param wired for symmetry with other resolution paths.
+	void defaultRegion;
+
+	return {
+		accessKeyId: role.accessKeyId,
+		secretAccessKey: role.secretAccessKey,
+		sessionToken: role.sessionToken,
+		expiresAt: role.expiration,
+	};
+}
+
+async function loadSsoCachedToken(
+	startUrl: string,
+	sessionName: string | undefined,
+): Promise<SsoCachedToken | undefined> {
+	const cacheDir = path.join(getTrustedHomeDir(), ".aws", "sso", "cache");
+	let entries: string[];
+	try {
+		entries = await fs.promises.readdir(cacheDir);
+	} catch (err) {
+		if (isEnoent(err)) return undefined;
+		throw err;
+	}
+	// Prefer the deterministic hash for legacy `sso_start_url` profiles or the
+	// session name for the newer `sso-session` shape; otherwise scan.
+	const candidates: string[] = [];
+	const hash = await sha1Hex(sessionName || startUrl);
+	candidates.push(`${hash}.json`);
+	for (const entry of entries) {
+		if (entry.endsWith(".json") && !candidates.includes(entry)) candidates.push(entry);
+	}
+	for (const file of candidates) {
+		if (!entries.includes(file)) continue;
+		try {
+			const text = await fs.promises.readFile(path.join(cacheDir, file), "utf8");
+			const parsed = JSON.parse(text) as SsoCachedToken;
+			if (parsed.startUrl === startUrl || (sessionName && file === `${hash}.json`)) {
+				return parsed;
+			}
+		} catch (err) {
+			logger.debug("aws-credentials: failed to read SSO cache", { file, err: String(err) });
+		}
+	}
+	return undefined;
+}
+
+async function sha1Hex(input: string): Promise<string> {
+	const digest = await globalThis.crypto.subtle.digest("SHA-1", new TextEncoder().encode(input));
+	const bytes = new Uint8Array(digest);
+	let out = "";
+	for (let i = 0; i < bytes.length; i++) out += bytes[i].toString(16).padStart(2, "0");
+	return out;
+}
+
+// ---------- credential_process ----------
+
+/** JSON envelope emitted by an external credential process. Matches the
+ * AWS CLI / SDK contract documented at
+ * https://docs.aws.amazon.com/sdkref/latest/guide/feature-process-credentials.html */
+interface CredentialProcessEnvelope {
+	Version?: number;
+	AccessKeyId?: string;
+	SecretAccessKey?: string;
+	SessionToken?: string;
+	Expiration?: string;
+}
+
+async function readCredentialProcess(
+	profile: string,
+	command: string,
+	signal: AbortSignal | undefined,
+): Promise<ResolvedCredentials> {
+	const argv = buildCredentialProcessArgv(profile, command);
+
+	const child = Bun.spawn(argv, {
+		stdin: "ignore",
+		stdout: "pipe",
+		stderr: "pipe",
+		windowsHide: true,
+		signal,
+	});
+	const [stdout, stderr, exitCode] = await Promise.all([
+		new Response(child.stdout).text(),
+		new Response(child.stderr).text(),
+		child.exited,
+	]);
+	if (exitCode !== 0) {
+		const tail = stderr.trim().slice(-512) || stdout.trim().slice(-512) || "(no output)";
+		throw new Error(`AWS credential_process for profile '${profile}' exited ${exitCode}: ${tail}`);
+	}
+
+	let parsed: CredentialProcessEnvelope;
+	try {
+		parsed = JSON.parse(stdout) as CredentialProcessEnvelope;
+	} catch (err) {
+		throw new Error(`AWS credential_process for profile '${profile}' did not emit valid JSON: ${String(err)}`);
+	}
+	if (parsed.Version !== 1) {
+		throw new Error(
+			`AWS credential_process for profile '${profile}' returned unsupported Version ${parsed.Version ?? "<missing>"}; expected 1.`,
+		);
+	}
+	if (!parsed.AccessKeyId || !parsed.SecretAccessKey) {
+		throw new Error(
+			`AWS credential_process for profile '${profile}' returned envelope without AccessKeyId/SecretAccessKey.`,
+		);
+	}
+
+	const out: ResolvedCredentials = {
+		accessKeyId: parsed.AccessKeyId,
+		secretAccessKey: parsed.SecretAccessKey,
+	};
+	if (parsed.SessionToken) out.sessionToken = parsed.SessionToken;
+	if (parsed.Expiration) {
+		const exp = Date.parse(parsed.Expiration);
+		if (!Number.isNaN(exp)) out.expiresAt = exp;
+	}
+	return out;
+}
+
+/** Resolve the argv for `Bun.spawn`. On Windows we route `.cmd`/`.bat` helpers
+ * through `cmd.exe /c` because direct execution refuses batch files (mirrors
+ * Node's `execFile` policy and avoids surprise no-ops). */
+function buildCredentialProcessArgv(profile: string, command: string): string[] {
+	const tokens = tokenizeCredentialProcessCommand(command);
+	if (tokens.length === 0) {
+		throw new Error(`AWS credential_process for profile '${profile}' is empty.`);
+	}
+	if (process.platform === "win32" && isBatchScript(tokens[0])) {
+		return ["cmd.exe", "/d", "/s", "/c", command];
+	}
+	return tokens;
+}
+
+function isBatchScript(executable: string): boolean {
+	const lower = executable.toLowerCase();
+	return lower.endsWith(".cmd") || lower.endsWith(".bat");
+}
+
+/** POSIX-shell-style tokenizer used by the AWS CLI for `credential_process`.
+ *
+ * Outside quotes a backslash escapes the next character. Inside single quotes
+ * everything is literal (no escapes, cannot contain `'`). Inside double quotes
+ * a backslash only escapes `$`, `` ` ``, `"`, and `\` — every other backslash
+ * is preserved verbatim, which is what makes Windows paths like
+ * `"C:\Program Files\tool\auth.exe"` survive tokenization. */
+export function tokenizeCredentialProcessCommand(cmd: string): string[] {
+	const tokens: string[] = [];
+	let current = "";
+	let hasToken = false;
+	let mode: "normal" | "single" | "double" = "normal";
+	for (let i = 0; i < cmd.length; i++) {
+		const ch = cmd[i];
+		if (mode === "normal") {
+			if (ch === "'") {
+				mode = "single";
+				hasToken = true;
+				continue;
+			}
+			if (ch === '"') {
+				mode = "double";
+				hasToken = true;
+				continue;
+			}
+			if (ch === "\\" && i + 1 < cmd.length) {
+				current += cmd[++i];
+				hasToken = true;
+				continue;
+			}
+			if (ch === " " || ch === "\t" || ch === "\n" || ch === "\r") {
+				if (hasToken) {
+					tokens.push(current);
+					current = "";
+					hasToken = false;
+				}
+				continue;
+			}
+			current += ch;
+			hasToken = true;
+			continue;
+		}
+		if (mode === "single") {
+			if (ch === "'") {
+				mode = "normal";
+				continue;
+			}
+			current += ch;
+			continue;
+		}
+		// double-quote
+		if (ch === '"') {
+			mode = "normal";
+			continue;
+		}
+		if (ch === "\\" && i + 1 < cmd.length) {
+			const next = cmd[i + 1];
+			if (next === "$" || next === "`" || next === '"' || next === "\\") {
+				current += next;
+				i++;
+				continue;
+			}
+			// Preserve literal backslash for Windows paths.
+			current += ch;
+			continue;
+		}
+		current += ch;
+	}
+	if (mode !== "normal") {
+		throw new Error("AWS credential_process command has an unterminated quote.");
+	}
+	if (hasToken) tokens.push(current);
+	return tokens;
+}
+
+// ---------- IMDSv2 ----------
+
+const IMDS_HOST = "169.254.169.254";
+const IMDS_TIMEOUT_MS = 1000;
+
+async function readImdsCredentials(parentSignal: AbortSignal | undefined): Promise<ResolvedCredentials | undefined> {
+	const timeout = AbortSignal.timeout(IMDS_TIMEOUT_MS);
+	const signal = parentSignal ? AbortSignal.any([parentSignal, timeout]) : timeout;
+	try {
+		const tokenRes = await fetch(`http://${IMDS_HOST}/latest/api/token`, {
+			method: "PUT",
+			headers: { "x-aws-ec2-metadata-token-ttl-seconds": "21600" },
+			signal,
+		});
+		if (!tokenRes.ok) return undefined;
+		const token = await tokenRes.text();
+
+		const roleRes = await fetch(`http://${IMDS_HOST}/latest/meta-data/iam/security-credentials/`, {
+			headers: { "x-aws-ec2-metadata-token": token },
+			signal,
+		});
+		if (!roleRes.ok) return undefined;
+		const role = (await roleRes.text()).trim();
+		if (!role) return undefined;
+
+		const credsRes = await fetch(
+			`http://${IMDS_HOST}/latest/meta-data/iam/security-credentials/${encodeURIComponent(role)}`,
+			{
+				headers: { "x-aws-ec2-metadata-token": token },
+				signal,
+			},
+		);
+		if (!credsRes.ok) return undefined;
+		const body = (await credsRes.json()) as {
+			AccessKeyId?: string;
+			SecretAccessKey?: string;
+			Token?: string;
+			Expiration?: string;
+		};
+		if (!body.AccessKeyId || !body.SecretAccessKey) return undefined;
+		const out: ResolvedCredentials = {
+			accessKeyId: body.AccessKeyId,
+			secretAccessKey: body.SecretAccessKey,
+		};
+		if (body.Token) out.sessionToken = body.Token;
+		if (body.Expiration) out.expiresAt = Date.parse(body.Expiration);
+		return out;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Test/diagnostic helper — drops cached credentials. */
+export function clearAwsCredentialCache(): void {
+	cache.clear();
+}