@skrr-ai/auth-core 0.1.2

package/dist/esm/credentialResolver.d.ts

@@ -0,0 +1,278 @@
+/**
+ * credentialResolver.ts — documented credential precedence for the
+ * OverSky daemon and CLI.
+ *
+ * Roadmap: docs/daemon-auth-roadmap.md, Phase H.
+ *
+ * The resolver walks a fixed, ordered list of credential sources and
+ * returns the first non-null token along with its source name. Source
+ * names are part of the public surface — they show up in
+ * `oversky doctor`, `oversky status`, and `sky whoami`, and operators
+ * use them to triage "where did this token come from?" tickets.
+ *
+ * Precedence (high → low):
+ *
+ *   1. flag         — `--token <jwt>` CLI flag (debugging)
+ *   2. env-token    — `OVERSKY_TOKEN` env (CI / static; Phase I adds
+ *                     server-side scope=ci validation)
+ *   3. auth-helper  — `OVERSKY_AUTH_HELPER` script output (rotating
+ *                     creds — Vault, AWS SM, internal SSO proxy)
+ *   4. fd-handoff   — `OVERSKY_AUTH_FD` parent→child IPC (Electron
+ *                     supervisor → daemon child). Internal; never
+ *                     user-configured.
+ *   5. keychain     — macOS Keychain (`ai.skrr.daemon`)
+ *   6. file         — `~/.skrr/auth.json` (0600)
+ *   7. interactive  — Browser/device-code login (TTY only, blocked
+ *                     under launchd via `isHeadless()`)
+ *
+ * Skip rules (Phase H.2 + H.4):
+ *   - `bareMode: true` skips slots 4–7 (no platform storage, no IPC,
+ *     no interactive). Bare mode demands an explicit token from env or
+ *     flag — designed for reproducible CI runs and "is the daemon
+ *     broken or is my config corrupted?" triage.
+ *   - `storeMode: 'env-only'` skips slots 5 + 6 (and the daemon
+ *     wrapper additionally disables the auth-generation.json sidecar).
+ *   - `storeMode: 'keychain'` skips slot 6 (file backend).
+ *   - `storeMode: 'file'` skips slot 5 (keychain backend).
+ *
+ * Backend access uses dependency-injected callbacks
+ * (`readKeychainToken`, `readFileToken`, `runInteractiveLogin`) so this
+ * module stays free of OS-specific imports and the Sky CLI can wire its
+ * own backends without dragging the daemon's `keychain.ts` into
+ * non-daemon binaries.
+ */
+import { type AuthHelperFailureReason } from './authHelper.js';
+export type CredentialSource = 'flag' | 'env-token' | 'auth-helper' | 'fd-handoff' | 'keychain' | 'file' | 'interactive' | 'none';
+/**
+ * Ordered slots tried by `CredentialResolver.resolve()`. Excludes
+ * `'none'` (only emitted when no slot produced a token). Treat this as
+ * the canonical published precedence — flipping the order is a public
+ * API change and breaks operator runbooks.
+ */
+export declare const CREDENTIAL_PRECEDENCE: readonly ["flag", "env-token", "auth-helper", "fd-handoff", "keychain", "file", "interactive"];
+export type CredentialStoreMode = 'auto' | 'keychain' | 'file' | 'env-only';
+export interface CredentialResolverOptions {
+    /** `--token <jwt>` flag value, when present on the CLI. */
+    flagToken?: string;
+    /** `--bare` mode (or `OVERSKY_BARE_MODE=1`): skips slots 4–7. */
+    bareMode?: boolean;
+    /** `config.credentials.store` value; defaults to 'auto'. */
+    storeMode?: CredentialStoreMode;
+    /**
+     * Test/explicit override for `OVERSKY_TOKEN`. Pass `undefined` to read
+     * from `process.env`; pass `null` to force-skip the slot; pass a
+     * string to use that value directly.
+     */
+    envTokenOverride?: string | null;
+    /** Test/explicit override for `OVERSKY_AUTH_HELPER` env. Same semantics. */
+    authHelperPathOverride?: string | null;
+    /**
+     * Predicate consulted before invoking the interactive slot. The daemon
+     * wires `isHeadlessDaemon()`; the CLI may wire its own check.
+     */
+    isHeadless?: () => boolean;
+    /**
+     * Read the keychain backend. Returns the token string or null. The
+     * daemon wraps `keychain.readToken()` (and handles `resetAvailability`
+     * on misses) inside this callback.
+     */
+    readKeychainToken?: () => string | null;
+    /** Read the file backend (`~/.skrr/auth.json`). */
+    readFileToken?: () => string | null;
+    /** Trigger interactive login; returns the new token or null. */
+    runInteractiveLogin?: () => Promise<string | null>;
+    /**
+     * L6.1 — workspace-trust gate for `OVERSKY_AUTH_HELPER`.
+     *
+     * Called BEFORE the helper is invoked. The daemon wires this to the
+     * `daemon/src/permissions/workspace-trust.ts` checker; tests can pass a
+     * stub directly. When this returns `{trusted: false, ...}` for a
+     * project- or local-scope helper, the resolver:
+     *   1. Logs an `auth_helper_blocked_untrusted` event via
+     *      `onAuthHelperBlocked` if wired.
+     *   2. Fails CLOSED — returns a `{token: null, source: 'auth-helper'}`
+     *      record with `failClosed: true` so the chain does NOT fall
+     *      through to OAuth. (See L6.1 spec point 4.)
+     *
+     * Absent → no trust check is performed (backward-compat for the CLI
+     * and tests that don't care about workspace-trust). Production daemon
+     * MUST wire this.
+     */
+    helperTrustGate?: (helperPath: string, fromEnvVar: boolean) => HelperTrustDecision;
+    /**
+     * Audit hook fired when `helperTrustGate` blocks the helper. Daemon
+     * wires this to the event-log so security-sensitive denials are
+     * persisted alongside other auth events.
+     */
+    onAuthHelperBlocked?: (info: AuthHelperBlockedInfo) => void;
+    /**
+     * Audit hook fired when L6.3 returns the cold-cache failure sentinel.
+     * Useful for surfacing "your helper is broken" without spamming the
+     * event-log on every read within the TTL.
+     */
+    onAuthHelperSentinelHit?: (info: AuthHelperSentinelInfo) => void;
+}
+/**
+ * L6.1 — return value of the workspace-trust callback.
+ */
+export interface HelperTrustDecision {
+    trusted: boolean;
+    origin: 'user' | 'project' | 'local';
+    reason?: 'no-record' | 'helper-changed';
+}
+export interface AuthHelperBlockedInfo {
+    helperPath: string;
+    origin: 'user' | 'project' | 'local';
+    reason: 'no-record' | 'helper-changed';
+    cwd: string;
+}
+export interface AuthHelperSentinelInfo {
+    helperPath: string;
+    reason: AuthHelperFailureReason;
+    cachedAt: number;
+    ttlMs: number;
+}
+/**
+ * Token kind discriminator (Phase I).
+ *
+ *   - 'standard' — anything that should be treated as a JWT (the default
+ *                  daemon device-code-issued access token, refresh-derived
+ *                  rotations, the user's CLI session token, etc.).
+ *   - 'ci'       — long-lived CI token with the `osk_ci_` prefix. The
+ *                  daemon uses this for the bootstrap-to-daemon-JWT flow
+ *                  (POST /api/daemons/token), MUST NOT schedule refresh,
+ *                  and on auth failure exits 75 with a CI-specific error
+ *                  rather than writing needs-reauth.json.
+ *   - 'install'  — short-lived web-minted JWT with `scope=daemon-install`.
+ *                  The daemon exchanges it through the same /api/daemons/token
+ *                  bootstrap path, persists only the returned daemon
+ *                  credential, and never treats the install JWT as a normal
+ *                  session token.
+ *
+ * Detection is local-only; no server round-trip. The JWT payload read is
+ * intentionally signature-less and is only used to select the client
+ * bootstrap path. The server remains the authority when the token is
+ * exchanged at /api/daemons/token.
+ *
+ * The kill switch `OVERSKY_DISABLE_CI_TOKEN_RESOLVER=1` forces every token to
+ * `'standard'` for triage purposes.
+ */
+export type TokenKind = 'standard' | 'ci' | 'install';
+/** CI-token plaintext prefix; mirrors api/server/services/Auth/daemonCiTokens.js. */
+export declare const CI_TOKEN_PREFIX = "osk_ci_";
+/**
+ * Classify a token by local shape. Pure function; safe to call on any string
+ * (including `null`-coerced empty). Returns `'standard'` for empty input
+ * so callers don't need to null-check before classification.
+ *
+ * Honors `OVERSKY_DISABLE_CI_TOKEN_RESOLVER=1` kill switch — when set,
+ * everything classifies as `'standard'` so the resolver can be used as
+ * a triage tool ("is the CI-token path the problem?").
+ */
+/**
+ * SECURITY NOTE — this reads `scope` out of an UNVERIFIED JWT payload.
+ *
+ * That is safe here, and stays safe only under one condition: the return value
+ * selects a local code path and nothing else. `'install'` means "refresh this
+ * the install-token way"; it grants no capability, skips no check, and asserts
+ * no identity. The server still validates the token on every request, so a
+ * forged `scope: daemon-install` buys an attacker a different local branch and
+ * the same 401.
+ *
+ * The forgery is trivial — no signature is checked, so anyone who can write the
+ * credential file or set the env var can put any claim in it. That is fine
+ * while the only consequence is routing. It stops being fine the moment a
+ * caller treats `TokenKind` as a permission. Do not let this value gate a
+ * capability, and do not add a branch here that returns a kind meaning "more
+ * privileged".
+ *
+ * See `jwtUtils.ts` for the general rule.
+ */
+export declare function classifyTokenKind(token: string | null | undefined): TokenKind;
+export interface ResolvedCredential {
+    token: string | null;
+    source: CredentialSource;
+    /**
+     * Phase I — discriminator the daemon uses to branch on refresh
+     * scheduling, needs-reauth handling, and the bootstrap-to-daemon-JWT
+     * flow. Always `'standard'` when `token` is null.
+     */
+    kind: TokenKind;
+}
+/** @internal test-only — drop the helper cache between tests. */
+export declare function __resetCredentialResolverForTest(): void;
+/**
+ * L6.3 — typed error thrown when the cold-cache failure sentinel is in
+ * effect. Callers (daemon refresh path, CLI) can catch this specifically
+ * to render "auth helper unavailable: <reason>" without falling through
+ * to OAuth or device-code retry.
+ */
+export declare class AuthHelperUnavailableError extends Error {
+    readonly reason: AuthHelperFailureReason;
+    readonly cachedAt: number;
+    constructor(reason: AuthHelperFailureReason, cachedAt: number);
+}
+/**
+ * L6.1 — typed error thrown when the workspace-trust gate blocks a
+ * project- or local-scope helper. Surfaces the actionable next step
+ * (`oversky trust accept`) to the user; the daemon catches and presents
+ * this without falling through to OAuth.
+ */
+export declare class AuthHelperUntrustedError extends Error {
+    readonly origin: 'user' | 'project' | 'local';
+    readonly reason: 'no-record' | 'helper-changed';
+    readonly helperPath: string;
+    constructor(helperPath: string, origin: 'user' | 'project' | 'local', reason: 'no-record' | 'helper-changed');
+}
+/**
+ * H3-6 — public invalidation seam for the `OVERSKY_AUTH_HELPER` result
+ * cache. 401 handlers call this right after receiving a 401 from the
+ * server so the NEXT credential resolve re-invokes the helper to mint
+ * a fresh token instead of serving the stale (cached) one for up to
+ * `OVERSKY_AUTH_HELPER_TTL_MS`.
+ *
+ * Without this seam, a rotated secret at the helper's source (Vault,
+ * AWS Secrets Manager, etc.) could take up to 5 minutes to propagate
+ * to OverSky even when the server is actively rejecting the old
+ * value. The helper is the only slot in the precedence chain that
+ * naturally caches; keychain/file reads are already one-shot per
+ * resolve.
+ *
+ * L6.3 — also clears the cold-cache failure sentinel. A 401 means the
+ * server is rejecting whatever we sent, which usually means the helper
+ * needs to retry from scratch — even when the LAST helper attempt
+ * failed and seeded the sentinel. Without this, a transient helper
+ * failure during the same TTL window as a server-issued 401 would lock
+ * the daemon out for the full TTL.
+ *
+ * Idempotent: calling this on an already-empty cache is a no-op.
+ */
+export declare function invalidateAuthHelperCache(): void;
+export declare class CredentialResolver {
+    private readonly opts;
+    constructor(opts?: CredentialResolverOptions);
+    /**
+     * Walk the precedence chain and return the first non-null token.
+     * Returns `{ token: null, source: 'none' }` when nothing matches.
+     *
+     * Fail-closed exceptions from the auth-helper slot
+     * (`AuthHelperUntrustedError`, `AuthHelperUnavailableError`) propagate
+     * out — they intentionally PREVENT fall-through to OAuth. Callers
+     * that want soft-fall-through behavior must catch explicitly. See
+     * L6.1 spec point 4 and L6.3.
+     */
+    resolve(): Promise<ResolvedCredential>;
+    /**
+     * Test seam: invoke a single slot in isolation. Production code should
+     * always go through `resolve()` so the chain ordering is enforced.
+     */
+    tryResolveSlot(source: Exclude<CredentialSource, 'none'>): Promise<string | null>;
+    private shouldSkip;
+    private tryResolveFlag;
+    private tryResolveEnvToken;
+    private tryResolveAuthHelper;
+    private tryResolveFdHandoff;
+    private tryResolveKeychain;
+    private tryResolveFile;
+    private tryResolveInteractive;
+}

