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

package/dist/chunk-QTRX2LSF.js

@@ -0,0 +1,659 @@
+// src/ids.ts
+import {
+  createHash,
+  randomBytes,
+  randomUUID,
+  timingSafeEqual
+} from "crypto";
+var USER_CODE_ALPHABET = "ABCDEFGHJKMNPQRTWXYZ2346789";
+function generateDeviceCode() {
+  return randomBytes(32).toString("base64url");
+}
+function generateRunnerId() {
+  return `runner_${randomUUID()}`;
+}
+function generateJobId() {
+  return randomUUID();
+}
+function generateUserCode() {
+  const chars = [];
+  while (chars.length < 8) {
+    for (const byte of randomBytes(16)) {
+      const limit = 256 - 256 % USER_CODE_ALPHABET.length;
+      if (byte >= limit) continue;
+      const symbol = USER_CODE_ALPHABET[byte % USER_CODE_ALPHABET.length];
+      if (symbol === void 0) continue;
+      chars.push(symbol);
+      if (chars.length === 8) break;
+    }
+  }
+  return `${chars.slice(0, 4).join("")}-${chars.slice(4).join("")}`;
+}
+function hashSecret(secret) {
+  return createHash("sha256").update(secret, "utf8").digest("hex");
+}
+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 {
+  FetchRequest,
+  SealedOutcome,
+  keyId as keyId2,
+  open as open2,
+  publicIdentityOf as publicIdentityOf2,
+  RequestSignature,
+  verifyRequest,
+  verifyPublicIdentity,
+  ClaimRequest,
+  ERROR_STATUS,
+  HeartbeatRequest,
+  PairRequest,
+  PROTOCOL_VERSION,
+  ReleaseRequest,
+  ResultRequest,
+  provenanceFor
+} from "@byollm/protocol";
+
+// src/reseal.ts
+import {
+  ENVELOPE_MAX_AGE_MS,
+  keyId,
+  open,
+  publicIdentityOf,
+  seal
+} from "@byollm/protocol";
+async function resealForDevice(input) {
+  const senderKeyId = keyId(publicIdentityOf(input.siteKeys).identity);
+  const opened = await open({
+    envelope: input.job.envelope,
+    recipientKeys: input.siteKeys,
+    senderIdentityPublic: input.siteKeys.identityPublic,
+    expected: {
+      jobId: input.job.id,
+      senderKeyId,
+      recipientKeyId: senderKeyId,
+      direction: "payload"
+    }
+  });
+  if (!opened.ok) {
+    return { ok: false, reason: "unopenable" };
+  }
+  const envelope = await seal({
+    plaintext: opened.plaintext,
+    senderKeys: input.siteKeys,
+    recipientEncryptionPublic: input.device.encryption,
+    context: {
+      jobId: input.job.id,
+      senderKeyId,
+      recipientKeyId: keyId(input.device.identity),
+      // From the record, never recomputed from a fresh clock read — the
+      // envelope's own deadline is what the signature bound.
+      deadlineAt: input.job.createdAt + ENVELOPE_MAX_AGE_MS,
+      direction: "payload"
+    }
+  });
+  return { ok: true, envelope };
+}
+
+// src/records.ts
+function deadlineFor(job, now) {
+  return job.deadlineAt ?? (job.claimableAt ?? now) + job.ttlMs;
+}
+
+// src/handlers.ts
+var DEFAULTS = {
+  leaseMs: 6e4,
+  pairingTtlMs: 10 * 6e4,
+  pollIntervalMs: 2e3
+};
+function fail(error, message, retryAfterSeconds) {
+  return {
+    status: ERROR_STATUS[error],
+    body: {
+      error,
+      message,
+      ...retryAfterSeconds === void 0 ? {} : { retryAfter: retryAfterSeconds }
+    },
+    ...retryAfterSeconds === void 0 ? {} : { retryAfterSeconds }
+  };
+}
+function ok(body) {
+  return { status: 200, body };
+}
+var ByollmHandlers = class {
+  #store;
+  #verificationUrl;
+  #leaseMs;
+  #pairingTtlMs;
+  #pollIntervalMs;
+  #now;
+  #siteKeys;
+  /** This site's identity key id — Amendment A's `stub.site`. Derived once. */
+  #siteKeyId;
+  constructor(config) {
+    this.#store = config.store;
+    if (!verifyPublicIdentity(publicIdentityOf2(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.#siteKeyId = keyId2(publicIdentityOf2(config.siteKeys).identity);
+    this.#verificationUrl = config.verificationUrl;
+    this.#leaseMs = config.leaseMs ?? DEFAULTS.leaseMs;
+    this.#pairingTtlMs = config.pairingTtlMs ?? DEFAULTS.pairingTtlMs;
+    this.#pollIntervalMs = config.pollIntervalMs ?? DEFAULTS.pollIntervalMs;
+    this.#now = config.now ?? Date.now;
+  }
+  /**
+   * Dispatch one protocol call.
+   *
+   * @param endpoint - which of the five, already routed from the path
+   * @param body - the parsed JSON request body, untrusted
+   * @param auth - the signature and the exact bytes it covers
+   */
+  async handle(endpoint, body, auth) {
+    switch (endpoint) {
+      case "pair":
+        return this.#pair(body);
+      case "claim":
+        return this.#authed(auth, body, ClaimRequest, this.#claim.bind(this));
+      case "heartbeat":
+        return this.#authed(
+          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(auth, body, ResultRequest, this.#result.bind(this));
+      case "release":
+        return this.#authed(
+          auth,
+          body,
+          ReleaseRequest,
+          this.#release.bind(this)
+        );
+    }
+  }
+  /**
+   * Shared preamble for the four authenticated endpoints: verify the
+   * signature, reject a revoked runner, and parse the body.
+   *
+   * Authentication happens before schema validation so a stranger probing the
+   * endpoint learns nothing about the wire format.
+   */
+  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.getRunner(signature.data.runnerId);
+    if (!runner) {
+      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");
+    }
+    const parsed = schema.safeParse(body);
+    if (!parsed.success || parsed.data === void 0) {
+      return fail("bad-request", "request body failed schema validation");
+    }
+    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 resealed = await resealForDevice({
+      siteKeys: this.#siteKeys,
+      job: { id: job.id, envelope: job.envelope, createdAt: job.createdAt },
+      device: runner.device
+    });
+    if (!resealed.ok) {
+      return fail("server-error", "this job's payload could not be opened");
+    }
+    return ok({ envelope: resealed.envelope });
+  }
+  // -- 1. pair --------------------------------------------------------------
+  async #pair(body) {
+    const parsed = PairRequest.safeParse(body);
+    if (!parsed.success) {
+      return fail("bad-request", "pair request failed schema validation");
+    }
+    const request = parsed.data;
+    const now = this.#now();
+    if (request.action === "start") {
+      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",
+        owner: null,
+        runnerId: null,
+        collected: false,
+        label: request.daemon.label,
+        platform: request.daemon.platform,
+        daemonVersion: request.daemon.version,
+        capabilities: request.capabilities,
+        expiresAt,
+        createdAt: now
+      });
+      const response = {
+        deviceCode,
+        userCode,
+        verificationUrl: this.#verificationUrl,
+        expiresAt,
+        pollIntervalMs: this.#pollIntervalMs
+      };
+      return ok(response);
+    }
+    const pairing = await this.#store.getPairingByDeviceCodeHash(
+      hashSecret(request.deviceCode)
+    );
+    if (!pairing) {
+      return fail("not-found", "unknown device code");
+    }
+    if (pairing.state === "denied") {
+      return ok({ status: "denied" });
+    }
+    if (pairing.expiresAt <= now && pairing.state === "pending") {
+      return ok({ status: "expired" });
+    }
+    if (pairing.state === "approved" && !pairing.collected && pairing.runnerId !== null && pairing.owner !== null) {
+      const response = {
+        status: "approved",
+        runnerId: pairing.runnerId,
+        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: publicIdentityOf2(this.#siteKeys)
+      };
+      await this.#store.consumePairingToken(pairing.deviceCodeHash);
+      return ok(response);
+    }
+    if (pairing.state === "approved") {
+      return fail("not-found", "this pairing has already been collected");
+    }
+    return ok({ status: "pending" });
+  }
+  // -- 2. claim -------------------------------------------------------------
+  async #claim(request, runner) {
+    if (request.runnerId !== runner.id) {
+      return fail("unauthorized", "runner id does not match the signing key");
+    }
+    const now = this.#now();
+    const jobs = await this.#store.claim({
+      runnerId: runner.id,
+      runnerOwner: runner.owner,
+      capabilities: request.capabilities,
+      max: request.max,
+      leaseMs: this.#leaseMs,
+      now
+    });
+    const response = {
+      jobs: jobs.map((job) => ({
+        id: job.id,
+        kind: job.kind,
+        audience: job.audience,
+        owner: job.owner,
+        // This site, named by its identity key id — Amendment A §A.3. The
+        // daemon pinned this exact value at pairing, so it can check the stub
+        // against the envelope it later opens rather than taking our word for
+        // which site sent it. On this plane that is redundant, which is the
+        // point: the direct and relayed stubs are the same shape, and a daemon
+        // serving both cannot tell which upstream it is talking to.
+        site: this.#siteKeyId,
+        // 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: deadlineFor(job, now),
+        // `audienceAllow` is not sent — cloud_008 §0.2. The list stays on
+        // `JobRecord`, where `claim` already filtered candidates with it; the
+        // daemon's own allowlist is what decides `named` (byollm_001 Rev 1
+        // §B) and always was.
+        //
+        // Removing it from `JobStub` did **not** make this line a type error.
+        // A conditional spread is not excess-property-checked, so the field
+        // would have gone on being sent to a daemon whose `.strict()` parse
+        // now rejects the entire claim response — every daemon on the version
+        // pair, refusing all work, for a field nobody read. Worth stating
+        // where it happened: the schema is the contract, and the compiler
+        // does not enforce it through a spread.
+        // 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
+    };
+    return ok(response);
+  }
+  // -- 3. heartbeat ---------------------------------------------------------
+  async #heartbeat(request, runner) {
+    if (request.runnerId !== runner.id) {
+      return fail("unauthorized", "runner id does not match the signing key");
+    }
+    const now = this.#now();
+    const revoked = runner.revokedAt !== null;
+    if (revoked) {
+      const held = await this.#store.listClaimedBy(runner.id);
+      const response2 = {
+        revoked: true,
+        cancel: [],
+        lost: held.map((job) => job.id),
+        serverTime: now
+      };
+      return ok(response2);
+    }
+    await this.#store.touchRunner({
+      runnerId: runner.id,
+      capabilities: request.capabilities,
+      daemonVersion: request.daemonVersion,
+      paused: request.paused,
+      now
+    });
+    const { lost } = await this.#store.renewLeases({
+      runnerId: runner.id,
+      leases: request.activeLeases,
+      leaseMs: this.#leaseMs,
+      now
+    });
+    const cancel = await this.#store.listCancelRequests(runner.id);
+    const response = {
+      revoked: false,
+      cancel,
+      lost: [...lost],
+      serverTime: now
+    };
+    return ok(response);
+  }
+  // -- 4. result ------------------------------------------------------------
+  async #result(request, runner) {
+    if (request.runnerId !== runner.id) {
+      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,
+      runnerOwner: runner.owner,
+      // From the envelope the device signed, not from the request beside it
+      // — cloud_008 §2.5. A daemon can no longer seal one answer and declare
+      // it came from a different model.
+      backendClass: outcome.value.ran.backendClass,
+      model: outcome.value.ran.model
+    });
+    const {
+      accepted,
+      duplicate,
+      job: updated
+    } = await this.#store.complete({
+      jobId: request.jobId,
+      // Who is asking, for the duplicate answer only — §3.6. Authorisation
+      // is `holder`, below, and still is.
+      runnerId: runner.id,
+      // The grant, not the runner — cloud_008 §1.4a. `CompleteHolder`'s own
+      // docstring already called the lease "the more exact check anyway";
+      // this plane simply had no lease id to give it until now.
+      holder: { by: "lease", leaseId: request.leaseId },
+      outcome: outcome.value.outcome,
+      provenance,
+      now
+    });
+    const response = {
+      accepted,
+      // Only when true — cloud_008 §3.6. Absent means "not a duplicate", and
+      // an optional field that is always present is a required one wearing a
+      // question mark.
+      ...duplicate === true ? { duplicate: true } : {},
+      state: updated?.state ?? job.state
+    };
+    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 open2({
+      envelope: request.envelope,
+      recipientKeys: this.#siteKeys,
+      senderIdentityPublic: runner.device.identity,
+      expected: {
+        jobId: request.jobId,
+        senderKeyId: keyId2(runner.device.identity),
+        recipientKeyId: keyId2(publicIdentityOf2(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 sealed = SealedOutcome.safeParse(parsed);
+    if (!sealed.success) return refuse("the sealed result was not an outcome");
+    if (sealed.data.outcome.outcome !== request.disposition) {
+      return refuse("the declared disposition is not the one that was sealed");
+    }
+    return { ok: true, value: sealed.data };
+  }
+  // -- 5. release -----------------------------------------------------------
+  async #release(request, runner) {
+    if (request.runnerId !== runner.id) {
+      return fail("unauthorized", "runner id does not match the signing key");
+    }
+    const released = await this.#store.release({
+      runnerId: runner.id,
+      leases: request.leases,
+      reason: request.reason,
+      now: this.#now()
+    });
+    const response = { released };
+    return ok(response);
+  }
+};
+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,
+  ERROR_STATUS as ERROR_STATUS2,
+  PROTOCOL_PREFIX,
+  checkProtocolVersion
+} from "@byollm/protocol";
+var MAX_BODY_BYTES = 8 * 1024 * 1024;
+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 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, {
+        error: "bad-request",
+        message: "protocol endpoints accept POST only"
+      });
+    }
+    const endpoint = routeEndpoint(new URL(request.url).pathname, basePath);
+    if (endpoint === null) {
+      return json(404, {
+        error: "not-found",
+        message: `not a ${basePath} endpoint`
+      });
+    }
+    const declared = request.headers.get("content-length");
+    if (declared !== null && Number(declared) > MAX_BODY_BYTES) {
+      return json(400, {
+        error: "bad-request",
+        message: "request body too large"
+      });
+    }
+    let body;
+    let rawBody;
+    try {
+      rawBody = await request.text();
+      const text = rawBody;
+      if (text.length > MAX_BODY_BYTES) {
+        return json(400, {
+          error: "bad-request",
+          message: "request body too large"
+        });
+      }
+      body = JSON.parse(text);
+    } catch {
+      return json(400, {
+        error: "bad-request",
+        message: "request body is not valid JSON"
+      });
+    }
+    const refusal = checkProtocolVersion(body);
+    if (refusal) {
+      return json(ERROR_STATUS2[refusal.error], refusal);
+    }
+    const result = await handlers.handle(endpoint, body, {
+      endpoint,
+      // 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"
+    };
+    if (result.retryAfterSeconds !== void 0) {
+      headers["retry-after"] = String(result.retryAfterSeconds);
+    }
+    return new Response(JSON.stringify(result.body), {
+      status: result.status,
+      headers
+    });
+  };
+}
+function json(status, body) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      "content-type": "application/json",
+      "cache-control": "no-store"
+    }
+  });
+}
+
+export {
+  generateDeviceCode,
+  generateRunnerId,
+  generateJobId,
+  generateUserCode,
+  hashSecret,
+  secretsMatch,
+  generateLeaseId,
+  deadlineFor,
+  resealForDevice,
+  ByollmHandlers,
+  SERVED_PROTOCOL_VERSION,
+  routeEndpoint,
+  signatureFrom,
+  createFetchHandler
+};
+//# sourceMappingURL=chunk-QTRX2LSF.js.map