@sanning/proof 0.12.0 → 0.14.0

package/dist/zip-reader.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The one ZIP reader `case` uses, for a case file named on the command line.
+ *
+ * The TypeScript half of `src/sanning_proof/zip_reader.py`. Node has no ZIP
+ * reader, and Python's `zipfile` is not used, so the two kernels read one
+ * archive by one rule rather than by two libraries that disagree on the edges:
+ * a central directory that contradicts a local header, a name that is not
+ * UTF-8, data after the end of a deflate stream. Where either library would
+ * have made a choice, this module refuses instead.
+ *
+ * What it reads (evidence-bundle.md 5.6.1): the central directory, and each
+ * entry's data through its local header. Stored and deflate only. What it
+ * REFUSES, as a whole archive: no end-of-central-directory record, ZIP64, more
+ * than one disk, an entry the central directory places outside the archive, a
+ * local header that does not match its central entry, a size or CRC-32 that
+ * does not match the data, two entries with one name, a name that is not
+ * UTF-8, more than MAX_ZIP_ENTRIES entries or MAX_ZIP_BYTES bytes in all, and
+ * a name nested deeper than MAX_ZIP_DEPTH folders. What it REPORTS and never
+ * reads, entry by entry: an encrypted entry, a symbolic link, a method other
+ * than stored or deflate, and a name that is absolute, holds a backslash or a
+ * NUL, or has an empty, `.` or `..` segment.
+ *
+ * Pure: bytes in, entries out. The caller turns them into the tree `case`
+ * splits.
+ */
+/** More entries than this refuse the archive: the walk's own bound on names. */
+export declare const MAX_ZIP_ENTRIES = 50000;
+/** More uncompressed bytes than this, across every entry, refuse the archive. */
+export declare const MAX_ZIP_BYTES: number;
+/** A name nested deeper than this many folders refuses the archive. */
+export declare const MAX_ZIP_DEPTH = 32;
+/** The archive cannot be read as a case file. `message` is the whole report, identical in both kernels. */
+export declare class ZipReadError extends Error {
+    constructor(message: string);
+}
+/**
+ * One file entry. `refused` is why the entry is reported and not read, or
+ * `null`; `data` is its bytes where it was read.
+ */
+export interface ZipEntry {
+    name: string;
+    refused: string | null;
+    data: Uint8Array | null;
+}
+/**
+ * Every FILE entry of a ZIP archive, in central-directory order. A directory
+ * entry (a name ending in `/`) is not a file and is not returned. Throws
+ * `ZipReadError`.
+ */
+export declare function readZip(data: Uint8Array): ZipEntry[];

package/dist/zip-reader.js

