@quantiya/codevibe-core 2.0.0 → 2.0.2

package/dist/credential-broker/broker.d.ts

@@ -0,0 +1,165 @@
+import { type StrictAuditSink } from "./audit-sink";
+import { getProviderConfig } from "./broker-config";
+import { type RotationHandle } from "./broker-token";
+import { type BrokerRequest, type BrokerResponse, type BrokerToken, type ModelGatewayBroker, type UpstreamClient, type VendorKeyStore, type VendorProvider } from "./types";
+/**
+ * Construction-time dependencies. All injectable so W1 unit-tests run
+ * against stubs (no network, deterministic audit ACKs). Defaults wire the
+ * real keychain store + a deterministic stub audit sink (the real strict
+ * sink is W3). `upstreamClient` has NO default — a network client is out
+ * of W1 scope, so the broker MUST be given one (tests pass a stub).
+ */
+export interface BrokerDeps {
+    /** Orchestration task_id = the audit scope (§3.5), passed at session start. */
+    taskId: string;
+    /** Injected upstream HTTP client (no real network in W1). */
+    upstreamClient: UpstreamClient;
+    /** Vendor-key store (defaults to the keychain-backed store, §3.3). */
+    vendorKeyStore?: VendorKeyStore;
+    /** Strict audit sink (defaults to the in-memory stub until W3, §3.5). */
+    auditSink?: StrictAuditSink;
+}
+/**
+ * The local model-gateway broker (§3.2). One per session on
+ * `127.0.0.1:<ephemeral>`. Holds the upstream credential in-process only
+ * (zeroized on `stop()`), authenticates the agent's broker token, builds
+ * a canonical upstream request, scrubs secrets (I2), enforces audit-
+ * before-effect via the injected `StrictAuditSink`, and forwards.
+ */
+export declare class LocalModelGatewayBroker implements ModelGatewayBroker, VendorKeyStore {
+    private readonly taskId;
+    private readonly upstreamClient;
+    private readonly vendorKeyStore;
+    private readonly auditSink;
+    private readonly tokenMinter;
+    private readonly brokerId;
+    private server;
+    private boundAddr;
+    /** In-process cache of upstream vendor keys (zeroized on stop()). */
+    private upstreamKeys;
+    /** Latest `credential_issuance_id` per provider (for the model_call FK). */
+    private issuanceIds;
+    private issuanceCounter;
+    constructor(deps: BrokerDeps);
+    /**
+     * Start the per-session HTTP gateway on an ephemeral loopback port + mint
+     * the session's broker token. Resolves the bound `127.0.0.1:<port>`.
+     */
+    start(): Promise<{
+        hostBrokerAddr: string;
+    }>;
+    /** Liveness — the LE waits for this before launching the agent. */
+    healthz(): Promise<boolean>;
+    /**
+     * Tear down: close the HTTP server, ZEROIZE the in-process upstream
+     * credentials, and clear the broker token. Idempotent.
+     */
+    stop(): Promise<void>;
+    /** The current broker token (for the agent's apiKeyHelper bootstrap). */
+    currentBrokerToken(): BrokerToken | null;
+    /**
+     * Re-mint (rotate) the broker token and return the new value. The LE calls
+     * this periodically (well within the TTL) + rewrites the apiKeyHelper token
+     * file so a long-running session never hits an expired-token 401 loop.
+     *
+     * M-3 — this is a GRACE rotation: the NEW token becomes current but the PRIOR
+     * token KEEPS authenticating until the LE confirms the helper file holds the
+     * new token (then calls {@link commitBrokerTokenRotation}). This closes the
+     * 401-loop window: there is NEVER a moment where the agent's file (which holds
+     * the prior token until the rewrite lands) is rejected. If the file rewrite
+     * FAILS, the LE calls {@link rollbackBrokerTokenRotation} to restore the prior
+     * token as the sole active one (fail-closed — no dead token left in the file).
+     * Returns null if the broker is stopped OR a rotation is already in-flight
+     * (Finding 3 overlap guard — the minter refuses a second concurrent rotation).
+     * The returned {@link RotationHandle} MUST be passed back to
+     * {@link commitBrokerTokenRotation} / {@link rollbackBrokerTokenRotation} so a
+     * stale (superseded) commit/rollback cannot clobber a newer rotation.
+     */
+    rotateBrokerToken(): RotationHandle | null;
+    /**
+     * Confirm a grace rotation: the helper file now holds the new token, so the
+     * prior (grace) token stops authenticating (single-active-token restored).
+     * Generation-bound (Finding 3): pass the {@link RotationHandle} from the
+     * matching {@link rotateBrokerToken}; a stale handle is a no-op.
+     */
+    commitBrokerTokenRotation(handle?: RotationHandle): void;
+    /**
+     * Roll back a grace rotation whose file rewrite FAILED: the prior token is
+     * restored as current (still in the agent's file, still valid) and the new
+     * token is discarded. No dead-token window. Generation-bound (Finding 3): pass
+     * the {@link RotationHandle} from the matching {@link rotateBrokerToken}.
+     */
+    rollbackBrokerTokenRotation(handle?: RotationHandle): void;
+    getVendorKey(provider: VendorProvider): Promise<string | null>;
+    setVendorKey(provider: VendorProvider, key: string): Promise<void>;
+    /**
+     * Handle one broker request (§3.2). The pure, transport-agnostic core —
+     * the HTTP server (`handleHttp`) adapts node req/res onto this. Route
+     * table check first (everything else → 403), then broker-token auth on
+     * the two POSTs (the ONLY 401 is an invalid agent→broker token), then
+     * the per-provider gateway (§3.3/§3.4/§3.5).
+     */
+    handle(req: BrokerRequest): Promise<BrokerResponse>;
+    private gateway;
+    /**
+     * Load the vendor key, caching it in-process, and emit
+     * `broker_credential_loaded` (§3.5) on each keychain load — with a
+     * `key_fingerprint` (sha256 prefix) and a fresh `credential_issuance_id`,
+     * NEVER the key. The credential-loaded audit is best-effort (it does not
+     * gate the forward — the `model_call` row does); a lost load-audit is a
+     * forensic gap, not an unsafe effect.
+     */
+    private loadVendorKey;
+    private lastIssuanceId;
+    /**
+     * Map an upstream response to the agent-facing status (§3.2). An upstream
+     * 401/403 (bad/expired vendor key) → 502 (NOT a pass-through 401, which
+     * would loop the agent's token-refresh hook). Every other status carries
+     * through; the body is the upstream JSON on success.
+     */
+    private mapUpstream;
+    /**
+     * Best-effort extraction of the requested model name for the audit row.
+     *
+     * OWN-property check ONLY (Codex W1 R3 prototype-pollution class). The
+     * body originates from `JSON.parse`, so a `{"__proto__":{"model":"<secret>"}}`
+     * payload could leave an INHERITED `model` on the prototype chain. A bare
+     * `"model" in body` / `body.model` would WALK the chain and read that
+     * injected secret straight into the durable `model_call.model` audit row
+     * (exfil). `Object.hasOwn` + an own-only read see ONLY a real top-level
+     * `$.model`; an inherited one is invisible → audited `model` is `"unknown"`,
+     * never the leaked value. (This is also fed the POST-scrub body, so even a
+     * real secret-shaped own `$.model` is already redacted by the scrubber —
+     * Codex W1 R1; the own-only read closes the inherited-property variant.)
+     */
+    private extractModel;
+    /** Best-effort token/cost extraction from an upstream response body. */
+    private extractUsage;
+    /**
+     * Emit a PRE-FORWARD (gated) audit row and BLOCK for a durable ACK
+     * (§3.5 audit-before-effect). Returns true ONLY on `{ack}`; a `{nack}`,
+     * a rejected promise (IPC failure), or any thrown error → false (the
+     * caller fails closed: 503, no forward). A security audit cannot
+     * silently drop.
+     */
+    private emitGated;
+    /**
+     * Emit a BEST-EFFORT audit row (`model_call_result` post-response,
+     * `broker_credential_loaded`). Losing it is a cost-tracking / forensic
+     * gap, never a security-invariant violation — so it never gates an
+     * effect and swallows nack/error.
+     */
+    private emitBestEffort;
+    /**
+     * Adapt a node HTTP request/response onto `handle`. Extracts the broker
+     * token (Anthropic `x-api-key` / `authorization: Bearer`; OpenAI
+     * `authorization: Bearer`), the agent headers/query/content-type, and the
+     * JSON body, then writes the `BrokerResponse` back. A malformed JSON body
+     * on a model POST → 400 (outside the canonical shape).
+     */
+    private handleHttp;
+    private extractBrokerToken;
+    private readBody;
+    private writeJson;
+}
+export { getProviderConfig };

