ai-saas-guard 0.43.2 → 0.44.0

package/README.md

@@ -25,6 +25,11 @@
   <a href="docs/release-quality-knowledge-base.md"><img alt="Release gate documented" src="https://img.shields.io/badge/release%20gate-documented-0f766e.svg"></a>
 </p>
 
+<p align="center">
+  <strong>Try the 30-second demo — no signup, no code upload, no LLM call:</strong><br>
+  <code>npx ai-saas-guard@latest demo --summary</code>
+</p>
+
 ---
 
 ## Before You Invite Users
@@ -112,7 +117,7 @@ Want to see the report before scanning your own repo?
 npx ai-saas-guard@latest demo --summary
 ```
 
-The demo command uses packaged public fixtures: `examples/demo-risky-saas` currently returns 19 intentional findings across Stripe, Supabase, silent-success paths, Next/Vercel deploy hints, and GitHub Actions; `examples/demo-safe-saas` returns 0 findings for the same broad surfaces with safer static patterns. Rerun `demo` without `--summary` for the full human-readable report, or see [docs/demo-quickstart.md](docs/demo-quickstart.md) if you want to inspect the fixture files locally.
+The demo command uses packaged public fixtures: `examples/demo-risky-saas` currently returns 20 intentional findings across Stripe, Supabase, silent-success paths, Next/Vercel deploy hints, and GitHub Actions; `examples/demo-safe-saas` returns 0 findings for the same broad surfaces with safer static patterns. Rerun `demo` without `--summary` for the full human-readable report, or see [docs/demo-quickstart.md](docs/demo-quickstart.md) if you want to inspect the fixture files locally.
 
 ## See The Output
 
@@ -120,7 +125,7 @@ The report is designed to be read before launch or before merging an AI-heavy PR
 
 ```text
 ai-saas-guard scan summary
-Findings: 19 findings: 2 critical, 6 high, 7 medium, 3 low, 1 info
+Findings: 20 findings: 2 critical, 6 high, 8 medium, 3 low, 1 info
 Launch gate: blocked: critical launch-readiness findings need review before inviting users
 
 Top risks:
@@ -248,13 +253,13 @@ The CLI is published on npm as `ai-saas-guard`, and the GitHub Action is availab
 | Area | Status |
 | --- | --- |
 | Public GitHub repository | Available |
-| npm CLI | `ai-saas-guard@0.43.2` |
-| GitHub Action | `zr9959/ai-saas-guard@v0` or fixed tag `v0.43.2` |
+| npm CLI | `ai-saas-guard@0.43.3` |
+| GitHub Action | `zr9959/ai-saas-guard@v0` or fixed tag `v0.43.3` |
 | Outputs | Launch decision queue, short summary, terminal, JSON, SARIF, and PR-focused markdown |
 | Project config | `.ai-saas-guard.json` rule toggles, severity overrides, suppressions, and fail thresholds |
 | Privacy model | Local-first, read-only scan commands, no LLM calls, no code upload |
-| Versioned Action tags | `v0.43.2`, `v0` |
-| Current release | `0.43.2` fixes hosted cleanup observability, scoped smoke KV cleanup, shallow-history PR diff fallback, Check Run Markdown escaping, and local scan coverage diagnostics while keeping billing disabled |
+| Versioned Action tags | `v0.43.3`, `v0` |
+| Current release | `0.43.3` reduces silent-success false positives for Cloudflare Durable Object stubs, benign null-return parsing/cache reads, configuration fallback parameters, and assertion-rich tests while keeping billing disabled |
 | npm publishing | Trusted Publisher/OIDC, no long-lived publish token |
 | Repository trust hardening | Strict branch protection, Dependabot, CodeQL, fast-check fuzzing, signed release provenance assets, private vulnerability reporting, secret scanning, and push protection |
 | Cloudflare hosted ingress | Deployed at `https://ai-saas-guard-hosted.zr9959.workers.dev`; public install/privacy notes are in [docs/hosted-install-privacy.md](docs/hosted-install-privacy.md); signed GitHub App webhook delivery and compact Check Run smoke now pass in staging |
