@agentproto/pair-client 0.2.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,137 @@
+# @agentproto/pair-client
+
+The browser side of agentproto E2E daemon pairing. A phone (or any browser
+tab, worker or service worker) scans the QR from `agentproto pair offer --qr`,
+pairs with the daemon through the rendezvous broker, and from then on reaches
+it with a plain WHATWG `fetch`: streamed bodies and SSE included, every
+request multiplexed over one end-to-end encrypted WebSocket. The broker only
+ever sees ciphertext.
+
+It speaks the same `pair/v1` handshake and `agentproto/tunnel/v1` frames as
+the Node CLI (`agentproto pair accept` / `pair exec`), so the daemon can't
+tell the two clients apart. It is browser-safe: no `node:` import, no
+`Buffer`/`process`, WebCrypto only. A test bundles it for the browser and runs
+a real pair + fetch in a realm that has only web globals.
+
+## Pair
+
+```ts
+import { inspectOffer, pairFromOffer, createIndexedDbCredentialStore } from "@agentproto/pair-client"
+
+const store = createIndexedDbCredentialStore()
+
+// No network: what the QR says.
+const info = await inspectOffer(location.href) // { fingerprint, rendezvousUrl, expiresAt }
+
+// Handshake (spends the one-time offer), then show the daemon to the user.
+const pending = await pairFromOffer(location.href, { store, clientName: "Jeremy's phone" })
+showConfirm(pending.daemon.name, pending.daemon.fingerprint)
+const credential = await pending.confirm() // stored; or pending.cancel()
+```
+
+**One origin per daemon.** `pair offer --qr` points at a per-daemon page by
+default, `https://{fp}.agentproto.cloud/pair` (`pairing.pairPage` or
+`--pair-page` change it). A page built for that must check that it's on its
+daemon's origin before pairing (AIP-59 §5.8):
+
+```ts
+import { expectedPairHost, inspectOffer, PAIR_WEB_URL_TEMPLATE_CLOUD } from "@agentproto/pair-client"
+
+const info = await inspectOffer(location.href)
+if (location.host !== expectedPairHost(PAIR_WEB_URL_TEMPLATE_CLOUD, info.fingerprint)) {
+  throw new Error("this pairing QR is for another daemon's page")
+}
+```
+
+`pairFromOffer` accepts both offer forms: the web link
+`https://<fingerprint>.agentproto.cloud/pair#v=2&rv=…` (the offer rides in the fragment,
+which is never sent to a server) and the plain `agentproto://pair?…` URL.
+
+The daemon records the pairing as soon as the handshake succeeds, the same as
+for `pair accept`. `cancel()` only drops it on this side; remove the daemon's
+record with `agentproto pair revoke`.
+
+## Connect and fetch
+
+```ts
+import { connect } from "@agentproto/pair-client"
+
+const client = connect(credential, { store })
+client.onStateChange(({ state, error }) => render(state, error?.message))
+// state: "connecting" | "open" | "offline" | "revoked" | "outdated" | "closed"
+
+const res = await client.fetch("/sessions")          // a real Response
+const events = await client.fetch("/events", { signal }) // res.body streams chunk by chunk
+```
+
+- **Multiplexing:** any number of concurrent requests share one channel.
+- **Streaming:** `http_response_head` resolves the `Response`. The body is a
+  `ReadableStream` fed by each `http_response_chunk` as it arrives, so SSE works.
+- **Abort:** aborting the signal, or cancelling the body, sends `http_cancel` and
+  the daemon stops its upstream request.
+- **Reconnect:** jittered exponential backoff, capped (500 ms → 30 s by
+  default). In-flight requests fail with `TunnelClientError{code:"disconnected"}`.
+  New requests wait for the reconnect, or fail with `offline` after
+  `requestWaitMs`. A ping/pong keepalive catches half-open sockets.
+- **Revocation:** after `agentproto pair revoke` the daemon answers this
+  pairing with an authenticated `pairing_revoked` frame inside the E2E channel.
+  The client goes to `revoked`, stops retrying, and every call rejects with
+  `TunnelClientError{code:"revoked"}`: "this device was unpaired from
+  &lt;daemon&gt;; scan a new pairing QR". The broker can't forge that signal.
+
+- **Protocol:** pair/v2. Each connection derives a *route* token and an *auth*
+  token (from the offer secret, or from the pair root and the day). Only the
+  route goes on the broker URL; the auth is sealed into the hello. A v1 offer,
+  or a credential stored before v2, gives `TunnelClientError{code:
+  "protocol_outdated"}` (state `outdated`) and is never dialed: upgrade the
+  daemon and scan a new QR.
+
+The daemon keeps one standing channel per epoch slot for each pairing, so
+share one `TunnelClient` per credential. Don't connect twice.
+
+## In a service worker
+
+The package runs in a service worker: `WebSocket`, `crypto.subtle`,
+`indexedDB`, `fetch` types and streams are all there. Keep one client per
+credential at module scope and use it for every `fetch` event:
+
+```ts
+import { connect, createIndexedDbCredentialStore } from "@agentproto/pair-client"
+
+const store = createIndexedDbCredentialStore()
+const clients = new Map<string, ReturnType<typeof connect>>()
+
+async function clientFor(id: string) {
+  let c = clients.get(id)
+  if (!c || c.state === "closed") {
+    const cred = await store.get(id)
+    if (!cred) throw new Error("not paired")
+    const prefix = `/d/${id}`
+    c = connect(cred, { store, mapPath: url => url.pathname.slice(prefix.length) + url.search })
+    clients.set(id, c)
+  }
+  return c
+}
+
+self.addEventListener("fetch", (event: FetchEvent) => {
+  const m = new URL(event.request.url).pathname.match(/^\/d\/([0-9a-f]{32})\//)
+  if (!m) return
+  event.respondWith(clientFor(m[1]!).then(c => c.fetch(event.request)))
+})
+```
+
+The browser may stop an idle service worker. The next `fetch` event then
+builds a new client, which reconnects in about one round trip.
+
+## Credential storage
+
+`CredentialStore` is `{ get, put, delete, list }`:
+
+- `createIndexedDbCredentialStore()` works in a window or a worker, scoped to
+  the origin.
+- `createMemoryCredentialStore()` is for tests.
+
+Nothing is written to localStorage. The pair root is imported as a
+**non-extractable** WebCrypto HKDF `CryptoKey`, and IndexedDB stores the key
+object as-is. Script can derive the day's routing token with it but can't
+read the secret back out.

