moai-adk 0.35.1__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-plugin-builder/validation.md

@@ -0,0 +1,373 @@
+# Plugin Validation Guide
+
+## Validation Commands
+
+### CLI Validation
+
+Basic Validation:
+```bash
+claude plugin validate ./my-plugin
+```
+
+Verbose Validation:
+```bash
+claude plugin validate ./my-plugin --verbose
+```
+
+Strict Mode:
+```bash
+claude plugin validate ./my-plugin --strict
+```
+
+### Validation Output
+
+Success Output:
+```
+Plugin validation passed: my-plugin
+  - plugin.json: valid
+  - commands: 3 found
+  - agents: 2 found
+  - skills: 1 found
+  - hooks: valid
+```
+
+Error Output:
+```
+Plugin validation failed: my-plugin
+  ERROR: plugin.json missing required field 'name'
+  ERROR: commands/invalid.md missing frontmatter
+  WARNING: agent tools reference unknown tool 'CustomTool'
+```
+
+## Validation Rules by Component
+
+### plugin.json Validation
+
+Required Checks:
+- File exists at .claude-plugin/plugin.json
+- Valid JSON syntax
+- Contains "name" field
+- Name is kebab-case format
+
+Name Validation:
+- Lowercase letters, numbers, hyphens only
+- Must start with letter
+- No consecutive hyphens
+- Maximum 64 characters
+
+Optional Field Checks:
+- version: Valid semver (X.Y.Z)
+- author.email: Valid email format
+- author.url: Valid URL
+- homepage: Valid URL
+- repository: Valid URL
+- license: Valid SPDX identifier
+- keywords: Array of strings
+
+Path Reference Checks:
+- All paths start with "./"
+- Referenced paths exist
+- No path traversal (..)
+- Paths are relative to plugin root
+
+### Command Validation
+
+File Requirements:
+- Extension is .md
+- File is readable
+- File is not empty
+
+Frontmatter Validation:
+- YAML frontmatter present (between --- delimiters)
+- Contains description field
+- Description is non-empty string
+
+Content Validation:
+- Body content exists after frontmatter
+- No syntax errors in markdown
+- Argument references are valid ($1, $2, $ARGUMENTS)
+
+### Agent Validation
+
+File Requirements:
+- Extension is .md
+- File is readable
+
+Frontmatter Validation:
+- Contains name field
+- Name is valid identifier
+- Description is present (recommended)
+
+Tool Validation:
+- All listed tools are valid tool names
+- Valid tools: Read, Write, Edit, Grep, Glob, Bash, WebFetch, WebSearch, Task, TodoWrite
+
+Model Validation:
+- If specified, must be: sonnet, opus, haiku, inherit
+- Default is inherit
+
+Permission Mode Validation:
+- If specified, must be: default, bypassPermissions, plan, passthrough
+- Default is default
+
+Skill References:
+- Referenced skills exist in plugin or project
+- Skill names are valid identifiers
+
+### Skill Validation
+
+Directory Requirements:
+- Skill directory exists
+- SKILL.md file present in directory
+
+Frontmatter Validation:
+- Contains name field
+- Contains description field
+- allowed-tools contains valid tool names
+
+Content Validation:
+- File is under 500 lines
+- Contains Quick Reference section
+- Contains Implementation Guide section
+
+### Hook Validation
+
+File Requirements:
+- hooks.json is valid JSON
+- hooks.json contains "hooks" object
+
+Event Validation:
+- Event names are valid hook events
+- Valid events: PreToolUse, PostToolUse, PermissionRequest, UserPromptSubmit, SessionStart, SessionEnd, Stop, SubagentStop, Notification, PreCompact
+
+Hook Entry Validation:
+- Each entry has valid structure
+- Matcher is string or array
+- hooks array is present
+
+Hook Definition Validation:
+- type is "command" or "prompt"
+- If command: command field is string
+- If prompt: prompt field is string
+
+Command Path Validation:
+- Script paths are valid
+- Referenced scripts exist
+- Scripts are executable
+
+### MCP Server Validation
+
+File Requirements:
+- .mcp.json is valid JSON
+- Contains mcpServers object
+
+Server Entry Validation:
+- Each server has unique name
+- Contains command field
+- Command is string
+
+Args Validation:
+- If present, is array
+- All elements are strings
+
+Env Validation:
+- If present, is object
+- All values are strings
+- Environment variables properly formatted
+
+Transport Validation:
+- If type specified, is: stdio, http, sse
+- If http/sse: url field required
+- URL is valid format
+
+### LSP Server Validation
+
+File Requirements:
+- .lsp.json is valid JSON
+- Contains lspServers object
+
+Server Entry Validation:
+- Each server has unique name
+- Contains command field
+- Contains extensionToLanguage mapping
+
+Extension Mapping Validation:
+- Keys start with "."
+- Values are non-empty strings
+- At least one mapping present
+
+## Common Validation Errors
+
+### plugin.json Errors
+
+Error: Invalid plugin name
+```
+ERROR: Plugin name 'My_Plugin' is invalid
+  - Must be kebab-case
+  - Use lowercase letters, numbers, hyphens
+  Fix: Rename to 'my-plugin'
+```
+
+Error: Missing name field
+```
+ERROR: plugin.json missing required field 'name'
+  Fix: Add "name": "plugin-name" to plugin.json
+```
+
+Error: Invalid version format
+```
+ERROR: Version '1.0' is not valid semver
+  Fix: Use format X.Y.Z (e.g., "1.0.0")
+```
+
+Error: Path does not exist
+```
+ERROR: Path './commands' does not exist
+  Fix: Create commands directory or remove from plugin.json
+```
+
+### Command Errors
+
+Error: Missing frontmatter
+```
+ERROR: commands/test.md missing YAML frontmatter
+  Fix: Add frontmatter with description:
+  ---
+  description: Command description
+  ---
+```
+
+Error: Missing description
+```
+ERROR: commands/test.md frontmatter missing 'description'
+  Fix: Add description field to frontmatter
+```
+
+### Agent Errors
+
+Error: Invalid tool reference
+```
+ERROR: agents/helper.md references invalid tool 'Execute'
+  Valid tools: Read, Write, Edit, Grep, Glob, Bash, WebFetch, WebSearch, Task, TodoWrite
+  Fix: Use valid tool name
+```
+
+Error: Invalid model
+```
+ERROR: agents/helper.md has invalid model 'gpt4'
+  Valid models: sonnet, opus, haiku, inherit
+  Fix: Use valid model name
+```
+
+### Hook Errors
+
+Error: Invalid event name
+```
+ERROR: hooks.json contains invalid event 'BeforeWrite'
+  Valid events: PreToolUse, PostToolUse, PermissionRequest, UserPromptSubmit, SessionStart, SessionEnd, Stop, SubagentStop, Notification, PreCompact
+  Fix: Use valid event name
+```
+
+Error: Invalid hook type
+```
+ERROR: Hook type 'script' is invalid
+  Valid types: command, prompt
+  Fix: Use 'command' or 'prompt'
+```
+
+Error: Script not found
+```
+ERROR: Hook script './hooks/validate.sh' not found
+  Fix: Create script or update path
+```
+
+### MCP Server Errors
+
+Error: Missing command
+```
+ERROR: MCP server 'my-server' missing 'command' field
+  Fix: Add command field with executable path
+```
+
+Error: Invalid args type
+```
+ERROR: MCP server 'my-server' args must be array
+  Fix: Change args to array format: ["arg1", "arg2"]
+```
+
+### LSP Server Errors
+
+Error: Missing extensionToLanguage
+```
+ERROR: LSP server 'python' missing 'extensionToLanguage'
+  Fix: Add extension mapping: {".py": "python"}
+```
+
+Error: Invalid extension format
+```
+ERROR: Extension 'py' should start with '.'
+  Fix: Change to '.py'
+```
+
+## Validation Best Practices
+
+Pre-Submission Checklist:
+1. Run `claude plugin validate` before distribution
+2. Test plugin locally with `--plugin-dir`
+3. Verify all paths resolve correctly
+4. Test all commands work as expected
+5. Confirm hooks trigger on events
+6. Validate MCP/LSP servers connect
+
+Automated Validation:
+
+Add to CI/CD pipeline:
+```yaml
+# GitHub Actions example
+- name: Validate Plugin
+  run: claude plugin validate ./my-plugin --strict
+```
+
+Version Control Hooks:
+
+Add pre-commit validation:
+```bash
+#!/bin/bash
+# .git/hooks/pre-commit
+claude plugin validate . --strict
+if [ $? -ne 0 ]; then
+  echo "Plugin validation failed"
+  exit 1
+fi
+```
+
+## Validation Levels
+
+Level 1 - Syntax:
+- JSON/YAML validity
+- Required fields present
+- Basic type checking
+
+Level 2 - Semantic:
+- Path references exist
+- Tool names valid
+- Event names valid
+- Model names valid
+
+Level 3 - Functional:
+- Scripts executable
+- Commands invocable
+- Servers connectable
+- Hooks triggerable
+
+Running Different Levels:
+
+Syntax only:
+```bash
+claude plugin validate ./my-plugin --level syntax
+```
+
+Full validation:
+```bash
+claude plugin validate ./my-plugin --level full
+```

