@skrr-ai/auth-core 0.1.2

package/dist/cjs/types.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Shared types & error classes used across refresh, refreshScheduler, and
+ * fdToken modules. Lives in its own file so consumers can `import type` from
+ * the package without dragging in side-effecting modules.
+ */
+export interface TokenPair {
+    /**
+     * Legacy daemon/cli/web access JWT. Null after Stage-E #1 step 4
+     * for daemon-scope refresh responses: the JWT-daemon substrate has
+     * been retired and only `opaqueAccessToken` is shipped. Non-daemon
+     * scopes (cli, web) still receive a non-null JWT here.
+     */
+    accessToken: string | null;
+    /** Epoch ms. */
+    accessExpiresAt: number;
+    refreshToken: string;
+    /** Epoch ms. */
+    refreshExpiresAt: number;
+    /**
+     * Stage-E #1 — opaque `osk_dmn_*` daemon access token co-issued
+     * with the JWT for daemon-scope sessions. Optional during the
+     * dark-ship migration window:
+     *
+     *   - `undefined` / absent: server didn't co-issue (older API,
+     *     non-daemon scope, or `OVERSKY_DMN_OPAQUE_DISABLED=1` set).
+     *     Daemon authenticates with the JWT (legacy behavior).
+     *   - `null`: server co-issued but the value is explicitly null
+     *     (kill switch tripped mid-rotation, or write failed). Daemon
+     *     callers MUST treat this as "clear any cached opaque slot
+     *     so we don't keep using a stale opaque after its row was
+     *     family-revoked".
+     *   - `string`: opaque plaintext. Daemon stores in keychain and
+     *     prefers over JWT for the next handshake (gated by
+     *     `OVERSKY_PREFER_OPAQUE_DAEMON_TOKEN`, default on).
+     *
+     * Expires in lockstep with `accessExpiresAt` (server-side they're
+     * minted in the same transaction with identical TTL). The pair
+     * intentionally does NOT carry a separate `opaqueAccessExpiresAt`.
+     */
+    opaqueAccessToken?: string | null;
+    /**
+     * Production-hardening 2026-05-06 — soft backoff hint from the server
+     * indicating the fleet refresh-QPS is high and the daemon SHOULD
+     * defer its next proactive refresh by this many seconds (plus its
+     * own jitter). Distinct from a 429 Retry-After: this is advisory,
+     * the rotation already succeeded, and the daemon's correctness is
+     * not at risk if it ignores the hint. Honoring it lets a fleet
+     * stretch its refresh-cadence under load WITHOUT any rejected
+     * requests.
+     *
+     * Sourced from the response's `X-Refresh-Backoff` header (or
+     * `Retry-After` when present on a 200). Absent when the server
+     * isn't backpressuring or the header parser failed.
+     */
+    softBackoffSeconds?: number;
+}
+/**
+ * Server-emitted permanent-failure codes.
+ *
+ * Three groups, all permanent (no amount of retry helps):
+ *   - REFRESH_*       — refresh-token specific (most common path).
+ *   - TOKEN_*         — access-token specific (server pushes 4402 close;
+ *                       daemon classifies as TOKEN_INVALID/TOKEN_EXPIRED).
+ *   - SESSION_REVOKED — admin/forensic revoke; whole family burned.
+ *   - UNKNOWN_401     — server returned 401 with a code we don't
+ *                       recognize. Treated as permanent (better to prompt
+ *                       re-auth than to loop forever) but tagged
+ *                       distinctly so monitoring can surface server-side
+ *                       bugs separately from real expirations.
+ *
+ * Production-hardening 2026-05-06 — widened from the original 4-value
+ * union to include `TOKEN_INVALID`, `TOKEN_EXPIRED`, and `UNKNOWN_401`
+ * to match the codes the daemon and client UX actually emit/render.
+ * Without this, the client `describeAuthFailure` exhaustiveness check
+ * was silently broken for the non-REFRESH branches.
+ */
+export type PermanentAuthReason = 'REFRESH_INVALID' | 'REFRESH_REUSED' | 'REFRESH_EXPIRED' | 'SESSION_REVOKED' | 'TOKEN_INVALID' | 'TOKEN_EXPIRED' | 'UNKNOWN_401';
+export declare class PermanentAuthFailure extends Error {
+    readonly code: PermanentAuthReason;
+    constructor(code: PermanentAuthReason, message: string);
+}
+export declare class TransientAuthFailure extends Error {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+export interface ReauthState {
+    code: string;
+    message?: string;
+    /** Epoch ms. */
+    at: number;
+}

package/dist/cjs/types.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * Shared types & error classes used across refresh, refreshScheduler, and
+ * fdToken modules. Lives in its own file so consumers can `import type` from
+ * the package without dragging in side-effecting modules.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransientAuthFailure = exports.PermanentAuthFailure = void 0;
+class PermanentAuthFailure extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'PermanentAuthFailure';
+        this.code = code;
+    }
+}
+exports.PermanentAuthFailure = PermanentAuthFailure;
+class TransientAuthFailure extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = 'TransientAuthFailure';
+        this.cause = cause;
+    }
+}
+exports.TransientAuthFailure = TransientAuthFailure;

