@tellescope/sdk 1.256.15 → 1.256.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tellescope/sdk",
-  "version": "1.256.15",
+  "version": "1.256.16",
   "description": "Code for interacting with the Tellescope API",
   "main": "./lib/cjs/sdk.js",
   "module": "./lib/esm/sdk.js",
@@ -32,14 +32,14 @@
   },
   "homepage": "https://github.com/tellescope-os/tellescope#readme",
   "dependencies": {
-    "@tellescope/constants": "1.256.15",
-    "@tellescope/schema": "1.256.15",
-    "@tellescope/testing": "1.256.15",
-    "@tellescope/types-client": "1.256.15",
-    "@tellescope/types-models": "1.256.15",
-    "@tellescope/types-utilities": "1.256.15",
-    "@tellescope/utilities": "1.256.15",
-    "@tellescope/validation": "1.256.15",
+    "@tellescope/constants": "1.256.16",
+    "@tellescope/schema": "1.256.16",
+    "@tellescope/testing": "1.256.16",
+    "@tellescope/types-client": "1.256.16",
+    "@tellescope/types-models": "1.256.16",
+    "@tellescope/types-utilities": "1.256.16",
+    "@tellescope/utilities": "1.256.16",
+    "@tellescope/validation": "1.256.16",
     "axios": "0.30.3",
     "dotenv": "14.3.2",
     "form-data": "4.0.4",
@@ -55,5 +55,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "180f82301125bdd5e73608991061e49ed3d41e96"
+  "gitHead": "5874f0e4ca75d8ce70768a5933cd5bb5b3b15c58"
 }

package/src/tests/api_tests/security/file-link-session-confinement.test.ts

