@skrr-ai/auth-core 0.1.2

package/dist/esm/daemonPair.d.ts

@@ -0,0 +1,172 @@
+/** Box nonce length per RFC 8439 / NaCl. */
+export declare const PAIR_NONCE_LEN = 24;
+/** Curve25519 public key length. */
+export declare const PAIR_PUBKEY_LEN = 32;
+/** Curve25519 secret key length. */
+export declare const PAIR_SECRET_LEN = 32;
+/** Big-endian uint16 length prefix for the AAD trailer. */
+export declare const PAIR_AAD_LEN_PREFIX = 2;
+/** Server validator caps `encryptedPayload` at 8192 chars (base64). */
+export declare const PAIR_BUNDLE_MAX_BASE64_LEN = 8192;
+/** Conservative ceiling on the trailer to keep the bundle well under cap. */
+export declare const PAIR_AAD_MAX_LEN = 1024;
+/** AAD prefix — version-bumped on any breaking format change. */
+export declare const PAIR_AAD_PREFIX = "oversky:pair:v1";
+export type PairBundleErrorCode = 'BUNDLE_TOO_SHORT' | 'BUNDLE_TOO_LONG' | 'BUNDLE_BAD_BASE64' | 'AAD_LEN_OVERFLOW' | 'AAD_LEN_UNDERFLOW' | 'AAD_MISMATCH' | 'DECRYPT_FAILED' | 'PLAINTEXT_NOT_JSON' | 'PLAINTEXT_BAD_SHAPE' | 'DAEMON_ID_MISMATCH' | 'INVALID_KEY';
+export declare class PairBundleError extends Error {
+    readonly code: PairBundleErrorCode;
+    constructor(code: PairBundleErrorCode, message: string);
+}
+/**
+ * Plaintext shape sealed inside the box. Versioned via `v` so future
+ * additions (e.g. data-encryption-key for L12 envelope handoff) extend
+ * the schema without breaking older daemons.
+ *
+ * `token` is optional because Stage-E #1 step 4 daemon-scope mints ship
+ * `opaqueAccessToken` only (no JWT). At least one of `token` or
+ * `opaqueAccessToken` MUST be present, enforced in `parsePairPlaintext`.
+ */
+export interface PairPlaintextV1 {
+    v: 1;
+    /** Daemon-scope JWT — optional after Stage-E #1 step 4. */
+    token?: string;
+    /** Access token expiry (epoch ms). */
+    expiresAt?: number;
+    /** Rotating refresh token. */
+    refreshToken?: string;
+    /** Refresh token expiry (epoch ms). */
+    refreshExpiresAt?: number;
+    /** Stage-E #1 — opaque `osk_dmn_*` daemon access token. */
+    opaqueAccessToken?: string;
+    /**
+     * The daemonId the credentials were minted for. Daemon MUST verify
+     * this matches the `daemonId` it advertised in the QR — guards against
+     * a misdirected /respond targeting a different daemon's pairing row.
+     */
+    daemonId: string;
+    /** Mobile-side issuance time (epoch ms). For audit/log only. */
+    issuedAt: number;
+}
+export interface PairBundle {
+    /** Raw 24-byte nonce. */
+    nonce: Uint8Array;
+    /** Raw 32-byte mobile ephemeral public key. */
+    ephemeralPublicKey: Uint8Array;
+    /** Box ciphertext (plaintext + Poly1305 tag). */
+    ciphertext: Uint8Array;
+    /** Canonical AAD bytes — SHOULD match the rebuilt AAD on verify. */
+    aad: Uint8Array;
+}
+/**
+ * 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.
+ */
+export declare function buildPairAad(daemonId: string, responseUserId: string): Uint8Array;
+/**
+ * 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.
+ */
+export declare function parsePairPlaintext(raw: unknown): PairPlaintextV1;
+export interface AssembleBundleOptions {
+    /** Plaintext to seal — JSON-stringified before boxing. */
+    plaintext: PairPlaintextV1;
+    /** Daemon's ephemeral X25519 public key (32 bytes). */
+    daemonPublicKey: Uint8Array;
+    /** Mobile's ephemeral X25519 secret key (32 bytes). */
+    ephemeralSecretKey: Uint8Array;
+    /** Mobile's ephemeral X25519 public key (32 bytes), echoed into bundle. */
+    ephemeralPublicKey: Uint8Array;
+    /** Canonical AAD bytes from `buildPairAad`. */
+    aad: Uint8Array;
+    /**
+     * Override the random nonce — for tests only. Production callers must
+     * leave this undefined so a fresh nonce is generated.
+     */
+    __nonceForTest?: Uint8Array;
+}
+/**
+ * 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`.
+ */
+export declare function assemblePairBundleBase64(opts: AssembleBundleOptions): string;
+/**
+ * Parse the wire bytes into a `PairBundle` without decrypting. Used as
+ * a preflight by `openPairBundleBase64` and exposed for tests.
+ */
+export declare function parsePairBundle(bytes: Uint8Array): PairBundle;
+export interface OpenBundleOptions {
+    /** Base64 wire payload from `/poll`'s `response` field. */
+    encryptedPayloadBase64: string;
+    /** Daemon's ephemeral X25519 secret key. */
+    daemonSecretKey: Uint8Array;
+    /**
+     * Canonical AAD bytes the daemon expects, rebuilt from `daemonId` +
+     * `responseUserId` returned by the /poll response.
+     */
+    expectedAad: Uint8Array;
+    /**
+     * The daemonId the daemon advertised in its QR. We verify the
+     * decrypted plaintext echoes the SAME id, in addition to the AAD
+     * trailer the server bound. Belt-and-suspenders.
+     */
+    expectedDaemonId: string;
+}
+/**
+ * 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.
+ */
+export declare function openPairBundleBase64(opts: OpenBundleOptions): PairPlaintextV1;
+export interface PairUrlFields {
+    /** 32-byte daemon ephemeral public key, base64url no-pad. */
+    publicKeyBase64Url: string;
+    /** Server-issued pair id, hex. */
+    pairId: string;
+    /** Daemon id (free-form, ASCII, ≤128 chars). */
+    daemonId: string;
+    /**
+     * User-friendly machine label so the mobile can show "Approve pairing
+     * with MacBook-Pro?" — purely UX, not security-bearing.
+     */
+    host?: string;
+    /** Server URL the daemon is paired against, for split-deployment hints. */
+    serverUrl?: string;
+    /**
+     * Wire-format protocol version. Bump on any breaking change to the
+     * bundle layout or AAD canonical form.
+     */
+    v?: number;
+}
+/**
+ * Build the URL the daemon prints as a QR code. URL-safe parameters
+ * only; the bulk is the public key, which is fine.
+ */
+export declare function buildPairUrl(fields: PairUrlFields): string;
+/**
+ * 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.
+ */
+export declare function parsePairUrl(url: string): PairUrlFields | null;
+export declare function uint8ArrayToBase64(bytes: Uint8Array): string;
+export declare function base64ToUint8Array(b64: string): Uint8Array;
+export declare function uint8ArrayToBase64Url(bytes: Uint8Array): string;
+export declare function base64UrlToUint8Array(b64url: string): Uint8Array;
+export interface PairKeyPair {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+}
+export declare function generatePairKeyPair(): PairKeyPair;

