@skrr-ai/auth-core 0.1.2

package/dist/cjs/refreshClassification.d.ts

@@ -0,0 +1,53 @@
+/**
+ * refreshClassification.ts — pure HTTP→{Permanent, Transient, Success} mapping.
+ *
+ * Extracted from refresh.ts so RN-side clients (which can't pull the full
+ * Node-bound refresh module) can apply the same response classification
+ * the daemon does. The byte-equal mirror in mobile is at
+ * `mobile/react-native/src/api/authProtocol.ts` — keep both files in sync.
+ * (2026-08 — the codeless/unknown-401 → `UNKNOWN_401` change below still needs
+ * to be ported to that mirror in the mobile repo, which is a separate git root
+ * gitignored from this one; until then mobile keeps the old immediate-latch
+ * behaviour, which is safe — it just re-auths a touch more eagerly.)
+ *
+ * Pure: no fetch, no fs, no lock. Caller passes in the parsed response and
+ * the http status; we return a discriminated union.
+ */
+import { PermanentAuthFailure, TransientAuthFailure, type PermanentAuthReason } from './types.js';
+export { PermanentAuthFailure, TransientAuthFailure };
+export type { PermanentAuthReason };
+export interface RefreshResponseShape {
+    /** Optional server-supplied error code, e.g. 'REFRESH_REUSED'. */
+    code?: string;
+    /** Optional human-readable error message. */
+    message?: string;
+    /** When 200, the new access token. */
+    token?: string;
+    /** When 200, the (possibly rotated) refresh token. */
+    refreshToken?: string;
+}
+export interface ClassifiedRefreshSuccess {
+    kind: 'success';
+    token: string;
+    refreshToken?: string;
+}
+export interface ClassifiedRefreshFailure {
+    kind: 'failure';
+    failure: PermanentAuthFailure | TransientAuthFailure;
+}
+export type ClassifiedRefreshResult = ClassifiedRefreshSuccess | ClassifiedRefreshFailure;
+/**
+ * Classify an HTTP response from /api/auth/refresh (or /api/daemons/token/refresh)
+ * into a discriminated union of success or failure.
+ *
+ * Rules match the canonical doRefresh() logic in refresh.ts:
+ *  - 200 + body.token → success
+ *  - 429             → TransientAuthFailure (rate-limited, caller should back off)
+ *  - 401 + known permanent code → PermanentAuthFailure with that reason
+ *  - 401 + unknown/missing code → PermanentAuthFailure('UNKNOWN_401', ...) — AMBIGUOUS,
+ *      a caller with a retry budget may ride it out (see the WEB interceptor and the
+ *      daemon's UNKNOWN_401_BUDGET in refresh.ts); a caller without one fails closed.
+ *  - 4xx (not 429)   → PermanentAuthFailure('REFRESH_INVALID', ...) — server explicitly rejected
+ *  - 5xx / null body / anything else → TransientAuthFailure (transient, retry OK)
+ */
+export declare function classifyRefreshResponse(status: number, body: RefreshResponseShape | null): ClassifiedRefreshResult;

