@byollm/server 0.1.0-alpha.2 → 0.1.0-alpha.4

package/README.md

@@ -1,5 +1,5 @@
 > [!WARNING]
-> **Alpha (`0.1.0-alpha.2`) — under active development. Don't use this yet.**
+> **Alpha (`0.1.0-alpha.4`) — under active development. Don't use this yet.**
 >
 > Install it deliberately: `npm install @byollm/server@alpha`.
 >
@@ -12,6 +12,19 @@
 > bare install resolves here too. This notice is the only guard — deliberately
 > not an npm deprecation, which would read as *abandoned* rather than *early*.
 > Ask for `@alpha` explicitly so your lockfile records that you meant to.
+>
+> **`alpha.4` breaks every integration.** Three things changed for you:
+>
+> 1. **`siteKeys` is required.** Run `npx @byollm/server@alpha keygen` once,
+>    set `BYOLLM_SITE_KEYS`, and pass it to `ByollmApp` and `createHandler`.
+>    Once — not per deploy, never at startup.
+> 2. **`createHandler` takes a function.** `next build` imports route modules
+>    with no secrets present, so a config object fails the build.
+> 3. **Every paired runner re-pairs.** Bearer tokens are replaced by per-request
+>    signatures against a pinned device key, so old tokens authenticate nothing.
+>
+> Your store adapter is unaffected: payloads and results are sealed before they
+> reach it, and `JobStore` did not change.
 
 # `@byollm/server`
 
@@ -30,28 +43,68 @@ npm install @byollm/server
 ```ts
 // app/api/byollm/[...route]/route.ts
 import { createHandler } from "@byollm/server/next";
-import { store } from "@/lib/byollm";
+import { siteKeysFromEnv } from "@byollm/server";
+import { getStore } from "@/lib/byollm";
 
-export const { POST } = createHandler({
-  store,
+export const { POST } = createHandler(() => ({
+  store: getStore(),
+  siteKeys: siteKeysFromEnv("BYOLLM_SITE_KEYS"),
   verificationUrl: "https://your-app.com/settings/runners",
-});
+  // Next serves this route under /api, so say where it is mounted. The
+  // handler matches the full path and will 404 without this.
+  basePath: "/api/byollm",
+}));
 ```
 
+**Pass a function, not an object.** `next build` imports every route module to
+collect page data, in an environment that has no secrets. A config object is
+constructed during that import, so the build fails on credentials it cannot
+have. A function is not called until the first request.
+
+Then pair against that same path — `byollm connect https://your-app.com/api`.
+The daemon appends `/byollm/<endpoint>` to whatever origin it is given, so
+connecting to the bare domain looks for `/byollm/claim` and finds nothing.
+To serve at `/byollm` instead, put the route at `app/byollm/[...route]/route.ts`,
+drop `basePath`, and pair against the bare domain.
+
 **2. Pick a store.**
 
 ```ts
 // lib/byollm.ts
-import { ByollmApp, MemoryStore } from "@byollm/server";
+import { ByollmApp, MemoryStore, siteKeysFromEnv } from "@byollm/server";
 
-export const store = new MemoryStore();
-export const app = new ByollmApp({ store });
+// Lazily, and memoized, for the same reason the mount takes a function: a
+// module-scope `new` runs during `next build`.
+let store: MemoryStore | undefined;
+export function getStore(): MemoryStore {
+  return (store ??= new MemoryStore());
+}
+
+let app: ByollmApp | undefined;
+export function getApp(): ByollmApp {
+  return (app ??= new ByollmApp({
+    store: getStore(),
+    siteKeys: siteKeysFromEnv("BYOLLM_SITE_KEYS"),
+  }));
+}
 ```
 
+Generate that identity once, and keep it:
+
+```bash
+npx @byollm/server@alpha keygen   # prints BYOLLM_SITE_KEYS=...
+```
+
+Once, not per deploy and never at startup — a daemon pins this identity when
+its owner approves the pairing, and regenerating it means every paired machine
+must pair again. Generating at startup fails only under horizontal scale: each
+instance would have a different identity, and a daemon would be refused by
+whichever one it did not pair with.
+
 **3. Enqueue.**
 
 ```ts
-const job = await app.enqueue({
+const job = await getApp().enqueue({
   kind: "llm.generate",
   audience: "self", // this user's own machine only — the default
   owner: userId,
@@ -75,7 +128,7 @@ types the code their daemon showed them:
 
 ```ts
 // The owner comes from YOUR session. A daemon can never assert who it is.