package/dist/index.d.ts

@@ -0,0 +1,307 @@
+import { HelloFrame } from '@agentproto/acp/tunnel/browser';
+export { DEFAULT_PAIR_PAGE, PAIR_PAGE_FP_PLACEHOLDER, PAIR_WEB_URL, PAIR_WEB_URL_TEMPLATE_CLOUD, encodeOfferWebUrl, expectedPairHost, resolvePairPageUrl } from '@agentproto/secrets/pairing/browser';
+
+/**
+ * One E2E channel to the daemon through the rendezvous: dial the broker, run
+ * the `pair/v1` client handshake, and read the daemon's greeting.
+ *
+ * This is the Node client's `acceptOffer` / `openPairChannel` sequence
+ * (`packages/cli/src/util/pair-transport.ts`) — same upgrade URL, same pair/v2
+ * hello (static keys pinned, the client name, and the AUTH token sealed to the
+ * daemon's key), same verification — built only from the browser-safe
+ * entries, so the daemon can't tell the two clients apart. The ROUTE token is
+ * the only thing on the broker URL; the auth token never leaves the sealed
+ * hello.
+ */
+
+/** The tunnel `error` code the daemon answers a revoked pairing with
+ *  (`PAIRING_REVOKED_CODE` in `@agentproto/runtime`'s pairing registry). */
+declare const PAIRING_REVOKED_CODE = "pairing_revoked";
+/** A WHATWG `WebSocket` constructor (the global one by default). */
+type WebSocketConstructor = new (url: string) => WebSocket;
+interface ChannelTimeouts {
+    /** Rendezvous dial ceiling. Default 15s (as the CLI). */
+    dialTimeoutMs?: number;
+    /** Handshake ceiling. Default 15s (as the CLI). */
+    handshakeTimeoutMs?: number;
+    /** How long to wait for the daemon's first tunnel frame. Default 10s. */
+    greetingTimeoutMs?: number;
+}
+
+/**
+ * The stored pairing credential and where it lives.
+ *
+ * `PairCredential` carries what the Node CLI persists per pairing
+ * (`~/.agentproto/pair-credentials.json`, `ClientPairing` in
+ * `packages/cli/src/util/client-pairings.ts`) — the pinned daemon keys, the
+ * rendezvous URL, the pair root, timestamps — so a reconnect is byte-for-byte
+ * the one the CLI makes. Two differences, both client-local:
+ *
+ *   - `pairRoot` is normally a **non-extractable** WebCrypto HKDF `CryptoKey`
+ *     (`importPairRootKey`): script can derive the epoch routing tokens with
+ *     it but can't read the secret back out. IndexedDB stores it as-is
+ *     (structured clone). A base64 string is accepted too (e.g. a credential
+ *     imported from the CLI's file).
+ *   - The CLI keeps one `name` that is both the user's label and the handshake
+ *     `clientName`; here `name` is the daemon's display name and `clientName`
+ *     the label this device announced to the daemon (what `pair ls` shows).
+ *
+ * No localStorage anywhere: `createIndexedDbCredentialStore` for browsers and
+ * service workers, `createMemoryCredentialStore` for tests.
+ */
+interface PairCredential {
+    /** Pairing protocol the credential was made under (`PAIR_VERSION`, 2). A
+     *  credential without it predates pair/v2: `connect` refuses it with
+     *  `protocol_outdated` instead of dialing (the daemon would never serve it). */
+    protocol?: number;
+    /** Store key: the daemon fingerprint (one credential per daemon, as the CLI
+     *  keys its pairings). */
+    id: string;
+    /** Daemon identity fingerprint (32 hex): the pin. */
+    fingerprint: string;
+    /** Daemon display name: its tunnel `hello` label, else its host name, else
+     *  the fingerprint. */
+    name: string;
+    /** The label this device sent in the handshake (the daemon's `pair ls` name). */
+    clientName: string;
+    /** Daemon static X25519 public key (base64 SPKI DER), pinned. */
+    daemonX25519Pub: string;
+    /** Daemon static Ed25519 public key (base64 SPKI DER), pinned: verifies the
+     *  daemon's transcript signature on every (re)connect. */
+    daemonEd25519Pub: string;
+    /** Rendezvous endpoint to reconnect through. */
+    rendezvousUrl: string;
+    /** Long-term shared secret the epoch routing tokens derive from: a
+     *  non-extractable HKDF `CryptoKey`, or base64. */
+    pairRoot: CryptoKey | string;
+    /** ISO-8601 when this pairing was made. */
+    createdAt: string;
+    /** ISO-8601 of the most recent (re)connect. */
+    lastSeen: string;
+}
+interface CredentialStore {
+    get(id: string): Promise<PairCredential | undefined>;
+    /** Insert or replace (keyed by `id`). */
+    put(credential: PairCredential): Promise<void>;
+    /** Returns whether something was removed. */
+    delete(id: string): Promise<boolean>;
+    list(): Promise<PairCredential[]>;
+}
+/** In-memory store (tests, or a page that must not persist). */
+declare function createMemoryCredentialStore(initial?: PairCredential[]): CredentialStore;
+interface IndexedDbCredentialStoreOptions {
+    /** Database name. Default `agentproto-pair`. */
+    dbName?: string;
+    /** Object store name. Default `credentials`. */
+    storeName?: string;
+    /** The IndexedDB factory. Default `globalThis.indexedDB` (window or worker). */
+    indexedDB?: IDBFactory;
+}
+/**
+ * IndexedDB-backed store. Works in a window and in a service worker (both
+ * expose `indexedDB`); credentials are scoped to the origin like all IndexedDB
+ * data. The `CryptoKey` pair root is stored by structured clone, so it stays
+ * non-extractable at rest and after reload.
+ */
+declare function createIndexedDbCredentialStore(opts?: IndexedDbCredentialStoreOptions): CredentialStore;
+
+/**
+ * The one error type this package throws, with a stable machine code so a UI
+ * can branch on it (e.g. show "scan a new pairing QR" for `revoked`).
+ */
+type TunnelClientErrorCode = 
+/** The daemon told us (authenticated, inside the E2E channel) that this
+ *  pairing was revoked. Terminal: pair again from a new offer. */
+"revoked"
+/** The offer or stored credential predates pairing protocol v2 (or the
+ *  daemon says so). Terminal: upgrade agentproto and pair again. */
+ | "protocol_outdated"
+/** The daemon could not be reached (rendezvous dial, handshake or greeting
+ *  failed, or no connection came up within the wait). Retried with backoff. */
+ | "offline"
+/** The live connection dropped while this request was in flight. */
+ | "disconnected"
+/** `client.close()` was called. */
+ | "closed"
+/** The offer URL is malformed or expired. */
+ | "invalid_offer"
+/** The pairing handshake over the offer failed (bad daemon signature, spent
+ *  offer, fingerprint mismatch, timeout…). */
+ | "pairing_failed"
+/** `confirm()` after `cancel()` (or a second `confirm()`). */
+ | "cancelled"
+/** The daemon's upstream failed mid-stream (surfaced on the body stream). */
+ | "stream_error";
+declare class TunnelClientError extends Error {
+    readonly code: TunnelClientErrorCode;
+    constructor(code: TunnelClientErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+
+/**
+ * `connect(credential)` — a long-lived, self-healing tunnel to a paired
+ * daemon, with a WHATWG `fetch` on top.
+ *
+ * Connection: the CLI's `openPairChannel` sequence (epoch routing token for
+ * today, then yesterday's to bridge clock skew; a fresh handshake each time),
+ * kept up with jittered, capped exponential backoff. A live channel is watched
+ * with ping/pong so a half-open socket is noticed.
+ *
+ * State (for a UI): `connecting` → `open`; on failure or drop → `offline`
+ * (while waiting to retry) → `connecting` …; `revoked`, `outdated` and
+ * `closed` are terminal. `revoked` is only ever entered on the daemon's
+ * authenticated `pairing_revoked` frame — never on anything the broker could
+ * fake — and stops all retries. `outdated` means the credential predates
+ * pair/v2 (it is never dialed) or the daemon said so, authenticated, the same
+ * way.
+ *
+ * Tokens (pair/v2): each attempt derives the epoch ROUTE — the only value on
+ * the broker URL — and the epoch AUTH, which is sealed into the hello and
+ * never leaves it.
+ *
+ * Requests: `http_request` frames multiplexed over the one channel by `reqId`.
+ * The response resolves at the daemon's `http_response` (buffered) or
+ * `http_response_head` (streamed: SSE / NDJSON), whose body is then a
+ * `ReadableStream` fed chunk by chunk as `http_response_chunk` frames arrive.
+ * Aborting (the request's signal, or cancelling the body) sends
+ * `http_cancel`. In-flight requests fail with `disconnected` when the channel
+ * drops; new ones wait for the (re)connection, up to `requestWaitMs`.
+ */
+
+type ConnectionState = "connecting" | "open" | "offline" | "revoked" | "outdated" | "closed";
+interface ConnectOptions extends ChannelTimeouts {
+    /** WebSocket constructor. Default: the global `WebSocket`. */
+    WebSocket?: WebSocketConstructor;
+    /** When set, `lastSeen` is refreshed there after each (re)connect
+     *  (best-effort, as the CLI does). */
+    store?: CredentialStore;
+    /** First retry delay. Default 500ms. */
+    reconnectMinMs?: number;
+    /** Retry delay ceiling. Default 30s. */
+    reconnectMaxMs?: number;
+    /** How long a request waits for a connection before failing `offline`.
+     *  Default 20s. */
+    requestWaitMs?: number;
+    /** Ping interval on a live channel. Default 25s; `0` disables. */
+    keepAliveMs?: number;
+    /** A ping unanswered this long drops the channel (and reconnects).
+     *  Default 10s. */
+    pongTimeoutMs?: number;
+    /** Map a request URL to the daemon path (path + query, must start with `/`).
+     *  Default: `url.pathname + url.search`. A service worker uses this to strip
+     *  its scope prefix. */
+    mapPath?: (url: URL) => string;
+    /** Clock (ms). Default `Date.now`. */
+    now?: () => number;
+    /** Random source for backoff jitter, in [0, 1). Default `Math.random`. */
+    random?: () => number;
+}
+interface StateChange {
+    state: ConnectionState;
+    /** Why we're `offline` / `revoked` / `outdated` / `closed` (the last failure). */
+    error?: TunnelClientError;
+}
+interface TunnelClient {
+    /** The pairing this client serves. */
+    readonly credential: PairCredential;
+    readonly state: ConnectionState;
+    /** The daemon's hello on the current (or last) channel. */
+    readonly hello: HelloFrame | null;
+    /** The most recent connection failure, if any. */
+    readonly lastError: TunnelClientError | null;
+    /** Subscribe to state changes. Returns an unsubscribe function. */
+    onStateChange(listener: (change: StateChange) => void): () => void;
+    /** Resolves once connected; rejects with `revoked` / `protocol_outdated` /
+     *  `closed`, or `offline`
+     *  when no connection came up within `requestWaitMs`. */
+    ready(): Promise<void>;
+    /** A WHATWG `fetch` through the daemon. Relative URLs are fine: only the
+     *  path + query (see `mapPath`) is sent. Rejects with `TunnelClientError`
+     *  (`offline` / `disconnected` / `revoked` / `protocol_outdated` / `closed`)
+     *  where `fetch` would
+     *  reject with a network error, or with the signal's reason on abort. */
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+    /** Skip the current backoff wait and retry now (e.g. on `online`). */
+    reconnect(): void;
+    /** Close the channel and stop reconnecting. Pending requests fail `closed`.
+     *  The state becomes `closed`, except that a terminal `revoked` / `outdated`
+     *  is kept (with its `lastError`). */
+    close(): void;
+}
+/**
+ * Connect to a paired daemon. Returns immediately; the client connects in the
+ * background (watch `state` / `onStateChange`, or `await client.ready()`).
+ * One client per credential: the daemon keeps one standing channel per epoch
+ * slot, so share this instance rather than connecting twice.
+ */
+declare function connect(credential: PairCredential, opts?: ConnectOptions): TunnelClient;
+
+/**
+ * First contact: turn an offer (the `pair offer --qr` link, or the plain
+ * `agentproto://pair?…` URL) into a stored credential.
+ *
+ * Two steps so a UI can ask the human before persisting anything:
+ *
+ *   1. `inspectOffer(url)` — no network: parse + validate the offer and return
+ *      the daemon fingerprint it pins and when it expires.
+ *   2. `pairFromOffer(url)` — run the handshake through the offer's rendezvous
+ *      (this spends the one-time offer; the daemon records the pairing now,
+ *      exactly as for `agentproto pair accept`), read the daemon's hello for its
+ *      name, close the channel, and hand back `{ daemon, confirm, cancel }`.
+ *      `confirm()` builds the credential (pair root as a non-extractable
+ *      `CryptoKey`) and stores it; `cancel()` drops it. Cancelling does not undo
+ *      the daemon's record — remove that with `agentproto pair revoke`.
+ */
+
+interface OfferInfo {
+    /** Daemon identity fingerprint (32 hex) the offer pins — show it to the user. */
+    fingerprint: string;
+    /** The rendezvous the handshake will go through. */
+    rendezvousUrl: string;
+    /** Offer expiry. */
+    expiresAt: Date;
+}
+/** Parse and validate an offer without touching the network. Accepts the web
+ *  form (`https://…/pair#…`) and the `agentproto://pair?…` form. */
+declare function inspectOffer(offerUrl: string, opts?: {
+    now?: number;
+}): Promise<OfferInfo>;
+interface PairFromOfferOptions extends ChannelTimeouts {
+    /** How this device is listed on the daemon (`agentproto pair ls`).
+     *  Default `browser@<location.host>` (or `browser`). */
+    clientName?: string;
+    /** Where `confirm()` stores the credential. Omit to only get it back. */
+    store?: CredentialStore;
+    /** WebSocket constructor. Default: the global `WebSocket`. */
+    WebSocket?: WebSocketConstructor;
+    /** Clock (ms). Default `Date.now`. */
+    now?: () => number;
+}
+interface PairedDaemon {
+    /** Daemon identity fingerprint — verified by the handshake. */
+    fingerprint: string;
+    /** Display name (hello label, else host name, else the fingerprint). */
+    name: string;
+    /** The daemon's `serve --label`, if any. */
+    label?: string;
+    /** `<os>/<hostname>` from the daemon's hello (diagnostic). */
+    platform?: string;
+    rendezvousUrl: string;
+}
+interface PendingPairing {
+    daemon: PairedDaemon;
+    /** Build the credential and (with `opts.store`) persist it. */
+    confirm(): Promise<PairCredential>;
+    /** Discard the pairing on this side. */
+    cancel(): void;
+}
+/**
+ * Run the `pair/v1` handshake for an offer. See the module doc for the
+ * two-step flow. Throws `TunnelClientError` — `invalid_offer` for a
+ * malformed/expired offer, `pairing_failed` for everything the handshake can
+ * hit (unreachable daemon, spent offer, bad signature, fingerprint mismatch).
+ */
+declare function pairFromOffer(offerUrl: string, opts?: PairFromOfferOptions): Promise<PendingPairing>;
+
+export { type ChannelTimeouts, type ConnectOptions, type ConnectionState, type CredentialStore, type IndexedDbCredentialStoreOptions, type OfferInfo, PAIRING_REVOKED_CODE, type PairCredential, type PairFromOfferOptions, type PairedDaemon, type PendingPairing, type StateChange, type TunnelClient, TunnelClientError, type TunnelClientErrorCode, type WebSocketConstructor, connect, createIndexedDbCredentialStore, createMemoryCredentialStore, inspectOffer, pairFromOffer };