feat: PR 1.7 Add DPoP (Demonstrating Proof-of-Possession) support

.gitignore

@@ -17,9 +17,12 @@ vendor/
 
 # Docs
 docs/
-# Example binaries
-examples/echo-example/echo
-examples/gin-example/gin
-examples/http-example/http
-examples/http-jwks-example/http-jwks
-examples/iris-example/iris
+
+# Example binaries - ignore executables (not .go, .mod, .sum, .md files)
+examples/*/echo
+examples/*/gin
+examples/*/iris
+examples/*/http
+examples/*/http-jwks
+examples/*/http-dpop
+examples/*/http-dpop-*

MIGRATION_GUIDE.md

@@ -28,14 +28,16 @@ This guide helps you migrate from go-jwt-middleware v2 to v3. While v3 introduce
 | **Architecture** | Monolithic | Core-Adapter pattern |
 | **Context Key** | `ContextKey{}` struct | Unexported `contextKey int` |
 | **Type Names** | `ExclusionUrlHandler` | `ExclusionURLHandler` |
+| **TokenExtractor** | Returns `string` | Returns `ExtractedToken` |
+| **DPoP Support** | Not available | Full RFC 9449 support |
 
 ### Why Upgrade?
 
 - ✅ **Better Performance**: lestrrat-go/jwx v3 is faster and more efficient
 - ✅ **More Algorithms**: Support for EdDSA, ES256K, and all modern algorithms
 - ✅ **Type Safety**: Generics eliminate type assertion errors at compile time
 - ✅ **Better IDE Support**: Self-documenting options with autocomplete
-- ✅ **Enhanced Security**: CVE mitigations and RFC 6750 compliance
+- ✅ **Enhanced Security**: CVE mitigations, RFC 6750 compliance, and DPoP support
 - ✅ **Modern Go**: Built for Go 1.23+ with modern patterns
 
 ## Breaking Changes
@@ -120,6 +122,26 @@ type ExclusionUrlHandler func(r *http.Request) bool
 type ExclusionURLHandler func(r *http.Request) bool
 ```
 
+### 5. TokenExtractor Signature Change
+
+`TokenExtractor` now returns `ExtractedToken` (with scheme) instead of `string`:
+
+**v2:**
+```go
+type TokenExtractor func(r *http.Request) (string, error)
+```
+
+**v3:**
+```go
+type ExtractedToken struct {
+    Token  string
+    Scheme AuthScheme  // AuthSchemeBearer, AuthSchemeDPoP, or AuthSchemeUnknown
+}
+type TokenExtractor func(r *http.Request) (ExtractedToken, error)
+```
+
+**Note:** Built-in extractors (`CookieTokenExtractor`, `ParameterTokenExtractor`, `MultiTokenExtractor`) work unchanged. Only custom extractors need updating.
+
 ## Step-by-Step Migration
 
 ### 1. Update Dependencies
@@ -328,15 +350,48 @@ if err != nil {
 
 #### Token Extractors
 
-No changes needed - same API:
+**v3 Breaking Change**: `TokenExtractor` now returns `ExtractedToken` instead of `string`:
+
+**v2:**
+```go
+// TokenExtractor returned string
+type TokenExtractor func(r *http.Request) (string, error)
+```
+
+**v3:**
+```go
+// TokenExtractor returns ExtractedToken with both token and scheme
+type ExtractedToken struct {
+    Token  string
+    Scheme AuthScheme  // bearer, dpop, or unknown
+}
+type TokenExtractor func(r *http.Request) (ExtractedToken, error)
+```
 
+Built-in extractors work the same way:
 ```go
-// Both v2 and v3
+// These all work unchanged - internal implementation updated
 jwtmiddleware.CookieTokenExtractor("jwt")
 jwtmiddleware.ParameterTokenExtractor("token")
 jwtmiddleware.MultiTokenExtractor(extractors...)
 ```
 
+**Custom extractors must be updated:**
+```go
+// v2
+customExtractor := func(r *http.Request) (string, error) {
+    return r.Header.Get("X-Custom-Token"), nil
+}
+
+// v3
+customExtractor := func(r *http.Request) (jwtmiddleware.ExtractedToken, error) {
+    return jwtmiddleware.ExtractedToken{
+        Token:  r.Header.Get("X-Custom-Token"),
+        Scheme: jwtmiddleware.AuthSchemeUnknown, // or AuthSchemeBearer if you know
+    }, nil
+}
+```
+
 ### 5. Update Claims Access
 
 #### Handler Claims Access
@@ -578,6 +633,31 @@ middleware, err := jwtmiddleware.New(
 )
 ```
 
+### 6. DPoP (Demonstrating Proof-of-Possession)
+
+v3 adds full support for RFC 9449 DPoP, which provides proof-of-possession for access tokens:
+
+```go
+// DPoP modes:
+// - DPoPAllowed (default): Accept both Bearer and DPoP tokens
+// - DPoPRequired: Only accept DPoP tokens  
+// - DPoPDisabled: Ignore DPoP, reject DPoP scheme
+
+middleware, err := jwtmiddleware.New(
+    jwtmiddleware.WithValidator(jwtValidator),
+    jwtmiddleware.WithDPoPMode(jwtmiddleware.DPoPRequired),
+)
+```
+
+DPoP validates:
+- Proof signature using asymmetric algorithms (RS256, ES256, etc.)
+- HTTP method and URL binding (`htm` and `htu` claims)
+- Token binding via thumbprint (`jkt` claim in access token's `cnf`)
+- Access token hash (`ath` claim) matching
+- Replay protection via `jti` and `iat` claims
+
+See the [DPoP examples](./examples/http-dpop-example) for complete working code.
+
 ## FAQ
 
 ### Q: Can I use v2 and v3 side by side during migration?

README.md

@@ -70,6 +70,17 @@ jwtmiddleware.New(
 ### 🛡️ Enhanced Security
 - RFC 6750 compliant error responses
 - Secure defaults (credentials required, clock skew = 0)
+- **DPoP support** (RFC 9449) for proof-of-possession tokens
+
+### 🔑 DPoP (Demonstrating Proof-of-Possession)
+Prevent token theft with proof-of-possession:
+
+```go
+jwtmiddleware.New(
+    jwtmiddleware.WithValidator(jwtValidator),
+    jwtmiddleware.WithDPoPMode(jwtmiddleware.DPoPRequired),
+)
+```
 
 ## Getting Started
 
@@ -121,7 +132,7 @@ var handler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 })
 
 func main() {
-	keyFunc := func(ctx context.Context) (interface{}, error) {
+	keyFunc := func(ctx context.Context) (any, error) {
 		// Our token must be signed using this secret
 		return []byte("secret"), nil
 	}
@@ -442,12 +453,60 @@ jwtValidator, err := validator.New(
 )
 ```
 
+### DPoP (Demonstrating Proof-of-Possession)
+
+v3 adds support for [DPoP (RFC 9449)](https://datatracker.ietf.org/doc/html/rfc9449), which provides proof-of-possession for access tokens. This prevents token theft and replay attacks.
+
+#### DPoP Modes
+
+| Mode | Description | Use Case |
+|------|-------------|----------|
+| **DPoPAllowed** (default) | Accepts both Bearer and DPoP tokens | Migration period, backward compatibility |
+| **DPoPRequired** | Only accepts DPoP tokens | Maximum security |
+| **DPoPDisabled** | Ignores DPoP proofs, rejects DPoP scheme | Legacy systems |
+
+#### Basic DPoP Setup
+
+```go
+middleware, err := jwtmiddleware.New(
+	jwtmiddleware.WithValidator(jwtValidator),
+	jwtmiddleware.WithDPoPMode(jwtmiddleware.DPoPAllowed), // Default
+)
+```
+
+#### Require DPoP for Maximum Security
+
+```go
+middleware, err := jwtmiddleware.New(
+	jwtmiddleware.WithValidator(jwtValidator),
+	jwtmiddleware.WithDPoPMode(jwtmiddleware.DPoPRequired),
+)
+```
+
+#### Behind a Proxy
+
+When running behind a reverse proxy, configure trusted proxy headers:
+
+```go
+middleware, err := jwtmiddleware.New(
+	jwtmiddleware.WithValidator(jwtValidator),
+	jwtmiddleware.WithDPoPMode(jwtmiddleware.DPoPRequired),
+	jwtmiddleware.WithStandardProxy(),  // Trust X-Forwarded-* headers
+)
+```
+
+See the [DPoP examples](./examples/http-dpop-example) for complete working code.
+
 ## Examples
 
 For complete working examples, check the [examples](./examples) directory:
 
 - **[http-example](./examples/http-example)** - Basic HTTP server with HMAC
 - **[http-jwks-example](./examples/http-jwks-example)** - Production setup with JWKS and Auth0
+- **[http-dpop-example](./examples/http-dpop-example)** - DPoP support (allowed mode)
+- **[http-dpop-required](./examples/http-dpop-required)** - DPoP required mode
+- **[http-dpop-disabled](./examples/http-dpop-disabled)** - DPoP disabled mode
+- **[http-dpop-trusted-proxy](./examples/http-dpop-trusted-proxy)** - DPoP behind reverse proxy
 - **[gin-example](./examples/gin-example)** - Integration with Gin framework
 - **[echo-example](./examples/echo-example)** - Integration with Echo framework
 - **[iris-example](./examples/iris-example)** - Integration with Iris framework

core/context.go

@@ -9,6 +9,9 @@ type contextKey int
 
 const (
 	claimsKey contextKey = iota
+	dpopContextKey
+	authSchemeKey
+	dpopModeKey
 )
 
 // GetClaims retrieves claims from the context with type safety using generics.
@@ -53,3 +56,106 @@ func SetClaims(ctx context.Context, claims any) context.Context {
 func HasClaims(ctx context.Context) bool {
 	return ctx.Value(claimsKey) != nil
 }
+
+// SetDPoPContext stores DPoP context in the context.
+// This is a helper function for adapters to set DPoP context after validation.
+//
+// DPoP context contains information about the validated DPoP proof, including
+// the public key thumbprint, issued-at timestamp, and the raw proof JWT.
+func SetDPoPContext(ctx context.Context, dpopCtx *DPoPContext) context.Context {
+	return context.WithValue(ctx, dpopContextKey, dpopCtx)
+}
+
+// GetDPoPContext retrieves DPoP context from the context.
+// Returns nil if no DPoP context exists (e.g., for Bearer tokens).
+//
+// Example usage:
+//
+//	dpopCtx := core.GetDPoPContext(ctx)
+//	if dpopCtx != nil {
+//	    log.Printf("DPoP token from key: %s", dpopCtx.PublicKeyThumbprint)
+//	}
+func GetDPoPContext(ctx context.Context) *DPoPContext {
+	val := ctx.Value(dpopContextKey)
+	if val == nil {
+		return nil
+	}
+
+	dpopCtx, ok := val.(*DPoPContext)
+	if !ok {
+		return nil
+	}
+
+	return dpopCtx
+}
+
+// HasDPoPContext checks if a DPoP context exists in the context.
+// Returns true for DPoP-bound tokens, false for Bearer tokens.
+//
+// Example usage:
+//
+//	if core.HasDPoPContext(ctx) {
+//	    dpopCtx := core.GetDPoPContext(ctx)
+//	    // Handle DPoP-specific logic...
+//	}
+func HasDPoPContext(ctx context.Context) bool {
+	return ctx.Value(dpopContextKey) != nil
+}
+
+// SetAuthScheme stores the authorization scheme in the context.
+// This is used by adapters to track which auth scheme was used in the request.
+func SetAuthScheme(ctx context.Context, scheme AuthScheme) context.Context {
+	return context.WithValue(ctx, authSchemeKey, scheme)
+}
+
+// GetAuthScheme retrieves the authorization scheme from the context.
+// Returns AuthSchemeUnknown if no scheme was set.
+//
+// Example usage:
+//
+//	scheme := core.GetAuthScheme(ctx)
+//	if scheme == core.AuthSchemeDPoP {
+//	    // Handle DPoP-specific logic...
+//	}
+func GetAuthScheme(ctx context.Context) AuthScheme {
+	val := ctx.Value(authSchemeKey)
+	if val == nil {
+		return AuthSchemeUnknown
+	}
+
+	scheme, ok := val.(AuthScheme)
+	if !ok {
+		return AuthSchemeUnknown
+	}
+
+	return scheme
+}
+
+// SetDPoPMode stores the DPoP mode in the context.
+// This is used by adapters to track the DPoP mode configuration for error handling.
+func SetDPoPMode(ctx context.Context, mode DPoPMode) context.Context {
+	return context.WithValue(ctx, dpopModeKey, mode)
+}
+
+// GetDPoPMode retrieves the DPoP mode from the context.
+// Returns DPoPAllowed if no mode was set (default).
+//
+// Example usage:
+//
+//	mode := core.GetDPoPMode(ctx)
+//	if mode == core.DPoPRequired {
+//	    // Only accept DPoP tokens
+//	}
+func GetDPoPMode(ctx context.Context) DPoPMode {
+	val := ctx.Value(dpopModeKey)
+	if val == nil {
+		return DPoPAllowed // Default mode
+	}
+
+	mode, ok := val.(DPoPMode)
+	if !ok {
+		return DPoPAllowed
+	}
+
+	return mode
+}