ai-saas-guard 0.16.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.16.0`, `v0` |
-| npm package | `ai-saas-guard@0.16.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
@@ -208,19 +208,23 @@ The first hosted service slice is defined in [docs/hosted-first-service-slice.md
 
 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 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.
 
 Hosted pricing and packaging boundaries are documented in [docs/hosted-pricing-packaging.md](docs/hosted-pricing-packaging.md). Core local scanning stays useful without an account; hosted plans may add workflow convenience, saved reports, team policy, and optional human review, but they do not gate local CLI scanning.
 
-Hosted pre-implementation pure contracts are documented in [docs/hosted-preimplementation-contracts.md](docs/hosted-preimplementation-contracts.md). They now include a pull request webhook intake planner that verifies signatures before parsing or queueing, a durable scan queue planner that reuses queued, running, and completed jobs for the same trusted scan key, a worker read-only scan planner that fixes the CLI command and requires repository `contents: read`, and a Check Run publication planner that requires repository `checks: write` and builds bounded check-only payloads from compact reports. They also cover queue-safe webhook event parsing, bounded check-run summary rendering, idempotent queue cleanup planning, worker checkout cleanup planning, a retention/deletion cleanup planner, and an operational release gate evaluator that requires fresh CI, replay, static-check, dependency, container, cleanup, privacy, monitoring, rollback, incident-response, and release-cleanup evidence before hosted exposure. PR comments remain a later workflow or paid hosted feature, not part of the hosted MVP contract.
+Hosted pre-implementation pure contracts are documented in [docs/hosted-preimplementation-contracts.md](docs/hosted-preimplementation-contracts.md). They now include a pull request webhook intake planner that verifies signatures before parsing or queueing, a durable scan queue planner that reuses queued, running, and completed jobs for the same trusted scan key, a worker read-only scan planner that fixes the CLI command and requires repository `contents: read`, and a Check Run publication planner that requires repository `checks: write` and builds bounded check-only payloads from compact reports. They also cover queue-safe webhook event parsing, bounded check-run summary rendering, idempotent queue cleanup planning, worker checkout cleanup planning, a retention/deletion cleanup planner, and an operational release gate evaluator that requires fresh CI, replay, static-check, dependency, container, cleanup, privacy, monitoring, rollback, incident-response, and release-cleanup evidence before hosted exposure. The service runtime composes these contracts behind replaceable adapters. PR comments remain a later workflow or paid hosted feature, not part of the hosted MVP contract.
 
 A public hosted compact report schema fixture is available at [examples/hosted-compact-report.json](examples/hosted-compact-report.json). It is synthetic and public-safe: compact evidence only, no raw source, raw diffs, secrets, webhook payload bodies, customer payloads, private URLs, or worker checkout paths.
 
 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 intake order, webhook verification, installation token scoping, durable queue idempotency, compact reports, retention limits, uninstall cleanup, repeated cleanup idempotency, scoped deletion planning, and operational release gate blocking. These helpers do not implement or deploy a 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.
 
@@ -254,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.16.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.16.0`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.16.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.16.0`。GitHub Action 支持 `v0` 浮动
 | Markdown PR summary | 已可用 |
 | GitHub Action | 已可用 |
 | 项目配置 | `.ai-saas-guard.json` 支持规则开关、severity 覆盖和 fail threshold |
-| 当前版本 | `0.16.0` |
-| Action 标签 | `v0.16.0`、`v0` |
+| 当前版本 | `0.18.0` |
+| Action 标签 | `v0.18.0`、`v0` |
 | npm 发布 | GitHub Actions Trusted Publisher/OIDC，无需长期 npm token |
 
 ## 快速开始
@@ -243,8 +243,10 @@ 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)
 - [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)
@@ -255,6 +257,8 @@ 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 或命令
+- 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/dist/hosted/service.d.ts