@@ -0,0 +1,291 @@
+require('source-map-support').install();
+
+import axios from "axios"
+
+import {
+  assert_checks,
+  Check,
+  setup_isolated_tenant,
+} from "../../setup_isolated"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+
+const RAND = () => Math.random().toString(36).slice(2, 10)
+
+/**
+ * The `{{files.<id>.link}}` merge field must mint a session that can download ONE file, and nothing
+ * else.
+ *
+ * That merge field is how the webapp's "Generate PDF -> Save and Share -> Email" flow on the enduser
+ * timeline (DownloadFormResponse.tsx, ComposeSharePDFEmail) delivers a document to a hand-typed
+ * address — a referral contact, a caregiver, an outside provider. The link is resolved at send time
+ * by message_templating.ts, which called login_enduser with no confinement at all, so the recipient
+ * received a full 24-hour patient-portal session: chat history, every form response, every file,
+ * observations, medications, and every write route including PATCH /enduser/:id.
+ *
+ * Route access was not the only leak. Both portals call refresh-enduser-session during URL-token
+ * intake, and for a session not flagged `fromPublicSession` that handler returns the whole patient
+ * document (name, dateOfBirth, email, phone, insurance, fields, notes) — so the chart was handed
+ * over on page load, before a single route was touched. Probe 7b covers that.
+ *
+ * Two variants, because one bit — is the recipient the patient? — drives two behaviours the merge
+ * field previously could not express:
+ *
+ *   `link`         goes to the patient. Keeps the org's MFA policy, keeps OTP recovery.
+ *   `shared-link`  goes to someone who is NOT the patient. An OTP code is delivered to the PATIENT's
+ *                  own email or phone, so for this variant recovery is both unanswerable by the
+ *                  holder and a way to make the platform message the patient on demand. It is
+ *                  refused, and the token is minted bypassMFA so it never needs a challenge either.
+ *
+ * Probe 12 is the one that decides whether the OTP rule is real: the three OTP endpoints read their
+ * `token` argument with `jwtDecode`, which does not verify the signature. The file link puts a
+ * decodable JWT in the recipient's URL bar, so they know the enduser id, and a scope name in an
+ * unverified token is a suggestion rather than a claim. Without signature verification the rule is
+ * a paper wall.
+ *
+ * Every confinement probe is paired against the tenant's own admin session, so a red check means
+ * confinement rather than a broken fixture.
+ */
+
+type Probe = { status: number, body: any }
+
+const probe = async (
+  method: 'get' | 'post' | 'patch',
+  path: string,
+  o: { token?: string, params?: object, data?: object } = {},
+): Promise<Probe> => {
+  const r = await axios.request({
+    method,
+    url: `${host}/v1${path}`,
+    params: o.params,
+    data: o.data,
+    headers: o.token ? { Authorization: `Bearer ${o.token}` } : undefined,
+    validateStatus: () => true,
+  })
+  return { status: r.status, body: r.data }
+}
+
+export const file_link_session_confinement_checks = async (): Promise<Check[]> => {
+  const checks: Check[] = []
+  const record = (label: string, pass: boolean, detail: string) => checks.push({ label, pass, detail })
+
+  let tenant: Awaited<ReturnType<typeof setup_isolated_tenant>> | undefined
+
+  try {
+    tenant = await setup_isolated_tenant({
+      name: `FileLink ${RAND()}`, users: [{ isAdmin: true }], apiKeys: 0,
+    })
+    const sdk = tenant.sdk
+
+    // dontsend- so the OTP probes cannot deliver anything real, same convention the provisioner uses
+    const enduser = await sdk.api.endusers.createOne({
+      fname: 'FileLink', lname: 'Recipient',
+      email: `dontsend-filelink-${RAND()}@tellescope.com`,
+      phone: '+15555550100',
+      dateOfBirth: '01-01-1990',
+    })
+
+    // No S3 upload needed: prepare_file_upload inserts the files record with its secureName
+    // immediately, and file_download_URL only SIGNS a GET url — it never checks the object exists.
+    const newFile = async (name: string) => (
+      (await sdk.api.files.prepare_file_upload({
+        name, type: 'application/pdf', size: 1000, enduserId: enduser.id,
+      })).file
+    )
+    const fileA = await newFile(`shared-${RAND()}.pdf`)   // the one that gets shared
+    const fileB = await newFile(`private-${RAND()}.pdf`)  // the rest of the patient's chart
+
+    /**
+     * Mints a token exactly the way a real send does — get_templated_message is the endpoint the
+     * worker calls (worker/app.js handleOutgoingEmail).
+     *
+     * replaceLinks always rewrites the resolved link into a tracking redirect, so `plaintext` holds
+     * `doc (${API_URL}/r/<redirectToken>)` rather than the portal URL. Follow the 302 to recover it.
+     */
+    const mint = async (verb: 'link' | 'shared-link') => {
+      const { plaintext } = await sdk.api.templates.get_templated_message({
+        channel: 'Email',
+        userId: tenant!.users[0].id,
+        enduserId: enduser.id,
+        message: `{{files.${fileA.id}.${verb}:doc}}`,
+      })
+
+      const redirectURL = plaintext.match(/\((https?:\/\/[^)\s]+)\)/)?.[1]
+      if (!redirectURL) return { token: undefined, detail: `no link resolved from: ${plaintext}` }
+
+      const r = await axios.get(redirectURL, { maxRedirects: 0, validateStatus: () => true })
+      const location = r.headers['location']
+      if (!location) return { token: undefined, detail: `redirect did not 302 (${r.status})` }
+
+      const token = new URL(location).searchParams.get('token') ?? undefined
+      return { token, detail: token ? 'minted' : `no token in ${location}` }
+    }
+
+    /* ================================ confinement + the pin ================================ */
+
+    // Positive control first: the admin session reads both files fine, so a 403 below is confinement.
+    const adminFiles = await probe('get', '/files', { token: tenant.users[0].authToken })
+    record(
+      'control: admin session lists files',
+      adminFiles.status === 200, `status ${adminFiles.status}`,
+    )
+
+    const confinement_probes = async (variant: 'link' | 'shared-link', token: string) => {
+      const p = (label: string, expected: number, r: Probe) => record(
+        `${variant} — ${label}`, r.status === expected, `status ${r.status} (expected ${expected})`,
+      )
+
+      p('1: downloads the shared file', 200,
+        await probe('get', '/file-download-URL', { token, params: { secureName: fileA.secureName } }))
+
+      p('2: cannot download another file on the same patient', 403,
+        await probe('get', '/file-download-URL', { token, params: { secureName: fileB.secureName } }))
+
+      // validateInput merges query, then body, then params — body wins over query, so a pin checked
+      // against req.query rather than req.validated would be sidesteppable exactly like this.
+      p('3: cannot smuggle another secureName through the body', 403,
+        await probe('get', '/file-download-URL', {
+          token, params: { secureName: fileA.secureName }, data: { secureName: fileB.secureName },
+        }))
+
+      // a listing would turn the pin into a directory of the patient's chart
+      p('4: cannot list files', 403, await probe('get', '/files', { token }))
+
+      p('5a: cannot read chats', 403, await probe('get', '/chats', { token }))
+      p('5b: cannot read form responses', 403, await probe('get', '/form-responses', { token }))
+      p('5c: cannot read observations', 403, await probe('get', '/enduser-observations', { token }))
+
+      p('6: cannot update the patient', 403,
+        await probe('patch', `/enduser/${enduser.id}`, { token, data: { updates: { fname: 'Overwritten' } } }))
+
+      const refreshed = await probe('post', '/refresh-enduser-session', { token })
+      p('7: can refresh its own session', 200, refreshed)
+
+      // 7b — the refresh payload must be the fromPublicSession shape, not the whole chart
+      const leaked = ['dateOfBirth', 'email', 'phone', 'fields', 'insurance', 'lname']
+        .filter(f => (refreshed.body?.enduser ?? {})[f] !== undefined)
+      record(
+        `${variant} — 7b: refresh response withholds patient fields`,
+        refreshed.status === 200 && leaked.length === 0,
+        leaked.length ? `leaked: ${leaked.join(', ')}` : 'no patient fields in payload',
+      )
+
+      // 8 — confinement has to survive the re-mint, or one refresh launders it away
+      const refreshedToken = refreshed.body?.authToken
+      if (typeof refreshedToken === 'string' && refreshedToken) {
+        p('8a: refreshed token still cannot download another file', 403,
+          await probe('get', '/file-download-URL', {
+            token: refreshedToken, params: { secureName: fileB.secureName },
+          }))
+        p('8b: refreshed token still cannot update the patient', 403,
+          await probe('patch', `/enduser/${enduser.id}`, {
+            token: refreshedToken, data: { updates: { fname: 'Overwritten' } },
+          }))
+      } else {
+        record(`${variant} — 8: refreshed token available`, false, 'refresh returned no authToken')
+      }
+    }
+
+    const plain = await mint('link')
+    if (plain.token) {
+      await confinement_probes('link', plain.token)
+    } else {
+      record('link — minted', false, plain.detail)
+    }
+
+    const shared = await mint('shared-link')
+    if (shared.token) {
+      await confinement_probes('shared-link', shared.token)
+    } else {
+      // Before the shared-link verb exists the merge field does not resolve. Record it and skip the
+      // shared probes rather than throwing, so the first run reports the whole picture at once.
+      record('shared-link — minted', false, shared.detail)
+    }
+
+    /* ========================================= OTP ========================================= */
+
+    if (shared.token) {
+      const methods = await probe('get', '/endusers/otp-methods', { params: { token: shared.token } })
+      record(
+        'shared-link — 9: OTP methods are not offered',
+        methods.status === 403, `status ${methods.status} (expected 403)`,
+      )
+
+      const send = await probe('post', '/endusers/send-otp-code', {
+        data: { token: shared.token, method: 'email' },
+      })
+      record(
+        'shared-link — 10: cannot make us send the patient a login code',
+        send.status === 403, `status ${send.status} (expected 403)`,
+      )
+
+      // rejected on scope BEFORE the code lookup, so it is not an oracle on code validity
+      const verify = await probe('post', '/endusers/verify-otp-code', {
+        data: { token: shared.token, code: '000000' },
+      })
+      record(
+        'shared-link — 11: OTP verification refuses the scope before checking the code',
+        verify.status === 403, `status ${verify.status} (expected 403, 400 = reached the code check)`,
+      )
+
+      // 12 — the same call with the scope claim stripped and the signature broken. The OTP endpoints
+      // jwtDecode without verifying, so without signature verification this sails straight through
+      // and every check above is decorative.
+      const [header, payload] = shared.token.split('.')
+      const decoded = JSON.parse(Buffer.from(payload, 'base64url').toString())
+      delete decoded.sessionScopes
+      delete decoded.scopeContext
+      const forged = [
+        header,
+        Buffer.from(JSON.stringify(decoded)).toString('base64url'),
+        'not-a-real-signature',
+      ].join('.')
+
+      const forgedSend = await probe('post', '/endusers/send-otp-code', {
+        data: { token: forged, method: 'email' },
+      })
+      record(
+        'shared-link — 12: a forged token cannot strip the scope to unlock OTP',
+        forgedSend.status === 403 || forgedSend.status === 401 || forgedSend.status === 404,
+        `status ${forgedSend.status} (expected 401/403/404; 204 = signature never verified)`,
+      )
+    }
+
+    if (plain.token) {
+      // 13 — the patient-facing variant must keep its recovery path. Deliverable to a dontsend-
+      // address, so nothing leaves the system.
+      const send = await probe('post', '/endusers/send-otp-code', {
+        data: { token: plain.token, method: 'email' },
+      })
+      record(
+        'link — 13: patient OTP recovery still works',
+        send.status === 204, `status ${send.status} (expected 204)`,
+      )
+    }
+  } finally {
+    // Teardown BEFORE anything asserts — assert calls process.exit, which skips pending finallys and
+    // would strand the provisioned tenant permanently.
+    if (tenant) { try { await tenant.teardown() } catch (e) { console.error('teardown failed', e) } }
+  }
+
+  return checks
+}
+
+/** Asserting wrapper, for standalone runs and for sequential use in the suite. */
+export const file_link_session_confinement_tests = async () => {
+  assert_checks('Shared file link session confinement', await file_link_session_confinement_checks())
+}
+
+// Allow running this test file independently
+if (require.main === module) {
+  console.log(`🌐 Using API URL: ${host}`)
+  file_link_session_confinement_tests()
+    .then(() => {
+      console.log("✅ file link session confinement test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ file link session confinement test suite failed:", error)
+      process.exit(1)
+    })
+}

