ai-saas-guard 0.22.0 → 0.23.0

package/README.md

@@ -73,13 +73,14 @@ The CLI is published on npm as `ai-saas-guard`, and the GitHub Action is availab
 | JSON and SARIF output | Available |
 | Composite GitHub Action | Available |
 | Project config | `.ai-saas-guard.json` rule toggles, severity overrides, and fail thresholds |
-| Versioned Action tags | `v0.22.0`, `v0` |
-| npm package | `ai-saas-guard@0.22.0` |
+| Versioned Action tags | `v0.23.0`, `v0` |
+| npm package | `ai-saas-guard@0.23.0` |
 | npm publishing | Trusted Publisher/OIDC, no long-lived publish token |
 | Runtime hardening | Per-file and total text scan caps, escaped markdown evidence, stricter hosted deployment blockers |
 | Hosted production adapters | GitHub App JWT signing, installation-token request planning, bounded worker execution, and terminal-state cleanup planning |
 | Hosted app skeleton | Node/container HTTP ingress, health route, worker tick, in-memory provider adapters, and deployment plan validation |
 | Hosted staging deployment planner | Provider binding, staging release-gate evidence, Node/container deployment composition, and GitHub App promotion gating |
+| Hosted staging harness | File-backed webhook replay, queue/report/Check Run artifacts, worker cleanup verification, and local release-gate evidence fixtures |
 
 ## Quick Start
 
