@tellescope/sdk 1.256.13 → 1.256.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tellescope/sdk",
-  "version": "1.256.13",
+  "version": "1.256.14",
   "description": "Code for interacting with the Tellescope API",
   "main": "./lib/cjs/sdk.js",
   "module": "./lib/esm/sdk.js",
@@ -32,14 +32,14 @@
   },
   "homepage": "https://github.com/tellescope-os/tellescope#readme",
   "dependencies": {
-    "@tellescope/constants": "1.256.13",
-    "@tellescope/schema": "1.256.13",
-    "@tellescope/testing": "1.256.13",
-    "@tellescope/types-client": "1.256.13",
-    "@tellescope/types-models": "1.256.13",
-    "@tellescope/types-utilities": "1.256.13",
-    "@tellescope/utilities": "1.256.13",
-    "@tellescope/validation": "1.256.13",
+    "@tellescope/constants": "1.256.14",
+    "@tellescope/schema": "1.256.14",
+    "@tellescope/testing": "1.256.14",
+    "@tellescope/types-client": "1.256.14",
+    "@tellescope/types-models": "1.256.14",
+    "@tellescope/types-utilities": "1.256.14",
+    "@tellescope/utilities": "1.256.14",
+    "@tellescope/validation": "1.256.14",
     "axios": "0.30.3",
     "dotenv": "14.3.2",
     "form-data": "4.0.4",
@@ -55,5 +55,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "457e037174ead2b05f585d810de05f724659430a"
+  "gitHead": "0b32ba0040e286c4a1013287f9e154e612db11af"
 }

package/src/tests/api_tests/organization_signup.test.ts

