@tellescope/sdk 2.0.0-beta.1 → 2.0.0-beta.3

package/src/tests/api_tests/security/enduser-write-restrictions.test.ts

@@ -1,14 +1,16 @@
 require('source-map-support').install();
 
-import { Session, EnduserSession } from "../../../sdk"
+import { EnduserSession } from "../../../sdk"
 import {
-  async_test,
-  log_header,
-} from "@tellescope/testing"
-import { setup_tests } from "../../setup"
+  assert_checks,
+  Check,
+  IsolatedSuite,
+  setup_isolated_tenant,
+} from "../../setup_isolated"
 
 const host = process.env.API_URL || 'http://localhost:8080' as const
-const businessId = process.env.TEST_BUSINESS_ID || '60398b1131a295e64f084ff6'
+
+const RAND = () => Math.random().toString(36).slice(2, 10)
 
 const ENDUSER_PASSWORD = 'F0106TestPassword!123'
 
@@ -84,16 +86,93 @@ const restrictedFormResponseUpdates = (staffId: string, otherEnduserId: string):
  *   - nothing persists (spot-checked on assignedTo, the highest-impact field)
  *   - enduser self-updates of allowed fields still work (fname, hideFromEnduserPortal)
  *   - staff sessions can still update the restricted fields
+ *
+ * Runs on its own provisioned tenant, so the patient session's businessId comes from the tenant
+ * rather than a TEST_BUSINESS_ID env var with a hardcoded shared-org fallback. Checks are collected
+ * and returned rather than asserted inline: `assert` calls process.exit, which would skip this
+ * suite's `finally` cleanup and, in the parallel pool, every other in-flight suite's teardown.
  */
