@skrr-ai/auth-core 0.1.2

package/dist/esm/credentialEnvelopeBridge.js

@@ -0,0 +1,620 @@
+/**
+ * credentialEnvelopeBridge.ts — composed L12 runtime (init, transforms, lock).
+ *
+ * Lifts the previously-duplicated `daemon/src/credEnvelope.ts` and
+ * `cli/src/lib/cred-envelope.ts` modules into a single shared
+ * implementation. The daemon and CLI both consume this module so they
+ * land on the SAME on-disk artifacts:
+ *
+ *   <configDir>/profiles/<p>/cred-dek-wrapped     — KEK-wrapped DEK
+ *   <configDir>/profiles/<p>/cred-envelope.lock   — proper-lockfile sentinel
+ *
+ * `<configDir>` is supplied by the consumer via `configureAuthCore({configDir})`
+ * — both binaries today resolve to `~/.skrr` so first-enrollment races
+ * between `sky` and `oversky` serialize against the same lockfile.
+ *
+ * NAMING NOTE — the suffix `Bridge` distinguishes this composed runtime
+ * (init + sign + persist + telemetry) from the pure-crypto primitive
+ * file `credentialEnvelope.ts` it composes.
+ *
+ * Failure mode contract:
+ *   - KEK unavailable on this platform: transforms are passthrough; one
+ *     `cred_envelope.kek_unavailable` telemetry event fires at init.
+ *   - Init failure: transforms passthrough; never crashes the consumer.
+ *   - Daemon configures `credEnvelopeFailClosed=true` so writes throw
+ *     when not active. CLI leaves it unset; legacy `OVERSKY_KEK_REQUIRED=1`
+ *     env var is still honored as a back-compat trigger.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import lockfile from 'proper-lockfile';
+import { buildCredentialAad, decrypt as credEnvelopeDecrypt, deserialize as credEnvelopeDeserialize, encrypt as credEnvelopeEncrypt, isEnvelopeString as isCredEnvelopeString, generateDek, serialize as credEnvelopeSerialize, } from './credentialEnvelope.js';
+import { getKekStrategy, zeroizeKekCaches } from './kek/index.js';
+import { emitAuthTelemetry, getAuthConfigDir, getAuthLogger, getCredEnvelopeFailClosed, } from './runtime.js';
+/**
+ * Account name the wrapped DEK lives under (file fallback). Keeping the
+ * literal here so a future rename surfaces as a single grep target.
+ */
+const ACCOUNT_CRED_DEK_WRAPPED = 'cred-dek-wrapped';
+let _state = { kind: 'uninit' };
+/**
+ * Sticky flag set by `initCredEnvelope` when the on-disk wrapped DEK
+ * exists but unwrap fails under a currently-available KEK — strong
+ * evidence the KEK was rotated underneath us. Persists across the init
+ * pass so `describeCredEnvelopeState()` and the `oversky status` surface
+ * can explain why local credentials were just re-enrolled.
+ */
+let _kekRotationDetected = false;
+/** @internal Test seam — force-set state, returns previous. */
+export function __setStateForTest(next) {
+    const prev = _state;
+    _state = next;
+    return prev;
+}
+/** @internal Test seam — read state for assertions. */
+export function __getStateForTest() {
+    return _state;
+}
+/**
+ * Per-profile config directory. Uses the consumer-supplied configDir from
+ * `configureAuthCore()`; the whole point of this module is shared on-disk
+ * artifacts, so daemon/CLI MUST configure the same root.
+ */
+function profileConfigDir(profile) {
+    return path.join(getAuthConfigDir(), 'profiles', profile);
+}
+function wrappedDekFilePath(profile) {
+    return path.join(profileConfigDir(profile), ACCOUNT_CRED_DEK_WRAPPED);
+}
+/**
+ * Atomic 0600 write — tmp+fsync+rename+dir-fsync. Same shape as the
+ * original daemon/CLI implementations so partial-write races between
+ * `sky` and `oversky` produce the same on-disk transitions.
+ */
+function atomicWrite0600(target, value) {
+    const dir = path.dirname(target);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tmp = `${target}.tmp.${process.pid}.${Date.now()}`;
+    const fd = fs.openSync(tmp, 'w', 0o600);
+    try {
+        fs.writeSync(fd, value);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    fs.renameSync(tmp, target);
+    try {
+        const dirFd = fs.openSync(dir, 'r');
+        try {
+            fs.fsyncSync(dirFd);
+        }
+        finally {
+            fs.closeSync(dirFd);
+        }
+    }
+    catch {
+        /* best-effort — Windows / some BSDs reject dir fsync */
+    }
+}
+/**
+ * Telemetry shim. Routes through the consumer-supplied logEvent sink
+ * (daemon: structured event log; CLI: typically no-op or stderr at DEBUG).
+ * Also writes to `getAuthLogger().warn` on failure so an operator running
+ * with verbose logs sees the signal even without a configured event sink.
+ *
+ * The event name passed in is the FULLY-QUALIFIED `cred_envelope.*` form
+ * because daemon-side telemetry consumers (`event-log.ts`, dashboards,
+ * spec assertions) key off the prefixed name. Do not strip the prefix.
+ */
+function emit(eventName, success, metadata) {
+    emitAuthTelemetry({
+        timestamp: new Date().toISOString(),
+        eventType: 'auth',
+        success,
+        metadata: { event: eventName, ...metadata },
+    });
+    if (!success) {
+        getAuthLogger().warn(`[credEnvelope] ${eventName}`, metadata);
+    }
+}
+// ---------------------------------------------------------------------------
+// First-enrollment lockfile (gap G5).
+//
+// Two daemon processes that race to enroll a fresh DEK under the same
+// profile would each generate a different DEK, wrap each, and the second
+// rename-write would silently win — making any envelopes wrapped under
+// the loser's DEK permanently unrecoverable. The lock serializes this
+// window. Mirrors `withAuthLock` in `packages/auth-core/src/refresh.ts`.
+// ---------------------------------------------------------------------------
+const CRED_LOCK_STALE_MS = 30_000;
+const CRED_LOCK_RETRY_MS = 100;
+// Exponential retry capped at 400 ms: 50 retries are ~20 s total, not 5 s.
+const CRED_LOCK_MAX_RETRIES = 50;
+function credEnvelopeLockPath(profile) {
+    return path.join(profileConfigDir(profile), 'cred-envelope.lock');
+}
+/**
+ * Acquire the cross-process credential-envelope lock for a profile, run
+ * the body, release in `finally`. Emits `cred_envelope.lock_acquired`
+ * and `cred_envelope.lock_released` so contention shows up in telemetry.
+ *
+ * The lock file is a sentinel (mode 0600) — `proper-lockfile` locks the
+ * sentinel rather than the real wrapped-DEK file because the latter is
+ * subject to atomic tmp+rename writes that would race with the lock
+ * adapter on some filesystems.
+ */
+async function withCredEnvelopeLock(profile, body) {
+    const lockPath = credEnvelopeLockPath(profile);
+    const dir = path.dirname(lockPath);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (!fs.existsSync(lockPath)) {
+        fs.writeFileSync(lockPath, '', { mode: 0o600 });
+    }
+    const acquireStart = Date.now();
+    const release = await lockfile.lock(lockPath, {
+        stale: CRED_LOCK_STALE_MS,
+        retries: {
+            retries: CRED_LOCK_MAX_RETRIES,
+            minTimeout: CRED_LOCK_RETRY_MS,
+            maxTimeout: CRED_LOCK_RETRY_MS * 4,
+            factor: 1.5,
+        },
+    });
+    const acquiredAt = Date.now();
+    emit('cred_envelope.lock_acquired', true, {
+        profile,
+        waitedMs: acquiredAt - acquireStart,
+    });
+    try {
+        return await body();
+    }
+    finally {
+        const heldForMs = Date.now() - acquiredAt;
+        emit('cred_envelope.lock_released', true, {
+            profile,
+            waitedMs: heldForMs,
+        });
+        try {
+            await release();
+        }
+        catch {
+            /* best-effort — stale-lock fallback handles next-acquire */
+        }
+    }
+}
+/**
+ * Initialize the envelope path. Idempotent — second call when state is
+ * non-uninit returns immediately.
+ *
+ * Order:
+ *   1. Probe KEK; unavailable → disabled+kek_unavailable.
+ *   2. Try to read+unwrap an existing DEK; success → active.
+ *   3. Generate fresh DEK, wrap, persist atomically; → active.
+ *   4. Any throw → disabled+init_failed; transforms stay passthrough.
+ */
+export async function initCredEnvelope(profile) {
+    if (_state.kind !== 'uninit')
+        return;
+    if (typeof profile !== 'string' || profile.length === 0) {
+        _state = { kind: 'disabled', reason: 'init_failed' };
+        emit('cred_envelope.init_failed', false, { reason: 'empty_profile' });
+        return;
+    }
+    let kek;
+    try {
+        kek = getKekStrategy();
+    }
+    catch (err) {
+        _state = { kind: 'disabled', reason: 'platform_unsupported' };
+        emit('cred_envelope.init_failed', false, {
+            reason: 'kek_resolve_threw',
+            message: err?.message ?? 'unknown',
+        });
+        return;
+    }
+    let kekAvailable = false;
+    try {
+        kekAvailable = await kek.available();
+    }
+    catch {
+        kekAvailable = false;
+    }
+    if (!kekAvailable) {
+        _state = { kind: 'disabled', reason: 'kek_unavailable' };
+        emit('cred_envelope.kek_unavailable', false, {
+            kekId: kek.id,
+            profile,
+            describe: kek.describe(),
+        });
+        return;
+    }
+    const aad = buildCredentialAad(profile);
+    const targetPath = wrappedDekFilePath(profile);
+    // Capture the kek's tier-aware kind once at init so transform-side events
+    // can include it without holding a live `kek` reference. macOS sets `kind`
+    // only after the first wrap/unwrap; null here is honest.
+    const captureKind = () => typeof kek.kind === 'string' || kek.kind === null ? (kek.kind ?? null) : null;
+    // Existing wrapped DEKs are immutable between enrollments and are published
+    // with atomic rename. Reading and unwrapping one therefore does not need the
+    // first-enrollment mutex. Keeping this hot path outside the lock matters for
+    // short-lived CLI processes: a burst of read-only `sky` commands used to
+    // serialize here, and contenders could outlive the CLI's bounded auth
+    // prefetch even though there was no write for them to coordinate.
+    //
+    // Any miss or unwrap failure falls through to the locked path below. That
+    // path re-reads the file after acquiring the mutex before it decides whether
+    // to enroll or rotate, so a concurrent writer can never make this optimistic
+    // read create a second DEK or produce a false rotation signal.
+    try {
+        if (!kek.unwrapExisting)
+            throw new Error('KEK has no read-only unwrap path');
+        const wrappedBytes = fs.readFileSync(targetPath);
+        const candidate = await kek.unwrapExisting(wrappedBytes, aad);
+        if (candidate.length === 32) {
+            _state = {
+                kind: 'active',
+                dek: candidate,
+                kekId: kek.id,
+                kekKind: captureKind(),
+                profile,
+            };
+            emit('cred_envelope.active', true, {
+                kekId: kek.id,
+                kekKind: captureKind(),
+                profile,
+                existingDekFastPath: true,
+            });
+            return;
+        }
+        candidate.fill(0);
+    }
+    catch {
+        // The locked path owns diagnostics and recovery. In particular, it
+        // distinguishes a stable unwrap failure (probable KEK rotation) from a
+        // file that another process replaced between this read and lock acquire.
+    }
+    let dek = null;
+    let unwrapAttemptedAndFailed = false;
+    await withCredEnvelopeLock(profile, async () => {
+        // Re-stat after acquiring the lock — a sibling sky/oversky may have
+        // enrolled while we were waiting. Without this, both processes would
+        // proceed to "first-run enrollment" and the second writer's DEK
+        // would silently win, orphaning the first writer's DEK and every
+        // credential it has already wrapped.
+        let wrappedBytes = null;
+        try {
+            if (fs.existsSync(targetPath)) {
+                wrappedBytes = fs.readFileSync(targetPath);
+            }
+        }
+        catch (err) {
+            emit('cred_envelope.init_failed', false, {
+                reason: 'wrapped_dek_read_threw',
+                message: err?.message ?? 'unknown',
+            });
+            wrappedBytes = null;
+        }
+        if (wrappedBytes !== null) {
+            try {
+                const candidate = await kek.unwrap(wrappedBytes, aad);
+                if (candidate.length !== 32) {
+                    emit('cred_envelope.init_failed', false, {
+                        reason: 'unwrapped_dek_wrong_length',
+                        length: candidate.length,
+                        kekKind: captureKind(),
+                    });
+                    unwrapAttemptedAndFailed = true;
+                }
+                else {
+                    dek = candidate;
+                }
+            }
+            catch (err) {
+                emit('cred_envelope.unwrap.failed', false, {
+                    reason: 'wrapped_dek_unwrap_threw',
+                    kekId: kek.id,
+                    kekKind: captureKind(),
+                    message: err?.message ?? 'unknown',
+                });
+                unwrapAttemptedAndFailed = true;
+            }
+        }
+        // KEK rotation detection (gap G4). If the wrapped file was present,
+        // KEK reported `available=true`, but unwrap threw — the most likely
+        // explanation is the KEK was rotated underneath us. Surface this as
+        // a distinct event so dashboards can count rotations separately
+        // from genuinely-corrupt blobs, while still falling through to a
+        // fresh enrollment so the daemon stays operational.
+        if (unwrapAttemptedAndFailed && dek === null) {
+            _kekRotationDetected = true;
+            emit('cred_envelope.kek_rotated', false, {
+                kekId: kek.id,
+                kekKind: captureKind(),
+                profile,
+                message: 'wrapped DEK present but unwrap failed under available KEK; treating as rotation and re-enrolling',
+            });
+        }
+        // First-run enrollment if no DEK yet.
+        if (dek === null) {
+            try {
+                dek = generateDek();
+                const wrapped = await kek.wrap(dek, aad);
+                atomicWrite0600(targetPath, wrapped);
+                emit('cred_envelope.dek_enrolled', true, {
+                    kekId: kek.id,
+                    kekKind: captureKind(),
+                    profile,
+                    ...(unwrapAttemptedAndFailed ? { reEnrolledAfterRotation: true } : {}),
+                });
+            }
+            catch (err) {
+                _state = { kind: 'disabled', reason: 'init_failed' };
+                emit('cred_envelope.init_failed', false, {
+                    reason: 'enrollment_failed',
+                    kekId: kek.id,
+                    kekKind: captureKind(),
+                    message: err?.message ?? 'unknown',
+                });
+                return;
+            }
+        }
+        _state = {
+            kind: 'active',
+            dek: dek,
+            kekId: kek.id,
+            kekKind: captureKind(),
+            profile,
+        };
+        emit('cred_envelope.active', true, {
+            kekId: kek.id,
+            kekKind: captureKind(),
+            profile,
+            ...(unwrapAttemptedAndFailed ? { reEnrolledAfterRotation: true } : {}),
+        });
+    });
+}
+/**
+ * Reset state. With `clearOnDisk` deletes the wrapped DEK file too —
+ * used by `oversky logout` / `sky logout`. Zeroes the in-memory DEK
+ * before dropping state for forward secrecy on the active credential.
+ */
+export async function resetCredEnvelope(opts) {
+    if (opts?.clearOnDisk && opts.profile) {
+        try {
+            fs.unlinkSync(wrappedDekFilePath(opts.profile));
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT') {
+                emit('cred_envelope.clear_failed', false, {
+                    profile: opts.profile,
+                    message: err?.message ?? 'unknown',
+                });
+            }
+        }
+    }
+    if (_state.kind === 'active') {
+        _state.dek.fill(0);
+    }
+    _state = { kind: 'uninit' };
+    _kekRotationDetected = false;
+}
+/**
+ * Idempotent shutdown — must be called from the daemon's graceful-exit
+ * handler (SIGTERM / SIGINT). Zeroes the in-memory DEK and drops the
+ * platform KEK caches so neither lingers in process memory after the
+ * exit path begins. The KEK-cache zeroize hooks come from the platform
+ * registry exposed by `@skrr-ai/auth-core` (`zeroizeKekCaches()`); each
+ * platform module registers its hook at module-load time.
+ *
+ * Synchronous so the caller's exit path can run it without managing a
+ * promise chain. Distinct from `resetCredEnvelope` because:
+ *   - shutdown does NOT delete on-disk state (the next process restart
+ *     should still find the wrapped DEK).
+ *   - shutdown ALSO zeroes platform KEK caches (resetCredEnvelope leaves
+ *     them resident so the next reactivation can reuse them).
+ */
+let _shutdownDone = false;
+export function shutdownCredEnvelope() {
+    if (_shutdownDone)
+        return;
+    _shutdownDone = true;
+    try {
+        if (_state.kind === 'active') {
+            _state.dek.fill(0);
+        }
+    }
+    catch {
+        /* swallow — shutdown is best-effort */
+    }
+    try {
+        zeroizeKekCaches();
+    }
+    catch {
+        /* swallow — shutdown is best-effort */
+    }
+    _state = { kind: 'uninit' };
+    _kekRotationDetected = false;
+}
+/** @internal Test seam — re-arm `shutdownCredEnvelope` so it can run again. */
+export function __resetShutdownGuardForTest() {
+    _shutdownDone = false;
+}
+/**
+ * True iff the envelope path is initialized AND active. Hot-path
+ * predicate used by sync transforms; never throws.
+ */
+export function isCredEnvelopeActive() {
+    return _state.kind === 'active';
+}
+/**
+ * Operator-readable summary of envelope state. Used by `oversky status`
+ * and CLI debug commands. Never includes the DEK or any key material.
+ *
+ * `kekRotated` is true when the most recent init pass detected a wrapped
+ * DEK that could not be unwrapped under the currently-available KEK and
+ * had to fall back to a fresh enrollment. Operators see this in
+ * `oversky status`; clears on the next clean `resetCredEnvelope`.
+ */
+export function describeCredEnvelopeState() {
+    if (_state.kind === 'disabled') {
+        return {
+            kind: 'disabled',
+            reason: _state.reason,
+            ...(_kekRotationDetected ? { kekRotated: true } : {}),
+        };
+    }
+    if (_state.kind === 'active') {
+        return {
+            kind: 'active',
+            kekId: _state.kekId,
+            kekKind: _state.kekKind,
+            profile: _state.profile,
+            ...(_kekRotationDetected ? { kekRotated: true } : {}),
+        };
+    }
+    return { kind: 'uninit' };
+}
+/**
+ * Sync write transform. Returns the wrapped serialized form when active.
+ *
+ * Behavior when not active:
+ *   - If `credEnvelopeFailClosed` was set via `configureAuthCore()` (or
+ *     `OVERSKY_KEK_REQUIRED=1` is set as a back-compat trigger), emits
+ *     `cred_envelope.wrap.refused` and throws — the caller must not
+ *     write plaintext.
+ *   - Otherwise, returns the plaintext (legacy fail-open behavior used
+ *     by CLI today during dark-ship rollout).
+ *
+ * Empty-string input is universally passthrough — there is no secret
+ * to protect.
+ */
+export function maybeEncryptForWrite(plaintext) {
+    if (typeof plaintext !== 'string' || plaintext.length === 0)
+        return plaintext;
+    if (_state.kind !== 'active') {
+        const stateKind = _state.kind;
+        const reason = _state.kind === 'disabled' ? _state.reason : undefined;
+        if (getCredEnvelopeFailClosed()) {
+            emit('cred_envelope.wrap.refused', false, {
+                stateKind,
+                ...(reason !== undefined ? { reason } : {}),
+            });
+            throw new Error(`cred_envelope: envelope path is ${stateKind}` +
+                (reason ? ` (${reason})` : '') +
+                '; refusing to write credential as plaintext');
+        }
+        return plaintext;
+    }
+    try {
+        const aad = buildCredentialAad(_state.profile);
+        const sealed = credEnvelopeEncrypt(plaintext, _state.dek, aad);
+        const out = credEnvelopeSerialize(sealed);
+        emit('cred_envelope.wrap.success', true, {
+            kekId: _state.kekId,
+            kekKind: _state.kekKind,
+        });
+        return out;
+    }
+    catch (err) {
+        const message = err?.message ?? 'unknown';
+        emit('cred_envelope.wrap.failure', false, {
+            kekId: _state.kekId,
+            kekKind: _state.kekKind,
+            message,
+        });
+        if (getCredEnvelopeFailClosed()) {
+            emit('cred_envelope.wrap.refused', false, {
+                stateKind: 'active',
+                kekId: _state.kekId,
+                kekKind: _state.kekKind,
+                message,
+            });
+            throw err;
+        }
+        return plaintext;
+    }
+}
+/**
+ * Always-fail-open variant of `maybeEncryptForWrite` for callers that
+ * cannot afford to abort their write when the envelope path is inactive
+ * (today: device-identity persistence, which writes the private key as
+ * plaintext JSON before the L12 KEK ships per-platform). The wire form
+ * is identical to `maybeEncryptForWrite` when active (envelope-prefixed)
+ * and identical to the input when not.
+ *
+ * Distinct from `maybeEncryptForWrite` because that helper honors the
+ * daemon's `credEnvelopeFailClosed: true` policy — designed for callers
+ * that MUST refuse a plaintext write rather than silently degrade.
+ */
+export function wrapIfActiveOrPassthrough(plaintext) {
+    if (typeof plaintext !== 'string' || plaintext.length === 0)
+        return plaintext;
+    if (_state.kind !== 'active')
+        return plaintext;
+    try {
+        const aad = buildCredentialAad(_state.profile);
+        const sealed = credEnvelopeEncrypt(plaintext, _state.dek, aad);
+        const out = credEnvelopeSerialize(sealed);
+        emit('cred_envelope.wrap.success', true, {
+            kekId: _state.kekId,
+            kekKind: _state.kekKind,
+        });
+        return out;
+    }
+    catch (err) {
+        emit('cred_envelope.wrap.failure', false, {
+            kekId: _state.kekId,
+            kekKind: _state.kekKind,
+            message: err?.message ?? 'unknown',
+        });
+        return plaintext;
+    }
+}
+export function maybeDecryptOnRead(stored) {
+    if (typeof stored !== 'string' || stored.length === 0) {
+        return { plaintext: stored, needsMigration: false };
+    }
+    if (isCredEnvelopeString(stored)) {
+        if (_state.kind !== 'active') {
+            emit('cred_envelope.read.envelope_but_inactive', false, {
+                stateKind: _state.kind,
+            });
+            return { plaintext: null, needsMigration: false };
+        }
+        const sealed = credEnvelopeDeserialize(stored);
+        if (!sealed) {
+            emit('cred_envelope.read.malformed', false, {
+                kekId: _state.kekId,
+                kekKind: _state.kekKind,
+            });
+            return { plaintext: null, needsMigration: false };
+        }
+        try {
+            const aad = buildCredentialAad(_state.profile);
+            const pt = credEnvelopeDecrypt(sealed, _state.dek, aad).toString('utf-8');
+            return { plaintext: pt, needsMigration: false };
+        }
+        catch (err) {
+            emit('cred_envelope.read.decrypt_failed', false, {
+                kekId: _state.kekId,
+                kekKind: _state.kekKind,
+                message: err?.message ?? 'unknown',
+            });
+            return { plaintext: null, needsMigration: false };
+        }
+    }
+    // Legacy plaintext path.
+    if (_state.kind === 'active') {
+        emit('cred_envelope.unwrap.fallback_to_legacy', true, {
+            kekId: _state.kekId,
+            kekKind: _state.kekKind,
+        });
+        return { plaintext: stored, needsMigration: true };
+    }
+    return { plaintext: stored, needsMigration: false };
+}
+/** @internal Test seam — wrapped-DEK path resolver. */
+export function __wrappedDekFilePathForTest(profile) {
+    return wrappedDekFilePath(profile);
+}