ai-saas-guard 0.9.0 → 0.10.0

package/README.md

@@ -51,8 +51,8 @@ The CLI is published on npm as `ai-saas-guard`, and the GitHub Action is availab
 | JSON and SARIF output | Available |
 | Composite GitHub Action | Available |
 | Project config | `.ai-saas-guard.json` rule toggles, severity overrides, and fail thresholds |
-| Versioned Action tags | `v0.9.0`, `v0` |
-| npm package | `ai-saas-guard@0.9.0` |
+| Versioned Action tags | `v0.10.0`, `v0` |
+| npm package | `ai-saas-guard@0.10.0` |
 | npm publishing | Trusted Publisher/OIDC, no long-lived publish token |
 
 ## Quick Start
@@ -182,6 +182,20 @@ Use [docs/stripe-webhook-replay.md](docs/stripe-webhook-replay.md) after `check-
 
 See [docs/github-app-design.md](docs/github-app-design.md) for the proposed hosted GitHub App layer. The note covers least-privilege permissions, selected repositories, webhook verification, PR comments, check runs, privacy, data retention, prompt injection handling, and why the hosted app should not replace the local CLI.
 
+The first hosted service slice is defined in [docs/hosted-first-service-slice.md](docs/hosted-first-service-slice.md). It is intentionally check-run-only: signed GitHub App webhook intake, trusted scan identity, idempotent scan queueing, read-only worker behavior, compact report storage, and no PR comments, dashboard, billing, or AI summaries.
+
+The hosted deployment model is documented in [docs/hosted-deployment-model.md](docs/hosted-deployment-model.md). It chooses a containerized Node.js ingress and worker model with a managed durable queue, platform secret manager, structured redacted logs, installation/repository rate limits, and rollback/incident response paths.
+
+The hosted operational release gate is documented in [docs/hosted-operational-release-gate.md](docs/hosted-operational-release-gate.md). It defines the hosted-specific CI, replay, queue, worker cleanup, privacy, monitoring, rollback, and incident-response evidence required before any hosted environment is exposed to users.
+
+Hosted uninstall and data deletion behavior is documented in [docs/hosted-uninstall-data-deletion.md](docs/hosted-uninstall-data-deletion.md). It defines repository removal, full app uninstall, compact report deletion, queue cancellation, audit record retention, repeated cleanup, and user-facing deletion wording.
+
+Hosted pricing and packaging boundaries are documented in [docs/hosted-pricing-packaging.md](docs/hosted-pricing-packaging.md). Core local scanning stays useful without an account; hosted plans may add workflow convenience, saved reports, team policy, and optional human review, but they do not gate local CLI scanning.
+
+Hosted pre-implementation pure contracts are documented in [docs/hosted-preimplementation-contracts.md](docs/hosted-preimplementation-contracts.md). They cover queue-safe webhook event parsing, bounded check-run summary rendering, idempotent queue cleanup planning, worker checkout cleanup planning, and other service-free helpers exported from `ai-saas-guard/hosted/contracts`.
+
+A public hosted compact report schema fixture is available at [examples/hosted-compact-report.json](examples/hosted-compact-report.json). It is synthetic and public-safe: compact evidence only, no raw source, raw diffs, secrets, webhook payload bodies, customer payloads, private URLs, or worker checkout paths.
+
 The proposed hosted app permission boundary is intentionally narrow: repository contents read, pull requests read, checks write, and metadata read for the first version. Optional PR comments require repository policy opt-in, and broad permissions such as administration, deployments, Actions write, and repository secrets are out of scope.
 
 The repository also includes pure pre-implementation hosted contract helpers and tests for webhook verification, installation token scoping, queue idempotency, compact reports, and retention limits. These helpers do not implement or deploy a hosted service.
@@ -218,7 +232,7 @@ Use `suppressions` for narrower false-positive handling when one rule is noisy o
 
 ## GitHub Action
 
-The repo includes a composite Action. Use `v0` for the latest compatible pre-1.0 Action, a specific release tag such as `v0.9.0` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
+The repo includes a composite Action. Use `v0` for the latest compatible pre-1.0 Action, a specific release tag such as `v0.10.0` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
 
 ```yaml
 name: ai-saas-guard

