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

moai_adk/templates/.claude/skills/moai-platform-auth0/modules/state-parameters.md

@@ -0,0 +1,177 @@
+# OAuth 2.0 State Parameters
+
+Module: moai-platform-auth0/modules/state-parameters.md
+Version: 1.0.0
+Last Updated: 2025-12-24
+
+---
+
+## Overview
+
+The OAuth 2.0 state parameter is a critical security mechanism that protects against Cross-Site Request Forgery (CSRF) attacks and enables post-authentication redirect handling. Proper implementation of state parameters is essential for secure authentication flows.
+
+---
+
+## CSRF Protection
+
+### Primary Purpose
+
+The primary reason for using the state parameter is to mitigate CSRF attacks by using a unique and non-guessable value associated with each authentication request.
+
+### How CSRF Attacks Work
+
+Attacker Scenario: An attacker tricks a user's browser into making an authentication request without the user's knowledge.
+
+Without State Parameter: The application cannot distinguish between legitimate and forged authentication responses.
+
+With State Parameter: The application can verify that the response corresponds to a request it initiated.
+
+### Implementation Process
+
+Step 1 - Generate Random String: Before redirecting to the Identity Provider, generate a cryptographically secure random string (for example, xyzABC123).
+
+Step 2 - Store Locally: Store the generated value in cookies, sessions, or local storage depending on application type.
+
+Step 3 - Include in Request: Add the state parameter to the authorization request URL.
+
+Step 4 - Validate on Return: When receiving the authentication response, compare the returned state value with the stored value.
+
+### Validation Logic
+
+If the returned state matches the stored value: The response is legitimate, proceed with authentication.
+
+If the returned state does not match: You may be the target of an attack because this is either a response for an unsolicited request or someone trying to forge the response. Reject the authentication attempt.
+
+---
+
+## Redirect Users Post-Authentication
+
+### Context Preservation
+
+The state parameter can preserve application context across the authentication flow.
+
+Use Case: User attempts to access a protected resource, gets redirected to authenticate, and should return to the original resource after authentication.
+
+### Implementation
+
+Encode Information: Include the intended destination URL alongside the nonce in the state parameter.
+
+After Validation: Extract the destination URL from the state and redirect the user accordingly.
+
+Example Structure: The state value might contain both a random nonce and an encoded destination path.
+
+---
+
+## Storage Recommendations
+
+Storage method depends on application type:
+
+Regular Web Applications: Use server-side session storage or signed cookies.
+
+Single-Page Applications: Use browser local storage with appropriate security measures.
+
+Native Applications: Use device memory or secure local storage.
+
+---
+
+## Security Requirements
+
+### State Value Characteristics
+
+Uniqueness: Each authentication request must have a unique state value.
+
+Opacity: State values should not be predictable or guessable.
+
+Sufficient Entropy: Use cryptographically secure random number generators.
+
+### Cookie-Based Storage Security
+
+Signed Cookies: When storing state in cookies, sign the cookie to prevent tampering.
+
+HttpOnly: Consider HttpOnly flag to prevent JavaScript access.
+
+Secure: Use Secure flag to ensure transmission only over HTTPS.
+
+SameSite: Configure SameSite attribute appropriately.
+
+### URL Encoding Security
+
+Avoid Plaintext: Do not use plaintext or predictable encoding for stored URLs.
+
+Encryption: Consider encrypting sensitive redirect URLs.
+
+Length Limits: Be aware that excessively long state values may trigger 414 Request-URI Too Large errors.
+
+---
+
+## Implementation Examples
+
+### Authorization Request
+
+When constructing the authorization URL:
+
+Include the state parameter with the generated random value.
+
+Store the corresponding value locally before redirecting.
+
+Ensure the state is URL-encoded if it contains special characters.
+
+### Response Handling
+
+When receiving the authorization response:
+
+Extract the state parameter from the response.
+
+Retrieve the stored state value.
+
+Compare the values for exact match.
+
+Only proceed if values match.
+
+---
+
+## Common Mistakes to Avoid
+
+Reusing State Values: Each authentication request needs a fresh state value.
+
+Weak Random Generation: Use cryptographically secure random generators, not Math.random().
+
+Not Validating State: Always validate the returned state, never skip this step.
+
+Storing State Insecurely: Protect stored state values from unauthorized access.
+
+Predictable Patterns: Avoid using timestamps or sequential numbers as state values.
+
+---
+
+## Error Handling
+
+### Missing State Parameter
+
+If the authorization response lacks a state parameter but one was sent, treat as a potential attack.
+
+### State Mismatch
+
+Log the mismatch for security monitoring.
+
+Do not complete the authentication.
+
+Display an appropriate error message to the user.
+
+Consider implementing rate limiting if mismatches occur frequently.
+
+---
+
+## Related Modules
+
+- attack-protection-overview.md: Overall attack protection strategy
+- tokens-overview.md: Token security
+- application-credentials.md: Application security
+
+---
+
+## Resources
+
+Auth0 Documentation: State Parameter
+Auth0 Documentation: Prevent Attacks with State Parameters
+OAuth 2.0 RFC 6749: State Parameter Specification

