@typedstandards/verify-core 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -6,6 +6,23 @@ 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

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.1",
+  "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",