# Dependency Policy — Supply-Chain Hardening

Co-Vibe treats third-party packages as a primary attack surface. Recent npm
registry incidents (compromised maintainer accounts publishing malicious patch
releases) mean a floating version range can silently pull hostile code on the
next install. Our posture is **freeze by default, upgrade deliberately**.

## Rules

1. **Direct dependencies are pinned to exact versions** in `package.json` — no
   `^` or `~` ranges. A given checkout always installs the same versions.
2. **The lockfile is the source of truth.** `package-lock.json` (v3) pins every
   transitive dependency with an integrity hash. Always install with `npm ci`,
   never `npm install`, in CI and production builds. `npm ci` fails closed if the
   lockfile and `package.json` disagree or an integrity hash mismatches.
3. **`.npmrc` enforces the freeze.** `save-exact=true` makes any future
   `npm install <pkg>` record an exact version; `engine-strict=true` honors the
   supported Node range. The `doctor` script validates `.npmrc` and fails if it
   ever disables the lockfile, points at an untrusted registry, or embeds
   credentials.
4. **No automatic upgrade bot.** There is intentionally no Dependabot/Renovate
   config. Dependencies do not move on their own. (If one is added later, it must
   open PRs for review only — never auto-merge.)
5. **CI enforces supply-chain gates** (`Security gate` job, every PR + push):
   - `npm ci` — integrity-verified install from the frozen lockfile.
   - `npm audit --audit-level=high` — fails the build on high/critical CVEs.
   - `npm audit signatures` — verifies every installed package has a valid npm
     registry signature (provenance).
   - `npm run check:secrets` — no committed secrets.

## Upgrading (the deliberate path)

Dependencies stay frozen **until the next release cycle**. To bump intentionally:

1. Change the exact version in `package.json` for the specific package only.
2. `npm install --package-lock-only` to update the lockfile (review the diff —
   confirm only the intended subtree changed; no unexpected transitive moves).
3. `npm ci` locally, then run `npm run readiness` (includes `npm run security`).
4. Read the release notes / changelog and skim the diff for anything suspicious
   (new install scripts, network calls, obfuscated code) before merging.
5. Prefer waiting a few days after a release before adopting it, so the ecosystem
   has time to surface a compromised publish.

## Accepted advisories

CI gates on `--audit-level=high`. Moderate advisories are reviewed and tracked
here rather than blocking the build:

- **`postcss <8.5.10`** (CSS-stringify XSS, GHSA-qx2v-qp2m-jg93) — transitive via
  `next` → `@workos-inc/authkit-nextjs`. No fix currently available; not reachable
  with untrusted CSS in this app. Re-evaluate when an upstream fix ships.