@stacksjs/defaults 0.70.207 → 0.70.208

package/ai/skills/stacks-search-engine/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: stacks-search-engine
+description: Use when implementing search in Stacks — full-text search with Meilisearch or Algolia backends, document indexing, search settings management, the useSearch model trait for automatic indexing, or search driver configuration. Covers @stacksjs/search-engine and config/search-engine.ts.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Search Engine
+
+Full-text search integration with Meilisearch and Algolia drivers.
+
+## Key Paths
+- Core package: `storage/framework/core/search-engine/src/`
+- Configuration: `config/search-engine.ts`
+
+## Search Driver Factory
+
+```typescript
+import { useSearchEngine, useAlgolia, useMeilisearch } from '@stacksjs/search-engine'
+
+const search = useSearchEngine()       // default driver
+const algolia = useAlgolia()            // Algolia client
+const meili = useMeilisearch()          // Meilisearch client
+```
+
+## Document Operations
+
+```typescript
+// Index documents
+await search.addDocuments('products', [
+  { id: 1, name: 'Widget', description: 'A useful widget', price: 29.99 },
+  { id: 2, name: 'Gadget', description: 'A cool gadget', price: 49.99 }
+])
+
+// Search
+const results = await search.search('products', 'widget')
+
+// List indexes
+const indexes = await search.listIndexes()
+
+// Get/update settings
+const settings = await search.getSettings('products')
+await search.updateSettings('products', {
+  searchableAttributes: ['name', 'description'],
+  filterableAttributes: ['price', 'category'],
+  sortableAttributes: ['price', 'created_at']
+})
+
+// Flush all documents
+await search.flush('products')
+```
+
+## Model Integration (useSearch Trait)
+
+Models with `useSearch` trait are automatically indexed:
+
+```typescript
+defineModel({
+  name: 'Product',
+  traits: {
+    useSearch: {
+      displayable: ['name', 'description', 'price'],
+      searchable: ['name', 'description'],
+      sortable: ['name', 'price', 'created_at'],
+      filterable: ['category', 'status', 'price']
+    }
+  }
+})
+```
+
+## CLI Commands
+
+```bash
+buddy search-engine:update                    # index all searchable models
+buddy search-engine:update --model Product    # index specific model
+buddy search-engine:update --flush            # flush before re-indexing
+buddy search-engine:update --settings         # update search settings only
+buddy search-engine:settings                  # list current settings
+buddy search-engine:settings --model Product  # settings for specific model
+```
+
+## Driver Comparison
+
+| Feature | Meilisearch | Algolia |
+|---------|------------|---------|
+| Self-hosted | Yes | No (cloud) |
+| Pricing | Free (self-hosted) | Per-search pricing |
+| Typo tolerance | Built-in | Built-in |
+| Faceted search | Yes | Yes |
+| Geo search | Yes | Yes |
+| Speed | Very fast | Very fast |
+
+## config/search-engine.ts
+
+```typescript
+{ driver: 'opensearch' }  // 'meilisearch' | 'algolia' | 'opensearch'
+```
+
+Environment variables: `MEILISEARCH_HOST`, `MEILISEARCH_KEY`, `SEARCH_ENGINE_DRIVER`
+
+## Gotchas
+- Default driver is `opensearch` — configure in config or env
+- `useSearch` trait determines which model fields are indexed
+- `displayable` controls which fields appear in search results
+- `searchable` controls which fields are queried during search
+- `filterable` enables faceted filtering on those fields
+- `sortable` enables sorting by those fields
+- Use `buddy search-engine:update --flush` for full re-index
+- Meilisearch requires a running Meilisearch server
+- Algolia requires API keys from your Algolia dashboard
+- Settings updates don't re-index — run `search-engine:update` after changes