package/dist/cjs/refreshClassification.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * refreshClassification.ts — pure HTTP→{Permanent, Transient, Success} mapping.
+ *
+ * Extracted from refresh.ts so RN-side clients (which can't pull the full
+ * Node-bound refresh module) can apply the same response classification
+ * the daemon does. The byte-equal mirror in mobile is at
+ * `mobile/react-native/src/api/authProtocol.ts` — keep both files in sync.
+ * (2026-08 — the codeless/unknown-401 → `UNKNOWN_401` change below still needs
+ * to be ported to that mirror in the mobile repo, which is a separate git root
+ * gitignored from this one; until then mobile keeps the old immediate-latch
+ * behaviour, which is safe — it just re-auths a touch more eagerly.)
+ *
+ * Pure: no fetch, no fs, no lock. Caller passes in the parsed response and
+ * the http status; we return a discriminated union.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransientAuthFailure = exports.PermanentAuthFailure = void 0;
+exports.classifyRefreshResponse = classifyRefreshResponse;
+const types_js_1 = require("./types.js");
+Object.defineProperty(exports, "PermanentAuthFailure", { enumerable: true, get: function () { return types_js_1.PermanentAuthFailure; } });
+Object.defineProperty(exports, "TransientAuthFailure", { enumerable: true, get: function () { return types_js_1.TransientAuthFailure; } });
+/**
+ * Maps server-supplied error codes to the canonical PermanentAuthReason values
+ * exported from types.ts. Only the four values present in PermanentAuthReason
+ * are listed; anything else falls through to 'REFRESH_INVALID'.
+ */
+const PERMANENT_CODE_SET = new Set([
+    'REFRESH_INVALID',
+    'REFRESH_REUSED',
+    'REFRESH_EXPIRED',
+    'SESSION_REVOKED',
+]);
+/**
+ * Classify an HTTP response from /api/auth/refresh (or /api/daemons/token/refresh)
+ * into a discriminated union of success or failure.
+ *
+ * Rules match the canonical doRefresh() logic in refresh.ts:
+ *  - 200 + body.token → success
+ *  - 429             → TransientAuthFailure (rate-limited, caller should back off)
+ *  - 401 + known permanent code → PermanentAuthFailure with that reason
+ *  - 401 + unknown/missing code → PermanentAuthFailure('UNKNOWN_401', ...) — AMBIGUOUS,
+ *      a caller with a retry budget may ride it out (see the WEB interceptor and the
+ *      daemon's UNKNOWN_401_BUDGET in refresh.ts); a caller without one fails closed.
+ *  - 4xx (not 429)   → PermanentAuthFailure('REFRESH_INVALID', ...) — server explicitly rejected
+ *  - 5xx / null body / anything else → TransientAuthFailure (transient, retry OK)
+ */
+function classifyRefreshResponse(status, body) {
+    // Success
+    if (status === 200 && body?.token) {
+        return {
+            kind: 'success',
+            token: body.token,
+            refreshToken: body.refreshToken,
+        };
+    }
+    // 429 — rate limited, transient
+    if (status === 429) {
+        return {
+            kind: 'failure',
+            failure: new types_js_1.TransientAuthFailure(body?.message ?? 'Refresh rate-limited by server'),
+        };
+    }
+    // 401 — auth failure; check for known permanent code
+    if (status === 401) {
+        const code = body?.code;
+        if (code && PERMANENT_CODE_SET.has(code)) {
+            return {
+                kind: 'failure',
+                failure: new types_js_1.PermanentAuthFailure(code, body?.message ?? code),
+            };
+        }
+        // Unknown-shape 401 (no code, or a code we don't recognise). This is NOT a
+        // proven credential death: the refresh endpoint returns a codeless 401 for
+        // benign, self-healing conditions too — the refresh cookie simply not riding
+        // along on THIS request (SameSite suppression on a cross-site entry / a
+        // restored tab), or a token another concurrent refresh already rotated (the
+        // loser presents a now-rotated token; its next same-origin retry carries the
+        // successor and succeeds). Labelling those permanent makes a single transient
+        // 401 sign the user out of every tab while the server-side session is still
+        // alive and unexpired. So classify as `UNKNOWN_401`: still a
+        // PermanentAuthFailure so a caller with no retry budget stays safe (fails
+        // closed), but a distinct code the WEB interceptor recognises and rides out
+        // under a bounded budget before latching (mirrors the daemon's
+        // UNKNOWN_401_BUDGET in refresh.ts). A KNOWN death code above still latches
+        // immediately.
+        return {
+            kind: 'failure',
+            failure: new types_js_1.PermanentAuthFailure('UNKNOWN_401', body?.message ?? 'Unknown auth failure'),
+        };
+    }
+    // Other 4xx (not 429, not 401) — server explicitly rejected, not retryable
+    if (status >= 400 && status < 500) {
+        return {
+            kind: 'failure',
+            failure: new types_js_1.PermanentAuthFailure('REFRESH_INVALID', body?.message ?? `HTTP ${status}`),
+        };
+    }
+    // 200 without a token (malformed success), 5xx, network-level errors, or any
+    // other status — treat as transient so the caller's retry loop can recover.
+    return {
+        kind: 'failure',
+        failure: new types_js_1.TransientAuthFailure(body?.message ?? `HTTP ${status}`),
+    };
+}

package/dist/cjs/refreshScheduler.d.ts

