ai-saas-guard 0.19.0 → 0.20.0

package/README.md

@@ -73,10 +73,11 @@ 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.19.0`, `v0` |
-| npm package | `ai-saas-guard@0.19.0` |
+| Versioned Action tags | `v0.20.0`, `v0` |
+| npm package | `ai-saas-guard@0.20.0` |
 | npm publishing | Trusted Publisher/OIDC, no long-lived publish token |
 | Runtime hardening | Per-file and total text scan caps, escaped markdown evidence, stricter hosted deployment blockers |
+| Hosted production adapters | GitHub App JWT signing, installation-token request planning, bounded worker execution, and terminal-state cleanup planning |
 
 ## Quick Start
 
@@ -213,13 +214,15 @@ The hosted service runtime is documented in [docs/hosted-service-runtime.md](doc
 
 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, public HTTPS URLs, container digest, secret references, raw secret inputs, permissions, or events are incomplete or unsafe.
 
+The hosted production adapter layer is documented in [docs/hosted-production-adapters.md](docs/hosted-production-adapters.md). It exports `createHostedGitHubAppJwt`, `planHostedGitHubInstallationTokenRequest`, and `planHostedProductionWorkerExecution` from `ai-saas-guard/hosted/production-adapters`. It adds RS256 GitHub App JWT generation, selected-repository installation-token request plans, separate worker and Check Run token scopes, a fixed read-only worker command, bounded timeout and output budgets, compact JSON-only output, and cleanup plans for success, failure, timeout, and cancellation. It still does not expose a public hosted service by itself.
+
 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. 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.
+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, an operational release gate evaluator, and the production adapter plans needed for GitHub App auth and bounded worker execution. 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.
 
@@ -259,7 +262,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.19.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.20.0` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
 
 ```yaml
 name: ai-saas-guard
@@ -389,7 +392,8 @@ Open-source core:
 
 Near-term priorities:
 
-- GitHub App implementation should wait until the hosted design note's open questions and implementation gate are answered.
+- Wire the hosted production adapters to a real provider queue, secret manager, compact report store, and GitHub Checks API client.
+- Keep hosted exposure blocked until the operational release gate has fresh evidence from a deployed artifact.
 
 Potential paid layer later:
 

package/README.zh-CN.md

@@ -55,7 +55,7 @@ AI 能很快把一个 SaaS 从想法做成可运行的产品。真正难的是
 
 这个仓库是公开 GitHub 仓库。
 
-CLI 已发布到 npm：`ai-saas-guard@0.19.0`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.19.0`。
+CLI 已发布到 npm：`ai-saas-guard@0.20.0`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.20.0`。
 
 | 模块 | 状态 |
 | --- | --- |
@@ -66,10 +66,11 @@ CLI 已发布到 npm：`ai-saas-guard@0.19.0`。GitHub Action 支持 `v0` 浮动
 | Markdown PR summary | 已可用 |
 | GitHub Action | 已可用 |
 | 项目配置 | `.ai-saas-guard.json` 支持规则开关、severity 覆盖和 fail threshold |
-| 当前版本 | `0.19.0` |
-| Action 标签 | `v0.19.0`、`v0` |
+| 当前版本 | `0.20.0` |
+| Action 标签 | `v0.20.0`、`v0` |
 | npm 发布 | GitHub Actions Trusted Publisher/OIDC，无需长期 npm token |
 | 运行时加固 | 单文件和总扫描文本预算、markdown evidence 转义、更严格的 hosted deployment 阻断 |
+| Hosted production adapters | GitHub App JWT 签名、installation-token 请求规划、有边界的 worker 执行和终态 cleanup 规划 |
 
 ## 快速开始
 
@@ -249,6 +250,7 @@ jobs:
 - [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-production-adapters.md](docs/hosted-production-adapters.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)
@@ -261,6 +263,7 @@ jobs:
 - 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 引用、原始 secret 输入、permission 或 event 不安全时阻止创建
+- Hosted production adapter layer：`ai-saas-guard/hosted/production-adapters` 导出 `createHostedGitHubAppJwt`、`planHostedGitHubInstallationTokenRequest` 和 `planHostedProductionWorkerExecution`，用于 GitHub App RS256 JWT、selected-repository installation token 请求规划、worker/check-run 分离 token scope、固定只读 worker 命令、timeout/output 预算、compact JSON-only 输出，以及 success/failure/timeout/cancellation 的 cleanup 规划；它本身仍然不部署公开 hosted 服务
 - 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
@@ -270,7 +273,7 @@ jobs:
 - operational release gate evaluator：检查 hosted 暴露前是否具备 fresh CI、webhook replay、workflow static check、dependency/container scan、cleanup、privacy、monitoring、rollback、incident response 和 release cleanup 证据；缺任何 P0 证据都会阻止 hosted exposure
 - hosted compact report fixture：[examples/hosted-compact-report.json](examples/hosted-compact-report.json)
 
-这些 helper 不会启动服务、不会调用 GitHub API、不会请求 installation token、不会真实写 check run、不会发 PR comment，也不会上传源码。
+这些 helper 不会启动服务、不会直接调用 GitHub API、不会持久化 installation token、不会真实写 check run、不会发 PR comment，也不会上传源码。
 
 ## 它不是什么
 

package/dist/hosted/production-adapters.d.ts

@@ -0,0 +1,143 @@
+import { type KeyObject } from "node:crypto";
+import { type HostedScanIdentity, type HostedWorkerCheckoutCleanupPlan, type HostedWorkerReadOnlyScanPlan } from "./contracts.js";
+export declare const HOSTED_GITHUB_API_VERSION = "2026-03-10";
+export declare const HOSTED_GITHUB_APP_JWT_MAX_TTL_SECONDS = 600;
+export declare const HOSTED_GITHUB_APP_JWT_CLOCK_SKEW_SECONDS = 60;
+export declare const HOSTED_WORKER_MAX_TIMEOUT_MS = 600000;
+export declare const HOSTED_WORKER_DEFAULT_TIMEOUT_MS = 300000;
+export declare const HOSTED_WORKER_MAX_OUTPUT_BYTES = 1048576;
+export type HostedGitHubInstallationTokenPurpose = "worker_checkout" | "check_run_publication" | "first_slice";
+export interface HostedGitHubAppJwtInput {
+    appId: string | number;
+    privateKey: string | Buffer | KeyObject;
+    nowSeconds?: number;
+    ttlSeconds?: number;
+    clockSkewSeconds?: number;
+}
+export interface HostedGitHubAppJwt {
+    token: string;
+    algorithm: "RS256";
+    issuer: string;
+    issuedAt: number;
+    expiresAt: number;
+    maxTtlSeconds: typeof HOSTED_GITHUB_APP_JWT_MAX_TTL_SECONDS;
+    privacy: {
+        includesPrivateKey: false;
+    };
+}
+export interface HostedGitHubInstallationTokenRequestInput {
+    installationId: number;
+    repositoryId: number;
+    purpose: HostedGitHubInstallationTokenPurpose;
+    requestedAt: string;
+    apiBaseUrl?: string;
+    apiVersion?: string;
+    appJwt?: string;
+    rawPrivateKey?: string;
+    rawInstallationToken?: string;
+}
+export interface HostedGitHubInstallationTokenRequestPlan {
+    readyToRequestToken: boolean;
+    blockedReasons: string[];
+    purpose: HostedGitHubInstallationTokenPurpose;
+    requestedAt: string;
+    request: {
+        method: "POST";
+        url: string;
+        endpoint: string;
+        headers: {
+            accept: "application/vnd.github+json";
+            "x-github-api-version": string;
+        };
+        authorization: "runtime_bearer_app_jwt";
+        body: {
+            repository_ids: number[];
+            permissions: Record<string, "read" | "write">;
+        };
+    };
+    responseHandling: {
+        tokenType: "installation_access_token";
+        persistToken: false;
+        cacheUntilExpiresAt: true;
+        redactTokenInLogs: true;
+    };
+    privacy: {
+        includesAppJwt: false;
+        includesInstallationToken: false;
+        includesPrivateKey: false;
+        includesCustomerPayloads: false;
+    };
+}
+export interface HostedProductionWorkerExecutionInput {
+    identity: HostedScanIdentity;
+    jobKey: string;
+    requestedAt: string;
+    selectedRepositoryIds: number[];
+    removedRepositoryIds?: number[];
+    temporaryCheckoutRoot?: string;
+    workerTimeoutMs?: number;
+    maxOutputBytes?: number;
+    rawSource?: string;
+    rawDiff?: string;
+    secretValues?: string[];
+    customerPayload?: unknown;
+}
+export interface HostedProductionWorkerExecutionPlan {
+    readyToRunWorker: boolean;
+    blockedReasons: string[];
+    jobKey: string;
+    requestedAt: string;
+    workerPlan: HostedWorkerReadOnlyScanPlan;
+    checkoutTokenRequest: HostedGitHubInstallationTokenRequestPlan;
+    checkRunTokenRequest: HostedGitHubInstallationTokenRequestPlan;
+    execution: {
+        commandSource: "trusted_runtime_plan";
+        timeoutMs: number;
+        maxOutputBytes: number;
+        cancellation: "supported";
+        networkAccess: "disabled";
+        writeMode: "read_only";
+        shell: "disabled";
+    };
+    output: {
+        compactJsonOnly: true;
+        persistRawSource: false;
+        persistRawDiffs: false;
+        persistSecrets: false;
+        persistCustomerPayloads: false;
+    };
+    cleanup: {
+        success: HostedWorkerCheckoutCleanupPlan;
+        failure: HostedWorkerCheckoutCleanupPlan;
+        timeout: HostedWorkerCheckoutCleanupPlan;
+        cancellation: HostedWorkerCheckoutCleanupPlan;
+    };
+    privacy: {
+        includesTemporaryCheckoutRoot: false;
+        includesRawSource: false;
+        includesRawDiffs: false;
+        includesSecrets: false;
+        includesCustomerPayloads: false;
+        includesAppJwt: false;
+        includesInstallationToken: false;
+        acceptsCommandFromPrText: false;
+    };
+}
+export interface HostedProductionSecretProvider {
+    getSecret(ref: string): Promise<string>;
+}
+export interface HostedProductionInstallationTokenRequester {
+    requestInstallationToken(plan: HostedGitHubInstallationTokenRequestPlan, appJwt: HostedGitHubAppJwt): Promise<{
+        token: string;
+        expiresAt: string;
+    }>;
+}
+export interface HostedProductionWorkerAdapter {
+    runReadOnlyCli(plan: HostedProductionWorkerExecutionPlan): Promise<{
+        stdout: string;
+        exitCode: number;
+    }>;
+}
+export declare function createHostedGitHubAppJwt(input: HostedGitHubAppJwtInput): HostedGitHubAppJwt;
+export declare function planHostedGitHubInstallationTokenRequest(input: HostedGitHubInstallationTokenRequestInput): HostedGitHubInstallationTokenRequestPlan;
+export declare function planHostedProductionWorkerExecution(input: HostedProductionWorkerExecutionInput): HostedProductionWorkerExecutionPlan;

package/dist/hosted/production-adapters.js

@@ -0,0 +1,226 @@
+import { createSign } from "node:crypto";
+import { createHostedWorkerCheckoutCleanupPlan, planHostedWorkerReadOnlyScan } from "./contracts.js";
+export const HOSTED_GITHUB_API_VERSION = "2026-03-10";
+export const HOSTED_GITHUB_APP_JWT_MAX_TTL_SECONDS = 600;
+export const HOSTED_GITHUB_APP_JWT_CLOCK_SKEW_SECONDS = 60;
+export const HOSTED_WORKER_MAX_TIMEOUT_MS = 600_000;
+export const HOSTED_WORKER_DEFAULT_TIMEOUT_MS = 300_000;
+export const HOSTED_WORKER_MAX_OUTPUT_BYTES = 1_048_576;
+export function createHostedGitHubAppJwt(input) {
+    const nowSeconds = normalizeUnixSeconds(input.nowSeconds, Math.floor(Date.now() / 1000));
+    const ttlSeconds = clampPositiveInteger(input.ttlSeconds, HOSTED_GITHUB_APP_JWT_MAX_TTL_SECONDS, HOSTED_GITHUB_APP_JWT_MAX_TTL_SECONDS);
+    const clockSkewSeconds = clampPositiveInteger(input.clockSkewSeconds, HOSTED_GITHUB_APP_JWT_CLOCK_SKEW_SECONDS, HOSTED_GITHUB_APP_JWT_CLOCK_SKEW_SECONDS);
+    const issuedAt = nowSeconds - clockSkewSeconds;
+    const expiresAt = nowSeconds + ttlSeconds;
+    const issuer = String(input.appId);
+    const header = { typ: "JWT", alg: "RS256" };
+    const payload = { iat: issuedAt, exp: expiresAt, iss: issuer };
+    const signingInput = `${base64UrlJson(header)}.${base64UrlJson(payload)}`;
+    const signature = createSign("RSA-SHA256")
+        .update(signingInput)
+        .end()
+        .sign(input.privateKey)
+        .toString("base64url");
+    return {
+        token: `${signingInput}.${signature}`,
+        algorithm: "RS256",
+        issuer,
+        issuedAt,
+        expiresAt,
+        maxTtlSeconds: HOSTED_GITHUB_APP_JWT_MAX_TTL_SECONDS,
+        privacy: {
+            includesPrivateKey: false
+        }
+    };
+}
+export function planHostedGitHubInstallationTokenRequest(input) {
+    const blockedReasons = [
+        ...installationTokenInputBlockedReasons(input),
+        ...safeApiUrlBlockedReasons(input.apiBaseUrl)
+    ];
+    const apiBaseUrl = normalizeApiBaseUrl(input.apiBaseUrl);
+    const endpoint = `/app/installations/${input.installationId}/access_tokens`;
+    return {
+        readyToRequestToken: blockedReasons.length === 0,
+        blockedReasons,
+        purpose: input.purpose,
+        requestedAt: input.requestedAt,
+        request: {
+            method: "POST",
+            url: `${apiBaseUrl}${endpoint}`,
+            endpoint,
+            headers: {
+                accept: "application/vnd.github+json",
+                "x-github-api-version": input.apiVersion?.trim() || HOSTED_GITHUB_API_VERSION
+            },
+            authorization: "runtime_bearer_app_jwt",
+            body: {
+                repository_ids: [input.repositoryId],
+                permissions: permissionsForPurpose(input.purpose)
+            }
+        },
+        responseHandling: {
+            tokenType: "installation_access_token",
+            persistToken: false,
+            cacheUntilExpiresAt: true,
+            redactTokenInLogs: true
+        },
+        privacy: {
+            includesAppJwt: false,
+            includesInstallationToken: false,
+            includesPrivateKey: false,
+            includesCustomerPayloads: false
+        }
+    };
+}
+export function planHostedProductionWorkerExecution(input) {
+    const workerPlan = planHostedWorkerReadOnlyScan({
+        identity: input.identity,
+        jobKey: input.jobKey,
+        requestedAt: input.requestedAt,
+        installationId: input.identity.installationId,
+        selectedRepositoryIds: input.selectedRepositoryIds,
+        removedRepositoryIds: input.removedRepositoryIds,
+        installationTokenPermissions: { contents: "read" }
+    });
+    const checkoutTokenRequest = planHostedGitHubInstallationTokenRequest({
+        installationId: input.identity.installationId,
+        repositoryId: input.identity.repositoryId,
+        purpose: "worker_checkout",
+        requestedAt: input.requestedAt
+    });
+    const checkRunTokenRequest = planHostedGitHubInstallationTokenRequest({
+        installationId: input.identity.installationId,
+        repositoryId: input.identity.repositoryId,
+        purpose: "check_run_publication",
+        requestedAt: input.requestedAt
+    });
+    const blockedReasons = [
+        ...workerPlanBlockedReasons(workerPlan),
+        ...prefixBlockedReasons("checkout_token", checkoutTokenRequest.blockedReasons),
+        ...prefixBlockedReasons("check_run_token", checkRunTokenRequest.blockedReasons)
+    ];
+    return {
+        readyToRunWorker: blockedReasons.length === 0,
+        blockedReasons,
+        jobKey: input.jobKey,
+        requestedAt: input.requestedAt,
+        workerPlan,
+        checkoutTokenRequest,
+        checkRunTokenRequest,
+        execution: {
+            commandSource: "trusted_runtime_plan",
+            timeoutMs: clampPositiveInteger(input.workerTimeoutMs, HOSTED_WORKER_DEFAULT_TIMEOUT_MS, HOSTED_WORKER_MAX_TIMEOUT_MS),
+            maxOutputBytes: clampPositiveInteger(input.maxOutputBytes, HOSTED_WORKER_MAX_OUTPUT_BYTES, HOSTED_WORKER_MAX_OUTPUT_BYTES),
+            cancellation: "supported",
+            networkAccess: "disabled",
+            writeMode: "read_only",
+            shell: "disabled"
+        },
+        output: {
+            compactJsonOnly: true,
+            persistRawSource: false,
+            persistRawDiffs: false,
+            persistSecrets: false,
+            persistCustomerPayloads: false
+        },
+        cleanup: {
+            success: cleanupPlan(input, "success"),
+            failure: cleanupPlan(input, "failure"),
+            timeout: cleanupPlan(input, "timeout"),
+            cancellation: cleanupPlan(input, "cancellation")
+        },
+        privacy: {
+            includesTemporaryCheckoutRoot: false,
+            includesRawSource: false,
+            includesRawDiffs: false,
+            includesSecrets: false,
+            includesCustomerPayloads: false,
+            includesAppJwt: false,
+            includesInstallationToken: false,
+            acceptsCommandFromPrText: false
+        }
+    };
+}
+function base64UrlJson(value) {
+    return Buffer.from(JSON.stringify(value)).toString("base64url");
+}
+function normalizeUnixSeconds(value, fallback) {
+    if (value === undefined || !Number.isFinite(value)) {
+        return fallback;
+    }
+    return Math.max(0, Math.floor(value));
+}
+function clampPositiveInteger(value, fallback, maximum) {
+    if (value === undefined || !Number.isFinite(value)) {
+        return fallback;
+    }
+    return Math.min(maximum, Math.max(1, Math.floor(value)));
+}
+function installationTokenInputBlockedReasons(input) {
+    const reasons = [];
+    if (typeof input.appJwt === "string" && input.appJwt.trim()) {
+        reasons.push("raw_secret_material:appJwt");
+    }
+    if (typeof input.rawPrivateKey === "string" && input.rawPrivateKey.trim()) {
+        reasons.push("raw_secret_material:rawPrivateKey");
+    }
+    if (typeof input.rawInstallationToken === "string" && input.rawInstallationToken.trim()) {
+        reasons.push("raw_secret_material:rawInstallationToken");
+    }
+    if (!Number.isSafeInteger(input.installationId) || input.installationId <= 0) {
+        reasons.push("invalid_installation_id");
+    }
+    if (!Number.isSafeInteger(input.repositoryId) || input.repositoryId <= 0) {
+        reasons.push("invalid_repository_id");
+    }
+    return reasons;
+}
+function safeApiUrlBlockedReasons(apiBaseUrl) {
+    if (!apiBaseUrl) {
+        return [];
+    }
+    try {
+        const url = new URL(apiBaseUrl);
+        return url.protocol === "https:" ? [] : ["invalid_github_api_url"];
+    }
+    catch {
+        return ["invalid_github_api_url"];
+    }
+}
+function normalizeApiBaseUrl(apiBaseUrl) {
+    const value = apiBaseUrl?.trim() || "https://api.github.com";
+    return value.replace(/\/+$/, "");
+}
+function permissionsForPurpose(purpose) {
+    if (purpose === "worker_checkout") {
+        return {
+            contents: "read",
+            pull_requests: "read"
+        };
+    }
+    if (purpose === "check_run_publication") {
+        return {
+            checks: "write"
+        };
+    }
+    return {
+        contents: "read",
+        pull_requests: "read",
+        checks: "write"
+    };
+}
+function workerPlanBlockedReasons(plan) {
+    return plan.accepted ? [] : [`worker_plan_rejected:${plan.reason ?? "unknown"}`];
+}
+function prefixBlockedReasons(prefix, reasons) {
+    return reasons.map((reason) => `${prefix}:${reason}`);
+}
+function cleanupPlan(input, terminalState) {
+    return createHostedWorkerCheckoutCleanupPlan({
+        identity: input.identity,
+        jobKey: input.jobKey,
+        terminalState,
+        finishedAt: input.requestedAt
+    });
+}

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

package/docs/github-app-deployment.md

@@ -61,6 +61,8 @@ The deployment plan never returns:
 - client secret values
 - customer payloads
 
+The production adapter layer in [hosted-production-adapters.md](hosted-production-adapters.md) extends this boundary after App creation: it generates short-lived RS256 GitHub App JWTs, plans selected-repository installation-token requests, separates worker checkout and Check Run token scopes, and keeps bearer credentials out of serializable request plans.
+
 It returns only safe manifest fields, blocker IDs, environment metadata, container digest, secret reference names, and deployment steps.
 
 ## Deployment Steps
@@ -76,4 +78,4 @@ When `readyToCreateGitHubApp` is true:
 
 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.
+The next deployment stage should wire the hosted service runtime and production adapters to a real platform queue, compact report store, GitHub installation authentication, worker isolation layer, and Checks API publisher.

package/docs/hosted-preimplementation-contracts.md

@@ -2,7 +2,7 @@
 
 This document collects pure hosted contracts that can be tested before any hosted GitHub App service is deployed. These contracts keep the hosted design inspectable, local-first, and implementation-ready without adding network calls, credentials, queues, workers, or GitHub API writes. They are no network calls contracts by design.
 
-The helpers live in `src/hosted/contracts.ts` and are exported from `ai-saas-guard/hosted/contracts`.
+The helpers live in `src/hosted/contracts.ts` and are exported from `ai-saas-guard/hosted/contracts`. The production adapter plans live in `src/hosted/production-adapters.ts` and are exported from `ai-saas-guard/hosted/production-adapters`.
 
 ## Pull Request Webhook Intake Planner
 
@@ -70,6 +70,29 @@ Trust boundaries:
 
 The exported helper is `planHostedWorkerReadOnlyScan`. It is intended to be the worker-provider-independent contract for the first real hosted worker implementation.
 
+## Production Adapter Plans
+
+The production adapter layer turns the pure hosted contracts into a safer shape for real platform wiring. It is still provider-independent: it does not start a worker, call GitHub, request live installation tokens, write Check Runs, or upload source code.
+
+Default behavior:
+
+- create short-lived GitHub App JWTs with RS256 signing, 60-second issued-at clock skew, and a 10-minute maximum expiration
+- plan installation-token requests for a selected repository ID only
+- use separate token scopes for worker checkout and Check Run publication
+- keep bearer credentials outside serializable request plans by using `runtime_bearer_app_jwt`
+- fix the worker command to `ai-saas-guard pr-risk --root <worker-checkout> --base <trusted-base-sha> --json`
+- cap worker timeout and output budgets
+- require compact JSON-only worker output
+- precompute cleanup plans for success, failure, timeout, and cancellation
+
+Privacy boundaries:
+
+- do not persist signing-key material, App JWTs, installation tokens, temporary checkout roots, checkout paths, raw source, raw diffs, secrets, customer payloads, or low-level worker errors
+- do not accept repository identity, token scope, or worker command from PR-authored text
+- keep local CLI usage independent from the hosted service
+
+The exported helpers are `createHostedGitHubAppJwt`, `planHostedGitHubInstallationTokenRequest`, and `planHostedProductionWorkerExecution`.
+
 ## 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.

package/docs/hosted-production-adapters.md

@@ -0,0 +1,114 @@
+# Hosted Production Adapters
+
+This document describes the hosted production adapter layer implemented in `src/hosted/production-adapters.ts`.
+
+It does not announce a public hosted service. The module provides provider-independent auth, token-request, worker-execution, timeout, output, and cleanup plans that can be wired to a real hosted platform after the operational release gate has evidence.
+
+## What Exists
+
+The package exports `ai-saas-guard/hosted/production-adapters` with:
+
+- `createHostedGitHubAppJwt`
+- `planHostedGitHubInstallationTokenRequest`
+- `planHostedProductionWorkerExecution`
+
+The layer covers the next hosted build step:
+
+- GitHub App JWT generation with RS256 signing
+- 60-second issued-at clock skew
+- 10-minute maximum JWT expiration
+- installation-token request planning for selected repositories only
+- separate token scopes for worker checkout and Check Run publication
+- no raw private key, app JWT, or installation token persistence in request plans
+- fixed worker command from trusted runtime state, not pull request text
+- bounded worker timeout and output budgets
+- compact JSON-only worker output
+- cleanup plans for success, failure, timeout, and cancellation
+
+## GitHub App Auth Chain
+
+The runtime path is intentionally split:
+
+1. A secret provider reads the GitHub App private key at runtime.
+2. `createHostedGitHubAppJwt` signs a short-lived App JWT.
+3. `planHostedGitHubInstallationTokenRequest` creates a safe installation-token request plan.
+4. A platform adapter injects the runtime App JWT into the HTTP request and receives the installation token.
+5. The token is cached only until its GitHub `expires_at`, redacted from logs, and not persisted as report or queue state.
+
+The safe request plan uses `authorization: "runtime_bearer_app_jwt"` instead of returning a bearer token. This prevents accidental serialization of live credentials in logs, job records, release notes, or tests.
+
+## Token Scopes
+
+| Purpose | Repository scope | Permissions |
+| --- | --- | --- |
+| `worker_checkout` | selected repository ID only | `contents: read`, `pull_requests: read` |
+| `check_run_publication` | selected repository ID only | `checks: write` |
+| `first_slice` | selected repository ID only | `contents: read`, `pull_requests: read`, `checks: write` |
+
+`metadata: read` remains part of the GitHub App manifest permission contract, but GitHub installation token request bodies only include permissions that need explicit narrowing for the current operation.
+
+## Worker Execution Boundary
+
+`planHostedProductionWorkerExecution` composes the existing read-only worker contract with production execution limits:
+
+- command: `ai-saas-guard`
+- args: `pr-risk --root <worker-checkout> --base <trusted-base-sha> --json`
+- shell: disabled
+- network access: disabled for the CLI process
+- write mode: read-only
+- timeout: maximum 600 seconds
+- output budget: maximum 1 MiB
+- output retention: compact JSON only
+
+The plan never returns:
+
+- temporary checkout roots
+- private checkout paths
+- raw source
+- raw diffs
+- secrets
+- customer payloads
+- app JWTs
+- installation tokens
+
+## Cleanup Behavior
+
+The production plan precomputes cleanup obligations for every terminal worker state:
+
+- success
+- failure
+- timeout
+- cancellation
+
+Every terminal state schedules worker checkout deletion, credential removal, raw-source removal, raw-diff removal, generated-artifact removal, and compact audit metadata preservation. Cleanup failure remains a separate operator-review path in the lower-level hosted contracts.
+
+## Adapter Interfaces
+
+The module also defines minimal interfaces for real platform wiring:
+
+- `HostedProductionSecretProvider`
+- `HostedProductionInstallationTokenRequester`
+- `HostedProductionWorkerAdapter`
+
+These are intentionally small. A deployment can back them with Cloudflare, Fly.io, Render, AWS, GCP, Azure, or another platform without changing the scanner core.
+
+## Current Status
+
+The repository can now plan the production auth and worker boundary for the hosted GitHub App path. A public hosted environment still requires:
+
+- public HTTPS webhook URL
+- platform secret manager
+- deployed ingress and worker containers
+- managed durable queue
+- compact report storage
+- real GitHub Checks API publisher
+- monitoring and alerting
+- rollback and incident-response evidence
+- hosted operational release gate evidence from the deployed artifact
+
+Do not describe this module as a live hosted service. It is the production adapter layer needed before a live hosted service can be exposed.
+
+## References
+
+- GitHub Docs: [Generating a JSON Web Token for a GitHub App](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-json-web-token-jwt-for-a-github-app)
+- GitHub Docs: [Generating an installation access token for a GitHub App](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app)

package/docs/hosted-service-runtime.md

@@ -41,6 +41,8 @@ Production deployments must provide durable adapters:
 
 The exported `createInMemoryHostedServiceAdapters` is only for tests, local smoke runs, and examples. It is not a production queue or production data store.
 
+The production adapter layer in [hosted-production-adapters.md](hosted-production-adapters.md) now defines the next boundary around this runtime: GitHub App JWT creation, selected-repository installation-token request planning, separate worker and Check Run token scopes, fixed read-only worker execution, bounded timeout/output settings, compact JSON-only output, and cleanup planning for success, failure, timeout, and cancellation.
+
 ## Privacy
 
 The runtime intentionally returns safe planning and status objects only.
@@ -81,6 +83,7 @@ This runtime makes the hosted service implementation-ready inside the repository
 - platform secret manager
 - managed queue
 - compact report storage
+- production adapters wired to the platform secret manager and GitHub Checks API
 - 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.19.0`