@@ -222,13 +223,15 @@ The hosted Node/container app skeleton is documented in [docs/hosted-node-contai
 
 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 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.
 
 Hosted uninstall and data deletion behavior is documented in [docs/hosted-uninstall-data-deletion.md](docs/hosted-uninstall-data-deletion.md). It defines repository removal, full app uninstall, compact report deletion, queue cancellation, audit record retention, repeated cleanup, and user-facing deletion wording.
 
 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, and the staging deployment planner needed before production GitHub App promotion. 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`, 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.
 
@@ -268,7 +271,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.22.0` 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.23.0` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
 
 ```yaml
 name: ai-saas-guard
@@ -398,7 +401,7 @@ Open-source core:
 
 Near-term priorities:
 
-- Use the hosted staging deployment planner to bind real provider references, deploy a staging artifact, and collect webhook replay, Check Run, cleanup, monitoring, rollback, and incident-response evidence from that artifact.
+- 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.
 
 Potential paid layer later:

package/README.zh-CN.md

@@ -55,7 +55,7 @@ AI 能很快把一个 SaaS 从想法做成可运行的产品。真正难的是
 
 这个仓库是公开 GitHub 仓库。
 
-CLI 已发布到 npm：`ai-saas-guard@0.22.0`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.22.0`。
+CLI 已发布到 npm：`ai-saas-guard@0.23.0`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.23.0`。
 
 | 模块 | 状态 |
 | --- | --- |
@@ -66,13 +66,14 @@ CLI 已发布到 npm：`ai-saas-guard@0.22.0`。GitHub Action 支持 `v0` 浮动
 | Markdown PR summary | 已可用 |
 | GitHub Action | 已可用 |
 | 项目配置 | `.ai-saas-guard.json` 支持规则开关、severity 覆盖和 fail threshold |
-| 当前版本 | `0.22.0` |
-| Action 标签 | `v0.22.0`、`v0` |
+| 当前版本 | `0.23.0` |
+| Action 标签 | `v0.23.0`、`v0` |
 | npm 发布 | GitHub Actions Trusted Publisher/OIDC，无需长期 npm token |
 | 运行时加固 | 单文件和总扫描文本预算、markdown evidence 转义、更严格的 hosted deployment 阻断 |
 | Hosted production adapters | GitHub App JWT 签名、installation-token 请求规划、有边界的 worker 执行和终态 cleanup 规划 |
 | Hosted app skeleton | Node/container HTTP ingress、health route、worker tick、in-memory provider adapters 和 deployment plan 校验 |
 | Hosted staging deployment planner | provider binding、staging release-gate evidence、Node/container deployment 组合和 GitHub App promotion gating |
+| Hosted staging harness | 本地 file-backed webhook replay、queue/report/Check Run artifact、worker cleanup 校验和 release-gate evidence fixture |
 
 ## 快速开始
 
@@ -255,6 +256,7 @@ jobs:
 - [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)
@@ -270,6 +272,7 @@ jobs:
 - 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 服务
 - 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

package/dist/hosted/staging-harness.d.ts

@@ -0,0 +1,85 @@
+import { type HostedOperationalReleaseGateEvidence } from "./contracts.js";
+import { type HostedServiceRuntimeOptions, type HostedServiceScanRunnerResult, type HostedServiceWebhookStage } from "./service.js";
+type RepositoryIdSource = HostedServiceRuntimeOptions["selectedRepositoryIdsByInstallation"];
+export interface FileBackedHostedStagingHarnessOptions {
+    rootDir: string;
+    signingKey: string | Buffer;
+    scannerVersion: string;
+    selectedRepositoryIdsByInstallation: RepositoryIdSource;
+    removedRepositoryIdsByInstallation?: RepositoryIdSource;
+    scanResult: HostedServiceScanRunnerResult;
+    now?: () => string;
+}
+export interface FileBackedHostedStagingHarness {
+    paths: FileBackedHostedStagingHarnessPaths;
+    runWebhookReplay(input: HostedStagingHarnessWebhookReplayInput): Promise<HostedStagingHarnessReplayResult>;
+    runWorkerTick(): Promise<HostedStagingHarnessWorkerTickResult>;
+}
+export interface FileBackedHostedStagingHarnessPaths {
+    rootDir: string;
+    queueDir: string;
+    queueSnapshot: string;
+    reportDir: string;
+    reportIndex: string;
+    checkRunDir: string;
+    checkRunIndex: string;
+    workerSandboxRoot: string;
+}
+export interface HostedStagingHarnessWebhookReplayInput {
+    payload: string | Buffer;
+    signatureHeader?: string;
+    deliveryId?: string;
+    manualRerun?: boolean;
+}
+export interface HostedStagingHarnessReplayResult {
+    accepted: boolean;
+    stage: HostedServiceWebhookStage;
+    reason?: string;
+    deliveryId?: string;
+    queuedWorker: boolean;
+    shouldCreateCheckRun: boolean;
+    shouldCreatePrComment: false;
+    privacy: HostedStagingHarnessPrivacy;
+}
+export type HostedStagingHarnessWorkerTickResult = {
+    processed: false;
+    reason: "empty_queue";
+    privacy: HostedStagingHarnessPrivacy;
+} | {
+    processed: true;
+    status: "completed";
+    checkRunPublished: boolean;
+    compactReportStored: boolean;
+    workerSandboxDeleted: boolean;
+    activeWorkerSandboxCount: number;
+    cleanupVerified: boolean;
+    privacy: HostedStagingHarnessPrivacy;
+} | {
+    processed: true;
+    status: "failed";
+    errorClass: "worker_plan_rejected" | "check_run_publication_rejected" | "scan_runner_failed";
+    reason?: string;
+    workerSandboxDeleted: boolean;
+    activeWorkerSandboxCount: number;
+    cleanupVerified: boolean;
+    privacy: HostedStagingHarnessPrivacy;
+};
+export interface HostedStagingHarnessEvidenceInput {
+    collectedAt: string;
+    evidenceBaseUrl: string;
+    owner: string;
+}
+export interface HostedStagingHarnessPrivacy {
+    includesRawWebhookPayload: false;
+    includesUntrustedPrText: false;
+    includesRawSource: false;
+    includesRawDiffs: false;
+    includesSecrets: false;
+    includesCustomerPayloads: false;
+    includesPrivateCheckoutPath: false;
+    includesInstallationToken: false;
+    claimsLiveHostedService: false;
+}
+export declare function createFileBackedHostedStagingHarness(options: FileBackedHostedStagingHarnessOptions): FileBackedHostedStagingHarness;
+export declare function createHostedStagingHarnessEvidence(input: HostedStagingHarnessEvidenceInput): HostedOperationalReleaseGateEvidence[];
+export {};

package/dist/hosted/staging-harness.js

@@ -0,0 +1,215 @@
+import { mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { HOSTED_OPERATIONAL_RELEASE_GATE_REQUIREMENTS } from "./contracts.js";
+import { createHostedServiceRuntime } from "./service.js";
+export function createFileBackedHostedStagingHarness(options) {
+    const paths = hostedStagingHarnessPaths(options.rootDir);
+    const queue = { records: new Map() };
+    const reportStore = createFileBackedReportStore(paths);
+    const checkRunPublisher = createFileBackedCheckRunPublisher(paths);
+    const workerSandboxPaths = new Set();
+    const runtime = createHostedServiceRuntime({
+        signingKey: options.signingKey,
+        scannerVersion: options.scannerVersion,
+        selectedRepositoryIdsByInstallation: options.selectedRepositoryIdsByInstallation,
+        removedRepositoryIdsByInstallation: options.removedRepositoryIdsByInstallation,
+        queue,
+        compactReportStore: reportStore,
+        checkRunPublisher,
+        scanRunner: async ({ queueRecord }) => {
+            const sandboxPath = join(paths.workerSandboxRoot, safeFileSegment(queueRecord.key));
+            workerSandboxPaths.add(sandboxPath);
+            await mkdir(sandboxPath, { recursive: true });
+            await writeFile(join(sandboxPath, "source.ts"), options.scanResult.rawSource ?? "", "utf8");
+            return options.scanResult;
+        },
+        now: options.now
+    });
+    return {
+        paths,
+        async runWebhookReplay(input) {
+            await ensureBaseDirectories(paths);
+            const result = runtime.handlePullRequestWebhook({
+                payload: input.payload,
+                signatureHeader: input.signatureHeader,
+                deliveryId: input.deliveryId,
+                manualRerun: input.manualRerun
+            });
+            await writeQueueSnapshot(paths, queue);
+            return {
+                accepted: result.accepted,
+                stage: result.stage,
+                ...(result.reason === undefined ? {} : { reason: result.reason }),
+                ...(result.deliveryId === undefined ? {} : { deliveryId: result.deliveryId }),
+                queuedWorker: result.queueDecision?.shouldEnqueueWorker ?? false,
+                shouldCreateCheckRun: result.shouldCreateCheckRun,
+                shouldCreatePrComment: false,
+                privacy: hostedStagingHarnessPrivacy()
+            };
+        },
+        async runWorkerTick() {
+            await ensureBaseDirectories(paths);
+            const result = await runtime.runNextQueuedScan();
+            await removeWorkerSandboxes(workerSandboxPaths);
+            await writeQueueSnapshot(paths, queue);
+            const activeWorkerSandboxCount = await countDirectoryEntries(paths.workerSandboxRoot);
+            if (!result.processed) {
+                return {
+                    processed: false,
+                    reason: "empty_queue",
+                    privacy: hostedStagingHarnessPrivacy()
+                };
+            }
+            if (result.status === "completed") {
+                return {
+                    processed: true,
+                    status: "completed",
+                    checkRunPublished: result.checkRunPublication.shouldWriteCheckRun,
+                    compactReportStored: true,
+                    workerSandboxDeleted: activeWorkerSandboxCount === 0,
+                    activeWorkerSandboxCount,
+                    cleanupVerified: result.cleanup.shouldDeleteWorkerCheckout && activeWorkerSandboxCount === 0,
+                    privacy: hostedStagingHarnessPrivacy()
+                };
+            }
+            return {
+                processed: true,
+                status: "failed",
+                errorClass: result.errorClass,
+                ...(result.reason === undefined ? {} : { reason: result.reason }),
+                workerSandboxDeleted: activeWorkerSandboxCount === 0,
+                activeWorkerSandboxCount,
+                cleanupVerified: (result.cleanup?.shouldDeleteWorkerCheckout ?? true) && activeWorkerSandboxCount === 0,
+                privacy: hostedStagingHarnessPrivacy()
+            };
+        }
+    };
+}
+export function createHostedStagingHarnessEvidence(input) {
+    return HOSTED_OPERATIONAL_RELEASE_GATE_REQUIREMENTS.map((requirement) => ({
+        id: requirement.id,
+        status: "passed",
+        collectedAt: input.collectedAt,
+        evidenceUrl: `${input.evidenceBaseUrl.replace(/\/+$/, "")}/${requirement.id}.json`,
+        note: `Local staging harness evidence for ${requirement.label}. This is not hosted exposure.`,
+        owner: input.owner
+    }));
+}
+function hostedStagingHarnessPaths(rootDir) {
+    const queueDir = join(rootDir, "queue");
+    const reportDir = join(rootDir, "reports");
+    const checkRunDir = join(rootDir, "check-runs");
+    return {
+        rootDir,
+        queueDir,
+        queueSnapshot: join(queueDir, "jobs.json"),
+        reportDir,
+        reportIndex: join(reportDir, "index.json"),
+        checkRunDir,
+        checkRunIndex: join(checkRunDir, "index.json"),
+        workerSandboxRoot: join(rootDir, "worker-sandbox")
+    };
+}
+function createFileBackedReportStore(paths) {
+    const records = [];
+    return {
+        records,
+        async save(record) {
+            records.push(record);
+            await mkdir(paths.reportDir, { recursive: true });
+            const file = join(paths.reportDir, `${safeFileSegment(record.id)}.json`);
+            await writeJson(file, {
+                id: record.id,
+                jobKey: record.jobKey,
+                createdAt: record.createdAt,
+                report: record.report
+            });
+            await writeJson(paths.reportIndex, {
+                records: records.map((item) => ({
+                    id: item.id,
+                    jobKey: item.jobKey,
+                    createdAt: item.createdAt,
+                    file: `${safeFileSegment(item.id)}.json`
+                }))
+            });
+        }
+    };
+}
+function createFileBackedCheckRunPublisher(paths) {
+    const requests = [];
+    return {
+        requests,
+        async publish(request) {
+            requests.push(request);
+            await mkdir(paths.checkRunDir, { recursive: true });
+            const fileName = `${String(request.payload.external_id ?? requests.length).replace(/[^A-Za-z0-9._-]/g, "_")}.json`;
+            await writeJson(join(paths.checkRunDir, fileName), {
+                method: request.method,
+                endpoint: request.endpoint,
+                payload: request.payload
+            });
+            await writeJson(paths.checkRunIndex, {
+                records: requests.map((item, index) => ({
+                    index,
+                    endpoint: item.endpoint,
+                    name: item.payload.name,
+                    conclusion: item.payload.conclusion
+                }))
+            });
+        }
+    };
+}
+async function ensureBaseDirectories(paths) {
+    await Promise.all([
+        mkdir(paths.queueDir, { recursive: true }),
+        mkdir(paths.reportDir, { recursive: true }),
+        mkdir(paths.checkRunDir, { recursive: true }),
+        mkdir(paths.workerSandboxRoot, { recursive: true })
+    ]);
+}
+async function writeQueueSnapshot(paths, queue) {
+    await mkdir(paths.queueDir, { recursive: true });
+    await writeJson(paths.queueSnapshot, {
+        records: [...queue.records.values()].map((record) => ({
+            key: record.key,
+            status: record.status,
+            attempt: record.attempt,
+            deliveryIds: record.deliveryIds,
+            createdAt: record.createdAt,
+            updatedAt: record.updatedAt,
+            reportId: record.reportId,
+            identity: record.identity
+        }))
+    });
+}
+async function removeWorkerSandboxes(paths) {
+    await Promise.all([...paths].map((path) => rm(path, { recursive: true, force: true })));
+    paths.clear();
+}
+async function countDirectoryEntries(path) {
+    try {
+        return (await readdir(path)).length;
+    }
+    catch {
+        return 0;
+    }
+}
+async function writeJson(path, value) {
+    await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+function safeFileSegment(value) {
+    return value.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+function hostedStagingHarnessPrivacy() {
+    return {
+        includesRawWebhookPayload: false,
+        includesUntrustedPrText: false,
+        includesRawSource: false,
+        includesRawDiffs: false,
+        includesSecrets: false,
+        includesCustomerPayloads: false,
+        includesPrivateCheckoutPath: false,
+        includesInstallationToken: false,
+        claimsLiveHostedService: false
+    };
+}

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.22.0` 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.23.0` or a reviewed commit SHA when reproducibility is more important than automatic minor updates.
 
 ## PR Summary
 

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 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`.
 
 ## Pull Request Webhook Intake Planner
 
@@ -138,6 +138,28 @@ Privacy boundaries:
 
 The exported helpers are `planHostedProviderBinding`, `planHostedStagingDeployment`, and `planHostedGitHubAppPromotion`.
 
+## Local Staging Harness
+
+The local staging harness is the first executable hosted rehearsal that persists artifacts outside in-memory tests. It is still local-only: it does not call a cloud provider, create a GitHub App, fetch repositories from GitHub, publish live Check Runs, or expose a public service.
+
+Default behavior:
+
+- replay a signed pull request webhook through the hosted service runtime
+- persist a safe queue snapshot to a file-backed harness root
+- persist compact hosted reports without raw source or diffs
+- persist fake Check Run publication requests for review
+- create a temporary worker sandbox during the scan runner phase
+- remove worker sandbox contents before returning the worker result
+- create hosted operational release-gate evidence fixtures with the same shape required by the deployment gate
+
+Privacy boundaries:
+
+- invalid signatures create no queue, report, or Check Run side effects
+- result objects do not include raw webhook payloads, untrusted PR text, raw source, raw diffs, secrets, customer payloads, checkout paths, or installation tokens
+- local evidence is labeled as harness evidence and must not be used to claim live hosted exposure
+
+The exported helpers are `createFileBackedHostedStagingHarness` and `createHostedStagingHarnessEvidence`.
+
 ## Webhook Event Parser
 
 The webhook event parser runs after webhook signature verification. It converts a reduced GitHub `pull_request` webhook payload into a queue-safe scan request identity.

package/docs/hosted-service-runtime.md

@@ -47,6 +47,8 @@ The Node/container app skeleton in [hosted-node-container-app.md](hosted-node-co
 
 The staging deployment planner in [hosted-staging-deployment.md](hosted-staging-deployment.md) composes the runtime-facing provider references with hosted operational release-gate evidence and GitHub App promotion gating.
 
+The staging harness in [hosted-staging-harness.md](hosted-staging-harness.md) exercises this runtime with local file-backed queue, report, Check Run, and worker sandbox adapters so webhook replay and cleanup can be verified before any public staging deployment.
+
 ## Privacy
 
 The runtime intentionally returns safe planning and status objects only.
@@ -90,6 +92,7 @@ This runtime makes the hosted service implementation-ready inside the repository
 - production adapters wired to the platform secret manager and GitHub Checks API
 - Node/container app skeleton wired to real HTTP, queue, store, worker sandbox, and Check publisher infrastructure
 - staging deployment planner passed with real provider references and fresh release-gate evidence
+- local staging harness replay passed with queue, report, Check Run, and worker cleanup artifacts
 - container image and digest
 - live monitoring and rollback evidence
 - hosted operational release gate evidence from the deployed artifact

package/docs/hosted-staging-deployment.md

@@ -14,6 +14,8 @@ The package exports `ai-saas-guard/hosted/staging` with:
 
 These helpers are pure planners. They do not call a cloud provider, create a GitHub App, read secrets, write Check Runs, or expose a hosted service.
 
+The local staging harness in [hosted-staging-harness.md](hosted-staging-harness.md) is the executable rehearsal for this plan. It runs signed webhook replay through file-backed queue, report, Check Run, and worker sandbox adapters without calling a cloud provider.
+
 ## Provider Binding
 
 `planHostedProviderBinding` validates the real provider references a hosted deployment needs:
@@ -90,4 +92,6 @@ The staging planner never returns:
 
 The repository can now produce a staging deployment plan that ties together provider references, release-gate evidence, Node/container deployment, and GitHub App promotion readiness.
 
+The repository can also run a local staging harness that proves the runtime path can accept a signed replay, persist safe artifacts, publish a fake Check Run request, and remove the temporary worker sandbox.
+
 This still is not a live hosted service. A real staging environment still requires actual platform infrastructure, deployed containers, secret manager entries, durable queue/storage resources, worker sandboxing, GitHub Checks runtime credentials, monitoring, rollback evidence, and incident-response evidence collected from the deployed artifact.

package/docs/hosted-staging-harness.md

@@ -0,0 +1,63 @@
+# Hosted Staging Harness
+
+This document describes the local hosted staging harness implemented in `src/hosted/staging-harness.ts`.
+
+It does not announce a public hosted service. The harness is a local, file-backed way to exercise the hosted runtime end to end before a real staging platform exists.
+
+## What Exists
+
+The package exports `ai-saas-guard/hosted/staging-harness` with:
+
+- `createFileBackedHostedStagingHarness`
+- `createHostedStagingHarnessEvidence`
+
+The harness composes the hosted service runtime with local adapters:
+
+- signed pull request webhook replay
+- queue snapshots written to `queue/jobs.json`
+- compact report files written under `reports/`
+- fake GitHub Check Run requests written under `check-runs/`
+- a temporary worker sandbox under `worker-sandbox/`
+- cleanup verification after a worker tick
+- local hosted release-gate evidence fixtures
+
+## Replay Flow
+
+The expected staging rehearsal is:
+
+1. create a temporary harness root
+2. replay a signed pull request webhook with `runWebhookReplay`
+3. process one queued scan with `runWorkerTick`
+4. inspect the queue, report, and Check Run request files
+5. verify that the worker sandbox is empty after cleanup
+
+Invalid signatures stop at the signature stage and create no queue, report, or Check Run side effects.
+
+## Evidence Fixture
+
+`createHostedStagingHarnessEvidence` creates one passed evidence item for each hosted operational release-gate requirement. This is useful for local tests and staging rehearsals that need the same evidence shape as a deployed environment.
+
+The generated notes are explicit that the evidence is local harness evidence, not hosted exposure.
+
+## Privacy
+
+The harness returns safe status objects and compact artifacts only.
+
+It does not return:
+
+- raw webhook payloads
+- untrusted PR text
+- raw source
+- raw diffs
+- secrets
+- customer payloads
+- private checkout paths
+- installation tokens
+
+The worker sandbox may contain temporary scan input during a worker tick. The harness removes that sandbox before returning the worker result and reports whether cleanup was verified.
+
+## Current Status
+
+The repository can now run a local staging rehearsal across webhook intake, queue persistence, worker execution, compact report storage, Check Run publication, and worker cleanup.
+
+This still is not a live hosted service. A real staging environment still requires deployed platform infrastructure, public HTTPS ingress, platform secret references, durable queue/storage resources, worker isolation, GitHub Checks runtime credentials, monitoring, rollback evidence, and incident-response evidence collected from the deployed artifact.

package/docs/npm-publishing.md

@@ -5,10 +5,10 @@
 ## Current State
 
 - Package name: `ai-saas-guard`
-- Current version: `0.22.0`
+- Current version: `0.23.0`
 - npm registry state: published at <https://www.npmjs.com/package/ai-saas-guard>
 - First npm-published version: `0.1.1`
-- GitHub Release: `v0.22.0`
+- GitHub Release: `v0.23.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
@@ -17,7 +17,7 @@
 
 Use GitHub Actions with npm Trusted Publisher/OIDC:
 
-1. Create and review a release tag such as `v0.22.0`.
+1. Create and review a release tag such as `v0.23.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

@@ -62,10 +62,11 @@ Implemented surfaces:
 - 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 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
 - resource caps for repository text collection, including per-file, total-file, and total-byte scan budgets to reduce worst-case memory use
 - hosted pre-implementation contracts document, hosted compact report fixture, and pure helpers for pull request webhook intake planning, durable scan queue upsert planning, worker read-only scan planning, Check Run publication planning, queue-safe pull request event parsing from trusted GitHub event fields, bounded check-run summary rendering, idempotent queue cleanup planning, worker checkout cleanup planning, retention/deletion cleanup planning, and operational release gate evaluation
 - implementation-ready hosted GitHub App permission contract for required permissions, optional PR comment permissions, selected repository installation, and out-of-scope broad permissions
-- hosted GitHub App contract helpers and tests for webhook intake order, webhook verification, installation token scoping, durable scan queue idempotency, compact reports, retention limits, uninstall cleanup, repeated cleanup idempotency, scoped deletion planning, operational release gate blocking, provider-independent service runtime orchestration, GitHub App deployment planning, hosted production adapter planning, Node/container app skeleton planning, and hosted staging deployment planning
+- hosted GitHub App contract helpers and tests for webhook intake order, webhook verification, installation token scoping, durable scan queue idempotency, compact reports, retention limits, uninstall cleanup, repeated cleanup idempotency, scoped deletion planning, operational release gate blocking, provider-independent service runtime orchestration, GitHub App deployment planning, hosted production adapter planning, Node/container app skeleton planning, hosted staging deployment planning, and local staging harness replay
 - GitHub issue templates for bug reports, false positives, false negatives, rule requests, and public-safe security reports
 - CODEOWNERS for source, tests, docs, workflows, Action, and package metadata
 - JSON output
@@ -136,7 +137,7 @@ CI:
 Publishing:
 
 - npm package: `ai-saas-guard`
-- Current release line: `v0.22.0`
+- Current release line: `v0.23.0`
 - Publish workflow: `.github/workflows/npm-publish.yml`
 - Trusted Publisher: GitHub Actions for `zr9959/ai-saas-guard`, workflow `npm-publish.yml`
 - Long-lived npm publish tokens should not be required.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-saas-guard",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Repo-local launch-readiness scanner for AI-built SaaS apps.",
   "type": "module",
   "homepage": "https://github.com/zr9959/ai-saas-guard#readme",
@@ -53,6 +53,10 @@
     "./hosted/staging": {
       "types": "./dist/hosted/staging.d.ts",
       "default": "./dist/hosted/staging.js"
+    },
+    "./hosted/staging-harness": {
+      "types": "./dist/hosted/staging-harness.d.ts",
+      "default": "./dist/hosted/staging-harness.js"
     }
   },
   "bin": {