@omnicross/contracts 0.1.1 → 0.1.3

package/dist/account-tokens-types.d.cts

@@ -9,6 +9,45 @@ import { OpenCodeGoTokenConfig } from './subscription-types.cjs';
  * sanitized shapes, and the OAuth exchange request types.
  */
 
+/**
+ * Upstream proxy descriptor (upstream-proxy). Routes an outbound upstream call
+ * through an http/https or socks5 proxy. Two interchangeable shapes:
+ *  - `{ url }`      — a full proxy URL, e.g. `http://user:pass@host:1080` or
+ *                     `socks5://host:1080` (userinfo carries basic-auth).
+ *  - structured     — an explicit `{ type, host, port, username?, password? }`.
+ *
+ * `username`/`password` are SECRETS: encrypted at rest via the same envelope as
+ * other credentials, masked in every sanitized/admin view, and never logged
+ * (logs carry at most `host:port`). Additive everywhere it appears — absent ⇒ a
+ * direct (non-proxied) call, byte-identical to before proxy support.
+ */
+type ProxyConfig = {
+    url: string;
+} | {
+    type: 'http' | 'https' | 'socks5';
+    host: string;
+    port: number;
+    username?: string;
+    password?: string;
+};
+/**
+ * Persisted per-account client identity (subscription-client-fingerprint #7, P2).
+ * The frozen fingerprint headers a real Claude Code client sent for this account,
+ * captured + replayed so relayed traffic presents a stable identity across
+ * restarts. NON-secret metadata: it holds ONLY whitelisted fingerprint headers
+ * (`x-stainless-*` / user-agent / anthropic-beta / x-app / CC headers) — NEVER
+ * `authorization` / `x-api-key` / `cookie` (excluded at capture AND at
+ * store-normalize). Additive + OPTIONAL — an existing `tokens.json` without it
+ * parses unchanged (the account re-captures from a real client). Because it is
+ * non-secret it lives on the entry OUTSIDE the encrypted `tokens` block and is
+ * not walked by the secrets encryptor.
+ */
+type AccountClientIdentity = {
+    /** The frozen fingerprint headers (lowercased keys; token/secret excluded). */
+    headers: Record<string, string>;
+    /** Epoch ms of the freeze / last TTL refresh. */
+    capturedAt: number;
+};
 /**
  * Authorization method (general)
  */
@@ -25,6 +64,18 @@ type SubscriptionLevel = 'Free' | 'Pro' | 'Max';
  * Token configuration status
  */
 type TokenStatus = 'unconfigured' | 'authorized' | 'configured' | 'expired' | 'error';
+/**
+ * Machine-readable credential-sync warning code (external-cli-sync).
+ *
+ * - `external-divergent`: the external CLI's native credential file (e.g.
+ *   `~/.claude/.credentials.json`) holds a DIFFERENT, fresher credential than
+ *   the stored account — the stored refresh token may have been rotated out.
+ * - `external-not-rotated`: a refresh failed and the external file holds the
+ *   SAME dead credential — a genuine revocation, re-login is required.
+ * - `duplicate-token`: two accounts of one provider share the same credential —
+ *   refreshing one will invalidate the other (single-use refresh tokens).
+ */
+type SyncWarningCode = 'external-divergent' | 'external-not-rotated' | 'duplicate-token';
 /**
  * Claude token configuration
  */
@@ -40,6 +91,9 @@ type ClaudeTokenConfig = {
     setupTokenExpiresAt?: string;
     lastRefreshedAt?: string;
     errorMessage?: string;
+    /** Persisted credential-sync warning (external-cli-sync); cleared on a
+     *  successful refresh / import. */
+    syncWarning?: SyncWarningCode;
 };
 /**
  * Codex (OpenAI) token configuration
@@ -56,6 +110,9 @@ type CodexTokenConfig = {
     organizationId?: string;
     lastRefreshedAt?: string;
     errorMessage?: string;
+    /** Persisted credential-sync warning (external-cli-sync); cleared on a
+     *  successful refresh / import. */
+    syncWarning?: SyncWarningCode;
 };
 /**
  * Gemini token configuration
@@ -84,6 +141,57 @@ type SubscriptionAccountEntry<TConfig> = {
     label?: string;
     /** ISO creation timestamp. */
     createdAt?: string;
