ai-saas-guard 0.29.1 → 0.29.2

package/README.md

@@ -60,23 +60,40 @@ npx ai-saas-guard@latest pr-risk --root /path/to/your-saas --base origin/main --
 
 You get rule IDs, severity, file evidence, why it matters, how to verify it manually, and a concrete fix direction. The scanner is deterministic, read-only, and does not call an LLM.
 
+## Try The Demo Fixtures
+
+Want to see the report before scanning your own repo?
+
+```bash
+git clone https://github.com/zr9959/ai-saas-guard.git
+cd ai-saas-guard
+npx ai-saas-guard@latest scan --root examples/demo-risky-saas
+npx ai-saas-guard@latest scan --root examples/demo-safe-saas
+```
+
+The risky demo currently returns 19 intentional findings across Stripe, Supabase, silent-success paths, Next/Vercel deploy hints, and GitHub Actions. The safe demo returns 0 findings for the same broad surfaces with safer static patterns. See [docs/demo-quickstart.md](docs/demo-quickstart.md).
+
 ## See The Output
 
 The report is designed to be read before launch or before merging an AI-heavy PR. A longer copy-paste example is in [docs/sample-launch-report.md](docs/sample-launch-report.md).
 
 ```text
 Launch Gate: review before launch
-4 findings: 1 high, 3 medium
+19 findings: 2 critical, 6 high, 7 medium, 3 low, 1 info
 
-HIGH stripe.webhook.missing-signature
+CRITICAL stripe.webhook.missing-signature
 File: app/api/stripe/webhook/route.ts
 Why: billing access can be granted from a webhook path that does not verify Stripe signatures.
 Verify: replay a webhook with an invalid signature and confirm the route rejects it.
 Fix: read the raw body, call stripe.webhooks.constructEvent, and make event handling idempotent.
 
-MEDIUM supabase.rls.tenant-predicate-missing
-File: supabase/migrations/20260524_accounts.sql
-Verify: sign in as user A and user B; confirm neither can SELECT or UPDATE the other's rows.
+HIGH silent-success.swallowed-error
+File: app/api/billing/checkout/route.ts
+Verify: force the upstream billing call to fail and confirm the route returns an error, not fake success.
+
+MEDIUM deploy.next.missing-security-headers
+File: app/api/billing/checkout/route.ts
+Verify: inspect production response headers for auth, billing, and API pages.
 ```
 
 ## What You Get
@@ -162,13 +179,13 @@ The CLI is published on npm as `ai-saas-guard`, and the GitHub Action is availab
 | Area | Status |
 | --- | --- |
 | Public GitHub repository | Available |
-| npm CLI | `ai-saas-guard@0.29.1` |
-| GitHub Action | `zr9959/ai-saas-guard@v0` or fixed tag `v0.29.1` |
+| npm CLI | `ai-saas-guard@0.29.2` |
+| GitHub Action | `zr9959/ai-saas-guard@v0` or fixed tag `v0.29.2` |
 | Outputs | Terminal, JSON, SARIF, and PR-focused markdown |
 | Project config | `.ai-saas-guard.json` rule toggles, severity overrides, suppressions, and fail thresholds |
 | Privacy model | Local-first, read-only scan commands, no LLM calls, no code upload |
-| Versioned Action tags | `v0.29.1`, `v0` |
-| Current release | `0.29.1` post-release onboarding polish: clearer README first screen, synced Chinese README, GitHub Action UX validation, and updated Action docs |
+| Versioned Action tags | `v0.29.2`, `v0` |
+| Current release | `0.29.2` publishes public risky/safe demo fixtures, a demo quickstart, quickstart feedback template, and refreshed first-run README guidance |
 | npm publishing | Trusted Publisher/OIDC, no long-lived publish token |
 | Repository trust hardening | Strict branch protection, Dependabot, CodeQL, fast-check fuzzing, signed release provenance assets, private vulnerability reporting, secret scanning, and push protection |
 | Cloudflare hosted ingress | Deployed at `https://ai-saas-guard-hosted.zr9959.workers.dev`; signed GitHub App webhook delivery and compact Check Run smoke now pass in staging |
