moai-adk 0.35.1__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-security-auth0/modules/highly-regulated-identity.md

@@ -0,0 +1,272 @@
+# Highly Regulated Identity
+
+Auth0 Highly Regulated Identity (HRI) is a Financial-Grade Identity solution designed to secure sensitive data operations and services in regulated industries.
+
+## Overview
+
+HRI provides enhanced security for:
+- Financial services (banks, payment processors)
+- Healthcare (patient data, prescriptions)
+- Government services (identity verification)
+- Any high-value transaction processing
+
+Target Operations:
+- Money transfers
+- Digital payments
+- Medical record access
+- Contract signing
+- High-value authorizations
+
+## Requirements
+
+Plan: Enterprise Plan with Highly Regulated Identity add-on
+
+Contact: Auth0 sales for add-on enablement
+
+## Core Security Features
+
+### Strong Customer Authentication (SCA)
+
+Definition: Authentication requiring at least two independent factors from different categories.
+
+Factor Categories:
+- Knowledge: Something known (password, PIN)
+- Possession: Something possessed (device, token)
+- Inherence: Something intrinsic (biometric)
+
+Supported MFA Factors:
+- Mobile push notifications
+- SMS verification
+- Email verification
+- WebAuthn (security keys, biometrics)
+
+Dynamic Application:
+- Apply based on transaction risk
+- Step-up for sensitive operations
+- Context-aware enforcement
+
+### Dynamic Linking
+
+Purpose: Bind authorization to specific transaction details so users know exactly what they authorize.
+
+Rich Authorization Requests (RAR):
+- Include transaction details in authorization
+- Display details to user for confirmation
+- Authorization linked to specific transaction
+
+User Experience:
+- User sees transaction context
+- Confirms specific action (e.g., transfer $100)
+- Cannot be repurposed for other transactions
+
+Step-Up with Context:
+- Trigger MFA with transaction details
+- User verifies both identity and transaction
+- Strong binding between auth and action
+
+### Data Protection
+
+Pushed Authorization Requests (PAR):
+- Send authorization parameters directly to Auth0
+- Receive reference URI
+- Avoid exposing parameters in browser
+- Protect sensitive data from URL exposure
+
+JWT-Secured Authorization Requests (JAR):
+- Sign authorization request as JWT
+- Protect request integrity
+- Optional encryption for confidentiality
+- Prevent request tampering
+
+JSON Web Encryption (JWE):
+- Encrypt access token payloads
+- Protect authorization details
+- Confidentiality for sensitive data
+
+### Application Authentication
+
+Private Key JWT:
+- Asymmetric key authentication
+- Private key never transmitted
+- Register up to two public keys
+- Zero-downtime credential rotation
+
+mTLS for OAuth:
+- X.509 certificate authentication
+- Mutual TLS required
+- Certificate-based identity
+- Strongest client authentication
+
+Supported Algorithms:
+- RS256, RS384, RS512
+- PS256, PS384, PS512
+
+### Token Binding
+
+Certificate Thumbprint Association:
+- Token bound to client certificate
+- cnf claim with x5t#S256
+- Prevents token theft
+
+Sender Constraining:
+- Only legitimate client can use token
+- Certificate required for token use
+- Useless if stolen without certificate
+
+## Implementation
+
+### Prerequisites
+
+1. Enterprise Plan
+2. HRI add-on enabled
+3. Application configured as confidential client
+4. Certificate or key pair for authentication
+
+### Configuration Steps
+
+1. Enable HRI:
+   - Contact Auth0
+   - Activate add-on on tenant
+   - Verify HRI features available
+
+2. Configure Client Authentication:
+   - Generate key pair or obtain certificate
+   - Register with Auth0
+   - Configure application settings
+
+3. Enable Security Features:
+   - Configure PAR endpoint
+   - Set up JAR signing
+   - Enable token binding
+
+4. Configure MFA:
+   - Enable required factors
+   - Set up step-up policies
+   - Configure SCA rules
+
+5. Test Implementation:
+   - Verify all flows work
+   - Test error scenarios
+   - Validate security properties
+
+### Credential Management
+
+Key Pair Management:
+- Generate secure key pairs
+- Store private key securely
+- Register public key with Auth0
+
+Certificate Management:
+- Obtain from trusted CA
+- Register with Auth0
+- Plan for rotation
+
+Rotation:
+- Register new credential
+- Deploy to clients
+- Remove old credential
+- Up to two credentials active
+
+### Transaction Flow
+
+For High-Value Operations:
+
+1. Initiate Transaction:
+   - User starts sensitive operation
+   - Application determines step-up needed
+
+2. Authorization with RAR:
+   - Include transaction details
+   - Use PAR for security
+   - Sign request with JAR
+
+3. User Authentication:
+   - SCA enforced (two factors)
+   - Transaction details displayed
+   - User confirms authorization
+
+4. Token Issuance:
+   - Sender-constrained token issued
+   - Bound to client credential
+   - Contains authorization details
+
+5. Execute Operation:
+   - Present token to API
+   - Validate sender constraining
+   - Complete transaction
+
+## Security Benefits
+
+### Against Common Attacks
+
+Token Theft:
+- Tokens bound to client
+- Useless without credential
+- Sender constraining protection
+
+Request Manipulation:
+- JAR ensures integrity
+- Signed by client
+- Tampering detected
+
+Parameter Exposure:
+- PAR keeps parameters off URL
+- Server-to-server transmission
+- Reduced attack surface
+
+Phishing:
+- WebAuthn resists phishing
+- Transaction details visible
+- User confirms actual operation
+
+### Regulatory Compliance
+
+PSD2 (Europe):
+- SCA requirements met
+- Dynamic linking supported
+- Transaction authentication
+
+Open Banking:
+- FAPI-aligned
+- Financial-grade security
+- Regulatory compliance
+
+## Best Practices
+
+### Security Configuration
+
+Enable All Features:
+- Use PAR for all requests
+- Sign requests with JAR
+- Enable sender constraining
+- Enforce SCA appropriately
+
+Credential Security:
+- HSM for private keys
+- Secure certificate storage
+- Regular rotation
+- Access controls
+
+### User Experience
+
+Clear Transaction Display:
+- Show what user authorizes
+- Specific amounts and details
+- No ambiguous permissions
+
+Efficient MFA:
+- WebAuthn for seamless experience
+- Push notifications for speed
+- Fallback options available
+
+### Operations
+
+Monitoring:
+- Log all HRI transactions
+- Monitor for anomalies
+- Alert on failures
+
+Testing:
+- Regular security testing
+- Conformance verification
+- Penetration testing