+    /**
+     * Scheduling precedence in the account pool (subscription-account-scheduling).
+     * Lower = higher precedence; default `50` when absent (CRS `parseInt(x,10) || 50`
+     * parity). OPTIONAL — an existing `tokens.json` without it parses unchanged and
+     * every account defaults to 50.
+     */
+    priority?: number;
+    /**
+     * ISO timestamp of the last time this account was selected to serve a request
+     * (subscription-account-scheduling LRU tie-break input). OPTIONAL, best-effort
+     * throttled persist — the selector's in-memory overlay is the authoritative live
+     * value; an account without it sorts as least-recently-used (timestamp `0`).
+     */
+    lastUsedAt?: string;
+    /**
+     * Per-account upstream proxy override (upstream-proxy). When set, this
+     * account's relay + OAuth-refresh traffic is routed through this proxy,
+     * WINNING over the per-provider and global proxy layers. OPTIONAL — an
+     * existing `tokens.json` without it parses unchanged (no proxy → direct). Its
+     * `password` is a secret: encrypted at rest by the tokens `SecretBox` walker
+     * and masked in the sanitized view.
+     */
+    proxy?: ProxyConfig;
+    /**
+     * Per-account model support + logical→actual remap (subscription-account-model-map).
+     * CRS dual-format, OPTIONAL — an existing `tokens.json` without it parses
+     * unchanged (the account supports every model and never remaps, byte-identical
+     * to before this change):
+     *  - **array** `["a","b"]` — an ALLOW-LIST: the account supports ONLY these
+     *    logical models (skip-only, no remap). In a ≥2-account pool the account is
+     *    routed AROUND for any other model.
+     *  - **object** `{ "a": "X", "b": "Y" }` — the keys are the same allow-list AND
+     *    each value is the account's ACTUAL upstream model, so a selected account
+     *    remaps the logical model to its actual model on the outbound request.
+     *
+     * Model-support filtering only applies when the provider has ≥2 accounts (the
+     * same gate as account health) — a sole account is never model-gated
+     * (never-strand; the upstream stays authoritative). A sole account that must
+     * serve a logical model AS a different actual model uses the OBJECT map (remap),
+     * not skip.
+     */
+    supportedModels?: string[] | Record<string, string>;
+    /**
+     * Persisted per-account client fingerprint identity (subscription-client-
+     * fingerprint #7, P2). OPTIONAL, additive, NON-secret metadata (kept OUTSIDE the
+     * encrypted `tokens` block) — an existing `tokens.json` without it parses
+     * unchanged. Written through by the daemon on a first-seen freeze / TTL refresh;
+     * seeded back into the in-memory identity store at boot so a claude account's
+     * replayed identity survives restart.
+     */
+    identity?: AccountClientIdentity;
     /** The provider's existing token config, verbatim. */
     tokens: TConfig;
 };
@@ -110,6 +218,22 @@ type AccountTokensConfig = {
     activeOpencodegoAccountId?: string;
     updatedAt: string;
 };
