start-vibing-stacks 2.14.0 → 2.16.0

package/stacks/_shared/skills/research-cache/SKILL.md

@@ -1,62 +1,139 @@
 ---
 name: research-cache
-version: 1.0.0
+version: 2.0.0
+description: "Caches web research findings under `.claude/skills/research-cache/cache/` to avoid redundant searches. Each entry has YAML frontmatter (`expires_on`, `sources`, `tier`, `engines`) so a session can grep-filter fresh entries without reading the body. Consumed by `research-web` v2.0.0 BEFORE any MCP / WebSearch call."
 ---
 
-# Research Cache — Best Practices Storage
+# Research Cache — Best-Practices Storage (v2.0.0)
 
-**ALWAYS invoke BEFORE any web research.**
+**ALWAYS invoke BEFORE any web research.** This skill is the **read AND write** side of `research-web` v2.0.0.
 
-## Purpose
-
-Caches research findings to avoid redundant searches and maintain institutional knowledge.
-
-## Structure
+## Layout
 
 ```
 .claude/skills/research-cache/
 ├── SKILL.md
 └── cache/
-    ├── php-uuid-performance.md
-    ├── laravel-octane-memory.md
-    └── [topic].md
+    ├── _index.json                    # auto-derived, optional (one record per cache entry)
+    └── <topic-slug>.md                # one file per topic. ≤ 8 KB. Pruned at expires_on.
+```
+
+## Cache entry frontmatter (token-efficient lookup)
+
+Every cache entry MUST start with this frontmatter so a `grep` over `cache/*.md` filters fresh entries without parsing bodies:
+
+```yaml
+---
+topic: <kebab-case>
+stack: php | nodejs | python | universal | frontend
+researched_on: YYYY-MM-DD
+expires_on: YYYY-MM-DD            # researched_on + 30 days (60 for stable specs, 14 for moving libraries)
+tier: 1 | 2                       # 1 = MCP web-scraper used; 2 = built-in WebSearch fallback
+engines: [brave, vertex, grok]    # which engines contributed (Tier 1 only)
+sources_count: <int>
+confidence: high | medium | low   # high = 3+ official-doc sources agree; low = single blog post
+---
 ```
 
-## Before Searching
+## Read protocol (lookup BEFORE searching)
 
-1. Check cache: `ls .claude/skills/research-cache/cache/`
-2. Grep for topic: `grep -rl "topic" .claude/skills/research-cache/cache/`
-3. If found and recent (<30 days) → USE CACHE
-4. If not found → Research and CREATE cache entry
+```bash
+TOPIC="<kebab-case>"
+TODAY=$(date +%F)
 
-## Cache Entry Template
+# 1. Direct hit?
+F=".claude/skills/research-cache/cache/${TOPIC}.md"
+if [ -f "$F" ]; then
+  EXPIRES=$(awk -F': ' '/^expires_on:/{print $2; exit}' "$F")
+  [ "$EXPIRES" \> "$TODAY" ] && echo "FRESH cache hit: $F" && exit 0
+  echo "STALE: $F (expired $EXPIRES); will refresh"
+fi
+
+# 2. Fuzzy hit? (alias / synonym)
+grep -l "topic:.*${TOPIC%%-*}" .claude/skills/research-cache/cache/*.md 2>/dev/null
+```
+
+If FRESH → use the cache, do NOT re-search.
+If STALE or MISSING → research, then write a new entry (overwrite or create).
+
+## Write protocol (after research)
+
+Always overwrite — never append. Stale data is worse than missing data.
+
+### Body template
 
 ```markdown
-# Research: {Topic}
+---
+topic: <kebab-case>
+stack: <one-of>
+researched_on: 2026-05-13
+expires_on: 2026-06-12
+tier: 1
+engines: [brave, vertex, grok]
+sources_count: 5
+confidence: high
+---
+
+# Research: <Topic Title>
 
-**Date:** YYYY-MM-DD
-**Stack:** PHP|Node.js|Universal
-**Sources:** [list]
-**Expires:** YYYY-MM-DD (30 days from research)
+> **TL;DR** (≤ 3 lines). The actionable answer in 30 seconds.
 
-## Key Findings
-1. Finding — Source: [URL]
+## Findings (cited)
+
+| # | Finding | Source | Date | Tier |
+|---|---|---|---|---|
+| 1 | <one-line> | https://docs.example.com/foo | 2026-04-12 | official |
+| 2 | <one-line> | https://eng-blog.example.com/bar | 2026-03-30 | engineering |
 
 ## Recommendations
-- Actionable recommendation
 
-## Code Examples
-\`\`\`php
-// Example implementation
-\`\`\`
+- <actionable rule, ready to drop into a skill or CLAUDE.md>
+- <do this, not that>
+
+## Anti-patterns
+
+- <something to avoid + why>
+
+## Code reference (optional)
+
+- File / line / commit pointing at where this rule should be applied — NOT inline code dumps.
+
+## Open questions
 
-## References
-- [URL] — [Description]
+- <thing the research did NOT answer; flag for next round>
 ```
 
