@tellescope/sdk 1.256.15 → 2.0.0-beta.0

package/package.json

@@ -1,25 +1,25 @@
 {
   "name": "@tellescope/sdk",
-  "version": "1.256.15",
+  "version": "2.0.0-beta.0",
   "description": "Code for interacting with the Tellescope API",
   "main": "./lib/cjs/sdk.js",
   "module": "./lib/esm/sdk.js",
   "types": "./lib/esm/sdk.d.ts",
   "scripts": {
-    "test": "npm run-script build:cjs && npm run-script retest",
+    "test": "npm run-script build:cjs && node ../../../scripts/dev/check-build-fresh.mjs && npm run-script retest",
     "retest": "npm run-script retest-api && npm run-script retest-public-api && npm run-script retest-webhooks",
-    "test-api": "npm run-script build:cjs && npm run-script retest-api",
+    "test-api": "npm run-script build:cjs && node ../../../scripts/dev/check-build-fresh.mjs && npm run-script retest-api",
     "retest-api": "node -r dotenv/config lib/cjs/tests/tests.js",
-    "test-public-api": "npm run-script build:cjs && npm run-script retest-public-api",
+    "test-public-api": "npm run-script build:cjs && node ../../../scripts/dev/check-build-fresh.mjs && npm run-script retest-public-api",
     "retest-public-api": "node -r dotenv/config lib/cjs/tests/public_endpoint_tests.js",
-    "test-sockets": "npm run-script build:cjs && npm run-script retest-sockets",
+    "test-sockets": "npm run-script build:cjs && node ../../../scripts/dev/check-build-fresh.mjs && npm run-script retest-sockets",
     "retest-sockets": "node -r dotenv/config lib/cjs/tests/socket_tests.js",
-    "test-webhooks": "npm run-script build:cjs && npm run-script retest-webhooks",
+    "test-webhooks": "npm run-script build:cjs && node ../../../scripts/dev/check-build-fresh.mjs && npm run-script retest-webhooks",
     "retest-webhooks": "node -r dotenv/config lib/cjs/tests/webhooks_tests.js",
     "build": "npm run-script build:esm && npm run-script build:cjs",
     "build:esm": "tsc",
-    "build:cjs": "tsc --module commonjs --outDir lib/cjs",
-    "watch:cjs": "tsc --module commonjs --outDir lib/cjs --watch"
+    "build:cjs": "tsc -b tsconfig.cjs.json",
+    "watch:cjs": "tsc -b -w --preserveWatchOutput tsconfig.cjs.json"
   },
   "repository": {
     "type": "git",
@@ -31,18 +31,21 @@
     "url": "https://github.com/tellescope-os/tellescope/issues"
   },
   "homepage": "https://github.com/tellescope-os/tellescope#readme",
+  "engines": {
+    "node": ">=22.12.0"
+  },
   "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",
-    "axios": "0.30.3",
+    "@tellescope/constants": "2.0.0-beta.0",
+    "@tellescope/schema": "2.0.0-beta.0",
+    "@tellescope/testing": "2.0.0-beta.0",
+    "@tellescope/types-client": "2.0.0-beta.0",
+    "@tellescope/types-models": "2.0.0-beta.0",
+    "@tellescope/types-utilities": "2.0.0-beta.0",
+    "@tellescope/utilities": "2.0.0-beta.0",
+    "@tellescope/validation": "2.0.0-beta.0",
+    "axios": "0.33.0",
     "dotenv": "14.3.2",
-    "form-data": "4.0.4",
+    "form-data": "4.0.6",
     "source-map-support": "0.5.21"
   },
   "devDependencies": {
@@ -55,5 +58,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "180f82301125bdd5e73608991061e49ed3d41e96"
+  "gitHead": "95b2448bb219e7634e29ef4b7850f8f74d73dcbc"
 }

package/src/sdk.ts

