TC-85: tunnel relay -- WS registration, HTTP-over-WS framing, Host routing

Adds the remote-reachability tunnel relay: a node opens one outbound
WebSocket to wss://<host>/v1/tunnel/<name>, authenticates with the same
signed-payload scheme as claim/delete/cert (action: "tunnel", subject
must own <name>, sequence anti-replay -- src/names.ts), and the relay
then proxies inbound HTTPS requests for <name>.tinycloud.link down that
socket as simple JSON request/response frames (src/tunnel/protocol.ts).

- src/tunnel/registry.ts: one live socket per name, newest-wins eviction
  (a fresh registration closes the prior socket with a distinct close
  code rather than rejecting the new connection).
- src/tunnel/proxy.ts: sends request/requestBody frames, demuxes
  response/responseBody/error frames by request id (concurrency-safe,
  many in-flight requests can share one socket), with a timeout.
- src/tunnel/upgrade.ts: the WS handshake -- auth-frame timeout, name
  ownership + signature verification, sequence bump (same
  bump-before-side-effect pattern as the cert flow), ws ping/pong
  heartbeat with dead-peer termination.
- src/tunnel/host-router.ts: Hono middleware that proxies any request
  whose Host header names a claimed tunnel through its socket, and
  leaves the control-plane API's own hostname (api.tinycloud.link)
  untouched. Wired into ServerConfig as an opt-in `tunnelRegistry`
  field -- omitting it (as all existing callers/tests do) leaves /v1
  routing byte-for-byte unchanged.
- src/index.ts: constructs the registry and attaches the WS upgrade
  handler to the same http.Server @hono/node-server returns.

Node-side (Rust client) implementation is out of scope; the wire
protocol in src/tunnel/protocol.ts and the auth/lifecycle rules in
src/tunnel/upgrade.ts are the contract for it (README documents both
precisely). Ingress/TLS wiring for *.tinycloud.link traffic is a
separate, deliberately unresolved question here -- see the README's
"Ingress and TLS for tunnels" section and the follow-up docker-compose
change, neither of which is deployed by this PR.

Author: samgbafa

src/index.ts

@@ -4,6 +4,9 @@ import { DnsO1AcmeIssuer } from "./acme.js";
 import { CloudflareDnsProvider } from "./dns/cloudflare.js";
 import { PostgresAcmeAccountStore, PostgresCertRateLimiter, PostgresNameStore } from "./postgres.js";
 import { createServer } from "./server.js";
+import { DEFAULT_API_HOSTNAME } from "./tunnel/host-router.js";
+import { TunnelRegistry } from "./tunnel/registry.js";
+import { attachTunnelUpgrade } from "./tunnel/upgrade.js";
 
 const port = Number.parseInt(process.env.PORT ?? "3000", 10);
 const databaseUrl = process.env.DATABASE_URL;
@@ -45,15 +48,21 @@ const acmeIssuer = new DnsO1AcmeIssuer({
   dnsProvider,
 });
 
+const tunnelRegistry = new TunnelRegistry();
+const apiHostname = process.env.API_HOSTNAME ?? DEFAULT_API_HOSTNAME;
+
 const app = createServer({
   nameStore,
   dnsProvider,
   acmeIssuer,
   rateLimiter,
   attestationDocument: process.env.ATTESTATION_DOCUMENT,
+  tunnelRegistry,
+  apiHostname,
 });
 