+/**
+ * Secret-free view of a per-account/global/provider proxy (upstream-proxy). The
+ * password is NEVER carried — only a `hasPassword` presence flag plus a
+ * display-safe `host:port` endpoint (userinfo stripped). Rendered in the admin
+ * accounts view.
+ */
+type SanitizedProxyConfig = {
+    /** `'url'` when configured via a full URL, else the structured proxy type. */
+    kind: 'url' | 'http' | 'https' | 'socks5';
+    /** Display-safe `host:port` (parsed from a url form; userinfo stripped). */
+    endpoint?: string;
+    /** Optional non-secret username (for display); the password is never returned. */
+    username?: string;
+    /** Whether a proxy password is set. The password value itself never leaves. */
+    hasPassword: boolean;
+};
 /**
  * Sanitized view of a single subscription account (frontend display).
  * NEVER carries raw token material (no accessToken/refreshToken/idToken/apiKey).
@@ -125,6 +249,62 @@ type SubscriptionAccountSanitized = {
     isSetupToken?: boolean;
     hasAccessToken: boolean;
     isActive: boolean;
+    /**
+     * Scheduling precedence (subscription-account-scheduling) — editable in the
+     * admin accounts view so an operator can order a pool. Absent ⇒ default 50.
+     */
+    priority?: number;
+    /**
+     * ISO timestamp of the last scheduler selection (display-only in the admin
+     * accounts view). Absent ⇒ never selected (or the best-effort persist has not
+     * yet flushed).
+     */
+    lastUsedAt?: string;
+    /**
+     * Credential-sync warning for this account (external-cli-sync). Carries the
+     * persisted code when one was recorded by a failed refresh, plus the
+     * list-time computed codes (`external-divergent` / `duplicate-token`).
+     */
+    syncWarning?: SyncWarningCode;
+    /**
+     * Live scheduling-health state (subscription-account-health) — in-memory, never
+     * persisted. Absent / `'healthy'` ⇒ eligible; the rest mean the account is
+     * currently excluded from the pool (multi-account) or would surface the
+     * upstream's error (single-account). Secret-free.
+     */
+    health?: 'healthy' | 'rate_limited' | 'overloaded' | 'transient' | 'blocked';
+    /**
+     * ISO instant the current health cooldown elapses (absent for healthy /
+     * permanently-blocked). Lets the admin view render "rate-limited until …".
+     */
+    cooldownUntil?: string;
+    /**
+     * Secret-free view of this account's proxy override (upstream-proxy). Absent ⇒
+     * no per-account proxy configured. The password is masked to a `hasPassword`
+     * flag — never returned.
+     */
+    proxy?: SanitizedProxyConfig;
+    /**
+     * Per-account model support / logical→actual remap (subscription-account-model-map)
+     * — editable in the admin accounts view. Carried verbatim (secret-free — model
+     * ids are not token material): an array allow-list or an object logical→actual
+     * map. Absent ⇒ the account supports every model with no remap.
+     */
+    supportedModels?: string[] | Record<string, string>;
+    /**
+     * COARSE client-fingerprint status (subscription-client-fingerprint #7, D7) —
+     * whether THIS account has a captured/frozen client identity in the in-memory
+     * store. Present only when fingerprint replay is ENABLED (else absent ⇒ the UI
+     * shows nothing). Secret-free by construction: it is a BOOLEAN only — the raw
+     * captured headers are NEVER surfaced here (nor in any admin view).
+     */
+    identityCaptured?: boolean;
+    /**
+     * ISO instant this account's fingerprint identity was frozen / last TTL-refreshed
+     * (subscription-client-fingerprint #7, D7). Present only alongside
+     * `identityCaptured === true`. Coarse timestamp only — never the headers.
+     */
+    identityCapturedAt?: string;
 };
 /**
  * OAuth authorization parameters
@@ -143,4 +323,4 @@ type TokenExchangeRequest = {
     state: string;
 };
 
-export type { AccountTokensConfig, AuthMethod, ClaudeAuthMethod, ClaudeTokenConfig, CodexTokenConfig, GeminiTokenConfig, OAuthParams, SubscriptionAccountEntry, SubscriptionAccountSanitized, SubscriptionLevel, TokenExchangeRequest, TokenStatus };
+export type { AccountClientIdentity, AccountTokensConfig, AuthMethod, ClaudeAuthMethod, ClaudeTokenConfig, CodexTokenConfig, GeminiTokenConfig, OAuthParams, ProxyConfig, SanitizedProxyConfig, SubscriptionAccountEntry, SubscriptionAccountSanitized, SubscriptionLevel, SyncWarningCode, TokenExchangeRequest, TokenStatus };

package/dist/account-tokens-types.d.ts

@@ -9,6 +9,45 @@ import { OpenCodeGoTokenConfig } from './subscription-types.js';
  * sanitized shapes, and the OAuth exchange request types.
  */
 
