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

package/README.md

@@ -1,5 +1,5 @@
 > [!WARNING]
-> **Alpha (`0.1.0-alpha.54`) — under active development. Don't use this yet.**
+> **Alpha (`0.1.0-alpha.56`) — 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.54` is that release, whole.
+> so `0.1.0-alpha.56` 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

@@ -1029,7 +1029,17 @@ declare function publicIdentityOf(keys: StoredKeys): PublicIdentity;
  */
 declare function verifyPublicIdentity(identity: PublicIdentity): boolean;
 /** Sign arbitrary bytes with an identity key. */
-declare function signWith(keys: StoredKeys, data: Uint8Array): string;
+/**
+ * Sign bytes with an identity key.
+ *
+ * Takes only the private half it uses. A signer that demanded a whole
+ * {@link StoredKeys} would make every caller hold an encryption keypair for a
+ * job that has no encryption in it — and the control plane, which signs
+ * rosters and opens nothing, would be generating and storing secret material
+ * it can never need. Every existing caller passes a full `StoredKeys`, which
+ * satisfies this.
+ */
+declare function signWith(keys: Pick<StoredKeys, "identityPrivate">, data: Uint8Array): string;
 /** Verify bytes against a raw Ed25519 public key. */
 declare function verifyWith(identityPublic: string, data: Uint8Array, signature: string): boolean;
 /**
@@ -1286,6 +1296,107 @@ declare function verifyRequest(input: {
     maxSkewMs?: number;
 }): SignatureFailure | null;
 
+/**
+ * The roster a daemon holds, and how it knows the roster is real.
+ *
+ * byollm_001 Amendment G, RATIFIED 2026-08-25. A `team` job is admitted by a
+ * list **this device holds**, signed by the owner's control plane and verified
+ * against a key pinned at pairing — never by an assertion from the party
+ * routing the job, per-job or in bulk.
+ *
+ * The relay's power over this is exactly denial: it can withhold a roster as
+ * it can withhold a job, and it can forge neither. That is what lets the hub
+ * go on reading and filtering rosters for its own routing without being
+ * trusted for admission — non-authorship, not blindness.
+ */
+/**
+ * How old a held roster may be before a device stops honouring it.
+ *
+ * One hour, and the shortest constant in this protocol on purpose: every other
+ * one bounds how long a *thing* stays valid, and this one alone bounds how
+ * long a *person* keeps access after the owner has said no.
+ *
+ * A failure bound, not a sync interval. A daemon refreshes on every heartbeat
+ * and a removal propagates in seconds; the hour is what a device gets when
+ * that conversation stops working — enough that a closed laptop or a flaky
+ * café network does not narrow a working device, and not so much that a
+ * removed teammate outlives the owner's patience.
+ */
+declare const ROSTER_MAX_AGE_MS: number;
+/**
+ * The domain separator, and why a roster gets its own.
+ *
+ * Every signature in this system says what kind of statement it is before it
+ * says anything else. Without that, bytes signed for one purpose verify for
+ * another: a roster document and a request body are both "some bytes this key
+ * signed", and a scheme that could not tell them apart would let a captured
+ * roster be replayed as a request — or worse, let a control plane that signs
+ * one thing be held to have signed the other.
+ */
+declare const ROSTER_CONTEXT = "byollm/v1/roster";
+declare const SignedRoster: z.ZodObject<{
+    owner: z.ZodString;
+    members: z.ZodArray<z.ZodString>;
+    issuedAt: z.ZodNumber;
+    signature: z.ZodString;
+}, z.core.$strict>;
+type SignedRoster = z.infer<typeof SignedRoster>;
+/**
+ * The exact bytes both sides sign and verify.
+ *
+ * Every field that decides what the roster *means* is in here. Leave one out
+ * and it becomes something an intermediary can change without breaking the
+ * signature — `owner` most of all: a roster whose owner was not signed over
+ * could be lifted from one account and delivered to another's devices, and
+ * every signature check would pass.
+ *
+ * Members are joined with NUL, which cannot appear in an id, so no arrangement
+ * of member names can imitate a different membership. Joining on a comma would
+ * let `["a,b"]` and `["a","b"]` sign identically.
+ */
+declare function rosterStatement(input: {
+    owner: string;
+    members: readonly string[];
+    issuedAt: number;
+}): Uint8Array;
+/** Sign a roster with the control plane's own key. */
+declare function signRoster(keys: Pick<StoredKeys, "identityPrivate">, input: {
+    owner: string;
+    members: readonly string[];
+    issuedAt: number;
+}): SignedRoster;
+/** Why a roster was refused. Typed for logs; never returned to a caller. */
+type RosterRefusal = "bad-signature" | "wrong-owner" | "stale" | "from-the-future"
+/**
+ * A roster arrived and this device pinned no key to check it against.
+ *
+ * Not a bad signature — nothing was checked. It is the one refusal that is
+ * evidence *about the pairing* rather than about the document: an upstream
+ * that sends rosters has a control plane, so a device holding no key from
+ * it paired before roster sync existed and can never verify one. The remedy
+ * is re-pairing, and this is the only refusal here that has one.
+ */
+ | "no-pinned-key";
+/**
+ * Is this roster one this device may admit people from, right now?
+ *
+ * `owner` is passed in rather than read out of the document, for the reason
+ * {@link verifyLink} takes its successor as an argument: a verifier that
+ * recovered the owner from the signed bytes would accept a genuine roster
+ * belonging to somebody else, and every check would pass.
+ *
+ * Age is checked in **both** directions. A clock far ahead is as much a
+ * problem as one behind: an `issuedAt` in the future would extend a roster's
+ * life past the bound, which is the whole thing being enforced.
+ */
+declare function verifyRoster(input: {
+    roster: SignedRoster;
+    owner: string;
+    controlPlanePublic: string;
+    now: number;
+    maxAgeMs?: number;
+}): RosterRefusal | null;
+
 /**
  * Rotation — byollm_009 Amendment C.
  *
@@ -1850,6 +1961,7 @@ declare const PairPollResponse: z.ZodDiscriminatedUnion<[z.ZodObject<{
         encryption: z.ZodString;
         encryptionSig: z.ZodString;
     }, z.core.$strict>>;
+    controlPlanePublic: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>], "status">;
 type PairPollResponse = z.infer<typeof PairPollResponse>;
 declare const PairRequest: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -2082,6 +2194,12 @@ declare const HeartbeatResponse: z.ZodObject<{
     }, z.core.$strict>>;
     serverTime: z.ZodNumber;
     awaitingConsent: z.ZodArray<z.ZodString>;
+    roster: z.ZodOptional<z.ZodObject<{
+        owner: z.ZodString;
+        members: z.ZodArray<z.ZodString>;
+        issuedAt: z.ZodNumber;
+        signature: z.ZodString;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 type HeartbeatResponse = z.infer<typeof HeartbeatResponse>;
 /**
@@ -2217,4 +2335,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, JobRefused, 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, RefusalReason, 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, WithheldKind, backendDescriptor, backendName, canTransition, canonicalRequest, checkProtocolVersion, classifyCost, cryptoReady, declaredVersion, effectiveOfferScope, fingerprint, generateKeys, isBackendId, isCloudTaggedModel, 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 };
+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, JobRefused, 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, ROSTER_CONTEXT, ROSTER_MAX_AGE_MS, RefusalReason, ReleaseRequest, ReleaseResponse, RequestSignature, ResultDisposition, ResultProvenance, ResultRequest, ResultResponse, type RosterRefusal, RunMetadata, SIZE_CLASS_LIMITS, SUCCESSION_CONTEXT, SUPPORTED_PROTOCOL_VERSIONS, SealedEnvelope, SealedOutcome, type SignatureFailure, SignedRoster, SizeClass, type SpendConsent, StoredKeys, Succession, type SuccessionFailure, type SuccessionWalk, TERMINAL_STATES, type VersionRefusal, WireError, WireErrorCode, WithheldKind, backendDescriptor, backendName, canTransition, canonicalRequest, checkProtocolVersion, classifyCost, cryptoReady, declaredVersion, effectiveOfferScope, fingerprint, generateKeys, isBackendId, isCloudTaggedModel, isJobKind, isLocalHost, isTerminal, keyId, kindsOf, matchAudience, mustsVerifiedBy, open, payloadTextLength, provenanceFor, publicIdentityOf, resolveCost, rosterStatement, seal, signRequest, signRoster, signSiteRequest, signSuccession, signWith, sizeClassCeiling, sizeClassOf, successionStatement, verifyLink, verifyPublicIdentity, verifyRequest, verifyRoster, verifySiteRequest, verifyWith, walkSuccession };