@tellescope/sdk 1.251.0 → 1.252.1

package/src/tests/api_tests/security/F-0008-handle-incoming-communication-cross-tenant.test.ts

@@ -0,0 +1,130 @@
+require('source-map-support').install();
+
+import axios from "axios"
+import { ObjectId } from 'bson'
+import { Session } from "../../../sdk"
+import {
+  async_test,
+  log_header,
+} from "@tellescope/testing"
+import { setup_tests } from "../../setup"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+
+const CROSS_ORG_API_KEY = process.env.CROSS_ORG_API_KEY
+const CROSS_ORG_TARGET_BUSINESS_ID = process.env.CROSS_ORG_TARGET_BUSINESS_ID
+
+const post = async (path: string, body: any, headers: Record<string, string> = {}) => {
+  try {
+    const res = await axios.post(`${host}${path}`, body, {
+      validateStatus: () => true,
+      headers,
+    })
+    return { status: res.status, data: res.data }
+  } catch (err: any) {
+    return { status: err?.response?.status, data: err?.response?.data }
+  }
+}
+
+/**
+ * Regression test for F-0008 (security-audit/findings/F-0008-handle-incoming-communication-cross-tenant-enduser-lookup.md).
+ *
+ * `journeys.handle_incoming_communication` previously used `buildAllQueries({ unrestricted: true, organizationIds: [] }).endusers.findById(enduserId)`,
+ * permitting cross-tenant lookup of any enduser by id. The handler then called `handleIncomingCommunication(...)`
+ * against the matched enduser, triggering journey progression and automated actions on someone else's tenant.
+ *
+ * The fix switches to the standard tenant-scoped `DB.endusers.findById(enduserId)` wrapper, which automatically
+ * filters by `req.session.businessId`. Cross-tenant lookups now return null → handler returns 404 → no side effect.
+ *
+ * Note: the same-tenant happy path is already covered by the existing test at
+ * `packages/public/sdk/src/tests/tests.ts:7588` ("handle_incoming_communication test for other enduser") — that
+ * test creates endusers in the test tenant, sets up journeys, calls handle_incoming_communication, and asserts
+ * journey-step cancellation. This file covers the negative cases only.
+ *
+ * **Negative-only by design**: the test never drives `handleIncomingCommunication` against a cross-tenant
+ * enduser — the post-fix code returns 404 before any side effects fire, and the assertion confirms that.
+ */
+export const handle_incoming_communication_cross_tenant_tests = async ({ sdk, sdkNonAdmin } : { sdk: Session, sdkNonAdmin: Session }) => {
+  log_header("F-0008: handle_incoming_communication cross-tenant rejection")
+
+  // ====================================================================
+  // Assertion 1: nonexistent enduserId returns 404 (baseline; regression
+  // guard for the not-found path that any cross-tenant call now lands in).
+  // ====================================================================
+  const nonexistentId = new ObjectId().toHexString()
+  const nonexistentRes = await post(
+    '/v1/journeys/handle-incoming-communication',
+    { enduserId: nonexistentId },
+    { Authorization: `Bearer ${sdk.authToken}` },
+  )
+  await async_test(
+    "F-0008: handle_incoming_communication with nonexistent enduserId returns 404",
+    async () => ({ status: nonexistentRes.status }),
+    { onResult: r => r.status === 404 },
+  )
+
+  // ====================================================================
+  // Assertion 2: cross-tenant enduserId returns 404 (the actual F-0008 fix).
+  // Env-gated; skipped when cross-org infra isn't configured.
+  // Safe to run post-fix because the tenant-scoped DB returns null for
+  // cross-tenant lookups — no handleIncomingCommunication side effect fires.
+  // ====================================================================
+  if (!(CROSS_ORG_API_KEY && CROSS_ORG_TARGET_BUSINESS_ID)) {
+    console.log("  [F-0008] Skipping cross-tenant rejection assertion — CROSS_ORG_* env vars not set")
+    return
+  }
+
+  const sdkCrossOrg = new Session({
+    host,
+    apiKey: CROSS_ORG_API_KEY,
+    headers: { 'x-tellescope-organization': CROSS_ORG_TARGET_BUSINESS_ID },
+  })
+
+  // Create a sentinel enduser in the cross-org tenant. Use a clearly-test email
+  // so any accidental side-effect routing is obvious in logs.
+  const ts = Date.now()
+  const crossEnduser = await sdkCrossOrg.api.endusers.createOne({
+    fname: 'F0008CrossTenant', lname: 'Sentinel',
+    email: `f0008-cross-${ts}@tellescope.com`,
+  } as any)
+
+  try {
+    const crossRes = await post(
+      '/v1/journeys/handle-incoming-communication',
+      { enduserId: crossEnduser.id },
+      { Authorization: `Bearer ${sdk.authToken}` },
+    )
+
+    await async_test(
+      "F-0008: handle_incoming_communication with cross-tenant enduserId returns 404 (no side effect)",
+      async () => ({
+        status: crossRes.status,
+        message: crossRes.data?.message ?? null,
+      }),
+      { onResult: r => r.status === 404 },
+    )
+  } finally {
+    try { await sdkCrossOrg.api.endusers.deleteOne(crossEnduser.id) } catch {}
+  }
+}
+
+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 handle_incoming_communication_cross_tenant_tests({ sdk, sdkNonAdmin })
+  }
+
+  runTests()
+    .then(() => {
+      console.log("✅ F-0008 handle_incoming_communication cross-tenant test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ F-0008 handle_incoming_communication cross-tenant test suite failed:", error)
+      process.exit(1)
+    })
+}

