@byokit/pair 0.0.0-stage → 0.9.0

package/dist/host.js

@@ -0,0 +1,866 @@
+// The host: the computer that owns the credentials. It pairs devices (scanned or typed code, then a person says yes),
+// keeps one durable grant per device, answers their requests, and removes them. It never listens on anything itself:
+// the app hands it WebSockets (`accept`), or one relay socket that carries many devices (`relay`).
+import { Handshake, b64, b64url, firstFrame, hostId, messageBytes, random, unb64url } from "./channel.js";
+import { bindCode, cleanName, codeKey, encodeCompactOffer, newCode, normalizeCode, offerText } from "./pairing.js";
+import { PublicLinkError } from "./device.js";
+import { LINK_PROBE, LINK_PROBE_OK } from "./check.js";
+import { MAX_STREAMS, Streams } from "./stream.js";
+const HANDSHAKE_MS = 15_000;
+const MAX_TRIES = 5; // wrong codes before every open code is withdrawn
+const MAX_ANSWERS = 1000;
+const MAX_TIMER = 2 ** 31 - 1; // setTimeout's limit (about 24 days)
+/** What a 0.3 host understands beyond 0.1, told to devices in `ready`. */
+export const FEATURES = ['ping', 'unpair', 'rekey'];
+class PairExpired extends Error {
+}
+const later = (ms, fn) => { const t = setTimeout(fn, ms); t.unref?.(); return t; };
+export class Host {
+    keys;
+    /** This host's address on a relay. */
+    id;
+    opts;
+    grants;
+    store;
+    tickets = new Map();
+    codes = new Map();
+    tries = 0;
+    live = new Map();
+    expiryTimers = new Map();
+    answered = new Map();
+    answerWork = new Map();
+    changes = Promise.resolve();
+    unsubscribe;
+    stopped = false;
+    recent = new Map(); // handshake times, per peer and in all ('')
+    constructor(opts, grants) {
+        this.opts = opts;
+        this.keys = opts.keys;
+        this.id = hostId(opts.keys.publicKey);
+        this.store = opts.grants;
+        this.grants = grants;
+    }
+    static async open(opts) {
+        const host = new Host(opts, [...((await opts.grants?.load()) ?? [])]);
+        if (opts.grants?.subscribe) {
+            host.unsubscribe = opts.grants.subscribe(() => { void host.reload().catch((e) => host.report(e)); });
+            try {
+                await host.reload();
+            }
+            catch (e) {
+                host.close();
+                throw e;
+            }
+        }
+        return host;
+    }
+    now() { return this.opts.now?.() ?? Date.now(); }
+    get pairMs() { return Math.min(this.opts.pairMs ?? 300_000, 300_000); }
+    ended(g) { return g.expires !== undefined && g.expires <= this.now(); }
+    currentGrant(grants, id, key) {
+        const g = grants.find((x) => x.id === id);
+        return g && !this.ended(g) && (g.key === key || g.nextKey === key) ? g : undefined;
+    }
+    admitGrant(g, key) {
+        const current = this.grants.find((x) => x.id === g.id);
+        if (!current || current.key !== g.key || current.role !== g.role)
+            return { error: 'removed' };
+        if (this.ended(current))
+            return { error: 'ended' };
+        if (!this.currentGrant(this.grants, g.id, key))
+            return { error: 'removed' };
+        return { grant: current };
+    }
+    async change(fn) {
+        const next = this.changes.then(fn);
+        this.changes = next.then(() => { }, () => { });
+        return next;
+    }
+    async save(grants) { await this.store?.save(grants.map((g) => ({ ...g }))); }
+    report(error) { try {
+        (this.opts.onError ?? console.error)(error);
+    }
+    catch { } }
+    answerTask(device, action) {
+        const next = (this.answerWork.get(device) ?? Promise.resolve()).then(action);
+        const tail = next.then(() => { }, () => { });
+        this.answerWork.set(device, tail);
+        void tail.then(() => { if (this.answerWork.get(device) === tail)
+            this.answerWork.delete(device); });
+        return next;
+    }
+    async drop(device, keys) {
+        if (!keys)
+            this.answered.delete(device);
+        if (this.opts.answers && (!keys || keys.length))
+            await this.answerTask(device, () => this.opts.answers.drop(device, keys));
+    }
+    presence(g, online) {
+        try {
+            this.opts.onConnection?.({ ...g }, online);
+        }
+        catch (e) {
+            this.report(e);
+        }
+    }
+    addLive(conn, entry) {
+        const online = [...this.live.values()].some((s) => s.dev.id === entry.dev.id);
+        this.live.set(conn, entry);
+        if (!online)
+            this.presence(entry.dev, true);
+    }
+    removeLive(conn) {
+        const entry = this.live.get(conn);
+        if (!entry)
+            return;
+        this.live.delete(conn);
+        clearTimeout(this.expiryTimers.get(conn));
+        this.expiryTimers.delete(conn);
+        if (![...this.live.values()].some((s) => s.dev.id === entry.dev.id))
+            this.presence(entry.dev, false);
+    }
+    watchExpiry(conn) {
+        clearTimeout(this.expiryTimers.get(conn));
+        this.expiryTimers.delete(conn);
+        const g = this.live.get(conn)?.dev;
+        if (!g || g.expires === undefined)
+            return;
+        if (this.ended(g))
+            return void this.revoke(g.id, 'ended').catch((e) => this.report(e));
+        this.expiryTimers.set(conn, later(Math.min(g.expires - this.now(), MAX_TIMER), () => this.watchExpiry(conn)));
+    }
+    endLive(id, why, keep) {
+        for (const [conn, s] of this.live)
+            if (s.dev.id === id) {
+                this.removeLive(conn);
+                s.streams.closeAll('removed');
+                if (conn === keep)
+                    continue;
+                this.sealed(conn, s.ch, { t: 'revoked', why });
+                later(1000, () => conn.close(4401, 'removed'));
+            }
+    }
+    /** Every grant change goes through here, one at a time: store first, then memory, then the live sockets. */
+    transition(next, why, persist = true, keep) {
+        return this.change(async () => {
+            const updated = await next(this.grants);
+            if (!updated)
+                return null;
+            if (persist)
+                await this.save(updated);
+            const previous = this.grants;
+            this.grants = updated;
+            const cleanup = [];
+            for (const old of previous) {
+                const current = updated.find((g) => g.id === old.id);
+                if (current && !this.ended(current) && current.key === old.key && current.role === old.role) {
+                    for (const [conn, s] of this.live)
+                        if (s.dev.id === old.id) {
+                            this.live.set(conn, { ...s, dev: current });
+                            if (current.expires !== old.expires)
+                                this.watchExpiry(conn);
+                        }
+                    continue;
+                }
+                if (!current)
+                    void this.drop(old.id).catch((e) => this.report(e));
+                if (why)
+                    this.endLive(old.id, current && this.ended(current) ? 'ended' : why, keep);
+                else
+                    for (const [conn, s] of this.live)
+                        if (s.dev.id === old.id) {
+                            this.removeLive(conn);
+                            s.streams.closeAll('unreachable');
+                            try {
+                                conn.close(1001, 'grant changed');
+                            }
+                            catch { }
+                        }
+                // Invoke synchronously after invalidation; await only after every affected grant has lost access.
+                try {
+                    cleanup.push(Promise.resolve(this.opts.onGrantRemoved?.({ ...old }, !current ? (why === 'ended' ? 'expired' : 'revoked') : this.ended(current) ? 'expired' : 'changed')));
+                }
+                catch (error) {
+                    cleanup.push(Promise.reject(error));
+                }
+            }
+            await Promise.all(cleanup);
+            return updated;
+        });
+    }
+    /** Re-read the durable authority without writing it back. Removed/changed grants close their sockets.
+     *  A failed read leaves memory untouched and rejects; subscribed failures also reach onError. */
+    async reload() {
+        if (!this.store || this.stopped)
+            return;
+        await this.transition(async () => {
+            const grants = await this.store.load();
+            return this.stopped ? null : grants.map((g) => {
+                const current = this.grants.find((old) => old.id === g.id);
+                return current && JSON.stringify(current) === JSON.stringify(g) ? current : { ...g };
+            });
+        }, 'revoked', false);
+    }
+    pending(o) {
+        this.checkLifetime(o.lifetime);
+        return { role: o.role, expires: this.now() + this.pairMs,
+            ...(o.kind === undefined ? {} : { kind: String(o.kind) }), ...(o.lifetime === undefined ? {} : { lifetime: o.lifetime }), ...(o.meta === undefined ? {} : { meta: o.meta }) };
+    }
+    /** A QR's text for one device. `urls` are where a device can reach this host (direct `ws://`, or a relay's
+     *  `wss://…/link/v1/<id>`); `base` makes it a link a browser can open. Single use, gone after `pairMs`. */
+    offer(o) {
+        const p = this.pending(o);
+        const ticket = b64url(random(16));
+        this.tickets.set(ticket, p);
+        this.tries = 0;
+        const offer = { v: 1, host: b64url(this.keys.publicKey), name: cleanName(this.opts.name, 'your computer'), urls: o.urls, ticket,
+            expires: p.expires, role: p.role, ...(p.lifetime === undefined ? {} : { lifetime: p.lifetime }) };
+        return { text: offerText(offer, o.base), expires: p.expires };
+    }
+    /** A QR-sized offer: the same secret a typed code carries (same single use, life, words and approval, through
+     *  one code entry), plus the addresses to try, packed binary. No browser-link form: links keep `offer`. */
+    compactOffer(o) {
+        const p = this.pending(o);
+        const secret = normalizeCode(newCode());
+        const text = encodeCompactOffer({ code: secret, urls: o.urls, expires: p.expires,
+            name: cleanName(this.opts.name, 'your computer'), role: p.role,
+            ...(p.lifetime === undefined ? {} : { lifetime: p.lifetime }) }); // throws before anything is stored
+        this.codes.set(secret, p);
+        this.tries = 0;
+        return { text, code: secret.replace(/(.{4})(?=.)/g, '$1-'), expires: p.expires };
+    }
+    /** A code a person types on the device instead of scanning. Single use, gone after `pairMs`. */
+    code(o) {
+        const code = newCode();
+        const p = this.pending(o);
+        this.codes.set(normalizeCode(code), p);
+        this.tries = 0;
+        return { code, expires: p.expires };
+    }
+    /** A 57-character typed offer that pins this machine's key. Use the whole code with `pairWithCode`;
+     *  addresses come separately (e.g. relay `findHost`). Same approval, single use and expiry as `code`. */
+    shortCode(o) {
+        const { code, expires } = this.code(o);
+        return { code: bindCode(code, this.keys.publicKey), expires };
+    }
+    /** Withdraws every open QR and code. */
+    stopPairing() { this.tickets.clear(); this.codes.clear(); }
+    devices() {
+        const online = new Set([...this.live.values()].map((s) => s.dev.id));
+        return this.grants.map((g) => ({ ...g, online: online.has(g.id) }));
+    }
+    /** Adds a device this app already trusts some other way: for moving devices paired under an older protocol onto
+     *  this one without pairing again. Only call it with a key that arrived over an authenticated channel. */
+    async enrol(g) {
+        const added = await this.grant(b64url(g.key), cleanName(g.name, 'Device'), g);
+        if (!added)
+            throw new Error('Your computer has all the devices it allows. Remove one there first.');
+        return added;
+    }
+    async setMeta(id, meta) {
+        const updated = await this.transition((grants) => grants.some((g) => g.id === id) ? grants.map((g) => g.id === id ? { ...g, meta } : g) : null);
+        if (!updated)
+            throw new Error('Device not found.');
+    }
+    /** Removes a device: its grant goes, its open connections close, and its key is refused from now on. */
+    async revoke(id, why = 'revoked') {
+        if (why === 'ended')
+            this.endLive(id, why);
+        await this.transition((grants) => grants.some((g) => g.id === id) ? grants.filter((g) => g.id !== id) : null, why);
+    }
+    /** An event for every connected device (or those `to` picks). */
+    broadcast(e, to = () => true) {
+        for (const [conn, s] of this.live)
+            if (to(s.dev) && !this.ended(s.dev))
+                this.sealed(conn, s.ch, { t: 'event', e });
+    }
+    /** One WebSocket, straight from a device. `peer` (e.g. its IP address) lets the host slow down one noisy source. */
+    accept(ws, o = {}) {
+        const h = this.connection({ send: (t) => ws.send(t), binary: (b) => ws.send(b), close: (c, r) => ws.close(c, r) }, o.peer);
+        ws.addEventListener('message', (e) => {
+            const d = e.data;
+            if (typeof d === 'string')
+                return h.message(d);
+            if (d instanceof ArrayBuffer)
+                return h.message(new Uint8Array(d));
+            if (ArrayBuffer.isView(d))
+                return h.message(new Uint8Array(d.buffer, d.byteOffset, d.byteLength)); // ws's Buffer
+            ws.close(4400, 'unexpected frame');
+        });
+        ws.addEventListener('close', () => h.closed());
+    }
+    /** One WebSocket to a relay that carries many devices' connections. Each relay message is `{c, f}` (connection id,
+     *  one frame, exactly as a device sent it or should get it) or `{c, end: code}`. The relay sees only that. */
+    relay(ws) {
+        const conns = new Map();
+        ws.addEventListener('message', (e) => {
+            let m;
+            try {
+                m = JSON.parse(String(e.data));
+            }
+            catch {
+                return;
+            }
+            if (typeof m?.c !== 'string' || m.c.length > 64)
+                return;
+            let h = conns.get(m.c);
+            if (m.end !== undefined) {
+                h?.closed();
+                conns.delete(m.c);
+                return;
+            }
+            if (typeof m.f !== 'string')
+                return;
+            if (!h) {
+                const c = m.c;
+                h = this.connection({
+                    send: (f) => ws.send(JSON.stringify({ c, f })),
+                    close: (code) => { if (conns.delete(c)) {
+                        ws.send(JSON.stringify({ c, end: code }));
+                        h.closed();
+                    } },
+                });
+                conns.set(c, h);
+            }
+            h.message(m.f);
+        });
+        ws.addEventListener('close', () => { for (const h of conns.values())
+            h.closed(); conns.clear(); });
+    }
+    close() {
+        this.stopped = true;
+        this.unsubscribe?.();
+        this.unsubscribe = undefined;
+        for (const [conn, { streams }] of this.live) {
+            streams.closeAll('unreachable');
+            this.removeLive(conn);
+            conn.close(1001, 'host closing');
+        }
+        this.live.clear();
+    }
+    sealed(conn, ch, msg) { this.out(conn, () => ch.seal(msg)); }
+    out(conn, frames) {
+        try {
+            for (const f of frames())
+                conn.send(f);
+        }
+        catch {
+            conn.close(4400, 'send failed');
+        }
+    }
+    /** What the device hears when the app's stream code throws: a `PublicLinkError`'s message, else `failed`. */
+    reason(e) {
+        if (e instanceof PublicLinkError)
+            return e.message.slice(0, 200);
+        this.report(e);
+        return 'failed';
+    }
+    take(map, key) {
+        const p = map.get(key);
+        map.delete(key); // single use, even when it has run out
+        return p && p.expires >= this.now() ? p : undefined;
+    }
+    wrong() {
+        if (++this.tries >= MAX_TRIES)
+            this.stopPairing();
+    }
+    /** A sliding one-minute window, in all and per peer; checked before any key agreement is spent on a stranger. */
+    admit(peer) {
+        const now = Date.now();
+        const limits = [['', this.opts.handshakes?.perMinute ?? 300]];
+        if (peer)
+            limits.push([`peer:${peer}`, this.opts.handshakes?.perPeer ?? 30]);
+        for (const [k, times] of this.recent) {
+            const fresh = times.filter((t) => t > now - 60_000);
+            if (fresh.length)
+                this.recent.set(k, fresh);
+            else
+                this.recent.delete(k);
+        }
+        const windows = limits.map(([k, max]) => {
+            const w = this.recent.get(k) ?? [];
+            this.recent.set(k, w);
+            return [w, max];
+        });
+        if (windows.some(([w, max]) => w.length >= max))
+            return false;
+        for (const [w] of windows)
+            w.push(now);
+        return true;
+    }
+    checkLifetime(lifetime) {
+        if (lifetime !== undefined && (!Number.isSafeInteger(lifetime) || lifetime <= 0))
+            throw new Error('A lifetime must be a positive whole number of milliseconds.');
+    }
+    async grant(key, name, t, pairExpires) {
+        this.checkLifetime(t.lifetime);
+        let added = null;
+        await this.transition((grants) => {
+            if (pairExpires !== undefined && pairExpires < this.now())
+                throw new PairExpired();
+            const others = grants.filter((g) => g.key !== key && g.nextKey !== key); // pairing the same device again replaces its grant
+            if (this.opts.maxDevices && others.length >= this.opts.maxDevices)
+                return null;
+            const cap = t.kind === undefined ? undefined : this.opts.caps?.[t.kind];
+            if (cap !== undefined && others.filter((g) => g.kind === t.kind).length >= cap)
+                return null;
+            const now = this.now();
+            added = { id: b64url(random(9)), key, name, role: t.role, created: now, lastSeen: now,
+                ...(t.kind === undefined ? {} : { kind: t.kind }), ...(t.lifetime === undefined ? {} : { expires: now + t.lifetime }), ...(t.meta === undefined ? {} : { meta: t.meta }) };
+            return [...others, added];
+        });
+        // A slow store can commit after the code ran out: the five-minute life holds through the save too.
+        if (added && pairExpires !== undefined && pairExpires < this.now()) {
+            await this.revoke(added.id);
+            throw new PairExpired();
+        }
+        return added;
+    }
+    connection(conn, peer) {
+        let hs = null;
+        let ch = null;
+        let dev = null;
+        let code;
+        let busy = false; // waiting for the person at the host
+        let gone = false;
+        const timer = later(HANDSHAKE_MS, () => { if (!dev && !busy)
+            end(4408, 'too slow'); });
+        const end = (c, why) => { if (!gone)
+            conn.close(c, why); };
+        const refuse = (why) => { this.sealed(conn, ch, { t: 'refused', why }); later(1000, () => end(4401, why)); };
+        const pair = async (key, name, p, how, kept) => {
+            const k = b64url(key);
+            busy = true;
+            clearTimeout(timer);
+            const req = { name: cleanName(name, 'Device'), role: p.role, words: hs.words, how,
+                ...(p.kind === undefined ? {} : { kind: p.kind }), ...(p.lifetime ? { lifetime: p.lifetime } : {}), ...(p.meta === undefined ? {} : { meta: p.meta }) };
+            const yes = await Promise.race([
+                Promise.resolve().then(() => this.opts.confirm(req)).catch(() => false),
+                new Promise((r) => later(this.pairMs, () => r(false))),
+            ]);
+            // A device that said it kept a pending grant resumes from it after being killed while the person decided, so
+            // its yes outlives the socket; any other gone device could never use the grant, so it gets none.
+            if (gone && kept !== 1)
+                return;
+            if (!yes) {
+                if (!gone)
+                    refuse('declined');
+                return;
+            }
+            try {
+                const added = await this.grant(k, req.name, p, p.expires);
+                if (gone)
+                    return;
+                if (added)
+                    await attach(added, true);
+                else
+                    refuse('full');
+            }
+            catch (e) {
+                if (!gone)
+                    refuse(e instanceof PairExpired ? 'expired' : 'failed');
+            }
+        };
+        const attach = async (g, paired = false, auth) => {
+            if (gone)
+                return;
+            busy = true;
+            const key = b64url(hs.remoteKey);
+            const admit = () => {
+                const current = this.grants.find((x) => x.id === g.id);
+                if (!current)
+                    return 'not-paired';
+                if (this.ended(current))
+                    return 'ended';
+                return this.currentGrant(this.grants, g.id, key) ?? 'not-paired';
+            };
+            const reject = (why) => {
+                if (why === 'ended')
+                    void this.revoke(g.id, 'ended').catch((e) => this.report(e));
+                refuse(why);
+            };
+            try {
+                if (!paired) {
+                    // A device that rekeyed proves its new key by using it; from then on only that key works.
+                    const updated = await this.transition((grants) => {
+                        const current = this.currentGrant(grants, g.id, key);
+                        if (!current)
+                            return null;
+                        return grants.map((x) => {
+                            if (x.id !== g.id)
+                                return x;
+                            const { nextKey, ...rest } = x;
+                            return nextKey === key ? { ...rest, key, lastSeen: this.now() } : { ...x, lastSeen: this.now() };
+                        });
+                    });
+                    if (!updated)
+                        return refuse('not-paired');
+                }
+                if (gone || this.stopped)
+                    return end(1001, 'host closing');
+                const before = admit();
+                if (typeof before === 'string')
+                    return reject(before);
+                if (auth?.fresh === true) {
+                    try {
+                        await this.drop(before.id);
+                    }
+                    catch (e) {
+                        this.report(e);
+                        return refuse('failed');
+                    }
+                }
+                else if (auth)
+                    this.acknowledge(before.id, auth.session, auth.ack);
+                if (gone)
+                    return;
+                const current = admit();
+                if (typeof current === 'string')
+                    return reject(current);
+                dev = g = current;
+                busy = false;
+                clearTimeout(timer);
+                const c = ch;
+                const data = conn.binary
+                    ? (s, d) => { try {
+                        for (const f of c.sealData(s, d))
+                            conn.binary(f);
+                    }
+                    catch {
+                        conn.close(4400, 'send failed');
+                    } }
+                    : (s, d) => this.out(conn, () => c.sealData(s, d).map(b64));
+                const streams = new Streams({ send: (m) => this.sealed(conn, c, m), data, reason: (e) => this.reason(e), report: (e) => this.report(e) });
+                const meta = this.opts.deviceMeta?.({ ...g });
+                this.addLive(conn, { dev, ch: c, streams });
+                this.sealed(conn, c, { t: 'ready', device: { id: g.id, name: g.name, role: g.role }, host: { name: this.opts.name }, features: FEATURES,
+                    ...(g.expires === undefined ? {} : { expires: g.expires }),
+                    ...(meta === undefined ? {} : { meta }),
+                    ...(this.opts.stream ? { streams: 1, ...(conn.binary ? { binary: 1 } : {}) } : {}) });
+                this.watchExpiry(conn);
+            }
+            catch {
+                if (!gone)
+                    refuse('failed');
+            }
+        };
+        const handshake = (text) => {
+            if (!hs) {
+                if (!this.admit(peer))
+                    return end(4429, 'slow down');
+                const first = firstFrame(text);
+                if (first.mode === 'ik') {
+                    hs = new Handshake('ik', false, this.keys);
+                    let hello;
+                    try {
+                        hello = hs.read(first.body);
+                    }
+                    catch {
+                        return end(4403, 'wrong host key');
+                    } // dialled for another key
+                    if (hello.v !== 1)
+                        throw new Error('unknown version');
+                    conn.send(hs.write());
+                    ch = hs.channel();
+                    return;
+                }
+                // A typed code: whichever open code finishes the handshake is the one this device holds.
+                for (const [c, p] of this.codes) {
+                    const attempt = new Handshake('code', false, this.keys, { psk: codeKey(c) });
+                    try {
+                        attempt.read(first.body);
+                    }
+                    catch {
+                        continue;
+                    }
+                    this.codes.delete(c); // single use from the moment it is tried
+                    if (p.expires < this.now())
+                        break;
+                    hs = attempt;
+                    code = p;
+                    conn.send(hs.write());
+                    return;
+                }
+                this.wrong();
+                return end(4401, 'wrong code');
+            }
+            const hello = hs.read(text); // the typed-code handshake's last message: the device's key and name
+            ch = hs.channel();
+            void pair(hs.remoteKey, hello.name, code, 'code', hello.pending);
+        };
+        const inner = (d, m) => {
+            if (m.t === 'req')
+                return void this.request(conn, d, m, b64url(hs.remoteKey));
+            if (m.t === 'ping')
+                return this.sealed(conn, ch, { t: 'pong', n: m.n });
+            if (m.t === 'unpair') { // the device forgets this computer, and asks it to forget the device too
+                return void this.transition((grants) => this.currentGrant(grants, d.id, b64url(hs.remoteKey)) ? grants.filter((g) => g.id !== d.id) : null, 'revoked', true, conn)
+                    .then((ok) => { if (!ok)
+                    return refuse('not-paired'); this.sealed(conn, ch, { t: 'unpaired' }); later(1000, () => end(1000, 'unpaired')); })
+                    .catch((e) => {
+                    this.report(e);
+                    this.sealed(conn, ch, { t: 'unpair-failed' });
+                });
+            }
+            if (m.t === 'rekey') { // a fresh device key, valid alongside the old one until the device first uses it
+                let key;
+                try {
+                    key = b64url(unb64url(String(m.key)));
+                    if (unb64url(key).length !== 32)
+                        throw new Error();
+                }
+                catch {
+                    return end(4400, 'bad key');
+                }
+                return void this.transition((grants) => this.currentGrant(grants, d.id, b64url(hs.remoteKey)) ? grants.map((g) => g.id === d.id ? { ...g, nextKey: key } : g) : null)
+                    .then((ok) => { if (ok)
+                    this.sealed(conn, ch, { t: 'rekeyed' });
+                else
+                    refuse('not-paired'); })
+                    .catch((e) => { this.report(e); end(4400, 'failed'); });
+            }
+        };
+        return {
+            message: (text) => {
+                if (gone)
+                    return;
+                try {
+                    if (!ch) {
+                        // A reachability probe (`check` in check.ts): answered read-only, before any handshake is spent. It
+                        // touches no ticket, code, grant or counter, so a probed offer still pairs; the reply carries nothing
+                        // but the fact a link host is here. Through a relay this rides the same bare frames as a handshake.
+                        if (text === LINK_PROBE) {
+                            conn.send(LINK_PROBE_OK);
+                            return later(250, () => { if (!gone)
+                                conn.close(1000, 'probe'); });
+                        }
+                        return typeof text === 'string' ? handshake(text) : end(4400, 'text frames only');
+                    }
+                    const m = ch.open(text); // throws unless this is the device's next authentic frame
+                    if (m === undefined || busy)
+                        return;
+                    if (dev) {
+                        const key = b64url(hs.remoteKey);
+                        if (['open', 'data', 'credit', 'end', 'opened'].includes(m.t)) {
+                            const admitted = this.admitGrant(dev, key);
+                            if ('error' in admitted) {
+                                if (admitted.error === 'ended')
+                                    void this.revoke(dev.id, 'ended').catch((e) => this.report(e));
+                                else {
+                                    this.live.get(conn)?.streams.closeAll('removed');
+                                    this.removeLive(conn);
+                                    end(4401, 'not-paired');
+                                }
+                                return;
+                            }
+                        }
+                        if (m.t === 'open')
+                            return void this.openStream(dev, this.live.get(conn).streams, m, key).catch(() => end(4400, 'bad stream message'));
+                        if (this.live.get(conn)?.streams.message(m))
+                            return;
+                        return inner(dev, m);
+                    }
+                    if (m.t === 'auth') {
+                        const k = b64url(hs.remoteKey);
+                        const g = this.grants.find((x) => x.key === k || x.nextKey === k);
+                        if (!g)
+                            return refuse('not-paired');
+                        if (this.ended(g)) {
+                            void this.revoke(g.id, 'ended').catch((e) => this.report(e));
+                            return refuse('ended');
+                        }
+                        if (!this.currentGrant(this.grants, g.id, k))
+                            return refuse('not-paired');
+                        return void attach(g, false, m);
+                    }
+                    if (m.t === 'pair' && hs.mode === 'ik') {
+                        const p = typeof m.ticket === 'string' ? this.take(this.tickets, m.ticket) : undefined;
+                        if (!p) {
+                            this.wrong();
+                            return refuse('expired');
+                        }
+                        return void pair(hs.remoteKey, m.name, p, 'scan', m.pending);
+                    }
+                    end(4400, 'unexpected');
+                }
+                catch {
+                    end(4400, 'bad frame'); // a bad frame ends the socket; the device reconnects with a fresh handshake
+                }
+            },
+            closed: () => { gone = true; clearTimeout(timer); this.live.get(conn)?.streams.closeAll('unreachable'); this.removeLive(conn); },
+        };
+    }
+    async openStream(dev, streams, m, authenticatedKey) {
+        const id = m.s, credit = m.credit;
+        if (!Number.isInteger(id) || id < 1 || id > 2 ** 32 - 1 || streams.has(id) || !Number.isInteger(credit) || credit < 0)
+            throw new Error('bad stream message');
+        const s = streams.add(id, String(m.op ?? ''), m.args);
+        const req = { op: s.op, args: s.args };
+        if (!this.opts.stream)
+            return s.end('not-supported');
+        if (streams.size > MAX_STREAMS)
+            return s.end('busy');
+        const admitted = await this.admitRequest(req, dev, authenticatedKey);
+        if ('error' in admitted) {
+            if (admitted.error === 'ended')
+                void this.revoke(dev.id, 'ended').catch((e) => this.report(e));
+            return s.end(admitted.error);
+        }
+        if (!streams.has(id))
+            return;
+        s.accept(Math.min(credit, 2 ** 31));
+        try {
+            await this.opts.stream(s, req, admitted.grant);
+        }
+        catch (e) {
+            s.end(this.reason(e));
+        }
+    }
+    acknowledge(device, session, ack) {
+        if (typeof session !== 'string' || !Number.isSafeInteger(ack) || ack < 0)
+            return;
+        const seen = this.answered.get(device);
+        const gone = [];
+        if (seen)
+            for (const [key, entry] of seen)
+                if (entry.session === session && entry.id <= ack) {
+                    seen.delete(key);
+                    gone.push(key);
+                }
+        void this.drop(device, gone).catch((e) => this.report(e));
+    }
+    async request(conn, dev, m, authenticatedKey) {
+        const id = m.id;
+        const answer = (r) => { const s = this.live.get(conn); if (s)
+            this.sealed(conn, s.ch, { t: 'res', id, ...r }); };
+        const g = this.grants.find((x) => x.id === dev.id);
+        if (!g || (!this.ended(g) && !this.currentGrant(this.grants, dev.id, authenticatedKey)))
+            return answer({ ok: false, error: 'removed' });
+        if (this.ended(g)) {
+            answer({ ok: false, error: 'ended' });
+            return void this.revoke(g.id, 'ended').catch((e) => this.report(e));
+        }
+        this.acknowledge(g.id, m.session, m.ack);
+        const seen = this.answered.get(g.id) ?? new Map();
+        this.answered.set(g.id, seen);
+        const key = typeof m.key === 'string' && m.key.length <= 80 ? m.key : '';
+        const session = typeof m.session === 'string' && m.session.length <= 80 ? m.session : '';
+        if (!key || !session || !Number.isSafeInteger(id) || id < 1)
+            return answer({ ok: false, error: 'failed' });
+        const req = { op: String(m.op ?? ''), args: m.args, key: `${g.id}:${key}` };
+        const args = JSON.stringify(req.args ?? null);
+        let entry = seen.get(key);
+        if (entry && (entry.op !== req.op || entry.args !== args))
+            return answer({ ok: false, error: 'failed' });
+        let cached = !!entry;
+        if (!entry) {
+            if (seen.size >= MAX_ANSWERS)
+                return answer({ ok: false, error: 'busy' });
+            const store = this.opts.answers;
+            const reply = Promise.resolve().then(async () => {
+                if (store) {
+                    let kept;
+                    try {
+                        kept = await this.answerTask(g.id, () => store.get(g.id, key));
+                    }
+                    catch (e) {
+                        this.report(e);
+                        return { ok: false, error: 'failed' };
+                    } // unknown: never run twice
+                    if (kept != null) {
+                        if (typeof kept !== 'object' || Array.isArray(kept))
+                            return { ok: false, error: 'failed' };
+                        const record = kept;
+                        if (record.op !== req.op || record.args !== args || !record.reply || typeof record.reply !== 'object' || Array.isArray(record.reply))
+                            return { ok: false, error: 'failed' };
+                        const r = record.reply;
+                        const fields = Object.keys(r);
+                        if (r.ok === true && fields.includes('ok') && fields.every((f) => f === 'ok' || f === 'value')) {
+                            cached = true;
+                            return fields.includes('value') ? { ok: true, value: r.value } : { ok: true };
+                        }
+                        if (r.ok === false && typeof r.error === 'string' && fields.includes('ok') && fields.includes('error') && fields.every((f) => f === 'ok' || f === 'error' || f === 'message') && (fields.length === 2 || (fields.length === 3 && typeof r.message === 'string'))) {
+                            cached = true;
+                            return { ok: false, error: r.error, ...(fields.length === 3 ? { message: r.message } : {}) };
+                        }
+                        return { ok: false, error: 'failed' };
+                    }
+                }
+                const result = await this.run(req, g, m.notValidAfter, authenticatedKey);
+                if (store)
+                    try {
+                        await this.answerTask(g.id, () => store.put(g.id, key, { op: req.op, args, reply: result }));
+                    }
+                    catch (e) {
+                        this.report(e);
+                    }
+                return result;
+            });
+            entry = { id, session, op: req.op, args, reply };
+            seen.set(key, entry);
+        }
+        const reply = await entry.reply;
+        const admitted = await this.admitRequest(req, g, authenticatedKey, cached);
+        if ('error' in admitted) {
+            answer({ ok: false, error: admitted.error });
+            if (admitted.error === 'ended')
+                void this.revoke(g.id, 'ended').catch((e) => this.report(e));
+            return;
+        }
+        answer(reply);
+    }
+    async admitRequest(req, g, authenticatedKey, checkPolicy = true) {
+        const before = this.admitGrant(g, authenticatedKey);
+        if ('error' in before)
+            return before;
+        const current = before.grant;
+        if (!checkPolicy)
+            return before;
+        const denied = current.role === 'control' ? 'not-allowed' : 'view-only';
+        try {
+            const ok = this.opts.allow ? await this.opts.allow(req, current) : current.role === 'control' || (this.opts.canView?.(req) ?? false);
+            if (ok !== true)
+                return { error: denied };
+        }
+        catch (e) {
+            this.report(e);
+            return { error: denied };
+        }
+        const after = this.admitGrant(g, authenticatedKey);
+        if ('error' in after)
+            return after;
+        if (after.grant !== current)
+            return { error: denied };
+        return after;
+    }
+    async run(req, g, notValidAfter, authenticatedKey) {
+        const checked = (result) => {
+            const snapshot = JSON.parse(JSON.stringify(result));
+            messageBytes({ t: 'res', id: 0, ...snapshot });
+            return snapshot;
+        };
+        // A request that arrives after the moment its sender said it stops making sense is not run at all.
+        if (typeof notValidAfter === 'number' && this.now() > notValidAfter)
+            return { ok: false, error: 'too-late' };
+        const admitted = await this.admitRequest(req, g, authenticatedKey);
+        if ('error' in admitted)
+            return { ok: false, error: admitted.error };
+        if (typeof notValidAfter === 'number' && this.now() > notValidAfter)
+            return { ok: false, error: 'too-late' };
+        try {
+            return checked({ ok: true, value: await this.opts.handle(req, admitted.grant) });
+        }
+        catch (e) {
+            if (e instanceof PublicLinkError) {
+                try {
+                    return checked({ ok: false, error: 'public', message: e.message });
+                }
+                catch (invalid) {
+                    e = invalid;
+                }
+            }
+            this.report(e);
+            return { ok: false, error: 'failed' };
+        }
+    }
+}