@tellescope/sdk 1.256.0 → 1.256.2

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

@@ -0,0 +1,417 @@
+require('source-map-support').install();
+
+import axios from "axios"
+
+import { Session, EnduserSession } from "../../sdk"
+import {
+  assert,
+  log_header,
+} from "@tellescope/testing"
+import { setup_tests } from "../setup"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+
+/**
+ * {{enduser.embeddablesAuthToken}} — a 24h, path-confined enduser token that can be spliced into a
+ * third-party URL by a message author.
+ *
+ * The Embeddables handoff: Tellescope messages a patient a link to an Embeddables-hosted page with an
+ * enduser token in the URL; that page reads the patient's own record with it, refreshes it on load, and
+ * falls back to the existing OTP flow once it has expired.
+ *
+ * Everything here renders through POST /v1/templated-message, which runs the real
+ * process_message -> getTemplatedData path — the same code a real send uses, including the
+ * login_enduser minting branch. No messages are sent.
+ *
+ * Two facts the assertions rest on:
+ *  - a BARE url/token is not shortened (only the {url}[text] syntax becomes a /r/<token> redirect), so
+ *    the raw JWT lands in `plaintext` and is directly readable — unlike {{portal.link...}}, whose token
+ *    the shortener swallows.
+ *  - decoding needs no dependency: the test asserts on CLAIMS, never on signature validity.
+ */
+
+const decodeJwt = (jwt: string) => {
+  const [, payload] = jwt.split('.')
+  if (!payload) throw new Error(`not a JWT: ${jwt}`)
+  return JSON.parse(Buffer.from(payload, 'base64url').toString()) as {
+    id: string,
+    type: string,
+    businessId: string,
+    sessionScopes?: string[],
+    iat: number,
+    exp: number,
+  }
+}
+
+const looksLikeJwt = (s: string) => s.split('.').length === 3 && s.split('.').every(p => !!p)
+
+const SECONDS_IN_DAY = 86400
+
+type ProbeMethod = 'get' | 'post' | 'patch' | 'delete'
+
+export const embeddables_auth_token_tests = async ({ sdk, sdkNonAdmin } : { sdk: Session, sdkNonAdmin: Session }) => {
+  log_header("Embeddables Auth Token Merge Field Tests")
+
+  const businessId = sdk.userInfo.businessId
+
+  // Probe with raw axios rather than the SDK: parseError (sdk/src/session.ts) discards the status code,
+  // and a confinement denial (403 Inaccessible) has to be told apart from a 401 or a permissions error.
+  const request = async (token: string, method: ProbeMethod, path: string, data?: any) => {
+    const r = await axios.request({
+      method,
+      url: `${host}/v1${path}`,
+      ...method === 'get' ? { params: data } : { data },
+      headers: { Authorization: `Bearer ${token}` },
+      validateStatus: () => true,
+    })
+    return { status: r.status, body: r.data }
+  }
+
+  const enduser = await sdk.api.endusers.createOne({
+    fname: 'Embeddables',
+    lname: 'Patient',
+    email: `embeddables-token-${Date.now()}@tellescope.com`,
+    phone: '+15555555555',
+  })
+  const otherEnduser = await sdk.api.endusers.createOne({
+    fname: 'Other',
+    lname: 'Patient',
+    email: `embeddables-other-${Date.now()}@tellescope.com`,
+    dateOfBirth: '01-01-1990',
+  })
+  // a tenant custom field with the same name as the merge field, to prove it cannot shadow it
+  const collisionEnduser = await sdk.api.endusers.createOne({
+    fname: 'Collision',
+    fields: { embeddablesAuthToken: 'SHOULD_NOT_APPEAR' },
+  })
+
+  try {
+    /* ------------------------------------------------------------------ *
+     * 5a. Minting and TTL, through the real templating pipeline
+     * ------------------------------------------------------------------ */
+
+    const render = async (message: string, o?: { enduserId?: string, caller?: Session }) => {
+      const caller = o?.caller ?? sdk
+      const r = await caller.api.templates.get_templated_message({
+        message,
+        enduserId: o?.enduserId ?? enduser.id,
+        userId: caller.userInfo.id,
+        channel: 'Chat',
+      })
+      return r.plaintext
+    }
+    const renderToken = async (message: string, o?: { enduserId?: string, caller?: Session }) => (
+      decodeJwt(await render(message, o))
+    )
+
+    const defaultToken = await renderToken('{{enduser.embeddablesAuthToken}}')
+    assert(
+      defaultToken.type === 'enduser',
+      `token type is '${defaultToken.type}', expected 'enduser'`,
+      'merge field mints an enduser token',
+    )
+    assert(
+      defaultToken.id === enduser.id,
+      `token id is '${defaultToken.id}', expected '${enduser.id}'`,
+      'token is bound to the templated enduser',
+    )
+    assert(
+      defaultToken.businessId === businessId,
+      `token businessId is '${defaultToken.businessId}', expected '${businessId}'`,
+      'token carries the correct businessId',
+    )
+    assert(
+      JSON.stringify(defaultToken.sessionScopes) === JSON.stringify(['embeddables-token']),
+      `sessionScopes is ${JSON.stringify(defaultToken.sessionScopes)}, expected ["embeddables-token"]`,
+      'token is confined to exactly the embeddables-token scope',
+    )
+    assert(
+      defaultToken.exp - defaultToken.iat === SECONDS_IN_DAY,
+      `default TTL is ${defaultToken.exp - defaultToken.iat}s, expected ${SECONDS_IN_DAY}s`,
+      'default TTL is 24h, matching {{portal.link...}}',
+    )
+
+    const shortToken = await renderToken('{{enduser.embeddablesAuthToken:3600}}')
+    assert(
+      shortToken.exp - shortToken.iat === 3600,
+      `configured TTL is ${shortToken.exp - shortToken.iat}s, expected 3600s`,
+      'a caller-specified TTL is honored',
+    )
+
+    // At MINT TIME only. The scope grants refresh, and refresh mints max(remaining, 4h) with no absolute
+    // ceiling, so a sub-4h TTL is floored to 4h on first refresh and the session can slide indefinitely.
+    // Inherited from how every enduser link token works (including the 24h {{portal.link}}) — see the
+    // comment at the cap in message_templating.ts. This asserts the cap, not a lifetime guarantee.
+    const cappedToken = await renderToken('{{enduser.embeddablesAuthToken:999999}}')
+    assert(
+      cappedToken.exp - cappedToken.iat === SECONDS_IN_DAY,
+      `capped TTL is ${cappedToken.exp - cappedToken.iat}s, expected ${SECONDS_IN_DAY}s`,
+      'the 24h cap holds — the minted TTL is configurable downward only',
+    )
+
+    // garbage must fall back to the default: not NaN, not a thrown error, not an empty string
+    for (const ttl of ['abc', '-5', '0']) {
+      const fallback = await renderToken(`{{enduser.embeddablesAuthToken:${ttl}}}`)
+      assert(
+        fallback.exp - fallback.iat === SECONDS_IN_DAY,
+        `TTL ':${ttl}' produced ${fallback.exp - fallback.iat}s, expected a ${SECONDS_IN_DAY}s fallback`,
+        `an unparseable TTL (':${ttl}') falls back to 24h`,
+      )
+    }
+
+    // the literal Embeddables use case: the token spliced into a third-party URL
+    const inURL = await render('https://example.com/?token={{enduser.embeddablesAuthToken}}')
+    const urlPrefix = 'https://example.com/?token='
+    assert(
+      inURL.startsWith(urlPrefix),
+      `rendered URL was '${inURL}'`,
+      'the token substitutes inline into an arbitrary URL',
+    )
+    assert(
+      !inURL.includes('/r/'),
+      `rendered URL was shortened: '${inURL}'`,
+      'a bare URL is not run through the link shortener',
+    )
+    assert(
+      decodeJwt(inURL.slice(urlPrefix.length)).id === enduser.id,
+      'the JWT spliced into the URL did not decode to this enduser',
+      'the JWT survives intact inside the URL',
+    )
+
+    const collisionRendered = await render(
+      '{{enduser.embeddablesAuthToken}}',
+      { enduserId: collisionEnduser.id },
+    )
+    assert(
+      !collisionRendered.includes('SHOULD_NOT_APPEAR') && looksLikeJwt(collisionRendered),
+      `custom field shadowed the merge field: '${collisionRendered}'`,
+      'a tenant custom field named embeddablesAuthToken cannot shadow the merge field',
+    )
+    assert(
+      decodeJwt(collisionRendered).id === collisionEnduser.id,
+      'the collision-guard render did not decode to a JWT for that enduser',
+      'the collision-guard render is a real token',
+    )
+
+    // the new field.split(':') runs on EVERY enduser merge field — a regression there would silently
+    // truncate ordinary field names, so pin that they still resolve
+    const mixed = await render('{{enduser.fname}}|{{enduser.embeddablesAuthToken}}')
+    const [renderedFname, mixedToken] = mixed.split('|')
+    assert(
+      renderedFname === 'Embeddables',
+      `expected fname 'Embeddables', got '${renderedFname}'`,
+      'ordinary enduser merge fields still resolve alongside the new one',
+    )
+    assert(
+      looksLikeJwt(mixedToken ?? ''),
+      `expected a JWT after the fname, got '${mixedToken}'`,
+      'the token still renders when combined with other fields',
+    )
+
+    /* ------------------------------------------------------------------ *
+     * 5b. The scope grants exactly what it should
+     * ------------------------------------------------------------------ */
+
+    const scopedAuthToken = await render('{{enduser.embeddablesAuthToken}}')
+    const scopedSession = new EnduserSession({ host, businessId, authToken: scopedAuthToken })
+
+    const ownRead = await request(scopedAuthToken, 'get', `/enduser/${enduser.id}`)
+    assert(
+      ownRead.status === 200 && ownRead.body?.id === enduser.id,
+      `own-record read returned ${ownRead.status}: ${JSON.stringify(ownRead.body)}`,
+      'the token reads its own enduser record (GET /enduser/:id)',
+    )
+
+    // getOne(id) is the singular read the SDK's findById routes to. NOT the bulk path —
+    // findById(id, { batch: true }) hits /endusers/bulk-read, a different grant that is deliberately
+    // outside this scope (see the trap documented at session_scopes.ts:33-38)
+    const ownReadViaSDK = await scopedSession.api.endusers.getOne(enduser.id)
+    assert(
+      ownReadViaSDK?.id === enduser.id,
+      `SDK getOne returned ${JSON.stringify(ownReadViaSDK)}`,
+      'the SDK singular-read path works with the token',
+    )
+
+    const bulkRead = await request(scopedAuthToken, 'post', '/endusers/bulk-read', { ids: [enduser.id] })
+    assert(
+      bulkRead.status === 403,
+      `bulk-read returned ${bulkRead.status}, expected 403`,
+      'findById({ batch: true }) is NOT granted — bulk-read is a separate route',
+    )
+
+    // ESCALATION CHECK. If the scope dropped on refresh, a 24h URL token would upgrade itself into a
+    // full portal session and the entire design would leak.
+    const refreshed = await scopedSession.refresh_session()
+    const refreshedClaims = decodeJwt(refreshed.authToken)
+    assert(
+      JSON.stringify(refreshedClaims.sessionScopes) === JSON.stringify(['embeddables-token']),
+      `refreshed token sessionScopes is ${JSON.stringify(refreshedClaims.sessionScopes)}`,
+      'refresh_session preserves the confinement — no escalation via refresh',
+    )
+    assert(
+      refreshedClaims.id === enduser.id,
+      `refreshed token id is '${refreshedClaims.id}'`,
+      'refresh_session returns a token for the same enduser',
+    )
+
+    // Each entry pins the status of the layer that actually stops it, because two different layers do.
+    // 403 Inaccessible is the scope confinement (checkAccess -> isPathAllowed) and is what everything an
+    // enduser session type can reach at all returns. load-inbox-data is staff-only — it has no entry in
+    // endusers.enduserActions, so its checkAccess is built with allowEnduser: false (routing.ts:913) and
+    // an enduser token is rejected as unauthenticated before the confinement is ever consulted. That 401
+    // is a stricter denial, not a weaker one; it is pinned as 401 so that a later change making the route
+    // enduser-reachable surfaces here rather than passing silently on the confinement fallback.
+    const denied: [string, ProbeMethod, string, any, number][] = [
+      // deliberately ungranted: it returns only the decoded token the caller already holds. Asserting
+      // the 403 means a future widening has to be a conscious edit.
+      ['current_session_info', 'get', '/enduser-session-info', undefined, 403],
+      // no write grant at all — and email/phone are login channels (password reset resolves by email,
+      // OTP delivers to phone), so specifically confirm they cannot be repointed
+      ['updateOne (fname)', 'patch', `/enduser/${enduser.id}`, { updates: { fname: 'Hacked' } }, 403],
+      ['updateOne (email)', 'patch', `/enduser/${enduser.id}`, { updates: { email: 'attacker@example.com' } }, 403],
+      ['updateOne (phone)', 'patch', `/enduser/${enduser.id}`, { updates: { phone: '+15550001111' } }, 403],
+      ['chat_rooms.getSome', 'get', '/chat-rooms', undefined, 403],
+      ['load_inbox_data', 'get', '/endusers/load-inbox-data', { limit: 10 }, 401],
+      ['endusers.getSome (readMany)', 'get', '/endusers', undefined, 403],
+      // THE FILTER ORACLE. The bare singular-read route is the same handler as /enduser/:id, but with no
+      // path id it evaluates a caller-supplied filter against UNREDACTED records and answers 200 on match
+      // / 400 on miss — a per-field probe over every enduser in the business (applyRedactions strips the
+      // response body, never the filter). Both syntaxes are asserted because dropping mdbFilter alone
+      // would not close it: `filter`'s _gt/_lt/_in operators binary-search a value just as well. A 403
+      // here means the route is unreachable, not that one filter shape was rejected.
+      ['bare read (filter oracle)', 'get', '/enduser', { filter: { fname: 'Other' } }, 403],
+      ['bare read (mdbFilter oracle)', 'get', '/enduser', { mdbFilter: { fname: { $regex: '^Oth' } } }, 403],
+    ]
+    for (const [label, method, path, data, expected] of denied) {
+      const r = await request(scopedAuthToken, method, path, data)
+      assert(
+        r.status === expected,
+        `${label} returned ${r.status}: ${JSON.stringify(r.body)} — expected ${expected}`,
+        `denied: ${label} (${expected})`,
+      )
+    }
+
+    // the write really did not land
+    const afterWriteAttempts = await sdk.api.endusers.getOne(enduser.id)
+    assert(
+      afterWriteAttempts.fname === 'Embeddables' && afterWriteAttempts.phone === '+15555555555',
+      `record was mutated: ${JSON.stringify({ fname: afterWriteAttempts.fname, phone: afterWriteAttempts.phone })}`,
+      'no denied write reached the record',
+    )
+
+    // CROSS-PATIENT READ. get:/enduser/:id cannot be pinned (the id lives in the token, not in
+    // scopeContext), so this is route-allowed and will not 403. What stops it is applyRedactions
+    // reducing a foreign enduser to { id, displayName, unredactedFields, unredactedTags }. This is the
+    // PHI-egress assertion — the one place the :id wildcard could bite.
+    const crossRead = await request(scopedAuthToken, 'get', `/enduser/${otherEnduser.id}`)
+    const leaked = ['email', 'phone', 'dateOfBirth', 'fields', 'fname', 'lname']
+      .filter(k => crossRead.status === 200 && crossRead.body?.[k] !== undefined)
+    assert(
+      leaked.length === 0,
+      `cross-patient read (status ${crossRead.status}) leaked: ${leaked.join(', ')}`,
+      'a cross-patient read is reduced to non-PHI display fields',
+    )
+
+    /* ------------------------------------------------------------------ *
+     * 5c. Invalidation behaves as recommended to Embeddables
+     *
+     * They were told to burn the URL token on page load via
+     * refresh_session({ invalidatePreviousToken: true }), so pin that contract.
+     * ------------------------------------------------------------------ */
+
+    const tokenA = await render('{{enduser.embeddablesAuthToken}}')
+    const sessionA = new EnduserSession({ host, businessId, authToken: tokenA })
+
+    const preBurn = await request(tokenA, 'get', `/enduser/${enduser.id}`)
+    assert(preBurn.status === 200, `token A read returned ${preBurn.status}`, 'token A reads its own record before the burn')
+
+    // a separately-minted session for the same enduser — the control proving the blocklist is
+    // per-credential and not a blanket logout that would kick the patient out of the portal
+    const { authToken: portalToken } = await sdk.api.endusers.generate_auth_token({ id: enduser.id })
+
+    const { authToken: tokenB } = await sessionA.refresh_session({ invalidatePreviousToken: true })
+
+    const postBurnA = await request(tokenA, 'get', `/enduser/${enduser.id}`)
+    assert(
+      postBurnA.status === 401,
+      `token A returned ${postBurnA.status} after the burn, expected 401`,
+      'invalidatePreviousToken blocklists token A (401)',
+    )
+    // note: the body here is plain text 'Unauthenticated', not JSON — do not JSON.parse it
+
+    const postBurnB = await request(tokenB, 'get', `/enduser/${enduser.id}`)
+    assert(
+      postBurnB.status === 200,
+      `token B returned ${postBurnB.status} after the burn, expected 200`,
+      'token B still works after the burn',
+    )
+
+    const postBurnPortal = await request(portalToken, 'get', `/enduser/${enduser.id}`)
+    assert(
+      postBurnPortal.status === 200,
+      `separately-minted session returned ${postBurnPortal.status}, expected 200`,
+      'the burn is a per-token blocklist, not a blanket logout of the patient',
+    )
+
+    /* ------------------------------------------------------------------ *
+     * 5d. The OTP fallback is still reachable from a dead token
+     *
+     * The whole Embeddables fallback rests on this: otp-methods only jwtDecodes the token and never
+     * verifies it, so expiry and invalidation are both irrelevant to it. Read-only, sends nothing.
+     *
+     * Deliberately not covered: send-otp-code / verify-otp-code. send_otp dispatches a real email/SMS,
+     * so it stays out of the automated suite — and neither endpoint is changed by this work.
+     * ------------------------------------------------------------------ */
+
+    const otpMethods = await new EnduserSession({ host, businessId }).api.endusers.get_otp_methods({ token: tokenA })
+    assert(
+      otpMethods.methods.includes('email') && otpMethods.methods.includes('sms'),
+      `otp methods for an invalidated token: ${JSON.stringify(otpMethods.methods)}`,
+      'otp-methods still resolves from an invalidated token (the OTP fallback stays reachable)',
+    )
+
+    /* ------------------------------------------------------------------ *
+     * 5e. Access control on rendering
+     *
+     * get_templated_message is not admin-gated; it requires templates.read + endusers.read, hand-checked
+     * in its handler. A non-admin rendering this field is INTENTIONAL — any staff user who can already
+     * render {{portal.link...}} through this endpoint can already mint a patient token, so the merge
+     * field adds no new privilege. Asserted so that decision stays visible rather than implicit.
+     * ------------------------------------------------------------------ */
+
+    const nonAdminToken = await renderToken('{{enduser.embeddablesAuthToken}}', { caller: sdkNonAdmin })
+    assert(
+      nonAdminToken.id === enduser.id
+        && JSON.stringify(nonAdminToken.sessionScopes) === JSON.stringify(['embeddables-token']),
+      `non-admin render produced ${JSON.stringify(nonAdminToken)}`,
+      'a non-admin with templates.read + endusers.read can render the field (intentional)',
+    )
+  } finally {
+    await Promise.all([
+      sdk.api.endusers.deleteOne(enduser.id).catch(() => {}),
+      sdk.api.endusers.deleteOne(otherEnduser.id).catch(() => {}),
+      sdk.api.endusers.deleteOne(collisionEnduser.id).catch(() => {}),
+    ])
+  }
+}
+
+// Allow running this test file independently
+if (require.main === module) {
+  const sdk = new Session({ host })
+  const sdkNonAdmin = new Session({ host })
+
+  const runTests = async () => {
+    await setup_tests(sdk, sdkNonAdmin)
+    await embeddables_auth_token_tests({ sdk, sdkNonAdmin })
+  }
+
+  runTests()
+    .then(() => {
+      console.log("✅ Embeddables auth token test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ Embeddables auth token test suite failed:", error)
+      process.exit(1)
+    })
+}