@agentproto/secrets 0.1.0-alpha.0 → 0.2.0

package/dist/pairing/index.d.ts

@@ -0,0 +1,455 @@
+import { DaemonIdentity } from '../identity/index.js';
+
+/**
+ * @agentproto/secrets/pairing — the `pair/v1` 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, offerToken})
+ *   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/v1")
+ *                     → 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 one-time `offerToken`.
+ *   - `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.
+ *
+ * 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. */
+declare const PAIR_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 PairingErrorCode = "malformed_hello" | "malformed_reply" | "invalid_key" | "unseal_failed" | "ephemeral_mismatch" | "offer_rejected" | "bad_signature" | "malformed_offer" | "offer_expired";
+/** 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;
+    /** One-time offer token. From the offer's `t`. */
+    offerToken: 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. Throws `PairingError` on
+     *  a bad signature, malformed reply, or invalid key — never returns partial
+     *  state. */
+    complete(reply: PairingReply): PairingSession;
+}
+/**
+ * Begin a client handshake. Generates the client ephemeral keypair, seals the
+ * hello payload to the daemon's static key, and returns the `hello` to send
+ * plus a `complete` to run once the daemon replies.
+ */
+declare function startClientHandshake(params: ClientHandshakeParams): StartedClientHandshake;
+/** What the daemon brings to the handshake: its identity, and a predicate that
+ *  validates (and, in P2, spends) the one-time offer token. */
+interface DaemonHandshakeParams {
+    identity: DaemonIdentity;
+    /**
+     * Validate the presented offer token. 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 or already
+     * spent token simply returns false.
+     */
+    verifyOfferToken: (token: string) => 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 offer token and the ephemeral-key binding, signs the
+ * transcript, and derives the session. Throws `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): DaemonHandshakeResult;
+/** 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. */
+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=1
+ *     &rv=<rendezvous ws/wss url>          // where both sides meet
+ *     &id=<fingerprint>                    // daemon identity fingerprint (16 hex)
+ *     &pk=<b64url x25519 SPKI DER>         // daemon static encryption key
+ *     &sk=<b64url ed25519 SPKI DER>        // daemon signing key
+ *     &t=<one-time offer token>            // rendezvous routing + first-contact proof
+ *     &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 token so a stranger who never saw the URL can't pair.
+ *
+ * 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.
+ *
+ * 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. */
+declare const OFFER_VERSION: 1;
+/**
+ * A parsed, structurally-valid pairing offer. `daemonX25519Pub` /
+ * `daemonEd25519Pub` are standard-base64 SPKI DER (handshake-ready). `token` is
+ * the opaque one-time offer token verbatim (the daemon checks it against its
+ * offer store). `exp` is unix **seconds**.
+ */
+interface PairingOffer {
+    v: typeof OFFER_VERSION;
+    /** Rendezvous endpoint both sides dial (ws:// or wss://). */
+    rendezvousUrl: string;
+    /** Daemon identity fingerprint (16 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 token (routing + first-contact proof). */
+    token: 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. `token` is emitted verbatim (callers mint it as base64url).
+ */
+declare function encodeOfferUrl(offer: PairingOffer): 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. Throws `PairingError` — never returns
+ * a partial object — on any structural problem:
+ *
+ *   - `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.
+ */
+declare function parseOfferUrl(url: string, opts?: ParseOfferOptions): 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 routing
+ * token, the peers' IPs, ciphertext sizes, and timing; never plaintext, and it
+ * cannot 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).
+ *
+ * Two derivations, both HKDF-SHA256 over secret session material so the
+ * untrusted rendezvous — which sees the handshake transcript in the clear —
+ * can never reproduce them:
+ *
+ *   - **pair root** `K_pair = HKDF(session, "pair-root")`: the long-term shared
+ *     secret persisted by both sides (daemon `pairings.json`, client
+ *     `credentials.json`). Everything a reconnect needs derives from it.
+ *   - **epoch routing token** `t' = HKDF(K_pair, "rv-route" ‖ epoch)`: the
+ *     rendezvous routing token for a reconnect, rotated per UTC day so the
+ *     broker can't link a pairing's sessions across days. Both sides derive the
+ *     same token for the same epoch without any further communication.
+ *
+ * ## 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.
+ *
+ * This uses the shipped P1 `PairingSession` verbatim (no change to the key
+ * schedule) — it only reads the two direction keys and the transcript hash.
+ */
+
+/**
+ * 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: PairingSession): 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;
+/**
+ * Derive the rendezvous routing token for a pairing at a given epoch:
+ * `t' = HKDF(pairRoot, "rv-route" ‖ epoch)`. Returned as base64url so it drops
+ * straight into a `?t=` upgrade param. Deterministic — both sides derive the
+ * same token for the same `(pairRoot, epoch)`.
+ */
+declare function deriveEpochRoutingToken(pairRoot: string, epoch: number): string;
+/**
+ * The set of epoch routing 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 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, now?: number): {
+    epoch: number;
+    token: string;
+}[];
+
+/**
+ * @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, this module is 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): TunnelE2ESession;
+}
+/**
+ * Begin the daemon (initiator) side. Generates the daemon ephemeral keypair,
+ * MACs it under the token, and returns the `offer` to send plus a `complete` to
+ * run once the host replies with its `accept`.
+ */
+declare function startTunnelHandshake(token: string): 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. Throws `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): 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;
+
+export { type ClientHandshakeParams, type DaemonHandshakeParams, type DaemonHandshakeResult, HOSTED_RENDEZVOUS_URL, OFFER_URL_HOST, OFFER_URL_SCHEME, OFFER_VERSION, PAIR_VERSION, PairingError, type PairingErrorCode, type PairingHello, type PairingOffer, type PairingReply, type PairingSession, type ParseOfferOptions, type StartedClientHandshake, type StartedTunnelHandshake, TUNNEL_E2E_VERSION, type TunnelAccept, type TunnelE2ESession, TunnelHandshakeError, type TunnelHandshakeErrorCode, type TunnelHandshakeResult, type TunnelOffer, currentEpoch, decodePairingHello, decodePairingReply, decodeTunnelAccept, decodeTunnelOffer, deriveEpochRoutingToken, derivePairRoot, encodeOfferUrl, encodePairingMessage, encodeTunnelMessage, epochRoutingTokens, parseOfferUrl, respondToHandshake, respondToTunnelHandshake, startClientHandshake, startTunnelHandshake };