@skrr-ai/auth-core 0.1.2

package/README.md

@@ -0,0 +1,21 @@
+# @skrr-ai/auth-core
+
+Shared authentication substrate for OverSky packages.
+
+This package contains the token store, refresh helpers, localhost login
+callback, device-key helpers, TTL parsing, credential envelope helpers, and auth
+failure classification used by the OverSky daemon and Sky CLI.
+
+## Install
+
+```bash
+npm install @skrr-ai/auth-core
+```
+
+## Usage
+
+```ts
+import { parseTtlDays } from '@skrr-ai/auth-core';
+```
+
+The npm package ships compiled JavaScript and TypeScript declarations only.

package/dist/cjs/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/cjs/aead.js

@@ -0,0 +1,65 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AEAD_TAG_LEN = exports.AEAD_NONCE_LEN = exports.AEAD_KEY_LEN = void 0;
+exports.aeadSeal = aeadSeal;
+exports.aeadOpen = aeadOpen;
+/**
+ * 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.
+ */
+const node_crypto_1 = __importDefault(require("node:crypto"));
+/** AEAD algorithm. */
+const ALG = 'aes-256-gcm';
+/** Key length in bytes (256 bits). */
+exports.AEAD_KEY_LEN = 32;
+/** Nonce length in bytes (96-bit GCM standard). */
+exports.AEAD_NONCE_LEN = 12;
+/** GCM authentication tag length in bytes (128 bits). */
+exports.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.
+ */
+function aeadSeal(plaintext, key, aad) {
+    if (!Buffer.isBuffer(key) || key.length !== exports.AEAD_KEY_LEN) {
+        throw new TypeError(`aeadSeal: key must be a ${exports.AEAD_KEY_LEN}-byte Buffer`);
+    }
+    const nonce = node_crypto_1.default.randomBytes(exports.AEAD_NONCE_LEN);
+    const cipher = node_crypto_1.default.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.
+ */
+function aeadOpen(sealed, key, aad) {
+    if (!Buffer.isBuffer(key) || key.length !== exports.AEAD_KEY_LEN) {
+        throw new TypeError(`aeadOpen: key must be a ${exports.AEAD_KEY_LEN}-byte Buffer`);
+    }
+    if (!Buffer.isBuffer(sealed.nonce) || sealed.nonce.length !== exports.AEAD_NONCE_LEN) {
+        throw new Error('aeadOpen: invalid nonce length');
+    }
+    if (!Buffer.isBuffer(sealed.tag) || sealed.tag.length !== exports.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 = node_crypto_1.default.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/cjs/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/cjs/authExpiredDetector.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAuthExpiredSseEvent = isAuthExpiredSseEvent;
+exports.handleMidStreamAuthExpiry = handleMidStreamAuthExpiry;
+/**
+ * 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' }`
+ */
+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;
+}
+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/cjs/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;

package/dist/cjs/authHelper.js

@@ -0,0 +1,321 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SENTINEL_TRIGGERING_FAILURES = void 0;
+exports.getLastAuthHelperFailureReason = getLastAuthHelperFailureReason;
+exports.__resetAuthHelperFailureReasonForTest = __resetAuthHelperFailureReasonForTest;
+exports.invokeAuthHelper = invokeAuthHelper;
+exports.getDefaultHelperTtlMs = getDefaultHelperTtlMs;
+/**
+ * authHelper.ts — invocation contract for `OVERSKY_AUTH_HELPER`.
+ *
+ * The helper is a user-supplied executable that prints a fresh token to
+ * stdout. It exists so operators with rotating credentials (Vault, AWS
+ * Secrets Manager, internal SSO proxy) can plug in without OverSky needing
+ * to know how their secret store works. The contract mirrors Claude Code's
+ * `apiKeyHelper`.
+ *
+ * Wire protocol:
+ *   - `OVERSKY_AUTH_HELPER` env points at an absolute, executable path.
+ *   - We `spawn(path, [], { shell: false })` — never via shell, so no
+ *     argument injection regardless of what's in the env value.
+ *   - The helper writes EITHER a bare JWT to stdout, OR a JSON object
+ *     `{ "token": "...", "expiresAt"?: <ms epoch> }`.
+ *   - Stderr is captured for diagnostic logging only — never returned as
+ *     token material.
+ *   - Stdout cap: 64 KiB (`MAX_OUTPUT_BYTES`). Real JWTs are < 4 KiB.
+ *   - Default timeout: 10 s (`OVERSKY_AUTH_HELPER_TIMEOUT_MS` overrides).
+ *
+ * Safety invariants:
+ *   - Relative paths rejected — explicit absolute path required.
+ *   - Non-executable file rejected (any of u/g/o exec bits must be set).
+ *   - Non-zero exit, timeout, oversized output, malformed JSON → null.
+ *   - On any failure the resolver chain falls through to the next slot;
+ *     we never throw from a helper failure.
+ *   - L6.3 (cold-cache failure sentinel) lives one layer up in
+ *     `credentialResolver.ts` — when the SPAWN ATTEMPT itself fails on a
+ *     cold cache the resolver caches a typed `{kind:'failed'}` sentinel
+ *     to prevent silent fall-through to OAuth.
+ *
+ * Kill switch: `OVERSKY_DISABLE_AUTH_HELPER=1` short-circuits to null.
+ */
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const runtime_js_1 = require("./runtime.js");
+const MAX_OUTPUT_BYTES = 64 * 1024;
+const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_TTL_MS = 5 * 60_000;
+/**
+ * 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.
+ */
+exports.SENTINEL_TRIGGERING_FAILURES = new Set([
+    'spawn-error',
+    'timeout',
+    'non-zero-exit',
+    'oversized',
+    'empty-output',
+    'parse-error',
+]);
+/**
+ * Diagnostic outcome of the LAST `invokeAuthHelper()` call. The resolver
+ * reads this immediately after the call to decide whether to cache a
+ * cold-cache failure sentinel.
+ *
+ * Module-level (not part of the function return) because changing
+ * `invokeAuthHelper`'s return type would ripple through every existing
+ * caller and test. Reading it BEFORE another invocation is racy in
+ * theory but safe in practice — the resolver awaits the same promise it
+ * read this from.
+ */
+let _lastFailureReason = null;
+function getLastAuthHelperFailureReason() {
+    return _lastFailureReason;
+}
+/** @internal test-only — clear the failure-reason latch between cases. */
+function __resetAuthHelperFailureReasonForTest() {
+    _lastFailureReason = null;
+}
+/**
+ * Invoke the helper script and return its parsed token, or null on any
+ * failure. Never throws.
+ */
+async function invokeAuthHelper(scriptPath, options = {}) {
+    const log = (0, runtime_js_1.getAuthLogger)();
+    // Reset on entry so a successful call clears any prior failure latch.
+    _lastFailureReason = null;
+    if (process.env.OVERSKY_DISABLE_AUTH_HELPER === '1') {
+        log.debug?.('[authHelper] OVERSKY_DISABLE_AUTH_HELPER=1 — skipping helper');
+        _lastFailureReason = 'disabled';
+        return null;
+    }
+    if (!scriptPath || !node_path_1.default.isAbsolute(scriptPath)) {
+        log.error(`[authHelper] OVERSKY_AUTH_HELPER must be an absolute path; got "${scriptPath}"`);
+        _lastFailureReason = 'invalid-path';
+        return null;
+    }
+    let stat;
+    try {
+        stat = node_fs_1.default.statSync(scriptPath);
+    }
+    catch (err) {
+        log.error(`[authHelper] OVERSKY_AUTH_HELPER not found at "${scriptPath}": ${formatErr(err)}`);
+        _lastFailureReason = 'invalid-path';
+        return null;
+    }
+    if (!stat.isFile()) {
+        log.error(`[authHelper] OVERSKY_AUTH_HELPER "${scriptPath}" is not a regular file`);
+        _lastFailureReason = 'invalid-path';
+        return null;
+    }
+    if ((stat.mode & 0o111) === 0) {
+        log.error(`[authHelper] OVERSKY_AUTH_HELPER "${scriptPath}" is not executable`);
+        _lastFailureReason = 'not-executable';
+        return null;
+    }
+    const timeoutMs = options.timeoutMs ?? parseTimeoutMs();
+    return new Promise((resolve) => {
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        let truncated = false;
+        let killedForTimeout = false;
+        let resolved = false;
+        const settle = (result) => {
+            if (resolved)
+                return;
+            resolved = true;
+            clearTimeout(timer);
+            resolve(result);
+        };
+        let child;
+        try {
+            child = (0, node_child_process_1.spawn)(scriptPath, [], {
+                shell: false,
+                // detached: true makes the child its own process-group leader so
+                // we can SIGKILL the whole group on timeout. Without this, killing
+                // the script's shell leaves grandchildren (sleep, curl, vault) as
+                // orphans holding stdio open — `close` would never fire and the
+                // daemon would hang past the timeout window.
+                detached: true,
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+        }
+        catch (err) {
+            log.error(`[authHelper] spawn failed: ${formatErr(err)}`);
+            _lastFailureReason = 'spawn-error';
+            settle(null);
+            return;
+        }
+        const timer = setTimeout(() => {
+            killedForTimeout = true;
+            log.warn(`[authHelper] helper timed out after ${timeoutMs}ms — killing`);
+            // Kill the entire process group so subprocess trees (a helper that
+            // shells out to vault/aws/curl) don't outlive the timeout. The
+            // negative pid form targets the process group; falls back to a
+            // single-process kill on platforms or shapes where that fails.
+            try {
+                if (typeof child.pid === 'number') {
+                    process.kill(-child.pid, 'SIGKILL');
+                }
+                else {
+                    child.kill('SIGKILL');
+                }
+            }
+            catch {
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            // Tear down stdio so any lingering pipe holders don't keep us hung.
+            try {
+                child.stdout?.destroy();
+            }
+            catch {
+                /* ignore */
+            }
+            try {
+                child.stderr?.destroy();
+            }
+            catch {
+                /* ignore */
+            }
+            _lastFailureReason = 'timeout';
+            // Settle immediately — do not wait for `close`. Orphan grandchildren
+            // may keep the close event pending indefinitely; the resolver chain
+            // must move on within the configured timeout.
+            settle(null);
+        }, timeoutMs);
+        if (typeof timer.unref === 'function')
+            timer.unref();
+        child.stdout.on('data', (chunk) => {
+            stdoutBytes += chunk.length;
+            if (stdoutBytes > MAX_OUTPUT_BYTES) {
+                truncated = true;
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch {
+                    /* ignore */
+                }
+                return;
+            }
+            stdoutChunks.push(chunk);
+        });
+        child.stderr.on('data', (chunk) => {
+            // Defensive cap on stderr too (a chatty helper shouldn't OOM the daemon).
+            if (stderrBytes < MAX_OUTPUT_BYTES) {
+                stderrChunks.push(chunk);
+                stderrBytes += chunk.length;
+            }
+        });
+        child.on('error', (err) => {
+            log.error(`[authHelper] runtime error: ${formatErr(err)}`);
+            _lastFailureReason = 'spawn-error';
+            settle(null);
+        });
+        child.on('close', (code) => {
+            if (truncated) {
+                log.error(`[authHelper] stdout exceeded ${MAX_OUTPUT_BYTES} bytes — refusing to parse`);
+                _lastFailureReason = 'oversized';
+                settle(null);
+                return;
+            }
+            if (killedForTimeout) {
+                // _lastFailureReason already set to 'timeout' in the timer.
+                settle(null);
+                return;
+            }
+            const stderr = Buffer.concat(stderrChunks).toString('utf-8').trim();
+            if (stderr)
+                log.debug?.(`[authHelper] stderr: ${stderr}`);
+            if (code !== 0) {
+                log.error(`[authHelper] helper exited with code ${code}`);
+                _lastFailureReason = 'non-zero-exit';
+                settle(null);
+                return;
+            }
+            const stdout = Buffer.concat(stdoutChunks).toString('utf-8').trim();
+            if (!stdout) {
+                log.error('[authHelper] helper produced empty stdout');
+                _lastFailureReason = 'empty-output';
+                settle(null);
+                return;
+            }
+            const parsed = parseHelperOutput(stdout, log);
+            if (parsed === null) {
+                _lastFailureReason = 'parse-error';
+            }
+            settle(parsed);
+        });
+    });
+}
+function parseHelperOutput(stdout, log) {
+    // JSON path first; fall back to bare-string token.
+    const trimmed = stdout.trim();
+    const looksLikeJson = trimmed.startsWith('{') || trimmed.startsWith('"');
+    if (looksLikeJson) {
+        try {
+            const obj = JSON.parse(trimmed);
+            if (typeof obj === 'string') {
+                return obj.length > 0 ? { token: obj } : null;
+            }
+            if (obj && typeof obj === 'object') {
+                const rec = obj;
+                const token = typeof rec.token === 'string' ? rec.token : null;
+                if (!token || token.length === 0) {
+                    log.error('[authHelper] JSON output missing "token" field');
+                    return null;
+                }
+                const expiresAt = typeof rec.expiresAt === 'number' && Number.isFinite(rec.expiresAt)
+                    ? rec.expiresAt
+                    : undefined;
+                return expiresAt !== undefined ? { token, expiresAt } : { token };
+            }
+            log.error('[authHelper] JSON output was not an object or string');
+            return null;
+        }
+        catch (err) {
+            log.error(`[authHelper] JSON parse failed: ${formatErr(err)}`);
+            return null;
+        }
+    }
+    // Bare token — single line, no JSON. Reject if it contains whitespace
+    // beyond surrounding trim (defensive — helper might have leaked logs).
+    if (/\s/.test(trimmed)) {
+        log.error('[authHelper] bare-token output contains whitespace — refusing (use JSON if helper logs to stdout)');
+        return null;
+    }
+    return { token: trimmed };
+}
+function parseTimeoutMs() {
+    const raw = process.env.OVERSKY_AUTH_HELPER_TIMEOUT_MS;
+    if (!raw)
+        return DEFAULT_TIMEOUT_MS;
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_TIMEOUT_MS;
+}
+function getDefaultHelperTtlMs() {
+    const raw = process.env.OVERSKY_AUTH_HELPER_TTL_MS;
+    if (!raw)
+        return DEFAULT_TTL_MS;
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_TTL_MS;
+}
+function formatErr(err) {
+    return err instanceof Error ? err.message : String(err);
+}