+/**
+ * Upstream proxy descriptor (upstream-proxy). Routes an outbound upstream call
+ * through an http/https or socks5 proxy. Two interchangeable shapes:
+ *  - `{ url }`      — a full proxy URL, e.g. `http://user:pass@host:1080` or
+ *                     `socks5://host:1080` (userinfo carries basic-auth).
+ *  - structured     — an explicit `{ type, host, port, username?, password? }`.
+ *
+ * `username`/`password` are SECRETS: encrypted at rest via the same envelope as
+ * other credentials, masked in every sanitized/admin view, and never logged
+ * (logs carry at most `host:port`). Additive everywhere it appears — absent ⇒ a
+ * direct (non-proxied) call, byte-identical to before proxy support.
+ */
+type ProxyConfig = {
+    url: string;
+} | {
+    type: 'http' | 'https' | 'socks5';
+    host: string;
+    port: number;
+    username?: string;
+    password?: string;
+};
+/**
+ * Persisted per-account client identity (subscription-client-fingerprint #7, P2).
+ * The frozen fingerprint headers a real Claude Code client sent for this account,
+ * captured + replayed so relayed traffic presents a stable identity across
+ * restarts. NON-secret metadata: it holds ONLY whitelisted fingerprint headers
+ * (`x-stainless-*` / user-agent / anthropic-beta / x-app / CC headers) — NEVER
+ * `authorization` / `x-api-key` / `cookie` (excluded at capture AND at
+ * store-normalize). Additive + OPTIONAL — an existing `tokens.json` without it
+ * parses unchanged (the account re-captures from a real client). Because it is
+ * non-secret it lives on the entry OUTSIDE the encrypted `tokens` block and is
+ * not walked by the secrets encryptor.
+ */
+type AccountClientIdentity = {
+    /** The frozen fingerprint headers (lowercased keys; token/secret excluded). */
+    headers: Record<string, string>;
+    /** Epoch ms of the freeze / last TTL refresh. */
+    capturedAt: number;
+};
 /**
  * Authorization method (general)
  */
@@ -25,6 +64,18 @@ type SubscriptionLevel = 'Free' | 'Pro' | 'Max';
  * Token configuration status
  */
 type TokenStatus = 'unconfigured' | 'authorized' | 'configured' | 'expired' | 'error';
+/**
+ * Machine-readable credential-sync warning code (external-cli-sync).
+ *
+ * - `external-divergent`: the external CLI's native credential file (e.g.
+ *   `~/.claude/.credentials.json`) holds a DIFFERENT, fresher credential than
+ *   the stored account — the stored refresh token may have been rotated out.
+ * - `external-not-rotated`: a refresh failed and the external file holds the
+ *   SAME dead credential — a genuine revocation, re-login is required.
+ * - `duplicate-token`: two accounts of one provider share the same credential —
+ *   refreshing one will invalidate the other (single-use refresh tokens).
+ */
+type SyncWarningCode = 'external-divergent' | 'external-not-rotated' | 'duplicate-token';
 /**
  * Claude token configuration
  */
@@ -40,6 +91,9 @@ type ClaudeTokenConfig = {
     setupTokenExpiresAt?: string;
     lastRefreshedAt?: string;
     errorMessage?: string;
+    /** Persisted credential-sync warning (external-cli-sync); cleared on a
+     *  successful refresh / import. */
+    syncWarning?: SyncWarningCode;
 };
 /**
  * Codex (OpenAI) token configuration
@@ -56,6 +110,9 @@ type CodexTokenConfig = {
     organizationId?: string;
     lastRefreshedAt?: string;
     errorMessage?: string;
+    /** Persisted credential-sync warning (external-cli-sync); cleared on a
+     *  successful refresh / import. */
+    syncWarning?: SyncWarningCode;
 };
 /**
  * Gemini token configuration
@@ -84,6 +141,57 @@ type SubscriptionAccountEntry<TConfig> = {
     label?: string;
     /** ISO creation timestamp. */
     createdAt?: string;
