ai-saas-guard 0.9.0 → 0.11.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 can turn an idea into a working SaaS quickly. The harder question is whether the app is ready for real users.
+
+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:
+
+- 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 command-line launch preflight for founders, solo builders, and reviewers shipping SaaS apps with AI coding tools.
+`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.
 
-It answers one narrow question:
+## What You Get
 
-> What changed in auth, billing, data access, secrets, MCP tools, or deploy config that deserves human review first?
+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.9.0`, `v0` |
-| npm package | `ai-saas-guard@0.9.0` |
+| Versioned Action tags | `v0.11.0`, `v0` |
+| npm package | `ai-saas-guard@0.11.0` |
 | npm publishing | Trusted Publisher/OIDC, no long-lived publish token |
 
 ## Quick Start
@@ -182,9 +204,23 @@ Use [docs/stripe-webhook-replay.md](docs/stripe-webhook-replay.md) after `check-
 
 See [docs/github-app-design.md](docs/github-app-design.md) for the proposed hosted GitHub App layer. The note covers least-privilege permissions, selected repositories, webhook verification, PR comments, check runs, privacy, data retention, prompt injection handling, and why the hosted app should not replace the local CLI.
 
+The first hosted service slice is defined in [docs/hosted-first-service-slice.md](docs/hosted-first-service-slice.md). It is intentionally check-run-only: signed GitHub App webhook intake, trusted scan identity, idempotent scan queueing, read-only worker behavior, compact report storage, and no PR comments, dashboard, billing, or AI summaries.
+
+The hosted deployment model is documented in [docs/hosted-deployment-model.md](docs/hosted-deployment-model.md). It chooses a containerized Node.js ingress and worker model with a managed durable queue, platform secret manager, structured redacted logs, installation/repository rate limits, and rollback/incident response paths.
+
+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.
+
+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, builds trusted scan identity, authorizes selected-repository scope, and defaults to check-run-only output. 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, 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.
 
@@ -218,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.9.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.11.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,293 @@
+<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.11.0`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.11.0`。
+
+| 模块 | 状态 |
+| --- | --- |
+| 公开 GitHub 仓库 | 已可用 |
+| npm CLI | 已发布为 `ai-saas-guard` |
+| 本地源码运行 | 已可用 |
+| JSON 和 SARIF 输出 | 已可用 |
+| Markdown PR summary | 已可用 |
+| GitHub Action | 已可用 |
+| 项目配置 | `.ai-saas-guard.json` 支持规则开关、severity 覆盖和 fail threshold |
+| 当前版本 | `0.11.0` |
+| Action 标签 | `v0.11.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 输出
+- 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

@@ -32,6 +32,57 @@ export interface HostedScanIdentity {
     headSha: string;
     scannerVersion: string;
 }
