@moonglade/provenance 0.0.0-stage → 2.6.0

package/dist/merkle.js

@@ -0,0 +1,176 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nodeHash = exports.leafHash = exports.MERKLE_ALGORITHM = void 0;
+exports.leavesFromRegistry = leavesFromRegistry;
+exports.buildLevels = buildLevels;
+exports.merkleRoot = merkleRoot;
+exports.inclusionProof = inclusionProof;
+exports.verifyProof = verifyProof;
+const crypto = __importStar(require("crypto"));
+/**
+ * RFC 6962 Merkle tree over vault artifacts, with inclusion proofs.
+ *
+ * WHY THIS REPLACES scanAndAudit's ROOT
+ * -------------------------------------
+ * `ProvenanceVault.scanAndAudit` computed its "merkleRoot" as a single SHA-256
+ * over every hash concatenated together. That is a manifest checksum. It detects
+ * that something changed and nothing else - in particular it cannot produce an
+ * inclusion proof, which is the only reason to use a tree in the first place.
+ *
+ * With a tree, a third party can verify ONE document against a published root
+ * without downloading the whole registry: log2(n) hashes, about 9 for a few
+ * hundred artifacts. With a linear digest they would need every artifact hash in
+ * the vault to check a single file.
+ *
+ * DOMAIN SEPARATION
+ * -----------------
+ * Leaves are hashed with a 0x00 prefix and internal nodes with 0x01. Without it
+ * an internal node can be presented as a leaf - a second-preimage attack on the
+ * tree shape.
+ *
+ * Odd nodes are PROMOTED, never duplicated. Duplicating the last leaf lets two
+ * distinct trees share a root, which is the Bitcoin CVE-2012-2459 class of bug.
+ *
+ * PARITY WITH THE PYTHON IMPLEMENTATION
+ * -------------------------------------
+ * This is a deliberate port of the vault's `_merkle.py` and must agree with it
+ * byte for byte - two disagreeing provenance implementations would be worse than
+ * one honest flat digest. Leaf ordering, leaf encoding (note the TWO spaces
+ * between hash and path) and the empty-tree value are all fixed by that
+ * requirement, and `merkle.test.ts` checks against roots generated by the Python.
+ */
+exports.MERKLE_ALGORITHM = 'merkle-sha256-rfc6962';
+const LEAF_PREFIX = Buffer.from([0x00]);
+const NODE_PREFIX = Buffer.from([0x01]);
+const sha256 = (b) => crypto.createHash('sha256').update(b).digest();
+const leafHash = (data) => sha256(Buffer.concat([LEAF_PREFIX, data]));
+exports.leafHash = leafHash;
+const nodeHash = (left, right) => sha256(Buffer.concat([NODE_PREFIX, left, right]));
+exports.nodeHash = nodeHash;
+/**
+ * Deterministic leaf order: sorted by path. Walk order is not stable across
+ * filesystems; sorting is.
+ */
+function leavesFromRegistry(artifacts) {
+    return Object.keys(artifacts).sort().map(p => [p, (0, exports.leafHash)(Buffer.from(`${artifacts[p].sha256}  ${p}`, 'utf8'))]);
+}
+/** Every level, leaves first, root last. */
+function buildLevels(leaves) {
+    if (leaves.length === 0)
+        return [[sha256(Buffer.alloc(0))]];
+    const levels = [leaves];
+    while (levels[levels.length - 1].length > 1) {
+        const cur = levels[levels.length - 1];
+        const next = [];
+        for (let i = 0; i + 1 < cur.length; i += 2)
+            next.push((0, exports.nodeHash)(cur[i], cur[i + 1]));
+        if (cur.length % 2)
+            next.push(cur[cur.length - 1]); // promote, never duplicate
+        levels.push(next);
+    }
+    return levels;
+}
+function merkleRoot(artifacts) {
+    const leaves = leavesFromRegistry(artifacts).map(([, h]) => h);
+    const levels = buildLevels(leaves);
+    return levels[levels.length - 1][0].toString('hex');
+}
+/** The sibling hashes needed to rebuild the root from one leaf. */
+function inclusionProof(artifacts, target) {
+    const entries = leavesFromRegistry(artifacts);
+    const idx = entries.findIndex(([p]) => p === target);
+    if (idx === -1)
+        return null;
+    const levels = buildLevels(entries.map(([, h]) => h));
+    const proof = [];
+    let i = idx;
+    for (const level of levels.slice(0, -1)) {
+        const sibling = i ^ 1;
+        if (sibling < level.length) {
+            proof.push({
+                side: sibling > i ? 'right' : 'left',
+                hash: level[sibling].toString('hex')
+            });
+        }
+        // A promoted node has no sibling at this level; the index still halves.
+        i = Math.floor(i / 2);
+    }
+    return {
+        algorithm: exports.MERKLE_ALGORITHM,
+        artifact: target,
+        artifact_sha256: artifacts[target].sha256,
+        leaf_sha256: entries[idx][1].toString('hex'),
+        leaf_index: idx,
+        tree_size: entries.length,
+        proof,
+        merkle_root: levels[levels.length - 1][0].toString('hex')
+    };
+}
+/**
+ * Recompute the root from a leaf plus its audit path.
+ * If expectedRoot is provided, validates that the proof resolves to it.
+ */
+function verifyProof(proof, expectedRoot, expectedArtifact) {
+    try {
+        const hex = (value) => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+        if (!proof || proof.algorithm !== exports.MERKLE_ALGORITHM || typeof proof.artifact !== 'string' || !proof.artifact ||
+            !hex(proof.artifact_sha256) || !hex(proof.leaf_sha256) || !hex(proof.merkle_root) ||
+            !Number.isSafeInteger(proof.tree_size) || proof.tree_size < 1 || !Number.isSafeInteger(proof.leaf_index) || proof.leaf_index < 0 || proof.leaf_index >= proof.tree_size ||
+            !Array.isArray(proof.proof) || proof.proof.length > 53 || (expectedRoot !== undefined && (!hex(expectedRoot) || proof.merkle_root !== expectedRoot)))
+            return false;
+        if (expectedArtifact && (expectedArtifact.path !== proof.artifact || expectedArtifact.sha256 !== proof.artifact_sha256))
+            return false;
+        let h = (0, exports.leafHash)(Buffer.from(`${proof.artifact_sha256}  ${proof.artifact}`, 'utf8'));
+        if (h.toString('hex') !== proof.leaf_sha256)
+            return false;
+        let index = proof.leaf_index, width = proof.tree_size, stepIndex = 0;
+        while (width > 1) {
+            if (index % 2 === 1 || index + 1 < width) {
+                const step = proof.proof[stepIndex++];
+                if (!step || !hex(step.hash) || step.side !== (index % 2 === 1 ? 'left' : 'right'))
+                    return false;
+                const sibling = Buffer.from(step.hash, 'hex');
+                h = step.side === 'left' ? (0, exports.nodeHash)(sibling, h) : (0, exports.nodeHash)(h, sibling);
+            }
+            index = Math.floor(index / 2);
+            width = Math.ceil(width / 2);
+        }
+        return stepIndex === proof.proof.length && h.toString('hex') === proof.merkle_root;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/self-test.d.ts

@@ -0,0 +1,21 @@
+export interface ConditionResult {
+    name: string;
+    passed: boolean;
+    durationMs: number;
+    error?: string;
+    details?: string;
+}
+export interface SelfTestReport {
+    passed: boolean;
+    version: string;
+    nodeVersion: string;
+    platform: string;
+    conditions: ConditionResult[];
+    totalDurationMs: number;
+    verifiedPackageArtifacts: number;
+}
+export declare function runSelfTests(options?: {
+    packageRoot?: string;
+    verbose?: boolean;
+}): Promise<SelfTestReport>;
+export declare function printSelfTestReport(report: SelfTestReport): void;

package/dist/self-test.js

@@ -0,0 +1,280 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSelfTests = runSelfTests;
+exports.printSelfTestReport = printSelfTestReport;
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+const index_1 = require("./index");
+const merkle_1 = require("./merkle");
+const artifactEnvelope_1 = require("./artifactEnvelope");
+const timestamp_1 = require("./timestamp");
+async function runSelfTests(options = {}) {
+    const startTime = Date.now();
+    const root = options.packageRoot ?? path.resolve(__dirname, '..');
+    const conditions = [];
+    // Helper to record condition results
+    async function runCondition(name, fn) {
+        const t0 = Date.now();
+        try {
+            const details = await fn();
+            conditions.push({
+                name,
+                passed: true,
+                durationMs: Date.now() - t0,
+                details: details || undefined
+            });
+        }
+        catch (err) {
+            conditions.push({
+                name,
+                passed: false,
+                durationMs: Date.now() - t0,
+                error: err?.message || String(err)
+            });
+        }
+    }
+    // Condition 1: Ed25519 Micro-Signatures & Structured V2 Framing
+    await runCondition('Ed25519 Micro-Signatures & V2 Framing', async () => {
+        const keyPair = index_1.ProvenanceEngine.generateEd25519KeyPair();
+        const digest = 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855';
+        const payload = index_1.ProvenanceEngine.buildSigningPayload({
+            scope: 'moonglade:self-test:doc',
+            sha256: digest,
+            signer: 'test@moonglade.ai'
+        });
+        const signature = crypto.sign(null, payload, keyPair.privateKey);
+        const valid = crypto.verify(null, payload, keyPair.publicKey, signature);
+        if (!valid)
+            throw new Error('Valid signature failed verification');
+        // Reject tampered payload
+        const tamperedPayload = index_1.ProvenanceEngine.buildSigningPayload({
+            scope: 'moonglade:self-test:doc',
+            sha256: '0000000000000000000000000000000000000000000000000000000000000000',
+            signer: 'test@moonglade.ai'
+        });
+        const tamperedPayloadValid = crypto.verify(null, tamperedPayload, keyPair.publicKey, signature);
+        if (tamperedPayloadValid)
+            throw new Error('Tampered payload was accepted as valid');
+        // Reject tampered signature
+        const corruptedSig = Buffer.from(signature);
+        corruptedSig[0] ^= 0xff;
+        const tamperedSigValid = crypto.verify(null, payload, keyPair.publicKey, corruptedSig);
+        if (tamperedSigValid)
+            throw new Error('Corrupted signature was accepted as valid');
+        return 'Sign, verify, and tamper rejection passed';
+    });
+    // Condition 2: RFC 6962 Merkle Trees & Leaf Inclusion Proofs
+    await runCondition('RFC 6962 Merkle Trees & Inclusion Proofs', async () => {
+        const mockRegistry = {
+            'docs/a.md': { sha256: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' },
+            'docs/b.md': { sha256: 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb' },
+            'docs/c.md': { sha256: 'cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc' },
+            'docs/d.md': { sha256: 'dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd' }
+        };
+        const root = (0, merkle_1.merkleRoot)(mockRegistry);
+        if (!/^[0-9a-f]{64}$/.test(root))
+            throw new Error('Invalid Merkle root derived');
+        const proof = (0, merkle_1.inclusionProof)(mockRegistry, 'docs/c.md');
+        if (!proof)
+            throw new Error('Inclusion proof derivation failed for existing leaf');
+        const validProof = (0, merkle_1.verifyProof)(proof, root);
+        if (!validProof)
+            throw new Error('Valid inclusion proof failed mathematical verification');
+        // Corrupted proof must fail
+        const corruptedProof = JSON.parse(JSON.stringify(proof));
+        corruptedProof.proof[0].hash = '0000000000000000000000000000000000000000000000000000000000000000';
+        if ((0, merkle_1.verifyProof)(corruptedProof, root))
+            throw new Error('Corrupted inclusion proof was accepted');
+        // Missing artifact returns null
+        if ((0, merkle_1.inclusionProof)(mockRegistry, 'docs/missing.md') !== null) {
+            throw new Error('Inclusion proof returned non-null for missing leaf');
+        }
+        return `Tree of size 4 verified; root ${root.slice(0, 12)}...`;
+    });
+    // Condition 3: Artifact Envelope v1 Contract & Canonical Byte Binding
+    await runCondition('Artifact Envelope v1 Schema & Hash Binding', async () => {
+        const rawBytes = Buffer.from('# Moonglade Self Test\nInvariant proof substrate.', 'utf8');
+        const expectedId = (0, artifactEnvelope_1.artifactId)(rawBytes);
+        const envelope = (0, artifactEnvelope_1.createArtifactEnvelope)({
+            artifact_type: 'release',
+            canonical_bytes: expectedId,
+            created_at: new Date().toISOString(),
+            parents: [],
+            attestations: [{ method: 'self-test', status: 'provisional' }],
+            status: 'signed',
+            evidence: { integrity: 'valid', signature: 'provisional', timestamp: 'none', scope: 'valid' },
+            generator: { agent: 'synthetic-test', model: 'self-test-harness' },
+            bytes: rawBytes
+        });
+        if (!(0, artifactEnvelope_1.validateArtifactEnvelope)(envelope))
+            throw new Error('Constructed envelope failed schema validation');
+        if (envelope.artifact_id !== expectedId)
+            throw new Error('Envelope artifact_id does not match canonical bytes hash');
+        // Tampered schema must fail
+        const tampered = { ...envelope, artifact_id: 'invalid-id' };
+        if ((0, artifactEnvelope_1.validateArtifactEnvelope)(tampered))
+            throw new Error('Invalid envelope format was accepted as valid');
+        return `Envelope ${envelope.artifact_id.slice(0, 19)}... verified`;
+    });
+    // Condition 4: Fail-Closed Gate Barriers & Anti-Tampering Rejection
+    await runCondition('Fail-Closed Gate Barriers & Mutation Rejection', async () => {
+        const tempDir = path.join(root, '.tmp-selftest-' + Date.now());
+        await fs.mkdir(tempDir, { recursive: true });
+        const testDoc = path.join(tempDir, 'gate-test.md');
+        const keyPair = index_1.ProvenanceEngine.generateEd25519KeyPair();
+        try {
+            await fs.writeFile(testDoc, '# Gate Assertion Test\nOriginal untouched bytes.\n', 'utf8');
+            await index_1.ProvenanceEngine.sealDocument(testDoc, keyPair.privateKey, 'test-signer', 'head', {
+                vaultRoot: tempDir,
+                timestamp: false
+            });
+            // Valid check must pass
+            const initialVerify = await index_1.ProvenanceEngine.verifyDocument(testDoc, keyPair.publicKey);
+            if (!initialVerify.verified) {
+                throw new Error(`Expected verification to succeed: ${initialVerify.error}`);
+            }
+            // Mutate the document
+            await fs.appendFile(testDoc, '\nMalicious unsealed line inserted.\n', 'utf8');
+            const tamperedVerify = await index_1.ProvenanceEngine.verifyDocument(testDoc, keyPair.publicKey);
+            if (tamperedVerify.verified) {
+                throw new Error('Mutated document passed verification; fail-closed gate violated');
+            }
+            if (!tamperedVerify.error?.includes('Hash mismatch')) {
+                throw new Error(`Expected hash mismatch error, got: ${tamperedVerify.error}`);
+            }
+            return 'Sealed artifact verified; post-seal modification rejected fail-closed';
+        }
+        finally {
+            await fs.rm(tempDir, { recursive: true, force: true }).catch(() => { });
+        }
+    });
+    // Condition 5: Concurrent Degrading Timestamping Architecture (DTA)
+    await runCondition('Concurrent Degrading Timestamp Architecture (DTA)', async () => {
+        const dummyDigest = crypto.createHash('sha256').update('dta-test').digest();
+        const dta = await (0, timestamp_1.concurrentDegradingTimestamp)(dummyDigest, { specifiedTier: 'L4_HOST_UNAUTHENTICATED' });
+        if (!dta.tier || dta.tier !== 'L4_HOST_UNAUTHENTICATED') {
+            throw new Error(`Expected L4 offline degradation tier, got ${dta.tier}`);
+        }
+        if (!dta.tsa_time || isNaN(Date.parse(dta.tsa_time))) {
+            throw new Error('Invalid ISO timestamp returned by DTA degradation fallback');
+        }
+        if (!Array.isArray(dta.probes) || dta.probes.length === 0) {
+            throw new Error('Expected probe audit telemetry in DTA result');
+        }
+        return `Degraded to ${dta.tier} at ${dta.tsa_time}`;
+    });
+    // Condition 6: Package Self-Provenance (All Shipped Items Carry Provenance)
+    let verifiedCount = 0;
+    await runCondition('Package Self-Provenance Verification', async () => {
+        // Look for all .provenance.json files directly in package root and docs
+        const entries = await fs.readdir(root, { withFileTypes: true });
+        const sidecarFiles = [];
+        for (const ent of entries) {
+            if (ent.isFile() && ent.name.endsWith('.provenance.json')) {
+                sidecarFiles.push(path.join(root, ent.name));
+            }
+        }
+        // Only package-root sidecars belong to this distribution inventory.
+        if (sidecarFiles.length === 0) {
+            return 'No shipped sidecars; distribution files are intentionally unsealed pending release approval';
+        }
+        for (const sidecarPath of sidecarFiles) {
+            const sidecarRaw = await fs.readFile(sidecarPath, 'utf8');
+            const sidecar = JSON.parse(sidecarRaw);
+            const targetPath = sidecarPath.replace(/\.provenance\.json$/, '');
+            let fileBytes;
+            try {
+                fileBytes = await fs.readFile(targetPath);
+            }
+            catch {
+                // Special case: package.provenance.json may target package.json
+                if (path.basename(sidecarPath) === 'package.provenance.json') {
+                    fileBytes = await fs.readFile(path.join(root, 'package.json'));
+                }
+                else {
+                    throw new Error(`Target artifact missing for sidecar: ${path.basename(sidecarPath)}`);
+                }
+            }
+            const compareBytes = index_1.ProvenanceEngine.canonicalizeBytes(fileBytes, path.basename(sidecarPath) === 'package.provenance.json' ? 'package.json' : targetPath);
+            const computedHash = crypto.createHash('sha256').update(compareBytes).digest('hex');
+            if (!/^[a-f0-9]{64}$/.test(sidecar.sha256_at_last_write) || sidecar.sha256_at_last_write !== computedHash) {
+                throw new Error(`Hash mismatch on shipped artifact ${path.basename(targetPath)}: sidecar has ${sidecar.sha256_at_last_write}, actual is ${computedHash}`);
+            }
+            if (sidecar.envelope) {
+                if (!(0, artifactEnvelope_1.validateArtifactEnvelope)(sidecar.envelope)) {
+                    throw new Error(`Invalid envelope on shipped artifact ${path.basename(targetPath)}`);
+                }
+            }
+            verifiedCount++;
+        }
+        return `${verifiedCount} shipped sidecar hashes compared; no package signature verification performed`;
+    });
+    const totalDurationMs = Date.now() - startTime;
+    const passed = conditions.every(c => c.passed);
+    return {
+        passed,
+        version: require('../package.json').version,
+        nodeVersion: process.version,
+        platform: `${process.platform}-${process.arch}`,
+        conditions,
+        totalDurationMs,
+        verifiedPackageArtifacts: verifiedCount
+    };
+}
+function printSelfTestReport(report) {
+    console.log(`\nMoonglade Provenance Self-Test Suite v${report.version} (${report.platform}, Node ${report.nodeVersion})`);
+    console.log('='.repeat(75));
+    for (let i = 0; i < report.conditions.length; i++) {
+        const c = report.conditions[i];
+        const statusTag = c.passed ? '[PASS]' : '[FAIL]';
+        console.log(`${statusTag} ${i + 1}. ${c.name} (${c.durationMs}ms)`);
+        if (c.details) {
+            console.log(`       Evidence: ${c.details}`);
+        }
+        if (c.error) {
+            console.log(`       Error: ${c.error}`);
+        }
+    }
+    console.log('-'.repeat(75));
+    if (report.passed) {
+        console.log(`All ${report.conditions.length} condition suites PASSED (${report.totalDurationMs}ms). Environment verified.`);
+    }
+    else {
+        const failedCount = report.conditions.filter(c => !c.passed).length;
+        console.error(`${failedCount} condition suite(s) FAILED (${report.totalDurationMs}ms). Verification failed.`);
+    }
+}