Substratum.cloud

Appearance

Architecture Decision Record (ADR) 27: Zero Trust PDS-Based Provenance ​

Status: Accepted
Date: 2026-05-16

Glossary (acronyms in full, with abbreviation in brackets) ​

  • Architecture Decision Record (ADR)
  • Authenticated Transfer Protocol (AT Protocol)
  • Content Identifier (CID)
  • Decentralized Identifier (DID)
  • Demonstration of Proof-of-Possession (DPoP)
  • Open Authorization (OAuth)
  • Personal Data Server (PDS)
  • Pre-Shared Key (PSK)
  • Merkle Search Tree (MST)

Context ​

Substratum's authentication and identity layer relies on the AT Protocol (did:plc) and OAuth. In a multi-tenant SaaS or federated mesh environment, we must cryptographically prove file ownership and enforce Access Control Lists (ACL) on the private libp2p mesh.

Previously, we considered two flawed models for receipt provenance:

  1. User #atproto Key Signing on Gateway: The Gateway requires a single SUBSTRATUM_PROVENANCE_SIGNING_KEY. This breaks in an OAuth environment because the Gateway never possesses the users' private AT Protocol signing keys.
  2. Gateway Attestation: The Gateway uses its own private key to attest to uploads. This creates a "Walled Garden" and centralized point of compromise, breaking the Zero Trust and Data Sovereignty mandate. Self-hosted users generating their own receipts would be rejected by the Gateway.

A pure Zero Trust architecture requires that only the user has the cryptographic power to prove they uploaded a file and authorized access to it. However, because web clients cannot securely access the user's private #atproto keys (which live on their PDS), local client-side signing is not feasible for standard web users.

Decision ​

We will adopt a PDS-Based Provenance model to achieve Zero Trust without requiring manual key management for web users.

  1. OAuth DPoP Integration: When a user uploads a file, the Gateway uses their OAuth DPoP session to act as an authorized AT Protocol AppView/Client.
  2. PDS createRecord: The Gateway calls com.atproto.repo.createRecord on the user's Personal Data Server (PDS) to create a new cloud.substratum.passport.receipt record containing the asset_cid and the access_control list.
  3. Optimistic Validation: We leverage the AT Protocol's "schema-less" optimistic validation. The PDS accepts the custom cloud.substratum.passport.receipt JSON without needing predefined lexicon support.
  4. PDS-Level Signing: The PDS signs the repository commit (using the user's private #atproto key) incorporating the new receipt.
  5. Mesh Verification (Retrieval Layer): The libp2p mesh swarm actor no longer verifies raw JSON provenance_signature strings. Instead, it queries the user's AT Protocol repository for the receipt record and verifies the Merkle Search Tree (MST) commit signature.

Consequences ​

Positive ​

  • True Zero Trust: The Gateway never holds the user's private AT Protocol key, and the Gateway cannot unilaterally forge receipts.
  • Interoperability & Federation: Any AT Protocol client or Substratum node can read the PDS and verify ownership. Self-hosted users and SaaS users share the exact same cryptographic proof mechanism.
  • Seamless UX: Users do not need to manage, paste, or expose their private AT Protocol signing keys to the Substratum application.

Negative ​

  • Network Overhead: Uploading a file now requires a network roundtrip from the Gateway to the user's PDS to create the record.
  • Mesh Verification Complexity: The libp2p retrieval layer must now resolve and verify MST proofs from the AT Protocol, which is computationally heavier than checking a single ECDSA/EdDSA signature on a JSON blob.
  • PDS Bloat: User PDS repositories will store a receipt record for every file they upload to Substratum.