opencode-auth-load-balancer 0.8.1 → 0.9.1

package/dist/login-rev.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The shared version of a row's OAuth login. Gist sync orders the copies of one
+ * login that different machines hold by it, so every change of the access +
+ * refresh pair (login, refresh, minted rotation) bumps it in the same pool
+ * transaction as the credential.
+ */
+import type { PoolAccount } from './types';
+/** Record that `row`'s login pair just changed. */
+export declare function bumpLoginRev(row: PoolAccount, now?: number): void;
+/** The version of a row's login; a row that never recorded one is revision 1, at time 0. */
+export declare function loginVersion(row: PoolAccount): {
+    rev: number;
+    at: number;
+};

package/dist/providers/anthropic/usage.d.ts

@@ -17,8 +17,8 @@ export declare function sendUsageProbe(access: string): Promise<Response>;
 export declare function probeSnapshot(headers: Headers, now: number): UsageSnapshot | null;
 /**
  * Poll the dedicated usage endpoint for authoritative 5h + 7d utilization without
- * consuming inference quota. Returns null on any failure — including a 200 whose
- * body is not the usage shape — so the caller keeps the last-known snapshot.
+ * consuming inference quota. A 401 is surfaced for bounded OAuth recovery;
+ * other failures, including an invalid 200 body, keep the last-known snapshot.
  *
  * A row without a refresh token is a `claude setup-token` bearer, scoped to
  * `user:inference` alone; the endpoint demands `user:profile` and answers it

package/dist/providers/kimi/usage.d.ts

@@ -6,7 +6,7 @@ import type { PoolAccount, UsageSnapshot } from '../../types';
  * broken body keeps the last-known snapshot instead of reading as 0% used.
  */
 export declare function parseUsages(json: unknown, now: number): UsageSnapshot | null;
-/** `GET {baseUrl}/usages` — free, spends no quota. Null on any failure. */
+/** `GET {baseUrl}/usages`: surface 401 for OAuth recovery; other failures return null. */
 export declare function getUsages(baseUrl: string, key: string): Promise<unknown>;
 /** The adapter's `fetchUsage` for one deployment. */
 export declare function usageFetcher(baseUrl: string): (account: PoolAccount, now: number) => Promise<UsageSnapshot | null>;

package/dist/providers/openai/usage.d.ts

@@ -14,7 +14,8 @@ export declare function parseUsageHeaders(headers: Headers): Partial<UsageSnapsh
 /**
  * Poll GET /wham/usage for authoritative 5h + weekly utilization without
  * consuming inference quota, assigning each returned window to its role BY
- * DURATION (see `isWeeklyMinutes`) rather than by position. Null on failure.
+ * DURATION (see `isWeeklyMinutes`) rather than by position. A 401 is surfaced
+ * for bounded OAuth recovery; other failures return null.
  * Sends the Codex CLI's `codex-cli` UA and the `chatgpt-account-id` (from the
  * stored id or, as a fallback, decoded from the access-token JWT) — required
  * for team/workspace accounts.

package/dist/providers/usage-http.d.ts

@@ -1,9 +1,6 @@
-/**
- * Shared HTTP shell for the plugin's read-only JSON GETs — the provider usage
- * endpoints (Anthropic `/usage`, OpenAI `/wham/usage`) and the npm dist-tags
- * lookup behind `providers/anthropic/version.ts`. GET with a timeout, null on
- * ANY failure — network throw/timeout, non-ok status (body cancelled so the
- * connection is released), or a 200 whose body is not JSON. Callers keep only
- * their own headers and shape guards; the transport contract lives here ONCE.
- */
 export declare function fetchJson<T>(url: string, headers: Record<string, string>, timeoutMs: number): Promise<T | null>;
+export declare class UsageAuthenticationError extends Error {
+    readonly status = 401;
+    constructor();
+}
+export declare function fetchUsageJson<T>(url: string, headers: Record<string, string>, timeoutMs: number): Promise<T | null>;

package/dist/refresh-hooks.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Hooks gist sync plugs into the refresh path. A leaf module on purpose:
+ * `refresh.ts` stays free of GitHub and crypto code, and sync can register
+ * without an import cycle. No hooks are set unless sync registers some.
+ */
+import type { PoolAccount } from './types';
+export interface RefreshHooks {
+    /**
+     * Called inside the account's refresh lock, before the provider is asked:
+     * resolves true when it put a newer shared login on the row (re-read it).
+     * `recovery` is set once the provider refused the refresh token.
+     */
+    pull?: (account: PoolAccount, recovery: boolean) => Promise<boolean>;
+    /** Called outside the lock after a refresh this call performed. */
+    afterRefresh?: () => void;
+}
+export declare function setRefreshHooks(hooks: RefreshHooks | null): void;
+export declare function getRefreshHooks(): RefreshHooks | null;

