@byokit/pair 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.9.0 (2026-10-09)
+
+- FIX: a phone killed while the person at the computer decides now resumes against the pinned computer, for compact and version 1 QRs alike. `pairWithOffer` takes `onPending(grant)`, which hands over the pending grant to keep before the computer can approve this device, and `pendingGrant` accepts a compact QR given the authenticated `host` key, and `parseOffer` reads a compact QR for inspection (expiry, addresses, name, role) without one. Before, `pendingGrant` refused compact QRs, and even a version 1 pending grant never came online after a real kill. A socket that drops once the computer has taken the code now ends pairing with `unreachable` instead of trying the next address, where the spent code or ticket could only be refused as `wrong-code` or `expired`. A socket that closes while `onPending` is still saving ends pairing at once with that close; a version 1 `onPending` that never settles times out. The compact QR is unchanged: 109 characters for one relay address and the name Umer.
+- SECURITY: pinning and approval semantics. A compact QR's pending grant pins the key the code handshake authenticated, kept after Noise message 2 and before the device's identity goes out in message 3; if saving it fails, pairing stops before the computer learns the device. A device using `onPending` says so inside the handshake, and only then does the computer keep a yes given after its socket dropped, granting only the device key that handshake authenticated; any other device that leaves still gets no grant. A computer with another key at the same address is still refused, and a version 1 `pendingGrant` refuses a `host` that differs from its QR.
+- `parseOffer` now returns `PairOffer | CompactOffer`, so a compact QR parses for inspection. Code that reads `.host` or `.ticket`, or passes the result to `offerText` or `encodeOffer`, narrows with `'host' in offer`, or calls the new `parseV1Offer` for the old version 1-only type.
+- FIX: the pairing picture's words match what the host now prints: scan the code, or type the shown code where the phone page asks for it, with no raw address to type.
+- FIX: the browser pairing test closes only the Chromium processes it spawned — over that browser's own private CDP pipe — instead of signalling a whole process group, so a killed or timed-out test can no longer take out or leave behind the wrong process tree. `BYOKIT_CHROME` is the single documented key that selects the test browser.
+
 ## 0.8.0 (2026-10-07)
 
 - Add redacted startup, page/module and link-stage diagnostics to the browser pairing test; the intermittent CI timeout's root cause remains unknown.

package/README.md