@@ -450,7 +455,7 @@ Use `suppressions` for narrower false-positive handling when one rule is noisy o
 
 ## GitHub Action
 
-The repo includes a composite Action. Use `v0` for the latest compatible pre-1.0 Action, a specific release tag such as `v0.43.2` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
+The repo includes a composite Action. Use `v0` for the latest compatible pre-1.0 Action, a specific release tag such as `v0.43.3` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
 
 ```yaml
 name: ai-saas-guard

package/dist/cli.js

@@ -2,6 +2,7 @@
 import { resolve } from "node:path";
 import { applyGuardConfig, loadGuardConfig } from "./config.js";
 import { checkActions, checkMcp, checkStripe, checkSupabase, classifyPrRisk, runShowcase, scanRepository } from "./index.js";
+import { formatCommentReport } from "./report/comment.js";
 import { formatJsonReport } from "./report/json.js";
 import { formatMarkdownReport } from "./report/markdown.js";
 import { formatSarifReport } from "./report/sarif.js";
@@ -25,6 +26,9 @@ async function main(argv) {
             report = await scanRepository({ rootDir: args.rootDir });
             break;
         case "check-supabase":
+            if (args.doctor) {
+                process.stderr.write("Note: --doctor is deprecated; the Supabase RLS doctor section is always included.\n");
+            }
             report = await checkSupabase({ rootDir: args.rootDir, doctor: args.doctor });
             break;
         case "check-stripe":
@@ -81,8 +85,8 @@ function parseArgs(argv) {
         }
         if (arg === "--format") {
             const value = argv[index + 1];
-            if (value !== "terminal" && value !== "json" && value !== "sarif" && value !== "markdown" && value !== "summary") {
-                throw new Error("--format requires terminal, json, sarif, markdown, or summary");
+            if (value !== "terminal" && value !== "json" && value !== "sarif" && value !== "markdown" && value !== "summary" && value !== "comment") {
+                throw new Error("--format requires terminal, json, sarif, markdown, summary, or comment");
             }
             result.format = value;
             index += 1;
@@ -150,6 +154,8 @@ function formatReport(report, format) {
         return formatMarkdownReport(report);
     if (format === "summary")
         return `${formatSummaryReport(report)}\n`;
+    if (format === "comment")
+        return `${formatCommentReport(report)}\n`;
     return `${formatTerminalReport(report)}\n`;
 }
 function shouldFail(report, failOn) {
@@ -178,11 +184,11 @@ Repo-local launch-readiness scanner for AI-built SaaS apps.
 Usage:
   ai-saas-guard scan [--root <repo>] [--config <file>] [--json|--sarif|--summary] [--fail-on <severity>]
   ai-saas-guard demo [--json|--markdown|--summary]
-  ai-saas-guard check-supabase [--root <repo>] [--config <file>] [--doctor] [--json|--sarif|--summary] [--fail-on <severity>]
+  ai-saas-guard check-supabase [--root <repo>] [--config <file>] [--json|--sarif|--summary] [--fail-on <severity>]
   ai-saas-guard check-stripe [--root <repo>] [--config <file>] [--json|--sarif|--summary] [--fail-on <severity>]
   ai-saas-guard check-mcp [--root <repo>] [--config <file>] [--policy-template] [--json|--sarif|--summary] [--fail-on <severity>]
   ai-saas-guard check-actions [--root <repo>] [--config <file>] [--json|--sarif|--summary] [--fail-on <severity>]
-  ai-saas-guard pr-risk [--root <repo>] [--config <file>] [--base <branch>] [--json|--sarif|--markdown|--summary] [--fail-on <severity>]
+  ai-saas-guard pr-risk [--root <repo>] [--config <file>] [--base <branch>] [--json|--sarif|--markdown|--summary|--format comment] [--fail-on <severity>]
 
 Defaults:
   - read-only
@@ -192,8 +198,10 @@ Defaults:
   - terminal output by default, JSON with --json
   - SARIF output for GitHub code scanning with --sarif
   - PR-focused markdown summary with --markdown
+  - PR-comment-ready markdown with pr-risk --format comment (paste into a review)
   - first-run launch summary with --summary
   - project config auto-loaded from .ai-saas-guard.json when present
+  - --doctor is deprecated: the Supabase RLS doctor section is always included in check-supabase output; the flag is still accepted but has no effect
 `;
 }
 main(process.argv.slice(2)).then((code) => {

package/dist/hosted/scan-worker/engine.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The real scanner engine, running inside the staging source-checkout worker.
+ *
+ * This is the same rule engine as the CLI: `classifyPrRisk` (the pr-risk
+ * review-queue engine) plus the full `scan` suite (secrets, Stripe, Supabase,
+ * MCP, API routes, deploy config, silent-success, Actions) executed over an
+ * in-memory ScanContext built from SHA-pinned file contents. No filesystem,
+ * no child processes, no network: pure deterministic rules over text.
+ *
+ * Outputs are compacted before leaving the worker: rule ID, severity, file,
+ * and line only. Raw source, raw diffs, PR text, matches, and snippets never
+ * leave the worker boundary.
+ */
+import type { Severity } from "../../types.js";
+import { STAGING_PRIVACY_FLAGS, type ValidatedScanJob } from "./job.js";
+export interface CompactFinding {
+    ruleId: string;
+    severity: Severity;
+    file: string;
+    line?: number;
+}
+export interface PrRiskSummary {
+    categories: string[];
+    topRiskyFiles: Array<{
+        path: string;
+        score: number;
+        categories: string[];
+    }>;
+    reviewChecklist: string[];
+}
+export interface SourceScanResult {
+    jobKey: string;
+    status: "completed";
+    scannerEngine: "cli-identical";
+    scannerVersion: string;
+    repositoryFullName: string;
+    pullRequestNumber: number;
+    baseSha: string;
+    headSha: string;
+    filesScanned: number;
+    startedAt: string;
+    completedAt: string;
+    durationMs: number;
+    stages: Array<{
+        id: string;
+        ok: boolean;
+    }>;
+    prRisk: PrRiskSummary;
+    summaryCounts: {
+        critical: number;
+        high: number;
+        medium: number;
+        low: number;
+        info: number;
+        total: number;
+    };
+    compactFindingCount: number;
+    compactFindings: CompactFinding[];
+    scannerErrors: string[];
+    privacy: typeof STAGING_PRIVACY_FLAGS;
+}
+export declare const MAX_COMPACT_FINDINGS = 200;
+declare const SCAN_STAGES: readonly ["validate", "pr_risk", "full_scan", "compact"];
+export declare function runSourceScan(job: ValidatedScanJob, options: {
+    scannerVersion: string;
+}): Promise<SourceScanResult>;
+export { SCAN_STAGES };

package/dist/hosted/scan-worker/engine.js

@@ -0,0 +1,153 @@
+/**
+ * The real scanner engine, running inside the staging source-checkout worker.
+ *
+ * This is the same rule engine as the CLI: `classifyPrRisk` (the pr-risk
+ * review-queue engine) plus the full `scan` suite (secrets, Stripe, Supabase,
+ * MCP, API routes, deploy config, silent-success, Actions) executed over an
+ * in-memory ScanContext built from SHA-pinned file contents. No filesystem,
+ * no child processes, no network: pure deterministic rules over text.
+ *
+ * Outputs are compacted before leaving the worker: rule ID, severity, file,
+ * and line only. Raw source, raw diffs, PR text, matches, and snippets never
+ * leave the worker boundary.
+ */
+import { checkActions } from "../../scanners/actions.js";
+import { scanApiRoutes } from "../../scanners/apiRoutes.js";
+import { scanDeployConfig } from "../../scanners/deploy.js";
+import { classifyPrRisk } from "../../scanners/gitDiff.js";
+import { checkMcp } from "../../scanners/mcp.js";
+import { scanNextPublicEnv, scanSecrets } from "../../scanners/secrets.js";
+import { scanSilentSuccess } from "../../scanners/silentSuccess.js";
+import { checkStripe } from "../../scanners/stripe.js";
+import { checkSupabase } from "../../scanners/supabase.js";
+import { detectStackInventory } from "../../stackInventory.js";
+import { summarizeFindings, uniqueFindings } from "../../report/findings.js";
+import { STAGING_PRIVACY_FLAGS } from "./job.js";
+export const MAX_COMPACT_FINDINGS = 200;
+const SCAN_STAGES = ["validate", "pr_risk", "full_scan", "compact"];
+function buildScanContext(files) {
+    const textFiles = files.map((file) => ({
+        path: file.path,
+        absolutePath: file.path,
+        content: file.content
+    }));
+    const diagnostics = {
+        filesScanned: textFiles.length,
+        bytesScanned: textFiles.reduce((total, file) => total + file.content.length, 0),
+        unreadableFiles: [],
+        unreadableDirectories: [],
+        skippedLargeFiles: [],
+        skippedBudgetFiles: [],
+        maxFilesReached: false,
+        maxTotalBytesReached: false
+    };
+    return {
+        rootDir: ".",
+        files: textFiles,
+        filesByPath: new Map(textFiles.map((file) => [file.path, file])),
+        fileCollection: diagnostics,
+        getFiles: (predicate) => (predicate ? textFiles.filter(predicate) : [...textFiles])
+    };
+}
+function compactFinding(finding) {
+    const evidence = finding.evidence?.[0];
+    const file = typeof evidence?.file === "string" && evidence.file.length > 0 ? evidence.file : undefined;
+    if (!file)
+        return undefined;
+    const compact = {
+        ruleId: finding.ruleId,
+        severity: finding.severity,
+        file
+    };
+    if (typeof evidence?.line === "number" && Number.isFinite(evidence.line)) {
+        compact.line = evidence.line;
+    }
+    return compact;
+}
+export async function runSourceScan(job, options) {
+    const startedAt = new Date().toISOString();
+    const startedMs = Date.now();
+    const stages = [{ id: "validate", ok: true }];
+    const scannerErrors = [];
+    const context = buildScanContext(job.files);
+    // Stage 1: the real pr-risk review-queue engine over the unified diff.
+    const prRiskReport = await classifyPrRisk({ rootDir: ".", diffText: job.diffText });
+    stages.push({ id: "pr_risk", ok: true });
+    // Stage 2: the full CLI `scan` suite over the in-memory file contents.
+    const scannerRuns = [
+        { name: "scanSecrets", run: () => scanSecrets(context) },
+        { name: "scanNextPublicEnv", run: () => scanNextPublicEnv(context) },
+        { name: "checkStripe", run: async () => (await checkStripe(context)).findings },
+        { name: "checkMcp", run: async () => (await checkMcp(context)).findings },
+        { name: "scanApiRoutes", run: () => scanApiRoutes(context) },
+        { name: "scanDeployConfig", run: () => scanDeployConfig(context) },
+        { name: "scanSilentSuccess", run: () => scanSilentSuccess(context) },
+        { name: "checkActions", run: async () => (await checkActions(context)).findings }
+    ];
+    // checkSupabase mirrors the CLI: it only runs when the stack inventory
+    // detects Supabase usage in the scanned files.
+    const stackInventory = await detectStackInventory(context);
+    if (stackInventory.databases.includes("supabase")) {
+        scannerRuns.push({ name: "checkSupabase", run: async () => (await checkSupabase(context)).findings });
+    }
+    const collected = [...prRiskReport.findings];
+    for (const scanner of scannerRuns) {
+        try {
+            const findings = await scanner.run();
+            collected.push(...findings);
+        }
+        catch (error) {
+            scannerErrors.push(`${scanner.name}: ${error instanceof Error ? error.message : "unknown error"}`);
+        }
+    }
+    stages.push({ id: "full_scan", ok: true });
+    const merged = uniqueFindings(collected);
+    const summary = summarizeFindings(merged);
+    const compactFindings = [];
+    for (const finding of merged) {
+        const compact = compactFinding(finding);
+        if (compact)
+            compactFindings.push(compact);
+        if (compactFindings.length >= MAX_COMPACT_FINDINGS)
+            break;
+    }
+    stages.push({ id: "compact", ok: true });
+    const completedAt = new Date().toISOString();
+    return {
+        jobKey: job.jobKey,
+        status: "completed",
+        scannerEngine: "cli-identical",
+        scannerVersion: options.scannerVersion,
+        repositoryFullName: job.repositoryFullName,
+        pullRequestNumber: job.pullRequestNumber,
+        baseSha: job.baseSha,
+        headSha: job.headSha,
+        filesScanned: job.files.length,
+        startedAt,
+        completedAt,
+        durationMs: Date.now() - startedMs,
+        stages,
+        prRisk: {
+            categories: [...prRiskReport.categories],
+            topRiskyFiles: prRiskReport.topRiskyFiles.map((file) => ({
+                path: file.path,
+                score: file.score,
+                categories: [...file.categories]
+            })),
+            reviewChecklist: [...prRiskReport.reviewChecklist]
+        },
+        summaryCounts: {
+            critical: summary.critical,
+            high: summary.high,
+            medium: summary.medium,
+            low: summary.low,
+            info: summary.info,
+            total: summary.total
+        },
+        compactFindingCount: compactFindings.length,
+        compactFindings,
+        scannerErrors,
+        privacy: STAGING_PRIVACY_FLAGS
+    };
+}
+export { SCAN_STAGES };

package/dist/hosted/scan-worker/job.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Pure scan-job validation for the staging source-checkout worker.
+ *
+ * Cloud-independent: no `cloudflare:workers` imports, safe under node:test.
+ * The worker receives PR source from the staging orchestrator (which fetches
+ * SHA-pinned file contents and the unified diff via the GitHub API). The
+ * worker never holds GitHub credentials and never touches the network for
+ * source: the trust boundary is the pinned head/base SHA pair plus the
+ * staging repository allowlist.
+ */
+export interface SourceFileInput {
+    path: string;
+    content: string;
+}
+export interface ScanJobRequestBody {
+    repositoryFullName?: unknown;
+    pullRequestNumber?: unknown;
+    baseSha?: unknown;
+    headSha?: unknown;
+    diffText?: unknown;
+    files?: unknown;
+}
+export interface ValidatedScanJob {
+    jobKey: string;
+    repositoryFullName: string;
+    pullRequestNumber: number;
+    baseSha: string;
+    headSha: string;
+    diffText: string;
+    files: SourceFileInput[];
+}
+export declare const STAGING_ALLOWED_REPOSITORIES: ReadonlySet<string>;
+export declare const SCAN_JOB_LIMITS: {
+    readonly maxFiles: 300;
+    readonly maxFileBytes: number;
+    readonly maxTotalBytes: number;
+    readonly maxDiffBytes: number;
+    readonly jobKeyMaxLength: 160;
+};
+export declare const STAGING_PRIVACY_FLAGS: {
+    readonly includesRawWebhookPayload: false;
+    readonly includesUntrustedPrText: false;
+    readonly includesRawSource: false;
+    readonly includesRawDiffs: false;
+    readonly includesSecrets: false;
+    readonly includesCustomerPayloads: false;
+    readonly includesPrivateCheckoutPath: false;
+    readonly includesInstallationToken: false;
+    readonly checkRunPublishedByWorker: false;
+    readonly persistsScanRecords: false;
+};
+export declare class ScanJobValidationError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function buildScanJobKey(input: {
+    repositoryFullName: string;
+    pullRequestNumber: number;
+    headSha: string;
+}): string;
+export declare function validateScanJobRequest(body: ScanJobRequestBody): ValidatedScanJob;

package/dist/hosted/scan-worker/job.js

@@ -0,0 +1,113 @@
+/**
+ * Pure scan-job validation for the staging source-checkout worker.
+ *
+ * Cloud-independent: no `cloudflare:workers` imports, safe under node:test.
+ * The worker receives PR source from the staging orchestrator (which fetches
+ * SHA-pinned file contents and the unified diff via the GitHub API). The
+ * worker never holds GitHub credentials and never touches the network for
+ * source: the trust boundary is the pinned head/base SHA pair plus the
+ * staging repository allowlist.
+ */
+export const STAGING_ALLOWED_REPOSITORIES = new Set(["zr9959/ai-saas-guard"]);
+export const SCAN_JOB_LIMITS = {
+    maxFiles: 300,
+    maxFileBytes: 256 * 1024,
+    maxTotalBytes: 2 * 1024 * 1024,
+    maxDiffBytes: 2 * 1024 * 1024,
+    jobKeyMaxLength: 160
+};
+export const STAGING_PRIVACY_FLAGS = {
+    includesRawWebhookPayload: false,
+    includesUntrustedPrText: false,
+    includesRawSource: false,
+    includesRawDiffs: false,
+    includesSecrets: false,
+    includesCustomerPayloads: false,
+    includesPrivateCheckoutPath: false,
+    includesInstallationToken: false,
+    checkRunPublishedByWorker: false,
+    persistsScanRecords: false
+};
+const SHA_RE = /^[a-f0-9]{40}$/i;
+const REPO_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const JOB_KEY_RE = /^[A-Za-z0-9:_\-.]{1,160}$/;
+const textEncoder = new TextEncoder();
+function utf8Bytes(value) {
+    return textEncoder.encode(value).length;
+}
+export class ScanJobValidationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "ScanJobValidationError";
+        this.code = code;
+    }
+}
+export function buildScanJobKey(input) {
+    const [owner, repo] = input.repositoryFullName.split("/");
+    return `scan:staging:${owner}:${repo}:${input.pullRequestNumber}:${input.headSha}`;
+}
+function asNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function validateSha(label, value) {
+    const text = asNonEmptyString(value);
+    if (!text || !SHA_RE.test(text)) {
+        throw new ScanJobValidationError("invalid_sha", `${label} must be a 40-character hex SHA`);
+    }
+    return text.toLowerCase();
+}
+export function validateScanJobRequest(body) {
+    const repositoryFullName = asNonEmptyString(body?.repositoryFullName);
+    if (!repositoryFullName || !REPO_RE.test(repositoryFullName)) {
+        throw new ScanJobValidationError("invalid_repository", "repositoryFullName must look like owner/repo");
+    }
+    if (!STAGING_ALLOWED_REPOSITORIES.has(repositoryFullName)) {
+        throw new ScanJobValidationError("repository_not_allowed", "repository is not in the staging allowlist");
+    }
+    const pullRequestNumber = body?.pullRequestNumber;
+    if (typeof pullRequestNumber !== "number" || !Number.isInteger(pullRequestNumber) || pullRequestNumber <= 0) {
+        throw new ScanJobValidationError("invalid_pr_number", "pullRequestNumber must be a positive integer");
+    }
+    const baseSha = validateSha("baseSha", body?.baseSha);
+    const headSha = validateSha("headSha", body?.headSha);
+    const diffText = asNonEmptyString(body?.diffText);
+    if (!diffText) {
+        throw new ScanJobValidationError("diff_required", "diffText (unified diff) is required");
+    }
+    if (utf8Bytes(diffText) > SCAN_JOB_LIMITS.maxDiffBytes) {
+        throw new ScanJobValidationError("diff_too_large", "diffText exceeds the staging size cap");
+    }
+    if (!Array.isArray(body?.files) || body.files.length === 0) {
+        throw new ScanJobValidationError("files_required", "files (changed-file contents at head SHA) is required");
+    }
+    if (body.files.length > SCAN_JOB_LIMITS.maxFiles) {
+        throw new ScanJobValidationError("too_many_files", `files exceeds the staging cap of ${SCAN_JOB_LIMITS.maxFiles}`);
+    }
+    const files = [];
+    let totalBytes = 0;
+    for (const entry of body.files) {
+        const path = asNonEmptyString(entry?.path);
+        const content = typeof entry?.content === "string" ? entry.content : undefined;
+        if (!path || content === undefined) {
+            throw new ScanJobValidationError("invalid_file_entry", "every file entry needs { path, content }");
+        }
+        if (path.startsWith("/") || path.includes("..")) {
+            throw new ScanJobValidationError("invalid_file_path", "file paths must be repo-relative without traversal");
+        }
+        const bytes = utf8Bytes(content);
+        if (bytes > SCAN_JOB_LIMITS.maxFileBytes) {
+            throw new ScanJobValidationError("file_too_large", `file ${path} exceeds the per-file staging cap`);
+        }
+        totalBytes += bytes;
+        if (totalBytes > SCAN_JOB_LIMITS.maxTotalBytes) {
+            throw new ScanJobValidationError("total_too_large", "combined file contents exceed the staging cap");
+        }
+        files.push({ path, content });
+    }
+    const jobKey = buildScanJobKey({ repositoryFullName, pullRequestNumber, headSha });
+    if (!JOB_KEY_RE.test(jobKey) || jobKey.length > SCAN_JOB_LIMITS.jobKeyMaxLength) {
+        throw new ScanJobValidationError("invalid_job_key", "derived job key failed the charset check");
+    }
+    return { jobKey, repositoryFullName, pullRequestNumber, baseSha, headSha, diffText, files };
+}