@@ -0,0 +1,116 @@
+import { type CompactHostedFinding, type CompactHostedReport, type HostedCheckRunPublicationPlan, type HostedScanQueueRecord, type HostedScanQueueUpsertDecision, type HostedWorkerCheckoutCleanupPlan, type HostedWorkerReadOnlyScanPlan } from "./contracts.js";
+type RepositoryIdSource = Record<number, number[]> | Map<number, number[]>;
+export interface HostedServiceWebhookRequest {
+    payload: string | Buffer;
+    signatureHeader?: string;
+    deliveryId?: string;
+    manualRerun?: boolean;
+    allowDraft?: boolean;
+}
+export type HostedServiceWebhookStage = "signature" | "payload" | "event" | "installation_scope" | "queue";
+export interface HostedServiceWebhookResult {
+    accepted: boolean;
+    stage: HostedServiceWebhookStage;
+    reason?: string;
+    deliveryId?: string;
+    queueDecision?: HostedScanQueueUpsertDecision;
+    shouldFetchRepository: boolean;
+    shouldCreateCheckRun: boolean;
+    shouldCreatePrComment: false;
+    privacy: {
+        includesRawWebhookPayload: false;
+        includesUntrustedPrText: false;
+        includesRawSource: false;
+        includesRawDiffs: false;
+        includesSecrets: false;
+        includesCustomerPayloads: false;
+    };
+}
+export interface HostedServiceQueueAdapter {
+    records: Map<string, HostedScanQueueRecord>;
+}
+export interface HostedCompactReportStoreRecord {
+    id: string;
+    jobKey: string;
+    createdAt: string;
+    report: CompactHostedReport;
+}
+export interface HostedCompactReportStore {
+    records?: HostedCompactReportStoreRecord[];
+    save(record: HostedCompactReportStoreRecord): Promise<void> | void;
+}
+export interface HostedCheckRunRequest {
+    method: "POST";
+    endpoint: string;
+    payload: NonNullable<HostedCheckRunPublicationPlan["request"]>["payload"];
+}
+export interface HostedCheckRunPublisher {
+    requests?: HostedCheckRunRequest[];
+    publish(request: HostedCheckRunRequest): Promise<void> | void;
+}
+export interface HostedServiceScanRunnerResult {
+    summaryCounts: Record<string, number>;
+    findings: CompactHostedFinding[];
+    retentionDays?: number;
+    rawSource?: string;
+    rawDiff?: string;
+    secretValues?: string[];
+    customerPayload?: unknown;
+}
+export interface HostedServiceScanRunnerInput {
+    plan: HostedWorkerReadOnlyScanPlan & {
+        accepted: true;
+    };
+    queueRecord: HostedScanQueueRecord;
+}
+export type HostedServiceScanRunner = (input: HostedServiceScanRunnerInput) => Promise<HostedServiceScanRunnerResult> | HostedServiceScanRunnerResult;
+export interface HostedServiceRuntimeOptions {
+    signingKey: string | Buffer;
+    scannerVersion: string;
+    selectedRepositoryIdsByInstallation: RepositoryIdSource;
+    removedRepositoryIdsByInstallation?: RepositoryIdSource;
+    queue: HostedServiceQueueAdapter;
+    compactReportStore: HostedCompactReportStore;
+    checkRunPublisher: HostedCheckRunPublisher;
+    scanRunner: HostedServiceScanRunner;
+    now?: () => string;
+}
+export interface HostedServiceRuntime {
+    handlePullRequestWebhook(request: HostedServiceWebhookRequest): HostedServiceWebhookResult;
+    runNextQueuedScan(): Promise<HostedServiceWorkerResult>;
+}
+export type HostedServiceWorkerResult = {
+    processed: false;
+    reason: "empty_queue";
+} | {
+    processed: true;
+    status: "completed";
+    queueRecord: HostedScanQueueRecord;
+    workerPlan: HostedWorkerReadOnlyScanPlan & {
+        accepted: true;
+    };
+    report: CompactHostedReport;
+    checkRunPublication: HostedCheckRunPublicationPlan;
+    cleanup: HostedWorkerCheckoutCleanupPlan;
+} | {
+    processed: true;
+    status: "failed";
+    queueRecord: HostedScanQueueRecord;
+    reason?: string;
+    errorClass: "worker_plan_rejected" | "check_run_publication_rejected" | "scan_runner_failed";
+    workerPlan?: HostedWorkerReadOnlyScanPlan;
+    checkRunPublication?: HostedCheckRunPublicationPlan;
+    cleanup?: HostedWorkerCheckoutCleanupPlan;
+};
+export interface InMemoryHostedServiceAdapters {
+    queue: HostedServiceQueueAdapter;
+    compactReportStore: HostedCompactReportStore & {
+        records: HostedCompactReportStoreRecord[];
+    };
+    checkRunPublisher: HostedCheckRunPublisher & {
+        requests: HostedCheckRunRequest[];
+    };
+}
+export declare function createInMemoryHostedServiceAdapters(): InMemoryHostedServiceAdapters;
+export declare function createHostedServiceRuntime(options: HostedServiceRuntimeOptions): HostedServiceRuntime;
+export {};

