@quantiya/codevibe-core 2.0.1 → 2.0.2

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,69 @@
+/**
+ * The five CP-7 audit kinds (§3.5), in their snake_case wire form — the
+ * exact strings the `AuditEventKind` enum serializes as and the
+ * `audit-keys` discriminator constants use. Defined here (not imported
+ * from a Rust-mirrored module) because W1 only needs the broker-side
+ * wire kinds; W3 wires these to the real `AuditEventKind` enum + NAPI
+ * `parse_audit_kind`.
+ *
+ * Note: only `model_call`, `model_call_result`, `model_context_scrubbed`,
+ * and `broker_credential_loaded` are broker-emitted. `egress_denied` is
+ * emitted by the substrate's egress proxy (§3.5, W2/W3) — it is included
+ * in the union for completeness of the CP-7 audit taxonomy but the broker
+ * never emits it.
+ */
+export type AuditKindCp7 = "model_call" | "model_call_result" | "egress_denied" | "model_context_scrubbed" | "broker_credential_loaded";
+/**
+ * The strict audit sink the broker emits through (§3.5).
+ *
+ * Per §3.5: the sender transmits `{kind, payload}` and BLOCKS for the
+ * LE's durable ACK. A resolved `{ ack }` means the row is durably on
+ * disk (the gated effect — the upstream forward — may proceed for a
+ * pre-forward row). A resolved `{ nack }` means the durable write failed
+ * (the broker fails closed: 503, no forward). A rejected/timed-out promise
+ * is treated by the broker exactly like a NACK (fail closed on a
+ * pre-forward row).
+ */
+export interface StrictAuditSink {
+    emit(kind: AuditKindCp7, payload: Record<string, unknown>): Promise<{
+        ack: string;
+    } | {
+        nack: string;
+    }>;
+}
+/**
+ * A recorded emit, surfaced by {@link StubStrictAuditSink} for test
+ * assertions (the real LE emitter exposes nothing comparable — this is a
+ * test seam only).
+ */
+export interface RecordedAuditEmit {
+    kind: AuditKindCp7;
+    payload: Record<string, unknown>;
+}
+/**
+ * In-memory deterministic `StrictAuditSink` for unit tests + the injected
+ * default until W3. Every `emit` ACKs with a deterministic
+ * `stub-ack-<n>` id and records the `{kind, payload}` for assertions.
+ *
+ * Two test hooks (both default off so the happy path is deterministic):
+ * - `nackKinds`: any kind in this set NACKs instead of ACKing — exercises
+ *   the audit-before-effect 503 path.
+ * - `failKinds`: any kind in this set REJECTS the promise — exercises the
+ *   "IPC error / timeout treated as fail-closed" path.
+ */
+export declare class StubStrictAuditSink implements StrictAuditSink {
+    private readonly opts;
+    readonly emitted: RecordedAuditEmit[];
+    private counter;
+    constructor(opts?: {
+        nackKinds?: ReadonlyArray<AuditKindCp7>;
+        failKinds?: ReadonlyArray<AuditKindCp7>;
+    });
+    emit(kind: AuditKindCp7, payload: Record<string, unknown>): Promise<{
+        ack: string;
+    } | {
+        nack: string;
+    }>;
+    /** All emitted rows of a given kind (test helper). */
+    ofKind(kind: AuditKindCp7): RecordedAuditEmit[];
+}

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

