ai-saas-guard 0.27.1 → 0.28.0

package/CONTRIBUTING.md

@@ -7,7 +7,7 @@
 1. Open an issue or comment on an existing issue before large feature work.
 2. Keep pull requests focused. Separate scanner behavior, docs, workflow changes, and release work when practical.
 3. Include tests for behavior changes. New scanner rules need a vulnerable fixture, a safe fixture, and assertions for both.
-4. Update documentation when behavior, commands, outputs, or release expectations change. If `README.md` changes, review and update `README.zh-CN.md` in the same pull request.
+4. Update documentation when behavior, commands, outputs, or release expectations change. If `README.md` changes, review and update `docs/README.zh-CN.md` in the same pull request.
 5. Fill out the pull request template with release gate evidence and known limitations.
 
 ## Local Development

package/README.md

@@ -13,7 +13,7 @@
 </p>
 
 <p align="center">
-  English | <a href="README.zh-CN.md">中文 README</a>
+  English | <a href="docs/README.zh-CN.md">中文 README</a>
 </p>
 
 <p align="center">
@@ -73,16 +73,16 @@ 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.27.1` |
-| GitHub Action | `zr9959/ai-saas-guard@v0` or fixed tag `v0.27.1` |
+| npm CLI | `ai-saas-guard@0.28.0` |
+| GitHub Action | `zr9959/ai-saas-guard@v0` or fixed tag `v0.28.0` |
 | Outputs | 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.27.1`, `v0` |
-| Current release | `0.27.1` npm README metadata fix; launch-gate report summary remains current |
+| Versioned Action tags | `v0.28.0`, `v0` |
+| Current release | `0.28.0` hosted read-only checkout worker export, hosted Check Run smoke evidence, and README sync |
 | 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`; Worker health and Check Run publisher configuration are live, but end-to-end GitHub App webhook delivery is still blocked pending private App settings verification |
+| Cloudflare hosted ingress | Deployed at `https://ai-saas-guard-hosted.zr9959.workers.dev`; signed GitHub App webhook delivery and compact Check Run smoke now pass in staging |
 | Hosted GitHub App staging | Private App `ai-saas-guard-hosted` (`3834787`) installed on `zr9959/ai-saas-guard`; hosted operations evidence is in [docs/hosted-operations-evidence.md](docs/hosted-operations-evidence.md) |
 | OpenSSF Best Practices | Passing badge, project `12955`; `.bestpractices.json` remains the conservative evidence record |
 
