@agjs/tsforge 0.1.18 → 0.2.0

package/src/rule-packs/rule-metadata.ts

@@ -0,0 +1,163 @@
+import type { IRuleCatalogEntry, RuleTier } from "./rule-catalog.types";
+
+const DEFAULT_BY_TIER: Record<
+  RuleTier,
+  Omit<IRuleCatalogEntry, "tier"> & { tier: RuleTier }
+> = {
+  safety: { tier: "safety", falsePositiveRisk: "low" },
+  framework: { tier: "framework", falsePositiveRisk: "low" },
+  architecture: { tier: "architecture", falsePositiveRisk: "medium" },
+  experimental: { tier: "experimental", falsePositiveRisk: "high" },
+};
+
+/** Explicit catalog entries; unlisted rules inherit tier from pack defaults. */
+const RULE_ENTRIES: Readonly<Record<string, IRuleCatalogEntry>> = {
+  "prefer-early-return": {
+    tier: "architecture",
+    tags: ["style"],
+    falsePositiveRisk: "medium",
+  },
+  "component-folder-structure": { tier: "architecture", tags: ["react"] },
+  "no-state-in-component-body": { tier: "architecture", tags: ["react"] },
+  "no-inline-jsx-functions": { tier: "architecture", tags: ["react"] },
+  "no-anonymous-useEffect": {
+    tier: "framework",
+    tags: ["react"],
+    falsePositiveRisk: "medium",
+  },
+  "no-derived-state-in-effect": {
+    tier: "framework",
+    tags: ["react"],
+    falsePositiveRisk: "medium",
+  },
+  "no-html-img-element": { tier: "framework", tags: ["nextjs"] },
+  "catch-must-handle": { tier: "safety", tags: ["security"] },
+  "no-auth-token-in-storage": { tier: "safety", tags: ["security"] },
+  "no-child-process-exec": { tier: "safety", tags: ["security"] },
+  "no-dynamic-regexp": { tier: "safety", tags: ["security"] },
+  "no-inner-html-assignment": { tier: "safety", tags: ["security"] },
+  "no-spawn-with-shell": { tier: "safety", tags: ["security"] },
+  "no-user-controlled-redirect": { tier: "safety", tags: ["security"] },
+  "no-user-controlled-fetch-url": { tier: "safety", tags: ["security"] },
+  "no-prototype-polluting-merge": { tier: "safety", tags: ["security"] },
+  "webhook-must-verify-signature-before-parse": {
+    tier: "safety",
+    tags: ["security"],
+  },
+  "upload-must-set-limits": { tier: "safety", tags: ["security"] },
+  "mutating-route-requires-authz": {
+    tier: "experimental",
+    tags: ["authorization"],
+    falsePositiveRisk: "high",
+  },
+  "server-action-requires-authz": {
+    tier: "experimental",
+    tags: ["authorization", "nextjs"],
+    falsePositiveRisk: "high",
+  },
+  "server-action-requires-authz-and-validation": {
+    tier: "experimental",
+    tags: ["authorization", "nextjs", "validation"],
+    falsePositiveRisk: "high",
+  },
+  "jwt-must-verify-not-decode": { tier: "safety", tags: ["security", "jwt"] },
+  "auth-cookie-must-set-samesite": {
+    tier: "safety",
+    tags: ["security", "cookies"],
+  },
+  "auth-cookie-must-set-maxage-or-expires": {
+    tier: "safety",
+    tags: ["security", "cookies"],
+    falsePositiveRisk: "medium",
+  },
+  "update-delete-must-have-where": {
+    tier: "safety",
+    tags: ["drizzle", "database"],
+  },
+  "update-delete-account-scoped-must-filter-scope": {
+    tier: "safety",
+    tags: ["drizzle", "database", "multi-tenant"],
+  },
+  "caught-error-log-requires-cause": { tier: "framework", tags: ["logging"] },
+  "logger-not-console": {
+    tier: "architecture",
+    tags: ["logging"],
+    falsePositiveRisk: "medium",
+  },
+  "server-only-modules-import-server-only": {
+    tier: "framework",
+    tags: ["nextjs"],
+  },
+  "no-secret-props-to-client": { tier: "safety", tags: ["nextjs", "security"] },
+  "mutation-should-revalidate-cache": {
+    tier: "framework",
+    tags: ["nextjs"],
+    falsePositiveRisk: "medium",
+  },
+  "no-conditional-expect": { tier: "framework", tags: ["testing"] },
+  "fake-timers-must-be-restored": { tier: "framework", tags: ["testing"] },
+  "no-real-network-in-unit-tests": {
+    tier: "framework",
+    tags: ["testing"],
+    falsePositiveRisk: "medium",
+  },
+  "id-param-requires-object-authz": {
+    tier: "experimental",
+    tags: ["authorization"],
+    falsePositiveRisk: "high",
+  },
+  "fetch-must-check-ok": { tier: "safety", tags: ["async", "http"] },
+  "json-parse-must-validate": { tier: "safety", tags: ["validation"] },
+  "no-unsafe-boundary-cast": { tier: "safety", tags: ["validation"] },
+  "exported-functions-require-return-type": {
+    tier: "framework",
+    falsePositiveRisk: "medium",
+  },
+};
+
+const PACK_DEFAULT_TIER: Readonly<Record<string, RuleTier>> = {
+  security: "safety",
+  "runtime-boundaries": "safety",
+  authorization: "experimental",
+  "typescript-core": "safety",
+  "react-component-architecture": "framework",
+  nextjs: "framework",
+  fastify: "framework",
+  elysia: "framework",
+  drizzle: "framework",
+  bullmq: "framework",
+  "comment-hygiene": "architecture",
+  "code-flow": "framework",
+};
+
+export function getRuleCatalogEntry(
+  ruleId: string,
+  packId?: string
+): IRuleCatalogEntry {
+  const explicit = RULE_ENTRIES[ruleId];
+
+  if (explicit !== undefined) {
+    return explicit;
+  }
+
+  const packTier = packId !== undefined ? PACK_DEFAULT_TIER[packId] : undefined;
+  const tier = packTier ?? "framework";
+
+  return DEFAULT_BY_TIER[tier];
+}
+
+export function listRulesByTier(
+  rules: readonly { packId: string; ruleId: string }[]
+): Map<RuleTier, { packId: string; ruleId: string }[]> {
+  const byTier = new Map<RuleTier, { packId: string; ruleId: string }[]>();
+
+  for (const entry of rules) {
+    const meta = getRuleCatalogEntry(entry.ruleId, entry.packId);
+    const list = byTier.get(meta.tier) ?? [];
+
+    list.push(entry);
+    byTier.set(meta.tier, list);
+  }
+
+  return byTier;
+}