@@ -335,7 +352,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.29.1` 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.29.2` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
 
 ```yaml
 name: ai-saas-guard

package/docs/README.zh-CN.md

@@ -59,23 +59,40 @@ npx ai-saas-guard@latest pr-risk --root /path/to/your-saas --base origin/main --
 
 你会得到 rule ID、severity、文件证据、为什么重要、如何人工验证，以及具体修复方向。扫描是 deterministic、只读的，不调用 LLM。
 
+## 先试公开 demo
+
+如果你还不想先扫自己的私有仓库，可以先跑公开 fixture：
+
+```bash
+git clone https://github.com/zr9959/ai-saas-guard.git
+cd ai-saas-guard
+npx ai-saas-guard@latest scan --root examples/demo-risky-saas
+npx ai-saas-guard@latest scan --root examples/demo-safe-saas
+```
+
+risky demo 当前会故意触发 19 个 finding，覆盖 Stripe、Supabase、silent-success、Next/Vercel deploy 提示和 GitHub Actions。safe demo 在同类风险面上使用更安全的静态写法，当前返回 0 个 finding。说明见 [demo-quickstart.md](demo-quickstart.md)。
+
 ## 输出长什么样
 
 报告是给上线前或合并 AI 大 PR 前快速阅读的。更完整的可复制样例见 [docs/sample-launch-report.md](sample-launch-report.md)。
 
 ```text
 Launch Gate: review before launch
-4 findings: 1 high, 3 medium
+19 findings: 2 critical, 6 high, 7 medium, 3 low, 1 info
 
-HIGH stripe.webhook.missing-signature
+CRITICAL stripe.webhook.missing-signature
 File: app/api/stripe/webhook/route.ts
 Why: billing access can be granted from a webhook path that does not verify Stripe signatures.
 Verify: replay a webhook with an invalid signature and confirm the route rejects it.
 Fix: read the raw body, call stripe.webhooks.constructEvent, and make event handling idempotent.
 
-MEDIUM supabase.rls.tenant-predicate-missing
-File: supabase/migrations/20260524_accounts.sql
-Verify: sign in as user A and user B; confirm neither can SELECT or UPDATE the other's rows.
+HIGH silent-success.swallowed-error
+File: app/api/billing/checkout/route.ts
+Verify: force the upstream billing call to fail and confirm the route returns an error, not fake success.
+
+MEDIUM deploy.next.missing-security-headers
+File: app/api/billing/checkout/route.ts
+Verify: inspect production response headers for auth, billing, and API pages.
 ```
 
 ## 你会得到什么
@@ -144,18 +161,18 @@ node dist/cli.js scan --root /path/to/your-saas
 
 这个仓库是公开 GitHub 仓库。
 
-CLI 已发布到 npm：`ai-saas-guard@0.29.1`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.29.1`。
+CLI 已发布到 npm：`ai-saas-guard@0.29.2`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.29.2`。
 
 | 模块 | 状态 |
 | --- | --- |
 | 公开 GitHub 仓库 | 已可用 |
-| npm CLI | `ai-saas-guard@0.29.1` |
-| GitHub Action | `zr9959/ai-saas-guard@v0` 或固定标签 `v0.29.1` |
+| npm CLI | `ai-saas-guard@0.29.2` |
+| GitHub Action | `zr9959/ai-saas-guard@v0` 或固定标签 `v0.29.2` |
 | 输出格式 | Terminal、JSON、SARIF 和 PR markdown |
 | 项目配置 | `.ai-saas-guard.json` 支持规则开关、severity 覆盖、suppressions 和 fail threshold |
 | 隐私模型 | 本地优先、只读扫描、不调用 LLM、不上传代码 |
-| 当前版本 | `0.29.1` 发布后入口优化：README 首屏更清晰、中文 README 同步、GitHub Action UX 校验和 Action 文档更新 |
-| Action 标签 | `v0.29.1`、`v0` |
+| 当前版本 | `0.29.2` 发布公开 risky/safe demo fixtures、demo quickstart、quickstart 反馈模板，并刷新首次试用 README 指引 |
+| Action 标签 | `v0.29.2`、`v0` |
 | npm 发布 | GitHub Actions Trusted Publisher/OIDC，无需长期 npm token |
 | 仓库可信度加固 | 严格 branch protection、Dependabot、CodeQL、fast-check fuzzing、signed release provenance assets、private vulnerability reporting、secret scanning 和 push protection |
 | Cloudflare hosted ingress | 已部署到 `https://ai-saas-guard-hosted.zr9959.workers.dev`；签名 GitHub App webhook delivery 和 compact Check Run staging smoke 已通过 |

