@percayso-community/cayso-contracts 0.30.0 → 1.0.0

package/README.md

@@ -26,20 +26,32 @@ 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.
 
-**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`:
+**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
@@ -53,7 +65,7 @@ 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: the published, versioned surface a consumer in another language generates its types from. |
-| `@percayso-community/cayso-contracts/operator` | The three operator reads' types and route constants, for an operator app's server. |
+| `@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.
@@ -84,8 +96,10 @@ 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.
@@ -103,10 +117,16 @@ 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

package/dist/assertion.d.ts

@@ -756,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
@@ -907,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
      *
@@ -944,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/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;
+}

package/dist/client.d.ts

@@ -24,6 +24,23 @@
  * so each attempt gets a fresh one. That the retry re-fetches is a decision, not
  * an accident.
  *
+ * ## A second assertion, on the Organisation operations alone
+ *
+ * An act on an Organisation Wallet needs BizID's authority assertion beside Percayso
+ * ID's (CAY-0100 §4). The three methods that can be one take an optional
+ * {@link AuthorityAssertionProvider} as their last argument, and nothing else does.
+ * Its `getAuthorityAssertion()` is called under exactly the discipline above: inside
+ * each attempt, beside `getAssertion()`, never cached, and re-fetched on a retry,
+ * because the authority assertion is short-lived and single-use too. It travels in
+ * its own header, {@link AUTHORITY_ASSERTION_HEADER}, never in `Authorization`.
+ *
+ * It is per CALL rather than a client option, and that is the point. BizID mints an
+ * authority for one operation and one Organisation, and these methods name no
+ * Organisation, so only the caller knows which Organisation this act is for. A
+ * client-wide provider would have to guess, or would hand every Organisation
+ * operation the same authority. Passing none sends no header, and the request is
+ * exactly the request a `0.30.0` client sent.
+ *
  * ## One method per route, no method that is not
  *
  * Every method reads its method and path from `ROUTES` — no URL is hand-written
@@ -107,6 +124,19 @@ export interface CaysoClientOptions {
      */
     warn?: (message: string) => void;
 }
+/**
+ * Where an Organisation operation gets BizID's authority assertion for this one act
+ * (CAY-0100 §4): the second credential, beside the one `getAssertion` supplies.
+ *
+ * Called before EVERY attempt, never once and never cached, for the reason
+ * `getAssertion` is: the credential is short-lived and single-use, so one minted for
+ * a first attempt must not be presented again by a retry. The value is the compact
+ * JWS BizID minted, sent in {@link AUTHORITY_ASSERTION_HEADER} exactly as returned.
+ */
+export interface AuthorityAssertionProvider {
+    /** Called before every attempt. Authority assertions are short-lived, so never cache one. */
+    getAuthorityAssertion(): Promise<string>;
+}
 /**
  * One method per entry in `ROUTES`, and no method that is not. `getMyWallet`
  * answers `null` where the contract says a wallet may not exist yet, rather than
@@ -166,8 +196,12 @@ export interface CaysoClient {
      * carries no idempotency key and a repeat is the same act rather than a second
      * one. A credential carrying no organisation authority is refused; absence
      * provisions nothing.
+     *
+     * `authority` supplies BizID's authority assertion for `provision-organisation`
+     * (CAY-0100 §4). Optional, and sent only when given: no route reads it until the
+     * binding is served, and from then an Organisation operation without it is refused.
      */
-    provisionOrganisation(): Promise<OrganisationView>;
+    provisionOrganisation(authority?: AuthorityAssertionProvider): Promise<OrganisationView>;
     /**
      * Authorise a purchase — or REPLAY one (CAY-0032). Posting the same
      * `idempotencyKey` twice returns the ORIGINAL authorisation, at the original
@@ -184,8 +218,12 @@ export interface CaysoClient {
      * `'terminal'` means the key's purchase has finished and will not change: a
      * repeat of it will keep answering `'terminal'` forever, and the remedy is a new
      * purchase under a NEW key.
+     *
+     * `authority` supplies BizID's authority assertion for a purchase on behalf of an
+     * Organisation Wallet, when `onBehalfOfWalletId` names one (CAY-0100 §4a). A
+     * Citizen's own purchase needs none and passes none.
      */
-    authorisePurchase(req: PurchaseRequest): Promise<PurchaseAuthorised | PurchaseTerminal>;
+    authorisePurchase(req: PurchaseRequest, authority?: AuthorityAssertionProvider): Promise<PurchaseAuthorised | PurchaseTerminal>;
     getPurchase(purchaseId: string): Promise<PurchaseResult>;
     /**
      * Cancel a purchase the caller started, releasing its reservation (CAY-0032).
@@ -213,8 +251,11 @@ export interface CaysoClient {
      * thrown {@link CaysoApiError} whose `code` is a `CommercialPaymentRefusal`
      * member, one of the gate's codes, or a seam code, as {@link authorisePurchase}'s
      * refusals do. A refusal means nothing moved.
+     *
+     * `authority` supplies BizID's authority assertion on the `'mandate'` route
+     * (CAY-0100 §4a). The `'payment-allowance'` route needs none and passes none.
      */
