opencode-auth-load-balancer 0.5.1 → 0.6.0

package/dist/sync/payload.d.ts

@@ -0,0 +1,50 @@
+export declare const PAYLOAD_VERSION = 2;
+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. */
+/** A Map, not an object: a provider id from a gist must never resolve to an inherited member such as `constructor`. */
+export declare const SECRET_SHAPES: ReadonlyMap<string, RegExp>;
+/** One synced credential, identified by the listing machine and its row id there. */
+export interface SyncEntry {
+    /** The machine that listed it. */
+    origin: string;
+    /** That machine's row id. */
+    id: string;
+    providerID: string;
+    label: string;
+    /** A Claude inference token, or a Kimi API key. */
+    secret: string;
+    /** epoch ms a minted Claude token lapses. */
+    expiresAt?: number;
+}
+/** 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. */
+export interface ParsedPayload {
+    at: number;
+    entries: SyncEntry[];
+    /**
+     * Keys of every listed entry, valid or not. An entry that fails validation is
+     * not imported, but it is still listed: it must never read as "removed".
+     */
+    listed: ReadonlySet<string>;
+    /** How many entries could not be read at all: a writer must not rewrite what it cannot parse. */
+    unreadable: number;
+}
+/**
+ * The snapshot in a decrypted payload. Unknown fields, unknown providers,
+ * malformed entries and duplicates are dropped; an unknown version, a
+ * malformed envelope, a missing timestamp, or too many entries is an error.
+ */
+export declare function parsePayload(text: string): ParsedPayload;

package/dist/sync/start.d.ts

@@ -0,0 +1,5 @@
+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 declare function startSync(): SyncLoop | null;

package/dist/sync/state.d.ts

@@ -0,0 +1,79 @@
+/** A pool row a synced entry landed on, and a digest of the secret it carried. */
+export interface ImportedRef {
+    accountId: string;
+    fingerprint: string;
+}
+/**
+ * An entry that was not imported because the account already has a credential:
+ * the digest of the entry's secret, and the row in the way with the digest of
+ * the static credential it held ('' when it holds none, such as an OAuth login).
+ * While that row still holds it, the entry is not probed again.
+ */
+export interface SkippedRef {
+    fingerprint: string;
+    blocker: string;
+    holds: string;
+}
+/**
+ * The latest outcome, for the TUI (its own file: there is nowhere else to say
+ * "no GitHub token" before any state exists). `reqAt` echoes the request it
+ * answers. Never holds the link or key.
+ */
+export interface SyncStatus {
+    at: number;
+    ok: boolean;
+    message: string;
+    reqAt?: number;
+}
+/**
+ * What this machine can do besides downloading, as the last cycle found it:
+ * upload (`ok`), or not for lack of a GitHub login, because the GitHub account
+ * cannot update the gist, or because the gist holds entries this version
+ * cannot read and must not rewrite.
+ */
+export type SyncWrite = 'ok' | 'no-token' | 'denied' | 'unreadable';
+/** Everything sync remembers. Holds the encryption key: the file is owner-only and not part of the pool. */
+export interface SyncState {
+    v: 1;
+    gistId: string;
+    /** The link's key, base64url. */
+    key: string;
+    /** This machine created the gist, so it may show the link. */
+    creator: boolean;
+    /** The creator's GitHub login, for building the link. */
+    owner?: string;
+    write?: SyncWrite;
+    /** No upload attempt before this time: the back-off after the GitHub account was refused. */
+    writeCheckAt?: number;
+    etag?: string;
+    syncedAt?: number;
+    /** Digest of this machine's own entries as of the last cycle that brought the gist up to date. */
+    uploadedDigest?: string;
+    /** The t stamped on the last upload: the next one is strictly later, whatever the clock does. */
+    uploadedAt?: number;
+    /** The newest snapshot t applied: an older ciphertext replayed from the gist is refused. */
+    appliedAt?: number;
+    /** The next scheduled download (and upload check). */
+    pollAt?: number;
+    /** No background download or upload before this time: the retry delay and rate-limit back-off after a failure. */
+    retryAt?: number;
+    /** Entry key (origin/id) to the local row it was imported into. */
+    imported: Record<string, ImportedRef>;
+    /** Entry key to why it was not imported. */
+    skipped: Record<string, SkippedRef>;
+}
+/**
+ * A key-indexed map. Keys come from another machine, so the record has no
+ * prototype: `__proto__`, `constructor` and `prototype` are then ordinary
+ * keys, and a lookup never finds an inherited member.
+ */
+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>;
+export declare function readSyncState(): Promise<SyncState | null>;
+/**
+ * Read-modify-write the state under a cross-process lock. `fn` returns the
+ * next state, or null to forget everything (the file is removed).
+ */
+export declare function updateSyncState(fn: (current: SyncState | null) => SyncState | null): Promise<SyncState | null>;
+/** Publish the outcome for the TUI to show; best effort, since a lost line only loses a message. */
+export declare function writeSyncStatus(status: SyncStatus): Promise<void>;

package/dist/sync/timing.d.ts

@@ -0,0 +1,4 @@
+/** A subscriber asks GitHub at most this often; the due time is persisted, so every window shares it. */
+export declare const POLL_MS: number;
+/** After a failed upload the publisher waits this long (or as long as GitHub asked) before the next try. */
+export declare const PUBLISH_RETRY_MS: number;

package/dist/token-mint.d.ts