@@ -0,0 +1,53 @@
+export interface RefreshSchedulerOptions {
+    /**
+     * Invoked when the scheduler decides to refresh. Must return the fresh
+     * access token object on success (so the scheduler can chain-schedule
+     * from it) or null on any failure. On null the failure counter is bumped.
+     */
+    onRefresh: () => Promise<{
+        accessToken: string;
+    } | null>;
+    /**
+     * Current access token getter. Used on wake to reschedule from the
+     * canonical token when the in-memory one is stale (e.g. another process
+     * rotated while we were asleep).
+     */
+    getAccessToken: () => string | undefined | null;
+    /** Log prefix label. Default "refresh". */
+    label?: string;
+    /** How long before `exp` to fire refresh. Default 5 min. */
+    refreshBufferMs?: number;
+    /** Fallback interval if `exp` cannot be decoded. Default 30 min. */
+    fallbackIntervalMs?: number;
+    /** Max consecutive onRefresh failures before giving up. Default 3. */
+    maxFailures?: number;
+    /** Test hooks. */
+    setTimeoutFn?: (cb: () => void, ms: number) => NodeJS.Timeout;
+    clearTimeoutFn?: (timer: NodeJS.Timeout) => void;
+    nowFn?: () => number;
+    /** Backoff cap — controls onWake drift threshold (2×). Default 120_000. */
+    backoffCapMs?: number;
+    /**
+     * Override the kill-switch check. When undefined (default) the package's
+     * runtime-injected kill switches are consulted. Useful for tests.
+     */
+    disabled?: boolean;
+}
+export interface RefreshScheduler {
+    /** Schedule refresh for a token by decoding its exp. Cancels any existing timer. */
+    schedule(token: string): void;
+    /** Schedule using an explicit TTL in seconds (for opaque tokens). */
+    scheduleFromExpiresIn(expiresInSeconds: number): void;
+    /** Cancel any pending refresh. */
+    cancel(): void;
+    /** Call on wake/visibility change to detect dropped fires. */
+    onWake(): void;
+    /** Test-only: expose the current timer state. */
+    readonly _debugState: {
+        scheduledFor: number | null;
+        generation: number;
+        consecutiveFailures: number;
+        longTailAttempt: number;
+    };
+}
+export declare function createRefreshScheduler(opts: RefreshSchedulerOptions): RefreshScheduler;

package/dist/cjs/refreshScheduler.js

