Files
code-review-cli/AGENTS.md
Philippe Loulidi 04a38e3a24 Harden untrusted-tree trust boundary: address AI review + security audit
Fixes the review's critical finding plus five further issues surfaced by a
full-repo security audit, all in the same threat class — the reviewed PR tree
is attacker-controlled and its content must never resolve a binary, reach a raw
fs read, forge reviewer state, or leak host secrets.

Review findings:
- claudeSubscriptionActive no longer spawns a bare `claude` with inherited
  cwd/env; it takes the resolved, pathInside-checked CLI path + allowlisted
  env and probes from tmpdir. All three call sites routed through it.
- doctor folds routed scope configs into the engine set (resolveEngines), so
  an Anthropic-only scope no longer passes with the Claude checks skipped.
- review scopes buildEngineMap to the selected agents, so a run whose passes
  never use Claude no longer preflights (and fails on) a missing Claude CLI.

Audit fixes (platform-independent — live on POSIX):
- verify: confine evidencePresence's read to the review tree (pathInside),
  blocking absolute/`..` reads of host secrets and the present/absent oracle.
- auth: a non-anthropic entry naming CLAUDE_CODE_OAUTH_TOKEN/ANTHROPIC_AUTH_TOKEN
  is now refused, so the subscription token can't be forwarded to a foreign
  provider.
- prompts: flatten finding.title/rationale through sanitizeUntrusted so an
  injected finding can't forge verifier prompt boundaries.
- github reporter: identify our own comment by author + marker, not the
  public marker alone, so a forged comment can't carry review state forward.
- ci: collapse subprocess argv/stderr in public PR failure comments.

Bare-name spawn hardening (defense-in-depth; the cwd-hijack is Windows-only, as
POSIX execvp does not search cwd, but the tool is published and `.` may sit in
PATH):
- Resolve git/gh to trusted absolute paths (resolveTrustedTool) before every
  spawn, and taskkill via an absolute System32 path.
- The `opencode`/`claude` direct-spawn callers in doctor/setup-auth resolve an
  absolute path (resolveOpencodeCli/resolveClaudeCli). startOpencode keeps the
  SDK's own spawn: injecting an absolute path there would mean maintaining a
  fork of the SDK's server bootstrap, not worth it for a Windows-only threat on
  a POSIX-supported tool; the accepted residual is documented in place.

Regression tests added for each; typecheck, lint, fmt:check clean; 328 tests pass.
2026-07-29 10:00:33 -07:00

3.9 KiB

Agent guide

@expo/code-review-cli (ecr) is a config-driven AI code reviewer engine. Adopting repos scaffold .expo-code-review/ (agent prompts + config) and a CI workflow; the CLI diffs a PR, fans the diff out to reviewer agents via OpenCode, verifies their findings, and posts one updating PR comment.

Layout

  • src/cli.ts — entry point; dispatches to src/commands/* (init, review, ci, doctor, dismiss).
  • src/core/ — engine: diffing/chunking, prompt assembly, OpenCode server, finding verification, comment rendering, auth.
  • src/sources/ — where the diff comes from (local-git, github-pr).
  • src/reporters/ — where findings go (terminal, github).
  • src/config/ — zod schema + loader for .expo-code-review/config.jsonc; routing.ts parses the monorepo routing.jsonc manifest and assigns changed files to scopes (last-match-wins).
  • templates/ — the files ecr init scaffolds into adopting repos. Keep them in sync with the code (config options, workflow steps, auth defaults).
  • src/__tests__/ — bun test unit tests, one file per module.

Conventions

  • TypeScript, ESM with NodeNext resolution: relative imports use the .js suffix.
  • Commands: USAGE string, handle -h/--help first, report errors to stderr via errorMessage(error) (src/core/util.ts), set process.exitCode (2 for usage/failure) — never call process.exit().
  • Child processes always go through src/core/exec.ts (execFile with argument arrays, no shell).
  • New config options must update src/config/schema.ts, src/config/load.ts, and templates/config.jsonc together.
  • Core paths must work in both local mode (local-git + terminal reporter) and CI mode (github-pr + GitHub reporter).
  • ecr ci must never fail a PR's checks — reviewer errors degrade gracefully.
  • Scope configs never carry auth/breakGlass — those are root-only, enforced in the schema (ScopeReviewConfigSchema), the loader (loadAuthFromRoot), and the CI guard. With no routing.jsonc, behavior is byte-identical to single-config mode.
  • opencode-ai and @opencode-ai/sdk are one unit — pinned EXACTLY, bumped together. The SDK spawns the CLI (launch("opencode")), so the two are a matched pair: a CLI older than the SDK rejects model ids the SDK accepts. Exact pins stop an npx install in CI from floating one ahead of the other, and startOpencode prepends our own node_modules/.bin to PATH so a machine's global install can't shadow the pinned one. ecr doctor prints the version actually in use. (The SDK's spawn is a bare launch("opencode"); on POSIX — the supported platform — the cwd is never searched, so a PR-committed shim can't hijack it. The direct-spawn opencode callers we own, ecr doctor/ecr setup-auth, are hardened via resolveOpencodeCli.)
  • Fail fast and name the fix for setup errors. A bad model id or credential hits every pass identically, so it must throw once, before any pass runs, with the fix in the message (assertModelsResolvable, checkOauthTokenShape) — never as N indistinguishable coverage gaps discovered after spending the run's budget.

Security invariants

  • PR content (diffs, paths, titles, config in the reviewed repo) is untrusted. Prompt interpolation goes through sanitizeUntrusted/boundary markers in src/core/prompts.ts.
  • Model output is untrusted: schema-validate it, and trust file/line/ evidence only after verification (src/core/verify.ts).
  • The model credential (auth.tokenEnv) must never reach logs, error messages, or .expo-code-review/.runs/. FORBIDDEN_TOKEN_ENVS in src/core/auth.ts stops configs from exfiltrating non-provider secrets — don't weaken it.

Workflow

  • bun run dev runs the CLI from source; bun test runs unit tests; bun run typecheck type-checks.
  • Releases: bun run release (see scripts/release.sh).