package/ai/skills/stacks-security/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: stacks-security
+description: Use when implementing security in Stacks — password hashing (bcrypt/argon2), app key generation, AES encryption/decryption, hash verification, rehashing detection, or security configuration (firewall, rate limiting, IP allowlists). Covers @stacksjs/security and config/security.ts.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Security
+
+## Key Paths
+- Core package: `storage/framework/core/security/src/`
+- Security config: `config/security.ts`
+- Hashing config: `config/hashing.ts`
+
+## Source Files
+```
+security/src/
+├── index.ts    # all exports
+├── key.ts      # generateAppKey()
+├── crypt.ts    # encrypt/decrypt (AES via APP_KEY)
+└── hash.ts     # password hashing (bcrypt/argon2)
+```
+
+## App Key Generation
+
+```typescript
+import { generateAppKey } from '@stacksjs/security'
+
+const key = generateAppKey()  // 32-character random string
+// Run via CLI: buddy key:generate
+```
+
+## Encryption / Decryption
+
+```typescript
+import { encrypt, decrypt } from '@stacksjs/security'
+
+const encrypted = await encrypt('sensitive data')           // uses APP_KEY
+const encrypted = await encrypt('data', 'custom-passphrase')
+const decrypted = await decrypt(encrypted)
+const decrypted = await decrypt(encrypted, 'custom-passphrase')
+```
+
+## Password Hashing
+
+```typescript
+import { make, check, needsRehash, info, detectAlgorithm } from '@stacksjs/security'
+
+// Hash a password
+const hash = await make('password123')                          // bcrypt (default)
+const hash = await make('password123', { algorithm: 'argon2' })
+const hash = await make('password123', { rounds: 14 })          // bcrypt rounds
+
+// Verify
+const valid = await check('password123', hash)  // true/false
+
+// Check if rehash needed (e.g., after changing rounds)
+const needs = needsRehash(hash, { rounds: 14 })
+
+// Inspect hash
+const hashInfo = info(hash)         // { algorithm, options }
+const algo = detectAlgorithm(hash)  // 'bcrypt' | 'argon2' | 'argon2id' | ...
+```
+
+### Aliases
+- `hashMake` = `make`
+- `hashCheck` = `check`
+- `hashNeedsRehash` = `needsRehash`
+- `hashInfo` = `info`
+- `makeHash` = `make`
+- `verifyHash` = `check`
+
+### Algorithm-Specific Functions
+```typescript
+bcryptEncode(value, rounds?)     // bcrypt hash
+bcryptVerify(value, hash)        // bcrypt verify
+argon2Encode(value, options?)    // argon2 hash
+argon2Verify(value, hash)        // argon2 verify
+md5Encode(value)                  // MD5 (legacy only)
+base64Encode(value)               // base64
+base64Verify(value, encoded)      // base64 compare
+```
+
+## HashMakeOptions
+```typescript
+interface HashMakeOptions {
+  algorithm?: 'bcrypt' | 'argon2' | 'argon2id' | 'argon2i' | 'argon2d'
+  rounds?: number      // bcrypt (default: 12)
+  memory?: number      // argon2 (default: 65536)
+  time?: number        // argon2 (default: 3)
+}
+```
+
+## config/hashing.ts
+```typescript
+{
+  driver: 'bcrypt',
+  bcrypt: { rounds: 12 },
+  argon2: { memory: 65536, time: 3 }
+}
+```
+
+## config/security.ts
+```typescript
+{
+  firewall: {
+    enabled: true,
+    countryCodes: [],                // block by country
+    ipAddresses: {
+      allowlist: [],
+      blocklist: []
+    },
+    rateLimitPerMinute: 500,
+    useIpReputationLists: true,
+    useKnownBadInputsRuleSet: true
+  }
+}
+```
+
+## Gotchas
+- Default hashing is bcrypt with 12 rounds — sufficient for most applications
+- `needsRehash()` compares current hash options against provided options — useful after config changes
+- APP_KEY is used for `encrypt()`/`decrypt()` — generate via `buddy key:generate`
+- APP_KEY format is colon-separated (validated during deployment)
+- Argon2 requires more memory/time but is more resistant to GPU attacks
+- `md5Encode()` exists for legacy compatibility only — never use for passwords
+- The firewall config is used by cloud deployment for WAF rules
+- Rate limiting is per-minute per-IP (500 default)