package/dist/esm/aead.d.ts

@@ -0,0 +1,24 @@
+/** Key length in bytes (256 bits). */
+export declare const AEAD_KEY_LEN = 32;
+/** Nonce length in bytes (96-bit GCM standard). */
+export declare const AEAD_NONCE_LEN = 12;
+/** GCM authentication tag length in bytes (128 bits). */
+export declare const AEAD_TAG_LEN = 16;
+/** Result of an AEAD seal operation. */
+export interface AeadSealed {
+    readonly nonce: Buffer;
+    readonly ct: Buffer;
+    readonly tag: Buffer;
+}
+/**
+ * Seal `plaintext` under `key` with optional `aad`. A fresh 96-bit nonce is
+ * generated per call — callers must never reuse nonces for the same key.
+ *
+ * Throws if `key` is not exactly 32 bytes.
+ */
+export declare function aeadSeal(plaintext: Buffer, key: Buffer, aad?: Buffer): AeadSealed;
+/**
+ * Open a sealed AEAD blob. Throws on any authentication failure (wrong key,
+ * wrong AAD, truncated ciphertext). Never silently returns garbage.
+ */
+export declare function aeadOpen(sealed: AeadSealed, key: Buffer, aad?: Buffer): Buffer;

package/dist/esm/aead.js

