@byokit/pair 0.0.0-stage → 0.9.0

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { hostId, keyPair, keyPairFrom, b64url, unb64url, type KeyPair } from './channel.ts';
+export { Host, type AnswerStore, type Grant, type GrantStore, type GrantTerms, type HostOptions, type LinkRequest, type PairRequest, type Role, type Socket, } from './host.ts';
+export { DeviceLink, LINK_WORDS, LinkError, PublicLinkError, pairWithCode, pairWithOffer, pendingGrant, type DeviceGrant, type DeviceStore, type Dial, type LinkOptions, type LinkProblem, type LinkStatus, type RequestOptions, } from './device.ts';
+export { cleanName, decodeCompactOffer, decodeOffer, encodeCompactOffer, encodeOffer, normalizeCode, offerText, parseOffer, parseV1Offer, COMPACT_TAG } from './pairing.ts';
+export { LinkStream, WINDOW } from './stream.ts';
+export { check, LINK_PROBE, LINK_PROBE_OK, type CheckOptions, type CheckResult } from './check.ts';
+export type { CompactOffer, PairOffer } from './pairing.ts';
+export { browserDeviceStore, browserDeviceStores, secureDeviceStore, secureDeviceStores, type DeviceStores, type KeptDevice, type SecureStoreLike } from './stores.ts';
+export { migrateGrant, GrantMigrationError, type GrantMigrationProblem } from './migrate.ts';

package/dist/index.js

@@ -0,0 +1,8 @@
+export { hostId, keyPair, keyPairFrom, b64url, unb64url } from "./channel.js";
+export { Host, } from "./host.js";
+export { DeviceLink, LINK_WORDS, LinkError, PublicLinkError, pairWithCode, pairWithOffer, pendingGrant, } from "./device.js";
+export { cleanName, decodeCompactOffer, decodeOffer, encodeCompactOffer, encodeOffer, normalizeCode, offerText, parseOffer, parseV1Offer, COMPACT_TAG } from "./pairing.js";
+export { LinkStream, WINDOW } from "./stream.js";
+export { check, LINK_PROBE, LINK_PROBE_OK } from "./check.js";
+export { browserDeviceStore, browserDeviceStores, secureDeviceStore, secureDeviceStores } from "./stores.js";
+export { migrateGrant, GrantMigrationError } from "./migrate.js";

package/dist/migrate.d.ts

@@ -0,0 +1,14 @@
+import type { DeviceGrant } from './device.ts';
+export type GrantMigrationProblem = 'unsupported-format' | 'invalid-grant';
+/** A migration failure. Neither the message nor the error retains the input or its keys. */
+export declare class GrantMigrationError extends Error {
+    readonly code: GrantMigrationProblem;
+    constructor(code: GrantMigrationProblem);
+}
+/** Converts the pre-kit Crewhouse phone grant (no `v`, padded base64 `sk`/`crewdPk`,
+ *  `fp`, `urls`, `device`) from a parsed object or its JSON. The fingerprint checks
+ *  host-key consistency, not authenticity: only a connection to the host verifies
+ *  the device's access. No storage, network access or logging is performed. */
+export declare function migrateGrant(raw: unknown, options: {
+    format: 'crewhouse-v0';
+}): DeviceGrant;

package/dist/migrate.js