+    /**
+     * Scheduling precedence in the account pool (subscription-account-scheduling).
+     * Lower = higher precedence; default `50` when absent (CRS `parseInt(x,10) || 50`
+     * parity). OPTIONAL — an existing `tokens.json` without it parses unchanged and
+     * every account defaults to 50.
+     */
+    priority?: number;
+    /**
+     * ISO timestamp of the last time this account was selected to serve a request
+     * (subscription-account-scheduling LRU tie-break input). OPTIONAL, best-effort
+     * throttled persist — the selector's in-memory overlay is the authoritative live
+     * value; an account without it sorts as least-recently-used (timestamp `0`).
+     */
+    lastUsedAt?: string;
+    /**
+     * Per-account upstream proxy override (upstream-proxy). When set, this
+     * account's relay + OAuth-refresh traffic is routed through this proxy,
+     * WINNING over the per-provider and global proxy layers. OPTIONAL — an
+     * existing `tokens.json` without it parses unchanged (no proxy → direct). Its
+     * `password` is a secret: encrypted at rest by the tokens `SecretBox` walker
+     * and masked in the sanitized view.
+     */
+    proxy?: ProxyConfig;
+    /**
+     * Per-account model support + logical→actual remap (subscription-account-model-map).
+     * CRS dual-format, OPTIONAL — an existing `tokens.json` without it parses
+     * unchanged (the account supports every model and never remaps, byte-identical
+     * to before this change):
+     *  - **array** `["a","b"]` — an ALLOW-LIST: the account supports ONLY these
+     *    logical models (skip-only, no remap). In a ≥2-account pool the account is
+     *    routed AROUND for any other model.
+     *  - **object** `{ "a": "X", "b": "Y" }` — the keys are the same allow-list AND
+     *    each value is the account's ACTUAL upstream model, so a selected account
+     *    remaps the logical model to its actual model on the outbound request.
+     *
+     * Model-support filtering only applies when the provider has ≥2 accounts (the
+     * same gate as account health) — a sole account is never model-gated
+     * (never-strand; the upstream stays authoritative). A sole account that must
+     * serve a logical model AS a different actual model uses the OBJECT map (remap),
+     * not skip.
+     */
+    supportedModels?: string[] | Record<string, string>;
+    /**
+     * Persisted per-account client fingerprint identity (subscription-client-
+     * fingerprint #7, P2). OPTIONAL, additive, NON-secret metadata (kept OUTSIDE the
+     * encrypted `tokens` block) — an existing `tokens.json` without it parses
+     * unchanged. Written through by the daemon on a first-seen freeze / TTL refresh;
+     * seeded back into the in-memory identity store at boot so a claude account's
+     * replayed identity survives restart.
+     */
+    identity?: AccountClientIdentity;
     /** The provider's existing token config, verbatim. */
     tokens: TConfig;
 };
@@ -110,6 +218,22 @@ type AccountTokensConfig = {
     activeOpencodegoAccountId?: string;
     updatedAt: string;
 };
