@sanning/proof 0.9.0 → 0.9.2

package/README.md

@@ -203,7 +203,7 @@ The primary signature covers `JCS(envelope minus signature minus co_signatures)`
 
 ## Why you can trust it (without trusting us)
 
-Three **independent implementations** of this kernel exist: this package, the Python [`sanning-proof`](https://pypi.org/project/sanning-proof/) (PyPI), and and the MIT-licensed Go reference. The TypeScript and Python kernels are conformance-gated **byte-for-byte** in CI against one shared corpus, pinned per file by SHA-256 at cut tag `test-vectors-v3.4`, and a cross-kernel agreement gate re-runs the corpus plus adversarial negatives through both, asserting identical verdicts on identical bytes. The Go reference runs as a third leg of that same gate, built at the commit its vendoring pins.
+Three **independent implementations** of this kernel exist: this package, the Python [`sanning-proof`](https://pypi.org/project/sanning-proof/) (PyPI), and and the MIT-licensed Go reference. The TypeScript and Python kernels are conformance-gated **byte-for-byte** in CI against one shared corpus, pinned per file by SHA-256 at cut tag `test-vectors-v3.6`, and a cross-kernel agreement gate re-runs the corpus plus adversarial negatives through both, asserting identical verdicts on identical bytes. The Go reference runs as a third leg of that same gate, built at the commit its vendoring pins.
 
 That mutual gate is the point: anyone can verify these provenance records with **no Sanning code in the trust path**, write your own verifier against the specs that ship inside the [`sanning-proof`](https://pypi.org/project/sanning-proof/) sdist, and the corpus will tell you if it is conformant.
 

package/dist/agent-proof.js

@@ -77,6 +77,11 @@ export async function verifyAgentProofBundle(bundle, options = {}) {
             errors.push("checkpoint envelope signature failed");
         if (res.payloadHashOk !== true)
             errors.push("checkpoint envelope payload binding failed");
+        // A malformed skeleton field (proof#95) fails the envelope with a valid
+        // signature and binding; name it rather than fail with no reason.
+        for (const m of res.errors)
+            if (m.startsWith("malformed "))
+                errors.push(`checkpoint envelope ${m}`);
         const payload = (b.checkpoint_envelope.payload ?? {});
         if (typeof payload.merkle_root === "string")
             merkleRoot = payload.merkle_root;

package/dist/evidence.js

@@ -466,6 +466,11 @@ async function verifyAnchorTrace(b, bodyType, specVersionOk, assertedStatus, err
             }
             if (res.payloadHashOk === false)
                 cpErrors.push("checkpoint record does not bind to payload_hash");
+            // proof#95: a malformed skeleton field fails the envelope with a valid
+            // signature and binding; name it rather than fail with no reason.
+            for (const m of res.errors)
+                if (m.startsWith("malformed "))
+                    cpErrors.push(`checkpoint envelope ${m}`);
             // WHY the binding is undetermined decides which sentence is true.
             // record_bytes really absent is one thing; record_bytes present and
             // unbindable (a degenerate envelope, unreadable hex) is another, and
@@ -564,6 +569,11 @@ async function verifyAnchorTrace(b, bodyType, specVersionOk, assertedStatus, err
             }
             if (res.payloadHashOk === false)
                 evErrors.push("event record does not bind to payload_hash");
+            // A malformed skeleton field fails the envelope with a valid signature
+            // and binding (proof#95), so without this the event fails with no reason.
+            for (const m of res.errors)
+                if (m.startsWith("malformed "))
+                    evErrors.push(`event envelope ${m}`);
         }
         catch (e) {
             evErrors.push(`event envelope verify error: ${stringifyErr(e)}`);
@@ -1234,6 +1244,11 @@ async function verifyStampEvidence(b, specVersionOk, assertedStatus, errors, opt
             }
             if (res.payloadHashOk === false)
                 evErrors.push("event record does not bind to payload_hash");
+            // A malformed skeleton field fails the envelope with a valid signature
+            // and binding (proof#95), so without this the event fails with no reason.
+            for (const m of res.errors)
+                if (m.startsWith("malformed "))
+                    evErrors.push(`event envelope ${m}`);
         }
         catch (e) {
             evErrors.push(`event envelope verify error: ${stringifyErr(e)}`);

package/dist/verifier.d.ts

@@ -4,6 +4,7 @@ export declare const MAX_CANONICAL_DEPTH = 128;
 export declare function exceedsDepth(value: unknown, max: number): boolean;
 export declare function jcs(value: unknown): string;
 export declare function specVersionSupported(specVersion: string): boolean;
+export declare function isRfc3339UtcInstant(value: unknown): boolean;
 export declare function contentHashes(env: Envelope): {
     role: ContentRole;
     hash: string;

package/dist/verifier.js

@@ -93,11 +93,27 @@ function resolveToJSON(node, max) {
 // bound exists to prevent, reached through the bound (proof#71 review). Copying
 // what was measured is what makes check and use the same value. It also settles
 // a getter, which is read once here and never re-read.
+//
+// Every object copy has a NULL prototype, and that is load-bearing too. RFC
+// 8785 has no reserved member names, and `JSON.parse` keeps `__proto__` as an
+// ordinary own key. On a plain `{}`, `copy["__proto__"] = x` runs the setter
+// inherited from `Object.prototype`: it replaces the copy's prototype and
+// creates no key, so the member and everything under it vanished from the
+// canonical bytes. Content there was covered by no hash and no signature, and
+// this kernel disagreed with the Python and Go kernels on the same bytes
+// (0.9.0; the same bug class as proof#31 and proof#34). With no prototype
+// there is no setter, so every key, `__proto__` included, lands as an own data
+// property. `canonicalize` reads the copy with `Object.keys` and `object[key]`
+// and tests `toJSON instanceof Function`, none of which a prototype affects
+// for JSON data, so no other input's output changes.
+function emptyObject() {
+    return Object.create(null);
+}
 function boundedInput(value, max) {
     const root = resolveToJSON(value, max);
     if (root === OVER_DEEP || root === null || typeof root !== "object")
         return root;
-    const copy = Array.isArray(root) ? [] : {};
+    const copy = Array.isArray(root) ? [] : emptyObject();
     const stack = [[root, copy, 1]];
     while (stack.length > 0) {
         const [src, dst, depth] = stack.pop();
@@ -113,7 +129,7 @@ function boundedInput(value, max) {
             }
             if (depth + 1 > max)
                 return OVER_DEEP; // a container nested past the bound
-            const childCopy = Array.isArray(child) ? [] : {};
+            const childCopy = Array.isArray(child) ? [] : emptyObject();
             dst[key] = childCopy;
             stack.push([child, childCopy, depth + 1]);
         }
@@ -212,6 +228,57 @@ export function specVersionSupported(specVersion) {
         return minor.length > 0 && /^[0-9]+$/.test(minor);
     });
 }
+// `signed_at` format (envelope-spec §2: "RFC 3339 UTC, `Z`"), proof#95. The
+// accepted form is RFC 3339 `date-time` narrowed three ways, identically in
+// every kernel:
+//   - the zone is an uppercase `Z`: never a numeric offset (not even
+//     `+00:00`), never a lowercase `z` or `t`;
+//   - the date is a real proleptic Gregorian date from 0001-01-01 to
+//     9999-12-31, so February 29 only in a leap year;
+//   - second 60 is refused. RFC 3339 allows it at a real leap second, but
+//     which instants those were needs a table, and JavaScript's `Date`,
+//     Python's `datetime` and Go's `time` cannot hold one, so a verified `:60`
+//     would fail the first consumer that parses it.
+// Fractional seconds of any length are allowed. Digits are ASCII `[0-9]`
+// (Python's `\d` matches any Unicode digit, so the Python kernel spells it the
+// same way).
+const RFC3339_UTC = /^([0-9]{4})-([0-9]{2})-([0-9]{2})T([0-9]{2}):([0-9]{2}):([0-9]{2})(?:\.[0-9]+)?Z$/;
+const DAYS_IN_MONTH = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+export function isRfc3339UtcInstant(value) {
+    if (typeof value !== "string")
+        return false;
+    const m = RFC3339_UTC.exec(value);
+    if (m === null)
+        return false;
+    const [year, month, day, hour, minute, second] = m.slice(1).map(Number);
+    if (year < 1 || month < 1 || month > 12 || day < 1)
+        return false;
+    const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+    const days = month === 2 && leap ? 29 : DAYS_IN_MONTH[month - 1];
+    return day <= days && hour <= 23 && minute <= 59 && second <= 59;
+}
+// The skeleton fields whose FORMAT §2 fixes and no other check reaches: a
+// correctly signed envelope with `signed_at: "2026-02-30T00:00:00Z"` or
+// `environment: "prod\u0000uction"` passes the signature and the payload
+// binding, so without this it verified in full. Each is checked only when
+// present: §2 flags an absent `signed_at` as non-conformant rather than
+// rejecting it, and `environment` is optional in the skeleton.
+//
+// Own properties only, because those are the members `jcs` signs over.
+function skeletonFieldErrors(env) {
+    const fields = env;
+    const own = (k) => (Object.prototype.hasOwnProperty.call(fields, k) ? fields[k] : undefined);
+    const out = [];
+    const signedAt = own("signed_at");
+    if (signedAt !== undefined && !isRfc3339UtcInstant(signedAt)) {
+        out.push("malformed signed_at: not an RFC 3339 UTC date-time with Z naming a real date and time (envelope-spec §2)");
+    }
+    const environment = own("environment");
+    if (environment !== undefined && environment !== "dev" && environment !== "production") {
+        out.push('malformed environment: not "dev" or "production" (envelope-spec §2)');
+    }
+    return out;
+}
 // The content hash(es) an envelope commits to, by event type — the values a
 // reverse lookup can match the user's in-browser file hash against.
 //   asset_registered -> payload.hash            (the registered, known-good bytes)
@@ -323,6 +390,13 @@ export async function verifyEnvelope(env, optionsOrContentHash) {
     const specVersionOk = specVersionSupported(env.spec_version);
     if (!specVersionOk)
         errors.push(`unsupported spec_version: ${JSON.stringify(env.spec_version)}`);
+    // Skeleton field format (envelope-spec §2, proof#95): a present `signed_at`
+    // or `environment` that is not what §2 says fails the verdict. There is no
+    // result field for it, so the verdict shape is unchanged for every envelope
+    // the spec allows; the reason is in `errors`.
+    const fieldErrors = skeletonFieldErrors(env);
+    errors.push(...fieldErrors);
+    const fieldsOk = fieldErrors.length === 0;
     // Check 1 — Payload binding (both modes; see header).
     //
     // payload_hash MUST be present and a string in every mode — envelope-spec
@@ -423,7 +497,7 @@ export async function verifyEnvelope(env, optionsOrContentHash) {
         //
         // Absence stays undetermined: `contentHashOk` is null when no hash was
         // supplied, and null must not fail (P-10 — absence is not failure).
-        ok: specVersionOk && signatureOk && payloadHashOk !== false && contentHashOk !== false,
+        ok: specVersionOk && fieldsOk && signatureOk && payloadHashOk !== false && contentHashOk !== false,
         specVersionOk,
         payloadHashOk,
         signatureOk,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanning/proof",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "TypeScript kernel of the Sanning verification stack: RFC 8785 (JCS) canonicalization, SHA-256, and Ed25519 verification for Verifiable Event Envelopes. Full-family verifier (inline + external commitment); accepts sanning.agent/v1, sanning.mlflow/v1, sanning.events/v1. Conformance-gated byte-for-byte against the test-vectors corpus.",
   "license": "MIT",
   "type": "module",

package/src/agent-proof.ts

@@ -118,6 +118,9 @@ export async function verifyAgentProofBundle(
     checkpointOk = res.ok && res.payloadHashOk === true;
     if (!res.signatureOk) errors.push("checkpoint envelope signature failed");
     if (res.payloadHashOk !== true) errors.push("checkpoint envelope payload binding failed");
+    // A malformed skeleton field (proof#95) fails the envelope with a valid
+    // signature and binding; name it rather than fail with no reason.
+    for (const m of res.errors) if (m.startsWith("malformed ")) errors.push(`checkpoint envelope ${m}`);
     const payload = (b.checkpoint_envelope.payload ?? {}) as {
       merkle_root?: unknown;
       leaf_count?: unknown;

package/src/evidence.ts

@@ -1082,6 +1082,9 @@ async function verifyAnchorTrace(
         cpErrors.push("checkpoint envelope signature failed");
       }
       if (res.payloadHashOk === false) cpErrors.push("checkpoint record does not bind to payload_hash");
+      // proof#95: a malformed skeleton field fails the envelope with a valid
+      // signature and binding; name it rather than fail with no reason.
+      for (const m of res.errors) if (m.startsWith("malformed ")) cpErrors.push(`checkpoint envelope ${m}`);
       // WHY the binding is undetermined decides which sentence is true.
       // record_bytes really absent is one thing; record_bytes present and
       // unbindable (a degenerate envelope, unreadable hex) is another, and
@@ -1187,6 +1190,9 @@ async function verifyAnchorTrace(
         evErrors.push("event envelope signature failed");
       }
       if (res.payloadHashOk === false) evErrors.push("event record does not bind to payload_hash");
+      // A malformed skeleton field fails the envelope with a valid signature
+      // and binding (proof#95), so without this the event fails with no reason.
+      for (const m of res.errors) if (m.startsWith("malformed ")) evErrors.push(`event envelope ${m}`);
     } catch (e) {
       evErrors.push(`event envelope verify error: ${stringifyErr(e)}`);
     }
@@ -1938,6 +1944,9 @@ async function verifyStampEvidence(
         evErrors.push("event envelope signature failed");
       }
       if (res.payloadHashOk === false) evErrors.push("event record does not bind to payload_hash");
+      // A malformed skeleton field fails the envelope with a valid signature
+      // and binding (proof#95), so without this the event fails with no reason.
+      for (const m of res.errors) if (m.startsWith("malformed ")) evErrors.push(`event envelope ${m}`);
     } catch (e) {
       evErrors.push(`event envelope verify error: ${stringifyErr(e)}`);
     }

package/src/verifier.ts

@@ -103,10 +103,27 @@ function resolveToJSON(node: unknown, max: number): unknown {
 // bound exists to prevent, reached through the bound (proof#71 review). Copying
 // what was measured is what makes check and use the same value. It also settles
 // a getter, which is read once here and never re-read.
+//
+// Every object copy has a NULL prototype, and that is load-bearing too. RFC
+// 8785 has no reserved member names, and `JSON.parse` keeps `__proto__` as an
+// ordinary own key. On a plain `{}`, `copy["__proto__"] = x` runs the setter
+// inherited from `Object.prototype`: it replaces the copy's prototype and
+// creates no key, so the member and everything under it vanished from the
+// canonical bytes. Content there was covered by no hash and no signature, and
+// this kernel disagreed with the Python and Go kernels on the same bytes
+// (0.9.0; the same bug class as proof#31 and proof#34). With no prototype
+// there is no setter, so every key, `__proto__` included, lands as an own data
+// property. `canonicalize` reads the copy with `Object.keys` and `object[key]`
+// and tests `toJSON instanceof Function`, none of which a prototype affects
+// for JSON data, so no other input's output changes.
+function emptyObject(): Record<string, unknown> {
+  return Object.create(null) as Record<string, unknown>;
+}
+
 function boundedInput(value: unknown, max: number): unknown {
   const root = resolveToJSON(value, max);
   if (root === OVER_DEEP || root === null || typeof root !== "object") return root;
-  const copy: Record<string, unknown> | unknown[] = Array.isArray(root) ? [] : {};
+  const copy: Record<string, unknown> | unknown[] = Array.isArray(root) ? [] : emptyObject();
   const stack: Array<[object, Record<string, unknown> | unknown[], number]> = [[root, copy, 1]];
   while (stack.length > 0) {
     const [src, dst, depth] = stack.pop()!;
@@ -120,7 +137,7 @@ function boundedInput(value: unknown, max: number): unknown {
         continue;
       }
       if (depth + 1 > max) return OVER_DEEP; // a container nested past the bound
-      const childCopy: Record<string, unknown> | unknown[] = Array.isArray(child) ? [] : {};
+      const childCopy: Record<string, unknown> | unknown[] = Array.isArray(child) ? [] : emptyObject();
       (dst as Record<string, unknown>)[key] = childCopy;
       stack.push([child, childCopy, depth + 1]);
     }
@@ -224,6 +241,57 @@ export function specVersionSupported(specVersion: string): boolean {
   });
 }
 
+// `signed_at` format (envelope-spec §2: "RFC 3339 UTC, `Z`"), proof#95. The
+// accepted form is RFC 3339 `date-time` narrowed three ways, identically in
+// every kernel:
+//   - the zone is an uppercase `Z`: never a numeric offset (not even
+//     `+00:00`), never a lowercase `z` or `t`;
+//   - the date is a real proleptic Gregorian date from 0001-01-01 to
+//     9999-12-31, so February 29 only in a leap year;
+//   - second 60 is refused. RFC 3339 allows it at a real leap second, but
+//     which instants those were needs a table, and JavaScript's `Date`,
+//     Python's `datetime` and Go's `time` cannot hold one, so a verified `:60`
+//     would fail the first consumer that parses it.
+// Fractional seconds of any length are allowed. Digits are ASCII `[0-9]`
+// (Python's `\d` matches any Unicode digit, so the Python kernel spells it the
+// same way).
+const RFC3339_UTC = /^([0-9]{4})-([0-9]{2})-([0-9]{2})T([0-9]{2}):([0-9]{2}):([0-9]{2})(?:\.[0-9]+)?Z$/;
+const DAYS_IN_MONTH = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+
+export function isRfc3339UtcInstant(value: unknown): boolean {
+  if (typeof value !== "string") return false;
+  const m = RFC3339_UTC.exec(value);
+  if (m === null) return false;
+  const [year, month, day, hour, minute, second] = m.slice(1).map(Number);
+  if (year < 1 || month < 1 || month > 12 || day < 1) return false;
+  const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+  const days = month === 2 && leap ? 29 : DAYS_IN_MONTH[month - 1];
+  return day <= days && hour <= 23 && minute <= 59 && second <= 59;
+}
+
+// The skeleton fields whose FORMAT §2 fixes and no other check reaches: a
+// correctly signed envelope with `signed_at: "2026-02-30T00:00:00Z"` or
+// `environment: "prod\u0000uction"` passes the signature and the payload
+// binding, so without this it verified in full. Each is checked only when
+// present: §2 flags an absent `signed_at` as non-conformant rather than
+// rejecting it, and `environment` is optional in the skeleton.
+//
+// Own properties only, because those are the members `jcs` signs over.
+function skeletonFieldErrors(env: Envelope): string[] {
+  const fields = env as unknown as Record<string, unknown>;
+  const own = (k: string): unknown => (Object.prototype.hasOwnProperty.call(fields, k) ? fields[k] : undefined);
+  const out: string[] = [];
+  const signedAt = own("signed_at");
+  if (signedAt !== undefined && !isRfc3339UtcInstant(signedAt)) {
+    out.push("malformed signed_at: not an RFC 3339 UTC date-time with Z naming a real date and time (envelope-spec §2)");
+  }
+  const environment = own("environment");
+  if (environment !== undefined && environment !== "dev" && environment !== "production") {
+    out.push('malformed environment: not "dev" or "production" (envelope-spec §2)');
+  }
+  return out;
+}
+
 // The content hash(es) an envelope commits to, by event type — the values a
 // reverse lookup can match the user's in-browser file hash against.
 //   asset_registered -> payload.hash            (the registered, known-good bytes)
@@ -345,6 +413,14 @@ export async function verifyEnvelope(
   const specVersionOk = specVersionSupported(env.spec_version);
   if (!specVersionOk) errors.push(`unsupported spec_version: ${JSON.stringify(env.spec_version)}`);
 
+  // Skeleton field format (envelope-spec §2, proof#95): a present `signed_at`
+  // or `environment` that is not what §2 says fails the verdict. There is no
+  // result field for it, so the verdict shape is unchanged for every envelope
+  // the spec allows; the reason is in `errors`.
+  const fieldErrors = skeletonFieldErrors(env);
+  errors.push(...fieldErrors);
+  const fieldsOk = fieldErrors.length === 0;
+
   // Check 1 — Payload binding (both modes; see header).
   //
   // payload_hash MUST be present and a string in every mode — envelope-spec
@@ -449,7 +525,7 @@ export async function verifyEnvelope(
     //
     // Absence stays undetermined: `contentHashOk` is null when no hash was
     // supplied, and null must not fail (P-10 — absence is not failure).
-    ok: specVersionOk && signatureOk && payloadHashOk !== false && contentHashOk !== false,
+    ok: specVersionOk && fieldsOk && signatureOk && payloadHashOk !== false && contentHashOk !== false,
     specVersionOk,
     payloadHashOk,
     signatureOk,