@@ -313,6 +313,9 @@ type Queries = { [K in keyof ClientModelForName]: APIQuery<K> } & {
     get_form_statistics: (args: extractFields<CustomActions['forms']['get_form_statistics']['parameters']>) => (
       Promise<extractFields<CustomActions['forms']['get_form_statistics']['returns']>>
     ),
+    public_form_details: (args: extractFields<PublicActions['forms']['public_form_details']['parameters']>) => (
+      Promise<extractFields<PublicActions['forms']['public_form_details']['returns']>>
+    ),
   },
   phone_trees: {
     start_outbound_call: (args: extractFields<CustomActions['phone_trees']['start_outbound_call']['parameters']>) => (
@@ -1052,6 +1055,7 @@ export class Session extends SessionManager {
     queries.organizations.invite_user = a => this._POST(`/v1/${schema.users.customActions.invite_user.path}`, a) 
 
     queries.forms.get_form_statistics = args => this._GET(`/v1${schema.forms.customActions.get_form_statistics.path}`, args)
+    queries.forms.public_form_details = args => this._GET(`/v1${schema.forms.publicActions.public_form_details.path}`, args)
 
     queries.form_fields.load_choices_from_database = args => this._GET(`/v1${schema.form_fields.customActions.load_choices_from_database.path}`, args)
     queries.form_fields.booking_info = args => this._GET(`/v1${schema.form_fields.customActions.booking_info.path}`, args)
@@ -1350,4 +1354,4 @@ export class Session extends SessionManager {
   sync = (a: { from: Date }) => this.GET<typeof a, { results: Pick<DataSyncRecord, 'modelName' | 'recordId' | 'data'>[], to: string }>('/v1/data-sync', a)
 }
 
-export { SessionOptions }
+export type { SessionOptions }

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

@@ -10,7 +10,7 @@ import {
 import { authenticate_enduser_via_token, setup_tests } from "../setup"
 
 const host = process.env.API_URL || 'http://localhost:8080' as const
-const businessId = '60398b1131a295e64f084ff6'
+const businessId = process.env.TEST_BUSINESS_ID || '60398b1131a295e64f084ff6'
 
 // Second-tenant session, used to prove the active patient count never crosses tenants.
 // Same key used by the org-isolation tests in tests.ts.

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

@@ -3,7 +3,7 @@ import { log_header, wait, async_test } from "@tellescope/testing"
 import { Enduser } from "@tellescope/types-client"
 import { setup_tests } from "../setup"
 
-const host = process.env.TEST_HOST || "http://localhost:8080"
+const host = process.env.API_URL || process.env.TEST_HOST || "http://localhost:8080"
 
 export const appointment_rescheduled_trigger_tests = async ({ sdk, sdkNonAdmin } : { sdk: Session, sdkNonAdmin: Session }) => {
   log_header("Automation Trigger Tests (Appointment Rescheduled)")

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

@@ -8,7 +8,7 @@ import {
 import { setup_tests, authenticate_enduser_via_token } from "../setup"
 
 const host = process.env.API_URL || 'http://localhost:8080' as const
-const businessId = '60398b1131a295e64f084ff6'
+const businessId = process.env.TEST_BUSINESS_ID || '60398b1131a295e64f084ff6'
 
 /**
  * CU-86e2dvrn9: calendar_events.references switched from updatesDisabled to

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

@@ -12,7 +12,7 @@ import { ModelName } from "@tellescope/types-models"
 import { authenticate_enduser_via_token, setup_tests } from "../setup"
 
 const host = process.env.API_URL || 'http://localhost:8080' as const
-const businessId = '60398b1131a295e64f084ff6'
+const businessId = process.env.TEST_BUSINESS_ID || '60398b1131a295e64f084ff6'
 
 type OwnerField = 'enduserId' | 'enduserIds' | 'attendees.id'
 

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

@@ -6,7 +6,7 @@ import {
   async_test,
   log_header,
 } from "@tellescope/testing"
-import { setup_tests } from "../setup"
+import { reset_test_tenant, setup_tests } from "../setup"
 
 const host = process.env.API_URL || 'http://localhost:8080' as const
 
@@ -43,7 +43,7 @@ export const enduser_login_rate_limits_tests = async ({ sdk, sdkNonAdmin } : { s
   const businessId = sdk.userInfo.businessId
 
   // Ensure throttled_events from prior tests don't bleed in.
-  await sdk.reset_db()
+  await reset_test_tenant(sdk)
 
   // ---- /v1/login-enduser per-IP cap (20/min) ----
   // Bogus emails ensure we never reach the actual DB lookup / login work.
@@ -58,7 +58,7 @@ export const enduser_login_rate_limits_tests = async ({ sdk, sdkNonAdmin } : { s
     { expectedResult: 'tripped' }
   )
 
-  await sdk.reset_db()
+  await reset_test_tenant(sdk)
 
   // ---- /v1/begin-enduser-login-flow per-IP cap (10/min) ----
   // Use distinct emails so the per-identifier limit (5/10min) does NOT trip first;
@@ -73,7 +73,7 @@ export const enduser_login_rate_limits_tests = async ({ sdk, sdkNonAdmin } : { s
     { expectedResult: 'tripped' }
   )
 
-  await sdk.reset_db()
+  await reset_test_tenant(sdk)
 
   // ---- /v1/begin-enduser-login-flow per-identifier cap (5 / 10 min per email) ----
   // Hit a single email below the per-IP cap.
@@ -88,7 +88,7 @@ export const enduser_login_rate_limits_tests = async ({ sdk, sdkNonAdmin } : { s
     { expectedResult: 'tripped' }
   )
 
-  await sdk.reset_db()
+  await reset_test_tenant(sdk)
 
   // ---- /v1/endusers/send-otp-code per-IP cap (5/min) ----
   // Use a bogus JWT-shaped token so we trip the IP guard first (it runs before any DB work).
@@ -116,7 +116,7 @@ export const enduser_login_rate_limits_tests = async ({ sdk, sdkNonAdmin } : { s
 
   // ---- Legitimate-login regression: a single successful login should still go through ----
   // Reset state, then create a real enduser with a password and confirm one login succeeds.
-  await sdk.reset_db()
+  await reset_test_tenant(sdk)
 
   const ts = Date.now()
   const enduser = await sdk.api.endusers.createOne({
@@ -151,7 +151,7 @@ export const enduser_login_rate_limits_tests = async ({ sdk, sdkNonAdmin } : { s
     )
   } finally {
     await sdk.api.endusers.deleteOne(enduser.id).catch(() => null)
-    await sdk.reset_db().catch(() => null)
+    await reset_test_tenant(sdk).catch(() => null)
   }
 }
 

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

@@ -7,10 +7,10 @@ import {
   log_header,
   wait,
 } from "@tellescope/testing"
-import { setup_tests } from "../setup"
+import { reset_test_tenant, setup_tests } from "../setup"
 
 const host = process.env.API_URL || 'http://localhost:8080' as const
-const businessId = '60398b1131a295e64f084ff6'
+const businessId = process.env.TEST_BUSINESS_ID || '60398b1131a295e64f084ff6'
 
 // Main test function that can be called independently
 export const enduser_session_invalidation_tests = async ({ sdk, sdkNonAdmin } : { sdk: Session, sdkNonAdmin: Session }) => {
@@ -126,7 +126,7 @@ export const enduser_session_invalidation_tests = async ({ sdk, sdkNonAdmin } :
   }
 
   // Ensure OTP is off and db is clean before starting
-  await sdk.reset_db()
+  await reset_test_tenant(sdk)
   await wait(undefined, 500)
   await resetOTPSettings(sdk)
 
@@ -242,7 +242,7 @@ export const enduser_session_invalidation_tests = async ({ sdk, sdkNonAdmin } :
   )
 
   // Reset rate limiting state before continuing
-  await sdk.reset_db()
+  await reset_test_tenant(sdk)
   await wait(undefined, 500)
 
   // Test 8: Disabling OTP does NOT invalidate sessions

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

@@ -9,7 +9,7 @@ import {
 import { setup_tests } from "../setup"
 
 const host = process.env.API_URL || 'http://localhost:8080' as const
-const businessId = '60398b1131a295e64f084ff6'
+const businessId = process.env.TEST_BUSINESS_ID || '60398b1131a295e64f084ff6'
 
 /**
  * Tests for managed_content_records enduser access filtering.

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

@@ -9,7 +9,7 @@ import {
 import { setup_tests } from "../setup"
 
 const host = process.env.API_URL || 'http://localhost:8080' as const
-const businessId = '60398b1131a295e64f084ff6'
+const businessId = process.env.TEST_BUSINESS_ID || '60398b1131a295e64f084ff6'
 
 /**
  * Tests for file_download_URL enduser access via managed content fallback.

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

@@ -75,6 +75,15 @@ export const mdi_webhooks_tests = async ({ sdk, sdkNonAdmin }: { sdk: Session, s
     )
     assert(status === 401, `message_created with bad auth should 401 (got ${status})`, "MDI webhook authenticates before patient lookup")
   }
+
+  // 5. case_order_created / case_order_updated with bogus auth -> still 401.
+  for (const event_type of ['case_order_created', 'case_order_updated']) {
+    const { status } = await postMDI(
+      { event_type, case_id: 'mdi-case-test-1', case_order_id: 'mdi-order-test-1', order_status: 'ready' },
+      { 'Authorization': `Bearer not-a-real-mdi-token-${Date.now()}` },
+    )
+    assert(status === 401, `${event_type} with bad auth should 401 (got ${status})`, `MDI webhook authenticates before ${event_type} dispatch`)
+  }
 }
 
 // Allow running this test file independently

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

@@ -9,7 +9,7 @@ import { ObservationComponent } from "@tellescope/types-models"
 import { authenticate_enduser_via_token, setup_tests } from "../setup"
 
 const host = process.env.API_URL || 'http://localhost:8080' as const
-const businessId = '60398b1131a295e64f084ff6'
+const businessId = process.env.TEST_BUSINESS_ID || '60398b1131a295e64f084ff6'
 
 const ENDUSER_PASSWORD = 'NutritionTestPassword!123'
 

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

@@ -10,7 +10,7 @@ import {
 import { setup_tests } from "../setup"
 
 const host = process.env.API_URL || 'http://localhost:8080' as const
-const businessId = '60398b1131a295e64f084ff6'
+const businessId = process.env.TEST_BUSINESS_ID || '60398b1131a295e64f084ff6'
 
 const v1Url = `${host}/v1/webhooks/openloop/${businessId}`
 const v2Url = `${host}/v1/webhooks/openloop-v2/${businessId}`

package/src/tests/api_tests/security/allowed-paths-confinement.test.ts

@@ -631,7 +631,7 @@ export const allowed_paths_confinement_tests = async ({ sdk } : { sdk: Session,
     // record. `allowedPaths` is a JWT claim only (WithAllowedPaths in types-models is used solely on
     // the session type; there is no schema validator for it), so an API-key session can never carry
     // one and is never path-confined. Assert that rather than reason about it.
-    const apiKeySDK = new Session({ host, apiKey: '3n5q0SCBT_iUvZz-b9BJtX7o7HQUVJ9v132PgHJNJsg.' })
+    const apiKeySDK = new Session({ host, apiKey: process.env.TEST_API_KEY || '3n5q0SCBT_iUvZz-b9BJtX7o7HQUVJ9v132PgHJNJsg.' })
     for (const path of ['/journeys', '/form-responses', '/endusers', '/calendar-events', '/files']) {
       const r = await axios.request({
         method: 'get',

package/src/tests/api_tests/security/booking-info-idor-token-mint.test.ts

@@ -8,7 +8,7 @@ import {
 import { authenticate_enduser_via_token, setup_tests } from "../../setup"
 
 const host = process.env.API_URL || 'http://localhost:8080' as const
-const businessId = '60398b1131a295e64f084ff6'
+const businessId = process.env.TEST_BUSINESS_ID || '60398b1131a295e64f084ff6'
 
 const RAND = () => Math.random().toString(36).slice(2, 10)
 

package/src/tests/api_tests/security/enduser-ai-summary-trust-gate.test.ts

@@ -6,7 +6,7 @@ import { FormResponse } from "@tellescope/types-client"
 import { setup_tests } from "../../setup"
 
 const host = process.env.API_URL || "http://localhost:8080"
-const businessId = '60398b1131a295e64f084ff6'
+const businessId = process.env.TEST_BUSINESS_ID || '60398b1131a295e64f084ff6'
 
 const ENDUSER_PASSWORD = 'AISummaryGateTestPassword!123'
 

package/src/tests/api_tests/security/enduser-cross-create.test.ts

@@ -8,7 +8,7 @@ import {
 import { setup_tests } from "../../setup"
 
 const host = process.env.API_URL || 'http://localhost:8080' as const
-const businessId = '60398b1131a295e64f084ff6'
+const businessId = process.env.TEST_BUSINESS_ID || '60398b1131a295e64f084ff6'
 
 const ENDUSER_PASSWORD = 'F0116TestPassword!123'
 

package/src/tests/api_tests/security/enduser-write-restrictions.test.ts

@@ -8,7 +8,7 @@ import {
 import { setup_tests } from "../../setup"
 
 const host = process.env.API_URL || 'http://localhost:8080' as const
-const businessId = '60398b1131a295e64f084ff6'
+const businessId = process.env.TEST_BUSINESS_ID || '60398b1131a295e64f084ff6'
 
 const ENDUSER_PASSWORD = 'F0106TestPassword!123'
 

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