+/**
+ * Secret-free view of a per-account/global/provider proxy (upstream-proxy). The
+ * password is NEVER carried — only a `hasPassword` presence flag plus a
+ * display-safe `host:port` endpoint (userinfo stripped). Rendered in the admin
+ * accounts view.
+ */
+type SanitizedProxyConfig = {
+    /** `'url'` when configured via a full URL, else the structured proxy type. */
+    kind: 'url' | 'http' | 'https' | 'socks5';
+    /** Display-safe `host:port` (parsed from a url form; userinfo stripped). */
+    endpoint?: string;
+    /** Optional non-secret username (for display); the password is never returned. */
+    username?: string;
+    /** Whether a proxy password is set. The password value itself never leaves. */
+    hasPassword: boolean;
+};
 /**
  * Sanitized view of a single subscription account (frontend display).
  * NEVER carries raw token material (no accessToken/refreshToken/idToken/apiKey).
@@ -125,6 +249,62 @@ type SubscriptionAccountSanitized = {
     isSetupToken?: boolean;
     hasAccessToken: boolean;
     isActive: boolean;
+    /**
+     * Scheduling precedence (subscription-account-scheduling) — editable in the
+     * admin accounts view so an operator can order a pool. Absent ⇒ default 50.
+     */
+    priority?: number;
+    /**
+     * ISO timestamp of the last scheduler selection (display-only in the admin
+     * accounts view). Absent ⇒ never selected (or the best-effort persist has not
+     * yet flushed).
+     */
+    lastUsedAt?: string;
+    /**
+     * Credential-sync warning for this account (external-cli-sync). Carries the
+     * persisted code when one was recorded by a failed refresh, plus the
+     * list-time computed codes (`external-divergent` / `duplicate-token`).
+     */
+    syncWarning?: SyncWarningCode;
+    /**
+     * Live scheduling-health state (subscription-account-health) — in-memory, never
+     * persisted. Absent / `'healthy'` ⇒ eligible; the rest mean the account is
+     * currently excluded from the pool (multi-account) or would surface the
+     * upstream's error (single-account). Secret-free.
+     */
+    health?: 'healthy' | 'rate_limited' | 'overloaded' | 'transient' | 'blocked';
+    /**
+     * ISO instant the current health cooldown elapses (absent for healthy /
+     * permanently-blocked). Lets the admin view render "rate-limited until …".
+     */
+    cooldownUntil?: string;
+    /**
+     * Secret-free view of this account's proxy override (upstream-proxy). Absent ⇒
+     * no per-account proxy configured. The password is masked to a `hasPassword`
+     * flag — never returned.
+     */
+    proxy?: SanitizedProxyConfig;
+    /**
+     * Per-account model support / logical→actual remap (subscription-account-model-map)
+     * — editable in the admin accounts view. Carried verbatim (secret-free — model
+     * ids are not token material): an array allow-list or an object logical→actual
+     * map. Absent ⇒ the account supports every model with no remap.
+     */
+    supportedModels?: string[] | Record<string, string>;
+    /**
+     * COARSE client-fingerprint status (subscription-client-fingerprint #7, D7) —
+     * whether THIS account has a captured/frozen client identity in the in-memory
+     * store. Present only when fingerprint replay is ENABLED (else absent ⇒ the UI
+     * shows nothing). Secret-free by construction: it is a BOOLEAN only — the raw
+     * captured headers are NEVER surfaced here (nor in any admin view).
+     */
+    identityCaptured?: boolean;
+    /**
+     * ISO instant this account's fingerprint identity was frozen / last TTL-refreshed
+     * (subscription-client-fingerprint #7, D7). Present only alongside
+     * `identityCaptured === true`. Coarse timestamp only — never the headers.
+     */
+    identityCapturedAt?: string;
 };
 /**
  * OAuth authorization parameters
@@ -143,4 +323,4 @@ type TokenExchangeRequest = {
     state: string;
 };
 
-export type { AccountTokensConfig, AuthMethod, ClaudeAuthMethod, ClaudeTokenConfig, CodexTokenConfig, GeminiTokenConfig, OAuthParams, SubscriptionAccountEntry, SubscriptionAccountSanitized, SubscriptionLevel, TokenExchangeRequest, TokenStatus };
+export type { AccountClientIdentity, AccountTokensConfig, AuthMethod, ClaudeAuthMethod, ClaudeTokenConfig, CodexTokenConfig, GeminiTokenConfig, OAuthParams, ProxyConfig, SanitizedProxyConfig, SubscriptionAccountEntry, SubscriptionAccountSanitized, SubscriptionLevel, SyncWarningCode, TokenExchangeRequest, TokenStatus };

package/dist/audit-types.cjs

@@ -0,0 +1,36 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/audit-types.ts
+var audit_types_exports = {};
+__export(audit_types_exports, {
+  DEFAULT_AUDIT_CONFIG: () => DEFAULT_AUDIT_CONFIG
+});
+module.exports = __toCommonJS(audit_types_exports);
+var DEFAULT_AUDIT_CONFIG = {
+  enabled: false,
+  captureBodies: false,
+  maxBodyBytes: 8192,
+  retentionDays: 7,
+  trustForwardedFor: false
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_AUDIT_CONFIG
+});

package/dist/audit-types.d.cts

@@ -0,0 +1,98 @@
+/**
+ * Request-audit contracts (request-audit-log, design D1/D2).
+ *
+ * Two dependency-light shapes shared across the `@omnicross/*` packages:
+ *  - `AuditRecord` — the FROZEN per-request audit entry. It carries request
+ *    METADATA (who/where/when/status/latency/model) plus, ONLY when body capture
+ *    is explicitly enabled, a redacted+truncated request/response body snapshot.
+ *    It is SECRET-FREE BY CONSTRUCTION: it holds the outbound key ID (NEVER the
+ *    key material/hash), the client IP + user-agent (PII, hence the whole store
+ *    is authed-only + TTL-pruned), and NEVER a token, Authorization header, or
+ *    api-key header value (request headers are NEVER captured). A secret-scan
+ *    test asserts no key/token pattern survives in a written record.
+ *  - `AuditConfig` — the `audit` config segment. Two independent switches:
+ *    `enabled` (record metadata) and `captureBodies` (the sensitive second
+ *    opt-in — record bodies too), both default OFF (zero regression).
+ *
+ * @module audit-types
+ */
+/**
+ * One per-request audit entry (design D1). The metadata fields are recorded
+ * whenever audit is `enabled`; the two body snapshots are present ONLY when
+ * `captureBodies` is ALSO on, and always after truncation + redaction. NO field
+ * ever holds key material, an upstream token, or an Authorization/api-key header.
+ */
+interface AuditRecord {
+    /** Unique record id (a generated request id — NOT any secret). */
+    id: string;
+    /** Epoch ms the request was captured. */
+    ts: number;
+    /** Outbound key id (attribution) — NEVER the key secret/hash. Null when unauthenticated. */
+    keyId?: string | null;
+    /** Client IP (PII). Socket address by default; a trusted forwarded header only when configured. */
+    ip?: string;
+    /** Client user-agent (PII). */
+    ua?: string;
+    /** HTTP method. */
+    method: string;
+    /** Request path (query string dropped so no secret query param is stored). */
+    path: string;
+    /** Resolved upstream model. */
+    model?: string;
+    /** Upstream provider id (or `'byo'`). */
+    provider?: string;
+    /** HTTP status the client received. */
+    status: number;
+    /** End-to-end latency (ms). */
+    latencyMs: number;
+    /** Prompt-side token count (present only when the host correlates usage). */
+    inputTokens?: number;
+    /** Completion-side token count (present only when the host correlates usage). */
+    outputTokens?: number;
+    /** Cost in USD (present only when the host correlates usage). */
+    costUsd?: number;
+    /** Sanitized error message (present only on a failed relay). */
+    error?: string;
+    /**
+     * Request body snapshot — present ONLY when `captureBodies`, truncated to the
+     * configured cap, and ALWAYS run through the secret-redaction pass first.
+     */
+    requestBody?: string;
+    /**
+     * Response body snapshot — present ONLY when `captureBodies` AND the response
+     * was NON-streaming (a streaming response records metadata only), truncated +
+     * redacted like `requestBody`.
+     */
+    responseBody?: string;
+}
+/**
+ * The `audit` config segment (design D2), normalized like `accountHealth`.
+ * Absent/`enabled:false` ⇒ no sink wired + no capture ⇒ byte-identical zero
+ * regression. `captureBodies` is a SEPARATE, sensitive opt-in that does nothing
+ * unless `enabled` is also on.
+ */
+interface AuditConfig {
+    /** Master switch; default FALSE (zero regression). */
+    enabled: boolean;
+    /** Capture request/response bodies too (redacted+truncated); default FALSE. */
+    captureBodies: boolean;
+    /** Per-body truncation cap in bytes; default 8192, clamped. */
+    maxBodyBytes: number;
+    /** TTL retention in days; default 7, clamped `[1, 365]`. */
+    retentionDays: number;
+    /**
+     * Trust the `X-Forwarded-For` header for the client IP (LEAD OQ1 anti-spoof).
+     * Default FALSE — the socket remote address is authoritative. Only set true
+     * behind a trusted reverse proxy; a client-supplied XFF is NEVER trusted by
+     * default.
+     */
+    trustForwardedFor: boolean;
+}
+/** Frozen defaults for the `audit` segment (SSOT). */
+declare const DEFAULT_AUDIT_CONFIG: AuditConfig;
+/** One page of audit records the authed admin query returns (newest first). */
+interface AuditQueryResult {
+    records: AuditRecord[];
+}
+
+export { type AuditConfig, type AuditQueryResult, type AuditRecord, DEFAULT_AUDIT_CONFIG };