ai-saas-guard 0.17.0 → 0.18.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.17.0`, `v0` |
-| npm package | `ai-saas-guard@0.17.0` |
+| Versioned Action tags | `v0.18.0`, `v0` |
+| npm package | `ai-saas-guard@0.18.0` |
 | npm publishing | Trusted Publisher/OIDC, no long-lived publish token |
 
 ## Quick Start
@@ -210,6 +210,8 @@ The hosted deployment model is documented in [docs/hosted-deployment-model.md](d
 
 The hosted service runtime is documented in [docs/hosted-service-runtime.md](docs/hosted-service-runtime.md). It exports `createHostedServiceRuntime` from `ai-saas-guard/hosted/service` and implements the provider-independent service core for signed webhook intake, idempotent queue upsert, read-only worker orchestration, compact report storage, Check Run publication adapters, and worker cleanup planning. It does not deploy a public hosted environment by itself.
 
+The hosted GitHub App deployment planner is documented in [docs/github-app-deployment.md](docs/github-app-deployment.md). It exports `planHostedGitHubAppDeployment` from `ai-saas-guard/hosted/github-app`, generates the least-privilege manifest for the first hosted slice, and blocks creation when the release gate, HTTPS URLs, container digest, secret references, permissions, or events are incomplete or unsafe.
+
 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.
@@ -222,7 +224,7 @@ A public hosted compact report schema fixture is available at [examples/hosted-c
 
 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 hosted contract helpers and runtime tests for webhook intake order, webhook verification, installation token scoping, durable queue idempotency, compact reports, retention limits, uninstall cleanup, repeated cleanup idempotency, scoped deletion planning, operational release gate blocking, and provider-independent hosted service orchestration. These helpers do not deploy a public hosted service.
+The repository also includes hosted contract helpers and runtime tests for webhook intake order, webhook verification, installation token scoping, durable queue idempotency, compact reports, retention limits, uninstall cleanup, repeated cleanup idempotency, scoped deletion planning, operational release gate blocking, provider-independent hosted service orchestration, and GitHub App deployment planning. These helpers do not deploy a public hosted service.
 
 Users should prefer the local CLI for private repositories, offline review, or no-account workflows where hosted code processing is not acceptable.
 
@@ -256,7 +258,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.17.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.18.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.17.0`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.17.0`。
+CLI 已发布到 npm：`ai-saas-guard@0.18.0`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.18.0`。
 
 | 模块 | 状态 |
 | --- | --- |
@@ -66,8 +66,8 @@ CLI 已发布到 npm：`ai-saas-guard@0.17.0`。GitHub Action 支持 `v0` 浮动
 | Markdown PR summary | 已可用 |
 | GitHub Action | 已可用 |
 | 项目配置 | `.ai-saas-guard.json` 支持规则开关、severity 覆盖和 fail threshold |
-| 当前版本 | `0.17.0` |
-| Action 标签 | `v0.17.0`、`v0` |
+| 当前版本 | `0.18.0` |
+| Action 标签 | `v0.18.0`、`v0` |
 | npm 发布 | GitHub Actions Trusted Publisher/OIDC，无需长期 npm token |
 
 ## 快速开始
@@ -243,6 +243,7 @@ jobs:
 相关文档：
 
 - [docs/github-app-design.md](docs/github-app-design.md)
+- [docs/github-app-deployment.md](docs/github-app-deployment.md)
 - [docs/hosted-first-service-slice.md](docs/hosted-first-service-slice.md)
 - [docs/hosted-deployment-model.md](docs/hosted-deployment-model.md)
 - [docs/hosted-service-runtime.md](docs/hosted-service-runtime.md)
@@ -257,6 +258,7 @@ jobs:
 - durable scan queue planner：同一个 trusted scan key 的 queued/running/completed job 会复用，不重复排 worker，也不会把源码、diff、secret 或 PR 正文放进队列 payload
 - worker read-only scan planner：只用 trusted identity 规划临时 worker checkout，要求 repository `contents: read`，固定运行 `ai-saas-guard pr-risk --json`，并忽略 PR 正文里的 repo 名、token scope 或命令
 - hosted service runtime：`ai-saas-guard/hosted/service` 导出 `createHostedServiceRuntime`，把签名 webhook intake、幂等 queue upsert、read-only worker 编排、compact report 存储、Check Run 发布 adapter 和 worker cleanup 串成可测试的服务核心；它本身不部署公开 hosted 环境
+- GitHub App deployment planner：`ai-saas-guard/hosted/github-app` 导出 `planHostedGitHubAppDeployment`，生成 first slice 最小权限 manifest，并在 release gate、HTTPS URL、container digest、secret 引用、permission 或 event 不安全时阻止创建
 - 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/github-app.d.ts

