@bitkyc08/opencodex 2.77.0 → 2.78.0

package/src/cli/access-audio-input.ts

@@ -0,0 +1,84 @@
+/** Bounded local audio input; never reads stdin, devices, or a caller's whole file unchecked. */
+import { constants } from "node:fs";
+import { open, stat, type FileHandle } from "node:fs/promises";
+import { CliUsageError, readSecretBytes } from "./runtime-api";
+
+export const AUDIO_FILE_MAX_BYTES = 25_000_000;
+export const AUDIO_BODY_MAX_BYTES = 32 * 1024 * 1024;
+const FILE_TIMEOUT_MS = 30_000;
+
+export interface AudioInputDeps {
+  audioFileTimeoutMs?: number;
+  audioOpen?: typeof open;
+  audioStat?: typeof stat;
+}
+
+export function audioTimeout(value: number | undefined, maximum: number): number {
+  if (value === undefined) return maximum;
+  if (!Number.isFinite(value) || value <= 0 || value > maximum) throw new CliUsageError("Invalid audio deadline");
+  return value;
+}
+
+async function withinInputDeadline<T>(operation: Promise<T>, signal: AbortSignal, late?: (value: T) => Promise<void>): Promise<T> {
+  let stopped = signal.aborted;
+  let abort = () => {};
+  const cancellation = new Promise<never>((_, reject) => {
+    abort = () => { stopped = true; reject(new Error("Audio input canceled")); };
+    signal.addEventListener("abort", abort, { once: true });
+    if (signal.aborted) abort();
+  });
+  try {
+    return await Promise.race([operation.then(async value => {
+      if (stopped) {
+        await late?.(value);
+        throw new Error("Audio input canceled");
+      }
+      return value;
+    }), cancellation]);
+  } finally { signal.removeEventListener("abort", abort); }
+}
+
+export async function readAudioFile(path: string, signal: AbortSignal, deps: AudioInputDeps = {}): Promise<File> {
+  const timeoutMs = audioTimeout(deps.audioFileTimeoutMs, FILE_TIMEOUT_MS);
+  signal.throwIfAborted();
+  const deadline = new AbortController();
+  const abort = () => deadline.abort();
+  signal.addEventListener("abort", abort, { once: true });
+  const timer = setTimeout(abort, timeoutMs);
+  let handle: FileHandle | undefined;
+  let stream: ReturnType<FileHandle["createReadStream"]> | undefined;
+  let bytes: Uint8Array<ArrayBuffer> | undefined;
+  const validate = (value: Awaited<ReturnType<FileHandle["stat"]>>) => {
+    if (!value.isFile() || value.size === 0 || value.size > AUDIO_FILE_MAX_BYTES) {
+      throw new CliUsageError("Audio input must be a nonempty regular file no larger than 25,000,000 bytes");
+    }
+  };
+  try {
+    validate(await withinInputDeadline((deps.audioStat ?? stat)(path), deadline.signal));
+    handle = await withinInputDeadline(
+      (deps.audioOpen ?? open)(path, constants.O_RDONLY | constants.O_NONBLOCK), deadline.signal, file => file.close(),
+    );
+    validate(await withinInputDeadline(handle.stat(), deadline.signal));
+    deadline.signal.throwIfAborted();
+    stream = handle.createReadStream({ autoClose: false });
+    // Teardown can emit a pending I/O error after the bounded reader detaches.
+    const ignoreTeardownError = () => {};
+    stream.on("error", ignoreTeardownError);
+    stream.once("close", () => stream?.removeListener("error", ignoreTeardownError));
+    bytes = await readSecretBytes({ stdinImpl: stream, stdinTimeoutMs: timeoutMs, stdinSignal: deadline.signal }, "Audio file", AUDIO_FILE_MAX_BYTES);
+    deadline.signal.throwIfAborted();
+    // Never disclose the user's basename in the multipart body; retain only a bounded format suffix.
+    const suffix = /\.[a-z0-9]{1,8}$/i.exec(path)?.[0] ?? ".webm";
+    return new File([bytes], `audio${suffix}`, { type: "application/octet-stream" });
+  } catch (error) {
+    if (deadline.signal.aborted) throw new Error("Audio input deadline or cancellation");
+    if (error instanceof CliUsageError) throw new CliUsageError("Audio input must be a nonempty regular file no larger than 25,000,000 bytes");
+    throw new Error("Unable to read audio input");
+  } finally {
+    clearTimeout(timer);
+    signal.removeEventListener("abort", abort);
+    stream?.destroy();
+    bytes?.fill(0);
+    await handle?.close();
+  }
+}

