@percayso-community/cayso-contracts 0.29.0 → 1.0.0

package/README.md

@@ -21,22 +21,37 @@ Percayso Cloud is the second: its Contribution Store presents the settlement
 assertion to Cayso directly, and the Cloud generates its types from the `schema`
 entry point rather than typing Cayso's half by hand. The Cloud's two seams live in
 `cloud-settlement`, and the settlement path, which a registered issuer calls and
-no person does, is `CLOUD_SETTLEMENT_ROUTE`, published apart from `ROUTES`.
-
-**The operator read surface, on its own entry point** (CAY-0026, Amendment 4). Three
-reads an operator app's *server* calls — the movement list, the purchase list and the
-quickening ladder — are published at `@percayso-community/cayso-contracts/operator`:
+no person does, is `CLOUD_SETTLEMENT_ROUTE`, published apart from `ROUTES`. The
+Cloud verifies Cayso's authorisation acknowledgement under a key it reads from
+`ACKNOWLEDGEMENT_KEYS_ROUTE`, an unauthenticated read of public keys, published
+apart from both.
+
+**Percayso BizID's authority assertion** (CAY-0100) is published ahead of the
+binding that accepts it. `AuthorityClaims` is its own type, under the identity
+assertion's `AssertionHeader`, with no verification or assurance fields. It travels
+in the `AUTHORITY_ASSERTION_HEADER` header, beside `Authorization`, and the thin
+client sends it only on an Organisation operation given a per-request provider for
+it. The binding's refusals are the closed `AuthorityBindingRefusal`.
+`AssertionClaims` declares `auth_time`, which Percayso ID mints and the binding
+compares. `organisationAuthority` and `mandateFor` are retired and still published,
+until the breaking step that removes them.
+
+**The operator read surface, on its own entry point** (CAY-0026, Amendments 4 and 5).
+Four reads an operator app's *server* calls — the movement list, the purchase list, the
+quickening ladder and the economy summary — are published at `@percayso-community/cayso-contracts/operator`:
 their paths and scopes, query inputs (wallet id, a half-open `[from, to)` window, a
 keyset cursor), rows and pages, and their closed refusal and not-configured bodies.
 Money is `Cents`, a wallet is named by its wallet id, and no Percayso identity
 appears on any row. It is not re-exported from the barrel, so Piper and the Cloud
 never import an operator vocabulary by accident, and the schema describes it under
 its own `operator` key rather than among the person-facing types. Cayso sends no
-CORS headers: these reads are for a server, never a browser. Widening the entry
-point beyond these three needs a further amendment.
+CORS headers: these reads are for a server, never a browser. The economy summary
+(Amendment 5) answers aggregates only: whole-number counts and cent totals, with no
+wallet id, identity or row of any kind. Widening the entry point beyond these four
+needs a further amendment.
 
 **Deliberately not published:** peer types, holdings and carves, and every operator
-route but those three reads. They are not a consumer's business, and putting them on
+route but those four reads. They are not a consumer's business, and putting them on
 the public surface widens it for nothing.
 
 **This package carries no numbers.** Amounts, rates, tiers, schedules and
@@ -49,22 +64,42 @@ restated here.
 |---|---|
 | `@percayso-community/cayso-contracts` | Types and constants. No runtime. |
 | `@percayso-community/cayso-contracts/client` | The thin client — fetch, assertion header, idempotent retry. |
-| `@percayso-community/cayso-contracts/schema` | A machine-readable descriptor of the published surface. |
-| `@percayso-community/cayso-contracts/operator` | The three operator reads' types and route constants, for an operator app's server. |
+| `@percayso-community/cayso-contracts/schema` | A machine-readable descriptor of the published surface: the published, versioned surface a consumer in another language generates its types from. |
+| `@percayso-community/cayso-contracts/operator` | The four operator reads' types and route constants, for an operator app's server. |
 
 The split is the point: a consumer wanting only the types takes on no runtime at
 all. The client owns the fetch, the assertion header and the idempotent retry.
 
 The `schema` entry point serves a data description of the same surface —
