@skrr-ai/auth-core 0.1.2

package/dist/esm/refresh.d.ts

@@ -0,0 +1,215 @@
+import { type ReauthState, type TokenPair } from './types.js';
+declare function authLockPath(): string;
+declare function reauthFlagPath(): string;
+/**
+ * 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 declare function installLockExitHandlers(): void;
+/**
+ * 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 declare function withAuthLock<T>(body: () => Promise<T>, daemonId?: string): Promise<T>;
+/**
+ * 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 declare const UNKNOWN_401_BUDGET = 3;
+/** Test-only: clear all per-daemonId unknown-401 streak state. */
+export declare function __resetUnknown401StreaksForTest(): void;
+/**
+ * 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 declare const __refreshDiagnostics: {
+    proofAttemptCount: number;
+    requestAttemptCount: number;
+    reset(): void;
+};
+/**
+ * Refresh the daemon access+refresh token pair against the server.
+ *
+ * Single-flight per daemonId: if a refresh is already in flight for this
+ * daemon, the caller awaits the same promise. Without this N parallel HTTP
+ * calls would fire N refreshes, the second rotation would revoke the first,
+ * and the server's family-reuse detector would log everyone out.
+ *
+ * Does NOT itself persist the new pair — that's the caller's job, so the
+ * same lock can span "refresh + write to keychain" atomically.
+ */
+/**
+ * Optional callback invoked just before each refresh HTTP request to
+ * produce an L11 device-identity JWS proof. Daemon callers wire this
+ * to `signServerRequest({method, url, refreshToken})` from
+ * `daemon/src/deviceIdentity.ts`. Returning `null` / `undefined` (or
+ * throwing) leaves the request without a proof header — the daemon's
+ * device identity may legitimately not be initialized yet (Phase 1
+ * binary running against a Phase 1 server-side, etc.).
+ *
+ * The callback is invoked TWICE on the rotation path — once for the
+ * primary refresh attempt and once for the rotation-resilience retry —
+ * because each request gets its own fresh `iat` + `jti` to avoid the
+ * server's anti-replay cache.
+ */
+export type DeviceProofSigner = (params: {
+    method: string;
+    url: string;
+    refreshToken: string;
+}) => string | null | undefined;
+export declare function refreshDaemonToken(serverUrl: string, currentRefreshToken: string, daemonId: string, options?: {
+    machineUuid?: string;
+    origin?: string;
+    /**
+     * L11 Phase 3 — when supplied, every outgoing refresh request is
+     * accompanied by an `OverSky-DPoP` header carrying the JWS produced
+     * by this callback. A null return is treated as "no proof
+     * available" and silently skipped — the server-side middleware in
+     * `off` / `warn` mode will continue to accept the request.
+     */
+    signRequestProof?: DeviceProofSigner;
+}): Promise<TokenPair>;
+/**
+ * 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 declare function revokeDaemonRefreshSession(serverUrl: string, refreshToken: string): Promise<void>;
+export declare function persistReauthState(state: ReauthState): void;
+export declare function needsReauthState(): {
+    needed: boolean;
+    reason?: string;
+    since?: number;
+};
+export declare function clearReauthState(): void;
+/** Path getters exposed for tests + the daemon's connection.ts handler. */
+export { authLockPath as AUTH_LOCK_PATH_FN, reauthFlagPath as REAUTH_FLAG_PATH_FN };