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

package/README.md

@@ -1,5 +1,5 @@
 > [!WARNING]
-> **Alpha (`0.1.0-alpha.31`) — under active development. Don't use this yet.**
+> **Alpha (`0.1.0-alpha.33`) — under active development. Don't use this yet.**
 >
 > Install it deliberately: `npm install @byollm/protocol@alpha`.
 >
@@ -83,7 +83,7 @@
 > packages published and `@byollm/server` did not: a Sigstore
 > transparency-log 409 on its provenance attestation. The workflow's
 > "already published" guard correctly refuses to resume a partial publish,
-> so `0.1.0-alpha.31` is that release, whole.
+> so `0.1.0-alpha.33` is that release, whole.
 >
 > If you run the Supabase adapter, `alpha.21` needs
 > `20260819010000_completed_by_lease_id.sql`: alpha.19 shipped §3.6's

package/dist/index.d.ts

@@ -1108,6 +1108,110 @@ declare function verifyRequest(input: {
     maxSkewMs?: number;
 }): SignatureFailure | null;
 
+/**
+ * Rotation — byollm_009 Amendment C.
+ *
+ * A site holding identity key **K1** wants to be known by **K2**. It publishes
+ * a *succession*: K2, plus a signature by K1 over a statement naming both key
+ * ids. That signature is the entire mechanism, and the reason rotation can be
+ * automatic without becoming a hole is that **the relay cannot mint one** — it
+ * never holds K1. It is the same trust step a daemon already performs at
+ * pairing, applied to the site's own succession.
+ *
+ * ## Why the statement names both keys
+ *
+ * A signature over K2 alone could be lifted from this site's record and
+ * replayed into another site's, moving *that* site to K2 — a key the attacker
+ * holds. Naming the predecessor binds the succession to one chain, and it is
+ * the reason `verifyLink` takes the id it expects to be succeeding from
+ * rather than reading it out of the statement it is checking.
+ */
+/** The domain separator. Distinct from every other thing an identity signs. */
+declare const SUCCESSION_CONTEXT = "byollm/v1/site-succession";
+/**
+ * How long a retired key may still sign work — Amendment C, ruling 2.
+ *
+ * A protocol constant and not the site's to choose. Per-site overlap
+ * arithmetic is exactly the kind of number that has to mean one thing
+ * everywhere, and a site that could choose it could choose *forever*, which is
+ * a two-key site permanently and a second key nobody ever notices retiring.
+ *
+ * Seven days: long enough that a daemon which polls daily and a laptop shut
+ * for a long weekend both see the new record before the old key stops working,
+ * short enough that "which key is live" is never an interesting question.
+ */
+declare const RETIREMENT_WINDOW_MS: number;
+/**
+ * The longest chain a daemon will walk — Amendment C, ruling 1.
+ *
+ * **A denial-of-service guard, not policy.** The bound exists so a projection
+ * cannot make a daemon verify ten thousand signatures, not to express an
+ * opinion about how often a site may rotate. A site that legitimately exceeds
+ * it has a re-pair ahead of it, which is why it is generous: at one rotation a
+ * quarter this is sixteen years.
+ */
+declare const MAX_SUCCESSION_CHAIN = 64;
+/** One step of a chain: a key, and the signature by it over its successor. */
+declare const Succession: z.ZodObject<{
+    identity: z.ZodObject<{
+        identity: z.ZodString;
+        encryption: z.ZodString;
+        encryptionSig: z.ZodString;
+    }, z.core.$strict>;
+    signature: z.ZodString;
+}, z.core.$strict>;
+type Succession = z.infer<typeof Succession>;
+/** The exact bytes signed. One definition; both sides call it. */
+declare function successionStatement(fromKeyId: string, toKeyId: string): Uint8Array;
+/**
+ * Sign a succession from the keys being retired to the identity taking over.
+ *
+ * Takes `StoredKeys` for the predecessor because only the holder of K1's
+ * private half can produce this, which is the property the whole design rests
+ * on. A site calls this once, at rotation, on the machine holding its keys.
+ */
+declare function signSuccession(previous: StoredKeys, next: PublicIdentity): Succession;
+/**
+ * Check one link: did `link.identity` sign over succeeding to `toKeyId`?
+ *
+ * `toKeyId` is passed in rather than read from anywhere in `link`, and that is
+ * the load-bearing detail. A verifier that recovered the successor from the
+ * signed statement would accept a statement about *any* successor, which is
+ * the replay this design names in C.1 — the signature is genuine, the
+ * successor it names is not the one being installed.
+ */
+declare function verifyLink(link: Succession, toKeyId: string): boolean;
+/** Why a chain was refused, in the words a log line uses. */
+type SuccessionFailure = "no-chain" | "too-long" | "unknown-origin" | "broken-link";
+interface SuccessionWalk {
+    /** The ids the chain passes through, oldest first, ending at the current. */
+    readonly path: string[];
+    /** The approved id the chain reached, when it reached one. */
+    readonly from?: string;
+    readonly failure?: SuccessionFailure;
+}
+/**
+ * Walk a chain from the key being presented back to a key already approved.
+ *
+ * `chain` is ordered oldest last, as the projection carries it — so walking it
+ * means starting at the current key and stepping backwards, each link proving
+ * that its holder signed for the id in front of it.
+ *
+ * Returns the approved id it reached, or why it did not. **Deliberately
+ * returns rather than throws**: a chain that does not verify is ordinary
+ * hostile input, and the caller's job is to keep its existing pin and say so.
+ *
+ * `approved` is asked as a predicate rather than taken as a set because the
+ * daemon's notion of "already approved" includes tombstoned ids — a site that
+ * left the allowlist and came back is still a site this machine has vouched
+ * for, and rotation must not become a way to launder that distinction away.
+ */
+declare function walkSuccession(input: {
+    current: string;
+    chain: readonly Succession[];
+    approved: (keyId: string) => boolean;
+}): SuccessionWalk;
+
 /**
  * The normative MUSTs of protocol v0, as data.
  *
@@ -1696,6 +1800,17 @@ declare const HeartbeatResponse: z.ZodObject<{
         encryption: z.ZodString;
         encryptionSig: z.ZodString;
     }, z.core.$strict>>;
+    successions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        succeeds: z.ZodArray<z.ZodObject<{
+            identity: z.ZodObject<{
+                identity: z.ZodString;
+                encryption: z.ZodString;
+                encryptionSig: z.ZodString;
+            }, z.core.$strict>;
+            signature: z.ZodString;
+        }, z.core.$strict>>;
+        retiringUntil: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>>;
     cancel: z.ZodArray<z.ZodObject<{
         jobId: z.ZodString;
         leaseId: z.ZodString;
@@ -1841,4 +1956,4 @@ declare const FetchResponse: z.ZodObject<{
 }, z.core.$strict>;
 type FetchResponse = z.infer<typeof FetchResponse>;
 
-export { AUDIENCES, Audience, BACKENDS, BACKEND_IDS, BackendClass, BackendCost, type BackendDescriptor, type BackendId, BackendIdSchema, Capability, CapabilityMatrix, ChatMessage, ChatPayload, ClaimRequest, ClaimResponse, ClaimedJob, ClaimedStub, DeliveredResult, ENCRYPTION_KEY_CONTEXT, ENDPOINTS, ENVELOPE_MAX_AGE_MS, ERROR_STATUS, type Endpoint, type EnvelopeContext, EnvelopeDirection, type EnvelopeFailure, FetchRequest, FetchResponse, GeneratePayload, HeartbeatRequest, HeartbeatResponse, JOB_KINDS, JobKind, JobOutcome, JobPayload, JobResultCanceled, JobResultError, JobResultOk, JobState, JobStub, KindedPayload, Lease, MAX_CLOCK_SKEW_MS, MIN_PROTOCOL_VERSION, MUSTS, MUST_IDS, type MatchDaemon, type MatchJob, MatchRefusal, type MatchResult, type Must, type MustEnforcer, type MustId, type MustVerification, type MustVerifiedBy, OFFER_SCOPES, OfferScope, type OpenResult, PAYLOAD_LIMITS, PROTOCOL_PREFIX, PROTOCOL_VERSION, PairPollRequest, PairPollResponse, PairRequest, PairStartRequest, PairStartResponse, type PayloadFor, PublicIdentity, REFUSAL_MESSAGES, ReleaseRequest, ReleaseResponse, RequestSignature, ResultDisposition, ResultProvenance, ResultRequest, ResultResponse, RunMetadata, SIZE_CLASS_LIMITS, SUPPORTED_PROTOCOL_VERSIONS, SealedEnvelope, SealedOutcome, type SignatureFailure, SizeClass, type SpendConsent, StoredKeys, TERMINAL_STATES, type VersionRefusal, WireError, WireErrorCode, backendDescriptor, canTransition, canonicalRequest, checkProtocolVersion, cryptoReady, declaredVersion, effectiveOfferScope, fingerprint, generateKeys, isBackendId, isJobKind, isLocalHost, isTerminal, keyId, kindsOf, matchAudience, mustsVerifiedBy, open, payloadTextLength, provenanceFor, publicIdentityOf, resolveCost, seal, signRequest, signSiteRequest, signWith, sizeClassCeiling, sizeClassOf, verifyPublicIdentity, verifyRequest, verifySiteRequest, verifyWith };
+export { AUDIENCES, Audience, BACKENDS, BACKEND_IDS, BackendClass, BackendCost, type BackendDescriptor, type BackendId, BackendIdSchema, Capability, CapabilityMatrix, ChatMessage, ChatPayload, ClaimRequest, ClaimResponse, ClaimedJob, ClaimedStub, DeliveredResult, ENCRYPTION_KEY_CONTEXT, ENDPOINTS, ENVELOPE_MAX_AGE_MS, ERROR_STATUS, type Endpoint, type EnvelopeContext, EnvelopeDirection, type EnvelopeFailure, FetchRequest, FetchResponse, GeneratePayload, HeartbeatRequest, HeartbeatResponse, JOB_KINDS, JobKind, JobOutcome, JobPayload, JobResultCanceled, JobResultError, JobResultOk, JobState, JobStub, KindedPayload, Lease, MAX_CLOCK_SKEW_MS, MAX_SUCCESSION_CHAIN, MIN_PROTOCOL_VERSION, MUSTS, MUST_IDS, type MatchDaemon, type MatchJob, MatchRefusal, type MatchResult, type Must, type MustEnforcer, type MustId, type MustVerification, type MustVerifiedBy, OFFER_SCOPES, OfferScope, type OpenResult, PAYLOAD_LIMITS, PROTOCOL_PREFIX, PROTOCOL_VERSION, PairPollRequest, PairPollResponse, PairRequest, PairStartRequest, PairStartResponse, type PayloadFor, PublicIdentity, REFUSAL_MESSAGES, RETIREMENT_WINDOW_MS, ReleaseRequest, ReleaseResponse, RequestSignature, ResultDisposition, ResultProvenance, ResultRequest, ResultResponse, RunMetadata, SIZE_CLASS_LIMITS, SUCCESSION_CONTEXT, SUPPORTED_PROTOCOL_VERSIONS, SealedEnvelope, SealedOutcome, type SignatureFailure, SizeClass, type SpendConsent, StoredKeys, Succession, type SuccessionFailure, type SuccessionWalk, TERMINAL_STATES, type VersionRefusal, WireError, WireErrorCode, backendDescriptor, canTransition, canonicalRequest, checkProtocolVersion, cryptoReady, declaredVersion, effectiveOfferScope, fingerprint, generateKeys, isBackendId, isJobKind, isLocalHost, isTerminal, keyId, kindsOf, matchAudience, mustsVerifiedBy, open, payloadTextLength, provenanceFor, publicIdentityOf, resolveCost, seal, signRequest, signSiteRequest, signSuccession, signWith, sizeClassCeiling, sizeClassOf, successionStatement, verifyLink, verifyPublicIdentity, verifyRequest, verifySiteRequest, verifyWith, walkSuccession };