-generated from these very types, never hand-written — for tooling that needs the
-shape at runtime (a diff, a doc generator, a compatibility check). It is a
-diagnostic, **not** a stand-in for depending on the package: see below.
+generated from these very types, never hand-written. It is a published, versioned
+surface in its own right, and there are two ways to depend on this package through
+it, by language:
+
+1. **A TypeScript consumer imports the types**, and the compiler holds the surface.
+   Piper does this. For such a consumer the schema is a tool *about* the contract —
+   a diff, a doc generator, a compatibility check — and never a replacement for the
+   import.
+2. **A consumer in another language generates from the `schema` entry point of the
+   published tarball at a pinned version**, and treats a drift between its generated
+   types and the schema as a build failure. That *is* depending on the package: the
+   pin is the lockfile entry and the regeneration is the compile. The Percayso Cloud
+   is this consumer (`CAY-0026` Amendment 3; `CMTY-0018` §3 as amended): it is written
+   in Go, it cannot import a TypeScript type, and its generator reads the npm tarball
+   at a pinned version so that its Go types for the two Cloud seams in
+   `cloud-settlement` are never typed by hand. The package ships the schema as a JS
+   module only, which is why the generator reads the tarball and not a registry
+   endpoint.
+
+What stays refused is reading the schema off the wire as a substitute for either:
+see the version endpoint, below.
 
 ## Independent versioning
 
 `CONTRACT_VERSION` is exported from the barrel and is **independent** — its own
-semantic version, starting `0.1.0`, not a repo-wide constant shared with anything
-else. Piper's own contracts share one global version bumped across all of them
+semantic version, not a repo-wide constant shared with anything else. It started at
+`0.1.0`, and from `1.0.0` it follows ordinary semantic versioning, Cayso's adoption of CMTY-0032
+([CAY-0101](../../docs/architectural-decision-record/CAY-0101-the-contracts-follow-ordinary-semantic-versioning-from-1-0-0.md)):
+a minor is additive and drops nothing, and a major is the only breaking kind. Piper's own contracts share one global version bumped across all of them
 together; independent versioning across a service boundary is exactly what this
 money surface gains that theirs lack (CAY-0026). The constant and the package's
 `version` field must agree, and a test fails when they drift.
@@ -82,24 +117,33 @@ describes. The thin client's `getVersion()` reads it and warns once, per client
 instance, when the server's contract *major* differs from the one the client was
 built against.
 
-After a minor bump that is additive on the wire, a deployment keeps the previous
-minor in `supportedContractVersions` for one release, so a consumer still pinned
-to it keeps working while it moves. A breaking bump drops it, and says so in the
-bump's changelog.
+A deployment keeps serving every earlier minor of its major and lists them in
+`supportedContractVersions`, so a consumer pinned to any of them keeps working; a
+consumer's handshake accepts a Cayso if `contractVersion` or any entry of
+`supportedContractVersions` is on its own line: from `1.0.0` the same major, below it the
+same minor. Only a
+major breaks, and its first release lists nothing from an older major and says so in
+the bump's changelog. An earlier major is listed only during a declared transition:
+`1.0.0` keeps `0.32.0`, `0.31.0`, `0.30.0` and `0.29.0`, and the next major drops them
+([CAY-0101](../../docs/architectural-decision-record/CAY-0101-the-contracts-follow-ordinary-semantic-versioning-from-1-0-0.md),
+amending CAY-0086).
 
 Alongside it, `GET /api/version/schema` serves the same machine-readable
 descriptor as `@percayso-community/cayso-contracts/schema` — the surface outside consumers read, with
 no operator, webhook or peer route. It exists for tooling and diagnostics.
 
-**It is not a substitute for depending on this package.** The descriptor is
-data; the guarantee is the *types*, and the types do not exist at runtime — they
-are erased when TypeScript compiles. A consumer that reads the schema off the
-wire and validates against it has re-created Piper's original mistake by another
-route: hand-rolling the shape instead of importing it, and losing every
-compile-time guarantee the moment the wire description and the code drift. Import
-`@percayso-community/cayso-contracts` and let the compiler hold the surface. Read the schema
-endpoint when you are building a tool *about* the contract, never to stand in for
-having it.
+**The wire is not a substitute for depending on this package.** The descriptor
+served here is data about *this deployment*; the guarantee is the published
+package at a pinned version. A consumer that reads the schema off the wire and
+validates or generates against it has re-created Piper's original mistake by
+another route: it couples its build to a deployment's uptime, replaces a pinned
+version with whatever happens to be deployed at that moment, and loses every
+guarantee the moment the wire description and its code drift. Import
+`@percayso-community/cayso-contracts` and let the compiler hold the surface, or —
+in another language — generate from the `schema` entry point of the published
+tarball at a pinned version, as the Cloud does. Read the schema *endpoint* when
+you are building a tool *about* a running deployment, never to stand in for
+having the package.
 
 ## No dependencies
 