package/src/cli/access-audio-live.ts

@@ -0,0 +1,99 @@
+/** One readiness observation over the existing audio key subprotocol, with bounded local teardown. */
+import { audioTimeout } from "./access-audio-input";
+
+const READY_TIMEOUT_MS = 15_000;
+const CLOSE_TIMEOUT_MS = 2_000;
+const FRAME_MAX_BYTES = 64 * 1024;
+const SESSION_MAX_BYTES = 2 * 1024 * 1024;
+const SESSION_UPDATE = {
+  type: "session.update",
+  session: { instructions: "", audio: { output: { voice: "cove" } }, delegation: { type: "client" } },
+};
+export type AudioClientSocket = WebSocket & { terminate(): void };
+export interface AudioLiveDeps {
+  audioReadyTimeoutMs?: number;
+  audioCloseTimeoutMs?: number;
+  audioSocket?: (url: string, protocols: string[]) => AudioClientSocket;
+}
+export interface AudioLiveReport {
+  schemaVersion: 1;
+  ready: boolean;
+  close: "confirmed" | "unverified";
+  check: "session-readiness";
+  event?: "session.started" | "session.updated";
+}
+
+export async function checkAudioLive(origin: string, model: string, key: string, signal: AbortSignal, deps: AudioLiveDeps = {}): Promise<{ report: AudioLiveReport; ok: boolean }> {
+  const readyMs = audioTimeout(deps.audioReadyTimeoutMs, READY_TIMEOUT_MS);
+  const closeMs = audioTimeout(deps.audioCloseTimeoutMs, CLOSE_TIMEOUT_MS);
+  signal.throwIfAborted();
+  const url = new URL("/v1/live", origin);
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  url.searchParams.set("model", model);
+  const protocols = ["opencodex-audio", `opencodex-key.${Buffer.from(key, "utf8").toString("base64url")}`];
+  const report: AudioLiveReport = { schemaVersion: 1, ready: false, close: "unverified", check: "session-readiness" };
+  const started = performance.now();
+  // Native Bun rejects handshake redirects. Real two-endpoint regressions cover HTTP and WS Location forms.
+  // The CLI runs on Bun; its native WebSocket adds terminate beyond the DOM type.
+  const socket = (deps.audioSocket ?? ((address, carrier) => new WebSocket(address, carrier) as AudioClientSocket))(url.href, protocols);
+  return await new Promise(resolve => {
+    let finished = false;
+    let closing = false;
+    let failed = false;
+    let total = 0;
+    let closeTimer: ReturnType<typeof setTimeout> | undefined;
+    const finish = (confirmed: boolean) => {
+      if (finished) return;
+      finished = true;
+      report.close = confirmed ? "confirmed" : "unverified";
+      clearTimeout(readyTimer);
+      clearTimeout(closeTimer);
+      signal.removeEventListener("abort", onAbort);
+      socket.onopen = socket.onmessage = socket.onerror = socket.onclose = null;
+      if (socket.readyState !== WebSocket.CLOSED) socket.terminate();
+      resolve({ report, ok: !failed && report.ready && confirmed });
+    };
+    const close = () => {
+      if (closing || finished) return;
+      closing = true;
+      clearTimeout(readyTimer);
+      closeTimer = setTimeout(() => finish(false), closeMs);
+      try {
+        if (socket.readyState === WebSocket.OPEN) socket.send('{"type":"session.close"}');
+        socket.close(1000);
+      } catch { failed = true; finish(false); }
+    };
+    const fail = () => { failed = true; close(); };
+    const onAbort = () => { failed = true; finish(false); };
+    const readyTimer = setTimeout(fail, Math.max(0, readyMs - (performance.now() - started)));
+    socket.onopen = () => {
+      if (closing || finished) return;
+      try { socket.send(JSON.stringify(SESSION_UPDATE)); }
+      catch { fail(); }
+    };
+    socket.onmessage = event => {
+      if (finished) return;
+      if (typeof event.data !== "string") { fail(); return; }
+      const size = Buffer.byteLength(event.data, "utf8");
+      total += size;
+      if (size > FRAME_MAX_BYTES || total > SESSION_MAX_BYTES) { fail(); return; }
+      let message: unknown;
+      try { message = JSON.parse(event.data); } catch { fail(); return; }
+      if (!message || typeof message !== "object" || Array.isArray(message) || !("type" in message) || typeof message.type !== "string") { fail(); return; }
+      if (message.type === "error" || message.type === "protocol.error") { fail(); return; }
+      if (message.type !== "session.started" && message.type !== "session.updated") return;
+      const session = "session" in message ? message.session : undefined;
+      if (!session || typeof session !== "object" || Array.isArray(session)) return;
+      if ("status" in session && (session.status === "error" || session.status === "failed" || (!report.ready && session.status === "closed"))) { fail(); return; }
+      if (!closing && "id" in session && typeof session.id === "string" && session.id.trim()) {
+        report.ready = true;
+        report.event = message.type;
+        close();
+      }
+    };
+    socket.onerror = fail;
+    socket.onclose = event => finish(event.code === 1000);
+    signal.addEventListener("abort", onAbort, { once: true });
+    if (signal.aborted) onAbort();
+  });
+}