package/src/tests/api_tests/security/F-0013-sanitize-user-html.test.ts

@@ -0,0 +1,109 @@
+import { sanitize_user_html } from "@tellescope/utilities"
+
+// Regression test for F-0013 / F-0014 (pattern 06 — XSS via dangerouslySetInnerHTML).
+// sanitize_user_html is the canonical render-time sanitizer that replaced remove_script_tags
+// at every dangerouslySetInnerHTML sink. This asserts it neutralizes XSS vectors (incl. encoded /
+// whitespace / mixed-case / iframe-srcdoc bypass variants) while preserving legitimate
+// customization HTML (tables, headings, lists, links, images, inline styles).
+//
+// Pure-function test — no Session needed. Runs as part of the main suite and standalone:
+//   ./build_cjs.sh && cd packages/public/sdk && node -r dotenv/config lib/cjs/tests/api_tests/security/F-0013-sanitize-user-html.test.js
+
+const fail = (msg: string) => { throw new Error(msg) }
+
+const has_no_executable_vector = (out: string) => {
+  const o = out.toLowerCase()
+  // A handler smuggled into an attribute VALUE (e.g. title="<img onerror=...>") is inert
+  // text — strip quoted values before checking for *live* on*= attributes to avoid false positives.
+  const withoutValues = o.replace(/"[^"]*"/g, '""').replace(/'[^']*'/g, "''")
+  return !/\son[a-z]+\s*=/.test(withoutValues)   // no live on*= event-handler attribute
+      && !o.includes('javascript:')              // dropped schemes never appear in safe output
+      && !o.includes('vbscript:')
+      && !o.includes('<script')                  // literal dangerous tags (encoded &lt;script is fine)
+      && !o.includes('<iframe')
+      && !o.includes('<svg')
+      && !o.includes('<math')
+      && !o.includes('<object')
+      && !o.includes('<embed')
+      && !o.includes('<form')
+      && !o.includes('<noscript')
+      && !o.includes('<template')
+}
+
+export const sanitize_user_html_xss_tests = async () => {
+  console.log("Running F-0013/F-0014 sanitize_user_html XSS regression tests")
+
+  const xssPayloads: [string, string][] = [
+    ['img onerror', `<img src=x onerror="alert(document.domain)">`],
+    ['svg onload', `<svg onload="alert(1)"></svg>`],
+    ['svg animate onbegin', `<svg><animate onbegin="alert(1)" attributeName="x" dur="1s"></svg>`],
+    ['details ontoggle', `<details open ontoggle="alert(1)"></details>`],
+    ['input onfocus autofocus', `<input autofocus onfocus="alert(1)">`],
+    ['body onpageshow', `<body onpageshow="alert(1)">`],
+    ['a javascript scheme', `<a href="javascript:alert(1)">x</a>`],
+    ['a javascript entity-encoded', `<a href="jav&#x09;ascript:alert(1)">x</a>`],
+    ['iframe javascript src', `<iframe src="javascript:alert(1)"></iframe>`],
+    ['iframe srcdoc nested', `<iframe srcdoc="<img src=x onerror=alert(1)>"></iframe>`],
+    ['script tag', `<script>alert(1)</script>`],
+    ['onerror newline before =', `<img src=x onerror\n="alert(1)">`],
+    ['onerror mixed case', `<IMG SRC=x OnErRoR="alert(1)">`],
+    ['marquee onstart', `<marquee onstart="alert(1)">x</marquee>`],
+    // mutation / namespace confusion — svg/math/noscript/template must be stripped
+    ['mathml mglyph style mxss', `<math><mtext><table><mglyph><style><!--</style><img src=x onerror=alert(1)>`],
+    ['svg foreignObject', `<svg><foreignObject><img src=x onerror=alert(1)></foreignObject></svg>`],
+    ['noscript context confusion', `<noscript><p title="</noscript><img src=x onerror=alert(1)>">`],
+    ['template content', `<template><img src=x onerror=alert(1)></template>`],
+    // comment / CDATA confusion
+    ['comment confusion', `<!--><img src=x onerror=alert(1)>-->`],
+    ['cdata confusion', `<![CDATA[<img src=x onerror=alert(1)>]]>`],
+    // markup smuggled inside an attribute value must stay inert
+    ['markup inside attr value', `<img src="x" alt="<script>alert(1)</script>">`],
+    // protocol obfuscation
+    ['vbscript scheme', `<a href="vbscript:msgbox(1)">x</a>`],
+    ['data text/html href', `<a href="data:text/html,<script>alert(1)</script>">x</a>`],
+    ['javascript decimal entity', `<a href="&#74;avascript:alert(1)">x</a>`],
+    ['javascript newline entity', `<a href="jav&#x0A;ascript:alert(1)">x</a>`],
+  ]
+  for (const [name, payload] of xssPayloads) {
+    const out = sanitize_user_html(payload)
+    if (!has_no_executable_vector(out)) fail(`XSS not neutralized [${name}] -> ${out}`)
+  }
+
+  // DOM clobbering: caller-controlled id/name must be stripped
+  const clobber = sanitize_user_html(`<a id="x" name="getElementById">link</a><img name="y">`)
+  if (/\b(id|name)\s*=/.test(clobber)) fail(`id/name not stripped (DOM clobbering): ${clobber}`)
+
+  // legitimate customization HTML must survive
+  const heading = sanitize_user_html(`<h1>Welcome</h1><h3 style="color:#333">Sub</h3>`)
+  if (!(heading.includes('<h1>') && heading.includes('<h3') && heading.toLowerCase().includes('color'))) fail(`headings/style stripped: ${heading}`)
+
+  const table = sanitize_user_html(`<table><thead><tr><th>H</th></tr></thead><tbody><tr><td style="padding:4px" colspan="2">cell</td></tr></tbody></table>`)
+  if (!(table.includes('<table') && table.includes('<td') && table.includes('colspan'))) fail(`table stripped: ${table}`)
+
+  const list = sanitize_user_html(`<ul><li>a</li></ul><ol start="3"><li>c</li></ol>`)
+  if (!(list.includes('<ul') && list.includes('<li') && list.includes('<ol'))) fail(`list stripped: ${list}`)
+
+  const link = sanitize_user_html(`<a href="https://example.com">link</a>`)
+  if (!link.includes('href="https://example.com"')) fail(`safe link stripped: ${link}`)
+  if (!link.toLowerCase().includes('noopener')) fail(`external link not hardened: ${link}`)
+
+  const img = sanitize_user_html(`<img src="https://cdn.example.com/a.png" alt="pic" width="200">`)
+  if (!(img.includes('src="https://cdn.example.com/a.png"') && img.includes('alt="pic"'))) fail(`http image stripped: ${img}`)
+
+  const dataimg = sanitize_user_html(`<img src="data:image/png;base64,iVBORw0KGgo=">`)
+  if (!dataimg.includes('data:image/png')) fail(`data: image stripped: ${dataimg}`)
+
+  const fmt = sanitize_user_html(`<p><strong>b</strong> <em>i</em> <span style="font-size:14px">s</span></p><blockquote>q</blockquote>`)
+  if (!(fmt.includes('<strong>') && fmt.includes('<span') && fmt.toLowerCase().includes('font-size'))) fail(`formatting stripped: ${fmt}`)
+
+  const mixed = sanitize_user_html(`<p>Hello <b>name</b></p><img src=x onerror="steal()">`)
+  if (!(mixed.includes('<b>name</b>') && !/\son[a-z]+\s*=/.test(mixed.toLowerCase()))) fail(`mixed content not handled: ${mixed}`)
+
+  console.log("✅ F-0013/F-0014 sanitize_user_html XSS regression tests passed")
+}
+
+if (require.main === module) {
+  sanitize_user_html_xss_tests()
+    .then(() => { console.log("✅ suite completed"); process.exit(0) })
+    .catch((err) => { console.error("❌ suite failed:", err); process.exit(1) })
+}

