@omnicross/core 0.1.1 → 0.1.3

package/dist/types-aBFFXoBz.d.cts

@@ -0,0 +1,830 @@
+import { ProxyConfig } from '@omnicross/contracts/account-tokens-types';
+import { AuditConfig } from '@omnicross/contracts/audit-types';
+import { BillingConfig } from '@omnicross/contracts/billing-types';
+import { HealthReport } from '@omnicross/contracts/health-logging-types';
+import { VoucherRecord, VoucherGrant, VoucherInfo, VoucherConfig } from '@omnicross/contracts/voucher-types';
+import { WebhookConfig } from '@omnicross/contracts/webhook-types';
+import { L as Logger } from './logger-4GvQNzhE.cjs';
+import { ProviderConfigSource } from './ports/provider-config-source.cjs';
+import { P as ProviderProxy } from './ProviderProxy-CnMQYN59.cjs';
+import { ProviderProxyDeps } from './provider-proxy/types.cjs';
+
+/**
+ * keyPolicy — PURE decision helpers for the outbound key-policy envelope
+ * (`outbound-key-policy`, design D2/D4). Expiry/activation resolution +
+ * cost-quota decision. No I/O, no clock ownership (the caller passes `now`), so
+ * these are trivially unit-testable and reused by both the auth path
+ * (`verifyKey`) and the wire path (`outboundApiRouter`).
+ *
+ * The #6 (`restrictedModels`) and #9 (voucher) children EXTEND the key-policy
+ * schema; they must not change the shapes frozen here.
+ *
+ * @module outbound-api/keyPolicy
+ */
+/** The expiry/activation subset of a key row `computeKeyExpiry` reads. */
+interface KeyExpiryInput {
+    /** Fixed-mode absolute expiry (epoch ms). */
+    expiresAt?: number | null;
+    /** Expiry mode; absent ⇒ `'fixed'`. */
+    activationMode?: 'fixed' | 'activation';
+    /** Activation-mode lifetime in days (absent/null ⇒ never expires). */
+    activationDays?: number | null;
+    /** First-use activation stamp (epoch ms); null ⇒ not yet activated. */
+    activatedAt?: number | null;
+}
+/** Result of {@link computeKeyExpiry}. */
+interface KeyExpiryResult {
+    expired: boolean;
+    /** The resolved absolute expiry (epoch ms), when the key has one. */
+    effectiveExpiresAt?: number;
+    /**
+     * True when this is an activation-mode key that has NOT been activated yet, so
+     * the caller SHOULD stamp the activation (best-effort) on a successful verify.
+     */
+    needsActivation?: boolean;
+}
+/**
+ * Resolve whether a key is past its effective expiry (design D2).
+ *  - `fixed`: expired when `expiresAt != null && now >= expiresAt`.
+ *  - `activation`: while `activatedAt == null` the key is NOT expired (it
+ *    activates on THIS use → `needsActivation`); once activated, expired when
+ *    `now >= activatedAt + activationDays*DAY`. A null `activationDays` never
+ *    expires.
+ * A key with no expiry configured never expires.
+ */
+declare function computeKeyExpiry(row: KeyExpiryInput, now: number): KeyExpiryResult;
+/** Per-key USD cost limits carried on the verified key (absent scope ⇒ no cap). */
+interface KeyCostLimits {
+    dailyUsd?: number;
+    totalUsd?: number;
+    weeklyUsd?: number;
+}
+/** In-memory per-key accumulated spend snapshot (see `keySpendTracker`). */
+interface KeySpend {
+    dailyUsd: number;
+    /** Local-midnight boundary the `dailyUsd` window opened at (epoch ms). */
+    dailyWindowStart: number;
+    weeklyUsd: number;
+    /** Local week-start boundary the `weeklyUsd` window opened at (epoch ms). */
+    weeklyWindowStart: number;
+    totalUsd: number;
+}
+/** Decision returned by {@link checkKeyQuota}. */
+type QuotaDecision = {
+    allowed: true;
+} | {
+    allowed: false;
+    scope: 'daily' | 'weekly' | 'total';
+    limitUsd: number;
+    spentUsd: number;
+};
+/**
+ * Decide whether the key's accumulated spend already meets/exceeds any
+ * configured cost limit (design D4). `allowed:false` when a scope's PRIOR spend
+ * is `>= limit` (the triggering request's own cost is unknown pre-flight →
+ * bounded one-request overage, CRS-equivalent). An unconfigured scope is never
+ * gated; a `limits`-less key always passes.
+ */
+declare function checkKeyQuota(limits: KeyCostLimits | undefined, spend: KeySpend): QuotaDecision;
+/**
+ * Per-key model restriction carried on the verified key (outbound-key-policy #6).
+ * Present ONLY when the key has `enableModelRestriction === true` — so the wire
+ * layer's presence check (`if (key.modelRestriction) …`) is the zero-regression
+ * gate.
+ */
+interface ModelRestriction {
+    mode: 'blacklist' | 'allowlist';
+    /** Bare modelIds the mode acts on. Empty allowlist denies every model. */
+    models: string[];
+}
+
+/**
+ * keySpendTracker — a cheap in-memory per-key accumulated-spend cache
+ * (`outbound-key-policy`, design D3).
+ *
+ * The request-path cost check MUST NOT scan the usage log. This tracker keeps an
+ * O(1) per-`apiKeyId` aggregate:
+ *  - LAZY SEED: on the first `getSpend` for a key (cache miss), it derives that
+ *    key's total / today's / this-week's spend from the durable usage store via
+ *    the injected {@link KeySpendSeeder} — ONE query per newly-seen key, NOT per
+ *    request. Because it re-seeds from the store, `totalUsd` survives a restart
+ *    (the jsonl IS the durable source; this is just a hot cache).
+ *  - INCREMENT: `add(id, cost, now)` is wired to `UsageRecorder`'s per-request
+ *    record hook, so every recorded request updates the aggregate with no scan.
+ *  - WINDOW ROLL: `getSpend`/`add` roll the daily window at local midnight and
+ *    the weekly window at the local week start before reading/incrementing.
+ *
+ * @module outbound-api/keySpendTracker
+ */
+
+/**
+ * Reader the wire layer depends on (structural). Kept minimal so a test double —
+ * or a future indexed impl — is trivial and the router needs no concrete class.
+ */
+interface KeySpendReader {
+    getSpend(apiKeyId: string, now: number): Promise<KeySpend>;
+}
+/**
+ * Durable-store seed source (design D3). ONE scan of a single key's events
+ * returns all three spend windows (`totalUsd` + `dailyUsd` from `dayStartTs` +
+ * `weeklyUsd` from `weekStartTs`, all `ts < endTs`). One call per newly-seen key.
+ */
+interface KeySpendSeeder {
+    getSpendByKey(query: {
+        apiKeyId: string;
+        dayStartTs: number;
+        weekStartTs: number;
+        endTs: number;
+    }): Promise<{
+        totalUsd: number;
+        dailyUsd: number;
+        weeklyUsd: number;
+    }>;
+}
+/** Local-midnight boundary for `ts` (epoch ms). */
+declare function startOfLocalDay(ts: number): number;
+/**
+ * Local week-start boundary for `ts` (Sunday 00:00 local) — the daily boundary
+ * shifted back to the most recent Sunday.
+ */
+declare function startOfLocalWeek(ts: number): number;
+declare class KeySpendTracker implements KeySpendReader {
+    private readonly seeder;
+    /** apiKeyId → live accumulated spend (seeded lazily). */
+    private readonly spend;
+    constructor(seeder: KeySpendSeeder);
+    /**
+     * Read the key's accumulated spend, seeding from the durable store on a cache
+     * miss and rolling the daily/weekly windows on a hit.
+     */
+    getSpend(apiKeyId: string, now: number): Promise<KeySpend>;
+    /**
+     * Increment the aggregate for one recorded request. No-op when the key has not
+     * been seeded yet — a later `getSpend` will lazy-seed from the durable store,
+     * which already includes this record, so it is neither lost nor double-counted.
+     */
+    add(apiKeyId: string, costUsd: number, now: number): void;
+    /** Drop all cached spend (tests / teardown). */
+    reset(): void;
+    /**
+     * Derive a fresh spend snapshot for `apiKeyId` from the durable store in a
+     * SINGLE scan (all three windows at once). `endTs` is EXCLUSIVE, so `now + 1`
+     * includes a record stamped at exactly `now`.
+     */
+    private seed;
+}
+
+/**
+ * voucher — the `VoucherDb` port + PURE code/grant helpers for the voucher
+ * redemption system (voucher-redemption #9, design D2/D3/D4/D5/D7).
+ *
+ * Layered on top of the #4 outbound key-policy: a voucher redemption only
+ * MUTATES a key's `totalCostLimitUsd` (credit) or `expiresAt` (renewal) through
+ * the already-built `outboundApiKeysSetPolicy` enforcement — no new key fields.
+ *
+ * This module is pure logic + a store port:
+ *  - Code generation reuses the key-auth unbiased base62 generator (`CC_` prefix)
+ *    and sha256 hashing — the plaintext is returned once and NEVER persisted.
+ *  - `computeVoucherGrant` derives the ABSOLUTE grant target (with per-card caps)
+ *    from the current key policy — recorded on the card so the apply step is
+ *    idempotently re-appliable after an interrupted redeem (design D4).
+ *  - `VoucherDb` mirrors `OutboundKeyDb` with an ATOMIC status compare-and-set
+ *    (`redeemCas`/`revokeCas`) — the single-use guarantee.
+ *
+ * @module outbound-api/voucher
+ */
+
+/**
+ * Generate a fresh high-entropy voucher code: `CC_<base62>`. Reuses the key-auth
+ * unbiased (rejection-sampled) base62 generator, so a code is a ~190-bit
+ * credential — guessing is infeasible (design D3). The plaintext is returned ONCE
+ * at generation and NEVER persisted or logged.
+ */
+declare function generateVoucherCode(): string;
+/** Hash a presented/generated voucher code (sha256 hex) — the redeem lookup key. */
+declare function hashVoucherCode(code: string): string;
+/** The short display prefix stored alongside the hash (e.g. `CC_AB12`). */
+declare function voucherCodePrefix(code: string): string;
+/** A small id for a created voucher (independent of the code). */
+declare function newVoucherId(): string;
+/**
+ * Compute the ABSOLUTE grant target a redemption should apply to a key (design
+ * D5), clamped by the card's per-card anti-abuse caps. Pure — the caller records
+ * this on the card at the CAS flip AND applies the same absolute via
+ * `outboundApiKeysSetPolicy`, so an interrupted redeem is idempotently
+ * re-appliable (never double-spends).
+ *
+ *  - `credit`  → `min((current.totalCostLimitUsd ?? 0) + creditUsd, maxTotalCostLimitUsd ?? ∞)`.
+ *    Raising the ceiling above accumulated spend lets an over-limit key resume
+ *    (the #4 spend tracker keeps the spend; only the ceiling rises).
+ *  - `renewal` → `min((current.expiresAt ?? now) + renewalDays·DAY, now + maxExpiryDays·DAY ?? ∞)`.
+ */
+declare function computeVoucherGrant(voucher: VoucherRecord, currentKey: Pick<OutboundKeyDbRow, 'totalCostLimitUsd' | 'expiresAt'> | null | undefined, now: number): VoucherGrant;
+/**
+ * Project a stored voucher to the admin-safe DTO (design D2). Strips the
+ * `codeHash` — the admin sees the display prefix + status + value + caps only,
+ * NEVER the hash. This is the ONLY projection an admin GET returns.
+ */
+declare function toVoucherInfo(v: VoucherRecord): VoucherInfo;
+/** Input to `VoucherDb.create` — the card fields minus the derived lifecycle. */
+interface VoucherCreateInput {
+    id: string;
+    codeHash: string;
+    codePrefix: string;
+    type: VoucherRecord['type'];
+    creditUsd?: number;
+    renewalDays?: number;
+    maxTotalCostLimitUsd?: number;
+    maxExpiryDays?: number;
+    createdAt?: number;
+}
+/**
+ * The voucher store port (design D7), mirroring `OutboundKeyDb`. The daemon
+ * implements it over the SAME update-capable mechanism the key store uses (a JSON
+ * file with a synchronous read-check-write that is atomic within Node's single
+ * thread — NOT an append-only jsonl, which cannot flip a status in place).
+ *
+ * `redeemCas`/`revokeCas` are ATOMIC compare-and-sets: they transition the card
+ * out of `unredeemed` ONLY IF it is still `unredeemed`, returning whether THIS
+ * call won. A concurrent second redeem loses (returns false) — the single-use
+ * guarantee (design D4).
+ */
+interface VoucherDb {
+    /** Create + persist a card (status `unredeemed`). */
+    voucherCreate(input: VoucherCreateInput): Promise<VoucherRecord>;
+    /** Look up a card by its code hash (the redeem lookup). Null when absent. */
+    voucherGetByHash(codeHash: string): Promise<VoucherRecord | null>;
+    /**
+     * ATOMIC single-use flip `unredeemed → redeemed`, recording the redeeming key
+     * id + the AUDIT `granted*` snapshot and setting `grantApplied = false`. Returns
+     * true when THIS call won the CAS (the card was still `unredeemed`), false when
+     * it lost (already redeemed/revoked) — the single-use guard (design D4). The
+     * grant is NOT applied here; the caller applies a RELATIVE increment then calls
+     * {@link voucherMarkGrantApplied}.
+     */
+    voucherRedeemCas(id: string, keyId: string, granted: VoucherGrant, now: number): Promise<boolean>;
+    /**
+     * Mark a redeemed card's grant as APPLIED (`grantApplied = true`), AFTER the
+     * key policy write succeeded (MJ1 fix). The guard against a replay double-add:
+     * a `redeemed` card with `grantApplied === true` is never re-applied. Returns
+     * false when the card is missing/not redeemed.
+     */
+    voucherMarkGrantApplied(id: string): Promise<boolean>;
+    /**
+     * Revert a flip whose grant apply FAILED (M3): `redeemed → unredeemed`, clearing
+     * the redeem bookkeeping, ONLY IF the card is `redeemed`, was redeemed by
+     * `keyId`, and `grantApplied !== true` (never revert an applied grant). Returns
+     * true when reverted, false otherwise. Lets the holder retry a card whose apply
+     * hit a transient key error instead of silently losing it.
+     */
+    voucherRevertRedeem(id: string, keyId: string): Promise<boolean>;
+    /**
+     * ATOMIC flip `unredeemed → revoked`. Returns true when THIS call won (the card
+     * was still `unredeemed`), false otherwise — a REDEEMED card can NEVER be
+     * revoked (design D6).
+     */
+    voucherRevokeCas(id: string, now: number): Promise<boolean>;
+    /** List all cards (admin; the caller projects to `VoucherInfo` — no hash out). */
+    voucherList(): Promise<VoucherRecord[]>;
+}
+
+/**
+ * Shared contract types for the outbound API server (`outbound-api-server`).
+ *
+ * The outbound server is a SEPARATE long-lived HTTP listener (distinct from the
+ * resident loopback `ProviderProxy`) that authenticates external callers via
+ * named API keys and routes their requests through the EXISTING `provider-proxy`
+ * ingress parsers + transformer — there is exactly one conversion stack.
+ *
+ * These types are kept in their own module so the server, router, auth, rate
+ * limiter, role detection, and route resolver can share shapes without circular
+ * imports.
+ *
+ * @module outbound-api/types
+ */
+
+/** The four endpoints, 1:1 with the four wire-format ingress parsers. */
+type OutboundEndpoint = 'chat' | 'responses' | 'messages' | 'gemini';
+/** A `"providerId,modelId"` model reference (mirrors `RouterConfig` vocab). */
+type ModelRef = string;
+/** The detected request role; precedence background > default. */
+type RequestRole = 'background' | 'default';
+/**
+ * Dispatch mode for the list-mapped `chat` endpoint (openai-chat-bridge #11).
+ *  - `'list'` (default): the client requests one of the endpoint's configured
+ *    `models` refs by modelId — the exact current behavior (zero regression).
+ *  - `'prefix'`: the requested model's NAME PREFIX (`claude-*` / `gpt-*` /
+ *    `gemini-*`) selects a configured target from {@link ModelPrefixTargets},
+ *    on a single `/v1/chat/completions` — a routing convenience over the same
+ *    conversion machinery. An unmatched prefix is a clear per-request error.
+ */
+type ChatDispatchMode = 'list' | 'prefix';
+/**
+ * Prefix → target `"providerId,modelId"` ref map for the `chat` endpoint's
+ * `dispatchMode: 'prefix'` (openai-chat-bridge #11). Each target may be a
+ * subscription (e.g. `claude,claude-sonnet-4-5`) or a BYO ref — the same ref
+ * vocabulary the list mode uses. Absent prefixes are simply unroutable in prefix
+ * mode. The vocabulary is the three core prefixes (claude / gpt / gemini);
+ * additional prefixes (deepseek, …) are an additive-later extension.
+ */
+interface ModelPrefixTargets {
+    claude?: ModelRef;
+    gpt?: ModelRef;
+    gemini?: ModelRef;
+}
+/**
+ * SSOT of the canonical model KINDS per kind-mapped endpoint.
+ *
+ * The `messages` (Claude Code) and `responses` (Codex) endpoints route by model
+ * KIND rather than role: the user configures one upstream ref per kind, and an
+ * incoming versioned client id (`claude-opus-4-8-2026xxxx`) is classified to its
+ * kind (`opus`) so CLI upgrades need no reconfig. `chat`/`gemini` are NOT in this
+ * map — they keep the role-based (`default`/`background`) config.
+ */
+declare const ENDPOINT_MODEL_KINDS: {
+    readonly messages: readonly ["fable", "opus", "sonnet", "haiku"];
+    readonly responses: readonly ["codex", "mini"];
+};
+/** The endpoints that route by model kind (`messages` | `responses`). */
+type KindMappedEndpoint = keyof typeof ENDPOINT_MODEL_KINDS;
+/** Claude Code (`messages`) kinds. */
+type MessagesModelKind = (typeof ENDPOINT_MODEL_KINDS)['messages'][number];
+/** Codex (`responses`) kinds. */
+type ResponsesModelKind = (typeof ENDPOINT_MODEL_KINDS)['responses'][number];
+/** Any canonical model kind across the kind-mapped endpoints. */
+type ModelKind = MessagesModelKind | ResponsesModelKind;
+/**
+ * Per-endpoint routing config. Persisted independently of the global
+ * "默认模型" settings tab; survives restart.
+ *
+ * The shape is HETEROGENEOUS by endpoint class:
+ *  - kind-mapped (`messages`/`responses`): `modelMap` (kind → ref) is authoritative;
+ *    everything else is unused.
+ *  - list-mapped (`chat`): `models` (a list of refs) is authoritative — the
+ *    client requests one of the listed modelIds directly (`GET /v1/models`
+ *    serves the list); no default/background roles.
+ *  - role-based (`gemini`): `defaultModel`/`backgroundModel` (+ optional
+ *    `backgroundModelIds`) are authoritative.
+ */
+interface EndpointRoutingConfig {
+    /** Which of the four endpoints this block configures. */
+    endpoint: OutboundEndpoint;
+    /**
+     * Kind-mapped endpoints (`messages`/`responses`): model KIND → `"providerId,modelId"`.
+     * Keys are the endpoint's declared {@link ENDPOINT_MODEL_KINDS}.
+     */
+    modelMap?: Record<string, ModelRef>;
+    /**
+     * List-mapped endpoint (`chat`): the `"providerId,modelId"` refs this endpoint
+     * serves. The ref's modelId is the model name the client requests and the name
+     * `GET /v1/models` advertises; a request whose `model` is not in the list is
+     * rejected per-request (404-style). Empty ⇒ endpoint unused.
+     */
+    models?: ModelRef[];
+    /**
+     * List-mapped endpoint (`chat`) dispatch mode (openai-chat-bridge #11). Absent
+     * ⇒ `'list'` (default) — routing is byte-identical to before this change. Only
+     * `'prefix'` changes behavior (route by model-name prefix via `prefixTargets`).
+     */
+    dispatchMode?: ChatDispatchMode;
+    /**
+     * List-mapped endpoint (`chat`) prefix → target map, consumed ONLY when
+     * `dispatchMode === 'prefix'` (openai-chat-bridge #11). Ignored in list mode.
+     */
+    prefixTargets?: ModelPrefixTargets;
+    /** Role-based endpoint (`gemini`): model for normal requests. */
+    defaultModel?: ModelRef;
+    /** Role-based endpoint (`gemini`): model for background/probe requests. */
+    backgroundModel?: ModelRef;
+    /** Gates subscription-vs-BYO provider selection. Default FALSE. */
+    useSubscription: boolean;
+    /**
+     * OPTIONAL "background model id" override list (role-based `gemini` only).
+     * When set, an incoming requested model id appearing in this list is
+     * classified as the BACKGROUND role; otherwise the registry small/haiku-class
+     * signal is the baseline. Empty/unset → registry signal only. Compared against
+     * the requested model id (bare or `providerId,modelId`).
+     */
+    backgroundModelIds?: string[];
+}
+/**
+ * User-message serial-queue segment (per-upstream-account 防风控). Frozen
+ * defaults + valid ranges (SSOT + clamp in `apiServerConfig`):
+ *  - `enabled`       default **false** (opt-in).
+ *  - `delayMs`       default **200**, valid `0..10000` — min gap between one
+ *                    account's serialized requests.
+ *  - `waitTimeoutMs` default **60000**, valid `1000..300000` — a waiter past
+ *                    this rejects (wire → 503).
+ */
+interface UserMessageQueueConfig {
+    enabled: boolean;
+    delayMs: number;
+    waitTimeoutMs: number;
+}
+/**
+ * Per-key concurrency-queue segment (排队而非硬拒). Frozen defaults + valid
+ * ranges (SSOT + clamp in `apiServerConfig`):
+ *  - `maxQueueSizeFactor` default **2**, valid `1..10` — per-key max queued =
+ *    `max(limit*factor, minQueueSize)`.
+ *  - `minQueueSize`       default **4**, valid `1..100` — floor of the above.
+ *  - `waitTimeoutMs`      default **60000**, valid `1000..300000` — a waiter
+ *    past this rejects (wire → 429).
+ */
+interface ConcurrencyQueueConfig {
+    maxQueueSizeFactor: number;
+    minQueueSize: number;
+    waitTimeoutMs: number;
+}
+/**
+ * Subscription account-health segment (subscription-account-health, LEAD OQ1).
+ * Persisted + strictly validated like the queue segments; applied to the shared
+ * `SubscriptionAccountHealth` tracker at daemon boot.
+ *  - `overloadCooldownEnabled` default **true** — a 529 places the account in
+ *    overload cooldown (ON by default; CRS ships it off).
+ *  - `overloadCooldownMs`      default **600000** (10 min), valid `60000..3600000`.
+ */
+interface AccountHealthConfig {
+    overloadCooldownEnabled: boolean;
+    overloadCooldownMs: number;
+}
+/**
+ * Scheduled account-probe segment (subscription-account-probe, #8 health-cron).
+ * The active complement to #2's passive health machine: a cheap, staggered,
+ * default-OFF background probe that discovers a dead/expired account BEFORE real
+ * traffic does. Persisted + range-clamped like `accountHealth`; consumed by the
+ * daemon `AccountHealthProbeScheduler` (an `unref()`ed interval — omnicross has
+ * no cron dep). ALL knobs are load-safety valves:
+ *  - `enabled`          default **false** (zero regression — no probes, no /health
+ *                       boolean, byte-identical when off).
+ *  - `intervalMs`       default **900000** (15 min), valid `60000..86400000`.
+ *  - `onlyMultiAccount` default **true** — probe only providers with ≥2 accounts
+ *                       (where #2 health-gating actually matters; a single-account
+ *                       provider is never probed — #2 keeps it schedulable anyway).
+ *  - `timeoutMs`        default **5000** per upstream probe, valid `1000..60000`.
+ *  - `historySize`      default **10** rolling per-account records, valid `1..200`.
+ *  - `staggerMs`        default **500** gap between consecutive probes, valid
+ *                       `0..60000` (so N accounts never fire N simultaneous GETs).
+ */
+interface AccountProbeConfig {
+    enabled: boolean;
+    intervalMs: number;
+    onlyMultiAccount: boolean;
+    timeoutMs: number;
+    historySize: number;
+    staggerMs: number;
+}
+/**
+ * Client-fingerprint segment (subscription-client-fingerprint #7). Opt-in,
+ * default OFF: when disabled the claude-subscription outbound headers are
+ * byte-identical to before this change (content-type + the OAuth bearer only).
+ * When enabled, real client fingerprint headers are captured per account, frozen,
+ * and replayed on outbound so relayed traffic presents a stable, REAL per-account
+ * client identity. `ua` is an OPTIONAL operator UA baseline applied ONLY when an
+ * account has no captured identity yet (never a fabricated stainless value).
+ * Persisted + read at daemon boot (like `accountHealth`; a change takes effect on
+ * restart). Carries NO secret.
+ */
+interface FingerprintConfig {
+    /** Master switch; default false ⇒ no capture/replay ⇒ byte-identical outbound. */
+    enabled: boolean;
+    /** Operator UA baseline for un-captured accounts (piece 4). Absent ⇒ none. */
+    ua?: string;
+}
+/**
+ * Layered upstream-proxy segment (upstream-proxy). Global + per-provider proxy
+ * config for outbound EGRESS to upstreams (NOT the inbound listener). Resolved
+ * with precedence account > provider > global > env; the per-account layer lives
+ * on the account entry (`SubscriptionAccountEntry.proxy`), not here. Absent ⇒ no
+ * proxy at these layers (direct fetch). `byProvider` keys are subscription
+ * provider ids (`claude`/`codex`/`gemini`/`opencodego`) or `'byo'`. A `ProxyConfig`
+ * `password` is a SECRET — encrypted at rest + masked in the admin GET.
+ */
+interface OutboundProxyConfig {
+    /** Applies to every upstream unless a more specific layer overrides. */
+    global?: ProxyConfig;
+    /** Per-provider override, keyed by subscription provider id or `'byo'`. */
+    byProvider?: Record<string, ProxyConfig>;
+}
+/** The persisted server config. */
+interface OutboundApiServerConfig {
+    /** When false the listener never binds (off by default). */
+    enabled: boolean;
+    /** When true the listener binds `0.0.0.0` (LAN) instead of `127.0.0.1`. */
+    networkBinding: boolean;
+    /** Per-endpoint routing config, one per endpoint (4 entries). */
+    endpoints: EndpointRoutingConfig[];
+    /** Persisted port (fixed default; falls back to ephemeral on EADDRINUSE). */
+    port?: number;
+    /**
+     * User-message serial queue segment. Optional in the persisted shape;
+     * `normalizeServerConfig` always fills it with the frozen defaults, so a
+     * normalized config carries it.
+     */
+    userMessageQueue?: UserMessageQueueConfig;
+    /**
+     * Per-key concurrency queue segment. Optional in the persisted shape;
+     * `normalizeServerConfig` always fills it with the frozen defaults.
+     */
+    concurrencyQueue?: ConcurrencyQueueConfig;
+    /**
+     * Subscription account-health segment. Optional in the persisted shape;
+     * `normalizeServerConfig` always fills it with the frozen defaults. Applied to
+     * the shared health tracker at daemon boot (change takes effect on restart).
+     */
+    accountHealth?: AccountHealthConfig;
+    /**
+     * Scheduled account-probe segment (subscription-account-probe #8). Optional in
+     * the persisted shape; `normalizeServerConfig` always fills it with the frozen
+     * defaults (enabled:false). Read by the daemon `AccountHealthProbeScheduler` at
+     * boot; a change takes effect on restart. Default-off ⇒ no scheduler runs.
+     */
+    accountProbe?: AccountProbeConfig;
+    /**
+     * Layered upstream-proxy segment (upstream-proxy). Optional; when absent no
+     * global/provider proxy applies (direct egress). `normalizeServerConfig` drops
+     * malformed entries but does NOT synthesize a default (a missing proxy segment
+     * stays absent — zero-config = direct fetch).
+     */
+    proxy?: OutboundProxyConfig;
+    /**
+     * Webhook notification segment (webhook-notifications). Optional; when absent
+     * (or `enabled:false`) the emit sink is never wired ⇒ `emitWebhookEvent` is a
+     * no-op ⇒ byte-identical zero regression. `normalizeServerConfig` drops
+     * malformed destinations but does NOT synthesize a default (a missing webhook
+     * segment stays absent). A destination `secret` is encrypted at rest + masked
+     * in admin views.
+     */
+    webhook?: WebhookConfig;
+    /**
+     * Request-audit segment (request-audit-log). Optional; when absent (or
+     * `enabled:false`) no capture config or sink is wired ⇒ the capture hook does
+     * nothing ⇒ byte-identical zero regression. `normalizeServerConfig` always
+     * fills it with the frozen defaults (enabled:false). Read by the daemon at boot
+     * + admin PUT to (un)register the core sink + capture config; a change takes
+     * effect immediately (hot-reloaded like `webhook`). Carries NO secret.
+     */
+    audit?: AuditConfig;
+    /**
+     * Billing-event-stream segment (billing-event-stream). Optional; when absent
+     * (or `enabled:false`) no sink is wired ⇒ `publishBillingEvent` is a no-op ⇒ no
+     * ledger append, no POST, byte-identical zero regression.
+     * `normalizeServerConfig` always fills it with the frozen defaults
+     * (enabled:false). Read by the daemon at boot + admin PUT to (un)register the
+     * core sink + capture gate; a change takes effect immediately (hot-reloaded like
+     * `webhook`/`audit`). Carries ONE secret (`secret`, the HMAC key — encrypted at
+     * rest + masked in admin).
+     */
+    billing?: BillingConfig;
+    /**
+     * Client-fingerprint segment (subscription-client-fingerprint #7). Optional in
+     * the persisted shape; `normalizeServerConfig` always fills it with the frozen
+     * defaults (enabled:false). Read at daemon boot to `configure` + seed + wire
+     * persistence on the shared identity store; a change takes effect on restart.
+     * Default-off ⇒ no capture/replay ⇒ byte-identical outbound headers.
+     */
+    fingerprint?: FingerprintConfig;
+    /**
+     * Voucher (redemption-card) segment (voucher-redemption #9). Optional in the
+     * persisted shape; `normalizeServerConfig` always fills it with the frozen
+     * defaults (enabled:false). When disabled (the default) the `POST /redeem`
+     * endpoint rejects + no admin generate is offered ⇒ no key is ever mutated ⇒
+     * byte-identical zero regression, purely additive on the #4 key-policy.
+     */
+    voucher?: VoucherConfig;
+}
+/** A live status snapshot the Settings tab renders. */
+interface OutboundApiServerStatus {
+    running: boolean;
+    /** Actual bound port (0 when not running). */
+    port: number;
+    /** Loopback base URL (always present when running). */
+    loopbackUrl: string | null;
+    /** LAN base URL (present only when network binding is on). */
+    lanUrl: string | null;
+    /** The four format endpoint URLs (loopback). */
+    formats: OutboundFormatUrls | null;
+    /** The four format endpoint URLs over the LAN (only when network binding on). */
+    lanFormats: OutboundFormatUrls | null;
+}
+/** The four format endpoint URLs for one base. */
+interface OutboundFormatUrls {
+    chat: string;
+    responses: string;
+    messages: string;
+    gemini: string;
+}
+/** A stored key DTO (never carries the plaintext secret). */
+interface OutboundApiKeyInfo {
+    id: string;
+    name: string;
+    keyPrefix: string;
+    enabled: boolean;
+    createdAt: number;
+    lastUsedAt: number | null;
+    revoked: boolean;
+    /**
+     * Per-key concurrency ceiling for the outbound concurrency gate. Absent or
+     * `0` = unlimited (the gate is bypassed entirely for this key).
+     */
+    maxConcurrency?: number;
+    /** Fixed-mode absolute expiry (epoch ms). */
+    expiresAt?: number | null;
+    /** Expiry mode; absent ⇒ `'fixed'`. */
+    activationMode?: OutboundKeyActivationMode;
+    /** Activation-mode lifetime in days. */
+    activationDays?: number | null;
+    /** First-use activation stamp (epoch ms); written once, surfaced read-only. */
+    activatedAt?: number | null;
+    /** Daily USD cost cap. */
+    dailyCostLimitUsd?: number | null;
+    /** Lifetime USD cost cap. */
+    totalCostLimitUsd?: number | null;
+    /** Weekly USD cost cap. */
+    weeklyCostLimitUsd?: number | null;
+    /** Per-key rate-limit max requests per window (absent ⇒ 60; `0` ⇒ unlimited). */
+    rateLimitMaxRequests?: number | null;
+    /** Per-key rate-limit window (ms; absent ⇒ 60_000). */
+    rateLimitWindowMs?: number | null;
+    /** Master switch: when false/unset the model list is inert (no restriction). */
+    enableModelRestriction?: boolean;
+    /** Restriction mode; absent ⇒ `'blacklist'` (CRS-parity). */
+    restrictionMode?: OutboundKeyModelRestrictionMode;
+    /** The model-id list the mode acts on (bare modelIds; empty allowlist denies all). */
+    restrictedModels?: string[];
+    /**
+     * The key's OWN accumulated spend (outbound-key-policy), surfaced by the admin
+     * so an operator sees spend-vs-limit. Present only when the host wired a spend
+     * reader. Leak-safe: each key carries only ITS own numbers — the same data the
+     * key's holder already sees in a 402 body.
+     */
+    spend?: {
+        dailyUsd: number;
+        weeklyUsd: number;
+        totalUsd: number;
+    };
+}
+/** Expiry mode for an outbound key: fixed absolute vs first-use activation. */
+type OutboundKeyActivationMode = 'fixed' | 'activation';
+/**
+ * Per-key model-restriction mode (outbound-key-policy #6). `blacklist` denies the
+ * listed models; `allowlist` permits ONLY the listed models (an empty allowlist
+ * denies everything — a deliberate "disabled by model" state).
+ */
+type OutboundKeyModelRestrictionMode = 'blacklist' | 'allowlist';
+/**
+ * The settable key-policy envelope (`outboundApiKeysSetPolicy`). Every field is
+ * three-way: a value SETS, explicit `null` CLEARS, and OMISSION keeps the stored
+ * value (mirrors the `maxConcurrency` write contract). `activatedAt` is NOT here
+ * — it is written once by `outboundApiKeysMarkActivated`, never operator-set.
+ * The #6/#9 children extend this shape; do not drift the frozen fields.
+ */
+interface OutboundKeyPolicy {
+    expiresAt?: number | null;
+    activationMode?: OutboundKeyActivationMode | null;
+    activationDays?: number | null;
+    dailyCostLimitUsd?: number | null;
+    totalCostLimitUsd?: number | null;
+    weeklyCostLimitUsd?: number | null;
+    rateLimitMaxRequests?: number | null;
+    rateLimitWindowMs?: number | null;
+    enableModelRestriction?: boolean | null;
+    restrictionMode?: OutboundKeyModelRestrictionMode | null;
+    restrictedModels?: string[] | null;
+}
+/** The one-time create result; `plaintextOnce` is shown exactly once. */
+interface OutboundApiKeyCreated {
+    id: string;
+    name: string;
+    keyPrefix: string;
+    createdAt: number;
+    plaintextOnce: string;
+}
+/**
+ * Structural subset of the DB the outbound server needs — the named-key CRUD
+ * surface. Kept structural so the server module does not depend on the full
+ * `DbRpc`.
+ */
+interface OutboundKeyDbRow {
+    id: string;
+    name: string;
+    keyHash: string;
+    keyPrefix: string;
+    enabled: boolean;
+    createdAt: number;
+    lastUsedAt: number | null;
+    revokedAt: number | null;
+    /**
+     * Per-key concurrency ceiling. Absent/`0` = unlimited = the concurrency gate
+     * is bypassed for this key. Persisted by the daemon (`omnicross-uqc-daemon`).
+     */
+    maxConcurrency?: number;
+    /** Fixed-mode absolute expiry (epoch ms). */
+    expiresAt?: number | null;
+    /** Expiry mode; absent ⇒ `'fixed'`. */
+    activationMode?: OutboundKeyActivationMode;
+    /** Activation-mode lifetime in days. */
+    activationDays?: number | null;
+    /** First-use activation stamp (epoch ms); written ONCE on first successful use. */
+    activatedAt?: number | null;
+    /** Daily USD cost cap. */
+    dailyCostLimitUsd?: number | null;
+    /** Lifetime USD cost cap. */
+    totalCostLimitUsd?: number | null;
+    /** Weekly USD cost cap. */
+    weeklyCostLimitUsd?: number | null;
+    /** Per-key rate-limit max requests per window (absent ⇒ 60; `0` ⇒ unlimited). */
+    rateLimitMaxRequests?: number | null;
+    /** Per-key rate-limit window (ms; absent ⇒ 60_000). */
+    rateLimitWindowMs?: number | null;
+    /** Master switch; false/unset ⇒ no model check (zero-regression gate). */
+    enableModelRestriction?: boolean;
+    /** Restriction mode; absent ⇒ `'blacklist'`. */
+    restrictionMode?: OutboundKeyModelRestrictionMode;
+    /** The model-id list the mode acts on (bare modelIds). */
+    restrictedModels?: string[];
+}
+interface OutboundKeyDb {
+    outboundApiKeysList(): Promise<OutboundKeyDbRow[]>;
+    outboundApiKeysGetByHash(hash: string): Promise<OutboundKeyDbRow | null>;
+    outboundApiKeysCreate(input: {
+        id: string;
+        name: string;
+        keyHash: string;
+        keyPrefix: string;
+        createdAt?: number;
+    }): Promise<OutboundKeyDbRow>;
+    outboundApiKeysRevoke(id: string): Promise<boolean>;
+    outboundApiKeysTouchLastUsed(id: string): Promise<boolean>;
+    outboundApiKeysSetEnabled(id: string, enabled: boolean): Promise<boolean>;
+    /**
+     * Set (or clear) a key's per-key concurrency ceiling. `null` clears the field
+     * → unlimited (gate bypassed). Mirrors `outboundApiKeysSetEnabled`; returns
+     * `false` when the key is missing/revoked. Implemented by the daemon
+     * (`omnicross-uqc-daemon`); test fakes implement it inline.
+     */
+    outboundApiKeysSetMaxConcurrency(id: string, maxConcurrency: number | null): Promise<boolean>;
+    /**
+     * Set (or clear) a key's policy envelope (expiry / activation window / cost
+     * limits / per-key rate) in one write (outbound-key-policy). Each field is
+     * three-way — a value sets, explicit `null` clears, omission keeps — mirroring
+     * `outboundApiKeysSetMaxConcurrency`. Returns `false` when the key is
+     * missing/revoked. Does NOT touch `activatedAt`.
+     */
+    outboundApiKeysSetPolicy(id: string, policy: OutboundKeyPolicy): Promise<boolean>;
+    /**
+     * Stamp the one-time first-use activation (`activatedAt`) for an
+     * activation-mode key. Best-effort like `outboundApiKeysTouchLastUsed`; a
+     * no-op returning `false` when the key is missing/revoked or already
+     * activated (the original stamp is never overwritten — activation is
+     * idempotent).
+     */
+    outboundApiKeysMarkActivated(id: string, activatedAt: number): Promise<boolean>;
+}
+/**
+ * App-session-scoped dependencies the outbound server needs. The resident
+ * `ProviderProxy` is shared so the new listener mints routes on the SAME route
+ * map and reuses the SAME ingress parsers + transformer.
+ */
+interface OutboundApiDeps {
+    readonly db: OutboundKeyDb;
+    /**
+     * OPTIONAL voucher store (voucher-redemption #9). When wired (by the daemon
+     * bootstrap), the key-authenticated `POST /redeem` endpoint can redeem cards
+     * against the presenting key (gated on `voucher.enabled`). Absent ⇒ `/redeem`
+     * is inert (byte-identical zero-regression for embedders/tests that do not wire
+     * it, and whenever the feature is disabled).
+     */
+    readonly voucherDb?: VoucherDb;
+    readonly llmConfig: ProviderConfigSource;
+    /** The resident proxy — shared for route minting + ingress dispatch. */
+    readonly providerProxy: ProviderProxy;
+    /** The proxy's app-session deps (reused verbatim for `routeRequest`). */
+    readonly proxyDeps: ProviderProxyDeps;
+    /**
+     * OPTIONAL unauthenticated `/health` provider (daemon-health-endpoint, D1
+     * secondary mount). When wired (by the daemon bootstrap — core NEVER imports
+     * daemon), the server serves `GET|HEAD /health` (+ `/healthz`) BEFORE its
+     * per-request key-auth, so an orchestrator can probe the TRAFFIC port. Absent
+     * ⇒ `/health` is not mounted and falls through to normal auth (byte-identical
+     * zero-regression for embedders that do not wire it).
+     */
+    readonly healthReportProvider?: () => HealthReport;
+    /**
+     * OPTIONAL per-key spend reader (outbound-key-policy). When wired (by the
+     * daemon bootstrap), a key carrying a cost limit is checked against its
+     * accumulated spend before dispatch (→ 402). Absent ⇒ NO cost-quota check runs
+     * (byte-identical zero-regression for embedders/tests that do not wire it, and
+     * for every policy-less key regardless).
+     */
+    readonly keySpendTracker?: KeySpendReader;
+    /**
+     * OPTIONAL injected logger (configurable-logging). When wired (by the daemon
+     * bootstrap), the server's OWN lifecycle lines (listen/stop/error) + the relay
+     * dispatch-error route through it — so they honor the configured level / format
+     * / file sink. Absent ⇒ the legacy `console.*` fallback (byte-identical for
+     * embedders/tests that do not wire it).
+     */
+    readonly logger?: Logger;
+}
+
+export { type AccountProbeConfig as A, computeVoucherGrant as B, type ChatDispatchMode as C, generateVoucherCode as D, ENDPOINT_MODEL_KINDS as E, type FingerprintConfig as F, hashVoucherCode as G, newVoucherId as H, startOfLocalDay as I, startOfLocalWeek as J, type KeyCostLimits as K, toVoucherInfo as L, type MessagesModelKind as M, voucherCodePrefix as N, type OutboundKeyDb as O, type ModelRef as P, type QuotaDecision as Q, type RequestRole as R, type ModelRestriction as S, type AccountHealthConfig as T, type UserMessageQueueConfig as U, type VoucherCreateInput as V, type OutboundKeyModelRestrictionMode as W, type ConcurrencyQueueConfig as a, type EndpointRoutingConfig as b, type KeyExpiryInput as c, type KeyExpiryResult as d, type KeySpend as e, type KeySpendReader as f, type KeySpendSeeder as g, KeySpendTracker as h, type KindMappedEndpoint as i, type ModelKind as j, type ModelPrefixTargets as k, type OutboundApiDeps as l, type OutboundApiKeyCreated as m, type OutboundApiKeyInfo as n, type OutboundApiServerConfig as o, type OutboundApiServerStatus as p, type OutboundEndpoint as q, type OutboundFormatUrls as r, type OutboundKeyActivationMode as s, type OutboundKeyDbRow as t, type OutboundKeyPolicy as u, type OutboundProxyConfig as v, type ResponsesModelKind as w, type VoucherDb as x, checkKeyQuota as y, computeKeyExpiry as z };