payload-doctor 0.5.4

package/dist/checks/project.js

@@ -0,0 +1,235 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectChecks = projectChecks;
+const ts_morph_1 = require("ts-morph");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const util_1 = require("../util");
+/** Line number (1-based) of the first occurrence of `needle` in `text`, else 1. */
+function lineOf(text, needle) {
+    const idx = text.indexOf(needle);
+    if (idx < 0)
+        return 1;
+    return text.slice(0, idx).split('\n').length;
+}
+/**
+ * All `payload` and `@payloadcms/*` packages must be on the exact same version;
+ * a mismatch is one of the most common causes of mysterious build/runtime breaks.
+ * Reads the root package.json (skips ranges/tags/workspace specs we can't compare).
+ */
+function dependencyVersionMismatch(ctx) {
+    const pkgPath = path.join(ctx.root, 'package.json');
+    let text;
+    try {
+        text = fs.readFileSync(pkgPath, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    let pkg;
+    try {
+        pkg = JSON.parse(text);
+    }
+    catch {
+        return [];
+    }
+    // Defensive schema guard: a malformed package.json (non-object root, or
+    // dependencies that aren't objects) must not throw — just skip the check.
+    if (typeof pkg !== 'object' || pkg === null || Array.isArray(pkg))
+        return [];
+    const asObj = (v) => v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+    const deps = { ...asObj(pkg.dependencies), ...asObj(pkg.devDependencies) };
+    const byVersion = new Map();
+    for (const [name, spec] of Object.entries(deps)) {
+        if (name !== 'payload' && !name.startsWith('@payloadcms/'))
+            continue;
+        if (typeof spec !== 'string')
+            continue;
+        const v = spec.replace(/^[\^~>=<\s]+/, '');
+        if (!/^\d+\.\d+\.\d+/.test(v))
+            continue; // skip ranges/tags/workspace:* etc.
+        const arr = byVersion.get(v) ?? [];
+        arr.push(name);
+        byVersion.set(v, arr);
+    }
+    if (byVersion.size < 2)
+        return [];
+    const summary = [...byVersion.entries()].map(([v, names]) => `${names.length}×${v}`).join(', ');
+    const line = lineOf(text, '@payloadcms/') || lineOf(text, '"payload"');
+    return [
+        {
+            ruleId: 'dependency-version-mismatch',
+            category: 'config',
+            severity: 'error',
+            message: `Mismatched payload / @payloadcms/* versions in package.json (${summary}) — keep all Payload packages on one version`,
+            file: ctx.rel(pkgPath),
+            line,
+            column: 1,
+            hint: 'Pin every payload and @payloadcms/* dependency to the exact same version.',
+        },
+    ];
+}
+/**
+ * Cross-file: relationship/upload fields that form a cycle (A → B → A or a
+ * self-reference). Cycles are often legitimate (category trees, related posts),
+ * so this is `info` — a reminder that maxDepth must bound population to avoid
+ * runaway queries.
+ */
+function circularRelationships(files, ctx) {
+    const adj = new Map();
+    const nodeBySlug = new Map();
+    for (const file of files) {
+        for (const obj of file.getDescendantsOfKind(ts_morph_1.SyntaxKind.ObjectLiteralExpression)) {
+            if ((0, util_1.getConfigKind)(obj) !== 'collection')
+                continue;
+            const slugInit = (0, util_1.propInit)(obj, 'slug');
+            if (!slugInit || !ts_morph_1.Node.isStringLiteral(slugInit))
+                continue;
+            const slug = slugInit.getLiteralValue();
+            nodeBySlug.set(slug, slugInit);
+            const targets = adj.get(slug) ?? new Set();
+            for (const field of obj.getDescendantsOfKind(ts_morph_1.SyntaxKind.ObjectLiteralExpression)) {
+                const t = (0, util_1.propInit)(field, 'type');
+                if (!t || !ts_morph_1.Node.isStringLiteral(t))
+                    continue;
+                const tv = t.getLiteralValue();
+                if (tv !== 'relationship' && tv !== 'upload')
+                    continue;
+                const rel = (0, util_1.propInit)(field, 'relationTo');
+                if (!rel)
+                    continue;
+                if (ts_morph_1.Node.isStringLiteral(rel))
+                    targets.add(rel.getLiteralValue());
+                else if (ts_morph_1.Node.isArrayLiteralExpression(rel)) {
+                    for (const el of rel.getElements())
+                        if (ts_morph_1.Node.isStringLiteral(el))
+                            targets.add(el.getLiteralValue());
+                }
+            }
+            adj.set(slug, targets);
+        }
+    }
+    const known = new Set(adj.keys());
+    // Tarjan's SCC: O(V+E). A collection is in a cycle if its strongly-connected
+    // component has >1 member, or it references itself (self-loop).
+    let index = 0;
+    const idx = new Map();
+    const low = new Map();
+    const onStack = new Set();
+    const stack = [];
+    const sccOf = new Map();
+    const strongconnect = (v) => {
+        idx.set(v, index);
+        low.set(v, index);
+        index++;
+        stack.push(v);
+        onStack.add(v);
+        for (const w of adj.get(v) ?? []) {
+            if (!known.has(w))
+                continue;
+            if (!idx.has(w)) {
+                strongconnect(w);
+                low.set(v, Math.min(low.get(v), low.get(w)));
+            }
+            else if (onStack.has(w)) {
+                low.set(v, Math.min(low.get(v), idx.get(w)));
+            }
+        }
+        if (low.get(v) === idx.get(v)) {
+            const comp = [];
+            let w;
+            do {
+                w = stack.pop();
+                onStack.delete(w);
+                comp.push(w);
+            } while (w !== v);
+            for (const m of comp)
+                sccOf.set(m, comp);
+        }
+    };
+    for (const v of known)
+        if (!idx.has(v))
+            strongconnect(v);
+    const findings = [];
+    for (const slug of known) {
+        const comp = sccOf.get(slug) ?? [slug];
+        // NOTE: the selfLoop check is NOT redundant — Tarjan puts a self-referencing
+        // node in a size-1 SCC, indistinguishable from an acyclic node, so a plain
+        // SCC-size>1 test would miss real self-loops (e.g. articles -> articles).
+        const selfLoop = adj.get(slug)?.has(slug) ?? false;
+        if (comp.length < 2 && !selfLoop)
+            continue;
+        const node = nodeBySlug.get(slug);
+        if (!node)
+            continue;
+        const pathStr = comp.length >= 2 ? `${comp.join(' → ')} → ${comp[0]}` : `${slug} → ${slug}`;
+        findings.push((0, util_1.makeFinding)(node, ctx, 'circular-relationship', 'correctness', 'info', `Circular relationship: ${pathStr} — ensure maxDepth bounds population so queries don't recurse endlessly`, 'Cycles are fine (e.g. category trees); just keep query depth small and avoid populating the loop fully.'));
+    }
+    return findings;
+}
+/**
+ * Cross-file check: the same slug defined on more than one collection/global.
+ * Slugs must be unique — Payload derives DB collections and admin/API routes
+ * from them, so a duplicate silently shadows one definition.
+ */
+function projectChecks(files, ctx) {
+    const bySlug = new Map();
+    for (const file of files) {
+        for (const obj of file.getDescendantsOfKind(ts_morph_1.SyntaxKind.ObjectLiteralExpression)) {
+            const kind = (0, util_1.getConfigKind)(obj);
+            if (kind !== 'collection' && kind !== 'global')
+                continue;
+            const slugInit = (0, util_1.propInit)(obj, 'slug');
+            if (!slugInit || !ts_morph_1.Node.isStringLiteral(slugInit))
+                continue;
+            const val = slugInit.getLiteralValue();
+            const arr = bySlug.get(val) ?? [];
+            arr.push(slugInit);
+            bySlug.set(val, arr);
+        }
+    }
+    const findings = [];
+    for (const [val, nodes] of bySlug) {
+        if (nodes.length < 2)
+            continue;
+        for (const n of nodes) {
+            findings.push((0, util_1.makeFinding)(n, ctx, 'duplicate-slug', 'config', 'error', `Duplicate slug "${val}" — defined ${nodes.length} times across collections/globals`, 'Slugs must be unique; Payload builds DB collections and routes from them.'));
+        }
+    }
+    findings.push(...dependencyVersionMismatch(ctx));
+    findings.push(...circularRelationships(files, ctx));
+    return findings;
+}

package/dist/checks/quality.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.qualityChecks = void 0;
+const ts_morph_1 = require("ts-morph");
+const util_1 = require("../util");
+const LOOP_KINDS = new Set([
+    ts_morph_1.SyntaxKind.ForStatement,
+    ts_morph_1.SyntaxKind.ForOfStatement,
+    ts_morph_1.SyntaxKind.ForInStatement,
+    ts_morph_1.SyntaxKind.WhileStatement,
+    ts_morph_1.SyntaxKind.DoStatement,
+]);
+const ITER_METHODS = new Set(['map', 'forEach', 'filter', 'reduce', 'flatMap', 'some', 'every']);
+/** Is this node lexically inside a loop or an array-iteration callback? */
+function insideIteration(node) {
+    let cur = node.getParent();
+    while (cur) {
+        if (LOOP_KINDS.has(cur.getKind()))
+            return true;
+        if (ts_morph_1.Node.isCallExpression(cur)) {
+            const expr = cur.getExpression();
+            if (ts_morph_1.Node.isPropertyAccessExpression(expr) && ITER_METHODS.has(expr.getName())) {
+                // only count it if our node is in an argument (the callback), not the array
+                if (cur.getArguments().some((a) => a === node || a.getDescendants().includes(node)))
+                    return true;
+            }
+        }
+        cur = cur.getParent();
+    }
+    return false;
+}
+/**
+ * A Local API read (`payload.find`/`findByID`/`findGlobal`) inside a loop or
+ * map/forEach callback is the classic N+1: one query per iteration. Batch it
+ * (a single `find` with an `in` filter) instead.
+ */
+const hookNPlusOne = {
+    id: 'hook-n-plus-one',
+    category: 'correctness',
+    describe: 'Local API read inside a loop / map (N+1 query)',
+    run(file, ctx) {
+        const findings = [];
+        for (const call of file.getDescendantsOfKind(ts_morph_1.SyntaxKind.CallExpression)) {
+            const local = (0, util_1.isLocalApiCall)(call);
+            if (!local || !util_1.READ_METHODS.has(local.method))
+                continue;
+            if (!insideIteration(call))
+                continue;
+            // If the queried collection/global is a string literal, every iteration hits
+            // the SAME collection -> a real, batchable N+1 (warning). If it's dynamic
+            // (a variable/expression), the loop likely spans different collections per
+            // item and can't be trivially batched -> info.
+            const target = (0, util_1.propInit)(local.arg, 'collection') ?? (0, util_1.propInit)(local.arg, 'global');
+            const literalTarget = !!target && ts_morph_1.Node.isStringLiteral(target);
+            const severity = literalTarget ? 'warning' : 'info';
+            findings.push((0, util_1.makeFinding)(call, ctx, 'hook-n-plus-one', 'correctness', severity, literalTarget
+                ? `payload.${local.method} runs inside a loop/iteration on a fixed collection — one query per item (N+1)`
+                : `payload.${local.method} runs inside a loop on a dynamic collection — batch where possible (likely heterogeneous, so info)`, 'If the collection is fixed, fetch once with { where: { id: { in: ids } } } and map over the result.'));
+        }
+        return findings;
+    },
+};
+const SENSITIVE_LOG_WORDS = new Set([
+    'password',
+    'token',
+    'secret',
+    'apikey',
+    'privatekey',
+    'creditcard',
+    'ssn',
+    'cvv',
+]);
+const CONSOLE_METHODS = new Set(['log', 'error', 'warn', 'info', 'debug', 'trace']);
+/**
+ * Logging a sensitive value (password/token/secret/…) leaks it into stdout and
+ * log aggregators. We match explicit sensitive property accesses in console.* args.
+ */
+const sensitiveDataLogged = {
+    id: 'sensitive-data-logged',
+    category: 'security',
+    describe: 'console.* logs a sensitive value (password/token/secret/…)',
+    run(file, ctx) {
+        const findings = [];
+        for (const call of file.getDescendantsOfKind(ts_morph_1.SyntaxKind.CallExpression)) {
+            const expr = call.getExpression();
+            if (!ts_morph_1.Node.isPropertyAccessExpression(expr))
+                continue;
+            if (expr.getExpression().getText() !== 'console')
+                continue;
+            if (!CONSOLE_METHODS.has(expr.getName()))
+                continue;
+            for (const arg of call.getArguments()) {
+                // property accesses like data.password, req.user.token
+                const accesses = arg.getDescendantsOfKind(ts_morph_1.SyntaxKind.PropertyAccessExpression);
+                const targets = accesses.length ? accesses : (ts_morph_1.Node.isPropertyAccessExpression(arg) ? [arg] : []);
+                const hit = targets.some((a) => (0, util_1.nameSegments)(a.getName()).some((s) => SENSITIVE_LOG_WORDS.has(s)));
+                if (hit) {
+                    findings.push((0, util_1.makeFinding)(call, ctx, 'sensitive-data-logged', 'security', 'warning', 'A sensitive value (password/token/secret/…) is written to the console', 'Remove the log or redact the field; logs end up in stdout and aggregators.'));
+                    break;
+                }
+            }
+        }
+        return findings;
+    },
+};
+exports.qualityChecks = [hookNPlusOne, sensitiveDataLogged];

package/dist/checks/rendering.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderingChecks = void 0;
+const ts_morph_1 = require("ts-morph");
+const util_1 = require("../util");
+// Signals that a file deals with Payload rich text / CMS HTML.
+const CMS_IMPORT = /(@payloadcms\/richtext|richtext-lexical|\blexical\b|serializeLexical|slate|RichText|from ['"]payload)/i;
+// Signals that the rendered expression is CMS content.
+const CMS_NAME = /(richtext|\bcontent\b|\bbody\b|\bhtml\b|lexical|serialized|\bblocks?\b|\bdescription\b)/i;
+// Signals the HTML is already sanitized.
+const SANITIZED = /sanitize|dompurify|\bpurify\b|clean\s*\(/i;
+function htmlExpressionText(attr) {
+    if (!ts_morph_1.Node.isJsxAttribute(attr))
+        return '';
+    const init = attr.getInitializer();
+    if (!init || !ts_morph_1.Node.isJsxExpression(init))
+        return '';
+    const inner = init.getExpression();
+    if (!inner)
+        return '';
+    if (ts_morph_1.Node.isObjectLiteralExpression(inner)) {
+        const p = inner.getProperty('__html');
+        if (p && ts_morph_1.Node.isPropertyAssignment(p))
+            return p.getInitializer()?.getText() ?? '';
+        return inner.getText();
+    }
+    return inner.getText();
+}
+/**
+ * The block-render seam: rendering Payload rich text / block HTML into React
+ * (often shadcn/ui) via dangerouslySetInnerHTML without sanitization is a stored
+ * XSS risk when the source content is user-writable. We only flag cases that
+ * look like CMS content (otherwise it's a generic React concern for react-doctor).
+ */
+const unsafeRichtextRender = {
+    id: 'unsafe-richtext-render',
+    category: 'rendering',
+    describe: 'dangerouslySetInnerHTML renders CMS/rich-text content without sanitization',
+    run(file, ctx) {
+        const findings = [];
+        const fileText = file.getFullText();
+        const importSignal = CMS_IMPORT.test(fileText);
+        for (const attr of file.getDescendantsOfKind(ts_morph_1.SyntaxKind.JsxAttribute)) {
+            if (attr.getNameNode().getText() !== 'dangerouslySetInnerHTML')
+                continue;
+            const html = htmlExpressionText(attr);
+            if (SANITIZED.test(html))
+                continue; // already sanitized
+            // only flag when it clearly handles CMS/rich-text content
+            if (!importSignal && !CMS_NAME.test(html))
+                continue;
+            findings.push((0, util_1.makeFinding)(attr, ctx, 'unsafe-richtext-render', 'rendering', 'info', 'dangerouslySetInnerHTML renders rich-text/CMS HTML — review this sink: a static tool cannot tell whether the source is sanitized', 'If the HTML can ever come from user input, sanitize it (e.g. DOMPurify) and restrict write access to the source collection.'));
+        }
+        return findings;
+    },
+};
+exports.renderingChecks = [unsafeRichtextRender];

package/dist/checks/routes.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.routeChecks = void 0;
+const ts_morph_1 = require("ts-morph");
+const util_1 = require("../util");
+/**
+ * Fail-open secret check: `if (secret && header !== ...) return 401` means that
+ * when the secret is unset the guard is skipped and the endpoint is public.
+ */
+const cronNotFailClosed = {
+    id: 'cron-not-fail-closed',
+    category: 'security',
+    describe: 'Secret/cron auth check is fail-open (missing secret leaves endpoint public)',
+    run(file, ctx) {
+        const findings = [];
+        for (const ifStmt of file.getDescendantsOfKind(ts_morph_1.SyntaxKind.IfStatement)) {
+            const cond = ifStmt.getExpression();
+            if (!ts_morph_1.Node.isBinaryExpression(cond))
+                continue;
+            if (cond.getOperatorToken().getKind() !== ts_morph_1.SyntaxKind.AmpersandAmpersandToken)
+                continue;
+            const leftText = cond.getLeft().getText();
+            // Left operand is a bare secret-ish truthiness guard.
+            if (!/secret|token|apikey|api_key/i.test(leftText))
+                continue;
+            if (/[=!<>]/.test(leftText))
+                continue; // left already a comparison, not a bare guard
+            const thenText = ifStmt.getThenStatement().getText();
+            if (!/(401|403|unauthorized|forbidden|return|throw)/i.test(thenText))
+                continue;
+            findings.push((0, util_1.makeFinding)(ifStmt, ctx, 'cron-not-fail-closed', 'security', 'error', 'Auth guard is fail-open: if the secret is unset the check is skipped and the endpoint stays public', 'Fail closed: if (!secret) return 500/false BEFORE comparing the header.'));
+        }
+        return findings;
+    },
+};
+function bodyHasMutation(node) {
+    for (const call of node.getDescendantsOfKind(ts_morph_1.SyntaxKind.CallExpression)) {
+        const local = (0, util_1.isLocalApiCall)(call);
+        if (local && util_1.MUTATION_METHODS.has(local.method))
+            return call;
+    }
+    return undefined;
+}
+/**
+ * GET handlers that write are triggered by prefetch / link scanners / double
+ * renders. Detects Next.js `export function GET` and Payload endpoints with
+ * method:'get' whose body performs a Local API mutation.
+ */
+const sideEffectInGet = {
+    id: 'side-effect-in-get',
+    category: 'correctness',
+    describe: 'GET handler performs a write (prefetch/scanner can trigger it)',
+    run(file, ctx) {
+        const findings = [];
+        const path = file.getFilePath();
+        const isCron = /\/cron\//i.test(path);
+        const isUnsub = !isCron && /unsubscribe|opt-?out/i.test(path);
+        const sev = isCron ? 'info' : isUnsub ? 'warning' : 'error';
+        const note = isCron
+            ? ' (Vercel cron requires GET — ensure the write is idempotent)'
+            : isUnsub
+                ? ' (email one-click unsubscribe — but mail-client prefetch can auto-trigger it; prefer RFC 8058 List-Unsubscribe-Post or a confirm step)'
+                : '';
+        // Next.js route handlers: export async function GET(...) {}
+        for (const fn of file.getFunctions()) {
+            if (fn.getName() !== 'GET')
+                continue;
+            const body = fn.getBody();
+            if (!body)
+                continue;
+            const mutation = bodyHasMutation(body);
+            if (mutation) {
+                findings.push((0, util_1.makeFinding)(fn.getNameNode() ?? fn, ctx, 'side-effect-in-get', 'correctness', sev, `GET route handler performs a write — link prefetch or email scanners can trigger it unintentionally${note}`, 'Move the side effect to POST, or add an idempotency guard.'));
+            }
+        }
+        // Payload custom endpoints: { method: 'get', handler: ... }
+        for (const obj of file.getDescendantsOfKind(ts_morph_1.SyntaxKind.ObjectLiteralExpression)) {
+            const methodProp = obj.getProperty('method');
+            if (!methodProp || !ts_morph_1.Node.isPropertyAssignment(methodProp))
+                continue;
+            const m = methodProp.getInitializer()?.getText().replace(/['"`]/g, '').toLowerCase();
+            if (m !== 'get')
+                continue;
+            const handlerProp = obj.getProperty('handler');
+            if (!handlerProp)
+                continue;
+            const mutation = bodyHasMutation(obj);
+            if (mutation) {
+                findings.push((0, util_1.makeFinding)(methodProp, ctx, 'side-effect-in-get', 'correctness', sev, `Payload endpoint with method:'get' performs a write${note}`, 'Use method:\'post\' for mutating endpoints, or guard against repeated calls.'));
+            }
+        }
+        return findings;
+    },
+};
+/** Returning error.message / error.stack to the client leaks internals. */
+const leaksErrorMessage = {
+    id: 'leaks-error-message',
+    category: 'security',
+    describe: 'Internal error message/stack returned to the client',
+    run(file, ctx) {
+        const findings = [];
+        for (const pa of file.getDescendantsOfKind(ts_morph_1.SyntaxKind.PropertyAssignment)) {
+            const name = pa.getName().replace(/['"`]/g, '');
+            if (name !== 'error' && name !== 'message')
+                continue;
+            const initText = pa.getInitializer()?.getText() ?? '';
+            if (/(^|[^\w.])(err|error|e|ex|exception)\s*\.\s*(message|stack)\b/.test(initText)) {
+                findings.push((0, util_1.makeFinding)(pa, ctx, 'leaks-error-message', 'security', 'warning', 'Response leaks an internal error message/stack to the client', 'Log the error server-side; return a generic message like "Internal server error".'));
+            }
+        }
+        return findings;
+    },
+};
+exports.routeChecks = [cronNotFailClosed, sideEffectInGet, leaksErrorMessage];