@ktlsr/aer-verify 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ktlesr
+
+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

@@ -1,3 +1,44 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @ktlsr/aer-verify
+
+Offline verifier for [Agent Evidence Recorder](https://aer.ktlsr.com) audit packets. Reads local
+files only — no network request, no AER account, no database. Zero runtime dependencies (Node ≥ 18).
+
+```sh
+npx @ktlsr/aer-verify packet.json --receipt receipt.json --trusted-key aer-key.json
+```
+
+- `packet.json` — a JSON packet exported from AER (schema 1.1–2.0).
+- `--receipt` — the receipt **you kept** when the run was sealed (the `complete` response, or its
+  `receipt` field). This is what makes a later rewrite detectable.
+- `--trusted-key` (repeatable) — an Ed25519 public key you obtained **out of band**:
+  `{ "key_id", "public_key" }`, a list of them, or a saved `GET /api/v1/receipt-keys` response.
+  A key carried inside the packet is never used.
+- `--require-anchor` — exit 1 unless the result is tied to your receipt or trusted key.
+- `--json` — machine-readable report.
+
+## What it reports, separately
+
+| Check | Meaning |
+| --- | --- |
+| Schema | Known packet version? Unknown versions are never "verified". |
+| Event chain | Each event's hash and link (`aer-chain/1`); `consistent_unsealed` while the run is open. |
+| Seal | Whether the run was sealed (completed/failed). |
+| Run manifest | Agent, status, tenant, times, policies, capture claims, lineage, sourced blocks — frozen at seal (`aer-manifest/1`). |
+| Content hash | Whole-file consistency. Not tamper evidence by itself: an editor can recompute it. |
+| Receipt in packet / signature | The server's receipt, and its signature checked **only** against your trusted keys. |
+| Your kept receipt | Whether this packet is the run you hold a receipt for. |
+
+It also lists the fields no integrity check covers (counters, export-time views).
+
+**Anchored: NO** means the file is internally consistent — whoever produced it could have rewritten
+and recomputed everything. Anchoring needs a receipt you kept or a signature by a key you trust.
+
+Exit codes: `0` verified · `2` verified with limits (legacy schema, unsealed, pre-manifest run) ·
+`1` failed · `4` unsupported or unreadable input.
+
+## Limits
+
+AER verifies what was **recorded**: not that the events happened, that sources are correct, or that
+nothing went unreported. `issued_at` in a receipt is the AER server's clock, not an independent
+timestamp. Schema 1.x packets carry no manifest; their content hash covers the writer's key order and
+may not be reproducible after storage.

package/dist/aer-verify/src/cli.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+// aer-verify — check an AER audit packet offline. Reads local files only; makes no network request.
+//
+//   aer-verify packet.json [--receipt receipt.json] [--trusted-key key.json ...] [--require-anchor] [--json]
+//
+// Exit codes: 0 verified · 2 verified with limits (partial / unsealed / legacy) · 1 failed · 4 unsupported/unreadable.
+const node_fs_1 = require("node:fs");
+const index_1 = require("../../evidence-chain/src/index");
+const USAGE = "usage: aer-verify <packet.json> [--receipt <receipt.json>] [--trusted-key <key.json>]... [--require-anchor] [--json]";
+/** Fixed messages only: a parser/OS error message can quote file contents (keys, payloads). */
+class InputError extends Error {
+}
+function readJson(path, what) {
+    let text;
+    try {
+        text = (0, node_fs_1.readFileSync)(path, "utf8");
+    }
+    catch {
+        throw new InputError(`cannot read the ${what} file`);
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new InputError(`the ${what} file is not valid JSON`);
+    }
+}
+/** Accepts the receipt itself or the whole `complete` response ({ run, receipt }). */
+function toReceipt(v) {
+    const o = v;
+    if (o && typeof o === "object" && o.statement)
+        return o;
+    if (o && typeof o === "object" && o.receipt)
+        return o.receipt;
+    throw new InputError("the receipt file has no `statement`");
+}
+/** Accepts one key {key_id, public_key}, an array of them, or the /api/v1/receipt-keys response. */
+function toKeys(v) {
+    const list = Array.isArray(v) ? v : v && typeof v === "object" && "keys" in v ? v.keys : [v];
+    return list.map((k) => {
+        const o = k;
+        if (!o || typeof o.key_id !== "string" || typeof o.public_key !== "string")
+            throw new InputError("a trusted key needs key_id and public_key");
+        return { key_id: o.key_id, public_key: o.public_key };
+    });
+}
+const LINES = [
+    ["schema", "Schema"],
+    ["chain", "Event chain"],
+    ["seal", "Seal"],
+    ["manifest", "Run manifest"],
+    ["content_hash", "Content hash"],
+    ["packet_receipt", "Receipt in packet"],
+    ["signature", "Receipt signature"],
+    ["trusted_receipt", "Your kept receipt"],
+    ["trusted_receipt_signature", "Kept receipt signature"],
+];
+function render(r) {
+    const out = [`AER packet verification — ${r.overall.toUpperCase()}`, ""];
+    for (const [key, label] of LINES) {
+        const c = r[key];
+        const extra = [c.version && `v${c.version}`, c.key_id && `key ${c.key_id}`, c.detail, c.reason].filter(Boolean).join(" · ");
+        out.push(`  ${label.padEnd(24)} ${c.status}${extra ? `  (${extra})` : ""}`);
+    }
+    out.push("", `  Versions: canonical ${r.versions.canonicalization}, chain ${r.versions.chain}, manifest ${r.versions.manifest ?? "—"}, content ${r.versions.content_hash}`);
+    out.push(r.anchored
+        ? "  Anchored: yes — tied to a receipt you kept or a key you trust."
+        : "  Anchored: NO — this only shows the file is internally consistent. Whoever produced it could have");
+    if (!r.anchored)
+        out.push("            rewritten and recomputed everything. Pass --receipt and/or --trusted-key to anchor it.");
+    if (r.not_integrity_bound.length) {
+        out.push("", "  Not covered by chain or manifest (editable without detection):");
+        for (const f of r.not_integrity_bound)
+            out.push(`    - ${f}`);
+    }
+    out.push("", "  AER verifies what was recorded, not that the recorded events happened or that sources are correct.");
+    return out.join("\n");
+}
+function main(argv) {
+    const args = [...argv];
+    let packetPath;
+    let receiptPath;
+    const keyPaths = [];
+    let json = false;
+    let requireAnchor = false;
+    while (args.length) {
+        const a = args.shift();
+        if (a === "--receipt")
+            receiptPath = args.shift();
+        else if (a === "--trusted-key")
+            keyPaths.push(args.shift() ?? "");
+        else if (a === "--json")
+            json = true;
+        else if (a === "--require-anchor")
+            requireAnchor = true;
+        else if (a === "-h" || a === "--help") {
+            console.log(USAGE);
+            return 0;
+        }
+        else if (!packetPath && !a.startsWith("--"))
+            packetPath = a;
+        else {
+            console.error(USAGE);
+            return 4;
+        }
+    }
+    if (!packetPath) {
+        console.error(USAGE);
+        return 4;
+    }
+    let report;
+    try {
+        report = (0, index_1.verifyPacket)(readJson(packetPath, "packet"), {
+            trustedReceipt: receiptPath ? toReceipt(readJson(receiptPath, "receipt")) : undefined,
+            trustedKeys: keyPaths.flatMap((p) => toKeys(readJson(p, "trusted key"))),
+        });
+    }
+    catch (err) {
+        // Unreadable input: our own fixed message, never the underlying error text.
+        console.error(`aer-verify: ${err instanceof InputError ? err.message : "input could not be processed"}`);
+        return 4;
+    }
+    console.log(json ? JSON.stringify(report, null, 2) : render(report));
+    if (report.overall === "unsupported")
+        return 4;
+    if (report.overall === "failed")
+        return 1;
+    if (requireAnchor && !report.anchored)
+        return 1;
+    return report.overall === "verified" ? 0 : 2;
+}
+if (require.main === module)
+    process.exit(main(process.argv.slice(2)));

package/dist/evidence-chain/src/canonicalize.js

@@ -0,0 +1,23 @@
+"use strict";
+// Deterministic serialization. The writer and every verifier MUST produce identical bytes for the
+// same logical value, regardless of object key order. Leaves are int | string | boolean | null
+// (this domain has no floats; costMicroUsd is integer micro-USD). undefined is normalized to null.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalize = canonicalize;
+function sortValue(v) {
+    if (v === undefined || v === null)
+        return null;
+    if (Array.isArray(v))
+        return v.map(sortValue);
+    if (typeof v === "object") {
+        const out = {};
+        for (const k of Object.keys(v).sort()) {
+            out[k] = sortValue(v[k]);
+        }
+        return out;
+    }
+    return v;
+}
+function canonicalize(value) {
+    return JSON.stringify(sortValue(value));
+}

package/dist/evidence-chain/src/chain.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeChain = computeChain;
+const hash_1 = require("./hash");
+/** Build the append-only chain for a run: genesis → … → head, in seq order. */
+function computeChain(runId, cores) {
+    const ordered = [...cores].sort((a, b) => a.seq - b.seq);
+    const links = [];
+    let prev = (0, hash_1.genesisHash)(runId);
+    for (const core of ordered) {
+        const hash = (0, hash_1.hashEvent)(prev, core);
+        links.push({ ...core, prevHash: prev, hash });
+        prev = hash;
+    }
+    return links;
+}

package/dist/evidence-chain/src/hash.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.genesisHash = genesisHash;
+exports.hashEvent = hashEvent;
+const node_crypto_1 = require("node:crypto");
+const canonicalize_1 = require("./canonicalize");
+const sha256hex = (s) => (0, node_crypto_1.createHash)("sha256").update(s, "utf8").digest("hex");
+/** Chain root, bound to the run so a chain copied wholesale from another run fails verification. */
+function genesisHash(runId) {
+    return sha256hex("AER-CHAIN-v1:" + runId);
+}
+/** The canonical, hashed projection of an event. Findings are sorted so storage order can't change the hash. */
+function coreView(c) {
+    return {
+        seq: c.seq,
+        type: c.type,
+        title: c.title,
+        occurredAt: c.occurredAt,
+        inputRedacted: c.inputRedacted ?? null,
+        outputRedacted: c.outputRedacted ?? null,
+        riskLevel: c.riskLevel ?? null,
+        costMicroUsd: c.costMicroUsd ?? null,
+        metadata: c.metadata ?? null,
+        findings: [...c.findings]
+            .map((f) => ({
+            findingType: f.findingType,
+            severity: f.severity,
+            fieldPath: f.fieldPath,
+            originalHash: f.originalHash,
+        }))
+            .sort((a, b) => `${a.fieldPath}|${a.originalHash}|${a.findingType}`.localeCompare(`${b.fieldPath}|${b.originalHash}|${b.findingType}`)),
+    };
+}
+/** hash = sha256(prevHash + "\n" + canonical(core)). The delimiter keeps prev/core unambiguous. */
+function hashEvent(prevHash, core) {
+    return sha256hex(prevHash + "\n" + (0, canonicalize_1.canonicalize)(coreView(core)));
+}

package/dist/evidence-chain/src/index.js

@@ -0,0 +1,41 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unrepresentableKeyPath = exports.packetContentHash = exports.manifestInputFromPacket = exports.packetChainLinks = exports.verifyPacket = exports.checkReceiptSignature = exports.publicKeyOf = exports.signReceipt = exports.manifestHash = exports.buildManifest = exports.verifyChain = exports.computeChain = exports.hashEvent = exports.genesisHash = exports.canonicalize = void 0;
+var canonicalize_1 = require("./canonicalize");
+Object.defineProperty(exports, "canonicalize", { enumerable: true, get: function () { return canonicalize_1.canonicalize; } });
+var hash_1 = require("./hash");
+Object.defineProperty(exports, "genesisHash", { enumerable: true, get: function () { return hash_1.genesisHash; } });
+Object.defineProperty(exports, "hashEvent", { enumerable: true, get: function () { return hash_1.hashEvent; } });
+var chain_1 = require("./chain");
+Object.defineProperty(exports, "computeChain", { enumerable: true, get: function () { return chain_1.computeChain; } });
+var verify_1 = require("./verify");
+Object.defineProperty(exports, "verifyChain", { enumerable: true, get: function () { return verify_1.verifyChain; } });
+var manifest_1 = require("./manifest");
+Object.defineProperty(exports, "buildManifest", { enumerable: true, get: function () { return manifest_1.buildManifest; } });
+Object.defineProperty(exports, "manifestHash", { enumerable: true, get: function () { return manifest_1.manifestHash; } });
+var receipt_1 = require("./receipt");
+Object.defineProperty(exports, "signReceipt", { enumerable: true, get: function () { return receipt_1.signReceipt; } });
+Object.defineProperty(exports, "publicKeyOf", { enumerable: true, get: function () { return receipt_1.publicKeyOf; } });
+Object.defineProperty(exports, "checkReceiptSignature", { enumerable: true, get: function () { return receipt_1.checkReceiptSignature; } });
+var packet_1 = require("./packet");
+Object.defineProperty(exports, "verifyPacket", { enumerable: true, get: function () { return packet_1.verifyPacket; } });
+Object.defineProperty(exports, "packetChainLinks", { enumerable: true, get: function () { return packet_1.packetChainLinks; } });
+Object.defineProperty(exports, "manifestInputFromPacket", { enumerable: true, get: function () { return packet_1.manifestInputFromPacket; } });
+Object.defineProperty(exports, "packetContentHash", { enumerable: true, get: function () { return packet_1.packetContentHash; } });
+__exportStar(require("./versions"), exports);
+var representable_1 = require("./representable");
+Object.defineProperty(exports, "unrepresentableKeyPath", { enumerable: true, get: function () { return representable_1.unrepresentableKeyPath; } });

package/dist/evidence-chain/src/manifest.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildManifest = buildManifest;
+exports.manifestHash = manifestHash;
+const node_crypto_1 = require("node:crypto");
+const canonicalize_1 = require("./canonicalize");
+const hash_1 = require("./hash");
+const versions_1 = require("./versions");
+const sha256hex = (s) => (0, node_crypto_1.createHash)("sha256").update(s, "utf8").digest("hex");
+/**
+ * The run manifest: binds run context (agent, status, tenant, policies, lineage) and each event's
+ * out-of-chain fields (capture claim, policy, sourced block — the latter by digest) to the chain
+ * head. Frozen at seal; its hash is what a receipt/signature commits to.
+ */
+function buildManifest(input) {
+    const nullable = (v) => (v === undefined ? null : v);
+    return {
+        manifest_version: versions_1.MANIFEST,
+        canonicalization: versions_1.CANONICALIZATION,
+        hash_algorithm: "sha256",
+        chain: {
+            version: versions_1.CHAIN,
+            genesis: (0, hash_1.genesisHash)(input.run.id),
+            head: input.seal,
+            event_count: input.events.length,
+        },
+        run: {
+            id: input.run.id,
+            organization_id: input.run.organizationId,
+            project_id: input.run.projectId,
+            agent_name: input.run.agentName,
+            status: input.run.status,
+            risk_level: input.run.riskLevel,
+            started_at: input.run.startedAt,
+            ended_at: input.run.endedAt,
+            cost_micro_usd: input.run.costMicroUsd,
+            redaction_policy: input.run.redactionPolicy,
+            capture_declared: nullable(input.run.captureDeclared),
+            environment: input.run.environment,
+            conversation_ref: input.run.conversationRef,
+            turn_ref: input.run.turnRef,
+            parent_run_id: input.run.parentRunId,
+        },
+        events: [...input.events]
+            .sort((a, b) => a.seq - b.seq)
+            .map((e) => ({
+            seq: e.seq,
+            hash: e.hash,
+            redaction_policy: e.redactionPolicy,
+            capture_declared: nullable(e.captureDeclared),
+            sourced_digest: e.sourced === null || e.sourced === undefined ? null : sha256hex((0, canonicalize_1.canonicalize)(e.sourced)),
+        })),
+    };
+}
+/** sha256 over the manifest's canonical bytes (raw hex). */
+function manifestHash(manifest) {
+    return sha256hex((0, canonicalize_1.canonicalize)(manifest));
+}

package/dist/evidence-chain/src/packet.js

@@ -0,0 +1,419 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.packetChainLinks = packetChainLinks;
+exports.manifestInputFromPacket = manifestInputFromPacket;
+exports.packetContentHash = packetContentHash;
+exports.packetShapeError = packetShapeError;
+exports.verifyPacket = verifyPacket;
+// Offline packet verification. Input: a parsed packet (JSON) plus what the VERIFIER trusts (a receipt
+// it kept, public keys it obtained out of band). No network, no DB, no AER account.
+const node_crypto_1 = require("node:crypto");
+const canonicalize_1 = require("./canonicalize");
+const manifest_1 = require("./manifest");
+const receipt_1 = require("./receipt");
+const hash_1 = require("./hash");
+const representable_1 = require("./representable");
+const verify_1 = require("./verify");
+const versions_1 = require("./versions");
+const sha256hex = (s) => (0, node_crypto_1.createHash)("sha256").update(s, "utf8").digest("hex");
+const strip = (v) => v.replace(/^sha256:/, "");
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const str = (v) => (typeof v === "string" ? v : null);
+/** Packet events → chain links, `sha256:` presentation prefix removed (the bytes the writer hashed). */
+function packetChainLinks(packet) {
+    const events = Array.isArray(packet.events) ? packet.events : [];
+    return events.map((e) => ({
+        seq: e.seq,
+        type: e.type,
+        title: e.title,
+        occurredAt: e.occurredAt,
+        inputRedacted: e.inputRedacted ?? null,
+        outputRedacted: e.outputRedacted ?? null,
+        riskLevel: e.riskLevel ?? null,
+        costMicroUsd: e.costMicroUsd ?? null,
+        metadata: e.metadata ?? null,
+        findings: (Array.isArray(e.findings) ? e.findings : []).map((f) => ({
+            findingType: f.findingType,
+            severity: f.severity,
+            fieldPath: f.fieldPath,
+            originalHash: typeof f.originalHash === "string" ? strip(f.originalHash) : "",
+        })),
+        hash: typeof e.hash === "string" ? strip(e.hash) : "",
+        prevHash: typeof e.prevHash === "string" ? strip(e.prevHash) : "",
+    }));
+}
+/** A capture view {layer, ...declared} back to the stored declaration. */
+function declared(capture) {
+    const d = isObj(capture) ? capture.client_declared : null;
+    if (!isObj(d))
+        return null;
+    const { layer: _layer, ...rest } = d;
+    return rest;
+}
+const serverPolicy = (capture) => {
+    const s = isObj(capture) ? capture.server_applied : null;
+    return isObj(s) ? str(s.policy) : null;
+};
+/** Rebuild the manifest input from a 2.x packet — must match what the server froze at seal. */
+function manifestInputFromPacket(packet) {
+    const run = packet.run;
+    const links = isObj(run.links) ? run.links : {};
+    const parent = isObj(links.parentRun) ? links.parentRun : null;
+    return {
+        run: {
+            id: run.id,
+            organizationId: run.organizationId,
+            projectId: run.projectId,
+            agentName: run.agentName,
+            status: run.status,
+            riskLevel: run.riskLevel,
+            startedAt: run.startedAt,
+            endedAt: str(run.endedAt),
+            costMicroUsd: run.costMicroUsd,
+            redactionPolicy: serverPolicy(run.capture),
+            captureDeclared: declared(run.capture),
+            environment: str(run.environment),
+            conversationRef: str(links.conversationRef),
+            turnRef: str(links.turnRef),
+            parentRunId: parent ? str(parent.id) : null,
+        },
+        events: packet.events.map((e) => {
+            let sourced = null;
+            if (isObj(e.sourced)) {
+                // `not_recorded` is a reading aid added at export time, not part of the stored block.
+                const { not_recorded: _gaps, ...rest } = e.sourced;
+                sourced = rest;
+            }
+            return {
+                seq: e.seq,
+                hash: typeof e.hash === "string" ? strip(e.hash) : "",
+                redactionPolicy: serverPolicy(e.capture),
+                captureDeclared: declared(e.capture),
+                sourced,
+            };
+        }),
+        seal: typeof packet.seal === "string" ? strip(packet.seal) : "",
+    };
+}
+/** content_hash as the writer computed it, per schema generation. */
+function packetContentHash(packet) {
+    const exp = isObj(packet.export) ? packet.export : {};
+    const { content_hash: _h, ...restExport } = exp;
+    const base = { ...packet, export: restExport };
+    return String(packet.schema_version).startsWith("1.")
+        ? { algorithm: versions_1.CONTENT_HASH_LEGACY, hex: sha256hex(JSON.stringify(base)) }
+        : { algorithm: versions_1.CONTENT_HASH, hex: sha256hex((0, canonicalize_1.canonicalize)(base)) };
+}
+/** Fields only the content_hash covers — anyone who edits the file can recompute that hash too. */
+const NOT_INTEGRITY_BOUND = {
+    "1": [
+        "run.* (agentName, status, riskLevel, times, counters)",
+        "run.capture / events[].capture",
+        "run.links / events[].sourced",
+        "redaction_findings (copy of events[].findings)",
+        "export.*",
+    ],
+    "2": [
+        "run.durationMs, run.eventCount, run.redactionCount (counters)",
+        "run.links.parentRun.status / agentName (resolved at export time)",
+        "events[].sourced.not_recorded (derived at export time)",
+        "redaction_findings (copy of events[].findings)",
+        "views, coverage (descriptive)",
+        "export.* (generatedAt, type)",
+    ],
+};
+const HASH = /^sha256:[0-9a-f]{64}$/;
+const isInt = (v) => Number.isInteger(v);
+const isStrOrNull = (v) => v === null || typeof v === "string";
+const isHashOrNull = (v) => v === null || (typeof v === "string" && HASH.test(v));
+/**
+ * The packet's shape, checked BEFORE anything is hashed or compared: a wrong type must never be
+ * normalised into a valid one (e.g. `sourced: []` read as null). Free-form JSON (input/output/
+ * metadata, sourced/declaration contents) is only required to be present with the right outer type.
+ */
+function packetShapeError(p, version) {
+    const minor = version.startsWith("1.") ? Number(version.slice(2)) : 99;
+    const run = p.run;
+    const top = [
+        ["run.id", typeof run.id === "string"],
+        ["run.agentName", typeof run.agentName === "string"],
+        ["run.status", typeof run.status === "string"],
+        ["run.riskLevel", typeof run.riskLevel === "string"],
+        ["run.startedAt", typeof run.startedAt === "string"],
+        ["run.endedAt", isStrOrNull(run.endedAt)],
+        ["run.costMicroUsd", isInt(run.costMicroUsd)],
+        ["seal", isHashOrNull(p.seal)],
+        ["chain", isObj(p.chain) && typeof p.chain.algorithm === "string" && typeof p.chain.genesis === "string"],
+        ["export", isObj(p.export) && typeof p.export.generatedAt === "string"],
+        ["redaction_findings", Array.isArray(p.redaction_findings)],
+    ];
+    if (minor >= 2)
+        top.push(["run.capture", captureOk(run.capture)]);
+    if (minor >= 3) {
+        const l = run.links;
+        top.push([
+            "run.links",
+            isObj(l) && isStrOrNull(l.conversationRef) && isStrOrNull(l.turnRef) &&
+                (l.parentRun === null || (isObj(l.parentRun) && typeof l.parentRun.id === "string")),
+        ]);
+    }
+    if (minor === 99) {
+        top.push(["run.organizationId", typeof run.organizationId === "string"], ["run.projectId", typeof run.projectId === "string"], ["run.environment", isStrOrNull(run.environment)], ["manifest_hash", isHashOrNull(p.manifest_hash)], ["receipt", p.receipt === null || receiptShapeOk(p.receipt)], ["versions", isObj(p.versions)]);
+    }
+    for (const [field, ok] of top)
+        if (!ok)
+            return `${field} has the wrong type or is missing`;
+    const events = p.events;
+    for (let i = 0; i < events.length; i++) {
+        const e = events[i];
+        if (!isObj(e))
+            return `events[${i}] is not an object`;
+        const checks = [
+            ["seq", isInt(e.seq) && e.seq > 0],
+            ["type", typeof e.type === "string"],
+            ["title", typeof e.title === "string"],
+            ["occurredAt", typeof e.occurredAt === "string"],
+            ["inputRedacted", "inputRedacted" in e],
+            ["outputRedacted", "outputRedacted" in e],
+            ["metadata", "metadata" in e],
+            ["riskLevel", isStrOrNull(e.riskLevel)],
+            ["costMicroUsd", e.costMicroUsd === null || isInt(e.costMicroUsd)],
+            ["hash", isHashOrNull(e.hash)],
+            ["prevHash", isHashOrNull(e.prevHash)],
+            [
+                "findings",
+                Array.isArray(e.findings) &&
+                    e.findings.every((f) => isObj(f) && typeof f.findingType === "string" && typeof f.severity === "string" &&
+                        typeof f.fieldPath === "string" && isHashOrNull(f.originalHash)),
+            ],
+        ];
+        if (minor >= 2)
+            checks.push(["capture", captureOk(e.capture)]);
+        if (minor >= 3)
+            checks.push(["sourced", e.sourced === null || isObj(e.sourced)]);
+        for (const [field, ok] of checks)
+            if (!ok)
+                return `events[${i}].${field} has the wrong type or is missing`;
+    }
+    return null;
+}
+function captureOk(c) {
+    if (!isObj(c))
+        return false;
+    const s = c.server_applied;
+    const d = c.client_declared;
+    return ((s === null || (isObj(s) && s.layer === "server" && typeof s.policy === "string")) &&
+        (d === null || (isObj(d) && d.layer === "client")));
+}
+function receiptShapeOk(r) {
+    if (!isObj(r) || !isObj(r.statement))
+        return false;
+    const s = r.signature;
+    return s === null || (isObj(s) && typeof s.alg === "string" && typeof s.key_id === "string" && typeof s.value === "string");
+}
+/** Declared algorithm versions this verifier implements; anything else is unsupported, never assumed. */
+function versionError(p, version, runId) {
+    const chain = p.chain;
+    if (chain.algorithm !== "sha256")
+        return `chain.algorithm ${String(chain.algorithm)} not supported`;
+    if (chain.genesis !== `sha256:${(0, hash_1.genesisHash)(runId)}`)
+        return "chain.genesis is not the aer-chain/1 genesis for this run";
+    if (version.startsWith("1."))
+        return null; // 1.x predates declared versions: implicitly canonical/1 + chain/1
+    const v = p.versions;
+    if (v.canonicalization !== versions_1.CANONICALIZATION)
+        return `canonicalization ${String(v.canonicalization)} not supported`;
+    if (v.chain !== versions_1.CHAIN)
+        return `chain ${String(v.chain)} not supported`;
+    if (v.content_hash !== versions_1.CONTENT_HASH)
+        return `content_hash ${String(v.content_hash)} not supported`;
+    if (!(v.manifest === null || v.manifest === versions_1.MANIFEST))
+        return `manifest ${String(v.manifest)} not supported`;
+    if (p.manifest_hash !== null && v.manifest !== versions_1.MANIFEST)
+        return "manifest_hash present without a supported manifest version";
+    return null;
+}
+/** Every commitment in a receipt statement, checked against the packet; issued_at stays a claim. */
+function receiptMismatch(s, ctx) {
+    if (!isObj(s))
+        return "receipt has no statement";
+    if (s.receipt_version !== versions_1.RECEIPT)
+        return `receipt_version ${String(s.receipt_version)} not supported`;
+    if (s.manifest_version !== versions_1.MANIFEST)
+        return `manifest_version ${String(s.manifest_version)} not supported`;
+    const checks = [
+        ["run_id", s.run_id === ctx.runId],
+        ["organization_id", s.organization_id === ctx.run.organizationId],
+        ["project_id", s.project_id === ctx.run.projectId],
+        ["manifest_hash", typeof s.manifest_hash === "string" && ctx.manifest !== null && strip(s.manifest_hash) === ctx.manifest],
+        ["chain_head", typeof s.chain_head === "string" && ctx.seal !== null && strip(s.chain_head) === ctx.seal],
+        ["event_count", s.event_count === ctx.events],
+        ["clock", s.clock === "aer-server"],
+        ["issued_at", typeof s.issued_at === "string"],
+    ];
+    for (const [field, ok] of checks)
+        if (!ok)
+            return `receipt ${field} does not match this packet`;
+    return null;
+}
+/**
+ * Verify a packet offline. Each check is reported on its own; `overall` is "verified" only when the
+ * schema is current, the chain is sealed and intact, the content hash and the manifest reproduce,
+ * and nothing that was checked failed. Never throws on bad input — reports it.
+ */
+function verifyPacket(input, opts = {}) {
+    const trusted = opts.trustedKeys ?? [];
+    const report = {
+        overall: "failed",
+        anchored: false,
+        schema: { status: "malformed", version: null },
+        versions: { canonicalization: versions_1.CANONICALIZATION, chain: versions_1.CHAIN, manifest: null, content_hash: versions_1.CONTENT_HASH },
+        chain: { status: "not_run" },
+        content_hash: { status: "not_run" },
+        manifest: { status: "not_run" },
+        seal: { status: "not_run" },
+        signature: { status: "not_run" },
+        packet_receipt: { status: "not_run" },
+        trusted_receipt: { status: "not_run" },
+        trusted_receipt_signature: { status: "not_run" },
+        not_integrity_bound: [],
+    };
+    if (!isObj(input) || !isObj(input.run) || typeof input.run.id !== "string" || !Array.isArray(input.events)) {
+        report.schema.detail = "not an AER packet (run.id / events missing)";
+        return report;
+    }
+    const packet = input;
+    const version = str(packet.schema_version);
+    report.schema.version = version;
+    if (!version || !versions_1.SUPPORTED_PACKET_SCHEMAS.includes(version)) {
+        // Never "verify" a format this verifier does not know: its hash scopes may differ.
+        report.schema = { status: "unsupported", version, detail: `supported: ${versions_1.SUPPORTED_PACKET_SCHEMAS.join(", ")}` };
+        report.overall = "unsupported";
+        return report;
+    }
+    const legacySchema = version.startsWith("1.");
+    const runId = packet.run.id;
+    // Shape first: a wrong type is never coerced into a valid one before hashing/comparison.
+    const shape = packetShapeError(packet, version);
+    const proto = shape ? null : (0, representable_1.unrepresentableKeyPath)(packet);
+    if (shape || proto) {
+        report.schema = {
+            status: "malformed",
+            version,
+            detail: shape ?? `${proto}: own "__proto__" keys are not representable in ${versions_1.CANONICALIZATION} (not covered by any hash)`,
+        };
+        return report;
+    }
+    // Declared algorithms are reported as declared and checked — never assumed to be this build's.
+    if (!legacySchema) {
+        const v = packet.versions;
+        report.versions = {
+            canonicalization: String(v.canonicalization),
+            chain: String(v.chain),
+            manifest: v.manifest === null ? null : String(v.manifest),
+            content_hash: String(v.content_hash),
+        };
+    }
+    else {
+        report.versions.content_hash = versions_1.CONTENT_HASH_LEGACY;
+    }
+    const unsupported = versionError(packet, version, runId);
+    if (unsupported) {
+        report.schema = { status: "unsupported", version, detail: unsupported };
+        report.overall = "unsupported";
+        return report;
+    }
+    report.schema.status = "supported";
+    report.not_integrity_bound = NOT_INTEGRITY_BOUND[legacySchema ? "1" : "2"];
+    const seal = typeof packet.seal === "string" ? strip(packet.seal) : null;
+    // 1. Chain.
+    try {
+        const v = (0, verify_1.verifyChain)(packetChainLinks(packet), seal, runId);
+        report.chain = v.ok
+            ? { status: v.status, detail: `${v.checkedCount} events` }
+            : v.status === "legacy"
+                ? { status: "legacy", detail: v.reason }
+                : { status: "broken", detail: v.reason };
+    }
+    catch {
+        report.chain = { status: "broken", detail: "events are not well-formed chain links" };
+    }
+    report.seal = { status: seal ? "sealed" : "unsealed" };
+    // 2. Content hash (whole file consistency — NOT tamper evidence on its own).
+    const claimed = isObj(packet.export) ? str(packet.export.content_hash) : null;
+    const computed = packetContentHash(packet);
+    if (!claimed)
+        report.content_hash = { status: "missing" };
+    else if (strip(claimed) === computed.hex)
+        report.content_hash = { status: "verified" };
+    else
+        report.content_hash = legacySchema
+            ? { status: "not_reproducible", detail: "1.x hashes the writer's key order; storage may have reordered keys" }
+            : { status: "mismatch" };
+    // 3. Manifest (2.x): rebuilt from the packet, compared with the hash frozen at seal.
+    let rebuilt = null;
+    if (legacySchema)
+        report.manifest = { status: "not_in_schema" };
+    else {
+        const frozen = str(packet.manifest_hash);
+        try {
+            rebuilt = seal ? (0, manifest_1.manifestHash)((0, manifest_1.buildManifest)(manifestInputFromPacket(packet))) : null;
+        }
+        catch {
+            rebuilt = null;
+        }
+        if (!frozen)
+            report.manifest = { status: "not_frozen", detail: seal ? "sealed before run manifests existed" : "run not sealed" };
+        else if (rebuilt && strip(frozen) === rebuilt)
+            report.manifest = { status: "verified" };
+        else
+            report.manifest = { status: "mismatch", detail: "run context or out-of-chain event fields differ from what was frozen at seal" };
+    }
+    const receiptCtx = { runId, run: packet.run, seal, manifest: rebuilt, events: packet.events.length };
+    // 4. The server's receipt inside the packet: signature only counts against keys the verifier trusts.
+    const packetReceipt = isObj(packet.receipt) ? packet.receipt : null;
+    if (!packetReceipt) {
+        report.packet_receipt = { status: "not_present" };
+        report.signature = { status: "not_present" };
+    }
+    else {
+        report.signature = (0, receipt_1.checkReceiptSignature)(packetReceipt, trusted);
+        const why = receiptMismatch(packetReceipt.statement, receiptCtx);
+        report.packet_receipt = why ? { status: "mismatch", detail: why } : { status: "matches_packet" };
+    }
+    // 5. A receipt the verifier kept: the anchor that a fully recomputed packet cannot match.
+    if (!opts.trustedReceipt) {
+        report.trusted_receipt = { status: "not_provided" };
+        report.trusted_receipt_signature = { status: "not_provided" };
+    }
+    else {
+        report.trusted_receipt_signature = (0, receipt_1.checkReceiptSignature)(opts.trustedReceipt, trusted);
+        const why = rebuilt ? receiptMismatch(opts.trustedReceipt.statement, receiptCtx) : null;
+        if (!rebuilt)
+            report.trusted_receipt = { status: "cannot_compare", detail: "packet has no reproducible manifest (unsealed or schema 1.x)" };
+        else if (why)
+            report.trusted_receipt = { status: "mismatch", detail: `packet differs from the run you hold a receipt for: ${why}` };
+        else
+            report.trusted_receipt = { status: "match" };
+    }
+    const failed = report.chain.status === "broken" ||
+        report.content_hash.status === "mismatch" ||
+        report.manifest.status === "mismatch" ||
+        report.signature.status === "invalid" ||
+        report.packet_receipt.status === "mismatch" ||
+        report.trusted_receipt.status === "mismatch" ||
+        report.trusted_receipt.status === "cannot_compare" ||
+        report.trusted_receipt_signature.status === "invalid";
+    report.anchored =
+        !failed && (report.signature.status === "valid_trusted" || report.trusted_receipt.status === "match");
+    report.overall = failed
+        ? "failed"
+        : report.chain.status === "legacy"
+            ? "legacy_unchained"
+            : report.chain.status === "consistent_unsealed"
+                ? "consistent_unsealed"
+                : legacySchema || report.manifest.status !== "verified" || report.content_hash.status !== "verified"
+                    ? "verified_partial"
+                    : "verified";
+    return report;
+}

package/dist/evidence-chain/src/receipt.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.signReceipt = signReceipt;
+exports.publicKeyOf = publicKeyOf;
+exports.checkReceiptSignature = checkReceiptSignature;
+const node_crypto_1 = require("node:crypto");
+const canonicalize_1 = require("./canonicalize");
+function toPublicKey(material) {
+    return material.includes("BEGIN")
+        ? (0, node_crypto_1.createPublicKey)(material)
+        : (0, node_crypto_1.createPublicKey)({ key: Buffer.from(material, "base64"), format: "der", type: "spki" });
+}
+function toPrivateKey(material) {
+    return material.includes("BEGIN")
+        ? (0, node_crypto_1.createPrivateKey)(material)
+        : (0, node_crypto_1.createPrivateKey)({ key: Buffer.from(material, "base64"), format: "der", type: "pkcs8" });
+}
+const statementBytes = (s) => Buffer.from((0, canonicalize_1.canonicalize)(s), "utf8");
+/** Sign with an Ed25519 private key (base64 PKCS8 DER or PEM). The key never leaves this call. */
+function signReceipt(statement, privateKey, keyId) {
+    const value = (0, node_crypto_1.sign)(null, statementBytes(statement), toPrivateKey(privateKey)).toString("base64");
+    return { statement, signature: { alg: "Ed25519", key_id: keyId, value } };
+}
+/** base64 SPKI DER public key for a private key — what the server publishes for verifiers. */
+function publicKeyOf(privateKey) {
+    return (0, node_crypto_1.createPublicKey)(toPrivateKey(privateKey)).export({ format: "der", type: "spki" }).toString("base64");
+}
+/** Check a receipt's signature against keys the caller trusts. A key carried in the packet is never used. */
+function checkReceiptSignature(receipt, trusted) {
+    const sig = receipt.signature;
+    if (!sig)
+        return { status: "not_present" };
+    if (sig.alg !== "Ed25519")
+        return { status: "invalid", key_id: sig.key_id, reason: `unsupported alg ${sig.alg}` };
+    const key = trusted.find((k) => k.key_id === sig.key_id);
+    if (!key)
+        return { status: "untrusted_key", key_id: sig.key_id };
+    try {
+        const ok = (0, node_crypto_1.verify)(null, statementBytes(receipt.statement), toPublicKey(key.public_key), Buffer.from(sig.value, "base64"));
+        return ok ? { status: "valid_trusted", key_id: sig.key_id } : { status: "invalid", key_id: sig.key_id, reason: "signature does not match" };
+    }
+    catch {
+        return { status: "invalid", key_id: sig.key_id, reason: "unreadable key or signature" };
+    }
+}

package/dist/evidence-chain/src/representable.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unrepresentableKeyPath = unrepresentableKeyPath;
+/**
+ * aer-canonical/1 rebuilds objects by assignment (`out[k] = …`). An OWN "__proto__" key — which
+ * JSON.parse creates as plain data — is therefore re-routed to the prototype and silently left out
+ * of the hashed bytes: anything under it is not covered by any hash. The algorithm is frozen (old
+ * records were hashed that way), so such content is refused instead: at the API boundary (never
+ * written) and in the verifier (a packet carrying one is malformed, never "verified").
+ * Returns the JSON path of the first such key, or null.
+ */
+function unrepresentableKeyPath(value, path = "$") {
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            const p = unrepresentableKeyPath(value[i], `${path}[${i}]`);
+            if (p)
+                return p;
+        }
+        return null;
+    }
+    if (value !== null && typeof value === "object") {
+        if (Object.prototype.hasOwnProperty.call(value, "__proto__"))
+            return `${path}.__proto__`;
+        for (const k of Object.keys(value)) {
+            const p = unrepresentableKeyPath(value[k], `${path}.${k}`);
+            if (p)
+                return p;
+        }
+    }
+    return null;
+}

