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/mfa-api-management.md

@@ -0,0 +1,278 @@
+# MFA API Management
+
+Manage multi-factor authentication programmatically using Auth0 Management API and Authentication API for enrollments, factors, and user MFA settings.
+
+## Management API Operations
+
+### List User Enrollments
+
+Retrieve all MFA enrollments for a user.
+
+Endpoint: GET /api/v2/users/{user_id}/enrollments
+
+Response includes:
+- Enrollment ID
+- Factor type
+- Status (confirmed, pending)
+- Enrollment date
+- Device information
+
+### Delete User Enrollment
+
+Remove a specific MFA enrollment.
+
+Endpoint: DELETE /api/v2/users/{user_id}/enrollments/{enrollment_id}
+
+Use cases:
+- User lost device
+- Factor replacement
+- Security incident response
+
+### Reset User MFA
+
+Remove all MFA enrollments for a user.
+
+Endpoint: DELETE /api/v2/users/{user_id}/authenticators
+
+Effect:
+- Removes all enrolled factors
+- User must re-enroll on next MFA challenge
+- Recovery codes invalidated
+
+### Generate Recovery Codes
+
+Create new recovery codes for a user.
+
+Endpoint: POST /api/v2/users/{user_id}/recovery-code-regeneration
+
+Response:
+- New recovery codes array
+- Previous codes invalidated
+- User must store new codes
+
+## Authentication API Operations
+
+### MFA Challenge
+
+Initiate MFA challenge during authentication.
+
+Endpoint: POST /oauth/token (with mfa_token)
+
+Parameters:
+- mfa_token: Token from initial authentication
+- challenge_type: Factor type to challenge
+- authenticator_id: Specific enrollment (optional)
+
+### MFA OOB Challenge
+
+Initiate out-of-band challenge (push, SMS).
+
+Endpoint: POST /mfa/challenge
+
+Parameters:
+- mfa_token: MFA session token
+- challenge_type: oob
+- authenticator_id: Enrollment ID
+- oob_channel: push, sms, or voice
+
+### Verify MFA
+
+Complete MFA verification.
+
+Endpoint: POST /oauth/token
+
+Parameters:
+- grant_type: mfa-oob or mfa-otp
+- mfa_token: MFA session token
+- otp: One-time password (for TOTP)
+- oob_code: Out-of-band code (for SMS)
+- binding_code: Push notification code
+
+## Enrollment Management
+
+### Programmatic Enrollment
+
+Enroll user in MFA factor via API.
+
+Steps:
+1. Get enrollment ticket via Management API
+2. Generate enrollment data (QR, secret)
+3. Present to user for enrollment
+4. Confirm enrollment
+
+### Enrollment Verification
+
+Confirm pending enrollment.
+
+Endpoint: POST /mfa/associate
+
+Parameters:
+- mfa_token: Association token
+- otp: Verification code from new factor
+
+### List Available Factors
+
+Get configured MFA factors for tenant.
+
+Endpoint: GET /api/v2/guardian/factors
+
+Response includes:
+- Factor type
+- Enabled status
+- Configuration details
+
+## Factor-Specific APIs
+
+### Guardian (Push)
+
+Send push notification:
+- Endpoint handles notification delivery
+- Response includes challenge ID
+- Poll or webhook for response
+
+Guardian enrollment:
+- Generate enrollment ticket
+- Create QR code for app scanning
+- Confirm via app acknowledgment
+
+### SMS/Voice
+
+Send verification code:
+- Endpoint triggers message delivery
+- Code valid for limited time
+- Rate limiting applies
+
+### TOTP
+
+Generate secret:
+- Create TOTP secret for enrollment
+- Encode as QR code or manual entry
+- Verify initial OTP to confirm
+
+### WebAuthn
+
+Create credential options:
+- Generate challenge
+- Define allowed authenticators
+- Set user verification requirement
+
+Verify credential:
+- Validate authenticator assertion
+- Confirm credential binding
+- Store public key
+
+## User Self-Service
+
+### Enable User MFA Management
+
+Allow users to manage their own MFA:
+- View enrolled factors
+- Add new factors
+- Remove factors
+- Generate recovery codes
+
+### Implementation
+
+User MFA Portal:
+- Build custom UI or use Auth0 dashboard
+- Call Management API with user token
+- Implement proper authorization
+- Audit user actions
+
+## Administrative Operations
+
+### Bulk MFA Reset
+
+Reset MFA for multiple users:
+- Export affected user list
+- Iterate with Management API
+- Log reset actions
+- Communicate to users
+
+### MFA Enforcement
+
+Require MFA enrollment:
+- Use Rules or Actions
+- Check enrollment status
+- Redirect to enrollment if missing
+- Allow grace period if needed
+
+### Audit MFA Events
+
+Track MFA-related activities:
+- Enrollment events
+- Authentication events
+- Reset events
+- Failure events
+
+## Error Handling
+
+### Common Errors
+
+mfa_required:
+- User needs to complete MFA
+- Provide mfa_token for challenge flow
+- Redirect to MFA flow
+
+invalid_otp:
+- OTP verification failed
+- May be expired or incorrect
+- Allow retry with rate limiting
+
+enrollment_not_found:
+- Requested enrollment does not exist
+- May be deleted or invalid ID
+- Handle gracefully
+
+rate_limited:
+- Too many MFA attempts
+- Implement backoff
+- Inform user of wait time
+
+### Error Response Handling
+
+Implement proper error handling:
+- Parse error codes
+- Display user-friendly messages
+- Log for debugging
+- Alert on suspicious patterns
+
+## Security Considerations
+
+API Access:
+- Use appropriate API permissions
+- Implement rate limiting
+- Audit API usage
+- Rotate API credentials
+
+Token Handling:
+- MFA tokens are short-lived
+- Do not log sensitive tokens
+- Secure token storage
+- Implement proper expiration
+
+User Authorization:
+- Verify user identity before MFA changes
+- Require current authentication
+- Log administrative actions
+- Alert on suspicious changes
+
+## Best Practices
+
+Implementation:
+- Use official SDKs when available
+- Implement proper error handling
+- Test all edge cases
+- Monitor API usage
+
+User Experience:
+- Clear error messages
+- Helpful enrollment guidance
+- Fallback options available
+- Support documentation
+
+Security:
+- Audit all MFA operations
+- Alert on mass resets
+- Monitor for abuse patterns
+- Regular security review

