@skrr-ai/auth-core 0.1.2

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

@@ -0,0 +1,112 @@
+import type { KekStrategy } from './types.js';
+/**
+ * Stable telemetry kind string — fleet dashboards size the macOS cohort
+ * by this value. Only one backend ships in this module today.
+ */
+declare const KIND_SHELLOUT = "macos-keychain-shellout";
+/**
+ * @internal Test seam — inject a mock execFile for hermetic tests so the
+ * suite never touches the real Keychain. Reset to `null` to restore the
+ * real `child_process.execFile`.
+ */
+type ExecFileLike = (file: string, args: readonly string[], options?: {
+    encoding?: BufferEncoding;
+    stdio?: unknown;
+}) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export declare function __setExecFileForTest(fn: ExecFileLike | null): void;
+/** @internal Test seam — clear the security-binary probe cache. */
+export declare function __resetSecurityProbeCacheForTest(): void;
+/** @internal Test seam — clear the resolved-keychain cache. */
+export declare function __resetResolvedKeychainCacheForTest(): void;
+/**
+ * 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 declare function zeroizeMacosKekCache(): void;
+/** @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 declare function __resetKekCacheForTest(): void;
+/**
+ * @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 declare function __getKekCacheForTest(service?: string, account?: string): Buffer | null;
+export declare class MacosKek implements KekStrategy {
+    readonly 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. */
+    private _lastKind;
+    /** Keychain `service` (the `-s` arg) this instance reads/writes. */
+    private readonly service;
+    /** Keychain `account` (the `-a` arg) this instance reads/writes. */
+    private readonly 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?: {
+        service?: string;
+        account?: string;
+    });
+    /**
+     * 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(): typeof KIND_SHELLOUT | null;
+    /**
+     * `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.
+     */
+    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 {};