crosscheck-cli 0.0.63 → 0.0.64

package/dist/key-status.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Report which providers this machine has keys for — and nothing else.
+ *
+ * WHY THIS EXISTS: keys are per-machine and never leave the machine, which is
+ * the right security posture but leaves the browser blind. Open /account on
+ * your laptop and it cannot tell you that your desktop lost its OpenAI key
+ * two days ago, because it has no idea the desktop ever had one. Every
+ * machine but the one you are sitting at is a black hole. This closes that
+ * with metadata, without weakening the posture at all.
+ *
+ * WHAT LEAVES THIS MACHINE, exhaustively:
+ *   provider name · a key is present yes/no · the last 4 characters ·
+ *   how it last behaved · when that was
+ *
+ * The last-4 is the only part derived from the key itself, and it exists for
+ * one reason: so a human can tell whether the key on the dashboard is the one
+ * they think it is before replacing it. `suffix4()` is the ONLY place in this
+ * file that touches key material, it is four characters wide by construction,
+ * and the server's schema independently rejects anything longer. Two
+ * independent bounds, because a single one is a single edit away from gone.
+ *
+ * Reporting is opt-OUT via CROSSCHECK_NO_KEY_STATUS=1. An org that considers
+ * provider coverage sensitive can turn it off and lose only the dashboard.
+ */
+/** How a key last behaved. Mirrors cb_key_result on the server. */
+export type KeyResult = "ok" | "invalid_key" | "quota_billing" | "network" | "provider_down" | "unknown";
+export type KeyStatusItem = {
+    provider: string;
+    present: boolean;
+    suffix?: string;
+    lastResult?: KeyResult;
+    lastCheckedAt?: string;
+};
+/**
+ * The last four characters, or nothing.
+ *
+ * Short keys return undefined rather than a padded or partial value: a key
+ * under 8 characters is not a real key, and reporting a suffix of a 5-char
+ * string would expose most of it. The threshold is deliberately well above 4.
+ */
+export declare function suffix4(key: string | null | undefined): string | undefined;
+export declare function keyStatusDisabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Read the local store and describe it. Absent providers are reported
+ * explicitly as `present: false` rather than omitted, because the server
+ * treats a report as a full replacement of the seat's provider set and
+ * "missing from the list" has to mean "no longer configured".
+ */
+export declare function collectKeyStatus(): Promise<KeyStatusItem[]>;
+/**
+ * Send the report. Best-effort and silent: this runs on the MCP startup path,
+ * where a network problem must cost a stale dashboard row and never a failed
+ * connection.
+ */
+export declare function reportKeyStatus(args: {
+    seatId: string;
+    orgId: string;
+    jwt: string;
+    serverUrl?: string;
+    timeoutMs?: number;
+}): Promise<"sent" | "skipped" | "failed">;

package/dist/key-verify.d.ts

@@ -0,0 +1,31 @@
+/**
+ * "Does this key actually work?" — answered by asking the provider, cheaply.
+ *
+ * Every probe here is a model-list GET: no completion, no tokens, no cost.
+ * That matters, because a verify button that quietly bills you is a verify
+ * button people learn not to press.
+ *
+ * THE DISTINCTION THIS FILE EXISTS FOR: "we could not reach the provider" and
+ * "the provider rejected your key" are completely different problems with
+ * completely different fixes, and they arrive looking similar. Collapsing
+ * them sends someone to regenerate a key because their wifi dropped. So the
+ * default for anything ambiguous is `network` or `unknown` — never
+ * `invalid_key`. We accuse a key only when a provider actually refused it.
+ */
+/** Mirrors cb_key_result on the server and KeyResult in key-status.ts. */
+export type VerifyResult = "ok" | "invalid_key" | "quota_billing" | "network" | "provider_down" | "unknown";
+export type VerifyOutcome = {
+    result: VerifyResult;
+    /** One line, safe to show a user. NEVER contains the key. */
+    detail: string;
+};
+export declare function canVerify(provider: string): boolean;
+export declare function classifyStatus(status: number, body: string): VerifyOutcome;
+/**
+ * Probe one provider. `fetchImpl` is injectable so the classification can be
+ * tested without touching the network.
+ */
+export declare function verifyKey(provider: string, key: string, opts?: {
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}): Promise<VerifyOutcome>;

