@byokit/pair 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+## 0.10.0 (2026-10-12)
+
+- DOCS: the "Checking reachability before pairing" section now shows both sides: setup self-checks its own advertised URLs with `check()` before printing the tick, and the phone re-checks the scanned offer before consent. The probe still spends nothing, so a checked offer pairs afterwards.
+- ADD: `ndjson(stream)` sends and receives whole JSON messages over a pair stream, one per `\n`-terminated line, through the existing credit window. Chunks split at any byte boundary reassemble before decoding, a line past `NDJSON_MAX_LINE` (1 MiB, configurable per stream) ends the stream with `line-too-long` on both ends, and a non-JSON line ends it with `failed`.
+- FIX: every wait in the link end-to-end suite is bounded: each test carries a one-minute deadline, so a request stalled past its reconnect window (twice it parked the whole full-suite run at 0% CPU until killed) fails by its test name instead of hanging every lane and release behind the shared test lock. The file still passes in about 10 s alone; nothing about the protocol changed.
+
+## 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

@@ -1,7 +1,7 @@
-<h1 align="center">@byokit/link</h1>
+<h1 align="center">@byokit/pair</h1>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/@byokit/link"><img alt="npm" src="https://img.shields.io/npm/v/@byokit/link?style=flat&label=npm" /></a>
+  <a href="https://www.npmjs.com/package/@byokit/pair"><img alt="npm" src="https://img.shields.io/npm/v/@byokit/pair?style=flat&label=npm" /></a>
   <a href="https://github.com/umeranjum17/byokit/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/umeranjum17/byokit/ci.yml?style=flat&branch=main" /></a>
   <a href="LICENSE"><img alt="Apache 2.0" src="https://img.shields.io/badge/license-Apache--2.0-666?style=flat" /></a>
   <img alt="Node | browsers | React Native" src="https://img.shields.io/badge/platform-Node%20%7C%20browsers%20%7C%20React%20Native-666?style=flat" />
@@ -12,8 +12,11 @@ One encrypted link between the two. The computer (the <strong>host</strong>) kee
 only its own key and a grant, and asks the host to do things. For apps that reach a person's own computer from their
 phone or browser.</p>
 
+This package was published as `@byokit/link` up to 0.8.x. `@byokit/link` still re-exports it unchanged through
+0.8.x and is removed in 0.9.0; new installs use `@byokit/pair`.
+
 <p align="center">
