@skrr-ai/auth-core 0.1.2

package/dist/esm/fdToken.js

@@ -0,0 +1,231 @@
+/**
+ * fdToken.ts — one-shot credential handoff over an inherited pipe fd.
+ *
+ * When Electron's `DaemonSupervisor` (or any parent process) spawns a
+ * foreground daemon, it can stream the access (and optionally refresh)
+ * token over an inherited pipe fd instead of writing the token to disk and
+ * waiting for the daemon to find it. This eliminates:
+ *   - The Keychain-propagation race on macOS (write → security DB index
+ *     update → daemon read) that bites cold-start foreground spawns.
+ *   - The `auth.json` filesystem mtime-watch race on non-darwin platforms.
+ *
+ * Wire protocol — parent writes a single JSON object (newline tolerated
+ * but not required) and closes the write side so the child sees EOF:
+ *
+ *     { "accessToken": "...",
+ *       "accessExpiresAt"?: 1234567890000,
+ *       "refreshToken"?:   "...",
+ *       "refreshExpiresAt"?: 1234567890000 }
+ *
+ * The child reads once, parses, and closes the fd — regardless of outcome.
+ *
+ * LaunchAgent-spawned daemons (different process tree from Electron) do NOT
+ * get this handoff because launchd/systemd/schtasks don't propagate pipe
+ * fds across the boundary. Those keep using the keychain / file backend.
+ *
+ * Safety invariants:
+ *   - `OVERSKY_AUTH_FD` absent → null (caller falls back).
+ *   - fd not parseable / not readable → null.
+ *   - Read exceeds 64 KB → bail (real payloads ~1 KB; defensive cap).
+ *   - Read times out after 2 s (parent crashed mid-handoff) → null.
+ *   - Malformed JSON or missing accessToken → null.
+ *   - Always close the fd after the read, regardless of outcome.
+ *   - After the first successful consume we SCRUB the env var so a later
+ *     getToken() that misses any cache doesn't try to re-read a fd that
+ *     has already been closed.
+ */
+import fs from 'node:fs';
+import { getAuthKillSwitches } from './runtime.js';
+const MAX_PAYLOAD_BYTES = 64 * 1024;
+const READ_TIMEOUT_MS = 2_000;
+const FD_ENV_VAR = 'OVERSKY_AUTH_FD';
+/**
+ * Test seam — lets unit tests stub the actual fd read without opening a
+ * real pipe. Default: null → real bounded-async `createReadStream(fd)` path.
+ */
+let _fdReader = null;
+/** @internal test-only — replace the fd reader. Pass null to restore. */
+export function __setFdReaderForTest(fn) {
+    _fdReader = fn;
+}
+function parseFd(envValue) {
+    if (!envValue)
+        return null;
+    const fd = Number.parseInt(envValue, 10);
+    if (!Number.isFinite(fd) || fd < 0)
+        return null;
+    return fd;
+}
+/**
+ * Bounded async read of the pipe fd with a 2 s deadline and a 64 KB cap.
+ *
+ * Uses `fs.createReadStream(fd)` with an `AbortController` so a hung parent
+ * writer (never closes its write side, never signals EOF) cannot stall the
+ * daemon. On timeout we abort the stream and return null. The fd is closed
+ * exactly once — either by the stream itself on 'close', or explicitly by
+ * `closeSync` on the error/timeout paths.
+ */
+function readFdBounded(fd) {
+    return new Promise((resolve) => {
+        const controller = new AbortController();
+        let settled = false;
+        let bytes = 0;
+        const chunks = [];
+        let streamClosedFd = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (!streamClosedFd) {
+                try {
+                    fs.closeSync(fd);
+                }
+                catch {
+                    /* fd may already be closed by the stream — ignore */
+                }
+            }
+            resolve(result);
+        };
+        const timer = setTimeout(() => {
+            try {
+                controller.abort();
+            }
+            catch {
+                /* ignore */
+            }
+            console.warn(`[auth/fdToken] read fd ${fd} timed out after ${READ_TIMEOUT_MS} ms — parent writer may have crashed`);
+            finish(null);
+        }, READ_TIMEOUT_MS);
+        if (typeof timer.unref === 'function')
+            timer.unref();
+        let stream;
+        try {
+            stream = fs.createReadStream('', {
+                fd,
+                autoClose: true,
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            console.warn(`[auth/fdToken] failed to open read stream on fd ${fd}: ${err instanceof Error ? err.message : String(err)}`);
+            finish(null);
+            return;
+        }
+        stream.on('data', (chunk) => {
+            const buf = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk;
+            bytes += buf.length;
+            if (bytes > MAX_PAYLOAD_BYTES) {
+                try {
+                    controller.abort();
+                }
+                catch {
+                    /* ignore */
+                }
+                console.warn(`[auth/fdToken] payload size exceeds ${MAX_PAYLOAD_BYTES} — discarding`);
+                finish(null);
+                return;
+            }
+            chunks.push(buf);
+        });
+        stream.on('error', (err) => {
+            if (err && (err.name === 'AbortError' || err.code === 'ABORT_ERR')) {
+                finish(null);
+                return;
+            }
+            console.warn(`[auth/fdToken] failed to read fd ${fd}: ${err instanceof Error ? err.message : String(err)}`);
+            finish(null);
+        });
+        stream.on('close', () => {
+            streamClosedFd = true;
+            if (settled)
+                return;
+            if (bytes === 0) {
+                finish(null);
+                return;
+            }
+            const raw = Buffer.concat(chunks, bytes).toString('utf8');
+            finish(raw);
+        });
+    });
+}
+/**
+ * Attempt a one-shot read of the handoff fd. Returns the parsed payload on
+ * success, or null on any failure (missing env var, bad fd, bad JSON, etc.).
+ *
+ * Side effect: on the first successful read the env var is scrubbed so a
+ * later caller that misses every in-process cache doesn't retry the now-
+ * closed fd.
+ */
+export async function readAuthFromFd() {
+    // Kill switch: ignore the fd handoff entirely and fall back to the
+    // keychain / file backend (pre-Phase-4 path).
+    if (getAuthKillSwitches().fdTokenHandoff)
+        return null;
+    const fd = parseFd(process.env[FD_ENV_VAR]);
+    if (fd === null)
+        return null;
+    let raw = null;
+    try {
+        if (_fdReader) {
+            const ret = _fdReader(fd);
+            raw =
+                typeof ret?.then === 'function'
+                    ? await ret
+                    : ret;
+        }
+        else {
+            raw = await readFdBounded(fd);
+        }
+    }
+    catch (err) {
+        console.warn(`[auth/fdToken] failed to read fd ${fd}: ${err instanceof Error ? err.message : String(err)}`);
+        raw = null;
+        if (_fdReader) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    if (raw === null)
+        return null;
+    if (raw.length > MAX_PAYLOAD_BYTES) {
+        console.warn(`[auth/fdToken] payload size ${raw.length} exceeds ${MAX_PAYLOAD_BYTES} — discarding`);
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw.trim());
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const obj = parsed;
+    if (typeof obj.accessToken !== 'string' || obj.accessToken.length === 0) {
+        return null;
+    }
+    const out = { accessToken: obj.accessToken };
+    if (typeof obj.accessExpiresAt === 'number' && Number.isFinite(obj.accessExpiresAt)) {
+        out.accessExpiresAt = obj.accessExpiresAt;
+    }
+    if (typeof obj.refreshToken === 'string' && obj.refreshToken.length > 0) {
+        out.refreshToken = obj.refreshToken;
+    }
+    if (typeof obj.refreshExpiresAt === 'number' && Number.isFinite(obj.refreshExpiresAt)) {
+        out.refreshExpiresAt = obj.refreshExpiresAt;
+    }
+    // Scrub the env var so a later getToken() that misses caches doesn't try
+    // to re-read the now-closed fd.
+    try {
+        delete process.env[FD_ENV_VAR];
+    }
+    catch {
+        // Some hardened runtimes make process.env partially immutable. Best-effort.
+    }
+    return out;
+}

package/dist/esm/harnessTrust.d.ts

@@ -0,0 +1,72 @@
+/**
+ * OSK-3897 — harness trust TIERS, shared by the daemon and the CLI.
+ *
+ * ── Why this lives in auth-core ────────────────────────────────────────────
+ *
+ * `sky code doctor` must tell a user what tier their harness is and what that
+ * means for credentials and permission prompts. The daemon is the authority for
+ * that answer, but the CLI cannot import `daemon/src` — separate packages, and
+ * the daemon already depends on the CLI, so the reverse edge would be a cycle.
+ *
+ * `auth-core` is the one package BOTH already resolve: it is a daemon dependency
+ * and it is copied verbatim into the published CLI by
+ * `cli/scripts/vendor-monorepo-deps.js`, which keeps its `exports` map intact and
+ * preserves a single physical instance. So sharing through here changes nothing
+ * in the build or the release pipeline.
+ *
+ * Before this, the CLI carried a MIRROR of the table with a static test that
+ * parsed the daemon's source to catch drift. That guard worked — and it was still
+ * only a guard. The regression it existed to catch had already shipped once: the
+ * doctor described Tier 2 behaviour for a day after the owner decision of
+ * 2026-08-11 moved `sky-code` to Tier 1, and a unit test asserting the stale
+ * string made the wrong claim look load-bearing.
+ *
+ * ── What deliberately did NOT move ────────────────────────────────────────
+ *
+ * The PROVENANCE half stays in the daemon: `OVERSKY_DISTRIBUTED_HARNESSES`,
+ * `PROVENANCE_ELEVATABLE_TIERS`, `ProvenanceEvidence`, `effectiveHarnessTier`,
+ * `credentialTierForSpawn`, and the signature verification behind them.
+ *
+ * That split is the point. A tier is a PUBLISHED FACT — safe for any surface to
+ * read and state. Provenance is EVIDENCE ABOUT BYTES ON DISK, which only the
+ * process that spawns the binary can gather. Moving it here would let the CLI
+ * appear to speak about binary identity it has no way to verify, which is a worse
+ * failure than the drift this file fixes: a confident wrong answer beats an
+ * honestly stale one for causing harm.
+ */
+/** A harness's trust tier. 3 is the safe default for anything unrecognised. */
+export type HarnessTrustTier = 1 | 2 | 3;
+/**
+ * Trust tier by backend name.
+ *
+ * Tier 1 — first-party / audited. Tier 2 — reviewed open-source community
+ * harness. Tier 3 has NO entries on purpose: it is what any name absent from this
+ * map resolves to, so adding trust is always a deliberate, reviewable edit and
+ * never an omission.
+ *
+ * `sky-code` is Tier 1 by OWNER DECISION (2026-08-11). The full reasoning, and
+ * the measured cost of the Tier 2 posture it replaced, is recorded in
+ * `daemon/src/harness-trust.ts` beside the gates that read it — the argument
+ * belongs where the enforcement is, not in a shared vocabulary module.
+ */
+export declare const HARNESS_TIERS: Readonly<Record<string, HarnessTrustTier>>;
+/**
+ * Resolve the trust tier for a backend name.
+ *
+ * Returns `3` for any name that is not first-party or reviewed-community —
+ * including empty, whitespace-only, and non-string inputs. Unknown == untrusted.
+ */
+export declare function getHarnessTier(backendName: string): HarnessTrustTier;
+/** What a tier permits in terms of credential DELIVERY. */
+export type CredentialDeliveryPolicy = 'direct-or-gateway' | 'gateway-only' | 'byo-only';
+export declare function credentialPolicyForTier(tier: HarnessTrustTier): CredentialDeliveryPolicy;
+/** How a credential reaches a spawned harness. */
+export type CredentialMode = 'direct-key' | 'gateway' | 'env-map' | 'none';
+/**
+ * May an operator-configured `auto` permission mode SURVIVE for this tier?
+ *
+ * This never approves anything. It answers only whether a mode the operator
+ * already chose is kept or downgraded to per-call adjudication — which is the
+ * distinction most often lost when someone reads "Tier 1" as "pre-approved".
+ */
+export declare function tierPermitsConfiguredAutoMode(tier: HarnessTrustTier): boolean;

package/dist/esm/harnessTrust.js

@@ -0,0 +1,97 @@
+/**
+ * OSK-3897 — harness trust TIERS, shared by the daemon and the CLI.
+ *
+ * ── Why this lives in auth-core ────────────────────────────────────────────
+ *
+ * `sky code doctor` must tell a user what tier their harness is and what that
+ * means for credentials and permission prompts. The daemon is the authority for
+ * that answer, but the CLI cannot import `daemon/src` — separate packages, and
+ * the daemon already depends on the CLI, so the reverse edge would be a cycle.
+ *
+ * `auth-core` is the one package BOTH already resolve: it is a daemon dependency
+ * and it is copied verbatim into the published CLI by
+ * `cli/scripts/vendor-monorepo-deps.js`, which keeps its `exports` map intact and
+ * preserves a single physical instance. So sharing through here changes nothing
+ * in the build or the release pipeline.
+ *
+ * Before this, the CLI carried a MIRROR of the table with a static test that
+ * parsed the daemon's source to catch drift. That guard worked — and it was still
+ * only a guard. The regression it existed to catch had already shipped once: the
+ * doctor described Tier 2 behaviour for a day after the owner decision of
+ * 2026-08-11 moved `sky-code` to Tier 1, and a unit test asserting the stale
+ * string made the wrong claim look load-bearing.
+ *
+ * ── What deliberately did NOT move ────────────────────────────────────────
+ *
+ * The PROVENANCE half stays in the daemon: `OVERSKY_DISTRIBUTED_HARNESSES`,
+ * `PROVENANCE_ELEVATABLE_TIERS`, `ProvenanceEvidence`, `effectiveHarnessTier`,
+ * `credentialTierForSpawn`, and the signature verification behind them.
+ *
+ * That split is the point. A tier is a PUBLISHED FACT — safe for any surface to
+ * read and state. Provenance is EVIDENCE ABOUT BYTES ON DISK, which only the
+ * process that spawns the binary can gather. Moving it here would let the CLI
+ * appear to speak about binary identity it has no way to verify, which is a worse
+ * failure than the drift this file fixes: a confident wrong answer beats an
+ * honestly stale one for causing harm.
+ */
+/**
+ * Trust tier by backend name.
+ *
+ * Tier 1 — first-party / audited. Tier 2 — reviewed open-source community
+ * harness. Tier 3 has NO entries on purpose: it is what any name absent from this
+ * map resolves to, so adding trust is always a deliberate, reviewable edit and
+ * never an omission.
+ *
+ * `sky-code` is Tier 1 by OWNER DECISION (2026-08-11). The full reasoning, and
+ * the measured cost of the Tier 2 posture it replaced, is recorded in
+ * `daemon/src/harness-trust.ts` beside the gates that read it — the argument
+ * belongs where the enforcement is, not in a shared vocabulary module.
+ */
+export const HARNESS_TIERS = Object.freeze({
+    // --- Tier 1: first-party / audited ---
+    claude: 1,
+    codex: 1,
+    opencode: 1,
+    'opencode-acp': 1,
+    gemini: 1,
+    'gemini-acp': 1,
+    'sky-code': 1,
+    // --- Tier 2: reviewed open-source community harnesses ---
+    goose: 2,
+    aider: 2,
+    cline: 2,
+    openhands: 2,
+    kimi: 2,
+    hermes: 2,
+});
+/**
+ * Resolve the trust tier for a backend name.
+ *
+ * Returns `3` for any name that is not first-party or reviewed-community —
+ * including empty, whitespace-only, and non-string inputs. Unknown == untrusted.
+ */
+export function getHarnessTier(backendName) {
+    if (!backendName || typeof backendName !== 'string')
+        return 3;
+    const key = backendName.trim();
+    if (!key)
+        return 3;
+    return HARNESS_TIERS[key] ?? 3;
+}
+export function credentialPolicyForTier(tier) {
+    if (tier === 1)
+        return 'direct-or-gateway';
+    if (tier === 2)
+        return 'gateway-only';
+    return 'byo-only';
+}
+/**
+ * May an operator-configured `auto` permission mode SURVIVE for this tier?
+ *
+ * This never approves anything. It answers only whether a mode the operator
+ * already chose is kept or downgraded to per-call adjudication — which is the
+ * distinction most often lost when someone reads "Tier 1" as "pre-approved".
+ */
+export function tierPermitsConfiguredAutoMode(tier) {
+    return tier === 1;
+}

package/dist/esm/headers-helper.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Invalidate the headers-helper cache.
+ * - `invalidateHeadersHelperCache('foo')` clears only the `foo` server.
+ * - `invalidateHeadersHelperCache()` clears all servers.
+ */
+export declare function invalidateHeadersHelperCache(serverName?: string): void;
+export interface RunHeadersHelperOptions {
+    serverName: string;
+    serverUrl: string;
+}
+/**
+ * Invoke the headers helper for the named MCP server and return the
+ * resulting headers. Results are cached per `serverName` for 5 minutes.
+ *
+ * On cold-cache failure the function throws (fail closed — better to
+ * surface the misconfiguration than to silently send unauthenticated
+ * requests to an MCP server expecting credentials).
+ *
+ * On warm-cache helper failure the stale cached value is returned with
+ * a warning so ongoing requests are not disrupted during a transient
+ * helper outage.
+ *
+ * Returns `{}` (empty object) when no helper is configured.
+ */
+export declare function runHeadersHelper(opts: RunHeadersHelperOptions): Promise<Record<string, string>>;