@@ -0,0 +1,57 @@
+/**
+ * aead.ts — shared AES-256-GCM primitive for auth-core envelope formats.
+ *
+ * CredentialEnvelope (L12 at-rest) uses AES-256-GCM. This module owns the
+ * bare cipher operation; framing, versioning, and serialization live in its
+ * envelope module.
+ */
+import crypto from 'node:crypto';
+/** AEAD algorithm. */
+const ALG = 'aes-256-gcm';
+/** Key length in bytes (256 bits). */
+export const AEAD_KEY_LEN = 32;
+/** Nonce length in bytes (96-bit GCM standard). */
+export const AEAD_NONCE_LEN = 12;
+/** GCM authentication tag length in bytes (128 bits). */
+export const AEAD_TAG_LEN = 16;
+/**
+ * Seal `plaintext` under `key` with optional `aad`. A fresh 96-bit nonce is
+ * generated per call — callers must never reuse nonces for the same key.
+ *
+ * Throws if `key` is not exactly 32 bytes.
+ */
+export function aeadSeal(plaintext, key, aad) {
+    if (!Buffer.isBuffer(key) || key.length !== AEAD_KEY_LEN) {
+        throw new TypeError(`aeadSeal: key must be a ${AEAD_KEY_LEN}-byte Buffer`);
+    }
+    const nonce = crypto.randomBytes(AEAD_NONCE_LEN);
+    const cipher = crypto.createCipheriv(ALG, key, nonce);
+    if (aad && aad.length > 0)
+        cipher.setAAD(aad);
+    const ct = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return { nonce, ct, tag };
+}
+/**
+ * Open a sealed AEAD blob. Throws on any authentication failure (wrong key,
+ * wrong AAD, truncated ciphertext). Never silently returns garbage.
+ */
+export function aeadOpen(sealed, key, aad) {
+    if (!Buffer.isBuffer(key) || key.length !== AEAD_KEY_LEN) {
+        throw new TypeError(`aeadOpen: key must be a ${AEAD_KEY_LEN}-byte Buffer`);
+    }
+    if (!Buffer.isBuffer(sealed.nonce) || sealed.nonce.length !== AEAD_NONCE_LEN) {
+        throw new Error('aeadOpen: invalid nonce length');
+    }
+    if (!Buffer.isBuffer(sealed.tag) || sealed.tag.length !== AEAD_TAG_LEN) {
+        throw new Error('aeadOpen: invalid auth tag length');
+    }
+    if (!Buffer.isBuffer(sealed.ct)) {
+        throw new Error('aeadOpen: ciphertext must be a Buffer');
+    }
+    const decipher = crypto.createDecipheriv(ALG, key, sealed.nonce);
+    if (aad && aad.length > 0)
+        decipher.setAAD(aad);
+    decipher.setAuthTag(sealed.tag);
+    return Buffer.concat([decipher.update(sealed.ct), decipher.final()]);
+}

package/dist/esm/authExpiredDetector.d.ts

@@ -0,0 +1,65 @@
+/**
+ * authExpiredDetector.ts — mid-stream auth-expired SSE detector.
+ *
+ * HTTP auth is checked BEFORE the body stream starts — a 401 mid-stream
+ * is technically impossible. But long-running SSE / Socket.IO sessions
+ * (chat with tool calls, agent steps, voice) can see the access token
+ * expire mid-body, because the server-side auth check fires per-event
+ * on every internal step. The server's contract: emit a terminal event
+ * with `type: 'error'` + `error.code === 'auth_expired'` (or the legacy
+ * forms `event: 'auth:expired'`, `event: 'auth_expired'`, `code:
+ * 'auth_expired'`) signalling the client to refresh and restart.
+ *
+ * This module recognises every documented shape and exposes a small
+ * orchestration helper that runs the caller-supplied refresher, then
+ * fires a user-visible message via the callbacks bag.
+ *
+ * Pure — no React, no fetch, no platform code. Suitable for daemon,
+ * desktop, web, and mobile clients. The mobile React Native client
+ * keeps a byte-equal mirror at
+ * `mobile/react-native/src/chat/streaming/authExpiredDetector.ts`
+ * (separate repo, can't import this package today). Treat that file
+ * as auth-tier canonical: any change here MUST be ported there.
+ */
+/** Minimal shape of a parsed SSE event this module recognises. */
+export interface ParsedSseLike {
+    type?: unknown;
+    event?: unknown;
+    error?: unknown;
+    code?: unknown;
+}
+/**
+ * Return true when `parsed` looks like the server's mid-stream auth
+ * expiry signal. The check is broad on purpose — multiple server
+ * generations use slightly different shapes and we want to catch them
+ * all rather than drop into the generic-error branch and confuse the
+ * user.
+ *
+ * Accepted shapes (any one is enough):
+ *   - `{ type: 'error', error: { code: 'auth_expired' } }`
+ *   - `{ event: 'auth:expired' }`
+ *   - `{ event: 'auth_expired' }`
+ *   - `{ code: 'auth_expired' }`
+ *   - `{ type: 'error', error: 'auth_expired' }`
+ */
+export declare function isAuthExpiredSseEvent(parsed: unknown): boolean;
+/**
+ * Integration helper — call from the SSE parser when `isAuthExpiredSseEvent`
+ * returns true. Calls the supplied refresher, fires callbacks.onError
+ * with a user-visible message, and returns the new token (or null on
+ * failure) so the caller can decide whether to auto-retry.
+ *
+ * Pure in the sense that it does NOT drive a fetch / socket itself —
+ * that is the caller's responsibility, because retry semantics differ
+ * between SSE (re-POST) and Socket.IO (disconnect+reconnect).
+ */
+export interface AuthExpiredCallbacks {
+    onError?: (message: string) => void;
+}
+export interface HandleMidStreamAuthExpiryResult {
+    /** True when the refresher returned a fresh token. */
+    refreshed: boolean;
+    /** The fresh token when refreshed===true, else null. */
+    token: string | null;
+}
+export declare function handleMidStreamAuthExpiry(callbacks: AuthExpiredCallbacks, refresher: () => Promise<string | null>): Promise<HandleMidStreamAuthExpiryResult>;