package/dist/assertion.d.ts

@@ -383,9 +383,19 @@
  * It is not a second use of `'make-commercial-payment'`: nothing moves when it is
  * presented, and what it authorises is spending in later periods, settled by the
  * Contribution Store's assertion, which no person presents and which therefore has
- * no operation here. It is classified before it is served.
+ * no operation here.
+ *
+ * `'revoke-standing-authorisation'` is the owner withdrawing that delegation from
+ * their Instance (CAY-0094). It is its own operation rather than a mode of
+ * presenting, because one path carries one scope at CAY-0030's gate: a credential
+ * minted to revoke must not thereby delegate, nor the reverse.
+ *
+ * `'bind-node'` is the owner's Instance binding a Node to the wallet its Instance key
+ * is already bound to (CMTY-0018 §4, CAY-0095). Its own operation, because it decides
+ * where a Node's earnings land and binds no key: a credential minted to delegate
+ * spending must not thereby direct earnings, nor the reverse.
  */
-export type ContractOperation = 'read-own-wallet' | 'read-purchase-result' | 'authorise-purchase' | 'cancel-purchase' | 'provision-citizenship' | 'read-own-citizenship' | 'provision-organisation' | 'claim-founder-wallet' | 'make-commercial-payment' | 'make-citizen-transfer' | 'change-handle' | 'read-handle-change-receipt' | 'place-quote' | 'withdraw-quote' | 'request-buy-back' | 'read-citizen-market' | 'read-marketplace-receipt' | 'settle-marketplace-order' | 'settle-marketplace-refund' | 'present-standing-authorisation';
+export type ContractOperation = 'read-own-wallet' | 'read-purchase-result' | 'authorise-purchase' | 'cancel-purchase' | 'provision-citizenship' | 'read-own-citizenship' | 'provision-organisation' | 'claim-founder-wallet' | 'make-commercial-payment' | 'make-citizen-transfer' | 'change-handle' | 'read-handle-change-receipt' | 'place-quote' | 'withdraw-quote' | 'request-buy-back' | 'read-citizen-market' | 'read-marketplace-receipt' | 'settle-marketplace-order' | 'settle-marketplace-refund' | 'present-standing-authorisation' | 'revoke-standing-authorisation' | 'bind-node';
 /**
  * An operation key belonging to a deployment's OWN surfaces rather than to this
  * contract — operator work, above all. Deliberately not enumerated: this package
@@ -746,6 +756,15 @@ export interface AssertionClaims {
      * THIS operation — the organisation-authority claim (CAY-0059 §3). OPTIONAL on
      * the wire, and its absence provisions nothing.
      *
+     * ## RETIRED by CAY-0100, and kept until #419
+     *
+     * BizID holds the Organisation, so the evidence for an act on an Organisation
+     * Wallet becomes BizID's `AuthorityClaims.organisationId`, and Percayso ID stops
+     * minting this claim. It stays declared, and read, until the previous `cayso-api`
+     * pin already runs the binding, because a revert must not bring back a reader of a
+     * claim nobody mints (CAY-0100 §7, Consequences). Its removal is the breaking
+     * contract step, #419. Nothing new may read it.
+     *
      * ## It is a second fact beside `sub`, and it replaces nothing
      *
      * `sub` stays what it has always been: the citizen Percayso ID authenticated
@@ -897,6 +916,14 @@ export interface AssertionClaims {
      * displays — never the Organisation ID of the holder behind it, and never an
      * Instance ID. Present when the holder may act for one or more organisations.
      *
+     * ## RETIRED by CAY-0100 §4a, and kept until #419
+     *
+     * The commercial payment's mandate route, the delegated purchase and an allowance
+     * grant on an Organisation Wallet authorise from BizID's `AuthorityClaims`, not from
+     * this claim. Percayso ID stops sending it only once no reader of it is left at the
+     * previous `cayso-api` pin (CAY-0100, Consequences), and its removal is the breaking
+     * contract step, #419. Nothing new may read it.
+     *
      * ## THIS IS NOT THE ORGANISATION-AUTHORITY CLAIM, AND THE TWO MUST NOT BE
      * OVERLOADED
      *
@@ -934,4 +961,30 @@ export interface AssertionClaims {
      * session, in seconds. Nothing in Phase A may branch on it (CAY-0008).
      */
     readonly sessionAgeSeconds?: number;
