@tellescope/sdk 1.250.2 → 1.252.0

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

@@ -0,0 +1,223 @@
+require('source-map-support').install();
+
+import { Session, EnduserSession } from "../../sdk"
+import { log_header, wait, async_test } from "@tellescope/testing"
+import { Enduser } from "@tellescope/types-client"
+import { setup_tests } from "../setup"
+
+const host = process.env.API_URL || "http://localhost:8080"
+
+const pollFor = async <T>(
+  fetchFn: () => Promise<T | undefined>,
+  evaluateFn: (result: T | undefined) => result is T,
+  description: string,
+  intervalMs = 500,
+  maxIterations = 30,
+): Promise<T> => {
+  let lastResult: T | undefined
+  for (let i = 0; i < maxIterations; i++) {
+    await wait(undefined, intervalMs)
+    lastResult = await fetchFn()
+    if (evaluateFn(lastResult)) return lastResult
+  }
+  throw new Error(`Polling timeout: ${description} - waited ${maxIterations * intervalMs}ms`)
+}
+
+export const push_forms_to_portal_group_completion_tests = async ({ sdk, sdkNonAdmin } : { sdk: Session, sdkNonAdmin: Session }) => {
+  log_header("Push Forms To Portal - Form Group Completed Trigger Tests")
+
+  const createdEnduserIds: string[] = []
+  const createdJourneyIds: string[] = []
+  const createdFormIds: string[] = []
+  const createdFormGroupIds: string[] = []
+  const createdTriggerIds: string[] = []
+
+  try {
+    // 1. Create two forms, each with a single text field
+    const formA = await sdk.api.forms.createOne({ title: 'Push To Portal Form A' })
+    createdFormIds.push(formA.id)
+    const fieldA = await sdk.api.form_fields.createOne({
+      formId: formA.id,
+      type: 'string',
+      title: 'FieldA',
+      previousFields: [{ type: 'root', info: {} }],
+    })
+
+    const formB = await sdk.api.forms.createOne({ title: 'Push To Portal Form B' })
+    createdFormIds.push(formB.id)
+    const fieldB = await sdk.api.form_fields.createOne({
+      formId: formB.id,
+      type: 'string',
+      title: 'FieldB',
+      previousFields: [{ type: 'root', info: {} }],
+    })
+
+    // 2. Create a form group containing both forms (shared across both submission flows)
+    const formGroup = await sdk.api.form_groups.createOne({
+      title: 'Push To Portal Test Group',
+      formIds: [formA.id, formB.id],
+    })
+    createdFormGroupIds.push(formGroup.id)
+
+    // Helper: run the full push-to-portal → submit → trigger flow with a configurable submitter.
+    // Each invocation creates its own trigger/journey/step/enduser and asserts its own tag.
+    // We test both the admin (user-session) submitter and the enduser (portal-session) submitter
+    // because they exercise different DB scopes in submit_form_response — and the regression QA caught
+    // was only triggered on the enduser-session path.
+    const runFlow = async ({ label, tag, submitAsEnduser } : { label: string, tag: string, submitAsEnduser: boolean }) => {
+      const trigger = await sdk.api.automation_triggers.createOne({
+        event: { type: 'Form Group Completed', info: { groupId: formGroup.id } },
+        action: { type: 'Add Tags', info: { tags: [tag] } },
+        status: 'Active',
+        title: `Form Group Completed - Push to Portal (${label})`,
+      })
+      createdTriggerIds.push(trigger.id)
+
+      const journey = await sdk.api.journeys.createOne({
+        title: `Push To Portal Trigger Journey (${label})`,
+      })
+      createdJourneyIds.push(journey.id)
+
+      const pushStep = await sdk.api.automation_steps.createOne({
+        journeyId: journey.id,
+        action: { type: 'pushFormsToPortal', info: { formGroupIds: [formGroup.id] } },
+        events: [{ type: 'onJourneyStart', info: {} }],
+      })
+
+      const enduser = await sdk.api.endusers.createOne({ fname: 'PushPortal', lname: label })
+      createdEnduserIds.push(enduser.id)
+
+      await sdk.api.endusers.add_to_journey({
+        enduserIds: [enduser.id],
+        journeyId: journey.id,
+      })
+
+      const pushedResponses = await pollFor(
+        async () => {
+          const responses = await sdk.api.form_responses.getSome({
+            filter: { enduserId: enduser.id },
+          })
+          const pushed = responses.filter(r => !!r.pushedToPortalAt)
+          return pushed.length >= 2 ? pushed : undefined
+        },
+        (result): result is any[] => Array.isArray(result) && result.length >= 2,
+        `pushed-to-portal form_responses to be created by worker (${label})`,
+        500,
+        40,
+      )
+
+      for (const fr of pushedResponses) {
+        if (!fr.pushedToPortalAt) {
+          throw new Error(`Expected pushedToPortalAt to be set on form_response ${fr.id} (${label})`)
+        }
+        if (fr.groupId !== pushStep.id) {
+          throw new Error(`Expected form_response.groupId (${fr.groupId}) to equal automation step id (${pushStep.id}) (${label})`)
+        }
+        if (fr.automationStepId !== pushStep.id) {
+          throw new Error(`Expected form_response.automationStepId (${fr.automationStepId}) to equal automation step id (${pushStep.id}) (${label})`)
+        }
+      }
+
+      await async_test(
+        `Worker writes groupId === automationStepId and pushedToPortalAt set (${label})`,
+        async () => true,
+        { onResult: r => r === true },
+      )
+
+      // Build the submitter session
+      let submitterApi: typeof sdk.api | EnduserSession['api']
+      if (submitAsEnduser) {
+        const { authToken } = await sdk.api.endusers.generate_auth_token({ id: enduser.id })
+        const enduserSDK = new EnduserSession({ host, authToken, businessId: sdk.userInfo.businessId })
+        submitterApi = enduserSDK.api
+      } else {
+        submitterApi = sdk.api
+      }
+
+      for (const fr of pushedResponses) {
+        const isFormA = fr.formId === formA.id
+        const targetFieldId = isFormA ? fieldA.id : fieldB.id
+        const targetFieldTitle = isFormA ? 'FieldA' : 'FieldB'
+        await submitterApi.form_responses.submit_form_response({
+          accessCode: fr.accessCode as string,
+          responses: [{
+            fieldId: targetFieldId,
+            fieldTitle: targetFieldTitle,
+            answer: { type: 'string', value: 'pushed-portal-answer' },
+          }],
+        })
+      }
+
+      await pollFor(
+        async () => {
+          const e = await sdk.api.endusers.getOne(enduser.id)
+          return e.tags?.includes(tag) ? e : undefined
+        },
+        (result): result is Enduser => !!result,
+        `Form Group Completed trigger to apply tag after push-to-portal submissions (${label})`,
+        500,
+        30,
+      )
+
+      await async_test(
+        `Form Group Completed trigger fires for push-to-portal completion (${label})`,
+        () => sdk.api.endusers.getOne(enduser.id),
+        { onResult: (e: Enduser) => !!e.tags?.includes(tag) },
+      )
+    }
+
+    // Admin submitter: simulates a staff user filling in the form on behalf of the patient
+    // (uses a user-scoped DB in submit_form_response).
+    await runFlow({
+      label: 'admin-submit',
+      tag: 'form-group-completed-push-admin',
+      submitAsEnduser: false,
+    })
+
+    // Enduser submitter: simulates the patient submitting via the portal
+    // (uses an enduser-scoped DB in submit_form_response — exercises the path QA caught).
+    await runFlow({
+      label: 'enduser-submit',
+      tag: 'form-group-completed-push-enduser',
+      submitAsEnduser: true,
+    })
+
+  } finally {
+    for (const id of createdTriggerIds) {
+      try { await sdk.api.automation_triggers.deleteOne(id) } catch (e) { /* ignore */ }
+    }
+    for (const id of createdEnduserIds) {
+      try { await sdk.api.endusers.deleteOne(id) } catch (e) { /* ignore */ }
+    }
+    for (const id of createdJourneyIds) {
+      try { await sdk.api.journeys.deleteOne(id) } catch (e) { /* ignore */ }
+    }
+    for (const id of createdFormGroupIds) {
+      try { await sdk.api.form_groups.deleteOne(id) } catch (e) { /* ignore */ }
+    }
+    for (const id of createdFormIds) {
+      try { await sdk.api.forms.deleteOne(id) } catch (e) { /* ignore */ }
+    }
+  }
+}
+
+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 push_forms_to_portal_group_completion_tests({ sdk, sdkNonAdmin })
+  }
+
+  runTests()
+    .then(() => {
+      console.log("✅ Push forms to portal group completion test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ Push forms to portal group completion test suite failed:", error)
+      process.exit(1)
+    })
+}

