@skrr-ai/auth-core 0.1.2

package/dist/esm/kek/types.d.ts

@@ -0,0 +1,111 @@
+/**
+ * kek/types.ts — platform-strategy interface for the Key Encryption Key.
+ *
+ * The KEK is the root of the at-rest encryption hierarchy. It MUST live
+ * in a platform-native store (Secure Enclave, DPAPI, libsecret +
+ * machine-id-derived material) so that an attacker who exfiltrates the
+ * on-disk wrapped DEK cannot brute-force it offline.
+ *
+ * Each platform implementation owns its own native binding and key
+ * lifecycle. They share only this interface, which is deliberately small
+ * to make swapping implementations cheap as native bindings ship.
+ *
+ * Failure mode contract — every implementation MUST:
+ *   - Return `available()` honestly. If `available()` is true, `wrap()`
+ *     and `unwrap()` are expected to succeed under normal conditions.
+ *   - On `available()` returning false, the daemon falls through to the
+ *     legacy plaintext backend with a `cred_envelope.kek_unavailable`
+ *     telemetry event. NEVER crash the daemon because a KEK is missing.
+ *   - Throw on unwrap with the wrong key/AAD; never silently return
+ *     garbage. The cipher path inside `credentialEnvelope.ts` already
+ *     enforces this; native impls just have to surface that error.
+ */
+/**
+ * Platform-bound key for wrapping/unwrapping the per-profile DEK.
+ *
+ * Implementations are per-platform but the API is platform-agnostic so
+ * the daemon's integration code stays platform-blind.
+ */
+export interface KekStrategy {
+    /**
+     * Stable lowercase identifier for telemetry, logs, and dashboard
+     * filtering. Format: `<platform>-<backend>` e.g. `macos-secure-enclave`,
+     * `linux-libsecret`, `windows-dpapi`. Stable across versions; new
+     * backends get new ids.
+     */
+    readonly id: string;
+    /**
+     * Optional finer-grained backend identifier for strategies that select
+     * between multiple implementations at runtime (e.g. macOS NAPI binding
+     * vs. `security(1)` shellout). Stable lowercase string —
+     * `macos-secure-enclave-napi`, `macos-keychain-shellout`. `null` until
+     * the first wrap/unwrap completes; older callers can ignore this
+     * entirely. See `docs/daemon-auth-l12-kek-platform-bindings.md`.
+     */
+    readonly kind?: string | null;
+    /**
+     * Fast probe — must NOT throw, NOT prompt the user, and NOT exceed
+     * ~50ms in the success case. Used at daemon startup to decide whether
+     * to enable the envelope path.
+     *
+     * Returning true is a promise that the wrap/unwrap calls will succeed
+     * under normal conditions; if those subsequently fail, the daemon
+     * falls back to legacy plaintext + emits `cred_envelope.wrap.failure`.
+     */
+    available(): Promise<boolean>;
+    /**
+     * Wrap a 32-byte DEK under the platform-bound KEK. Returns opaque
+     * platform-specific bytes the caller persists alongside the wrapped
+     * credentials. The format is private to the implementation; never
+     * inspected by the daemon.
+     *
+     * The optional `aad` is bound into the wrap when the platform's AEAD
+     * supports it. Linux/Windows backends MUST honor it; macOS Secure
+     * Enclave's ECIES variant has limited AAD support — implementations
+     * may emulate AAD by deriving a per-context KEK via HKDF when the
+     * primitive doesn't support AAD natively.
+     */
+    wrap(dek: Buffer, aad?: Buffer): Promise<Buffer>;
+    /**
+     * Unwrap a previously-wrapped DEK. Throws on:
+     *   - Wrong KEK / AAD mismatch (treat as a hard authentication failure)
+     *   - Corrupted wrapped bytes
+     *   - Platform-side errors (keychain locked, Secure Enclave busy, etc.)
+     *
+     * Callers should catch and emit `cred_envelope.unwrap.fallback_to_legacy`
+     * before falling through to the plaintext path.
+     */
+    unwrap(wrapped: Buffer, aad?: Buffer): Promise<Buffer>;
+    /**
+     * Optional read-only unwrap used by the credential-envelope optimistic
+     * startup path. Implementations MUST NOT create, rotate, or persist native
+     * KEK material from this method. If the native key is missing, throw and let
+     * the caller retry `unwrap()` under the cross-process enrollment mutex.
+     *
+     * Strategies that cannot guarantee this invariant leave the method absent;
+     * callers then take the mutex before any unwrap attempt.
+     */
+    unwrapExisting?(wrapped: Buffer, aad?: Buffer): Promise<Buffer>;
+    /**
+     * Human-readable description for the `oversky status` / diagnostics
+     * page. Includes platform-specific hints ("Secure Enclave with
+     * biometry", "DPAPI user scope", "machine-id-derived KEK with
+     * libsecret store"). Never includes secret material.
+     */
+    describe(): string;
+}
+/**
+ * Sentinel error class used by KEK implementations to signal
+ * unrecoverable native failures (e.g. Secure Enclave key invalidated by
+ * a Touch ID change). The daemon's integration treats these as
+ * `available=false` going forward and re-probes on the next startup.
+ *
+ * Distinct from generic `Error` so the integration's catch can decide
+ * whether to fall back permanently or just for this request.
+ */
+export declare class KekUnavailableError extends Error {
+    readonly id: string;
+    constructor(id: string, message: string, opts?: {
+        cause?: unknown;
+    });
+}