package/dist/credential-broker/canonical.d.ts

@@ -0,0 +1,119 @@
+import type { BrokerRequest, VendorProvider } from "./types";
+/**
+ * The agent-supplied request, as the §3.2 `BrokerRequest` carries it.
+ * `headers` / `query` are OPTIONAL on the wire type but, when present,
+ * the canonical constructor DROPS them all (only an exact-allowlist beta
+ * token survives). They are accepted on the inbound shape solely so the
+ * gateway can assert it dropped them (conformance-testable).
+ */
+export interface CanonicalInput {
+    provider: VendorProvider;
+    /** The agent's raw inbound request. */
+    request: BrokerRequest;
+    /**
+     * Agent-supplied headers (lowercased keys), if the transport surfaced
+     * any. The canonical constructor drops all of them except an exact-
+     * allowlist beta token.
+     */
+    agentHeaders?: Readonly<Record<string, string>>;
+    /** Agent-supplied query string params, if any. ALL are dropped. */
+    agentQuery?: Readonly<Record<string, string>>;
+    /** Agent-declared content type, if the transport surfaced it. */
+    agentContentType?: string;
+}
+/**
+ * A constructed, canonical upstream request — everything the broker needs
+ * to forward, with the agent's raw envelope discarded. `model_call_id` is
+ * allocated here (§3.4) so a request that is scrubbed-then-rejected still
+ * has a stable id for its audit row.
+ */
+export interface CanonicalRequest {
+    provider: VendorProvider;
+    /** Absolute upstream URL (origin + canonical path), synthesized from config. */
+    upstreamUrl: string;
+    /**
+     * The upstream headers the broker synthesized — vendor/version +
+     * content-type + any exact-allowlist beta token. The upstream CREDENTIAL
+     * is injected separately at forward time (§3.3), NOT here.
+     */
+    headers: Record<string, string>;
+    /** The carried-through model-bound JSON body (the only surviving surface). */
+    body: unknown;
+    /** Per-forward id, allocated at construction (§3.4 / §3.5). */
+    modelCallId: string;
+    /** SHA-256 of the ORIGINAL pre-scrub body (§3.5 `request_sha256`). */
+    requestSha256: string;
+}
+/**
+ * A 400-class rejection (request outside the canonical shape). Carries a
+ * non-revealing reason for the broker's error envelope.
+ */
+export declare class CanonicalRejectError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+/**
+ * Compute the SHA-256 hex of the request body over a STABLE serialization
+ * of the ORIGINAL (pre-scrub) bytes. Uses `JSON.stringify` of the parsed
+ * body so the digest is independent of incidental whitespace, and is
+ * computed before any redaction so a scrub never changes it (§3.5).
+ */
+export declare function requestSha256(body: unknown): string;
+/**
+ * Build the canonical upstream request (§3.4 step 0). Rejects (throws
+ * `CanonicalRejectError` → 400) anything outside the canonical shape:
+ * non-JSON content type, a body that isn't a JSON object, or a non-
+ * allowlisted beta token. DROPS the agent's auth / every other header /
+ * all query params silently (they simply do not survive into the result).
+ */
+export declare function buildCanonicalRequest(input: CanonicalInput): CanonicalRequest;
+/**
+ * One general secret-shaped KEY the guard redacted (Codex W1 R4). Mirrors a
+ * scrubber `ScrubFinding`: the broker emits one `model_context_scrubbed` row
+ * per entry, carrying the PLACEHOLDER path + pattern class, NEVER the raw key.
+ */
+export interface GuardKeyScrub {
+    /** Canonical JSONPath of the redacted KEY's location (placeholder, leak-free). */
+    readonly field: string;
+    /** The non-revealing pattern class (always `secret_object_key`). */
+    readonly patternClass: string;
+}
+/**
+ * §3.4 step 1 — self-credential guard, and the AUTHORITATIVE object-key
+ * redactor for the whole request path. Two responsibilities:
+ *
+ *  (a) Assert the broker's own upstream key / the broker token never appear
+ *      in any model-bound field — as a string VALUE *or* as an object KEY
+ *      (defense-in-depth: redact + tell the caller so it audits via
+ *      `model_context_scrubbed`). Self-cred VALUE → `[REDACTED-SELF-CRED]`;
+ *      self-cred KEY → `[REDACTED-SELF-CRED-KEY]-<n>` (Codex W1 R2).
+ *
+ *  (b) Redact ANY *general* secret-shaped object KEY (`keyIsSecret`, the
+ *      scrubber's predicate) to `[REDACTED-CP7-KEY]-<n>` — even when it is
+ *      NOT a self-credential. This runs FIRST (before the §3.4-step-2
+ *      scrubber and before any leaked-path is recorded), so NO JSONPath the
+ *      guard builds — for its OWN key redactions, or for a self-cred VALUE
+ *      nested *beneath* such a key — can ever carry a raw secret key.
+ *
+ * (b) is the Codex W1 R4 fix. Before it, a self-cred value nested under a
+ * non-self-cred secret-shaped key (e.g. `{ "sk-ant-EXFIL…": { trigger:
+ * "<broker-token>" } }`) made the guard record `field =
+ * "$['sk-ant-EXFIL…'].trigger"` BEFORE the downstream scrubber's key
+ * redaction could fire — landing the raw key verbatim in a durable
+ * `model_context_scrubbed` row. Making the guard the single, FIRST key
+ * redactor closes that seam: every secret-shaped key (self-cred OR general)
+ * is a placeholder before any path is built, in either pass.
+ *
+ * Returns the redacted body, the `leakedPaths` where a SELF-credential was
+ * found (`pattern_class: self_credential`), and `keyScrubs` for general
+ * secret-shaped keys (`pattern_class: secret_object_key`). Every recorded
+ * path uses a PLACEHOLDER for any redacted key, never the raw key — so the
+ * audit surface is leak-free. The downstream scrubber sees only placeholder
+ * keys (never re-redacts them) and remains a value scrubber + a backstop key
+ * redactor should coverage ever diverge.
+ */
+export declare function selfCredentialGuard(body: unknown, secrets: ReadonlyArray<string>): {
+    body: unknown;
+    leakedPaths: string[];
+    keyScrubs: GuardKeyScrub[];
+};

