bolthole 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,143 @@
-# Temporary Holding Version
+# bolthole (JavaScript)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Reach any service from anywhere, through a relay that can't read your traffic.**
+
+JavaScript SDK for [Bolthole](https://github.com/abcdlsj/bolthole). Runs in
+browsers, Node 22+, Deno, Bun and Cloudflare Workers. Plain ES modules on
+WebCrypto — no build step, no dependencies.
+
+```
+ your service ── agent ──outbound WSS──▶ relay ◀──HTTPS/WSS── client (phone, browser, server)
+                   └──────────── end-to-end encrypted (Noise) ───────────┘
+```
+
+The agent dials **out** to the relay and keeps the connection open. Clients go
+through the relay to the agent. Both ends derive keys from a 256-bit code that
+travels in the URL fragment, so the relay only ever forwards ciphertext.
+
+## Install
+
+```bash
+npm install bolthole
+```
+
+Need a relay? Deploy one to Cloudflare Workers for free, or run the Go binary:
+
+```bash
+npx wrangler deploy                      # see github.com/abcdlsj/bolthole
+bolthole serve --addr :8787              # or a relay on your own box
+```
+
+## Client
+
+```js
+import { Client } from 'bolthole';
+
+const c = new Client('https://relay.example.com/#k=6Xo2…');
+
+const res = await c.fetch('/api/status', { method: 'POST', body: 'x' });
+const ws = await c.websocket('/live');            // send() / read() / close()
+const sock = await c.tcp();                       // raw byte stream
+```
+
+`c.fetch` and `c.websocket` take the same arguments as the globals; paths are
+resolved against the agent's address, not the relay's.
+
+| Method | |
+| --- | --- |
+| `fetch(input, init)` | HTTP through the agent, response streamed back |
+| `websocket(path, protocols)` | WebSocket over the tunnel: `send()`, `read()`, `close()`, `protocol` |
+| `tcp(target)` | Raw stream to a target the agent allows |
+| `open(kind, meta)` | Any stream kind, including ones you define; `st.acceptMeta` holds the agent's reply |
+| `session()` | The live encrypted session, dialing if needed |
+| `close()` | Drop the connection |
+
+Options: `{ mode: 'auto' | 'relay' | 'direct', direct: [url], relayDelayMs,
+directTimeoutMs, WebSocket }`. In the default `auto` mode the client races
+direct addresses against the relay and settles on whichever answers first.
+
+## Agent
+
+```js
+import { Agent } from 'bolthole';
+
+const agent = new Agent({
+  relay: 'https://relay.example.com',
+  // code: '…',                  // persistent 43-char code; random if omitted
+  fetch: (req) => new Response('hi'),   // your service
+});
+agent.run();                    // reconnects forever
+console.log(agent.connString);  // send this to clients — it is a password
+```
+
+Options: `{ relay, code, fetch, websocket, kinds, public, direct, auth, name,
+ onStatus, onSession, WebSocket }`. `websocket` handles `ws` streams,
+`kinds` maps a custom kind name to `(stream, info) => …`.
+
+`fetch` is any fetch-style handler, so an existing `Request → Response`
+function works unchanged. Set `public: true` to also serve plaintext HTTP
+through the relay for things meant to be public (webhooks, a landing page) —
+in that mode the relay can see and alter that traffic. `auth` carries a relay
+registration key or JWT; `onStatus` reports `{connected, error, retryMs}`.
+
+Shorthands: `connect(connString, opts)` and `serve(opts)`.
+
+## Custom stream kinds
+
+HTTP, WebSocket and TCP are just stream kinds. Define your own when you want
+your own protocol inside the encrypted channel:
+
+```js
+// Agent side: register a handler per kind.
+new Agent({
+  relay: 'https://relay.example.com',
+  fetch: handler,
+  kinds: {
+    'myapp.sync': async (st, info) => {
+      await st.accept({ ok: true });      // send meta back to the caller
+      for await (const chunk of st.readable()) { /* … */ }
+      await st.write(reply);              // backpressure-aware
+    },
+  },
+}).run();
+
+// Client side: open that kind.
+const st = await c.open('myapp.sync', { room: 'dev' });
+console.log(st.acceptMeta);               // { ok: true }
+await st.write(bytes);
+await st.closeWrite();
+for await (const chunk of st.readable()) { /* … */ }
+```
+
+A stream is a byte pipe with flow control: `write`, `read`, `readable()`
+(a web `ReadableStream`), `pipeFrom`, `closeWrite`, `reset(code)`.
+
+Stream kinds are documented in the
+[protocol spec](https://github.com/abcdlsj/bolthole/blob/main/spec/PROTOCOL.md).
+
+## Relay
+
+`bolthole/relay` is the relay core, so you can host one without the Go binary:
+
+```js
+import { RelayHub } from 'bolthole/relay';
+```
+
+The Workers edition lives in the main repository under `cloudflare/`.
+
+## What this package does not hide
+
+The relay sees timing, sizes, and which token hash is talked to. Put it behind
+TLS. A page served through the relay could be altered by a malicious relay
+before it runs — for real deployments, host the client page yourself.
+
+## Credits
+
+The approach came from [alma-relay](https://github.com/yetone/alma-relay):
+an outbound-only agent connection, a relay blind to its traffic, and a Workers
+deployment that costs nothing while idle. Bolthole generalizes it into a
+protocol and SDK for any service.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "bolthole",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Reach any service from anywhere through a relay that can't read your traffic. Browser, Node, Deno, Bun and Workers.",
+  "type": "module",
+  "license": "MIT",
+  "author": "abcdlsj",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/abcdlsj/bolthole.git",
+    "directory": "js"
+  },
+  "homepage": "https://github.com/abcdlsj/bolthole/tree/main/js#readme",
+  "bugs": "https://github.com/abcdlsj/bolthole/issues",
+  "keywords": [
+    "relay",
+    "tunnel",
+    "reverse-proxy",
+    "end-to-end-encryption",
+    "noise-protocol",
+    "websocket",
+    "cloudflare-workers",
+    "nat-traversal"
+  ],
+  "exports": {
+    ".": "./src/index.js",
+    "./relay": "./src/relay.js"
+  },
+  "files": ["src"],
+  "engines": { "node": ">=22" },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "devDependencies": {
+    "ws": "^8.18.0"
+  }
+}

package/src/agent.js

@@ -0,0 +1,161 @@
+// Agent: expose a fetch-style handler (and optional WebSocket / custom
+// stream handlers) through a relay, end-to-end encrypted. Runs anywhere
+// with WebSocket + WebCrypto: Node 22+, Deno, Bun.
+import { derive, formatConnString, newCode } from './codes.js';
+import { agentHandshake, PROTO_MUX, MAX_RECORD } from './noise.js';
+import { Session } from './mux.js';
+import { wsConn, serveHttp, WsStream } from './kinds.js';
+import { enc, dec } from './bytes.js';
+
+const E2E_PATH = '/.bolthole/e2e';
+
+/**
+ * @typedef {object} AgentOptions
+ * @property {string} relay                       relay base URL
+ * @property {string} [code]                      connect code (generated if omitted)
+ * @property {(req: Request, info: {encrypted: boolean, session: Session}) => Response|Promise<Response>} [fetch] handler for `http` streams
+ * @property {(ws: WsStream, meta: object) => void} [websocket] handler for `ws` streams
+ * @property {Record<string, (stream: import('./mux.js').Stream, info: object) => void>} [kinds] custom stream kinds
+ * @property {(session: Session, hello: object) => void} [onSession] each connected client
+ * @property {string} [name]
+ * @property {string} [auth]                      registration key or JWT
+ * @property {boolean} [public]                   also serve plaintext streams from the relay
+ * @property {string[]} [direct]                  direct URLs to advertise to clients
+ * @property {(s: {connected: boolean, error?: Error, retryMs?: number}) => void} [onStatus]
+ * @property {typeof WebSocket} [WebSocket]
+ */
+
+export class Agent {
+  /** @param {AgentOptions} opts */
+  constructor(opts) {
+    this.opts = opts;
+    this.code = opts.code ?? newCode();
+    this.WS = opts.WebSocket ?? globalThis.WebSocket;
+    this.keys = derive(this.code);
+    this.stopped = false;
+    this.outer = null;
+  }
+
+  /** The connection string clients need. */
+  get connString() {
+    return formatConnString(this.opts.relay, this.code);
+  }
+
+  /** Where plaintext traffic lands when `public` is set. */
+  async publicURL() {
+    return `${this.opts.relay.replace(/\/+$/, '')}/c/${(await this.keys).routingToken}/`;
+  }
+
+  /** Connects and keeps reconnecting until stop(). Resolves when stopped. */
+  async run() {
+    let attempt = 0;
+    while (!this.stopped) {
+      const started = Date.now();
+      try {
+        const sess = await this._connect();
+        attempt = 0;
+        this.opts.onStatus?.({ connected: true });
+        await Promise.race([
+          sess.done,
+          new Promise((r) => (sess.onGoAway = r)), // relay draining: redial now
+        ]);
+        if (sess.remoteGoAway && !this.stopped) continue;
+        throw sess.err ?? new Error('bolthole: relay connection closed');
+      } catch (e) {
+        if (this.stopped) break;
+        if (e.permanent) {
+          this.opts.onStatus?.({ connected: false, error: e });
+          throw e;
+        }
+        if (Date.now() - started > 30000) attempt = 0;
+        let delay = Math.random() * Math.min(30000, 500 * 2 ** attempt) + 250;
+        if (e.code === 4000) delay = 30000; // replaced by another agent with our code
+        attempt++;
+        this.opts.onStatus?.({ connected: false, error: e, retryMs: delay });
+        await new Promise((r) => setTimeout(r, delay));
+      }
+    }
+  }
+
+  stop() {
+    this.stopped = true;
+    this.outer?.goAway('going_away', 'agent shutting down');
+    this.outer?.close();
+  }
+
+  async _connect() {
+    const { tokenHash } = await this.keys;
+    const base = this.opts.relay.replace(/^http/, 'ws').replace(/\/+$/, '');
+    const conn = await wsConn(new this.WS(`${base}/v1/agent?th=${tokenHash}`, ['relay.v1']));
+    await conn.write(JSON.stringify({ type: 'hello', v: 1, token_hash: tokenHash, name: this.opts.name, auth: this.opts.auth, version: '0.1.0', caps: ['mux/1'] }));
+    let w;
+    try {
+      w = JSON.parse(dec.decode(await conn.read()));
+    } catch (e) {
+      if (e.code === 4002 || e.code === 4003) e.permanent = true;
+      throw e;
+    }
+    if (w.type === 'error') {
+      const err = new Error(`bolthole: relay refused registration: ${w.code}: ${w.message}`);
+      err.permanent = w.code === 'unauthorized' || w.code === 'invalid_token_hash';
+      conn.close();
+      throw err;
+    }
+    const sess = new Session(conn, { dialer: true, heartbeatMs: w.heartbeat_ms || 20000, onStream: (st) => this._outer(st) });
+    this.outer = sess;
+    return sess;
+  }
+
+  _outer(st) {
+    if (st.kind === 'ws' && (st.meta?.path || '').split('?')[0] === E2E_PATH) {
+      st.accept({}).then(() => this.serveSecure(new WsStream(st).asConn())).catch(() => st.reset('internal'));
+      return;
+    }
+    if (!this.opts.public) return st.reset('e2e_required', 'this agent only accepts end-to-end encrypted sessions');
+    this._dispatch(st, { encrypted: false, session: this.outer });
+  }
+
+  /** Runs the E2E handshake on any transport (relay stream or direct socket). */
+  async serveSecure(conn) {
+    const { psk } = await this.keys;
+    let res;
+    try {
+      res = await agentHandshake(conn, psk, (h) => {
+        if (!(h.protos || []).includes(PROTO_MUX)) throw new Error('no common protocol');
+        return { proto: PROTO_MUX, name: this.opts.name, direct: this.opts.direct };
+      });
+    } catch {
+      conn.close();
+      return;
+    }
+    const inner = new Session(res.channel, { dialer: false, maxFrame: MAX_RECORD, onStream: (st) => this._dispatch(st, { encrypted: true, session: inner }) });
+    this.opts.onSession?.(inner, res.hello);
+    await inner.done;
+  }
+
+  _dispatch(st, info) {
+    const o = this.opts;
+    if (st.kind === 'http' && o.fetch) return void serveHttp(st, o.fetch, info).catch(() => st.reset('internal'));
+    if (st.kind === 'ws' && o.websocket) {
+      return void st
+        .accept({})
+        .then(() => o.websocket(new WsStream(st), st.meta || {}, info))
+        .catch(() => st.reset('internal'));
+    }
+    const h = o.kinds?.[st.kind];
+    if (h) return void Promise.resolve()
+      .then(() => h(st, info))
+      .catch(() => st.reset('internal'));
+    st.reset('unsupported_kind', st.kind);
+  }
+}
+
+/** Shorthand: start an agent and return it. */
+export function serve(opts) {
+  const a = new Agent(opts);
+  a.running = a.run();
+  a.running.catch(() => {});
+  return a;
+}
+
+export { enc };

package/src/bytes.js

@@ -0,0 +1,93 @@
+// Small byte helpers shared by every module. No dependencies.
+
+export const enc = new TextEncoder();
+export const dec = new TextDecoder();
+
+/** @param {...Uint8Array} parts */
+export function concat(...parts) {
+  let n = 0;
+  for (const p of parts) n += p.length;
+  const out = new Uint8Array(n);
+  let o = 0;
+  for (const p of parts) {
+    out.set(p, o);
+    o += p.length;
+  }
+  return out;
+}
+
+export function b64url(bytes) {
+  let s = '';
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+export function unb64url(s) {
+  const t = s.replace(/-/g, '+').replace(/_/g, '/');
+  const bin = atob(t + '='.repeat((4 - (t.length % 4)) % 4));
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+export function hex(bytes) {
+  let s = '';
+  for (const b of bytes) s += b.toString(16).padStart(2, '0');
+  return s;
+}
+
+export function u32(n) {
+  const b = new Uint8Array(4);
+  new DataView(b.buffer).setUint32(0, n >>> 0);
+  return b;
+}
+
+export function readU32(b, off = 0) {
+  return new DataView(b.buffer, b.byteOffset, b.byteLength).getUint32(off);
+}
+
+/** Normalise ArrayBuffer / views / Node Buffers to a plain Uint8Array. */
+export function toBytes(x) {
+  if (x instanceof Uint8Array) return x;
+  if (x instanceof ArrayBuffer) return new Uint8Array(x);
+  if (ArrayBuffer.isView(x)) return new Uint8Array(x.buffer, x.byteOffset, x.byteLength);
+  if (typeof x === 'string') return enc.encode(x);
+  throw new TypeError('expected bytes');
+}
+
+/** A promise you can resolve from outside. */
+export function deferred() {
+  let resolve, reject;
+  const promise = new Promise((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+/** An unbounded async FIFO: push() items, await shift(). */
+export class Queue {
+  constructor() {
+    this.items = [];
+    this.waiters = [];
+    this.error = null;
+  }
+  push(item) {
+    if (this.error) return;
+    const w = this.waiters.shift();
+    if (w) w.resolve(item);
+    else this.items.push(item);
+  }
+  fail(err) {
+    if (this.error) return;
+    this.error = err;
+    for (const w of this.waiters.splice(0)) w.reject(err);
+  }
+  shift() {
+    if (this.items.length) return Promise.resolve(this.items.shift());
+    if (this.error) return Promise.reject(this.error);
+    const d = deferred();
+    this.waiters.push(d);
+    return d.promise;
+  }
+}

package/src/client.js

@@ -0,0 +1,167 @@
+// Client: reach an agent through a relay (or directly) and talk to it with
+// fetch(), WebSockets, raw streams, or your own stream kinds.
+import { parseConnString, derive } from './codes.js';
+import { clientHandshake, PROTO_MUX, MAX_RECORD } from './noise.js';
+import { Session } from './mux.js';
+import { wsConn, fetchOver, WsStream } from './kinds.js';
+
+const E2E_PATH = '/.bolthole/e2e';
+
+/**
+ * @typedef {object} ConnectOptions
+ * @property {string} [name]          sent to the agent inside the encrypted hello
+ * @property {'auto'|'relay'|'direct'} [mode]
+ * @property {string[]} [direct]      extra direct candidates (ws://host:port/.bolthole/e2e)
+ * @property {number} [relayDelayMs]  head start for direct candidates (250)
+ * @property {number} [directTimeoutMs] (2000)
+ * @property {(path: string) => void} [onPath]
+ * @property {(stream: import('./mux.js').Stream) => void} [onStream] agent-opened streams
+ * @property {typeof WebSocket} [WebSocket] constructor to use (defaults to the global)
+ */
+
+/**
+ * A resilient connection to one agent. Reconnects on demand and remembers
+ * direct candidates the agent advertises.
+ */
+export class Client {
+  /** @param {string} connString @param {ConnectOptions} [opts] */
+  constructor(connString, opts = {}) {
+    this.cs = parseConnString(connString);
+    this.opts = { mode: 'auto', relayDelayMs: 250, directTimeoutMs: 2000, ...opts };
+    this.WS = opts.WebSocket ?? globalThis.WebSocket;
+    if (!this.WS) throw new Error('bolthole: no WebSocket implementation; pass opts.WebSocket');
+    this.direct = [...(opts.direct ?? [])];
+    this.keys = derive(this.cs.code);
+    this.current = null;
+    this.dialing = null;
+    this.path = '';
+  }
+
+  /** Returns a live session, dialing if needed. */
+  async session() {
+    if (this.current && !this.current.session.isClosed && !this.current.session.remoteGoAway) return this.current.session;
+    if (!this.dialing) {
+      this.dialing = this._race().finally(() => (this.dialing = null));
+    }
+    const c = await this.dialing;
+    return c.session;
+  }
+
+  async _race() {
+    const { routingToken, psk } = await this.keys;
+    const cands = [];
+    if (this.opts.mode !== 'relay') for (const url of this.direct) cands.push({ path: 'direct ' + url, url, delay: 0, timeout: this.opts.directTimeoutMs });
+    if (this.opts.mode !== 'direct') {
+      const base = this.cs.relay.replace(/^http/, 'ws');
+      cands.push({ path: 'relay', url: `${base}/c/${routingToken}${E2E_PATH}`, delay: cands.length ? this.opts.relayDelayMs : 0, timeout: 30000 });
+    }
+    if (!cands.length) throw new Error('bolthole: no path to the agent');
+
+    const ctrl = { done: false };
+    const attempts = cands.map((c) => this._dialOne(c, psk, ctrl));
+    let winner;
+    try {
+      winner = await Promise.any(attempts);
+    } catch (e) {
+      throw new AggregateError(e.errors, 'bolthole: could not reach the agent');
+    }
+    ctrl.done = true;
+    // Close any loser that also finished.
+    for (const a of attempts) a.then((c) => c !== winner && c.session.close(), () => {});
+    this._install(winner);
+    return winner;
+  }
+
+  async _dialOne(cand, psk, ctrl) {
+    if (cand.delay) await new Promise((r) => setTimeout(r, cand.delay));
+    if (ctrl.done) throw new Error('lost the race');
+    const ws = new this.WS(cand.url);
+    const timer = setTimeout(() => {
+      try {
+        ws.close();
+      } catch {}
+    }, cand.timeout);
+    try {
+      const raw = await wsConn(ws);
+      const { channel, hello } = await clientHandshake(raw, psk, { protos: [PROTO_MUX], name: this.opts.name || undefined });
+      clearTimeout(timer);
+      const session = new Session(channel, { dialer: true, maxFrame: MAX_RECORD, onStream: this.opts.onStream });
+      return { session, hello, path: cand.path };
+    } catch (e) {
+      clearTimeout(timer);
+      try {
+        ws.close();
+      } catch {}
+      throw e;
+    }
+  }
+
+  _install(c) {
+    const old = this.current;
+    this.current = c;
+    this.path = c.path;
+    for (const u of c.hello.direct ?? []) if (!this.direct.includes(u)) this.direct.push(u);
+    if (old) {
+      old.session.goAway('going_away', 'client switched path');
+      const drain = () => (old.session.streams.size === 0 ? old.session.close() : setTimeout(drain, 500));
+      drain();
+    }
+    this.opts.onPath?.(c.path);
+  }
+
+  /** fetch() to the agent. Only the URL's path and query are used. */
+  async fetch(input, init) {
+    return fetchOver(await this.session(), input, init);
+  }
+
+  /** Opens a WebSocket to `path` on the agent. */
+  async websocket(path, protocols = []) {
+    const s = await this.session();
+    const st = s.open('ws', { path, protocols });
+    const meta = await st.accepted;
+    const ws = new WsStream(st);
+    ws.protocol = meta.protocol ?? '';
+    return ws;
+  }
+
+  /** Opens a raw byte stream to a named TCP target on the agent. */
+  async tcp(target = '') {
+    const s = await this.session();
+    const st = s.open('tcp', { target });
+    await st.accepted;
+    return st;
+  }
+
+  /** Opens a stream of your own kind. Resolves after the agent accepts. */
+  async open(kind, meta) {
+    const s = await this.session();
+    const st = s.open(kind, meta);
+    st.acceptMeta = await st.accepted;
+    return st;
+  }
+
+  /** Tries direct candidates now and switches if one answers. */
+  async tryUpgrade() {
+    if (this.path !== 'relay' || !this.direct.length) return false;
+    const { psk } = await this.keys;
+    const ctrl = { done: false };
+    try {
+      const c = await Promise.any(this.direct.map((url) => this._dialOne({ path: 'direct ' + url, url, timeout: this.opts.directTimeoutMs }, psk, ctrl)));
+      ctrl.done = true;
+      this._install(c);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  close() {
+    this.current?.session.close();
+    this.current = null;
+  }
+}
+
+/** Shorthand: new Client(connString, opts). */
+export function connect(connString, opts) {
+  return new Client(connString, opts);
+}

package/src/codes.js

@@ -0,0 +1,63 @@
+// Connect codes, routing tokens and connection strings (spec §1).
+import { b64url, unb64url, hex, enc } from './bytes.js';
+
+const SALT = enc.encode('bolthole/v1');
+const subtle = globalThis.crypto.subtle;
+
+/** A fresh random 32-byte connect code, base64url encoded. */
+export function newCode() {
+  return b64url(crypto.getRandomValues(new Uint8Array(32)));
+}
+
+export function parseCode(s) {
+  const b = unb64url(String(s).trim());
+  if (b.length !== 32) throw new Error('bolthole: a connect code is 43 base64url characters');
+  return b;
+}
+
+async function hkdf(ikm, info, len) {
+  const key = await subtle.importKey('raw', ikm, 'HKDF', false, ['deriveBits']);
+  const bits = await subtle.deriveBits({ name: 'HKDF', hash: 'SHA-256', salt: SALT, info: enc.encode(info) }, key, len * 8);
+  return new Uint8Array(bits);
+}
+
+/** SHA-256 of the routing token, lowercase hex. */
+export async function hashToken(token) {
+  return hex(new Uint8Array(await subtle.digest('SHA-256', enc.encode(token))));
+}
+
+/**
+ * Everything derived from a code.
+ * @param {Uint8Array|string} code
+ * @returns {Promise<{routingToken: string, tokenHash: string, psk: Uint8Array}>}
+ */
+export async function derive(code) {
+  const c = typeof code === 'string' ? parseCode(code) : code;
+  const routingToken = b64url(await hkdf(c, 'routing-token', 24));
+  const psk = await hkdf(c, 'e2e-psk', 32);
+  return { routingToken, tokenHash: await hashToken(routingToken), psk };
+}
+
+/** "https://relay/#k=<code>" */
+export function formatConnString(relay, code) {
+  const u = new URL(relay);
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') throw new Error('bolthole: relay URL must be http(s)');
+  u.hash = '';
+  if (!u.pathname.endsWith('/')) u.pathname += '/';
+  return `${u.toString()}#k=${typeof code === 'string' ? code : b64url(code)}`;
+}
+
+/**
+ * Parses "https://relay/#k=<code>[&name=…]".
+ * @returns {{relay: string, code: Uint8Array, name: string}} relay has no trailing slash.
+ */
+export function parseConnString(s) {
+  const u = new URL(String(s).trim());
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') throw new Error('bolthole: connection string must start with http(s)://');
+  const frag = new URLSearchParams(u.hash.replace(/^#/, ''));
+  const code = parseCode(frag.get('k') || '');
+  u.hash = '';
+  u.search = '';
+  const relay = u.toString().replace(/\/+$/, '');
+  return { relay, code, name: frag.get('name') || '' };
+}

package/src/index.js

@@ -0,0 +1,9 @@
+// bolthole: reach any service from anywhere through a relay that can't read
+// your traffic. This entry point works in browsers, Node 22+, Deno, Bun and
+// Cloudflare Workers.
+export { Client, connect } from './client.js';
+export { Agent, serve } from './agent.js';
+export { newCode, parseCode, derive, hashToken, formatConnString, parseConnString } from './codes.js';
+export { Session, Stream, ResetError, encodeFrame, decodeFrame, T as FrameType } from './mux.js';
+export { WsStream, wsConn, fetchOver, serveHttp, encodeHeaders, decodeHeaders } from './kinds.js';
+export { clientHandshake, agentHandshake, Channel, PROTO_MUX } from './noise.js';