@percayso/identity-contracts 0.1.0

package/dist/evidence.js

@@ -0,0 +1,224 @@
+/**
+ * The evidence vocabulary: facts, never scores, and a method that cannot exceed
+ * what its facts support.
+ *
+ * §8.2 is the whole of this file in two sentences. "The verification provider must
+ * return **evidence facts and reason codes**, not an unqualified score or Boolean."
+ * And: "**Evidence is never overstated.** A passport MRZ read plus an unmatched
+ * selfie is not a document-and-biometric decision, and no provider's unqualified
+ * 'pass' may be recorded as one."
+ *
+ * ENFORCED TWICE.
+ *
+ * The compile-time half is `MethodSupportedBy`, a type-level function from evidence
+ * to the strongest method that evidence honestly supports. Code that knows its
+ * evidence as literals — a fixture, a test, a stub profile, the issuer assembling a
+ * claim it is about to mint — writes `MethodSupportedBy<typeof facts>` and gets a
+ * compile error rather than an overclaim. `document-and-biometric` is unreachable
+ * from evidence whose `biometricComparedToDocumentPortrait` is `false`, and there is
+ * no widening that gets there.
+ *
+ * The runtime half is `parseVerificationCaseSummary`, because a type can say nothing
+ * about a provider's JSON. It recomputes the supported method from the facts on the
+ * wire and refuses a `method` stronger than they bear — the exact case §8.2 names.
+ *
+ * WHY THE SUPPORT RULE IS WRITTEN HERE AND NOT IMPORTED.
+ *
+ * `@cayso/contracts` exports `methodForEvidence`, which answers the same question,
+ * and this package deliberately cannot use it: it holds no runtime dependency, and
+ * the coupling scan's rule C makes that mechanical by refusing a bare specifier in a
+ * value position. Two implementations of one rule is normally how they diverge, so
+ * the divergence is closed where it can be closed — `evidence.test.ts` imports
+ * Cayso's function (a test file, outside the coupling scan, using the exact-pinned
+ * development dependency) and asserts the two agree across every combination of the
+ * three facts. An upstream change to the rule fails this package's test run rather
+ * than passing silently into a consumer.
+ *
+ * The authority still belongs upstream. A verifier or issuer taking a real decision
+ * uses Cayso's function, and that is where the value dependency is taken. What lives
+ * here refuses an overstatement at a contract boundary; it does not grant an
+ * assurance.
+ *
+ * NO ROUTE IS HARD-CODED, AND THE STUB'S IDENTIFIER IS NOT IN THIS PACKAGE.
+ *
+ * §8.3 requires a "route-neutral, versioned evidence model" and warns that
+ * "hard-coding the first document reader into policy is how it becomes permanent by
+ * accident". So `EvidenceRoute` and `EvidencePolicyVersion` are opaque versioned
+ * identifiers rather than closed unions: phase one is passport-only, and a published
+ * union with one member would make that the contract every consumer compiled
+ * against. Adding a route is "a **new** evidence-policy version" (§8.3), which is a
+ * value, not a type change.
+ *
+ * The stub's route and policy version are deliberately absent for a stronger reason.
+ * §8.4 requires that "the production bundle contains neither the stub implementation
+ * nor its selection identifier". A member named for the stub in a contract package
+ * every production surface imports would place that selection identifier in every
+ * one of them. The stub names its own route, in its own package, excluded at build
+ * time — which is §8.4's "decisive control is build-time exclusion, not
+ * configuration".
+ */
+import { readApplicationId, readVerificationCaseId, } from "./ids.js";
+import { readBoolean, readClosedRecord, readString, refuseValue, } from "./parse.js";
+/**
+ * A versioned identifier: lower case, separated by hyphens or dots.
+ *
+ * Dots are admitted so that `passport-1.2` is expressible; upper case and
+ * whitespace are not, because these values appear in stored records and in
+ * comparisons, and two spellings of one route is one route nobody can query.
+ */
+const VERSIONED_IDENTIFIER = /^[a-z0-9]+(?:[-.][a-z0-9]+)*$/;
+/** An `EvidenceRoute` from a wire value, or a refusal. */
+export const parseEvidenceRoute = (value, field = "evidenceRoute") => {
+    if (!VERSIONED_IDENTIFIER.test(value)) {
+        refuseValue(field, "must be a lower-case versioned identifier separated by hyphens or dots");
+    }
+    return value;
+};
+/** An `EvidencePolicyVersion` from a wire value, or a refusal. */
+export const parseEvidencePolicyVersion = (value, field = "evidencePolicyVersion") => {
+    if (!VERSIONED_IDENTIFIER.test(value)) {
+        refuseValue(field, "must be a lower-case versioned identifier separated by hyphens or dots");
+    }
+    return value;
+};
+/** Every outcome, in §8.6's order. */
+export const VERIFICATION_OUTCOMES = Object.freeze(["pass", "refer", "fail"]);
+/** A `VerificationOutcome` from a wire value, or a refusal. */
+export const parseVerificationOutcome = (value, field = "outcome") => {
+    if (typeof value !== "string" ||
+        !VERIFICATION_OUTCOMES.includes(value)) {
+        refuseValue(field, "must be one of pass, refer or fail (§8.6)");
+    }
+    return value;
+};
+/**
+ * The strongest method this evidence supports, at runtime, or `null` for evidence
+ * that supports none.
+ *
+ * `null` is not a failure and must not be rendered as one: it is the honest answer
+ * for a case that examined nothing yet. A caller holding `null` has nothing to
+ * assert, which is §8.2's position exactly.
+ */
+export const methodSupportedByEvidence = (evidence) => {
+    if (!evidence.identityDocumentChecked) {
+        return null;
+    }
+    if (evidence.biometricCaptured &&
+        evidence.biometricComparedToDocumentPortrait) {
+        return "document-and-biometric";
+    }
+    return "document";
+};
+/**
+ * Whether `method` is honest about `evidence` — the refusable form of §8.2.
+ *
+ * Evidence may exceed what a method asserts; it may never fall short of it. A
+ * `dev-bypass` case is honest only when nothing was examined: a bypass that claims
+ * a document was checked is an overstatement in the other direction, and the one a
+ * migration would most like to make.
+ */
+export const evidenceSupportsMethod = (method, evidence) => {
+    if (method === "dev-bypass") {
+        return (!evidence.identityDocumentChecked &&
+            !evidence.biometricCaptured &&
+            !evidence.biometricComparedToDocumentPortrait);
+    }
+    const supported = methodSupportedByEvidence(evidence);
+    if (supported === null) {
+        return false;
+    }
+    return method === "document" ? true : supported === "document-and-biometric";
+};
+const CASE_FIELDS = Object.freeze([
+    "verificationCaseId",
+    "applicationId",
+    "outcome",
+    "evidenceRoute",
+    "evidencePolicyVersion",
+    "facts",
+    "method",
+    "providerCaseReference",
+]);
+/** Fields that would make a supplier's number the decision. §8.2, §8.8 and §15 all refuse them. */
+const SCORE_FIELDS = Object.freeze([
+    "score",
+    "providerScore",
+    "confidence",
+    "matchScore",
+    "threshold",
+    "similarity",
+]);
+const FACT_FIELDS = Object.freeze([
+    "identityDocumentChecked",
+    "biometricCaptured",
+    "biometricComparedToDocumentPortrait",
+    "documentAuthenticityEstablished",
+    "presentationAttackCheckPerformed",
+]);
+const METHOD_MEMBERS = Object.freeze([
+    "dev-bypass",
+    "document",
+    "document-and-biometric",
+]);
+/** The evidence facts from a wire value, or a refusal. */
+export const parseIdentityEvidenceFacts = (value, field = "facts") => {
+    const record = readClosedRecord(value, field, [
+        ...FACT_FIELDS,
+        ...SCORE_FIELDS,
+    ]);
+    for (const key of Object.keys(record)) {
+        if (SCORE_FIELDS.includes(key)) {
+            refuseValue(`${field}.${key}`, "is a provider figure and not an evidence fact. A bare provider score is never the decision (§8.2, §15)");
+        }
+    }
+    return {
+        identityDocumentChecked: readBoolean(record, field, "identityDocumentChecked"),
+        biometricCaptured: readBoolean(record, field, "biometricCaptured"),
+        biometricComparedToDocumentPortrait: readBoolean(record, field, "biometricComparedToDocumentPortrait"),
+        documentAuthenticityEstablished: readBoolean(record, field, "documentAuthenticityEstablished"),
+        presentationAttackCheckPerformed: readBoolean(record, field, "presentationAttackCheckPerformed"),
+    };
+};
+/**
+ * A `VerificationCaseSummary` from a wire value, or a refusal.
+ *
+ * The refusal that matters is the last one: a `method` the facts do not bear is
+ * refused, naming the method the facts actually support. That is §8.2's "A passport
+ * MRZ read plus an unmatched selfie is not a document-and-biometric decision",
+ * enforced where a provider's response enters this pillar.
+ */
+export const parseVerificationCaseSummary = (value, field = "verificationCase") => {
+    const record = readClosedRecord(value, field, [
+        ...CASE_FIELDS,
+        ...SCORE_FIELDS,
+    ]);
+    for (const key of Object.keys(record)) {
+        if (SCORE_FIELDS.includes(key)) {
+            refuseValue(`${field}.${key}`, "is a provider figure and not a decision. This pillar records its own versioned decision from evidence facts (§8.2, §8.8, §15)");
+        }
+    }
+    const facts = parseIdentityEvidenceFacts(record["facts"], `${field}.facts`);
+    const method = readString(record, field, "method");
+    if (!METHOD_MEMBERS.includes(method)) {
+        refuseValue(`${field}.method`, "must be a verification method of the Cayso assurance profile");
+    }
+    if (!evidenceSupportsMethod(method, facts)) {
+        const supported = methodSupportedByEvidence(facts);
+        refuseValue(`${field}.method`, supported === null
+            ? "claims more than the evidence facts support. These facts support no method at all (§8.2)"
+            : `claims more than the evidence facts support. These facts support ${supported} (§8.2)`);
+    }
+    const providerCaseReference = record["providerCaseReference"];
+    return {
+        verificationCaseId: readVerificationCaseId(record, field, "verificationCaseId"),
+        applicationId: readApplicationId(record, field, "applicationId"),
+        outcome: parseVerificationOutcome(record["outcome"], `${field}.outcome`),
+        evidenceRoute: parseEvidenceRoute(readString(record, field, "evidenceRoute"), `${field}.evidenceRoute`),
+        evidencePolicyVersion: parseEvidencePolicyVersion(readString(record, field, "evidencePolicyVersion"), `${field}.evidencePolicyVersion`),
+        facts,
+        method: method,
+        providerCaseReference: providerCaseReference === null
+            ? null
+            : readString(record, field, "providerCaseReference"),
+    };
+};