package/dist/keychain.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Secret store — NO native dependencies.
+ *
+ * Replaces the former `@napi-rs/keyring` backend, whose per-platform native
+ * binary kept corrupting on `npx` installs (truncated `.node` → dlopen
+ * failure; npm/cli#4828). The public API is unchanged so call sites don't move.
+ *
+ * Three backends:
+ *   - "file" (DEFAULT, recommended): an encrypted file at <dir>/secrets.enc
+ *     (AES-256-GCM) keyed by a random 32-byte key at <dir>/secret.key
+ *     (mode 0400); data file 0600, dir 0700. Pure Node `crypto`, ZERO password
+ *     prompts. <dir> defaults to ~/.crosscheck — in your home directory, never
+ *     inside the repo you're working in, never committed to git. Threat model:
+ *     protects against casual file copying / sync, not a process already
+ *     running as you (same as gh / aws / .env).
+ *   - "keychain" (opt-in, macOS only): shells out to `/usr/bin/security`. More
+ *     OS-integrated, but macOS prompts for your LOGIN PASSWORD on every write —
+ *     so a fresh setup asks several times. Not the default for that reason.
+ *     Every spawn is hard-timeout-bounded with captured stdio, so a Keychain
+ *     GUI prompt can never block a non-interactive `serve` (a timeout is
+ *     treated as "not found" — we degrade, never hang).
+ *   - "1password" (opt-in, enterprise): routes ONLY "key:<provider>" lookups
+ *     that have an entry in ~/.crosscheck/1password.json to the 1Password
+ *     backend (see src/onepassword/); everything else — the activation JWT,
+ *     the HMAC signing key, installUuid, and any provider NOT listed in that
+ *     config — still uses the file store, always. 1Password can't hold a
+ *     machine-local secret and was never asked to; this is explicit routing
+ *     by secret class, not a fallback. Read-only: writes to a 1Password-
+ *     mapped provider throw ReadOnlyBackendError. A configured-but-failing
+ *     1Password read throws OnePasswordReadError rather than silently
+ *     reading a stale value from the local file store — see
+ *     docs/onepassword-security.md for the full design.
+ *
+ * Selection precedence:
+ *   1. CROSSCHECK_SECRET_STORE = file | keychain | 1password  (env override)
+ *   2. saved preference in <dir>/store.json                    (set by `keys store` / `keys setup --backend 1password`)
+ *   3. "file"                                                    (default)
+ *
+ * Migration: when the file backend is active and no file store exists yet, we
+ * transparently import any existing macOS-keychain items once (those reads are
+ * prompt-free), so upgrading from a keychain build never strands a user.
+ *
+ * Keys never leave the machine, except when the 1password backend is active
+ * and a provider is explicitly mapped to it — that key never touches
+ * crosscheck's own storage at all, encrypted or not.
+ */
+import { type OpReadErrorKind } from "./onepassword/op.js";
+/**
+ * "1password-only" is crosscheck-enterprise's mode: unlike "1password"
+ * (opt-in per provider, unmapped providers silently fall back to the file
+ * store), it closes that fallback specifically for provider keys — an
+ * unmapped provider throws instead of reading/writing the file store.
+ * Machine-local secrets (jwt, hmacSigningKey, etc.) are unaffected either
+ * way; see onePasswordProviderFor's null-for-non-"key:"-names behavior.
+ */
+export type Backend = "keychain" | "file" | "1password" | "1password-only";
+export declare function dataDir(): string;
+/** Backend label for `crosscheck doctor`. */
+export declare function secretBackend(): Backend;
+/** Where the encrypted file store lives (shown by `doctor`). */
+export declare function fileStorePath(): string;
+/** Thrown by setSecret/deleteSecret for a "key:<provider>" that's mapped to
+ *  the 1Password backend — it's read-only in this version. */
+export declare class ReadOnlyBackendError extends Error {
+    constructor(name: string);
+}
+/** Thrown by getSecret when a provider IS mapped to 1Password but the read
+ *  failed — never silently falls back to the local file store instead,
+ *  which would defeat the point of an enterprise-mandated backend and could
+ *  resurrect a stale or already-rotated key. */
+export declare class OnePasswordReadError extends Error {
+    readonly provider: string;
+    readonly code: OpReadErrorKind;
+    constructor(provider: string, code: OpReadErrorKind, detail: string);
+}
+/** Thrown by getSecret/setSecret/deleteSecret in "1password-only" mode for a
+ *  "key:<provider>" that has no 1Password mapping — the enterprise-mode
+ *  equivalent of ReadOnlyBackendError, but for the CLOSED fallback rather
+ *  than a read-only mapped entry. */
+export declare class NotMappedInEnterpriseModeError extends Error {
+    constructor(provider: string);
+}
+export declare function setSecret(name: string, value: string): Promise<void>;
+export declare function getSecret(name: string): Promise<string | null>;
+export declare function deleteSecret(name: string): Promise<boolean>;
+/**
+ * List every Crosscheck-owned credential. Used by `crosscheck keys list` and
+ * by deactivation to wipe everything in one pass.
+ *
+ * For a 1Password-mapped provider this NEVER performs an actual 1Password
+ * read: doing so here would mean every `listSecrets()` call (doctor, `keys
+ * list`, deactivation) silently fans out into one `op` invocation per
+ * mapped provider — in desktop mode, that's N sequential GUI unlock
+ * prompts for an operation the user didn't ask to unlock anything for. The
+ * placeholder marker reports "configured," never the resolved value.
+ */
+export declare const ONEPASSWORD_LIST_PLACEHOLDER = "(configured via 1Password \u2014 value not read)";
+export declare function listSecrets(): Promise<Array<{
+    account: string;
+    password: string;
+}>>;
+/**
+ * Switch the secret store backend and migrate existing secrets into it.
+ * Persists the choice so all future invocations use it. Returns how many
+ * credentials were migrated. NOTE: migrating *to* keychain triggers a macOS
+ * login-password prompt per credential — callers should warn first.
+ */
+/**
+ * Persist "1password" as the active backend WITHOUT setSecretBackend()'s
+ * copy-existing-secrets-in behavior, which is meaningless for a read-only,
+ * config-driven backend. Callers (`keys setup --backend 1password`) must
+ * validate config + connectivity themselves FIRST — this only flips the
+ * switch once that validation already succeeded.
+ */
+export declare function enableOnePasswordBackend(): void;
+/** crosscheck-enterprise only — see the Backend type's "1password-only" doc. */
+export declare function enableOnePasswordOnlyBackend(): void;
+export declare function setSecretBackend(target: Backend): Promise<{
+    migrated: number;
+}>;

package/dist/keys-browser-flow.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Browser-paste flow for upstream LLM keys. Same trust pattern as
+ * `gh auth login`: the CLI spins up a localhost HTTP server, opens a
+ * Crosscheck (XC)-served form in the user's browser, and the form POSTs the
+ * pasted key directly back to localhost. Crosscheck's servers never
+ * see the value.
+ *
+ * Why this exists: pasting a 200-character API key into a terminal is
+ * (a) easy to screw up (newlines, shell history), (b) reveals the value
+ * on-screen, and (c) culturally foreign to non-CLI-native users. The
+ * browser form is masked-input, has Cmd-V "Paste from Clipboard"
+ * affordances built in, and is what every developer is used to from
+ * console.anthropic.com etc.
+ *
+ * Security properties:
+ *   - State token (32 bytes urlsafe) bound at server-start. Mismatched
+ *     state → CLI rejects the POST.
+ *   - Loopback only — server binds to 127.0.0.1 (NOT 0.0.0.0). Other
+ *     machines on the LAN can't hit it.
+ *   - Browser → CLI path is HTTP, but it's loopback, so it never crosses
+ *     the network. Modern browsers special-case localhost CORS.
+ *   - 5-minute timeout. Server self-terminates after the value lands or
+ *     the deadline elapses.
+ *   - Server accepts exactly one valid POST. Subsequent calls 410.
+ *   - Provider list pinned at compile time on both sides (server + CLI)
+ *     so an attacker-controlled query string can't store a key under a
+ *     made-up provider name.
+ */
+export declare const SUPPORTED_PROVIDERS: Set<string>;
+export type CapturedKey = {
+    provider: string;
+    value: string;
+};
+/**
+ * Run the browser flow. Returns the captured key on success; throws on
+ * timeout, invalid state, or server error.
+ */
+export declare function captureKeyViaBrowser(args: {
+    provider: string;
+    /**
+     * Optional override for the page URL — useful for local dev / preview
+     * deployments. Defaults to ${SERVER_URL}/cli/keys (crosscheckagent.com).
+     */
+    pageBaseUrl?: string;
+}): Promise<CapturedKey>;
+/**
+ * Batch variant: collect keys for MULTIPLE providers in ONE browser page.
+ * The CLI opens /cli/keys?providers=a,b,c&state&callback; the page POSTs a
+ * single { state, keys: { provider: value } } to the loopback /keys endpoint.
+ * Returns the captured (non-empty) keys map. Used by `keys setup` / `install`
+ * so there is zero interactive terminal input. Keys never transit our backend.
+ */
+export declare function captureKeysViaBrowser(args: {
+    providers: string[];
+    pageBaseUrl?: string;
+    timeoutMs?: number;
+    /** When false, the CLI does NOT open /cli/keys itself — the keys form is
+     *  hosted elsewhere (e.g. /cli/start) and posts to this same loopback. */
+    openPage?: boolean;
+    /** Invoked once the loopback is listening, with its callback URL + state, so
+     *  the caller can route the user to a page that posts keys back here (e.g.
+     *  run device-auth opening /cli/start with these params). The keys timeout
+     *  starts after this resolves. */
+    onReady?: (info: {
+        callback: string;
+        state: string;
+    }) => Promise<void> | void;
+}): Promise<Record<string, string>>;

package/dist/keys-manage-cli.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `crosscheck keys manage` — open a live key-management session in the browser.
+ *
+ * Runs in the foreground on purpose. The session is a capability over your
+ * local key store, and a capability should be visible while it exists: the
+ * terminal shows what's happening, and closing it closes the session. A
+ * background daemon quietly holding this open would be the wrong shape.
+ */
+export declare function runKeysManage(opts?: {
+    open?: boolean;
+}): Promise<void>;

package/dist/keys-session.d.ts

@@ -0,0 +1,89 @@
+/**
+ * A live, authenticated key-management session on this machine.
+ *
+ * WHAT THIS CHANGES. Key management used to be one-shot: `crosscheck keys`
+ * opened a page, the page POSTed one batch, the CLI applied it and exited.
+ * You could not sit in your account page and manage keys, and you could not
+ * see what a change did. This turns that into a session the browser can drive
+ * for as long as it's open — which is what makes /account a place you return
+ * to rather than a form you submit.
+ *
+ * WHAT IT DOES NOT CHANGE: keys still never reach our servers. The browser
+ * talks straight to 127.0.0.1. Everything below exists to make that channel
+ * safe to leave open for ten minutes instead of ten seconds.
+ *
+ * THE TOKEN NEVER TOUCHES OUR SERVER. It is delivered to the page in the URL
+ * *fragment* (`#xc=port.token`), and fragments are not sent in HTTP requests.
+ * So crosscheckagent.com — and its logs, and its proxies, and anyone who ever
+ * breaches it — cannot obtain the capability to manage keys on your machine.
+ * This is deliberately stricter than the design called for: registering the
+ * token server-side would have enabled a nicer "click a button in the browser
+ * first" flow, at the cost of making our server able to reach into your key
+ * store. That trade wasn't worth making, so the flow starts in the terminal.
+ *
+ * Defence in depth, each layer assuming the others failed:
+ *   - binds 127.0.0.1 only, never 0.0.0.0 — nothing on the LAN can see it
+ *   - every request needs the bearer token, compared in constant time
+ *   - CORS locked to our origin, so a hostile page can't read responses
+ *   - Private Network Access preflight answered explicitly (see below)
+ *   - idle TTL of 10 minutes, hard cap of 60, so a forgotten tab isn't
+ *     an indefinitely open door
+ *   - responses carry the last 4 characters of a key and never more, so a
+ *     bug in this file cannot turn into a key disclosure
+ */
+import { type VerifyResult } from "./key-verify.js";
+/** Idle timeout. Every authenticated request pushes it out. */
+export declare const IDLE_TTL_MS: number;
+/** Absolute ceiling, regardless of activity. A session left open all day is
+ *  not a session, it's a hole. */
+export declare const MAX_SESSION_MS: number;
+export type ProviderState = {
+    provider: string;
+    label: string;
+    present: boolean;
+    suffix?: string;
+    lastResult?: VerifyResult;
+    lastCheckedAt?: string;
+    canVerify: boolean;
+};
+/** In-memory record of verifies done this session, so the page can show the
+ *  result of the button the user just pressed. Not persisted: a verify is a
+ *  point-in-time fact and pretending otherwise is how "healthy" badges lie. */
+type VerifyMemo = Map<string, {
+    result: VerifyResult;
+    at: string;
+}>;
+export declare function isManageableProvider(name: string): boolean;
+export declare function readProviderStates(memo: VerifyMemo): Promise<ProviderState[]>;
+/**
+ * CORS, plus the header that stops Chromium blocking this outright.
+ *
+ * Chromium's Private Network Access treats a request from a public HTTPS page
+ * to 127.0.0.1 as a privilege escalation and sends a preflight carrying
+ * `Access-Control-Request-Private-Network: true`. If the listener doesn't
+ * answer `Access-Control-Allow-Private-Network: true`, the request is blocked
+ * with no visible error — the fetch just fails, and the page has no way to
+ * tell that apart from "the CLI isn't running". Cheap to send, and it is the
+ * difference between this feature working and mysteriously not.
+ */
+export declare function sessionCorsHeaders(origin?: string): Record<string, string>;
+export declare function tokensMatch(expected: string, provided: string | undefined): boolean;
+export declare function bearerFrom(header: string | undefined): string | undefined;
+export type SessionHandle = {
+    port: number;
+    token: string;
+    url: string;
+    /** Resolves when the session ends, for any reason. */
+    done: Promise<"ended" | "idle" | "expired">;
+    close: (reason?: "ended" | "idle" | "expired") => void;
+};
+/**
+ * Start the session server. Resolves once it's listening; the caller decides
+ * whether to open a browser and how to report progress.
+ */
+export declare function startKeysSession(opts?: {
+    onEvent?: (msg: string) => void;
+}): Promise<SessionHandle>;
+/** Providers currently holding a key — used for the terminal summary. */
+export declare function configuredProviders(): Promise<string[]>;
+export {};

package/dist/keys-setup.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Provider-key setup. Non-interactive by design — it never reads stdin (so it
+ * can't hang in a non-TTY / agent context):
+ *
+ *   1. Silently import any keys already present in the environment
+ *      (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, XAI_API_KEY,
+ *      KIMI_API_KEY).
+ *   2. For any provider still missing a key, open ONE browser page that
+ *      collects them all at once and posts them straight to a localhost
+ *      loopback server → the local secret store. Zero terminal typing.
+ *
+ * Keys are stored only in the local secret store (see keychain.ts: OS keychain
+ * on macOS, an encrypted file elsewhere) and never transit crosscheckagent.com.
+ * Power users who want to type a single key can still use
+ * `crosscheck keys add <provider> --paste`.
+ */
+export type PanelProvider = {
+    key: string;
+    label: string;
+    env: string[];
+};
+/** The default panel. `grok` maps to XAI_API_KEY inside the engine. `env` lists
+ *  the environment variables we'll auto-import from, in priority order — the
+ *  aliases catch people who set GROK_API_KEY / GOOGLE_API_KEY / etc. */
+export declare const KEY_PANEL: PanelProvider[];
+/**
+ * Use what's already available: count existing keychain entries, import any
+ * env-present keys (writing them to the keychain), and return the providers
+ * that still need a key. No prompts, no network.
+ */
+export declare function importEnvKeys(): Promise<{
+    configured: number;
+    need: PanelProvider[];
+}>;
+/** Standalone `crosscheck keys setup`: env-import, then one browser page for the rest. */
+export declare function runKeysSetup(): Promise<{
+    configured: number;
+}>;

package/dist/lib.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Library surface — the API Crosscheck Desktop consumes.
+ *
+ * WHY THIS FILE EXISTS
+ * --------------------
+ * The desktop app needs the same vault, the same activation, the same model
+ * resolution and the same key verification the CLI has. There are three ways
+ * to get that and only one of them is safe:
+ *
+ *   1. Copy the code into the desktop repo.  REJECTED. The secret store and
+ *      the activation signing are exactly the code that must never diverge
+ *      between two clients writing the same `~/.crosscheck/` directory. Two
+ *      copies is two encryption implementations and eventually two file
+ *      formats.
+ *   2. Extract into a third npm package.  REJECTED for now. It buys nothing
+ *      over this file and adds a package to version, publish and keep in
+ *      lockstep — the same npx-cache trap that already forces a CLI bump on
+ *      every engine release (see config.ts, ENGINE_FALLBACK_VERSION).
+ *   3. Export from the CLI itself.  THIS. The desktop app takes a single
+ *      dependency on `crosscheck-cli`, which already pins `crosscheck-mcp`
+ *      exactly — so one dependency delivers the vault AND a version-locked
+ *      engine, and the CLI and the desktop app are the same code by
+ *      construction rather than by discipline.
+ *
+ * WHAT IS DELIBERATELY NOT HERE
+ * -----------------------------
+ * Nothing that prints to the console or reads stdin. Every export below is a
+ * pure function or an async call that returns data. The CLI's interactive
+ * wizards (`keys-setup`, `keys-manage-cli`, `doctor`) stay out: the desktop
+ * app renders its own UI over the same primitives, and a library that can
+ * `process.exit()` is a library that can take an Electron main process down
+ * with it.
+ */
+export { dataDir, fileStorePath, secretBackend, setSecretBackend, getSecret, setSecret, deleteSecret, listSecrets, ONEPASSWORD_LIST_PLACEHOLDER, ReadOnlyBackendError, OnePasswordReadError, NotMappedInEnterpriseModeError, type Backend, } from "./keychain.js";
+export { CANONICAL_PROVIDERS, KEY_FORMATS, resolveProvider, looksLikeApiKey, validateKey, formatWarning, } from "./key-format.js";
+export { canVerify, classifyStatus, verifyKey, type VerifyResult, type VerifyOutcome, } from "./key-verify.js";
+export { suffix4, keyStatusDisabled, collectKeyStatus, reportKeyStatus, type KeyResult, type KeyStatusItem, } from "./key-status.js";
+export { activate, activateDeviceFlow } from "./activate.js";
+export { currentState, isAllowedToRun, runHeartbeat, startScheduler, type HeartbeatState, } from "./heartbeat.js";
+export { readLocalModelPrefs, readLocalModelModes, readLocalOrigins, effectiveForMode, setChainForMode, setLocalModelPref, addLocalModelFallback, removeLocalModelFallback, unsetLocalModelPref, syncModelPreferencesFromServer, pushModelPreferenceToServer, deleteModelPreferenceOnServer, readPendingConflicts, writePendingConflicts, clearPendingConflicts, type ModelPreferences, type ModeScopedPreferences, type ModelMode, type PrefOrigin, type OriginMap, type PrefConflict, } from "./model-prefs.js";
+export { MODEL_ENV_VARS, resolveModelForProvider, resolveAllModels, type ModelSource, type ResolvedModel, } from "./model-resolve.js";
+export { resolveEffectiveModel, isBlockedByPolicy, type ModelPolicy, type ModelPolicyEntry, } from "./model-policy.js";
+export { SERVER_URL, CLI_VERSION, ENGINE_PACKAGE, CLI_PACKAGE } from "./config.js";
+export { resolveEngineVersion } from "./engine-version.js";
+export { registerMcpServer, SERVER_NAME as MCP_SERVER_NAME, SERVER_COMMAND as MCP_SERVER_COMMAND, SERVER_ARGS as MCP_SERVER_ARGS, type RegisterResult, type ServerRegistration, } from "./mcp-register.js";

package/dist/lib.js

@@ -0,0 +1,57 @@
+/**
+ * Library surface — the API Crosscheck Desktop consumes.
+ *
+ * WHY THIS FILE EXISTS
+ * --------------------
+ * The desktop app needs the same vault, the same activation, the same model
+ * resolution and the same key verification the CLI has. There are three ways
+ * to get that and only one of them is safe:
+ *
+ *   1. Copy the code into the desktop repo.  REJECTED. The secret store and
+ *      the activation signing are exactly the code that must never diverge
+ *      between two clients writing the same `~/.crosscheck/` directory. Two
+ *      copies is two encryption implementations and eventually two file
+ *      formats.
+ *   2. Extract into a third npm package.  REJECTED for now. It buys nothing
+ *      over this file and adds a package to version, publish and keep in
+ *      lockstep — the same npx-cache trap that already forces a CLI bump on
+ *      every engine release (see config.ts, ENGINE_FALLBACK_VERSION).
+ *   3. Export from the CLI itself.  THIS. The desktop app takes a single
+ *      dependency on `crosscheck-cli`, which already pins `crosscheck-mcp`
+ *      exactly — so one dependency delivers the vault AND a version-locked
+ *      engine, and the CLI and the desktop app are the same code by
+ *      construction rather than by discipline.
+ *
+ * WHAT IS DELIBERATELY NOT HERE
+ * -----------------------------
+ * Nothing that prints to the console or reads stdin. Every export below is a
+ * pure function or an async call that returns data. The CLI's interactive
+ * wizards (`keys-setup`, `keys-manage-cli`, `doctor`) stay out: the desktop
+ * app renders its own UI over the same primitives, and a library that can
+ * `process.exit()` is a library that can take an Electron main process down
+ * with it.
+ */
+// --- The vault. Same file, same lock, same AES-256-GCM. ---------------------
+export { dataDir, fileStorePath, secretBackend, setSecretBackend, getSecret, setSecret, deleteSecret, listSecrets, ONEPASSWORD_LIST_PLACEHOLDER, ReadOnlyBackendError, OnePasswordReadError, NotMappedInEnterpriseModeError, } from "./keychain.js";
+// --- Which providers exist, and does this string look like one's key? -------
+export { CANONICAL_PROVIDERS, KEY_FORMATS, resolveProvider, looksLikeApiKey, validateKey, formatWarning, } from "./key-format.js";
+// --- Does the key actually work? Asks the provider, never our server. -------
+export { canVerify, classifyStatus, verifyKey, } from "./key-verify.js";
+// --- Metadata-only reporting. Presence, last 4, last outcome. ---------------
+export { suffix4, keyStatusDisabled, collectKeyStatus, reportKeyStatus, } from "./key-status.js";
+// --- Seat activation and the signed heartbeat. ------------------------------
+export { activate, activateDeviceFlow } from "./activate.js";
+export { currentState, isAllowedToRun, runHeartbeat, startScheduler, } from "./heartbeat.js";
+// --- Model pinning: local preferences, org policy, effective resolution. ----
+export { readLocalModelPrefs, readLocalModelModes, readLocalOrigins, effectiveForMode, setChainForMode, setLocalModelPref, addLocalModelFallback, removeLocalModelFallback, unsetLocalModelPref, syncModelPreferencesFromServer, pushModelPreferenceToServer, deleteModelPreferenceOnServer, readPendingConflicts, writePendingConflicts, clearPendingConflicts, } from "./model-prefs.js";
+export { MODEL_ENV_VARS, resolveModelForProvider, resolveAllModels, } from "./model-resolve.js";
+export { resolveEffectiveModel, isBlockedByPolicy, } from "./model-policy.js";
+// --- Identity and versions, so the app can report what it is running. -------
+export { SERVER_URL, CLI_VERSION, ENGINE_PACKAGE, CLI_PACKAGE } from "./config.js";
+export { resolveEngineVersion } from "./engine-version.js";
+// --- Registering the MCP server with Claude Code. -------------------------
+// The wizard's last step. Shared so the app and `crosscheck install` write
+// byte-identical entries to ~/.claude.json — two spellings of the same server
+// is how a user ends up with a duplicate that fails opaquely.
+export { registerMcpServer, SERVER_NAME as MCP_SERVER_NAME, SERVER_COMMAND as MCP_SERVER_COMMAND, SERVER_ARGS as MCP_SERVER_ARGS, } from "./mcp-register.js";
+//# sourceMappingURL=lib.js.map

package/dist/lib.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lib.js","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,+EAA+E;AAC/E,OAAO,EACL,OAAO,EACP,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,SAAS,EACT,SAAS,EACT,YAAY,EACZ,WAAW,EACX,4BAA4B,EAC5B,oBAAoB,EACpB,oBAAoB,EACpB,8BAA8B,GAE/B,MAAM,eAAe,CAAC;AAEvB,+EAA+E;AAC/E,OAAO,EACL,mBAAmB,EACnB,WAAW,EACX,eAAe,EACf,eAAe,EACf,WAAW,EACX,aAAa,GACd,MAAM,iBAAiB,CAAC;AAEzB,+EAA+E;AAC/E,OAAO,EACL,SAAS,EACT,cAAc,EACd,SAAS,GAGV,MAAM,iBAAiB,CAAC;AAEzB,+EAA+E;AAC/E,OAAO,EACL,OAAO,EACP,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,GAGhB,MAAM,iBAAiB,CAAC;AAEzB,+EAA+E;AAC/E,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,EACL,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,cAAc,GAEf,MAAM,gBAAgB,CAAC;AAExB,+EAA+E;AAC/E,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,wBAAwB,EACxB,mBAAmB,EACnB,8BAA8B,EAC9B,2BAA2B,EAC3B,6BAA6B,EAC7B,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,GAOtB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,cAAc,EACd,uBAAuB,EACvB,gBAAgB,GAGjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,qBAAqB,EACrB,iBAAiB,GAGlB,MAAM,mBAAmB,CAAC;AAE3B,+EAA+E;AAC/E,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACnF,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAE3D,6EAA6E;AAC7E,2EAA2E;AAC3E,8EAA8E;AAC9E,8DAA8D;AAC9D,OAAO,EACL,iBAAiB,EACjB,WAAW,IAAI,eAAe,EAC9B,cAAc,IAAI,kBAAkB,EACpC,WAAW,IAAI,eAAe,GAG/B,MAAM,mBAAmB,CAAC"}

package/dist/mcp-register.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Self-register the crosscheck MCP server with Claude Code so the user never
+ * hand-edits JSON.
+ *
+ * Primary path: the `claude` CLI — `claude mcp add --scope user crosscheck --
+ * npx -y -p crosscheck-cli@latest crosscheck serve`. User scope means it's
+ * available in every workspace, which matches a per-seat license.
+ *
+ * Fallback: if the `claude` CLI isn't on PATH, merge-write the user's
+ * ~/.claude.json `mcpServers` map in place — never clobbering existing
+ * servers or other settings.
+ *
+ * The bin name is pinned explicitly via `-p <pkg> <bin>` rather than the
+ * shorter `npx -y crosscheck-cli@latest serve` — bare `npx <pkg>` only
+ * auto-selects a bin when the package ships exactly one, or one matching
+ * the package name. crosscheck-cli briefly shipped a second bin
+ * (crosscheck-enterprise) in 0.0.50, which made every existing
+ * registration written with the short form fail with "could not
+ * determine executable to run" (silently, since this string gets written
+ * to ~/.claude.json and only fails later as an opaque MCP connection
+ * error). Keep this form even now that crosscheck-cli is back to a single
+ * bin — it's what makes a future second bin safe to add again.
+ */
+export declare const SERVER_NAME = "crosscheck";
+export declare const SERVER_COMMAND = "npx";
+export declare const SERVER_ARGS: string[];
+export type RegisterResult = {
+    method: "cli";
+} | {
+    method: "file";
+    configPath: string;
+} | {
+    method: "manual";
+    snippet: string;
+    reason: string;
+};
+export type ServerRegistration = {
+    name: string;
+    command: string;
+    args: string[];
+};
+/**
+ * `reg` defaults to the standard crosscheck-cli registration. crosscheck-
+ * enterprise passes its own {name: "crosscheck-enterprise", command: "npx",
+ * args: ["-y", "crosscheck-enterprise@latest", "serve"]} so Claude Code
+ * spawns the right binary — both can coexist in the same ~/.claude.json
+ * under different server names.
+ */
+export declare function registerMcpServer(reg?: ServerRegistration): RegisterResult;

package/dist/mcp.d.ts

@@ -0,0 +1,24 @@
+/**
+ * MCP server façade. Spawns the TypeScript crosscheck-mcp engine as a
+ * subprocess and lets the IDE's MCP stdio JSON-RPC traffic flow through it.
+ *
+ * (Previously this bundled and spawned a Python server. crosscheck-mcp is now
+ * pure TypeScript and ships as a normal npm dependency — no Python required.)
+ *
+ * Pre-flight (before spawning the child):
+ *   1. Verify the activation JWT from the OS keychain — refuse to serve if
+ *      missing, expired, or revoked.
+ *   2. Resolve the crosscheck-mcp engine entry from node_modules (falling back
+ *      to `npx -y crosscheck-mcp` if it isn't installed alongside).
+ *   3. Pull every upstream LLM key from the keychain into the child's env
+ *      (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, XAI_API_KEY,
+ *      GROQ_API_KEY, DEEPSEEK_API_KEY, MISTRAL_API_KEY). The customer never
+ *      hand-manages env vars.
+ *
+ * The child inherits stdio so the IDE's MCP client talks to it directly; we
+ * don't proxy or interpret the JSON-RPC traffic. The CLI is the
+ * license/onboarding wrapper; crosscheck-mcp is the engine.
+ */
+export declare function startMcpServer(opts?: {
+    enforceProviderPolicy?: boolean;
+}): Promise<void>;

package/dist/model-policy.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Pure resolution logic for "which model actually gets called for this
+ * provider" — no I/O. Two independent things feed it:
+ *   - a candidate model (explicit env var override > a saved personal
+ *     preference > nothing), resolved by the caller before this runs
+ *   - an optional enterprise model policy entry for that provider
+ *     (crosscheck-enterprise only — a standard install never has one)
+ *
+ * A model policy is a hard clamp, not a suggestion: if the candidate isn't
+ * allowed, this never returns it. Deliberately does NOT know crosscheck-mcp's
+ * own DEFAULT_MODELS (duplicating that map here would just reintroduce the
+ * exact staleness bug detectStalePins was built to catch) — when nothing
+ * safe can be resolved, it returns undefined and the caller leaves the
+ * env var unset, deferring to the engine's own built-in default. An admin
+ * who wants a *specific* fallback should set `pinned`, or list it first
+ * in `allow`.
+ */
+export type ModelPolicyEntry = {
+    /** "*" = no model-level restriction for this provider (only the existing
+     *  provider-level allowlist applies). Otherwise the exact list of model
+     *  ids this org permits for this provider. */
+    allow: "*" | readonly string[];
+    /** Always wins over `allow`, including over "*". */
+    deny: readonly string[];
+    /** Admin-chosen fallback when neither the caller's candidate nor a
+     *  user-set preference is usable. Optional. */
+    pinned?: string;
+};
+export type ModelPolicy = Readonly<Record<string, ModelPolicyEntry>>;
+/**
+ * Resolve the effective model for one provider. `policy` is this
+ * provider's entry only (or undefined — most providers on a standard
+ * install have none). Returns undefined when nothing safe to inject was
+ * found, meaning: don't set the env var, let the engine use its own
+ * default.
+ */
+export declare function resolveEffectiveModel(args: {
+    candidate?: string;
+    policy?: ModelPolicyEntry;
+}): string | undefined;
+/** True when `model` would be rejected by `policy` — used to tell the user
+ *  WHY their chosen preference didn't take effect, distinct from "no
+ *  preference was set at all." */
+export declare function isBlockedByPolicy(model: string, policy: ModelPolicyEntry): boolean;