@@ -0,0 +1,62 @@
+import { b64, b64url, hash, unb64 } from "./channel.js";
+/** A migration failure. Neither the message nor the error retains the input or its keys. */
+export class GrantMigrationError extends Error {
+    code;
+    constructor(code) {
+        super(code === 'unsupported-format' ? 'This saved pairing needs a different update.' : 'This saved pairing cannot be read. Pair this device again.');
+        this.name = 'GrantMigrationError';
+        this.code = code;
+    }
+}
+const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const text = (value) => typeof value === 'string' && value.trim().length > 0;
+const bad = () => { throw new GrantMigrationError('invalid-grant'); };
+const key = (value) => {
+    if (typeof value !== 'string' || !/^[A-Za-z0-9+/]{43}=$/.test(value))
+        return bad();
+    const bytes = unb64(value);
+    if (bytes.length !== 32 || b64(bytes) !== value)
+        return bad();
+    return bytes;
+};
+const wsUrl = (value) => {
+    if (typeof value !== 'string' || !/^wss?:\/\//.test(value) || /\s/.test(value))
+        return false;
+    const url = new URL(value);
+    return !!url.hostname && !url.username && !url.password && !url.hash;
+};
+/** Converts the pre-kit Crewhouse phone grant (no `v`, padded base64 `sk`/`crewdPk`,
+ *  `fp`, `urls`, `device`) from a parsed object or its JSON. The fingerprint checks
+ *  host-key consistency, not authenticity: only a connection to the host verifies
+ *  the device's access. No storage, network access or logging is performed. */
+export function migrateGrant(raw, options) {
+    let supported = false;
+    try {
+        supported = options?.format === 'crewhouse-v0';
+    }
+    catch { }
+    if (!supported)
+        throw new GrantMigrationError('unsupported-format');
+    try {
+        const g = typeof raw === 'string' ? JSON.parse(raw) : raw;
+        if (!record(g) || Object.keys(g).length !== 5 || Object.keys(g).some((k) => !['sk', 'crewdPk', 'fp', 'urls', 'device'].includes(k)))
+            return bad();
+        const secret = key(g.sk), host = key(g.crewdPk);
+        const fp = Array.from(hash(16, host).subarray(0, 8), (b) => b.toString(16).padStart(2, '0')).join('').match(/.{4}/g).join(' ');
+        if (g.fp !== fp || !Array.isArray(g.urls) || !g.urls.length)
+            return bad();
+        const urls = Array.from(g.urls);
+        if (!urls.every(wsUrl))
+            return bad();
+        const d = g.device;
+        if (!record(d) || Object.keys(d).length !== 3 || Object.keys(d).some((k) => !['id', 'name', 'role'].includes(k)) ||
+            !text(d.id) || !text(d.name) || (d.role !== 'control' && d.role !== 'view'))
+            return bad();
+        return { v: 1, secretKey: b64url(secret), host: b64url(host), hostName: 'your computer',
+            urls: urls, device: { id: d.id, name: d.name, role: d.role } };
+    }
+    catch {
+        // JSON, URL and crypto errors can carry input text; expose only a fixed typed failure.
+        throw new GrantMigrationError('invalid-grant');
+    }
+}

package/dist/node.d.ts

@@ -0,0 +1,17 @@
+import type { GrantStore } from './host.ts';
+import { type KeyPair } from './channel.ts';
+import type { KeptDevice } from './stores.ts';
+/** The host's key pair, kept in `path` (0600, in a 0700 folder, written atomically). The first call makes it.
+ *  A file that exists but can't be read as a key is never replaced: a new key would silently cut off every paired
+ *  device, so it throws and a person decides. */
+export declare function hostKeyFile(path: string): KeyPair;
+/** The parts of Electron's `safeStorage` this uses; pass `safeStorage` from 'electron' (main process, after `ready`). */
+export type SafeStorageLike = {
+    encryptString(text: string): Uint8Array;
+    decryptString(data: Buffer): string;
+};
+export declare function fileDeviceStore(path: string, safeStorage?: SafeStorageLike): KeptDevice;
+/** Host grants at the app's path: atomic 0600 writes and notifications across processes, including rename/unlink.
+ *  Cooperating writers lock and reject stale snapshots; notifications are advisory and Host.reload reads the authority.
+ *  Polling avoids platform-dependent rename watcher loss. No keys or application files are discovered. */
+export declare function fileGrantStore(path: string, intervalMs?: number): GrantStore;

package/dist/node.js

@@ -0,0 +1,210 @@
+// Node only (`@byokit/pair/node`): host key and device grant files. Kept out of the main entry for browsers and React Native.
+import { closeSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, unlinkSync, unwatchFile, watchFile, writeFileSync, writeSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { b64url, keyPair, keyPairFrom, random, unb64url } from "./channel.js";
+/** The host's key pair, kept in `path` (0600, in a 0700 folder, written atomically). The first call makes it.
+ *  A file that exists but can't be read as a key is never replaced: a new key would silently cut off every paired
+ *  device, so it throws and a person decides. */
+export function hostKeyFile(path) {
+    const folder = dirname(path);
+    mkdirSync(folder, { recursive: true, mode: 0o700 });
+    if ((lstatSync(folder).mode & 0o777) !== 0o700)
+        throw new Error(`${folder} must be a private 0700 folder for the link key`);
+    const existing = () => {
+        const st = lstatSync(path);
+        if (!st.isFile())
+            throw new Error(`${path} is not a plain file; refusing to use it as the link key`);
+        if (st.mode & 0o077)
+            throw new Error(`${path} allows others to read or write; refusing to use it as the link key`);
+        const o = JSON.parse(readFileSync(path, 'utf8'));
+        const secret = typeof o?.secretKey === 'string' ? unb64url(o.secretKey) : new Uint8Array();
+        if (o?.v !== 1 || secret.length !== 32)
+            throw new Error(`${path} does not hold a link key; refusing to replace it`);
+        return keyPairFrom(secret);
+    };
+    try {
+        return existing();
+    }
+    catch (e) {
+        if (e?.code !== 'ENOENT')
+            throw e;
+    }
+    const keys = keyPair();
+    const tmp = `${path}.${process.pid}.${b64url(random(6))}.tmp`;
+    let created = false;
+    try {
+        const fd = openSync(tmp, 'wx', 0o600);
+        created = true;
+        try {
+            writeSync(fd, JSON.stringify({ v: 1, secretKey: b64url(keys.secretKey) }));
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        try {
+            linkSync(tmp, path);
+        }
+        catch (e) {
+            if (e?.code === 'EEXIST')
+                return existing();
+            throw e;
+        }
+        return keys;
+    }
+    finally {
+        if (created)
+            try {
+                unlinkSync(tmp);
+            }
+            catch (e) {
+                if (e?.code !== 'ENOENT')
+                    throw e;
+            }
+    }
+}
+export function fileDeviceStore(path, safeStorage) {
+    return {
+        async load() {
+            let raw;
+            try {
+                raw = readFileSync(path);
+            }
+            catch (e) {
+                if (e?.code === 'ENOENT')
+                    return null;
+                throw e;
+            }
+            const g = JSON.parse(safeStorage ? safeStorage.decryptString(raw) : raw.toString('utf8'));
+            return g?.v === 1 ? g : null;
+        },
+        save(g) {
+            const text = JSON.stringify(g);
+            mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+            const tmp = `${path}.${process.pid}.${b64url(random(6))}.tmp`;
+            let created = false;
+            try {
+                const fd = openSync(tmp, 'wx', 0o600);
+                created = true;
+                try {
+                    writeFileSync(fd, safeStorage ? safeStorage.encryptString(text) : text);
+                    fsyncSync(fd);
+                }
+                finally {
+                    closeSync(fd);
+                }
+                renameSync(tmp, path);
+            }
+            finally {
+                if (created)
+                    try {
+                        unlinkSync(tmp);
+                    }
+                    catch (e) {
+                        if (e?.code !== 'ENOENT')
+                            throw e;
+                    }
+            }
+        },
+        clear() { rmSync(path, { force: true }); },
+    };
+}
+/** Host grants at the app's path: atomic 0600 writes and notifications across processes, including rename/unlink.
+ *  Cooperating writers lock and reject stale snapshots; notifications are advisory and Host.reload reads the authority.
+ *  Polling avoids platform-dependent rename watcher loss. No keys or application files are discovered. */
+export function fileGrantStore(path, intervalMs = 100) {
+    if (!Number.isSafeInteger(intervalMs) || intervalMs < 1)
+        throw new Error('A watch interval must be a positive whole number of milliseconds.');
+    let loaded;
+    const read = () => {
+        try {
+            const st = lstatSync(path);
+            if (!st.isFile() || st.mode & 0o077)
+                throw new Error('Link grants must be a private plain file.');
+            const folder = lstatSync(dirname(path));
+            if (!folder.isDirectory() || (folder.mode & 0o777) !== 0o700)
+                throw new Error('Link grants require a private 0700 folder.');
+            return readFileSync(path, 'utf8');
+        }
+        catch (e) {
+            if (e?.code === 'ENOENT')
+                return null;
+            throw e;
+        }
+    };
+    return {
+        load() {
+            const text = read();
+            if (text === null) {
+                loaded = null;
+                return [];
+            }
+            const grants = JSON.parse(text);
+            if (!Array.isArray(grants) || grants.some((g) => !g || typeof g.id !== 'string' || typeof g.key !== 'string'
+                || typeof g.name !== 'string' || !['view', 'control'].includes(g.role) || !Number.isFinite(g.created)
+                || (g.expires !== undefined && !Number.isFinite(g.expires)))
+                || new Set(grants.map((g) => g.id)).size !== grants.length)
+                throw new Error('Invalid link grants.');
+            loaded = text;
+            return grants;
+        },
+        async save(grants) {
+            mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+            const folder = lstatSync(dirname(path));
+            if (!folder.isDirectory() || (folder.mode & 0o777) !== 0o700)
+                throw new Error('Link grants require a private 0700 folder.');
+            // Cooperating writers use the same exclusive lock. Never erase an abandoned lock automatically.
+            const lock = `${path}.lock`;
+            let fd;
+            const until = Date.now() + 5000;
+            while (fd === undefined) {
+                try {
+                    fd = openSync(lock, 'wx', 0o600);
+                }
+                catch (e) {
+                    if (e?.code !== 'EEXIST' || Date.now() >= until)
+                        throw e;
+                    await new Promise((r) => setTimeout(r, 10));
+                }
+            }
+            const tmp = `${path}.${process.pid}.${b64url(random(6))}.tmp`;
+            let created = false;
+            try {
+                const current = read();
+                if (loaded !== undefined && current !== loaded)
+                    throw new Error('Link grants changed in another process; reload before saving.');
+                const text = JSON.stringify(grants);
+                const file = openSync(tmp, 'wx', 0o600);
+                created = true;
+                try {
+                    writeFileSync(file, text);
+                    fsyncSync(file);
+                }
+                finally {
+                    closeSync(file);
+                }
+                renameSync(tmp, path);
+                loaded = text;
+            }
+            finally {
+                try {
+                    if (created)
+                        unlinkSync(tmp);
+                }
+                catch (e) {
+                    if (e?.code !== 'ENOENT')
+                        throw e;
+                }
+                finally {
+                    closeSync(fd);
+                    unlinkSync(lock);
+                }
+            }
+        },
+        subscribe(changed) {
+            const listener = () => changed();
+            watchFile(path, { interval: intervalMs, persistent: false }, listener);
+            return () => unwatchFile(path, listener);
+        },
+    };
+}

package/dist/pairing.d.ts

@@ -0,0 +1,71 @@
+import type { Role } from './host.ts';
+/** What a scanned QR (or opened pairing link) holds. The ticket is single-use and short-lived. `role` and `lifetime`
+ *  (how long the device's access lasts, in ms; absent means until removed) let the device say what it is agreeing to
+ *  before it connects; 0.1 parsers ignore them, and the host's own records decide. */
+export type PairOffer = {
+    v: 1;
+    host: string;
+    name: string;
+    urls: string[];
+    ticket: string;
+    expires: number;
+    role?: Role;
+    lifetime?: number;
+};
+/** A device or host name as a person should see it: no hidden characters, at most 60 of them. */
+export declare const cleanName: (name: unknown, fallback: string) => string;
+/** The QR's text. Give a web address (`https://…/pair`) to get a link a browser can open instead: the offer rides in
+ *  the part after `#`, which browsers never send to a server. */
+export declare function offerText(offer: PairOffer, base?: string): string;
+/** Scan (or pasted link) in, offer out; throws a plain sentence for anything that is not a live byokit pairing code.
+ * A compact offer comes back without `host` or `ticket` (it has neither: `pairWithOffer` learns the host key).
+ * Pass `0` as `now` to inspect an expired offer without connecting. */
+export declare function parseOffer(scanned: string, now?: number): PairOffer | CompactOffer;
+/** A version 1 offer only; `parseOffer` for anything else. */
+export declare function parseV1Offer(scanned: string, now?: number): PairOffer;
+/** A complete offline offer in groups of five base32 characters, with a transcription checksum. This carries the
+ * same single-use ticket as the QR; it neither extends expiry nor replaces host approval. */
+export declare function encodeOffer(offer: PairOffer): string;
+/** Read an offline offer without network access. Case, spaces and dashes are ignored; O means 0 and I/L mean 1.
+ * Old compact direct offers remain readable for migration; new offers always use the current format.
+ * Other typos fail the checksum. Expiry and addresses follow `parseV1Offer`; `now = 0` permits inspection only. */
+export declare function decodeOffer(text: string, now?: number): PairOffer;
+/** Typed codes use letters and numbers nobody mixes up (no 0/O, 1/I/L). Twelve of them are about 59 bits: too many
+ *  to guess, even offline, in the few minutes a code lives. */
+export declare const CODE_ALPHABET = "23456789ABCDEFGHJKMNPQRSTUVWXYZ";
+export declare function newCode(): string;
+/** A legacy secret or machine-bound short code, normalized or null. Case, spaces and dashes don't matter. */
+export declare function normalizeCode(typed: string): string | null;
+/** Public machine-key commitment; the secret's entropy still comes only from `newCode`. */
+export declare const shortKey: (hostKey: Uint8Array) => string;
+export declare const bindCode: (code: string, hostKey: Uint8Array) => string;
+/** Accept a bound code or the legacy secret; malformed bound codes never downgrade. */
+export declare function parseCode(typed: string): {
+    secret: string;
+    commitment?: string;
+} | null;
+/** The Noise pre-shared key a typed code stands for. */
+export declare const codeKey: (code: string) => Uint8Array;
+export declare const COMPACT_TAG = "BYOKIT-LINK:2:";
+export type CompactOffer = {
+    code: string;
+    urls: string[];
+    expires: number;
+    name: string;
+    role: Role;
+    lifetime?: number;
+};
+/** Pack a code secret, its addresses and terms into QR-sized text. Throws a plain sentence for anything that would
+ *  not survive the trip (bad addresses, absurd lengths); the host calls this before storing the code, so a throw
+ *  leaves no open entry behind. */
+export declare function encodeCompactOffer(o: {
+    code: string;
+    urls: string[];
+    expires: number;
+    name: string;
+    role: Role;
+    lifetime?: number;
+}): string;
+/** Read a compact offer. Case, spaces and dashes are forgiven; anything else that is not a compact offer throws a
+ *  plain sentence. Expiry follows `parseOffer`; `now = 0` permits inspection only. */
+export declare function decodeCompactOffer(scanned: string, now?: number): CompactOffer;