@synctek/forgeos 2.0.0

package/dist/trust/ledger.js

@@ -0,0 +1,351 @@
+/**
+ * Local Trust Ledger — hash-chained JSONL audit trail for code intelligence.
+ *
+ * Binary-compatible with the Python ledger.py implementation.
+ *
+ * Each ForgeOS project maintains a local append-only ledger at
+ * `.forgeos/ledger.jsonl`. Entries are hash-chained using SHA-256 over
+ * the canonical fields "seq:prev_hash:payload_hash:timestamp", producing
+ * a tamper-evident record of every analysis run, review, and metric change.
+ *
+ * Chain hash formula:
+ *   chain_hash = SHA-256("{seq}:{prev_hash}:{payload_hash}:{timestamp}")
+ *
+ * JSONL format: one JSON object per line, keys sorted (sort_keys=True),
+ * written with appendFileSync. Matches Python's json.dumps(..., sort_keys=True).
+ *
+ * File locking: Node.js single-threaded event loop provides safe sequential
+ * writes within one process. For cross-process safety, a .ledger.lock file
+ * is created (advisory lock, best-effort) — same approach as Python's
+ * fcntl.LOCK_EX. Full POSIX flock is not available in pure Node stdlib;
+ * the lock file is written atomically and removed after use.
+ *
+ * Entry field order in JSONL (matches Python's sort_keys=True output):
+ *   chain_hash, entry_type, payload, payload_hash, prev_hash, schema_version,
+ *   seq, signature, source_tree_hash, timestamp
+ */
+import { readFileSync, appendFileSync, existsSync, mkdirSync, writeFileSync, unlinkSync, } from 'fs';
+import { join, dirname } from 'path';
+import { GENESIS_SENTINEL, SCHEMA_VERSION, ENTRY_TYPES, computeChainHash, computePayloadHash, pythonJsonDumps, } from './chain.js';
+import { KeyManager } from './signing.js';
+import { computeSourceTreeHash } from './git-binding.js';
+export class LedgerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'LedgerError';
+    }
+}
+export class ChainIntegrityError extends LedgerError {
+    seq;
+    constructor(seq, message) {
+        super(`Chain break at seq ${seq}: ${message}`);
+        this.name = 'ChainIntegrityError';
+        this.seq = seq;
+    }
+}
+// ------------------------------------------------------------------
+// TrustLedger
+// ------------------------------------------------------------------
+/**
+ * Append-only, hash-chained ledger for local code intelligence data.
+ *
+ * The ledger lives at {projectPath}/.forgeos/ledger.jsonl.
+ *
+ * Example:
+ *   const ledger = new TrustLedger('/my/project');
+ *   const entry = ledger.append('analysis_snapshot', { quality_score: 82.4 });
+ *   const result = ledger.verifyChain();
+ *   const stats = ledger.getChainStats();
+ */
+export class TrustLedger {
+    ledgerPath;
+    lockPath;
+    keyManager;
+    constructor(projectPath) {
+        this.ledgerPath = join(projectPath, '.forgeos', 'ledger.jsonl');
+        this.lockPath = join(projectPath, '.forgeos', '.ledger.lock');
+        // Attempt to initialize KeyManager; fall back to null if keys don't exist
+        this.keyManager = new KeyManager(projectPath);
+    }
+    // ------------------------------------------------------------------
+    // Public API
+    // ------------------------------------------------------------------
+    /**
+     * Append a new entry to the ledger and return the complete record.
+     *
+     * Optionally binds to git state (sourceTreeHash) and signs the entry
+     * (signature) if keys are available.
+     *
+     * @param entryType - One of the 7 canonical entry types.
+     * @param payload - Arbitrary JSON-serializable payload dict.
+     * @param repoPath - Optional repo path for git binding.
+     * @param signature - Optional pre-computed Ed25519 signature (base64).
+     *                    If null, the ledger will attempt to self-sign if keys exist.
+     * @returns The complete ledger entry.
+     * @throws LedgerError if the ledger directory does not exist.
+     * @throws Error if entryType is not in ENTRY_TYPES.
+     */
+    append(entryType, payload, repoPath, signature) {
+        if (!ENTRY_TYPES.has(entryType)) {
+            throw new Error(`Unknown entry_type ${JSON.stringify(entryType)}. Valid types: ${[...ENTRY_TYPES].sort().join(', ')}`);
+        }
+        const ledgerDir = dirname(this.ledgerPath);
+        if (!existsSync(ledgerDir)) {
+            throw new LedgerError(`Ledger directory ${ledgerDir} does not exist. Run 'forgeos analyze --init' to initialise the project.`);
+        }
+        // Ensure parent for lock file exists
+        mkdirSync(dirname(this.lockPath), { recursive: true });
+        return this.appendLocked(entryType, payload, repoPath ?? null, signature ?? null);
+    }
+    /**
+     * Verify the integrity of the entire hash chain.
+     *
+     * Walks every entry in order, recomputing each chain_hash and checking
+     * that it matches the stored value, and that prev_hash matches the
+     * chain_hash of the preceding entry.
+     *
+     * @returns VerifyResult with validity, entry count, and first break location.
+     */
+    verifyChain() {
+        if (!existsSync(this.ledgerPath)) {
+            return {
+                valid: true,
+                total_entries: 0,
+                first_break_at: null,
+                message: 'No ledger file — chain trivially valid.',
+            };
+        }
+        const rawLines = this.readRawLines();
+        if (rawLines.length === 0) {
+            return {
+                valid: true,
+                total_entries: 0,
+                first_break_at: null,
+                message: 'Empty ledger — chain trivially valid.',
+            };
+        }
+        let prevChainHash = GENESIS_SENTINEL;
+        for (let i = 0; i < rawLines.length; i++) {
+            let entry;
+            try {
+                entry = JSON.parse(rawLines[i]);
+            }
+            catch (exc) {
+                return {
+                    valid: false,
+                    total_entries: rawLines.length,
+                    first_break_at: i,
+                    message: `Malformed JSON at seq ${i}: ${exc}`,
+                };
+            }
+            if (entry.seq !== i) {
+                return {
+                    valid: false,
+                    total_entries: rawLines.length,
+                    first_break_at: i,
+                    message: `seq mismatch at position ${i}: stored ${entry.seq}`,
+                };
+            }
+            if (entry.prev_hash !== prevChainHash) {
+                return {
+                    valid: false,
+                    total_entries: rawLines.length,
+                    first_break_at: i,
+                    message: `prev_hash mismatch at seq ${i}: expected ${JSON.stringify(prevChainHash)}, got ${JSON.stringify(entry.prev_hash)}`,
+                };
+            }
+            const payloadHash = computePayloadHash(entry.payload);
+            const expectedChainHash = computeChainHash(i, prevChainHash, payloadHash, entry.timestamp);
+            if (entry.chain_hash !== expectedChainHash) {
+                return {
+                    valid: false,
+                    total_entries: rawLines.length,
+                    first_break_at: i,
+                    message: `chain_hash mismatch at seq ${i}: expected ${JSON.stringify(expectedChainHash)}, got ${JSON.stringify(entry.chain_hash)}`,
+                };
+            }
+            prevChainHash = entry.chain_hash;
+        }
+        return {
+            valid: true,
+            total_entries: rawLines.length,
+            first_break_at: null,
+            message: `Chain valid — ${rawLines.length} entries verified.`,
+        };
+    }
+    /**
+     * Read entries from the ledger with optional filtering.
+     *
+     * @param entryType - If set, only return entries of this type.
+     * @param since - If set, only return entries with timestamp >= this ISO string.
+     * @param limit - Maximum number of entries to return.
+     * @returns Array of entry dicts in chronological order.
+     */
+    readEntries(entryType, since, limit) {
+        if (!existsSync(this.ledgerPath)) {
+            return [];
+        }
+        const results = [];
+        for (const raw of this.readRawLines()) {
+            if (!raw)
+                continue;
+            const entry = JSON.parse(raw);
+            if (entryType !== undefined && entry.entry_type !== entryType) {
+                continue;
+            }
+            if (since !== undefined && entry.timestamp < since) {
+                continue;
+            }
+            results.push(entry);
+            if (limit !== undefined && results.length >= limit) {
+                break;
+            }
+        }
+        return results;
+    }
+    /**
+     * Return the most recent ledger entry, or null if empty.
+     */
+    getLatest() {
+        if (!existsSync(this.ledgerPath)) {
+            return null;
+        }
+        const rawLines = this.readRawLines();
+        if (rawLines.length === 0) {
+            return null;
+        }
+        return JSON.parse(rawLines[rawLines.length - 1]);
+    }
+    /**
+     * Return aggregate statistics about the ledger chain.
+     *
+     * Matches Python's get_chain_stats() return structure exactly.
+     */
+    getChainStats() {
+        if (!existsSync(this.ledgerPath)) {
+            return {
+                entry_count: 0,
+                first_timestamp: null,
+                last_timestamp: null,
+                chain_valid: true,
+                by_type: {},
+                shareable_chain_hash: null,
+            };
+        }
+        const rawLines = this.readRawLines();
+        if (rawLines.length === 0) {
+            return {
+                entry_count: 0,
+                first_timestamp: null,
+                last_timestamp: null,
+                chain_valid: true,
+                by_type: {},
+                shareable_chain_hash: null,
+            };
+        }
+        const first = JSON.parse(rawLines[0]);
+        const last = JSON.parse(rawLines[rawLines.length - 1]);
+        const byType = {};
+        for (const raw of rawLines) {
+            const e = JSON.parse(raw);
+            const t = e.entry_type ?? 'unknown';
+            byType[t] = (byType[t] ?? 0) + 1;
+        }
+        const verifyResult = this.verifyChain();
+        return {
+            entry_count: rawLines.length,
+            first_timestamp: first.timestamp ?? null,
+            last_timestamp: last.timestamp ?? null,
+            chain_valid: verifyResult.valid,
+            by_type: byType,
+            shareable_chain_hash: last.chain_hash ?? null,
+        };
+    }
+    // ------------------------------------------------------------------
+    // Internal helpers
+    // ------------------------------------------------------------------
+    /**
+     * Write a new entry.
+     *
+     * Advisory file locking via .ledger.lock is used for cross-process safety.
+     * Node.js is single-threaded so within one process this is sequential.
+     */
+    appendLocked(entryType, payload, repoPath, providedSignature) {
+        // Acquire advisory lock (best-effort)
+        const lockAcquired = this.acquireLock();
+        try {
+            const latest = this.getLatest();
+            const seq = latest !== null ? latest.seq + 1 : 0;
+            const prevHash = latest !== null ? latest.chain_hash : GENESIS_SENTINEL;
+            const timestamp = new Date().toISOString();
+            const payloadHash = computePayloadHash(payload);
+            const chainHash = computeChainHash(seq, prevHash, payloadHash, timestamp);
+            // Compute git binding if repo path provided
+            const sourceTreeHash = repoPath !== null ? computeSourceTreeHash(repoPath) : null;
+            // Build entry without signature first (for signing)
+            const entry = {
+                schema_version: SCHEMA_VERSION,
+                seq,
+                timestamp,
+                entry_type: entryType,
+                payload,
+                payload_hash: payloadHash,
+                prev_hash: prevHash,
+                chain_hash: chainHash,
+                source_tree_hash: sourceTreeHash,
+                signature: null,
+            };
+            // Sign if keys available and no pre-computed signature provided
+            let finalSignature = providedSignature;
+            if (finalSignature === null && this.keyManager !== null) {
+                try {
+                    finalSignature = this.keyManager.signEntry(entry);
+                }
+                catch {
+                    // Keys unavailable — proceed unsigned
+                    finalSignature = null;
+                }
+            }
+            entry.signature = finalSignature;
+            // Serialize: matches Python's json.dumps(entry, ensure_ascii=False, sort_keys=True)
+            // Python sorts keys alphabetically, so: chain_hash, entry_type, payload,
+            // payload_hash, prev_hash, schema_version, seq, signature, source_tree_hash, timestamp
+            const line = pythonJsonDumps(entry);
+            appendFileSync(this.ledgerPath, line + '\n', 'utf8');
+            return entry;
+        }
+        finally {
+            if (lockAcquired) {
+                this.releaseLock();
+            }
+        }
+    }
+    /** Read all non-empty lines from the ledger file. */
+    readRawLines() {
+        const content = readFileSync(this.ledgerPath, 'utf8');
+        return content.split('\n').map(l => l.trim()).filter(l => l.length > 0);
+    }
+    /**
+     * Acquire advisory lock by creating .ledger.lock.
+     * Returns true if lock was created (should be released), false if lock
+     * already existed (proceeding anyway — this is advisory only).
+     */
+    acquireLock() {
+        try {
+            writeFileSync(this.lockPath, String(process.pid), { flag: 'wx' });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    releaseLock() {
+        try {
+            unlinkSync(this.lockPath);
+        }
+        catch {
+            // Ignore errors on lock release
+        }
+    }
+}
+//# sourceMappingURL=ledger.js.map

package/dist/trust/ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../../src/trust/ledger.ts"],"names":[],"mappings":"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"}

package/dist/trust/signing.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Ed25519 key management for Trust Ledger entry signing.
+ *
+ * Binary-compatible with the Python signing.py implementation.
+ *
+ * Key files:
+ *   .forgeos/keys/private.pem  (mode 0o600 — owner read/write only)
+ *   .forgeos/keys/public.pem   (world-readable)
+ *
+ * Key format: PKCS8 PEM for private, SPKI PEM for public — matching
+ * Python's serialization.PrivateFormat.PKCS8 and
+ * serialization.PublicFormat.SubjectPublicKeyInfo.
+ *
+ * Fingerprint: first 16 hex chars of SHA-256(raw_32_byte_public_key).
+ * This matches Python's get_fingerprint() which calls:
+ *   public_key.public_bytes(Encoding.Raw, PublicFormat.Raw) → 32 bytes
+ *   SHA-256(raw_bytes).hexdigest()[:16]
+ *
+ * Signatures: Ed25519 raw signatures, base64-encoded (standard alphabet),
+ * produced over the canonical UTF-8 bytes of the entry dict. This matches
+ * Python's base64.b64encode(raw_sig).decode("ascii").
+ *
+ * Security invariants (matching Python):
+ *   - load_private_key raises if file mode is broader than 0o600
+ *   - Key rotation archives old_public.pem before overwriting
+ */
+import { type KeyObject } from 'crypto';
+export declare class SigningError extends Error {
+    constructor(message: string);
+}
+export declare class KeyNotFoundError extends SigningError {
+    constructor(message: string);
+}
+export declare class KeyPermissionError extends SigningError {
+    constructor(message: string);
+}
+/**
+ * Manages Ed25519 keypairs for a ForgeOS project.
+ *
+ * All key files are stored under {projectPath}/.forgeos/keys/.
+ *
+ * Example:
+ *   const km = new KeyManager('/my/project');
+ *   km.generateKeypair();
+ *   const sig = km.signEntry({ seq: 0, ... });
+ *   const ok = km.verifySignature({ seq: 0, ... }, sig);
+ */
+export declare class KeyManager {
+    private keysDir;
+    constructor(projectPath: string);
+    get privateKeyPath(): string;
+    get publicKeyPath(): string;
+    /**
+     * Generate a new Ed25519 keypair and persist it to disk.
+     *
+     * Creates the key directory (mode 0o700) if it does not exist.
+     * Overwrites any existing keypair — rotate deliberately via rotateKey().
+     *
+     * @returns The key fingerprint (first 16 hex chars of SHA-256 of raw public key bytes).
+     */
+    generateKeypair(): string;
+    /**
+     * Rotate the keypair, returning [oldFingerprint, newFingerprint].
+     *
+     * The old public key is preserved at old_public.pem during the transition
+     * so callers can construct a capability_declared ledger entry referencing
+     * both keys. After the transition entry is written, the caller may delete
+     * old_public.pem.
+     *
+     * @returns Tuple of [oldFingerprint, newFingerprint].
+     * @throws KeyNotFoundError if no existing keypair is found.
+     */
+    rotateKey(): [string, string];
+    /**
+     * Load the private key from disk, enforcing strict file permissions.
+     *
+     * @throws KeyNotFoundError if the private key file does not exist.
+     * @throws KeyPermissionError if the file mode is broader than 0o600.
+     */
+    loadPrivateKey(): KeyObject;
+    /**
+     * Load the public key from disk.
+     *
+     * @throws KeyNotFoundError if the public key file does not exist.
+     */
+    loadPublicKey(): KeyObject;
+    /**
+     * Return the raw 32-byte Ed25519 public key material.
+     *
+     * This replicates Python's:
+     *   public_key.public_bytes(Encoding.Raw, PublicFormat.Raw)
+     * which returns the 32-byte raw Ed25519 public key (not PEM, not DER SPKI).
+     */
+    getPublicKeyBytes(): Buffer;
+    /**
+     * Return the key fingerprint as 16 hex characters.
+     *
+     * Fingerprint = first 16 hex chars of SHA-256(raw_public_key_bytes).
+     *
+     * This matches Python's:
+     *   raw_bytes = public_key.public_bytes(Encoding.Raw, PublicFormat.Raw)
+     *   digest = hashlib.sha256(raw_bytes).hexdigest()
+     *   return digest[:16]
+     */
+    getFingerprint(): string;
+    /**
+     * Sign an entry dict with the project's private key.
+     *
+     * The entry is serialized to canonical JSON (sorted keys, UTF-8) before
+     * signing, matching Python's:
+     *   entry_bytes = json.dumps(entry, sort_keys=True, ensure_ascii=False).encode("utf-8")
+     *   raw_sig = private_key.sign(entry_bytes)
+     *   return base64.b64encode(raw_sig).decode("ascii")
+     *
+     * @param entry - The entry dict to sign (before signature field is set).
+     * @returns Base64-encoded (standard alphabet) signature string.
+     */
+    signEntry(entry: Record<string, unknown>): string;
+    /**
+     * Verify an Ed25519 signature against an entry dict.
+     *
+     * Returns false on any verification failure — never throws.
+     *
+     * Matches Python's verify_signature which catches all exceptions and
+     * returns False rather than propagating.
+     *
+     * @param entry - The entry dict that was signed.
+     * @param signature - Base64-encoded signature string.
+     * @returns true if the signature is valid, false otherwise.
+     */
+    verifySignature(entry: Record<string, unknown>, signature: string): boolean;
+    private assertPrivateKeyPermissions;
+}
+//# sourceMappingURL=signing.d.ts.map

package/dist/trust/signing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signing.d.ts","sourceRoot":"","sources":["../../src/trust/signing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,QAAQ,CAAC;AAmBhB,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,gBAAiB,SAAQ,YAAY;gBACpC,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,kBAAmB,SAAQ,YAAY;gBACtC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;GAUG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,OAAO,CAAS;gBAEZ,WAAW,EAAE,MAAM;IAI/B,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED,IAAI,aAAa,IAAI,MAAM,CAE1B;IAMD;;;;;;;OAOG;IACH,eAAe,IAAI,MAAM;IAezB;;;;;;;;;;OAUG;IACH,SAAS,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC;IAqB7B;;;;;OAKG;IACH,cAAc,IAAI,SAAS;IAa3B;;;;OAIG;IACH,aAAa,IAAI,SAAS;IAW1B;;;;;;OAMG;IACH,iBAAiB,IAAI,MAAM;IAS3B;;;;;;;;;OASG;IACH,cAAc,IAAI,MAAM;IAUxB;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM;IAcjD;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAkB3E,OAAO,CAAC,2BAA2B;CAWpC"}