package/docs/demo-quickstart.md

@@ -0,0 +1,60 @@
+# Demo Quickstart
+
+Use these public fixtures when you want to understand `ai-saas-guard` before pointing it at a private repository.
+
+## Risky Demo
+
+```bash
+npx ai-saas-guard@latest scan --root examples/demo-risky-saas
+```
+
+The risky demo intentionally includes unsigned Stripe webhook handling, a silent-success billing fallback, broad Supabase RLS, and overpowered GitHub Actions permissions.
+
+Expected summary:
+
+```text
+19 findings: 2 critical, 6 high, 7 medium, 3 low, 1 info
+```
+
+The first findings should point at trust-boundary files such as:
+
+- `app/api/stripe/webhook/route.ts` for missing Stripe signature verification and idempotency
+- `supabase/migrations/001_accounts.sql` for broad RLS and missing tenant predicates
+- `app/api/billing/checkout/route.ts` for a silent-success billing fallback
+- `.github/workflows/ci.yml` for launch-related workflow hygiene hints
+
+For local development from this repository checkout:
+
+```bash
+npm ci
+npm run build
+node dist/cli.js scan --root examples/demo-risky-saas
+```
+
+## Safe Demo
+
+```bash
+npx ai-saas-guard@latest scan --root examples/demo-safe-saas
+```
+
+The safe demo keeps the same broad surfaces but uses safer static patterns: Stripe signature verification and idempotency hints, scoped RLS, security headers, documented env variables, request IDs, and bounded GitHub Actions permissions.
+
+Expected summary:
+
+```text
+0 findings
+```
+
+For local development from this repository checkout:
+
+```bash
+node dist/cli.js scan --root examples/demo-safe-saas
+```
+
+## What To Look For
+
+- Every finding has a rule ID, severity, file evidence, why it matters, a manual verification step, and a fix direction.
+- The risky demo is intentionally noisy enough to show the report shape.
+- The safe demo is intentionally small; it is not a complete SaaS template and does not certify a real app.
+
+Do not paste real API keys, customer data, private source code, webhook secrets, or production URLs into public issues when sharing output.

package/docs/npm-publishing.md

@@ -5,11 +5,11 @@
 ## Current State
 
 - Package name: `ai-saas-guard`
-- Current published version: `0.29.1`
+- Current published version: `0.29.2`
 - Next source candidate: none
 - npm registry state: published at <https://www.npmjs.com/package/ai-saas-guard>
 - First npm-published version: `0.1.1`
-- GitHub Release: `v0.29.1`
+- GitHub Release: `v0.29.2`
 - 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
@@ -18,7 +18,7 @@
 
 Use GitHub Actions with npm Trusted Publisher/OIDC:
 
-1. Create and review a release tag such as `v0.29.1`.
+1. Create and review a release tag such as `v0.29.2`.
 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/examples/demo-risky-saas/.github/workflows/ci.yml

@@ -0,0 +1,13 @@
+name: Risky demo CI
+
+on:
+  pull_request:
+
+permissions: write-all
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6.0.2
+      - run: npm test

package/examples/demo-risky-saas/README.md

@@ -0,0 +1,25 @@
+# Risky Demo SaaS
+
+This is a tiny public fixture that intentionally contains common AI-built SaaS launch risks.
+
+Run from the repository root:
+
+```bash
+node dist/cli.js scan --root examples/demo-risky-saas
+```
+
+Or with the published package:
+
+```bash
+npx ai-saas-guard@latest scan --root examples/demo-risky-saas
+```
+
+Expected themes:
+
+- unsigned Stripe webhook handling
+- silent-success billing fallback
+- broad Supabase RLS policy
+- over-broad GitHub Actions permissions
+- stale PR workflow risk
+
+This fixture uses inert placeholder code only. It does not contain real secrets, customer data, or production URLs.