@@ -0,0 +1,39 @@
+import type { VendorProvider } from "./types";
+/**
+ * Per-provider wire facts the broker synthesizes on the upstream call.
+ */
+export interface ProviderConfig {
+    /** Upstream origin (scheme + host) the broker forwards to. */
+    readonly upstreamBaseUrl: string;
+    /** The canonical upstream path for this provider's model route. */
+    readonly upstreamPath: "/v1/messages" | "/v1/responses";
+    /**
+     * Headers the broker synthesizes on EVERY upstream call — overriding
+     * whatever the agent supplied. `content-type` is always normalized to
+     * `application/json` (the only carried-through content type, §3.4).
+     */
+    readonly synthesizedHeaders: Readonly<Record<string, string>>;
+    /**
+     * The EXACT allowlist of `anthropic-beta` (or provider equivalent)
+     * tokens the broker will pass through. A request carrying a beta token
+     * outside this set is rejected (400) — header VALUES are agent-
+     * controlled and can carry data (Codex R2). Empty for OpenAI (no beta
+     * header is forwarded).
+     */
+    readonly betaTokenAllowlist: ReadonlySet<string>;
+    /**
+     * The name of the agent-supplied beta header this provider honors
+     * (lowercased), or `null` if the provider has none. Used by the
+     * canonical constructor to find the agent's beta tokens to validate.
+     */
+    readonly betaHeaderName: string | null;
+}
+/**
+ * Resolve the locked wire facts for a provider. Pure data — no I/O.
+ */
+export declare function getProviderConfig(provider: VendorProvider): ProviderConfig;
+/**
+ * Map an inbound broker route path to the vendor provider it gateways.
+ * `/v1/messages` → Anthropic, `/v1/responses` → OpenAI.
+ */
+export declare function providerForPath(path: string): VendorProvider | null;

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