package/dist/esm/kek/types.js

@@ -0,0 +1,39 @@
+/**
+ * kek/types.ts — platform-strategy interface for the Key Encryption Key.
+ *
+ * The KEK is the root of the at-rest encryption hierarchy. It MUST live
+ * in a platform-native store (Secure Enclave, DPAPI, libsecret +
+ * machine-id-derived material) so that an attacker who exfiltrates the
+ * on-disk wrapped DEK cannot brute-force it offline.
+ *
+ * Each platform implementation owns its own native binding and key
+ * lifecycle. They share only this interface, which is deliberately small
+ * to make swapping implementations cheap as native bindings ship.
+ *
+ * Failure mode contract — every implementation MUST:
+ *   - Return `available()` honestly. If `available()` is true, `wrap()`
+ *     and `unwrap()` are expected to succeed under normal conditions.
+ *   - On `available()` returning false, the daemon falls through to the
+ *     legacy plaintext backend with a `cred_envelope.kek_unavailable`
+ *     telemetry event. NEVER crash the daemon because a KEK is missing.
+ *   - Throw on unwrap with the wrong key/AAD; never silently return
+ *     garbage. The cipher path inside `credentialEnvelope.ts` already
+ *     enforces this; native impls just have to surface that error.
+ */
+/**
+ * Sentinel error class used by KEK implementations to signal
+ * unrecoverable native failures (e.g. Secure Enclave key invalidated by
+ * a Touch ID change). The daemon's integration treats these as
+ * `available=false` going forward and re-probes on the next startup.
+ *
+ * Distinct from generic `Error` so the integration's catch can decide
+ * whether to fall back permanently or just for this request.
+ */
+export class KekUnavailableError extends Error {
+    id;
+    constructor(id, message, opts) {
+        super(message, opts);
+        this.name = 'KekUnavailableError';
+        this.id = id;
+    }
+}

package/dist/esm/kek/windows.d.ts

