@askalf/dario 6.18.4 → 6.19.1

package/README.md

@@ -16,7 +16,7 @@
 
 <p><strong>One local endpoint. Every AI tool you own. Your Claude seats first, your ChatGPT plan and a metered key as the rungs you chain behind them, and a ledger of who paid for what.</strong></p>
 
-<sub><code>npm i -g @askalf/dario</code> or <code>brew install askalf/tap/dario</code> · <strong>0</strong> runtime deps · <a href="https://www.npmjs.com/package/@askalf/dario">SLSA-attested</a> every release · nothing phones home · ~42k lines you can read in a weekend · independent, unofficial, third-party (<a href="DISCLAIMER.md">DISCLAIMER.md</a>)</sub>
+<sub><code>npm i -g @askalf/dario</code> or <code>brew install askalf/tap/dario</code> · <strong>0</strong> runtime deps · <a href="https://www.npmjs.com/package/@askalf/dario">SLSA-attested</a> every release · nothing phones home · ~43k lines you can read in a weekend · independent, unofficial, third-party (<a href="DISCLAIMER.md">DISCLAIMER.md</a>)</sub>
 
 <sub><a href="#start-in-60-seconds">Start</a> · <a href="#why-people-pick-it">Why dario</a> · <a href="#what-it-does-with-a-request">Routing</a> · <a href="#will-my-account-get-suspended">Risk</a> · <a href="#reference">Reference</a> · <a href="#trust--transparency">Trust</a> · <a href="docs/returning.md">Coming back after a while?</a></sub>
 
@@ -113,11 +113,11 @@ dario runs entirely on your machine, authenticates as you with your own Claude l
 
 | Signal | Status |
 |---|---|
