@gajae-code/ai 0.1.1

package/src/providers/aws-credentials.ts

@@ -0,0 +1,501 @@
+/**
+ * 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 os from "node:os";
+import * as path from "node:path";
+import { $env, isEnoent, logger } from "@gajae-code/utils";
+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 = opts.profile || $env.AWS_PROFILE || "default";
+	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 = readEnvCredentials();
+	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).`,
+	);
+}
+
+function readEnvCredentials(): ResolvedCredentials | undefined {
+	const ak = $env.AWS_ACCESS_KEY_ID;
+	const sk = $env.AWS_SECRET_ACCESS_KEY;
+	if (!ak || !sk) return undefined;
+	const token = $env.AWS_SESSION_TOKEN;
+	return token
+		? { accessKeyId: ak, secretAccessKey: sk, sessionToken: token }
+		: { accessKeyId: ak, secretAccessKey: sk };
+}
+
+// ---------- INI parsing ----------
+
+/** Map of section name -> map of key -> value. Section names are stripped of
+ * any leading `profile ` (so `~/.aws/config` aligns with `~/.aws/credentials`). */
+type IniFile = Record<string, Record<string, string>>;
+
+function parseIni(text: string): IniFile {
+	const out: IniFile = {};
+	let current: Record<string, string> | null = null;
+	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()}`;
+			let section = out[name];
+			if (!section) {
+				section = {};
+				out[name] = section;
+			}
+			current = section;
+			continue;
+		}
+		if (!current) continue;
+		const eq = line.indexOf("=");
+		if (eq === -1) continue;
+		current[line.slice(0, eq).trim()] = line.slice(eq + 1).trim();
+	}
+	return out;
+}
+
+async function readIniFile(p: string): Promise<IniFile | undefined> {
+	try {
+		const text = await fs.promises.readFile(p, "utf8");
+		return parseIni(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 home = os.homedir();
+	const credentialsPath = $env.AWS_SHARED_CREDENTIALS_FILE || path.join(home, ".aws", "credentials");
+	const configPath = $env.AWS_CONFIG_FILE || path.join(home, ".aws", "config");
+
+	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;
+
+	if (merged.aws_access_key_id && merged.aws_secret_access_key) {
+		const out: ResolvedCredentials = {
+			accessKeyId: merged.aws_access_key_id,
+			secretAccessKey: merged.aws_secret_access_key,
+		};
+		if (merged.aws_session_token) out.sessionToken = merged.aws_session_token;
+		return out;
+	}
+
+	if (merged.sso_account_id && merged.sso_role_name) {
+		return readSsoCredentials(merged, configIni, region, signal);
+	}
+
+	if (merged.credential_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: IniFile | 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(os.homedir(), ".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();
+}

package/src/providers/aws-eventstream.ts

@@ -0,0 +1,185 @@
+/**
+ * `application/vnd.amazon.eventstream` decoder.
+ *
+ * Wire format (all integers big-endian):
+ *
+ *   [total length     u32]
+ *   [headers length   u32]
+ *   [prelude CRC32    u32]   <- CRC over the first 8 bytes
+ *   [headers          headers_length]
+ *   [payload          total_length - headers_length - 16]
+ *   [message CRC32    u32]   <- CRC over the entire message minus the trailing 4 bytes
+ *
+ * Headers: a sequence of `[name_len u8][name utf8][value_type u8][value …]`.
+ * We only need the typed values Bedrock emits (boolean true/false, byte, short,
+ * integer, long, byte-array, string, timestamp, uuid). All are surfaced as
+ * strings for ease of consumption — Bedrock only sets string-valued headers in
+ * practice (`:event-type`, `:message-type`, `:content-type`, `:exception-type`).
+ */
+
+const PRELUDE_LEN = 8;
+const PRELUDE_CRC_LEN = 4;
+const MESSAGE_CRC_LEN = 4;
+const HEADER_BLOCK_OFFSET = PRELUDE_LEN + PRELUDE_CRC_LEN;
+const MIN_MESSAGE_LEN = HEADER_BLOCK_OFFSET + MESSAGE_CRC_LEN;
+
+export interface EventStreamMessage {
+	/** Lower-cased copy is *not* applied — Bedrock uses casing like `:event-type` verbatim. */
+	headers: Record<string, string>;
+	payload: Uint8Array;
+}
+
+/** CRC32 (IEEE / zlib polynomial 0xEDB88320), matches `@aws-crypto/crc32`. */
+const CRC_TABLE = (() => {
+	const t = new Uint32Array(256);
+	for (let i = 0; i < 256; i++) {
+		let c = i;
+		for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+		t[i] = c >>> 0;
+	}
+	return t;
+})();
+
+export function crc32(bytes: Uint8Array, seed = 0): number {
+	let c = (seed ^ 0xffffffff) >>> 0;
+	for (let i = 0; i < bytes.length; i++) c = (CRC_TABLE[(c ^ bytes[i]) & 0xff] ^ (c >>> 8)) >>> 0;
+	return (c ^ 0xffffffff) >>> 0;
+}
+
+/**
+ * Decode a single, fully buffered eventstream message. Throws if the framing is
+ * malformed or either CRC mismatches. Used by both `decodeEventStream` (the
+ * streaming entry point) and the unit tests, which exercise it with hand-built
+ * frames.
+ */
+export function decodeMessage(frame: Uint8Array): EventStreamMessage {
+	if (frame.length < MIN_MESSAGE_LEN) throw new Error("eventstream: frame too short");
+	const view = new DataView(frame.buffer, frame.byteOffset, frame.byteLength);
+	const total = view.getUint32(0, false);
+	if (total !== frame.length) throw new Error(`eventstream: framed length ${total} != buffer ${frame.length}`);
+	const headersLen = view.getUint32(4, false);
+	const preludeCrc = view.getUint32(8, false);
+	const computedPreludeCrc = crc32(frame.subarray(0, PRELUDE_LEN));
+	if (computedPreludeCrc !== preludeCrc) throw new Error("eventstream: prelude CRC mismatch");
+	const msgCrc = view.getUint32(total - MESSAGE_CRC_LEN, false);
+	const computedMsgCrc = crc32(frame.subarray(0, total - MESSAGE_CRC_LEN));
+	if (computedMsgCrc !== msgCrc) throw new Error("eventstream: message CRC mismatch");
+
+	const headersBytes = frame.subarray(HEADER_BLOCK_OFFSET, HEADER_BLOCK_OFFSET + headersLen);
+	const payload = frame.subarray(HEADER_BLOCK_OFFSET + headersLen, total - MESSAGE_CRC_LEN);
+	return { headers: parseHeaders(headersBytes), payload };
+}
+
+function parseHeaders(buf: Uint8Array): Record<string, string> {
+	const out: Record<string, string> = {};
+	const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+	const decoder = new TextDecoder();
+	let p = 0;
+	while (p < buf.length) {
+		const nameLen = view.getUint8(p);
+		p += 1;
+		const name = decoder.decode(buf.subarray(p, p + nameLen));
+		p += nameLen;
+		const type = view.getUint8(p);
+		p += 1;
+		switch (type) {
+			case 0: // bool true
+				out[name] = "true";
+				break;
+			case 1: // bool false
+				out[name] = "false";
+				break;
+			case 2: // byte
+				out[name] = String(view.getInt8(p));
+				p += 1;
+				break;
+			case 3: // short
+				out[name] = String(view.getInt16(p, false));
+				p += 2;
+				break;
+			case 4: // integer
+				out[name] = String(view.getInt32(p, false));
+				p += 4;
+				break;
+			case 5: // long — surface as decimal string to avoid precision loss
+				out[name] = bigIntFromBytes(buf.subarray(p, p + 8)).toString();
+				p += 8;
+				break;
+			case 6: {
+				// byte array — base64 for safe transport
+				const len = view.getUint16(p, false);
+				p += 2;
+				out[name] = Buffer.from(buf.buffer, buf.byteOffset + p, len).toString("base64");
+				p += len;
+				break;
+			}
+			case 7: {
+				// string
+				const len = view.getUint16(p, false);
+				p += 2;
+				out[name] = decoder.decode(buf.subarray(p, p + len));
+				p += len;
+				break;
+			}
+			case 8: // timestamp (ms since epoch as i64)
+				out[name] = new Date(Number(bigIntFromBytes(buf.subarray(p, p + 8)))).toISOString();
+				p += 8;
+				break;
+			case 9: {
+				// uuid
+				const u = buf.subarray(p, p + 16);
+				const hex: string[] = [];
+				for (let i = 0; i < 16; i++) hex.push(u[i].toString(16).padStart(2, "0"));
+				out[name] =
+					`${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10, 16).join("")}`;
+				p += 16;
+				break;
+			}
+			default:
+				throw new Error(`eventstream: unknown header value type ${type}`);
+		}
+	}
+	return out;
+}
+
+function bigIntFromBytes(b: Uint8Array): bigint {
+	let v = 0n;
+	for (let i = 0; i < b.length; i++) v = (v << 8n) | BigInt(b[i]);
+	// sign-extend (two's complement)
+	if (b.length === 8 && b[0] & 0x80) v -= 1n << 64n;
+	return v;
+}
+
+/**
+ * Async generator that consumes a `ReadableStream<Uint8Array>` (e.g. a fetch
+ * response body) and yields fully-framed messages. Handles arbitrary chunk
+ * boundaries: messages may span multiple chunks, and a single chunk may carry
+ * many messages.
+ */
+export async function* decodeEventStream(source: ReadableStream<Uint8Array>): AsyncGenerator<EventStreamMessage> {
+	const reader = source.getReader();
+	// Single growable buffer; we slide a read cursor along it and compact when a
+	// complete prefix has been consumed. Avoids per-message Uint8Array copies.
+	let buf: Uint8Array<ArrayBufferLike> = new Uint8Array(0);
+	try {
+		while (true) {
+			const { value, done } = await reader.read();
+			if (value && value.length > 0) buf = buf.length === 0 ? value : Buffer.concat([buf, value]);
+			let offset = 0;
+			while (buf.length - offset >= 4) {
+				const dv = new DataView(buf.buffer, buf.byteOffset + offset, buf.length - offset);
+				const total = dv.getUint32(0, false);
+				if (total < MIN_MESSAGE_LEN) throw new Error(`eventstream: total length ${total} below minimum`);
+				if (buf.length - offset < total) break;
+				const frame = buf.subarray(offset, offset + total);
+				yield decodeMessage(frame);
+				offset += total;
+			}
+			if (offset > 0) buf = buf.slice(offset);
+			if (done) break;
+		}
+		if (buf.length > 0) throw new Error("eventstream: truncated message at end of stream");
+	} finally {
+		reader.releaseLock();
+	}
+}