@@ -0,0 +1,71 @@
+import type { KekStrategy } from './types.js';
+declare const KIND = "windows-dpapi-powershell-shellout";
+/**
+ * @internal Test seam — inject a mock execFile for hermetic tests so the
+ * suite never touches the real PowerShell or DPAPI. Reset to `null` to
+ * restore the real `child_process.execFile`.
+ */
+type ExecFileLike = (file: string, args: readonly string[], options?: {
+    encoding?: BufferEncoding;
+}) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export declare function __setExecFileForTest(fn: ExecFileLike | null): void;
+/**
+ * @internal Test seam — no-op for Windows since DPAPI is stateless on
+ * the library side (no in-process master-blob to clear). Exists for API
+ * symmetry with `__resetKekCacheForTest` on macOS so test harness setup
+ * code can call the same pattern across platforms.
+ */
+export declare function __resetMasterBlobForTest(): void;
+export declare class WindowsKek implements KekStrategy {
+    readonly id = "windows-dpapi";
+    /**
+     * Telemetry kind of the most recent successful wrap/unwrap. `null`
+     * before any call. Always `'windows-dpapi-powershell-shellout'` for
+     * this Tier-2 implementation.
+     */
+    private _lastKind;
+    get kind(): typeof KIND | null;
+    /**
+     * Returns true when PowerShell is on PATH and the DPAPI assembly loads.
+     *
+     * Result is cached for the process lifetime. On probe failure (ENOENT,
+     * empty stdout, PowerShell Constrained Language Mode blocking the type),
+     * returns false and the daemon falls through to the legacy plaintext
+     * backend.
+     */
+    available(): Promise<boolean>;
+    /**
+     * Wrap `dek` using Windows DPAPI with `aad` as optional entropy.
+     *
+     * IMPORTANT: DPAPI IS the wrap — there is no separate AES-GCM layer.
+     * The returned bytes are the raw DPAPI ciphertext blob and should be
+     * persisted as-is (e.g. to a 0600 file under the profile config dir).
+     *
+     * The `aad` buffer acts as DPAPI's `optionalEntropy`. Must match
+     * exactly at unwrap time. If `aad` is omitted or empty, `$null`
+     * entropy is used — still bound to user identity, but without the
+     * extra entropy protection.
+     *
+     * @throws {KekUnavailableError} on non-win32 platform or PowerShell failure.
+     */
+    wrap(dek: Buffer, aad?: Buffer): Promise<Buffer>;
+    /**
+     * Unwrap a previously-wrapped DEK using Windows DPAPI.
+     *
+     * The `aad` buffer must match exactly what was passed to `wrap()`.
+     * DPAPI CryptographicException (mismatched entropy, corrupted blob,
+     * master-key roll after user-profile reset) surfaces as a plain `Error`
+     * so that upstream `credEnvelope.ts` can map it to the `kek_rotated`
+     * path and force re-enrollment.
+     *
+     * @throws {Error} on DPAPI CryptographicException (kek_rotated path).
+     * @throws {KekUnavailableError} on non-win32 or PowerShell invocation failure.
+     */
+    unwrap(wrapped: Buffer, aad?: Buffer): Promise<Buffer>;
+    unwrapExisting(wrapped: Buffer, aad?: Buffer): Promise<Buffer>;
+    describe(): string;
+}
+export {};

package/dist/esm/kek/windows.js