package/src/cli/access-audio.ts

@@ -0,0 +1,123 @@
+/** Explicit-key audio consumers. No management headers, model controls, or credential fallback. */
+import { signalWithTimeout } from "../lib/abort";
+import { CliUsageError, printData, takeFlag, takeOptionWithSyntax } from "./runtime-api";
+import {
+  readBoundedDataJson, redactSelectedKey, withDataCommandSignals, withSelectedDataKey,
+  type DataClientDeps, type SelectedDataTarget,
+} from "./access-data-client";
+import { AUDIO_BODY_MAX_BYTES, readAudioFile, audioTimeout, type AudioInputDeps } from "./access-audio-input";
+import { checkAudioLive, type AudioLiveDeps, type AudioLiveReport } from "./access-audio-live";
+
+const HTTP_TIMEOUT_MS = 130_000;
+const RESPONSE_MAX_BYTES = 2 * 1024 * 1024;
+const MODEL_MAX_BYTES = 16 * 1024;
+const TRANSCRIPTION_MODELS = new Set(["gpt-4o-transcribe", "gpt-4o-mini-transcribe", "whisper-1"]);
+const USAGE = "Usage: ocx access audio transcribe FILE --model ID --api-key-stdin [--json]\n       ocx access audio live-check --model ID --api-key-stdin [--json]";
+export interface AccessAudioDeps extends DataClientDeps, AudioInputDeps, AudioLiveDeps {
+  audioHttpTimeoutMs?: number;
+}
+interface AudioArgs { action: "transcribe" | "live-check"; model: string; json: boolean; file?: string }
+
+function parseArgs(argv: string[]): AudioArgs {
+  const args = [...argv];
+  const action = args.shift();
+  const json = takeFlag(args, "--json");
+  const stdin = takeFlag(args, "--api-key-stdin");
+  const model = takeOptionWithSyntax(args, "--model")?.value;
+  if (!stdin || !model || model.trim() !== model || !model.trim() || Buffer.byteLength(model) > MODEL_MAX_BYTES
+    || /[\x00-\x1f\x7f-\x9f]/.test(model)) throw new CliUsageError("Invalid audio arguments");
+  if (action === "transcribe" && TRANSCRIPTION_MODELS.has(model) && args.length === 1 && args[0] && !args[0].startsWith("-")) {
+    return { action, model, json, file: args[0] };
+  }
+  if (action === "live-check" && args.length === 0) return { action, model, json };
+  throw new CliUsageError("Invalid audio arguments");
+}
+
+async function transcribe(file: File, model: string, context: { target: SelectedDataTarget; key: string }, signal: AbortSignal, deps: AccessAudioDeps): Promise<{ text: string }> {
+  // Each bounded ASCII multipart header/boundary plus the fixed field names fits
+  // in 4 KiB. File/model/filename are independently bounded before serialization.
+  if (file.size + Buffer.byteLength(model) + Buffer.byteLength(file.name) + 4096 > AUDIO_BODY_MAX_BYTES) throw new Error("Audio multipart limit");
+  const form = new FormData();
+  form.set("file", file);
+  form.set("model", model);
+  form.set("response_format", "json");
+  await context.target.assertCurrent();
+  signal.throwIfAborted();
+  const deadline = signalWithTimeout(audioTimeout(deps.audioHttpTimeoutMs, HTTP_TIMEOUT_MS), signal);
+  let response: Response | undefined;
+  try {
+    response = await (deps.fetchImpl ?? fetch)(new URL("/v1/audio/transcriptions", context.target.origin), {
+      method: "POST", body: form, headers: { "x-opencodex-api-key": context.key },
+      credentials: "omit", redirect: "error", signal: deadline.signal,
+    });
+    deadline.signal.throwIfAborted();
+    if (!response.ok) throw new Error("Audio request refused");
+    const result = await readBoundedDataJson(response, { maxBytes: RESPONSE_MAX_BYTES, signal: deadline.signal });
+    deadline.signal.throwIfAborted();
+    if (!result || typeof result !== "object" || Array.isArray(result) || !("text" in result) || typeof result.text !== "string") throw new Error("Unsupported audio response");
+    await context.target.assertCurrent();
+    deadline.signal.throwIfAborted();
+    return { text: redactSelectedKey(result.text, context.key) };
+  } finally {
+    // Cancellation itself may never settle; it must not retain the key or deadline.
+    try {
+      if (response?.body && !response.body.locked) void response.body.cancel().catch(() => {});
+    } catch { /* best-effort body teardown must preserve the original outcome */ }
+    finally { deadline.cleanup(); }
+  }
+}
+
+function showLive(report: AudioLiveReport, json: boolean): void {
+  printData(report, json, [
+    report.ready ? "Session readiness observed." : "Session readiness was not observed.",
+    report.close === "confirmed" ? "Normal socket closure confirmed." : "Socket closure is unverified.",
+    "This checks session readiness only; it does not test a voice roundtrip.",
+  ]);
+}
+
+export async function handleAccessAudioCommand(argv: string[], deps: AccessAudioDeps = {}): Promise<number> {
+  let options: AudioArgs;
+  try {
+    options = parseArgs(argv);
+    audioTimeout(deps.audioFileTimeoutMs, 30_000);
+    audioTimeout(deps.audioHttpTimeoutMs, HTTP_TIMEOUT_MS);
+    audioTimeout(deps.audioReadyTimeoutMs, 15_000);
+    audioTimeout(deps.audioCloseTimeoutMs, 2_000);
+  } catch {
+    console.error("Invalid audio arguments. Use a supported model and pipe the selected key on stdin.");
+    console.error(USAGE);
+    return 2;
+  }
+  return await withDataCommandSignals(deps, async signal => {
+    let liveReport: AudioLiveReport = { schemaVersion: 1, ready: false, close: "unverified", check: "session-readiness" };
+    try {
+      const file = options.action === "transcribe" ? await readAudioFile(options.file!, signal, deps) : undefined;
+      return await withSelectedDataKey(deps, signal, async context => {
+        if (file) {
+          const result = await transcribe(file, options.model, context, signal, deps);
+          signal.throwIfAborted();
+          printData(result, options.json, [result.text]);
+          return 0;
+        }
+        await context.target.assertCurrent();
+        signal.throwIfAborted();
+        const result = await checkAudioLive(context.target.origin, options.model, context.key, signal, deps);
+        liveReport = result.report;
+        await context.target.assertCurrent();
+        signal.throwIfAborted();
+        showLive(liveReport, options.json);
+        if (!result.ok) console.error("Audio readiness or normal closure could not be confirmed. Check the selected target and audio model before retrying.");
+        return result.ok ? 0 : 1;
+      });
+    } catch (error) {
+      if (signal.aborted) throw error;
+      if (error instanceof CliUsageError) {
+        console.error("Invalid audio file or key input. Use a nonempty regular audio file and pipe a printable ASCII key without extra lines.");
+        return 2;
+      }
+      if (options.action === "live-check") showLive(liveReport, options.json);
+      console.error("Audio operation failed. Check the selected target, key, model, file limits and connection before retrying.");
+      return 1;
+    }
+  });
+}