+- Current version: `0.20.0`
 - npm registry state: published at <https://www.npmjs.com/package/ai-saas-guard>
 - First npm-published version: `0.1.1`
-- GitHub Release: `v0.19.0`
+- GitHub Release: `v0.20.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.19.0`.
+1. Create and review a release tag such as `v0.20.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

@@ -59,10 +59,11 @@ Implemented surfaces:
 - 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, public HTTPS URLs, container digest, secret references, raw secret input blockers, and release-gate checks
+- hosted production adapter layer document and helpers for RS256 GitHub App JWT creation, selected-repository installation-token request planning, separate worker/check-run token scopes, fixed read-only worker execution, timeout/output budgets, and cleanup planning for success, failure, timeout, and cancellation
 - resource caps for repository text collection, including per-file, total-file, and total-byte scan budgets to reduce worst-case memory use
 - 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, provider-independent service runtime orchestration, and GitHub App deployment planning
+- 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, GitHub App deployment planning, and hosted production adapter 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
@@ -133,7 +134,7 @@ CI:
 Publishing:
 
 - npm package: `ai-saas-guard`
-- Current release line: `v0.19.0`
+- Current release line: `v0.20.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.19.0",
+  "version": "0.20.0",
   "description": "Repo-local launch-readiness scanner for AI-built SaaS apps.",
   "type": "module",
   "homepage": "https://github.com/zr9959/ai-saas-guard#readme",
@@ -41,6 +41,10 @@
     "./hosted/github-app": {
       "types": "./dist/hosted/github-app.d.ts",
       "default": "./dist/hosted/github-app.js"
+    },
+    "./hosted/production-adapters": {
+      "types": "./dist/hosted/production-adapters.d.ts",
+      "default": "./dist/hosted/production-adapters.js"
     }
   },
   "bin": {