@skrr-ai/auth-core 0.1.2

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

@@ -0,0 +1,89 @@
+/**
+ * kek/index.ts — platform selector for the Key Encryption Key strategy.
+ *
+ * Resolves a single KEK implementation based on `process.platform` at
+ * call time. The returned strategy may report `available=false` (e.g.,
+ * the native binding hasn't shipped on the current platform yet) — the
+ * daemon's integration code MUST honor that and fall through to the
+ * legacy plaintext path with a `cred_envelope.kek_unavailable` event.
+ *
+ * Test seam: `__setKekStrategyForTest()` lets unit tests inject a
+ * synthetic strategy with a deterministic in-memory KEK so the
+ * dual-read / re-encrypt-on-migration paths can be exercised without a
+ * real platform binding.
+ */
+import type { KekStrategy } from './types.js';
+export type { KekStrategy } from './types.js';
+export { KekUnavailableError } from './types.js';
+export { MacosKek } from './macos.js';
+export { LinuxKek } from './linux.js';
+export { WindowsKek } from './windows.js';
+export { zeroizeKekCaches, registerZeroizeHook } from './zeroize-registry.js';
+/**
+ * @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`.
+ */
+export declare function __setKekStrategyForTest(strategy: KekStrategy | null): void;
+/**
+ * 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).
+ */
+export declare function getKekStrategy(): KekStrategy;
+/**
+ * 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.
+ */
+export declare class InMemoryKek implements KekStrategy {
+    readonly id = "in-memory-test";
+    private readonly key;
+    constructor(key: Buffer);
+    /**
+     * 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(): string;
+    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;
+}
+/**
+ * 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.
+ */
+export declare class UnavailableKek implements KekStrategy {
+    readonly id = "unavailable-test";
+    get kind(): string;
+    available(): Promise<boolean>;
+    wrap(): Promise<Buffer>;
+    unwrap(): Promise<Buffer>;
+    describe(): string;
+}

package/dist/esm/kek/index.js

@@ -0,0 +1,162 @@
+import { KekUnavailableError } from './types.js';
+import { MacosKek } from './macos.js';
+import { LinuxKek } from './linux.js';
+import { WindowsKek } from './windows.js';
+export { KekUnavailableError } from './types.js';
+export { MacosKek } from './macos.js';
+export { LinuxKek } from './linux.js';
+export { WindowsKek } from './windows.js';
+export { zeroizeKekCaches, registerZeroizeHook } from './zeroize-registry.js';
+/**
+ * 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 KekUnavailableError(this.id, `KEK unsupported on platform ${this.platform}`);
+    }
+    async unwrap() {
+        throw new 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`.
+ */
+export 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).
+ */
+export 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 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 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 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.
+ */
+export 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 import('../credentialEnvelope.js');
+        return Buffer.from(serialize(sealBuffer(dek, this.key, aad)), 'utf-8');
+    }
+    async unwrap(wrapped, aad) {
+        const { deserialize, openBuffer } = await import('../credentialEnvelope.js');
+        const sealed = deserialize(wrapped.toString('utf-8'));
+        if (!sealed)
+            throw new 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)';
+    }
+}
+/**
+ * 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.
+ */
+export class UnavailableKek {
+    id = 'unavailable-test';
+    get kind() {
+        return 'unavailable-test';
+    }
+    async available() {
+        return false;
+    }
+    async wrap() {
+        throw new KekUnavailableError(this.id, 'UnavailableKek: wrap called while unavailable');
+    }
+    async unwrap() {
+        throw new KekUnavailableError(this.id, 'UnavailableKek: unwrap called while unavailable');
+    }
+    describe() {
+        return 'unavailable test KEK (forces the kek_unavailable branch)';
+    }
+}

package/dist/esm/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 {};