Passport Receipt Schema

The Passport Receipt is a core component of Substratum's Data Integrity & Resilience layer. It provides built-in support for Digital Asset Passport standards, ensuring every file carries an immutable audit trail for provenance and copyright.

Overview

Every file uploaded to the Substratum network is accompanied by a cloud.substratum.passport.receipt AT Protocol record on the owner's Personal Data Server (PDS). The record binds the asset Content Identifier (CID) to the owner's did:plc and an Access Control List.

Early v1 design docs assumed a detached provenance_signature on receipt JSON, signed with the owner's AT Protocol private key. That sketch did not account for OAuth web clients—the gateway never holds user #atproto keys, and browsers cannot sign with them safely. The shipped v2 model (ADR 27: Zero Trust PDS-Based Provenance) publishes cloud.substratum.passport.receipt on the owner repo via createRecord; provenance is the PDS-signed Merkle Search Tree (MST) commit that incorporates the record. The libp2p retrieval layer verifies that repo commit—no detached signature field and no Substratum-held signing key.

The canonical machine contract is libs/lexicons/defs/cloud.substratum.passport.receipt.json. The JSON below is narrative reference aligned with that lexicon.

Core Components

1. ownerDid: The DID of the creator/uploader.
2. assetCid: The content-addressed identifier of the underlying asset in the private mesh blockstore.
3. access_control: A list of DIDs authorized to view the content, enabling content-level sharing.
4. metadata: Optional Digital Asset Passport fields (cloud.substratum.passport.assetMetadata).
5. PDS repo commit: Provenance is the AT Protocol MST commit on the owner repo when the receipt record is written—the user's #atproto key stays on the PDS, not in the gateway or browser.

Schema Definition (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Substratum Passport Receipt (cloud.substratum.passport.receipt)",
  "type": "object",
  "required": [
    "version",
    "assetCid",
    "ownerDid",
    "timestamp"
  ],
  "properties": {
    "version": {
      "type": "string",
      "description": "Schema version (e.g., '1.0.0')"
    },
    "assetCid": {
      "type": "string",
      "description": "The Content Identifier (CID) of the underlying asset"
    },
    "ownerDid": {
      "type": "string",
      "description": "The did:plc of the user who uploaded/owns the asset"
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp of the upload/creation"
    },
    "access_control": {
      "type": "array",
      "description": "List of DIDs authorized to access this asset. If empty, it is strictly private to the owner.",
      "items": {
        "type": "string"
      }
    },
    "metadata": {
      "type": "object",
      "description": "Digital Asset Passport standard metadata (cloud.substratum.passport.assetMetadata)",
      "properties": {
        "title": { "type": "string" },
        "description": { "type": "string" },
        "mimeType": { "type": "string" },
        "copyright": { "type": "string" },
        "license": { "type": "string" }
      }
    }
  }
}

Publication and Sync

The gateway (or home-base) publishes receipts via com.atproto.repo.createRecord using the owner's OAuth DPoP session. Catalog rows in PostgreSQL may lead the owner PDS briefly; ADR 28: Receipt Sync Queue and Grantee Access Removal defines how catalog intent converges onto owner-repo receipts.

The Benefit

• Provenance: Creators have cryptographic proof that they authored the receipt, because only their PDS can produce a valid MST commit with their #atproto key.
• Copyright: The metadata block allows for clear, immutable copyright and licensing declarations.
• Seamless Delivery: The gateway can read access_control to issue temporary, time-bound access tokens for paid content, patrons, and subscribers without decrypting the underlying asset first.
• Mesh enforcement: The libp2p swarm resolves the owner-repo receipt and verifies the MST commit before honoring access_control for GetBlock and replication (ADR 27).