package/src/tests/api_tests/security/F-0016-prototype-pollution.test.ts

@@ -0,0 +1,50 @@
+import { add_value_for_dotted_key } from "@tellescope/utilities"
+
+// Regression test for F-0016 (pattern 17 — prototype pollution).
+// add_value_for_dotted_key must NOT write through __proto__/constructor/prototype path segments
+// (which would pollute Object.prototype process-wide), while still performing legitimate dotted assignment.
+//
+// Pure-function test — no Session needed. Runs in the main suite and standalone:
+//   ./build_cjs.sh && cd packages/public/sdk && node -r dotenv/config lib/cjs/tests/api_tests/security/F-0016-prototype-pollution.test.js
+
+const fail = (msg: string) => { throw new Error(msg) }
+
+export const prototype_pollution_tests = async () => {
+  console.log("Running F-0016 prototype-pollution regression tests")
+
+  // 1. __proto__ path must not pollute Object.prototype
+  add_value_for_dotted_key({ insurance: {} } as any, 'insurance.__proto__.__pp_a__', 'polluted')
+  const leakedA = ({} as any).__pp_a__
+  delete (Object.prototype as any).__pp_a__ // clean up regardless, so a failure here can't contaminate the rest of the suite
+  if (leakedA !== undefined) fail('Object.prototype polluted via __proto__ path')
+
+  // 2. constructor.prototype path must not pollute
+  add_value_for_dotted_key({ insurance: {} } as any, 'insurance.constructor.prototype.__pp_b__', 'polluted')
+  const leakedB = ({} as any).__pp_b__
+  delete (Object.prototype as any).__pp_b__
+  if (leakedB !== undefined) fail('Object.prototype polluted via constructor.prototype path')
+
+  // 3. a leading __proto__ segment must not pollute either
+  add_value_for_dotted_key({} as any, '__proto__.__pp_c__', 'polluted')
+  const leakedC = ({} as any).__pp_c__
+  delete (Object.prototype as any).__pp_c__
+  if (leakedC !== undefined) fail('Object.prototype polluted via leading __proto__ segment')
+
+  // 4. legitimate dotted assignment still works (existing intermediate objects)
+  const obj = { a: { b: {} } } as any
+  add_value_for_dotted_key(obj, 'a.b.c', 42)
+  if (obj.a.b.c !== 42) fail('legitimate dotted assignment broke')
+
+  // 5. single-key assignment still works
+  const flat = {} as any
+  add_value_for_dotted_key(flat, 'name', 'ok')
+  if (flat.name !== 'ok') fail('single-key assignment broke')
+
+  console.log("✅ F-0016 prototype-pollution regression tests passed")
+}
+
+if (require.main === module) {
+  prototype_pollution_tests()
+    .then(() => { console.log("✅ suite completed"); process.exit(0) })
+    .catch((err) => { console.error("❌ suite failed:", err); process.exit(1) })
+}