+## Expiry policy (cost vs freshness)
+
+| Topic kind | TTL | Example |
+|---|---|---|
+| Specification (W3C, RFC, OpenAPI) | 60 days | WCAG 2.2 conformance |
+| Stable framework (Laravel, Django, Express) | 30 days | Laravel 12 sessions |
+| Fast-moving library (any minor < 1.0, anything pre-release) | 14 days | shadcn registries, AI SDKs |
+| Security advisory | 7 days | CVE feeds, OWASP draft |
+
+After `expires_on`, the entry is read-only history — `research-web` will refresh it on the next lookup.
+
+## Source ranking (recorded in each finding row)
+
+1. **official** — vendor docs, RFCs, W3C, MDN
+2. **engineering** — engineering blogs of the project (vercel.com/blog, fastify.io/blog)
+3. **community** — high-signal: Stack Overflow with 50+ votes, GitHub issues with maintainer response
+4. **opinion** — random blog post — accepted only if it confirms an official-doc claim, never as primary
+
 ## Rules
 
-1. **CHECK CACHE FIRST** — avoid redundant searches
-2. **CITE SOURCES** — every finding needs URL
-3. **DATE ENTRIES** — for freshness checks
-4. **STACK-SPECIFIC** — tag by stack for filtering
+1. **CHECK CACHE FIRST** — frontmatter `expires_on` lookup is one `awk`. Cheaper than any web call.
+2. **OVERWRITE, NEVER APPEND** — stale information is worse than missing.
+3. **CITE EVERY FINDING** — URL + date + tier. No bare claims.
+4. **TTL BY TOPIC KIND** — see table above. A spec lasts longer than a pre-release library.
+5. **CONFIDENCE EXPLICIT** — `high` requires ≥ 3 official-doc sources agreeing; `low` is single source.
+6. **NO INLINE CODE DUMPS** — link to file/line; the model can `Read` when it needs the bytes.
+7. **NO PII / SECRETS / CUSTOMER DATA** — never quote env values, tokens, internal hostnames.
+8. **PROMOTE WHAT'S UNIVERSAL** — if a rule applies project-wide, surface it for inclusion in `CLAUDE.md` (do not auto-edit).
+
+## See Also
+
+- `research-web` v2.0.0 — MCP-first researcher; reads/writes this cache
+- `claude-md-compactor` v2.0.0 — receives promoted rules; enforces 20 KB CLAUDE.md budget
+- `mcp-web-scraper` skill — the MCP server providing Tier 1 search/scrape capability

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

@@ -1,12 +1,14 @@
 ---
 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.
+version: 2.0.0
+description: "Environment variable hygiene, OIDC federation for CI/CD (2026 default — replaces long-lived static secrets), secret detection (gitleaks 3-layer: pre-commit + CI + GitHub push protection), rotation, and secret-store patterns. Invoke whenever .env, secrets, API keys, env-var-reading code, or CI cloud-deploy credentials are touched."
 ---
 
 # Secrets Management
 
-**ALWAYS invoke when touching `.env`, `process.env`, `os.environ`, secrets, API keys, or auth credentials.**
+**ALWAYS invoke when touching `.env`, `process.env`, `os.environ`, secrets, API keys, auth credentials, or CI workflows that authenticate to cloud providers.**
+
+> 2026 reality check: **28.65 million** new hardcoded secrets were added to public GitHub repositories in 2025 (+34% YoY, source: Snyk State of Secrets). The threat model is "an attacker is already scanning every commit you push, in real time."
 
 ## Core Rules
 
@@ -16,6 +18,7 @@ description: Environment variable hygiene, secret detection, rotation, and secre
 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.
+7. **Prefer OIDC federation over static cloud creds in CI.** A leaked OIDC trust policy needs branch-+-repo match to be exploited; a leaked AWS access key works from anywhere until rotated.
 
 ---
 
@@ -122,35 +125,115 @@ return [
 | **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) |
+| **HashiCorp Vault** | On-prem / self-hosted, dynamic creds (auto-revoked) |
+| **SOPS + age** | Git-encrypted secrets (GitOps) — `age` recommended over PGP for new repos (no keyring management, single-line keys) |
 | **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.
 
