Security
Threat model and offline verification
The same three questions apply here: who made the decision, what happened, and can the record be trusted. This page explains the adversarial model behind that claim, what DarkMatter protects against, what it doesn't, and how to verify records without depending on our infrastructure.
What DarkMatter is designed to prevent
Retroactive modification of execution records
Commits made through any of the SDKs are hashed on your machine before transmission. The integrity_hash binds each record to the one before it: it is SHA-256 of the record’s own payload_hash joined to its parent’s integrity_hash, both carrying the sha256: prefix, with the literal root standing in for the parent of the first record. At L3 the agent also signs a commit envelope with an Ed25519 key only they hold; below L3 there is no signature, only the chain. Any change to any field breaks the chain from that point forward. The next dm.verify() call will flag the break and identify the step. This protects against: developers editing records after the fact, database administrators modifying rows, and accidental data corruption.
Disputed claims about what your system did
Because records are stored outside your system with cryptographic proof, DarkMatter provides an independent record that neither you nor your engineers control. An auditor, customer, or regulator can verify what happened without trusting your reporting. This is the primary use case for regulated industries.
Loss of execution history when a run is deleted or overwritten
Committed records are tamper-evident: altering one breaks verification for it and every record after it, so an overwrite cannot pass unnoticed. It is evidence of change, not prevention of it. You can export a proof bundle at any time. The bundle is self-contained and verifiable offline with no ongoing DarkMatter dependency.
What DarkMatter does not protect against
Malicious data committed before recording begins
DarkMatter records what you commit. If an agent produces a manipulated output and you commit that output, DarkMatter will faithfully record the manipulated output. The chain integrity is preserved, but the content integrity depends on what you chose to commit. DarkMatter does not validate payload content.
DarkMatter infrastructure compromise
If DarkMatter's own infrastructure were compromised, records could theoretically be modified at the storage layer before hashing. Mitigation: export proof bundles regularly and store them independently. The offline verifier uses the hashes in the bundle, if DarkMatter servers were compromised after export, your local bundle still proves what was recorded at export time. For highest assurance, encrypt payloads before you commit them, so that a compromise of our storage exposes ciphertext, and keep your own exports.
Self-hosted deployments
When you self-host DarkMatter, you control the infrastructure. This removes the "independent execution record" guarantee, because you could modify the database directly. Self-hosting is appropriate for privacy and data sovereignty requirements. The cloud product is the correct choice when you need third-party independence, because the record is then held by someone other than the party being asked about.
What happens if DarkMatter goes down?
Your committed records are safe and verifiable regardless of DarkMatter's operational status, provided you have exported a proof bundle. The bundle contains everything needed to verify integrity:
bundle.json
├── _spec # verifier url, the exact command, what it does not check
├── metadata # ctx_id, chain length, when and by whom it was exported
├── integrity # chain_intact, root and tip hashes, timestamp range
├── commits[] # every record with its payload, hashes and inclusion proof
├── checkpoint # the signed log root covering this chain, with witness state
├── server_pubkey # the Ed25519 key the checkpoint is signed with
└── export_hash # hash of the bundle itself
The checkpoint is DarkMatter’s signature over the log root at the moment of export, and server_pubkey is the key to check it with. It also carries witness_count and witness_signatures. Every witness registered today is operated by DarkMatter, so a co-signature is not yet corroboration by anyone else; what the checkpoint gives you is a signed statement you hold a copy of, which is what a later change would have to contradict.
Run verification with no internet connection, no DarkMatter account:
python verify_darkmatter_chain.py bundle.json
# → Verifying chain: 8 steps
# → Step 1: ctx_1775... ✓ valid
# → Step 2: ctx_1776... ✓ valid
# → Step 3: ctx_1777... ✓ valid [fork point]
# → Step 4: ctx_1778... ✓ valid
# → Chain intact. Root: ctx_1775... Tip: ctx_1778...
The verifier checks: (1) each commit's payload_hash matches SHA-256 of the stored payload, (2) each commit's integrity_hash matches SHA-256 of payload_hash + parent_hash, (3) parent-child links are intact across the full chain.
Export proof bundles regularly if you have compliance requirements. We recommend exporting at the end of each significant pipeline run. Bundles can also be exported via the dashboard or with dm.bundle(ctx_id).
Verification format specification
The chain format is documented so you can build your own verifier:
// Each commit record:
{
"id": "ctx_1775...",
"payload_hash": "sha256:3c3654...", // SHA-256 of canonical(payload), Integrity Spec v1.0
"parent_hash": "sha256:dec459...", // integrity_hash of parent commit (null for root)
"integrity_hash": "sha256:a7b2c4...", // SHA-256 of the two prefixed hashes joined: payload_hash + parent_hash, with the literal "root" in place of parent_hash at the root
"created_at": "2026-04-03T...",
"payload": {...}
}
To verify a single commit: SHA-256(canonical(commit_envelope)) === integrity_hash, full spec
To verify the chain: each commit's parent_hash must equal the previous commit's integrity_hash.
The format follows the Context Passport open standard (CC0). Any compatible verifier will work.
Reporting security issues
Email [email protected] with a description and reproduction steps. We acknowledge within 24 hours and patch critical issues within 72 hours.