-    makeCommercialPayment(req: CommercialPaymentRequest): Promise<CommercialPaymentMade>;
+    makeCommercialPayment(req: CommercialPaymentRequest, authority?: AuthorityAssertionProvider): Promise<CommercialPaymentMade>;
     /**
      * Transfer unrestricted cents from the caller's own Citizen Wallet to another
      * Citizen Wallet — or REPLAY a transfer already made under the same key (CAY-0088).

package/dist/client.js

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { CONTRACT_VERSION, NOT_PROVISIONED } from './index.js';
+import { AUTHORITY_ASSERTION_HEADER, CONTRACT_VERSION, NOT_PROVISIONED } from './index.js';
 import { ROUTES } from './routes.js';
 // --- The retry mechanism -----------------------------------------------------
 // These are this slice's own mechanism, not economics: an attempt count, a
@@ -110,6 +110,16 @@ function buildClient(options, internals) {
             if (spec.idempotencyKey !== undefined && spec.idempotencyKey.length > 0) {
                 headers['Idempotency-Key'] = spec.idempotencyKey;
             }
+            // The second credential, under the first one's discipline: per attempt, never
+            // cached, and in a header of its own (CAY-0100 §4). Absent unless the caller
+            // passed a provider, so every other request is unchanged. An empty value is sent
+            // as no header, as an empty key is above, so the server reads it as missing
+            // rather than as present and malformed.
+            if (spec.authority !== undefined) {
+                const authority = await spec.authority.getAuthorityAssertion();
+                if (authority.length > 0)
+                    headers[AUTHORITY_ASSERTION_HEADER] = authority;
+            }
             const init = { method: spec.method, headers };
             if (spec.body !== undefined)
                 init.body = JSON.stringify(spec.body);
@@ -190,7 +200,7 @@ function buildClient(options, internals) {
                 idempotent: true,
             });
         },
-        async provisionOrganisation() {
+        async provisionOrganisation(authority) {
             return requestJson({
                 method: ROUTES.organisationProvision.method,
                 path: ROUTES.organisationProvision.path,
@@ -198,9 +208,10 @@ function buildClient(options, internals) {
                 // is: the operation is idempotent on the attested Organisation ID, so a
                 // repeat is the same act rather than a second one.
                 idempotent: true,
+                authority,
             });
         },
-        async authorisePurchase(req) {
+        async authorisePurchase(req, authority) {
             return requestJson({
                 method: ROUTES.purchaseAuthorise.method,
                 path: ROUTES.purchaseAuthorise.path,
@@ -208,9 +219,10 @@ function buildClient(options, internals) {
                 idempotent: typeof req.idempotencyKey === 'string' && req.idempotencyKey.length > 0,
                 body: req,
                 idempotencyKey: req.idempotencyKey,
+                authority,
             });
         },
-        async makeCommercialPayment(req) {
+        async makeCommercialPayment(req, authority) {
             return requestJson({
                 method: ROUTES.commercialPayment.method,
                 path: ROUTES.commercialPayment.path,
@@ -219,6 +231,7 @@ function buildClient(options, internals) {
                 idempotent: typeof req.idempotencyKey === 'string' && req.idempotencyKey.length > 0,
                 body: req,
                 idempotencyKey: req.idempotencyKey,
+                authority,
             });
         },
         async makeCitizenTransfer(req) {

package/dist/cloud-settlement.d.ts

@@ -98,9 +98,11 @@
  * A **withheld** contribution row is carried and settles nothing: it writes no
  * movement and does not refuse the period. How a later period pays what was withheld
  * is open (CAY-0096 §5). A row of nought cents writes no movement either, though every
- * check on it still runs. A **Core Node**'s qualified row is refused with its own
- * member, `contribution_node_is_a_core_node`: a Core Node's owner is the Operator, and
- * where its contribution settles, if anywhere, is not designed (CAY-0096 §4).
+ * check on it still runs. A **Core Node**'s qualified row of any amount but nought is
+ * refused with its own member, `contribution_node_is_a_core_node`: a Core Node's owner is
+ * the Operator, and where its contribution settles, if anywhere, is not designed
+ * (CAY-0096 §4). A Core Node row of nought cents is skipped and settles nothing, an
+ * interim rule pending that design (30 October 2026, cloud.platform#357).
  *
  * ## What is not here
  *
@@ -734,8 +736,9 @@ export type ContributionRowRefusal =
  */
 'contribution_node_not_bound'
 /**
- * A qualified row names a Node this deployment is told is a Core Node. A Core
- * Node's owner is the Operator (CMTY-0018 §4), so it settles to no Citizen Wallet.
+ * A qualified row of more than nought cents names a Node this deployment is told is a
+ * Core Node. A Core Node's owner is the Operator (CMTY-0018 §4), so it settles to no
+ * Citizen Wallet. A nought row for a Core Node is skipped instead (interim, #357).
  */
  | 'contribution_node_is_a_core_node'
 /** The Treasury holds too few unrestricted cents to pay this row. */