-export const enduser_write_restrictions_tests = async ({ sdk } : { sdk: Session, sdkNonAdmin: Session }) => {
-  log_header("enduser write restrictions (enduserUpdatesDisabled)")
+export const enduser_write_restrictions_checks = async (): Promise<Check[]> => {
+  const checks: Check[] = []
+  const record = (label: string, pass: boolean, detail: string) => checks.push({ label, pass, detail })
+
+  // The raw value decides the fallback, not JSON.stringify of it — JSON.stringify('') is '""',
+  // which is truthy, so a `|| fallback` on the stringified form could never fire.
+  const describe = (value: any): string => {
+    if (value === undefined || value === null) return String(value)
+    const stringified = JSON.stringify(value)
+    return stringified === undefined ? String(value) : stringified
+  }
+  const errorMessage = (e: any): string => (
+    typeof e?.message === 'string' && e.message !== '' ? e.message : describe(e)
+  )
+
+  /** The async_test({ shouldError, onError }) equivalent, as a soft Check. */
+  const expect_rejection = async (
+    label: string,
+    fn: () => Promise<any>,
+    expectedMessage: string,
+  ) => {
+    let error: any
+    let rejected = false
+    try {
+      await fn()
+    } catch (e: any) {
+      rejected = true
+      error = e
+    }
+
+    if (!rejected) {
+      // deliberately does NOT print the record: it is a patient profile / form response
+      record(label, false, `NOT REJECTED: the update succeeded (expected "${expectedMessage}")`)
+      return
+    }
+
+    const message = errorMessage(error)
+    record(
+      label,
+      message === expectedMessage,
+      message === expectedMessage
+        ? `rejected: ${message}`
+        : `rejected with the WRONG error: ${message} (expected "${expectedMessage}")`,
+    )
+  }
+
+  /**
+   * The async_test({ onResult }) equivalent, as a soft Check: a call that REJECTS is a failure
+   * (async_test treats it the same way), and a resolved call passes only when `inspect` agrees.
+   * `inspect` runs inside the try so a throw inside it fails this one check rather than escaping
+   * `run` and aborting every other suite in the batch. It returns the detail too, rather than this
+   * dumping the whole record — an enduser and a FormResponse carry the patient's name, email and
+   * answers, and the check table prints on every run.
+   */
+  const expect_result = async <T,>(
+    label: string,
+    fn: () => Promise<T>,
+    inspect: (r: T) => { pass: boolean, detail: string },
+  ) => {
+    try {
+      const { pass, detail } = inspect(await fn())
+      record(label, pass, detail)
+    } catch (e: any) {
+      record(label, false, `rejected instead of resolving: ${errorMessage(e)}`)
+    }
+  }
 
+  let tenant: Awaited<ReturnType<typeof setup_isolated_tenant>> | undefined
   let enduserId: string | undefined
   let otherEnduserId: string | undefined
   let formId: string | undefined
   let formResponseId: string | undefined
 
   try {
+    tenant = await setup_isolated_tenant({
+      name: `Enduser write restrictions ${RAND()}`,
+      users: [{ isAdmin: true }],
+      apiKeys: 0,
+    })
+    const { sdk } = tenant
+
     // Setup: throwaway enduser with portal credentials, plus a form_response they own
     const enduserEmail = `f0106-enduser-${Date.now()}@example.com`
     const enduser = await sdk.api.endusers.createOne({ email: enduserEmail, fname: 'F0106', lname: 'Restricted' })
@@ -106,7 +185,7 @@ export const enduser_write_restrictions_tests = async ({ sdk } : { sdk: Session,
     otherEnduserId = otherEnduser.id
     await sdk.api.endusers.set_password({ id: enduser.id, password: ENDUSER_PASSWORD })
 
-    const enduserSDK = new EnduserSession({ host, businessId })
+    const enduserSDK = new EnduserSession({ host, businessId: tenant.businessId })
     await enduserSDK.authenticate(enduserEmail, ENDUSER_PASSWORD)
 
     const form = await sdk.api.forms.createOne({ title: 'Write Restriction Test Form' })
@@ -119,54 +198,69 @@ export const enduser_write_restrictions_tests = async ({ sdk } : { sdk: Session,
 
     // ---- enduser self-update of restricted endusers fields must 400 ----
     for (const [field, value] of Object.entries(restrictedEnduserUpdates(sdk.userInfo.id, enduser.id))) {
-      await async_test(
+      await expect_rejection(
         `enduser cannot self-update endusers.${field}`,
         () => enduserSDK.api.endusers.updateOne(enduser.id, { [field]: value } as any),
-        { shouldError: true, onError: e => e.message === `${field} cannot be updated by endusers` },
+        `${field} cannot be updated by endusers`,
       )
     }
 
     // Variant A persistence check: the rejected assignedTo write must not
     // have granted the staff read-filter match.
-    await async_test(
+    await expect_result(
       'rejected assignedTo write did not persist',
       () => sdk.api.endusers.getOne(enduser.id),
-      { onResult: e => !e.assignedTo?.length && !e.tags?.length && e.externalId === undefined },
+      e => ({
+        pass: !e.assignedTo?.length && !e.tags?.length && e.externalId === undefined,
+        detail: `assignedTo=${describe(e.assignedTo)} tags=${describe(e.tags)} `
+          + `externalId=${describe(e.externalId)} (want none of them set)`,
+      }),
     )
 
     // ---- enduser self-update of restricted form_responses fields must 400 ----
     for (const [field, value] of Object.entries(restrictedFormResponseUpdates(sdk.userInfo.id, otherEnduser.id))) {
-      await async_test(
+      await expect_rejection(
         `enduser cannot self-update form_responses.${field}`,
         () => enduserSDK.api.form_responses.updateOne(formResponse.id, { [field]: value } as any),
-        { shouldError: true, onError: e => e.message === `${field} cannot be updated by endusers` },
+        `${field} cannot be updated by endusers`,
       )
     }
 
-    await async_test(
+    await expect_result(
       'rejected writes did not persist (markedAsSubmitted, procedureCodes, submittedBy, enduserId)',
       () => sdk.api.form_responses.getOne(formResponse.id),
-      { onResult: fr => (
-        !fr.markedAsSubmitted && !fr.procedureCodes?.length && fr.submittedBy === undefined
-        // still points at its own patient: a successful repoint is what redirects the intake write
-        && fr.enduserId === enduser.id
-      ) },
+      fr => ({
+        pass: (
+          !fr.markedAsSubmitted && !fr.procedureCodes?.length && fr.submittedBy === undefined
+          // still points at its own patient: a successful repoint is what redirects the intake write
+          && fr.enduserId === enduser.id
+        ),
+        detail: `markedAsSubmitted=${describe(fr.markedAsSubmitted)} `
+          + `procedureCodes=${describe(fr.procedureCodes?.length)} submittedBy=${describe(fr.submittedBy)} `
+          + `enduserId matches own=${describe(fr.enduserId === enduser.id)}`,
+      }),
     )
 
     // ---- Positive controls: intended enduser self-updates still work ----
-    await async_test(
+    await expect_result(
       'enduser can still update own profile fields (fname/lname)',
       () => enduserSDK.api.endusers.updateOne(enduser.id, { fname: 'StillAllowed', lname: 'Patient' }),
-      { onResult: e => e.fname === 'StillAllowed' && e.lname === 'Patient' },
+      e => ({
+        pass: e.fname === 'StillAllowed' && e.lname === 'Patient',
+        detail: `fname set=${describe(e.fname === 'StillAllowed')} lname set=${describe(e.lname === 'Patient')}`,
+      }),
     )
-    await async_test(
+    await expect_result(
       'enduser can still update own form_response (hideFromEnduserPortal — intended per schema)',
       () => enduserSDK.api.form_responses.updateOne(formResponse.id, { hideFromEnduserPortal: true }),
-      { onResult: fr => fr.hideFromEnduserPortal === true },
+      fr => ({
+        pass: fr.hideFromEnduserPortal === true,
+        detail: `hideFromEnduserPortal=${describe(fr.hideFromEnduserPortal)} (want true)`,
+      }),
     )
 
     // ---- Positive controls: staff sessions are unaffected by enduserUpdatesDisabled ----
-    await async_test(
+    await expect_result(
       'staff can still update restricted endusers fields (tags, assignedTo, externalId, note, source)',
       () => sdk.api.endusers.updateOne(enduser.id, {
         tags: ['staff-set-tag'],
@@ -175,66 +269,90 @@ export const enduser_write_restrictions_tests = async ({ sdk } : { sdk: Session,
         note: 'staff-set note',
         source: 'staff-set-source',
       }),
-      { onResult: e => (
-        !!e.tags?.includes('staff-set-tag')
-        && !!e.assignedTo?.includes(sdk.userInfo.id)
-        && e.externalId === 'staff-set-external-id'
-      ) },
+      e => ({
+        pass: (
+          !!e.tags?.includes('staff-set-tag')
+          && !!e.assignedTo?.includes(sdk.userInfo.id)
+          && e.externalId === 'staff-set-external-id'
+        ),
+        detail: `tags=${describe(e.tags)} assignedTo includes staff=`
+          + `${describe(!!e.assignedTo?.includes(sdk.userInfo.id))} externalId=${describe(e.externalId)}`,
+      }),
     )
-    await async_test(
+    await expect_result(
       'staff can still update restricted form_responses fields (procedureCodes, diagnosisCodes, tags)',
       () => sdk.api.form_responses.updateOne(formResponse.id, {
         procedureCodes: [{ code: 'G0019', units: 1 }],
         diagnosisCodes: [{ code: 'Z71.3', description: 'Dietary counseling and surveillance' }],
         tags: ['staff-set-tag'],
       }),
-      { onResult: fr => (
-        fr.procedureCodes?.[0]?.code === 'G0019'
-        && fr.diagnosisCodes?.[0]?.code === 'Z71.3'
-        && !!fr.tags?.includes('staff-set-tag')
-      ) },
+      fr => ({
+        pass: (
+          fr.procedureCodes?.[0]?.code === 'G0019'
+          && fr.diagnosisCodes?.[0]?.code === 'Z71.3'
+          && !!fr.tags?.includes('staff-set-tag')
+        ),
+        detail: `procedureCodes[0].code=${describe(fr.procedureCodes?.[0]?.code)} `
+          + `diagnosisCodes[0].code=${describe(fr.diagnosisCodes?.[0]?.code)} tags=${describe(fr.tags)}`,
+      }),
     )
 
     // enduserId is enduserUpdatesDisabled rather than updatesDisabled specifically so this keeps
     // working: staff sometimes need to move a response to the correct profile to fix a mistake.
-    await async_test(
+    await expect_result(
       'staff can still repoint form_responses.enduserId to another patient',
       () => sdk.api.form_responses.updateOne(formResponse.id, { enduserId: otherEnduser.id }),
-      { onResult: fr => fr.enduserId === otherEnduser.id },
+      fr => ({
+        pass: fr.enduserId === otherEnduser.id,
+        detail: `repointed to the other patient=${describe(fr.enduserId === otherEnduser.id)}`,
+      }),
     )
-    await async_test(
+    await expect_result(
       'staff can repoint form_responses.enduserId back',
       () => sdk.api.form_responses.updateOne(formResponse.id, { enduserId: enduser.id }),
-      { onResult: fr => fr.enduserId === enduser.id },
+      fr => ({
+        pass: fr.enduserId === enduser.id,
+        detail: `repointed back to the owner=${describe(fr.enduserId === enduser.id)}`,
+      }),
     )
   } finally {
-    if (formResponseId) {
-      try { await sdk.api.form_responses.deleteOne(formResponseId) } catch {}
-    }
-    if (formId) {
-      try { await sdk.api.forms.deleteOne(formId) } catch {}
-    }
-    if (enduserId) {
-      try { await sdk.api.endusers.deleteOne(enduserId) } catch {}
-    }
-    if (otherEnduserId) {
-      try { await sdk.api.endusers.deleteOne(otherEnduserId) } catch {}
+    if (tenant) {
+      const { sdk } = tenant
+      if (formResponseId) {
+        try { await sdk.api.form_responses.deleteOne(formResponseId) } catch {}
+      }
+      if (formId) {
+        try { await sdk.api.forms.deleteOne(formId) } catch {}
+      }
+      if (enduserId) {
+        try { await sdk.api.endusers.deleteOne(enduserId) } catch {}
+      }
+      if (otherEnduserId) {
+        try { await sdk.api.endusers.deleteOne(otherEnduserId) } catch {}
+      }
+      // Teardown BEFORE anything asserts — assert calls process.exit, which would strand this tenant.
+      try { await tenant.teardown() } catch (e) { console.error('teardown failed', e) }
     }
   }
+
+  return checks
+}
+
+/** Asserting wrapper, for standalone runs. */
+export const enduser_write_restrictions_tests = async () => {
+  assert_checks('Enduser write restrictions', await enduser_write_restrictions_checks())
+}
+
+/** Enrolls this suite in the auto-discovered parallel pool — see run_discovered_isolated_suites. */
+export const ISOLATED_SUITE: IsolatedSuite = {
+  name: 'Enduser write restrictions',
+  run: enduser_write_restrictions_checks,
 }
 
 // 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 enduser_write_restrictions_tests({ sdk, sdkNonAdmin })
-  }
-
-  runTests()
+  enduser_write_restrictions_tests()
     .then(() => {
       console.log("✅ enduser write-restriction test suite completed successfully")
       process.exit(0)

package/src/tests/api_tests/security/file-link-session-confinement.test.ts

@@ -6,6 +6,7 @@ import {
   assert_checks,
   Check,
   setup_isolated_tenant,
+  IsolatedSuite,
 } from "../../setup_isolated"
 
 const host = process.env.API_URL || 'http://localhost:8080' as const
@@ -276,6 +277,9 @@ export const file_link_session_confinement_tests = async () => {
   assert_checks('Shared file link session confinement', await file_link_session_confinement_checks())
 }
 
+/** Enrolls this suite in the auto-discovered parallel pool — see run_discovered_isolated_suites. */
+export const ISOLATED_SUITE: IsolatedSuite = { name: 'Shared file link session confinement', run: file_link_session_confinement_checks }
+
 // Allow running this test file independently
 if (require.main === module) {
   console.log(`🌐 Using API URL: ${host}`)

package/src/tests/api_tests/security/form-logic-js-execution.test.ts

@@ -4,6 +4,7 @@ import {
   assert_checks,
   Check,
   setup_isolated_tenant,
+  IsolatedSuite,
 } from "../../setup_isolated"
 
 const host = process.env.API_URL || 'http://localhost:8080' as const
@@ -168,6 +169,9 @@ export const form_logic_js_execution_tests = async () => {
   assert_checks('$JS in stored conditional logic', await form_logic_js_execution_checks())
 }
 
+/** Enrolls this suite in the auto-discovered parallel pool — see run_discovered_isolated_suites. */
+export const ISOLATED_SUITE: IsolatedSuite = { name: '$JS in stored conditional logic', run: form_logic_js_execution_checks }
+
 // Allow running this test file independently
 if (require.main === module) {
   console.log(`🌐 Using API URL: ${host}`)

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

@@ -65,6 +65,19 @@ const host = process.env.API_URL || 'http://localhost:8080' as const
  *   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
  *
+ * ?alwaysSetPhone=true (CU-86e3k4ptv) is a second per-request override, narrower than ?enduserId=:
+ * it allows PHONE ONLY through the lock, on every finalized webhook, overwriting an existing and
+ * different number. Email — the password-reset channel this lock exists to protect — stays blocked.
+ *   G16 (GREEN) the flag overwrites an existing, different phone on a guessed match
+ *   G17 (GREEN) ...and in that same request the submitted email is still dropped
+ *   R16 (RED)   the identical request WITHOUT the flag leaves both phone and email blocked
+ *   R17 (RED)   the flag does not open email on a phone match either
+ *   R18 (RED)   only the literal string 'true' enables it — ?alwaysSetPhone=1 keeps the lock
+ *   G18 (GREEN) a flagged webhook still stamps authFieldIntakeDisabled on the response, so later
+ *               writes through save_enduser_updates_for_form_response stay blocked
+ *   R19 (RED)   it is request-scoped: a flag passed on an earlier webhook for the same
+ *               responder_uuid does not unlock a later one that omits it
+ *
  * 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.
@@ -155,12 +168,15 @@ export const formsort_webhook_auth_field_lock_tests = async (
     finalized: boolean,
     enduserId?: string,
     createNewEnduser?: boolean,
+    // sent verbatim, so a scenario can pin that only the literal string 'true' enables the opt-in
+    alwaysSetPhone?: string,
   }) => {
     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')
+    if (o.alwaysSetPhone !== undefined) url.searchParams.set('alwaysSetPhone', o.alwaysSetPhone)
 
     const res = await axios.post(
       url.toString(),
@@ -688,6 +704,215 @@ export const formsort_webhook_auth_field_lock_tests = async (
     }
   })
 
+  // ---------------------------------------------------------------------------------------------
+  // G16 — ?alwaysSetPhone=true: the opt-in allows phone through the lock on a GUESSED match (the
+  // path R2 blocks), overwriting a phone that is already stored and different. Phone is also the
+  // only field this submission changes, which exercises the "at least one update provided" guard —
+  // if the delete happened before that guard, nothing would be written at all.
+  // ---------------------------------------------------------------------------------------------
+  await runScenario('G16', 'alwaysSetPhone=true overwrites an existing phone on a guessed match', async () => {
+    const email = emailFor('g16')
+    const originalPhone = nextPhone()
+    const victim = await makeVictim('g16', { email, phone: originalPhone })
+    const intakePhone = nextPhone()
+
+    const { data } = await postWebhook({
+      label: 'g16',
+      finalized: true,
+      alwaysSetPhone: 'true',
+      answers: [{ key: 'email', value: email }, { key: 'phone', value: intakePhone }],
+    })
+    if (!matched('G16', 'alwaysSetPhone=true overwrites an existing phone on a guessed match', data, victim.id)) return
+
+    const enduser = await pollEnduser(victim.id, e => e.phone === intakePhone)
+    record('G16', 'alwaysSetPhone=true overwrites an existing phone on a guessed match',
+      enduser?.phone === intakePhone,
+      `phone=${enduser?.phone || '(unset)'} expected=${intakePhone}`)
+  })
+
+  // ---------------------------------------------------------------------------------------------
+  // G17 — the same request, with BOTH a new phone and a different email, so the two halves of the
+  // rule are observed together: phone lands, email does not. Shaped like R3 (a draft formed by a
+  // guess, finalized through the sticky flag) because that is the only resolution path where the
+  // submitted email can differ from the stored one while the patient still matches.
+  // ---------------------------------------------------------------------------------------------
+  await runScenario('G17', 'alwaysSetPhone=true writes phone and still drops email', async () => {
+    const originalEmail = emailFor('g17')
+    const originalPhone = nextPhone()
+    const victim = await makeVictim('g17', { email: originalEmail, phone: originalPhone })
+    const attackerEmail = emailFor('g17-attacker')
+    const intakePhone = nextPhone()
+
+    // draft matches the pre-existing patient by phone -> authFieldIntakeDisabled is stamped on it
+    await postWebhook({ label: 'g17', finalized: false, answers: [{ key: 'phone', value: originalPhone }] })
+
+    const { data } = await postWebhook({
+      label: 'g17',
+      finalized: true,
+      alwaysSetPhone: 'true',
+      answers: [{ key: 'phone', value: intakePhone }, { key: 'email', value: attackerEmail }],
+    })
+    if (!matched('G17', 'alwaysSetPhone=true writes phone and still drops email', data, victim.id)) return
+
+    const enduser = await pollEnduser(victim.id, e => e.phone === intakePhone)
+    record('G17', 'alwaysSetPhone=true writes phone through the sticky flag', enduser?.phone === intakePhone,
+      `phone=${enduser?.phone || '(unset)'} expected=${intakePhone}`)
+    record('G17', 'alwaysSetPhone=true leaves email blocked in the same request',
+      enduser?.email === originalEmail,
+      `email=${enduser?.email || '(unset)'} expected=${originalEmail}`)
+  })
+
+  // ---------------------------------------------------------------------------------------------
+  // R16 — the control for G17: byte-identical request without the flag. Both fields stay blocked,
+  // i.e. the default behavior is unchanged.
+  // ---------------------------------------------------------------------------------------------
+  await runScenario('R16', 'without the flag the same request blocks phone and email', async () => {
+    const originalEmail = emailFor('r16')
+    const originalPhone = nextPhone()
+    const victim = await makeVictim('r16', { email: originalEmail, phone: originalPhone })
+    const attackerEmail = emailFor('r16-attacker')
+    const intakePhone = nextPhone()
+
+    await postWebhook({ label: 'r16', finalized: false, answers: [{ key: 'phone', value: originalPhone }] })
+
+    const { data } = await postWebhook({
+      label: 'r16',
+      finalized: true,
+      answers: [{ key: 'phone', value: intakePhone }, { key: 'email', value: attackerEmail }],
+    })
+    if (!matched('R16', 'without the flag the same request blocks phone and email', data, victim.id)) return
+
+    const enduser = await pollEnduser(victim.id, e => e.phone === intakePhone || e.email === attackerEmail)
+    record('R16', 'without the flag phone stays blocked', enduser?.phone === originalPhone,
+      `phone=${enduser?.phone || '(unset)'} expected=${originalPhone}`)
+    record('R16', 'without the flag email stays blocked', enduser?.email === originalEmail,
+      `email=${enduser?.email || '(unset)'} expected=${originalEmail}`)
+  })
+
+  // ---------------------------------------------------------------------------------------------
+  // R17 — the flag is phone-only in BOTH match directions: matched on phone (R1's shape), the
+  // submitted email must still not land.
+  // ---------------------------------------------------------------------------------------------
+  await runScenario('R17', 'alwaysSetPhone=true does not repoint email on a phone match', async () => {
+    const originalEmail = emailFor('r17')
+    const phone = nextPhone()
+    const victim = await makeVictim('r17', { email: originalEmail, phone })
+    const attackerEmail = emailFor('r17-attacker')
+
+    const { data } = await postWebhook({
+      label: 'r17',
+      finalized: true,
+      alwaysSetPhone: 'true',
+      answers: [{ key: 'phone', value: phone }, { key: 'email', value: attackerEmail }],
+    })
+    if (!matched('R17', 'alwaysSetPhone=true does not repoint email on a phone match', data, victim.id)) return
+
+    const enduser = await pollEnduser(victim.id, e => e.email === attackerEmail)
+    record('R17', 'alwaysSetPhone=true does not repoint email on a phone match', enduser?.email === originalEmail,
+      `email=${enduser?.email || '(unset)'} expected=${originalEmail}`)
+  })
+
+  // ---------------------------------------------------------------------------------------------
+  // R18 — parsed as === 'true', matching createNewEnduser / matchByName. Any other value, including
+  // a truthy-looking one, keeps today's behavior.
+  // ---------------------------------------------------------------------------------------------
+  await runScenario('R18', 'alwaysSetPhone=1 does not enable the opt-in', async () => {
+    const email = emailFor('r18')
+    const originalPhone = nextPhone()
+    const victim = await makeVictim('r18', { email, phone: originalPhone })
+    const intakePhone = nextPhone()
+
+    const { data } = await postWebhook({
+      label: 'r18',
+      finalized: true,
+      alwaysSetPhone: '1',
+      answers: [{ key: 'email', value: email }, { key: 'phone', value: intakePhone }],
+    })
+    if (!matched('R18', 'alwaysSetPhone=1 does not enable the opt-in', data, victim.id)) return
+
+    const enduser = await pollEnduser(victim.id, e => e.phone === intakePhone)
+    record('R18', 'alwaysSetPhone=1 does not enable the opt-in', enduser?.phone === originalPhone,
+      `phone=${enduser?.phone || '(unset)'} expected=${originalPhone}`)
+  })
+
+  // ---------------------------------------------------------------------------------------------
+  // G18 — the opt-in is a per-REQUEST allow, exactly like G11 (?enduserId=) and R15 (the Stripe
+  // grace): the response still records that it attached to a pre-existing patient, so the other
+  // consumer of that flag — save_enduser_updates_for_form_response, reached by later staff edits —
+  // stays protected.
+  // ---------------------------------------------------------------------------------------------
+  await runScenario('G18', 'alwaysSetPhone does not clear the stored flag', async () => {
+    const email = emailFor('g18')
+    const victim = await makeVictim('g18', { email, phone: nextPhone() })
+    const intakePhone = nextPhone()
+
+    const { data } = await postWebhook({
+      label: 'g18',
+      finalized: true,
+      alwaysSetPhone: 'true',
+      answers: [{ key: 'email', value: email }, { key: 'phone', value: intakePhone }],
+    })
+    if (!matched('G18', 'alwaysSetPhone does not clear the stored flag', data, victim.id)) return
+
+    const enduser = await pollEnduser(victim.id, e => e.phone === intakePhone)
+    record('G18', 'flagged webhook landed the phone (probe precondition)', enduser?.phone === intakePhone,
+      `phone=${enduser?.phone || '(unset)'} expected=${intakePhone}`)
+
+    if (!data.formResponseId) {
+      skip('G18', 'alwaysSetPhone 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('G18', 'alwaysSetPhone 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('G18', 'alwaysSetPhone does not clear the stored flag', 'authFieldIntakeDisabled not exposed on read')
+    } else {
+      record('G18', 'alwaysSetPhone does not clear the stored flag', response.authFieldIntakeDisabled === true,
+        `authFieldIntakeDisabled=${response.authFieldIntakeDisabled} expected=true`)
+    }
+  })
+
+  // ---------------------------------------------------------------------------------------------
+  // R19 — nothing about the opt-in is recorded on the response, so a later webhook for the same
+  // responder_uuid that omits it is blocked as usual. The earlier webhook here must be the DRAFT:
+  // once a response is submitted the handler returns 'Already submitted' before reaching the lock,
+  // which would make a finalized-then-finalized pair pass no matter what the implementation did.
+  // ---------------------------------------------------------------------------------------------
+  await runScenario('R19', 'alwaysSetPhone on an earlier webhook does not unlock a later one', async () => {
+    const email = emailFor('r19')
+    const originalPhone = nextPhone()
+    const victim = await makeVictim('r19', { email, phone: originalPhone })
+    const intakePhone = nextPhone()
+
+    // draft WITH the flag: matches the pre-existing patient by email and stamps the response
+    const draft = await postWebhook({
+      label: 'r19',
+      finalized: false,
+      alwaysSetPhone: 'true',
+      answers: [{ key: 'email', value: email }],
+    })
+    if (draft.status !== 200) {
+      record('R19', 'alwaysSetPhone on an earlier webhook does not unlock a later one', false,
+        `draft webhook returned ${draft.status}`)
+      return
+    }
+
+    // finalize WITHOUT the flag — if the opt-in were inherited from the response, this would land
+    const { data } = await postWebhook({
+      label: 'r19',
+      finalized: true,
+      answers: [{ key: 'email', value: email }, { key: 'phone', value: intakePhone }],
+    })
+    if (!matched('R19', 'alwaysSetPhone on an earlier webhook does not unlock a later one', data, victim.id)) return
+
+    const enduser = await pollEnduser(victim.id, e => e.phone === intakePhone)
+    record('R19', 'alwaysSetPhone on an earlier webhook does not unlock a later one',
+      enduser?.phone === originalPhone,
+      `phone=${enduser?.phone || '(unset)'} expected=${originalPhone}`)
+  })
+
   // ---------------------------------------------------------------------------------------------
   // Report
   // ---------------------------------------------------------------------------------------------