@byollm/protocol 0.1.0-alpha.3 → 0.1.0-alpha.5

package/dist/index.js

@@ -350,6 +350,21 @@ function canTransition(from, to) {
   return TRANSITIONS[from].includes(to);
 }
 var Lease = z4.object({
+  /**
+   * Identifies *this* grant, not just its holder.
+   *
+   * A runner can hold a job, release it, and claim it again — three leases,
+   * one runner id. Without an id for the grant itself, a lease-scoped request
+   * names a mutable target ambiguously, and a replayed release from the first
+   * grant lands on the third: the job returns to the queue while the daemon
+   * is mid-execution, and the work runs twice on the owner's hardware.
+   *
+   * That was a live hole, found in review after signed requests shipped. The
+   * signature scheme's replay argument rests on endpoints being idempotent —
+   * and release *is*, per lease, but not across leases, because nothing in
+   * the request said which one.
+   */
+  id: z4.string().min(1),
   /** The runner holding the lease. */
   runnerId: z4.string().min(1),
   /** Epoch milliseconds after which the claim is void. */
@@ -421,6 +436,333 @@ var DeliveredResult = z4.object({
   outcome: JobOutcome.optional(),
   provenance: ResultProvenance.optional()
 }).strict();
+var SizeClass = z4.enum(["small", "medium", "large", "unbounded"]);
+var SIZE_CLASS_LIMITS = Object.freeze({
+  small: 4e3,
+  medium: 64e3,
+  large: Number.POSITIVE_INFINITY
+});
+function sizeClassCeiling(sizeClass) {
+  if (sizeClass === "unbounded") return Number.POSITIVE_INFINITY;
+  return SIZE_CLASS_LIMITS[sizeClass];
+}
+function sizeClassOf(textChars) {
+  if (textChars <= SIZE_CLASS_LIMITS.small) return "small";
+  if (textChars <= SIZE_CLASS_LIMITS.medium) return "medium";
+  return "large";
+}
+var JobStub = z4.object({
+  id: z4.string().min(1),
+  kind: JobKind,
+  /** The app's id for the user who enqueued it. */
+  owner: z4.string().min(1),
+  audience: Audience,
+  audienceAllow: z4.array(z4.string().min(1)).optional(),
+  sizeClass: SizeClass,
+  /** Reserved for byollm_006. False until streaming exists. */
+  streaming: z4.boolean(),
+  /** Epoch ms after which the work is pointless; bounds ciphertext retention. */
+  deadlineAt: z4.number().int().positive()
+}).strict();
+var ClaimedStub = JobStub.extend({ lease: Lease }).strict();
+
+// src/envelope.ts
+import { createPrivateKey as createPrivateKey2, createPublicKey as createPublicKey2 } from "crypto";
+import sodium from "libsodium-wrappers";
+import { z as z6 } from "zod";
+
+// src/keys.ts
+import {
+  createHash,
+  createPrivateKey,
+  createPublicKey,
+  generateKeyPairSync,
+  sign,
+  verify
+} from "crypto";
+import { z as z5 } from "zod";
+var PublicIdentity = z5.object({
+  /** Raw Ed25519 public key. The pinned one. */
+  identity: z5.string().min(1),
+  /** Raw X25519 public key, for sealing to this party. */
+  encryption: z5.string().min(1),
+  /**
+   * Ed25519 signature over the encryption key, by the identity key.
+   *
+   * This is what stops an upstream substituting an encryption key of its
+   * own while relaying a genuine identity: the receiver pins the identity
+   * and refuses any encryption key not signed by it.
+   */
+  encryptionSig: z5.string().min(1)
+}).strict();
+var StoredKeys = z5.object({
+  version: z5.literal(1),
+  identityPublic: z5.string().min(1),
+  identityPrivate: z5.string().min(1),
+  encryptionPublic: z5.string().min(1),
+  encryptionPrivate: z5.string().min(1),
+  encryptionSig: z5.string().min(1),
+  createdAt: z5.number().int().positive()
+}).strict();
+var ENCRYPTION_KEY_CONTEXT = "byollm/v1/encryption-key";
+function rawPublic(key) {
+  const jwk = key.export({ format: "jwk" });
+  const x = jwk.x;
+  if (typeof x !== "string") throw new Error("key has no raw public component");
+  return x;
+}
+function importPublic(raw, crv) {
+  return createPublicKey({ key: { kty: "OKP", crv, x: raw }, format: "jwk" });
+}
+function importPrivate(stored) {
+  return createPrivateKey({
+    key: Buffer.from(stored, "base64"),
+    type: "pkcs8",
+    format: "der"
+  });
+}
+var exportPrivate = (key) => key.export({ type: "pkcs8", format: "der" }).toString("base64");
+function generateKeys(now) {
+  const identity = generateKeyPairSync("ed25519");
+  const encryption = generateKeyPairSync("x25519");
+  const encryptionPublic = rawPublic(encryption.publicKey);
+  return {
+    version: 1,
+    identityPublic: rawPublic(identity.publicKey),
+    identityPrivate: exportPrivate(identity.privateKey),
+    encryptionPublic,
+    encryptionPrivate: exportPrivate(encryption.privateKey),
+    encryptionSig: sign(
+      null,
+      Buffer.from(`${ENCRYPTION_KEY_CONTEXT}:${encryptionPublic}`),
+      identity.privateKey
+    ).toString("base64url"),
+    createdAt: now
+  };
+}
+function publicIdentityOf(keys) {
+  return {
+    identity: keys.identityPublic,
+    encryption: keys.encryptionPublic,
+    encryptionSig: keys.encryptionSig
+  };
+}
+function verifyPublicIdentity(identity) {
+  try {
+    return verify(
+      null,
+      Buffer.from(`${ENCRYPTION_KEY_CONTEXT}:${identity.encryption}`),
+      importPublic(identity.identity, "Ed25519"),
+      Buffer.from(identity.encryptionSig, "base64url")
+    );
+  } catch {
+    return false;
+  }
+}
+function signWith(keys, data) {
+  return sign(null, data, importPrivate(keys.identityPrivate)).toString(
+    "base64url"
+  );
+}
+function verifyWith(identityPublic, data, signature) {
+  try {
+    return verify(
+      null,
+      data,
+      importPublic(identityPublic, "Ed25519"),
+      Buffer.from(signature, "base64url")
+    );
+  } catch {
+    return false;
+  }
+}
+var ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+function fingerprint(identityPublic) {
+  const digest = createHash("sha256").update(Buffer.from(identityPublic, "base64url")).digest();
+  let bits = 0;
+  let value = 0;
+  let out = "";
+  for (const byte of digest.subarray(0, 15)) {
+    value = value << 8 | byte;
+    bits += 8;
+    while (bits >= 5) {
+      out += ALPHABET.charAt(value >>> bits - 5 & 31);
+      bits -= 5;
+    }
+  }
+  const groups = out.match(/.{1,4}/g) ?? [];
+  return `BYOLLM-${groups.join("-")}`;
+}
+var keyId = (identityPublic) => fingerprint(identityPublic);
+
+// src/envelope.ts
+var readied;
+async function cryptoReady() {
+  readied ??= sodium.ready;
+  await readied;
+}
+var ENVELOPE_MAX_AGE_MS = 24 * 60 * 6e4;
+var EnvelopeDirection = z6.enum(["payload", "result"]);
+var SealedEnvelope = z6.object({
+  /** Base64url `crypto_box_seal` output over the signed plaintext. */
+  ciphertext: z6.string().min(1),
+  /** Who this was sealed to — the recipient checks it is them. */
+  recipientKeyId: z6.string().min(1),
+  /** Who signed it — the recipient checks this against its pin. */
+  senderKeyId: z6.string().min(1),
+  direction: EnvelopeDirection,
+  /**
+   * When this ciphertext stops being worth keeping.
+   *
+   * Carried *on* the envelope rather than recomputed by the opener. An
+   * earlier version derived it from the job's creation time, which meant
+   * two systems had to agree on a timestamp to the millisecond — and they
+   * did not, once a real database rounded it. A bound value that has to be
+   * reconstructed is a bound value that eventually is not.
+   *
+   * Not trusted as written: it is also inside the signature, so a changed
+   * deadline fails to verify.
+   */
+  deadlineAt: z6.number().int().positive()
+}).strict();
+function signedBody(context, plaintext) {
+  return Buffer.from(
+    JSON.stringify({
+      v: "byollm/v1/envelope",
+      jobId: context.jobId,
+      senderKeyId: context.senderKeyId,
+      recipientKeyId: context.recipientKeyId,
+      deadlineAt: context.deadlineAt,
+      direction: context.direction,
+      plaintext
+    }),
+    "utf8"
+  );
+}
+var rawX25519 = (key, part) => {
+  const jwk = key.export({ format: "jwk" });
+  const value = part === "x" ? jwk.x : jwk.d;
+  if (typeof value !== "string") throw new Error("not an X25519 key");
+  return new Uint8Array(Buffer.from(value, "base64url"));
+};
+async function seal(input) {
+  await cryptoReady();
+  const body = signedBody(input.context, input.plaintext);
+  const signature = signWith(input.senderKeys, body);
+  const inner = JSON.stringify({ body: body.toString("base64url"), signature });
+  const recipient = new Uint8Array(
+    Buffer.from(input.recipientEncryptionPublic, "base64url")
+  );
+  const ciphertext = sodium.crypto_box_seal(
+    new Uint8Array(Buffer.from(inner, "utf8")),
+    recipient
+  );
+  return {
+    ciphertext: Buffer.from(ciphertext).toString("base64url"),
+    recipientKeyId: input.context.recipientKeyId,
+    senderKeyId: input.context.senderKeyId,
+    direction: input.context.direction,
+    deadlineAt: input.context.deadlineAt
+  };
+}
+async function open(input) {
+  await cryptoReady();
+  const { envelope, expected } = input;
+  if (envelope.recipientKeyId !== expected.recipientKeyId || envelope.senderKeyId !== expected.senderKeyId || envelope.direction !== expected.direction) {
+    return { ok: false, reason: "not-for-us" };
+  }
+  let inner;
+  try {
+    const priv = createPrivateKey2({
+      key: Buffer.from(input.recipientKeys.encryptionPrivate, "base64"),
+      type: "pkcs8",
+      format: "der"
+    });
+    const pub = createPublicKey2(priv);
+    const opened = sodium.crypto_box_seal_open(
+      new Uint8Array(Buffer.from(envelope.ciphertext, "base64url")),
+      rawX25519(pub, "x"),
+      rawX25519(priv, "d")
+    );
+    inner = Buffer.from(opened).toString("utf8");
+  } catch {
+    return { ok: false, reason: "unopenable" };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(inner);
+  } catch {
+    return { ok: false, reason: "malformed" };
+  }
+  if (typeof parsed.body !== "string" || typeof parsed.signature !== "string") {
+    return { ok: false, reason: "malformed" };
+  }
+  const body = Buffer.from(parsed.body, "base64url");
+  if (!verifyWith(input.senderIdentityPublic, body, parsed.signature)) {
+    return { ok: false, reason: "bad-signature" };
+  }
+  let claims;
+  try {
+    claims = JSON.parse(body.toString("utf8"));
+  } catch {
+    return { ok: false, reason: "malformed" };
+  }
+  if (claims["jobId"] !== expected.jobId || claims["senderKeyId"] !== expected.senderKeyId || claims["recipientKeyId"] !== expected.recipientKeyId || claims["deadlineAt"] !== envelope.deadlineAt || claims["direction"] !== expected.direction) {
+    return { ok: false, reason: "context-mismatch" };
+  }
+  if (typeof claims["plaintext"] !== "string") {
+    return { ok: false, reason: "malformed" };
+  }
+  return { ok: true, plaintext: claims["plaintext"] };
+}
+
+// src/signing.ts
+import { createHash as createHash2 } from "crypto";
+import { z as z7 } from "zod";
+var MAX_CLOCK_SKEW_MS = 12e4;
+var RequestSignature = z7.object({
+  /** Which runner is calling. The server looks up its pinned identity. */
+  runnerId: z7.string().min(1),
+  /** Epoch ms, bounded by {@link MAX_CLOCK_SKEW_MS}. */
+  issuedAt: z7.number().int().positive(),
+  /** Base64url Ed25519 signature over {@link canonicalRequest}. */
+  signature: z7.string().min(1)
+}).strict();
+function canonicalRequest(input) {
+  const digest = createHash2("sha256").update(input.body, "utf8").digest("hex");
+  return Buffer.from(
+    [
+      "byollm/v1/request",
+      input.endpoint,
+      input.runnerId,
+      String(input.issuedAt),
+      digest
+    ].join("\n"),
+    "utf8"
+  );
+}
+function signRequest(keys, input) {
+  return {
+    runnerId: input.runnerId,
+    issuedAt: input.issuedAt,
+    signature: signWith(keys, canonicalRequest(input))
+  };
+}
+function verifyRequest(input) {
+  const skew = input.maxSkewMs ?? MAX_CLOCK_SKEW_MS;
+  if (Math.abs(input.now - input.signature.issuedAt) > skew) return "stale";
+  const ok = verifyWith(
+    input.identityPublic,
+    canonicalRequest({
+      endpoint: input.endpoint,
+      runnerId: input.signature.runnerId,
+      issuedAt: input.signature.issuedAt,
+      body: input.body
+    }),
+    input.signature.signature
+  );
+  return ok ? null : "bad-signature";
+}
 
 // src/musts.ts
 var must = (m) => Object.freeze(m);
@@ -430,31 +772,78 @@ var MUSTS = Object.freeze({
     id: "PAIR_ONE_USER",
     statement: "A runner token MUST be bound to exactly one user; a daemon MUST refuse work not attributable to its paired user.",
     enforcedBy: "both",
+    verifiedBy: "conformance",
     source: "byollm_001 \xA7MUSTs"
   }),
   PAIR_INTERACTIVE: must({
     id: "PAIR_INTERACTIVE",
     statement: "Pairing MUST be interactive (device-code approval in the app's own session); a long-lived pasted secret MUST NOT be accepted as pairing.",
     enforcedBy: "server",
+    verifiedBy: "conformance",
     source: "byollm_001 \xA7Endpoints.1"
   }),
   PAIR_CODE_EXPIRES: must({
     id: "PAIR_CODE_EXPIRES",
     statement: "An unapproved device code MUST expire and MUST NOT be redeemable after expiry.",
     enforcedBy: "server",
+    verifiedBy: "conformance",
     source: "byollm_001 \xA7Endpoints.1"
   }),
   // ---- Typed job kinds --------------------------------------------------
+  VERSION_HANDSHAKE_REQUIRED: must({
+    id: "VERSION_HANDSHAKE_REQUIRED",
+    statement: "Every protocol request MUST declare a protocol version, and a server MUST refuse an absent or unsupported one with a structured error naming what it supports \u2014 never a generic parse failure.",
+    enforcedBy: "both",
+    verifiedBy: "conformance",
+    source: "byollm_009 \xA74"
+  }),
+  KEYS_EXCHANGED_AT_CONSENT: must({
+    id: "KEYS_EXCHANGED_AT_CONSENT",
+    statement: "Pairing MUST exchange both parties' public identities; each side MUST verify that the encryption key is signed by the identity presenting it, and MUST pin the identity. Keys MUST NOT be delivered before approval.",
+    enforcedBy: "both",
+    verifiedBy: "conformance",
+    source: "byollm_009 \xA75"
+  }),
+  REQUESTS_SIGNED_NOT_BEARER: must({
+    id: "REQUESTS_SIGNED_NOT_BEARER",
+    statement: "Every authenticated request MUST be signed by the calling device's pinned identity key, over the endpoint, the runner id, a timestamp and the exact request body. A server MUST NOT accept a bearer credential in place of a signature.",
+    enforcedBy: "both",
+    verifiedBy: "conformance",
+    source: "byollm_009 \xA74.2"
+  }),
+  LEASE_SCOPED_BY_GRANT: must({
+    id: "LEASE_SCOPED_BY_GRANT",
+    statement: "A lease-scoped request MUST name the lease it acts on, and a server MUST apply it only to that lease. Naming the job and the runner is not sufficient: both survive a claim-release-reclaim cycle.",
+    enforcedBy: "both",
+    verifiedBy: "conformance",
+    source: "byollm_009 \xA74.2"
+  }),
+  STUB_METADATA_EXHAUSTIVE: must({
+    id: "STUB_METADATA_EXHAUSTIVE",
+    statement: "A claim MUST answer with stubs carrying exactly the enumerated fields and no payload. An endpoint MUST NOT emit a stub carrying others, and an upstream MUST NOT require any.",
+    enforcedBy: "both",
+    verifiedBy: "conformance",
+    source: "byollm_009 \xA76"
+  }),
+  ENVELOPE_SEALED_AND_SIGNED: must({
+    id: "ENVELOPE_SEALED_AND_SIGNED",
+    statement: "A stored payload MUST be sealed, and MUST be signed by the sender's identity key. An endpoint MUST refuse an envelope whose signature does not verify against the identity it pinned.",
+    enforcedBy: "server",
+    verifiedBy: "conformance",
+    source: "byollm_009 \xA76"
+  }),
   KIND_TYPED_ONLY: must({
     id: "KIND_TYPED_ONLY",
     statement: "Job kinds MUST resolve against handlers baked into the daemon. A daemon MUST refuse an unknown kind rather than guess.",
     enforcedBy: "daemon",
+    verifiedBy: "conformance",
     source: "byollm_001 \xA7Jobs are typed data"
   }),
   KIND_NO_CODE: must({
     id: "KIND_NO_CODE",
     statement: "A server MUST NOT be able to convey code, a shell string, or a path to execute; payloads are data handed to a model only.",
     enforcedBy: "daemon",
+    verifiedBy: "conformance",
     source: "byollm_001 \xA7Jobs are typed data; byollm_004 \xA71"
   }),
   // ---- Capability and claiming -----------------------------------------
@@ -462,18 +851,21 @@ var MUSTS = Object.freeze({
     id: "CLAIM_REQUIRES_CAPABILITY",
     statement: "A daemon MUST NOT be given a job whose kind is absent from its advertised capability matrix.",
     enforcedBy: "both",
+    verifiedBy: "conformance",
     source: "byollm_001 \xA7MUSTs"
   }),
   CAPABILITY_IS_DETECTED: must({
     id: "CAPABILITY_IS_DETECTED",
     statement: "An advertised capability matrix MUST be the intersection of owner config and detected, healthy reality \u2014 never config alone.",
     enforcedBy: "daemon",
+    verifiedBy: "conformance",
     source: "byollm_002 \xA7Routing"
   }),
   CLAIM_ATOMIC: must({
     id: "CLAIM_ATOMIC",
     statement: "Claiming MUST be atomic: a job MUST NOT be handed to two runners concurrently.",
     enforcedBy: "server",
+    verifiedBy: "conformance",
     source: "byollm_001 \xA7Endpoints.2"
   }),
   // ---- Leases -----------------------------------------------------------
@@ -481,12 +873,14 @@ var MUSTS = Object.freeze({
     id: "LEASE_HONORED",
     statement: "A daemon MUST stop work on a job whose lease it has failed to renew, and MUST NOT report a result for an expired lease it no longer holds.",
     enforcedBy: "daemon",
+    verifiedBy: "conformance",
     source: "byollm_001 \xA7MUSTs"
   }),
   LEASE_RECLAIMABLE: must({
     id: "LEASE_RECLAIMABLE",
     statement: "A lease that expires un-renewed MUST make its job claimable again with no loss of the job.",
     enforcedBy: "server",
+    verifiedBy: "conformance",
     source: "byollm_001 \xA7Endpoints.2"
   }),
   // ---- Audience and offer scope ----------------------------------------
@@ -494,48 +888,56 @@ var MUSTS = Object.freeze({
     id: "AUDIENCE_BOTH_SIDES",
     statement: "A job MUST run on a daemon only if the daemon's offer scope admits the job's owner AND the job's audience admits the daemon's owner.",
     enforcedBy: "both",
+    verifiedBy: "conformance",
     source: "byollm_001 \xA7The audience model"
   }),
   SUBSCRIPTION_SELF_LOCK: must({
     id: "SUBSCRIPTION_SELF_LOCK",
     statement: "A subscription-class backend's offer scope MUST be 'self' and MUST NOT be widened by configuration.",
     enforcedBy: "daemon",
+    verifiedBy: "conformance",
     source: "byollm_001 \xA7The audience model"
   }),
   METERED_DEFAULTS_SELF: must({
     id: "METERED_DEFAULTS_SELF",
     statement: "A metered backend's effective offer scope MUST be 'self' unless the owner has explicitly acknowledged spending money on others' work.",
     enforcedBy: "daemon",
+    verifiedBy: "conformance",
     source: "byollm_007 \xA74"
   }),
   METERED_REQUIRES_CEILING: must({
     id: "METERED_REQUIRES_CEILING",
     statement: "A widened metered backend MUST carry a spend ceiling, and the daemon MUST refuse community work once it is reached.",
     enforcedBy: "daemon",
+    verifiedBy: "conformance",
     source: "byollm_007 \xA74"
   }),
   COST_NOT_CONFIGURABLE: must({
     id: "COST_NOT_CONFIGURABLE",
     statement: "A built-in provider's cost class MUST NOT be overridable by configuration.",
     enforcedBy: "daemon",
+    verifiedBy: "conformance",
     source: "byollm_007 \xA72"
   }),
   REMOTE_IS_NEVER_FREE: must({
     id: "REMOTE_IS_NEVER_FREE",
     statement: "A generic HTTP backend whose base URL is not loopback or private MUST be treated as metered.",
     enforcedBy: "daemon",
+    verifiedBy: "conformance",
     source: "byollm_007 \xA72"
   }),
   NAMED_LOCAL_ALLOWLIST: must({
     id: "NAMED_LOCAL_ALLOWLIST",
     statement: "A 'named' job MUST be admitted only by the daemon's own local (server origin, user id) allowlist \u2014 never on the server's assertion alone.",
     enforcedBy: "daemon",
+    verifiedBy: "conformance",
     source: "byollm_001 Rev 1 \xA7B"
   }),
   REFUSAL_NOT_REOFFERED: must({
     id: "REFUSAL_NOT_REOFFERED",
     statement: "A server MUST NOT re-offer a job to a runner that released it with reason 'refused'.",
     enforcedBy: "server",
+    verifiedBy: "conformance",
     source: "byollm_001 Rev 1 \xA7B (loop resolved in build review)"
   }),
   // ---- Revocation and cancel -------------------------------------------
@@ -543,12 +945,14 @@ var MUSTS = Object.freeze({
     id: "REVOCATION_HONORED",
     statement: "A revoked daemon MUST stop claiming and MUST abandon in-flight work by the next heartbeat at the latest.",
     enforcedBy: "daemon",
+    verifiedBy: "conformance",
     source: "byollm_001 \xA7MUSTs"
   }),
   CANCEL_HONORED: must({
     id: "CANCEL_HONORED",
     statement: "A job id in a heartbeat response's cancel list MUST abort that job's in-flight backend call and be reported as 'canceled'.",
     enforcedBy: "daemon",
+    verifiedBy: "conformance",
     source: "byollm_001 Rev 1 \xA7C"
   }),
   // ---- Lifecycle, dependencies, delivery -------------------------------
@@ -556,30 +960,35 @@ var MUSTS = Object.freeze({
     id: "DEPENDS_ON_GATING",
     statement: "A job MUST NOT be claimable until every job in its dependsOn set has reached the 'ok' state.",
     enforcedBy: "server",
+    verifiedBy: "conformance",
     source: "byollm_001 Rev 1 \xA7E"
   }),
   TTL_EXPIRY: must({
     id: "TTL_EXPIRY",
     statement: "An unclaimed job MUST become 'expired' once its TTL elapses, and the TTL clock MUST start when the job becomes claimable, not at enqueue.",
     enforcedBy: "server",
+    verifiedBy: "conformance",
     source: "byollm_001 Rev 1 \xA7D (TTL clock resolved in build review)"
   }),
   NO_RUNNER_SIGNAL: must({
     id: "NO_RUNNER_SIGNAL",
     statement: "A server MUST surface noRunnerAvailable when no runner with matching capability has heartbeated within the liveness window, and MUST NOT raise it for a job still blocked on dependencies.",
     enforcedBy: "server",
+    verifiedBy: "conformance",
     source: "byollm_001 Rev 1 \xA7D"
   }),
   RESULT_IDEMPOTENT: must({
     id: "RESULT_IDEMPOTENT",
     statement: "Result submission MUST be idempotent by job id; the first terminal outcome wins and later submissions MUST NOT change it.",
     enforcedBy: "server",
+    verifiedBy: "conformance",
     source: "byollm_001 \xA7Endpoints.4"
   }),
   RESULT_PROVENANCE: must({
     id: "RESULT_PROVENANCE",
     statement: "A result from a non-'self' job MUST carry its provenance (audience and runner) to the delivery seam so an app never treats volunteer output as first-party.",
     enforcedBy: "server",
+    verifiedBy: "conformance",
     source: "byollm_003 Rev 1 \xA7Return-trip"
   }),
   // ---- The trust surface -------------------------------------------------
@@ -587,6 +996,7 @@ var MUSTS = Object.freeze({
     id: "INGRESS_LOGGED_BEFORE_EXECUTION",
     statement: "Every executed prompt MUST be appended to the local ingress log before execution begins.",
     enforcedBy: "daemon",
+    verifiedBy: "conformance",
     source: "byollm_001 \xA7MUSTs"
   }),
   // ---- Execution isolation (byollm_004) ---------------------------------
@@ -594,178 +1004,263 @@ var MUSTS = Object.freeze({
     id: "NO_SHELL_INTERPOLATION",
     statement: "Process-class backends MUST be invoked with a fixed argv array and the payload delivered on stdin; payload text MUST NOT reach a command line.",
     enforcedBy: "daemon",
+    verifiedBy: "adversarial",
     source: "byollm_004 \xA72"
   }),
   NO_PAYLOAD_ROUTING: must({
     id: "NO_PAYLOAD_ROUTING",
     statement: "Model, backend, base URL, and flags MUST come from owner config only; a payload MUST NOT influence any of them.",
     enforcedBy: "daemon",
+    verifiedBy: "adversarial",
     source: "byollm_004 \xA72"
   }),
   STRIPPED_CHILD_ENV: must({
     id: "STRIPPED_CHILD_ENV",
     statement: "Process-class children MUST spawn with an allowlisted environment, a scratch cwd, no inherited descriptors beyond std streams, and hard timeout and output-size caps.",
     enforcedBy: "daemon",
+    verifiedBy: "adversarial",
     source: "byollm_004 \xA72"
   }),
   HTTP_BASE_URL_SAFE: must({
     id: "HTTP_BASE_URL_SAFE",
     statement: "HTTP-class backends MUST send requests only to the owner-configured base URL and MUST refuse base URLs resolving to cloud-metadata or link-local addresses.",
     enforcedBy: "daemon",
+    verifiedBy: "adversarial",
     source: "byollm_004 Rev 1 \xA7Backend taxonomy"
   }),
   OUTPUT_INERT: must({
     id: "OUTPUT_INERT",
     statement: "Returned text MUST be treated as inert bytes: never evaluated, never written to a payload-named path, never interpolated into a shell or into terminal control sequences when logged.",
     enforcedBy: "daemon",
+    verifiedBy: "adversarial",
     source: "byollm_004 \xA72"
   }),
   COMMUNITY_BUDGETS: must({
     id: "COMMUNITY_BUDGETS",
     statement: "Jobs whose owner is not the daemon's owner MUST be subject to the owner's rate limits, daily cap, and resource budget.",
     enforcedBy: "daemon",
+    verifiedBy: "adversarial",
     source: "byollm_004 \xA74"
   })
 });
 var MUST_IDS = Object.freeze(Object.keys(MUSTS));
