@agentproto/pairing-host 0.1.0

package/dist/index.mjs

@@ -0,0 +1,874 @@
+import { randomBytes, timingSafeEqual, createHmac } from 'crypto';
+import { readFile, stat, mkdir, writeFile, chmod, rename } from 'fs/promises';
+import { homedir } from 'os';
+import { join, dirname, basename } from 'path';
+import { wrapWebSocket, createTunnelServer, DEFAULT_HTTP_FORWARD_TIMEOUT_MS, daemonHandshakeOverSink } from '@agentproto/acp/tunnel';
+import { PairingError, deriveOfferTokens, encodeOfferUrl, OFFER_VERSION, currentEpoch, deriveEpochTokens, HOSTED_RENDEZVOUS_URL, decodePairingHello, respondToLegacyHandshake, respondToHandshake, encodePairingMessage, PAIRING_PROTOCOL_OUTDATED_MESSAGE, derivePairRoot } from '@agentproto/secrets/pairing';
+import { identityFingerprint } from '@agentproto/secrets/identity';
+import WebSocket from 'ws';
+
+/**
+ * @agentproto/pairing-host
+ * Host side of AIP-59 pairing as a library (registry, rendezvous dialer,
+ * loopback HTTP forwarder, local-device bearer).
+ */
+
+
+// src/reconnect-log-gate.ts
+function createReconnectLogGate(opts = {}) {
+  const windowMs = opts.windowMs ?? 6e4;
+  const now = opts.now ?? Date.now;
+  const state = /* @__PURE__ */ new Map();
+  return {
+    onFailure(key, message) {
+      const ts = now();
+      const prev = state.get(key);
+      if (prev && ts - prev.lastLoggedAt < windowMs) {
+        prev.suppressed += 1;
+        return null;
+      }
+      const suffix = prev && prev.suppressed > 0 ? ` (${prev.suppressed} failure${prev.suppressed === 1 ? "" : "s"} suppressed)` : "";
+      state.set(key, { lastLoggedAt: ts, suppressed: 0 });
+      return `${message}${suffix}`;
+    },
+    onSuccess(key) {
+      state.delete(key);
+    }
+  };
+}
+var LOCAL_BEARER_PREFIX = "apd1";
+var MAC_CONTEXT = "agentproto/local-device/v1|";
+function newLocalDevice(name, createdAt) {
+  return {
+    fingerprint: randomBytes(16).toString("hex"),
+    name,
+    createdAt,
+    secret: randomBytes(32).toString("base64url")
+  };
+}
+function macOf(rec) {
+  return createHmac("sha256", Buffer.from(rec.secret, "base64url")).update(MAC_CONTEXT + rec.fingerprint, "utf8").digest();
+}
+function deriveLocalBearer(rec) {
+  return `${LOCAL_BEARER_PREFIX}.${rec.fingerprint}.${macOf(rec).toString("base64url")}`;
+}
+function parseLocalBearer(bearer) {
+  if (typeof bearer !== "string" || bearer.length > 256) return null;
+  const parts = bearer.split(".");
+  if (parts.length !== 3 || parts[0] !== LOCAL_BEARER_PREFIX) return null;
+  const [, fingerprint, mac] = parts;
+  if (!/^[0-9a-f]{32}$/.test(fingerprint) || !/^[A-Za-z0-9_-]+$/.test(mac)) return null;
+  return { fingerprint, mac };
+}
+function verifyLocalBearer(rec, parsed) {
+  const target = rec ?? { fingerprint: "0".repeat(32), secret: randomBytes(32).toString("base64url") };
+  const expected = macOf(target).toString("base64url");
+  const presented = parsed?.mac ?? "";
+  const sameLength = presented.length === expected.length;
+  const equal = timingSafeEqual(
+    Buffer.from(expected),
+    Buffer.from(sameLength ? presented : "0".repeat(expected.length))
+  );
+  return Boolean(rec) && parsed !== null && sameLength && equal;
+}
+function isLocalDeviceRecord(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const r = v;
+  return typeof r["fingerprint"] === "string" && /^[0-9a-f]{32}$/.test(r["fingerprint"]) && typeof r["name"] === "string" && typeof r["createdAt"] === "string" && typeof r["secret"] === "string" && r["secret"].length > 0;
+}
+
+// src/pairing-registry.ts
+var PAIRINGS_VERSION = 2;
+var LEGACY_PAIRINGS_VERSION = 1;
+var PAIRING_REVOKED_CODE = "pairing_revoked";
+function revokedFrame() {
+  return {
+    t: "error",
+    code: PAIRING_REVOKED_CODE,
+    message: "this device was unpaired from the daemon (agentproto pair revoke); pair again with a new offer"
+  };
+}
+var DEFAULT_TTL_MS = 10 * 6e4;
+var DEFAULT_RECONNECT_MIN_MS = 1e3;
+var DEFAULT_RECONNECT_MAX_MS = 3e4;
+var DEFAULT_HANDSHAKE_TIMEOUT_MS = 11e4;
+var DEFAULT_REVOKED_GRACE_MS = 14 * 864e5;
+function defaultPairingsPath() {
+  return join(homedir(), ".agentproto", "pairings.json");
+}
+async function readPairingsSnapshot(path) {
+  try {
+    const raw = await readFile(path ?? defaultPairingsPath(), "utf8");
+    const parsed = JSON.parse(raw);
+    if (!isPairingsFile(parsed)) return [];
+    const fromV1 = parsed.v === LEGACY_PAIRINGS_VERSION;
+    return parsed.pairings.map((rec) => fromV1 ? { ...rec, legacy: true } : rec);
+  } catch {
+    return [];
+  }
+}
+function b64url(bytes) {
+  return bytes.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function constantTimeEqual(a, b) {
+  const key = randomBytes(32);
+  const da = createHmac("sha256", key).update(a, "utf8").digest();
+  const db = createHmac("sha256", key).update(b, "utf8").digest();
+  return timingSafeEqual(da, db);
+}
+var OUTDATED_HELLO_VERSION = `pair/v2 required \u2014 ${PAIRING_PROTOCOL_OUTDATED_MESSAGE}`;
+function createPairingRegistry(deps) {
+  const pairingsPath = deps.pairingsPath ?? defaultPairingsPath();
+  const now = deps.now ?? Date.now;
+  const log = deps.log ?? (() => {
+  });
+  const reconnectMinMs = deps.reconnectMinMs ?? DEFAULT_RECONNECT_MIN_MS;
+  const reconnectMaxMs = deps.reconnectMaxMs ?? DEFAULT_RECONNECT_MAX_MS;
+  const handshakeTimeoutMs = deps.handshakeTimeoutMs ?? DEFAULT_HANDSHAKE_TIMEOUT_MS;
+  const revokedGraceMs = deps.revokedGraceMs ?? DEFAULT_REVOKED_GRACE_MS;
+  const dialFailureGate = createReconnectLogGate({ now });
+  const pairings = /* @__PURE__ */ new Map();
+  const onlineCounts = /* @__PURE__ */ new Map();
+  const revoked = /* @__PURE__ */ new Map();
+  const offers = /* @__PURE__ */ new Map();
+  const loops = /* @__PURE__ */ new Map();
+  const channels = /* @__PURE__ */ new Set();
+  const localDevices = /* @__PURE__ */ new Map();
+  let fileSig = "";
+  let shuttingDown = false;
+  async function sigOfFile() {
+    try {
+      const st = await stat(pairingsPath);
+      return `${st.mtimeMs}:${st.size}:${st.ino}`;
+    } catch (err) {
+      if (isEnoent(err)) return null;
+      throw err;
+    }
+  }
+  function replaceLocalDevices(records) {
+    localDevices.clear();
+    if (!Array.isArray(records)) return;
+    for (const rec of records) if (isLocalDeviceRecord(rec)) localDevices.set(rec.fingerprint, rec);
+  }
+  async function refreshLocalDevices() {
+    let sig;
+    try {
+      sig = await sigOfFile();
+    } catch {
+      return;
+    }
+    if (sig === null) {
+      localDevices.clear();
+      fileSig = "";
+      return;
+    }
+    if (sig === fileSig) return;
+    try {
+      const parsed = JSON.parse(await readFile(pairingsPath, "utf8"));
+      if (isPairingsFile(parsed)) {
+        replaceLocalDevices(parsed.localDevices);
+        fileSig = sig;
+      }
+    } catch {
+    }
+  }
+  let loadPromise = null;
+  function ensureLoaded() {
+    loadPromise ??= doLoad();
+    return loadPromise;
+  }
+  async function doLoad() {
+    try {
+      const sig = await sigOfFile();
+      const raw = await readFile(pairingsPath, "utf8");
+      const parsed = JSON.parse(raw);
+      if (isPairingsFile(parsed)) {
+        if (sig !== null) fileSig = sig;
+        replaceLocalDevices(parsed.localDevices);
+        const fromV1 = parsed.v === LEGACY_PAIRINGS_VERSION;
+        for (const rec of parsed.pairings) {
+          pairings.set(rec.fingerprint, fromV1 ? { ...rec, legacy: true } : rec);
+        }
+        for (const rec of parsed.revoked ?? []) {
+          if (isRevokedRecord(rec) && tombstoneLive(rec)) revoked.set(rec.fingerprint, rec);
+        }
+        const legacy = Array.from(pairings.values()).filter((r) => r.legacy);
+        if (legacy.length > 0) {
+          log(
+            `[pairing] ${legacy.length} pairing(s) in ${pairingsPath} use the retired pair/v1 protocol and will not be served (${legacy.map((r) => r.name).join(", ")}). Re-pair each client \u2014 run \`agentproto pair offer\` \u2014 then \`agentproto pair revoke <name>\` the legacy entry.`
+          );
+        }
+      } else {
+        log(`[pairing] ignoring ${pairingsPath}: unrecognised format`);
+      }
+    } catch (err) {
+      if (!isEnoent(err)) {
+        log(`[pairing] could not read ${pairingsPath}: ${errMsg(err)}`);
+      }
+    }
+  }
+  let persistChain = Promise.resolve();
+  function persist() {
+    const run = persistChain.then(() => doPersist());
+    persistChain = run.catch(() => {
+    });
+    return run;
+  }
+  function mutateLocal(apply) {
+    const run = persistChain.then(async () => {
+      await refreshLocalDevices();
+      apply();
+      await doPersist(false);
+    });
+    persistChain = run.catch(() => {
+    });
+    return run;
+  }
+  async function doPersist(refresh = true) {
+    if (refresh) await refreshLocalDevices();
+    for (const [fp, rec] of revoked) if (!tombstoneLive(rec)) revoked.delete(fp);
+    const file = {
+      v: PAIRINGS_VERSION,
+      pairings: Array.from(pairings.values()),
+      ...revoked.size > 0 ? { revoked: Array.from(revoked.values()) } : {},
+      ...localDevices.size > 0 ? { localDevices: Array.from(localDevices.values()) } : {}
+    };
+    const dir = dirname(pairingsPath);
+    await mkdir(dir, { recursive: true });
+    const tmp = join(dir, `.${basename(pairingsPath)}.tmp-${process.pid}`);
+    await writeFile(tmp, JSON.stringify(file, null, 2) + "\n", { encoding: "utf8", mode: 384 });
+    await chmod(tmp, 384).catch(() => {
+    });
+    await rename(tmp, pairingsPath);
+    fileSig = await sigOfFile() ?? "";
+  }
+  function startLoop(spec) {
+    if (loops.has(spec.key)) return;
+    const abort = new AbortController();
+    const done = runLoop(spec, abort.signal).catch((err) => {
+      log(`[pairing] loop ${spec.key} ended: ${errMsg(err)}`);
+    });
+    loops.set(spec.key, { abort, done });
+  }
+  async function stopLoop(key, reason) {
+    const loop = loops.get(key);
+    if (!loop) return;
+    loops.delete(key);
+    loop.abort.abort(reason);
+    await loop.done.catch(() => {
+    });
+  }
+  async function runLoop(spec, signal) {
+    let backoff = reconnectMinMs;
+    while (!signal.aborted && spec.shouldContinue()) {
+      const expected = await spec.tokens();
+      let sink;
+      try {
+        sink = await deps.dial(dialUrl(spec.rendezvousUrl, expected.route), signal);
+      } catch (err) {
+        if (signal.aborted) break;
+        const line = dialFailureGate.onFailure(
+          spec.key,
+          `[pairing] dial ${spec.key} failed: ${errMsg(err)}`
+        );
+        if (line) log(line);
+        await sleep(backoff, signal);
+        backoff = Math.min(backoff * 2, reconnectMaxMs);
+        continue;
+      }
+      if (!sink.isOpen) {
+        if (signal.aborted) break;
+        await sleep(backoff, signal);
+        backoff = Math.min(backoff * 2, reconnectMaxMs);
+        continue;
+      }
+      dialFailureGate.onSuccess(spec.key);
+      let serving = false;
+      const onAbort = () => {
+        if (serving && signal.reason === REVOKED) return;
+        try {
+          sink.close("registry shutdown");
+        } catch {
+        }
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+      try {
+        let capturedSession = null;
+        let capturedHello = null;
+        let legacyPeer = false;
+        let wrapped;
+        try {
+          const identity = await deps.loadIdentity();
+          wrapped = await daemonHandshakeOverSink(
+            sink,
+            async (helloBytes) => {
+              let hello;
+              try {
+                hello = decodePairingHello(helloBytes);
+              } catch (err) {
+                if (!(err instanceof PairingError) || err.code !== "pairing_protocol_outdated") throw err;
+                legacyPeer = true;
+                return respondToLegacyHandshake(helloBytes, identity);
+              }
+              const result = await respondToHandshake(hello, {
+                identity,
+                verifyAuthToken: (presented) => spec.verify(presented, expected)
+              });
+              capturedSession = result.session;
+              capturedHello = hello;
+              return { reply: encodePairingMessage(result.reply), keys: result.session };
+            },
+            { timeoutMs: handshakeTimeoutMs }
+          );
+        } catch (err) {
+          if (signal.aborted) break;
+          void err;
+          await sleep(backoff, signal);
+          backoff = Math.min(backoff * 2, reconnectMaxMs);
+          continue;
+        }
+        if (legacyPeer) {
+          sendOutdatedNotice(wrapped);
+          log(`[pairing] told a pair/v1 client on ${spec.key} to re-pair`);
+          await sleep(backoff, signal);
+          backoff = Math.min(backoff * 2, reconnectMaxMs);
+          continue;
+        }
+        backoff = reconnectMinMs;
+        if (!capturedSession || !capturedHello) {
+          wrapped.close("internal: missing session");
+          continue;
+        }
+        if (spec.reject) {
+          wrapped.send(spec.reject);
+          wrapped.close(spec.reject.code);
+          log(`[pairing] refused revoked pairing via ${spec.key}`);
+          continue;
+        }
+        let ctx;
+        try {
+          ctx = await spec.onPaired(capturedSession, capturedHello);
+        } catch (err) {
+          log(`[pairing] persist for ${spec.key} failed: ${errMsg(err)}`);
+          wrapped.close("persist failed");
+          continue;
+        }
+        serving = true;
+        const handle = deps.serve(wrapped, ctx);
+        channels.add(handle);
+        onlineCounts.set(ctx.fingerprint, (onlineCounts.get(ctx.fingerprint) ?? 0) + 1);
+        log(`[pairing] channel up (${ctx.mode}) for ${ctx.fingerprint} via ${spec.key}`);
+        await waitClosed(wrapped, signal);
+        channels.delete(handle);
+        await handle.close().catch(() => {
+        });
+        const remaining = (onlineCounts.get(ctx.fingerprint) ?? 1) - 1;
+        if (remaining > 0) onlineCounts.set(ctx.fingerprint, remaining);
+        else onlineCounts.delete(ctx.fingerprint);
+        log(`[pairing] channel closed (${ctx.mode}) for ${ctx.fingerprint}`);
+        if (spec.singleUse) break;
+      } finally {
+        signal.removeEventListener("abort", onAbort);
+      }
+    }
+  }
+  async function createOffer(input = {}) {
+    await ensureLoaded();
+    let rendezvousUrl;
+    let rendezvousIsHostedDefault = false;
+    if (input.rendezvousUrl) {
+      rendezvousUrl = input.rendezvousUrl;
+    } else if (deps.defaultRendezvousUrl !== void 0) {
+      if (deps.defaultRendezvousUrl === "") {
+        throw new PairingError(
+          "malformed_offer",
+          'rendezvous disabled \u2014 pairing.rendezvous is set to "" (explicit opt-out); pass --rendezvous to route this offer through a specific broker'
+        );
+      }
+      rendezvousUrl = deps.defaultRendezvousUrl;
+    } else {
+      rendezvousUrl = HOSTED_RENDEZVOUS_URL;
+      rendezvousIsHostedDefault = true;
+    }
+    const identity = await deps.loadIdentity();
+    const secret = b64url(randomBytes(16));
+    const { route, auth } = await deriveOfferTokens(secret);
+    const ttlMs = input.ttlMs ?? DEFAULT_TTL_MS;
+    const exp = Math.floor((now() + ttlMs) / 1e3);
+    const scope = input.scope;
+    offers.set(route, { route, auth, exp, spent: false, rendezvousUrl, ...scope ? { scope } : {} });
+    const fingerprint = await identityFingerprint(identity.x25519.pub);
+    const url = encodeOfferUrl({
+      v: OFFER_VERSION,
+      rendezvousUrl,
+      fingerprint,
+      daemonX25519Pub: identity.x25519.pub,
+      daemonEd25519Pub: identity.ed25519.pub,
+      secret,
+      exp,
+      ...scope ? { scope } : {}
+    });
+    startOfferLoop({ route, auth }, rendezvousUrl);
+    log(
+      `[pairing] offer minted (exp ${new Date(exp * 1e3).toISOString()}) via ${rendezvousUrl}` + (rendezvousIsHostedDefault ? " (hosted default)" : "") + (scope === "host" ? " [HOST-SCOPED]" : "")
+    );
+    return { secret, exp, url, fingerprint, rendezvousUrl, rendezvousIsHostedDefault, ...scope ? { scope } : {} };
+  }
+  function offerValid(route) {
+    const entry = offers.get(route);
+    return !!entry && !entry.spent && entry.exp * 1e3 > now();
+  }
+  function startOfferLoop(tokens, rendezvousUrl) {
+    const { route } = tokens;
+    startLoop({
+      key: `offer:${route}`,
+      rendezvousUrl,
+      tokens: () => tokens,
+      shouldContinue: () => offerValid(route),
+      singleUse: true,
+      verify: (presented) => {
+        const entry = offers.get(route);
+        if (!entry || entry.spent || entry.exp * 1e3 <= now()) return false;
+        if (!constantTimeEqual(presented, entry.auth)) return false;
+        entry.spent = true;
+        return true;
+      },
+      onPaired: async (session, hello) => {
+        const pairRoot = await derivePairRoot(session);
+        const fingerprint = session.peerFingerprint;
+        const nowIso = new Date(now()).toISOString();
+        const entry = offers.get(route);
+        const record = {
+          clientPub: hello.ePub,
+          name: session.clientName ?? fingerprint,
+          fingerprint,
+          createdAt: pairings.get(fingerprint)?.createdAt ?? nowIso,
+          lastSeen: nowIso,
+          pairRoot,
+          rendezvousUrl,
+          ...entry?.scope ? { scope: entry.scope } : {}
+        };
+        pairings.set(fingerprint, record);
+        revoked.delete(fingerprint);
+        await persist();
+        startReconnectLoops(record);
+        return { mode: "offer", fingerprint, name: record.name, ...record.scope ? { scope: record.scope } : {} };
+      }
+    });
+  }
+  function startReconnectLoops(record) {
+    for (const slot of ["cur", "prev"]) {
+      const epochOf = () => slot === "cur" ? currentEpoch(now()) : currentEpoch(now()) - 1;
+      startLoop({
+        key: `pair:${record.fingerprint}:${slot}`,
+        rendezvousUrl: record.rendezvousUrl,
+        tokens: () => deriveEpochTokens(record.pairRoot, epochOf()),
+        shouldContinue: () => pairings.has(record.fingerprint),
+        singleUse: false,
+        // A legacy (v1) pairing is parked on only so its client can be told to
+        // re-pair; it never authenticates, whatever it presents.
+        verify: (presented, expected) => !record.legacy && constantTimeEqual(presented, expected.auth),
+        onPaired: async (session, _hello) => {
+          const existing = pairings.get(record.fingerprint);
+          if (existing) {
+            existing.lastSeen = new Date(now()).toISOString();
+            await persist().catch((err) => log(`[pairing] lastSeen persist failed: ${errMsg(err)}`));
+          }
+          return {
+            mode: "reconnect",
+            fingerprint: record.fingerprint,
+            name: existing?.name ?? record.name,
+            ...record.scope ? { scope: record.scope } : {}
+          };
+        }
+      });
+    }
+  }
+  function startTombstoneLoops(rec) {
+    for (const slot of ["cur", "prev"]) {
+      const epochOf = () => slot === "cur" ? currentEpoch(now()) : currentEpoch(now()) - 1;
+      const tokensFor = () => rec.routes.find((r) => r.epoch === epochOf());
+      startLoop({
+        key: `revoked:${rec.fingerprint}:${slot}`,
+        rendezvousUrl: rec.rendezvousUrl,
+        tokens: () => tokensFor() ?? { route: "", auth: "" },
+        shouldContinue: () => revoked.get(rec.fingerprint) === rec && tombstoneLive(rec) && tokensFor() !== void 0,
+        singleUse: false,
+        // The AUTH token, never the route: the broker knows every route, and a
+        // tombstone must not become a way for it to probe revocation state.
+        verify: (presented, expected) => expected.auth !== "" && constantTimeEqual(presented, expected.auth),
+        reject: revokedFrame(),
+        onPaired: async () => {
+          throw new Error("unreachable: a tombstone never serves");
+        }
+      });
+    }
+  }
+  function tombstoneLive(rec) {
+    return Date.parse(rec.expiresAt) > now();
+  }
+  async function startAutoconnect() {
+    await ensureLoaded();
+    for (const record of pairings.values()) {
+      startReconnectLoops(record);
+    }
+    for (const rec of revoked.values()) {
+      startTombstoneLoops(rec);
+    }
+    if (pairings.size > 0) {
+      log(`[pairing] autoconnect: standing connections for ${pairings.size} pairing(s)`);
+    }
+  }
+  async function revoke(idOrName) {
+    await ensureLoaded();
+    let target = pairings.get(idOrName);
+    if (!target) {
+      for (const rec of pairings.values()) {
+        if (rec.name === idOrName) {
+          target = rec;
+          break;
+        }
+      }
+    }
+    if (!target) {
+      await refreshLocalDevices();
+      const device = findLocalDevice(idOrName);
+      if (!device) return false;
+      await mutateLocal(() => void localDevices.delete(device.fingerprint));
+      log(`[pairing] revoked local device ${device.fingerprint} (${device.name})`);
+      return true;
+    }
+    pairings.delete(target.fingerprint);
+    let tombstone = null;
+    if (revokedGraceMs > 0 && !target.legacy) {
+      const at = now();
+      const expiresAt = at + revokedGraceMs;
+      const routes = [];
+      for (let e = currentEpoch(at) - 1; e <= currentEpoch(expiresAt); e++) {
+        routes.push({ epoch: e, ...await deriveEpochTokens(target.pairRoot, e) });
+      }
+      tombstone = {
+        fingerprint: target.fingerprint,
+        name: target.name,
+        rendezvousUrl: target.rendezvousUrl,
+        revokedAt: new Date(at).toISOString(),
+        expiresAt: new Date(expiresAt).toISOString(),
+        routes
+      };
+      revoked.set(target.fingerprint, tombstone);
+    }
+    await persist();
+    await stopLoop(`pair:${target.fingerprint}:cur`, REVOKED);
+    await stopLoop(`pair:${target.fingerprint}:prev`, REVOKED);
+    if (tombstone) startTombstoneLoops(tombstone);
+    log(`[pairing] revoked ${target.fingerprint} (${target.name})`);
+    return true;
+  }
+  async function list() {
+    await ensureLoaded();
+    await refreshLocalDevices();
+    return [
+      ...Array.from(pairings.values()).map((r) => ({ ...r })),
+      ...Array.from(localDevices.values()).map(localDeviceView)
+    ];
+  }
+  function findLocalDevice(idOrName) {
+    const byFp = localDevices.get(idOrName);
+    if (byFp) return byFp;
+    for (const rec of localDevices.values()) if (rec.name === idOrName) return rec;
+    return void 0;
+  }
+  function localDeviceView(rec) {
+    return {
+      clientPub: "",
+      name: rec.name,
+      fingerprint: rec.fingerprint,
+      createdAt: rec.createdAt,
+      lastSeen: rec.createdAt,
+      pairRoot: "",
+      rendezvousUrl: "",
+      local: true
+    };
+  }
+  async function mintLocalDevice(input) {
+    const name = input.name.trim();
+    if (!name) throw new Error("device name must not be empty");
+    await ensureLoaded();
+    const rec = newLocalDevice(name, new Date(now()).toISOString());
+    await mutateLocal(() => void localDevices.set(rec.fingerprint, rec));
+    log(`[pairing] minted local device ${rec.fingerprint} (${rec.name})`);
+    return {
+      bearer: deriveLocalBearer(rec),
+      fingerprint: rec.fingerprint,
+      name: rec.name,
+      createdAt: rec.createdAt
+    };
+  }
+  async function verifyDeviceBearer(bearer) {
+    await ensureLoaded();
+    await refreshLocalDevices();
+    const parsed = parseLocalBearer(bearer);
+    const rec = parsed ? localDevices.get(parsed.fingerprint) : void 0;
+    return verifyLocalBearer(rec, parsed) && rec ? { fingerprint: rec.fingerprint, name: rec.name } : null;
+  }
+  async function renamePairing(idOrName, newName) {
+    const trimmed = newName.trim();
+    if (!trimmed) throw new Error("device name must not be empty");
+    await ensureLoaded();
+    let target = pairings.get(idOrName);
+    if (!target) {
+      for (const rec of pairings.values()) {
+        if (rec.name === idOrName) {
+          target = rec;
+          break;
+        }
+      }
+    }
+    if (!target) {
+      await refreshLocalDevices();
+      const device = findLocalDevice(idOrName);
+      if (!device) return false;
+      await mutateLocal(() => {
+        const current = localDevices.get(device.fingerprint);
+        if (current) current.name = trimmed;
+      });
+      log(`[pairing] renamed ${device.fingerprint} to "${trimmed}"`);
+      return true;
+    }
+    target.name = trimmed;
+    await persist();
+    log(`[pairing] renamed ${target.fingerprint} to "${trimmed}"`);
+    return true;
+  }
+  function isOnline(fingerprint) {
+    return (onlineCounts.get(fingerprint) ?? 0) > 0;
+  }
+  async function shutdown() {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    for (const key of Array.from(loops.keys())) {
+      await stopLoop(key);
+    }
+    for (const handle of Array.from(channels)) {
+      await handle.close().catch(() => {
+      });
+    }
+    channels.clear();
+  }
+  return {
+    createOffer,
+    list,
+    rename: renamePairing,
+    revoke,
+    isOnline,
+    startAutoconnect,
+    shutdown,
+    mintLocalDevice,
+    verifyDeviceBearer
+  };
+}
+function dialUrl(rendezvousUrl, token) {
+  const sep = rendezvousUrl.includes("?") ? "&" : "?";
+  return `${rendezvousUrl}${sep}side=daemon&t=${encodeURIComponent(token)}`;
+}
+function sendOutdatedNotice(sink) {
+  sink.send({ t: "error", code: "pairing_protocol_outdated", message: PAIRING_PROTOCOL_OUTDATED_MESSAGE });
+  sink.send({
+    t: "hello",
+    // Deliberately not TUNNEL_VERSION: a v1 client reports an unknown version
+    // verbatim, which is how the notice reaches its user (see
+    // OUTDATED_HELLO_VERSION).
+    version: OUTDATED_HELLO_VERSION,
+    capabilities: { pty: false },
+    label: "pairing_protocol_outdated"
+  });
+  sink.close("pairing_protocol_outdated");
+}
+var REVOKED = /* @__PURE__ */ Symbol("pairing revoked");
+function waitClosed(sink, signal) {
+  return new Promise((resolve) => {
+    if (!sink.isOpen) {
+      resolve();
+      return;
+    }
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      resolve();
+    };
+    sink.onClose(() => finish());
+    signal.addEventListener("abort", () => {
+      if (signal.reason === REVOKED) {
+        sink.send(revokedFrame());
+        sink.close(PAIRING_REVOKED_CODE);
+      } else {
+        sink.close("registry shutdown");
+      }
+      finish();
+    });
+  });
+}
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    if (signal.aborted) return resolve();
+    const timer = setTimeout(resolve, ms);
+    if (typeof timer.unref === "function") timer.unref();
+    signal.addEventListener("abort", () => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+}
+function isPairingsFile(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const rec = v;
+  if (rec["v"] !== PAIRINGS_VERSION && rec["v"] !== LEGACY_PAIRINGS_VERSION) return false;
+  if (!Array.isArray(rec["pairings"])) return false;
+  return rec["pairings"].every(isPairingRecord);
+}
+function isPairingRecord(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const r = v;
+  return typeof r["clientPub"] === "string" && typeof r["name"] === "string" && typeof r["fingerprint"] === "string" && typeof r["createdAt"] === "string" && typeof r["lastSeen"] === "string" && typeof r["pairRoot"] === "string" && typeof r["rendezvousUrl"] === "string";
+}
+function isRevokedRecord(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const r = v;
+  return typeof r["fingerprint"] === "string" && typeof r["name"] === "string" && typeof r["rendezvousUrl"] === "string" && typeof r["revokedAt"] === "string" && typeof r["expiresAt"] === "string" && Array.isArray(r["routes"]) && r["routes"].every((x) => {
+    if (typeof x !== "object" || x === null) return false;
+    const t = x;
+    return typeof t["epoch"] === "number" && typeof t["route"] === "string" && typeof t["auth"] === "string";
+  });
+}
+function isEnoent(err) {
+  return typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT";
+}
+function errMsg(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+async function dialRendezvous(url, signal, opts = {}) {
+  const ws = new WebSocket(url, opts.agent ? { agent: opts.agent } : void 0);
+  await new Promise((resolve, reject) => {
+    const cleanup = () => {
+      ws.off("open", onOpen);
+      ws.off("error", onError);
+      signal.removeEventListener("abort", onAbort);
+    };
+    const onOpen = () => {
+      cleanup();
+      resolve();
+    };
+    const onError = (err) => {
+      cleanup();
+      reject(err);
+    };
+    const onAbort = () => {
+      cleanup();
+      try {
+        ws.close();
+      } catch {
+      }
+      reject(new Error("dial aborted"));
+    };
+    if (signal.aborted) {
+      onAbort();
+      return;
+    }
+    ws.once("open", onOpen);
+    ws.once("error", onError);
+    signal.addEventListener("abort", onAbort);
+  });
+  return wrapWebSocket(ws);
+}
+var LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+function isLoopback(url) {
+  return LOOPBACK_HOSTS.has(url.hostname) || /^127\.\d+\.\d+\.\d+$/.test(url.hostname);
+}
+function safePathname(path) {
+  if (!path.startsWith("/") || path.startsWith("//") || path.includes("\\")) return null;
+  if (/%2e|%2f|%5c/i.test(path)) return null;
+  const end = path.search(/[?#]/);
+  return end === -1 ? path : path.slice(0, end);
+}
+function pathAllowed(pathname, allow) {
+  return allow.some((rule) => {
+    if (rule instanceof RegExp) {
+      rule.lastIndex = 0;
+      return rule.test(pathname);
+    }
+    if (rule.endsWith("/*")) {
+      const base = rule.slice(0, -2);
+      return pathname === base || pathname.startsWith(`${base}/`);
+    }
+    return pathname === rule;
+  });
+}
+function serveLoopbackHttp(opts) {
+  const target = typeof opts.target === "string" ? new URL(opts.target) : opts.target;
+  if (target.protocol !== "http:" && target.protocol !== "https:") {
+    throw new Error(`serveLoopbackHttp: target must be http(s), got ${target.protocol}`);
+  }
+  if (!isLoopback(target)) {
+    throw new Error(`serveLoopbackHttp: target must be a loopback address, got ${target.hostname}`);
+  }
+  const httpUpstream = target.origin + target.pathname.replace(/\/$/, "");
+  const allow = opts.allowPaths;
+  return (sink) => {
+    const guarded = allow ? guardSink(sink, allow) : sink;
+    const server = createTunnelServer({
+      sink: guarded,
+      label: opts.label ?? "loopback-http",
+      pty: false,
+      authorize: () => null,
+      httpUpstream,
+      ...opts.injectHeaders && Object.keys(opts.injectHeaders).length > 0 ? { httpInjectHeaders: opts.injectHeaders } : {},
+      httpForwardTimeoutMs: opts.httpForwardTimeoutMs ?? DEFAULT_HTTP_FORWARD_TIMEOUT_MS,
+      httpStreamIdleTimeoutMs: 12e4
+    });
+    return { close: () => server.close() };
+  };
+}
+function guardSink(sink, allow) {
+  const denied = /* @__PURE__ */ new Set();
+  const deny = (reqId, path) => {
+    denied.add(reqId);
+    sink.send({
+      t: "http_response",
+      reqId,
+      status: 403,
+      error: { code: "path_not_allowed", message: `path '${path}' is not allowed on this host` }
+    });
+  };
+  return {
+    send: (frame) => sink.send(frame),
+    close: (reason) => sink.close(reason),
+    onClose: (handler) => sink.onClose(handler),
+    get isOpen() {
+      return sink.isOpen;
+    },
+    get sentCount() {
+      return sink.sentCount;
+    },
+    get recvCount() {
+      return sink.recvCount;
+    },
+    onFrame: (handler) => sink.onFrame((frame) => {
+      if (frame.t === "http_request") {
+        const pathname = safePathname(frame.path);
+        if (pathname === null || !pathAllowed(pathname, allow)) {
+          deny(frame.reqId, pathname ?? "(invalid)");
+          return;
+        }
+      } else if (frame.t === "http_request_chunk" && denied.has(frame.reqId)) {
+        if (frame.end) denied.delete(frame.reqId);
+        return;
+      }
+      handler(frame);
+    })
+  };
+}
+
+export { PAIRINGS_VERSION, PAIRING_REVOKED_CODE, createPairingRegistry, createReconnectLogGate, dialRendezvous, readPairingsSnapshot, serveLoopbackHttp };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map