package/src/cli/access-data-client.ts

@@ -0,0 +1,127 @@
+/** Explicit data credentials never use management headers or the enrolled secret. */
+import { readClientConnectionState, assertClientConnectionUnchanged } from "../client/state";
+import { normalizeHubOrigin } from "../client/hub-client";
+import { findLiveProxy, probeHostname, type LiveProxy } from "../server/proxy-liveness";
+import { readBoundedResponseBytes } from "../lib/bounded-body";
+import { CliUsageError, readSecretBytes, type RuntimeApiDeps } from "./runtime-api";
+
+export interface SelectedDataTarget {
+  origin: string;
+  assertCurrent(): Promise<void>;
+}
+export interface DataClientDeps extends RuntimeApiDeps {
+  signal?: AbortSignal;
+  readClientConnectionState?: typeof readClientConnectionState;
+  assertClientConnectionUnchanged?: typeof assertClientConnectionUnchanged;
+}
+
+async function selectTarget(deps: DataClientDeps, signal: AbortSignal): Promise<SelectedDataTarget> {
+  signal.throwIfAborted();
+  const readState = deps.readClientConnectionState ?? readClientConnectionState;
+  const state = readState();
+  if (state.kind === "connected") {
+    const expected = structuredClone(state.value);
+    const origin = normalizeHubOrigin(expected.serverUrl);
+    const check = deps.assertClientConnectionUnchanged ?? assertClientConnectionUnchanged;
+    const assertCurrent = async () => { signal.throwIfAborted(); check(expected); };
+    await assertCurrent();
+    return { origin, assertCurrent };
+  }
+  if (state.kind !== "disconnected") throw new Error("Selected target is unavailable.");
+  const discover = deps.findLiveProxy ?? findLiveProxy;
+  const live = await discover();
+  signal.throwIfAborted();
+  if (!live || live.role === "client") throw new Error("Selected target is unavailable.");
+  const originOf = (value: LiveProxy) => normalizeHubOrigin(`http://${probeHostname(value.hostname)}:${value.port}`);
+  const origin = originOf(live);
+  const assertCurrent = async () => {
+    signal.throwIfAborted();
+    if (readState().kind !== "disconnected") throw new Error("Selected target changed.");
+    const current = await discover();
+    signal.throwIfAborted();
+    if (!current || current.pid !== live.pid || current.port !== live.port || current.role !== live.role
+      || originOf(current) !== origin || readState().kind !== "disconnected") {
+      throw new Error("Selected target changed.");
+    }
+  };
+  await assertCurrent();
+  return { origin, assertCurrent };
+}
+
+export async function withSelectedDataKey<T>(
+  deps: DataClientDeps,
+  signal: AbortSignal,
+  operation: (context: { target: SelectedDataTarget; key: string }) => Promise<T>,
+): Promise<T> {
+  let bytes: Uint8Array | undefined;
+  const input = deps.stdinImpl ?? process.stdin;
+  try {
+    const target = await selectTarget(deps, signal);
+    if (input.isTTY) throw new CliUsageError("Pipe the selected API key through stdin.");
+    const timeout = deps.stdinTimeoutMs ?? 30_000;
+    if (!Number.isFinite(timeout) || timeout <= 0 || timeout > 30_000) throw new Error("Invalid input deadline.");
+    try {
+      bytes = await readSecretBytes({ ...deps, stdinTimeoutMs: timeout, stdinSignal: signal }, "API key", 4096);
+    } catch (error) {
+      if (error instanceof CliUsageError && error.message.startsWith("timed out")) {
+        throw new Error("API key input timed out.");
+      }
+      throw error;
+    }
+    let key: string;
+    try { key = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes); }
+    catch { throw new CliUsageError("API key input must be valid UTF-8."); }
+    key = key.replace(/\r?\n$/, "");
+    if (!key || key.trim() !== key || !/^[\x20-\x7e]+$/.test(key)) {
+      throw new CliUsageError("API key must contain printable ASCII without outer whitespace or extra lines.");
+    }
+    await target.assertCurrent();
+    signal.throwIfAborted();
+    return await operation({ target, key });
+  } finally {
+    bytes?.fill(0);
+    input.pause();
+  }
+}
+
+export async function readBoundedDataJson(
+  response: Response,
+  options: { maxBytes: number; signal: AbortSignal },
+): Promise<unknown> {
+  const result = await readBoundedResponseBytes(response, options);
+  try {
+    if (result.oversized) throw new Error("Response exceeded its limit.");
+    return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(result.bytes));
+  } finally { result.bytes.fill(0); }
+}
+
+export function redactSelectedKey(text: string, key: string): string {
+  return key ? text.split(key).join("[redacted]") : text;
+}
+
+/** One command owns signals; consumers check abortion before every output/effect. */
+export async function withDataCommandSignals(
+  deps: DataClientDeps,
+  run: (signal: AbortSignal) => Promise<number>,
+): Promise<number> {
+  const controller = new AbortController();
+  let exit = 130;
+  const interrupt = () => { if (!controller.signal.aborted) { exit = 130; controller.abort(); } };
+  const terminate = () => { if (!controller.signal.aborted) { exit = 143; controller.abort(); } };
+  process.on("SIGINT", interrupt);
+  process.on("SIGTERM", terminate);
+  deps.signal?.addEventListener("abort", interrupt, { once: true });
+  if (deps.signal?.aborted) interrupt();
+  try {
+    controller.signal.throwIfAborted();
+    const result = await run(controller.signal);
+    return controller.signal.aborted ? exit : result;
+  } catch (error) {
+    if (controller.signal.aborted) return exit;
+    throw error;
+  } finally {
+    process.removeListener("SIGINT", interrupt);
+    process.removeListener("SIGTERM", terminate);
+    deps.signal?.removeEventListener("abort", interrupt);
+  }
+}

