@finguard/pack-spec 1.0.0

package/dist/canonical.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Canonical JSON — the only serialization allowed inside a pack_hash preimage.
+ * Rules (Evidence Pack Spec v1 §3): lexicographically sorted object keys,
+ * no insignificant whitespace, UTF-8. Arrays keep their order (callers must
+ * pre-sort where the spec requires it, e.g. attested_files by name).
+ */
+export type Json = string | number | boolean | null | Json[] | {
+    [key: string]: Json;
+};
+export declare function canonicalJson(value: Json): string;

package/dist/canonical.js

@@ -0,0 +1,16 @@
+export function canonicalJson(value) {
+    if (value === null || typeof value !== "object") {
+        if (typeof value === "number" && !Number.isFinite(value)) {
+            throw new Error("canonicalJson: non-finite numbers are not permitted");
+        }
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalJson).join(",")}]`;
+    }
+    const keys = Object.keys(value).sort();
+    const body = keys
+        .map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`)
+        .join(",");
+    return `{${body}}`;
+}

package/dist/ed25519.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Ed25519 verification via WebCrypto (Node >= 18, Chrome >= 113, Firefox,
+ * Safari). Signing is NOT implemented here — signing is the commercial
+ * control plane's job; the open verifier only ever needs public keys.
+ * (Spec v1 §7: the format is open, the trust anchor is operated.)
+ */
+export declare function verifyEd25519(opts: {
+    /** 32-byte raw public key, as hex or base64 string, or raw bytes. */
+    publicKey: string | Uint8Array;
+    /** The message that was signed: ascii(pack_hash). */
+    message: string;
+    /** Base64 signature from MANIFEST.signature. */
+    signatureBase64: string;
+}): Promise<boolean>;
+/** Key registry format (Spec v1 §7). */
+export interface RegistryKey {
+    key_id: string;
+    alg: "ed25519";
+    /** base64 or hex raw 32-byte public key */
+    public_key: string;
+    valid_from: string;
+    revoked_at?: string | null;
+}
+export declare function findRegistryKey(registry: RegistryKey[], key_id: string): RegistryKey | undefined;

package/dist/ed25519.js

@@ -0,0 +1,26 @@
+import { fromBase64, fromHex, utf8 } from "./hash.js";
+/**
+ * Ed25519 verification via WebCrypto (Node >= 18, Chrome >= 113, Firefox,
+ * Safari). Signing is NOT implemented here — signing is the commercial
+ * control plane's job; the open verifier only ever needs public keys.
+ * (Spec v1 §7: the format is open, the trust anchor is operated.)
+ */
+export async function verifyEd25519(opts) {
+    const raw = normalizeKey(opts.publicKey);
+    if (raw.byteLength !== 32) {
+        throw new Error(`Ed25519 public key must be 32 raw bytes, got ${raw.byteLength}`);
+    }
+    const key = await crypto.subtle.importKey("raw", raw, { name: "Ed25519" }, false, ["verify"]);
+    return crypto.subtle.verify({ name: "Ed25519" }, key, fromBase64(opts.signatureBase64), utf8(opts.message));
+}
+function normalizeKey(key) {
+    if (typeof key !== "string")
+        return key;
+    const trimmed = key.trim();
+    if (/^[0-9a-fA-F]{64}$/.test(trimmed))
+        return fromHex(trimmed);
+    return fromBase64(trimmed);
+}
+export function findRegistryKey(registry, key_id) {
+    return registry.find((k) => k.key_id === key_id && !k.revoked_at);
+}

package/dist/hash.d.ts

@@ -0,0 +1,9 @@
+/**
+ * SHA-256 via WebCrypto — available in every modern browser and Node >= 18.
+ * Zero dependencies keeps the verifier trivially auditable.
+ */
+export declare function sha256Hex(bytes: Uint8Array): Promise<string>;
+export declare function hex(bytes: Uint8Array): string;
+export declare function fromHex(s: string): Uint8Array;
+export declare function fromBase64(s: string): Uint8Array;
+export declare function utf8(s: string): Uint8Array;

package/dist/hash.js