package/dist/sync/apply.d.ts

@@ -23,6 +23,8 @@ export type Landing = {
     blocker: string;
     holds: string;
 };
+/** `label`, or `label (n)` when another row already carries it (labels are unique pool-wide). */
+export declare function uniqueLabel(pool: PoolFile, label: string): string;
 /**
  * Land one verified credential, deciding everything from the pool as it is
  * under the lock (callers run this inside `mutatePool`):

package/dist/sync/cycle.d.ts

@@ -11,6 +11,8 @@ export interface CycleReport {
 }
 /** After GitHub refuses the account's write, nothing is attempted for this long (downloads go on). */
 export declare const WRITE_BACKOFF_MS = 3600000;
+/** "Uploaded 2 credentials and 3 logins." (the logins only when there are some). */
+export declare function uploadedMessage(entries: number, logins: number): string;
 /**
  * Run one cycle. `force` is "Upload now": it needs a GitHub token (and says so
  * if there is none), reads the gist afresh, and tries to write even inside the

package/dist/sync/enabled.d.ts

@@ -0,0 +1,2 @@
+/** On unless `OPENCODE_AUTH_LB_SYNC` is `0` / `false` / `no` / `off`. */
+export declare function syncEnabled(env?: NodeJS.ProcessEnv): boolean;

package/dist/sync/login-hooks.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The sync side of the refresh hooks: before a machine spends a login's
+ * single-use refresh token it looks at the gist, because another machine may
+ * have refreshed that login already.
+ *
+ * Runs inside the caller's refresh lock, so it never takes that lock again and
+ * never takes the cycle lock or writes the sync state (the cycle takes refresh
+ * locks while holding the cycle lock; the other order could deadlock).
+ */
+import type { PoolAccount } from '../types';
+import { type GhRunner } from './github-auth';
+/** The hook `refresh.ts` calls; `runGh` finds the GitHub token (a test replaces it). */
+export declare function createPullLogin(runGh?: GhRunner): (account: PoolAccount, _recovery: boolean) => Promise<boolean>;
+export declare const pullLogin: (account: PoolAccount, _recovery: boolean) => Promise<boolean>;

package/dist/sync/login-payload.d.ts

@@ -0,0 +1,40 @@
+export declare const MAX_LOGINS = 64;
+/** A set, not an object: a provider id from a gist must never resolve to an inherited member such as `constructor`. */
+export declare const LOGIN_PROVIDERS: ReadonlySet<string>;
+/** One shared login: the newest `(rev, at, refresh fingerprint)` of a key wins on every machine. */
+export interface LoginRecord {
+    /** `${providerID}:${accountId}`: the identity of the login across machines. */
+    key: string;
+    providerID: string;
+    label: string;
+    access: string;
+    refresh: string;
+    /** epoch ms the access token lapses. */
+    expires: number;
+    accountId: string;
+    orgId?: string;
+    /** epoch ms the login itself lapses, when known. */
+    refreshExpires?: number;
+    rev: number;
+    at: number;
+}
+export declare function loginKey(providerID: string, accountId: string): string;
+export declare function parseLogin(raw: unknown): LoginRecord | null;
+/** The logins in a stable order (by key), so equal lists produce equal payloads. */
+export declare function sortLogins(logins: readonly LoginRecord[]): LoginRecord[];
+/** A digest of the logins: when it changes, the gist is out of date. */
+export declare function loginsDigest(logins: readonly LoginRecord[]): string;
+/**
+ * The total order two machines share to pick the winner among copies of one
+ * login: revision, then time, then the refresh token's fingerprint (so even a
+ * tie of both is settled the same way everywhere). Positive when `a` is newer.
+ */
+export declare function compareLogins(a: Pick<LoginRecord, 'at' | 'refresh' | 'rev'>, b: Pick<LoginRecord, 'at' | 'refresh' | 'rev'>): number;
+/** What a payload's login list yields: the valid logins, every key listed, and how many could not be read. */
+export interface ParsedLogins {
+    logins: LoginRecord[];
+    loginsListed: Set<string>;
+    loginsUnreadable: number;
+}
+/** Parse a raw login list. A duplicate key keeps the first valid login; an unreadable one is counted, never imported. */
+export declare function parseLoginList(rawList: readonly unknown[]): ParsedLogins;