moai_adk/templates/.claude/skills/moai-platform-auth0/modules/mfa-factors.md

@@ -0,0 +1,226 @@
+# MFA Factors
+
+Detailed reference for all Auth0 multi-factor authentication factors including configuration and implementation guidance.
+
+## Independent Factors
+
+### WebAuthn with Security Keys
+
+Physical security keys providing phishing-resistant authentication.
+
+Supported Standards:
+- FIDO2
+- WebAuthn
+- U2F (backward compatibility)
+
+Compatible Devices:
+- YubiKey series
+- Feitian keys
+- Google Titan
+- Other FIDO2-compliant keys
+
+Configuration:
+- Enable in MFA settings
+- Optionally require PIN verification
+- Configure user verification level
+
+User Experience:
+- Insert or tap security key
+- Enter PIN if required
+- Complete biometric if supported
+
+### One-Time Password (TOTP)
+
+Time-based codes generated by authenticator apps.
+
+Compatible Applications:
+- Google Authenticator
+- Microsoft Authenticator
+- Authy
+- 1Password
+- Any TOTP-compatible app
+
+Configuration:
+- Standard 6-digit codes
+- 30-second refresh interval
+- QR code or manual entry setup
+
+User Experience:
+- Scan QR code during enrollment
+- Enter 6-digit code from app
+- Code refreshes every 30 seconds
+
+### Push Notifications (Guardian)
+
+Mobile app notifications for one-tap authentication.
+
+Requirements:
+- Auth0 Guardian app or custom Guardian SDK app
+- iOS or Android device
+- Internet connectivity
+
+Configuration:
+- Enable Guardian factor
+- Choose notification service (AWS SNS, FCM, APN)
+- Configure application branding
+
+User Experience:
+- Receive push notification
+- View transaction context
+- Approve or deny with one tap
+
+### Phone Message (SMS/Voice)
+
+Verification codes delivered via SMS or voice call.
+
+SMS Verification:
+- 6-digit code via text message
+- Works with any mobile phone
+- Requires phone number verification
+
+Voice Verification:
+- Automated call with spoken code
+- Fallback when SMS unavailable
+- Accessibility consideration
+
+Configuration:
+- Enable Phone Message factor
+- Configure SMS provider (Twilio, etc.)
+- Set voice call as fallback
+
+Limitations:
+- SIM swapping vulnerability
+- Delivery delays possible
+- International coverage varies
+
+### Cisco Duo Security
+
+Integration with Cisco Duo platform.
+
+Requirements:
+- Existing Cisco Duo account
+- Duo API credentials
+- Enterprise plan recommended
+
+Configuration:
+- Configure Duo integration
+- Set API credentials
+- Map Duo policies
+
+User Experience:
+- Duo prompt appears
+- Use Duo Push, call, or passcode
+- Consistent with other Duo-protected apps
+
+## Dependent Factors
+
+### WebAuthn with Device Biometrics
+
+Platform authenticators using built-in device biometrics.
+
+Supported Platforms:
+- Face ID (iOS)
+- Touch ID (iOS/macOS)
+- Windows Hello
+- Android Fingerprint
+
+Requirements:
+- User verification capability
+- Platform authenticator support
+- Biometric enrollment on device
+
+User Experience:
+- Prompted for biometric
+- Face scan or fingerprint
+- Seamless verification
+
+Note: Requires independent factor enrolled first.
+
+### Email Verification
+
+One-time codes delivered via email.
+
+Configuration:
+- Enable Email factor
+- Configure email provider
+- Customize email template
+
+User Experience:
+- Receive email with code
+- Enter code in application
+- Limited validity period
+
+Use Cases:
+- Backup factor
+- Low-security scenarios
+- Users without smartphones
+
+### Recovery Codes
+
+Pre-generated backup codes for emergency access.
+
+Characteristics:
+- Set of single-use codes
+- Generated during enrollment
+- User must store securely
+
+Configuration:
+- Enable Recovery Codes factor
+- Configure code count (typically 10)
+- Set regeneration policy
+
+User Experience:
+- Receive codes during enrollment
+- Download or print codes
+- Enter one code when needed
+- Each code works once only
+
+Best Practices:
+- Encourage secure storage
+- Remind users to regenerate after use
+- Provide clear usage instructions
+
+## Factor Selection Strategy
+
+High Security Applications:
+- WebAuthn security keys as primary
+- TOTP as backup
+- Recovery codes for emergency
+
+Consumer Applications:
+- Push notifications for convenience
+- SMS as fallback
+- Recovery codes optional
+
+Enterprise Applications:
+- Cisco Duo for unified security
+- WebAuthn for phishing resistance
+- TOTP for compatibility
+
+Mobile-First Applications:
+- Push notifications primary
+- Device biometrics secondary
+- SMS fallback
+
+## Factor Comparison
+
+Security Ranking (highest to lowest):
+1. WebAuthn Security Keys
+2. WebAuthn Device Biometrics
+3. Push Notifications
+4. TOTP
+5. SMS/Voice
+6. Email
+
+Convenience Ranking (highest to lowest):
+1. Device Biometrics
+2. Push Notifications
+3. Security Keys (with biometric)
+4. TOTP
+5. SMS
+6. Email
+
+Phishing Resistance:
+- WebAuthn: High resistance
+- Push with context: Moderate resistance
+- TOTP/SMS/Email: No resistance