package/dist/hosted/service.js

@@ -0,0 +1,250 @@
+import { authorizeInstallationTokenScope, createCompactHostedReport, createHostedWorkerCheckoutCleanupPlan, parseHostedPullRequestEvent, planHostedCheckRunPublication, planHostedScanQueueUpsert, planHostedWorkerReadOnlyScan, verifyGitHubWebhook } from "./contracts.js";
+export function createInMemoryHostedServiceAdapters() {
+    const compactReportRecords = [];
+    const checkRunRequests = [];
+    return {
+        queue: { records: new Map() },
+        compactReportStore: {
+            records: compactReportRecords,
+            save(record) {
+                compactReportRecords.push(record);
+            }
+        },
+        checkRunPublisher: {
+            requests: checkRunRequests,
+            publish(request) {
+                checkRunRequests.push(request);
+            }
+        }
+    };
+}
+export function createHostedServiceRuntime(options) {
+    const seenDeliveryIds = new Set();
+    const now = options.now ?? (() => new Date().toISOString());
+    return {
+        handlePullRequestWebhook(request) {
+            const signatureDecision = verifyGitHubWebhook({
+                payload: request.payload,
+                signatureHeader: request.signatureHeader,
+                signingKey: options.signingKey,
+                deliveryId: request.deliveryId,
+                seenDeliveryIds
+            });
+            if (!signatureDecision.accepted) {
+                return rejectWebhookRequest("signature", signatureDecision.reason ?? "invalid_signature", request.deliveryId);
+            }
+            if (!request.deliveryId) {
+                return rejectWebhookRequest("event", "missing_delivery_id");
+            }
+            const parsedPayload = parseWebhookPayload(request.payload);
+            if (!parsedPayload) {
+                return rejectWebhookRequest("payload", "invalid_json", request.deliveryId);
+            }
+            const eventDecision = parseHostedPullRequestEvent({
+                payload: parsedPayload,
+                scannerVersion: options.scannerVersion,
+                allowDraft: request.allowDraft
+            });
+            if (!eventDecision.accepted || !eventDecision.identity) {
+                return rejectWebhookRequest("event", eventDecision.reason ?? "missing_required_field", request.deliveryId);
+            }
+            const selectedRepositoryIds = repositoryIdsFor(options.selectedRepositoryIdsByInstallation, eventDecision.identity.installationId);
+            const removedRepositoryIds = repositoryIdsFor(options.removedRepositoryIdsByInstallation, eventDecision.identity.installationId);
+            const scopeDecision = authorizeInstallationTokenScope({
+                identity: eventDecision.identity,
+                installationId: eventDecision.identity.installationId,
+                selectedRepositoryIds,
+                removedRepositoryIds
+            });
+            if (!scopeDecision.authorized) {
+                return rejectWebhookRequest("installation_scope", scopeDecision.reason ?? "repository_not_installed", request.deliveryId);
+            }
+            const queueDecision = planHostedScanQueueUpsert({
+                identity: eventDecision.identity,
+                deliveryId: request.deliveryId,
+                requestedAt: now(),
+                queue: options.queue.records,
+                manualRerun: request.manualRerun
+            });
+            return {
+                accepted: true,
+                stage: "queue",
+                deliveryId: request.deliveryId,
+                queueDecision,
+                shouldFetchRepository: queueDecision.shouldEnqueueWorker,
+                shouldCreateCheckRun: queueDecision.shouldCreateCheckRun,
+                shouldCreatePrComment: false,
+                privacy: hostedServiceWebhookPrivacy()
+            };
+        },
+        async runNextQueuedScan() {
+            const queuedRecord = nextQueuedRecord(options.queue.records);
+            if (!queuedRecord) {
+                return { processed: false, reason: "empty_queue" };
+            }
+            const requestedAt = now();
+            queuedRecord.status = "running";
+            queuedRecord.updatedAt = requestedAt;
+            const selectedRepositoryIds = repositoryIdsFor(options.selectedRepositoryIdsByInstallation, queuedRecord.identity.installationId);
+            const removedRepositoryIds = repositoryIdsFor(options.removedRepositoryIdsByInstallation, queuedRecord.identity.installationId);
+            const workerPlan = planHostedWorkerReadOnlyScan({
+                identity: queuedRecord.identity,
+                jobKey: queuedRecord.key,
+                requestedAt,
+                installationId: queuedRecord.identity.installationId,
+                selectedRepositoryIds,
+                removedRepositoryIds,
+                installationTokenPermissions: { contents: "read" }
+            });
+            if (!workerPlan.accepted) {
+                queuedRecord.status = "failed";
+                queuedRecord.updatedAt = now();
+                return {
+                    processed: true,
+                    status: "failed",
+                    queueRecord: cloneQueueRecord(queuedRecord),
+                    reason: workerPlan.reason,
+                    errorClass: "worker_plan_rejected",
+                    workerPlan
+                };
+            }
+            const acceptedWorkerPlan = workerPlan;
+            try {
+                const scanResult = await options.scanRunner({
+                    plan: acceptedWorkerPlan,
+                    queueRecord: cloneQueueRecord(queuedRecord)
+                });
+                const report = createCompactHostedReport({
+                    identity: queuedRecord.identity,
+                    summaryCounts: scanResult.summaryCounts,
+                    findings: scanResult.findings,
+                    retentionDays: scanResult.retentionDays,
+                    rawDiff: scanResult.rawDiff,
+                    secretValues: scanResult.secretValues,
+                    customerPayload: scanResult.customerPayload
+                });
+                const reportId = `${queuedRecord.key}:${queuedRecord.attempt}`;
+                await options.compactReportStore.save({
+                    id: reportId,
+                    jobKey: queuedRecord.key,
+                    createdAt: now(),
+                    report
+                });
+                const checkRunPublication = planHostedCheckRunPublication({
+                    identity: queuedRecord.identity,
+                    report,
+                    jobKey: queuedRecord.key,
+                    requestedAt: now(),
+                    installationId: queuedRecord.identity.installationId,
+                    selectedRepositoryIds,
+                    removedRepositoryIds,
+                    installationTokenPermissions: { checks: "write" }
+                });
+                if (!checkRunPublication.accepted || !checkRunPublication.request) {
+                    queuedRecord.status = "failed";
+                    queuedRecord.updatedAt = now();
+                    return {
+                        processed: true,
+                        status: "failed",
+                        queueRecord: cloneQueueRecord(queuedRecord),
+                        reason: checkRunPublication.reason,
+                        errorClass: "check_run_publication_rejected",
+                        workerPlan: acceptedWorkerPlan,
+                        checkRunPublication
+                    };
+                }
+                await options.checkRunPublisher.publish(checkRunPublication.request);
+                const cleanup = createHostedWorkerCheckoutCleanupPlan({
+                    identity: queuedRecord.identity,
+                    jobKey: queuedRecord.key,
+                    terminalState: "success",
+                    finishedAt: now()
+                });
+                queuedRecord.status = "completed";
+                queuedRecord.reportId = reportId;
+                queuedRecord.updatedAt = now();
+                return {
+                    processed: true,
+                    status: "completed",
+                    queueRecord: cloneQueueRecord(queuedRecord),
+                    workerPlan: acceptedWorkerPlan,
+                    report,
+                    checkRunPublication,
+                    cleanup
+                };
+            }
+            catch {
+                const cleanup = createHostedWorkerCheckoutCleanupPlan({
+                    identity: queuedRecord.identity,
+                    jobKey: queuedRecord.key,
+                    terminalState: "failure",
+                    finishedAt: now()
+                });
+                queuedRecord.status = "failed";
+                queuedRecord.updatedAt = now();
+                return {
+                    processed: true,
+                    status: "failed",
+                    queueRecord: cloneQueueRecord(queuedRecord),
+                    errorClass: "scan_runner_failed",
+                    workerPlan: acceptedWorkerPlan,
+                    cleanup
+                };
+            }
+        }
+    };
+}
+function rejectWebhookRequest(stage, reason, deliveryId) {
+    return {
+        accepted: false,
+        stage,
+        reason,
+        ...(deliveryId === undefined ? {} : { deliveryId }),
+        shouldFetchRepository: false,
+        shouldCreateCheckRun: false,
+        shouldCreatePrComment: false,
+        privacy: hostedServiceWebhookPrivacy()
+    };
+}
+function hostedServiceWebhookPrivacy() {
+    return {
+        includesRawWebhookPayload: false,
+        includesUntrustedPrText: false,
+        includesRawSource: false,
+        includesRawDiffs: false,
+        includesSecrets: false,
+        includesCustomerPayloads: false
+    };
+}
+function parseWebhookPayload(payload) {
+    try {
+        return JSON.parse(Buffer.isBuffer(payload) ? payload.toString("utf8") : payload);
+    }
+    catch {
+        return undefined;
+    }
+}
+function repositoryIdsFor(source, installationId) {
+    if (!source) {
+        return [];
+    }
+    if (source instanceof Map) {
+        return source.get(installationId) ?? [];
+    }
+    return source[installationId] ?? [];
+}
+function nextQueuedRecord(records) {
+    for (const record of records.values()) {
+        if (record.status === "queued") {
+            return record;
+        }
+    }
+    return undefined;
+}
+function cloneQueueRecord(record) {
+    return {
+        ...record,
+        identity: { ...record.identity },
+        deliveryIds: [...record.deliveryIds]
+    };
+}

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.16.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

