@skrr-ai/auth-core 0.1.2

package/dist/esm/kek/macos.js

@@ -0,0 +1,586 @@
+/**
+ * kek/macos.ts — macOS KEK strategy.
+ *
+ * The macOS strategy is the `security(1)` shellout to the user's login
+ * Keychain. It stores a 32-byte master KEK under
+ * `service=ai.skrr.daemon.kek`, `account=master-kek-v1` and wraps the
+ * DEK with AES-256-GCM via the existing credential-envelope primitives.
+ * No native deps — matches `daemon/src/keychain.ts`'s project precedent
+ * of shelling out to `security` instead of linking a `.node` binding
+ * (which the bun-compiled daemon binary cannot consume). A future
+ * Secure-Enclave helper-binary path is tracked in the L12 ADR but is not
+ * part of this module.
+ *
+ * Threat model the shellout backend defends against:
+ *   - Cold-disk theft / Time Machine snapshots / restic backups: the
+ *     login keychain is encrypted at rest under the user's login.
+ *   - Same-UID file readers: the keychain is gated by the user's
+ *     authenticated session.
+ *
+ * Threat model the shellout backend does NOT defend against:
+ *   - Live-process memory access while the daemon is running.
+ *   - Root-equivalent malware that can `security unlock-keychain`.
+ *   - Hardware-bound non-extractable storage — that requires a future
+ *     Secure-Enclave helper-binary tracked separately.
+ *
+ * Explicit-keychain-targeting strategy: every `find-generic-password` and
+ * `add-generic-password` invocation passes the resolved login-keychain
+ * path as a trailing positional argument. Without that argument,
+ * `security(1)` falls back to "the default keychain in the current exec
+ * context" — and when that lookup fails (LaunchAgent without a GUI
+ * session, headless SSH, a user with no default keychain configured) it
+ * triggers a system-modal `Keychain Not Found` dialog that blocks the
+ * daemon process and offers a destructive `Reset To Defaults` action to
+ * the user. A daemon must NEVER block on UI. We resolve the path once
+ * up-front via `security default-keychain -d user` (with canonical-path
+ * fallbacks) and refuse to run if nothing resolves — `available()`
+ * returns false and the upstream credEnvelope reports
+ * `disabled.kek_unavailable` cleanly instead of hanging on a dialog.
+ *
+ * Service / account override: the constructor accepts an optional
+ * `{ service?, account? }` pair so callers can scope a `MacosKek`
+ * instance to a non-default keychain entry. The intended use cases are
+ * (a) multi-tenant tests that need parallel isolated KEKs in one
+ * process and (b) the real-keychain smoke test, which generates a
+ * unique service per run so it can `delete-generic-password` on
+ * teardown without touching the developer's actual master KEK. The
+ * production dispatcher in `kek/index.ts` passes nothing and gets the
+ * canonical `ai.skrr.daemon.kek` / `master-kek-v1` pair — that
+ * path is the only one fleet telemetry sizes against.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import crypto from 'node:crypto';
+import os from 'node:os';
+import path from 'node:path';
+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';
+/**
+ * Stable telemetry kind string — fleet dashboards size the macOS cohort
+ * by this value. Only one backend ships in this module today.
+ */
+const KIND_SHELLOUT = 'macos-keychain-shellout';
+/**
+ * Default keychain layout for the shellout backend. Stable across
+ * versions and used by the production dispatcher in `kek/index.ts`.
+ * 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';
+/** `security` exit code when the requested item does not exist. */
+const SECURITY_ITEM_NOT_FOUND = 44;
+const execFileAsync = promisify(execFile);
+let _execFileForTest = null;
+export function __setExecFileForTest(fn) {
+    _execFileForTest = fn;
+    // Probes are cached per-process; reset so the next available() call
+    // re-evaluates with the new mock.
+    _securityProbeCache = undefined;
+    // The resolved-keychain cache also depends on `security default-keychain`
+    // output — reset it so a new mock can drive a different resolution path.
+    _resolvedKeychainCache = undefined;
+}
+/** Default execFile wrapper used when no test override is installed. */
+const defaultExec = async (file, args, options) => {
+    // promisify(execFile)'s typing is loose — coerce the encoding option
+    // explicitly for the typed test seam.
+    const result = await execFileAsync(file, args, {
+        encoding: 'utf-8',
+        ...(options ?? {}),
+    });
+    // Defensive coercion — when callers override the encoding, stdout may
+    // surface as Buffer/Uint8Array; the typeof guard keeps both shapes safe.
+    return {
+        stdout: typeof result.stdout === 'string'
+            ? result.stdout
+            : Buffer.from(result.stdout).toString('utf-8'),
+        stderr: typeof result.stderr === 'string'
+            ? result.stderr
+            : Buffer.from(result.stderr).toString('utf-8'),
+    };
+};
+function exec(file, args) {
+    const impl = _execFileForTest ?? defaultExec;
+    return impl(file, args, { encoding: 'utf-8' });
+}
+// ---------------------------------------------------------------------------
+// Probes — cached for the process lifetime to keep available() ~O(1).
+// ---------------------------------------------------------------------------
+/** `undefined` = not yet probed; `boolean` = cached probe outcome. */
+let _securityProbeCache;
+async function probeSecurityBinary() {
+    if (process.platform !== 'darwin')
+        return false;
+    if (_securityProbeCache !== undefined)
+        return _securityProbeCache;
+    try {
+        await exec('security', ['help']);
+        _securityProbeCache = true;
+    }
+    catch {
+        _securityProbeCache = false;
+    }
+    return _securityProbeCache;
+}
+/** @internal Test seam — clear the security-binary probe cache. */
+export function __resetSecurityProbeCacheForTest() {
+    _securityProbeCache = undefined;
+}
+// ---------------------------------------------------------------------------
+// Login-keychain resolution.
+//
+// Memoized per-process so we make at most one `security default-keychain`
+// call per probe lifecycle. `__setExecFileForTest()` and
+// `__resetResolvedKeychainCacheForTest()` clear the cache so test mocks
+// can drive deterministic resolution.
+// ---------------------------------------------------------------------------
+/**
+ * `undefined` = not yet probed; `string` = absolute path of the resolved
+ * login keychain; `null` = nothing resolved (treat as unavailable).
+ */
+let _resolvedKeychainCache;
+/**
+ * Resolve the canonical login keychain path for the current user.
+ *
+ * Resolution order:
+ *   1. Query `security default-keychain -d user`. Output is a quoted
+ *      absolute path; parse and return.
+ *   2. Fall back to `~/Library/Keychains/login.keychain-db`
+ *      (modern macOS, El Capitan and later).
+ *   3. Fall back to `~/Library/Keychains/login.keychain` (legacy).
+ *   4. Return `null` when nothing resolves — caller treats as unavailable.
+ *
+ * Caching: result is memoized for the process lifetime in
+ * `_resolvedKeychainCache` so we make at most one `security
+ * default-keychain` call per probe lifecycle. The cache is reset by
+ * `__resetResolvedKeychainCacheForTest()` and `__setExecFileForTest()`.
+ *
+ * Why explicit resolution: passing the resolved path as a positional
+ * argument to `security find-generic-password` and `add-generic-password`
+ * eliminates the system-modal "Keychain Not Found" dialog that
+ * `security` triggers when it cannot find a default keychain in the
+ * current exec context. A daemon must never block on UI.
+ */
+async function resolveLoginKeychain() {
+    if (_resolvedKeychainCache !== undefined)
+        return _resolvedKeychainCache;
+    // Step 1 — ask `security` for the default user keychain.
+    try {
+        const { stdout } = await exec('security', ['default-keychain', '-d', 'user']);
+        // Output shape: `    "/Users/foo/Library/Keychains/login.keychain-db"`
+        // (leading whitespace, then the path quoted)
+        const match = stdout.match(/"([^"]+)"/);
+        if (match && match[1] && fs.existsSync(match[1])) {
+            _resolvedKeychainCache = match[1];
+            return _resolvedKeychainCache;
+        }
+    }
+    catch {
+        /* fall through to canonical paths */
+    }
+    // Step 2 — modern canonical path.
+    const modern = path.join(os.homedir(), 'Library', 'Keychains', 'login.keychain-db');
+    if (fs.existsSync(modern)) {
+        _resolvedKeychainCache = modern;
+        return _resolvedKeychainCache;
+    }
+    // Step 3 — legacy path (pre-El Capitan).
+    const legacy = path.join(os.homedir(), 'Library', 'Keychains', 'login.keychain');
+    if (fs.existsSync(legacy)) {
+        _resolvedKeychainCache = legacy;
+        return _resolvedKeychainCache;
+    }
+    // Step 4 — nothing resolves; caller treats as unavailable.
+    _resolvedKeychainCache = null;
+    return null;
+}
+/** @internal Test seam — clear the resolved-keychain cache. */
+export function __resetResolvedKeychainCacheForTest() {
+    _resolvedKeychainCache = undefined;
+}
+// ---------------------------------------------------------------------------
+// Shellout backend: Keychain-resident 32-byte KEK + AES-256-GCM wrap.
+// ---------------------------------------------------------------------------
+/**
+ * Read the master KEK bytes from the keychain. Returns null on item-not-
+ * found (exit 44) — caller treats this as "first use, generate one."
+ *
+ * Any other failure (locked keychain, missing binary at runtime, etc.)
+ * throws a `KekUnavailableError` so the caller can decide between
+ * fail-open (default) and fail-closed (`OVERSKY_KEK_REQUIRED=1`).
+ *
+ * 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 `find-generic-password` so
+ * `security(1)` cannot fall back to a "default keychain" lookup in a
+ * non-GUI exec context, which would otherwise trigger a system-modal
+ * `Keychain Not Found` dialog and block the daemon. If no keychain
+ * resolves, throw `KekUnavailableError` immediately rather than
+ * shelling out at all.
+ */
+async function readKekFromKeychain(service, account) {
+    const keychainPath = await resolveLoginKeychain();
+    if (keychainPath === null) {
+        throw new KekUnavailableError(KIND_SHELLOUT, 'no user login keychain resolvable; cannot read master KEK');
+    }
+    try {
+        const { stdout } = await exec('security', [
+            'find-generic-password',
+            '-s',
+            service,
+            '-a',
+            account,
+            '-w',
+            keychainPath,
+        ]);
+        const trimmed = stdout.replace(/\n$/, '').trim();
+        if (trimmed.length === 0)
+            return null;
+        let raw;
+        try {
+            raw = Buffer.from(trimmed, 'base64');
+        }
+        catch {
+            throw new KekUnavailableError(KIND_SHELLOUT, 'keychain KEK is not valid base64');
+        }
+        if (raw.length !== KEY_LEN) {
+            throw new KekUnavailableError(KIND_SHELLOUT, `keychain KEK has wrong length (got ${raw.length}, want ${KEY_LEN})`);
+        }
+        return raw;
+    }
+    catch (err) {
+        if (err instanceof KekUnavailableError)
+            throw err;
+        const status = err.code ?? err.status;
+        if (status === SECURITY_ITEM_NOT_FOUND)
+            return null;
+        const stderr = String(err.stderr ?? '');
+        if (stderr.includes('User interaction is not allowed') ||
+            stderr.includes('errSecInteractionNotAllowed') ||
+            stderr.includes('errSecAuthFailed')) {
+            throw new KekUnavailableError(KIND_SHELLOUT, `keychain locked or non-interactive context (status=${status}); ` +
+                `unlock the login keychain or run the daemon from a GUI session`, { cause: err });
+        }
+        throw new KekUnavailableError(KIND_SHELLOUT, `find-generic-password failed (status=${status})`, {
+            cause: err,
+        });
+    }
+}
+/**
+ * Persist a master KEK to the keychain. Uses `-U` so the upsert is
+ * idempotent — repeated first-use races just overwrite each other rather
+ * than failing with "item already exists." We accept the second-writer-
+ * wins outcome because (a) the daemon is single-tenant per profile and
+ * (b) all writers are generating the same shape of secret.
+ *
+ * Race note: if two daemon processes both miss and both store within the
+ * same TOCTOU window, the second overwrite wins and any DEKs already
+ * wrapped under the first KEK become permanently unrecoverable. The
+ * envelope path's caller (`credEnvelope.ts:initCredEnvelope`) handles
+ * this gracefully — `unwrap` failure → log + treat as first enrollment.
+ *
+ * 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.
+ */
+async function writeKekToKeychain(kek, service, account) {
+    if (kek.length !== KEY_LEN) {
+        throw new KekUnavailableError(KIND_SHELLOUT, `writeKekToKeychain: expected ${KEY_LEN}-byte buffer, got ${kek.length}`);
+    }
+    const keychainPath = await resolveLoginKeychain();
+    if (keychainPath === null) {
+        throw new KekUnavailableError(KIND_SHELLOUT, 'no user login keychain resolvable; cannot write master KEK');
+    }
+    const b64 = kek.toString('base64');
+    try {
+        await exec('security', [
+            'add-generic-password',
+            '-s',
+            service,
+            '-a',
+            account,
+            '-w',
+            b64,
+            '-U',
+            keychainPath,
+        ]);
+    }
+    catch (err) {
+        if (err instanceof KekUnavailableError)
+            throw err;
+        const status = err.code ?? err.status;
+        const stderr = String(err.stderr ?? '');
+        if (stderr.includes('User interaction is not allowed') ||
+            stderr.includes('errSecInteractionNotAllowed') ||
+            stderr.includes('errSecAuthFailed')) {
+            throw new KekUnavailableError(KIND_SHELLOUT, `keychain locked or non-interactive context (status=${status}); ` +
+                `unlock the login keychain or run the daemon from a GUI session`, { cause: err });
+        }
+        throw new KekUnavailableError(KIND_SHELLOUT, `add-generic-password failed (status=${status})`, {
+            cause: err,
+        });
+    }
+}
+/**
+ * In-process cache of master KEKs, keyed by `${service}::${account}` so
+ * multiple `MacosKek` instances scoped to different keychain entries
+ * (e.g. the smoke test's per-run unique service, or a multi-tenant
+ * test) keep isolated cache slots. Loaded lazily on the first
+ * wrap/unwrap so a daemon that never reaches the active envelope path
+ * never spawns a `security` process. Cleared by
+ * `__resetKekCacheForTest()` and by the registered zeroize hook so the
+ * test suite and production graceful-shutdown can simulate or enforce
+ * fresh-process state.
+ */
+const _kekCacheBySvc = new Map();
+// Register the zeroize hook at module-load time so any caller that
+// invokes `zeroizeKekCaches()` from `@skrr-ai/auth-core` (e.g. the
+// daemon's graceful-shutdown handler) clears this cache without needing
+// a direct import of macos.ts.
+registerZeroizeHook(() => zeroizeMacosKekCache());
+/**
+ * Zero out and drop every cached master-KEK buffer.
+ *
+ * Iterates the cache map, fills each buffer with zeroes (so any
+ * residual reference held by a caller observes the wipe), then clears
+ * the map. The buffer-fill happens before the map clear so the typed
+ * test seam (`__getKekCacheForTest`) can prove the wipe targeted the
+ * actual cached bytes rather than a copy.
+ *
+ * Must be called on:
+ *   - Daemon shutdown (SIGTERM / SIGINT) so the KEK does not linger in
+ *     memory across the process exit window where coredumps could land.
+ *   - KEK rotation, after the new KEK has been resolved and the wrapped
+ *     DEK re-issued, so the OLD KEK does not stay resident.
+ *   - Logout flows that wipe at-rest credentials, so there is no useful
+ *     KEK left to wrap a re-enrolled DEK under the previous identity.
+ *
+ * Idempotent — safe to call when the cache is already empty.
+ */
+export function zeroizeMacosKekCache() {
+    for (const buf of _kekCacheBySvc.values()) {
+        buf.fill(0);
+    }
+    _kekCacheBySvc.clear();
+}
+/** @internal Test seam — clear the in-process master-KEK cache. Internally
+ *  routes through the production zeroize helper so the test-reset path
+ *  exercises the same buffer-fill that ships in production. */
+export function __resetKekCacheForTest() {
+    zeroizeMacosKekCache();
+}
+/**
+ * @internal Test seam — return the live cache buffer for the given
+ * `service`/`account` pair so the zeroize test can hold a reference,
+ * run zeroize, and verify the underlying bytes went to all-zero
+ * (proving the fill was on the actual buffer rather than a copy).
+ * Returns null when no entry is cached for that pair.
+ *
+ * Defaults to the canonical production keys so existing tests that
+ * call `__getKekCacheForTest()` keep working without args.
+ */
+export function __getKekCacheForTest(service = KEYCHAIN_SERVICE, account = KEYCHAIN_ACCOUNT) {
+    return _kekCacheBySvc.get(`${service}::${account}`) ?? null;
+}
+/**
+ * Resolve the master KEK for the given `service`/`account` pair,
+ * generating + storing one on first use. Cached per pair after the
+ * first successful resolution so subsequent wrap/unwrap calls on the
+ * same instance do not respawn `security`.
+ */
+async function resolveOrCreateKek(service, account) {
+    const cacheKey = `${service}::${account}`;
+    const cached = _kekCacheBySvc.get(cacheKey);
+    if (cached !== undefined)
+        return cached;
+    const existing = await readKekFromKeychain(service, account);
+    if (existing !== null) {
+        _kekCacheBySvc.set(cacheKey, existing);
+        return existing;
+    }
+    const fresh = crypto.randomBytes(KEY_LEN);
+    await writeKekToKeychain(fresh, service, account);
+    _kekCacheBySvc.set(cacheKey, fresh);
+    return fresh;
+}
+/** Resolve an already-persisted master KEK without creating one. */
+async function resolveExistingKek(service, account) {
+    const cacheKey = `${service}::${account}`;
+    const cached = _kekCacheBySvc.get(cacheKey);
+    if (cached !== undefined)
+        return cached;
+    const existing = await readKekFromKeychain(service, account);
+    if (existing === null) {
+        throw new KekUnavailableError(KIND_SHELLOUT, 'macOS Keychain master KEK is missing; refusing to create it outside the enrollment lock');
+    }
+    _kekCacheBySvc.set(cacheKey, existing);
+    return existing;
+}
+/**
+ * Wrap a DEK using the shellout backend. Returns the serialized envelope
+ * bytes (a UTF-8 string encoded as Buffer) so the on-disk shape matches
+ * the in-memory test KEK.
+ */
+async function shelloutWrap(dek, aad, service, account) {
+    const kek = await resolveOrCreateKek(service, account);
+    const sealed = sealBuffer(dek, kek, aad);
+    return Buffer.from(envelopeSerialize(sealed), 'utf-8');
+}
+/**
+ * Unwrap a previously-wrapped DEK using the shellout backend. Throws
+ * loudly on tag mismatch — `credEnvelope.ts` decides whether to fail-open
+ * or fail-closed.
+ */
+async function shelloutUnwrap(wrapped, aad, service, account, createIfMissing = true) {
+    const kek = await (createIfMissing
+        ? resolveOrCreateKek(service, account)
+        : resolveExistingKek(service, account));
+    const text = wrapped.toString('utf-8');
+    const sealed = envelopeDeserialize(text);
+    if (!sealed) {
+        throw new KekUnavailableError(KIND_SHELLOUT, 'wrapped blob is not a valid serialized envelope');
+    }
+    const out = openBuffer(sealed, kek, aad);
+    if (out.length !== KEY_LEN) {
+        throw new KekUnavailableError(KIND_SHELLOUT, `unwrapped DEK has wrong length (got ${out.length}, want ${KEY_LEN})`);
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// MacosKek — KekStrategy implementation.
+// ---------------------------------------------------------------------------
+export class MacosKek {
+    id = 'macos-secure-enclave';
+    /** Telemetry kind of the backend that satisfied the most recent call.
+     *  Public so the daemon's `cred_envelope` events can include it. */
+    _lastKind = null;
+    /** Keychain `service` (the `-s` arg) this instance reads/writes. */
+    service;
+    /** Keychain `account` (the `-a` arg) this instance reads/writes. */
+    account;
+    /**
+     * @param opts.service Optional override for the keychain `-s` value.
+     *   Defaults to `ai.skrr.daemon.kek` — the canonical production
+     *   pair. Override only for hermetic multi-tenant tests or for the
+     *   real-keychain smoke test, which generates a unique service per
+     *   run so its `delete-generic-password` teardown cannot clobber the
+     *   developer's actual master KEK. Production callers MUST pass
+     *   nothing so fleet telemetry stays sized against one keychain
+     *   entry per host.
+     * @param opts.account Optional override for the keychain `-a` value.
+     *   Defaults to `master-kek-v1`. Same caveat as `service`: an
+     *   override that points at a non-default entry must be paired with
+     *   explicit cleanup if the entry should not persist past the
+     *   caller's lifetime — `MacosKek` itself never deletes keychain
+     *   items.
+     */
+    constructor(opts) {
+        this.service = opts?.service ?? KEYCHAIN_SERVICE;
+        this.account = opts?.account ?? KEYCHAIN_ACCOUNT;
+    }
+    /**
+     * Telemetry kind of the most recent successful wrap/unwrap. `null`
+     * before any call. Stable string `'macos-keychain-shellout'` after the
+     * first successful wrap or unwrap. The kind does not vary with
+     * `service`/`account` overrides — the backend is the same.
+     */
+    get kind() {
+        return this._lastKind;
+    }
+    /**
+     * `available()` is true on darwin when (a) `security` is on PATH AND
+     * (b) a user login keychain can be resolved. Both checks are required
+     * because shelling out without a resolvable keychain triggers a
+     * system-modal `Keychain Not Found` dialog from the daemon — which
+     * blocks the process and offers a destructive `Reset To Defaults`
+     * action. When the keychain resolution fails, we honestly return
+     * `false` so `credEnvelope.ts` reports `disabled.kek_unavailable`
+     * cleanly. Cached results — the probe spawns at most one
+     * `security help` and one `security default-keychain` per process.
+     */
+    async available() {
+        if (process.platform !== 'darwin')
+            return false;
+        if (!(await probeSecurityBinary()))
+            return false;
+        const keychainPath = await resolveLoginKeychain();
+        return keychainPath !== null;
+    }
+    async wrap(dek, aad) {
+        if (process.platform !== 'darwin') {
+            throw new KekUnavailableError(this.id, 'macOS KEK called on non-darwin platform');
+        }
+        const aadBuf = aad ?? Buffer.alloc(0);
+        if (!(await probeSecurityBinary())) {
+            throw new KekUnavailableError(this.id, 'macOS KEK unavailable: `security` not on PATH');
+        }
+        try {
+            const out = await shelloutWrap(dek, aadBuf, this.service, this.account);
+            this._lastKind = KIND_SHELLOUT;
+            return out;
+        }
+        catch (err) {
+            if (err instanceof KekUnavailableError)
+                throw err;
+            throw new KekUnavailableError(this.id, err?.message ?? 'shellout wrap failed', {
+                cause: err,
+            });
+        }
+    }
+    async unwrap(wrapped, aad) {
+        if (process.platform !== 'darwin') {
+            throw new KekUnavailableError(this.id, 'macOS KEK called on non-darwin platform');
+        }
+        const aadBuf = aad ?? Buffer.alloc(0);
+        if (!(await probeSecurityBinary())) {
+            throw new KekUnavailableError(this.id, 'macOS KEK unavailable: `security` not on PATH');
+        }
+        try {
+            const out = await shelloutUnwrap(wrapped, aadBuf, this.service, this.account);
+            this._lastKind = KIND_SHELLOUT;
+            return out;
+        }
+        catch (err) {
+            if (err instanceof KekUnavailableError)
+                throw err;
+            // Pass cipher errors (tag mismatch, malformed blob) through with
+            // no swallowing — credEnvelope.ts decides fail-open vs fail-closed.
+            throw err;
+        }
+    }
+    async unwrapExisting(wrapped, aad) {
+        if (process.platform !== 'darwin') {
+            throw new KekUnavailableError(this.id, 'macOS KEK called on non-darwin platform');
+        }
+        const aadBuf = aad ?? Buffer.alloc(0);
+        if (!(await probeSecurityBinary())) {
+            throw new KekUnavailableError(this.id, 'macOS KEK unavailable: `security` not on PATH');
+        }
+        const out = await shelloutUnwrap(wrapped, aadBuf, this.service, this.account, false);
+        this._lastKind = KIND_SHELLOUT;
+        return out;
+    }
+    describe() {
+        if (process.platform !== 'darwin') {
+            return 'macOS KEK (not darwin — unavailable)';
+        }
+        if (_securityProbeCache === true) {
+            return 'macOS Keychain via security(1) shellout';
+        }
+        if (_securityProbeCache === false) {
+            return 'macOS KEK unavailable (security binary missing)';
+        }
+        return 'macOS KEK (probe pending — call available() to materialize)';
+    }
+}