Technical Specification: Substratum v1.0

Last Updated: 2026-06-07

Core Features & Benefits

Feature	Function	The Benefit
DID-Siloed Nodes	Media is hosted on nodes that only handshake with your specific DID.	Absolute data sovereignty; no "neighbor" discovery.
Substratum Gateway	A high-speed private edge that issues temporary, time-bound access tokens.	Seamless delivery for paid content, patrons, and subscribers.
Passport Receipts	Built-in support for Digital Asset Passport standards.	Every file carries an immutable audit trail for provenance and copyright.

1. Identity & Authentication (The "Key")

Substratum does not maintain a proprietary user database. It uses the AT Protocol for all authentication.

• Identity Method: did:plc (Persistent Identifier).
• Auth Flow: Implement the AT Proto OAuth (3-legged) profile.
  1. User enters their handle (e.g., user.bsky.social).
  2. Substratum resolves the handle to a did:plc:xyz document.
  3. User is redirected to their PDS (Personal Data Server) to authorize Substratum.
• Token Scoping: The OAuth session issues a JWT that must be presented to the Substratum Gateway for any CRUD operations on the swarm.

2. Network Architecture (The "Bedrock")

Substratum implements a Hybrid Mesh consisting of the Global Triangle (managed cloud) and the Local Sidecar (user-managed).

A. The Global Triangle (Cloud Nodes)

• Deployment: Three nodes in non-overlapping legal jurisdictions: US-East (Virginia), EU-Central (Frankfurt), and Asia-Pacific (Tokyo).
• Discovery: These nodes do not use the Public DHT. They use a Static Bootstrapper list.
• Protocol: libp2p with noise encryption.

B. The Private Swarm (PSK Generation)

Every user is assigned a unique 256-bit Swarm PSK derived from: $$PSK = SHA256(Substratum_Master_Secret + User_DID)$$ This ensures that even if a "Sidecar" is compromised, only that specific user's silo is exposed, not the entire Substratum network.

3. The "Identity-Gated" Gateway (The "Drive")

The Gateway is a high-performance Web 2.0 (HTTPS) proxy that brokers the relationship between the browser and the IPFS bits.

Layer	Responsibility	Implementation
Ingress	Handle HTTPS requests for CIDs.	Axum routes using api-models.
Auth	Verify the AT Proto OAuth JWT.	Middleware check against the PDS issuer.
Resolution	Map CID to User DID.	Internal Metadata Store (Redis/PostgreSQL).
Retrieval	Fetch blocks from the Private Swarm.	substratum-retrieval (libp2p). Enforces ACLs at the peer level.

Gateway Runtime Configuration

• JWT_SECRET: signs gateway session JWTs.
• SWARM_MASTER_SECRET: derives per-user private swarm PSKs.
• LIBP2P_IDENTITY_KEY: base64 protobuf keypair for a stable gateway PeerId.
• Storage backend selection:
  • FlatFS (default): used when S3_ACCESS_KEY is not set.
  • S3-compatible: enabled when S3_ACCESS_KEY is set, with S3_SECRET_KEY.
  • Optional overrides: S3_REGION (default us-east-1), S3_BUCKET (default substratum-blocks), and S3_ENDPOINT (required for providers like DigitalOcean Spaces).
• Reference template: .env.example.

4. Data Integrity & Resilience (The "Sabotage Layer")

• Multi-Jurisdictional Pinning: Every upload is automatically pinned across all three "Triangle" nodes.
• Passport Receipts: Every file is accompanied by a cloud.substratum.passport.receipt AT Protocol record on the owner's PDS containing:
  • ownerDid: The master identity of the uploader.
  • assetCid: The content-addressed identifier of the asset.
  • access_control: A list of DIDs authorized to view the content (enabling content-level sharing).
  • PDS commit proof: Provenance is the Merkle Search Tree (MST) commit signature on the owner repo—not a detached JSON signature (ADR 27). The libp2p Swarm Actor resolves the owner-repo receipt and verifies the MST commit before checking the requester's DID against access_control. Catalog ACL may lead the PDS briefly; ADR 28 converges catalog intent onto owner-repo receipts.

5. Application Components

Substratum.cloud (SaaS Dashboard)

• Visual Interface: Manage drives, view storage usage, and generate sharing links.
• Developer API: An S3-compatible API that requires a DID-Signed Header instead of a static secret key.

The Substratum Sidecar (Local Agent)

• Form Factor: Docker container or CLI binary.
• Function: Joins the user's private swarm and provides a local localhost:8080 gateway.
• Offline Mode: If the cloud nodes are unreachable, the Sidecar acts as the primary provider for local applications.

---

6. Implementation Milestones

1. Phase 1 (Identity): Build the did:plc resolver and OAuth flow.
2. Phase 2 (Siloing): Implement the PSK-per-DID generation and private libp2p handshake.
3. Phase 3 (Gateway): Build the "Auth-Gate" that checks JWTs before resolving IPFS blocks.
4. Phase 4 (Resilience): Deploy the "Triangle" and build the Sidecar sync protocol.

---

Design Note on Brute-Force Protection: By combining Network Isolation (the PSK-siloed swarm) with Identity-Gated Swarm Access (requiring an AT Proto JWT in the libp2p payload and verifying owner-repo Passport Receipts via PDS MST commits), we create a two-lock system. An attacker would need to both crack the XSalsa20 swarm encryption and compromise the user's AT Proto private keys to "see" the data. Even a rogue libp2p node with a stolen PSK cannot retrieve blocks without cryptographically proving membership in an authorized DID, nor can they forge an owner-repo receipt without the owner's #atproto signing key.