package/dist/credential-broker/index.d.ts

@@ -0,0 +1,15 @@
+export type { VendorProvider, BrokerRouteMethod, BrokerRoute, BrokerStatus, BrokerRequest, BrokerResponse, ModelGatewayBroker, VendorKeyStore, BrokerToken, UpstreamResponse, UpstreamClient, } from "./types";
+export { BROKER_ROUTES } from "./types";
+export { LocalModelGatewayBroker } from "./broker";
+export type { BrokerDeps } from "./broker";
+export { FetchUpstreamClient } from "./upstream-client";
+export type { StrictAuditSink, AuditKindCp7, RecordedAuditEmit } from "./audit-sink";
+export { StubStrictAuditSink } from "./audit-sink";
+export { KeychainVendorKeyStore } from "./vendor-key-store";
+export { BrokerTokenMinter, type RotationHandle } from "./broker-token";
+export { buildCanonicalRequest, selfCredentialGuard, requestSha256, CanonicalRejectError, } from "./canonical";
+export type { CanonicalInput, CanonicalRequest } from "./canonical";
+export { scrubRequestBody } from "./scrubber";
+export type { ScrubFinding, ScrubResult } from "./scrubber";
+export { getProviderConfig, providerForPath } from "./broker-config";
+export type { ProviderConfig } from "./broker-config";

