@tellescope/sdk 1.256.12 → 1.256.14

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) })
+}

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

@@ -0,0 +1,288 @@
+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"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+
+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 for F-0191
+ * (security-audit/findings/F-0191-schema-adminonly-not-enforced.md).
+ *
+ * `adminOnly: true` on a CUSTOM action in schema.ts was documentation-only. The runtime gate
+ * (routing.ts:944) reads the flag off the options object built by getCustomEndpointFields, and
+ * api.ts:609 set `adminOnly: o.adminOnly` without ever consulting `action.adminOnly`. So every
+ * admin-only custom action had to declare the flag twice, and the copies desynced: 11 of 20
+ * declared custom actions were unenforced at runtime while both public doc artifacts
+ * (openapi.json and the unauthenticated GET /documentation feed, which read the SCHEMA flag)
+ * advertised "**Admin only.**".
+ *
+ * DEFAULT CRUD actions never had this bug — routing.ts:2434 etc. read
+ * model.defaultActions.<op>.adminOnly straight off the schema. The fix
+ * (`adminOnly: o.adminOnly ?? action.adminOnly`) makes custom actions behave the same way.
+ *
+ * Five of the 11 were de-flagged in the schema instead, because the flag itself was wrong and
+ * enforcing it would revert a deliberate decision: users.invite_user carries an explicit
+ * "no longer admin only, but controlled by users.create" and send_invitation_to_existing is its
+ * sibling; organizations.create_and_join is the self-service signup path and would 401 every new
+ * org (a fresh user has no roles — the handler is what grants Admin); sync_note_to_canvas is
+ * designed around `access: 'read'` for non-admin callers; background_errors.mark_read substitutes
+ * its own RBAC check that intentionally admits non-admins holding the verb.
+ *
+ * SAFETY: every probe fails EARLY inside its handler — after the adminOnly gate but before any
+ * vendor call. Pre-fix these requests really do reach the handler, and these handlers talk to
+ * Twilio, Athena and Canvas:
+ *   - trigger_events     : no `action` key + an absent triggerId => the loop `continue`s (inert)
+ *   - athena-subscription: frequency 1 trips the `frequency < 5` guard on the handler's first line
+ *   - sync-athena        : 404s on the missing Athena integration (skipped if one exists)
+ *   - link-twilio        : takes NO parameters and can CREATE A REAL TWILIO SUBACCOUNT, so it is
+ *                          probed only when the org already has a twilioSID (handler short-circuits)
+ *   - twilio-embed       : no phoneNumberSid => 404 no-config or 400, both before any Twilio call
+ *   - handle-autoreply   : absent enduserId => `if (!enduser) return` (communications.ts:42)
+ * Input validation runs BEFORE the adminOnly gate (routing.ts:921 orders access, then validate),
+ * so every probe body must be schema-VALID or the test would prove nothing.
+ *
+ * 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.
+ */
+export const schema_adminonly_enforcement_tests = async ({ sdk } : { sdk: Session, sdkNonAdmin: Session }) => {
+  log_header("F-0191: schema-declared adminOnly must be enforced on custom actions")
+
+  const checks: Check[] = []
+  const record = (label: string, pass: boolean, detail: string) => checks.push({ label, pass, detail })
+
+  // Raw axios: the SDK's parseError discards the HTTP status, and the status is the whole point.
+  const request = async (
+    authToken: string, method: 'get' | 'post', path: string, data?: any,
+  ) => {
+    const r = await axios.request({
+      method,
+      url: `${host}/v1${path}`,
+      ...method === 'get' ? { params: data } : { data },
+      headers: { Authorization: `Bearer ${authToken}` },
+      validateStatus: () => true,
+    })
+    return { status: r.status, body: r.data }
+  }
+
+  const isAdminDenial = (r: { status: number, body: any }) => (
+    r.status === 401 && r.body?.message === 'Admin access only'
+  )
+  const summarize = (r: { status: number, body: any }) => (
+    `${r.status} ${(JSON.stringify(r.body) ?? '').slice(0, 120)}`
+  )
+
+  let roleId = ''
+  let attackerId = ''
+  let enduserId = ''
+
+  try {
+    /* ================= fixtures ================= */
+
+    const role = `f0191-staff-${RAND()}`
+    const rbap = await sdk.api.role_based_access_permissions.createOne({
+      role,
+      permissions: {
+        ...PROVIDER_PERMISSIONS,
+        // grant exactly the verbs the actions under test declare, so a rejection proves the ADMIN
+        // gate fired rather than ordinary RBAC
+        automation_triggers: FULL_ACCESS,
+        organizations: FULL_ACCESS,
+        availability_blocks: FULL_ACCESS,
+        background_errors: FULL_ACCESS,
+        users: FULL_ACCESS,
+      },
+    } as any)
+    roleId = rbap.id
+
+    const attacker = await sdk.api.users.createOne({
+      email: `f0191-attacker-${RAND()}@tellescope.example`,
+      fname: 'F0191', lname: 'Staff',
+      verifiedEmail: true,
+      notificationEmailsDisabled: true,
+      roles: [role],
+    } as any)
+    attackerId = attacker.id
+
+    const attackerToken = (await sdk.api.users.generate_auth_token({ id: attackerId })).authToken
+    const adminToken = (await sdk.api.users.generate_auth_token({ id: sdk.userInfo.id })).authToken
+
+    const attackerSDK = new Session({ host, authToken: attackerToken })
+    await attackerSDK.refresh_session()
+    record(
+      'setup: attacker is a non-admin holding every verb under test',
+      attackerSDK.userInfo.id === attackerId && !(attackerSDK.userInfo.roles ?? []).includes('Admin'),
+      `id=${attackerSDK.userInfo.id} roles=${JSON.stringify(attackerSDK.userInfo.roles)}`,
+    )
+
+    const enduser = await sdk.api.endusers.createOne({ fname: 'F0191', lname: 'Patient' })
+    enduserId = enduser.id
+
+    // A guaranteed-valid, guaranteed-absent id: create then delete, so probes hit the handler's
+    // "not found" branch rather than tripping input validation (which runs BEFORE the admin gate).
+    const doomed = await sdk.api.endusers.createOne({ fname: 'F0191', lname: 'Absent' })
+    const ABSENT_ID = doomed.id
+    await sdk.api.endusers.deleteOne(ABSENT_ID)
+
+    /* ===== environment guards for the two probes input alone cannot make safe ===== */
+
+    let athenaIntegrationExists = false
+    try {
+      const existing = await sdk.api.integrations.load_redacted({})
+      athenaIntegrationExists = !!existing.integrations.find((i: any) => /athena/i.test(i.title ?? ''))
+    } catch { /* load not permitted — assume absent */ }
+
+    let orgHasTwilioSID = false
+    try {
+      const org = await sdk.api.organizations.getOne(sdk.userInfo.businessId)
+      orgHasTwilioSID = !!(org as any)?.twilioSID
+    } catch { /* ignore */ }
+
+    /* ===== GROUP B: the six genuine gaps — each must become 401 ===== */
+
+    const groupB: {
+      label: string, method: 'get' | 'post', path: string, data?: any, skip?: string,
+    }[] = [
+      {
+        label: 'automation_triggers.trigger_events',
+        method: 'post', path: '/automation-triggers/trigger-events',
+        // no `action` key: stays off the arbitrary-action-execution branch entirely
+        data: { triggers: [{ enduserId, automationTriggerId: ABSENT_ID }] },
+      },
+      {
+        label: 'organizations.add_athena_subscription',
+        method: 'post', path: '/organizations/athena-subscription',
+        data: { type: 'patients', frequency: 1 }, // trips `frequency < 5` on the handler's first line
+      },
+      {
+        label: 'organizations.sync_athena_subscription',
+        method: 'post', path: '/organizations/sync-athena-subscription',
+        data: { type: 'patients' },
+        skip: athenaIntegrationExists
+          ? 'org HAS an Athena integration — probing would call Athena.process_subscription for real'
+          : undefined,
+      },
+      {
+        label: 'organizations.link_twilio',
+        method: 'post', path: '/organizations/link-twilio',
+        data: {},
+        skip: orgHasTwilioSID
+          ? undefined
+          : 'org has no twilioSID — probing would CREATE A REAL TWILIO SUBACCOUNT',
+      },
+      {
+        label: 'organizations.load_twilio_embed',
+        method: 'get', path: '/organizations/twilio-embed',
+        data: { type: 'tfn-verification' }, // no phoneNumberSid => rejected before any Twilio call
+      },
+      {
+        label: 'availability_blocks.handle_autoreply',
+        method: 'post', path: '/handle-out-of-office-autoreply',
+        data: { channel: 'Email', enduserId: ABSENT_ID }, // communications.ts:42 `if (!enduser) return`
+      },
+    ]
+
+    for (const probe of groupB) {
+      if (probe.skip) {
+        record(`B: ${probe.label} rejects a non-admin`, true, `SKIPPED (safety) — ${probe.skip}`)
+        continue
+      }
+
+      const attackerResult = await request(attackerToken, probe.method, probe.path, probe.data)
+      // baseline: an admin must NOT be admin-denied on the same path, so a blanket 401 can't pass
+      const baseline = await request(adminToken, probe.method, probe.path, probe.data)
+      const badProbe = isAdminDenial(baseline)
+
+      record(
+        `B: ${probe.label} rejects a non-admin`,
+        !badProbe && isAdminDenial(attackerResult),
+        `attacker=${summarize(attackerResult)} | admin baseline=${baseline.status}`
+          + (badProbe ? ' BAD PROBE: admin was also admin-denied' : ''),
+      )
+    }
+
+    /* ===== GROUP A: de-flagged actions must NOT become admin-only ===== */
+
+    const groupA: { label: string, method: 'get' | 'post', path: string, data?: any }[] = [
+      {
+        label: 'organizations.sync_note_to_canvas',
+        method: 'post', path: '/organizations/sync-note-to-canvas',
+        data: { enduserId: ABSENT_ID, note: 'F-0191 control' }, // 404 Enduser not found
+      },
+      {
+        label: 'background_errors.mark_read',
+        method: 'post', path: '/background-errors/mark-read', data: {},
+      },
+      {
+        label: 'users.send_invitation_to_existing',
+        method: 'post', path: '/invite-existing-user-to-organization',
+        // takes userId (not email); an absent id hits RecordNotFoundError, well short of any invite
+        data: { userId: ABSENT_ID },
+      },
+    ]
+
+    for (const probe of groupA) {
+      const r = await request(attackerToken, probe.method, probe.path, probe.data)
+      record(
+        `A: ${probe.label} stays reachable by a non-admin (flag intentionally dropped)`,
+        !isAdminDenial(r),
+        `${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  F-0191 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 {} }
+  }
+}
+
+// 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()
+    .then(() => {
+      console.log("✅ F-0191 schema adminOnly enforcement test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ F-0191 schema adminOnly enforcement test suite failed:", error)
+      process.exit(1)
+    })
+}