@skrr-ai/auth-core 0.1.2

package/dist/esm/authHelper.js

@@ -0,0 +1,311 @@
+/**
+ * authHelper.ts — invocation contract for `OVERSKY_AUTH_HELPER`.
+ *
+ * The helper is a user-supplied executable that prints a fresh token to
+ * stdout. It exists so operators with rotating credentials (Vault, AWS
+ * Secrets Manager, internal SSO proxy) can plug in without OverSky needing
+ * to know how their secret store works. The contract mirrors Claude Code's
+ * `apiKeyHelper`.
+ *
+ * Wire protocol:
+ *   - `OVERSKY_AUTH_HELPER` env points at an absolute, executable path.
+ *   - We `spawn(path, [], { shell: false })` — never via shell, so no
+ *     argument injection regardless of what's in the env value.
+ *   - The helper writes EITHER a bare JWT to stdout, OR a JSON object
+ *     `{ "token": "...", "expiresAt"?: <ms epoch> }`.
+ *   - Stderr is captured for diagnostic logging only — never returned as
+ *     token material.
+ *   - Stdout cap: 64 KiB (`MAX_OUTPUT_BYTES`). Real JWTs are < 4 KiB.
+ *   - Default timeout: 10 s (`OVERSKY_AUTH_HELPER_TIMEOUT_MS` overrides).
+ *
+ * Safety invariants:
+ *   - Relative paths rejected — explicit absolute path required.
+ *   - Non-executable file rejected (any of u/g/o exec bits must be set).
+ *   - Non-zero exit, timeout, oversized output, malformed JSON → null.
+ *   - On any failure the resolver chain falls through to the next slot;
+ *     we never throw from a helper failure.
+ *   - L6.3 (cold-cache failure sentinel) lives one layer up in
+ *     `credentialResolver.ts` — when the SPAWN ATTEMPT itself fails on a
+ *     cold cache the resolver caches a typed `{kind:'failed'}` sentinel
+ *     to prevent silent fall-through to OAuth.
+ *
+ * Kill switch: `OVERSKY_DISABLE_AUTH_HELPER=1` short-circuits to null.
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { getAuthLogger } from './runtime.js';
+const MAX_OUTPUT_BYTES = 64 * 1024;
+const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_TTL_MS = 5 * 60_000;
+/**
+ * L6.3 — failure outcomes that should TRIGGER the cold-cache sentinel.
+ * Validation failures (`disabled`, `invalid-path`, `not-executable`) are
+ * deliberately excluded: those mean "helper isn't really wired up" and
+ * the resolver chain should fall through to the next slot, not fail
+ * closed.
+ *
+ * Exported as a `const` set so the resolver can do
+ * `SENTINEL_TRIGGERING_FAILURES.has(reason)` without re-encoding the
+ * policy in two places.
+ */
+export const SENTINEL_TRIGGERING_FAILURES = new Set([
+    'spawn-error',
+    'timeout',
+    'non-zero-exit',
+    'oversized',
+    'empty-output',
+    'parse-error',
+]);
+/**
+ * Diagnostic outcome of the LAST `invokeAuthHelper()` call. The resolver
+ * reads this immediately after the call to decide whether to cache a
+ * cold-cache failure sentinel.
+ *
+ * Module-level (not part of the function return) because changing
+ * `invokeAuthHelper`'s return type would ripple through every existing
+ * caller and test. Reading it BEFORE another invocation is racy in
+ * theory but safe in practice — the resolver awaits the same promise it
+ * read this from.
+ */
+let _lastFailureReason = null;
+export function getLastAuthHelperFailureReason() {
+    return _lastFailureReason;
+}
+/** @internal test-only — clear the failure-reason latch between cases. */
+export function __resetAuthHelperFailureReasonForTest() {
+    _lastFailureReason = null;
+}
+/**
+ * Invoke the helper script and return its parsed token, or null on any
+ * failure. Never throws.
+ */
+export async function invokeAuthHelper(scriptPath, options = {}) {
+    const log = getAuthLogger();
+    // Reset on entry so a successful call clears any prior failure latch.
+    _lastFailureReason = null;
+    if (process.env.OVERSKY_DISABLE_AUTH_HELPER === '1') {
+        log.debug?.('[authHelper] OVERSKY_DISABLE_AUTH_HELPER=1 — skipping helper');
+        _lastFailureReason = 'disabled';
+        return null;
+    }
+    if (!scriptPath || !path.isAbsolute(scriptPath)) {
+        log.error(`[authHelper] OVERSKY_AUTH_HELPER must be an absolute path; got "${scriptPath}"`);
+        _lastFailureReason = 'invalid-path';
+        return null;
+    }
+    let stat;
+    try {
+        stat = fs.statSync(scriptPath);
+    }
+    catch (err) {
+        log.error(`[authHelper] OVERSKY_AUTH_HELPER not found at "${scriptPath}": ${formatErr(err)}`);
+        _lastFailureReason = 'invalid-path';
+        return null;
+    }
+    if (!stat.isFile()) {
+        log.error(`[authHelper] OVERSKY_AUTH_HELPER "${scriptPath}" is not a regular file`);
+        _lastFailureReason = 'invalid-path';
+        return null;
+    }
+    if ((stat.mode & 0o111) === 0) {
+        log.error(`[authHelper] OVERSKY_AUTH_HELPER "${scriptPath}" is not executable`);
+        _lastFailureReason = 'not-executable';
+        return null;
+    }
+    const timeoutMs = options.timeoutMs ?? parseTimeoutMs();
+    return new Promise((resolve) => {
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        let truncated = false;
+        let killedForTimeout = false;
+        let resolved = false;
+        const settle = (result) => {
+            if (resolved)
+                return;
+            resolved = true;
+            clearTimeout(timer);
+            resolve(result);
+        };
+        let child;
+        try {
+            child = spawn(scriptPath, [], {
+                shell: false,
+                // detached: true makes the child its own process-group leader so
+                // we can SIGKILL the whole group on timeout. Without this, killing
+                // the script's shell leaves grandchildren (sleep, curl, vault) as
+                // orphans holding stdio open — `close` would never fire and the
+                // daemon would hang past the timeout window.
+                detached: true,
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+        }
+        catch (err) {
+            log.error(`[authHelper] spawn failed: ${formatErr(err)}`);
+            _lastFailureReason = 'spawn-error';
+            settle(null);
+            return;
+        }
+        const timer = setTimeout(() => {
+            killedForTimeout = true;
+            log.warn(`[authHelper] helper timed out after ${timeoutMs}ms — killing`);
+            // Kill the entire process group so subprocess trees (a helper that
+            // shells out to vault/aws/curl) don't outlive the timeout. The
+            // negative pid form targets the process group; falls back to a
+            // single-process kill on platforms or shapes where that fails.
+            try {
+                if (typeof child.pid === 'number') {
+                    process.kill(-child.pid, 'SIGKILL');
+                }
+                else {
+                    child.kill('SIGKILL');
+                }
+            }
+            catch {
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            // Tear down stdio so any lingering pipe holders don't keep us hung.
+            try {
+                child.stdout?.destroy();
+            }
+            catch {
+                /* ignore */
+            }
+            try {
+                child.stderr?.destroy();
+            }
+            catch {
+                /* ignore */
+            }
+            _lastFailureReason = 'timeout';
+            // Settle immediately — do not wait for `close`. Orphan grandchildren
+            // may keep the close event pending indefinitely; the resolver chain
+            // must move on within the configured timeout.
+            settle(null);
+        }, timeoutMs);
+        if (typeof timer.unref === 'function')
+            timer.unref();
+        child.stdout.on('data', (chunk) => {
+            stdoutBytes += chunk.length;
+            if (stdoutBytes > MAX_OUTPUT_BYTES) {
+                truncated = true;
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch {
+                    /* ignore */
+                }
+                return;
+            }
+            stdoutChunks.push(chunk);
+        });
+        child.stderr.on('data', (chunk) => {
+            // Defensive cap on stderr too (a chatty helper shouldn't OOM the daemon).
+            if (stderrBytes < MAX_OUTPUT_BYTES) {
+                stderrChunks.push(chunk);
+                stderrBytes += chunk.length;
+            }
+        });
+        child.on('error', (err) => {
+            log.error(`[authHelper] runtime error: ${formatErr(err)}`);
+            _lastFailureReason = 'spawn-error';
+            settle(null);
+        });
+        child.on('close', (code) => {
+            if (truncated) {
+                log.error(`[authHelper] stdout exceeded ${MAX_OUTPUT_BYTES} bytes — refusing to parse`);
+                _lastFailureReason = 'oversized';
+                settle(null);
+                return;
+            }
+            if (killedForTimeout) {
+                // _lastFailureReason already set to 'timeout' in the timer.
+                settle(null);
+                return;
+            }
+            const stderr = Buffer.concat(stderrChunks).toString('utf-8').trim();
+            if (stderr)
+                log.debug?.(`[authHelper] stderr: ${stderr}`);
+            if (code !== 0) {
+                log.error(`[authHelper] helper exited with code ${code}`);
+                _lastFailureReason = 'non-zero-exit';
+                settle(null);
+                return;
+            }
+            const stdout = Buffer.concat(stdoutChunks).toString('utf-8').trim();
+            if (!stdout) {
+                log.error('[authHelper] helper produced empty stdout');
+                _lastFailureReason = 'empty-output';
+                settle(null);
+                return;
+            }
+            const parsed = parseHelperOutput(stdout, log);
+            if (parsed === null) {
+                _lastFailureReason = 'parse-error';
+            }
+            settle(parsed);
+        });
+    });
+}
+function parseHelperOutput(stdout, log) {
+    // JSON path first; fall back to bare-string token.
+    const trimmed = stdout.trim();
+    const looksLikeJson = trimmed.startsWith('{') || trimmed.startsWith('"');
+    if (looksLikeJson) {
+        try {
+            const obj = JSON.parse(trimmed);
+            if (typeof obj === 'string') {
+                return obj.length > 0 ? { token: obj } : null;
+            }
+            if (obj && typeof obj === 'object') {
+                const rec = obj;
+                const token = typeof rec.token === 'string' ? rec.token : null;
+                if (!token || token.length === 0) {
+                    log.error('[authHelper] JSON output missing "token" field');
+                    return null;
+                }
+                const expiresAt = typeof rec.expiresAt === 'number' && Number.isFinite(rec.expiresAt)
+                    ? rec.expiresAt
+                    : undefined;
+                return expiresAt !== undefined ? { token, expiresAt } : { token };
+            }
+            log.error('[authHelper] JSON output was not an object or string');
+            return null;
+        }
+        catch (err) {
+            log.error(`[authHelper] JSON parse failed: ${formatErr(err)}`);
+            return null;
+        }
+    }
+    // Bare token — single line, no JSON. Reject if it contains whitespace
+    // beyond surrounding trim (defensive — helper might have leaked logs).
+    if (/\s/.test(trimmed)) {
+        log.error('[authHelper] bare-token output contains whitespace — refusing (use JSON if helper logs to stdout)');
+        return null;
+    }
+    return { token: trimmed };
+}
+function parseTimeoutMs() {
+    const raw = process.env.OVERSKY_AUTH_HELPER_TIMEOUT_MS;
+    if (!raw)
+        return DEFAULT_TIMEOUT_MS;
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_TIMEOUT_MS;
+}
+export function getDefaultHelperTtlMs() {
+    const raw = process.env.OVERSKY_AUTH_HELPER_TTL_MS;
+    if (!raw)
+        return DEFAULT_TTL_MS;
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_TTL_MS;
+}
+function formatErr(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/esm/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/esm/credentialEnvelope.js

@@ -0,0 +1,213 @@
+/**
+ * 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.
+ */
+import crypto from 'node:crypto';
+import { aeadSeal, aeadOpen, AEAD_KEY_LEN, AEAD_NONCE_LEN, AEAD_TAG_LEN } from './aead.js';
+/** Serialized magic prefix. Bumped only on a breaking format change. */
+export const ENVELOPE_MAGIC = 'osk-env1';
+/** Key length in bytes (256 bits). */
+export const KEY_LEN = AEAD_KEY_LEN;
+/** Nonce length in bytes (96 bits — GCM standard). */
+const NONCE_LEN = AEAD_NONCE_LEN;
+/** GCM authentication tag length in bytes (128 bits). */
+const TAG_LEN = 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).
+ */
+export function generateDek() {
+    return crypto.randomBytes(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.
+ */
+export 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.
+ */
+export function sealBuffer(plaintext, key, aad) {
+    if (!Buffer.isBuffer(plaintext)) {
+        throw new TypeError('sealBuffer: plaintext must be a Buffer');
+    }
+    if (!Buffer.isBuffer(key) || key.length !== KEY_LEN) {
+        throw new TypeError(`sealBuffer: key must be a ${KEY_LEN}-byte Buffer`);
+    }
+    const { nonce, ct, tag } = 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.
+ */
+export function openBuffer(sealed, key, aad) {
+    if (!sealed || sealed.v !== 1) {
+        throw new Error('openBuffer: unsupported envelope version');
+    }
+    if (!Buffer.isBuffer(key) || key.length !== KEY_LEN) {
+        throw new TypeError(`openBuffer: key must be a ${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 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.
+ */
+export function wrap(dek, kek, aad) {
+    if (!Buffer.isBuffer(dek) || dek.length !== KEY_LEN) {
+        throw new TypeError(`wrap: dek must be a ${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.
+ */
+export function unwrap(wrapped, kek, aad) {
+    const out = openBuffer(wrapped, kek, aad);
+    if (out.length !== 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export function serialize(sealed) {
+    if (!sealed || sealed.v !== 1) {
+        throw new Error('serialize: unsupported envelope version');
+    }
+    return `${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.
+ */
+export 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] !== 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.
+ */
+export function isEnvelopeString(s) {
+    return typeof s === 'string' && s.startsWith(`${ENVELOPE_MAGIC}:`);
+}