chore(security): set up deepsec workspace

BU
17h ago
+3083-1

Related issue or discussion

None. This was requested directly.

What this changes

Adds a deepsec workspace in .deepsec/. deepsec is Vercel's open-source security review harness: a local regex scan picks candidate files, then an AI agent reviews them. Nothing in this PR runs in CI or ships in the npm package.

The AI review has not run, so there are no findings yet. It needs a model credential and costs money, so a maintainer has to finish setup (see "To finish setup").

What is in the workspace:

  • The scaffold from deepsec init --scaffold-only at deepsec 2.3.12, pinned exactly, with a lockfile.
  • data/resend-node/INFO.md, the project context deepsec gives to every AI review. It describes how the SDK handles the API key, the threat model, the patterns to flag and the known false positives. It steers every later review, so it is worth a careful read.

Changes on top of the generated scaffold:

  • .deepsec/pnpm-workspace.yaml repeats the root minimumReleaseAge and trustPolicy. .deepsec/ is its own pnpm workspace, so the root file does not apply to it.
  • .deepsec/.gitignore also ignores data/*/tech.json, which every scan rewrites with a timestamp and the absolute path of the local checkout. It also ignores findings/ and findings.json, the export targets from the deepsec docs. This repository is public, so findings must not be committed.
  • biome.jsonc skips .deepsec. deepsec rewrites deepsec.config.ts and generated-matchers.ts in its own style, and pnpm lint fails on them otherwise.
  • .deepsec/README.md sets the workspace up with pnpm deepsec setup, which runs the pinned version. The generated text said to re-run npx deepsec init, which downloads the latest release.
  • .deepsec/README.md documents that deepsec copies a credentialed remote URL into project.json and into exported finding links, and how to fix it.
  • .deepsec/AGENTS.md runs init-project through pnpm deepsec, because a bare deepsec is not on PATH.
  • The generated SETUP.md, a prompt for writing INFO.md, is left out, and the two docs no longer point to it for resend-node.

Verified

On a fresh clone of this branch:

  • pnpm lint, pnpm typecheck and pnpm test pass with the same counts as canary: Biome checks 320 files, and 49 test files pass.
  • The root pnpm install --frozen-lockfile leaves .deepsec/ alone, and npm pack --dry-run lists no .deepsec file.
  • In .deepsec/, pnpm install --frozen-lockfile and pnpm deepsec scan work. The scan flags 32 files with 39 candidate matches, and git status stays clean afterwards.
  • pnpm deepsec setup --through install completes the scaffold and install phases, so setup resumes at the model-access step.

The remote URL note in the README was reproduced with a dummy token. The token appeared in project.json and in an exported finding, and was gone after setting githubUrl as the README says.

To finish setup

From .deepsec/, with a model credential:

pnpm install
pnpm deepsec setup --model-profile value --max-cost-usd 25

This uses Vercel AI Gateway and logs in to Vercel. To use your own OpenAI key instead:

MY_KEY=... pnpm deepsec setup --agent codex --model-auth direct --ai-provider openai --ai-api-key-env MY_KEY --max-cost-usd 25

Setup then inventories the SDK's surfaces, generates matchers for what the built-in ones miss, and runs the AI review. --max-cost-usd stops the review at that spend, and running the command again continues it.

Notes

  • The lockfile pins 288 packages, all tooling. GitHub's dependency graph will list them, and Renovate will likely propose deepsec updates as it does for e2e/.

Checklist

  • I understand the code in this PR and the problem it solves.
  • I read this description, and it accurately describes the change.
Open in Web Open in Cursor 

Summary by cubic

Adds a .deepsec/ workspace so maintainers can run deepsec security reviews of the SDK locally. Nothing here runs in CI or ships in the npm package.

  • Pins deepsec 2.3.12 with a lockfile; .deepsec/ is its own pnpm workspace.
  • Adds data/resend-node/INFO.md, the project context (what the SDK does, how the API key is handled, threat model, patterns to flag, known false positives) that deepsec injects into every AI review.
  • Keeps regenerated scan output out of the public repo via .gitignore, and has Biome skip .deepsec because deepsec rewrites its config files in its own style.
  • Verified that root pnpm lint, pnpm typecheck, and pnpm test still pass and npm pack lists no .deepsec files.

To finish setup

The AI review has not run yet and requires a model credential. From .deepsec/, run pnpm deepsec setup --model-profile value --max-cost-usd 25 (uses Vercel AI Gateway and logs in to Vercel) or --agent codex --model-auth direct --ai-provider openai --ai-api-key-env MY_KEY to use an OpenAI key. Setup inventories the SDK's surfaces, generates matchers, and runs the review; --max-cost-usd caps the spend and can be resumed.

Notes

  • The workspace docs warn that deepsec copies the origin remote URL into the ignored data/*/project.json and into exported finding links, so a token embedded in that URL leaks into both.