@percayso-community/cayso-contracts 1.0.0 → 2.1.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/assertion.d.ts

@@ -394,8 +394,12 @@
  * 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.
+ *
+ * `'bind-enrolled-node'` is the Citizen binding a Node the Registry enrolled under them
+ * to their own wallet (CMTY-0018 §4, CAY-0095 Amendment 1): the Citizen's own tap, no
+ * Instance key. Its own operation for the same reason as `'bind-node'`.
  */
-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';
+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' | 'bind-enrolled-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

package/dist/assurance.js

@@ -553,6 +553,22 @@ export const ASSURANCE_POLICY = {
             'held to the bar of presenting a standing authorisation: anything but the development ' +
             'bypass.',
     },
+    // The Citizen binding a Node the Registry enrolled under them (CAY-0095 Amendment 1).
+    // The same bar as 'bind-node', for the same reason: where a Node's earnings land.
+    'bind-enrolled-node': {
+        operation: 'bind-enrolled-node',
+        assurance: 'required',
+        decisions: {
+            // Asserts nothing; permanently refused wherever "identity-verified" is meant.
+            'dev-bypass': 'refused',
+            document: 'accepted',
+            'document-and-biometric': 'accepted',
+        },
+        rationale: "Binding an enrolled 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
@@ -596,6 +612,7 @@ export const OPERATION_FOR_ROUTE = {
     standingAuthorisation: 'present-standing-authorisation',
     revokeStandingAuthorisation: 'revoke-standing-authorisation',
     bindNode: 'bind-node',
+    bindEnrolledNode: 'bind-enrolled-node',
     version: null,
 };
 /**

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

@@ -86,7 +86,7 @@
  */
 import type { BuyBackMade, BuyBackRequest, CitizenMarketViewed, QuotePlaced, QuoteRequest, QuoteWithdrawalRequest, QuoteWithdrawn } from './citizen-market.js';
 import type { CitizenshipFounderClaimed, CitizenshipView } from './citizenship.js';
-import type { StandingAuthorisationAcknowledged, StandingAuthorisationRequest, StandingAuthorisationRevocationRequest, StandingAuthorisationRevoked, NodeBindingRequest, NodeBound } from './cloud-settlement.js';
+import type { StandingAuthorisationAcknowledged, StandingAuthorisationRequest, StandingAuthorisationRevocationRequest, StandingAuthorisationRevoked, NodeBindingRequest, NodeBound, NodeEnrolmentBindingRequest } from './cloud-settlement.js';
 import type { CitizenTransferMade, CitizenTransferRequest } from './citizen-transfer.js';
 import type { CommercialPaymentMade, CommercialPaymentRequest } from './commercial-payment.js';
 import type { HandleChangeCharged, HandleChangeReceiptReadResponse } from './handle-change.js';
@@ -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>;
@@ -370,6 +368,14 @@ export interface CaysoClient {
      * nothing was bound.
      */
     bindNode(req: NodeBindingRequest): Promise<NodeBound>;
+    /**
+     * Bind a Node the Registry enrolled under the caller to the caller's own wallet, under
+     * the caller's money-grade assertion (`bind-enrolled-node`, CAY-0095 Amendment 1).
+     * Safe to repeat: the same Node bound to the same wallet answers `bound` again and
+     * writes nothing. A refusal arrives as a thrown {@link CaysoApiError} whose `code` is a
+     * `NodeEnrolmentBindingRefusal` member, one of the gate's codes, or a seam code.
+     */
+    bindEnrolledNode(req: NodeEnrolmentBindingRequest): Promise<NodeBound>;
     getVersion(): Promise<CaysoVersion>;
 }
 /**

package/dist/client.js

@@ -340,6 +340,15 @@ function buildClient(options, internals) {
                 body: req,
             });
         },
+        async bindEnrolledNode(req) {
+            return requestJson({
+                method: ROUTES.bindEnrolledNode.method,
+                path: ROUTES.bindEnrolledNode.path,
+                // Safe to repeat: the same Node bound to the same wallet answers the same.
+                idempotent: true,
+                body: req,
+            });
+        },
         async getPurchase(purchaseId) {
             return requestJson({
                 method: ROUTES.purchaseResult.method,

package/dist/cloud-settlement.d.ts

@@ -469,6 +469,61 @@ export type NodeBindingRefusal =
  | 'core_node_not_bound'
 /** The Node is already bound to a different wallet. A binding is never re-pointed. */
  | 'node_bound_to_another_wallet';
+/**
+ * The Registry's statement that a Node is enrolled under a Citizen (CMTY-0018 §4, CMTY-0019,
+ * CAY-0095 Amendment 1): a CAY-0072 compact signed by a Registry key, whose header `kid`
+ * names that key. `iss` is the Registry's issuer, one fixed string per environment. `sub` is the Citizen's Percayso ID subject, which must be
+ * the verified assertion's.
+ */
+export interface NodeEnrolmentClaims {
+    /** The Registry's issuer for this environment, e.g. `percayso-cloud-registry:dev`. Not the `kid`. */
+    readonly iss: string;
+    /** Exactly `'cayso'`, and checked, not merely present. */
+    readonly aud: 'cayso';
+    /** The Citizen the Node is enrolled under: their Percayso ID subject. */
+    readonly sub: string;
+    /** The Node enrolled. */
+    readonly node_id: NodeId;
+    /** Issued-at, in **seconds** since the Unix epoch. */
+    readonly iat: number;
+    /** Expiry, in **seconds** since the Unix epoch. */
+    readonly exp: number;
+}
+/**
+ * The Citizen binding an enrolled Node to their own wallet (`bind-enrolled-node`): the
+ * Registry-signed {@link NodeEnrolmentClaims} compact, and nothing else. No Instance key,
+ * no standing authorisation, no wallet.
+ */
+export interface NodeEnrolmentBindingRequest {
+    readonly nodeEnrolment: string;
+}
+/** The enrolled-Node binding was refused, with one member of the closed union. Nothing was bound. */
+export interface NodeEnrolmentBindingRefused {
+    readonly outcome: 'refused';
+    readonly error: NodeEnrolmentBindingRefusal;
+}
+/**
+ * Why binding an enrolled Node was refused. Closed. Every member means nothing was bound.
+ */
+export type NodeEnrolmentBindingRefusal = 
+/** The verification method is outside the money-grade profile (`ASSURANCE_POLICY['bind-enrolled-node']`). */
+'assurance_not_money_grade'
+/** Not a compact in CAY-0072's format, or its claims are not exactly {@link NodeEnrolmentClaims} with `aud` `'cayso'`. */
+ | 'node_enrolment_malformed'
+/** `iss` is not this environment's Registry issuer, or the header's `kid` is no key of it. One member for both. */
+ | 'node_enrolment_issuer_not_recognised'
+/** The signature does not verify over the bytes presented, or `alg` is not the key's. */
+ | 'node_enrolment_signature_invalid'
+/** `exp` is at or before now, or `iat` is further ahead of now than the clock-skew tolerance. */
+ | 'node_enrolment_not_current'
+/** `sub` is not the verified holder's subject: the Node is enrolled under somebody else. */
+ | 'node_enrolment_not_for_holder'
+/** The verified holder has no Citizen Wallet bound now. */
+ | 'holder_has_no_wallet'
+/** The Node is a Core Node. Its owner is the Operator, so it is bound to no Citizen Wallet. */
+ | 'core_node_not_bound'
+/** The Node is already bound to a different wallet. A binding is never re-pointed. */
+ | 'node_bound_to_another_wallet';
 /**
  * The Contribution Store's question about one Node (CAY-0095): signed by a key of
  * the registered Store issuer, in CAY-0072's format, whose header `kid` names that

package/dist/contract-schema.generated.js

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 export const CONTRACT_SCHEMA = {
-    "contractVersion": "1.0.0",
+    "contractVersion": "2.1.0",
     "packageName": "@percayso-community/cayso-contracts",
     "capabilities": {
         "wallet": "cayso.wallet",
@@ -101,6 +101,10 @@ export const CONTRACT_SCHEMA = {
             "method": "POST",
             "path": "/api/cloud/node-bindings"
         },
+        "bindEnrolledNode": {
+            "method": "POST",
+            "path": "/api/cloud/node-enrolment-bindings"
+        },
         "version": {
             "method": "GET",
             "path": "/api/version"
@@ -930,6 +934,9 @@ export const CONTRACT_SCHEMA = {
                     {
                         "literal": "core_node_ids_not_configured"
                     },
+                    {
+                        "literal": "node_registry_not_configured"
+                    },
                     {
                         "literal": "contribution_store_issuer_not_configured"
                     },
@@ -1005,6 +1012,9 @@ export const CONTRACT_SCHEMA = {
                     {
                         "ref": "NodeBindingRefusal"
                     },
+                    {
+                        "ref": "NodeEnrolmentBindingRefusal"
+                    },
                     {
                         "ref": "NodeBindingQueryRefusal"
                     },
@@ -1824,6 +1834,9 @@ export const CONTRACT_SCHEMA = {
                     },
                     {
                         "literal": "bind-node"
+                    },
+                    {
+                        "literal": "bind-enrolled-node"
                     }
                 ]
             }
@@ -3239,6 +3252,118 @@ export const CONTRACT_SCHEMA = {
                 }
             }
         },
+        "NodeEnrolmentBindingRefusal": {
+            "kind": "alias",
+            "of": {
+                "union": [
+                    {
+                        "literal": "assurance_not_money_grade"
+                    },
+                    {
+                        "literal": "node_enrolment_malformed"
+                    },
+                    {
+                        "literal": "node_enrolment_issuer_not_recognised"
+                    },
+                    {
+                        "literal": "node_enrolment_signature_invalid"
+                    },
+                    {
+                        "literal": "node_enrolment_not_current"
+                    },
+                    {
+                        "literal": "node_enrolment_not_for_holder"
+                    },
+                    {
+                        "literal": "holder_has_no_wallet"
+                    },
+                    {
+                        "literal": "core_node_not_bound"
+                    },
+                    {
+                        "literal": "node_bound_to_another_wallet"
+                    }
+                ]
+            }
+        },
+        "NodeEnrolmentBindingRefused": {
+            "kind": "object",
+            "properties": {
+                "outcome": {
+                    "type": {
+                        "literal": "refused"
+                    },
+                    "readonly": true,
+                    "optional": false
+                },
+                "error": {
+                    "type": {
+                        "ref": "NodeEnrolmentBindingRefusal"
+                    },
+                    "readonly": true,
+                    "optional": false
+                }
+            }
+        },
+        "NodeEnrolmentBindingRequest": {
+            "kind": "object",
+            "properties": {
+                "nodeEnrolment": {
+                    "type": {
+                        "scalar": "string"
+                    },
+                    "readonly": true,
+                    "optional": false
+                }
+            }
+        },
+        "NodeEnrolmentClaims": {
+            "kind": "object",
+            "properties": {
+                "iss": {
+                    "type": {
+                        "scalar": "string"
+                    },
+                    "readonly": true,
+                    "optional": false
+                },
+                "aud": {
+                    "type": {
+                        "literal": "cayso"
+                    },
+                    "readonly": true,
+                    "optional": false
+                },
+                "sub": {
+                    "type": {
+                        "scalar": "string"
+                    },
+                    "readonly": true,
+                    "optional": false
+                },
+                "node_id": {
+                    "type": {
+                        "ref": "NodeId"
+                    },
+                    "readonly": true,
+                    "optional": false
+                },
+                "iat": {
+                    "type": {
+                        "scalar": "number"
+                    },
+                    "readonly": true,
+                    "optional": false
+                },
+                "exp": {
+                    "type": {
+                        "scalar": "number"
+                    },
+                    "readonly": true,
+                    "optional": false
+                }
+            }
+        },
         "NodeId": {
             "kind": "alias",
             "of": {

package/dist/errors.d.ts

@@ -45,7 +45,7 @@
 import type { AuthorityBindingRefusal } from './authority.js';
 import type { FounderClaimRefusal } from './citizenship.js';
 import type { BuyBackRefusal, QuotePlacementRefusal, QuoteWithdrawalRefusal } from './citizen-market.js';
-import type { SettlementAssertionRefusal, StandingAuthorisationRefusal, StandingAuthorisationRevocationRefusal, NodeBindingQueryRefusal, NodeBindingRefusal } from './cloud-settlement.js';
+import type { SettlementAssertionRefusal, StandingAuthorisationRefusal, StandingAuthorisationRevocationRefusal, NodeBindingQueryRefusal, NodeBindingRefusal, NodeEnrolmentBindingRefusal } from './cloud-settlement.js';
 import type { CitizenTransferRefusal } from './citizen-transfer.js';
 import type { HandleChangeReceiptReadRefusal, HandleChangeRefusal } from './handle-change.js';
 import type { CommercialPaymentRefusal } from './commercial-payment.js';
@@ -216,6 +216,8 @@ export type CaysoApiErrorCode =
  * Citizen Wallet. Told "none" is a configuration; untold is a closed door.
  */
  | 'core_node_ids_not_configured'
+/** No Registry key is configured to verify a Node enrolment (CAY-0095, its first amendment). */
+ | 'node_registry_not_configured'
 /**
  * No Contribution Store issuer is registered on this deployment, so no statement
  * from the Store is verified and the Store's read of a Node's binding is not
@@ -227,8 +229,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'
@@ -265,7 +267,7 @@ export type CaysoApiErrorCode =
 /** There is no such purchase under this caller's wallet. */
  | 'not_found'
 /** Something failed on the way and the refusal discloses nothing further. */
- | 'internal_error' | PurchaseFailureReason | PurchaseCancelRefusalReason | FounderClaimRefusal | CommercialPaymentRefusal | CitizenTransferRefusal | HandleChangeRefusal | HandleChangeReceiptReadRefusal | QuotePlacementRefusal | QuoteWithdrawalRefusal | BuyBackRefusal | MarketplaceReceiptReadRefusal | MarketplaceOrderRefusal | MarketplaceRefundRefusal | StandingAuthorisationRefusal | StandingAuthorisationRevocationRefusal | NodeBindingRefusal | NodeBindingQueryRefusal | SettlementAssertionRefusal | AuthorityBindingRefusal;
+ | 'internal_error' | PurchaseFailureReason | PurchaseCancelRefusalReason | FounderClaimRefusal | CommercialPaymentRefusal | CitizenTransferRefusal | HandleChangeRefusal | HandleChangeReceiptReadRefusal | QuotePlacementRefusal | QuoteWithdrawalRefusal | BuyBackRefusal | MarketplaceReceiptReadRefusal | MarketplaceOrderRefusal | MarketplaceRefundRefusal | StandingAuthorisationRefusal | StandingAuthorisationRevocationRefusal | NodeBindingRefusal | NodeEnrolmentBindingRefusal | NodeBindingQueryRefusal | SettlementAssertionRefusal | AuthorityBindingRefusal;
 /**
  * The body of every refusal on this surface: one code, and nothing beside it.
  *

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.1.0";
 /** The package's own name, so a consumer can name what it depends on. */
 export declare const packageName = "@percayso-community/cayso-contracts";
 /**
@@ -825,7 +848,7 @@ export type { HandleChangeReceiptStatement, HandleChangeReceipt, HandleChangeCha
 export type { QuoteSide, QuoteRequest, Quote, QuotePlaced, QuoteRefused, QuoteResponse, QuoteEntryRefusal, QuotePlacementRefusal, QuoteWithdrawalRequest, QuoteWithdrawal, QuoteWithdrawn, QuoteWithdrawalRefused, QuoteWithdrawalResponse, QuoteWithdrawalRefusal, BuyBackRequest, BuyBack, BuyBackMade, BuyBackRefused, BuyBackResponse, BuyBackRefusal, BookLevel, QuoteStatus, QuoteWithdrawalReason, OwnQuote, OwnQuoteNotWithdrawn, OwnQuoteWithdrawn, CitizenMarketView, CitizenMarketViewed, CitizenMarketViewRefusal, CitizenMarketViewRefused, CitizenMarketResponse, } from './citizen-market.js';
 export type { MarketplaceReceiptSignatureAlgorithm, MarketplaceReceiptKeyId, MarketplaceSaleKind, MarketplaceReceiptLeg, MarketplaceSettlementReceiptStatement, HousePublisherChargeReceiptStatement, ThirdPartyRefundReceiptStatement, HousePublisherRefundReceiptStatement, MarketplaceReceiptStatement, MarketplaceReceipt, MarketplaceReceiptReadRequest, MarketplaceReceiptFound, MarketplaceNoMovement, MarketplaceReceiptReadRefusal, MarketplaceReceiptReadRefused, MarketplaceReceiptReadResponse, } from './marketplace-receipt.js';
 export type { StoreSignedStatement, MarketplaceOrderRequest, MarketplaceRefundRequest, MarketplaceOrderReceipt, MarketplaceRefundReceipt, MarketplaceOrderSettled, MarketplaceOrderRefused, MarketplaceOrderResponse, MarketplaceOrderRefusal, MarketplaceRefundSettled, MarketplaceRefundRefused, MarketplaceRefundResponse, MarketplaceRefundRefusal, } from './marketplace-settlement.js';
-export type { InstanceKeyId, SettlementPeriodRule, SettlementPeriodId, NodeId, ContributionStoreIssuer, PercaysoCloudAudience, StandingAuthorisationClaims, StandingAuthorisationRequest, AuthorisationAcknowledgementClaims, AcknowledgementKeyId, AcknowledgementPublicKey, AcknowledgementKeySet, StandingAuthorisationAcknowledged, StandingAuthorisationRefused, StandingAuthorisationResponse, StandingAuthorisationRefusal, StandingAuthorisationRevocationRequest, StandingAuthorisationRevoked, StandingAuthorisationRevocationRefused, StandingAuthorisationRevocationResponse, StandingAuthorisationRevocationRefusal, NodePresentationClaims, NodeBindingRequest, NodeBound, NodeBindingRefused, NodeBindingResponse, NodeBindingRefusal, NodeBindingQueryClaims, NodeBindingQueryRequest, NodeBindingStatus, NodeBindingQueryRefused, NodeBindingQueryRefusal, ContributionType, SettlementPeriod, ContributionWithheldReason, ContributionQualified, ContributionWithheld, ContributionQualification, ContributionRow, ConsumptionRow, SettlementTotals, SettlementAssertionClaims, SettlementAssertionRequest, SettlementAssertionSettled, SettlementAssertionRefused, ContributionRowRefused, ConsumptionRowRefused, SettlementAssertionResponse, SettlementAssertionLevelRefusal, ContributionRowRefusal, ConsumptionRowRefusal, SettlementAssertionRefusal, } from './cloud-settlement.js';
+export type { InstanceKeyId, SettlementPeriodRule, SettlementPeriodId, NodeId, ContributionStoreIssuer, PercaysoCloudAudience, StandingAuthorisationClaims, StandingAuthorisationRequest, AuthorisationAcknowledgementClaims, AcknowledgementKeyId, AcknowledgementPublicKey, AcknowledgementKeySet, StandingAuthorisationAcknowledged, StandingAuthorisationRefused, StandingAuthorisationResponse, StandingAuthorisationRefusal, StandingAuthorisationRevocationRequest, StandingAuthorisationRevoked, StandingAuthorisationRevocationRefused, StandingAuthorisationRevocationResponse, StandingAuthorisationRevocationRefusal, NodePresentationClaims, NodeBindingRequest, NodeBound, NodeBindingRefused, NodeBindingResponse, NodeBindingRefusal, NodeEnrolmentClaims, NodeEnrolmentBindingRequest, NodeEnrolmentBindingRefused, NodeEnrolmentBindingRefusal, NodeBindingQueryClaims, NodeBindingQueryRequest, NodeBindingStatus, NodeBindingQueryRefused, NodeBindingQueryRefusal, ContributionType, SettlementPeriod, ContributionWithheldReason, ContributionQualified, ContributionWithheld, ContributionQualification, ContributionRow, ConsumptionRow, SettlementTotals, SettlementAssertionClaims, SettlementAssertionRequest, SettlementAssertionSettled, SettlementAssertionRefused, ContributionRowRefused, ConsumptionRowRefused, SettlementAssertionResponse, SettlementAssertionLevelRefusal, ContributionRowRefusal, ConsumptionRowRefusal, SettlementAssertionRefusal, } from './cloud-settlement.js';
 export type { PurchaseRequest, PurchaseAuthorised, PurchaseTerminal, PurchaseUnresolved, PurchaseRefused, PurchaseAuthorisationResponse, PurchaseFailureReason, PurchaseStatus, LivePurchaseStatus, TerminalPurchaseStatus, PurchaseCancelRefusalReason, PurchaseCancelled, PurchaseCancelRefused, PurchaseCancelResponse, PurchaseResult, } from './purchase.js';
 export type { VerificationMethod, VerificationStatus, SubjectPersonhood, AssertionClaims, AssertionHeader, AssertionEnvelope, ContractOperation, InternalOperation, ScopeKey, } from './assertion.js';
 export type { AuthorityClaims, AuthorityEnvelope, AuthorityBindingRefusal } from './authority.js';

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.1.0';
 /** The package's own name, so a consumer can name what it depends on. */
 export const packageName = '@percayso-community/cayso-contracts';
 /**

package/dist/routes.d.ts

@@ -127,6 +127,11 @@
  * the wallet; the revocation is a row of its own beside them. The body names the
  * authorisation's `jti` and no wallet.
  *
+ * `bindEnrolledNode` binds a Node the Registry enrolled under the verified Citizen to that
+ * Citizen's own wallet (`bind-enrolled-node`, CAY-0095 Amendment 1). The body carries the
+ * Registry-signed enrolment and nothing else: no Instance key and no wallet. A `POST` to a
+ * collection of its own, for `bindNode`'s reasons.
+ *
  * `bindNode` binds a Node to the wallet its presenting Instance key is already bound
  * to (`bind-node`, CAY-0095), under the owner's assertion. A person is behind it, so
  * it is classified by a person's assurance. The body carries the Node ID signed by the
@@ -229,6 +234,10 @@ export declare const ROUTES: {
         readonly method: "POST";
         readonly path: "/api/cloud/node-bindings";
     };
+    readonly bindEnrolledNode: {
+        readonly method: "POST";
+        readonly path: "/api/cloud/node-enrolment-bindings";
+    };
     readonly version: {
         readonly method: "GET";
         readonly path: "/api/version";

package/dist/routes.js

@@ -142,6 +142,11 @@
  * the wallet; the revocation is a row of its own beside them. The body names the
  * authorisation's `jti` and no wallet.
  *
+ * `bindEnrolledNode` binds a Node the Registry enrolled under the verified Citizen to that
+ * Citizen's own wallet (`bind-enrolled-node`, CAY-0095 Amendment 1). The body carries the
+ * Registry-signed enrolment and nothing else: no Instance key and no wallet. A `POST` to a
+ * collection of its own, for `bindNode`'s reasons.
+ *
  * `bindNode` binds a Node to the wallet its presenting Instance key is already bound
  * to (`bind-node`, CAY-0095), under the owner's assertion. A person is behind it, so
  * it is classified by a person's assurance. The body carries the Node ID signed by the
@@ -187,6 +192,7 @@ export const ROUTES = {
         path: '/api/cloud/standing-authorisation-revocations',
     },
     bindNode: { method: 'POST', path: '/api/cloud/node-bindings' },
+    bindEnrolledNode: { method: 'POST', path: '/api/cloud/node-enrolment-bindings' },
     version: { method: 'GET', path: '/api/version' },
 };
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percayso-community/cayso-contracts",
-  "version": "1.0.0",
+  "version": "2.1.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": {