@typedstandards/verify-core 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog — @typedstandards/verify-core
+
+Factual record of what changed per published version. Check numbers (#1–#15)
+refer to the Typed Standards specification §9.2 verification sequence. Issue
+references are to `npstorey/civic-ai-tools-website` (#119 is the offline-crypto
+hardening arc; #116 is the standalone-verifier arc this package was extracted
+in).
+
+## 0.7.0 — 2026-06-16
+
+- #1 envelope integrity is now TRI-STATE. `VerifyResult` gains an
+  `envelopeIntegrity: { status: 'verified' | 'altered' | 'unavailable'; reason? }`
+  field. A null `package` (content not fetched) previously surfaced only as
+  `hashMatch: false`, which a consumer could not distinguish from real tampering;
+  it now resolves to `status: 'unavailable'`, distinct from the `altered`
+  (bytes-present, hash-mismatch) case. `VerifyInput` gains an optional
+  `contentUnavailableReason: 'private' | 'unfetchable'` so the caller can say WHY
+  the content is absent — `private` (the commitment redacted the location for a
+  sealed/committed record, integrity N/A) vs. `unfetchable` (a present location
+  whose bytes could not be retrieved). Fixes the verifier false-alarming
+  "Contents changed since signing" on a perfectly valid content-private package
+  (npstorey/typedstandards#21). Additive and back-compatible: `hashMatch` is
+  unchanged (still `false` in both the `altered` and `unavailable` cases), so
+  existing consumers reading only `hashMatch` are unaffected.
+
+## 0.6.1 — 2026-06-10
+
+- Documentation only; no code changes. Corrects the README's stale "Check
+  depth (v1)" section — checks #7/#8/#10 have run at full cryptographic depth
+  since 0.2.0–0.6.0, not presence/hash-parity/state depth as previously
+  described. Adds this changelog.
+
+## 0.6.0 — 2026-06-07
+
+- #7 hardening: strict RFC 5280 certificate-chain validation (#119 P4).
+- Shared `parseInclusionProof` guard for #8 consumers (#119 P4).
+
+## 0.5.0 — 2026-06-07
+
+- #10 at full depth: independent verification of the signed lifecycle
+  attestation chain, including reachability from the package node, replacing
+  host-reported state (#119 P3).
+
+## 0.4.0 — 2026-06-07
+
+- #7 deepened: TSA certificate-chain verification to a pinned FreeTSA root;
+  token `genTime` surfaced to check #5 (#119 P2b).
+
+## 0.3.1 — 2026-06-07
+
+- Fix: accept high-S ECDSA signatures (`lowS: false`) from third-party
+  signers.
+
+## 0.3.0 — 2026-06-07
+
+- #7 at cryptographic depth: RFC 3161 token parsing, message-imprint match,
+  and TSA signature verification, FreeTSA profile (#119 P2a).
+
+## 0.2.0 — 2026-06-06
+
+- #8 at cryptographic depth: Rekor Merkle inclusion-proof verification from
+  the carried proof, against Rekor's pinned public key; carried-offline
+  integration test (#119 P1).
+
+## 0.1.0 — 2026-06-05
+
+- Initial release (#116 WS2/WS3): the spec §9.2 check suite, browser-safe (no
+  Node built-ins). #7 at presence depth, #8 at hash-parity depth, #10 at state
+  depth; all other checks fully client-side.

package/README.md

@@ -66,17 +66,28 @@ The barrel (`.`) also exports the individual check functions
 `computeContentHashSha256`), and every status vocabulary type — so a consumer can
 drive the checks one-at-a-time and render the math as it resolves.
 
-## Check depth (v1)
-
-Fully client-side: #1 envelope hash, #2 signature, #3 canonicalization, #4 content
-hash, #5 key trust, #6 kid consistency, #9 blob refs, #12 type, #13 nodeId, #14
-signer identity, #15 captureMethod vocab. **Presence** only for #7 (RFC 3161).
-**Hash-parity** only for #8 (Rekor). **State** depth for #10 (lifecycle).
-
-The deeper offline crypto — TSA-chain verification, Rekor Merkle-inclusion,
-independent lifecycle-chain verification, and the authoritative bundle-mode test —
-is a fast-follow (#119), not in this release. The UI built on this should be
-honest about what is presence vs. full-crypto.
+## Check depth (v0.6.x)
+
+Every check in the spec §9.2 sequence runs fully client-side, including the three
+that shipped at reduced depth in v0.1:
+
+- **#7 RFC 3161 timestamp** — full cryptographic verification: token parsing,
+  message-imprint match, TSA signature, and certificate-chain validation with
+  strict RFC 5280 checks to a pinned root (FreeTSA EC-P384 leaf → RSA-4096
+  root).
+- **#8 Rekor transparency log** — cryptographic Merkle inclusion-proof
+  verification from the proof carried with the package, against Rekor's pinned
+  public key; no live call to Rekor required.
+- **#10 lifecycle** — independent verification of the signed lifecycle
+  attestation chain, including reachability from the package node, instead of
+  trusting a host-reported state.
+
+Verification is offline-first: from a self-contained commitment bundle the full
+sequence runs with zero network access (demonstrated by a hermetic,
+network-blocked test in this monorepo). Trust anchors (the TSA certificate
+chain and the Rekor log public key) ship pinned in the source with capture
+dates and rotation notes. See `CHANGELOG.md` for how each check reached full
+depth across 0.2.0–0.6.0.
 
 ## License
 

package/dist/verify.d.ts

@@ -11,6 +11,34 @@ export interface VerifySignatureEnvelope {
     algorithm?: string;
     kid?: string;
 }
+/**
+ * Why a package's content was unavailable for envelope recomputation (#1).
+ *   - `private` — the commitment OMITTED the content location: a creator-only /
+ *     unlisted record whose bytes are private by design. Integrity is N/A, never a
+ *     failure; the public commitment (signature, key, timestamp, transparency log)
+ *     is still fully verifiable.
+ *   - `unfetchable` — a location WAS present but its bytes could not be retrieved
+ *     (404 / network). An availability problem, surfaced as unconfirmed rather than
+ *     altered.
+ */
+export type ContentUnavailableReason = 'private' | 'unfetchable';
+/**
+ * Tri-state envelope integrity (#1). Replaces the boolean `hashMatch` lens, which
+ * collapsed "content unavailable" onto `false` — so a private (content-redacted)
+ * record read as tampered.
+ *   - `verified`    — bytes present; the recomputed hash matches the signed hash.
+ *   - `altered`     — bytes present; the hash MISMATCHES. Real tampering.
+ *   - `unavailable` — no bytes to recompute from; `reason` says whether the content
+ *                     was private by design or merely unfetchable.
+ * `hashMatch` is retained UNCHANGED for back-compat (it is `false` in BOTH the
+ * `altered` and `unavailable` cases); a consumer that must not conflate tampering
+ * with unavailability reads THIS field.
+ */
+export interface EnvelopeIntegrityResult {
+    status: 'verified' | 'altered' | 'unavailable';
+    /** Present only when `status === 'unavailable'`. */
+    reason?: ContentUnavailableReason;
+}
 /** Lifecycle STATE as carried by the WS1 sidecar (`CommitmentLifecycle`). */
 export interface CommitmentLifecycleState {
     status: 'active' | 'withdrawn';
@@ -24,9 +52,11 @@ export interface CommitmentLifecycleState {
  * the package JSON the sidecar's `packageUrl` resolves to.
  */
 export interface VerifyInput {
-    /** The canonical package JSON (the signed envelope). Null mirrors the server's
-     *  "blob unavailable" path: integrity fails and the package-derived checks
-     *  report null. */
+    /** The canonical package JSON (the signed envelope). Null when the content is
+     *  unavailable — its bytes were not fetched, so envelope integrity (#1) cannot be
+     *  recomputed and the package-derived checks report null. `contentUnavailableReason`
+     *  says WHY it is null (private-by-design vs. unfetchable); the two read very
+     *  differently and must not be conflated with tampering. */
     package: Record<string, unknown> | null;
     /** The claimed envelope hash (`sidecar.packageHash` / `basePackageHash`). */
     packageHash: string;
@@ -55,6 +85,13 @@ export interface VerifyInput {
     /** Legacy external SHA-256 for the pre-v0.1 content-hash relabel. Defaults to
      *  `packageHash` (they coincide for pre-v0.1 packages). */
     legacyExternalHash?: string;
+    /** When `package` is null, why: `private` (the commitment redacted the content
+     *  location — a sealed/committed record) or `unfetchable` (a location was present
+     *  but its bytes could not be retrieved). Drives the `unavailable` reason on
+     *  `envelopeIntegrity`. Ignored when `package` is non-null. Absent ⇒ the
+     *  conservative `unfetchable` (a null package with no stated reason is treated as
+     *  an unconfirmed availability problem, never silently as a by-design redaction). */
+    contentUnavailableReason?: ContentUnavailableReason;
 }
 export interface VerifyDeps {
     /** Parsed trust registry (server: loaded; browser: fetched from the sidecar's
@@ -72,6 +109,10 @@ export interface VerifyDeps {
  *  can surface them directly. */
 export interface VerifyResult {
     hashMatch: boolean;
+    /** Tri-state envelope integrity (#1) — the corrected lens consumers SHOULD render
+     *  instead of branching on `hashMatch`, which cannot express "content unavailable,
+     *  so integrity is N/A" and reads it as tampering. See `EnvelopeIntegrityResult`. */
+    envelopeIntegrity: EnvelopeIntegrityResult;
     recomputedHash: string | null;
     /** = recomputedHash (check #13 nodeId). */
     nodeId: string | null;

package/dist/verify.js

@@ -38,12 +38,24 @@ import { resolveLifecycleFromLegacyColumns, } from "./lifecycle.js";
  */
 export async function verifyEvidence(input, deps) {
     const { package: pkg, packageHash } = input;
-    // Step 1 — recompute the envelope hash (checks #1 + #13).
+    // Step 1 — recompute the envelope hash (checks #1 + #13). Tri-state: a present
+    // package recomputes to `verified` / `altered`; a null package is `unavailable`
+    // (NOT `altered`) — its content was never fetched, so there is nothing to compare,
+    // and `contentUnavailableReason` distinguishes a by-design redaction (private)
+    // from a fetch failure (unfetchable). `hashMatch` stays a boolean for back-compat.
     let hashMatch = false;
     let recomputedHash = null;
+    let envelopeIntegrity;
     if (pkg) {
         recomputedHash = recomputePackageHash(pkg);
         hashMatch = recomputedHash === packageHash;
+        envelopeIntegrity = { status: hashMatch ? 'verified' : 'altered' };
+    }
+    else {
+        envelopeIntegrity = {
+            status: 'unavailable',
+            reason: input.contentUnavailableReason ?? 'unfetchable',
+        };
     }
     // Step 2 — signature (check #2), dispatching on the stored algorithm (#111).
     let signatureValid = null;
@@ -144,6 +156,7 @@ export async function verifyEvidence(input, deps) {
         });
     return {
         hashMatch,
+        envelopeIntegrity,
         recomputedHash,
         nodeId: recomputedHash,
         signatureValid,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typedstandards/verify-core",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Portable, browser-safe verification core for Typed Standards evidence packages — the §9.2 check suite, single-sourced so it verifies identically on a server and in the browser.",
   "license": "MIT",
   "author": "Nathan Storey",
@@ -20,6 +20,7 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {