@qodfy/core 0.2.3 → 0.2.4

package/dist/index.d.ts

@@ -1,5 +1,9 @@
 type IssueSeverity = "critical" | "warning" | "info";
 type IssueConfidence = "high" | "medium" | "low";
+type IssueEvidence = {
+    label: string;
+    detail?: string;
+};
 type IssueCategory = "security" | "environment" | "api" | "webhook" | "ai" | "maintainability" | "project";
 declare const validScanChecks: readonly ["project", "api", "environment", "ai", "webhook", "maintainability", "security"];
 type ScanCheck = typeof validScanChecks[number];
@@ -15,6 +19,7 @@ type Issue = {
     file?: string;
     suggestion?: string;
     fixPrompt?: string;
+    evidence?: IssueEvidence[];
 };
 type ScanReport = {
     projectPath: string;
@@ -36,4 +41,4 @@ type ScanOptions = {
 };
 declare function scanProject(input: string | ScanOptions): Promise<ScanReport>;
 
-export { type Issue, type IssueCategory, type IssueConfidence, type IssueSeverity, type ScanCheck, type ScanOptions, type ScanReport, recommendedScanChecks, scanProject, validScanChecks };
+export { type Issue, type IssueCategory, type IssueConfidence, type IssueEvidence, type IssueSeverity, type ScanCheck, type ScanOptions, type ScanReport, recommendedScanChecks, scanProject, validScanChecks };

package/dist/index.js

@@ -114,10 +114,11 @@ var issueIdPrefixes = {
   "environment-variable-missing-from-example": "environment-variable-missing-from-example",
   "security-client-side-secret": "security-client-side-secret",
   "security-hardcoded-secret": "security-hardcoded-secret",
-  "api-route-missing-auth": "security-api-auth",
+  "sensitive-api-route-missing-auth": "sensitive-api-route-missing-auth",
   "api-public-read-route": "api-public-read-route",
-  "api-public-form-abuse-protection": "api-public-form-protection",
-  "api-internal-route-protection": "api-internal-route-protection",
+  "public-form-missing-abuse-protection": "public-form-missing-abuse-protection",
+  "internal-route-missing-protection": "internal-route-missing-protection",
+  "api-mutation-route-review-auth": "api-mutation-route-review-auth",
   "ai-route-missing-rate-limit": "ai-route-rate-limit",
   "maintainability-large-file": "maintainability-large-file",
   "maintainability-large-file-skipped": "maintainability-large-file-skipped",
@@ -326,7 +327,7 @@ async function scanProject(input) {
     );
     if (runAiChecks && usesAI) {
       aiFiles++;
-      const hasRateLimit = content.includes("rateLimit") || content.includes("ratelimit") || content.includes("upstash") || content.includes("limiter");
+      const hasRateLimit = hasRateLimitSignal(content);
       if (apiRouteSet.has(file) && !hasRateLimit) {
         addIssue({
           ruleId: "ai-route-missing-rate-limit",
@@ -341,18 +342,23 @@ async function scanProject(input) {
         });
       }
     }
-    const webhookRouteInfo = (runWebhookChecks || runApiChecks) && apiRouteSet.has(file) ? getWebhookRouteInfo(relativeFile, content) : null;
-    if (webhookRouteInfo && !hasWebhookSignatureVerification(content, webhookRouteInfo.provider)) {
+    const apiRouteAnalysis = (runWebhookChecks || runApiChecks) && apiRouteSet.has(file) ? analyzeApiRoute({
+      file,
+      relativeFile,
+      content
+    }) : null;
+    if (runWebhookChecks && apiRouteAnalysis?.intent === "webhook" && !apiRouteAnalysis.hasWebhookVerification) {
       addIssue({
         ruleId: "webhook-missing-signature-verification",
         category: "webhook",
-        severity: webhookRouteInfo.confidence === "high" ? "critical" : "warning",
-        confidence: webhookRouteInfo.confidence === "high" ? "high" : "medium",
+        severity: apiRouteAnalysis.confidence === "high" ? "critical" : "warning",
+        confidence: apiRouteAnalysis.confidence,
         title: "Webhook route may be missing signature verification",
         message: "This webhook route appears to handle external events, but Qodfy could not find signature verification before the event is handled.",
         file: relativeFile,
-        suggestion: getWebhookSignatureSuggestion(webhookRouteInfo.provider),
-        fixPrompt: createWebhookSignatureFixPrompt(relativeFile)
+        suggestion: getWebhookSignatureSuggestion(apiRouteAnalysis.webhookProvider),
+        fixPrompt: createWebhookSignatureFixPrompt(relativeFile),
+        evidence: apiRouteAnalysis.evidence
       });
     }
     if (runSecurityChecks) {
@@ -375,13 +381,11 @@ async function scanProject(input) {
         });
       }
     }
-    if (runApiChecks && apiRouteSet.has(file)) {
+    if (runApiChecks && apiRouteAnalysis) {
       addApiRouteProtectionIssues({
         addIssue,
-        content,
         includeLowConfidence,
-        relativeFile,
-        webhookRouteInfo
+        analysis: apiRouteAnalysis
       });
     }
     const usedEnvVariables = runEnvironmentChecks || runSecurityChecks ? getUsedEnvVariables(content) : /* @__PURE__ */ new Set();
@@ -686,108 +690,123 @@ function isApiRoute(filePath) {
 }
 function addApiRouteProtectionIssues({
   addIssue,
-  content,
   includeLowConfidence,
-  relativeFile,
-  webhookRouteInfo
+  analysis
 }) {
-  const intent = classifyApiRouteIntent(relativeFile, content, webhookRouteInfo);
-  const hasAuth = hasAuthOrSessionCheck(content);
-  const methods = getHttpMethods(content);
-  if (intent === "webhook") {
+  if (analysis.intent === "webhook") {
     return;
   }
-  if (intent === "public-read") {
+  if (analysis.intent === "public-read") {
     if (includeLowConfidence) {
       addIssue({
         ruleId: "api-public-read-route",
         category: "api",
         severity: "info",
-        confidence: "low",
+        confidence: analysis.confidence,
         title: "Public read API route detected",
         message: "This route appears intentionally public. Authentication may not be required.",
-        file: relativeFile,
+        file: analysis.relativeFile,
         suggestion: "Verify that it only exposes public or published data and has appropriate validation, caching, and abuse protection.",
-        fixPrompt: createPublicReadRouteFixPrompt(relativeFile)
+        fixPrompt: createPublicReadRouteFixPrompt(analysis.relativeFile),
+        evidence: analysis.evidence
       });
     }
     return;
   }
-  if (intent === "public-form") {
-    if (!hasAbuseProtection(content)) {
+  if (analysis.intent === "public-form") {
+    if (!analysis.hasRateLimit && !analysis.hasValidation) {
       addIssue({
-        ruleId: "api-public-form-abuse-protection",
+        ruleId: "public-form-missing-abuse-protection",
         category: "api",
         severity: "warning",
-        confidence: "medium",
+        confidence: analysis.confidence,
         title: "Public form route may be missing abuse protection",
         message: "This route appears to accept public submissions. Consider adding rate limiting, validation, or spam protection.",
-        file: relativeFile,
+        file: analysis.relativeFile,
         suggestion: "Check for rate limiting, validation, captcha, Turnstile, reCAPTCHA, hCaptcha, or another spam protection pattern.",
-        fixPrompt: createPublicFormProtectionFixPrompt(relativeFile)
+        fixPrompt: createPublicFormProtectionFixPrompt(analysis.relativeFile),
+        evidence: analysis.evidence
       });
     }
     return;
   }
-  if (intent === "internal") {
-    if (!hasInternalRouteProtection(content)) {
+  if (analysis.intent === "internal") {
+    if (!analysis.hasAuth && !analysis.hasSecretProtection) {
       addIssue({
-        ruleId: "api-internal-route-protection",
-        category: "api",
+        ruleId: "internal-route-missing-protection",
+        category: "security",
         severity: "warning",
-        confidence: "high",
+        confidence: analysis.confidence,
         title: "Internal API route may be missing protection",
         message: "This route appears internal or operational. Confirm it is protected by auth, a secret token, or server-only access.",
-        file: relativeFile,
+        file: analysis.relativeFile,
         suggestion: "Use the project's existing auth pattern or a secret token check for operational routes such as cron, cleanup, or revalidation.",
-        fixPrompt: createInternalRouteProtectionFixPrompt(relativeFile)
+        fixPrompt: createInternalRouteProtectionFixPrompt(analysis.relativeFile),
+        evidence: analysis.evidence
       });
     }
     return;
   }
-  if (intent === "sensitive-mutation") {
-    if (!hasAuth) {
+  if (analysis.intent === "sensitive-mutation") {
+    if (!analysis.hasAuth) {
       addIssue({
-        ruleId: "api-route-missing-auth",
-        category: "api",
+        ruleId: "sensitive-api-route-missing-auth",
+        category: "security",
         severity: "warning",
-        confidence: "high",
+        confidence: analysis.confidence,
         title: "Sensitive API route may be missing authentication",
         message: "This route appears to handle user-specific or sensitive operations. Confirm it is protected before launch.",
-        file: relativeFile,
+        file: analysis.relativeFile,
         suggestion: "Review the existing project auth/session pattern and apply it if this route handles private data, uploads, payments, or account changes.",
-        fixPrompt: createApiAuthFixPrompt(relativeFile)
+        fixPrompt: createApiAuthFixPrompt(analysis.relativeFile),
+        evidence: analysis.evidence
       });
     }
     return;
   }
-  if (hasMutationMethod(methods) && !hasAuth) {
+  if (analysis.authExpected === "review" && !analysis.hasAuth) {
     addIssue({
-      ruleId: "api-route-missing-auth",
+      ruleId: "api-mutation-route-review-auth",
       category: "api",
       severity: "warning",
-      confidence: "medium",
+      confidence: analysis.confidence,
       title: "API mutation route should be reviewed for authentication",
-      message: "This route appears to handle a mutation, but Qodfy could not find an auth/session check.",
-      file: relativeFile,
+      message: "This route mutates data or handles requests, but Qodfy could not determine whether authentication is required.",
+      file: analysis.relativeFile,
       suggestion: "Confirm the route is intentionally public, or add the existing project auth/session check before handling private data.",
-      fixPrompt: createApiAuthFixPrompt(relativeFile)
+      fixPrompt: createApiAuthFixPrompt(analysis.relativeFile),
+      evidence: analysis.evidence
     });
   }
 }
-function classifyApiRouteIntent(relativeFile, content, webhookRouteInfo) {
+function analyzeApiRoute({
+  file,
+  relativeFile,
+  content
+}) {
   const normalizedFile = relativeFile.toLowerCase();
-  const methods = getHttpMethods(content);
-  if (webhookRouteInfo || routePathHasAny(normalizedFile, ["webhook", "webhooks", "callback"])) {
-    return "webhook";
-  }
-  if (routePathHasAny(normalizedFile, ["internal", "admin", "cron", "cleanup", "revalidate", "private"])) {
-    return "internal";
-  }
-  if (routePathHasAny(normalizedFile, ["contact", "subscribe", "newsletter", "lead", "inquiry"])) {
-    return "public-form";
+  const methods = getRouteHttpMethods(content);
+  const evidence = [];
+  const webhookRouteInfo = getWebhookRouteInfo(relativeFile, content);
+  const hasAuth = hasAuthOrSessionCheck(content);
+  const hasSecretProtection = hasSecretProtectionSignal(content);
+  const hasRateLimit = hasRateLimitSignal(content);
+  const hasValidation = hasValidationSignal(content);
+  const hasCacheHeaders = hasCacheHeaderSignal(content);
+  const hasMethodBlocking = hasMethodBlockingSignal(content);
+  const webhookProvider = webhookRouteInfo?.provider ?? "unknown";
+  const hasWebhookVerification = hasWebhookSignatureVerification(content, webhookProvider);
+  if (methods.length > 0) {
+    for (const method of methods) {
+      evidence.push({ label: "exports", detail: method });
+    }
+  } else {
+    evidence.push({ label: "no exported HTTP method detected" });
   }
-  if (routePathHasAny(normalizedFile, [
+  const webhookPathMatch = getRoutePathMatch(normalizedFile, ["webhook", "webhooks", "callback"]);
+  const internalPathMatch = getRoutePathMatch(normalizedFile, ["internal", "admin", "cron", "cleanup", "revalidate", "private"]);
+  const formPathMatch = getRoutePathMatch(normalizedFile, ["contact", "subscribe", "newsletter", "lead", "inquiry"]);
+  const sensitivePathMatch = getRoutePathMatch(normalizedFile, [
     "upload",
     "checkout",
     "order",
@@ -802,10 +821,8 @@ function classifyApiRouteIntent(relativeFile, content, webhookRouteInfo) {
     "cart",
     "profile",
     "settings"
-  ])) {
-    return "sensitive-mutation";
-  }
-  if (routePathHasAny(normalizedFile, [
+  ]);
+  const publicContentPathMatch = getRoutePathMatch(normalizedFile, [
     "blog",
     "blogs",
     "post",
@@ -818,56 +835,155 @@ function classifyApiRouteIntent(relativeFile, content, webhookRouteInfo) {
     "categories",
     "sitemap",
     "rss"
-  ])) {
-    return "public-read";
+  ]);
+  let intent = "unknown";
+  if (webhookRouteInfo || webhookPathMatch) {
+    intent = "webhook";
+    evidence.push({
+      label: webhookPathMatch ? "webhook path detected" : "webhook content detected",
+      detail: webhookPathMatch ?? webhookProvider
+    });
+  } else if (internalPathMatch) {
+    intent = "internal";
+    evidence.push({ label: "path contains", detail: internalPathMatch });
+  } else if (formPathMatch) {
+    intent = "public-form";
+    evidence.push({ label: "path contains", detail: formPathMatch });
+  } else if (hasMutationMethod(methods) && sensitivePathMatch) {
+    intent = "sensitive-mutation";
+    evidence.push({ label: "path contains", detail: sensitivePathMatch });
+  } else if (methods.includes("GET") && publicContentPathMatch && !sensitivePathMatch && !internalPathMatch) {
+    intent = "public-read";
+    evidence.push({ label: "public content route detected", detail: publicContentPathMatch });
   }
-  if (hasMutationMethod(methods)) {
-    return "unknown";
+  if (hasAuth) {
+    evidence.push({ label: "auth/session check detected" });
+  } else {
+    evidence.push({ label: "no auth/session check detected" });
   }
-  if (methods.size === 0 || isReadOnlyRoute(methods)) {
-    return "unknown";
+  if (hasSecretProtection) {
+    evidence.push({ label: "secret token check detected" });
   }
-  return "unknown";
+  if (hasRateLimit) {
+    evidence.push({ label: "rate limit detected" });
+  } else if (intent === "public-form") {
+    evidence.push({ label: "no rate limit detected" });
+  }
+  if (hasValidation) {
+    evidence.push({ label: "validation detected" });
+  } else if (intent === "public-form") {
+    evidence.push({ label: "no validation detected" });
+  }
+  if (hasCacheHeaders) {
+    evidence.push({ label: "cache/public-read safety signal detected" });
+  }
+  if (hasMethodBlocking) {
+    evidence.push({ label: "method blocking detected" });
+  }
+  if (intent === "webhook") {
+    if (hasWebhookVerification) {
+      evidence.push({ label: "webhook signature verification detected" });
+    } else {
+      evidence.push({ label: "no webhook signature verification detected" });
+    }
+  }
+  return {
+    file,
+    relativeFile,
+    methods,
+    intent,
+    authExpected: getAuthExpectation(intent, methods),
+    confidence: getApiRouteConfidence(intent, methods, webhookRouteInfo),
+    evidence,
+    hasAuth,
+    hasSecretProtection,
+    hasRateLimit,
+    hasValidation,
+    hasCacheHeaders,
+    hasMethodBlocking,
+    hasWebhookVerification,
+    webhookProvider
+  };
+}
+function getAuthExpectation(intent, methods) {
+  if (intent === "internal" || intent === "sensitive-mutation") {
+    return true;
+  }
+  if (intent === "unknown" && hasMutationMethod(methods)) {
+    return "review";
+  }
+  return false;
+}
+function getApiRouteConfidence(intent, methods, webhookRouteInfo) {
+  if (intent === "sensitive-mutation" || intent === "internal") {
+    return "high";
+  }
+  if (intent === "webhook") {
+    return webhookRouteInfo?.confidence === "high" ? "high" : "medium";
+  }
+  if (intent === "public-form" || intent === "unknown" && hasMutationMethod(methods)) {
+    return "medium";
+  }
+  return "low";
 }
-function routePathHasAny(normalizedFile, terms) {
-  return terms.some((term) => {
+function getRoutePathMatch(normalizedFile, terms) {
+  return terms.find((term) => {
     const escapedTerm = term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
     return new RegExp(`(^|[\\/._\\[\\]-])${escapedTerm}([\\/._\\[\\]-]|$)`).test(normalizedFile);
   });
 }
-function getHttpMethods(content) {
+function getExportedHttpMethods(content) {
   const methods = /* @__PURE__ */ new Set();
-  const exportedMethodPattern = /\bexport\s+(?:async\s+)?(?:function|const)\s+(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\b/g;
-  const requestMethodPattern = /\b(?:request|req)\.method\s*(?:={2,3}|!={1,2})\s*["'](GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)["']/g;
-  const methodCasePattern = /\bcase\s+["'](GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)["']/g;
-  for (const match of content.matchAll(exportedMethodPattern)) {
+  const functionExportPattern = /\bexport\s+(?:async\s+)?function\s+(GET|POST|PUT|PATCH|DELETE)\b/g;
+  const constExportPattern = /\bexport\s+const\s+(GET|POST|PUT|PATCH|DELETE)\b/g;
+  for (const match of content.matchAll(functionExportPattern)) {
+    methods.add(match[1]);
+  }
+  for (const match of content.matchAll(constExportPattern)) {
     methods.add(match[1]);
   }
+  return [...methods];
+}
+function getRouteHttpMethods(content) {
+  const methods = new Set(getExportedHttpMethods(content));
+  const requestMethodPattern = /\b(?:request|req)\.method\s*(?:={2,3}|!={1,2})\s*["'](GET|POST|PUT|PATCH|DELETE)["']/g;
+  const methodCasePattern = /\bcase\s+["'](GET|POST|PUT|PATCH|DELETE)["']/g;
   for (const match of content.matchAll(requestMethodPattern)) {
     methods.add(match[1]);
   }
   for (const match of content.matchAll(methodCasePattern)) {
     methods.add(match[1]);
   }
-  return methods;
+  return [...methods];
 }
 function hasMutationMethod(methods) {
-  return ["POST", "PUT", "PATCH", "DELETE"].some((method) => methods.has(method));
-}
-function isReadOnlyRoute(methods) {
-  return [...methods].every((method) => method === "GET" || method === "HEAD" || method === "OPTIONS");
+  return ["POST", "PUT", "PATCH", "DELETE"].some(
+    (method) => methods.includes(method)
+  );
 }
 function hasAuthOrSessionCheck(content) {
   const normalizedContent = content.toLowerCase();
   return normalizedContent.includes("auth(") || normalizedContent.includes("getserversession") || normalizedContent.includes("currentuser") || normalizedContent.includes("clerkclient") || normalizedContent.includes("session") || normalizedContent.includes("requireauth") || normalizedContent.includes("requireuser") || normalizedContent.includes("requireadmin") || normalizedContent.includes("verifysession") || normalizedContent.includes("getuser") || normalizedContent.includes("jwt") || normalizedContent.includes("authorization") || normalizedContent.includes("bearer") || normalizedContent.includes("cookies()") || normalizedContent.includes("request.cookies") || normalizedContent.includes("middleware");
 }
-function hasInternalRouteProtection(content) {
+function hasSecretProtectionSignal(content) {
+  const normalizedContent = content.toLowerCase();
+  return /\bprocess\.env\.[A-Za-z0-9_]*SECRET\b/.test(content) || /\bprocess\.env\[['"`][A-Za-z0-9_]*SECRET['"`]\]/.test(content) || normalizedContent.includes("cron_secret") || normalizedContent.includes("revalidate_secret") || normalizedContent.includes("authorization") || normalizedContent.includes("bearer") || normalizedContent.includes("token");
+}
+function hasRateLimitSignal(content) {
+  const normalizedContent = content.toLowerCase();
+  return normalizedContent.includes("ratelimit") || normalizedContent.includes("rate limit") || normalizedContent.includes("limiter") || normalizedContent.includes("upstash") || normalizedContent.includes("throttle");
+}
+function hasValidationSignal(content) {
+  const normalizedContent = content.toLowerCase();
+  return normalizedContent.includes("zod") || normalizedContent.includes("schema") || normalizedContent.includes("validate") || normalizedContent.includes("validation") || normalizedContent.includes("sanitize") || normalizedContent.includes("safeparse") || normalizedContent.includes("parse(") || normalizedContent.includes("slugregex") || normalizedContent.includes("isvalid") || normalizedContent.includes("captcha") || normalizedContent.includes("turnstile") || normalizedContent.includes("recaptcha") || normalizedContent.includes("hcaptcha");
+}
+function hasCacheHeaderSignal(content) {
   const normalizedContent = content.toLowerCase();
-  return hasAuthOrSessionCheck(content) || /\bprocess\.env\.[A-Za-z0-9_]*SECRET\b/.test(content) || /\bprocess\.env\[['"`][A-Za-z0-9_]*SECRET['"`]\]/.test(content) || normalizedContent.includes("cron_secret") || normalizedContent.includes("revalidate_secret") || normalizedContent.includes("authorization") || normalizedContent.includes("bearer") || normalizedContent.includes("token");
+  return normalizedContent.includes("cache-control") || normalizedContent.includes("s-maxage") || normalizedContent.includes("stale-while-revalidate") || normalizedContent.includes("public") || normalizedContent.includes("published") || normalizedContent.includes("status");
 }
-function hasAbuseProtection(content) {
+function hasMethodBlockingSignal(content) {
   const normalizedContent = content.toLowerCase();
-  return normalizedContent.includes("ratelimit") || normalizedContent.includes("rate limit") || normalizedContent.includes("limiter") || normalizedContent.includes("captcha") || normalizedContent.includes("turnstile") || normalizedContent.includes("recaptcha") || normalizedContent.includes("hcaptcha") || normalizedContent.includes("validation") || normalizedContent.includes("validate") || normalizedContent.includes("zod") || normalizedContent.includes("safeparse");
+  return normalizedContent.includes("method not allowed") || normalizedContent.includes("status: 405") || /\b405\b/.test(normalizedContent);
 }
 function getWebhookRouteInfo(relativeFile, content) {
   const normalizedFile = relativeFile.toLowerCase();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qodfy/core",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Scanner engine for Qodfy, an open-source launch readiness scanner for AI-built apps.",
   "keywords": [
     "qodfy",