@skrr-ai/auth-core 0.1.2

package/dist/cjs/credentialEnvelope.d.ts

@@ -0,0 +1,85 @@
+/** Serialized magic prefix. Bumped only on a breaking format change. */
+export declare const ENVELOPE_MAGIC = "osk-env1";
+/** Key length in bytes (256 bits). */
+export declare const KEY_LEN = 32;
+/**
+ * In-memory representation of a sealed value. Carries a version byte so a
+ * future `osk-env2` migration can dual-read both formats from disk.
+ */
+export interface SealedBlob {
+    readonly v: 1;
+    readonly nonce: Buffer;
+    readonly ct: Buffer;
+    readonly tag: Buffer;
+}
+/**
+ * Generate a fresh 256-bit Data Encryption Key. Uses Node's crypto-random
+ * source (libsodium-grade on macOS/Linux, BCryptGenRandom on Windows).
+ */
+export declare function generateDek(): Buffer;
+/**
+ * Build the canonical AAD for binding a sealed credential to a specific
+ * profile + envelope version. Including profile in the AAD prevents an
+ * attacker who copies a sealed blob from profile `dev` into profile
+ * `prod`'s slot from getting a successful decrypt — the AAD won't match.
+ *
+ * Stable string format so a re-derivation in a future process produces
+ * the exact same AAD bytes for the same profile.
+ */
+export declare function buildCredentialAad(profile: string, version?: number): Buffer;
+/**
+ * Low-level AEAD seal. The shared primitive used by both DEK-wrapping and
+ * credential-encryption — the only difference between those operations is
+ * the semantic role of the key, not the cipher. Caller chooses the AAD.
+ */
+export declare function sealBuffer(plaintext: Buffer, key: Buffer, aad?: Buffer): SealedBlob;
+/**
+ * Low-level AEAD open. Throws on tag mismatch (wrong key, AAD mismatch,
+ * truncated/corrupted ciphertext) — never silently returns garbage.
+ */
+export declare function openBuffer(sealed: SealedBlob, key: Buffer, aad?: Buffer): Buffer;
+/**
+ * Wrap a 32-byte DEK under a KEK. The wrapped DEK is what gets persisted
+ * to disk — the KEK itself never leaves its platform store.
+ */
+export declare function wrap(dek: Buffer, kek: Buffer, aad?: Buffer): SealedBlob;
+/**
+ * Unwrap a previously-wrapped DEK using the same KEK. AAD must match the
+ * value used at wrap time or the GCM tag check fails.
+ */
+export declare function unwrap(wrapped: SealedBlob, kek: Buffer, aad?: Buffer): Buffer;
+/**
+ * Encrypt a credential (string or Buffer) under a DEK. Strings are
+ * encoded as UTF-8 before sealing; the open path returns a Buffer so the
+ * caller decides how to interpret it.
+ */
+export declare function encrypt(plaintext: Buffer | string, dek: Buffer, aad?: Buffer): SealedBlob;
+/**
+ * Decrypt a credential previously sealed with `encrypt`. Returns the raw
+ * plaintext bytes; UTF-8-decode at the call site if the original was a
+ * string.
+ */
+export declare function decrypt(sealed: SealedBlob, dek: Buffer, aad?: Buffer): Buffer;
+/**
+ * Serialize a SealedBlob to a single text token. Stable across processes
+ * and platforms — same blob serializes to the same string everywhere.
+ */
+export declare function serialize(sealed: SealedBlob): string;
+/**
+ * Parse a serialized envelope string. Returns null on any malformed
+ * input — callers should treat null as "this is not an envelope" and
+ * fall through to the legacy plaintext path.
+ *
+ * Deliberately tolerant: garbage in returns null, never throws. Throws
+ * are reserved for the cipher path so a wrong key surfaces as a real
+ * authentication failure instead of being silently swallowed.
+ */
+export declare function deserialize(s: string): SealedBlob | null;
+/**
+ * Cheap structural check — does this string LOOK like a serialized
+ * envelope? Used by dual-read paths to decide whether to attempt a
+ * decrypt or to treat the value as legacy plaintext. A true return does
+ * NOT guarantee the contents are valid; the actual decrypt is what
+ * authenticates the value.
+ */
+export declare function isEnvelopeString(s: unknown): s is string;

package/dist/cjs/credentialEnvelope.js

