ai-saas-guard 0.1.1

package/dist/index.js

@@ -0,0 +1,7 @@
+export { scanRepository } from "./commands/scan.js";
+export { checkStripe } from "./commands/checkStripe.js";
+export { checkSupabase } from "./commands/checkSupabase.js";
+export { checkMcp } from "./commands/checkMcp.js";
+export { classifyPrRisk } from "./commands/prRisk.js";
+export { createScanContext } from "./context.js";
+export { getRuleMetadata, RULE_CATALOG } from "./rules/catalog.js";

package/dist/report/findings.d.ts

@@ -0,0 +1,6 @@
+import type { BaseReport, CommandName, Finding, Summary } from "../types.js";
+export declare function summarizeFindings(findings: Finding[]): Summary;
+export declare function createReport<T extends BaseReport>(command: CommandName, rootDir: string, findings: Finding[], extra: Omit<T, keyof BaseReport | "command">): T;
+export declare function sortFindings(findings: Finding[]): Finding[];
+export declare function finding(input: Finding): Finding;
+export declare function uniqueFindings(findings: Finding[]): Finding[];

package/dist/report/findings.js

@@ -0,0 +1,49 @@
+const severities = ["critical", "high", "medium", "low", "info"];
+export function summarizeFindings(findings) {
+    const summary = {
+        critical: 0,
+        high: 0,
+        medium: 0,
+        low: 0,
+        info: 0,
+        total: findings.length
+    };
+    for (const finding of findings) {
+        summary[finding.severity] += 1;
+    }
+    return summary;
+}
+export function createReport(command, rootDir, findings, extra) {
+    return {
+        command,
+        rootDir,
+        generatedAt: new Date().toISOString(),
+        findings: sortFindings(findings),
+        summary: summarizeFindings(findings),
+        ...extra
+    };
+}
+export function sortFindings(findings) {
+    return [...findings].sort((a, b) => {
+        const severityDelta = severities.indexOf(a.severity) - severities.indexOf(b.severity);
+        if (severityDelta !== 0)
+            return severityDelta;
+        return a.ruleId.localeCompare(b.ruleId);
+    });
+}
+export function finding(input) {
+    return input;
+}
+export function uniqueFindings(findings) {
+    const seen = new Set();
+    const result = [];
+    for (const item of findings) {
+        const firstEvidence = item.evidence[0];
+        const key = `${item.ruleId}:${firstEvidence?.file ?? ""}:${firstEvidence?.line ?? ""}:${item.title}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(item);
+    }
+    return result;
+}

package/dist/report/json.d.ts

@@ -0,0 +1,2 @@
+import type { BaseReport } from "../types.js";
+export declare function formatJsonReport(report: BaseReport): string;

package/dist/report/json.js

@@ -0,0 +1,3 @@
+export function formatJsonReport(report) {
+    return `${JSON.stringify(report, null, 2)}\n`;
+}

package/dist/report/sarif.d.ts

@@ -0,0 +1,2 @@
+import type { BaseReport } from "../types.js";
+export declare function formatSarifReport(report: BaseReport): string;

package/dist/report/sarif.js

@@ -0,0 +1,62 @@
+import { getRuleMetadata } from "../rules/catalog.js";
+export function formatSarifReport(report) {
+    const rules = new Map();
+    for (const finding of report.findings) {
+        if (rules.has(finding.ruleId))
+            continue;
+        const metadata = getRuleMetadata(finding.ruleId);
+        rules.set(finding.ruleId, {
+            id: finding.ruleId,
+            name: finding.ruleId,
+            shortDescription: { text: metadata?.title ?? finding.title },
+            fullDescription: { text: metadata?.why ?? finding.why },
+            help: { text: `${finding.suggestedVerification}\n\nFix direction: ${finding.suggestedFix}` },
+            defaultConfiguration: { level: sarifLevel(finding) }
+        });
+    }
+    return `${JSON.stringify({
+        version: "2.1.0",
+        $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: "ai-saas-guard",
+                        informationUri: "https://github.com/zr9959/ai-saas-guard",
+                        rules: [...rules.values()]
+                    }
+                },
+                results: report.findings.map((finding) => sarifResult(finding))
+            }
+        ]
+    }, null, 2)}\n`;
+}
+function sarifResult(finding) {
+    const evidence = finding.evidence[0] ?? { file: "." };
+    return {
+        ruleId: finding.ruleId,
+        level: sarifLevel(finding),
+        message: {
+            text: `${finding.title}\n\nWhy: ${finding.why}\n\nVerify: ${finding.suggestedVerification}\n\nFix direction: ${finding.suggestedFix}`
+        },
+        locations: [
+            {
+                physicalLocation: {
+                    artifactLocation: {
+                        uri: evidence.file
+                    },
+                    region: {
+                        startLine: evidence.line ?? 1
+                    }
+                }
+            }
+        ]
+    };
+}
+function sarifLevel(finding) {
+    if (finding.severity === "critical" || finding.severity === "high")
+        return "error";
+    if (finding.severity === "medium" || finding.severity === "low")
+        return "warning";
+    return "note";
+}

package/dist/report/terminal.d.ts

@@ -0,0 +1,3 @@
+import type { BaseReport, Finding } from "../types.js";
+export declare function formatTerminalReport(report: BaseReport): string;
+export declare function formatFindingSummary(finding: Finding): string;

package/dist/report/terminal.js

@@ -0,0 +1,31 @@
+export function formatTerminalReport(report) {
+    const lines = [];
+    lines.push(`ai-saas-guard ${report.command}`);
+    lines.push(`Root: ${report.rootDir}`);
+    lines.push(`Findings: ${report.summary.total} total | critical ${report.summary.critical} | high ${report.summary.high} | medium ${report.summary.medium} | low ${report.summary.low} | info ${report.summary.info}`);
+    if (report.findings.length === 0) {
+        lines.push("");
+        lines.push("No heuristic launch-readiness risks found by this command.");
+        return lines.join("\n");
+    }
+    for (const [index, item] of report.findings.entries()) {
+        lines.push("");
+        lines.push(`${index + 1}. [${item.severity.toUpperCase()}] ${item.title}`);
+        lines.push(`   Rule: ${item.ruleId}`);
+        lines.push(`   Why: ${item.why}`);
+        lines.push(`   Verify: ${item.suggestedVerification}`);
+        lines.push(`   Fix direction: ${item.suggestedFix}`);
+        lines.push("   Evidence:");
+        for (const evidence of item.evidence.slice(0, 5)) {
+            const location = evidence.line ? `${evidence.file}:${evidence.line}` : evidence.file;
+            const detail = evidence.snippet ?? evidence.match ?? "";
+            lines.push(`   - ${location}${detail ? ` -> ${detail}` : ""}`);
+        }
+    }
+    return lines.join("\n");
+}
+export function formatFindingSummary(finding) {
+    const firstEvidence = finding.evidence[0];
+    const location = firstEvidence?.line ? `${firstEvidence.file}:${firstEvidence.line}` : firstEvidence?.file;
+    return `${finding.severity.toUpperCase()} ${finding.ruleId}${location ? ` ${location}` : ""}`;
+}

package/dist/rules/catalog.d.ts

@@ -0,0 +1,11 @@
+import type { Severity } from "../types.js";
+export type RuleStability = "default" | "experimental" | "strict";
+export interface RuleMetadata {
+    ruleId: string;
+    severity: Severity;
+    title: string;
+    why: string;
+    stability: RuleStability;
+}
+export declare const RULE_CATALOG: Record<string, RuleMetadata>;
+export declare function getRuleMetadata(ruleId: string): RuleMetadata | undefined;

package/dist/rules/catalog.js

@@ -0,0 +1,208 @@
+export const RULE_CATALOG = {
+    "secrets.detected": {
+        ruleId: "secrets.detected",
+        severity: "high",
+        title: "Secret-like value detected",
+        why: "Credentials committed to source, config, or examples can be exposed before launch.",
+        stability: "default"
+    },
+    "next.env.public-secret": {
+        ruleId: "next.env.public-secret",
+        severity: "high",
+        title: "Risky NEXT_PUBLIC environment variable",
+        why: "Next.js exposes NEXT_PUBLIC variables to browser code, so secret-like values can leak to users.",
+        stability: "default"
+    },
+    "stripe.webhook.missing-route": {
+        ruleId: "stripe.webhook.missing-route",
+        severity: "medium",
+        title: "No Stripe webhook handler found",
+        why: "Stripe checkout redirects are not a reliable source of billing truth.",
+        stability: "default"
+    },
+    "stripe.webhook.missing-signature": {
+        ruleId: "stripe.webhook.missing-signature",
+        severity: "critical",
+        title: "Stripe webhook does not verify the Stripe signature",
+        why: "Unsigned webhook handlers can accept forged billing events.",
+        stability: "default"
+    },
+    "stripe.webhook.raw-body-risk": {
+        ruleId: "stripe.webhook.raw-body-risk",
+        severity: "high",
+        title: "Stripe signature verification may use a parsed JSON body",
+        why: "Stripe signature checks require the exact raw request body.",
+        stability: "default"
+    },
+    "stripe.webhook.public-secret": {
+        ruleId: "stripe.webhook.public-secret",
+        severity: "critical",
+        title: "Stripe signing secret appears public",
+        why: "Public Stripe secrets can be bundled into client code and abused.",
+        stability: "default"
+    },
+    "stripe.webhook.missing-idempotency": {
+        ruleId: "stripe.webhook.missing-idempotency",
+        severity: "high",
+        title: "Stripe webhook lacks duplicate event idempotency",
+        why: "Stripe retries and duplicate events can drift billing state.",
+        stability: "default"
+    },
+    "stripe.webhook.no-entitlement-path": {
+        ruleId: "stripe.webhook.no-entitlement-path",
+        severity: "medium",
+        title: "Stripe webhook does not show an entitlement update path",
+        why: "Returning HTTP 200 is not the same as changing application access state.",
+        stability: "default"
+    },
+    "stripe.webhook.missing-critical-event": {
+        ruleId: "stripe.webhook.missing-critical-event",
+        severity: "high",
+        title: "Stripe webhook does not handle a critical lifecycle event",
+        why: "Failure, cancellation, update, and refund paths need explicit handling.",
+        stability: "default"
+    },
+    "supabase.rls.broad-policy": {
+        ruleId: "supabase.rls.broad-policy",
+        severity: "critical",
+        title: "Broad Supabase RLS policy",
+        why: "`USING (true)` often turns login into public data access.",
+        stability: "default"
+    },
+    "supabase.rls.missing-ownership-filter": {
+        ruleId: "supabase.rls.missing-ownership-filter",
+        severity: "high",
+        title: "Supabase policy lacks an ownership filter",
+        why: "Policies need resource ownership or tenant membership checks.",
+        stability: "default"
+    },
+    "supabase.table.missing-owner-column": {
+        ruleId: "supabase.table.missing-owner-column",
+        severity: "medium",
+        title: "Sensitive table has no owner or tenant column",
+        why: "Sensitive tables are hard to protect without owner or tenant keys.",
+        stability: "default"
+    },
+    "supabase.rls.not-enabled": {
+        ruleId: "supabase.rls.not-enabled",
+        severity: "critical",
+        title: "Sensitive table does not enable row level security",
+        why: "User-data tables should enable row level security.",
+        stability: "default"
+    },
+    "supabase.storage.public-bucket": {
+        ruleId: "supabase.storage.public-bucket",
+        severity: "high",
+        title: "Supabase storage policy or bucket appears public",
+        why: "Storage buckets can leak files even when database rows are protected.",
+        stability: "default"
+    },
+    "api.route.missing-rate-limit": {
+        ruleId: "api.route.missing-rate-limit",
+        severity: "medium",
+        title: "Sensitive API route lacks obvious rate limiting",
+        why: "Login, checkout, upload, AI, and webhook routes are common abuse targets.",
+        stability: "default"
+    },
+    "api.route.auth-without-ownership": {
+        ruleId: "api.route.auth-without-ownership",
+        severity: "high",
+        title: "API route checks auth but lacks an ownership guard",
+        why: "Login checks do not prove resource ownership checks.",
+        stability: "default"
+    },
+    "deploy.next.static-export-api-risk": {
+        ruleId: "deploy.next.static-export-api-risk",
+        severity: "medium",
+        title: "Next static export may conflict with server routes",
+        why: "Static export can conflict with runtime API assumptions.",
+        stability: "default"
+    },
+    "deploy.edge-runtime-node-api": {
+        ruleId: "deploy.edge-runtime-node-api",
+        severity: "medium",
+        title: "Route may use Node-only APIs in Edge runtime",
+        why: "Edge runtime can break Node-only dependencies.",
+        stability: "default"
+    },
+    "deploy.env.example-missing": {
+        ruleId: "deploy.env.example-missing",
+        severity: "low",
+        title: "Important runtime env var is not documented",
+        why: "Missing env docs cause local-success, production-failure deploys.",
+        stability: "default"
+    },
+    "mcp.config.invalid-json": {
+        ruleId: "mcp.config.invalid-json",
+        severity: "medium",
+        title: "MCP config is not valid JSON",
+        why: "Broken MCP configs hide the actual tool inventory.",
+        stability: "default"
+    },
+    "mcp.config.plaintext-secret": {
+        ruleId: "mcp.config.plaintext-secret",
+        severity: "high",
+        title: "MCP server contains plaintext secret-like config",
+        why: "Prompt and tool logs can expose plaintext credentials.",
+        stability: "default"
+    },
+    "mcp.config.non-local-bind": {
+        ruleId: "mcp.config.non-local-bind",
+        severity: "high",
+        title: "MCP server may bind outside localhost",
+        why: "Broad bind addresses can expose local tools to the network.",
+        stability: "default"
+    },
+    "mcp.config.insecure-http": {
+        ruleId: "mcp.config.insecure-http",
+        severity: "medium",
+        title: "MCP server uses insecure HTTP for a non-local endpoint",
+        why: "Plain HTTP can expose tool calls and credentials outside localhost.",
+        stability: "default"
+    },
+    "mcp.config.broad-filesystem": {
+        ruleId: "mcp.config.broad-filesystem",
+        severity: "high",
+        title: "MCP server has broad filesystem or write access",
+        why: "Write access over broad paths increases prompt-injection blast radius.",
+        stability: "default"
+    },
+    "mcp.tool.shell": {
+        ruleId: "mcp.tool.shell",
+        severity: "high",
+        title: "MCP server exposes shell-like tools",
+        why: "Generic shell tools can turn prompt injection into command execution.",
+        stability: "default"
+    },
+    "mcp.tool.raw-sql": {
+        ruleId: "mcp.tool.raw-sql",
+        severity: "high",
+        title: "MCP server exposes database or raw SQL capability",
+        why: "Raw SQL tools can read or mutate production data if over-scoped.",
+        stability: "default"
+    },
+    "mcp.config.loose-permissions": {
+        ruleId: "mcp.config.loose-permissions",
+        severity: "low",
+        title: "MCP config file is readable by group or other users",
+        why: "Secret-bearing configs should not be group/world-readable.",
+        stability: "default"
+    },
+    "pr-risk.sensitive-surface": {
+        ruleId: "pr-risk.sensitive-surface",
+        severity: "medium",
+        title: "Review first sensitive PR surface",
+        why: "AI-generated PRs often bury trust-boundary changes inside larger diffs.",
+        stability: "default"
+    },
+    "pr-risk.no-diff": {
+        ruleId: "pr-risk.no-diff",
+        severity: "info",
+        title: "No git diff found",
+        why: "PR classification needs a diff to identify changed trust boundaries.",
+        stability: "default"
+    }
+};
+export function getRuleMetadata(ruleId) {
+    return RULE_CATALOG[ruleId];
+}

package/dist/scanners/apiRoutes.d.ts

@@ -0,0 +1,3 @@
+import type { Finding } from "../types.js";
+import type { ScanInput } from "../context.js";
+export declare function scanApiRoutes(input: ScanInput): Promise<Finding[]>;

package/dist/scanners/apiRoutes.js

@@ -0,0 +1,52 @@
+import { resolveScanContext } from "../context.js";
+import { finding, uniqueFindings } from "../report/findings.js";
+import { lineAt, lineNumberForIndex } from "../utils/files.js";
+const sensitiveRoutePattern = /(login|register|auth|checkout|stripe|webhook|upload|ai|generate|admin|password|reset|token)/i;
+const rateLimitPattern = /(rateLimit|ratelimit|rate-limit|throttle|limiter|upstash|slowDown)/i;
+const authPattern = /(auth|session|currentUser|getUser|jwt|cookies|authorization)/i;
+const ownershipPattern = /(user_id|owner_id|tenant_id|organization_id|workspace_id|resource\.user|resource\.owner|where\s*:\s*{[\s\S]{0,100}(user|owner|tenant))/i;
+export async function scanApiRoutes(input) {
+    const files = (await resolveScanContext(input)).getFiles((file) => isApiRoute(file.path));
+    const findings = [];
+    for (const file of files) {
+        const hasPostOrMutation = /\b(POST|PUT|PATCH|DELETE)\b|export\s+async\s+function\s+(POST|PUT|PATCH|DELETE)/.test(file.content);
+        const isSensitive = sensitiveRoutePattern.test(file.path) || sensitiveRoutePattern.test(file.content);
+        if (isSensitive && hasPostOrMutation && !rateLimitPattern.test(file.content)) {
+            findings.push(finding({
+                ruleId: "api.route.missing-rate-limit",
+                title: `Sensitive API route lacks obvious rate limiting: ${file.path}`,
+                severity: "medium",
+                evidence: [{ file: file.path, line: firstLine(file.content, /\b(POST|PUT|PATCH|DELETE)\b/), snippet: firstSnippet(file.content, /\b(POST|PUT|PATCH|DELETE)\b/) }],
+                why: "Login, checkout, upload, AI, and webhook endpoints are common abuse targets in AI-built SaaS apps.",
+                suggestedVerification: "Run repeated requests against this route in a staging environment and confirm abuse is throttled before expensive or stateful work runs.",
+                suggestedFix: "Add IP/user keyed rate limiting close to the route entry point, with stricter limits for auth, checkout, upload, AI, and webhook paths."
+            }));
+        }
+        if (authPattern.test(file.content) && /params\.|searchParams|get\(|findUnique|findFirst|update|delete/i.test(file.content) && !ownershipPattern.test(file.content)) {
+            findings.push(finding({
+                ruleId: "api.route.auth-without-ownership",
+                title: `API route checks auth but lacks an obvious ownership guard: ${file.path}`,
+                severity: "high",
+                evidence: [{ file: file.path, line: firstLine(file.content, authPattern), snippet: firstSnippet(file.content, authPattern) }],
+                why: "A route can require login but still allow User B to access User A's resource by guessing an ID.",
+                suggestedVerification: "Run a two-account IDOR test: create a resource as User A, then read, update, and delete it using User B's session.",
+                suggestedFix: "Scope every resource query or mutation by the current user's owner, tenant, or membership relationship."
+            }));
+        }
+    }
+    return uniqueFindings(findings);
+}
+function isApiRoute(path) {
+    return (/(^|\/)app\/api\/.+\/route\.(ts|js|tsx|jsx)$/i.test(path) ||
+        /(^|\/)pages\/api\/.+\.(ts|js)$/i.test(path) ||
+        /(^|\/)(routes|controllers)\/.+\.(ts|js)$/i.test(path));
+}
+function firstLine(content, pattern) {
+    const match = pattern.exec(content);
+    pattern.lastIndex = 0;
+    return match ? lineNumberForIndex(content, match.index) : undefined;
+}
+function firstSnippet(content, pattern) {
+    const line = firstLine(content, pattern);
+    return line ? lineAt(content, line) : undefined;
+}

package/dist/scanners/deploy.d.ts

@@ -0,0 +1,3 @@
+import type { Finding } from "../types.js";
+import type { ScanInput } from "../context.js";
+export declare function scanDeployConfig(input: ScanInput): Promise<Finding[]>;

package/dist/scanners/deploy.js

@@ -0,0 +1,56 @@
+import { resolveScanContext } from "../context.js";
+import { finding, uniqueFindings } from "../report/findings.js";
+import { lineAt, lineNumberForIndex } from "../utils/files.js";
+export async function scanDeployConfig(input) {
+    const files = (await resolveScanContext(input)).files;
+    const findings = [];
+    const envExample = files.find((file) => /(^|\/)\.env\.example$/.test(file.path));
+    const referencedEnv = new Set();
+    for (const file of files) {
+        for (const match of file.content.matchAll(/process\.env\.([A-Z0-9_]+)/g)) {
+            referencedEnv.add(match[1]);
+        }
+        if (/next\.config\.(ts|js|mjs)$/.test(file.path) && /output\s*:\s*["']export["']/.test(file.content) && /app\/api|route\.ts|serverActions/i.test(file.content)) {
+            const line = lineNumberForIndex(file.content, file.content.search(/output\s*:/));
+            findings.push(finding({
+                ruleId: "deploy.next.static-export-api-risk",
+                title: "Next static export may conflict with server routes",
+                severity: "medium",
+                evidence: [{ file: file.path, line, snippet: lineAt(file.content, line) }],
+                why: "Next/Vercel deploys often break when local server behavior depends on runtime routes that static export cannot serve.",
+                suggestedVerification: "Run the same production build command used by CI and request each API route locally from the built output.",
+                suggestedFix: "Use a server-capable Next deployment target for API routes, or split static pages from server endpoints."
+            }));
+        }
+        if (/runtime\s*=\s*["']edge["']/.test(file.content) && /(PrismaClient|fs\.|node:fs|stripe\.webhooks\.constructEvent)/.test(file.content)) {
+            const line = lineNumberForIndex(file.content, file.content.search(/runtime\s*=/));
+            findings.push(finding({
+                ruleId: "deploy.edge-runtime-node-api",
+                title: `Route may use Node-only APIs while configured for Edge runtime: ${file.path}`,
+                severity: "medium",
+                evidence: [{ file: file.path, line, snippet: lineAt(file.content, line) }],
+                why: "Next.js routes that work locally can fail on Vercel when Edge runtime code uses Node-only libraries or raw body assumptions.",
+                suggestedVerification: "Run `next build` and deploy-preview logs for this route with production runtime settings.",
+                suggestedFix: "Move Node-only code to the Node.js runtime or replace incompatible dependencies."
+            }));
+        }
+    }
+    if (envExample) {
+        const documentedEnv = new Set([...envExample.content.matchAll(/^([A-Z0-9_]+)=/gm)].map((match) => match[1]));
+        const missingImportantEnv = [...referencedEnv].filter((name) => {
+            return /(STRIPE|SUPABASE|DATABASE|NEXTAUTH|AUTH|WEBHOOK|SECRET|TOKEN)/.test(name) && !documentedEnv.has(name);
+        });
+        for (const name of missingImportantEnv.slice(0, 10)) {
+            findings.push(finding({
+                ruleId: "deploy.env.example-missing",
+                title: `Important runtime env var is not documented in .env.example: ${name}`,
+                severity: "low",
+                evidence: [{ file: envExample.path, match: name }],
+                why: "Missing production env variables are a common reason Next/Vercel apps work locally and fail after deploy.",
+                suggestedVerification: "Compare required variables against Vercel or CI environment settings before launch.",
+                suggestedFix: "Add a placeholder and short purpose comment for this variable in .env.example."
+            }));
+        }
+    }
+    return uniqueFindings(findings);
+}

package/dist/scanners/gitDiff.d.ts

@@ -0,0 +1,2 @@
+import type { PrRiskOptions, PrRiskReport } from "../types.js";
+export declare function classifyPrRisk(options: PrRiskOptions): Promise<PrRiskReport>;