hatch3r 1.0.0

package/rules/hatch3r-secrets-management.mdc

@@ -0,0 +1,74 @@
+---
+description: Secret management, rotation, and secure handling patterns for the project
+alwaysApply: true
+---
+# Secrets Management
+
+## Env Var Management
+
+- Store configuration and secrets in environment variables. Never hard-code secrets (API keys, tokens, passwords, connection strings) in source code, comments, or commit messages.
+- Maintain a `.env.example` file in the repository root listing every required environment variable with placeholder values and brief descriptions. Update it whenever a new env var is introduced.
+- Actual `.env` files must be in `.gitignore`. Verify `.gitignore` includes `.env`, `.env.local`, `.env.*.local`, and any other secret-bearing files before every commit.
+- Use a typed env loader (e.g., `@t3-oss/env-core`, `envalid`, `zod` schema) to validate and parse environment variables at application startup. Fail fast with a clear error message listing missing or invalid variables.
+- Separate secrets by environment: `.env.development`, `.env.staging`, `.env.production`. Never share production secrets with development environments.
+- Document the source of each secret (which service/provider generates it) in `.env.example` or an internal secrets inventory document.
+
+## Secret Rotation Policies
+
+| Secret Type | Rotation Frequency | Trigger for Immediate Rotation |
+|-------------|-------------------|-------------------------------|
+| API keys (third-party) | Every 90 days | Suspected compromise, employee departure |
+| Database credentials | Every 90 days | Credential exposure, personnel change |
+| JWT signing keys | Every 180 days | Algorithm upgrade, key compromise |
+| Webhook secrets | Every 180 days | Partner-side breach, integration change |
+| Service account tokens | Every 90 days | Scope change, compromise |
+| Encryption keys | Every 365 days (or per compliance) | Algorithm vulnerability, compliance audit |
+| OAuth client secrets | Every 180 days | Provider breach, app re-registration |
+
+- Implement dual-key (overlap) rotation: deploy the new secret, update all consumers, verify, then revoke the old secret. Never revoke before all consumers have migrated.
+- Automate rotation where the provider supports it (AWS Secrets Manager auto-rotation, GCP Secret Manager rotation schedules).
+- Log every rotation event: who initiated, when, which secret (by name, never by value), success/failure.
+
+## Cloud Secret Managers
+
+- **AWS Secrets Manager:** Store secrets as JSON key-value pairs. Use IAM policies to scope access per service/role. Enable automatic rotation with Lambda rotation functions. Use `aws-sdk` `GetSecretValue` at runtime — never bake secrets into container images or deployment artifacts.
+- **GCP Secret Manager:** Store each secret as a versioned resource. Grant `secretmanager.secretAccessor` role per service account with resource-level IAM. Access secrets via `@google-cloud/secret-manager` client library at startup. Use secret versions (not `latest` in production) for auditability.
+- **Azure Key Vault:** Store secrets, keys, and certificates. Use Managed Identity for authentication — no credentials needed to access the vault. Apply access policies per application identity. Enable soft-delete and purge protection.
+- **HashiCorp Vault:** Use dynamic secrets where possible (database credentials, cloud IAM). Implement AppRole or Kubernetes auth for machine identity. Set TTLs on all leases. Audit log every access.
+- **General:** Abstract the secret provider behind an interface so the application code is not coupled to a specific cloud provider. Inject the provider at startup via configuration.
+
+## CI/CD Secret Injection
+
+- **GitHub Actions:** Store secrets in repository or organization settings. Reference via `${{ secrets.SECRET_NAME }}`. Never echo secrets in workflow logs — use masking (`::add-mask::`). Use environment-scoped secrets for production deployments with required reviewers.
+- **GitLab CI:** Store in project or group CI/CD variables. Mark as "Protected" (only available on protected branches) and "Masked" (redacted from logs). Use file-type variables for multi-line secrets (certificates, keys).
+- **General CI principles:** Secrets must not appear in build logs, artifacts, or cached layers. Pin CI action versions by SHA (not tag) to prevent supply chain attacks on secret-accessing workflows. Rotate CI secrets on the same schedule as application secrets.
+- **Ephemeral secrets:** For CI jobs that need temporary cloud access, use OIDC federation (e.g., GitHub Actions `aws-actions/configure-aws-credentials` with OIDC) instead of long-lived credentials.
+
+## Application-Level Secret Handling
+
+- **Never log secrets.** Sanitize log output to redact any field matching known secret patterns (tokens, keys, passwords). Use structured logging with an explicit allowlist of loggable fields.
+- **Never serialize secrets** into JSON responses, error messages, stack traces, or client-side state. Treat secrets as write-only values: they go into the system but never come back out in any observable output.
+- **Memory safety:** Clear secret values from memory after use where the language/runtime permits (overwrite buffers, null references). Avoid storing secrets in global/static variables that persist for the application lifetime.
+- **Transport:** Transmit secrets only over TLS 1.2+. Never send secrets in URL query parameters (they appear in access logs and browser history). Use request headers or POST body.
+- **Principle of least privilege:** Each service/function should have access only to the secrets it needs. Avoid a single "master" secret store accessible to all services.
+- **Secret-bearing config objects:** Wrap secrets in a `Secret<T>` type that overrides `toString()` and `toJSON()` to return `"[REDACTED]"`. This prevents accidental exposure via logging or serialization.
+
+## Secret Scanning in CI
+
+- **gitleaks:** Run `gitleaks detect` in CI on every push and PR. Configure `.gitleaks.toml` with project-specific rules and allowlists for false positives (test fixtures, documentation examples).
+- **TruffleHog:** Use `trufflehog git` for historical scanning of the full repository. Run quarterly or on suspected compromise. Focus on high-entropy strings and known secret patterns.
+- **GitHub Secret Scanning:** Enable GitHub's built-in secret scanning and push protection. Configure custom patterns for project-specific secret formats.
+- **Pre-commit hooks:** Install a local pre-commit hook (e.g., `gitleaks protect --staged`) to catch secrets before they reach the remote. This is defense-in-depth — CI scanning is still required.
+- **Remediation SLA:** Secrets detected in CI must be rotated immediately (within 1 hour for production secrets). Assume any secret that reached a commit is compromised, even if the commit was force-pushed away — git history is recoverable.
+
+## Emergency Rotation Procedures
+
+When a secret is confirmed or suspected compromised:
+
+1. **Assess scope:** Identify which secret, which environments, and which services are affected. Check audit logs for unauthorized access.
+2. **Generate new secret:** Create a replacement via the appropriate provider (cloud console, API, or CLI). Do not reuse or derive from the compromised value.
+3. **Deploy new secret:** Update the secret in the secret manager and deploy affected services. Use blue-green or rolling deployment to avoid downtime.
+4. **Revoke old secret:** After confirming all services are using the new secret, revoke/delete the old one. Verify revocation by testing that the old value is rejected.
+5. **Audit impact:** Review access logs for the compromised secret's lifetime. Identify any unauthorized actions taken with the compromised credential.
+6. **Incident report:** Document the timeline, root cause (how the secret was exposed), blast radius, remediation steps, and preventive measures. File as a security incident per the project's incident response process.
+7. **Prevent recurrence:** Add scanning rules for the pattern that was missed, review access controls, and update rotation policies if the secret exceeded its rotation window.

