@agentproto/secrets 0.2.6 → 1.0.0

package/dist/webcrypto-BU57p0_g.d.ts

@@ -0,0 +1,652 @@
+import { C as CryptoProvider } from './types-B2ZfEhsU.js';
+import { D as DaemonIdentity } from './core-D8zVNPDb.js';
+
+/**
+ * @agentproto/secrets/pairing — the `pair/v2` session handshake
+ * (design: DESIGN §4).
+ *
+ * A Noise-flavoured, two-message handshake that lets a client and a daemon —
+ * connected only through an untrusted rendezvous that byte-splices their
+ * sockets — derive per-direction AEAD keys such that the rendezvous can neither
+ * read nor forge the session:
+ *
+ * ```
+ *   client → daemon:  e_pub                       // ephemeral X25519
+ *                     ct₀ = Seal(to = daemon_x25519,
+ *                            {clientPub: e_pub, clientName, auth})
+ *   daemon → client:  d_e_pub, sig = Ed25519(daemon_ed25519,
+ *                            transcript = sha256(e_pub ‖ ct₀ ‖ d_e_pub))
+ *   both:             K  = HKDF-SHA256(ECDH(e, d_e) ‖ ECDH(e, daemon_x25519),
+ *                            salt = transcript, info = "agentproto/pair/v2")
+ *                     → K_c2d ‖ K_d2c  (two AES-256-GCM keys)
+ * ```
+ *
+ * Why this shape:
+ *   - The client learned the daemon's static public keys out-of-band (the offer
+ *     URL / QR). Verifying `sig` against the offer's Ed25519 key proves the peer
+ *     is the daemon the human scanned, not a rendezvous impersonating it — MITM
+ *     protection without a CA.
+ *   - The daemon proves the client is authorised by opening `ct₀` (only the
+ *     daemon's X25519 private key can) and checking the sealed `auth` token in
+ *     constant time. `auth` is derived from the pairing secret under a label
+ *     distinct from the broker ROUTE token (./derive.ts), so the one value the
+ *     broker sees in clear — the route on the upgrade URL — never authenticates.
+ *     pair/v1 sealed the route itself as the proof, which let a broker that
+ *     knew the route (all of them) seal its own hello and pair; v1 is retired
+ *     (see `respondToLegacyHandshake`).
+ *   - `sig` covers the whole transcript and the transcript salts the key
+ *     schedule, so any tampering with `e_pub`, `ct₀`, or `d_e_pub` in flight
+ *     makes either the signature or the derived keys disagree — the session
+ *     fails closed, never continuing with attacker-chosen material.
+ *
+ * The primitives come from a `CryptoProvider` (node:crypto or WebCrypto), so this
+ * one implementation runs in Node and in a browser; every entry point that does
+ * crypto is async and takes an optional trailing `crypto` argument.
+ *
+ * This module is deliberately **transport-agnostic**: it produces and consumes
+ * plain messages (`encode*`/`decode*` give byte arrays). The code that pumps
+ * those bytes over a `FrameSink` lives in `@agentproto/acp/tunnel`, which stays
+ * free of any dependency on this package — it receives only the derived keys.
+ * All crypto stays here so the acp layer never touches key material beyond the
+ * two symmetric session keys.
+ */
+
+/** Wire version of the handshake. Bumped if the message shape or key schedule
+ *  changes; both sides refuse a version they don't recognise. v2: the sealed
+ *  hello carries a dedicated auth token, never the broker route (./derive.ts). */
+declare const PAIR_VERSION: 2;
+/** The retired pair/v1 wire version. Recognised only to answer it with a
+ *  re-pair notice (`respondToLegacyHandshake`); never served. */
+declare const LEGACY_PAIR_VERSION: 1;
+/** What a peer is told when it speaks the retired protocol: pairings made
+ *  under pair/v1 can't be upgraded in place, so the fix is a fresh pairing. */
+declare const PAIRING_PROTOCOL_OUTDATED_MESSAGE: string;
+/** Stable, machine-readable failure codes. Every rejection maps to one of
+ *  these so callers (and tests) branch on a code, not a message string. */
+type PairingErrorCode = "malformed_hello" | "malformed_reply" | "invalid_key" | "unseal_failed" | "ephemeral_mismatch" | "offer_rejected" | "bad_signature" | "malformed_offer" | "offer_expired" | "pairing_protocol_outdated";
+/** Raised for every handshake failure. Never carries key material or
+ *  plaintext; the `code` is the contract, the message is for humans. */
+declare class PairingError extends Error {
+    readonly code: PairingErrorCode;
+    constructor(code: PairingErrorCode, message: string);
+}
+/** Client → daemon. `ePub` is the client ephemeral X25519 public key (base64
+ *  SPKI DER); `ct0` is the sealed hello payload (a `seal()` envelope string). */
+interface PairingHello {
+    v: typeof PAIR_VERSION;
+    ePub: string;
+    ct0: string;
+}
+/** Daemon → client. `dePub` is the daemon ephemeral X25519 public key (base64
+ *  SPKI DER); `sig` is the Ed25519 transcript signature (base64). */
+interface PairingReply {
+    v: typeof PAIR_VERSION;
+    dePub: string;
+    sig: string;
+}
+/**
+ * The result of a completed handshake, on either side. `sendKey`/`recvKey` are
+ * already role-adjusted (a client's `sendKey` is a daemon's `recvKey`), so the
+ * consumer — `wrapE2E` — never has to know which side it is.
+ */
+interface PairingSession {
+    /** AES-256-GCM key for frames THIS side sends. 32 bytes. */
+    sendKey: Uint8Array;
+    /** AES-256-GCM key for frames THIS side receives. 32 bytes. */
+    recvKey: Uint8Array;
+    /** Fingerprint of the peer's static identity (the daemon's X25519 key on the
+     *  client side; in P1, the client's ephemeral key on the daemon side, since
+     *  clients have no persisted identity until P2's pairings store). */
+    peerFingerprint: string;
+    /** `sha256(e_pub ‖ ct₀ ‖ d_e_pub)` — the exact transcript both sides bound
+     *  to. A later phase channel-binds reconnect tokens to this. */
+    transcriptHash: Uint8Array;
+    /**
+     * The human-facing client label carried in the sealed hello. On the daemon
+     * side this is the name the peer chose (surfaced in `pairings.json` and on
+     * `pair accept`); on the client side it echoes the name this side supplied.
+     * Optional so pre-P2 callers constructing a session literal are unaffected —
+     * P2 (pairing-registry) reads it to name a persisted pairing without opening
+     * the seal a second time. Populated by both handshake entry points below.
+     */
+    clientName?: string;
+}
+/** Everything the client learned from the offer URL, plus its chosen name. */
+interface ClientHandshakeParams {
+    /** Daemon static X25519 public key (base64 SPKI DER) — the seal recipient
+     *  and one ECDH input. From the offer's `pk`. */
+    daemonX25519Pub: string;
+    /** Daemon static Ed25519 public key (base64 SPKI DER) — verifies `sig`.
+     *  From the offer's `sk`. */
+    daemonEd25519Pub: string;
+    /** Auth token sealed into the hello: `deriveOfferTokens(offer.secret).auth`
+     *  on first contact, `deriveEpochAuthToken(pairRoot, epoch)` on reconnect.
+     *  NEVER the route token the broker sees. */
+    authToken: string;
+    /** Human-facing client label the daemon displays on accept. */
+    clientName: string;
+}
+/** A started client handshake: send `hello`, then feed the daemon's reply to
+ *  `complete` to derive the session. */
+interface StartedClientHandshake {
+    hello: PairingHello;
+    /** Verify the daemon reply and derive the session. Rejects with
+     *  `PairingError` on a bad signature, malformed reply, or invalid key —
+     *  never resolves partial state. */
+    complete(reply: PairingReply): Promise<PairingSession>;
+}
+/**
+ * Begin a client handshake. Generates the client ephemeral keypair, seals the
+ * hello payload to the daemon's static key, and resolves to the `hello` to send
+ * plus a `complete` to run once the daemon replies.
+ *
+ * `crypto` selects the primitive implementation (default: WebCrypto here,
+ * `node:crypto` through the `@agentproto/secrets/pairing` Node entry). The
+ * provider is captured for `complete` as well.
+ */
+declare function startClientHandshake(params: ClientHandshakeParams, crypto?: CryptoProvider): Promise<StartedClientHandshake>;
+/** What the daemon brings to the handshake: its identity, and a predicate that
+ *  validates (and, for an offer, spends) the sealed auth token. */
+interface DaemonHandshakeParams {
+    identity: DaemonIdentity;
+    /**
+     * Validate the presented auth token (constant time). Returning false
+     * rejects the handshake with `offer_rejected`. The daemon owns single-use +
+     * expiry policy here so this module never needs to know about the offer
+     * store — a stale, spent, or wrong token simply returns false. May be async.
+     */
+    verifyAuthToken: (token: string) => boolean | Promise<boolean>;
+}
+/** A completed daemon handshake: send `reply`, keep `session`. */
+interface DaemonHandshakeResult {
+    reply: PairingReply;
+    session: PairingSession;
+}
+/**
+ * Respond to a client hello. Opens the sealed payload with the daemon's X25519
+ * private key, checks the ephemeral-key binding and the auth token, signs the
+ * transcript, and derives the session. Rejects with `PairingError` on any
+ * failure — a tampered `ct₀`, a swapped `ePub`, a rejected token — before
+ * producing any reply, so a rejected client learns nothing and gets no session.
+ */
+declare function respondToHandshake(hello: PairingHello, params: DaemonHandshakeParams, crypto?: CryptoProvider): Promise<DaemonHandshakeResult>;
+/**
+ * Answer a retired pair/v1 hello so its client can be TOLD to re-pair.
+ *
+ * An unmodified v1 client only surfaces what arrives inside a completed v1
+ * channel — anything short of that (a closed socket, a WS close reason, which
+ * its transport drops) reads as a timeout. So the daemon completes the v1 key
+ * schedule (`agentproto/pair/v1`) and hands back the reply + keys; the caller
+ * sends ONLY the outdated notice over them and closes.
+ *
+ * Deliberately performs NO authorisation: the v1 token proves nothing (it's
+ * the broker-visible route), so it isn't even read. The result must never be
+ * served — it is a one-way notice channel, and a party that gets one (the
+ * broker included) gains nothing but that notice. Rejects with `PairingError`
+ * for anything that isn't a well-formed v1 hello sealed to this daemon.
+ */
+declare function respondToLegacyHandshake(helloBytes: Uint8Array, identity: DaemonIdentity, crypto?: CryptoProvider): Promise<{
+    reply: Uint8Array;
+    keys: {
+        sendKey: Uint8Array;
+        recvKey: Uint8Array;
+    };
+}>;
+/** Serialize a handshake message to bytes for transport. */
+declare function encodePairingMessage(message: PairingHello | PairingReply): Uint8Array;
+/** Parse + validate a client hello from raw bytes. Truncated or malformed
+ *  input throws `PairingError("malformed_hello")` — never a partial object. A
+ *  retired pair/v1 hello throws `PairingError("pairing_protocol_outdated")` so
+ *  the daemon can answer it with `respondToLegacyHandshake`. */
+declare function decodePairingHello(bytes: Uint8Array): PairingHello;
+/** Parse + validate a daemon reply from raw bytes. Truncated or malformed
+ *  input throws `PairingError("malformed_reply")`. */
+declare function decodePairingReply(bytes: Uint8Array): PairingReply;
+
+/**
+ * The pairing offer URL codec (design: DESIGN §2).
+ *
+ * `agentproto pair offer` prints a single URL (also renderable as a QR):
+ *
+ * ```
+ *   agentproto://pair?v=2
+ *     &rv=<rendezvous ws/wss url>          // where both sides meet
+ *     &id=<fingerprint>                    // daemon identity fingerprint (32 hex)
+ *     &pk=<b64url x25519 SPKI DER>         // daemon static encryption key
+ *     &sk=<b64url ed25519 SPKI DER>        // daemon signing key
+ *     &s=<one-time offer secret>           // derives the route + auth tokens
+ *     &exp=<unix seconds>                  // offer expiry
+ * ```
+ *
+ * The URL **is** the bootstrap secret. It carries the daemon's public keys, so
+ * a client that scans it can pin the daemon and detect a man-in-the-middle
+ * rendezvous (verifying the handshake signature against `sk`); and it carries a
+ * one-time, short-TTL secret so a stranger who never saw the URL can't pair.
+ * The secret itself never goes on the wire: both sides derive from it a ROUTE
+ * token for the broker and an AUTH token for the sealed hello
+ * (`deriveOfferTokens`, ./derive.ts), so the broker — which sees the route —
+ * can't pair.
+ *
+ * v=1 offers (pair/v1) used their `t` token as both route and proof; they are
+ * refused with `pairing_protocol_outdated`.
+ *
+ * This module is a **pure codec** — it validates structure and echoes bytes; it
+ * performs no I/O and no network calls, so it is safe to run on either side
+ * (the daemon builds it, the client parses it). It lives in `@agentproto/secrets`
+ * beside the handshake so both sides share one authority on the format.
+ *
+ * ## The web form (phone QR)
+ *
+ * A phone camera opens `https://` links, not `agentproto://`. For a browser
+ * client the same parameters ride in the **fragment** of a web URL:
+ *
+ * ```
+ *   https://<fingerprint>.agentproto.cloud/pair#v=2&rv=…&id=…&pk=…&sk=…&s=…&exp=…
+ * ```
+ *
+ * i.e. the query string of the `agentproto://` URL, verbatim, after the `#`.
+ * A fragment is never sent to a server (not in the request line, not in
+ * `Referer`), so the page host never sees the token. `encodeOfferWebUrl` builds
+ * it; `parseOfferUrl` accepts both forms and validates them identically.
+ *
+ * Key material travels **base64url** in the URL (no `+`/`/`/`=` to percent-
+ * escape). The handshake, however, speaks standard base64 SPKI DER, so
+ * `parseOfferUrl` returns `daemonX25519Pub`/`daemonEd25519Pub` already converted
+ * back to standard base64 — feed them straight into `startClientHandshake`.
+ */
+
+/** URL scheme + host for offer URLs. */
+declare const OFFER_URL_SCHEME: "agentproto:";
+declare const OFFER_URL_HOST: "pair";
+/** Offer-format version. Bumped if the param set changes. v2: `s` (a secret
+ *  that never goes on the wire) replaces v1's `t` (route-and-proof). */
+declare const OFFER_VERSION: 2;
+/** A single shared-origin page for the web form of an offer: every daemon's
+ *  pairing on one origin (AIP-59 §5.8 fallback, which exposes each pairing to
+ *  every other paired daemon's UI). Not the default: select it explicitly with
+ *  `pairing.pairPage` / `--pair-page`. */
+declare const PAIR_WEB_URL: "https://cli.agentproto.sh/pair";
+/** Placeholder for the daemon fingerprint in a pair-page template. Allowed in
+ *  the hostname only. */
+declare const PAIR_PAGE_FP_PLACEHOLDER: "{fp}";
+/**
+ * The default pair page: one origin per daemon
+ * (`<fingerprint>.agentproto.cloud`, AIP-59 §5.8), so each daemon's page,
+ * service worker and stored credential are isolated from every other
+ * pairing's by the browser's same-origin policy. Override it with
+ * `pairing.pairPage` / `--pair-page` (a self-hosted page, or a plain URL).
+ */
+declare const PAIR_WEB_URL_TEMPLATE_CLOUD: "https://{fp}.agentproto.cloud/pair";
+/** The pair page used when none is configured. */
+declare const DEFAULT_PAIR_PAGE: "https://{fp}.agentproto.cloud/pair";
+/**
+ * A parsed, structurally-valid pairing offer. `daemonX25519Pub` /
+ * `daemonEd25519Pub` are standard-base64 SPKI DER (handshake-ready). `secret` is
+ * the opaque one-time offer secret verbatim — derive the route + auth tokens
+ * from it with `deriveOfferTokens`; never send it anywhere. `exp` is unix
+ * **seconds**.
+ */
+interface PairingOffer {
+    v: typeof OFFER_VERSION;
+    /** Rendezvous endpoint both sides dial (ws:// or wss://). */
+    rendezvousUrl: string;
+    /** Daemon identity fingerprint (32 lowercase hex) — must equal fingerprint(pk). */
+    fingerprint: string;
+    /** Daemon static X25519 public key, standard base64 SPKI DER. */
+    daemonX25519Pub: string;
+    /** Daemon static Ed25519 public key, standard base64 SPKI DER. */
+    daemonEd25519Pub: string;
+    /** One-time offer secret — derives the broker route and the sealed auth
+     *  token (`deriveOfferTokens`). Never sent on its own. */
+    secret: string;
+    /** Offer expiry, unix seconds. */
+    exp: number;
+}
+/**
+ * Build the offer URL from an offer. The public keys come in as standard
+ * base64 (the shape the identity file + handshake use) and are emitted as
+ * base64url. `secret` is emitted verbatim (callers mint it as base64url).
+ */
+declare function encodeOfferUrl(offer: PairingOffer): string;
+/**
+ * Resolve a pair-page setting for one daemon. `templateOrUrl` is either a plain
+ * http(s) URL (returned unchanged) or a template with `{fp}` in its HOSTNAME,
+ * e.g. `https://{fp}.agentproto.cloud/pair`, where `{fp}` becomes the daemon
+ * identity `fingerprint` (lowercase hex, which must be a valid DNS label).
+ * Throws `PairingError("malformed_offer")` for a template with `{fp}` outside
+ * the hostname (userinfo, port, path, query, fragment), for any other brace
+ * left in the URL, for a non-http(s) URL, or for a URL with a fragment (the
+ * offer goes there).
+ */
+declare function resolvePairPageUrl(templateOrUrl: string, fingerprint: string): string;
+/**
+ * The `host` (hostname[:port]) a pair page for `fingerprint` must be served
+ * from under `templateOrUrl`. The page compares it with its own
+ * `location.host` to refuse an offer meant for another daemon's origin.
+ */
+declare function expectedPairHost(templateOrUrl: string, fingerprint: string): string;
+/**
+ * Re-wrap an `agentproto://pair?…` offer URL as its web form
+ * `<pageUrl>#<query>` (see "The web form" above). The parameters are carried
+ * byte-for-byte. `pageUrl` is a plain http(s) URL without a fragment, or a
+ * `{fp}` template (see `resolvePairPageUrl`) filled in with the offer's daemon
+ * fingerprint (`id`).
+ */
+declare function encodeOfferWebUrl(offerUrl: string, pageUrl?: string): string;
+interface ParseOfferOptions {
+    /**
+     * When set, the parser rejects an offer whose `exp` is at or before this
+     * instant (unix **milliseconds**) with `PairingError("offer_expired")`. Omit
+     * to parse structure only and let the caller decide when to check expiry
+     * (the daemon's offer store is the authoritative single-use + expiry gate).
+     */
+    now?: number;
+}
+/**
+ * Parse + strictly validate an offer URL. Rejects with `PairingError` — never
+ * resolves a partial object — on any structural problem:
+ *
+ *   - `pairing_protocol_outdated`: a v=1 (pair/v1) offer from an older daemon.
+ *   - `malformed_offer`: wrong scheme/host, unknown version, missing/blank
+ *     params, non-base64url keys/token, non-integer `exp`, or a `fingerprint`
+ *     that does not match `fingerprint(pk)` (tamper detection: a rendezvous or
+ *     link-mangler that swaps the daemon key can't keep `id` consistent).
+ *   - `offer_expired`: only when `opts.now` is supplied and `exp` has passed.
+ *
+ * Accepts the `agentproto://pair?…` form and the web form
+ * (`https://…/pair#<query>`, see `encodeOfferWebUrl`).
+ *
+ * Async because the `id` ↔ `fingerprint(pk)` check hashes the key, and
+ * WebCrypto's SHA-256 is async; `crypto` selects the provider.
+ */
+declare function parseOfferUrl(url: string, opts?: ParseOfferOptions, crypto?: CryptoProvider): Promise<PairingOffer>;
+
+/**
+ * The hosted rendezvous broker — the meeting point `pair offer` defaults to
+ * when neither `--rendezvous` nor `pairing.rendezvous` is configured.
+ *
+ * ## Why it lives here
+ *
+ * It sits in `@agentproto/secrets/pairing`, beside `offer-url.ts` — the codec
+ * that bakes this endpoint into every offer's `rv=` param. The daemon runtime
+ * already depends on `@agentproto/secrets`, so it reaches this constant without
+ * `@agentproto/runtime` gaining a dependency on `@agentproto/rendezvous`. That
+ * matters: the broker package is a deliberately lean, standalone container (its
+ * only dep is `ws`), and nothing on the daemon/CLI side should have to pull it
+ * in just to learn the default endpoint's URL.
+ *
+ * ## What the broker sees
+ *
+ * The hosted broker only ever relays **ciphertext** — it learns the route
+ * token (opaque; it authenticates nothing — see ./derive.ts), the peers' IPs,
+ * ciphertext sizes, and timing; never plaintext or an auth token, and it
+ * cannot pair, inject, or alter frames (the pairing handshake is transcript-bound and
+ * every frame is AEAD-sealed). See `docs/cli/concepts/pairing.md` for the full
+ * threat model.
+ *
+ * ## Pointing elsewhere / self-hosting
+ *
+ * The broker is self-hostable (`agentproto rendezvous serve`). To route through
+ * your own instead of the hosted default, set `pairing.rendezvous` in
+ * `config.json` (or pass `--rendezvous` for a single offer). To disable the
+ * default entirely — so a daemon never reaches the hosted broker unless an
+ * endpoint is named explicitly — set `pairing.rendezvous: ""` (an explicit
+ * opt-out; `pair offer` then requires `--rendezvous`).
+ */
+declare const HOSTED_RENDEZVOUS_URL: "wss://rdv.agentproto.sh/v1";
+
+/**
+ * Pairing-derived key material (design: DESIGN §3/§4).
+ *
+ * All derivations are HKDF-SHA256 over secret material the untrusted
+ * rendezvous never sees, so it can't reproduce any of them:
+ *
+ *   - **pair root** `K_pair = HKDF(session, "pair-root")`: the long-term shared
+ *     secret persisted by both sides (daemon `pairings.json`, client
+ *     `pair-credentials.json`). Everything a reconnect needs derives from it.
+ *   - **route / auth split** (pair/v2): every pairing secret — the offer secret
+ *     from the offer URL, and the pair root per epoch — yields TWO one-way
+ *     outputs under distinct labels:
+ *       - a **route token**, the ONLY value that goes on the broker upgrade URL
+ *         (`?side=…&t=<route>`). It is an opaque meeting-point name; it
+ *         authenticates nothing.
+ *       - an **auth token**, sent ONLY inside the sealed hello (opened by the
+ *         daemon's X25519 key alone) and checked by the daemon in constant time.
+ *     HKDF is one-way, so a broker that logs every route it ever sees still
+ *     can't compute an auth token. pair/v1 used a single value for both jobs,
+ *     which let the broker pair as a client (offer) or replay a reconnect.
+ *
+ * Labels (salt ‖ info), all HKDF-SHA256:
+ *
+ * | output            | IKM                    | salt                        | info                           | len |
+ * | ----------------- | ---------------------- | --------------------------- | ------------------------------ | --- |
+ * | pair root         | sorted session keys    | transcript hash             | `agentproto/pair-root`         | 32  |
+ * | offer route       | UTF-8 of offer secret  | `agentproto/pair-offer`     | `agentproto/rv-route`          | 16  |
+ * | offer auth        | UTF-8 of offer secret  | `agentproto/pair-offer`     | `agentproto/rv-auth`           | 32  |
+ * | epoch route `e`   | pair root (raw bytes)  | `agentproto/rv-route-salt`  | `agentproto/rv-route` ‖ u64(e) | 16  |
+ * | epoch auth `e`    | pair root (raw bytes)  | `agentproto/rv-auth-salt`   | `agentproto/rv-auth` ‖ u64(e)  | 32  |
+ *
+ * Tokens are base64url: a 16-byte route is 22 chars (the broker's width), a
+ * 32-byte auth is 43. The epoch route is byte-identical to pair/v1's epoch
+ * token on purpose: a legacy (v1) client still meets the daemon at the same
+ * place, so the daemon can tell it to re-pair instead of leaving it to time out.
+ * That leaks nothing new — the route was always public to the broker.
+ *
+ * ## Why the pair root is derived order-independently
+ *
+ * A `PairingSession` exposes `sendKey`/`recvKey`, which are **role-swapped**
+ * between the two peers (the client's `sendKey` is the daemon's `recvKey`). To
+ * get an identical root on both sides without threading a "which side am I"
+ * flag, we sort the two keys byte-wise before mixing them: the *set* {sendKey,
+ * recvKey} is identical on both sides, so the sorted concatenation — and thus
+ * the HKDF output — is identical. Both keys are secret ECDH-derived material the
+ * rendezvous never sees, so the root (and every epoch token) stays secret.
+ *
+ * Every derivation is async (WebCrypto HKDF is) and takes an optional trailing
+ * `crypto` provider.
+ *
+ * ## The pair root as a non-extractable key
+ *
+ * The epoch derivations accept the pair root either as base64 or as a
+ * **non-extractable** WebCrypto HKDF `CryptoKey` (`importPairRootKey`). A
+ * browser client can keep that key in IndexedDB, and script can derive tokens
+ * with it but never read the root back out. The salts, infos and lengths are
+ * the same either way, so the tokens are byte-identical.
+ */
+
+/**
+ * Derive the long-term pair root from a completed handshake session. Returns
+ * standard base64 (persisted in `pairings.json` / `credentials.json`). Both
+ * peers, despite role-swapped direction keys, produce the identical root.
+ */
+declare function derivePairRoot(session: Pick<PairingSession, "sendKey" | "recvKey" | "transcriptHash">, crypto?: CryptoProvider): Promise<string>;
+/** The current pairing epoch — the UTC day number. Injectable `now` (ms) for
+ *  tests; defaults to the wall clock. */
+declare function currentEpoch(now?: number): number;
+/** A route token (broker URL only) and its paired auth token (sealed hello
+ *  only), both base64url. */
+interface RouteAuthTokens {
+    route: string;
+    auth: string;
+}
+/**
+ * Import a base64 pair root as a **non-extractable** WebCrypto HKDF key (see
+ * "The pair root as a non-extractable key" above). IndexedDB stores it by
+ * structured clone, so it stays non-extractable at rest.
+ */
+declare function importPairRootKey(pairRoot: string): Promise<CryptoKey>;
+/**
+ * Derive the rendezvous ROUTE token for a pairing at a given epoch:
+ * `HKDF(pairRoot, salt "agentproto/rv-route-salt", "agentproto/rv-route" ‖ epoch)`.
+ * base64url, so it drops straight into a `?t=` upgrade param. This is the only
+ * reconnect value the broker sees; it does not authenticate. Deterministic —
+ * both sides derive the same token for the same `(pairRoot, epoch)`.
+ */
+declare function deriveEpochRoutingToken(pairRoot: string | CryptoKey, epoch: number, crypto?: CryptoProvider): Promise<string>;
+/**
+ * Derive the reconnect AUTH token for a pairing at a given epoch:
+ * `HKDF(pairRoot, salt "agentproto/rv-auth-salt", "agentproto/rv-auth" ‖ epoch)`.
+ * Carried only inside the sealed hello; the daemon compares it in constant
+ * time. Never put it on a URL.
+ */
+declare function deriveEpochAuthToken(pairRoot: string | CryptoKey, epoch: number, crypto?: CryptoProvider): Promise<string>;
+/** Route + auth tokens for a pairing at one epoch. */
+declare function deriveEpochTokens(pairRoot: string | CryptoKey, epoch: number, crypto?: CryptoProvider): Promise<RouteAuthTokens>;
+/**
+ * Derive the route + auth tokens for a pairing offer from its secret (the
+ * offer URL's `s`): the daemon parks on — and the client dials — `route`; the
+ * client seals `auth` into its hello. The secret itself never leaves the offer
+ * URL.
+ */
+declare function deriveOfferTokens(offerSecret: string, crypto?: CryptoProvider): Promise<RouteAuthTokens>;
+/**
+ * The route + auth tokens a peer should accept/dial to bridge clock skew
+ * around a day boundary: the current epoch and the previous one (design:
+ * PLAN "accept current and previous epoch"). The daemon parks on both routes
+ * so a client whose clock sits on either side of midnight still finds it; the
+ * client likewise tries both when reconnecting.
+ */
+declare function epochRoutingTokens(pairRoot: string | CryptoKey, now?: number, crypto?: CryptoProvider): Promise<({
+    epoch: number;
+} & RouteAuthTokens)[]>;
+
+/**
+ * @agentproto/secrets/pairing — the `tunnel-e2e/v1` handshake.
+ *
+ * The reverse tunnel (`agentproto serve --connect <host>`) is a DIFFERENT trust
+ * relationship from the client↔daemon pairing in ./handshake.ts:
+ *
+ *   - There is no offer URL, no QR, no PKI. The daemon and the host already
+ *     share one pre-provisioned secret — the `apt_` **tunnel token** the daemon
+ *     presents as its WS bearer. Both ends hold it before the socket opens.
+ *   - So instead of authenticating with a static-key seal + Ed25519 signature,
+ *     both ends authenticate by proving knowledge of that shared token, and get
+ *     forward secrecy from a fresh ephemeral X25519 exchange.
+ *
+ * ```
+ *   daemon → host:   offer  = { ePub_d, mac_d = HMAC(K_auth, "offer/v1" ‖ ePub_d) }
+ *   host → daemon:   accept = { ePub_h, mac_h = HMAC(K_auth, "accept/v1" ‖ ePub_d ‖ ePub_h) }
+ *   both:            K_auth = HKDF(ikm = utf8(token),
+ *                             salt = sha256(token), info = "…/auth/v1")   // token-only MAC key
+ *                    K      = HKDF(ikm = ECDH(e_d, e_h),
+ *                             salt = sha256(token), info = "…/v1")        // → K_d2h ‖ K_h2d
+ * ```
+ *
+ * Why this shape:
+ *   - **Mutual authentication at handshake time.** `mac_d` binds the daemon
+ *     ephemeral to the token; the host verifies it and refuses (`bad_auth`) if
+ *     the token differs — no partial session, no plaintext, before the daemon's
+ *     first byte. `mac_h` binds BOTH ephemerals to the token; the daemon
+ *     verifies it symmetrically. A man-in-the-middle without the token cannot
+ *     forge either MAC for its own ephemeral, and cannot reuse a recorded one
+ *     (it lacks the matching private key to finish the ECDH). So the confirm is
+ *     a **transcript/confirm step that fails a token mismatch AT handshake time,
+ *     not mid-stream** — exactly what a wrong `tunnel.token` on one side needs.
+ *   - **Forward secrecy.** The session keys mix ONLY the ephemeral ECDH output;
+ *     the long-term token merely salts them. A later token compromise can't
+ *     decrypt a recorded past session.
+ *   - **Salt-binds the token.** Because `sha256(token)` salts the session-key
+ *     HKDF too, even if the MACs were somehow bypassed the derived AEAD keys
+ *     still disagree under a mismatched token → the channel fails closed.
+ *
+ * Like ./handshake.ts, the primitives come from a `CryptoProvider` (node:crypto
+ * or WebCrypto) and every crypto entry point is async with an optional trailing
+ * `crypto` argument. Like ./handshake.ts, this module is also deliberately **transport-agnostic**: it
+ * produces and consumes plain byte messages (`encode*`/`decode*`). The code that
+ * pumps those bytes over a `FrameSink` and wraps the channel lives in
+ * `@agentproto/acp/tunnel`, which never depends on this package — it receives
+ * only the two derived symmetric keys. Everything crypto stays here.
+ */
+
+/** Wire version. Bumped if the message shape or key schedule changes; both
+ *  sides refuse a version they don't recognise. */
+declare const TUNNEL_E2E_VERSION: 1;
+/** Stable, machine-readable failure codes. Every rejection maps to one of these
+ *  so callers (and tests) branch on a code, not a message string. */
+type TunnelHandshakeErrorCode = "malformed_offer" | "malformed_accept" | "invalid_key" | "bad_auth" | "unsupported_version";
+/** Raised for every tunnel-handshake failure. Never carries key material or the
+ *  token; the `code` is the contract, the message is for humans. */
+declare class TunnelHandshakeError extends Error {
+    readonly code: TunnelHandshakeErrorCode;
+    constructor(code: TunnelHandshakeErrorCode, message: string);
+}
+/** Daemon → host. `ePub` is the daemon ephemeral X25519 public key (base64 SPKI
+ *  DER); `mac` authenticates it under the shared tunnel token. */
+interface TunnelOffer {
+    v: typeof TUNNEL_E2E_VERSION;
+    ePub: string;
+    mac: string;
+}
+/** Host → daemon. `ePub` is the host ephemeral X25519 public key (base64 SPKI
+ *  DER); `mac` authenticates both ephemerals under the shared tunnel token. */
+interface TunnelAccept {
+    v: typeof TUNNEL_E2E_VERSION;
+    ePub: string;
+    mac: string;
+}
+/**
+ * A completed tunnel handshake, on either side. `sendKey`/`recvKey` are already
+ * role-adjusted (the daemon's `sendKey` is the host's `recvKey`), so the
+ * consumer — `wrapE2E` — never has to know which side it is.
+ */
+interface TunnelE2ESession {
+    /** AES-256-GCM key for frames THIS side sends. 32 bytes. */
+    sendKey: Uint8Array;
+    /** AES-256-GCM key for frames THIS side receives. 32 bytes. */
+    recvKey: Uint8Array;
+    /** `sha256(SESSION_INFO ‖ ePub_d ‖ ePub_h)` — the exact transcript both sides
+     *  bound to. Exposed for parity with `PairingSession`; not required to use. */
+    transcriptHash: Uint8Array;
+}
+/** A started daemon handshake: send `offer`, then feed the host's `accept` to
+ *  `complete` to derive the session. */
+interface StartedTunnelHandshake {
+    offer: TunnelOffer;
+    /**
+     * Verify the host accept and derive the session. Throws `TunnelHandshakeError`
+     * on a bad MAC (`bad_auth` — the host holds a different token), a malformed
+     * accept, or an invalid key — never returns partial state.
+     */
+    complete(accept: TunnelAccept): Promise<TunnelE2ESession>;
+}
+/**
+ * Begin the daemon (initiator) side. Generates the daemon ephemeral keypair,
+ * MACs it under the token, and resolves to the `offer` to send plus a
+ * `complete` to run once the host replies with its `accept`. `crypto` selects
+ * the primitive implementation (captured for `complete` too).
+ */
+declare function startTunnelHandshake(token: string, crypto?: CryptoProvider): Promise<StartedTunnelHandshake>;
+/** A completed host handshake: send `accept`, keep `session`. */
+interface TunnelHandshakeResult {
+    accept: TunnelAccept;
+    session: TunnelE2ESession;
+}
+/**
+ * Respond to a daemon offer (host side). Verifies the offer MAC under the shared
+ * token, generates the host ephemeral, MACs both ephemerals, and derives the
+ * session. Rejects with `TunnelHandshakeError` on a bad MAC (`bad_auth`),
+ * malformed offer, or invalid key BEFORE producing any accept — so a mismatched
+ * token yields no session and no reply, failing closed at handshake time.
+ */
+declare function respondToTunnelHandshake(offer: TunnelOffer, token: string, crypto?: CryptoProvider): Promise<TunnelHandshakeResult>;
+/** Serialize a handshake message to bytes for transport. */
+declare function encodeTunnelMessage(message: TunnelOffer | TunnelAccept): Uint8Array;
+/** Parse + validate a daemon offer from raw bytes. Truncated or malformed input
+ *  throws `TunnelHandshakeError("malformed_offer")` — never a partial object. */
+declare function decodeTunnelOffer(bytes: Uint8Array): TunnelOffer;
+/** Parse + validate a host accept from raw bytes. Truncated or malformed input
+ *  throws `TunnelHandshakeError("malformed_accept")`. */
+declare function decodeTunnelAccept(bytes: Uint8Array): TunnelAccept;
+
+/**
+ * `CryptoProvider` over WebCrypto (`globalThis.crypto.subtle`) — the default in
+ * the browser-safe entry. Browser-safe: no `node:` import, no `Buffer`.
+ *
+ * Needs X25519 + Ed25519 in `SubtleCrypto` (Chrome 133+, Safari 17+, Firefox
+ * 130+, Node ≥ 20). The subtle instance is resolved lazily, per call, so merely
+ * importing this module never throws in an environment without WebCrypto.
+ */
+
+declare const webCryptoProvider: CryptoProvider;
+
+export { startClientHandshake as $, decodeTunnelOffer as A, deriveEpochAuthToken as B, type ClientHandshakeParams as C, DEFAULT_PAIR_PAGE as D, deriveEpochRoutingToken as E, deriveEpochTokens as F, deriveOfferTokens as G, HOSTED_RENDEZVOUS_URL as H, derivePairRoot as I, encodeOfferUrl as J, encodeOfferWebUrl as K, LEGACY_PAIR_VERSION as L, encodePairingMessage as M, encodeTunnelMessage as N, OFFER_URL_HOST as O, PAIRING_PROTOCOL_OUTDATED_MESSAGE as P, epochRoutingTokens as Q, type RouteAuthTokens as R, type StartedClientHandshake as S, TUNNEL_E2E_VERSION as T, expectedPairHost as U, importPairRootKey as V, parseOfferUrl as W, resolvePairPageUrl as X, respondToHandshake as Y, respondToLegacyHandshake as Z, respondToTunnelHandshake as _, type DaemonHandshakeParams as a, startTunnelHandshake as a0, webCryptoProvider as a1, type DaemonHandshakeResult as b, OFFER_URL_SCHEME as c, OFFER_VERSION as d, PAIR_PAGE_FP_PLACEHOLDER as e, PAIR_VERSION as f, PAIR_WEB_URL as g, PAIR_WEB_URL_TEMPLATE_CLOUD as h, PairingError as i, type PairingErrorCode as j, type PairingHello as k, type PairingOffer as l, type PairingReply as m, type PairingSession as n, type ParseOfferOptions as o, type StartedTunnelHandshake as p, type TunnelAccept as q, type TunnelE2ESession as r, TunnelHandshakeError as s, type TunnelHandshakeErrorCode as t, type TunnelHandshakeResult as u, type TunnelOffer as v, currentEpoch as w, decodePairingHello as x, decodePairingReply as y, decodeTunnelAccept as z };