+function mustsVerifiedBy(kind) {
+  return MUST_IDS.filter((id) => MUSTS[id].verifiedBy === kind);
+}
 
 // src/wire.ts
-import { z as z5 } from "zod";
+import { z as z8 } from "zod";
 var PROTOCOL_VERSION = "0";
+var SUPPORTED_PROTOCOL_VERSIONS = Object.freeze([
+  PROTOCOL_VERSION
+]);
+var MIN_PROTOCOL_VERSION = SUPPORTED_PROTOCOL_VERSIONS[0] ?? PROTOCOL_VERSION;
+function checkProtocolVersion(body) {
+  const declared = typeof body === "object" && body !== null && Object.hasOwn(body, "protocolVersion") ? body.protocolVersion : void 0;
+  if (typeof declared !== "string" || declared.length === 0) {
+    return {
+      error: "unsupported-protocol-version",
+      message: "this request declared no protocol version. Upgrade the daemon: `npm i -g byollm@alpha`.",
+      supported: SUPPORTED_PROTOCOL_VERSIONS,
+      minimum: MIN_PROTOCOL_VERSION
+    };
+  }
+  if (!SUPPORTED_PROTOCOL_VERSIONS.includes(declared)) {
+    return {
+      error: "unsupported-protocol-version",
+      message: `this server speaks protocol ${SUPPORTED_PROTOCOL_VERSIONS.join(", ")} and the daemon asked for ${declared}. ` + (declared < MIN_PROTOCOL_VERSION ? "Upgrade the daemon: `npm i -g byollm@alpha`." : "This daemon is newer than the server; the server needs upgrading."),
+      supported: SUPPORTED_PROTOCOL_VERSIONS,
+      minimum: MIN_PROTOCOL_VERSION
+    };
+  }
+  return null;
+}
 var PROTOCOL_PREFIX = "/byollm";
 var ENDPOINTS = Object.freeze([
   "pair",
   "claim",
+  "fetch",
   "heartbeat",
   "result",
   "release"
 ]);
