@aleutian/verification 0.0.0 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,597 @@
+# Changelog
+
+All notable changes to `@aleutian/verification` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to a SemVer track per the
+[SDK Release Charter](../../docs/sdk/release_charter_v1.md). While on the
+0.x track, minor bumps may introduce breaking changes; patch bumps remain
+backwards-compatible. Cross-language version alignment activates only after
+a 1.0 cut (see charter §5).
+
+## [Unreleased]
+
+## [0.7.0] — 2026-10-20
+
+### Added — X-Wing specification vectors
+
+- `test/xwingSpecVectors.test.ts` holds the Tier-2 X-Wing decapsulation to the
+  specification's official vectors (`sdk/testdata/xwing_spec_vectors.json`, now
+  part of proof's vector set; `MANIFEST.json` SHA-256 `304583d41eca4e74e2fb19cd799f499e663d60d0366bb70f4f712db903264d3c`). It re-checks the
+  fixture against the SHAKE128 checksum the specification publishes, derives each
+  `pk` from its `sk`, and decapsulates each `ct` to `ss`. Until now this code was
+  checked only against vectors this project generated. The only source change is
+  an internal export of the two functions for the test, outside the package's
+  exports.
+
+### Added — proof v0.5.0 formats
+
+Implemented from proof's format-spec (§2.0, §2.2, §2.5, §5.0, §5.5, §9),
+bundle-format §16 and sink-format §9.1 alone, and held to all five new shared
+vector files of the v0.5.0 set (`MANIFEST.json` SHA-256
+`2eecb9f606ca3937849bea3d891eeed2fc4306d77ccf344b01ddf33ff4e0f514`). The
+v2/v3/v6/bundle-v1 paths are unchanged and still pass their frozen vectors.
+Dispatch is on declared versions only (`format_version`, anchor `version`,
+bundle `format`).
+
+- **Chain format v4**: `computeLeafHashV4`, `computeChainHashV4` (ids and
+  types hashed as stored, never normalised; length-prefixed). `verifyChainOffline`
+  verifies v4 entries, erased ones from their stored leaf hash (no chain hash
+  is taken on trust), and v2/v3 chains continued in v4 (§2.5). The walk applies
+  §5.5's break order: `format_field_misuse` for a v2/v3 entry after v4, a v4
+  member on a v2/v3 entry, or a v4 entry with run fields or a tombstone shape;
+  the v4 first-entry rule and the two entry shapes as `invalid_field`; leaf
+  hash before chain hash. New result field `erasedFound`. `parseEntriesText`
+  reads v4 entries (an erased one has no id, type or content hash) and records
+  which members were present (`presentMembers`). Held to every case of
+  `chain_v4_vectors.json` (vectors, `v3_prefix`, rejects) and the 39
+  `chain_cases` of `verify_verdict_v4_vectors.json`.
+- **Anchors v7**: strict reading (`entry_count`, `start_seq`, `end_seq` are
+  JSON strings, returned as `bigint`, so values above 2^53 stay exact; every
+  member required), §9.3 invariants, `canonicalizeAnchorV7`,
+  `computeAnchorChainHashV7` (length-prefixed subject), and
+  `verifyAnchorLocally` with the ML-DSA context `aleutian.proof.anchor.v7`
+  (chosen from the declared version; v1–v6 keep the empty context).
+  `bindAnchorV7ToEntries(anchor, entries, { subject, previousAnchorHash })`
+  binds by sequence in §9.7's order and reports `subjectChecked`; new outcome
+  `tenant_mismatch`. `bindAnchorToEntries` and `verifyChainOffline` route a v7
+  anchor there. Held to `anchor_v7_canonical_vectors.json` (canonical bytes,
+  chain hash, signatures, rejects) and the 23 `bind_cases` of
+  `verify_verdict_v4_vectors.json`.
+- **Record envelope `aleutian.proof.record.v2`**: `buildRecordEnvelopeV2`,
+  `verifyRecordSignatureV2` (field 0x09 leaf hash, context
+  `aleutian.proof.record.v2`), and `verifyMLDSA65PureWithContext`. Held to
+  `record_v2_vectors.json`.
+- **Bundles `aleutian.proof.bundle.v2`** in `verifyProofBundle` and the
+  `verify-proof-bundle` CLI: entries with `salt` and `leaf_hash` (both
+  required; a v1-shaped or erased-shaped entry is `structure`), v7 checkpoints
+  (step e over entry `end_seq` by index, counts compared as integers), record.v2
+  signatures, and the v2 value limit of 17,000,000 (`PROOF_BUNDLE_LIMITS.valuesV2`).
+  Same result format and codes. Held to all 192 cases of `bundle_v2_vectors.json`,
+  and to each signature a case lists.
+
+### Changed — proof v0.5.0 vectors, revised
+
+Held to the revised v0.5.0 vector set (`MANIFEST.json` SHA-256
+`62b96a47373c1cf41b21af29ac23b9760eee205b00933d26769efcee09b5c662`):
+52 `chain_cases`, 20 `entries_text_cases` and 23 `bind_cases` in
+`verify_verdict_v4_vectors.json`, 30 anchor v7 rejects, 22 chain v4 vectors
+and 193 bundle v2 cases.
+
+- The verdict vectors now pin the number of breaks a walk reports with every
+  break collected (§5.0, §5.5: at most one per entry from steps 2 to 8, after
+  a `sequence_gap`); the walk already agreed on every case.
+- `parseEntriesText` refuses a member name that case-folds to a format member
+  without being it (`ſalt` with U+017F, `eraſed`), as it already refused
+  `CHAIN_HASH`: a case-folding reader takes either for the real member.
+- A v7 anchor's `anchor_id` and `previous_anchor_id` must be non-empty, and
+  its `subject`, `anchor_id`, `previous_anchor_id` and `signing_key_id` valid
+  UTF-8 (no lone surrogate), in `checkAnchorWellFormed` (§9.3, §9.8). The
+  strict text reader already refused null members, invalid UTF-8 and lone
+  surrogate escapes.
+
+### Changed
+
+- `canonicalizeAnchorForVersion` refuses a version with no canonical form
+  (5, or anything but 1–4, 6, 7) instead of canonicalizing it as v1.
+- A v1–v6 anchor carrying `previous_anchor_hash` or a sequence range is
+  refused (format-spec §9.8), and a v2 or v3 entry carrying `salt`,
+  `leaf_hash` or `erased` is the break `format_field_misuse` (§2.2); both
+  members were ignored before.
+
+Held to proof's SHARED vectors for chain hash v3, anchor v6 and key ids
+(computed in Python from the format spec), instead of constants copied from Go.
+They found two real disagreements with the format, both fixed here.
+
+### Fixed
+
+- **Anchor canonical bytes now escape exactly as Go does** (format-spec §9.2):
+  `<` `>` `&` U+2028 U+2029 as `\u` escapes, in every anchor version. Before,
+  an anchor whose id or subject held one of them canonicalized differently from
+  the bytes that were signed, and failed verification.
+- **Chain hash v3 refuses malformed inputs** (format-spec §2.1, §3), as proof
+  does: a `previous_hash` that is not empty or 128 lowercase hex, a
+  `content_hash` that is neither 128 lowercase hex nor a tombstone value, a
+  `global_seq` above 2^63 − 1, or a timestamp not in the `YYYY-MM-DDTHH:MM:SS.ffffffZ` form. The preimage is `|`-delimited and not
+  self-delimiting, so a malformed field could make two different entries hash
+  alike. *(Breaking only for callers that passed malformed values.)*
+- **Proof bundle verifier, after review (`_72e`), to bundle-format revision 3.2:**
+  - **Bounded memory.** The bundle is read in one streaming pass that counts
+    JSON values (§5's new 15,000,000 limit, `too-large` at §9.1 position 3;
+    `ProofBundleLimits` gains `values`), knows each value's §4 position, stops
+    building at the first structure violation, duplicate name, wrong `format`
+    or count overrun, and decodes escaped strings without one allocation per
+    escape. 16 MiB of `{}` chains went from about 1.3 GB of heap to under
+    1 MB; 64 MiB no longer crashes Node.
+  - **Piped CLI output is complete.** The bin sets `process.exitCode` instead
+    of calling `process.exit()`, which cut `--json | jq` at 64 KiB on macOS. An
+    error escaping the command prints a fixed message and exits 5, never a
+    stack.
+  - Checkpoint step e is linear (the first malformed entry is found once).
+  - Hashing in the bundle verifier is synchronous (`@noble/hashes`).
+  - Key files must be regular files of at most 16 KiB (a directory, FIFO or
+    larger file is a usage error); the bundle file is opened once and read up
+    to one byte past the 256 MiB limit.
+  - Unreadable human output states both trust dimensions (§10).
+  - A malformed `trust` argument throws `ProofBundleVerifierError`.
+  - The bundle verifier no longer imports `keys.ts`, so browser bundles of it
+    carry no embedded key fixtures: the v6 anchor canonicalization moved to
+    `anchorCanonical.ts` (`canonicalizeAnchorV6` is still exported unchanged).
+
+### Added
+
+- Key ids (format-spec §9.6): `keyIdMLDSA65`, `keyIdXWing`, `mldsa65Spki`. A verifier uses them to check that the
+  key it verifies a signature with really has the key id the signature names.
+- The commitment and `record.v1` vectors are vendored too, ready for the sink
+  bundle verifier (`_72`).
+- **Proof sink export bundles** (`aleutian.proof.bundle.v1`, proof's
+  `bundle-format.md` revision 3.2): `verifyProofBundle(bytes, { checkpointKeys,
+  recordKeys })` returns the `aleutian.proof.bundle-result.v1` result, and the
+  CLI gains `aleutian-verify verify-proof-bundle <bundle.json>
+  [--checkpoint-key F]... [--record-key F]... [--json]` (exit 0 ok, 1 failed,
+  2 usage, 3 unreadable, 4 unauthenticated, 5 internal error). Written from the
+  spec alone, independently of proof's code, and held to all 114 cases of the
+  shared `bundle_v1_vectors.json`. A strict JSON parser enforces the bundle
+  grammar (valid UTF-8, no BOM, no lone surrogates, duplicate names refused
+  after unescaping, depth 8, numbers never rounded); `global_seq` is a BigInt.
+  Signatures are pure ML-DSA-65 with an empty context: context and HashML-DSA
+  signatures fail. Output never prints a bundle value other than a valid chain
+  id. Browser-safe.
+- `parseProofPublicKeyFile`: trust key files (one `PUBLIC KEY` PEM block, the
+  RFC 9881 SPKI of an ML-DSA-65 key); anything else is refused.
+- Salted commitments (format-spec §8): `computeCommitment`, `openCommitment`.
+- The record-signature envelope (sink-format §9.1): `buildRecordEnvelopeV1`,
+  `verifyRecordSignatureV1`, `verifyMLDSA65Pure`. Held to the commitment and
+  `record.v1` vectors, including the pinned regression signature.
+
+## [0.6.0] — 2026-09-26
+
+_Prepared, never published._ This version was built and gated for chain format
+v3 and anchor v6, but never uploaded. Its contents shipped first in 0.7.0, with
+everything in that entry. This number is skipped.
+
+First release to implement the CURRENT AleutianChain formats, and the first
+held to shared cross-language conformance vectors.
+
+### Added
+
+- **Chain hash v3** (`computeChainHashV3`, `CHAIN_HASH_PREFIX_V3`), which binds
+  the chain-wide `globalSeq` rather than v2's batch-local `sequenceNum`, making
+  a chain independent of how it was grouped into append calls.
+- **`globalSeq` accepts `bigint`.** The format's sequence is a 64-bit integer
+  and JavaScript's `number` holds 53 bits exactly: the reference
+  implementation's own test vector `9007199254740993` becomes `…992` as a
+  literal AND through `JSON.parse`. Passing a `number` above
+  `Number.MAX_SAFE_INTEGER` now THROWS rather than hashing a value that is not
+  the one on the wire — a wrong digest surfaces downstream as a chain break on
+  intact data.
+- **Format dispatch** in `verifyChainOffline`; `formatVersion` absent or 0 means
+  v2, which keeps every pre-v3 chain verifiable.
+- **Anchor v6** (`canonicalizeAnchorV6`), where `subject` replaces `company_id`
+  inside the signed bytes and moves from 3rd alphabetically to 8th. v5 remains
+  refused.
+- Break types `unknown_format` and `format_field_misuse`, neither of which is
+  tamper evidence.
+- **Conformance vector enforcement** (`test/conformanceVectors.test.ts`).
+
+### Changed
+
+- **BREAKING: `Anchor.companyId` is now `Anchor.subject`.** The wire key still
+  follows the anchor's version, and `parseAnchor` accepts either spelling —
+  refusing two different values under them.
+
+### Fixed
+
+- The Security section claimed **"Ed25519 signatures via tweetnacl"**. Anchors
+  are ML-DSA-65; tweetnacl is used for X25519 key exchange in the tier-2 unseal
+  path, not for signatures. It also said HMAC-SHA256 while the feature list nine
+  lines above said HMAC-SHA-512 — the latter is correct.
+
+## [0.5.0] — 2026-08-20
+
+Closes `consent_rendered_hash_06`. `hashRendered` computed unkeyed SHA-512,
+which has never matched production server output — the server has
+HMAC-keyed this hash since 2026-04-16 (`18_20_review_01`), closing a
+rainbow-table oracle on PII-adjacent rendered consent bytes. This release
+makes the SDK match.
+
+### Changed
+
+- **BREAKING: `hashRendered(b: Uint8Array): Promise<string>` is now
+  `hashRendered(b: Uint8Array, tenantPepper: Uint8Array): string`** —
+  synchronous, and moved to a new module (`consentRenderedHash.ts`). There
+  is no unkeyed variant to fall back to. Callers obtain `tenantPepper` via
+  the new consent-pepper reveal endpoint
+  (`POST /v1/internal/consent/rendered-pepper/reveal`,
+  `consent_rendered_hash_04`) before calling `hashRendered`.
+- **BREAKING: `hashRendered` is no longer exported from the browser bundle**
+  (`@aleutian/verification/browser`, `dist/browser/index.js`). Its input now
+  includes a SECRET tenant pepper, which must never ship into
+  browser-executable code — same reasoning that already excludes the
+  `webhook` module from the browser build. Node-only; import from the
+  default (Node) entry point.
+
+## [0.4.0] — 2026-06-14
+
+Closes `sdk_anchor_binding_gap`. Previous SDK releases could not validate
+real Aleutian-produced anchors because the anchor's `chain_hash` lives in
+a different SHA-512 domain (`"aleutian.anchor.v2:"`) than the per-entry
+`chain_hash` (`"aleutian.chain.v2:"`). `verifyChainOffline` was doing raw
+byte-equality between the walked tip and `anchor.chainHash` — a comparison
+that can never succeed for real producer output. This release ships the
+missing binding primitive and rewrites the verification step to use it.
+
+### Added
+
+- **`computeAnchorChainHash(prevAnchorHash, companyId, startEntryId, endEntryId, tipChainHash)`** — async; byte-identical to the Go SDK `ComputeAnchorChainHash` and the producer at `internal/chainlinker/anchor_generator.go`. Recomputes the SHA-512 over the `"aleutian.anchor.v2:"` domain that the producer stores in `anchors.chain_hash`.
+- **`SEED_ANCHOR_HASH`** — the genesis `previousAnchorHash` (`SHA-512("aleutian.anchor.seed.v2")`), used as the prior-anchor input when verifying the first anchor in a company's chain.
+- **`SEED_ANCHOR_ID`** — sentinel `previousAnchorId` for genesis anchors.
+- **`ANCHOR_CHAIN_DOMAIN_V2`** — exported domain-separator constant, for callers reimplementing the hash in non-SDK code.
+- **`ChainVerifyOptions.anchor`** + **`ChainVerifyOptions.previousAnchorHash`** — the new supported anchor-binding API. Pass the full anchor and the prior anchor's `chainHash`; the SDK recomputes the expected anchor digest and constant-time compares against `anchor.chainHash`. Empty `previousAnchorHash` + `anchor.previousAnchorId === SEED_ANCHOR_ID` auto-fills `SEED_ANCHOR_HASH` for convenience.
+- New CLI flag on `aleutian-verify`: `--previous-anchor-hash <hex>`. Genesis anchors can omit it; mid-chain anchors require it.
+
+### Changed
+
+- `Anchor.chainHash` doc-comment corrected — clarifies that this field is the anchor-of-anchors digest (output of `computeAnchorChainHash`), NOT the tip entry's `chain_hash`. Verifiers must recompute, not byte-compare.
+- README + module doc-comments updated to the new pattern; the prior examples referenced `anchor.chainState.lastChainHash`, a field that never existed on the public `Anchor` type.
+
+### Deprecated
+
+- **`ChainVerifyOptions.expectedLastHash`** — the raw-equality path that could never bind real producer anchors. Preserved this release for any caller still passing it; will be removed in the next minor.
+
+### Migration
+
+```ts
+// Before (0.3.x — could not bind real anchors)
+const result = await verifyChainOffline(entries, {
+  expectedLastHash: anchor.chainHash,
+});
+
+// After (0.4.0)
+import { SEED_ANCHOR_HASH } from "@aleutian/verification";
+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,
+});
+```
+
+### Verification
+
+Pinned by cross-language golden vector (byte-identical Go + Python + JS),
+SDK↔producer byte-equality regression test, and end-to-end live-BQ smoke
+against real `duncan` production data (`scripts/smoke-sdk-live.sh`).
+
+## [0.3.1] — 2026-05-29
+
+Patch release shipping two deferred items from
+`dsar_chain_f_post_review_followups`: an additive options-object API
+shape for `verifyChainEntryV3` (M1) and elimination of the redundant
+per-field NFC re-normalization on the canonical-bytes hot path (M6).
+No canonical-bytes change for NFC inputs (the only contract that
+matters cross-language).
+
+### Added
+
+- **`verifyChainEntryV3` options-object form (M1).** The function now
+  accepts a second-shape call:
+
+  ```ts
+  verifyChainEntryV3(entry, { signature, contentHash, trustManifest })
+  ```
+
+  in addition to the existing positional form. The new form is
+  preferred going forward; it removes positional-argument-order
+  bugs and is the only form supported by the 0.4.0 cut. A new
+  `VerifyChainEntryV3Options` interface is exported. The new shape
+  emits no deprecation warning.
+
+### Deprecated
+
+- **Positional form of `verifyChainEntryV3`.** Calling
+  `verifyChainEntryV3(entry, signature, contentHash, trustManifest)`
+  still works on the 0.3.x track but emits a **one-shot**
+  `console.warn` notice on first use per process. Migrate to the
+  options-object form. Positional form will be **removed** in 0.4.0.
+
+### Changed
+
+- **Double-NFC encoding eliminated (M6).** `V3Encoder` gained a
+  constructor flag `{ assumeNormalized: true }` that skips the
+  redundant `s.normalize("NFC")` call in `appendStr` on the
+  assumption that the caller has already validated. The internal
+  `chainCanonicalV3` pipeline now constructs its encoder with this
+  flag, saving one `String.normalize` call per field on the hot path.
+  `validateV3StringField` now rejects inputs that are not already in
+  Unicode NFC form to make the flag sound (defense-in-depth — every
+  v3 string field today is restricted to ASCII via upstream regex, so
+  the gate is unreachable on well-formed inputs and no real caller
+  is affected). Canonical bytes are unchanged for all NFC inputs;
+  golden vectors and cross-language pins still pass.
+
+### References
+
+- Ticket: `tickets/code_complete/dsar_chain_f_post_review_followups.md`
+- Parent: `dsar_chain_f_review_pre_emptive` (closed 2026-05-29)
+
+## [0.3.0] — 2026-05-29
+
+This release closes the six post-V1/V2-audit JS SDK fix tickets from the
+`dsar_js_v1v2_audit_pass` sweep. One TypeScript-typing widening is a
+breaking change at the type level (no runtime behaviour change for
+in-range values), so this lands as a minor bump on the 0.x track per the
+release charter.
+
+### Breaking (types only)
+
+- **`Anchor` int64 fields widened to `bigint | number`.**
+  `Anchor.entryCount`, `Anchor.createdAtMs`, and `Anchor.verifiedThrough`
+  are now typed `bigint | number` so int64 values exceeding
+  `Number.MAX_SAFE_INTEGER` (2^53 − 1) can be represented losslessly.
+  Real-world millisecond timestamps and entry counts continue to fit
+  in `number` and require no caller change. Callers that explicitly
+  declared variables as `number` will see a type error and should
+  widen to `bigint | number` or narrow with a `typeof === "number"`
+  guard. `parseAnchor` accepts JSON `number` (legacy) **or** JSON
+  `string` (full int64 precision) for int64 fields. The
+  `canonicalizeAnchor` / `canonicalizeAnchorV4` encoders manually
+  assemble the canonical JSON so `bigint` values emit byte-identically
+  to Go/Python without going through the lossy `JSON.stringify(bigint)`
+  path (which throws). `canonicalizeAnchorForVersion` is now exported
+  from the package root. Ticket: `dsar_js_anchor_int64_widening`.
+
+### Security / Privacy
+
+- **`InvalidProcessingMode` no longer echoes caller input** into its
+  error message. The message is now a fixed string
+  `"unknown processing mode (input redacted)"` so callers cannot
+  accidentally surface untrusted bytes through logs. Enforces Privacy
+  Invariant 4 at the SDK boundary. Ticket:
+  `dsar_js_processing_mode_error_echo`.
+- **Defensive copy on trust-manifest and embedded public keys.**
+  `TrustManifest.publicKey()` and `getPublicKey()` now return a fresh
+  `Uint8Array` per call so caller mutation can no longer corrupt the
+  cached/embedded key bytes. Ticket:
+  `dsar_js_trust_manifest_key_mutability`.
+- **Lone-surrogate gate on canonical-encoder string inputs.**
+  `consentCanonical` and `encodeProcessingModeCanonicalFields` now
+  reject strings containing unpaired UTF-16 surrogates with a
+  redacted-byte error, preventing `TextEncoder`'s silent
+  U+FFFD-substitution from diverging the JS encoder from the Go /
+  Python producers. Well-formed surrogate pairs (emoji etc.) continue
+  to pass through. Ticket: `dsar_js_consent_lone_surrogate_gate`.
+
+### Added
+
+- **`redactedView` module.** Four helpers — `redactedAnchor`,
+  `redactedConsentChainEntry`, `redactedExportedEntry`,
+  `redactedOfflineBreak` — return frozen opaque markers
+  (`{ __type: "<TypeName>", __redacted: true }`) safe to pass into
+  `console.log`, `JSON.stringify`, structured loggers, or template
+  literals. The producer interfaces are plain object literals (cannot
+  own a `toJSON` override), so the WARNING comments on `Anchor`,
+  `ConsentChainEntry`, `ExportedEntry`, and `OfflineBreak` now point
+  callers at the matching helper. Ticket:
+  `dsar_js_consent_anchor_json_stringify_leak`.
+
+### Internal
+
+- **Consolidated constant-time comparator in `verify.ts`.** The local
+  string-XOR `constantTimeEqual` was replaced with the shared
+  `internal/constantTime.ts` byte comparator (which prefers Node's
+  C-level `crypto.timingSafeEqual` when available and falls back to a
+  non-short-circuiting pure-JS loop in browsers). A thin
+  `chainHashEqual` wrapper handles the hex-string → UTF-8 byte
+  encoding so the call sites stay ergonomic. Strictly better timing
+  profile on Node; no behavioural change on browsers. Ticket:
+  `dsar_js_verify_consolidate_constant_time`.
+
+### Migration
+
+If you previously declared anchor int64 fields as `number`:
+
+```ts
+// Before
+const count: number = anchor.entryCount;
+
+// After (choose one)
+const count: bigint | number = anchor.entryCount;
+// or, if you know the value fits in Number:
+const count = typeof anchor.entryCount === "bigint"
+  ? Number(anchor.entryCount)
+  : anchor.entryCount;
+```
+
+For producers emitting int64 values that can exceed
+`Number.MAX_SAFE_INTEGER`, ship them as JSON strings; `parseAnchor`
+will promote them to `bigint`. For values that fit in `number`, the
+existing JSON-number form continues to work unchanged.
+
+## [0.2.2] — 2026-05-29
+
+### Added
+
+- **Browser bundle.** A dedicated browser-target build now ships
+  alongside the Node bundle:
+  - `dist/browser/index.js` (ESM) — for bundlers (Vite, webpack, esbuild, Rollup)
+  - `dist/browser/index.global.js` (IIFE) — for direct `<script>` includes,
+    exposes a `window.AleutianVerification` global
+  - `dist/browser/index.d.ts` — typings
+- `package.json` `exports` map gains a `"browser"` conditional, so
+  bundlers automatically resolve to the browser bundle when building
+  for a browser target. A `"./browser"` sub-path is also exposed for
+  explicit opt-in.
+- `src/internal/constantTime.ts` — shared cross-runtime constant-time
+  byte-array equality. `verifyV3.ts` and `consent.ts` both consume it;
+  the previous duplication and `consent.ts`'s top-level static
+  `import … from "crypto"` (a module-load blocker in browsers) are
+  gone.
+- `src/anchorLoaders.ts` — Node-only `loadAnchor` /
+  `loadExportedEntries` split out of `anchor.ts` so the browser bundle
+  does not pull `await import("fs/promises")` into its reachable
+  graph. Re-exported from `src/index.ts` for back-compat; intentionally
+  not re-exported from the browser entry.
+- `test/browserBundle.smoke.test.ts` — happy-dom-environment smoke
+  that imports the built `dist/browser/index.js`, re-encodes a
+  Go-baked golden V3 fixture, and asserts byte-identical content
+  hash. Also pins that the webhook surface is absent from the browser
+  bundle.
+
+### Changed
+
+- `consent.ts` `verifyConsentEntry`: `Buffer.from(s, "utf8")` →
+  `new TextEncoder().encode(s)` for cross-runtime byte construction.
+  No behavioral change in Node; unblocks browser usage.
+
+### Notes
+
+- The Node bundle (`dist/index.js`, `dist/index.cjs`) is **unchanged**
+  in API or behavior — webhook verification, file-system loaders, and
+  every other previously-exported symbol remain on the Node entry.
+- Webhook verification is intentionally absent from the browser bundle
+  (server→server only; existing API is sync HMAC-SHA-512 with no
+  async-free browser equivalent). See README "Browser Support" for
+  detail.
+- See `dsar_js_browser_target_audit` for the audit and design.
+
+## [0.2.1] — 2026-05-29
+
+### Changed
+
+- **License flipped to Apache 2.0.** Resolves the prior `UNLICENSED` state
+  documented in the 0.2.0 notes. The SDK is now openly distributed under
+  Apache License 2.0 — `package.json` `license` field updated, full LICENSE
+  file added at the module root, per-file Apache 2.0 short-form headers
+  applied across all source and test files. Decision locked via
+  `sdk_license_unification` ticket Option D (per-module rule in
+  CLAUDE.md §2.2). Aligns with the Go SDK and Python SDK, which were
+  flipped to Apache 2.0 in the same change. Customers integrating the
+  prior 0.2.0 release should re-resolve from this version to pick up the
+  Apache 2.0 license file in their build artifacts; no source or
+  behavioral changes in this release.
+
+## [0.2.0] — 2026-05-28
+
+Added full V3 SAR (Data Subject Access Request) chain entry verification at
+byte-level parity with the Go and Python SDK implementations.
+
+### Added
+
+**`canonicalV3` module** — TS port of the V3 canonical encoder
+
+- `chainCanonicalV3(entry: ChainEntryV3): Uint8Array` — encode a typed V3
+  chain entry to the canonical TLV byte sequence per pqc_05c v3 §3 + §4.
+- `computeV3ContentHash(canonical: Uint8Array): Promise<Uint8Array>` —
+  SHA-512(`aleutian.chain.entry.v3:` || canonical).
+- `encodeAndHashV3(entry)` — one-call convenience pairing the above.
+- `validateV3Entry(entry: ChainEntryV3): void` — typed V3 entry validator;
+  throws `ErrInvalidEntryV3` on any failure. Called automatically by
+  `chainCanonicalV3` before encoding.
+- `V3Encoder` class — exported for direct unit testing of encoder mechanics
+  (NFC normalization, BE encoding, length cap) without routing through the
+  full pipeline.
+- Constants: `DOMAIN_PREFIX_V3`, `DOMAIN_PREFIX_V3_BYTES`,
+  `MAX_V3_STRING_FIELD_BYTES = 256`, `MAX_CANONICAL_BYTES_V3 = 4096`,
+  `V3_SHA512_HEX_LEN = 128`, `EXTENDED_SANITY_BOUND_MS`.
+
+**`verifyV3` module** — V3 signature verifier
+
+- `verifyChainEntryV3(entry, signature, contentHash, trustManifest)` — the
+  single customer-facing verifier entry point. Resolves on success; throws
+  one of the typed `Err*V3` subclasses on failure.
+- `TrustManifestV3.fromMap({...})` — construct an in-process trust manifest
+  with **eager** ML-DSA-65 byte-length validation + defensive key copies.
+- `constantTimeEqual(a, b)` — pure-JS constant-time byte-array equality
+  (browser-safe; no `crypto.timingSafeEqual` available there).
+- Constant: `CONTENT_HASH_V3_BYTES = 64`.
+
+**Error hierarchy** — all extend `ErrInvalidEntryV3`
+
+- `ErrInvalidEntryV3` — encoder/validator base sentinel.
+- `ErrContentHashMismatchV3` — re-encoded hash does not match the claim.
+- `ErrSignatureInvalidV3` — signature parses but does not verify.
+- `ErrSignatureMalformedV3` — signature has wrong shape (length, type).
+- `ErrUnknownSigningKeyV3` — `signingKeyId` not in the trust manifest.
+- `ErrPublicKeyMalformedV3` — trust-manifest public key has wrong shape.
+
+**5 SAR entry type interfaces + supporting enums**
+
+- `SARIntentEntryV3`, `SARAcknowledgedEntryV3`, `SARFulfilledEntryV3`
+  (includes `certificateId` as the alphabetical-first body field per
+  `dsar_fulfill_b_pre_02e`), `SARRejectedEntryV3`, `SARExtendedEntryV3`.
+- `ChainEntryV3` discriminated union over `entryType`.
+- `EventTypeV3`, `SARTypeV3`, `SARFulfillmentKindV3`, `SARSourceChannelV3`
+  literal types.
+- `TenantHMACDigestV3` branded type + `tenantHMACDigestFromHex` /
+  `tenantHMACDigestFromRaw` / `tenantHMACDigestZero` / `tenantHMACDigestIsZero`
+  constructors and predicates.
+- `CONCRETE_SAR_ENTRY_TYPE_TAGS` runtime-immutable allowlist
+  (`Object.freeze` + `add`/`delete`/`clear` overridden to throw).
+- `hasValidChainEntryTag(value)` — runtime guard against
+  structural-typing impostors. `isChainEntryV3` retained as a
+  deprecation alias.
+
+### Changed
+
+- **Cross-language byte-identical canonical bytes against
+  `sdk/verification-go`** — proven by a new fixture-parity test
+  (`test/goldenV3.test.ts`) that loads the Go-baked golden vectors and
+  asserts byte-for-byte equality on canonical bytes AND content hashes
+  for all 5 SAR entry types (7 vectors total).
+- **Privacy posture hardening** (Privacy Inv 4 / chain_d H2 throughout):
+  error messages do NOT echo caller-supplied values (offending field
+  contents, post-NFC byte lengths, claimed/computed hash bytes, or
+  `signingKeyId`). Regression-guarded by dedicated tests.
+- **Hardened cross-language constant pins** — `MAX_CANONICAL_BYTES_V3 = 4096`
+  and SHA-512 hex length pinned identically to Go and Python SDKs.
+- **Internal v3 regex pinning** — V3 regex patterns are now string-equality
+  pinned against the producer source-of-truth shape, so silent drift on
+  either side fails CI.
+
+### Cross-SDK status
+
+After this release, all three Aleutian verification SDKs are at full V3 SAR
+parity:
+
+| Capability | Go | Python | JS (0.2.0) |
+|---|---|---|---|
+| Canonical encoder | ✓ | ✓ | ✓ |
+| Validators | ✓ | ✓ | ✓ |
+| Verifier | ✓ | ✓ | ✓ |
+| TrustManifest | ✓ | ✓ | ✓ |
+| Cross-language fixture parity | ✓ | ✓ | ✓ |
+
+### Notes
+
+- License posture (`UNLICENSED` → AGPL-3.0-or-later) remains pending the
+  cross-SDK `sdk_license_unification` decision and is intentionally NOT
+  flipped in this release.
+- Bundled fixtures live at `testdata/` and are exercised by the in-package
+  cross-language parity test.
+
+## [0.1.0] — Prior
+
+V1/V2 anchor, chain, tombstone, and webhook verification primitives.
+SHA-512-based chain hashing (post-`dsar_chain_f_pre_js_webhook_sha512`).
+ML-DSA-65 standalone verifier for anchor signatures.