@@ -0,0 +1,220 @@
+/**
+ * The one ZIP reader `case` uses, for a case file named on the command line.
+ *
+ * The TypeScript half of `src/sanning_proof/zip_reader.py`. Node has no ZIP
+ * reader, and Python's `zipfile` is not used, so the two kernels read one
+ * archive by one rule rather than by two libraries that disagree on the edges:
+ * a central directory that contradicts a local header, a name that is not
+ * UTF-8, data after the end of a deflate stream. Where either library would
+ * have made a choice, this module refuses instead.
+ *
+ * What it reads (evidence-bundle.md 5.6.1): the central directory, and each
+ * entry's data through its local header. Stored and deflate only. What it
+ * REFUSES, as a whole archive: no end-of-central-directory record, ZIP64, more
+ * than one disk, an entry the central directory places outside the archive, a
+ * local header that does not match its central entry, a size or CRC-32 that
+ * does not match the data, two entries with one name, a name that is not
+ * UTF-8, more than MAX_ZIP_ENTRIES entries or MAX_ZIP_BYTES bytes in all, and
+ * a name nested deeper than MAX_ZIP_DEPTH folders. What it REPORTS and never
+ * reads, entry by entry: an encrypted entry, a symbolic link, a method other
+ * than stored or deflate, and a name that is absolute, holds a backslash or a
+ * NUL, or has an empty, `.` or `..` segment.
+ *
+ * Pure: bytes in, entries out. The caller turns them into the tree `case`
+ * splits.
+ */
+import { inflateRawSync } from "node:zlib";
+import { utf8Strict } from "./verifier.js";
+/** More entries than this refuse the archive: the walk's own bound on names. */
+export const MAX_ZIP_ENTRIES = 50_000;
+/** More uncompressed bytes than this, across every entry, refuse the archive. */
+export const MAX_ZIP_BYTES = 2 ** 30;
+/** A name nested deeper than this many folders refuses the archive. */
+export const MAX_ZIP_DEPTH = 32;
+const EOCD = 0x06054b50;
+const CENTRAL = 0x02014b50;
+const LOCAL = 0x04034b50;
+const S_IFMT = 0o170000;
+const S_IFLNK = 0o120000;
+const UNIX = 3;
+/** The archive cannot be read as a case file. `message` is the whole report, identical in both kernels. */
+export class ZipReadError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ZipReadError";
+    }
+}
+const CRC_TABLE = (() => {
+    const table = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        table[n] = c >>> 0;
+    }
+    return table;
+})();
+function crc32(bytes) {
+    let c = 0xffffffff;
+    for (let i = 0; i < bytes.length; i++)
+        c = CRC_TABLE[(c ^ bytes[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+function refusal(name) {
+    if (name.startsWith("/"))
+        return "an absolute name";
+    if (name.includes("\\"))
+        return "a name with a backslash";
+    if (name.includes("\u0000"))
+        return "a name with a NUL";
+    for (const segment of name.split("/")) {
+        if (segment === "" || segment === "." || segment === "..") {
+            return "a name with an empty, . or .. segment";
+        }
+    }
+    return null;
+}
+function sameBytes(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+/**
+ * Every FILE entry of a ZIP archive, in central-directory order. A directory
+ * entry (a name ending in `/`) is not a file and is not returned. Throws
+ * `ZipReadError`.
+ */
+export function readZip(data) {
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    const n = data.length;
+    const u32 = (at) => view.getUint32(at, true);
+    const u16 = (at) => view.getUint16(at, true);
+    // The end-of-central-directory record: 22 bytes plus a comment of at most
+    // 65535, searched backwards so the LAST signature wins.
+    let eocd = -1;
+    const lowest = Math.max(0, n - 22 - 0xffff);
+    for (let at = n - 22; at >= lowest; at--) {
+        if (u32(at) === EOCD && at + 22 + u16(at + 20) === n) {
+            eocd = at;
+            break;
+        }
+    }
+    if (eocd < 0)
+        throw new ZipReadError("is not a readable .zip archive");
+    const disk = u16(eocd + 4);
+    const cdDisk = u16(eocd + 6);
+    const hereCount = u16(eocd + 8);
+    const count = u16(eocd + 10);
+    const cdSize = u32(eocd + 12);
+    const cdOffset = u32(eocd + 16);
+    if (count === 0xffff || cdSize === 0xffffffff || cdOffset === 0xffffffff) {
+        throw new ZipReadError("is a ZIP64 archive, which case does not read");
+    }
+    if (disk !== 0 || cdDisk !== 0 || hereCount !== count) {
+        throw new ZipReadError("spans more than one disk, which case does not read");
+    }
+    if (count > MAX_ZIP_ENTRIES) {
+        throw new ZipReadError(`holds more than ${MAX_ZIP_ENTRIES} entries; refusing to read it`);
+    }
+    if (cdOffset + cdSize > eocd)
+        throw new ZipReadError("is not a readable .zip archive");
+    const entries = [];
+    const names = new Set();
+    let total = 0;
+    let at = cdOffset;
+    for (let e = 0; e < count; e++) {
+        if (at + 46 > eocd || u32(at) !== CENTRAL) {
+            throw new ZipReadError("is not a readable .zip archive");
+        }
+        const madeBy = u16(at + 4);
+        const flags = u16(at + 8);
+        const method = u16(at + 10);
+        const crc = u32(at + 16);
+        const csize = u32(at + 20);
+        const usize = u32(at + 24);
+        const nameLen = u16(at + 28);
+        const extraLen = u16(at + 30);
+        const commentLen = u16(at + 32);
+        const external = u32(at + 38);
+        const localAt = u32(at + 42);
+        const rawName = data.subarray(at + 46, at + 46 + nameLen);
+        at += 46 + nameLen + extraLen + commentLen;
+        if (at > eocd)
+            throw new ZipReadError("is not a readable .zip archive");
+        let name;
+        try {
+            name = utf8Strict(rawName);
+        }
+        catch {
+            throw new ZipReadError("holds a name that is not valid UTF-8; rename it, then run case again");
+        }
+        if (names.has(name))
+            throw new ZipReadError(`holds ${name} twice`);
+        names.add(name);
+        if (name.endsWith("/"))
+            continue;
+        if (name.split("/").length - 1 > MAX_ZIP_DEPTH) {
+            throw new ZipReadError(`is nested more than ${MAX_ZIP_DEPTH} folders deep; refusing to read it`);
+        }
+        let refused = refusal(name);
+        if (refused === null && flags & 0x1)
+            refused = "an encrypted entry";
+        if (refused === null &&
+            madeBy >> 8 === UNIX &&
+            ((external >>> 16) & S_IFMT) === S_IFLNK) {
+            refused = "a symbolic link";
+        }
+        if (refused === null && method !== 0 && method !== 8) {
+            refused = "a compression method other than stored or deflate";
+        }
+        if (refused !== null) {
+            entries.push({ name, refused, data: null });
+            continue;
+        }
+        total += usize;
+        if (total > MAX_ZIP_BYTES) {
+            throw new ZipReadError(`holds more than ${MAX_ZIP_BYTES} bytes uncompressed; refusing to read it`);
+        }
+        const unreadable = () => new ZipReadError(`holds ${name}, which cannot be read`);
+        if (localAt + 30 > cdOffset || u32(localAt) !== LOCAL)
+            throw unreadable();
+        const localNameLen = u16(localAt + 26);
+        const localExtraLen = u16(localAt + 28);
+        if (!sameBytes(data.subarray(localAt + 30, localAt + 30 + localNameLen), rawName)) {
+            throw unreadable();
+        }
+        const start = localAt + 30 + localNameLen + localExtraLen;
+        if (start + csize > cdOffset)
+            throw unreadable();
+        const packed = data.subarray(start, start + csize);
+        let body;
+        if (method === 0) {
+            body = packed;
+        }
+        else {
+            // `info: true` hands back the engine, whose `bytesWritten` is how many
+            // input bytes the stream consumed. Anything left over is data after the
+            // end of the deflate stream, which Python's `unused_data` refuses too.
+            let result;
+            try {
+                result = inflateRawSync(packed, {
+                    info: true,
+                    maxOutputLength: usize + 1,
+                });
+            }
+            catch {
+                throw unreadable();
+            }
+            if (result.engine.bytesWritten !== packed.length)
+                throw unreadable();
+            body = new Uint8Array(result.buffer.buffer, result.buffer.byteOffset, result.buffer.length);
+        }
+        if (body.length !== usize || crc32(body) !== crc)
+            throw unreadable();
+        entries.push({ name, refused: null, data: body.slice() });
+    }
+    return entries;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanning/proof",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "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 and sanning.events/v2. Conformance-gated byte-for-byte against the test-vectors corpus.",
   "license": "MIT",
   "type": "module",
@@ -14,7 +14,7 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "proof": "./dist/cli.js"
+    "sanning-proof": "./dist/cli.js"
   },
   "files": [
     "src",

package/src/agent-proof.ts

@@ -1,4 +1,4 @@
-// Agent inclusion-proof bundle verification.
+// Agent inclusion proof verification (`sanning.agent.proof/v1`).
 //
 // The `sanning.agent.proof/v1` bundle is the agent's ~1.4 KB self-contained
 // inclusion proof: a signed checkpoint envelope (sanning.agent/v1, INLINE payload)
@@ -19,7 +19,7 @@ import { leafHash, verifyInclusion } from "./merkle.js";
 import { MAX_CANONICAL_DEPTH, exceedsDepth, jcs, jcsParse, verifyEnvelope } from "./verifier.js";
 import type { Envelope } from "./types.js";
 
-export const AGENT_PROOF_SPEC_PREFIX = "sanning.agent.proof/v1";
+export const AGENT_PROOF_SPEC_VERSION = "sanning.agent.proof/v1";
 
 export interface AgentProofBundle {
   spec_version: string;
@@ -63,10 +63,10 @@ function toHex(bytes: Uint8Array): string {
 
 export function isAgentProofSpec(specVersion: unknown): boolean {
   if (typeof specVersion !== "string") return false;
-  return specVersion === AGENT_PROOF_SPEC_PREFIX || specVersion.startsWith(`${AGENT_PROOF_SPEC_PREFIX}.`);
+  return specVersion === AGENT_PROOF_SPEC_VERSION || specVersion.startsWith(`${AGENT_PROOF_SPEC_VERSION}.`);
 }
 
-export async function verifyAgentProofBundle(
+export async function verifyAgentProof(
   bundle: unknown,
   options: VerifyAgentProofOptions = {},
 ): Promise<AgentProofResult> {