@skrr-ai/cli 0.1.122 → 0.1.124

package/dist/node_modules/@skrr-ai/auth-core/dist/esm/kek/macos.d.ts

@@ -21,6 +21,28 @@ export declare function __setExecFileForTest(fn: ExecFileLike | null): void;
 export declare function __resetSecurityProbeCacheForTest(): void;
 /** @internal Test seam — clear the resolved-keychain cache. */
 export declare function __resetResolvedKeychainCacheForTest(): void;
+/**
+ * Create a master KEK without replacing an existing item. This key is shared
+ * by profiles, so even a first-use race in a different process must not
+ * overwrite the key protecting already wrapped credentials.
+ *
+ * The `service` / `account` parameters are threaded from the calling
+ * `MacosKek` instance so each instance keeps its own keychain entry.
+ *
+ * Explicit-keychain target: the resolved login-keychain path is passed
+ * as the trailing positional argument to `add-generic-password` so
+ * `security(1)` cannot fall back to a "default keychain" lookup that
+ * triggers a system-modal `Keychain Not Found` dialog. If no keychain
+ * resolves, throw `KekUnavailableError` immediately rather than
+ * shelling out at all.
+ */
+declare function writeKekToKeychain(kek: Buffer, service: string, account: string): Promise<void>;
+/**
+ * @internal Test seam — the Keychain write on its own, so a spec can reach the live-state
+ * guard without `wrap()`'s `security` probe getting in the way. A spec using it empties `PATH`,
+ * so that a guard which stopped firing reaches no `security` binary.
+ */
+export declare const __writeKekToKeychainForTest: typeof writeKekToKeychain;
 /**
  * Zero out and drop every cached master-KEK buffer.
  *

package/dist/node_modules/@skrr-ai/auth-core/dist/esm/kek/macos.js

@@ -57,6 +57,8 @@ import fs from 'node:fs';
 import { openBuffer, sealBuffer, deserialize as envelopeDeserialize, serialize as envelopeSerialize, KEY_LEN, } from '../credentialEnvelope.js';
 import { KekUnavailableError } from './types.js';
 import { registerZeroizeHook } from './zeroize-registry.js';
+import { MASTER_KEK_KEYCHAIN_ACCOUNT, MASTER_KEK_KEYCHAIN_SERVICE } from './masterKekService.js';
+import { assertMayMutateLiveKeychain, rethrowIfLiveStateRefusal } from '../liveState.js';
 /**
  * Stable telemetry kind string — fleet dashboards size the macOS cohort
  * by this value. Only one backend ships in this module today.
@@ -68,8 +70,8 @@ const KIND_SHELLOUT = 'macos-keychain-shellout';
  * Test seams and smoke tests can override either field via the
  * `MacosKek` constructor without touching this canonical pair.
  */
-const KEYCHAIN_SERVICE = 'ai.skrr.daemon.kek';
-const KEYCHAIN_ACCOUNT = 'master-kek-v1';
+const KEYCHAIN_SERVICE = MASTER_KEK_KEYCHAIN_SERVICE;
+const KEYCHAIN_ACCOUNT = MASTER_KEK_KEYCHAIN_ACCOUNT;
 /** `security` exit code when the requested item does not exist. */
 const SECURITY_ITEM_NOT_FOUND = 44;
 const execFileAsync = promisify(execFile);