moai_adk/templates/.claude/skills/moai-security-auth0/modules/jwt-fundamentals.md

@@ -0,0 +1,248 @@
+# JWT Fundamentals
+
+JSON Web Tokens (JWTs) are an open standard (RFC 7519) providing a compact, self-contained method for securely transmitting information between parties as a JSON object.
+
+## Structure
+
+JWTs consist of three parts separated by dots:
+- Header
+- Payload
+- Signature
+
+Format: header.payload.signature
+
+### Header
+
+Contains metadata about the token:
+- typ: Token type (JWT)
+- alg: Signing algorithm
+
+Common Algorithms:
+- HS256: HMAC with SHA-256 (symmetric)
+- RS256: RSA with SHA-256 (asymmetric)
+- ES256: ECDSA with SHA-256 (asymmetric)
+
+### Payload
+
+Contains claims (statements about the entity and additional data).
+
+Registered Claims (standard):
+- iss (issuer): Token issuer
+- sub (subject): Subject identifier
+- aud (audience): Intended recipients
+- exp (expiration): Expiration time
+- nbf (not before): Token valid after this time
+- iat (issued at): Token issue time
+- jti (JWT ID): Unique identifier
+
+Public Claims:
+- Registered in IANA JWT Registry
+- Common across implementations
+
+Private Claims:
+- Custom claims for specific use
+- Require namespace in Auth0
+
+### Signature
+
+Ensures token integrity and authenticity.
+
+Signature Creation:
+- Encode header and payload
+- Apply signing algorithm
+- Use secret (HS256) or private key (RS256)
+
+## Signing Algorithms
+
+### HS256 (Symmetric)
+
+Characteristics:
+- Single shared secret
+- Secret known by issuer and verifier
+- Simpler key management
+- Must protect secret carefully
+
+Use Cases:
+- Single application scenarios
+- Trusted environments
+- Simple implementations
+
+### RS256 (Asymmetric)
+
+Characteristics:
+- Public/private key pair
+- Private key signs, public key verifies
+- Public key can be shared freely
+- No secret sharing required
+
+Advantages:
+- Multiple verifiers without secret sharing
+- Key rotation without application changes
+- Better for distributed systems
+
+Auth0 Recommendation: Use RS256 for most scenarios.
+
+### Algorithm Comparison
+
+HS256:
+- Faster signing/verification
+- Simpler setup
+- Secret must be protected everywhere
+
+RS256:
+- Slower but more flexible
+- Only issuer has private key
+- Public key verification
+- Better for microservices
+
+## Validation
+
+### Signature Verification
+
+Steps:
+1. Decode header (base64url)
+2. Identify algorithm
+3. Get verification key (secret or public key)
+4. Verify signature mathematically
+
+### Claim Validation
+
+Required Checks:
+- exp: Token not expired
+- iss: Issuer matches expected value
+- aud: Audience includes your application
+
+Optional Checks:
+- nbf: Current time is after not-before
+- iat: Issued at time is reasonable
+- Custom claims as needed
+
+### Key Management
+
+For RS256:
+- Retrieve JWKS from issuer
+- Match kid (key ID) in header
+- Cache keys with appropriate TTL
+- Handle key rotation gracefully
+
+JWKS Endpoint: {your-domain}/.well-known/jwks.json
+
+## Security Considerations
+
+### Signed vs Encrypted
+
+Auth0 JWTs are Signed (JWS):
+- Signature verifies integrity
+- Content is NOT encrypted
+- Anyone can read payload
+- Only issuer can create valid signature
+
+JWE (Encrypted):
+- Content is encrypted
+- Requires decryption key
+- Used for sensitive data
+- More complex implementation
+
+### Security Best Practices
+
+Never Trust Unverified Tokens:
+- Always verify signature
+- Always check claims
+- Use established libraries
+
+Sensitive Data:
+- Never store sensitive data in JWT payload
+- Payload is only base64 encoded, not encrypted
+- Assume payload contents are public
+
+Transmission:
+- Always use HTTPS
+- Never include in URL parameters
+- Use Authorization header
+
+Algorithm Attacks:
+- Never accept "none" algorithm
+- Specify expected algorithm in verification
+- Use library that enforces algorithm
+
+## Common Vulnerabilities
+
+### Algorithm Confusion
+
+Attack: Changing RS256 to HS256 and using public key as secret.
+
+Prevention:
+- Explicitly specify expected algorithm
+- Use libraries that require algorithm specification
+
+### Token Injection
+
+Attack: Modifying payload and re-signing with weak key.
+
+Prevention:
+- Use strong keys
+- Validate all claims
+- Check issuer strictly
+
+### Replay Attacks
+
+Attack: Reusing captured tokens.
+
+Prevention:
+- Short expiration times
+- Use jti claim for uniqueness
+- Implement token binding (DPoP)
+
+## Implementation
+
+### Using Libraries
+
+Recommended:
+- Use official Auth0 SDKs
+- Use well-maintained JWT libraries
+- Avoid custom implementations
+
+Popular Libraries:
+- Node.js: jsonwebtoken, jose
+- Python: PyJWT, python-jose
+- Java: java-jwt, nimbus-jose-jwt
+- .NET: System.IdentityModel.Tokens.Jwt
+
+### Caching
+
+JWKS Caching:
+- Cache public keys
+- Set appropriate TTL
+- Invalidate on verification failure
+- Handle rotation gracefully
+
+Token Caching:
+- Cache validation results
+- Consider token lifetime
+- Invalidate on expiration
+
+## Auth0 Specifics
+
+### Token Signing
+
+Auth0 uses:
+- RS256 by default for ID tokens
+- Configurable per API for access tokens
+- Tenant-specific signing keys
+
+### JWKS Location
+
+Endpoint: https://{your-tenant}.auth0.com/.well-known/jwks.json
+
+Contains:
+- Public keys for verification
+- Key IDs for matching
+- Algorithm information
+
+### Key Rotation
+
+Auth0 rotates signing keys:
+- New key added to JWKS
+- Old key remains temporarily
+- Applications should handle multiple keys
+- Cache should handle rotation gracefully