package/examples/demo-risky-saas/app/api/billing/checkout/route.ts

@@ -0,0 +1,14 @@
+export async function POST() {
+  try {
+    return Response.json({ checkoutUrl: await createCheckout() });
+  } catch {
+    return Response.json({
+      success: true,
+      checkoutUrl: "/billing/demo-success"
+    });
+  }
+}
+
+async function createCheckout() {
+  throw new Error("provider unavailable");
+}

package/examples/demo-risky-saas/app/api/stripe/webhook/route.ts

@@ -0,0 +1,14 @@
+export async function POST(req: Request) {
+  const event = await req.json();
+
+  if (event.type === "checkout.session.completed") {
+    await grantAccess(event.data.object.customer);
+    return Response.json({ success: true });
+  }
+
+  return Response.json({ ok: true });
+}
+
+async function grantAccess(customerId: string) {
+  console.log("granting access", customerId);
+}

package/examples/demo-risky-saas/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "ai-saas-guard-demo-risky-saas",
+  "private": true,
+  "type": "module"
+}

package/examples/demo-risky-saas/supabase/migrations/001_accounts.sql

@@ -0,0 +1,14 @@
+create table public.accounts (
+  id uuid primary key,
+  tenant_id uuid not null,
+  user_id uuid not null,
+  plan text not null
+);
+
+alter table public.accounts enable row level security;
+
+create policy "public read accounts"
+on public.accounts
+for select
+to public
+using (true);

package/examples/demo-safe-saas/.env.example

@@ -0,0 +1,3 @@
+STRIPE_SECRET_KEY=
+STRIPE_WEBHOOK_KEY=
+NEXT_PUBLIC_SUPABASE_URL=