package/dist/evidence-chain/src/types.js

@@ -0,0 +1,3 @@
+"use strict";
+// Shared shapes. Framework-agnostic — no Prisma, no app types leak in here.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/evidence-chain/src/verify.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyChain = verifyChain;
+const hash_1 = require("./hash");
+/**
+ * The single shared verifier. Pure: input is ONLY the links + seal (+ runId for genesis).
+ * No DB, no app context, no I/O. Consumers map their source (packet JSON / DB rows) into
+ * ChainLink[] and delegate here — never reimplement chain logic.
+ */
+function verifyChain(links, seal, runId) {
+    const ordered = [...links].sort((a, b) => a.seq - b.seq);
+    // A run created before the chain feature carries no hashes — distinct from tampering.
+    if (ordered.length > 0 && ordered.every((l) => !l.hash && !l.prevHash)) {
+        return { ok: false, status: "legacy", reason: "no chain present (pre-chain run)" };
+    }
+    let prev = (0, hash_1.genesisHash)(runId);
+    let checked = 0;
+    for (const link of ordered) {
+        if (link.prevHash !== prev) {
+            return {
+                ok: false,
+                status: "broken",
+                brokenSeq: link.seq,
+                reason: `prevHash mismatch at seq ${link.seq}`,
+                checkedCount: checked,
+            };
+        }
+        if (link.hash !== (0, hash_1.hashEvent)(prev, link)) {
+            return {
+                ok: false,
+                status: "broken",
+                brokenSeq: link.seq,
+                reason: `content hash mismatch at seq ${link.seq}`,
+                checkedCount: checked,
+            };
+        }
+        prev = link.hash;
+        checked++;
+    }
+    // seal is null while a run is still running: nothing to compare the head against yet.
+    if (seal === null)
+        return { ok: true, status: "consistent_unsealed", checkedCount: checked };
+    if (seal !== prev) {
+        const lastSeq = ordered.length ? ordered[ordered.length - 1].seq : 0;
+        return {
+            ok: false,
+            status: "broken",
+            brokenSeq: lastSeq,
+            reason: "seal does not match chain head",
+            checkedCount: checked,
+        };
+    }
+    return { ok: true, status: "verified", checkedCount: checked };
+}

