ai-saas-guard 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +7 -4
  2. package/docs/github-action.md +1 -1
  3. package/docs/launch-readiness-checklist.md +191 -0
  4. package/docs/npm-publishing.md +3 -3
  5. package/docs/project-handoff.md +5 -5
  6. package/package.json +1 -1
package/README.md CHANGED
@@ -51,8 +51,8 @@ The CLI is published on npm as `ai-saas-guard`, and the GitHub Action is availab
51
51
  | JSON and SARIF output | Available |
52
52
  | Composite GitHub Action | Available |
53
53
  | Project config | `.ai-saas-guard.json` rule toggles, severity overrides, and fail thresholds |
54
- | Versioned Action tags | `v0.5.0`, `v0` |
55
- | npm package | `ai-saas-guard@0.5.0` |
54
+ | Versioned Action tags | `v0.6.0`, `v0` |
55
+ | npm package | `ai-saas-guard@0.6.0` |
56
56
  | npm publishing | Trusted Publisher/OIDC, no long-lived publish token |
57
57
 
58
58
  ## Quick Start
@@ -170,6 +170,10 @@ If `--base` cannot be resolved, `pr-risk` emits `pr-risk.diff-unavailable` inste
170
170
  | `check-stripe` | Inspect webhook handlers and billing lifecycle coverage |
171
171
  | `check-mcp` | Inventory MCP configs and classify side effects |
172
172
 
173
+ ## Launch Readiness Checklist
174
+
175
+ Use [docs/launch-readiness-checklist.md](docs/launch-readiness-checklist.md) when an app is close to inviting real users. It explains how to combine `ai-saas-guard` output with manual two-account authorization testing, Stripe webhook verification, MCP config review, Supabase policy review, deploy checks, rollback planning, and a clear reminder that this is not a full security audit.
176
+
173
177
  ## Stripe Webhook Replay
174
178
 
175
179
  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.
@@ -195,7 +199,7 @@ Add `.ai-saas-guard.json` at the repository root to tune findings without changi
195
199
 
196
200
  ## GitHub Action
197
201
 
198
- 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:
202
+ The repo includes a composite Action. Use `v0` for the latest compatible pre-1.0 Action, a specific release tag such as `v0.6.0` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
199
203
 
