ai-saas-guard 0.10.0 → 0.12.0

package/README.md

@@ -1,11 +1,19 @@
 <h1 align="center">ai-saas-guard</h1>
 
 <p align="center">
-  <strong>Local-first launch preflight for AI-built SaaS apps.</strong>
+  <strong>You used AI to build your SaaS. Now you need to know what is risky before launch.</strong>
 </p>
 
 <p align="center">
-  Find the auth, billing, data-access, secret, MCP, and deploy surfaces a human should review before launch or merge.
+  ai-saas-guard points reviewers to the auth, billing, data access, secrets, MCP, and deploy changes that deserve human attention first. It runs locally, reads your repo only, and does not upload code.
+</p>
+
+<p align="center">
+  It is not a pentest. It is a practical review checklist for launch-risk hotspots.
+</p>
+
+<p align="center">
+  English | <a href="README.zh-CN.md">中文 README</a>
 </p>
 
 <p align="center">
@@ -18,13 +26,29 @@
 
 ---
 
-## What It Does
+## The Problem It Solves
 
-`ai-saas-guard` is a command-line launch preflight for founders, solo builders, and reviewers shipping SaaS apps with AI coding tools.
+AI can turn an idea into a working SaaS quickly. The harder question is whether the app is ready for real users.
 
-It answers one narrow question:
+The risky parts are often not the obvious UI bugs. They are the small changes that decide who can see data, who gets paid access, where secrets are exposed, and what an AI tool is allowed to do:
 
-> What changed in auth, billing, data access, secrets, MCP tools, or deploy config that deserves human review first?
+- Can one customer read another customer's data?
+- Can a Stripe webhook grant access twice, miss a failed payment, or trust an unsigned request?
+- Did a public environment variable expose a secret?
+- Did an MCP tool get shell, database, or broad filesystem access?
+- Did a pull request hide auth, billing, or deploy changes inside a large AI-generated diff?
+
+`ai-saas-guard` is a local-first, review-first preflight for that moment. It does not try to prove your app is secure. It is not a pentest, certification, or full audit. It gives founders, solo builders, small teams, and reviewers a short, evidence-backed list of what to check before launch or merge.
+
+## What You Get
+
+Run it against a repository or pull request and get findings with:
+
+- the rule that matched
+- severity and file evidence
+- why the issue matters in a SaaS launch
+- how to verify it manually
+- a practical fix direction
 
 It is built for common AI-SaaS stacks:
 
@@ -35,8 +59,6 @@ It is built for common AI-SaaS stacks:
 - MCP server configuration
 - AI-generated pull requests with large mixed diffs
 
-It is intentionally evidence-first. Findings include a rule ID, severity, file evidence, why it matters, how to verify it, and a fix direction.
-
 ## Current Status
 
 This repository is public on GitHub.
