penthera 1.1.1 → 1.4.0

package/lib/fix/recipes/headers.js

@@ -0,0 +1,250 @@
+/**
+ * Recipe: security response headers (CSP starter, HSTS, X-Frame-Options and
+ * frame-ancestors, Referrer-Policy, X-Content-Type-Options) for Next.js,
+ * Express, Fastify and Hono. Guidance: remediation rules "header-csp" and
+ * "header-generic", and references/remediation.md#security-headers.
+ */
+import { auditSecurityHeaders } from "../../blackbox/headers.js";
+import {
+  detectFramework, hasDep, readText, walkCodeFiles, findEntryFile, findLine,
+  addImport, insertAfterLine, toDiff,
+} from "../util.js";
+
+// A starter CSP: it allows inline scripts and styles because most framework
+// apps (Next.js hydration in particular) break without them. The owner action
+// says to tighten it.
+const CSP = "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self' data:; connect-src 'self'; frame-ancestors 'none'; object-src 'none'; base-uri 'self'; form-action 'self'";
+
+export const SECURITY_HEADERS = [
+  ["Content-Security-Policy", CSP],
+  ["Strict-Transport-Security", "max-age=63072000; includeSubDomains"],
+  ["X-Frame-Options", "DENY"],
+  ["Referrer-Policy", "strict-origin-when-cross-origin"],
+  ["X-Content-Type-Options", "nosniff"],
+  ["Permissions-Policy", "camera=(), microphone=(), geolocation=()"],
+];
+
+// The headers this recipe is responsible for (Permissions-Policy is a bonus in
+// the literal variants, but helmet and secureHeaders don't set it by default).
+const COVERED = ["content-security-policy", "strict-transport-security", "x-frame-options", "referrer-policy", "x-content-type-options"];
+const HELMET_DEFAULTS = COVERED;
+const HONO_DEFAULTS = ["strict-transport-security", "x-frame-options", "referrer-policy", "x-content-type-options"];
+
+const NEXT_CONFIGS = ["next.config.js", "next.config.mjs", "next.config.ts", "next.config.cjs"];
+
+const OWNER_ACTIONS = [
+  "Tighten the starter Content-Security-Policy for your app: it allows inline scripts and styles. Test in staging (or ship it as Content-Security-Policy-Report-Only first) and move to nonces or hashes.",
+  "Only keep Strict-Transport-Security if the site is served over HTTPS everywhere; add `preload` once you are sure.",
+];
+
+const ANCHORS = {
+  express: /^(\s*)(?:const|let|var)\s+(\w+)\s*=\s*express\(\s*\)\s*;?\s*$/,
+  hono: /^(\s*)(?:const|let|var)\s+(\w+)\s*=\s*new\s+Hono(?:<[^>]*>)?\(\s*\)\s*;?\s*$/,
+};
+
+function fastifyAnchor(source) {
+  const factory = source.match(/import\s+(\w+)\s+from\s+['"]fastify['"]/)?.[1]
+    || source.match(/(?:const|let|var)\s+(\w+)\s*=\s*require\(\s*['"]fastify['"]\s*\)\s*;?/)?.[1];
+  if (factory) return new RegExp(`^(\\s*)(?:const|let|var)\\s+(\\w+)\\s*=\\s*(?:await\\s+)?${factory}\\([^()]*\\)\\s*;?\\s*$`);
+  return /^(\s*)(?:const|let|var)\s+(\w+)\s*=\s*require\(\s*['"]fastify['"]\s*\)\([^()]*\)\s*;?\s*$/;
+}
+
+function anchorFor(framework, source) {
+  return framework === "fastify" ? fastifyAnchor(source) : ANCHORS[framework];
+}
+
+function nextConfig(repoPath) {
+  for (const file of NEXT_CONFIGS) {
+    const source = readText(repoPath, file);
+    if (source != null) return { file, source };
+  }
+  return null;
+}
+
+/** Lower-case names of the security headers the repo's code visibly sets. */
+export function staticHeaders(repoPath, framework) {
+  const found = new Set();
+  const literal = /(?:key\s*:\s*|\.(?:setHeader|header|set|append)\(\s*)['"]([A-Za-z-]+)['"]/g;
+  const sources = [];
+  if (framework === "next") {
+    const cfg = nextConfig(repoPath);
+    if (cfg) sources.push(cfg.source);
+    for (const f of ["middleware.ts", "middleware.js", "src/middleware.ts", "src/middleware.js"]) {
+      const s = readText(repoPath, f);
+      if (s) sources.push(s);
+    }
+  } else {
+    for (const f of walkCodeFiles(repoPath)) {
+      const s = readText(repoPath, f);
+      if (s) sources.push(s);
+    }
+  }
+  for (const s of sources) {
+    for (const m of s.matchAll(literal)) found.add(m[1].toLowerCase());
+    const helmet = /['"]helmet['"]/.test(s) && /\bhelmet\s*\(/.test(s);
+    const fastifyHelmet = /['"]@fastify\/helmet['"]/.test(s) && /\.register\(/.test(s);
+    if (helmet || fastifyHelmet) HELMET_DEFAULTS.forEach((h) => found.add(h));
+    if (/\bsecureHeaders\s*\(/.test(s)) {
+      HONO_DEFAULTS.forEach((h) => found.add(h));
+      if (/contentSecurityPolicy\s*:/.test(s)) found.add("content-security-policy");
+    }
+  }
+  return found;
+}
+
+function missingHeaders(repoPath, framework) {
+  const present = staticHeaders(repoPath, framework);
+  return COVERED.filter((h) => !present.has(h));
+}
+
+function planNext(repoPath) {
+  const cfg = nextConfig(repoPath);
+  const headerLines = [
+    "const securityHeaders = [",
+    ...SECURITY_HEADERS.map(([k, v]) => `  { key: "${k}", value: ${JSON.stringify(v)} },`),
+    "];",
+    "",
+  ];
+  const headersFn = [
+    "  async headers() {",
+    '    return [{ source: "/:path*", headers: securityHeaders }];',
+    "  },",
+  ];
+  if (!cfg) {
+    const after = [
+      "// Security headers (added by penthera fix).",
+      ...headerLines,
+      "/** @type {import('next').NextConfig} */",
+      "const nextConfig = {",
+      ...headersFn,
+      "};",
+      "",
+      "export default nextConfig;",
+      "",
+    ].join("\n");
+    return toDiff([{ file: "next.config.mjs", before: null, after }]);
+  }
+  const { file, source } = cfg;
+  // An existing headers() would need merging; leave that to a human.
+  if (/\bheaders\s*\(/.test(source) || /\bsecurityHeaders\b/.test(source)) return null;
+
+  const lines = source.split("\n");
+  let idx = -1;
+  let empty = false;
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^(?:(?:const|let|var)\s+(\w+)(?:\s*:\s*[\w.]+)?\s*=|module\.exports\s*=|export\s+default)\s*\{\s*(\}\s*;?)?\s*$/);
+    if (!m) continue;
+    // A named config object must be the one that gets exported.
+    if (m[1] && !new RegExp(`(?:export\\s+default|module\\.exports\\s*=)\\s*${m[1]}\\s*;?\\s*$`, "m").test(source)) continue;
+    idx = i;
+    empty = Boolean(m[2]);
+    break;
+  }
+  if (idx < 0) return null;
+
+  const opening = lines[idx].replace(/\}\s*;?\s*$/, "").trimEnd();
+  const semicolon = /;\s*$/.test(lines[idx]);
+  const replaced = empty ? [opening, ...headersFn, `}${semicolon ? ";" : ""}`] : [lines[idx], ...headersFn];
+  lines.splice(idx, 1, ...replaced);
+  // Keep a JSDoc type comment (/** @type {import('next').NextConfig} */) attached to its object.
+  const at = idx > 0 && /^\s*\/\*\*.*\*\/\s*$/.test(lines[idx - 1]) ? idx - 1 : idx;
+  lines.splice(at, 0, "// Security headers (added by penthera fix).", ...headerLines);
+  return toDiff([{ file, before: source, after: lines.join("\n") }]);
+}
+
+function planServer(repoPath, framework) {
+  const probeAnchor = framework === "fastify" ? /['"]fastify['"]/ : ANCHORS[framework];
+  const entry = findEntryFile(repoPath, new RegExp(probeAnchor.source, "m"));
+  if (!entry) return null;
+  const { file, source } = entry;
+  const anchor = anchorFor(framework, source);
+  const idx = findLine(source, anchor);
+  if (idx < 0) return null;
+  const app = source.split("\n")[idx].match(anchor)[2];
+
+  let after;
+  if (framework === "express" && hasDep(repoPath, "helmet")) {
+    after = insertAfterLine(source, idx, [`${app}.use(helmet());`]);
+    after = addImport(after, { name: "helmet", module: "helmet" });
+  } else if (framework === "fastify" && hasDep(repoPath, "@fastify/helmet")) {
+    after = insertAfterLine(source, idx, [`${app}.register(fastifyHelmet);`]);
+    after = addImport(after, { name: "fastifyHelmet", module: "@fastify/helmet" });
+  } else if (framework === "hono") {
+    after = insertAfterLine(source, idx, [
+      `${app}.use(`,
+      '  "*",',
+      "  secureHeaders({",
+      "    contentSecurityPolicy: {",
+      `      defaultSrc: ["'self'"],`,
+      `      scriptSrc: ["'self'", "'unsafe-inline'"],`,
+      `      styleSrc: ["'self'", "'unsafe-inline'"],`,
+      `      imgSrc: ["'self'", "data:", "blob:"],`,
+      `      frameAncestors: ["'none'"],`,
+      `      objectSrc: ["'none'"],`,
+      `      baseUri: ["'self'"],`,
+      "    },",
+      '    xFrameOptions: "DENY",',
+      '    referrerPolicy: "strict-origin-when-cross-origin",',
+      "  }),",
+      ");",
+    ]);
+    after = addImport(after, { name: "secureHeaders", module: "hono/secure-headers", named: true });
+  } else if (framework === "express") {
+    after = insertAfterLine(source, idx, [
+      "",
+      "// Security headers (added by penthera fix). Tighten the starter CSP for your app.",
+      `${app}.use((req, res, next) => {`,
+      ...SECURITY_HEADERS.map(([k, v]) => `  res.setHeader("${k}", ${JSON.stringify(v)});`),
+      "  next();",
+      "});",
+    ]);
+  } else if (framework === "fastify") {
+    after = insertAfterLine(source, idx, [
+      "",
+      "// Security headers (added by penthera fix). Tighten the starter CSP for your app.",
+      `${app}.addHook("onSend", async (request, reply, payload) => {`,
+      ...SECURITY_HEADERS.map(([k, v]) => `  reply.header("${k}", ${JSON.stringify(v)});`),
+      "  return payload;",
+      "});",
+    ]);
+  } else {
+    return null;
+  }
+  return toDiff([{ file, before: source, after }]);
+}
+
+export default {
+  id: "security-headers",
+  title: "Add security response headers",
+  matches(finding) {
+    const t = finding.title || "";
+    if (/permissions-policy/i.test(t)) return false;
+    return /content-security-policy|x-frame-options|frame-ancestors|x-content-type-options|referrer-policy|strict-transport-security|hsts/i.test(t);
+  },
+  detect(repoPath) {
+    return detectFramework(repoPath);
+  },
+  plan(repoPath, _finding, framework) {
+    if (!["next", "express", "fastify", "hono"].includes(framework)) return null;
+    if (missingHeaders(repoPath, framework).length === 0) return null; // already fixed
+    const change = framework === "next" ? planNext(repoPath) : planServer(repoPath, framework);
+    if (!change) return null;
+    return { ...change, ownerActions: OWNER_ACTIONS, confidence: "medium" };
+  },
+  /** Static stand-in for the header audit: which covered headers the code never sets. */
+  probe(repoPath) {
+    const framework = detectFramework(repoPath);
+    if (!["next", "express", "fastify", "hono"].includes(framework)) return [];
+    const present = staticHeaders(repoPath, framework);
+    const headers = Object.fromEntries([...present].map((h) => [h, "set"]));
+    const where = framework === "next"
+      ? nextConfig(repoPath)?.file || "next.config.mjs"
+      : findEntryFile(repoPath, framework === "fastify" ? /['"]fastify['"]/ : new RegExp(ANCHORS[framework].source, "m"))?.file || null;
+    const findings = auditSecurityHeaders(headers, "https://localhost", { local: true })
+      .filter((f) => !/permissions-policy/i.test(f.title));
+    if (!present.has("strict-transport-security")) {
+      findings.push({ severity: "low", title: "Missing Strict-Transport-Security", description: "No HSTS header is set in code.", category: "headers" });
+    }
+    return findings.map((f) => ({ ...f, url: where, source: "fix-probe:headers" }));
+  },
+};

package/lib/fix/recipes/rate-limit.js

@@ -0,0 +1,211 @@
+/**
+ * Recipe: a rate-limit stub on login/auth routes. Express (express-rate-limit
+ * when installed, otherwise an in-memory limiter), Fastify (preHandler), Hono
+ * (middleware) and Next.js App Router route handlers. Guidance: remediation
+ * rules "rate-limiting" and "auth", references/remediation.md#rate-limiting.
+ *
+ * The stub is per-process and in memory: it stops naive brute force against a
+ * single instance, and the owner action says to move to a shared store.
+ */
+import { detectFramework as detectSourceFramework } from "../../whitebox/frameworks.js";
+import { detectFramework, hasDep, readText, walkCodeFiles, insertAfterImports, addImport, isTypeScript, toDiff } from "../util.js";
+
+const AUTH_SEGMENT = /^(?:login|log-in|logon|signin|sign-in|signup|sign-up|register|auth|session|sessions|forgot-password|reset-password|password-reset|otp|mfa|2fa|verify-otp|magic-link)$/i;
+const ROUTE_LINE = /^(\s*)(\w+)\.(post|put|all)\(\s*(['"`])([^'"`]+)\4\s*,\s*(.*)$/;
+const LIMITED = /rateLimit|limiter|throttle/i;
+
+export function isAuthPath(path) {
+  if (!path || /\[\.\.\./.test(path)) return false; // catch-alls such as NextAuth's [...nextauth]
+  return path.split("/").filter(Boolean).some((seg) => AUTH_SEGMENT.test(seg));
+}
+
+function nextRoutePath(file) {
+  const m = file.match(/(?:^|\/)app\/(.*\/)?route\.(?:js|ts|mjs)$/);
+  if (!m) return null;
+  const dirs = (m[1] || "").split("/").filter((d) => d && !/^\(.*\)$/.test(d));
+  return "/" + dirs.join("/");
+}
+
+/** Unprotected auth routes in one file: [{ method, path, line, framework }]. */
+function authRoutes(file, source, repoFramework) {
+  const routes = [];
+  const nextPath = nextRoutePath(file);
+  if (nextPath) {
+    if (!isAuthPath(nextPath) || LIMITED.test(source)) return routes;
+    const lines = source.split("\n");
+    const line = lines.findIndex((l) => /^export\s+(?:async\s+)?function\s+POST\s*\(/.test(l));
+    if (line >= 0) routes.push({ method: "POST", path: nextPath, line, framework: "next" });
+    return routes;
+  }
+  const fileFw = detectSourceFramework(source);
+  const framework = fileFw !== "node" ? fileFw : repoFramework;
+  if (!["express", "fastify", "hono"].includes(framework)) return routes;
+  if (/\.(?:use|register)\([^)\n]*(?:rateLimit|limiter|throttle|rate-limit)/i.test(source)) return routes; // a global limiter
+  source.split("\n").forEach((l, line) => {
+    const m = l.match(ROUTE_LINE);
+    if (!m || !isAuthPath(m[5]) || LIMITED.test(m[6])) return;
+    routes.push({ method: m[3].toUpperCase(), path: m[5], line, framework });
+  });
+  return routes;
+}
+
+function coreLines(ts) {
+  return [
+    "// Login rate limit (added by penthera fix): at most LOGIN_MAX_ATTEMPTS per client",
+    "// per window, kept in memory. Use a shared store (Redis, your edge or WAF) when",
+    "// you run more than one instance.",
+    "const LOGIN_WINDOW_MS = 15 * 60 * 1000;",
+    "const LOGIN_MAX_ATTEMPTS = 10;",
+    `const loginAttempts = new Map${ts ? "<string, { count: number; reset: number }>" : ""}();`,
+    `function loginLimitExceeded(key${ts ? ": string" : ""})${ts ? ": boolean" : ""} {`,
+    "  const now = Date.now();",
+    "  if (loginAttempts.size > 10000) {",
+    "    for (const [k, v] of loginAttempts) if (now > v.reset) loginAttempts.delete(k);",
+    "  }",
+    "  const entry = loginAttempts.get(key);",
+    "  if (!entry || now > entry.reset) {",
+    "    loginAttempts.set(key, { count: 1, reset: now + LOGIN_WINDOW_MS });",
+    "    return false;",
+    "  }",
+    "  entry.count += 1;",
+    "  return entry.count > LOGIN_MAX_ATTEMPTS;",
+    "}",
+  ];
+}
+
+const TOO_MANY = '{ error: "Too many attempts, try again later" }';
+
+function wrapperLines(framework, ts) {
+  const any = ts ? ": any" : "";
+  if (framework === "express") {
+    return [
+      `function rateLimitLogin(req${any}, res${any}, next${any}) {`,
+      `  if (loginLimitExceeded(req.ip || "unknown")) return res.status(429).json(${TOO_MANY});`,
+      "  next();",
+      "}",
+    ];
+  }
+  if (framework === "fastify") {
+    return [
+      `async function rateLimitLogin(request${any}, reply${any}) {`,
+      `  if (loginLimitExceeded(request.ip)) return reply.code(429).send(${TOO_MANY});`,
+      "}",
+    ];
+  }
+  if (framework === "hono") {
+    return [
+      `async function rateLimitLogin(c${any}, next${any}) {`,
+      '  const ip = c.req.header("x-forwarded-for")?.split(",")[0].trim() || "unknown";',
+      `  if (loginLimitExceeded(ip)) return c.json(${TOO_MANY}, 429);`,
+      "  await next();",
+      "}",
+    ];
+  }
+  return [
+    `function rateLimitLogin(request${ts ? ": Request" : ""})${ts ? ": Response | null" : ""} {`,
+    '  const ip = request.headers.get("x-forwarded-for")?.split(",")[0].trim() || "unknown";',
+    "  if (!loginLimitExceeded(ip)) return null;",
+    `  return Response.json(${TOO_MANY}, { status: 429 });`,
+    "}",
+  ];
+}
+
+function fixFile(repoPath, file, source, routes) {
+  const lines = source.split("\n");
+  const framework = routes[0].framework;
+  const useExpressRateLimit = framework === "express" && hasDep(repoPath, "express-rate-limit");
+  for (const r of [...routes].reverse()) {
+    const l = lines[r.line];
+    if (framework === "next") {
+      const m = l.match(/^export\s+(?:async\s+)?function\s+POST\s*\(\s*(\w+)/);
+      if (!m || !/\{\s*$/.test(l)) return null;
+      lines.splice(r.line + 1, 0, `  const limited = rateLimitLogin(${m[1]});`, "  if (limited) return limited;");
+      continue;
+    }
+    const m = l.match(ROUTE_LINE);
+    if (framework === "fastify") {
+      if (!m[6] || /^\{/.test(m[6])) return null; // options object (or unseen next line): merge by hand
+      lines[r.line] = l.slice(0, l.length - m[6].length) + `{ preHandler: rateLimitLogin }, ${m[6]}`;
+    } else {
+      lines[r.line] = l.slice(0, l.length - m[6].length) + `rateLimitLogin, ${m[6]}`;
+    }
+  }
+  let after = lines.join("\n");
+  if (!/\brateLimitLogin\s*=|function\s+rateLimitLogin\b/.test(source)) {
+    const ts = isTypeScript(file);
+    if (useExpressRateLimit) {
+      after = insertAfterImports(after, [
+        "// Login rate limit (added by penthera fix): 10 attempts per client per 15 minutes.",
+        'const rateLimitLogin = rateLimit({ windowMs: 15 * 60 * 1000, limit: 10, standardHeaders: "draft-7", legacyHeaders: false });',
+      ]);
+      after = addImport(after, { name: "rateLimit", module: "express-rate-limit", named: true });
+    } else {
+      after = insertAfterImports(after, [...coreLines(ts), "", ...wrapperLines(framework, ts)]);
+    }
+  }
+  return { file, before: source, after };
+}
+
+function routeFiles(repoPath) {
+  const framework = detectFramework(repoPath);
+  return walkCodeFiles(repoPath)
+    .map((file) => {
+      const source = readText(repoPath, file);
+      return { file, source, routes: source ? authRoutes(file, source, framework) : [] };
+    })
+    .filter((f) => f.routes.length > 0);
+}
+
+function routeOf(finding) {
+  return finding.route || (finding.title || "").match(/(?:rate limiting|rate limit)[^/]*?(?:(?:POST|PUT|ALL)\s+)?(\/\S*)/i)?.[1] || finding.url || "";
+}
+
+export default {
+  id: "auth-rate-limit",
+  title: "Rate-limit login and auth routes",
+  matches(finding) {
+    const isRate = finding.category === "rate-limiting" || /rate limit/i.test(finding.title || "");
+    if (!isRate) return false;
+    const route = routeOf(finding);
+    try {
+      return isAuthPath(route.startsWith("http") ? new URL(route).pathname : route);
+    } catch {
+      return false;
+    }
+  },
+  detect(repoPath) {
+    const fw = detectFramework(repoPath);
+    return ["next", "express", "fastify", "hono"].includes(fw) ? fw : null;
+  },
+  plan(repoPath, finding) {
+    let route = routeOf(finding);
+    try {
+      if (route.startsWith("http")) route = new URL(route).pathname;
+    } catch { /* keep as-is */ }
+    const target = routeFiles(repoPath).find((f) => f.routes.some((r) => r.path === route));
+    if (!target) return null;
+    const change = toDiff([fixFile(repoPath, target.file, target.source, target.routes)]);
+    if (!change) return null;
+    return {
+      ...change,
+      ownerActions: [
+        "The limiter is in memory and per process. Move it to a shared store (Redis, your platform's limiter, or a WAF rule) before you run more than one instance.",
+        "Make sure the client IP is the real one: set Express `trust proxy` behind a proxy, and only trust X-Forwarded-For from your own edge. Consider also limiting per account.",
+      ],
+      confidence: "medium",
+    };
+  },
+  probe(repoPath) {
+    return routeFiles(repoPath).flatMap(({ file, routes }) =>
+      routes.map((r) => ({
+        severity: "medium",
+        title: `Login route without rate limiting: ${r.method} ${r.path}`,
+        description: `Defined in ${file}:${r.line + 1}`,
+        url: file,
+        route: r.path,
+        category: "rate-limiting",
+        source: "fix-probe:rate-limit",
+      })),
+    );
+  },
+};

package/lib/fix/recipes/secrets.js

@@ -0,0 +1,110 @@
+/**
+ * Recipe: move a hardcoded secret out of JS/TS source into an environment
+ * variable and list that variable in .env.example. Guidance: remediation rule
+ * "secrets", references/remediation.md#hardcoded-secrets.
+ *
+ * The secret is already burned: a diff can take it out of the code, but only
+ * the owner can rotate it, so "rotate this secret" is always an owner action.
+ * The plan's diff contains the old value on its "-" line; plans carry it in
+ * `redactions` so anything that prints or stores a plan can mask it.
+ */
+import { findSecretsInText } from "../../whitebox/secrets.js";
+import { readText, walkCodeFiles, envExampleChange, toDiff, toEnvName } from "../util.js";
+
+const JS_FILE = /\.(js|ts|mjs|cjs|jsx|tsx)$/;
+
+// Env var names for provider keys that are not inside a named assignment.
+const PROVIDER_ENV = [
+  [/Anthropic/i, "ANTHROPIC_API_KEY"],
+  [/OpenRouter/i, "OPENROUTER_API_KEY"],
+  [/OpenAI/i, "OPENAI_API_KEY"],
+  [/Google/i, "GOOGLE_API_KEY"],
+  [/Groq/i, "GROQ_API_KEY"],
+  [/Hugging Face/i, "HF_TOKEN"],
+  [/Replicate/i, "REPLICATE_API_TOKEN"],
+  [/xAI/i, "XAI_API_KEY"],
+  [/Perplexity/i, "PERPLEXITY_API_KEY"],
+  [/LangSmith/i, "LANGSMITH_API_KEY"],
+  [/Pinecone/i, "PINECONE_API_KEY"],
+  [/Stripe/i, "STRIPE_SECRET_KEY"],
+  [/AWS/i, "AWS_ACCESS_KEY_ID"],
+  [/GitHub/i, "GITHUB_TOKEN"],
+];
+
+/**
+ * Locate the string literal holding a secret on one line.
+ * Returns { start, end, value, envName } (offsets within the line) or null.
+ */
+function locate(line, hit) {
+  const at = line.indexOf(hit.match);
+  if (at < 0) return null;
+  // Assignment rules match `key = "value"`; provider rules match the raw key.
+  const assigned = hit.match.match(/^([\w$-]+)\s*[:=]\s*(['"])([^'"]*)\2$/);
+  const value = assigned ? assigned[3] : hit.match;
+  const valueAt = assigned ? at + hit.match.lastIndexOf(value) : at;
+  const quote = line[valueAt - 1];
+  if (!["'", '"', "`"].includes(quote) || line[valueAt + value.length] !== quote) return null; // not a whole literal
+  if (quote === "`" && value.includes("${")) return null;
+  // Name: the key the literal is assigned to, else the provider's usual name.
+  const before = line.slice(0, valueAt - 1);
+  const key = before.match(/([A-Za-z_$][\w$]*)['"]?\s*[:=]\s*$/)?.[1];
+  const envName = (key && !/^(?:key|value|token|secret)$/i.test(key) && toEnvName(key))
+    || PROVIDER_ENV.find(([re]) => re.test(hit.name))?.[1]
+    || (key && toEnvName(key))
+    || "SECRET_VALUE";
+  return { start: valueAt - 1, end: valueAt + value.length + 1, value, envName };
+}
+
+function findSecret(source, title) {
+  const lines = source.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    for (const hit of findSecretsInText(lines[i])) {
+      if (title && `${hit.name} in source` !== title) continue;
+      const loc = locate(lines[i], hit);
+      if (loc) return { line: i, ...loc, name: hit.name };
+    }
+  }
+  return null;
+}
+
+export default {
+  id: "secret-to-env",
+  title: "Move a hardcoded secret to an environment variable",
+  matches(finding) {
+    return finding.category === "secrets";
+  },
+  detect() {
+    return "node";
+  },
+  plan(repoPath, finding) {
+    const file = finding.url;
+    if (!file || !JS_FILE.test(file) || !walkCodeFiles(repoPath).includes(file)) return null;
+    const source = readText(repoPath, file);
+    if (!source) return null;
+    const hit = findSecret(source, finding.title);
+    if (!hit) return null;
+
+    const lines = source.split("\n");
+    const l = lines[hit.line];
+    // TypeScript types process.env values as string | undefined; the owner action says to set it.
+    const ref = `process.env.${hit.envName}${/\.tsx?$/.test(file) ? " as string" : ""}`;
+    lines[hit.line] = l.slice(0, hit.start) + ref + l.slice(hit.end);
+    const change = toDiff([
+      { file, before: source, after: lines.join("\n") },
+      envExampleChange(repoPath, hit.envName, "", `${hit.name}: set the real value in .env or your secret manager, never in code`),
+    ]);
+    if (!change) return null;
+
+    const ownerActions = [
+      `Rotate this secret at the provider now and treat the old value as compromised. A recipe can never rotate it for you.`,
+      `Set ${hit.envName} in your local .env and in every deployment environment before deploying this change.`,
+      "If the old value was ever committed or pushed, purge it from git history (git filter-repo or BFG) after rotating.",
+    ];
+    if (/^(?:NEXT_PUBLIC_|VITE_|PUBLIC_|REACT_APP_)/.test(hit.envName) || /^\s*['"]use client['"]/.test(source)) {
+      ownerActions.push("This code runs in the browser, so an env var is still shipped to every visitor. Move the call that needs the secret to a server route.");
+    }
+    const ignore = readText(repoPath, ".gitignore");
+    if (!ignore || !/^\.env\b/m.test(ignore)) ownerActions.push("Add .env to .gitignore so the real value is never committed.");
+    return { ...change, ownerActions, confidence: "high", redactions: [hit.value] };
+  },
+};