package/dist/ids.d.ts

@@ -0,0 +1,158 @@
+/**
+ * The identifiers of §9 and §15, each branded and each parsed.
+ *
+ * The canon's identifier rules are almost all rules about CONFUSION — which opaque
+ * string may stand in for which other opaque string — and they are the rules this
+ * pillar has already lost twice. CONTEXT.md states three of them outright: a Citizen
+ * ID "is the only identifier that may appear as an assertion subject"; a Piper
+ * Platform subject "identifies a local account… is never evidence of which human is
+ * present and is never the source of a Citizen ID"; a Handle "is never a Citizen ID
+ * and never appears in Cayso Platform's ledger identity".
+ *
+ * Every one of those is a string. Nothing structural tells them apart, so the brand
+ * of `brand.ts` does the telling: they are mutually unassignable, and a function that
+ * asks for a `CitizenId` cannot be handed a `PiperPlatformSubject` however the value
+ * was obtained. That is the half a compiler holds.
+ *
+ * The half a compiler cannot hold is a value that arrived over a wire, which is what
+ * each `parse…` function is for.
+ *
+ * WHAT THE PARSERS DELIBERATELY DO NOT DO
+ *
+ * They do not pin a generated format. §12.2 limits this package to "wire types,
+ * closed error/status unions and a thin client only", and how a Citizen ID is
+ * MINTED is the schema's business — P1-3's — not the contract's. What the contract
+ * can honestly say is the shape an opaque identifier has on the wire: printable,
+ * unpunctuated, URL-safe, and therefore incapable of being an email address or a
+ * qualified name. `OPAQUE_IDENTIFIER` admits UUID, ULID, base64url and every other
+ * format P1-3 might choose, and admits none of the values CONTEXT.md says an
+ * identifier is not.
+ *
+ * They also carry no length bound. A bound would be a figure, and this pillar's rule
+ * is that a figure belongs in §12.5's register with its evidence and is read from
+ * configuration. The bound that actually matters to a service is the request-size
+ * limit, which §12.1 puts on the slice that exposes an endpoint (P1-8).
+ */
+import type { Branded } from "./brand.js";
+/**
+ * The Community email domains of §9: `percayso.me` for Citizens, `percayso.biz` for
+ * Organisations. Both are confirmed and owned by Percayso.
+ *
+ * Organisation addresses are not phase-one work — §9 says so — and the domain is
+ * listed anyway because the union is the contract. A closed union that omitted a
+ * domain the canon confirms would be a union the Organisation slice has to break.
+ */
+export declare const COMMUNITY_EMAIL_DOMAINS: readonly ["percayso.me", "percayso.biz"];
+/** One of the two Community email domains. */
+export type CommunityEmailDomain = (typeof COMMUNITY_EMAIL_DOMAINS)[number];
+/**
+ * Identity Platform's stable, opaque identifier for a Citizen.
+ *
+ * The only identifier that may appear as an assertion subject (CONTEXT.md, and
+ * `assertion.ts` is where that is made unexpressible rather than merely stated).
+ */
+export type CitizenId = Branded<"CitizenId">;
+/** The identifier of one person's attempt to become a Citizen (§5.2). */
+export type ApplicationId = Branded<"ApplicationId">;
+/** The identifier of the record of what evidence was examined, and what was concluded. */
+export type VerificationCaseId = Branded<"VerificationCaseId">;
+/**
+ * The identifier of one registered installation of Piper Platform (§15 `deployments`).
+ *
+ * Registration "gives accountability, throttling and revocation. It does NOT admit an
+ * issuer, prove the code is unmodified, or establish which human is present"
+ * (CONTEXT.md, **Deployment**). Its separateness from `CitizenId` is the type-level
+ * form of §14.4's "possession of any deployment credential is insufficient without
+ * independently verifiable Citizen proof".
+ */
+export type DeploymentId = Branded<"DeploymentId">;
+/**
+ * The identifier of a local user inside one Piper Platform deployment.
+ *
+ * It identifies a local account and nothing else. §7.1: Identity Platform derives the
+ * Citizen subject from its own authenticated session, and "no path, query, body,
+ * header, cookie or installation registration may replace it". This type exists
+ * PRECISELY so that the replacement cannot be written: it is not assignable to
+ * `CitizenId`, and this package publishes no function that converts one to the other.
+ */
+export type PiperPlatformSubject = Branded<"PiperPlatformSubject">;
+/** A Citizen's unique, chosen, public pseudonym, in the canonical form of §9.1. */
+export type CanonicalHandle = Branded<"CanonicalHandle">;
+/**
+ * The submitted form of a Handle, stored separately from the canonical one (§9.1).
+ *
+ * Separate types rather than one, because §9.1 requires separate storage and the
+ * reason is operational: an algorithm upgrade "never silently changes an existing
+ * Handle", which is only checkable if the two forms were never the same field.
+ */
+export type DisplayHandle = Branded<"DisplayHandle">;
+/**
+ * The address assigned to a Citizen under a Community domain, as its OWN identifier.
+ *
+ * §9.2: the initial local part is the canonical Handle, and it is then stored
+ * separately — "changing the Handle does not automatically change the email address".
+ * A distinct brand is what stops a Handle being written into this field by a
+ * conversion somebody thought was obviously safe.
+ */
+export type CommunityEmailAddress = Branded<"CommunityEmailAddress">;
+/**
+ * An opaque reference tying one exchange to its audit record (§15 `audit_events`).
+ *
+ * It is carried on a refusal, and it is the ONLY thing carried on one that varies —
+ * see `refusal.ts` for why that list is as short as it is.
+ */
+export type CorrelationReference = Branded<"CorrelationReference">;
+/** Decode a Citizen ID, or refuse. */
+export declare const parseCitizenId: (value: string, field?: string) => CitizenId;
+/** Decode an Application identifier, or refuse. */
+export declare const parseApplicationId: (value: string, field?: string) => ApplicationId;
+/** Decode a Verification Case identifier, or refuse. */
+export declare const parseVerificationCaseId: (value: string, field?: string) => VerificationCaseId;
+/** Decode a Deployment identifier, or refuse. */
+export declare const parseDeploymentId: (value: string, field?: string) => DeploymentId;
+/**
+ * Decode a Piper Platform subject, or refuse.
+ *
+ * Structurally identical to `parseCitizenId` and deliberately kept as its own
+ * function. Two parsers that produce unassignable types is the point: a caller that
+ * has a local subject and needs a Citizen ID has to go and get one from a Percayso ID
+ * session, which is §7.1's rule, and there is nowhere in this package to shortcut it.
+ */
+export declare const parsePiperPlatformSubject: (value: string, field?: string) => PiperPlatformSubject;
+/** Decode a correlation reference, or refuse. */
+export declare const parseCorrelationReference: (value: string, field?: string) => CorrelationReference;
+/**
+ * Decode a canonical Handle, or refuse.
+ *
+ * Refuses anything that is not already canonical — an upper-case letter, a leading or
+ * trailing hyphen, consecutive hyphens, or any character outside §9.1's alphabet.
+ * CANONICALISING is not done here and must not be: NFKC, case folding and the TR39
+ * skeleton are P1-12's, and a second implementation of them is how two spellings of
+ * the same Handle end up in two tables.
+ */
+export declare const parseCanonicalHandle: (value: string, field?: string) => CanonicalHandle;
+/**
+ * Decode a Community email address, or refuse.
+ *
+ * The local part is checked for the same alphabet as a canonical Handle because §9.2
+ * says the initial local part IS one. It is not checked for being any PARTICULAR
+ * Handle: the address is its own identifier from the moment it is assigned, and a
+ * parser that insisted the two still matched would refuse every renamed Handle in the
+ * pillar — the exact breakage §9.2 exists to prevent.
+ */
+export declare const parseCommunityEmailAddress: (value: string, field?: string) => CommunityEmailAddress;
+/**
+ * Decode a display Handle, or refuse.
+ *
+ * Only emptiness and surrounding whitespace are refused. The submitted form is
+ * deliberately permissive — §9.1 stores it precisely BECAUSE it is not the canonical
+ * form — and every rule that narrows it lives with the canonicalisation algorithm in
+ * P1-12.
+ */
+export declare const parseDisplayHandle: (value: string, field?: string) => DisplayHandle;
+/** Read and decode a Citizen ID from a record field. */
+export declare const readCitizenId: (record: Readonly<Record<string, unknown>>, field: string, key: string) => CitizenId;
+/** Read and decode an Application identifier from a record field. */
+export declare const readApplicationId: (record: Readonly<Record<string, unknown>>, field: string, key: string) => ApplicationId;
+/** Read and decode a Verification Case identifier from a record field. */
+export declare const readVerificationCaseId: (record: Readonly<Record<string, unknown>>, field: string, key: string) => VerificationCaseId;