+export type PullRequestEventRejectReason = "unsupported_action" | "draft_pull_request" | "missing_required_field";
+export interface HostedPullRequestEventInput {
+    payload: unknown;
+    scannerVersion: string;
+    allowDraft?: boolean;
+    supportedActions?: string[];
+}
+export interface HostedPullRequestEventDecision {
+    accepted: boolean;
+    shouldQueueScanJob: boolean;
+    reason?: PullRequestEventRejectReason;
+    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;
@@ -62,6 +113,85 @@ export interface HostedScanJobDecision {
     shouldCreateCheckRun: boolean;
     shouldCreatePrComment: boolean;
 }
+export type HostedQueueJobStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
+export type HostedQueueCleanupTrigger = "repository_removed" | "installation_deleted" | "repeated_cleanup";
+export interface HostedQueueCleanupJobState {
+    key: string;
+    identity: HostedScanIdentity;
+    status: HostedQueueJobStatus;
+    attempt?: number;
+    deliveryIds?: string[];
+}
+export interface HostedQueueCleanupPlanInput {
+    trigger: HostedQueueCleanupTrigger;
+    installationId: number;
+    repositoryId?: number;
+    requestedAt: string;
+    jobs: HostedQueueCleanupJobState[];
+}
+export interface HostedQueueCleanupPlan {
+    trigger: HostedQueueCleanupTrigger;
+    scope: "repository" | "installation";
+    installationId: number;
+    repositoryId?: number;
+    requestedAt: string;
+    idempotencyKey: string;
+    idempotent: true;
+    matchedJobKeys: string[];
+    cancelQueuedJobKeys: string[];
+    requestRunningCancellationJobKeys: string[];
+    preserveTerminalJobKeys: string[];
+    keepUnmatchedJobKeys: string[];
+    cancelQueuedJobs: true;
+    requestRunningCancellation: true;
+    deleteRawSource: false;
+    deleteRawDiffs: false;
+    deleteSecrets: false;
+    deleteCustomerPayloads: false;
+}
+export type HostedWorkerCheckoutTerminalState = "success" | "failure" | "timeout" | "cancellation" | "cleanup_failure";
+export type HostedWorkerCheckoutCleanupAction = "delete_checkout" | "record_cleanup_failure";
+export interface HostedWorkerCheckoutCleanupInput {
+    identity: HostedScanIdentity;
+    jobKey: string;
+    terminalState: HostedWorkerCheckoutTerminalState;
+    finishedAt: string;
+    checkoutPath?: string;
+    cleanupError?: string;
+    rawSource?: string;
+    rawDiff?: string;
+    secretValues?: string[];
+    customerPayload?: unknown;
+}
+export interface HostedWorkerCheckoutCleanupPlan {
+    cleanupAction: HostedWorkerCheckoutCleanupAction;
+    shouldDeleteWorkerCheckout: boolean;
+    shouldRemoveCredentials: boolean;
+    shouldRemoveRawSource: boolean;
+    shouldRemoveRawDiffs: boolean;
+    shouldRemoveGeneratedArtifacts: boolean;
+    requiresOperatorReview: boolean;
+    preserveAuditRecord: true;
+    visibleUserMessage: string;
+    safeMetadata: {
+        jobKey: string;
+        installationId: number;
+        repositoryId: number;
+        repositoryFullName: string;
+        pullRequestNumber: number;
+        scannerVersion: string;
+        terminalState: HostedWorkerCheckoutTerminalState;
+        finishedAt: string;
+    };
+    privacy: {
+        returnsCheckoutPath: false;
+        returnsCleanupError: false;
+        returnsRawSource: false;
+        returnsRawDiffs: false;
+        returnsSecrets: false;
+        returnsCustomerPayloads: false;
+    };
+}
 export interface CompactHostedFinding {
     ruleId: string;
     severity: string;
@@ -98,17 +228,96 @@ export interface CompactHostedReport {
     modelTraining: "disabled";
     workerCheckoutDeletion: "after_scan_completion";
 }
+export type HostedCheckRunConclusion = "success" | "neutral" | "failure";
+export type HostedCheckRunSeverityThreshold = "critical" | "high" | "medium" | "low" | "info";
+export type HostedCheckRunAnnotationLevel = "notice" | "warning" | "failure";
+export interface HostedCheckRunSummaryInput {
+    report: CompactHostedReport;
+    failOnSeverity?: HostedCheckRunSeverityThreshold;
+    maxMarkdownChars?: number;
+}
+export interface HostedCheckRunAnnotation {
+    path: string;
+    startLine: number;
+    endLine: number;
+    annotationLevel: HostedCheckRunAnnotationLevel;
+    title: string;
+    message: string;
+}
+export interface HostedCheckRunSummary {
+    name: "AI SaaS Guard";
+    conclusion: HostedCheckRunConclusion;
+    output: {
+        title: string;
+        summary: string;
+        text: string;
+    };
+    annotations: HostedCheckRunAnnotation[];
+    localCliCommand: string;
+    privacy: {
+        includesRawSource: false;
+        includesRawDiffs: false;
+        includesSecrets: false;
+        includesCustomerPayloads: false;
+        modelTraining: "disabled";
+    };
+}
+export type HostedDeletionTrigger = "repository_removed" | "installation_deleted" | "repeated_cleanup";
+export interface HostedDeletionPlanInput {
+    trigger: HostedDeletionTrigger;
+    installationId: number;
+    repositoryId?: number;
+    requestedAt: string;
+    auditRecordRetentionDays?: number;
+}
+export interface HostedDeletionPlan {
+    trigger: HostedDeletionTrigger;
+    scope: "repository" | "installation";
+    installationId: number;
+    repositoryId?: number;
+    requestedAt: string;
+    idempotencyKey: string;
+    idempotent: true;
+    deleteCompactReports: true;
+    cancelQueuedJobs: true;
+    deleteWorkerCheckouts: true;
+    deleteRawSource: false;
+    deleteRawDiffs: false;
+    deleteSecrets: false;
+    deleteCustomerPayloads: false;
+    deleteGitHubOwnedCheckRuns: false;
+    preserveAuditRecord: true;
+    auditRecordRetentionDays: number;
+    visibleUserMessage: string;
+}
 export declare const HOSTED_PRIVACY_DEFAULTS: {
     readonly retentionDays: 30;
+    readonly auditRecordRetentionDays: 90;
     readonly modelTraining: "disabled";
     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 getHostedQueueCleanupIdempotencyKey(input: {
+    trigger: HostedQueueCleanupTrigger;
+    installationId: number;
+    repositoryId?: number;
+}): string;
+export declare function createHostedQueueCleanupPlan(input: HostedQueueCleanupPlanInput): HostedQueueCleanupPlan;
+export declare function createHostedWorkerCheckoutCleanupPlan(input: HostedWorkerCheckoutCleanupInput): HostedWorkerCheckoutCleanupPlan;
 export declare function resolveHostedRetentionDays(input?: {
     teamRequestedDays?: number;
 }): number;
 export declare function createCompactHostedReport(input: CompactHostedReportInput): CompactHostedReport;
+export declare function createHostedCheckRunSummary(input: HostedCheckRunSummaryInput): HostedCheckRunSummary;
+export declare function getHostedDeletionIdempotencyKey(input: {
+    trigger: HostedDeletionTrigger;
+    installationId: number;
+    repositoryId?: number;
+}): string;
+export declare function createHostedDeletionPlan(input: HostedDeletionPlanInput): HostedDeletionPlan;