200
204
  ```yaml
201
205
  name: ai-saas-guard
@@ -324,7 +328,6 @@ Open-source core:
324
328
 
325
329
  Near-term priorities:
326
330
 
327
- - launch-readiness checklist content
328
331
  - false-positive suppression and rule stability labels
329
332
  - GitHub App design note for the potential hosted layer
330
333
 
package/docs/github-action.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  `ai-saas-guard` ships as a composite GitHub Action for pull request and code scanning workflows.
4
4
 
5
- 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.
5
+ Use `zr9959/ai-saas-guard@v0` for the latest compatible pre-1.0 Action. Use a specific tag such as `v0.6.0` or a reviewed commit SHA when reproducibility is more important than automatic minor updates.
6
6
 
7
7
  ## PR Summary
8
8
 
package/docs/launch-readiness-checklist.md ADDED
@@ -0,0 +1,191 @@
1
+ # Launch Readiness Checklist
2
+
3
+ Use this checklist when an AI-built SaaS app is close to launch, a founder is about to invite real users, or a reviewer needs a practical pre-merge review path.
4
+
5
+ This is not a full security audit, penetration test, compliance review, or proof that the app is secure. It is a founder-readable launch preflight that combines `ai-saas-guard` findings with manual verification for the most common SaaS launch blockers.
6
+
7
+ ## Start With The Local Preflight
8
+
9
+ Run from the app repository:
10
+
11
+ ```bash
12
+ npx ai-saas-guard@latest scan --root .
13
+ npx ai-saas-guard@latest pr-risk --root . --base origin/main
14
+ npx ai-saas-guard@latest check-supabase --root .
15
+ npx ai-saas-guard@latest check-stripe --root .
16
+ npx ai-saas-guard@latest check-mcp --root .
17
+ ```
18
+
19
+ Treat every finding as a review queue item. The tool is read-only and local-first, so it can show where to inspect, but it cannot confirm production settings, account ownership, live Stripe dashboard state, or every possible authorization path.
20
+
21
+ ## Launch Blocker Rules
22
+
23
+ Use these labels while reviewing:
24
+
25
+ | Level | Meaning | Examples |
26
+ | --- | --- | --- |
27
+ | Launch blocker | Do not ship until fixed or explicitly disabled for the product. | Any user can read another tenant's data, unsigned Stripe webhooks grant access, real secrets are committed. |
28
+ | Must verify | Shipping may be reasonable only after a named manual test passes. | Rate limits, billing lifecycle handling, storage object scope, rollback path. |
29
+ | Follow-up | Track after launch when the current product risk is bounded. | Extra docs, sharper false-positive suppression, non-critical workflow polish. |
30
+
31
+ If a finding affects auth, billing, user data, secrets, file storage, production deploy config, or MCP tools with side effects, assume it is at least "must verify" until a human has tested the exact path.
32
+
33
+ ## Two-Account Authorization Testing
34
+
35
+ Two-account authorization testing is the fastest manual check for broken SaaS isolation.
36
+
37
+ Prepare two ordinary test accounts:
38
+
39
+ - User A in organization or workspace A.
40
+ - User B in organization or workspace B.
41
+ - At least one private object owned by each account or workspace: project, document, invoice, file, message, API key, or team member.
42
+
43
+ Verify read isolation:
44
+
45
+ - Log in as User A and open User A's private objects.
46
+ - Try to load User B's object by changing route parameters, object IDs, slugs, search filters, API URLs, and browser history entries.
47
+ - Repeat the same checks through direct API calls if the app exposes JSON routes.
48
+ - Confirm User A receives a 403 or 404 and no object metadata leaks in the response.
49
+
50
+ Verify write isolation:
51
+
52
+ - As User A, try to update, delete, invite users to, export, or share User B's objects by tampering with IDs.
53
+ - Confirm the server rejects the request, not only the UI.
54
+ - Confirm no partial write, audit entry, billing change, storage object, notification, or background job was created.
55
+
56
+ Verify tenant switching:
57
+
58
+ - If a user can belong to multiple workspaces, switch active workspaces and repeat the same read/write checks.
59
+ - Confirm server-side ownership checks use the selected tenant membership, not only a client-side workspace ID.
60
+
61
+ For Supabase apps, compare these manual checks with row-level security policy evidence from `check-supabase`. RLS should protect sensitive tables even when a route, query builder, or generated client code is wrong.
62
+
63
+ ## Stripe Webhook Verification
64
+
65
+ Stripe webhook verification is required for subscription or credit products because checkout redirects are not billing truth.
66
+
67
+ Minimum checks:
68
+
69
+ - The webhook route reads the raw request body.
70
+ - The handler verifies the `Stripe-Signature` header with the server-only webhook secret before any database write.
71
+ - The signing secret is never exposed through `NEXT_PUBLIC_*`, client bundles, public logs, issue comments, or screenshots.
72
+ - The handler stores or dedupes `event.id`.
73
+ - Entitlement state is updated from Stripe webhook reconciliation, not only from checkout success pages.
74
+
75
+ Replay the critical billing paths with the companion cookbook:
76
+
77
+ ```bash
78
+ stripe listen --forward-to localhost:3000/api/stripe/webhook
79
+ stripe trigger checkout.session.completed
80
+ stripe trigger invoice.payment_failed
81
+ stripe trigger customer.subscription.updated
82
+ stripe trigger customer.subscription.deleted
83
+ stripe trigger charge.refunded
84
+ ```
85
+
86
+ Expected evidence:
87
+
88
+ - Checkout success grants the right user or tenant access only after signature verification.
89
+ - Failed invoice creates the intended past-due or grace state.
90
+ - Subscription updates reconcile plan, quantity, status, cancellation, and period fields.
91
+ - Cancellation revokes or downgrades paid access.
92
+ - Refund handling is explicit, even if the product requires manual review.
93
+ - Duplicate delivery of the same event ID is a no-op.
94
+ - Out-of-order events reconcile to one durable entitlement state.
95
+
96
+ See [stripe-webhook-replay.md](stripe-webhook-replay.md) for the full command cookbook.
97
+
98
+ ## MCP Config Review
99
+
100
+ MCP config review matters because local tools can turn prompt injection into filesystem, shell, database, or network side effects.
101
+
102
+ Inventory every MCP server used by the app, agent, or development workflow:
103
+
104
+ - Config files such as `.mcp.json`, `.cursor/mcp.json`, `claude_desktop_config.json`, or tool-specific equivalents.
105
+ - Tool descriptions that expose shell commands, raw SQL, browser automation, filesystem writes, or deployment actions.
106
+ - Environment variables and credentials passed to MCP servers.
107
+ - Bind addresses and transport URLs.
108
+
109
+ Review questions:
110
+
111
+ - Does any MCP server bind to `0.0.0.0` or a non-localhost host?
112
+ - Does any tool allow broad filesystem read/write access outside the intended repository?
113
+ - Does any tool run arbitrary shell commands or raw SQL against production-like data?
114
+ - Are credentials stored in plaintext config files?
115
+ - Are secret-bearing config files group-readable or world-readable?
116
+ - Can the tool mutate billing, user access, customer data, or deploy state without a human approval step?
117
+
118
+ Launch blocker examples:
119
+
120
+ - A production database URL is stored in an MCP config.
121
+ - A broad filesystem tool can write outside the app repository.
122
+ - A shell or SQL tool is exposed to untrusted prompts without environment separation.
123
+
124
+ Use `check-mcp` findings as the starting inventory, then manually inspect any tool that can read secrets or change state.
125
+
126
+ ## Supabase And Storage
127
+
128
+ For Supabase apps, launch only after the data model has an ownership story.
129
+
130
+ Check:
131
+
132
+ - Sensitive tables have RLS enabled.
133
+ - Policies use `auth.uid()` or tenant membership checks tied to the row.
134
+ - Write policies use `WITH CHECK` so users cannot insert or move rows into another tenant.
135
+ - Storage buckets and `storage.objects` policies are scoped by owner, tenant, or object path.
136
+ - Service-role keys stay server-only and are not used in browser code.
137
+
138
+ Manual verification should still use the two-account flow above. Scanner findings can point to weak policies, but the actual product workflow determines whether access is correctly isolated.
139
+
140
+ ## Secrets, Env, And Deploy
141
+
142
+ Before launch:
143
+
144
+ - Rotate any real secret that was committed, pasted into a public issue, or printed in a public log.
145
+ - Confirm examples use inert placeholders, not real-looking provider tokens.
146
+ - Confirm `NEXT_PUBLIC_*` variables contain only values that are safe for browsers.
147
+ - Check `.env.example` or deploy docs include required production variables without revealing secret values.
148
+ - Confirm Vercel, Netlify, or other deploy settings match runtime expectations: API routes are not accidentally static, and Node-only libraries are not deployed to incompatible Edge runtimes.
149
+
150
+ ## CI And PR Review
151
+
152
+ Minimum repository workflow:
153
+
154
+ - CI runs tests on pull requests and pushes to the default branch.
155
+ - `ai-saas-guard pr-risk` runs with enough git history to compare against the base branch.
156
+ - SARIF or markdown output is used when reviewers need scan results in GitHub.
157
+ - Large AI-generated pull requests are split when they combine UI, auth, database, billing, and deploy changes.
158
+
159
+ Review the first files named by `pr-risk` before reviewing cosmetic changes. If a base ref is missing, fix checkout depth or fetch history before trusting the PR risk result.
160
+
161
+ ## Rollback And Incident Readiness
162
+
163
+ Before inviting real users, define:
164
+
165
+ - How to disable paid access changes without deleting customer data.
166
+ - How to revoke or rotate leaked keys.
167
+ - How to roll back a failed deployment.
168
+ - How to pause new signups or billing flows.
169
+ - Where webhook delivery failures, auth errors, and database policy denials are logged.
170
+ - Who decides whether a finding is a launch blocker or an accepted risk.
171
+
172
+ The goal is not a perfect process. The goal is that the founder can answer what happens when auth, billing, deploy, or data isolation fails on launch day.
173
+
174
+ ## Founder Sign-Off
175
+
176
+ A launch-ready review should leave behind short evidence, not just a feeling.
177
+
178
+ Use this minimal sign-off:
179
+
180
+ | Area | Evidence to keep |
181
+ | --- | --- |
182
+ | CLI preflight | Command output or CI link for `scan` and focused checks |
183
+ | Two-account authorization | User A/User B notes with tested object types and rejected actions |
184
+ | Stripe | Webhook replay notes for success, failure, update, cancellation, refund, duplicate, and out-of-order paths |
185
+ | Supabase | RLS and storage policy review notes |
186
+ | MCP | Reviewed MCP config files and disabled or constrained risky tools |
187
+ | Secrets | Rotation notes or confirmation that only placeholders were found |
188
+ | Deploy | Production env and runtime checks |
189
+ | Rollback | Known rollback command or deploy platform rollback path |
190
+
191
+ If any row is blank for a product surface the app actually uses, treat it as a must-verify item before launch.
package/docs/npm-publishing.md CHANGED
@@ -5,10 +5,10 @@
5
5
  ## Current State
6
6
 
7
7
  - Package name: `ai-saas-guard`
8
- - Current version: `0.5.0`
8
+ - Current version: `0.6.0`
9
9
  - npm registry state: published at <https://www.npmjs.com/package/ai-saas-guard>
10
10
  - First npm-published version: `0.1.1`
11
- - GitHub Release: `v0.5.0`
11
+ - GitHub Release: `v0.6.0`
12
12
  - Publish workflow: `.github/workflows/npm-publish.yml`
13
13
  - Trusted Publisher: GitHub Actions, `zr9959/ai-saas-guard`, workflow `npm-publish.yml`, allowed action `npm publish`
14
14
  - Long-lived npm publish token: not required
@@ -17,7 +17,7 @@
17
17
 
18
18
  Use GitHub Actions with npm Trusted Publisher/OIDC:
19
19
 
20
- 1. Create and review a release tag such as `v0.5.0`.
20
+ 1. Create and review a release tag such as `v0.6.0`.
21
21
  2. Publish from the GitHub Release or run the `Publish npm` workflow manually with `ref` set to that tag.
22
22
  3. Keep `permissions.id-token: write` in the workflow so npm can exchange the GitHub Actions OIDC identity for a short-lived publish credential.
23
23
  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 CHANGED
@@ -39,6 +39,7 @@ Do not market it as a full pentest, full SAST platform, or proof that an app is
39
39
  Implemented surfaces:
40
40
 
41
41
  - secret-like values and risky public env exposure
42
+ - founder-readable launch-readiness checklist for two-account authorization, Stripe webhook verification, MCP config review, Supabase, deploy, CI, and rollback checks
42
43
  - Stripe webhook signature, raw body, idempotency, and lifecycle handler heuristics
43
44
  - Stripe webhook replay cookbook for checkout, renewal failure, updates, cancellation, refunds, duplicate delivery, and out-of-order review
44
45
  - Supabase RLS, tenant membership, ownership filter, weak `WITH CHECK`, and storage object policy heuristics
@@ -100,7 +101,7 @@ GitHub Project:
100
101
 
101
102
  Current issue set:
102
103
 
103
- - #1 Add launch-readiness checklist content
104
+ - No open roadmap issues after the `v0.6.0` checklist release.
104
105
 
105
106
  CI:
106
107
 
@@ -112,7 +113,7 @@ CI:
112
113
  Publishing:
113
114
 
114
115
  - npm package: `ai-saas-guard`
115
- - Current release line: `v0.5.0`
116
+ - Current release line: `v0.6.0`
116
117
  - Publish workflow: `.github/workflows/npm-publish.yml`
117
118
  - Trusted Publisher: GitHub Actions for `zr9959/ai-saas-guard`, workflow `npm-publish.yml`
118
119
  - Long-lived npm publish tokens should not be required.
@@ -139,9 +140,8 @@ Not allowed:
139
140
 
140
141
  Recommended order:
141
142
 
142
- 1. Add launch-readiness checklist content.
143
- 2. Improve false-positive suppression and rule stability labels.
144
- 3. Add a GitHub App design note for the potential hosted layer.
143
+ 1. Improve false-positive suppression and rule stability labels.
144
+ 2. Add a GitHub App design note for the potential hosted layer.
145
145
 
146
146
  For every feature, keep the scanner evidence-first:
147
147
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ai-saas-guard",
3
- "version": "0.5.0",
3
+ "version": "0.6.0",
4
4
  "description": "Repo-local launch-readiness scanner for AI-built SaaS apps.",
5
5
  "type": "module",
6
6
  "homepage": "https://github.com/zr9959/ai-saas-guard#readme",