@centient/secrets 0.9.0 → 0.10.0

package/dist/crypto/darwin-keychain.js

@@ -0,0 +1,793 @@
+/**
+ * Hardened macOS Keychain core (#188).
+ *
+ * ## The defect this module exists to end
+ *
+ * Every `security` invocation in this package used to be wrong in the same two
+ * ways, and both ways only bite in a context that cannot complain:
+ *
+ *   1. **Writes preauthorized nothing.** `add-generic-password … -T ""` trusts
+ *      *no* application. An item written that way is readable only by granting
+ *      consent through a dialog — and a launchd daemon or an SSH login has no
+ *      UI in which such a dialog can render. The item is therefore unreadable
+ *      in exactly the contexts a credential store is for.
+ *   2. **Reads consulted the search list.** `find-generic-password` with no
+ *      keychain argument walks the session search list, which leads with the
+ *      login keychain. In a sessionless context that keychain is locked, and a
+ *      locked copy *shadows* a readable System-keychain copy — so the read
+ *      fails even though the credential is right there.
+ *
+ * Combined with the old accessors' habit of collapsing every failure into
+ * `null`, the result was a store that silently reported "nothing configured"
+ * to a headless reader. See issue #188 and `docs/threat-model.md`.
+ *
+ * ## The posture
+ *
+ *   1. **Session-aware reads.** An interactive session keeps its existing
+ *      search-list read (so vaults that open today keep opening unchanged). A
+ *      *sessionless* context reads the System keychain by **explicit
+ *      positional target** first — no search list, so nothing can shadow it —
+ *      and only consults the search list when the System keychain genuinely
+ *      has no copy. That ordering is what makes a misclassified context
+ *      harmless: the fallback can only ever add a result, never lose one.
+ *   2. **Preauthorized writes.** `-T /usr/bin/security` grants the reader path
+ *      at write time, on every write, everywhere in this package. Never
+ *      `-T ""`.
+ *   3. **`-U` replace-in-place.** A rotation is one command and never leaves
+ *      two generations of the same account. The old delete-then-add left a
+ *      window in which the credential existed nowhere.
+ *   4. **Discriminated results.** Reads, probes, writes, deletes and the
+ *      migration all answer with a discriminated union. `absent` and `locked`
+ *      are never merged (see {@link ../secret-state.js}).
+ *
+ * ## Never logs a value
+ *
+ * No function here logs or formats a credential into a diagnostic. Every
+ * `detail`/`reason`/`command` string is value-free by construction — the
+ * operator command reads the secret with `read -s` into a shell variable, so
+ * it appears in neither the printed text nor the shell history.
+ *
+ * ## Residual, stated rather than hidden
+ *
+ * A programmatic write passes the value in `argv` (`-w <value>`), briefly
+ * visible to a local `ps`. That is unchanged from this package's previous
+ * write path, so it is not a regression — but it is why the OPERATOR-facing
+ * command printed by {@link privilegedWriteCommand} keeps the value out of the
+ * command text entirely. `docs/threat-model.md` §4.3 tracks the argv exposure.
+ */
+import { execFileSync } from "child_process";
+import { detectSessionContext } from "../platform/session-context.js";
+// =============================================================================
+// Constants
+// =============================================================================
+/** The macOS system keychain — readable from the launchd system domain. */
+export const SYSTEM_KEYCHAIN_PATH = "/Library/Keychains/System.keychain";
+/**
+ * The reader path preauthorized on write (`-T`), and the binary this module
+ * spawns. Absolute deliberately: the `-T` argument names a path, so the two
+ * must be the same path or the grant does not describe the reader.
+ */
+export const SECURITY_BINARY = "/usr/bin/security";
+/** Cap on the bytes of a `security` diagnostic carried into a result. */
+const DETAIL_LIMIT = 200;
+function defaultRunSecurity(args, options = {}) {
+    try {
+        const stdout = execFileSync(SECURITY_BINARY, [...args], {
+            encoding: "utf8",
+            stdio: ["pipe", "pipe", "pipe"],
+            ...(options.maxBuffer !== undefined ? { maxBuffer: options.maxBuffer } : {}),
+        });
+        return { status: 0, stderr: "", stdout: stdout ?? "" };
+    }
+    catch (e) {
+        const err = e;
+        const status = typeof err.status === "number" ? err.status : -1;
+        const stderr = typeof err.stderr === "string"
+            ? err.stderr
+            : err.stderr !== undefined
+                ? err.stderr.toString("utf8")
+                : (err.message ?? "");
+        const stdout = typeof err.stdout === "string"
+            ? err.stdout
+            : err.stdout !== undefined
+                ? err.stdout.toString("utf8")
+                : "";
+        return { status, stderr, stdout };
+    }
+}
+/**
+ * Resolve the injected seam against the live process. Defaults are read on
+ * every call rather than captured at module load, so a caller that adjusts
+ * `process.platform` (several suites in this package do) is honoured.
+ */
+function resolveDeps(deps) {
+    return {
+        runSecurity: deps.runSecurity ?? defaultRunSecurity,
+        platform: deps.platform ?? process.platform,
+        env: deps.env ?? process.env,
+    };
+}
+// =============================================================================
+// Classification
+// =============================================================================
+function notApplicable(platform) {
+    return {
+        kind: "not-applicable",
+        reason: `platform ${platform} has no macOS keychain`,
+    };
+}
+/**
+ * Classify a `security` outcome.
+ *
+ * Stderr patterns are checked BEFORE exit codes on purpose: Apple has shifted
+ * `security` exit codes between releases while the user-facing strings have
+ * stayed stable, so pinning on the code alone silently reclassifies an
+ * unreadable item as a missing one on the next OS bump — the very collapse
+ * this module exists to prevent.
+ */
+export function classifyKeychainRead(status, stderr, stdout) {
+    const lower = stderr.toLowerCase();
+    if (lower.includes("interaction is not allowed") ||
+        lower.includes("interactionnotallowed") ||
+        lower.includes("user name or passphrase you entered is not correct")) {
+        return { kind: "locked" };
+    }
+    if (status === 51)
+        return { kind: "locked" };
+    if (status === 44)
+        return { kind: "absent" };
+    if (status === 0) {
+        // `-w` prints ONLY the password, newline-terminated. Strip that one
+        // newline and nothing else — a general `trim()` would silently mutate a
+        // credential whose leading or trailing whitespace is significant.
+        const value = stdout.replace(/\n$/, "");
+        // An empty value from a status-0 read is a corrupt item, not a credential.
+        // Returning it would hand the reader an empty token and look configured.
+        return value.length > 0
+            ? { kind: "found", value }
+            : {
+                kind: "failed",
+                detail: "security returned an empty value for an existing item",
+            };
+    }
+    const detail = stderr.trim().slice(0, DETAIL_LIMIT) || `security exited ${status}`;
+    return { kind: "failed", detail };
+}
+/** Drop the value from a read outcome, yielding the value-free state. */
+export function toSecretState(read) {
+    return read.kind === "found" ? { kind: "found" } : read;
+}
+/** True when the failure is "you are not allowed to write this keychain". */
+function isPrivilegeFailure(status, stderr) {
+    const lower = stderr.toLowerCase();
+    return (lower.includes("write permissions") ||
+        lower.includes("not permitted") ||
+        lower.includes("permission denied") ||
+        lower.includes("authorization") ||
+        // errSecWrPerm / errSecAuthFailed families observed on a non-root write.
+        status === 45 ||
+        status === 51);
+}
+// =============================================================================
+// Operator command construction
+// =============================================================================
+/**
+ * Shell-quote one argument for the copy/paste operator command.
+ *
+ * The service and account reach this from caller-supplied strings, so an
+ * unquoted interpolation turns a remediation command into a DIFFERENT command
+ * the moment one of them carries a shell metacharacter. Single-quote wrapping
+ * is the only form that neutralizes every metacharacter; an embedded single
+ * quote is closed, escaped and reopened (the POSIX `'\''` idiom).
+ */
+export function shellQuote(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+/**
+ * The operator command for a privileged System-keychain write.
+ *
+ * The command TEXT is value-free: the secret is read by `read -s` (silent, and
+ * present in both zsh and bash) into a shell variable, so it never appears in
+ * the printed command, in a log line, or in shell history — history records
+ * the literal `"$PW"`, not its expansion.
+ *
+ * Why not a `security` prompt form: `-w` consumes any following token as the
+ * password, so a trailing keychain path would silently BECOME the stored
+ * value, and the bare dangling `-w` form is not a reliable terminal prompt.
+ * The `read -s` flow sidesteps `security`'s prompt semantics entirely and
+ * RESTORES the explicit System-keychain positional target, so the write cannot
+ * land in the wrong keychain.
+ */
+export function privilegedWriteCommand(service, account) {
+    const write = [
+        "sudo",
+        SECURITY_BINARY,
+        "add-generic-password",
+        "-U",
+        "-s",
+        shellQuote(service),
+        "-a",
+        shellQuote(account),
+        "-T",
+        SECURITY_BINARY,
+        "-w",
+        '"$PW"',
+        SYSTEM_KEYCHAIN_PATH,
+    ].join(" ");
+    return [
+        `printf 'value for %s (input hidden): ' ${shellQuote(account)}`,
+        "IFS= read -rs PW",
+        `printf '\\n'`,
+        write,
+        "unset PW",
+    ].join(" && ");
+}
+// =============================================================================
+// Reads
+// =============================================================================
+function systemReadArgs(service, account) {
+    return [
+        "find-generic-password",
+        "-s",
+        service,
+        "-a",
+        account,
+        "-w",
+        SYSTEM_KEYCHAIN_PATH,
+    ];
+}
+function searchListReadArgs(service, account) {
+    return ["find-generic-password", "-s", service, "-a", account, "-w"];
+}
+/**
+ * Read one credential from the System keychain, addressing it EXPLICITLY.
+ *
+ * The trailing keychain path is the whole point: without it `security` walks
+ * the session search list, which in a sessionless context leads with the
+ * locked login keychain — so a stale login copy shadows the readable System
+ * one and the read fails in exactly the context that has no way to prompt.
+ */
+export function readSystemKeychainCredential(service, account, deps = {}) {
+    const { runSecurity, platform } = resolveDeps(deps);
+    if (platform !== "darwin")
+        return notApplicable(platform);
+    const { status, stderr, stdout } = runSecurity(systemReadArgs(service, account));
+    return classifyKeychainRead(status, stderr, stdout);
+}
+/**
+ * Read one credential through the session search list — the historical path,
+ * and still the right one in an interactive session where the login keychain
+ * is unlocked and is where the item lives.
+ */
+export function readSearchListCredential(service, account, deps = {}) {
+    const { runSecurity, platform } = resolveDeps(deps);
+    if (platform !== "darwin")
+        return notApplicable(platform);
+    const { status, stderr, stdout } = runSecurity(searchListReadArgs(service, account));
+    return classifyKeychainRead(status, stderr, stdout);
+}
+/**
+ * Read a credential using the path appropriate to THIS execution context.
+ *
+ * - Interactive session: the search-list read, byte-for-byte what this package
+ *   did before #188. Vaults that open today keep opening.
+ * - Sessionless (launchd system domain, SSH): the explicit System-keychain
+ *   read first, so no login copy can shadow it — then, only if the System
+ *   keychain genuinely has no such item, the search-list read.
+ *
+ * The fallback ordering is deliberate and load-bearing. Session detection is a
+ * heuristic (see `../platform/session-context.ts`); with System consulted
+ * first, a *false* sessionless verdict cannot lose a credential that used to
+ * be readable, and a false interactive verdict is no worse than today. The
+ * shadowing bug cannot come back either way, because the search list is only
+ * ever reached after the System keychain has answered `absent`.
+ */
+export function readKeychainCredential(service, account, deps = {}) {
+    const resolved = resolveDeps(deps);
+    if (resolved.platform !== "darwin")
+        return notApplicable(resolved.platform);
+    if (sessionContext(resolved).kind === "interactive") {
+        return readSearchListCredential(service, account, resolved);
+    }
+    const system = readSystemKeychainCredential(service, account, resolved);
+    if (system.kind !== "absent")
+        return system;
+    return readSearchListCredential(service, account, resolved);
+}
+function sessionContext(deps) {
+    return detectSessionContext({ platform: deps.platform, env: deps.env });
+}
+// =============================================================================
+// Probes (metadata only — no value reaches any stream)
+// =============================================================================
+/**
+ * **Presence, not readability.** Metadata-only existence probe against the
+ * System keychain.
+ *
+ * No `-w`, so `security` prints no value on any stream. That is also its
+ * limit: a `found` here means only that an item with these coordinates exists.
+ * An item can exist and still be unreadable — locked keychain, an ACL that
+ * does not preauthorize the reader, a partially written item — so this must
+ * NOT be used to answer "what is the state of this credential?". Reporting
+ * `found` for an item the reader cannot open is the exact failure mode #188
+ * exists to end.
+ *
+ * Its correct use is the non-destructive residency question inside
+ * {@link migrateLoginCredentialToSystem} ("is a copy already here, so that I
+ * need not move one?"), which is deliberately answered without reading the
+ * secret. Credential STATE is {@link probeKeychainCredentialState}.
+ */
+export function probeSystemKeychainEntry(service, account, deps = {}) {
+    const { runSecurity, platform } = resolveDeps(deps);
+    if (platform !== "darwin")
+        return notApplicable(platform);
+    const { status, stderr } = runSecurity([
+        "find-generic-password",
+        "-s",
+        service,
+        "-a",
+        account,
+        SYSTEM_KEYCHAIN_PATH,
+    ]);
+    if (status === 0)
+        return { kind: "found" };
+    return toSecretState(classifyKeychainRead(status, stderr, ""));
+}
+/**
+ * **Presence, not readability.** Metadata-only existence probe through the
+ * session search list. Same caveat as {@link probeSystemKeychainEntry}: use
+ * {@link probeKeychainCredentialState} for credential state.
+ */
+export function probeSearchListEntry(service, account, deps = {}) {
+    const { runSecurity, platform } = resolveDeps(deps);
+    if (platform !== "darwin")
+        return notApplicable(platform);
+    const { status, stderr } = runSecurity([
+        "find-generic-password",
+        "-s",
+        service,
+        "-a",
+        account,
+    ]);
+    if (status === 0)
+        return { kind: "found" };
+    return toSecretState(classifyKeychainRead(status, stderr, ""));
+}
+/**
+ * **Presence, not readability.** Metadata-only probe along the same keychain
+ * the reader would consult in this context.
+ *
+ * Same caveat as the two functions above, and for the same reason: a status-0
+ * metadata hit says an item exists, not that opening it yields bytes. Use
+ * {@link probeKeychainCredentialState} for credential state.
+ */
+export function probeKeychainEntry(service, account, deps = {}) {
+    const resolved = resolveDeps(deps);
+    if (resolved.platform !== "darwin")
+        return notApplicable(resolved.platform);
+    if (sessionContext(resolved).kind === "interactive") {
+        return probeSearchListEntry(service, account, resolved);
+    }
+    const system = probeSystemKeychainEntry(service, account, resolved);
+    if (system.kind !== "absent")
+        return system;
+    return probeSearchListEntry(service, account, resolved);
+}
+/**
+ * The credential STATE probe: what will the reader in THIS context actually
+ * get?
+ *
+ * Runs the real read — {@link readKeychainCredential}, the same path, the same
+ * explicit target, the same `-w` — and then **discards the value**, returning
+ * only the value-free {@link SecretState}. So `found` here means "the reader
+ * will get bytes", which is the claim a caller needs and the claim a metadata
+ * probe cannot make.
+ *
+ * Presence is not readability, and the gap between them is not hypothetical:
+ * an item whose ACL does not preauthorize the reader, or that sits in a locked
+ * keychain, or that was written empty, is *present* and *unreadable*. A probe
+ * that answered `found` for those would hand a caller trusted state that is
+ * wrong in precisely the direction #188 exists to fix — a reader told the
+ * credential is there, failing anyway, with no signal that says why.
+ *
+ * The trade is deliberate: this reads secret material into the process to
+ * answer, where {@link probeKeychainEntry} does not. Nothing leaves — the
+ * value never reaches a return value, a log, or a stream. Callers that must
+ * not read the secret at all (the migration's residency check) use the
+ * metadata probe under its own name, and accept that it answers a narrower
+ * question.
+ */
+export function probeKeychainCredentialState(service, account, deps = {}) {
+    return toSecretState(readKeychainCredential(service, account, deps));
+}
+// =============================================================================
+// Writes
+// =============================================================================
+/**
+ * Store a credential in the System keychain, preauthorized for the reader path.
+ *
+ * `-U` replaces an existing item in place (the rotation path, and the reason
+ * there is no delete-then-add window here); `-T` grants
+ * `/usr/bin/security` up front because no consent prompt can render in the
+ * launchd or SSH contexts that have to read it.
+ */
+export function writeSystemKeychainCredential(service, account, value, deps = {}) {
+    const { runSecurity, platform } = resolveDeps(deps);
+    if (platform !== "darwin")
+        return notApplicable(platform);
+    if (value.length === 0) {
+        return { kind: "failed", detail: "refusing to store an empty value" };
+    }
+    const { status, stderr } = runSecurity([
+        "add-generic-password",
+        "-U",
+        "-s",
+        service,
+        "-a",
+        account,
+        "-T",
+        SECURITY_BINARY,
+        "-w",
+        value,
+        SYSTEM_KEYCHAIN_PATH,
+    ]);
+    if (status === 0)
+        return { kind: "stored" };
+    if (isPrivilegeFailure(status, stderr)) {
+        return { kind: "needs-privilege", command: privilegedWriteCommand(service, account) };
+    }
+    return {
+        kind: "failed",
+        detail: stderr.trim().slice(0, DETAIL_LIMIT) || `security exited ${status}`,
+    };
+}
+/**
+ * Store a credential in the session's default (login) keychain — the
+ * historical destination — but with the two flags that were missing: `-U` so a
+ * rotation replaces in place, and `-T /usr/bin/security` so the item is
+ * readable without a consent dialog.
+ *
+ * A permission failure here is reported as `failed`, not `needs-privilege`:
+ * `sudo` is the wrong remedy for a login keychain (it would write root's), and
+ * offering it would send an operator down a path that cannot work.
+ */
+export function writeDefaultKeychainCredential(service, account, value, deps = {}) {
+    const { runSecurity, platform } = resolveDeps(deps);
+    if (platform !== "darwin")
+        return notApplicable(platform);
+    if (value.length === 0) {
+        return { kind: "failed", detail: "refusing to store an empty value" };
+    }
+    const { status, stderr } = runSecurity([
+        "add-generic-password",
+        "-U",
+        "-s",
+        service,
+        "-a",
+        account,
+        "-T",
+        SECURITY_BINARY,
+        "-w",
+        value,
+    ]);
+    if (status === 0)
+        return { kind: "stored" };
+    return {
+        kind: "failed",
+        detail: stderr.trim().slice(0, DETAIL_LIMIT) || `security exited ${status}`,
+    };
+}
+/**
+ * Store a credential using the destination appropriate to THIS context.
+ *
+ * - Interactive: the default (login) keychain, unchanged destination, now with
+ *   `-U` and `-T`.
+ * - Sessionless: the System keychain, so the reader that has no session can
+ *   actually open it. If that write needs privileges the credential is still
+ *   written to the default keychain rather than failing outright — but the
+ *   result says so (`keychain`) and carries the value-free command that
+ *   promotes it (`privilegedCommand`). Reporting the lesser destination is
+ *   what keeps this from being a silent downgrade.
+ */
+export function writeKeychainCredential(service, account, value, deps = {}) {
+    const resolved = resolveDeps(deps);
+    if (resolved.platform !== "darwin")
+        return notApplicable(resolved.platform);
+    if (value.length === 0) {
+        return { kind: "failed", detail: "refusing to store an empty value" };
+    }
+    if (sessionContext(resolved).kind === "interactive") {
+        const written = writeDefaultKeychainCredential(service, account, value, resolved);
+        return written.kind === "stored" ? { kind: "stored", keychain: "default" } : written;
+    }
+    const system = writeSystemKeychainCredential(service, account, value, resolved);
+    if (system.kind === "stored") {
+        return { kind: "stored", keychain: SYSTEM_KEYCHAIN_PATH };
+    }
+    if (system.kind !== "needs-privilege")
+        return system;
+    const fallback = writeDefaultKeychainCredential(service, account, value, resolved);
+    if (fallback.kind !== "stored")
+        return system;
+    return {
+        kind: "stored",
+        keychain: "default",
+        privilegedCommand: system.command,
+    };
+}
+/**
+ * Did a write land where THIS context's reader will look for it?
+ *
+ * `kind: "stored"` alone does not answer that. In a sessionless context a
+ * System-keychain write that needs privileges falls back to the default
+ * keychain — the value is stored, and the result says so and carries the
+ * command that promotes it, but a launchd or SSH reader will not find it
+ * there. A boolean caller that treated that as success would record a write
+ * the reader cannot see: a silent downgrade, which is the same class of lie as
+ * the read-side collapse this module exists to fix.
+ *
+ * So: interactive → the default keychain IS where the reader looks, so any
+ * `stored` is reachable. Sessionless → only the System keychain is.
+ *
+ * Callers that want the nuance rather than the boolean use the discriminated
+ * {@link KeychainWriteResult} directly; it carries both the destination and
+ * the value-free promotion command.
+ */
+export function storedWithinReaderReach(result, deps = {}) {
+    if (result.kind !== "stored")
+        return false;
+    const resolved = resolveDeps(deps);
+    if (sessionContext(resolved).kind === "interactive")
+        return true;
+    return result.keychain === SYSTEM_KEYCHAIN_PATH;
+}
+// =============================================================================
+// Deletes
+// =============================================================================
+function classifyDelete(status, stderr) {
+    if (status === 0)
+        return { kind: "deleted" };
+    if (status === 44)
+        return { kind: "absent" };
+    const lower = stderr.toLowerCase();
+    if (lower.includes("could not be found") || lower.includes("the specified item could not be found")) {
+        return { kind: "absent" };
+    }
+    return {
+        kind: "failed",
+        detail: stderr.trim().slice(0, DETAIL_LIMIT) || `security exited ${status}`,
+    };
+}
+/**
+ * Resolve the LOGIN keychain's path (`security login-keychain`) so a delete can
+ * be aimed at it explicitly. `null` when it cannot be resolved — and that
+ * `null` is load-bearing: the caller then SKIPS the delete rather than running
+ * an untargeted one.
+ */
+function resolveLoginKeychainPath(runSecurity) {
+    const { status, stdout } = runSecurity(["login-keychain"]);
+    if (status !== 0)
+        return null;
+    const resolved = stdout.trim().replace(/^"|"$/g, "");
+    if (resolved.length === 0)
+        return null;
+    // Never treat the System keychain as the login keychain, however we got here
+    // — the entire purpose of this resolution is to keep a delete off it.
+    if (resolved === SYSTEM_KEYCHAIN_PATH)
+        return null;
+    return resolved;
+}
+/**
+ * Delete the LOGIN-keychain copy of an account — TARGETED at the login
+ * keychain, never resolved through the search list.
+ *
+ * An untargeted `delete-generic-password -s <svc> -a <acct>` resolves through
+ * the user search list, which commonly INCLUDES
+ * `/Library/Keychains/System.keychain`. On a host with no login shadow such a
+ * delete matches the System item and removes the credential just verified,
+ * turning a cleanup into the outage it exists to prevent.
+ *
+ * Two guards: the delete names the login keychain explicitly, and when that
+ * path cannot be resolved the delete is SKIPPED. An unswept login shadow is a
+ * degraded state the caller reports; a deleted System credential is an outage.
+ */
+function deleteLoginCopy(service, account, runSecurity) {
+    const loginKeychain = resolveLoginKeychainPath(runSecurity);
+    if (loginKeychain === null)
+        return false;
+    const { status } = runSecurity([
+        "delete-generic-password",
+        "-s",
+        service,
+        "-a",
+        account,
+        loginKeychain,
+    ]);
+    return status === 0;
+}
+/**
+ * Delete a credential from wherever this context can read it.
+ *
+ * Interactive: the historical default-destination delete, unchanged.
+ *
+ * Sessionless: both copies the read path can see — the System copy (explicit
+ * target) and the login copy (targeted through `login-keychain`, skipped when
+ * unresolvable). Deleting only one would leave the other to be resurrected by
+ * the very fallback that makes sessionless reads work.
+ */
+export function deleteKeychainCredential(service, account, deps = {}) {
+    const resolved = resolveDeps(deps);
+    const { runSecurity, platform } = resolved;
+    if (platform !== "darwin")
+        return notApplicable(platform);
+    if (sessionContext(resolved).kind === "interactive") {
+        const { status, stderr } = runSecurity([
+            "delete-generic-password",
+            "-s",
+            service,
+            "-a",
+            account,
+        ]);
+        return classifyDelete(status, stderr);
+    }
+    const system = runSecurity([
+        "delete-generic-password",
+        "-s",
+        service,
+        "-a",
+        account,
+        SYSTEM_KEYCHAIN_PATH,
+    ]);
+    const systemResult = classifyDelete(system.status, system.stderr);
+    const loginDeleted = deleteLoginCopy(service, account, runSecurity);
+    if (systemResult.kind === "failed")
+        return systemResult;
+    if (systemResult.kind === "deleted" || loginDeleted)
+        return { kind: "deleted" };
+    return { kind: "absent" };
+}
+// =============================================================================
+// Migration
+// =============================================================================
+/**
+ * The pre-delete gate: is the System copy READABLE through the exact path a
+ * sessionless reader uses?
+ *
+ * Presence is NOT readability. An item can exist and still be unreadable —
+ * locked keychain, an ACL that does not preauthorize the reader, a partially
+ * written item — so gating the delete on the metadata probe could green-light
+ * removing a working login fallback and leave a daemon credential-blind. Only
+ * a `found` from the FULL read proves bytes come back. The metadata probe
+ * remains for NON-destructive presence checks only.
+ */
+function systemCopyIsReadable(service, account, deps) {
+    return readSystemKeychainCredential(service, account, deps).kind === "found";
+}
+/**
+ * Move one credential from the login keychain to the System keychain, ONCE,
+ * then remove the login copy so nothing can shadow it.
+ *
+ * Idempotent: a System copy that already exists short-circuits to
+ * `already-resident` (and still sweeps a login shadow if one is left).
+ *
+ * Fail-loud-but-SAFE ordering — the login copy is deleted LAST, and only after
+ * the System copy is verified readable through the explicit-target read. Every
+ * earlier failure returns `blocked` with the login copy intact, so the previous
+ * read path keeps working: a failed migration can never produce "reader up with
+ * no credential".
+ */
+export function migrateLoginCredentialToSystem(service, account, deps = {}) {
+    const resolved = resolveDeps(deps);
+    const { runSecurity, platform } = resolved;
+    if (platform !== "darwin") {
+        return { kind: "blocked", reason: `platform ${platform} has no macOS keychain` };
+    }
+    // Already resident? Probe metadata only — no need to read the secret to
+    // answer this, and not reading it keeps the idempotent path value-free.
+    const resident = probeSystemKeychainEntry(service, account, resolved);
+    if (resident.kind === "found") {
+        // Presence is not readability. Sweep the login shadow ONLY when the System
+        // copy actually yields bytes through the reader's own path — otherwise the
+        // login copy IS the working credential and deleting it blinds the reader.
+        if (!systemCopyIsReadable(service, account, resolved)) {
+            return {
+                kind: "blocked",
+                reason: "a System-keychain item exists but is NOT readable (locked, or its ACL does not preauthorize the reader); the login copy has been LEFT IN PLACE",
+            };
+        }
+        const deleted = deleteLoginCopy(service, account, runSecurity);
+        return { kind: "already-resident", loginCopyDeleted: deleted };
+    }
+    if (resident.kind === "locked") {
+        return {
+            kind: "blocked",
+            reason: "the System keychain is locked; cannot determine whether the credential is resident",
+        };
+    }
+    // Read the login copy through the search list (that is where it lives).
+    const login = runSecurity(searchListReadArgs(service, account));
+    const loginRead = classifyKeychainRead(login.status, login.stderr, login.stdout);
+    if (loginRead.kind !== "found") {
+        return loginRead.kind === "absent"
+            ? { kind: "nothing-to-migrate" }
+            : {
+                kind: "blocked",
+                reason: loginRead.kind === "locked"
+                    ? "the login keychain is locked, so the source copy cannot be read (run this from an unlocked GUI session)"
+                    : loginRead.kind === "failed"
+                        ? `login-keychain read failed: ${loginRead.detail}`
+                        : loginRead.reason,
+            };
+    }
+    const written = writeSystemKeychainCredential(service, account, loginRead.value, resolved);
+    if (written.kind !== "stored") {
+        // Login copy untouched — the pre-migration read path is exactly as it was.
+        return written.kind === "needs-privilege"
+            ? {
+                kind: "blocked",
+                reason: "writing the System keychain requires root",
+                command: written.command,
+            }
+            : {
+                kind: "blocked",
+                reason: written.kind === "failed"
+                    ? `System-keychain write failed: ${written.detail}`
+                    : written.reason,
+            };
+    }
+    // Verify through the SAME explicit-target read a sessionless reader will use
+    // — a FULL read, not a metadata probe: an item can exist and still be
+    // unreadable, and the delete below is irreversible.
+    if (!systemCopyIsReadable(service, account, resolved)) {
+        return {
+            kind: "blocked",
+            reason: "the System copy was written but could not be verified; the login copy has been LEFT IN PLACE",
+        };
+    }
+    const deleted = deleteLoginCopy(service, account, runSecurity);
+    return { kind: "migrated", loginCopyDeleted: deleted };
+}
+// =============================================================================
+// Diagnostics
+// =============================================================================
+/**
+ * The keychain search list, for diagnostics. Names only — a search list
+ * carries no secret material, and knowing that the login keychain leads it is
+ * exactly what explains a shadowed read.
+ */
+export function keychainSearchList(deps = {}) {
+    const { runSecurity, platform } = resolveDeps(deps);
+    if (platform !== "darwin")
+        return [];
+    const { status, stdout } = runSecurity(["list-keychains", "-d", "user"]);
+    if (status !== 0)
+        return [];
+    return stdout
+        .split("\n")
+        .map((line) => line.trim().replace(/^"|"$/g, ""))
+        .filter((line) => line.length > 0);
+}
+/**
+ * Raw `security dump-keychain` output, for the enumeration path in
+ * `vault-common.ts`.
+ *
+ * Deliberately NOT platform-guarded: enumeration is only reachable when the
+ * Keychain backend is the active one, and guarding here would change a
+ * spawn-and-fail into a silent empty answer on a host whose platform string
+ * has been adjusted (several suites in this package do exactly that).
+ *
+ * `-d` is deliberately omitted, so no password data is in the output.
+ */
+export function dumpKeychain(deps = {}) {
+    const { runSecurity } = resolveDeps(deps);
+    const { status, stderr, stdout } = runSecurity(["dump-keychain"], {
+        maxBuffer: 32 * 1024 * 1024,
+    });
+    if (status === 0)
+        return { kind: "ok", output: stdout };
+    return {
+        kind: "failed",
+        detail: stderr.trim().slice(0, DETAIL_LIMIT) || `security exited ${status}`,
+    };
+}
+//# sourceMappingURL=darwin-keychain.js.map