@@ -50,13 +50,17 @@ The first hosted service slice is scoped in [docs/hosted-first-service-slice.md]
 
 The hosted deployment model is scoped in [docs/hosted-deployment-model.md](hosted-deployment-model.md). It chooses containerized Node.js ingress and worker roles connected by a managed durable queue, with platform-managed secrets, structured redacted logs, installation/repository rate limits, rollback, and incident response paths.
 
+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.
 
 Hosted pricing and packaging boundaries are scoped in [docs/hosted-pricing-packaging.md](hosted-pricing-packaging.md). Core local scanning stays useful without an account; future hosted plans may charge for workflow convenience, saved reports, team policy, private repo hosted behavior, and optional human review, but not for access to useful local scanning.
 
-Hosted pre-implementation pure contracts are scoped in [docs/hosted-preimplementation-contracts.md](hosted-preimplementation-contracts.md). They define service-free helpers such as queue-safe pull request event parsing, bounded check-run summary rendering, idempotent queue cleanup planning, and worker checkout cleanup planning before any hosted ingress, queue, worker, or GitHub API integration is added.
+Hosted pre-implementation pure contracts are scoped in [docs/hosted-preimplementation-contracts.md](hosted-preimplementation-contracts.md). They define service-free helpers such as queue-safe pull request event parsing, bounded check-run summary rendering, idempotent queue cleanup planning, worker checkout cleanup planning, and operational release gate evaluation. The hosted service runtime composes those helpers behind replaceable adapters.
 
 The hosted compact report schema fixture is published at [examples/hosted-compact-report.json](../examples/hosted-compact-report.json). It is synthetic and public-safe, and it documents the compact evidence shape without raw source, raw diffs, secrets, customer payloads, or worker checkout paths.
 