package/dist/credential-broker/scrubber.d.ts

@@ -0,0 +1,45 @@
+/**
+ * A single scrub finding — surfaced so the broker emits one
+ * `model_context_scrubbed` audit row per (field, pattern_class). NEVER
+ * carries the secret value.
+ */
+export interface ScrubFinding {
+    /** Canonical JSONPath of the field that was scrubbed, e.g. `$.messages[0].content`. */
+    readonly field: string;
+    /** The non-revealing pattern class (e.g. `anthropic_api_key`). */
+    readonly patternClass: string;
+}
+/**
+ * Result of scrubbing one request body.
+ */
+export interface ScrubResult {
+    /** A DEEP-CLONED, redacted copy of the body (the original is untouched). */
+    readonly scrubbed: unknown;
+    /** One finding per (field, pattern_class) hit; empty if nothing matched. */
+    readonly findings: ScrubFinding[];
+}
+/**
+ * Does this object-key NAME itself match a high-confidence secret shape?
+ * A key like `"sk-ant-…"` carries the secret AS the key — value-only
+ * scrubbing would forward it verbatim (exfil out the one allow-listed
+ * egress) and a JSONPath built from it would embed the raw secret in an
+ * audit row. Reuses the SAME `SECRET_PATTERNS` so key + value coverage
+ * evolve together (no separate key schema). Read-only `.test()` (lastIndex
+ * is reset each side because the regexes are global/stateful).
+ *
+ * EXPORTED (Codex W1 R4): the self-credential guard (`canonical.ts`) runs
+ * BEFORE this scrubber and is the AUTHORITATIVE key redactor — it imports
+ * this predicate so a general secret-shaped KEY is replaced with a
+ * placeholder before ANY JSONPath is built, in either pass. Sharing this one
+ * function keeps the guard's and the scrubber's key coverage identical (no
+ * second key schema to drift).
+ */
+export declare function keyIsSecret(key: string): boolean;
+/**
+ * The I2 scrubber (§3.4 step 2). Walks the model-bound request JSON,
+ * redacts high-confidence secret shapes in every string, and reports each
+ * scrub by canonical JSONPath + pattern class (never the value). The
+ * returned `scrubbed` body is a deep clone — the caller keeps the
+ * original to compute `request_sha256` over the PRE-scrub bytes (§3.5).
+ */
+export declare function scrubRequestBody(body: unknown): ScrubResult;