+    /**
+     * When the Citizen tapped their passkey for this assertion, in **seconds** since the
+     * Unix epoch: the issuer's convention, not `Millis`, as `exp` and `iat` are.
+     * OPTIONAL on the wire, declared ahead of its first reader (CAY-0100).
+     *
+     * Percayso ID mints it. BizID's authority assertion carries the tap it saw as
+     * `AuthorityClaims.auth_time`, and the binding (#417) refuses the two unless they
+     * are equal, so one tap serves both (CAY-0100 §4). Spelled `auth_time`, as OpenID
+     * Connect and that claim spell it, rather than in this surface's camel case, so the
+     * two sides of the comparison carry one name.
+     *
+     * ## Declared before Percayso ID mints it, and why that order is the point
+     *
+     * A verifier refuses any claim key it does not know. If Percayso ID minted
+     * `auth_time` before the `cayso-api` pin declared it, a Cloud revert to the previous
+     * pin would refuse every identity assertion. So Cayso declares it first, and
+     * Percayso ID mints it only once the previous pin already does (CAY-0100,
+     * Consequences). A verifier admits a non-negative integer here and refuses any other
+     * value as malformed.
+     *
+     * ## Nothing may branch on it yet
+     *
+     * Like {@link sessionAgeSeconds}, it is declared and depended on by nothing until the
+     * binding is built. Its absence refuses nothing, and its presence admits nothing.
+     */
+    readonly auth_time?: number;
 }

package/dist/assurance.js

@@ -518,6 +518,41 @@ export const ASSURANCE_POLICY = {
             'bypass. Nothing moves when it is presented; what it authorises moves later, without the ' +
             'holder present, which is why the bar is applied here.',
     },
