@byollm/protocol 0.1.0-alpha.31 → 0.1.0-alpha.32

package/dist/index.js

@@ -855,6 +855,65 @@ function verifyRequest(input) {
   return ok ? null : "bad-signature";
 }
 
+// src/succession.ts
+import { z as z8 } 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({
+  /**
+   * The predecessor's public identity — K1, in full.
+   *
+   * The whole identity rather than the key id, because a daemon meeting a
+   * chain it has not seen before has to *verify* each link, and a key id is
+   * a fingerprint: enough to compare, never enough to check a signature.
+   */
+  identity: PublicIdentity,
+  /** K1's signature over the statement naming K1 and its successor. */
+  signature: z8.string().min(1)
+}).strict();
+function successionStatement(fromKeyId, toKeyId) {
+  return Buffer.from(`${SUCCESSION_CONTEXT}:${fromKeyId}:${toKeyId}`);
+}
+function signSuccession(previous, next) {
+  return {
+    identity: {
+      identity: previous.identityPublic,
+      encryption: previous.encryptionPublic,
+      encryptionSig: previous.encryptionSig
+    },
+    signature: signWith(
+      previous,
+      successionStatement(keyId(previous.identityPublic), keyId(next.identity))
+    )
+  };
+}
+function verifyLink(link, toKeyId) {
+  if (!verifyPublicIdentity(link.identity)) return false;
+  return verifyWith(
+    link.identity.identity,
+    successionStatement(keyId(link.identity.identity), toKeyId),
+    link.signature
+  );
+}
+function walkSuccession(input) {
+  const { current, chain, approved } = input;
+  if (chain.length === 0) return { path: [current], failure: "no-chain" };
+  if (chain.length > MAX_SUCCESSION_CHAIN)
+    return { path: [current], failure: "too-long" };
+  const steps = [...chain].reverse();
+  const path = [current];
+  let succeeding = current;
+  for (const link of steps) {
+    if (!verifyLink(link, succeeding)) return { path, failure: "broken-link" };
+    const previous = keyId(link.identity.identity);
+    path.unshift(previous);
+    if (approved(previous)) return { path, from: previous };
+    succeeding = previous;
+  }
+  return { path, failure: "unknown-origin" };
+}
+
 // src/musts.ts
 function kindsOf(must2) {
   return typeof must2.verifiedBy === "string" ? [must2.verifiedBy] : must2.verifiedBy;
@@ -918,8 +977,20 @@ var MUSTS = Object.freeze({
     // upstream sends and which the fence above does not see. That was the
     // bypass: the pin was deleted with the id, so the comparison had nothing
     // to compare against and the substitution arrived as a stranger.
+    // **Not `conformance`, and that is a live gap rather than a judgement.**
+    // Amendment C's succession clause is a rule about two implementations
+    // agreeing, which is what a conformance check is for — but rotating a
+    // site's key is not something `ConformanceTarget` can express, and adding
+    // an optional hook that most targets omit would produce a check reporting
+    // success for a reason unrelated to the property it claims. That is this
+    // project's most-repeated bug, and it is not worth reintroducing for a
+    // stronger-sounding word in a table. The rotation path is verified by
+    // `site-rotation.test.ts` (both directions, against the shipped runner)
+    // and `relay/test/rotation.test.ts` (both planes, against the reference
+    // relay); the missing piece is a second *independent* implementation to
+    // check them against, and there is not one yet.
     verifiedBy: ["construction", "adversarial"],
-    source: "byollm_009 \xA7B.2"
+    source: "byollm_009 \xA7B.2, Amendment C"
   }),
   KEYS_EXCHANGED_AT_CONSENT: must({
     id: "KEYS_EXCHANGED_AT_CONSENT",
@@ -1257,7 +1328,7 @@ function mustsVerifiedBy(kind) {
 }
 
 // src/wire.ts
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 var PROTOCOL_VERSION = "0";
 var SUPPORTED_PROTOCOL_VERSIONS = Object.freeze([
   PROTOCOL_VERSION
@@ -1300,22 +1371,22 @@ var ENDPOINTS = Object.freeze([
   "result",
   "release"
 ]);
-var Capability = z8.object({
+var Capability = z9.object({
   kind: JobKind,
   backendId: BackendIdSchema,
   backendClass: BackendClass,
-  model: z8.string().min(1),
+  model: z9.string().min(1),
   offerScope: OfferScope
 }).strict();
-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),
+var CapabilityMatrix = z9.array(Capability);
+var PairStartRequest = z9.object({
+  protocolVersion: z9.literal(PROTOCOL_VERSION),
+  action: z9.literal("start"),
+  daemon: z9.object({
+    version: z9.string().min(1),
     /** Shown in the app's runner list so a user can tell their machines apart. */
-    label: z8.string().min(1).max(120),
-    platform: z8.enum(["darwin", "linux", "win32"])
+    label: z9.string().min(1).max(120),
+    platform: z9.enum(["darwin", "linux", "win32"])
   }),
   /**
    * This machine's public keys (byollm_009 §5).
@@ -1327,29 +1398,29 @@ var PairStartRequest = z8.object({
   device: PublicIdentity,
   capabilities: CapabilityMatrix
 }).strict();
-var PairStartResponse = z8.object({
+var PairStartResponse = z9.object({
   /** Secret the daemon polls with. Never shown to the user. */
-  deviceCode: z8.string().min(20),
+  deviceCode: z9.string().min(20),
   /** Short code the user reads and confirms in the browser. */
-  userCode: z8.string().min(4).max(16),
+  userCode: z9.string().min(4).max(16),
   /** Where the user approves. Must be on the server's own origin. */
-  verificationUrl: z8.url(),
+  verificationUrl: z9.url(),
   /** Epoch ms after which the code is dead ({@link MUSTS.PAIR_CODE_EXPIRES}). */
-  expiresAt: z8.number().int().positive(),
+  expiresAt: z9.number().int().positive(),
   /** How often the daemon may poll. */
-  pollIntervalMs: z8.number().int().min(500).max(6e4)
+  pollIntervalMs: z9.number().int().min(500).max(6e4)
 }).strict();
-var PairPollRequest = z8.object({
-  protocolVersion: z8.literal(PROTOCOL_VERSION),
-  action: z8.literal("poll"),
-  deviceCode: z8.string().min(20)
+var PairPollRequest = z9.object({
+  protocolVersion: z9.literal(PROTOCOL_VERSION),
+  action: z9.literal("poll"),
+  deviceCode: z9.string().min(20)
 }).strict();
-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"),
+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"),
     // `runnerToken` is gone — cloud_008 §2.4, finding 37.
     //
     // It was minted here, hashed into `RunnerRecord.tokenHash`, written to
@@ -1366,11 +1437,11 @@ var PairPollResponse = z8.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: z8.string().min(1),
+    runnerId: z9.string().min(1),
     /** The app's id for the approving user — this daemon's owner forever. */
-    owner: z8.string().min(1),
+    owner: z9.string().min(1),
     /** Display name for the trust UI, if the app offers one. */
-    ownerLabel: z8.string().optional(),
+    ownerLabel: z9.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.
@@ -1389,34 +1460,34 @@ var PairPollResponse = z8.discriminatedUnion("status", [
      * runner's lookup is a map read rather than a join across two
      * namespaces.
      */
-    sites: z8.record(z8.string().min(1), PublicIdentity)
+    sites: z9.record(z9.string().min(1), PublicIdentity)
   }).strict()
 ]);
-var PairRequest = z8.discriminatedUnion("action", [
+var PairRequest = z9.discriminatedUnion("action", [
   PairStartRequest,
   PairPollRequest
 ]);
-var ClaimRequest = z8.object({
-  protocolVersion: z8.literal(PROTOCOL_VERSION),
-  runnerId: z8.string().min(1),
+var ClaimRequest = z9.object({
+  protocolVersion: z9.literal(PROTOCOL_VERSION),
+  runnerId: z9.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: z8.number().int().min(1).max(64)
+  max: z9.number().int().min(1).max(64)
 }).strict();
-var ClaimResponse = z8.object({
+var ClaimResponse = z9.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),
+  jobs: z9.array(ClaimedStub),
   /** Lease duration granted, so the daemon knows its renewal deadline. */
-  leaseMs: z8.number().int().positive()
+  leaseMs: z9.number().int().positive()
 }).strict();
-var HeartbeatRequest = z8.object({
-  protocolVersion: z8.literal(PROTOCOL_VERSION),
-  runnerId: z8.string().min(1),
-  daemonVersion: z8.string().min(1),
+var HeartbeatRequest = z9.object({
+  protocolVersion: z9.literal(PROTOCOL_VERSION),
+  runnerId: z9.string().min(1),
+  daemonVersion: z9.string().min(1),
   capabilities: CapabilityMatrix,
   /**
    * Leases this daemon believes it holds; the server renews exactly these.
@@ -1424,13 +1495,13 @@ var HeartbeatRequest = z8.object({
    * 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) })
+  activeLeases: z9.array(
+    z9.object({ jobId: z9.string().min(1), leaseId: z9.string().min(1) })
   ),
   /** True while the owner has the daemon paused; the server stops offering work. */
-  paused: z8.boolean()
+  paused: z9.boolean()
 }).strict();
-var HeartbeatResponse = z8.object({
+var HeartbeatResponse = z9.object({
   /**
    * The sites this daemon may serve, right now — cloud_008 finding 59.
    *
@@ -1448,7 +1519,40 @@ var HeartbeatResponse = z8.object({
    * rather than being told a second time — two fields for one fact is how
    * they drift.
    */
-  sites: z8.record(z8.string().min(1), PublicIdentity),
+  sites: z9.record(z9.string().min(1), PublicIdentity),
+  /**
+   * How a site's current key traces back to one this daemon already holds —
+   * byollm_009 Amendment C.
+   *
+   * Keyed by the same id as `sites`, and **additive on purpose**: `sites`
+   * remains the one statement of which key is current, and this says only
+   * how that key got there. Two fields for one fact is how they drift; this
+   * is two facts, and the second is evidence about the first.
+   *
+   * Optional because a site that has never rotated has no chain, which is
+   * every site today. A daemon that receives one for an id it already holds
+   * ignores it: the pin it has is the pin it approved.
+   *
+   * §12 carries what this adds to the metadata surface — a site's rotation
+   * history is public by construction, because a daemon that cannot read it
+   * cannot verify it.
+   */
+  successions: z9.record(
+    z9.string().min(1),
+    z9.object({
+      /** Oldest last, as the projection carries it. */
+      succeeds: z9.array(Succession).max(MAX_SUCCESSION_CHAIN),
+      /**
+       * Until when the superseded key may still sign work — epoch ms.
+       *
+       * The daemon holds its own clock against this, for the reason it
+       * holds its own allowlist: a projection that could extend the
+       * window indefinitely would be a two-key site forever, decided by
+       * the party this design does not trust.
+       */
+      retiringUntil: z9.number().int().positive().optional()
+    }).strict()
+  ).optional(),
   /**
    * Per-job cancel (byollm_001 Rev 1 §C). The daemon aborts these jobs'
    * in-flight backend calls and reports them `canceled`.
@@ -1459,8 +1563,8 @@ var HeartbeatResponse = z8.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: z8.array(
-    z8.object({ jobId: z8.string().min(1), leaseId: z8.string().min(1) }).strict()
+  cancel: z9.array(
+    z9.object({ jobId: z9.string().min(1), leaseId: z9.string().min(1) }).strict()
   ),
   // `leases` is deliberately absent — cloud_008 §1.4b, finding 16.
   //
@@ -1490,11 +1594,11 @@ var HeartbeatResponse = z8.object({
    * ambiguous across sites, and "the lease you no longer hold" is exactly
    * what this field means anyway.
    */
-  lost: z8.array(
-    z8.object({ jobId: z8.string().min(1), leaseId: z8.string().min(1) }).strict()
+  lost: z9.array(
+    z9.object({ jobId: z9.string().min(1), leaseId: z9.string().min(1) }).strict()
   ),
   /** Server clock, so a daemon with a skewed clock still honors leases. */
-  serverTime: z8.number().int().positive(),
+  serverTime: z9.number().int().positive(),
   /**
    * Sites whose disclosure the user must read again before work moves —
    * cloud_008 finding 48, named rather than counted.
@@ -1509,13 +1613,13 @@ var HeartbeatResponse = z8.object({
    * operator stopped it" — one word with two subjects on two halves of one
    * exchange is a confusion nobody untangles from a log.
    */
-  awaitingConsent: z8.array(z8.string().min(1))
+  awaitingConsent: z9.array(z9.string().min(1))
 }).strict();
-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),
+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),
   /**
    * The grant this result was produced under — cloud_008 §1.4a.
    *
@@ -1538,7 +1642,7 @@ var ResultRequest = z8.object({
    * learned once already, when a replayed release yanked a later grant, and
    * it applies here for the same reason.
    */
-  leaseId: z8.string().min(1),
+  leaseId: z9.string().min(1),
   /**
    * The outcome, sealed to the site and signed by the device.
    *
@@ -1570,12 +1674,12 @@ var ResultRequest = z8.object({
   // on it, so it is a class a routing party consumes. Nobody between the
   // two ends consumes these.
 }).strict();
-var ResultResponse = z8.object({
+var ResultResponse = z9.object({
   /**
    * False when this submission wrote nothing — the daemon should discard,
    * not retry ({@link MUSTS.RESULT_IDEMPOTENT}).
    */
-  accepted: z8.boolean(),
+  accepted: z9.boolean(),
   /**
    * True when this device had already recorded this job's result.
    *
@@ -1589,13 +1693,13 @@ var ResultResponse = z8.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: z8.boolean().optional(),
+  duplicate: z9.boolean().optional(),
   /** The job's state after this submission. */
-  state: z8.string().min(1)
+  state: z9.string().min(1)
 }).strict();
-var ReleaseRequest = z8.object({
-  protocolVersion: z8.literal(PROTOCOL_VERSION),
-  runnerId: z8.string().min(1),
+var ReleaseRequest = z9.object({
+  protocolVersion: z9.literal(PROTOCOL_VERSION),
+  runnerId: z9.string().min(1),
   /**
    * Which leases to release — the grant, not just the job.
    *
@@ -1603,8 +1707,8 @@ var ReleaseRequest = z8.object({
    * 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) })
+  leases: z9.array(
+    z9.object({ jobId: z9.string().min(1), leaseId: z9.string().min(1) })
   ),
   /**
    * Why, so the app's runner list can say something true.
@@ -1615,12 +1719,12 @@ var ReleaseRequest = z8.object({
    * stop offering that job to that runner, or the pair would spin between
    * claim and release forever.
    */
-  reason: z8.enum(["shutdown", "pause", "revoked", "backend-down", "refused"])
+  reason: z9.enum(["shutdown", "pause", "revoked", "backend-down", "refused"])
 }).strict();
-var ReleaseResponse = z8.object({
-  released: z8.array(z8.string().min(1))
+var ReleaseResponse = z9.object({
+  released: z9.array(z9.string().min(1))
 }).strict();
-var WireErrorCode = z8.enum([
+var WireErrorCode = z9.enum([
   "bad-request",
   "unsupported-protocol-version",
   // "We do not know who you are." Exactly 401, and only that — cloud_008
@@ -1670,9 +1774,9 @@ var WireErrorCode = z8.enum([
   "rate-limited",
   "server-error"
 ]);
-var WireError = z8.object({
+var WireError = z9.object({
   error: WireErrorCode,
-  message: z8.string().min(1),
+  message: z9.string().min(1),
   /**
    * What this server speaks, on `unsupported-protocol-version` — §B.4.
    *
@@ -1686,10 +1790,10 @@ var WireError = z8.object({
    * Modelled the way `clock-skew`'s two fields already are — code-specific
    * extras, refused on any other code by the refinement below.
    */
-  supported: z8.array(z8.string().min(1)).optional(),
-  minimum: z8.string().min(1).optional(),
+  supported: z9.array(z9.string().min(1)).optional(),
+  minimum: z9.string().min(1).optional(),
   /** Seconds; mirrors Retry-After for `rate-limited` and `server-error`. */
-  retryAfter: z8.number().int().nonnegative().optional(),
+  retryAfter: z9.number().int().nonnegative().optional(),
   /**
    * The server's clock, and the window it allows. `clock-skew` only.
    *
@@ -1699,8 +1803,8 @@ var WireError = z8.object({
    * heartbeat response returns the same value, and so does every `Date`
    * header.
    */
-  serverTime: z8.number().int().positive().optional(),
-  maxSkewMs: z8.number().int().positive().optional()
+  serverTime: z9.number().int().positive().optional(),
+  maxSkewMs: z9.number().int().positive().optional()
 }).strict().superRefine((error, ctx) => {
   const skew = error.error === "clock-skew";
   const carried = error.serverTime !== void 0 || error.maxSkewMs !== void 0;
@@ -1751,16 +1855,16 @@ var ERROR_STATUS = Object.freeze({
   "rate-limited": 429,
   "server-error": 500
 });
-var FetchRequest = z8.object({
+var FetchRequest = z9.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: z8.literal(PROTOCOL_VERSION),
-  runnerId: z8.string().min(1),
-  jobId: z8.string().min(1),
+  protocolVersion: z9.literal(PROTOCOL_VERSION),
+  runnerId: z9.string().min(1),
+  jobId: z9.string().min(1),
   /**
    * The grant this daemon holds.
    *
@@ -1768,9 +1872,9 @@ var FetchRequest = z8.object({
    * only the job would be answerable for whatever lease exists when it
    * arrives ({@link Lease.id}).
    */
-  leaseId: z8.string().min(1)
+  leaseId: z9.string().min(1)
 }).strict();
-var FetchResponse = z8.object({
+var FetchResponse = z9.object({
   /**
    * The work, sealed to the device that claimed it — byollm_009 §6.
    *
@@ -1820,6 +1924,7 @@ export {
   KindedPayload,
   Lease,
   MAX_CLOCK_SKEW_MS,
+  MAX_SUCCESSION_CHAIN,
   MIN_PROTOCOL_VERSION,
   MUSTS,
   MUST_IDS,
@@ -1836,6 +1941,7 @@ export {
   PairStartResponse,
   PublicIdentity,
   REFUSAL_MESSAGES,
+  RETIREMENT_WINDOW_MS,
   ReleaseRequest,
   ReleaseResponse,
   RequestSignature,
@@ -1845,11 +1951,13 @@ export {
   ResultResponse,
   RunMetadata,
   SIZE_CLASS_LIMITS,
+  SUCCESSION_CONTEXT,
   SUPPORTED_PROTOCOL_VERSIONS,
   SealedEnvelope,
   SealedOutcome,
   SizeClass,
   StoredKeys,
+  Succession,
   TERMINAL_STATES,
   WireError,
   WireErrorCode,
@@ -1878,12 +1986,16 @@ export {
   seal,
   signRequest,
   signSiteRequest,
+  signSuccession,
   signWith,
   sizeClassCeiling,
   sizeClassOf,
+  successionStatement,
+  verifyLink,
   verifyPublicIdentity,
   verifyRequest,
   verifySiteRequest,
-  verifyWith
+  verifyWith,
+  walkSuccession
 };
 //# sourceMappingURL=index.js.map