@quantiya/codevibe-core 2.0.6 → 2.0.7

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

@@ -1,7 +1,38 @@
+import { PassThrough } from "node:stream";
 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";
+import { type RefreshTransport } from "./oauth-refresh";
+import { OAuthAccountLock } from "./oauth-account-lock";
+import { type BrokerHandled, type BrokerRequest, type BrokerResponse, type BrokerToken, type ModelGatewayBroker, type ResponseSink, type UpstreamClient, type VendorKeyStore, type VendorOAuthBundle, type VendorProvider } from "./types";
+/**
+ * PHASE-643 §3.3 — the streaming STALL meter: a `PassThrough`-derived stage that
+ * OWNS the idle timer (there is NO outer timer variable — agy R5, eliminating
+ * the stale-reference leak structurally). It ARMS the timer at construction,
+ * RE-ARMS it per chunk, calls `onIdle()` (→ `reg.controller.abort()`) on fire,
+ * and DISARMS it in `_destroy()`.
+ *
+ * Arm-order pin (Stage-1 v10): the timer arms LAZILY in `_construct` — which
+ * Node invokes AFTER `new IdleMeter(...)` has returned and been assigned to
+ * `meter` — so a constructor throw could never leave an armed timer that
+ * `meter?.destroy()` cannot reach. `autoDestroy` is pinned `true` (the Node
+ * default; pipeline explicitly skips destroying naturally-completed streams, so
+ * `autoDestroy` is what runs `_destroy` — and thus disarms the timer — on a
+ * successful stream), guaranteeing no timer survives a completed stream and no
+ * spurious late abort can fire.
+ */
+export declare class IdleMeter extends PassThrough {
+    private readonly idleMs;
+    private readonly onIdle;
+    private idleTimer;
+    private disarmed;
+    constructor(idleMs: number, onIdle: () => void);
+    _construct(callback: (err?: Error | null) => void): void;
+    _transform(chunk: unknown, _enc: BufferEncoding, cb: (err?: Error | null, data?: unknown) => void): void;
+    _destroy(err: Error | null, cb: (err?: Error | null) => void): void;
+    private arm;
+    private disarm;
+}
 /**
  * Construction-time dependencies. All injectable so W1 unit-tests run
  * against stubs (no network, deterministic audit ACKs). Defaults wire the
@@ -18,7 +49,38 @@ export interface BrokerDeps {
     vendorKeyStore?: VendorKeyStore;
     /** Strict audit sink (defaults to the in-memory stub until W3, §3.5). */
     auditSink?: StrictAuditSink;
+    /**
+     * PHASE-626 §5 — the C4 refresh transport (token endpoint). Defaults to the
+     * hardened `FetchRefreshTransport`. Injected as a stub in tests.
+     */
+    refreshTransport?: RefreshTransport;
+    /**
+     * PHASE-626 §5 — the cross-process OAuth-account lock for the (single) C4
+     * provider `openai`. Defaults to the portable `mkdir`-lock at
+     * `defaultOAuthLockDir("vendor-oauth-openai")`. Injected in tests.
+     */
+    oauthLock?: OAuthAccountLock;
+    /** Proactive-refresh age threshold (ms). Test override. */
+    proactiveRefreshThresholdMs?: number;
+    /** stop() bounded-drain timeout (ms). Test override. */
+    stopDrainTimeoutMs?: number;
+    /** Injectable clock/delay for the stop drain (tests). */
+    now?: () => number;
+    delay?: (ms: number) => Promise<void>;
 }
+/**
+ * LOCAL-ONLY diagnostic shape of a non-200 upstream body. Upstream error
+ * bodies are UNTRUSTED and can carry credential material in ANY string —
+ * including inside the canonical `error.message`/`type`/`code` fields (a bare
+ * JWT matches no I2 pattern; Stage-2 r3 empirically refuted the
+ * scrub-the-allow-listed-values variant) — so ZERO upstream-controlled bytes
+ * may reach the logger. Reports structure only: which canonical error fields
+ * exist (key names come from OUR constant list, never the body) and their
+ * byte lengths. Own-property reads only (the W1 R3 prototype-pollution
+ * class). Cannot throw: no upstream value is ever serialized or traversed
+ * beyond one fixed level.
+ */
+export declare function upstreamErrorShape(body: unknown): Record<string, unknown> | undefined;
 /**
  * The local model-gateway broker (§3.2). One per session on
  * `127.0.0.1:<ephemeral>`. Holds the upstream credential in-process only
@@ -35,12 +97,34 @@ export declare class LocalModelGatewayBroker implements ModelGatewayBroker, Vend
     private readonly brokerId;
     private server;
     private boundAddr;
-    /** In-process cache of upstream vendor keys (zeroized on stop()). */
+    /** In-process cache of the resolved upstream credential (zeroized on stop()). */
     private upstreamKeys;
     /** Latest `credential_issuance_id` per provider (for the model_call FK). */
     private issuanceIds;
     private issuanceCounter;
