ai-saas-guard 0.7.0 → 0.9.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.7.0`, `v0` |
-| npm package | `ai-saas-guard@0.7.0` |
+| Versioned Action tags | `v0.9.0`, `v0` |
+| npm package | `ai-saas-guard@0.9.0` |
 | npm publishing | Trusted Publisher/OIDC, no long-lived publish token |
 
 ## Quick Start
@@ -178,6 +178,16 @@ Use [docs/launch-readiness-checklist.md](docs/launch-readiness-checklist.md) whe
 
 Use [docs/stripe-webhook-replay.md](docs/stripe-webhook-replay.md) after `check-stripe` flags missing signature verification, idempotency, lifecycle handlers, or entitlement updates. The cookbook maps findings to concrete `stripe listen` and `stripe trigger` commands for checkout success, failed renewal, subscription update, cancellation, refund, duplicate delivery, and out-of-order event review.
 
+## 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, 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 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
 
 Add `.ai-saas-guard.json` at the repository root to tune findings without changing scanner code. The CLI auto-loads this file from `--root` when it exists. Use `--config <file>` to point to a different JSON file.
@@ -208,7 +218,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.7.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.9.0` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
 
 ```yaml
 name: ai-saas-guard
@@ -337,7 +347,7 @@ Open-source core:
 
 Near-term priorities:
 
-- GitHub App design note for the potential hosted layer
+- GitHub App implementation should wait until the hosted design note's open questions and implementation gate are answered.
 
 Potential paid layer later:
 

package/dist/hosted/contracts.d.ts

@@ -0,0 +1,114 @@
+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 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 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 declare const HOSTED_PRIVACY_DEFAULTS: {
+    readonly retentionDays: 30;
+    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 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 resolveHostedRetentionDays(input?: {
+    teamRequestedDays?: number;
+}): number;
+export declare function createCompactHostedReport(input: CompactHostedReportInput): CompactHostedReport;

package/dist/hosted/contracts.js

@@ -0,0 +1,154 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+export const HOSTED_PRIVACY_DEFAULTS = {
+    retentionDays: 30,
+    modelTraining: "disabled",
+    deleteWorkerCheckout: "after_scan_completion"
+};
+export function verifyGitHubWebhook(input) {
+    const { deliveryId, seenDeliveryIds, signatureHeader } = input;
+    if (!signatureHeader) {
+        return rejectWebhook("missing_signature", deliveryId);
+    }
+    const parsedSignature = parseSha256Signature(signatureHeader);
+    if (!parsedSignature) {
+        return rejectWebhook("malformed_signature", deliveryId);
+    }
+    const expected = createHmac("sha256", input.signingKey).update(input.payload).digest();
+    if (!timingSafeEqual(parsedSignature, expected)) {
+        return rejectWebhook("invalid_signature", deliveryId);
+    }
+    if (deliveryId && seenDeliveryIds?.has(deliveryId)) {
+        return rejectWebhook("replayed_delivery_id", deliveryId);
+    }
+    if (deliveryId) {
+        seenDeliveryIds?.add(deliveryId);
+    }
+    return {
+        accepted: true,
+        shouldQueueScanJob: true,
+        shouldFetchRepository: false,
+        deliveryId
+    };
+}
+export function buildHostedScanIdentity(input) {
+    return {
+        installationId: input.installationId,
+        repositoryId: input.repositoryId,
+        repositoryFullName: input.repositoryFullName,
+        pullRequestNumber: input.pullRequestNumber,
+        baseSha: input.baseSha,
+        headSha: input.headSha,
+        scannerVersion: input.scannerVersion
+    };
+}
+export function authorizeInstallationTokenScope(input) {
+    if (input.installationId !== input.identity.installationId) {
+        return rejectInstallationScope("installation_mismatch");
+    }
+    if (input.removedRepositoryIds?.includes(input.identity.repositoryId)) {
+        return rejectInstallationScope("repository_removed_from_installation");
+    }
+    if (!input.selectedRepositoryIds.includes(input.identity.repositoryId)) {
+        return rejectInstallationScope("repository_not_installed");
+    }
+    return {
+        authorized: true,
+        shouldFetchSource: true
+    };
+}
+export function getHostedScanIdempotencyKey(identity) {
+    return [
+        identity.installationId,
+        identity.repositoryId,
+        identity.pullRequestNumber,
+        identity.headSha,
+        identity.scannerVersion
+    ].join(":");
+}
+export function upsertHostedScanJob(queue, input) {
+    const key = getHostedScanIdempotencyKey(input.identity);
+    const existing = queue.get(key);
+    if (!existing) {
+        queue.set(key, {
+            key,
+            attempt: 1,
+            deliveryIds: [input.deliveryId]
+        });
+        return {
+            key,
+            created: true,
+            reusedExistingReport: false,
+            attempt: 1,
+            shouldCreateCheckRun: true,
+            shouldCreatePrComment: true
+        };
+    }
+    if (!existing.deliveryIds.includes(input.deliveryId)) {
+        existing.deliveryIds.push(input.deliveryId);
+    }
+    if (input.manualRerun) {
+        existing.attempt += 1;
+    }
+    return {
+        key,
+        created: false,
+        reusedExistingReport: true,
+        attempt: existing.attempt,
+        shouldCreateCheckRun: false,
+        shouldCreatePrComment: false
+    };
+}
+export function resolveHostedRetentionDays(input = {}) {
+    if (input.teamRequestedDays === undefined) {
+        return HOSTED_PRIVACY_DEFAULTS.retentionDays;
+    }
+    const requestedDays = Math.floor(input.teamRequestedDays);
+    return Math.min(HOSTED_PRIVACY_DEFAULTS.retentionDays, Math.max(1, requestedDays));
+}
+export function createCompactHostedReport(input) {
+    const { identity } = input;
+    const ruleIds = [...new Set(input.findings.map((finding) => finding.ruleId))];
+    return {
+        installationId: identity.installationId,
+        repositoryId: identity.repositoryId,
+        repositoryFullName: identity.repositoryFullName,
+        pullRequestNumber: identity.pullRequestNumber,
+        baseSha: identity.baseSha,
+        headSha: identity.headSha,
+        scannerVersion: identity.scannerVersion,
+        summaryCounts: { ...input.summaryCounts },
+        ruleIds,
+        evidence: input.findings.map((finding) => ({
+            ruleId: finding.ruleId,
+            severity: finding.severity,
+            file: finding.file,
+            ...(finding.line === undefined ? {} : { line: finding.line })
+        })),
+        retentionDays: resolveHostedRetentionDays({ teamRequestedDays: input.retentionDays }),
+        modelTraining: HOSTED_PRIVACY_DEFAULTS.modelTraining,
+        workerCheckoutDeletion: HOSTED_PRIVACY_DEFAULTS.deleteWorkerCheckout
+    };
+}
+function rejectWebhook(reason, deliveryId) {
+    return {
+        accepted: false,
+        reason,
+        shouldQueueScanJob: false,
+        shouldFetchRepository: false,
+        deliveryId
+    };
+}
+function rejectInstallationScope(reason) {
+    return {
+        authorized: false,
+        shouldFetchSource: false,
+        reason
+    };
+}
+function parseSha256Signature(signatureHeader) {
+    const match = /^sha256=([0-9a-f]{64})$/i.exec(signatureHeader.trim());
+    if (!match?.[1]) {
+        return undefined;
+    }
+    return Buffer.from(match[1], "hex");
+}

package/dist/scanners/stripe.js

@@ -3,11 +3,12 @@ import { createReport, finding, uniqueFindings } from "../report/findings.js";
 import { lineAt, lineNumberForIndex } from "../utils/files.js";
 const criticalEvents = [
     "invoice.payment_failed",
+    "invoice.payment_action_required",
     "customer.subscription.deleted",
     "customer.subscription.updated",
     "charge.refunded"
 ];
-const eventPattern = /["']((?:checkout\.session\.completed|invoice\.payment_failed|customer\.subscription\.(?:deleted|updated|created)|charge\.(?:refunded|dispute\.created)|refund\.(?:created|updated)))["']/g;
+const eventPattern = /["']((?:checkout\.session\.completed|invoice\.(?:payment_failed|payment_action_required)|customer\.subscription\.(?:deleted|updated|created)|charge\.(?:refunded|dispute\.created)|refund\.(?:created|updated)))["']/g;
 export async function checkStripe(input) {
     const context = await resolveScanContext(input);
     const runtimeFiles = context.files.filter((file) => !isDocumentationFile(file.path));
@@ -32,6 +33,7 @@ export async function checkStripe(input) {
             testCommands: [
                 "stripe trigger checkout.session.completed",
                 "stripe trigger invoice.payment_failed",
+                "stripe trigger invoice.payment_action_required",
                 "stripe trigger customer.subscription.updated",
                 "stripe trigger customer.subscription.deleted",
                 "stripe trigger charge.refunded"
@@ -143,6 +145,7 @@ export async function checkStripe(input) {
         testCommands: [
             "stripe trigger checkout.session.completed",
             "stripe trigger invoice.payment_failed",
+            "stripe trigger invoice.payment_action_required",
             "stripe trigger customer.subscription.updated",
             "stripe trigger customer.subscription.deleted",
             "stripe trigger charge.refunded"

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

package/docs/github-app-design.md

@@ -0,0 +1,366 @@
+# GitHub App Design Note
+
+This note describes a possible hosted GitHub App layer for `ai-saas-guard`. It is a product and security design note, not an implementation announcement. The current project remains a local-first CLI and composite GitHub Action.
+
+The hosted GitHub App should save review time for teams that want PR comments, saved reports, policy settings, and scan history. It does not replace the local CLI. The CLI must remain useful on its own for private repositories, offline review, and users who do not want source code processed by a hosted service.
+
+## Product Goal
+
+The hosted app should answer the same narrow product question as the CLI:
+
+> What changed in auth, billing, data access, secrets, MCP tools, or deploy config that deserves human review first?
+
+The hosted layer adds workflow convenience:
+
+- PR comments with a concise review-first summary.
+- Check runs that point to findings without blocking every PR by default.
+- Saved reports for launch-readiness history.
+- Team policy settings for fail thresholds, suppressions, and stability preferences.
+- Optional human launch-readiness review for teams that want an expert pass.
+
+It should not become a broad SAST platform, pentest claim, or automatic security certification.
+
+## Non-Goals
+
+Do not build these into the first GitHub App version:
+
+- Full production infrastructure scanning.
+- Automatic code rewrites.
+- Secret rotation.
+- Direct deploy, billing, or database mutation.
+- Long-lived raw source archives.
+- Broad organization-wide installation by default.
+- AI-generated comments that treat untrusted PR text as instructions.
+
+## Recommended First Version
+
+Start with a PR review assistant that runs the same deterministic scanner logic as the CLI:
+
+1. A repository installs the GitHub App on selected repositories.
+2. A pull request event queues a scan job.
+3. The worker checks out or fetches the PR diff in an isolated job.
+4. The scanner runs in read-only mode.
+5. The app publishes a short check run summary.
+6. If enabled by policy, the app posts one PR comment with review-first files and required manual verification.
+7. The app stores a compact report record, not a full source copy.
+
+The first version should prefer check runs over noisy PR comments. PR comments should be opt-in per repository.
+
+## 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.
+
+### Required First-Version Permissions
+
+Only these permissions are required for the first hosted version. No required permission may be added without a new public issue that explains the product need, user impact, security tradeoff, and rollback path.
+
+| Status | Permission | Access | Default | Why |
+| --- | --- | --- | --- | --- |
+| Required | repository contents: read | Read | Enabled | Fetch files or diffs needed for deterministic scans. |
+| Required | pull requests: read | Read | Enabled | Read PR metadata, changed files, and base/head refs. |
+| Required | checks: write | Write | Enabled | Publish a check run with summary, findings count, and report link. |
+| Required | metadata: read | Read | Enabled | Required by GitHub Apps for repository identity. |
+
+### Optional Permissions
+
+Optional permissions are disabled by default and must be enabled through repository policy opt-in. Pull request comments require repository policy before the app can post or update any comment.
+
+| Status | Permission | Access | Default | Why |
+| --- | --- | --- | --- | --- |
+| Optional | pull requests: write | Write | Disabled | Post one upserted PR comment only when repository policy opt-in enables comments. |
+| Optional | issues: write | Write | Disabled | Only if GitHub represents PR comments through issue comment APIs for the chosen comment workflow. |
+
+### Install Boundary
+
+Selected repositories only:
+
+- The app should default to selected repository installation, not all repositories.
+- Repository admins should be able to remove a repository from the installation without affecting local CLI use.
+- No organization-wide installation requirement.
+- The hosted app does not replace the local CLI for repositories that do not install it.
+
+### Out-Of-Scope Permissions
+
+Avoid broad permissions:
+
+- No administration permission for the first version.
+- No deployments permission.
+- No actions: write permission.
+- No repository secrets permission.
+- No organization secrets permission.
+- No repository security-events write permission unless a later public issue scopes SARIF upload behavior.
+- No organization-wide installation requirement.
+
+## Event Model
+
+Accept only the events needed for review:
+
+- `pull_request` for opened, reopened, synchronized, and ready-for-review PRs.
+- `check_suite` or `check_run` only if needed for rerun behavior.
+- Installation events for setup and repository selection changes.
+
+Do not use `pull_request_target` semantics in the app worker. Treat PR title, body, comments, branch names, and code contents as untrusted data.
+
+## Webhook Security
+
+Every inbound GitHub webhook must pass webhook signature verification before any queue write or repository lookup.
+
+Additional requirements:
+
+- Reject requests with missing or invalid signatures.
+- Enforce timestamp or delivery replay checks when available.
+- Store GitHub delivery IDs for idempotency.
+- Make scan jobs idempotent by installation, repository, PR, head SHA, and scanner version.
+- Rate-limit repeated events for the same PR and commit.
+
+### Webhook Verification Test Contract
+
+Before hosted implementation starts, automated tests must cover:
+
+- valid signature requests queue exactly one scan request.
+- invalid signature requests are rejected.
+- missing signature requests are rejected.
+- malformed signature requests are rejected.
+- replayed delivery ID requests are rejected or treated as already processed.
+- duplicate event requests for the same delivery and PR head do not create duplicate scan work.
+
+Failed verification produces no scan job and no repository fetch. The webhook handler must verify the signed-webhook boundary before any queue write, installation lookup, token lookup, repository lookup, or worker dispatch.
+
+Fixtures for these tests must use no real credentials and no customer payloads. Payload examples should be reduced synthetic GitHub-shaped JSON with inert repository names, fake installation IDs, and fake SHAs.
+
+## Data Flow
+
+The hosted app should keep the data flow simple and inspectable:
+
+1. GitHub sends a signed webhook.
+2. The API verifies the signature and writes a small scan request to a queue.
+3. A worker fetches repository content or PR diff using an installation token.
+4. The worker runs the same scanner package version recorded in the scan request.
+5. Findings are converted into a compact report.
+6. The app writes a check run and optional PR comment.
+7. The report is retained according to team policy.
+
+### Installation Token Scoping Test Contract
+
+Every hosted scan request should carry explicit identity fields:
+
+- `installationId`
+- `repositoryId`
+- `repositoryFullName`
+- `pullRequestNumber`
+- `baseSha`
+- `headSha`
+- `scannerVersion`
+
+Automated tests must cover selected-repository installs, non-installed repositories, repository removal from an installation, and mismatched installation IDs.
+
+Worker behavior:
+
+- Token lookup must use `installationId` and `repositoryId` from the verified GitHub event, not from PR title, body, branch name, comments, README, or code.
+- A token lookup failure stops before source fetch.
+- Workers must never accept repository identity from untrusted PR text.
+- Workers must keep read-only worker behavior: fetch content or diffs, run the scanner, write checks or permitted comments, and avoid repository mutation.
+
+### Hosted Scan Queue Idempotency Test Contract
+
+The idempotency key is:
+
+```text
+installationId:repositoryId:pullRequestNumber:headSha:scannerVersion
+```
+
+Automated tests must cover duplicate webhook deliveries, rapid synchronize events, manual reruns, and scanner version changes.
+
+Queue behavior:
+
+- Repeated events with the same idempotency key should reuse the existing report or update the existing queued/running job.
+- Repeated events must produce no duplicate check runs and no duplicate PR comments.
+- Manual reruns may create a new attempt record, but they should keep the same logical report identity unless `headSha` or `scannerVersion` changes.
+- Scanner version changes should create a distinct scan identity so teams can compare old and new rule behavior.
+- Failure and retry state should be observable by installation, repository, PR, head SHA, scanner version, attempt number, and error class without logging raw source content.
+
+Prefer storing these compact report fields:
+
+- repository ID and name
+- PR number
+- head SHA and base SHA
+- scanner version
+- summary counts
+- rule IDs
+- evidence file paths and line numbers
+- reviewer checklist
+- suppression policy version
+
+Avoid storing these fields by default:
+
+- full file contents
+- raw diffs
+- secrets or matched secret values
+- generated logs with unredacted code snippets
+- customer data copied from application fixtures
+
+## Privacy And Data Retention
+
+### Privacy And Data Retention Contract
+
+Privacy should be a first-version feature, not a later add-on.
+
+Default app-side retention is 30 days for compact scan reports.
+
+Stored fields:
+
+- repository ID and name
+- PR number
+- base SHA and head SHA
+- scanner version
+- summary counts
+- rule IDs
+- evidence file paths and line numbers
+- reviewer checklist
+- suppression policy version
+- scan state, attempt number, and error class
+
+Avoided fields:
+
+- full file contents
+- raw diffs
+- secrets or matched secret values
+- generated logs with unredacted code snippets
+- customer data copied from application fixtures
+- private issue text, private comments, or unrelated repository documents that are not needed for the scan
+
+Retention and deletion rules:
+
+- Keep check run and PR comment content in GitHub as controlled by the customer's repository settings.
+- Raw worker checkout directories are deleted after scan completion.
+- Do not train models on customer code or findings.
+- Provide repository uninstall cleanup for stored app-side records.
+- Team admins can shorten retention.
+- Longer retention must be explicit and tied to paid audit history.
+
+Users should prefer the local CLI for private repositories, offline review, strict no-account workflows, or repositories where hosted processing is not acceptable.
+
+## Prompt Injection Handling
+
+If future versions use AI to summarize findings, prompt injection handling must be explicit:
+
+- PR text, code, diffs, issue comments, and README content are untrusted input.
+- Untrusted repository content must never override system, developer, or policy instructions.
+- AI summaries must be derived from deterministic scanner output first, not from free-form repository claims.
+- The app must not run shell commands suggested by PR text.
+- The app must not follow links from PR text during default scans.
+- Human approval is required before posting generated remediation comments that go beyond scanner evidence.
+
+The first version can avoid AI entirely and still be useful by posting deterministic PR triage.
+
+## Human Approval And Comments
+
+The app should avoid noisy or overconfident comments.
+
+Default behavior:
+
+- Always create or update a check run.
+- Do not post a PR comment unless the repository enables comments.
+- If comments are enabled, post one upserted summary comment per PR.
+- Never claim the PR is secure.
+- Use language such as "review first" and "verify" instead of "pass" for non-empty findings.
+
+Human approval should be required for:
+
+- opening issues automatically
+- requesting changes on a PR
+- posting detailed remediation text
+- marking a launch review as accepted
+- applying team-wide suppression policy changes
+
+## Configuration Model
+
+The hosted app should reuse the local config model where possible:
+
+- `.ai-saas-guard.json` remains the repository-owned policy file.
+- Team UI settings can set defaults, but repository config should be visible and reviewable.
+- Rule severity overrides and path-specific suppressions should behave the same as the CLI.
+- Stability labels can drive policy, such as "fail checks only on strict high/critical findings."
+
+Policy precedence should be simple:
+
+1. explicit PR workflow input or check rerun option
+2. repository `.ai-saas-guard.json`
+3. team default policy
+4. product default policy
+
+## Report UX
+
+The report should be short enough for busy PR review:
+
+- summary counts by severity
+- changed sensitive surfaces
+- top files to review first
+- exact rule IDs
+- evidence path and line
+- manual verification steps
+- links to launch-readiness and Stripe replay docs when relevant
+- note that the output is not a full security audit
+
+Saved reports should make trend review easier:
+
+- scan history by repository
+- repeated findings
+- suppressed findings by reason
+- rule stability breakdown
+- launch review sign-off evidence
+
+## Billing And Packaging
+
+The open-source CLI should stay useful without an account.
+
+Possible hosted plans:
+
+- Free: public repos, check run only, short retention.
+- Team: private repos, PR comments, saved reports, team policy settings.
+- Launch Review: optional human review attached to a checklist and report.
+
+Do not gate core local scanning behind the hosted app.
+
+## Operational Requirements
+
+Before launch, the hosted app needs:
+
+- privacy policy
+- terms of service
+- security contact
+- incident response plan
+- webhook delivery replay handling
+- worker isolation design
+- dependency and container scanning
+- audit logs for comment, check, policy, and report access
+- rate limits per installation and repository
+- clear uninstall and data deletion behavior
+
+## Open Questions
+
+These should be answered before implementation:
+
+- Should the first hosted version fetch full repository files or PR diffs only?
+- Should private repo reports store snippets, or only file paths and line numbers?
+- Should comments be opt-in per repository or per organization?
+- Should strict findings fail checks by default, or only after explicit policy setup?
+- What is the minimum paid feature that saves enough time without weakening the open-source CLI?
+
+## Implementation Gate
+
+Do not start implementation until the hosted app has:
+
+- documented GitHub App permissions
+- webhook signature verification tests
+- installation-token scoping tests
+- queue idempotency tests
+- privacy and data retention docs
+- prompt injection abuse-case tests if AI summaries are included
+- release gate evidence equivalent to the CLI package process
+
+Current pre-implementation gate evidence:
+
+- `tests/guard.test.mjs` verifies that this public design note keeps the permission, webhook, token scoping, idempotency, privacy, and retention contracts documented.
+- `tests/hosted-contracts.test.mjs` verifies pure contract helpers for valid signature, invalid signature, missing signature, malformed signature, replayed delivery ID, selected-repository installs, non-installed repositories, repository removal from an installation, mismatched installation IDs, deterministic queue idempotency, duplicate event reuse, manual reruns, scanner version changes, compact reports, retention limits, and raw-source exclusion.
+- `src/hosted/contracts.ts` is intentionally service-free: it does not start a server, call GitHub, request tokens, fetch repositories, write comments, or persist reports.

package/docs/npm-publishing.md

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

@@ -40,8 +40,8 @@ Implemented surfaces:
 
 - secret-like values and risky public env exposure
 - founder-readable launch-readiness checklist for two-account authorization, Stripe webhook verification, MCP config review, Supabase, deploy, CI, and rollback checks
-- Stripe webhook signature, raw body, idempotency, and lifecycle handler heuristics
-- Stripe webhook replay cookbook for checkout, renewal failure, updates, cancellation, refunds, duplicate delivery, and out-of-order review
+- Stripe webhook signature, raw body, idempotency, and lifecycle handler heuristics, including payment-action-required invoice recovery
+- Stripe webhook replay cookbook for checkout, renewal failure, payment action required, updates, cancellation, refunds, duplicate delivery, and out-of-order review
 - Supabase RLS, tenant membership, ownership filter, weak `WITH CHECK`, and storage object policy heuristics
 - sensitive API route heuristics
 - MCP config side-effect and secret-bearing risk inventory
@@ -51,6 +51,11 @@ Implemented surfaces:
 - PR-focused markdown summary output for GitHub step summaries or PR comments
 - project-local `.ai-saas-guard.json` config for rule toggles, severity overrides, path-specific suppressions, and default fail thresholds
 - rule stability labels in catalog metadata, public rule docs, and SARIF rule properties
+- hosted GitHub App design note covering least-privilege permissions, webhook verification, privacy, data retention, prompt-injection handling, and implementation gates
+- 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 verification, installation token scoping, scan queue idempotency, compact reports, and retention limits
+- 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
 - SARIF output
 - composite GitHub Action wrapper
@@ -102,7 +107,11 @@ GitHub Project:
 
 Current issue set:
 
-- No open roadmap issues after the `v0.7.0` suppression and stability release.
+- #14 `Roadmap: define first hosted service slice`
+- #15 `Roadmap: choose hosted app deployment model`
+- #16 `Roadmap: define hosted operational release gate`
+- #17 `Roadmap: define hosted uninstall and data deletion`
+- #18 `Roadmap: define hosted pricing and packaging boundaries`
 
 CI:
 
@@ -114,7 +123,7 @@ CI:
 Publishing:
 
 - npm package: `ai-saas-guard`
-- Current release line: `v0.7.0`
+- Current release line: `v0.9.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.
@@ -141,7 +150,9 @@ Not allowed:
 
 Recommended order:
 
