@chrischall/mcp-utils 0.15.0 → 0.17.0

package/README.md

@@ -32,7 +32,7 @@ import light:
 | Import | Contents |
 | --- | --- |
 | `@chrischall/mcp-utils` | core barrel: `server` + `response` + `errors` + `config` + `fs` + `http` + `concurrency` + `dates` + `zod` + `auth` + `scrape` |
-| `@chrischall/mcp-utils/session` | session registry, session store, token manager, cookie-session manager |
+| `@chrischall/mcp-utils/session` | session registry, session store, state persistence, token manager, cookie-session manager |
 | `@chrischall/mcp-utils/fetchproxy` | fetchproxy transport adapter, bot-wall / retry / concurrency helpers |
 | `@chrischall/mcp-utils/html` | opt-in HTML scraping helpers (needs `node-html-parser`) |
 | `@chrischall/mcp-utils/scrape` | convenience alias for the zero-dep `scrape` module (also in the core barrel) |
@@ -485,6 +485,115 @@ Replaces the hand-rolled re-login / single-flight / 401-replay code in
 `artsonia-mcp`, `canvas-parent-mcp`, `evite-mcp`, `signupgenius-mcp`, and
 `skylight-mcp`.
 
+#### Surviving a restart — `StatePersistence` *(opt-in)*
+
+Both managers own a credential only for the life of the process. On a
+scale-to-zero host that means a full login on every cold start — children idle
+out after ten minutes, several services rate-limit the login endpoint, and one
+escalates repeated attempts to a captcha that breaks server-side auth outright.
+Pass `persistence` and the credential survives instead:
+
+```ts
+import {
+  TokenManager,
+  createFileStatePersistence,
+  resolveStateDir,
+  type BearerTokens,
+} from '@chrischall/mcp-utils/session';
+import { join } from 'node:path';
+
+const tokens = new TokenManager({
+  // Function form: run the login ONLY when nothing usable was restored.
+  initial: () => loginWithPassword(),
+  refresh: (rt) => exchangeRefreshToken(rt),
+  persistence: createFileStatePersistence<BearerTokens>({
+    filePath: join(resolveStateDir({ subdir: '.acme-mcp' }), 'tokens.json'),
+  }),
+});
+```
+
+What that buys, in order of how often it applies: a stored token that is still
+valid costs **nothing**; a stored token that has expired but carries a refresh
+token costs **one refresh** instead of a login; only an empty or unusable store
+runs `initial`. A refresh token revoked between runs is not terminal — the
+stored copy is discarded and the login re-runs, so a stale file cannot brick the
+server. A *transient* refresh failure is treated differently: a `RateLimitedError`,
+a `RequestTimeoutError` or a 5xx `ApiError` surfaces to the caller with the
+refresh token left intact, because destroying a valid credential and burning a
+login on a passing outage is the cost this feature exists to avoid. Override
+`isRefreshRevoked` for a service that signals revocation some other way.
+
+`createFileStatePersistence` writes atomically (temp file + rename), leaves the
+file `0600`, and creates any missing directory `0700` — but does **not**
+re-permission a directory that already exists, since a bare `resolveStateDir()`
+is `$HOME` and `mcp-host` creates the data dir before the child starts. It never
+throws: a read-only or full disk degrades to in-memory operation, costing a
+login rather than a failed request. `resolveStateDir` prefers `MCP_DATA_DIR` — the variable `mcp-host`
+injects for a registration with `state.dataDir: true` — then `HOME`, then the OS
+home directory. It reads both through `readEnvVar`, so blank values, the
+`'null'` / `'undefined'` sentinels and unexpanded `${...}` placeholders are all
+treated as unset (`MCP_DATA_DIR=null` would otherwise be a *relative* `./null`
+directory, quietly parking the credential under the process cwd).
+
+> On `mcp-host`, set `state.dataDir: true` in the repo's `mint.yaml` when you
+> adopt this. Without it the child's `$HOME` is on the container rootfs, which
+> an idle-stop discards — the runner's unpersisted-state detector will report
+> the omission, but the writes still vanish.
+
+`CookieSessionManager` takes the same option, storing `{ session, sessionAt }`
+so `maxAgeMs` keeps counting from the original login. Its `invalidate()` clears
+the stored copy — without that, a session detected as expired would be read back
+off disk and the expiry would loop.
+
+#### Capabilities lifted from the hand-rolled stores
+
+Four repos (`freshbooks-mcp`, `kiaaccess-mcp`, `alphaportal-mcp`, `vibo-mcp`)
+persisted tokens before this helper existed. Auditing them before migrating
+turned up behaviour the first cut did not have:
+
+- **`onPersistError`** — a failed write is swallowed by default, which is right
+  when it merely costs a future re-login. It is wrong for a service that rotates
+  **single-use** refresh tokens: the old one is already spent upstream, so a new
+  one that never reaches disk locks the account out on the next start. Throw
+  from the hook to make the write fatal (`freshbooks-mcp`'s case). Accordingly
+  `createFileStatePersistence.save` now *reports* a failed write by throwing;
+  `load` stays total. A failure raised this way is wrapped in a
+  `StatePersistenceError` so it can never be mistaken for a revoked credential —
+  the refresh that produced it succeeded, so discarding the stored record would
+  destroy the only surviving copy, which is the lockout the option exists to
+  prevent.
+- **`boundTo`** — bind a record to the credential that minted it, so a rotated
+  password or a re-run OAuth bootstrap discards the cache instead of being
+  shadowed by it. Only a salted HMAC digest is written, never the credential, and
+  the salt is fresh per write so the same credential never leaves the same
+  artifact twice. It is a change-detector, not a password store — pass a
+  non-secret discriminator where you have one. (`freshbooks-mcp` tracked this as
+  `seededFromEnv`, storing the raw token.)
+- **`createKeyedFileStatePersistence`** — many records in one file, keyed by
+  account, each key handed out as a plain `StatePersistence` a manager takes
+  directly. Required for any server authenticating as more than one identity,
+  and for anything serving several users from one process, where a
+  single-record file would hand one user's token to the next. Keys normalize
+  trim+lowercase by default, because they are account identities, not origins.
+  Writes are whole-file read-modify-write, so two processes saving different
+  keys at the same instant can drop one update — the loser re-authenticates
+  rather than reading anything wrong, which is the right trade for a credential
+  cache and would not be for a general store.
+- **`resolveStateFile({ envVar, subdir, fileName })`** — an env override for the
+  path, checked through the same hardened `readEnvVar`. Every one of the four
+  had one, and every one used it to keep its test suite off the developer's real
+  `$HOME`.
+
+Records are written in a small envelope (`{ v: 1, boundTo?, state }`). A bare
+record written by an earlier version is still read, so nothing already on disk
+is lost.
+
+Persistence is **opt-in throughout**: a manager constructed without it behaves
+exactly as before, and no credential reaches a disk because a dependency was
+upgraded. The interface is two methods (`load` / `save`, plus an optional
+`clear`), each allowed to be async, so a backend other than the local filesystem
+can be dropped in.
+
 ### `fetchproxy` — transport adapter *(subpath, optional peer)*
 
 ```ts

package/dist/session/index.d.ts

@@ -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.
@@ -179,6 +185,212 @@ export declare class SessionStore<T extends Record<string, unknown>> {
     /** Clear in-memory state without touching disk. Test helper. */
     resetForTest(): void;
 }
+/**
+ * A place to keep a credential between processes.
+ *
+ * Why this exists: {@link TokenManager} and {@link CookieSessionManager} own a
+ * credential's lifecycle *within* a process, and every fleet server used to
+ * throw that credential away on exit — so a cold start re-ran the full login
+ * even when a valid refresh token had been minted seconds earlier. On
+ * `mcp-host` that is the normal case, not the exception: children idle out
+ * after ten minutes and the machine scales to zero behind them. Several
+ * services rate-limit the login endpoint, and at least one (per the kiaaccess
+ * notes) escalates repeated attempts to a captcha that breaks server-side auth
+ * for the account permanently. Re-login is not always a free retry.
+ *
+ * Deliberately opt-in: a manager given no `persistence` behaves exactly as it
+ * did before, and no credential reaches a disk because a package was upgraded.
+ *
+ * Both methods may be sync or async. The fleet's own implementation
+ * ({@link createFileStatePersistence}) is sync — it writes one small file — but
+ * the async signature leaves room for a backend that has to go over a wire.
+ *
+ * **A failing implementation should throw.** Whether losing a write is
+ * survivable is the MANAGER's call, not the store's: for most services a failed
+ * save costs a re-login, but freshbooks-mcp rotates single-use refresh tokens,
+ * so a new token that does not reach disk locks the account out on the next
+ * start. The managers catch every call and, by default, swallow it — pass
+ * `onPersistError` to observe or to make it fatal.
+ */
+export interface StatePersistence<T> {
+    /** Read the stored state; `null` when absent, unparseable, or unusable. */
+    load(): T | null | Promise<T | null>;
+    /** Write state, replacing whatever was there. */
+    save(state: T): void | Promise<void>;
+    /**
+     * Discard the stored state. Optional, but a manager that detects its stored
+     * credential is no good calls this — without it, an expired session is read
+     * straight back off disk and the expiry loops.
+     */
+    clear?(): void | Promise<void>;
+}
+/**
+ * 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 declare class StatePersistenceError extends Error {
+    readonly cause: unknown;
+    constructor(cause: unknown);
+}
+/** Options for {@link createFileStatePersistence}. */
+export interface FileStatePersistenceOptions<T> {
+    /** Absolute path to the JSON file. Parent directories are created as needed. */
+    filePath: string;
+    /**
+     * Bind the record to the credential that minted it. Pass the value whose change
+     * should invalidate the cache — an env-supplied refresh token, an account id.
+     * Only a salted HMAC digest is written, never the value, and the salt is fresh
+     * per write. It is a change-detector rather than a password store, so prefer a
+     * non-secret discriminator where one exists.
+     *
+     * Without this a rotated credential is silently shadowed by a cache minted
+     * from the old one: the operator re-bootstraps, and the server keeps using
+     * what it had. freshbooks-mcp discovered this and tracked it as
+     * `seededFromEnv`; this is the generalised, non-secret-storing form.
+     *
+     * A record with no binding is not accepted when one is required — it cannot
+     * be shown to belong to this credential.
+     */
+    boundTo?: string;
+    /**
+     * Narrow the parsed JSON to `T`, returning `null` to reject it. Without this
+     * any well-formed JSON is handed back and the caller must check the shape —
+     * the managers do, but a custom consumer should pass a guard.
+     */
+    validate?: (raw: unknown) => T | null;
+}
+/**
+ * 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 declare function createFileStatePersistence<T>(opts: FileStatePersistenceOptions<T>): Required<StatePersistence<T>>;
+/** Options for {@link createKeyedFileStatePersistence}. */
+export interface KeyedFileStatePersistenceOptions<T> {
+    /** Absolute path to the shared JSON file. Parent dirs are created as needed. */
+    filePath: string;
+    /** Narrow a stored record to `T`, returning `null` to reject it. */
+    validate?: (raw: unknown) => T | null;
+    /**
+     * Normalize a key before storing or looking up. Defaults to trim + lowercase,
+     * because these keys are account identities (emails, usernames) — NOT origins.
+     * kiaaccess-mcp and alphaportal-mcp both had to override `SessionStore`'s
+     * origin normalizer for exactly this reason, so it is the default here.
+     */
+    normalizeKey?: (key: string) => string;
+}
+/** A keyed store: hand each key out as its own {@link StatePersistence}. */
+export interface KeyedStatePersistence<T> {
+    /**
+     * A single-record view of one key, shaped exactly like the persistence the
+     * managers take — so a multi-account server gives each account its own
+     * {@link TokenManager} over one shared file.
+     */
+    forKey(key: string): Required<StatePersistence<T>>;
+    /** The normalized keys currently held. */
+    keys(): string[];
+}
+/**
+ * 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 declare function createKeyedFileStatePersistence<T>(opts: KeyedFileStatePersistenceOptions<T>): KeyedStatePersistence<T>;
+/** Options for {@link resolveStateDir}. */
+export interface ResolveStateDirOptions {
+    /** Environment to read (defaults to `process.env`) — injectable for tests. */
+    env?: Record<string, string | undefined>;
+    /** Optional service-scoped subdirectory to join onto the base. */
+    subdir?: string;
+}
+/**
+ * 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 declare function resolveStateDir(opts?: ResolveStateDirOptions): string;
+/** Options for {@link resolveStateFile}. */
+export interface ResolveStateFileOptions extends ResolveStateDirOptions {
+    /**
+     * An env var naming the file outright, checked first. Every fleet repo that
+     * hand-rolled persistence has one (`KIA_SESSION_FILE`, `VIBO_SESSION_FILE`,
+     * `ALPHAPORTAL_SESSION_FILE`) and every one of them uses it to keep its test
+     * suite off the developer's real `$HOME` — which is worth having by default
+     * rather than rediscovering per repo.
+     */
+    envVar?: string;
+    /** File name inside the resolved directory. */
+    fileName: string;
+}
+/**
+ * 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 declare function resolveStateFile(opts: ResolveStateFileOptions): string;
 /** Refresh proactively this many ms before the access token expires. */
 export declare const TOKEN_REFRESH_SKEW_MS: number;
 /** A bearer access token + (optional) refresh token + absolute expiry. */
@@ -198,8 +410,21 @@ export interface RefreshedTokens {
 }
 /** Options for {@link TokenManager}. */
 export interface TokenManagerOptions {
-    /** Initial tokens (typically from env or a one-shot bootstrap). */
-    initial: BearerTokens;
+    /**
+     * The starting tokens — either the tokens themselves, or a **bootstrap
+     * function** that mints them (typically a full login).
+     *
+     * Pass the function form to get the persistence benefit: it is invoked only
+     * when {@link TokenManagerOptions.persistence} has nothing usable, so a
+     * restart that finds a stored token never logs in at all, and one that finds
+     * an expired token with a refresh token spends a refresh instead of a login.
+     * It is single-flighted like every other credential operation here, so a
+     * burst of first calls hits a rate-limited login endpoint exactly once.
+     *
+     * The eager object form is unchanged: the caller already paid for the login,
+     * so persistence is not consulted and the tokens are used as given.
+     */
+    initial: BearerTokens | (() => Promise<BearerTokens>);
     /**
      * Exchange the current refresh token for fresh tokens. Called at most once
      * per concurrent burst (the in-flight promise is shared).
@@ -210,36 +435,124 @@ export interface TokenManagerOptions {
      * refresh). Defaults to {@link TOKEN_REFRESH_SKEW_MS} (5 minutes).
      */
     skewMs?: number;
+    /**
+     * Keep tokens across process restarts. Read once on the bootstrap path
+     * (function-form `initial` only), written after every successful bootstrap
+     * and refresh, including rotation. Omit for the previous in-memory-only
+     * behaviour. See {@link StatePersistence}.
+     */
+    persistence?: StatePersistence<BearerTokens>;
+    /**
+     * Decide whether a {@link TokenManagerOptions.refresh} rejection means the
+     * credential itself is dead (re-mint via the bootstrap) or the endpoint was
+     * merely unreachable (surface it, keep the token).
+     *
+     * The distinction matters in both directions. Treating a transient failure as
+     * revocation deletes a still-VALID refresh token and burns a login against an
+     * endpoint that may rate-limit or escalate to a captcha — the exact cost this
+     * whole feature exists to avoid. Treating a real revocation as transient
+     * leaves the server broken until someone deletes the stored file by hand.
+     *
+     * The default resolves that by only excusing failures that are transient *by
+     * construction* — a {@link RateLimitedError}, a {@link RequestTimeoutError},
+     * or an {@link ApiError} with a 5xx status. Anything else is assumed to be a
+     * dead credential, which keeps the recover-from-revocation guarantee. Override
+     * it for a service that signals revocation some other way (or, conversely, one
+     * that answers a live token with a 5xx). Mirrors the permanent-vs-transient
+     * split {@link CookieSessionManagerOptions.isPermanentError} already makes.
+     */
+    isRefreshRevoked?: (err: unknown) => boolean;
+    /**
+     * Called when a {@link TokenManagerOptions.persistence} write fails.
+     *
+     * Default: the failure is swallowed and the request proceeds on the
+     * in-memory token — right when a lost write merely costs a future re-login.
+     * It is WRONG when the service rotates single-use refresh tokens: the old one
+     * is already spent upstream, so a new one that never reaches disk locks the
+     * account out on the next start. **Throw from this hook to make the write
+     * fatal**, with a message naming the recovery (freshbooks-mcp's case).
+     */
+    onPersistError?: (err: unknown) => void;
+    /** Injectable clock (defaults to `Date.now`) — for tests. */
+    now?: () => number;
 }
 /**
  * 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 declare class TokenManager {
-    private accessToken;
-    private refreshToken;
-    private expiresAt;
+    private tokens;
+    private readonly bootstrapFn;
     private readonly refreshFn;
     private readonly skewMs;
+    private readonly persistence;
+    private readonly now;
+    private readonly isRefreshRevokedFn;
+    private readonly onPersistErrorFn;
     private inFlight;
+    private 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.
+     */
+    private persistenceRead;
     constructor(opts: TokenManagerOptions);
     /** Whether the token is within the skew window of (or past) expiry. */
     private needsRefresh;
+    /**
+     * 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.
+     */
+    private isUsable;
+    /** Read persisted tokens, guarding shape and usability. Never throws. */
+    private loadPersisted;
+    /**
+     * Write tokens. Silent by default (a lost write costs a future login, not this
+     * request); throws a {@link StatePersistenceError} when `onPersistError` does.
+     */
+    private persist;
+    /** Discard persisted tokens (a refresh they could not satisfy). Never throws. */
+    private clearPersisted;
+    /** The current tokens, single-flighting the bootstrap if there are none. */
+    private ensureTokens;
+    /** One bootstrap attempt: persisted tokens if usable, else the login. */
+    private runBootstrap;
     /**
      * 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(): Promise<void>;
+    /** One refresh attempt against the current refresh token. */
+    private runRefresh;
+    /**
+     * 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.
+     */
+    private reBootstrap;
     /** Get a valid access token, refreshing proactively inside the skew window. */
     getAccessToken(): Promise<string>;
-    /** Current absolute expiry (epoch ms). */
+    /** Current absolute expiry (epoch ms), or `0` before the first bootstrap. */
     getExpiresAt(): number;
     /**
      * Run an authenticated request with reactive 401-replay. `call` receives a
@@ -329,6 +642,43 @@ export interface CookieSessionManagerOptions<S, R = Response> {
      * login failure to the caller instead of the stale response.
      */
     onReplayLoginError?: (err: unknown) => void;
+    /**
+     * Keep the session across process restarts. Read ONCE, on the first login
+     * path, and written after every successful login and {@link
+     * CookieSessionManager.seed}. {@link CookieSessionManager.invalidate} clears
+     * it — without that, a session detected as expired would be read straight
+     * back off disk and the expiry would loop.
+     *
+     * The stored envelope carries the login time alongside the session so
+     * {@link CookieSessionManagerOptions.maxAgeMs} keeps counting from the
+     * original login rather than restarting at the restore. Omit for the previous
+     * in-memory-only behaviour. See {@link StatePersistence}.
+     */
+    persistence?: StatePersistence<PersistedCookieSession<S>>;
+    /**
+     * Called when a {@link CookieSessionManagerOptions.persistence} write fails.
+     * Swallowed by default — the in-memory session is still usable.
+     *
+     * Where a throwing hook goes depends on which write failed. The login path
+     * awaits its write, so the error reaches a direct {@link CookieSessionManager.ensure}
+     * caller — but it is deliberately NOT offered to
+     * {@link CookieSessionManagerOptions.isPermanentError} first, because caching a
+     * disk error as a permanent config failure would brick every later `ensure()`.
+     *
+     * Two places it does NOT reach the caller. {@link CookieSessionManager.withSession}'s
+     * expiry replay catches `ensure()` and returns the stale response by design, so
+     * a "fatal" write there is dropped unless
+     * {@link CookieSessionManagerOptions.onReplayLoginError} rethrows too. And the
+     * `seed()`/`invalidate()` writes are fire-and-forget onto the ordering chain,
+     * whose retained tail swallows.
+     */
+    onPersistError?: (err: unknown) => void;
+}
+/** What {@link CookieSessionManagerOptions.persistence} stores: a session plus its login time. */
+export interface PersistedCookieSession<S> {
+    session: S;
+    /** Epoch ms the session was minted or seeded — the `maxAgeMs` clock. */
+    sessionAt: number;
 }
 /**
  * Cookie-session analog of {@link TokenManager}: owns a site's cookie-session
@@ -382,6 +732,17 @@ export declare class CookieSessionManager<S = CookieSession, R = Response> {
     private readonly maxAgeMs;
     private readonly now;
     private readonly onReplayLoginErrorFn;
+    private readonly persistence;
+    private readonly onPersistErrorFn;
+    /** Persistence is consulted once per process; a miss must not be re-read. */
+    private persistenceRead;
+    /**
+     * 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.
+     */
+    private persistChain;
     constructor(opts: CookieSessionManagerOptions<S, R>);
     /** The current session, or `undefined` before the first successful login. */
     get current(): S | undefined;
@@ -425,6 +786,24 @@ export declare class CookieSessionManager<S = CookieSession, R = Response> {
      * (new config). Used to recover from a detected session expiry.
      */
     invalidate(): void;
+    /**
+     * 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.
+     */
+    private restoreFromPersistence;
+    /**
+     * 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.
+     */
+    private enqueuePersist;
+    /** Write the session. Silent unless `onPersistError` throws. */
+    private persist;
+    /** Discard the persisted session. Never throws. */
+    private clearPersisted;
     /**
      * Run an authenticated `call` with the current session and reactive
      * expiry-replay. `call` receives the session and returns a `Response`. If

package/dist/session/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"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"}