@@ -0,0 +1,240 @@
+require('source-map-support').install();
+
+import axios from "axios"
+
+import { Session } from "../../sdk"
+import { wait } from "@tellescope/testing"
+import {
+  assert_checks,
+  Check,
+  set_email_verification_code,
+  setup_isolated_tenant,
+  test_support_request,
+} from "../setup_isolated"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+
+const RAND = () => Math.random().toString(36).slice(2, 10)
+
+// legacy shared fixture — teardown must refuse it
+const SEEDED_TEST_BUSINESS_ID = '60398b1131a295e64f084ff6'
+
+/**
+ * Covers the self-service organization signup chain, which had ZERO test coverage:
+ * `users.register` -> `users.submit_email_verification` -> `organizations.create_and_join`.
+ *
+ * That gap is why F-0191 nearly shipped a schema `adminOnly` flag on create_and_join that would have
+ * 401'd every new organization — a freshly registered user has no `roles`, because create_and_join is
+ * itself what grants Admin. This test is the regression guard for that.
+ *
+ * It also covers the new test-support provisioning module, including the assertion that matters most:
+ * teardown refuses any organization it did not create.
+ *
+ * Uses a `dontsend...@tellescope.com` address so the verification email is dropped at
+ * forCommunications before it is ever enqueued (locally the worker consumes the same test queue the
+ * API writes to, so an unsuppressed registration really does send mail).
+ */
+export const organization_signup_checks = async (): Promise<Check[]> => {
+  const checks: Check[] = []
+  const record = (label: string, pass: boolean, detail: string) => checks.push({ label, pass, detail })
+
+  let bootstrapUserId = ''
+  let createdBusinessId = ''
+  let provisioned: Awaited<ReturnType<typeof setup_isolated_tenant>> | undefined
+
+  try {
+    /* ===== A: provisioning works with no seeded database ===== */
+
+    provisioned = await setup_isolated_tenant()
+    record(
+      'A1: provision-tenant returns a usable admin session',
+      !!provisioned.businessId && provisioned.sdk.userInfo?.businessId === provisioned.businessId,
+      `businessId=${provisioned.businessId} session businessId=${provisioned.sdk.userInfo?.businessId}`,
+    )
+
+    // proves the frozen utf8 api-key hash was reproduced correctly, and that the key's creator
+    // resolves — a key whose creator is missing fails authentication outright
+    let keyDetail = ''
+    let keyPass = false
+    try {
+      const keySession = new Session({ host, apiKey: provisioned.apiKeys[0] })
+      keyDetail = await keySession.test_authenticated()
+      keyPass = keyDetail === 'Authenticated!'
+    } catch (e: any) {
+      keyDetail = `rejected: ${e?.message || e?.toString()}`
+    }
+    record('A2: a provisioned API key authenticates', keyPass, `test_authenticated -> ${keyDetail}`)
+
+    // the tenant is genuinely usable, not just addressable
+    const enduser = await provisioned.sdk.api.endusers.createOne({ fname: 'Provisioned', lname: 'Patient' })
+    record('A3: the provisioned tenant accepts writes', !!enduser.id, `enduserId=${enduser.id}`)
+
+    /* ===== B: teardown refuses anything it did not create — the safety assertion ===== */
+
+    const refusal = await test_support_request('/teardown-tenant', { businessId: SEEDED_TEST_BUSINESS_ID })
+    record(
+      'B1: teardown REFUSES an organization without the provenance marker',
+      refusal.status === 403,
+      `status=${refusal.status} ${JSON.stringify(refusal.body)} (expected 403)`,
+    )
+
+    /* ===== C: the signup chain ===== */
+
+    const email = `dontsend-signup-${RAND()}@tellescope.com`
+    const password = `Signup-${RAND()}-A1!`
+
+    const registerResult = await axios.request({
+      method: 'post', url: `${host}/v1/users/register`,
+      data: { email, password, termsVersion: '1' },
+      validateStatus: () => true,
+    })
+    record(
+      'C1: register accepts a new org-less user',
+      registerResult.status === 204,
+      `status=${registerResult.status} ${JSON.stringify(registerResult.data ?? '')}`,
+    )
+    await wait(undefined, 1200) // register is IP-limited to ~1/sec
+
+    // login works before verification, which is how a test learns the new user's id
+    const preVerifyLogin = await axios.request({
+      method: 'post', url: `${host}/v1/users/login`,
+      data: { email, password },
+      validateStatus: () => true,
+    })
+    bootstrapUserId = preVerifyLogin.data?.user?.id ?? ''
+    record(
+      'C2: the unverified user can log in (and is org-less)',
+      preVerifyLogin.status === 200 && !!bootstrapUserId && !preVerifyLogin.data?.user?.businessId,
+      `status=${preVerifyLogin.status} id=${bootstrapUserId} businessId=${preVerifyLogin.data?.user?.businessId ?? '(none)'}`,
+    )
+
+    // an unverified session must be rejected by a gated endpoint
+    const unverifiedAttempt = await axios.request({
+      method: 'post', url: `${host}/v1/organizations/create-and-join`,
+      data: { name: 'Should Not Work', subdomain: `nope-${RAND()}` },
+      headers: { Authorization: `Bearer ${preVerifyLogin.data?.authToken}` },
+      validateStatus: () => true,
+    })
+    record(
+      'C3: create_and_join is rejected before email verification',
+      unverifiedAttempt.status === 400,
+      `status=${unverifiedAttempt.status} ${JSON.stringify(unverifiedAttempt.data ?? '')}`,
+    )
+
+    // set the pending code, then drive the REAL verification endpoint
+    const code = `verify-${RAND()}`
+    await set_email_verification_code(email, code)
+
+    const verified = await axios.request({
+      method: 'post', url: `${host}/v1/users/submit-email-verification`,
+      data: { email, code },
+      validateStatus: () => true,
+    })
+    record(
+      'C4: submit_email_verification accepts the code and mints a token',
+      verified.status === 200 && !!verified.data?.authToken,
+      `status=${verified.status} authToken=${!!verified.data?.authToken}`,
+    )
+
+    /* ===== D: create_and_join — what F-0191's flag would have broken ===== */
+
+    const subdomain = `signup-${RAND()}`
+    const joined = await axios.request({
+      method: 'post', url: `${host}/v1/organizations/create-and-join`,
+      data: { name: `Signup Test ${RAND()}`, subdomain },
+      headers: { Authorization: `Bearer ${verified.data?.authToken}` },
+      validateStatus: () => true,
+    })
+    createdBusinessId = joined.data?.organization?.id ?? ''
+    record(
+      'D1: a freshly verified, org-less user can create and join an organization',
+      joined.status === 200 && !!createdBusinessId,
+      `status=${joined.status} organizationId=${createdBusinessId} ${joined.status !== 200 ? JSON.stringify(joined.data) : ''}`,
+    )
+    record(
+      'D2: the handler grants Admin and sets businessId (the roles bootstrap)',
+      joined.data?.user?.roles?.includes('Admin') && joined.data?.user?.businessId === createdBusinessId,
+      `roles=${JSON.stringify(joined.data?.user?.roles)} businessId=${joined.data?.user?.businessId}`,
+    )
+    record(
+      'D3: a fresh token is returned',
+      !!joined.data?.authToken && joined.data.authToken !== verified.data?.authToken,
+      `token returned=${!!joined.data?.authToken}, rotated=${joined.data?.authToken !== verified.data?.authToken}`,
+    )
+
+    const second = await axios.request({
+      method: 'post', url: `${host}/v1/organizations/create-and-join`,
+      data: { name: 'Second Org', subdomain: `signup-${RAND()}` },
+      headers: { Authorization: `Bearer ${joined.data?.authToken}` },
+      validateStatus: () => true,
+    })
+    record(
+      'D4: a user already in an organization cannot create another',
+      second.status === 400,
+      `status=${second.status} ${JSON.stringify(second.data ?? '')}`,
+    )
+
+    /* ===== E: teardown actually removes the tenant ===== */
+
+    // a second, disposable tenant so the assertions above keep their fixture
+    const disposable = await setup_isolated_tenant({ users: [{ isAdmin: true }], apiKeys: 1 })
+    const disposableKey = disposable.apiKeys[0]
+    await disposable.sdk.api.endusers.createOne({ fname: 'Disposable', lname: 'Patient' })
+    await disposable.teardown()
+
+    const secondTeardown = await test_support_request('/teardown-tenant', { businessId: disposable.businessId })
+    record(
+      'E1: teardown removes the organization record itself',
+      secondTeardown.status === 404,
+      `re-teardown status=${secondTeardown.status} ${JSON.stringify(secondTeardown.body)} (expected 404 — org gone)`,
+    )
+
+    let revokedDetail = ''
+    let revokedPass = false
+    try {
+      revokedDetail = await (new Session({ host, apiKey: disposableKey })).test_authenticated()
+    } catch (e: any) {
+      revokedPass = true
+      revokedDetail = `rejected: ${e?.message || e?.toString()}`
+    }
+    record(
+      'E2: the torn-down tenant\'s API key no longer authenticates',
+      revokedPass,
+      revokedDetail,
+    )
+
+  } finally {
+    if (provisioned) { try { await provisioned.teardown() } catch (e) { console.error('teardown failed', e) } }
+    // The signup-created org is NOT test-seeded, so teardown-tenant correctly refuses it; the org row
+    // is documented residue. The bootstrap user IS removable via test-support (the
+    // /tellescope-admin/delete-user route needs a staff session an isolated test deliberately lacks —
+    // posting to it without an Authorization header silently 401'd, so this used to leak every run).
+    if (bootstrapUserId) {
+      try { await test_support_request('/delete-user', { userId: bootstrapUserId }) } catch {}
+    }
+    if (createdBusinessId) {
+      console.log(`  note: organization ${createdBusinessId} was created by the signup flow and is left behind (nothing can delete an org record)`)
+    }
+  }
+
+  return checks
+}
+
+/** Asserting wrapper, for standalone runs and for sequential use in the suite. */
+export const organization_signup_tests = async () => {
+  assert_checks('Organization signup', await organization_signup_checks())
+}
+
+// Allow running this test file independently
+if (require.main === module) {
+  console.log(`🌐 Using API URL: ${host}`)
+  organization_signup_tests()
+    .then(() => {
+      console.log("✅ Organization signup test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ Organization signup test suite failed:", error)
+      process.exit(1)
+    })
+}