@@ -0,0 +1,25 @@
+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`. */
+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;
+/**
+ * Mint `accountId` a token under its refresh lock, since the grant spends the
+ * single-use refresh token: the row is re-read once the lock is held (another
+ * process may have minted already), and the result lands only while the row
+ * still holds the refresh token spent — whose rotated successor it keeps
+ * even when the token itself is not pooled. Resolves whether a token landed;
+ * rejects when the grant fails.
+ */
+export declare function mintToken(adapter: ProviderAdapter, accountId: string): Promise<boolean>;
+/**
+ * Mint every due row of `adapter`'s provider a token, in the background of
+ * startup and the request path. A process asks for each row at most once
+ * per RETRY_MS, and a failed grant leaves the row as it was: the grant is a
+ * refresh like any other, so a dead login surfaces through the regular
+ * refresh instead.
+ */
+export declare function maintainTokens(adapter: ProviderAdapter, now: number, poolSnapshot?: PoolFile): Promise<void>;
+/** Mint a just-landed OAuth login its token at once, so the login completes paired. */
+export declare function mintAtLogin(adapter: ProviderAdapter, account: PoolAccount): Promise<boolean>;

package/dist/types.d.ts

@@ -33,7 +33,46 @@ export interface TokenSet {
     expires: number;
     /** Provider account id (e.g. chatgpt-account-id), when present. */
     accountId?: string;
+    /** Organization the credential acts for (Anthropic), when known: see `PoolAccount.orgId`. */
+    orgId?: string;
+    /**
+     * A long-lived bearer that only serves inference (Claude's `claude
+     * setup-token`). It joins a row as its `inferenceToken` instead of
+     * replacing the row's OAuth login.
+     */
+    inferenceOnly?: boolean;
+    /** epoch ms an `inferenceOnly` token lapses, when known: see `PoolAccount.inferenceExpires`. */
+    inferenceExpires?: number;
+    /** epoch ms the OAuth login itself expires: see `PoolAccount.refreshExpires`. */
+    refreshExpires?: number;
+    /**
+     * Usage measured while logging in (a setup-token's validation probe, an
+     * OAuth login's first poll). It seeds the row, and its weekly reset anchor
+     * tells pairing which row the login belongs to.
+     */
+    usage?: UsageSnapshot;
+}
+/** When and why a login stopped working. */
+export interface LostLogin {
+    at: number;
+    reason: string;
 }
+/**
+ * The logins of a row the provider refused for good: `oauth` when its
+ * refresh was refused (invalid_grant), `token` when its static credential (a
+ * setup-token or API key) answered 401.
+ */
+export interface LostLogins {
+    oauth?: LostLogin;
+    token?: LostLogin;
+}
+/**
+ * `expires` stamped on a static credential (a Kimi API key, a Claude
+ * setup-token): it has no refresh token behind it, so `needsRefresh` must
+ * never fire — one that stops working answers 401 instead. Finite, so the
+ * pool store's `Number.isFinite(expires)` normalization keeps it.
+ */
+export declare const STATIC_CREDENTIAL_EXPIRES: number;
 /** One pooled credential. */
 export type CooldownKind = 'quota' | 'auth' | 'transient';
 export interface PoolAccount {
@@ -56,6 +95,42 @@ export interface PoolAccount {
     tokenGen?: number;
     /** Provider account id (e.g. chatgpt-account-id), or null. */
     accountId: string | null;
+    /**
+     * A long-lived inference-only bearer (Claude's `claude setup-token`). When
+     * set it serves every request, and the row's OAuth login (`access` +
+     * `refresh`), if any, only polls usage — so an OAuth logout no longer stops
+     * inference. On a row without an OAuth login, `access` mirrors it with
+     * `refresh: ''` and a never-due expiry, like any static credential.
+     */
+    inferenceToken?: string;
+    /**
+     * epoch ms `inferenceToken` lapses, known only for a token the plugin
+     * minted from the row's OAuth login (`src/token-mint.ts`), which renews it
+     * ahead of time. A pasted token's lifetime is unknown, so it has none.
+     */
+    inferenceExpires?: number;
+    /**
+     * Logins of this row the provider refused for good, each kept with when
+     * and why until that login is replaced. While the row's other login still
+     * works the row keeps serving on it, and the lost one shows as `oauth
+     * re-login` / `token re-login` — distinct from a whole-row `re-login`,
+     * which is what remains when nothing works.
+     */
+    lostLogins?: LostLogins;
+    /**
+     * epoch ms the row's OAuth login itself expires — its refresh token, from
+     * `refresh_token_expires_in` or else Claude Code's own 30-day assumption at
+     * login. Refreshes do not extend it, so the dashboards warn in its last
+     * days, as Claude Code does.
+     */
+    refreshExpires?: number;
+    /**
+     * Organization the row's credentials act for (Anthropic), when known. A
+     * setup-token carries no account identity — only the organization its
+     * responses report — so this is the key that pairs it with its account's
+     * OAuth login on one row.
+     */
+    orgId?: string;
     usage: UsageSnapshot;
     /** epoch ms; the account is skipped until this time. 0 = no cooldown. */
     cooldownUntil: number;

package/dist/util.d.ts

@@ -40,6 +40,13 @@ export declare function isFiniteNumber(v: unknown): v is number;
  * copy by design — the TUI runtime cannot import `src/`.
  */
 export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * A one-line summary of a rejected HTTP response for the dashboards: the
+ * status plus what the common JSON error envelopes name — RFC 6749's
+ * `{error, error_description}`, Anthropic's and OpenAI's `{error: {type,
+ * message}}` — or else the start of the raw body.
+ */
+export declare function errorSummary(status: number, body: string): string;
 /**
  * Collect the `text` of every content block into one string. A message's
  * `content` arrives as either a plain string (passed through) or an array of

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-auth-load-balancer",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Load-balance opencode requests across multiple Anthropic (Claude) and OpenAI (Codex) OAuth accounts and Kimi Code subscriptions, weighted primarily by weekly usage with drain-before-reset scheduling.",
   "type": "module",
   "license": "MIT",