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

Every commit is hashed client-side by the SDK. The integrity_hash is SHA-256 of the canonical commit envelope, which binds agent_id, key_id, timestamp, payload_hash, and parent_integrity_hash. The agent signs this envelope with their Ed25519 key. 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 immutable. 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, use self-hosting (MIT license) or BYOK encryption.

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 with BYOK is the correct choice when you need third-party independence.

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:

darkmatter_proof_bundle.json
├── chain_records.json      # all commit records with hashes
├── integrity_map.json      # SHA-256 chain for each step
└── verifier.py             # standalone Python verifier, no dependencies

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 canonical({schema_version, agent_id, key_id, timestamp, payload_hash, parent_integrity_hash})
  "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.