rsc-universal 0.1.1

package/skills/secure-coding/references/secrets-and-supply-chain.md

@@ -0,0 +1,205 @@
+# Secrets & supply chain
+
+Keep secrets out of the repo and out of client bundles, pin every dependency,
+and gate the result in CI. Tools: `gitleaks`, `pip-audit` (or `uvx pip-audit`), `osv-scanner`,
+`npm`/`pnpm`, `govulncheck`, `syft`. Versions: Python 3.12+ /
+`pydantic-settings`, Next.js 15, Go 1.22+, PostgreSQL 16.
+
+## Env vs vaults
+
+12-factor env vars for dev; a secret manager (HashiCorp Vault, cloud Secrets
+Manager, Doppler) for prod. **Fail fast** on a missing secret at startup so a
+misconfigured deploy never runs half-authenticated.
+
+```python
+# GOOD (FastAPI) — pydantic-settings BaseSettings; missing secret = startup error.
+from pydantic import SecretStr
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", extra="forbid")
+    database_url: str
+    jwt_signing_key: SecretStr          # never logged when interpolated
+
+settings = Settings()                   # raises if a required var is unset
+```
+
+```go
+// GOOD (Go) — mustEnv panics at startup if the variable is missing.
+func mustEnv(key string) string {
+    v, ok := os.LookupEnv(key)
+    if !ok || v == "" {
+        panic("missing required env var: " + key)
+    }
+    return v
+}
+var dbURL = mustEnv("DATABASE_URL")
+```
+
+```ts
+// Next.js — ONLY NEXT_PUBLIC_* reaches the browser bundle. Everything else is
+// server-only. BAD: reading a secret in a Client Component ships it to users.
+// "use client" + process.env.STRIPE_SECRET_KEY  -> leaked to the browser.
+// GOOD: read secrets in Server Components, Route Handlers, or Server Actions.
+const stripeKey = process.env.STRIPE_SECRET_KEY; // server-only file, no "use client"
+```
+
+```dart
+// Flutter — there is NO server-side; anything compiled into the app binary is
+// extractable. NEVER ship a backend API secret in the client. Inject build-time
+// public config with --dart-define; store per-user tokens in the OS keystore.
+// BAD: const apiSecret = "sk_live_...";  // shipped in the APK/IPA, trivially dumped
+const apiBaseUrl = String.fromEnvironment("API_BASE_URL");  // flutter run --dart-define=API_BASE_URL=...
+```
+
+### Which secret lives where
+
+| Secret kind | Dev | Prod | Never |
+|---|---|---|---|
+| Backend API keys (Stripe secret, DB URL) | `.env` (gitignored) | Secret manager / platform env | Repo, client bundle, mobile binary |
+| JWT signing key | `.env` | Secret manager (rotatable) | Repo, logs, `NEXT_PUBLIC_*` |
+| Per-user access/refresh token | n/a | OS keystore (mobile) / `HttpOnly` cookie (web) | `localStorage`, `SharedPreferences` |
+| Public config (base URL, publishable key) | `.env` | env / `--dart-define` / `NEXT_PUBLIC_*` | — (public by design) |
+
+## Never in repo
+
+`.gitignore` patterns — ignore real env files, keep the example:
+
+```text
+.env
+.env.*
+!.env.example
+```
+
+Run `gitleaks` as a pre-commit hook, against history, and in CI. **Incident
+order when a secret IS committed: rotate FIRST, then scrub history.** History
+rewriting with `git filter-repo` is slow and forces every clone to re-sync; the
+secret is already public the instant it's pushed, so revoke/rotate the
+credential immediately and treat the scrub as cleanup.
+
+```bash
+# Rotate the credential at the provider FIRST. Then:
+git filter-repo --path config/secrets.yml --invert-paths   # scrub from history
+gitleaks git . --no-banner --redact --exit-code 1          # confirm history is clean
+gitleaks dir . --no-banner --redact --exit-code 1          # confirm working tree is clean
+```
+
+## Rotation
+
+Rotate on a cadence (e.g. quarterly) and immediately on any suspected exposure.
+After rotation, **invalidate active sessions and tokens** so credentials minted
+under the old secret can't keep riding along (a JWT signing-key rotation must
+revoke outstanding access/refresh tokens, or attackers keep their forged ones).
+
+On-exposure runbook, in order — each step assumes the previous is done:
+
+1. **Revoke/rotate at the provider** (Stripe, AWS, the OIDC IdP). The leaked
+   value is dead the moment a new one is minted; this is the only step that
+   actually stops the bleed.
+2. **Roll forward in prod** — push the new value to the secret manager and
+   redeploy. Keep the old key valid for a short overlap only if a zero-downtime
+   handoff requires it, then disable it.
+3. **Invalidate derived credentials** — sessions, access/refresh tokens, and any
+   cache keyed on the old secret (see the JWT note above).
+4. **Scrub history** with `git filter-repo` (slow; do it after the rotation, not
+   before) and force every clone to re-sync.
+5. **Add a `gitleaks` rule / pre-commit hook** so the same class of leak can't
+   recur, and note the incident in the audit log.
+
+## Dependency pinning & lockfiles
+
+Commit the lockfile; install with the frozen/verified flag in CI.
+
+| Ecosystem | Pin / lock | Verified install |
+|---|---|---|
+| Python | `uv lock` or `pip-tools` compile **with hashes** | `pip install --require-hashes -r requirements.txt` |
+| Node | `package-lock.json` / `pnpm-lock.yaml` committed | `npm ci` / `pnpm i --frozen-lockfile` |
+| Go | `go.sum` committed | `go mod verify` |
+| Dart | `pubspec.lock` committed | `dart pub get --enforce-lockfile` |
+
+`--require-hashes` and `go mod verify` defend against a registry serving a
+different artifact than the one you locked (A08 integrity).
+
+## Audit tooling — command, how to read, how to fix
+
+| Tool | Command | A finding looks like | Fix |
+|---|---|---|---|
+| pip-audit | `pip-audit` | `Name Version ID Fix-Versions` row per vuln | Upgrade to a fix version; use constraints for a transitive |
+| osv-scanner | `osv-scanner scan source -L pnpm-lock.yaml` | OSV id + severity + introduced/fixed range; lockfile-aware, multi-ecosystem (v2 CLI) | Upgrade; `overrides` for a transitive |
+| npm audit | `npm audit --omit=dev --audit-level=high` | severity + path through the dep tree | `npm audit fix`, or `overrides` for transitive |
+| govulncheck | `govulncheck ./...` | only vulns your code **calls** (reachability) + the call trace | Upgrade; `go mod replace` for a transitive |
+| dart | `dart pub outdated` | outdated (no CVE feed) — advisory only | Upgrade to latest resolvable |
+
+`govulncheck`'s reachability advantage: it won't flag a CVE in a function your
+code never invokes, cutting false positives that `osv-scanner` (which matches
+by version) reports. Use both — osv for breadth, govulncheck for Go precision.
+
+Overriding a transitive (recap):
+
+```json
+{ "overrides": { "vulnerable-lib": "1.2.4" } }
+```
+
+```text
+vulnerable-lib==1.2.4
+```
+
+```go
+replace vulnerable-lib v1.2.3 => vulnerable-lib v1.2.4
+```
+
+## SBOM & provenance
+
+Emit a Software Bill of Materials with `syft` so you can answer "are we
+affected by CVE-X?" instantly:
+
+```bash
+syft dir:. -o cyclonedx-json=sbom.cdx.json     # or spdx-json
+```
+
+For build provenance, sign artifacts with `cosign` and target SLSA build
+levels so consumers can verify an artifact came from your pipeline, not a
+tampered one. For browser-loaded third-party scripts, use SRI
+(`integrity="sha384-…" crossorigin`) — see A08 in `owasp-by-stack.md`.
+
+## CI security gate (the payoff)
+
+This GitHub Actions job is `verify.sh` in CI: secret scan + SAST + per-stack
+CVE audit, failing the build on high/critical findings.
+
+```yaml
+name: security
+on: [pull_request]
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }          # full history for gitleaks
+      - name: gitleaks
+        uses: gitleaks/gitleaks-action@v2
+      - name: semgrep
+        # The semgrep-action wrapper is deprecated; run the CLI directly
+        # (here in its official image) and let `semgrep ci` gate the build.
+        run: docker run --rm -v "$PWD:/src" -w /src semgrep/semgrep semgrep ci --config=auto
+      - name: python audit
+        if: hashFiles('**/pyproject.toml', '**/requirements*.txt') != ''
+        run: pipx run pip-audit
+      - name: node audit
+        if: hashFiles('**/package.json') != ''
+        run: npm audit --omit=dev --audit-level=high
+      - name: go audit
+        if: hashFiles('**/go.mod') != ''
+        run: go run golang.org/x/vuln/cmd/govulncheck@latest ./...
+```
+
+Add Dependabot or Renovate to open dependency-bump PRs automatically (e.g.
+`.github/dependabot.yml` with `package-ecosystem` entries per manifest), so
+CVEs get patched on a schedule rather than only when the gate fails.
+
+---
+
+`scripts/verify.sh` is the local equivalent of this job — run it before opening
+the PR. See the "Secrets & supply chain" section of `SKILL.md` for the
+one-paragraph rules, and `owasp-by-stack.md` (A06, A08) for the per-stack
+override/replace code.