+    // The owner withdrawing that delegation from their Instance (CAY-0094). Held to the
+    // bar of the act it undoes: a credential that could not have delegated must not be
+    // able to withdraw a delegation either, or a weaker assertion becomes a way to stop
+    // an owner's Instance spending what they authorised.
+    'revoke-standing-authorisation': {
+        operation: 'revoke-standing-authorisation',
+        assurance: 'required',
+        decisions: {
+            // Asserts nothing; permanently refused wherever "identity-verified" is meant.
+            'dev-bypass': 'refused',
+            document: 'accepted',
+            'document-and-biometric': 'accepted',
+        },
+        rationale: 'Revoking a standing authorisation withdraws a delegation of spending from the ' +
+            "holder's wallet, so it is held to the bar of presenting one: anything but the " +
+            'development bypass. A credential that could not delegate cannot undo a delegation.',
+    },
+    // The owner's Instance binding a Node to their wallet (CMTY-0018 §4, CAY-0095). Held to
+    // the bar of presenting a standing authorisation: a bound Node's earnings are paid into
+    // the wallet at every later settlement, without the holder present, so choosing where
+    // they land is a decision about somebody's money.
+    'bind-node': {
+        operation: 'bind-node',
+        assurance: 'required',
+        decisions: {
+            // Asserts nothing; permanently refused wherever "identity-verified" is meant.
+            'dev-bypass': 'refused',
+            document: 'accepted',
+            'document-and-biometric': 'accepted',
+        },
+        rationale: "Binding a Node decides which wallet the Node's earnings are paid into at every later " +
+            'settlement, without the holder present, and a binding is never re-pointed, so it is ' +
+            'held to the bar of presenting a standing authorisation: anything but the development ' +
+            'bypass.',
+    },
 };
 /**
  * Every operation, as a value. Derived from {@link ASSURANCE_POLICY} for the same
@@ -559,6 +594,8 @@ export const OPERATION_FOR_ROUTE = {
     requestBuyBack: 'request-buy-back',
     marketplaceOrder: 'settle-marketplace-order',
     standingAuthorisation: 'present-standing-authorisation',
+    revokeStandingAuthorisation: 'revoke-standing-authorisation',
+    bindNode: 'bind-node',
     version: null,
 };
 /**

package/dist/authority.d.ts

@@ -0,0 +1,221 @@
+/**
+ * `authority` — the shape of Percayso BizID's authority assertion, and the closed
+ * reasons the binding refuses one for (CAY-0100 §2, §4).
+ *
+ * BizID holds the Organisation and Percayso ID holds people (CMTY-0031, BIZ-0010).
+ * So the evidence that a Citizen may act for an Organisation comes from BizID, a
+ * second issuer, in a credential of its own: {@link AuthorityClaims}. It says that
+ * this Citizen may do this operation for this Organisation, under its formed
+ * mandate. It is not a second identity assertion and shares no type with
+ * `AssertionClaims`.
+ *
+ * This file is the SHAPE ALONE, published so that Piper can build against it
+ * before Cayso accepts it. Nothing here reads, verifies or binds a credential.
+ * BizID's registration as an authority issuer, its verifier and the binding to
+ * Percayso ID's assertion are later slices (#415–#417), and until they are served
+ * an Organisation operation answers exactly as it did.
+ *
+ * ## The envelope is the identity assertion's
+ *
+ * Compact JWS, `EdDSA` over Ed25519 (CAY-0072), with a header of exactly
+ * `{alg, kid}`: the same {@link AssertionHeader}, not a second header type, so the
+ * one rule about what a header may say is written once. `iss` is BizID, `aud` is
+ * `'cayso'` and `jti` is fresh. `iat` and `exp` are in seconds, and `exp` sits
+ * within `MAX_ASSERTION_LIFETIME_SECONDS` (`assertion.ts`), the ceiling an identity
+ * assertion is held to. That ceiling is not restated here. Replay protection is on
+ * `(iss, jti)`, exactly as for identity assertions (CAY-0030).
+ *
+ * ## No verification or assurance fields
+ *
+ * BizID verifies no people. Money-grade assurance comes from Percayso ID's
+ * assertion, under the per-operation acceptance policy (CAY-0029), and nothing
+ * here can stand in for it. An `AuthorityClaims` alone authenticates no route: it
+ * is accepted only beside a Percayso ID assertion it binds to (CAY-0100 §3, §4).
+ *
+ * ## It travels in its own header, beside the identity assertion
+ *
+ * See {@link AUTHORITY_ASSERTION_HEADER}. The thin client sends it on the
+ * Organisation operations alone, fetched for each request and never cached, under
+ * the discipline the identity assertion is fetched under.
+ */
+import type { AssertionHeader, ContractOperation } from './assertion.js';
+/**
+ * The request header an authority assertion travels in, beside the identity
+ * assertion's `Authorization: Bearer` (CAY-0100 §4).
+ *
+ * ## Why this name
+ *
+ * - **Not `Authorization`.** That header carries Percayso ID's assertion and only
+ *   it. A request has one `Authorization`, and the two credentials are verified by
+ *   two verifiers against two registrations, so neither may be mistaken for the
+ *   other by where it arrived.
+ * - **No `X-` prefix.** RFC 6648 retired it, and the one header this contract
+ *   already names beside `Authorization` is `Idempotency-Key`, which has none. This
+ *   follows that spelling: two words, each capitalised, hyphenated.
+ * - **The glossary's noun.** CAY-0100 calls the credential BizID's *authority
+ *   assertion*, so the header says that and nothing more. It does not name BizID,
+ *   for the reason `Authorization` does not name Percayso ID: who minted it is the
+ *   credential's `iss`, checked against a registration, never a header's say-so.
+ *
+ * The value is the compact JWS alone, with no `Bearer` scheme: the scheme belongs to
+ * `Authorization`'s grammar, and this header has no other value to tell it from.
+ *
+ * Published as a value so a consumer that does not use the thin client spells it
+ * from the contract rather than from a retyped copy, and so the service that reads
+ * it reads the same string.
+ */
+export declare const AUTHORITY_ASSERTION_HEADER: "Authority-Assertion";
+/**
+ * A minted authority assertion as a whole: the identity assertion's header, and the
+ * claims BizID asserts (CAY-0100 §2).
+ *
+ * The header is {@link AssertionHeader} itself, exactly `{alg, kid}`, read first to
+ * choose a check and believed never. The split is the one `AssertionEnvelope` makes,
+ * for the same reason.
+ */
+export interface AuthorityEnvelope {
+    /** How to check this credential. Read first, believed never. */
+    readonly header: AssertionHeader;
+    /** What BizID asserts, established only once the header's check has passed. */
+    readonly claims: AuthorityClaims;
+}
+/**
+ * The claims carried by BizID's authority assertion (CAY-0100 §2): this Citizen may
+ * perform this operation for this Organisation, under this version of its formed
+ * mandate.
+ *
+ * CLOSED. These ten keys and no others: a verifier refuses a key it does not know, as
+ * it does for an identity assertion. There are no verification or assurance fields,
+ * because BizID does not verify people.
+ *
+ * A claim to be CHECKED, never a claim to be trusted. Cayso verifies a minted
+ * assertion and never takes a caller's word for who they are, nor for whom they act
+ * (CLAUDE.md, Trust and authentication).
+ */
+export interface AuthorityClaims {
+    /**
+     * Who minted this: Percayso BizID, registered as an authority issuer for this type
+     * alone (CAY-0100 §3). Typed `string` rather than a literal for the reason
+     * `AssertionClaims.iss` is: an unrecognised issuer must be representable in order
+     * to be refused.
+     */
+    readonly iss: string;
+    /** The intended recipient. Exactly `'cayso'`, and checked, not merely present. */
+    readonly aud: 'cayso';
+    /**
+     * This assertion's unique identity, fresh for each one. Replay is refused on
+     * `(iss, jti)`, exactly as for identity assertions (CAY-0030). It never names the
+     * identity assertion's `jti`, and the identity assertion never names it (CAY-0100
+     * §4): each is consumed as its own single use.
+     */
+    readonly jti: string;
+    /**
+     * Issued-at, in **seconds** since the Unix epoch, the issuer's convention and not
+     * `Millis`, as on `AssertionClaims`.
+     */
+    readonly iat: number;
+    /**
+     * Expiry, in **seconds** since the Unix epoch. No further ahead than
+     * `MAX_ASSERTION_LIFETIME_SECONDS`, the ceiling an identity assertion is held to
+     * (CAY-0100 §2). At or before now is expired, with no skew grace added.
+     */
+    readonly exp: number;
+    /**
+     * The Citizen this authority is for: the subject Percayso ID's assertion already
+     * named. **NEVER taken as an identity** (CAY-0100 §3). BizID attests no person, so
+     * this is read only as the value the binding compares with the identity assertion's
+     * `sub`, and a mismatch is `subject_mismatch`. Like that `sub`, it never reaches
+     * the chain (CAY-0006).
+     */
+    readonly sub: string;
+    /**
+     * The ONE operation this authority was minted for. SINGULAR, never a list: a list
+     * would be a menu, and a credential carrying a menu lets whatever holds it choose.
+     * It must be in Percayso ID's `scope` and be the operation of the route it is
+     * presented on, so an authority for one act cannot be spent on another (CAY-0100
+     * §4).
+     */
+    readonly operation: ContractOperation;
+    /**
+     * The Organisation ID Percayso BizID mints: the permanent external identity of the
+     * Organisation Wallet's holder (CAY-0100 §1).
+     *
+     * It reaches Cayso from THIS claim and from nowhere else: not a path, a body or a
+     * query, and not Percayso ID's assertion, which does not echo it because Percayso
+     * ID holds people, not Organisations (CAY-0100 §4). Nothing compares it against a
+     * Percayso ID claim.
+     *
+     * A plain `string`, for the reason `AssertionClaims.organisationAuthority` is one:
+     * this is the wire, JSON carries no brands, and a published type a consumer cannot
+     * build from a string it holds is a distinction that consumer cannot observe. The
+     * branded `OrganisationId`, which refuses an Instance ID at compile time, lives on
+     * the write path in `apps/api`, where the holder key is formed (CAY-0059 §5).
+     */
+    readonly organisationId: string;
+    /**
+     * The version of the Organisation's formed mandate BizID decided this authority
+     * under (CAY-0100 §5). Cayso records it with the movement, or in the act's audit
+     * row where the act writes no movement, and refuses an `AuthorityClaims` without
+     * one. It checks only that it is present and well formed: what the mandate allows is
+     * BizID's to decide, and Cayso does not interpret it.
+     *
+     * A JSON **integer, at least 1**: the mandate's version counter, which starts at 1 and
+     * rises by one each time the mandate is re-formed. The JWS payload carries a bare
+     * number (`"mandateVersion":1`), as `bizid-contracts` declares it and BIZ-0010 records
+     * it. {@link isMandateVersion} is the one check of that shape.
+     */
+    readonly mandateVersion: number;
+    /**
+     * When the Citizen tapped their Percayso ID passkey, in **seconds** since the Unix
+     * epoch: the tap BizID saw (CAY-0100 §2). Percayso ID's assertion carries the same
+     * `auth_time`, so one tap serves both, and the binding refuses two that differ as
+     * `auth_time_mismatch` (§4). Spelled `auth_time`, as OpenID Connect spells it and as
+     * BIZ-0010 does, rather than in this surface's camel case.
+     */
+    readonly auth_time: number;
+}
+/**
+ * Why the binding refused an Organisation operation: CAY-0100 §4's working shape,
+ * closed and spelled here.
+ *
+ * Published before anything produces it, as `founder_wallet_lapsed` was, so a
+ * consumer exhausting `CaysoApiErrorCode` renders it from the version that declared
+ * it. A new reason is a new member and a contract version, never a free-text field.
+ * Every member means the same thing: the operation did not happen.
+ *
+ * It is the BINDING's refusal, not the operation's. Each operation keeps its own
+ * union for what it refuses once the binding holds, and the identity assertion
+ * keeps the gate's codes.
+ */
+export type AuthorityBindingRefusal = 
+/**
+ * An Organisation operation was presented with no authority assertion. Refused,
+ * and never read as "act as the Citizen alone" (CAY-0100 §4).
+ */
+'authority_assertion_missing'
+/**
+ * The authority assertion did not verify: malformed, an issuer or key not
+ * registered for this type, a bad signature, expired, or already used. One member
+ * for all of them, so the refusal describes no part of the check to whoever is
+ * probing it.
+ */
+ | 'authority_assertion_invalid'
+/** The two assertions name different subjects. */
+ | 'subject_mismatch'
+/** The authority's `operation` is not in Percayso ID's `scope`. */
+ | 'operation_not_in_scope'
+/**
+ * The authority's `operation` is not the operation of the route it was presented
+ * on, so an authority minted for one act cannot be spent on another.
+ */
+ | 'operation_not_the_routes'
+/** The two assertions carry different `auth_time`s, so no one passkey tap serves both. */
+ | 'auth_time_mismatch'
+/** The two assertions are not both unexpired at the same moment. */
+ | 'not_jointly_current';
+/**
+ * Whether `value` is a well-formed {@link AuthorityClaims.mandateVersion}: a JSON integer
+ * of at least 1. The one statement of the shape, so the verifier (#416) and any consumer
+ * check it the same way. It says nothing about what the mandate allows.
+ */
+export declare function isMandateVersion(value: unknown): value is number;