-1. Add a GitHub App design note for the potential hosted layer.
+1. Work #14 before writing hosted service code.
+2. Work #15 and #16 before any hosted deployment.
+3. Work #17 and #18 before private repo onboarding or paid hosted features.
 
 For every feature, keep the scanner evidence-first:
 

package/docs/rules.md

@@ -51,7 +51,7 @@ Prefer fixing risky code over suppressing findings. When a finding is a reviewed
 | `stripe.webhook.public-secret` | critical | Stripe secrets must not use `NEXT_PUBLIC_*`. |
 | `stripe.webhook.missing-idempotency` | high | Stripe retries and duplicate events can drift billing state. |
 | `stripe.webhook.no-entitlement-path` | medium | Returning HTTP 200 is not the same as changing app access state. |
-| `stripe.webhook.missing-critical-event` | high/medium | Failure, cancellation, update, and refund paths need explicit handling. |
+| `stripe.webhook.missing-critical-event` | high/medium | Failure, payment-action, cancellation, update, and refund paths need explicit handling. |
 
 ## Supabase
 

package/docs/stripe-webhook-replay.md

@@ -49,6 +49,7 @@ Run the commands one at a time. Watch both the `stripe listen` terminal and your
 | --- | --- | --- |
 | Checkout success | `stripe trigger checkout.session.completed` | The app maps the Checkout Session to the correct user or tenant and grants access only after signature verification. |
 | Failed renewal | `stripe trigger invoice.payment_failed` | The app marks the subscription past-due, starts a grace path if intended, and does not leave unrestricted paid access forever. |
