moai-adk 0.8.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-platform-auth0/modules/dpop-implementation.md

@@ -0,0 +1,283 @@
+# DPoP Implementation
+
+Demonstrating Proof-of-Possession (DPoP) is an OAuth 2.0 extension that cryptographically binds access and refresh tokens to the client application, preventing token theft and misuse.
+
+## Overview
+
+DPoP ensures only the client possessing the private key can use issued tokens. Unlike traditional bearer tokens where anyone with the token can use it, DPoP tokens are bound to a specific client.
+
+## Current Status
+
+DPoP at Auth0 is in Early Access. Contact your Auth0 representative to request access.
+
+## How DPoP Works
+
+### Key Pair Generation
+
+Client generates asymmetric key pair:
+- Private key: Kept secret, never transmitted
+- Public key: Included in DPoP proof JWT
+
+Recommended Algorithms:
+- ES256 (Elliptic Curve): Recommended for modern applications
+- RS256 (RSA): Broader compatibility
+
+Key Storage:
+- Hardware-backed keystores when available
+- Secure enclave on mobile devices
+- Encrypted storage for web applications
+
+### DPoP Proof JWT
+
+A signed JWT proving possession of the private key.
+
+Header Claims:
+- typ: Must be "dpop+jwt"
+- alg: Signing algorithm (ES256, RS256)
+- jwk: Public key representation
+
+Payload Claims:
+- jti: Unique identifier (prevents replay)
+- htm: HTTP method of request (POST, GET)
+- htu: HTTP URI of request (without fragments)
+- iat: Issue timestamp
+- ath: Access token hash (for API calls)
+- nonce: Server-provided value (for public clients)
+
+### Token Request
+
+When requesting tokens:
+1. Generate new DPoP proof JWT
+2. Set htm to POST
+3. Set htu to token endpoint
+4. Sign with private key
+5. Send in DPoP header
+
+Request Headers:
+- DPoP: {dpop_proof_jwt}
+- Content-Type: application/x-www-form-urlencoded
+
+### Nonce Handling (Public Clients)
+
+For SPAs and mobile apps:
+
+Initial Request:
+- Send without nonce
+- May receive use_dpop_nonce error
+- Response includes DPoP-Nonce header
+
+Retry with Nonce:
+- Generate new DPoP proof
+- Include nonce in payload
+- Auth0 validates nonce freshness
+
+### Token Binding
+
+Auth0 binds token to public key:
+
+Access Token Contains:
+- cnf (confirmation) claim
+- jkt (JWK Thumbprint) value
+- SHA-256 hash of public key
+
+This binding ensures only the key holder can use the token.
+
+### API Request
+
+When calling resource server:
+
+Generate New DPoP Proof:
+- htm: HTTP method (GET, POST, etc.)
+- htu: API endpoint URL
+- ath: Base64url SHA-256 hash of access token
+- Same key pair as token request
+
+Request Headers:
+- Authorization: DPoP {access_token}
+- DPoP: {dpop_proof_jwt}
+
+### Server Validation
+
+Resource server validates:
+1. Extract DPoP proof from header
+2. Verify proof signature
+3. Check jti uniqueness (prevent replay)
+4. Validate htm matches request method
+5. Validate htu matches request URI
+6. Compute access token hash
+7. Compare ath with computed hash
+8. Compare proof jwk thumbprint with token cnf.jkt
+
+## Implementation Steps
+
+### Step 1: Key Generation
+
+Generate asymmetric key pair:
+- Use cryptographic library
+- Store private key securely
+- Persist across token refresh
+
+Key Considerations:
+- Generate once per installation
+- Reuse for token refresh
+- May rotate periodically
+
+### Step 2: Initial Token Request
+
+Create DPoP proof for token endpoint:
+- Include required claims
+- Sign with private key
+- No ath claim (no access token yet)
+
+### Step 3: Handle Nonce (If Required)
+
+If use_dpop_nonce error:
+- Extract nonce from DPoP-Nonce header
+- Create new proof with nonce
+- Retry request
+
+### Step 4: Store Tokens
+
+After successful request:
+- Store access token
+- Store refresh token (if applicable)
+- Associate with key pair
+
+### Step 5: API Calls
+
+For each API request:
+- Generate fresh DPoP proof
+- Include ath claim with token hash
+- Send both token and proof
+
+### Step 6: Token Refresh
+
+When refreshing tokens:
+- Generate new DPoP proof
+- Use same key pair
+- New tokens bound to same key
+
+## Security Considerations
+
+### Key Protection
+
+Private Key Security:
+- Never transmit private key
+- Use secure storage
+- Consider hardware backing
+
+Key Compromise:
+- If key compromised, token useless without new key
+- Revoke tokens and regenerate key pair
+- Better than bearer token compromise
+
+### Replay Prevention
+
+jti Uniqueness:
+- Generate unique jti for each proof
+- Resource server tracks seen jti values
+- Rejects duplicates
+
+Time Binding:
+- iat limits proof validity
+- Short acceptance window
+- Clock synchronization important
+
+### Token Binding
+
+Benefits:
+- Stolen token unusable without private key
+- Attacker cannot forge valid proofs
+- Significantly reduces token theft risk
+
+## Client Types
+
+### Confidential Clients
+
+Server-side applications:
+- Secure key storage available
+- Combine with client authentication
+- Strongest security configuration
+
+### Public Clients
+
+SPAs and mobile apps:
+- Must handle nonce flow
+- Use secure platform storage
+- More complex but valuable
+
+### Native Applications
+
+Mobile apps:
+- Use platform secure storage
+- Hardware-backed keys when available
+- iOS Keychain, Android Keystore
+
+## Comparison with mTLS
+
+DPoP Advantages:
+- Application-layer (no TLS changes)
+- Works with public clients
+- No PKI infrastructure required
+- Easier deployment
+
+mTLS Advantages:
+- Transport-layer binding
+- Established infrastructure
+- Simpler for confidential clients
+
+Choose DPoP When:
+- Public clients (SPA, mobile)
+- No PKI available
+- Flexibility needed
+
+Choose mTLS When:
+- Confidential clients only
+- PKI exists
+- Transport-layer binding preferred
+
+## Troubleshooting
+
+Common Issues:
+
+Invalid Signature:
+- Verify key pair consistency
+- Check algorithm matches
+- Confirm JWT format
+
+Nonce Required:
+- Public clients need nonce
+- Extract from error response
+- Include in retry
+
+Token Binding Failure:
+- Use same key for proof and token
+- Verify ath calculation
+- Check thumbprint computation
+
+Clock Skew:
+- Synchronize client clock
+- Allow reasonable iat window
+- Consider server time
+
+## Best Practices
+
+Key Management:
+- Secure key generation
+- Protected storage
+- Consistent key usage
+
+Proof Generation:
+- Fresh proof per request
+- Unique jti always
+- Correct claim values
+
+Error Handling:
+- Handle nonce errors
+- Retry logic
+- Clear error messaging
+
+Testing:
+- Validate full flow
+- Test error scenarios
+- Verify binding works

