payload-doctor
Static security & correctness linter for Payload CMS — the TypeScript headless CMS. It scans your collections, access control, hooks, routes and config for known anti-patterns — the kind that AI coding agents and humans alike get wrong — and prints a 0–100 health score with actionable findings.
Note: this is for Payload CMS (the framework). It does not inspect or validate API request/response payloads (JSON/XML). If you came looking for that, this isn't it.
Think of it as a react-doctor for Payload. One command, no install:
npx -y payload-doctor@latest .
Why
Payload's Local API bypasses access control by default (overrideAccess is
true unless you set it to false). It's the single most expensive footgun in a
Payload app: a route can authenticate a user and still hand them someone else's
records, because the collection's access functions never run. payload-doctor
catches that and a dozen related issues before they reach production.
Usage
# scan the current project
npx -y payload-doctor@latest .
# show fix hints
npx -y payload-doctor@latest . --verbose
# machine-readable output for CI / dashboards
npx -y payload-doctor@latest . --json
# big report? show only the per-rule rollup
npx -y payload-doctor@latest . --summary
# print a suggested fix per rule (never modifies files)
npx -y payload-doctor@latest . --fix
# fail a CI job if the score drops below a threshold
npx -y payload-doctor@latest . --min-score 80
# print the version
npx -y payload-doctor@latest --version
Recommended workflow: run it → fix the errors first → re-run and watch the score climb. Keep a clean git state before applying fixes.
Score bands: 75–100 great · 50–74 needs work · 0–49 critical.
The score is max(0, 100 − 10·errors − 3·warnings); info findings don't affect
it. Ten or more errors floor it at 0 by design — once you're in the red, track
the dropping error/warning counts (and the per-rule summary) to gauge progress
rather than the score alone.
Exit code is 1 when any error-severity finding is present (or the score is
below --min-score), 0 otherwise — drop it straight into CI or a pre-commit
hook. Use --no-exit-code while you're adopting it.
Suppressing intentional cases
Some findings are deliberate — an OAuth callback that writes on GET, a cron
job using overrideAccess: true. Silence them inline, ESLint-style:
// payload-doctor-disable-next-line local-api-override-access
await payload.update({ collection: 'jobs', id, data })
// payload-doctor-disable-line side-effect-in-get
// payload-doctor-disable side-effect-in-get ← whole file; omit the rule to silence all
Rule names may be written with or without the payload-doctor/ prefix. The
number of suppressed findings is reported so suppressions stay visible.
Checks
| Rule | Category | Severity | What it catches |
|---|---|---|---|
local-api-override-access |
security | error / warning | Local API call (route handler, server action or server component) without overrideAccess: false — access control bypassed |
override-access-true-with-user |
security | error | overrideAccess: true while passing a user — control skipped on purpose |
collection-missing-access |
security | warning | Collection with no explicit access block |
open-access-function |
security | error / info | access.{create,update,delete} returns true (anyone can write) |
missing-owner-enforcement |
security | warning | User-owned collection that doesn't force ownership on create |
user-writable-privileged-field |
security | error | roles / isAdmin / … field without field-level access.update |
mass-assignment |
security | error/warning | Privileged field settable on create (auth collection, open create, no field access.create) |
cron-not-fail-closed |
security | error | Secret/cron guard that is fail-open when the secret is unset |
side-effect-in-get |
correctness | error | GET handler performs a write (prefetch / email scanners trigger it) |
leaks-error-message |
security | warning | Internal error.message / stack returned to the client |
hardcoded-secret |
security | error | Secret, key or connection string committed as a string literal |
wide-open-cors |
config | warning | CORS set to '*' |
token-field-readable |
privacy | warning | Token/hash/secret field exposed via API (no field-level read) |
unsafe-richtext-render |
rendering | info | dangerouslySetInnerHTML renders CMS/rich-text HTML — review the sink (source may or may not be sanitized) |
collection-missing-slug |
config | error | Collection/global config without a slug |
duplicate-slug |
config | error | Same slug on more than one collection/global |
hook-missing-return |
correctness | warning | Transforming hook (beforeChange/afterRead…) returns nothing |
admin-hidden-not-access |
security | warning | admin.hidden field with no field access — still returned by the API |
dependency-version-mismatch |
config | error | Mixed payload / @payloadcms/* versions in package.json |
relationship-missing-relationTo |
correctness | error | relationship/upload field without relationTo |
select-without-options |
correctness | error | select/radio field without options |
duplicate-field-name |
correctness | error | Two fields with the same name in one fields array |
auth-weak-config |
security | warning | Auth lockout disabled (maxLoginAttempts: 0) or very long tokenExpiration |
sensitive-data-logged |
security | warning | console.* logs a password/token/secret value |
reserved-field-name |
config | warning | Field/slug collides with a Payload-reserved or Mongo-illegal identifier |
excessive-max-depth |
config | warning | maxDepth/defaultDepth above 10 |
missing-index-on-filter-field |
config | info | Commonly-filtered field (email/slug/…) without index: true |
hook-n-plus-one |
correctness | warning | Local API read inside a loop / map (N+1 query) |
circular-relationship |
correctness | info | relationship/upload fields form a cycle (watch maxDepth) |
List them anytime with npx -y payload-doctor@latest --list.
The checks are static heuristics, like any linter. They are tuned for low false-positives, but always review findings in context. Files under
migrations/,seeds/,scripts/and tests are treated as trusted system code and skipped for the request-context rules.
Use with AI coding agents
This repo ships a SKILL.md, so it works as an agent skill too:
npx skills add https://github.com/metakraft/payload-doctor --skill payload-doctor
Then your agent can run the doctor after generating Payload code, fix the flagged issues, and re-run to verify — closing the gap between "AI writes code" and "code ships".
Contributing
A check is a small object implementing the Check interface (see src/types.ts)
that receives a ts-morph SourceFile and returns Finding[]. Add yours to the
relevant file in src/checks/ and register it in src/checks/index.ts. There are
self-test fixtures in test/fixtures/ — an intentionally insecure project
(vulnerable), a secure reference (clean), and a tricky set of legitimate
patterns that must NOT produce findings (the false-positive guard). Build and run
the assertion suite with:
npm install
npm test
npm test builds the project and asserts that vulnerable is flagged while
clean and tricky stay silent. Add a fixture whenever you add or change a
check, and keep the false-positive rate low — a noisy linter gets disabled.
PRs that add checks, reduce false-positives, or add fixtures are welcome.
Bugs & feature requests
Please use GitHub Issues —
there are templates for bug reports (incl. false positives) and new-check requests.
Open-ended questions and "show & tell" go in
Discussions; suspected
security issues via a private Security Advisory (see SECURITY.md). npm bugs
from a project using the package opens the issue tracker directly.
Author
Leander M. von Kraft — www.metakraft.de Tierramor Agency — AI-native project work.
Disclaimer
Provided as-is, free and open source, without warranty or any obligation — no support, no guarantees, no liability. The checks are static heuristics: they help, but you remain responsible for reviewing findings and securing your own code. Use at your own risk.
License
MIT. Free to use, modify and distribute. No rights reserved beyond the attribution the MIT license asks for.
