@percayso-community/cayso-contracts 0.27.0 → 0.30.0

package/README.md

@@ -21,7 +21,10 @@ 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`.
+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.
 
 **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
@@ -49,16 +52,34 @@ 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/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. |
 
 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
 
@@ -91,15 +112,18 @@ 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

@@ -326,6 +326,21 @@
  * credential minted to place a quote must not thereby move cents to somebody without
  * a match, nor the reverse. It is served at `ROUTES.citizenTransfer`.
  *
+ * `'change-handle'` is a Citizen's Handle change, charged by Cayso (CAY-0091). It is
+ * not a second use of `'make-citizen-transfer'`, which pays another Citizen, nor of
+ * `'settle-marketplace-order'`, which presents Store Platform's signed order: a Handle
+ * change charges the Citizen for a Community service on the authority of a change
+ * reference Percayso ID minted. A credential minted for any other operation must not
+ * authorise a Handle change, and the reverse. It is served at `ROUTES.handleChange`,
+ * and it charges for the change reference named by
+ * {@link AssertionClaims.handleChangeReference} and no other.
+ *
+ * `'read-handle-change-receipt'` asks whether a change reference was charged
+ * (CAY-0091), as `'read-marketplace-receipt'` asks of a checkout key. It is its own
+ * operation because it is a read beside the money-grade charge it reports on: a
+ * credential minted to ask what happened must not thereby be able to make something
+ * happen. It is served at `ROUTES.handleChangeReceipt`.
+ *
  * `'place-quote'`, `'withdraw-quote'` and `'request-buy-back'` are the citizen
  * market's three acts (CAY-0080, Open decision Q). They are three operations
  * because they are three acts: a credential minted to withdraw a quote must not
@@ -368,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' | '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
@@ -839,6 +864,42 @@ export interface AssertionClaims {
      * of work.
      */
     readonly founderClaimReference?: string;
+    /**
+     * The change reference: the single-use, opaque value Percayso ID issued when it
+     * reserved the Citizen's proposed Handle (CAY-0091). OPTIONAL on the wire, and read by
+     * `'change-handle'` and `'read-handle-change-receipt'` and by no other operation.
+     *
+     * ## It travels with its operations, in both directions
+     *
+     * As {@link founderClaimReference} does. A credential whose `scope` carries
+     * `'change-handle'` or `'read-handle-change-receipt'` must carry this claim, and a
+     * credential that carries this claim must be scoped to one of them. A verifier refuses
+     * either half missing as a malformed credential, before any gate reads it: a Handle
+     * change with no reference charges for nothing, and a reference carried to any other
+     * operation is half of a Handle change put in front of a route with no business
+     * reading it.
+     *
+     * ## It is carried here and never in a request
+     *
+     * The reference fixes the new Handle BEFORE the charge, so a receipt cannot be spent
+     * on a different name. A reference named in a body would be the caller's claim about
+     * which Handle change is theirs (CAY-0021); inside the signed assertion it is Percayso
+     * ID's statement. Cayso charges at most once per reference, keys the charge by it, and
+     * names it in the signed receipt.
+     *
+     * ## What it is not
+     *
+     * It is NOT the Handle. Cayso never learns the Handle: the reference is opaque, and
+     * Cayso compares it and never parses it. It is not derived from a Percayso identity,
+     * and it carries no `sub`, no name and no email. This contract asks for a non-empty
+     * string and nothing more.
+     *
+     * ## It is as trustworthy as the verifier, and no more
+     *
+     * As with every claim: declaring it makes the promise structural, and a real
+     * signature check is what makes it trustworthy.
+     */
+    readonly handleChangeReference?: string;
     /**
      * The Organisation **Wallet IDs** this identity holds the mandate for
      * (CAY-0024, CAY-0059 §7). Each entry is a wallet id — the opaque identifier

package/dist/assurance.js

@@ -343,6 +343,33 @@ export const ASSURANCE_POLICY = {
             'anything but the development bypass. An unverified holder must never be able to send, ' +
             'because sending is how value reaches somebody else.',
     },
+    // A Citizen paying Cayso to change their Handle (CAY-0091). Money-grade, at the
+    // Citizen transfer's bar: value leaves the holder, and the payment is what lets
+    // Percayso ID change a public name, so an unverified holder must not be able to
+    // make it. An allowlist, so a future method is admissible only when somebody
+    // decides it here.
+    'change-handle': {
+        operation: 'change-handle',
+        assurance: 'required',
+        decisions: {
+            // Asserts nothing; permanently refused wherever "identity-verified" is meant.
+            'dev-bypass': 'refused',
+            document: 'accepted',
+            'document-and-biometric': 'accepted',
+        },
+        rationale: "A Handle change charges the Citizen's own Citizen Wallet, so it is money-grade: anything " +
+            'but the development bypass. The receipt it answers with lets Percayso ID change a ' +
+            'Handle, which an unverified holder must never be able to buy.',
+    },
+    // Asking whether a change reference was charged (CAY-0091). A read: nothing moves and
+    // nothing is reserved, so it applies no bar, as the marketplace receipt read applies
+    // none. A credential scoped to it cannot charge anything.
+    'read-handle-change-receipt': {
+        operation: 'read-handle-change-receipt',
+        assurance: 'not-required',
+        rationale: 'Asking whether a change reference was charged moves nothing and reserves nothing. It ' +
+            'answers a receipt Cayso already signed, or that there was no charge, and nothing more.',
+    },
     // The citizen market's three acts (CAY-0080 §7, Open decision Q). All three are
     // money-grade and all three are allowlists, at the purchase path's bar: the acting
     // party is a Citizen, and a bar no issuer can yet clear would shut the market on
@@ -491,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
@@ -524,12 +586,16 @@ export const OPERATION_FOR_ROUTE = {
     purchaseCancel: 'cancel-purchase',
     commercialPayment: 'make-commercial-payment',
     citizenTransfer: 'make-citizen-transfer',
+    handleChange: 'change-handle',
+    handleChangeReceipt: 'read-handle-change-receipt',
     citizenMarket: 'read-citizen-market',
     placeQuote: 'place-quote',
     withdrawQuote: 'withdraw-quote',
     requestBuyBack: 'request-buy-back',
     marketplaceOrder: 'settle-marketplace-order',
     standingAuthorisation: 'present-standing-authorisation',
+    revokeStandingAuthorisation: 'revoke-standing-authorisation',
+    bindNode: 'bind-node',
     version: null,
 };
 /**

package/dist/client.d.ts

@@ -69,9 +69,10 @@
  */
 import type { BuyBackMade, BuyBackRequest, CitizenMarketViewed, QuotePlaced, QuoteRequest, QuoteWithdrawalRequest, QuoteWithdrawn } from './citizen-market.js';
 import type { CitizenshipFounderClaimed, CitizenshipView } from './citizenship.js';
-import type { StandingAuthorisationAcknowledged, StandingAuthorisationRequest } from './cloud-settlement.js';
+import type { StandingAuthorisationAcknowledged, StandingAuthorisationRequest, StandingAuthorisationRevocationRequest, StandingAuthorisationRevoked, NodeBindingRequest, NodeBound } 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';
 import type { MarketplaceOrderRequest, MarketplaceOrderSettled } from './marketplace-settlement.js';
 import type { OrganisationView } from './organisation.js';
 import type { PurchaseAuthorised, PurchaseCancelled, PurchaseRequest, PurchaseResult, PurchaseTerminal } from './purchase.js';
@@ -225,6 +226,24 @@ export interface CaysoClient {
      * refusal means nothing moved.
      */
     makeCitizenTransfer(req: CitizenTransferRequest): Promise<CitizenTransferMade>;
+    /**
+     * Charge the caller's own Citizen Wallet for a Handle change, and receive the signed
+     * receipt Percayso ID relies on (CAY-0091) — or, for a change reference already
+     * charged, the receipt of that charge, with nothing charged again.
+     *
+     * There is nothing to send: the change reference is inside the assertion, the wallet
+     * is the verified holder's own, and the price is Cayso's. A refusal arrives as a thrown
+     * {@link CaysoApiError} whose `code` is a `HandleChangeRefusal` member, one of the
+     * gate's codes, or a seam code. A refusal means nothing moved.
+     */
+    changeHandle(): Promise<HandleChangeCharged>;
+    /**
+     * Ask whether the change reference inside the assertion was charged for the caller
+     * (CAY-0091): its receipt, or `no-charge`. Never "pending". A refusal arrives as a
+     * thrown {@link CaysoApiError} whose `code` is a `HandleChangeReceiptReadRefusal`
+     * member, one of the gate's codes, or a seam code — and is never "no charge".
+     */
+    readHandleChangeReceipt(): Promise<HandleChangeReceiptReadResponse>;
     /**
      * Read the citizen market as the caller sees it (CAY-0080 §1.4): the published
      * value and its band, both bounds per quote unit, the best bid and the best ask with
@@ -285,10 +304,31 @@ export interface CaysoClient {
      * Safe to repeat: the authorisation's `jti` is its own key, and presenting the same
      * authorisation again binds nothing twice. A refusal arrives as a thrown
      * {@link CaysoApiError} whose `code` is a `StandingAuthorisationRefusal` member, one
-     * of the gate's codes, or a seam code, and means nothing was bound. Published before
-     * the route is served.
+     * of the gate's codes, or a seam code, and means nothing was bound. Each
+     * presentation answers a freshly signed acknowledgement.
      */
     presentStandingAuthorisation(req: StandingAuthorisationRequest): Promise<StandingAuthorisationAcknowledged>;
+    /**
+     * Revoke a standing authorisation the caller's wallet holds, named by its `jti`,
+     * under the owner's assertion (`revoke-standing-authorisation`, CAY-0094).
+     *
+     * Safe to repeat: revoking a revoked authorisation answers `revoked` again and
+     * writes nothing. A refusal arrives as a thrown {@link CaysoApiError} whose `code`
+     * is a `StandingAuthorisationRevocationRefusal` member, one of the gate's codes, or
+     * a seam code, and means nothing was written.
+     */
+    revokeStandingAuthorisation(req: StandingAuthorisationRevocationRequest): Promise<StandingAuthorisationRevoked>;
+    /**
+     * Bind a Node to the wallet the presenting Instance key is already bound to, under
+     * the owner's assertion (`bind-node`, CAY-0095). The key must have been bound to the
+     * caller's wallet by a standing authorisation it presented; this binds no key.
+     *
+     * Safe to repeat: binding a bound Node to the same wallet answers `bound` again and
+     * writes nothing. A refusal arrives as a thrown {@link CaysoApiError} whose `code` is
+     * a `NodeBindingRefusal` member, one of the gate's codes, or a seam code, and means
+     * nothing was bound.
+     */
+    bindNode(req: NodeBindingRequest): Promise<NodeBound>;
     getVersion(): Promise<CaysoVersion>;
 }
 /**

package/dist/client.js

@@ -231,6 +231,25 @@ function buildClient(options, internals) {
                 idempotencyKey: req.idempotencyKey,
             });
         },
+        async changeHandle() {
+            return requestJson({
+                method: ROUTES.handleChange.method,
+                path: ROUTES.handleChange.path,
+                // Safe to retry with no key: the charge is keyed by the change reference
+                // inside the assertion, so a repeat answers the charge already made, and each
+                // attempt mints a fresh assertion, so the single-use `jti` is never presented
+                // twice.
+                idempotent: true,
+            });
+        },
+        async readHandleChangeReceipt() {
+            return requestJson({
+                method: ROUTES.handleChangeReceipt.method,
+                path: ROUTES.handleChangeReceipt.path,
+                // A read: it moves nothing, so a retry is always safe.
+                idempotent: true,
+            });
+        },
         async getCitizenMarket() {
             return requestJson({
                 method: ROUTES.citizenMarket.method,
@@ -290,6 +309,24 @@ function buildClient(options, internals) {
                 body: req,
             });
         },
+        async revokeStandingAuthorisation(req) {
+            return requestJson({
+                method: ROUTES.revokeStandingAuthorisation.method,
+                path: ROUTES.revokeStandingAuthorisation.path,
+                // Safe to repeat: a revoked authorisation revoked again answers the same.
+                idempotent: true,
+                body: req,
+            });
+        },
+        async bindNode(req) {
+            return requestJson({
+                method: ROUTES.bindNode.method,
+                path: ROUTES.bindNode.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,