@aleutian/verification 0.0.0 → 0.7.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 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 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 Aleutian AI
+
+   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

@@ -0,0 +1,485 @@
+# @aleutian/verification
+
+Aleutian AI verification SDK for offline V3 SAR chain entry, anchor, and
+webhook verification. All verification runs offline; no network calls.
+
+## Features
+
+- **V3 SAR chain entry verification** — verify the cryptographic signature on
+  a Data Subject Access Request audit chain entry (`verifyChainEntryV3`,
+  ML-DSA-65 / FIPS 204). Byte-identical to the Go and Python SDKs against
+  shared golden vectors.
+- **Anchor verification** — verify ML-DSA-65 anchor signatures using
+  embedded or supplied public keys (v7 with the FIPS 204 context
+  `aleutian.proof.anchor.v7`, v1–v6 with the empty context).
+- **Chain verification** — verify SHA-512 chain hash integrity for chain
+  formats v4 (leaf hash + chain hash; erased entries recomputed from their
+  leaf hash), v3 and v2, including v2/v3 chains continued in v4.
+- **Anchor binding** — bind v1–v4, v6 and v7 anchors to the entries they
+  cover; v7 anchors by sequence, with the expected subject and predecessor.
+- **Tombstone detection** — validate GDPR deletion markers.
+- **Webhook verification** — verify HMAC-SHA-512 webhook signatures
+  (Node.js only).
+
+## Installation
+
+```bash
+npm install @aleutian/verification
+```
+
+## Quick Start
+
+### Verify a V3 SAR chain entry
+
+The single public verifier:
+
+```typescript
+import {
+  TrustManifestV3,
+  verifyChainEntryV3,
+  type SARFulfilledEntryV3,
+} from "@aleutian/verification";
+
+// 1. Build the trust manifest from your controller's published signing keys.
+const trustManifest = TrustManifestV3.fromMap({
+  "anchor-signer-2026-v1": new Uint8Array([
+    /* 1952 ML-DSA-65 public-key bytes */
+  ]),
+});
+
+// 2. The chain entry your controller signed (snake_case → camelCase mapping
+// happens at JSON-decode time; see the cross-SDK golden vectors for the
+// canonical shape).
+const entry: SARFulfilledEntryV3 = {
+  companyId: "comp_01HK7AAAAAAAAAAAAAAAAAAAAA",
+  entryType: "sar_fulfilled",
+  signingKeyId: "anchor-signer-2026-v1",
+  timestampMs: 1_715_000_000_000,
+  certificateId: "cert_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  fulfillmentKind: "erasure",
+  intentEntryId: "018fa1b3-c4d5-7000-8000-1234567890ab",
+  legalBasis: "art_17_erasure",
+  manifestRoot: "d".repeat(128),
+  requestId: "01HK7BBBBBBBBBBBBBBBBBBBBB",
+  tombstoneCount: 42,
+};
+
+// 3. The signature + content_hash from the BigQuery row (or your
+// controller's published audit feed).
+const signature = new Uint8Array(/* 3309 raw ML-DSA-65 bytes */);
+const contentHash = new Uint8Array(/* 64 raw SHA-512 bytes */);
+
+try {
+  await verifyChainEntryV3(entry, signature, contentHash, trustManifest);
+  console.log("verified");
+} catch (e) {
+  // Branch on the typed error subclass (NOT on err.message — Privacy Inv 4).
+  console.error("verification failed:", (e as Error).name);
+}
+```
+
+The verifier throws one of: `ErrInvalidEntryV3`, `ErrContentHashMismatchV3`,
+`ErrSignatureInvalidV3`, `ErrSignatureMalformedV3`, `ErrUnknownSigningKeyV3`,
+or `ErrPublicKeyMalformedV3`. All extend `ErrInvalidEntryV3` so customers
+can catch broadly or narrowly.
+
+### Operating the verifier safely (M3 — production hygiene)
+
+A few patterns to avoid when deploying this SDK on a public verifier
+endpoint (e.g. `verify.your-company.com`):
+
+- **Do NOT `console.log(entry)` or `console.log(canonical)` in production.**
+  V3 SAR entries carry `requestId` (a per-tenant SAR identifier) and
+  HMAC digests over caller-supplied cleartext. Even though the digests
+  are redacted by `toString` / `toJSON` (the SDK ships this protection
+  for `TenantHMACDigestV3` out of the box), an `entry` object also
+  contains the `requestId` and `timestampMs` pair, which together pin
+  a per-tenant SAR within ~1ms. Log the typed error name instead
+  (`err.name`), never the entry object.
+- **Do NOT mint signing keys in your verifier process.** ML-DSA-65
+  keypairs are produced by Aleutian's KMS, distributed via the trust
+  manifest. A verifier that generates keys locally to "test" signature
+  paths can accidentally publish them or hold them in memory next to
+  user data. Use `TrustManifestV3.fromMap` with bytes you fetched
+  from an authenticated source.
+- **Do NOT echo the bad value in error messages your verifier shows
+  to data subjects.** The SDK never echoes caller input in its own
+  error messages (Privacy Inv 4 — regression-guarded). Preserve this
+  posture in your own catch-block when surfacing errors via UI.
+- **Do branch on the typed error subclass** (`err instanceof
+  ErrContentHashMismatchV3`) rather than parsing `err.message`. The
+  message text is intentionally opaque.
+
+### Verify Chain Export
+
+```typescript
+import {
+  loadAnchor,
+  loadExportedEntries,
+  verifyAnchorLocally,
+  verifyChainOffline,
+  SEED_ANCHOR_HASH,
+} from "@aleutian/verification";
+
+// Load and verify anchor
+const anchor = await loadAnchor("anchor-2026-01-20.json");
+verifyAnchorLocally(anchor); // Throws on failure
+
+// Load and verify chain
+const entries = await loadExportedEntries("export-2026-01.json");
+const result = await verifyChainOffline(entries, {
+  anchor,
+  // For genesis anchors pass SEED_ANCHOR_HASH (or omit; SDK auto-fills).
+  // For mid-chain anchors pass the prior anchor's chainHash here.
+  previousAnchorHash: SEED_ANCHOR_HASH,
+});
+
+if (result.valid) {
+  console.log(`Chain valid: ${result.entriesVerified} entries`);
+} else {
+  console.log(`Chain invalid: ${result.breaks.length} breaks`);
+}
+```
+
+### Verify a v4 chain and bind a v7 anchor
+
+```typescript
+import {
+  bindAnchorV7ToEntries,
+  parseAnchorText,
+  parseEntriesText,
+  verifyAnchorLocally,
+  verifyChainOffline,
+} from "@aleutian/verification";
+
+const entries = parseEntriesText(entriesBytes); // v2, v3 and v4 entries
+const result = await verifyChainOffline(entries);
+// result.erasedFound: erased v4 entries — still recomputed, so still verified.
+// result.entriesNotVerified: entries up to the last v2/v3 tombstone (never verified).
+
+const anchor = parseAnchorText(anchorBytes); // v7: entry_count, start_seq, end_seq are strings
+verifyAnchorLocally(anchor, publicKey);      // context "aleutian.proof.anchor.v7"
+const bind = await bindAnchorV7ToEntries(anchor, entries, { subject: "orders" });
+if (bind.bound && bind.subjectChecked) {
+  // the anchor is about "orders" and binds these entries
+}
+```
+
+v7's sequence numbers and count are JSON strings because they may exceed 2^53;
+`parseAnchorText` and `parseEntriesText` return them as `bigint`, never as a
+rounded `number`. Without `subject`, the result says `subjectChecked: false`.
+
+### Verify a proof sink export bundle
+
+A bundle (`aleutian.proof.bundle.v1` or `aleutian.proof.bundle.v2`, proof's
+`bundle-format.md`) is a sink's evidence exported so that someone else can
+check it without the sink, the writer, or proof's code. This verifier was
+written from the spec alone and is held to the shared `bundle_v1_vectors.json`
+and `bundle_v2_vectors.json`. Both formats produce the same
+`aleutian.proof.bundle-result.v1`; v2 (proof v0.5.0) carries chain format v4
+entries, v7 checkpoints and `record.v2` signatures. **Trust is yours:** you supply the
+ML-DSA-65 public keys you trust for checkpoints and for record signatures; a
+bundle never adds a key.
+
+```sh
+aleutian-verify verify-proof-bundle bundle.json \
+    --checkpoint-key checkpoint.pub --record-key record.pub [--json]
+```
+
+| Exit | Meaning |
+|---|---|
+| 0 | `ok`: no problem, and every entry is authenticated by a key you trust |
+| 1 | `failed`: at least one problem |
+| 2 | usage: bad arguments, a missing or unreadable file, an invalid key file |
+| 3 | the bundle is unreadable |
+| 4 | `unauthenticated`: consistent, but provenance is not established |
+| 5 | an internal error in the verifier: never a verdict on the bundle |
+
+`--json` prints exactly the `aleutian.proof.bundle-result.v1` result. Key files
+are the PEM files `proof keygen` and `proof sink init` write. Without any key
+the best possible verdict is `unauthenticated`: chain hashes need no key, so
+anyone can fabricate a chain whose hashes recompute.
+
+A pass does **not** prove that the bundle holds every chain, that a chain is
+complete to its end, or anything against a writer who controls the evidence and
+every key you trust (bundle-format §1). Output never prints a bundle value
+other than a valid chain id.
+
+```typescript
+import { parseProofPublicKeyFile, verifyProofBundle } from "@aleutian/verification";
+
+const result = await verifyProofBundle(bundleBytes, {
+  checkpointKeys: [parseProofPublicKeyFile(checkpointPemBytes)],
+  recordKeys: [],
+});
+if (result.readable && result.verdict === "ok") {
+  // every entry authenticated by a checkpoint key you trust
+}
+```
+
+The library API is browser-safe.
+
+### Verify Webhook (Node.js)
+
+```typescript
+import express from "express";
+import { isValidWebhook } from "@aleutian/verification";
+
+app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
+  if (
+    !isValidWebhook(
+      req.headers["x-aleutian-signature"] as string,
+      req.body,
+      process.env.WEBHOOK_SECRET!
+    )
+  ) {
+    return res.status(401).send("Invalid signature");
+  }
+  // Process webhook...
+  res.sendStatus(200);
+});
+```
+
+## API Reference
+
+### Chain Verification
+
+- `computeChainHash(previousHash, runId, sequenceNum, timestamp, contentHash)` - Compute chain hash (v2)
+- `computeChainHashMs(previousHash, runId, sequenceNum, timestampMs, contentHash)` - Compute hash from Unix milliseconds
+- `computeLeafHashV4(entryId, entryType, contentHash, salt)` - Compute a v4 leaf hash
+- `computeChainHashV4(previousHash, globalSeq, timestamp, leafHash)` - Compute a v4 chain hash
+- `verifyChainOffline(entries, options?)` - Verify complete chain (v2, v3, v4)
+- `parseEntriesText(text)` - Read an entries file strictly
+- `bindAnchorToEntries(anchor, entries, previousAnchorHash)` - Bind a v1–v6 anchor
+- `bindAnchorV7ToEntries(anchor, entries, { subject?, previousAnchorHash? })` - Bind a v7 anchor
+
+### Anchor Verification
+
+- `verifyAnchorLocally(anchor, publicKey?)` - Verify anchor signature (context by declared version)
+- `parseAnchorText(text)` - Read an anchor strictly (format-spec §9.8)
+- `canonicalizeAnchorForVersion(anchor)` - Canonical bytes for the declared version
+- `computeAnchorChainHashV7(previousAnchorHash, subject, startSeq, endSeq, tip)` - v7 anchor chain hash
+- `canonicalizeAnchor(anchor)` - Get canonical JSON for verification
+- `loadAnchor(path)` - Load anchor from file (Node.js)
+- `loadExportedEntries(path)` - Load entries from file (Node.js)
+
+### Webhook Verification (Node.js only)
+
+- `isValidWebhook(signatureHeader, payload, secret)` - Simple validation (returns boolean)
+- `verifyWebhookSignature(signatureHeader, payload, secret, options?)` - Full validation (throws on error)
+- `verifyWebhookWithSecrets(signatureHeader, payload, secrets, options?)` - Support secret rotation
+- `computeWebhookSignature(secret, timestamp, payload)` - Compute signature (for testing)
+- `decodeSecret(secret)` - Decode base64 or hex secret from dashboard
+
+### Tombstone Detection
+
+- `isTombstone(entryType, entryId)` - Check if entry is a tombstone
+- `isTombstoneContentHash(contentHash)` - Quick prefix check
+- `validateTombstoneContentHash(contentHash)` - Full format validation
+
+### Keys
+
+- `getPublicKey(keyId)` - Get embedded public key
+- `isKnownKey(keyId)` - Check if key ID is known
+- `listKeyIds()` - List all embedded key IDs
+
+## Types
+
+```typescript
+interface Anchor {
+  version: number;
+  anchorId: string;
+  companyId: string;
+  region: string;
+  chainState: ChainState;
+  metadata: Metadata;
+  signature: Signature;
+}
+
+interface ExportedEntry {
+  entryId: string;
+  entryType: string;
+  timestamp: string;
+  runId: string;
+  sequenceNum: number;
+  globalSeq: number;
+  contentHash: string;
+  chainHash: string;
+}
+
+interface OfflineVerificationResult {
+  valid: boolean;
+  entriesVerified: number;
+  tombstonesFound: number;
+  breaks: OfflineBreak[];
+  durationMs: number;
+}
+```
+
+### Anchor int64 fields: `bigint | number`
+
+As of 0.3.0, `Anchor.entryCount`, `Anchor.createdAtMs`, and
+`Anchor.verifiedThrough` accept either `bigint` or `number`. Real-world
+millisecond timestamps and counters fit in `number` and need no caller
+change. For int64 values that exceed `Number.MAX_SAFE_INTEGER` (2^53 − 1)
+— for example, the synthetic 2^63 − 1 boundary — pass them as `bigint`
+or as JSON strings; `parseAnchor` will route strings through `BigInt(...)`.
+
+```typescript
+// Number — preserves the existing API
+const a1 = parseAnchor({ /* ... */ entry_count: 42, created_at_ms: 1700000000000 });
+
+// JSON string — preserves full int64 precision
+const a2 = parseAnchor({ /* ... */ verified_through: "9223372036854775807" });
+
+// Consuming the field
+const n = typeof a2.entryCount === "bigint"
+  ? a2.entryCount       // use BigInt arithmetic
+  : BigInt(a2.entryCount); // promote for uniform handling
+```
+
+
+## Conformance
+
+One of three implementations of the same format, held to a **shared set of
+conformance vectors** kept in the public `proof` repository and vendored here
+with a manifest of SHA-256 digests.
+
+```
+                    proof/fixtures/testdata/   ← canonical, public
+                              │  vendored + digest-checked
+              ┌───────────────┼───────────────┐
+              ▼               ▼               ▼
+             Go            Python          JavaScript
+              └────── all must reproduce ─────┘
+```
+
+The expected outputs are **data**, never regenerated by an implementation during
+a run: a vector edited to make one implementation pass fails the other two.
+`test/conformanceVectors.test.ts` verifies the vendored copy before any test
+trusts it.
+
+**Vector set passed:** proof v0.5.0's plus the X-Wing specification's official
+vectors (`xwing_spec_vectors.json`), `sdk/testdata/MANIFEST.json` with
+SHA-256 `304583d41eca4e74e2fb19cd799f499e663d60d0366bb70f4f712db903264d3c`
+(`shasum -a 256 MANIFEST.json`), every case of every file it lists.
+
+**Formats this SDK verifies:**
+
+| Format | Spec | Vectors |
+|---|---|---|
+| Chain hash v4 (leaf hash, chain hash, erasure, continuation from v2/v3) | format-spec §2.0, §2.5, §5.0 | `chain_v4_vectors.json` |
+| Chain hash v3, v2 (frozen) | format-spec §2.1, §2.3 | `chain_v3_vectors.json`, `chain_vectors.json` |
+| Verifier verdicts: break order and counters, v7 keyless bind | format-spec §5.5, §9.7 | `verify_verdict_v4_vectors.json`, `verify_verdict_vectors.json` |
+| Anchors v7 (context `aleutian.proof.anchor.v7`) | format-spec §9 | `anchor_v7_canonical_vectors.json` |
+| Anchors v1, v3, v4, v6 (frozen), anchor chain hash | format-spec §9 | `anchor_v6_canonical_vectors.json`, `anchor_v4_canonical_vectors.json`, `anchor_chain_hash_vectors.json` |
+| Sink bundles `aleutian.proof.bundle.v2` and `.v1` | bundle-format §1–§16 | `bundle_v2_vectors.json`, `bundle_v1_vectors.json` |
+| Record envelopes `aleutian.proof.record.v2` (context `aleutian.proof.record.v2`) and `.v1` | sink-format §9.1 | `record_v2_vectors.json`, `record_v1_vectors.json` |
+| Key ids, salted commitments, Merkle trees, capture leaf v3 | format-spec §9.6, §8, §7, §6 | `keyid_vectors.json`, `commitment_vectors.json`, `merkle_golden.json`, `v3_golden_capture_request.json` |
+
+This SDK is also tested against artifacts the Go implementation produced —
+a v3 chain from `proof append` and a v6 anchor signed by `proof anchor` with a
+real ML-DSA-65 key.
+
+### What this SDK does not do
+
+It **verifies**; it does not produce. No signing, no chain linking, no key
+generation — those live in the Go implementation. A verifier should be small,
+dependency-light and safe to drop into an auditor's environment, including a
+browser.
+
+## Security
+
+- **ML-DSA-65** (FIPS 204) anchor signatures — post-quantum, verify-only. This
+  SDK cannot sign; see "What this SDK does not do".
+- HMAC-**SHA-512** webhook signatures via Node.js crypto (constant-time)
+- [tweetnacl](https://tweetnacl.js.org/) is used for **X25519 key exchange** in
+  the tier-2 unseal path (audited, constant-time) — NOT for signatures. An
+  earlier version of this section said "Ed25519 signatures via tweetnacl",
+  which was wrong on both counts.
+- Webhook verification uses `crypto.timingSafeEqual` to prevent timing attacks
+- Secret rotation verifies ALL secrets to prevent timing side-channel (H-5)
+- Signature parsing uses constant-time pattern (H-1)
+
+### Privacy Notes
+
+- `anchor.companyId` contains business-identifying information - do not log
+- `OfflineBreak.entryId` may correlate to PII - truncate hashes before logging
+- `durationMs` can reveal chain size - do not log in production
+
+## Browser Support
+
+The SDK ships a dedicated browser bundle alongside the Node bundle. Modern
+browsers (Chrome 80+, Firefox 75+, Safari 14+, Edge 80+) are supported.
+
+### npm consumers (bundlers — Vite, webpack, esbuild, Rollup)
+
+No special configuration required. The `package.json` `exports` map
+includes a `"browser"` conditional, so bundlers automatically resolve
+to `dist/browser/index.js` (ESM) when building for a browser target.
+
+```typescript
+import {
+  verifyChainEntryV3,
+  TrustManifestV3,
+  encodeAndHashV3,
+} from "@aleutian/verification";
+```
+
+### CDN / `<script>` include (no bundler)
+
+The IIFE bundle exposes everything on a `window.AleutianVerification`
+global:
+
+```html
+<script src="https://unpkg.com/@aleutian/verification/dist/browser/index.global.js"></script>
+<script type="module">
+  const { encodeAndHashV3, verifyChainEntryV3 } = window.AleutianVerification;
+
+  // Fetch your anchor and entry from your server / Aleutian
+  const entryJson = await fetch("/entry.json").then((r) => r.json());
+
+  // ... convert wire JSON to typed ChainEntryV3 (camelCase) ...
+  const { canonical, contentHash } = await encodeAndHashV3(entry);
+  // ...
+</script>
+```
+
+### What's NOT in the browser bundle
+
+The browser bundle intentionally omits two surfaces:
+
+- **Webhook verification** (`verifyWebhookSignature`, `isValidWebhook`,
+  etc.) — webhooks are server→server and the existing API is sync
+  HMAC-SHA-512, which has no async-free browser equivalent. Use the
+  Node bundle for webhook verification.
+- **File-system loaders** (`loadAnchor`, `loadExportedEntries`) —
+  browsers don't have filesystem access. Use `fetch(...)` then
+  `parseAnchor` / `parseExportedEntries` instead.
+
+### Threat-model caveat for constant-time compare in browsers
+
+The constant-time hash and signature compares in `verifyChainEntryV3`
+prefer the Node built-in (`crypto.timingSafeEqual`, C-level) when
+available; in the browser they fall back to a pure-JS implementation.
+The pure-JS fallback is best-effort under JIT — for high-assurance
+deployments, prefer running verification under Node.
+
+### Browser-bundle CI
+
+Two suites cover the browser bundle:
+
+- `npm test` (vitest) runs the happy-dom smoke at
+  `test/browserBundle.smoke.test.ts` — fast, covers the ESM import
+  surface and the `crypto.subtle.digest("SHA-512", ...)` contract.
+- `npm run test:browser` (Playwright + Chromium) runs a real-browser
+  pass at `test/playwright/browser_smoke.spec.ts` that loads the IIFE
+  bundle via `<script>`, attaches `window.AleutianVerification`, and
+  re-hashes the same Go-baked V3 SAR golden vector inside real V8.
+  Requires `npx playwright install chromium` once.
+
+## License
+
+Apache-2.0
+
+Copyright 2026 Aleutian AI