@gajae-code/coding-agent 0.12.21 → 0.13.0

package/src/sdk/transport/serve-cli.ts

@@ -1,9 +1,10 @@
+import { getAgentDir } from "@gajae-code/utils";
 import { CliParseError } from "@gajae-code/utils/cli";
-import type { SdkSessionEndpoint } from "../client/discovery";
-import { listSdkSessionEndpoints } from "../client/discovery";
-import { type SdkEndpointSelectionError, selectLiveEndpoint } from "../client/liveness";
+import { readSdkBrokerDiscovery, SdkClient, SdkClientError } from "../client";
 import { DEFAULT_PENDING_CEILING_BYTES, MIN_PENDING_CEILING_BYTES, startSocketServe, startStdioServe } from "./index";
 
+const MAX_SESSION_LIST_PAGES = 10_000;
+
 type ServeMode = { kind: "stdio" } | { kind: "socket"; socketPath: string };
 
 interface ServeArguments {
@@ -67,11 +68,72 @@ export function resolveServePendingCeiling(flagValue: string | undefined, envVal
 	return ceiling;
 }
 
-function isSelectionError(value: SdkSessionEndpoint | SdkEndpointSelectionError): value is SdkEndpointSelectionError {
-	return "code" in value;
+type BrokerSessionRow = { sessionId: string; live: boolean; ambiguous: boolean };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Extracts the broker `result` envelope, converting an explicit error frame into a typed throw. */
+function brokerResult(value: unknown): Record<string, unknown> {
+	if (isRecord(value) && value.ok === false) {
+		const error = isRecord(value.error) ? value.error : {};
+		const code = typeof error.code === "string" ? error.code : "unavailable";
+		const message = typeof error.message === "string" ? error.message : "SDK broker request failed";
+		throw new SdkClientError(code, message, value.error);
+	}
+	return isRecord(value) && isRecord(value.result) ? value.result : {};
+}
+
+function brokerSessionRows(value: Record<string, unknown>): BrokerSessionRow[] {
+	if (!Array.isArray(value.sessions)) return [];
+	return value.sessions.flatMap(item => {
+		if (!isRecord(item) || typeof item.sessionId !== "string" || !item.sessionId) return [];
+		return [{ sessionId: item.sessionId, live: item.live === true, ambiguous: item.ambiguous === true }];
+	});
 }
 
-/** Attaches a stdio or Unix-socket relay to one live SDK session endpoint. */
+/**
+ * Exhausts broker `session.list` cursor pagination (default page limit 100) to
+ * one full snapshot; exported for tests.
+ */
+export async function listBrokerSessions(broker: SdkClient): Promise<BrokerSessionRow[]> {
+	const rows: BrokerSessionRow[] = [];
+	let cursor: string | undefined;
+	for (let pageCount = 0; pageCount < MAX_SESSION_LIST_PAGES; pageCount++) {
+		const listed = brokerResult(await broker.global("session.list", cursor === undefined ? {} : { cursor }));
+		rows.push(...brokerSessionRows(listed));
+		const nextCursor =
+			typeof listed.continuationCursor === "string" && listed.continuationCursor.length > 0
+				? listed.continuationCursor
+				: undefined;
+		if (!nextCursor) return rows;
+		cursor = nextCursor;
+	}
+	throw new SdkClientError("protocol_error", "session.list exceeded the page budget.");
+}
+
+/** Selects the session to serve through broker `session.list` truth (C10); exported for tests. */
+export function selectBrokerSession(sessions: BrokerSessionRow[], explicitSessionId: string | undefined): string {
+	if (explicitSessionId !== undefined) {
+		const row = sessions.find(session => session.sessionId === explicitSessionId);
+		if (!row) throw new Error(`not_found: session ${explicitSessionId} is not indexed by the broker`);
+		if (row.ambiguous) throw new Error("ambiguous_session: session id maps to more than one state root");
+		if (!row.live) throw new Error(`endpoint_stale: session ${explicitSessionId} endpoint is not live`);
+		return row.sessionId;
+	}
+	const live = sessions.filter(session => session.live && !session.ambiguous);
+	if (live.length === 0) throw new Error("no_live_endpoint: no live session endpoint");
+	if (live.length > 1) throw new Error("multiple_live_endpoints: more than one live session; specify --session <id>");
+	return live[0]!.sessionId;
+}
+
+/**
+ * Attaches a stdio or Unix-socket relay to one live SDK session endpoint.
+ * Session targeting is broker-bound (C10): `session.list` resolves the session
+ * and `session.get_endpoint` mints the exact credential — never a direct
+ * endpoint-file read. A missing or unreachable broker fails closed.
+ */
 export async function runSdkServe(argv: string[]): Promise<void> {
 	const parsed = parseServeArguments(argv);
 	if (parsed.mode.kind === "socket" && process.platform === "win32")
@@ -80,26 +142,51 @@ export async function runSdkServe(argv: string[]): Promise<void> {
 		parsed.pendingCeiling,
 		process.env.GJC_SDK_SERVE_PENDING_CEILING_BYTES,
 	);
-	const discovered = await listSdkSessionEndpoints(process.cwd());
-	const selected = selectLiveEndpoint(discovered.endpoints, parsed.sessionId);
-	if (isSelectionError(selected)) {
-		const sessionHint = parsed.sessionId ? ` for session ${parsed.sessionId}` : "; specify --session <id>";
-		throw new Error(`${selected.code}${sessionHint}`);
+	const discovery = await readSdkBrokerDiscovery(getAgentDir());
+	if (!discovery) throw new Error("broker_unavailable: SDK broker is not running");
+	let broker: SdkClient;
+	try {
+		broker = await SdkClient.connect(discovery.url, discovery.token);
+	} catch {
+		throw new Error("broker_unavailable: SDK broker is not reachable");
 	}
-	const options = { url: selected.url, token: selected.token, pendingCeilingBytes };
-	const handle =
-		parsed.mode.kind === "stdio"
-			? await startStdioServe(options)
-			: await startSocketServe({ ...options, socketPath: parsed.mode.socketPath });
-	const stop = () => {
-		void handle.close();
-	};
-	process.once("SIGINT", stop);
-	process.once("SIGTERM", stop);
 	try {
-		await handle.done;
+		const sessionId = selectBrokerSession(await listBrokerSessions(broker), parsed.sessionId);
+		const endpoint = brokerResult(await broker.global("session.get_endpoint", { sessionId }));
+		const url = typeof endpoint.url === "string" && endpoint.url ? endpoint.url : undefined;
+		const token = typeof endpoint.token === "string" ? endpoint.token : "";
+		if (!url) throw new Error("unavailable: broker returned an invalid endpoint record");
+		const options = {
+			url,
+			token,
+			pendingCeilingBytes,
+			validateDownstreamFrame: (source: string): boolean => {
+				try {
+					const frame = JSON.parse(source) as { type?: unknown; elevationRequestId?: unknown };
+					return frame.type !== "control_request" || frame.elevationRequestId === undefined;
+				} catch {
+					return true;
+				}
+			},
+		};
+		const handle =
+			parsed.mode.kind === "stdio"
+				? await startStdioServe(options)
+				: await startSocketServe({ ...options, socketPath: parsed.mode.socketPath });
+		const stop = () => {
+			void handle.close();
+		};
+		process.once("SIGINT", stop);
+		process.once("SIGTERM", stop);
+		try {
+			await handle.done;
+		} finally {
+			process.removeListener("SIGINT", stop);
+			process.removeListener("SIGTERM", stop);
+		}
+	} catch (error) {
+		throw error instanceof SdkClientError ? new Error(`${error.code}: ${error.message}`) : error;
 	} finally {
-		process.removeListener("SIGINT", stop);
-		process.removeListener("SIGTERM", stop);
+		await broker.close();
 	}
 }

package/src/secrets/obfuscator.ts

@@ -21,17 +21,95 @@ export interface SecretEntry {
 
 const REPLACEMENT_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
 
-/** Generate a deterministic same-length replacement string from a secret value. */
-function generateDeterministicReplacement(secret: string): string {
-	// Simple hash: use Bun.hash for speed, seed from the secret bytes
-	const hash = BigInt(Bun.hash(secret));
+/**
+ * Domain separator for replace-mode replacement derivation. Distinct from
+ * `PLACEHOLDER_DOMAIN` so a value minted under one construction can never be
+ * confused with a value minted under the other, even with the same key.
+ */
+const REPLACEMENT_DOMAIN = "gjc.secret-obfuscation.replacement.v1\0";
+
+/** One HMAC-SHA256 digest block length in bytes. */
+const REPLACEMENT_DIGEST_BYTES = 32;
+
+/** Largest accepted byte for uniform rejection sampling (256 - (256 % 62)). */
+const REPLACEMENT_REJECT_THRESHOLD = 248;
+
+/**
+ * Generate a deterministic, keyed, same-length replacement string from a
+ * secret value.
+ *
+ * COMPATIBILITY CONTRACT (required behavior, must never regress):
+ * - Deterministic within a process: the same secret under the same key always
+ *   yields the same replacement, independent of entry order or call order.
+ * - Same length: `result.length === secret.length` (UTF-16 code units, i.e.
+ *   `String.prototype.length` semantics — unchanged from the pre-fix
+ *   implementation). Astral-plane characters count as two units, exactly as
+ *   they did before.
+ * - Allowed characters: output is restricted to `[A-Za-z0-9]` (62 chars).
+ * - Explicit `replacement` values in secrets.yml are authoritative and are
+ *   never derived; this path runs only when `replacement` is undefined.
+ * - Replace mode stays one-way: the derived value is never reversed by
+ *   `deobfuscate()`.
+ *
+ * THREAT MODEL (issue #4166):
+ * - Attacker model: an observer sees one or more replacements (model context,
+ *   provider-side logs, saved/shared transcripts) and has full knowledge of
+ *   the public algorithm. Without the 32-byte obfuscation key they cannot
+ *   confirm a candidate secret offline and cannot predict or precompute the
+ *   replacement for any secret. The construction is a keyed PRF
+ *   (HMAC-SHA256), so output is unpredictable without the key, and keyed
+ *   domain separation keeps this construction distinct from the placeholder
+ *   construction.
+ * - Accepted residual disclosure: the replacement is same-length by design
+ *   (required behavior above), so the secret's exact length is still
+ *   observable. This is inherent to size-preserving substitution and is
+ *   explicitly out of scope; the fix removes the *keyless confirmation*
+ *   oracle, not the length signal.
+ * - Cross-process stability / key rotation: the process key is generated per
+ *   process (`PROCESS_SECRET_OBFUSCATION_KEY`), so derived replacements are
+ *   stable within a process and differ across processes or after a key
+ *   rotation. This is a deliberate decision, identical in scope to the
+ *   obfuscate-mode placeholder behavior. Users who need stable values across
+ *   processes or restarts must set an explicit `replacement` in secrets.yml.
+ * - Collision/bias: output is a keyed pseudorandom mapping. Two distinct
+ *   secrets can in principle collide (birthday bound over the 62^len output
+ *   space); for realistic secret lengths this is negligible. Character
+ *   distribution is uniform by construction: digest bytes are rejection-
+ *   sampled (bytes 248-255 rejected, 256 - (256 % 62) = 248 = 62 * 4), so
+ *   every character is exactly equally likely, with no modulo bias.
+ * - Empty secrets: a zero-length secret yields an empty replacement and the
+ *   obfuscator treats it as a no-op (load-time validation rejects empty
+ *   content anyway). Unicode secrets are hashed as UTF-8 bytes, so encoding
+ *   is canonical. Very long secrets expand via a counter-based HMAC stream
+ *   in O(length) blocks; generation cost is linear in the secret length.
+ * - Overlapping secrets and streaming: derivation is per-secret and does not
+ *   depend on matching semantics (longest-first overlap handling is
+ *   unchanged), and `obfuscate()` runs per complete text payload, so chunked
+ *   output (e.g. streamed LLM messages) sees the same deterministic
+ *   replacement for the same secret within a process.
+ */
+function generateDeterministicReplacement(secret: string, key: Uint8Array): string {
+	const length = secret.length;
+	if (length === 0) return "";
 	const chars: string[] = [];
-	let h = hash;
-	for (let i = 0; i < secret.length; i++) {
-		// Mix the hash for each character position
-		h = h ^ (BigInt(i + 1) * 0x9e3779b97f4a7c15n);
-		const idx = Number((h < 0n ? -h : h) % BigInt(REPLACEMENT_CHARS.length));
-		chars.push(REPLACEMENT_CHARS[idx]);
+	// CTR-style expansion: HMAC(key, DOMAIN || counter || secret) per 32-byte
+	// block. The counter is big-endian and fixed-width, so the stream is
+	// unambiguous and never repeats.
+	const counter = new Uint8Array(8);
+	const counterView = new DataView(counter.buffer);
+	let block: Uint8Array | undefined;
+	let blockOffset = REPLACEMENT_DIGEST_BYTES;
+	let blockIndex = 0;
+	while (chars.length < length) {
+		if (block === undefined || blockOffset >= REPLACEMENT_DIGEST_BYTES) {
+			counterView.setUint32(4, blockIndex, false);
+			block = createHmac("sha256", key).update(REPLACEMENT_DOMAIN).update(counter).update(secret, "utf8").digest();
+			blockOffset = 0;
+			blockIndex++;
+		}
+		const byte = block[blockOffset++]!;
+		if (byte >= REPLACEMENT_REJECT_THRESHOLD) continue;
+		chars.push(REPLACEMENT_CHARS[byte % REPLACEMENT_CHARS.length]!);
 	}
 	return chars.join("");
 }
@@ -115,7 +193,8 @@ export class SecretObfuscator {
 					index++;
 				} else {
 					// replace mode
-					const replacement = entry.replacement ?? generateDeterministicReplacement(entry.content);
+					const replacement =
+						entry.replacement ?? generateDeterministicReplacement(entry.content, this.#placeholderKey);
 					this.#replaceMappings.set(entry.content, replacement);
 				}
 			} else {
@@ -168,7 +247,8 @@ export class SecretObfuscator {
 
 			for (const matchValue of matches) {
 				if (entry.mode === "replace") {
-					const replacement = entry.replacement ?? generateDeterministicReplacement(matchValue);
+					const replacement =
+						entry.replacement ?? generateDeterministicReplacement(matchValue, this.#placeholderKey);
 					result = replaceAll(result, matchValue, replacement);
 				} else {
 					// obfuscate mode — get or create stable index