ai-saas-guard 0.4.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.4.0`, `v0` |
-| npm package | `ai-saas-guard@0.4.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
@@ -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.4.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,7 +324,6 @@ Open-source core:
 
 Near-term priorities:
 
-- Stripe webhook replay cookbook
 - launch-readiness checklist content
 - false-positive suppression and rule stability labels
 - GitHub App design note for the potential hosted layer

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/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.4.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.4.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.4.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.4.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,6 +40,7 @@ Implemented surfaces:
 
 - secret-like values and risky public env exposure
 - 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
 - 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
@@ -100,7 +101,6 @@ GitHub Project:
 Current issue set:
 
 - #1 Add launch-readiness checklist content
-- #5 Write Stripe webhook replay cookbook
 
 CI:
 
@@ -112,7 +112,7 @@ CI:
 Publishing:
 
 - npm package: `ai-saas-guard`
-- Current release line: `v0.4.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.
@@ -139,10 +139,9 @@ Not allowed:
 
 Recommended order:
 
-1. Write Stripe webhook replay cookbook.
-2. Add launch-readiness checklist content.
-3. Improve false-positive suppression and rule stability labels.
-4. 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/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.4.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",