package/src/rule-packs/runtime-boundaries/index.ts

@@ -0,0 +1,33 @@
+import type { TSESLint } from "@typescript-eslint/utils";
+
+import { noPrototypePollutingMergeRule } from "./rules/no-prototype-polluting-merge";
+import { noUserControlledFetchUrlRule } from "./rules/no-user-controlled-fetch-url";
+import { noUserControlledRedirectRule } from "./rules/no-user-controlled-redirect";
+import { uploadMustSetLimitsRule } from "./rules/upload-must-set-limits";
+import { webhookMustVerifySignatureBeforeParseRule } from "./rules/webhook-must-verify-signature-before-parse";
+import type { IRulePack } from "../rule-packs.types";
+
+const rules: Record<string, TSESLint.RuleModule<string, readonly unknown[]>> = {
+  "no-prototype-polluting-merge": noPrototypePollutingMergeRule,
+  "no-user-controlled-fetch-url": noUserControlledFetchUrlRule,
+  "no-user-controlled-redirect": noUserControlledRedirectRule,
+  "upload-must-set-limits": uploadMustSetLimitsRule,
+  "webhook-must-verify-signature-before-parse":
+    webhookMustVerifySignatureBeforeParseRule,
+};
+
+export const runtimeBoundariesPack: IRulePack = {
+  id: "runtime-boundaries",
+  description:
+    "Runtime boundary safety: open redirects, SSRF, prototype pollution, webhook verification, and upload limits.",
+  rules,
+  rulesConfig: {
+    "no-prototype-polluting-merge": "error",
+    "no-user-controlled-fetch-url": "error",
+    "no-user-controlled-redirect": "error",
+    "upload-must-set-limits": "warn",
+    "webhook-must-verify-signature-before-parse": "warn",
+  },
+};
+
+export default runtimeBoundariesPack;

package/src/rule-packs/runtime-boundaries/rules/no-prototype-polluting-merge.ts

