@skrr-ai/auth-core 0.1.2

package/dist/cjs/kek/index.js

@@ -0,0 +1,208 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnavailableKek = exports.InMemoryKek = exports.registerZeroizeHook = exports.zeroizeKekCaches = exports.WindowsKek = exports.LinuxKek = exports.MacosKek = exports.KekUnavailableError = void 0;
+exports.__setKekStrategyForTest = __setKekStrategyForTest;
+exports.getKekStrategy = getKekStrategy;
+const types_js_1 = require("./types.js");
+const macos_js_1 = require("./macos.js");
+const linux_js_1 = require("./linux.js");
+const windows_js_1 = require("./windows.js");
+var types_js_2 = require("./types.js");
+Object.defineProperty(exports, "KekUnavailableError", { enumerable: true, get: function () { return types_js_2.KekUnavailableError; } });
+var macos_js_2 = require("./macos.js");
+Object.defineProperty(exports, "MacosKek", { enumerable: true, get: function () { return macos_js_2.MacosKek; } });
+var linux_js_2 = require("./linux.js");
+Object.defineProperty(exports, "LinuxKek", { enumerable: true, get: function () { return linux_js_2.LinuxKek; } });
+var windows_js_2 = require("./windows.js");
+Object.defineProperty(exports, "WindowsKek", { enumerable: true, get: function () { return windows_js_2.WindowsKek; } });
+var zeroize_registry_js_1 = require("./zeroize-registry.js");
+Object.defineProperty(exports, "zeroizeKekCaches", { enumerable: true, get: function () { return zeroize_registry_js_1.zeroizeKekCaches; } });
+Object.defineProperty(exports, "registerZeroizeHook", { enumerable: true, get: function () { return zeroize_registry_js_1.registerZeroizeHook; } });
+/**
+ * Strategy used when the current platform has no implementation. Always
+ * unavailable; never throws on probe. Provides an honest `id` so fleet
+ * telemetry can distinguish "we have no KEK on this platform" from
+ * "the platform's KEK probe failed."
+ */
+class UnsupportedPlatformKek {
+    id;
+    platform;
+    constructor(platform) {
+        this.platform = platform;
+        this.id = `unsupported-${platform}`;
+    }
+    async available() {
+        return false;
+    }
+    async wrap() {
+        throw new types_js_1.KekUnavailableError(this.id, `KEK unsupported on platform ${this.platform}`);
+    }
+    async unwrap() {
+        throw new types_js_1.KekUnavailableError(this.id, `KEK unsupported on platform ${this.platform}`);
+    }
+    describe() {
+        return `unsupported platform: ${this.platform}`;
+    }
+}
+let _override = null;
+/**
+ * @internal Test-only seam — inject a synthetic KEK strategy that wraps
+ * with a fixed in-memory key. Resets to platform default when called
+ * with `null`.
+ */
+function __setKekStrategyForTest(strategy) {
+    _override = strategy;
+}
+/**
+ * Resolve the KEK strategy for the current process. Returns the test
+ * override when set; otherwise selects by `process.platform`.
+ *
+ * Idempotent and side-effect-free — the strategy is constructed fresh
+ * on each call. Implementations must keep their own caches if probing
+ * is expensive (none of the current stubs do).
+ */
+function getKekStrategy() {
+    if (_override)
+        return _override;
+    switch (process.platform) {
+        case 'darwin':
+            // C5 (shipped): macOS uses the `security(1)` shellout backend with
+            // a Secure Enclave NAPI binding preferred when present. Backend
+            // selection happens inside MacosKek; no dispatch change required.
+            return new macos_js_1.MacosKek();
+        case 'linux':
+            // TODO(L12): Linux libsecret + machine-id-derived KEK is still a
+            // stub. Planned approach: shellout to `secret-tool`, modeled after
+            // the macOS shellout pattern shipped in C5. See
+            // `docs/daemon-auth-l12-kek-platform-bindings.md` §5.
+            return new linux_js_1.LinuxKek();
+        case 'win32':
+            // TODO(L12): Windows DPAPI KEK is still a stub. Planned approach:
+            // PowerShell shellout invoking ProtectedData.Protect (or a future
+            // dpapi NAPI binding). See
+            // `docs/daemon-auth-l12-kek-platform-bindings.md` §5.
+            return new windows_js_1.WindowsKek();
+        default:
+            return new UnsupportedPlatformKek(process.platform);
+    }
+}
+/**
+ * In-memory KEK strategy backed by a fixed buffer. Useful for tests and
+ * for a future `--kek=file:<path>` opt-in for users who explicitly
+ * waive platform-native protection (e.g., headless CI on a hardened
+ * VM where DPAPI isn't reachable). Do NOT default to this in production
+ * paths — it provides no protection beyond filesystem permissions on
+ * whatever holds the buffer.
+ */
+class InMemoryKek {
+    id = 'in-memory-test';
+    key;
+    constructor(key) {
+        if (!Buffer.isBuffer(key) || key.length !== 32) {
+            throw new TypeError('InMemoryKek: key must be a 32-byte Buffer');
+        }
+        this.key = Buffer.from(key);
+    }
+    /**
+     * Stable backend identifier surfaced via `KekStrategy.kind`. Distinct
+     * from the MacosKek shellout / NAPI kinds so telemetry filters can
+     * exclude in-memory test traffic from fleet dashboards.
+     */
+    get kind() {
+        return 'in-memory-test';
+    }
+    async available() {
+        return true;
+    }
+    async wrap(dek, aad) {
+        const { sealBuffer, serialize } = await Promise.resolve().then(() => __importStar(require('../credentialEnvelope.js')));
+        return Buffer.from(serialize(sealBuffer(dek, this.key, aad)), 'utf-8');
+    }
+    async unwrap(wrapped, aad) {
+        const { deserialize, openBuffer } = await Promise.resolve().then(() => __importStar(require('../credentialEnvelope.js')));
+        const sealed = deserialize(wrapped.toString('utf-8'));
+        if (!sealed)
+            throw new types_js_1.KekUnavailableError(this.id, 'InMemoryKek: malformed wrapped blob');
+        return openBuffer(sealed, this.key, aad);
+    }
+    async unwrapExisting(wrapped, aad) {
+        return this.unwrap(wrapped, aad);
+    }
+    describe() {
+        return 'in-memory test KEK (NOT FOR PRODUCTION)';
+    }
+}
+exports.InMemoryKek = InMemoryKek;
+/**
+ * Test double for the KEK-UNAVAILABLE branch — the twin of `InMemoryKek`.
+ *
+ * It exists because "no KEK on this platform" cannot be expressed by passing
+ * `null` to `__setKekStrategyForTest`. `null` means "use the platform
+ * default", and the platform defaults do not agree: `LinuxKek` essentially
+ * always resolves (tier-3 derives a KEK from machine identity when libsecret
+ * is absent), `MacosKek` resolves only when a login keychain can be found —
+ * which a test that sandboxes `HOME` accidentally prevents — and `WindowsKek`
+ * is still a stub. A suite that wants the unavailable branch and passes `null`
+ * is therefore not testing that branch; it is testing which machine it landed
+ * on, and it flips from green to red when the machine changes.
+ *
+ * That is not hypothetical: four daemon suites asserting fail-closed behaviour
+ * passed on macOS purely because their temp `HOME` hid the keychain, and went
+ * red the first time CI ever executed them on Linux.
+ *
+ * `wrap`/`unwrap` throw rather than returning junk, matching the contract in
+ * `types.ts`: a strategy that reports unavailable must never silently produce
+ * ciphertext a caller could mistake for protected material.
+ */
+class UnavailableKek {
+    id = 'unavailable-test';
+    get kind() {
+        return 'unavailable-test';
+    }
+    async available() {
+        return false;
+    }
+    async wrap() {
+        throw new types_js_1.KekUnavailableError(this.id, 'UnavailableKek: wrap called while unavailable');
+    }
+    async unwrap() {
+        throw new types_js_1.KekUnavailableError(this.id, 'UnavailableKek: unwrap called while unavailable');
+    }
+    describe() {
+        return 'unavailable test KEK (forces the kek_unavailable branch)';
+    }
+}
+exports.UnavailableKek = UnavailableKek;

