start-vibing-stacks 2.6.0 → 2.7.3

package/stacks/_shared/skills/secrets-management/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: secrets-management
+version: 1.0.0
+description: Environment variable hygiene, secret detection, rotation, and secret-store patterns. Invoke whenever .env, secrets, API keys, or env-var-reading code are touched.
+---
+
+# Secrets Management
+
+**ALWAYS invoke when touching `.env`, `process.env`, `os.environ`, secrets, API keys, or auth credentials.**
+
+## Core Rules
+
+1. **No secrets in code, ever.** Not in tests, not in fixtures, not in comments.
+2. **No secrets in logs.** Redact before logging.
+3. **No secrets in URLs / query strings.** Headers or body only — URLs land in proxy logs.
+4. **No secrets in error messages** returned to clients.
+5. **`.env` is in `.gitignore`. `.env.example` is committed.** No exceptions.
+6. **Rotate after any leak.** Even suspected. The risk window is the time it takes to rotate, not when you think the leak started.
+
+---
+
+## File Layout
+
+```
+.env                  # gitignored, real values, local dev
+.env.example          # committed, placeholders only
+.env.production       # NEVER committed; use platform secret store
+.env.test             # gitignored if real keys; committed if all-fake
+```
+
+`.gitignore`:
+```
+.env
+.env.*
+!.env.example
+!.env.test.example
+```
+
+`.env.example` template:
+```bash
+# Application
+NODE_ENV=development
+APP_URL=http://localhost:3000
+
+# Database
+DATABASE_URL=postgres://user:pass@localhost:5432/dbname
+
+# Auth
+JWT_SECRET=<generate: openssl rand -base64 32>
+SESSION_SECRET=<generate: openssl rand -base64 32>
+
+# Third-party (use service prefix to scan with allowlists)
+STRIPE_SECRET_KEY=sk_test_...
+OPENAI_API_KEY=sk-...
+```
+
+---
+
+## Reading Env Vars Safely
+
+### Node.js / TypeScript
+```ts
+// Validate at boot — fail fast if missing
+import { z } from 'zod';
+
+const Env = z.object({
+  NODE_ENV: z.enum(['development', 'test', 'production']),
+  DATABASE_URL: z.string().url(),
+  JWT_SECRET: z.string().min(32),
+  STRIPE_SECRET_KEY: z.string().startsWith('sk_'),
+});
+
+export const env = Env.parse(process.env);
+// Now `env.JWT_SECRET` is typed and guaranteed present
+```
+
+Bracket notation only (`tsconfig` strict):
+```ts
+process.env['JWT_SECRET']   // CORRECT
+```
+
+### Python
+```python
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", extra="forbid")
+    database_url: str
+    jwt_secret: str
+    stripe_secret_key: str
+
+settings = Settings()  # raises if missing/invalid
+```
+
+### PHP / Laravel
+```php
+// config/services.php — read once, cached via `php artisan config:cache`
+return [
+    'stripe' => ['secret' => env('STRIPE_SECRET_KEY')],
+];
+// Use config('services.stripe.secret') in app code — NEVER env() at runtime
+```
+
+---
+
+## Public vs Server-Only Vars
+
+| Stack | Public prefix | Rule |
+|---|---|---|
+| Next.js | `NEXT_PUBLIC_` | Anything with this prefix is shipped to the browser |
+| Vite | `VITE_` | Same — bundled into JS |
+| CRA | `REACT_APP_` | Same |
+
+`security-rules.json` enforces: nothing matching `*SECRET|*TOKEN|*PRIVATE|*PASSWORD|*CREDENTIAL` may have a public prefix.
+
+---
+
+## Secret Stores (Production)
+
+| Tool | When |
+|---|---|
+| **Vercel/Netlify env vars** | Simple deployments |
+| **AWS Secrets Manager** / **GCP Secret Manager** / **Azure Key Vault** | Cloud-native, IAM-scoped |
+| **Doppler** | Multi-environment sync |
+| **HashiCorp Vault** | On-prem / self-hosted, dynamic creds |
+| **SOPS + age** | Git-encrypted secrets (GitOps) |
+| **1Password Connect / op-cli** | Team-shared dev secrets |
+
+**Rule:** `.env.production` is **never** committed. Production secrets live in the platform store and are injected at deploy/runtime.
+
+---
+
+## Detection — Block Before Commit
+
+### gitleaks (recommended)
+
+Install:
+```bash
+brew install gitleaks       # macOS
+# or: docker run --rm -v $(pwd):/repo zricethezav/gitleaks:latest detect -s /repo
+```
+
+Pre-commit hook:
+```bash
+gitleaks protect --staged --redact --verbose
+```
+
+CI step:
+```yaml
+- name: Gitleaks scan
+  uses: gitleaks/gitleaks-action@v2
+```
+
+### Quick grep (as a fallback)
+
+```bash
+# Block obvious patterns in staged diff
+git diff --cached -U0 | grep -nEi \
+  '(api[_-]?key|secret|token|bearer|password|aws_(access|secret)|private_key)\s*[:=]\s*["'\''][a-zA-Z0-9/+=_-]{16,}'
+```
+
+---
+
+## Rotation Playbook
+
+When a secret leaks (or is suspected):
+
+1. **Revoke** at the provider immediately. Do not wait for git history rewrites.
+2. **Issue new secret**, deploy with new value.
+3. **Update audit log** — what leaked, when, who, scope of access.
+4. **Scan history**: `gitleaks detect --log-opts="--all"` — find every commit/branch that contained it.
+5. **History rewrite is optional** — git filter-repo / BFG only if you also rotate. The leaked secret in history is already gone from the world's POV once rotated.
+6. **Notify** — if customer data was reachable with the leaked secret, follow incident-disclosure policy.
+
+Token lifetimes (default targets):
+- Access token: ≤ 15 min
+- Refresh token: ≤ 7 days, rotated on use
+- Service-to-service token: ≤ 90 days, rotated automatically
+- Long-lived (e.g. cron API keys): document expiry, calendar reminder
+
+---
+
+## Logging Without Leaks
+
+```ts
+// Redact known fields before logging
+const REDACT = ['password', 'token', 'authorization', 'cookie', 'secret', 'apiKey', 'creditCard'];
+
+function safeLog(obj: unknown) {
+  return JSON.parse(JSON.stringify(obj, (key, val) =>
+    REDACT.some(r => key.toLowerCase().includes(r.toLowerCase())) ? '[REDACTED]' : val
+  ));
+}
+
+logger.info({ event: 'login_attempt', body: safeLog(req.body) });
+```
+
+Use `pino-noir`, `winston`'s `format.printf` filter, or your APM's redaction. Same for Python: `structlog` processors; PHP: Monolog `RedactProcessor`.
+
+See `observability` skill for full structured-logging setup.
+
+---
+
+## Supply-Chain Hygiene
+
+| Stack | Audit |
+|---|---|
+| Node.js | `npm audit --audit-level=high`, `bun audit`, `pnpm audit` |
+| Python | `pip-audit`, `safety check` |
+| PHP | `composer audit` |
+
+Lockfile rules:
+- **Always commit** `package-lock.json` / `bun.lock` / `pnpm-lock.yaml` / `poetry.lock` / `uv.lock` / `composer.lock`.
+- **Renovate** or **Dependabot** for automated PRs.
+- Pin major versions; allow minor/patch auto-merge after CI passes.
+
+---
+
+## FORBIDDEN
+
+| Pattern | Reason |
+|---|---|
+| `.env` committed | Trivial leak |
+| Secret in `README.md` / docstring | Leaks via search engines |
+| Secret in test fixtures | Leaks via PR diffs / forks |
+| Secret in `console.log` / `print` / `Log::info` | Ends up in CloudWatch / Datadog forever |
+| Secret in URL query string | Logged by every proxy in the chain |
+| Secret in commit message | Cannot delete, history rewrites costly |
+| `process.env.SECRET ?? "fallback-value"` with real fallback | Hardcoded backup secret |
+| Sharing via Slack/email | Use 1Password / Vault sharing |
+
+## Pre-Commit Checklist
+
+- [ ] `.env` in `.gitignore`
+- [ ] `.env.example` updated when new var added
+- [ ] gitleaks (or fallback grep) clean
+- [ ] No secret in code, tests, fixtures, comments, logs
+- [ ] No `NEXT_PUBLIC_*SECRET|*TOKEN|*PRIVATE` patterns
+- [ ] Env vars validated at boot (Zod / Pydantic / config())
+
+## See Also
+
+- `security-baseline` — broader OWASP scope
+- `observability` — log redaction details
+- Stack `api-security-*` — usage patterns