package/dist/evidence-chain/src/versions.js

@@ -0,0 +1,21 @@
+"use strict";
+// Named, frozen algorithm versions. A version string never changes meaning: any change to what is
+// hashed, or how, gets a NEW identifier and the old one keeps verifying historical records.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_PACKET_SCHEMAS = exports.CONTENT_HASH_LEGACY = exports.CONTENT_HASH = exports.RECEIPT = exports.MANIFEST = exports.CHAIN = exports.CANONICALIZATION = void 0;
+/** canonicalize(): sorted object keys, undefined → null, JSON.stringify for leaves (see canonicalize.ts). */
+exports.CANONICALIZATION = "aer-canonical/1";
+/** hashEvent()/genesisHash(): sha256(prevHash + "\n" + canonical(coreView)), genesis "AER-CHAIN-v1:" + runId. */
+exports.CHAIN = "aer-chain/1";
+/** buildManifest(): run context + per-event out-of-chain fields, frozen at seal. */
+exports.MANIFEST = "aer-manifest/1";
+/** Receipt statement + optional Ed25519 signature over its canonical bytes. */
+exports.RECEIPT = "aer-receipt/1";
+/** Packet content_hash for schema >= 2.0: sha256(canonical(packet without export.content_hash)). */
+exports.CONTENT_HASH = "aer-canonical/1+sha256";
+/**
+ * Packet content_hash for schema 1.x: sha256(JSON.stringify(packet)) in the writer's key order.
+ * Only reproducible while that order survives (it does not through JSONB storage).
+ */
+exports.CONTENT_HASH_LEGACY = "emission-order-json+sha256";
+exports.SUPPORTED_PACKET_SCHEMAS = ["1.1", "1.2", "1.3", "2.0"];

package/package.json

@@ -1,6 +1,38 @@
-{
-  "name": "@ktlsr/aer-verify",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@ktlsr/aer-verify",
+  "version": "0.1.0",
+  "description": "Offline verifier for Agent Evidence Recorder audit packets: chain, manifest, content hash, seal, receipt and signature — no network, no AER account.",
+  "license": "MIT",
+  "author": "ktlesr",
+  "type": "commonjs",
+  "bin": {
+    "aer-verify": "dist/aer-verify/src/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsc -p tsconfig.json && node --test test/cli.test.js test/review-stage4.test.js",
+    "prepublishOnly": "tsc -p tsconfig.json && node --test test/cli.test.js test/review-stage4.test.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ktlesr/aer.git",
+    "directory": "packages/aer-verify"
+  },
+  "homepage": "https://aer.ktlsr.com",
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "typescript": "^5"
+  }
+}