ai-saas-guard 0.12.0 → 0.13.0

package/README.md

@@ -73,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.12.0`, `v0` |
-| npm package | `ai-saas-guard@0.12.0` |
+| Versioned Action tags | `v0.13.0`, `v0` |
+| npm package | `ai-saas-guard@0.13.0` |
 | npm publishing | Trusted Publisher/OIDC, no long-lived publish token |
 
 ## Quick Start
@@ -214,7 +214,7 @@ Hosted uninstall and data deletion behavior is documented in [docs/hosted-uninst
 
 Hosted pricing and packaging boundaries are documented in [docs/hosted-pricing-packaging.md](docs/hosted-pricing-packaging.md). Core local scanning stays useful without an account; hosted plans may add workflow convenience, saved reports, team policy, and optional human review, but they do not gate local CLI scanning.
 
-Hosted pre-implementation pure contracts are documented in [docs/hosted-preimplementation-contracts.md](docs/hosted-preimplementation-contracts.md). They now include a pull request webhook intake planner that verifies signatures before parsing or queueing, 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`.
+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, and a worker read-only scan planner that fixes the CLI command, requires repository `contents: read`, and ignores PR-authored repo names, token scopes, and commands. 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.
 
@@ -254,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.12.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.13.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

@@ -55,7 +55,7 @@ AI 能很快把一个 SaaS 从想法做成可运行的产品。真正难的是
 
 这个仓库是公开 GitHub 仓库。
 
-CLI 已发布到 npm：`ai-saas-guard@0.12.0`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.12.0`。
+CLI 已发布到 npm：`ai-saas-guard@0.13.0`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.13.0`。
 
 | 模块 | 状态 |
 | --- | --- |
@@ -66,8 +66,8 @@ CLI 已发布到 npm：`ai-saas-guard@0.12.0`。GitHub Action 支持 `v0` 浮动
 | Markdown PR summary | 已可用 |
 | GitHub Action | 已可用 |
 | 项目配置 | `.ai-saas-guard.json` 支持规则开关、severity 覆盖和 fail threshold |
-| 当前版本 | `0.12.0` |
-| Action 标签 | `v0.12.0`、`v0` |
+| 当前版本 | `0.13.0` |
+| Action 标签 | `v0.13.0`、`v0` |
 | npm 发布 | GitHub Actions Trusted Publisher/OIDC，无需长期 npm token |
 
 ## 快速开始
@@ -254,6 +254,7 @@ jobs:
 
 - pull request webhook intake planner：先验签，再解析 payload、生成可信 identity、校验 selected-repository scope，并默认只走 check-run-only 输出
 - durable scan queue planner：同一个 trusted scan key 的 queued/running/completed job 会复用，不重复排 worker，也不会把源码、diff、secret 或 PR 正文放进队列 payload
+- worker read-only scan planner：只用 trusted identity 规划临时 worker checkout，要求 repository `contents: read`，固定运行 `ai-saas-guard pr-risk --json`，并忽略 PR 正文里的 repo 名、token scope 或命令
 - webhook event parser
 - check-run summary renderer
 - queue cleanup planner

package/dist/hosted/contracts.d.ts

@@ -201,6 +201,81 @@ export interface HostedQueueCleanupPlan {
     deleteCustomerPayloads: false;
 }
 export type HostedWorkerCheckoutTerminalState = "success" | "failure" | "timeout" | "cancellation" | "cleanup_failure";
