rootnode-academy/docs/PHASE9_1_STRIPE_TEST_VALIDATION.md

# Phase 9.1 — Real Stripe TEST-Mode Integration Validation

Status: **VALIDATED.** A real Stripe TEST Checkout Session, a real Stripe TEST payment ($399.00
— the founder-approved Winter Break Founding Cohort tuition), a genuine Stripe-signed webhook,
and the existing registration→enrollment conversion path were all proven end to end against
Stripe's real TEST-mode API — no live money, no live-mode credential, nothing simulated. This
document also records the first, credential-less attempt at this phase (which correctly stopped
rather than fake anything) and a real defect the live traffic exposed and fixed.

## 1. Baseline verification

- First attempt (credential-less): branch `main`, clean tree, HEAD = `origin/main` =
  `80a5f6e4576cb9b83a60c9e9b57e4ebc52b62f07` — the Phase 9 milestone.
- Resume attempt (this run): `git fetch origin` confirmed HEAD = `origin/main` =
  `77fd1869dbe694a7ff323a6fac07382e1f55b225` — the prior, credential-less Phase 9.1 commit.
- No `docs/ROOTNODE_PRICING_AND_OFFERS_V1.md` or any "Phase 9.5" commit exists anywhere in this
  repository's history, branches, or tags (verified via `git log --all`) — the pricing decision
  below came directly from Chase in this session, not from a document that turned out not to
  have reached this canonical repo yet (it was apparently done on a different machine and not
  yet pushed). Used directly; no invented business decision was needed to proceed.
- Phase 9 payment code and documentation re-inspected: `payment-provider.js`, `commerce.js`,
  `webhook-routes.js`, `offerings.js`'s 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`.

## 2. Stripe TEST credential status

**First attempt**: none found anywhere reachable (process env, every `.env` file, this repo's
Infisical wiring, session memory) — correctly stopped and documented rather than faked (see git
history for that version of this document).