package/src/cli/access-data-plane.ts

@@ -0,0 +1,104 @@
+import { signalWithTimeout } from "../lib/abort";
+import { CliUsageError, printData, takeFlag, takeOptionWithSyntax } from "./runtime-api";
+import { withSelectedDataKey, withDataCommandSignals, readBoundedDataJson, type DataClientDeps, type SelectedDataTarget } from "./access-data-client";
+import { projectModelResponse, type DataProtocol, type SafeModelResponse } from "./access-data-response";
+
+export interface SelectedKeyTestDeps extends DataClientDeps {
+  controlTimeoutMs?: number;
+  requestTimeoutMs?: number;
+}
+interface ProbeReport {
+  schemaVersion: 1;
+  control: { outcome: "not_run" | "credential_required" | "unavailable"; status?: number };
+  request: { outcome: "not_run" | "succeeded" | "failed" | "unsupported_response"; status?: number };
+  response?: SafeModelResponse;
+}
+const USAGE = "Usage: ocx access test <model> [--protocol chat|responses|messages] --api-key-stdin [--json]";
+function parse(argv: string[]) {
+  const args = [...argv];
+  try {
+    const json = takeFlag(args, "--json");
+    const stdin = takeFlag(args, "--api-key-stdin");
+    const protocol = takeOptionWithSyntax(args, "--protocol")?.value ?? "chat";
+    const model = args.shift();
+    if (!stdin || args.length || !model || model.startsWith("-") || model.trim() !== model
+      || model.length > 16_384 || /[\x00-\x1f\x7f]/.test(model)
+      || (protocol !== "chat" && protocol !== "responses" && protocol !== "messages")) throw new Error();
+    return { json, model, protocol } as { json: boolean; model: string; protocol: DataProtocol };
+  } catch { throw new CliUsageError("Invalid selected-key test arguments.", USAGE); }
+}
+function nativeRefusal(raw: unknown, protocol: DataProtocol): boolean {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return false;
+  const top = raw as Record<string, unknown>;
+  if (!top.error || typeof top.error !== "object" || Array.isArray(top.error)) return false;
+  const error = top.error as Record<string, unknown>;
+  if (error.message !== "opencodex API key required" || error.type !== "authentication_error") return false;
+  return (top.type === undefined && error.code === "invalid_api_key")
+    || (protocol === "messages" && top.type === "error" && error.code === undefined);
+}
+function timeout(value: number | undefined, ceiling: number): number {
+  if (value === undefined) return ceiling;
+  if (!Number.isFinite(value) || value <= 0 || value > ceiling) throw new Error("Invalid request deadline.");
+  return value;
+}
+async function requestJson(
+  target: SelectedDataTarget, path: string, body: string, key: string | undefined,
+  deps: SelectedKeyTestDeps, signal: AbortSignal, report: { status?: number },
+): Promise<unknown> {
+  await target.assertCurrent();
+  signal.throwIfAborted();
+  const deadline = signalWithTimeout(timeout(key === undefined ? deps.controlTimeoutMs : deps.requestTimeoutMs, key === undefined ? 5000 : 60_000), signal);
+  try {
+    const headers = new Headers({ "content-type": "application/json", accept: "application/json" });
+    if (key !== undefined) headers.set("x-opencodex-api-key", key);
+    const response = await (deps.fetchImpl ?? fetch)(`${target.origin}${path}`, {
+      method: "POST", body, headers, credentials: "omit", redirect: "error", signal: deadline.signal,
+    });
+    report.status = response.status;
+    const result = await readBoundedDataJson(response, { maxBytes: key === undefined ? 4096 : 2 * 1024 * 1024, signal: deadline.signal });
+    deadline.signal.throwIfAborted();
+    await target.assertCurrent();
+    signal.throwIfAborted();
+    return result;
+  } finally { deadline.cleanup(); }
+}
+export async function handleSelectedKeyTest(argv: string[], deps: SelectedKeyTestDeps = {}): Promise<number> {
+  let options: ReturnType<typeof parse>;
+  try { options = parse(argv); }
+  catch { console.error(`Error: Invalid selected-key test arguments.\n${USAGE}`); return 2; }
+  const report: ProbeReport = { schemaVersion: 1, control: { outcome: "not_run" }, request: { outcome: "not_run" } };
+  return withDataCommandSignals(deps, async signal => {
+    try {
+      await withSelectedDataKey(deps, signal, async ({ target, key }) => {
+        const path = options.protocol === "responses" ? "/v1/responses" : options.protocol === "chat" ? "/v1/chat/completions" : "/v1/messages";
+        report.control.outcome = "unavailable";
+        const control = await requestJson(target, path, "{", undefined, deps, signal, report.control);
+        if (report.control.status !== 401 || !nativeRefusal(control, options.protocol)) throw new Error();
+        report.control.outcome = "credential_required";
+        const body = options.protocol === "responses"
+          ? { model: options.model, input: "Reply with OK.", max_output_tokens: 16 }
+          : { model: options.model, messages: [{ role: "user", content: "Reply with OK." }], max_tokens: 16,
+            ...(options.protocol === "chat" ? { stream: false } : {}) };
+        report.request.outcome = "failed";
+        const raw = await requestJson(target, path, JSON.stringify(body), key, deps, signal, report.request);
+        if (!report.request.status || report.request.status < 200 || report.request.status >= 300) throw new Error();
+        report.request.outcome = "unsupported_response";
+        report.response = projectModelResponse(raw, options.protocol, key);
+        report.request.outcome = "succeeded";
+      });
+      signal.throwIfAborted();
+      printData(report, options.json, [
+        "Credentialless request was refused; the model request using the supplied key succeeded.",
+        ...(report.response?.completion === "limited" ? ["Completion was limited by the model response."] : []),
+        ...report.response!.text,
+      ]);
+      return 0;
+    } catch (error) {
+      if (signal.aborted) throw error;
+      if (error instanceof CliUsageError) { console.error("Error: Invalid API key input. Pipe one printable ASCII key through stdin."); return 2; }
+      if (options.json) printData(report, true);
+      console.error("Error: Selected-key test did not complete. Check the target, key and supported protocol before retrying.");
+      return 1;
+    }
+  });
+}