package/rules/hatch3r-security-patterns.md

@@ -0,0 +1,211 @@
+---
+description: Security patterns including input validation, auth enforcement, and AI/agentic security for the project
+alwaysApply: true
+---
+# Security Patterns
+
+## Input Validation
+
+- Validate at the boundary: API routes, form handlers, webhook receivers, CLI parsers. Never trust data that has crossed a trust boundary.
+- Use type-safe runtime schemas (zod, valibot, joi) co-located with the handler. Compile-time types alone are insufficient.
+- Allowlist over denylist for string inputs (permitted characters, values, formats). Denylists are always incomplete.
+- Enforce length limits, numeric range checks, and format validation (email, URL, UUID, ISO dates) on every external field.
+- Reject unexpected fields with strict/passthrough-off schemas. Unknown keys are an attack surface.
+- File uploads: validate type by magic bytes (not extension), enforce size limits, generate server-side filenames, reject path traversal (`..`, absolute paths, null bytes).
+
+## Output Encoding
+
+- Apply context-aware encoding: HTML entities for markup, URL-encoding for query params, JavaScript escaping for inline scripts, CSS escaping for style contexts.
+- Never construct HTML from user input without sanitization (DOMPurify or equivalent server-side library). Treat all user content as untrusted.
+- Use parameterized queries / prepared statements for SQL, Firestore filters, and NoSQL queries. Zero tolerance for string concatenation with user input.
+- Enable auto-escaping in template engines by default. Disable only per-expression with review.
+- Sanitize data before logging. Log output is also an injection vector (log forging, ANSI escape injection).
+
+## Authentication Enforcement
+
+- Auth middleware on every route by default. Public routes require explicit opt-out with code review justification.
+- Token validation: pin allowed algorithms (reject `none`), enforce expiry (`exp`), verify audience (`aud`) and issuer (`iss`) claims. Reject tokens failing any check.
+- Session security: `HttpOnly`, `Secure`, `SameSite=Strict` (or `Lax` with justification) cookies. Rotate session ID on privilege change (login, role switch).
+- Multi-factor authentication for sensitive operations: admin actions, payment, account deletion, API key generation.
+- Rate-limit authentication endpoints (login, token refresh, password reset). Lock accounts or add progressive delays after repeated failures.
+- Invalidate all sessions on password change. Provide "sign out everywhere" capability.
+
+## Fail-Closed Defaults
+
+- Default deny for authorization. Every permission must be explicitly granted; absence of a rule means deny.
+- Error handlers must not leak internal state: no stack traces, query details, file paths, or dependency versions in responses. Return generic error codes.
+- Fallback to the most restrictive behavior on config parse failure. Misconfiguration must never widen access.
+- Circuit breakers for downstream service failures. Degrade gracefully rather than retrying indefinitely or passing errors upstream.
+- Health checks and readiness probes must not expose sensitive configuration or internal topology.
+- Disable debug endpoints, verbose logging, and source maps in production builds. Gate behind feature flags if needed in staging.
+
+## CSRF Protection
+
+- Apply synchronizer token pattern or double-submit cookie for all state-mutating requests (POST, PUT, PATCH, DELETE).
+- Set `SameSite` cookie attribute as defense-in-depth. It supplements but does not replace CSRF tokens.
+- For API-only endpoints (no browser cookies), require a custom header (`X-Requested-With` or equivalent) that browsers will not send cross-origin without CORS preflight.
+- Validate `Origin` and `Referer` headers as an additional layer for critical endpoints.
+
+## AI & Agentic Security (OWASP Agentic Top 10)
+
+### ASI01 — Agent Goal Hijack
+
+- Separate system prompts from user input with clear delimiters. Never allow user content to override system instructions.
+- Implement input guardrails: scan user messages for injection patterns before LLM processing.
+- Enforce instruction hierarchy: system > developer > user. Reject attempts to redefine agent purpose.
+- Defend against indirect prompt injection: sanitize and tag content retrieved from external sources (RAG, web, files) before including in context.
+
+### ASI02 — Tool Misuse & Exploitation
+
+- Deny-by-default tool access. Each tool requires explicit grant per agent role.
+- Enforce parameter schemas on every tool call. Reject calls with unexpected, missing, or out-of-range arguments.
+- Rate-limit tool invocations per agent per time window. Alert on anomalous tool usage patterns.
+- Sandbox tool execution: restrict file system access, network egress, and subprocess spawning.
+
+### ASI03 — Identity & Privilege Abuse
+
+- Assign unique agent IDs per invocation. Log all actions with agent identity for non-repudiation.
+- Apply least privilege: agents receive scoped credentials, never full user or admin tokens.
+- Prevent privilege escalation across agent boundaries. An agent must not request or inherit higher privileges than its caller.
+- Audit delegation chains: every permission grant from user → agent → sub-agent must be traceable.
+
+### ASI04 — Supply Chain Vulnerabilities
+
+- Pin MCP server and plugin versions. Never auto-install unverified packages (`npx -y` on untrusted sources).
+- Verify package integrity (checksums, signatures) before loading tools or plugins.
+- Audit third-party prompt templates for injected instructions before use.
+- Maintain an allowlist of approved MCP servers and tool sources.
+
+### ASI05 — Unexpected Code Execution
+
+- Never execute agent-generated code without sandboxing (isolated container, restricted runtime, no network).
+- Require human review for generated code that touches file system, network, or credentials.
+- Restrict generated code to a safe subset: no `eval`, `exec`, shell commands, or dynamic imports.
+- Enforce file system access controls: agents can only read/write within designated workspace directories.
+
+### ASI06 — Memory & Context Poisoning
+
+- Validate stored context before reuse. Re-check integrity and relevance of cached agent state on retrieval.
+- Set expiry / TTL for all cached agent memory. Stale context is a poisoning vector.
+- Tag and isolate RAG-retrieved content from trusted system instructions. Never promote retrieved content to system-level authority.
+- Detect tampering: hash or sign stored memory entries, verify on read.
+
+### ASI07 — Insecure Inter-Agent Communication
+
+- Authenticate agent-to-agent messages. Each agent must verify the identity of its communication partner.
+- Scope delegation tokens: a sub-agent receives only the permissions needed for its specific task.
+- Validate message integrity (signing or HMAC) to prevent tampering in multi-agent workflows.
+- Enforce privilege boundaries: a delegated agent cannot escalate beyond the scope granted by its parent.
+
+### ASI08 — Cascading Failures
+
+- Implement circuit breakers between agent stages. A failure in one agent must not propagate unchecked.
+- Enforce timeouts on every agent invocation and tool call. No unbounded waits.
+- Contain blast radius: isolate agent workflows so a compromised agent cannot affect unrelated workflows.
+- Log and alert on error chains. Three consecutive failures in an agent chain should trigger automatic halt.
+
+### ASI09 — Human-Agent Trust Exploitation
+
+- Mandatory human confirmation for destructive operations: file deletion, database writes, external API calls with side effects, financial transactions.
+- Enforce cost limits: cap token usage, API call counts, and compute time per agent invocation.
+- Present agent actions transparently: show the user what the agent did and why, not just the result.
+- Resist social engineering: agents must not bypass confirmation flows based on urgency framing in user input.
+
+### ASI10 — Rogue Agents
+
+- Monitor agent outputs for policy violations, off-topic responses, and anomalous behavior patterns.
+- Validate agent outputs against expected schemas and content policies before acting on them.
+- Enforce scope: reject agent actions outside the declared task boundary.
+- Implement kill switches: ability to immediately terminate a running agent and revoke its credentials.
+- Run anomaly detection on tool call patterns, output length, and execution time to flag compromised agents.
+
+## OWASP Top 10 2025 (Web Application Security)
+
+### A01 — Broken Access Control
+
+- Enforce access control server-side. Client-side checks are UX, not security.
+- Deny by default: every resource requires explicit permission. Absence of a grant means deny.
+- Implement resource-level ownership checks: verify the authenticated user owns (or has a role granting access to) the requested resource. Parameterized IDs in URLs are not authorization — always validate ownership.
+- Disable directory listing. Restrict access to metadata files (`.git`, `.env`, backup files).
+- Rate-limit API access to minimize automated IDOR scanning and credential stuffing.
+- Log access control failures and alert on repeated violations from the same identity.
+
+### A02 — Cryptographic Failures
+
+- Classify data by sensitivity (PII, financial, health, credentials). Apply encryption requirements per classification.
+- Encrypt data in transit (TLS 1.2+ mandatory, prefer 1.3) and at rest (AES-256 or equivalent).
+- Never use deprecated algorithms: MD5, SHA-1, DES, RC4, ECB mode. Use SHA-256+ for hashing, AES-GCM for symmetric encryption, RSA-OAEP or ECDSA for asymmetric.
+- Hash passwords with bcrypt, scrypt, or Argon2id with appropriate work factors. Never use raw SHA/MD5 for passwords.
+- Generate cryptographic keys with secure random sources (`crypto.randomBytes`, not `Math.random`). Never hard-code keys or IVs.
+- Disable caching for responses containing sensitive data (`Cache-Control: no-store`).
+
+### A03 — Injection
+
+- Use parameterized queries or prepared statements for all database operations. Zero tolerance for string concatenation with user input in queries.
+- Apply context-aware output encoding: HTML entities, URL encoding, JavaScript escaping, CSS escaping, LDAP escaping — matched to the output context.
+- Validate and sanitize all external input with allowlist validation. Limit input length, character sets, and format.
+- Use `LIMIT` and pagination in queries to prevent mass data disclosure via injection.
+- For OS command execution: avoid entirely if possible. If necessary, use parameterized APIs (not shell interpolation) with strict input validation.
+
+### A04 — Insecure Design
+
+- Use threat modeling during design phase (STRIDE, attack trees, or equivalent). Identify trust boundaries and abuse cases before writing code.
+- Establish and enforce secure design patterns: separation of concerns, defense in depth, least privilege, fail-closed.
+- Write abuse-case user stories alongside feature user stories: "As an attacker, I want to..."
+- Design rate limiting, resource quotas, and cost controls into the architecture — not as afterthoughts.
+- Establish secure development lifecycle (SDL) practices: security requirements, design review, code review, testing.
+
+### A05 — Security Misconfiguration
+
+- Harden all environments: remove default accounts, disable unused features/ports/services, remove sample applications.
+- Use identical security configuration across development, staging, and production. Differences in security settings between environments mask vulnerabilities.
+- Automate configuration verification: infrastructure-as-code with security baselines, configuration scanning in CI.
+- Send security headers on every response (HSTS, CSP, X-Content-Type-Options, X-Frame-Options). Centralize in middleware.
+- Review cloud permissions quarterly. Remove unused IAM roles, security groups, and service accounts.
+- Disable detailed error messages in production. Use generic error responses with correlation IDs for debugging.
+
+### A06 — Vulnerable and Outdated Components
+
+- Maintain a software bill of materials (SBOM) for all direct and transitive dependencies.
+- Run `npm audit` (or equivalent) in CI on every build. Block merges with critical or high vulnerabilities.
+- Subscribe to security advisories for all critical dependencies (GitHub Dependabot, Snyk, or equivalent).
+- Remove unused dependencies. Unused code with known vulnerabilities is still a risk.
+- Pin dependency versions in lockfiles. Review lockfile changes in PRs with the same scrutiny as code changes.
+- Establish SLAs for vulnerability remediation: critical within 24 hours, high within 1 week, moderate within 1 sprint.
+
+### A07 — Identification and Authentication Failures
+
+- Implement multi-factor authentication for privileged accounts and sensitive operations.
+- Enforce password complexity requirements: minimum 8 characters, check against breached password databases (Have I Been Pwned API).
+- Protect against credential stuffing: rate-limit login attempts, implement progressive delays, use CAPTCHA after repeated failures.
+- Session management: generate new session ID on login, invalidate on logout, set absolute and idle timeouts.
+- Never expose session IDs in URLs. Use secure, HttpOnly, SameSite cookies.
+- Implement account lockout with notification after repeated failed attempts.
+
+### A08 — Software and Data Integrity Failures
+
+- Verify integrity of all software updates, dependencies, and CI/CD pipeline artifacts using digital signatures or checksums.
+- Use lockfiles and verify their integrity. `npm ci` (not `npm install`) in CI to ensure deterministic builds.
+- CI/CD pipelines: require code review for all changes, enforce branch protection, sign commits where feasible.
+- Never deserialize untrusted data without validation. Use schemas (zod, JSON Schema) to validate structure before processing.
+- Protect CI/CD secrets and permissions: restrict who can modify pipeline configuration, require approval for deployment steps.
+- Pin GitHub Actions and CI plugins by commit SHA, not mutable tags.
+
+### A09 — Security Logging and Monitoring Failures
+
+- Log all authentication events (success, failure, lockout), access control failures, input validation failures, and security-relevant business events.
+- Use structured logging with correlation IDs. Include: timestamp, severity, event type, user identity (if available), source IP, resource accessed, outcome.
+- Never log sensitive data: passwords, tokens, PII, credit card numbers, session IDs. Redact before logging.
+- Centralize logs and enable real-time alerting for security events. Alert on: brute-force patterns, privilege escalation, anomalous access patterns.
+- Retain security logs for the compliance-required period (minimum 90 days, typically 1 year).
+- Test that logging works: include security event logging in integration tests. Verify alerts fire during incident response drills.
+
+### A10 — Mishandling of Exceptional Conditions
+
+- Catch and handle every possible error at the point of occurrence. Uncaught exceptions are a vulnerability — they can crash services, leak state, or bypass security checks.
+- Fail closed, not open. When an error occurs in an authorization check, deny access. When a transaction fails mid-way, roll back completely. Never leave the system in a partially-completed state.
+- Implement global exception handlers as a safety net. All unhandled exceptions must be logged, reported, and result in a safe error response (no stack traces, no internal details).
+- Handle missing and malformed parameters explicitly. Do not rely on language defaults (undefined, null, zero) for security-sensitive logic.
+- Check return values and error codes from all system calls, library functions, and external API responses. Ignored return values are a common source of silent failures.
+- Add observability for error patterns: monitor error rates by category, alert on sudden spikes, and investigate recurring error types as potential attack probes.
+- Roll back incomplete transactions atomically. Partial writes, partial state changes, and orphaned resources are integrity violations.

