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.