@byollm/protocol 0.1.0-alpha.54 → 0.1.0-alpha.56

package/dist/index.js

@@ -1023,12 +1023,73 @@ function verifyRequest(input) {
   return ok ? null : "bad-signature";
 }
 
-// src/succession.ts
+// src/roster.ts
+import { Buffer as Buffer2 } from "buffer";
 import { z as z8 } from "zod";
+var ROSTER_MAX_AGE_MS = 60 * 6e4;
+var ROSTER_CONTEXT = "byollm/v1/roster";
+var SignedRoster = z8.object({
+  /** Whose devices this roster governs. */
+  owner: z8.string().min(1),
+  /**
+   * Who may have their `team` work run on this owner's devices.
+   *
+   * Owner ids, sorted, so the same membership always produces the same
+   * bytes — a document that differed by iteration order would produce a new
+   * signature every read and no way to tell a change from a shuffle.
+   */
+  members: z8.array(z8.string().min(1)),
+  /**
+   * When the control plane signed it — epoch ms, and the **only** honest
+   * anchor for age.
+   *
+   * Not when the daemon received it. A relay that simply withholds updates
+   * would otherwise keep a removed member served forever, which is the
+   * attack {@link ROSTER_MAX_AGE_MS} exists to bound.
+   */
+  issuedAt: z8.number().int().positive(),
+  /** Base64url Ed25519 over {@link rosterStatement}. */
+  signature: z8.string().min(1)
+}).strict();
+function rosterStatement(input) {
+  return Buffer2.from(
+    [
+      ROSTER_CONTEXT,
+      input.owner,
+      String(input.issuedAt),
+      [...input.members].sort().join("\0")
+    ].join("\n"),
+    "utf8"
+  );
+}
+function signRoster(keys, input) {
+  const members = [...input.members].sort();
+  return {
+    owner: input.owner,
+    members,
+    issuedAt: input.issuedAt,
+    signature: signWith(keys, rosterStatement({ ...input, members }))
+  };
+}
+function verifyRoster(input) {
+  const { roster, owner, now } = input;
+  if (roster.owner !== owner) return "wrong-owner";
+  const age = now - roster.issuedAt;
+  if (age < 0) return "from-the-future";
+  if (age > (input.maxAgeMs ?? ROSTER_MAX_AGE_MS)) return "stale";
+  return verifyWith(
+    input.controlPlanePublic,
+    rosterStatement(roster),
+    roster.signature
+  ) ? null : "bad-signature";
+}
+
+// src/succession.ts
+import { z as z9 } from "zod";
 var SUCCESSION_CONTEXT = "byollm/v1/site-succession";
 var RETIREMENT_WINDOW_MS = 7 * 24 * 60 * 60 * 1e3;
 var MAX_SUCCESSION_CHAIN = 64;