package/dist/hosted/scan-worker/node-shims.d.ts

@@ -0,0 +1,28 @@
+/**
+ * esbuild alias shims for node: builtins that do not exist in the Workers isolate.
+ *
+ * None of these code paths execute in the scan worker:
+ * - `node:child_process` execFile: only used by `readGitDiff` in
+ *   `src/scanners/gitDiff.ts`, which is bypassed because the worker always
+ *   passes explicit `diffText` to `classifyPrRisk`.
+ * - `node:fs/promises`: only used by file collectors (never called; the worker
+ *   builds its ScanContext in memory) and by `fileMode` in `src/scanners/mcp.ts`,
+ *   which catches the failure and treats the mode as unknown.
+ * - `node:util` promisify: only wraps execFile at module scope in gitDiff.ts.
+ * - `node:path` join/relative: only used by the file collectors.
+ *
+ * Aliasing keeps the bundle 100% platform-neutral so no nodejs_compat flag is
+ * required, and guarantees the real scanner engine (same code as the CLI) runs
+ * in the worker instead of a reimplementation.
+ */
+export declare function execFile(..._args: unknown[]): never;
+export declare function promisify(fn: (...args: unknown[]) => void): (...args: unknown[]) => Promise<unknown>;
+export declare function stat(..._args: unknown[]): Promise<never>;
+export declare function readdir(..._args: unknown[]): Promise<never>;
+export declare function readFile(..._args: unknown[]): Promise<never>;
+export declare function join(...parts: string[]): string;
+export declare function relative(_from: string, to: string): string;
+export declare function resolve(...parts: string[]): string;
+export declare function dirname(path: string): string;
+export declare function basename(path: string): string;
+export declare function extname(path: string): string;