@@ -0,0 +1,332 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRefreshScheduler = createRefreshScheduler;
+/**
+ * refreshScheduler.ts — proactive, sleep-aware JWT refresh scheduler.
+ *
+ * Why: reactive refresh (wait for 4401, then rotate) loses minutes of
+ * latency and surfaces as user-visible reconnect flicker. Scheduling a
+ * refresh BEFORE exp means the socket never trips the auth floor in
+ * steady state. Reactive refresh stays as the correctness floor — this
+ * scheduler is the comfort layer.
+ *
+ * Core invariants:
+ *
+ *   1. Generation counter per scheduler. Every schedule() / cancel() bumps
+ *      it. In-flight `doRefresh()` callbacks check generation before setting
+ *      any follow-up timer — so a late callback from a stale schedule
+ *      never hijacks the live timer chain.
+ *
+ *   2. Follow-up timer after every successful refresh. A one-shot timer
+ *      is insufficient for long-lived processes: once the first proactive
+ *      fire rotates the token, we re-derive `exp` from the new token and
+ *      schedule the next fire. Fallback to fallbackIntervalMs (default 30 m)
+ *      when the new token is opaque or undecodable.
+ *
+ *   3. Failure cap. If onRefresh returns null more than maxFailures times
+ *      in a row, stop rescheduling until schedule() is called externally
+ *      again. Prevents spinning forever against a broken backend.
+ *
+ *   4. .unref() on every timer. The scheduler must never be the reason the
+ *      process stays alive.
+ *
+ *   5. Sleep detection. onWake() compares Date.now() against the recorded
+ *      fire target. If wallclock has jumped past fire-target + 2×backoffCap,
+ *      the timer fired while the CPU was frozen (laptop lid) — we lost the
+ *      fire and must reschedule from the current token. Cheap when no drift.
+ */
+const runtime_js_1 = require("./runtime.js");
+const jwtUtils_js_1 = require("./jwtUtils.js");
+/** Refresh buffer: fire this long BEFORE exp. Default 5 min. */
+const DEFAULT_REFRESH_BUFFER_MS = 5 * 60 * 1000;
+/** Fallback refresh interval when the new token's expiry is unknown. */
+const DEFAULT_FALLBACK_INTERVAL_MS = 30 * 60 * 1000;
+/** Max consecutive onRefresh failures before giving up. */
+const DEFAULT_MAX_FAILURES = 3;
+/** Retry spacing between onRefresh failures. */
+const REFRESH_RETRY_DELAY_MS = 60_000;
+/**
+ * ±60 s jitter applied to the computed delay. Spreading the fleet prevents
+ * a 1M-daemon thundering herd after an outage recovery.
+ */
+const REFRESH_JITTER_MS = 60 * 1000;
+/** Floor on scheduled delay — never fire sooner than this. Guards against
+ *  clock skew producing negative delays with jitter. */
+const MIN_DELAY_FLOOR_MS = 30_000;
+/** Minimum effective refresh buffer — preserves SOME lead time even on
+ *  pathologically short-TTL tokens. */
+const MIN_REFRESH_BUFFER_FLOOR_MS = 5_000;
+/** Sleep/wake detection threshold: 2 × backoff cap (default 4 min). */
+const DEFAULT_BACKOFF_CAP_MS = 120_000;
+/**
+ * Long-tail recovery — see S2 fix. After `maxFailures` consecutive
+ * `onRefresh` returns of null, instead of stopping forever the scheduler
+ * arms a slow exponential-backoff timer that keeps probing in the
+ * background. Reset on the next successful refresh. Numbers chosen so the
+ * worst-case dead-comfort-layer window is bounded at 30 min instead of an
+ * unbounded "until the socket disconnects" forever.
+ */
+const LONG_TAIL_INITIAL_DELAY_MS = 5 * 60 * 1000;
+const LONG_TAIL_MAX_DELAY_MS = 30 * 60 * 1000;
+const LONG_TAIL_BACKOFF_FACTOR = 2;
+function formatDuration(ms) {
+    if (ms < 60_000)
+        return `${Math.round(ms / 1000)}s`;
+    const m = Math.floor(ms / 60_000);
+    const s = Math.round((ms % 60_000) / 1000);
+    return s > 0 ? `${m}m ${s}s` : `${m}m`;
+}
+/**
+ * Long-tail delay for attempt N (1-indexed). N=0 returns the initial delay
+ * — used the first time we transition into long-tail. Capped at
+ * LONG_TAIL_MAX_DELAY_MS.
+ */
+function computeLongTailDelay(currentAttempt) {
+    const exponent = Math.max(0, currentAttempt);
+    const delay = LONG_TAIL_INITIAL_DELAY_MS * Math.pow(LONG_TAIL_BACKOFF_FACTOR, exponent);
+    return Math.min(delay, LONG_TAIL_MAX_DELAY_MS);
+}
+function createRefreshScheduler(opts) {
+    const log = (0, runtime_js_1.getAuthLogger)();
+    const label = opts.label ?? 'refresh';
+    // Kill-switch resolution: explicit `opts.disabled` wins, else runtime-
+    // injected `killSwitches.refreshScheduler`. Defaults to enabled.
+    const disabled = opts.disabled ?? (0, runtime_js_1.getAuthKillSwitches)().refreshScheduler ?? false;
+    if (disabled) {
+        let warnedOnce = false;
+        const warnDisabled = (method) => {
+            if (!warnedOnce) {
+                log.warn(`[${label}] refresh scheduler is disabled via kill switch — ${method}() is a no-op; falling back to pre-scheduler refresh path`);
+                warnedOnce = true;
+            }
+        };
+        return {
+            schedule(_token) {
+                warnDisabled('schedule');
+            },
+            scheduleFromExpiresIn(_expiresInSeconds) {
+                warnDisabled('scheduleFromExpiresIn');
+            },
+            cancel() {
+                /* no-op */
+            },
+            onWake() {
+                /* no-op */
+            },
+            get _debugState() {
+                return {
+                    scheduledFor: null,
+                    generation: 0,
+                    consecutiveFailures: 0,
+                    longTailAttempt: 0,
+                };
+            },
+        };
+    }
+    const refreshBufferMs = opts.refreshBufferMs ?? DEFAULT_REFRESH_BUFFER_MS;
+    const fallbackIntervalMs = opts.fallbackIntervalMs ?? DEFAULT_FALLBACK_INTERVAL_MS;
+    const maxFailures = opts.maxFailures ?? DEFAULT_MAX_FAILURES;
+    const backoffCapMs = opts.backoffCapMs ?? DEFAULT_BACKOFF_CAP_MS;
+    const setTimeoutFn = opts.setTimeoutFn ??
+        global.setTimeout;
+    const clearTimeoutFn = opts.clearTimeoutFn ?? global.clearTimeout;
+    const now = opts.nowFn ?? (() => Date.now());
+    let timer = null;
+    let generation = 0;
+    let consecutiveFailures = 0;
+    let scheduledFor = null;
+    /**
+     * S2 fix: when `consecutiveFailures` hits `maxFailures` we don't stop
+     * forever — instead we enter long-tail recovery and probe with
+     * exponential backoff. `longTailAttempt` is 0 outside long-tail and the
+     * 1-indexed attempt number while in it. Reused for delay computation:
+     * delay = min(INITIAL × FACTOR^(attempt-1), MAX).
+     */
+    let longTailAttempt = 0;
+    function bumpGeneration() {
+        generation += 1;
+        return generation;
+    }
+    function clearTimer() {
+        if (timer) {
+            try {
+                clearTimeoutFn(timer);
+            }
+            catch {
+                /* ignore */
+            }
+            timer = null;
+        }
+        scheduledFor = null;
+    }
+    function setDelayTimer(delayMs, gen) {
+        const effective = Math.max(MIN_DELAY_FLOOR_MS, delayMs);
+        scheduledFor = now() + effective;
+        const t = setTimeoutFn(() => {
+            void doRefresh(gen);
+        }, effective);
+        if (t && typeof t.unref === 'function') {
+            try {
+                t.unref();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        timer = t;
+    }
+    /**
+     * H8 fix: a flat 5-minute buffer breaks for tokens with TTL < 10 min — the
+     * buffer meets-or-exceeds TTL, producing a <=0 baseDelay and an immediate-
+     * refresh loop. Clamp effective buffer to ttlMs/2 when configured buffer
+     * exceeds half the TTL. Never below MIN_REFRESH_BUFFER_FLOOR_MS so we
+     * preserve some lead time. When TTL/2 is itself below the floor (sub-10s
+     * tokens) the token is so short-lived we accept an immediate refresh.
+     */
+    function effectiveBufferForTtl(ttlMs) {
+        if (ttlMs <= 0)
+            return refreshBufferMs;
+        const half = ttlMs / 2;
+        if (refreshBufferMs > half) {
+            const clamped = Math.max(half, MIN_REFRESH_BUFFER_FLOOR_MS);
+            log.debug(`[${label}] refresh buffer clamped: ${formatDuration(refreshBufferMs)} → ${formatDuration(clamped)} (ttl=${formatDuration(ttlMs)})`);
+            return clamped;
+        }
+        return refreshBufferMs;
+    }
+    function schedule(token) {
+        const exp = (0, jwtUtils_js_1.decodeJwtExpiry)(token);
+        clearTimer();
+        const gen = bumpGeneration();
+        // External re-arm exits long-tail mode. The generation bump already
+        // invalidates any in-flight long-tail callback; reset the counter here
+        // so the next failure run starts fresh.
+        longTailAttempt = 0;
+        consecutiveFailures = 0;
+        if (!exp) {
+            log.debug(`[${label}] token has no decodable exp; using fallback interval ${formatDuration(fallbackIntervalMs)}`);
+            setDelayTimer(fallbackIntervalMs, gen);
+            return;
+        }
+        const expMs = exp * 1000;
+        const ttlMs = expMs - now();
+        const effectiveBuffer = effectiveBufferForTtl(ttlMs);
+        const baseDelay = ttlMs - effectiveBuffer;
+        const jitter = (Math.random() * 2 - 1) * REFRESH_JITTER_MS;
+        const delayMs = baseDelay + jitter;
+        if (delayMs <= 0) {
+            log.debug(`[${label}] token exp=${new Date(expMs).toISOString()} is past or inside buffer — refreshing immediately`);
+            scheduledFor = now();
+            setDelayTimer(0, gen);
+            return;
+        }
+        log.debug(`[${label}] scheduling refresh in ${formatDuration(delayMs)} (exp=${new Date(expMs).toISOString()})`);
+        setDelayTimer(delayMs, gen);
+    }
+    function scheduleFromExpiresIn(expiresInSeconds) {
+        clearTimer();
+        const gen = bumpGeneration();
+        const ttlMs = expiresInSeconds * 1000;
+        const effectiveBuffer = effectiveBufferForTtl(ttlMs);
+        const delayMs = Math.max(ttlMs - effectiveBuffer, MIN_DELAY_FLOOR_MS);
+        log.debug(`[${label}] scheduling refresh in ${formatDuration(delayMs)} (expires_in=${expiresInSeconds}s, buffer=${formatDuration(effectiveBuffer)})`);
+        setDelayTimer(delayMs, gen);
+    }
+    function cancel() {
+        bumpGeneration();
+        clearTimer();
+        consecutiveFailures = 0;
+        longTailAttempt = 0;
+    }
+    async function doRefresh(gen) {
+        if (gen !== generation) {
+            log.debug(`[${label}] stale doRefresh (gen ${gen} vs ${generation}) — skipping`);
+            return;
+        }
+        let result = null;
+        try {
+            result = await opts.onRefresh();
+        }
+        catch (err) {
+            log.warn(`[${label}] onRefresh threw: ${err?.message}`);
+            result = null;
+        }
+        if (gen !== generation) {
+            log.debug(`[${label}] post-refresh stale (gen ${gen} vs ${generation}) — skipping follow-up`);
+            return;
+        }
+        if (!result) {
+            consecutiveFailures += 1;
+            if (consecutiveFailures >= maxFailures) {
+                // S2 fix: instead of stopping forever after maxFailures, enter
+                // long-tail recovery. The first time we hit the cap we log
+                // `daemon_token_refresh_give_up` for backwards-compatible alerting,
+                // then arm a slow exponential-backoff probe. On every long-tail
+                // attempt we emit a structured log so operators can alert on
+                // sustained degradation. Reset on success.
+                const longTailDelay = computeLongTailDelay(longTailAttempt);
+                const isFirstEntry = longTailAttempt === 0;
+                if (isFirstEntry) {
+                    log.error('[auth/refresh] daemon_token_refresh_give_up', {
+                        label,
+                        failures: consecutiveFailures,
+                        reason: 'max_consecutive_failures',
+                    });
+                    longTailAttempt = 1;
+                }
+                else {
+                    longTailAttempt += 1;
+                }
+                log.warn('[auth/refresh] daemon_token_refresh_long_tail_attempt', {
+                    label,
+                    attempt: longTailAttempt,
+                    nextDelayMs: longTailDelay,
+                });
+                setDelayTimer(longTailDelay, gen);
+                return;
+            }
+            log.warn(`[${label}] refresh failed (${consecutiveFailures}/${maxFailures}) — retrying in ${formatDuration(REFRESH_RETRY_DELAY_MS)}`);
+            setDelayTimer(REFRESH_RETRY_DELAY_MS, gen);
+            return;
+        }
+        // Successful refresh — fully recover from long-tail (if active) and
+        // chain-schedule from the new token's exp.
+        consecutiveFailures = 0;
+        longTailAttempt = 0;
+        const newExp = (0, jwtUtils_js_1.decodeJwtExpiry)(result.accessToken);
+        if (newExp) {
+            schedule(result.accessToken);
+        }
+        else {
+            log.debug(`[${label}] refreshed token has no decodable exp — using fallback interval`);
+            clearTimer();
+            const nextGen = bumpGeneration();
+            setDelayTimer(fallbackIntervalMs, nextGen);
+        }
+    }
+    function onWake() {
+        if (scheduledFor === null)
+            return;
+        const drift = now() - scheduledFor;
+        const threshold = 2 * backoffCapMs;
+        if (drift <= threshold)
+            return;
+        log.info(`[${label}] wake detected drift ${formatDuration(drift)} past scheduled fire — rescheduling`);
+        const currentToken = opts.getAccessToken();
+        if (!currentToken) {
+            log.warn(`[${label}] onWake: no access token available; cancelling timer`);
+            cancel();
+            return;
+        }
+        schedule(currentToken);
+    }
+    return {
+        schedule,
+        scheduleFromExpiresIn,
+        cancel,
+        onWake,
+        get _debugState() {
+            return { scheduledFor, generation, consecutiveFailures, longTailAttempt };
+        },
+    };
+}