package/docs/hosted-service-runtime.md

@@ -0,0 +1,86 @@
+# Hosted Service Runtime
+
+This document describes the first real hosted service runtime now implemented in `src/hosted/service.ts`.
+
+It is not a public hosted deployment announcement. The runtime is a provider-independent service core that can be wired to a real queue, compact report store, GitHub Checks API client, and scanner worker in the next deployment stage. It does not deploy a public hosted environment.
+
+## What Exists
+
+The runtime exports `createHostedServiceRuntime` from `ai-saas-guard/hosted/service`.
+
+It implements the first hosted service slice:
+
+- signed GitHub App pull request webhook intake
+- signature verification before JSON parsing, queue writes, repository lookup, token scope checks, or worker dispatch
+- trusted scan identity from GitHub event fields only
+- selected-repository installation authorization
+- idempotent durable queue upsert through an adapter
+- read-only worker planning
+- scan runner adapter boundary
+- compact report storage adapter boundary
+- Check Run publication adapter boundary
+- worker checkout cleanup planning after success or failure
+
+## Runtime Roles
+
+The service core keeps the two production roles from the deployment model:
+
+- `webhook-ingress`: call `handlePullRequestWebhook`.
+- `scan-worker`: call `runNextQueuedScan`.
+
+The runtime does not start an HTTP server by itself. That keeps framework and cloud choices out of the package while preserving the exact trust-boundary order the hosted service needs.
+
+## Adapter Boundaries
+
+Production deployments must provide durable adapters:
+
+- queue adapter backed by a managed durable queue or relational job table
+- compact report store backed by managed storage
+- Check Run publisher backed by GitHub App installation authentication
+- scan runner backed by isolated worker checkout and the deterministic CLI
+
+The exported `createInMemoryHostedServiceAdapters` is only for tests, local smoke runs, and examples. It is not a production queue or production data store.
+
+## Privacy
+
+The runtime intentionally returns safe planning and status objects only.
+
+It does not return:
+
+- raw webhook payloads
+- untrusted PR text
+- raw source
+- raw diffs
+- secrets
+- customer payloads
+- private checkout paths
+- low-level worker exception messages
+
+Compact reports continue to include only trusted identity, summary counts, rule IDs, compact evidence paths and line numbers, retention metadata, and model-training disabled status.
+
+## Failure Behavior
+
+Invalid webhooks stop at the signature stage and create no queue, worker, report, or Check Run side effects.
+
+Worker failures are recorded with a cleanup-safe `scan_runner_failed` error class. The runtime still plans worker checkout deletion, but it does not expose raw exception text or private checkout paths.
+
+## Tests
+
+`tests/hosted-service.test.mjs` covers:
+
+- a signed pull request webhook queues one idempotent job and the worker publishes one Check Run request
+- duplicate deliveries reuse the logical queue record
+- invalid signatures create no side effects
+- worker failures preserve cleanup behavior without leaking private paths or low-level errors
+
+## Deployment Status
+
+This runtime makes the hosted service implementation-ready inside the repository. A public hosted environment still requires the next deployment stage:
+
+- real GitHub App credentials
+- platform secret manager
+- managed queue
+- compact report storage
+- container image and digest
+- live monitoring and rollback evidence
+- hosted operational release gate evidence from the deployed artifact

package/docs/npm-publishing.md

@@ -5,10 +5,10 @@
 ## Current State
 
 - Package name: `ai-saas-guard`
-- Current version: `0.16.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.16.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.16.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

@@ -57,9 +57,11 @@ 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 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
-- pure 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, and operational release gate blocking
+- 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
@@ -130,7 +132,7 @@ CI:
 Publishing:
 
 - npm package: `ai-saas-guard`
-- Current release line: `v0.16.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.16.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",
@@ -33,6 +33,14 @@
     "./hosted/contracts": {
       "types": "./dist/hosted/contracts.d.ts",
       "default": "./dist/hosted/contracts.js"
+    },
+    "./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": {