@byollm/relay 0.1.0-alpha.10

package/dist/index.js

@@ -0,0 +1,878 @@
+// src/daemon-plane.ts
+import {
+  ClaimRequest,
+  FetchRequest,
+  HeartbeatRequest,
+  PROTOCOL_VERSION,
+  ReleaseRequest,
+  ResultRequest,
+  RequestSignature,
+  keyId,
+  verifyRequest,
+  verifyPublicIdentity,
+  PublicIdentity
+} from "@byollm/protocol";
+import { randomUUID } from "crypto";
+import { z } from "zod";
+
+// src/state.ts
+var AWAITING_PAYLOAD_MS = 1e4;
+var RelayState = class {
+  #jobs = /* @__PURE__ */ new Map();
+  #presence = /* @__PURE__ */ new Map();
+  /**
+   * Take a stub for routing. The payload is not here and will not be.
+   *
+   * **Idempotent by job id, and that is a security property rather than a
+   * convenience.** Site-plane calls are authenticated by signature, and
+   * byollm_009 §4.2's argument for signing the request instead of a
+   * server-issued nonce rests entirely on every write being idempotent per the
+   * instance it names. This one was not: re-enqueueing a known id built a
+   * fresh `queued` job over the top of the old one, discarding a live claim,
+   * its lease and any payload the site had already sealed to a device. A
+   * replayed enqueue inside the two-minute freshness window was therefore a
+   * way to yank a job back from the machine running it — the `release` bug of
+   * §4.2, rediscovered on the other plane.
+   *
+   * So a known id returns what is already routing, unchanged. A site that
+   * restarts and republishes its queue is the normal case, and it must not
+   * disturb work in flight.
+   */
+  enqueue(input) {
+    const existing = this.#jobs.get(input.id);
+    if (existing) return existing;
+    const job = {
+      id: input.id,
+      siteId: input.siteId,
+      stub: input.stub,
+      state: "queued"
+    };
+    this.#jobs.set(job.id, job);
+    return job;
+  }
+  job(jobId) {
+    return this.#jobs.get(jobId);
+  }
+  jobs() {
+    return [...this.#jobs.values()];
+  }
+  /** Jobs a site must seal for, right now. */
+  awaiting(siteId) {
+    return this.jobs().filter(
+      (j) => j.siteId === siteId && j.state === "awaiting-payload"
+    );
+  }
+  /** Sealed results waiting to go home. */
+  finished(siteId) {
+    return this.jobs().filter(
+      (j) => j.siteId === siteId && j.state === "done" && j.result !== void 0
+    );
+  }
+  seen(presence) {
+    const existing = this.#presence.get(presence.runnerId);
+    if (existing) {
+      existing.lastSeenAt = presence.lastSeenAt;
+      return existing;
+    }
+    const fresh = { ...presence, revoked: false };
+    this.#presence.set(presence.runnerId, fresh);
+    return fresh;
+  }
+  presence(runnerId) {
+    return this.#presence.get(runnerId);
+  }
+  everyone() {
+    return [...this.#presence.values()];
+  }
+  /**
+   * Return a job to the queue, forgetting the claim.
+   *
+   * The stub survives; nothing is lost. That is `LEASE_RECLAIMABLE` and it is
+   * why the awaiting-payload timeout is cheap to fire: the worst case is that
+   * a device did nothing for ten seconds and another one gets a turn.
+   */
+  requeue(job) {
+    job.state = "queued";
+    delete job.claimedBy;
+    delete job.awaitingUntil;
+    delete job.payload;
+  }
+  /**
+   * Fire whatever the clock says is due, and report it.
+   *
+   * Returns the jobs it requeued so a caller can log or surface them — a
+   * timeout that fires invisibly is indistinguishable from a job that was
+   * never claimed, and those want very different debugging.
+   */
+  sweep(now) {
+    const requeued = [];
+    for (const job of this.#jobs.values()) {
+      if (job.state === "awaiting-payload" && (job.awaitingUntil ?? 0) <= now) {
+        this.requeue(job);
+        requeued.push(job);
+      }
+      const lease = job.claimedBy;
+      if (lease && (job.state === "ready" || job.state === "running") && lease.leaseExpiresAt <= now) {
+        this.requeue(job);
+        requeued.push(job);
+      }
+    }
+    return requeued;
+  }
+};
+
+// src/daemon-plane.ts
+var ok = (body) => ({ status: 200, body });
+var fail = (status, error, message) => ({
+  status,
+  body: { error, message }
+});
+var DaemonPlane = class {
+  #deps;
+  constructor(deps) {
+    this.#deps = deps;
+  }
+  /**
+   * Pair a device — cloud_004 §3, the key-exchange moment.
+   *
+   * The relay hands back **the site's** public identity, taken from the
+   * consent projection, not its own. This is the sentence that makes hub mode
+   * safe: the daemon pins the party that will actually seal its work, so an
+   * envelope is verified against the site even though it arrived via us. A
+   * relay that substituted its own identity here could inject work — and would
+   * need a private key to do it, which is why it has none.
+   */
+  pair(body) {
+    const parsed = PairFixtureRequest.safeParse(body);
+    if (!parsed.success) {
+      return fail(400, "bad-request", "pair request failed schema validation");
+    }
+    if (!verifyPublicIdentity(parsed.data.device)) {
+      return fail(400, "bad-request", "the device identity is not consistent");
+    }
+    const consent = this.#deps.projection.consentFor(
+      parsed.data.owner,
+      this.#deps.siteId
+    );
+    if (!consent) {
+      return fail(403, "unauthorized", "no consent record for this user");
+    }
+    const site = this.#deps.projection.siteFor(this.#deps.siteId);
+    if (!site) {
+      return fail(403, "unauthorized", "this site is not registered");
+    }
+    const approved = this.#deps.projection.deviceByFingerprint(
+      parsed.data.device.identity
+    );
+    if (!approved) {
+      return fail(
+        403,
+        "unauthorized",
+        "this device has not been approved by its owner"
+      );
+    }
+    if (approved.owner !== parsed.data.owner) {
+      return fail(403, "unauthorized", "this device belongs to another owner");
+    }
+    const runnerId = approved.runnerId;
+    this.#deps.state.seen({
+      runnerId,
+      owner: parsed.data.owner,
+      device: parsed.data.device,
+      lastSeenAt: this.#deps.now()
+    });
+    return ok({
+      protocolVersion: PROTOCOL_VERSION,
+      runnerId,
+      /** The *site's* key. See the note above — this is load-bearing. */
+      site: site.site
+    });
+  }
+  /** Every authenticated call: signature first, then consent, then work. */
+  #authed(input, body, schema, run, options = {}) {
+    const signature = RequestSignature.safeParse(input.signature);
+    if (!signature.success) {
+      return fail(401, "unauthorized", "this request is not signed");
+    }
+    const known = this.#deps.state.presence(signature.data.runnerId);
+    if (!known) {
+      return fail(401, "unauthorized", "this runner is not recognised");
+    }
+    const failure = verifyRequest({
+      identityPublic: known.device.identity,
+      endpoint: input.endpoint,
+      body: input.rawBody,
+      signature: signature.data,
+      now: this.#deps.now()
+    });
+    if (failure) return fail(401, "unauthorized", "signature check failed");
+    const revoked = this.#deps.projection.consentFor(known.owner, this.#deps.siteId) === null;
+    if (revoked && options.allowRevoked !== true) {
+      return fail(403, "revoked", "routing for this runner has been revoked");
+    }
+    known.lastSeenAt = this.#deps.now();
+    const parsed = schema.safeParse(body);
+    if (!parsed.success || parsed.data === void 0) {
+      return fail(400, "bad-request", "request failed schema validation");
+    }
+    return run(parsed.data, known);
+  }
+  claim(auth, body) {
+    return this.#authed(auth, body, ClaimRequest, (request, device) => {
+      if (request.runnerId !== device.runnerId) {
+        return fail(401, "unauthorized", "runner id does not match the key");
+      }
+      const now = this.#deps.now();
+      this.#deps.state.sweep(now);
+      const kinds = new Set(request.capabilities.map((c) => c.kind));
+      const granted = [];
+      for (const job of this.#deps.state.jobs()) {
+        if (granted.length >= request.max) break;
+        if (job.state !== "queued") continue;
+        if (job.siteId !== this.#deps.siteId) continue;
+        if (!kinds.has(job.stub.kind)) continue;
+        if (!this.#deps.projection.mayRunFor(device.owner, job.stub.owner)) {
+          continue;
+        }
+        const leaseId = randomUUID();
+        job.state = "awaiting-payload";
+        job.claimedBy = {
+          runnerId: device.runnerId,
+          owner: device.owner,
+          device: device.device,
+          leaseId,
+          leaseExpiresAt: now + this.#deps.leaseMs
+        };
+        job.awaitingUntil = now + AWAITING_PAYLOAD_MS;
+        granted.push({
+          ...job.stub,
+          lease: {
+            id: leaseId,
+            runnerId: device.runnerId,
+            expiresAt: job.claimedBy.leaseExpiresAt
+          }
+        });
+      }
+      return ok({ jobs: granted, leaseMs: this.#deps.leaseMs });
+    });
+  }
+  /**
+   * Hand over the sealed payload, if the site has left one.
+   *
+   * The one endpoint whose behaviour differs from a direct site's, and the
+   * difference is the whole design: a direct site seals here, on demand,
+   * because it holds the keys. The relay waits. A `409` means "claimed, not
+   * yet sealed" — a daemon should retry, not treat it as a refusal, because
+   * the job is still legitimately theirs until the lease or the
+   * awaiting-payload clock says otherwise.
+   */
+  fetch(auth, body) {
+    return this.#authed(auth, body, FetchRequest, (request, device) => {
+      const job = this.#deps.state.job(request.jobId);
+      if (!job) return fail(404, "not-found", "unknown job");
+      if (job.claimedBy?.runnerId !== device.runnerId) {
+        return fail(403, "unauthorized", "this runner does not hold the job");
+      }
+      if (job.claimedBy.leaseId !== request.leaseId) {
+        return fail(403, "unauthorized", "that lease is no longer current");
+      }
+      if (!job.payload) {
+        return fail(409, "not-ready", "the site has not sealed this job yet");
+      }
+      job.state = "running";
+      return ok({ envelope: job.payload });
+    });
+  }
+  /**
+   * Take a sealed result.
+   *
+   * The relay stores ciphertext and records the disposition so it can stop
+   * dispatching. It cannot check the two against each other — that requires
+   * opening the envelope, which is the site's job and the site's key. This is
+   * the asymmetry byollm_009 §6.1 describes: the hint is actionable here and
+   * only verifiable there.
+   */
+  result(auth, body) {
+    return this.#authed(auth, body, ResultRequest, (request, device) => {
+      const job = this.#deps.state.job(request.jobId);
+      if (!job) return fail(404, "not-found", "unknown job");
+      if (job.claimedBy?.runnerId !== device.runnerId) {
+        return fail(403, "unauthorized", "this runner does not hold the job");
+      }
+      if (job.state === "done") {
+        return ok({ accepted: false, state: job.state });
+      }
+      job.result = request.envelope;
+      job.disposition = request.disposition;
+      job.state = "done";
+      return ok({ accepted: true, state: job.state });
+    });
+  }
+  heartbeat(auth, body) {
+    return this.#authed(
+      auth,
+      body,
+      HeartbeatRequest,
+      (request, device) => {
+        const now = this.#deps.now();
+        this.#deps.state.sweep(now);
+        const known = this.#deps.state.presence(device.runnerId);
+        const consent = this.#deps.projection.consentFor(
+          device.owner,
+          this.#deps.siteId
+        );
+        const revoked = consent === null;
+        if (known) known.revoked = revoked;
+        const lost = request.activeLeases.filter(({ jobId, leaseId }) => {
+          const job = this.#deps.state.job(jobId);
+          return job?.claimedBy?.leaseId !== leaseId;
+        }).map(({ jobId }) => jobId);
+        return ok({
+          revoked,
+          cancel: [],
+          leases: [],
+          lost,
+          serverTime: now
+        });
+      },
+      { allowRevoked: true }
+    );
+  }
+  release(auth, body) {
+    return this.#authed(auth, body, ReleaseRequest, (request, device) => {
+      const released = [];
+      for (const { jobId, leaseId } of request.leases) {
+        const job = this.#deps.state.job(jobId);
+        if (!job || job.claimedBy?.runnerId !== device.runnerId) continue;
+        if (job.claimedBy.leaseId !== leaseId) continue;
+        this.#deps.state.requeue(job);
+        released.push(jobId);
+      }
+      return ok({ released });
+    });
+  }
+};
+var PairFixtureRequest = z.object({
+  protocolVersion: z.literal(PROTOCOL_VERSION),
+  owner: z.string().min(1),
+  device: PublicIdentity
+}).strict();
+var fingerprintOf = (identity) => keyId(identity.identity);
+
+// src/debug.ts
+var escape = (value) => value.replace(
+  /[&<>"]/g,
+  (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c] ?? c
+);
+var STATE_COLOUR = {
+  queued: "#8a8a8a",
+  "awaiting-payload": "#c98a00",
+  ready: "#0a7",
+  running: "#06c",
+  done: "#444"
+};
+function jobRow(job, now) {
+  const claimed = job.claimedBy;
+  const waiting = job.state === "awaiting-payload" && job.awaitingUntil !== void 0 ? `${String(Math.max(0, job.awaitingUntil - now))}ms left` : "";
+  return `<tr>
+    <td><code>${escape(job.id)}</code></td>
+    <td>${escape(job.stub.kind)}</td>
+    <td>${escape(job.stub.owner)}</td>
+    <td>${escape(job.stub.audience)}</td>
+    <td>${escape(job.stub.sizeClass)}</td>
+    <td>${job.stub.streaming ? "yes" : "no"}</td>
+    <td><b style="color:${STATE_COLOUR[job.state] ?? "#000"}">${escape(job.state)}</b> <span class="dim">${escape(waiting)}</span></td>
+    <td>${claimed ? `<code>${escape(fingerprintOf(claimed.device))}</code>` : "<span class='dim'>\u2014</span>"}</td>
+    <td>${job.payload ? "sealed" : "<span class='dim'>\u2014</span>"}</td>
+    <td>${job.result ? escape(job.disposition ?? "?") : "<span class='dim'>\u2014</span>"}</td>
+  </tr>`;
+}
+function debugPage(state, now) {
+  const jobs = state.jobs();
+  const devices = state.everyone();
+  return `<!doctype html>
+<html><head><meta charset="utf-8"><title>byollm relay \u2014 debug</title>
+<meta http-equiv="refresh" content="1">
+<style>
+ body{font:13px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace;margin:24px;color:#111;background:#fff}
+ h1{font-size:15px;margin:0 0 4px} h2{font-size:13px;margin:24px 0 6px}
+ table{border-collapse:collapse;width:100%;margin-top:4px}
+ th,td{text-align:left;padding:4px 8px;border-bottom:1px solid #eee;vertical-align:top}
+ th{font-weight:600;color:#666;border-bottom:1px solid #ccc}
+ code{background:#f5f5f5;padding:1px 4px;border-radius:3px}
+ .dim{color:#aaa} .note{color:#666;max-width:70ch;margin:8px 0 0}
+ @media(prefers-color-scheme:dark){
+  body{background:#111;color:#eee} th{color:#999;border-color:#333}
+  td{border-color:#222} code{background:#1c1c1c} .note{color:#999}
+ }
+</style></head><body>
+<h1>byollm relay \u2014 debug</h1>
+<p class="note">Everything this relay knows, which is everything on this page.
+There is no prompt or result text here because it holds none: payloads and
+results are sealed to their endpoints and pass through as ciphertext.</p>
+
+<h2>Routed jobs (${String(jobs.length)})</h2>
+<table>
+<tr><th>job</th><th>kind</th><th>owner</th><th>audience</th><th>size</th>
+    <th>stream</th><th>state</th><th>claimed by</th><th>payload</th><th>result</th></tr>
+${jobs.length ? jobs.map((j) => jobRow(j, now)).join("\n") : `<tr><td colspan="10" class="dim">nothing routed yet</td></tr>`}
+</table>
+
+<h2>Presence (${String(devices.length)})</h2>
+<table>
+<tr><th>runner</th><th>owner</th><th>fingerprint</th><th>last seen</th><th>routing</th></tr>
+${devices.length ? devices.map(
+    (d) => `<tr>
+  <td><code>${escape(d.runnerId)}</code></td>
+  <td>${escape(d.owner)}</td>
+  <td><code>${escape(fingerprintOf(d.device))}</code></td>
+  <td>${String(Math.max(0, now - d.lastSeenAt))}ms ago</td>
+  <td>${d.revoked ? "<b style='color:#c00'>revoked</b>" : "active"}</td>
+</tr>`
+  ).join("\n") : `<tr><td colspan="5" class="dim">no devices connected</td></tr>`}
+</table>
+</body></html>`;
+}
+
+// src/fixture.ts
+import { PublicIdentity as PublicIdentity2 } from "@byollm/protocol";
+import { z as z2 } from "zod";
+var SiteRecord = z2.object({
+  /** How the control plane names the site. */
+  siteId: z2.string().min(1),
+  /**
+   * The site's public identity.
+   *
+   * The relay distributes it and cannot use it: an identity key verifies
+   * signatures and seals nothing. This is the key-exchange half of consent
+   * (cloud_004 §3), and both endpoints pin what they receive.
+   */
+  site: PublicIdentity2
+}).strict();
+var ConsentRecord = z2.object({
+  /** The user, as the control plane identifies them. */
+  owner: z2.string().min(1),
+  /** Which site this consent is for. Scoped: consent is never global. */
+  siteId: z2.string().min(1)
+}).strict();
+var RosterRecord = z2.object({
+  /** Stable id for the group, used only inside the relay. */
+  id: z2.string().min(1),
+  /** Who owns the shared compute. */
+  owner: z2.string().min(1),
+  /** Members who may route to it. The owner is not implicitly a member. */
+  members: z2.array(z2.string().min(1))
+}).strict();
+var DeviceRecord = z2.object({
+  /** Who approved it. */
+  owner: z2.string().min(1),
+  /** The id the control plane assigned — the device does not choose it. */
+  runnerId: z2.string().min(1),
+  /** The keys a human compared a fingerprint of before approving. */
+  device: PublicIdentity2
+}).strict();
+var RevocationRecord = z2.object({ owner: z2.string().min(1), siteId: z2.string().min(1) }).strict();
+var RelayFixture = z2.object({
+  /** Registered sites, by id. A consent for a site absent here routes not. */
+  sites: z2.array(SiteRecord).default([]),
+  consents: z2.array(ConsentRecord),
+  devices: z2.array(DeviceRecord).default([]),
+  rosters: z2.array(RosterRecord).default([]),
+  /**
+   * Routes that were revoked, as structured pairs.
+   *
+   * A separate list rather than deleting the consent record, because the
+   * freeze gate needs revocation to be an observable *event* rather than an
+   * absence — "the row is gone" and "the row was revoked" are different
+   * answers to someone debugging why routing stopped.
+   *
+   * `{owner, siteId}` and never the composite string `"owner:siteId"`. A
+   * composite key is a parser waiting to meet an id containing its
+   * separator, which is the lesson the composite lease ids taught against
+   * Postgres — applied here before it became a contract.
+   */
+  revoked: z2.array(RevocationRecord).default([])
+}).strict();
+var EMPTY_FIXTURE = {
+  sites: [],
+  consents: [],
+  devices: [],
+  rosters: [],
+  revoked: []
+};
+var Projection = class {
+  #fixture;
+  constructor(fixture = EMPTY_FIXTURE) {
+    this.#fixture = RelayFixture.parse(fixture);
+  }
+  /** Replace the projection wholesale — the control plane pushed a new one. */
+  replace(fixture) {
+    this.#fixture = RelayFixture.parse(fixture);
+  }
+  /**
+   * The site this id names, if the control plane registered it.
+   *
+   * The only source of a site's public identity in this package. Everything
+   * that pins, verifies or seals to a site starts here.
+   */
+  siteFor(siteId) {
+    return this.#fixture.sites.find((s) => s.siteId === siteId) ?? null;
+  }
+  /**
+   * The device this runner id names, if a human approved it.
+   *
+   * Returns null for a device the control plane does not know, which is how
+   * the relay refuses to be the authority on identity.
+   */
+  deviceFor(runnerId) {
+    return this.#fixture.devices.find((d) => d.runnerId === runnerId) ?? null;
+  }
+  /** The device approved for these exact keys, if any. */
+  deviceByFingerprint(identityPublic) {
+    return this.#fixture.devices.find((d) => d.device.identity === identityPublic) ?? null;
+  }
+  /** The consent binding this owner to this site, if it exists and stands. */
+  consentFor(owner, siteId) {
+    const revoked = this.#fixture.revoked.some(
+      (r) => r.owner === owner && r.siteId === siteId
+    );
+    if (revoked) return null;
+    return this.#fixture.consents.find(
+      (c) => c.owner === owner && c.siteId === siteId
+    ) ?? null;
+  }
+  /**
+   * May this device's owner run work belonging to `jobOwner`?
+   *
+   * The relay's half of `AUDIENCE_BOTH_SIDES`. It is only ever a *narrowing*:
+   * the daemon re-checks its own allowlist locally and may still refuse, and
+   * the site's audience already bounded who could be offered the job. A relay
+   * that answered `true` for everyone would not widen anything — which is
+   * exactly the property that lets it be blind.
+   */
+  mayRunFor(deviceOwner, jobOwner) {
+    if (deviceOwner === jobOwner) return true;
+    return this.#fixture.rosters.some(
+      (r) => r.owner === deviceOwner && r.members.includes(jobOwner)
+    );
+  }
+};
+
+// src/site-plane.ts
+import {
+  JobStub,
+  RequestSignature as RequestSignature2,
+  SealedEnvelope,
+  verifySiteRequest
+} from "@byollm/protocol";
+import { z as z3 } from "zod";
+var EnqueueRequest = z3.object({
+  siteId: z3.string().min(1),
+  /**
+   * Everything the relay learns about the job.
+   *
+   * `JobStub` is exhaustive by construction and asserted so in the protocol
+   * package — a site that tried to attach a prompt here would be refused by
+   * the schema, not by a reviewer.
+   */
+  stub: JobStub
+}).strict();
+var PayloadRequest = z3.object({
+  siteId: z3.string().min(1),
+  jobId: z3.string().min(1),
+  /** Sealed to the claiming device. Opaque to us and to the schema. */
+  envelope: SealedEnvelope
+}).strict();
+var QueryRequest = z3.object({ siteId: z3.string().min(1) }).strict();
+var ok2 = (body) => ({ status: 200, body });
+var fail2 = (status, error, message) => ({
+  status,
+  body: { error, message }
+});
+var SitePlane = class {
+  #deps;
+  constructor(deps) {
+    this.#deps = deps;
+  }
+  /**
+   * Signature first, then the site id, then the work.
+   *
+   * The caller is whoever the signature says, verified against the key the
+   * control plane registered — never whoever the request claims. The `siteId`
+   * every request carries is then required to *match* that caller, so the two
+   * can never name different sites; a request that says one thing in its
+   * signed material and another in its body is refused rather than reconciled.
+   *
+   * Every endpoint goes through here, including the reads. That is deliberate:
+   * an authenticated write plane beside an open read plane would still hand a
+   * stranger presence, claims and lease ids, and "who is online right now" is
+   * exactly the fact a blind relay is otherwise so careful not to reveal.
+   */
+  #authed(auth, body, schema, siteIdOf, run) {
+    const signature = RequestSignature2.safeParse(auth.signature);
+    if (!signature.success) {
+      return fail2(401, "unauthorized", "this request is not signed");
+    }
+    const siteId = signature.data.runnerId;
+    const site = this.#deps.projection.siteFor(siteId);
+    if (!site) {
+      return fail2(401, "unauthorized", "this site is not registered");
+    }
+    const failure = verifySiteRequest({
+      identityPublic: site.site.identity,
+      endpoint: auth.endpoint,
+      body: auth.rawBody,
+      signature: signature.data,
+      now: this.#deps.now()
+    });
+    if (failure) return fail2(401, "unauthorized", "signature check failed");
+    const parsed = schema.safeParse(body);
+    if (!parsed.success || parsed.data === void 0) {
+      return fail2(400, "bad-request", "request failed schema validation");
+    }
+    if (siteIdOf(parsed.data) !== siteId) {
+      return fail2(403, "unauthorized", "that is not your site");
+    }
+    if (siteId !== this.#deps.routesFor) {
+      return fail2(403, "unauthorized", "this relay does not route for you");
+    }
+    return run(parsed.data, siteId);
+  }
+  enqueue(auth, body) {
+    return this.#authed(
+      auth,
+      body,
+      EnqueueRequest,
+      (request) => request.siteId,
+      (request, siteId) => {
+        const job = this.#deps.state.enqueue({
+          id: request.stub.id,
+          siteId,
+          stub: request.stub
+        });
+        return ok2({ jobId: job.id, state: job.state });
+      }
+    );
+  }
+  /**
+   * What needs sealing, and who to seal it to.
+   *
+   * The response carries the claiming device's **public** keys — which is the
+   * entire reason a blind relay can exist. The relay is a directory here, not
+   * a participant: it tells the site an address, and what the site sends to
+   * that address is unreadable on the way through.
+   */
+  pending(auth, siteId) {
+    return this.#authed(
+      auth,
+      { siteId },
+      QueryRequest,
+      (request) => request.siteId,
+      (_request, site) => {
+        this.#deps.state.sweep(this.#deps.now());
+        const jobs = this.#deps.state.awaiting(site).map((job) => ({
+          jobId: job.id,
+          // Non-null by construction: `awaiting` only returns claimed jobs.
+          // The optional chain is here so a future state-machine edit that
+          // broke that invariant would produce a missing field rather than a
+          // crash on the routing path.
+          device: job.claimedBy?.device,
+          runnerId: job.claimedBy?.runnerId,
+          leaseId: job.claimedBy?.leaseId,
+          /** So a site can decline to seal for a claim about to expire. */
+          awaitingUntil: job.awaitingUntil
+        }));
+        return ok2({ jobs });
+      }
+    );
+  }
+  payload(auth, body) {
+    return this.#authed(
+      auth,
+      body,
+      PayloadRequest,
+      (request) => request.siteId,
+      (request, siteId) => {
+        const job = this.#deps.state.job(request.jobId);
+        if (job?.siteId !== siteId) {
+          return fail2(404, "not-found", "unknown job");
+        }
+        if (job.state !== "awaiting-payload") {
+          return fail2(
+            409,
+            "too-late",
+            `job is ${job.state}, not awaiting payload`
+          );
+        }
+        job.payload = request.envelope;
+        job.state = "ready";
+        delete job.awaitingUntil;
+        return ok2({ jobId: job.id, state: job.state });
+      }
+    );
+  }
+  /** Sealed results, for the site to open and verify. */
+  results(auth, siteId) {
+    return this.#authed(
+      auth,
+      { siteId },
+      QueryRequest,
+      (request) => request.siteId,
+      (_request, site) => {
+        const jobs = this.#deps.state.finished(site).map((job) => ({
+          jobId: job.id,
+          envelope: job.result,
+          disposition: job.disposition,
+          runnerId: job.claimedBy?.runnerId,
+          /** The grant the site adopted, so it can complete against it. */
+          leaseId: job.claimedBy?.leaseId,
+          /**
+           * Which device ran it, so the site can verify the signature against
+           * the key it was told to seal to — and so `RESULT_PROVENANCE` can
+           * name a foreign device rather than guessing (cloud_004 §11.2).
+           */
+          device: job.claimedBy?.device
+        }));
+        return ok2({ jobs });
+      }
+    );
+  }
+};
+
+// src/index.ts
+var Relay = class {
+  state;
+  projection;
+  #daemon;
+  #site;
+  #now;
+  #basePath;
+  constructor(options) {
+    this.state = new RelayState();
+    this.projection = new Projection(options.fixture);
+    this.#now = options.now ?? Date.now;
+    this.#basePath = (options.basePath ?? "/byollm").replace(/\/+$/, "");
+    this.#daemon = new DaemonPlane({
+      state: this.state,
+      projection: this.projection,
+      now: this.#now,
+      leaseMs: options.leaseMs ?? 6e4,
+      siteId: options.siteId
+    });
+    this.#site = new SitePlane({
+      state: this.state,
+      projection: this.projection,
+      now: this.#now,
+      routesFor: options.siteId
+    });
+  }
+  /** Replace the projection — a control-plane push, or a fixture edit. */
+  project(fixture) {
+    this.projection.replace(fixture);
+  }
+  /**
+   * Fire due timers and report what moved.
+   *
+   * Exposed rather than run on an interval so a test can drive it, and so the
+   * production hub can decide its own scheduling. The relay never needs a
+   * timer to be *correct* — every read path sweeps first — but a job whose
+   * site vanished should return to the queue without waiting for someone to
+   * ask about it.
+   */
+  sweep() {
+    return { requeued: this.state.sweep(this.#now()).map((j) => j.id) };
+  }
+  /** The whole HTTP surface. */
+  async handle(request) {
+    const url = new URL(request.url);
+    const path = url.pathname;
+    if (path === "/debug" || path === `${this.#basePath}/debug`) {
+      return new Response(debugPage(this.state, this.#now()), {
+        headers: { "content-type": "text/html; charset=utf-8" }
+      });
+    }
+    const rawBody = request.method === "POST" ? await request.text() : "";
+    const body = rawBody === "" ? void 0 : safeJson(rawBody);
+    const endpoint = path.slice(path.lastIndexOf("/") + 1);
+    const auth = {
+      endpoint,
+      rawBody,
+      signature: signatureFrom(request.headers, "x-byollm-runner")
+    };
+    const siteAuth = {
+      endpoint,
+      rawBody,
+      signature: signatureFrom(request.headers, "x-byollm-site")
+    };
+    if (path === "/relay/site/enqueue") {
+      return json(this.#site.enqueue(siteAuth, body));
+    }
+    if (path === "/relay/site/payload") {
+      return json(this.#site.payload(siteAuth, body));
+    }
+    if (path === "/relay/site/pending") {
+      return json(
+        this.#site.pending(siteAuth, url.searchParams.get("siteId") ?? "")
+      );
+    }
+    if (path === "/relay/site/results") {
+      return json(
+        this.#site.results(siteAuth, url.searchParams.get("siteId") ?? "")
+      );
+    }
+    if (!path.startsWith(`${this.#basePath}/`)) {
+      return json({ status: 404, body: { error: "not-found" } });
+    }
+    switch (auth.endpoint) {
+      case "pair":
+        return json(this.#daemon.pair(body));
+      case "claim":
+        return json(this.#daemon.claim(auth, body));
+      case "fetch":
+        return json(this.#daemon.fetch(auth, body));
+      case "result":
+        return json(this.#daemon.result(auth, body));
+      case "heartbeat":
+        return json(this.#daemon.heartbeat(auth, body));
+      case "release":
+        return json(this.#daemon.release(auth, body));
+      default:
+        return json({ status: 404, body: { error: "not-found" } });
+    }
+  }
+};
+function safeJson(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return void 0;
+  }
+}
+function signatureFrom(headers, callerHeader) {
+  const runnerId = headers.get(callerHeader);
+  const issuedAt = headers.get("x-byollm-issued-at");
+  const signature = headers.get("x-byollm-signature");
+  if (runnerId === null || issuedAt === null || signature === null) {
+    return void 0;
+  }
+  return { runnerId, issuedAt: Number(issuedAt), signature };
+}
+var json = (result) => new Response(JSON.stringify(result.body), {
+  status: result.status,
+  headers: { "content-type": "application/json" }
+});
+export {
+  AWAITING_PAYLOAD_MS,
+  ConsentRecord,
+  DeviceRecord,
+  EMPTY_FIXTURE,
+  Projection,
+  Relay,
+  RelayFixture as RelayFixtureSchema,
+  RelayState,
+  RevocationRecord,
+  RosterRecord,
+  SiteRecord,
+  debugPage
+};
+//# sourceMappingURL=index.js.map