@ar.io/proof 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ar.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# @ar.io/proof
+
+> TypeScript kernel of the ar.io verification stack — verify a Verifiable Event
+> Envelope with no ar.io service in the trust path.
+
+The verification primitives for the envelope family specified in
+`ar-io-agent/docs/envelope-spec.md` (ario.agent/v1 profile per `artifact.md`):
+
+- **RFC 8785 (JCS)** canonicalization (`jcs`)
+- **SHA-256** (`sha256Hex`) via WebCrypto
+- **Ed25519** signature verification (`ed25519Verify`, via `@noble/ed25519` with
+  the SHA-512 hook wired to WebCrypto)
+- **`verifyEnvelope(env, expectedContentHash?)`** — the three load-bearing checks
+  (spec-version registry, `payload_hash` recompute, Ed25519 over the signed
+  scope) plus the optional content-hash bind
+- **`contentHashes(env)`** — which payload hash(es) an envelope commits to, by
+  event type (the reverse-provenance join keys)
+- **RFC 9162 binary Merkle tree** (`leafHash`, `nodeHash`, `merkleRoot`,
+  `auditPath`, `verifyInclusion`, `EMPTY_TREE_ROOT_HEX`) — §2.1 domain
+  separation, largest-power-of-two split (not the Bitcoin duplicate-leaf
+  variant), conformance-gated against the corpus's 7 Merkle vectors; parity
+  with the Python kernel's `ario_proof.merkle`
+
+This is the TypeScript sibling of the Python [`ar-io-proof`](https://github.com/ar-io/ar-io-proof)
+kernel and the Go reference (`ar-io-agent/pkg/proof`). All three are independent
+implementations of the same algorithm, each conformance-gated **byte-for-byte**
+against the shared `test-vectors-v1.0` corpus — that mutual gate is the
+product's core claim: verification needs no ar.io code in the trust path.
+
+## Signed scope
+
+The primary signature covers `JCS(envelope minus signature minus co_signatures)`
+(envelope-spec §2, §7.1). The `co_signatures` carve-out lets a countersignature
+be added without invalidating the primary signature; the field is reserved and
+default-absent, and its absence is never a failure.
+
+## Spec-version acceptance
+
+Fail-closed registry (`specVersionSupported`): exactly the accepted majors —
+`ario.agent/v1` and additive minors within it (`ario.agent/v1.<minor>`),
+matching the Go reference's semantics. Unknown majors and other profiles are
+rejected. The mlflow profile (`ario.mlflow/v1`) is a deliberate later one-entry
+addition, **not** implemented here — mlflow-dialect behaviors (e.g. the
+underscore-key strip) must not leak into the agent profile.
+
+## Workspace status
+
+Lives as an npm workspace inside `ar-io-proof-checker` (v1.2 wave decision —
+no separate repo yet); the checker consumes it as its verifier. **Not yet
+published to npm.** Before any publish: confirm the real npm scope (`@ar.io/`
+vs `@ar-io/`), flip `exports` to the built `dist/` output (`npm run build`
+emits ESM + type declarations), and get the coordinator's green light.
+
+MIT — verification must be open. See `LICENSE`.

package/dist/crypto.d.ts

@@ -0,0 +1,6 @@
+export declare function bytesToHex(bytes: Uint8Array): string;
+export declare function hexToBytes(hex: string): Uint8Array;
+export declare function utf8(s: string): Uint8Array;
+export declare function sha256Bytes(bytes: Uint8Array): Promise<Uint8Array>;
+export declare function sha256Hex(bytes: Uint8Array): Promise<string>;
+export declare function ed25519Verify(signatureHex: string, message: Uint8Array, publicKeyHex: string): Promise<boolean>;

package/dist/crypto.js

@@ -0,0 +1,59 @@
+// Low-level cryptographic primitives for the verifier. Deliberately thin: the
+// only third-party crypto dependency is @noble/ed25519 (single-file, audited,
+// zero-dependency). SHA-256 and SHA-512 come from WebCrypto — no extra hashing
+// library to trust.
+import * as ed from "@noble/ed25519";
+// @noble/ed25519 needs SHA-512 to verify. Wire it to WebCrypto rather than
+// pulling in @noble/hashes. globalThis.crypto.subtle exists in every modern
+// browser and in Node >= 19, so the same code path runs in the app and in tests.
+ed.etc.sha512Async = async (...msgs) => new Uint8Array(await crypto.subtle.digest("SHA-512", asBufferSource(ed.etc.concatBytes(...msgs))));
+// WebCrypto's digest() wants a BufferSource backed by a (non-shared) ArrayBuffer.
+// Our byte arrays always are; this keeps TS 5.7's stricter Uint8Array<ArrayBufferLike>
+// typing satisfied without a runtime copy.
+function asBufferSource(bytes) {
+    return bytes;
+}
+export function bytesToHex(bytes) {
+    let out = "";
+    for (const b of bytes)
+        out += b.toString(16).padStart(2, "0");
+    return out;
+}
+export function hexToBytes(hex) {
+    if (hex.length % 2 !== 0)
+        throw new Error("hexToBytes: odd-length string");
+    // Full validation: parseInt() partially parses ("1g" -> 1), which would let
+    // malformed hex through. A strict charset check closes that.
+    if (!/^[0-9a-fA-F]*$/.test(hex))
+        throw new Error("hexToBytes: non-hex characters");
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        out[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+}
+export function utf8(s) {
+    return new TextEncoder().encode(s);
+}
+export async function sha256Bytes(bytes) {
+    return new Uint8Array(await crypto.subtle.digest("SHA-256", asBufferSource(bytes)));
+}
+export async function sha256Hex(bytes) {
+    return bytesToHex(await sha256Bytes(bytes));
+}
+// Verify an Ed25519 signature. Inputs are hex (signature, public key) as they
+// appear in the envelope; message is raw bytes. Never throws — a malformed
+// signature or key is "not verified," not an exception, so a hostile envelope
+// can't crash the checker.
+export async function ed25519Verify(signatureHex, message, publicKeyHex) {
+    try {
+        // zip215:false → strict RFC-8032 verification, matching the Go agent's
+        // crypto/ed25519 exactly (noble defaults to the more lenient zip215:true).
+        return await ed.verifyAsync(hexToBytes(signatureHex), message, hexToBytes(publicKeyHex), {
+            zip215: false,
+        });
+    }
+    catch {
+        return false;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { contentHashes, jcs, specVersionSupported, verifyEnvelope } from "./verifier";
+export { bytesToHex, ed25519Verify, hexToBytes, sha256Bytes, sha256Hex, utf8 } from "./crypto";
+export { EMPTY_TREE_ROOT_HEX, auditPath, leafHash, merkleRoot, nodeHash, verifyInclusion, } from "./merkle";
+export type { ContentRole, Envelope, Subject, VerificationResult } from "./types";

package/dist/index.js

@@ -0,0 +1,15 @@
+// @ar.io/proof — TypeScript kernel of the ar.io verification stack.
+//
+// The verification primitives for the Verifiable Event Envelope family
+// (ar-io-agent docs/envelope-spec.md), ario.agent/v1 profile: RFC 8785 (JCS)
+// canonicalization, SHA-256, Ed25519 envelope verification, and the
+// content-hash extraction used for reverse provenance lookup. Sibling of the
+// Python `ar-io-proof` kernel and the Go `pkg/proof` reference; conformance
+// is byte-for-byte against the shared `test-vectors-v1.0` corpus.
+//
+// Scope boundary (envelope-spec §10 #13): this package verifies a SINGLE
+// envelope. Chain walking (previous_hash), checkpoint reconciliation, and
+// gateway/transport concerns are consumer-layer logic composed above it.
+export { contentHashes, jcs, specVersionSupported, verifyEnvelope } from "./verifier";
+export { bytesToHex, ed25519Verify, hexToBytes, sha256Bytes, sha256Hex, utf8 } from "./crypto";
+export { EMPTY_TREE_ROOT_HEX, auditPath, leafHash, merkleRoot, nodeHash, verifyInclusion, } from "./merkle";

package/dist/merkle.d.ts

@@ -0,0 +1,6 @@
+export declare const EMPTY_TREE_ROOT_HEX = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+export declare function leafHash(leafBytes: Uint8Array): Promise<Uint8Array>;
+export declare function nodeHash(left: Uint8Array, right: Uint8Array): Promise<Uint8Array>;
+export declare function merkleRoot(leafHashes: Uint8Array[]): Promise<Uint8Array>;
+export declare function auditPath(m: number, leafHashes: Uint8Array[]): Promise<Uint8Array[]>;
+export declare function verifyInclusion(leaf: Uint8Array, leafIndex: number, totalLeaves: number, auditPath: Uint8Array[], expectedRoot: Uint8Array): Promise<boolean>;

package/dist/merkle.js

@@ -0,0 +1,114 @@
+// RFC 9162 binary Merkle tree — build, audit paths, inclusion verification.
+//
+// A faithful port of the Go reference (ar-io-agent pkg/merkle), in lockstep
+// with the Python kernel's ario_proof.merkle. All hashing is SHA-256 with
+// RFC 9162 §2.1 domain separation: leaves prefixed 0x00, interior nodes 0x01.
+// A tree of n leaves splits into a left subtree of k leaves (the largest
+// power of two < n) and a right subtree of n−k — NOT the Bitcoin
+// duplicate-last-leaf variant, which produces different roots for
+// non-power-of-two leaf counts.
+//
+// The empty tree (zero leaves) hashes to SHA-256("") — EMPTY_TREE_ROOT_HEX.
+// Conformance is byte-for-byte against the 7 merkle-tree-* vectors of
+// test-vectors-v1.0 (test/conformance.test.ts).
+import { sha256Bytes } from "./crypto";
+export const EMPTY_TREE_ROOT_HEX = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+// SHA-256(0x00 || leafBytes) per RFC 9162 §2.1.
+export async function leafHash(leafBytes) {
+    return sha256Bytes(prefixed(0x00, leafBytes));
+}
+// SHA-256(0x01 || left || right) per RFC 9162 §2.1.
+export async function nodeHash(left, right) {
+    const buf = new Uint8Array(1 + left.length + right.length);
+    buf[0] = 0x01;
+    buf.set(left, 1);
+    buf.set(right, 1 + left.length);
+    return sha256Bytes(buf);
+}
+// The RFC 9162 Merkle Tree Hash of already-hashed leaves. Callers pass leaf
+// hashes — the output of leafHash on each leaf's canonical bytes. Zero leaves
+// yields SHA-256("").
+export async function merkleRoot(leafHashes) {
+    const n = leafHashes.length;
+    if (n === 0)
+        return sha256Bytes(new Uint8Array(0));
+    if (n === 1)
+        return leafHashes[0];
+    const k = largestPow2LessThan(n);
+    return nodeHash(await merkleRoot(leafHashes.slice(0, k)), await merkleRoot(leafHashes.slice(k)));
+}
+// The inclusion proof for the leaf at index m, per RFC 9162 §2.1.3: sibling
+// hashes bottom-up; empty for a single-leaf tree (the leaf hash itself is the
+// root). Throws RangeError when m is out of range.
+export async function auditPath(m, leafHashes) {
+    if (!Number.isInteger(m) || m < 0 || m >= leafHashes.length) {
+        throw new RangeError("merkle: leaf index out of range");
+    }
+    return path(m, leafHashes);
+}
+async function path(m, leafHashes) {
+    const n = leafHashes.length;
+    if (n === 1)
+        return [];
+    const k = largestPow2LessThan(n);
+    if (m < k) {
+        return [...(await path(m, leafHashes.slice(0, k))), await merkleRoot(leafHashes.slice(k))];
+    }
+    return [...(await path(m - k, leafHashes.slice(k))), await merkleRoot(leafHashes.slice(0, k))];
+}
+// Verify an RFC 9162 §2.1.3 inclusion proof. `leaf` is the leaf hash
+// (leafHash of the canonical leaf bytes); `path` is the audit path bottom-up;
+// `expectedRoot` is the merkleRoot committed by the checkpoint envelope.
+// True iff the path reconstructs the expected root. Never throws.
+export async function verifyInclusion(leaf, leafIndex, totalLeaves, auditPath, expectedRoot) {
+    if (!Number.isInteger(leafIndex) || leafIndex < 0 || totalLeaves <= 0 || leafIndex >= totalLeaves) {
+        return false;
+    }
+    if (totalLeaves === 1)
+        return auditPath.length === 0 && bytesEqual(leaf, expectedRoot);
+    let fn = leafIndex;
+    let sn = totalLeaves - 1;
+    let r = leaf;
+    for (const p of auditPath) {
+        if (sn === 0)
+            return false; // path longer than the tree depth — malformed
+        if ((fn & 1) === 1 || fn === sn) {
+            r = await nodeHash(p, r);
+            if ((fn & 1) === 0) {
+                while ((fn & 1) === 0 && fn !== 0) {
+                    fn >>= 1;
+                    sn >>= 1;
+                }
+            }
+        }
+        else {
+            r = await nodeHash(r, p);
+        }
+        fn >>= 1;
+        sn >>= 1;
+    }
+    return sn === 0 && bytesEqual(r, expectedRoot);
+}
+function prefixed(prefix, bytes) {
+    const buf = new Uint8Array(1 + bytes.length);
+    buf[0] = prefix;
+    buf.set(bytes, 1);
+    return buf;
+}
+// Largest k = 2**a with k < n (0 for n < 2).
+function largestPow2LessThan(n) {
+    if (n < 2)
+        return 0;
+    let k = 1;
+    while (k * 2 < n)
+        k *= 2;
+    return k;
+}
+function bytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a[i] ^ b[i];
+    return diff === 0;
+}

package/dist/types.d.ts

@@ -0,0 +1,28 @@
+export interface Subject {
+    type: string;
+    tenant_id: string;
+    agent_id: string;
+}
+export interface Envelope {
+    spec_version: string;
+    event_id: string;
+    event_type: string;
+    subject: Subject;
+    payload_hash: string;
+    payload: Record<string, unknown>;
+    previous_hash: string;
+    signed_at: string;
+    public_key: string;
+    signature: string;
+    co_signatures?: unknown[];
+}
+export type ContentRole = "asset" | "baseline" | "observed";
+export interface VerificationResult {
+    ok: boolean;
+    specVersionOk: boolean;
+    payloadHashOk: boolean;
+    signatureOk: boolean;
+    contentHashOk: boolean | null;
+    contentRole: ContentRole | null;
+    errors: string[];
+}

package/dist/types.js

@@ -0,0 +1,6 @@
+// Wire types for ar.io Verifiable Event Envelopes (ar-io-agent
+// docs/envelope-spec.md; the ario.agent/v1 profile detail is artifact.md
+// §3–§4). We model only the fields the verifier consumes; unknown fields are
+// preserved by structural typing (envelopes are verified over their canonical
+// bytes, not this interface).
+export {};

package/dist/verifier.d.ts

@@ -0,0 +1,8 @@
+import type { ContentRole, Envelope, VerificationResult } from "./types";
+export declare function jcs(value: unknown): string;
+export declare function specVersionSupported(specVersion: string): boolean;
+export declare function contentHashes(env: Envelope): {
+    role: ContentRole;
+    hash: string;
+}[];
+export declare function verifyEnvelope(env: Envelope, expectedContentHash?: string): Promise<VerificationResult>;

package/dist/verifier.js

@@ -0,0 +1,146 @@
+// Independent client-side implementation of the ar.io agent envelope
+// verification algorithm (ar-io-agent docs/artifact.md §6, docs/auditor-recipe.md
+// Recipe 1). This is deliberately a second implementation of the same algorithm
+// the Go agent runs — a second, conformance-tested verifier is what demonstrates
+// the product's claim: verification needs no ar.io code in the trust path.
+//
+// Conformance is enforced by test/conformance.test.ts, which runs every
+// ar-io-agent test vector through this code and asserts byte-for-byte agreement.
+import canonicalize from "canonicalize";
+import { ed25519Verify, sha256Hex, utf8 } from "./crypto";
+// Fail-closed accepted-profile registry (envelope-spec §2, artifact.md §13):
+// exactly the accepted profile majors, nothing else. Minors within an accepted
+// major ("ario.agent/v1.<minor>") are additive and tolerated — matching the Go
+// reference kernel's semantics (pkg/proof isSupportedSpec) so the JS and
+// WASM-Go verifiers agree. Accepting a new profile (e.g. ario.mlflow/v1) is a
+// deliberate one-entry addition HERE and only here — mlflow-dialect behaviors
+// (like its underscore-key strip) must never leak into the agent profile.
+const ACCEPTED_SPEC_MAJORS = ["ario.agent/v1"];
+// RFC 8785 (JCS) canonicalization. The `canonicalize` package is the reference
+// JS implementation; correctness is pinned by the conformance vectors.
+export function jcs(value) {
+    const canonical = canonicalize(value);
+    if (typeof canonical !== "string") {
+        throw new Error("jcs: canonicalize returned a non-string (input not JSON-serializable?)");
+    }
+    return canonical;
+}
+export function specVersionSupported(specVersion) {
+    if (typeof specVersion !== "string" || specVersion === "")
+        return false;
+    return ACCEPTED_SPEC_MAJORS.some((m) => specVersion === m || specVersion.startsWith(`${m}.`));
+}
+// 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)
+//   asset_missing    -> payload.baseline.hash   (last known-good bytes that vanished)
+//   tamper_detected  -> payload.observed.hash   (the tampered bytes that were flagged)
+//                    -> payload.baseline.hash   (the known-good bytes it diverged from)
+// Other event types commit to no asset content hash.
+export function contentHashes(env) {
+    const p = env.payload;
+    const asStr = (v) => (typeof v === "string" && v ? v : undefined);
+    const out = [];
+    switch (env.event_type) {
+        case "asset_registered": {
+            const h = asStr(p.hash);
+            if (h)
+                out.push({ role: "asset", hash: h });
+            break;
+        }
+        case "asset_missing": {
+            const h = asStr(p.baseline?.hash);
+            if (h)
+                out.push({ role: "baseline", hash: h });
+            break;
+        }
+        case "tamper_detected": {
+            const obs = asStr(p.observed?.hash);
+            if (obs)
+                out.push({ role: "observed", hash: obs });
+            const base = asStr(p.baseline?.hash);
+            if (base)
+                out.push({ role: "baseline", hash: base });
+            break;
+        }
+    }
+    return out;
+}
+// Verify an envelope. The three load-bearing checks (spec_version, payload_hash,
+// signature) establish that the envelope is authentic. When `expectedContentHash`
+// is supplied (the in-browser hash of the user's file), an additional bind check
+// confirms the bytes the user holds are the bytes this envelope is about — this
+// is the step that makes a lying gateway tag worthless.
+export async function verifyEnvelope(env, expectedContentHash) {
+    const errors = [];
+    // Guard a malformed input (null / non-object / array) up front — every field
+    // access below assumes an object. A hostile gateway or a hand-edited report
+    // can supply anything; treat it as "not verified," never a thrown exception.
+    if (env === null || typeof env !== "object" || Array.isArray(env)) {
+        return {
+            ok: false,
+            specVersionOk: false,
+            payloadHashOk: false,
+            signatureOk: false,
+            contentHashOk: expectedContentHash === undefined ? null : false,
+            contentRole: null,
+            errors: ["envelope is not a JSON object"],
+        };
+    }
+    const specVersionOk = specVersionSupported(env.spec_version);
+    if (!specVersionOk)
+        errors.push(`unsupported spec_version: ${JSON.stringify(env.spec_version)}`);
+    // Check 1 — Record Matches: payload_hash == SHA-256(JCS(payload)).
+    let payloadHashOk = false;
+    try {
+        const recomputed = await sha256Hex(utf8(jcs(env.payload)));
+        payloadHashOk = recomputed === env.payload_hash;
+        if (!payloadHashOk) {
+            errors.push(`payload_hash mismatch: envelope=${env.payload_hash} recomputed=${recomputed}`);
+        }
+    }
+    catch (e) {
+        errors.push(`payload canonicalization failed: ${stringifyErr(e)}`);
+    }
+    // Check 2 — Signature Confirmed: Ed25519 over the signed scope, which is
+    // JCS(envelope minus `signature` minus `co_signatures`) per envelope-spec §2.
+    // The co_signatures carve-out (§7.1) lets a countersignature be added without
+    // invalidating the primary signature; the field is reserved/default-absent.
+    // The corpus has no co-signed vectors, so this strip is pinned by an explicit
+    // unit test rather than by conformance.
+    let signatureOk = false;
+    try {
+        const { signature: _signature, co_signatures: _coSignatures, ...envelopeForSig } = env;
+        signatureOk = await ed25519Verify(env.signature, utf8(jcs(envelopeForSig)), env.public_key);
+        if (!signatureOk)
+            errors.push("Ed25519 signature verification failed");
+    }
+    catch (e) {
+        errors.push(`signature verification error: ${stringifyErr(e)}`);
+    }
+    // Check 3 (optional) — Content Bind: the user's bytes match a hash this
+    // envelope commits to. The tag got us here; only this proves the bytes match.
+    let contentHashOk = null;
+    let contentRole = null;
+    if (expectedContentHash !== undefined) {
+        const want = expectedContentHash.toLowerCase();
+        const match = contentHashes(env).find((c) => c.hash.toLowerCase() === want);
+        contentHashOk = match !== undefined;
+        contentRole = match ? match.role : null;
+        if (!contentHashOk) {
+            errors.push("provided content hash does not match any hash this envelope commits to");
+        }
+    }
+    return {
+        ok: specVersionOk && payloadHashOk && signatureOk,
+        specVersionOk,
+        payloadHashOk,
+        signatureOk,
+        contentHashOk,
+        contentRole,
+        errors,
+    };
+}
+function stringifyErr(e) {
+    return e instanceof Error ? e.message : String(e);
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@ar.io/proof",
+  "version": "0.1.0",
+  "description": "TypeScript kernel of the ar.io verification stack: RFC 8785 (JCS) canonicalization, SHA-256, and Ed25519 verification for Verifiable Event Envelopes (ario.agent/v1 profile). Conformance-gated byte-for-byte against the test-vectors-v1.0 corpus.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@noble/ed25519": "^2.1.0",
+    "canonicalize": "^2.0.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ar-io/ar-io-proof-checker.git",
+    "directory": "packages/proof"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "ar.io",
+    "arweave",
+    "verification",
+    "provenance",
+    "jcs",
+    "rfc8785",
+    "ed25519",
+    "merkle",
+    "rfc9162"
+  ]
+}

package/src/crypto.ts

@@ -0,0 +1,69 @@
+// Low-level cryptographic primitives for the verifier. Deliberately thin: the
+// only third-party crypto dependency is @noble/ed25519 (single-file, audited,
+// zero-dependency). SHA-256 and SHA-512 come from WebCrypto — no extra hashing
+// library to trust.
+
+import * as ed from "@noble/ed25519";
+
+// @noble/ed25519 needs SHA-512 to verify. Wire it to WebCrypto rather than
+// pulling in @noble/hashes. globalThis.crypto.subtle exists in every modern
+// browser and in Node >= 19, so the same code path runs in the app and in tests.
+ed.etc.sha512Async = async (...msgs: Uint8Array[]): Promise<Uint8Array> =>
+  new Uint8Array(await crypto.subtle.digest("SHA-512", asBufferSource(ed.etc.concatBytes(...msgs))));
+
+// WebCrypto's digest() wants a BufferSource backed by a (non-shared) ArrayBuffer.
+// Our byte arrays always are; this keeps TS 5.7's stricter Uint8Array<ArrayBufferLike>
+// typing satisfied without a runtime copy.
+function asBufferSource(bytes: Uint8Array): BufferSource {
+  return bytes as unknown as BufferSource;
+}
+
+export function bytesToHex(bytes: Uint8Array): string {
+  let out = "";
+  for (const b of bytes) out += b.toString(16).padStart(2, "0");
+  return out;
+}
+
+export function hexToBytes(hex: string): Uint8Array {
+  if (hex.length % 2 !== 0) throw new Error("hexToBytes: odd-length string");
+  // Full validation: parseInt() partially parses ("1g" -> 1), which would let
+  // malformed hex through. A strict charset check closes that.
+  if (!/^[0-9a-fA-F]*$/.test(hex)) throw new Error("hexToBytes: non-hex characters");
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+
+export function utf8(s: string): Uint8Array {
+  return new TextEncoder().encode(s);
+}
+
+export async function sha256Bytes(bytes: Uint8Array): Promise<Uint8Array> {
+  return new Uint8Array(await crypto.subtle.digest("SHA-256", asBufferSource(bytes)));
+}
+
+export async function sha256Hex(bytes: Uint8Array): Promise<string> {
+  return bytesToHex(await sha256Bytes(bytes));
+}
+
+// Verify an Ed25519 signature. Inputs are hex (signature, public key) as they
+// appear in the envelope; message is raw bytes. Never throws — a malformed
+// signature or key is "not verified," not an exception, so a hostile envelope
+// can't crash the checker.
+export async function ed25519Verify(
+  signatureHex: string,
+  message: Uint8Array,
+  publicKeyHex: string,
+): Promise<boolean> {
+  try {
+    // zip215:false → strict RFC-8032 verification, matching the Go agent's
+    // crypto/ed25519 exactly (noble defaults to the more lenient zip215:true).
+    return await ed.verifyAsync(hexToBytes(signatureHex), message, hexToBytes(publicKeyHex), {
+      zip215: false,
+    });
+  } catch {
+    return false;
+  }
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+// @ar.io/proof — TypeScript kernel of the ar.io verification stack.
+//
+// The verification primitives for the Verifiable Event Envelope family
+// (ar-io-agent docs/envelope-spec.md), ario.agent/v1 profile: RFC 8785 (JCS)
+// canonicalization, SHA-256, Ed25519 envelope verification, and the
+// content-hash extraction used for reverse provenance lookup. Sibling of the
+// Python `ar-io-proof` kernel and the Go `pkg/proof` reference; conformance
+// is byte-for-byte against the shared `test-vectors-v1.0` corpus.
+//
+// Scope boundary (envelope-spec §10 #13): this package verifies a SINGLE
+// envelope. Chain walking (previous_hash), checkpoint reconciliation, and
+// gateway/transport concerns are consumer-layer logic composed above it.
+
+export { contentHashes, jcs, specVersionSupported, verifyEnvelope } from "./verifier";
+export { bytesToHex, ed25519Verify, hexToBytes, sha256Bytes, sha256Hex, utf8 } from "./crypto";
+export {
+  EMPTY_TREE_ROOT_HEX,
+  auditPath,
+  leafHash,
+  merkleRoot,
+  nodeHash,
+  verifyInclusion,
+} from "./merkle";
+export type { ContentRole, Envelope, Subject, VerificationResult } from "./types";

package/src/merkle.ts

@@ -0,0 +1,125 @@
+// RFC 9162 binary Merkle tree — build, audit paths, inclusion verification.
+//
+// A faithful port of the Go reference (ar-io-agent pkg/merkle), in lockstep
+// with the Python kernel's ario_proof.merkle. All hashing is SHA-256 with
+// RFC 9162 §2.1 domain separation: leaves prefixed 0x00, interior nodes 0x01.
+// A tree of n leaves splits into a left subtree of k leaves (the largest
+// power of two < n) and a right subtree of n−k — NOT the Bitcoin
+// duplicate-last-leaf variant, which produces different roots for
+// non-power-of-two leaf counts.
+//
+// The empty tree (zero leaves) hashes to SHA-256("") — EMPTY_TREE_ROOT_HEX.
+// Conformance is byte-for-byte against the 7 merkle-tree-* vectors of
+// test-vectors-v1.0 (test/conformance.test.ts).
+
+import { sha256Bytes } from "./crypto";
+
+export const EMPTY_TREE_ROOT_HEX =
+  "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+
+// SHA-256(0x00 || leafBytes) per RFC 9162 §2.1.
+export async function leafHash(leafBytes: Uint8Array): Promise<Uint8Array> {
+  return sha256Bytes(prefixed(0x00, leafBytes));
+}
+
+// SHA-256(0x01 || left || right) per RFC 9162 §2.1.
+export async function nodeHash(left: Uint8Array, right: Uint8Array): Promise<Uint8Array> {
+  const buf = new Uint8Array(1 + left.length + right.length);
+  buf[0] = 0x01;
+  buf.set(left, 1);
+  buf.set(right, 1 + left.length);
+  return sha256Bytes(buf);
+}
+
+// The RFC 9162 Merkle Tree Hash of already-hashed leaves. Callers pass leaf
+// hashes — the output of leafHash on each leaf's canonical bytes. Zero leaves
+// yields SHA-256("").
+export async function merkleRoot(leafHashes: Uint8Array[]): Promise<Uint8Array> {
+  const n = leafHashes.length;
+  if (n === 0) return sha256Bytes(new Uint8Array(0));
+  if (n === 1) return leafHashes[0];
+  const k = largestPow2LessThan(n);
+  return nodeHash(await merkleRoot(leafHashes.slice(0, k)), await merkleRoot(leafHashes.slice(k)));
+}
+
+// The inclusion proof for the leaf at index m, per RFC 9162 §2.1.3: sibling
+// hashes bottom-up; empty for a single-leaf tree (the leaf hash itself is the
+// root). Throws RangeError when m is out of range.
+export async function auditPath(m: number, leafHashes: Uint8Array[]): Promise<Uint8Array[]> {
+  if (!Number.isInteger(m) || m < 0 || m >= leafHashes.length) {
+    throw new RangeError("merkle: leaf index out of range");
+  }
+  return path(m, leafHashes);
+}
+
+async function path(m: number, leafHashes: Uint8Array[]): Promise<Uint8Array[]> {
+  const n = leafHashes.length;
+  if (n === 1) return [];
+  const k = largestPow2LessThan(n);
+  if (m < k) {
+    return [...(await path(m, leafHashes.slice(0, k))), await merkleRoot(leafHashes.slice(k))];
+  }
+  return [...(await path(m - k, leafHashes.slice(k))), await merkleRoot(leafHashes.slice(0, k))];
+}
+
+// Verify an RFC 9162 §2.1.3 inclusion proof. `leaf` is the leaf hash
+// (leafHash of the canonical leaf bytes); `path` is the audit path bottom-up;
+// `expectedRoot` is the merkleRoot committed by the checkpoint envelope.
+// True iff the path reconstructs the expected root. Never throws.
+export async function verifyInclusion(
+  leaf: Uint8Array,
+  leafIndex: number,
+  totalLeaves: number,
+  auditPath: Uint8Array[],
+  expectedRoot: Uint8Array,
+): Promise<boolean> {
+  if (!Number.isInteger(leafIndex) || leafIndex < 0 || totalLeaves <= 0 || leafIndex >= totalLeaves) {
+    return false;
+  }
+  if (totalLeaves === 1) return auditPath.length === 0 && bytesEqual(leaf, expectedRoot);
+
+  let fn = leafIndex;
+  let sn = totalLeaves - 1;
+  let r = leaf;
+
+  for (const p of auditPath) {
+    if (sn === 0) return false; // path longer than the tree depth — malformed
+    if ((fn & 1) === 1 || fn === sn) {
+      r = await nodeHash(p, r);
+      if ((fn & 1) === 0) {
+        while ((fn & 1) === 0 && fn !== 0) {
+          fn >>= 1;
+          sn >>= 1;
+        }
+      }
+    } else {
+      r = await nodeHash(r, p);
+    }
+    fn >>= 1;
+    sn >>= 1;
+  }
+
+  return sn === 0 && bytesEqual(r, expectedRoot);
+}
+
+function prefixed(prefix: number, bytes: Uint8Array): Uint8Array {
+  const buf = new Uint8Array(1 + bytes.length);
+  buf[0] = prefix;
+  buf.set(bytes, 1);
+  return buf;
+}
+
+// Largest k = 2**a with k < n (0 for n < 2).
+function largestPow2LessThan(n: number): number {
+  if (n < 2) return 0;
+  let k = 1;
+  while (k * 2 < n) k *= 2;
+  return k;
+}
+
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a[i] ^ b[i];
+  return diff === 0;
+}

package/src/types.ts

@@ -0,0 +1,50 @@
+// Wire types for ar.io Verifiable Event Envelopes (ar-io-agent
+// docs/envelope-spec.md; the ario.agent/v1 profile detail is artifact.md
+// §3–§4). We model only the fields the verifier consumes; unknown fields are
+// preserved by structural typing (envelopes are verified over their canonical
+// bytes, not this interface).
+
+export interface Subject {
+  type: string;
+  tenant_id: string;
+  agent_id: string;
+}
+
+export interface Envelope {
+  spec_version: string;
+  event_id: string;
+  event_type: string;
+  subject: Subject;
+  payload_hash: string;
+  payload: Record<string, unknown>;
+  previous_hash: string;
+  signed_at: string;
+  public_key: string;
+  signature: string;
+  // Reserved, default-absent (envelope-spec §7.1): countersignatures over the
+  // same skeleton. OUTSIDE the signed scope — the primary signature covers the
+  // envelope minus `signature` AND minus `co_signatures`, so a countersignature
+  // can be added without invalidating the primary. Absence implies a single
+  // signer and MUST NOT be treated as a failure.
+  co_signatures?: unknown[];
+}
+
+// Which payload field a matched content hash came from. tamper_detected commits
+// to both the tampered ("observed") bytes and the known-good ("baseline") bytes.
+export type ContentRole = "asset" | "baseline" | "observed";
+
+export interface VerificationResult {
+  // Cryptographic validity: spec_version + payload_hash + Ed25519 signature all
+  // passed. This is "the envelope is authentic," independent of the user's bytes.
+  ok: boolean;
+  specVersionOk: boolean;
+  payloadHashOk: boolean;
+  signatureOk: boolean;
+  // Content bind: did the hash the caller supplied (e.g. the in-browser hash of
+  // a user's file) match a hash this envelope commits to? null when no hash was
+  // supplied (verifying an envelope on its own). This is the check that defeats
+  // a lying gateway — the tag only got us to the candidate.
+  contentHashOk: boolean | null;
+  contentRole: ContentRole | null;
+  errors: string[];
+}

package/src/verifier.ts

@@ -0,0 +1,160 @@
+// Independent client-side implementation of the ar.io agent envelope
+// verification algorithm (ar-io-agent docs/artifact.md §6, docs/auditor-recipe.md
+// Recipe 1). This is deliberately a second implementation of the same algorithm
+// the Go agent runs — a second, conformance-tested verifier is what demonstrates
+// the product's claim: verification needs no ar.io code in the trust path.
+//
+// Conformance is enforced by test/conformance.test.ts, which runs every
+// ar-io-agent test vector through this code and asserts byte-for-byte agreement.
+
+import canonicalize from "canonicalize";
+
+import { ed25519Verify, sha256Hex, utf8 } from "./crypto";
+import type { ContentRole, Envelope, VerificationResult } from "./types";
+
+// Fail-closed accepted-profile registry (envelope-spec §2, artifact.md §13):
+// exactly the accepted profile majors, nothing else. Minors within an accepted
+// major ("ario.agent/v1.<minor>") are additive and tolerated — matching the Go
+// reference kernel's semantics (pkg/proof isSupportedSpec) so the JS and
+// WASM-Go verifiers agree. Accepting a new profile (e.g. ario.mlflow/v1) is a
+// deliberate one-entry addition HERE and only here — mlflow-dialect behaviors
+// (like its underscore-key strip) must never leak into the agent profile.
+const ACCEPTED_SPEC_MAJORS = ["ario.agent/v1"];
+
+// RFC 8785 (JCS) canonicalization. The `canonicalize` package is the reference
+// JS implementation; correctness is pinned by the conformance vectors.
+export function jcs(value: unknown): string {
+  const canonical = canonicalize(value);
+  if (typeof canonical !== "string") {
+    throw new Error("jcs: canonicalize returned a non-string (input not JSON-serializable?)");
+  }
+  return canonical;
+}
+
+export function specVersionSupported(specVersion: string): boolean {
+  if (typeof specVersion !== "string" || specVersion === "") return false;
+  return ACCEPTED_SPEC_MAJORS.some((m) => specVersion === m || specVersion.startsWith(`${m}.`));
+}
+
+// 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)
+//   asset_missing    -> payload.baseline.hash   (last known-good bytes that vanished)
+//   tamper_detected  -> payload.observed.hash   (the tampered bytes that were flagged)
+//                    -> payload.baseline.hash   (the known-good bytes it diverged from)
+// Other event types commit to no asset content hash.
+export function contentHashes(env: Envelope): { role: ContentRole; hash: string }[] {
+  const p = env.payload as {
+    hash?: unknown;
+    baseline?: { hash?: unknown };
+    observed?: { hash?: unknown };
+  };
+  const asStr = (v: unknown): string | undefined => (typeof v === "string" && v ? v : undefined);
+
+  const out: { role: ContentRole; hash: string }[] = [];
+  switch (env.event_type) {
+    case "asset_registered": {
+      const h = asStr(p.hash);
+      if (h) out.push({ role: "asset", hash: h });
+      break;
+    }
+    case "asset_missing": {
+      const h = asStr(p.baseline?.hash);
+      if (h) out.push({ role: "baseline", hash: h });
+      break;
+    }
+    case "tamper_detected": {
+      const obs = asStr(p.observed?.hash);
+      if (obs) out.push({ role: "observed", hash: obs });
+      const base = asStr(p.baseline?.hash);
+      if (base) out.push({ role: "baseline", hash: base });
+      break;
+    }
+  }
+  return out;
+}
+
+// Verify an envelope. The three load-bearing checks (spec_version, payload_hash,
+// signature) establish that the envelope is authentic. When `expectedContentHash`
+// is supplied (the in-browser hash of the user's file), an additional bind check
+// confirms the bytes the user holds are the bytes this envelope is about — this
+// is the step that makes a lying gateway tag worthless.
+export async function verifyEnvelope(
+  env: Envelope,
+  expectedContentHash?: string,
+): Promise<VerificationResult> {
+  const errors: string[] = [];
+
+  // Guard a malformed input (null / non-object / array) up front — every field
+  // access below assumes an object. A hostile gateway or a hand-edited report
+  // can supply anything; treat it as "not verified," never a thrown exception.
+  if (env === null || typeof env !== "object" || Array.isArray(env)) {
+    return {
+      ok: false,
+      specVersionOk: false,
+      payloadHashOk: false,
+      signatureOk: false,
+      contentHashOk: expectedContentHash === undefined ? null : false,
+      contentRole: null,
+      errors: ["envelope is not a JSON object"],
+    };
+  }
+
+  const specVersionOk = specVersionSupported(env.spec_version);
+  if (!specVersionOk) errors.push(`unsupported spec_version: ${JSON.stringify(env.spec_version)}`);
+
+  // Check 1 — Record Matches: payload_hash == SHA-256(JCS(payload)).
+  let payloadHashOk = false;
+  try {
+    const recomputed = await sha256Hex(utf8(jcs(env.payload)));
+    payloadHashOk = recomputed === env.payload_hash;
+    if (!payloadHashOk) {
+      errors.push(`payload_hash mismatch: envelope=${env.payload_hash} recomputed=${recomputed}`);
+    }
+  } catch (e) {
+    errors.push(`payload canonicalization failed: ${stringifyErr(e)}`);
+  }
+
+  // Check 2 — Signature Confirmed: Ed25519 over the signed scope, which is
+  // JCS(envelope minus `signature` minus `co_signatures`) per envelope-spec §2.
+  // The co_signatures carve-out (§7.1) lets a countersignature be added without
+  // invalidating the primary signature; the field is reserved/default-absent.
+  // The corpus has no co-signed vectors, so this strip is pinned by an explicit
+  // unit test rather than by conformance.
+  let signatureOk = false;
+  try {
+    const { signature: _signature, co_signatures: _coSignatures, ...envelopeForSig } = env;
+    signatureOk = await ed25519Verify(env.signature, utf8(jcs(envelopeForSig)), env.public_key);
+    if (!signatureOk) errors.push("Ed25519 signature verification failed");
+  } catch (e) {
+    errors.push(`signature verification error: ${stringifyErr(e)}`);
+  }
+
+  // Check 3 (optional) — Content Bind: the user's bytes match a hash this
+  // envelope commits to. The tag got us here; only this proves the bytes match.
+  let contentHashOk: boolean | null = null;
+  let contentRole: ContentRole | null = null;
+  if (expectedContentHash !== undefined) {
+    const want = expectedContentHash.toLowerCase();
+    const match = contentHashes(env).find((c) => c.hash.toLowerCase() === want);
+    contentHashOk = match !== undefined;
+    contentRole = match ? match.role : null;
+    if (!contentHashOk) {
+      errors.push("provided content hash does not match any hash this envelope commits to");
+    }
+  }
+
+  return {
+    ok: specVersionOk && payloadHashOk && signatureOk,
+    specVersionOk,
+    payloadHashOk,
+    signatureOk,
+    contentHashOk,
+    contentRole,
+    errors,
+  };
+}
+
+function stringifyErr(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}