package/rules/hatch3r-security-patterns.mdc

@@ -0,0 +1,211 @@
+---
+description: Security patterns including input validation, auth enforcement, and AI/agentic security for the project
+alwaysApply: true
+---
+# Security Patterns
+
+## Input Validation
+
+- Validate at the boundary: API routes, form handlers, webhook receivers, CLI parsers. Never trust data that has crossed a trust boundary.
+- Use type-safe runtime schemas (zod, valibot, joi) co-located with the handler. Compile-time types alone are insufficient.
+- Allowlist over denylist for string inputs (permitted characters, values, formats). Denylists are always incomplete.
+- Enforce length limits, numeric range checks, and format validation (email, URL, UUID, ISO dates) on every external field.
+- Reject unexpected fields with strict/passthrough-off schemas. Unknown keys are an attack surface.
+- File uploads: validate type by magic bytes (not extension), enforce size limits, generate server-side filenames, reject path traversal (`..`, absolute paths, null bytes).
+
+## Output Encoding
+
+- Apply context-aware encoding: HTML entities for markup, URL-encoding for query params, JavaScript escaping for inline scripts, CSS escaping for style contexts.
+- Never construct HTML from user input without sanitization (DOMPurify or equivalent server-side library). Treat all user content as untrusted.
+- Use parameterized queries / prepared statements for SQL, Firestore filters, and NoSQL queries. Zero tolerance for string concatenation with user input.
+- Enable auto-escaping in template engines by default. Disable only per-expression with review.
+- Sanitize data before logging. Log output is also an injection vector (log forging, ANSI escape injection).
+
+## Authentication Enforcement
+
+- Auth middleware on every route by default. Public routes require explicit opt-out with code review justification.
+- Token validation: pin allowed algorithms (reject `none`), enforce expiry (`exp`), verify audience (`aud`) and issuer (`iss`) claims. Reject tokens failing any check.
+- Session security: `HttpOnly`, `Secure`, `SameSite=Strict` (or `Lax` with justification) cookies. Rotate session ID on privilege change (login, role switch).
+- Multi-factor authentication for sensitive operations: admin actions, payment, account deletion, API key generation.
+- Rate-limit authentication endpoints (login, token refresh, password reset). Lock accounts or add progressive delays after repeated failures.
+- Invalidate all sessions on password change. Provide "sign out everywhere" capability.
+
+## Fail-Closed Defaults
+
+- Default deny for authorization. Every permission must be explicitly granted; absence of a rule means deny.
+- Error handlers must not leak internal state: no stack traces, query details, file paths, or dependency versions in responses. Return generic error codes.
+- Fallback to the most restrictive behavior on config parse failure. Misconfiguration must never widen access.
+- Circuit breakers for downstream service failures. Degrade gracefully rather than retrying indefinitely or passing errors upstream.
+- Health checks and readiness probes must not expose sensitive configuration or internal topology.
+- Disable debug endpoints, verbose logging, and source maps in production builds. Gate behind feature flags if needed in staging.
+
+## CSRF Protection
+
+- Apply synchronizer token pattern or double-submit cookie for all state-mutating requests (POST, PUT, PATCH, DELETE).
+- Set `SameSite` cookie attribute as defense-in-depth. It supplements but does not replace CSRF tokens.
+- For API-only endpoints (no browser cookies), require a custom header (`X-Requested-With` or equivalent) that browsers will not send cross-origin without CORS preflight.
+- Validate `Origin` and `Referer` headers as an additional layer for critical endpoints.
+
+## AI & Agentic Security (OWASP Agentic Top 10)
+
+### ASI01 — Agent Goal Hijack
+
+- Separate system prompts from user input with clear delimiters. Never allow user content to override system instructions.
+- Implement input guardrails: scan user messages for injection patterns before LLM processing.
+- Enforce instruction hierarchy: system > developer > user. Reject attempts to redefine agent purpose.
+- Defend against indirect prompt injection: sanitize and tag content retrieved from external sources (RAG, web, files) before including in context.
+
+### ASI02 — Tool Misuse & Exploitation
+
+- Deny-by-default tool access. Each tool requires explicit grant per agent role.
+- Enforce parameter schemas on every tool call. Reject calls with unexpected, missing, or out-of-range arguments.
+- Rate-limit tool invocations per agent per time window. Alert on anomalous tool usage patterns.
+- Sandbox tool execution: restrict file system access, network egress, and subprocess spawning.
+
+### ASI03 — Identity & Privilege Abuse
+
+- Assign unique agent IDs per invocation. Log all actions with agent identity for non-repudiation.
+- Apply least privilege: agents receive scoped credentials, never full user or admin tokens.
+- Prevent privilege escalation across agent boundaries. An agent must not request or inherit higher privileges than its caller.
+- Audit delegation chains: every permission grant from user → agent → sub-agent must be traceable.
+
+### ASI04 — Supply Chain Vulnerabilities
+
+- Pin MCP server and plugin versions. Never auto-install unverified packages (`npx -y` on untrusted sources).
+- Verify package integrity (checksums, signatures) before loading tools or plugins.
+- Audit third-party prompt templates for injected instructions before use.
+- Maintain an allowlist of approved MCP servers and tool sources.
+
+### ASI05 — Unexpected Code Execution
+
+- Never execute agent-generated code without sandboxing (isolated container, restricted runtime, no network).
+- Require human review for generated code that touches file system, network, or credentials.
+- Restrict generated code to a safe subset: no `eval`, `exec`, shell commands, or dynamic imports.
+- Enforce file system access controls: agents can only read/write within designated workspace directories.
+
+### ASI06 — Memory & Context Poisoning
+
+- Validate stored context before reuse. Re-check integrity and relevance of cached agent state on retrieval.
+- Set expiry / TTL for all cached agent memory. Stale context is a poisoning vector.
+- Tag and isolate RAG-retrieved content from trusted system instructions. Never promote retrieved content to system-level authority.
+- Detect tampering: hash or sign stored memory entries, verify on read.
+
+### ASI07 — Insecure Inter-Agent Communication
+
+- Authenticate agent-to-agent messages. Each agent must verify the identity of its communication partner.
+- Scope delegation tokens: a sub-agent receives only the permissions needed for its specific task.
+- Validate message integrity (signing or HMAC) to prevent tampering in multi-agent workflows.
+- Enforce privilege boundaries: a delegated agent cannot escalate beyond the scope granted by its parent.
+
+### ASI08 — Cascading Failures
+
+- Implement circuit breakers between agent stages. A failure in one agent must not propagate unchecked.
+- Enforce timeouts on every agent invocation and tool call. No unbounded waits.
+- Contain blast radius: isolate agent workflows so a compromised agent cannot affect unrelated workflows.
+- Log and alert on error chains. Three consecutive failures in an agent chain should trigger automatic halt.
+
+### ASI09 — Human-Agent Trust Exploitation
+
+- Mandatory human confirmation for destructive operations: file deletion, database writes, external API calls with side effects, financial transactions.
+- Enforce cost limits: cap token usage, API call counts, and compute time per agent invocation.
+- Present agent actions transparently: show the user what the agent did and why, not just the result.
+- Resist social engineering: agents must not bypass confirmation flows based on urgency framing in user input.
+
+### ASI10 — Rogue Agents
+
+- Monitor agent outputs for policy violations, off-topic responses, and anomalous behavior patterns.
+- Validate agent outputs against expected schemas and content policies before acting on them.
+- Enforce scope: reject agent actions outside the declared task boundary.
+- Implement kill switches: ability to immediately terminate a running agent and revoke its credentials.
+- Run anomaly detection on tool call patterns, output length, and execution time to flag compromised agents.
+
+## OWASP Top 10 2025 (Web Application Security)
+
+### A01 — Broken Access Control
+
+- Enforce access control server-side. Client-side checks are UX, not security.
+- Deny by default: every resource requires explicit permission. Absence of a grant means deny.
+- Implement resource-level ownership checks: verify the authenticated user owns (or has a role granting access to) the requested resource. Parameterized IDs in URLs are not authorization — always validate ownership.
+- Disable directory listing. Restrict access to metadata files (`.git`, `.env`, backup files).
+- Rate-limit API access to minimize automated IDOR scanning and credential stuffing.
+- Log access control failures and alert on repeated violations from the same identity.
+
+### A02 — Cryptographic Failures
+
+- Classify data by sensitivity (PII, financial, health, credentials). Apply encryption requirements per classification.
+- Encrypt data in transit (TLS 1.2+ mandatory, prefer 1.3) and at rest (AES-256 or equivalent).
+- Never use deprecated algorithms: MD5, SHA-1, DES, RC4, ECB mode. Use SHA-256+ for hashing, AES-GCM for symmetric encryption, RSA-OAEP or ECDSA for asymmetric.
+- Hash passwords with bcrypt, scrypt, or Argon2id with appropriate work factors. Never use raw SHA/MD5 for passwords.
+- Generate cryptographic keys with secure random sources (`crypto.randomBytes`, not `Math.random`). Never hard-code keys or IVs.
+- Disable caching for responses containing sensitive data (`Cache-Control: no-store`).
+
+### A03 — Injection
+
+- Use parameterized queries or prepared statements for all database operations. Zero tolerance for string concatenation with user input in queries.
+- Apply context-aware output encoding: HTML entities, URL encoding, JavaScript escaping, CSS escaping, LDAP escaping — matched to the output context.
+- Validate and sanitize all external input with allowlist validation. Limit input length, character sets, and format.
+- Use `LIMIT` and pagination in queries to prevent mass data disclosure via injection.
+- For OS command execution: avoid entirely if possible. If necessary, use parameterized APIs (not shell interpolation) with strict input validation.
+
+### A04 — Insecure Design
+
+- Use threat modeling during design phase (STRIDE, attack trees, or equivalent). Identify trust boundaries and abuse cases before writing code.
+- Establish and enforce secure design patterns: separation of concerns, defense in depth, least privilege, fail-closed.
+- Write abuse-case user stories alongside feature user stories: "As an attacker, I want to..."
+- Design rate limiting, resource quotas, and cost controls into the architecture — not as afterthoughts.
+- Establish secure development lifecycle (SDL) practices: security requirements, design review, code review, testing.
+
+### A05 — Security Misconfiguration
+
+- Harden all environments: remove default accounts, disable unused features/ports/services, remove sample applications.
+- Use identical security configuration across development, staging, and production. Differences in security settings between environments mask vulnerabilities.
+- Automate configuration verification: infrastructure-as-code with security baselines, configuration scanning in CI.
+- Send security headers on every response (HSTS, CSP, X-Content-Type-Options, X-Frame-Options). Centralize in middleware.
+- Review cloud permissions quarterly. Remove unused IAM roles, security groups, and service accounts.
+- Disable detailed error messages in production. Use generic error responses with correlation IDs for debugging.
+
+### A06 — Vulnerable and Outdated Components
+
+- Maintain a software bill of materials (SBOM) for all direct and transitive dependencies.
+- Run `npm audit` (or equivalent) in CI on every build. Block merges with critical or high vulnerabilities.
+- Subscribe to security advisories for all critical dependencies (GitHub Dependabot, Snyk, or equivalent).
+- Remove unused dependencies. Unused code with known vulnerabilities is still a risk.
+- Pin dependency versions in lockfiles. Review lockfile changes in PRs with the same scrutiny as code changes.
+- Establish SLAs for vulnerability remediation: critical within 24 hours, high within 1 week, moderate within 1 sprint.
+
+### A07 — Identification and Authentication Failures
+
+- Implement multi-factor authentication for privileged accounts and sensitive operations.
+- Enforce password complexity requirements: minimum 8 characters, check against breached password databases (Have I Been Pwned API).
+- Protect against credential stuffing: rate-limit login attempts, implement progressive delays, use CAPTCHA after repeated failures.
+- Session management: generate new session ID on login, invalidate on logout, set absolute and idle timeouts.
+- Never expose session IDs in URLs. Use secure, HttpOnly, SameSite cookies.
+- Implement account lockout with notification after repeated failed attempts.
+
+### A08 — Software and Data Integrity Failures
+
+- Verify integrity of all software updates, dependencies, and CI/CD pipeline artifacts using digital signatures or checksums.
+- Use lockfiles and verify their integrity. `npm ci` (not `npm install`) in CI to ensure deterministic builds.
+- CI/CD pipelines: require code review for all changes, enforce branch protection, sign commits where feasible.
+- Never deserialize untrusted data without validation. Use schemas (zod, JSON Schema) to validate structure before processing.
+- Protect CI/CD secrets and permissions: restrict who can modify pipeline configuration, require approval for deployment steps.
+- Pin GitHub Actions and CI plugins by commit SHA, not mutable tags.
+
+### A09 — Security Logging and Monitoring Failures
+
+- Log all authentication events (success, failure, lockout), access control failures, input validation failures, and security-relevant business events.
+- Use structured logging with correlation IDs. Include: timestamp, severity, event type, user identity (if available), source IP, resource accessed, outcome.
+- Never log sensitive data: passwords, tokens, PII, credit card numbers, session IDs. Redact before logging.
+- Centralize logs and enable real-time alerting for security events. Alert on: brute-force patterns, privilege escalation, anomalous access patterns.
+- Retain security logs for the compliance-required period (minimum 90 days, typically 1 year).
+- Test that logging works: include security event logging in integration tests. Verify alerts fire during incident response drills.
+
+### A10 — Mishandling of Exceptional Conditions
+
+- Catch and handle every possible error at the point of occurrence. Uncaught exceptions are a vulnerability — they can crash services, leak state, or bypass security checks.
+- Fail closed, not open. When an error occurs in an authorization check, deny access. When a transaction fails mid-way, roll back completely. Never leave the system in a partially-completed state.
+- Implement global exception handlers as a safety net. All unhandled exceptions must be logged, reported, and result in a safe error response (no stack traces, no internal details).
+- Handle missing and malformed parameters explicitly. Do not rely on language defaults (undefined, null, zero) for security-sensitive logic.
+- Check return values and error codes from all system calls, library functions, and external API responses. Ignored return values are a common source of silent failures.
+- Add observability for error patterns: monitor error rates by category, alert on sudden spikes, and investigate recurring error types as potential attack probes.
+- Roll back incomplete transactions atomically. Partial writes, partial state changes, and orphaned resources are integrity violations.

