@tellescope/sdk 1.255.16 → 1.255.18

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

@@ -12,7 +12,7 @@ import { setup_tests } from "../setup"
 const host = process.env.API_URL || 'http://localhost:8080' as const
 
 // fields that the admin org-wide list endpoint is allowed to return
-const ALLOWED_FIELDS = ['id', 'creator', 'businessId', 'updatedAt'].sort()
+const ALLOWED_FIELDS = ['id', 'creator', 'businessId', 'updatedAt', 'scopes'].sort()
 
 export const organization_api_keys_tests = async (
   { sdk, sdkNonAdmin }: { sdk: Session, sdkNonAdmin: Session }
@@ -104,7 +104,7 @@ export const organization_api_keys_tests = async (
     assert(
       offending === undefined,
       `a returned record exposed non-allowlisted fields: ${JSON.stringify(offending)}`,
-      "returned records contain only allowlisted fields (subset of id, creator, businessId, updatedAt)"
+      "returned records contain only allowlisted fields (subset of id, creator, businessId, updatedAt, scopes)"
     )
 
     // =============================================

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

@@ -0,0 +1,319 @@
+require('source-map-support').install();
+
+import axios from "axios"
+import { Session } from "../../sdk"
+import {
+  assert,
+  async_test,
+  log_header,
+  wait,
+} from "@tellescope/testing"
+import { setup_tests } from "../setup"
+import { FORM_INGESTION_API_KEY_SCOPE } from "@tellescope/types-models"
+
+const host = process.env.API_URL || "http://localhost:8080"
+
+const TEST_EMAIL = "scoped-api-keys@tellescope.com"
+
+export const scoped_api_keys_tests = async ({ sdk, sdkNonAdmin } : { sdk: Session, sdkNonAdmin: Session }) => {
+  log_header("Scoped API Keys (form-ingestion)")
+
+  const form = await sdk.api.forms.createOne({ title: "Scoped API Key Test Form" })
+
+  const buildUrl = (pathSegment: string) => {
+    const url = new URL(`${host}/v1/webhooks/form-ingestion/${pathSegment}`)
+    url.searchParams.set('formId', form.id)
+    url.searchParams.set('returnJSON', 'true')
+    return url.toString()
+  }
+
+  const bodyFor = (responder_uuid: string) => ({
+    answers: [{ key: 'email', value: TEST_EMAIL }],
+    responder_uuid,
+    finalized: true,
+  })
+
+  const keyIds: string[] = []
+  const formResponseIds: string[] = []
+  const fileIds: string[] = []
+  let throwawayUserId: string | undefined
+  let throwawayRoleId: string | undefined
+
+  try {
+    // =============================================
+    // (a) Admin creates a scoped key
+    // =============================================
+    const scoped = await sdk.api.api_keys.createOne({ scopes: [FORM_INGESTION_API_KEY_SCOPE] })
+    keyIds.push(scoped.id)
+    assert(!!scoped.id && !!scoped.key, "scoped key create returned no id/key", "admin creates a form-ingestion-scoped key")
+
+    // record reflects the scope for its creator (CREATOR_ONLY_ACCESS read)
+    await async_test(
+      "scoped key record stores scopes",
+      () => sdk.api.api_keys.getOne(scoped.id),
+      { onResult: k => JSON.stringify(k.scopes) === JSON.stringify([FORM_INGESTION_API_KEY_SCOPE]) },
+    )
+
+    // =============================================
+    // (b) Scoped key is rejected on all general /v1 auth
+    // =============================================
+    await async_test(
+      "scoped key rejected on /v1/test-authenticated",
+      () => new Session({ host, apiKey: scoped.key }).test_authenticated(),
+      // SDK parseError surfaces a raw 401 body as the string 'Unauthenticated'
+      { shouldError: true, onError: (e: any) => e === 'Unauthenticated' || e?.statusCode === 401 || /unauthenticated/i.test(e?.message || '') },
+    )
+    await async_test(
+      "scoped key rejected on GET /v1/endusers",
+      () => axios.get(`${host}/v1/endusers`, { headers: { Authorization: `API_KEY ${scoped.key}` } }),
+      { shouldError: true, onError: (e: any) => e.response?.status === 401 },
+    )
+    await async_test(
+      "scoped key rejected on cross-org targeting (x-tellescope-organization)",
+      () => axios.get(`${host}/v1/endusers`, {
+        headers: {
+          Authorization: `API_KEY ${scoped.key}`,
+          'x-tellescope-organization': sdk.userInfo.businessId,
+        },
+      }),
+      { shouldError: true, onError: (e: any) => e.response?.status === 401 },
+    )
+
+    // =============================================
+    // (c) Scoped key IS accepted by the form-ingestion webhook
+    // =============================================
+    const headerResult = await axios.post(
+      buildUrl('key-in-header'),
+      bodyFor("scoped-1"),
+      { headers: { Authorization: `API_KEY ${scoped.key}` } },
+    )
+    assert(
+      headerResult.status === 200 && !!headerResult.data?.formResponseId,
+      `scoped key header auth failed: ${headerResult.status} ${JSON.stringify(headerResult.data)}`,
+      "scoped key authenticates the form-ingestion webhook via header",
+    )
+    if (headerResult.data?.formResponseId) formResponseIds.push(headerResult.data.formResponseId)
+
+    const pathResult = await axios.post(buildUrl(scoped.key), bodyFor("scoped-2"))
+    assert(
+      pathResult.status === 200 && !!pathResult.data?.formResponseId,
+      `scoped key path auth failed: ${pathResult.status} ${JSON.stringify(pathResult.data)}`,
+      "scoped key authenticates the form-ingestion webhook via path segment",
+    )
+    if (pathResult.data?.formResponseId) formResponseIds.push(pathResult.data.formResponseId)
+
+    // =============================================
+    // (c2) Scoped key CAN run the file-upload flow (prepare + confirm) — needed for intake forms with files
+    // =============================================
+    const scopedSession = new Session({ host, apiKey: scoped.key })
+    const { file: uploadedFile } = await scopedSession.api.files.prepare_file_upload({
+      name: 'scoped-intake-file.txt', size: 12, type: 'text/plain',
+    })
+    assert(
+      !!uploadedFile?.id,
+      "scoped key prepare_file_upload returned no file",
+      "scoped key can call POST /prepare-file-upload",
+    )
+    if (uploadedFile?.id) fileIds.push(uploadedFile.id)
+
+    await async_test(
+      "scoped key can call POST /files/confirm-upload",
+      () => scopedSession.api.files.confirm_file_upload({ id: uploadedFile.id }),
+      { onResult: () => true },
+    )
+
+    // ...but is blocked from EVERY other endpoint in the files domain — proving the two allowed paths are the
+    // ONLY files access, and that the '/files/confirm-upload' allow-prefix does not open the '/files/*' namespace.
+    const blockedFileEndpoints: [string, () => Promise<any>][] = [
+      ['GET /v1/files (readMany)', () => axios.get(`${host}/v1/files`, { headers: { Authorization: `API_KEY ${scoped.key}` } })],
+      ['GET /v1/file/:id (read one)', () => axios.get(`${host}/v1/file/000000000000000000000000`, { headers: { Authorization: `API_KEY ${scoped.key}` } })],
+      ['DELETE /v1/file/:id (destructive)', () => axios.delete(`${host}/v1/file/000000000000000000000000`, { headers: { Authorization: `API_KEY ${scoped.key}` } })],
+      ['POST /v1/files/send-fax (/files/* sibling)', () => axios.post(`${host}/v1/files/send-fax`, {}, { headers: { Authorization: `API_KEY ${scoped.key}` } })],
+      ['POST /v1/files/ocr (/files/* sibling)', () => axios.post(`${host}/v1/files/ocr`, {}, { headers: { Authorization: `API_KEY ${scoped.key}` } })],
+      ['POST /v1/files/push (/files/* sibling)', () => axios.post(`${host}/v1/files/push`, {}, { headers: { Authorization: `API_KEY ${scoped.key}` } })],
+    ]
+    for (const [label, call] of blockedFileEndpoints) {
+      await async_test(
+        `scoped key blocked on ${label}`,
+        call,
+        { shouldError: true, onError: (e: any) => e.response?.status === 401 || e.response?.status === 403 },
+      )
+    }
+
+    // =============================================
+    // (d) Non-admin cannot create a scoped key (throwaway user, never mutate existing roles)
+    // =============================================
+    const apiKeysRole = await sdk.api.role_based_access_permissions.createOne({
+      role: 'scoped-api-keys-test-role',
+      permissions: { api_keys: { create: 'All', read: 'All', update: 'All', delete: 'All' } },
+    })
+    throwawayRoleId = apiKeysRole.id
+
+    const throwawayUser = (
+      await sdk.api.users.getOne({ email: 'scoped.api.keys.user@tellescope.com' }).catch(() => null)
+    ) || (
+      await sdk.api.users.createOne({ email: 'scoped.api.keys.user@tellescope.com', notificationEmailsDisabled: true, verifiedEmail: true })
+    )
+    throwawayUserId = throwawayUser.id
+    await sdk.api.users.updateOne(throwawayUser.id, { roles: [apiKeysRole.role] }, { replaceObjectFields: true })
+    await wait(undefined, 2000) // wait for the role change to propagate before authenticating
+
+    const otherSdk = new Session({
+      host,
+      authToken: (await sdk.api.users.generate_auth_token({ id: throwawayUser.id })).authToken,
+    })
+
+    await async_test(
+      "non-admin cannot create a scoped key (401)",
+      () => otherSdk.api.api_keys.createOne({ scopes: [FORM_INGESTION_API_KEY_SCOPE] }),
+      { shouldError: true, onError: (e: any) => e === 'Unauthenticated' || e?.statusCode === 401 || /admin/i.test(e?.message || '') },
+    )
+
+    // ...but CAN still create an unscoped key; an empty scopes list is rejected by validation (fail closed)
+    const nonAdminKey = await otherSdk.api.api_keys.createOne({})
+    await async_test(
+      "empty scopes list rejected by validation",
+      () => otherSdk.api.api_keys.createOne({ scopes: [] }),
+      { shouldError: true, onError: (e: any) => e?.statusCode === 400 || /empty|not valid|invalid/i.test(e?.message || '') },
+    )
+    // creator-only cleanup for the throwaway user's key before the user is deleted
+    await otherSdk.api.api_keys.deleteOne(nonAdminKey.id).catch(() => {})
+
+    // =============================================
+    // (e) Unscoped keys are unchanged (no regression)
+    // =============================================
+    const unscoped = await sdk.api.api_keys.createOne({})
+    const unscopedKeyValue = (unscoped as any).key as string
+    keyIds.push(unscoped.id)
+
+    await async_test(
+      "unscoped key still authenticates general /v1",
+      () => new Session({ host, apiKey: unscopedKeyValue }).test_authenticated(),
+      { onResult: r => !!r },
+    )
+    // Frozen pre-existing behavior: unscoped /v1-created keys store a utf8-encoded hashedKey, which the
+    // webhook's hex lookup never matches — only legacy plaintext keys and hex-stored scoped keys work there.
+    // (Legacy-key webhook auth is covered by formsort_header_auth.test.ts.)
+    await async_test(
+      "unscoped /v1-created key still does NOT authenticate the webhook (frozen encoding quirk)",
+      () => axios.post(
+        buildUrl('key-in-header'),
+        bodyFor("scoped-3"),
+        { headers: { Authorization: `API_KEY ${unscopedKeyValue}` } },
+      ),
+      { shouldError: true, onError: (e: any) => e.response?.status === 401 },
+    )
+
+    // =============================================
+    // (f) Admin org-wide list includes scopes (and still never leaks secrets)
+    // =============================================
+    const { apiKeys } = await sdk.api.api_keys.get_organization_api_keys()
+    assert(
+      !!apiKeys.find(k => k.id === scoped.id && JSON.stringify(k.scopes) === JSON.stringify([FORM_INGESTION_API_KEY_SCOPE])),
+      "org list did not report scopes on the scoped key",
+      "get_organization_api_keys reports scopes on scoped keys",
+    )
+    assert(
+      !!apiKeys.find(k => k.id === unscoped.id && k.scopes === undefined),
+      "org list reported scopes on an unscoped key",
+      "get_organization_api_keys omits scopes on unscoped keys",
+    )
+    assert(
+      apiKeys.every(k => (k as any).key === undefined && (k as any).hashedKey === undefined),
+      "org list leaked key material",
+      "get_organization_api_keys still never returns key/hashedKey",
+    )
+
+    // =============================================
+    // (g) Legacy non-/v1 funnel (app.js requireLoginAndAccess → is_logged_in_API_key with NO requestPath).
+    // Proves scoped keys fail closed on every non-/v1 caller (also stands in for the Medplum webhook path),
+    // and that unscoped keys still authenticate the legacy funnel after this work.
+    // NOTE: the legacy middleware reads the key from ?apiKey= / body only (never the Authorization header).
+    // =============================================
+    await async_test(
+      "unscoped key authenticates a legacy non-/v1 route",
+      () => axios.get(`${host}/API-keys-for-user?apiKey=${encodeURIComponent(unscopedKeyValue)}`),
+      { onResult: (r: any) => r.status === 200 },
+    )
+    await async_test(
+      "scoped key rejected on a legacy non-/v1 route (fail closed, no requestPath)",
+      () => axios.get(`${host}/API-keys-for-user?apiKey=${encodeURIComponent(scoped.key)}`),
+      { shouldError: true, onError: (e: any) => e.response?.status === 401 },
+    )
+
+    // =============================================
+    // (h) Data-egress adjacency: the scope's allowed paths must NOT leak to the file DOWNLOAD endpoint.
+    // =============================================
+    await async_test(
+      "scoped key cannot call file_download_URL (no PHI egress)",
+      () => axios.get(`${host}/v1/file-download-URL?secureName=nonexistent`, { headers: { Authorization: `API_KEY ${scoped.key}` } }),
+      { shouldError: true, onError: (e: any) => e.response?.status === 401 || e.response?.status === 403 },
+    )
+
+    // =============================================
+    // (i) Transport independence: the scope gate applies whether the key is in the header or the ?apiKey= query.
+    // =============================================
+    await async_test(
+      "scoped key via ?apiKey= query param still rejected on a disallowed /v1 endpoint",
+      () => axios.get(`${host}/v1/endusers?apiKey=${encodeURIComponent(scoped.key)}`),
+      { shouldError: true, onError: (e: any) => e.response?.status === 401 || e.response?.status === 403 },
+    )
+    await async_test(
+      "unscoped key via ?apiKey= query param still authenticates /v1 (regression)",
+      () => axios.get(`${host}/v1/test-authenticated?apiKey=${encodeURIComponent(unscopedKeyValue)}`),
+      { onResult: (r: any) => r.status === 200 },
+    )
+
+    // =============================================
+    // Validation: unknown scope values are rejected
+    // =============================================
+    await async_test(
+      "unknown scope value rejected by validation",
+      () => sdk.api.api_keys.createOne({ scopes: ['not-a-real-scope'] as any }),
+      { shouldError: true, onError: (e: any) => e?.statusCode === 400 || /must match|not valid|invalid/i.test(e?.message || '') },
+    )
+  } finally {
+    for (const id of keyIds) {
+      await sdk.api.api_keys.deleteOne(id).catch(() => {})
+    }
+    for (const id of formResponseIds) {
+      await sdk.api.form_responses.deleteOne(id).catch(() => {})
+    }
+    for (const id of fileIds) {
+      await sdk.api.files.deleteOne(id).catch(() => {})
+    }
+    try {
+      const enduser = await sdk.api.endusers.getOne({ email: TEST_EMAIL })
+      await sdk.api.endusers.deleteOne(enduser.id)
+    } catch (err) { /* may not exist */ }
+    await sdk.api.forms.deleteOne(form.id).catch(() => {})
+    if (throwawayUserId) {
+      await sdk.api.users.deleteOne(throwawayUserId).catch(() => {})
+    }
+    if (throwawayRoleId) {
+      await sdk.api.role_based_access_permissions.deleteOne(throwawayRoleId).catch(() => {})
+    }
+  }
+}
+
+// Allow running this test file independently
+if (require.main === module) {
+  console.log(`🌐 Using API URL: ${host}`)
+  const sdk = new Session({ host })
+  const sdkNonAdmin = new Session({ host })
+
+  const runTests = async () => {
+    await setup_tests(sdk, sdkNonAdmin)
+    await scoped_api_keys_tests({ sdk, sdkNonAdmin })
+  }
+
+  runTests()
+    .then(() => {
+      console.log("✅ Scoped API keys test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ Scoped API keys test suite failed:", error)
+      process.exit(1)
+    })
+}

package/src/tests/tests.ts

@@ -87,6 +87,7 @@ import { enduser_login_rate_limits_tests } from "./api_tests/enduser_login_rate_
 import { eom_procedure_codes_tests } from "./api_tests/eom_procedure_codes.test";
 import { cross_org_api_key_tests } from "./api_tests/cross_org_api_key.test";
 import { organization_api_keys_tests } from "./api_tests/organization_api_keys.test";
+import { scoped_api_keys_tests } from "./api_tests/scoped_api_keys.test";
 import { custom_dashboards_tests } from "./api_tests/custom_dashboards.test";
 import { message_assignment_trigger_tests } from "./api_tests/message_assignment_trigger.test";
 import { outbound_chat_sent_trigger_tests } from "./api_tests/outbound_chat_sent_trigger.test";
@@ -15084,6 +15085,7 @@ const ip_address_form_tests = async () => {
     await eom_procedure_codes_tests({ sdk, sdkNonAdmin })
     await cross_org_api_key_tests({ sdk, sdkNonAdmin })
     await organization_api_keys_tests({ sdk, sdkNonAdmin })
+    await scoped_api_keys_tests({ sdk, sdkNonAdmin })
     await organization_settings_duplicates_tests({ sdk, sdkNonAdmin })
     await enduser_session_invalidation_tests({ sdk, sdkNonAdmin })
     await chats_analytics_tests({ sdk, sdkNonAdmin })