package/src/tests/api_tests/security/F-0001-data-sync-redaction-bypass.test.ts

@@ -0,0 +1,236 @@
+require('source-map-support').install();
+
+import { Session } from "../../../sdk"
+import {
+  async_test,
+  log_header,
+  wait,
+} from "@tellescope/testing"
+import { setup_tests } from "../../setup"
+import { PROVIDER_PERMISSIONS } from "@tellescope/constants"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+const [nonAdminEmail, nonAdminPassword] = [process.env.NON_ADMIN_EMAIL, process.env.NON_ADMIN_PASSWORD]
+
+const FULL_ACCESS = { create: 'All' as const, read: 'All' as const, update: 'All' as const, delete: 'All' as const }
+
+// Schema fields tagged `redactions: ['all']` that must never appear in
+// `/v1/data-sync` results. See packages/public/schema/src/schema.ts.
+const REDACTABLE_FIELDS_BY_MODEL: Record<string, string[]> = {
+  users:    ['hashedPass', 'hashedInviteCode'],
+  endusers: ['hashedPassword'],
+}
+
+type Violation = { modelName: string, recordId: string, leakedField: string }
+
+const collectViolations = (results: { modelName: string, recordId: string, data: string }[]): Violation[] => {
+  const violations: Violation[] = []
+  for (const record of results) {
+    if (!record.data || record.data === 'deleted') continue
+    const fields = REDACTABLE_FIELDS_BY_MODEL[record.modelName]
+    if (!fields) continue
+    let parsed: any
+    try { parsed = JSON.parse(record.data) } catch { continue }
+    for (const f of fields) {
+      if (f in parsed && parsed[f] !== undefined && parsed[f] !== null && parsed[f] !== '') {
+        violations.push({ modelName: record.modelName, recordId: record.recordId, leakedField: f })
+      }
+    }
+  }
+  return violations
+}
+
+/**
+ * Regression test for F-0001 (security-audit/findings/F-0001-data-sync-bypasses-applyRedactions.md).
+ *
+ * The /v1/data-sync handler must apply the central applyRedactions() pipeline to
+ * every non-deleted record. The original bug: redactions were gated behind
+ *   `if (session.fieldRedactions && session.fieldRedactions[record.modelName])`
+ * which meant any session without role-based field redactions (including all
+ * admins) received raw records — leaking schema-level `redactions: ['all']`
+ * fields (hashedPass, hashedPassword, hashedInviteCode).
+ *
+ * This test:
+ *   1. Configures a non-admin user with broad read access on users + endusers
+ *      and NO fieldRedactions — the realistic "regular user with read access"
+ *      condition that triggers the bypass.
+ *   2. Creates an enduser with a password to populate the sync stream.
+ *   3. Calls /v1/data-sync as the non-admin.
+ *   4. Asserts no returned record contains hashedPass / hashedPassword /
+ *      hashedInviteCode.
+ *
+ * Pre-fix: assertion fails with leaked records.
+ * Post-fix: assertion passes.
+ */
+export const data_sync_redaction_bypass_tests = async ({ sdk, sdkNonAdmin } : { sdk: Session, sdkNonAdmin: Session }) => {
+  log_header("F-0001: /v1/data-sync field-redaction bypass regression")
+
+  const roleName = `f0001-data-sync-bypass-${Date.now()}`
+  let testEnduserId: string | undefined
+  let rbapId: string | undefined
+  const originalRoles = sdkNonAdmin.userInfo.roles
+
+  try {
+    // 1. Create a role with broad read access but NO fieldRedactions.
+    //    This is the realistic "regular user with read access" condition
+    //    that triggers the bypass in the pre-fix handler.
+    const rbap = await sdk.api.role_based_access_permissions.createOne({
+      role: roleName,
+      permissions: {
+        ...PROVIDER_PERMISSIONS,
+        users: FULL_ACCESS,
+        endusers: FULL_ACCESS,
+      },
+      // intentionally NO fieldRedactions — this is the exploit condition.
+    })
+    rbapId = rbap.id
+
+    // 2. Assign role to the non-admin user and re-authenticate so the new
+    //    session reflects the role's permissions.
+    await sdk.api.users.updateOne(
+      sdkNonAdmin.userInfo.id,
+      { roles: [roleName] },
+      { replaceObjectFields: true },
+    )
+    await wait(undefined, 1500)
+    await sdkNonAdmin.authenticate(nonAdminEmail!, nonAdminPassword!)
+
+    // 3. Create a test enduser and set a password — this populates
+    //    `hashedPassword` on the enduser record and writes a data_sync_records
+    //    row for it.
+    const testEnduser = await sdk.api.endusers.createOne({
+      fname: 'F0001Target',
+      lname: 'Patient',
+      email: `f0001-target-${Date.now()}@example.com`,
+    })
+    testEnduserId = testEnduser.id
+    await sdk.api.endusers.set_password({ id: testEnduser.id, password: 'F0001TestPassword!123' })
+
+    // The non-admin user's own `hashedPass` is set from login and refreshed
+    // on every write to their user record (e.g., the role-assignment update
+    // above). No extra setup needed for users.hashedPass to be in the stream.
+
+    await wait(undefined, 500)
+
+    // 4. As the non-admin, call /v1/data-sync from epoch zero to capture all
+    //    sync records the role can see.
+    const sync = await sdkNonAdmin.sync({ from: new Date(0) })
+
+    // 5. Walk every record. Fail if any contains a `redactions: ['all']` field.
+    const violations = collectViolations(sync.results)
+
+    // Belt-and-suspenders: at least one user record SHOULD be in the stream
+    // (the non-admin's own record). If the stream is empty, the assertion below
+    // would pass vacuously — guard against that.
+    const userRecordsInStream = sync.results.filter(r => r.modelName === 'users').length
+    await async_test(
+      "F-0001 guard: /v1/data-sync sync stream contains at least one user record",
+      async () => ({ userRecords: userRecordsInStream, totalRecords: sync.results.length }),
+      { onResult: r => r.userRecords >= 1 },
+    )
+
+    await async_test(
+      "F-0001: /v1/data-sync must NOT return hashedPass / hashedPassword / hashedInviteCode (see security-audit/findings/F-0001)",
+      async () => ({
+        violationCount: violations.length,
+        violations: violations.slice(0, 10),
+        affectedModels: Array.from(new Set(violations.map(v => v.modelName))),
+        affectedFields: Array.from(new Set(violations.map(v => v.leakedField))),
+      }),
+      { onResult: r => r.violationCount === 0 },
+    )
+
+    // ========================================================================
+    // Additional coverage for applyRedactions code paths reachable via /v1/data-sync.
+    // Each of these is a distinct branch in applyRedactions (routing.ts:1165-1238)
+    // and could regress independently of the F-0001 fix.
+    // ========================================================================
+
+    // Case A: schema-level `redactions: ['all']` must apply to ADMIN sessions too.
+    // Admins have no session.fieldRedactions, but `redactions: ['all']` is universal.
+    // Pre-fix: admin saw hashedPass via data-sync because applyRedactions was skipped entirely.
+    // Post-fix: applyRedactions always runs and `redactions: ['all']` strips for everyone.
+    const adminSync = await sdk.sync({ from: new Date(0) })
+    const adminViolations = collectViolations(adminSync.results)
+    await async_test(
+      "F-0001 coverage A: admin /v1/data-sync also strips redactions:['all'] fields (hashedPass etc.)",
+      async () => ({
+        violationCount: adminViolations.length,
+        violations: adminViolations.slice(0, 10),
+      }),
+      { onResult: r => r.violationCount === 0 },
+    )
+
+    // Case B: `linkedAccountAccess` on users must be stripped when the caller is NOT
+    // the record's owner. This is a separate branch in applyRedactions (routing.ts:1220-1225)
+    // and protects against cross-user enumeration of who-requested-access-to-whom.
+    // The non-admin user reads other user records via data-sync; if any of those
+    // records have linkedAccountAccess set, it must be stripped on read.
+    const otherUsersInStream = sync.results.filter(
+      r => r.modelName === 'users' && r.recordId !== sdkNonAdmin.userInfo.id
+    )
+    const linkedAccountLeaks: { recordId: string }[] = []
+    for (const record of otherUsersInStream) {
+      if (!record.data || record.data === 'deleted') continue
+      try {
+        const parsed = JSON.parse(record.data)
+        if ('linkedAccountAccess' in parsed && parsed.linkedAccountAccess !== undefined) {
+          linkedAccountLeaks.push({ recordId: record.recordId })
+        }
+      } catch {}
+    }
+    await async_test(
+      "F-0001 coverage B: /v1/data-sync strips linkedAccountAccess from other users' records",
+      async () => ({
+        otherUserRecords: otherUsersInStream.length,
+        leakCount: linkedAccountLeaks.length,
+        leaks: linkedAccountLeaks.slice(0, 5),
+      }),
+      { onResult: r => r.leakCount === 0 },
+    )
+  } finally {
+    // Cleanup: restore non-admin's original roles, delete role and test enduser.
+    try {
+      await sdk.api.users.updateOne(
+        sdkNonAdmin.userInfo.id,
+        { roles: originalRoles ?? [] },
+        { replaceObjectFields: true },
+      )
+    } catch {}
+    if (rbapId) {
+      try { await sdk.api.role_based_access_permissions.deleteOne(rbapId) } catch {}
+    }
+    if (testEnduserId) {
+      try { await sdk.api.endusers.deleteOne(testEnduserId) } catch {}
+    }
+    // Re-authenticate the non-admin to drop the exploit role from their JWT
+    // before subsequent tests run.
+    // Role restore above re-triggers deauthenticate_user; wait > 1s so the freshly minted
+    // token's (second-floored) iat lands after the deauth timestamp and isn't permanently
+    // rejected by is_logged_in's iat-slack check. Matches the in-test re-auth above.
+    await wait(undefined, 1500)
+    try { await sdkNonAdmin.authenticate(nonAdminEmail!, nonAdminPassword!) } 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 data_sync_redaction_bypass_tests({ sdk, sdkNonAdmin })
+  }
+
+  runTests()
+    .then(() => {
+      console.log("✅ F-0001 data-sync redaction-bypass test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ F-0001 data-sync redaction-bypass test suite failed:", error)
+      process.exit(1)
+    })
+}