-serve({ fetch: app.fetch, port });
+const server = serve({ fetch: app.fetch, port });
+attachTunnelUpgrade(server, { registry: tunnelRegistry, nameStore });
 console.log(`tinycloud-link listening on :${port}`);
 
 const shutdown = async () => {

src/names.test.ts

@@ -6,14 +6,17 @@ import {
   canonicalCertRequestPayload,
   canonicalClaimPayload,
   canonicalDeletePayload,
+  canonicalTunnelAuthPayload,
   fqdnForName,
   validateCertRequest,
   validateNameClaim,
   validateNameDelete,
   validateNameLabel,
+  validateTunnelAuth,
   verifyCertRequest,
   verifyNameClaim,
   verifyNameDelete,
+  verifyTunnelAuth,
 } from "./names.js";
 import { createTestCsr, createTestEcCsr } from "./test-support/csr.js";
 import { didKeySigner, pkhSigner } from "./test-support/signing.js";
@@ -241,6 +244,53 @@ test("validates and verifies a name delete record", async () => {
   assert.equal(await verifyNameDelete(record), true);
 });
 
+test("validates and verifies a tunnel auth record", async () => {
+  const signer = didKeySigner(40);
+  const unsigned = {
+    version: 1 as const,
+    action: "tunnel" as const,
+    name: "tunnelnode",
+    subject: signer.subject,
+    sequence: 2,
+  };
+  const signature = await signer.sign(canonicalTunnelAuthPayload(unsigned));
+  const record = { ...unsigned, signature };
+
+  assert.deepEqual(validateTunnelAuth(record), record);
+  assert.equal(await verifyTunnelAuth(record), true);
+});
+
+test("rejects a tunnel auth record signed by the wrong key", async () => {
+  const signer = didKeySigner(41);
+  const other = didKeySigner(42);
+  const unsigned = {
+    version: 1 as const,
+    action: "tunnel" as const,
+    name: "tunnelnode",
+    subject: signer.subject,
+    sequence: 2,
+  };
+  const signature = await other.sign(canonicalTunnelAuthPayload(unsigned));
+  const record = { ...unsigned, signature };
+
+  assert.equal(await verifyTunnelAuth(record), false);
+});
+
+test("rejects a tunnel auth record with the wrong action", () => {
+  assert.throws(
+    () =>
+      validateTunnelAuth({
+        version: 1,
+        action: "claim",
+        name: "tunnelnode",
+        subject: didKeySigner(43).subject,
+        sequence: 1,
+        signature: "x",
+      }),
+    NameError
+  );
+});
+
 test("validates and verifies a cert request record", async () => {
   const signer = didKeySigner(13);
   const domain = fqdnForName("certnode");

src/names.ts

@@ -9,6 +9,17 @@ export function fqdnForName(name: string): string {
   return `${name}.${DOMAIN_SUFFIX}`;
 }
 
+// The tunnel relay's namespace: <name>.tinycloud.link (the public apex zone,
+// not the LAN-only local.tinycloud.link zone above). A name claimed via
+// PUT /v1/names/:name is the same name a subject can open a tunnel for --
+// there is one name registry, two surfaces (LAN A/AAAA records vs. a remote
+// WebSocket tunnel).
+export const REMOTE_DOMAIN_SUFFIX = "tinycloud.link";
+
+export function remoteFqdnForName(name: string): string {
+  return `${name}.${REMOTE_DOMAIN_SUFFIX}`;
+}
+
 const NAME_LABEL_PATTERN = /^[a-z0-9]([a-z0-9-]{1,30}[a-z0-9])?$/;
 
 // Reserved so a claimed name can never collide with infrastructure, the
@@ -209,6 +220,61 @@ export async function verifyNameDelete(record: NameDeleteRecord): Promise<boolea
   return verifySignedPayload(record.subject, canonicalDeletePayload(record), record.signature);
 }
 
+// --- tunnel registration (first frame sent over wss://.../v1/tunnel/:name) ---
+//
+// Same signed-payload scheme as claim/delete/cert above: the node proves it
+// owns `name` (already claimed via PUT /v1/names/:name) with a signature
+// over a canonical payload and a strictly-increasing sequence, reusing the
+// name record's own sequence counter for replay protection.
+
+export interface TunnelAuthPayload {
+  version: 1;
+  action: "tunnel";
+  name: string;
+  subject: string;
+  sequence: number;
+}
+
+export interface TunnelAuthRecord extends TunnelAuthPayload {
+  signature: string;
+}
+
+export function canonicalTunnelAuthPayload(payload: TunnelAuthPayload): string {
+  return JSON.stringify({
+    version: payload.version,
+    action: payload.action,
+    name: payload.name,
+    subject: payload.subject,
+    sequence: payload.sequence,
+  });
+}
+
+export function validateTunnelAuth(input: unknown): TunnelAuthRecord {
+  if (input === null || typeof input !== "object") {
+    throw new NameError("body must be an object");
+  }
+  const body = input as Partial<TunnelAuthRecord>;
+  if (body.version !== 1) {
+    throw new NameError("version must be 1");
+  }
+  if (body.action !== "tunnel") {
+    throw new NameError('action must be "tunnel"');
+  }
+
+  return {
+    version: 1,
+    action: "tunnel",
+    name: validateNameLabel(body.name),
+    subject: validateSubject(body.subject),
+    sequence: validateSequence(body.sequence),
+    signature: validateSignature(body.signature),
+  };
+}
+
+export async function verifyTunnelAuth(record: TunnelAuthRecord): Promise<boolean> {
+  return verifySignedPayload(record.subject, canonicalTunnelAuthPayload(record), record.signature);
+}
+
 // --- cert request (POST /v1/certs/:name) ---
 
 export interface CertRequestPayload {

src/server.ts

@@ -14,6 +14,8 @@ import {
   verifyNameDelete,
 } from "./names.js";
 import type { CertRateLimiter, NameStore } from "./storage.js";
+import { DEFAULT_API_HOSTNAME, createTunnelMiddleware } from "./tunnel/host-router.js";
+import type { TunnelRegistry } from "./tunnel/registry.js";
 
 const DAY_MS = 24 * 60 * 60 * 1000;
 
@@ -25,6 +27,10 @@ export interface ServerConfig {
   attestationDocument?: string;
   certRateLimitPerDay?: number;
   nameUpdateRateLimitPerDay?: number;
+  /** When set, requests whose Host header names a claimed tunnel (rather than `apiHostname`) are proxied through it. Omit to leave tunnel routing disabled entirely (no behavior change to the /v1 API). */
+  tunnelRegistry?: TunnelRegistry;
+  /** The control-plane API's own hostname, exempted from tunnel routing. Defaults to "api.tinycloud.link". */
+  apiHostname?: string;
 }
 
 // Prefixes name-update entries so they share the cert rate-limit store without
@@ -38,6 +44,15 @@ export function createServer(config: ServerConfig): Hono {
   const rateLimit = config.certRateLimitPerDay ?? 5;
   const nameUpdateRateLimit = config.nameUpdateRateLimitPerDay ?? 30;
 
+  if (config.tunnelRegistry) {
+    app.use(
+      "*",
+      createTunnelMiddleware(config.tunnelRegistry, {
+        apiHostname: config.apiHostname ?? DEFAULT_API_HOSTNAME,
+      })
+    );
+  }
+
   app.get("/health", (c) => c.json({ ok: true }));
 
   app.get("/attestation", (c) => {