package/dist/sync/logins.d.ts

@@ -0,0 +1,63 @@
+import { type PoolAccount, type PoolFile } from '../types';
+import { type LoginRecord } from './login-payload';
+import { type SyncEntry } from './payload';
+/** On unless `OPENCODE_AUTH_LB_SYNC_LOGINS` is `0` / `false` / `no` / `off`. */
+export declare function loginsSyncEnabled(env?: NodeJS.ProcessEnv): boolean;
+/** The login keys the pool's rows hold. */
+export declare function heldMarks(accounts: readonly PoolAccount[]): Record<string, true>;
+/**
+ * This machine's shareable logins, one per key: a real OAuth login (a refresh
+ * token, not a Kimi API key or a setup-token), of a known account, that still
+ * works. Usage, cooldowns, sessions, `tokenGen`, the inference token and local
+ * ids never go in. Every login passes the receiver's own validation.
+ */
+export declare function ownLogins(pool: PoolFile): LoginRecord[];
+/**
+ * The logins to write: per key the winner of the gist's and this machine's
+ * copy. A gist login this machine has no copy of is carried over untouched; a
+ * login of this machine the gist lacks is added while there is room.
+ */
+export declare function mergeLogins(gist: readonly LoginRecord[], own: readonly LoginRecord[]): LoginRecord[];
+/** How many of this machine's logins are, as they are, what `next` lists. */
+export declare function ownCopies(next: readonly LoginRecord[], own: readonly LoginRecord[]): number;
+/**
+ * The digest of what this machine would publish: when it differs from the one
+ * stored at the last upload, the gist may be out of date. Without logins it is
+ * the entries' digest alone, so a machine that shares none keeps its old one.
+ */
+export declare function publishDigest(entries: readonly SyncEntry[], logins: readonly LoginRecord[]): string;
+/** Whether `row` is this machine's copy of `login`: the same key, and the same organization when both know it. */
+export declare function sameLogin(row: PoolAccount, login: LoginRecord): boolean;
+/** The version a row holds, comparable with a login's. */
+export declare function versionOf(row: PoolAccount): Pick<LoginRecord, 'at' | 'refresh' | 'rev'>;
+/**
+ * Put the gist's login onto the row that holds the same login, in one pool
+ * transaction that re-checks the row's (refresh, tokenGen) as
+ow was read:
+ * a row that moved on in the meantime is left to the next cycle. The bumped
+ * 	okenGen makes a refresh that is in flight lose its CAS. The row keeps its
+ * inference token, usage, cooldowns, sessions and label. The caller holds the
+ * row's refresh lock (the lock is not re-entrant).
+ */
+export declare function overwriteLocked(row: PoolAccount, login: LoginRecord): Promise<boolean>;
+/** What sync remembers about deleted rows, in and out of `applyLogins`. */
+export interface LoginMarks {
+    known: Readonly<Record<string, true>> | undefined;
+    suppressed: Readonly<Record<string, true>> | undefined;
+}
+export interface LoginsApplied {
+    /** Rows the gist's logins were put onto, or created. */
+    adopted: number;
+    known: Record<string, true>;
+    suppressed: Record<string, true>;
+}
+/**
+ * Bring the pool's logins in line with the gist's. First the deletion guard: a
+ * key that was held and has no row any more was deleted by the user, so it is
+ * suppressed and never imported; a suppressed key with a row again was logged
+ * in to again, so it is released (and outranks the gist's copy). Then every
+ * gist login that wins over this machine's copy is put onto the pool. A login
+ * that is not newer is ignored: this machine's copy is then the winner, and
+ * is written back.
+ */
+export declare function applyLogins(gist: readonly LoginRecord[], marks: LoginMarks, now: number): Promise<LoginsApplied>;

package/dist/sync/payload.d.ts

@@ -1,6 +1,8 @@
-export declare const PAYLOAD_VERSION = 2;
+import { type LoginRecord } from './login-payload';
+import { MAX_LABEL, printable } from './text';
+export { MAX_LABEL, printable };
+export declare const PAYLOAD_VERSION = 3;
 export declare const MAX_ENTRIES = 64;
-export declare const MAX_LABEL = 80;
 /** A machine's origin: 128 random bits as hex. Not a secret, and never derived from a host name. */
 export declare const ORIGIN_RE: RegExp;
 /** The providers a credential may sync for, and the shape its secret must have. */
@@ -21,16 +23,14 @@ export interface SyncEntry {
 }
 /** The identity of an entry across machines. */
 export declare function entryKey(entry: Pick<SyncEntry, 'origin' | 'id'>): string;