package/dist/esm/authExpiredDetector.js

@@ -0,0 +1,85 @@
+/**
+ * authExpiredDetector.ts — mid-stream auth-expired SSE detector.
+ *
+ * HTTP auth is checked BEFORE the body stream starts — a 401 mid-stream
+ * is technically impossible. But long-running SSE / Socket.IO sessions
+ * (chat with tool calls, agent steps, voice) can see the access token
+ * expire mid-body, because the server-side auth check fires per-event
+ * on every internal step. The server's contract: emit a terminal event
+ * with `type: 'error'` + `error.code === 'auth_expired'` (or the legacy
+ * forms `event: 'auth:expired'`, `event: 'auth_expired'`, `code:
+ * 'auth_expired'`) signalling the client to refresh and restart.
+ *
+ * This module recognises every documented shape and exposes a small
+ * orchestration helper that runs the caller-supplied refresher, then
+ * fires a user-visible message via the callbacks bag.
+ *
+ * Pure — no React, no fetch, no platform code. Suitable for daemon,
+ * desktop, web, and mobile clients. The mobile React Native client
+ * keeps a byte-equal mirror at
+ * `mobile/react-native/src/chat/streaming/authExpiredDetector.ts`
+ * (separate repo, can't import this package today). Treat that file
+ * as auth-tier canonical: any change here MUST be ported there.
+ */
+/**
+ * Return true when `parsed` looks like the server's mid-stream auth
+ * expiry signal. The check is broad on purpose — multiple server
+ * generations use slightly different shapes and we want to catch them
+ * all rather than drop into the generic-error branch and confuse the
+ * user.
+ *
+ * Accepted shapes (any one is enough):
+ *   - `{ type: 'error', error: { code: 'auth_expired' } }`
+ *   - `{ event: 'auth:expired' }`
+ *   - `{ event: 'auth_expired' }`
+ *   - `{ code: 'auth_expired' }`
+ *   - `{ type: 'error', error: 'auth_expired' }`
+ */
+export function isAuthExpiredSseEvent(parsed) {
+    if (!parsed || typeof parsed !== 'object')
+        return false;
+    const p = parsed;
+    const eventStr = typeof p.event === 'string' ? p.event.toLowerCase() : '';
+    if (eventStr === 'auth:expired' || eventStr === 'auth_expired')
+        return true;
+    const codeStr = typeof p.code === 'string' ? p.code.toLowerCase() : '';
+    if (codeStr === 'auth_expired')
+        return true;
+    const typeStr = typeof p.type === 'string' ? p.type.toLowerCase() : '';
+    if (typeStr === 'error' && isAuthExpiredError(p.error)) {
+        return true;
+    }
+    return false;
+}
+function isAuthExpiredError(err) {
+    if (!err)
+        return false;
+    if (typeof err === 'string')
+        return err.toLowerCase() === 'auth_expired';
+    if (typeof err !== 'object')
+        return false;
+    const maybe = err.code;
+    if (typeof maybe === 'string' && maybe.toLowerCase() === 'auth_expired') {
+        return true;
+    }
+    const message = err.message;
+    if (typeof message === 'string' && message.toLowerCase().includes('auth_expired')) {
+        return true;
+    }
+    return false;
+}
+export async function handleMidStreamAuthExpiry(callbacks, refresher) {
+    let token = null;
+    try {
+        token = await refresher();
+    }
+    catch {
+        token = null;
+    }
+    if (token) {
+        callbacks.onError?.('Your session was refreshed. Tap retry to resume the response.');
+        return { refreshed: true, token };
+    }
+    callbacks.onError?.('Session expired. Please sign in again.');
+    return { refreshed: false, token: null };
+}

