@skrr-ai/auth-core 0.1.2

package/dist/esm/refresh.js

@@ -0,0 +1,863 @@
+/**
+ * refresh.ts — refresh-token client for OverSky daemon-style sessions.
+ *
+ * Responsibilities:
+ *   1. Single-flight per daemonId: concurrent callers share one in-flight HTTP
+ *      request so we don't fire 6 refreshes for 6 parallel API calls (which
+ *      would race-rotate and trip the server's family-reuse detector).
+ *   2. File-locked read-modify-write on `<configDir>/auth.lock` so the daemon,
+ *      Electron main, and CLI can't corrupt the stored token pair.
+ *   3. Structured error classification — callers get either
+ *      PermanentAuthFailure (stop reconnecting, show re-auth UX) or
+ *      TransientAuthFailure (network glitch, retry later).
+ *   4. Persists a needs-reauth flag so the next start / Electron read can
+ *      surface the banner without another round-trip.
+ *
+ * Lock strategy: `proper-lockfile` is battle-tested on Linux/macOS/Windows.
+ * Every read-modify-write is wrapped in `withAuthLock()`. The lock is
+ * released in `finally` — crash between acquire and release leaves a stale
+ * `.lock` file that `proper-lockfile` invalidates after `LOCK_STALE_MS`
+ * (30 s, longer than any reasonable refresh RTT).
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import lockfile from 'proper-lockfile';
+import { getAuthLogger, getAuthConfigDir, emitAuthTelemetry, notifyResponseObserver, } from './runtime.js';
+import { PermanentAuthFailure, TransientAuthFailure, } from './types.js';
+/**
+ * P1-6: Reduced from 30 s to 5 s.
+ *
+ * The original 30 s matched the worst-case refresh RTT — meaning a
+ * crashed process holding `auth.lock` could block all siblings for up
+ * to 30 s, risking a deadlock on degraded networks. 5 s is well above
+ * any realistic refresh RTT (p99 ≈ 50 ms) but low enough that a stale
+ * lock from a crashed daemon clears before the outer reconnect backoff
+ * times out.
+ */
+const LOCK_STALE_MS = 5_000;
+const LOCK_RETRY_MS = 100;
+const LOCK_MAX_RETRIES = 50; // ~5 s total wait before giving up
+/**
+ * P1-6: Module-level guard so registering process-exit handlers is
+ * idempotent. A second import (or a unit test that re-requires the
+ * module) must not double-register the same handlers.
+ */
+let _exitHandlersInstalled = false;
+/**
+ * D-4 — Re-entrancy tracking for `withAuthLock`.
+ *
+ * `proper-lockfile` is NOT re-entrant within a process: a second
+ * `lockfile.lock()` call on the same file from the same process will
+ * block until `LOCK_STALE_MS` (5 s) elapses and treat itself as stale —
+ * effectively a 5 s deadlock. Several call sites legitimately nest:
+ *
+ *   performRefresh → withAuthLock → saveToken → withAuthLock (new)
+ *   consumeFdAuth  → saveToken    → withAuthLock (new, no outer lock)
+ *
+ * `AsyncLocalStorage` propagates across `await` boundaries within the
+ * same async call chain, so a nested `withAuthLock` invocation in the
+ * same chain can detect "outer lock already held" and skip the
+ * `proper-lockfile` acquire. Cross-process callers each have their own
+ * ALS store and always go through the real file lock.
+ *
+ * The store carries a boolean: `true` = the current async context
+ * already holds the auth lock.
+ */
+const _authLockHeld = new AsyncLocalStorage();
+function authLockPath() {
+    return path.join(getAuthConfigDir(), 'auth.lock');
+}
+function reauthFlagPath() {
+    return path.join(getAuthConfigDir(), 'needs-reauth.json');
+}
+/**
+ * P1-6 — Register best-effort lock-release handlers on process exit
+ * signals so a crash or SIGTERM during a refresh leaves the lock file
+ * in a released state. Without this, a sibling process must wait up to
+ * `LOCK_STALE_MS` (5 s) for `proper-lockfile` to declare the lock stale.
+ *
+ * Guards:
+ *   - `_exitHandlersInstalled` (module-level): safe to call multiple
+ *     times (e.g., from unit-test re-imports) — handlers are registered
+ *     exactly once per process.
+ *   - Every handler swallows errors: `lockfile.unlockSync` throws when
+ *     the lock file doesn't exist or was never acquired; we must not
+ *     crash the process during shutdown.
+ *
+ * `lockfile.unlockSync` is available in `proper-lockfile` ≥ 4.1.0 and
+ * removes the `.lock` companion directory that `proper-lockfile` creates
+ * next to `auth.lock`. It is synchronous so it runs safely in POSIX
+ * signal handlers and `process.on('exit')`.
+ */
+export function installLockExitHandlers() {
+    if (_exitHandlersInstalled)
+        return;
+    _exitHandlersInstalled = true;
+    function tryRelease() {
+        try {
+            lockfile.unlockSync(authLockPath());
+        }
+        catch {
+            /* lock not held or already released — not an error */
+        }
+    }
+    process.on('exit', tryRelease);
+    process.on('SIGTERM', () => {
+        tryRelease();
+        process.exit(0);
+    });
+    process.on('SIGINT', () => {
+        tryRelease();
+        process.exit(130);
+    });
+    process.on('SIGHUP', () => {
+        tryRelease();
+        process.exit(1);
+    });
+}
+/**
+ * Acquire the cross-process auth lock, run the body, release on `finally`.
+ * Throws if the lock can't be acquired within
+ * `LOCK_MAX_RETRIES × LOCK_RETRY_MS`.
+ *
+ * We lock a sentinel file (auth.lock) that we create/touch if missing —
+ * locking the real auth.json would race with atomic-rename writes.
+ *
+ * @param daemonId  When supplied, lock-lifecycle telemetry events are emitted:
+ *   refresh_lock_acquiring, refresh_lock_acquired, refresh_lock_released.
+ */
+export async function withAuthLock(body, daemonId) {
+    // D-4 — Re-entrancy guard. If the current async context already holds
+    // the auth lock (e.g. performRefresh → withAuthLock → saveToken →
+    // withAuthLock), skip the proper-lockfile acquire to avoid the 5 s
+    // deadlock that would occur because proper-lockfile is not re-entrant
+    // within a process. Cross-process callers each have their own ALS store
+    // and always go through the real file lock.
+    if (_authLockHeld.getStore() === true) {
+        return body();
+    }
+    const lockPath = authLockPath();
+    const dir = path.dirname(lockPath);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    if (!fs.existsSync(lockPath)) {
+        fs.writeFileSync(lockPath, '', { mode: 0o600 });
+    }
+    const acquireStart = Date.now();
+    emitAuthTelemetry({
+        timestamp: new Date().toISOString(),
+        eventType: 'auth',
+        success: true,
+        metadata: { event: 'refresh_lock_acquiring', ...(daemonId ? { daemonId } : {}) },
+    });
+    const release = await lockfile.lock(lockPath, {
+        stale: LOCK_STALE_MS,
+        retries: {
+            retries: LOCK_MAX_RETRIES,
+            minTimeout: LOCK_RETRY_MS,
+            maxTimeout: LOCK_RETRY_MS * 4,
+            factor: 1.5,
+        },
+    });
+    const acquiredAt = Date.now();
+    emitAuthTelemetry({
+        timestamp: new Date().toISOString(),
+        eventType: 'auth',
+        success: true,
+        metadata: {
+            event: 'refresh_lock_acquired',
+            waitedMs: acquiredAt - acquireStart,
+            ...(daemonId ? { daemonId } : {}),
+        },
+    });
+    // Run body inside ALS context marking the lock as held for this async chain.
+    return _authLockHeld.run(true, async () => {
+        try {
+            return await body();
+        }
+        finally {
+            const heldForMs = Date.now() - acquiredAt;
+            emitAuthTelemetry({
+                timestamp: new Date().toISOString(),
+                eventType: 'auth',
+                success: true,
+                metadata: {
+                    event: 'refresh_lock_released',
+                    heldForMs,
+                    ...(daemonId ? { daemonId } : {}),
+                },
+            });
+            try {
+                await release();
+            }
+            catch (err) {
+                getAuthLogger().debug(`[auth/refresh] lock release failed: ${err?.message}`);
+            }
+        }
+    });
+}
+/**
+ * In-flight refresh promises keyed by daemonId. Coalesces concurrent callers.
+ *
+ * Keying matters: an unkeyed map silently returned the wrong pair if two
+ * different daemons (or a future Electron host running multiple embedded
+ * daemons) refreshed simultaneously in the same process. Today most
+ * processes are single-instance, but the invariant is cheaper to preserve
+ * than to debug later.
+ *
+ * Defense-in-depth: the `.finally(() => delete)` is the primary cleanup,
+ * but if a future caller throws inside that callback the entry would leak
+ * forever and silently mask every subsequent refresh attempt for the same
+ * daemonId. `INFLIGHT_REAP_MS` provides a forced cleanup ceiling well above
+ * any reasonable refresh RTT (default 60 s ≫ p99 ~50 ms).
+ */
+const inflightRefreshes = new Map();
+const INFLIGHT_REAP_MS = 60_000;
+/**
+ * Consecutive unknown-shape-401 budget per daemonId.
+ *
+ * A 401 from `/token/refresh` whose body `code` is NOT one of the four
+ * credential-death codes (REFRESH_INVALID / REFRESH_REUSED /
+ * REFRESH_EXPIRED / SESSION_REVOKED) — an unknown code, a missing code,
+ * or an unparseable body — is most likely an artifact of infra OverSky
+ * does not fully control: a proxy/middleware regression, a clock-skew
+ * replay rejection (DEVICE_PROOF_REPLAYED), or a half-rolled-out server
+ * route. By construction it is NOT a daemon's actual refresh-family burn
+ * (those arrive as one of the four known codes).
+ *
+ * Pre-fix every unknown-shape 401 latched `PermanentAuthFailure('UNKNOWN_401')`
+ * + `persistReauthState` on the FIRST occurrence — forcing a manual
+ * reconnect even when the next refresh would have succeeded. Now the
+ * first `UNKNOWN_401_BUDGET` unknown-401s accumulated on a given daemonId
+ * (within `UNKNOWN_401_WINDOW_MS`, see the reset/window rules below) throw
+ * `TransientAuthFailure` instead, so the daemon's
+ * `performRefresh → return false` path lets the refreshScheduler /
+ * reactive retry+backoff ride out a transient regression WITHOUT latching
+ * needs-reauth. Only after the budget is exhausted do we fall back to the
+ * original permanent latch — preserving the iron rule that the interactive
+ * re-auth modal remains the final fallback.
+ *
+ * The four KNOWN codes are genuinely permanent and are NEVER routed
+ * through this budget — they latch immediately as before.
+ *
+ * Counter semantics:
+ *   - Incremented on each consecutive unknown-shape 401 for a daemonId.
+ *   - Reset to zero ONLY on a DEFINITIVE outcome that tells us about the
+ *     credential's true state: a 200 success (credential alive) OR a
+ *     KNOWN-permanent 401 (credential dead, recognized). It is DELIBERATELY
+ *     NOT reset on a transient non-401 outcome (network error, 429, 5xx).
+ *
+ *     RESET SEMANTICS (Finding 4 follow-up — deliberate). Originally the
+ *     streak reset on ANY non-unknown-401 outcome, including transient ones.
+ *     That created a retry-forever hole: a dead-but-unknown-code credential
+ *     whose endpoint INTERMITTENTLY returns transient errors (a flaky proxy
+ *     that alternates 503 ↔ unknown-401, say) could never accumulate
+ *     `UNKNOWN_401_BUDGET` consecutive unknown-401s — every transient blip
+ *     wiped the streak — so it would never latch and the daemon would retry
+ *     forever, never surfacing the re-auth affordance. By treating only
+ *     success / known-permanent-401 as streak-resetting, a flaky-but-dead
+ *     unknown credential still converges to the permanent latch: the
+ *     unknown-401s accumulate ACROSS interleaved transient noise (subject to
+ *     the window below) and eventually exhaust the budget.
+ *   - Bounded window: if the previous unknown-401 for this daemonId is
+ *     older than `UNKNOWN_401_WINDOW_MS`, the run is considered stale and
+ *     the counter restarts at 1. This bounds how far apart interleaved
+ *     unknown-401s can be and still count toward the same latch, so two
+ *     genuinely unrelated incidents hours apart don't sum into a premature
+ *     latch — while a flaky-but-dead credential, which keeps producing
+ *     unknown-401s well within the window, still converges.
+ */
+/**
+ * BOOT-BUDGET COUPLING (Finding 4 follow-up). Exported so the daemon's
+ * startup-recovery loop can statically assert
+ * `STARTUP_RECOVERY_MAX_ATTEMPTS >= UNKNOWN_401_BUDGET`.
+ *
+ * Why the coupling is load-bearing: the boot path
+ * (`recoverAccessTokenAtStartup` in `daemon/src/auth.ts`) retries
+ * `transient_error` results up to `STARTUP_RECOVERY_MAX_ATTEMPTS` times,
+ * then exits `EX_TEMPFAIL` so the supervisor restarts the process. Each
+ * in-budget unknown-shape 401 is classified `transient_error`. If the
+ * boot loop's max attempts were LESS than this budget, a
+ * genuinely-dead-but-unknown-code credential would make the boot loop
+ * give up (EX_TEMPFAIL → supervisor restart) BEFORE the in-process
+ * budget ever exhausts and latches `PermanentAuthFailure('UNKNOWN_401')`
+ * + persists needs-reauth. The supervisor would then restart-loop
+ * forever and the user would NEVER see the re-auth affordance — a
+ * strand. Keeping `STARTUP_RECOVERY_MAX_ATTEMPTS >= UNKNOWN_401_BUDGET`
+ * guarantees the in-process budget exhausts and latches within a single
+ * boot, on the final boot attempt, before control returns to the
+ * supervisor. The daemon enforces this with a module-load static
+ * assertion (`assertStartupRecoveryCoversUnknown401Budget`) plus a unit
+ * test; see `daemon/src/auth.ts`.
+ */
+export const UNKNOWN_401_BUDGET = 3;
+const UNKNOWN_401_WINDOW_MS = 5 * 60_000;
+const unknown401Streaks = new Map();
+/**
+ * Record one unknown-shape 401 for `daemonId` and report whether the
+ * consecutive budget is now exhausted (i.e. this occurrence should latch
+ * permanent) or still within budget (i.e. this occurrence should be
+ * treated as transient and retried).
+ *
+ * Returns `{ exhausted, count }` where `count` is the post-increment
+ * consecutive streak length. When `exhausted` is true the streak is
+ * cleared so a subsequent successful re-auth + future regression starts
+ * a fresh budget rather than latching on its first unknown-401.
+ */
+function recordUnknown401(daemonId, now) {
+    const prev = unknown401Streaks.get(daemonId);
+    // A gap longer than the window means the prior unknown-401 belongs to a
+    // different, already-resolved incident — restart the streak at 1.
+    const count = prev && now - prev.lastAt <= UNKNOWN_401_WINDOW_MS ? prev.count + 1 : 1;
+    if (count >= UNKNOWN_401_BUDGET) {
+        // Budget exhausted — clear so the next regression (after a successful
+        // re-auth) gets its own fresh budget instead of latching immediately.
+        unknown401Streaks.delete(daemonId);
+        return { exhausted: true, count };
+    }
+    unknown401Streaks.set(daemonId, { count, lastAt: now });
+    return { exhausted: false, count };
+}
+/**
+ * Reset the unknown-shape-401 streak for `daemonId`. Called ONLY on the
+ * two DEFINITIVE outcomes — a 200 success or a KNOWN-permanent 401 — that
+ * tell us the credential's true state. Transient non-401 outcomes
+ * (network error, 429, 5xx) intentionally do NOT call this, so a
+ * flaky-but-dead unknown credential still converges to the permanent
+ * latch instead of retrying forever. See the `UNKNOWN_401_BUDGET` /
+ * `recordUnknown401` block above for the full rationale.
+ */
+function resetUnknown401Streak(daemonId) {
+    unknown401Streaks.delete(daemonId);
+}
+/** Test-only: clear all per-daemonId unknown-401 streak state. */
+export function __resetUnknown401StreaksForTest() {
+    unknown401Streaks.clear();
+}
+/**
+ * H1 — Test-only diagnostic counters that prove every outgoing refresh
+ * request to `/refresh` is paired with a freshly-built proof.
+ *
+ *   - `requestAttemptCount`: incremented each time `buildRequestInit()`
+ *     prepares an outgoing fetch.
+ *   - `proofAttemptCount`: incremented each time `signRequestProof` is
+ *     invoked (success, null return, OR thrown — they all count as
+ *     "an attempt was made").
+ *
+ * Invariant under test: when `signRequestProof` is supplied,
+ * `proofAttemptCount === requestAttemptCount` after each call. A future
+ * retry that forgets to re-call `buildRequestInit()` (or that hoists
+ * the proof outside the loop) breaks this invariant immediately.
+ *
+ * Exposed only for tests — no production code reads it. Callers can
+ * snapshot + reset between asserts.
+ */
+export const __refreshDiagnostics = {
+    proofAttemptCount: 0,
+    requestAttemptCount: 0,
+    reset() {
+        this.proofAttemptCount = 0;
+        this.requestAttemptCount = 0;
+    },
+};
+export async function refreshDaemonToken(serverUrl, currentRefreshToken, daemonId, options = {}) {
+    const existing = inflightRefreshes.get(daemonId);
+    if (existing) {
+        // A concurrent caller is coalescing onto the in-flight promise.
+        // refresh_race_resolved fires when it resolves (the caller adopted
+        // the sibling's token rather than firing a duplicate HTTP request).
+        return existing.then((pair) => {
+            emitAuthTelemetry({
+                timestamp: new Date().toISOString(),
+                eventType: 'auth',
+                success: true,
+                metadata: { event: 'refresh_race_resolved', daemonId, sourceTokenAdopted: true },
+            });
+            return pair;
+        });
+    }
+    const p = doRefresh(serverUrl, currentRefreshToken, daemonId, options).finally(() => {
+        // Only delete our own entry — a racing caller could have replaced it,
+        // but with keying by daemonId that would be a different key.
+        if (inflightRefreshes.get(daemonId) === p) {
+            inflightRefreshes.delete(daemonId);
+        }
+    });
+    inflightRefreshes.set(daemonId, p);
+    // Belt-and-suspenders reap if the `finally` ever throws (logger crash etc.).
+    const reaper = setTimeout(() => {
+        if (inflightRefreshes.get(daemonId) === p) {
+            try {
+                getAuthLogger().warn(`[auth/refresh] inflight reap fired for ${daemonId} — finally cleanup did not complete within ${INFLIGHT_REAP_MS}ms`);
+            }
+            catch {
+                /* logger unavailable */
+            }
+            inflightRefreshes.delete(daemonId);
+        }
+    }, INFLIGHT_REAP_MS);
+    if (typeof reaper.unref === 'function')
+        reaper.unref();
+    return p;
+}
+/**
+ * Best-effort server-side revocation of a refresh session. Idempotent on
+ * the server — never reveals whether the presented token existed. Returns
+ * silently on transport failure; callers still proceed with local cleanup.
+ *
+ * Kept tight: 5-second timeout so a hung server doesn't stall logout.
+ *
+ * H1 (HIGH) — wire contract: the body carries BOTH `refreshTokenHash`
+ * (preferred — SHA-256 hex digest of the plaintext refresh token, the
+ * exact value the server stores in `refreshHash`) AND the legacy
+ * `refreshToken` plaintext during a migration window. Newer servers
+ * short-circuit on `refreshTokenHash` and never read the plaintext;
+ * older servers ignore the unknown field and fall through to the
+ * legacy `refreshToken` path. Once the next API release ships the
+ * hash-aware revoke route to the entire fleet, the legacy plaintext
+ * field can be dropped from this body.
+ *
+ * Why both during migration: any intermediary that logs request
+ * bodies (CDN, WAF, API gateway, corporate proxy) would otherwise
+ * capture a usable refresh token in plaintext. The refresh path
+ * already only sends what the server hashes server-side; the revoke
+ * path's contract previously leaked the token in transit. Sending
+ * the hash makes the body ineligible as a credential for any future
+ * replay attempt while keeping back-compat with un-upgraded servers.
+ */
+export async function revokeDaemonRefreshSession(serverUrl, refreshToken) {
+    if (!refreshToken)
+        return;
+    const log = getAuthLogger();
+    const url = `${serverUrl.replace(/\/+$/, '')}/api/daemons/token/revoke`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 5_000);
+    // H1 — SHA-256 hex digest matches the server's `hashRefreshToken`
+    // helper byte-for-byte: `crypto.createHash('sha256').update(token).digest('hex')`.
+    // 64-char lowercase hex string, the exact lookup key in the
+    // `refreshHash` index.
+    const refreshTokenHash = crypto.createHash('sha256').update(refreshToken, 'utf8').digest('hex');
+    try {
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ refreshTokenHash, refreshToken }),
+            signal: controller.signal,
+        });
+        notifyResponseObserver(res);
+        if (!res.ok) {
+            log.debug(`[auth/refresh] revoke returned ${res.status}`);
+        }
+    }
+    catch (err) {
+        log.debug(`[auth/refresh] revoke network error: ${err?.message}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function doRefresh(serverUrl, currentRefreshToken, daemonId, options = {}) {
+    const log = getAuthLogger();
+    const startMs = Date.now();
+    emitAuthTelemetry({
+        timestamp: new Date().toISOString(),
+        eventType: 'auth',
+        success: true,
+        metadata: { event: 'refresh_start', daemonId },
+    });
+    const url = `${serverUrl.replace(/\/+$/, '')}/api/daemons/token/refresh`;
+    // Build body with machineUuid only when supplied — preserves backward
+    // compat with older servers that ignore unknown fields. The server's
+    // soft-binding check (H7) tolerates either side missing the field.
+    const body = {
+        refreshToken: currentRefreshToken,
+        daemonId,
+    };
+    if (options.machineUuid) {
+        body.machineUuid = options.machineUuid;
+    }
+    // H1 — Per-attempt request builder. The proof MUST be minted once
+    // per outgoing HTTP request: every fetch carries a fresh `iat` +
+    // `jti` so the server-side replay cache (`seen-jti:{thumbprint}:{jti}`,
+    // see `api/server/services/Auth/jtiReplayCache.js`) never rejects a
+    // legitimate retry as a duplicate. If the proof were minted once and
+    // reused across retries, every retry would deterministically lose
+    // to the cache.
+    //
+    // Today the function only makes one HTTP attempt — but the contract
+    // is "every outgoing request to /refresh uses a freshly-built proof"
+    // and we want the structure to enforce it before any future retry
+    // logic re-introduces the bug. The attempt counter is exposed via
+    // a test-only diagnostic (`__refreshDiagnostics`) so we can assert
+    // the invariant without exporting a private control surface.
+    //
+    // FOOTGUN — do NOT hoist `buildRequestInit` outside this function or
+    // outside any future retry loop. The structural test
+    // "proof-per-attempt invariant: a retry loop must call buildRequestInit()
+    // per attempt" in `refresh.deviceProof.test.ts` asserts the function
+    // is defined inside `doRefresh` and will fail if it is moved.
+    function buildRequestInit() {
+        // Phase 3-R5: the stable `X-Oversky-Origin` header is the server's
+        // preferred identity signal on the benign-grace rotation match. Newer
+        // servers prefer it over the raw User-Agent; older servers ignore
+        // unknown headers. Safe one-sided change either way.
+        const headers = { 'Content-Type': 'application/json' };
+        if (options.origin) {
+            headers['X-Oversky-Origin'] = options.origin;
+        }
+        // L11 Phase 3 — attach a device-identity proof when the daemon-side
+        // bridge can mint one. A null/undefined return or a thrown callback
+        // is non-fatal: the request goes out without the header and the
+        // server's lenient middleware (`off` / `warn` mode default) accepts
+        // it. Once the operator flips `OVERSKY_DEVICE_PROOF_ENFORCE=enforce`
+        // on the server, a missing-proof request from an enrolled daemon
+        // becomes a 401 — but daemons that reach this code path always have
+        // device identity initialized via `prefetchAuth()`, so the only
+        // legitimate "missing proof" case is a daemon binary older than
+        // Phase 1.
+        __refreshDiagnostics.requestAttemptCount += 1;
+        if (options.signRequestProof) {
+            try {
+                const proof = options.signRequestProof({
+                    method: 'POST',
+                    url,
+                    refreshToken: currentRefreshToken,
+                });
+                // Count every callback invocation, including ones that
+                // returned null/empty/threw. The invariant we care about is
+                // "one mint per attempt" — whether the mint produced a usable
+                // header is a separate concern (legacy daemons, key not yet
+                // initialized, etc.).
+                __refreshDiagnostics.proofAttemptCount += 1;
+                if (typeof proof === 'string' && proof.length > 0) {
+                    headers['OverSky-DPoP'] = proof;
+                }
+            }
+            catch (err) {
+                // Even a thrown callback counts as an attempt — the daemon
+                // bridge tried to mint, the mint failed, and we proceed
+                // without the header. Without this count the invariant
+                // would silently drift if a future regression made the
+                // callback throw on every-other call.
+                __refreshDiagnostics.proofAttemptCount += 1;
+                log.debug(`[auth/refresh] signRequestProof threw — proceeding without device-identity header: ${err?.message ?? 'unknown'}`);
+            }
+        }
+        return {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(body),
+        };
+    }
+    let response;
+    try {
+        // Single attempt today. The builder structure is the load-bearing
+        // bit: any future retry must call `buildRequestInit()` again so
+        // the per-attempt invariant — fresh jti per request — holds.
+        response = await fetch(url, buildRequestInit());
+        notifyResponseObserver(response);
+    }
+    catch (err) {
+        log.warn(`[auth/refresh] network error: ${err?.message}`);
+        // RESET SEMANTICS (Finding 4 follow-up): a transient (network) outcome
+        // does NOT reset the unknown-401 streak. Resetting here would let a
+        // dead-but-unknown-code credential whose endpoint INTERMITTENTLY drops
+        // the connection never accumulate to the latch — it would retry forever
+        // because every other network blip wipes the streak. The streak resets
+        // ONLY on a 200 success or a KNOWN-permanent 401 (see those branches).
+        emitAuthTelemetry({
+            timestamp: new Date().toISOString(),
+            eventType: 'auth',
+            success: false,
+            metadata: {
+                event: 'refresh_failure',
+                daemonId,
+                durationMs: Date.now() - startMs,
+                errorCode: 'NETWORK_ERROR',
+            },
+        });
+        throw new TransientAuthFailure('Network error during refresh', err);
+    }
+    // TODO: refresh.ts could delegate to classifyRefreshResponse(response.status, body)
+    // from ./refreshClassification.ts once mobile parity is validated and device tests
+    // cover the 401/429/5xx branches. Today the inline classification is kept to avoid
+    // the risk of a behavioural regression in the daemon's S1/S2/S3 paths without full
+    // test coverage. See packages/auth-core/src/refreshClassification.ts for the
+    // extracted pure helper that mobile uses.
+    if (response.status === 200) {
+        const data = (await response.json());
+        // Soft backoff hint (production-hardening 2026-05-06). Server-side
+        // sets `X-Refresh-Backoff: <seconds>` when fleet refresh-QPS is
+        // high; the daemon's scheduler should defer its NEXT proactive
+        // refresh by that amount + jitter. Distinct from 429 Retry-After
+        // which signals "this request was rejected" — soft backoff fires
+        // on 200 responses, the rotation succeeded, and ignoring the hint
+        // is safe but causes the herd to reconverge.
+        //
+        // Parse defensively: a malformed header (negative, NaN, absurdly
+        // large) produces `undefined` so consumers fall through to their
+        // own scheduler defaults.
+        // Cap at 10 min so a misconfigured / compromised server cannot pin
+        // daemons to a multi-hour interval and starve them of refresh.
+        const SOFT_BACKOFF_MAX_SECONDS = 600;
+        let softBackoffSeconds;
+        const backoffHeader = response.headers.get('X-Refresh-Backoff');
+        if (typeof backoffHeader === 'string') {
+            const parsed = parseInt(backoffHeader, 10);
+            if (Number.isFinite(parsed) && parsed > 0) {
+                if (parsed > SOFT_BACKOFF_MAX_SECONDS) {
+                    getAuthLogger().warn(`[auth/refresh] X-Refresh-Backoff=${parsed}s exceeds ${SOFT_BACKOFF_MAX_SECONDS}s cap — clamping`);
+                }
+                softBackoffSeconds = Math.min(parsed, SOFT_BACKOFF_MAX_SECONDS);
+            }
+        }
+        const pair = {
+            // Coerce empty string / undefined to null so consumers branch
+            // on a single canonical shape (the wire may legitimately ship
+            // any of three things for daemon scope: `null` literal, field
+            // absent, or empty string). Non-daemon scopes always supply a
+            // non-empty JWT here.
+            accessToken: typeof data.accessToken === 'string' && data.accessToken.length > 0
+                ? data.accessToken
+                : null,
+            accessExpiresAt: new Date(data.accessExpiresAt).getTime(),
+            refreshToken: data.refreshToken,
+            refreshExpiresAt: new Date(data.refreshExpiresAt).getTime(),
+            // Distinguish "field absent" (older server, leave caller's
+            // existing value alone) from "field present but null" (server
+            // explicitly cleared, callers MUST overwrite their cache).
+            // Three-valued semantic mirrors the daemon-side saveToken
+            // options bag — see daemon/src/auth.ts JSDoc.
+            opaqueAccessToken: Object.prototype.hasOwnProperty.call(data, 'opaqueAccessToken')
+                ? typeof data.opaqueAccessToken === 'string'
+                    ? data.opaqueAccessToken
+                    : null
+                : undefined,
+            ...(softBackoffSeconds !== undefined ? { softBackoffSeconds } : {}),
+        };
+        log.info(`[auth/refresh] rotated — access expires in ${Math.round((pair.accessExpiresAt - Date.now()) / 1000)}s`);
+        emitAuthTelemetry({
+            timestamp: new Date().toISOString(),
+            eventType: 'auth',
+            success: true,
+            metadata: {
+                event: 'refresh_success',
+                daemonId,
+                durationMs: Date.now() - startMs,
+                tokensRotated: true,
+            },
+        });
+        // RESET SEMANTICS (Finding 4 follow-up): a 200 success is one of only
+        // TWO outcomes that reset the unknown-401 streak (the other is a
+        // KNOWN-permanent 401). A success PROVES the credential is alive and the
+        // endpoint healthy, so any prior unknown-401 run was genuinely transient
+        // — the next regression starts with a fresh budget. Transient non-401
+        // outcomes (network/429/5xx) deliberately do NOT reset, so a flaky-but-
+        // dead unknown credential still converges to the permanent latch.
+        resetUnknown401Streak(daemonId);
+        try {
+            clearReauthState();
+        }
+        catch {
+            /* ignore */
+        }
+        return pair;
+    }
+    if (response.status === 429) {
+        // RESET SEMANTICS (Finding 4 follow-up): a 429 is transient and does
+        // NOT reset the unknown-401 streak. A dead-but-unknown-code credential
+        // whose endpoint also intermittently rate-limits must still converge to
+        // the permanent latch; resetting here would let it retry forever.
+        emitAuthTelemetry({
+            timestamp: new Date().toISOString(),
+            eventType: 'auth',
+            success: false,
+            metadata: {
+                event: 'refresh_failure',
+                daemonId,
+                durationMs: Date.now() - startMs,
+                errorCode: 'RATE_LIMITED',
+                statusCode: 429,
+            },
+        });
+        throw new TransientAuthFailure('Refresh rate-limited by server');
+    }
+    if (response.status === 401) {
+        let parsedBody = {};
+        try {
+            parsedBody = (await response.json());
+        }
+        catch {
+            /* ignore */
+        }
+        const code = parsedBody.code;
+        const permanent = [
+            'REFRESH_INVALID',
+            'REFRESH_REUSED',
+            'REFRESH_EXPIRED',
+            'SESSION_REVOKED',
+        ];
+        if (code && permanent.includes(code)) {
+            // A KNOWN credential-death code is genuinely permanent — latch
+            // immediately, exactly as before. It is NOT routed through the
+            // unknown-401 budget.
+            //
+            // RESET SEMANTICS (Finding 4 follow-up): this is one of only TWO
+            // outcomes that reset the unknown-401 streak (the other is a 200
+            // success). We reset here because the server just spoke a definitive,
+            // recognized verdict about the credential — whatever it says next
+            // about an unknown-shape 401 starts a clean run, and we also prevent a
+            // prior unknown-401 run from compounding with a real family-burn.
+            resetUnknown401Streak(daemonId);
+            log.warn(`[auth/refresh] permanent failure: ${code} — ${parsedBody.message ?? ''}`);
+            emitAuthTelemetry({
+                timestamp: new Date().toISOString(),
+                eventType: 'auth',
+                success: false,
+                metadata: {
+                    event: 'refresh_failure',
+                    daemonId,
+                    durationMs: Date.now() - startMs,
+                    errorCode: code,
+                    statusCode: 401,
+                },
+            });
+            persistReauthState({ code, message: parsedBody.message, at: Date.now() });
+            throw new PermanentAuthFailure(code, parsedBody.message || code);
+        }
+        // Unknown-shape 401 — unknown code, missing code, or unparseable body.
+        // By construction this is NOT a daemon's actual refresh-family burn
+        // (those arrive as one of the four KNOWN codes above); it most likely
+        // came from infra OverSky does not fully control — a proxy/middleware
+        // regression, a clock-skew replay rejection (DEVICE_PROOF_REPLAYED),
+        // or a half-rolled-out server route.
+        //
+        // Pre-fix every such 401 latched `PermanentAuthFailure('UNKNOWN_401')`
+        // + `persistReauthState` on the FIRST occurrence, forcing a manual
+        // reconnect even when the next refresh would have succeeded. Now we
+        // give a bounded retry budget: the first `UNKNOWN_401_BUDGET`
+        // consecutive unknown-401s on this daemonId throw `TransientAuthFailure`
+        // (NO persistReauthState), so the daemon's `performRefresh → return false`
+        // path lets the scheduler / reactive retry+backoff ride out a transient
+        // regression. Only once the budget is exhausted do we fall back to the
+        // original permanent latch — keeping the interactive re-auth modal as
+        // the FINAL fallback. The distinct `UNKNOWN_401` telemetry tag is kept
+        // on BOTH branches so monitoring can still see a server-side bug
+        // separately from a real expiration (and watch the retry-vs-latch split).
+        const message = parsedBody.message || 'Unknown auth failure';
+        const { exhausted, count } = recordUnknown401(daemonId, Date.now());
+        if (!exhausted) {
+            log.warn(`[auth/refresh] unknown-shape 401 (${count}/${UNKNOWN_401_BUDGET}) — treating as transient, will retry: ${message}`);
+            emitAuthTelemetry({
+                timestamp: new Date().toISOString(),
+                eventType: 'auth',
+                success: false,
+                metadata: {
+                    event: 'refresh_failure',
+                    daemonId,
+                    durationMs: Date.now() - startMs,
+                    errorCode: 'UNKNOWN_401',
+                    statusCode: 401,
+                    // Distinguish a transient (retrying) unknown-401 from the
+                    // budget-exhausted latch in the telemetry stream.
+                    transient: true,
+                    unknown401Streak: count,
+                },
+            });
+            throw new TransientAuthFailure(`Unknown auth failure (transient, retrying): ${message}`);
+        }
+        // Budget exhausted within the window — fall back to the original
+        // permanent behavior: latch + persist the reauth flag so the daemon
+        // surfaces the banner and the interactive modal becomes the final
+        // recovery path.
+        log.warn(`[auth/refresh] unknown-shape 401 budget exhausted (${count}/${UNKNOWN_401_BUDGET}) — latching permanent: ${message}`);
+        emitAuthTelemetry({
+            timestamp: new Date().toISOString(),
+            eventType: 'auth',
+            success: false,
+            metadata: {
+                event: 'refresh_failure',
+                daemonId,
+                durationMs: Date.now() - startMs,
+                errorCode: 'UNKNOWN_401',
+                statusCode: 401,
+                transient: false,
+                unknown401Streak: count,
+            },
+        });
+        persistReauthState({
+            code: 'UNKNOWN_401',
+            message,
+            at: Date.now(),
+        });
+        throw new PermanentAuthFailure('UNKNOWN_401', message);
+    }
+    // 5xx / unexpected — transient. Caller will back off.
+    // RESET SEMANTICS (Finding 4 follow-up): a 5xx is transient and does NOT
+    // reset the unknown-401 streak. A dead-but-unknown-code credential whose
+    // endpoint intermittently 5xxs must still converge to the permanent latch;
+    // resetting here would let it retry forever.
+    let bodyText = '';
+    try {
+        bodyText = await response.text();
+    }
+    catch {
+        /* ignore */
+    }
+    emitAuthTelemetry({
+        timestamp: new Date().toISOString(),
+        eventType: 'auth',
+        success: false,
+        metadata: {
+            event: 'refresh_failure',
+            daemonId,
+            durationMs: Date.now() - startMs,
+            errorCode: 'SERVER_ERROR',
+            statusCode: response.status,
+        },
+    });
+    throw new TransientAuthFailure(`Refresh failed (${response.status}): ${bodyText.slice(0, 200)}`);
+}
+export function persistReauthState(state) {
+    const log = getAuthLogger();
+    const flagPath = reauthFlagPath();
+    try {
+        const dir = path.dirname(flagPath);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        fs.writeFileSync(flagPath, JSON.stringify(state, null, 2) + '\n', {
+            mode: 0o600,
+        });
+    }
+    catch (err) {
+        log.debug(`[auth/refresh] failed to persist reauth flag: ${err?.message}`);
+    }
+}
+export function needsReauthState() {
+    try {
+        const flagPath = reauthFlagPath();
+        if (!fs.existsSync(flagPath))
+            return { needed: false };
+        const raw = fs.readFileSync(flagPath, 'utf-8');
+        const state = JSON.parse(raw);
+        return { needed: true, reason: state.code, since: state.at };
+    }
+    catch {
+        return { needed: false };
+    }
+}
+export function clearReauthState() {
+    const log = getAuthLogger();
+    try {
+        const flagPath = reauthFlagPath();
+        if (fs.existsSync(flagPath))
+            fs.unlinkSync(flagPath);
+    }
+    catch (err) {
+        log.debug(`[auth/refresh] clearReauthState: ${err?.message}`);
+    }
+}
+/** Path getters exposed for tests + the daemon's connection.ts handler. */
+export { authLockPath as AUTH_LOCK_PATH_FN, reauthFlagPath as REAUTH_FLAG_PATH_FN };