@hcs-witness/verify 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+Toutes les modifications notables de ce projet sont consignées ici.
+Le format suit [Keep a Changelog](https://keepachangelog.com/fr/1.1.0/)
+et le projet respecte [Semantic Versioning](https://semver.org/lang/fr/).
+
+## [1.0.0] - 2026-XX-XX
+
+Première publication publique. Succède au paquet interne privé
+`@gateguard/verify` (0.2.0) — même format de preuve, mêmes vérifications.
+
+### Ajouté
+
+- Vérification hors ligne de preuves HCS Witness v1 et v2 :
+  signatures ES256 (P-256, low-S) et ML-DSA-65 (contexte
+  `gateguard:proof:v1`), fenêtre de validité des clés, plafond
+  `signals`, horodatages cohérents.
+- Vérification d'ancrage : inclusion Merkle RFC 6962 (DTR),
+  lecture des fichiers OpenTimestamps embarqués (attestation Bitcoin,
+  calendriers en attente) — aucun accès réseau.
+- `checkActionBinding` : lie la preuve à l'action, au contexte (JCS)
+  et au texte affiché (NFC) avant exécution.
+- CLI `hcs-witness-verify <proof.json> --keys <keys.json>
+[--now <rfc3339>] [--json]`.
+- Schémas JSON exportés (`proofSchema`, `unsignedProofSchema`,
+  `keysetSchema`) et gardes de type (`isProof`, `isUnsignedProof`,
+  `isKeyset`) — sans dépendance de validation.
+
+### Sécurité / dépendances
+
+- Dépendances d'exécution réduites à deux : `@noble/post-quantum` et
+  `canonicalize` (épinglées en version exacte).
+- ES256 et SHA-256 passent par `node:crypto` ; le validateur TypeBox
+  interne est remplacé par un évaluateur JSON Schema dédié.
+
+[1.0.0]: https://github.com/hcs-witness/verify/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 AI Solution
+
+   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.

package/README.md

@@ -1,3 +1,148 @@
-# Temporary Holding Version
+# @hcs-witness/verify
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Offline verification library and CLI for **HCS Witness** proofs —
+vérificateur hors ligne des preuves HCS Witness.
+
+A proof is a signed document attesting that a human approved (or
+refused) a critical action. This package verifies such proofs **without
+any network access**: signatures (ES256 + ML-DSA-65), key validity
+windows, Merkle inclusion, and embedded OpenTimestamps anchors.
+
+Runtime dependencies: two — `@noble/post-quantum` and `canonicalize`,
+pinned to exact versions. ES256 and SHA-256 go through `node:crypto`.
+
+## Installation
+
+```bash
+npm install --global @hcs-witness/verify   # CLI
+npm install @hcs-witness/verify            # library
+```
+
+Requires Node.js **≥ 22** — no Node-24-only API is used at runtime
+(tested in CI on Node 22 and 24; releases are built on Node 24).
+
+## Verify a proof (CLI)
+
+```bash
+hcs-witness-verify <proof.json> --keys <keys.json> [--now <rfc3339>] [--json]
+```
+
+- `<proof.json>`: a proof document (`proofs/<proof_id>.json` in an audit
+  export, or `GET /v1/proofs/<id>` output).
+- `--keys`: the public keyset (`keys.json` in an export, or
+  `/.well-known/hcs-keys.json` on the issuing service).
+- `--now`: reference time for expiry checks (default: none).
+- Exit code: `0` valid, `1` invalid, `2` usage error.
+
+```console
+$ hcs-witness-verify proofs/ggp_01JZ….json --keys keys.json
+proof_id: ggp_01JZFXANCH0REDPR00FV2TEST9
+status: VALID
+presence: measured, not yet rated (challenge: numeric, synced passkey)
+anchor: merkle inclusion OK
+anchor: bitcoin block 915042 (attested by the .ots file)
+note: block confirmation is to be done with a node or an explorer
+```
+
+## Library usage
+
+```ts
+import {
+  verifyProof,
+  verifyAnchor,
+  checkActionBinding,
+} from "@hcs-witness/verify";
+
+const result = verifyProof(proofJson, keysetJson, { now: new Date() });
+// → { valid: boolean, errors: VerifyErrorCode[], proof_id? }
+
+const anchor = verifyAnchor(proofJson);
+// → { present, inclusion, otsMatchesRoot, bitcoinBlockHeight, pendingCalendars }
+
+// Before executing the attested action — mandatory binding check:
+const binding = checkActionBinding(proofJson, {
+  action: "armoury.firearm.release",
+  context, // same object sent with the approval request
+  displayText, // exact text shown to the human (NFC applied)
+});
+```
+
+The exported JSON Schemas (`proofSchema`, `unsignedProofSchema`,
+`keysetSchema`) are plain JSON Schema documents — usable with any
+validator (e.g. ajv) — and `isProof` / `isUnsignedProof` / `isKeyset`
+are dependency-free type guards.
+
+## Verify the package provenance
+
+Every release is published from GitHub Actions via **npm trusted
+publishing (OIDC)** with Sigstore provenance — no access token exists
+anywhere.
+
+```bash
+npm audit signatures   # in a project that depends on @hcs-witness/verify
+```
+
+The package page on [npmjs.com/package/@hcs-witness/verify](https://www.npmjs.com/package/@hcs-witness/verify)
+shows the provenance badge linking back to the exact GitHub Actions run
+and commit in [hcs-witness/verify](https://github.com/hcs-witness/verify).
+
+## Verify a Bitcoin anchor
+
+If the proof carries `anchor.ots` (base64 OpenTimestamps file attesting
+the Merkle root), offline parsing is included; confirming the block on
+the blockchain is done with the public OpenTimestamps tooling:
+
+```bash
+# save anchors/<batch_id>.ots from the audit export, then:
+ots verify anchors/<batch_id>.ots
+```
+
+`verifyAnchor` reports `bitcoinBlockHeight` when the .ots embeds a
+Bitcoin attestation, and `pendingCalendars` when it is still awaiting
+confirmation.
+
+## Proof format and compatibility
+
+- Format versions `v: 1` and `v: 2` (the `presence` block appeared in
+  v2) are supported. The package version is **independent** of the
+  proof-format version.
+- A new verifier release always keeps verifying all previously
+  published format versions; dropping a format version requires a
+  major release announced ≥ 12 months in advance.
+- The ML-DSA context string `gateguard:proof:v1` and the JCS (RFC 8785)
+  canonicalization are part of the signed format — they are immutable
+  and retained verbatim for compatibility.
+- The `presence` block is signed but **never** used for cryptographic
+  validity; it is reported for information only.
+
+## Security
+
+Vulnerability reports: **contact@ia-solution.fr** — see
+[SECURITY.md](SECURITY.md). This package performs **zero network
+access**: any network I/O is a security defect.
+
+---
+
+## Français
+
+`@hcs-witness/verify` nécessite Node.js **≥ 22** et vérifie hors ligne les preuves HCS Witness :
+signatures ES256 (P-256, low-S) et ML-DSA-65, fenêtre de validité des
+clés, inclusion Merkle et ancrage OpenTimestamps — **sans aucun accès
+réseau**.
+
+```bash
+npm install --global @hcs-witness/verify
+hcs-witness-verify proofs/<proof_id>.json --keys keys.json
+```
+
+- Codes de sortie : `0` valide, `1` invalide, `2` erreur d'usage.
+- Provenance : `npm audit signatures` + badge de provenance sur la page
+  npm ; publication par trusted publishing OIDC depuis GitHub Actions,
+  sans aucun jeton.
+- Ancrage Bitcoin : `verifyAnchor` vérifie l'inclusion Merkle et lit le
+  fichier `.ots` embarqué ; la confirmation du bloc se fait avec les
+  outils publics OpenTimestamps (`ots verify anchors/<batch_id>.ots`).
+- Compatibilité : les formats `v:1` et `v:2` restent vérifiables ; le
+  contexte signé `gateguard:proof:v1` et la canonicalisation JCS sont
+  immuables.
+- Sécurité : signalement à **contact@ia-solution.fr** (cf. SECURITY.md).

package/bin/hcs-witness-verify.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/cli.js";

package/dist/anchor.d.ts

@@ -0,0 +1,20 @@
+export interface AnchorResult {
+    /** La preuve porte un champ anchor bien formé. */
+    readonly present: boolean;
+    /** Inclusion Merkle feuille → racine vérifiée hors ligne. */
+    readonly inclusion: boolean;
+    /** Le fichier .ots atteste bien la racine Merkle. */
+    readonly otsMatchesRoot: boolean | undefined;
+    /** Hauteur de bloc attestée par l'attestation Bitcoin du .ots. */
+    readonly bitcoinBlockHeight: number | undefined;
+    /** URIs des calendriers en attestation « pending ». */
+    readonly pendingCalendars: readonly string[];
+}
+/**
+ * Vérifie hors ligne l'ancrage d'une preuve : inclusion Merkle de la
+ * feuille (SHA-256(0x00‖SHA-256(signedPayload))) vers merkle_root, puis
+ * lecture du fichier .ots embarqué : sa racine attestée doit égaler
+ * merkle_root ; la hauteur de bloc en est extraite. Aucun réseau.
+ */
+export declare function verifyAnchor(proof: unknown): AnchorResult;
+//# sourceMappingURL=anchor.d.ts.map

package/dist/anchor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchor.d.ts","sourceRoot":"","sources":["../src/anchor.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,YAAY;IAC3B,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,qDAAqD;IACrD,QAAQ,CAAC,cAAc,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7C,kEAAkE;IAClE,QAAQ,CAAC,kBAAkB,EAAE,MAAM,GAAG,SAAS,CAAC;IAChD,uDAAuD;IACvD,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C;AAoBD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,CA2DzD"}

package/dist/anchor.js

@@ -0,0 +1,82 @@
+import { merkleLeafHash, verifyMerkleInclusion } from "./merkle.js";
+import { allAttestations, bitcoinBlockHeight, parseOtsFile } from "./ots.js";
+import { isProof, signedPayload } from "./schema.js";
+function b64ToBytes(b64) {
+    try {
+        return Uint8Array.from(Buffer.from(b64, "base64"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function hexToBytes(hex) {
+    return Uint8Array.from(hex.match(/../g) ?? [], (pair) => Number.parseInt(pair, 16));
+}
+function bytesEq(a, b) {
+    return a.length === b.length && a.every((x, i) => x === b.at(i));
+}
+/**
+ * Vérifie hors ligne l'ancrage d'une preuve : inclusion Merkle de la
+ * feuille (SHA-256(0x00‖SHA-256(signedPayload))) vers merkle_root, puis
+ * lecture du fichier .ots embarqué : sa racine attestée doit égaler
+ * merkle_root ; la hauteur de bloc en est extraite. Aucun réseau.
+ */
+export function verifyAnchor(proof) {
+    const empty = {
+        present: false,
+        inclusion: false,
+        otsMatchesRoot: undefined,
+        bitcoinBlockHeight: undefined,
+        pendingCalendars: [],
+    };
+    if (!isProof(proof)) {
+        return empty;
+    }
+    const p = proof;
+    const anchor = p.anchor;
+    if (anchor === undefined) {
+        return empty;
+    }
+    const root = hexToBytes(anchor.merkle_root);
+    const leaf = merkleLeafHash(signedPayload(p));
+    const path = anchor.path.map(hexToBytes);
+    // leaf_count n'est pas dans la preuve : on le recherche. Un chemin de
+    // longueur L ne peut couvrir qu'un lot dont la taille est dans
+    // ]index, index + 2^L] ; la vérification n'aboutit que pour la vraie.
+    let inclusion = false;
+    const maxCount = anchor.leaf_index + 2 ** path.length;
+    for (let count = anchor.leaf_index + 1; count <= maxCount; count += 1) {
+        if (verifyMerkleInclusion(leaf, anchor.leaf_index, count, path, root)) {
+            inclusion = true;
+            break;
+        }
+    }
+    let otsMatchesRoot;
+    let height;
+    const pending = [];
+    if (anchor.ots !== undefined) {
+        const bytes = b64ToBytes(anchor.ots);
+        try {
+            if (bytes === undefined)
+                throw new Error("bad base64");
+            const ots = parseOtsFile(bytes);
+            otsMatchesRoot = bytesEq(ots.fileDigest, root);
+            height = bitcoinBlockHeight(ots.timestamp);
+            for (const { attestation } of allAttestations(ots.timestamp)) {
+                if (attestation.kind === "pending" && attestation.uri !== undefined) {
+                    pending.push(attestation.uri);
+                }
+            }
+        }
+        catch {
+            otsMatchesRoot = false;
+        }
+    }
+    return {
+        present: true,
+        inclusion,
+        otsMatchesRoot,
+        bitcoinBlockHeight: height,
+        pendingCalendars: pending,
+    };
+}

package/dist/base64.d.ts

@@ -0,0 +1,3 @@
+export declare function bytesToB64url(bytes: Uint8Array): string;
+export declare function b64urlToBytes(input: string): Uint8Array | null;
+//# sourceMappingURL=base64.d.ts.map

package/dist/base64.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64.d.ts","sourceRoot":"","sources":["../src/base64.ts"],"names":[],"mappings":"AAOA,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAkBvD;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CA0B9D"}

package/dist/base64.js

@@ -0,0 +1,46 @@
+const B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+function rev(ch) {
+    // Callers guarantee input matches /^[A-Za-z0-9_-]*$/ first.
+    return B64.indexOf(ch);
+}
+export function bytesToB64url(bytes) {
+    let out = "";
+    for (let i = 0; i < bytes.length; i += 3) {
+        const b0 = bytes.at(i) ?? 0;
+        const has1 = i + 1 < bytes.length;
+        const has2 = i + 2 < bytes.length;
+        const b1 = bytes.at(i + 1) ?? 0;
+        const b2 = bytes.at(i + 2) ?? 0;
+        out += B64.charAt(b0 >> 2);
+        out += B64.charAt(((b0 & 3) << 4) | (b1 >> 4));
+        if (has1) {
+            out += B64.charAt(((b1 & 0x0f) << 2) | (b2 >> 6));
+        }
+        if (has2) {
+            out += B64.charAt(b2 & 0x3f);
+        }
+    }
+    return out;
+}
+export function b64urlToBytes(input) {
+    if (input.length % 4 === 1 || !/^[A-Za-z0-9_-]*$/.test(input)) {
+        return null;
+    }
+    const quad = (a, b, c, d) => (rev(a) << 18) | (rev(b) << 12) | (rev(c) << 6) | rev(d);
+    const bytes = [];
+    const fullGroups = Math.floor(input.length / 4);
+    for (let i = 0; i < fullGroups; i += 1) {
+        const n = quad(input.charAt(i * 4), input.charAt(i * 4 + 1), input.charAt(i * 4 + 2), input.charAt(i * 4 + 3));
+        bytes.push((n >> 16) & 0xff, (n >> 8) & 0xff, n & 0xff);
+    }
+    const tail = input.slice(fullGroups * 4);
+    if (tail.length === 2) {
+        const n = quad(tail.charAt(0), tail.charAt(1), "A", "A");
+        bytes.push((n >> 16) & 0xff);
+    }
+    else if (tail.length === 3) {
+        const n = quad(tail.charAt(0), tail.charAt(1), tail.charAt(2), "A");
+        bytes.push((n >> 16) & 0xff, (n >> 8) & 0xff);
+    }
+    return Uint8Array.from(bytes);
+}

package/dist/binding.d.ts

@@ -0,0 +1,22 @@
+export type BindingErrorCode = "SCHEMA_INVALID" | "ACTION_MISMATCH" | "CONTEXT_MISMATCH" | "DISPLAY_MISMATCH";
+export interface BindingCheck {
+    /** Action about to be executed, e.g. "armoury.firearm.release". */
+    readonly action: string;
+    /** Same context object that was sent with the approval request. */
+    readonly context: Record<string, unknown>;
+    /** Exact text the human was shown (NFC normalization applied). */
+    readonly displayText: string;
+}
+export interface BindingResult {
+    readonly valid: boolean;
+    readonly errors: readonly BindingErrorCode[];
+}
+/**
+ * Binds the proof to what is about to be executed: the caller MUST run
+ * this check right before performing the action, with the action, the
+ * context and the exact display text. It closes the loop between what
+ * the human saw on the approval page and what the system executes —
+ * a mismatch means the proof was issued for something else.
+ */
+export declare function checkActionBinding(proof: unknown, expected: BindingCheck): BindingResult;
+//# sourceMappingURL=binding.d.ts.map

package/dist/binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../src/binding.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,gBAAgB,GACxB,gBAAgB,GAChB,iBAAiB,GACjB,kBAAkB,GAClB,kBAAkB,CAAC;AAEvB,MAAM,WAAW,YAAY;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,kEAAkE;IAClE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAC9C;AAMD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,YAAY,GACrB,aAAa,CA6Bf"}

package/dist/binding.js

@@ -0,0 +1,38 @@
+import { sha256 } from "./hash.js";
+import { canonicalBytes } from "./jcs.js";
+import { isProof } from "./schema.js";
+function hex(bytes) {
+    return [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+ * Binds the proof to what is about to be executed: the caller MUST run
+ * this check right before performing the action, with the action, the
+ * context and the exact display text. It closes the loop between what
+ * the human saw on the approval page and what the system executes —
+ * a mismatch means the proof was issued for something else.
+ */
+export function checkActionBinding(proof, expected) {
+    if (!isProof(proof)) {
+        return { valid: false, errors: ["SCHEMA_INVALID"] };
+    }
+    const p = proof;
+    const errors = [];
+    if (p.action !== expected.action) {
+        errors.push("ACTION_MISMATCH");
+    }
+    let contextHex;
+    try {
+        contextHex = hex(sha256(canonicalBytes(expected.context)));
+    }
+    catch {
+        contextHex = "";
+    }
+    if (contextHex !== p.context_sha256) {
+        errors.push("CONTEXT_MISMATCH");
+    }
+    const displayHex = hex(sha256(new TextEncoder().encode(expected.displayText.normalize("NFC"))));
+    if (displayHex !== p.display_sha256) {
+        errors.push("DISPLAY_MISMATCH");
+    }
+    return { valid: errors.length === 0, errors };
+}

package/dist/check.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Évaluateur JSON Schema minimal : couvre exactement les constructions
+ * des schémas exportés (type, const, anyOf, properties, required,
+ * additionalProperties, patternProperties, items, pattern, minLength,
+ * minimum). Ce n'est PAS un moteur JSON Schema général — les schémas
+ * sont fixes et internes au format de preuve HCS Witness.
+ */
+export interface JsonSchema {
+    readonly type?: string;
+    readonly const?: unknown;
+    readonly anyOf?: readonly JsonSchema[];
+    readonly properties?: Record<string, JsonSchema>;
+    readonly required?: readonly string[];
+    readonly additionalProperties?: boolean;
+    readonly patternProperties?: Record<string, JsonSchema>;
+    readonly items?: JsonSchema;
+    readonly pattern?: string;
+    readonly minLength?: number;
+    readonly minimum?: number;
+}
+export declare function checkSchema(schema: JsonSchema, value: unknown): boolean;
+//# sourceMappingURL=check.d.ts.map

package/dist/check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../src/check.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACvC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACjD,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IACxC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxD,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAsCD,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CA8DvE"}