package/dist/credential-broker/types.d.ts

@@ -0,0 +1,141 @@
+/**
+ * The vendor providers Rung 1 brokers. Claude + Codex (Anthropic +
+ * OpenAI) only — Gemini stays out of the substrate (§6 Q4, agy is
+ * reduced-trust).
+ */
+export type VendorProvider = "anthropic" | "openai";
+/** A route the broker serves. */
+export type BrokerRouteMethod = "POST" | "GET";
+/**
+ * The locked broker route table (§3.2). Declared as data-shape types so
+ * the W1 gateway and any conformance test agree on the surface without
+ * a contract reopen.
+ */
+export interface BrokerRoute {
+    method: BrokerRouteMethod;
+    path: "/v1/messages" | "/v1/responses" | "/healthz";
+    /** Whether the route requires a valid agent→broker token. */
+    auth: "broker_token" | "none";
+}
+/**
+ * The broker's locked route table — exactly three routes (§3.2). Any
+ * other method+path → 403.
+ */
+export declare const BROKER_ROUTES: readonly BrokerRoute[];
+/**
+ * The broker's HTTP status taxonomy (§3.2 + §3.2 upstream-auth note).
+ * Declared as a typed enum so the W1 gateway and reviewers share one
+ * source of truth for the fail-closed status mapping.
+ */
+export type BrokerStatus = 200 | 400 | 401 | 403 | 502 | 503;
+/**
+ * An inbound request to the broker. `method`/`path` are **raw HTTP
+ * strings**, deliberately NOT narrowed to `BROKER_ROUTES` (Codex W0 R1):
+ * the §3.2 contract is "everything else → 403", so the type MUST be able
+ * to represent a *disallowed* route for the W1 gateway's `handle()` to be
+ * conformance-testable (send `/v1/admin` / `DELETE` → assert 403). Only
+ * the three `(method, path)` pairs in `BROKER_ROUTES` are forwarded; every
+ * other request fails closed at 403.
+ */
+export interface BrokerRequest {
+    method: string;
+    path: string;
+    /** Opaque short-lived agent→broker token (§3.3); absent for `/healthz`. */
+    brokerToken?: string;
+    /** Model-bound JSON body (the only carried-through surface, §3.4). */
+    body?: unknown;
+    /**
+     * Agent-supplied headers (lowercased keys), if the transport surfaced
+     * any. The §3.4 canonical constructor DROPS all of them except an
+     * exact-allowlist beta token; carried on the wire type so `handle()`'s
+     * canonicalization is conformance-testable (assert the agent's
+     * `authorization` / `x-api-key` / unknown headers do not reach upstream).
+     */
+    agentHeaders?: Readonly<Record<string, string>>;
+    /** Agent-supplied query params, if any. ALL are dropped (§3.4). */
+    agentQuery?: Readonly<Record<string, string>>;
+    /** Agent-declared content type, if surfaced. Non-JSON → 400 (§3.4). */
+    agentContentType?: string;
+}
+/** Response from a broker model-gateway route. */
+export interface BrokerResponse {
+    status: BrokerStatus;
+    /** Upstream model-bound JSON body on 200; an error envelope otherwise. */
+    body?: unknown;
+}
+/**
+ * The lifecycle surface of the per-session local broker daemon (§3.2).
+ * The LE starts one broker per session on `127.0.0.1:<ephemeral>` and
+ * tears it down at session end. Signatures only in W0.
+ */
+export interface ModelGatewayBroker {
+    /** Start listening on an ephemeral loopback port; resolve the bound addr. */
+    start(): Promise<{
+        hostBrokerAddr: string;
+    }>;
+    /** Liveness — the LE waits for this before launching the agent. */
+    healthz(): Promise<boolean>;
+    /** Handle one model-gateway request (the §3.2 route surface). */
+    handle(req: BrokerRequest): Promise<BrokerResponse>;
+    /** Tear down; zeroize the in-process upstream credential (§3.3). */
+    stop(): Promise<void>;
+}
+/**
+ * The provider-scoped vendor-key storage API (§3.3) — [NEW], owner W1.
+ * Reuses the existing keychain backend (OS keyring + file fallback).
+ * Signatures only in W0; the implementation (keychain accounts
+ * `vendor-key-<provider>`) lands in W1.
+ */
+export interface VendorKeyStore {
+    /**
+     * Read the user's vendor key for `provider` from the keychain. Returns
+     * `null` when no key is present — the broker then fails closed (503),
+     * NEVER a silent fallback to an ambient `ANTHROPIC_API_KEY` /
+     * `OPENAI_API_KEY` (that would re-introduce the I1 ambient-cred path).
+     */
+    getVendorKey(provider: VendorProvider): Promise<string | null>;
+    /** Persist the user's vendor key for `provider` (one-time setup step). */
+    setVendorKey(provider: VendorProvider, key: string): Promise<void>;
+}
+/**
+ * The agent→broker token (§3.3): per-session, broker-minted, opaque,
+ * short-lived. Authenticates the agent to the LOCAL broker only — it is
+ * NOT a vendor credential.
+ */
+export interface BrokerToken {
+    /** Opaque token value emitted to the agent's apiKeyHelper / `[auth]` hook. */
+    readonly value: string;
+    /** Epoch-ms expiry; the helper refreshes on expiry / on a broker 401. */
+    readonly expiresAtMs: number;
+}
+/**
+ * The result of a broker→vendor upstream call. The broker maps upstream
+ * status to the agent-facing `BrokerStatus` (§3.2): an upstream 401/403
+ * (bad/expired vendor key) → 502 (NOT a pass-through), every other status
+ * carries through.
+ */
+export interface UpstreamResponse {
+    /** Raw upstream HTTP status. */
+    status: number;
+    /** Parsed JSON body (model-bound). */
+    body?: unknown;
+}
+/**
+ * The broker→vendor upstream HTTP client (§3.3/§3.4). INJECTED so W1 tests
+ * use a stub (no real network). The real fetch-backed client lands when
+ * the broker is wired into the LE; W1 only depends on this interface.
+ */
+export interface UpstreamClient {
+    /**
+     * POST the canonical request upstream. `headers` already includes the
+     * synthesized vendor/version headers AND the injected upstream
+     * credential (the caller adds the credential header). Resolves with the
+     * upstream status + body; rejects only on a transport/network error
+     * (which the broker maps to its forward-error path).
+     */
+    post(args: {
+        url: string;
+        headers: Readonly<Record<string, string>>;
+        body: unknown;
+    }): Promise<UpstreamResponse>;
+}