@@ -0,0 +1,230 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KEY_LEN = exports.ENVELOPE_MAGIC = void 0;
+exports.generateDek = generateDek;
+exports.buildCredentialAad = buildCredentialAad;
+exports.sealBuffer = sealBuffer;
+exports.openBuffer = openBuffer;
+exports.wrap = wrap;
+exports.unwrap = unwrap;
+exports.encrypt = encrypt;
+exports.decrypt = decrypt;
+exports.serialize = serialize;
+exports.deserialize = deserialize;
+exports.isEnvelopeString = isEnvelopeString;
+/**
+ * credentialEnvelope.ts — at-rest envelope encryption primitives (L12 Layer 0).
+ *
+ * NAMING NOTE — this module is the "credential at-rest envelope." It is
+ * structurally distinct from `daemon/src/envelope-encryption.ts`, which
+ * encrypts wire-protocol session envelopes with a server-known DEK. The
+ * two should never share a key, a serialized format, or a rotation
+ * policy. We deliberately do NOT use the bare word "envelope" in this
+ * module's filename to avoid that confusion; future readers grepping for
+ * "envelope" must hit a name that immediately disambiguates which layer
+ * they are looking at.
+ *
+ * Threat model — what this module protects:
+ *   - Cold copy of `~/Library/Keychains/login.keychain-db` taken from a
+ *     sleeping laptop and brute-forced offline.
+ *   - Backup snapshot of `~/.skrr/...` in Time Machine / Backblaze /
+ *     Restic that ends up on a less-trusted disk.
+ *   - Same-UID malware that reads the on-disk JSON file backend without
+ *     standing up an OS prompt.
+ *
+ * What it does NOT protect:
+ *   - Privileged on-host malware (root) reading the daemon's process memory.
+ *   - Server-side compromise of refresh tokens that the server already
+ *     holds by design.
+ *
+ * Hierarchy:
+ *   plaintext credential
+ *     ─ AES-256-GCM(DEK, nonce, AAD) ─▶ sealed credential blob
+ *   plaintext DEK (32 bytes, generated locally)
+ *     ─ AES-256-GCM(KEK, nonce, AAD) ─▶ wrapped DEK blob
+ *   KEK (platform-native; Secure Enclave / DPAPI / libsecret-derived)
+ *     never appears in JS memory in unwrappable form.
+ *
+ * This module owns ONLY the AES-256-GCM primitive plus the serialized
+ * format. Platform KEK acquisition lives in `./kek/`. DEK lifecycle
+ * (generation, rotation, persistence) lives in the daemon-side bridge.
+ */
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const aead_js_1 = require("./aead.js");
+/** Serialized magic prefix. Bumped only on a breaking format change. */
+exports.ENVELOPE_MAGIC = 'osk-env1';
+/** Key length in bytes (256 bits). */
+exports.KEY_LEN = aead_js_1.AEAD_KEY_LEN;
+/** Nonce length in bytes (96 bits — GCM standard). */
+const NONCE_LEN = aead_js_1.AEAD_NONCE_LEN;
+/** GCM authentication tag length in bytes (128 bits). */
+const TAG_LEN = aead_js_1.AEAD_TAG_LEN;
+/**
+ * Generate a fresh 256-bit Data Encryption Key. Uses Node's crypto-random
+ * source (libsodium-grade on macOS/Linux, BCryptGenRandom on Windows).
+ */
+function generateDek() {
+    return node_crypto_1.default.randomBytes(exports.KEY_LEN);
+}
+/**
+ * Build the canonical AAD for binding a sealed credential to a specific
+ * profile + envelope version. Including profile in the AAD prevents an
+ * attacker who copies a sealed blob from profile `dev` into profile
+ * `prod`'s slot from getting a successful decrypt — the AAD won't match.
+ *
+ * Stable string format so a re-derivation in a future process produces
+ * the exact same AAD bytes for the same profile.
+ */
+function buildCredentialAad(profile, version = 1) {
+    if (typeof profile !== 'string' || profile.length === 0) {
+        throw new Error('buildCredentialAad: profile must be a non-empty string');
+    }
+    if (!Number.isInteger(version) || version < 1) {
+        throw new Error('buildCredentialAad: version must be a positive integer');
+    }
+    return Buffer.from(`oversky:cred:v${version}:profile=${profile}`, 'utf-8');
+}
+/**
+ * Low-level AEAD seal. The shared primitive used by both DEK-wrapping and
+ * credential-encryption — the only difference between those operations is
+ * the semantic role of the key, not the cipher. Caller chooses the AAD.
+ */
+function sealBuffer(plaintext, key, aad) {
+    if (!Buffer.isBuffer(plaintext)) {
+        throw new TypeError('sealBuffer: plaintext must be a Buffer');
+    }
+    if (!Buffer.isBuffer(key) || key.length !== exports.KEY_LEN) {
+        throw new TypeError(`sealBuffer: key must be a ${exports.KEY_LEN}-byte Buffer`);
+    }
+    const { nonce, ct, tag } = (0, aead_js_1.aeadSeal)(plaintext, key, aad);
+    return { v: 1, nonce, ct, tag };
+}
+/**
+ * Low-level AEAD open. Throws on tag mismatch (wrong key, AAD mismatch,
+ * truncated/corrupted ciphertext) — never silently returns garbage.
+ */
+function openBuffer(sealed, key, aad) {
+    if (!sealed || sealed.v !== 1) {
+        throw new Error('openBuffer: unsupported envelope version');
+    }
+    if (!Buffer.isBuffer(key) || key.length !== exports.KEY_LEN) {
+        throw new TypeError(`openBuffer: key must be a ${exports.KEY_LEN}-byte Buffer`);
+    }
+    if (!Buffer.isBuffer(sealed.nonce) || sealed.nonce.length !== NONCE_LEN) {
+        throw new Error('openBuffer: invalid nonce length');
+    }
+    if (!Buffer.isBuffer(sealed.tag) || sealed.tag.length !== TAG_LEN) {
+        throw new Error('openBuffer: invalid auth tag length');
+    }
+    if (!Buffer.isBuffer(sealed.ct)) {
+        throw new Error('openBuffer: invalid ciphertext');
+    }
+    return (0, aead_js_1.aeadOpen)(sealed, key, aad);
+}
+/**
+ * Wrap a 32-byte DEK under a KEK. The wrapped DEK is what gets persisted
+ * to disk — the KEK itself never leaves its platform store.
+ */
+function wrap(dek, kek, aad) {
+    if (!Buffer.isBuffer(dek) || dek.length !== exports.KEY_LEN) {
+        throw new TypeError(`wrap: dek must be a ${exports.KEY_LEN}-byte Buffer`);
+    }
+    return sealBuffer(dek, kek, aad);
+}
+/**
+ * Unwrap a previously-wrapped DEK using the same KEK. AAD must match the
+ * value used at wrap time or the GCM tag check fails.
+ */
+function unwrap(wrapped, kek, aad) {
+    const out = openBuffer(wrapped, kek, aad);
+    if (out.length !== exports.KEY_LEN) {
+        throw new Error(`unwrap: unwrapped DEK has wrong length (got ${out.length})`);
+    }
+    return out;
+}
+/**
+ * Encrypt a credential (string or Buffer) under a DEK. Strings are
+ * encoded as UTF-8 before sealing; the open path returns a Buffer so the
+ * caller decides how to interpret it.
+ */
+function encrypt(plaintext, dek, aad) {
+    const buf = typeof plaintext === 'string' ? Buffer.from(plaintext, 'utf-8') : plaintext;
+    return sealBuffer(buf, dek, aad);
+}
+/**
+ * Decrypt a credential previously sealed with `encrypt`. Returns the raw
+ * plaintext bytes; UTF-8-decode at the call site if the original was a
+ * string.
+ */
+function decrypt(sealed, dek, aad) {
+    return openBuffer(sealed, dek, aad);
+}
+// ---------------------------------------------------------------------------
+// String serialization — keychain slots and JSON files store strings, so a
+// SealedBlob has to round-trip through a single text token.
+//
+// Format:  osk-env1:<b64u(nonce)>:<b64u(ct)>:<b64u(tag)>
+// Length:  ~88 chars for a typical 100-byte plaintext (well under the
+//          keychain's per-slot limit).
+// ---------------------------------------------------------------------------
+/** URL-safe base64 (no padding) — keychain-friendly, no `=` to confuse parsers. */
+function b64u(buf) {
+    return buf.toString('base64').replace(/=+$/, '').replace(/\+/g, '-').replace(/\//g, '_');
+}
+function b64uDecode(s) {
+    const padded = s.replace(/-/g, '+').replace(/_/g, '/');
+    const pad = padded.length % 4;
+    return Buffer.from(pad === 0 ? padded : padded + '='.repeat(4 - pad), 'base64');
+}
+/**
+ * Serialize a SealedBlob to a single text token. Stable across processes
+ * and platforms — same blob serializes to the same string everywhere.
+ */
+function serialize(sealed) {
+    if (!sealed || sealed.v !== 1) {
+        throw new Error('serialize: unsupported envelope version');
+    }
+    return `${exports.ENVELOPE_MAGIC}:${b64u(sealed.nonce)}:${b64u(sealed.ct)}:${b64u(sealed.tag)}`;
+}
+/**
+ * Parse a serialized envelope string. Returns null on any malformed
+ * input — callers should treat null as "this is not an envelope" and
+ * fall through to the legacy plaintext path.
+ *
+ * Deliberately tolerant: garbage in returns null, never throws. Throws
+ * are reserved for the cipher path so a wrong key surfaces as a real
+ * authentication failure instead of being silently swallowed.
+ */
+function deserialize(s) {
+    if (typeof s !== 'string' || s.length === 0)
+        return null;
+    const parts = s.split(':');
+    if (parts.length !== 4)
+        return null;
+    if (parts[0] !== exports.ENVELOPE_MAGIC)
+        return null;
+    try {
+        const nonce = b64uDecode(parts[1]);
+        const ct = b64uDecode(parts[2]);
+        const tag = b64uDecode(parts[3]);
+        if (nonce.length !== NONCE_LEN || tag.length !== TAG_LEN)
+            return null;
+        return { v: 1, nonce, ct, tag };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Cheap structural check — does this string LOOK like a serialized
+ * envelope? Used by dual-read paths to decide whether to attempt a
+ * decrypt or to treat the value as legacy plaintext. A true return does
+ * NOT guarantee the contents are valid; the actual decrypt is what
+ * authenticates the value.
+ */
+function isEnvelopeString(s) {
+    return typeof s === 'string' && s.startsWith(`${exports.ENVELOPE_MAGIC}:`);
+}

package/dist/cjs/credentialEnvelopeBridge.d.ts

@@ -0,0 +1,116 @@
+type CredEnvelopeState = {
+    kind: 'uninit';
+} | {
+    kind: 'disabled';
+    reason: DisabledReason;
+} | {
+    kind: 'active';
+    dek: Buffer;
+    kekId: string;
+    /**
+     * Backend-tier identifier captured at init time
+     * (e.g. `macos-keychain-shellout`, `in-memory-test`). Snapshotted
+     * here so transform-side events can surface the kind without
+     * holding a live `kek` reference.
+     */
+    kekKind: string | null;
+    profile: string;
+};
+type DisabledReason = 'kek_unavailable' | 'init_failed' | 'platform_unsupported' | 'kek_rotated';
+/** @internal Test seam — force-set state, returns previous. */
+export declare function __setStateForTest(next: CredEnvelopeState): CredEnvelopeState;
+/** @internal Test seam — read state for assertions. */
+export declare function __getStateForTest(): CredEnvelopeState;
+/**
+ * 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 declare function initCredEnvelope(profile: string): Promise<void>;
+/**
+ * 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 declare function resetCredEnvelope(opts?: {
+    profile?: string;
+    clearOnDisk?: boolean;
+}): Promise<void>;
+export declare function shutdownCredEnvelope(): void;
+/** @internal Test seam — re-arm `shutdownCredEnvelope` so it can run again. */
+export declare function __resetShutdownGuardForTest(): void;
+/**
+ * True iff the envelope path is initialized AND active. Hot-path
+ * predicate used by sync transforms; never throws.
+ */
+export declare function isCredEnvelopeActive(): boolean;
+/**
+ * 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 declare function describeCredEnvelopeState(): {
+    kind: CredEnvelopeState['kind'];
+    reason?: DisabledReason;
+    kekId?: string;
+    kekKind?: string | null;
+    profile?: string;
+    kekRotated?: boolean;
+};
+/**
+ * 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 declare function maybeEncryptForWrite(plaintext: string): string;
+/**
+ * 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 declare function wrapIfActiveOrPassthrough(plaintext: string): string;
+/**
+ * Sync read transform. Three cases:
+ *   1. Envelope on disk + path active → decrypt; null on tag mismatch
+ *      (caller treats null as a forced re-login signal).
+ *   2. Envelope on disk + path NOT active → null (rolled-back binary
+ *      while envelopes are persisted).
+ *   3. Legacy plaintext → return as-is; if path is active, set
+ *      `needsMigration=true` so caller can upgrade in place.
+ */
+export interface ReadTransformResult {
+    /** Decoded plaintext, or null on hard failure. */
+    plaintext: string | null;
+    /** True when the on-disk form was legacy plaintext AND the envelope
+     *  path is active — caller should re-write to upgrade. */
+    needsMigration: boolean;
+}
+export declare function maybeDecryptOnRead(stored: string): ReadTransformResult;
+/** @internal Test seam — wrapped-DEK path resolver. */
+export declare function __wrappedDekFilePathForTest(profile: string): string;
+export {};