@skrr-ai/cli 0.1.8

package/dist/lib/credential-resolver.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTrustedAutonomousCredential = resolveTrustedAutonomousCredential;
+exports.resolveCredential = resolveCredential;
+exports.kindOf = kindOf;
+exports.formatCredentialSource = formatCredentialSource;
+/**
+ * credential-resolver.ts — Phase H.1 precedence for the Sky CLI.
+ *
+ * Constructs a `CredentialResolver` (from @skrr-ai/auth-core) wired with
+ * CLI-appropriate backends. The resolver walks the published chain:
+ *
+ *   1. flag         — --token <jwt> (debugging; BaseCommand parses)
+ *   2. env-token    — OVERSKY_TOKEN (CI / static; kind='ci' detected)
+ *   3. auth-helper  — OVERSKY_AUTH_HELPER script output
+ *   4. fd-handoff   — N/A for CLI (skipped; no parent fd)
+ *   5. keychain     — ai.skrr.cli.<profile>
+ *   6. file         — ~/.skrr/cli-auth.json (and legacy cli-config.json)
+ *   7. interactive  — skipped; `skrr login` is the explicit interactive path
+ *
+ * Why skip `interactive` here? The resolver's `runInteractiveLogin`
+ * would fire whenever `this.requireAuth()` is called without a token —
+ * that's a footgun for commands like `skrr whoami` which should fail
+ * with "run `skrr login`" rather than launching a browser unprompted.
+ * Login is an explicit user action (the `skrr login` command), not a
+ * side-effect of a missing token. Same design choice as the daemon.
+ */
+const auth_core_1 = require("@skrr-ai/auth-core");
+const auth_core_init_1 = require("./auth-core-init");
+const config_1 = require("./config");
+const auth_storage_1 = require("./auth-storage");
+const cred_envelope_1 = require("./cred-envelope");
+/**
+ * Return the only credential an Agent-owned CLI process is allowed to use.
+ *
+ * The daemon stamps `OVERSKY_AUTONOMOUS_SESSION=1` after sanitizing the
+ * provider environment.  Once that trusted marker is present, `--token`,
+ * `OVERSKY_TOKEN`, auth helpers, Keychain, cli-auth.json, and daemon
+ * auto-broker credentials are all ambient human authority and must be
+ * ignored.  A missing session token is represented by the normal null
+ * credential so the command can fail closed without probing those sources.
+ *
+ * `null` means this is an ordinary CLI invocation and the regular resolver
+ * chain should run.
+ */
+function resolveTrustedAutonomousCredential(env = process.env) {
+    if (env.OVERSKY_AUTONOMOUS_SESSION !== '1')
+        return null;
+    const token = env.OVERSKY_SESSION_TOKEN?.trim() || null;
+    return {
+        token,
+        source: token ? 'env-token' : 'none',
+        kind: (0, auth_core_1.classifyTokenKind)(token),
+    };
+}
+/**
+ * Resolve the active credential. Returns the token, the source that
+ * produced it, and (Phase I) a `kind` discriminator so callers can
+ * branch on CI vs. standard tokens.
+ */
+async function resolveCredential(opts = {}) {
+    const cfg = (() => {
+        try {
+            return (0, config_1.loadConfig)();
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    const storeMode = opts.storeModeOverride ?? cfg?.credentials?.store ?? 'auto';
+    const bareMode = opts.bareMode || ['1', 'true', 'TRUE', 'yes'].includes(process.env.OVERSKY_BARE_MODE ?? '');
+    // Clear an observation left by a prior, unrelated direct backend probe in
+    // this process. Only a blocked read made by THIS resolver should trigger the
+    // bounded wait/retry below.
+    (0, cred_envelope_1.consumeEncryptedCredentialReadWhileInactive)();
+    const resolver = new auth_core_1.CredentialResolver({
+        flagToken: opts.flagToken,
+        bareMode,
+        storeMode,
+        // CLI never has an interactive slot — users run `skrr login` explicitly.
+        isHeadless: () => true,
+        // Stored credentials are only usable against the origin that issued
+        // them. Desktop can update cli-config.json#baseURL when switching
+        // environments; passing the current URL here prevents a dev refresh
+        // token from ever being presented to prod (or vice versa).
+        readKeychainToken: () => (cfg?.baseURL ? auth_storage_1.backends.readKeychainToken(cfg.baseURL) : null),
+        readFileToken: () => (cfg?.baseURL ? auth_storage_1.backends.readFileToken(cfg.baseURL) : null),
+    });
+    const resolved = await resolver.resolve();
+    const encryptedReadBlocked = (0, cred_envelope_1.consumeEncryptedCredentialReadWhileInactive)();
+    if (resolved.token || !encryptedReadBlocked || opts.allowUnreadableStoredCredential) {
+        return resolved;
+    }
+    // The resolver reached a real envelope-wrapped Keychain/file value while
+    // auth prefetch was still inactive. Wait for that SAME in-flight init and
+    // retry only the stored slots; higher-precedence flag/env/helper sources have
+    // already declined, so re-running them would duplicate side effects.
+    await (0, auth_core_init_1.waitForCliCredentialEnvelope)();
+    const storedSources = storeMode === 'keychain'
+        ? ['keychain']
+        : storeMode === 'file'
+            ? ['file']
+            : storeMode === 'env-only' || bareMode
+                ? []
+                : ['keychain', 'file'];
+    for (const source of storedSources) {
+        const token = await resolver.tryResolveSlot(source);
+        if (token)
+            return { token, source, kind: (0, auth_core_1.classifyTokenKind)(token) };
+    }
+    return { token: null, source: 'none', kind: 'standard' };
+}
+/**
+ * Classify an already-resolved token without re-running the chain.
+ * Thin wrapper over `classifyTokenKind` so callers that already hold
+ * a token (e.g., just post-login) don't need to re-resolve.
+ */
+function kindOf(token) {
+    return (0, auth_core_1.classifyTokenKind)(token);
+}
+/**
+ * Human-readable label for a `CredentialSource`. Used by `skrr whoami`
+ * and (Phase H) `skrr doctor`.
+ *
+ * ADD-CLI5 — labels are aligned with the daemon's
+ * `daemon/src/auth.ts::formatCredentialSource` so operators grepping
+ * support logs don't have to maintain a mental map of two parallel
+ * vocabularies for the same concept. Where the underlying artifact
+ * genuinely differs (e.g. the CLI persists at `cli-auth.json`; the
+ * daemon at `auth.json`), the label names the CANONICAL kind of
+ * source (`auth.json file`) — the exact filename shows up in
+ * `skrr doctor`/`oversky doctor` output anyway.
+ *
+ * The source names themselves (`flag`, `env-token`, etc.) are the
+ * load-bearing stable surface — those ship from `@skrr-ai/auth-core`
+ * and are checked by BOTH codebases' tests. These human labels are
+ * presentation-only.
+ */
+function formatCredentialSource(source) {
+    switch (source) {
+        case 'flag':
+            return 'CLI --token flag';
+        case 'env-token':
+            return 'OVERSKY_TOKEN';
+        case 'auth-helper':
+            return 'OVERSKY_AUTH_HELPER';
+        case 'fd-handoff':
+            return 'parent process (fd-handoff)';
+        case 'keychain':
+            return 'macOS Keychain';
+        case 'file':
+            return 'auth.json file';
+        case 'interactive':
+            return 'interactive login';
+        case 'none':
+            return '(none)';
+        default: {
+            // Defensive against a future CredentialSource enum extension.
+            // Compile-time exhaustiveness without crashing at runtime.
+            const _exhaustive = source;
+            return String(_exhaustive);
+        }
+    }
+}

package/dist/lib/daemonBroker.d.ts

@@ -0,0 +1,255 @@
+/**
+ * daemonBroker.ts — Sky CLI client for the local `oversky` daemon's
+ * cli-handoff endpoint.
+ *
+ * When the daemon is already authenticated for the user on this machine,
+ * the CLI can skip its own browser-based login entirely by asking the
+ * daemon to broker a sibling cli-scope refresh family. See
+ * `daemon/src/auth/cliHandoff.ts` for the daemon-side handler and
+ * `api/server/routes/daemons.js::cli-handoff` for the server route.
+ *
+ * ## Design constraints
+ *
+ * - **Read-only on the daemon's auth.** The CLI never touches the
+ *   daemon's keychain entries directly — it goes through the loopback
+ *   HTTP broker which uses the daemon's bearer to call the server. That
+ *   means a logged-out daemon = clean fall-through to PKCE, not a CLI
+ *   that tries to read stale credentials.
+ * - **Bounded total time.** The broker call must not hang the CLI on a
+ *   wedged daemon. Combined header + body + upstream is capped at 20s
+ *   (matches the daemon's own 15s upstream cap + a 5s buffer).
+ * - **Distinct exit semantics.** Any error short-circuits to "fall
+ *   through to PKCE" — only an explicit 403 with `code:
+ *   'CI_TOKEN_REFUSED'` is surfaced to the user (skrr shouldn't silently
+ *   reauthenticate a CI process). Everything else returns `null`.
+ *
+ * ## Bootstrap file location
+ *
+ * Mirrors `daemon/src/local-bootstrap.ts::bootstrapPath()`. On macOS the
+ * file is `~/Library/Application Support/skrr/daemon-island.<profile>.json`;
+ * on Linux/Windows it's `~/.skrr/profiles/<profile>/daemon-island.json`
+ * with a pre-Phase-K fallback to `~/.skrr/daemon-island.json`. We
+ * default `<profile>` to `'default'` to match the CLI's existing keychain
+ * service-name suffix; a future `--profile` flag would override this.
+ *
+ * The bootstrap file carries `{ pid, host, port, secret }`. We check pid
+ * liveness with `process.kill(pid, 0)` to filter stale files left behind
+ * by a force-killed daemon.
+ */
+import { type CliConfig } from './config';
+/**
+ * Wire-shape of the bootstrap file. Mirrors
+ * `daemon/src/local-bootstrap.ts::LocalBootstrap`. Kept loose — fields
+ * the CLI doesn't use are ignored, and a future addition (e.g. version
+ * bump, new metadata) doesn't break this reader.
+ */
+export interface LocalBootstrap {
+    version?: number;
+    pid?: number;
+    daemonId?: string;
+    host?: string;
+    port?: number;
+    /** Base64 32-byte handshake secret. */
+    secret?: string;
+    /**
+     * Server URL the daemon is authenticated against (e.g.
+     * `https://oversky.ai` or `http://localhost:3080`). Daemons that
+     * pre-date the baseURL-match check do not write this field — the
+     * broker pre-flight then refuses to call so we never mint against
+     * an unknown server.
+     */
+    serverUrl?: string;
+}
+/**
+ * Normalize a base URL for equality comparison. Mirrors the daemon-side
+ * `normalizeBaseUrl` in `daemon/src/auth/cliHandoff.ts` so both ends
+ * compare identical strings. Trailing slashes stripped, scheme + host
+ * lowercased, path preserved as-is.
+ */
+export declare function normalizeBaseUrl(u: string | undefined | null): string | null;
+/**
+ * Successful broker response. Shape mirrors the server's
+ * `/api/daemons/cli-handoff` payload.
+ */
+export interface DaemonBrokerResult {
+    accessToken: string;
+    /** ISO-8601 string from the server, or epoch ms when newer servers ship it. */
+    accessExpiresAt?: string | number;
+    refreshToken: string;
+    refreshExpiresAt?: string | number;
+    cliId: string;
+    userId: string;
+    email: string | null;
+}
+/**
+ * Explicit reasons the broker path could fail. These exist to keep the
+ * caller's fall-through decision auditable — most reasons → silently
+ * fall through to PKCE; `ci_token_refused` is the one we surface
+ * because re-driving it via PKCE would not change the outcome.
+ */
+export type DaemonBrokerErrorReason = 'no_bootstrap' | 'stale_bootstrap' | 'bootstrap_parse' | 'base_url_mismatch' | 'daemon_not_authed' | 'ci_token_refused' | 'server_error' | 'network' | 'timeout' | 'unknown';
+export interface DaemonBrokerFailure {
+    ok: false;
+    reason: DaemonBrokerErrorReason;
+    /** Human-readable detail for logging / `--verbose` reporting. */
+    detail?: string;
+    /** HTTP status when the failure came from the broker / server. */
+    status?: number;
+    /** Server-supplied error code when present (e.g. 'CI_TOKEN_REFUSED'). */
+    code?: string;
+    /**
+     * For `base_url_mismatch`: the daemon's serverUrl, so the caller can
+     * surface a helpful hint like "run `skrr login --base-url <X>` to use
+     * the daemon".
+     */
+    daemonServerUrl?: string;
+}
+export type DaemonBrokerOutcome = (DaemonBrokerResult & {
+    ok: true;
+}) | DaemonBrokerFailure;
+export interface DaemonBrokerOptions {
+    /** Stable per-machine cliId the CLI wants the new refresh row bound to. */
+    cliId: string;
+    /**
+     * The Sky CLI's currently-configured baseURL (e.g. `https://oversky.ai`).
+     * Two roles:
+     *   1. Pre-flight check vs `bootstrap.serverUrl` — when they don't
+     *      match, we refuse to call the daemon so we never mint a token
+     *      against the wrong server. The broker token would be signed by
+     *      a server the CLI isn't pointing at and the next skrr command
+     *      would 401 with a confusing signature-mismatch error.
+     *   2. Sent in the request body so the daemon can re-validate; an
+     *      older daemon without the check ignores the field, a newer
+     *      daemon refuses on mismatch with 400 `BASE_URL_MISMATCH`.
+     *
+     * Optional only so tests / callers that don't yet thread it through
+     * compile. Real-world callers (login.ts) always pass it.
+     */
+    baseURL?: string;
+    /**
+     * Profile name. Defaults to `'default'`. A future `--profile` flag
+     * threads through here. Used to resolve the bootstrap file path.
+     */
+    profile?: string;
+    /** Override the bootstrap file path entirely (tests / unusual layouts). */
+    bootstrapPathOverride?: string;
+    /** Override total request timeout. Tests use a short value. */
+    timeoutMs?: number;
+}
+/**
+ * Compute the bootstrap file path. Exported for tests so they can assert
+ * the platform fork without monkeypatching `os.platform()`.
+ */
+export declare function resolveBootstrapPath(profile?: string): string;
+/** Build deterministic non-default bootstrap paths from a daemon config directory. */
+export declare function resolveProfileBootstrapPaths(primary: string, entryNames: readonly string[]): string[];
+/**
+ * List the bootstrap files that a Sky CLI may use for a local daemon
+ * handoff. `default` stays first for backwards compatibility; any other
+ * profile is a fallback for users who run their daemon with `--profile`.
+ *
+ * Profile names are derived from filenames/directories created by the
+ * daemon, never interpolated from user input. Sorting makes the fallback
+ * deterministic when more than one matching daemon is running.
+ */
+export declare function resolveBootstrapCandidatePaths(profile?: string): string[];
+/**
+ * Resolve the first live daemon bootstrap for a profile. Message-intent
+ * submission reuses the same authenticated loopback discovery as the login
+ * broker, including the pre-Phase-K non-darwin fallback.
+ */
+export declare function findLiveDaemonBootstrap({ profile, bootstrapPathOverride, }?: {
+    profile?: string;
+    bootstrapPathOverride?: string;
+}): LocalBootstrap | null;
+/**
+ * Read and validate the bootstrap file. Returns null on absent / stale /
+ * unparseable so the caller can fall through to its own login flow
+ * without distinguishing those cases (the daemon owns recovery — if the
+ * file is malformed, the CLI shouldn't try to repair it).
+ */
+export declare function readBootstrap(filePath: string): LocalBootstrap | null;
+/**
+ * Try the daemon-as-broker handoff. Returns a tagged outcome so callers
+ * can decide between fall-through and surface-to-user without parsing
+ * messages.
+ *
+ * The CLI's `cliLogin()` dispatcher calls this BEFORE the PKCE branch;
+ * any `ok: false` outcome (except `ci_token_refused`) means "continue to
+ * PKCE", and `ok: true` means "we're done, persist + return".
+ */
+export declare function attemptDaemonBrokerLogin(opts: DaemonBrokerOptions): Promise<DaemonBrokerOutcome>;
+/**
+ * Convenience wrapper: run the broker call and, on success, persist the
+ * returned bundle through the canonical Sky CLI auth backend (Keychain
+ * on macOS, `cli-auth.json` elsewhere). Returns the same outcome shape
+ * so the caller can branch on `ok`.
+ */
+export declare function attemptDaemonBrokerLoginAndPersist(opts: DaemonBrokerOptions): Promise<DaemonBrokerOutcome>;
+export interface MaybeAutoBrokerOptions {
+    /** Sky's current CliConfig — used to derive cliId and baseURL. */
+    cliConfig: CliConfig;
+    /** True when the operator passed `--bare` or set `OVERSKY_BARE_MODE`. */
+    bareMode: boolean;
+    /**
+     * oclif command id (e.g. 'tasks list', 'whoami', 'login'). Used to
+     * short-circuit auth-self-managed commands. Passed via
+     * `BaseCommand.id` after oclif's init.
+     */
+    commandId?: string;
+    /**
+     * Read the daemon island bootstrap from this path instead of resolving it
+     * from the OS config dir. Mirrors the same option on
+     * `AttemptDaemonBrokerOptions` and is forwarded verbatim.
+     *
+     * Without it `maybeAutoBroker` always reached the developer's REAL
+     * `daemon-island.<profile>.json`, so its tests only passed on a machine
+     * whose live daemon happened to be authed against the same `baseURL` the
+     * test used — and failed with `base_url_mismatch` (or `no_bootstrap` on CI)
+     * everywhere else. Production callers omit it and behave exactly as before.
+     */
+    bootstrapPathOverride?: string;
+}
+export interface MaybeAutoBrokerResult {
+    /**
+     * True when the broker was actually attempted. False means we
+     * short-circuited (skip-list, bare mode, env override, etc.) and the
+     * caller should treat this as a no-op.
+     */
+    triggered: boolean;
+    /** The broker outcome when triggered. Undefined on no-op. */
+    outcome?: DaemonBrokerOutcome;
+    /**
+     * When a fresh cliId was generated to seed the call, the caller
+     * MUST persist the returned CliConfig before subsequent commands
+     * run — otherwise the next process would mint a different cliId
+     * and end up with a divergent refresh family.
+     */
+    updatedConfig?: CliConfig;
+}
+/**
+ * Auto-broker pre-flight for `BaseCommand.init()`. When the credential
+ * resolver returns no token, this attempts a silent daemon broker so
+ * a user with `oversky login` already done never has to type
+ * `skrr login` at all.
+ *
+ * Skip rules (any single trigger short-circuits):
+ *   - `bareMode` — operator said "don't touch the keychain/file"
+ *   - `isEnvAuthOverride()` — `OVERSKY_TOKEN` / `OVERSKY_REFRESH_TOKEN`
+ *     supplied; operator owns auth lifecycle
+ *   - `OVERSKY_SKIP_DAEMON_BROKER=1` — explicit opt-out
+ *   - `commandId` is in `AUTH_SELF_MANAGED_COMMANDS`
+ *
+ * Side effects:
+ *   - Calls `attemptDaemonBrokerLoginAndPersist` which writes to the
+ *     keychain / cli-auth.json on success (this is the whole point —
+ *     subsequent commands read the persisted token via the normal
+ *     resolver chain, no broker round-trip per command).
+ *   - May generate a new `cliId` if the config doesn't have one. The
+ *     caller MUST persist `updatedConfig` so the next invocation
+ *     presents the same id to the server's refresh rotator.
+ *
+ * Never throws — broker call failures are surfaced via the typed
+ * `outcome` discriminator (or absent on skip).
+ */
+export declare function maybeAutoBroker(opts: MaybeAutoBrokerOptions): Promise<MaybeAutoBrokerResult>;