package/dist/cjs/kek/linux.d.ts

@@ -0,0 +1,92 @@
+import type { KekStrategy } from './types.js';
+/** Stable telemetry kind strings — one per backend tier. */
+declare const KIND_LIBSECRET = "linux-libsecret-shellout";
+declare const KIND_HKDF = "linux-machineid-hkdf";
+/**
+ * Type for the execFile mock. Accepts an optional `input` in options so
+ * tests can assert the stdin payload passed to `secret-tool store`.
+ */
+type ExecFileLike = (file: string, args: readonly string[], options?: {
+    encoding?: BufferEncoding;
+    input?: string;
+}) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+/**
+ * @internal Test seam — inject a mock execFile for hermetic tests so the
+ * suite never touches the real Secret Service. Reset to `null` to restore
+ * the real `child_process.execFile`.
+ */
+export declare function __setExecFileForTest(fn: ExecFileLike | null): void;
+type ReadFileSyncLike = (path: string, encoding: BufferEncoding) => string;
+/**
+ * @internal Test seam — inject a mock readFileSync so Tier-3 derivation
+ * tests can drive deterministic IKM without writing to /proc or /etc.
+ * Reset to `null` to restore the real `fs.readFileSync`. Pass `null` to
+ * also clear the tier selection + KEK cache so the next call re-probes.
+ */
+export declare function __setFsForTest(fn: ReadFileSyncLike | null): void;
+/**
+ * Zero out and drop every in-process master-KEK cache buffer (both the
+ * Tier-2 by-service map and the Tier-3 single buffer).
+ *
+ * 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.
+ *   - Logout flows that wipe at-rest credentials.
+ *
+ * Idempotent — safe to call when the caches are already empty.
+ */
+export declare function zeroizeLinuxKekCache(): void;
+/** @internal Test seam — clear the in-process master-KEK cache + tier
+ *  selection. Routes through the production zeroize helper so the
+ *  test-reset path exercises the same buffer-fill that ships in
+ *  production, and additionally clears `_tierSelection` so a subsequent
+ *  test re-probes (otherwise Tier-3 caching across tests poisons later
+ *  cases). */
+export declare function __resetKekCacheForTest(): void;
+export declare class LinuxKek implements KekStrategy {
+    readonly id = "linux-libsecret-machineid";
+    private _lastKind;
+    private readonly service;
+    private readonly account;
+    /**
+     * Construct a Linux KEK strategy.
+     *
+     * @param opts.service Optional Secret Service `service` attribute used
+     *   by Tier-2 `secret-tool lookup`/`store`. Defaults to
+     *   `'ai.skrr.daemon.kek'`. Override only for test isolation /
+     *   smoke tests; production callers should use the default so different
+     *   daemon processes on the same host share the same KEK and can unwrap
+     *   each other's persisted credentials. Ignored on the Tier-3 (HKDF)
+     *   path. Callers that override are responsible for cleaning up the
+     *   corresponding Secret Service entry when done.
+     * @param opts.account Optional Secret Service `account` attribute.
+     *   Defaults to `'master-kek-v1'`. Same scoping rules as `service`.
+     */
+    constructor(opts?: {
+        service?: string;
+        account?: string;
+    });
+    /**
+     * Telemetry kind of the most recent successful wrap/unwrap. `null` before
+     * any call. After the first successful wrap or unwrap, one of:
+     *   - `'linux-libsecret-shellout'` (Tier-2)
+     *   - `'linux-machineid-hkdf'` (Tier-3)
+     */
+    get kind(): typeof KIND_LIBSECRET | typeof KIND_HKDF | null;
+    /**
+     * `available()` is true on Linux when EITHER backend can satisfy a
+     * wrap: libsecret is reachable, or `/etc/machine-id` exists so Tier-3
+     * derivation can succeed. Probe results are cached for the process
+     * lifetime.
+     */
+    available(): Promise<boolean>;
+    wrap(dek: Buffer, aad?: Buffer): Promise<Buffer>;
+    unwrap(wrapped: Buffer, aad?: Buffer): Promise<Buffer>;
+    unwrapExisting(wrapped: Buffer, aad?: Buffer): Promise<Buffer>;
+    describe(): string;
+}
+export {};