+### 2026 reference architecture (defense in depth)
+
+1. **Short-lived credentials via OIDC** for CI/CD → no static cloud secrets
+2. **Encrypted secrets in Git via SOPS+age** for app config that must travel with code
+3. **Dynamic secrets via Vault** for DB/API tokens generated on-demand and auto-revoked
+
 ---
 
-## Detection — Block Before Commit
+## OIDC Federation — CI/CD Without Static Cloud Secrets *(2026 default)*
+
+GitHub Actions presents a JWT to the cloud's STS; cloud returns a short-lived (≤ 1h) credential. **No long-lived `AWS_SECRET_ACCESS_KEY` in repo secrets.**
+
+### AWS — IAM Role + Trust Policy
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [{
+    "Effect": "Allow",
+    "Principal": { "Federated": "arn:aws:iam::ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com" },
+    "Action": "sts:AssumeRoleWithWebIdentity",
+    "Condition": {
+      "StringEquals": {
+        "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
+      },
+      "StringLike": {
+        "token.actions.githubusercontent.com:sub": "repo:my-org/my-repo:ref:refs/heads/main"
+      }
+    }
+  }]
+}
+```
 
-### gitleaks (recommended)
+```yaml
+permissions:
+  id-token: write              # MANDATORY for OIDC
+  contents: read
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: arn:aws:iam::ACCOUNT_ID:role/gha-deployer
+          aws-region: us-east-1
+      - run: aws s3 sync ./dist s3://my-bucket
+```
+
+### GCP — Workload Identity Federation
+```yaml
+- uses: google-github-actions/auth@v2
+  with:
+    workload_identity_provider: 'projects/.../providers/github'
+    service_account: 'gha-deployer@my-project.iam.gserviceaccount.com'
+```
+
+### npm publish — provenance via OIDC (no `NPM_TOKEN`)
+```yaml
+permissions:
+  id-token: write
+  contents: read
+- run: npm publish --provenance --access public
+```
+
+**Anti-pattern:** storing `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` as repo secrets. If you can use OIDC, you must.
+
+---
+
+## Detection — Three-Layer Defense *(2026 standard)*
+
+A single layer is insufficient. Deploy **all three** so a bypass at one layer is caught at the next.
+
+### Layer 1 — Local pre-commit hook (developer machine)
+
+Catches before the secret ever leaves the laptop.
 
-Install:
 ```bash
 brew install gitleaks       # macOS
 # or: docker run --rm -v $(pwd):/repo zricethezav/gitleaks:latest detect -s /repo
 ```
 
-Pre-commit hook:
+`.git/hooks/pre-commit` (or via `pre-commit` framework):
 ```bash
 gitleaks protect --staged --redact --verbose
 ```
 
-CI step:
+Gitleaks ships rules for **150+ credential patterns** (AWS, GCP, GitHub, Stripe, OpenAI, Anthropic, Slack, JWT, private keys, etc.).
+
+### Layer 2 — CI scan on every PR (server-side)
+
+Blocks PRs that slipped past Layer 1.
+
 ```yaml
 - name: Gitleaks scan
   uses: gitleaks/gitleaks-action@v2
+  env:
+    GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }}   # only needed for org accounts
 ```
 
+### Layer 3 — GitHub Push Protection (platform-side)
+
+Enable in **Settings → Code security → Secret scanning → Push protection**. GitHub's own scanner blocks the `git push` itself for known provider patterns. Free for public repos; **GitHub Advanced Security** for private.
+
 ### Quick grep (as a fallback)
 
 ```bash
@@ -233,13 +316,16 @@ Lockfile rules:
 
 - [ ] `.env` in `.gitignore`
 - [ ] `.env.example` updated when new var added
-- [ ] gitleaks (or fallback grep) clean
+- [ ] gitleaks (Layer 1) clean
 - [ ] No secret in code, tests, fixtures, comments, logs
 - [ ] No `NEXT_PUBLIC_*SECRET|*TOKEN|*PRIVATE` patterns
 - [ ] Env vars validated at boot (Zod / Pydantic / config())
+- [ ] CI workflows that touch cloud use **OIDC**, not static keys
+- [ ] GitHub Push Protection enabled on the repo
 
 ## See Also
 
-- `security-baseline` — broader OWASP scope
+- `security-baseline` — broader OWASP scope (2025-A03 Software Supply Chain Failures)
 - `observability` — log redaction details
