@percayso/identity-contracts 0.1.0

package/dist/refusal.js

@@ -0,0 +1,116 @@
+/**
+ * The closed refusal union: what a caller is told when this pillar says no, and
+ * everything it is deliberately not told.
+ *
+ * §14.4 sets both halves of the requirement, and they pull against each other. "A
+ * Citizen sees actionable, accessible status and refusal text without exposure of
+ * internal risk signals." Actionable, so a refusal cannot be an opaque failure;
+ * without internal risk signals, so it cannot be the reason. A closed union of codes
+ * satisfies both: the code says what the caller may do next, and the consumer
+ * renders the text — accessibly, in the Citizen's language, at the right reading
+ * level — because a wire string can be none of those things.
+ *
+ * ENFORCED TWICE, AND THE SECOND HALF IS THE INTERESTING ONE.
+ *
+ * `Refusal` has no message field, no detail field and no reason field. There is
+ * nowhere to put prose, so no handler can attach a provider's explanation to a
+ * refusal on its way out; that is the type half, and it is the half that survives a
+ * hurried afternoon. `parseRefusal` is the decoder half and refuses those field
+ * names explicitly rather than by the general unknown-key rule, because a caller
+ * sending `reason` has a provider payload in their hand and needs to be told why it
+ * stops here.
+ *
+ * WHY THE UNION DOES NOT ENUMERATE.
+ *
+ * Several members cover more than one underlying cause on purpose. `not_permitted`
+ * answers both "this is not yours" and "this does not exist", because two codes
+ * would make the refusal an existence oracle for anything addressed by identifier.
+ * `onboarding_result_not_redeemable` covers every one of §14.4's five cases — a
+ * second redemption, another client, expiry, an altered Citizen, a different
+ * transaction verifier — as one member, because telling an attacker WHICH of the
+ * five they tripped is how they work out what to change. The union cannot express
+ * the distinction, which is stronger than a convention that it should not be
+ * exposed.
+ *
+ * A REFUSAL IS NOT A PARSE ERROR. `ContractParseError` in `parse.ts` is detailed
+ * because it is private to a consumer's own process. A `Refusal` crosses a network
+ * boundary and carries a code and a correlation reference, and nothing else. Joining
+ * them up — returning a parse message to a caller — would leak exactly what §14.4's
+ * disclosure criterion protects.
+ */
+import { parseCorrelationReference } from "./ids.js";
+import { readClosedRecord, readString, refuseValue } from "./parse.js";
+/** Every refusal code. A consumer that must render them all reads this. */
+export const REFUSAL_CODES = Object.freeze([
+    "unauthenticated",
+    "step_up_required",
+    "not_permitted",
+    "state_not_permitted",
+    "input_not_acceptable",
+    "handle_unavailable",
+    "document_already_bound",
+    "evidence_insufficient",
+    "onboarding_result_not_redeemable",
+    "rate_limited",
+    "temporarily_unavailable",
+]);
+/**
+ * The refusals a person may appeal, per §8.6's route.
+ *
+ * `document_already_bound` is here because §14.4 names it: "Reuse of a document
+ * identifier already bound to an active Citizen is refused, and the refusal is
+ * appealable", and §16's R7 says why — a false duplicate refusal permanently
+ * excludes a legitimate person if the appeal cannot override the control itself.
+ * `evidence_insufficient` is here because an appeal is reconsideration of a
+ * decision about evidence.
+ *
+ * The others are not appealable and saying so is not a diminishment: appealing
+ * `rate_limited` is waiting, and appealing `unauthenticated` is signing in. An
+ * Application REJECTION is a lifecycle state (§5.2's `rejected --> under_appeal`)
+ * rather than a refusal code, and its appeal route is that transition.
+ */
+const APPEALABLE_REFUSALS = Object.freeze([
+    "document_already_bound",
+    "evidence_insufficient",
+]);
+/** Whether §8.6's appeal route applies to this refusal. */
+export const isAppealable = (code) => APPEALABLE_REFUSALS.includes(code);
+const REFUSAL_FIELDS = Object.freeze([
+    "refusal",
+    "correlationReference",
+]);
+/**
+ * Fields that would turn a refusal into a disclosure. Refused by name so the
+ * message can say why, rather than reporting an unrecognised key.
+ */
+const DISCLOSING_FIELDS = Object.freeze([
+    "message",
+    "detail",
+    "details",
+    "reason",
+    "internalReason",
+    "providerReason",
+    "riskSignal",
+    "riskSignals",
+    "stack",
+]);
+/** A `Refusal` from a wire value, or a refusal of its own. */
+export const parseRefusal = (value, field = "refusal") => {
+    const record = readClosedRecord(value, field, [
+        ...REFUSAL_FIELDS,
+        ...DISCLOSING_FIELDS,
+    ]);
+    for (const key of Object.keys(record)) {
+        if (DISCLOSING_FIELDS.includes(key)) {
+            refuseValue(`${field}.${key}`, "carries free text or an internal signal. A refusal is a code and a correlation reference; the text is the consumer's to render, accessibly (§14.4)");
+        }
+    }
+    const code = readString(record, field, "refusal");
+    if (!REFUSAL_CODES.includes(code)) {
+        refuseValue(`${field}.refusal`, `must be one of the ${REFUSAL_CODES.length} refusal codes of this contract`);
+    }
+    return {
+        refusal: code,
+        correlationReference: parseCorrelationReference(readString(record, field, "correlationReference"), `${field}.correlationReference`),
+    };
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@percayso/identity-contracts",
+  "version": "0.1.0",
+  "description": "Percayso ID wire types: identifiers, closed lifecycle states, the closed refusal union, the evidence vocabulary and a thin client.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Percayso-Community/identity.platform.git",
+    "directory": "packages/identity-contracts"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "lint": "eslint .",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "@cayso/contracts": "0.6.1"
+  },
+  "devDependencies": {
+    "@cayso/contracts": "0.6.1",
+    "typescript": "6.0.3",
+    "vitest": "5.0.0"
+  }
+}