JjX4NUdZddlmZddlZddlZddlZddlZddlmZddl m Z ddl m Z m Z dZded <d Zd d ZeZd ed <ehdZded<Gddee ZedGddZd!dZd"dZd#dZd$dZd%dZd&dZ d'dZd(dZgdZ y))uHash-chain primitives for the audit log — pure, stdlib-only, side-effect-free. The chain links every audit record to its predecessor by digest, so an in-place edit, a deletion, a reordering, or a truncation of the *beginning* severs the sequence at a point a verifier can localise. This module builds the links and verifies them; it never touches storage. **What a keyless chain does NOT do — read before claiming anything about it.** The digest is plain SHA-256 with no secret. Anyone who can read this file can recompute every link, so an adversary holding write access to the database can rewrite the log end-to-end and present a chain that verifies perfectly. The same applies to deleting the *end* of the chain: the remaining records are a shorter but perfectly valid chain. This chain is **tamper-evident, not tamper-proof**. It detects corruption and naive editing; it does not detect a determined attacker who recomputes. Closing that gap needs a keyed integrity mechanism or an external anchor the writer cannot rewrite — deliberately out of scope here, and recorded as an open item in the plan's F6 section. These functions are intentionally free of any dependency on :class:`AuditLog`, so that verification never inherits a bug from the code that wrote the chain. ) annotationsN) dataclass)Enum)AnyFinal@0000000000000000000000000000000000000000000000000000000000000000z Final[str]GENESISCYBERBRAIN_CHAIN_KEYctjjt}|st td|j dS)uHNačte HMAC klíč z env proměnné; selže, pokud chybí (fail-closed).zW environment variable is not set. Refusing to start with a predictable audit-chain key.utf-8)osenvironget_CHAIN_KEY_ENV RuntimeErrorencode)keys M/home/oem/CyberBrain26-unified/src/cyberbrain26/security_plane/audit/chain.py_load_chain_keyr(sG **.. (C D D   ::g z Final[bytes] CHAIN_KEY>seq prev_hash entry_hashzFinal[frozenset[str]] _CHAIN_FIELDSc(eZdZdZdZdZdZdZdZdZ y) TamperClassaHow a broken link most likely arose. Kept separate from "invalid" because the distinction is what makes a report actionable: a deletion and an edit are different incidents with different causes, and collapsing them into one boolean hides which one happened. none in_place_editdeletion reorderingprefix_truncation missing_linkN) __name__ __module__ __qualname____doc__NONE IN_PLACE_EDITDELETION REORDERINGPREFIX_TRUNCATION MISSING_LINKrrrr<s( D#MHJ+!LrrT)frozenceZdZUdZded<ded<ded<ded<ded <d Zd ed <ejZd ed<dZ ded<dZ ded<y )VerificationReportahResult of walking a chain. Frozen: the verdict is itself evidence. ``linkage_ok`` and ``integrity_ok`` are reported separately and must stay so. A chain can link perfectly while a single field inside one record was edited (``linkage_ok=True``, ``integrity_ok=False``); collapsing them into one boolean hides exactly which attack occurred. boolintact linkage_ok integrity_okintrecords_checkedstrheadNz int | Nonefirst_broken_seqr tamper_classdetailFunverified_premise) r$r%r&r'__annotations__r:rr(r;r=r>r.rrr1r1LsW L I#'j' + 0 0L+0FC %$rr1cbt|tr|St|tr|jr t |St|t r-|j Dcic]\}}|t|c}}St|tr|Dcgc] }t|c}S|Scc}}wcc}w)a Canonicalise a value so hashing survives a storage round-trip. SQLite is typed and does not preserve the distinction between an integer and an integral float: ``latency_ms = 5.0`` can read back as ``5``. Hashing the raw value would therefore produce a false mismatch on an untouched record. Collapsing integral floats to ``int`` on both the write and the verify side makes the two agree regardless of how the value was stored. ``bool`` is a subclass of ``int`` and must be excluded, or ``True`` would become ``1``. ) isinstancer2float is_integerr6dictitems _normaliselist)valuekvs rrFrFes% %E$4$4$65z%-2[[];TQ:a= ;;%',-! 1 -- L<-s !B&B,c|jDcic]\}}|tvs|t|}}}tj|dddt j dScc}}w)uDeterministic serialisation of a record, for hashing. Sorted keys and fixed separators make key order and whitespace irrelevant, so a verifier can reproduce this from the persisted row alone. The hashed set is the whole record minus the chain columns — see :data:`_CHAIN_FIELDS`. Float formatting is a known fragility: a library upgrade that changes how a float renders would make every record fail re-verification even though nothing was tampered with. :func:`_normalise` removes the common case and ``tests/test_audit_chain.py`` pins the behaviour with a golden vector so a change cannot pass unnoticed. T),:F) sort_keys separators ensure_asciidefaultr )rErrFjsondumpsr8r)recordrIrJpayloads rcanonical_event_bytesrVzs]-3LLNUDAqa}>Tq*Q-UGU ::4JUTW  fWoVs A#A#cptj||jdzj}|S)aReturn the hex digest binding ``canonical`` to ``prev_hash``. Deliberately ordered ``canonical || prev_hash``: the predecessor digest is the last thing folded in, which is what makes the link commit transitively to the entire prefix of the chain. ascii)hashlibsha256r hexdigest) canonicalrdigests r compute_linkr^s0^^I (8(8(AA B L L NF Mrc,tt||S)zCConvenience wrapper: canonicalise ``record`` then compute its link.)r^rV)rTrs rlink_for_recordr`s -f5y AArct|}tjt||j dzt j j}|S)aReturn the HMAC-SHA256 digest binding ``event`` to ``previous_hash``. Uses HMAC rather than plain SHA-256 so that an attacker who can read the code but not the key cannot forge a valid chain. The key is embedded in this module; a production deployment would replace it with a secret from a key management system. The digest is computed over the canonical event bytes followed by the previous hash, creating a keyed link that is part of the hash-chain but protected by the secret key. rX)rVhmacnewrrrYrZr[)event previous_hashr\r]s rcompute_event_hashrfsL&e,I XXM((11ik  Mrc |stddddtdS|djd}|djdstddddtdd|d  St}d }t|D]\}}|jd}|&tddd||tj d |d cS|2||dzk7r*tddd|||t ||||d|dzd|cS|}|jd}|jd}||k7r$tddd|||t|||d|dcSt||} || k7r*tddd|dz||tjd|dcS| }tdddt||S)uWalk ``records`` from genesis and report integrity, stopping at the first break. ``records`` must be ordered by ``seq`` ascending. Verification stops at the first break deliberately: once the chain diverges, every later record inherits an untrustworthy predecessor, so any mismatch after it is a consequence rather than an independent fact. Reporting only the first gives one defensible statement about where history diverged. Two invariants are checked separately at every step: * **integrity** — the record's stored digest equals the digest recomputed from its own stored fields. Catches an edit to any hashed field. * **linkage** — the record's stored ``prev_hash`` equals the running digest. Catches a deletion, a reorder, or an inserted record. A log whose first record carries no digest is reported as ``unverified_premise=True`` and ``intact=False``. Treating "never chained" as a pass is the failure mode where a green result proves nothing. Trz empty log)r3r4r5r7r9r=rrFz/log is not hash-chained: the first record (seq=z) has no entry_hash. Rows written before the chain existed are not covered by it, so this is a declared boundary, not a clean verification)r3r4r5r7r9r>r=Nzrecord z) has no seq, so its position is undefined)r3r4r5r7r9r;r=zseq gap: expected z, found )r3r4r5r7r9r:r;r=rzlink break at seq zF: prev_hash does not match the digest produced by the preceding recordzintegrity break at seq zV: stored entry_hash does not match the digest recomputed from this record's own fields)r3r4r5r7r9) r1r r enumeraterr- _classify_gap_classify_breakrfr)len) records first_seqrunning previous_seqindexrTr stored_prev stored_own recomputeds r verify_chainrus$( !    u%I 1:>>, '!#A)MOO  G#L"7+? vjj ;% " %(55 'PQ   #|a/?(?% " %!$*7E7LQ+L1,<+=XcUK   jj- ZZ - ' !% " %!$,WeWE(.77  (8  #%" % !$(66-cU3FF  ?B G   rc||dDchc]}|jd}}|dk(rtjS||jd|vr||vrtjStjScc}w)zKDecide whether a sequence gap means a deletion, a reorder, or a truncation.Nrrr)rrr,r*r+)rmrqrorprlaters rrjrj-sv+2%&/ :QQUU< :E : z,,,u~+&e3u8L###  ! !! ;sA1c|dk(rtjS|Dchc]}|jdc}thz}||jd}||vrtjS||k7rtj Stj Scc}w)z6Classify a linkage break using the pointers around it.rrr)rr,rr r*r+r))rmrqrorwproducedpointers rrkrk>s z,,,-45l#5 AHen  -Gh###'%%%  $ $$ 6sB ) rr rr1rVrfr^r`ru)returnbytes)rHrr|r)rTdict[str, Any]r|r})r\r}rr8r|r8)rTr~rr8r|r8)rdr~rer8r|r8)rmlist[dict[str, Any]]r|r1) rmrrqr6ror8rpr6r|r)rmrrqr6ror8r|r)!r' __future__rrYrbrRr dataclassesrenumrtypingrrr r?rrr frozensetrr8rr1rFrVr^r`rfrurjrk__all__r.rrrs,# !'*+ <+ (11S'T $T "#t "  $%%%0*&B *xv" !" "" "  "" % r