@@ -0,0 +1,69 @@
+export declare const HOSTED_GITHUB_APP_REQUIRED_PERMISSIONS: {
+    readonly contents: "read";
+    readonly pull_requests: "read";
+    readonly checks: "write";
+    readonly metadata: "read";
+};
+export declare const HOSTED_GITHUB_APP_EVENTS: readonly ["pull_request", "installation", "installation_repositories"];
+export type HostedGitHubAppPermissionName = keyof typeof HOSTED_GITHUB_APP_REQUIRED_PERMISSIONS;
+export type HostedGitHubAppPermissionValue = "read" | "write" | "none";
+export type HostedGitHubAppEvent = (typeof HOSTED_GITHUB_APP_EVENTS)[number];
+export interface HostedGitHubAppReleaseGateSummary {
+    shouldExposeHostedEnvironment: boolean;
+    blocked: boolean;
+    containerImageDigestRecorded: boolean;
+    missingEvidenceIds?: string[];
+    failedEvidenceIds?: string[];
+    staleEvidenceIds?: string[];
+    exceptionEvidenceIds?: string[];
+    releaseNotesCompliant?: boolean;
+}
+export interface HostedGitHubAppSecretRefs {
+    appId: string;
+    privateKey: string;
+    webhookSecret: string;
+}
+export interface HostedGitHubAppDeploymentInput {
+    appName: string;
+    homepageUrl: string;
+    webhookUrl: string;
+    environment: string;
+    containerImageDigest: string;
+    secretRefs: HostedGitHubAppSecretRefs;
+    releaseGate: HostedGitHubAppReleaseGateSummary;
+    setupUrl?: string;
+    callbackUrl?: string;
+    requestedPermissions?: Record<string, HostedGitHubAppPermissionValue>;
+    requestedEvents?: string[];
+    rawPrivateKey?: string;
+    rawWebhookSecret?: string;
+}
+export interface HostedGitHubAppManifest {
+    name: string;
+    url: string;
+    hook_attributes: {
+        url: string;
+        active: true;
+    };
+    redirect_url?: string;
+    setup_url?: string;
+    public: false;
+    default_permissions: typeof HOSTED_GITHUB_APP_REQUIRED_PERMISSIONS;
+    default_events: HostedGitHubAppEvent[];
+}
+export interface HostedGitHubAppDeploymentPlan {
+    readyToCreateGitHubApp: boolean;
+    blockedReasons: string[];
+    environment: string;
+    containerImageDigest: string;
+    manifest: HostedGitHubAppManifest;
+    requiredSecretRefs: string[];
+    deploymentSteps: string[];
+    privacy: {
+        includesPrivateKey: false;
+        includesWebhookSecret: false;
+        includesClientSecret: false;
+        includesCustomerPayloads: false;
+    };
+}
+export declare function planHostedGitHubAppDeployment(input: HostedGitHubAppDeploymentInput): HostedGitHubAppDeploymentPlan;

package/dist/hosted/github-app.js

