@chrischall/mcp-utils 0.15.0 → 0.17.0

package/dist/session/index.js

@@ -1,5 +1,5 @@
 /**
- * Session scaffolding for the MCP fleet — four related-but-distinct surfaces
+ * Session scaffolding for the MCP fleet — five related-but-distinct surfaces
  * consolidated behind one subpath (`@chrischall/mcp-utils/session`):
  *
  *  1. {@link SessionRegistry} — an *ephemeral, in-memory* registry of signed-in
@@ -12,12 +12,18 @@
  *     (0600 file / 0700 dir), normalized keys, and a most-recently-used "active"
  *     pointer. Used by ofw/creditkarma/honeybook.
  *
- *  3. {@link TokenManager} — a bearer-token lifecycle manager: proactive refresh
- *     inside a 5-minute skew window, reactive 401-replay, and a single-flight
- *     semaphore so concurrent callers coalesce into ONE refresh. Used by
- *     skylight/canvas/creditkarma/honeybook/zola.
+ *  3. {@link StatePersistence} — the opt-in seam that lets the two managers
+ *     below survive a process restart, with {@link createFileStatePersistence}
+ *     (atomic, 0600) and {@link resolveStateDir} (`MCP_DATA_DIR` → `HOME`) as
+ *     the disk-backed default. Without it a scale-to-zero host re-runs a full
+ *     login on every cold start, against endpoints that often rate-limit it.
  *
- *  4. {@link CookieSessionManager} — the cookie-session analog of TokenManager:
+ *  4. {@link TokenManager} — a bearer-token lifecycle manager: a lazily
+ *     bootstrapped login, proactive refresh inside a 5-minute skew window,
+ *     reactive 401-replay, and a single-flight semaphore so concurrent callers
+ *     coalesce into ONE exchange. Used by skylight/canvas/creditkarma/honeybook/zola.
+ *
+ *  5. {@link CookieSessionManager} — the cookie-session analog of TokenManager:
  *     a single-flight login + reactive expiry-replay (with heuristic, not just
  *     status-code, expiry detection) + clear-on-settle so a rejected login never
  *     sticks. Used by artsonia/canvas/evite/signupgenius/skylight.
@@ -26,10 +32,13 @@
  * the one audited implementation the fleet shares.
  */
 import { z } from 'zod';
-import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, renameSync, } from 'node:fs';
-import { dirname } from 'node:path';
-import { randomBytes } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, renameSync, unlinkSync, } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { randomBytes, createHmac } from 'node:crypto';
 import { textResult } from '../response/index.js';
+import { readEnvVar } from '../config/index.js';
+import { ApiError, RateLimitedError, RequestTimeoutError } from '../http/index.js';
 /** Generate a short, collision-resistant label id. */
 function makeSessionId() {
     return Date.now().toString(36) + randomBytes(6).toString('hex');
@@ -389,72 +398,572 @@ export class SessionStore {
         this.mostRecentKey = null;
     }
 }