package/dist/credential-broker/upstream-client.d.ts

@@ -0,0 +1,20 @@
+import type { UpstreamClient, UpstreamResponse } from "./types";
+/**
+ * The production fetch-backed {@link UpstreamClient}. Constructed once per
+ * broker session by the LE and injected into `LocalModelGatewayBroker`
+ * (replacing the W1 stub).
+ */
+export declare class FetchUpstreamClient implements UpstreamClient {
+    private readonly opts;
+    constructor(opts?: {
+        /** Injectable for tests (default: global `fetch`). */
+        fetchFn?: typeof fetch;
+        /** Per-request timeout (ms). */
+        timeoutMs?: number;
+    });
+    post(args: {
+        url: string;
+        headers: Readonly<Record<string, string>>;
+        body: unknown;
+    }): Promise<UpstreamResponse>;
+}

package/dist/credential-broker/vendor-key-store.d.ts

@@ -0,0 +1,54 @@
+import type { VendorKeyStore, VendorProvider } from "./types";
+/**
+ * Keychain-backed implementation of {@link VendorKeyStore} (§3.3). Reads
+ * the same keychain service the rest of CodeVibe uses (`getConfig()
+ * .keychain.serviceName`) so vendor keys live alongside the existing
+ * device identity + OAuth tokens under one auditable backend.
+ *
+ * r5 HIGH-1 / r6 HIGH-2 (Codex): unlike the OAuth-token storage, the vendor
+ * key is KEYCHAIN-ONLY at rest for BOTH read and write — `setVendorKey`
+ * (write) and `getVendorKey` (read) BOTH require the real OS keychain and
+ * FAIL CLOSED rather than touch the plaintext file backend (see the two
+ * methods + file header). The agent can never REACH the key at runtime on any
+ * substrate (A1 never mounts `~/.codevibe`; A5 denies it in the Seatbelt
+ * profile).
+ */
+export declare class KeychainVendorKeyStore implements VendorKeyStore {
+    private get serviceName();
+    /**
+     * Read the user's vendor key from the keychain. Returns `null` when no
+     * key is present (the broker fails closed — 503). Backend errors
+     * (keyring unavailable, corrupted store) propagate to the caller, same
+     * as `KeychainManager.getTokens` — a hard config failure the user must
+     * see, NOT a silent "no key" that would mask a broken keychain.
+     *
+     * NO ambient-env fallback (I1): a missing key is `null`, full stop.
+     *
+     * r6 HIGH-2 (Codex): KEYCHAIN-ONLY on the READ side too. We require the real
+     * OS keychain (`getActiveBackendKind() === 'keytar'`) BEFORE reading. On the
+     * FILE backend we FAIL CLOSED by returning `null` (the broker then fails
+     * closed — 503) and DO NOT read `~/.codevibe/<service>.json` — so a legacy /
+     * manually-placed PLAINTEXT vendor key is never sourced from the file store.
+     * On a file-backend (headless Linux) box the user supplies the vendor key
+     * per-session into broker memory (the documented open item — see file header).
+     * SCOPED to the vendor key — the shared backend's OAuth-token file fallback
+     * (#29) is untouched (we only call the read-only `getActiveBackendKind`).
+     */
+    getVendorKey(provider: VendorProvider): Promise<string | null>;
+    /**
+     * Persist the user's vendor key (one-time setup step). The plaintext
+     * value is never logged.
+     *
+     * r5 HIGH-1 (Codex): FAIL CLOSED if only the FILE backend is available —
+     * the broker refuses to write a PLAINTEXT vendor key to
+     * `~/.codevibe/<service>.json`. We prefer the REAL OS keychain; if it is
+     * unavailable (the file backend is active), we throw rather than silently
+     * persisting the key in plaintext (which would break the keychain-only
+     * at-rest invariant). This is SCOPED to the vendor key — the shared
+     * backend's OAuth-token file fallback (#29) is untouched. r6 HIGH-2: the READ
+     * side (`getVendorKey`) is now gated the SAME way (returns `null` on the file
+     * backend, no plaintext read); on a fail-closed box the user supplies the key
+     * per-session into broker memory.
+     */
+    setVendorKey(provider: VendorProvider, key: string): Promise<void>;
+}

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 export { KeychainManager, keychainManager, KeychainError } from './keychain';
 export { CryptoService, cryptoService, CryptoError, ENCRYPTION_VERSION } from './crypto';