package/rules/hatch3r-testing.md

@@ -0,0 +1,89 @@
+---
+id: hatch3r-testing
+type: rule
+description: Test standards and conventions for the project
+scope: always
+---
+# Testing Standards
+
+## Core Principles
+
+- Unit tests: project test runner. Integration: test runner + emulators/mocks. E2E: browser automation (Playwright or equivalent).
+- **Deterministic.** Mock time where needed. No wall clock dependency.
+- **Isolated.** Each test sets up and tears down its own state.
+- **Fast.** Unit tests < 50ms. Integration tests < 2s.
+- **Named clearly.** Describe behavior: `"should award 15 XP for 25-min focus block"`.
+- **Regression.** Every bug fix includes a test that fails before the fix and passes after.
+- **No network.** Unit tests must not make network calls. Use mocks.
+- No type escape hatches in tests. No `.skip` without a linked issue.
+- Write tests to `tests/unit/`, `tests/integration/`, `tests/e2e/`, or equivalent.
+- Use test fixtures from `tests/fixtures/` or equivalent.
+- **Browser verification.** For UI changes, verify visually in the browser via browser automation MCP after automated tests pass. Capture screenshots as evidence.
+
+## Coverage Thresholds
+
+- **Statement coverage:** 80% minimum across the project. New code must not decrease overall coverage.
+- **Branch coverage:** 70% minimum. Uncovered branches must be justified (e.g., defensive error handling unlikely to trigger).
+- **Function coverage:** 80% minimum. Every exported function must have at least one test.
+- **Per-PR gate:** CI blocks merge if the PR decreases coverage by more than 1% in any metric.
+- **Critical modules** (auth, payments, data persistence, security rules): 90% statement, 85% branch minimum.
+- Generate coverage reports in CI and publish as PR comments or artifacts for visibility.
+- Exclude generated code, type declarations, and config files from coverage metrics.
+
+## Mocking Strategy
+
+- **Prefer fakes over mocks** for stateful dependencies (databases, caches). Fakes implement the real interface with in-memory state, making tests more realistic.
+- **Use stubs** for simple value returns where behavior is irrelevant to the test (e.g., config lookups, feature flags).
+- **Use mocks** (with call verification) only when the interaction itself is the behavior under test (e.g., verifying an event was emitted, an API was called with specific arguments).
+- **Mock boundaries, not internals.** Mock at module/service boundaries (HTTP clients, database drivers, external SDKs). Never mock private functions or internal implementation details.
+- **Reset mocks between tests.** Use `beforeEach` / `afterEach` to restore original implementations. Leaked mock state is a top source of flaky tests.
+- **Type-safe mocks.** Mock implementations must satisfy the same TypeScript interface as the real dependency. Avoid `as any` in mock setup.
+- **No mocking the unit under test.** If you need to mock part of the module you are testing, the module has too many responsibilities — refactor first.
+
+## Property-Based Testing
+
+- Use a property-based testing library (fast-check or equivalent) for functions with wide input domains.
+- **Priority targets:** parsers, serializers, validators, encoders/decoders, mathematical functions, and any pure function with complex input types.
+- Define invariants as properties: round-trip (encode then decode equals original), idempotency (applying twice equals applying once), monotonicity, commutativity.
+- Use `fc.assert` with at least 100 runs per property. Increase to 1000 for critical paths.
+- When a property test finds a failure, add the minimal counterexample as a dedicated regression unit test.
+- Shrinking must be enabled — it reduces failing inputs to the smallest reproduction case.
+- Property tests belong alongside unit tests in `tests/unit/`. Name them clearly: `"property: round-trip serialization for UserProfile"`.
+
+## Mutation Testing
+
+- Use Stryker (or equivalent mutation testing framework) on critical modules to measure test effectiveness beyond line coverage.
+- **Mutation score target:** 70% minimum on critical modules (auth, data layer, business rules). 60% minimum project-wide.
+- Run mutation testing in CI on a weekly schedule (not per-PR — too slow). Report results as a CI artifact.
+- **Surviving mutants** indicate tests that pass regardless of code changes — these are false-coverage tests. Fix them by adding assertions that detect the mutation.
+- Focus mutation testing effort on modules where a bug would cause data loss, security vulnerability, or financial impact.
+- Exclude test files, generated code, and UI presentation logic from mutation analysis.
+
+## Flaky Test Handling
+
+- **Zero tolerance policy.** A flaky test erodes trust in the entire suite. Fix or quarantine within 48 hours of detection.
+- **Quarantine process:** Move the flaky test to a `tests/quarantine/` directory or tag with `.skip("FLAKY: #issue-number")`. Create a tracking issue immediately.
+- **Retry strategy in CI:** Allow a maximum of 1 automatic retry for the full test suite. Never retry individual tests silently — that masks flakiness.
+- **Root cause investigation:** Common causes are shared mutable state, timing dependencies (real clocks, `setTimeout`), port conflicts, uncontrolled randomness, and external service calls.
+- **Fix patterns:** Replace `setTimeout` with fake timers, replace shared state with per-test setup, replace port binding with dynamic ports, seed random generators deterministically.
+- **Flaky test metrics:** Track flaky test rate over time. Target < 0.5% flaky rate (flaky runs / total runs). Alert when rate exceeds 1%.
+- **Quarantine review:** Review quarantined tests weekly. Tests quarantined for more than 30 days must be either fixed or deleted with justification.
+
+## Test Data Management
+
+- **Factories over fixtures.** Use factory functions (builder pattern) to generate test data with sensible defaults and per-test overrides. Factories produce valid objects by default; tests override only the fields relevant to the scenario.
+- **Builder pattern example:** `buildUser({ role: "admin" })` returns a full valid User with admin role and random but valid defaults for all other fields.
+- **No shared mutable fixtures.** If multiple tests read the same fixture data, each test must get its own copy. Use `structuredClone()` or factory functions.
+- **Realistic data.** Use faker or equivalent for generating realistic names, emails, dates. Avoid magic strings like `"test"`, `"foo"`, `"abc123"`.
+- **Deterministic seeding.** When using random data generators, seed them per test file so failures are reproducible.
+- **Fixture files** (JSON, YAML) are acceptable for large, complex, or externally-sourced test inputs (API response snapshots, configuration samples). Store in `tests/fixtures/`.
+- **Database state:** Integration tests that require database state must set up and tear down within the test using helpers. Never depend on database state from a previous test.
+
+## Snapshot Testing
+
+- **Use sparingly.** Snapshots are appropriate for serialized output (JSON API responses, CLI output, rendered HTML structure) where the exact output matters and is stable.
+- **Not appropriate for:** UI component visual appearance (use visual regression tests), objects with timestamps or random IDs (unstable), large objects (unreadable diffs).
+- **Review discipline.** Snapshot updates (`--update-snapshots`) must be reviewed as carefully as code changes. Reviewers must verify the new snapshot is intentionally correct, not just "different."
+- **Keep snapshots small.** Snapshot files > 100 lines suggest the test is asserting too broadly. Narrow the assertion to the relevant subset.
+- **Inline snapshots** (where supported) are preferred over external `.snap` files for short outputs (< 20 lines) because they keep the assertion co-located with the test.
+- **Name snapshot files** to match their test file: `auth.test.ts` → `auth.test.ts.snap`.