@askalf/dario 6.20.3 → 6.22.0

package/README.md

@@ -213,7 +213,7 @@ dario is the routing layer of **[Own Your Stack](https://github.com/askalf)**, o
 
 dario is part of **Own Your Stack**, the open toolkit behind **[Sprayberry Labs](https://sprayberrylabs.com)**, the software studio with one human on staff, run by [askalf](https://askalf.org), the AI operation these tools are part of.
 
-Built in the open, scars included. Follow the build: **[@ask_alf](https://x.com/ask_alf)** · **[ownyourstack.sprayberrylabs.com](https://ownyourstack.sprayberrylabs.com)**
+Built in the open, scars included. Follow the build: **[@ask_alf](https://x.com/ask_alf)**
 
 ### Sponsors
 

package/dist/account-sync.d.ts

@@ -19,32 +19,81 @@
  * made after it, so the instances' clocks must agree (NTP) to well under the
  * time between a removal and a later login.
  *
+ * Admin API logins that are started but not yet completed ride the same
+ * service (`/logins/<claude|codex>/...`, see SharedPendingLogins below), so
+ * a login started on one replica completes on another.
+ *
  * Every call fails open: with the service unreachable an instance serves the
  * accounts on its own disk, logging once per outage. The registry holds
  * every seat's full credentials, refresh tokens included, with no expiry, so
  * DARIO_REFRESH_LOCK_TOKEN reads every seat; that is why this is an opt-in
  * separate from `--pool-shared-state`.
+ *
+ * ChatGPT seats ride the same switch and the same rules in a registry of their
+ * own (`/codex-accounts/...`, codex-account-sync.ts), since aliases are a
+ * namespace per engine: a second AccountSync, with an AccountRegistry that
+ * says where its records live and how to read them.
  */
 import { type AccountCredentials } from './accounts.js';
+/** What the sync needs of a record, whichever engine it belongs to. */
+export interface SyncedCredentials {
+    alias: string;
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+    grantedAt?: number;
+}
 /** Where the sync reads and writes this instance's accounts. accounts.ts in production; a test passes its own. */
-export interface AccountSyncStore {
-    loadAll(): Promise<AccountCredentials[]>;
-    save(creds: AccountCredentials, opts: {
+export interface AccountSyncStore<R extends SyncedCredentials = AccountCredentials> {
+    loadAll(): Promise<R[]>;
+    save(creds: R, opts: {
         fetchedAt: number;
         removedAt?: number;
     }): Promise<{
         saved: boolean;
-        replaced?: AccountCredentials;
+        replaced?: R;
     }>;
     remove(alias: string, removedAt: number): Promise<boolean>;
     /** Removals this process made, alias to epoch ms. */
     localRemovals(): ReadonlyMap<string, number>;
 }
 export declare const accountFileStore: AccountSyncStore;
+/** A started, not yet completed admin API login: the PKCE secrets and when they lapse. */
+export interface SharedLogin {
+    codeVerifier: string;
+    state: string;
+    expiresAt: number;
+}
+/** Which engine's pending logins: they are separate namespaces, as the seats are. */
+export type LoginEngine = 'claude' | 'codex';
+/**
+ * Pending admin API logins held on the shared service, so any instance can
+ * complete one that another started. The verifier and state are secrets and
+ * are stored as the registry stores credentials. 'failed' is the service
+ * not answering or not knowing the endpoint (an older service); the caller
+ * then keeps the login on this instance only.
+ */
+export interface SharedPendingLogins {
+    /**
+     * Publish a login for `alias`, replacing any other. 'full' when the service already holds its cap of other aliases.
+     * With `create`, a live login under the alias is left alone and the answer is 'taken'.
+     */
+    put(engine: LoginEngine, alias: string, login: SharedLogin, ttlMs: number, create?: boolean): Promise<'stored' | 'full' | 'taken' | 'failed'>;
+    /** The login for `alias`, null when the service holds none (or it lapsed). Does not consume it. */
+    get(engine: LoginEngine, alias: string): Promise<SharedLogin | null | 'failed'>;
+    /**
+     * Delete the login for `alias` whose state is `state`, and only that one. True when this call removed
+     * it live; false when none was there, it lapsed, or another login has replaced it (another instance
+     * completed or restarted it first), which the caller must treat as lost.
+     */
+    remove(engine: LoginEngine, alias: string, state: string): Promise<boolean | 'failed'>;
+    /** The aliases with a pending login on any instance. */
+    aliases(engine: LoginEngine): Promise<string[] | 'failed'>;
+}
 /** What one sync changed on this instance, handed to the running proxy. */
-export interface AccountSyncChange {
+export interface AccountSyncChange<R extends SyncedCredentials = AccountCredentials> {
     /** Records the pool lacks or holds older credentials for. */
-    records: AccountCredentials[];
+    records: R[];
     /** Seats the pool still holds whose account was removed. */
     removed: Array<{
         alias: string;
@@ -72,19 +121,35 @@ export interface AccountSyncStatus {
     errors: number;
     lastError: string | null;
 }
-export interface AccountSyncOptions {
+/** One engine's registry on the service: where its records live and how to read them. */
+export interface AccountRegistry<R extends SyncedCredentials> {
+    /** The service path it answers under: `<path>/list`, `<path>/<alias>/put`, `<path>/<alias>/remove`. */
+    path: string;
+    /** What the log calls one record. */
+    noun: string;
+    store: AccountSyncStore<R>;
+    /** A registry record complete enough to serve from, stored under its own alias. */
+    isRecord(alias: string, rec: unknown): rec is R;
+    /** Names a record in a log line, never with its credentials. */
+    describe(creds: R): string;
+    /** Whether two records under one alias are different subscriptions. */
+    differ(a: R, b: R): boolean;
+}
+export interface AccountSyncOptions<R extends SyncedCredentials = AccountCredentials> {
     baseUrl: string;
     token: string;
     /** Sync interval, ms. Default 15000. */
     intervalMs?: number;
-    store?: AccountSyncStore;
+    store?: AccountSyncStore<R>;
     log?: (line: string) => void;
+    /** Default: the Claude accounts. */
+    registry?: AccountRegistry<R>;
 }
 export declare const DEFAULT_ACCOUNT_SYNC_INTERVAL_MS = 15000;
-export interface AccountSyncPlan {
+export interface AccountSyncPlan<R extends SyncedCredentials = AccountCredentials> {
     /** Registry records to write here, each with the removal time it must outlive. */
     save: Array<{
-        creds: AccountCredentials;
+        creds: R;
         removedAt?: number;
     }>;
     /** Local files a removal covers. */
@@ -93,7 +158,7 @@ export interface AccountSyncPlan {
         removedAt: number;
     }>;
     /** Local records newer than the registry's. */
-    push: AccountCredentials[];
+    push: R[];
 }
 /** The latest removal of `alias` either side knows of, or undefined. */
 export declare function removalTime(alias: string, markers: ReadonlyMap<string, number>, localRemovals: ReadonlyMap<string, number>): number | undefined;
@@ -104,7 +169,7 @@ export declare function removalTime(alias: string, markers: ReadonlyMap<string,
  * newer wins. The registry's goes to disk, ours goes to the registry, and a
  * local file no record outlives is removed.
  */
-export declare function planAccountSync(local: readonly AccountCredentials[], registry: ReadonlyMap<string, AccountCredentials>, markers: ReadonlyMap<string, number>, localRemovals: ReadonlyMap<string, number>): AccountSyncPlan;
+export declare function planAccountSync<R extends SyncedCredentials>(local: readonly R[], registry: ReadonlyMap<string, R>, markers: ReadonlyMap<string, number>, localRemovals: ReadonlyMap<string, number>): AccountSyncPlan<R>;
 /** A registry record complete enough to serve from, stored under its own alias. */
 export declare function isRegistryRecord(alias: string, rec: unknown): rec is AccountCredentials;
 /** How `dario accounts remove` ended with the shared account registry on. */
@@ -124,16 +189,19 @@ export type SharedRemovalResult =
  * goes only once the registry took the removal, and only when it holds no
  * login granted after it. Throws when the service does not answer.
  */
-export declare function removeAccountEverywhere(baseUrl: string, token: string, alias: string, opts?: {
-    store?: AccountSyncStore;
+export declare function removeAccountEverywhere<R extends SyncedCredentials = AccountCredentials>(baseUrl: string, token: string, alias: string, opts?: {
+    store?: AccountSyncStore<R>;
     removedAt?: number;
+    registry?: AccountRegistry<R>;
 }): Promise<SharedRemovalResult>;
-export declare class AccountSync {
+export declare class AccountSync<R extends SyncedCredentials = AccountCredentials> implements SharedPendingLogins {
     readonly intervalMs: number;
     private readonly baseUrl;
     private readonly token;
+    private readonly registry;
     private readonly store;
     private readonly log;
+    private readonly tag;
     private onChange;
     private live;
     private timer;
@@ -143,14 +211,14 @@ export declare class AccountSync {
     private markers;
     private down;
     private stats;
-    constructor(opts: AccountSyncOptions);
+    constructor(opts: AccountSyncOptions<R>);
     /**
      * Connect a running pool: `live` reads a seat's credentials, `onChange`
      * gets what each later sync changed. Until then a sync updates the
      * accounts directory only, which is all the startup sync needs, since the
      * pool loads from that directory after it.
      */
-    attach(live: (alias: string) => LiveSeat | undefined, onChange: (change: AccountSyncChange) => Promise<void> | void): void;
+    attach(live: (alias: string) => LiveSeat | undefined, onChange: (change: AccountSyncChange<R>) => Promise<void> | void): void;
     /** Sync on the interval. The timer never keeps the process alive. */
     start(): void;
     stop(): void;
@@ -162,8 +230,14 @@ export declare class AccountSync {
      * login the sync just removed.
      */
     removalOf(alias: string): number | undefined;
+    private loginPath;
+    private loginFailed;
+    put(engine: LoginEngine, alias: string, login: SharedLogin, ttlMs: number, create?: boolean): Promise<'stored' | 'full' | 'taken' | 'failed'>;
+    get(engine: LoginEngine, alias: string): Promise<SharedLogin | null | 'failed'>;
+    remove(engine: LoginEngine, alias: string, state: string): Promise<boolean | 'failed'>;
+    aliases(engine: LoginEngine): Promise<string[] | 'failed'>;
     /** One sync. Null when the registry could not be read; never throws. */
-    syncOnce(): Promise<AccountSyncChange | null>;
+    syncOnce(): Promise<AccountSyncChange<R> | null>;
     private run;
     /**
      * One POST to the service. Null on any failure: the caller carries on with

package/dist/account-sync.js

@@ -19,11 +19,20 @@
  * made after it, so the instances' clocks must agree (NTP) to well under the
  * time between a removal and a later login.
  *
+ * Admin API logins that are started but not yet completed ride the same
+ * service (`/logins/<claude|codex>/...`, see SharedPendingLogins below), so
+ * a login started on one replica completes on another.
+ *
  * Every call fails open: with the service unreachable an instance serves the
  * accounts on its own disk, logging once per outage. The registry holds
  * every seat's full credentials, refresh tokens included, with no expiry, so
  * DARIO_REFRESH_LOCK_TOKEN reads every seat; that is why this is an opt-in
  * separate from `--pool-shared-state`.
+ *
+ * ChatGPT seats ride the same switch and the same rules in a registry of their
+ * own (`/codex-accounts/...`, codex-account-sync.ts), since aliases are a
+ * namespace per engine: a second AccountSync, with an AccountRegistry that
+ * says where its records live and how to read them.
  */
 import { loadAllAccounts, saveSharedAccount, removeSharedAccount, localAccountRemovals, credentialsAreNewer, grantedAfter, isValidAccountAlias, } from './accounts.js';
 import { maskEmail } from './pool.js';
@@ -34,6 +43,18 @@ export const accountFileStore = {
     remove: removeSharedAccount,
     localRemovals: localAccountRemovals,
 };
+function parseSharedLogin(raw) {
+    const r = raw;
+    if (!r || typeof r !== 'object')
+        return null;
+    if (typeof r.codeVerifier !== 'string' || r.codeVerifier.length === 0)
+        return null;
+    if (typeof r.state !== 'string' || r.state.length === 0)
+        return null;
+    if (typeof r.expiresAt !== 'number' || !Number.isFinite(r.expiresAt))
+        return null;
+    return { codeVerifier: r.codeVerifier, state: r.state, expiresAt: r.expiresAt };
+}
 export const DEFAULT_ACCOUNT_SYNC_INTERVAL_MS = 15_000;
 const CALL_TIMEOUT_MS = 3_000;
 /** The latest removal of `alias` either side knows of, or undefined. */
@@ -83,12 +104,12 @@ export function isRegistryRecord(alias, rec) {
         && typeof r.expiresAt === 'number' && Number.isFinite(r.expiresAt)
         && Array.isArray(r.scopes) && typeof r.deviceId === 'string' && typeof r.accountUuid === 'string';
 }
-function parseRegistry(raw) {
+function parseRegistry(raw, isRecord) {
     const out = new Map();
     if (!raw || typeof raw !== 'object')
         return out;
     for (const [alias, rec] of Object.entries(raw))
-        if (isRegistryRecord(alias, rec))
+        if (isRecord(alias, rec))
             out.set(alias, rec);
     return out;
 }
@@ -121,9 +142,10 @@ async function registryCall(baseUrl, token, path, body) {
  * login granted after it. Throws when the service does not answer.
  */
 export async function removeAccountEverywhere(baseUrl, token, alias, opts = {}) {
-    const store = opts.store ?? accountFileStore;
+    const registry = opts.registry ?? CLAUDE_REGISTRY;
+    const store = opts.store ?? registry.store;
     const removedAt = opts.removedAt ?? Date.now();
-    const res = await registryCall(baseUrl, token, `/accounts/${encodeURIComponent(alias)}/remove`, { removedAt });
+    const res = await registryCall(baseUrl, token, `${registry.path}/${encodeURIComponent(alias)}/remove`, { removedAt });
     if (res.removed !== true)
         return 'registry-newer';
     if (await store.remove(alias, removedAt))
@@ -139,12 +161,22 @@ export async function removeAccountEverywhere(baseUrl, token, alias, opts = {})
 function describeAccount(c) {
     return maskEmail(c.accountEmail) ?? c.accountId ?? 'unknown account';
 }
+const CLAUDE_REGISTRY = {
+    path: '/accounts',
+    noun: 'account',
+    store: accountFileStore,
+    isRecord: isRegistryRecord,
+    describe: describeAccount,
+    differ: (a, b) => !!a.accountId && !!b.accountId && a.accountId !== b.accountId,
+};
 export class AccountSync {
     intervalMs;
     baseUrl;
     token;
+    registry;
     store;
     log;
+    tag;
     onChange = null;
     live = null;
     timer = null;
@@ -166,8 +198,10 @@ export class AccountSync {
         this.baseUrl = opts.baseUrl.replace(/\/+$/, '');
         this.token = opts.token;
         this.intervalMs = clampTimerMs(Math.max(1_000, opts.intervalMs ?? DEFAULT_ACCOUNT_SYNC_INTERVAL_MS));
-        this.store = opts.store ?? accountFileStore;
+        this.registry = opts.registry ?? CLAUDE_REGISTRY;
+        this.store = opts.store ?? this.registry.store;
         this.log = opts.log ?? ((line) => console.error(line));
+        this.tag = `[dario] shared ${this.registry.noun}s:`;
     }
     /**
      * Connect a running pool: `live` reads a seat's credentials, `onChange`
@@ -203,6 +237,42 @@ export class AccountSync {
     removalOf(alias) {
         return removalTime(alias, this.markers, this.store.localRemovals());
     }
+    loginPath(engine, alias, action) {
+        return `/logins/${engine}/${encodeURIComponent(alias)}/${action}`;
+    }
+    // Never logs the login: the line carries the alias and the transport error only.
+    loginFailed(what, alias) {
+        this.log(`${this.tag} could not ${what} the pending login for "${alias}" on the service (${this.stats.lastError ?? 'no answer'}); using this instance's copy`);
+        return 'failed';
+    }
+    async put(engine, alias, login, ttlMs, create = false) {
+        const out = await this.call(this.loginPath(engine, alias, 'put'), create ? { login, ttlMs, create: true } : { login, ttlMs });
+        if (!out)
+            return this.loginFailed('publish', alias);
+        if (out.stored === true)
+            return 'stored';
+        if (out.full === true)
+            return 'full';
+        return out.taken === true ? 'taken' : this.loginFailed('publish', alias);
+    }
+    async get(engine, alias) {
+        const out = await this.call(this.loginPath(engine, alias, 'get'), {});
+        if (!out)
+            return this.loginFailed('read', alias);
+        return parseSharedLogin(out.login);
+    }
+    async remove(engine, alias, state) {
+        const out = await this.call(this.loginPath(engine, alias, 'remove'), { state });
+        if (!out)
+            return this.loginFailed('remove', alias);
+        return out.removed === true;
+    }
+    async aliases(engine) {
+        const out = await this.call(`/logins/${engine}/list`, {});
+        if (!out)
+            return 'failed';
+        return Array.isArray(out.aliases) ? out.aliases.filter((a) => typeof a === 'string') : [];
+    }
     /** One sync. Null when the registry could not be read; never throws. */
     syncOnce() {
         if (this.queued)
@@ -212,7 +282,7 @@ export class AccountSync {
             return this.run().catch((err) => {
                 this.stats.errors++;
                 this.stats.lastError = err instanceof Error ? err.message : String(err);
-                this.log(`[dario] shared accounts: sync failed (${this.stats.lastError}); retrying on the next sync`);
+                this.log(`${this.tag} sync failed (${this.stats.lastError}); retrying on the next sync`);
                 return null;
             });
         });
@@ -227,17 +297,17 @@ export class AccountSync {
         for (const [alias, at] of this.store.localRemovals()) {
             if ((this.published.get(alias) ?? -Infinity) >= at)
                 continue;
-            const res = await this.call(`/accounts/${encodeURIComponent(alias)}/remove`, { removedAt: at });
+            const res = await this.call(`${this.registry.path}/${encodeURIComponent(alias)}/remove`, { removedAt: at });
             if (!res)
                 break;
             this.published.set(alias, at);
             this.stats.removalsPublished++;
         }
         const fetchedAt = Date.now();
-        const res = await this.call('/accounts/list', {});
+        const res = await this.call(`${this.registry.path}/list`, {});
         if (!res)
             return null;
-        const registry = parseRegistry(res.accounts);
+        const registry = parseRegistry(res.accounts, this.registry.isRecord);
         const markers = parseMarkers(res.removed);
         this.markers = markers;
         this.stats.registryAccounts = registry.size;
@@ -260,7 +330,7 @@ export class AccountSync {
             kept.delete(alias);
             removed.push({ alias, removedAt });
             this.stats.removed++;
-            this.log(`[dario] shared accounts: removed account "${alias}"; it was removed on another instance`);
+            this.log(`${this.tag} removed ${this.registry.noun} "${alias}"; it was removed on another instance`);
         }
         for (const { creds, removedAt } of plan.save) {
             const out = await this.store.save(creds, removedAt === undefined ? { fetchedAt } : { fetchedAt, removedAt });
@@ -270,13 +340,13 @@ export class AccountSync {
             this.stats.saved++;
             const was = out.replaced;
             if (!was) {
-                this.log(`[dario] shared accounts: added account "${creds.alias}" (${describeAccount(creds)}) from the registry`);
+                this.log(`${this.tag} added ${this.registry.noun} "${creds.alias}" (${this.registry.describe(creds)}) from the registry`);
             }
-            else if (was.accountId && creds.accountId && was.accountId !== creds.accountId) {
+            else if (this.registry.differ(was, creds)) {
                 // Aliases are one namespace across every instance. Two instances
                 // that each logged a different subscription in under one alias
                 // (`login`, most often) keep only the newer grant.
-                this.log(`[dario] shared accounts: account "${creds.alias}" here was ${describeAccount(was)} and is now ${describeAccount(creds)}, a newer login under the same alias on another instance; aliases are shared across instances, so give each subscription its own alias`);
+                this.log(`${this.tag} ${this.registry.noun} "${creds.alias}" here was ${this.registry.describe(was)} and is now ${this.registry.describe(creds)}, a newer login under the same alias on another instance; aliases are shared across instances, so give each subscription its own alias`);
             }
         }
         for (const creds of plan.push) {
@@ -285,14 +355,14 @@ export class AccountSync {
             const removedSince = this.store.localRemovals().get(creds.alias);
             if (!grantedAfter(creds, removedSince))
                 continue;
-            const out = await this.call(`/accounts/${encodeURIComponent(creds.alias)}/put`, { credentials: creds });
+            const out = await this.call(`${this.registry.path}/${encodeURIComponent(creds.alias)}/put`, { credentials: creds });
             if (!out)
                 break;
             if (!out.stored)
                 continue;
             this.stats.pushed++;
             if (!registry.has(creds.alias))
-                this.log(`[dario] shared accounts: published account "${creds.alias}" to the registry`);
+                this.log(`${this.tag} published ${this.registry.noun} "${creds.alias}" to the registry`);
         }
         const change = { records: [], removed };
         if (this.live) {
@@ -334,7 +404,7 @@ export class AccountSync {
             this.stats.lastOkAt = Date.now();
             if (this.down) {
                 this.down = false;
-                this.log(`[dario] shared accounts: service reachable again (${this.baseUrl})`);
+                this.log(`${this.tag} service reachable again (${this.baseUrl})`);
             }
             return out;
         }
@@ -343,7 +413,7 @@ export class AccountSync {
             this.stats.lastError = err instanceof Error ? err.message : String(err);
             if (!this.down) {
                 this.down = true;
-                this.log(`[dario] shared accounts: ${this.baseUrl} unreachable (${this.stats.lastError}); serving the accounts on this instance's disk until it answers again`);
+                this.log(`${this.tag} ${this.baseUrl} unreachable (${this.stats.lastError}); serving the accounts on this instance's disk until it answers again`);
             }
             return null;
         }

package/dist/admin-api.d.ts

@@ -77,6 +77,7 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { CodexSeatState } from './codex-accounts.js';
 import { type CodexUsageView } from './codex-usage.js';
+import type { SharedPendingLogins } from './account-sync.js';
 import { type KeyStore } from './keys.js';
 /** Persisted account metadata surfaced by `GET /admin/accounts`. */
 export interface AdminAccountRecord {
@@ -226,6 +227,13 @@ export interface AdminDeps {
      * off on this proxy; the routes answer 404.
      */
     keys?: KeyStore | null;
+    /**
+     * The shared account registry's pending-login store (account-sync.ts), set
+     * when `--pool-shared-accounts` is on. A login started here is also
+     * published there, so any instance can complete it. Absent: pending logins
+     * live in this process only.
+     */
+    sharedLogins?: SharedPendingLogins | null;
 }
 /**
  * Handle an `/admin/*` request. Returns `true` if it owned the request (matched