moai_adk/templates/.claude/skills/moai-security-auth0/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: moai-security-auth0
+description: Auth0 security specialist covering attack protection, multi-factor authentication, token security, sender constraining, and compliance. Use when implementing Auth0 security features, configuring attack defenses, setting up MFA, or meeting regulatory requirements.
+version: 1.0.0
+category: security
+tags: [auth0, security, mfa, attack-protection, tokens, dpop, mtls, compliance, fapi, gdpr]
+context7-libraries: [/auth0/auth0-docs]
+related-skills: [moai-platform-auth0, expert-security, moai-platform-clerk]
+updated: 2025-12-24
+status: active
+allowed-tools: Read, Write, Edit, Grep, Glob, WebFetch, WebSearch, Bash
+---
+
+# Auth0 Security Specialist
+
+Comprehensive security skill for Auth0 implementations covering attack protection, multi-factor authentication, token security, sender constraining (DPoP/mTLS), and regulatory compliance (FAPI, GDPR, HIPAA).
+
+## Quick Reference
+
+### Security Feature Categories
+
+Attack Protection:
+- Bot Detection: CAPTCHA challenges for suspicious traffic
+- Breached Password Detection: Blocks compromised credentials
+- Brute Force Protection: Limits failed login attempts per account
+- Suspicious IP Throttling: Rate limits high-velocity attacks
+
+Multi-Factor Authentication:
+- Push notifications via Auth0 Guardian
+- One-time passwords (TOTP)
+- WebAuthn with security keys and biometrics
+- SMS/voice verification and Adaptive MFA
+
+Token Security:
+- JWT structure and validation
+- Access token management with scopes
+- Refresh token rotation and expiration
+- Token revocation strategies
+
+Sender Constraining:
+- DPoP: Application-layer token binding
+- mTLS: Transport-layer certificate binding
+
+Compliance: FAPI, GDPR, HIPAA/HITECH, PCI DSS, ISO 27001, SOC 2
+
+### Dashboard Navigation
+
+Attack Protection: Dashboard > Security > Attack Protection
+MFA Configuration: Dashboard > Security > Multi-factor Auth
+Security Center: Dashboard > Security > Security Center
+
+### Essential Setup Checklist
+
+1. Enable Bot Detection with appropriate sensitivity
+2. Activate Breached Password Detection
+3. Configure Brute Force Protection thresholds
+4. Enable Suspicious IP Throttling
+5. Set up at least one MFA factor
+6. Configure token expiration policies
+
+---
+
+## Implementation Guide
+
+### Attack Protection
+
+Bot Detection: Navigate to Dashboard > Security > Attack Protection > Bot Detection. Configure sensitivity (Low/Medium/High) and response type (Auth Challenge recommended, Simple CAPTCHA, or third-party). IP AllowList supports up to 100 addresses/CIDR ranges.
+
+Supported flows: Universal Login, Classic Login, Lock.js v12.4.0+, native apps. Unsupported: Enterprise connections, social login, cross-origin authentication.
+
+Breached Password Detection: Enable for signup and login. Response actions include blocking compromised credentials and user/admin notifications. Standard Detection has 7-13 months detection time; Credential Guard (Enterprise) reduces to 12-36 hours. Test with passwords starting with AUTH0-TEST-.
+
+Brute Force Protection: Default threshold is 10 failed attempts (configurable 1-100). Protection mechanisms include IP-based blocking and account lockout. Blocks remove after 30 days, password change, admin removal, or user unblock link.
+
+Suspicious IP Throttling: Velocity-based detection for high-volume attacks. Responds with HTTP 429. Configure separate thresholds for login (daily) and signup (per minute) attempts.
+
+For details: modules/attack-protection-overview.md
+
+### Multi-Factor Authentication
+
+Factor Configuration: Navigate to Dashboard > Security > Multi-factor Auth.
+
+Independent Factors (at least one required):
+- WebAuthn with FIDO Security Keys
+- One-time Password (OTP/TOTP)
+- Push Notifications via Auth0 Guardian
+- Phone Message (SMS/Voice)
+- Cisco Duo Security
+
+Dependent Factors: WebAuthn Biometrics, Email, Recovery codes
+
+MFA Policies: Never, Use Adaptive MFA (Enterprise), Always
+
+WebAuthn: Provides passwordless MFA with security keys or biometrics. Single interaction for multi-factor authentication, phishing-resistant.
+
+Adaptive MFA (Enterprise): Evaluates risk signals per transaction:
+- NewDevice: Device not used in past 30 days
+- ImpossibleTravel: Geographic anomalies
+- UntrustedIP: Suspicious activity history
+
+High-risk transactions require verification regardless of existing MFA sessions.
+
+Step-Up Authentication: Enhanced verification for sensitive operations. APIs use scopes; web apps verify ID token claims.
+
+For details: modules/mfa-overview.md, modules/adaptive-mfa.md
+
+### Token Security
+
+JWT Fundamentals: RFC 7519 standard. Auth0 issues signed JWTs (JWS). Structure includes Header, Payload (claims), and Signature. Always validate signatures, never store sensitive data in payloads, use HTTPS only.
+
+Access Tokens: Authorize API access with scopes. Types: Opaque (require introspection) and JWT (self-contained). Key claims: iss, sub, aud, scope, exp. Default lifetime: 86400 seconds (24 hours).
+
+Refresh Tokens: Enable session continuity. Maximum 200 active per user per application. Security features: Rotation (invalidates predecessor), expiring tokens (idle/absolute), revocation via Management API.
+
+Best Practices:
+- Treat signing keys as critical credentials
+- Prefer RS256 over HS256 for public key validation
+- Store tokens server-side when possible
+- Cache and reuse until expiration
+
+For details: modules/tokens-overview.md, modules/token-best-practices.md
+
+### Sender Constraining
+
+DPoP (Application Layer): Binds tokens to client-generated asymmetric key pairs.
+
+Steps: Generate key pair (ES256 recommended), create DPoP Proof JWT, send via DPoP header, include updated proof with each API request.
+
+Proof JWT Structure:
+- Header: typ (dpop+jwt), alg, jwk (public key)
+- Payload: jti, htm, htu, iat, ath (for API calls)
+
+Public clients must handle use_dpop_nonce errors.
+
+mTLS (Transport Layer): Binds tokens to X.509 certificates.
+
+Process: Client establishes mTLS connection, Auth0 calculates certificate SHA-256 thumbprint, embeds in token cnf claim as x5t#S256. Resource server validates thumbprint.
+
+Requirements: Confidential clients only, Enterprise Plan with HRI add-on, PKI infrastructure.
+
+For details: modules/dpop-implementation.md, modules/mtls-sender-constraining.md
+
+### Compliance
+
+Highly Regulated Identity (Enterprise + HRI add-on):
+- Strong Customer Authentication: Minimum two independent factors
+- Dynamic Linking: Transaction details in authorization
+- PAR: Pushed Authorization Requests
+- JAR: JWT-Secured Authorization Requests
+- JWE: Access token encryption
+- Private Key JWT and mTLS authentication
+
+GDPR Compliance:
+- Customer as Data Controller, Auth0 as Data Processor
+- User rights: Access, portability (JSON export), erasure, consent management
+- Security: Profile encryption, breach detection, brute-force protection
+
+Certifications: ISO 27001/27017/27018, SOC 2 Type 2, CSA STAR, FAPI 1 Advanced OP, HIPAA BAA available, PCI DSS compliant models
+
+For details: modules/highly-regulated-identity.md, modules/gdpr-compliance.md
+
+---
+
+## Advanced Patterns
+
+### Security Center Monitoring
+
+Access from Dashboard > Security > Security Center.
+
+Threat Categories:
+- Credential Stuffing: Machine-driven compromise attempts
+- Signup Attacks: Automated account creation
+- MFA Bypass: Circumvention attempts
+
+Filtering: Time period (up to 14 days), applications, connections. Auto-aggregation by minute/hour/day.
+
+Metrics: Bot detection counts, IP throttling events, brute force triggers, breached password alerts, MFA success/failure rates.
+
+### Application Credentials
+
+Client Secret (Default): Symmetric, simple but vulnerable to interception.
+
+Private Key JWT (Enterprise): Asymmetric key pairs, private key never transmitted, short-lived assertions. Recommended for enhanced security.
+
+mTLS for OAuth (HRI): X.509 certificates, strongest protection.
+
+Key Management: Register up to two public keys for zero-downtime rotation. Algorithms: RS256, RS384, PS256.
+
+### Continuous Session Protection
+
+Use Auth0 Actions for session context during token refresh events.
+
+Capabilities: IP/ASN monitoring, device tracking, expiration management, anomaly detection.
+
+Dynamic management: Customize lifetimes by user attributes, organization, or role.
+
+---
+
+## Module Reference
+
+Attack Protection:
+- modules/attack-protection-overview.md
+- modules/bot-detection.md
+- modules/breached-password-detection.md
+- modules/brute-force-protection.md
+- modules/suspicious-ip-throttling.md
+- modules/akamai-integration.md
+- modules/attack-protection-log-events.md
+- modules/state-parameters.md
+
+MFA:
+- modules/mfa-overview.md
+- modules/mfa-factors.md
+- modules/webauthn-fido.md
+- modules/adaptive-mfa.md
+- modules/guardian-configuration.md
+- modules/step-up-authentication.md
+- modules/mfa-api-management.md
+- modules/customize-mfa.md
+- modules/ropg-flow-mfa.md
+
+Tokens:
+- modules/tokens-overview.md
+- modules/jwt-fundamentals.md
+- modules/id-tokens.md
+- modules/access-tokens.md
+- modules/delegation-tokens.md
+- modules/refresh-tokens.md
+- modules/token-revocation.md
+- modules/token-best-practices.md
+
+Sender Constraining:
+- modules/dpop-implementation.md
+- modules/mtls-sender-constraining.md
+
+Compliance:
+- modules/compliance-overview.md
+- modules/fapi-implementation.md
+- modules/highly-regulated-identity.md
+- modules/gdpr-compliance.md
+- modules/certifications.md
+- modules/tenant-access-control.md
+- modules/customer-managed-keys.md
+
+Security Operations:
+- modules/security-center.md
+- modules/application-credentials.md
+- modules/continuous-session-protection.md
+- modules/security-guidance.md
+- modules/mdl-verification.md
+
+---
+
+## Works Well With
+
+- moai-platform-auth0: Platform integration patterns
+- expert-security: General security analysis
+- moai-platform-clerk: Alternative authentication comparison
+- moai-lang-typescript: TypeScript SDK implementations
+- moai-lang-python: Python SDK implementations
+- moai-domain-backend: API security integration
+
+---
+
+## Resources
+
+Official Documentation:
+- https://auth0.com/docs/secure
+- https://auth0.com/docs/secure/attack-protection
+- https://auth0.com/docs/secure/multi-factor-authentication
+- https://auth0.com/docs/secure/tokens
+- https://auth0.com/docs/secure/sender-constraining
+- https://auth0.com/docs/secure/data-privacy-and-compliance
+
+Context7: Library /auth0/auth0-docs for latest API documentation