@skrr-ai/auth-core 0.1.2

package/dist/cjs/daemonPair.js

@@ -0,0 +1,495 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PairBundleError = exports.PAIR_AAD_PREFIX = exports.PAIR_AAD_MAX_LEN = exports.PAIR_BUNDLE_MAX_BASE64_LEN = exports.PAIR_AAD_LEN_PREFIX = exports.PAIR_SECRET_LEN = exports.PAIR_PUBKEY_LEN = exports.PAIR_NONCE_LEN = void 0;
+exports.buildPairAad = buildPairAad;
+exports.parsePairPlaintext = parsePairPlaintext;
+exports.assemblePairBundleBase64 = assemblePairBundleBase64;
+exports.parsePairBundle = parsePairBundle;
+exports.openPairBundleBase64 = openPairBundleBase64;
+exports.buildPairUrl = buildPairUrl;
+exports.parsePairUrl = parsePairUrl;
+exports.uint8ArrayToBase64 = uint8ArrayToBase64;
+exports.base64ToUint8Array = base64ToUint8Array;
+exports.uint8ArrayToBase64Url = uint8ArrayToBase64Url;
+exports.base64UrlToUint8Array = base64UrlToUint8Array;
+exports.generatePairKeyPair = generatePairKeyPair;
+/**
+ * daemonPair.ts — pure-crypto primitives for the mobile-as-keyholder QR
+ * pairing handshake (Tier 1 #2 from Happy lessons).
+ *
+ * Wire format (matches `api/server/routes/daemonPair.js` header):
+ *
+ *   bundle =
+ *     nonce        (24 bytes)        // tweetnacl box nonce
+ *     ephemeralPk  (32 bytes)        // mobile-side X25519 public key
+ *     ciphertext   (variable)        // tweetnacl box(plaintext, daemonPk, ephSk, nonce)
+ *     lenAad       (2 bytes, big-endian)
+ *     aad          (lenAad bytes, ASCII)
+ *
+ *   encryptedPayload = base64(bundle)
+ *
+ * Canonical AAD (C4 — bound by the server at /respond, rebuilt by the
+ * daemon at /poll for verify):
+ *
+ *   oversky:pair:v1:daemonId=<daemonId>:responseUserId=<userId>
+ *
+ * Note: this module is platform-agnostic. It does no disk IO, no network
+ * IO, and no console IO. The daemon CLI orchestrator (`daemon/src/pair.ts`)
+ * imports these primitives; the mobile RN client mirrors the same shapes
+ * in TypeScript with its own tweetnacl.
+ *
+ * Lifetime invariant: the ephemeral X25519 secret key NEVER persists. The
+ * mobile generates one per pairing, uses it once, and discards. The daemon
+ * generates one per `oversky pair` invocation, uses it for the duration
+ * of the polling window, and discards on success/failure/abort.
+ */
+const tweetnacl_1 = __importDefault(require("tweetnacl"));
+// ---------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------
+/** Box nonce length per RFC 8439 / NaCl. */
+exports.PAIR_NONCE_LEN = 24;
+/** Curve25519 public key length. */
+exports.PAIR_PUBKEY_LEN = 32;
+/** Curve25519 secret key length. */
+exports.PAIR_SECRET_LEN = 32;
+/** Big-endian uint16 length prefix for the AAD trailer. */
+exports.PAIR_AAD_LEN_PREFIX = 2;
+/** Server validator caps `encryptedPayload` at 8192 chars (base64). */
+exports.PAIR_BUNDLE_MAX_BASE64_LEN = 8192;
+/** Conservative ceiling on the trailer to keep the bundle well under cap. */
+exports.PAIR_AAD_MAX_LEN = 1024;
+/** AAD prefix — version-bumped on any breaking format change. */
+exports.PAIR_AAD_PREFIX = 'oversky:pair:v1';
+class PairBundleError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'PairBundleError';
+        this.code = code;
+    }
+}
+exports.PairBundleError = PairBundleError;
+// ---------------------------------------------------------------------
+// AAD
+// ---------------------------------------------------------------------
+/**
+ * Build the canonical AAD bytes for a pairing response. Both sides
+ * (mobile-builder and daemon-verifier) call this with identical inputs:
+ *   - mobile gets `responseUserId` from its own JWT (`req.user.id`)
+ *   - daemon gets `responseUserId` from the `/poll` response
+ *
+ * The encoding is ASCII; non-ASCII inputs are rejected so a hostile
+ * daemonId/userId can't smuggle bytes that would shift the boundary.
+ */
+function buildPairAad(daemonId, responseUserId) {
+    if (typeof daemonId !== 'string' || daemonId.length === 0) {
+        throw new PairBundleError('AAD_MISMATCH', 'daemonId must be a non-empty string');
+    }
+    if (typeof responseUserId !== 'string' || responseUserId.length === 0) {
+        throw new PairBundleError('AAD_MISMATCH', 'responseUserId must be a non-empty string');
+    }
+    // Reject any non-ASCII printable byte. This forces the canonical
+    // encoding to be representable as 1-byte-per-char so length prefixes
+    // are unambiguous and a unicode-rebalancing attack on the trailer
+    // can't shift the AAD/ciphertext boundary.
+    if (!/^[\x21-\x7E]+$/.test(daemonId) || !/^[\x21-\x7E]+$/.test(responseUserId)) {
+        throw new PairBundleError('AAD_MISMATCH', 'daemonId and responseUserId must be ASCII printable (no spaces, no controls)');
+    }
+    const text = `${exports.PAIR_AAD_PREFIX}:daemonId=${daemonId}:responseUserId=${responseUserId}`;
+    if (text.length > exports.PAIR_AAD_MAX_LEN) {
+        throw new PairBundleError('AAD_LEN_OVERFLOW', 'AAD exceeds maximum length');
+    }
+    // Pure ASCII → safe to use TextEncoder (1 byte per char in this range).
+    return new TextEncoder().encode(text);
+}
+// ---------------------------------------------------------------------
+// Plaintext shape validation
+// ---------------------------------------------------------------------
+/**
+ * Parse and validate the JSON plaintext that came out of the box. We
+ * keep this tolerant on output (older daemons may write extra fields)
+ * but strict on the invariant fields the daemon needs to persist.
+ */
+function parsePairPlaintext(raw) {
+    if (!raw || typeof raw !== 'object') {
+        throw new PairBundleError('PLAINTEXT_BAD_SHAPE', 'plaintext is not an object');
+    }
+    const obj = raw;
+    if (obj.v !== 1) {
+        throw new PairBundleError('PLAINTEXT_BAD_SHAPE', `unsupported pair plaintext version: ${String(obj.v)}`);
+    }
+    const token = optString(obj.token);
+    const opaqueAccessToken = optString(obj.opaqueAccessToken);
+    if (!token && !opaqueAccessToken) {
+        throw new PairBundleError('PLAINTEXT_BAD_SHAPE', 'plaintext must include at least one of token or opaqueAccessToken');
+    }
+    const daemonId = optString(obj.daemonId);
+    if (!daemonId) {
+        throw new PairBundleError('PLAINTEXT_BAD_SHAPE', 'plaintext.daemonId is required');
+    }
+    const issuedAt = optNumber(obj.issuedAt);
+    if (issuedAt === undefined) {
+        throw new PairBundleError('PLAINTEXT_BAD_SHAPE', 'plaintext.issuedAt is required');
+    }
+    return {
+        v: 1,
+        ...(token ? { token } : {}),
+        ...(opaqueAccessToken ? { opaqueAccessToken } : {}),
+        expiresAt: optNumber(obj.expiresAt),
+        refreshToken: optString(obj.refreshToken),
+        refreshExpiresAt: optNumber(obj.refreshExpiresAt),
+        daemonId,
+        issuedAt,
+    };
+}
+function optString(v) {
+    return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+function optNumber(v) {
+    return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+}
+/**
+ * Mobile-side: encrypt the plaintext to the daemon's pubkey and frame
+ * the result for transport. Returns base64-encoded bundle suitable for
+ * the `encryptedPayload` field of `POST /api/auth/pair/respond`.
+ */
+function assemblePairBundleBase64(opts) {
+    if (opts.daemonPublicKey.length !== exports.PAIR_PUBKEY_LEN) {
+        throw new PairBundleError('INVALID_KEY', 'daemonPublicKey must be 32 bytes');
+    }
+    if (opts.ephemeralSecretKey.length !== exports.PAIR_SECRET_LEN) {
+        throw new PairBundleError('INVALID_KEY', 'ephemeralSecretKey must be 32 bytes');
+    }
+    if (opts.ephemeralPublicKey.length !== exports.PAIR_PUBKEY_LEN) {
+        throw new PairBundleError('INVALID_KEY', 'ephemeralPublicKey must be 32 bytes');
+    }
+    if (opts.aad.length === 0 || opts.aad.length > exports.PAIR_AAD_MAX_LEN) {
+        throw new PairBundleError('AAD_LEN_OVERFLOW', 'aad must be 1..1024 bytes');
+    }
+    const nonce = opts.__nonceForTest ?? tweetnacl_1.default.randomBytes(exports.PAIR_NONCE_LEN);
+    if (nonce.length !== exports.PAIR_NONCE_LEN) {
+        throw new PairBundleError('INVALID_KEY', 'nonce must be 24 bytes');
+    }
+    const plaintextJson = JSON.stringify(opts.plaintext);
+    const plaintextBytes = new TextEncoder().encode(plaintextJson);
+    const ciphertext = tweetnacl_1.default.box(plaintextBytes, nonce, opts.daemonPublicKey, opts.ephemeralSecretKey);
+    const totalLen = exports.PAIR_NONCE_LEN + exports.PAIR_PUBKEY_LEN + ciphertext.length + exports.PAIR_AAD_LEN_PREFIX + opts.aad.length;
+    const bundle = new Uint8Array(totalLen);
+    let offset = 0;
+    bundle.set(nonce, offset);
+    offset += exports.PAIR_NONCE_LEN;
+    bundle.set(opts.ephemeralPublicKey, offset);
+    offset += exports.PAIR_PUBKEY_LEN;
+    bundle.set(ciphertext, offset);
+    offset += ciphertext.length;
+    // Big-endian uint16 length prefix for AAD.
+    bundle[offset] = (opts.aad.length >>> 8) & 0xff;
+    bundle[offset + 1] = opts.aad.length & 0xff;
+    offset += exports.PAIR_AAD_LEN_PREFIX;
+    bundle.set(opts.aad, offset);
+    const base64 = uint8ArrayToBase64(bundle);
+    if (base64.length > exports.PAIR_BUNDLE_MAX_BASE64_LEN) {
+        throw new PairBundleError('BUNDLE_TOO_LONG', `encryptedPayload exceeds ${exports.PAIR_BUNDLE_MAX_BASE64_LEN} chars`);
+    }
+    return base64;
+}
+// ---------------------------------------------------------------------
+// Bundle parse + decrypt + AAD verify (daemon side)
+// ---------------------------------------------------------------------
+/**
+ * Parse the wire bytes into a `PairBundle` without decrypting. Used as
+ * a preflight by `openPairBundleBase64` and exposed for tests.
+ */
+function parsePairBundle(bytes) {
+    const minLen = exports.PAIR_NONCE_LEN + exports.PAIR_PUBKEY_LEN + exports.PAIR_AAD_LEN_PREFIX + 16;
+    if (bytes.length < minLen) {
+        throw new PairBundleError('BUNDLE_TOO_SHORT', `bundle is ${bytes.length} bytes, need at least ${minLen}`);
+    }
+    let offset = 0;
+    const nonce = bytes.slice(offset, offset + exports.PAIR_NONCE_LEN);
+    offset += exports.PAIR_NONCE_LEN;
+    const ephemeralPublicKey = bytes.slice(offset, offset + exports.PAIR_PUBKEY_LEN);
+    offset += exports.PAIR_PUBKEY_LEN;
+    // The AAD is at the END of the bundle (length-prefixed). Walk backwards
+    // from the tail so the remainder is unambiguously the ciphertext.
+    if (bytes.length - offset < exports.PAIR_AAD_LEN_PREFIX + 1) {
+        throw new PairBundleError('BUNDLE_TOO_SHORT', 'no room for AAD trailer');
+    }
+    // Find the AAD-length prefix by walking forward through ciphertext +
+    // trailer. The ciphertext length is unknown until we know the AAD
+    // length. Simplest deterministic decode: assume the trailer is at the
+    // end and that lenAad fits the remaining bytes exactly.
+    //
+    // Specifically: the last (lenAad) bytes are AAD; the 2 bytes before
+    // that are the big-endian length; everything between offset and
+    // (bytes.length - lenAad - 2) is ciphertext.
+    if (bytes.length < offset + exports.PAIR_AAD_LEN_PREFIX) {
+        throw new PairBundleError('BUNDLE_TOO_SHORT', 'no room for AAD length prefix');
+    }
+    // We need to walk: pick the lenAad as the last 2 bytes WITH the
+    // tail bytes after them — that means the prefix is at
+    // bytes.length - 2 - lenAad. But we don't know lenAad yet.
+    //
+    // The bundle layout puts the prefix BEFORE the AAD bytes, so the
+    // prefix is at `bytes.length - lenAad - 2`. The ONLY consistent
+    // decode is: lenAad = u16BE(bytes[bytes.length - 2 - L : ...]) where
+    // we walk L from 0 upward. The simpler and equally-correct approach:
+    // require the writer to ALSO put a trailer-length at the tail. But
+    // we don't — so we adopt the convention that lenAad lives
+    // immediately AFTER the ciphertext, which means we need the writer
+    // and reader to agree on where the ciphertext ends.
+    //
+    // The agreement: lenAad is encoded at offset
+    //   bytes.length - lenAad - 2
+    // and the AAD itself is the last `lenAad` bytes. To find lenAad we
+    // first read the last 2 bytes? No — those are the tail of the AAD.
+    //
+    // Concrete decoder: walk lenAad candidates from the end. The prefix
+    // bytes appear at position `len - 2 - candidateLen`. Read those 2
+    // bytes BE; if they equal candidateLen and candidateLen ≤ AAD_MAX,
+    // accept.
+    let aadLen = -1;
+    let prefixOffset = -1;
+    for (let cand = 1; cand <= exports.PAIR_AAD_MAX_LEN; cand += 1) {
+        const candPrefixOffset = bytes.length - cand - exports.PAIR_AAD_LEN_PREFIX;
+        if (candPrefixOffset < offset)
+            break;
+        const hi = bytes[candPrefixOffset];
+        const lo = bytes[candPrefixOffset + 1];
+        const declared = (hi << 8) | lo;
+        if (declared === cand) {
+            aadLen = cand;
+            prefixOffset = candPrefixOffset;
+            break;
+        }
+    }
+    if (aadLen < 0 || prefixOffset < 0) {
+        throw new PairBundleError('AAD_LEN_UNDERFLOW', 'could not locate AAD length prefix');
+    }
+    const ciphertext = bytes.slice(offset, prefixOffset);
+    if (ciphertext.length < 16) {
+        throw new PairBundleError('BUNDLE_TOO_SHORT', 'ciphertext shorter than Poly1305 tag');
+    }
+    const aad = bytes.slice(prefixOffset + exports.PAIR_AAD_LEN_PREFIX, bytes.length);
+    if (aad.length !== aadLen) {
+        throw new PairBundleError('AAD_LEN_UNDERFLOW', 'AAD length prefix disagrees with trailer');
+    }
+    return { nonce, ephemeralPublicKey, ciphertext, aad };
+}
+/**
+ * Daemon-side: parse, AAD-verify, decrypt, JSON-parse, validate the
+ * pairing response. Returns the validated plaintext on success; throws
+ * `PairBundleError` on any failure.
+ *
+ * Constant-time-ish AAD comparison: tweetnacl's box.open already runs
+ * Poly1305 in constant time, and the AAD compare we do is byte-by-byte
+ * on a 1KB-bounded buffer — short side-channel exposure is negligible
+ * given we're comparing public-known canonical bytes.
+ */
+function openPairBundleBase64(opts) {
+    if (opts.daemonSecretKey.length !== exports.PAIR_SECRET_LEN) {
+        throw new PairBundleError('INVALID_KEY', 'daemonSecretKey must be 32 bytes');
+    }
+    if (opts.encryptedPayloadBase64.length > exports.PAIR_BUNDLE_MAX_BASE64_LEN) {
+        throw new PairBundleError('BUNDLE_TOO_LONG', `encryptedPayload exceeds ${exports.PAIR_BUNDLE_MAX_BASE64_LEN} chars`);
+    }
+    let bytes;
+    try {
+        bytes = base64ToUint8Array(opts.encryptedPayloadBase64);
+    }
+    catch (err) {
+        throw new PairBundleError('BUNDLE_BAD_BASE64', `encryptedPayload is not valid base64: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const bundle = parsePairBundle(bytes);
+    // AAD verify FIRST — fail fast before doing the box.open work, and
+    // surface a precise error code if the trailer was tampered with.
+    if (!constantTimeEqual(bundle.aad, opts.expectedAad)) {
+        throw new PairBundleError('AAD_MISMATCH', 'pair-response AAD does not match the daemon-rebuilt canonical form');
+    }
+    const plaintextBytes = tweetnacl_1.default.box.open(bundle.ciphertext, bundle.nonce, bundle.ephemeralPublicKey, opts.daemonSecretKey);
+    if (!plaintextBytes) {
+        throw new PairBundleError('DECRYPT_FAILED', 'box.open returned null — wrong key, tampered ciphertext, or wrong nonce');
+    }
+    let json;
+    try {
+        json = JSON.parse(new TextDecoder().decode(plaintextBytes));
+    }
+    catch (err) {
+        throw new PairBundleError('PLAINTEXT_NOT_JSON', `decrypted plaintext is not JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const plaintext = parsePairPlaintext(json);
+    if (plaintext.daemonId !== opts.expectedDaemonId) {
+        throw new PairBundleError('DAEMON_ID_MISMATCH', `decrypted daemonId (${plaintext.daemonId}) does not match expected (${opts.expectedDaemonId})`);
+    }
+    return plaintext;
+}
+const PAIR_URL_SCHEME = 'oversky://pair';
+/**
+ * Build the URL the daemon prints as a QR code. URL-safe parameters
+ * only; the bulk is the public key, which is fine.
+ */
+function buildPairUrl(fields) {
+    const params = new URLSearchParams();
+    params.set('pk', fields.publicKeyBase64Url);
+    params.set('id', fields.pairId);
+    params.set('daemonId', fields.daemonId);
+    if (fields.host)
+        params.set('host', fields.host);
+    if (fields.serverUrl)
+        params.set('server', fields.serverUrl);
+    params.set('v', String(fields.v ?? 1));
+    return `${PAIR_URL_SCHEME}?${params.toString()}`;
+}
+/**
+ * Parse a scanned URL back into structured fields. Returns null on any
+ * format error so the caller can show a user-friendly "not a pair QR"
+ * message rather than a stack trace. Strict validation of every field's
+ * shape keeps a hostile QR from steering the mobile at a bad daemonId.
+ */
+function parsePairUrl(url) {
+    if (typeof url !== 'string' || !url.startsWith(`${PAIR_URL_SCHEME}?`))
+        return null;
+    const query = url.slice(`${PAIR_URL_SCHEME}?`.length);
+    let params;
+    try {
+        params = new URLSearchParams(query);
+    }
+    catch {
+        return null;
+    }
+    const pk = params.get('pk');
+    const id = params.get('id');
+    const daemonId = params.get('daemonId');
+    if (!pk || !id || !daemonId)
+        return null;
+    // Public key: 32 bytes base64url unpadded → 43 chars; tolerate padded too.
+    if (pk.length < 32 || pk.length > 64 || !/^[A-Za-z0-9_-]+={0,2}$/.test(pk))
+        return null;
+    // pairId: hex.
+    if (id.length < 16 || id.length > 64 || !/^[a-f0-9]+$/.test(id))
+        return null;
+    // daemonId: ASCII printable, ≤128 chars.
+    if (daemonId.length === 0 || daemonId.length > 128 || !/^[\x21-\x7E]+$/.test(daemonId)) {
+        return null;
+    }
+    const host = params.get('host') ?? undefined;
+    // eslint-disable-next-line no-control-regex -- intentional: reject hosts containing control chars
+    if (host !== undefined && (host.length > 256 || /[\x00-\x1F]/.test(host)))
+        return null;
+    const serverUrl = params.get('server') ?? undefined;
+    if (serverUrl !== undefined) {
+        try {
+            const u = new URL(serverUrl);
+            if (u.protocol !== 'http:' && u.protocol !== 'https:')
+                return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    const v = params.get('v');
+    const versionNum = v === null ? 1 : Number(v);
+    if (!Number.isInteger(versionNum) || versionNum < 1 || versionNum > 255)
+        return null;
+    return {
+        publicKeyBase64Url: pk,
+        pairId: id,
+        daemonId,
+        host,
+        serverUrl,
+        v: versionNum,
+    };
+}
+// ---------------------------------------------------------------------
+// Encoding helpers — Node + RN compat.
+//
+// Node 16+ supports `Buffer.from(b64, 'base64')`. RN ships a polyfill
+// via `react-native-polyfill-globals`. We avoid `Buffer` entirely and
+// stick to atob/btoa-equivalent pure-byte routines so this module
+// runs unchanged on both platforms.
+// ---------------------------------------------------------------------
+const B64_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+function uint8ArrayToBase64(bytes) {
+    let out = '';
+    let i = 0;
+    for (; i + 2 < bytes.length; i += 3) {
+        const b0 = bytes[i];
+        const b1 = bytes[i + 1];
+        const b2 = bytes[i + 2];
+        out += B64_ALPHABET[b0 >> 2];
+        out += B64_ALPHABET[((b0 & 0x03) << 4) | (b1 >> 4)];
+        out += B64_ALPHABET[((b1 & 0x0f) << 2) | (b2 >> 6)];
+        out += B64_ALPHABET[b2 & 0x3f];
+    }
+    if (i < bytes.length) {
+        const b0 = bytes[i];
+        if (i + 1 === bytes.length) {
+            out += B64_ALPHABET[b0 >> 2];
+            out += B64_ALPHABET[(b0 & 0x03) << 4];
+            out += '==';
+        }
+        else {
+            const b1 = bytes[i + 1];
+            out += B64_ALPHABET[b0 >> 2];
+            out += B64_ALPHABET[((b0 & 0x03) << 4) | (b1 >> 4)];
+            out += B64_ALPHABET[(b1 & 0x0f) << 2];
+            out += '=';
+        }
+    }
+    return out;
+}
+function base64ToUint8Array(b64) {
+    // Tolerate base64url too — the wire format on /respond uses standard
+    // base64, but /poll's `response` field passes through whatever the
+    // mobile sent, and we don't want to fail on a missing-pad edge case.
+    let s = b64.replace(/-/g, '+').replace(/_/g, '/');
+    while (s.length % 4 !== 0)
+        s += '=';
+    const lookup = new Int16Array(128).fill(-1);
+    for (let i = 0; i < B64_ALPHABET.length; i += 1) {
+        lookup[B64_ALPHABET.charCodeAt(i)] = i;
+    }
+    // Strip valid padding.
+    let strLen = s.length;
+    while (strLen > 0 && s.charCodeAt(strLen - 1) === 61 /* '=' */)
+        strLen -= 1;
+    const outLen = (strLen * 3) >> 2;
+    const out = new Uint8Array(outLen);
+    let oi = 0;
+    for (let i = 0; i < strLen; i += 4) {
+        const c0 = lookup[s.charCodeAt(i)] ?? -1;
+        const c1 = i + 1 < strLen ? (lookup[s.charCodeAt(i + 1)] ?? -1) : -1;
+        const c2 = i + 2 < strLen ? (lookup[s.charCodeAt(i + 2)] ?? -1) : -1;
+        const c3 = i + 3 < strLen ? (lookup[s.charCodeAt(i + 3)] ?? -1) : -1;
+        if (c0 < 0 || c1 < 0)
+            throw new Error('invalid base64 character');
+        out[oi++] = (c0 << 2) | (c1 >> 4);
+        if (c2 >= 0)
+            out[oi++] = ((c1 & 0x0f) << 4) | (c2 >> 2);
+        if (c3 >= 0)
+            out[oi++] = ((c2 & 0x03) << 6) | c3;
+    }
+    return out;
+}
+function uint8ArrayToBase64Url(bytes) {
+    return uint8ArrayToBase64(bytes).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function base64UrlToUint8Array(b64url) {
+    return base64ToUint8Array(b64url);
+}
+function constantTimeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i += 1)
+        diff |= a[i] ^ b[i];
+    return diff === 0;
+}
+function generatePairKeyPair() {
+    const kp = tweetnacl_1.default.box.keyPair();
+    return { publicKey: kp.publicKey, secretKey: kp.secretKey };
+}

package/dist/cjs/daemonScopes.d.ts

@@ -0,0 +1,74 @@
+/**
+ * daemonScopes.ts — daemon-capability scope vocabulary for the
+ * non-Mongoose tier.
+ *
+ * The schema-bound canonical home is
+ * `@skrr-ai/data-schemas/common/daemonScopes` — that file owns the
+ * Mongoose validators (`VALID_SCOPE_SET`, schema enum allowlists), the
+ * consent-screen group metadata (`SCOPE_GROUPS`), and the helper
+ * functions that the API server depends on at runtime.
+ *
+ * This file is the parallel home for tiers that cannot import
+ * `@skrr-ai/data-schemas` without dragging Mongoose into their
+ * bundle:
+ *   - `daemon/` (Node CLI / standalone binary, ships via Bun compile)
+ *   - `desktop/` (Electron main process, lean bundle)
+ *   - `cli/` (oclif Sky CLI)
+ *
+ * The two homes are kept byte-equal at CI time by
+ * `api/server/services/Auth/__tests__/daemonScopes.parity.spec.js`.
+ * A new scope MUST be added in BOTH files; the parity test fails on
+ * any drift before merge.
+ *
+ * # Vocabulary stability
+ *
+ * The six strings are user-visible (consent screens) and persisted
+ * (JWT claims, Mongo column values, Redis hash fields, audit logs).
+ * Renaming a scope is a breaking change for every credential already
+ * minted with the old value. Add new scopes, deprecate old ones —
+ * never rename in place.
+ */
+/**
+ * The canonical daemon scope vocabulary. Six strings, frozen.
+ *
+ *   - `daemon:tools:bash`        — bash tool execution
+ *   - `daemon:tools:fs:read`     — Read tool (file read)
+ *   - `daemon:tools:fs:write`    — Write + Edit tools (file mutation)
+ *   - `daemon:browser:cdp`       — browser automation via CDP (reserved)
+ *   - `daemon:session:replay`    — `daemon:session:replay` socket event
+ *   - `daemon:offline-queue`     — daemon-initiated offline queue
+ *
+ * Order is the consent-screen render order: tools-first, I/O second,
+ * control-flow last.
+ */
+export declare const SCOPES: Readonly<{
+    readonly TOOLS_BASH: "daemon:tools:bash";
+    readonly TOOLS_FS_READ: "daemon:tools:fs:read";
+    readonly TOOLS_FS_WRITE: "daemon:tools:fs:write";
+    readonly BROWSER_CDP: "daemon:browser:cdp";
+    readonly SESSION_REPLAY: "daemon:session:replay";
+    readonly OFFLINE_QUEUE: "daemon:offline-queue";
+}>;
+export type DaemonScope = (typeof SCOPES)[keyof typeof SCOPES];
+/**
+ * The six daemon scopes in canonical order. Frozen so consumers can
+ * pass it directly to OAuth `scope` parameters without defensive
+ * copies.
+ */
+export declare const ALL_DAEMON_SCOPES: readonly DaemonScope[];
+/**
+ * Set form of `ALL_DAEMON_SCOPES` for O(1) membership checks.
+ */
+export declare const VALID_DAEMON_SCOPE_SET: ReadonlySet<string>;
+/** Type guard for canonical daemon-scope strings. */
+export declare function isDaemonScope(s: unknown): s is DaemonScope;
+/**
+ * `cli` — REST-only sign-in grant for first-party CLI clients. Peer
+ * to the six daemon scopes; lives on `OAuthClient.allowedScopes` for
+ * the `oversky-cli` client. See the data-schemas canonical for the
+ * full reasoning behind keeping this OUT of `ALL_DAEMON_SCOPES` (the
+ * grandfather sentinel `expandScopes(undefined)` would over-grant).
+ */
+export declare const OAUTH_CLI_SCOPE: "cli";
+export type OAuthCliScope = typeof OAUTH_CLI_SCOPE;
+export type OAuthScope = DaemonScope | OAuthCliScope;

package/dist/cjs/daemonScopes.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * daemonScopes.ts — daemon-capability scope vocabulary for the
+ * non-Mongoose tier.
+ *
+ * The schema-bound canonical home is
+ * `@skrr-ai/data-schemas/common/daemonScopes` — that file owns the
+ * Mongoose validators (`VALID_SCOPE_SET`, schema enum allowlists), the
+ * consent-screen group metadata (`SCOPE_GROUPS`), and the helper
+ * functions that the API server depends on at runtime.
+ *
+ * This file is the parallel home for tiers that cannot import
+ * `@skrr-ai/data-schemas` without dragging Mongoose into their
+ * bundle:
+ *   - `daemon/` (Node CLI / standalone binary, ships via Bun compile)
+ *   - `desktop/` (Electron main process, lean bundle)
+ *   - `cli/` (oclif Sky CLI)
+ *
+ * The two homes are kept byte-equal at CI time by
+ * `api/server/services/Auth/__tests__/daemonScopes.parity.spec.js`.
+ * A new scope MUST be added in BOTH files; the parity test fails on
+ * any drift before merge.
+ *
+ * # Vocabulary stability
+ *
+ * The six strings are user-visible (consent screens) and persisted
+ * (JWT claims, Mongo column values, Redis hash fields, audit logs).
+ * Renaming a scope is a breaking change for every credential already
+ * minted with the old value. Add new scopes, deprecate old ones —
+ * never rename in place.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OAUTH_CLI_SCOPE = exports.VALID_DAEMON_SCOPE_SET = exports.ALL_DAEMON_SCOPES = exports.SCOPES = void 0;
+exports.isDaemonScope = isDaemonScope;
+/**
+ * The canonical daemon scope vocabulary. Six strings, frozen.
+ *
+ *   - `daemon:tools:bash`        — bash tool execution
+ *   - `daemon:tools:fs:read`     — Read tool (file read)
+ *   - `daemon:tools:fs:write`    — Write + Edit tools (file mutation)
+ *   - `daemon:browser:cdp`       — browser automation via CDP (reserved)
+ *   - `daemon:session:replay`    — `daemon:session:replay` socket event
+ *   - `daemon:offline-queue`     — daemon-initiated offline queue
+ *
+ * Order is the consent-screen render order: tools-first, I/O second,
+ * control-flow last.
+ */
+exports.SCOPES = Object.freeze({
+    TOOLS_BASH: 'daemon:tools:bash',
+    TOOLS_FS_READ: 'daemon:tools:fs:read',
+    TOOLS_FS_WRITE: 'daemon:tools:fs:write',
+    BROWSER_CDP: 'daemon:browser:cdp',
+    SESSION_REPLAY: 'daemon:session:replay',
+    OFFLINE_QUEUE: 'daemon:offline-queue',
+});
+/**
+ * The six daemon scopes in canonical order. Frozen so consumers can
+ * pass it directly to OAuth `scope` parameters without defensive
+ * copies.
+ */
+exports.ALL_DAEMON_SCOPES = Object.freeze([
+    exports.SCOPES.TOOLS_BASH,
+    exports.SCOPES.TOOLS_FS_READ,
+    exports.SCOPES.TOOLS_FS_WRITE,
+    exports.SCOPES.BROWSER_CDP,
+    exports.SCOPES.SESSION_REPLAY,
+    exports.SCOPES.OFFLINE_QUEUE,
+]);
+/**
+ * Set form of `ALL_DAEMON_SCOPES` for O(1) membership checks.
+ */
+exports.VALID_DAEMON_SCOPE_SET = new Set(exports.ALL_DAEMON_SCOPES);
+/** Type guard for canonical daemon-scope strings. */
+function isDaemonScope(s) {
+    return typeof s === 'string' && exports.VALID_DAEMON_SCOPE_SET.has(s);
+}
+/**
+ * `cli` — REST-only sign-in grant for first-party CLI clients. Peer
+ * to the six daemon scopes; lives on `OAuthClient.allowedScopes` for
+ * the `oversky-cli` client. See the data-schemas canonical for the
+ * full reasoning behind keeping this OUT of `ALL_DAEMON_SCOPES` (the
+ * grandfather sentinel `expandScopes(undefined)` would over-grant).
+ */
+exports.OAUTH_CLI_SCOPE = 'cli';