@@ -51,8 +73,8 @@ 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.10.0`, `v0` |
-| npm package | `ai-saas-guard@0.10.0` |
+| Versioned Action tags | `v0.12.0`, `v0` |
+| npm package | `ai-saas-guard@0.12.0` |
 | npm publishing | Trusted Publisher/OIDC, no long-lived publish token |
 
 ## Quick Start
@@ -192,13 +214,13 @@ 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 cover queue-safe webhook event parsing, bounded check-run summary rendering, idempotent queue cleanup planning, worker checkout cleanup planning, and other service-free helpers exported from `ai-saas-guard/hosted/contracts`.
+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, plus a durable scan queue planner that reuses queued, running, and completed jobs for the same trusted scan key. They also cover queue-safe webhook event parsing, bounded check-run summary rendering, idempotent queue cleanup planning, worker checkout cleanup planning, and other service-free helpers exported from `ai-saas-guard/hosted/contracts`.
 
 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.
 
 The proposed hosted app permission boundary is intentionally narrow: repository contents read, pull requests read, checks write, and metadata read for the first version. Optional PR comments require repository policy opt-in, and broad permissions such as administration, deployments, Actions write, and repository secrets are out of scope.
 
-The repository also includes pure pre-implementation hosted contract helpers and tests for webhook verification, installation token scoping, queue idempotency, compact reports, and retention limits. These helpers do not implement or deploy a hosted service.
+The repository also includes pure pre-implementation hosted contract helpers and tests for webhook intake order, webhook verification, installation token scoping, durable queue idempotency, compact reports, and retention limits. These helpers do not implement or deploy a hosted service.
 
 Users should prefer the local CLI for private repositories, offline review, or no-account workflows where hosted code processing is not acceptable.
 
@@ -232,7 +254,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.10.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.12.0` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
 
 ```yaml
 name: ai-saas-guard

package/README.zh-CN.md

@@ -0,0 +1,294 @@
+<h1 align="center">ai-saas-guard</h1>
+
+<p align="center">
+  <strong>你用 AI 把 SaaS 做出来了。现在要知道上线前哪里最容易出事。</strong>
+</p>
+
+<p align="center">
+  ai-saas-guard 会优先指出 auth、billing、data access、secrets、MCP 和 deploy 里最值得人工 review 的改动。它本地运行、只读仓库、不上传代码。
+</p>
+
+<p align="center">
+  它不是渗透测试，而是一份面向上线风险点的实用 review 清单。
+</p>
+
+<p align="center">
+  <a href="README.md">English README</a> | 中文
+</p>
+
+---
+
+## 它解决什么问题
+
+AI 能很快把一个 SaaS 从想法做成可运行的产品。真正难的是：它能不能放心给真实用户用。
+
+上线前最危险的通常不是界面小 bug，而是那些会影响用户数据、付费权限、密钥暴露和 AI 工具权限的小改动：
+
+- 一个用户会不会看到另一个客户的数据？
+- Stripe webhook 会不会重复开通权限、漏处理付款失败，或者信任未签名请求？
+- `NEXT_PUBLIC_*` 里是不是不小心暴露了 secret？
+- MCP 工具是不是拿到了 shell、数据库或过宽的文件系统权限？
+- AI 生成的大 PR 里，是不是把 auth、billing 或 deploy 改动藏在 UI 调整中？
+
+`ai-saas-guard` 是面向这个时刻的本地优先、review-first 上线预检工具。它不会证明你的应用绝对安全，也不是渗透测试、认证或完整安全审计。它的目标是给 founder、独立开发者、小团队和 reviewer 一份短而有证据的清单，告诉你上线或合并 PR 前最该先看哪里。
+
+## 你会得到什么
+
+对仓库或 PR 运行后，它会给出：
+
+- 命中的 rule
+- severity 和文件证据
+- 为什么这个问题会影响 SaaS 上线
+- 如何人工验证
+- 实际修复方向
+
+它适合常见 AI 构建的 SaaS 技术栈：
+
+- Next.js 和 Vercel
+- Supabase RLS、storage policy、SQL migration
+- Stripe checkout、subscription、webhook
+- Prisma 或 SQL migration
+- MCP server 配置
+- AI 生成的大型混合 PR
+
+## 当前状态
+
+这个仓库是公开 GitHub 仓库。
+
+CLI 已发布到 npm：`ai-saas-guard@0.12.0`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.12.0`。
+
+| 模块 | 状态 |
+| --- | --- |
+| 公开 GitHub 仓库 | 已可用 |
+| npm CLI | 已发布为 `ai-saas-guard` |
+| 本地源码运行 | 已可用 |
+| JSON 和 SARIF 输出 | 已可用 |
+| Markdown PR summary | 已可用 |
+| GitHub Action | 已可用 |
+| 项目配置 | `.ai-saas-guard.json` 支持规则开关、severity 覆盖和 fail threshold |
+| 当前版本 | `0.12.0` |
+| Action 标签 | `v0.12.0`、`v0` |
+| npm 发布 | GitHub Actions Trusted Publisher/OIDC，无需长期 npm token |
+
+## 快速开始
+
+无需全局安装，直接运行：
+
+```bash
+npx ai-saas-guard@latest scan --root /path/to/your-saas
+```
+
+运行专项检查：
+
+```bash
+npx ai-saas-guard@latest pr-risk --root /path/to/your-saas --base origin/main
+npx ai-saas-guard@latest check-supabase --root /path/to/your-saas
+npx ai-saas-guard@latest check-stripe --root /path/to/your-saas
+npx ai-saas-guard@latest check-mcp --root /path/to/your-saas
+```
+
+机器可读输出：
+
+```bash
+npx ai-saas-guard@latest scan --root /path/to/your-saas --json
+npx ai-saas-guard@latest scan --root /path/to/your-saas --sarif > ai-saas-guard.sarif
+npx ai-saas-guard@latest pr-risk --root /path/to/your-saas --base origin/main --markdown > ai-saas-guard-pr.md
+```
+
+本地开发：
+
+```bash
+git clone https://github.com/zr9959/ai-saas-guard.git
+cd ai-saas-guard
+npm ci
+npm run build
+node dist/cli.js scan --root /path/to/your-saas
+```
+
+## 主要命令
+
+| 命令 | 用途 |
+| --- | --- |
+| `scan` | 对 secrets、Stripe、Supabase、MCP、API routes、deploy config 做整体上线预检 |
+| `pr-risk` | 分析当前 git diff 或指定 base branch diff，判断哪些文件和风险面应该先 review |
+| `check-supabase` | 检查 migration 和 policy 文件里的 RLS、ownership、storage policy 风险 |
+| `check-stripe` | 检查 webhook 签名、raw body、幂等、订阅生命周期和 entitlement 更新路径 |
+| `check-mcp` | 检查 MCP 配置里的 secret、非 localhost 绑定、shell/db/filesystem 等副作用 |
+
+## 它会检查什么
+
+| 风险面 | 例子 |
+| --- | --- |
+| Secrets 和 env | 类似密钥的字符串、危险的 `NEXT_PUBLIC_*` 暴露 |
+| Stripe | webhook 缺失、未验证签名、raw body 签名风险、缺幂等、缺失败/取消/退款/更新处理 |
+| Supabase | 敏感表没启用 RLS、policy 过宽、缺少 ownership filter、`WITH CHECK` 过弱、storage object policy 过宽 |
+| API routes | 有 auth 但缺少明显 ownership guard，敏感 mutation route 缺少 rate-limit 提示 |
+| MCP | 明文 secret、非 localhost 绑定、过宽文件系统权限、shell 工具、raw SQL 工具 |
+| Deploy config | Next static export 和 API route 冲突、Edge runtime 使用 Node-only API、关键 env 文档缺失 |
+| PR risk | auth、billing、RLS、env、deploy、API、storage、测试删除、大型混合 diff |
+
+完整规则请看 [docs/rules.md](docs/rules.md)。
+
+## PR 风险分流
+
+`scan` 可以扫整个仓库，但这个项目更锋利的入口是 PR review。
+
+AI 生成的 PR 经常把很多东西混在一起：
+
+- UI 调整
+- auth/session 改动
+- database migration
+- Stripe checkout 或 webhook 改动
+- Supabase policy
+- Vercel 配置
+- 测试被删除或削弱
+
+`pr-risk` 会输出：
+
+- 最应该先 review 的文件
+- PR 触碰到的敏感类别
+- review-first checklist
+- 建议拆分 PR 的方向
+- 必要测试或人工验证步骤
+- 当 base ref 或 shallow checkout 导致无法比较时，给出明确诊断
+
+```bash
+node dist/cli.js pr-risk --root /path/to/your-saas --base origin/main --json
+node dist/cli.js pr-risk --root /path/to/your-saas --base origin/main --markdown
+```
+
+## 目标用户
+
+这个工具主要面向：
+
+- 用 AI 编程工具快速做 SaaS MVP 的 founder 或独立开发者
+- 没有专职安全工程师的小团队
+- 需要 review 大型 AI-generated PR 的 reviewer
+- 给客户交付 SaaS 的开发者或 agency
+- 希望在 CI 里加一道轻量上线预检的小团队
+
+它的目标不是吓人，也不是制造大量噪音，而是帮你把 review 时间用在最值得看的地方。
+
+## GitHub Action
+
+可以在 GitHub Actions 里直接使用：
+
+```yaml
+name: ai-saas-guard
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  preflight:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6.0.2
+        with:
+          fetch-depth: 0
+      - uses: zr9959/ai-saas-guard@v0
+        with:
+          command: pr-risk
+          root: ${{ github.workspace }}
+          base: origin/main
+          fail-on: high
+          config: .ai-saas-guard.json
+```
+
+更多 GitHub Action 示例请看 [docs/github-action.md](docs/github-action.md)。
+
+## 项目配置
+
+在仓库根目录添加 `.ai-saas-guard.json` 可以调整规则：
+
+```json
+{
+  "failOn": "high",
+  "rules": {
+    "stripe.webhook.missing-signature": "off",
+    "stripe.webhook.missing-idempotency": "critical",
+    "deploy.env.example-missing": "info"
+  },
+  "suppressions": [
+    {
+      "ruleId": "stripe.webhook.missing-idempotency",
+      "paths": ["app/api/stripe/webhook/route.ts"],
+      "reason": "Temporary launch exception with duplicate-event coverage in integration tests."
+    }
+  ]
+}
+```
+
+`rules` 可以关闭规则或覆盖 severity。`suppressions` 适合处理某个具体路径上的 false positive。`failOn` 用于设置 CI 失败阈值。
+
+## 隐私模型
+
+`ai-saas-guard` 设计上适合在私有本地仓库中运行。
+
+- 本地运行
+- 读取仓库文件和 git diff
+- scan 命令无网络调用
+- 不上传代码
+- 不需要账号或登录
+- 不修改被扫描仓库
+- 对类似 secret 的 evidence 做 redaction
+
+## Hosted GitHub App 设计
+
+当前仓库已经包含未来 Hosted GitHub App 的设计文档和纯契约测试，但还没有部署真实 hosted 服务。
+
+相关文档：
+
+- [docs/github-app-design.md](docs/github-app-design.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-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)
+
+已经实现的 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
+- webhook event parser
+- check-run summary renderer
+- queue cleanup planner
+- worker checkout cleanup planner
+- hosted compact report fixture：[examples/hosted-compact-report.json](examples/hosted-compact-report.json)
+
+这些 helper 不会启动服务、不会调用 GitHub API、不会请求 installation token、不会写 check run，也不会上传源码。
+
+## 它不是什么
+
+这个项目刻意避免过度安全承诺。
+
+- 不是渗透测试
+- 不是完整 SAST 平台
+- 不能证明你的应用绝对安全
+- 不能替代两账号权限测试
+- 不执行 Stripe、Supabase、Vercel 或浏览器流程
+- 不检查没有体现在本地文件里的生产设置
+- 不替代 Semgrep、Gitleaks、TruffleHog、Bearer、CodeQL 或人工 review
+
+正确使用方式是：把它当成上线前和 PR review 前的 preflight，帮助你决定应该先把人工注意力放在哪里。
+
+## 开发
+
+```bash
+npm ci
+npm test
+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 执行。
+
+以后更新英文 `README.md` 时，也要同步检查并更新本中文 `README.zh-CN.md`。
+
+## 安全报告
+
+报告漏洞前请阅读 [SECURITY.md](SECURITY.md)。不要在公开 issue 中发布真实 API key、客户数据、私有源码或生产 URL。

package/dist/hosted/contracts.d.ts

@@ -46,6 +46,43 @@ export interface HostedPullRequestEventDecision {
     action?: string;
     identity?: HostedScanIdentity;
 }
+export type HostedPullRequestWebhookIntakeStage = "signature" | "payload" | "event" | "installation_scope" | "queue";
+export type HostedPullRequestWebhookIntakeRejectReason = WebhookRejectReason | PullRequestEventRejectReason | InstallationScopeRejectReason | "invalid_json" | "missing_delivery_id";
+export interface HostedPullRequestWebhookIntakeInput {
+    payload: string | Buffer;
+    signatureHeader?: string;
+    signingKey: string | Buffer;
+    deliveryId?: string;
+    seenDeliveryIds?: Set<string>;
+    scannerVersion: string;
+    selectedRepositoryIds: number[];
+    removedRepositoryIds?: number[];
+    queue: Map<string, HostedScanJobState>;
+    allowDraft?: boolean;
+    supportedActions?: string[];
+    manualRerun?: boolean;
+}
+export interface HostedPullRequestWebhookIntakeDecision {
+    accepted: boolean;
+    stage: HostedPullRequestWebhookIntakeStage;
+    reason?: HostedPullRequestWebhookIntakeRejectReason;
+    action?: string;
+    deliveryId?: string;
+    identity?: HostedScanIdentity;
+    job?: HostedScanJobDecision;
+    shouldQueueScanJob: boolean;
+    shouldFetchRepository: boolean;
+    shouldCreateCheckRun: boolean;
+    shouldCreatePrComment: false;
+    privacy: {
+        includesRawWebhookPayload: false;
+        includesUntrustedPrText: false;
+        includesRawSource: false;
+        includesRawDiffs: false;
+        includesSecrets: false;
+        includesCustomerPayloads: false;
+    };
+}
 export type InstallationScopeRejectReason = "installation_mismatch" | "repository_not_installed" | "repository_removed_from_installation";
 export interface InstallationScopeInput {
     identity: HostedScanIdentity;
@@ -77,6 +114,57 @@ export interface HostedScanJobDecision {
     shouldCreatePrComment: boolean;
 }
 export type HostedQueueJobStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
+export interface HostedScanQueueRecord {
+    key: string;
+    identity: HostedScanIdentity;
+    status: HostedQueueJobStatus;
+    attempt: number;
+    deliveryIds: string[];
+    createdAt: string;
+    updatedAt: string;
+    reportId?: string;
+}
+export interface HostedScanQueuePayload {
+    key: string;
+    identity: HostedScanIdentity;
+    deliveryId: string;
+    attempt: number;
+    requestedAt: string;
+    source: "github_pull_request";
+}
+export interface HostedScanQueueUpsertInput {
+    identity: HostedScanIdentity;
+    deliveryId: string;
+    requestedAt: string;
+    queue: Map<string, HostedScanQueueRecord>;
+    manualRerun?: boolean;
+    rawSource?: string;
+    rawDiff?: string;
+    secretValues?: string[];
+    untrustedPrText?: string;
+    customerPayload?: unknown;
+}
+export interface HostedScanQueueUpsertDecision {
+    key: string;
+    idempotent: true;
+    created: boolean;
+    reusedExistingJob: boolean;
+    existingStatus?: HostedQueueJobStatus;
+    attempt: number;
+    queueRecord: HostedScanQueueRecord;
+    queuePayload: HostedScanQueuePayload;
+    shouldEnqueueWorker: boolean;
+    shouldReuseCompletedReport: boolean;
+    shouldCreateCheckRun: boolean;
+    shouldCreatePrComment: false;
+    privacy: {
+        includesRawSource: false;
+        includesRawDiffs: false;
+        includesSecrets: false;
+        includesUntrustedPrText: false;
+        includesCustomerPayloads: false;
+    };
+}
 export type HostedQueueCleanupTrigger = "repository_removed" | "installation_deleted" | "repeated_cleanup";
 export interface HostedQueueCleanupJobState {
     key: string;
@@ -260,11 +348,13 @@ export declare const HOSTED_PRIVACY_DEFAULTS: {
     readonly deleteWorkerCheckout: "after_scan_completion";
 };
 export declare function verifyGitHubWebhook(input: GitHubWebhookInput): GitHubWebhookDecision;
+export declare function planHostedPullRequestWebhookIntake(input: HostedPullRequestWebhookIntakeInput): HostedPullRequestWebhookIntakeDecision;
 export declare function buildHostedScanIdentity(input: HostedScanIdentityInput): HostedScanIdentity;
 export declare function parseHostedPullRequestEvent(input: HostedPullRequestEventInput): HostedPullRequestEventDecision;
 export declare function authorizeInstallationTokenScope(input: InstallationScopeInput): InstallationScopeDecision;
 export declare function getHostedScanIdempotencyKey(identity: HostedScanIdentity): string;
 export declare function upsertHostedScanJob(queue: Map<string, HostedScanJobState>, input: HostedScanJobInput): HostedScanJobDecision;
+export declare function planHostedScanQueueUpsert(input: HostedScanQueueUpsertInput): HostedScanQueueUpsertDecision;
 export declare function getHostedQueueCleanupIdempotencyKey(input: {
     trigger: HostedQueueCleanupTrigger;
     installationId: number;

package/dist/hosted/contracts.js

@@ -42,6 +42,65 @@ export function verifyGitHubWebhook(input) {
         deliveryId
     };
 }
+export function planHostedPullRequestWebhookIntake(input) {
+    const signatureDecision = verifyGitHubWebhook({
+        payload: input.payload,
+        signatureHeader: input.signatureHeader,
+        signingKey: input.signingKey,
+        deliveryId: input.deliveryId,
+        seenDeliveryIds: input.seenDeliveryIds
+    });
+    if (!signatureDecision.accepted) {
+        return rejectPullRequestWebhookIntake("signature", signatureDecision.reason ?? "invalid_signature", input.deliveryId);
+    }
+    if (!input.deliveryId) {
+        return rejectPullRequestWebhookIntake("event", "missing_delivery_id");
+    }
+    const payload = parseJsonPayload(input.payload);
+    if (!payload) {
+        return rejectPullRequestWebhookIntake("payload", "invalid_json", input.deliveryId);
+    }
+    const eventDecision = parseHostedPullRequestEvent({
+        payload,
+        scannerVersion: input.scannerVersion,
+        allowDraft: input.allowDraft,
+        supportedActions: input.supportedActions
+    });
+    if (!eventDecision.accepted || !eventDecision.identity) {
+        return rejectPullRequestWebhookIntake("event", eventDecision.reason ?? "missing_required_field", input.deliveryId, eventDecision.action);
+    }
+    const scopeDecision = authorizeInstallationTokenScope({
+        identity: eventDecision.identity,
+        installationId: eventDecision.identity.installationId,
+        selectedRepositoryIds: input.selectedRepositoryIds,
+        removedRepositoryIds: input.removedRepositoryIds
+    });
+    if (!scopeDecision.authorized) {
+        return rejectPullRequestWebhookIntake("installation_scope", scopeDecision.reason ?? "repository_not_installed", input.deliveryId, eventDecision.action, eventDecision.identity);
+    }
+    const queueDecision = upsertHostedScanJob(input.queue, {
+        identity: eventDecision.identity,
+        deliveryId: input.deliveryId,
+        manualRerun: input.manualRerun
+    });
+    const checkRunOnlyQueueDecision = {
+        ...queueDecision,
+        shouldCreatePrComment: false
+    };
+    return {
+        accepted: true,
+        stage: "queue",
+        action: eventDecision.action,
+        deliveryId: input.deliveryId,
+        identity: eventDecision.identity,
+        job: checkRunOnlyQueueDecision,
+        shouldQueueScanJob: queueDecision.created || input.manualRerun === true,
+        shouldFetchRepository: queueDecision.shouldCreateCheckRun,
+        shouldCreateCheckRun: queueDecision.shouldCreateCheckRun,
+        shouldCreatePrComment: false,
+        privacy: hostedWebhookIntakePrivacy()
+    };
+}
 export function buildHostedScanIdentity(input) {
     return {
         installationId: input.installationId,
@@ -145,7 +204,7 @@ export function upsertHostedScanJob(queue, input) {
             reusedExistingReport: false,
             attempt: 1,
             shouldCreateCheckRun: true,
-            shouldCreatePrComment: true
+            shouldCreatePrComment: false
         };
     }
     if (!existing.deliveryIds.includes(input.deliveryId)) {
@@ -163,6 +222,76 @@ export function upsertHostedScanJob(queue, input) {
         shouldCreatePrComment: false
     };
 }
+export function planHostedScanQueueUpsert(input) {
+    const key = getHostedScanIdempotencyKey(input.identity);
+    const existing = input.queue.get(key);
+    if (!existing) {
+        const record = {
+            key,
+            identity: input.identity,
+            status: "queued",
+            attempt: 1,
+            deliveryIds: [input.deliveryId],
+            createdAt: input.requestedAt,
+            updatedAt: input.requestedAt
+        };
+        input.queue.set(key, record);
+        return {
+            key,
+            idempotent: true,
+            created: true,
+            reusedExistingJob: false,
+            attempt: record.attempt,
+            queueRecord: { ...record, deliveryIds: [...record.deliveryIds] },
+            queuePayload: createHostedScanQueuePayload(record, input.deliveryId, input.requestedAt),
+            shouldEnqueueWorker: true,
+            shouldReuseCompletedReport: false,
+            shouldCreateCheckRun: true,
+            shouldCreatePrComment: false,
+            privacy: hostedScanQueuePrivacy()
+        };
+    }
+    if (!existing.deliveryIds.includes(input.deliveryId)) {
+        existing.deliveryIds.push(input.deliveryId);
+    }
+    const existingStatus = existing.status;
+    if (input.manualRerun) {
+        existing.attempt += 1;
+        existing.status = "queued";
+        existing.updatedAt = input.requestedAt;
+        return {
+            key,
+            idempotent: true,
+            created: false,
+            reusedExistingJob: false,
+            existingStatus,
+            attempt: existing.attempt,
+            queueRecord: cloneHostedScanQueueRecord(existing),
+            queuePayload: createHostedScanQueuePayload(existing, input.deliveryId, input.requestedAt),
+            shouldEnqueueWorker: true,
+            shouldReuseCompletedReport: false,
+            shouldCreateCheckRun: true,
+            shouldCreatePrComment: false,
+            privacy: hostedScanQueuePrivacy()
+        };
+    }
+    existing.updatedAt = input.requestedAt;
+    return {
+        key,
+        idempotent: true,
+        created: false,
+        reusedExistingJob: true,
+        existingStatus,
+        attempt: existing.attempt,
+        queueRecord: cloneHostedScanQueueRecord(existing),
+        queuePayload: createHostedScanQueuePayload(existing, input.deliveryId, input.requestedAt),
+        shouldEnqueueWorker: false,
+        shouldReuseCompletedReport: existingStatus === "completed",
+        shouldCreateCheckRun: false,
+        shouldCreatePrComment: false,
+        privacy: hostedScanQueuePrivacy()
+    };
+}
 export function getHostedQueueCleanupIdempotencyKey(input) {
     return ["queue-cleanup", input.trigger, input.installationId, input.repositoryId ?? "all"].join(":");
 }
@@ -357,6 +486,65 @@ function rejectInstallationScope(reason) {
         reason
     };
 }
+function rejectPullRequestWebhookIntake(stage, reason, deliveryId, action, identity) {
+    return {
+        accepted: false,
+        stage,
+        reason,
+        ...(deliveryId === undefined ? {} : { deliveryId }),
+        ...(action === undefined ? {} : { action }),
+        ...(identity === undefined ? {} : { identity }),
+        shouldQueueScanJob: false,
+        shouldFetchRepository: false,
+        shouldCreateCheckRun: false,
+        shouldCreatePrComment: false,
+        privacy: hostedWebhookIntakePrivacy()
+    };
+}
+function hostedWebhookIntakePrivacy() {
+    return {
+        includesRawWebhookPayload: false,
+        includesUntrustedPrText: false,
+        includesRawSource: false,
+        includesRawDiffs: false,
+        includesSecrets: false,
+        includesCustomerPayloads: false
+    };
+}
+function createHostedScanQueuePayload(record, deliveryId, requestedAt) {
+    return {
+        key: record.key,
+        identity: record.identity,
+        deliveryId,
+        attempt: record.attempt,
+        requestedAt,
+        source: "github_pull_request"
+    };
+}
+function cloneHostedScanQueueRecord(record) {
+    return {
+        ...record,
+        identity: { ...record.identity },
+        deliveryIds: [...record.deliveryIds]
+    };
+}
+function hostedScanQueuePrivacy() {
+    return {
+        includesRawSource: false,
+        includesRawDiffs: false,
+        includesSecrets: false,
+        includesUntrustedPrText: false,
+        includesCustomerPayloads: false
+    };
+}
+function parseJsonPayload(payload) {
+    try {
+        return JSON.parse(Buffer.isBuffer(payload) ? payload.toString("utf8") : payload);
+    }
+    catch {
+        return undefined;
+    }
+}
 function queueCleanupMatches(job, input, scope) {
     if (job.identity.installationId !== input.installationId) {
         return 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.10.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.12.0` or a reviewed commit SHA when reproducibility is more important than automatic minor updates.
 
 ## PR Summary
 

