ADR 12: AT Protocol Rust Ecosystem Integration

Status: Accepted Date: 2026-04-10

Context

Substratum's authentication and identity layer relies entirely on the AT Protocol (did:plc). Implementing the modern AT Protocol 3-legged OAuth 2.0 profile manually—including Client ID Metadata Documents (CIMD), Pushed Authorization Requests (PAR), Proof Key for Code Exchange (PKCE), and Demonstration of Proof-of-Possession (DPoP)—is highly complex and error-prone.

We need to determine whether to build these cryptographic and network resolution pipelines from scratch using low-level HTTP clients (reqwest) and standard JWT libraries, or to leverage existing Rust crates. The chosen solution must integrate seamlessly with our Axum/Tokio backend and support high-throughput, non-blocking DID resolution for the Gateway.

Decision

We will adopt the **atproto-* workspace** as the foundational dependency for our auth and ingress crates, running on Axum 0.8 and Tokio.

Specifically, we will use:

1. **atproto-identity**: To handle did:plc resolution, fallback logic, and multibase key parsing. We will heavily utilize its internal LRU caching (storage_lru) to prevent rate-limiting from plc.directory during high-volume IPFS block requests.
2. **atproto-oauth-axum**: To manage the entire state machine of the 3-legged OAuth flow, including serving JWKS and handling PAR/PKCE automatically.
3. **atproto-xrpcs**: To provide native Axum FromRequestParts extractors (e.g., auth: Authorization) that asynchronously verify ATProto JWT signatures and DPoP proofs against dynamically resolved cryptographic keys before executing route handlers.

Consequences

• Positive:
  • Security & Compliance: Eliminates the risk of manual implementation flaws in complex cryptographic flows (like DPoP and multibase decoding). Ensures full RFC compliance.
  • Performance: Native asynchronous traits in Axum 0.8 allow the atproto-xrpcs middleware to yield to the Tokio runtime during network-bound DID resolution, preventing thread blocking. The LRU cache ensures microsecond validation times after initial resolution.
  • Developer Velocity: Provides out-of-the-box Axum extractors and OAuth routing handlers, saving weeks of custom development.
• Negative:
  • Ecosystem Dependency: Tightly couples our authentication architecture to the atproto-* workspace. We must actively monitor these crates for security advisories and updates.
  • Frontend Complexity: Enforcing DPoP means the Mithril.js frontend must generate and sign a unique cryptographic proof for every single API request using the WASM core crate, increasing client-side complexity.