moai_adk/templates/.claude/skills/moai-platform-auth0/modules/fapi-implementation.md

@@ -0,0 +1,259 @@
+# FAPI Implementation
+
+Financial-grade API (FAPI) is a set of security and privacy specifications developed by the OpenID Foundation for robust authentication and authorization in financial services and other high-security scenarios.
+
+## Overview
+
+FAPI provides enhanced OAuth 2.0 and OpenID Connect profiles designed for:
+- Financial services
+- Open banking
+- Healthcare
+- Government services
+- Any high-security application
+
+## Auth0 FAPI Certification
+
+Auth0 is certified for:
+- FAPI 1.0 Advanced OP (OpenID Provider)
+- mTLS client authentication profile
+- Private Key JWT client authentication profile
+
+## FAPI Security Profiles
+
+### FAPI 1.0 Baseline
+
+Minimum security requirements for read-only access:
+- OAuth 2.0 authorization code flow
+- PKCE required
+- State parameter required
+- Confidential clients
+
+### FAPI 1.0 Advanced
+
+Enhanced security for read-write access:
+- All baseline requirements
+- Pushed Authorization Requests (PAR)
+- JWT-secured Authorization Requests (JAR)
+- mTLS or Private Key JWT client authentication
+- Sender-constrained tokens
+
+## Core Security Features
+
+### Strong Customer Authentication (SCA)
+
+Requirement: At least two independent authentication factors.
+
+Factor Categories:
+- Something known (password, PIN)
+- Something possessed (device, token)
+- Something inherent (biometric)
+
+Auth0 Implementation:
+- Multi-factor authentication
+- WebAuthn support
+- Push notifications
+- SMS/Voice verification
+
+### Dynamic Linking
+
+Purpose: Bind authorization to specific transaction details.
+
+Implementation:
+- Rich Authorization Requests (RAR)
+- Transaction details in authorization request
+- User verifies transaction during authorization
+- Authorization uniquely linked to transaction
+
+User Experience:
+- See transaction details
+- Confirm specific action
+- Authentication bound to transaction
+
+### Pushed Authorization Requests (PAR)
+
+Purpose: Secure transmission of authorization parameters.
+
+How It Works:
+1. Client sends parameters to PAR endpoint
+2. Auth0 returns request_uri
+3. Client redirects with request_uri only
+4. Sensitive parameters never in browser
+
+Benefits:
+- Parameters not exposed in URL
+- Reduced risk of manipulation
+- Signed request verification
+
+### JWT-Secured Authorization Requests (JAR)
+
+Purpose: Protect authorization request integrity and confidentiality.
+
+How It Works:
+- Authorization parameters in signed JWT
+- Optionally encrypted
+- Prevents tampering
+
+Benefits:
+- Request integrity
+- Optional confidentiality
+- Signed by client
+
+### JSON Web Encryption (JWE)
+
+Purpose: Encrypt access token payloads containing sensitive authorization details.
+
+Use Cases:
+- Rich authorization data
+- Sensitive permissions
+- Transaction details in tokens
+
+## Client Authentication
+
+### Private Key JWT
+
+Asymmetric authentication using signed JWTs.
+
+Features:
+- Private key never transmitted
+- Short-lived signed assertions
+- No shared secret
+
+Requirements:
+- Enterprise plan
+- Register public key with Auth0
+- Sign client_assertion with private key
+
+### mTLS for OAuth
+
+Mutual TLS client authentication.
+
+Features:
+- Certificate-based authentication
+- Transport-layer security
+- Strong client identity
+
+Requirements:
+- Enterprise plan with HRI add-on
+- Register client certificate
+- mTLS infrastructure
+
+## Token Security
+
+### Sender Constraining
+
+Bind tokens to client:
+- DPoP for application-layer binding
+- mTLS for transport-layer binding
+- Prevents token theft
+
+### Token Binding
+
+Certificate thumbprint in tokens:
+- cnf claim with x5t#S256
+- Validates client certificate
+- Ensures token only used by legitimate client
+
+## Implementation Requirements
+
+### Plan Requirements
+
+Minimum: Enterprise Plan
+
+For Full FAPI:
+- Highly Regulated Identity add-on
+- Required for mTLS
+- Required for advanced features
+
+### Configuration Steps
+
+1. Enable HRI Features:
+   - Contact Auth0
+   - Enable add-on
+   - Configure tenant
+
+2. Configure Client Authentication:
+   - Choose Private Key JWT or mTLS
+   - Register credentials
+   - Configure application
+
+3. Enable PAR:
+   - Configure PAR endpoint
+   - Update client to use PAR
+   - Test request flow
+
+4. Configure Token Binding:
+   - Enable sender constraining
+   - Choose DPoP or mTLS
+   - Configure resource servers
+
+### Application Changes
+
+Client Requirements:
+- Support PAR flow
+- Implement JAR if required
+- Handle sender-constrained tokens
+- Proper error handling
+
+Resource Server Requirements:
+- Validate sender-constrained tokens
+- Verify token binding
+- Handle FAPI token types
+
+## Best Practices
+
+### Credential Management
+
+Private Keys:
+- Secure generation
+- Protected storage
+- Regular rotation
+- Zero-downtime rotation support
+
+Certificates:
+- Proper CA hierarchy
+- Certificate lifecycle management
+- Revocation handling
+
+### Security Configuration
+
+Enable All Features:
+- PAR for authorization
+- JAR for request signing
+- Sender constraining for tokens
+- Strong client authentication
+
+Monitor and Audit:
+- Log all FAPI transactions
+- Monitor for anomalies
+- Regular security review
+
+### Testing
+
+Conformance Testing:
+- Use FAPI conformance suite
+- Test all flows
+- Verify error handling
+- Document test results
+
+## Regulatory Context
+
+### Open Banking
+
+UK/EU Open Banking:
+- FAPI profiles mandated
+- PSD2 alignment
+- Strong customer authentication
+
+### Financial Services
+
+Global Standards:
+- Financial sector requirements
+- Regulatory compliance
+- Security best practices
+
+### Healthcare
+
+SMART on FHIR:
+- FAPI-aligned security
+- Healthcare data protection
+- Patient consent management