package/docs/hosted-preimplementation-contracts.md

@@ -4,6 +4,49 @@ This document collects pure hosted contracts that can be tested before any hoste
 
 The helpers live in `src/hosted/contracts.ts` and are exported from `ai-saas-guard/hosted/contracts`.
 
+## Pull Request Webhook Intake Planner
+
+The pull request webhook intake planner is the first pure implementation slice for the future hosted service. It composes the earlier contracts into one safe order without starting a server or calling GitHub APIs.
+
+Default behavior:
+
+- verify `X-Hub-Signature-256` before parsing JSON, queueing work, authorizing token scope, or planning repository fetches
+- reject invalid, missing, malformed, or replayed signatures before payload parsing
+- parse only signed pull request payloads
+- derive scan identity from trusted GitHub event fields through the webhook event parser
+- authorize selected-repository installation scope before any fetch is planned
+- upsert one idempotent scan job by installation, repository, pull request, head SHA, and scanner version
+- default to check-run-only output; PR comments remain disabled for the first hosted slice
+
+Privacy boundaries:
+
+- return only trusted identity, queue metadata, stage, reason, and booleans needed by an ingress or worker
+- do not return raw webhook payloads, untrusted PR text, raw source, raw diffs, secrets, or customer payloads
+- keep local CLI usage independent from the hosted service
+
+The exported helper is `planHostedPullRequestWebhookIntake`. It is intentionally service-free: callers still need a real webhook server, queue provider, installation token lookup, worker checkout, scanner execution, compact report storage, and GitHub Checks API writer before any hosted environment exists.
+
+## Durable Scan Queue Planner
+
+The durable scan queue planner defines how the future hosted service should create or reuse scan jobs once a signed pull request webhook has produced trusted scan identity. It is a pure planner only: it does not connect to a queue provider, run a worker, fetch source, write reports, or call GitHub APIs.
+
+Default behavior:
+
+- compute the same logical scan key from installation ID, repository ID, pull request number, head SHA, and scanner version
+- create one queued job when no matching job exists
+- reuse existing queued, running, or completed jobs for duplicate deliveries
+- reuse completed compact reports instead of enqueueing duplicate worker work
+- allow manual reruns to increment `attempt` while keeping the same logical scan key
+- keep the first hosted slice check-run-only; PR comments remain disabled
+
+Queue payload boundaries:
+
+- include only scan identity, job key, delivery ID, attempt, requested time, and source
+- do not include raw source, raw diffs, secret values, untrusted PR text, webhook payload bodies, customer payloads, private URLs, or worker checkout paths
+- return safe queue metadata that can be stored by a durable queue without leaking source code
+
+The exported helper is `planHostedScanQueueUpsert`. It is intended to be the queue-provider-independent contract for the first real hosted queue implementation.
+
 ## 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.