package/dist/authority.js

@@ -0,0 +1,49 @@
+/*
+ * Copyright 2026 Percayso Community
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * The request header an authority assertion travels in, beside the identity
+ * assertion's `Authorization: Bearer` (CAY-0100 §4).
+ *
+ * ## Why this name
+ *
+ * - **Not `Authorization`.** That header carries Percayso ID's assertion and only
+ *   it. A request has one `Authorization`, and the two credentials are verified by
+ *   two verifiers against two registrations, so neither may be mistaken for the
+ *   other by where it arrived.
+ * - **No `X-` prefix.** RFC 6648 retired it, and the one header this contract
+ *   already names beside `Authorization` is `Idempotency-Key`, which has none. This
+ *   follows that spelling: two words, each capitalised, hyphenated.
+ * - **The glossary's noun.** CAY-0100 calls the credential BizID's *authority
+ *   assertion*, so the header says that and nothing more. It does not name BizID,
+ *   for the reason `Authorization` does not name Percayso ID: who minted it is the
+ *   credential's `iss`, checked against a registration, never a header's say-so.
+ *
+ * The value is the compact JWS alone, with no `Bearer` scheme: the scheme belongs to
+ * `Authorization`'s grammar, and this header has no other value to tell it from.
+ *
+ * Published as a value so a consumer that does not use the thin client spells it
+ * from the contract rather than from a retyped copy, and so the service that reads
+ * it reads the same string.
+ */
+export const AUTHORITY_ASSERTION_HEADER = 'Authority-Assertion';
+/**
+ * Whether `value` is a well-formed {@link AuthorityClaims.mandateVersion}: a JSON integer
+ * of at least 1. The one statement of the shape, so the verifier (#416) and any consumer
+ * check it the same way. It says nothing about what the mandate allows.
+ */
+export function isMandateVersion(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 1;
+}