Stripe Key Mode Guard

The four mixes

1. Live secret, test publishable. Checkout renders. The card form is a test form. Real customers get "your card was declined" — or a test card succeeds and you ship a product for a payment that never existed.

2. Test secret in production. Every charge succeeds and none of them is money. Orders look perfect. You find out when the balance is zero at the end of the month.

3. Webhook secret from the wrong mode. Every signature check fails, so no event is processed. The charges are real; nothing is fulfilled. This one is invisible from both ends — Stripe logs delivery failures nobody reads, and your app simply never hears.

4. Price id from the other mode. No such price, in production only, for a price that plainly exists in the dashboard you are looking at — because you are looking at the other mode.

None of these is a code bug. Every one is an environment assembled by hand, and the only defence is checking before the first request rather than learning from a customer.

What it will not pretend to know

A webhook secret does not encode its mode. whsec_ is whsec_ in both. So this warns rather than passing it silently — saying nothing would imply the check had covered it, and this is precisely the failure that shows up nowhere.

An object id does not encode its mode either. A price_… is structurally valid in both, so modeOf returns unknown rather than guessing. A guess here is wrong half the time.

An empty string is unset, not a key. Tooling that materialises environments writes absent secrets back as KEY="", so a plain undefined check passes on a variable carrying nothing.

It reports every problem, not the first

Returning early means someone fixes the publishable key, redeploys, and discovers the webhook secret was wrong too — a second deployment, and a second window in which money moves incorrectly.

It never prints a key

describeStripeConfig prints modes: stripe: secret=live publishable=test webhook=set errors=2.

A key in a log is a key in a log aggregator, a screenshot and a support ticket. There is a test asserting no key value appears in the output, because the safe-looking print is exactly how these escape.

What this does NOT do

No Stripe calls — it reads strings you already have, so it costs nothing and works offline at boot. It cannot verify a key is valid, only that the modes agree; a revoked live key looks identical to a working one.

No idempotency, retry or webhook handling. See stripe-retry-safety-verdict and idempotency-key-manager in this catalogue for those.

Verified

12 tests: mode extraction for secret, publishable and restricted keys, object ids reported as unknown, empty strings treated as unset, the live/test mix, the expected-mode mismatch, missing and malformed webhook secrets, the unverifiable-mode warning, missing object ids, all problems returned rather than the first, and no key value appearing in the summary line.

Not covered: no test hits Stripe, so nothing here confirms a key actually works.