package/stacks/_shared/skills/security-baseline/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: security-baseline
+version: 1.0.0
+description: Universal OWASP Top 10 baseline with stack-aware examples. Invoke before designing or reviewing any feature that touches user data, auth, persistence, or external IO.
+---
+
+# Security Baseline — OWASP Top 10 (2021)
+
+**ALWAYS invoke when designing auth, APIs, persistence, file uploads, or any user-input flow.**
+
+> Threat model first. Then code. Defense in depth: every layer assumes the previous one failed.
+
+## Core Principles
+
+1. **Trust no input** — validate at every boundary (HTTP, queue, file, env, IPC).
+2. **Least privilege** — minimum scopes, minimum table access, minimum filesystem rights.
+3. **Fail closed** — on error, deny. Never default to "allow on exception".
+4. **Defense in depth** — auth + authz + input validation + output encoding + audit log.
+5. **No security by obscurity** — assume attacker has source code.
+
+---
+
+## A01 — Broken Access Control
+
+| Anti-pattern | Fix |
+|---|---|
+| User ID from request body/query | Always derive from session/JWT |
+| Unscoped `Model.findById(id)` | Scope by owner: `where userId == session.userId` |
+| Role check in frontend only | Re-check on server |
+| IDOR (sequential IDs leak existence) | Use UUIDs **and** authz check |
+
+### Node.js (Next.js / Express)
+```ts
+// WRONG — uses body userId
+const userId = req.body.userId;
+const orders = await Order.find({ userId });
+
+// CORRECT — derives from session
+const session = await auth();
+if (!session) throw new UnauthorizedError();
+const orders = await Order.find({ userId: session.user.id });
+```
+
+### Python (FastAPI)
+```python
+# CORRECT — Depends() resolves authenticated user
+@app.get("/orders")
+async def list_orders(user: User = Depends(current_user)):
+    return await Order.filter(user_id=user.id).all()
+```
+
+### PHP (Laravel)
+```php
+// CORRECT — Policy + scoped query
+$orders = $request->user()->orders()->get();
+$this->authorize('view', $order);
+```
+
+---
+
+## A02 — Cryptographic Failures
+
+- **Never** use MD5/SHA1 for passwords. Use bcrypt/argon2/scrypt.
+- **TLS everywhere**. HSTS header in production.
+- **Cookies**: `HttpOnly`, `Secure`, `SameSite=Strict|Lax`.
+- **Secrets** never in code, never in logs, never in URLs.
+- **JWT**: short expiry (15m access, 7d refresh), rotate refresh tokens, signed with strong secret.
+
+```ts
+// Node.js password hashing
+import { hash, verify } from '@node-rs/argon2';
+const hashed = await hash(password, { memoryCost: 19456, timeCost: 2 });
+const ok = await verify(hashed, attempt);
+```
+
+---
+
+## A03 — Injection
+
+| Type | Fix |
+|---|---|
+| SQL | Parameterized queries / ORM with bindings |
+| NoSQL | Sanitize operators (`$where`, `$regex`) — never accept raw object from user |
+| Command | `execFile` with array args, never `exec` with string |
+| LDAP/XPath/Template | Library-specific escapers |
+| Header injection | Strip `\r\n` from any user-controlled header value |
+
+```ts
+// WRONG — Mongo operator injection
+User.findOne({ email: req.body.email });
+// If body is { email: { $ne: null } } → returns first user
+
+// CORRECT — coerce to string/Zod parse first
+const { email } = z.object({ email: z.string().email() }).parse(req.body);
+User.findOne({ email });
+```
+
+---
+
+## A04 — Insecure Design
+
+- Threat-model **before** coding new flows. Document threats in `domain.md`.
+- Anti-automation: rate limit, CAPTCHA on signup/login/password reset.
+- Business logic limits: max items per cart, max API calls per minute, max file size.
+
+---
+
+## A05 — Security Misconfiguration
+
+- Disable directory listings, default accounts, sample apps.
+- Set security headers: `Content-Security-Policy`, `X-Content-Type-Options: nosniff`, `Referrer-Policy`, `Permissions-Policy`.
+- Error messages: generic to clients, detailed in server logs only.
+- `NODE_ENV=production` / `APP_DEBUG=false` in prod — verify in CI.
+
+---
+
+## A06 — Vulnerable Components
+
+- Run `npm audit` / `pip-audit` / `composer audit` in CI.
+- Pin lockfiles. Use Dependabot/Renovate.
+- See `supply-chain` notes in `secrets-management` skill.
+
+---
+
+## A07 — Authentication Failures
+
+- Lockout after N failed attempts (with exponential backoff or CAPTCHA, **not** permanent — DoS risk).
+- Require MFA for admin/sensitive actions.
+- Rotate session token on login, logout, password change, privilege change.
+- Password reset tokens: single-use, expire ≤ 1h, sent to email of record.
+
+---
+
+## A08 — Software & Data Integrity
+
+- Verify signatures on dependencies where possible (Sigstore, npm provenance).
+- Sign artifacts in CI/CD.
+- Validate webhook signatures (Stripe, GitHub, etc.) **before** parsing body.
+
+```ts
+// Stripe webhook — verify FIRST
+const sig = req.headers['stripe-signature'];
+const event = stripe.webhooks.constructEvent(rawBody, sig, secret);
+```
+
+---
+
+## A09 — Security Logging Failures
+
+- Log: auth events, authz denials, validation failures, admin actions, payment events.
+- Never log: passwords, tokens, full PAN, full SSN, raw cookies, secrets.
+- Use correlation IDs to trace a request across services. See `observability` skill.
+
+---
+
+## A10 — Server-Side Request Forgery (SSRF)
+
+- Allowlist outbound destinations when fetching user-supplied URLs.
+- Block private IP ranges (10/8, 172.16/12, 192.168/16, 169.254/16, ::1, fc00::/7).
+- Resolve DNS yourself and check the IP — defeats DNS rebinding.
+
+```ts
+import { isIP } from 'net';
+const PRIVATE = /^(10\.|172\.(1[6-9]|2\d|3[01])\.|192\.168\.|127\.|169\.254\.|::1|fc|fd)/i;
+const url = new URL(userUrl);
+const ip = await dns.lookup(url.hostname);
+if (PRIVATE.test(ip.address)) throw new ForbiddenError('Private IP not allowed');
+```
+
+---
+
+## Mandatory Boundary Validation
+
+Every external input MUST be validated by a schema:
+
+| Stack | Library |
+|---|---|
+| Node.js | Zod (`zod-validation` skill) |
+| Python | Pydantic (`pydantic-validation` skill) |
+| PHP | FormRequest + rules |
+
+No exceptions for "trusted" sources. Internal services drift, queues replay malformed payloads, env files are edited by hand.
+
+---
+
+## Pre-Commit Security Checklist
+
+- [ ] All routes have authn + authz checks
+- [ ] User ID derived from session, never from body
+- [ ] All inputs validated by schema
+- [ ] No secrets in code (see `secrets-management`)
+- [ ] No raw SQL / Mongo operators from user input
+- [ ] Security headers set on responses
+- [ ] Rate limit on auth + write endpoints
+- [ ] PII not in logs (see `observability`)
+- [ ] Webhook signatures verified before parsing
+
+## See Also
+
+- `secrets-management` — env hygiene, gitleaks
+- `observability` — log redaction
+- `api-security-node` / `api-security-python` / PHP `api-security` — stack-specific hardening