+    private readonly refreshTransport;
+    private oauthLock;
+    private readonly proactiveThresholdMs;
+    private readonly stopDrainTimeoutMs;
+    private readonly nowFn;
+    private readonly delayFn;
+    /**
+     * Per-provider credential generation (§5) — advances on EVERY self-refresh
+     * AND on adopting a sibling's persisted bundle. A 401 issued under an older
+     * generation retries on the current credential WITHOUT re-refreshing.
+     */
+    private credentialGeneration;
+    /** Intra-instance single-flight: one in-flight refresh per provider. */
+    private inflightRefresh;
+    /** STOPPING gate — reject new gateway work once set. */
+    private stopping;
+    /** Monotonic lifecycle generation `stop()` bumps (straggler no-op guard). */
+    private lifecycleGeneration;
+    /** Registered in-flight credential-bearing outer ops. */
+    private readonly ops;
     constructor(deps: BrokerDeps);
+    /** Lazily resolve the OAuth-account lock for the (only) C4 provider `openai`. */
+    private getOAuthLock;
     /**
      * 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>`.
@@ -53,8 +137,29 @@ export declare class LocalModelGatewayBroker implements ModelGatewayBroker, Vend
     /**
      * Tear down: close the HTTP server, ZEROIZE the in-process upstream
      * credentials, and clear the broker token. Idempotent.
+     *
+     * PHASE-626 §5 stop lifecycle (Stage-2 R1/R2/R3/R4 Codex): today's naive
+     * "clear the map immediately" lets an in-flight keychain load or refresh
+     * completing AFTER `stop()` silently REPOPULATE credentials post-stop. The
+     * new lifecycle: (1) enter STOPPING (reject new work) + bump the lifecycle
+     * generation so any straggler resuming post-stop aborts as a no-op; (2) await
+     * a BOUNDED drain of in-flight credential-bearing ops; (3) ABORT every
+     * registered signal (cancels abortable inner ops: the model-forward fetch +
+     * refresh transport) AND await the SETTLEMENT of every registered outer task
+     * (non-cancellable host ops — keychain, `mkdir`-lock, audit-sink — are awaited
+     * to natural settlement, never falsely raced); (4) drop ALL credential +
+     * in-flight-promise references as the FINAL step.
      */
     stop(): Promise<void>;
+    /**
+     * Register an in-flight credential-bearing OUTER operation SYNCHRONOUSLY
+     * (before its first `await`) so `stop()` can abort + await it. Closes the
+     * started-but-unregistered pre-registration race.
+     */
+    private registerOp;
+    private deregisterOp;
+    /** True once `stop()` has bumped past the op's captured generation. */
+    private isStale;
     /** The current broker token (for the agent's apiKeyHelper bootstrap). */
     currentBrokerToken(): BrokerToken | null;
     /**
@@ -92,25 +197,104 @@ export declare class LocalModelGatewayBroker implements ModelGatewayBroker, Vend
     rollbackBrokerTokenRotation(handle?: RotationHandle): void;
     getVendorKey(provider: VendorProvider): Promise<string | null>;
     setVendorKey(provider: VendorProvider, key: string): Promise<void>;
+    clearVendorKey(provider: VendorProvider): Promise<boolean>;
+    getVendorOAuthBundle(provider: VendorProvider): Promise<VendorOAuthBundle | null>;
+    setVendorOAuthBundle(provider: VendorProvider, bundle: VendorOAuthBundle): Promise<void>;
+    clearVendorOAuthBundle(provider: VendorProvider): Promise<boolean>;
     /**
      * 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).
+     * table check first (everything else → 403), then local metadata/health,
+     * then broker-token auth on the two model 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>;
+    handle(req: BrokerRequest, sink: ResponseSink): Promise<BrokerResponse | BrokerHandled>;
+    /**
+     * The credential-bearing OUTER operation (§5 stop lifecycle). Registers on
+     * the op-registry SYNCHRONOUSLY (before its first `await`), then runs the
+     * gateway body with the registration's abort signal + captured lifecycle
+     * generation, and deregisters in `finally`.
+     */
     private gateway;