package/src/cli/access-data-response.ts

@@ -0,0 +1,76 @@
+/** Whitelist native text completions; never serialize arbitrary provider payloads. */
+import { redactSelectedKey } from "./access-data-client";
+export type DataProtocol = "chat" | "responses" | "messages";
+export interface SafeModelResponse {
+  protocol: DataProtocol;
+  text: string[];
+  completion: "complete" | "limited";
+  usage?: { inputTokens?: number; outputTokens?: number; totalTokens?: number };
+}
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+function usageOf(raw: unknown, protocol: DataProtocol): SafeModelResponse["usage"] {
+  if (raw === undefined || raw === null) return undefined;
+  const usage = record(raw);
+  if (!usage) throw new Error("Invalid usage.");
+  const result: NonNullable<SafeModelResponse["usage"]> = {};
+  const fields = protocol === "chat"
+    ? { inputTokens: "prompt_tokens", outputTokens: "completion_tokens", totalTokens: "total_tokens" } as const
+    : { inputTokens: "input_tokens", outputTokens: "output_tokens", totalTokens: "total_tokens" } as const;
+  for (const name of ["inputTokens", "outputTokens", "totalTokens"] as const) {
+    const value = usage[fields[name]];
+    if (value === undefined) continue;
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new Error("Invalid usage.");
+    result[name] = value;
+  }
+  return Object.keys(result).length ? result : undefined;
+}
+export function projectModelResponse(raw: unknown, protocol: DataProtocol, key: string): SafeModelResponse {
+  const row = record(raw);
+  if (!row || (row.error !== undefined && row.error !== null)) throw new Error("Unsupported response.");
+  const text: string[] = [];
+  let limited = false;
+  if (protocol === "responses") {
+    if (row.object !== "response" || (row.status !== "completed" && row.status !== "incomplete") || !Array.isArray(row.output)) throw new Error("Unsupported response.");
+    if (record(row.incomplete_details)?.reason === "content_filter") throw new Error("Unsupported response.");
+    limited = row.status === "incomplete";
+    for (const value of row.output) {
+      const item = record(value);
+      if (!item || item.type !== "message" || item.role !== "assistant" || !Array.isArray(item.content)) {
+        // Reasoning/tool entries are not text evidence and are never exposed.
+        continue;
+      }
+      for (const blockValue of item.content) {
+        const block = record(blockValue);
+        if (block?.type !== "output_text" || typeof block.text !== "string") throw new Error("Unsupported response.");
+        text.push(block.text);
+      }
+    }
+  } else if (protocol === "chat") {
+    if (row.object !== "chat.completion" || !Array.isArray(row.choices) || row.choices.length === 0) throw new Error("Unsupported response.");
+    for (const value of row.choices) {
+      const choice = record(value);
+      const message = record(choice?.message);
+      if (!choice || (choice.finish_reason !== "stop" && choice.finish_reason !== "length")
+        || !message || message.role !== "assistant" || typeof message.content !== "string"
+        || (message.refusal !== undefined && message.refusal !== null)) throw new Error("Unsupported response.");
+      limited ||= choice.finish_reason === "length";
+      text.push(message.content);
+    }
+  } else {
+    if (row.type !== "message" || row.role !== "assistant" || !Array.isArray(row.content)
+      || (row.stop_reason !== "end_turn" && row.stop_reason !== "stop_sequence" && row.stop_reason !== "max_tokens")) {
+      throw new Error("Unsupported response.");
+    }
+    limited = row.stop_reason === "max_tokens";
+    for (const value of row.content) {
+      const block = record(value);
+      if (block?.type === "text" && typeof block.text === "string") text.push(block.text);
+      else if (block?.type !== "thinking" && block?.type !== "redacted_thinking") throw new Error("Unsupported response.");
+    }
+  }
+  if (!text.length) throw new Error("Unsupported response.");
+  const usage = usageOf(row.usage, protocol);
+  return { protocol, text: text.map(value => redactSelectedKey(value, key)), completion: limited ? "limited" : "complete", ...(usage ? { usage } : {}) };
+}