@@ -0,0 +1,344 @@
+/**
+ * kek/windows.ts — Windows DPAPI KEK strategy.
+ *
+ * ARCHITECTURAL NOTE — DPAPI IS the wrap, not a key store:
+ *
+ *   Unlike the macOS path (which keeps a 32-byte KEK in the Keychain and
+ *   then AES-256-GCM-wraps the DEK with that KEK), Windows DPAPI is
+ *   structurally different. `ProtectedData.Protect(plaintext, entropy, scope)`
+ *   returns a self-contained ciphertext blob that you persist yourself.
+ *   There is no named persistent credential to load; the "KEK" is implicit
+ *   in the user's Windows profile master key, derived from login credentials.
+ *
+ *   As a result:
+ *     - `wrap(dek, aad)` calls DPAPI directly with `optionalEntropy = aad`.
+ *     - `unwrap(wrapped, aad)` calls DPAPI with the same entropy.
+ *     - The bytes returned to `credEnvelope.ts` ARE the DPAPI ciphertext;
+ *       there is no separate AES-GCM layer on top.
+ *     - Do NOT attempt to unify this with the macOS `credentialEnvelope.ts`
+ *       AES-GCM layer. The primitives are different by design.
+ *
+ * Security model (CurrentUser scope — mandatory):
+ *   - DPAPI binds the ciphertext to the Windows user identity via the
+ *     user's login-derived master key. A different Windows account on the
+ *     same machine CANNOT decrypt the blob.
+ *   - `DataProtectionScope.CurrentUser` is always used. `LocalMachine`
+ *     scope is explicitly NOT used: it would allow any account on the box
+ *     to decrypt — violating cross-user isolation.
+ *   - `optionalEntropy` = the `aad` buffer acts as AAD-equivalent:
+ *     must match exactly at unwrap time.
+ *
+ * Backend — PowerShell shellout:
+ *   PowerShell is available on every Windows installation since Win 7+.
+ *   No extra native dependencies are required, matching the project
+ *   precedent in `daemon/src/keychain.ts`. A NAPI binding can replace
+ *   this in a future Phase D for enterprise hardened environments
+ *   (PowerShell Constrained Language Mode blocks the DPAPI assembly load;
+ *   see `available()` — probe will return false in those environments).
+ *
+ * Argument size limit:
+ *   PowerShell `-Command` is bounded at roughly 32 KB. A 32-byte DEK and
+ *   small AAD labels are well within that limit. Document and enforce at
+ *   the call site if callers begin passing large AAD in a future revision.
+ *
+ * Edge cases (documented; not tested in this PR):
+ *   - CRYPTPROTECT master-key roll (user profile reset): `Unprotect` throws
+ *     `CryptographicException` → surfaces as plain `Error` → upstream
+ *     `credEnvelope.ts` treats as `kek_rotated` → forces re-enrollment.
+ *   - Roaming profiles: `CurrentUser` scope is user-bound + machine-local,
+ *     so a roamed login on a new box re-runs first-time enrollment naturally.
+ *   - PowerShell Constrained Language Mode: probe will return false since
+ *     `[System.Security.Cryptography.ProtectedData]` access is blocked.
+ *     `available()` correctly reflects this as unavailable.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { KekUnavailableError } from './types.js';
+const KIND = 'windows-dpapi-powershell-shellout';
+const execFileAsync = promisify(execFile);
+let _execFileForTest = null;
+export function __setExecFileForTest(fn) {
+    _execFileForTest = fn;
+    // Reset the probe cache so the next available() re-evaluates with the mock.
+    _powershellProbeCache = undefined;
+}
+/** Default execFile wrapper used when no test override is installed. */
+const defaultExec = async (file, args, options) => {
+    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' });
+}
+// ---------------------------------------------------------------------------
+// Probe — cached for the process lifetime to keep available() ~O(1).
+// ---------------------------------------------------------------------------
+/** `undefined` = not yet probed; `boolean` = cached probe outcome. */
+let _powershellProbeCache;
+/**
+ * Probe whether PowerShell and the DPAPI assembly are accessible.
+ *
+ * Checks that `[System.Security.Cryptography.ProtectedData]` resolves —
+ * a non-empty stdout means the type loaded and DPAPI is usable.
+ * Exit 0 with empty stdout, non-zero exit, or ENOENT → false.
+ *
+ * Enterprise environments with PowerShell Constrained Language Mode will
+ * fail here because the ProtectedData type is blocked in that mode.
+ */
+async function probePowerShell() {
+    if (process.platform !== 'win32')
+        return false;
+    if (_powershellProbeCache !== undefined)
+        return _powershellProbeCache;
+    try {
+        const { stdout } = await exec('powershell.exe', [
+            '-NoProfile',
+            '-NonInteractive',
+            '-Command',
+            '[System.Security.Cryptography.ProtectedData].FullName',
+        ]);
+        _powershellProbeCache = stdout.trim().length > 0;
+    }
+    catch {
+        _powershellProbeCache = false;
+    }
+    return _powershellProbeCache;
+}
+// ---------------------------------------------------------------------------
+// DPAPI shellout helpers.
+// ---------------------------------------------------------------------------
+/**
+ * Call `ProtectedData.Protect` via PowerShell.
+ *
+ * Both `plaintext` and `entropy` are passed as base64 strings inside the
+ * PowerShell command. Base64 chars (`A-Za-z0-9+/=`) are safe inside
+ * PowerShell single-quoted strings — no escaping needed.
+ *
+ * Scope: `CurrentUser` — mandatory for cross-user isolation.
+ *
+ * @param plaintext - The bytes to protect (the DEK).
+ * @param entropy   - Optional entropy / AAD-equivalent. Empty Buffer → $null.
+ * @returns DPAPI ciphertext as a Buffer.
+ * @throws {KekUnavailableError} on any PowerShell or DPAPI failure.
+ */
+async function dpapiProtect(plaintext, entropy) {
+    const ptB64 = plaintext.toString('base64');
+    const enB64 = entropy.length > 0 ? entropy.toString('base64') : null;
+    const entropyExpr = enB64 !== null ? `$en = [Convert]::FromBase64String('${enB64}');` : '$en = $null;';
+    const command = [
+        `$pt = [Convert]::FromBase64String('${ptB64}');`,
+        entropyExpr,
+        '$ct = [System.Security.Cryptography.ProtectedData]::Protect($pt, $en, [System.Security.Cryptography.DataProtectionScope]::CurrentUser);',
+        '[Convert]::ToBase64String($ct)',
+    ].join(' ');
+    let stdout;
+    let stderr;
+    try {
+        ({ stdout, stderr } = await exec('powershell.exe', [
+            '-NoProfile',
+            '-NonInteractive',
+            '-Command',
+            command,
+        ]));
+    }
+    catch (err) {
+        throw new KekUnavailableError(KIND, `DPAPI Protect failed: ${err.message}`, {
+            cause: err,
+        });
+    }
+    if (stderr && stderr.includes('CryptographicException')) {
+        throw new KekUnavailableError(KIND, `DPAPI Protect CryptographicException: ${stderr.trim()}`);
+    }
+    const trimmed = stdout.trim();
+    if (trimmed.length === 0) {
+        throw new KekUnavailableError(KIND, 'DPAPI Protect returned empty output');
+    }
+    try {
+        return Buffer.from(trimmed, 'base64');
+    }
+    catch (err) {
+        throw new KekUnavailableError(KIND, 'DPAPI Protect output is not valid base64', { cause: err });
+    }
+}
+/**
+ * Call `ProtectedData.Unprotect` via PowerShell.
+ *
+ * DPAPI failure (e.g. master-key roll after user-profile reset,
+ * `CryptographicException`) is surfaced as a plain `Error` (NOT
+ * `KekUnavailableError`) so that upstream `credEnvelope.ts` can map the
+ * failure to the `kek_rotated` path and force re-enrollment rather than
+ * permanently disabling the KEK.
+ *
+ * @param wrapped - DPAPI ciphertext produced by `dpapiProtect`.
+ * @param entropy - Must match the entropy used at protect time exactly.
+ * @returns Plaintext bytes (the DEK).
+ * @throws {Error} on DPAPI CryptographicException (mismatched key/entropy,
+ *   corrupted blob, master-key roll). NOT KekUnavailableError — see above.
+ * @throws {KekUnavailableError} on PowerShell invocation failure unrelated
+ *   to DPAPI crypto (binary missing, empty output, base64 decode error).
+ */
+async function dpapiUnprotect(wrapped, entropy) {
+    const wrappedB64 = wrapped.toString('base64');
+    const enB64 = entropy.length > 0 ? entropy.toString('base64') : null;
+    const entropyExpr = enB64 !== null ? `$en = [Convert]::FromBase64String('${enB64}');` : '$en = $null;';
+    const command = [
+        `$ct = [Convert]::FromBase64String('${wrappedB64}');`,
+        entropyExpr,
+        '$pt = [System.Security.Cryptography.ProtectedData]::Unprotect($ct, $en, [System.Security.Cryptography.DataProtectionScope]::CurrentUser);',
+        '[Convert]::ToBase64String($pt)',
+    ].join(' ');
+    let stdout;
+    let stderr;
+    try {
+        ({ stdout, stderr } = await exec('powershell.exe', [
+            '-NoProfile',
+            '-NonInteractive',
+            '-Command',
+            command,
+        ]));
+    }
+    catch (err) {
+        // Non-zero exit from PowerShell — check for CryptographicException
+        // which signals a DPAPI failure (mismatched key, corrupted blob, etc.).
+        const msg = err.message ?? '';
+        const stderrStr = err.stderr ?? '';
+        if (msg.includes('CryptographicException') || stderrStr.includes('CryptographicException')) {
+            // Plain Error so upstream maps to kek_rotated, not kek_unavailable.
+            throw new Error(`DPAPI Unprotect CryptographicException: ${stderrStr || msg}`);
+        }
+        throw new KekUnavailableError(KIND, `DPAPI Unprotect failed: ${msg}`, { cause: err });
+    }
+    if (stderr && stderr.includes('CryptographicException')) {
+        // Surfaces on some PowerShell versions via stderr without non-zero exit.
+        throw new Error(`DPAPI Unprotect CryptographicException: ${stderr.trim()}`);
+    }
+    const trimmed = stdout.trim();
+    if (trimmed.length === 0) {
+        throw new KekUnavailableError(KIND, 'DPAPI Unprotect returned empty output');
+    }
+    try {
+        return Buffer.from(trimmed, 'base64');
+    }
+    catch (err) {
+        throw new KekUnavailableError(KIND, 'DPAPI Unprotect output is not valid base64', {
+            cause: err,
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// WindowsKek — KekStrategy implementation.
+// ---------------------------------------------------------------------------
+/**
+ * @internal Test seam — no-op for Windows since DPAPI is stateless on
+ * the library side (no in-process master-blob to clear). Exists for API
+ * symmetry with `__resetKekCacheForTest` on macOS so test harness setup
+ * code can call the same pattern across platforms.
+ */
+export function __resetMasterBlobForTest() {
+    // DPAPI is self-contained per-blob; there is no in-process master-KEK
+    // cache to clear. This seam is intentionally a no-op.
+    _powershellProbeCache = undefined;
+}
+export class WindowsKek {
+    id = 'windows-dpapi';
+    /**
+     * Telemetry kind of the most recent successful wrap/unwrap. `null`
+     * before any call. Always `'windows-dpapi-powershell-shellout'` for
+     * this Tier-2 implementation.
+     */
+    _lastKind = null;
+    get kind() {
+        return this._lastKind;
+    }
+    /**
+     * Returns true when PowerShell is on PATH and the DPAPI assembly loads.
+     *
+     * Result is cached for the process lifetime. On probe failure (ENOENT,
+     * empty stdout, PowerShell Constrained Language Mode blocking the type),
+     * returns false and the daemon falls through to the legacy plaintext
+     * backend.
+     */
+    async available() {
+        return probePowerShell();
+    }
+    /**
+     * Wrap `dek` using Windows DPAPI with `aad` as optional entropy.
+     *
+     * IMPORTANT: DPAPI IS the wrap — there is no separate AES-GCM layer.
+     * The returned bytes are the raw DPAPI ciphertext blob and should be
+     * persisted as-is (e.g. to a 0600 file under the profile config dir).
+     *
+     * The `aad` buffer acts as DPAPI's `optionalEntropy`. Must match
+     * exactly at unwrap time. If `aad` is omitted or empty, `$null`
+     * entropy is used — still bound to user identity, but without the
+     * extra entropy protection.
+     *
+     * @throws {KekUnavailableError} on non-win32 platform or PowerShell failure.
+     */
+    async wrap(dek, aad) {
+        if (process.platform !== 'win32') {
+            throw new KekUnavailableError(this.id, 'Windows DPAPI KEK called on non-win32 platform');
+        }
+        if (!(await probePowerShell())) {
+            throw new KekUnavailableError(this.id, 'Windows DPAPI KEK unavailable: PowerShell or DPAPI assembly not accessible');
+        }
+        const aadBuf = aad ?? Buffer.alloc(0);
+        const out = await dpapiProtect(dek, aadBuf);
+        this._lastKind = KIND;
+        return out;
+    }
+    /**
+     * Unwrap a previously-wrapped DEK using Windows DPAPI.
+     *
+     * The `aad` buffer must match exactly what was passed to `wrap()`.
+     * DPAPI CryptographicException (mismatched entropy, corrupted blob,
+     * master-key roll after user-profile reset) surfaces as a plain `Error`
+     * so that upstream `credEnvelope.ts` can map it to the `kek_rotated`
+     * path and force re-enrollment.
+     *
+     * @throws {Error} on DPAPI CryptographicException (kek_rotated path).
+     * @throws {KekUnavailableError} on non-win32 or PowerShell invocation failure.
+     */
+    async unwrap(wrapped, aad) {
+        if (process.platform !== 'win32') {
+            throw new KekUnavailableError(this.id, 'Windows DPAPI KEK called on non-win32 platform');
+        }
+        if (!(await probePowerShell())) {
+            throw new KekUnavailableError(this.id, 'Windows DPAPI KEK unavailable: PowerShell or DPAPI assembly not accessible');
+        }
+        const aadBuf = aad ?? Buffer.alloc(0);
+        const out = await dpapiUnprotect(wrapped, aadBuf);
+        this._lastKind = KIND;
+        return out;
+    }
+    // DPAPI owns its master-key lifecycle; unprotect never creates application
+    // KEK material, so the normal unwrap is safe for the optimistic read path.
+    async unwrapExisting(wrapped, aad) {
+        return this.unwrap(wrapped, aad);
+    }
+    describe() {
+        if (process.platform !== 'win32') {
+            return 'Windows DPAPI KEK (not win32 — unavailable)';
+        }
+        if (_powershellProbeCache === true) {
+            return 'Windows DPAPI (CurrentUser) via PowerShell shellout';
+        }
+        if (_powershellProbeCache === false) {
+            return 'Windows DPAPI KEK unavailable (PowerShell or DPAPI assembly inaccessible)';
+        }
+        return 'Windows DPAPI KEK (probe pending — call available() to materialize)';
+    }
+}

package/dist/esm/kek/zeroize-registry.d.ts

@@ -0,0 +1,44 @@
+/**
+ * kek/zeroize-registry.ts — pluggable shutdown/rotation zeroize hooks.
+ *
+ * Each platform KEK module that holds in-process secret material (today
+ * only macOS's `_kekCache`; Linux and Windows when their cache layers
+ * land) calls `registerZeroizeHook(fn)` from its module body. The daemon
+ * (or any auth-core caller) invokes `zeroizeKekCaches()` on shutdown,
+ * KEK rotation, or logout to fire every registered hook.
+ *
+ * Lives in its own file (rather than inside `kek/index.ts`) so platform
+ * modules can import the registry without pulling in the cross-platform
+ * selector that re-exports them — avoids a circular import.
+ *
+ * Hook contract:
+ *   - Must be synchronous (zeroization is a buffer.fill — no I/O).
+ *   - Must be idempotent — safe to call when the cache is empty.
+ *   - Must NOT throw. Any error inside a hook is swallowed so a partial
+ *     failure on one platform's hook never blocks zeroization on the
+ *     others.
+ *   - Registration is process-lifetime; there is no de-register path
+ *     because every caller is a module-scope singleton.
+ */
+type ZeroizeHook = () => void;
+/**
+ * Register a zeroize hook. Called at module-load time from each platform
+ * KEK module that owns a cache buffer. Idempotent against the SAME
+ * function reference (does not re-add) so a test that re-imports the
+ * module does not stack duplicates.
+ */
+export declare function registerZeroizeHook(fn: ZeroizeHook): void;
+/**
+ * Fire every registered zeroize hook. Errors are swallowed — zeroization
+ * is best-effort; a failure to clear one platform's cache must not block
+ * the others, and there is no useful recovery path for the caller.
+ *
+ * Daemon callers should invoke this on:
+ *   - SIGTERM / SIGINT (graceful shutdown)
+ *   - KEK rotation (after the new wrap is materialized)
+ *   - Logout (after at-rest credentials are wiped)
+ */
+export declare function zeroizeKekCaches(): void;
+/** @internal Test seam — drop all registered hooks. */
+export declare function __resetZeroizeRegistryForTest(): void;
+export {};

package/dist/esm/kek/zeroize-registry.js

@@ -0,0 +1,58 @@
+/**
+ * kek/zeroize-registry.ts — pluggable shutdown/rotation zeroize hooks.
+ *
+ * Each platform KEK module that holds in-process secret material (today
+ * only macOS's `_kekCache`; Linux and Windows when their cache layers
+ * land) calls `registerZeroizeHook(fn)` from its module body. The daemon
+ * (or any auth-core caller) invokes `zeroizeKekCaches()` on shutdown,
+ * KEK rotation, or logout to fire every registered hook.
+ *
+ * Lives in its own file (rather than inside `kek/index.ts`) so platform
+ * modules can import the registry without pulling in the cross-platform
+ * selector that re-exports them — avoids a circular import.
+ *
+ * Hook contract:
+ *   - Must be synchronous (zeroization is a buffer.fill — no I/O).
+ *   - Must be idempotent — safe to call when the cache is empty.
+ *   - Must NOT throw. Any error inside a hook is swallowed so a partial
+ *     failure on one platform's hook never blocks zeroization on the
+ *     others.
+ *   - Registration is process-lifetime; there is no de-register path
+ *     because every caller is a module-scope singleton.
+ */
+const _hooks = [];
+/**
+ * Register a zeroize hook. Called at module-load time from each platform
+ * KEK module that owns a cache buffer. Idempotent against the SAME
+ * function reference (does not re-add) so a test that re-imports the
+ * module does not stack duplicates.
+ */
+export function registerZeroizeHook(fn) {
+    if (_hooks.indexOf(fn) === -1) {
+        _hooks.push(fn);
+    }
+}
+/**
+ * Fire every registered zeroize hook. Errors are swallowed — zeroization
+ * is best-effort; a failure to clear one platform's cache must not block
+ * the others, and there is no useful recovery path for the caller.
+ *
+ * Daemon callers should invoke this on:
+ *   - SIGTERM / SIGINT (graceful shutdown)
+ *   - KEK rotation (after the new wrap is materialized)
+ *   - Logout (after at-rest credentials are wiped)
+ */
+export function zeroizeKekCaches() {
+    for (const hook of _hooks) {
+        try {
+            hook();
+        }
+        catch {
+            /* swallow — zeroize is best-effort and must not throw */
+        }
+    }
+}
+/** @internal Test seam — drop all registered hooks. */
+export function __resetZeroizeRegistryForTest() {
+    _hooks.length = 0;
+}