+    private gatewayInner;
+    /**
+     * PHASE-643 §3.3 — the in-scope streaming write for a 200 `text/event-stream`
+     * forward. Runs INSIDE the op scope (the op stays in `this.ops` across the
+     * stream → `stop()` phase-3 settles). Pipes the upstream body incrementally
+     * into the caller-provided sink, byte-for-byte, forwarding ONLY `content-type`.
+     *
+     * Teardown principle (R6): NO ownership tracking — a resolving `pipeline()` does
+     * NOT prove it adopted the stages (a setup-time rejection, e.g.
+     * `ERR_STREAM_UNABLE_TO_PIPE` on an already-destroyed sink, leaves BOTH the
+     * source AND the meter live). The unified catch UNCONDITIONALLY + IDEMPOTENTLY
+     * tears down EVERY broker-allocated stage — `meter?.destroy()` (disarms its
+     * armed idle timer via `_destroy`) FIRST (Stage-2 R6 Codex MED, empirically
+     * reproduced on Node ≥22), then a guarded `source` destroy-before-abort with a
+     * no-op `'error'` listener (§5.1-D), then `reg.controller.abort()` — on ANY
+     * throw OR pipeline rejection in steps 1–3, whether or not the pipeline was
+     * invoked or already destroyed the stages. A missed teardown would leave a live
+     * credential-bearing fetch (or an armed ref'd timer) that `stop()` can no longer
+     * reach after op deregister.
+     */
+    private streamForward;
     /**
-     * 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.
+     * Build the upstream `{url, headers}` for a resolved credential (§5). For an
+     * `oauth_bundle` (C4) the URL is OVERRIDDEN to the ChatGPT config and its
+     * synthesized headers (originator / User-Agent) are merged over the openai
+     * canonical headers; the credential headers add `Authorization: Bearer` +
+     * `ChatGPT-Account-Id`. For C1/C2/C3 the canonical URL + the C2-beta synthesis
+     * are preserved unchanged.
      */
-    private loadVendorKey;
+    private buildUpstreamTarget;
+    /**
+     * Load the vendor credential (class-discriminated + precedence), caching it
+     * in-process, and emit `broker_credential_loaded` (§3.5) — with a
+     * `key_fingerprint` (sha256 prefix over the class-appropriate string; for an
+     * oauth_bundle the `refresh_token`) and a fresh `credential_issuance_id`,
+     * NEVER the raw credential.
+     *
+     * Precedence (§5): C1/C2/C3 (`vendor-key-<provider>`) WINS over a C4
+     * `vendor-oauth-openai` bundle. Explicit key wins; no config knob.
+     */
+    private loadVendorCredential;
+    private genOf;
+    private currentBundle;
+    /** Is the C4 bundle's `last_refresh` older than the proactive threshold? */
+    private isProactiveDue;
+    /**
+     * Adopt a bundle into the in-process cache AND advance the local credential
+     * generation (§5 — adoption is treated identically to a self-refresh, so a
+     * stale-generation 401 recognizes the rotation and does not re-rotate).
+     * Respects the lifecycle guard: never repopulates a cleared cache post-stop.
+     */
+    private adoptBundle;
+    /**
+     * Ensure a fresh C4 access token via single-flight + the cross-broker lock.
+     * `mode` distinguishes reactive (post-401 — a transient failure fails the
+     * call closed) from proactive (token still valid — a transient failure keeps
+     * serving the current token). `usedGen` (reactive only) is the generation the
+     * failed request rode: a 401 older than the current generation retries on the
+     * CURRENT credential WITHOUT refreshing (staggered-stale-401 guard).
+     */
+    private refreshOAuth;
+    /**
+     * The cross-broker critical section (§5): acquire the OAuth-account lock →
+     * RE-READ the persisted bundle under the lock → compare-and-skip on
+     * `access_token` identity → refresh via the token endpoint → reassert
+     * ownership → whole-bundle write-through → advance generation → release.
+     * The single-flight promise resolves only AFTER persist + cache update.
+     */
+    private doRefreshUnderLock;
     private lastIssuanceId;