package/src/tests/tests.ts

@@ -163,6 +163,7 @@ import { organization_signup_checks } from "./api_tests/organization_signup.test
 import { add_to_journey_foreign_enduserid_checks } from "./api_tests/security/add-to-journey-foreign-enduserid.test";
 import { tickets_bulk_assign_from_queue_checks } from "./api_tests/tickets_bulk_assign_from_queue.test";
 import { enduser_observations_auto_review_checks } from "./api_tests/enduser_observations_auto_review.test";
+import { file_link_session_confinement_checks } from "./api_tests/security/file-link-session-confinement.test";
 import { run_isolated_in_parallel } from "./setup_isolated";
 import { elation_user_id_tests } from "./api_tests/elation_user_id.test";
 import { organization_settings_duplicates_tests } from "./api_tests/organization_settings_duplicates.test";
@@ -15405,6 +15406,7 @@ const ip_address_form_tests = async () => {
       { name: 'Tickets bulk assign from queue', run: tickets_bulk_assign_from_queue_checks },
       { name: 'Vital auto-review on create', run: enduser_observations_auto_review_checks },
       { name: '$JS in stored conditional logic', run: form_logic_js_execution_checks },
+      { name: 'Shared file link session confinement', run: file_link_session_confinement_checks },
     ])
     await embeddables_auth_token_tests({ sdk, sdkNonAdmin })
     await proxy_image_ssrf_tests({ sdk, sdkNonAdmin })