-  <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/docs/images/herdr-kit-host.png" width="420" alt="A terminal running npm start -- --herdr &quot;$(command -v herdr)&quot; --via lan --name 'Kitchen computer', showing a large pairing QR code, then: On the phone, scan this. If its page is already open there, type K3J8-CJZ7-SE4R instead. Codes last five minutes. Press Enter for new ones. Connecting to Herdr… Connected to Herdr. (stand-in Herdr)" />
+  <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/docs/images/herdr-kit-host.png" width="420" alt="A terminal running npm start -- --herdr &quot;$(command -v herdr)&quot; --via lan --name 'Kitchen computer', showing a large pairing QR code, then: On the phone, scan this, or open http://192.168.1.144:7310/ and type K3J8-CJZ7-SE4R. Codes last five minutes. Press Enter for new ones. Connecting to Herdr… Connected to Herdr. (stand-in Herdr)" />
   <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/examples/herdr-kit/docs/2-compare.png" width="240" alt="A phone page titled Agents, under Pair this phone: Check your computer shows these two words, then say yes there. The words are coast comet." />
 </p>
 <p align="center"><sub>Left: the host terminal of <a href="https://github.com/umeranjum17/byokit/tree/main/examples/herdr-kit">examples/herdr-kit</a> (<code>npm start -- --herdr "$(command -v herdr)" --via lan --name 'Kitchen computer'</code>, pictured against the kit's stand-in Herdr, <code>BYOKIT_EXAMPLE_FAKE=1</code>) showing the QR and the typed code. Right: the phone in the same example showing the two words to compare.</sub></p>
@@ -27,26 +30,26 @@ Host policy and streams are available; relay routing is in [`@byokit/relay`](../
 ## Install
 
 ```sh
-npm install @byokit/link
+npm install @byokit/pair
 ```
 
-[![npm](https://img.shields.io/npm/v/@byokit/link?style=flat&label=)](https://www.npmjs.com/package/@byokit/link) · [Latest release](https://github.com/umeranjum17/byokit/releases?q=link-v) · [All releases](https://github.com/umeranjum17/byokit/releases)
+[![npm](https://img.shields.io/npm/v/@byokit/pair?style=flat&label=)](https://www.npmjs.com/package/@byokit/pair) · [Latest release](https://github.com/umeranjum17/byokit/releases?q=pair-v) · [All releases](https://github.com/umeranjum17/byokit/releases)
 
 ## Quickstart
 
 ```sh
-npm install @byokit/link ws
+npm install @byokit/pair ws
 ```
 
 `ws` is only the WebSocket server for this example; any server works. A host and a device in one file, on loopback:
 
 ```ts
 import { WebSocketServer } from 'ws';
-import { DeviceLink, Host, keyPair, pairWithOffer } from '@byokit/link';
+import { DeviceLink, Host, keyPair, pairWithOffer } from '@byokit/pair';
 
 // The computer: it keeps the credentials and answers requests.
 const host = await Host.open({
-  keys: keyPair(),                       // keep it with hostKeyFile() from '@byokit/link/node' in a real app
+  keys: keyPair(),                       // keep it with hostKeyFile() from '@byokit/pair/node' in a real app
   name: 'Kitchen computer',
   confirm: ({ name, words }) => { console.log(`host: pair ${name}? it shows "${words}"`); return true; },
   handle: (req, device) => ({ echo: req.args, from: device.name }),
@@ -89,13 +92,13 @@ answer: { echo: { text: 'hi' }, from: 'Pixel 9' }
 | `LinkError`, `PublicLinkError`, `LINK_WORDS` | Failures with a plain `message` and a `code`; a handler error safe to show; the plain message for each failure code |
 | `secureDeviceStore`, `browserDeviceStore` | Where a device keeps its grant on a phone or in a browser |
 | `keyPair`, `keyPairFrom`, `hostId`, `b64url`, `unb64url`, `normalizeCode` | Keys, the host id, base64url and typed-code helpers |
-| `hostKeyFile`, `fileDeviceStore` (`@byokit/link/node`) | Node only: the host's key file, and a computer's device store |
+| `hostKeyFile`, `fileDeviceStore` (`@byokit/pair/node`) | Node only: the host's key file, and a computer's device store |
 
 ## Host
 
 ```ts
-import { Host } from '@byokit/link';
-import { hostKeyFile } from '@byokit/link/node';
+import { Host } from '@byokit/pair';
+import { hostKeyFile } from '@byokit/pair/node';
 
 const host = await Host.open({
   keys: hostKeyFile('./link-secret/host.key'), // made once in its own 0700 folder; or use your keychain
@@ -112,7 +115,7 @@ const { code } = host.code({ role: 'view' });     // or a code to type: "7KQ4-M2
 host.devices(); await host.revoke(id); host.broadcast(event);
 ```
 
-`hostKeyFile(path)` from `@byokit/link/node` wants a path in its own private (`0700`) folder; it refuses an
+`hostKeyFile(path)` from `@byokit/pair/node` wants a path in its own private (`0700`) folder; it refuses an
 existing folder with another mode rather than changing its permissions.
 
 More host policy, all optional:
@@ -127,6 +130,9 @@ More host policy, all optional:
   handlers with transactional effects can store it alongside the effect to avoid repeating work after a crash between
   the handler and `answers.put`.
 - `handshakes: { perMinute, perPeer }` limits new handshakes; pass `host.accept(ws, { peer: ip })` to count per source.
+- `onGrantRemoved(grant, why)` runs at the one boundary where a grant is durably gone — `revoked`, `expired` or
+  `changed` — so an app can delete its copy. Access is already withdrawn when it runs, a socket drop does not
+  trigger it, and a failing cleanup never restores access.
 
 `compactOffer` is the QR text: the same secret a typed code carries (same single use, life, words and
 approval) plus the addresses to try, packed binary, so a standard offer fits a QR version 4 or lower.
@@ -152,11 +158,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
@@ -184,7 +192,7 @@ old connections, and changed expiry reschedules access. A failed load rejects an
 A `GrantStore` may provide `subscribe(changed): unsubscribe`; the host reloads automatically on notification,
 reports reload failures through `onError`, and unsubscribes on `close()`.
 
-Node apps can use `fileGrantStore(path)` from `@byokit/link/node`. It touches the app's chosen file, temporary
+Node apps can use `fileGrantStore(path)` from `@byokit/pair/node`. It touches the app's chosen file, temporary
 files and a sibling `.lock` only, writes atomically at 0600 in a 0700 folder, rejects symlinks/nonprivate files on read, and polls
 for cross-process replace/remove (default 100 ms; second argument changes the interval). Cooperating writers
 use an exclusive lock and reject a stale loaded snapshot instead of overwriting an external revoke. Load again
@@ -205,7 +213,7 @@ The **handle** step authorizes the already-paired inviter, **offer** records the
 then **confirm** checks that metadata before approving the new peer:
 
 ```ts
-import { Host, keyPair, PublicLinkError } from '@byokit/link';
+import { Host, keyPair, PublicLinkError } from '@byokit/pair';
 
 // Supply the app's human approval UI.
 declare const ui: { ask(message: string): Promise<boolean> };
@@ -233,7 +241,7 @@ const host: Host = await Host.open({
 });
 ```
 
-Import `Host`, `keyPair` and `PublicLinkError` from `@byokit/link`; `ui.ask` is the app's approval UI. The app
+Import `Host`, `keyPair` and `PublicLinkError` from `@byokit/pair`; `ui.ask` is the app's approval UI. The app
 chooses metadata on the host, never from an untrusted invitee. This composition is delegated pairing:
 the approved control device requests a constrained invitation; a peer cannot widen its terms. Check the
 inviter's current grant, including expiry, in both `handle` and `confirm`. Apply capability scope in `allow`
@@ -245,7 +253,7 @@ long-lived or host-offline signed invitation.
 ## Device
 
 To keep several paired computers, use `secureDeviceStores(secureStore, prefix?)` or
-`browserDeviceStores(databaseName?)` from `@byokit/link`. Both offer `list()` (entry names), `load(name)`,
+`browserDeviceStores(databaseName?)` from `@byokit/pair`. Both offer `list()` (entry names), `load(name)`,
 `save(name, grant)`, `remove(name)`, and `store(name)` (the one-entry adapter for `DeviceLink`). Names use
 letters, digits, dots, underscores and dashes, up to 120 characters. A secure collection uses
 `<prefix>.index` and `<prefix>.grant.<name>`; existing single-entry stores stay independent. Calls sharing
@@ -255,7 +263,7 @@ The browser collection enumerates existing `browserDeviceStore` entries in its d
 non-extractable wrapping keys and forgotten-grant protection; removed tombstones stay out of `list()`.
 
 ```ts
-import { DeviceLink, secureDeviceStores, type DeviceGrant, type SecureStoreLike } from '@byokit/link';
+import { DeviceLink, secureDeviceStores, type DeviceGrant, type SecureStoreLike } from '@byokit/pair';
 
 // Supply the platform secure-storage module and a grant returned by pairing.
 declare const SecureStore: SecureStoreLike;
@@ -269,7 +277,7 @@ await computers.remove('kitchen');
 ```
 
 ```ts
-import { DeviceLink, pairWithOffer, pairWithCode } from '@byokit/link';
+import { DeviceLink, pairWithOffer, pairWithCode } from '@byokit/pair';
 
 const grant = await pairWithOffer(scanned, { name: 'Pixel 9', onWords: (w) => show(w) });
 // Or pairWithCode(url, typed, { name: 'Pixel 9', onWords: (w) => show(w) });
@@ -279,10 +287,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
@@ -308,7 +323,7 @@ One store per paired computer, each with `load()` for the next start:
 |---|---|---|
 | Phone | `secureDeviceStore(SecureStore, 'byokit.link.home')` with `expo-secure-store` | Keychain on iOS, Keystore on Android; the grant is about 300 bytes, one value. |
 | Browser or PWA | `browserDeviceStore('home')` | IndexedDB, sealed with AES-GCM by a non-extractable browser key. The stored record alone opens nothing, but scripts running on the same origin can still use the key to decrypt it; keep untrusted scripts off the page. |
-| Computer (Node, Electron's main process) | `fileDeviceStore(path, safeStorage?)` from `@byokit/link/node` | A 0600 file in a newly created 0700 folder (an existing folder keeps its permissions), sealed with Electron's `safeStorage` when given. Without `safeStorage`, the file contains the grant in plaintext. |
+| Computer (Node, Electron's main process) | `fileDeviceStore(path, safeStorage?)` from `@byokit/pair/node` | A 0600 file in a newly created 0700 folder (an existing folder keeps its permissions), sealed with Electron's `safeStorage` when given. Without `safeStorage`, the file contains the grant in plaintext. |
 
 ```ts
 const store = secureDeviceStore(SecureStore, 'byokit.link.home');
@@ -320,7 +335,7 @@ const link = new DeviceLink(grant, { store, onStatus });
 ### React Native
 
 Install a `crypto.getRandomValues` polyfill such as `react-native-get-random-values` (or use `expo-crypto`) and
-import it **before** `@byokit/link`. Metro resolves `sodium-universal` to `sodium-javascript` through its browser
+import it **before** `@byokit/pair`. Metro resolves `sodium-universal` to `sodium-javascript` through its browser
 field. The device uses the platform's WebSocket and needs no Node globals. See [`examples/expo`](../../examples/expo).
 
 ## Streams
@@ -348,6 +363,13 @@ s.end();
 View-only devices open only the streams `allow` permits (or `canView` when `allow` is absent). A host without `stream`
 tells devices so (`LinkError` `not-supported`), and so does a host older than streams.
 
+For whole JSON messages instead of bytes, `ndjson(stream)` sends one object per `\n`-terminated line and delivers
+each complete message in order: `const j = ndjson(s); await j.send({ text: 'hi' }); j.onMessage((m) => …)`.
+Messages split at any byte boundary arrive whole, including a multi-byte character split across two chunks, and a
+returned handler promise holds the sender back through the same credit window. A line past `NDJSON_MAX_LINE`
+(1 MiB, `ndjson(s, { maxLine })` changes it) ends the stream with `'line-too-long'` on both ends and is never
+delivered, so nothing is buffered without bound; a line that is not JSON ends it with `failed`.
+
 On a direct socket, stream bytes go as binary WebSocket messages (without base64 overhead); through a relay, whose
 host wrapper is text, the same frames go as base64 text. The host says which in `ready`; everything else stays text.
 
@@ -367,7 +389,7 @@ Frames are the same bytes on every path; a relay only routes them and cannot rea
 - The relay authenticates the host's socket and limits abuse its own way. Link routing needs no device id: the host
   checks devices itself on every handshake.
 
-`@byokit/link` does not include a relay server; use [`@byokit/relay`](../relay) for the standalone server,
+`@byokit/pair` does not include a relay server; use [`@byokit/relay`](../relay) for the standalone server,
 reconnecting host client and device code lookup.
 
 ## Migrating pre-kit phone pairings
@@ -406,10 +428,10 @@ share one key across machines. Muxr parity beyond this migration is tracked sepa
 ## Checking reachability before pairing
 
 ```ts
-import { check, parseOffer } from '@byokit/link';
+import { check, parseOffer } from '@byokit/pair';
 
-// Before asking the person to approve, the phone probes the offer's URLs (the host probes its own advertised
-// URLs the same way, as a self-check only). Results come back in input order.
+// Phone: before asking the person to approve, probe the scanned offer's URLs.
+// Results come back in input order.
 export async function precheck(scanned: string): Promise<void> {
   const { urls } = parseOffer(scanned);
   const results = await check(urls, { timeoutMs: 5000 });
@@ -419,6 +441,22 @@ export async function precheck(scanned: string): Promise<void> {
 }
 ```
 
+Setup runs the same probe on its own advertised URLs before printing the tick, so a dead
+address never becomes a QR. The phone runs it again after scanning, before consent:
+
+```ts
+import { check } from '@byokit/pair';
+
+// Setup: self-check the offer's URLs first; only print the tick when one answers.
+export async function selfcheck(urls: string[]): Promise<boolean> {
+  const results = await check(urls, { timeoutMs: 5000 });
+  for (const r of results) {
+    if (!r.ok) console.log(`${r.url}: ${r.message}`);
+  }
+  return results.some((r) => r.ok);
+}
+```
+
 Probed four at a time by default (`concurrency` changes that). The probe answers read-only: it sends no ticket,
 so a checked offer still pairs afterwards, and the reply carries nothing but the fact a link host is there. It
 works in Node, browsers and React Native, and through a relay with no relay change (devices speak bare frames
@@ -470,13 +508,13 @@ untrusted address, never a trusted machine key. A malicious lookup pointing at a
 fails the commitment check. QR offers and legacy `host.code()` remain compatible; callers of
 the latter do not get this additional machine-key pinning.
 
-Runnable loopback example (Node 22.18+, `npm install @byokit/link ws`; save as `pair.ts`, run
+Runnable loopback example (Node 22.18+, `npm install @byokit/pair ws`; save as `pair.ts`, run
 `node pair.ts`). In an app, show the code on the computer and let the phone type it:
 
 ```ts
 import { createInterface } from 'node:readline/promises';
 import { WebSocketServer } from 'ws';
-import { DeviceLink, Host, keyPair, pairWithCode } from '@byokit/link';
+import { DeviceLink, Host, keyPair, pairWithCode } from '@byokit/pair';
 
 const terminal = createInterface({ input: process.stdin, output: process.stdout });
 const host = await Host.open({

package/SECURITY.md

@@ -1,4 +1,4 @@
-# @byokit/link: threat model and review checklist
+# @byokit/pair: threat model and review checklist
 
 Muxr parity is tracked separately.
 
@@ -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.
@@ -132,7 +132,7 @@ A home computer (the **host**) holds AI sign-ins and other credentials. Phones,
       authenticates with it.
 - [x] The handshake limiter runs before any Diffie-Hellman.
 - [x] Nothing in the main entry reads or writes files, environment variables or other programs.
-      `@byokit/link/node` `hostKeyFile(path)` touches only that path: 0600 in 0700, atomic, never replaces a file it
+      `@byokit/pair/node` `hostKeyFile(path)` touches only that path: 0600 in 0700, atomic, never replaces a file it
       can't read, refuses symlinks.
 
 - [ ] Presence fires once on first/last sockets, including failed/successful unpair, reload, expiry and close.

package/dist/check.d.ts

@@ -28,7 +28,7 @@ export type CheckOptions = {
         onerror: unknown;
     };
 };
-/** Probe each URL for a link host, in input order. Only `unreachable` (nothing there), `timeout` (something there
- *  that never answered) and `wrong-host` (something else answered) can come back, each with its LINK_WORDS sentence;
- *  no new codes were needed. Never sends a ticket, so offers stay usable. */
+/** Probe each URL for a link host, in input order. Only `unreachable` (nothing there: same network or firewall),
+ *  `slow` (something there that never answered: wait and try again) and `wrong-host` (something else answered) can
+ *  come back, each with its LINK_WORDS sentence. Never sends a ticket, so offers stay usable. */
 export declare function check(urls: string[], o?: CheckOptions): Promise<CheckResult[]>;

package/dist/check.js

@@ -24,7 +24,7 @@ function probe(url, o, timeoutMs) {
             catch { }
             resolve(r);
         };
-        const timer = setTimeout(() => finish(fail(url, opened ? 'timeout' : 'unreachable')), timeoutMs);
+        const timer = setTimeout(() => finish(fail(url, opened ? 'slow' : 'unreachable')), timeoutMs);
         timer.unref?.();
         try {
             const WS = o.WebSocket ?? globalThis.WebSocket;
@@ -55,9 +55,9 @@ function probe(url, o, timeoutMs) {
         };
     });
 }
-/** Probe each URL for a link host, in input order. Only `unreachable` (nothing there), `timeout` (something there
- *  that never answered) and `wrong-host` (something else answered) can come back, each with its LINK_WORDS sentence;
- *  no new codes were needed. Never sends a ticket, so offers stay usable. */
+/** Probe each URL for a link host, in input order. Only `unreachable` (nothing there: same network or firewall),
+ *  `slow` (something there that never answered: wait and try again) and `wrong-host` (something else answered) can
+ *  come back, each with its LINK_WORDS sentence. Never sends a ticket, so offers stay usable. */
 export async function check(urls, o = {}) {
     const timeoutMs = o.timeoutMs ?? 8000;
     const out = new Array(urls.length);

package/dist/device.d.ts

@@ -41,7 +41,7 @@ export type Dial = {
 };
 /** Every way the link can fail, in words a person can act on. */
 export declare const LINK_WORDS: {
-    readonly unreachable: "Can't reach your computer. Check it's on and connected.";
+    readonly unreachable: "Can't reach your computer. Check the phone and computer are on the same network, and that no firewall is blocking the connection.";
     readonly 'wrong-host': "Something other than your computer answered, so this device didn't connect.";
     readonly 'wrong-code': "That code didn't match. Check it, or show a new one on your computer.";
     readonly expired: "That pairing code has run out. Show a new one on your computer.";
@@ -51,6 +51,7 @@ export declare const LINK_WORDS: {
     readonly removed: "This device was removed on your computer.";
     readonly 'view-only': "This device can watch but not make changes.";
     readonly timeout: "Your computer didn't answer in time.";
+    readonly slow: "Your computer is slow to answer. Wait a moment and try again.";
     readonly failed: "Your computer couldn't do that.";
     readonly busy: "Your computer is still catching up. Try again in a moment.";
     readonly stopped: "This link is stopped. Try connecting again.";
@@ -78,15 +79,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,11 +3,11 @@
 // 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 = {
-    unreachable: "Can't reach your computer. Check it's on and connected.",
+    unreachable: "Can't reach your computer. Check the phone and computer are on the same network, and that no firewall is blocking the connection.",
     'wrong-host': "Something other than your computer answered, so this device didn't connect.",
     'wrong-code': "That code didn't match. Check it, or show a new one on your computer.",
     expired: 'That pairing code has run out. Show a new one on your computer.',
@@ -17,6 +17,7 @@ export const LINK_WORDS = {
     removed: 'This device was removed on your computer.',
     'view-only': 'This device can watch but not make changes.',
     timeout: "Your computer didn't answer in time.",
+    slow: 'Your computer is slow to answer. Wait a moment and try again.',
     failed: "Your computer couldn't do that.",
     busy: 'Your computer is still catching up. Try again in a moment.',
     stopped: 'This link is stopped. Try connecting again.',
@@ -43,6 +44,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;
@@ -75,7 +80,8 @@ async function dial(url, me, host, hello, o, on = { message: () => { }, close: (
             }
             catch { }
         };
-        let timer = later(o.timeoutMs ?? 8000, () => fail(new LinkError('timeout')));
+        let opened = false;
+        let timer = later(o.timeoutMs ?? 8000, () => fail(new LinkError(opened ? 'slow' : 'unreachable')));
         try {
             ws = new WS(target);
             ws.binaryType = 'arraybuffer';
@@ -88,7 +94,12 @@ async function dial(url, me, host, hello, o, on = { message: () => { }, close: (
             ws.send(f); };
         const data = (s, d) => { for (const f of ch.sealData(s, d))
             ws.send(binary ? f : b64(f)); };
-        ws.onopen = () => ws.send(hs.write(mode === 'ik' ? { v: 1 } : {}));
+        ws.onopen = () => { opened = true; try {
+            ws.send(hs.write(mode === 'ik' ? { v: 1 } : {}));
+        }
+        catch {
+            fail(new LinkError('unreachable'));
+        } };
         ws.onerror = () => fail(new LinkError('unreachable'));
         // Before the handshake finishes nothing is authenticated, so these only choose what to say, never what to forget.
         ws.onclose = (e) => fail(new LinkError(ch ? 'unreachable' : e?.code === 4401 && mode === 'code' ? 'wrong-code' : e?.code === 4403 ? 'wrong-host' : 'unreachable'));
@@ -107,16 +118,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('slow')));
+                        }
+                    };
+                    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 +174,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 !== 'slow' && 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 !== 'slow' && 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,8 +1,8 @@
 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 { LinkStream, WINDOW } from './stream.ts';
+export { cleanName, decodeCompactOffer, decodeOffer, encodeCompactOffer, encodeOffer, normalizeCode, offerText, parseOffer, parseV1Offer, COMPACT_TAG } from './pairing.ts';
+export { LinkStream, NDJSON_LINE_TOO_LONG, NDJSON_MAX_LINE, WINDOW, ndjson, type NdjsonOptions, type NdjsonStream } 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';

package/dist/index.js

@@ -1,8 +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, COMPACT_TAG } from "./pairing.js";
-export { LinkStream, WINDOW } from "./stream.js";
+export { cleanName, decodeCompactOffer, decodeOffer, encodeCompactOffer, encodeOffer, normalizeCode, offerText, parseOffer, parseV1Offer, COMPACT_TAG } from "./pairing.js";
+export { LinkStream, NDJSON_LINE_TOO_LONG, NDJSON_MAX_LINE, WINDOW, ndjson } 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/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/dist/stream.d.ts

@@ -53,6 +53,29 @@ export declare class LinkStream {
     ended(error?: string): void;
     waitOpened(): Promise<LinkStream>;
 }
+/** The longest one JSON line `ndjson` buffers, in bytes (a line is its UTF-8 bytes up to `\n`). */
+export declare const NDJSON_MAX_LINE: number;
+/** The stream error an `ndjson` reader ends its stream with when a line runs past its cap. Both sides see it. */
+export declare const NDJSON_LINE_TOO_LONG = "line-too-long";
+export type NdjsonOptions = {
+    /** The longest one line buffered before the stream ends with `NDJSON_LINE_TOO_LONG`. Defaults to `NDJSON_MAX_LINE`. */
+    maxLine?: number;
+};
+export type NdjsonStream = {
+    /** The byte stream underneath, for `onEnd`, `end` and anything else not about JSON. */
+    readonly stream: LinkStream;
+    /** Sends one JSON message (`JSON.stringify` plus `\n`) through the stream's credit window. */
+    send(message: unknown): Promise<void>;
+    /** Each whole JSON message, in order. Returning a promise holds the sender back until it settles. */
+    onMessage(fn: (message: unknown) => void | Promise<void>): void;
+    /** Ends the stream both ways: after the sends already made, or at once with an error. */
+    end(error?: string): void;
+};
+/** Whole JSON messages over a byte `LinkStream`, one `\n`-terminated line each. Chunks split at any byte
+ *  boundary reassemble before decoding, so a multi-byte character split across two chunks still arrives whole.
+ *  A line past the cap ends the stream with `NDJSON_LINE_TOO_LONG` and is never delivered, so nothing is buffered
+ *  without bound; a line that is not JSON ends it with `failed` through the stream's usual handler-error path. */
+export declare function ndjson(stream: LinkStream, opts?: NdjsonOptions): NdjsonStream;
 /** One connection's streams. */
 export declare class Streams {
     private all;

package/dist/stream.js

@@ -178,6 +178,79 @@ export class LinkStream {
         return new Promise((resolve, reject) => { this.settle = { resolve, reject: (e) => reject(e) }; });
     }
 }
+/** The longest one JSON line `ndjson` buffers, in bytes (a line is its UTF-8 bytes up to `\n`). */
+export const NDJSON_MAX_LINE = 1024 * 1024;
+/** The stream error an `ndjson` reader ends its stream with when a line runs past its cap. Both sides see it. */
+export const NDJSON_LINE_TOO_LONG = 'line-too-long';
+/** Whole JSON messages over a byte `LinkStream`, one `\n`-terminated line each. Chunks split at any byte
+ *  boundary reassemble before decoding, so a multi-byte character split across two chunks still arrives whole.
+ *  A line past the cap ends the stream with `NDJSON_LINE_TOO_LONG` and is never delivered, so nothing is buffered
+ *  without bound; a line that is not JSON ends it with `failed` through the stream's usual handler-error path. */
+export function ndjson(stream, opts = {}) {
+    const maxLine = opts.maxLine ?? NDJSON_MAX_LINE;
+    if (!Number.isInteger(maxLine) || maxLine < 1)
+        throw new Error('bad ndjson maxLine');
+    const decode = new TextDecoder();
+    let parts = [];
+    let buffered = 0;
+    let failed = false;
+    const untilNewline = () => {
+        let at = 0;
+        for (const p of parts) {
+            const i = p.indexOf(10);
+            if (i !== -1)
+                return at + i;
+            at += p.byteLength;
+        }
+        return -1;
+    };
+    const take = (n) => {
+        const out = new Uint8Array(n);
+        for (let at = 0; at < n;) {
+            const p = parts[0];
+            const k = Math.min(p.byteLength, n - at);
+            out.set(p.subarray(0, k), at);
+            at += k;
+            parts = k === p.byteLength ? parts.slice(1) : [p.subarray(k), ...parts.slice(1)];
+        }
+        return out;
+    };
+    return {
+        stream,
+        send(message) {
+            const line = JSON.stringify(message);
+            if (line === undefined)
+                throw new Error('ndjson cannot send undefined');
+            return stream.write(`${line}\n`);
+        },
+        onMessage(fn) {
+            stream.onData = async (chunk) => {
+                if (failed)
+                    return;
+                parts.push(chunk);
+                buffered += chunk.byteLength;
+                for (;;) {
+                    const at = untilNewline();
+                    if (at === -1) {
+                        if (buffered > maxLine) {
+                            failed = true;
+                            parts = [];
+                            buffered = 0;
+                            stream.end(NDJSON_LINE_TOO_LONG);
+                        }
+                        return;
+                    }
+                    const line = decode.decode(take(at));
+                    take(1); // the '\n'
+                    buffered -= at + 1;
+                    if (line.length > 0)
+                        await fn(JSON.parse(line));
+                }
+            };
+        },
+        end(error) { stream.end(error); },
+    };
+}
 const count = (n, max) => {
     if (!Number.isInteger(n) || n < 0 || n > max)
         throw new Error('bad stream message');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/pair",
-  "version": "0.8.0",
+  "version": "0.10.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",