@@ -0,0 +1,123 @@
+import type { BrokerToken } from "./types";
+/**
+ * Mints + holds the current per-session broker token, and authenticates
+ * inbound agent→broker tokens against it. A new token replaces the prior
+ * one (single active token per session); `authenticate` accepts ONLY the
+ * current, unexpired value — every other value (including a just-rotated
+ * old token) is rejected, which the broker maps to the only 401 it emits.
+ */
+/**
+ * A grace-rotation handle (Finding 3). `rotateWithGrace` returns this; the LE
+ * passes it back to {@link BrokerTokenMinter.commitRotation} /
+ * {@link BrokerTokenMinter.rollbackRotation}. The `generation` GENERATION-BINDS
+ * the commit/rollback to the SPECIFIC rotation that produced it: a stale handle
+ * (from a rotation already superseded by a newer one) is rejected, so a slow
+ * commit/rollback cannot clobber a newer in-flight rotation's token.
+ */
+export interface RotationHandle {
+    readonly token: BrokerToken;
+    readonly generation: number;
+}
+export declare class BrokerTokenMinter {
+    private readonly ttlMs;
+    private current;
+    /**
+     * During a rotation the PRIOR token stays acceptable until the LE confirms
+     * the apiKeyHelper file holds the NEW token (`commitRotation`). This closes
+     * the 401-loop window the contract forbids (Stage-2 M-3): if we invalidated
+     * the prior token BEFORE the file refresh landed, the agent's file would hold
+     * a now-rejected token until the next refresh. With the grace token, BOTH the
+     * new and the prior token authenticate until the write is confirmed.
+     */
+    private graceToken;
+    /**
+     * Finding 3 — generation counter, bumped on every successful grace rotation.
+     * Commit/rollback are bound to the generation of the rotation they belong to;
+     * a stale (superseded) commit/rollback is a no-op. The generation also gates
+     * OVERLAPPING rotations: `rotateWithGrace` REJECTS (returns null) while a grace
+     * is still pending, so two near-concurrent rotations can never chain
+     * grace→grace and strand the file token.
+     */
+    private generation;
+    constructor(ttlMs?: number);
+    /** Mint (or rotate) the session's broker token; returns the new token. */
+    mint(now?: number): BrokerToken;
+    /**
+     * M-3 — SAFE rotation. Mint a NEW current token but KEEP the prior token
+     * valid (as a grace token) so there is no window where the agent's file (which
+     * still holds the prior token until the LE rewrites it) is rejected. The LE
+     * MUST call {@link commitRotation} AFTER it confirms the helper file now holds
+     * the new token (drops the grace token), or {@link rollbackRotation} if the
+     * file write FAILED (restores the prior token as current and discards the new
+     * one — the agent's file is still valid, fail-closed, no dead token).
+     *
+     * Finding 3 — OVERLAP REJECTION: returns null when a grace rotation is already
+     * pending (not yet committed/rolled back). Chaining grace→grace would make the
+     * SECOND rotation's grace token be the FIRST rotation's new token (not the
+     * file-resident prior token); if the first refresh then writes its token and
+     * commits, the file token could be left unauthenticated. By refusing to start a
+     * second rotation until the first settles, BOTH tokens that ever authenticate
+     * are {file-resident prior, new} — the file token is never stranded.
+     *
+     * Returns the {@link RotationHandle} for the new token, or null if the broker
+     * has no current token yet (nothing to rotate) OR a rotation is in-flight.
+     */
+    rotateWithGrace(now?: number): RotationHandle | null;
+    /**
+     * Confirm the helper file now holds the new token — drop the grace token so
+     * the prior token stops authenticating (single-active-token restored).
+     *
+     * Finding 3 — generation-bound: a commit whose `generation` does not match the
+     * current generation is STALE (a newer rotation/mint superseded it) and is a
+     * NO-OP, so it cannot drop a newer rotation's grace token.
+     */
+    commitRotation(handle?: RotationHandle): void;
+    /**
+     * The file refresh FAILED — roll back: restore the prior (grace) token as
+     * current and discard the just-minted new token. The agent's file still holds
+     * the prior token, which is once again the sole active token → no dead-token
+     * window. No-op if there is no pending grace rotation.
+     *
+     * Finding 3 — generation-bound: a rollback whose `generation` does not match
+     * the current generation is STALE and a NO-OP, so a late rollback from a
+     * superseded rotation cannot revert a newer rotation's token.
+     */
+    rollbackRotation(handle?: RotationHandle): void;
+    /** Whether a rotation is mid-flight (grace token still accepted). Test seam. */
+    hasPendingGrace(): boolean;
+    /** The current token, or null if none minted yet. */
+    get(): BrokerToken | null;
+    /**
+     * EVERY broker-token value that `authenticate()` would currently accept — the
+     * CURRENT token plus, during a mid-flight grace rotation, the PRIOR (grace)
+     * token. Used by the broker's self-credential guard so it scrubs ALL tokens a
+     * model-bound field could be carrying, not just `get()` (Stage-2 MEDIUM): the
+     * prior token still authenticates during the grace window AND is still resident
+     * in the agent's helper file, so a model-bound field echoing it is a live-token
+     * leak the guard must redact. Values are returned only (the actual scrub +
+     * commit/rollback gate is the caller's); a stale/expired grace token is NOT
+     * included (it can no longer authenticate, so it is not a live secret).
+     *
+     * NOTE: this does NOT filter on `expiresAtMs` — `authenticate()` rejects an
+     * expired token, but an expired-yet-still-resident token in the helper file is
+     * still a secret-shaped value the guard should keep out of model-bound content;
+     * we err toward scrubbing both held values whenever they are non-null. (An
+     * expired token cannot be USED, but redacting it is strictly safer and never
+     * wrong — the guard only ever removes a value, never adds one.)
+     */
+    acceptedValues(): string[];
+    /**
+     * Authenticate an inbound agent→broker token. True for the current, unexpired
+     * token value OR (during a mid-flight rotation) the unexpired grace token —
+     * the latter keeps the agent's pre-refresh file valid until the LE confirms
+     * the file rewrite (M-3 no-rejection-window contract). A missing / stale /
+     * expired / mismatched token → false (the broker returns 401 — the ONLY 401
+     * it emits, §3.2).
+     *
+     * Constant-time-ish compare is unnecessary for a loopback-only local
+     * token, but we still avoid leaking via early-return on length.
+     */
+    authenticate(token: string | undefined, now?: number): boolean;
+    /** Zeroize the held token (broker teardown). */
+    clear(): void;
+}

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;