package/dist/hosted/contracts.d.ts

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

package/dist/hosted/contracts.js

@@ -1,9 +1,21 @@
 import { createHmac, timingSafeEqual } from "node:crypto";
 export const HOSTED_PRIVACY_DEFAULTS = {
     retentionDays: 30,
+    auditRecordRetentionDays: 90,
     modelTraining: "disabled",
     deleteWorkerCheckout: "after_scan_completion"
 };
+const CHECK_RUN_NAME = "AI SaaS Guard";
+const DEFAULT_CHECK_RUN_MARKDOWN_CHARS = 4000;
+const MAX_CHECK_RUN_ANNOTATIONS = 50;
+const severityOrder = ["critical", "high", "medium", "low", "info"];
+const severityRanks = {
+    critical: 5,
+    high: 4,
+    medium: 3,
+    low: 2,
+    info: 1
+};
 export function verifyGitHubWebhook(input) {
     const { deliveryId, seenDeliveryIds, signatureHeader } = input;
     if (!signatureHeader) {
@@ -41,6 +53,59 @@ export function buildHostedScanIdentity(input) {
         scannerVersion: input.scannerVersion
     };
 }
+export function parseHostedPullRequestEvent(input) {
+    const supportedActions = input.supportedActions ?? [
+        "opened",
+        "reopened",
+        "synchronize",
+        "ready_for_review"
+    ];
+    const payload = input.payload;
+    if (!isRecord(payload)) {
+        return rejectPullRequestEvent("missing_required_field");
+    }
+    const action = valueAsString(payload.action);
+    if (!action || !supportedActions.includes(action)) {
+        return rejectPullRequestEvent("unsupported_action", action);
+    }
+    const installation = valueAsRecord(payload.installation);
+    const repository = valueAsRecord(payload.repository);
+    const pullRequest = valueAsRecord(payload.pull_request);
+    const base = valueAsRecord(pullRequest?.base);
+    const head = valueAsRecord(pullRequest?.head);
+    const installationId = valueAsNumber(installation?.id);
+    const repositoryId = valueAsNumber(repository?.id);
+    const repositoryFullName = valueAsString(repository?.full_name);
+    const pullRequestNumber = valueAsNumber(pullRequest?.number);
+    const baseSha = valueAsString(base?.sha);
+    const headSha = valueAsString(head?.sha);
+    const draft = pullRequest?.draft === true;
+    if (installationId === undefined ||
+        repositoryId === undefined ||
+        !repositoryFullName ||
+        pullRequestNumber === undefined ||
+        !baseSha ||
+        !headSha) {
+        return rejectPullRequestEvent("missing_required_field", action);
+    }
+    if (draft && !input.allowDraft) {
+        return rejectPullRequestEvent("draft_pull_request", action);
+    }
+    return {
+        accepted: true,
+        shouldQueueScanJob: true,
+        action,
+        identity: buildHostedScanIdentity({
+            installationId,
+            repositoryId,
+            repositoryFullName,
+            pullRequestNumber,
+            baseSha,
+            headSha,
+            scannerVersion: input.scannerVersion
+        })
+    };
+}
 export function authorizeInstallationTokenScope(input) {
     if (input.installationId !== input.identity.installationId) {
         return rejectInstallationScope("installation_mismatch");
@@ -98,6 +163,80 @@ export function upsertHostedScanJob(queue, input) {
         shouldCreatePrComment: false
     };
 }
+export function getHostedQueueCleanupIdempotencyKey(input) {
+    return ["queue-cleanup", input.trigger, input.installationId, input.repositoryId ?? "all"].join(":");
+}
+export function createHostedQueueCleanupPlan(input) {
+    const scope = input.trigger === "installation_deleted" ? "installation" : "repository";
+    const matchedJobs = input.jobs.filter((job) => queueCleanupMatches(job, input, scope));
+    const unmatchedJobs = input.jobs.filter((job) => !queueCleanupMatches(job, input, scope));
+    return {
+        trigger: input.trigger,
+        scope,
+        installationId: input.installationId,
+        ...(scope === "repository" && input.repositoryId !== undefined
+            ? { repositoryId: input.repositoryId }
+            : {}),
+        requestedAt: input.requestedAt,
+        idempotencyKey: getHostedQueueCleanupIdempotencyKey({
+            trigger: input.trigger,
+            installationId: input.installationId,
+            repositoryId: scope === "repository" ? input.repositoryId : undefined
+        }),
+        idempotent: true,
+        matchedJobKeys: matchedJobs.map((job) => job.key),
+        cancelQueuedJobKeys: matchedJobs
+            .filter((job) => job.status === "queued")
+            .map((job) => job.key),
+        requestRunningCancellationJobKeys: matchedJobs
+            .filter((job) => job.status === "running")
+            .map((job) => job.key),
+        preserveTerminalJobKeys: matchedJobs
+            .filter((job) => isTerminalQueueStatus(job.status))
+            .map((job) => job.key),
+        keepUnmatchedJobKeys: unmatchedJobs.map((job) => job.key),
+        cancelQueuedJobs: true,
+        requestRunningCancellation: true,
+        deleteRawSource: false,
+        deleteRawDiffs: false,
+        deleteSecrets: false,
+        deleteCustomerPayloads: false
+    };
+}
+export function createHostedWorkerCheckoutCleanupPlan(input) {
+    const cleanupFailed = input.terminalState === "cleanup_failure";
+    return {
+        cleanupAction: cleanupFailed ? "record_cleanup_failure" : "delete_checkout",
+        shouldDeleteWorkerCheckout: !cleanupFailed,
+        shouldRemoveCredentials: !cleanupFailed,
+        shouldRemoveRawSource: !cleanupFailed,
+        shouldRemoveRawDiffs: !cleanupFailed,
+        shouldRemoveGeneratedArtifacts: !cleanupFailed,
+        requiresOperatorReview: cleanupFailed,
+        preserveAuditRecord: true,
+        visibleUserMessage: cleanupFailed
+            ? "Worker checkout cleanup failed; manual cleanup review is required without exposing checkout data."
+            : "Worker checkout is scheduled for deletion after scan completion.",
+        safeMetadata: {
+            jobKey: input.jobKey,
+            installationId: input.identity.installationId,
+            repositoryId: input.identity.repositoryId,
+            repositoryFullName: input.identity.repositoryFullName,
+            pullRequestNumber: input.identity.pullRequestNumber,
+            scannerVersion: input.identity.scannerVersion,
+            terminalState: input.terminalState,
+            finishedAt: input.finishedAt
+        },
+        privacy: {
+            returnsCheckoutPath: false,
+            returnsCleanupError: false,
+            returnsRawSource: false,
+            returnsRawDiffs: false,
+            returnsSecrets: false,
+            returnsCustomerPayloads: false
+        }
+    };
+}
 export function resolveHostedRetentionDays(input = {}) {
     if (input.teamRequestedDays === undefined) {
         return HOSTED_PRIVACY_DEFAULTS.retentionDays;
@@ -129,6 +268,71 @@ export function createCompactHostedReport(input) {
         workerCheckoutDeletion: HOSTED_PRIVACY_DEFAULTS.deleteWorkerCheckout
     };
 }
+export function createHostedCheckRunSummary(input) {
+    const { report } = input;
+    const totalFindings = getHostedReportFindingTotal(report);
+    const localCliCommand = `npx ai-saas-guard@${report.scannerVersion} pr-risk --root .`;
+    const conclusion = resolveCheckRunConclusion(report, input.failOnSeverity);
+    return {
+        name: CHECK_RUN_NAME,
+        conclusion,
+        output: {
+            title: formatCheckRunTitle(totalFindings, conclusion, input.failOnSeverity),
+            summary: "Review first: verify this launch-readiness signal before release; it is not a full security audit, pentest, or certification.",
+            text: truncateMarkdown(formatCheckRunMarkdown(report, conclusion, localCliCommand), input.maxMarkdownChars)
+        },
+        annotations: report.evidence.slice(0, MAX_CHECK_RUN_ANNOTATIONS).map((finding) => {
+            const line = finding.line ?? 1;
+            return {
+                path: finding.file,
+                startLine: line,
+                endLine: line,
+                annotationLevel: annotationLevelForSeverity(finding.severity),
+                title: finding.ruleId,
+                message: `${finding.severity} finding. Review locally before launch.`
+            };
+        }),
+        localCliCommand,
+        privacy: {
+            includesRawSource: false,
+            includesRawDiffs: false,
+            includesSecrets: false,
+            includesCustomerPayloads: false,
+            modelTraining: HOSTED_PRIVACY_DEFAULTS.modelTraining
+        }
+    };
+}
+export function getHostedDeletionIdempotencyKey(input) {
+    return [input.trigger, input.installationId, input.repositoryId ?? "all"].join(":");
+}
+export function createHostedDeletionPlan(input) {
+    const scope = input.trigger === "installation_deleted" ? "installation" : "repository";
+    const repositoryId = scope === "repository" ? input.repositoryId : undefined;
+    return {
+        trigger: input.trigger,
+        scope,
+        installationId: input.installationId,
+        ...(repositoryId === undefined ? {} : { repositoryId }),
+        requestedAt: input.requestedAt,
+        idempotencyKey: getHostedDeletionIdempotencyKey({
+            trigger: input.trigger,
+            installationId: input.installationId,
+            repositoryId
+        }),
+        idempotent: true,
+        deleteCompactReports: true,
+        cancelQueuedJobs: true,
+        deleteWorkerCheckouts: true,
+        deleteRawSource: false,
+        deleteRawDiffs: false,
+        deleteSecrets: false,
+        deleteCustomerPayloads: false,
+        deleteGitHubOwnedCheckRuns: false,
+        preserveAuditRecord: true,
+        auditRecordRetentionDays: input.auditRecordRetentionDays ?? HOSTED_PRIVACY_DEFAULTS.auditRecordRetentionDays,
+        visibleUserMessage: "Hosted app-side compact reports and queued work are removed; GitHub-owned check runs remain in GitHub according to repository settings."
+    };
+}
 function rejectWebhook(reason, deliveryId) {
     return {
         accepted: false,
@@ -138,6 +342,14 @@ function rejectWebhook(reason, deliveryId) {
         deliveryId
     };
 }
+function rejectPullRequestEvent(reason, action) {
+    return {
+        accepted: false,
+        shouldQueueScanJob: false,
+        reason,
+        ...(action === undefined ? {} : { action })
+    };
+}
 function rejectInstallationScope(reason) {
     return {
         authorized: false,
@@ -145,6 +357,115 @@ function rejectInstallationScope(reason) {
         reason
     };
 }
+function queueCleanupMatches(job, input, scope) {
+    if (job.identity.installationId !== input.installationId) {
+        return false;
+    }
+    return scope === "installation" || job.identity.repositoryId === input.repositoryId;
+}
+function isTerminalQueueStatus(status) {
+    return status === "completed" || status === "failed" || status === "cancelled";
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function valueAsRecord(value) {
+    return isRecord(value) ? value : undefined;
+}
+function valueAsString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function valueAsNumber(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0
+        ? value
+        : undefined;
+}
+function resolveCheckRunConclusion(report, failOnSeverity) {
+    if (getHostedReportFindingTotal(report) === 0) {
+        return "success";
+    }
+    if (failOnSeverity &&
+        report.evidence.some((finding) => severityRank(finding.severity) >= severityRanks[failOnSeverity])) {
+        return "failure";
+    }
+    return "neutral";
+}
+function getHostedReportFindingTotal(report) {
+    const countedBySeverity = Object.entries(report.summaryCounts).reduce((total, [severity, count]) => severity === "total" ? total : total + (typeof count === "number" ? count : 0), 0);
+    const explicitTotal = typeof report.summaryCounts.total === "number" ? report.summaryCounts.total : 0;
+    return Math.max(countedBySeverity, explicitTotal, report.evidence.length);
+}
+function formatCheckRunTitle(totalFindings, conclusion, failOnSeverity) {
+    if (totalFindings === 0) {
+        return "AI SaaS Guard found no launch-readiness findings";
+    }
+    if (conclusion === "failure" && failOnSeverity) {
+        return `AI SaaS Guard found findings at or above ${failOnSeverity}`;
+    }
+    return `AI SaaS Guard found ${totalFindings} finding${totalFindings === 1 ? "" : "s"} to review`;
+}
+function formatCheckRunMarkdown(report, conclusion, localCliCommand) {
+    const findingLines = report.evidence.length === 0
+        ? ["No findings in the compact hosted report."]
+        : [
+            "| Severity | Rule | Evidence |",
+            "| --- | --- | --- |",
+            ...report.evidence.map((finding) => `| ${escapeMarkdownTableCell(finding.severity)} | ${escapeMarkdownTableCell(finding.ruleId)} | ${escapeMarkdownTableCell(formatFindingLocation(finding))} |`)
+        ];
+    return [
+        "### AI SaaS Guard",
+        "",
+        "Review first: verify findings locally before launch. This hosted check is not a full security audit, pentest, or certification.",
+        "",
+        `Conclusion: ${conclusion}`,
+        `Local CLI: \`${localCliCommand}\``,
+        `Retention: compact report ${report.retentionDays} days; raw source, raw diffs, secrets, and customer payloads are not retained.`,
+        "",
+        "Summary:",
+        ...severityOrder.map((severity) => `- ${capitalize(severity)}: ${report.summaryCounts[severity] ?? 0}`),
+        "",
+        "Findings:",
+        ...findingLines
+    ].join("\n");
+}
+function truncateMarkdown(markdown, maxMarkdownChars) {
+    const maxChars = maxMarkdownChars === undefined
+        ? DEFAULT_CHECK_RUN_MARKDOWN_CHARS
+        : Math.max(1, Math.floor(maxMarkdownChars));
+    if (markdown.length <= maxChars) {
+        return markdown;
+    }
+    const suffix = "\n\n_Additional findings truncated by hosted check output limit. Run the local CLI for the full report._";
+    if (maxChars <= suffix.length) {
+        return suffix.slice(0, maxChars);
+    }
+    return `${markdown.slice(0, maxChars - suffix.length).trimEnd()}${suffix}`;
+}
+function severityRank(severity) {
+    const normalized = severity.toLowerCase();
+    return normalized in severityRanks
+        ? severityRanks[normalized]
+        : 0;
+}
+function annotationLevelForSeverity(severity) {
+    const rank = severityRank(severity);
+    if (rank >= severityRanks.high) {
+        return "failure";
+    }
+    if (rank >= severityRanks.medium) {
+        return "warning";
+    }
+    return "notice";
+}
+function formatFindingLocation(finding) {
+    return `${finding.file}${finding.line === undefined ? "" : `:${finding.line}`}`;
+}
+function escapeMarkdownTableCell(value) {
+    return value.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}
+function capitalize(value) {
+    return `${value.charAt(0).toUpperCase()}${value.slice(1)}`;
+}
 function parseSha256Signature(signatureHeader) {
     const match = /^sha256=([0-9a-f]{64})$/i.exec(signatureHeader.trim());
     if (!match?.[1]) {

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

package/docs/github-app-design.md

@@ -46,6 +46,20 @@ Start with a PR review assistant that runs the same deterministic scanner logic
 
 The first version should prefer check runs over noisy PR comments. PR comments should be opt-in per repository.
 
+The first hosted service slice is scoped in [docs/hosted-first-service-slice.md](hosted-first-service-slice.md). That slice is check-run-only and exists to prove signed webhook intake, trusted identity construction, idempotent queueing, read-only worker behavior, compact report storage, and local-first positioning before any PR comments, dashboard, billing, or AI summaries are added.
+
+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 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.
+
+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.
+
 ## Least-Privilege Permissions
 
 Use least-privilege permissions and install on selected repositories only. This section is the Implementation-ready permission contract for the first hosted GitHub App version.