-| Source | **~42k** lines of TypeScript across **87** files, auditable in a weekend. One credential path since v5: the pool. |
+| Source | **~43k** lines of TypeScript across **87** files, auditable in a weekend. One credential path since v5: the pool. |
 | Dependencies | **0 runtime.** Verify: `npm ls --production` |
 | Provenance | Every release [SLSA-attested](https://www.npmjs.com/package/@askalf/dario) via GitHub Actions + Sigstore, published with OIDC trusted publishing: no long-lived npm token exists to leak |
 | Scanning | [CodeQL](https://github.com/askalf/dario/actions/workflows/codeql.yml) on every push to master, every PR and weekly · [ClusterFuzzLite](./.github/workflows/cflite.yml) fuzzes the SSE translator, the rejection parsers and the cch stamper weekly · the [OpenSSF Scorecard](https://scorecard.dev/viewer/?uri=github.com/askalf/dario) badge above and the [Best Practices](https://www.bestpractices.dev/projects/13638) entry are live |
-| Tests | **282 test files** run in parallel by `npm test` on Node 18, 20 and 22; the live e2e / compat / stealth suites have their own entry points. Green on every release |
+| Tests | **285 test files** run in parallel by `npm test` on Node 18, 20 and 22; the live e2e / compat / stealth suites have their own entry points. Green on every release |
 | Credentials | Your own subscription tokens, never logged, redacted from errors, `0600` on disk in `0700` dirs |
 | Network | Binds `127.0.0.1` by default; upstream only to configured backends over HTTPS; hardcoded SSRF allow-list; refuses a non-loopback bind without `DARIO_API_KEY`; refuses cross-origin and DNS-rebound browser requests |
 | Telemetry | **None.** No analytics, no tracking, nothing phones home |

package/dist/account-sync.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Shared account registry (`--pool-shared-accounts`). Every instance merges
+ * the Claude accounts in its `~/.dario/accounts/` with a registry on the
+ * refresh-lock service, through three endpoints both reference backends
+ * implement (redis-lock/, cloudflare/refresh-lock/):
+ *
+ *   POST /accounts/list            {}                → { accounts: { alias: AccountCredentials }, removed: { alias: removedAt } }
+ *   POST /accounts/<alias>/put     { credentials }   → { stored }
+ *   POST /accounts/<alias>/remove  { removedAt }     → { removed }
+ *
+ * A sync runs at startup, before the pool loads, then every 15 seconds and
+ * after each admin API change. It publishes the removals this process made,
+ * reads the registry, writes into the accounts directory every record newer
+ * than the file there, removes the files a removal marker covers, pushes
+ * every file newer than the registry's record, and hands the running pool
+ * what changed, checked against the removals made here up to that moment.
+ * Newer is credentialsAreNewer: the later grant, then the later expiry. A
+ * removal marker beats every grant made before it and loses to every grant
+ * made after it, so the instances' clocks must agree (NTP) to well under the
+ * time between a removal and a later login.
+ *
+ * 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`.
+ */
+import { type AccountCredentials } from './accounts.js';
+/** 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: {
+        fetchedAt: number;
+        removedAt?: number;
+    }): Promise<{
+        saved: boolean;
+        replaced?: AccountCredentials;
+    }>;
+    remove(alias: string, removedAt: number): Promise<boolean>;
+    /** Removals this process made, alias to epoch ms. */
+    localRemovals(): ReadonlyMap<string, number>;
+}
+export declare const accountFileStore: AccountSyncStore;
+/** What one sync changed on this instance, handed to the running proxy. */
+export interface AccountSyncChange {
+    /** Records the pool lacks or holds older credentials for. */
+    records: AccountCredentials[];
+    /** Seats the pool still holds whose account was removed. */
+    removed: Array<{
+        alias: string;
+        removedAt: number;
+    }>;
+}
+/** The credentials a live pool seat holds, as far as ordering them needs. */
+export type LiveSeat = {
+    expiresAt: number;
+    grantedAt?: number;
+};
+export interface AccountSyncStatus {
+    enabled: true;
+    intervalMs: number;
+    lastSyncAt: number | null;
+    lastOkAt: number | null;
+    /** Records and removal markers the registry held at the last good read. */
+    registryAccounts: number | null;
+    registryRemoved: number | null;
+    /** Cumulative: records written from the registry, files removed, records pushed, removals published. */
+    saved: number;
+    removed: number;
+    pushed: number;
+    removalsPublished: number;
+    errors: number;
+    lastError: string | null;
+}
+export interface AccountSyncOptions {
+    baseUrl: string;
+    token: string;
+    /** Sync interval, ms. Default 15000. */
+    intervalMs?: number;
+    store?: AccountSyncStore;
+    log?: (line: string) => void;
+}
+export declare const DEFAULT_ACCOUNT_SYNC_INTERVAL_MS = 15000;
+export interface AccountSyncPlan {
+    /** Registry records to write here, each with the removal time it must outlive. */
+    save: Array<{
+        creds: AccountCredentials;
+        removedAt?: number;
+    }>;
+    /** Local files a removal covers. */
+    remove: Array<{
+        alias: string;
+        removedAt: number;
+    }>;
+    /** Local records newer than the registry's. */
+    push: AccountCredentials[];
+}
+/** 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;
+/**
+ * Merge this instance's account files with the registry, per alias. A record
+ * counts only when it outlives the latest removal of its alias (the
+ * registry's marker or one this process made); of the two that count, the
+ * 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;
+/** 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. */
+export type SharedRemovalResult = 
+/** The registry took the removal, and the file here is gone. */
+'removed'
+/** The registry holds a login for the alias granted after the removal; nothing changed. */
+ | 'registry-newer'
+/** The registry took the removal, but the file here holds a login granted after it, which stays. */
+ | 'local-newer'
+/** The registry took the removal, but the file here, which it covers, could not be deleted. */
+ | 'local-failed';
+/**
+ * Remove an account from the registry, then from this instance's disk, for
+ * `dario accounts remove`. The removal is published first: a running
+ * replica would otherwise push the account back from its own copy. The file
+ * 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;
+    removedAt?: number;
+}): Promise<SharedRemovalResult>;
+export declare class AccountSync {
+    readonly intervalMs: number;
+    private readonly baseUrl;
+    private readonly token;
+    private readonly store;
+    private readonly log;
+    private onChange;
+    private live;
+    private timer;
+    private running;
+    private queued;
+    private readonly published;
+    private markers;
+    private down;
+    private stats;
+    constructor(opts: AccountSyncOptions);
+    /**
+     * 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;
+    /** Sync on the interval. The timer never keeps the process alive. */
+    start(): void;
+    stop(): void;
+    status(): AccountSyncStatus;
+    /**
+     * The latest removal of `alias` this instance knows of: the registry's
+     * marker at the last good read, or one this process made. A path that
+     * writes account files outside the sync checks it, so it never restores a
+     * login the sync just removed.
+     */
+    removalOf(alias: string): number | undefined;
+    /** One sync. Null when the registry could not be read; never throws. */
+    syncOnce(): Promise<AccountSyncChange | null>;
+    private run;
+    /**
+     * One POST to the service. Null on any failure: the caller carries on with
+     * the accounts on disk, which is the whole contract. Logged once per
+     * transition into and out of the failed state, not per call.
+     */
+    private call;
+}

package/dist/account-sync.js

@@ -0,0 +1,351 @@
+/**
+ * Shared account registry (`--pool-shared-accounts`). Every instance merges
+ * the Claude accounts in its `~/.dario/accounts/` with a registry on the
+ * refresh-lock service, through three endpoints both reference backends
+ * implement (redis-lock/, cloudflare/refresh-lock/):
+ *
+ *   POST /accounts/list            {}                → { accounts: { alias: AccountCredentials }, removed: { alias: removedAt } }
+ *   POST /accounts/<alias>/put     { credentials }   → { stored }
+ *   POST /accounts/<alias>/remove  { removedAt }     → { removed }
+ *
+ * A sync runs at startup, before the pool loads, then every 15 seconds and
+ * after each admin API change. It publishes the removals this process made,
+ * reads the registry, writes into the accounts directory every record newer
+ * than the file there, removes the files a removal marker covers, pushes
+ * every file newer than the registry's record, and hands the running pool
+ * what changed, checked against the removals made here up to that moment.
+ * Newer is credentialsAreNewer: the later grant, then the later expiry. A
+ * removal marker beats every grant made before it and loses to every grant
+ * made after it, so the instances' clocks must agree (NTP) to well under the
+ * time between a removal and a later login.
+ *
+ * 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`.
+ */
+import { loadAllAccounts, saveSharedAccount, removeSharedAccount, localAccountRemovals, credentialsAreNewer, grantedAfter, isValidAccountAlias, } from './accounts.js';
+import { maskEmail } from './pool.js';
+import { clampTimerMs } from './timer-ms.js';
+export const accountFileStore = {
+    loadAll: loadAllAccounts,
+    save: saveSharedAccount,
+    remove: removeSharedAccount,
+    localRemovals: localAccountRemovals,
+};
+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. */
+export function removalTime(alias, markers, localRemovals) {
+    const a = markers.get(alias), b = localRemovals.get(alias);
+    if (a === undefined)
+        return b;
+    if (b === undefined)
+        return a;
+    return Math.max(a, b);
+}
+/**
+ * Merge this instance's account files with the registry, per alias. A record
+ * counts only when it outlives the latest removal of its alias (the
+ * registry's marker or one this process made); of the two that count, the
+ * newer wins. The registry's goes to disk, ours goes to the registry, and a
+ * local file no record outlives is removed.
+ */
+export function planAccountSync(local, registry, markers, localRemovals) {
+    const plan = { save: [], remove: [], push: [] };
+    const localByAlias = new Map(local.map((a) => [a.alias, a]));
+    for (const alias of new Set([...localByAlias.keys(), ...registry.keys()])) {
+        const removedAt = removalTime(alias, markers, localRemovals);
+        const mine = localByAlias.get(alias);
+        const theirs = registry.get(alias);
+        const mineCounts = mine !== undefined && grantedAfter(mine, removedAt);
+        const theirsCount = theirs !== undefined && grantedAfter(theirs, removedAt);
+        if (theirsCount && (!mineCounts || credentialsAreNewer(theirs, mine))) {
+            plan.save.push(removedAt === undefined ? { creds: theirs } : { creds: theirs, removedAt });
+        }
+        else if (mineCounts) {
+            if (!theirsCount || credentialsAreNewer(mine, theirs))
+                plan.push.push(mine);
+        }
+        else if (mine !== undefined && removedAt !== undefined) {
+            plan.remove.push({ alias, removedAt });
+        }
+    }
+    return plan;
+}
+/** A registry record complete enough to serve from, stored under its own alias. */
+export function isRegistryRecord(alias, rec) {
+    const r = rec;
+    return !!r && typeof r === 'object' && r.alias === alias && isValidAccountAlias(alias)
+        && typeof r.accessToken === 'string' && r.accessToken.length > 0
+        && typeof r.refreshToken === 'string' && r.refreshToken.length > 0
+        && typeof r.expiresAt === 'number' && Number.isFinite(r.expiresAt)
+        && Array.isArray(r.scopes) && typeof r.deviceId === 'string' && typeof r.accountUuid === 'string';
+}
+function parseRegistry(raw) {
+    const out = new Map();
+    if (!raw || typeof raw !== 'object')
+        return out;
+    for (const [alias, rec] of Object.entries(raw))
+        if (isRegistryRecord(alias, rec))
+            out.set(alias, rec);
+    return out;
+}
+function parseMarkers(raw) {
+    const out = new Map();
+    if (!raw || typeof raw !== 'object')
+        return out;
+    for (const [alias, at] of Object.entries(raw)) {
+        if (isValidAccountAlias(alias) && typeof at === 'number' && Number.isFinite(at))
+            out.set(alias, at);
+    }
+    return out;
+}
+async function registryCall(baseUrl, token, path, body) {
+    const res = await fetch(`${baseUrl.replace(/\/+$/, '')}${path}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
+    });
+    if (!res.ok)
+        throw new Error(`HTTP ${res.status}`);
+    return (await res.json());
+}
+/**
+ * Remove an account from the registry, then from this instance's disk, for
+ * `dario accounts remove`. The removal is published first: a running
+ * replica would otherwise push the account back from its own copy. The file
+ * 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 async function removeAccountEverywhere(baseUrl, token, alias, opts = {}) {
+    const store = opts.store ?? accountFileStore;
+    const removedAt = opts.removedAt ?? Date.now();
+    const res = await registryCall(baseUrl, token, `/accounts/${encodeURIComponent(alias)}/remove`, { removedAt });
+    if (res.removed !== true)
+        return 'registry-newer';
+    if (await store.remove(alias, removedAt))
+        return 'removed';
+    // Not removed by this call: a running proxy on this disk applied the
+    // marker first, a login landed in the file after the removal, or the
+    // file could not be deleted. Only an absent file counts as removed.
+    const current = (await store.loadAll()).find((a) => a.alias === alias);
+    if (!current)
+        return 'removed';
+    return grantedAfter(current, removedAt) ? 'local-newer' : 'local-failed';
+}
+function describeAccount(c) {
+    return maskEmail(c.accountEmail) ?? c.accountId ?? 'unknown account';
+}
+export class AccountSync {
+    intervalMs;
+    baseUrl;
+    token;
+    store;
+    log;
+    onChange = null;
+    live = null;
+    timer = null;
+    // One sync at a time, and at most one waiting: a call while one runs gets
+    // the next run, which starts after it and so sees what it wrote.
+    running = Promise.resolve();
+    queued = null;
+    // Removal time last published per alias, so each removal goes out once.
+    published = new Map();
+    // The registry's removal markers at the last good read.
+    markers = new Map();
+    down = false;
+    stats = {
+        lastSyncAt: null, lastOkAt: null,
+        registryAccounts: null, registryRemoved: null,
+        saved: 0, removed: 0, pushed: 0, removalsPublished: 0, errors: 0, lastError: null,
+    };
+    constructor(opts) {
+        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.log = opts.log ?? ((line) => console.error(line));
+    }
+    /**
+     * 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, onChange) {
+        this.live = live;
+        this.onChange = onChange;
+    }
+    /** Sync on the interval. The timer never keeps the process alive. */
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => { void this.syncOnce(); }, this.intervalMs);
+        this.timer.unref?.();
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+    }
+    status() {
+        return { enabled: true, intervalMs: this.intervalMs, ...this.stats };
+    }
+    /**
+     * The latest removal of `alias` this instance knows of: the registry's
+     * marker at the last good read, or one this process made. A path that
+     * writes account files outside the sync checks it, so it never restores a
+     * login the sync just removed.
+     */
+    removalOf(alias) {
+        return removalTime(alias, this.markers, this.store.localRemovals());
+    }
+    /** One sync. Null when the registry could not be read; never throws. */
+    syncOnce() {
+        if (this.queued)
+            return this.queued;
+        const next = this.running.then(() => {
+            this.queued = null;
+            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`);
+                return null;
+            });
+        });
+        this.queued = next;
+        this.running = next;
+        return next;
+    }
+    async run() {
+        this.stats.lastSyncAt = Date.now();
+        // Removals first: a list read after them no longer holds those records,
+        // and one read before would hand them straight back.
+        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 });
+            if (!res)
+                break;
+            this.published.set(alias, at);
+            this.stats.removalsPublished++;
+        }
+        const fetchedAt = Date.now();
+        const res = await this.call('/accounts/list', {});
+        if (!res)
+            return null;
+        const registry = parseRegistry(res.accounts);
+        const markers = parseMarkers(res.removed);
+        this.markers = markers;
+        this.stats.registryAccounts = registry.size;
+        this.stats.registryRemoved = markers.size;
+        const local = await this.store.loadAll();
+        const localRemovals = this.store.localRemovals();
+        const plan = planAccountSync(local, registry, markers, localRemovals);
+        // The record each alias ends on here: the files that outlive their
+        // alias's removal, then whatever the registry replaced.
+        const kept = new Map();
+        for (const a of local)
+            if (grantedAfter(a, removalTime(a.alias, markers, localRemovals)))
+                kept.set(a.alias, a);
+        const removed = [];
+        for (const { alias, removedAt } of plan.remove) {
+            // Kept when a login landed in the file since it was read; the next
+            // sync takes that login to the pool.
+            if (!(await this.store.remove(alias, removedAt)))
+                continue;
+            kept.delete(alias);
+            removed.push({ alias, removedAt });
+            this.stats.removed++;
+            this.log(`[dario] shared accounts: removed account "${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 });
+            if (!out.saved)
+                continue;
+            kept.set(creds.alias, creds);
+            this.stats.saved++;
+            const was = out.replaced;
+            if (!was) {
+                this.log(`[dario] shared accounts: added account "${creds.alias}" (${describeAccount(creds)}) from the registry`);
+            }
+            else if (was.accountId && creds.accountId && was.accountId !== creds.accountId) {
+                // 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`);
+            }
+        }
+        for (const creds of plan.push) {
+            // A removal made here while this sync ran waits for the next one;
+            // pushing the file it removed would bring the account back until then.
+            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 });
+            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`);
+        }
+        const change = { records: [], removed };
+        if (this.live) {
+            // The pool gets the state as of now: a removal made here while this
+            // sync waited on the service covers the records read before it.
+            const removedNow = this.store.localRemovals();
+            for (const [alias, rec] of kept)
+                if (!grantedAfter(rec, removedNow.get(alias)))
+                    kept.delete(alias);
+            for (const rec of kept.values()) {
+                const seat = this.live(rec.alias);
+                if (!seat || credentialsAreNewer(rec, seat))
+                    change.records.push(rec);
+            }
+            // A seat whose file went another way (a CLI removal in another
+            // process, or a peer on a shared accounts volume) is still in the pool.
+            const planned = new Set(plan.remove.map((r) => r.alias));
+            for (const alias of new Set([...markers.keys(), ...removedNow.keys()])) {
+                if (kept.has(alias) || planned.has(alias))
+                    continue;
+                const removedAt = removalTime(alias, markers, removedNow);
+                const seat = this.live(alias);
+                if (seat && !grantedAfter(seat, removedAt))
+                    removed.push({ alias, removedAt });
+            }
+        }
+        if (this.onChange && (change.records.length > 0 || change.removed.length > 0))
+            await this.onChange(change);
+        return change;
+    }
+    /**
+     * One POST to the service. Null on any failure: the caller carries on with
+     * the accounts on disk, which is the whole contract. Logged once per
+     * transition into and out of the failed state, not per call.
+     */
+    async call(path, body) {
+        try {
+            const out = await registryCall(this.baseUrl, this.token, path, body);
+            this.stats.lastOkAt = Date.now();
+            if (this.down) {
+                this.down = false;
+                this.log(`[dario] shared accounts: service reachable again (${this.baseUrl})`);
+            }
+            return out;
+        }
+        catch (err) {
+            this.stats.errors++;
+            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`);
+            }
+            return null;
+        }
+    }
+}

