ai-saas-guard 0.3.0 → 0.5.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.3.0`, `v0` |
-| npm package | `ai-saas-guard@0.3.0` |
+| Versioned Action tags | `v0.5.0`, `v0` |
+| npm package | `ai-saas-guard@0.5.0` |
 | npm publishing | Trusted Publisher/OIDC, no long-lived publish token |
 
 ## Quick Start
@@ -121,7 +121,7 @@ Evidence:
 | --- | --- |
 | Secrets and env | Secret-like values, risky `NEXT_PUBLIC_*` exposure |
 | Stripe | Missing webhook route, unsigned webhook handling, parsed-body signature risk, missing idempotency, missing failure/cancel/update/refund paths |
-| Supabase | RLS disabled on sensitive tables, `USING (true)`, missing ownership filters, public storage hints |
+| Supabase | RLS disabled on sensitive tables, broad `USING`/`WITH CHECK`, tenant membership patterns, weak write checks, storage object policy scope |
 | API routes | Auth checks without obvious ownership guards, missing rate-limit hints on sensitive mutation routes |
 | MCP | Plaintext secrets, non-localhost binds, broad filesystem/write access, shell tools, raw SQL tools |
 | Deploy config | Next static export/runtime mismatches, Edge runtime with Node-only APIs, missing important env documentation |
@@ -170,6 +170,10 @@ If `--base` cannot be resolved, `pr-risk` emits `pr-risk.diff-unavailable` inste
 | `check-stripe` | Inspect webhook handlers and billing lifecycle coverage |
 | `check-mcp` | Inventory MCP configs and classify side effects |
 
+## Stripe Webhook Replay
+
+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.
+
 ## 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.
@@ -191,7 +195,7 @@ Add `.ai-saas-guard.json` at the repository root to tune findings without changi
 
 ## 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.3.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.5.0` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
 
 ```yaml
 name: ai-saas-guard
@@ -320,10 +324,9 @@ Open-source core:
 
 Near-term priorities:
 
-- expanded Supabase RLS fixtures
-- Stripe webhook replay cookbook
 - launch-readiness checklist content
 - false-positive suppression and rule stability labels
+- GitHub App design note for the potential hosted layer
 
 Potential paid layer later:
 

package/dist/rules/catalog.js

@@ -66,7 +66,7 @@ export const RULE_CATALOG = {
         ruleId: "supabase.rls.broad-policy",
         severity: "critical",
         title: "Broad Supabase RLS policy",
-        why: "`USING (true)` often turns login into public data access.",
+        why: "`USING (true)` or `WITH CHECK (true)` can turn login into broad data access or writes.",
         stability: "default"
     },
     "supabase.rls.missing-ownership-filter": {
@@ -76,6 +76,13 @@ export const RULE_CATALOG = {
         why: "Policies need resource ownership or tenant membership checks.",
         stability: "default"
     },
+    "supabase.rls.weak-with-check": {
+        ruleId: "supabase.rls.weak-with-check",
+        severity: "high",
+        title: "Supabase write policy has a weak WITH CHECK predicate",
+        why: "Insert and update policies need WITH CHECK predicates tied to the current user or tenant membership.",
+        stability: "default"
+    },
     "supabase.table.missing-owner-column": {
         ruleId: "supabase.table.missing-owner-column",
         severity: "medium",

package/dist/scanners/stripe.js

@@ -10,8 +10,8 @@ const criticalEvents = [
 const eventPattern = /["']((?:checkout\.session\.completed|invoice\.payment_failed|customer\.subscription\.(?:deleted|updated|created)|charge\.(?:refunded|dispute\.created)|refund\.(?:created|updated)))["']/g;
 export async function checkStripe(input) {
     const context = await resolveScanContext(input);
-    const files = context.files;
-    const webhookFiles = files.filter((file) => {
+    const runtimeFiles = context.files.filter((file) => !isDocumentationFile(file.path));
+    const webhookFiles = runtimeFiles.filter((file) => {
         const path = file.path.toLowerCase();
         const content = file.content.toLowerCase();
         return ((path.includes("stripe") && path.includes("webhook")) ||
@@ -19,7 +19,7 @@ export async function checkStripe(input) {
             content.includes("stripe-signature") ||
             content.includes("checkout.session.completed"));
     });
-    const stripeSignalFiles = files.filter((file) => !/\.(md|txt)$/i.test(file.path) && !file.path.startsWith("docs/"));
+    const stripeSignalFiles = runtimeFiles;
     const usesStripe = webhookFiles.length > 0 ||
         stripeSignalFiles.some((file) => /STRIPE_SECRET_KEY|STRIPE_WEBHOOK_SECRET|from\s+["']stripe["']|require\(["']stripe["']\)|new\s+Stripe|stripe\.webhooks|checkout\.session\.completed/i.test(`${file.path}\n${file.content}`));
     const findings = [];
@@ -164,3 +164,7 @@ function firstSnippetMatching(content, pattern) {
     const line = firstLineMatching(content, pattern);
     return line ? lineAt(content, line) : undefined;
 }
+function isDocumentationFile(path) {
+    const normalizedPath = path.replace(/\\/g, "/").toLowerCase();
+    return normalizedPath.startsWith("docs/") || /\.(md|mdx|rst|txt)$/i.test(normalizedPath);
+}

package/dist/scanners/supabase.js

@@ -28,18 +28,24 @@ export async function checkSupabase(input) {
         for (const match of file.content.matchAll(/alter\s+table\s+([a-zA-Z0-9_."]+)\s+enable\s+row\s+level\s+security/gi)) {
             rlsEnabledTables.add(normalizeSqlIdentifier(match[1]));
         }
-        for (const match of file.content.matchAll(/create\s+policy\s+"?([^"\n]+)"?\s+on\s+([a-zA-Z0-9_."]+)[\s\S]*?(?:using\s*\(([\s\S]*?)\)|with\s+check\s*\(([\s\S]*?)\))\s*;/gi)) {
-            const policyName = match[1].trim();
-            const tableName = normalizeSqlIdentifier(match[2]);
-            const predicate = `${match[3] ?? ""} ${match[4] ?? ""}`.trim();
-            const line = lineNumberForIndex(file.content, match.index ?? 0);
-            if (/\btrue\b/i.test(predicate) || /\bto\s+(public|anon|authenticated)\b[\s\S]*\busing\s*\(\s*true\s*\)/i.test(match[0])) {
+        for (const policy of parsePolicies(file.content)) {
+            const { name: policyName, tableName, line } = policy;
+            const predicates = [policy.usingPredicate, policy.withCheckPredicate].filter((value) => Boolean(value));
+            if (isStorageObjectsTable(tableName)) {
+                const riskyStoragePredicate = predicates.find((predicate) => isUnscopedStoragePredicate(predicate));
+                if (riskyStoragePredicate) {
+                    findings.push(storageFinding(file.path, file.content, line, "Supabase storage.objects policy lacks owner or tenant scope"));
+                }
+                continue;
+            }
+            const broadPredicate = predicates.find((predicate) => isBroadPredicate(predicate));
+            if (broadPredicate || /\bto\s+(public|anon|authenticated)\b[\s\S]*\busing\s*\(\s*true\s*\)/i.test(policy.statement)) {
                 riskyPolicies.push({
                     file: file.path,
                     line,
                     policyName,
                     tableName,
-                    reason: "Policy predicate is broad (`USING (true)` or equivalent)."
+                    reason: "Policy predicate is broad (`USING (true)`, `WITH CHECK (true)`, or equivalent)."
                 });
                 findings.push(finding({
                     ruleId: "supabase.rls.broad-policy",
@@ -51,7 +57,8 @@ export async function checkSupabase(input) {
                     suggestedFix: "Replace broad predicates with ownership checks such as `auth.uid() = user_id` or a tenant membership join."
                 }));
             }
-            if (!/\bauth\.uid\s*\(/i.test(predicate) && !ownershipColumnPattern.test(predicate) && sensitiveTablePattern.test(tableName)) {
+            const combinedPredicate = predicates.join(" ");
+            if (!/\bauth\.uid\s*\(/i.test(combinedPredicate) && !ownershipColumnPattern.test(combinedPredicate) && sensitiveTablePattern.test(tableName)) {
                 riskyPolicies.push({
                     file: file.path,
                     line,
@@ -69,18 +76,28 @@ export async function checkSupabase(input) {
                     suggestedFix: "Reference `auth.uid()` and a stable ownership or membership column in every sensitive table policy."
                 }));
             }
+            if (sensitiveTablePattern.test(tableName) && hasWeakWithCheck(policy)) {
+                riskyPolicies.push({
+                    file: file.path,
+                    line,
+                    policyName,
+                    tableName,
+                    reason: "Write policy has a weak or missing `WITH CHECK` predicate."
+                });
+                findings.push(finding({
+                    ruleId: "supabase.rls.weak-with-check",
+                    title: `Supabase write policy "${policyName}" has a weak WITH CHECK predicate`,
+                    severity: "high",
+                    evidence: [{ file: file.path, line, snippet: lineAt(file.content, line) }],
+                    why: "A write policy can read the right tenant rows but still allow inserted or updated rows to move into another owner or tenant unless `WITH CHECK` is scoped.",
+                    suggestedVerification: "As User A, try inserting or updating a row with User B's owner, organization, workspace, or tenant ID and confirm the database rejects it.",
+                    suggestedFix: "Add a `WITH CHECK` predicate tied to `auth.uid()` and the same owner, tenant, or membership relationship used by the read policy."
+                }));
+            }
         }
-        for (const match of file.content.matchAll(/storage\.buckets[\s\S]{0,200}\bpublic\b\s*[,=]\s*true|create\s+policy[\s\S]{0,200}\bstorage\.objects[\s\S]{0,200}using\s*\(\s*true\s*\)/gi)) {
+        for (const match of file.content.matchAll(/storage\.buckets[\s\S]{0,200}\bpublic\b\s*[,=]\s*true/gi)) {
             const line = lineNumberForIndex(file.content, match.index ?? 0);
-            findings.push(finding({
-                ruleId: "supabase.storage.public-bucket",
-                title: "Supabase storage policy or bucket appears public",
-                severity: "high",
-                evidence: [{ file: file.path, line, snippet: lineAt(file.content, line) }],
-                why: "Public buckets can expose uploads, invoices, profile documents, or tenant files even when database rows are protected.",
-                suggestedVerification: "Upload a private file as User A and confirm unauthenticated users and User B cannot fetch it by URL.",
-                suggestedFix: "Make buckets private by default and add storage object policies scoped by owner or tenant."
-            }));
+            findings.push(storageFinding(file.path, file.content, line, "Supabase storage bucket appears public"));
         }
     }
     for (const table of tables) {
@@ -124,3 +141,100 @@ export async function checkSupabase(input) {
 function normalizeSqlIdentifier(value) {
     return value.replace(/"/g, "").trim().toLowerCase();
 }
+function parsePolicies(content) {
+    const policies = [];
+    const policyPattern = /create\s+policy\s+(?:"([^"]+)"|([^\s\n]+))\s+on\s+([a-zA-Z0-9_."]+)[\s\S]*?;/gi;
+    for (const match of content.matchAll(policyPattern)) {
+        const statement = match[0];
+        policies.push({
+            name: (match[1] ?? match[2] ?? "").trim(),
+            tableName: normalizeSqlIdentifier(match[3]),
+            operation: parsePolicyOperation(statement),
+            usingPredicate: extractPredicate(statement, "using"),
+            withCheckPredicate: extractPredicate(statement, "with check"),
+            statement,
+            line: lineNumberForIndex(content, match.index ?? 0)
+        });
+    }
+    return policies;
+}
+function parsePolicyOperation(statement) {
+    const match = /\bfor\s+(select|insert|update|delete|all)\b/i.exec(statement);
+    const operation = match?.[1]?.toLowerCase();
+    if (operation === "select" ||
+        operation === "insert" ||
+        operation === "update" ||
+        operation === "delete" ||
+        operation === "all") {
+        return operation;
+    }
+    return "unknown";
+}
+function extractPredicate(statement, clause) {
+    const clausePattern = clause === "using" ? /\busing\s*\(/i : /\bwith\s+check\s*\(/i;
+    const match = clausePattern.exec(statement);
+    if (!match)
+        return undefined;
+    const openParen = match.index + match[0].lastIndexOf("(");
+    return extractBalancedParentheses(statement, openParen);
+}
+function extractBalancedParentheses(value, openParen) {
+    let depth = 0;
+    let inSingleQuote = false;
+    for (let index = openParen; index < value.length; index += 1) {
+        const char = value[index];
+        const next = value[index + 1];
+        if (char === "'" && next === "'") {
+            index += 1;
+            continue;
+        }
+        if (char === "'") {
+            inSingleQuote = !inSingleQuote;
+            continue;
+        }
+        if (inSingleQuote)
+            continue;
+        if (char === "(")
+            depth += 1;
+        if (char === ")") {
+            depth -= 1;
+            if (depth === 0)
+                return value.slice(openParen + 1, index).trim();
+        }
+    }
+    return undefined;
+}
+function isBroadPredicate(predicate) {
+    return predicate.trim().toLowerCase() === "true";
+}
+function hasWeakWithCheck(policy) {
+    if (policy.operation !== "insert" && policy.operation !== "update" && policy.operation !== "all")
+        return false;
+    if (!policy.withCheckPredicate)
+        return policy.operation === "insert";
+    if (isBroadPredicate(policy.withCheckPredicate))
+        return true;
+    return !isScopedOwnershipPredicate(policy.withCheckPredicate);
+}
+function isScopedOwnershipPredicate(predicate) {
+    return /\bauth\.uid\s*\(/i.test(predicate) && ownershipColumnPattern.test(predicate);
+}
+function isStorageObjectsTable(tableName) {
+    return tableName === "storage.objects";
+}
+function isUnscopedStoragePredicate(predicate) {
+    if (isBroadPredicate(predicate))
+        return true;
+    return !/\bauth\.uid\s*\(|\bowner\b|\bowner_id\b|\buser_id\b|\btenant_id\b|\borganization_id\b|\bworkspace_id\b/i.test(predicate);
+}
+function storageFinding(filePath, content, line, title) {
+    return finding({
+        ruleId: "supabase.storage.public-bucket",
+        title,
+        severity: "high",
+        evidence: [{ file: filePath, line, snippet: lineAt(content, line) }],
+        why: "Storage object policies or public buckets can expose tenant files even when database rows are protected.",
+        suggestedVerification: "Upload a private file as User A and confirm unauthenticated users and User B cannot fetch it by URL or object path.",
+        suggestedFix: "Keep buckets private and scope storage object policies by `owner`, `auth.uid()`, tenant, workspace, or a membership relationship."
+    });
+}

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

package/docs/npm-publishing.md

@@ -5,10 +5,10 @@
 ## Current State
 
 - Package name: `ai-saas-guard`
-- Current version: `0.3.0`
+- Current version: `0.5.0`
 - npm registry state: published at <https://www.npmjs.com/package/ai-saas-guard>
 - First npm-published version: `0.1.1`
-- GitHub Release: `v0.3.0`
+- GitHub Release: `v0.5.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.3.0`.
+1. Create and review a release tag such as `v0.5.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,7 +40,8 @@ Implemented surfaces:
 
 - secret-like values and risky public env exposure
 - Stripe webhook signature, raw body, idempotency, and lifecycle handler heuristics