+    /**
+     * The user-visible remediation response for a PERMANENT (`invalid_grant`) C4
+     * refresh failure — the refresh token is dead, so no in-broker recovery is
+     * possible and the user must re-import (§5 failure classification + remediation
+     * scoping). Shared by BOTH the reactive (post-401) and proactive refresh paths
+     * so the surfaced instruction cannot drift.
+     */
+    private permanentRefreshResponse;
     /**
      * 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

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

@@ -0,0 +1,40 @@
+/** The C4 ChatGPT-subscription upstream wire facts (LIVE-PINNED, §13 OQ-1). */
+export interface ChatGptUpstreamConfig {
+    /** ChatGPT backend origin the C4 Bearer forwards to (origin confinement target). */
+    readonly upstreamBaseUrl: string;
+    /** The Responses route appended to the base for `/v1/responses`-shaped calls. */
+    readonly upstreamPath: string;
+    /**
+     * Headers the broker SYNTHESIZES on EVERY C4 upstream call (NOT agent-
+     * supplied — the canonical constructor drops all agent headers). These are
+     * broker-owned constants; the credential-derived `ChatGPT-Account-Id` +
+     * `Authorization` are added separately by `credentialHeaders` (they depend
+     * on the resolved bundle).
+     */
+    readonly synthesizedHeaders: Readonly<Record<string, string>>;
+    /**
+     * PHASE-643-B §7 (v11) — pinned WIRE FACT: the real chatgpt.com Responses
+     * endpoint returns `200` + a genuine SSE body with NO `Content-Type` header at
+     * all (probe-proven 2026-07-21 — Cloudflare-fronted, `Transfer-Encoding:
+     * chunked`, no content-type either with or without an `Accept` header). So a
+     * `200` with an ABSENT/empty content-type on THIS endpoint must be STREAMED as
+     * SSE, not buffered. This is per-endpoint pinned knowledge (same class as the
+     * `originator`/UA pins), NOT body-sniffing and NOT `Accept` synthesis. Only the
+     * flagged (C4/oauth_bundle chatgpt) target sets it; declared non-SSE 200s
+     * (`application/json`) on this target STILL buffer.
+     */
+    readonly assumeSseOn200: boolean;
+}
+export declare const CHATGPT_UPSTREAM_CONFIG: ChatGptUpstreamConfig;
+/** The full pinned C4 model-forward URL (`{base}{route}`). */
+export declare function chatGptUpstreamUrl(): string;
+/** OAuth token-refresh endpoint (LIVE-PINNED). */
+export declare const CHATGPT_TOKEN_ENDPOINT = "https://auth.openai.com/oauth/token";
+/** Public OAuth client_id for the refresh grant (LIVE-PINNED). */
+export declare const CHATGPT_OAUTH_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+/**
+ * The request content type for the refresh grant. The body is
+ * `grant_type=refresh_token&refresh_token=…&client_id=…` (§5), so it is a
+ * standard OAuth2 form-encoded token request.
+ */
+export declare const CHATGPT_REFRESH_CONTENT_TYPE = "application/x-www-form-urlencoded";

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

@@ -1,4 +1,4 @@
-export type { VendorProvider, BrokerRouteMethod, BrokerRoute, BrokerStatus, BrokerRequest, BrokerResponse, ModelGatewayBroker, VendorKeyStore, BrokerToken, UpstreamResponse, UpstreamClient, } from "./types";
+export type { VendorProvider, BrokerRouteMethod, BrokerRoute, BrokerStatus, BrokerRequest, BrokerResponse, BrokerHandled, ResponseSink, ModelGatewayBroker, VendorKeyStore, VendorOAuthBundle, ResolvedCredential, BrokerToken, UpstreamResult, UpstreamResponse, UpstreamClient, } from "./types";
 export { BROKER_ROUTES } from "./types";
 export { LocalModelGatewayBroker } from "./broker";
 export type { BrokerDeps } from "./broker";
@@ -7,6 +7,9 @@ export type { StrictAuditSink, AuditKindCp7, RecordedAuditEmit } from "./audit-s
 export { StubStrictAuditSink } from "./audit-sink";
 export { KeychainVendorKeyStore } from "./vendor-key-store";
 export { BrokerTokenMinter, type RotationHandle } from "./broker-token";