-/** `text` with those characters turned into spaces, trimmed. */
-export declare function printable(text: string): string;
 export declare function parseEntry(raw: unknown): SyncEntry | null;
 /** The entries in a stable order (by key), so equal lists produce equal payloads. */
 export declare function sortEntries(entries: readonly SyncEntry[]): SyncEntry[];
 /** A digest of the entries: when it changes, the gist is out of date. */
 export declare function entriesDigest(entries: readonly SyncEntry[]): string;
-/** The plaintext to encrypt. */
-export declare function buildPayload(entries: readonly SyncEntry[], at: number): string;
-/** A snapshot read back: when it was written, its valid entries, and every key it still lists. */
+/** The plaintext to encrypt: always the current version, entries and logins each in a stable order. */
+export declare function buildPayload(entries: readonly SyncEntry[], at: number, logins?: readonly LoginRecord[]): string;
+/** A snapshot read back: when it was written, its valid entries and logins, and every key it still lists. */
 export interface ParsedPayload {
     at: number;
     entries: SyncEntry[];
@@ -41,6 +41,12 @@ export interface ParsedPayload {
     listed: ReadonlySet<string>;
     /** How many entries could not be read at all: a writer must not rewrite what it cannot parse. */
     unreadable: number;
+    /** The valid logins (none in a version 2 snapshot). */
+    logins: LoginRecord[];
+    /** Keys of every listed login, valid or not. */
+    loginsListed: ReadonlySet<string>;
+    /** How many logins could not be read at all: as for entries, a writer must not rewrite them. */
+    loginsUnreadable: number;
 }
 /**
  * The snapshot in a decrypted payload. Unknown fields, unknown providers,

package/dist/sync/start.d.ts

@@ -1,5 +1,23 @@
+import { syncEnabled } from './enabled';
+import { type SyncEngine } from './engine';
 import { type SyncLoop } from './loop';
-/** On unless `OPENCODE_AUTH_LB_SYNC` is `0` / `false` / `no` / `off`. */
-export declare function syncEnabled(env?: NodeJS.ProcessEnv): boolean;
-/** Start the gist-sync schedule for this process; null when sync is switched off. */
+export { syncEnabled };
+/**
+ * Start the gist-sync schedule for this process; null when sync is switched
+ * off. With login sharing on it also plugs into the refresh path: a refresh is
+ * published at once, and a refresh about to happen first looks at the gist.
+ */
 export declare function startSync(): SyncLoop | null;
+export interface LoginPublishOptions {
+    engine?: SyncEngine;
+    timeoutMs?: number;
+}
+/**
+ * Publish a login that just landed, in the same breath: one sync cycle, so the
+ * machines that follow the gist get it without waiting for the schedule (the
+ * process may be a login command that exits right after). A no-op unless sync
+ * and login sharing are on and this machine follows a gist. Bounded, and it
+ * swallows every failure: a login never waits long for, or fails because of,
+ * its upload.
+ */
+export declare function publishAfterLogin(options?: LoginPublishOptions): Promise<void>;

package/dist/sync/state.d.ts

@@ -61,6 +61,10 @@ export interface SyncState {
     imported: Record<string, ImportedRef>;
     /** Entry key to why it was not imported. */
     skipped: Record<string, SkippedRef>;
+    /** Login keys this machine held a row for at the last pass: a key that has no row any more was deleted by the user. */
+    loginKnown?: Record<string, true>;
+    /** Login keys the user deleted here: never imported again until a row for the key exists once more. */
+    loginSuppressed?: Record<string, true>;
 }
 /**
  * A key-indexed map. Keys come from another machine, so the record has no
@@ -69,6 +73,8 @@ export interface SyncState {
  */
 export declare function newMap<T>(from?: Readonly<Record<string, T>>): Record<string, T>;
 export declare function newRefs(from?: Readonly<Record<string, ImportedRef>>): Record<string, ImportedRef>;
+/** A map of marks, or undefined when it holds none: a state without logins stays as compact as it was. */
+export declare function marks(from: Readonly<Record<string, true>> | undefined): Record<string, true> | undefined;
 export declare function readSyncState(): Promise<SyncState | null>;
 /**
  * Read-modify-write the state under a cross-process lock. `fn` returns the

package/dist/sync/text.d.ts

@@ -0,0 +1,5 @@
+/** `text` with those characters turned into spaces, trimmed. */
+export declare function printable(text: string): string;
+export declare function boundedString(value: unknown, max: number): string | undefined;
+/** The longest label a synced credential or login may carry. */
+export declare const MAX_LABEL = 80;

package/dist/token-mint.d.ts

@@ -1,6 +1,15 @@
 import type { ProviderAdapter } from './providers/types';
 import type { PoolAccount, PoolFile } from './types';
-/** On unless `OPENCODE_AUTH_LB_ANTHROPIC_AUTO_TOKEN` is `0` / `false` / `no` / `off`. */
+/**
+ * Off unless `OPENCODE_AUTH_LB_ANTHROPIC_AUTO_TOKEN` is `1` / `true` / `yes` /
+ * `on`. Verified against Anthropic's token endpoint: a refresh grant for
+ * `scope=user:inference&expires_in=31536000` is answered with an 8-hour token
+ * (the lifetime is ignored), and the refresh token it rotates to is narrowed
+ * to `user:inference` for good, so the login can no longer read its usage
+ * (`403 … user:profile`) and a full-scope refresh is refused (`invalid_scope`).
+ * The token is then too short to pool, so the grant only does harm. A
+ * long-lived token comes from a pasted `claude setup-token`.
+ */
 export declare function autoTokenEnabled(env?: NodeJS.ProcessEnv): boolean;
 /** A row whose OAuth login should mint it a token: it has none, or its minted one nears its end. */
 export declare function tokenDue(account: PoolAccount, now: number): boolean;

package/dist/types.d.ts

@@ -124,6 +124,16 @@ export interface PoolAccount {
      * days, as Claude Code does.
      */
     refreshExpires?: number;
+    /**
+     * The SHARED version of the row's OAuth login (gist sync orders machines'
+     * copies of one login by it): 1 when the login was created, plus one for
+     * every re-login, committed refresh rotation and minted rotation (see
+     * `src/login-rev.ts`). Absent on rows without an OAuth login and on legacy
+     * rows (read as 1).
+     */
+    loginRev?: number;
+    /** epoch ms `loginRev` was last bumped (a tie-break between equal revisions). Absent reads as 0. */
+    loginAt?: number;
     /**
      * Organization the row's credentials act for (Anthropic), when known. A
      * setup-token carries no account identity — only the organization its

package/dist/usage-merge.d.ts

@@ -1,4 +1,8 @@
-import type { UsageWindow } from './types';
+import { type ScoreConfig } from './scheduler/score-core';
+import type { PoolAccount, UsageWindow } from './types';
+export declare const MAX_TRANSIENT_COOLDOWN_MS: number;
+/** Call only after fresh usage was measured; cached headroom cannot disprove a later 429. */
+export declare function reconcileQuotaCooldown(account: PoolAccount, cfg: ScoreConfig, now: number): void;
 /**
  * Roll a FIXED weekly reset anchor forward to its next occurrence strictly after
  * `now`. Weekly windows are anchored per account (verified live: Anthropic's

package/dist/usage-poll.d.ts

@@ -0,0 +1,11 @@
+import { type LoopTimers } from './sync/loop';
+interface UsagePollDeps {
+    now?: () => number;
+    refresh?: (now: number) => Promise<void>;
+    timers?: LoopTimers;
+}
+export declare function startUsagePoll(deps?: UsagePollDeps): {
+    tick: () => Promise<void>;
+    dispose(): Promise<void>;
+};
+export {};

package/dist/usage-refresh.d.ts

@@ -1,18 +1,7 @@
 import type { ProviderAdapter } from './providers/types';
 import { type PoolFile } from './types';
 export declare const USAGE_REFRESH_TTL_MS: number;
-/**
- * Max lifetime of a TRANSIENT (non-quota) cooldown. fetch.ts cools a thrown
- * network error or a header-less 429/402 for at most `ACCOUNT_COOLDOWN_MS`
- * (5min) and an auth 401/403 for `AUTH_COOLDOWN_MS` (2min); ONLY a quota 429's
- * `Retry-After` writes a cooldown beyond this. So a cooldown whose remainder
- * still exceeds this bound is necessarily quota-derived — the one class that can
- * outlive its own usage window after an out-of-band reset (see the stale-cooldown
- * reconciliation below). Kept `=== ACCOUNT_COOLDOWN_MS` by a drift-guard test;
- * defined locally because importing it from fetch.ts (which imports THIS module)
- * would form a cycle.
- */
-export declare const MAX_TRANSIENT_COOLDOWN_MS: number;
+export { MAX_TRANSIENT_COOLDOWN_MS } from './usage-merge';
 /**
  * Test-only window into the module-private `lastPoll` throttle map. Never
  * imported by production code — only by usage-refresh tests that need to