cto-legends · module overview · infrastructure · MIT
legends-stripe: Stripe Payments, Fee Drag & Webhook Governance
Audit Stripe .env price IDs, sync Test and Live price ladders, reconcile fixed-fee drag and net retained cash to the cent, and verify raw-body HMAC webhooks with zero dependencies.
GitHub Repository (https://github.com/avalonreset/legends-stripe)
Developers and founders shipping on Astro, Next.js, or Python hit the same expensive Stripe bugs repeatedly: a live secret key gets paired with a test publishable key or an archived price_1... ID in production .env files; archiving a Product leaves its child Prices active as orphans; fixed $0.30 transaction fees and international card surcharges quietly eat 4% to 7.4% of small charges; or web middleware parses JSON before verifying Stripe-Signature HMAC headers.
legends-stripe gives your coding agent a zero-dependency Python 3.11+ standard-library CLI to govern your entire Stripe payment stack safely. Every catalog update or webhook change runs in read-only preview mode first and generates a SHA-256 plan_hash, ensuring no Live Mode product, price ladder, or webhook endpoint is created or archived without your explicit confirmation.
Alongside live audits for monthly recurring revenue (MRR), past-due dunning queues, double-billed customers, and zero-charge Checkout Session smoke tests, the module ships with ready-to-drop Astro v7 and Python server templates (Checkout Sessions, same-origin Customer Billing Portal, and raw-body HMAC webhook handlers) plus an attachable legends-empire runbook pack.
Deterministic Execution Boundary
Where Ad-Hoc Stripe Scripts Leak Revenue and Break Checkout
Unguided Stripe scripts and generic webhook templates routinely cause broken production checkouts, orphaned price records, and signature verification bugs when middleware re-serializes JSON bodies. Meanwhile, standard dashboard charts celebrate gross volume while hiding how $0.30 fixed transaction fees and uncaptured 3DS payment intents erode your net retained cash.
- Test vs. Live .env and Price-ID Verification: Cross-checks your project .env file against the live Stripe API to verify that sk_live_ and pk_live_ modes match, every referenced price_1... and prod_... exists and is active, and no archived Product is wired to your checkout buttons.
- Preview-First SHA-256 Catalog & Price Ladder Sync: Plans multi-tier and multi-interval price ladders offline, validates 500-character descriptions and 22-character bank statement descriptors before calling Stripe, and requires an exact SHA-256 plan_hash before changing anything in Live Mode.
- Stripe Fee Drag & Net Cash Telemetry: Reconciles /v1/balance, /v1/balance_transactions, /v1/charges, and /v1/payment_intents (filtering out uncaptured 3DS requires_action noise) to show Gross Revenue, fixed-fee drag (where $0.30 fees eat 4% to 7.4% of small charges), Refunds, Disputes, and Net Retained Cash to the exact cent.
- Raw-Body HMAC & 5-Event Subscription Webhook Audit: Verifies Stripe-Signature headers using constant-time hmac.compare_digest over raw UTF-8 request bytes with a 300-second replay window, and audits live webhook endpoints for the five core subscription events (checkout.session.completed, customer.subscription.updated, customer.subscription.deleted, invoice.paid, and invoice.payment_failed) so past-due dunning and cancellations never desync your app database.
CLI Subcommands & Capability Surface
- Environment & .env Price-ID Governance: Audits project .env files for missing or mismatched STRIPE_SECRET_KEY, STRIPE_PUBLISHABLE_KEY, and STRIPE_WEBHOOK_SECRET values, verifies every price_1... and prod_... ID against live Stripe, and exports active price maps as .env, JSON, or TypeScript const maps.
- Stripe Fee Drag & Net Cash Telemetry: Calculates available and pending balances, Gross Revenue, fixed-fee drag on small charges, Refunds, Disputes, Net Retained Cash, and 12-month projections to the exact cent, with optional customer PII redaction and Markdown receipt export.
- Catalog Lint & Price Ladder Sync: Detects product descriptions over 500 characters, invalid 22-character bank statement descriptors, and orphaned active Prices. Plans and syncs clean price ladders across Test and Live modes with preview-first SHA-256 plan locking and cascading price archive plans.
- Subscription Dunning, MRR & Double-Billing Audit: Scans active subscriptions to calculate MRR and ARR, surface past_due and unpaid dunning recovery queues, track cancel_at_period_end churn, catch customers accidentally billed across multiple active subscriptions, and run safe zero-charge Checkout Session smoke tests.
- 5-Event Subscription Webhook & Signature Audit: Runs offline constant-time HMAC-SHA256 Stripe-Signature checks over raw request bytes, probes live HTTPS webhook endpoints with SSRF protection, and audits or configures the five essential subscription webhook events (checkout.session.completed, customer.subscription.updated, customer.subscription.deleted, invoice.paid, and invoice.payment_failed).
- Drop-In Astro v7 & Python Server Blueprints: Exports production-ready Astro v7 TypeScript API endpoints (astro-webhook, astro-checkout, and astro-portal with same-origin return_url validation) and zero-dependency Python webhook handlers, plus DNS CNAME and TLS readiness checks for custom payment domains.
Raw Frontier LLM vs. legends-stripe Execution Matrix
- Checkout & .env Configuration Safety: Standard AI Chat (Copies test price_1... IDs into production .env files or mixes sk_live_ and pk_test_ keys, causing immediate 400 errors at checkout.) vs. With legends-stripe (Cross-checks every .env key and price_1... or prod_... variable against the live Stripe API and exports typed price lookup maps.) · Structured JSON report confirming zero mode mismatches, zero missing keys, and active status on all referenced Prices and Products.
- Catalog & Price Ladder Updates: Standard AI Chat (Creates duplicate products on retry, violates 22-character statement descriptor rules, or archives products while leaving child prices active.) vs. With legends-stripe (Validates field constraints offline, diffs against existing lookup_key and metadata, plans cascading price archives, and locks writes behind a SHA-256 plan_hash.) · Read-only preview diff with a SHA-256 plan_hash before execution, followed by live API readback of created or archived IDs.
- Fee Drag & Net Cash Visibility: Standard AI Chat (Reports gross charge totals while ignoring how $0.30 fixed fees eat 4% to 7.4% of small charges, dispute deductions, and uncaptured 3DS payment intents.) vs. With legends-stripe (Reconciles balance_transactions in exact cents, filters out uncaptured requires_action 3DS noise, and calculates exact fee drag percentages and Net Retained Cash.) · Cent-exact financial report breaking down Gross Revenue, Stripe Fees, Refunds, Disputes, Net Retained Cash, and small-charge fee drag alerts.
- Webhook & Secret Protection: Standard AI Chat (Verifies signatures against re-serialized JSON bodies, subscribes only to checkout.session.completed, or echoes secret keys into terminal logs.) vs. With legends-stripe (Verifies HMAC-SHA256 signatures over raw request bytes, audits all five subscription lifecycle webhook events, blocks SSRF redirects, and scrubs all sk_, rk_, and whsec_ tokens.) · Offline HMAC replay tests, SSRF-hardened HTTPS endpoint probes, and 100% secret-scrubbed CLI and Markdown outputs.
Explicit Safety Boundaries & Exclusions
- Never handles, processes, or stores raw credit card PAN numbers, CVVs, or PCI-DSS cardholder data.
- Never executes Live Mode catalog, price ladder, or webhook mutations without an explicit preview pass and matching SHA-256 --confirm-plan hash.
- Never echoes sk_live_, sk_test_, rk_, or whsec_ secret tokens into stdout, stderr, exception tracebacks, or generated Markdown reports.
- Never follows HTTP redirects with Authorization headers attached or probes loopback, private RFC1918, or cloud metadata IP addresses.
Operator FAQ
- Can legends-stripe accidentally modify or archive products in my Live Mode Stripe account?
- No. Every command that can create or update Stripe resources (catalog-sync, webhook-upsert, and product-upsert in Live Mode) defaults to a read-only preview mode and calculates a deterministic SHA-256 plan_hash. No Live Mode write request is sent unless you explicitly pass --apply together with the matching --confirm-plan hash and --live.
- How does legends-stripe differ from the official Stripe CLI?
- While the official Stripe CLI is designed for local webhook forwarding and generic resource requests, legends-stripe is an opinionated governance and financial audit tool built on the Python 3.11+ standard library with zero dependencies. It catches Test-vs-Live .env price-ID drift before deploy, calculates exact fixed-fee drag and net retained cash to the cent, detects double-billed subscribers, plans cascading price archives, and outputs ready-to-drop Astro v7 and Python server templates.
- How are API keys and customer personal data protected during audits?
- The CLI reads STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET from your environment or an explicit --env-file and automatically scrubs sk_live_, sk_test_, rk_, and whsec_ tokens from all JSON outputs, error messages, and Markdown reports. Adding --redact-pii masks customer emails and identifiers across all net cash and subscription dunning reports.
- Why does webhook signature verification fail in many Astro, Next.js, or Python apps?
- Stripe computes the v1 HMAC-SHA256 signature over the exact raw UTF-8 request body bytes combined with the timestamp header (t.raw_body). If web middleware parses the body into JSON and re-serializes it before verification, whitespace or key ordering changes break the digest. legends-stripe includes both an offline verify-webhook / sign-webhook test harness and drop-in Astro and Python templates that read the raw request buffer directly.
All 20 cto-legends Packages (1 Router + 19 Modules)
cto-legends · GitHub: The single local CLI router for Claude Code, Codex, and Cursor: reads one compact startup index and loads 19 isolated Python tools on demand with zero context bloat.legends-empire · GitHub: Govern your local Obsidian and Markdown vault with SHA-256 file integrity locks, crash-safe write transactions, immutable evidence staging, and read-only stewardship audits.legends-astro · GitHub: Migrate WordPress, Next.js, or legacy HTML sites to Astro v7 with a pre-build route and SEO parity contract, offline documentation, and post-build verification.legends-hetzner · GitHub: Scan live European and US Hetzner Cloud stock, compare cost-optimized x86 and ARM64 sizing, and enforce 10-check preflight plans before provisioning any server.legends-coolify · GitHub: Audit your self-hosted Coolify servers, Docker container states, deployment queues, environment variable keys, and database backup schedules over read-only HTTPS with zero secret exposure.legends-cloudflare · GitHub: Execute preview-first Cloudflare DNS updates and cutovers that preserve orange-cloud proxy states, guard multi-record hostnames, and verify every change via live API readback.legends-stripe · GitHub: Audit Stripe .env price IDs, sync Test and Live price ladders, reconcile fixed-fee drag and net retained cash to the cent, and verify raw-body HMAC webhooks with zero dependencies.legends-gohighlevel · GitHub: Operate GoHighLevel sub-accounts, batch-clone V2 snapshots with headless PIT minting, X-ray and rebrand internal workflow steps, and enforce 5-layer agency permissions and 4-store SaaS rebilling markups.legends-github · GitHub: Audit GitHub repository health, package verified releases, align your 20 repo topics with live search demand, and verify 1280x640 Open Graph social preview cards pixel for pixel.legends-jev · GitHub: Local Python OCR and visual verification for UI screenshots, exact original-image pixel coordinates, and Google Street View storefront signage audits.legends-geogrid · GitHub: Run circular-lattice Google Maps rank studies up to 30 positions deep at wholesale DataForSEO rates, complete with Street View signage dossiers and 18-page vector PDF briefings.legends-dataforseo · GitHub: Query Google organic SERPs, Google Maps, and keyword volume over the DataForSEO API with offline cost previews, zero-dependency Python execution, and SHA-256 local evidence banking.legends-firecrawl · GitHub: Convert JavaScript-heavy websites into clean Markdown and run preview-gated Firecrawl site maps, bounded crawls, and Alexandria catalog queries with SHA-256 local evidence banking.legends-grant · GitHub: Search federal, state, and foundation grants across 56 US jurisdictions, verify verbatim eligibility rules against your private company facts, and check proposal budgets to the cent.legends-obs · GitHub: Automate OBS Studio over its local WebSocket server with profile backups, window-aware scene switching, hardware encoder checks, and canary test-clip verification.legends-captions · GitHub: Repair misheard technical terms, lock letter-by-letter acronym timing, and render frame-accurate word-by-word subtitles for 4K60 vertical and widescreen video.legends-yt-dlp · GitHub: Paced yt-dlp video, audio, and YouTube transcript pipeline with resumable batch ledgers, local GPU word alignment, and frame-accurate FFmpeg clip cuts.legends-stable-audio-3 · GitHub: Generate custom instrumental tracks on your local GPU with Stable Audio 3 and crossfade multi-hour background mixes with automated silence trimming.legends-hyperyap · GitHub: Push-to-talk local GPU voice dictation for Windows, macOS, and Linux: transcribe speech offline with NVIDIA Parakeet and paste straight into your active editor or terminal.legends-ambient-intelligence · GitHub: Offline voice memo and meeting transcription pipeline: archive USB voice recorders with SHA-256 deduplication, run local Whisper or Parakeet, and distill Obsidian notes.