moai_adk/templates/.claude/skills/moai-platform-auth0/modules/step-up-authentication.md

@@ -0,0 +1,251 @@
+# Step-Up Authentication
+
+Step-up authentication requires users to authenticate with stronger credentials when accessing sensitive resources, adding security without impacting the entire user experience.
+
+## Concept
+
+Step-up authentication allows applications to:
+- Grant initial access with standard authentication
+- Require additional verification for sensitive operations
+- Dynamically elevate authentication level
+- Protect high-risk transactions
+
+## Use Cases
+
+Financial Applications:
+- View account balance: Standard login
+- Transfer funds: Require MFA
+- Change beneficiary: Require MFA + verification
+
+Healthcare Applications:
+- View appointments: Standard login
+- Access medical records: Require MFA
+- Download prescriptions: Require MFA
+
+E-commerce Applications:
+- Browse products: No authentication
+- View order history: Standard login
+- Change payment method: Require MFA
+
+Administrative Applications:
+- View dashboard: Standard login
+- Modify user permissions: Require MFA
+- Access audit logs: Require MFA
+
+## Implementation Approaches
+
+### API-Based Step-Up (Scopes)
+
+For applications with API backends:
+
+Mechanism:
+- Map sensitive operations to specific scopes
+- Include scope in access token requests
+- API validates scope presence
+- Trigger MFA when scope requires elevation
+
+Flow:
+1. User performs standard login
+2. Access token contains basic scopes
+3. User attempts sensitive operation
+4. Application requests elevated scope
+5. Auth0 triggers MFA challenge
+6. User completes MFA
+7. New access token contains elevated scope
+8. API authorizes sensitive operation
+
+Scope Examples:
+- read:balance (standard)
+- transfer:funds (requires MFA)
+- admin:users (requires MFA)
+
+### Web Application Step-Up (Token Claims)
+
+For traditional web applications:
+
+Mechanism:
+- Verify authentication level through ID token claims
+- Check for MFA completion in token
+- Redirect to MFA if not present
+- Grant access after verification
+
+Claims to Check:
+- acr (Authentication Context Class Reference)
+- amr (Authentication Methods Reference)
+- Custom claims set by Actions
+
+Flow:
+1. User performs standard login
+2. ID token contains authentication claims
+3. User navigates to sensitive page
+4. Application checks token claims
+5. If MFA not present, redirect to re-authentication
+6. Auth0 prompts for MFA
+7. New ID token contains MFA claims
+8. Application grants access
+
+## Implementation with Actions
+
+### Triggering Step-Up
+
+Use post-login Actions to enforce MFA for specific conditions:
+
+Condition Examples:
+- Specific scope requested
+- Sensitive application accessed
+- High-risk operation detected
+- Elevated privilege requested
+
+Action Logic:
+- Check requested scopes
+- Evaluate risk context
+- Challenge with MFA if needed
+- Add custom claims to tokens
+
+### Custom Claims
+
+Add claims indicating authentication strength:
+- mfa_completed: boolean
+- auth_level: numeric
+- auth_methods: array
+
+These claims enable applications to verify authentication status without additional API calls.
+
+## Token Validation
+
+### Access Token Validation
+
+For API step-up:
+- Validate token signature
+- Check scope claims
+- Verify audience
+- Confirm token freshness
+
+Scope Verification:
+- Extract scope claim
+- Check for required scope
+- Deny if scope missing
+- Consider scope hierarchies
+
+### ID Token Validation
+
+For web app step-up:
+- Validate token signature
+- Check authentication claims
+- Verify token freshness
+- Confirm claim values
+
+Claim Verification:
+- Extract acr/amr claims
+- Check for MFA indicators
+- Verify claim currency
+- Deny if requirements not met
+
+## Freshness Requirements
+
+Token Age Considerations:
+- Step-up may require fresh authentication
+- Stale tokens may not reflect current context
+- Consider max_age parameter for re-authentication
+
+Implementing Freshness:
+- Check iat (issued at) claim
+- Require token issued within threshold
+- Force re-authentication if too old
+- Balance security with user experience
+
+## User Experience
+
+Seamless Step-Up:
+- Clear explanation of why additional verification needed
+- Quick MFA completion
+- Return to original context after verification
+- Remember step-up for session duration
+
+Error Handling:
+- Clear messages for MFA failures
+- Fallback factor options
+- Support contact information
+- Graceful degradation
+
+Session Management:
+- Track step-up status in session
+- Appropriate timeout for elevated sessions
+- Clear elevation on logout
+- Optional elevation expiry
+
+## Security Considerations
+
+Transaction Binding:
+- Bind MFA to specific transaction
+- Display transaction details during approval
+- Prevent transaction manipulation
+- Log transaction context
+
+Rate Limiting:
+- Limit step-up attempts
+- Prevent MFA fatigue attacks
+- Monitor unusual patterns
+- Alert on suspicious activity
+
+Scope Escalation Prevention:
+- Validate scope transitions
+- Prevent unauthorized elevation
+- Audit scope requests
+- Monitor privilege changes
+
+## Best Practices
+
+Scope Design:
+- Clear scope hierarchy
+- Consistent naming convention
+- Documented scope requirements
+- Regular scope review
+
+User Communication:
+- Explain step-up requirement
+- Provide context for verification
+- Offer help resources
+- Consistent messaging
+
+Implementation:
+- Server-side enforcement
+- Never trust client-only checks
+- Comprehensive logging
+- Regular security review
+
+Testing:
+- Test all step-up scenarios
+- Verify scope enforcement
+- Check error handling
+- Validate token claims
+
+## Example Scenarios
+
+### Banking Step-Up
+
+Initial Login:
+- User logs in with password
+- Receives basic access token
+- Can view balances and statements
+
+Fund Transfer:
+- User initiates transfer
+- Application requests transfer:funds scope
+- Auth0 challenges with MFA
+- User approves via Guardian
+- Transfer completes
+
+### Admin Console Step-Up
+
+Initial Access:
+- Admin logs in with SSO
+- Can view dashboard and reports
+- Basic admin privileges
+
+User Management:
+- Admin accesses user management
+- System checks ID token claims
+- MFA not present, redirects to step-up
+- Admin completes MFA
+- User management access granted

