rootnode-academy/docs/PHASE9_1_STRIPE_TEST_VALIDATION.md

Phase 9.1 — Real Stripe TEST-Mode Integration Validation

Status: BLOCKED — no Stripe TEST credentials are available to this session. This document records exactly what was verified without them, exactly what Chase needs to provide, and the permanent, opt-in validation script that will run the real proof the moment those credentials exist. No live money was risked; no Stripe network call of any kind was made during this phase.

1. Baseline verification

• Branch: main. Working tree: clean at start.
• git fetch origin — HEAD and origin/main both 80a5f6e4576cb9b83a60c9e9b57e4ebc52b62f07, exactly the Phase 9 milestone commit.
• Phase 9 payment code and documentation inspected in full: payment-provider.js, commerce.js, webhook-routes.js, offerings.js's registration/conversion path, admin-offerings-routes.js's payment routes, integration-routes.js's checkout/agreement/ status routes, platform/test/e2e-phase9.js, infra/scripts/drills/ test-phase9-winter-camp-commerce.js, docs/STRIPE_INTEGRATION_RUNBOOK.md, docs/ WINTER_BREAK_LAUNCH_CHECKLIST.md. Nothing was changed as a result of this review — no defect was found, and none was invented to justify a change (§1/§22's own instruction).

2. Stripe TEST credential search — none found

Searched, in order: process environment (env | grep -i stripe), every .env/.env.example file reachable from this repository and the operator's home directory, this repository's own Infisical project wiring (none exists — no .infisical.json in this repo), and this session's own memory of prior credential-provisioning work (none references Stripe or this project). No STRIPE_SECRET_KEY, no STRIPE_WEBHOOK_SECRET, in any test or live form, exists anywhere this session can reach.

This is exactly STOP condition 1/2 from this phase's own authorization. Per §2/§27: do not fake validation, stop after documenting exactly what's needed.

What Chase needs to provide or configure

1. A Stripe account (test mode is available on any account, including one with no live business verification completed yet).
2. From the Stripe Dashboard, in Test mode: the test Secret key (sk_test_...) → STRIPE_SECRET_KEY.
3. A webhook signing secret for a test endpoint — either a permanent test-mode webhook endpoint configured in the dashboard, or the ephemeral one the Stripe CLI prints when running stripe listen --forward-to <gateway>/api/webhooks/payment → STRIPE_WEBHOOK_SECRET. Full setup steps already documented in docs/STRIPE_INTEGRATION_RUNBOOK.md's "Local testing against real Stripe TEST mode" section (written during Phase 9, unchanged and still accurate).
4. Both values set as environment configuration on the running Platform API process (PAYMENT_PROVIDER=stripe alongside them) — never committed to git, never placed in any browser-reachable configuration. No credential value appears anywhere in this document, any commit, or any log produced during this phase.

Once those exist, run the permanent validation script this phase adds (§4 below) to produce the actual proof this phase was asked to deliver.

3. Stripe adapter architecture — confirmed, unchanged

Inspected payment-provider.js's StripeProvider.createCheckoutSession(): it uses dynamic Checkout line-item price_data (unit_amount/currency/product_data.name supplied inline per session), not pre-created Stripe Price/Product IDs. RootNode's offerings table remains the sole source of truth for identity, price, and currency; Stripe never becomes a second business-domain model — no Stripe object id is ever treated as anything other than an opaque provider_reference. This matches §3's explicit constraint and required no change.

4. Permanent opt-in Stripe integration test — added

platform/test/stripe-integration-test.js (new). Default behavior (no environment variable set): prints a skip message and exits 0 with zero Stripe network traffic — confirmed by running it with no configuration at all. Verified this run:

$ node test/stripe-integration-test.js
Stripe integration test skipped (RUN_STRIPE_INTEGRATION_TEST is not "true") — no Stripe network traffic, no credentials required.

Enabled via RUN_STRIPE_INTEGRATION_TEST=true, reusing the exact STRIPE_SECRET_KEY/ STRIPE_WEBHOOK_SECRET-adjacent naming Phase 9 already established (only STRIPE_SECRET_KEY is actually needed by the script itself, to independently query Stripe's own API — the webhook secret only needs to be configured on the server process, not read by this script). Guard clauses verified directly, without needing real credentials:

Condition	Verified behavior
OWNER_EMAIL/OWNER_PASSWORD unset	Exits 1 with a clear message.
STRIPE_SECRET_KEY unset	Exits 1, names the exact variable needed.
STRIPE_SECRET_KEY starts with sk_live_	Refuses to run — "TEST MODE ONLY" — exits 1.
STRIPE_SECRET_KEY any other non-test shape	Refuses to run out of caution — exits 1.
A syntactically valid sk_test_... value, no real stack running	Reaches main() cleanly, fails only on the expected connection error — confirms no syntax defect in the enabled code path.

When real test credentials exist and the dev stack is running with PAYMENT_PROVIDER=stripe, this script will automatically and honestly prove, via pure API calls (no browser needed):

• RootNode creates a real Stripe TEST Checkout Session (not RootNode's own claim — verified by retrieving the session directly from Stripe's own checkout.sessions.retrieve API).
• The amount/currency Stripe actually recorded matches the offering's server-side price exactly, even when the request is sent with a tampered amount/currency in the body — proving server-authoritative pricing against Stripe's own object, the strongest form of that proof.
• session.livemode === false is asserted directly — the script itself refuses to consider its own run valid against anything but a real TEST-mode session.
• RootNode's webhook route rejects an invalid/garbage signature cleanly, with zero domain side effect (the registration's status is re-read and asserted unchanged).