package/src/tests/api_tests/security/F-0179-booking-info-idor-token-mint.test.ts

@@ -0,0 +1,225 @@
+require('source-map-support').install();
+
+import { Session, EnduserSession } from "../../../sdk"
+import {
+  assert,
+  log_header,
+} from "@tellescope/testing"
+import { authenticate_enduser_via_token, setup_tests } from "../../setup"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+const businessId = '60398b1131a295e64f084ff6'
+
+const RAND = () => Math.random().toString(36).slice(2, 10)
+
+const VICTIM_STATE = 'CA'
+const ATTACKER_STATE_WRITE = 'NY'
+
+type Check = {
+  label: string,
+  pass: boolean,
+  detail: string,
+}
+
+/**
+ * Regression test for F-0179
+ * (security-audit/findings/F-0179-booking-info-idor-token-mint.md).
+ *
+ * `form_fields.booking_info` resolved its target patient as
+ * `DB.endusers.findById(enduserId || req.session.id)` with no ownership check for enduser
+ * sessions. The enduser DB branch builds the endusers collection with `enduserAccess: true`
+ * (database.ts), so a FOREIGN in-tenant id resolves — and the handler then writes
+ * `enduserFields.state` onto that record and calls `login_enduser` with
+ * `sessionScopes: ['appointment-booking']`, returning a live 24h token for the victim inside
+ * `bookingURL`. booking_info is enduser-callable AND granted to the 'public-form' scope, so a
+ * portal patient or an anonymous form-filler could mint a working session as any co-tenant patient.
+ *
+ * The fix mirrors `prepare_form_response` (api.ts): reject when an enduser session supplies an
+ * `enduserId` other than its own, before the booking-page lookup and before the `state` write.
+ *
+ * RED (pre-fix): A1 and A2 fail — the exploit returns 200 with a bookingURL whose token decodes to
+ * the VICTIM's id, and the victim's `state` is overwritten. B/C (positive controls) pass pre-fix.
+ * GREEN (post-fix): all six checks pass.
+ *
+ * Checks are collected and printed before any assert runs: the testing harness has
+ * EXIT_ON_FIRST_ERROR, so asserting inline would kill the process before the evidence table and
+ * before `finally` cleanup.
+ */
+export const booking_info_idor_tests = async ({ sdk } : { sdk: Session, sdkNonAdmin: Session }) => {
+  log_header("F-0179: booking_info must not mint an appointment-booking token for another enduser")
+
+  const checks: Check[] = []
+  const record = (label: string, pass: boolean, detail: string) => checks.push({ label, pass, detail })
+
+  // The minted JWT carries `id: enduser._id.toString()` (authentication.ts login_enduser). Decode
+  // it straight out of the returned URL — the whole point of the finding is WHOSE session it is.
+  const token_enduser_id = (bookingURL: string) => {
+    const token = /[?&]token=([^&]+)/.exec(bookingURL || '')?.[1]
+    const payload = token?.split('.')[1]
+    if (!payload) return ''
+    try {
+      return JSON.parse(Buffer.from(payload, 'base64').toString()).id as string
+    } catch {
+      return ''
+    }
+  }
+
+  let templateId = ''
+  let bookingPageId = ''
+  const enduserIds: string[] = []
+
+  try {
+    /* ================= fixtures ================= */
+
+    const template = await sdk.api.calendar_event_templates.createOne({
+      title: `F0179 template ${RAND()}`, durationInMinutes: 30,
+    } as any)
+    templateId = template.id
+
+    const bookingPage = await sdk.api.appointment_booking_pages.createOne({
+      title: `F0179 booking page ${RAND()}`,
+      calendarEventTemplateIds: [templateId],
+      locationIds: [],
+    } as any)
+    bookingPageId = bookingPage.id
+
+    const attacker = await sdk.api.endusers.createOne({
+      email: `f0179-attacker-${RAND()}@tellescope.example`, fname: 'F0179', lname: 'Attacker',
+    })
+    enduserIds.push(attacker.id)
+
+    const victim = await sdk.api.endusers.createOne({
+      email: `f0179-victim-${RAND()}@tellescope.example`, fname: 'F0179', lname: 'Victim',
+      state: VICTIM_STATE,
+    })
+    enduserIds.push(victim.id)
+
+    // Token mint, NOT enduserSDK.authenticate — /login-enduser is IP rate-limited and the suite
+    // shares one IP.
+    const attackerSDK = new EnduserSession({ host, businessId })
+    await authenticate_enduser_via_token(sdk, attackerSDK, { id: attacker.id })
+
+    /* ===== A: the exploit — enduser mints a booking session as another patient ===== */
+
+    let a1Detail = ''
+    let a1Pass = false
+    try {
+      const r = await attackerSDK.api.form_fields.booking_info({ bookingPageId, enduserId: victim.id })
+      const mintedFor = token_enduser_id(r.bookingURL)
+      a1Detail = (
+        `EXPLOITED: 200 with a bookingURL; token subject=${mintedFor} `
+        + `(victim=${victim.id}, attacker=${attacker.id})`
+        + (mintedFor === victim.id ? ' — a live appointment-booking session AS THE VICTIM' : '')
+      )
+    } catch (e: any) {
+      a1Pass = true
+      a1Detail = `rejected: ${e?.message || e?.toString()}`
+    }
+    record('A1: enduser cannot mint a booking token for another enduser', a1Pass, a1Detail)
+
+    // A2: the same call also writes enduserFields.state onto the target before minting.
+    let a2Attempt = ''
+    try {
+      await attackerSDK.api.form_fields.booking_info({
+        bookingPageId, enduserId: victim.id, enduserFields: { state: ATTACKER_STATE_WRITE },
+      })
+      a2Attempt = 'call returned 200'
+    } catch (e: any) {
+      a2Attempt = `call rejected: ${e?.message || e?.toString()}`
+    }
+    const victimAfter = await sdk.api.endusers.getOne(victim.id)
+    record(
+      'A2: enduser cannot write `state` onto another enduser via enduserFields',
+      victimAfter.state === VICTIM_STATE,
+      `${a2Attempt}; victim.state=${victimAfter.state} (expected ${VICTIM_STATE})`,
+    )
+
+    /* ===== B: positive controls — the patient's own booking flow still works ===== */
+
+    let b1Detail = ''
+    let b1Pass = false
+    try {
+      const r = await attackerSDK.api.form_fields.booking_info({ bookingPageId })
+      const mintedFor = token_enduser_id(r.bookingURL)
+      b1Pass = mintedFor === attacker.id
+      b1Detail = `token subject=${mintedFor} (self=${attacker.id})`
+    } catch (e: any) {
+      b1Detail = `unexpectedly rejected: ${e?.message || e?.toString()}`
+    }
+    record('B1: enduser can still load booking info with no enduserId', b1Pass, b1Detail)
+
+    let b2Detail = ''
+    let b2Pass = false
+    try {
+      const r = await attackerSDK.api.form_fields.booking_info({ bookingPageId, enduserId: attacker.id })
+      const mintedFor = token_enduser_id(r.bookingURL)
+      b2Pass = mintedFor === attacker.id
+      b2Detail = `token subject=${mintedFor} (self=${attacker.id})`
+    } catch (e: any) {
+      b2Detail = `unexpectedly rejected: ${e?.message || e?.toString()}`
+    }
+    record('B2: enduser can still load booking info for its OWN enduserId', b2Pass, b2Detail)
+
+    /* ===== C: positive controls — the staff branches are untouched ===== */
+
+    let c1Detail = ''
+    let c1Pass = false
+    try {
+      const r = await sdk.api.form_fields.booking_info({ bookingPageId, enduserId: victim.id })
+      const mintedFor = token_enduser_id(r.bookingURL)
+      c1Pass = mintedFor === victim.id
+      c1Detail = `token subject=${mintedFor} (target=${victim.id})`
+    } catch (e: any) {
+      c1Detail = `unexpectedly rejected: ${e?.message || e?.toString()}`
+    }
+    record('C1: staff can still load booking info for a specific enduser', c1Pass, c1Detail)
+
+    let c2Detail = ''
+    let c2Pass = false
+    try {
+      const r = await sdk.api.form_fields.booking_info({ bookingPageId })
+      c2Pass = !!r.bookingURL && !!r.warningMessage
+      c2Detail = `warningMessage=${JSON.stringify(r.warningMessage)} bookingURL=${!!r.bookingURL}`
+    } catch (e: any) {
+      c2Detail = `unexpectedly rejected: ${e?.message || e?.toString()}`
+    }
+    record('C2: staff test-contact preview branch still works', c2Pass, c2Detail)
+
+    /* ===== report: print full table first, then assert (harness exits on first failure) ===== */
+    console.log('\n  F-0179 check summary:')
+    for (const c of checks) {
+      console.log(`    ${c.pass ? 'PASS' : 'FAIL'}  ${c.label}  —  ${c.detail}`)
+    }
+    console.log('')
+
+    for (const c of checks) {
+      assert(c.pass, `${c.label} — ${c.detail}`, c.label)
+    }
+  } finally {
+    for (const id of enduserIds) { try { await sdk.api.endusers.deleteOne(id) } catch {} }
+    if (bookingPageId) { try { await sdk.api.appointment_booking_pages.deleteOne(bookingPageId) } catch {} }
+    if (templateId) { try { await sdk.api.calendar_event_templates.deleteOne(templateId) } catch {} }
+  }
+}
+
+// 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 booking_info_idor_tests({ sdk, sdkNonAdmin })
+  }
+
+  runTests()
+    .then(() => {
+      console.log("✅ F-0179 booking_info IDOR test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ F-0179 booking_info IDOR test suite failed:", error)
+      process.exit(1)
+    })
+}