+export type HostedWorkerReadOnlyScanRejectReason = InstallationScopeRejectReason | "contents_read_permission_required";
+export interface HostedWorkerReadOnlyScanInput {
+    identity: HostedScanIdentity;
+    jobKey: string;
+    requestedAt: string;
+    installationId: number;
+    selectedRepositoryIds: number[];
+    removedRepositoryIds?: number[];
+    installationTokenPermissions: {
+        contents?: string;
+    };
+    checkoutRoot?: string;
+    untrustedRepositoryFullName?: string;
+    untrustedTokenPermissions?: unknown;
+    untrustedCommand?: string;
+    untrustedPrText?: string;
+    rawSource?: string;
+    rawDiff?: string;
+    secretValues?: string[];
+    customerPayload?: unknown;
+}
+export interface HostedWorkerReadOnlyScanPlan {
+    accepted: boolean;
+    reason?: HostedWorkerReadOnlyScanRejectReason;
+    jobKey: string;
+    requestedAt: string;
+    readOnly: true;
+    shouldFetchSource: boolean;
+    shouldRunCli: boolean;
+    shouldPersistRawSource: false;
+    shouldPersistRawDiffs: false;
+    shouldCreatePrComment: false;
+    installationTokenScope?: {
+        installationId: number;
+        repositoryId: number;
+        permissions: {
+            contents: "read";
+        };
+        selectedRepositoryOnly: true;
+    };
+    checkout?: {
+        repositoryId: number;
+        repositoryFullName: string;
+        pullRequestNumber: number;
+        baseSha: string;
+        targetCommitSha: string;
+        directoryScope: "temporary_worker_directory";
+        cleanupRequired: true;
+        returnsCheckoutPath: false;
+    };
+    cli?: {
+        command: "ai-saas-guard";
+        args: string[];
+        workingDirectory: "<worker-checkout>";
+        networkAccess: "disabled";
+        writeMode: "read_only";
+    };
+    output?: {
+        compactJsonOnly: true;
+        persistRawSource: false;
+        persistRawDiffs: false;
+        persistSecrets: false;
+        persistCustomerPayloads: false;
+    };
+    privacy: {
+        returnsCheckoutPath: false;
+        includesRawSource: false;
+        includesRawDiffs: false;
+        includesSecrets: false;
+        includesCustomerPayloads: false;
+        acceptsRepositoryIdentityFromPrText: false;
+        acceptsTokenScopeFromPrText: false;
+        acceptsCommandFromPrText: false;
+    };
+}
 export type HostedWorkerCheckoutCleanupAction = "delete_checkout" | "record_cleanup_failure";
 export interface HostedWorkerCheckoutCleanupInput {
     identity: HostedScanIdentity;
@@ -361,6 +436,7 @@ export declare function getHostedQueueCleanupIdempotencyKey(input: {
     repositoryId?: number;
 }): string;
 export declare function createHostedQueueCleanupPlan(input: HostedQueueCleanupPlanInput): HostedQueueCleanupPlan;
+export declare function planHostedWorkerReadOnlyScan(input: HostedWorkerReadOnlyScanInput): HostedWorkerReadOnlyScanPlan;
 export declare function createHostedWorkerCheckoutCleanupPlan(input: HostedWorkerCheckoutCleanupInput): HostedWorkerCheckoutCleanupPlan;
 export declare function resolveHostedRetentionDays(input?: {
     teamRequestedDays?: number;

package/dist/hosted/contracts.js

@@ -332,6 +332,69 @@ export function createHostedQueueCleanupPlan(input) {
         deleteCustomerPayloads: false
     };
 }
+export function planHostedWorkerReadOnlyScan(input) {
+    const scopeDecision = authorizeInstallationTokenScope({
+        identity: input.identity,
+        installationId: input.installationId,
+        selectedRepositoryIds: input.selectedRepositoryIds,
+        removedRepositoryIds: input.removedRepositoryIds
+    });
+    if (!scopeDecision.authorized) {
+        return rejectHostedWorkerReadOnlyScan(input, scopeDecision.reason ?? "repository_not_installed");
+    }
+    if (input.installationTokenPermissions.contents !== "read") {
+        return rejectHostedWorkerReadOnlyScan(input, "contents_read_permission_required");
+    }
+    return {
+        accepted: true,
+        jobKey: input.jobKey,
+        requestedAt: input.requestedAt,
+        readOnly: true,
+        shouldFetchSource: true,
+        shouldRunCli: true,
+        shouldPersistRawSource: false,
+        shouldPersistRawDiffs: false,
+        shouldCreatePrComment: false,
+        installationTokenScope: {
+            installationId: input.identity.installationId,
+            repositoryId: input.identity.repositoryId,
+            permissions: { contents: "read" },
+            selectedRepositoryOnly: true
+        },
+        checkout: {
+            repositoryId: input.identity.repositoryId,
+            repositoryFullName: input.identity.repositoryFullName,
+            pullRequestNumber: input.identity.pullRequestNumber,
+            baseSha: input.identity.baseSha,
+            targetCommitSha: input.identity.headSha,
+            directoryScope: "temporary_worker_directory",
+            cleanupRequired: true,
+            returnsCheckoutPath: false
+        },
+        cli: {
+            command: "ai-saas-guard",
+            args: [
+                "pr-risk",
+                "--root",
+                "<worker-checkout>",
+                "--base",
+                input.identity.baseSha,
+                "--json"
+            ],
+            workingDirectory: "<worker-checkout>",
+            networkAccess: "disabled",
+            writeMode: "read_only"
+        },
+        output: {
+            compactJsonOnly: true,
+            persistRawSource: false,
+            persistRawDiffs: false,
+            persistSecrets: false,
+            persistCustomerPayloads: false
+        },
+        privacy: hostedWorkerReadOnlyScanPrivacy()
+    };
+}
 export function createHostedWorkerCheckoutCleanupPlan(input) {
     const cleanupFailed = input.terminalState === "cleanup_failure";
     return {
@@ -537,6 +600,33 @@ function hostedScanQueuePrivacy() {
         includesCustomerPayloads: false
     };
 }
+function rejectHostedWorkerReadOnlyScan(input, reason) {
+    return {
+        accepted: false,
+        reason,
+        jobKey: input.jobKey,
+        requestedAt: input.requestedAt,
+        readOnly: true,
+        shouldFetchSource: false,
+        shouldRunCli: false,
+        shouldPersistRawSource: false,
+        shouldPersistRawDiffs: false,
+        shouldCreatePrComment: false,
+        privacy: hostedWorkerReadOnlyScanPrivacy()
+    };
+}
+function hostedWorkerReadOnlyScanPrivacy() {
+    return {
+        returnsCheckoutPath: false,
+        includesRawSource: false,
+        includesRawDiffs: false,
+        includesSecrets: false,
+        includesCustomerPayloads: false,
+        acceptsRepositoryIdentityFromPrText: false,
+        acceptsTokenScopeFromPrText: false,
+        acceptsCommandFromPrText: false
+    };
+}
 function parseJsonPayload(payload) {
     try {
         return JSON.parse(Buffer.isBuffer(payload) ? payload.toString("utf8") : payload);

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

package/docs/hosted-preimplementation-contracts.md

@@ -47,6 +47,29 @@ Queue payload boundaries:
 
 The exported helper is `planHostedScanQueueUpsert`. It is intended to be the queue-provider-independent contract for the first real hosted queue implementation.
 
+## Worker Read-Only Scan Planner
+
+The worker read-only scan planner defines how a future hosted worker should prepare a scan after the durable queue hands it a trusted job. It is a pure planner only: it does not request installation tokens, create directories, checkout repositories, run the CLI, persist reports, delete files, or call GitHub APIs.
+
+Default behavior:
+
+- authorize the same installation and selected-repository scope before any checkout is planned
+- require installation token permissions to be repository `contents: read`
+- derive repository ID, repository full name, pull request number, base SHA, head SHA, and scanner version only from trusted scan identity
+- plan checkout of the trusted head commit into a temporary worker directory
+- plan a fixed read-only CLI invocation: `ai-saas-guard pr-risk --root <worker-checkout> --base <baseSha> --json`
+- collect compact JSON output only
+- require checkout cleanup after every terminal worker state
+- keep PR comments disabled for the first hosted slice
+
+Trust boundaries:
+
+- ignore PR-authored repository names, token scopes, and commands
+- do not accept worker command, checkout target, installation ID, repository ID, repository name, or token permissions from PR title, body, comments, branch names, README, or code
+- do not return checkout paths, raw source, raw diffs, secret values, customer payloads, private URLs, or installation token values
+
+The exported helper is `planHostedWorkerReadOnlyScan`. It is intended to be the worker-provider-independent contract for the first real hosted worker 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.
@@ -189,6 +212,9 @@ Automated tests must cover:
 - 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
+- worker read-only scan planning requires repository `contents: read` permissions
+- worker read-only scan planning uses trusted identity for checkout target and fixed CLI command
+- worker read-only scan planning does not persist raw source, raw diffs, secrets, customer payloads, checkout paths, PR-authored commands, or PR-authored token scopes
 - 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.12.0`
+- Current version: `0.13.0`
 - npm registry state: published at <https://www.npmjs.com/package/ai-saas-guard>
 - First npm-published version: `0.1.1`
-- GitHub Release: `v0.12.0`
+- GitHub Release: `v0.13.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.12.0`.
+1. Create and review a release tag such as `v0.13.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,7 +57,7 @@ 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 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
+- 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, 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 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
@@ -114,19 +114,20 @@ GitHub Project:
 Current issue set:
 
 - 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.
+- Closed hosted MVP issue: #25 idempotent queue contract.
+- Open hosted MVP roadmap issues: #26 read-only worker checkout, #27 Check summaries, #28 retention/uninstall cleanup, and #29 hosted operational release gate.
 
 CI:
 
 - Workflow: `.github/workflows/ci.yml`
 - Runs on pull requests and pushes to `main`
 - Uses `permissions: contents: read`
-- Latest verified run for the hosted report fixture batch succeeded
+- Latest verified run for the hosted durable queue contract release succeeded
 
 Publishing:
 
 - npm package: `ai-saas-guard`
-- Current release line: `v0.12.0`
+- Current release line: `v0.13.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.12.0",
+  "version": "0.13.0",
   "description": "Repo-local launch-readiness scanner for AI-built SaaS apps.",
   "type": "module",
   "homepage": "https://github.com/zr9959/ai-saas-guard#readme",