+- `ci-pipelines` — OIDC patterns + workflow permissions
 - Stack `api-security-*` — usage patterns

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

@@ -1,15 +1,38 @@
 ---
 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.
+version: 2.0.0
+description: "Universal OWASP Top 10 baseline with stack-aware examples. Covers BOTH OWASP 2021 (numbering kept stable for security-auditor §A01–§A10 cross-references) AND OWASP 2025 deltas (Software Supply Chain Failures new at A03, Mishandling Exceptional Conditions new at A10, SSRF demoted into Broken Access Control). Invoke before designing or reviewing any feature that touches user data, auth, persistence, supply chain, or external IO."
 ---
 
-# Security Baseline — OWASP Top 10 (2021)
+# Security Baseline — OWASP Top 10 (2021 + 2025 deltas)
 
-**ALWAYS invoke when designing auth, APIs, persistence, file uploads, or any user-input flow.**
+**ALWAYS invoke when designing auth, APIs, persistence, file uploads, supply-chain integrations, or any user-input flow.**
 
 > Threat model first. Then code. Defense in depth: every layer assumes the previous one failed.
 
+## OWASP Top 10 — 2021 vs 2025 (released Nov 2025)
+
+OWASP Top 10:2025 was published at OWASP Global AppSec DC in November 2025. Material changes:
+
+| 2021 | 2025 | Status |
+|---|---|---|
+| A01 Broken Access Control | A01 Broken Access Control | Same #1; **SSRF folded in here** |
+| A02 Cryptographic Failures | A04 Cryptographic Failures | Demoted |
+| A03 Injection | A05 Injection | Demoted |
+| A04 Insecure Design | A06 Insecure Design | Demoted |
+| A05 Security Misconfiguration | **A02 Security Misconfiguration** | Promoted (most observed) |
+| A06 Vulnerable Components | (covered by 2025-A03) | Subsumed |
+| A07 Authentication Failures | A07 Authentication Failures | Same |
+| A08 Software & Data Integrity | A08 Software or Data Integrity Failures | Same |
+| A09 Security Logging Failures | A09 Security Logging and Alerting Failures | Same |
+| A10 SSRF | (folded into A01) | **Removed as a top-10 category — STILL DANGEROUS, see A01** |
+| — | **A03 Software Supply Chain Failures** | **NEW** (was A06 Vulnerable Components, expanded) |
+| — | **A10 Mishandling of Exceptional Conditions** | **NEW** (error handling that fails open / leaks state) |
+
+**This skill keeps the §A01–§A10 anchors using the 2021 numbering** because cross-references in `security-auditor` v2.0.0, `api-security-*` skills, and stack overlays already cite them. The 2025 deltas are documented inline (see §A03+, §A06, §A10 sections).
+
+---
+
 ## Core Principles
 
 1. **Trust no input** — validate at every boundary (HTTP, queue, file, env, IPC).
@@ -114,11 +137,41 @@ User.findOne({ email });
 
 ---
 
-## A06 — Vulnerable Components
+## A06 — Vulnerable Components  *(2025: subsumed into the new A03 — Software Supply Chain Failures)*
 
 - Run `npm audit` / `pip-audit` / `composer audit` in CI.
 - Pin lockfiles. Use Dependabot/Renovate.
-- See `supply-chain` notes in `secrets-management` skill.
+- See `supply-chain` notes in `secrets-management` skill and the **A03+ (2025) Software Supply Chain Failures** section below.
+
+---
+
+## A03+ (2025 only) — Software Supply Chain Failures *(NEW in 2025)*
+
+Expanded from 2021's A06. Treats the **build, dependency, and distribution pipeline** as part of the threat surface.
+
+| Threat | Mitigation |
+|---|---|
+| Malicious dependency (typosquat, dependency confusion) | Lock to private registries first; pin by hash where possible (npm `--integrity`, pip hashes) |
+| Compromised maintainer / token | Require 2FA on maintainer accounts; mandatory provenance for first-party publishes |
+| Build pipeline injection | Pin GitHub Actions by SHA, not tag; least-privilege `permissions:`; OIDC for cloud auth |
+| Unsigned artifacts | Sign releases (Sigstore / cosign); verify signatures at deploy |
+| `postinstall` script abuse | `npm config set ignore-scripts true` for CI installs; allowlist trusted packages |
+| Lockfile drift | Fail CI when lockfile changes without manual review |
+
+```yaml
+# Pin GitHub Actions by SHA
+- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11   # v4.1.1
+- uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0
+
+# Provenance + ignore scripts
+permissions:
+  id-token: write              # OIDC for npm publish provenance
+  contents: read
+- run: npm ci --ignore-scripts
+- run: npm publish --provenance --access public
+```
+
+See `secrets-management` (OIDC federation), `ci-pipelines` (pinning + provenance), and `secrets-management` (28M secrets leaked on GitHub in 2025 — supply chain hygiene matters).
 
 ---
 