+export { CHATGPT_UPSTREAM_CONFIG, chatGptUpstreamUrl, CHATGPT_TOKEN_ENDPOINT, CHATGPT_OAUTH_CLIENT_ID, CHATGPT_REFRESH_CONTENT_TYPE, } from "./chatgpt-config";
+export { FetchRefreshTransport, refreshOAuthToken, buildRefreshBody, type RefreshTransport, type RefreshOutcome, } from "./oauth-refresh";
+export { OAuthAccountLock, createOAuthAccountLock, defaultOAuthLockDir, type OAuthAccountLockOptions, type LockHandle, type LockOwner, } from "./oauth-account-lock";
 export { buildCanonicalRequest, selfCredentialGuard, requestSha256, CanonicalRejectError, } from "./canonical";
 export type { CanonicalInput, CanonicalRequest } from "./canonical";
 export { scrubRequestBody } from "./scrubber";

package/dist/credential-broker/oauth-account-lock.d.ts

@@ -0,0 +1,104 @@
+/** Liveness of a recorded lock owner (only `dead` is ever reclaimed). */
+export type OwnerLiveness = "alive" | "dead" | "unknown";
+/** The `owner.json` record written once per acquisition. */
+export interface LockOwner {
+    pid: number;
+    host: string;
+    /** Random per-ACQUISITION nonce — the fence for every destructive/heartbeat op. */
+    ownerId: string;
+    /** Acquisition time (ISO), for diagnostics. */
+    startedAt: string;
+}
+export interface OAuthAccountLockOptions {
+    /** The canonical lockdir path (keyed to the OAuth account). */
+    lockDir: string;
+    /** Staleness TTL (» max critical-section time). Default 30s. */
+    ttlMs?: number;
+    /** Heartbeat interval (« TTL). Default 5s. */
+    heartbeatMs?: number;
+    /** Contention deadline. Default 60s. */
+    maxWaitMs?: number;
+    /** Base retry backoff. Default 25ms (capped 1s). */
+    backoffMs?: number;
+    now?: () => number;
+    delay?: (ms: number) => Promise<void>;
+    /** This process's pid (injectable for tests). */
+    pid?: number;
+    /** This host's id (injectable for tests). */
+    hostId?: string;
+    /** Liveness probe (injectable for tests). Default = same-host `process.kill(pid,0)`. */
+    isProcessAlive?: (pid: number, host: string) => OwnerLiveness;
+    /** Per-acquisition nonce generator (injectable for tests). */
+    randomId?: () => string;
+    /** `utimes(lockdir)` heartbeat op (injectable so tests can observe/spy). */
+    utimesFn?: (dir: string) => Promise<void>;
+    /** Disable the auto-interval heartbeat (tests drive ticks manually). */
+    disableAutoHeartbeat?: boolean;
+}
+/** A held lock. `release` is one-shot + idempotent. */
+export interface LockHandle {
+    readonly ownerId: string;
+    /**
+     * Reassert-before-mutation (§5 primary revocation-wins backstop): re-read the
+     * canonical `owner.json` and return true iff `ownerId === ours`. The broker
+     * calls this IMMEDIATELY before EVERY keychain `setPassword`/`deletePassword`,
+     * aborting fail-closed on a false result — independently defeating any
+     * displacement that COMPLETED before the re-read.
+     */
+    reassertOwnership(): Promise<boolean>;
+    /** One-shot release: cancel+join heartbeat, then unlink+rmdir under `ownerId` re-assert. */
+    release(): Promise<void>;
+    /** TEST-ONLY: run one heartbeat tick synchronously (simulates a queued `utimes`). */
+    _tickForTest(): Promise<void>;
+}
+/** The portable cross-process OAuth-account lock (§5 / AMEND-1). */
+export declare class OAuthAccountLock {
+    private readonly lockDir;
+    private readonly ownerFile;
+    private readonly reclaimGuardDir;
+    private readonly ttlMs;
+    private readonly heartbeatMs;
+    private readonly maxWaitMs;
+    private readonly backoffMs;
+    private readonly now;
+    private readonly delayFn;
+    private readonly pid;
+    private readonly hostId;
+    private readonly isProcessAlive;
+    private readonly randomId;
+    private readonly utimesFn;
+    private readonly disableAutoHeartbeat;
+    constructor(opts: OAuthAccountLockOptions);
+    /**
+     * Acquire the lock (bounded by `maxWaitMs`). Resolves a {@link LockHandle} on
+     * success; REJECTS fail-closed on: an unwritable lockdir root, a contention
+     * timeout (live/ambiguous/ownerless holder), or a dead/stranded reclaim guard.
+     * ZERO side effects on the persisted bundle on any fail-closed path.
+     */
+    acquire(): Promise<LockHandle>;
+    /** Whether the EXISTING lockdir holder is reclaimable (dead), or must be waited on. */
+    private classifyExistingHolder;
+    /**
+     * Reclaim a stale, provably-dead lockdir under the SEPARATE reclaim guard.
+     * Returns a fresh {@link LockHandle} on success, or `null` if the reclaim was
+     * aborted (a sibling already reclaimed, or the guard is held). Throws only if
+     * the guard is dead/stranded (fail-closed → offline cleanup).
+     */
+    private tryReclaim;
+    /** Write `owner.json`, start the heartbeat, and build the handle. */
+    private onAcquired;
+    private tryMkdir;
+    private readOwner;
+    private lockDirAge;
+    private removeStaleDir;
+    private rmdirQuiet;
+    private backoff;
+}
+/**
+ * Default lockdir path for a provider's OAuth account — a stable per-host path
+ * under `~/.codevibe/locks/` (all C4 brokers are same-host, so a shared
+ * filesystem path gives cross-process exclusion). NOT under the substrate
+ * mount (I1) — this is host-side broker coordination only.
+ */
+export declare function defaultOAuthLockDir(account: string): string;
+export declare function createOAuthAccountLock(opts: OAuthAccountLockOptions): OAuthAccountLock;

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