@@ -152,11 +152,13 @@ const { text } = host.offer({
 console.log(text); // terminal-to-browser deep link; the offer stays after #
 ```
 
-`offerText(parseOffer(text), 'https://app.example/pair.html')` makes the same deep link from an existing offer.
+`offerText(parseV1Offer(text), 'https://app.example/pair.html')` makes the same deep link from an existing version 1 offer.
 There is no separate `offerLink`. Use `parseOffer(text, 0)` to inspect an expired offer; this does not renew it,
-and pairing still refuses an expired ticket.
+and pairing still refuses an expired ticket. `parseOffer` reads a compact QR too, returning a `CompactOffer` (expiry,
+addresses, name, role) with no `host` or `ticket`: narrow with `'host' in offer` before reading a version 1 offer's
+fields. `parseV1Offer` is the old version 1-only parse, for `offerText` and `encodeOffer`, which take a `PairOffer`.
 
-For an offline, typeable alternative, `encodeOffer(parseOffer(text))` holds the **entire offer**, including
+For an offline, typeable alternative, `encodeOffer(parseV1Offer(text))` holds the **entire offer**, including
 all direct and relay addresses. `decodeOffer` also reads old compact direct codes for migration, preserving
 their key, ticket, role and second-resolution expiry; re-encoding uses the current complete format.
 `decodeOffer(typed)` returns a `PairOffer` and checks expiry without contacting
@@ -279,10 +281,17 @@ await link.request('send.message', { text: 'hi' });  // waits through reconnects
 await link.request('send.message', { text: 'hi' }, { timeoutMs: 20_000, notValidAfter: Date.now() + 60_000 });
 ```
 
-- For crash-safe pairing, make a `keyPair()`, save `pendingGrant(scanned, { name, key })` before pairing, then pass
-  that same `key` to `pairWithOffer(scanned, { name, key, onWords })`. If the app dies while the person decides,
-  a `DeviceLink` made from the saved pending grant retries until approval (up to five minutes after the offer expires),
-  then forgets it if the host still has not approved.
+- For crash-safe pairing, pass `onPending: (g) => secureStore.save(g)` to `pairWithOffer`. It gets the pending grant
+  before the host can approve this device: for a compact offer, once the host proved it holds the code and before
+  this device's key and name reach it (so the grant pins the host key the handshake authenticated); for a version 1
+  offer, before dialling. If the app dies while the person decides, a `DeviceLink` made from the saved pending grant
+  retries until approval (up to five minutes after the offer expires), then forgets it if the host still has not
+  approved; a host with another key there is `refused`. Because the device tells the host it kept a pending grant, a yes
+  given after it went away still counts; a device that kept none gets no grant it could never use. So when
+  `pairWithOffer` rejects after `onPending` ran without a sealed refusal (`e.sealed` false, e.g. `unreachable` once the
+  computer has taken the code), keep the pending grant and make a `DeviceLink` from it: it comes online on a yes and forgets
+  itself on a no.
+  `pendingGrant(scanned, { name, key, host })` builds the same grant; a compact offer needs `host`.
 - `resolve: (url) => …` runs before each dial (e.g. open an SSH tunnel and return `ws://127.0.0.1:<port>/…`);
   `link.addUrl(url)` adds an address found later (a wrong host there just fails its handshake).
 - A quiet connection is pinged (`pingMs`, default 20 s) and redialled when the host stops answering; at most

package/SECURITY.md

@@ -27,7 +27,7 @@ A home computer (the **host**) holds AI sign-ins and other credentials. Phones,
 | QR / pairing link | `byokit-link:1:<base64url JSON>`: `{v, host (X25519 public key), name, urls, ticket (128 bits), expires, role?, lifetime?}`. The optional role and access lifetime let the device show the terms; older parsers ignore them. As a link, it rides after `#`, which browsers never send to a server. |
 | Offline offer envelope | Versioned base32 of the complete validated offer plus a 32-bit FNV-1a transcription checksum. Case, whitespace, dashes and O/0, I/L/1 aliases are normalized; noncanonical padding is refused. The checksum is not authentication. The same QR ticket, host key, expiry and approval rules apply; relay addresses and grant terms are preserved. |
 | Typed code | 12 characters from a 31-character unambiguous alphabet (about 59 bits), `XXXX-XXXX-XXXX`. |
-| Pairing rules | Tickets and codes are single use (burned at first presentation, even when expired or refused), live 5 minutes through grant creation, and 5 wrong tries withdraw every open ticket and code. Nothing is stored until the person at the host approves; both screens show the same **two confirmation words**, derived from the handshake hash. Optional device cap. |
+| Pairing rules | Tickets and codes are single use (burned at first presentation, even when expired or refused), live 5 minutes through grant creation, and 5 wrong tries withdraw every open ticket and code. Nothing is stored until the person at the host approves; both screens show the same **two confirmation words**, derived from the handshake hash. Optional device cap. An approval holds after the device's socket dropped only when the device said, inside the handshake (`pending: 1` in its sealed `pair` request or typed-code message 3), that it kept a pending grant; the grant names only the device key that handshake authenticated. Any other device that leaves gets no grant, so no slot is held by a key nobody has. A compact QR carries no host key; the device keeps the key the code handshake authenticated (after message 2, before its identity goes out in message 3) as its pending grant's pin, so a resumed link is pinned exactly as from a version 1 QR. |
 | Grants | Held by the host with a device key and role; optional `kind`, `expires`, `nextKey` and `meta` support caps, expiry, rekey and app policy. Every handshake and request checks the grant. `allow` decides access when supplied; otherwise control is allowed and view-only uses `canView` (default: none). |
 | Presence and reload | Presence counts authenticated live sockets per grant and fires only on first/last. Store notifications trigger a serialized `Host.reload` with no write-back; removed/key-changed/role-changed grants close live sockets, and changed expiry reschedules access. A failed read preserves the last known authority and reports the failure: notifications are eventual, so an app needing instantaneous external-authority checks must enforce them in `allow`. The Node file backend uses a cooperating-writer lock and rejects stale snapshots; it polls only the app's chosen path and stops when the host closes. |
 | Ready metadata | Only the opt-in `deviceMeta(grant)` projection is sent to the device, inside the sealed `ready`. Host grant metadata is private by default. The app must not project credentials. |
@@ -115,9 +115,9 @@ A home computer (the **host**) holds AI sign-ins and other credentials. Phones,
 - [x] Host policy is enforced before the app handler; without `allow`, view-only defaults closed. Only an explicit `PublicLinkError` discloses its chosen message; other handler failures are logged on the host and return plain `failed`.
 - [x] A device forgets its grant only on a sealed `revoked`, `ended` or `not-paired` (or when a pending pairing expires).
 - [x] Names shown to people are stripped of control and direction-flipping characters and capped at 60.
-- [x] `parseOffer` accepts only `ws:`/`wss:` addresses without credentials, at most 8, a 32-byte key and 16-byte
+- [x] `parseV1Offer` accepts only `ws:`/`wss:` addresses without credentials, at most 8, a 32-byte key and 16-byte
       ticket.
-- [x] Offline offer decoding checks the checksum, version, canonical padding, bounds and all `parseOffer` rules, including expiry; inspecting with `now = 0` never renews a ticket. Legacy compact offers are accepted only on the migration read path, with their original pinned key, ticket, role and second-resolution expiry; they cannot change new encodings.
+- [x] Offline offer decoding checks the checksum, version, canonical padding, bounds and all `parseV1Offer` rules, including expiry; inspecting with `now = 0` never renews a ticket. Legacy compact offers are accepted only on the migration read path, with their original pinned key, ticket, role and second-resolution expiry; they cannot change new encodings.
 - [x] The channel refuses frames past 2³² − 1 and messages over 16 MB.
 - [x] Stream opens re-check the grant and policy before the app's `stream` handler; data past a stream's window,
       or stream data that isn't a binary inner message, drops the socket; streams end on disconnect and revoke.

package/dist/device.d.ts

@@ -78,15 +78,24 @@ type PairOptions = Dial & {
 };
 /** The grant a scanned code will become, to keep in secure storage *before* pairing. If the app dies while the person
  *  at the host decides, a `DeviceLink` made from it later connects once the host has said yes (or learns it said no),
- *  instead of leaving the host holding a grant for a key nobody has. Pass its key to `pairWithOffer`. */
+ *  instead of leaving the host holding a grant for a key nobody has. Pass its key to `pairWithOffer`, or let
+ *  `pairWithOffer`'s `onPending` hand it over. A compact offer carries no host key: it needs `host`, the key the code
+ *  handshake authenticated (`onPending` passes it). For a version 1 offer, a different `host` is refused. */
 export declare function pendingGrant(scanned: string, o: {
     name: string;
     key?: KeyPair;
+    host?: string;
 }): DeviceGrant;
+type OfferOptions = PairOptions & {
+    /** Keep this pending grant before the host can approve this device (see `pendingGrant`). A compact offer calls it
+     *  once the host proved it holds the code, before this device's key and name reach it; a throw stops pairing there. */
+    onPending?: (g: DeviceGrant) => void | Promise<void>;
+};
 /** A scanned QR (or opened pairing link) in, a grant out, once the person at the host says yes. `onWords` gets the
  *  two words to show while they decide. Tries each address in the code until one answers. A compact offer pairs
- *  like a typed code over the packed addresses: same single use, life, words and approval, no host key pinned. */
-export declare function pairWithOffer(scanned: string, o: PairOptions): Promise<DeviceGrant>;
+ *  like a typed code over the packed addresses: same single use, life, words and approval; the host key it pins is
+ *  the one the code handshake authenticated, handed to `onPending` before the host learns this device. */
+export declare function pairWithOffer(scanned: string, o: OfferOptions): Promise<DeviceGrant>;
 /** A typed code in, a grant out. `Host.shortCode` also pins the machine key before sharing the device identity.
  *  `url` is an untrusted address, e.g. from relay `findHost`; only the full code authenticates the host. */
 export declare function pairWithCode(url: string, typed: string, o: PairOptions): Promise<DeviceGrant>;

package/dist/device.js

@@ -3,7 +3,7 @@
 // its requests survive a reconnect: each carries a key, so a retried tap runs once. Uses only the platform's
 // WebSocket, so the same code runs in browsers, React Native and Node.
 import { Handshake, b64, b64url, keyPair, keyPairFrom, random, unb64url } from "./channel.js";
-import { cleanName, codeKey, decodeCompactOffer, parseCode, parseOffer, shortKey, COMPACT_TAG } from "./pairing.js";
+import { cleanName, codeKey, decodeCompactOffer, parseCode, parseOffer, parseV1Offer, shortKey, COMPACT_TAG } from "./pairing.js";
 import { Streams } from "./stream.js";
 /** Every way the link can fail, in words a person can act on. */
 export const LINK_WORDS = {
@@ -43,6 +43,10 @@ export class PublicLinkError extends LinkError {
 const known = (why) => typeof why === 'string' && Object.hasOwn(LINK_WORDS, why);
 const problem = (why) => (known(why) ? why : 'unreachable');
 const later = (ms, fn) => { const t = setTimeout(fn, ms); t.unref?.(); return t; };
+const within = (ms, work) => new Promise((resolve, reject) => {
+    const t = later(ms, () => reject(new LinkError('timeout')));
+    work.then((v) => { clearTimeout(t); resolve(v); }, (e) => { clearTimeout(t); reject(e); });
+});
 /** One socket: the handshake, the first request (`auth` or `pair`), and the host's `ready`. */
 async function dial(url, me, host, hello, o, on = { message: () => { }, close: () => { } }) {
     let target = url;
@@ -107,16 +111,33 @@ async function dial(url, me, host, hello, o, on = { message: () => { }, close: (
                     } // only the right host can answer
                     if (host.commitment && shortKey(hs.remoteKey) !== host.commitment)
                         return fail(new LinkError('wrong-host'));
-                    if (hello.t === 'code')
-                        ws.send(hs.write({ name: hello.name }));
-                    ch = hs.channel();
-                    if (hello.t !== 'code')
-                        send(hello);
-                    if (pairing) { // now a person at the host decides; give them time
-                        o.onWords?.(hs.words);
-                        clearTimeout(timer);
-                        timer = later(6 * 60_000, () => fail(new LinkError('timeout')));
-                    }
+                    const go = () => {
+                        if (hello.t === 'code')
+                            ws.send(hs.write({ name: hello.name, ...(hello.pending ? { pending: 1 } : {}) }));
+                        ch = hs.channel();
+                        if (hello.t !== 'code')
+                            send(hello);
+                        if (pairing) { // now a person at the host decides; give them time
+                            o.onWords?.(hs.words);
+                            clearTimeout(timer);
+                            timer = later(6 * 60_000, () => fail(new LinkError('timeout')));
+                        }
+                    };
+                    if (!host.pin)
+                        return go();
+                    // The host proved it holds the code; the app keeps its key before this device is disclosed in message 3. A save
+                    // that never settles times out, or ends sooner when the host drops the socket.
+                    clearTimeout(timer);
+                    within(o.timeoutMs ?? 8000, Promise.resolve().then(() => host.pin(hs.remoteKey))).then(() => {
+                        if (settled)
+                            return;
+                        try {
+                            go();
+                        }
+                        catch {
+                            fail(new LinkError('unreachable'));
+                        }
+                    }, fail);
                     return;
                 }
                 const m = ch.open(typeof ev.data === 'string' ? ev.data : new Uint8Array(ev.data)); // throws unless it is the host's next authentic frame
@@ -146,47 +167,72 @@ function granted(me, hostKey, url, urls, ready) {
 }
 /** The grant a scanned code will become, to keep in secure storage *before* pairing. If the app dies while the person
  *  at the host decides, a `DeviceLink` made from it later connects once the host has said yes (or learns it said no),
- *  instead of leaving the host holding a grant for a key nobody has. Pass its key to `pairWithOffer`. */
+ *  instead of leaving the host holding a grant for a key nobody has. Pass its key to `pairWithOffer`, or let
+ *  `pairWithOffer`'s `onPending` hand it over. A compact offer carries no host key: it needs `host`, the key the code
+ *  handshake authenticated (`onPending` passes it). For a version 1 offer, a different `host` is refused. */
 export function pendingGrant(scanned, o) {
     const offer = parseOffer(scanned);
+    let host = 'host' in offer ? offer.host : undefined;
+    if (o.host !== undefined) {
+        let given;
+        try {
+            given = unb64url(o.host);
+        }
+        catch {
+            throw new LinkError('wrong-host');
+        }
+        if (given.length !== 32 || (host !== undefined && host !== b64url(given)))
+            throw new LinkError('wrong-host');
+        host = b64url(given);
+    }
+    if (host === undefined)
+        throw new Error("A compact pairing code doesn't carry the computer's key: use pairWithOffer's onPending.");
     const me = o.key ?? keyPair();
-    return { v: 1, secretKey: b64url(me.secretKey), pendingUntil: offer.expires + 300_000, host: offer.host, hostName: offer.name, urls: offer.urls,
+    return { v: 1, secretKey: b64url(me.secretKey), pendingUntil: offer.expires + 300_000, host, hostName: offer.name, urls: offer.urls,
         device: { id: '', name: cleanName(o.name, 'Device'), role: offer.role ?? 'view' } };
 }
 /** A scanned QR (or opened pairing link) in, a grant out, once the person at the host says yes. `onWords` gets the
  *  two words to show while they decide. Tries each address in the code until one answers. A compact offer pairs
- *  like a typed code over the packed addresses: same single use, life, words and approval, no host key pinned. */
+ *  like a typed code over the packed addresses: same single use, life, words and approval; the host key it pins is
+ *  the one the code handshake authenticated, handed to `onPending` before the host learns this device. */
 export async function pairWithOffer(scanned, o) {
+    let taken = false; // the host has the code (it read the ticket or the code's first message): no other address can answer
+    const words = { ...o, onWords: (w) => { taken = true; o.onWords(w); } };
     if (scanned.indexOf(COMPACT_TAG) >= 0) {
         const compact = decodeCompactOffer(scanned);
         const me = o.key ?? keyPair();
+        const pin = o.onPending && ((key) => { taken = true; return o.onPending(pendingGrant(scanned, { name: o.name, key: me, host: b64url(key) })); });
         let last = new LinkError('unreachable');
         for (const url of compact.urls) {
             try {
-                const l = await dial(url, me, { psk: codeKey(compact.code) }, { t: 'code', name: o.name }, o);
+                const l = await dial(url, me, { psk: codeKey(compact.code), pin }, { t: 'code', name: o.name, ...(pin ? { pending: 1 } : {}) }, words);
                 l.close();
                 return granted(me, b64url(l.hostKey), url, compact.urls, l.ready);
             }
             catch (e) {
-                last = e instanceof LinkError ? e : new LinkError('unreachable');
-                if (last.code !== 'unreachable' && last.code !== 'timeout' && last.code !== 'wrong-host')
+                if (!(e instanceof LinkError))
+                    throw e; // the app's own onPending failure, as it said it
+                last = e;
+                if (taken || (last.code !== 'unreachable' && last.code !== 'timeout' && last.code !== 'wrong-host'))
                     break;
             }
         }
         throw last;
     }
-    const offer = parseOffer(scanned);
+    const offer = parseV1Offer(scanned);
     const me = o.key ?? keyPair();
+    if (o.onPending)
+        await within(o.timeoutMs ?? 8000, Promise.resolve(o.onPending(pendingGrant(scanned, { name: o.name, key: me }))));
     let last = new LinkError('unreachable');
     for (const url of offer.urls) {
         try {
-            const l = await dial(url, me, { key: unb64url(offer.host) }, { t: 'pair', ticket: offer.ticket, name: o.name }, o);
+            const l = await dial(url, me, { key: unb64url(offer.host) }, { t: 'pair', ticket: offer.ticket, name: o.name, ...(o.onPending ? { pending: 1 } : {}) }, words);
             l.close();
             return granted(me, offer.host, url, offer.urls, l.ready);
         }
         catch (e) {
             last = e instanceof LinkError ? e : new LinkError('unreachable');
-            if (last.code !== 'unreachable' && last.code !== 'timeout' && last.code !== 'wrong-host')
+            if (taken || (last.code !== 'unreachable' && last.code !== 'timeout' && last.code !== 'wrong-host'))
                 break;
         }
     }

package/dist/host.js

@@ -428,7 +428,7 @@ export class Host {
         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) => {
+        const pair = async (key, name, p, how, kept) => {
             const k = b64url(key);
             busy = true;
             clearTimeout(timer);
@@ -438,10 +438,15 @@ export class Host {
                 Promise.resolve().then(() => this.opts.confirm(req)).catch(() => false),
                 new Promise((r) => later(this.pairMs, () => r(false))),
             ]);
-            if (gone)
+            // 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;
-            if (!yes)
-                return refuse('declined');
+            }
             try {
                 const added = await this.grant(k, req.name, p, p.expires);
                 if (gone)
@@ -581,7 +586,7 @@ export class Host {
             }
             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');
+            void pair(hs.remoteKey, hello.name, code, 'code', hello.pending);
         };
         const inner = (d, m) => {
             if (m.t === 'req')
@@ -674,7 +679,7 @@ export class Host {
                             this.wrong();
                             return refuse('expired');
                         }
-                        return void pair(hs.remoteKey, m.name, p, 'scan');
+                        return void pair(hs.remoteKey, m.name, p, 'scan', m.pending);
                     }
                     end(4400, 'unexpected');
                 }

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 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, COMPACT_TAG } from './pairing.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';

package/dist/index.js

@@ -1,7 +1,7 @@
 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, COMPACT_TAG } from "./pairing.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";

package/dist/pairing.d.ts

@@ -18,14 +18,17 @@ export declare const cleanName: (name: unknown, fallback: string) => string;
  *  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;
+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 `parseOffer`; `now = 0` permits inspection only. */
+ * 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. */

package/dist/pairing.js

@@ -12,8 +12,13 @@ export function offerText(offer, base) {
     return base ? `${base}#${body}` : body;
 }
 /** 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 function parseOffer(scanned, now = Date.now()) {
+    return scanned.indexOf(COMPACT_TAG) >= 0 ? decodeCompactOffer(scanned, now) : parseV1Offer(scanned, now);
+}
+/** A version 1 offer only; `parseOffer` for anything else. */
+export function parseV1Offer(scanned, now = Date.now()) {
     const at = scanned.indexOf(TAG);
     let o;
     try {
@@ -63,7 +68,7 @@ function checksum(bytes) {
 /** 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 function encodeOffer(offer) {
-    const checked = parseOffer(offerText(offer), 0);
+    const checked = parseV1Offer(offerText(offer), 0);
     const body = b4a.from(JSON.stringify(checked));
     const bytes = new Uint8Array(1 + body.length + 4);
     bytes[0] = 1;
@@ -84,7 +89,7 @@ export function encodeOffer(offer) {
 }
 /** 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 `parseOffer`; `now = 0` permits inspection only. */
+ * Other typos fail the checksum. Expiry and addresses follow `parseV1Offer`; `now = 0` permits inspection only. */
 export function decodeOffer(text, now = Date.now()) {
     if (text.length > MAX_TYPED_OFFER)
         throw badOffer();
@@ -111,7 +116,7 @@ export function decodeOffer(text, now = Date.now()) {
     const b = Uint8Array.from(bytes);
     if (b.length < 6 || b[0] !== 1 || checksum(b.subarray(0, -4)) !== new DataView(b.buffer).getUint32(b.length - 4))
         throw badOffer();
-    return parseOffer(TAG + b64url(b.subarray(1, -4)), now);
+    return parseV1Offer(TAG + b64url(b.subarray(1, -4)), now);
 }
 // Migration read path only. The old direct envelope used seconds, a role byte and no name/lifetime.
 function decodeLegacyOffer(s, now) {
@@ -169,7 +174,7 @@ function decodeLegacyOffer(s, now) {
     }
     if (at !== end || urls.some((url) => !url.startsWith('ws:') || !wsUrl(url)))
         throw badOffer();
-    return parseOffer(offerText({
+    return parseV1Offer(offerText({
         v: 1, host: b64url(b.subarray(2, 34)), ticket: b64url(b.subarray(34, 50)),
         expires: view.getUint32(50) * 1000, name: 'your computer', role: b[1] ? 'control' : 'view', urls,
     }), now);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/pair",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Scan a code to pair a phone or browser with the home computer over one encrypted link (Noise IK over WebSocket).",
   "license": "Apache-2.0",
   "type": "module",