@percayso-community/cayso-contracts 0.23.0

package/dist/assurance.js

@@ -0,0 +1,551 @@
+/*
+ * Copyright 2026 Percayso Community
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { ROUTES } from './routes.js';
+// --- The profile's version ---------------------------------------------------
+/**
+ * The version of the assurance profile this deployment speaks — the one an issuer
+ * stamps on a claim it mints, as `AssertionClaims.assuranceProfileVersion`.
+ *
+ * It names the standard as well as the version, because the standard is Cayso's
+ * own (see the file docblock) and a bare `1` would not say whose. Adopting an
+ * external scheme later, or changing what any method asserts, is a NEW version
+ * with a new identifier — never a redefinition of this one. Redefining a version
+ * in place is how a claim minted last month silently comes to mean something else.
+ *
+ * It is deliberately NOT the contract version: the contract version describes the
+ * wire surface and moves when a type changes, while this moves when the MEANING of
+ * evidence changes. Two clocks, two numbers, for the same reason the contract
+ * version is not the schema version (CONTEXT.md, Contract version).
+ */
+export const ASSURANCE_PROFILE_VERSION = 'cayso-assurance-1';
+/**
+ * Every assurance profile version this deployment recognises. A claim carrying
+ * anything else is refused ({@link assessAssurance}) rather than read as if it
+ * meant what this version means — fail closed, the posture every adapter in this
+ * tree takes (CLAUDE.md, Trust and authentication).
+ *
+ * A future version that is genuinely compatible is added here deliberately. It
+ * contains {@link ASSURANCE_PROFILE_VERSION} by construction: a deployment always
+ * recognises the profile it speaks.
+ */
+export const RECOGNISED_ASSURANCE_PROFILE_VERSIONS = [ASSURANCE_PROFILE_VERSION];
+/**
+ * What each method asserts. These statements are the contract: a consumer reads
+ * them to decide whether its evidence qualifies, and an issuer is bound by them
+ * when it mints.
+ */
+export const EVIDENCE_STATEMENTS = {
+    'dev-bypass': {
+        method: 'dev-bypass',
+        evidence: {
+            identityDocumentChecked: false,
+            biometricCaptured: false,
+            biometricComparedToDocumentPortrait: false,
+        },
+        asserts: 'Asserts NOTHING. No identity document was examined, no biometric was captured, and no ' +
+            'comparison was performed. It marks an identity verified having checked nothing at all, ' +
+            'and an identity marked this way keeps the method permanently.',
+    },
+    document: {
+        method: 'document',
+        evidence: {
+            identityDocumentChecked: true,
+            biometricCaptured: false,
+            biometricComparedToDocumentPortrait: false,
+        },
+        asserts: 'Asserts that a government-issued identity document was checked for validity. It asserts ' +
+            'NO comparison between that document and the person presenting it: the document is sound, ' +
+            'and nothing here says who was holding it.',
+    },
+    'document-and-biometric': {
+        method: 'document-and-biometric',
+        evidence: {
+            identityDocumentChecked: true,
+            biometricCaptured: true,
+            biometricComparedToDocumentPortrait: true,
+        },
+        asserts: 'Asserts a valid government-issued identity document AND a live biometric capture compared ' +
+            "against that document's portrait, with a recorded match decision. The comparison is the " +
+            "whole of what distinguishes this from 'document' — a capture that was never compared is " +
+            "'document', not this.",
+    },
+};
+/**
+ * Every verification method, as a value. Derived from {@link EVIDENCE_STATEMENTS}
+ * rather than hand-listed: that table is a mapped type over the union, so its keys
+ * ARE the union and this list cannot drift from it. A hand-written array beside a
+ * union is a second home for the same fact, and the two disagree eventually.
+ */
+export const VERIFICATION_METHODS = Object.keys(EVIDENCE_STATEMENTS);
+/**
+ * Whether `evidence` supports asserting `method` — the issuer's check, and the
+ * whole of what makes an overclaiming claim REFUSABLE rather than merely
+ * discouraged.
+ *
+ * True when everything the method asserts actually happened. Evidence may exceed
+ * what the method asserts (a compared biometric supports `'document'` perfectly
+ * well); it may never fall short of it.
+ *
+ * The case this exists for: an issuer that checked a document and captured a face
+ * WITHOUT comparing them gets `false` for `'document-and-biometric'`. It must then
+ * mint `'document'` or mint nothing — it must not assert a match decision that was
+ * never recorded.
+ *
+ * `'dev-bypass'` asserts nothing, so nothing can fall short of it and this is
+ * vacuously true for it. That is correct and harmless: a method that claims
+ * nothing cannot overclaim, and it is refused at every gated operation anyway.
+ */
+export function evidenceSupports(method, evidence) {
+    const asserted = EVIDENCE_STATEMENTS[method].evidence;
+    return ((!asserted.identityDocumentChecked || evidence.identityDocumentChecked) &&
+        (!asserted.biometricCaptured || evidence.biometricCaptured) &&
+        (!asserted.biometricComparedToDocumentPortrait || evidence.biometricComparedToDocumentPortrait));
+}
+/**
+ * The strongest method this evidence honestly supports, or `null` when it supports
+ * none. An issuer mints THIS, rather than the method it would like to have.
+ *
+ * `'dev-bypass'` is never returned. It is not a conclusion evidence supports — it
+ * is the marker of a verification that examined nothing, set by the bypass itself
+ * and never derived from evidence. Evidence that proves nothing yields `null`, and
+ * an issuer holding `null` has nothing to assert.
+ */
+export function methodForEvidence(evidence) {
+    if (evidenceSupports('document-and-biometric', evidence))
+        return 'document-and-biometric';
+    if (evidenceSupports('document', evidence))
+        return 'document';
+    return null;
+}
+/**
+ * The acceptance policy: which methods each operation accepts. THE statement of
+ * record — a gate reads it rather than holding its own condition.
+ *
+ * `'dev-bypass'` is `'refused'` at every gated operation and appears in no
+ * accepted set (CAY-0021).
+ */
+export const ASSURANCE_POLICY = {
+    // A holder reading their own balance. No bar: nothing moves, the data is the
+    // holder's own, and the wallet surface deliberately serves a development-bypassed
+    // identity its own wallet while refusing it a purchase. Reading is not a lesser
+    // form of buying — it is a different act, and this entry says so rather than
+    // pretending the bypass cleared something.
+    'read-own-wallet': {
+        operation: 'read-own-wallet',
+        assurance: 'not-required',
+        rationale: 'A holder reading their own balance moves no value and reads nobody else, so no assurance ' +
+            'bar is applied. Authentication is still required; that is a different gate.',
+    },
+    // Polling a purchase the caller started. Same reasoning: a read of one's own
+    // record. The purchase it reports on was itself gated when it was authorised.
+    'read-purchase-result': {
+        operation: 'read-purchase-result',
+        assurance: 'not-required',
+        rationale: 'Polling the result of a purchase the caller already made moves no value; the assurance bar ' +
+            'was applied when that purchase was authorised, and applying it again at the read would ' +
+            'refuse a holder their own outcome.',
+    },
+    // The value-moving operation on this surface, and the bar the money gate reads.
+    'authorise-purchase': {
+        operation: 'authorise-purchase',
+        assurance: 'required',
+        decisions: {
+            // Asserts nothing; permanently refused wherever "identity-verified" is meant.
+            'dev-bypass': 'refused',
+            // A checked document, with no comparison to the person presenting it. Accepted:
+            // this is the bar the money gate has enforced since it was written, and this
+            // slice lifts that policy into the contract without changing it.
+            document: 'accepted',
+            'document-and-biometric': 'accepted',
+        },
+        rationale: 'Buying moves value, so the identity must have been checked by something. A checked document ' +
+            'is the standing bar; it is stated here rather than left as a condition inside the gate.',
+    },
+    // Terminating a purchase the holder started, before anything is captured
+    // (CAY-0032). REQUIRED, and at the same bar as authorising: cancelling releases
+    // reserved headroom and closes a money-path record for good, and a bar lower than
+    // the one that admitted the authorisation would let a weaker credential undo what
+    // a stronger one did. It is its OWN operation rather than a second use of
+    // 'authorise-purchase' because the acts differ — a credential minted so a
+    // confirmation page can finish a purchase should not thereby be able to end one —
+    // and because scope is checked per operation at the gate, so two acts sharing one
+    // key share one authorisation.
+    'cancel-purchase': {
+        operation: 'cancel-purchase',
+        assurance: 'required',
+        decisions: {
+            // Asserts nothing; permanently refused wherever "identity-verified" is meant.
+            'dev-bypass': 'refused',
+            document: 'accepted',
+            'document-and-biometric': 'accepted',
+        },
+        rationale: 'Cancelling releases reserved headroom and closes a purchase for good, so it is money-grade: ' +
+            'anything but the development bypass. The bar is deliberately the same as authorising — a ' +
+            'credential that could not have bought cannot undo a purchase either.',
+    },
+    // Asking whether one's own citizenship has been provisioned. No bar, and for
+    // the same reason reading one's own wallet has none: the question moves no
+    // value, reads nobody else, and — since CAY-0031 — provisions nothing by being
+    // asked. It is deliberately NOT folded into 'provision-citizenship': putting
+    // the write's bar in front of the read would mean a citizen could not find out
+    // whether they had been provisioned without clearing the bar for provisioning
+    // them, which is the question answering itself.
+    'read-own-citizenship': {
+        operation: 'read-own-citizenship',
+        assurance: 'not-required',
+        rationale: 'Asking whether your own citizenship has been provisioned moves no value, reads nobody ' +
+            'else and writes nothing, so no assurance bar is applied. Authentication is still ' +
+            'required; that is a different gate.',
+    },
+    // Binding a Percayso identity to a wallet for the first time, and granting the
+    // sign-up cents that arrive with it (CAY-0031). The policy below was decided in
+    // CAY-0029, before the route existed; CAY-0031 serves the route and reads this
+    // entry unchanged rather than reopening it.
+    'provision-citizenship': {
+        operation: 'provision-citizenship',
+        assurance: 'required',
+        decisions: {
+            'dev-bypass': 'refused',
+            // Accepted, and the reasoning is worth recording because the opposite is
+            // tempting. Provisioning IS the moment an identity becomes a holder, and it
+            // is the only moment at which "is this person the one the document
+            // describes" can be asked — so a bar requiring a recorded comparison is
+            // defensible on its merits. It is not taken, for a reason outside this
+            // file: the only issuer that exists asserts `'document'` and cannot assert
+            // more, so that bar would provision nobody. A wallet is a precondition of
+            // every other operation, so an unprovisionable citizen is not a narrow
+            // refusal — it closes the whole surface, including the purchase path this
+            // same table admits a checked document to. A gate stricter than the one
+            // behind it refuses everybody and protects no-one.
+            //
+            // Sybil farming of grants is the real risk this bar would have addressed,
+            // and it is addressed where the canon puts it — the Account Prohibitions —
+            // rather than by a bar that also excludes every honest citizen.
+            document: 'accepted',
+            'document-and-biometric': 'accepted',
+        },
+        rationale: 'Provisioning binds an identity to a wallet once and every later act inherits that binding, ' +
+            'so it is money-grade: anything but the development bypass. A recorded document-to-person ' +
+            'comparison is not required, because a wallet is a precondition of every other operation ' +
+            'and a bar no issuer can currently clear would provision nobody.',
+    },
+    // Binding an Organisation ID to an Organisation Wallet for the first time
+    // (CAY-0059). Its OWN operation rather than a second use of
+    // 'provision-citizenship': the two bind different holders from different facts —
+    // citizenship binds the authenticated `sub`, this binds the one Organisation ID
+    // the issuer attested — and scope is checked per operation at the gate, so one
+    // key covering both acts would let a credential minted to provision a citizen's
+    // own citizenship bring an Organisation Wallet into being.
+    //
+    // The bar is deliberately the SAME as provisioning a citizen, and for the same
+    // reason rather than a different one: the acting party is still a citizen, the
+    // only issuer that exists asserts 'document' and cannot assert more, and a bar
+    // no issuer can clear would provision nobody. It grants no cents — an
+    // organisation receives no sign-up grant — but it brings a wallet into being,
+    // and a wallet is the precondition of every later act against it.
+    'provision-organisation': {
+        operation: 'provision-organisation',
+        assurance: 'required',
+        decisions: {
+            'dev-bypass': 'refused',
+            document: 'accepted',
+            'document-and-biometric': 'accepted',
+        },
+        rationale: 'Provisioning an organisation binds an Organisation ID to a wallet once and every later act ' +
+            'against that wallet inherits the binding, so it is money-grade: anything but the development ' +
+            'bypass. The bar matches provisioning a citizen because the acting party is a citizen and a ' +
+            'stricter bar than the issuer can clear would provision nobody.',
+    },
+    // Binding a founder wallet, created at genesis and holding a founder's share of
+    // the founder pool, to the Citizen it was allocated to (CAY-0081). Its OWN
+    // operation rather than a second use of 'provision-citizenship': it delivers no
+    // sign-up grant, and a claimed founder must never receive one by any route.
+    //
+    // The bar is DELIBERATELY STRICTER than provisioning's, and the argument that
+    // keeps provisioning at 'document' does not carry over. A founder completes full
+    // identity proofing before claiming (CAY-0081 §9). 'Personally known' decides who
+    // is on the nomination list, not whether they are verified. Provisioning stays at
+    // 'document' because a bar no issuer can clear would provision nobody and close
+    // the whole surface. A bar no issuer can clear here closes the founder claim and
+    // nothing else. Until the issuer can assert a recorded document-to-person
+    // comparison, no founder can claim anywhere but a development stack, and that is
+    // correct. Whether 'document-and-biometric' is what Identity Platform's full
+    // proofing asserts is identity.platform#87's answer.
+    'claim-founder-wallet': {
+        operation: 'claim-founder-wallet',
+        assurance: 'required',
+        decisions: {
+            // Asserts nothing; permanently refused wherever "identity-verified" is meant.
+            'dev-bypass': 'refused',
+            // A checked document with no comparison to the person presenting it. Refused:
+            // it does not show the person claiming is the person the document describes,
+            // and the founder's allocation is the largest figure a claim can reach.
+            document: 'refused',
+            'document-and-biometric': 'accepted',
+        },
+        rationale: 'Claiming binds a founder wallet, and the founder allocation it holds, to one Citizen for ' +
+            'good, with no operator path to correct a mis-claim. So a founder must have completed full ' +
+            'identity proofing: a checked document compared to the person presenting it. A bar the issuer ' +
+            'cannot yet clear closes the founder claim and nothing else.',
+    },
+    // An Organisation paying a Citizen (CAY-0079 §1). Money-grade, on both routes and
+    // for different reasons: the mandate holder because value leaves the
+    // organisation for an individual, and the Authorised User because CAY-0037
+    // already requires the money-grade profile at every use of an allowance. It is an
+    // allowlist, so a future method is admissible only when somebody decides it here.
+    //
+    // The bar is the purchase path's rather than the founder claim's. The acting
+    // party is a citizen, the only issuer that exists asserts 'document', and a bar no
+    // issuer can clear would close the payment on every deployment. What limits how
+    // much can leave is the mandate, the allowance's limit and the Signatory /
+    // Authorised-User threshold, and none of them is an assurance question.
+    'make-commercial-payment': {
+        operation: 'make-commercial-payment',
+        assurance: 'required',
+        decisions: {
+            // Asserts nothing; permanently refused wherever "identity-verified" is meant.
+            'dev-bypass': 'refused',
+            document: 'accepted',
+            'document-and-biometric': 'accepted',
+        },
+        rationale: 'A commercial payment moves value out of an organisation to an individual, so it is ' +
+            'money-grade: anything but the development bypass. The bar applies on both routes, and to ' +
+            'an Authorised User it applies again at every payment, not only when the allowance was granted.',
+    },
+    // 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
+    // every deployment. What limits the market is its figures, which are canon and
+    // unset until the canon carries them, and none of them is an assurance question.
+    //
+    // During B7's exit window an excluded holder places no new quote, and the market
+    // withdraws their resting quotes; the buy-back stays open as an exit route. That is
+    // eligibility rather than assurance, and no exclusion signal reaches Cayso yet, so
+    // it is recorded here and enforced by nothing until the slice that delivers the
+    // signal (`citizen-market.ts`).
+    'place-quote': {
+        operation: 'place-quote',
+        assurance: 'required',
+        decisions: {
+            // Asserts nothing; permanently refused wherever "identity-verified" is meant.
+            'dev-bypass': 'refused',
+            document: 'accepted',
+            'document-and-biometric': 'accepted',
+        },
+        rationale: 'Placing a quote offers cents for sterling or bids sterling for cents, and an ask reserves ' +
+            'cents from entry, so it is money-grade: anything but the development bypass. During the ' +
+            'exclusion exit window no new quote is placed, because entering the market is not an exit.',
+    },
+    // Gated at the SAME bar as placing, so that a lower-assurance credential cannot
+    // interfere with a holder's quotes. A holder who no longer clears it has their
+    // quotes withdrawn by the market rather than left stranded behind a bar they
+    // cannot reach — which is the market's act, not this operation.
+    'withdraw-quote': {
+        operation: 'withdraw-quote',
+        assurance: 'required',
+        decisions: {
+            // Asserts nothing; permanently refused wherever "identity-verified" is meant.
+            'dev-bypass': 'refused',
+            document: 'accepted',
+            'document-and-biometric': 'accepted',
+        },
+        rationale: 'Withdrawing a quote releases reserved cents and changes what the book offers, so it is held ' +
+            'to the same money-grade bar as placing one: a credential that could not have placed a quote ' +
+            'cannot interfere with one either.',
+    },
+    // Selling unrestricted cents to the Treasury at the floor reference. It pays
+    // sterling out, so it is money-grade. It stays open during B7's exit window:
+    // Simon James named it, with transfer, as the way an excluded holder's
+    // unrestricted cents may leave.
+    'request-buy-back': {
+        operation: 'request-buy-back',
+        assurance: 'required',
+        decisions: {
+            // Asserts nothing; permanently refused wherever "identity-verified" is meant.
+            'dev-bypass': 'refused',
+            document: 'accepted',
+            'document-and-biometric': 'accepted',
+        },
+        rationale: 'A buy-back pays sterling for cents the Treasury cancels, so it is money-grade: anything but ' +
+            'the development bypass. It is an exit route during the exclusion exit window, and stays ' +
+            'open to an excluded holder while the window lasts.',
+    },
+    // Reading the book. No bar, for read-own-wallet's reason: nothing moves, and what
+    // the read shows is the published value, the two bounds, the best bid and ask with
+    // their sizes, and the caller's own quotes. Placing and withdrawing are gated; a
+    // look at the book is a different act, and this entry says so rather than letting
+    // the read borrow the market's bar.
+    'read-citizen-market': {
+        operation: 'read-citizen-market',
+        assurance: 'not-required',
+        rationale: 'Reading the book moves no value and names nobody: it shows the published value, the floor ' +
+            "reference, the best bid and ask with their sizes, and the caller's own quotes. " +
+            'Authentication is still required; that is a different gate.',
+    },
+    // The marketplace status read (CAY-0083 §2). Read-scope, not money-grade, because
+    // nothing moves: it answers the signed receipt of the movement a key landed for the
+    // buyer's own wallet, or "no movement for this key", and writes no row. The bar was
+    // applied when the settlement it reports on was presented, as `read-purchase-result`
+    // leaves it at the authorisation. Holding the read to the money-grade bar would
+    // refuse a buyer the one answer that tells them whether their cents moved, which is
+    // the answer that stops a retry under a new key.
+    'read-marketplace-receipt': {
+        operation: 'read-marketplace-receipt',
+        assurance: 'not-required',
+        rationale: "Asking what an idempotency key landed for the buyer's own wallet moves no value, reads " +
+            'nobody else and writes nothing, so no assurance bar is applied; the bar was applied when ' +
+            'the sale or refund was presented. Authentication is still required; that is a different gate.',
+    },
+    // The two marketplace operations Piper presents Store Platform's signed decisions
+    // under (CAY-0083 §3). Both money-grade, and both allowlists (CAY-0029), so a future
+    // method is admissible only when somebody decides it here.
+    //
+    // The bar is the purchase path's rather than the founder claim's, for the reason
+    // the commercial payment's is: the acting party is a Citizen, the only issuer that
+    // exists asserts 'document', and a bar no issuer can clear would close the
+    // marketplace on every deployment. What limits a sale is Store Platform's signed
+    // order and the buyer's unrestricted cents, and what limits a refund is Store
+    // Platform's signed decision and its refund policy. None of those is an assurance
+    // question.
+    'settle-marketplace-order': {
+        operation: 'settle-marketplace-order',
+        assurance: 'required',
+        decisions: {
+            // Asserts nothing; permanently refused wherever "identity-verified" is meant.
+            'dev-bypass': 'refused',
+            document: 'accepted',
+            'document-and-biometric': 'accepted',
+        },
+        rationale: "Settling a marketplace sale moves the buyer's cents to a publisher and the Treasury, so it " +
+            'is money-grade: anything but the development bypass. The signed order says what is bought ' +
+            'and who is paid; the assertion says who is buying, and it is held to this bar.',
+    },
+    // A refund draws a publisher's cents back to the buyer on Store Platform's
+    // authority. The buyer is the payee, and their assertion shows who is present, so
+    // it is held to the SAME bar as the sale: a credential that could not have bought
+    // cannot be refunded either, and a lower bar here would let a weaker credential
+    // draw cents out of a publisher's wallet that a stronger one paid in.
+    'settle-marketplace-refund': {
+        operation: 'settle-marketplace-refund',
+        assurance: 'required',
+        decisions: {
+            // Asserts nothing; permanently refused wherever "identity-verified" is meant.
+            'dev-bypass': 'refused',
+            document: 'accepted',
+            'document-and-biometric': 'accepted',
+        },
+        rationale: "Settling a marketplace refund draws cents from a publisher's wallet and the Treasury to the " +
+            'buyer, so it is money-grade: anything but the development bypass. The authority is Store ' +
+            "Platform's signed refund decision; the assertion shows the buyer is present, and it is held " +
+            'to the same bar as the sale it refunds.',
+    },
+};
+/**
+ * Every operation, as a value. Derived from {@link ASSURANCE_POLICY} for the same
+ * reason {@link VERIFICATION_METHODS} is derived from the statements: the mapped
+ * type makes the table's keys the union, so this cannot drift.
+ */
+export const CONTRACT_OPERATIONS = Object.keys(ASSURANCE_POLICY);
+/**
+ * Which operation each route on the contract surface exercises, or `null` for a
+ * route that carries no identity at all (the public version handshake — you cannot
+ * be assured before you can negotiate the contract).
+ *
+ * Adding a route to `ROUTES` is a compile error here until it is mapped, so "every
+ * operation on this surface is classified" is mechanical rather than asserted.
+ * The reverse direction is deliberately not total — an operation may be
+ * classified before it has a route, which is how `'provision-citizenship'` was
+ * decided here and then served, unchanged, by CAY-0031.
+ *
+ * The two citizenship routes map to two DIFFERENT operations, which is the whole
+ * reason they are two paths: one path carries one scope requirement at CAY-0030's
+ * gate, so a read sharing a path with a write would share its scope too.
+ */
+export const OPERATION_FOR_ROUTE = {
+    wallet: 'read-own-wallet',
+    citizenship: 'read-own-citizenship',
+    citizenshipProvision: 'provision-citizenship',
+    citizenshipFounderClaim: 'claim-founder-wallet',
+    organisationProvision: 'provision-organisation',
+    purchaseAuthorise: 'authorise-purchase',
+    purchaseResult: 'read-purchase-result',
+    purchaseCancel: 'cancel-purchase',
+    commercialPayment: 'make-commercial-payment',
+    citizenMarket: 'read-citizen-market',
+    placeQuote: 'place-quote',
+    withdrawQuote: 'withdraw-quote',
+    requestBuyBack: 'request-buy-back',
+    version: null,
+};
+/**
+ * The closed set of methods an operation accepts, or `null` when it applies no
+ * assurance bar. `null` and `[]` are different answers and the caller must tell
+ * them apart: `[]` would mean "accepts nothing", which is true of no operation
+ * here.
+ *
+ * Derived from the decisions, never authored beside them — one table, read two
+ * ways, so an accepted set cannot disagree with the decision it came from.
+ */
+export function acceptedMethods(operation) {
+    const policy = ASSURANCE_POLICY[operation];
+    if (policy.assurance === 'not-required')
+        return null;
+    return VERIFICATION_METHODS.filter((method) => policy.decisions[method] === 'accepted');
+}
+/** The single accepted value — one object, since it carries nothing. */
+const ACCEPTED = { accepted: true };
+/**
+ * May this claim perform this operation, on assurance grounds? The verifier half
+ * of the profile, and the function a gate calls instead of writing a condition.
+ *
+ * It reads exactly three fields — the profile version, the status and the method —
+ * and nothing else. Not `mandateFor`: whether a caller may act for a wallet is
+ * authority, not assurance, and the Signatory / Authorised-User threshold is a
+ * canon figure the gate for that operation reads from configuration. Not the reserved
+ * claims. Not the issuer or the key: whether the claim can be TRUSTED is the trust
+ * envelope's question, a separate gap, and a caller must answer it separately.
+ * This function assumes it has already been answered.
+ *
+ * The order of the checks is the order of the questions: do we understand this
+ * profile at all, does this operation apply a bar, was the identity verified, did
+ * it name a method, is that method accepted here.
+ */
+export function assessAssurance(operation, claims) {
+    // An unrecognised profile is refused before anything else and whatever the
+    // operation: a method name minted under a profile we do not hold means whatever
+    // that profile said it meant, and reading it as if it meant this one's is the
+    // failure the version exists to prevent.
+    if (!RECOGNISED_ASSURANCE_PROFILE_VERSIONS.includes(claims.assuranceProfileVersion)) {
+        return { accepted: false, refusalReason: 'assurance_profile_unrecognised' };
+    }
+    const policy = ASSURANCE_POLICY[operation];
+    if (policy.assurance === 'not-required')
+        return ACCEPTED;
+    if (claims.verificationStatus !== 'verified') {
+        return { accepted: false, refusalReason: 'identity_unverified' };
+    }
+    // Verified while naming no method is an incoherent claim, and it is exactly the
+    // trap CAY-0021 names in a different guise: asking for "verified" and inheriting
+    // whatever that includes. There is no evidence to assess, so there is nothing to
+    // accept.
+    if (claims.verificationMethod === null) {
+        return { accepted: false, refusalReason: 'verification_method_absent' };
+    }
+    if (policy.decisions[claims.verificationMethod] !== 'accepted') {
+        return { accepted: false, refusalReason: 'verification_method_not_accepted' };
+    }
+    return ACCEPTED;
+}