-var Capability = z5.object({
+var Capability = z8.object({
   kind: JobKind,
   backendId: BackendIdSchema,
   backendClass: BackendClass,
-  model: z5.string().min(1),
+  model: z8.string().min(1),
   offerScope: OfferScope
 }).strict();
-var CapabilityMatrix = z5.array(Capability);
-var PairStartRequest = z5.object({
-  protocolVersion: z5.literal(PROTOCOL_VERSION),
-  action: z5.literal("start"),
-  daemon: z5.object({
-    version: z5.string().min(1),
+var CapabilityMatrix = z8.array(Capability);
+var PairStartRequest = z8.object({
+  protocolVersion: z8.literal(PROTOCOL_VERSION),
+  action: z8.literal("start"),
+  daemon: z8.object({
+    version: z8.string().min(1),
     /** Shown in the app's runner list so a user can tell their machines apart. */
-    label: z5.string().min(1).max(120),
-    platform: z5.enum(["darwin", "linux", "win32"])
+    label: z8.string().min(1).max(120),
+    platform: z8.enum(["darwin", "linux", "win32"])
   }),
+  /**
+   * This machine's public keys (byollm_009 §5).
+   *
+   * Pairing is where the two parties learn each other's identities, because
+   * it is the one moment a human is already deciding to trust: the approval
+   * click. A key exchanged anywhere else would be a key nobody chose.
+   */
+  device: PublicIdentity,
   capabilities: CapabilityMatrix
 }).strict();
-var PairStartResponse = z5.object({
+var PairStartResponse = z8.object({
   /** Secret the daemon polls with. Never shown to the user. */
-  deviceCode: z5.string().min(20),
+  deviceCode: z8.string().min(20),
   /** Short code the user reads and confirms in the browser. */
-  userCode: z5.string().min(4).max(16),
+  userCode: z8.string().min(4).max(16),
   /** Where the user approves. Must be on the server's own origin. */
-  verificationUrl: z5.url(),
+  verificationUrl: z8.url(),
   /** Epoch ms after which the code is dead ({@link MUSTS.PAIR_CODE_EXPIRES}). */
-  expiresAt: z5.number().int().positive(),
+  expiresAt: z8.number().int().positive(),
   /** How often the daemon may poll. */
-  pollIntervalMs: z5.number().int().min(500).max(6e4)
+  pollIntervalMs: z8.number().int().min(500).max(6e4)
 }).strict();
-var PairPollRequest = z5.object({
-  protocolVersion: z5.literal(PROTOCOL_VERSION),
-  action: z5.literal("poll"),
-  deviceCode: z5.string().min(20)
+var PairPollRequest = z8.object({
+  protocolVersion: z8.literal(PROTOCOL_VERSION),
+  action: z8.literal("poll"),
+  deviceCode: z8.string().min(20)
 }).strict();
-var PairPollResponse = z5.discriminatedUnion("status", [
-  z5.object({ status: z5.literal("pending") }).strict(),
-  z5.object({ status: z5.literal("denied") }).strict(),
-  z5.object({ status: z5.literal("expired") }).strict(),
-  z5.object({
-    status: z5.literal("approved"),
+var PairPollResponse = z8.discriminatedUnion("status", [
+  z8.object({ status: z8.literal("pending") }).strict(),
+  z8.object({ status: z8.literal("denied") }).strict(),
+  z8.object({ status: z8.literal("expired") }).strict(),
+  z8.object({
+    status: z8.literal("approved"),
     /** Bearer token for every later call. Scoped to exactly one user. */
-    runnerToken: z5.string().min(20),
-    runnerId: z5.string().min(1),
+    runnerToken: z8.string().min(20),
+    runnerId: z8.string().min(1),
     /** The app's id for the approving user — this daemon's owner forever. */
-    owner: z5.string().min(1),
+    owner: z8.string().min(1),
     /** Display name for the trust UI, if the app offers one. */
-    ownerLabel: z5.string().optional()
+    ownerLabel: z8.string().optional(),
+    /**
+     * The site's public keys, for the daemon to pin (byollm_009 §5).
+     *
+     * Returned only on approval — a pending or denied poll learns nothing,
+     * so an unapproved code cannot be used to enumerate a site's keys.
+     */
+    site: PublicIdentity
   }).strict()
 ]);
-var PairRequest = z5.discriminatedUnion("action", [
+var PairRequest = z8.discriminatedUnion("action", [
   PairStartRequest,
   PairPollRequest
 ]);
-var ClaimRequest = z5.object({
-  protocolVersion: z5.literal(PROTOCOL_VERSION),
-  runnerId: z5.string().min(1),
+var ClaimRequest = z8.object({
+  protocolVersion: z8.literal(PROTOCOL_VERSION),
+  runnerId: z8.string().min(1),
   /** Re-sent on every claim so a server never matches against a stale matrix. */
   capabilities: CapabilityMatrix,
   /** Upper bound on jobs to return; the server may return fewer. */
-  max: z5.number().int().min(1).max(64)
+  max: z8.number().int().min(1).max(64)
 }).strict();
-var ClaimResponse = z5.object({
-  jobs: z5.array(ClaimedJob),
+var ClaimResponse = z8.object({
+  /**
+   * Stubs, not jobs. The payload arrives from `fetch`, sealed to whichever
+   * device claimed — see {@link JobStub} for the exhaustive metadata list.
+   */
+  jobs: z8.array(ClaimedStub),
   /** Lease duration granted, so the daemon knows its renewal deadline. */
-  leaseMs: z5.number().int().positive()
+  leaseMs: z8.number().int().positive()
 }).strict();
-var HeartbeatRequest = z5.object({
-  protocolVersion: z5.literal(PROTOCOL_VERSION),
-  runnerId: z5.string().min(1),
-  daemonVersion: z5.string().min(1),
+var HeartbeatRequest = z8.object({
+  protocolVersion: z8.literal(PROTOCOL_VERSION),
+  runnerId: z8.string().min(1),
+  daemonVersion: z8.string().min(1),
   capabilities: CapabilityMatrix,
-  /** Jobs this daemon believes it holds; the server renews their leases. */
-  activeJobIds: z5.array(z5.string().min(1)),
+  /**
+   * Leases this daemon believes it holds; the server renews exactly these.
+   *
+   * Lease ids rather than job ids, so a replayed heartbeat cannot renew a
+   * grant the runner no longer holds — see {@link Lease.id}.
+   */
+  activeLeases: z8.array(
+    z8.object({ jobId: z8.string().min(1), leaseId: z8.string().min(1) })
+  ),
   /** True while the owner has the daemon paused; the server stops offering work. */
-  paused: z5.boolean()
+  paused: z8.boolean()
 }).strict();
-var HeartbeatResponse = z5.object({
+var HeartbeatResponse = z8.object({
   /** Once true, the daemon stops claiming and abandons in-flight work. */
-  revoked: z5.boolean(),
+  revoked: z8.boolean(),
   /**
    * Per-job cancel (byollm_001 Rev 1 §C). The daemon aborts these jobs'
    * in-flight backend calls and reports them `canceled`.
    */
-  cancel: z5.array(z5.string().min(1)),
+  cancel: z8.array(z8.string().min(1)),
   /** Jobs whose leases were renewed, with their new expiry. */
-  leases: z5.array(
-    z5.object({
-      jobId: z5.string().min(1),
-      expiresAt: z5.number().int().positive()
+  leases: z8.array(
+    z8.object({
+      jobId: z8.string().min(1),
+      expiresAt: z8.number().int().positive()
     }).strict()
   ),
   /**
    * Jobs the daemon thinks it holds but the server has reassigned or
    * expired. The daemon must stop work on these and not report results.
    */
-  lost: z5.array(z5.string().min(1)),
+  lost: z8.array(z8.string().min(1)),
   /** Server clock, so a daemon with a skewed clock still honors leases. */
-  serverTime: z5.number().int().positive()
+  serverTime: z8.number().int().positive()
 }).strict();
-var ResultRequest = z5.object({
-  protocolVersion: z5.literal(PROTOCOL_VERSION),
-  runnerId: z5.string().min(1),
-  jobId: z5.string().min(1),
-  outcome: JobOutcome,
+var ResultDisposition = z8.enum(["ok", "error", "canceled"]);
+var ResultRequest = z8.object({
+  protocolVersion: z8.literal(PROTOCOL_VERSION),
+  runnerId: z8.string().min(1),
+  jobId: z8.string().min(1),
+  /**
+   * The outcome, sealed to the site and signed by the device.
+   *
+   * The return leg of the payload envelope, and sealed for the same reason:
+   * a model's answer is as sensitive as the prompt that produced it, and an
+   * intermediary that cannot read one must not be handed the other.
+   */
+  envelope: SealedEnvelope,
+  /**
+   * The sealed outcome's discriminator, in the clear.
+   *
+   * Checked against the envelope once opened. It is a routing hint, not a
+   * fact: believing it unverified would let a daemon mark a job `ok` while
+   * sealing an error, and only the app would ever find out.
+   */
+  disposition: ResultDisposition,
   /** Which model actually served it, for the result's provenance. */
-  model: z5.string().min(1),
+  model: z8.string().min(1),
   backendClass: BackendClass,
   /** Wall-clock milliseconds the backend call took. */
-  durationMs: z5.number().int().nonnegative()
+  durationMs: z8.number().int().nonnegative()
 }).strict();
-var ResultResponse = z5.object({
+var ResultResponse = z8.object({
   /**
    * False when the submission lost an idempotency race or the lease was
    * already gone — the daemon should discard, not retry
    * ({@link MUSTS.RESULT_IDEMPOTENT}).
    */
-  accepted: z5.boolean(),
+  accepted: z8.boolean(),
   /** The job's state after this submission. */
-  state: z5.string().min(1)
+  state: z8.string().min(1)
 }).strict();
-var ReleaseRequest = z5.object({
-  protocolVersion: z5.literal(PROTOCOL_VERSION),
-  runnerId: z5.string().min(1),
-  jobIds: z5.array(z5.string().min(1)),
+var ReleaseRequest = z8.object({
+  protocolVersion: z8.literal(PROTOCOL_VERSION),
+  runnerId: z8.string().min(1),
+  /**
+   * Which leases to release — the grant, not just the job.
+   *
+   * A release naming only a job id releases whatever lease exists at the
+   * moment it arrives, which for a replayed request is not the lease the
+   * daemon meant. See {@link Lease.id}.
+   */
+  leases: z8.array(
+    z8.object({ jobId: z8.string().min(1), leaseId: z8.string().min(1) })
+  ),
   /**
    * Why, so the app's runner list can say something true.
    *
@@ -775,12 +1270,12 @@ var ReleaseRequest = z5.object({
    * stop offering that job to that runner, or the pair would spin between
    * claim and release forever.
    */
-  reason: z5.enum(["shutdown", "pause", "revoked", "backend-down", "refused"])
+  reason: z8.enum(["shutdown", "pause", "revoked", "backend-down", "refused"])
 }).strict();
-var ReleaseResponse = z5.object({
-  released: z5.array(z5.string().min(1))
+var ReleaseResponse = z8.object({
+  released: z8.array(z8.string().min(1))
 }).strict();
-var WireErrorCode = z5.enum([
+var WireErrorCode = z8.enum([
   "bad-request",
   "unsupported-protocol-version",
   "unauthorized",
@@ -789,11 +1284,11 @@ var WireErrorCode = z5.enum([
   "rate-limited",
   "server-error"
 ]);
-var WireError = z5.object({
+var WireError = z8.object({
   error: WireErrorCode,
-  message: z5.string().min(1),
+  message: z8.string().min(1),
   /** Seconds; mirrors Retry-After for `rate-limited` and `server-error`. */
-  retryAfter: z5.number().int().nonnegative().optional()
+  retryAfter: z8.number().int().nonnegative().optional()
 }).strict();
 var ERROR_STATUS = Object.freeze({
   "bad-request": 400,
@@ -804,6 +1299,30 @@ var ERROR_STATUS = Object.freeze({
   "rate-limited": 429,
   "server-error": 500
 });
+var FetchRequest = z8.object({
+  protocolVersion: z8.string().min(1),
+  runnerId: z8.string().min(1),
+  jobId: z8.string().min(1),
+  /**
+   * The grant this daemon holds.
+   *
+   * Named, not inferred: a fetch is lease-scoped, and a request that names
+   * only the job would be answerable for whatever lease exists when it
+   * arrives ({@link Lease.id}).
+   */
+  leaseId: z8.string().min(1)
+}).strict();
+var FetchResponse = z8.object({
+  /**
+   * The work, sealed to the device that claimed it — byollm_009 §6.
+   *
+   * Not plaintext. The site opens its own at-rest envelope and re-seals to
+   * the claiming device's key, signed by the site's identity, so the work
+   * is readable only by the machine that took it and only if it came from
+   * the site that machine pinned.
+   */
+  envelope: SealedEnvelope
+}).strict();
 export {
   AUDIENCES,
   Audience,
@@ -819,9 +1338,14 @@ export {
   ClaimRequest,
   ClaimResponse,
   ClaimedJob,
+  ClaimedStub,
   DeliveredResult,
   ENDPOINTS,
+  ENVELOPE_MAX_AGE_MS,
   ERROR_STATUS,
+  EnvelopeDirection,
+  FetchRequest,
+  FetchResponse,
   GeneratePayload,
   HeartbeatRequest,
   HeartbeatResponse,
@@ -833,8 +1357,11 @@ export {
   JobResultError,
   JobResultOk,
   JobState,
+  JobStub,
   KindedPayload,
   Lease,
+  MAX_CLOCK_SKEW_MS,
+  MIN_PROTOCOL_VERSION,
   MUSTS,
   MUST_IDS,
   MatchRefusal,
@@ -848,25 +1375,50 @@ export {
   PairRequest,
   PairStartRequest,
   PairStartResponse,
+  PublicIdentity,
   REFUSAL_MESSAGES,
   ReleaseRequest,
   ReleaseResponse,
+  RequestSignature,
+  ResultDisposition,
   ResultProvenance,
   ResultRequest,
   ResultResponse,
+  SIZE_CLASS_LIMITS,
+  SUPPORTED_PROTOCOL_VERSIONS,
+  SealedEnvelope,
+  SizeClass,
+  StoredKeys,
   TERMINAL_STATES,
   WireError,
   WireErrorCode,
   backendDescriptor,
   canTransition,
+  canonicalRequest,
+  checkProtocolVersion,
+  cryptoReady,
   effectiveOfferScope,
+  fingerprint,
+  generateKeys,
   isBackendId,
   isJobKind,
   isLocalHost,
   isTerminal,
+  keyId,
   matchAudience,
+  mustsVerifiedBy,
+  open,
   payloadTextLength,
   provenanceFor,
-  resolveCost
+  publicIdentityOf,
+  resolveCost,
+  seal,
+  signRequest,
+  signWith,
+  sizeClassCeiling,
+  sizeClassOf,
+  verifyPublicIdentity,
+  verifyRequest,
+  verifyWith
 };
 //# sourceMappingURL=index.js.map