package/dist/ids.js

@@ -0,0 +1,154 @@
+/**
+ * The identifiers of §9 and §15, each branded and each parsed.
+ *
+ * The canon's identifier rules are almost all rules about CONFUSION — which opaque
+ * string may stand in for which other opaque string — and they are the rules this
+ * pillar has already lost twice. CONTEXT.md states three of them outright: a Citizen
+ * ID "is the only identifier that may appear as an assertion subject"; a Piper
+ * Platform subject "identifies a local account… is never evidence of which human is
+ * present and is never the source of a Citizen ID"; a Handle "is never a Citizen ID
+ * and never appears in Cayso Platform's ledger identity".
+ *
+ * Every one of those is a string. Nothing structural tells them apart, so the brand
+ * of `brand.ts` does the telling: they are mutually unassignable, and a function that
+ * asks for a `CitizenId` cannot be handed a `PiperPlatformSubject` however the value
+ * was obtained. That is the half a compiler holds.
+ *
+ * The half a compiler cannot hold is a value that arrived over a wire, which is what
+ * each `parse…` function is for.
+ *
+ * WHAT THE PARSERS DELIBERATELY DO NOT DO
+ *
+ * They do not pin a generated format. §12.2 limits this package to "wire types,
+ * closed error/status unions and a thin client only", and how a Citizen ID is
+ * MINTED is the schema's business — P1-3's — not the contract's. What the contract
+ * can honestly say is the shape an opaque identifier has on the wire: printable,
+ * unpunctuated, URL-safe, and therefore incapable of being an email address or a
+ * qualified name. `OPAQUE_IDENTIFIER` admits UUID, ULID, base64url and every other
+ * format P1-3 might choose, and admits none of the values CONTEXT.md says an
+ * identifier is not.
+ *
+ * They also carry no length bound. A bound would be a figure, and this pillar's rule
+ * is that a figure belongs in §12.5's register with its evidence and is read from
+ * configuration. The bound that actually matters to a service is the request-size
+ * limit, which §12.1 puts on the slice that exposes an endpoint (P1-8).
+ */
+import { readString, refuseValue } from "./parse.js";
+/**
+ * The shape of an opaque identifier on the wire.
+ *
+ * URL-safe and unpunctuated, which is what makes it an identifier rather than a
+ * value with structure somebody might read. It excludes `@`, so no email address can
+ * ever be decoded as a Citizen ID; it excludes whitespace and `.`, `/` and `:`, so no
+ * name, address or qualified reference can either.
+ */
+const OPAQUE_IDENTIFIER = /^[A-Za-z0-9_-]+$/;
+/**
+ * The canonical Handle alphabet of §9.1: `a-z`, `0-9` and `-`, starting and ending
+ * alphanumeric, with no consecutive hyphens.
+ *
+ * §9.1's LENGTH BOUNDS ARE NOT RESTATED HERE. They are canon figures, the canon is
+ * the one place a figure is written down, and the algorithm they belong to — NFKC,
+ * case folding, the TR39 confusable skeleton, the reserved set and the versioned
+ * policy that governs all of it — is slice P1-12's, not this package's. What this
+ * parser is for is narrower and worth having on its own: it refuses a value that is
+ * NOT ALREADY CANONICAL, so a display form can never be decoded into a field that
+ * means the canonical one.
+ */
+const CANONICAL_HANDLE = /^[a-z0-9](?:-?[a-z0-9])*$/;
+/**
+ * The Community email domains of §9: `percayso.me` for Citizens, `percayso.biz` for
+ * Organisations. Both are confirmed and owned by Percayso.
+ *
+ * Organisation addresses are not phase-one work — §9 says so — and the domain is
+ * listed anyway because the union is the contract. A closed union that omitted a
+ * domain the canon confirms would be a union the Organisation slice has to break.
+ */
+export const COMMUNITY_EMAIL_DOMAINS = Object.freeze([
+    "percayso.me",
+    "percayso.biz",
+]);
+const parseOpaque = (value, field) => {
+    if (!OPAQUE_IDENTIFIER.test(value)) {
+        refuseValue(field, "must be an opaque identifier: unreserved URL characters only, and therefore never an address, a name or a qualified reference");
+    }
+    return value;
+};
+/** Decode a Citizen ID, or refuse. */
+export const parseCitizenId = (value, field = "citizenId") => parseOpaque(value, field);
+/** Decode an Application identifier, or refuse. */
+export const parseApplicationId = (value, field = "applicationId") => parseOpaque(value, field);
+/** Decode a Verification Case identifier, or refuse. */
+export const parseVerificationCaseId = (value, field = "verificationCaseId") => parseOpaque(value, field);
+/** Decode a Deployment identifier, or refuse. */
+export const parseDeploymentId = (value, field = "deploymentId") => parseOpaque(value, field);
+/**
+ * Decode a Piper Platform subject, or refuse.
+ *
+ * Structurally identical to `parseCitizenId` and deliberately kept as its own
+ * function. Two parsers that produce unassignable types is the point: a caller that
+ * has a local subject and needs a Citizen ID has to go and get one from a Percayso ID
+ * session, which is §7.1's rule, and there is nowhere in this package to shortcut it.
+ */
+export const parsePiperPlatformSubject = (value, field = "piperPlatformSubject") => parseOpaque(value, field);
+/** Decode a correlation reference, or refuse. */
+export const parseCorrelationReference = (value, field = "correlationReference") => parseOpaque(value, field);
+/**
+ * Decode a canonical Handle, or refuse.
+ *
+ * Refuses anything that is not already canonical — an upper-case letter, a leading or
+ * trailing hyphen, consecutive hyphens, or any character outside §9.1's alphabet.
+ * CANONICALISING is not done here and must not be: NFKC, case folding and the TR39
+ * skeleton are P1-12's, and a second implementation of them is how two spellings of
+ * the same Handle end up in two tables.
+ */
+export const parseCanonicalHandle = (value, field = "canonicalHandle") => {
+    if (!CANONICAL_HANDLE.test(value)) {
+        refuseValue(field, "must already be canonical per §9.1: lower-case ASCII letters, digits and single interior hyphens, starting and ending alphanumeric. Canonicalisation belongs to P1-12 and is not performed here");
+    }
+    return value;
+};
+/**
+ * Decode a Community email address, or refuse.
+ *
+ * The local part is checked for the same alphabet as a canonical Handle because §9.2
+ * says the initial local part IS one. It is not checked for being any PARTICULAR
+ * Handle: the address is its own identifier from the moment it is assigned, and a
+ * parser that insisted the two still matched would refuse every renamed Handle in the
+ * pillar — the exact breakage §9.2 exists to prevent.
+ */
+export const parseCommunityEmailAddress = (value, field = "communityEmailAddress") => {
+    const at = value.indexOf("@");
+    if (at === -1 || value.indexOf("@", at + 1) !== -1) {
+        refuseValue(field, "must contain exactly one @");
+    }
+    const local = value.slice(0, at);
+    const domain = value.slice(at + 1);
+    if (!CANONICAL_HANDLE.test(local)) {
+        refuseValue(`${field}.localPart`, "must use §9.1's canonical alphabet, which is the alphabet the address was first assigned from");
+    }
+    if (!COMMUNITY_EMAIL_DOMAINS.includes(domain)) {
+        refuseValue(`${field}.domain`, `must be one of the ${COMMUNITY_EMAIL_DOMAINS.length} Community domains of §9`);
+    }
+    return value;
+};
+/**
+ * Decode a display Handle, or refuse.
+ *
+ * Only emptiness and surrounding whitespace are refused. The submitted form is
+ * deliberately permissive — §9.1 stores it precisely BECAUSE it is not the canonical
+ * form — and every rule that narrows it lives with the canonicalisation algorithm in
+ * P1-12.
+ */
+export const parseDisplayHandle = (value, field = "displayHandle") => {
+    if (value.trim() === "" || value.trim() !== value) {
+        refuseValue(field, "must be non-empty and carry no surrounding whitespace");
+    }
+    return value;
+};
+/** Read and decode a Citizen ID from a record field. */
+export const readCitizenId = (record, field, key) => parseCitizenId(readString(record, field, key), `${field}.${key}`);
+/** Read and decode an Application identifier from a record field. */
+export const readApplicationId = (record, field, key) => parseApplicationId(readString(record, field, key), `${field}.${key}`);
+/** Read and decode a Verification Case identifier from a record field. */
+export const readVerificationCaseId = (record, field, key) => parseVerificationCaseId(readString(record, field, key), `${field}.${key}`);

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `@percayso/identity-contracts` — the identity vocabulary this pillar publishes.
+ *
+ * WHAT IS HERE. The identifiers of §9 and §15, the closed lifecycle states of §5.2
+ * and §11.3, the closed refusal union, the evidence vocabulary of §8.2 and §8.3, and
+ * the assertion request and issuance shapes. Every one of them is a WIRE type with a
+ * decoder beside it. Where the canon states an invariant, it is written twice: once
+ * as a type that cannot express the violation, and once as a value the decoder
+ * refuses.
+ *
+ * WHAT IS DELIBERATELY NOT HERE. No server, no policy engine, no verifier, no
+ * database access and no figures. The thin client ships from the separate `./client`
+ * entry point so that a consumer wanting only the types does not pay for it, and so
+ * that the packaging test can prove the type surface stands alone.
+ *
+ * NOTHING RUNS ON IMPORT. Importing this module defines types, freezes a handful of
+ * tables and nothing else: no connection, no environment read, no clock. The rule is
+ * this repository's and the sibling's alike, and it is what makes a contract package
+ * safe to depend on from anywhere.
+ *
+ * NO RUNTIME DEPENDENCY. `@cayso/contracts` appears here only in type position.
+ * Assertion, assurance and operation types are IMPORTED from it and never restated,
+ * and the package manifest records it as a peer dependency, exact-pinned; the
+ * package README explains why that shape rather than either of the other two. The
+ * built JavaScript names it nowhere, and `packaging.test.ts` asserts so against the
+ * real tarball.
+ */
+export type { Branded } from "./brand.js";
+export { ContractParseError, readArray, readBoolean, readClosedRecord, readMember, readObject, readString, refuseValue, } from "./parse.js";
+export { COMMUNITY_EMAIL_DOMAINS, parseApplicationId, parseCanonicalHandle, parseCitizenId, parseCommunityEmailAddress, parseCorrelationReference, parseDeploymentId, parseDisplayHandle, parsePiperPlatformSubject, parseVerificationCaseId, readApplicationId, readCitizenId, readVerificationCaseId, } from "./ids.js";
+export type { ApplicationId, CanonicalHandle, CitizenId, CommunityEmailAddress, CommunityEmailDomain, CorrelationReference, DeploymentId, DisplayHandle, PiperPlatformSubject, VerificationCaseId, } from "./ids.js";
+export { APPLICATION_STATES, APPLICATION_TRANSITIONS, isApplicationTransitionPermitted, isRetryable, isTerminalApplicationState, parseApplicationState, parseApplicationSummary, parseApprovedApplication, } from "./application.js";
+export type { ApplicationState, ApplicationSummary, ApprovedApplication, } from "./application.js";
+export { CITIZEN_STATUSES, parseCitizenCreation, parseCitizenNames, parseCitizenRecord, parseCitizenStatus, } from "./citizen.js";
+export type { CitizenCreation, CitizenNames, CitizenRecord, CitizenStatus, Personhood, } from "./citizen.js";
+export { PROVISIONING_STATES, PROVISIONING_TRANSITIONS, isProvisioningTransitionPermitted, parseCaysoConfirmation, parseProvisioningCoordination, } from "./provisioning.js";
+export type { CaysoConfirmation, ProvisioningCoordination, ProvisioningState, } from "./provisioning.js";
+export { VERIFICATION_OUTCOMES, evidenceSupportsMethod, methodSupportedByEvidence, parseEvidencePolicyVersion, parseEvidenceRoute, parseIdentityEvidenceFacts, parseVerificationCaseSummary, parseVerificationOutcome, } from "./evidence.js";
+export type { EvidencePolicyVersion, EvidenceRoute, IdentityEvidenceFacts, MethodSupportedBy, VerificationCaseSummary, VerificationOutcome, } from "./evidence.js";
+export { REFUSAL_CODES, isAppealable, parseRefusal } from "./refusal.js";
+export type { ContractResult, Refusal, RefusalCode } from "./refusal.js";
+export { ASSERTION_OPERATIONS, parseAssertionIssuanceRecord, parseAssertionRequest, } from "./assertion.js";
+export type { AssertionIssuanceRecord, AssertionOperation, AssertionRequest, AssertionScope, IssuanceOutcome, } from "./assertion.js";

