# Security Checks Agents must run security checks before claiming done. ## Required Checks Run the repo's actual commands once they exist. Minimum expected checks: - dependency audit - secret scan - auth route review - MCP token handling review - protected route check - hosted WorkOS deployment canary - WorkOS mode hides local-only demo and developer-switch routes - health route returns readiness only, not secrets or raw work data - no raw tokens in logs - no secrets in git - no local companion config, generated report media, or database files tracked for public release - real hosted deployments must use the managed PostgreSQL/Cloud SQL path - PostgreSQL schema and runtime smokes must prove tenant/workspace isolation before the production doctor is allowed to pass ## Secret Rules Do not commit: - `.env` - `.env.local` - auth secrets - API keys - MCP raw tokens - database files - session dumps - raw agent transcripts ## Auth Review Check: - unauthenticated users cannot open protected UI pages - unauthenticated users cannot call protected APIs - tenant/user administration routes require authentication and tenant admin role for member creation - workspace cookies are accepted only when the workspace belongs to the active tenant - post-auth onboarding (`POST /api/onboarding`) grants tenant/workspace admin only to the bootstrap (first) member; a user joining an existing tenant cannot self-elevate - MCP calls without valid token fail - revoked MCP tokens fail - token hashes are stored instead of raw tokens - MCP token-created agent activity logs as the token owner - device-flow endpoints (`/api/setup/device`, `/api/setup/device/poll`) are rate limited; grant approval requires a cookie session and binds the signed-in developer/tenant/workspace - device codes are stored hashed; minted typed tokens are delivered exactly once by the poll endpoint and never logged - WorkOS mode runs AuthKit proxy middleware before protected UI/API routes - production without complete WorkOS env reports blocked auth instead of local-dev - WorkOS sign-in and callback routes fail closed when auth config is blocked - local-only route handlers fail closed when auth config is blocked - protected UI API handlers fail closed when auth config is blocked - malformed UI API bodies return structured errors or safe defaults - `/api/state` returns 401 when no developer is authenticated - `/api/health` does not expose raw error detail - UI session cookies always persist with the `Max-Age` configured by `COVIBE_REMEMBER_ME_DAYS` (default 30 days); sign-out cookie deletions are never extended to that age - logout clears Co-Vibe session cookies and uses AuthKit logout in WorkOS mode - local-dev logout sets a signed-out marker instead of falling back to `@hakan` - Settings does not allow users to change email; password changes use provider reset ## MCP Review Check: - blocked starts cannot bypass confirmation - overlap warnings are returned to the agent - all tool calls write usage events - state-changing tools write work events - errors do not leak secrets - `/api/mcp` rate-limits per client IP (env `COVIBE_MCP_RATE_LIMIT` / `COVIBE_MCP_RATE_WINDOW_MS`, default 240/min) before parsing or DB work; over-limit returns `429` with `Retry-After`. In-memory and per-instance — pair with an edge/shared limiter for multi-instance deploys - PostgreSQL RLS `with check` matches the strict `using` equality, so rows cannot be written with a NULL workspace_id/tenant_id that read views could surface across tenants ## CI Gates The `Customer readiness` workflow runs a dedicated `Security gate` job on every pull request and push to `main`, independently of the heavier build jobs: - `npm ci` — integrity-verified install from the frozen lockfile. - `npm run check:secrets` — no committed secrets. - `npm audit --audit-level=high` — fails on high/critical CVEs. - `npm audit signatures` — verifies npm registry provenance of every dependency. ## Supply Chain & Dependency Freeze Dependencies are **frozen**: direct deps are pinned to exact versions, the v3 lockfile pins every transitive dep with an integrity hash, and `.npmrc` (`save-exact`, `engine-strict`) keeps the freeze sticky. There is intentionally no Dependabot/Renovate auto-upgrade bot. CI gates on `--audit-level=high`; moderate advisories are tracked, not blocking (currently accepted: `postcss <8.5.10` CSS-stringify XSS, transitive via `next` → `@workos-inc/authkit-nextjs`, no fix available, not reachable with untrusted CSS). Full policy and the deliberate-upgrade procedure: `docs/engineering/dependency-policy.md`. ## Reporting If a check fails, do not hide it. Write it in `reports/morning-report.md` with: - severity - command or manual check - result - next action ## Current Command Run: ```bash npm run security ``` This runs dependency audit, secret scan, public-repo hygiene, public-doc setup command checks, companion package contents, minimal dependency manifest, README setup-shape checks, and a static auth/token review. Public-repo hygiene checks tracked files plus unignored untracked files, so a local `.env`, database, MCP config, or generated report artifact fails before it can be staged for a public release. Public docs may use placeholders such as `cv_...`, but concrete `COVIBE_MCP_TOKEN=cv_...` examples and setup command lines that pass concrete raw tokens fail the public check. Run `npm run check:deploy` before building the hosted image. It verifies the Next standalone output config, Docker runtime command, persistent data volume, Docker build-context exclusions for secrets and local agent config, and the hosted/container runtime leak guard for raw Co-Vibe MCP token-shaped response data. For a deployed customer environment, also run: ```bash npm run readiness:handoff -- https://your-covibe-host ``` This first runs a fast remote `/api/health`, `/api/mcp`, and `/downloads/co-vibe.tgz` preflight for DNS/TLS, WorkOS auth, exact compact MCP tool surface, companion-package availability, protected-route rejection, unauthenticated token creation rejection, hidden local-only routes, malformed MCP envelope rejection, missing/invalid MCP-token rejection, and token-shaped response leaks, then runs `doctor:production` before the long local customer gate. `doctor:production` requires real hosted origins to use managed PostgreSQL/Cloud SQL. Use `npm run smoke:postgres` to verify the generated PostgreSQL schema/RLS policies and `npm run smoke:postgres:runtime` to verify repository calls run through PostgreSQL tenant/workspace scope. The companion tarball check also rejects tiny, malformed, or non-Co-Vibe packages before customer install checks run. It then runs customer readiness, production WorkOS config checks, and a hosted canary for `/api/health`, the exact compact `/api/mcp` tool surface, the companion tarball download/install/setup/doctor/snapshot/watch/MCP tool-list path, sign-in reachability, unauthenticated API rejection, hidden local-dev routes, malformed MCP envelope rejection, MCP token enforcement, and response leak checks for raw Co-Vibe MCP token-shaped values. The handoff command rejects localhost, private-network hosts, non-HTTPS URLs, callback paths, query strings, hashes, credential-bearing URLs, and temporary tunnel domains. The hosted URL must be the permanent deployment origin, not the WorkOS callback URL.