package/dist/esm/daemonPair.js

@@ -0,0 +1,476 @@
+/**
+ * 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.
+ */
+import nacl from 'tweetnacl';
+// ---------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------
+/** Box nonce length per RFC 8439 / NaCl. */
+export const PAIR_NONCE_LEN = 24;
+/** Curve25519 public key length. */
+export const PAIR_PUBKEY_LEN = 32;
+/** Curve25519 secret key length. */
+export const PAIR_SECRET_LEN = 32;
+/** Big-endian uint16 length prefix for the AAD trailer. */
+export const PAIR_AAD_LEN_PREFIX = 2;
+/** Server validator caps `encryptedPayload` at 8192 chars (base64). */
+export const PAIR_BUNDLE_MAX_BASE64_LEN = 8192;
+/** Conservative ceiling on the trailer to keep the bundle well under cap. */
+export const PAIR_AAD_MAX_LEN = 1024;
+/** AAD prefix — version-bumped on any breaking format change. */
+export const PAIR_AAD_PREFIX = 'oversky:pair:v1';
+export class PairBundleError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'PairBundleError';
+        this.code = code;
+    }
+}
+// ---------------------------------------------------------------------
+// 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.
+ */
+export 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 = `${PAIR_AAD_PREFIX}:daemonId=${daemonId}:responseUserId=${responseUserId}`;
+    if (text.length > 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.
+ */
+export 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`.
+ */
+export function assemblePairBundleBase64(opts) {
+    if (opts.daemonPublicKey.length !== PAIR_PUBKEY_LEN) {
+        throw new PairBundleError('INVALID_KEY', 'daemonPublicKey must be 32 bytes');
+    }
+    if (opts.ephemeralSecretKey.length !== PAIR_SECRET_LEN) {
+        throw new PairBundleError('INVALID_KEY', 'ephemeralSecretKey must be 32 bytes');
+    }
+    if (opts.ephemeralPublicKey.length !== PAIR_PUBKEY_LEN) {
+        throw new PairBundleError('INVALID_KEY', 'ephemeralPublicKey must be 32 bytes');
+    }
+    if (opts.aad.length === 0 || opts.aad.length > PAIR_AAD_MAX_LEN) {
+        throw new PairBundleError('AAD_LEN_OVERFLOW', 'aad must be 1..1024 bytes');
+    }
+    const nonce = opts.__nonceForTest ?? nacl.randomBytes(PAIR_NONCE_LEN);
+    if (nonce.length !== 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 = nacl.box(plaintextBytes, nonce, opts.daemonPublicKey, opts.ephemeralSecretKey);
+    const totalLen = PAIR_NONCE_LEN + PAIR_PUBKEY_LEN + ciphertext.length + PAIR_AAD_LEN_PREFIX + opts.aad.length;
+    const bundle = new Uint8Array(totalLen);
+    let offset = 0;
+    bundle.set(nonce, offset);
+    offset += PAIR_NONCE_LEN;
+    bundle.set(opts.ephemeralPublicKey, offset);
+    offset += 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 += PAIR_AAD_LEN_PREFIX;
+    bundle.set(opts.aad, offset);
+    const base64 = uint8ArrayToBase64(bundle);
+    if (base64.length > PAIR_BUNDLE_MAX_BASE64_LEN) {
+        throw new PairBundleError('BUNDLE_TOO_LONG', `encryptedPayload exceeds ${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.
+ */
+export function parsePairBundle(bytes) {
+    const minLen = PAIR_NONCE_LEN + PAIR_PUBKEY_LEN + 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 + PAIR_NONCE_LEN);
+    offset += PAIR_NONCE_LEN;
+    const ephemeralPublicKey = bytes.slice(offset, offset + PAIR_PUBKEY_LEN);
+    offset += 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 < 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 + 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 <= PAIR_AAD_MAX_LEN; cand += 1) {
+        const candPrefixOffset = bytes.length - cand - 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 + 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.
+ */
+export function openPairBundleBase64(opts) {
+    if (opts.daemonSecretKey.length !== PAIR_SECRET_LEN) {
+        throw new PairBundleError('INVALID_KEY', 'daemonSecretKey must be 32 bytes');
+    }
+    if (opts.encryptedPayloadBase64.length > PAIR_BUNDLE_MAX_BASE64_LEN) {
+        throw new PairBundleError('BUNDLE_TOO_LONG', `encryptedPayload exceeds ${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 = nacl.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.
+ */
+export 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.
+ */
+export 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+/';
+export 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;
+}
+export 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;
+}
+export function uint8ArrayToBase64Url(bytes) {
+    return uint8ArrayToBase64(bytes).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+export 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;
+}
+export function generatePairKeyPair() {
+    const kp = nacl.box.keyPair();
+    return { publicKey: kp.publicKey, secretKey: kp.secretKey };
+}