@@ -240,13 +240,15 @@ The hosted GitHub App deployment planner is documented in [docs/github-app-deplo
 
 The hosted production adapter layer is documented in [docs/hosted-production-adapters.md](docs/hosted-production-adapters.md). It exports `createHostedGitHubAppJwt`, `planHostedGitHubInstallationTokenRequest`, and `planHostedProductionWorkerExecution` from `ai-saas-guard/hosted/production-adapters`. It adds RS256 GitHub App JWT generation, selected-repository installation-token request plans, separate worker and Check Run token scopes, a fixed read-only worker command, bounded timeout and output budgets, compact JSON-only output, and cleanup plans for success, failure, timeout, and cancellation. It still does not expose a public hosted service by itself.
 
+The hosted read-only checkout worker is exported from `ai-saas-guard/hosted/worker`. It creates a temporary checkout from trusted GitHub App identity, uses a runtime installation token only through git askpass, runs the fixed `ai-saas-guard pr-risk --json` command with bounded timeout/output, converts CLI JSON into compact findings, and deletes the checkout after success or failure. It does not return source, diffs, secrets, checkout paths, PR-authored commands, or installation tokens.
+
 The hosted Node/container app skeleton is documented in [docs/hosted-node-container-app.md](docs/hosted-node-container-app.md). It exports `createHostedHttpApp`, `createInMemoryHostedAppPlatform`, and `planHostedNodeContainerDeployment` from `ai-saas-guard/hosted/app`. It adds a safe `/healthz` route, signed `/github/webhook` ingress, one-job worker tick, in-memory provider adapters for tests, and deployment-plan validation for secret manager, queue, compact report store, worker sandbox, and GitHub Checks publisher references. It still does not deploy or expose a public hosted service by itself.
 
 The hosted staging deployment planner is documented in [docs/hosted-staging-deployment.md](docs/hosted-staging-deployment.md). It exports `planHostedProviderBinding`, `planHostedStagingDeployment`, and `planHostedGitHubAppPromotion` from `ai-saas-guard/hosted/staging`. It composes real provider references, the Node/container deployment plan, hosted operational release-gate evidence, and GitHub App deployment planning so staging and production promotion stay blocked until the required queue, store, worker sandbox, Check Run publisher, logs, metrics, rollback, and incident-response references are present. It still does not call a cloud provider, create a GitHub App, or expose a public hosted service by itself.
 
 The hosted staging harness is documented in [docs/hosted-staging-harness.md](docs/hosted-staging-harness.md). It exports `createFileBackedHostedStagingHarness` and `createHostedStagingHarnessEvidence` from `ai-saas-guard/hosted/staging-harness`. It runs signed webhook replay through the provider-independent hosted runtime with local file-backed queue, compact report, and Check Run adapters, then verifies worker sandbox cleanup. It is a staging rehearsal tool only; it does not call cloud providers, create a GitHub App, publish live Check Runs, or expose a public hosted service.
 
-The first live hosted ingress is deployed on Cloudflare Workers at `https://ai-saas-guard-hosted.zr9959.workers.dev` and documented in [hosted/cloudflare-worker/README.md](hosted/cloudflare-worker/README.md). It exposes `/healthz`, `/github/app/manifest-callback`, and signed `/github/webhook` intake backed by Cloudflare KV. A private staging GitHub App, `ai-saas-guard-hosted`, is installed on `zr9959/ai-saas-guard` with selected-repository access and the first-slice permission contract. The Worker can verify signatures, store compact pull request identity records, exchange a scoped installation token, fetch PR file metadata from GitHub, classify PR-risk hotspots, and publish a bounded Check Run summary. Current deployed evidence is tracked in [docs/hosted-operations-evidence.md](docs/hosted-operations-evidence.md): health and Check Run publisher configuration pass, but end-to-end GitHub App webhook delivery is still blocked until the private App webhook settings are verified. It still does not run a full source checkout scan worker or store raw webhook payloads, PR title/body text, raw diffs, source, secrets, checkout paths, or installation tokens.
+The first live hosted ingress is deployed on Cloudflare Workers at `https://ai-saas-guard-hosted.zr9959.workers.dev` and documented in [hosted/cloudflare-worker/README.md](hosted/cloudflare-worker/README.md). It exposes `/healthz`, `/github/app/manifest-callback`, and signed `/github/webhook` intake backed by Cloudflare KV. A private staging GitHub App, `ai-saas-guard-hosted`, is installed on `zr9959/ai-saas-guard` with selected-repository access and the first-slice permission contract. The Worker verifies signatures, stores compact pull request identity records, exchanges a scoped installation token, fetches PR file metadata from GitHub, classifies PR-risk hotspots, and publishes a bounded Check Run summary. Current deployed evidence is tracked in [docs/hosted-operations-evidence.md](docs/hosted-operations-evidence.md): health, signed webhook delivery, compact KV records, cleanup, and Check Run publication pass for the staging smoke. The Cloudflare Worker still does not run a full source checkout scan worker or store raw webhook payloads, PR title/body text, raw diffs, source, secrets, checkout paths, or installation tokens.
 
 The hosted operational release gate is documented in [docs/hosted-operational-release-gate.md](docs/hosted-operational-release-gate.md). It defines the hosted-specific CI, replay, queue, worker cleanup, privacy, monitoring, rollback, and incident-response evidence required before any hosted environment is exposed to users. The pure gate evaluator exported from `ai-saas-guard/hosted/contracts` blocks hosted exposure unless every P0 evidence item is fresh, a container digest is recorded, and release notes avoid pentest, certification, and full-audit claims.
 
@@ -254,7 +256,7 @@ Hosted uninstall and data deletion behavior is documented in [docs/hosted-uninst
 
 Hosted pricing and packaging boundaries are documented in [docs/hosted-pricing-packaging.md](docs/hosted-pricing-packaging.md). Core local scanning stays useful without an account; hosted plans may add workflow convenience, saved reports, team policy, and optional human review, but they do not gate local CLI scanning.
 
-Hosted pre-implementation pure contracts are documented in [docs/hosted-preimplementation-contracts.md](docs/hosted-preimplementation-contracts.md). They now include a pull request webhook intake planner that verifies signatures before parsing or queueing, a durable scan queue planner that reuses queued, running, and completed jobs for the same trusted scan key, a worker read-only scan planner that fixes the CLI command and requires repository `contents: read`, and a Check Run publication planner that requires repository `checks: write` and builds bounded check-only payloads from compact reports. They also cover queue-safe webhook event parsing, bounded check-run summary rendering, idempotent queue cleanup planning, worker checkout cleanup planning, a retention/deletion cleanup planner, an operational release gate evaluator, the production adapter plans needed for GitHub App auth and bounded worker execution, the Node/container app skeleton needed for real provider wiring, the staging deployment planner needed before production GitHub App promotion, and the local staging harness needed to rehearse webhook replay, persistence, publication, and cleanup without cloud calls. The service runtime composes these contracts behind replaceable adapters. PR comments remain a later workflow or paid hosted feature, not part of the hosted MVP contract.
+Hosted pre-implementation pure contracts are documented in [docs/hosted-preimplementation-contracts.md](docs/hosted-preimplementation-contracts.md). They now include a pull request webhook intake planner that verifies signatures before parsing or queueing, a durable scan queue planner that reuses queued, running, and completed jobs for the same trusted scan key, a worker read-only scan planner that fixes the CLI command and requires repository `contents: read`, a concrete Node read-only checkout scan runner, and a Check Run publication planner that requires repository `checks: write` and builds bounded check-only payloads from compact reports. They also cover queue-safe webhook event parsing, bounded check-run summary rendering, idempotent queue cleanup planning, worker checkout cleanup planning, a retention/deletion cleanup planner, an operational release gate evaluator, the production adapter plans needed for GitHub App auth and bounded worker execution, the Node/container app skeleton needed for real provider wiring, the staging deployment planner needed before production GitHub App promotion, and the local staging harness needed to rehearse webhook replay, persistence, publication, and cleanup without cloud calls. The service runtime composes these contracts behind replaceable adapters. PR comments remain a later workflow or paid hosted feature, not part of the hosted MVP contract.
 
 A public hosted compact report schema fixture is available at [examples/hosted-compact-report.json](examples/hosted-compact-report.json). It is synthetic and public-safe: compact evidence only, no raw source, raw diffs, secrets, webhook payload bodies, customer payloads, private URLs, or worker checkout paths.
 
@@ -294,7 +296,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.27.1` 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.28.0` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
 
 ```yaml
 name: ai-saas-guard
@@ -426,8 +428,8 @@ Open-source core:
 
 Near-term priorities:
 
-- Use the hosted staging harness to rehearse webhook replay, Check Run publication, compact report persistence, and worker cleanup locally; then bind real provider references, deploy a staging artifact, and collect monitoring, rollback, and incident-response evidence from that artifact.
-- Keep hosted exposure blocked until the operational release gate has fresh evidence from a deployed artifact.
+- Bind the Node/container read-only checkout worker to real provider references, deploy it behind staging queue/sandbox controls, and collect monitoring, rollback, incident-response, dependency, and container-scan evidence.
+- Keep production hosted exposure blocked until the operational release gate has fresh evidence from the deployed checkout worker artifact.
 
 Potential paid layer later:
 

package/dist/hosted/worker.d.ts

@@ -0,0 +1,43 @@
+import type { HostedServiceScanRunner, HostedServiceScanRunnerInput, HostedServiceScanRunnerResult } from "./service.js";
+export type HostedReadOnlyCheckoutCommandStage = "git_init" | "git_remote_add" | "git_fetch_head" | "git_fetch_base" | "git_checkout" | "cli_scan";
+export interface HostedReadOnlyCheckoutCommand {
+    stage: HostedReadOnlyCheckoutCommandStage;
+    command: string;
+    args: string[];
+    cwd: string;
+    env: Record<string, string>;
+    timeoutMs: number;
+    maxOutputBytes: number;
+    shell: false;
+}
+export interface HostedReadOnlyCheckoutCommandResult {
+    stdout: string;
+}
+export type HostedReadOnlyCheckoutCommandRunner = (command: HostedReadOnlyCheckoutCommand) => Promise<HostedReadOnlyCheckoutCommandResult> | HostedReadOnlyCheckoutCommandResult;
+export type HostedInstallationTokenProvider = (input: HostedServiceScanRunnerInput) => Promise<string> | string;
+export interface HostedReadOnlyCheckoutScanRunnerOptions {
+    checkoutRoot?: string;
+    githubCloneBaseUrl?: string;
+    gitCommand?: string;
+    cliCommand?: string;
+    fetchDepth?: number;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+    installationTokenProvider: HostedInstallationTokenProvider;
+    commandRunner?: HostedReadOnlyCheckoutCommandRunner;
+}
+export type HostedReadOnlyCheckoutScanSafeReason = "invalid_worker_plan" | "invalid_repository_full_name" | "invalid_clone_base_url" | "missing_installation_token" | "git_init_failed" | "git_remote_add_failed" | "git_fetch_head_failed" | "git_fetch_base_failed" | "git_checkout_failed" | "cli_scan_failed" | "invalid_cli_output" | "cleanup_failed";
+export declare class HostedReadOnlyCheckoutScanError extends Error {
+    readonly safeReason: HostedReadOnlyCheckoutScanSafeReason;
+    readonly privacy: {
+        readonly includesTemporaryCheckoutRoot: false;
+        readonly includesRawSource: false;
+        readonly includesRawDiffs: false;
+        readonly includesSecrets: false;
+        readonly includesCustomerPayloads: false;
+        readonly includesInstallationToken: false;
+    };
+    constructor(safeReason: HostedReadOnlyCheckoutScanSafeReason);
+}
+export declare function createHostedReadOnlyCheckoutScanRunner(options: HostedReadOnlyCheckoutScanRunnerOptions): HostedServiceScanRunner;
+export declare function runHostedReadOnlyCheckoutScan(input: HostedServiceScanRunnerInput, options: HostedReadOnlyCheckoutScanRunnerOptions): Promise<HostedServiceScanRunnerResult>;

package/dist/hosted/worker.js

@@ -0,0 +1,267 @@
+import { execFile } from "node:child_process";
+import { chmod, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { HOSTED_WORKER_DEFAULT_TIMEOUT_MS, HOSTED_WORKER_MAX_OUTPUT_BYTES, HOSTED_WORKER_MAX_TIMEOUT_MS } from "./production-adapters.js";
+const execFileAsync = promisify(execFile);
+const DEFAULT_GITHUB_CLONE_BASE_URL = "https://github.com";
+const DEFAULT_FETCH_DEPTH = 100;
+const MAX_FETCH_DEPTH = 1_000;
+const MAX_COMPACT_FINDINGS = 200;
+export class HostedReadOnlyCheckoutScanError extends Error {
+    safeReason;
+    privacy = {
+        includesTemporaryCheckoutRoot: false,
+        includesRawSource: false,
+        includesRawDiffs: false,
+        includesSecrets: false,
+        includesCustomerPayloads: false,
+        includesInstallationToken: false
+    };
+    constructor(safeReason) {
+        super(`hosted_read_only_checkout_scan_failed:${safeReason}`);
+        this.name = "HostedReadOnlyCheckoutScanError";
+        this.safeReason = safeReason;
+    }
+}
+export function createHostedReadOnlyCheckoutScanRunner(options) {
+    return (input) => runHostedReadOnlyCheckoutScan(input, options);
+}
+export async function runHostedReadOnlyCheckoutScan(input, options) {
+    const { plan } = input;
+    const { checkout, cli } = plan;
+    if (!plan.accepted || !plan.readOnly || !checkout || !cli || cli.writeMode !== "read_only") {
+        throw new HostedReadOnlyCheckoutScanError("invalid_worker_plan");
+    }
+    const repository = parseRepositoryFullName(checkout.repositoryFullName);
+    if (!repository) {
+        throw new HostedReadOnlyCheckoutScanError("invalid_repository_full_name");
+    }
+    const cloneBaseUrl = normalizeSafeCloneBaseUrl(options.githubCloneBaseUrl ?? DEFAULT_GITHUB_CLONE_BASE_URL);
+    const cloneUrl = `${cloneBaseUrl}/${repository.owner}/${repository.repo}.git`;
+    const timeoutMs = clampPositiveInteger(options.timeoutMs, HOSTED_WORKER_DEFAULT_TIMEOUT_MS, HOSTED_WORKER_MAX_TIMEOUT_MS);
+    const maxOutputBytes = clampPositiveInteger(options.maxOutputBytes, HOSTED_WORKER_MAX_OUTPUT_BYTES, HOSTED_WORKER_MAX_OUTPUT_BYTES);
+    const fetchDepth = clampPositiveInteger(options.fetchDepth, DEFAULT_FETCH_DEPTH, MAX_FETCH_DEPTH);
+    const checkoutRoot = options.checkoutRoot ?? join(tmpdir(), "ai-saas-guard-hosted-checkouts");
+    const token = await options.installationTokenProvider(input);
+    if (typeof token !== "string" || token.trim().length === 0) {
+        throw new HostedReadOnlyCheckoutScanError("missing_installation_token");
+    }
+    await mkdir(checkoutRoot, { recursive: true, mode: 0o700 });
+    const checkoutDir = await mkdtemp(join(checkoutRoot, "job-"));
+    let terminalError;
+    try {
+        await chmod(checkoutDir, 0o700);
+        const askpassPath = join(checkoutDir, ".git-askpass.sh");
+        await writeFile(askpassPath, [
+            "#!/bin/sh",
+            "case \"$1\" in",
+            "*Username*) printf '%s' 'x-access-token' ;;",
+            "*Password*) printf '%s' \"$AI_SAAS_GUARD_GITHUB_TOKEN\" ;;",
+            "*) printf '%s' '' ;;",
+            "esac",
+            ""
+        ].join("\n"), { mode: 0o700 });
+        const gitEnv = safeWorkerEnv(checkoutDir, {
+            GIT_ASKPASS: askpassPath,
+            GIT_TERMINAL_PROMPT: "0",
+            GIT_CONFIG_NOSYSTEM: "1",
+            GIT_CONFIG_GLOBAL: "/dev/null"
+        });
+        const gitSecretEnv = { AI_SAAS_GUARD_GITHUB_TOKEN: token };
+        const gitCommand = options.gitCommand ?? "git";
+        await runCommand(options, gitSecretEnv, commandSpec("git_init", gitCommand, ["init"], checkoutDir, gitEnv, timeoutMs, maxOutputBytes));
+        await runCommand(options, gitSecretEnv, commandSpec("git_remote_add", gitCommand, ["remote", "add", "origin", cloneUrl], checkoutDir, gitEnv, timeoutMs, maxOutputBytes));
+        await runCommand(options, gitSecretEnv, commandSpec("git_fetch_head", gitCommand, ["fetch", "--no-tags", "--depth", String(fetchDepth), "origin", checkout.targetCommitSha], checkoutDir, gitEnv, timeoutMs, maxOutputBytes));
+        await runCommand(options, gitSecretEnv, commandSpec("git_fetch_base", gitCommand, ["fetch", "--no-tags", "--depth", String(fetchDepth), "origin", checkout.baseSha], checkoutDir, gitEnv, timeoutMs, maxOutputBytes));
+        await runCommand(options, gitSecretEnv, commandSpec("git_checkout", gitCommand, ["checkout", "--detach", checkout.targetCommitSha], checkoutDir, gitEnv, timeoutMs, maxOutputBytes));
+        const cliEnv = safeWorkerEnv(checkoutDir);
+        const cliArgs = cli.args.map((arg) => arg === "<worker-checkout>" ? checkoutDir : arg);
+        const cliResult = await runCommand(options, {}, commandSpec("cli_scan", options.cliCommand ?? cli.command, cliArgs, checkoutDir, cliEnv, timeoutMs, maxOutputBytes));
+        return compactScanRunnerResult(cliResult.stdout);
+    }
+    catch (error) {
+        terminalError =
+            error instanceof HostedReadOnlyCheckoutScanError
+                ? error
+                : new HostedReadOnlyCheckoutScanError("cli_scan_failed");
+        throw terminalError;
+    }
+    finally {
+        try {
+            await rm(checkoutDir, { recursive: true, force: true });
+        }
+        catch {
+            if (!terminalError) {
+                throw new HostedReadOnlyCheckoutScanError("cleanup_failed");
+            }
+        }
+    }
+}
+function commandSpec(stage, command, args, cwd, env, timeoutMs, maxOutputBytes) {
+    return {
+        stage,
+        command,
+        args,
+        cwd,
+        env,
+        timeoutMs,
+        maxOutputBytes,
+        shell: false
+    };
+}
+async function runCommand(options, secretEnv, command) {
+    try {
+        if (options.commandRunner) {
+            return await options.commandRunner(command);
+        }
+        const { stdout } = await execFileAsync(command.command, command.args, {
+            cwd: command.cwd,
+            env: { ...command.env, ...secretEnv },
+            timeout: command.timeoutMs,
+            maxBuffer: command.maxOutputBytes,
+            encoding: "utf8",
+            shell: false
+        });
+        return { stdout };
+    }
+    catch {
+        throw new HostedReadOnlyCheckoutScanError(`${command.stage}_failed`);
+    }
+}
+function compactScanRunnerResult(stdout) {
+    try {
+        const report = JSON.parse(stdout);
+        const findings = Array.isArray(report.findings) ? report.findings : [];
+        return {
+            summaryCounts: normalizeSummaryCounts(report.summary),
+            findings: findings.slice(0, MAX_COMPACT_FINDINGS).flatMap(compactFinding)
+        };
+    }
+    catch {
+        throw new HostedReadOnlyCheckoutScanError("invalid_cli_output");
+    }
+}
+function compactFinding(value) {
+    if (!isRecord(value))
+        return [];
+    const ruleId = stringValue(value.ruleId);
+    const severity = stringValue(value.severity);
+    const evidence = Array.isArray(value.evidence) ? value.evidence.find(isRecord) : undefined;
+    const file = stringValue(evidence?.file) ?? stringValue(value.file);
+    if (!ruleId || !severity || !file)
+        return [];
+    const line = integerValue(evidence?.line) ?? integerValue(value.line);
+    return [
+        {
+            ruleId,
+            severity,
+            file,
+            ...(line === undefined ? {} : { line })
+        }
+    ];
+}
+function normalizeSummaryCounts(value) {
+    const record = isRecord(value) ? value : {};
+    const summary = {
+        critical: numberValue(record.critical),
+        high: numberValue(record.high),
+        medium: numberValue(record.medium),
+        low: numberValue(record.low),
+        info: numberValue(record.info)
+    };
+    summary.total = numberValue(record.total, summary.critical + summary.high + summary.medium + summary.low + summary.info);
+    return summary;
+}
+function safeWorkerEnv(checkoutDir, extra = {}) {
+    return {
+        PATH: process.env.PATH ?? "/usr/bin:/bin",
+        HOME: checkoutDir,
+        TMPDIR: checkoutDir,
+        CI: "true",
+        NO_COLOR: "1",
+        ...extra
+    };
+}
+function parseRepositoryFullName(value) {
+    const match = /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/.exec(value);
+    if (!match)
+        return undefined;
+    return {
+        owner: match[1],
+        repo: match[2]
+    };
+}
+function normalizeSafeCloneBaseUrl(value) {
+    try {
+        const url = new URL(value);
+        if (url.protocol !== "https:" ||
+            url.username ||
+            url.password ||
+            url.search ||
+            url.hash ||
+            hasNonSlashPath(url.pathname) ||
+            isUnsafeHostedHostname(url.hostname)) {
+            throw new HostedReadOnlyCheckoutScanError("invalid_clone_base_url");
+        }
+        return `${url.protocol}//${url.host}`;
+    }
+    catch (error) {
+        if (error instanceof HostedReadOnlyCheckoutScanError)
+            throw error;
+        throw new HostedReadOnlyCheckoutScanError("invalid_clone_base_url");
+    }
+}
+function hasNonSlashPath(pathname) {
+    for (const character of pathname) {
+        if (character !== "/")
+            return true;
+    }
+    return false;
+}
+function isUnsafeHostedHostname(hostname) {
+    const normalized = hostname.toLowerCase().replace(/\.$/, "");
+    return (normalized === "localhost" ||
+        normalized.endsWith(".localhost") ||
+        isUnsafeIpv4Hostname(normalized) ||
+        normalized === "::1" ||
+        normalized.startsWith("fc") ||
+        normalized.startsWith("fd") ||
+        normalized.startsWith("fe80:"));
+}
+function isUnsafeIpv4Hostname(hostname) {
+    const parts = hostname.split(".");
+    if (parts.length !== 4 || !parts.every((part) => /^\d+$/.test(part)))
+        return false;
+    const octets = parts.map((part) => Number(part));
+    if (octets.some((octet) => !Number.isInteger(octet) || octet < 0 || octet > 255)) {
+        return false;
+    }
+    const [first, second] = octets;
+    return (first === 0 ||
+        first === 10 ||
+        first === 127 ||
+        (first === 169 && second === 254) ||
+        (first === 172 && second >= 16 && second <= 31) ||
+        (first === 192 && second === 168) ||
+        (first === 100 && second >= 64 && second <= 127) ||
+        first >= 224);
+}
+function clampPositiveInteger(value, fallback, maximum) {
+    if (value === undefined || !Number.isFinite(value))
+        return fallback;
+    return Math.min(maximum, Math.max(1, Math.floor(value)));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringValue(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function integerValue(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) ? value : undefined;
+}
+function numberValue(value, fallback = 0) {
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}

package/{README.zh-CN.md → docs/README.zh-CN.md}

@@ -13,15 +13,15 @@
 </p>
 
 <p align="center">
-  <a href="README.md">English README</a> | 中文
+  <a href="../README.md">English README</a> | 中文
 </p>
 
 <p align="center">
   <a href="https://github.com/zr9959/ai-saas-guard/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/zr9959/ai-saas-guard/actions/workflows/ci.yml/badge.svg"></a>
   <a href="https://www.bestpractices.dev/projects/12955"><img alt="OpenSSF Best Practices" src="https://www.bestpractices.dev/projects/12955/badge"></a>
   <a href="https://www.npmjs.com/package/ai-saas-guard"><img alt="npm" src="https://img.shields.io/npm/v/ai-saas-guard.svg"></a>
-  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
-  <a href="package.json"><img alt="Node.js >=20" src="https://img.shields.io/badge/node-%3E%3D20-339933.svg"></a>
+  <a href="../LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
+  <a href="../package.json"><img alt="Node.js >=20" src="https://img.shields.io/badge/node-%3E%3D20-339933.svg"></a>
 </p>
 
 ---
@@ -67,22 +67,22 @@ AI 能很快把一个 SaaS 做到“看起来能用”。真正危险的是上
 
 这个仓库是公开 GitHub 仓库。
 
-CLI 已发布到 npm：`ai-saas-guard@0.27.1`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.27.1`。
+CLI 已发布到 npm：`ai-saas-guard@0.28.0`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.28.0`。
 
 | 模块 | 状态 |
 | --- | --- |
 | 公开 GitHub 仓库 | 已可用 |
-| npm CLI | `ai-saas-guard@0.27.1` |
-| GitHub Action | `zr9959/ai-saas-guard@v0` 或固定标签 `v0.27.1` |
+| npm CLI | `ai-saas-guard@0.28.0` |
+| GitHub Action | `zr9959/ai-saas-guard@v0` 或固定标签 `v0.28.0` |
 | 输出格式 | Terminal、JSON、SARIF 和 PR markdown |
 | 项目配置 | `.ai-saas-guard.json` 支持规则开关、severity 覆盖、suppressions 和 fail threshold |
 | 隐私模型 | 本地优先、只读扫描、不调用 LLM、不上传代码 |
-| 当前版本 | `0.27.1` npm README metadata fix；CLI 和 hosted Check Run 的 launch-gate report summary 仍是当前功能 |
-| Action 标签 | `v0.27.1`、`v0` |
+| 当前版本 | `0.28.0` hosted read-only checkout worker export、hosted Check Run smoke evidence 和 README 同步 |
+| Action 标签 | `v0.28.0`、`v0` |
 | npm 发布 | GitHub Actions Trusted Publisher/OIDC，无需长期 npm token |
 | 仓库可信度加固 | 严格 branch protection、Dependabot、CodeQL、fast-check fuzzing、signed release provenance assets、private vulnerability reporting、secret scanning 和 push protection |
-| Cloudflare hosted ingress | 已部署到 `https://ai-saas-guard-hosted.zr9959.workers.dev`；Worker health 和 Check Run publisher 配置已在线，但端到端 GitHub App webhook delivery 仍需要验证私有 App 设置 |
-| Hosted GitHub App staging | 私有 App `ai-saas-guard-hosted`（`3834787`）已安装到 `zr9959/ai-saas-guard`；hosted operations evidence 见 [docs/hosted-operations-evidence.md](docs/hosted-operations-evidence.md) |
+| Cloudflare hosted ingress | 已部署到 `https://ai-saas-guard-hosted.zr9959.workers.dev`；签名 GitHub App webhook delivery 和 compact Check Run staging smoke 已通过 |
+| Hosted GitHub App staging | 私有 App `ai-saas-guard-hosted`（`3834787`）已安装到 `zr9959/ai-saas-guard`；hosted operations evidence 见 [docs/hosted-operations-evidence.md](hosted-operations-evidence.md) |
 | OpenSSF Best Practices | 已获得 passing badge，项目 `12955`；`.bestpractices.json` 继续作为保守证据记录 |
 
 ## 快速开始
@@ -148,17 +148,17 @@ node dist/cli.js scan --root /path/to/your-saas
 | GitHub Actions | workflow 权限过宽、PR workflow 缺 concurrency cancel、docs-only 改动跑全量 CI、secret/tool version 缺 fail-fast、`pr-risk` checkout 太浅、Action 未 pin SHA |
 | PR risk | auth、billing、RLS、env、deploy、API、storage、silent-success、测试删除、缺 spec/context、大型混合 diff |
 
-完整规则请看 [docs/rules.md](docs/rules.md)。
+完整规则请看 [docs/rules.md](rules.md)。
 
 ## 仓库可信度加固
 
-公开仓库的维护和发布控制见 [docs/repository-trust-hardening.md](docs/repository-trust-hardening.md)。当前已经配置严格 branch protection、required CI checks、Dependabot npm/GitHub Actions 更新、CodeQL SAST、fast-check fuzz/property tests、基于 npm trusted publishing provenance 的 signed GitHub release assets、private vulnerability reporting、secret scanning 和 push protection。
+公开仓库的维护和发布控制见 [docs/repository-trust-hardening.md](repository-trust-hardening.md)。当前已经配置严格 branch protection、required CI checks、Dependabot npm/GitHub Actions 更新、CodeQL SAST、fast-check fuzz/property tests、基于 npm trusted publishing provenance 的 signed GitHub release assets、private vulnerability reporting、secret scanning 和 push protection。
 
 最新 GitHub releases 会镜像 npm package tarball，并附带 `*.tgz.sigstore.json` 和 `*.tgz.intoto.jsonl` provenance assets。上传前会用 npm registry metadata 校验 tarball digest，并使用 npm provenance 作为来源。
 
 当前 Scorecard 提升路线优先做真实控制，不做表面刷分：更严格的 review gate、可被检测到的 fuzzing、以及 OpenSSF Best Practices Badge 流程。仓库年龄、贡献者多样性、已 review 的 PR 历史这些分数只能随着真实维护逐步提升。
 
-仓库现在已经获得 [OpenSSF Best Practices passing badge](https://www.bestpractices.dev/projects/12955)。[.bestpractices.json](.bestpractices.json) 继续作为公开项目条目的保守证据记录。`dynamic_analysis_enable_assertions` 仍然谨慎标为 unmet，直到运行时断言覆盖面超过当前测试、property 和 fuzz assertions。
+仓库现在已经获得 [OpenSSF Best Practices passing badge](https://www.bestpractices.dev/projects/12955)。[.bestpractices.json](../.bestpractices.json) 继续作为公开项目条目的保守证据记录。`dynamic_analysis_enable_assertions` 仍然谨慎标为 unmet，直到运行时断言覆盖面超过当前测试、property 和 fuzz assertions。
 
 ## PR 风险分流
 
@@ -229,7 +229,7 @@ jobs:
           config: .ai-saas-guard.json
 ```
 
-更多 GitHub Action 示例请看 [docs/github-action.md](docs/github-action.md)。
+更多 GitHub Action 示例请看 [docs/github-action.md](github-action.md)。
 
 ## 项目配置
 
@@ -270,36 +270,37 @@ jobs:
 
 ## Hosted GitHub App 设计
 
-当前仓库已经包含未来 Hosted GitHub App 的设计文档、纯契约测试，以及第一个真实 Cloudflare hosted ingress。私有 staging GitHub App `ai-saas-guard-hosted` 已安装到 `zr9959/ai-saas-guard`，Cloudflare 已配置所需的云端凭据绑定。Worker 代码已经能接收签名 webhook、写入 KV 队列、换取 scoped installation token、读取 GitHub PR file metadata、做 compact PR-risk classification，并发布有长度上限的 Check Run summary；但当前端到端 GitHub App webhook delivery smoke 还被私有 App webhook 设置阻断，证据记录在 [docs/hosted-operations-evidence.md](docs/hosted-operations-evidence.md)。它还不是完整 source checkout scan worker。
+当前仓库已经包含未来 Hosted GitHub App 的设计文档、纯契约测试、第一个真实 Cloudflare hosted ingress，以及 Node/container read-only checkout scan runner。私有 staging GitHub App `ai-saas-guard-hosted` 已安装到 `zr9959/ai-saas-guard`，Cloudflare 已配置所需的云端凭据绑定。Worker 代码已经能接收签名 webhook、写入 KV 队列、换取 scoped installation token、读取 GitHub PR file metadata、做 compact PR-risk classification，并发布有长度上限的 Check Run summary；当前端到端 GitHub App webhook delivery smoke 已通过，证据记录在 [docs/hosted-operations-evidence.md](hosted-operations-evidence.md)。Cloudflare ingress 本身仍不是完整 source checkout scan worker。
 
 相关文档：
 
-- [docs/github-app-design.md](docs/github-app-design.md)
-- [docs/github-app-deployment.md](docs/github-app-deployment.md)
-- [docs/hosted-first-service-slice.md](docs/hosted-first-service-slice.md)
-- [docs/hosted-deployment-model.md](docs/hosted-deployment-model.md)
-- [docs/hosted-service-runtime.md](docs/hosted-service-runtime.md)
-- [docs/hosted-production-adapters.md](docs/hosted-production-adapters.md)
-- [docs/hosted-node-container-app.md](docs/hosted-node-container-app.md)
-- [docs/hosted-staging-deployment.md](docs/hosted-staging-deployment.md)
-- [docs/hosted-staging-harness.md](docs/hosted-staging-harness.md)
-- [docs/hosted-operational-release-gate.md](docs/hosted-operational-release-gate.md)
-- [docs/hosted-uninstall-data-deletion.md](docs/hosted-uninstall-data-deletion.md)
-- [docs/hosted-pricing-packaging.md](docs/hosted-pricing-packaging.md)
-- [docs/hosted-preimplementation-contracts.md](docs/hosted-preimplementation-contracts.md)
+- [docs/github-app-design.md](github-app-design.md)
+- [docs/github-app-deployment.md](github-app-deployment.md)
+- [docs/hosted-first-service-slice.md](hosted-first-service-slice.md)
+- [docs/hosted-deployment-model.md](hosted-deployment-model.md)
+- [docs/hosted-service-runtime.md](hosted-service-runtime.md)
+- [docs/hosted-production-adapters.md](hosted-production-adapters.md)
+- [docs/hosted-node-container-app.md](hosted-node-container-app.md)
+- [docs/hosted-staging-deployment.md](hosted-staging-deployment.md)
+- [docs/hosted-staging-harness.md](hosted-staging-harness.md)
+- [docs/hosted-operational-release-gate.md](hosted-operational-release-gate.md)
+- [docs/hosted-uninstall-data-deletion.md](hosted-uninstall-data-deletion.md)
+- [docs/hosted-pricing-packaging.md](hosted-pricing-packaging.md)
+- [docs/hosted-preimplementation-contracts.md](hosted-preimplementation-contracts.md)
 
 已经实现的 hosted 预实现纯契约包括：
 
 - pull request webhook intake planner：先验签，再解析 payload、生成可信 identity、校验 selected-repository scope，并默认只走 check-run-only 输出
 - durable scan queue planner：同一个 trusted scan key 的 queued/running/completed job 会复用，不重复排 worker，也不会把源码、diff、secret 或 PR 正文放进队列 payload
 - worker read-only scan planner：只用 trusted identity 规划临时 worker checkout，要求 repository `contents: read`，固定运行 `ai-saas-guard pr-risk --json`，并忽略 PR 正文里的 repo 名、token scope 或命令
+- hosted read-only checkout worker：`ai-saas-guard/hosted/worker` 导出 `createHostedReadOnlyCheckoutScanRunner`，从 trusted GitHub App identity 创建临时 checkout，只通过 git askpass 使用 runtime installation token，运行固定 `ai-saas-guard pr-risk --json`，把 CLI JSON 转成 compact findings，并在成功或失败后删除 checkout；不会返回源码、diff、secret、checkout path、PR 里写的命令或 installation token
 - hosted service runtime：`ai-saas-guard/hosted/service` 导出 `createHostedServiceRuntime`，把签名 webhook intake、幂等 queue upsert、read-only worker 编排、compact report 存储、Check Run 发布 adapter 和 worker cleanup 串成可测试的服务核心；它本身不部署公开 hosted 环境
 - GitHub App deployment planner：`ai-saas-guard/hosted/github-app` 导出 `planHostedGitHubAppDeployment`，生成 first slice 最小权限 manifest，并在 release gate、公开 HTTPS URL、container digest、secret 引用、原始 secret 输入、permission 或 event 不安全时阻止创建
 - Hosted production adapter layer：`ai-saas-guard/hosted/production-adapters` 导出 `createHostedGitHubAppJwt`、`planHostedGitHubInstallationTokenRequest` 和 `planHostedProductionWorkerExecution`，用于 GitHub App RS256 JWT、selected-repository installation token 请求规划、worker/check-run 分离 token scope、固定只读 worker 命令、timeout/output 预算、compact JSON-only 输出，以及 success/failure/timeout/cancellation 的 cleanup 规划；它本身仍然不部署公开 hosted 服务
 - Hosted Node/container app skeleton：`ai-saas-guard/hosted/app` 导出 `createHostedHttpApp`、`createInMemoryHostedAppPlatform` 和 `planHostedNodeContainerDeployment`，提供安全 `/healthz`、签名 `/github/webhook` ingress、单 job worker tick、测试用 in-memory provider adapters，以及 secret manager、queue、compact report store、worker sandbox、GitHub Checks publisher 的部署引用校验；它本身仍然不部署或暴露公开 hosted 服务
 - Hosted staging deployment planner：`ai-saas-guard/hosted/staging` 导出 `planHostedProviderBinding`、`planHostedStagingDeployment` 和 `planHostedGitHubAppPromotion`，把真实 provider 引用、Node/container deployment plan、hosted operational release-gate evidence 和 GitHub App deployment planning 组合起来；缺少 queue、store、worker sandbox、Check Run publisher、logs、metrics、rollback 或 incident-response 引用时，会阻止 staging exposure 和 production promotion；它本身仍然不会调用云平台、创建 GitHub App 或暴露公开 hosted 服务
 - Hosted staging harness：`ai-saas-guard/hosted/staging-harness` 导出 `createFileBackedHostedStagingHarness` 和 `createHostedStagingHarnessEvidence`，可以在本地用 file-backed queue、compact report、Check Run request 和 worker sandbox 跑通签名 webhook replay、worker tick 和 cleanup 校验；它只是 staging 演练工具，不会调用云平台、创建 GitHub App、写真实 Check Run 或暴露公开 hosted 服务
-- Cloudflare hosted ingress：`hosted/cloudflare-worker` 已部署到 `https://ai-saas-guard-hosted.zr9959.workers.dev`，提供 `/healthz`、`/github/app/manifest-callback` 和签名 `/github/webhook` intake；Worker 已具备 compact pull request identity、file/category risk signal 和 Check Run metadata 路径；staging GitHub App ID 为 `3834787`，installation ID 为 `135085075`；真实 GitHub App webhook delivery、完整 source checkout scan worker、monitoring、rollback 和 incident-response evidence 仍需要通过 hosted operational release gate
+- Cloudflare hosted ingress：`hosted/cloudflare-worker` 已部署到 `https://ai-saas-guard-hosted.zr9959.workers.dev`，提供 `/healthz`、`/github/app/manifest-callback` 和签名 `/github/webhook` intake；Worker 已具备 compact pull request identity、file/category risk signal 和 Check Run metadata 路径；staging GitHub App ID 为 `3834787`，installation ID 为 `135085075`；真实 GitHub App webhook delivery 和 Check Run smoke 已通过；完整 source checkout worker deployment、monitoring、rollback 和 incident-response evidence 仍需要通过 hosted operational release gate
 - webhook event parser
 - check-run summary renderer
 - Check Run publication planner：要求 repository `checks: write`，只从 compact report 生成有长度上限的 Check Run payload，包含 review categories、优先 review 文件、verification steps 和本地 CLI 复现命令；MVP 不发 PR comment
@@ -307,7 +308,7 @@ jobs:
 - worker checkout cleanup planner
 - retention/deletion cleanup planner：把 compact report 删除、按仓库或 installation 范围取消队列和 running job、worker checkout 删除、retention 过期清理、最小审计记录合成一个安全计划；不会输出源码、diff、secret、customer payload、private URL、checkout path 或底层 cleanup error
 - operational release gate evaluator：检查 hosted 暴露前是否具备 fresh CI、webhook replay、workflow static check、dependency/container scan、cleanup、privacy、monitoring、rollback、incident response 和 release cleanup 证据；缺任何 P0 证据都会阻止 hosted exposure
-- hosted compact report fixture：[examples/hosted-compact-report.json](examples/hosted-compact-report.json)
+- hosted compact report fixture：[examples/hosted-compact-report.json](../examples/hosted-compact-report.json)
 
 这些 helper 不会暴露公开服务、不会直接调用 GitHub API、不会持久化 installation token、不会真实写 check run、不会发 PR comment，也不会上传源码。
 
@@ -334,12 +335,12 @@ npm run build
 node dist/cli.js scan --root .
 ```
 
-发布 CLI、GitHub Action、npm package 或任何公开仓库更新前，必须按照 [docs/release-quality-knowledge-base.md](docs/release-quality-knowledge-base.md) 的 release gate 执行。
+发布 CLI、GitHub Action、npm package 或任何公开仓库更新前，必须按照 [docs/release-quality-knowledge-base.md](release-quality-knowledge-base.md) 的 release gate 执行。
 
-以后更新英文 `README.md` 时，也要同步检查并更新本中文 `README.zh-CN.md`。
+以后更新英文 `README.md` 时，也要同步检查并更新本中文 `docs/README.zh-CN.md`。
 
-贡献要求见 [CONTRIBUTING.md](CONTRIBUTING.md)，里面说明了 PR 流程、测试要求、规则设计、release gate evidence 和公开安全边界。
+贡献要求见 [CONTRIBUTING.md](../CONTRIBUTING.md)，里面说明了 PR 流程、测试要求、规则设计、release gate evidence 和公开安全边界。
 
 ## 安全报告
 
-报告漏洞前请阅读 [SECURITY.md](SECURITY.md)。不要在公开 issue 中发布真实 API key、客户数据、私有源码或生产 URL。
+报告漏洞前请阅读 [SECURITY.md](../SECURITY.md)。不要在公开 issue 中发布真实 API key、客户数据、私有源码或生产 URL。

package/docs/github-action.md

@@ -2,7 +2,7 @@
 
 `ai-saas-guard` ships as a composite GitHub Action for pull request and code scanning workflows.
 
-Use `zr9959/ai-saas-guard@v0` for the latest compatible pre-1.0 Action. Use a specific tag such as `v0.27.1` or a reviewed commit SHA when reproducibility is more important than automatic minor updates.
+Use `zr9959/ai-saas-guard@v0` for the latest compatible pre-1.0 Action. Use a specific tag such as `v0.28.0` or a reviewed commit SHA when reproducibility is more important than automatic minor updates.
 
 ## PR Summary
 

package/docs/github-app-deployment.md

@@ -87,6 +87,6 @@ The repository can now produce and validate the deployment plan, and a private s
 - Webhook URL: `https://ai-saas-guard-hosted.zr9959.workers.dev/github/webhook`
 - Secret storage: Cloudflare Worker secrets for `WEBHOOK_SECRET` and `GITHUB_APP_PRIVATE_KEY`
 
-This is now a first-slice staging Worker deployment, not a complete hosted scanner. The Worker code verifies signatures, queues compact pull request identity records, exchanges scoped installation tokens, fetches PR file metadata, classifies PR-risk hotspots, and publishes bounded Check Runs. Current operations evidence is tracked in [hosted-operations-evidence.md](hosted-operations-evidence.md); health and publisher configuration pass, but end-to-end GitHub App webhook delivery is still blocked pending private App settings verification. It still does not run full source checkout scan workers, store raw diffs, store source code, or expose a production hosted service.
+This is now a first-slice staging Worker deployment, not a complete hosted scanner. The Worker code verifies signatures, queues compact pull request identity records, exchanges scoped installation tokens, fetches PR file metadata, classifies PR-risk hotspots, and publishes bounded Check Runs. Current operations evidence is tracked in [hosted-operations-evidence.md](hosted-operations-evidence.md); health, signed webhook delivery, compact KV records, cleanup, and Check Run publication pass in staging. It still does not run full source checkout scan workers inside the Cloudflare Worker, store raw diffs, store source code, or expose a production hosted service.
 
 The next deployment stage should wire the hosted service runtime, production adapters, [Node/container app skeleton](hosted-node-container-app.md), and [staging deployment planner](hosted-staging-deployment.md) to a real platform queue, compact report store, GitHub installation authentication, worker isolation layer, Checks API publisher, logs, metrics, rollback, and incident-response evidence.

package/docs/hosted-operations-evidence.md

@@ -6,27 +6,28 @@ Passing these checks does not make the project a pentest, certification, or full
 
 ## Current Evidence
 
-Recorded on 2026-05-24 from the deployed Cloudflare Worker.
+Recorded on 2026-05-24 from the deployed Cloudflare Worker and a temporary no-file-change GitHub PR smoke.
 
 | Check | Evidence | Result |
 | --- | --- | --- |
-| Cloudflare Worker health | `GET https://ai-saas-guard-hosted.zr9959.workers.dev/healthz` returned `ok: true`, `checkRunPublisher: "configured"`, `scannerVersion: "0.25.0"`, and all privacy flags set to false for raw payloads, PR text, source, diffs, secrets, customer payloads, checkout paths, and installation tokens | Passed |
-| Deployed Worker version | `wrangler deployments list` showed current version `bc4b87d9-420a-48bb-a058-8066b08abe03`, deployed at `2026-05-24T04:30:41.924Z` | Passed |
+| Cloudflare Worker health | `GET https://ai-saas-guard-hosted.zr9959.workers.dev/healthz` returned `ok: true`, `checkRunPublisher: "configured"`, `scannerVersion: "0.28.0"`, and all privacy flags set to false for raw payloads, PR text, source, diffs, secrets, customer payloads, checkout paths, and installation tokens | Passed |
+| Deployed Worker version | `wrangler deployments list` showed current version `531d2286-86c6-4327-bfd0-67cad8693c10`, deployed at `2026-05-24T09:01:25.706Z` | Passed |
 | KV cleanup | `wrangler kv key list --namespace-id fa5344fbd7944de6a776bf8731d58460 --remote` returned `[]` after smoke cleanup | Passed |
-| Temporary smoke PR cleanup | Temporary PR `#36` was closed and branch `codex/hosted-smoke-20260524123129` was deleted | Passed |
-| End-to-end GitHub App delivery | Temporary PR `#36` triggered normal GitHub Actions and CodeQL checks, but no `ai-saas-guard PR risk` Check Run appeared and no KV delivery record was created | Blocked |
+| Temporary smoke PR cleanup | Temporary PR `#52` was closed, branch `codex/hosted-smoke-20260524170208` was deleted, and in-progress workflow run `26357038569` was cancelled | Passed |
+| End-to-end GitHub App delivery | Temporary PR `#52` created `ai-saas-guard PR risk` from GitHub App `ai-saas-guard-hosted`; Check Run `77585561127` completed with conclusion `success` for head SHA `408925d2bf4df564082dabc3e1893a72c25bdd19` | Passed |
+| Compact hosted record | KV scan record `scan:135085075:1247239389:52:408925d2bf4df564082dabc3e1893a72c25bdd19:0.28.0` completed with zero findings, `conclusion: "success"`, and all privacy flags set to false for raw payloads, PR text, source, diffs, secrets, customer payloads, checkout paths, and installation tokens | Passed |
 
-## Current Blocker
+## Remaining Release Gate Gaps
 
-The deployed Worker is configured to publish compact PR-risk Check Runs when it receives a signed `pull_request` webhook. The temporary smoke PR did not create any Worker KV records, which means the GitHub App webhook did not reach the Worker.
+The deployed Cloudflare Worker now receives signed GitHub App webhook delivery for pull request events and publishes bounded compact Check Runs. This is still staging evidence, not production hosted exposure.
 
-Before claiming live automatic PR checks, inspect the private GitHub App settings for `ai-saas-guard-hosted` and verify:
+The hosted release gate still requires fresh deployed evidence for:
 
-- the webhook is active
-- the webhook URL is `https://ai-saas-guard-hosted.zr9959.workers.dev/github/webhook`
-- the webhook secret matches the Cloudflare `WEBHOOK_SECRET`
-- `pull_request` events are subscribed
-- the App installation still includes `zr9959/ai-saas-guard`
+- full Node/container read-only checkout scan worker deployment
+- worker sandbox network restrictions and cleanup evidence
+- logs, metrics, alerting, rollback, and incident-response drills
+- dependency and container artifact scanning for the deployed worker image
+- retention and uninstall cleanup against the deployed provider stores
 
 ## Smoke Procedure
 

package/docs/hosted-preimplementation-contracts.md

@@ -2,7 +2,7 @@
 
 This document collects pure hosted contracts that can be tested before any hosted GitHub App service is deployed. These contracts keep the hosted design inspectable, local-first, and implementation-ready without adding network calls, credentials, queues, workers, or GitHub API writes. They are no network calls contracts by design.
 
-The helpers live in `src/hosted/contracts.ts` and are exported from `ai-saas-guard/hosted/contracts`. The production adapter plans live in `src/hosted/production-adapters.ts` and are exported from `ai-saas-guard/hosted/production-adapters`. The Node/container app skeleton lives in `src/hosted/app.ts` and is exported from `ai-saas-guard/hosted/app`. The staging deployment planner lives in `src/hosted/staging.ts` and is exported from `ai-saas-guard/hosted/staging`. The local staging harness lives in `src/hosted/staging-harness.ts` and is exported from `ai-saas-guard/hosted/staging-harness`.
+The helpers live in `src/hosted/contracts.ts` and are exported from `ai-saas-guard/hosted/contracts`. The production adapter plans live in `src/hosted/production-adapters.ts` and are exported from `ai-saas-guard/hosted/production-adapters`. The Node/container app skeleton lives in `src/hosted/app.ts` and is exported from `ai-saas-guard/hosted/app`. The concrete read-only checkout worker runner lives in `src/hosted/worker.ts` and is exported from `ai-saas-guard/hosted/worker`. The staging deployment planner lives in `src/hosted/staging.ts` and is exported from `ai-saas-guard/hosted/staging`. The local staging harness lives in `src/hosted/staging-harness.ts` and is exported from `ai-saas-guard/hosted/staging-harness`.
 
 ## Pull Request Webhook Intake Planner
 
@@ -70,6 +70,29 @@ Trust boundaries:
 
 The exported helper is `planHostedWorkerReadOnlyScan`. It is intended to be the worker-provider-independent contract for the first real hosted worker implementation.
 
+## Read-Only Checkout Worker Runner
+
+The read-only checkout worker runner turns the worker plan into a concrete Node/container runner without changing the product boundary. It is still a hosted building block, not a public hosted service by itself.
+
+Default behavior:
+
+- derive the GitHub clone URL only from trusted repository identity
+- require a runtime installation token provider and keep the token out of command arguments, returned results, compact reports, and serialized plans
+- pass the installation token to git only through a temporary askpass helper inside the worker checkout
+- run `git init`, add the trusted remote, fetch the trusted head and base SHAs with bounded depth, and checkout the trusted head SHA
+- run the fixed `ai-saas-guard pr-risk --root <worker-checkout> --base <baseSha> --json` command without shell parsing
+- cap command timeout and output bytes
+- parse only compact JSON fields from CLI output: summary counts, rule IDs, severity, file, and line
+- delete the temporary checkout after success or failure
+
+Privacy boundaries:
+
+- do not return temporary checkout paths, raw source, raw diffs, evidence snippets, secrets, customer payloads, PR-authored commands, PR-authored repository names, or installation tokens
+- do not persist source checkout contents beyond the worker run
+- rely on the deployment sandbox for network egress restrictions around the CLI phase; the runner itself removes GitHub credentials before invoking the CLI
+
+The exported helper is `createHostedReadOnlyCheckoutScanRunner`.
+
 ## Production Adapter Plans
 
 The production adapter layer turns the pure hosted contracts into a safer shape for real platform wiring. It is still provider-independent: it does not start a worker, call GitHub, request live installation tokens, write Check Runs, or upload source code.
@@ -381,6 +404,8 @@ Automated tests must cover:
 - worker read-only scan planning requires repository `contents: read` permissions
 - worker read-only scan planning uses trusted identity for checkout target and fixed CLI command
 - worker read-only scan planning does not persist raw source, raw diffs, secrets, customer payloads, checkout paths, PR-authored commands, or PR-authored token scopes
+- read-only checkout worker runner uses trusted clone targets, bounded command execution, compact output parsing, and cleanup after success or failure
+- read-only checkout worker runner does not expose installation tokens, checkout paths, raw source, raw diffs, secret values, customer payloads, or PR-authored commands
 - accepted pull request events build the expected trusted scan identity
 - unsupported actions are rejected
 - draft pull requests are rejected by default

package/docs/npm-publishing.md

@@ -5,11 +5,11 @@
 ## Current State
 
 - Package name: `ai-saas-guard`
-- Current published version: `0.27.1`
+- Current published version: `0.28.0`
 - Next source candidate: none
 - npm registry state: published at <https://www.npmjs.com/package/ai-saas-guard>
 - First npm-published version: `0.1.1`
-- GitHub Release: `v0.27.1`
+- GitHub Release: `v0.28.0`
 - Publish workflow: `.github/workflows/npm-publish.yml`
 - Trusted Publisher: GitHub Actions, `zr9959/ai-saas-guard`, workflow `npm-publish.yml`, allowed action `npm publish`
 - Long-lived npm publish token: not required
@@ -18,7 +18,7 @@
 
 Use GitHub Actions with npm Trusted Publisher/OIDC:
 
-1. Create and review a release tag such as `v0.27.1`.
+1. Create and review a release tag such as `v0.28.0`.
 2. Publish from the GitHub Release or run the `Publish npm` workflow manually with `ref` set to that tag.
 3. Keep `permissions.id-token: write` in the workflow so npm can exchange the GitHub Actions OIDC identity for a short-lived publish credential.
 4. Run `npm publish --access public` from the workflow. Trusted publishing automatically generates provenance for this public package from this public repository.

package/docs/project-handoff.md

@@ -60,6 +60,7 @@ Implemented surfaces:
 - hosted service runtime document and provider-independent runtime core for signed webhook intake, idempotent queue upsert, read-only worker orchestration, compact report storage, Check Run publication adapters, and worker cleanup planning
 - hosted GitHub App deployment planner document and least-privilege manifest planner for required permissions, events, public HTTPS URLs, container digest, secret references, raw secret input blockers, and release-gate checks
 - hosted production adapter layer document and helpers for RS256 GitHub App JWT creation, selected-repository installation-token request planning, separate worker/check-run token scopes, fixed read-only worker execution, timeout/output budgets, and cleanup planning for success, failure, timeout, and cancellation
+- hosted read-only checkout worker runner exported from `ai-saas-guard/hosted/worker`, with trusted clone targets, git askpass token handling, bounded command execution, compact CLI JSON parsing, and checkout cleanup after success or failure
 - hosted Node/container app skeleton document and helpers for safe health and webhook HTTP ingress, one-job worker ticks, in-memory provider adapters, provider reference validation, and the chosen `node_container` roles `webhook-ingress` and `scan-worker`
 - hosted staging deployment planner document and helpers for provider binding, staging release-gate evidence, Node/container deployment composition, and production GitHub App promotion gating
 - hosted staging harness document and helpers for local signed webhook replay, file-backed queue/report/Check Run artifacts, worker sandbox cleanup verification, and release-gate evidence fixtures without cloud calls
@@ -149,8 +150,8 @@ Hosted staging:
 - GitHub App ID: `3834787`
 - GitHub App installation ID: `135085075`
 - Installed repository: `zr9959/ai-saas-guard`
-- Current hosted mode: deployed Worker health and Check Run publisher configuration pass; code supports signed webhook ingress, compact queueing, scoped GitHub App token exchange, PR file risk classification, and bounded Check Run publishing
-- Not yet complete: end-to-end GitHub App webhook delivery settings verification, full source checkout scan worker execution, monitoring evidence, rollback evidence, incident-response evidence, production hosted exposure, and paid hosted workflow features
+- Current hosted mode: deployed Worker health, signed GitHub App webhook delivery, compact KV records, cleanup, and Check Run publication pass in staging; code supports signed webhook ingress, compact queueing, scoped GitHub App token exchange, PR file risk classification, bounded Check Run publishing, and a Node/container read-only checkout worker runner
+- Not yet complete: deployed full source checkout scan worker with sandbox evidence, monitoring evidence, rollback evidence, incident-response evidence, production hosted exposure, and paid hosted workflow features
 
 OpenSSF Best Practices:
 
@@ -160,7 +161,7 @@ OpenSSF Best Practices:
 Publishing:
 
 - npm package: `ai-saas-guard`
-- Current published release line: `v0.27.1`
+- Current published release line: `v0.28.0` pending this branch release
 - Next source candidate: none
 - Publish workflow: `.github/workflows/npm-publish.yml`
 - Trusted Publisher: GitHub Actions for `zr9959/ai-saas-guard`, workflow `npm-publish.yml`
@@ -173,7 +174,7 @@ Allowed in this public repository:
 - CLI source code
 - tests and intentionally vulnerable fixtures
 - public docs
-- English README and Chinese README; when `README.md` changes, review and update `README.zh-CN.md` in the same change
+- English README and Chinese README; when `README.md` changes, review and update `docs/README.zh-CN.md` in the same change
 - GitHub Action wrapper
 - examples that contain only inert fake data
 - release-quality process docs

package/docs/release-quality-knowledge-base.md

@@ -235,7 +235,7 @@ P0:
 - `types` points to generated declaration files if package exports TypeScript API.
 - `exports` is accurate.
 - README install examples match the published package name.
-- If `README.md` changes, `README.zh-CN.md` must be reviewed and updated or explicitly confirmed still current.
+- If `README.md` changes, `docs/README.zh-CN.md` must be reviewed and updated or explicitly confirmed still current.
 - Version follows semver.
 - Release notes state breaking changes, new checks, false-positive changes, and migration notes.
 - Publish with npm trusted publishing/OIDC when possible.

package/docs/repository-trust-hardening.md

@@ -125,6 +125,6 @@ The repository also includes `.bestpractices.json` with conservative proposed an
 Current badge evidence:
 
 - `CONTRIBUTING.md` documents the pull request process, test expectations, rule-design requirements, release gate evidence, and public-safety constraints.
-- `README.md` and `README.zh-CN.md` document the problem, install path, CLI commands, privacy model, GitHub Action use, hosted boundaries, and trust-hardening controls.
+- `README.md` and `docs/README.zh-CN.md` document the problem, install path, CLI commands, privacy model, GitHub Action use, hosted boundaries, and trust-hardening controls.
 - `.bestpractices.json` records only repository-backed OpenSSF Best Practices proposed answers; unknown or future claims should stay out until they can be supported by public evidence.
 - `dynamic_analysis_enable_assertions` is intentionally still marked unmet because the production CLI does not yet have broad runtime assertion coverage beyond tests, property tests, and fuzzing.

package/hosted/cloudflare-worker/README.md

@@ -13,14 +13,14 @@ It is intentionally narrow:
 - Duplicate GitHub delivery IDs are accepted idempotently.
 - Responses and KV records do not include raw webhook payloads, PR title/body text, source code, diffs, secrets, customer payloads, checkout paths, or installation tokens.
 
-This Worker is a real hosted ingress with first-slice Check Run publishing code, not yet the complete scan worker. `shouldCreateCheckRun` is `true` only when the GitHub App bindings are present and the event passes installation scope checks. Current operations evidence is tracked in [docs/hosted-operations-evidence.md](../../docs/hosted-operations-evidence.md); the Worker health check passes, but end-to-end GitHub App webhook delivery still needs private App settings verification. Full source checkout scanning remains gated behind the hosted operational release gate.
+This Worker is a real hosted ingress with first-slice Check Run publishing code, not yet the complete scan worker. `shouldCreateCheckRun` is `true` only when the GitHub App bindings are present and the event passes installation scope checks. Current operations evidence is tracked in [docs/hosted-operations-evidence.md](../../docs/hosted-operations-evidence.md); the Worker health check, signed webhook delivery, KV cleanup, and compact Check Run smoke pass in staging. Full source checkout scanning remains gated behind the hosted operational release gate and the Node/container checkout worker deployment path.
 
 ## Required Cloudflare Bindings
 
 - `HOSTED_EVENTS`: Cloudflare KV namespace for compact delivery and queued scan records.
 - `WEBHOOK_SECRET`: Worker secret matching the GitHub App webhook secret.
 - `GITHUB_APP_PRIVATE_KEY`: Worker secret for the staging GitHub App private key, used only in memory to sign short-lived GitHub App JWTs.
-- `SCANNER_VERSION`: public version string, currently `0.25.0`.
+- `SCANNER_VERSION`: public version string, currently `0.28.0`.
 - `GITHUB_APP_ID`, `GITHUB_APP_SLUG`, `GITHUB_APP_INSTALLATION_ID`: public staging identifiers for the private GitHub App installation.
 
 ## Deployment
@@ -45,7 +45,7 @@ Current public staging endpoint:
 - GitHub App ID: `3834787`
 - GitHub App installation ID: `135085075`
 - Installed repository: `zr9959/ai-saas-guard`
-- Mode: signed webhook ingress and compact queueing only
+- Mode: signed webhook ingress, compact queueing, PR file metadata classification, and bounded Check Run publishing
 
 ## Release Boundary
 

package/hosted/cloudflare-worker/wrangler.jsonc

@@ -7,7 +7,7 @@
     "enabled": true
   },
   "vars": {
-    "SCANNER_VERSION": "0.25.0",
+    "SCANNER_VERSION": "0.28.0",
     "GITHUB_APP_ID": "3834787",
     "GITHUB_APP_SLUG": "ai-saas-guard-hosted",
     "GITHUB_APP_INSTALLATION_ID": "135085075"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-saas-guard",
-  "version": "0.27.1",
+  "version": "0.28.0",
   "description": "Repo-local launch-readiness scanner for AI-built SaaS apps.",
   "readmeFilename": "README.md",
   "type": "module",
@@ -58,6 +58,10 @@
     "./hosted/staging-harness": {
       "types": "./dist/hosted/staging-harness.d.ts",
       "default": "./dist/hosted/staging-harness.js"
+    },
+    "./hosted/worker": {
+      "types": "./dist/hosted/worker.d.ts",
+      "default": "./dist/hosted/worker.js"
     }
   },
   "bin": {
@@ -81,8 +85,7 @@
     "dist",
     "examples",
     "hosted",
-    "README.md",
-    "README.zh-CN.md"
+    "README.md"
   ],
   "license": "MIT",
   "devDependencies": {