@@ -0,0 +1,72 @@
+import type { VendorOAuthBundle } from "./types";
+/**
+ * The injected refresh transport (§5). Separate from the model `UpstreamClient`
+ * (different content type, form body, token endpoint). Widened to accept an
+ * optional `signal` (the stop-lifecycle end-to-end cancellation contract).
+ * Resolves `{status, rawBody, contentType}`; REJECTS only on a transport error
+ * OR a 3xx redirect (redirect confinement).
+ */
+export interface RefreshTransport {
+    post(args: {
+        url: string;
+        body: string;
+        contentType: string;
+        signal?: AbortSignal;
+    }): Promise<RefreshTransportResponse>;
+}
+export interface RefreshTransportResponse {
+    status: number;
+    /** Raw response text (bounded); parsed by the classifier, NEVER logged. */
+    rawBody: string;
+    /** Lowercased response `content-type`, if any. */
+    contentType?: string;
+    /**
+     * True iff the body exceeded the bounded-read cap and was NOT materialized
+     * (transport streamed at most the cap + cancelled). The classifier treats an
+     * oversized body as transient WITHOUT parsing (it was never fully read).
+     */
+    oversized?: boolean;
+}
+/** The outcome of a refresh attempt — drives the reactive/proactive posture. */
+export type RefreshOutcome = {
+    kind: "rotated";
+    bundle: VendorOAuthBundle;
+} | {
+    kind: "permanent";
+    reason: string;
+} | {
+    kind: "transient";
+    reason: string;
+};
+/**
+ * The production fetch-backed {@link RefreshTransport}. Mirrors
+ * `FetchUpstreamClient`'s hardened posture for the NEW secret surface.
+ */
+export declare class FetchRefreshTransport implements RefreshTransport {
+    private readonly opts;
+    constructor(opts?: {
+        fetchFn?: typeof fetch;
+        timeoutMs?: number;
+    });
+    post(args: {
+        url: string;
+        body: string;
+        contentType: string;
+        signal?: AbortSignal;
+    }): Promise<RefreshTransportResponse>;
+}
+/** Build the OAuth2 refresh-grant form body (`refresh_token` is a secret). */
+export declare function buildRefreshBody(refreshToken: string): string;
+/**
+ * Perform ONE token refresh against the pinned endpoint and classify the
+ * result. On success returns a `rotated` bundle that already applies the §5
+ * write-through merge rule (`refresh_token`/`id_token` ?? current;
+ * `account_id` from current; `last_refresh` = now) — persistence + cache +
+ * generation advance are the caller's job (under the cross-broker lock).
+ *
+ * `now` supplies the `last_refresh` timestamp (injectable for tests).
+ */
+export declare function refreshOAuthToken(current: VendorOAuthBundle, transport: RefreshTransport, opts?: {
+    signal?: AbortSignal;
+    now?: () => Date;
+}): Promise<RefreshOutcome>;