What it deliberately does not automate: actually completing Stripe's hosted Checkout page. There is no supported pure-API way to "pay" a Checkout Session, and fabricating a signed "payment succeeded" webhook for a session nobody actually paid would itself be exactly the kind of faked validation this phase was told never to produce. Instead, the script prints the real checkout URL and polls RootNode's own status endpoint for a bounded window (default 90s, STRIPE_INTEGRATION_TEST_WAIT_SECONDS) while a human completes payment in a browser (Stripe's test card 4242 4242 4242 4242) or a parallel stripe listen --forward-to relays Stripe's real event — see docs/STRIPE_INTEGRATION_RUNBOOK.md. If nothing arrives in that window (expected in an unattended run), it says so plainly rather than reporting a false pass.

Never runs as part of normal regression suites or CI — no other test file requires or imports it, and its own default is a guaranteed no-op.

5. What was actually proven this phase

Step from the mission spec	Result
1. Baseline verification	Done — see §1.
2. Stripe TEST-mode safety	No live-mode action was possible or attempted; no credentials of any kind exist.
3. Stripe architecture review	Done — dynamic price_data, confirmed, unchanged (§3).
4-20 (disposable offering through security revalidation, all requiring a real Stripe TEST payment/webhook round trip)	Not performed — blocked on missing credentials. Faking any of these was explicitly disallowed.
21. Permanent opt-in integration test	Built (§4) — the automatable portion is real and will run the moment credentials exist; the human/CLI-dependent portion is honestly deferred, not faked.
22. Application changes	None made — no genuine defect was exposed (none could be, without real Stripe traffic), so §22's "smallest correct fix" rule had nothing to apply to.
23. Regression	No registration/agreement/enrollment/notification/frontend code changed this phase, so per §23's own conditional rule, no regression rerun was required. The new test file's default no-op path was verified directly (§4) instead.
24. Documentation	This document, plus the update noted below.
25. Live-mode readiness checklist	See §6.

6. Live-mode readiness checklist

Everything Stripe-side is still pending exactly as docs/STRIPE_INTEGRATION_RUNBOOK.md's "Going live" section already lays out, restated here as a checklist per §25:

Stripe:

• Business/account verification completed in the Stripe dashboard.
• Live API secret key (sk_live_...) generated.
• A permanent live-mode webhook endpoint created, pointed at the production API's /api/webhooks/payment URL, and its signing secret (whsec_...) captured.
• Payout/bank details configured in Stripe.
• Business/support information (statement descriptor, support contact) configured in Stripe.

RootNode:

• A real, HTTPS production URL for the Platform API (Stripe requires HTTPS for live webhooks).
• STRIPE_SECRET_KEY/STRIPE_WEBHOOK_SECRET (live values) provisioned into production secret configuration only.
• Production deployment itself (explicitly out of scope for this phase and Phase 9 — unchanged status).
• Backup/monitoring in place for the production database holding payment_transactions.
• The real Winter Break offering configured with its real price, once decided.

Business (Chase's decisions, not invented here): final price, refund/cancellation policy, camp dates, venue, capacity — all still open, tracked in docs/ WINTER_BREAK_LAUNCH_CHECKLIST.md.

Legal (unchanged from every prior phase's own list): the actual agreement/waiver text, guardian/minor consent review, privacy/retention requirements — see docs/ STUDENT_GUARDIAN_DATA_MODEL.md.

Nothing above is marked complete — none of it has been verified, and this phase did not attempt to invent or shortcut any of it.

7. Bugs found

None. No genuine defect was exposed because no real Stripe traffic was possible this phase.

8. Security posture — reasoned about, not re-verified against real Stripe

Every item in the mission's §20 checklist was already true and tested against the deterministic provider in Phase 9 (e2e-phase9.js), and nothing about switching providers changes the code path that enforces them (the same commerce.js/webhook-routes.js code runs regardless of which provider is active — see §3). This phase did not and could not re-verify them against REAL Stripe traffic specifically; that re-verification is exactly what stripe-integration-test.js (§4) will perform automatically the moment credentials exist.

Final status

PHASE 9.1 BLOCKED — NO STRIPE TEST CREDENTIALS AVAILABLE.

No real Stripe TEST Checkout, real TEST payment, or real signed Stripe webhook was created or observed this phase — none of the actions requiring them were attempted, per this phase's own explicit instruction never to fake validation. The permanent, opt-in stripe-integration-test.js is ready and waiting; provide STRIPE_SECRET_KEY/STRIPE_WEBHOOK_SECRET (test mode) and set RUN_STRIPE_INTEGRATION_TEST=true to run the real proof.