package/ai/skills/stacks-security-audit/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: stacks-security-audit
+description: Use when performing security analysis on a Stacks application — OWASP Top 10, STRIDE threat modeling, attack surface mapping, dependency audit. Requires concrete exploit scenarios. Invoke with /stacks-security-audit.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# /stacks-security-audit — Security Analysis
+
+You are performing a security analysis for a Stacks application. Be concrete — every finding must include a realistic exploit scenario. Vague warnings are worthless.
+
+## Determine Scope
+
+1. If the user specifies files or a feature, analyze that scope
+2. Otherwise, analyze: API routes (`routes/`), auth flows (`@stacksjs/auth`), middleware, data handling, config/services.ts
+
+## Step 1: Attack Surface Map
+
+```
+## Attack Surface
+
+| Entry Point | Type | Auth Required? | Input Validation |
+|-------------|------|----------------|------------------|
+| [route/handler] | [HTTP/CLI/WebSocket] | [yes/no] | [description] |
+```
+
+For Stacks specifically, check:
+- API routes in `routes/api.ts` (136+ routes auto-generated)
+- CLI command handlers via `buddy` (command injection via user args)
+- WebSocket endpoints (`@stacksjs/realtime`)
+- Config file parsing
+- Dev server endpoints (`rpx`, `localtunnels` exposure)
+- Dashboard routes (auth middleware applied?)
+- File upload handling via `EnhancedRequest.file()`
+
+## Step 2: OWASP Top 10
+
+Evaluate each applicable category. **Only report findings with confidence ≥ 8/10.**
+
+For each finding:
+1. **The vulnerability** — file:line reference
+2. **Exploit scenario** — step-by-step
+3. **Impact** — what attacker gains
+4. **Confidence** — 1-10
+5. **Fix** — concrete code change
+
+```
+### [OWASP Category]
+
+🔴 **[Finding]** (Confidence: [N]/10)
+
+**Location**: [file:line]
+**Vulnerability**: [what's wrong]
+
+**Exploit scenario**:
+1. Attacker does [X]
+2. System responds with [Y]
+3. Attacker gains [Z]
+
+**Impact**: [specific impact]
+**Fix**: [concrete change]
+```
+
+### Stacks-Specific Security Checks
+
+- **Auth token handling**: Check `@stacksjs/auth` for token validation, rotation (30d expiry, 7d rotation)
+- **Webhook URLs in `config/services.ts`**: Discord, Slack, Stripe keys — are they properly secured?
+- **ORM injection**: Check if user input flows unsanitized into query builder `.where()` calls
+- **Middleware gaps**: Are admin routes protected by `auth` middleware? Check `routes/api.ts` group middleware
+- **Rate limiting**: Is `throttle` middleware applied to auth endpoints?
+- **Passkey handling**: Check `@stacksjs/auth` passkey credential storage
+- **File uploads**: Check `EnhancedRequest.file()` for path traversal, size limits
+- **Maintenance mode bypass**: Check secret URL mechanism in Maintenance middleware
+
+## Step 3: STRIDE Threat Model
+
+| Threat | Question | Finding |
+|--------|----------|---------|
+| **Spoofing** | Can someone impersonate a user/service? | |
+| **Tampering** | Can data be modified in transit/rest? | |
+| **Repudiation** | Can actions happen without traces? | |
+| **Information Disclosure** | Can unauthorized data be accessed? | |
+| **Denial of Service** | Can the system be made unavailable? | |
+| **Elevation of Privilege** | Can higher privileges be gained? | |
+
+## Step 4: Dependency Audit
+
+1. Read `package.json` for direct dependencies
+2. Check for known vulnerabilities
+3. Flag overly permissive version ranges
+4. Check dependencies with filesystem/network/child_process access
+
+## Output Format
+
+```
+# Security Analysis: [scope]
+
+## Attack Surface
+[table]
+
+## Critical Findings (Confidence ≥ 8/10)
+[findings sorted by severity]
+
+## STRIDE Assessment
+[table]
+
+## Dependency Audit
+[findings]
+
+## Lower Confidence Observations
+[< 8/10 findings]
+
+## Summary
+- Critical findings: [count]
+- Risk: [LOW / MEDIUM / HIGH / CRITICAL]
+```
+
+## Rules
+
+- **Concrete exploits only.** "Doesn't validate input" is not a finding. Show the exact exploit.
+- **8/10 confidence threshold.** False positives erode trust.
+- **No theoretical threats.** If the code doesn't handle XML, skip XXE.
+- **Never suggest security-through-obscurity.**
+
+## Downstream
+
+> **Security analysis complete.** Run `/stacks-review` to verify fixes against these findings.