@percayso-community/cayso-contracts 0.23.0

package/dist/assertion.js

@@ -0,0 +1,63 @@
+/*
+ * 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.
+ */
+// --- The credential's clock and retention parameters -------------------------
+/**
+ * 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 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 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 const MINIMUM_ASSERTION_USE_RETENTION_SECONDS = MAX_ASSERTION_LIFETIME_SECONDS + CLOCK_SKEW_TOLERANCE_SECONDS;

package/dist/assurance.d.ts

@@ -0,0 +1,353 @@
+/**
+ * `assurance` — what each `VerificationMethod` actually proves, and which methods
+ * each operation accepts (CAY-0029).
+ *
+ * `assertion.ts` declares that a claim carries a method. It does not say what any
+ * method *asserts*, and until this file there was no statement of that anywhere:
+ * the money gate's own condition was the only operative definition of "good
+ * enough to move value", which made the acceptance policy an implementation
+ * detail a consumer could not read and could change without anybody being told.
+ * This file is that statement, written down as contract.
+ *
+ * ## The standard is Cayso's own, and it is versioned
+ *
+ * No external assurance scheme is adopted here. The three methods on this surface
+ * are the issuer's, their evidence is described in the issuer's terms, and
+ * inventing a mapping onto somebody else's levels would assert a correspondence
+ * nobody has checked. So the profile is written here — and {@link
+ * ASSURANCE_PROFILE_VERSION} exists so that adopting an external scheme later is a
+ * NEW VERSION of this profile rather than a rewrite of it. A claim says which
+ * version it was made under; a deployment says which versions it recognises; a
+ * claim made under a version this deployment does not recognise is refused rather
+ * than read as if it meant what this version means.
+ *
+ * ## The statements must be TRUTHFUL, and the one that matters is the comparison
+ *
+ * `'document-and-biometric'` is distinguished from `'document'` by exactly one
+ * thing: a live capture **compared against the document's portrait, with a
+ * recorded match decision**. Not a captured photograph. Not a liveness check. The
+ * comparison.
+ *
+ * The issuer today checks that a passport is valid and that a photograph contains
+ * *a* face, and never compares the two. That evidence supports `'document'` and
+ * nothing stronger — which is why the issuer maps it to `'document'` and refuses
+ * to mint a purchase assertion at all, rather than assert a biometric match that
+ * did not occur. {@link evidenceSupports} makes that refusal MECHANICAL rather
+ * than scrupulous: an issuer asks it before minting, and a claim asserting
+ * evidence that did not occur is refusable at the point it would be made.
+ *
+ * ## Acceptance is a CLOSED SET per operation, never a threshold
+ *
+ * Each operation names the methods it accepts, and the set is authored as a
+ * decision for every method ({@link MethodDecisions}) rather than as a rank with a
+ * `>=` comparison. The difference is the whole design:
+ *
+ *   - A rank ADMITS A NEW METHOD SILENTLY. Add a stronger method tomorrow and
+ *     every operation whose bar sits below it widens the moment it is declared,
+ *     with no review anywhere.
+ *   - A decision per method CANNOT. {@link MethodDecisions} is a mapped type over
+ *     {@link VerificationMethod}, so a new member is a COMPILE ERROR at every
+ *     gated operation until somebody writes `'accepted'` or `'refused'` for it.
+ *     Widening becomes a deliberate, reviewable edit.
+ *
+ * `'dev-bypass'` appears in no operation's accepted set and permanently (CAY-0021):
+ * it asserts nothing, so there is no operation meaning "identity-verified" that it
+ * can clear. That is not this slice's to revisit.
+ *
+ * ## An operation may have NO assurance bar, and that is not the same as accepting everything
+ *
+ * Reading one's own wallet requires authentication and no assurance at all: a
+ * holder looking at their own balance moves nothing, and the surface deliberately
+ * serves a development-bypassed identity its own wallet while refusing it a
+ * purchase. Recording that as `'not-required'` is the truthful entry. Recording it
+ * instead as "accepts every method" would put `'dev-bypass'` in an accepted set
+ * and assert, falsely, that the bypass clears a bar — when the honest statement is
+ * that no bar is applied. An operation with no bar cannot be widened by a new
+ * method, because it was never narrowed.
+ *
+ * ## What this file is NOT
+ *
+ * It is not the trust envelope. Whether a claim can be trusted at all — who
+ * issued it, under which key, whether it has been replayed or revoked — is a
+ * SEPARATE decision, taken in CAY-0030 and expressed in `assertion.ts`'s header
+ * and envelope types. A perfect face match signed by a runtime its owner controls
+ * is still not evidence. Nothing here reads an issuer, a key id or a scope, and
+ * nothing here should grow one: {@link assessAssurance} answers "how well is this
+ * identity known", the envelope answers "may this credential be believed at all",
+ * and a gate must satisfy both.
+ *
+ * It is not a gate either. This is data and pure functions: no route, no state, no
+ * environment read, nothing that runs on import (CLAUDE.md: packages have no side
+ * effects). `apps/api`'s money gate stays the single place the check HAPPENS; it
+ * stops being the place the policy is WRITTEN.
+ *
+ * It carries no numbers. An assurance profile version is a version identifier, not
+ * an amount, rate, tier, schedule or threshold; every economic figure lives in the
+ * canon PRD and is read from one place.
+ *
+ * ## Why the policy is not in the generated contract schema
+ *
+ * `contract-schema.generated.ts` describes the DATA CROSSING THE BOUNDARY — the
+ * wire shapes a consumer decodes. The wire consequence of this file is one field,
+ * `AssertionClaims.assuranceProfileVersion`, and that IS described there. The
+ * policy itself is a table a consumer imports at compile time, not a shape it
+ * decodes off a response, so it is deliberately not in the descriptor.
+ */
+import type { AssertionClaims, ContractOperation, VerificationMethod } from './assertion.js';
+import { ROUTES } from './routes.js';
+/**
+ * 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 declare 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 declare const RECOGNISED_ASSURANCE_PROFILE_VERSIONS: readonly string[];
+/**
+ * The evidence behind a verification, as three facts that either happened or did
+ * not. Booleans rather than prose because an issuer has to be able to CHECK its
+ * own claim against them ({@link evidenceSupports}), and prose cannot be checked.
+ *
+ * `biometricComparedToDocumentPortrait` is the field that matters. Capturing a
+ * biometric and comparing one are different events, and conflating them is exactly
+ * the overclaim this file exists to make refusable.
+ */
+export interface VerificationEvidence {
+    /** A government-issued identity document was examined and checked for validity. */
+    readonly identityDocumentChecked: boolean;
+    /** A live biometric was captured from the person presenting. Capture ALONE proves no link to the document. */
+    readonly biometricCaptured: boolean;
+    /** The captured biometric was compared against the document's portrait AND a match decision was recorded. */
+    readonly biometricComparedToDocumentPortrait: boolean;
+}
+/**
+ * What one verification method asserts: the evidence it stands for, and the
+ * sentence a human reads. The sentence and the booleans say the same thing twice
+ * on purpose — one for a person deciding whether their evidence qualifies, one for
+ * code that must decide the same question without reading English.
+ */
+export interface EvidenceStatement {
+    readonly method: VerificationMethod;
+    /** The evidence this method asserts occurred. Anything `false` here is asserted by this method NOT to have happened. */
+    readonly evidence: VerificationEvidence;
+    /** The truthful statement, for a human. It must not overclaim, and it must name what was NOT done. */
+    readonly asserts: string;
+}
+/**
+ * A statement for EVERY method — a mapped type, so a new member of {@link
+ * VerificationMethod} cannot arrive without somebody writing down what it proves.
+ * That is the first of the two compile errors a new method causes; the second is
+ * at every gated operation's {@link MethodDecisions}.
+ */
+type EvidenceStatements = {
+    readonly [M in VerificationMethod]: EvidenceStatement;
+};
+/**
+ * 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 declare const EVIDENCE_STATEMENTS: EvidenceStatements;
+/**
+ * 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 declare const VERIFICATION_METHODS: readonly VerificationMethod[];
+/**
+ * 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 declare function evidenceSupports(method: VerificationMethod, evidence: VerificationEvidence): boolean;
+/**
+ * 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 declare function methodForEvidence(evidence: VerificationEvidence): VerificationMethod | null;
+/**
+ * The operation vocabulary, re-exported from `assertion.ts` where it is declared.
+ *
+ * ONE VOCABULARY, NOT TWO. An assertion's `scope` lists the operations a
+ * credential was minted to perform (CAY-0030) and this file writes an acceptance
+ * policy per operation (CAY-0029); those are the same operations, so the type is
+ * declared once — beside the claims that carry it — and consumed here. It is
+ * re-exported rather than restated for exactly the reason {@link
+ * VERIFICATION_METHODS} is derived from {@link EVIDENCE_STATEMENTS}: a second
+ * home for one fact is two facts that disagree eventually. The same direction
+ * already holds for `VerificationMethod`, which this file consumes from
+ * `assertion.ts` and never redeclares.
+ */
+export type { ContractOperation } from './assertion.js';
+/** What one operation does with one method. There is no third answer and no ordering. */
+export type MethodDecision = 'accepted' | 'refused';
+/**
+ * A decision for EVERY method. This mapped type is the mechanism behind the
+ * acceptance criterion "adding a stronger method does not silently widen what an
+ * existing operation accepts": add a member to {@link VerificationMethod} and
+ * every gated operation stops compiling until somebody decides, for that
+ * operation, whether the new method is accepted.
+ */
+export type MethodDecisions = {
+    readonly [M in VerificationMethod]: MethodDecision;
+};
+/**
+ * An operation that means "identity-verified": it applies an assurance bar, and
+ * the closed set of methods that clear it is authored as {@link decisions}.
+ */
+export interface AssuranceRequired {
+    readonly operation: ContractOperation;
+    readonly assurance: 'required';
+    /** A decision for every method. The accepted SET is read from here, never a rank. */
+    readonly decisions: MethodDecisions;
+    /** Why this bar, in a sentence a consumer can act on. */
+    readonly rationale: string;
+}
+/**
+ * An operation that applies no assurance bar at all. Distinct from one that
+ * accepts every method: no bar is APPLIED, rather than every method CLEARING one.
+ * A caller still has to be authenticated — that is a different gate and not this
+ * profile's business.
+ */
+export interface AssuranceNotRequired {
+    readonly operation: ContractOperation;
+    readonly assurance: 'not-required';
+    readonly rationale: string;
+}
+/** What one operation requires of a verification. Switch on `assurance`. */
+export type OperationAssurance = AssuranceRequired | AssuranceNotRequired;
+/**
+ * An entry for EVERY operation — a mapped type, so a new operation cannot be added
+ * without being classified, the same discipline the route-policy table applies to
+ * routes.
+ */
+type AssurancePolicyTable = {
+    readonly [O in ContractOperation]: OperationAssurance;
+};
+/**
+ * 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 declare const ASSURANCE_POLICY: AssurancePolicyTable;
+/**
+ * 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 declare const CONTRACT_OPERATIONS: readonly ContractOperation[];
+/**
+ * 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 declare const OPERATION_FOR_ROUTE: {
+    readonly [R in keyof typeof ROUTES]: ContractOperation | 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 declare function acceptedMethods(operation: ContractOperation): readonly VerificationMethod[] | null;
+/**
+ * Why a verifier will not accept a claim ON ASSURANCE GROUNDS. A closed union, so
+ * a consumer renders a member instead of pattern-matching on our prose — the same
+ * discipline the purchase failure reasons follow (CAY-0023). A new reason is a new
+ * member and a version bump, never a free-text field.
+ *
+ * There is deliberately no member naming the development bypass. Which methods an
+ * operation accepts is policy that moves; "the method you presented is not
+ * accepted here" is the reason, and it stays true whatever the table says.
+ */
+export type AssuranceRefusalReason = 
+/** The claim was made under an assurance profile this deployment does not recognise. */
+'assurance_profile_unrecognised'
+/** The issuer does not regard this identity as verified at all. */
+ | 'identity_unverified'
+/** Verified, but naming no method — there is no evidence to assess. */
+ | 'verification_method_absent'
+/** The method is not in this operation's accepted set. */
+ | 'verification_method_not_accepted';
+/**
+ * The outcome of assessing a claim against an operation's policy. A discriminated
+ * union rather than a boolean and a nullable reason: a refusal always carries a
+ * reason, and an acceptance cannot carry one.
+ */
+export type AssuranceAssessment = {
+    readonly accepted: true;
+} | {
+    readonly accepted: false;
+    readonly refusalReason: AssuranceRefusalReason;
+};
+/**
+ * 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 declare function assessAssurance(operation: ContractOperation, claims: AssertionClaims): AssuranceAssessment;