-const runner = await app.approvePairing({
+const runner = await getApp().approvePairing({
   userCode: formData.get("code"),
   owner: session.userId,
 });
@@ -103,6 +156,7 @@ import {
 const store = supabaseStore({ client: serviceRoleClient });
 const app = new ByollmApp({
   store,
+  siteKeys: siteKeysFromEnv("BYOLLM_SITE_KEYS"),
   delivery: supabaseRealtimeDelivery(serviceRoleClient),
 });
 ```
@@ -123,7 +177,7 @@ and `untrusted` is derived from the audience — you cannot mark volunteer
 output as first-party:
 
 ```ts
-const { outcome, provenance } = await app.result(jobId);
+const { outcome, provenance } = await getApp().result(jobId);
 if (provenance?.untrusted) {
   // Do not render as trusted HTML. Do not feed to a privileged step.
   // Disclose where it came from.

package/bin/keygen.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * `npx @byollm/server keygen` — make a site identity, once.
+ *
+ * Prints an env-file fragment. Deliberately not written to a file: key
+ * material that lands on disk by default tends to end up committed, and the
+ * one place it should live is wherever this deployment keeps its secrets.
+ */
+import { formatSiteKeys, generateSiteKeys } from "../dist/index.js";
+
+if (process.argv.includes("--help") || process.argv.includes("-h")) {
+  process.stdout.write(
+    "usage: npx @byollm/server keygen\n\n" +
+      "Generates this site's byollm identity and prints it as an env line.\n" +
+      "Run it once. Store the result as a secret. Regenerating it makes every\n" +
+      "daemon that has paired with this site pair again.\n",
+  );
+  process.exit(0);
+}
+
+process.stdout.write(formatSiteKeys(generateSiteKeys()));

package/dist/{chunk-HL6EYHQ7.js → chunk-MGJX6626.js}

@@ -16,7 +16,7 @@ function generateRunnerId() {
   return `runner_${randomUUID()}`;
 }
 function generateJobId() {
-  return `job_${randomUUID()}`;
+  return randomUUID();
 }
 function generateUserCode() {
   const chars = [];
@@ -39,9 +39,20 @@ function secretsMatch(aHex, bHex) {
   if (aHex.length !== bHex.length) return false;
   return timingSafeEqual(Buffer.from(aHex, "hex"), Buffer.from(bHex, "hex"));
 }
+var generateLeaseId = () => randomUUID();
 
 // src/handlers.ts
 import {
+  ENVELOPE_MAX_AGE_MS,
+  FetchRequest,
+  seal,
+  JobOutcome,
+  keyId,
+  open,
+  publicIdentityOf,
+  RequestSignature,
+  verifyRequest,
+  verifyPublicIdentity,
   ClaimRequest,
   ERROR_STATUS,
   HeartbeatRequest,
@@ -77,8 +88,15 @@ var ByollmHandlers = class {
   #pairingTtlMs;
   #pollIntervalMs;
   #now;
+  #siteKeys;
   constructor(config) {
     this.#store = config.store;
+    if (!verifyPublicIdentity(publicIdentityOf(config.siteKeys))) {
+      throw new Error(
+        "siteKeys are not internally consistent: the encryption key is not signed by the identity key. Generate a fresh pair with `npx @byollm/server keygen`."
+      );
+    }
+    this.#siteKeys = config.siteKeys;
     this.#verificationUrl = config.verificationUrl;
     this.#leaseMs = config.leaseMs ?? DEFAULTS.leaseMs;
     this.#pairingTtlMs = config.pairingTtlMs ?? DEFAULTS.pairingTtlMs;
@@ -90,32 +108,29 @@ var ByollmHandlers = class {
    *
    * @param endpoint - which of the five, already routed from the path
    * @param body - the parsed JSON request body, untrusted
-   * @param bearer - the `Authorization: Bearer` value, if any
+   * @param auth - the signature and the exact bytes it covers
    */
-  async handle(endpoint, body, bearer) {
+  async handle(endpoint, body, auth) {
     switch (endpoint) {
       case "pair":
         return this.#pair(body);
       case "claim":
-        return this.#authed(bearer, body, ClaimRequest, this.#claim.bind(this));
+        return this.#authed(auth, body, ClaimRequest, this.#claim.bind(this));
       case "heartbeat":
         return this.#authed(
-          bearer,
+          auth,
           body,
           HeartbeatRequest,
           this.#heartbeat.bind(this),
           { allowRevoked: true }
         );
+      case "fetch":
+        return this.#authed(auth, body, FetchRequest, this.#fetch.bind(this));
       case "result":
-        return this.#authed(
-          bearer,
-          body,
-          ResultRequest,
-          this.#result.bind(this)
-        );
+        return this.#authed(auth, body, ResultRequest, this.#result.bind(this));
       case "release":
         return this.#authed(
-          bearer,
+          auth,
           body,
           ReleaseRequest,
           this.#release.bind(this)
@@ -123,19 +138,30 @@ var ByollmHandlers = class {
     }
   }
   /**
-   * Shared preamble for the four authenticated endpoints: resolve the bearer
-   * token to a runner, reject a revoked one, and parse the body.
+   * Shared preamble for the four authenticated endpoints: verify the
+   * signature, reject a revoked runner, and parse the body.
    *
-   * The token→runner lookup happens before schema validation so a stranger
-   * probing the endpoint learns nothing about the wire format.
+   * Authentication happens before schema validation so a stranger probing the
+   * endpoint learns nothing about the wire format.
    */
-  async #authed(bearer, body, schema, run, options = {}) {
-    if (bearer === void 0 || bearer.length === 0) {
-      return fail("unauthorized", "a runner token is required");
+  async #authed(auth, body, schema, run, options = {}) {
+    const signature = RequestSignature.safeParse(auth.signature);
+    if (!signature.success) {
+      return fail("unauthorized", "this request is not signed");
     }
-    const runner = await this.#store.getRunnerByTokenHash(hashSecret(bearer));
+    const runner = await this.#store.getRunner(signature.data.runnerId);
     if (!runner) {
-      return fail("unauthorized", "this runner token is not recognised");
+      return fail("unauthorized", "this runner is not recognised");
+    }
+    const failure = verifyRequest({
+      identityPublic: runner.device.identity,
+      endpoint: auth.endpoint,
+      body: auth.rawBody,
+      signature: signature.data,
+      now: this.#now()
+    });
+    if (failure !== null) {
+      return fail("unauthorized", "this request's signature is not valid");
     }
     if (runner.revokedAt !== null && options.allowRevoked !== true) {
       return fail("revoked", "this runner has been revoked by its owner");
@@ -146,6 +172,51 @@ var ByollmHandlers = class {
     }
     return run(parsed.data, runner);
   }
+  /**
+   * Hand over the payload for a lease this runner holds — byollm_009 §6.
+   *
+   * The second half of claim-then-fetch. A claim answers with a stub, and the
+   * work itself is collected separately by the device that took it, because a
+   * payload can only be sealed once its recipient is known.
+   *
+   * Scoped to the lease, not the job: answering for whatever lease happens to
+   * exist would hand the work to a runner whose grant had already been
+   * superseded.
+   */
+  async #fetch(request, runner) {
+    const job = await this.#store.get(request.jobId);
+    if (!job || job.lease?.runnerId !== runner.id || job.lease.id !== request.leaseId) {
+      return fail("not-found", "no such lease on this job");
+    }
+    const senderKeyId = keyId(publicIdentityOf(this.#siteKeys).identity);
+    const opened = await open({
+      envelope: job.envelope,
+      recipientKeys: this.#siteKeys,
+      senderIdentityPublic: this.#siteKeys.identityPublic,
+      expected: {
+        jobId: job.id,
+        senderKeyId,
+        recipientKeyId: senderKeyId,
+        direction: "payload"
+      }
+    });
+    if (!opened.ok) {
+      return fail("server-error", "this job's payload could not be opened");
+    }
+    const resealed = await seal({
+      plaintext: opened.plaintext,
+      senderKeys: this.#siteKeys,
+      recipientEncryptionPublic: runner.device.encryption,
+      context: {
+        jobId: job.id,
+        senderKeyId,
+        recipientKeyId: keyId(runner.device.identity),
+        deadlineAt: job.createdAt + ENVELOPE_MAX_AGE_MS,
+        direction: "payload"
+      }
+    });
+    return ok({ envelope: resealed });
+  }
   // -- 1. pair --------------------------------------------------------------
   async #pair(body) {
     const parsed = PairRequest.safeParse(body);
@@ -158,7 +229,14 @@ var ByollmHandlers = class {
       const deviceCode = generateDeviceCode();
       const userCode = generateUserCode();
       const expiresAt = now + this.#pairingTtlMs;
+      if (!verifyPublicIdentity(request.device)) {
+        return fail(
+          "bad-request",
+          "the device's encryption key is not signed by the identity it was presented with"
+        );
+      }
       await this.#store.createPairing({
+        device: request.device,
         deviceCodeHash: hashSecret(deviceCode),
         userCode,
         state: "pending",
@@ -198,7 +276,10 @@ var ByollmHandlers = class {
         status: "approved",
         runnerToken: pairing.runnerTokenOnce,
         runnerId: pairing.runnerId,
-        owner: pairing.owner
+        owner: pairing.owner,
+        // Only on approval: a pending or denied poll learns nothing, so an
+        // unapproved code cannot be used to enumerate a site's keys.
+        site: publicIdentityOf(this.#siteKeys)
       };
       await this.#store.consumePairingToken(pairing.deviceCodeHash);
       return ok(response);
@@ -211,7 +292,7 @@ var ByollmHandlers = class {
   // -- 2. claim -------------------------------------------------------------
   async #claim(request, runner) {
     if (request.runnerId !== runner.id) {
-      return fail("unauthorized", "runner id does not match the bearer token");
+      return fail("unauthorized", "runner id does not match the signing key");
     }
     const now = this.#now();
     const jobs = await this.#store.claim({
@@ -226,14 +307,24 @@ var ByollmHandlers = class {
       jobs: jobs.map((job) => ({
         id: job.id,
         kind: job.kind,
-        payload: job.payload,
         audience: job.audience,
         owner: job.owner,
+        // Bucketed, not measured: an exact size is a stronger fingerprint
+        // than routing needs (byollm_009 §6).
+        sizeClass: job.sizeClass,
+        // Reserved for byollm_006; no job declares it yet.
+        streaming: false,
+        // The stub's deadline bounds how long a captured envelope is worth
+        // keeping, so it is always present — falling back to the TTL window
+        // when the app named no absolute one.
+        deadlineAt: job.deadlineAt ?? (job.claimableAt ?? now) + job.ttlMs,
         ...job.audienceAllow === void 0 ? {} : { audienceAllow: [...job.audienceAllow] },
-        lease: job.lease ?? {
-          runnerId: runner.id,
-          expiresAt: now + this.#leaseMs
-        }
+        // No fallback. A job returned from `claim` holds a lease by
+        // definition, and synthesising one here would hand the daemon a lease
+        // id the store has never heard of — every later release naming it
+        // would silently match nothing. A store that returns an unleased job
+        // has broken its contract, and this says so.
+        lease: leaseOf(job)
       })),
       leaseMs: this.#leaseMs
     };
@@ -242,7 +333,7 @@ var ByollmHandlers = class {
   // -- 3. heartbeat ---------------------------------------------------------
   async #heartbeat(request, runner) {
     if (request.runnerId !== runner.id) {
-      return fail("unauthorized", "runner id does not match the bearer token");
+      return fail("unauthorized", "runner id does not match the signing key");
     }
     const now = this.#now();
     const revoked = runner.revokedAt !== null;
@@ -266,7 +357,7 @@ var ByollmHandlers = class {
     });
     const { renewed, lost } = await this.#store.renewLeases({
       runnerId: runner.id,
-      jobIds: request.activeJobIds,
+      leases: request.activeLeases,
       leaseMs: this.#leaseMs,
       now
     });
@@ -283,11 +374,13 @@ var ByollmHandlers = class {
   // -- 4. result ------------------------------------------------------------
   async #result(request, runner) {
     if (request.runnerId !== runner.id) {
-      return fail("unauthorized", "runner id does not match the bearer token");
+      return fail("unauthorized", "runner id does not match the signing key");
     }
     const now = this.#now();
     const job = await this.#store.get(request.jobId);
     if (!job) return fail("not-found", "unknown job");
+    const outcome = await this.#openResult(request, runner);
+    if (!outcome.ok) return outcome.failure;
     const provenance = provenanceFor({
       audience: job.audience,
       runnerId: runner.id,
@@ -298,7 +391,7 @@ var ByollmHandlers = class {
     const { accepted, job: updated } = await this.#store.complete({
       jobId: request.jobId,
       runnerId: runner.id,
-      outcome: request.outcome,
+      outcome: outcome.value,
       provenance,
       now
     });
@@ -308,14 +401,57 @@ var ByollmHandlers = class {
     };
     return ok(response);
   }
+  /**
+   * Open a sealed result, or refuse it.
+   *
+   * The mirror of the daemon's `#openPayload`, and refuses for the same
+   * reason: an outcome that does not verify against the device's pinned key is
+   * an assertion by whoever relayed it, and storing it would let an
+   * intermediary write answers into the app.
+   *
+   * The clear-text `disposition` is checked here rather than trusted. It is on
+   * the wire so a relay can route without opening anything, which means the
+   * one thing it must not be is authoritative — a daemon that sealed an error
+   * and declared `ok` would otherwise have its declaration believed by
+   * everything upstream of this line.
+   */
+  async #openResult(request, runner) {
+    const refuse = (why) => ({ ok: false, failure: fail("bad-request", why) });
+    const opened = await open({
+      envelope: request.envelope,
+      recipientKeys: this.#siteKeys,
+      senderIdentityPublic: runner.device.identity,
+      expected: {
+        jobId: request.jobId,
+        senderKeyId: keyId(runner.device.identity),
+        recipientKeyId: keyId(publicIdentityOf(this.#siteKeys).identity),
+        direction: "result"
+      }
+    });
+    if (!opened.ok) {
+      return refuse("the result did not verify as coming from this device");
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(opened.plaintext);
+    } catch {
+      return refuse("the sealed result was not valid JSON");
+    }
+    const outcome = JobOutcome.safeParse(parsed);
+    if (!outcome.success) return refuse("the sealed result was not an outcome");
+    if (outcome.data.outcome !== request.disposition) {
+      return refuse("the declared disposition is not the one that was sealed");
+    }
+    return { ok: true, value: outcome.data };
+  }
   // -- 5. release -----------------------------------------------------------
   async #release(request, runner) {
     if (request.runnerId !== runner.id) {
-      return fail("unauthorized", "runner id does not match the bearer token");
+      return fail("unauthorized", "runner id does not match the signing key");
     }
     const released = await this.#store.release({
       runnerId: runner.id,
-      jobIds: request.jobIds,
+      leases: request.leases,
       reason: request.reason,
       now: this.#now()
     });
@@ -324,22 +460,54 @@ var ByollmHandlers = class {
   }
 };
 var SERVED_PROTOCOL_VERSION = PROTOCOL_VERSION;
+function leaseOf(job) {
+  if (!job.lease) {
+    throw new Error(
+      `store returned job ${job.id} from claim with no lease \u2014 the store contract requires a claimed job to hold one`
+    );
+  }
+  return job.lease;
+}
 
 // src/http.ts
-import { ENDPOINTS, PROTOCOL_PREFIX } from "@byollm/protocol";
+import {
+  ENDPOINTS,
+  ERROR_STATUS as ERROR_STATUS2,
+  PROTOCOL_PREFIX,
+  checkProtocolVersion
+} from "@byollm/protocol";
 var MAX_BODY_BYTES = 8 * 1024 * 1024;
-function routeEndpoint(pathname) {
-  const index = pathname.lastIndexOf("/");
-  const last = index === -1 ? pathname : pathname.slice(index + 1);
-  return ENDPOINTS.includes(last) ? last : null;
+function normalizeBasePath(basePath) {
+  const trimmed = basePath.endsWith("/") ? basePath.slice(0, -1) : basePath;
+  if (!trimmed.startsWith("/")) {
+    throw new Error(`basePath must start with "/": got ${basePath}`);
+  }
+  if (trimmed.includes("//") || /[?#*]/.test(trimmed)) {
+    throw new Error(`basePath must be a plain path: got ${basePath}`);
+  }
+  return trimmed;
 }
-function bearerFrom(header) {
-  if (!header) return void 0;
-  const match = /^Bearer[ ]+(.+)$/i.exec(header.trim());
-  return match?.[1];
+function routeEndpoint(pathname, basePath = PROTOCOL_PREFIX) {
+  const base = normalizeBasePath(basePath);
+  const path = pathname.endsWith("/") ? pathname.slice(0, -1) : pathname;
+  if (!path.startsWith(`${base}/`)) return null;
+  const rest = path.slice(base.length + 1);
+  return ENDPOINTS.includes(rest) ? rest : null;
+}
+function signatureFrom(headers) {
+  const runnerId = headers.get("x-byollm-runner");
+  const rawIssuedAt = headers.get("x-byollm-issued-at");
+  const signature = headers.get("x-byollm-signature");
+  if (runnerId === null || signature === null || rawIssuedAt === null) {
+    return void 0;
+  }
+  const issuedAt = Number(rawIssuedAt);
+  if (!Number.isFinite(issuedAt)) return void 0;
+  return { runnerId, issuedAt, signature };
 }
 function createFetchHandler(config) {
   const handlers = new ByollmHandlers(config);
+  const basePath = normalizeBasePath(config.basePath ?? PROTOCOL_PREFIX);
   return async function handle(request) {
     if (request.method !== "POST") {
       return json(405, {
@@ -347,11 +515,11 @@ function createFetchHandler(config) {
         message: "protocol endpoints accept POST only"
       });
     }
-    const endpoint = routeEndpoint(new URL(request.url).pathname);
+    const endpoint = routeEndpoint(new URL(request.url).pathname, basePath);
     if (endpoint === null) {
       return json(404, {
         error: "not-found",
-        message: `not a ${PROTOCOL_PREFIX} endpoint`
+        message: `not a ${basePath} endpoint`
       });
     }
     const declared = request.headers.get("content-length");
@@ -362,8 +530,10 @@ function createFetchHandler(config) {
       });
     }
     let body;
+    let rawBody;
     try {
-      const text = await request.text();
+      rawBody = await request.text();
+      const text = rawBody;
       if (text.length > MAX_BODY_BYTES) {
         return json(400, {
           error: "bad-request",
@@ -377,11 +547,17 @@ function createFetchHandler(config) {
         message: "request body is not valid JSON"
       });
     }
-    const result = await handlers.handle(
+    const refusal = checkProtocolVersion(body);
+    if (refusal) {
+      return json(ERROR_STATUS2[refusal.error], refusal);
+    }
+    const result = await handlers.handle(endpoint, body, {
       endpoint,
-      body,
-      bearerFrom(request.headers.get("authorization"))
-    );
+      // The bytes as received. Re-serialising the parsed object would verify
+      // a signature over something the sender never sent.
+      rawBody,
+      signature: signatureFrom(request.headers)
+    });
     const headers = {
       "content-type": "application/json",
       "cache-control": "no-store"
@@ -413,10 +589,11 @@ export {
   generateUserCode,
   hashSecret,
   secretsMatch,
+  generateLeaseId,
   ByollmHandlers,
   SERVED_PROTOCOL_VERSION,
   routeEndpoint,
-  bearerFrom,
+  signatureFrom,
   createFetchHandler
 };
-//# sourceMappingURL=chunk-HL6EYHQ7.js.map
+//# sourceMappingURL=chunk-MGJX6626.js.map