@@ -139,6 +182,13 @@ These contracts do not:
 
 Automated tests must cover:
 
+- signed pull request webhook intake verifies signatures before JSON parsing or queueing
+- accepted pull request webhook intake queues one check-run-only scan request from trusted fields
+- rejected installation scope stops before repository fetch planning
+- durable scan queue planning creates one queued job for a new trusted scan key
+- duplicate deliveries reuse queued, running, and completed jobs without enqueueing duplicate worker work
+- completed duplicate jobs reuse compact reports
+- manual reruns increment attempt without changing the logical scan key
 - 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,10 +5,10 @@
 ## Current State
 
 - Package name: `ai-saas-guard`
-- Current version: `0.10.0`
+- Current version: `0.12.0`
 - npm registry state: published at <https://www.npmjs.com/package/ai-saas-guard>
 - First npm-published version: `0.1.1`
-- GitHub Release: `v0.10.0`
+- GitHub Release: `v0.12.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.10.0`.
+1. Create and review a release tag such as `v0.12.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

@@ -57,9 +57,9 @@ Implemented surfaces:
 - hosted operational release gate document requiring hosted CI, webhook replay, dependency and container scanning, privacy and retention verification, worker cleanup, monitoring and alerting, manual rollback, and incident response evidence before exposure
 - hosted uninstall and data deletion document defining repository removal, full app uninstall, compact report deletion, queue cancellation, audit record retention, repeated cleanup idempotency, and user-facing deletion wording
 - hosted pricing and packaging document defining open-source CLI boundaries, free/public repo hosted behavior, private repo hosted behavior, PR comments, saved reports, team policy, optional Launch Review, and no pentest/certification/full-audit claims
-- hosted pre-implementation contracts document, hosted compact report fixture, and pure helpers for queue-safe pull request event parsing from trusted GitHub event fields, bounded check-run summary rendering, idempotent queue cleanup planning, and worker checkout cleanup planning
+- hosted pre-implementation contracts document, hosted compact report fixture, and pure helpers for pull request webhook intake planning, durable scan queue upsert planning, queue-safe pull request event parsing from trusted GitHub event fields, bounded check-run summary rendering, idempotent queue cleanup planning, and worker checkout cleanup planning
 - implementation-ready hosted GitHub App permission contract for required permissions, optional PR comment permissions, selected repository installation, and out-of-scope broad permissions
-- pure hosted GitHub App contract helpers and tests for webhook verification, installation token scoping, scan queue idempotency, compact reports, and retention limits
+- pure hosted GitHub App contract helpers and tests for webhook intake order, webhook verification, installation token scoping, durable scan queue idempotency, compact reports, and retention limits
 - 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
@@ -113,7 +113,8 @@ GitHub Project:
 
 Current issue set:
 
-- No open roadmap issues after the hosted pre-implementation contract batch.
+- Closed hosted MVP issue: #24 webhook intake.
+- Open hosted MVP roadmap issues: #25 idempotent queue contract, #26 read-only worker checkout, #27 Check summaries, #28 retention/uninstall cleanup, and #29 hosted operational release gate.
 
 CI:
 
@@ -125,7 +126,7 @@ CI:
 Publishing:
 
 - npm package: `ai-saas-guard`
-- Current release line: `v0.10.0`
+- Current release line: `v0.12.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.
@@ -137,6 +138,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
 - GitHub Action wrapper
 - examples that contain only inert fake data
 - release-quality process docs

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

@@ -235,6 +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.
 - 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-saas-guard",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Repo-local launch-readiness scanner for AI-built SaaS apps.",
   "type": "module",
   "homepage": "https://github.com/zr9959/ai-saas-guard#readme",
@@ -52,7 +52,8 @@
     "docs",
     "dist",
     "examples",
-    "README.md"
+    "README.md",
+    "README.zh-CN.md"
   ],
   "license": "MIT",
   "devDependencies": {