package/dist/accounts.d.ts

@@ -1,3 +1,5 @@
+/** Whether `alias` is one an account file can be stored under. */
+export declare function isValidAccountAlias(alias: string): boolean;
 export interface AccountCredentials {
     alias: string;
     accessToken: string;
@@ -38,8 +40,54 @@ export type IdentitySource = 'claude-code' | 'generated';
 export declare function listAccountAliases(): Promise<string[]>;
 export declare function loadAccount(alias: string): Promise<AccountCredentials | null>;
 export declare function loadAllAccounts(): Promise<AccountCredentials[]>;
+/**
+ * Whether `candidate` holds newer credentials than `current`. A newer grant
+ * (a fresh login) wins outright, since an older grant's refreshed access
+ * token can expire later. Same grant, or a grant time missing on either
+ * side: the later expiry wins. The lock services apply the same rule.
+ */
+export declare function credentialsAreNewer(candidate: {
+    expiresAt: number;
+    grantedAt?: number;
+}, current: {
+    expiresAt?: number;
+    grantedAt?: number;
+}): boolean;
 export declare function saveAccount(creds: AccountCredentials): Promise<void>;
+export declare function _setAccountWriteHookForTest(hook: (() => Promise<void>) | null): void;
+/** The account files this process has removed, alias to epoch ms. */
+export declare function localAccountRemovals(): ReadonlyMap<string, number>;
 export declare function removeAccount(alias: string): Promise<boolean>;
+/**
+ * Whether credentials outlive a removal made at `removedAt`: granted after
+ * it, so a login that came later. With no removal, every record does. A
+ * record with no grant time predates grant times, so it predates the removal.
+ */
+export declare function grantedAfter(creds: {
+    grantedAt?: number;
+}, removedAt: number | undefined): boolean;
+/**
+ * Write a record read from the shared account registry (account-sync.ts),
+ * inside the alias's write chain. Skipped when this process removed the file
+ * at or after `fetchedAt`, since the registry was read before that removal,
+ * and when the file already holds credentials at least as new that outlive
+ * `removedAt`. `replaced` is the record the write overwrote.
+ */
+export declare function saveSharedAccount(creds: AccountCredentials, opts: {
+    fetchedAt: number;
+    removedAt?: number;
+}): Promise<{
+    saved: boolean;
+    replaced?: AccountCredentials;
+}>;
+/**
+ * Remove an account file because the shared account registry holds a
+ * removal made at `removedAt`, inside the alias's write chain. A file granted
+ * after the removal is a later login and is kept. Not recorded in
+ * localAccountRemovals: publishing it again under a later time would remove
+ * a login a peer made between the two.
+ */
+export declare function removeSharedAccount(alias: string, removedAt: number): Promise<boolean>;
 /**
  * Carry the organization the proxy observed on a seat into a record that is
  * about to be written anyway — its token refresh (dario#1244). The observation
@@ -118,6 +166,18 @@ export declare function chooseClientIdentity(existing: readonly AccountCredentia
 export declare function regenerateClientIdentity(aliases: readonly string[]): Promise<string[]>;
 /** Refresh an account's OAuth token using dario's auto-detected CC OAuth config. */
 export declare function refreshAccountToken(creds: AccountCredentials): Promise<AccountCredentials>;
+/**
+ * Adopt credentials another instance refreshed for this account, when the
+ * lock service holds a newer copy than `local` (dario#1733). Returns the
+ * newest credentials newer than `local`, saving them when the account file
+ * is older; null when nothing newer is shared, the account is gone, no lock
+ * service is set, or it cannot be reached. Never refreshes and never takes the lock. The
+ * proxy asks at startup and on every refresh tick, so a replica runs on its
+ * peer's rotation within one tick instead of carrying the old pair until its
+ * own refresh window. "Newer" is the lock service's rule: a newer grant, or
+ * the same grant with a later expiry.
+ */
+export declare function adoptSharedCredentials(local: Pick<AccountCredentials, 'alias' | 'expiresAt' | 'grantedAt'>): Promise<AccountCredentials | null>;
 /**
  * Fill in `accountId` (and the profile's other fields) on a record that predates
  * them, from one profile GET; saves and returns the record, unchanged when
@@ -227,8 +287,13 @@ export declare const MIGRATED_LOGIN_ALIAS = "login";
  *
  * @param preferredAlias caller may request a specific alias. If it's
  *   already the reserved `login` (or collides), falls back to `default`.
+ * @param opts.removedAt when the shared account registry (account-sync.ts)
+ *   removed the alias. A login granted before it is not back-filled, since
+ *   that would serve a removed account; a later login is.
  */
-export declare function ensureLoginCredentialsInPool(alias?: string): Promise<string | null>;
+export declare function ensureLoginCredentialsInPool(alias?: string, opts?: {
+    removedAt?: number | undefined;
+}): Promise<string | null>;
 /**
  * Detect divergence between `accounts/login.json` and the current
  * `credentials.json` (or whichever store loadCredentials finds), and