-export { AppSyncClient, DownloadUrlResponse } from './appsync';
+export { AppSyncClient, AppSyncGraphQLError, DownloadUrlResponse } from './appsync';
 export { queries, mutations, subscriptions } from './appsync';
 export { AuthService, authService } from './auth';
+export { bindOAuthServer, PRIMARY_PORT, PORT_RANGE_SIZE } from './auth';
 export { runAuthCli } from './auth';
 export { fireAuthCompletedBeacon, fireAuthFailedBeacon, markErrorBeaconed, errorWasBeaconed, getErrorReason, } from './auth';
 export type { AuthFailureReason, AuthStage } from './auth';
@@ -11,10 +12,22 @@ export type { Config, Environment } from './config';
 export { Logger, logger, createLogger } from './logger';
 export { parseInteractivePrompt, normalizeSnapshot, } from './prompt-parser';
 export type { ParsedInteractivePrompt, PromptKind, InteractivePromptOption, } from './prompt-parser';
-export { resumeOrCreateSession, prepareSessionEncryption, rekeySessionForNewDevices, startDeviceKeyWatcher, registerDeviceEncryptionKey, } from './session';
+export { resumeOrCreateSession, prepareSessionEncryption, rekeySessionForNewDevices, startDeviceKeyWatcher, registerDeviceEncryptionKey, prepareEventTimestamp, _resetPrepareEventTimestampForTesting, } from './session';
 export type { ResumeOrCreateSessionInput, ResumeOrCreateSessionResult } from './session';
