/** * Cryptographic audit-trail verification. Prevention of tampering is * best-effort (doc-level guards); detection is this module: recompute the * whole hash chain from the persisted entries and compare against the stored * chain head. */ import * as core from './core/index.js'; import { JournalEntry } from './skr.classes.journalentry.js'; import { getSequenceState } from './skr.sequence.js'; import { buildHashPayload } from './skr.posting.js'; import type { TSKRType } from './skr.types.js'; export interface IChainVerificationResult { valid: boolean; entriesChecked: number; issues: string[]; headHash: string | null; } /** The persisted fields of one journal entry the chain verification reads. */ export interface IChainedEntryDocument extends Omit[0], 'sequenceNumber' | 'postedAt'> { sequenceNumber?: number | null; prevHash?: string | null; entryHash?: string | null; postedAt?: Date | null; } /** * Checks one chain from the documents alone: `docs` are the schemaVersion-2 * entries of (skrType, fiscalYear) sorted by sequence number, `state` the * stored counter and head. Gaplessness, every entry hash, every link and the * head are compared; nothing is read or written. */ export function verifyChainDocuments( skrType: TSKRType, fiscalYear: number, docs: readonly IChainedEntryDocument[], state: { value: number; headHash: string } | null, ): IChainVerificationResult { const issues: string[] = []; if (docs.length === 0) { return { valid: !state || state.value === 0, entriesChecked: 0, issues: state && state.value !== 0 ? [`sequence counter is ${state.value} but no entries exist`] : [], headHash: state?.headHash ?? null, }; } // gaplessness docs.forEach((doc, index) => { const expected = index + 1; if (doc.sequenceNumber !== expected) { issues.push(`sequence gap: expected ${expected}, found ${doc.sequenceNumber}`); } }); // chain const genesis = core.genesisHash(skrType, fiscalYear); const chain = docs.map((doc) => ({ sequenceNumber: doc.sequenceNumber as number, prevHash: doc.prevHash as string, entryHash: doc.entryHash as string, payload: buildHashPayload({ sequenceNumber: doc.sequenceNumber as number, skrType: doc.skrType, fiscalYear: doc.fiscalYear, date: doc.date, postedAt: doc.postedAt as Date, description: doc.description, reference: doc.reference, taxScenario: doc.taxScenario, currency: doc.currency, reversalOf: doc.reversalOf, lines: doc.lines ?? [], }), })); const failure = core.verifyChain(chain, genesis); if (failure) { issues.push(failure.reason); } // head comparison const lastHash = chain[chain.length - 1].entryHash; if (!state) { issues.push('no sequence state document found'); } else { if (state.headHash !== lastHash) { issues.push(`stored chain head ${state.headHash} !== last entry hash ${lastHash}`); } if (state.value !== docs.length) { issues.push(`sequence counter ${state.value} !== entry count ${docs.length}`); } } return { valid: issues.length === 0, entriesChecked: docs.length, issues, headHash: state?.headHash ?? null, }; } /** * Walk sequence 1..N for (skrType, fiscalYear): check gaplessness, recompute * every entry hash from the persisted payload, verify the chain links, and * compare the final hash against the stored chain head. */ export async function verifyHashChain( skrType: TSKRType, fiscalYear: number, ): Promise { const cursor = await JournalEntry.getCursor( { skrType, fiscalYear, schemaVersion: 2 }, { sort: { sequenceNumber: 1 } }, ); const docs = await cursor.toArray(); const state = await getSequenceState(skrType, fiscalYear); return verifyChainDocuments(skrType, fiscalYear, docs, state); }