···
5. Find matching key by `kid` from JWT header
6. Cache the JWKS for 1 hour
+
DPoP (Demonstrating Proof-of-Possession) binds access tokens to client-controlled cryptographic keys, preventing token theft and replay attacks.
+
DPoP is an OAuth extension (RFC 9449) that adds proof-of-possession semantics to bearer tokens. When a PDS issues a DPoP-bound access token:
+
1. Access token contains `cnf.jkt` claim (JWK thumbprint of client's public key)
+
2. Client creates a DPoP proof JWT signed with their private key
+
3. Server verifies the proof signature and checks it matches the token's `cnf.jkt`
+
### CRITICAL: DPoP Security Model
+
> ⚠️ **DPoP is an ADDITIONAL security layer, NOT a replacement for token signature verification.**
+
The correct verification order is:
+
1. **ALWAYS verify the access token signature first** (via JWKS, HS256 shared secret, or DID resolution)
+
2. **If the verified token has `cnf.jkt`, REQUIRE valid DPoP proof**
+
3. **NEVER use DPoP as a fallback when signature verification fails**
+
**Why This Matters**: An attacker could create a fake token with `sub: "did:plc:victim"` and their own `cnf.jkt`, then present a valid DPoP proof signed with their key. If we accept DPoP as a fallback, the attacker can impersonate any user.
+
┌─────────────┐ ┌─────────────┐
+
└─────────────┘ └─────────────┘
+
│ 1. Authorization: Bearer <token> │
+
│───────────────────────────────────────>│
+
│ │ 2. VERIFY token signature
+
│ │ (REQUIRED - no fallback!)
+
│ │ 3. If token has cnf.jkt:
+
│ │ - Verify DPoP proof
+
│ │ - Check thumbprint match
+
│<───────────────────────────────────────│
+
### When DPoP is Required
+
DPoP verification is **REQUIRED** when:
+
- Access token signature has been verified AND
+
- Access token contains `cnf.jkt` claim (DPoP-bound)
+
If the token has `cnf.jkt` but no DPoP header is present, the request is **REJECTED**.
+
DPoP proofs include a unique `jti` (JWT ID) claim. The server tracks seen `jti` values to prevent replay attacks:
+
// Create a verifier with replay protection (default)
+
verifier := auth.NewDPoPVerifier()
+
defer verifier.Stop() // Stop cleanup goroutine on shutdown
+
// The verifier automatically rejects reused jti values within the proof validity window (5 minutes)
+
### DPoP Implementation
+
The `dpop.go` module provides:
+
// Create a verifier with replay protection
+
verifier := auth.NewDPoPVerifier()
+
// Verify the DPoP proof
+
proof, err := verifier.VerifyDPoPProof(dpopHeader, "POST", "https://coves.social/xrpc/...")
+
// Invalid proof (includes replay detection)
+
// Verify it binds to the VERIFIED access token
+
expectedThumbprint, err := auth.ExtractCnfJkt(claims)
+
// Token not DPoP-bound
+
if err := verifier.VerifyTokenBinding(proof, expectedThumbprint); err != nil {
+
// Proof doesn't match token
+
The DPoP header contains a JWT with:
+
- `typ`: `"dpop+jwt"` (required)
+
- `alg`: `"ES256"` (or other supported algorithm)
+
- `jwk`: Client's public key (JWK format)
+
- `jti`: Unique proof identifier (tracked for replay protection)
+
- `htm`: HTTP method (e.g., `"POST"`)
+
- `htu`: HTTP URI (without query/fragment)
+
- `iat`: Timestamp (must be recent, within 5 minutes)
+
"jti": "unique-id-123",
+
"htu": "https://coves.social/xrpc/social.coves.community.create",
## Security Considerations
···
- Required claims validation (sub, iss)
- Secure error messages (no internal details leaked)
+
- **DPoP proof verification** (proof-of-possession for token binding)
+
- **DPoP thumbprint validation** (prevents token theft attacks)
+
- **DPoP freshness checks** (5-minute proof validity window)
+
- **DPoP replay protection** (jti tracking with in-memory cache)
+
- **Secure DPoP model** (DPoP required AFTER signature verification, never as fallback)
### ⚠️ Not Yet Implemented
+
- Server-issued DPoP nonces (additional replay protection)
- Scope validation (checking `scope` claim)
- Audience validation (checking `aud` claim)
···
+
- [ ] DPoP nonce validation (server-managed nonce for additional replay protection)
- [ ] Scope-based authorization
- [ ] Audience claim validation
- [ ] Token revocation support
bretton.dev