stripe-audit（Stripe 审核）

Stripe Audit

Deep analysis of an existing Stripe integration.

Objective

Find everything that's wrong, suboptimal, or drifted. Produce actionable findings.

Process

1. Spawn the Auditor

This is a deep analysis. Spawn the stripe-auditor subagent to do the heavy lifting in parallel. It has read-only access and preloaded Stripe knowledge.

1.5. Check Environment

Before any CLI operations, verify environment parity:

~/.claude/skills/stripe/scripts/detect-environment.sh

If mismatch detected, fix before proceeding. Resources created in wrong account won't be visible to app.

2. Run Automated Checks

Execute the audit script for quick wins:

~/.claude/skills/stripe/scripts/stripe_audit.sh

This catches:

• Hardcoded keys
• Missing env vars
• Webhook signature verification
• Mode-dependent parameter errors

3. Deep Analysis Areas

The auditor should examine:

Configuration

• Env vars set on all deployments?
• Cross-platform parity (Vercel ↔ Convex)?
• No trailing whitespace in secrets?
• Test keys in dev, live keys in prod?

Local Development

• Does pnpm dev auto-start stripe listen?
• If yes, is there a sync script that captures the ephemeral secret?
• Script uses --print-secret flag?
• Secret synced to correct target (Convex env or.env.local)?

Webhook Health

• Endpoints registered correctly?
• URL returns non-3xx on POST?
• Recent events delivered (pending_webhooks = 0)?
• Signature verification present and FIRST?

Subscription Logic

• Trial handling uses Stripe's trial_end?
• Access control checks subscription status correctly?
• Edge cases handled (cancel during trial, resubscribe, out-of-order webhooks)?
• Idempotency on webhook processing?

Security

• No hardcoded keys in source?
• Secrets not logged?
• Error responses don't leak internal details?

Business Model

• Single pricing tier?
• Trial completion honored on upgrade?
• No freemium/feature-gating logic?

Subscription Management UX (per stripe-subscription-ux)

• Settings page with subscription section?
• Current plan and status displayed?
• Next billing date shown?
• Payment method on file displayed?
• "Manage Subscription" button (Stripe Portal)?
• Billing history accessible?
• Appropriate messaging for all states?

4. Validate with Thinktank

For complex findings, run them through Thinktank for multi-expert validation. Billing bugs are expensive.

Output

Structured findings report:

STRIPE AUDIT REPORT
==================

CONFIGURATION
✓ Env vars set on dev
✗ STRIPE_WEBHOOK_SECRET missing on prod
⚠ Webhook URL returns 307 redirect

WEBHOOK HEALTH
✓ Endpoints registered
✗ 3 events with pending_webhooks > 0

SUBSCRIPTION LOGIC
✓ Uses trial_end
⚠ Missing idempotency check

SECURITY
✓ No hardcoded keys
✓ Signature verification present

LOCAL DEVELOPMENT
✓ Auto-starts stripe listen
✗ No webhook secret auto-sync

BUSINESS MODEL
✓ Single tier
✗ Trial not passed on mid-trial upgrade

SUBSCRIPTION MANAGEMENT UX
✓ Settings page exists
✓ Plan name displayed
✗ No payment method shown
✗ No billing history
⚠ Portal button exists but return_url missing

---
SUMMARY: 8 pass, 3 warn, 5 fail

CRITICAL:
- Set STRIPE_WEBHOOK_SECRET on prod
- Fix webhook URL redirect

HIGH:
- Implement trial_end pass-through

MEDIUM:
- Add webhook idempotency

Research First

Before auditing, check current Stripe best practices. What was correct last year might be deprecated now. Use Gemini to verify against current documentation.