@@ -0,0 +1,135 @@
+export const HOSTED_GITHUB_APP_REQUIRED_PERMISSIONS = {
+    contents: "read",
+    pull_requests: "read",
+    checks: "write",
+    metadata: "read"
+};
+export const HOSTED_GITHUB_APP_EVENTS = [
+    "pull_request",
+    "installation",
+    "installation_repositories"
+];
+export function planHostedGitHubAppDeployment(input) {
+    const blockedReasons = [
+        ...releaseGateBlockedReasons(input.releaseGate),
+        ...containerDigestBlockedReasons(input.containerImageDigest),
+        ...urlBlockedReasons("homepage_url", input.homepageUrl),
+        ...urlBlockedReasons("webhook_url", input.webhookUrl),
+        ...optionalUrlBlockedReasons("setup_url", input.setupUrl),
+        ...optionalUrlBlockedReasons("callback_url", input.callbackUrl),
+        ...secretRefBlockedReasons(input.secretRefs),
+        ...permissionBlockedReasons(input.requestedPermissions),
+        ...eventBlockedReasons(input.requestedEvents)
+    ];
+    const manifest = {
+        name: input.appName.trim() || "AI SaaS Guard Hosted",
+        url: input.homepageUrl,
+        hook_attributes: {
+            url: input.webhookUrl,
+            active: true
+        },
+        ...(input.callbackUrl ? { redirect_url: input.callbackUrl } : {}),
+        ...(input.setupUrl ? { setup_url: input.setupUrl } : {}),
+        public: false,
+        default_permissions: HOSTED_GITHUB_APP_REQUIRED_PERMISSIONS,
+        default_events: [...HOSTED_GITHUB_APP_EVENTS]
+    };
+    return {
+        readyToCreateGitHubApp: blockedReasons.length === 0,
+        blockedReasons,
+        environment: input.environment,
+        containerImageDigest: input.containerImageDigest,
+        manifest,
+        requiredSecretRefs: safeSecretRefs(input.secretRefs),
+        deploymentSteps: [
+            "Create the GitHub App from the generated least-privilege manifest.",
+            "Store the App ID, private key, and webhook secret in the platform secret manager.",
+            "Deploy webhook ingress and scan worker containers with the recorded image digest.",
+            "Run the hosted operational release gate against the deployed artifact before exposure."
+        ],
+        privacy: {
+            includesPrivateKey: false,
+            includesWebhookSecret: false,
+            includesClientSecret: false,
+            includesCustomerPayloads: false
+        }
+    };
+}
+function releaseGateBlockedReasons(gate) {
+    return gate.shouldExposeHostedEnvironment &&
+        !gate.blocked &&
+        gate.containerImageDigestRecorded &&
+        gate.releaseNotesCompliant !== false
+        ? []
+        : ["release_gate_blocked"];
+}
+function containerDigestBlockedReasons(containerImageDigest) {
+    return /^sha256:[a-f0-9]{64}$/i.test(containerImageDigest)
+        ? []
+        : ["invalid_container_image_digest"];
+}
+function urlBlockedReasons(name, value) {
+    return isSafeHttpsUrl(value) ? [] : [`invalid_${name}`];
+}
+function optionalUrlBlockedReasons(name, value) {
+    if (!value) {
+        return [];
+    }
+    return urlBlockedReasons(name, value);
+}
+function isSafeHttpsUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === "https:" && url.hostname !== "localhost" && url.hostname !== "127.0.0.1";
+    }
+    catch {
+        return false;
+    }
+}
+function secretRefBlockedReasons(secretRefs) {
+    const reasons = [];
+    for (const key of ["appId", "privateKey", "webhookSecret"]) {
+        const value = secretRefs[key];
+        if (!value.trim()) {
+            reasons.push(`missing_secret_ref:${key}`);
+            continue;
+        }
+        if (looksLikeRawSecretMaterial(value)) {
+            reasons.push(`raw_secret_material:${key}`);
+        }
+    }
+    return reasons;
+}
+function looksLikeRawSecretMaterial(value) {
+    return /-----BEGIN [A-Z ]*PRIVATE KEY-----|whsec_|gh[opurs]_|github_pat_/i.test(value);
+}
+function permissionBlockedReasons(requestedPermissions) {
+    if (!requestedPermissions) {
+        return [];
+    }
+    const reasons = [];
+    for (const permission of Object.keys(requestedPermissions).sort()) {
+        if (!(permission in HOSTED_GITHUB_APP_REQUIRED_PERMISSIONS)) {
+            reasons.push(`permission_not_allowed:${permission}`);
+            continue;
+        }
+        const requiredValue = HOSTED_GITHUB_APP_REQUIRED_PERMISSIONS[permission];
+        if (requestedPermissions[permission] !== requiredValue) {
+            reasons.push(`permission_not_allowed:${permission}`);
+        }
+    }
+    return reasons;
+}
+function eventBlockedReasons(requestedEvents) {
+    if (!requestedEvents) {
+        return [];
+    }
+    const allowedEvents = new Set(HOSTED_GITHUB_APP_EVENTS);
+    return [...new Set(requestedEvents)]
+        .filter((event) => !allowedEvents.has(event))
+        .sort()
+        .map((event) => `event_not_allowed:${event}`);
+}
+function safeSecretRefs(secretRefs) {
+    return [secretRefs.appId, secretRefs.privateKey, secretRefs.webhookSecret].filter((value) => value.trim() && !looksLikeRawSecretMaterial(value));
+}

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

package/docs/github-app-deployment.md

