payload-doctor 0.5.4

package/dist/util.js

@@ -0,0 +1,281 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOCAL_API_METHODS = exports.READ_METHODS = exports.MUTATION_METHODS = void 0;
+exports.lineCol = lineCol;
+exports.makeFinding = makeFinding;
+exports.firstObjectArg = firstObjectArg;
+exports.propText = propText;
+exports.propInit = propInit;
+exports.hasProp = hasProp;
+exports.hasSpread = hasSpread;
+exports.unquote = unquote;
+exports.nameSegments = nameSegments;
+exports.hasSegment = hasSegment;
+exports.isLocalApiCall = isLocalApiCall;
+exports.enclosingArrayProp = enclosingArrayProp;
+exports.directTypeHint = directTypeHint;
+exports.getConfigKind = getConfigKind;
+exports.isCollectionConfig = isCollectionConfig;
+exports.isAuthCollection = isAuthCollection;
+exports.getFieldObjects = getFieldObjects;
+exports.returnsTrue = returnsTrue;
+exports.callsIn = callsIn;
+exports.isSystemPath = isSystemPath;
+exports.isServerJobPath = isServerJobPath;
+exports.looksLikeRequestFile = looksLikeRequestFile;
+const ts_morph_1 = require("ts-morph");
+/** Payload Local API mutation methods (write operations). */
+exports.MUTATION_METHODS = new Set(['create', 'update', 'delete']);
+/** Payload Local API read methods. */
+exports.READ_METHODS = new Set(['find', 'findByID', 'findGlobal']);
+exports.LOCAL_API_METHODS = new Set([...exports.MUTATION_METHODS, ...exports.READ_METHODS]);
+function lineCol(node) {
+    const sf = node.getSourceFile();
+    const { line, column } = sf.getLineAndColumnAtPos(node.getStart());
+    return { line, column };
+}
+function makeFinding(node, ctx, ruleId, category, severity, message, hint, fix) {
+    const { line, column } = lineCol(node);
+    return {
+        ruleId,
+        category,
+        severity,
+        message,
+        file: ctx.rel(node.getSourceFile().getFilePath()),
+        line,
+        column,
+        hint,
+        fix,
+    };
+}
+/** First object-literal argument of a call, if any. */
+function firstObjectArg(call) {
+    const arg = call.getArguments()[0];
+    if (arg && ts_morph_1.Node.isObjectLiteralExpression(arg))
+        return arg;
+    return undefined;
+}
+/** Get a string-ish value of an object property (initializer text without quotes). */
+function propText(obj, name) {
+    const prop = obj.getProperty(name);
+    if (!prop || !ts_morph_1.Node.isPropertyAssignment(prop))
+        return undefined;
+    const init = prop.getInitializer();
+    return init?.getText();
+}
+/** Raw initializer node of an object property. */
+function propInit(obj, name) {
+    const prop = obj.getProperty(name);
+    if (!prop || !ts_morph_1.Node.isPropertyAssignment(prop))
+        return undefined;
+    return prop.getInitializer();
+}
+function hasProp(obj, name) {
+    return obj.getProperty(name) !== undefined;
+}
+/** True if the object literal contains a spread (...x) we cannot statically see into. */
+function hasSpread(obj) {
+    return obj.getProperties().some((p) => ts_morph_1.Node.isSpreadAssignment(p));
+}
+function unquote(s) {
+    if (s === undefined)
+        return undefined;
+    return s.replace(/^['"`]|['"`]$/g, '');
+}
+/**
+ * Split a field/identifier name into lowercase word segments, handling
+ * camelCase and separators. "resetToken" -> ["reset","token"],
+ * "hashtags" -> ["hashtags"]. Lets checks match whole words instead of
+ * fragile substrings (so "hashtag" never matches "hash").
+ */
+function nameSegments(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .split(/[^a-zA-Z0-9]+/)
+        .filter(Boolean)
+        .map((s) => s.toLowerCase());
+}
+/** True if any word segment of `name` is in the given set. */
+function hasSegment(name, words) {
+    return nameSegments(name).some((seg) => words.has(seg));
+}
+/**
+ * A Payload Local API call looks like `x.<method>({ collection: '...', ... })`.
+ * We discriminate from generic Array#find etc. by requiring the first argument
+ * to be an object literal carrying a `collection` (or `global`) property.
+ */
+function isLocalApiCall(call) {
+    const expr = call.getExpression();
+    if (!ts_morph_1.Node.isPropertyAccessExpression(expr))
+        return undefined;
+    const method = expr.getName();
+    if (!exports.LOCAL_API_METHODS.has(method))
+        return undefined;
+    const arg = firstObjectArg(call);
+    if (!arg)
+        return undefined;
+    if (!hasProp(arg, 'collection') && !hasProp(arg, 'global'))
+        return undefined;
+    return { method, arg };
+}
+/** Name of the array property an object literal is an element of, if any. */
+function enclosingArrayProp(obj) {
+    const arr = obj.getParentIfKind(ts_morph_1.SyntaxKind.ArrayLiteralExpression);
+    if (!arr)
+        return undefined;
+    const pa = arr.getParentIfKind(ts_morph_1.SyntaxKind.PropertyAssignment);
+    if (!pa)
+        return undefined;
+    return pa.getName().replace(/['"`]/g, '');
+}
+/** Type annotation directly attached to this object (const x: T =, as T, satisfies T). */
+function directTypeHint(obj) {
+    let target = obj;
+    let p = obj.getParent();
+    while (p && (ts_morph_1.Node.isAsExpression(p) || ts_morph_1.Node.isSatisfiesExpression(p) || ts_morph_1.Node.isParenthesizedExpression(p))) {
+        const tn = p.getTypeNode?.();
+        if (tn)
+            return tn.getText();
+        target = p;
+        p = p.getParent();
+    }
+    if (p && ts_morph_1.Node.isVariableDeclaration(p) && p.getInitializer() === target) {
+        return p.getTypeNode()?.getText() ?? '';
+    }
+    return '';
+}
+/**
+ * Classify a `{ slug, fields }` object. Payload blocks and globals share that
+ * shape with collections, so we use position, type annotation and path to avoid
+ * flagging blocks/globals as collections (the #1 false-positive source).
+ */
+function getConfigKind(obj) {
+    if (!hasProp(obj, 'slug') || !hasProp(obj, 'fields'))
+        return 'unknown';
+    const prop = enclosingArrayProp(obj);
+    if (prop === 'blocks')
+        return 'block';
+    if (prop === 'globals')
+        return 'global';
+    if (prop === 'collections')
+        return 'collection';
+    if (prop === 'fields')
+        return 'block'; // a sub-config inside fields, not a collection
+    // Nested inside any enclosing config that has `fields` -> it's a block/sub-config.
+    let cur = obj.getParent();
+    while (cur) {
+        if (ts_morph_1.Node.isObjectLiteralExpression(cur) && hasProp(cur, 'fields'))
+            return 'block';
+        cur = cur.getParent();
+    }
+    const hint = directTypeHint(obj);
+    if (/\bBlock\b/.test(hint))
+        return 'block';
+    if (/GlobalConfig/.test(hint))
+        return 'global';
+    if (/CollectionConfig/.test(hint))
+        return 'collection';
+    const path = obj.getSourceFile().getFilePath();
+    if (/\/blocks?\//i.test(path))
+        return 'block';
+    if (/\/globals?\//i.test(path))
+        return 'global';
+    if (/\/collections?\//i.test(path))
+        return 'collection';
+    return 'unknown';
+}
+/**
+ * True only for confirmed collection configs. Blocks, globals and nested field
+ * configs are excluded so collection-level checks don't misfire on them.
+ */
+function isCollectionConfig(obj) {
+    return getConfigKind(obj) === 'collection';
+}
+/** Does the collection look like an auth collection (public registration is normal)? */
+function isAuthCollection(obj) {
+    return hasProp(obj, 'auth');
+}
+/** Return the `fields` array element object-literals of a collection config. */
+function getFieldObjects(collection) {
+    const fieldsInit = propInit(collection, 'fields');
+    if (!fieldsInit || !ts_morph_1.Node.isArrayLiteralExpression(fieldsInit))
+        return [];
+    return fieldsInit
+        .getElements()
+        .filter(ts_morph_1.Node.isObjectLiteralExpression);
+}
+/** Does an arrow/function initializer effectively `return true`? */
+/**
+ * True only if the function *unconditionally* returns boolean `true`:
+ *   () => true              (arrow expression body)
+ *   () => { return true }   (block whose first statement returns true)
+ *   function () { return true }
+ * Conditional returns (a guard before `return true`), expressions like
+ * `() => true && x`, and unresolvable identifiers (`read: publicRead`) all
+ * return false. AST-based, so it doesn't false-match on substrings.
+ * Non-goal (scope demarcation, not risk-avoidance): this is a focused heuristic for the
+ * literal-`true` case. Folding always-truthy expressions like `() => (!false)` or
+ * `() => 1 === 1` is a separate concern with a different scope — it would belong in a
+ * dedicated `always-truthy-expression` check, not in this predicate.
+ */
+function returnsTrue(init) {
+    if (!init)
+        return false;
+    const firstStatementReturnsTrue = (body) => {
+        if (!ts_morph_1.Node.isBlock(body))
+            return false;
+        const first = body.getStatements()[0];
+        if (!first || !ts_morph_1.Node.isReturnStatement(first))
+            return false;
+        const expr = first.getExpression();
+        return !!expr && expr.getKind() === ts_morph_1.SyntaxKind.TrueKeyword;
+    };
+    if (ts_morph_1.Node.isArrowFunction(init)) {
+        const body = init.getBody();
+        if (ts_morph_1.Node.isBlock(body))
+            return firstStatementReturnsTrue(body);
+        let e = body;
+        while (ts_morph_1.Node.isParenthesizedExpression(e))
+            e = e.getExpression();
+        return e.getKind() === ts_morph_1.SyntaxKind.TrueKeyword;
+    }
+    if (ts_morph_1.Node.isFunctionExpression(init) || ts_morph_1.Node.isFunctionDeclaration(init)) {
+        const body = init.getBody();
+        return !!body && firstStatementReturnsTrue(body);
+    }
+    return false;
+}
+/** Find every CallExpression in a node subtree. */
+function callsIn(node) {
+    return node.getDescendantsOfKind(ts_morph_1.SyntaxKind.CallExpression);
+}
+/** True if the file path looks like a migration/seed/script (system writes allowed). */
+function isSystemPath(path) {
+    return /(migrations?|seeds?|scripts?|\.test\.|\.spec\.)/i.test(path);
+}
+/**
+ * Broader "runs as the system, not on behalf of an end-user request" signal:
+ * cron jobs, webhook receivers, background sync/worker/job files. In these the
+ * Local API's default `overrideAccess: true` is expected, not a bug.
+ */
+function isServerJobPath(path) {
+    if (isSystemPath(path))
+        return true;
+    if (/\/(cron|webhooks?|workers?|jobs|tasks|queue)\//i.test(path))
+        return true;
+    if (/(^|\/|[-.])sync(\.|-|$)/i.test(path) || /-(sync|worker|job|cron)\.(ts|js|tsx|jsx)$/i.test(path))
+        return true;
+    return false;
+}
+/** True if the file path looks like a request handler (Next route / server action). */
+function looksLikeRequestFile(file) {
+    const p = file.getFilePath();
+    if (/\/(app|pages)\/.*\/route\.(ts|js|tsx|jsx)$/.test(p))
+        return true;
+    if (/\/api\//.test(p))
+        return true;
+    const text = file.getFullText();
+    if (/['"]use server['"]/.test(text))
+        return true;
+    return false;
+}

package/dist/version.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = void 0;
+// Keep in sync with package.json "version".
+exports.VERSION = '0.5.4';

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "payload-doctor",
+  "version": "0.5.4",
+  "description": "Static security & correctness linter for Payload CMS (the headless CMS) — audits collections, access control, hooks, routes and config. Not an API-payload validator.",
+  "type": "commonjs",
+  "bin": {
+    "payload-doctor": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "SKILL.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "test": "npm run build && node test/run.mjs",
+    "selftest": "node dist/cli.js test/fixtures/vulnerable --verbose"
+  },
+  "keywords": [
+    "payload",
+    "payloadcms",
+    "security",
+    "linter",
+    "audit",
+    "static-analysis",
+    "access-control",
+    "nextjs",
+    "payload-cms",
+    "ts-morph"
+  ],
+  "license": "MIT",
+  "author": "Leander M. von Kraft (https://www.metakraft.de)",
+  "homepage": "https://github.com/metakraft/payload-doctor#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/metakraft/payload-doctor.git"
+  },
+  "bugs": {
+    "url": "https://github.com/metakraft/payload-doctor/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "ts-morph": "^24.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.0.0"
+  }
+}