+/**
+ * Digest a credential under a salt.
+ *
+ * Salted per record rather than a bare `sha256(secret)`: this artifact sits in
+ * the same file as the tokens, and callers are invited to pass a password, so an
+ * unsalted digest would be a stable, precomputable target. The salt is random
+ * per write, so the same credential never produces the same digest twice.
+ *
+ * This is a change-detector, not a password store — prefer passing a non-secret
+ * discriminator (an env-supplied refresh token, an account id) where one exists.
+ */
+function bindingDigest(secret, salt) {
+    return createHmac('sha256', salt).update(secret).digest('hex').slice(0, 32);
+}
+function isEnvelope(raw) {
+    return raw !== null && typeof raw === 'object' && raw.v === 1 && 'state' in raw;
+}
+/**
+ * Wraps a failure that came from WRITING state, so the managers can tell it
+ * apart from a failure of the credential itself.
+ *
+ * This distinction is load-bearing, not cosmetic. `TokenManager` recovers from a
+ * rejected refresh by discarding the stored record and re-running the login —
+ * correct for a revoked token, catastrophic for a disk error, because the
+ * refresh that just SUCCEEDED already burned the old token upstream. Deleting
+ * the record at that point is precisely the lockout `onPersistError` exists to
+ * prevent, so a persistence failure is never routed into that recovery.
+ */
+export class StatePersistenceError extends Error {
+    cause;
+    constructor(cause) {
+        super(cause instanceof Error ? cause.message : String(cause));
+        this.name = 'StatePersistenceError';
+        this.cause = cause;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * File-backed {@link StatePersistence}. `load` never throws — an absent, corrupt
+ * or rejected record is simply `null`. `save` DOES throw on a failed write, so
+ * the manager above it can decide what that means.
+ *
+ * The file is `0600`, re-asserted after
+ * the write because `mode` only applies on creation. A directory is created
+ * `0700` and re-asserted the same way — but ONLY one this call creates: a bare
+ * {@link resolveStateDir} is `$HOME`, and on `mcp-host` the data dir exists
+ * before the child starts, so re-permissioning a pre-existing directory would
+ * be an invasive side effect of writing one token file rather than hardening.
+ *
+ * Two differences from {@link SessionStore}, which is why this is its own
+ * implementation rather than a wrapper over it. It holds ONE record rather than
+ * a keyed collection; and it replaces the file **atomically** — written to a
+ * temp file beside it, then renamed over the target — because two children of
+ * the same registration can share a data directory, and a half-written token
+ * file that parses as valid JSON is worse than none.
+ *
+ * A load failure (absent, corrupt, rejected by `validate`) returns `null`; a
+ * save failure throws, leaving the previous file intact — the atomic replace
+ * means a failed write never damages what was already there. On `mcp-host` this
+ * belongs under {@link resolveStateDir}, which needs
+ * the registration to declare `state.dataDir: true` — the runner's
+ * unpersisted-state detector will report the omission rather than let the
+ * writes silently vanish on the next idle-stop.
+ */
+export function createFileStatePersistence(opts) {
+    const { filePath, validate } = opts;
+    const secret = opts.boundTo;
+    return {
+        load() {
+            if (!existsSync(filePath))
+                return null;
+            try {
+                const raw = JSON.parse(readFileSync(filePath, 'utf8'));
+                let state;
+                if (isEnvelope(raw)) {
+                    const b = raw.boundTo;
+                    if (secret === undefined) {
+                        // A bound record is not ours to read when we hold no credential.
+                        if (b !== undefined)
+                            return null;
+                    }
+                    else {
+                        if (b === undefined)
+                            return null; // unbound record, binding required
+                        if (bindingDigest(secret, b.salt) !== b.digest)
+                            return null; // rotated
+                    }
+                    state = raw.state;
+                }
+                else {
+                    // Legacy bare record. Trusted only when no binding is required: it
+                    // carries no evidence of which credential minted it.
+                    if (secret !== undefined)
+                        return null;
+                    state = raw;
+                }
+                if (validate !== undefined)
+                    return validate(state);
+                return state;
+            }
+            catch {
+                // Corrupt or unreadable: the caller re-authenticates. Unlike
+                // SessionStore this does NOT preserve a `.corrupt` copy — the file
+                // holds one refreshable credential, not an irreplaceable capture.
+                return null;
+            }
+        },
+        save(state) {
+            const dir = dirname(filePath);
+            // A unique temp name so two writers cannot share (and tear) one temp file.
+            const tmp = `${filePath}.tmp-${randomBytes(6).toString('hex')}`;
+            // Only a directory THIS call creates gets tightened. `resolveStateDir()`
+            // without a `subdir` is `$HOME`, and chmodding a user's home directory to
+            // 0700 is not an acceptable side effect of writing one token file.
+            const dirExisted = existsSync(dir);
+            try {
+                mkdirSync(dir, { recursive: true, mode: 0o700 });
+                // mkdir's mode is subject to the umask, so re-assert it on what we made.
+                if (!dirExisted)
+                    chmodSync(dir, 0o700);
+                let boundTo;
+                if (secret !== undefined) {
+                    const salt = randomBytes(16).toString('hex');
+                    boundTo = { salt, digest: bindingDigest(secret, salt) };
+                }
+                const envelope = { v: 1, ...(boundTo !== undefined ? { boundTo } : {}), state };
+                writeFileSync(tmp, JSON.stringify(envelope, null, 2), { mode: 0o600 });
+                // Tighten BEFORE the rename: the window where fresh secrets sit in a
+                // possibly-loose file should not exist at all.
+                chmodSync(tmp, 0o600);
+                renameSync(tmp, filePath);
+                chmodSync(filePath, 0o600);
+            }
+            catch (err) {
+                // Best-effort cleanup of the temp file so a failed write does not
+                // litter the data dir. The failure itself is RE-THROWN: whether losing
+                // a write is survivable is the manager's call (see `onPersistError`),
+                // not this file's — freshbooks-mcp's rotating single-use tokens make it
+                // fatal, most services make it a nuisance.
+                try {
+                    if (existsSync(tmp))
+                        unlinkSync(tmp);
+                }
+                catch {
+                    /* best-effort */
+                }
+                throw err;
+            }
+        },
+        clear() {
+            try {
+                if (existsSync(filePath))
+                    unlinkSync(filePath);
+            }
+            catch {
+                /* best-effort */
+            }
+        },
+    };
+}
+/**
+ * Many records in one file, keyed by account.
+ *
+ * {@link createFileStatePersistence} holds exactly one record, which is wrong
+ * for any server that authenticates as more than one identity — and actively
+ * unsafe for one that serves several users from a single process, where a
+ * single-record file would hand one user's token to the next. kiaaccess-mcp and
+ * alphaportal-mcp both hand-rolled this over {@link SessionStore}; this is the
+ * shared form, with the same atomic-replace and `0600`/`0700` hardening as the
+ * single-record store.
+ *
+ * Reads go through the file each time rather than an in-process cache, so a
+ * record written by a SIBLING process is picked up — the property kiaaccess-mcp's
+ * "constructed per call" comment exists to preserve.
+ *
+ * WRITES, though, are whole-file read-modify-write: two processes saving
+ * DIFFERENT keys at the same instant can lose one of the two, because each
+ * rewrites the map it read. The replace is atomic, so the file is never torn —
+ * only a concurrent sibling's update can be dropped, and the loser re-authenticates
+ * rather than reading anything wrong. That is acceptable for credential caches
+ * (rare writes, self-healing) and would not be for a general-purpose store. If
+ * that ever stops being true the fix is a lock file, not a bigger read.
+ */
+export function createKeyedFileStatePersistence(opts) {
+    const { filePath, validate } = opts;
+    const normalize = opts.normalizeKey ?? ((k) => k.trim().toLowerCase());
+    const readAll = () => {
+        if (!existsSync(filePath))
+            return {};
+        try {
+            const raw = JSON.parse(readFileSync(filePath, 'utf8'));
+            if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+                return {};
+            return raw;
+        }
+        catch {
+            return {};
+        }
+    };
+    const writeAll = (all) => {
+        const dir = dirname(filePath);
+        const tmp = `${filePath}.tmp-${randomBytes(6).toString('hex')}`;
+        const dirExisted = existsSync(dir);
+        try {
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+            if (!dirExisted)
+                chmodSync(dir, 0o700);
+            writeFileSync(tmp, JSON.stringify(all, null, 2), { mode: 0o600 });
+            chmodSync(tmp, 0o600);
+            renameSync(tmp, filePath);
+            chmodSync(filePath, 0o600);
+        }
+        catch (err) {
+            try {
+                if (existsSync(tmp))
+                    unlinkSync(tmp);
+            }
+            catch {
+                /* best-effort */
+            }
+            throw err;
+        }
+    };
+    return {
+        forKey(key) {
+            const k = normalize(key);
+            return {
+                load() {
+                    const raw = readAll()[k];
+                    if (raw === undefined)
+                        return null;
+                    return validate !== undefined ? validate(raw) : raw;
+                },
+                save(state) {
+                    const all = readAll();
+                    all[k] = state;
+                    writeAll(all);
+                },
+                clear() {
+                    const all = readAll();
+                    if (!(k in all))
+                        return;
+                    delete all[k];
+                    writeAll(all);
+                },
+            };
+        },
+        keys() {
+            return Object.keys(readAll());
+        },
+    };
+}
+/**
+ * The home directory a state resolver should use: an injected `HOME` when the
+ * caller supplied an env, else the OS home. Shared by both branches below so
+ * they cannot drift — an override expanding `~` against a different home than
+ * the fallback resolves to is exactly the bug this centralises away.
+ */
+function homeOf(env) {
+    return readEnvVar('HOME', { env }) ?? homedir();
+}
+/**
+ * Where a server should keep state that must survive a restart.
+ *
+ * `MCP_DATA_DIR` first — that is the variable `mcp-host` injects for a
+ * registration with `state.dataDir: true`, pointing at a path on the Fly volume
+ * keyed by the registration itself (a slot `$HOME` is handed out by arrival
+ * order and moves between boots, which is why the data dir is the fix and a
+ * bigger rootfs is not). Then `HOME`, then the OS home directory.
+ *
+ * Blank and unexpanded-placeholder values (`${MCP_DATA_DIR}`, the shape a host
+ * config leaves behind when a variable was never substituted) are ignored
+ * rather than used as a literal directory name — the same hardening
+ * {@link readEnvVar} applies.
+ */
+export function resolveStateDir(opts = {}) {
+    // Delegated rather than re-implemented: readEnvVar is the fleet's one place
+    // that suppresses blank, `'null'`, `'undefined'` AND `${...}` placeholders.
+    // The sentinels matter as much as the placeholders here — `MCP_DATA_DIR=null`
+    // is a RELATIVE `./null` directory, so the credential would be written under
+    // the process cwd and silently stop surviving restarts.
+    const env = opts.env;
+    return join(readEnvVar('MCP_DATA_DIR', { env }) ?? homeOf(env), opts.subdir ?? '');
+}
+/**
+ * The full path to a state file: `<envVar>` if set, else
+ * {@link resolveStateDir}`/<subdir>/<fileName>`.
+ *
+ * The override goes through the same hardened {@link readEnvVar} as the base, so
+ * a host forwarding an unexpanded `${...}` — or the literal `null` — falls back
+ * rather than creating a relative directory of that name under the process cwd.
+ * The result is always absolute: `~` expands against the same home the fallback
+ * uses, and anything relative is resolved, because
+ * {@link FileStatePersistenceOptions.filePath} is documented as absolute and a
+ * cwd-relative store would move with the process.
+ */
+export function resolveStateFile(opts) {
+    const override = opts.envVar !== undefined ? readEnvVar(opts.envVar, { env: opts.env }) : undefined;
+    if (override !== undefined) {
+        // `~` expanded against the SAME home the fallback branch uses — `expandPath`
+        // would resolve it against os.homedir() and ignore an injected
+        // `opts.env.HOME`, making the two branches disagree. `resolve` then keeps
+        // the documented "absolute path" guarantee: a relative override would
+        // otherwise follow the process's cwd around.
+        if (override === '~')
+            return homeOf(opts.env);
+        if (override.startsWith('~/'))
+            return join(homeOf(opts.env), override.slice(2));
+        return resolve(override);
+    }
+    const dirOpts = { env: opts.env };
+    if (opts.subdir !== undefined)
+        dirOpts.subdir = opts.subdir;
+    return join(resolveStateDir(dirOpts), opts.fileName);
+}
 // ===========================================================================
-// 3. TokenManager — bearer lifecycle (skew, proactive + reactive, race-safe)
+// 4. TokenManager — bearer lifecycle (skew, proactive + reactive, race-safe)
 // ===========================================================================
 /** Refresh proactively this many ms before the access token expires. */
 export const TOKEN_REFRESH_SKEW_MS = 5 * 60 * 1000;
+/**
+ * The default {@link TokenManagerOptions.isRefreshRevoked}: everything except
+ * the failures mcp-utils itself can prove are transient. Deliberately
+ * conservative — an unrecognised error is treated as a dead credential, because
+ * a needless re-login costs one request and an unrecoverable one costs the
+ * server until a human intervenes.
+ */
+function defaultIsRefreshRevoked(err) {
+    if (err instanceof RateLimitedError || err instanceof RequestTimeoutError)
+        return false;
+    if (err instanceof ApiError && err.status >= 500)
+        return false;
+    return true;
+}
+/** Whether a parsed record has the shape of {@link BearerTokens}. */
+function isBearerTokens(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return false;
+    const t = raw;
+    if (typeof t.accessToken !== 'string' || t.accessToken === '')
+        return false;
+    if (typeof t.expiresAt !== 'number' || !Number.isFinite(t.expiresAt))
+        return false;
+    return t.refreshToken === undefined || typeof t.refreshToken === 'string';
+}
 /**
  * Manages a bearer access token's lifecycle:
  *
+ * - **Lazy bootstrap:** with a function-form {@link TokenManagerOptions.initial}
+ *   the login runs on first use, and only if {@link TokenManagerOptions.persistence}
+ *   has no usable token — the difference between a cold start costing a login
+ *   and costing nothing.
  * - **Proactive:** {@link TokenManager.getAccessToken} refreshes when the token
  *   is within `skewMs` (default 5 min) of expiry, returning a still-valid token.
  * - **Reactive:** {@link TokenManager.withAuth} runs a request, and on a `401`
  *   refreshes once and replays exactly once (no infinite loop).
- * - **Race-safe:** concurrent refreshes coalesce onto a single in-flight promise
- *   (semaphore), so a burst of callers triggers exactly ONE token exchange. The
- *   in-flight promise is cleared on settle so a later refresh can run again.
+ * - **Race-safe:** concurrent refreshes (and concurrent bootstraps) coalesce
+ *   onto a single in-flight promise, so a burst of callers triggers exactly ONE
+ *   exchange. The in-flight promise is cleared on settle so a later attempt can
+ *   run again — a rejected bootstrap never sticks.
+ * - **Recoverable:** when a refresh fails and a bootstrap function is available,
+ *   the stored credential is discarded and the login re-runs. A refresh token
+ *   revoked between two runs of the process must not brick the server.
  */
 export class TokenManager {
-    accessToken;
-    refreshToken;
-    expiresAt;
+    tokens;
+    bootstrapFn;
     refreshFn;
     skewMs;
+    persistence;
+    now;
+    isRefreshRevokedFn;
+    onPersistErrorFn;
     inFlight;
+    bootstrapInFlight;
+    /**
+     * Persistence is consulted at most once per process. Without this the
+     * revoked-token recovery below re-reads the SAME rejected record — `clear()`
+     * is optional on {@link StatePersistence} and its failures are swallowed, so
+     * recovery must not depend on it. After the first read the in-memory tokens
+     * (or their deliberate absence) are the truth.
+     */
+    persistenceRead = false;
     constructor(opts) {
-        this.accessToken = opts.initial.accessToken;
-        this.refreshToken = opts.initial.refreshToken;
-        this.expiresAt = opts.initial.expiresAt;
+        if (typeof opts.initial === 'function') {
+            this.bootstrapFn = opts.initial;
+        }
+        else {
+            this.tokens = { ...opts.initial };
+        }
         this.refreshFn = opts.refresh;
         this.skewMs = opts.skewMs ?? TOKEN_REFRESH_SKEW_MS;
+        this.persistence = opts.persistence;
+        this.now = opts.now ?? Date.now;
+        this.isRefreshRevokedFn = opts.isRefreshRevoked ?? defaultIsRefreshRevoked;
+        this.onPersistErrorFn = opts.onPersistError;
     }
     /** Whether the token is within the skew window of (or past) expiry. */
     needsRefresh() {
-        return Date.now() >= this.expiresAt - this.skewMs;
+        if (this.tokens === undefined)
+            return false;
+        return this.now() >= this.tokens.expiresAt - this.skewMs;
+    }
+    /**
+     * A stored token is worth using when it is still valid, OR when it carries a
+     * refresh token — an expired-but-refreshable token still saves the login,
+     * which is the expensive half.
+     */
+    isUsable(t) {
+        return this.now() < t.expiresAt - this.skewMs || t.refreshToken !== undefined;
+    }
+    /** Read persisted tokens, guarding shape and usability. Never throws. */
+    async loadPersisted() {
+        if (this.persistence === undefined || this.persistenceRead)
+            return null;
+        this.persistenceRead = true;
+        try {
+            const raw = await this.persistence.load();
+            if (!isBearerTokens(raw) || !this.isUsable(raw))
+                return null;
+            return raw;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Write tokens. Silent by default (a lost write costs a future login, not this
+     * request); throws a {@link StatePersistenceError} when `onPersistError` does.
+     */
+    async persist(t) {
+        if (this.persistence === undefined)
+            return;
+        try {
+            await this.persistence.save(t);
+        }
+        catch (err) {
+            // Default: the in-memory token is still valid for this process, so the
+            // request proceeds. A hook that rethrows makes the lost write fatal —
+            // wrapped so the recovery path below cannot mistake a disk error for a
+            // revoked credential and delete the very record that was not written.
+            if (this.onPersistErrorFn === undefined)
+                return;
+            try {
+                this.onPersistErrorFn(err);
+            }
+            catch (hookErr) {
+                throw new StatePersistenceError(hookErr);
+            }
+        }
+    }
+    /** Discard persisted tokens (a refresh they could not satisfy). Never throws. */
+    async clearPersisted() {
+        if (this.persistence?.clear === undefined)
+            return;
+        try {
+            await this.persistence.clear();
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    /** The current tokens, single-flighting the bootstrap if there are none. */
+    ensureTokens() {
+        if (this.tokens !== undefined)
+            return Promise.resolve(this.tokens);
+        if (this.bootstrapInFlight === undefined) {
+            this.bootstrapInFlight = this.runBootstrap().finally(() => {
+                this.bootstrapInFlight = undefined;
+            });
+        }
+        return this.bootstrapInFlight;
+    }
+    /** One bootstrap attempt: persisted tokens if usable, else the login. */
+    async runBootstrap() {
+        const stored = await this.loadPersisted();
+        if (stored !== null) {
+            this.tokens = stored;
+            return stored;
+        }
+        if (this.bootstrapFn === undefined) {
+            throw new Error('TokenManager: no tokens and no bootstrap function to mint them.');
+        }
+        const fresh = await this.bootstrapFn();
+        this.tokens = fresh;
+        // Unwrapped here: there is no recovery to protect on the bootstrap path (the
+        // credential was just minted), and the caller should see the hook's own
+        // error — repos throw an McpToolError whose `hint` a wrapper would strip.
+        try {
+            await this.persist(fresh);
+        }
+        catch (err) {
+            throw err instanceof StatePersistenceError ? err.cause : err;
+        }
+        return fresh;
     }
     /**
      * Single-flight refresh. Concurrent callers share one in-flight promise; it is
      * cleared on settle (success or failure) so a subsequent refresh can proceed.
      */
     refreshNow() {
-        if (!this.inFlight) {
-            const rt = this.refreshToken;
-            if (rt === undefined) {
-                return Promise.reject(new Error('TokenManager: cannot refresh — no refresh token is available.'));
-            }
-            this.inFlight = (async () => {
-                const tok = await this.refreshFn(rt);
-                this.accessToken = tok.accessToken;
-                if (tok.refreshToken !== undefined && tok.refreshToken !== '') {
-                    this.refreshToken = tok.refreshToken;
-                }
-                this.expiresAt = tok.expiresAt;
-            })().finally(() => {
+        if (this.inFlight === undefined) {
+            this.inFlight = this.runRefresh().finally(() => {
                 this.inFlight = undefined;
             });
         }
         return this.inFlight;
     }
+    /** One refresh attempt against the current refresh token. */
+    async runRefresh() {
+        const current = this.tokens ?? (await this.ensureTokens());
+        const rt = current.refreshToken;
+        if (rt === undefined) {
+            throw new Error('TokenManager: cannot refresh — no refresh token is available.');
+        }
+        const tok = await this.refreshFn(rt);
+        this.tokens = {
+            accessToken: tok.accessToken,
+            // Rotation is optional: keep the current refresh token when none comes back.
+            refreshToken: tok.refreshToken !== undefined && tok.refreshToken !== '' ? tok.refreshToken : rt,
+            expiresAt: tok.expiresAt,
+        };
+        await this.persist(this.tokens);
+    }
+    /**
+     * Recover from a refresh the current credential could not satisfy — commonly
+     * a refresh token restored from a previous process and revoked since. Without
+     * a bootstrap to fall back on this is terminal; with one, re-minting beats
+     * staying broken forever. Shared so the two entry points cannot diverge.
+     */
+    async reBootstrap(err) {
+        // A write that failed says nothing about the credential — and the refresh
+        // that produced it SUCCEEDED, spending the old token upstream. Clearing the
+        // store here would destroy the only surviving copy.
+        if (err instanceof StatePersistenceError)
+            throw err.cause;
+        if (this.bootstrapFn === undefined)
+            throw err;
+        // Only a credential we believe is DEAD is worth destroying. A 5xx or a
+        // timeout leaves a perfectly good refresh token that the next call can use.
+        if (!this.isRefreshRevokedFn(err))
+            throw err;
+        this.tokens = undefined;
+        await this.clearPersisted();
+        return this.ensureTokens();
+    }
     /** Get a valid access token, refreshing proactively inside the skew window. */
     async getAccessToken() {
-        if (this.needsRefresh())
-            await this.refreshNow();
-        return this.accessToken;
+        // Not `await this.ensureTokens()` unconditionally: with tokens already in
+        // hand that await would defer the refresh below by a microtask, and callers
+        // rely on a concurrent burst reaching the single-flight in the SAME tick.
+        let tokens = this.tokens ?? (await this.ensureTokens());
+        if (this.needsRefresh()) {
+            try {
+                await this.refreshNow();
+            }
+            catch (err) {
+                return (await this.reBootstrap(err)).accessToken;
+            }
+            tokens = this.tokens ?? tokens;
+        }
+        return tokens.accessToken;
     }
-    /** Current absolute expiry (epoch ms). */
+    /** Current absolute expiry (epoch ms), or `0` before the first bootstrap. */
     getExpiresAt() {
-        return this.expiresAt;
+        return this.tokens?.expiresAt ?? 0;
     }
     /**
      * Run an authenticated request with reactive 401-replay. `call` receives a
@@ -472,13 +981,31 @@ export class TokenManager {
         const usedToken = await this.getAccessToken();
         let res = await call(usedToken);
         if (res.status === 401) {
-            if (this.accessToken === usedToken)
-                await this.refreshNow();
-            res = await call(this.accessToken);
+            if (this.tokens?.accessToken === usedToken) {
+                // Same revoked-credential recovery getAccessToken has: a 401 replay must
+                // not be the one entry point that throws where the other re-mints.
+                try {
+                    await this.refreshNow();
+                }
+                catch (err) {
+                    await this.reBootstrap(err);
+                }
+            }
+            res = await call(this.tokens?.accessToken ?? usedToken);
         }
         return res;
     }
 }
+/** Whether a parsed record has the shape of {@link PersistedCookieSession}. */
+function isPersistedCookieSession(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return false;
+    const r = raw;
+    if (typeof r.sessionAt !== 'number' || !Number.isFinite(r.sessionAt))
+        return false;
+    // Field-by-field, like isBearerTokens: a primitive is not a session shape.
+    return typeof r.session === 'object' && r.session !== null;
+}
 /**
  * Cookie-session analog of {@link TokenManager}: owns a site's cookie-session
  * lifecycle with the same single-flight / replay / clear-on-settle discipline,
@@ -531,6 +1058,17 @@ export class CookieSessionManager {
     maxAgeMs;
     now;
     onReplayLoginErrorFn;
+    persistence;
+    onPersistErrorFn;
+    /** Persistence is consulted once per process; a miss must not be re-read. */
+    persistenceRead = false;
+    /**
+     * Serializes persistence writes. `seed()` and `invalidate()` are synchronous
+     * by contract and so fire-and-forget their save/clear; with an async backend a
+     * slow save could otherwise land AFTER the clear that followed it and leave an
+     * invalidated session on disk.
+     */
+    persistChain = Promise.resolve();
     constructor(opts) {
         this.loginFn = opts.login;
         // Optional: ensure-only consumers (no per-request expiry path) omit it; the
@@ -540,6 +1078,8 @@ export class CookieSessionManager {
         this.maxAgeMs = opts.maxAgeMs;
         this.now = opts.now ?? Date.now;
         this.onReplayLoginErrorFn = opts.onReplayLoginError;
+        this.persistence = opts.persistence;
+        this.onPersistErrorFn = opts.onPersistError;
     }
     /** The current session, or `undefined` before the first successful login. */
     get current() {
@@ -588,6 +1128,12 @@ export class CookieSessionManager {
         this.session = session;
         this.sessionAt = this.now();
         this.inFlight = undefined; // detach any in-flight login (it won't re-stamp)
+        // The caller has installed a session, so the stored one is superseded and
+        // must never be restored over it (or over a later invalidate()).
+        this.persistenceRead = true;
+        // Fire-and-forget: seed() is synchronous by contract, and a persistence
+        // failure must not change what the caller just installed.
+        void this.persist(session, this.sessionAt);
     }
     /**
      * One login attempt. Self-clears `inFlight` on settle so a rejected login
@@ -602,14 +1148,35 @@ export class CookieSessionManager {
         const holder = {};
         holder.p = (async () => {
             try {
+                // A restored session is the whole point: skip the login entirely.
+                // Guarded rather than awaited unconditionally — with no persistence the
+                // await would defer loginFn() past the tick a concurrent burst needs.
+                const restored = this.persistence !== undefined && !this.persistenceRead
+                    ? await this.restoreFromPersistence()
+                    : null;
+                if (restored !== null) {
+                    if (this.inFlight === holder.p) {
+                        this.session = restored.session;
+                        this.sessionAt = restored.sessionAt;
+                    }
+                    return restored.session;
+                }
                 const session = await this.loginFn();
+                const at = this.now();
                 if (this.inFlight === holder.p) {
                     this.session = session;
-                    this.sessionAt = this.now();
+                    this.sessionAt = at;
                 }
+                await this.persist(session, at);
                 return session;
             }
             catch (err) {
+                // A failed WRITE is not a failed login: routing it through
+                // isPermanentError can cache a transient disk error as permanent, and
+                // then every ensure() after the next expiry throws forever without ever
+                // retrying. The session itself was minted fine.
+                if (err instanceof StatePersistenceError)
+                    throw err.cause;
                 if (this.isPermanentErrorFn(err))
                     this.permanentError = err;
                 throw err;
@@ -630,6 +1197,86 @@ export class CookieSessionManager {
     invalidate() {
         this.session = undefined;
         this.inFlight = undefined;
+        // Fire-and-forget, and unconditional: the stored copy is the same session
+        // that just proved unusable. Leaving it would have the next ensure() read
+        // it back and loop on the very expiry that caused this call.
+        void this.clearPersisted();
+    }
+    /**
+     * The persisted session, if there is one worth using. Read at most once per
+     * process — after that the in-memory session (or its absence) is the truth,
+     * so an invalidate() cannot be undone by a stale file.
+     */
+    async restoreFromPersistence() {
+        if (this.persistence === undefined || this.persistenceRead)
+            return null;
+        this.persistenceRead = true;
+        try {
+            // Through the chain, not around it: `invalidate()` queues its `clear()`,
+            // and a read that jumped that queue would restore the very session the
+            // clear is about to remove.
+            let raw = null;
+            await this.enqueuePersist(async () => {
+                raw = await this.persistence?.load();
+            });
+            if (!isPersistedCookieSession(raw))
+                return null;
+            // Honour the proactive TTL against the ORIGINAL login time.
+            if (this.maxAgeMs !== undefined && this.now() - raw.sessionAt >= this.maxAgeMs)
+                return null;
+            return raw;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Append a persistence op to the chain, preserving call order.
+     *
+     * The RETURNED promise can reject — that is the whole `StatePersistenceError`
+     * path, and the awaited login write depends on it. Only the retained chain is
+     * swallowed, so one failed write cannot poison every later one.
+     */
+    enqueuePersist(op) {
+        const next = this.persistChain.then(op);
+        this.persistChain = next.catch(() => undefined);
+        return next;
+    }
+    /** Write the session. Silent unless `onPersistError` throws. */
+    persist(session, sessionAt) {
+        return this.enqueuePersist(async () => {
+            if (this.persistence === undefined)
+                return;
+            try {
+                await this.persistence.save({ session, sessionAt });
+            }
+            catch (err) {
+                // The in-memory session is still usable for this process. A hook that
+                // rethrows is wrapped so runLogin can tell a disk failure from a login
+                // failure — see the catch there.
+                if (this.onPersistErrorFn === undefined)
+                    return;
+                try {
+                    this.onPersistErrorFn(err);
+                }
+                catch (hookErr) {
+                    throw new StatePersistenceError(hookErr);
+                }
+            }
+        });
+    }
+    /** Discard the persisted session. Never throws. */
+    clearPersisted() {
+        return this.enqueuePersist(async () => {
+            if (this.persistence?.clear === undefined)
+                return;
+            try {
+                await this.persistence.clear();
+            }
+            catch {
+                /* best-effort */
+            }
+        });
     }
     /**
      * Run an authenticated `call` with the current session and reactive