@tellescope/sdk 1.255.18 → 1.256.0

package/src/tests/api_tests/security/F-0166-allowed-paths-wildcard-bypass.test.ts

@@ -0,0 +1,721 @@
+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
+
+/**
+ * Regression test for F-0166 — allowedPaths wildcard disables path confinement entirely.
+ *
+ * Several public, unauthenticated endpoints mint a JWT confined to a small set of API paths via an
+ * `allowedPaths` claim. The enforcement predicate (api/modules/authentication.ts checkAccess)
+ * contained:
+ *
+ *     || (p.endsWith('*') && req.path.split('/')[0] === p.split('/')[0])
+ *
+ * Every request path begins with '/', so req.path.split('/')[0] is ''. Every wildcard entry also
+ * begins with '/', so p.split('/')[0] is ''. The clause reduces to '' === '' — always true. Any
+ * allowedPaths array containing a single '*' entry therefore matched EVERY request path and the
+ * 403 never fired.
+ *
+ * Two mint sites contain `/meeting/*`, and both are public and unauthenticated:
+ *   - session_for_join_link  — enduser session, MFA bypassed
+ *   - session_for_start_link — full STAFF session with mfa: false
+ *
+ * So an unauthenticated caller holding a link token had an effectively unrestricted session.
+ *
+ * Fixing that exposed a second defect in the same primitive: entries matched by bare string prefix
+ * with no notion of HTTP method, so '/users' and '/endusers' were collection-NAMESPACE grants (22
+ * and 21 routes each). The worst consequence was a full escape — PATCH /users/consent called
+ * login_user on a freshly-read DB record with no options, minting a token with no allowedPaths at
+ * all, so two requests turned a start link into an unconfined staff session.
+ *
+ * Fix, in two parts:
+ *   - entries are now method-scoped and exact ('get:/endusers'), with ':param' for segments not
+ *     knowable at mint time ('get:/meeting/:id'). Un-prefixed and '*' entries remain honoured only
+ *     so tokens minted before this grammar keep working until they expire.
+ *   - consent / configure_inbox / switch_account forward req.session.allowedPaths into login_user.
+ *
+ * Scenarios:
+ *   S1 public-form session  — no wildcard; correctly confined throughout (regression anchor)
+ *   S2 join-link session    — RED before the wildcard fix
+ *   S3 start-link session   — RED before the wildcard fix (staff session; the severe case)
+ *   S4 side-effects of the /calendar-events entry
+ *   S6 namespace grants and the privilege-escalation chain — RED before method-scoped exact matching
+ *   S5 ordinary sessions with no allowedPaths claim, incl. headless API-key callers, are unaffected
+ */
+
+const RAND = () => Math.random().toString(36).slice(2, 10)
+const OBJECT_ID = '68a1b2c3d4e5f60718293a4b'
+
+type ProbeMethod = 'get' | 'post' | 'patch' | 'put' | 'delete'
+
+type Probe = {
+  scenario: string,
+  label: string,
+  path: string,
+  expected: 'allowed' | 'denied',
+  status: number,
+  baselineStatus?: number,
+  pass: boolean,
+  note?: string,
+}
+
+export const allowed_paths_confinement_tests = async ({ sdk } : { sdk: Session, sdkNonAdmin: Session }) => {
+  log_header("F-0166: allowedPaths wildcard bypasses session path confinement")
+
+  const probes: Probe[] = []
+
+  // Probe with raw axios rather than the SDK: parseError (sdk/src/session.ts) discards the status
+  // code, and a path-confinement denial is byte-identical to a permissions denial.
+  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 isPathDenial = (r: { status: number, body: any }) => (
+    r.status === 403 && r.body?.message === 'Inaccessible'
+  )
+
+  /**
+   * A confined session must be denied `path`.
+   *
+   * First confirms an UNCONFINED session of the same type gets a non-403 on the same path in the
+   * same run. Without that, a 403 could just as easily be an ordinary permissions denial and the
+   * test would pass for the wrong reason.
+   */
+  const expectDenied = async (
+    scenario: string, label: string, confinedToken: string, baselineToken: string,
+    method: ProbeMethod, path: string, data?: any,
+  ) => {
+    const baseline = await request(baselineToken, method, path, data)
+    const confined = await request(confinedToken, method, path, data)
+
+    probes.push({
+      scenario,
+      label,
+      path,
+      expected: 'denied',
+      status: confined.status,
+      baselineStatus: baseline.status,
+      pass: baseline.status !== 403 && isPathDenial(confined),
+      note: baseline.status === 403 ? 'BAD PROBE: baseline session also got 403' : undefined,
+    })
+  }
+
+  /**
+   * The path must not be blocked by confinement.
+   *
+   * Asserts the status is neither 403 (path denied) nor 401 (unauthenticated) rather than === 200,
+   * so a 404 from a nonexistent id or a 400 from a stub body is not a false failure. Rejecting 401
+   * matters: without it a probe that never reached the handler would pass as "allowed".
+   * `allow401` opts out for paths the session legitimately cannot authenticate against.
+   */
+  const expectAllowed = async (
+    scenario: string, label: string, token: string,
+    method: ProbeMethod, path: string, data?: any,
+    { allow401 = false }: { allow401?: boolean } = {},
+  ) => {
+    const r = await request(token, method, path, data)
+    probes.push({
+      scenario,
+      label,
+      path,
+      expected: 'allowed',
+      status: r.status,
+      pass: r.status !== 403 && (allow401 || r.status !== 401),
+      note: allow401 && r.status === 401 ? '401 expected: enduser cannot authenticate this model' : undefined,
+    })
+  }
+
+  let formId: string | undefined
+  let productId: string | undefined
+  let joinEnduserId: string | undefined
+  let formEnduserEmail: string | undefined
+  let hostUserId: string | undefined
+  let templateId: string | undefined
+  let bookingEnduserId: string | undefined
+  const eventIds: string[] = []
+
+  try {
+    /* ================= fixtures ================= */
+
+    const businessId = sdk.userInfo.businessId
+
+    // -- public form (no wildcard in its allowedPaths)
+    const form = await sdk.api.forms.createOne({
+      title: `F-0166 path confinement ${RAND()}`,
+      allowPublicURL: true,
+    })
+    formId = form.id
+    await sdk.api.form_fields.createOne({
+      formId: form.id,
+      title: 'q',
+      type: 'string',
+      previousFields: [{ type: 'root', info: {} }],
+    })
+    formEnduserEmail = `f0166-form-${RAND()}@tellescope.example`
+    const publicFormSession = await new EnduserSession({ host, businessId })
+      .api.form_responses.session_for_public_form({
+        businessId,
+        formId: form.id,
+        email: formEnduserEmail,
+        fname: 'Path',
+        lname: 'Confinement',
+        skipMatch: true, // also skips the intake-phone requirement
+      })
+
+    const product = await sdk.api.products.createOne({
+      title: `F-0166 product ${RAND()}`,
+      cost: { amount: 500, currency: 'USD' },
+      processor: 'Stripe',
+    } as any)
+    productId = product.id
+
+    // -- join link (enduser session, allowedPaths contains /meeting/*)
+    const joinEnduser = await sdk.api.endusers.createOne({
+      email: `f0166-join-${RAND()}@tellescope.example`,
+    })
+    joinEnduserId = joinEnduser.id
+
+    const joinLinkToken = `f0166-join-${RAND()}${RAND()}`
+    const joinEvent = await sdk.api.calendar_events.createOne({
+      title: 'F-0166 join', durationInMinutes: 30, startTimeInMS: Date.now() + 3600_000,
+      attendees: [{ type: 'enduser', id: joinEnduser.id, joinLinkToken }],
+    } as any)
+    eventIds.push(joinEvent.id)
+
+    const unrelatedEvent = await sdk.api.calendar_events.createOne({
+      title: 'F-0166 unrelated', durationInMinutes: 30, startTimeInMS: Date.now() + 3600_000,
+      attendees: [{ type: 'enduser', id: joinEnduser.id }],
+    } as any)
+    eventIds.push(unrelatedEvent.id)
+
+    const joinSession = await new EnduserSession({ host, businessId })
+      .api.calendar_events.session_for_join_link({ token: joinLinkToken })
+
+    // -- start link (STAFF session, allowedPaths contains /meeting/*)
+    // throwaway user; verifiedEmail must be set at create time (it is rejected on update)
+    const hostUser = await sdk.api.users.createOne({
+      email: `f0166-host-${RAND()}@tellescope.example`,
+      fname: 'Path', lname: 'Host',
+      verifiedEmail: true,
+      notificationEmailsDisabled: true,
+    } as any)
+    hostUserId = hostUser.id
+
+    const startLinkToken = `f0166-start-${RAND()}${RAND()}`
+    const startEvent = await sdk.api.calendar_events.createOne({
+      title: 'F-0166 start', durationInMinutes: 30, startTimeInMS: Date.now() + 3600_000,
+      attendees: [{ type: 'user', id: hostUser.id }, { type: 'enduser', id: joinEnduser.id }],
+      startLinkToken,
+    } as any)
+    eventIds.push(startEvent.id)
+
+    const startSession = await sdk.api.calendar_events.session_for_start_link({ token: startLinkToken })
+
+    // -- unconfined baselines of each session type (generate_auth_token, never .authenticate)
+    const { authToken: baselineEnduserToken } = await sdk.api.endusers.generate_auth_token({ id: joinEnduser.id })
+    const { authToken: baselineUserToken } = await sdk.api.users.generate_auth_token({ id: hostUser.id })
+
+    /* ============ S1: public-form session — no wildcard, correctly confined already ============ */
+
+    const S1 = 'S1 public-form'
+    await expectAllowed(S1, 'always-allowed path', publicFormSession.authToken, 'get', '/test-authenticated')
+    await expectAllowed(S1, 'listed: form info for access code', publicFormSession.authToken, 'get', '/form-info-for-access-code', { accessCode: publicFormSession.accessCode })
+    await expectAllowed(S1, 'listed: refresh enduser session', publicFormSession.authToken, 'post', '/refresh-enduser-session')
+    await expectAllowed(S1, 'listed: product by id', publicFormSession.authToken, 'get', `/product/${productId}`)
+
+    await expectDenied(S1, 'unlisted: calendar events', publicFormSession.authToken, baselineEnduserToken, 'get', '/calendar-events')
+    await expectDenied(S1, 'unlisted: form responses', publicFormSession.authToken, baselineEnduserToken, 'get', '/form-responses')
+    await expectDenied(S1, 'unlisted: files', publicFormSession.authToken, baselineEnduserToken, 'get', '/files')
+
+    // 'get:/product' names one route, so it no longer leaks the whole /products namespace the way a
+    // bare '/product' prefix entry did — that used to reach /products/prepare-stripe-checkout too
+    await expectDenied(S1, 'exact matching: /products not granted by get:/product', publicFormSession.authToken, baselineEnduserToken, 'get', '/products')
+
+    /* ---- field confinement on the granted generic update route ----
+     * 'patch:/enduser/:id' is granted for Portal V2's terms gate, so the route check alone no longer
+     * protects this session — SESSION_SCOPE_WRITABLE_FIELDS does. These probes are the live control:
+     * the consent write lands, and every contactable/identity field is refused. Without them the
+     * module test is the only thing standing between a scope-table edit and account takeover.
+     */
+    const formEnduserId = publicFormSession.enduserId
+
+    // The refresh payload for a fromPublicSession token must carry the session's OWN id — portal V2
+    // seeds its store from it and then addresses itself by id, so without it every write goes to
+    // /enduser/undefined — while still withholding everything else about the patient. Both halves
+    // matter: adding the id must not become a foothold for widening this payload.
+    const publicRefresh = await request(publicFormSession.authToken, 'post', '/refresh-enduser-session', {})
+    const refreshedEnduser = publicRefresh.body?.enduser ?? {}
+    probes.push({
+      scenario: S1,
+      label: 'public refresh exposes the session\'s own id',
+      path: '/refresh-enduser-session',
+      expected: 'allowed',
+      status: refreshedEnduser.id === formEnduserId ? 200 : 500,
+      pass: refreshedEnduser.id === formEnduserId,
+      note: `id=${refreshedEnduser.id}`,
+    })
+    const withheld = ['email', 'phone', 'dateOfBirth', 'fname', 'lname', 'note', 'insurance', 'tags']
+      .filter(f => refreshedEnduser[f] !== undefined)
+    probes.push({
+      scenario: S1,
+      label: 'public refresh still withholds the patient record',
+      path: '/refresh-enduser-session',
+      expected: 'denied',
+      status: withheld.length ? 200 : 403,
+      pass: withheld.length === 0,
+      note: withheld.length ? `LEAKED [${withheld}]` : `keys=[${Object.keys(refreshedEnduser)}]`,
+    })
+
+    await expectAllowed(
+      S1, 'field-restricted: may record terms consent', publicFormSession.authToken,
+      'patch', `/enduser/${formEnduserId}`,
+      { updates: { termsSigned: new Date().toISOString(), termsVersion: '1' } },
+    )
+
+    // The write being confined is not enough: the update RESPONSE is not redacted for enduser sessions
+    // (applyRedactions runs only for user sessions on that path), so an unprojected echo would hand
+    // this session the record it can't otherwise read — GET /enduser/:id is not even in this scope.
+    // Assert the response carries ONLY what the session was allowed to write.
+    const consentEcho = await request(
+      publicFormSession.authToken, 'patch', `/enduser/${formEnduserId}`,
+      { updates: { termsVersion: '2' } },
+    )
+    const echoedKeys = Object.keys(consentEcho.body ?? {})
+    const leakedKeys = echoedKeys.filter(k => !['id', 'termsSigned', 'termsVersion'].includes(k))
+    probes.push({
+      scenario: S1,
+      label: 'field-restricted: update response echoes only the writable fields',
+      path: `/enduser/${formEnduserId}`,
+      expected: 'allowed',
+      status: leakedKeys.length === 0 ? consentEcho.status : 500,
+      pass: consentEcho.status === 200 && leakedKeys.length === 0,
+      note: leakedKeys.length ? `LEAKED [${leakedKeys}]` : `echoed [${echoedKeys}]`,
+    })
+
+    // email/phone are the takeover vector: password reset resolves by findOne({ email }) and OTP codes
+    // deliver to enduser.phone. dateOfBirth/fname are the public-form MATCH keys, so writing them would
+    // let a session redirect which patient a later submission attaches to.
+    const fieldsThatMustBeRefused: [string, any][] = [
+      ['email', `f0166-takeover-${RAND()}@tellescope.example`],
+      ['phone', '+15555550123'],
+      ['landline', '+15555550124'],
+      ['dateOfBirth', '1990-01-01'],
+      ['fname', 'F0166Overwritten'],
+    ]
+    for (const [field, value] of fieldsThatMustBeRefused) {
+      const r = await request(
+        publicFormSession.authToken, 'patch', `/enduser/${formEnduserId}`, { updates: { [field]: value } },
+      )
+      probes.push({
+        scenario: S1,
+        label: `field-restricted: cannot write enduser '${field}'`,
+        path: `/enduser/${formEnduserId}`,
+        expected: 'denied',
+        status: r.status,
+        pass: r.status === 403,
+        note: 'route is granted; the field allowlist is what refuses this',
+      })
+    }
+
+    // the field guard must reject the whole request rather than filtering, or the allowed key would
+    // carry a disallowed one through alongside it
+    const mixed = await request(
+      publicFormSession.authToken, 'patch', `/enduser/${formEnduserId}`,
+      { updates: { termsVersion: '2', email: `f0166-mixed-${RAND()}@tellescope.example` } },
+    )
+    probes.push({
+      scenario: S1,
+      label: 'field-restricted: a mixed allowed+denied update is refused whole',
+      path: `/enduser/${formEnduserId}`,
+      expected: 'denied',
+      status: mixed.status,
+      pass: mixed.status === 403,
+      note: 'no partial application — email must not ride along with termsVersion',
+    })
+
+    // and the email on record must be untouched by all of the above
+    const afterProbes = await sdk.api.endusers.getOne(formEnduserId)
+    probes.push({
+      scenario: S1,
+      label: 'field-restricted: stored email survived every attempt',
+      path: `/enduser/${formEnduserId}`,
+      expected: 'denied',
+      status: afterProbes.email === formEnduserEmail ? 403 : 200,
+      pass: afterProbes.email === formEnduserEmail,
+      note: `stored=${afterProbes.email}`,
+    })
+
+    /* ============ S2: join-link session — RED before the fix ============ */
+
+    const S2 = 'S2 join-link (enduser)'
+    await expectDenied(S2, 'unlisted: form responses', joinSession.authToken, baselineEnduserToken, 'get', '/form-responses')
+    await expectDenied(S2, 'unlisted: files', joinSession.authToken, baselineEnduserToken, 'get', '/files')
+    await expectDenied(S2, 'unlisted: portal customizations', joinSession.authToken, baselineEnduserToken, 'get', '/portal-customizations')
+    await expectDenied(S2, 'unlisted: UNRELATED calendar event', joinSession.authToken, baselineEnduserToken, 'get', `/calendar-event/${unrelatedEvent.id}`)
+
+    await expectAllowed(S2, 'always-allowed path', joinSession.authToken, 'get', '/test-authenticated')
+    await expectAllowed(S2, 'listed: my meetings', joinSession.authToken, 'get', '/my-meetings')
+    // enduserActions for organizations is {}, so an enduser 401s here regardless of confinement
+    await expectAllowed(S2, 'listed: organizations', joinSession.authToken, 'get', '/organizations', undefined, { allow401: true })
+    await expectAllowed(S2, 'listed: users', joinSession.authToken, 'get', '/users')
+    await expectAllowed(S2, 'listed: pinned calendar event', joinSession.authToken, 'get', `/calendar-event/${joinEvent.id}`)
+    await expectAllowed(S2, 'wildcard: meeting by id', joinSession.authToken, 'get', `/meeting/${OBJECT_ID}`)
+    // the two paths widened in this change so the portal video flow keeps working
+    await expectAllowed(S2, 'widened: calendar events list', joinSession.authToken, 'get', '/calendar-events')
+    await expectAllowed(S2, 'widened: join meeting for event', joinSession.authToken, 'post', '/join-meeting-for-event', { calendarEventId: joinEvent.id })
+
+    // The WaitingRoom marks attendance here. This write is deliberately NOT field-restricted: the
+    // portal reads the event back through useCalendarEvents, whose updateElement REPLACES the local
+    // record with the update response (react state.tsx), so a truncated response would drop event
+    // fields out of local state mid-visit and break a live Twilio call. Assert both halves of that
+    // contract — the write lands, AND the response is still a whole event.
+    const attendanceWrite = await request(
+      joinSession.authToken, 'patch', `/calendar-event/${joinEvent.id}`,
+      { updates: { joinedVideoCall: [{ id: joinEnduserId, at: new Date().toISOString() }] } },
+    )
+    probes.push({
+      scenario: S2,
+      label: 'marks joinedVideoCall on its pinned event',
+      path: `/calendar-event/${joinEvent.id}`,
+      expected: 'allowed',
+      status: attendanceWrite.status,
+      pass: attendanceWrite.status === 200,
+    })
+    // title/durationInMinutes were set at fixture creation, so their presence proves the response was
+    // not projected down to the written field
+    const echoedEvent = attendanceWrite.body ?? {}
+    probes.push({
+      scenario: S2,
+      label: 'attendance write returns the WHOLE event (client replaces local state from it)',
+      path: `/calendar-event/${joinEvent.id}`,
+      expected: 'allowed',
+      status: (echoedEvent.title && echoedEvent.durationInMinutes) ? 200 : 500,
+      pass: !!echoedEvent.title && !!echoedEvent.durationInMinutes && !!echoedEvent.joinedVideoCall,
+      note: `echoed ${Object.keys(echoedEvent).length} keys`,
+    })
+
+    // confinement must survive a refresh rather than widening
+    const refreshedJoin = await request(joinSession.authToken, 'post', '/refresh-enduser-session', {})
+    const refreshedJoinToken = refreshedJoin.body?.authToken
+    probes.push({
+      scenario: S2, label: 'refresh returned a new token', path: '/refresh-enduser-session',
+      expected: 'allowed', status: refreshedJoin.status, pass: !!refreshedJoinToken,
+    })
+    if (refreshedJoinToken) {
+      await expectDenied(S2, 'after refresh: still denied form responses', refreshedJoinToken, baselineEnduserToken, 'get', '/form-responses')
+      await expectAllowed(S2, 'after refresh: still allowed my meetings', refreshedJoinToken, 'get', '/my-meetings')
+    }
+
+    /* ============ S3: start-link session — STAFF, RED before the fix ============ */
+
+    const S3 = 'S3 start-link (STAFF)'
+    await expectDenied(S3, 'unlisted: form responses', startSession.authToken, baselineUserToken, 'get', '/form-responses')
+    await expectDenied(S3, 'unlisted: journeys', startSession.authToken, baselineUserToken, 'get', '/journeys')
+    await expectDenied(S3, 'unlisted: tickets', startSession.authToken, baselineUserToken, 'get', '/tickets')
+    await expectDenied(S3, 'unlisted: data sync (org-wide change firehose)', startSession.authToken, baselineUserToken, 'get', '/data-sync', { from: new Date(Date.now() - 60_000).toISOString() })
+    await expectDenied(S3, 'unlisted: file download URL', startSession.authToken, baselineUserToken, 'get', '/file-download-URL', { secureName: 'f0166-does-not-exist' })
+    await expectDenied(S3, 'unlisted: UNRELATED calendar event', startSession.authToken, baselineUserToken, 'get', `/calendar-event/${unrelatedEvent.id}`)
+
+    await expectAllowed(S3, 'always-allowed path', startSession.authToken, 'get', '/test-authenticated')
+    await expectAllowed(S3, 'listed: my meetings', startSession.authToken, 'get', '/my-meetings')
+    await expectAllowed(S3, 'listed: calendar events', startSession.authToken, 'get', '/calendar-events')
+    await expectAllowed(S3, 'listed: organizations', startSession.authToken, 'get', '/organizations')
+    await expectAllowed(S3, 'listed: users', startSession.authToken, 'get', '/users')
+    await expectAllowed(S3, 'listed: endusers', startSession.authToken, 'get', '/endusers')
+    await expectAllowed(S3, 'listed: pinned calendar event', startSession.authToken, 'get', `/calendar-event/${startEvent.id}`)
+    await expectAllowed(S3, 'wildcard: meeting by id', startSession.authToken, 'get', `/meeting/${OBJECT_ID}`)
+    await expectAllowed(S3, 'prefix descendant: users bulk-read', startSession.authToken, 'post', '/users/bulk-read', { ids: [hostUser.id] })
+    await expectAllowed(S3, 'prefix descendant: endusers bulk-read', startSession.authToken, 'post', '/endusers/bulk-read', { ids: [joinEnduser.id] })
+    await expectAllowed(S3, 'widened: join meeting for event', startSession.authToken, 'post', '/join-meeting-for-event', { calendarEventId: startEvent.id })
+    await expectAllowed(S3, 'widened: add attendees to meeting', startSession.authToken, 'post', '/add-attendees-to-meeting', { id: OBJECT_ID })
+
+    // login_user propagates allowedPaths implicitly through its ...toSign rest spread — the
+    // "(ASSUMPTION)" comments in the mint sites depend on this, so assert it explicitly
+    const refreshedStart = await request(startSession.authToken, 'post', '/refresh-session', {})
+    const refreshedStartToken = refreshedStart.body?.authToken
+    probes.push({
+      scenario: S3, label: 'refresh returned a new token', path: '/refresh-session',
+      expected: 'allowed', status: refreshedStart.status, pass: !!refreshedStartToken,
+    })
+    if (refreshedStartToken) {
+      await expectDenied(S3, 'after refresh: still denied journeys', refreshedStartToken, baselineUserToken, 'get', '/journeys')
+      await expectAllowed(S3, 'after refresh: still allowed my meetings', refreshedStartToken, 'get', '/my-meetings')
+    }
+
+    /* ============ S4: side-effects of the widened /calendar-events entry ============ */
+
+    // Non-wildcard entries still match by bare prefix, so adding '/calendar-events' to the join-link
+    // list also prefix-grants '/calendar-events/bulk-update' and friends. Those are staff-only and
+    // gated by enduserActions, so an enduser session is still refused — assert that rather than
+    // assume it. This is the concrete argument for the segment-boundary follow-up.
+    const S4 = 'S4 widening side-effects'
+    const prefixGranted: [('patch' | 'post'), string][] = [
+      ['patch', '/calendar-events/bulk-update'],
+      ['post', '/calendar-events/report'],
+    ]
+    for (const [method, path] of prefixGranted) {
+      const r = await axios.request({
+        method,
+        url: `${host}/v1${path}`,
+        data: {},
+        headers: { Authorization: `Bearer ${joinSession.authToken}` },
+        validateStatus: () => true,
+      })
+      probes.push({
+        scenario: S4,
+        label: `enduser action gating blocks ${method.toUpperCase()} ${path}`,
+        path,
+        expected: 'denied',
+        status: r.status,
+        pass: r.status === 401 || r.status === 403,
+        note: 'prefix-granted by /calendar-events; blocked by enduserActions instead',
+      })
+    }
+
+    /* ============ S6: the namespace grants and the privilege-escalation chain ============ */
+
+    // Before method-scoped exact matching, '/users' and '/endusers' were collection-namespace
+    // grants: 22 and 21 routes each. The worst of them, PATCH /users/consent, called
+    // login_user on a fresh DB record and minted a token with NO allowedPaths at all — so an
+    // unauthenticated start link could be traded for a fully unconfined staff session.
+    const S6 = 'S6 namespace escapes'
+
+    // expectDenied issues the BASELINE request for real, so mutating probes must be given inert
+    // payloads — nonexistent ids or bodies that fail validation. A 400/404 baseline still proves the
+    // route is reachable (the check is only `!== 403`). Passing real ids here once made the
+    // unconfined baseline actually perform an /endusers/merge, deleting the fixture enduser.
+    const ABSENT_ID_A = '68a1b2c3d4e5f60718293a4b'
+    const ABSENT_ID_B = '68a1b2c3d4e5f60718293a4c'
+    const INVALID_EMAIL = 'f0166-not-an-email'
+
+    await expectDenied(S6, 'ESCAPE: /users/consent (minted an unconfined token)', startSession.authToken, baselineUserToken, 'patch', '/users/consent', { termsVersion: '1' })
+    await expectDenied(S6, 'ESCAPE: /users/switch-account', startSession.authToken, baselineUserToken, 'post', '/users/switch-account', { targetUserId: ABSENT_ID_A })
+    await expectDenied(S6, 'ESCAPE: /users/configure-inbox', startSession.authToken, baselineUserToken, 'post', '/users/configure-inbox', {})
+    await expectDenied(S6, 'PHI: /endusers/load-inbox-data', startSession.authToken, baselineUserToken, 'get', '/endusers/load-inbox-data')
+    await expectDenied(S6, 'PHI: /endusers/report', startSession.authToken, baselineUserToken, 'get', '/endusers/report')
+    await expectDenied(S6, 'PHI: /endusers/engagement', startSession.authToken, baselineUserToken, 'get', '/endusers/engagement')
+    await expectDenied(S6, 'DESTRUCTIVE: /endusers/merge', startSession.authToken, baselineUserToken, 'post', '/endusers/merge', { sourceEnduserId: ABSENT_ID_A, destinationEnduserId: ABSENT_ID_B })
+    await expectDenied(S6, 'DESTRUCTIVE: /endusers/bulk-update', startSession.authToken, baselineUserToken, 'patch', '/endusers/bulk-update', { ids: [ABSENT_ID_A], fields: {} })
+
+    // method scoping, end to end: the same path is readable but not writable.
+    // Baselines use the ADMIN token — the throwaway host user cannot create users or endusers, so it
+    // would 403 on permissions and the probe could not distinguish that from a confinement denial.
+    await expectAllowed(S6, 'method scoping: GET /endusers allowed', startSession.authToken, 'get', '/endusers')
+    await expectDenied(S6, 'method scoping: POST /endusers (create) denied', startSession.authToken, sdk.authToken, 'post', '/endusers', { email: INVALID_EMAIL })
+    await expectAllowed(S6, 'method scoping: GET /users allowed', startSession.authToken, 'get', '/users')
+    await expectDenied(S6, 'method scoping: POST /users (create) denied', startSession.authToken, sdk.authToken, 'post', '/users', { email: INVALID_EMAIL })
+
+    // even if consent were reachable, the token it mints must stay confined (defense in depth)
+    const consentAttempt = await request(startSession.authToken, 'patch', '/users/consent', { termsVersion: '1' })
+    if (consentAttempt.status === 200 && consentAttempt.body?.authToken) {
+      await expectDenied(S6, 'consent-minted token is still confined', consentAttempt.body.authToken, baselineUserToken, 'get', '/journeys')
+    }
+
+    // Confinement now lives in a `sessionScopes` claim resolved server-side. Refresh must carry that
+    // claim, not silently drop it — login_user's toSign is a deny-list so it propagates, but that is
+    // exactly the kind of implicit behavior worth asserting.
+    const refreshedForScopes = await request(startSession.authToken, 'post', '/refresh-session', {})
+    const rescopedToken = refreshedForScopes.body?.authToken
+    probes.push({
+      scenario: S6, label: 'refresh returned a new token', path: '/refresh-session',
+      expected: 'allowed', status: refreshedForScopes.status, pass: !!rescopedToken,
+    })
+    if (rescopedToken) {
+      await expectDenied(S6, 'after refresh: still cannot reach /users/consent', rescopedToken, baselineUserToken, 'patch', '/users/consent', { termsVersion: '1' })
+      await expectDenied(S6, 'after refresh: still cannot reach /endusers/load-inbox-data', rescopedToken, baselineUserToken, 'get', '/endusers/load-inbox-data')
+      await expectDenied(S6, 'after refresh: POST /endusers still denied', rescopedToken, baselineUserToken, 'post', '/endusers', { email: `f0166-should-not-exist-${RAND()}@tellescope.example` })
+      await expectAllowed(S6, 'after refresh: GET /endusers still allowed', rescopedToken, 'get', '/endusers')
+      await expectAllowed(S6, 'after refresh: my-meetings still allowed', rescopedToken, 'get', '/my-meetings')
+    }
+
+    /* ============ S7: appointment-booking session — the SAME terms gate as S1 ============
+     * Portal V2's terms gate wraps the booking route too, so this scope needs the same enduser write
+     * (and only that write). Without the grant the gate is unpassable and the patient never reaches the
+     * booking page at all. Field restriction and response projection must behave exactly as in S1 —
+     * mirrored here rather than assumed, since the two scopes are separate table entries.
+     */
+    const S7 = 'S7 appointment-booking'
+
+    const bookingTemplate = await sdk.api.calendar_event_templates.createOne({
+      title: `F-0166 booking ${RAND()}`, durationInMinutes: 30,
+    })
+    templateId = bookingTemplate.id
+
+    const bookingEnduserEmail = `f0166-booking-${RAND()}@tellescope.example`
+    const bookingEnduser = await sdk.api.endusers.createOne({
+      email: bookingEnduserEmail, fname: 'Booking', lname: 'Confinement',
+    })
+    bookingEnduserId = bookingEnduser.id
+
+    const bookingSession = await new EnduserSession({ host, businessId })
+      .api.calendar_events.session_for_public_appointment_booking({
+        businessId,
+        calendarEventTemplateId: bookingTemplate.id,
+        email: bookingEnduserEmail,
+        fname: 'Booking',
+        lname: 'Confinement',
+      })
+
+    await expectAllowed(
+      S7, 'field-restricted: may record terms consent', bookingSession.authToken,
+      'patch', `/enduser/${bookingEnduser.id}`,
+      { updates: { termsSigned: new Date().toISOString(), termsVersion: '1' } },
+    )
+
+    const bookingEcho = await request(
+      bookingSession.authToken, 'patch', `/enduser/${bookingEnduser.id}`, { updates: { termsVersion: '2' } },
+    )
+    const bookingLeaked = Object.keys(bookingEcho.body ?? {})
+      .filter(k => !['id', 'termsSigned', 'termsVersion'].includes(k))
+    probes.push({
+      scenario: S7,
+      label: 'field-restricted: update response echoes only the writable fields',
+      path: `/enduser/${bookingEnduser.id}`,
+      expected: 'allowed',
+      status: bookingLeaked.length === 0 ? bookingEcho.status : 500,
+      pass: bookingEcho.status === 200 && bookingLeaked.length === 0,
+      note: bookingLeaked.length ? `LEAKED [${bookingLeaked}]` : undefined,
+    })
+
+    for (const [field, value] of [['email', `f0166-bt-${RAND()}@tellescope.example`], ['phone', '+15555550188']] as [string, any][]) {
+      const r = await request(bookingSession.authToken, 'patch', `/enduser/${bookingEnduser.id}`, { updates: { [field]: value } })
+      probes.push({
+        scenario: S7,
+        label: `field-restricted: cannot write enduser '${field}'`,
+        path: `/enduser/${bookingEnduser.id}`,
+        expected: 'denied',
+        status: r.status,
+        pass: r.status === 403,
+        note: 'route is granted; the field allowlist is what refuses this',
+      })
+    }
+
+    // the booking scope must not have gained anything else along with the enduser write
+    await expectDenied(S7, 'unlisted: form responses', bookingSession.authToken, baselineEnduserToken, 'get', '/form-responses')
+    await expectDenied(S7, 'unlisted: calendar events', bookingSession.authToken, baselineEnduserToken, 'get', '/calendar-events')
+    await expectAllowed(S7, 'listed: refresh enduser session', bookingSession.authToken, 'post', '/refresh-enduser-session')
+
+    /* ============ S5: ordinary sessions with no allowedPaths claim ============ */
+
+    const S5 = 'S5 unconfined sessions'
+    for (const path of ['/journeys', '/form-responses', '/endusers', '/calendar-events', '/tickets']) {
+      await expectAllowed(S5, `staff session reaches ${path}`, baselineUserToken, 'get', path)
+    }
+    await expectAllowed(S5, 'staff session reaches /data-sync', baselineUserToken, 'get', '/data-sync', { from: new Date(Date.now() - 60_000).toISOString() })
+    for (const path of ['/form-responses', '/calendar-events', '/files']) {
+      await expectAllowed(S5, `enduser session reaches ${path}`, baselineEnduserToken, 'get', path)
+    }
+    const adminAuthenticated = await sdk.test_authenticated()
+    probes.push({
+      scenario: S5, label: 'admin sdk still authenticated', path: '/test-authenticated',
+      expected: 'allowed', status: 200, pass: adminAuthenticated === 'Authenticated!',
+    })
+
+    // Headless / server-to-server callers authenticate with an API key, which resolves to a DB user
+    // 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.' })
+    for (const path of ['/journeys', '/form-responses', '/endusers', '/calendar-events', '/files']) {
+      const r = await axios.request({
+        method: 'get',
+        url: `${host}/v1${path}`,
+        headers: { Authorization: `API_KEY ${(apiKeySDK as any).apiKey}` },
+        validateStatus: () => true,
+      })
+      probes.push({
+        scenario: S5,
+        label: `API key (headless) reaches ${path}`,
+        path,
+        expected: 'allowed',
+        status: r.status,
+        pass: r.status !== 403,
+      })
+    }
+
+    /* ============ report, then assert ============ */
+
+    // Collect everything before asserting. @tellescope/testing sets EXIT_ON_FIRST_ERROR, so
+    // asserting inline would abort at the first failure and hide the rest of the bypass.
+    const failures = probes.filter(p => !p.pass)
+
+    console.log('')
+    console.log('  F-0166 — full probe table')
+    console.log('  ' + '-'.repeat(112))
+    const scenarios = probes.map(p => p.scenario).filter((s, i, all) => all.indexOf(s) === i)
+    for (const scenario of scenarios) {
+      const inScenario = probes.filter(p => p.scenario === scenario)
+      const failed = inScenario.filter(p => !p.pass).length
+      console.log(`  ${scenario}: ${inScenario.length - failed}/${inScenario.length} passing${failed ? `  <-- ${failed} FAILING` : ''}`)
+      for (const p of inScenario) {
+        const baseline = p.baselineStatus !== undefined ? ` baseline=${p.baselineStatus}` : ''
+        console.log(`    ${p.pass ? ' ok ' : 'FAIL'}  want=${p.expected.padEnd(7)} got=${p.status}${baseline}  ${p.label}${p.note ? `  (${p.note})` : ''}`)
+      }
+    }
+    console.log('  ' + '-'.repeat(112))
+    console.log(`  TOTAL: ${probes.length - failures.length}/${probes.length} passing, ${failures.length} failing`)
+    console.log('')
+
+    for (const p of probes) {
+      assert(
+        p.pass,
+        `${p.scenario} — ${p.label} (${p.path}): wanted ${p.expected}, got status ${p.status}`
+          + (p.baselineStatus !== undefined ? ` (unconfined baseline got ${p.baselineStatus})` : ''),
+        `${p.scenario} — ${p.label}`,
+      )
+    }
+  } finally {
+    for (const id of eventIds) {
+      try { await sdk.api.calendar_events.deleteOne(id) } catch {}
+    }
+    if (joinEnduserId) { try { await sdk.api.endusers.deleteOne(joinEnduserId) } catch {} }
+    if (formEnduserEmail) {
+      try {
+        const e = await sdk.api.endusers.getOne({ email: formEnduserEmail })
+        if (e?.id) await sdk.api.endusers.deleteOne(e.id)
+      } catch {}
+    }
+    if (hostUserId) { try { await sdk.api.users.deleteOne(hostUserId) } catch {} }
+    if (bookingEnduserId) { try { await sdk.api.endusers.deleteOne(bookingEnduserId) } catch {} }
+    if (templateId) { try { await sdk.api.calendar_event_templates.deleteOne(templateId) } catch {} }
+    if (productId) { try { await sdk.api.products.deleteOne(productId) } catch {} }
+    if (formId) { try { await sdk.api.forms.deleteOne(formId) } catch {} }
+  }
+}
+
+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 allowed_paths_confinement_tests({ sdk, sdkNonAdmin })
+  }
+
+  runTests()
+  .then(() => {
+    console.log("✅ F-0166 allowedPaths confinement test suite completed successfully")
+    process.exit(0)
+  })
+  .catch((error) => {
+    console.error("❌ F-0166 allowedPaths confinement test suite failed:", error)
+    process.exit(1)
+  })
+}