ai-saas-guard 0.8.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.8.0`, `v0` |
-| npm package | `ai-saas-guard@0.8.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
@@ -180,7 +180,13 @@ 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 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 +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.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.9.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,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.8.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

@@ -48,31 +48,48 @@ The first version should prefer check runs over noisy PR comments. PR comments s
 
 ## Least-Privilege Permissions
 
-Use least-privilege permissions and install on selected repositories only.
+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.
 
-Recommended initial permission set:
+### Required First-Version Permissions
 
-| Permission | Access | Why |
-| --- | --- | --- |
-| repository contents: read | Read | Fetch files or diffs needed for deterministic scans. |
-| pull requests: read | Read | Read PR metadata, changed files, and base/head refs. |
-| checks: write | Write | Publish a check run with summary, findings count, and report link. |
-| metadata: read | Read | Required by GitHub Apps for repository identity. |
+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.
 
-Optional permissions, disabled by default:
+| 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. |
 
-| Permission | Access | Why |
-| --- | --- | --- |
-| pull requests: write | Write | Post PR comments when a team explicitly enables comments. |
-| issues: write | Write | Only if GitHub represents PR comments through issue comment APIs for a chosen workflow. |
+### 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 secrets permission.
 - No deployments permission.
-- No actions write permission.
-- No organization-wide install requirement.
+- 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
 
@@ -96,6 +113,21 @@ Additional requirements:
 - 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:
@@ -108,7 +140,46 @@ The hosted app should keep the data flow simple and inspectable:
 6. The app writes a check run and optional PR comment.
 7. The report is retained according to team policy.
 
-Prefer storing:
+### 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
@@ -120,7 +191,7 @@ Prefer storing:
 - reviewer checklist
 - suppression policy version
 
-Avoid storing by default:
+Avoid storing these fields by default:
 
 - full file contents
 - raw diffs
@@ -130,17 +201,44 @@ Avoid storing by default:
 
 ## Privacy And Data Retention
 
+### Privacy And Data Retention Contract
+
 Privacy should be a first-version feature, not a later add-on.
 
-Default data retention:
+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 compact scan reports for 30 days.
 - Keep check run and PR comment content in GitHub as controlled by the customer's repository settings.
-- Delete raw worker checkout directories immediately after scan completion.
+- 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.
 
-Team admins should be able to shorten retention. Longer retention should 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
 
@@ -260,3 +358,9 @@ Do not start implementation until the hosted app has:
 - 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.8.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.8.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.8.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
@@ -52,6 +52,10 @@ Implemented surfaces:
 - 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
@@ -103,7 +107,11 @@ GitHub Project:
 
 Current issue set:
 
-- No open roadmap issues after the `v0.8.0` GitHub App design note 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:
 
@@ -115,7 +123,7 @@ CI:
 Publishing:
 
 - npm package: `ai-saas-guard`
-- Current release line: `v0.8.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.
@@ -142,9 +150,9 @@ Not allowed:
 
 Recommended order:
 
-1. Open new roadmap issues for the hosted GitHub App implementation gates in `docs/github-app-design.md`.
-2. Add issue templates for bug reports, false positives, false negatives, rule requests, and security-safe reports.
-3. Add CODEOWNERS once there are multiple maintainers.
+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.8.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": {