package/dist/index.js

@@ -0,0 +1,35 @@
+/**
+ * `@percayso/identity-contracts` — the identity vocabulary this pillar publishes.
+ *
+ * WHAT IS HERE. The identifiers of §9 and §15, the closed lifecycle states of §5.2
+ * and §11.3, the closed refusal union, the evidence vocabulary of §8.2 and §8.3, and
+ * the assertion request and issuance shapes. Every one of them is a WIRE type with a
+ * decoder beside it. Where the canon states an invariant, it is written twice: once
+ * as a type that cannot express the violation, and once as a value the decoder
+ * refuses.
+ *
+ * WHAT IS DELIBERATELY NOT HERE. No server, no policy engine, no verifier, no
+ * database access and no figures. The thin client ships from the separate `./client`
+ * entry point so that a consumer wanting only the types does not pay for it, and so
+ * that the packaging test can prove the type surface stands alone.
+ *
+ * NOTHING RUNS ON IMPORT. Importing this module defines types, freezes a handful of
+ * tables and nothing else: no connection, no environment read, no clock. The rule is
+ * this repository's and the sibling's alike, and it is what makes a contract package
+ * safe to depend on from anywhere.
+ *
+ * NO RUNTIME DEPENDENCY. `@cayso/contracts` appears here only in type position.
+ * Assertion, assurance and operation types are IMPORTED from it and never restated,
+ * and the package manifest records it as a peer dependency, exact-pinned; the
+ * package README explains why that shape rather than either of the other two. The
+ * built JavaScript names it nowhere, and `packaging.test.ts` asserts so against the
+ * real tarball.
+ */
+export { ContractParseError, readArray, readBoolean, readClosedRecord, readMember, readObject, readString, refuseValue, } from "./parse.js";
+export { COMMUNITY_EMAIL_DOMAINS, parseApplicationId, parseCanonicalHandle, parseCitizenId, parseCommunityEmailAddress, parseCorrelationReference, parseDeploymentId, parseDisplayHandle, parsePiperPlatformSubject, parseVerificationCaseId, readApplicationId, readCitizenId, readVerificationCaseId, } from "./ids.js";
+export { APPLICATION_STATES, APPLICATION_TRANSITIONS, isApplicationTransitionPermitted, isRetryable, isTerminalApplicationState, parseApplicationState, parseApplicationSummary, parseApprovedApplication, } from "./application.js";
+export { CITIZEN_STATUSES, parseCitizenCreation, parseCitizenNames, parseCitizenRecord, parseCitizenStatus, } from "./citizen.js";
+export { PROVISIONING_STATES, PROVISIONING_TRANSITIONS, isProvisioningTransitionPermitted, parseCaysoConfirmation, parseProvisioningCoordination, } from "./provisioning.js";
+export { VERIFICATION_OUTCOMES, evidenceSupportsMethod, methodSupportedByEvidence, parseEvidencePolicyVersion, parseEvidenceRoute, parseIdentityEvidenceFacts, parseVerificationCaseSummary, parseVerificationOutcome, } from "./evidence.js";
+export { REFUSAL_CODES, isAppealable, parseRefusal } from "./refusal.js";
+export { ASSERTION_OPERATIONS, parseAssertionIssuanceRecord, parseAssertionRequest, } from "./assertion.js";