@tellescope/sdk 1.255.18 → 1.255.19

package/src/tests/api_tests/security/formsort_webhook_auth_field_lock.test.ts

@@ -0,0 +1,753 @@
+require('source-map-support').install();
+
+import axios from "axios"
+import { Session } from "../../../sdk"
+import {
+  assert,
+  log_header,
+} from "@tellescope/testing"
+import { setup_tests } from "../../setup"
+import { Enduser } from "@tellescope/types-client"
+import { FORM_INGESTION_API_KEY_SCOPE } from "@tellescope/types-models"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+
+/**
+ * Regression test for: email / phone are locked against writes from the Formsort webhook when it
+ * IMPLICITLY matched a patient that already existed before the submission started.
+ *
+ *   POST /v1/webhooks/formsort/*  (alias: /v1/webhooks/form-ingestion/*)
+ *
+ * The handler resolves an enduser four ways, in precedence order:
+ *   1. ?enduserId=            — an explicit assertion by the API-key-authenticated caller
+ *   2. existingResponse.enduserId — the patient attached to this responder_uuid's draft
+ *   3. findOne({ $or: [{ phone }, { email }] })  — a GUESS, optionally AND'ed with fname + lname
+ *   4. insert                 — brand-new patient
+ *
+ * On a finalized submission it then wrote a blanket `$set: enduserFields` onto whatever it landed
+ * on, and that object carries `email` and `phone`. Those are authentication channels:
+ * request-enduser-password-reset resolves purely by findOne({ email }), begin_login_flow accepts
+ * email OR phone, and send_otp delivers login codes to enduser.phone. So a submission that matched
+ * a patient on PHONE ALONE could repoint that patient's email (and vice versa), which chains to
+ * account takeover exactly as described in public_endpoint_auth_field_lock.test.ts.
+ *
+ * The rule under test: on path 3 — the guess — email and phone are dropped from the update. They
+ * remain writable on paths 1, 2 and 4.
+ *
+ *   - Path 1 stays open deliberately. This endpoint is API-key authenticated, so a caller that
+ *     names an enduserId knows which patient it means; keeping it writable preserves backwards
+ *     compatibility and lets a sophisticated consumer update these fields when it is safe.
+ *   - Path 2 stays open because Formsort fires a webhook per page: the patient who started the form
+ *     must still be able to fix a typo'd email on page 3. It is gated on the STICKY
+ *     FormResponse.authFieldIntakeDisabled flag, computed once when the response is first written,
+ *     so a response first formed by a guess can never be re-opened by a later webhook.
+ *
+ * A "fill only if blank" fix would NOT close this. Phone-only patients are the common case
+ * (sms_messages.leave_message creates them), and filling their blank email is the primary attack —
+ * hence the UNSET victim shapes in R5.
+ *
+ * Scenario groups (pre-fix expectation in parens):
+ *   R1  (RED)   matched on phone — submitted email must not land
+ *   R2  (RED)   matched on email — submitted phone must not land
+ *   R3  (RED)   stickiness: draft matched a pre-existing patient, finalize must not repoint them
+ *   R4  (RED)   unresolvable ?enduserId= falls through to the guess — must stay blocked
+ *   R5  (RED)   victim shapes: blank email / blank phone are filled by the guess (the takeover case)
+ *   G6  (GREEN) patient created by this responder's own draft may still correct their email
+ *   G7  (GREEN) explicit ?enduserId= still writes email + phone (backwards-compat escape hatch)
+ *   G8  (GREEN) ?createNewEnduser=true still writes email + phone
+ *   G9  (GREEN) brand-new patient still inserted WITH submitted email + phone
+ *   G10 (GREEN) fname/lname/dateOfBirth/gender/custom fields still update on a guessed match
+ *   G11 (GREEN) explicit ?enduserId= overrides for that request only — the stored flag stays set
+ *   G12 (GREEN) the Stripe grace: a BLANK phone on a contact the Stripe integration created within
+ *               the last hour is filled from intake (see stripe_provisional_enduser.ts)
+ *   R12         ...but a phone already stored on that contact is never overwritten
+ *   R13         ...and its email is never repointed
+ *   R14         both grace markers are load-bearing: neither source nor stripeCustomerId alone opens it
+ *   R15         the grace is per-request — it does not clear the stored flag
+ *
+ * The Stripe grace is deliberately confined to THIS endpoint, which is API-key authenticated. The
+ * anonymous public-form path gets no exemption; that boundary is pinned by G28 in
+ * public_endpoint_auth_field_lock.test.ts.
+ *
+ * STRUCTURE: record -> report -> cleanup -> assert.
+ * EXIT_ON_FIRST_ERROR is true in testing.ts, so assert() calls process.exit(1) synchronously on the
+ * first failure. Two consequences shape this file:
+ *   1. No async_test here. Every scenario records into `results`, a summary table prints, and a
+ *      single assert() loop runs LAST — so a pre-fix run prints the complete failure picture
+ *      instead of dying on the first probe.
+ *   2. process.exit() does not unwind pending finally blocks, so cleanup runs BEFORE the assert
+ *      loop; otherwise a by-design-failing run would leak every fixture into the next run.
+ */
+
+// The enduser update in this handler is fire-and-forget (.catch(console.error), not awaited).
+// Reading the victim immediately would frequently show the un-overwritten value on a VULNERABLE
+// server -> false pass. So poll for the attack LANDING: fails fast against vulnerable code, burns
+// the full window against fixed code.
+const OVERWRITE_WINDOW_MS = 3000
+const POLL_INTERVAL_MS = 150
+
+const sleep = (ms: number) => new Promise<void>(resolve => setTimeout(resolve, ms))
+
+type ScenarioResult = { group: string, name: string, ok: boolean, skipped?: boolean, detail: string }
+
+export const formsort_webhook_auth_field_lock_tests = async (
+  { sdk, sdkNonAdmin }: { sdk: Session, sdkNonAdmin: Session }
+) => {
+  log_header("Formsort Webhook Auth Field Lock (email / phone)")
+
+  // Every identity carries a per-run token so the handler's $or can only match our own records,
+  // and re-runs never collide.
+  const RUN = Date.now().toString(36)
+
+  const results: ScenarioResult[] = []
+  const record = (group: string, name: string, ok: boolean, detail = '') => {
+    results.push({ group, name, ok, detail })
+    console.log(`   ${ok ? '✓' : '✗'} [${group}] ${name}${detail ? ` — ${detail}` : ''}`)
+  }
+  const skip = (group: string, name: string, detail: string) => {
+    results.push({ group, name, ok: true, skipped: true, detail })
+    console.log(`   ⚠ SKIP [${group}] ${name} — ${detail}`)
+  }
+  // Converts a thrown exception into a recorded failure so one surprise doesn't abort the table.
+  const runScenario = async (group: string, name: string, fn: () => Promise<void>) => {
+    try {
+      await fn()
+    } catch (err: any) {
+      const message = err?.message ?? err?.error ?? JSON.stringify(err ?? {}).slice(0, 300)
+      record(group, name, false, `threw: ${message}`)
+    }
+  }
+
+  // phoneValidator normalizes to E.164, so generate +1555555xxxx values that are byte-comparable
+  // against what gets stored. 555-555-xxxx is the only 555 exchange libphonenumber accepts.
+  let phoneOffset = 0
+  const phoneSeed = Number(RUN.replace(/[^0-9]/g, '') || '0')
+  const nextPhone = () => `+1555555${String((phoneSeed + (phoneOffset += 1)) % 10_000).padStart(4, '0')}`
+
+  // The handler lowercases submitted emails before storing, so normalize here too — the overwrite
+  // predicates compare submitted and stored values directly.
+  const emailFor = (label: string) => `fswh-${label}-${RUN}@tellescope.com`.toLowerCase()
+
+  // responder_uuid is the form_response lookup key ({ source: 'Formsort', externalId }), and it is
+  // NOT scoped by formId — so it must be unique per scenario or drafts collide across scenarios.
+  const uuidFor = (label: string) => `fswh-${label}-${RUN}`
+
+  const createdEnduserIds: string[] = []
+  const createdFormIds: string[] = []
+  const createdApiKeyIds: string[] = []
+
+  // ---------------------------------------------------------------------------------------------
+  // Fixtures
+  // ---------------------------------------------------------------------------------------------
+  // The webhook parses `answers` by key directly (email / phone / fname / ts_enduser_*), NOT via
+  // form_fields, so the form needs no fields — it only has to exist and belong to this business.
+  const form = await sdk.api.forms.createOne({ title: `formsort auth field lock ${RUN}` })
+  createdFormIds.push(form.id)
+
+  // An UNSCOPED /v1 key does not authenticate this webhook (utf8 vs hex hashedKey — pinned by
+  // scoped_api_keys.test.ts). Create the key at runtime rather than depending on a seeded one.
+  const apiKey = await sdk.api.api_keys.createOne({ scopes: [FORM_INGESTION_API_KEY_SCOPE] })
+  createdApiKeyIds.push(apiKey.id)
+
+  const postWebhook = async (o: {
+    label: string,
+    answers: { key: string, value: any }[],
+    finalized: boolean,
+    enduserId?: string,
+    createNewEnduser?: boolean,
+  }) => {
+    const url = new URL(`${host}/v1/webhooks/form-ingestion/${apiKey.key}`)
+    url.searchParams.set('formId', form.id)
+    url.searchParams.set('returnJSON', 'true')
+    if (o.enduserId) url.searchParams.set('enduserId', o.enduserId)
+    if (o.createNewEnduser) url.searchParams.set('createNewEnduser', 'true')
+
+    const res = await axios.post(
+      url.toString(),
+      { answers: o.answers, responder_uuid: uuidFor(o.label), finalized: o.finalized },
+      { validateStatus: () => true },
+    )
+    // In-progress webhooks always return a bare 200 (the handler returns before the returnJSON
+    // block), so `data` is only populated for finalized calls.
+    return { status: res.status, data: (res.data || {}) as { formResponseId?: string, enduserId?: string } }
+  }
+
+  const makeVictim = async (label: string, fields: Partial<Enduser>) => {
+    const victim = await sdk.api.endusers.createOne({ ...fields } as any)
+    createdEnduserIds.push(victim.id)
+    return victim
+  }
+
+  const pollEnduser = async (id: string, landed: (e: Enduser) => boolean, windowMs = OVERWRITE_WINDOW_MS) => {
+    const deadline = Date.now() + windowMs
+    let enduser: Enduser | null = null
+    while (Date.now() < deadline) {
+      enduser = await sdk.api.endusers.getOne(id).catch(() => null) as Enduser | null
+      if (enduser && landed(enduser)) return enduser
+      await sleep(POLL_INTERVAL_MS)
+    }
+    return enduser
+  }
+
+  // A scenario that expects a MATCH is meaningless if the handler inserted instead — the victim
+  // would look untouched and the probe would false-pass. returnJSON hands back the id it landed on.
+  const matched = (group: string, name: string, data: { enduserId?: string }, victimId: string) => {
+    if (data?.enduserId === victimId) return true
+    record(group, name, false,
+      `probe invalid: webhook landed on enduserId=${data?.enduserId || '(none)'} expected victim=${victimId}`)
+    return false
+  }
+
+  // ---------------------------------------------------------------------------------------------
+  // R1 — matched on PHONE, submitted email must not land.
+  // ---------------------------------------------------------------------------------------------
+  await runScenario('R1', 'phone match does not repoint email', async () => {
+    const originalEmail = emailFor('r1')
+    const phone = nextPhone()
+    const victim = await makeVictim('r1', { email: originalEmail, phone })
+    const attackerEmail = emailFor('r1-attacker')
+
+    const { data } = await postWebhook({
+      label: 'r1',
+      finalized: true,
+      answers: [{ key: 'phone', value: phone }, { key: 'email', value: attackerEmail }],
+    })
+    if (!matched('R1', 'phone match does not repoint email', data, victim.id)) return
+
+    const enduser = await pollEnduser(victim.id, e => e.email === attackerEmail)
+    record('R1', 'phone match does not repoint email', enduser?.email === originalEmail,
+      `email=${enduser?.email || '(unset)'} expected=${originalEmail}`)
+  })
+
+  // ---------------------------------------------------------------------------------------------
+  // R2 — matched on EMAIL, submitted phone must not land.
+  // ---------------------------------------------------------------------------------------------
+  await runScenario('R2', 'email match does not repoint phone', async () => {
+    const email = emailFor('r2')
+    const originalPhone = nextPhone()
+    const victim = await makeVictim('r2', { email, phone: originalPhone })
+    const attackerPhone = nextPhone()
+
+    const { data } = await postWebhook({
+      label: 'r2',
+      finalized: true,
+      answers: [{ key: 'email', value: email }, { key: 'phone', value: attackerPhone }],
+    })
+    if (!matched('R2', 'email match does not repoint phone', data, victim.id)) return
+
+    const enduser = await pollEnduser(victim.id, e => e.phone === attackerPhone)
+    record('R2', 'email match does not repoint phone', enduser?.phone === originalPhone,
+      `phone=${enduser?.phone || '(unset)'} expected=${originalPhone}`)
+  })
+
+  // ---------------------------------------------------------------------------------------------
+  // R3 — stickiness. The draft matched a pre-existing patient by phone; the finalize resolves that
+  // patient via existingResponse.enduserId (path 2), which is the OPEN path. It must stay blocked,
+  // because the response was formed by a guess — that is what the sticky flag records.
+  // ---------------------------------------------------------------------------------------------
+  await runScenario('R3', 'draft formed by a guess stays blocked on finalize', async () => {
+    const originalEmail = emailFor('r3')
+    const phone = nextPhone()
+    const victim = await makeVictim('r3', { email: originalEmail, phone })
+    const attackerEmail = emailFor('r3-attacker')
+
+    // in-progress webhook: enough to match (phone present), creates the draft response
+    await postWebhook({ label: 'r3', finalized: false, answers: [{ key: 'phone', value: phone }] })
+
+    const { data } = await postWebhook({
+      label: 'r3',
+      finalized: true,
+      answers: [{ key: 'phone', value: phone }, { key: 'email', value: attackerEmail }],
+    })
+    if (!matched('R3', 'draft formed by a guess stays blocked on finalize', data, victim.id)) return
+
+    const enduser = await pollEnduser(victim.id, e => e.email === attackerEmail)
+    record('R3', 'draft formed by a guess stays blocked on finalize', enduser?.email === originalEmail,
+      `email=${enduser?.email || '(unset)'} expected=${originalEmail}`)
+  })
+
+  // ---------------------------------------------------------------------------------------------
+  // R4 — an unresolvable ?enduserId= must NOT count as an explicit assertion. findById returns null,
+  // the chain falls through to the $or guess, and the write must stay blocked. This pins that the
+  // override keys off the RESOLVED record, not the mere presence of the query param. A cross-tenant
+  // id takes the same route: DB is businessId-scoped, so findById returns null for it too.
+  // ---------------------------------------------------------------------------------------------
+  await runScenario('R4', 'unresolvable enduserId falls through to the guess', async () => {
+    const originalEmail = emailFor('r4')
+    const phone = nextPhone()
+    const victim = await makeVictim('r4', { email: originalEmail, phone })
+    const attackerEmail = emailFor('r4-attacker')
+
+    const { data } = await postWebhook({
+      label: 'r4',
+      finalized: true,
+      enduserId: '0000000000000000000000ff', // well-formed, nonexistent
+      answers: [{ key: 'phone', value: phone }, { key: 'email', value: attackerEmail }],
+    })
+    if (!matched('R4', 'unresolvable enduserId falls through to the guess', data, victim.id)) return
+
+    const enduser = await pollEnduser(victim.id, e => e.email === attackerEmail)
+    record('R4', 'unresolvable enduserId falls through to the guess', enduser?.email === originalEmail,
+      `email=${enduser?.email || '(unset)'} expected=${originalEmail}`)
+  })
+
+  // ---------------------------------------------------------------------------------------------
+  // R5 — victim shapes. A blank field is the LOAD-BEARING case: phone-only patients are common and
+  // cheap to create, and filling their blank email is the takeover primitive. "Only if blank" is
+  // therefore the wrong fix, and these two rows are what prove it.
+  // ---------------------------------------------------------------------------------------------
+  await runScenario('R5', 'blank email on a phone-only patient is not filled by a guess', async () => {
+    const phone = nextPhone()
+    const victim = await makeVictim('r5a', { phone, fname: 'Blank', lname: `Email${RUN}` })
+    const attackerEmail = emailFor('r5a-attacker')
+
+    const { data } = await postWebhook({
+      label: 'r5a',
+      finalized: true,
+      answers: [{ key: 'phone', value: phone }, { key: 'email', value: attackerEmail }],
+    })
+    if (!matched('R5', 'blank email on a phone-only patient is not filled by a guess', data, victim.id)) return
+
+    const enduser = await pollEnduser(victim.id, e => e.email === attackerEmail)
+    record('R5', 'blank email on a phone-only patient is not filled by a guess', !enduser?.email,
+      `email=${enduser?.email || '(unset)'} expected=(unset)`)
+  })
+
+  await runScenario('R5', 'blank phone on an email-only patient is not filled by a guess', async () => {
+    const email = emailFor('r5b')
+    const victim = await makeVictim('r5b', { email })
+    const attackerPhone = nextPhone()
+
+    const { data } = await postWebhook({
+      label: 'r5b',
+      finalized: true,
+      answers: [{ key: 'email', value: email }, { key: 'phone', value: attackerPhone }],
+    })
+    if (!matched('R5', 'blank phone on an email-only patient is not filled by a guess', data, victim.id)) return
+
+    const enduser = await pollEnduser(victim.id, e => e.phone === attackerPhone)
+    record('R5', 'blank phone on an email-only patient is not filled by a guess', !enduser?.phone,
+      `phone=${enduser?.phone || '(unset)'} expected=(unset)`)
+  })
+
+  // ---------------------------------------------------------------------------------------------
+  // G6 — the carve-out. The draft CREATED this patient (no prior record matched), so the response is
+  // not flagged and the same person may still correct their email on a later page of the form.
+  // ---------------------------------------------------------------------------------------------
+  await runScenario('G6', 'patient created by this draft may still correct their email', async () => {
+    const firstEmail = emailFor('g6-typo')
+    const correctedEmail = emailFor('g6-correct')
+    const phone = nextPhone()
+
+    // in-progress webhook with a never-before-seen email: inserts a new patient, response unflagged
+    await postWebhook({
+      label: 'g6',
+      finalized: false,
+      answers: [{ key: 'email', value: firstEmail }, { key: 'phone', value: phone }],
+    })
+
+    const { data } = await postWebhook({
+      label: 'g6',
+      finalized: true,
+      answers: [{ key: 'email', value: correctedEmail }, { key: 'phone', value: phone }],
+    })
+    if (!data?.enduserId) {
+      record('G6', 'patient created by this draft may still correct their email', false,
+        'probe invalid: webhook returned no enduserId')
+      return
+    }
+    createdEnduserIds.push(data.enduserId)
+
+    const enduser = await pollEnduser(data.enduserId, e => e.email === correctedEmail)
+    record('G6', 'patient created by this draft may still correct their email', enduser?.email === correctedEmail,
+      `email=${enduser?.email || '(unset)'} expected=${correctedEmail}`)
+  })
+
+  // ---------------------------------------------------------------------------------------------
+  // G7 — the backwards-compat escape hatch. An API-key-authenticated caller that names the patient
+  // explicitly still writes email and phone. Pinned so a later tightening can't silently remove it.
+  // ---------------------------------------------------------------------------------------------
+  await runScenario('G7', 'explicit enduserId still writes email and phone', async () => {
+    const victim = await makeVictim('g7', { email: emailFor('g7'), phone: nextPhone() })
+    const newEmail = emailFor('g7-new')
+    const newPhone = nextPhone()
+
+    const { data } = await postWebhook({
+      label: 'g7',
+      finalized: true,
+      enduserId: victim.id,
+      answers: [{ key: 'email', value: newEmail }, { key: 'phone', value: newPhone }],
+    })
+    if (!matched('G7', 'explicit enduserId still writes email and phone', data, victim.id)) return
+
+    const enduser = await pollEnduser(victim.id, e => e.email === newEmail && e.phone === newPhone)
+    record('G7', 'explicit enduserId still writes email', enduser?.email === newEmail,
+      `email=${enduser?.email || '(unset)'} expected=${newEmail}`)
+    record('G7', 'explicit enduserId still writes phone', enduser?.phone === newPhone,
+      `phone=${enduser?.phone || '(unset)'} expected=${newPhone}`)
+  })
+
+  // ---------------------------------------------------------------------------------------------
+  // G8 — ?createNewEnduser=true inserts a BLANK record up front and then fills it via the update
+  // branch, so email/phone must still land there.
+  // ---------------------------------------------------------------------------------------------
+  await runScenario('G8', 'createNewEnduser still writes email and phone', async () => {
+    const newEmail = emailFor('g8')
+    const newPhone = nextPhone()
+
+    const { data } = await postWebhook({
+      label: 'g8',
+      finalized: true,
+      createNewEnduser: true,
+      answers: [{ key: 'email', value: newEmail }, { key: 'phone', value: newPhone }],
+    })
+    if (!data?.enduserId) {
+      record('G8', 'createNewEnduser still writes email and phone', false,
+        'probe invalid: webhook returned no enduserId')
+      return
+    }
+    createdEnduserIds.push(data.enduserId)
+
+    const enduser = await pollEnduser(data.enduserId, e => e.email === newEmail && e.phone === newPhone)
+    record('G8', 'createNewEnduser still writes email', enduser?.email === newEmail,
+      `email=${enduser?.email || '(unset)'} expected=${newEmail}`)
+    record('G8', 'createNewEnduser still writes phone', enduser?.phone === newPhone,
+      `phone=${enduser?.phone || '(unset)'} expected=${newPhone}`)
+  })
+
+  // ---------------------------------------------------------------------------------------------
+  // G9 — brand-new patient, no prior record to match: the INSERT path keeps both fields.
+  // ---------------------------------------------------------------------------------------------
+  await runScenario('G9', 'brand-new patient is inserted with email and phone', async () => {
+    const newEmail = emailFor('g9')
+    const newPhone = nextPhone()
+
+    const { data } = await postWebhook({
+      label: 'g9',
+      finalized: true,
+      answers: [{ key: 'email', value: newEmail }, { key: 'phone', value: newPhone }],
+    })
+    if (!data?.enduserId) {
+      record('G9', 'brand-new patient is inserted with email and phone', false,
+        'probe invalid: webhook returned no enduserId')
+      return
+    }
+    createdEnduserIds.push(data.enduserId)
+
+    const enduser = await pollEnduser(data.enduserId, e => !!e.email && !!e.phone)
+    record('G9', 'brand-new patient is inserted with email', enduser?.email === newEmail,
+      `email=${enduser?.email || '(unset)'} expected=${newEmail}`)
+    record('G9', 'brand-new patient is inserted with phone', enduser?.phone === newPhone,
+      `phone=${enduser?.phone || '(unset)'} expected=${newPhone}`)
+  })
+
+  // ---------------------------------------------------------------------------------------------
+  // G10 — the narrowing is email/phone ONLY. Everything else the webhook parses must still update
+  // on a guessed match, otherwise this fix has quietly broken Formsort intake.
+  // ---------------------------------------------------------------------------------------------
+  await runScenario('G10', 'non-auth fields still update on a guessed match', async () => {
+    const originalEmail = emailFor('g10')
+    const phone = nextPhone()
+    const victim = await makeVictim('g10', {
+      email: originalEmail, phone, fname: 'Before', lname: 'Before',
+    })
+
+    const { data } = await postWebhook({
+      label: 'g10',
+      finalized: true,
+      answers: [
+        { key: 'phone', value: phone },
+        { key: 'email', value: emailFor('g10-attacker') },
+        { key: 'fname', value: 'After' },
+        { key: 'lname', value: 'After' },
+        { key: 'gender', value: 'Male' },
+        { key: 'dateOfBirth', value: '1990-01-02' }, // YYYY-MM-DD in, MM-DD-YYYY stored
+        { key: 'ts_enduser_lockprobe', value: `probe-${RUN}` },
+      ],
+    })
+    if (!matched('G10', 'non-auth fields still update on a guessed match', data, victim.id)) return
+
+    const enduser = await pollEnduser(victim.id, e => e.fname === 'After')
+    record('G10', 'fname still updates', enduser?.fname === 'After',
+      `fname=${enduser?.fname || '(unset)'} expected=After`)
+    record('G10', 'lname still updates', enduser?.lname === 'After',
+      `lname=${enduser?.lname || '(unset)'} expected=After`)
+    record('G10', 'gender still updates', enduser?.gender === 'Male',
+      `gender=${enduser?.gender || '(unset)'} expected=Male`)
+    record('G10', 'dateOfBirth still updates', enduser?.dateOfBirth === '01-02-1990',
+      `dateOfBirth=${enduser?.dateOfBirth || '(unset)'} expected=01-02-1990`)
+    record('G10', 'custom fields still update', enduser?.fields?.lockprobe === `probe-${RUN}`,
+      `fields.lockprobe=${enduser?.fields?.lockprobe || '(unset)'} expected=probe-${RUN}`)
+    record('G10', 'email still blocked while other fields update', enduser?.email === originalEmail,
+      `email=${enduser?.email || '(unset)'} expected=${originalEmail}`)
+  })
+
+  // ---------------------------------------------------------------------------------------------
+  // G11 — the explicit override is per-REQUEST, not a flag reset. A response formed by a guess keeps
+  // authFieldIntakeDisabled set, so the OTHER consumer of that flag
+  // (save_enduser_updates_for_form_response, reached by later staff edits) stays protected.
+  // ---------------------------------------------------------------------------------------------
+  await runScenario('G11', 'explicit override does not clear the stored flag', async () => {
+    const phone = nextPhone()
+    const victim = await makeVictim('g11', { email: emailFor('g11'), phone })
+    const newEmail = emailFor('g11-new')
+
+    // draft formed by a guess -> flagged
+    await postWebhook({ label: 'g11', finalized: false, answers: [{ key: 'phone', value: phone }] })
+
+    const { data } = await postWebhook({
+      label: 'g11',
+      finalized: true,
+      enduserId: victim.id,
+      answers: [{ key: 'phone', value: phone }, { key: 'email', value: newEmail }],
+    })
+    if (!matched('G11', 'explicit override does not clear the stored flag', data, victim.id)) return
+
+    const enduser = await pollEnduser(victim.id, e => e.email === newEmail)
+    record('G11', 'explicit override writes email even on a flagged response', enduser?.email === newEmail,
+      `email=${enduser?.email || '(unset)'} expected=${newEmail}`)
+
+    if (!data.formResponseId) {
+      skip('G11', 'stored flag survives the override', 'webhook returned no formResponseId')
+      return
+    }
+    const response: any = await sdk.api.form_responses.getOne(data.formResponseId).catch(() => null)
+    if (!response) {
+      skip('G11', 'stored flag survives the override', 'form response not readable')
+    } else if (response.authFieldIntakeDisabled === undefined) {
+      // The field is deliberately absent from schema.ts; if reads project it away there is nothing
+      // to assert here, and the enforcement is already covered by the scenarios above.
+      skip('G11', 'stored flag survives the override', 'authFieldIntakeDisabled not exposed on read')
+    } else {
+      record('G11', 'stored flag survives the override', response.authFieldIntakeDisabled === true,
+        `authFieldIntakeDisabled=${response.authFieldIntakeDisabled} expected=true`)
+    }
+  })
+
+  // ---------------------------------------------------------------------------------------------
+  // G12 — the Stripe grace. A contact the Stripe integration created minutes ago carries payment data
+  // only (email + name + stripeCustomerId, never a phone), so intake is the first place a phone number
+  // exists at all. enduser_is_provisional_stripe_record re-opens BLANK email/phone for one hour after
+  // that insert; see api/integrations/payments/stripe_provisional_enduser.ts.
+  //
+  // The Stripe webhook cannot be driven locally (it needs a signature and an integration record), but
+  // nothing about the grace depends on Stripe having done the insert: source and stripeCustomerId are
+  // both enduserUpdatesDisabled, so an admin can create the same shape and drive the real webhook
+  // against it. A fixture created here always has a fresh ObjectId, so this exercises the in-window
+  // branch; the expired branch is pinned by the unit tests in
+  // api/integrations/payments/stripe_provisional_enduser.test.ts.
+  // ---------------------------------------------------------------------------------------------
+  const stripeVictim = (label: string, fields: Partial<Enduser>) => makeVictim(label, {
+    source: 'Stripe',
+    stripeCustomerId: `cus_${RUN}${label}`,
+    ...fields,
+  })
+
+  await runScenario('G12', 'blank phone on a fresh Stripe contact is filled from intake', async () => {
+    const email = emailFor('g12')
+    const victim = await stripeVictim('g12', { email, fname: 'Stripe', lname: `Payer${RUN}` })
+    const intakePhone = nextPhone()
+
+    const { data } = await postWebhook({
+      label: 'g12',
+      finalized: true,
+      answers: [
+        { key: 'email', value: email },
+        { key: 'phone', value: intakePhone },
+        { key: 'dateOfBirth', value: '1990-01-02' }, // Stripe has no DOB; intake is the first source
+        { key: 'ts_enduser_stripeprobe', value: `probe-${RUN}` },
+      ],
+    })
+    if (!matched('G12', 'blank phone on a fresh Stripe contact is filled from intake', data, victim.id)) return
+
+    const enduser = await pollEnduser(victim.id, e => e.phone === intakePhone)
+    record('G12', 'blank phone on a fresh Stripe contact is filled from intake', enduser?.phone === intakePhone,
+      `phone=${enduser?.phone || '(unset)'} expected=${intakePhone}`)
+    // the grace must not disturb the ordinary update path around it
+    record('G12', 'non-auth fields still land alongside the graced phone', enduser?.dateOfBirth === '01-02-1990',
+      `dateOfBirth=${enduser?.dateOfBirth || '(unset)'} expected=01-02-1990`)
+    record('G12', 'email is unchanged by the grace', enduser?.email === email,
+      `email=${enduser?.email || '(unset)'} expected=${email}`)
+  })
+
+  // ---------------------------------------------------------------------------------------------
+  // R12 / R13 — the grace is strictly BLANK-FILL. Repointing a stored email or phone is the takeover
+  // primitive this lock exists to stop, and being minutes old does not make it safe.
+  // ---------------------------------------------------------------------------------------------
+  await runScenario('R12', 'grace does not overwrite a phone already on a Stripe contact', async () => {
+    const email = emailFor('r12')
+    const originalPhone = nextPhone()
+    const victim = await stripeVictim('r12', { email, phone: originalPhone })
+    const attackerPhone = nextPhone()
+
+    const { data } = await postWebhook({
+      label: 'r12',
+      finalized: true,
+      answers: [{ key: 'email', value: email }, { key: 'phone', value: attackerPhone }],
+    })
+    if (!matched('R12', 'grace does not overwrite a phone already on a Stripe contact', data, victim.id)) return
+
+    const enduser = await pollEnduser(victim.id, e => e.phone === attackerPhone)
+    record('R12', 'grace does not overwrite a phone already on a Stripe contact', enduser?.phone === originalPhone,
+      `phone=${enduser?.phone || '(unset)'} expected=${originalPhone}`)
+  })
+
+  await runScenario('R13', 'grace does not repoint the email of a Stripe contact', async () => {
+    const originalEmail = emailFor('r13')
+    const phone = nextPhone()
+    const victim = await stripeVictim('r13', { email: originalEmail, phone })
+    const attackerEmail = emailFor('r13-attacker')
+
+    // matched on phone, so the submitted email is free to differ from the stored one
+    const { data } = await postWebhook({
+      label: 'r13',
+      finalized: true,
+      answers: [{ key: 'phone', value: phone }, { key: 'email', value: attackerEmail }],
+    })
+    if (!matched('R13', 'grace does not repoint the email of a Stripe contact', data, victim.id)) return
+
+    const enduser = await pollEnduser(victim.id, e => e.email === attackerEmail)
+    record('R13', 'grace does not repoint the email of a Stripe contact', enduser?.email === originalEmail,
+      `email=${enduser?.email || '(unset)'} expected=${originalEmail}`)
+  })
+
+  // ---------------------------------------------------------------------------------------------
+  // R14 — BOTH markers are load-bearing. `source` is set by every other integration and by staff, and
+  // `stripeCustomerId` can be attached to a contact this integration never created, so neither alone
+  // may open the grace.
+  // ---------------------------------------------------------------------------------------------
+  await runScenario('R14', 'stripeCustomerId without a Stripe source does not open the grace', async () => {
+    const email = emailFor('r14a')
+    const victim = await makeVictim('r14a', { email, source: 'Elation', stripeCustomerId: `cus_${RUN}r14a` })
+    const attackerPhone = nextPhone()
+
+    const { data } = await postWebhook({
+      label: 'r14a',
+      finalized: true,
+      answers: [{ key: 'email', value: email }, { key: 'phone', value: attackerPhone }],
+    })
+    if (!matched('R14', 'stripeCustomerId without a Stripe source does not open the grace', data, victim.id)) return
+
+    const enduser = await pollEnduser(victim.id, e => e.phone === attackerPhone)
+    record('R14', 'stripeCustomerId without a Stripe source does not open the grace', !enduser?.phone,
+      `phone=${enduser?.phone || '(unset)'} expected=(unset)`)
+  })
+
+  await runScenario('R14', 'Stripe source without a stripeCustomerId does not open the grace', async () => {
+    const email = emailFor('r14b')
+    const victim = await makeVictim('r14b', { email, source: 'Stripe' })
+    const attackerPhone = nextPhone()
+
+    const { data } = await postWebhook({
+      label: 'r14b',
+      finalized: true,
+      answers: [{ key: 'email', value: email }, { key: 'phone', value: attackerPhone }],
+    })
+    if (!matched('R14', 'Stripe source without a stripeCustomerId does not open the grace', data, victim.id)) return
+
+    const enduser = await pollEnduser(victim.id, e => e.phone === attackerPhone)
+    record('R14', 'Stripe source without a stripeCustomerId does not open the grace', !enduser?.phone,
+      `phone=${enduser?.phone || '(unset)'} expected=(unset)`)
+  })
+
+  // ---------------------------------------------------------------------------------------------
+  // R15 — the grace is a per-REQUEST override, exactly like the explicit ?enduserId= hatch in G11: the
+  // response still records that it attached to a pre-existing contact, so the other consumer of that
+  // flag (save_enduser_updates_for_form_response, reached by later staff edits and by submissions
+  // after the window closes) stays protected.
+  // ---------------------------------------------------------------------------------------------
+  await runScenario('R15', 'grace does not clear the stored flag', async () => {
+    const email = emailFor('r15')
+    const victim = await stripeVictim('r15', { email })
+    const intakePhone = nextPhone()
+
+    const { data } = await postWebhook({
+      label: 'r15',
+      finalized: true,
+      answers: [{ key: 'email', value: email }, { key: 'phone', value: intakePhone }],
+    })
+    if (!matched('R15', 'grace does not clear the stored flag', data, victim.id)) return
+
+    const enduser = await pollEnduser(victim.id, e => e.phone === intakePhone)
+    record('R15', 'grace landed the phone (probe precondition)', enduser?.phone === intakePhone,
+      `phone=${enduser?.phone || '(unset)'} expected=${intakePhone}`)
+
+    if (!data.formResponseId) {
+      skip('R15', 'grace does not clear the stored flag', 'webhook returned no formResponseId')
+      return
+    }
+    const response: any = await sdk.api.form_responses.getOne(data.formResponseId).catch(() => null)
+    if (!response) {
+      skip('R15', 'grace does not clear the stored flag', 'form response not readable')
+    } else if (response.authFieldIntakeDisabled === undefined) {
+      // deliberately absent from schema.ts; if reads project it away there is nothing to assert here
+      skip('R15', 'grace does not clear the stored flag', 'authFieldIntakeDisabled not exposed on read')
+    } else {
+      record('R15', 'grace does not clear the stored flag', response.authFieldIntakeDisabled === true,
+        `authFieldIntakeDisabled=${response.authFieldIntakeDisabled} expected=true`)
+    }
+  })
+
+  // ---------------------------------------------------------------------------------------------
+  // Report
+  // ---------------------------------------------------------------------------------------------
+  const failures = results.filter(r => !r.ok)
+  const skipped = results.filter(r => !!r.skipped)
+  console.log('')
+  console.log('   ┌─ Formsort webhook auth-field lock — summary ───────────────────────────')
+  for (const r of results) {
+    const status = r.skipped ? 'SKIP' : r.ok ? 'PASS' : 'FAIL'
+    console.log(`   │ ${status}  ${r.group.padEnd(3)}  ${r.name}${r.detail ? `  —  ${r.detail}` : ''}`)
+  }
+  console.log(`   └─ ${results.length - failures.length}/${results.length} passed, ${skipped.length} skipped, ${failures.length} failed`)
+  console.log('')
+
+  // ---------------------------------------------------------------------------------------------
+  // Cleanup — MUST run before the assert loop (see the note at the top of this file).
+  // ---------------------------------------------------------------------------------------------
+  for (const formId of createdFormIds) {
+    const responses = await sdk.api.form_responses.getSome({ filter: { formId } }).catch(() => [])
+    for (const response of responses) {
+      await sdk.api.form_responses.deleteOne(response.id).catch(() => null)
+    }
+  }
+  for (const id of createdFormIds) {
+    await sdk.api.forms.deleteOne(id).catch(() => null)
+  }
+  const uniqueEnduserIds = createdEnduserIds.filter((id, i) => !!id && createdEnduserIds.indexOf(id) === i)
+  for (const id of uniqueEnduserIds) {
+    await sdk.api.endusers.deleteOne(id).catch(() => null)
+  }
+  for (const id of createdApiKeyIds) {
+    await sdk.api.api_keys.deleteOne(id).catch(() => null)
+  }
+
+  // ---------------------------------------------------------------------------------------------
+  // Assert — single pass, last, so the full table above is always printed first.
+  // ---------------------------------------------------------------------------------------------
+  for (const r of results) {
+    assert(r.ok, `[${r.group}] ${r.name} — ${r.detail}`, `[${r.group}] ${r.name}`)
+  }
+}
+
+// Allow running this test file independently
+if (require.main === module) {
+  console.log(`🌐 Using API URL: ${host}`)
+  const sdk = new Session({ host })
+  const sdkNonAdmin = new Session({ host })
+
+  const runTests = async () => {
+    await setup_tests(sdk, sdkNonAdmin)
+    await formsort_webhook_auth_field_lock_tests({ sdk, sdkNonAdmin })
+  }
+
+  runTests()
+    .then(() => {
+      console.log("✅ Formsort webhook auth field lock tests completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ Formsort webhook auth field lock tests failed:", error)
+      process.exit(1)
+    })
+}