ai-saas-guard 0.8.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.8.0`, `v0` |
-| npm package | `ai-saas-guard@0.8.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
@@ -180,7 +180,27 @@ Use [docs/stripe-webhook-replay.md](docs/stripe-webhook-replay.md) after `check-
 
 ## Hosted GitHub App Design
 
-See [docs/github-app-design.md](docs/github-app-design.md) for the proposed hosted GitHub App layer. The note covers least-privilege permissions, webhook verification, PR comments, check runs, privacy, data retention, prompt injection handling, and why the hosted app should not replace the local CLI.
+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.
+
+Users should prefer the local CLI for private repositories, offline review, or no-account workflows where hosted code processing is not acceptable.
 
 ## Project Configuration
 
@@ -212,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.8.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

@@ -0,0 +1,285 @@
+export type WebhookRejectReason = "missing_signature" | "malformed_signature" | "invalid_signature" | "replayed_delivery_id";
+export interface GitHubWebhookDecision {
+    accepted: boolean;
+    reason?: WebhookRejectReason;
+    shouldQueueScanJob: boolean;
+    shouldFetchRepository: boolean;
+    deliveryId?: string;
+}
+export interface GitHubWebhookInput {
+    payload: string | Buffer;
+    signatureHeader?: string;
+    signingKey: string | Buffer;
+    deliveryId?: string;
+    seenDeliveryIds?: Set<string>;
+}
+export interface HostedScanIdentityInput {
+    installationId: number;
+    repositoryId: number;
+    repositoryFullName: string;
+    pullRequestNumber: number;
+    baseSha: string;
+    headSha: string;
+    scannerVersion: string;
+    untrustedPrText?: string;
+}
+export interface HostedScanIdentity {
+    installationId: number;
+    repositoryId: number;
+    repositoryFullName: string;
+    pullRequestNumber: number;
+    baseSha: string;
+    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;
+    installationId: number;
+    selectedRepositoryIds: number[];
+    removedRepositoryIds?: number[];
+}
+export interface InstallationScopeDecision {
+    authorized: boolean;
+    shouldFetchSource: boolean;
+    reason?: InstallationScopeRejectReason;
+}
+export interface HostedScanJobState {
+    key: string;
+    attempt: number;
+    deliveryIds: string[];
+}
+export interface HostedScanJobInput {
+    identity: HostedScanIdentity;
+    deliveryId: string;
+    manualRerun?: boolean;
+}
+export interface HostedScanJobDecision {
+    key: string;
+    created: boolean;
+    reusedExistingReport: boolean;
+    attempt: number;
+    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;
+    file: string;
+    line?: number;
+}
+export interface CompactHostedReportInput {
+    identity: HostedScanIdentity;
+    summaryCounts: Record<string, number>;
+    findings: CompactHostedFinding[];
+    retentionDays?: number;
+    rawDiff?: string;
+    fullFileContents?: string;
+    secretValues?: string[];
+    customerPayload?: unknown;
+}
+export interface CompactHostedReport {
+    installationId: number;
+    repositoryId: number;
+    repositoryFullName: string;
+    pullRequestNumber: number;
+    baseSha: string;
+    headSha: string;
+    scannerVersion: string;
+    summaryCounts: Record<string, number>;
+    ruleIds: string[];
+    evidence: Array<{
+        ruleId: string;
+        severity: string;
+        file: string;
+        line?: number;
+    }>;
+    retentionDays: number;
+    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;