@@ -0,0 +1,79 @@
+# Hosted GitHub App Deployment
+
+This document defines the GitHub App deployment planner now implemented in `src/hosted/github-app.ts`.
+
+It does not create a GitHub App by itself. GitHub App creation still requires a real HTTPS webhook URL, a deployed hosted service artifact, platform secret storage, and a human owner or automation account with permission to create the app in GitHub. The planner makes those requirements explicit and blocks unsafe or incomplete deployment input.
+
+## What Exists
+
+The deployment planner exports `planHostedGitHubAppDeployment` from `ai-saas-guard/hosted/github-app`.
+
+It creates a least-privilege GitHub App manifest for the first hosted slice:
+
+- `contents: read`
+- `pull_requests: read`
+- `checks: write`
+- `metadata: read`
+
+Allowed events:
+
+- `pull_request`
+- `installation`
+- `installation_repositories`
+
+The manifest stays private by default and uses one active webhook URL.
+
+## Required Inputs
+
+A ready deployment plan requires:
+
+- app name
+- HTTPS homepage URL
+- HTTPS webhook URL
+- hosted environment name
+- `sha256:<digest>` container image digest
+- secret reference for GitHub App ID
+- secret reference for GitHub App private key
+- secret reference for webhook secret
+- hosted operational release gate decision that allows hosted exposure
+
+Secret references must be platform lookup names such as `platform-ref:github-app-key`, not raw secret values.
+
+## Blockers
+
+The planner blocks GitHub App creation when:
+
+- the hosted release gate is blocked
+- the container image digest is missing or malformed
+- URLs are not HTTPS
+- localhost URLs are used
+- required secret references are missing
+- raw private keys or webhook secrets are passed instead of secret references
+- requested permissions exceed the first-slice permission contract
+- requested events exceed the first-slice event contract
+
+## Privacy
+
+The deployment plan never returns:
+
+- private key material
+- webhook secret values
+- client secret values
+- customer payloads
+
+It returns only safe manifest fields, blocker IDs, environment metadata, container digest, secret reference names, and deployment steps.
+
+## Deployment Steps
+
+When `readyToCreateGitHubApp` is true:
+
+1. Create the GitHub App from the generated least-privilege manifest.
+2. Store the App ID, private key, and webhook secret in the platform secret manager.
+3. Deploy webhook ingress and scan worker containers with the recorded image digest.
+4. Run the hosted operational release gate against the deployed artifact before exposure.
+
+## Current Status
+
+The repository can now produce and validate the deployment plan, but it cannot honestly create a live GitHub App until a public hosted webhook URL, container image digest, and secret manager references exist.
+
+The next deployment stage should wire the hosted service runtime to a real platform queue, compact report store, GitHub installation authentication, and Checks API publisher.

package/docs/github-app-design.md

@@ -52,6 +52,8 @@ The hosted deployment model is scoped in [docs/hosted-deployment-model.md](hoste
 
 The hosted service runtime is scoped in [docs/hosted-service-runtime.md](hosted-service-runtime.md). It implements the provider-independent core for signed webhook intake, idempotent queue upsert, read-only worker orchestration, compact report storage, Check Run publication adapters, and worker cleanup planning. It does not deploy a public hosted environment by itself.
 
+The hosted GitHub App deployment planner is scoped in [docs/github-app-deployment.md](github-app-deployment.md). It generates the least-privilege first-slice manifest and blocks creation when release-gate evidence, HTTPS URLs, container digest, secret references, permissions, or events are incomplete or unsafe.
+
 The hosted operational release gate is scoped in [docs/hosted-operational-release-gate.md](hosted-operational-release-gate.md). It blocks hosted exposure unless CI, webhook replay, signature verification, token scoping, idempotency, privacy and retention, worker cleanup, monitoring, alerting, rollback, and incident response evidence are fresh for the release candidate.
 
 Hosted uninstall and data deletion behavior is scoped in [docs/hosted-uninstall-data-deletion.md](hosted-uninstall-data-deletion.md). It defines repository removal, full app uninstall, compact report deletion, queue cancellation, limited audit record retention, repeated cleanup idempotency, and user-facing deletion wording.

package/docs/npm-publishing.md

@@ -5,10 +5,10 @@
 ## Current State
 
 - Package name: `ai-saas-guard`
-- Current version: `0.17.0`
+- Current version: `0.18.0`
 - npm registry state: published at <https://www.npmjs.com/package/ai-saas-guard>
 - First npm-published version: `0.1.1`
-- GitHub Release: `v0.17.0`
+- GitHub Release: `v0.18.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.17.0`.
+1. Create and review a release tag such as `v0.18.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

@@ -58,9 +58,10 @@ Implemented surfaces:
 - 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 service runtime document and provider-independent runtime core for signed webhook intake, idempotent queue upsert, read-only worker orchestration, compact report storage, Check Run publication adapters, and worker cleanup planning
+- hosted GitHub App deployment planner document and least-privilege manifest planner for required permissions, events, HTTPS URLs, container digest, secret references, and release-gate checks
 - 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, and provider-independent service runtime orchestration
+- 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, and GitHub App deployment planning
 - 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
@@ -131,7 +132,7 @@ CI:
 Publishing:
 
 - npm package: `ai-saas-guard`
-- Current release line: `v0.17.0`
+- Current release line: `v0.18.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.17.0",
+  "version": "0.18.0",
   "description": "Repo-local launch-readiness scanner for AI-built SaaS apps.",
   "type": "module",
   "homepage": "https://github.com/zr9959/ai-saas-guard#readme",
@@ -37,6 +37,10 @@
     "./hosted/service": {
       "types": "./dist/hosted/service.d.ts",
       "default": "./dist/hosted/service.js"
+    },
+    "./hosted/github-app": {
+      "types": "./dist/hosted/github-app.d.ts",
+      "default": "./dist/hosted/github-app.js"
     }
   },
   "bin": {