@percayso-community/cayso-contracts 1.0.0 → 2.0.0

package/README.md

@@ -26,15 +26,27 @@ 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.
+**Percayso BizID's authority assertion** (CAY-0100) is published, and from `2.0.0`
+it is served: an act on an Organisation Wallet needs 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. Cayso binds it to the identity assertion — the same
+`sub`, the same `auth_time`, its `operation` in the identity assertion's `scope` and
+equal to the route's, both current at once — on `provisionOrganisation`,
+`makeCommercialPayment` on the `'mandate'` route, and `authorisePurchase` with any
+`onBehalfOfWalletId`, which must then name the wallet the bound Organisation is bound
+to, and refuses one that does not bind with a member of the closed
+`AuthorityBindingRefusal`. The payment-allowance route and a Citizen's own purchase need
+none. `AssertionClaims` declares `auth_time`, which
+Percayso ID mints and the binding compares. `organisationAuthority` and `mandateFor`
+are retired, authorise nothing, and are still published until the major that removes
+them.
+
+**`2.0.0` is a major, breaking on the wire from `1.0.0`** (CAY-0101): it lists
+nothing older, so `GET /api/version` answers `2.0.0` alone, and a consumer on `1.0.0`
+or on the `0.x` line that negotiates through it stops reading this Cayso until it
+moves to `2.0.0`. See `CONTRACT_VERSION`'s docblock for what changed.
 
 **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
@@ -124,8 +136,8 @@ consumer's handshake accepts a Cayso if `contractVersion` or any entry of
 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),
+`1.0.0` kept `0.32.0`, `0.31.0`, `0.30.0` and `0.29.0`, and `2.0.0`, the next major,
+dropped 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

package/dist/authority.d.ts

@@ -9,11 +9,11 @@
  * 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.
