@tellescope/sdk 1.256.13 → 1.256.14

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

package/src/tests/api_tests/security/F-0192-automated-actions-process-gate.test.ts

@@ -0,0 +1,238 @@
+require('source-map-support').install();
+
+import axios from "axios"
+
+import { Session } from "../../../sdk"
+import {
+  assert,
+  log_header,
+} from "@tellescope/testing"
+import { PROVIDER_PERMISSIONS, PLACEHOLDER_ID } 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 }
+
+const PROCESS_PATH = '/v1/automated-actions/process'
+
+// A single collected check. Everything is gathered first and asserted at the end, because the
+// testing harness exits the process on the first failed assert — collecting first means a RED run
+// prints the full evidence table (and reaches `finally` cleanup) before the first assert exits.
+type Check = {
+  label: string,
+  pass: boolean,
+  detail: string,
+}
+
+/**
+ * Regression test for F-0192
+ * (security-audit/findings/F-0192-automated-actions-process-fire-replay.md).
+ *
+ * `automated_actions.process` (api.ts:3902) is the WORKER's action runner — its schema description
+ * reads "Used by worker for new action types". It was registered with only
+ * `{ requiresSubscription: true }`, so the framework gated it on the ordinary
+ * `automated_actions.update` verb, which the default provider role holds ('Assigned'). The handler
+ * then dispatched `automatedAction.action` through a 14-branch if-chain reaching real vendors:
+ * chargebeeChargeCardOnFile (card charge), belugaAutoRx / belugaTriggerRefill / mdiTriggerRefill
+ * (prescriptions and refills), createScriptSureDraft (medication draft), healthiePushForms /
+ * metriportPushFormResponse (PHI export). It checked neither the row's `status` nor whether it had
+ * already run, so any row was replayable: MDI advances to the next scheduled refill each call,
+ * Chargebee charges again. And there was no storeUserLog, so the action was attributed to the
+ * worker rather than the caller.
+ *
+ * The fix has three parts:
+ *   1. `adminOnly: true` on the api.ts registration (routing.ts:944 reads the flag from that
+ *      options object — a schema-only flag is inert, which is the separate finding F-0191).
+ *   2. A single-fire claim for human callers: an atomic findOneAndUpdate with `status: 'active'` in
+ *      the filter, stamping `finished` + `processedAt` before the vendor dispatch. The worker
+ *      (`wasAutomated`) is exempt because its own claim in
+ *      worker/modules/database.ts:114 is already atomic and it needs the row to stay 'active'
+ *      across the call so a retryable failure (worker/modules/automations.ts:2053) can be
+ *      re-claimed after the lock times out.
+ *   3. storeUserLog on the human path, recording the caller and the automatedActionId.
+ *
+ * The seeded row uses `setEnduserStatus`, which is NOT one of the API's if-chain branches, so it
+ * falls through to `{ success: false, unimplemented: true }` (api.ts) — no vendor call, no Bedrock,
+ * no PHI export. `processAfter` is set an hour out so the live worker cannot race the row (the same
+ * trick mdi_trigger_refill / beluga_trigger_refill use).
+ *
+ * RED (pre-fix): A1 fails (a non-admin holding only `automated_actions.update` reaches the handler)
+ * and C1 fails (the second call on the same row executes again instead of being rejected).
+ * B1 (admin positive control) passes pre-fix and must keep passing.
+ * GREEN (post-fix): all five checks pass.
+ */
+export const automated_actions_process_gate_tests = async ({ sdk } : { sdk: Session, sdkNonAdmin: Session }) => {
+  log_header("F-0192: automated_actions.process must be admin-only and single-fire")
+
+  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 whole point here is WHICH
+  // status the gate returns.
+  const post = async (authToken: string, automatedActionId: string) => {
+    const r = await axios.request({
+      method: 'post',
+      url: `${host}${PROCESS_PATH}`,
+      data: { automatedActionId },
+      headers: { Authorization: `Bearer ${authToken}` },
+      validateStatus: () => true,
+    })
+    return { status: r.status, body: r.data }
+  }
+
+  let roleId = ''
+  let attackerId = ''
+  let enduserId = ''
+  const automatedActionIds: string[] = []
+
+  try {
+    /* ================= fixtures ================= */
+
+    // A non-admin role that explicitly HOLDS automated_actions update — the point of the finding is
+    // that holding the declared verb was enough to fire vendor actions.
+    const role = `f0192-automations-${RAND()}`
+    const rbap = await sdk.api.role_based_access_permissions.createOne({
+      role,
+      permissions: { ...PROVIDER_PERMISSIONS, automated_actions: FULL_ACCESS },
+    } as any)
+    roleId = rbap.id
+
+    // Throwaway staff user — never mutate an existing user's roles. verifiedEmail must be set at
+    // create time (it is rejected on update), otherwise calls are blocked on email verification
+    // rather than on the gate under test.
+    const attacker = await sdk.api.users.createOne({
+      email: `f0192-attacker-${RAND()}@tellescope.example`,
+      fname: 'F0192', lname: 'Staff',
+      verifiedEmail: true,
+      notificationEmailsDisabled: true,
+      roles: [role],
+    } as any)
+    attackerId = attacker.id
+
+    // Admin-minted token, not .authenticate — /login is IP rate-limited and the suite shares an IP.
+    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 session is a non-admin holding automated_actions.update',
+      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: 'F0192', lname: 'Patient' })
+    enduserId = enduser.id
+
+    // `setEnduserStatus` is handled by the worker, NOT by the API's process if-chain, so it falls
+    // through to `unimplemented: true`. processAfter is an hour out so the live worker cannot claim
+    // the row before the explicit calls below.
+    const seedAction = async () => {
+      const a = await sdk.api.automated_actions.createOne({
+        enduserId,
+        journeyId: PLACEHOLDER_ID,
+        automationStepId: PLACEHOLDER_ID,
+        event: { type: 'onJourneyStart', info: {} },
+        action: { type: 'setEnduserStatus', info: { status: 'Working' } },
+        status: 'active',
+        processAfter: Date.now() + 60 * 60 * 1000,
+      } as any)
+      automatedActionIds.push(a.id)
+      return a
+    }
+
+    /* ===== A: the privilege gap — a non-admin with the declared verb must be rejected ===== */
+
+    const attackerRow = await seedAction()
+    const attackerAttempt = await post(attackerToken, attackerRow.id)
+
+    // Baseline on the same path with an admin token, so a blanket 401 (expired subscription,
+    // bad route, broken fixture) cannot masquerade as a working gate.
+    const baselineRow = await seedAction()
+    const baseline = await post(adminToken, baselineRow.id)
+    const badProbe = baseline.status === 401 || baseline.status === 403
+
+    record(
+      'A1: a non-admin holding automated_actions.update cannot call process',
+      !badProbe && (attackerAttempt.status === 401 || attackerAttempt.status === 403),
+      `attacker=${attackerAttempt.status} ${JSON.stringify(attackerAttempt.body)} baseline(admin)=${baseline.status}`
+        + (badProbe ? ' BAD PROBE: admin baseline was also rejected' : ''),
+    )
+
+    // The attacker's row must be untouched — the gate has to fire before the claim and the dispatch.
+    const attackerRowAfter = await sdk.api.automated_actions.getOne(attackerRow.id)
+    record(
+      'A2: a rejected non-admin call leaves the row unfired (status still active)',
+      attackerRowAfter.status === 'active',
+      `status=${attackerRowAfter.status} (expected active)`,
+    )
+
+    /* ===== B: positive control — an admin can still call it ===== */
+
+    record(
+      'B1: an admin can still process a pending row',
+      baseline.status === 200 && baseline.body?.unimplemented === true,
+      `status=${baseline.status} body=${JSON.stringify(baseline.body)}`,
+    )
+
+    /* ===== C: the replay gate — the same row must not fire twice ===== */
+
+    const replay = await post(adminToken, baselineRow.id)
+    record(
+      'C1: processing the same row twice is rejected (no replay)',
+      replay.status === 409,
+      `second call status=${replay.status} body=${JSON.stringify(replay.body)} (expected 409)`,
+    )
+
+    const baselineRowAfter = await sdk.api.automated_actions.getOne(baselineRow.id)
+    record(
+      'C2: a processed row is marked finished so neither a replay nor the worker re-runs it',
+      baselineRowAfter.status === 'finished',
+      `status=${baselineRowAfter.status} (expected finished)`,
+    )
+
+    /* ===== report: print full table first, then assert (harness exits on first failure) ===== */
+    console.log('\n  F-0192 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 {
+    // Reverse order. The automated_actions go first: they hang off enduserId with
+    // onDependencyDelete 'delete', so deleting the enduser would take them with it.
+    for (const id of automatedActionIds) { try { await sdk.api.automated_actions.deleteOne(id) } catch {} }
+    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 automated_actions_process_gate_tests({ sdk, sdkNonAdmin })
+  }
+
+  runTests()
+    .then(() => {
+      console.log("✅ F-0192 automated_actions.process gate test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ F-0192 automated_actions.process gate test suite failed:", error)
+      process.exit(1)
+    })
+}