moai_adk/templates/.claude/skills/moai-platform-auth0/modules/mfa-overview.md

@@ -0,0 +1,174 @@
+# Multi-Factor Authentication Overview
+
+Auth0 Multi-Factor Authentication (MFA) is a user verification method requiring more than one type of validation, preventing unauthorized access even when credentials are compromised.
+
+## Why Use MFA
+
+MFA reduces cyber-attack likelihood by adding verification layers beyond passwords. Even if an attacker obtains a password, they cannot access the account without the additional factor(s).
+
+## Supported MFA Factors
+
+Auth0 supports multiple authentication methods categorized as independent and dependent factors.
+
+### Independent Factors
+
+At least one independent factor must be enabled. These can be used alone for MFA.
+
+WebAuthn with FIDO Security Keys:
+- Physical security keys (YubiKey, etc.)
+- FIDO2/U2F standard compliance
+- Phishing-resistant authentication
+
+One-Time Password (OTP/TOTP):
+- Time-based one-time passwords
+- Compatible with authenticator apps
+- Google Authenticator, Authy, etc.
+
+Push Notifications (Auth0 Guardian):
+- Mobile app push notifications
+- One-tap approval/denial
+- Rich notification with context
+
+Phone Message:
+- SMS verification codes
+- Voice call verification
+- Fallback for non-smartphone users
+
+Cisco Duo Security:
+- Enterprise Duo integration
+- Existing Duo infrastructure support
+- Unified security platform
+
+### Dependent Factors
+
+Require an independent factor to be configured first.
+
+WebAuthn with Device Biometrics:
+- Face ID, Touch ID, Windows Hello
+- Device-bound authentication
+- Convenient for enrolled devices
+
+Email Verification:
+- One-time codes via email
+- Backup verification method
+- Works across all devices
+
+Recovery Codes:
+- Pre-generated backup codes
+- Use when primary factors unavailable
+- One-time use per code
+
+## MFA Policies
+
+Configure when MFA is required.
+
+Never:
+- MFA not required
+- Users can optionally enroll
+- Lowest security, highest convenience
+
+Always:
+- MFA required for every login
+- All users must complete MFA
+- Highest security, more friction
+
+Use Adaptive MFA (Enterprise):
+- Risk-based MFA challenges
+- Only challenges when risk detected
+- Balance of security and convenience
+
+## Configuration
+
+### Dashboard Navigation
+
+Access: Dashboard > Security > Multi-factor Auth
+
+### Basic Setup
+
+1. Navigate to MFA settings
+2. Enable desired factors in Factors section
+3. Select MFA policy
+4. Configure additional settings
+
+### Additional Settings
+
+Show Multi-factor Authentication Options:
+- Lets users select from enabled factors during enrollment
+- Provides factor choice flexibility
+
+Customize MFA Factors using Actions:
+- Create personalized MFA flows via post-login Actions
+- Implement custom logic for factor selection
+- Challenge with specific factor sequences
+
+### Factor Enrollment
+
+User Enrollment Flow:
+- First-time MFA triggers enrollment
+- User selects from available factors
+- Completes factor-specific setup
+- Future logins use enrolled factor
+
+Administrative Enrollment:
+- Pre-enroll users via Management API
+- Import existing MFA enrollments
+- Bulk enrollment for organizations
+
+## Implementation Approaches
+
+### Universal Login MFA
+
+Recommended approach using Auth0-hosted login:
+- Automatic MFA integration
+- Consistent user experience
+- No custom UI development required
+
+### Custom MFA with Actions
+
+Use post-login Actions for custom logic:
+- Conditional MFA based on user attributes
+- Geographic or device-based challenges
+- Custom factor sequencing
+- Integration with external risk systems
+
+### Embedded MFA
+
+For custom applications:
+- Auth0.js SDK integration
+- Custom UI implementation
+- Direct API calls for MFA operations
+
+## Plan Requirements
+
+Professional Plan:
+- Standard MFA factors
+- Basic policy configuration
+
+Enterprise Plan:
+- All MFA factors
+- Adaptive MFA
+- Guardian customization
+- Advanced Actions support
+
+## Best Practices
+
+Factor Selection:
+- Enable multiple factors for user choice
+- Provide recovery codes as backup
+- Consider user device capabilities
+
+User Experience:
+- Clear enrollment instructions
+- Factor-specific guidance
+- Fallback options when factors fail
+
+Security Balance:
+- Use Adaptive MFA when possible
+- Avoid MFA fatigue with smart policies
+- Regularly audit enrolled factors
+
+Deployment:
+- Pilot with subset of users
+- Gradual rollout with communication
+- Monitor enrollment and success rates
+- Provide support resources