**This run**: Chase provided a real `sk_test_...` secret key directly. Format-verified as TEST
mode (never printed in full anywhere in this document, any commit, or any persisted log — only
an 8-character prefix `sk_test_` ever appears). Stored in `platform/.env` (gitignored, never
committed — confirmed via `git status` throughout this phase). A push to Infisical for durable
storage was attempted (per Chase's request) but the existing machine identity credential at
`~/.config/infisical/identity.env` returned a consistent `401 Invalid credentials` from
`app.infisical.com` across three attempts — a pre-existing, unrelated credential-store problem,
not something fixable from this session. The Stripe key remains safely local in the meantime.

The webhook signing secret was obtained via `stripe listen --api-key ... --forward-to
http://localhost:4200/api/webhooks/payment --print-secret` (the Stripe CLI, installed to
`~/.local/bin/stripe` this session for exactly this purpose — no Dashboard endpoint needed for
local TEST-mode validation).

## 3. Stripe adapter architecture — confirmed, unchanged

`StripeProvider.createCheckoutSession()` uses **dynamic Checkout line-item `price_data`**, never
pre-created Stripe Price/Product IDs. RootNode's `offerings` table remains the sole source of
truth for identity, price, and currency. Confirmed still true after this phase's fix (below) —
the fix only changes how a LATER webhook event is correlated back to a transaction, not how the
Checkout Session itself is created.

## 4. Disposable TEST offering used

A clearly-labeled, disposable offering — `[TEST] Stripe Integration Check <run-id>` —
`delivery_mode: cohort`, price **39900 (cents) / usd = $399.00**, the founder-approved Winter
Break "Founding Cohort" launch tuition Chase gave directly in this session (standard/reference
retail $449, paid in full, no deposit, no payment plan — none of that billing structure was
built, only the flat price was used for this validation). **Not** the real Winter Break offering
— a separate, disposable fixture, transitioned to `cancelled` at the end of the run (confirmed).

## 5. Registration result

A real **guardian + minor** registration (the more complex path, preferred per the mission spec
since the Winter Break audience may include minors) via
`POST /api/integrations/registrations` — guardian `display_name`/email/phone real-shaped test
data, registrant `is_minor: true`, no real child PII. Registration created, seat reserved,
payment status tracked separately from registration status, no enrollment existed before payment
— all as designed.

## 6. Agreement gate result

Checkout attempted before agreement acceptance → `409 AGREEMENTS_INCOMPLETE`. Agreement then
accepted via `POST /api/integrations/registrations/:id/agreements` → `201`, `accepted_version:
1` persisted. Checkout attempted again → succeeded. The real, live enforcement path, not
bypassed.

## 7. Real Stripe TEST Checkout Session result

`POST /api/integrations/registrations/:id/checkout` returned a real
`https://checkout.stripe.com/...` URL. Independently retrieved via **Stripe's own**
`checkout.sessions.retrieve` API (never trusting RootNode's own echo):

```
Stripe session cs_test_a1VBoHHATcDr3DRTnZixQX8E0E5Ulk3H1UAKwTYVEOYVboOcaKCuZEMuff:
  amount_total = 39900, currency = usd, mode = payment, livemode = false
```

## 8. Server-authoritative amount verification

The checkout request was sent with a tampered body (`amount: 1, currency: "eur"` — neither field
exists on the real contract, sent anyway to prove they're inert). Stripe's own recorded session
still shows `amount_total: 39900, currency: usd` — the real, configured offering price, not the
caller-supplied value. **The caller cannot choose the price or currency.**

## 9. Real TEST payment result

Chase completed the real Stripe-hosted TEST Checkout in a browser with Stripe's official test
card (4242 4242 4242 4242). Independently confirmed via Stripe's own API (not just the
redirect):

```
GET /v1/checkout/sessions/cs_test_a1VB... → status: complete, payment_status: paid,
  payment_intent: pi_3U9QuqPl0OwZKsjY0lprOPWi
```

## 10. Real signed webhook result

`stripe listen` relayed a genuine Stripe-signed `checkout.session.completed` event
(`evt_1U9QutPl0OwZKsjYSkW8Le84`) to `POST /api/webhooks/payment`, which accepted it (`200`,
`{"received":true,"result":"processed"}`). This is Stripe's own real signature over Stripe's own
real event body — not a locally-fabricated one.

## 11. Invalid-signature result

A garbage `Stripe-Signature` header against a fabricated body → `400 invalid_signature`. The
registration's status was re-read before and after and confirmed unchanged — zero domain side
effect from a rejected signature.

## 12. Payment transaction result

Exactly one `payment_transactions` row for this registration, `status: paid`,
`provider_reference` matching the real Checkout Session id. No `card_number`/`cvv`/`card_last4`/
`payment_method_details` field exists anywhere on the record (none is ever stored, by design).

## 13. Registration confirmation result

`offering_registrations.status = enrollment_activated`, server-derived entirely from the real
payment webhook — never a client action.

## 14. Enrollment conversion result

The **existing, unmodified** `convertRegistrationToEnrollment()` path ran — no second
implementation was created. Verified directly against the database: exactly one row in
`enrollments` for this student/program.

## 15. Cohort/capacity result

Exactly one row in `cohort_enrollments` for this student/cohort — the offering's `cohort_id`
correctly produced real classroom membership on conversion, unchanged from Phase 8/9's design.

## 16. Guardian preservation result

Exactly one row in `student_guardians` for this student (the Phase 9 guardian-linking fix from
the original Phase 9 phase held under real Stripe traffic too). `students.email` for the minor
remains the empty string — the guardian's email was never written into the student's own
identity record.

## 17. Activation/notification result

The real activation notification was queued and delivered through the existing dev-preview
mechanism (the same one every prior phase's testing has used — `EMAIL_PROVIDER` was left at its
dev default this run; Google Workspace live delivery was not exercised, since nothing about
Stripe validation requires it and the mission explicitly said not to make GWS delivery a Stripe
blocker). No second, Stripe-specific notification path exists — this reuses the exact
`notifyForEnrollment` flow every other enrollment trigger already uses.

## 18. Student access result

The real one-time activation token worked: `POST /api/student/activate` → `200`, and the newly
activated student's `GET /api/student/programs` includes the enrolled program. One access proof,
as instructed — no full curriculum rehearsal was repeated (Phase 8/9's own rehearsals already
cover that in depth).

## 19. Duplicate-event/idempotency result

The **real** Stripe event was fetched fresh via `stripe.events.retrieve(eventId)` and re-signed
locally with the real webhook secret (`stripe.webhooks.generateTestHeaderString`) — never a
fabricated "payment succeeded" event for an unpaid session, but a genuine replay of the exact
event Stripe itself recorded, mirroring what `stripe events resend` does server-side (not usable
here directly — an ephemeral `stripe listen` session has no persistent dashboard endpoint id to
target). Result: `200`, `{"result":"duplicate"}`. Confirmed via direct query: still exactly one
enrollment, still exactly one activation/confirmation notification — no double conversion, no
double seat consumption, no double email.

## 20. Declined-payment result

**Not exercised via an actual real declined Stripe TEST payment this session** — doing so would
require a second full browser-driven Checkout completion (Stripe Checkout Sessions have no
supported pure-API "decline" trigger; PaymentIntents-direct-confirm would mean not using
Checkout Sessions at all, which this phase was told not to redesign toward). Phase 9's
deterministic suite already proves "failed payment retains the seat" directly, and this phase's
own new regression test (§28) proves the exact real-Stripe reference-correlation shape a genuine
`payment_intent.payment_failed` event would use. Available on request if Chase wants one more
manual decline-card checkout to close this specific gap with fully real traffic.

## 21. Abandoned-checkout result

Fully automated, no browser needed: a second, separate registration's Checkout Session was
created normally, then expired via Stripe's own `sessions.expire()` API (a real, supported,
pure-API operation — no fabricated event). Stripe itself then fired a genuine
`checkout.session.expired` webhook, relayed by `stripe listen` and accepted (`200`). Confirmed:
the registration's status became `cancelled` and its seat was released exactly once, within the
polling window.

## 22. Refund result

`stripe.refunds.create({ payment_intent })` against the real PaymentIntent → `succeeded`
(`re_3U9QuqPl0OwZKsjY0IYvfOsM`, `39900 usd`). RootNode's own refund state was confirmed
(`status: refunded`). The non-cascade rule was reconfirmed directly against the database: the
registration stayed `enrollment_activated` and the enrollment stayed `active` — a refund does
**not** automatically revoke registration or academic access. Whether it *should*, for this
specific offering/policy, remains an explicit business-policy question this phase does not
decide in code (per Phase 9's own design and this phase's own instruction).

## 23. Stripe ↔ RootNode reconciliation

| | |
|---|---|
| RootNode registration | `04772e72-4a09-4afd-8032-d6ef4d132375` |
| RootNode enrollment | `10e2724a-43bb-4d35-8bea-98f600cbd8e9` |
| RootNode student | `student-001` |
| Stripe Checkout Session | `cs_test_a1VBoHHATcDr3DRTnZixQX8E0E5Ulk3H1UAKwTYVEOYVboOcaKCuZEMuff` |
| Stripe PaymentIntent | `pi_3U9QuqPl0OwZKsjY0lprOPWi` |
| Stripe webhook event | `evt_1U9QutPl0OwZKsjYSkW8Le84` |
| Stripe refund | `re_3U9QuqPl0OwZKsjY0IYvfOsM` |
| Amount / currency | `39900` / `usd` ($399.00) |

No secret key, webhook secret, card number, or CVV appears above or anywhere in this document.

## 24. Stripe Dashboard reconciliation

For a real transaction, Chase can locate it in the Stripe Dashboard under **Test mode →
Payments** (search by the PaymentIntent id `pi_...` or the Checkout Session id `cs_test_...`
above) or **Developers → Events** (search by the event id `evt_...`). The RootNode admin UI's
own Payments card (on the registration detail view) shows the matching `provider_reference`
side by side with RootNode's own status/timestamps — reconciliation is possible without either
system exposing credentials or card data to the other.

## 25. Security revalidation (with real Stripe enabled)

| Check | Result |
|---|---|
| Stripe secret key never reaches browser | Server-only env var; not referenced anywhere in `frontend/`. |
| Webhook signing secret never reaches browser | Same. |
| Caller cannot choose price | Proven directly (§8) against Stripe's own recorded amount. |
| Caller cannot choose currency | Proven directly (§8), same test. |
| Caller cannot bypass required agreements | Proven directly (§6). |
| Caller cannot bypass capacity | Unchanged architecture; existing `e2e-phase9.js` last-seat race regression rerun clean (§27). |
| Success redirect cannot forge payment | The script never trusted the redirect — every "paid" claim in this document is independently verified via Stripe's own API or the real webhook, not the URL. |
| Invalid webhook signature rejected | Proven directly (§11). |
| Duplicate webhook safe | Proven directly with a REAL re-signed event (§19). |
| No card number enters RootNode DB | Proven directly (§12) — no such field exists. |
| No card number enters RootNode logs | Confirmed — grepped this session's own logs/scratch files for the real secret values and any card-shaped pattern; none found. |
| No Stripe secret enters audit log | Existing `e2e-phase9.js` hygiene test rerun clean (§27). |
| No Stripe secret enters metrics | Same. |
| Stripe provider IDs not high-cardinality metric labels | Unchanged architecture — metrics still use only fixed-enum labels. |
| One student cannot inspect another's payment | Structural — payment routes are admin/owner-only; students have no route to any payment data at all. |
| Integration shared secret remains server-to-server only | Unchanged — never read from any browser-facing code. |

## 26. Bugs found

**One real defect**, found only because real Stripe traffic was exercised: `payment_intent.
payment_failed` and `charge.refunded` webhook events reference Stripe's PaymentIntent/Charge
object, never the Checkout Session — but `payment_transactions.provider_reference` only ever
stored the Session id. A real Stripe-issued failure or refund event would have silently failed
to match any transaction (`result: 'error', reason: 'UNKNOWN_TRANSACTION'`). Phase 9's
deterministic TestProvider never exposed this because its fabricated events always reuse
whatever reference the calling test explicitly supplies, never distinguishing real Stripe object
id shapes.

## 27. Bugs fixed

Smallest correct fix, matching Stripe's own documented pattern for this exact problem:

- `payment-provider.js`: `StripeProvider.createCheckoutSession()` now also sets
  `payment_intent_data: { metadata }` at session creation, so the SAME metadata (which already
  carries our own `transaction_id`) propagates onto the PaymentIntent Stripe creates — not just
  the Session.
- `normalizeEvent()` (now `async`, one extra API call only on the rare refund path): for
  `payment_intent.payment_failed`, reads `obj.metadata.transaction_id` directly (the event
  object IS the PaymentIntent). For `charge.refunded`, retrieves the PaymentIntent
  (`stripe.paymentIntents.retrieve`) since Charges do not inherit PaymentIntent metadata
  automatically, and reads `transaction_id` from there.
- `commerce.js`: the transaction lookup now matches `provider_reference = $1 OR
  transaction_id::text = $1` — a single additional `OR` clause, no schema/migration change.
- `webhook-routes.js`: added the now-required `await` on `verifyAndParseWebhook` (the
  deterministic `TestProvider`'s synchronous return is unaffected — `await` on a non-promise
  value resolves immediately).

Verified fixed: the real Stripe refund in this session (§22) correctly resolved via this new
path (the refund's `charge.refunded` webhook references the PaymentIntent, exactly the
previously-broken case), and a new permanent deterministic regression test (§28) proves the
mechanism directly.

## 28. Permanent regression coverage added

`platform/test/e2e-phase9.js` gained one new test: *"a webhook event referencing OUR OWN
transaction_id (not provider_reference) — the real Stripe payment_intent/charge shape — is
still matched"* — builds a test event whose `providerReference` is the transaction's own UUID
(exactly what the fixed `normalizeEvent()` now produces for real Stripe failure/refund events)
and confirms it's found and processed. This runs on every future deterministic `e2e-phase9.js`
pass, with no Stripe credentials required.

`platform/test/stripe-integration-test.js` (the opt-in real-Stripe check from the first Phase
9.1 attempt) was substantially extended: configurable price/currency
(`STRIPE_TEST_PRICE_CENTS`/`STRIPE_TEST_CURRENCY`, defaults stay cheap/generic), a
`STRIPE_TEST_MINOR=true` guardian+minor path, and — once a real payment lands — fully automated
deep verification (payment record, enrollment/cohort/guardian reconciliation, the real
re-signed-event duplicate proof, student access, a real refund) plus a fully automated,
browser-free abandoned/expired-checkout proof via `sessions.expire()`. Still opt-in, still a
guaranteed no-op by default, still refuses live-mode keys.

## 29. Regression results

- `platform/test/e2e-phase9.js`: **20/20** (fresh stack, `PAYMENT_PROVIDER=test`) — includes the
  one new regression test from §28.
- `infra/scripts/drills/test-phase9-winter-camp-commerce.js`: **13/13** (fresh stack) — unaffected
  by the fix, rerun to confirm.
- No registration/agreement/enrollment/notification-template code changed beyond the webhook
  correlation fix itself, so Phase 8/5B/5C were not rerun (per the mission's own conditional
  rule) — the fix is entirely inside `commerce.js`/`payment-provider.js`/`webhook-routes.js`,
  already covered by the Phase 9 suite.
- No frontend code changed — no frontend build was required.

## 30. Documentation

Rewrote `PHASE9_1_STRIPE_TEST_VALIDATION.md` (this document) from BLOCKED to the real, proven
results. Updated `docs/STRIPE_INTEGRATION_RUNBOOK.md` (real-Stripe local testing is no longer
"not yet exercised") and `docs/WINTER_BREAK_LAUNCH_CHECKLIST.md` (the Stripe TEST technical
validation item is now checked; live-mode items remain unchecked, correctly — this phase never
touched live mode). `docs/WEBSITE_REGISTRATION_AND_CHECKOUT.md` needed no change — nothing about
the website-facing contract itself changed this phase, only the server-side webhook correlation
internals.

## 31. Remaining Stripe TEST gaps

An actual real declined-payment checkout was not exercised (§20) — available on request, needs
one more manual browser step. Everything else the mission asked for was proven with real Stripe
traffic.

## 32. Remaining LIVE Stripe gaps

Unchanged from Phase 9 — see `docs/STRIPE_INTEGRATION_RUNBOOK.md`'s "Going live" section and
`docs/WINTER_BREAK_LAUNCH_CHECKLIST.md`: business/account verification, a live secret key, a
permanent live webhook endpoint, payout/bank configuration, a real HTTPS production URL, and
production deployment itself. None of this phase's work performed or authorized any live-mode
action.

## 33. Remaining Winter Break business decisions

Real dates, venue, and final capacity remain undecided (price is now decided — $399 launch /
$449 standard retail, per Chase directly this session; not yet reflected in a committed
`ROOTNODE_PRICING_AND_OFFERS_V1.md` in this canonical repo — see §1). Refund/cancellation
*policy* (as opposed to the mechanical non-cascade behavior proven in §22) remains an open
business decision.

## 34. Remaining legal requirements

Unchanged from every prior phase: the actual agreement/waiver legal text, jurisdiction-specific
minor-consent review, data-retention/deletion policy — see `docs/STUDENT_GUARDIAN_DATA_MODEL.md`.

## Final status

**PHASE 9.1 COMPLETE / STRIPE TEST-MODE VALIDATED**

A real Stripe TEST Checkout Session, a real Stripe TEST payment, a genuine Stripe-signed
webhook, and the existing registration→enrollment conversion were all proven end to end, plus a
real duplicate-delivery proof, a real automated abandoned-checkout proof, and a real refund with
the non-cascade rule reconfirmed. One genuine defect (webhook-event correlation for
PaymentIntent/Charge-referencing events) was found only by this real traffic, fixed with the
smallest correct change, and covered by a new permanent deterministic regression test.