-var Succession = z8.object({
+var Succession = z9.object({
   /**
    * The predecessor's public identity — K1, in full.
    *
@@ -1038,7 +1099,7 @@ var Succession = z8.object({
    */
   identity: PublicIdentity,
   /** K1's signature over the statement naming K1 and its successor. */
-  signature: z8.string().min(1)
+  signature: z9.string().min(1)
 }).strict();
 function successionStatement(fromKeyId, toKeyId) {
   return Buffer.from(`${SUCCESSION_CONTEXT}:${fromKeyId}:${toKeyId}`);
@@ -1517,7 +1578,7 @@ function mustsVerifiedBy(kind) {
 }
 
 // src/wire.ts
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 var PROTOCOL_VERSION = "0";
 var SUPPORTED_PROTOCOL_VERSIONS = Object.freeze([
   PROTOCOL_VERSION
@@ -1560,7 +1621,7 @@ var ENDPOINTS = Object.freeze([
   "result",
   "release"
 ]);
-var Capability = z9.object({
+var Capability = z10.object({
   kind: JobKind,
   /**
    * The owner's name for the service answering this kind — byollm_016.
@@ -1569,7 +1630,7 @@ var Capability = z9.object({
    * that something does. Phase B lets a job select by this name; until then
    * it is what a device page shows and what a default is chosen between.
    */
-  service: z9.string().min(1),
+  service: z10.string().min(1),
   /**
    * Whether this row is the default for its kind.
    *
@@ -1579,27 +1640,27 @@ var Capability = z9.object({
    * alone" would have to unlearn it, and the ones that did not would be
    * quietly wrong. One field now, no second shape later.
    */
-  isDefault: z9.boolean(),
+  isDefault: z10.boolean(),
   backendId: BackendIdSchema,
   backendClass: BackendClass,
-  model: z9.string().min(1),
+  model: z10.string().min(1),
   offerScope: OfferScope
 }).strict();
-var CapabilityMatrix = z9.array(Capability);
-var WithheldKind = z9.object({
+var CapabilityMatrix = z10.array(Capability);
+var WithheldKind = z10.object({
   kind: JobKind,
-  claimants: z9.array(
-    z9.object({ service: z9.string().min(1), offer: OfferScope }).strict()
+  claimants: z10.array(
+    z10.object({ service: z10.string().min(1), offer: OfferScope }).strict()
   ).min(2)
 }).strict();
-var PairStartRequest = z9.object({
-  protocolVersion: z9.literal(PROTOCOL_VERSION),
-  action: z9.literal("start"),
-  daemon: z9.object({
-    version: z9.string().min(1),
+var PairStartRequest = z10.object({
+  protocolVersion: z10.literal(PROTOCOL_VERSION),
+  action: z10.literal("start"),
+  daemon: z10.object({
+    version: z10.string().min(1),
     /** Shown in the app's runner list so a user can tell their machines apart. */
-    label: z9.string().min(1).max(120),
-    platform: z9.enum(["darwin", "linux", "win32"])
+    label: z10.string().min(1).max(120),
+    platform: z10.enum(["darwin", "linux", "win32"])
   }),
   /**
    * This machine's public keys (byollm_009 §5).
@@ -1611,29 +1672,29 @@ var PairStartRequest = z9.object({
   device: PublicIdentity,
   capabilities: CapabilityMatrix
 }).strict();
-var PairStartResponse = z9.object({
+var PairStartResponse = z10.object({
   /** Secret the daemon polls with. Never shown to the user. */
-  deviceCode: z9.string().min(20),
+  deviceCode: z10.string().min(20),
   /** Short code the user reads and confirms in the browser. */
-  userCode: z9.string().min(4).max(16),
+  userCode: z10.string().min(4).max(16),
   /** Where the user approves. Must be on the server's own origin. */
-  verificationUrl: z9.url(),
+  verificationUrl: z10.url(),
   /** Epoch ms after which the code is dead ({@link MUSTS.PAIR_CODE_EXPIRES}). */
-  expiresAt: z9.number().int().positive(),
+  expiresAt: z10.number().int().positive(),
   /** How often the daemon may poll. */
-  pollIntervalMs: z9.number().int().min(500).max(6e4)
+  pollIntervalMs: z10.number().int().min(500).max(6e4)
 }).strict();
-var PairPollRequest = z9.object({
-  protocolVersion: z9.literal(PROTOCOL_VERSION),
-  action: z9.literal("poll"),
-  deviceCode: z9.string().min(20)
+var PairPollRequest = z10.object({
+  protocolVersion: z10.literal(PROTOCOL_VERSION),
+  action: z10.literal("poll"),
+  deviceCode: z10.string().min(20)
 }).strict();
-var PairPollResponse = z9.discriminatedUnion("status", [
-  z9.object({ status: z9.literal("pending") }).strict(),
-  z9.object({ status: z9.literal("denied") }).strict(),
-  z9.object({ status: z9.literal("expired") }).strict(),
-  z9.object({
-    status: z9.literal("approved"),
+var PairPollResponse = z10.discriminatedUnion("status", [
+  z10.object({ status: z10.literal("pending") }).strict(),
+  z10.object({ status: z10.literal("denied") }).strict(),
+  z10.object({ status: z10.literal("expired") }).strict(),
+  z10.object({
+    status: z10.literal("approved"),
     // `runnerToken` is gone — cloud_008 §2.4, finding 37.
     //
     // It was minted here, hashed into `RunnerRecord.tokenHash`, written to
@@ -1650,11 +1711,11 @@ var PairPollResponse = z9.discriminatedUnion("status", [
     // `REQUESTS_SIGNED_NOT_BEARER` was already the rule and was already
     // enforced — every authenticated call is signed by the device's pinned
     // identity key. This removes the thing the MUST is named after.
-    runnerId: z9.string().min(1),
+    runnerId: z10.string().min(1),
     /** The app's id for the approving user — this daemon's owner forever. */
-    owner: z9.string().min(1),
+    owner: z10.string().min(1),
     /** Display name for the trust UI, if the app offers one. */
-    ownerLabel: z9.string().optional(),
+    ownerLabel: z10.string().optional(),
     /**
      * The sites this pairing covers, for the daemon to pin (byollm_009 §5),
      * keyed by each site's identity key id — cloud_009 §5.
@@ -1673,34 +1734,55 @@ var PairPollResponse = z9.discriminatedUnion("status", [
      * runner's lookup is a map read rather than a join across two
      * namespaces.
      */
-    sites: z9.record(z9.string().min(1), PublicIdentity)
+    sites: z10.record(z10.string().min(1), PublicIdentity),
+    /**
+     * The control plane's roster-signing key, pinned here — Amendment G.
+     *
+     * **Pairing is when, and that is the whole question.** Pairing is
+     * already the ceremony where an owner proves out of band that this
+     * device is theirs, so a key learned here rides trust that has already
+     * happened. The rejected alternative is trust-on-first-roster, and it
+     * is rejected because it hands the decision back to the relay: a daemon
+     * that learns whose signature to trust from the first roster to arrive
+     * has its membership authority chosen by whoever controls delivery.
+     *
+     * Optional on the wire, and only on the wire: a direct-mode server has
+     * no control plane and signs no rosters, and a daemon that never
+     * receives one simply serves no `team` job through it. It is not
+     * optional for a hub — a hub that omitted it would be asking devices to
+     * accept rosters from nobody in particular.
+     *
+     * Rotation is Amendment C's, with no path where a roster teaches a
+     * daemon a new key.
+     */
+    controlPlanePublic: z10.string().min(1).optional()
   }).strict()
 ]);
-var PairRequest = z9.discriminatedUnion("action", [
+var PairRequest = z10.discriminatedUnion("action", [
   PairStartRequest,
   PairPollRequest
 ]);
-var ClaimRequest = z9.object({
-  protocolVersion: z9.literal(PROTOCOL_VERSION),
-  runnerId: z9.string().min(1),
+var ClaimRequest = z10.object({
+  protocolVersion: z10.literal(PROTOCOL_VERSION),
+  runnerId: z10.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: z9.number().int().min(1).max(64)
+  max: z10.number().int().min(1).max(64)
 }).strict();
-var ClaimResponse = z9.object({
+var ClaimResponse = z10.object({
   /**
    * Stubs, not jobs. The payload arrives from `fetch`, sealed to whichever
    * device claimed — see {@link JobStub} for the exhaustive metadata list.
    */
-  jobs: z9.array(ClaimedStub),
+  jobs: z10.array(ClaimedStub),
   /** Lease duration granted, so the daemon knows its renewal deadline. */
-  leaseMs: z9.number().int().positive()
+  leaseMs: z10.number().int().positive()
 }).strict();
-var HeartbeatRequest = z9.object({
-  protocolVersion: z9.literal(PROTOCOL_VERSION),
-  runnerId: z9.string().min(1),
-  daemonVersion: z9.string().min(1),
+var HeartbeatRequest = z10.object({
+  protocolVersion: z10.literal(PROTOCOL_VERSION),
+  runnerId: z10.string().min(1),
+  daemonVersion: z10.string().min(1),
   capabilities: CapabilityMatrix,
   /**
    * Kinds this device is withholding, and why it can be said.
@@ -1709,20 +1791,20 @@ var HeartbeatRequest = z9.object({
    * older daemon against a newer hub is simply a device with no withheld
    * kinds rather than a parse failure.
    */
-  withheld: z9.array(WithheldKind).default([]),
+  withheld: z10.array(WithheldKind).default([]),
   /**
    * 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: z9.array(
-    z9.object({ jobId: z9.string().min(1), leaseId: z9.string().min(1) })
+  activeLeases: z10.array(
+    z10.object({ jobId: z10.string().min(1), leaseId: z10.string().min(1) })
   ),
   /** True while the owner has the daemon paused; the server stops offering work. */
-  paused: z9.boolean()
+  paused: z10.boolean()
 }).strict();
-var HeartbeatResponse = z9.object({
+var HeartbeatResponse = z10.object({
   /**
    * The sites this daemon may serve, right now — cloud_008 finding 59.
    *
@@ -1740,7 +1822,7 @@ var HeartbeatResponse = z9.object({
    * rather than being told a second time — two fields for one fact is how
    * they drift.
    */
-  sites: z9.record(z9.string().min(1), PublicIdentity),
+  sites: z10.record(z10.string().min(1), PublicIdentity),
   /**
    * How a site's current key traces back to one this daemon already holds —
    * byollm_009 Amendment C.
@@ -1758,11 +1840,11 @@ var HeartbeatResponse = z9.object({
    * history is public by construction, because a daemon that cannot read it
    * cannot verify it.
    */
-  successions: z9.record(
-    z9.string().min(1),
-    z9.object({
+  successions: z10.record(
+    z10.string().min(1),
+    z10.object({
       /** Oldest last, as the projection carries it. */
-      succeeds: z9.array(Succession).max(MAX_SUCCESSION_CHAIN),
+      succeeds: z10.array(Succession).max(MAX_SUCCESSION_CHAIN),
       /**
        * Until when the superseded key may still sign work — epoch ms.
        *
@@ -1771,7 +1853,7 @@ var HeartbeatResponse = z9.object({
        * window indefinitely would be a two-key site forever, decided by
        * the party this design does not trust.
        */
-      retiringUntil: z9.number().int().positive().optional()
+      retiringUntil: z10.number().int().positive().optional()
     }).strict()
   ).optional(),
   /**
@@ -1784,8 +1866,8 @@ var HeartbeatResponse = z9.object({
    * is the unique grant and the daemon already keys its work by it; this is
    * the same shape `activeLeases` sends in the other direction.
    */
-  cancel: z9.array(
-    z9.object({ jobId: z9.string().min(1), leaseId: z9.string().min(1) }).strict()
+  cancel: z10.array(
+    z10.object({ jobId: z10.string().min(1), leaseId: z10.string().min(1) }).strict()
   ),
   // `leases` is deliberately absent — cloud_008 §1.4b, finding 16.
   //
@@ -1815,11 +1897,11 @@ var HeartbeatResponse = z9.object({
    * ambiguous across sites, and "the lease you no longer hold" is exactly
    * what this field means anyway.
    */
-  lost: z9.array(
-    z9.object({ jobId: z9.string().min(1), leaseId: z9.string().min(1) }).strict()
+  lost: z10.array(
+    z10.object({ jobId: z10.string().min(1), leaseId: z10.string().min(1) }).strict()
   ),
   /** Server clock, so a daemon with a skewed clock still honors leases. */
-  serverTime: z9.number().int().positive(),
+  serverTime: z10.number().int().positive(),
   /**
    * Sites whose disclosure the user must read again before work moves —
    * cloud_008 finding 48, named rather than counted.
@@ -1834,13 +1916,28 @@ var HeartbeatResponse = z9.object({
    * operator stopped it" — one word with two subjects on two halves of one
    * exchange is a confusion nobody untangles from a log.
    */
-  awaitingConsent: z9.array(z9.string().min(1))
+  awaitingConsent: z10.array(z10.string().min(1)),
+  /**
+   * Who this owner's devices may serve `team` work for — Amendment G.
+   *
+   * Carried by the relay and authored by nobody it can reach. The daemon
+   * verifies it against the key pinned at pairing and admits from its own
+   * held copy, so this field is delivery and not instruction: withholding
+   * it narrows a device, and editing it is caught.
+   *
+   * Optional because a roster is a cloud-mode fact — direct mode has no
+   * control plane to author one — and because a daemon that has never
+   * received one must narrow rather than fail. Absent is not "admit
+   * nobody"; {@link ROSTER_MAX_AGE_MS} is what makes absence bite, and it
+   * bites the same way for a roster withheld as for one never sent.
+   */
+  roster: SignedRoster.optional()
 }).strict();
-var ResultDisposition = z9.enum(["ok", "error", "canceled"]);
-var ResultRequest = z9.object({
-  protocolVersion: z9.literal(PROTOCOL_VERSION),
-  runnerId: z9.string().min(1),
-  jobId: z9.string().min(1),
+var ResultDisposition = z10.enum(["ok", "error", "canceled"]);
+var ResultRequest = z10.object({
+  protocolVersion: z10.literal(PROTOCOL_VERSION),
+  runnerId: z10.string().min(1),
+  jobId: z10.string().min(1),
   /**
    * The grant this result was produced under — cloud_008 §1.4a.
    *
@@ -1863,7 +1960,7 @@ var ResultRequest = z9.object({
    * learned once already, when a replayed release yanked a later grant, and
    * it applies here for the same reason.
    */
-  leaseId: z9.string().min(1),
+  leaseId: z10.string().min(1),
   /**
    * The outcome, sealed to the site and signed by the device.
    *
@@ -1895,12 +1992,12 @@ var ResultRequest = z9.object({
   // on it, so it is a class a routing party consumes. Nobody between the
   // two ends consumes these.
 }).strict();
-var ResultResponse = z9.object({
+var ResultResponse = z10.object({
   /**
    * False when this submission wrote nothing — the daemon should discard,
    * not retry ({@link MUSTS.RESULT_IDEMPOTENT}).
    */
-  accepted: z9.boolean(),
+  accepted: z10.boolean(),
   /**
    * True when this device had already recorded this job's result.
    *
@@ -1914,13 +2011,13 @@ var ResultResponse = z9.object({
    * the same refusal it would get for a job that is *not* terminal, so a job
    * id cannot be used as a terminality probe.
    */
-  duplicate: z9.boolean().optional(),
+  duplicate: z10.boolean().optional(),
   /** The job's state after this submission. */
-  state: z9.string().min(1)
+  state: z10.string().min(1)
 }).strict();
-var ReleaseRequest = z9.object({
-  protocolVersion: z9.literal(PROTOCOL_VERSION),
-  runnerId: z9.string().min(1),
+var ReleaseRequest = z10.object({
+  protocolVersion: z10.literal(PROTOCOL_VERSION),
+  runnerId: z10.string().min(1),
   /**
    * Which leases to release — the grant, not just the job.
    *
@@ -1928,8 +2025,8 @@ var ReleaseRequest = z9.object({
    * moment it arrives, which for a replayed request is not the lease the
    * daemon meant. See {@link Lease.id}.
    */
-  leases: z9.array(
-    z9.object({ jobId: z9.string().min(1), leaseId: z9.string().min(1) })
+  leases: z10.array(
+    z10.object({ jobId: z10.string().min(1), leaseId: z10.string().min(1) })
   ),
   /**
    * Why, so the app's runner list can say something true.
@@ -1940,12 +2037,12 @@ var ReleaseRequest = z9.object({
    * stop offering that job to that runner, or the pair would spin between
    * claim and release forever.
    */
-  reason: z9.enum(["shutdown", "pause", "revoked", "backend-down", "refused"])
+  reason: z10.enum(["shutdown", "pause", "revoked", "backend-down", "refused"])
 }).strict();
-var ReleaseResponse = z9.object({
-  released: z9.array(z9.string().min(1))
+var ReleaseResponse = z10.object({
+  released: z10.array(z10.string().min(1))
 }).strict();
-var WireErrorCode = z9.enum([
+var WireErrorCode = z10.enum([
   "bad-request",
   "unsupported-protocol-version",
   // "We do not know who you are." Exactly 401, and only that — cloud_008
@@ -1995,9 +2092,9 @@ var WireErrorCode = z9.enum([
   "rate-limited",
   "server-error"
 ]);
-var WireError = z9.object({
+var WireError = z10.object({
   error: WireErrorCode,
-  message: z9.string().min(1),
+  message: z10.string().min(1),
   /**
    * What this server speaks, on `unsupported-protocol-version` — §B.4.
    *
@@ -2011,10 +2108,10 @@ var WireError = z9.object({
    * Modelled the way `clock-skew`'s two fields already are — code-specific
    * extras, refused on any other code by the refinement below.
    */
-  supported: z9.array(z9.string().min(1)).optional(),
-  minimum: z9.string().min(1).optional(),
+  supported: z10.array(z10.string().min(1)).optional(),
+  minimum: z10.string().min(1).optional(),
   /** Seconds; mirrors Retry-After for `rate-limited` and `server-error`. */
-  retryAfter: z9.number().int().nonnegative().optional(),
+  retryAfter: z10.number().int().nonnegative().optional(),
   /**
    * The server's clock, and the window it allows. `clock-skew` only.
    *
@@ -2024,8 +2121,8 @@ var WireError = z9.object({
    * heartbeat response returns the same value, and so does every `Date`
    * header.
    */
-  serverTime: z9.number().int().positive().optional(),
-  maxSkewMs: z9.number().int().positive().optional()
+  serverTime: z10.number().int().positive().optional(),
+  maxSkewMs: z10.number().int().positive().optional()
 }).strict().superRefine((error, ctx) => {
   const skew = error.error === "clock-skew";
   const carried = error.serverTime !== void 0 || error.maxSkewMs !== void 0;
@@ -2076,16 +2173,16 @@ var ERROR_STATUS = Object.freeze({
   "rate-limited": 429,
   "server-error": 500
 });
-var FetchRequest = z9.object({
+var FetchRequest = z10.object({
   // `literal`, like every other request — V1-17. This one said
   // `string().min(1)`, so a daemon speaking a version this server does not
   // know got past the handshake on the one endpoint that hands over a
   // sealed payload. The version check exists so that a mismatch is a named
   // refusal rather than a schema failure three fields later; here it was
   // neither.
-  protocolVersion: z9.literal(PROTOCOL_VERSION),
-  runnerId: z9.string().min(1),
-  jobId: z9.string().min(1),
+  protocolVersion: z10.literal(PROTOCOL_VERSION),
+  runnerId: z10.string().min(1),
+  jobId: z10.string().min(1),
   /**
    * The grant this daemon holds.
    *
@@ -2093,9 +2190,9 @@ var FetchRequest = z9.object({
    * only the job would be answerable for whatever lease exists when it
    * arrives ({@link Lease.id}).
    */
-  leaseId: z9.string().min(1)
+  leaseId: z10.string().min(1)
 }).strict();
-var FetchResponse = z9.object({
+var FetchResponse = z10.object({
   /**
    * The work, sealed to the device that claimed it — byollm_009 §6.
    *
@@ -2164,6 +2261,8 @@ export {
   PublicIdentity,
   REFUSAL_MESSAGES,
   RETIREMENT_WINDOW_MS,
+  ROSTER_CONTEXT,
+  ROSTER_MAX_AGE_MS,
   RefusalReason,
   ReleaseRequest,
   ReleaseResponse,
@@ -2178,6 +2277,7 @@ export {
   SUPPORTED_PROTOCOL_VERSIONS,
   SealedEnvelope,
   SealedOutcome,
+  SignedRoster,
   SizeClass,
   StoredKeys,
   Succession,
@@ -2210,8 +2310,10 @@ export {
   provenanceFor,
   publicIdentityOf,
   resolveCost,
+  rosterStatement,
   seal,
   signRequest,
+  signRoster,
   signSiteRequest,
   signSuccession,
   signWith,
@@ -2221,6 +2323,7 @@ export {
   verifyLink,
   verifyPublicIdentity,
   verifyRequest,
+  verifyRoster,
   verifySiteRequest,
   verifyWith,
   walkSuccession