+ * This file is the SHAPE ALONE. 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.
+ * Percayso ID's assertion are Cayso's (#415–#417), and from `2.0.0` the binding is
+ * served: an act on an Organisation Wallet without a binding authority assertion is
+ * refused with a member of {@link AuthorityBindingRefusal}.
  *
  * ## The envelope is the identity assertion's
  *
@@ -178,9 +178,9 @@ export interface AuthorityClaims {
  * 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.
+ * Published at `0.31.0`, before anything produced it, as `founder_wallet_lapsed` was,
+ * and produced from `2.0.0` on the Organisation operations (#417). 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

package/dist/client.d.ts

@@ -182,24 +182,22 @@ export interface CaysoClient {
      */
     claimFounderWallet(): Promise<CitizenshipFounderClaimed>;
     /**
-     * Provision the ORGANISATION the caller's assertion attests authority for, and
-     * answer its wallet (CAY-0059).
+     * Provision the ORGANISATION BizID's authority assertion names, and answer its
+     * wallet (CAY-0059, CAY-0100 §1).
      *
-     * IT TAKES NO ARGUMENT, AND THAT IS THE DECISION RATHER THAN AN OVERSIGHT. The
-     * Organisation ID is read from the organisation-authority claim on the verified
-     * assertion and from nowhere else — so there is no value a caller could pass
-     * that would reach the holder key, and a signature here naming an organisation
-     * would be the wallet-creation oracle CAY-0057 describes.
+     * IT NAMES NO ORGANISATION, AND THAT IS THE DECISION RATHER THAN AN OVERSIGHT. The
+     * Organisation ID is read from the `organisationId` of BizID's authority assertion,
+     * bound to the verified identity assertion, and from nowhere else — so there is no
+     * value a caller could pass that would reach the holder key, and a signature here
+     * naming an organisation would be the wallet-creation oracle CAY-0057 describes.
      *
-     * IDEMPOTENT on the attested Organisation ID, exactly as
-     * {@link provisionCitizenship} is idempotent on the caller's own identity, so it
-     * 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.
+     * IDEMPOTENT on the Organisation ID, exactly as {@link provisionCitizenship} is
+     * idempotent on the caller's own identity, so it carries no idempotency key and a
+     * repeat is the same act rather than a second one.
      *
      * `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.
+     * (CAY-0100 §4). From `2.0.0` it is required: without it the call is refused
+     * `authority_assertion_missing`, and nothing is provisioned.
      */
     provisionOrganisation(authority?: AuthorityAssertionProvider): Promise<OrganisationView>;
     /**
@@ -219,9 +217,9 @@ export interface CaysoClient {
      * 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.
+     * `authority` supplies BizID's authority assertion for a purchase on behalf of a wallet:
+     * every `onBehalfOfWalletId` needs one, naming the Organisation that wallet is bound to
+     * (CAY-0100 §4a). A Citizen's own purchase needs none and passes none.
      */
     authorisePurchase(req: PurchaseRequest, authority?: AuthorityAssertionProvider): Promise<PurchaseAuthorised | PurchaseTerminal>;
     getPurchase(purchaseId: string): Promise<PurchaseResult>;

package/dist/contract-schema.generated.js

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 export const CONTRACT_SCHEMA = {
-    "contractVersion": "1.0.0",
+    "contractVersion": "2.0.0",
     "packageName": "@percayso-community/cayso-contracts",
     "capabilities": {
         "wallet": "cayso.wallet",

package/dist/errors.d.ts

@@ -227,8 +227,8 @@ export type CaysoApiErrorCode =
  * No authority issuer is registered on this deployment, so no authority assertion
  * from Percayso BizID is verified and no act that needs one is performed (CAY-0100).
  * A closed door, never a refusal of the assertion and never "act as the Citizen
- * alone". Declared before any route answers it: the binding to the identity
- * assertion is the first to serve it. Not `authority_assertion_invalid`, which says
+ * alone". Declared before any route answered it, and now answered, as a closed door, by the
+ * binding to the identity assertion. Not `authority_assertion_invalid`, which says
  * the assertion was presented and refused.
  */
  | 'authority_issuer_not_configured'

package/dist/index.d.ts

@@ -84,6 +84,29 @@
  * `supportedContractVersions` is on its own line: from `1.0.0` the same major, below
  * it the same minor.
  *
+ * `1.0.0` → `2.0.0` SERVES the two-signer binding (CAY-0100 §4, §4a, #417), and it is
+ * a MAJOR, BREAKING ON THE WIRE, declared so under CAY-0101. It lists nothing older: a
+ * deployment of it serves `2.0.0` alone, so `1.0.0` and the `0.x` transition major 1
+ * carried are no longer served. No type in this package changed shape; the behaviour
+ * behind three routes a `1.0.0` consumer already calls did:
+ *
+ *   - **`ROUTES.organisationProvision`** reads the Organisation ID from BizID's
+ *     {@link AuthorityClaims}, sent in {@link AUTHORITY_ASSERTION_HEADER} and bound to
+ *     the identity assertion, and no longer from `organisationAuthority`. Without the
+ *     header it answers `401 authority_assertion_missing`, where it used to provision
+ *     or answer `403 no_organisation_authority`.
+ *   - **`ROUTES.commercialPayment` on the `'mandate'` route** is authorised by the bound
+ *     `AuthorityClaims`, not by `mandateFor`. The payment-allowance route is unchanged.
+ *   - **`ROUTES.purchaseAuthorise` with any `onBehalfOfWalletId`** is authorised the
+ *     same way, and the wallet named must be the one the bound Organisation is bound to;
+ *     `mandateFor` authorises no delegated purchase, into any wallet. A Citizen's own
+ *     purchase is unchanged.
+ *
+ * On those three acts the members of {@link AuthorityBindingRefusal} and
+ * `authority_issuer_not_configured` now reach the wire, which `0.31.0` declared and no
+ * route produced up to `1.0.0`. `organisationAuthority` and `mandateFor` stay declared,
+ * and are removed by a later major (#419).
+ *
  * `0.32.0` → `1.0.0` changes nothing but the version. Its content is exactly
  * `0.32.0`'s, and a deployment of it keeps serving `0.32.0`, `0.31.0`, `0.30.0` and
  * `0.29.0` as a declared transition from the `0.x` line, which the next major ends. The
@@ -652,7 +675,7 @@
  * have needed a breaking bump on their own. Under semver below `1.0.0` the minor
  * is where a breaking change goes, so the minor moves and the patch does not.
  */
-export declare const CONTRACT_VERSION: "1.0.0";
+export declare const CONTRACT_VERSION: "2.0.0";
 /** The package's own name, so a consumer can name what it depends on. */
 export declare const packageName = "@percayso-community/cayso-contracts";
 /**

package/dist/index.js

@@ -100,6 +100,29 @@
  * `supportedContractVersions` is on its own line: from `1.0.0` the same major, below
  * it the same minor.
  *
+ * `1.0.0` → `2.0.0` SERVES the two-signer binding (CAY-0100 §4, §4a, #417), and it is
+ * a MAJOR, BREAKING ON THE WIRE, declared so under CAY-0101. It lists nothing older: a
+ * deployment of it serves `2.0.0` alone, so `1.0.0` and the `0.x` transition major 1
+ * carried are no longer served. No type in this package changed shape; the behaviour
+ * behind three routes a `1.0.0` consumer already calls did:
+ *
+ *   - **`ROUTES.organisationProvision`** reads the Organisation ID from BizID's
+ *     {@link AuthorityClaims}, sent in {@link AUTHORITY_ASSERTION_HEADER} and bound to
+ *     the identity assertion, and no longer from `organisationAuthority`. Without the
+ *     header it answers `401 authority_assertion_missing`, where it used to provision
+ *     or answer `403 no_organisation_authority`.
+ *   - **`ROUTES.commercialPayment` on the `'mandate'` route** is authorised by the bound
+ *     `AuthorityClaims`, not by `mandateFor`. The payment-allowance route is unchanged.
+ *   - **`ROUTES.purchaseAuthorise` with any `onBehalfOfWalletId`** is authorised the
+ *     same way, and the wallet named must be the one the bound Organisation is bound to;
+ *     `mandateFor` authorises no delegated purchase, into any wallet. A Citizen's own
+ *     purchase is unchanged.
+ *
+ * On those three acts the members of {@link AuthorityBindingRefusal} and
+ * `authority_issuer_not_configured` now reach the wire, which `0.31.0` declared and no
+ * route produced up to `1.0.0`. `organisationAuthority` and `mandateFor` stay declared,
+ * and are removed by a later major (#419).
+ *
  * `0.32.0` → `1.0.0` changes nothing but the version. Its content is exactly
  * `0.32.0`'s, and a deployment of it keeps serving `0.32.0`, `0.31.0`, `0.30.0` and
  * `0.29.0` as a declared transition from the `0.x` line, which the next major ends. The
@@ -668,7 +691,7 @@
  * have needed a breaking bump on their own. Under semver below `1.0.0` the minor
  * is where a breaking change goes, so the minor moves and the patch does not.
  */
-export const CONTRACT_VERSION = '1.0.0';
+export const CONTRACT_VERSION = '2.0.0';
 /** The package's own name, so a consumer can name what it depends on. */
 export const packageName = '@percayso-community/cayso-contracts';
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percayso-community/cayso-contracts",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "The versioned capability contract surface through which anything outside this repository reads a wallet. Published; keep it the surface of every consumer outside this tree, Piper and the Percayso Cloud, and nothing internal.",
   "license": "Apache-2.0",
   "repository": {