@@ -153,11 +206,14 @@ const event = stripe.webhooks.constructEvent(rawBody, sig, secret);
 
 ---
 
-## A10 — Server-Side Request Forgery (SSRF)
+## A10 — Server-Side Request Forgery (SSRF)  *(2025: folded into A01 — Broken Access Control)*
+
+OWASP 2025 removed SSRF as a standalone category and treats it as a sub-class of A01. **The risk did not decrease** — apply the same controls. The numbering here is preserved so cross-references in `security-auditor` and per-stack overlays keep working.
 
 - 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.
+- Cloud metadata endpoints (`169.254.169.254`, `metadata.google.internal`) — **always block**, regardless of allowlist.
 
 ```ts
 import { isIP } from 'net';
@@ -169,6 +225,41 @@ if (PRIVATE.test(ip.address)) throw new ForbiddenError('Private IP not allowed')
 
 ---
 
+## A10+ (2025 only) — Mishandling of Exceptional Conditions *(NEW in 2025)*
+
+Errors that **fail open**, leak internals, or leave the system in an inconsistent state. Distinct from A09 (which is about *whether* you logged it) — this is about *how the code reacts*.
+
+| Anti-pattern | Why dangerous | Fix |
+|---|---|---|
+| `try { ... } catch (e) { /* ignore */ }` | Swallows security-relevant failures (e.g. authz check threw) | Log + rethrow, OR explicit comment why it's safe to ignore |
+| Auth check inside `try`, success path outside | If auth throws, code may continue as if authenticated | Authz **fails closed**: throw → caller treats as denied |
+| 500 with full stack trace to client | Leaks file paths, library versions, ORM internals | Generic message to client; full trace to logger only |
+| Webhook handler returns 500 on parse error | Provider retries forever; floods queue | Validate signature first; on parse error log + return 200 (idempotently dropped) |
+| Partial write on transaction failure | Money charged but order not created | Wrap multi-step writes in a transaction; on error, rollback all |
+| Default-allow on missing config (`if (!config.requireMfa) skip`) | Misconfiguration → security off | Default-deny: missing config = block |
+
+```ts
+// WRONG — fail open
+try {
+  await assertCanAccess(user, resource);
+} catch (e) {
+  console.log(e);
+  // ...code continues, request succeeds
+}
+
+// CORRECT — fail closed
+try {
+  await assertCanAccess(user, resource);
+} catch (e) {
+  logger.warn({ event: 'authz.error', err: e, userId: user.id, resourceId: resource.id });
+  throw e;             // caller maps to 403
+}
+```
+
+See `error-handling` skill for full taxonomy and Result-type patterns.
+
+---
+
 ## Mandatory Boundary Validation
 
 Every external input MUST be validated by a schema:
@@ -185,18 +276,24 @@ No exceptions for "trusted" sources. Internal services drift, queues replay malf
 
 ## 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
+- [ ] All routes have authn + authz checks (§A01)
+- [ ] User ID derived from session, never from body (§A01)
+- [ ] All inputs validated by schema (§A03)
+- [ ] No secrets in code (see `secrets-management`) (§A02 + 2025-A03)
+- [ ] No raw SQL / Mongo operators from user input (§A03)
+- [ ] Security headers set on responses (§A05)
+- [ ] Rate limit on auth + write endpoints (§A07)
+- [ ] PII not in logs (see `observability`) (§A09)
+- [ ] Webhook signatures verified before parsing (§A08)
+- [ ] CI pins GitHub Actions by SHA + uses OIDC for cloud auth (2025-A03)
+- [ ] No silent `catch` blocks; authz failures rethrow (2025-A10)
+- [ ] Cloud metadata endpoints blocked in any URL-fetching code (§A10)
 
 ## See Also
 
-- `secrets-management` — env hygiene, gitleaks
-- `observability` — log redaction
+- `secrets-management` — env hygiene, gitleaks, OIDC federation
+- `observability` — log redaction, PII handling
+- `error-handling` — fail-closed patterns (2025-A10)
+- `ci-pipelines` — pinning + provenance (2025-A03)
 - `api-security-node` / `api-security-python` / PHP `api-security` — stack-specific hardening
+- Stack overlays consume the §A01–§A10 anchors above. **Do not renumber.**