-export { detectInstalledAgents, pushDetectedAgents, applyPerSessionOrchestrationOverride, runOrchestrationCli, } from './orchestration';
-export type { DetectableAgent } from './orchestration';
+export { detectInstalledAgents, pushDetectedAgents, applyPerSessionOrchestrationOverride, runOrchestrationCli, V1_ORCHESTRATION_PROMPT_KIND, V1_ORCHESTRATION_OPTIONS, mapOptionNumberToUserDecisionKind, mapOptionToUserDecisionKind, } from './orchestration';
+export type { DetectableAgent, V1OrchestrationOption, V1UserDecisionKind, } from './orchestration';
 export * as Reviewer from './reviewer';
 export * as AuditKeys from './audit-keys';
+export * as Substrate from './substrate';
+export * as CredentialBroker from './credential-broker';
+export * as SubstrateLaunch from './substrate-launch';
 export * from './types';
+export * as Planner from './planner';
+export * as Continuation from './continuation';
+export * as StructuralSummary from './structural-summary';
+export { runOrchestrationShell } from './orchestration-shell';
+export { runCompanionMode } from './companion-mode';
+export { pickMode, TierError } from './orchestration-shell';
+export { emitShellEvent, createShellEventEmitter } from './orchestration-shell';
+export { processMarkers, withRoleMarker } from './orchestration-shell';
+export type { Mode, Tier, PlannerDecision, AgentKind, PlannerHealthState, OrchestrationState, OrchestrationAction, ConversationEntry, RunningTaskState, ReviewerSeatState, GateState, ExecutionEventEntry, RefusalEventEntry, BypassEventEntry, MobileEventEntry, EventStreamEntry, QueuedTask, PendingClarification, LastModeFile, } from './orchestration-shell';