@@ -294,6 +296,15 @@ async function writeKekToKeychain(kek, service, account) {
     if (keychainPath === null) {
         throw new KekUnavailableError(KIND_SHELLOUT, 'no user login keychain resolvable; cannot write master KEK');
     }
+    // A test that injected a fake `security` writes nothing real. One that did not is about to add
+    // an item to the keychain it just resolved, and the master KEK is the one item that cannot be
+    // recreated. A keychain that is not the account's (a throwaway file, or one a faked `security`
+    // names) cannot hold the installed product's KEK, so only the account's is protected.
+    if (_execFileForTest === null) {
+        assertMayMutateLiveKeychain(service, `add the Keychain item ${account} (a master KEK)`, {
+            keychainFile: keychainPath,
+        });
+    }
     const b64 = kek.toString('base64');
     try {
         await exec('security', [
@@ -323,6 +334,12 @@ async function writeKekToKeychain(kek, service, account) {
         });
     }
 }
+/**
+ * @internal Test seam — the Keychain write on its own, so a spec can reach the live-state
+ * guard without `wrap()`'s `security` probe getting in the way. A spec using it empties `PATH`,
+ * so that a guard which stopped firing reaches no `security` binary.
+ */
+export const __writeKekToKeychainForTest = writeKekToKeychain;
 /**
  * In-process cache of master KEKs, keyed by `${service}::${account}` so
  * multiple `MacosKek` instances scoped to different keychain entries
@@ -409,6 +426,7 @@ async function resolveOrCreateKek(service, account) {
             // A concurrent creator may have won. Only a successful read of its
             // existing item makes the failed create recoverable; all other errors
             // remain failures and must not cause an update or a second write.
+            rethrowIfLiveStateRefusal(error);
             const winner = await readKekFromKeychain(service, account).catch(() => null);
             if (!winner)
                 throw error;
@@ -546,6 +564,9 @@ export class MacosKek {
         catch (err) {
             if (err instanceof KekUnavailableError)
                 throw err;
+            // A refusal is not "the KEK is unavailable": wrapping it would let the credential
+            // envelope read a test aimed at the real Keychain as a locked one and carry on.
+            rethrowIfLiveStateRefusal(err);
             throw new KekUnavailableError(this.id, err?.message ?? 'shellout wrap failed', {
                 cause: err,
             });

package/dist/node_modules/@skrr-ai/auth-core/dist/esm/kek/masterKekService.d.ts

@@ -0,0 +1,69 @@
+/**
+ * kek/masterKekService.ts — the one place that names the machine-wide master KEK.
+ *
+ * The master KEK is ONE keychain item shared by every profile on the machine
+ * (`service=ai.skrr.daemon.kek`, `account=master-kek-v1`). Each profile's
+ * `cred-dek-wrapped` is sealed under it, and everything a profile stores — its
+ * tokens, its BYOK keys, its device private key — is sealed under that DEK.
+ * Deleting this one item therefore orphans every credential envelope on the
+ * machine at once, and nothing can bring it back: the key is random.
+ *
+ * It was deleted by accident on 2026-10-29. The desktop app's sign-out purge
+ * enumerates every service matching `ai.(skrr|oversky).daemon*` and drains each
+ * one, because that prefix used to hold only per-profile credential slots. The
+ * KEK moved under the same prefix without the purge being told, so a routine
+ * "your saved session was rejected" at app launch deleted it. The next daemon
+ * start could not open the DEK, treated that as a rotation, enrolled a new one,
+ * and the device private key sealed under the old DEK was gone for good — which
+ * the server then saw as `DEVICE_PROOF_MISSING` on every CLI hand-off.
+ *
+ * The fix first written for it was a denylist on a wildcard: the sweep kept
+ * matching everything under `ai.(skrr|oversky).daemon*` and skipped the services
+ * it knew to be precious. That fails open. The default for a service added under
+ * that prefix tomorrow was "deleted", which is how the KEK went, and how the
+ * person's own BYOK keys were being swept as well.
+ *
+ * So this module names what a sweep may delete, not what it may not. Every
+ * service in the daemon's Keychain namespace is in exactly one class
+ * (`classifyDaemonKeychainService`), and a sign-out selects with
+ * `isSessionKeychainService`: a service nobody has classified is LEFT IN PLACE.
+ * Deleting the KEK is a decision a caller makes by name, never a side effect of
+ * a sweep.
+ */
+/** Keychain `service` of the master KEK. */
+export declare const MASTER_KEK_KEYCHAIN_SERVICE = "ai.skrr.daemon.kek";
+/** Keychain `account` of the master KEK. */
+export declare const MASTER_KEK_KEYCHAIN_ACCOUNT = "master-kek-v1";
+/** Whether a keychain service name holds master-KEK material. */
+export declare function isMasterKekKeychainService(service: string): boolean;
+/** Whether a keychain service name holds a secret the person supplied, not a session. */
+export declare function isUserOwnedSecretKeychainService(service: string): boolean;
+/**
+ * Which kind of thing a service in the daemon's Keychain namespace holds. Exactly
+ * one, and the order of the checks in `classifyDaemonKeychainService` is what makes
+ * that true.
+ *
+ *   `master_kek`    key material every profile's envelope is sealed under. No sweep
+ *                   deletes it; a caller that must does so by name.
+ *   `user_secret`   what the person typed in (BYOK provider keys). A sign-out keeps
+ *                   it; a full uninstall removes it.
+ *   `session`       a profile's sign-in. A sign-out removes it.
+ *   `unclassified`  none of the above. Left in place, and reported, so that the next
+ *                   engineer who adds a service has to decide what it is.
+ */
+export type DaemonKeychainServiceClass = 'master_kek' | 'user_secret' | 'session' | 'unclassified';
+/**
+ * Classify one Keychain `service` name. The named non-members are asked FIRST: a
+ * profile may legally be called `byok.work` or `kek.x`, and its service then has
+ * the session shape AND the shape of the namespace it collides with. Reading it as
+ * the protected class is the safe direction (a sign-out leaves that profile's slots
+ * in place), so the protected classes win.
+ */
+export declare function classifyDaemonKeychainService(service: string): DaemonKeychainServiceClass;
+/**
+ * Whether a sign-out owns this service. This is the ONE predicate a sign-out sweep
+ * selects with (`services.filter(isSessionKeychainService)`): it names what is
+ * deleted, not what is spared. An uninstall adds `isUserOwnedSecretKeychainService`
+ * to it; no sweep adds the KEK.
+ */
+export declare function isSessionKeychainService(service: string): boolean;

package/dist/node_modules/@skrr-ai/auth-core/dist/esm/kek/masterKekService.js

@@ -0,0 +1,134 @@
+/**
+ * kek/masterKekService.ts — the one place that names the machine-wide master KEK.
+ *
+ * The master KEK is ONE keychain item shared by every profile on the machine
+ * (`service=ai.skrr.daemon.kek`, `account=master-kek-v1`). Each profile's
+ * `cred-dek-wrapped` is sealed under it, and everything a profile stores — its
+ * tokens, its BYOK keys, its device private key — is sealed under that DEK.
+ * Deleting this one item therefore orphans every credential envelope on the
+ * machine at once, and nothing can bring it back: the key is random.
+ *
+ * It was deleted by accident on 2026-10-29. The desktop app's sign-out purge
+ * enumerates every service matching `ai.(skrr|oversky).daemon*` and drains each
+ * one, because that prefix used to hold only per-profile credential slots. The
+ * KEK moved under the same prefix without the purge being told, so a routine
+ * "your saved session was rejected" at app launch deleted it. The next daemon
+ * start could not open the DEK, treated that as a rotation, enrolled a new one,
+ * and the device private key sealed under the old DEK was gone for good — which
+ * the server then saw as `DEVICE_PROOF_MISSING` on every CLI hand-off.
+ *
+ * The fix first written for it was a denylist on a wildcard: the sweep kept
+ * matching everything under `ai.(skrr|oversky).daemon*` and skipped the services
+ * it knew to be precious. That fails open. The default for a service added under
+ * that prefix tomorrow was "deleted", which is how the KEK went, and how the
+ * person's own BYOK keys were being swept as well.
+ *
+ * So this module names what a sweep may delete, not what it may not. Every
+ * service in the daemon's Keychain namespace is in exactly one class
+ * (`classifyDaemonKeychainService`), and a sign-out selects with
+ * `isSessionKeychainService`: a service nobody has classified is LEFT IN PLACE.
+ * Deleting the KEK is a decision a caller makes by name, never a side effect of
+ * a sweep.
+ */
+/** Keychain `service` of the master KEK. */
+export const MASTER_KEK_KEYCHAIN_SERVICE = 'ai.skrr.daemon.kek';
+/** Keychain `account` of the master KEK. */
+export const MASTER_KEK_KEYCHAIN_ACCOUNT = 'master-kek-v1';
+/**
+ * The master KEK under the current brand and the two names before the rename
+ * (`ai.oversky.daemon.kek`, and `com.oversky.daemon.kek`, which was the very first
+ * KEK identifier: see `LEGACY_NATIVE_ID_PREFIXES`), plus anything namespaced
+ * beneath any of them (`…kek.probe`, the Linux Secret Service probe). The
+ * pre-rename items are protected too: leaving a dead item behind costs bytes, and
+ * deleting key material is the one step that cannot be taken back.
+ */
+const MASTER_KEK_SERVICE_PATTERN = /^(?:ai\.(?:skrr|oversky)|com\.oversky)\.daemon\.kek(?:\..*)?$/;
+/** Whether a keychain service name holds master-KEK material. */
+export function isMasterKekKeychainService(service) {
+    return typeof service === 'string' && MASTER_KEK_SERVICE_PATTERN.test(service);
+}
+/**
+ * The person's own secrets, kept under the same `ai.*.daemon.` prefix: local BYOK provider keys
+ * (`ai.skrr.daemon.byok.<profile>-<suffix>`, written by `skrr daemon byok set`).
+ *
+ * They are not part of a session, and they are not key material either. They have their own
+ * lifecycle (`byok set`, `byok remove`), so a sign-out, above all one triggered by a server that
+ * rejected the saved session, must not delete them: that is the person's data, typed in once, and
+ * the sign-out that took it never asked. Only a full uninstall removes them: it adds this
+ * predicate to `isSessionKeychainService`, and no other sweep selects these services.
+ */
+const USER_OWNED_SECRET_SERVICE_PATTERN = /^ai\.(?:skrr|oversky)\.daemon\.byok(?:\..*)?$/;
+/** Whether a keychain service name holds a secret the person supplied, not a session. */
+export function isUserOwnedSecretKeychainService(service) {
+    return typeof service === 'string' && USER_OWNED_SECRET_SERVICE_PATTERN.test(service);
+}
+// ---------------------------------------------------------------------------
+// What a sign-out OWNS
+// ---------------------------------------------------------------------------
+/**
+ * A profile name as the daemon accepts it: `VALID_PROFILE_RE` in
+ * `daemon/src/profile.ts` (letters, digits, dot, dash, underscore; starts with a
+ * letter or digit; 64 characters at most). Dots are allowed, which is why the
+ * session grammar below cannot be told apart from the KEK or BYOK namespaces by
+ * its shape alone, and why the classifier asks those two first.
+ */
+const PROFILE_NAME = '[A-Za-z0-9][A-Za-z0-9._-]{0,63}';
+/**
+ * The config-dir suffix every current service carries: the first eight hex
+ * characters of sha256 of the profile's config dir (`configDirSuffix` in
+ * `daemon/src/keychain.ts`, mirrored by the desktop supervisor).
+ */
+const CONFIG_DIR_HASH = '-[a-f0-9]{8}';
+/**
+ * The session grammar: the services one profile's sign-in lives in, which are the
+ * ones a sign-out is for. It is POSITIVE and deliberately narrow.
+ *
+ *   ai.skrr.daemon.<profile>-<hash8>
+ *       The current layout, written by the daemon and the desktop supervisor
+ *       (`computeKeychainServiceForProfile`, and `machine-dek.ts`). The hash is
+ *       REQUIRED. `ai.skrr.daemon.<profile>` with no hash is the same shape as the
+ *       KEK (`ai.skrr.daemon.kek`, a "profile" called kek), and no current code
+ *       writes one, so a name of that shape is not a session: it is unclassified.
+ *
+ *   ai.oversky.daemon[.<profile>[-<hash8>]]
+ *       The three shapes the retired brand left on machines carried through the
+ *       rename: the pre-Phase-K bare service, the per-profile service, and the
+ *       per-profile service with the config-dir hash. The brand is retired, so this
+ *       set is closed: nothing new is ever written under it. A sign-out still has to
+ *       clear them, or a person who signed out keeps a live refresh token in the
+ *       Keychain.
+ *
+ * Anything else, including a service added under `ai.skrr.daemon` tomorrow, is not
+ * matched here, and a sweep that selects with this leaves it alone.
+ */
+const SESSION_SERVICE_PATTERNS = [
+    new RegExp(`^ai\\.skrr\\.daemon\\.${PROFILE_NAME}${CONFIG_DIR_HASH}$`),
+    new RegExp(`^ai\\.oversky\\.daemon(?:\\.${PROFILE_NAME}(?:${CONFIG_DIR_HASH})?)?$`),
+];
+/**
+ * Classify one Keychain `service` name. The named non-members are asked FIRST: a
+ * profile may legally be called `byok.work` or `kek.x`, and its service then has
+ * the session shape AND the shape of the namespace it collides with. Reading it as
+ * the protected class is the safe direction (a sign-out leaves that profile's slots
+ * in place), so the protected classes win.
+ */
+export function classifyDaemonKeychainService(service) {
+    if (typeof service !== 'string')
+        return 'unclassified';
+    if (isMasterKekKeychainService(service))
+        return 'master_kek';
+    if (isUserOwnedSecretKeychainService(service))
+        return 'user_secret';
+    if (SESSION_SERVICE_PATTERNS.some((pattern) => pattern.test(service)))
+        return 'session';
+    return 'unclassified';
+}
+/**
+ * Whether a sign-out owns this service. This is the ONE predicate a sign-out sweep
+ * selects with (`services.filter(isSessionKeychainService)`): it names what is
+ * deleted, not what is spared. An uninstall adds `isUserOwnedSecretKeychainService`
+ * to it; no sweep adds the KEK.
+ */
+export function isSessionKeychainService(service) {
+    return classifyDaemonKeychainService(service) === 'session';
+}

package/dist/node_modules/@skrr-ai/auth-core/dist/esm/liveState.d.ts

@@ -0,0 +1,154 @@
+import { CONFIG_DIR_NAME } from './localIdentity.js';
+/** Directory name of the state root inside a home directory. */
+export { CONFIG_DIR_NAME };
+/** Opt-in for a deliberate check against the machine's real state. */
+export declare const ALLOW_LIVE_STATE_ENV = "SKRR_TEST_ALLOW_LIVE_STATE";
+/** Set by every hermetic runner to the throwaway home it gave the process. */
+export declare const HERMETIC_HOME_ENV = "SKRR_TEST_HERMETIC_HOME";
+/** `LiveStateRefusedError.code`. Kept at its pre-consolidation value: scripts match on it. */
+export declare const LIVE_STATE_REFUSED_CODE = "SKRR_TEST_LIVE_STATE";
+/**
+ * Which signal says this is a test process, or `null`. The text names the signal so a false
+ * positive (a shell that exports `NODE_ENV=test`) diagnoses itself.
+ *
+ * `NODE_TEST_CONTEXT` is set by `node --test` in every file's child process and inherited by
+ * anything a test spawns. `--test` in `execArgv` covers `--test-isolation=none`, where tests run
+ * in the runner itself. A test file run DIRECTLY (`node file.test.ts`) has neither: node:test
+ * sets no marker for it, so the entry script's name is the only evidence. `JEST_WORKER_ID` is
+ * set in the real environment of every jest worker (and by `--runInBand`), so a child a spec
+ * spawns without `env` still carries it. `NODE_ENV=test` is what jest, vitest and `bun test`
+ * default to, and what custom scripts set by hand.
+ *
+ * `argv` is the process's own only when `env` is: a caller describing a hypothetical process
+ * (`{}`) describes all of it.
+ */
+export declare function testProcessSignal(env?: NodeJS.ProcessEnv, execArgv?: readonly string[], argv?: readonly string[]): string | null;
+/** Is this a test process? See `testProcessSignal` for what counts. */
+export declare function isTestProcess(env?: NodeJS.ProcessEnv, execArgv?: readonly string[], argv?: readonly string[]): boolean;
+/** Should a test process be refused access to the machine's real state? */
+export declare function refusesLiveStateInTest(env?: NodeJS.ProcessEnv, execArgv?: readonly string[], argv?: readonly string[]): boolean;
+/**
+ * The account's home directory from the user database. A test that points `HOME` somewhere else
+ * cannot move it, which is the point: it names where the INSTALLED product keeps its state,
+ * whatever this process believes.
+ *
+ * Node's `os.userInfo().homedir` reads the user database. Bun's returns `$HOME`, which is
+ * exactly what a test moves, so the compiled daemon asks the database itself — without that, a
+ * compiled binary spawned by a test with its own `HOME` saw that home as the live one and
+ * refused to start. `null` when it cannot be determined.
+ */
+export declare function accountHomeDir(): string | null;
+/**
+ * @internal Test seam — make `accountHomeDir()` answer `home` (`null`: "cannot be determined"),
+ * or restore the user-database lookup with `undefined`. It lets a spec stand a THROWAWAY
+ * directory in for the account's real home, so the guard can be exercised end to end — and its
+ * refusal removed, to prove the spec notices — without any path ever touching the real one.
+ * Never called from production code; `stateFileBoundary.spec.ts` fails if it is.
+ */
+export declare function __setAccountHomeForTest(home: string | null | undefined): void;
+/** The state root of the product installed for this account, when it can be known. */
+export declare function liveStateRoot(home?: string | null): string | null;
+/**
+ * What a guard decision is made against. Everything defaults to the running process; a spec
+ * injects a throwaway directory as `realHome` to prove the guard fires WITHOUT going near the
+ * machine's actual home.
+ */
+export interface LiveStateProbe {
+    env?: NodeJS.ProcessEnv;
+    execArgv?: readonly string[];
+    argv?: readonly string[];
+    /** The account's real home. `null` means "cannot be determined". Default: the user database. */
+    realHome?: string | null;
+}
+export declare class LiveStateRefusedError extends Error {
+    readonly code = "SKRR_TEST_LIVE_STATE";
+    /** What the mutation was aimed at: a path, or a Keychain service. */
+    readonly target: string;
+    /** Why this process was taken for a test. */
+    readonly signal: string;
+    constructor(what: string, target: string, signal: string, why: string, hint?: string);
+}
+/**
+ * Is `err` a live-state refusal? By name and code as well as by class: auth-core ships as both
+ * ESM and CJS, and two copies of it in one process (a farmed worktree) have two classes.
+ */
+export declare function isLiveStateRefusal(err: unknown): err is LiveStateRefusedError;
+/**
+ * First line of any `catch` that wraps a guarded mutation. A refusal swallowed into a telemetry
+ * event is a write that silently did not happen under a test that reports green, which is the
+ * "everything reads healthy" shape this repo has paid for before. A no-op outside a test
+ * process, where no refusal is ever constructed.
+ */
+export declare function rethrowIfLiveStateRefusal(err: unknown): void;
+/**
+ * Throw `LiveStateRefusedError` when a test process is about to mutate `target`, a path under
+ * the account's real home. Returns without reading anything else outside a test process.
+ *
+ * `what` completes "Refusing to …" (`replace the wrapped DEK`). `hint` replaces the default
+ * advice about how to run the test safely.
+ */
+export declare function assertMayMutateLiveState(target: string, what: string, probe?: LiveStateProbe, hint?: string): void;
+/** Service name prefix of the daemon's credential slots; always followed by `.<profile>`. */
+export declare const DAEMON_KEYCHAIN_SERVICE_BASE = "ai.skrr.daemon";
+/**
+ * Separate Keychain service for local BYOK secrets.
+ *
+ * Keeping provider keys out of the daemon-auth service prevents a broad "export daemon
+ * credentials" operation from accidentally including them and lets the user remove a provider
+ * key without disturbing their login.
+ */
+export declare const DAEMON_BYOK_KEYCHAIN_SERVICE_BASE = "ai.skrr.daemon.byok";
+/**
+ * The PRE-RENAME, pre-Phase-K service name. Read ONLY by the daemon's migration helper.
+ *
+ * It must NOT equal `DAEMON_KEYCHAIN_SERVICE_BASE`, and it held that value until a fix: the
+ * skrr rename swept the string like any other, and the two became identical. Nothing failed,
+ * because the failure is an absence — `migrateLegacyServiceToProfile` read a service nothing had
+ * ever written, found no slots, and reported success. Pre-rename credentials stayed where they
+ * were and the user silently re-authenticated. Written as a literal on purpose.
+ */
+export declare const LEGACY_DAEMON_KEYCHAIN_SERVICE = "ai.oversky.daemon";
+/** The profile the installed daemon runs when nothing selects another. */
+export declare const LIVE_DEFAULT_PROFILE = "default";
+/**
+ * `-<sha256(dir)[0:8]>`, the suffix of every per-profile Keychain service name. The input is the
+ * absolute, trailing-slash-stripped config directory, so two OS users running the daemon under
+ * their own `~/.skrr/` get distinct names and cannot read each other's tokens.
+ */
+export declare function keychainSuffixForDir(dir: string): string;
+/**
+ * Keychain services that belong to the product installed on this machine: the master KEK
+ * (current brand and the ones before it), the default profile's credential and BYOK slots under
+ * the account's real home, and the legacy names the daemon migrates from on start — a write to
+ * one of those is adopted by the next restart instead of the next read.
+ *
+ * The per-profile names are derived from the ACCOUNT's home, which no `HOME` override can reach.
+ * When the home is unknown only the names that need no home are returned; see
+ * `isLiveKeychainService` for what is done about the rest.
+ */
+export declare function liveKeychainServices(probe?: Pick<LiveStateProbe, 'realHome'>): ReadonlySet<string>;
+/**
+ * Does `service` name an item of the installed product? When the real home is unknown, a
+ * default-profile slot with a hash suffix is assumed live: its hash cannot be checked, and the
+ * guard fails closed.
+ */
+export declare function isLiveKeychainService(service: string, probe?: Pick<LiveStateProbe, 'realHome'>): boolean;
+/** Would a mutation of Keychain `service` be refused in a process with this shape? */
+export declare function refusesLiveKeychainMutation(service: string, probe?: LiveStateProbe): boolean;
+/** What a Keychain guard decision is made against. */
+export interface LiveKeychainProbe extends LiveStateProbe {
+    /**
+     * The keychain FILE the write is aimed at, when the caller knows it (macOS passes the login
+     * keychain it resolved). A keychain outside the real home is not the account's, so nothing
+     * the installed product reads can be in it, whatever the service is called: a throwaway
+     * keychain file, or a fake `security` that answers with a path of its own. Without it, the
+     * service name alone decides.
+     */
+    keychainFile?: string;
+}
+/**
+ * Throw `LiveStateRefusedError` when a test process is about to write or delete an item in a
+ * Keychain service the installed product reads. Callers that can be handed a fake `security`
+ * binary call this only when the real one would run: a mocked write touches nothing.
+ */
+export declare function assertMayMutateLiveKeychain(service: string, what: string, probe?: LiveKeychainProbe, hint?: string): void;