package/src/tests/api_tests/security/F-0185-startlinktoken-enduser-staff-escalation.test.ts

@@ -0,0 +1,162 @@
+require('source-map-support').install();
+
+import { Session, EnduserSession } from "../../../sdk"
+import { assert, log_header } from "@tellescope/testing"
+import { setup_tests, authenticate_enduser_via_token } from "../../setup"
+import { PROVIDER_PERMISSIONS } from "@tellescope/constants"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+
+/**
+ * Regression test for F-0185 — `calendar_events.startLinkToken` privilege escalation.
+ *
+ * startLinkToken is a DOCUMENTED feature ("Video Call Start Links"): a tenant's staff / API-key
+ * integration PATCHes a CalendarEvent to set a random token, then sends the host user the
+ * `/video/startlink?token=...` link, which `session_for_start_link` exchanges for a scope-limited
+ * User (staff) authToken for the first `type:'user'` attendee, MFA bypassed. Nothing in the codebase
+ * reads the token value back (the redeem matches server-side; the integration holds its own copy), so
+ * the field is write-only-by-design.
+ *
+ * TWO escalation vectors let a patient (or a low-privilege staff user) obtain the host's session:
+ *   WRITE — `enduserActions.update` + no `enduserUpdatesDisabled` let an enduser attendee PATCH
+ *           `startLinkToken` to a value they choose, then redeem it.
+ *   READ  — no `redactions` let an enduser attendee (or a non-admin staff user with calendar read)
+ *           read a LEGITIMATELY staff-set token and redeem it, with no write.
+ *
+ * Complete fix = TWO flags on schema.ts `startLinkToken`:
+ *   enduserUpdatesDisabled: true   (closes WRITE; preserves the staff/API-key write the feature needs)
+ *   redactions: ['all']            (closes READ for endusers AND non-admin users; safe — nothing reads
+ *                                   the value back). NOT `readonly` (would break the staff write — A2).
+ *
+ * Checks (collected, then asserted, so a RED run shows every failing vector):
+ *   A1  enduser attendee PATCH of startLinkToken is REJECTED                (WRITE gate)
+ *   A2  a staff-set token still redeems for the host's session             (feature preserved)
+ *   A3  an enduser-set token (if the write lands) does NOT redeem          (defence-in-depth)
+ *   A4  an enduser attendee does NOT receive startLinkToken on read        (READ gate, endusers)
+ *   A5  a non-admin staff user does NOT receive startLinkToken on read     (READ gate, users)
+ *
+ * No vendor, no Bedrock; the "host" is a throwaway user. Cleans up every created record.
+ */
+const RAND = () => Math.random().toString(36).slice(2, 10)
+
+export const startlinktoken_escalation_tests = async ({ sdk } : { sdk: Session, sdkNonAdmin: Session }) => {
+  log_header("F-0185: startLinkToken enduser-writable / readable → staff session escalation")
+
+  const businessId = sdk.userInfo.businessId
+  const userIds: string[] = []
+  const enduserIds: string[] = []
+  const eventIds: string[] = []
+  const roleIds: string[] = []
+
+  const checks: { label: string, pass: boolean, detail: string }[] = []
+  const record = (label: string, pass: boolean, detail: string) => checks.push({ label, pass, detail })
+
+  try {
+    // Throwaway host staff user — the account an attacker would escalate INTO.
+    const host_user = await sdk.api.users.createOne({
+      email: `f0185-host-${RAND()}@tellescope.example`, fname: 'F0185', lname: 'Host',
+      verifiedEmail: true, notificationEmailsDisabled: true,
+    } as any)
+    userIds.push(host_user.id)
+
+    // The attacking patient, an attendee of the host's appointment.
+    const patient = await sdk.api.endusers.createOne({
+      email: `f0185-patient-${RAND()}@tellescope.example`, fname: 'F0185', lname: 'Patient',
+    })
+    enduserIds.push(patient.id)
+
+    const event = await sdk.api.calendar_events.createOne({
+      title: 'F-0185 appointment', durationInMinutes: 30, startTimeInMS: Date.now() + 3600_000,
+      attendees: [{ type: 'user', id: host_user.id }, { type: 'enduser', id: patient.id }],
+    } as any)
+    eventIds.push(event.id)
+
+    const patientSDK = new EnduserSession({ host, businessId })
+    await authenticate_enduser_via_token(sdk, patientSDK, { id: patient.id })
+
+    // ---- A1: WRITE gate — enduser attendee cannot PATCH startLinkToken ----
+    const attackerToken = `f0185-attacker-${RAND()}${RAND()}`
+    let wrote = false, writeErr = ''
+    try {
+      await patientSDK.api.calendar_events.updateOne(event.id, { startLinkToken: attackerToken } as any)
+      wrote = true
+    } catch (err: any) { writeErr = err?.message ?? String(err) }
+    record('A1: enduser cannot write startLinkToken', !wrote,
+      wrote ? 'PATCH ACCEPTED — patient set a staff start-link token' : `rejected (${writeErr})`)
+
+    // ---- A3: defence-in-depth — an enduser-set token must not redeem ----
+    // Only lands when A1 failed (pre-fix). Read back as admin to see if the value stuck.
+    const adminView = await sdk.api.calendar_events.getOne(event.id)
+    if ((adminView as any).startLinkToken === attackerToken) {
+      let redeemed: any = null
+      try { redeemed = await new Session({ host }).api.calendar_events.session_for_start_link({ token: attackerToken }) } catch {}
+      record('A3: enduser-set token does not mint a staff session', !redeemed?.authToken,
+        redeemed?.authToken ? `minted a STAFF authToken for host ${host_user.id}` : 'not redeemable')
+    } else {
+      record('A3: enduser-set token does not mint a staff session', true, '(n/a — write blocked, value never landed)')
+    }
+
+    // ---- A2: feature pin — a STAFF-set token still redeems (write + redeem must both survive the fix) ----
+    const staffToken = `f0185-staff-${RAND()}${RAND()}`
+    let staffWriteErr = ''
+    try { await sdk.api.calendar_events.updateOne(event.id, { startLinkToken: staffToken } as any) }
+    catch (e: any) { staffWriteErr = e?.message ?? String(e) }
+    let legit: any = null
+    try { legit = await new Session({ host }).api.calendar_events.session_for_start_link({ token: staffToken }) }
+    catch (e: any) { legit = { error: e?.message ?? String(e) } }
+    record('A2: staff-set start link still works', !!legit?.authToken && legit.eventId === event.id,
+      `staffWrite=${staffWriteErr ? 'REJECTED(' + staffWriteErr + ')' : 'ok'} authToken=${!!legit?.authToken} eventId=${legit?.eventId} ${legit?.error ? '(' + legit.error + ')' : ''}`)
+
+    // ---- A4: READ gate (endusers) — patient attendee must not receive the token ----
+    let enduserRead: any = null
+    try { enduserRead = await patientSDK.api.calendar_events.getOne(event.id) } catch {}
+    record('A4: startLinkToken redacted from enduser reads',
+      !enduserRead || (enduserRead as any).startLinkToken === undefined,
+      `enduser read startLinkToken=${(enduserRead as any)?.startLinkToken ?? '(absent)'} — could redeem a staff-set token`)
+
+    // ---- A5: READ gate (non-admin users) — low-priv staff must not receive the token ----
+    const rbap = await sdk.api.role_based_access_permissions.createOne({
+      role: `F0185NonAdmin-${RAND()}`,
+      // Non-admin (non-Admin-role) staff with tenant-wide calendar READ — enough to load the event,
+      // so the assertion isolates redaction (not access). Spread a valid full permissions shape.
+      permissions: { ...PROVIDER_PERMISSIONS, calendar_events: { ...(PROVIDER_PERMISSIONS as any).calendar_events, read: 'All', readMany: 'All' } },
+    } as any).catch((e: any) => { console.warn('A5 role create failed:', e?.message ?? e); return null })
+    if (rbap) {
+      roleIds.push(rbap.id)
+      const nonAdmin = await sdk.api.users.createOne({
+        email: `f0185-nonadmin-${RAND()}@tellescope.example`, fname: 'F0185', lname: 'NonAdmin',
+        verifiedEmail: true, notificationEmailsDisabled: true, roles: [rbap.role],
+      } as any)
+      userIds.push(nonAdmin.id)
+      const { authToken } = await sdk.api.users.generate_auth_token({ id: nonAdmin.id })
+      const nonAdminSDK = new Session({ host, authToken })
+      let staffRead: any = null
+      try { staffRead = await nonAdminSDK.api.calendar_events.getOne(event.id) } catch {}
+      record('A5: startLinkToken redacted from non-admin user reads',
+        !staffRead || (staffRead as any).startLinkToken === undefined,
+        `non-admin user read startLinkToken=${(staffRead as any)?.startLinkToken ?? '(absent)'} — staff→host escalation via read`)
+    } else {
+      record('A5: startLinkToken redacted from non-admin user reads', true, '(n/a — could not create a non-admin role in this env)')
+    }
+
+    // Report the full table before asserting (the harness exits on the first failed assert).
+    console.log('\n  F-0185 check summary:')
+    for (const c of checks) console.log(`    ${c.pass ? 'PASS' : 'FAIL'}  ${c.label}  —  ${c.detail}`)
+    console.log('')
+    for (const c of checks) assert(c.pass, `${c.label} — ${c.detail}`, c.label)
+  } finally {
+    for (const id of eventIds) { try { await sdk.api.calendar_events.deleteOne(id) } catch {} }
+    for (const id of enduserIds) { try { await sdk.api.endusers.deleteOne(id) } catch {} }
+    for (const id of userIds) { try { await sdk.api.users.deleteOne(id) } catch {} }
+    for (const id of roleIds) { try { await sdk.api.role_based_access_permissions.deleteOne(id) } catch {} }
+  }
+}
+
+if (require.main === module) {
+  const sdk = new Session({ host })
+  const sdkNonAdmin = new Session({ host })
+  setup_tests(sdk, sdkNonAdmin)
+    .then(() => startlinktoken_escalation_tests({ sdk, sdkNonAdmin }))
+    .then(() => { console.log("✅ F-0185 startLinkToken escalation test suite completed successfully"); process.exit(0) })
+    .catch((error) => { console.error("❌ F-0185 startLinkToken escalation test suite failed:", error); process.exit(1) })
+}