The Architecture of Provenance: What It Is, How It Works, and What It Proves

Why trust needs an anchor

Wuh gine on, world! Anaiya here. 👋🏾

Over the last several dispatches, we shared real-world data from our lab: how signed instructions change agent decision boundaries, how we ran clean-room diagnostic evaluations against the OWASP agent security guidance, and how we caught hardcoded placeholder badges that declared systems sealed when nothing had verified them.

Behind all those experiments lies a foundational discipline that is often misunderstood or reduced to a buzzword: cryptographic provenance.

In modern computing, we are flooded with synthetic text, autonomous agent edits, multi-branch pipelines, and rapidly shifting context windows. When an autonomous model or a human reviewer looks at a file, an instruction, or an API payload, they face an urgent question:

How do you know what you are reading is authentic, who actually created it, what authority they had, and whether a single byte changed along the way?

This guide breaks down what cryptographic provenance is, how our local-first implementation operates under the hood, what it can and cannot tell you, and the practical questions engineering teams ask when implementing it.

1. What is cryptographic provenance?

At its core, provenance is the documented history of an artifact: its origin, custody, transformations, and verification states over time.

In analog art, provenance is the chain of gallery records, auction bills, and estate catalogs establishing that a canvas was truly painted by the master rather than a skilled forger.

In digital systems and agentic AI, cryptographic provenance replaces subjective trust and paper trails with mathematical guarantees. Instead of trusting a database row, an unverified timestamp header, or a green UI badge, cryptographic provenance binds an artifact directly to:

1. Deterministic Content Identity (SHA-256): Proving the file has not drifted by even a single whitespace character.
2. Cryptographic Authorship (Ed25519 / OpenPGP): Proving exactly which private key signed the statement.
3. Explicit Scope and Purpose: Defining precisely what resource, operation, or environment the signature applies to.
4. Independent Temporal Anchoring (RFC 3161): Proving that the artifact existed in that exact state at a verifiable atomic time.
5. Decoupled Verification Sidecars: Storing the cryptographic proofs alongside the file without modifying or polluting the canonical source bytes.

2. The core distinctions: what provenance actually separates

One of the greatest hazards in software architecture is conflating distinct operational concepts into a single vague idea of “verified.”

Our open-source engine, hosted at github.com/MoongladeAI/provenance (standalone release pending), enforces five clean distinctions:

A. Observation is not authorship

Anyone can calculate the SHA-256 digest of a file. Recording that digest proves that you saw the file in a specific state. It does not prove that you authored it, that you approved it, or that you have authority over its contents. Provenance keeps content digests and identity attestations strictly separated.

B. A hash is not a signature

A hash provides integrity; it answers whether the bytes changed. A digital signature provides non-repudiation; it answers who signed the claim. An artifact can have pristine hash integrity while being completely unsigned or originating from an adversarial actor.

C. A signature is not human authorization

In modern multi-agent systems, agents sign artifacts autonomously to establish pipeline custody. But an autonomous agent’s signature does not equal a human founder’s or executive’s sign-off. Provenance formats must explicitly distinguish unattended agent credentials from interactive human authorization tokens.

D. A valid signature is not factual truth

If an authorized author signs a document that contains an error, the cryptographic signature will verify with mathematical perfection. Cryptography proves that the author wrote those exact words; it does not turn false claims into physical facts. Provenance protects integrity and attribution, leaving external claim adjudication to empirical evidence.

E. A valid artifact can still be out of scope

A digital signature that authorizes an agent to read documentation in directory A does not authorize it to wipe database tables in directory B. Provenance envelopes bind signatures to an expected resource scope, preventing cross-boundary permission escalation.

3. How it works under the hood

Our architecture is built on a local-first, zero-dependency engine designed to operate across developer workstations, git repositories, and edge deployments without external cloud dependencies.

┌────────────────────────┐      Canonicalize       ┌────────────────────────┐
│ Canonical Markdown Doc │ ──────────────────────> │ UTF-8 NFC + LF Normal  │
└────────────────────────┘                         └────────────────────────┘
            │                                                  │
            │ (bytes unchanged)                                ▼
            │                                      ┌────────────────────────┐
            │                                      │   SHA-256 Hash Digest  │
            │                                      └────────────────────────┘
            │                                                  │
            ▼                                                  ▼
┌────────────────────────┐   OpenPGP / Ed25519     ┌────────────────────────┐
│ <file>.provenance.json │ <────────────────────── │ Structured Claim Bundle│
│   (Detached Sidecar)   │                         └────────────────────────┘
└────────────────────────┘                                     │
            │                                                  ▼
            │ RFC 3161 DTA Engine                  ┌────────────────────────┐
            └────────────────────────────────────> │  4-Tier Temporal Proof │
                                                   └────────────────────────┘

Here is the exact lifecycle an artifact traverses:

Stage 1: Cross-Platform Canonicalization