@@ -0,0 +1,35 @@
+/**
+ * SHA-256 via WebCrypto — available in every modern browser and Node >= 18.
+ * Zero dependencies keeps the verifier trivially auditable.
+ */
+export async function sha256Hex(bytes) {
+    const digest = await crypto.subtle.digest("SHA-256", bytes);
+    return hex(new Uint8Array(digest));
+}
+export function hex(bytes) {
+    let out = "";
+    for (const b of bytes)
+        out += b.toString(16).padStart(2, "0");
+    return out;
+}
+export function fromHex(s) {
+    if (!/^[0-9a-fA-F]*$/.test(s) || s.length % 2 !== 0) {
+        throw new Error("invalid hex string");
+    }
+    const out = new Uint8Array(s.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        out[i] = parseInt(s.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+}
+export function fromBase64(s) {
+    // atob exists in browsers and Node >= 16
+    const bin = atob(s.replace(/\s+/g, ""));
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+export function utf8(s) {
+    return new TextEncoder().encode(s);
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { canonicalJson, type Json } from "./canonical.js";
+export { sha256Hex, hex, fromHex, fromBase64, utf8 } from "./hash.js";
+export { PACK_SPEC_VERSION, fileEntries, packHashPreimage, computePackHash, buildManifest, serializeManifest, type Producer, type Role, type FileEntry, type Manifest, type SignatureStatus, type BuildManifestOptions, } from "./manifest.js";
+export { verifyEd25519, findRegistryKey, type RegistryKey, } from "./ed25519.js";
+export { verifyPack, type VerifyReport, type FileCheck, type SignatureResult, type Scope, } from "./verify-core.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { canonicalJson } from "./canonical.js";
+export { sha256Hex, hex, fromHex, fromBase64, utf8 } from "./hash.js";
+export { PACK_SPEC_VERSION, fileEntries, packHashPreimage, computePackHash, buildManifest, serializeManifest, } from "./manifest.js";
+export { verifyEd25519, findRegistryKey, } from "./ed25519.js";
+export { verifyPack, } from "./verify-core.js";

package/dist/manifest.d.ts

@@ -0,0 +1,78 @@
+export declare const PACK_SPEC_VERSION = "1.0";
+export type Role = "ciso" | "md" | "analyst";
+export interface Producer {
+    user_id: string;
+    display_name: string;
+    role: Role;
+}
+export interface FileEntry {
+    name: string;
+    sha256: string;
+    bytes: number;
+}
+export type SignatureStatus = "unsigned-demo" | "signed";
+export interface Manifest {
+    pack_spec_version: string;
+    generator: {
+        name: string;
+        version: string;
+    };
+    snapshot_id: string;
+    producer: Producer;
+    /** Informational — OUTSIDE the pack_hash preimage (Spec v1 §2). */
+    generated_at: string;
+    /** Informational — OUTSIDE the pack_hash preimage (Spec v1 §2). */
+    requested_at: string;
+    /** Sorted ascending by name (Spec v1 §2). */
+    attested_files: FileEntry[];
+    /** Listed + hashed, but outside the pack_hash preimage (Spec v1 §4). */
+    informational_files: FileEntry[];
+    pack_hash: string;
+    /** Base64 Ed25519 signature over ascii(pack_hash), or null. */
+    signature: string | null;
+    signature_status: SignatureStatus;
+    key_id: string | null;
+    /** Committed to the audit vault BEFORE download (Spec v1 §5). */
+    vault_entry_id: string | null;
+}
+/** Hash every file and return entries sorted ascending by name. */
+export declare function fileEntries(files: ReadonlyMap<string, Uint8Array>): Promise<FileEntry[]>;
+/**
+ * The canonical pack_hash preimage (Spec v1 §3).
+ * Timestamps, generator version, informational files, signature fields and
+ * vault_entry_id are deliberately EXCLUDED — same snapshot + same spec version
+ * + same producer must yield an identical pack_hash regardless of when or
+ * where the pack is built.
+ */
+export declare function packHashPreimage(input: {
+    pack_spec_version: string;
+    snapshot_id: string;
+    producer: Producer;
+    attested_files: FileEntry[];
+}): string;
+export declare function computePackHash(input: {
+    pack_spec_version: string;
+    snapshot_id: string;
+    producer: Producer;
+    attested_files: FileEntry[];
+}): Promise<string>;
+export interface BuildManifestOptions {
+    generator: {
+        name: string;
+        version: string;
+    };
+    snapshot_id: string;
+    producer: Producer;
+    generated_at: string;
+    requested_at: string;
+    attestedFiles: ReadonlyMap<string, Uint8Array>;
+    informationalFiles?: ReadonlyMap<string, Uint8Array>;
+    vault_entry_id?: string | null;
+    signature?: {
+        value: string;
+        key_id: string;
+    } | null;
+}
+export declare function buildManifest(opts: BuildManifestOptions): Promise<Manifest>;
+/** Stable, human-readable serialization used when writing MANIFEST.json to disk. */
+export declare function serializeManifest(manifest: Manifest): string;

package/dist/manifest.js

@@ -0,0 +1,60 @@
+import { canonicalJson } from "./canonical.js";
+import { sha256Hex, utf8 } from "./hash.js";
+export const PACK_SPEC_VERSION = "1.0";
+/** Hash every file and return entries sorted ascending by name. */
+export async function fileEntries(files) {
+    const entries = await Promise.all([...files.entries()].map(async ([name, bytes]) => ({
+        name,
+        sha256: await sha256Hex(bytes),
+        bytes: bytes.byteLength,
+    })));
+    return entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+/**
+ * The canonical pack_hash preimage (Spec v1 §3).
+ * Timestamps, generator version, informational files, signature fields and
+ * vault_entry_id are deliberately EXCLUDED — same snapshot + same spec version
+ * + same producer must yield an identical pack_hash regardless of when or
+ * where the pack is built.
+ */
+export function packHashPreimage(input) {
+    const sorted = [...input.attested_files].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+    return canonicalJson({
+        pack_spec_version: input.pack_spec_version,
+        snapshot_id: input.snapshot_id,
+        producer: { ...input.producer },
+        attested_files: sorted.map((f) => ({ ...f })),
+    });
+}
+export async function computePackHash(input) {
+    return sha256Hex(utf8(packHashPreimage(input)));
+}
+export async function buildManifest(opts) {
+    const attested_files = await fileEntries(opts.attestedFiles);
+    const informational_files = await fileEntries(opts.informationalFiles ?? new Map());
+    const pack_hash = await computePackHash({
+        pack_spec_version: PACK_SPEC_VERSION,
+        snapshot_id: opts.snapshot_id,
+        producer: opts.producer,
+        attested_files,
+    });
+    return {
+        pack_spec_version: PACK_SPEC_VERSION,
+        generator: opts.generator,
+        snapshot_id: opts.snapshot_id,
+        producer: opts.producer,
+        generated_at: opts.generated_at,
+        requested_at: opts.requested_at,
+        attested_files,
+        informational_files,
+        pack_hash,
+        signature: opts.signature?.value ?? null,
+        signature_status: opts.signature ? "signed" : "unsigned-demo",
+        key_id: opts.signature?.key_id ?? null,
+        vault_entry_id: opts.vault_entry_id ?? null,
+    };
+}
+/** Stable, human-readable serialization used when writing MANIFEST.json to disk. */
+export function serializeManifest(manifest) {
+    return JSON.stringify(manifest, null, 2) + "\n";
+}

package/dist/verify-core.d.ts

@@ -0,0 +1,39 @@
+import { type Manifest } from "./manifest.js";
+import { type RegistryKey } from "./ed25519.js";
+export type Scope = "attested" | "informational";
+export interface FileCheck {
+    name: string;
+    scope: Scope;
+    present: boolean;
+    expected_sha256: string;
+    actual_sha256: string | null;
+    expected_bytes: number;
+    actual_bytes: number | null;
+    ok: boolean;
+}
+export type SignatureResult = "signed-verified" | "signed-invalid" | "signed-unverified-no-key" | "unsigned-demo";
+export interface VerifyReport {
+    spec_version: string;
+    spec_supported: boolean;
+    manifest: Manifest;
+    files: FileCheck[];
+    /** Files in the archive that the MANIFEST does not list (MANIFEST/VERIFY/SPEC excluded). */
+    unlisted_files: string[];
+    expected_pack_hash: string;
+    computed_pack_hash: string;
+    pack_hash_ok: boolean;
+    signature: SignatureResult;
+    /** True iff spec supported, every listed file checks out, and pack_hash matches.
+     *  Signature ABSENCE does not fail verification; signature INVALIDITY does. */
+    ok: boolean;
+}
+/**
+ * Verify a pack given its files as bytes — fully offline (Spec v1 §6).
+ * Works identically in the browser and in Node; the CLI is a thin wrapper.
+ */
+export declare function verifyPack(files: ReadonlyMap<string, Uint8Array>, opts?: {
+    /** Raw Ed25519 public key (hex/base64) to verify a signed pack against. */
+    publicKey?: string | Uint8Array;
+    /** Key registry (Spec v1 §7); used when key_id is present and no publicKey given. */
+    registry?: RegistryKey[];
+}): Promise<VerifyReport>;

package/dist/verify-core.js

@@ -0,0 +1,92 @@
+import { sha256Hex } from "./hash.js";
+import { computePackHash, PACK_SPEC_VERSION, } from "./manifest.js";
+import { findRegistryKey, verifyEd25519 } from "./ed25519.js";
+const SELF_FILES = new Set(["MANIFEST.json", "VERIFY.md", "SPEC.md", "UPGRADE.md"]);
+/**
+ * Verify a pack given its files as bytes — fully offline (Spec v1 §6).
+ * Works identically in the browser and in Node; the CLI is a thin wrapper.
+ */
+export async function verifyPack(files, opts = {}) {
+    const manifestBytes = files.get("MANIFEST.json");
+    if (!manifestBytes) {
+        throw new Error("MANIFEST.json not found in pack");
+    }
+    const manifest = JSON.parse(new TextDecoder().decode(manifestBytes));
+    const spec_supported = manifest.pack_spec_version === PACK_SPEC_VERSION;
+    const checks = [];
+    const checkList = async (entries, scope) => {
+        for (const entry of entries ?? []) {
+            const bytes = files.get(entry.name);
+            if (!bytes) {
+                checks.push({
+                    name: entry.name,
+                    scope,
+                    present: false,
+                    expected_sha256: entry.sha256,
+                    actual_sha256: null,
+                    expected_bytes: entry.bytes,
+                    actual_bytes: null,
+                    ok: false,
+                });
+                continue;
+            }
+            const actual = await sha256Hex(bytes);
+            checks.push({
+                name: entry.name,
+                scope,
+                present: true,
+                expected_sha256: entry.sha256,
+                actual_sha256: actual,
+                expected_bytes: entry.bytes,
+                actual_bytes: bytes.byteLength,
+                ok: actual === entry.sha256 && bytes.byteLength === entry.bytes,
+            });
+        }
+    };
+    await checkList(manifest.attested_files, "attested");
+    await checkList(manifest.informational_files, "informational");
+    const listed = new Set([
+        ...(manifest.attested_files ?? []).map((f) => f.name),
+        ...(manifest.informational_files ?? []).map((f) => f.name),
+    ]);
+    const unlisted_files = [...files.keys()].filter((name) => !listed.has(name) && !SELF_FILES.has(name));
+    const computed_pack_hash = await computePackHash({
+        pack_spec_version: manifest.pack_spec_version,
+        snapshot_id: manifest.snapshot_id,
+        producer: manifest.producer,
+        attested_files: manifest.attested_files ?? [],
+    });
+    const pack_hash_ok = computed_pack_hash === manifest.pack_hash;
+    let signature = "unsigned-demo";
+    if (manifest.signature) {
+        let key = opts.publicKey;
+        if (!key && opts.registry && manifest.key_id) {
+            key = findRegistryKey(opts.registry, manifest.key_id)?.public_key;
+        }
+        if (!key) {
+            signature = "signed-unverified-no-key";
+        }
+        else {
+            const valid = await verifyEd25519({
+                publicKey: key,
+                message: manifest.pack_hash,
+                signatureBase64: manifest.signature,
+            });
+            signature = valid ? "signed-verified" : "signed-invalid";
+        }
+    }
+    const filesOk = checks.every((c) => c.ok);
+    const ok = spec_supported && filesOk && pack_hash_ok && signature !== "signed-invalid";
+    return {
+        spec_version: manifest.pack_spec_version,
+        spec_supported,
+        manifest,
+        files: checks,
+        unlisted_files,
+        expected_pack_hash: manifest.pack_hash,
+        computed_pack_hash,
+        pack_hash_ok,
+        signature,
+        ok,
+    };
+}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@finguard/pack-spec",
+  "version": "1.0.0",
+  "description": "Canonical types, hashing, and verification core for the FinGuard Evidence Pack Spec v1 — isomorphic (browser + Node), zero dependencies.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" }
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsc -p ."
+  },
+  "repository": { "type": "git", "url": "git+https://github.com/KGEmmanuel/finguard.git", "directory": "packages/pack-spec" },
+  "keywords": ["ai-governance", "evidence", "audit", "sha256", "ed25519", "regtech"]
+}