@skrr-ai/auth-core 0.1.2

package/dist/cjs/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;
+}