package/stacks/_shared/skills/test-coverage/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: test-coverage
+version: 1.0.0
+---
+
 # Test Coverage — Testing Management
 
 **ALWAYS invoke AFTER implementing any feature. Do NOT skip.**

package/stacks/_shared/skills/ui-ux-audit/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: ui-ux-audit
+version: 1.0.0
+---
+
 # UI/UX Audit
 
 **ALWAYS invoke BEFORE implementing any UI feature.**

package/stacks/frontend/react/skills/preline-ui/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: preline-ui
+version: 1.0.0
+---
+
 # Preline UI — Component & Theme System for TailwindCSS 4
 
 **ALWAYS invoke when using Preline components, creating themes, or customizing design tokens.**

package/stacks/frontend/react/skills/react-patterns/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: react-patterns
+version: 1.0.0
+---
+
 # React Patterns — Modern Component Architecture
 
 **ALWAYS invoke when writing React components, hooks, or state management.**

package/stacks/frontend/react/skills/react-standards/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: react-standards
+version: 1.0.0
+---
+
 # React 19+ Standards
 
 ## Version Requirements

package/stacks/frontend/react/skills/react-ui-patterns/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: react-ui-patterns
+version: 1.0.0
+---
+
 # React UI Patterns — Loading, Errors, Empty States & Forms
 
 **ALWAYS invoke when handling async UI states, forms, or user feedback.**

package/stacks/frontend/react/skills/shadcn-ui/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: shadcn-ui
+version: 1.0.0
+---
+
 # shadcn/ui — Component Library Patterns
 
 **ALWAYS invoke when adding or modifying shadcn/ui components.**

package/stacks/frontend/react/skills/tailwind-patterns/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: tailwind-patterns
+version: 1.0.0
+---
+
 # TailwindCSS 4 — CSS-First Design System
 
 **ALWAYS invoke when writing Tailwind classes, theming, or responsive layouts.**

package/stacks/frontend/react/skills/zod-validation/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: zod-validation
+version: 1.0.0
+---
+
 # Zod Validation — Runtime Type Safety
 
 **ALWAYS use Zod for form validation, API responses, and data boundaries.**

package/stacks/frontend/react-inertia/skills/inertia-react/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: inertia-react
+version: 1.0.0
+---
+
 # Inertia.js + React Integration
 
 ## Architecture Overview

package/stacks/frontend/react-inertia/skills/react-standards/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: react-standards
+version: 1.0.0
+---
+
 # React 19+ Standards (with Inertia.js)
 
 ## Version Requirements