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

package/src/tests/api_tests/security/schema-adminonly-enforcement.test.ts

@@ -3,12 +3,13 @@ require('source-map-support').install();
 import axios from "axios"
 
 import { Session } from "../../../sdk"
-import {
-  assert,
-  log_header,
-} from "@tellescope/testing"
 import { PROVIDER_PERMISSIONS } from "@tellescope/constants"
-import { setup_tests } from "../../setup"
+import {
+  assert_checks,
+  Check,
+  IsolatedSuite,
+  setup_isolated_tenant,
+} from "../../setup_isolated"
 
 const host = process.env.API_URL || 'http://localhost:8080' as const
 
@@ -17,12 +18,6 @@ const RAND = () => Math.random().toString(36).slice(2, 10)
 const ALL = 'All' as const
 const FULL_ACCESS = { create: ALL, read: ALL, update: ALL, delete: ALL }
 
-type Check = {
-  label: string,
-  pass: boolean,
-  detail: string,
-}
-
 /**
  * Regression test: `adminOnly` custom actions must be enforced at runtime, not merely declared.
  *
@@ -61,10 +56,13 @@ type Check = {
  *
  * RED (pre-fix): the six group-B rows fail — each reaches its handler and returns a non-401.
  * GREEN (post-fix): all six return 401 "Admin access only"; the group-A controls are unchanged.
+ *
+ * Runs on its own provisioned tenant, which makes the two environment-dependent probes deterministic
+ * rather than a function of whoever's local database the shared org came from: a fresh tenant has no
+ * Athena integration (so sync-athena is probed) and no twilioSID (so link-twilio, which can create a
+ * REAL Twilio subaccount, stays permanently on its skipped-for-safety path).
  */