package/examples/demo-safe-saas/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: Safe demo CI
+
+on:
+  pull_request:
+    paths-ignore:
+      - "docs/**"
+      - "*.md"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    env:
+      STRIPE_SECRET_KEY: ${{ secrets.STRIPE_SECRET_KEY }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e
+        with:
+          node-version: 20
+      - run: test -n "${STRIPE_SECRET_KEY:-}"
+      - run: npm ci
+      - run: npx ai-saas-guard pr-risk --base origin/main
+      - run: npm test

package/examples/demo-safe-saas/README.md

@@ -0,0 +1,17 @@
+# Safe Demo SaaS
+
+This is a tiny public fixture with safer launch-readiness patterns for the same broad surfaces as the risky demo.
+
+Run from the repository root:
+
+```bash
+node dist/cli.js scan --root examples/demo-safe-saas
+```
+
+Expected result:
+
+```text
+No heuristic launch-readiness risks found by this command.
+```
+
+The fixture is intentionally small. It is not a complete SaaS template and does not prove a real app is secure.

package/examples/demo-safe-saas/app/api/stripe/webhook/route.ts

@@ -0,0 +1,89 @@
+import Stripe from "stripe";
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
+
+export async function POST(req: Request) {
+  const requestId = req.headers.get("x-request-id") ?? crypto.randomUUID();
+  await rateLimit(req);
+  const body = await req.text();
+  const signature = req.headers.get("stripe-signature");
+  const event = stripe.webhooks.constructEvent(
+    body,
+    signature!,
+    process.env.STRIPE_WEBHOOK_KEY!
+  );
+  const tenant_id = await resolveTenantForStripeCustomer(event.data.object.customer);
+
+  console.info("stripe webhook received", { requestId, eventId: event.id, tenant_id });
+
+  if (await hasProcessedEvent(event.id)) {
+    return new Response("ok");
+  }
+
+  switch (event.type) {
+    case "checkout.session.completed":
+      await syncEntitlement(event.data.object.customer);
+      break;
+    case "invoice.payment_failed":
+      await markPastDue(event.data.object.customer);
+      break;
+    case "invoice.payment_action_required":
+      await requestPaymentAction(event.data.object.customer);
+      break;
+    case "customer.subscription.updated":
+      await syncSubscription(event.data.object);
+      break;
+    case "customer.subscription.deleted":
+      await revokeEntitlement(event.data.object.customer);
+      break;
+    case "charge.refunded":
+      await reviewRefund(event.data.object.customer);
+      break;
+    default:
+      break;
+  }
+
+  await recordProcessedEvent(event.id);
+  return new Response("ok");
+}
+
+async function hasProcessedEvent(eventId: string) {
+  return eventId.length === 0;
+}
+
+async function rateLimit(req: Request) {
+  console.log(req.headers.get("x-forwarded-for") ?? "local");
+}
+
+async function resolveTenantForStripeCustomer(customerId: unknown) {
+  console.log(customerId);
+  return String(customerId);
+}
+
+async function recordProcessedEvent(eventId: string) {
+  console.log(eventId);
+}
+
+async function syncEntitlement(customerId: string) {
+  console.log(customerId);
+}
+
+async function markPastDue(customerId: string) {
+  console.log(customerId);
+}
+
+async function requestPaymentAction(customerId: string) {
+  console.log(customerId);
+}
+
+async function syncSubscription(subscription: unknown) {
+  console.log(subscription);
+}
+
+async function revokeEntitlement(customerId: string) {
+  console.log(customerId);
+}
+
+async function reviewRefund(customerId: string) {
+  console.log(customerId);
+}

package/examples/demo-safe-saas/app/api/tenant/[tenantId]/route.ts

@@ -0,0 +1,18 @@
+export async function POST(request: Request) {
+  const requestId = request.headers.get("x-request-id") ?? crypto.randomUUID();
+  await rateLimit(request);
+  const payload = await request.json();
+
+  console.info("tenant update", { requestId, tenantId: payload.tenantId });
+  await updateTenantBilling(payload.tenantId, process.env.STRIPE_SECRET_KEY);
+
+  return Response.json({ ok: true, requestId });
+}
+
+async function updateTenantBilling(tenantId: string, stripeKey?: string) {
+  console.log(tenantId, Boolean(stripeKey));
+}
+
+async function rateLimit(request: Request) {
+  console.log(request.headers.get("x-forwarded-for") ?? "local");
+}

package/examples/demo-safe-saas/app/dashboard/[tenantId]/page.tsx

@@ -0,0 +1,11 @@
+import Image from "next/image";
+import Link from "next/link";
+
+export default function TenantDashboard() {
+  return (
+    <>
+      <Image src="https://cdn.example.com/logo.png" width={240} height={120} alt="" />
+      <Link prefetch={false} href="/dashboard/settings">Open settings</Link>
+    </>
+  );
+}

package/examples/demo-safe-saas/next.config.js

@@ -0,0 +1,22 @@
+module.exports = {
+  async headers() {
+    return [
+      {
+        source: "/(.*)",
+        headers: [
+          { key: "X-Frame-Options", value: "DENY" },
+          { key: "X-Content-Type-Options", value: "nosniff" },
+          { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" }
+        ]
+      }
+    ];
+  },
+  images: {
+    remotePatterns: [
+      {
+        protocol: "https",
+        hostname: "cdn.example.com"
+      }
+    ]
+  }
+};

package/examples/demo-safe-saas/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "ai-saas-guard-demo-safe-saas",
+  "private": true,
+  "type": "module"
+}

package/examples/demo-safe-saas/supabase/migrations/001_projects.sql

@@ -0,0 +1,18 @@
+create table public.projects (
+  id uuid primary key,
+  user_id uuid not null,
+  name text
+);
+
+alter table public.projects enable row level security;
+
+create policy "users read own projects"
+on public.projects
+for select
+using (auth.uid() = user_id);
+
+create policy "users write own projects"
+on public.projects
+for all
+using (auth.uid() = user_id)
+with check (auth.uid() = user_id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-saas-guard",
-  "version": "0.29.1",
+  "version": "0.29.2",
   "description": "Local-first CLI that catches launch blockers in AI-built Next.js/Supabase/Stripe SaaS apps.",
   "readmeFilename": "README.md",
   "type": "module",