package/skills/secure-coding/references/threat-modeling.md

@@ -0,0 +1,213 @@
+# Threat modeling — PR-sized, not enterprise ceremony
+
+Lightweight STRIDE you can finish inside a PR description. The goal is not a
+"complete" document; it is an explicit authz decision on every changed entry
+point, a validator on every untrusted input, a defense on every dangerous
+sink, and a written list of accepted residual risks. Model only the boundary
+the diff **changes** — never the whole app.
+
+## When to threat-model (and when to skip)
+
+**Do it when the diff:**
+
+- Introduces a new trust boundary (new endpoint, new queue consumer, new webhook).
+- Adds or changes an auth/authz surface (login, role check, token issuance, sharing).
+- Touches money, PII, file uploads, or outbound fetches of user-controlled URLs.
+- Wires up a new external integration (payment, email, object store, third-party API).
+
+**Skip it when the diff is:**
+
+- A copy-edit, string/i18n change, or pure styling/CSS.
+- An internal refactor that moves no data across a boundary and changes no authz.
+- Test-only or fixture-only code.
+- A dependency bump with no new reachable surface (still run `verify.sh`).
+
+"Good enough" trigger: if the change adds or moves an `‖` boundary (below),
+model it. If it doesn't, skip and move on.
+
+## STRIDE in one table
+
+| Threat | Question to ask | Typical control on this stack |
+|---|---|---|
+| **S**poofing | Who is the caller, and did we verify it? | Verified server-side session or JWT with checked `aud`/`iss`/`exp` and **pinned `algorithms`** (never `alg:none`). |
+| **T**ampering | Can the client alter what the server trusts? | Server-side authz + server-computed values (totals, IDs); signed/HMAC payloads for webhooks; DB `CHECK`/`UNIQUE`/FK constraints. |
+| **R**epudiation | Can we prove who did what? | Append-only audit log via `slog`/`structlog` keyed on `user_id` (not PII), with action + object id + timestamp. |
+| **I**nformation disclosure | Does the response leak more than this caller may see? | Field allowlists in the response model, generic errors to the client, ownership-scoped queries (`WHERE owner_id = :me`). |
+| **D**enial of service | Can one caller exhaust us? | Per-IP + per-identity rate limits, request body-size caps, statement/query timeouts, linear-time (ReDoS-safe) regex. |
+| **E**levation of privilege | Can a user act as admin or another user? | Deny-by-default authz, per-object ownership checks on **every** request, role checks enforced server-side only. |
+
+## Trust boundaries and a text DFD
+
+Model the request as a 5-box flow and mark every place data crosses from one
+trust level to another with `‖`. At each `‖`, untrusted data becomes trusted
+(or vice versa) **only after** the check that lives there runs.
+
+```text
+Client  ‖  Edge/CDN  ‖  API  ‖  DB  ‖  3rd-party
+```
+
+`‖` is a checkpoint: HTTP body → SQL, user string → shell/URL/HTML, JWT claim →
+authz decision, filename → filesystem path, upload → disk/exec. The control
+that defends the crossing must live on the trusted side (the server), never on
+the client.
+
+Worked DFD — **"user uploads an avatar"**:
+
+```text
+[Browser]
+   |  multipart/form-data (untrusted)
+   v
+[Next.js Route Handler]
+   |  || CHECK: size cap + sniff magic bytes (not file.type); reject SVG
+   v
+[FastAPI presign endpoint]
+   |  || CHECK: await auth(); is this the *caller's own* avatar slot? (authz)
+   v
+[Object store — private bucket]
+   |  || CHECK: random object key; no public-read ACL; server sets content-type
+   v
+[CDN]
+      || CHECK: short-TTL signed URL; Content-Disposition: attachment; nosniff
+```
+
+Each `||` annotates the one check it owns. If a box has no check on its inbound
+crossing, that is the finding.
+
+## Abuse cases — turn each user story into "…and an attacker does X"
+
+| Feature | Abuse case | Control |
+|---|---|---|
+| Login | Credential stuffing with leaked password lists | Per-IP **and** per-identity rate limit + temporary lockout; generic "invalid credentials". |
+| Avatar upload | Polyglot file / SVG carrying `<script>` | Sniff magic bytes, reject SVG, re-encode images server-side, serve from a separate origin with `Content-Disposition: attachment` + `X-Content-Type-Options: nosniff`. |
+| Search | Result enumeration + ReDoS via crafted pattern | Bound and validate input length, parameterize the query, use a linear-time regex engine (RE2 / Go `regexp`), cap result count. |
+| Webhook | Forgery or replay of a payment event | Verify HMAC signature, enforce a timestamp freshness window, dedupe on an idempotency key stored with a `UNIQUE` constraint. |
+| Password reset | Token leaked via `Host` header poisoning or `Referer` | Single-use **hashed** short-TTL token; build the reset link from a **configured base URL**, never from the request `Host`. |
+| Export / report | IDOR mass-extraction of other tenants' rows | Ownership-scoped query + per-object authz + rate limit; return `404` (not `403`) on a miss to avoid confirming the row exists. |
+
+## The PR-sized template
+
+Paste this into the PR description and fill only the rows that apply.
+
+```markdown
+### Threat model: <feature>
+
+**Assets** — what's worth stealing/breaking here (PII, money, files, tokens).
+
+**Entry points** — every changed handler/action/consumer (METHOD + path).
+
+**Trust boundaries** — the crossings this diff adds or moves.
+
+**STRIDE hits** — only the categories that actually apply, one line each.
+
+**Decided controls** — the concrete defense per hit (with the file it lives in).
+
+**Residual risk (accepted)** — what we are knowingly NOT defending, and why.
+```
+
+**"Good enough" stopping rule:** stop when every changed entry point has an
+explicit authz decision, every untrusted input has a validator, every dangerous
+sink has a defense, and every residual risk is written down. Do **not** keep
+going until the document feels "complete" — completeness is not the bar,
+coverage of the changed boundary is.
+
+## Worked example — FastAPI "create invoice + download via signed URL"
+
+```markdown
+### Threat model: invoices
+
+**Assets** — invoice PDF (financial), customer PII (name, address, line items).
+
+**Entry points**
+- POST /invoices                  (create)
+- GET  /invoices/{id}/download    (fetch signed URL)
+
+**Trust boundaries**
+- Client to API: request body (amount, customer_id) is untrusted.
+- API to object store: PDF stored under a random key in a private bucket.
+- API to client: short-TTL signed URL returned to the caller.
+
+**STRIDE hits**
+- Tampering: client submits its own `total` -> recompute server-side from line items.
+- Information disclosure: caller requests another tenant's invoice id (IDOR).
+- Elevation: caller downloads any invoice by guessing sequential ids.
+
+**Decided controls**
+- Ownership-scoped query on both endpoints (WHERE org_id = :caller_org).
+- Server computes `total`; the client value is ignored.
+- Download returns a 60s signed URL; the object key is random, bucket is private.
+- 404 (not 403) when the invoice is not owned, to avoid id enumeration.
+- Audit log: user_id + invoice_id + action on create and download.
+
+**Residual risk (accepted)**
+- A signed URL is bearer within its 60s TTL; we accept the short window rather
+  than per-download re-auth. Mitigated by the short TTL + audit trail.
+```
+
+The download handler doing the ownership check + expiry:
+
+```python
+# GOOD — ownership-scoped lookup, 404 on miss, short-lived signed URL.
+from datetime import timedelta
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+router = APIRouter()
+
+@router.get("/invoices/{invoice_id}/download")
+def download_invoice(
+    invoice_id: int,
+    db: Session = Depends(get_db),
+    user: User = Depends(get_current_user),
+) -> dict[str, str]:
+    invoice = db.execute(
+        select(Invoice).where(
+            Invoice.id == invoice_id,
+            Invoice.org_id == user.org_id,   # ownership scope
+        )
+    ).scalar_one_or_none()
+    if invoice is None:
+        # 404 (not 403): never confirm an invoice id the caller can't see.
+        raise HTTPException(status_code=404, detail="Not found")
+    url = object_store.signed_url(invoice.object_key, expires=timedelta(seconds=60))
+    audit.info("invoice_download", user_id=user.id, invoice_id=invoice.id)
+    return {"url": url}
+```
+
+Residual risk note: the signed URL is bearer for its 60-second TTL and the
+audit log records `user_id` only (no PII). Both are accepted trade-offs.
+
+## Common pitfalls when an agent threat-models
+
+These are the failure modes to self-check against before you call a model done:
+
+- **Modeling the whole app instead of the diff.** If you find yourself listing
+  threats to code the PR doesn't touch, stop — scope to the changed boundary.
+- **Listing threats with no decided control.** A STRIDE hit without a "Decided
+  control" line is just anxiety. Every hit needs a concrete defense or an
+  explicit "accepted" with a reason.
+- **Trusting a client-side check as a control.** Hidden buttons, disabled form
+  fields, and front-end validation are UX, not security. The control must live
+  on the server side of the `‖` it defends.
+- **Confusing authentication with authorization.** "The user is logged in" is
+  not a control for an IDOR. The control is "the query is scoped to *this*
+  caller's rows."
+- **Treating "internal" as safe.** An internal-only URL is exactly the SSRF
+  target (cloud metadata, the database). Boundaries exist inside the perimeter.
+- **Skipping the residual-risk line.** If you are knowingly not defending
+  something (e.g. a short-lived bearer URL), write it down so the reviewer can
+  accept it on purpose rather than discover it in an incident.
+
+## From model to fix — the handoff
+
+A finished model is an input to a code change, not the deliverable. For each
+"Decided control", open the matching category in `owasp-by-stack.md`, copy the
+GOOD pattern for the repo's stack, and wire it into the changed handler. Then
+run `../scripts/verify.sh` to confirm no secret/SAST/CVE regression slipped in
+alongside the fix.
+
+---
+
+See `owasp-by-stack.md` for the vulnerable→fixed code that implements each
+control per stack, and `authn-authz.md` for the auth surface (sessions, JWT,
+RBAC/ABAC) referenced by the Spoofing and Elevation rows above.

