@intoco/verifier 0.2.0

package/README.md

@@ -0,0 +1,201 @@
+# @intoco/verifier
+
+Verify **intoco seal signatures** autonomously — no intoco server, no account required.
+
+Works in **Node.js ≥ 22** and **modern browsers**. Pure JS — zero native compilation.
+
+## Installation
+
+```bash
+npm install @intoco/verifier
+```
+
+## Quick start — with automatic key lookup
+
+The typical usage for a third-party verifier. Fetch the JWKS once, cache it, verify offline.
+
+```ts
+import { verifySealAgainstJwks } from '@intoco/verifier';
+
+// Fetch the authority JWKS (cache this — keys rotate rarely)
+const jwks = await fetch('https://intoco.fr/v1/keys').then(r => r.json());
+
+// Fetch the seal you want to verify.
+// `<jeton>` is an EPHEMERAL monstration token: a pole of the ato mints it when they show
+// the seal (typically encoded in a QR code on their own screen), and it dies within ~90
+// seconds. There is no durable URL for a seal — that is deliberate.
+// For a durable, opposable artefact, use the attestation at /p/:code instead.
+const { payload, signature } = await fetch('https://intoco.fr/v1/monstrations/<jeton>')
+  .then(r => r.json());
+
+const result = await verifySealAgainstJwks({ seal_payload: payload, signature, jwks });
+
+if (result.verdict === 'valid') {
+  if (result.key_validity === 'expired') {
+    console.warn('Seal was signed with a now-retired key — still cryptographically valid');
+  }
+  if (result.key_validity === 'unknown') {
+    console.warn('Server does not report this key\'s validity window — see "Key validity window" below');
+  }
+  console.log('Valid seal');
+  console.log('  ato_id     :', result.ato_id);
+  console.log('  state      :', result.sealed_state);
+  console.log('  sealed at  :', result.sealed_at);
+  console.log('  sealed by  :', result.sealed_by);
+} else if (result.verdict === 'invalid') {
+  // The cryptography spoke: a real mismatch was detected.
+  console.error('FRAUD DETECTED — reason:', result.reason);
+  // 'PAYLOAD_MISMATCH'   → payload was tampered after signing
+  // 'INVALID_SIGNATURE'  → signature bytes are malformed
+} else {
+  // 'unverifiable' — the cryptography was never reached. This package simply lacks
+  // what it needs to judge. NOT an accusation — see "Three verdicts" below.
+  console.warn('Cannot verify — reason:', result.reason);
+  // 'UNKNOWN_SPEC_VERSION' → spec_version is not in ACCEPTED_SPEC_VERSIONS
+  // 'MISSING_REQUIRED_FIELD' → a required SealPayload field is absent
+  // 'KEY_NOT_FOUND'       → key_id in payload not present in JWKS
+  // 'INVALID_JWKS'        → JWKS structure is invalid
+}
+```
+
+## Low-level — supply the public key directly
+
+Use this when you already have the matching public key (e.g. from a local archive).
+
+```ts
+import { verifySeal } from '@intoco/verifier';
+
+const result = await verifySeal({
+  seal_payload: payload,
+  signature: seal.signature,
+  authority_public_key: key.public_key, // base64url-encoded Ed25519 public key
+});
+```
+
+## Three verdicts, never two — `valid` / `invalid` / `unverifiable`
+
+Every result carries a `verdict`, not a boolean. The two failure verdicts are **not**
+interchangeable, and this package never collapses one into the other:
+
+- **`invalid`** — the cryptography **spoke**: a real mismatch was detected (a forged or
+  tampered payload, or a malformed signature). This is a finding of fraud.
+- **`unverifiable`** — the cryptography was **never reached**: this package simply lacks
+  what it needs to judge (an unrecognized format, a missing field, a key it wasn't given).
+  Nothing is accused here — the seal may be perfectly genuine.
+
+Confusing the two would mean this package could brand a seal fraudulent when all it
+actually lacked was, say, the right key — a claim it never verified. `unverifiable` is
+never rendered as `invalid`.
+
+## `ato/v1` and `ato/v2` — both accepted
+
+This package accepts `spec_version: 'ato/v1'` **and** `'ato/v2'` — the exact list lives in
+one place, [`ACCEPTED_SPEC_VERSIONS`](./src/index.ts). `ato/v2` was a draft from 2026-08-18
+until it froze on 2026-09-09 (intoco reference implementation, `docs/REGISTRE-ARBITRAGES.md`,
+*« Gel du sceau ato/v2 — sept arbitrages + périmètre »*) — frozen means no field is ever
+added to it again without a new `spec_version` (`ato/v3`). Every seal sealed since
+2026-08-18, `ato/v1` or `ato/v2`, verifies with this package.
+
+### `sealed_by` — raw on `ato/v1`, pseudonymized on `ato/v2`
+
+`sealed_by` identifies the repondant who requested the seal.
+
+- On **`ato/v1`** seals, it is the **raw** repondant id.
+- On **`ato/v2`** seals (since the freeze), it is a **pseudonym** — the same HMAC-derived
+  value used for `chain_snapshot`'s three roles, salted by `ato_id`. Two seals on two
+  different `ato`s never share a pseudonym for the same person; the three roles within one
+  seal remain comparable to each other.
+
+This package never interprets the value either way — it only verifies the signature over
+whatever string the payload carries. Seals already sealed before the freeze keep their raw
+`sealed_by` forever (seals are append-only); only newly sealed `ato/v2` seals carry the
+pseudonym.
+
+### `motif_public` — inside the transitions, not in the payload
+
+`transitions_hash` (a required `SealPayload` field, see below) commits to an ordered array
+of transitions. Since the freeze, a transition's public motif (`motif_public` — e.g. a
+témoin relève or replacement, written only on a `soumis → engagé` transition) is included
+in that commitment when present, the same optional-field regime as `reason_hash`: a
+transition without a motif hashes exactly as it did before this field existed. This
+package never sees the raw transitions array — it treats `transitions_hash` as an opaque
+committed value and verifies only that the **signature** covers it. Whether that hash
+truly reflects the underlying transitions is a server-side concern (the intoco reference
+implementation recomputes and compares it — see its `SceauService.getPublicView`), not
+something this package checks.
+
+## Key validity window — `key_validity`, three verdicts, not two
+
+`valid_until` is **optional** on every key served by `GET /v1/keys`. Its absence is not a claim that the key is still valid — it means the server has not reported an end date. This package never collapses "we don't know" into "not expired": `key_validity` is `'valid' | 'expired' | 'unknown'`, computed purely from `valid_until`.
+
+**As of 2026-09, the intoco reference implementation's production deployment emits `valid_until: undefined` for every key** — the server-side environment variable that would populate it, `INTOCO_AUTHORITY_KEY_VALID_UNTIL`, is not yet set on Railway (it stays optional and absent until the operator configures a key rotation deadline; see `src/config.ts` in the reference implementation). **Every seal verified against the live production JWKS today therefore reads `key_validity: 'unknown'`, never `'valid'`** — that is correct, not a bug: nobody has yet declared when the current key stops being valid.
+
+## Failure reasons, by verdict
+
+| Verdict | Reason | Meaning |
+|---|---|---|
+| `invalid` | `PAYLOAD_MISMATCH` | Signature is well-formed but doesn't match — payload was tampered |
+| `invalid` | `INVALID_SIGNATURE` | Signature or public key bytes are malformed (wrong length, bad base64url) |
+| `unverifiable` | `UNKNOWN_SPEC_VERSION` | `spec_version` is not in `ACCEPTED_SPEC_VERSIONS` — this verifier cannot handle it |
+| `unverifiable` | `MISSING_REQUIRED_FIELD` | A required `SealPayload` field is `null` or `undefined` |
+| `unverifiable` | `KEY_NOT_FOUND` | `seal_payload.public_key_id` not found in the provided JWKS (`verifySealAgainstJwks` only) |
+| `unverifiable` | `INVALID_JWKS` | `jwks.keys` is missing or not an array (`verifySealAgainstJwks` only) |
+
+## How verification works
+
+1. **`spec_version` check** — must be in `ACCEPTED_SPEC_VERSIONS` (`unverifiable` otherwise)
+2. **Required field check** — all 11 required `SealPayload` fields must be present
+3. **RFC 8785 canonicalization** — the payload is serialized deterministically (same algorithm used by the intoco authority when signing)
+4. **Ed25519 verify** — the signature is verified against the canonical bytes using `@noble/ed25519`
+
+A seal verified as `verdict: 'valid'` guarantees:
+- The payload has not been modified since the intoco authority signed it
+- The signature was produced by the authority key identified by `public_key_id`
+
+It does **not** guarantee that `transitions_hash` or `content_hash` correctly reflect some
+external document or transition history — this package verifies the *signature*, not a
+confrontation against source material it was never given.
+
+> **Note on `key_validity`**: intoco rotates signing keys periodically. Seals issued before a key's retirement remain valid — `key_validity` lets you surface a warning (`'expired'`) or an honest "don't know" (`'unknown'`) without ever treating historical seals as invalid.
+
+## Types
+
+```ts
+type SealPayload = {
+  spec_version: 'ato/v1' | 'ato/v2';
+  seal_id: string;
+  ato_id: string;
+  sealed_state: 'adressé' | 'engagé' | 'soumis' | 'clôturé';
+  sealed_at: string;       // UTC ISO 8601, millisecond precision
+  sealed_by: string;       // raw on ato/v1, pseudonym (64-hex) on ato/v2 — see above
+  chain_snapshot: { appelant_id: string; porteur_id: string; temoin_id: string };
+  transitions_hash: string; // sha256:<hex>
+  content_hash: string;    // sha256:<hex>
+  espace_id: string;
+  public_key_id: string;
+  attachments_hash?: string[];
+  temoin_attesta?: boolean;   // present only once a soumis→clôturé transition exists
+  pole_reassigned?: boolean;  // present only once a pole relais/replacement has occurred
+};
+
+type VerifyResult =
+  | { verdict: 'valid'; key_id: string; sealed_at: string; sealed_state: string; ato_id: string; sealed_by: string }
+  | { verdict: 'invalid'; reason: 'INVALID_SIGNATURE' | 'PAYLOAD_MISMATCH' }
+  | { verdict: 'unverifiable'; reason: 'UNKNOWN_SPEC_VERSION' | 'MISSING_REQUIRED_FIELD' };
+
+type VerifyAgainstJwksResult =
+  | { verdict: 'valid'; key_validity: 'valid' | 'expired' | 'unknown'; key_id: string; sealed_at: string; sealed_state: string; ato_id: string; sealed_by: string }
+  | { verdict: 'invalid'; reason: 'INVALID_SIGNATURE' | 'PAYLOAD_MISMATCH' }
+  | { verdict: 'unverifiable'; reason: 'UNKNOWN_SPEC_VERSION' | 'MISSING_REQUIRED_FIELD' | 'KEY_NOT_FOUND' | 'INVALID_JWKS' };
+```
+
+## Dependencies
+
+| Package | Purpose |
+|---|---|
+| [`@noble/ed25519`](https://github.com/paulmillr/noble-ed25519) | Pure-JS Ed25519 — no native code, works in browsers |
+| [`canonicalize`](https://github.com/nicktindall/canonicalize) | RFC 8785 JSON canonicalization |
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@intoco/verifier",
+  "version": "0.2.0",
+  "description": "Verify intoco seal signatures autonomously — no intoco server required",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@noble/ed25519": "3.1.0",
+    "canonicalize": "1.0.8"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "vitest": "^1.6.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "keywords": ["intoco", "seal", "ed25519", "verifier", "crypto"]
+}