package/dist/esm/credentialResolver.js

@@ -0,0 +1,414 @@
+/**
+ * credentialResolver.ts — documented credential precedence for the
+ * OverSky daemon and CLI.
+ *
+ * Roadmap: docs/daemon-auth-roadmap.md, Phase H.
+ *
+ * The resolver walks a fixed, ordered list of credential sources and
+ * returns the first non-null token along with its source name. Source
+ * names are part of the public surface — they show up in
+ * `oversky doctor`, `oversky status`, and `sky whoami`, and operators
+ * use them to triage "where did this token come from?" tickets.
+ *
+ * Precedence (high → low):
+ *
+ *   1. flag         — `--token <jwt>` CLI flag (debugging)
+ *   2. env-token    — `OVERSKY_TOKEN` env (CI / static; Phase I adds
+ *                     server-side scope=ci validation)
+ *   3. auth-helper  — `OVERSKY_AUTH_HELPER` script output (rotating
+ *                     creds — Vault, AWS SM, internal SSO proxy)
+ *   4. fd-handoff   — `OVERSKY_AUTH_FD` parent→child IPC (Electron
+ *                     supervisor → daemon child). Internal; never
+ *                     user-configured.
+ *   5. keychain     — macOS Keychain (`ai.skrr.daemon`)
+ *   6. file         — `~/.skrr/auth.json` (0600)
+ *   7. interactive  — Browser/device-code login (TTY only, blocked
+ *                     under launchd via `isHeadless()`)
+ *
+ * Skip rules (Phase H.2 + H.4):
+ *   - `bareMode: true` skips slots 4–7 (no platform storage, no IPC,
+ *     no interactive). Bare mode demands an explicit token from env or
+ *     flag — designed for reproducible CI runs and "is the daemon
+ *     broken or is my config corrupted?" triage.
+ *   - `storeMode: 'env-only'` skips slots 5 + 6 (and the daemon
+ *     wrapper additionally disables the auth-generation.json sidecar).
+ *   - `storeMode: 'keychain'` skips slot 6 (file backend).
+ *   - `storeMode: 'file'` skips slot 5 (keychain backend).
+ *
+ * Backend access uses dependency-injected callbacks
+ * (`readKeychainToken`, `readFileToken`, `runInteractiveLogin`) so this
+ * module stays free of OS-specific imports and the Sky CLI can wire its
+ * own backends without dragging the daemon's `keychain.ts` into
+ * non-daemon binaries.
+ */
+import { invokeAuthHelper, getDefaultHelperTtlMs, getLastAuthHelperFailureReason, SENTINEL_TRIGGERING_FAILURES, } from './authHelper.js';
+import { readAuthFromFd } from './fdToken.js';
+import { decodeJwtPayload } from './jwtUtils.js';
+import { getAuthLogger } from './runtime.js';
+/**
+ * Ordered slots tried by `CredentialResolver.resolve()`. Excludes
+ * `'none'` (only emitted when no slot produced a token). Treat this as
+ * the canonical published precedence — flipping the order is a public
+ * API change and breaks operator runbooks.
+ */
+export const CREDENTIAL_PRECEDENCE = [
+    'flag',
+    'env-token',
+    'auth-helper',
+    'fd-handoff',
+    'keychain',
+    'file',
+    'interactive',
+];
+/** CI-token plaintext prefix; mirrors api/server/services/Auth/daemonCiTokens.js. */
+export const CI_TOKEN_PREFIX = 'osk_ci_';
+/**
+ * Classify a token by local shape. Pure function; safe to call on any string
+ * (including `null`-coerced empty). Returns `'standard'` for empty input
+ * so callers don't need to null-check before classification.
+ *
+ * Honors `OVERSKY_DISABLE_CI_TOKEN_RESOLVER=1` kill switch — when set,
+ * everything classifies as `'standard'` so the resolver can be used as
+ * a triage tool ("is the CI-token path the problem?").
+ */
+/**
+ * SECURITY NOTE — this reads `scope` out of an UNVERIFIED JWT payload.
+ *
+ * That is safe here, and stays safe only under one condition: the return value
+ * selects a local code path and nothing else. `'install'` means "refresh this
+ * the install-token way"; it grants no capability, skips no check, and asserts
+ * no identity. The server still validates the token on every request, so a
+ * forged `scope: daemon-install` buys an attacker a different local branch and
+ * the same 401.
+ *
+ * The forgery is trivial — no signature is checked, so anyone who can write the
+ * credential file or set the env var can put any claim in it. That is fine
+ * while the only consequence is routing. It stops being fine the moment a
+ * caller treats `TokenKind` as a permission. Do not let this value gate a
+ * capability, and do not add a branch here that returns a kind meaning "more
+ * privileged".
+ *
+ * See `jwtUtils.ts` for the general rule.
+ */
+export function classifyTokenKind(token) {
+    if (process.env.OVERSKY_DISABLE_CI_TOKEN_RESOLVER === '1')
+        return 'standard';
+    if (typeof token !== 'string' || token.length === 0)
+        return 'standard';
+    if (token.startsWith(CI_TOKEN_PREFIX))
+        return 'ci';
+    const payload = decodeJwtPayload(token);
+    if (payload &&
+        typeof payload === 'object' &&
+        !Array.isArray(payload) &&
+        payload.scope === 'daemon-install') {
+        return 'install';
+    }
+    return 'standard';
+}
+let _helperCache = null;
+/** @internal test-only — drop the helper cache between tests. */
+export function __resetCredentialResolverForTest() {
+    _helperCache = null;
+}
+/**
+ * L6.3 — typed error thrown when the cold-cache failure sentinel is in
+ * effect. Callers (daemon refresh path, CLI) can catch this specifically
+ * to render "auth helper unavailable: <reason>" without falling through
+ * to OAuth or device-code retry.
+ */
+export class AuthHelperUnavailableError extends Error {
+    reason;
+    cachedAt;
+    constructor(reason, cachedAt) {
+        super(`auth helper unavailable: ${reason}`);
+        this.name = 'AuthHelperUnavailableError';
+        this.reason = reason;
+        this.cachedAt = cachedAt;
+    }
+}
+/**
+ * L6.1 — typed error thrown when the workspace-trust gate blocks a
+ * project- or local-scope helper. Surfaces the actionable next step
+ * (`oversky trust accept`) to the user; the daemon catches and presents
+ * this without falling through to OAuth.
+ */
+export class AuthHelperUntrustedError extends Error {
+    origin;
+    reason;
+    helperPath;
+    constructor(helperPath, origin, reason) {
+        super(`OVERSKY_AUTH_HELPER (${origin}-scope) is not trusted for this workspace ` +
+            `(reason: ${reason}). Run \`oversky trust accept\` to allow it.`);
+        this.name = 'AuthHelperUntrustedError';
+        this.origin = origin;
+        this.reason = reason;
+        this.helperPath = helperPath;
+    }
+}
+/**
+ * H3-6 — public invalidation seam for the `OVERSKY_AUTH_HELPER` result
+ * cache. 401 handlers call this right after receiving a 401 from the
+ * server so the NEXT credential resolve re-invokes the helper to mint
+ * a fresh token instead of serving the stale (cached) one for up to
+ * `OVERSKY_AUTH_HELPER_TTL_MS`.
+ *
+ * Without this seam, a rotated secret at the helper's source (Vault,
+ * AWS Secrets Manager, etc.) could take up to 5 minutes to propagate
+ * to OverSky even when the server is actively rejecting the old
+ * value. The helper is the only slot in the precedence chain that
+ * naturally caches; keychain/file reads are already one-shot per
+ * resolve.
+ *
+ * L6.3 — also clears the cold-cache failure sentinel. A 401 means the
+ * server is rejecting whatever we sent, which usually means the helper
+ * needs to retry from scratch — even when the LAST helper attempt
+ * failed and seeded the sentinel. Without this, a transient helper
+ * failure during the same TTL window as a server-issued 401 would lock
+ * the daemon out for the full TTL.
+ *
+ * Idempotent: calling this on an already-empty cache is a no-op.
+ */
+export function invalidateAuthHelperCache() {
+    _helperCache = null;
+}
+export class CredentialResolver {
+    opts;
+    constructor(opts = {}) {
+        this.opts = opts;
+    }
+    /**
+     * Walk the precedence chain and return the first non-null token.
+     * Returns `{ token: null, source: 'none' }` when nothing matches.
+     *
+     * Fail-closed exceptions from the auth-helper slot
+     * (`AuthHelperUntrustedError`, `AuthHelperUnavailableError`) propagate
+     * out — they intentionally PREVENT fall-through to OAuth. Callers
+     * that want soft-fall-through behavior must catch explicitly. See
+     * L6.1 spec point 4 and L6.3.
+     */
+    async resolve() {
+        for (const source of CREDENTIAL_PRECEDENCE) {
+            if (this.shouldSkip(source))
+                continue;
+            const token = await this.tryResolveSlot(source);
+            if (token) {
+                return { token, source, kind: classifyTokenKind(token) };
+            }
+        }
+        return { token: null, source: 'none', kind: 'standard' };
+    }
+    /**
+     * Test seam: invoke a single slot in isolation. Production code should
+     * always go through `resolve()` so the chain ordering is enforced.
+     */
+    async tryResolveSlot(source) {
+        switch (source) {
+            case 'flag':
+                return this.tryResolveFlag();
+            case 'env-token':
+                return this.tryResolveEnvToken();
+            case 'auth-helper':
+                return this.tryResolveAuthHelper();
+            case 'fd-handoff':
+                return this.tryResolveFdHandoff();
+            case 'keychain':
+                return this.tryResolveKeychain();
+            case 'file':
+                return this.tryResolveFile();
+            case 'interactive':
+                return this.tryResolveInteractive();
+        }
+    }
+    shouldSkip(source) {
+        const { bareMode } = this.opts;
+        const storeMode = this.opts.storeMode ?? 'auto';
+        if (bareMode &&
+            (source === 'fd-handoff' ||
+                source === 'keychain' ||
+                source === 'file' ||
+                source === 'interactive')) {
+            return true;
+        }
+        if (storeMode === 'env-only' && (source === 'keychain' || source === 'file')) {
+            return true;
+        }
+        if (storeMode === 'keychain' && source === 'file')
+            return true;
+        if (storeMode === 'file' && source === 'keychain')
+            return true;
+        return false;
+    }
+    // ------------------------------------------------------------------
+    // Slot implementations
+    // ------------------------------------------------------------------
+    tryResolveFlag() {
+        const v = this.opts.flagToken;
+        return typeof v === 'string' && v.length > 0 ? v : null;
+    }
+    tryResolveEnvToken() {
+        if (this.opts.envTokenOverride === null)
+            return null; // explicit force-skip
+        if (typeof this.opts.envTokenOverride === 'string') {
+            return this.opts.envTokenOverride.length > 0 ? this.opts.envTokenOverride : null;
+        }
+        const v = process.env.OVERSKY_TOKEN;
+        return typeof v === 'string' && v.length > 0 ? v : null;
+    }
+    async tryResolveAuthHelper() {
+        let helperPath;
+        let fromEnvVar = false;
+        if (this.opts.authHelperPathOverride === null)
+            return null;
+        if (typeof this.opts.authHelperPathOverride === 'string') {
+            helperPath =
+                this.opts.authHelperPathOverride.length > 0 ? this.opts.authHelperPathOverride : null;
+        }
+        else {
+            helperPath = process.env.OVERSKY_AUTH_HELPER ?? null;
+            fromEnvVar = helperPath !== null;
+        }
+        if (!helperPath)
+            return null;
+        // ---------------------------------------------------------------
+        // L6.3 — sentinel served BEFORE re-spawning. Failure cache prevents
+        // silent fall-through to OAuth within the TTL window.
+        // ---------------------------------------------------------------
+        if (_helperCache && Date.now() < _helperCache.expiresAt) {
+            if (_helperCache.kind === 'success') {
+                return _helperCache.token;
+            }
+            // Failed sentinel still warm — fail closed. The slot returns
+            // a fail-closed signal via thrown error so the chain doesn't
+            // continue to keychain/file/OAuth.
+            this.opts.onAuthHelperSentinelHit?.({
+                helperPath,
+                reason: _helperCache.reason,
+                cachedAt: _helperCache.cachedAt,
+                ttlMs: _helperCache.expiresAt - _helperCache.cachedAt,
+            });
+            throw new AuthHelperUnavailableError(_helperCache.reason, _helperCache.cachedAt);
+        }
+        // ---------------------------------------------------------------
+        // L6.1 — workspace-trust gate. Project- and local-scope helpers
+        // must have an accepted trust record for the cwd. User-scope
+        // helpers (env var, ~/.skrr/) bypass the check.
+        //
+        // Trust check runs BEFORE invocation so we never even spawn an
+        // untrusted script. Failed trust = fail-closed throw, never
+        // falls through to OAuth.
+        // ---------------------------------------------------------------
+        if (this.opts.helperTrustGate) {
+            const decision = this.opts.helperTrustGate(helperPath, fromEnvVar);
+            if (!decision.trusted) {
+                const reason = decision.reason ?? 'no-record';
+                this.opts.onAuthHelperBlocked?.({
+                    helperPath,
+                    origin: decision.origin,
+                    reason,
+                    cwd: process.cwd(),
+                });
+                throw new AuthHelperUntrustedError(helperPath, decision.origin, reason);
+            }
+        }
+        const result = await invokeAuthHelper(helperPath);
+        if (result) {
+            const ttlMs = getDefaultHelperTtlMs();
+            const expiresAt = result.expiresAt ?? Date.now() + ttlMs;
+            _helperCache = { kind: 'success', token: result.token, expiresAt };
+            return result.token;
+        }
+        // ---------------------------------------------------------------
+        // L6.3 — invocation failed. Distinguish two failure classes:
+        //
+        //   - Validation failures ('disabled', 'invalid-path',
+        //     'not-executable', null) — helper isn't really wired up.
+        //     Fall through to next slot. NO sentinel.
+        //
+        //   - Execution failures ('timeout', 'non-zero-exit', 'oversized',
+        //     'empty-output', 'parse-error', 'spawn-error') — the helper
+        //     was wired up but couldn't deliver a token. Cache the
+        //     sentinel and fail closed for the TTL window. This matches
+        //     CC's `' '` literal sentinel at CC-A-34.
+        // ---------------------------------------------------------------
+        const reason = getLastAuthHelperFailureReason();
+        if (reason && SENTINEL_TRIGGERING_FAILURES.has(reason)) {
+            const ttlMs = getDefaultHelperTtlMs();
+            const cachedAt = Date.now();
+            _helperCache = {
+                kind: 'failed',
+                reason,
+                cachedAt,
+                expiresAt: cachedAt + ttlMs,
+            };
+            this.opts.onAuthHelperSentinelHit?.({
+                helperPath,
+                reason,
+                cachedAt,
+                ttlMs,
+            });
+            throw new AuthHelperUnavailableError(reason, cachedAt);
+        }
+        // Validation failure — no sentinel; fall through.
+        return null;
+    }
+    async tryResolveFdHandoff() {
+        // FD handoff is daemon-only; CLI never has OVERSKY_AUTH_FD set, so
+        // the env check below makes this a near-zero-cost slot for CLI
+        // processes. The fdToken module does its own kill-switch check
+        // (`fdTokenHandoff` killSwitch) and bounded read.
+        if (!process.env.OVERSKY_AUTH_FD)
+            return null;
+        try {
+            const payload = await readAuthFromFd();
+            if (!payload)
+                return null;
+            if (payload.accessExpiresAt && Date.now() > payload.accessExpiresAt) {
+                return null;
+            }
+            return payload.accessToken || null;
+        }
+        catch (err) {
+            getAuthLogger().warn(`[credentialResolver] FD handoff read failed: ${formatErr(err)}`);
+            return null;
+        }
+    }
+    tryResolveKeychain() {
+        if (!this.opts.readKeychainToken)
+            return null;
+        try {
+            return this.opts.readKeychainToken();
+        }
+        catch (err) {
+            getAuthLogger().warn(`[credentialResolver] keychain read failed: ${formatErr(err)}`);
+            return null;
+        }
+    }
+    tryResolveFile() {
+        if (!this.opts.readFileToken)
+            return null;
+        try {
+            return this.opts.readFileToken();
+        }
+        catch (err) {
+            getAuthLogger().warn(`[credentialResolver] file read failed: ${formatErr(err)}`);
+            return null;
+        }
+    }
+    async tryResolveInteractive() {
+        if (!this.opts.runInteractiveLogin)
+            return null;
+        if (this.opts.isHeadless?.())
+            return null;
+        try {
+            return await this.opts.runInteractiveLogin();
+        }
+        catch (err) {
+            getAuthLogger().warn(`[credentialResolver] interactive login failed: ${formatErr(err)}`);
+            return null;
+        }
+    }
+}
+function formatErr(err) {
+    return err instanceof Error ? err.message : String(err);
+}