moai_adk/templates/.claude/skills/moai-platform-auth0/modules/suspicious-ip-throttling.md

@@ -0,0 +1,240 @@
+# Suspicious IP Throttling
+
+Auth0 Suspicious IP Throttling automatically blocks traffic from IP addresses exhibiting high-velocity login or signup attempts, protecting against large-scale automated attacks.
+
+## How It Works
+
+The system tracks login and signup attempt velocity per IP address. When an address exceeds configured thresholds, Auth0 throttles subsequent attempts by responding with HTTP 429 (Too Many Requests) status codes.
+
+This protection is enabled by default on new tenants.
+
+## Velocity Detection Mechanisms
+
+### Login Attempt Tracking
+
+Monitoring Period: Daily (24-hour rolling window)
+
+Detection Logic:
+- Counts failed login attempts per IP address
+- Threshold based on total failures across all accounts
+- Does not require targeting specific account
+
+Throttling Behavior:
+- Once threshold exceeded, throttling activates
+- Allowed attempts distributed evenly across 24 hours
+- Example: Throttling rate of 100 grants approximately one attempt every 15 minutes
+
+### Signup Attempt Tracking
+
+Monitoring Period: Per minute
+
+Detection Logic:
+- Counts all signup attempts (successful and failed)
+- Threshold based on attempts within one-minute window
+- Triggers on high-velocity account creation
+
+Throttling Behavior:
+- When limit exceeded, further signups blocked
+- Throttling rate distributes attempts over 24 hours
+- Example: Rate of 72,000 allows roughly one attempt per second
+
+## Configuration
+
+### Dashboard Navigation
+
+Access: Dashboard > Security > Attack Protection > Suspicious IP Throttling
+
+### Threshold Settings
+
+Login Thresholds:
+- Maximum failed login attempts per day
+- Throttling rate (attempts allowed per 24 hours after blocking)
+
+Signup Thresholds:
+- Maximum signup attempts per minute
+- Throttling rate for signup after blocking
+
+### IP AllowList
+
+Add trusted IP sources to exempt from throttling:
+- Up to 100 IP addresses or CIDR ranges
+- Useful for automated testing systems
+- Protects known-good high-volume sources
+
+### Response Configuration
+
+Enable Traffic Limiting:
+- Activates HTTP 429 responses
+- Required for active protection
+
+Administrator Notifications:
+- Email alerts when thresholds exceeded
+- Configurable notification settings
+
+Monitoring Mode:
+- Disable all response actions
+- Events still logged
+- Useful for threshold calibration
+
+## HTTP 429 Response
+
+When throttled, requests receive:
+
+Status: 429 Too Many Requests
+
+Response includes:
+- Error description
+- Retry-after guidance
+- Rate limit information
+
+Client Handling:
+- Implement exponential backoff
+- Display user-friendly message
+- Avoid immediate retries
+
+## Important Considerations
+
+### What Does Not Count
+
+These request types do not increment thresholds:
+- Malformed requests
+- Schema validation errors
+- Requests from AllowListed IPs
+- Successful authentications (for login tracking)
+
+### Backend Applications
+
+For Resource Owner Password Grant:
+- Auth0 sees application server IP, not user IP
+- Must manually pass client IP via auth0-forwarded-for header
+- Without this, all users appear from same IP
+
+Implementation:
+- Extract client IP from X-Forwarded-For or similar
+- Include in auth0-forwarded-for header
+- Ensure proper IP extraction behind proxies
+
+### Shared IP Environments
+
+Organizations behind NAT or proxies:
+- All users share same public IP
+- More likely to trigger throttling
+- Consider higher thresholds or AllowList
+
+Mobile Networks:
+- Carrier NAT shares IP across subscribers
+- Geographic IP pools may appear suspicious
+- Consider mobile-specific thresholds
+
+## Monitoring and Metrics
+
+### Security Center
+
+Access: Dashboard > Security > Security Center
+
+Available Metrics:
+- Throttling events over time
+- Top throttled IPs
+- Geographic distribution
+- Attack pattern analysis
+
+### Tenant Logs
+
+Event Types:
+- Rate limit exceeded events
+- Throttling trigger events
+- IP blocking/unblocking
+
+Log Details:
+- Source IP address
+- Attempt counts
+- Threshold exceeded
+- Action taken
+
+## Integration with Attack Protection
+
+Layered with Bot Detection:
+- Bot detection evaluates request patterns
+- Suspicious IP throttling evaluates velocity
+- Both can trigger on same request
+
+Layered with Brute Force Protection:
+- Suspicious IP tracks across all accounts
+- Brute force tracks per account per IP
+- Different protection scopes
+
+## Best Practices
+
+### Initial Configuration
+
+1. Enable in monitoring mode
+2. Analyze baseline traffic patterns
+3. Identify high-volume legitimate sources
+4. Configure AllowList for trusted IPs
+5. Enable throttling with conservative thresholds
+6. Monitor false positive rate
+7. Adjust thresholds based on data
+
+### Threshold Selection
+
+Conservative (More Protection):
+- Lower thresholds
+- Faster throttling response
+- May impact legitimate high-volume users
+
+Permissive (Better UX):
+- Higher thresholds
+- Allow more attempts before throttling
+- Less protection against sophisticated attacks
+
+### For Different Application Types
+
+Consumer Applications:
+- Moderate login threshold
+- Higher signup threshold (organic growth periods)
+- Monitor for registration spam
+
+Enterprise Applications:
+- Lower thresholds acceptable
+- AllowList corporate IP ranges
+- Integrate with enterprise identity providers
+
+API-Heavy Applications:
+- Higher thresholds for legitimate API usage
+- AllowList application server IPs
+- Ensure auth0-forwarded-for header implementation
+
+### Ongoing Management
+
+Regular Reviews:
+- Check throttling events weekly
+- Identify new legitimate high-volume sources
+- Update AllowList as needed
+
+Attack Response:
+- Review attack patterns
+- Adjust thresholds temporarily if needed
+- Document attack characteristics
+
+Threshold Tuning:
+- Balance security with user experience
+- Consider seasonal traffic variations
+- Account for growth in user base
+
+## Troubleshooting
+
+Legitimate Traffic Throttled:
+- Add IP to AllowList
+- Increase thresholds
+- Check for auth0-forwarded-for header issues
+
+Throttling Not Triggering:
+- Verify feature is enabled
+- Check if IP is AllowListed
+- Confirm threshold configuration
+- Review request patterns
+
+429 Errors Not Handled:
+- Implement proper error handling in client
+- Add retry logic with backoff
+- Display appropriate user message