@chrischall/mcp-utils 0.14.2 → 0.16.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 { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, renameSync, unlinkSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
 import { randomBytes } 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,336 @@ export class SessionStore {
         this.mostRecentKey = null;
     }
 }
+/**
+ * File-backed {@link StatePersistence}. 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.
+ *
+ * Nothing here throws. A load failure (absent, corrupt, rejected by `validate`)
+ * returns `null`; a save failure is swallowed and leaves the previous file
+ * intact. 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;
+    return {
+        load() {
+            if (!existsSync(filePath))
+                return null;
+            try {
+                const raw = JSON.parse(readFileSync(filePath, 'utf8'));
+                if (validate !== undefined)
+                    return validate(raw);
+                return raw;
+            }
+            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);
+                writeFileSync(tmp, JSON.stringify(state, 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 {
+                // Degrade to in-memory. Best-effort cleanup of the temp file so a
+                // failed write does not litter the data dir.
+                try {
+                    if (existsSync(tmp))
+                        unlinkSync(tmp);
+                }
+                catch {
+                    /* best-effort */
+                }
+            }
+        },
+        clear() {
+            try {
+                if (existsSync(filePath))
+                    unlinkSync(filePath);
+            }
+            catch {
+                /* best-effort */
+            }
+        },
+    };
+}
+/**
+ * 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;
+    const base = readEnvVar('MCP_DATA_DIR', { env }) ?? readEnvVar('HOME', { env }) ?? homedir();
+    return opts.subdir !== undefined ? join(base, opts.subdir) : base;
+}
 // ===========================================================================
-// 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;
     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;
     }
     /** 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. Never throws — a failed write costs a login, not a request. */
+    async persist(t) {
+        if (this.persistence === undefined)
+            return;
+        try {
+            await this.persistence.save(t);
+        }
+        catch {
+            /* in-memory tokens are still valid for this process */
+        }
+    }
+    /** 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;
+        await this.persist(fresh);
+        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) {
+        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 +745,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 +822,16 @@ export class CookieSessionManager {
     maxAgeMs;
     now;
     onReplayLoginErrorFn;
+    persistence;
+    /** 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 +841,7 @@ export class CookieSessionManager {
         this.maxAgeMs = opts.maxAgeMs;
         this.now = opts.now ?? Date.now;
         this.onReplayLoginErrorFn = opts.onReplayLoginError;
+        this.persistence = opts.persistence;
     }
     /** The current session, or `undefined` before the first successful login. */
     get current() {
@@ -588,6 +890,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,11 +910,26 @@ 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) {
@@ -630,6 +953,70 @@ 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. Never throws. */
+    enqueuePersist(op) {
+        const next = this.persistChain.then(op);
+        this.persistChain = next.catch(() => undefined);
+        return next;
+    }
+    /** Write the session. Never throws — a failed write costs a login, not a request. */
+    persist(session, sessionAt) {
+        return this.enqueuePersist(async () => {
+            if (this.persistence === undefined)
+                return;
+            try {
+                await this.persistence.save({ session, sessionAt });
+            }
+            catch {
+                /* the in-memory session is still usable for this process */
+            }
+        });
+    }
+    /** 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