@agjs/tsforge 0.1.0

package/src/rule-packs/oauth-security/rules/state-must-be-redis-backed.ts

@@ -0,0 +1,193 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+import type { JSONSchema4 } from "@typescript-eslint/utils/json-schema";
+
+import { createRule } from "../../create-rule";
+import {
+  DEFAULT_REDIS_METHODS,
+  DEFAULT_STATE_FILES,
+  matchesAnyGlobPattern,
+  matchRedisCall,
+  toPosixRelative,
+} from "../utils";
+
+export const RULE_NAME = "state-must-be-redis-backed";
+
+export interface StateMustBeRedisBackedOptions {
+  readonly stateFiles?: readonly string[];
+  readonly redisMethodNames?: readonly string[];
+}
+
+type RuleOptions = [StateMustBeRedisBackedOptions];
+type MessageIds = "missingRedisWrite" | "stateInCookie";
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    stateFiles: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+      minItems: 1,
+    },
+    redisMethodNames: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+      minItems: 1,
+    },
+  },
+};
+
+function isCookieLikeReceiver(name: string): boolean {
+  const lower = name.toLowerCase();
+
+  return lower.includes("cookie") || lower.includes("reply") || lower === "res";
+}
+
+function extractReceiverIdentifier(obj: TSESTree.Node): string | null {
+  let receiver = obj;
+
+  while (receiver.type === AST_NODE_TYPES.MemberExpression) {
+    receiver = receiver.object;
+  }
+
+  if (receiver.type !== AST_NODE_TYPES.Identifier) {
+    return null;
+  }
+
+  return receiver.name;
+}
+
+function isCookieSetMethod(name: string): boolean {
+  return name === "set" || name === "setCookie";
+}
+
+function argumentContainsState(arg: TSESTree.CallExpressionArgument): boolean {
+  if (
+    arg.type === AST_NODE_TYPES.Identifier &&
+    /^(oauth_?)?state$/i.test(arg.name)
+  ) {
+    return true;
+  }
+
+  if (arg.type === AST_NODE_TYPES.ObjectExpression) {
+    for (const prop of arg.properties) {
+      if (prop.type !== AST_NODE_TYPES.Property || prop.computed) {
+        continue;
+      }
+
+      if (
+        prop.value.type === AST_NODE_TYPES.Identifier &&
+        /^(oauth_?)?state$/i.test(prop.value.name)
+      ) {
+        return true;
+      }
+    }
+  }
+
+  if (
+    arg.type === AST_NODE_TYPES.Literal &&
+    typeof arg.value === "string" &&
+    /^(oauth_?)?state$/i.test(arg.value)
+  ) {
+    // `setCookie("state", value, ...)` — pattern with the state stuffed
+    // into a cookie of that name.
+    return true;
+  }
+
+  return false;
+}
+
+function isCookieSetWithState(node: TSESTree.CallExpression): boolean {
+  const callee = node.callee;
+
+  if (
+    callee.type !== AST_NODE_TYPES.MemberExpression ||
+    callee.computed ||
+    callee.property.type !== AST_NODE_TYPES.Identifier
+  ) {
+    return false;
+  }
+
+  if (!isCookieSetMethod(callee.property.name)) {
+    return false;
+  }
+
+  const receiver = extractReceiverIdentifier(callee.object);
+
+  if (receiver === null || !isCookieLikeReceiver(receiver)) {
+    return false;
+  }
+
+  // Look for a `state` or `oauth_state` reference among the args.
+  return node.arguments.some((arg) => argumentContainsState(arg));
+}
+
+export const stateMustBeRedisBackedRule = createRule<RuleOptions, MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "OAuth state must be persisted to Redis and not stuffed into a cookie. Cookie-backed state lets attackers replay forged state across sessions.",
+    },
+    schema: [optionSchema],
+    messages: {
+      missingRedisWrite:
+        "OAuth state file does not call any of `{{methods}}` on a Redis-shaped client — state must be persisted server-side.",
+      stateInCookie:
+        "Found a cookie write that appears to carry OAuth state — store state in Redis, not in a cookie.",
+    },
+  },
+  defaultOptions: [
+    {
+      stateFiles: [...DEFAULT_STATE_FILES],
+      redisMethodNames: [...DEFAULT_REDIS_METHODS],
+    },
+  ],
+  create(context, [options]) {
+    const stateFiles = options.stateFiles ?? DEFAULT_STATE_FILES;
+    const redisMethodNames = new Set(
+      options.redisMethodNames ?? DEFAULT_REDIS_METHODS
+    );
+
+    const relative = toPosixRelative(context.filename, context.cwd);
+
+    if (!matchesAnyGlobPattern(relative, stateFiles)) {
+      return {};
+    }
+
+    let redisWriteCount = 0;
+
+    return {
+      CallExpression(node) {
+        const match = matchRedisCall(node, redisMethodNames);
+
+        if (match !== null) {
+          redisWriteCount += 1;
+
+          return;
+        }
+
+        if (isCookieSetWithState(node)) {
+          context.report({
+            node,
+            messageId: "stateInCookie",
+          });
+        }
+      },
+      "Program:exit"(program) {
+        if (redisWriteCount === 0) {
+          context.report({
+            node: program,
+            messageId: "missingRedisWrite",
+            data: {
+              methods: [...redisMethodNames].join(", "),
+            },
+          });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/oauth-security/rules/state-ttl-bounded.ts

@@ -0,0 +1,219 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+import type { JSONSchema4 } from "@typescript-eslint/utils/json-schema";
+
+import { createRule } from "../../create-rule";
+import {
+  DEFAULT_REDIS_METHODS,
+  DEFAULT_STATE_FILES,
+  matchesAnyGlobPattern,
+  matchRedisCall,
+  toPosixRelative,
+} from "../utils";
+
+export const RULE_NAME = "state-ttl-bounded";
+
+export interface StateTtlBoundedOptions {
+  readonly stateFiles?: readonly string[];
+  readonly maxTtlSeconds?: number;
+}
+
+type RuleOptions = [StateTtlBoundedOptions];
+type MessageIds = "stateTtlTooLong";
+
+const DEFAULT_MAX_TTL = 600;
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    stateFiles: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+      minItems: 1,
+    },
+    maxTtlSeconds: { type: "number", minimum: 1 },
+  },
+};
+
+function getNumericLiteral(node: TSESTree.Node | undefined): number | null {
+  if (node?.type === AST_NODE_TYPES.Literal && typeof node.value === "number") {
+    return node.value;
+  }
+
+  return null;
+}
+
+function resolveConstant(
+  name: string,
+  constants: Map<string, number>
+): number | null {
+  return constants.get(name) ?? null;
+}
+
+export const stateTtlBoundedRule = createRule<RuleOptions, MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "OAuth state writes to Redis must use a short TTL — long-lived state widens the replay window.",
+    },
+    schema: [optionSchema],
+    messages: {
+      stateTtlTooLong:
+        "State TTL of {{found}}s exceeds maximum {{max}}s — long-lived state widens the replay window.",
+    },
+  },
+  defaultOptions: [
+    {
+      stateFiles: [...DEFAULT_STATE_FILES],
+      maxTtlSeconds: DEFAULT_MAX_TTL,
+    },
+  ],
+  create(context, [options]) {
+    const stateFiles = options.stateFiles ?? DEFAULT_STATE_FILES;
+    const maxTtlSeconds = options.maxTtlSeconds ?? DEFAULT_MAX_TTL;
+    const redisMethods = new Set(DEFAULT_REDIS_METHODS);
+
+    const relative = toPosixRelative(context.filename, context.cwd);
+
+    if (!matchesAnyGlobPattern(relative, stateFiles)) {
+      return {};
+    }
+
+    const constants = new Map<string, number>();
+
+    function checkTtlNode(
+      node: TSESTree.CallExpressionArgument,
+      reportNode: TSESTree.Node
+    ): void {
+      let value: number | null = getNumericLiteral(node);
+
+      if (value === null && node.type === AST_NODE_TYPES.Identifier) {
+        value = resolveConstant(node.name, constants);
+
+        if (value === null) {
+          return;
+        }
+      }
+
+      if (value === null) {
+        return;
+      }
+
+      if (value <= maxTtlSeconds) {
+        return;
+      }
+
+      context.report({
+        node: reportNode,
+        messageId: "stateTtlTooLong",
+        data: { found: String(value), max: String(maxTtlSeconds) },
+      });
+    }
+
+    function handleSetexCall(node: TSESTree.CallExpression): void {
+      const ttl = node.arguments[1];
+
+      if (ttl === undefined) {
+        return;
+      }
+
+      checkTtlNode(ttl, ttl);
+    }
+
+    function handleSetCallWithFlagArg(node: TSESTree.CallExpression): void {
+      // ioredis: set(key, value, "EX", ttl) — find "EX" then take next.
+      for (let i = 2; i < node.arguments.length - 1; i++) {
+        const flag = node.arguments[i];
+
+        if (
+          flag?.type === AST_NODE_TYPES.Literal &&
+          typeof flag.value === "string" &&
+          flag.value.toUpperCase() === "EX"
+        ) {
+          const ttl = node.arguments[i + 1];
+
+          if (ttl === undefined) {
+            return;
+          }
+
+          checkTtlNode(ttl, ttl);
+
+          return;
+        }
+      }
+    }
+
+    function handleSetCallWithObjectArg(node: TSESTree.CallExpression): void {
+      // node-redis v4: set(key, value, { EX: ttl })
+      const last = node.arguments[node.arguments.length - 1];
+
+      if (last?.type !== AST_NODE_TYPES.ObjectExpression) {
+        return;
+      }
+
+      for (const prop of last.properties) {
+        if (prop.type !== AST_NODE_TYPES.Property || prop.computed) {
+          continue;
+        }
+
+        const keyName =
+          prop.key.type === AST_NODE_TYPES.Identifier
+            ? prop.key.name
+            : prop.key.type === AST_NODE_TYPES.Literal &&
+                typeof prop.key.value === "string"
+              ? prop.key.value
+              : null;
+
+        if (keyName === "EX" || keyName === "PX") {
+          if (
+            prop.value.type === AST_NODE_TYPES.Literal ||
+            prop.value.type === AST_NODE_TYPES.Identifier
+          ) {
+            checkTtlNode(prop.value, prop.value);
+          }
+
+          return;
+        }
+      }
+    }
+
+    return {
+      VariableDeclarator(node) {
+        if (
+          node.id.type === AST_NODE_TYPES.Identifier &&
+          node.init !== null &&
+          node.init.type === AST_NODE_TYPES.Literal &&
+          typeof node.init.value === "number"
+        ) {
+          constants.set(node.id.name, node.init.value);
+        }
+      },
+      CallExpression(node) {
+        const match = matchRedisCall(node, redisMethods);
+
+        if (match === null) {
+          return;
+        }
+
+        const method = match.method;
+
+        if (method === "setex" || method === "setEx" || method === "SETEX") {
+          handleSetexCall(node);
+
+          return;
+        }
+
+        if (method === "set" || method === "SET") {
+          handleSetCallWithFlagArg(node);
+
+          if (node.arguments.length > 0) {
+            handleSetCallWithObjectArg(node);
+          }
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/oauth-security/utils.ts

@@ -0,0 +1,127 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+import {
+  matchesAnyGlobPattern,
+  toPosixRelative as sharedToPosixRelative,
+} from "../utils";
+
+export const DEFAULT_REDIS_METHODS: readonly string[] = [
+  "set",
+  "setex",
+  "setEx",
+  "SETEX",
+  "SET",
+];
+
+export const DEFAULT_OIDC_PROVIDERS: readonly string[] = [
+  "Google",
+  "Apple",
+  "Microsoft",
+  "MicrosoftEntraId",
+  "Auth0",
+  "Okta",
+  "Cognito",
+];
+
+export const DEFAULT_VERIFIER_FN_NAMES: readonly string[] = [
+  "generateCodeVerifier",
+];
+
+export const DEFAULT_STATE_FILES: readonly string[] = [
+  "**/oauth/state.ts",
+  "**/oauth/oauth.state.ts",
+];
+
+export const DEFAULT_PROVIDERS_GLOB = "**/oauth/providers/**";
+
+export { sharedToPosixRelative as toPosixRelative, matchesAnyGlobPattern };
+
+/**
+ * Returns true when the receiver of `<id>.<method>(...)` looks like a Redis
+ * client by name heuristic — identifier ends with `redis`, `client`, or
+ * exactly `redis`/`client` (case-insensitive).
+ */
+export function looksLikeRedisIdentifier(name: string): boolean {
+  const lower = name.toLowerCase();
+
+  return (
+    lower === "redis" ||
+    lower === "client" ||
+    lower.endsWith("redis") ||
+    lower.endsWith("client")
+  );
+}
+
+/**
+ * Returns true when an identifier name suggests a Redis-client accessor —
+ * `getClient`, `getRedis`, `getOAuthStateRedis`, etc.
+ */
+function looksLikeRedisAccessor(name: string): boolean {
+  const lower = name.toLowerCase();
+
+  if (!lower.startsWith("get")) {
+    return false;
+  }
+
+  return lower.endsWith("redis") || lower.endsWith("client");
+}
+
+/**
+ * Returns the matched method name when `node` is `<id>.<method>(...)` with
+ * a Redis-shaped receiver and a method in `methods`. The receiver may be
+ * either an identifier (`redis.setex(...)`) or a call to a Redis-shaped
+ * accessor (`getClient().setex(...)`).
+ */
+export function matchRedisCall(
+  node: TSESTree.CallExpression,
+  methods: ReadonlySet<string>
+): { method: string; node: TSESTree.CallExpression } | null {
+  const callee = node.callee;
+
+  if (callee.type !== AST_NODE_TYPES.MemberExpression || callee.computed) {
+    return null;
+  }
+
+  if (callee.property.type !== AST_NODE_TYPES.Identifier) {
+    return null;
+  }
+
+  if (!methods.has(callee.property.name)) {
+    return null;
+  }
+
+  // Walk through chained MemberExpressions to the leftmost segment.
+  let receiver: TSESTree.Node = callee.object;
+
+  while (receiver.type === AST_NODE_TYPES.MemberExpression) {
+    receiver = receiver.object;
+  }
+
+  if (
+    receiver.type === AST_NODE_TYPES.Identifier &&
+    looksLikeRedisIdentifier(receiver.name)
+  ) {
+    return { method: callee.property.name, node };
+  }
+
+  if (receiver.type === AST_NODE_TYPES.CallExpression) {
+    const inner = receiver.callee;
+
+    if (
+      inner.type === AST_NODE_TYPES.Identifier &&
+      looksLikeRedisAccessor(inner.name)
+    ) {
+      return { method: callee.property.name, node };
+    }
+
+    if (
+      inner.type === AST_NODE_TYPES.MemberExpression &&
+      !inner.computed &&
+      inner.property.type === AST_NODE_TYPES.Identifier &&
+      looksLikeRedisAccessor(inner.property.name)
+    ) {
+      return { method: callee.property.name, node };
+    }
+  }
+
+  return null;
+}

package/src/rule-packs/react-component-architecture/index.ts

@@ -0,0 +1,35 @@
+import type { TSESLint } from "@typescript-eslint/utils";
+
+import { componentFolderStructureRule } from "./rules/component-folder-structure";
+import { forwardrefDisplayNameRule } from "./rules/forwardref-display-name";
+import { indexMustReexportDefaultRule } from "./rules/index-must-reexport-default";
+import { maxHooksPerFileRule } from "./rules/max-hooks-per-file";
+import { noCrossFeatureImportsRule } from "./rules/no-cross-feature-imports";
+import { noInlineJsxFunctionsRule } from "./rules/no-inline-jsx-functions";
+import type { IRulePack } from "../rule-packs.types";
+
+const rules: Record<string, TSESLint.RuleModule<string, readonly unknown[]>> = {
+  "component-folder-structure": componentFolderStructureRule,
+  "forwardref-display-name": forwardrefDisplayNameRule,
+  "index-must-reexport-default": indexMustReexportDefaultRule,
+  "max-hooks-per-file": maxHooksPerFileRule,
+  "no-cross-feature-imports": noCrossFeatureImportsRule,
+  "no-inline-jsx-functions": noInlineJsxFunctionsRule,
+};
+
+export const reactComponentArchitecturePack: IRulePack = {
+  id: "react-component-architecture",
+  description:
+    "Component structure, composition, and file organization for React",
+  rules,
+  rulesConfig: {
+    "component-folder-structure": "error",
+    "forwardref-display-name": "error",
+    "index-must-reexport-default": "error",
+    "max-hooks-per-file": "warn",
+    "no-cross-feature-imports": "error",
+    "no-inline-jsx-functions": "warn",
+  },
+};
+
+export default reactComponentArchitecturePack;

package/src/rule-packs/react-component-architecture/rules/component-folder-structure.ts

@@ -0,0 +1,123 @@
+import { existsSync } from "fs";
+import { dirname, join } from "path";
+import type { JSONSchema4 } from "@typescript-eslint/utils/json-schema";
+
+import { createRule } from "../../create-rule";
+import { getComponentName, isComponentFile, isInShadcnUi } from "../utils";
+
+export const RULE_NAME = "component-folder-structure";
+
+export interface ComponentFolderStructureOptions {
+  readonly requiredSiblings?: readonly string[];
+  readonly ignorePaths?: readonly string[];
+}
+
+type RuleOptions = [ComponentFolderStructureOptions];
+type MessageIds = "missingSiblings";
+
+const DEFAULT_SIBLINGS = [
+  "<Name>.hooks.ts",
+  "<Name>.types.ts",
+  "<Name>.stories.tsx",
+  "<Name>.test.ts",
+  "index.ts",
+];
+
+const DEFAULT_IGNORE_PATHS = [
+  "src/components/ui/",
+  "tests/",
+  "e2e/",
+  ".storybook/",
+  "node_modules",
+];
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    requiredSiblings: {
+      type: "array",
+      items: { type: "string" },
+    },
+    ignorePaths: {
+      type: "array",
+      items: { type: "string" },
+    },
+  },
+};
+
+export const componentFolderStructureRule = createRule<RuleOptions, MessageIds>(
+  {
+    name: RULE_NAME,
+    meta: {
+      type: "problem",
+      docs: {
+        description:
+          "Enforce required sibling files in component folders (hooks, types, stories, test, index)",
+      },
+      schema: [optionSchema],
+      messages: {
+        missingSiblings:
+          "Component '{{name}}' is missing required siblings: {{missing}}",
+      },
+    },
+    defaultOptions: [
+      {
+        requiredSiblings: DEFAULT_SIBLINGS,
+        ignorePaths: DEFAULT_IGNORE_PATHS,
+      },
+    ],
+    create(context, [options]) {
+      const filename = context.filename;
+
+      if (!isComponentFile(filename)) {
+        return {};
+      }
+
+      const ignorePaths = options.ignorePaths ?? DEFAULT_IGNORE_PATHS;
+
+      if (ignorePaths.some((p) => filename.includes(p))) {
+        return {};
+      }
+
+      if (isInShadcnUi(filename)) {
+        return {};
+      }
+
+      const componentName = getComponentName(filename);
+
+      if (!componentName) {
+        return {};
+      }
+
+      return {
+        "Program:exit"(node) {
+          const dir = dirname(filename);
+          const requiredSiblings = options.requiredSiblings ?? DEFAULT_SIBLINGS;
+
+          const missing: string[] = [];
+
+          for (const sibling of requiredSiblings) {
+            const siblingPath = sibling.replace("<Name>", componentName);
+            const fullPath = join(dir, siblingPath);
+
+            if (!existsSync(fullPath)) {
+              missing.push(siblingPath);
+            }
+          }
+
+          if (missing.length > 0) {
+            context.report({
+              node,
+              messageId: "missingSiblings",
+              data: {
+                name: componentName,
+                missing: missing.join(", "),
+              },
+            });
+          }
+        },
+      };
+    },
+  }
+);