package/src/tests/api_tests/security/F-0005-ai-conversations-rbac.test.ts

@@ -0,0 +1,154 @@
+require('source-map-support').install();
+
+import { ObjectId } from 'bson'
+import { Session } from "../../../sdk"
+import {
+  async_test,
+  log_header,
+  wait,
+} from "@tellescope/testing"
+import { setup_tests } from "../../setup"
+import { PROVIDER_PERMISSIONS } from "@tellescope/constants"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+const [nonAdminEmail, nonAdminPassword] = [process.env.NON_ADMIN_EMAIL, process.env.NON_ADMIN_PASSWORD]
+
+/**
+ * Regression test for F-0005 (security-audit/findings/F-0005-ai-conversations-bypass-rbac.md).
+ *
+ * Both `ai_conversations.send_message` and `ai_conversations.generate_ai_decision` are
+ * registered with `noAccessPermissions: true` ([api.ts:22699, 22721](packages/private/api/api/v1/api.ts)).
+ * Their only access gate is `if (req.session.type === 'enduser') throw 403`. They must ALSO
+ * check `session.access?.ai_conversations?.<action>` (and `session.access?.endusers?.read`
+ * for generate_ai_decision) — the standard pattern used 16 lines earlier in the same file
+ * at api.ts:22680 for the background_errors handler.
+ *
+ * This test:
+ *   1. Creates a role with explicit NO_ACCESS for ai_conversations (and endusers).
+ *   2. Assigns the role to the non-admin user.
+ *   3. Calls each endpoint as the non-admin.
+ *   4. Asserts each endpoint returns a 403-equivalent error (not 200).
+ *
+ * Pre-fix:
+ *   - send_message: 200 (or some downstream error from Bedrock) — NOT 403. Test fails.
+ *   - generate_ai_decision: 200 with `{}` (handler responds early before access check). Test fails.
+ *
+ * Post-fix: both endpoints throw 403 before any work happens. Test passes.
+ */
+export const ai_conversations_rbac_tests = async ({ sdk, sdkNonAdmin } : { sdk: Session, sdkNonAdmin: Session }) => {
+  log_header("F-0005: ai_conversations RBAC bypass regression")
+
+  const roleName = `f0005-ai-conversations-no-access-${Date.now()}`
+  let rbapId: string | undefined
+  const originalRoles = sdkNonAdmin.userInfo.roles
+
+  try {
+    // 1. Create a role that explicitly denies ai_conversations access AND endusers access.
+    //    This is the realistic configuration the bypass affects: a tenant operator
+    //    deliberately restricts a role from reading AI conversations / enduser PHI.
+    const rbap = await sdk.api.role_based_access_permissions.createOne({
+      role: roleName,
+      permissions: {
+        ...PROVIDER_PERMISSIONS,
+        ai_conversations: { create: null, read: null, update: null, delete: null },
+        endusers:         { create: null, read: null, update: null, delete: null },
+      },
+    })
+    rbapId = rbap.id
+
+    // 2. Assign the role to the non-admin user and re-authenticate so the new
+    //    session reflects the role's denied permissions.
+    await sdk.api.users.updateOne(
+      sdkNonAdmin.userInfo.id,
+      { roles: [roleName] },
+      { replaceObjectFields: true },
+    )
+    await wait(undefined, 1500)
+    await sdkNonAdmin.authenticate(nonAdminEmail!, nonAdminPassword!)
+
+    // 3a. send_message must throw 403 (or equivalent access error). Pre-fix: succeeds (or
+    //     fails downstream in Bedrock without 403). Post-fix: throws before any work.
+    await async_test(
+      "F-0005: ai_conversations.send_message must throw 403 when role denies ai_conversations",
+      () => sdkNonAdmin.api.ai_conversations.send_message({
+        message: 'F-0005 regression test',
+        type: 'Test',
+      } as any),
+      {
+        shouldError: true,
+        onError: (e: any) => {
+          // Accept any 4xx access-denial response — handler may use 403 (recommended)
+          // or 400 with "access" / "permission" in the message.
+          const msg = (e?.message ?? '').toLowerCase()
+          const status = e?.status ?? e?.code
+          return status === 403 || status === 401
+            || msg.includes('access') || msg.includes('permission') || msg.includes('forbidden')
+        },
+      },
+    )
+
+    // 3b. generate_ai_decision must throw 403 BEFORE the early res.json({}) response.
+    //     Pre-fix: handler responds 200 with {} immediately and processes in background.
+    //     Post-fix: handler throws 403 before res.json({}).
+    await async_test(
+      "F-0005: ai_conversations.generate_ai_decision must throw 403 when role denies endusers/ai_conversations",
+      () => sdkNonAdmin.api.ai_conversations.generate_ai_decision({
+        enduserId: new ObjectId().toHexString(),        // fake id — access check should fire first
+        automationStepId: new ObjectId().toHexString(),  // fake id — access check should fire first
+        outcomes: ['yes', 'no'],
+        prompt: 'F-0005 regression test',
+        sources: [{ type: 'SMS', limit: 1 }],            // non-empty so the validator passes; access check then fires
+      } as any),
+      {
+        shouldError: true,
+        onError: (e: any) => {
+          const msg = (e?.message ?? '').toLowerCase()
+          const status = e?.status ?? e?.code
+          return status === 403 || status === 401
+            || msg.includes('access') || msg.includes('permission') || msg.includes('forbidden')
+        },
+      },
+    )
+  } finally {
+    // Cleanup: restore original roles, delete the test role.
+    try {
+      await sdk.api.users.updateOne(
+        sdkNonAdmin.userInfo.id,
+        { roles: originalRoles ?? [] },
+        { replaceObjectFields: true },
+      )
+    } catch {}
+    if (rbapId) {
+      try { await sdk.api.role_based_access_permissions.deleteOne(rbapId) } catch {}
+    }
+    // Re-authenticate the non-admin to drop the no-access role from their JWT
+    // before subsequent tests run.
+    // Role restore above re-triggers deauthenticate_user; wait > 1s so the freshly minted
+    // token's (second-floored) iat lands after the deauth timestamp and isn't permanently
+    // rejected by is_logged_in's iat-slack check. Matches the in-test re-auth above.
+    await wait(undefined, 1500)
+    try { await sdkNonAdmin.authenticate(nonAdminEmail!, nonAdminPassword!) } 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 ai_conversations_rbac_tests({ sdk, sdkNonAdmin })
+  }
+
+  runTests()
+    .then(() => {
+      console.log("✅ F-0005 ai_conversations RBAC test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ F-0005 ai_conversations RBAC test suite failed:", error)
+      process.exit(1)
+    })
+}