-export const schema_adminonly_enforcement_tests = async ({ sdk } : { sdk: Session, sdkNonAdmin: Session }) => {
-  log_header("schema-declared adminOnly must be enforced on custom actions")
-
+export const schema_adminonly_enforcement_checks = async (): Promise<Check[]> => {
   const checks: Check[] = []
   const record = (label: string, pass: boolean, detail: string) => checks.push({ label, pass, detail })
 
@@ -89,11 +87,19 @@ export const schema_adminonly_enforcement_tests = async ({ sdk } : { sdk: Sessio
     `${r.status} ${(JSON.stringify(r.body) ?? '').slice(0, 120)}`
   )
 
+  let tenant: Awaited<ReturnType<typeof setup_isolated_tenant>> | undefined
   let roleId = ''
   let attackerId = ''
   let enduserId = ''
 
   try {
+    tenant = await setup_isolated_tenant({
+      name: `Schema adminOnly enforcement ${RAND()}`,
+      users: [{ isAdmin: true }],
+      apiKeys: 0,
+    })
+    const { sdk } = tenant
+
     /* ================= fixtures ================= */
 
     const role = `f0191-staff-${RAND()}`
@@ -246,36 +252,35 @@ export const schema_adminonly_enforcement_tests = async ({ sdk } : { sdk: Sessio
         `${summarize(r)} (expected a handler response, not 401 Admin access only)`,
       )
     }
-
-    /* ===== report: print full table first, then assert (harness exits on first failure) ===== */
-    console.log('\n  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 {
-    if (enduserId) { try { await sdk.api.endusers.deleteOne(enduserId) } catch {} }
-    if (attackerId) { try { await sdk.api.users.deleteOne(attackerId) } catch {} }
-    if (roleId) { try { await sdk.api.role_based_access_permissions.deleteOne(roleId) } catch {} }
+    if (tenant) {
+      const { sdk } = tenant
+      if (enduserId) { try { await sdk.api.endusers.deleteOne(enduserId) } catch {} }
+      if (attackerId) { try { await sdk.api.users.deleteOne(attackerId) } catch {} }
+      if (roleId) { try { await sdk.api.role_based_access_permissions.deleteOne(roleId) } 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 schema_adminonly_enforcement_tests = async () => {
+  assert_checks('Schema adminOnly enforcement', await schema_adminonly_enforcement_checks())
+}
+
+/** Enrolls this suite in the auto-discovered parallel pool — see run_discovered_isolated_suites. */
+export const ISOLATED_SUITE: IsolatedSuite = {
+  name: 'Schema adminOnly enforcement',
+  run: schema_adminonly_enforcement_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 schema_adminonly_enforcement_tests({ sdk, sdkNonAdmin })
-  }
-
-  runTests()
+  schema_adminonly_enforcement_tests()
     .then(() => {
       console.log("✅ schema adminOnly enforcement test suite completed successfully")
       process.exit(0)

package/src/tests/api_tests/security/self-admin-role-assignment.test.ts

@@ -1,15 +1,18 @@
 require('source-map-support').install();
 
 import { Session } from "../../../sdk"
+import { wait } from "@tellescope/testing"
 import {
-  assert,
-  log_header,
-  wait,
-} 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 RAND = () => Math.random().toString(36).slice(2, 10)
+
 /**
  * Self-role privilege-escalation guard (relates to a prior internal review, which was
  * investigated and closed as a FALSE POSITIVE — see that file for the full code trace).
@@ -29,43 +32,68 @@ const host = process.env.API_URL || 'http://localhost:8080' as const
  * The self-promotion is blocked.
  *
  * This test locks that boundary in place so a future refactor of the role constraints can't
- * silently reintroduce the escalation. A dedicated throwaway non-admin user is used as the
- * "attacker" (we never mutate the shared sdkNonAdmin's roles):
+ * silently reintroduce the escalation. It runs on its own provisioned tenant, whose single user is
+ * the admin; the "attacker" is a throwaway user this suite creates:
  *   1. Admin creates a throwaway user and assigns it a non-admin role (`['Provider']`).
  *   2. Authenticate AS that user via a freshly-minted auth token.
  *   3. As the attacker, attempt four self-role mutations — ['Admin'], ['Provider','Admin'],
- *      an arbitrary role, and [] — and assert EACH is blocked.       <-- the security assertions
+ *      an arbitrary role, and [] — and check EACH is blocked.        <-- the security checks
  *   4. Confirm (as admin) the attacker's roles are still ['Provider'] — nothing slipped through.
  *   5. Positive control: admin CAN update the throwaway user's roles. <-- guards against an
  *      over-restrictive regression that would block legitimate admin role management.
  *
- * Expected on current (correct) code: all assertions pass. A regression that made the self-update
- * path role-writable by non-admins would flip the step-3/step-4 assertions to red.
+ * The tenant provisions `roles: [{ role: 'Provider' }]` so the attacker's permissions come from a
+ * real role record (users.update: 'Default'), rather than from get_access_permissions_by_roles'
+ * unknown-role fallback — the escalation checks must only be able to pass via the role constraint.
+ * That `roles:` spec replaces the provisioner's default `[Non-Admin, Test]` entirely, which is safe
+ * here only because this tenant provisions no non-admin user.
+ *
+ * Expected on current (correct) code: all checks pass. A regression that made the self-update
+ * path role-writable by non-admins would flip the step-3/step-4 checks to red.
  */
-export const self_admin_role_assignment_tests = async ({ sdk } : { sdk: Session, sdkNonAdmin: Session }) => {
-  log_header("self-admin role assignment privilege-escalation regression")
+export const self_admin_role_assignment_checks = async (): Promise<Check[]> => {
+  const checks: Check[] = []
+  const record = (label: string, pass: boolean, detail: string) => checks.push({ label, pass, detail })
 
   const stamp = Date.now()
   const NON_ADMIN_ROLE = 'Provider'
 
-  // Assert that a self-role-update attempt is rejected by the relationship constraints.
-  const expect_blocked = async (fn: () => Promise<any>, description: string) => {
-    try {
-      await fn()
-      assert(false, `${description} - SELF-ROLE ESCALATION SUCCEEDED (expected it to be blocked)`)
-    } catch (e: any) {
-      // CRUD relationship-constraint failures surface as 400 { message, info } via SDK parseError.
-      assert(
-        e?.code === 400 || e?.statusCode === 400 || typeof e?.message === 'string',
-        `${description} - expected a block error, got: ${JSON.stringify(e)}`,
-        description,
-      )
-    }
-  }
-
+  let tenant: Awaited<ReturnType<typeof setup_isolated_tenant>> | undefined
   let attackerId: string | undefined
 
   try {
+    tenant = await setup_isolated_tenant({
+      name: `SelfAdminRoleAssignment ${RAND()}`,
+      users: [{ isAdmin: true }],
+      roles: [{ role: NON_ADMIN_ROLE }],
+      apiKeys: 0,
+    })
+    const { sdk } = tenant
+
+    // Record whether a self-role-update attempt is rejected by the relationship constraints.
+    const expect_blocked = async (fn: () => Promise<any>, description: string) => {
+      try {
+        const unexpected = await fn()
+        record(
+          description,
+          false,
+          `SELF-ROLE ESCALATION SUCCEEDED (expected it to be blocked); result=`
+          + `${unexpected === undefined ? '(none)' : JSON.stringify(unexpected)}`,
+        )
+      } catch (e: any) {
+        // CRUD relationship-constraint failures surface as 400 { message, info } via SDK parseError.
+        record(
+          description,
+          e?.code === 400 || e?.statusCode === 400 || typeof e?.message === 'string',
+          `blocked with ${
+            typeof e?.message === 'string' && e.message !== ''
+              ? e.message
+              : (e === undefined || e === null ? String(e) : JSON.stringify(e))
+          }`,
+        )
+      }
+    }
+
     // 1. Admin creates a throwaway non-admin user (notification emails off, timestamped email).
     //    verifiedEmail is set at creation (admin-only, updatesDisabled after) so the attacker can
     //    drive an authenticated session — otherwise actions are blocked on email-verification, not
@@ -81,10 +109,10 @@ export const self_admin_role_assignment_tests = async ({ sdk } : { sdk: Session,
 
     // Setup sanity: the attacker holds exactly the non-admin role and is NOT an admin.
     const attackerBefore = await sdk.api.users.getOne(attackerId)
-    assert(
-      JSON.stringify(attackerBefore.roles) === JSON.stringify([NON_ADMIN_ROLE]),
-      `Setup failed: expected attacker to hold [${NON_ADMIN_ROLE}], got ${JSON.stringify(attackerBefore.roles)}`,
+    record(
       'setup: attacker holds a non-admin role',
+      JSON.stringify(attackerBefore.roles) === JSON.stringify([NON_ADMIN_ROLE]),
+      `roles=${JSON.stringify(attackerBefore.roles ?? null)} (want [${NON_ADMIN_ROLE}])`,
     )
 
     // 2. Authenticate AS the attacker (no password needed — admin mints an auth token).
@@ -93,13 +121,14 @@ export const self_admin_role_assignment_tests = async ({ sdk } : { sdk: Session,
       authToken: (await sdk.api.users.generate_auth_token({ id: attackerId })).authToken,
     })
     await sdkAttacker.refresh_session() // populate userInfo from the freshly-minted token
-    assert(
-      sdkAttacker.userInfo.id === attackerId && !(sdkAttacker.userInfo.roles ?? []).includes('Admin'),
-      `Setup failed: attacker session is not the expected non-admin user`,
+    record(
       'setup: authenticated as the non-admin attacker',
+      sdkAttacker.userInfo.id === attackerId && !(sdkAttacker.userInfo.roles ?? []).includes('Admin'),
+      `session id=${JSON.stringify(sdkAttacker.userInfo.id ?? null)} roles=`
+      + `${JSON.stringify(sdkAttacker.userInfo.roles ?? null)} (want id=${attackerId}, no Admin)`,
     )
 
-    // 3. SECURITY ASSERTIONS — every self-role mutation by the non-admin must be blocked.
+    // 3. SECURITY CHECKS — every self-role mutation by the non-admin must be blocked.
     await expect_blocked(
       () => sdkAttacker.api.users.updateOne(attackerId!, { roles: ['Admin'] }, { replaceObjectFields: true }),
       'non-admin self-update to [Admin] is blocked',
@@ -117,43 +146,52 @@ export const self_admin_role_assignment_tests = async ({ sdk } : { sdk: Session,
       'non-admin self-update to [] (would grant defaults) is blocked',
     )
 
-    // 4. STATE ASSERTION — nothing slipped through; roles are still the original non-admin role.
+    // 4. STATE CHECK — nothing slipped through; roles are still the original non-admin role.
     const attackerAfter = await sdk.api.users.getOne(attackerId)
-    assert(
-      JSON.stringify(attackerAfter.roles) === JSON.stringify([NON_ADMIN_ROLE]),
-      `ESCALATION LEAK: attacker roles changed to ${JSON.stringify(attackerAfter.roles)} `
-        + `after self-update attempts. Expected [${NON_ADMIN_ROLE}].`,
+    record(
       'attacker roles unchanged after all self-escalation attempts',
+      JSON.stringify(attackerAfter.roles) === JSON.stringify([NON_ADMIN_ROLE]),
+      `roles=${JSON.stringify(attackerAfter.roles ?? null)} after self-update attempts`
+      + ` (want [${NON_ADMIN_ROLE}]; anything else is an ESCALATION LEAK)`,
     )
 
     // 5. POSITIVE CONTROL — an Admin CAN update the user's roles (mechanism is not over-restricted).
     await sdk.api.users.updateOne(attackerId, { roles: [NON_ADMIN_ROLE] }, { replaceObjectFields: true })
     const afterAdminUpdate = await sdk.api.users.getOne(attackerId)
-    assert(
-      JSON.stringify(afterAdminUpdate.roles) === JSON.stringify([NON_ADMIN_ROLE]),
-      `Admin role update failed: roles are ${JSON.stringify(afterAdminUpdate.roles)}, expected [${NON_ADMIN_ROLE}]`,
+    record(
       'admin can manage user roles (positive control)',
+      JSON.stringify(afterAdminUpdate.roles) === JSON.stringify([NON_ADMIN_ROLE]),
+      `roles=${JSON.stringify(afterAdminUpdate.roles ?? null)} (want [${NON_ADMIN_ROLE}])`,
     )
   } finally {
-    // Cleanup: delete the throwaway attacker. Never touches pre-existing users.
-    if (attackerId) {
-      try { await sdk.api.users.deleteOne(attackerId) } catch {}
+    if (tenant) {
+      // Cleanup: delete the throwaway attacker. Never touches pre-existing users.
+      if (attackerId) {
+        try { await tenant.sdk.api.users.deleteOne(attackerId) } 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 self_admin_role_assignment_tests = async () => {
+  assert_checks('Self-admin role assignment', await self_admin_role_assignment_checks())
+}
+
+/** Enrolls this suite in the auto-discovered parallel pool — see run_discovered_isolated_suites. */
+export const ISOLATED_SUITE: IsolatedSuite = {
+  name: 'Self-admin role assignment',
+  run: self_admin_role_assignment_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 self_admin_role_assignment_tests({ sdk, sdkNonAdmin })
-  }
-
-  runTests()
+  self_admin_role_assignment_tests()
     .then(() => {
       console.log("✅ self-admin role assignment test suite completed successfully")
       process.exit(0)

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

@@ -1,9 +1,13 @@
 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"
+import {
+  assert_checks,
+  Check,
+  IsolatedSuite,
+  setup_isolated_tenant,
+} from "../../setup_isolated"
 
 const host = process.env.API_URL || 'http://localhost:8080' as const
 
@@ -28,30 +32,38 @@ const host = process.env.API_URL || 'http://localhost:8080' as const
  *   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):
+ * Checks (collected, never asserted here, 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.
+ * No vendor, no Bedrock; the "host" is a throwaway user. Runs on its own provisioned tenant and
+ * cleans up every created record before tearing it down. The patient session is minted inline from
+ * endusers.generate_auth_token — this file imports nothing from the shared setup.ts fixture.
  */
 const RAND = () => Math.random().toString(36).slice(2, 10)
 
-export const startlinktoken_escalation_tests = async ({ sdk } : { sdk: Session, sdkNonAdmin: Session }) => {
-  log_header("startLinkToken enduser-writable / readable → staff session escalation")
+export const startlinktoken_escalation_checks = async (): Promise<Check[]> => {
+  const checks: Check[] = []
+  const record = (label: string, pass: boolean, detail: string) => checks.push({ label, pass, detail })
 
-  const businessId = sdk.userInfo.businessId
+  let tenant: Awaited<ReturnType<typeof setup_isolated_tenant>> | undefined
   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 {
+    tenant = await setup_isolated_tenant({
+      name: `startLinkToken escalation ${RAND()}`,
+      users: [{ isAdmin: true }],
+      apiKeys: 0,
+    })
+    const { sdk } = tenant
+    const businessId = tenant.businessId
+
     // 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',
@@ -71,8 +83,12 @@ export const startlinktoken_escalation_tests = async ({ sdk } : { sdk: Session,
     } as any)
     eventIds.push(event.id)
 
-    const patientSDK = new EnduserSession({ host, businessId })
-    await authenticate_enduser_via_token(sdk, patientSDK, { id: patient.id })
+    const { authToken: patientAuthToken, enduser: patientInfo } = (
+      await sdk.api.endusers.generate_auth_token({ id: patient.id })
+    )
+    const patientSDK = new EnduserSession({
+      host, authToken: patientAuthToken, enduser: patientInfo, businessId,
+    })
 
     // ---- A1: WRITE gate — enduser attendee cannot PATCH startLinkToken ----
     const attackerToken = `f0185-attacker-${RAND()}${RAND()}`
@@ -93,6 +109,8 @@ export const startlinktoken_escalation_tests = async ({ sdk } : { sdk: Session,
       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 {
+      // A genuine conditional vector, not a skip: the value never landed because A1 blocked the
+      // write, which is exactly the fixed behaviour this check is defence-in-depth for.
       record('A3: enduser-set token does not mint a staff session', true, '(n/a — write blocked, value never landed)')
     }
 
@@ -108,19 +126,24 @@ export const startlinktoken_escalation_tests = async ({ sdk } : { sdk: Session,
       `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 {}
+    let enduserRead: any = null, enduserReadErr = ''
+    try { enduserRead = await patientSDK.api.calendar_events.getOne(event.id) } catch (e: any) { enduserReadErr = e?.message ?? String(e) }
     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`)
+      // The detail distinguishes "read succeeded, token absent" from "read failed", which both
+      // satisfy the predicate: a blocked read proves nothing about redaction.
+      `enduser read startLinkToken=${(enduserRead as any)?.startLinkToken ?? '(absent)'}`
+      + `${enduserRead ? '' : ` — READ FAILED (${enduserReadErr !== '' ? enduserReadErr : 'no error message'}), so the READ gate was not probed`}`
+      + ` — could redeem a staff-set token`)
 
     // ---- A5: READ gate (non-admin users) — low-priv staff must not receive the token ----
+    let roleCreateErr = ''
     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 })
+    } as any).catch((e: any) => { roleCreateErr = e?.message ?? String(e); return null })
     if (rbap) {
       roleIds.push(rbap.id)
       const nonAdmin = await sdk.api.users.createOne({
@@ -130,33 +153,52 @@ export const startlinktoken_escalation_tests = async ({ sdk } : { sdk: Session,
       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 {}
+      let staffRead: any = null, staffReadErr = ''
+      try { staffRead = await nonAdminSDK.api.calendar_events.getOne(event.id) } catch (e: any) { staffReadErr = e?.message ?? String(e) }
       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`)
+        // Same as A4: a read this low-privilege user could not perform at all also satisfies the
+        // predicate, so the detail says which of the two happened.
+        `non-admin user read startLinkToken=${(staffRead as any)?.startLinkToken ?? '(absent)'}`
+        + `${staffRead ? '' : ` — READ FAILED (${staffReadErr !== '' ? staffReadErr : 'no error message'}), so the READ gate was not probed`}`
+        + ` — 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)')
+      // Previously a PASSING "(n/a)" check, which reported green without probing the READ gate at
+      // all. On a tenant this suite provisioned, the admin can always create a role — a failure here
+      // is a real defect, so it fails and carries the error.
+      record('A5: startLinkToken redacted from non-admin user reads', false,
+        `could not create a non-admin role on this freshly provisioned tenant, so the staff READ gate `
+        + `was never probed: ${roleCreateErr !== '' ? roleCreateErr : '(no error message)'}`)
     }
-
-    // Report the full table before asserting (the harness exits on the first failed assert).
-    console.log('\n  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 (tenant) {
+      const { sdk } = tenant
+      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 {} }
+      // 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 startlinktoken_escalation_tests = async () => {
+  assert_checks('startLinkToken escalation', await startlinktoken_escalation_checks())
+}
+
+/** Enrolls this suite in the auto-discovered parallel pool — see run_discovered_isolated_suites. */
+export const ISOLATED_SUITE: IsolatedSuite = {
+  name: 'startLinkToken escalation',
+  run: startlinktoken_escalation_checks,
 }
 
 if (require.main === module) {
-  const sdk = new Session({ host })
-  const sdkNonAdmin = new Session({ host })
-  setup_tests(sdk, sdkNonAdmin)
-    .then(() => startlinktoken_escalation_tests({ sdk, sdkNonAdmin }))
+  console.log(`🌐 Using API URL: ${host}`)
+  startlinktoken_escalation_tests()
     .then(() => { console.log("✅ startLinkToken escalation test suite completed successfully"); process.exit(0) })
     .catch((error) => { console.error("❌ startLinkToken escalation test suite failed:", error); process.exit(1) })
 }