@byollm/server 0.1.0-alpha.1 → 0.1.0-alpha.11

package/dist/index.js

@@ -1,17 +1,19 @@
 import {
   ByollmHandlers,
   SERVED_PROTOCOL_VERSION,
-  bearerFrom,
   createFetchHandler,
   generateDeviceCode,
   generateJobId,
+  generateLeaseId,
   generateRunnerId,
   generateRunnerToken,
   generateUserCode,
   hashSecret,
+  resealForDevice,
   routeEndpoint,
-  secretsMatch
-} from "./chunk-HL6EYHQ7.js";
+  secretsMatch,
+  signatureFrom
+} from "./chunk-4NIHWQAT.js";
 import {
   NoRunnerAvailableError,
   PollingDelivery,
@@ -20,19 +22,238 @@ import {
 
 // src/app.ts
 import {
+  ENVELOPE_MAX_AGE_MS,
+  KindedPayload,
+  keyId as keyId2,
+  payloadTextLength,
+  publicIdentityOf as publicIdentityOf2,
+  seal,
+  sizeClassOf,
   backendDescriptor,
   matchAudience
 } from "@byollm/protocol";
+
+// src/cloud.ts
+import {
+  JobOutcome,
+  keyId,
+  open,
+  publicIdentityOf,
+  provenanceFor,
+  signSiteRequest
+} from "@byollm/protocol";
+var CloudLane = class {
+  #options;
+  #store;
+  #siteKeys;
+  #now;
+  #fetch;
+  constructor(deps) {
+    this.#options = deps.options;
+    this.#store = deps.store;
+    this.#siteKeys = deps.siteKeys;
+    this.#now = deps.now;
+    this.#fetch = deps.options.fetch ?? globalThis.fetch;
+  }
+  /**
+   * Publish a job's stub for routing.
+   *
+   * The stub and nothing else — byollm_009 §6 makes that exhaustive by
+   * construction, so this cannot leak a payload even by mistake: there is no
+   * field on `JobStub` to put one in.
+   */
+  async publish(record) {
+    const stub = {
+      id: record.id,
+      kind: record.kind,
+      owner: record.owner,
+      audience: record.audience,
+      ...record.audienceAllow === void 0 ? {} : { audienceAllow: [...record.audienceAllow] },
+      sizeClass: record.sizeClass,
+      streaming: false,
+      // The relay needs *a* deadline to bound routing. A job without one gets
+      // the envelope's, which is the outer bound on how long the ciphertext
+      // is worth carrying — never longer than the work could possibly matter.
+      deadlineAt: record.deadlineAt ?? record.createdAt + ENVELOPE_TTL_FALLBACK
+    };
+    await this.#post("enqueue", {
+      siteId: this.#options.siteId,
+      stub
+    });
+  }
+  /**
+   * One cycle: seal for anything claimed, collect anything finished.
+   *
+   * Idempotent and safe to call as often as you like. Exposed as a single
+   * cycle rather than hidden behind a timer so a caller decides its own
+   * cadence — a serverless site runs it on a cron, a long-lived one on an
+   * interval, and a test runs it exactly when it means to.
+   */
+  async pump() {
+    const sealed = [];
+    const refused = [];
+    const completed = [];
+    const pending = await this.#get("pending");
+    for (const claim of pending.jobs) {
+      const record = await this.#store.get(claim.jobId);
+      if (!record) continue;
+      const resealed = await resealForDevice({
+        siteKeys: this.#siteKeys,
+        job: {
+          id: record.id,
+          envelope: record.envelope,
+          createdAt: record.createdAt
+        },
+        device: claim.device
+      });
+      if (!resealed.ok) {
+        refused.push(claim.jobId);
+        continue;
+      }
+      await this.#store.adopt({
+        jobId: claim.jobId,
+        leaseId: claim.leaseId,
+        expiresAt: claim.awaitingUntil,
+        now: this.#now()
+      });
+      await this.#post("payload", {
+        siteId: this.#options.siteId,
+        jobId: claim.jobId,
+        envelope: resealed.envelope
+      });
+      sealed.push(claim.jobId);
+    }
+    const finished = await this.#get("results");
+    for (const done of finished.jobs) {
+      const record = await this.#store.get(done.jobId);
+      if (!record || record.state === "ok" || record.state === "error") {
+        continue;
+      }
+      const outcome = await this.#openResult(done);
+      if (!outcome) {
+        refused.push(done.jobId);
+        continue;
+      }
+      await this.#store.complete({
+        jobId: done.jobId,
+        // The grant, not the machine: this site never paired with the device
+        // that ran it, and the signature it verified above is the stronger
+        // claim about who did.
+        holder: { by: "lease", leaseId: done.leaseId },
+        outcome,
+        provenance: provenanceFor({
+          audience: record.audience,
+          runnerId: done.runnerId,
+          runnerOwner: keyId(done.device.identity),
+          backendClass: "http",
+          model: "unknown"
+        }),
+        now: this.#now()
+      });
+      completed.push(done.jobId);
+    }
+    return { sealed, completed, refused };
+  }
+  /**
+   * Open a sealed result and verify it came from the device that claimed it.
+   *
+   * The relay says which device ran the job; this checks that claim against a
+   * signature the relay cannot produce. A relay that named the wrong device
+   * gets a refusal, not a stored result — which is what keeps `RELAY_BLIND`
+   * from quietly becoming `RELAY_TRUSTED`.
+   */
+  async #openResult(done) {
+    const opened = await open({
+      envelope: done.envelope,
+      recipientKeys: this.#siteKeys,
+      senderIdentityPublic: done.device.identity,
+      expected: {
+        jobId: done.jobId,
+        senderKeyId: keyId(done.device.identity),
+        recipientKeyId: keyId(publicIdentityOf(this.#siteKeys).identity),
+        direction: "result"
+      }
+    });
+    if (!opened.ok) return null;
+    let parsed;
+    try {
+      parsed = JSON.parse(opened.plaintext);
+    } catch {
+      return null;
+    }
+    const outcome = JobOutcome.safeParse(parsed);
+    if (!outcome.success) return null;
+    if (outcome.data.outcome !== done.disposition) return null;
+    return outcome.data;
+  }
+  /**
+   * Sign a site-plane call with this site's identity key.
+   *
+   * The same scheme the daemon uses against an upstream, because the site is
+   * in the same position: an outbound caller whose key the relay already holds
+   * for other reasons. Nothing else authenticates this plane — a relay that
+   * took the `siteId` in a body at face value would let anyone enqueue work in
+   * a site's name and read who claimed it.
+   */
+  #headers(endpoint, rawBody) {
+    const signature = signSiteRequest(this.#siteKeys, {
+      endpoint,
+      siteId: this.#options.siteId,
+      issuedAt: this.#now(),
+      body: rawBody
+    });
+    return {
+      "x-byollm-site": this.#options.siteId,
+      "x-byollm-issued-at": String(signature.issuedAt),
+      "x-byollm-signature": signature.signature
+    };
+  }
+  async #post(endpoint, body) {
+    const rawBody = JSON.stringify(body);
+    const response = await this.#fetch(
+      `${this.#options.relayOrigin}/relay/site/${endpoint}`,
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          ...this.#headers(endpoint, rawBody)
+        },
+        body: rawBody
+      }
+    );
+    return response.json();
+  }
+  async #get(endpoint) {
+    const url = `${this.#options.relayOrigin}/relay/site/${endpoint}?siteId=${encodeURIComponent(this.#options.siteId)}`;
+    const response = await this.#fetch(url, {
+      headers: this.#headers(endpoint, "")
+    });
+    return response.json();
+  }
+};
+var ENVELOPE_TTL_FALLBACK = 24 * 60 * 6e4;
+
+// src/app.ts
 var DEFAULT_LIVENESS_MS = 35e3;
 var ByollmApp = class {
   #store;
+  #siteKeys;
   #now;
   #livenessMs;
   #delivery;
+  /** Present only in the cloud lane; the site's side of the relay. */
+  cloud;
   constructor(options) {
     this.#store = options.store;
+    this.#siteKeys = options.siteKeys;
     this.#now = options.now ?? Date.now;
     this.#livenessMs = options.livenessMs ?? DEFAULT_LIVENESS_MS;
+    this.cloud = options.lane === void 0 ? void 0 : new CloudLane({
+      options: options.lane,
+      store: options.store,
+      siteKeys: options.siteKeys,
+      now: this.#now
+    });
     const deps = {
       ...options.noRunnerGraceMs === void 0 ? {} : { graceMs: options.noRunnerGraceMs },
       read: (jobId) => this.result(jobId),
@@ -66,7 +287,45 @@ var ByollmApp = class {
    * the app is obliged to disclose that to whoever reads it.
    */
   async enqueue(input) {
-    const record = await this.#store.create(input, this.#now());
+    const parsed = KindedPayload.safeParse({
+      kind: input.kind,
+      payload: input.payload
+    });
+    if (!parsed.success) {
+      const detail = parsed.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ");
+      throw new Error(`invalid ${input.kind} payload \u2014 ${detail}`);
+    }
+    const createdAt = this.#now();
+    const envelopeDeadlineAt = createdAt + ENVELOPE_MAX_AGE_MS;
+    const jobId = input.id ?? generateJobId();
+    const senderKeyId = keyId2(publicIdentityOf2(this.#siteKeys).identity);
+    const envelope = await seal({
+      plaintext: JSON.stringify(parsed.data.payload),
+      senderKeys: this.#siteKeys,
+      recipientEncryptionPublic: this.#siteKeys.encryptionPublic,
+      context: {
+        jobId,
+        senderKeyId,
+        recipientKeyId: senderKeyId,
+        deadlineAt: envelopeDeadlineAt,
+        direction: "payload"
+      }
+    });
+    const record = await this.#store.create(
+      {
+        ...input,
+        id: jobId,
+        envelope,
+        sizeClass: sizeClassOf(
+          payloadTextLength({
+            kind: input.kind,
+            payload: parsed.data.payload
+          })
+        )
+      },
+      createdAt
+    );
+    await this.cloud?.publish(record);
     return {
       id: record.id,
       record,
@@ -136,7 +395,18 @@ var ByollmApp = class {
         {
           owner: runner.owner,
           offerScope: capability.offerScope,
-          account: backendDescriptor(capability.backendId).account,
+          // A generic backend's cost depends on its base URL, which the
+          // server never sees; assume the expensive reading (byollm_007 §4).
+          cost: backendDescriptor(capability.backendId).cost ?? "metered",
+          // Consent is the daemon's to hold, and it has already applied it:
+          // the offer scope arriving here is the *effective* one, so a
+          // metered backend nobody agreed to share advertises `self` and is
+          // refused by the scope rule above. Re-deriving consent from
+          // `false` here would instead refuse every backend an owner
+          // deliberately shared, because the server has no way to learn they
+          // did — the signal would be wrong in the direction that breaks
+          // working setups.
+          spend: { acknowledged: true },
           // Same conservative assumption the claim path makes: the server
           // cannot see a remote daemon's local allowlist (protocol §4.2).
           locallyAllows: () => true
@@ -218,6 +488,45 @@ function normalizeUserCode(input) {
   return bare.length === 8 ? `${bare.slice(0, 4)}-${bare.slice(4)}` : bare;
 }
 
+// src/keys.ts
+import { StoredKeys, generateKeys, publicIdentityOf as publicIdentityOf3 } from "@byollm/protocol";
+import { fingerprint } from "@byollm/protocol";
+var generateSiteKeys = (now = Date.now()) => generateKeys(now);
+function siteKeysFromEnv(variable = "BYOLLM_SITE_KEYS", env = process.env) {
+  const raw = env[variable];
+  if (raw === void 0 || raw === "") {
+    throw new Error(
+      `${variable} is not set. Generate a site identity once with \`npx @byollm/server keygen\` and set it as ${variable}. Do not generate keys at startup: every instance would get a different identity and daemons would pin one and be refused by another.`
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(Buffer.from(raw, "base64").toString("utf8"));
+  } catch {
+    throw new Error(
+      `${variable} is not base64-encoded JSON. It should be exactly what \`npx @byollm/server keygen\` printed.`
+    );
+  }
+  const result = StoredKeys.safeParse(parsed);
+  if (!result.success) {
+    throw new Error(
+      `${variable} does not contain a valid site identity. Regenerate it with \`npx @byollm/server keygen\` \u2014 and if this site has already paired daemons, they will need to pair again.`
+    );
+  }
+  return result.data;
+}
+function formatSiteKeys(keys) {
+  const encoded = Buffer.from(JSON.stringify(keys)).toString("base64");
+  return `# Set this as BYOLLM_SITE_KEYS. It is a secret: it is this site's
+# identity, and anything holding it can be this site.
+BYOLLM_SITE_KEYS=${encoded}
+
+# Fingerprint (not secret \u2014 show it to users so they can check what
+# their daemon pinned):
+# ${fingerprint(publicIdentityOf3(keys).identity)}
+`;
+}
+
 // src/memory.ts
 import {
   backendDescriptor as backendDescriptor2,
@@ -236,7 +545,7 @@ var MemoryStore = class {
   }
   // -- jobs ---------------------------------------------------------------
   create(input, now) {
-    const id = input.id ?? generateJobId();
+    const id = input.id;
     const existing = this.#jobs.get(id);
     if (existing) return Promise.resolve(existing);
     const dependsOn = [...input.dependsOn ?? []];
@@ -246,7 +555,8 @@ var MemoryStore = class {
     const job = {
       id,
       kind: input.kind,
-      payload: input.payload,
+      envelope: input.envelope,
+      sizeClass: input.sizeClass,
       audience: input.audience ?? "self",
       owner: input.owner,
       audienceAllow: input.audienceAllow ? [...input.audienceAllow] : void 0,
@@ -264,7 +574,7 @@ var MemoryStore = class {
       provenance: null,
       updatedAt: now
     };
-    this.#jobs.set(id, job);
+    this.#write(id, job);
     return Promise.resolve(job);
   }
   get(jobId) {
@@ -283,13 +593,16 @@ var MemoryStore = class {
         ...job,
         state: "claimed",
         lease: {
+          // A fresh id per grant. Two claims of the same job by the same
+          // runner are two different leases, and must be distinguishable.
+          id: generateLeaseId(),
           runnerId: args.runnerId,
           expiresAt: args.now + args.leaseMs
         },
         attempts: job.attempts + 1,
         updatedAt: args.now
       };
-      this.#jobs.set(job.id, updated);
+      this.#write(job.id, updated);
       claimed.push(updated);
     }
     return Promise.resolve(claimed);
@@ -313,9 +626,16 @@ var MemoryStore = class {
       {
         owner: args.runnerOwner,
         offerScope: capability.offerScope,
-        // From the registry, not a local guess — the subscription self-lock
-        // must mean the same thing on both sides of the wire.
-        account: backendDescriptor2(capability.backendId).account,
+        // From the registry, not a local guess — the cost rules must mean the
+        // same thing on both sides of the wire. The server cannot see a
+        // remote daemon's base URL, so a generic backend with no declared
+        // cost is treated as metered: the expensive side, and the daemon
+        // refuses anyway if it disagrees (byollm_007 §2).
+        cost: backendDescriptor2(capability.backendId).cost ?? "metered",
+        // Nor can it see the owner's spend consent. It offers; the daemon is
+        // the enforcing side and releases with `refused` if its own rules say
+        // no — the same shape as the `named` allowlist.
+        spend: { acknowledged: true },
         // The server cannot see a remote daemon's local allowlist and must
         // not pretend to (protocol §4.2). It admits the job here; the daemon
         // is the enforcing side and releases with `refused` if its own list
@@ -329,9 +649,9 @@ var MemoryStore = class {
     this.#expireDueSync(args.now);
     const renewed = [];
     const lost = [];
-    for (const jobId of args.jobIds) {
+    for (const { jobId, leaseId } of args.leases) {
       const job = this.#jobs.get(jobId);
-      if (!job || job.lease?.runnerId !== args.runnerId) {
+      if (!job || job.lease?.runnerId !== args.runnerId || job.lease.id !== leaseId) {
         lost.push(jobId);
         continue;
       }
@@ -340,16 +660,40 @@ var MemoryStore = class {
         continue;
       }
       const expiresAt = args.now + args.leaseMs;
-      this.#jobs.set(jobId, {
+      this.#write(jobId, {
         ...job,
         state: "running",
-        lease: { runnerId: args.runnerId, expiresAt },
+        // Renewal extends the existing grant; it does not mint a new one.
+        lease: { ...job.lease, expiresAt },
         updatedAt: args.now
       });
       renewed.push({ jobId, expiresAt });
     }
     return Promise.resolve({ renewed, lost });
   }
+  adopt(args) {
+    const job = this.#jobs.get(args.jobId);
+    if (!job) return Promise.resolve(null);
+    if (job.state !== "queued" && job.state !== "claimed") {
+      return Promise.resolve(null);
+    }
+    if (job.lease && job.lease.id !== args.leaseId) {
+      return Promise.resolve(null);
+    }
+    const updated = {
+      ...job,
+      state: "claimed",
+      lease: {
+        id: args.leaseId,
+        // No runner: this site never paired with the machine holding it.
+        runnerId: "",
+        expiresAt: args.expiresAt
+      },
+      updatedAt: args.now
+    };
+    this.#write(updated.id, updated);
+    return Promise.resolve(updated);
+  }
   complete(args) {
     const job = this.#jobs.get(args.jobId);
     if (!job) return Promise.resolve({ accepted: false, job: null });
@@ -359,7 +703,8 @@ var MemoryStore = class {
     if (job.state === "expired") {
       return Promise.resolve({ accepted: false, job });
     }
-    if (job.lease?.runnerId !== args.runnerId) {
+    const holds = args.holder.by === "runner" ? job.lease?.runnerId === args.holder.runnerId : job.lease?.id === args.holder.leaseId;
+    if (!holds) {
       return Promise.resolve({ accepted: false, job });
     }
     const state = args.outcome.outcome === "ok" ? "ok" : args.outcome.outcome === "canceled" ? "canceled" : "error";
@@ -371,7 +716,7 @@ var MemoryStore = class {
       provenance: args.provenance,
       updatedAt: args.now
     };
-    this.#jobs.set(job.id, updated);
+    this.#write(job.id, updated);
     this.#cancelRequests.delete(job.id);
     if (state === "ok") this.#unblockDependents(job.id, args.now);
     return Promise.resolve({ accepted: true, job: updated });
@@ -392,16 +737,66 @@ var MemoryStore = class {
         (depId) => this.#jobs.get(depId)?.state === "ok"
       );
       if (ready) {
-        this.#jobs.set(job.id, { ...job, claimableAt: now, updatedAt: now });
+        this.#write(job.id, { ...job, claimableAt: now, updatedAt: now });
+      }
+    }
+  }
+  /**
+   * Watchers, by job id (byollm_009 §8.3).
+   *
+   * A `Set` per job so an unsubscribe removes exactly the handler it
+   * registered — two waiters on the same job are ordinary, and removing by
+   * job id alone would silently cancel someone else's wait.
+   */
+  #watchers = /* @__PURE__ */ new Map();
+  subscribe(jobId, onChange) {
+    const existing = this.#watchers.get(jobId) ?? /* @__PURE__ */ new Set();
+    existing.add(onChange);
+    this.#watchers.set(jobId, existing);
+    let live = true;
+    return () => {
+      if (!live) return;
+      live = false;
+      const set = this.#watchers.get(jobId);
+      set?.delete(onChange);
+      if (set?.size === 0) this.#watchers.delete(jobId);
+    };
+  }
+  /**
+   * The single write path for a job.
+   *
+   * Every mutation goes through here so notification cannot be forgotten by
+   * a future one. Nine call sites existed when the push seam was added, and
+   * "remember to notify" is not a property nine call sites keep.
+   */
+  #write(jobId, record) {
+    this.#jobs.set(jobId, record);
+    this.#notify(jobId);
+  }
+  /**
+   * Tell anyone watching that a job changed.
+   *
+   * A throwing watcher must not corrupt the store's own bookkeeping, so each
+   * is isolated: this runs inside write paths, and one bad listener taking
+   * out an unrelated write would be a far worse failure than a missed
+   * notification.
+   */
+  #notify(jobId) {
+    for (const watcher of this.#watchers.get(jobId) ?? []) {
+      try {
+        watcher();
+      } catch {
       }
     }
   }
   release(args) {
     const released = [];
-    for (const jobId of args.jobIds) {
+    for (const { jobId, leaseId } of args.leases) {
       const job = this.#jobs.get(jobId);
-      if (!job || job.lease?.runnerId !== args.runnerId) continue;
-      this.#jobs.set(jobId, {
+      if (!job || job.lease?.runnerId !== args.runnerId || job.lease.id !== leaseId) {
+        continue;
+      }
+      this.#write(jobId, {
         ...job,
         state: "queued",
         lease: null,
@@ -443,7 +838,7 @@ var MemoryStore = class {
           claimableAt: now,
           updatedAt: now
         };
-        this.#jobs.set(job.id, requeued);
+        this.#write(job.id, requeued);
         changed.push(requeued);
       }
     }
@@ -458,7 +853,7 @@ var MemoryStore = class {
         lease: null,
         updatedAt: now
       };
-      this.#jobs.set(job.id, expired);
+      this.#write(job.id, expired);
       changed.push(expired);
     }
     return changed;
@@ -473,7 +868,7 @@ var MemoryStore = class {
         lease: null,
         updatedAt: now
       };
-      this.#jobs.set(jobId, canceled);
+      this.#write(jobId, canceled);
       return Promise.resolve(canceled);
     }
     if (job.state === "claimed" || job.state === "running") {
@@ -525,6 +920,9 @@ var MemoryStore = class {
       id: args.runnerId,
       owner: args.owner,
       tokenHash: args.tokenHash,
+      // Carried from the pairing, not re-supplied at approval: the user
+      // approved a specific machine, and the runner must be that machine.
+      device: pairing.device,
       label: pairing.label,
       platform: pairing.platform,
       daemonVersion: pairing.daemonVersion,
@@ -613,22 +1011,26 @@ function capabilityFor(capabilities, kind) {
 export {
   ByollmApp,
   ByollmHandlers,
+  CloudLane,
   MemoryStore,
   NoRunnerAvailableError,
   PollingDelivery,
   ResultTimeoutError,
   SERVED_PROTOCOL_VERSION,
-  bearerFrom,
   capabilityFor,
   createFetchHandler,
+  formatSiteKeys,
   generateDeviceCode,
   generateJobId,
   generateRunnerId,
   generateRunnerToken,
+  generateSiteKeys,
   generateUserCode,
   hashSecret,
   normalizeUserCode,
   routeEndpoint,
-  secretsMatch
+  secretsMatch,
+  signatureFrom,
+  siteKeysFromEnv
 };
 //# sourceMappingURL=index.js.map