package/skills/secure-coding/scripts/verify.sh

@@ -0,0 +1,208 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ============================================================================
+# NAME
+#   verify.sh — secure-coding application-security gate
+#
+# USAGE
+#   ./verify.sh
+#   Run from the ROOT of YOUR project (the repo you are shipping), NOT from
+#   the skills repository. It auto-detects your stack from the manifests it
+#   finds (pyproject.toml / requirements*.txt / package.json / go.mod /
+#   pubspec.yaml) and runs the matching auditors.
+#
+# WHAT IT DOES
+#   1. Secret scan      — gitleaks over the working tree (and git history when
+#                         inside a git repo).
+#   2. SAST             — semgrep ERROR rules (and informational WARNINGs).
+#   3. Dependency CVEs  — per-stack: pip-audit (or `uvx pip-audit`),
+#                         osv-scanner/npm/pnpm/yarn, govulncheck,
+#                         dart pub outdated (informational).
+#   Each tool is DETECTED first; if it is missing the step is SKIPPED with a
+#   yellow warning (never a failure). The script exits non-zero ONLY on real
+#   high/critical findings.
+#
+# GUARANTEES
+#   - Idempotent and read-only: it never writes to the repo and never auto-fixes.
+#   - Network access only where a tool inherently needs it (CVE feeds).
+#   - semgrep --config=auto (which fetches remote rules) is OPT-IN via the
+#     SECURE_CODING_SEMGREP_AUTO=1 env var; without it, semgrep runs only when
+#     a local config is present.
+#   - Portable to stock macOS bash 3.2 (no mapfile, no associative arrays).
+#
+# ENV TOGGLES
+#   SECURE_CODING_SEMGREP_AUTO=1  Enable semgrep's network-fetched "auto" rules.
+#   NO_COLOR=1                    Disable ANSI color output.
+#
+# EXIT CODES
+#   0  No high/critical findings (skips and informational warnings are fine).
+#   1  At least one real high/critical finding — resolve before merge.
+# ============================================================================
+
+RED=$'\033[31m'; YEL=$'\033[33m'; GRN=$'\033[32m'; RST=$'\033[0m'
+if [ -n "${NO_COLOR:-}" ]; then RED=""; YEL=""; GRN=""; RST=""; fi
+
+FAILED=0
+warn()    { printf '%s[skip]%s %s\n' "$YEL" "$RST" "$*" >&2; }
+ok()      { printf '%s[ok]%s %s\n'   "$GRN" "$RST" "$*"; }
+bad()     { printf '%s[FAIL]%s %s\n' "$RED" "$RST" "$*" >&2; FAILED=1; }
+info()    { printf '%s[info]%s %s\n' "$YEL" "$RST" "$*"; }
+have()    { command -v "$1" >/dev/null 2>&1; }
+section() { printf '\n=== %s ===\n' "$*"; }
+
+# need <tool> <install-hint> : guard a tool block. Returns 0 if present,
+# else prints a skip warning and returns 1 so the caller can skip the block.
+need() {
+  if have "$1"; then
+    return 0
+  fi
+  warn "$1 not installed (install: $2)"
+  return 1
+}
+
+# ----------------------------------------------------------------------------
+# 1. Secrets — gitleaks
+# ----------------------------------------------------------------------------
+section "Secrets (gitleaks)"
+if need gitleaks "brew install gitleaks / https://github.com/gitleaks/gitleaks"; then
+  # gitleaks v8.19+ split scanning: `dir` walks the working-tree FILES, while
+  # `git` scans commit HISTORY (patches). The deprecated `detect` == `git`
+  # (history only) and would MISS an unstaged secret in a working file. We scan
+  # the working tree always, and history too when this is a git checkout.
+  # --redact keeps secret values out of this terminal output.
+  if gitleaks dir . --no-banner --redact --exit-code 1; then
+    ok "no secrets in working tree"
+  else
+    bad "gitleaks found secrets in the working tree — rotate the credential now"
+  fi
+  if [ -d .git ] && git rev-parse --git-dir >/dev/null 2>&1; then
+    if gitleaks git . --no-banner --redact --exit-code 1; then
+      ok "no secrets in git history"
+    else
+      bad "gitleaks found secrets in git history — rotate, THEN scrub history"
+    fi
+  else
+    warn "not a git repository; skipped history scan (working tree was scanned)"
+  fi
+fi
+
+# ----------------------------------------------------------------------------
+# 2. SAST — semgrep
+# ----------------------------------------------------------------------------
+section "SAST (semgrep)"
+if need semgrep "pipx install semgrep / brew install semgrep"; then
+  CFG=""
+  if   [ -f .semgrep.yml  ]; then CFG="--config .semgrep.yml"
+  elif [ -f .semgrep.yaml ]; then CFG="--config .semgrep.yaml"
+  elif [ -f semgrep.yml   ]; then CFG="--config semgrep.yml"
+  elif [ -d .semgrep      ]; then CFG="--config .semgrep"
+  elif [ "${SECURE_CODING_SEMGREP_AUTO:-}" = "1" ]; then CFG="--config=auto"
+  fi
+
+  if [ -z "$CFG" ]; then
+    warn "no semgrep config found and SECURE_CODING_SEMGREP_AUTO unset; skipping SAST"
+  else
+    # ERROR-severity findings gate the build. $CFG is intentionally unquoted so
+    # it splits into separate args (it only ever holds tool flags we set above).
+    if semgrep $CFG --error --severity ERROR --quiet; then
+      ok "no semgrep ERROR findings"
+    else
+      bad "semgrep reported ERROR-severity findings"
+    fi
+    # WARNING-severity findings are informational only and must never abort
+    # the script (set -e) nor flip FAILED.
+    semgrep $CFG --severity WARNING --quiet || warn "semgrep WARNING findings present (informational)"
+  fi
+fi
+
+# ----------------------------------------------------------------------------
+# 3. Per-stack dependency audit — detect by manifest, run ALL that match
+# ----------------------------------------------------------------------------
+section "Dependency audit"
+
+# --- Python ---------------------------------------------------------------
+if [ -f pyproject.toml ] || ls requirements*.txt >/dev/null 2>&1; then
+  if have pip-audit; then
+    if pip-audit; then ok "python deps: no known vulns (pip-audit)"
+    else bad "python deps: vulnerabilities reported by pip-audit"; fi
+  elif have uvx; then
+    # `uv pip audit` is NOT a real subcommand; run pip-audit through uvx.
+    if uvx pip-audit; then ok "python deps: no known vulns (uvx pip-audit)"
+    else bad "python deps: vulnerabilities reported by uvx pip-audit"; fi
+  else
+    warn "pip-audit not installed (install: pipx install pip-audit, or use uvx pip-audit)"
+  fi
+fi
+
+# --- Node / TypeScript ----------------------------------------------------
+if [ -f package.json ]; then
+  if have osv-scanner; then
+    LOCK=""
+    if   [ -f pnpm-lock.yaml     ]; then LOCK="pnpm-lock.yaml"
+    elif [ -f package-lock.json  ]; then LOCK="package-lock.json"
+    elif [ -f yarn.lock          ]; then LOCK="yarn.lock"
+    fi
+    # OSV-Scanner v2 reorganized the CLI under `scan source` (`-L`/`--lockfile`
+    # for a specific lockfile, `-r`/`--recursive` for a tree). The base `scan`
+    # command stays backward-compatible across the v2 major.
+    if [ -n "$LOCK" ]; then
+      if osv-scanner scan source -L "$LOCK"; then ok "node deps: no known vulns (osv-scanner $LOCK)"
+      else bad "node deps: vulnerabilities reported by osv-scanner"; fi
+    else
+      if osv-scanner scan source -r .; then ok "node deps: no known vulns (osv-scanner recursive)"
+      else bad "node deps: vulnerabilities reported by osv-scanner"; fi
+    fi
+  elif [ -f pnpm-lock.yaml ] && have pnpm; then
+    if pnpm audit --prod --audit-level high; then ok "node deps: no high+ vulns (pnpm audit)"
+    else bad "node deps: high+ vulnerabilities reported by pnpm audit"; fi
+  elif [ -f yarn.lock ] && have yarn; then
+    # Yarn Berry (>=2) ships `yarn npm audit`; classic yarn lacks a severity
+    # gate, so skip+warn rather than fail noisily.
+    if yarn npm audit --severity high >/dev/null 2>&1; then
+      if yarn npm audit --severity high; then ok "node deps: no high+ vulns (yarn npm audit)"
+      else bad "node deps: high+ vulnerabilities reported by yarn npm audit"; fi
+    else
+      warn "yarn classic has no severity-gated audit; install osv-scanner instead"
+    fi
+  elif [ -f package-lock.json ] && have npm; then
+    # `npm audit` REQUIRES a lockfile (it errors ENOLOCK without one) — that's
+    # why this branch is gated on package-lock.json, not just package.json.
+    if npm audit --omit=dev --audit-level=high; then ok "node deps: no high+ vulns (npm audit)"
+    else bad "node deps: high+ vulnerabilities reported by npm audit"; fi
+  elif [ ! -f package-lock.json ] && [ ! -f pnpm-lock.yaml ] && [ ! -f yarn.lock ]; then
+    warn "package.json but no lockfile; commit a lockfile or install osv-scanner to audit node deps"
+  else
+    warn "no usable node auditor found (install osv-scanner, or use npm/pnpm/yarn with their lockfile)"
+  fi
+fi
+
+# --- Go -------------------------------------------------------------------
+if [ -f go.mod ]; then
+  if need govulncheck "go install golang.org/x/vuln/cmd/govulncheck@latest"; then
+    # govulncheck reports only vulns your code actually CALLS (reachability).
+    if govulncheck ./...; then ok "go deps: no reachable vulns (govulncheck)"
+    else bad "go deps: reachable vulnerabilities reported by govulncheck"; fi
+  fi
+fi
+
+# --- Dart / Flutter -------------------------------------------------------
+if [ -f pubspec.yaml ]; then
+  # pub.dev has no CVE feed; `dart pub outdated` only flags stale versions.
+  # This step is INFORMATIONAL and never sets FAILED.
+  if need dart "https://dart.dev/get-dart"; then
+    dart pub outdated || true
+    info "dart deps: review outdated packages above (no CVE feed; advisory only)"
+  fi
+fi
+
+# ----------------------------------------------------------------------------
+# 4. Summary
+# ----------------------------------------------------------------------------
+section "Summary"
+if [ "$FAILED" -eq 0 ]; then
+  ok "no high/critical findings"
+else
+  printf '%shigh/critical findings present — resolve before merge%s\n' "$RED" "$RST" >&2
+fi
+exit "$FAILED"