-- Supabase RLS, broad policy, ownership filter, and public storage heuristics
+- Stripe webhook replay cookbook for checkout, renewal failure, 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
 - Next/Vercel deploy and runtime footguns
@@ -100,8 +101,6 @@ GitHub Project:
 Current issue set:
 
 - #1 Add launch-readiness checklist content
-- #5 Write Stripe webhook replay cookbook
-- #7 Expand Supabase RLS fixtures and ownership patterns
 
 CI:
 
@@ -113,7 +112,7 @@ CI:
 Publishing:
 
 - npm package: `ai-saas-guard`
-- Current release line: `v0.3.0`
+- Current release line: `v0.5.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.
@@ -140,11 +139,9 @@ Not allowed:
 
 Recommended order:
 
-1. Expand Supabase RLS fixtures and ownership patterns.
-2. Write Stripe webhook replay cookbook.
-3. Add launch-readiness checklist content.
-4. Improve false-positive suppression and rule stability labels.
-5. Add a GitHub App design note for the potential hosted layer.
+1. Add launch-readiness checklist content.
+2. Improve false-positive suppression and rule stability labels.
+3. Add a GitHub App design note for the potential hosted layer.
 
 For every feature, keep the scanner evidence-first:
 

package/docs/rules.md

@@ -27,11 +27,12 @@ Rule metadata is centralized in `src/rules/catalog.ts` and covered by tests so S
 
 | Rule ID | Severity | Why it exists |
 | --- | --- | --- |
-| `supabase.rls.broad-policy` | critical | `USING (true)` often turns login into public data access. |
+| `supabase.rls.broad-policy` | critical | `USING (true)` or `WITH CHECK (true)` can turn login into broad data access or writes. |
 | `supabase.rls.missing-ownership-filter` | high | Policies need resource ownership or tenant membership checks. |
+| `supabase.rls.weak-with-check` | high | Write policies need `WITH CHECK` predicates tied to the current user or tenant membership. |
 | `supabase.table.missing-owner-column` | medium | Sensitive tables are hard to protect without owner/tenant keys. |
 | `supabase.rls.not-enabled` | critical | User-data tables should enable row level security. |
-| `supabase.storage.public-bucket` | high | Storage buckets can leak files even when database rows are protected. |
+| `supabase.storage.public-bucket` | high | Storage buckets or unscoped storage object policies can leak files even when database rows are protected. |
 
 ## API Routes And Deploy
 

package/docs/stripe-webhook-replay.md

@@ -0,0 +1,206 @@
+# Stripe Webhook Replay Cookbook
+
+Use this cookbook after `ai-saas-guard check-stripe` flags missing signature checks, missing idempotency, missing lifecycle handlers, or unclear entitlement updates.
+
+It is a local test workflow for reviewers. It does not prove the production integration is secure, and it does not replace Stripe Dashboard checks, production endpoint configuration review, or two-account authorization tests.
+
+## Preconditions
+
+- Run against a sandbox or test-mode Stripe account.
+- Start the app locally with the same webhook route code that will be deployed.
+- Use fake local users and test subscriptions only.
+- Do not paste real API keys, signing secrets, customer data, or production URLs into issue comments or logs.
+- Make sure your handler verifies the `Stripe-Signature` header with Stripe's raw request body before changing billing state.
+
+Start local forwarding in one terminal:
+
+```bash
+stripe listen --forward-to localhost:3000/api/stripe/webhook
+```
+
+Copy the signing secret printed by `stripe listen` into your local server-only environment variable. Keep it out of client bundles and public logs.
+
+In another terminal, run the scanner first:
+
+```bash
+npx ai-saas-guard@latest check-stripe --root .
+```
+
+Use the findings as the review queue. Each finding should map to at least one replay below.
+
+## What To Observe
+
+For every replay, record these four facts:
+
+| Question | Expected evidence |
+| --- | --- |
+| Did the webhook return `2xx` only after verification and reconciliation? | Server log or test assertion |
+| Was the Stripe event ID stored or deduped? | `event.id` row, unique key, or idempotency log |
+| Did app entitlement state change correctly? | Plan, access, seat, credit, or subscription status row |
+| Is the user-facing state consistent after refresh? | Dashboard, gated route, API response, or account page |
+
+Entitlement reconciliation means the app derives access from Stripe's current billing truth, then writes one durable local state. Typical examples are `plan`, `subscription_status`, `current_period_end`, `cancel_at_period_end`, active seats, credit balance, or an access table keyed by user, organization, customer, or subscription.
+
+## Replay Matrix
+
+Run the commands one at a time. Watch both the `stripe listen` terminal and your app server logs.
+
+| Scenario | Command | What to verify |
+| --- | --- | --- |
+| 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. |
+| 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. |
+
+If a command is not available in your installed Stripe CLI, run `stripe trigger --help` or the event category help such as `stripe trigger customer.subscription --help`, then use the closest supported test event for the same billing state transition.
+
+## Checkout Success
+
+```bash
+stripe trigger checkout.session.completed
+```
+
+Review checklist:
+
+- The handler rejects unsigned requests before any database write.
+- The handler stores or checks the Stripe `event.id`.
+- The session is linked to a local user, organization, or tenant through metadata, customer ID, or subscription ID.
+- The app does not grant access only from the success redirect page.
+- Refreshing the app shows access from database state, not from a one-time URL parameter.
+
+`ai-saas-guard` findings this can validate:
+
+- `stripe.webhook.missing-signature`
+- `stripe.webhook.no-entitlement-path`
+- `stripe.webhook.missing-idempotency`
+
+## Failed Invoice
+
+```bash
+stripe trigger invoice.payment_failed
+```
+
+Review checklist:
+
+- The local subscription is not left as fully active without a documented grace policy.
+- The app records failure state in the same entitlement system used by normal access checks.
+- Customer notification or billing portal recovery is queued if that is part of the product flow.
+- A later recovery event can move the account back to the intended state without manual database edits.
+
+`ai-saas-guard` findings this can validate:
+
+- `stripe.webhook.missing-critical-event`
+- `stripe.webhook.no-entitlement-path`
+
+## Subscription Update
+
+```bash
+stripe trigger customer.subscription.updated
+```
+
+Review checklist:
+
+- Plan upgrades and downgrades update the local plan or entitlement rows.
+- Seat quantity changes do not leave stale access.
+- `cancel_at_period_end` and period boundaries are persisted if the app uses them.
+- The handler reconciles from Stripe identifiers instead of trusting a client-provided user ID.
+
+`ai-saas-guard` findings this can validate:
+
+- `stripe.webhook.missing-critical-event`
+- `stripe.webhook.no-entitlement-path`
+
+## Cancellation
+
+```bash
+stripe trigger customer.subscription.deleted
+```
+
+Review checklist:
+
+- The correct user, organization, or tenant loses paid access.
+- Shared team access is downgraded consistently, not only the account owner.
+- The app handles repeated cancellation events without throwing or creating inconsistent rows.
+- Historical records remain available only according to product policy.
+
+`ai-saas-guard` findings this can validate:
+
+- `stripe.webhook.missing-critical-event`
+- `stripe.webhook.missing-idempotency`
+
+## Refund
+
+```bash
+stripe trigger charge.refunded
+```
+
+Review checklist:
+
+- Refund handling is explicit, even if the intended action is "record and review manually."
+- Credits, invoices, or access extensions are not applied twice.
+- Refund events do not bypass subscription status checks.
+- Support/admin workflows have enough evidence to understand which customer, invoice, and subscription were involved.
+
+`ai-saas-guard` findings this can validate:
+
+- `stripe.webhook.missing-critical-event`
+- `stripe.webhook.no-entitlement-path`
+
+## Duplicate Event Replay
+
+Stripe can retry events, and the same event can reach your handler more than once. Your handler should be idempotent around the Stripe event ID and the domain object it mutates.
+
+Practical replay:
+
+```bash
+stripe trigger checkout.session.completed
+```
+
+Then replay the same captured event through your own test harness, fixture, or integration test. The important assertion is not that the Stripe CLI creates the same event twice; it is that your app has a test path where the same `event.id` is processed twice and the second attempt is a no-op.
+
+Review checklist:
+
+- `event.id` is stored with a unique constraint or equivalent dedupe guard.
+- The second delivery returns success without repeating fulfillment.
+- Access grants, invoices, credits, seats, and emails are not duplicated.
+- The handler is safe if the first attempt partially wrote state and then crashed.
+
+`ai-saas-guard` findings this can validate:
+
+- `stripe.webhook.missing-idempotency`
+
+## Out-of-Order Event Questions
+
+Stripe events should be treated as signals to reconcile state, not as a guarantee that the app saw every prior transition in the expected order.
+
+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 `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?
+
+When possible, add tests that call the entitlement reconciliation function directly with events in a different order. The durable result should match Stripe's current billing truth and the product's explicit grace/cancellation policy.
+
+## Minimal Acceptance Checklist
+
+Before launch or merge, a reviewer should be able to answer yes to each item:
+
+- Unsigned webhook requests are rejected before database writes.
+- Raw request body is used for signature verification.
+- 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.
+- `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.
+- Duplicate deliveries are no-ops after the first successful reconciliation.
+- Out-of-order events reconcile to one durable local entitlement state.
+
+## Source Links
+
+- Stripe CLI trigger docs: https://docs.stripe.com/stripe-cli/triggers
+- Stripe CLI forwarding docs: https://docs.stripe.com/stripe-cli/use-cli
+- Stripe webhook signature docs: https://docs.stripe.com/webhooks/signature

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-saas-guard",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Repo-local launch-readiness scanner for AI-built SaaS apps.",
   "type": "module",
   "homepage": "https://github.com/zr9959/ai-saas-guard#readme",