@percayso-community/cayso-contracts 0.23.0

package/dist/assertion.d.ts

@@ -0,0 +1,867 @@
+/**
+ * `assertion` — the shape of the credential Piper mints for a signed-in holder
+ * and Cayso verifies before it answers (CAY-0021), and the trust envelope that
+ * says who minted it and under which key (CAY-0030).
+ *
+ * This file is the *shape alone*. Nothing here reads, parses, verifies or
+ * expires a credential: verification is the `PercaysoIdVerifier` seam in slice
+ * 18 and the middleware is slice 19. This is the contract between two
+ * repositories and two people, written down before either side builds against
+ * it. An `AssertionClaims` value is 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 — not Piper's, not the admin app's, not a peer's (CLAUDE.md,
+ * Trust and authentication).
+ *
+ * ## An envelope is a HEADER and CLAIMS, and they are not the same thing
+ *
+ * {@link AssertionEnvelope} is a header ({@link AssertionHeader}) beside the
+ * claims ({@link AssertionClaims}), and the split is load-bearing rather than
+ * tidy.
+ *
+ * The header says *how to check this credential*: which algorithm it was signed
+ * with (`alg`) and which of the issuer's keys signed it (`kid`). The claims say
+ * *what the issuer asserts*: who the holder is, what was verified about them,
+ * what this credential may be used for. A verifier must read the header **before
+ * it can believe a single claim**, and it must read the header **without
+ * believing it** — the header is unauthenticated input that selects a check, not
+ * a statement to act on.
+ *
+ * Flattening `alg` and `kid` into the claims hides that ordering, and it invites
+ * the two failures CAY-0030 exists to close. If `alg` reads as a claim, somebody
+ * eventually *selects on it* — dispatching to the algorithm the credential names,
+ * which lets a caller name the algorithm their forgery is easiest under. If `kid`
+ * reads as a claim, somebody eventually treats it as a hint rather than a
+ * selector — trying every key until one verifies, which makes a revoked key as
+ * good as a live one. So the contract states the division here, in the type: the
+ * header is **read to choose a check**, the claims are **what the check
+ * establishes**.
+ *
+ * The obligations that follow are the verifier's, and they are stated so a
+ * consumer knows what it is being held to. `alg` is taken from the ISSUER'S
+ * REGISTRY ENTRY and the header's value is *checked against it*, never used to
+ * select a check. `kid` selects exactly ONE key, from that issuer's keys alone;
+ * an unknown `kid`, a `kid` belonging to a different issuer, and a revoked `kid`
+ * are each a refusal, and there is no fallback to a second key. Where the
+ * registry lives and what it contains is Cayso's own and is deliberately not on
+ * this surface.
+ *
+ * ## Lifetime is 60–120 seconds, single-use where the issuer can manage it
+ *
+ * These claims describe a *short-lived* credential. The band is **60 to 120
+ * seconds**, and it is single-use wherever the issuer can track that. This is
+ * the contract, stated here because it is the reason this slice exists as its
+ * own slice — not advice a consumer may weigh.
+ *
+ * Why so short: a long-lived credential that anybody holding it may present, and
+ * that moves money, is the admin-password objection wearing a different hat —
+ * "who has the admin password, select all records where this, into my wallet"
+ * (CAY-0008). Something you can copy once and replay for a month is that password
+ * again, however it was minted. The issuer's *own* sign-in sessions last 30 days
+ * (CAY-0008, and Piper's `identity` cookie), and this must emphatically **not** be
+ * one of those: an assertion is not a sign-in session handed across the boundary,
+ * it is a fresh, narrowly-scoped statement minted per request. The glossary says
+ * the same in one line — an assertion "never [carries] a password and never a
+ * Piper session" (CONTEXT.md).
+ *
+ * A note on where numbers live. CLAUDE.md keeps every *economic* figure —
+ * amounts, rates, tiers, schedules, thresholds — in the canon PRD and nowhere
+ * else, so that a number in two places cannot go stale. That rule governs the
+ * economy; the 60–120 second band, the clock constants below and the ceiling on
+ * `exp` are *security parameters of this credential*, and the briefs for these
+ * slices instruct they be recorded here **as the contract**. They are recorded
+ * here for that reason and cited to those briefs. No economic number appears
+ * anywhere in this file.
+ *
+ * ## The clock rules, and the direction skew is allowed to move in
+ *
+ * Three constants below state the whole of the timing contract:
+ * {@link MAX_ASSERTION_LIFETIME_SECONDS}, the furthest ahead of now an `exp` may
+ * sit before the credential is refused as over-long; {@link
+ * CLOCK_SKEW_TOLERANCE_SECONDS}, how far two honest clocks are assumed to
+ * disagree; and {@link MINIMUM_ASSERTION_USE_RETENTION_SECONDS}, derived from
+ * the two, which is the floor on how long a recorded use must be kept.
+ *
+ * **Skew tolerance may only ever refuse something, never admit something.** It
+ * is applied to `iat` — a credential issued further into the future than two
+ * honest clocks could disagree by is refused — and it is emphatically NOT applied
+ * to `exp`. Adding tolerance to `exp` would keep a credential alive past the
+ * moment its issuer said it died, which is to say it would lengthen a lifetime
+ * this contract exists to keep short. `exp` at or before now is expired, exactly,
+ * with no grace.
+ *
+ * ## `exp` and `iat` are SECONDS; every `Millis` on this surface is not
+ *
+ * The unit asymmetry is deliberate and it is the sharpest edge on this contract,
+ * so it is stated rather than left to be discovered. `exp`, `iat`,
+ * `recoveredAt` and `sessionAgeSeconds` are the **issuer's** fields and follow
+ * the issuer's convention: **seconds** since the Unix epoch (or, for
+ * `sessionAgeSeconds`, a duration in seconds). Every timestamp on the wallet and
+ * purchase contracts beside this one is `Millis` — milliseconds — and so is every
+ * clock in an implementation of this contract.
+ *
+ * The two do not meet implicitly anywhere. Reading an `exp` in seconds as if it
+ * were milliseconds is a credential that expires in the year 1970 — harmless; the
+ * reverse, reading a `Millis` as seconds, is a credential that expires fifty
+ * thousand years from now, which is the failure worth naming. A consumer crossing
+ * between them must do it through an explicit, named conversion, so that the
+ * crossing is visible at the point it happens.
+ *
+ * ## Rotation and revocation — the consumer's obligation
+ *
+ * The issuer's keys rotate, and this contract states what an issuer owes a
+ * verifier when they do. These are obligations on the party that mints, written
+ * here because they are the only half of CAY-0030 that is a consumer's business:
+ *
+ *   1. **A new key must be registered before it signs anything.** Cayso selects a
+ *      key by `kid` from a configured registry; a `kid` that arrives before the
+ *      registry knows it is an unknown key and is refused. There is no discovery,
+ *      no fetch-on-miss and no "try the others" — an unregistered key does not
+ *      become usable by being used.
+ *   2. **More than one key may be live at once, and that is how an overlap
+ *      works.** An issuer registers the new key, waits for the registration to
+ *      take effect, then starts signing with it, and only afterwards retires the
+ *      old one. Both are live in between; both verify; nothing is refused mid-way.
+ *      A rotation that skips the overlap refuses every credential minted between
+ *      the last old-key mint and the new key's registration.
+ *   3. **Revocation is immediate and independent of `exp`.** A revoked key stops
+ *      verifying the moment it is revoked, including for credentials minted
+ *      before the revocation whose `exp` has not yet passed. A short lifetime is
+ *      not a substitute for revocation: "it will expire in ninety seconds" is
+ *      ninety seconds of a key somebody else holds. The same is true one level up
+ *      — a revoked ISSUER's credentials stop verifying, whatever their `kid`.
+ *
+ * An issuer that cannot meet (1) cannot rotate without an outage, and that is the
+ * intended pressure: registration first is the only ordering under which a
+ * verifier never has to guess.
+ *
+ * ## `aud` must be checked, not merely present
+ *
+ * `aud` is the literal `'cayso'`, and a verifier must **check** it rather than
+ * observe that it is there. A credential minted for somebody else that merely
+ * *carries* an audience is a credential you accepted from the wrong recipient:
+ * audience binding only binds if the receiver refuses everything not addressed to
+ * it. The type pins the value; the check is slice 18's, and it is not optional.
+ *
+ * The same is true of `iss`, one level out. `aud` says who a credential was
+ * *for*; `iss` says who *made* it, and it is the field that decides which key may
+ * have signed it and which holders it may speak about. An `iss` a verifier merely
+ * records is an `iss` that binds nothing.
+ *
+ * ## `sub` is an issuer identity and must never be written to chain state
+ *
+ * `sub` is the holder's identity at the issuer (Percayso ID). It **must never
+ * reach chain state** (CAY-0006). On-chain accounts are pseudonymous, and the
+ * mapping from an issuer identity to a wallet lives in this repository's
+ * `holders` table — the Trust Network — and nowhere else. That mapping is the one
+ * thing in the system kept correctable, revocable and erasable, which is exactly
+ * what the ledger beside it is not (CONTEXT.md, Trust Network).
+ *
+ * The direction is one-way and that is the whole reason for the rule: you can
+ * always reveal a pseudonym later — publish the mapping, add a lookup — and you
+ * can never un-publish an identity once it has been committed to an append-only
+ * chain. Pseudonymity is the only choice that keeps the other one available
+ * (CAY-0006). So `sub` stops at the Trust Network; the `walletId` is the handle
+ * that travels onward.
+ *
+ * `sub` is also bound to `iss`, and the binding runs the other way from the one a
+ * reader expects: an issuer may only speak about the holders that are its own. A
+ * verifier holds each issuer's subject space and refuses a credential whose `sub`
+ * falls outside it, so an issuer cannot mint for another issuer's holder. Which
+ * space belongs to whom is configuration, and is not on this surface.
+ *
+ * ## Why `verificationMethod` is here, and why it is not noise
+ *
+ * `verificationMethod` is the field most easily mistaken for metadata, and it is
+ * the one that stops an unverified holder ending up with value. Piper's
+ * `PIPER_DEV_BYPASS` is on **unless** the environment holds the literal string
+ * `'false'`, and an identity marked verified that way keeps the method
+ * `'dev-bypass'` **permanently** (CAY-0021). So `verificationStatus === 'verified'`
+ * can be true of an identity that was checked by nothing at all, and a gate that
+ * asks only for "verified" inherits a check that checked nothing.
+ *
+ * That is why the method rides alongside the status. At any gate meaning
+ * "identity-verified", the code must require a method that is **explicitly not**
+ * the development bypass, rather than requiring "verified" and inheriting whatever
+ * that includes (CLAUDE.md, Trust and authentication). Where that gate is written
+ * is slices 18 and 24; *that it has to exist* is recorded here, on the field that
+ * makes it possible.
+ *
+ * ## The assurance profile version, and why it is required
+ *
+ * `verificationMethod` names HOW an identity was verified; it does not say what
+ * that method proves. What each method asserts, and which operations accept it,
+ * is the assurance profile in `assurance.ts` (CAY-0029) — and a profile that can
+ * change has to be versioned, or a claim minted last month silently comes to mean
+ * whatever the profile means today.
+ *
+ * So `assuranceProfileVersion` rides on every claim: the issuer stamps the profile
+ * it minted under, and a verifier refuses a version it does not recognise rather
+ * than reading the method as if it meant what this version means. It is REQUIRED,
+ * not optional — an unstamped claim is one whose method cannot be interpreted at
+ * all, and defaulting it to "presumably ours" is the assumption the field exists
+ * to remove.
+ *
+ * ## Assurance and scope answer different questions
+ *
+ * `assuranceProfileVersion`, `verificationStatus` and `verificationMethod` answer
+ * *how well do we know who this is*. {@link AssertionClaims.scope} answers *what
+ * did the issuer mint this credential to do*. Both must be satisfied and neither
+ * substitutes for the other: a document-verified identity presenting a credential
+ * scoped only to a wallet read may not authorise a purchase, and a credential
+ * scoped to a purchase minted for an unverified identity may not either.
+ *
+ * ## Personhood is a THIRD question, and it is not assurance
+ *
+ * `subjectPersonhood` answers neither *how well do we know who this is* nor *what
+ * was this minted to do*. It answers **is the subject one human being** — and
+ * nothing else on this surface did. It was added because an operator read's audit
+ * row promised to name a person while the credential behind it could perfectly
+ * well front a rota, a support tool or a reporting job (CAY-0041, CAY-0069), and a
+ * gate cannot refuse a fact nobody states.
+ *
+ * It is OPTIONAL and its absence is a refusal wherever a person is required, never
+ * a permission. The reasoning is on the field; read it there before assuming
+ * either half.
+ *
+ * ## The organisation a citizen acts for is a FOURTH question
+ *
+ * `organisationAuthority` answers none of the three above. It answers **which one
+ * Organisation this citizen may act for in this operation**, and it exists because
+ * an Organisation Wallet is keyed by the Organisation ID Percayso ID holds and
+ * attests, never by a Piper Instance (CAY-0059). A downloadable Instance is a
+ * public client and an identifier the caller supplies is a request rather than
+ * evidence (CAY-0057), so an organisation provisioning route reading an identifier
+ * from a path or a body would be a wallet-creation oracle: anybody who can name a
+ * UUID could bring an Organisation Wallet into being, or select one.
+ *
+ * It is SINGULAR and OPERATION-BOUND, it sits beside `sub` rather than replacing
+ * it, and it is emphatically not `mandateFor`. All four points are argued on the
+ * field; read them there.
+ *
+ * ## Which founder wallet a founder claims is a FIFTH question
+ *
+ * `founderClaimReference` answers **which founder wallet this citizen is claiming**
+ * (CAY-0081). It follows `organisationAuthority`'s pattern: one value, minted by
+ * the issuer for one operation, read by that operation alone. It goes one step
+ * further than that claim, because it is half of a claim on a founder's
+ * allocation. The reference travels on a `'claim-founder-wallet'` credential and
+ * on nothing else, and that credential does not verify without it. Both halves
+ * of that rule are argued on the field.
+ *
+ * ## The two reserved fields
+ *
+ * `recoveredAt` and `sessionAgeSeconds` are declared and depended on by nothing.
+ * They are here so the shape is fixed now, while it is free: a recovery is a
+ * second, shorter path to the signing key (CAY-0008), and a hold on the money
+ * path after one may eventually want to read them — but retrofitting a hold onto
+ * a live account is a migration over people's money, so the room is left in the
+ * shape today rather than added under pressure. Nothing in Phase A may branch on
+ * them; this file names no recovery window and suggests no value for either,
+ * because that would be defaulting a policy call in code.
+ */
+/**
+ * An act a holder performs against this contract surface, named so that a policy
+ * can be written about it.
+ *
+ * ONE VOCABULARY, NOT TWO. These same keys are what an operation's acceptance
+ * policy is written against (`assurance.ts`, CAY-0029) and what an assertion's
+ * {@link AssertionClaims.scope} lists (CAY-0030). They are declared here, in the
+ * file that declares the claims, precisely so there is one list rather than a
+ * scope vocabulary drifting away from a policy vocabulary; `assurance.ts`
+ * re-exports this type rather than restating it, the same way it consumes
+ * {@link VerificationMethod} from here.
+ *
+ * These are OPERATIONS, not routes. Every route on the contract surface that
+ * carries an identity maps to one of these — `assurance.ts`'s
+ * `OPERATION_FOR_ROUTE` is that correspondence, and it is a compile error to add
+ * a route without stating which operation it exercises. The correspondence is not
+ * one-to-one in the other direction: an operation may be classified before it has
+ * a route, which is how `'provision-citizenship'` was decided in CAY-0029 and
+ * read, unchanged, by the slice that finally served it (CAY-0031).
+ *
+ * `'provision-citizenship'` and `'read-own-citizenship'` are two operations
+ * because they are two acts. Provisioning creates a wallet and grants cents;
+ * asking whether it has happened creates nothing at all. Naming them once and
+ * gating them alike would make the question as expensive to ask as the answer is
+ * to produce, and would put the write's assurance bar in front of a read of one's
+ * own record.
+ *
+ * `'cancel-purchase'` is a member of THIS vocabulary rather than a fourth
+ * vocabulary of its own (CAY-0032). Cancelling is an act a holder performs against
+ * this surface, so the question "which scope authorises this" already had an
+ * answer here and reaching for a new kind of answer would have given the gate two
+ * things to check instead of one. It is separate from `'authorise-purchase'`
+ * because the two are separate acts: a credential minted to let a confirmation
+ * page finish a purchase should not, by that fact alone, be able to terminate one.
+ *
+ * `'provision-organisation'` is its own operation beside `'provision-citizenship'`
+ * rather than a second use of it (CAY-0059). The two bind different holders from
+ * different facts: citizenship binds the authenticated `sub`, and organisation
+ * provisioning binds the one Organisation ID the issuer attested on
+ * {@link AssertionClaims.organisationAuthority}. Scope is checked per operation at
+ * the gate, so one key covering both acts would let a credential minted to
+ * provision its holder's own citizenship bring an Organisation Wallet into being.
+ *
+ * `'claim-founder-wallet'` is its own operation beside `'provision-citizenship'`
+ * for the same reason, and a stronger one (CAY-0081). Provisioning binds a
+ * wallet it creates and mints a sign-up grant into it. The founder claim binds a
+ * founder wallet that already exists, and a claimed founder must never receive a
+ * sign-up grant by any route. One key covering both would let a credential minted
+ * to claim provision, and the reverse. It is served at
+ * `ROUTES.citizenshipFounderClaim`, and it binds the wallet named by
+ * {@link AssertionClaims.founderClaimReference} and no other.
+ *
+ * `'make-commercial-payment'` is an Organisation paying a Citizen (CAY-0079). It
+ * is its own operation rather than a second use of `'authorise-purchase'`, which
+ * brings sterling in and moves nothing out of an organisation. A commercial payment
+ * moves value out of an organisation to an individual, so a credential minted to
+ * buy Cayso must not thereby be able to pay somebody. It was classified before it
+ * was served, as `'provision-citizenship'` was, and it is served at
+ * `ROUTES.commercialPayment`.
+ *
+ * `'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
+ * thereby place one, and selling to the Treasury is not a quote at all, since the
+ * Treasury rests no quote in the book (Open decision G). None of them is a second
+ * use of `'make-commercial-payment'` either, because an organisation takes no part
+ * in the citizen market. They were classified before they were served, and each is
+ * served at one route: `ROUTES.placeQuote`, `ROUTES.withdrawQuote` and
+ * `ROUTES.requestBuyBack`.
+ *
+ * `'read-citizen-market'` is reading the book (CAY-0080 §1.4). It is its own
+ * operation because it is a read beside two writes: a credential minted to look at
+ * the book must not thereby place or withdraw a quote. It is served at
+ * `ROUTES.citizenMarket`.
+ *
+ * `'read-marketplace-receipt'` is the marketplace status read (CAY-0083 §2): Piper,
+ * under the buyer's assertion, asking what an idempotency key landed after the
+ * answer to a sale or refund was lost. It is its own operation because it is a read
+ * beside the money-grade settlement it reports on, and a credential minted to ask
+ * what happened must not thereby be able to make something happen. It is the
+ * first of CAY-0083 §3's three keys to be published. It is classified before it is
+ * served, and no route serves it yet.
+ *
+ * `'settle-marketplace-order'` and `'settle-marketplace-refund'` are the two
+ * money-grade marketplace operations whose outcome that read reports (CAY-0083 §3):
+ * Piper presenting Store Platform's signed order, and Store Platform's signed refund
+ * decision, each under the buyer's assertion. They are two operations because they
+ * check two authorities. A sale moves the buyer's cents on the buyer's say; a refund
+ * moves a publisher's cents on Store Platform's decision, with the buyer as payee.
+ * A credential minted to buy must not thereby be able to draw back from a
+ * publisher, and one operation with a mode flag would blur which authority is
+ * checked. Neither is a second use of `'authorise-purchase'`, which brings sterling
+ * in, or of `'make-commercial-payment'`, which is organisation-to-Citizen only.
+ * Both are classified before they are served, and no route serves either yet.
+ */
+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' | 'place-quote' | 'withdraw-quote' | 'request-buy-back' | 'read-citizen-market' | 'read-marketplace-receipt' | 'settle-marketplace-order' | 'settle-marketplace-refund';
+/**
+ * An operation key belonging to a deployment's OWN surfaces rather than to this
+ * contract — operator work, above all. Deliberately not enumerated: this package
+ * is published and carries the Piper-facing surface only (CAY-0026), and naming
+ * an internal vocabulary here would publish a set of keys no consumer of this
+ * contract may ever present. Where the closed set is kept instead is stated on
+ * {@link ScopeKey}.
+ */
+export type InternalOperation = string;
+/**
+ * A key an assertion's {@link AssertionClaims.scope} may carry: one of this
+ * contract's {@link ContractOperation}s, or one of the deployment's own
+ * {@link InternalOperation}s.
+ *
+ * Two vocabularies meet in one array and only one of them is published. A
+ * consumer needs every {@link ContractOperation} named here in order to mint a
+ * credential this deployment will accept. The internal half it does not need and
+ * must not have.
+ *
+ * So this type is open where {@link ContractOperation} is closed — and the closed
+ * set MOVES rather than disappearing. It is kept in two places that know what this
+ * one cannot:
+ *
+ *   - the VERIFIER is told the deployment's own vocabulary and refuses a scope key
+ *     that is in neither list, so an unrecognised key is malformed rather than
+ *     merely unauthorised. A deployment that declares no internal vocabulary
+ *     admits none — empty is the default and empty is not permissive;
+ *   - the SERVICE declares its internal keys as a closed union of its own, so a
+ *     route cannot be classified against an operation that does not exist.
+ *
+ * An empty scope still authorises nothing, here as everywhere else.
+ */
+export type ScopeKey = ContractOperation | InternalOperation;
+/**
+ * The furthest ahead of now, in **seconds**, a verified assertion's `exp` may
+ * sit before it is refused as over-long.
+ *
+ * It is a ceiling, not the lifetime: the lifetime band is 60–120 seconds (see the
+ * file docblock) and this sits comfortably above it, so an issuer working inside
+ * the band is never near it. It exists because the issuer is ANOTHER TEAM and
+ * this is a check on somebody else's output: a verifier that trusts an `exp`
+ * because the issuer is friendly forbids nothing, and a correctly-signed
+ * credential whose `exp` sits a week out is the long-lived credential this
+ * contract exists to refuse (CAY-0008).
+ *
+ * It lives on the contract rather than inside one service because two things read
+ * it — the verifier that refuses an over-long credential, and the replay
+ * retention floor derived from it below — and because a consumer is entitled to
+ * know the ceiling its credentials are measured against.
+ */
+export declare const MAX_ASSERTION_LIFETIME_SECONDS = 300;
+/**
+ * How far apart, in **seconds**, two honest clocks are assumed to be able to
+ * drift.
+ *
+ * It is applied in ONE DIRECTION ONLY: to refuse a credential whose `iat` sits
+ * further into the future than this, which no honest issuer's clock explains. It
+ * is NOT added to `exp`. Tolerance that extends a credential's life is tolerance
+ * that defeats the short lifetime, so the rule is stated as a direction rather
+ * than as a number a reader might apply symmetrically: **skew may refuse; it may
+ * never admit.** `exp` at or before now is expired, exactly.
+ */
+export declare const CLOCK_SKEW_TOLERANCE_SECONDS = 30;
+/**
+ * The floor, in **seconds**, on how long a recorded assertion use must be kept so
+ * that replay is actually refused (CAY-0030).
+ *
+ * DERIVED, NEVER WRITTEN DOWN AS A NUMBER. A retention window shorter than the
+ * longest life a credential can have plus the clock disagreement around it is a
+ * window a replay simply waits out: the record of the first use is discarded
+ * while the credential itself is still within `exp`, and the second presentation
+ * looks like a first. Deriving the floor from the two constants above means the
+ * relationship cannot go stale when either moves, and means there is no second
+ * copy of it to disagree with this one.
+ *
+ * It is a FLOOR, not the window. A deployment may keep uses longer; it may not
+ * keep them for less, and an implementation must refuse a shorter configured
+ * window **in code** rather than note the requirement in a comment.
+ */
+export declare const MINIMUM_ASSERTION_USE_RETENTION_SECONDS: number;
+/**
+ * How an identity came to be verified. **What each member asserts is stated in
+ * `assurance.ts`'s `EVIDENCE_STATEMENTS`** (CAY-0029) — this union names the
+ * methods; that table says what evidence each one stands for, and which
+ * operations accept it.
+ *
+ * Not every method is acceptable at a money gate: `'dev-bypass'` is Piper's
+ * development shortcut, it asserts nothing at all, and it is explicitly *not*
+ * acceptable where "identity-verified" is meant (CAY-0021). It appears in no
+ * operation's accepted set.
+ */
+export type VerificationMethod = 'dev-bypass' | 'document' | 'document-and-biometric';
+/** Whether the issuer regards this identity as verified. Says nothing, on its own, about *how*. */
+export type VerificationStatus = 'unverified' | 'verified';
+/**
+ * Whether the credential's subject is ONE HUMAN BEING, or a credential standing
+ * in front of more than one of them — or of none (CAY-0069, amending CAY-0041 and
+ * CAY-0064).
+ *
+ * This is the fact CAY-0041 §3's Option B needed and the envelope did not have.
+ * `sub` is an opaque string, and nothing beside it said whether it named a person
+ * or a rota, a support tool or a reporting job. An operator read's audit row
+ * therefore answered "who looked at this wallet" with whatever the deployment
+ * happened to be configured with, and no gate could tell the two apart.
+ *
+ * ## It is a union of two named cases, not a boolean
+ *
+ * `subjectIsAPerson: boolean` would have made the negative case nameless — one
+ * value standing for a rota, a service credential and an automated job alike —
+ * and would have to be re-litigated the first time a third case arrives (a shared
+ * credential that names the human it was presented for is Option C, and it is not
+ * foreclosed). Two named cases carry their meaning on the wire, which is the same
+ * reason `AuditedVerificationMethod` is a union and the acting party on a money
+ * row is one (CAY-0054).
+ *
+ * ## What each case asserts — and it is an ISSUER's statement, not ours
+ *
+ *   - `'natural-person'` — this credential was minted for one human being and is
+ *     presented by them. It is the only value an operator route accepts.
+ *   - `'shared-credential'` — it was not: it fronts several people, or nobody at
+ *     all. A support tool minting on somebody's behalf, an on-call rota's shared
+ *     identity, a reporting job. Well-formed, and refused wherever a person is
+ *     required.
+ *
+ * Cayso cannot check either one, and this contract does not pretend otherwise:
+ * the issuer asserts it, exactly as the issuer asserts `verificationMethod`, and
+ * an issuer's own half of the binding is a stated limit rather than something a
+ * verifier can audit (CAY-0030 §8). Under a verifier that checks no signature it
+ * is as choosable as `sub` is — see `AssertionClaims.subjectPersonhood`.
+ *
+ * ## Why it is NOT part of the assurance profile
+ *
+ * `assurance.ts`'s `VerificationEvidence` describes IDENTITY PROOFING — a document
+ * examined, a biometric captured, a comparison recorded. This is a different kind
+ * of fact and is orthogonal to all three: a shared credential can be perfectly
+ * document-verified (that is the residual CAY-0064 §5 named), and one human being
+ * can be verified by nothing at all. Folding it into the evidence would make it
+ * versioned by the assurance profile, so a new personhood case would become a
+ * re-interpretation of what every method proves — which it is not — and it would
+ * have to be answered by `evidenceSupports` and `methodForEvidence`, where no
+ * amount of personhood makes `'document'` supportable. So it rides BESIDE the
+ * assurance fields on the claims, where `verificationStatus` and
+ * `verificationMethod` are, and the profile is left describing proofing alone.
+ */
+export type SubjectPersonhood = 'natural-person' | 'shared-credential';
+/**
+ * The header of a minted assertion: how to check it, read BEFORE anything in it
+ * is believed and never believed itself (CAY-0030).
+ *
+ * Both fields are unauthenticated at the moment they are read — they are, after
+ * all, part of the thing being checked. That is exactly why they are separated
+ * from the claims: a header field is an input to selecting a check, and a claim
+ * is an output of passing one.
+ */
+export interface AssertionHeader {
+    /**
+     * The signature algorithm the issuer used.
+     *
+     * Typed `string`, deliberately NOT a closed union of the algorithms this
+     * deployment permits — the same reasoning
+     * {@link AssertionClaims.assuranceProfileVersion} is typed `string` for. A
+     * header naming an algorithm we do not permit must be REPRESENTABLE in order to
+     * be refused, and a type admitting only permitted values cannot describe the
+     * header a verifier most needs to reject.
+     *
+     * A VALUE TO CHECK, NEVER A VALUE TO SELECT ON. The permitted algorithm is
+     * fixed by the issuer's registry entry; this field is compared against it and a
+     * mismatch is a refusal. A verifier that dispatched on this field would let the
+     * presenter of a credential choose the algorithm their forgery is easiest
+     * under, which is the whole of the attack.
+     */
+    readonly alg: string;
+    /**
+     * Which of the issuer's keys signed this assertion.
+     *
+     * A SELECTOR, NOT A HINT. Exactly one key is chosen — from the keys registered
+     * to the `iss` on the claims, never from every key the deployment knows — and
+     * if that key is unknown, belongs to another issuer, or has been revoked, the
+     * credential is refused. There is no second attempt: a verifier that tries the
+     * remaining keys after one fails has made revocation meaningless, because a
+     * revoked key's credentials keep verifying under whichever key is tried next.
+     */
+    readonly kid: string;
+}
+/**
+ * A minted assertion as a whole: the header that says how to check it, and the
+ * claims it carries (CAY-0030).
+ *
+ * The two are separate types and are not merged, for the reason the file docblock
+ * gives at length: a verifier reads the header to CHOOSE a check and reads the
+ * claims as what that check ESTABLISHED. A single flat object loses that ordering
+ * and is how `alg` becomes something to dispatch on and `kid` becomes a hint.
+ *
+ * This contract does not fix the wire *encoding* — how a header and its claims are
+ * serialised and signed together is the issuer's and the verifier's business, and
+ * naming a serialisation here would pin a cryptographic dependency into a
+ * types-only published package. What it fixes is that a credential HAS these two
+ * parts and which fields belong to each.
+ */
+export interface AssertionEnvelope {
+    /** How to check this credential. Read first, believed never. */
+    readonly header: AssertionHeader;
+    /** What the issuer asserts, established only once the header's check has passed. */
+    readonly claims: AssertionClaims;
+}
+/**
+ * The claims carried by a minted assertion (CAY-0021, CAY-0030). This is the
+ * shape a verifier checks; it is not a value a consumer constructs and trusts.
+ */
+export interface AssertionClaims {
+    /**
+     * Who minted this assertion.
+     *
+     * It is the field every other trust decision hangs off: which keys may have
+     * signed the credential, which algorithm those keys use, which holders this
+     * issuer may speak for, and which economic universe it serves. An `iss` that is
+     * not in a verifier's configured registry is refused, and an empty registry
+     * therefore refuses everything — the fail-closed posture every adapter in this
+     * tree takes (CLAUDE.md, Trust and authentication). Recognising an issuer is a
+     * deliberate act of configuration, never something an issuer achieves by
+     * presenting a credential.
+     *
+     * Typed `string` rather than a literal for the reason the assurance profile
+     * version is: an unrecognised issuer must be representable in order to be
+     * refused.
+     */
+    readonly iss: string;
+    /**
+     * This assertion's unique identity, minted fresh by the issuer for each one.
+     *
+     * It is what makes a second presentation of the SAME credential detectable: a
+     * verifier records the pair (`iss`, `jti`) on the first successful verification
+     * and refuses any later presentation carrying it. The pair, not `jti` alone —
+     * two issuers may legitimately mint the same `jti` and neither is at fault, so
+     * a store keyed on `jti` alone would have one issuer's credential lock out
+     * another's.
+     *
+     * An issuer must not reuse one, and must not derive one from anything
+     * predictable: it is the issuer's obligation that two assertions never carry the
+     * same `jti`, and a verifier that sees a repeat treats it as a replay rather
+     * than investigating whose fault it was.
+     */
+    readonly jti: string;
+    /**
+     * The holder's identity id at the issuer. **NEVER reaches the chain** — it
+     * stops at the `holders` mapping in this repository (CAY-0006). Bound to
+     * {@link iss}: an issuer may only assert subjects in its own space, so one
+     * issuer cannot mint for another's holder.
+     */
+    readonly sub: string;
+    /** The intended recipient. Must be exactly `'cayso'`, and must be *checked*, not merely present. */
+    readonly aud: 'cayso';
+    /**
+     * What this assertion may be used for: the operations the issuer minted it to
+     * perform, named as {@link ScopeKey}s — this contract's own
+     * {@link ContractOperation}s, and any operation key the deployment declares for
+     * a surface that is not Piper-facing.
+     *
+     * **AN EMPTY SCOPE IS ACCEPTED FOR NOTHING.** `[]` does not mean "unrestricted"
+     * and it does not mean "the default"; it means the issuer authorised no
+     * operation, and every gated operation refuses it. That is the fail-closed
+     * reading and it is the only safe one: the alternative — an absent or empty
+     * scope meaning "everything" — turns the one field that narrows a credential
+     * into the one field whose omission widens it.
+     *
+     * It is REQUIRED and not optional, for the same reason. An optional scope has a
+     * missing case, and every missing case is eventually read as permission. A
+     * credential that authorises nothing is a well-formed credential that authorises
+     * nothing, and it is representable so that it can be refused.
+     *
+     * Scope is not assurance. It says what the credential is FOR; the assurance
+     * profile says how well the identity behind it is known. An operation needs
+     * both, and neither stands in for the other.
+     */
+    readonly scope: readonly ScopeKey[];
+    /**
+     * Expiry, in **seconds** since the Unix epoch. Short — 60–120 seconds; see the
+     * file docblock. This is seconds, not `Millis`: the other timestamps on this
+     * contract surface (`cayso.wallet`, `cayso.purchase`) are `Millis`, but `exp`
+     * and `iat` are the *issuer's* fields and follow the issuer's convention.
+     * Reading an `exp` in seconds as if it were milliseconds is a credential that
+     * never expires — so the unit is stated rather than assumed.
+     *
+     * At or before now is expired, with NO skew grace added (see
+     * {@link CLOCK_SKEW_TOLERANCE_SECONDS}), and further ahead than
+     * {@link MAX_ASSERTION_LIFETIME_SECONDS} is refused as over-long.
+     */
+    readonly exp: number;
+    /**
+     * Issued-at, in **seconds** since the Unix epoch — the issuer's convention, not
+     * `Millis`. See `exp`. An `iat` further ahead of now than
+     * {@link CLOCK_SKEW_TOLERANCE_SECONDS} is refused: that is the one place skew
+     * is read, and it is read to refuse.
+     */
+    readonly iat: number;
+    /** Whether the issuer regards this identity as verified. Insufficient alone — read it with `verificationMethod`. */
+    readonly verificationStatus: VerificationStatus;
+    /**
+     * How the identity was verified, or `null` when it was not. Nullable rather
+     * than optional: an unverified identity *has* no method, and the field is
+     * always present to carry that `null`. A money gate must require a method that
+     * is explicitly not `'dev-bypass'` (CAY-0021).
+     */
+    readonly verificationMethod: VerificationMethod | null;
+    /**
+     * The assurance profile this claim was minted under — `ASSURANCE_PROFILE_VERSION`
+     * for a claim minted against the current profile (CAY-0029).
+     *
+     * Typed `string`, deliberately NOT the literal: a claim carrying a version this
+     * deployment does not recognise must be REPRESENTABLE in order to be refused,
+     * and a type that only admits the current version cannot describe the claim a
+     * verifier most needs to reject. The refusal is
+     * `assessAssurance`'s, and its reason is a closed union member.
+     */
+    readonly assuranceProfileVersion: string;
+    /**
+     * Whether this credential's subject is one human being
+     * ({@link SubjectPersonhood}). OPTIONAL on the wire, and its absence is a
+     * refusal wherever a person is required — never a permission (CAY-0069).
+     *
+     * ## Why optional, and why that is not a default
+     *
+     * The dangerous shape would be an optional claim read as "yes, a person" when
+     * it is missing, which is worse than no claim at all: it would put a schema
+     * behind a guess. Nothing does that. What absence means is exactly **the issuer
+     * has not said**, and a consumer of this contract is told the consequence
+     * plainly — an operator route refuses a credential that does not carry
+     * `'natural-person'`, absence included, and nothing anywhere derives personhood
+     * from `sub`, from a naming convention, or from the verification method.
+     *
+     * It is optional rather than required because this deployment cannot make a
+     * claim on an issuer's behalf, and the decision that introduced it is scoped to
+     * OPERATOR routes (CAY-0069). A required claim would refuse every citizen
+     * credential minted against an issuer that has not yet been asked to assert it —
+     * a change to gates the decision deliberately does not touch. So the wire stays
+     * open, the gate that needs the fact refuses without it, and the day the
+     * programme wants personhood required of every credential it is a further
+     * decision rather than a field already forced.
+     *
+     * The comparison with `scope` is worth making, because `scope` IS required for a
+     * reason that does not apply here. An absent scope had to be refused because the
+     * only alternative reading — "unrestricted" — widens a credential. An absent
+     * personhood claim widens nothing: it narrows, everywhere it is read.
+     *
+     * ## It is as trustworthy as the verifier, and no more
+     *
+     * Under a verifier that checks no signature this claim is attacker-choosable
+     * exactly as `sub` is — a caller that can mint an envelope can mint one asserting
+     * `'natural-person'`. Declaring it makes the promise STRUCTURAL; a real signature
+     * check is what makes it TRUSTWORTHY, and the two are separate pieces of work.
+     */
+    readonly subjectPersonhood?: SubjectPersonhood;
+    /**
+     * The ONE Organisation ID for which the issuer says this citizen may perform
+     * THIS operation — the organisation-authority claim (CAY-0059 §3). OPTIONAL on
+     * the wire, and its absence provisions nothing.
+     *
+     * ## It is a second fact beside `sub`, and it replaces nothing
+     *
+     * `sub` stays what it has always been: the citizen Percayso ID authenticated
+     * directly. This says which Organisation that citizen is acting for. Collapsing
+     * the two — putting the Organisation ID in `sub` on organisation-scoped calls —
+     * was considered and rejected on the pillar owner's correction: the acting
+     * citizen and the organisation they act for are two facts, and one of them is
+     * the fact the audit trail and the acting party depend on (CAY-0054).
+     *
+     * ## SINGULAR and OPERATION-BOUND, never a list
+     *
+     * One Organisation ID, for one operation, minted for that operation. It is
+     * deliberately NOT the set of every Organisation the citizen is associated
+     * with: a list is a menu, and a credential carrying a menu lets whatever holds
+     * it choose from the menu. Piper may ASK Percayso ID for an assertion concerning
+     * a selected Organisation; Percayso ID verifies the relationship from its own
+     * records and mints the one value. Piper's submitted value is a request and
+     * never evidence (CAY-0057).
+     *
+     * ## THIS IS NOT `mandateFor`, AND THE TWO MUST NOT BE OVERLOADED
+     *
+     * CAY-0059 §7 is explicit, and the confusion is the mistake this claim most
+     * invites. {@link mandateFor} resolves Organisation **Wallet** IDs and is about
+     * SPENDING AUTHORITY through the existing mandate and allowance model
+     * (CAY-0024) — a wallet that already exists, and a limit already granted over
+     * it. This claim is about ESTABLISHING OR RESOLVING THE HOLDER, at a moment when
+     * the wallet does not exist yet and so cannot be named. A provisioning call has
+     * no wallet id to carry, which is the whole reason a second claim was needed
+     * rather than a second reading of the first. Nothing reads one where the other
+     * is meant, and a change that made either stand in for the other would undo
+     * CAY-0059 §7 in a line.
+     *
+     * ## Why the value is a plain `string` here
+     *
+     * The same reason `sub` is, and the same reason `Cents` is not branded
+     * (`./money`): this is the WIRE, JSON carries no brands, and a published
+     * Apache-2.0 type a consumer cannot build from a string it holds is a
+     * distinction that consumer cannot observe. The type that cannot express the
+     * violation — an Instance ID standing where an Organisation ID belongs (CAY-0059
+     * §5) — lives on the write path in `apps/api`, where the holder key is actually
+     * formed, exactly as the unforgeable money type lives beside the table rather
+     * than on the wire.
+     *
+     * ## It is as trustworthy as the verifier, and no more
+     *
+     * Under a verifier that checks no signature this claim is attacker-choosable
+     * exactly as `sub` is. Declaring it makes the promise STRUCTURAL — there is no
+     * path from a path, a body or a query to the holder key, so the wallet-creation
+     * oracle CAY-0057 names does not exist; a real signature check is what makes it
+     * TRUSTWORTHY, and the two are separate pieces of work.
+     */
+    readonly organisationAuthority?: string;
+    /**
+     * The founder claim reference: the opaque value naming the ONE founder wallet
+     * the issuer says this citizen may claim (CAY-0081, open decision 3). OPTIONAL
+     * on the wire, and read by `'claim-founder-wallet'` and by no other operation.
+     *
+     * ## It travels with its operation, in both directions
+     *
+     * A credential whose `scope` carries `'claim-founder-wallet'` must carry this
+     * claim, and a credential that carries this claim must be scoped to
+     * `'claim-founder-wallet'`. A verifier refuses either half missing as a
+     * malformed credential, before any gate reads it:
+     *
+     *   - **scoped to claim, with no reference.** The credential names an act it
+     *     cannot perform, because the founder claim takes the wallet from here and
+     *     from nowhere else. Refusing it at the verifier means no route can ever
+     *     be handed a founder claim credential with the reference missing and have
+     *     to decide what that means.
+     *   - **a reference, not scoped to claim.** The reference is half of a claim.
+     *     Identity Platform holds nominated person → reference, and Cayso holds
+     *     reference → wallet. A credential carrying it to any other operation puts
+     *     that half in front of a route with no business reading it, so the
+     *     credential is refused rather than the claim ignored.
+     *
+     * ## It is carried here and never in a request
+     *
+     * The reference is inside the signed assertion because a reference in a path,
+     * a body or a query would be a caller's claim about which allocation is theirs
+     * (CAY-0021). Piper may ask Percayso ID for a founder claim credential.
+     * Percayso ID decides from its own nomination record which reference, if any,
+     * this citizen is asserted for, and mints that one value. The founder claim
+     * route takes no field that names a Citizen, a wallet or an amount.
+     *
+     * ## What it is not
+     *
+     * It is NOT a wallet id. The wallet id is the operator-facing handle and never
+     * appears in an assertion, so the nomination list cannot become a directory of
+     * person → wallet. It is NOT derived from a Percayso identity. It carries no
+     * `sub`, no hash of one, no email and no name, and it is drawn from nothing by
+     * the Board's preparer. The founder schedule's own shape rule is the database's
+     * and is not restated here. This contract asks for a non-empty string and says
+     * nothing more about its shape.
+     *
+     * ## Why the value is a plain `string` here
+     *
+     * For the reason {@link 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.
+     *
+     * ## It is as trustworthy as the verifier, and no more
+     *
+     * Under a verifier that checks no signature this claim is attacker-choosable
+     * exactly as `sub` is. Declaring it makes the promise STRUCTURAL. A real
+     * signature check is what makes it TRUSTWORTHY, and the two are separate pieces
+     * of work.
+     */
+    readonly founderClaimReference?: 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
+     * this repository gives a wallet, and the only handle an operator surface
+     * 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.
+     *
+     * ## THIS IS NOT THE ORGANISATION-AUTHORITY CLAIM, AND THE TWO MUST NOT BE
+     * OVERLOADED
+     *
+     * {@link organisationAuthority} carries ONE Organisation ID and is about
+     * ESTABLISHING OR RESOLVING THE HOLDER. This claim is about SPENDING AUTHORITY,
+     * and it resolves through the existing wallet-based mandate and allowance model
+     * (CAY-0024) — a wallet that already exists, and a limit already granted over
+     * it. They cannot be one claim, and CAY-0059 §7 says so directly: at
+     * provisioning time the wallet does not yet exist, so a provisioning call has no
+     * wallet id to put here, and a claim about establishing a holder cannot be a
+     * claim about spending against a wallet that is already there. Reading one where
+     * the other is meant is the confusion §7 was written to prevent — and the
+     * confusion an earlier wording of this very docblock produced, by describing the
+     * field as a list of Instance ids (#208).
+     *
+     * The register of who may act for an organisation is Percayso ID's, not this
+     * economy's (CAY-0068). What arrives here is the issuer's attestation, accepted
+     * under a stated acceptance policy and never checked against a record in this
+     * tree.
+     *
+     * Declaring it sets no Signatory / Authorised-User threshold (a canon figure, read
+     * from configuration). The commercial payment's mandate route reads it to decide
+     * whether the caller may pay from the wallet they name (CAY-0079 §1), and nothing
+     * reads it as consent to anything else.
+     */
+    readonly mandateFor?: readonly string[];
+    /**
+     * RESERVED, declared and not yet depended on. When a key or passkey was last
+     * recovered, in seconds since the Unix epoch. Nothing in Phase A may branch on
+     * it (CAY-0008).
+     */
+    readonly recoveredAt?: number;
+    /**
+     * RESERVED, declared and not yet depended on. Age of the issuer's own sign-in
+     * session, in seconds. Nothing in Phase A may branch on it (CAY-0008).
+     */
+    readonly sessionAgeSeconds?: number;
+}