+| Payment action required | `stripe trigger invoice.payment_action_required` | The app prompts recovery, records limited or pending access state, and does not leave paid access unrestricted without a policy. |
 | Subscription update | `stripe trigger customer.subscription.updated` | Plan, quantity, cancel-at-period-end, period end, and status changes reconcile into local entitlement state. |
 | Cancellation | `stripe trigger customer.subscription.deleted` | Access is revoked or downgraded deterministically for the correct customer or tenant. |
 | Refund | `stripe trigger charge.refunded` | Refund handling does not accidentally grant access, double-credit an account, or ignore a required downgrade workflow. |
@@ -93,6 +94,24 @@ Review checklist:
 - `stripe.webhook.missing-critical-event`
 - `stripe.webhook.no-entitlement-path`
 
+## Payment Action Required
+
+```bash
+stripe trigger invoice.payment_action_required
+```
+
+Review checklist:
+
+- The app records a pending, past-due, or limited-access state instead of leaving unrestricted paid access indefinitely.
+- Customer recovery messaging or billing portal access is queued if that is part of the product policy.
+- The handler can later reconcile a successful payment or subscription update without duplicate access grants.
+- Access checks use local entitlement state, not only the last successful checkout redirect.
+
+`ai-saas-guard` findings this can validate:
+
+- `stripe.webhook.missing-critical-event`
+- `stripe.webhook.no-entitlement-path`
+
 ## Subscription Update
 
 ```bash
@@ -178,6 +197,7 @@ Use these questions during review:
 
 - What happens if `customer.subscription.updated` arrives before the app processed `checkout.session.completed`?
 - What happens if `invoice.payment_failed` arrives after a manual admin upgrade?
+- What happens if `invoice.payment_action_required` arrives after the user has already recovered payment?
 - What happens if `customer.subscription.deleted` arrives after a refund workflow already changed local access?
 - Does the handler fetch or derive current subscription/customer state before writing final entitlement state?
 - Is the local write guarded by Stripe customer, subscription, and tenant ownership, not just by event type?
@@ -193,6 +213,7 @@ Before launch or merge, a reviewer should be able to answer yes to each item:
 - Every handled event stores or dedupes `event.id`.
 - `checkout.session.completed` grants access through webhook reconciliation, not only redirect success.
 - `invoice.payment_failed` has an explicit past-due or grace behavior.
+- `invoice.payment_action_required` has an explicit recovery or limited-access behavior.
 - `customer.subscription.updated` updates plan, quantity, period, cancellation, and status fields used by access checks.
 - `customer.subscription.deleted` revokes or downgrades access for the correct user or tenant.
 - `charge.refunded` has an explicit record, downgrade, or manual review path.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-saas-guard",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Repo-local launch-readiness scanner for AI-built SaaS apps.",
   "type": "module",
   "homepage": "https://github.com/zr9959/ai-saas-guard#readme",
@@ -29,6 +29,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./hosted/contracts": {
+      "types": "./dist/hosted/contracts.d.ts",
+      "default": "./dist/hosted/contracts.js"
     }
   },
   "bin": {