@@ -0,0 +1,113 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { isExpression, isIdentifierNamed } from "../../boundary-utils";
+import { createRule } from "../../create-rule";
+
+export const RULE_NAME = "no-prototype-polluting-merge";
+
+type MessageIds = "prototypePollutingMerge";
+
+const REQUEST_FIELD_NAMES = new Set(["body", "query", "params"]);
+const REQUEST_OBJECT_NAMES = new Set(["req", "request", "ctx"]);
+
+function isRequestFieldExpression(node: TSESTree.Expression): boolean {
+  if (isIdentifierNamed(node, "body")) {
+    return true;
+  }
+
+  if (isIdentifierNamed(node, "query")) {
+    return true;
+  }
+
+  if (isIdentifierNamed(node, "params")) {
+    return true;
+  }
+
+  if (node.type !== AST_NODE_TYPES.MemberExpression || node.computed) {
+    return false;
+  }
+
+  const property = node.property;
+
+  if (
+    property.type !== AST_NODE_TYPES.Identifier ||
+    !REQUEST_FIELD_NAMES.has(property.name)
+  ) {
+    return false;
+  }
+
+  const object = node.object;
+
+  return (
+    object.type === AST_NODE_TYPES.Identifier &&
+    REQUEST_OBJECT_NAMES.has(object.name)
+  );
+}
+
+function isObjectAssignWithRequestFields(
+  node: TSESTree.CallExpression
+): boolean {
+  const callee = node.callee;
+
+  if (
+    callee.type !== AST_NODE_TYPES.MemberExpression ||
+    callee.computed ||
+    callee.object.type !== AST_NODE_TYPES.Identifier ||
+    callee.object.name !== "Object" ||
+    callee.property.type !== AST_NODE_TYPES.Identifier ||
+    callee.property.name !== "assign"
+  ) {
+    return false;
+  }
+
+  return node.arguments.some((arg, index) => {
+    if (index === 0 || !isExpression(arg)) {
+      return false;
+    }
+
+    return isRequestFieldExpression(arg);
+  });
+}
+
+function objectHasRequestFieldSpread(node: TSESTree.ObjectExpression): boolean {
+  return node.properties.some((prop) => {
+    if (prop.type !== AST_NODE_TYPES.SpreadElement) {
+      return false;
+    }
+
+    const argument = prop.argument;
+
+    return isExpression(argument) && isRequestFieldExpression(argument);
+  });
+}
+
+export const noPrototypePollutingMergeRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow merging request body/query/params into objects — enables prototype pollution.",
+    },
+    schema: [],
+    messages: {
+      prototypePollutingMerge:
+        "Do not merge `body`, `query`, or `params` into objects via `Object.assign` or spread — validate fields explicitly.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    return {
+      CallExpression(node: TSESTree.CallExpression) {
+        if (isObjectAssignWithRequestFields(node)) {
+          context.report({ node, messageId: "prototypePollutingMerge" });
+        }
+      },
+      ObjectExpression(node: TSESTree.ObjectExpression) {
+        if (objectHasRequestFieldSpread(node)) {
+          context.report({ node, messageId: "prototypePollutingMerge" });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/runtime-boundaries/rules/no-user-controlled-fetch-url.ts

@@ -0,0 +1,69 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { isExpression, isStringLiteral } from "../../boundary-utils";
+import { createRule } from "../../create-rule";
+
+export const RULE_NAME = "no-user-controlled-fetch-url";
+
+type MessageIds = "userControlledFetchUrl";
+
+const AXIOS_HTTP_METHODS = new Set(["get", "post"]);
+
+function isFetchCall(node: TSESTree.CallExpression): boolean {
+  const callee = node.callee;
+
+  return callee.type === AST_NODE_TYPES.Identifier && callee.name === "fetch";
+}
+
+function isAxiosHttpCall(node: TSESTree.CallExpression): boolean {
+  const callee = node.callee;
+
+  if (
+    callee.type !== AST_NODE_TYPES.MemberExpression ||
+    callee.computed ||
+    callee.property.type !== AST_NODE_TYPES.Identifier ||
+    !AXIOS_HTTP_METHODS.has(callee.property.name)
+  ) {
+    return false;
+  }
+
+  const object = callee.object;
+
+  return object.type === AST_NODE_TYPES.Identifier && object.name === "axios";
+}
+
+export const noUserControlledFetchUrlRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow fetch/axios requests to non-literal URLs — dynamic URLs enable SSRF.",
+    },
+    schema: [],
+    messages: {
+      userControlledFetchUrl:
+        "HTTP request URL must be a string literal — do not pass user-controlled values to `fetch()` or `axios`.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    return {
+      CallExpression(node: TSESTree.CallExpression) {
+        if (!isFetchCall(node) && !isAxiosHttpCall(node)) {
+          return;
+        }
+
+        const urlArg = node.arguments[0];
+
+        if (urlArg === undefined || !isExpression(urlArg)) {
+          return;
+        }
+
+        if (!isStringLiteral(urlArg)) {
+          context.report({ node, messageId: "userControlledFetchUrl" });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/runtime-boundaries/rules/no-user-controlled-redirect.ts

@@ -0,0 +1,79 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { isExpression, isStringLiteral } from "../../boundary-utils";
+import { createRule } from "../../create-rule";
+
+export const RULE_NAME = "no-user-controlled-redirect";
+
+type MessageIds = "userControlledRedirect";
+
+function isRedirectCall(node: TSESTree.CallExpression): boolean {
+  const callee = node.callee;
+
+  if (callee.type === AST_NODE_TYPES.Identifier && callee.name === "redirect") {
+    return true;
+  }
+
+  if (
+    callee.type !== AST_NODE_TYPES.MemberExpression ||
+    callee.computed ||
+    callee.property.type !== AST_NODE_TYPES.Identifier ||
+    callee.property.name !== "redirect"
+  ) {
+    return false;
+  }
+
+  const object = callee.object;
+
+  if (
+    object.type === AST_NODE_TYPES.Identifier &&
+    (object.name === "reply" || object.name === "NextResponse")
+  ) {
+    return true;
+  }
+
+  return (
+    object.type === AST_NODE_TYPES.MemberExpression &&
+    !object.computed &&
+    object.object.type === AST_NODE_TYPES.Identifier &&
+    object.object.name === "NextResponse" &&
+    object.property.type === AST_NODE_TYPES.Identifier &&
+    object.property.name === "redirect"
+  );
+}
+
+export const noUserControlledRedirectRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow redirects to non-literal URLs — user-controlled redirects enable open redirects.",
+    },
+    schema: [],
+    messages: {
+      userControlledRedirect:
+        "Redirect URL must be a string literal — do not pass user-controlled values to `redirect()`.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    return {
+      CallExpression(node: TSESTree.CallExpression) {
+        if (!isRedirectCall(node)) {
+          return;
+        }
+
+        const urlArg = node.arguments[0];
+
+        if (urlArg === undefined || !isExpression(urlArg)) {
+          return;
+        }
+
+        if (!isStringLiteral(urlArg)) {
+          context.report({ node, messageId: "userControlledRedirect" });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/runtime-boundaries/rules/upload-must-set-limits.ts

@@ -0,0 +1,126 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+
+export const RULE_NAME = "upload-must-set-limits";
+
+type MessageIds = "missingUploadLimits";
+
+const MULTIPART_CALLEE_NAMES = new Set(["file", "files", "saveRequestFiles"]);
+const LIMIT_PROPERTY_NAMES = new Set(["limits", "maxFileSize"]);
+
+function calleeEndsWithMultipartHandler(callee: TSESTree.Expression): boolean {
+  if (callee.type === AST_NODE_TYPES.Identifier && callee.name === "multer") {
+    return true;
+  }
+
+  if (callee.type !== AST_NODE_TYPES.MemberExpression) {
+    return false;
+  }
+
+  if (callee.computed || callee.property.type !== AST_NODE_TYPES.Identifier) {
+    return false;
+  }
+
+  return MULTIPART_CALLEE_NAMES.has(callee.property.name);
+}
+
+function objectHasLimitProperty(node: TSESTree.ObjectExpression): boolean {
+  return node.properties.some((prop) => {
+    if (prop.type !== AST_NODE_TYPES.Property || prop.computed) {
+      return false;
+    }
+
+    const key = prop.key;
+
+    if (key.type === AST_NODE_TYPES.Identifier) {
+      return LIMIT_PROPERTY_NAMES.has(key.name);
+    }
+
+    return (
+      key.type === AST_NODE_TYPES.Literal &&
+      typeof key.value === "string" &&
+      LIMIT_PROPERTY_NAMES.has(key.value)
+    );
+  });
+}
+
+function nodeReferencesLimitName(node: TSESTree.Node): boolean {
+  if (node.type === AST_NODE_TYPES.Identifier) {
+    return LIMIT_PROPERTY_NAMES.has(node.name);
+  }
+
+  if (node.type === AST_NODE_TYPES.Literal && typeof node.value === "string") {
+    return (
+      node.value.includes("multipart") ||
+      node.value.includes("@fastify/multipart")
+    );
+  }
+
+  if (node.type === AST_NODE_TYPES.ImportDeclaration) {
+    return node.source.value === "@fastify/multipart";
+  }
+
+  if (node.type === AST_NODE_TYPES.ObjectExpression) {
+    return objectHasLimitProperty(node);
+  }
+
+  return false;
+}
+
+export const uploadMustSetLimitsRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Multipart upload handlers should declare `limits` or `maxFileSize` to bound request size.",
+    },
+    schema: [],
+    messages: {
+      missingUploadLimits:
+        "Multipart upload handler is missing `limits` or `maxFileSize` configuration.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    let handlesMultipart = false;
+    let hasLimits = false;
+
+    return {
+      ImportDeclaration(node: TSESTree.ImportDeclaration) {
+        if (nodeReferencesLimitName(node)) {
+          handlesMultipart = true;
+        }
+      },
+      Literal(node: TSESTree.Literal) {
+        if (nodeReferencesLimitName(node)) {
+          handlesMultipart = true;
+        }
+      },
+      CallExpression(node: TSESTree.CallExpression) {
+        if (calleeEndsWithMultipartHandler(node.callee)) {
+          handlesMultipart = true;
+        }
+      },
+      ObjectExpression(node: TSESTree.ObjectExpression) {
+        if (objectHasLimitProperty(node)) {
+          hasLimits = true;
+        }
+      },
+      Identifier(node: TSESTree.Identifier) {
+        if (LIMIT_PROPERTY_NAMES.has(node.name)) {
+          hasLimits = true;
+        }
+      },
+      "Program:exit"() {
+        if (handlesMultipart && !hasLimits) {
+          context.report({
+            loc: { line: 1, column: 0 },
+            messageId: "missingUploadLimits",
+          });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/runtime-boundaries/rules/webhook-must-verify-signature-before-parse.ts

@@ -0,0 +1,87 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+
+export const RULE_NAME = "webhook-must-verify-signature-before-parse";
+
+type MessageIds = "jsonBeforeVerify";
+
+function isWebhookFile(filename: string): boolean {
+  const base = filename.split(/[\\/]/).pop() ?? "";
+
+  return base.toLowerCase().includes("webhook");
+}
+
+function isVerifyCall(node: TSESTree.CallExpression): boolean {
+  const callee = node.callee;
+
+  if (callee.type === AST_NODE_TYPES.Identifier) {
+    return callee.name === "verify" || callee.name.startsWith("verify");
+  }
+
+  if (
+    callee.type !== AST_NODE_TYPES.MemberExpression ||
+    callee.computed ||
+    callee.property.type !== AST_NODE_TYPES.Identifier
+  ) {
+    return false;
+  }
+
+  const name = callee.property.name;
+
+  return (
+    name === "constructEvent" || name === "verify" || name.startsWith("verify")
+  );
+}
+
+function isJsonCall(node: TSESTree.CallExpression): boolean {
+  const callee = node.callee;
+
+  return (
+    callee.type === AST_NODE_TYPES.MemberExpression &&
+    !callee.computed &&
+    callee.property.type === AST_NODE_TYPES.Identifier &&
+    callee.property.name === "json"
+  );
+}
+
+export const webhookMustVerifySignatureBeforeParseRule = createRule<
+  [],
+  MessageIds
+>({
+  name: RULE_NAME,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Webhook handlers must verify signatures before calling `.json()` on the request body.",
+    },
+    schema: [],
+    messages: {
+      jsonBeforeVerify:
+        "Verify the webhook signature (`verify*` or `constructEvent`) before parsing the body with `.json()`.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    if (!isWebhookFile(context.filename)) {
+      return {};
+    }
+
+    let verifySeen = false;
+
+    return {
+      CallExpression(node: TSESTree.CallExpression) {
+        if (isVerifyCall(node)) {
+          verifySeen = true;
+
+          return;
+        }
+
+        if (isJsonCall(node) && !verifySeen) {
+          context.report({ node, messageId: "jsonBeforeVerify" });
+        }
+      },
+    };
+  },
+});