package/dist/hosted/scan-worker/node-shims.js

@@ -0,0 +1,71 @@
+/**
+ * esbuild alias shims for node: builtins that do not exist in the Workers isolate.
+ *
+ * None of these code paths execute in the scan worker:
+ * - `node:child_process` execFile: only used by `readGitDiff` in
+ *   `src/scanners/gitDiff.ts`, which is bypassed because the worker always
+ *   passes explicit `diffText` to `classifyPrRisk`.
+ * - `node:fs/promises`: only used by file collectors (never called; the worker
+ *   builds its ScanContext in memory) and by `fileMode` in `src/scanners/mcp.ts`,
+ *   which catches the failure and treats the mode as unknown.
+ * - `node:util` promisify: only wraps execFile at module scope in gitDiff.ts.
+ * - `node:path` join/relative: only used by the file collectors.
+ *
+ * Aliasing keeps the bundle 100% platform-neutral so no nodejs_compat flag is
+ * required, and guarantees the real scanner engine (same code as the CLI) runs
+ * in the worker instead of a reimplementation.
+ */
+export function execFile(..._args) {
+    throw new Error("node:child_process is unavailable in the scan worker");
+}
+export function promisify(fn) {
+    return (...args) => new Promise((resolve, reject) => {
+        const callback = (err, ...results) => {
+            if (err) {
+                reject(err);
+                return;
+            }
+            reject(new Error("node:util.promisify stub is unavailable in the scan worker"));
+        };
+        try {
+            fn(...args, callback);
+        }
+        catch (error) {
+            reject(error);
+        }
+    });
+}
+export async function stat(..._args) {
+    throw new Error("node:fs is unavailable in the scan worker");
+}
+export async function readdir(..._args) {
+    throw new Error("node:fs is unavailable in the scan worker");
+}
+export async function readFile(..._args) {
+    throw new Error("node:fs is unavailable in the scan worker");
+}
+export function join(...parts) {
+    return parts
+        .join("/")
+        .replace(/\/{2,}/g, "/")
+        .replace(/\/\.\//g, "/");
+}
+export function relative(_from, to) {
+    return to;
+}
+export function resolve(...parts) {
+    return join(...parts);
+}
+export function dirname(path) {
+    const index = path.lastIndexOf("/");
+    return index <= 0 ? "." : path.slice(0, index);
+}
+export function basename(path) {
+    const index = path.lastIndexOf("/");
+    return index === -1 ? path : path.slice(index + 1);
+}
+export function extname(path) {
+    const base = basename(path);
+    const index = base.lastIndexOf(".");
+    return index <= 0 ? "" : base.slice(index);
+}

package/dist/hosted/scan-worker/worker.d.ts

@@ -0,0 +1,31 @@
+/**
+ * ai-saas-guard staging source-checkout worker (plain Worker, no containers).
+ *
+ * Staging-only companion to the live webhook-ingress worker
+ * (`hosted/cloudflare-worker`, `ai-saas-guard-hosted`). It runs the REAL
+ * scanner engine — the identical rule code as the CLI (`classifyPrRisk` plus
+ * the full `scan` suite) — over SHA-pinned PR source supplied by the staging
+ * orchestrator. The live ingress worker only classifies PR file metadata;
+ * this worker executes all 66 deterministic rules over actual file contents.
+ *
+ * Trust and privacy design:
+ * - The worker holds NO GitHub credentials. The staging orchestrator fetches
+ *   the unified diff and changed-file contents at the pinned head SHA via the
+ *   GitHub API and POSTs them here. Nothing in the worker can mint tokens,
+ *   clone repos, or publish Check Runs.
+ * - The staging repository allowlist plus full-SHA validation is the trust
+ *   boundary: content is addressable by SHA, which is stronger than
+ *   branch-name pinning.
+ * - Stateless: nothing is persisted. No KV, no Durable Objects, no logs of
+ *   request bodies. Cleanup is trivially complete because nothing is stored.
+ * - Only compact findings (ruleId, severity, file, line) leave the worker.
+ *   Raw source, raw diffs, PR text, matches, and snippets never do.
+ */
+interface WorkerEnv {
+    SCANNER_VERSION?: string;
+    SCAN_SECRET?: string;
+}
+declare const _default: {
+    fetch(request: Request, env: WorkerEnv): Promise<Response>;
+};
+export default _default;