package/dist/esm/authHelper.d.ts

@@ -0,0 +1,51 @@
+export interface HelperResult {
+    token: string;
+    /** ms-epoch absolute time. When omitted, callers default to TTL window. */
+    expiresAt?: number;
+}
+/**
+ * L6.3 — diagnostic taxonomy for the cold-cache failure sentinel.
+ *
+ *   - 'disabled'      — kill switch / config ruled out the helper before
+ *                       any I/O. Resolver: fall through (no sentinel).
+ *   - 'invalid-path'  — relative path, not-a-file, non-existent. The
+ *                       helper isn't really "configured" so the resolver
+ *                       falls through to the next slot.
+ *   - 'not-executable'— exec-bit unset. Same fall-through semantics.
+ *   - 'spawn-error'   — Node failed to spawn (ENOMEM, EACCES at exec
+ *                       time, etc.). Counts as "helper attempted and
+ *                       failed" → sentinel.
+ *   - 'timeout'       — helper exceeded `OVERSKY_AUTH_HELPER_TIMEOUT_MS`
+ *                       and we SIGKILL'd it → sentinel.
+ *   - 'non-zero-exit' — script exited with non-zero code → sentinel.
+ *   - 'oversized'     — stdout exceeded 64 KiB cap → sentinel.
+ *   - 'empty-output'  — script exited 0 with no stdout → sentinel.
+ *   - 'parse-error'   — JSON-shaped stdout but malformed, OR bare-token
+ *                       output had embedded whitespace → sentinel.
+ */
+export type AuthHelperFailureReason = 'disabled' | 'invalid-path' | 'not-executable' | 'spawn-error' | 'timeout' | 'non-zero-exit' | 'oversized' | 'empty-output' | 'parse-error';
+/**
+ * L6.3 — failure outcomes that should TRIGGER the cold-cache sentinel.
+ * Validation failures (`disabled`, `invalid-path`, `not-executable`) are
+ * deliberately excluded: those mean "helper isn't really wired up" and
+ * the resolver chain should fall through to the next slot, not fail
+ * closed.
+ *
+ * Exported as a `const` set so the resolver can do
+ * `SENTINEL_TRIGGERING_FAILURES.has(reason)` without re-encoding the
+ * policy in two places.
+ */
+export declare const SENTINEL_TRIGGERING_FAILURES: ReadonlySet<AuthHelperFailureReason>;
+export interface InvokeAuthHelperOptions {
+    /** Override the timeout (defaults to env or 10 s). */
+    timeoutMs?: number;
+}
+export declare function getLastAuthHelperFailureReason(): AuthHelperFailureReason | null;
+/** @internal test-only — clear the failure-reason latch between cases. */
+export declare function __resetAuthHelperFailureReasonForTest(): void;
+/**
+ * Invoke the helper script and return its parsed token, or null on any
+ * failure. Never throws.
+ */
+export declare function invokeAuthHelper(scriptPath: string, options?: InvokeAuthHelperOptions): Promise<HelperResult | null>;
+export declare function getDefaultHelperTtlMs(): number;