@quantiya/codevibe-core 2.0.1 → 2.0.3

package/dist/continuation/types.d.ts

@@ -0,0 +1,239 @@
+/**
+ * CP-6 LOCK #C6-A-1 AgentKind union — 4 values per AGY-2.0-SUPPORT-DESIGN.md.
+ * As of Phase C, ANTIGRAVITY is a fully-valid continuation SOURCE and TARGET
+ * end-to-end (TS `VALID_TARGET_AGENTS` + the Rust
+ * `recordContinuationPacketWritten` / `apply_user_decision` validators all
+ * accept it; the Codex M2 §4.10.4 rejection was inverted in Phase C).
+ */
+export type AgentKind = 'CLAUDE' | 'CODEX' | 'GEMINI' | 'ANTIGRAVITY';
+/**
+ * CP-6 LOCK #C6-A-1 — 4-value `HandoffReason` union. Implementor-
+ * continuation triggers only (master §8:932-937 reserves
+ * `reviewer_unavailable` / `reviewer_conflict` / `unsafe_action` for
+ * CP-3.h / CP-2.h / CP-9 min escalation — NOT CP-6 continuation
+ * packet-write paths).
+ *
+ * The 4 §7 trigger rows map onto §6:827 wire spellings 1:1:
+ *   - §7 "Quota exhausted" → `quota_exhausted`
+ *   - §7 "Auth failed"     → `auth_failed`
+ *   - §7 "Agent timeout"   → `timeout`
+ *   - §7 "User request"    → `user_requested`
+ *
+ * §6:827 also defines `explicit_escalation` + `reviewer_conflict`;
+ * the CP-6 reader accepts them but the writer never emits them.
+ */
+export type HandoffReason = 'quota_exhausted' | 'auth_failed' | 'timeout' | 'user_requested';
+/**
+ * Gate-state snapshot embedded in every continuation packet. Captures
+ * the prior implementor's verification + reviewer-quorum + final-
+ * approval pose so the next implementor can read but not bypass.
+ */
+export interface GateState {
+    verification: 'not_started' | 'pass' | 'fail';
+    reviewerQuorum: 'not_started' | 'pass' | 'revise' | 'block';
+    finalApproval: boolean;
+}
+/**
+ * Per-repo state captured at packet-write time by LOCK #C6-A-7
+ * dirty-state collector. `headSha` / `branch` fall through to the
+ * literal `"unknown"` sentinel when git is unavailable or
+ * `git rev-parse` times out.
+ */
+export interface RepoState {
+    /** repo basename (e.g., `codevibe-backend`). */
+    repo: string;
+    /** absolute filesystem path (clamped to authority writeScopes/readScopes). */
+    path: string;
+    /** git branch — literal `"unknown"` when git rev-parse fails. */
+    branch: string;
+    /** 40-hex git sha — literal `"unknown"` when git rev-parse fails. */
+    headSha: string;
+    dirty: boolean;
+    /** git status --porcelain output, relative to repo root. */
+    changedFiles: string[];
+}
+/**
+ * CP-6 LOCK #C6-A-1 — 17-field continuation packet structural type.
+ * Mirrors master §6:820-852 byte-for-byte.
+ *
+ * Sentinel taxonomy per §8.1:
+ *   - WRITER-CONSTANT (1):       packetVersion (always 1)
+ *   - STRICT-REQUIRED (8):       taskId, sessionId, sourceAgent,
+ *                                targetAgent, handoffReason, role,
+ *                                taskSummary, expiresAt
+ *   - CALLER-OR-COLLECTOR (1):   repoStates (falls through to
+ *                                dirty-state collector when caller
+ *                                passes undefined)
+ *   - AUTO-SENTINEL (7):         completedWork, remainingWork,
+ *                                verification, activeRules, gateState,
+ *                                safetyConstraints, reviewHistoryRefs
+ */
+export interface ContinuationPacket {
+    packetVersion: 1;
+    taskId: string;
+    sessionId: string;
+    sourceAgent: AgentKind;
+    targetAgent: AgentKind;
+    handoffReason: HandoffReason;
+    /** CP-6 always emits `"implementor"`; reviewer-role packets deferred. */
+    role: 'implementor';
+    repoStates: RepoState[];
+    /** Master §6:839 — "what the implementor is trying to complete". */
+    taskSummary: string;
+    /** Master §6:840 — facts already done. */
+    completedWork: string[];
+    /** Master §6:841 — next actions. */
+    remainingWork: string[];
+    /** Master §6:842 — tests run AND tests intentionally not run. */
+    verification: string[];
+    /** Master §6:843 — gate plan + commit/push rules + safety constraints. */
+    activeRules: string[];
+    gateState: GateState;
+    /** Master §6:849. */
+    safetyConstraints: string[];
+    /** Master §6:850 — file paths or AppSync row IDs. */
+    reviewHistoryRefs: string[];
+    /** ISO-8601 RFC 3339 timestamp. */
+    expiresAt: string;
+}
+export declare class PacketFidelityError extends Error {
+    readonly missingFields: string[];
+    constructor(missingFields: string[], message?: string);
+}
+export declare class PacketIoError extends Error {
+    readonly cause?: NodeJS.ErrnoException;
+    constructor(message: string, cause?: NodeJS.ErrnoException);
+}
+export declare class PacketHashMismatch extends Error {
+    readonly expectedHash: string;
+    readonly actualHash: string;
+    constructor(expectedHash: string, actualHash: string);
+}
+export declare class PacketAuditEmitError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+export declare class PacketNotFound extends Error {
+    readonly packetPath: string;
+    constructor(packetPath: string);
+}
+export declare class PacketUnverified extends Error {
+    readonly packetPath: string;
+    readonly taskId: string;
+    readonly packetHash: string;
+    constructor(packetPath: string, taskId: string, packetHash: string);
+}
+export declare class FrontmatterMalformed extends Error {
+    readonly cause?: Error;
+    constructor(message: string, cause?: Error);
+}
+export declare class SchemaInvalid extends Error {
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+export declare class PacketPermissionsLoose extends Error {
+    readonly path: string;
+    readonly actualMode: number;
+    constructor(filePath: string, actualMode: number);
+}
+/**
+ * Caller-supplied fields for `writer.write()`. All 8 STRICT-REQUIRED
+ * fields (per §8.1 sentinel taxonomy) are required at the type level;
+ * AUTO-SENTINEL fields are optional and default to the §8.1 sentinel
+ * when omitted. `repoStates` is optional — when undefined, the writer
+ * dispatches to the dirty-state collector.
+ *
+ * `offerId` is not part of the packet body itself (it lives on the
+ * backend audit row per LOCK #C6-A-10); the writer forwards it to
+ * `AppSyncClient.recordContinuationPacketWritten`. Use `null` for
+ * LE-initiated writes that have no prior Class B offer.
+ */
+export interface PacketWriteInput {
+    taskId: string;
+    sessionId: string;
+    sourceAgent: AgentKind;
+    targetAgent: AgentKind;
+    handoffReason: HandoffReason;
+    /**
+     * STRICT-REQUIRED per §8.1 sentinel taxonomy (Stage 2 R1 M-2 fix —
+     * was previously optional with a silent `?? 'implementor'` default,
+     * a contract deviation from the locked design). Callers MUST pass
+     * `'implementor'` explicitly; the writer throws `PacketFidelityError`
+     * with `missingFields: ['role', ...]` when undefined.
+     */
+    role: 'implementor';
+    taskSummary: string;
+    expiresAt: string;
+    repoStates?: RepoState[];
+    completedWork?: string[];
+    remainingWork?: string[];
+    verification?: string[];
+    activeRules?: string[];
+    gateState?: GateState;
+    safetyConstraints?: string[];
+    reviewHistoryRefs?: string[];
+    offerId?: string | null;
+    blockedReason?: HandoffReason;
+    /**
+     * PHASE-CP-10-MIN (#585) — the round's gate the desktop is handing off from
+     * (H-A). Forwarded to `recordContinuationPacketWritten` (the additive
+     * `gateId: ID` input) so the handler `fetch_row`s it, cross-checks
+     * `gate_row.task_id == input.task_id`, and uses it as the #C10M-14
+     * mutual-exclusion stamp target + the emitted prompt's `EmitContext.gate_id`.
+     * NOT embedded in the packet body. Required at the handler for #585's two
+     * triggers; optional at the type level so legacy/LE-initiated writes that
+     * predate CP-10 still type-check.
+     */
+    gateId?: string;
+}
+export interface PacketWriteResult {
+    /** 64-char lowercase hex SHA-256 of JCS-canonical-JSON(packet). */
+    packetHash: string;
+    /** Absolute path of the written CONTINUATION.md. */
+    path: string;
+}
+export interface PacketListEntry {
+    taskId: string;
+    packetExists: boolean;
+    lastModified: Date | null;
+    packetHash?: string;
+}
+/**
+ * Discriminated union returned by `reader.read()` when used in
+ * fail-soft mode. Throwing variants live on the reader directly; the
+ * union is exported for callers that prefer typed-return semantics.
+ */
+export type ContinuationPacketReadResult = {
+    kind: 'ok';
+    packet: ContinuationPacket;
+    packetHash: string;
+} | {
+    kind: 'not_found';
+    path: string;
+} | {
+    kind: 'unverified';
+    path: string;
+    taskId: string;
+    packetHash: string;
+} | {
+    kind: 'permissions_loose';
+    path: string;
+    actualMode: number;
+} | {
+    kind: 'frontmatter_malformed';
+    path: string;
+    message: string;
+} | {
+    kind: 'schema_invalid';
+    path: string;
+    errors: string[];
+} | {
+    kind: 'hash_mismatch';
+    path: string;
+    expectedHash: string;
+    actualHash: string;
+} | {
+    kind: 'io_error';
+    path: string;
+    message: string;
+};

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

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

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

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

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 };