moai_adk/templates/.claude/skills/moai-security-auth0/modules/mdl-verification.md

@@ -0,0 +1,211 @@
+# Mobile Driver's License Verification
+
+Module: moai-security-auth0/modules/mdl-verification.md
+Version: 1.0.0
+Last Updated: 2025-12-24
+
+---
+
+## Overview
+
+Auth0's Mobile Driver's License (mDL) Verification Service enables applications to validate Verifiable Credentials, specifically mobile driver's licenses. The service is designed for organizations needing to verify user credentials containing sensitive personally identifiable information (PII).
+
+Status: Early Access - Requires completion of Terms and Conditions form for enablement.
+
+---
+
+## Key Use Cases
+
+### Age Verification
+
+Verify that users meet minimum age requirements for age-restricted services or purchases.
+
+### License and Driving Privilege Validation
+
+Confirm that users hold valid driver's licenses with appropriate privileges.
+
+### Identity Verification
+
+Use driver's licenses as proof of identity, which is accepted in many countries.
+
+### KYC and AML Compliance
+
+Support Know Your Customer (KYC) and Anti-Money Laundering (AML) compliance processes with verified identity documents.
+
+---
+
+## How It Works
+
+### Verification Workflow
+
+Step 1: Application initiates a Verification Presentation Request via the mDL API.
+
+Step 2: API returns an engagement URI and Verification ID.
+
+Step 3: Application presents the URI to the user. QR code format is recommended for multi-device scenarios.
+
+Step 4: User opens their mobile wallet and consents to sharing their mDL credential.
+
+Step 5: Application polls the API to check presentation request status.
+
+Step 6: API returns the verification result with requested credential data.
+
+---
+
+## Technical Implementation
+
+### Integration Methods
+
+Direct API Integration: Embed the Mobile Driver's License Verification API directly into applications for full control.
+
+Low-Code Solution: Use Auth0 Forms as a pre-built interface for simpler implementation.
+
+### Configuration Requirements
+
+Verification Template Setup: Configure a Verification Template (VT) specifying which credential fields to request.
+
+Available Fields:
+- Date of birth
+- Address
+- Family name
+- Given name
+- Document number
+- Expiry date
+- Issuing authority
+
+API Configuration: Set up the Verifiable Digital Credential API through:
+- Auth0 Dashboard interface
+- Management API programmatic setup
+
+---
+
+## Compliance and Standards
+
+### ISO Standards
+
+The service references ISO/IEC TS 18013-7:2024 (REST API) standards for mobile driver's license verification.
+
+### Privacy Considerations
+
+Selective Disclosure: Users can consent to share only specific fields from their credential.
+
+Minimized Data Collection: Request only the fields necessary for your use case.
+
+Secure Transmission: All credential data is transmitted securely.
+
+---
+
+## Implementation Steps
+
+### Step 1: Enable the Service
+
+Contact Auth0 to complete the Early Access Terms and Conditions.
+
+Enable the mDL Verification Service in your tenant.
+
+### Step 2: Configure Verification Template
+
+Navigate to Dashboard then Credentials then Verification Templates.
+
+Create a new Verification Template.
+
+Specify the credential fields to request.
+
+Configure presentation requirements.
+
+### Step 3: Implement API Integration
+
+Initialize verification requests through the mDL API.
+
+Handle engagement URI presentation to users.
+
+Implement polling logic for verification status.
+
+Process verification results.
+
+### Step 4: Handle Verification Results
+
+Parse the returned credential data.
+
+Validate the verification status.
+
+Implement business logic based on verification outcome.
+
+Handle error cases appropriately.
+
+---
+
+## User Experience Considerations
+
+### QR Code Presentation
+
+For multi-device scenarios, present the engagement URI as a QR code.
+
+Users scan the QR code with their mobile device.
+
+Mobile wallet opens automatically for credential sharing.
+
+### Same-Device Flow
+
+For mobile applications, deep linking can open the wallet directly.
+
+Streamlined experience without QR code scanning.
+
+### Consent Flow
+
+Users explicitly consent to sharing credential data.
+
+Clear indication of which fields will be shared.
+
+Option to decline or cancel the verification.
+
+---
+
+## Security Best Practices
+
+Data Handling: Store and process credential data according to privacy regulations.
+
+Access Control: Limit access to verification results to authorized personnel.
+
+Audit Logging: Maintain logs of verification requests for compliance.
+
+Data Retention: Define and implement appropriate data retention policies.
+
+---
+
+## Error Handling
+
+### Common Scenarios
+
+User Declined: User chose not to share their credential.
+
+Credential Not Found: User does not have a compatible mDL.
+
+Verification Failed: Credential could not be verified.
+
+Timeout: Verification request expired before completion.
+
+### Recovery Actions
+
+Provide clear messaging to users about what went wrong.
+
+Offer alternative verification methods if available.
+
+Allow users to retry the verification process.
+
+---
+
+## Related Modules
+
+- compliance-overview.md: Compliance requirements
+- gdpr-compliance.md: Privacy considerations
+- highly-regulated-identity.md: Regulated identity features
+
+---
+
+## Resources
+
+Auth0 Documentation: Mobile Driver's License Verification
+Auth0 Documentation: Verifiable Credentials
+ISO/IEC TS 18013-7:2024: mDL REST API Specification
+Context7 Library: /auth0/auth0-docs (topic: mdl-verification)