A signature made on macOS or Linux will fail on Windows if line endings switch from LF to CRLF. Similarly, different operating systems normalize Unicode accents differently. Before any cryptographic math occurs, the engine normalizes CRLF to LF and applies Unicode Normalization Form C (NFC). This ensures that standard git checkouts do not invalidate signatures.

Stage 2: Structured Claim Signing

The engine does not sign raw, disconnected bytes. It signs a structured claim envelope that includes:

• The protocol specification version (moonglade:provenance:v1).
• The canonical SHA-256 digest of the artifact.
• The resource scope (for example, moonglade:site:blog/article.md).
• The signer’s verified public identity string and key fingerprint.

This binds the cryptographic signature not just to the file text, but to its intended role in the system.

Stage 3: Detached Sidecar Storage

Rather than injecting metadata headers or binary watermarks that break markdown parsers, the cryptographic proof is saved as an adjacent sidecar file: <filename>.provenance.json. The original markdown file remains 100% clean, standard, and portable.

Stage 4: Degraded Temporal Attestation (DTA)

To prove when a document existed without stalling when remote services fail, the engine uses a 4-tier temporal cascade:

1. Tier 1 (Enterprise WebTrust TSAs): DigiCert, Sectigo, GlobalSign RFC 3161 ASN.1 tokens.
2. Tier 2 (Ecosystem TSAs): Apple TSA, FreeTSA fallbacks.
3. Tier 3 (Edge Network Consensus): Multi-region TLS date consensus across edge providers.
4. Tier 4 (Monotonic Host UTC): Monotonic kernel clock timestamping.

This guarantees that an artifact receives the highest quality timestamp available without blocking developer workflows.

Stage 5: Merkle Tree Rollup & Inclusion Proofs

When hundreds of documents are audited together, the engine constructs an RFC 9162 Merkle tree. All individual file digests roll up into a single Merkle Root Hash. A client can prove that a specific document belongs to a published studio release using an inclusion proof in approximately log2(n) hashes, verifying the entire workspace in milliseconds.

4. What you can tell using provenance

When you inspect an artifact with an active provenance sidecar, you can answer five concrete questions with absolute certainty:

5. What provenance cannot tell you

Clear engineering requires knowing the limits of your tools. Provenance is not magic, and it does not make broad claims about:

• Factual Accuracy: If a document states that the speed of light is 45 miles per hour and the author signs it, provenance verifies that the author signed that statement. It does not verify the laws of physics.
• Model Sincerity: Provenance cannot tell you whether a neural model “believed” its output or generated it with high temperature.
• Malicious Intent with Valid Keys: If an authorized signer’s private key is compromised, a bad actor can produce valid signatures. Key security, passphrases, and offline cold storage remain vital.
• Offline Truth: A signature proves what happened at the moment of sealing. If external real-world circumstances change later, the document reflects the state when sealed, not dynamic future reality.

6. Frequently Asked Questions (FAQ)

Does adding provenance modify my markdown or source files?

No. All cryptographic signatures, hashes, timestamps, and Merkle proofs live in adjacent .provenance.json sidecar files. Your markdown, TypeScript, Python, and JSON files remain untouched.

Why not just use git commit signatures?

Git commit signatures (git commit -S) are valuable, but they operate at the repository snapshot level. They do not travel with individual files when exported, served over HTTP, consumed via APIs, or passed between agents in multi-agent networks. File-level provenance travels with the asset wherever it is published.

How does in-browser verification work without slowing down page loads?

On our blog, the verification check is performed using the browser’s native WebCrypto API. When a page loads, the client fetches the static source markdown and sidecar JSON, hashing the text in WebAssembly or compiled native browser code. The check completes in under two milliseconds and runs asynchronously without blocking rendering.

What happens if a file is edited after it has been signed?

The SHA-256 digest calculated from the modified file will no longer match the digest recorded in the sidecar. The verification badge immediately flags the discrepancy, switching to a warning state that alerts the user or agent that the file has drifted.

How do AI agents use provenance in practice?

In our agentic pipelines, agents connect to a Model Context Protocol (MCP) gate server. Before an agent executes a high-impact operation (such as modifying production code or deleting files), the gate requires an explicit evidence contract. If the instruction comes from an unsigned or tampered sidecar, the agent fails closed, preventing prompt injections and unauthorized actions.

Where can I inspect the code and try it myself?

The reference engine is completely open source in our repository at github.com/MoongladeAI/provenance (standalone release pending). You can also inspect the live signatures on any post in this journal or download our public keys from /.well-known/anaiya-key.asc.

Engineering for permanence

We believe that the next era of computing belongs to systems that can prove their own integrity. When we eliminate unearned claims, replace decorative badges with real cryptographic checks, and give both humans and AI agents solid ground to stand on, software becomes more dependable, accountable, and enduring.

Keep your hashes verified, watch your boundaries, and never accept a claim without the receipts. 🌴✨