package/src/tests/api_tests/security/F-0053-cascade-role-rename-cross-tenant.test.ts

@@ -0,0 +1,161 @@
+require('source-map-support').install();
+
+import { Session } from "../../../sdk"
+import {
+  assert,
+  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
+
+// Separate tenant (different businessId), reusing the same hardcoded apiKey that
+// multi_tenant_tests relies on in tests.ts.
+const OTHER_TENANT_API_KEY = "ba745e25162bb95a795c5fa1af70df188d93c4d3aac9c48b34a5c8c9dd7b80f7"
+
+/**
+ * Tenant-boundary guard for cascade_role_rename (relates to security-audit finding F-0053,
+ * which was investigated and closed as a FALSE POSITIVE — see that file for the code trace).
+ *
+ * The `cascade_role_rename` side-effect handler
+ * ([event_handlers_v2/role_based_access_permissions.ts](packages/private/api/api/v1/event_handlers_v2/role_based_access_permissions.ts))
+ * runs when a `role_based_access_permissions` doc's `role` field changes. It finds every user
+ * with the old role name (via `DBUnrestricted.users`) and rewrites their `roles` array, then
+ * deauthenticates them. F-0053 hypothesized this query was globally cross-tenant. It is NOT:
+ * `DBUnrestricted` bypasses per-user/per-role RBAC but is STILL scoped to the acting session's
+ * `businessId` (see `modifyFilterForAccessConstraint` injecting `{ businessId }` at
+ * database.ts:1761-1763, reached via the `unrestricted: true` branch at database.ts:2137-2144).
+ *
+ * This test locks that boundary in place so a future refactor of `DBUnrestricted` semantics
+ * can't silently turn the cascade into a cross-tenant write:
+ *   1. Tenant A creates a role `ROLE_OLD` and assigns it to a Tenant A user (positive control).
+ *   2. Tenant B (separate businessId) has a user whose roles include the SAME `ROLE_OLD`.
+ *   3. Tenant A renames the role `ROLE_OLD` -> `ROLE_NEW`.
+ *   4. Assert the Tenant B user's roles are UNCHANGED (still `[ROLE_OLD]`)  <-- guards the tenant boundary.
+ *   5. Assert the Tenant A user's roles ARE renamed to `[ROLE_NEW]`         <-- same-tenant cascade works.
+ *
+ * Expected on current (correct) code: BOTH assertions pass. A regression that drops the
+ * `businessId` scoping would flip assertion #4 to red (Tenant B user becomes `[ROLE_NEW]`).
+ *
+ * A collision-proof unique role name (timestamped) is used so the test never touches real roles.
+ */
+export const cascade_role_rename_cross_tenant_tests = async ({ sdk } : { sdk: Session, sdkNonAdmin: Session }) => {
+  log_header("F-0053: cascade role rename cross-tenant regression")
+
+  const stamp = Date.now()
+  const ROLE_OLD = `XTenantRename_${stamp}`
+  const ROLE_NEW = `${ROLE_OLD}_renamed`
+
+  // Tenant B = a genuinely separate businessId (the apiKey's org). admin is required to create /
+  // set roles on users, so the apiKey user must be an Admin in its org.
+  const sdkOther = new Session({ host, apiKey: OTHER_TENANT_API_KEY })
+
+  let rbapId: string | undefined
+  // We create dedicated throwaway users in BOTH tenants and delete them in `finally`. We never
+  // mutate any pre-existing user (an earlier version of this test clobbered the apiKey's own
+  // admin user via getSome+replaceObjectFields — see F-0053 finding notes). controlUser lives in
+  // Tenant A and SHOULD be renamed by the same-tenant cascade; victimUser lives in Tenant B and
+  // must be UNTOUCHED.
+  let controlUserId: string | undefined
+  let victimUserId: string | undefined
+
+  try {
+    const tenantABusinessId = sdk.userInfo.businessId
+
+    // 1. Tenant A: create the role to be renamed.
+    const rbap = await sdk.api.role_based_access_permissions.createOne({
+      role: ROLE_OLD,
+      permissions: { ...PROVIDER_PERMISSIONS },
+    })
+    rbapId = rbap.id
+
+    // 2. Tenant A: create a throwaway control user holding ROLE_OLD (notification emails off).
+    const controlUser = await sdk.api.users.createOne({
+      email: `f0053-control-${stamp}@example.com`,
+      notificationEmailsDisabled: true,
+    } as any)
+    controlUserId = controlUser.id
+    await sdk.api.users.updateOne(controlUserId, { roles: [ROLE_OLD] }, { replaceObjectFields: true })
+
+    // 3. Tenant B: create a throwaway victim user holding the SAME ROLE_OLD.
+    const victimUser = await sdkOther.api.users.createOne({
+      email: `f0053-victim-${stamp}@example.com`,
+      notificationEmailsDisabled: true,
+    } as any)
+    victimUserId = victimUser.id
+    await sdkOther.api.users.updateOne(victimUserId, { roles: [ROLE_OLD] }, { replaceObjectFields: true })
+
+    // 4. Setup sanity: tenants are distinct and both users actually hold ROLE_OLD before the rename.
+    //    (Distinguishes a setup failure from the security assertion below.)
+    assert(
+      victimUser.businessId !== tenantABusinessId,
+      `Victim user shares businessId with Tenant A (${victimUser.businessId}) — not a cross-tenant scenario`,
+      'F-0053 setup: tenants are distinct',
+    )
+    const victimBefore = await sdkOther.api.users.getOne(victimUserId)
+    const controlBefore = await sdk.api.users.getOne(controlUserId)
+    assert(
+      JSON.stringify(victimBefore.roles) === JSON.stringify([ROLE_OLD])
+        && JSON.stringify(controlBefore.roles) === JSON.stringify([ROLE_OLD]),
+      `Setup failed: expected both users to hold [${ROLE_OLD}] (victim=${JSON.stringify(victimBefore.roles)}, control=${JSON.stringify(controlBefore.roles)})`,
+      'F-0053 setup: both users hold ROLE_OLD',
+    )
+
+    // 5. Tenant A renames the role. This triggers cascade_role_rename.
+    await sdk.api.role_based_access_permissions.updateOne(rbapId, { role: ROLE_NEW })
+    await wait(undefined, 1500) // let the side effect run
+
+    // 6. SECURITY ASSERTION — the Tenant B victim must be untouched by Tenant A's rename.
+    const victimAfter = await sdkOther.api.users.getOne(victimUserId)
+    assert(
+      JSON.stringify(victimAfter.roles) === JSON.stringify([ROLE_OLD]),
+      `CROSS-TENANT LEAK: Tenant B victim roles changed to ${JSON.stringify(victimAfter.roles)} `
+        + `after Tenant A renamed its role. Expected [${ROLE_OLD}].`,
+      'F-0053: Tenant B user roles unaffected by other-tenant role rename',
+    )
+
+    // 7. POSITIVE CONTROL — the Tenant A control user SHOULD be renamed (same-tenant cascade intact).
+    const controlAfter = await sdk.api.users.getOne(controlUserId)
+    assert(
+      JSON.stringify(controlAfter.roles) === JSON.stringify([ROLE_NEW]),
+      `Same-tenant cascade broken: Tenant A control roles are ${JSON.stringify(controlAfter.roles)}, `
+        + `expected [${ROLE_NEW}].`,
+      'F-0053: Tenant A user roles renamed by same-tenant cascade',
+    )
+  } finally {
+    // Cleanup: delete both throwaway users and the role doc. Never touches pre-existing users.
+    if (victimUserId) {
+      try { await sdkOther.api.users.deleteOne(victimUserId) } catch {}
+    }
+    if (controlUserId) {
+      try { await sdk.api.users.deleteOne(controlUserId) } catch {}
+    }
+    if (rbapId) {
+      try { await sdk.api.role_based_access_permissions.deleteOne(rbapId) } 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 cascade_role_rename_cross_tenant_tests({ sdk, sdkNonAdmin })
+  }
+
+  runTests()
+    .then(() => {
+      console.log("✅ F-0053 cascade role rename cross-tenant test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ F-0053 cascade role rename cross-tenant test suite failed:", error)
+      process.exit(1)
+    })
+}

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

@@ -0,0 +1,165 @@
+require('source-map-support').install();
+
+import { Session } from "../../../sdk"
+import {
+  assert,
+  log_header,
+  wait,
+} from "@tellescope/testing"
+import { setup_tests } from "../../setup"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+
+/**
+ * Self-role privilege-escalation guard (relates to security-audit finding F-0076, which was
+ * investigated and closed as a FALSE POSITIVE — see that file for the full code trace).
+ *
+ * F-0076 hypothesized that a non-admin staff user could `PATCH /v1/users/{their-own-id}` with
+ * `{ roles: ['Admin'] }` and self-promote to Admin, because the FIRST `users` relationship
+ * constraint ("Only admin users can set the admin role",
+ * [schema.ts:3446](packages/public/schema/src/schema.ts#L3446)) has a self-exception
+ * (`if (_id === session.id) return`).
+ *
+ * That analysis missed the SECOND constraint, "Only admin users can update user roles"
+ * ([schema.ts:3486](packages/public/schema/src/schema.ts#L3486)), which has NO self-exception.
+ * Relationship constraints are AND-evaluated — `validateRelationshipConstraints`
+ * ([routing.ts:1240-1252](packages/private/api/api/modules/routing.ts#L1240)) loops the whole
+ * array and throws 400 on the FIRST evaluator that returns a string. So a non-admin self-update
+ * that includes `roles` passes constraint #1 (self-exception) but is rejected by constraint #2.
+ * 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):
+ *   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
+ *   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.
+ */
+export const self_admin_role_assignment_tests = async ({ sdk } : { sdk: Session, sdkNonAdmin: Session }) => {
+  log_header("F-0076: self-admin role assignment privilege-escalation regression")
+
+  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 attackerId: string | undefined
+
+  try {
+    // 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
+    //    on the role constraint we're actually testing.
+    const attacker = await sdk.api.users.createOne({
+      email: `f0076-attacker-${stamp}@example.com`,
+      notificationEmailsDisabled: true,
+      verifiedEmail: true,
+    } as any)
+    attackerId = attacker.id
+    await sdk.api.users.updateOne(attackerId, { roles: [NON_ADMIN_ROLE] }, { replaceObjectFields: true })
+    await wait(undefined, 2000) // role change triggers a logout; let it propagate before minting a token
+
+    // 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)}`,
+      'F-0076 setup: attacker holds a non-admin role',
+    )
+
+    // 2. Authenticate AS the attacker (no password needed — admin mints an auth token).
+    const sdkAttacker = new Session({
+      host,
+      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`,
+      'F-0076 setup: authenticated as the non-admin attacker',
+    )
+
+    // 3. SECURITY ASSERTIONS — every self-role mutation by the non-admin must be blocked.
+    await expect_blocked(
+      () => sdkAttacker.api.users.updateOne(attackerId!, { roles: ['Admin'] }, { replaceObjectFields: true }),
+      'F-0076: non-admin self-update to [Admin] is blocked',
+    )
+    await expect_blocked(
+      () => sdkAttacker.api.users.updateOne(attackerId!, { roles: [NON_ADMIN_ROLE, 'Admin'] }, { replaceObjectFields: true }),
+      'F-0076: non-admin self-update to [Provider, Admin] is blocked',
+    )
+    await expect_blocked(
+      () => sdkAttacker.api.users.updateOne(attackerId!, { roles: [`Arbitrary_${stamp}`] }, { replaceObjectFields: true }),
+      'F-0076: non-admin self-update to an arbitrary role is blocked',
+    )
+    await expect_blocked(
+      () => sdkAttacker.api.users.updateOne(attackerId!, { roles: [] }, { replaceObjectFields: true }),
+      'F-0076: non-admin self-update to [] (would grant defaults) is blocked',
+    )
+
+    // 4. STATE ASSERTION — 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}].`,
+      'F-0076: attacker roles unchanged after all self-escalation attempts',
+    )
+
+    // 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}]`,
+      'F-0076: admin can manage user roles (positive control)',
+    )
+  } finally {
+    // Cleanup: delete the throwaway attacker. Never touches pre-existing users.
+    if (attackerId) {
+      try { await sdk.api.users.deleteOne(attackerId) } 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 self_admin_role_assignment_tests({ sdk, sdkNonAdmin })
+  }
+
+  runTests()
+    .then(() => {
+      console.log("✅ F-0076 self-admin role assignment test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ F-0076 self-admin role assignment test suite failed:", error)
+      process.exit(1)
+    })
+}