/** * Canonical serialization + SHA-256 chaining for the GoBD audit trail. * Pure functions — the persistence layer decides what goes into the chain; * this module guarantees the representation is stable across releases. */ import * as plugins from './core.plugins.js'; /** * Deterministic string form of a value: object keys sorted recursively, * Dates as ISO strings, undefined properties omitted, array order preserved. * Non-integer numbers are rejected — monetary values must be integer cents. */ export function canonicalize(value: unknown): string { return JSON.stringify(sortValue(value)); } function sortValue(value: unknown): unknown { if (value === null || value === undefined) return value ?? null; if (value instanceof Date) return value.toISOString(); if (Array.isArray(value)) return value.map((entry) => sortValue(entry)); if (typeof value === 'number') { if (!Number.isFinite(value)) throw new Error(`Cannot canonicalize non-finite number ${value}`); if (!Number.isInteger(value)) { throw new Error( `Cannot canonicalize non-integer number ${value} — monetary values must be integer cents`, ); } return value; } if (typeof value === 'object') { const sorted: Record = {}; for (const key of Object.keys(value as Record).sort()) { const entry = (value as Record)[key]; if (entry !== undefined) sorted[key] = sortValue(entry); } return sorted; } return value; } /** * Hash of one chain entry: SHA-256 over predecessor hash + canonical payload. */ export function entryHash(prevHash: string, payload: unknown): string { return plugins.sha256FromStringSync(`${prevHash}\n${canonicalize(payload)}`); } /** * Chain genesis per ledger scope (one chain per skrType + fiscal year). */ export function genesisHash(skrType: string, fiscalYear: number): string { return plugins.sha256FromStringSync(`GENESIS:${skrType}:${fiscalYear}`); } /** * Walk a sequence of already-canonicalized entries and verify the chain. * Returns the first mismatch or null when intact. */ export function verifyChain( entries: Array<{ sequenceNumber: number; prevHash: string; entryHash: string; payload: unknown }>, genesis: string, ): { index: number; reason: string } | null { let expectedPrev = genesis; for (let index = 0; index < entries.length; index++) { const entry = entries[index]; if (entry.prevHash !== expectedPrev) { return { index, reason: `prevHash mismatch at sequence ${entry.sequenceNumber}` }; } const recomputed = entryHash(entry.prevHash, entry.payload); if (recomputed !== entry.entryHash) { return { index, reason: `entryHash mismatch at sequence ${entry.sequenceNumber}` }; } expectedPrev = entry.entryHash; } return null; }