@tellescope/sdk 1.250.2 → 1.252.0

package/src/tests/api_tests/security/F-0007-invite-user-enumeration.test.ts

@@ -0,0 +1,198 @@
+require('source-map-support').install();
+
+import axios from "axios"
+import { Session } from "../../../sdk"
+import {
+  async_test,
+  log_header,
+  wait,
+} from "@tellescope/testing"
+import { setup_tests } from "../../setup"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+
+const CROSS_ORG_API_KEY = process.env.CROSS_ORG_API_KEY
+const CROSS_ORG_TARGET_BUSINESS_ID = process.env.CROSS_ORG_TARGET_BUSINESS_ID
+
+const post = async (path: string, body: any, headers: Record<string, string> = {}) => {
+  try {
+    const res = await axios.post(`${host}${path}`, body, {
+      validateStatus: () => true,
+      headers,
+    })
+    return { status: res.status, data: res.data }
+  } catch (err: any) {
+    return { status: err?.response?.status, data: err?.response?.data }
+  }
+}
+
+/**
+ * Regression test for F-0007 (security-audit/findings/F-0007-invite-user-cross-tenant-email-enumeration.md).
+ *
+ * `users.invite_user` previously used `buildAllQueries({ unrestricted: true, organizationIds: [] }).users.findOne({ email })`
+ * to enforce platform-wide email uniqueness and threw the distinctive `"A user with this email already exists"`
+ * error on duplicate — regardless of which tenant the existing user was in. Any authenticated user could
+ * therefore probe whether email X is registered to any tenant on the platform.
+ *
+ * **Tests only the negative case** — never drives a successful invite (which would create a real user
+ * record and send a real transactional email). All assertions use either:
+ *   - An email that already exists in the test tenant (the admin's own email), so each call short-circuits
+ *     at the same-tenant duplicate check or rate-limit check before any invite work happens, OR
+ *   - The cross-org infrastructure (CROSS_ORG_API_KEY env var) targeting an email that exists in a different
+ *     tenant — verifies the post-fix response does NOT distinguish "exists elsewhere" from a generic outcome.
+ *
+ * Assertions:
+ *   1. Rate-limit defense-in-depth: rapid same-tenant duplicate requests trip 429 within ~12 attempts.
+ *   2. Same-tenant duplicate: returns the same `"already exists"` error pre/post-fix (this branch is
+ *      unchanged by the fix; asserted for regression-safety).
+ *   3. Cross-tenant duplicate (env-gated): post-fix response shape does NOT contain the `"already exists"`
+ *      string and matches the silent-no-op shape `{ created: { id: ... } }`. Skipped when CROSS_ORG_*
+ *      env vars are not set, mirroring cross_org_api_key.test.ts convention.
+ */
+export const invite_user_enumeration_tests = async ({ sdk, sdkNonAdmin } : { sdk: Session, sdkNonAdmin: Session }) => {
+  log_header("F-0007: users.invite_user cross-tenant enumeration regression")
+
+  // Reset state so prior tests' rate-limit accounting doesn't leak in.
+  await sdk.reset_db()
+
+  const organizationId = sdk.userInfo.organizationIds?.[0] ?? sdk.userInfo.businessId
+  // Use the test admin's own email — guaranteed to exist in the test tenant, so every invite
+  // request short-circuits at the same-tenant duplicate check (or earlier at the rate-limit
+  // check). No real users get created, no emails get sent.
+  const sameTenantExistingEmail = process.env.TEST_EMAIL!
+
+  // ====================================================================
+  // Assertion 1: rate-limit defense-in-depth
+  // Fire 15 requests with the admin's own email. Post-fix: rate limit
+  // fires before the same-tenant duplicate check on call 11+. Pre-fix:
+  // every call returns 400 "already exists" forever.
+  // ====================================================================
+  let rateLimitedAt = -1
+  for (let i = 0; i < 15; i++) {
+    const r = await post(
+      '/v1/invite-user-to-organization',
+      {
+        email: sameTenantExistingEmail,
+        fname: 'F0007', lname: 'RateLimit',
+        organizationId,
+      },
+      { Authorization: `Bearer ${sdk.authToken}` },
+    )
+    if (r.status === 429) {
+      rateLimitedAt = i
+      break
+    }
+  }
+
+  await async_test(
+    "F-0007: invite_user rate-limits within ~12 rapid requests (defense-in-depth; no invites sent)",
+    async () => ({ rateLimitedAt }),
+    { onResult: r => r.rateLimitedAt >= 0 && r.rateLimitedAt <= 12 },
+  )
+
+  // ====================================================================
+  // Assertion 2: same-tenant duplicate returns the descriptive error
+  // (unchanged by the fix; regression guard so a future change to the
+  // duplicate-detection path doesn't accidentally suppress same-tenant
+  // errors that operators rely on).
+  // ====================================================================
+  // Let rate limit decay so this single call isn't blocked.
+  await wait(undefined, 5000)
+  await sdk.reset_db()
+
+  const sameTenantRes = await post(
+    '/v1/invite-user-to-organization',
+    {
+      email: sameTenantExistingEmail,
+      fname: 'F0007', lname: 'SameTenant',
+      organizationId,
+    },
+    { Authorization: `Bearer ${sdk.authToken}` },
+  )
+
+  await async_test(
+    "F-0007: invite_user same-tenant duplicate returns 400 'already exists' (unchanged)",
+    async () => ({
+      status: sameTenantRes.status,
+      message: sameTenantRes.data?.message ?? '',
+    }),
+    { onResult: r => r.status === 400 && r.message.toLowerCase().includes('already exists') },
+  )
+
+  // ====================================================================
+  // Assertion 3: cross-tenant duplicate must NOT reveal existence
+  // Env-gated; skipped when cross-org infra not configured.
+  // ====================================================================
+  if (!(CROSS_ORG_API_KEY && CROSS_ORG_TARGET_BUSINESS_ID)) {
+    console.log("  [F-0007] Skipping cross-tenant silent no-op assertion — CROSS_ORG_* env vars not set")
+    return
+  }
+
+  // The target email is the admin's email in the home (test) tenant. We then attempt to invite
+  // that same email FROM a session belonging to the cross-org target tenant. Post-fix, the
+  // response should NOT contain "already exists" — it must be indistinguishable from a
+  // successful invite OR a generic non-revealing response. Pre-fix, the response is the
+  // distinctive "already exists" error revealing cross-tenant existence.
+  const sdkCrossOrg = new Session({
+    host,
+    apiKey: CROSS_ORG_API_KEY,
+    headers: { 'x-tellescope-organization': CROSS_ORG_TARGET_BUSINESS_ID },
+  })
+
+  // Resolve an organizationId in the target business. Falls back to the businessId itself.
+  let targetOrgId = CROSS_ORG_TARGET_BUSINESS_ID
+  try {
+    const orgs = await sdkCrossOrg.api.organizations.getSome({ limit: 1 })
+    if (orgs?.[0]?.id) targetOrgId = orgs[0].id
+  } catch {}
+
+  const crossRes = await post(
+    '/v1/invite-user-to-organization',
+    {
+      email: sameTenantExistingEmail,
+      fname: 'F0007', lname: 'CrossTenantProbe',
+      organizationId: targetOrgId,
+    },
+    {
+      Authorization: `API_KEY ${CROSS_ORG_API_KEY}`,
+      'x-tellescope-organization': CROSS_ORG_TARGET_BUSINESS_ID,
+    },
+  )
+
+  await async_test(
+    "F-0007: cross-tenant invite of existing email must NOT return 'already exists' (no enumeration)",
+    async () => ({
+      status: crossRes.status,
+      message: crossRes.data?.message ?? '',
+      hasCreatedShape: !!crossRes.data?.created?.id,
+    }),
+    {
+      onResult: r =>
+        // The response MUST NOT contain the "already exists" string regardless of status.
+        // Acceptable post-fix shapes: 200 with `{ created: { id: ... } }` (silent no-op), or
+        // 200 with a generic ack. Rate-limit 429 also OK if it slipped through to here.
+        !r.message.toLowerCase().includes('already exists'),
+    },
+  )
+}
+
+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 invite_user_enumeration_tests({ sdk, sdkNonAdmin })
+  }
+
+  runTests()
+    .then(() => {
+      console.log("✅ F-0007 invite_user enumeration test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ F-0007 invite_user enumeration test suite failed:", error)
+      process.exit(1)
+    })
+}

package/src/tests/api_tests/security/F-0008-handle-incoming-communication-cross-tenant.test.ts

@@ -0,0 +1,130 @@
+require('source-map-support').install();
+
+import axios from "axios"
+import { ObjectId } from 'bson'
+import { Session } from "../../../sdk"
+import {
+  async_test,
+  log_header,
+} from "@tellescope/testing"
+import { setup_tests } from "../../setup"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+
+const CROSS_ORG_API_KEY = process.env.CROSS_ORG_API_KEY
+const CROSS_ORG_TARGET_BUSINESS_ID = process.env.CROSS_ORG_TARGET_BUSINESS_ID
+
+const post = async (path: string, body: any, headers: Record<string, string> = {}) => {
+  try {
+    const res = await axios.post(`${host}${path}`, body, {
+      validateStatus: () => true,
+      headers,
+    })
+    return { status: res.status, data: res.data }
+  } catch (err: any) {
+    return { status: err?.response?.status, data: err?.response?.data }
+  }
+}
+
+/**
+ * Regression test for F-0008 (security-audit/findings/F-0008-handle-incoming-communication-cross-tenant-enduser-lookup.md).
+ *
+ * `journeys.handle_incoming_communication` previously used `buildAllQueries({ unrestricted: true, organizationIds: [] }).endusers.findById(enduserId)`,
+ * permitting cross-tenant lookup of any enduser by id. The handler then called `handleIncomingCommunication(...)`
+ * against the matched enduser, triggering journey progression and automated actions on someone else's tenant.
+ *
+ * The fix switches to the standard tenant-scoped `DB.endusers.findById(enduserId)` wrapper, which automatically
+ * filters by `req.session.businessId`. Cross-tenant lookups now return null → handler returns 404 → no side effect.
+ *
+ * Note: the same-tenant happy path is already covered by the existing test at
+ * `packages/public/sdk/src/tests/tests.ts:7588` ("handle_incoming_communication test for other enduser") — that
+ * test creates endusers in the test tenant, sets up journeys, calls handle_incoming_communication, and asserts
+ * journey-step cancellation. This file covers the negative cases only.
+ *
+ * **Negative-only by design**: the test never drives `handleIncomingCommunication` against a cross-tenant
+ * enduser — the post-fix code returns 404 before any side effects fire, and the assertion confirms that.
+ */
+export const handle_incoming_communication_cross_tenant_tests = async ({ sdk, sdkNonAdmin } : { sdk: Session, sdkNonAdmin: Session }) => {
+  log_header("F-0008: handle_incoming_communication cross-tenant rejection")
+
+  // ====================================================================
+  // Assertion 1: nonexistent enduserId returns 404 (baseline; regression
+  // guard for the not-found path that any cross-tenant call now lands in).
+  // ====================================================================
+  const nonexistentId = new ObjectId().toHexString()
+  const nonexistentRes = await post(
+    '/v1/journeys/handle-incoming-communication',
+    { enduserId: nonexistentId },
+    { Authorization: `Bearer ${sdk.authToken}` },
+  )
+  await async_test(
+    "F-0008: handle_incoming_communication with nonexistent enduserId returns 404",
+    async () => ({ status: nonexistentRes.status }),
+    { onResult: r => r.status === 404 },
+  )
+
+  // ====================================================================
+  // Assertion 2: cross-tenant enduserId returns 404 (the actual F-0008 fix).
+  // Env-gated; skipped when cross-org infra isn't configured.
+  // Safe to run post-fix because the tenant-scoped DB returns null for
+  // cross-tenant lookups — no handleIncomingCommunication side effect fires.
+  // ====================================================================
+  if (!(CROSS_ORG_API_KEY && CROSS_ORG_TARGET_BUSINESS_ID)) {
+    console.log("  [F-0008] Skipping cross-tenant rejection assertion — CROSS_ORG_* env vars not set")
+    return
+  }
+
+  const sdkCrossOrg = new Session({
+    host,
+    apiKey: CROSS_ORG_API_KEY,
+    headers: { 'x-tellescope-organization': CROSS_ORG_TARGET_BUSINESS_ID },
+  })
+
+  // Create a sentinel enduser in the cross-org tenant. Use a clearly-test email
+  // so any accidental side-effect routing is obvious in logs.
+  const ts = Date.now()
+  const crossEnduser = await sdkCrossOrg.api.endusers.createOne({
+    fname: 'F0008CrossTenant', lname: 'Sentinel',
+    email: `f0008-cross-${ts}@tellescope.com`,
+  } as any)
+
+  try {
+    const crossRes = await post(
+      '/v1/journeys/handle-incoming-communication',
+      { enduserId: crossEnduser.id },
+      { Authorization: `Bearer ${sdk.authToken}` },
+    )
+
+    await async_test(
+      "F-0008: handle_incoming_communication with cross-tenant enduserId returns 404 (no side effect)",
+      async () => ({
+        status: crossRes.status,
+        message: crossRes.data?.message ?? null,
+      }),
+      { onResult: r => r.status === 404 },
+    )
+  } finally {
+    try { await sdkCrossOrg.api.endusers.deleteOne(crossEnduser.id) } 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 handle_incoming_communication_cross_tenant_tests({ sdk, sdkNonAdmin })
+  }
+
+  runTests()
+    .then(() => {
+      console.log("✅ F-0008 handle_incoming_communication cross-tenant test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ F-0008 handle_incoming_communication cross-tenant test suite failed:", error)
+      process.exit(1)
+    })
+}

package/src/tests/api_tests/security/F-0013-sanitize-user-html.test.ts

@@ -0,0 +1,109 @@
+import { sanitize_user_html } from "@tellescope/utilities"
+
+// Regression test for F-0013 / F-0014 (pattern 06 — XSS via dangerouslySetInnerHTML).
+// sanitize_user_html is the canonical render-time sanitizer that replaced remove_script_tags
+// at every dangerouslySetInnerHTML sink. This asserts it neutralizes XSS vectors (incl. encoded /
+// whitespace / mixed-case / iframe-srcdoc bypass variants) while preserving legitimate
+// customization HTML (tables, headings, lists, links, images, inline styles).
+//
+// Pure-function test — no Session needed. Runs as part of the main suite and standalone:
+//   ./build_cjs.sh && cd packages/public/sdk && node -r dotenv/config lib/cjs/tests/api_tests/security/F-0013-sanitize-user-html.test.js
+
+const fail = (msg: string) => { throw new Error(msg) }
+
+const has_no_executable_vector = (out: string) => {
+  const o = out.toLowerCase()
+  // A handler smuggled into an attribute VALUE (e.g. title="<img onerror=...>") is inert
+  // text — strip quoted values before checking for *live* on*= attributes to avoid false positives.
+  const withoutValues = o.replace(/"[^"]*"/g, '""').replace(/'[^']*'/g, "''")
+  return !/\son[a-z]+\s*=/.test(withoutValues)   // no live on*= event-handler attribute
+      && !o.includes('javascript:')              // dropped schemes never appear in safe output
+      && !o.includes('vbscript:')
+      && !o.includes('<script')                  // literal dangerous tags (encoded &lt;script is fine)
+      && !o.includes('<iframe')
+      && !o.includes('<svg')
+      && !o.includes('<math')
+      && !o.includes('<object')
+      && !o.includes('<embed')
+      && !o.includes('<form')
+      && !o.includes('<noscript')
+      && !o.includes('<template')
+}
+
+export const sanitize_user_html_xss_tests = async () => {
+  console.log("Running F-0013/F-0014 sanitize_user_html XSS regression tests")
+
+  const xssPayloads: [string, string][] = [
+    ['img onerror', `<img src=x onerror="alert(document.domain)">`],
+    ['svg onload', `<svg onload="alert(1)"></svg>`],
+    ['svg animate onbegin', `<svg><animate onbegin="alert(1)" attributeName="x" dur="1s"></svg>`],
+    ['details ontoggle', `<details open ontoggle="alert(1)"></details>`],
+    ['input onfocus autofocus', `<input autofocus onfocus="alert(1)">`],
+    ['body onpageshow', `<body onpageshow="alert(1)">`],
+    ['a javascript scheme', `<a href="javascript:alert(1)">x</a>`],
+    ['a javascript entity-encoded', `<a href="jav&#x09;ascript:alert(1)">x</a>`],
+    ['iframe javascript src', `<iframe src="javascript:alert(1)"></iframe>`],
+    ['iframe srcdoc nested', `<iframe srcdoc="<img src=x onerror=alert(1)>"></iframe>`],
+    ['script tag', `<script>alert(1)</script>`],
+    ['onerror newline before =', `<img src=x onerror\n="alert(1)">`],
+    ['onerror mixed case', `<IMG SRC=x OnErRoR="alert(1)">`],
+    ['marquee onstart', `<marquee onstart="alert(1)">x</marquee>`],
+    // mutation / namespace confusion — svg/math/noscript/template must be stripped
+    ['mathml mglyph style mxss', `<math><mtext><table><mglyph><style><!--</style><img src=x onerror=alert(1)>`],
+    ['svg foreignObject', `<svg><foreignObject><img src=x onerror=alert(1)></foreignObject></svg>`],
+    ['noscript context confusion', `<noscript><p title="</noscript><img src=x onerror=alert(1)>">`],
+    ['template content', `<template><img src=x onerror=alert(1)></template>`],
+    // comment / CDATA confusion
+    ['comment confusion', `<!--><img src=x onerror=alert(1)>-->`],
+    ['cdata confusion', `<![CDATA[<img src=x onerror=alert(1)>]]>`],
+    // markup smuggled inside an attribute value must stay inert
+    ['markup inside attr value', `<img src="x" alt="<script>alert(1)</script>">`],
+    // protocol obfuscation
+    ['vbscript scheme', `<a href="vbscript:msgbox(1)">x</a>`],
+    ['data text/html href', `<a href="data:text/html,<script>alert(1)</script>">x</a>`],
+    ['javascript decimal entity', `<a href="&#74;avascript:alert(1)">x</a>`],
+    ['javascript newline entity', `<a href="jav&#x0A;ascript:alert(1)">x</a>`],
+  ]
+  for (const [name, payload] of xssPayloads) {
+    const out = sanitize_user_html(payload)
+    if (!has_no_executable_vector(out)) fail(`XSS not neutralized [${name}] -> ${out}`)
+  }
+
+  // DOM clobbering: caller-controlled id/name must be stripped
+  const clobber = sanitize_user_html(`<a id="x" name="getElementById">link</a><img name="y">`)
+  if (/\b(id|name)\s*=/.test(clobber)) fail(`id/name not stripped (DOM clobbering): ${clobber}`)
+
+  // legitimate customization HTML must survive
+  const heading = sanitize_user_html(`<h1>Welcome</h1><h3 style="color:#333">Sub</h3>`)
+  if (!(heading.includes('<h1>') && heading.includes('<h3') && heading.toLowerCase().includes('color'))) fail(`headings/style stripped: ${heading}`)
+
+  const table = sanitize_user_html(`<table><thead><tr><th>H</th></tr></thead><tbody><tr><td style="padding:4px" colspan="2">cell</td></tr></tbody></table>`)
+  if (!(table.includes('<table') && table.includes('<td') && table.includes('colspan'))) fail(`table stripped: ${table}`)
+
+  const list = sanitize_user_html(`<ul><li>a</li></ul><ol start="3"><li>c</li></ol>`)
+  if (!(list.includes('<ul') && list.includes('<li') && list.includes('<ol'))) fail(`list stripped: ${list}`)
+
+  const link = sanitize_user_html(`<a href="https://example.com">link</a>`)
+  if (!link.includes('href="https://example.com"')) fail(`safe link stripped: ${link}`)
+  if (!link.toLowerCase().includes('noopener')) fail(`external link not hardened: ${link}`)
+
+  const img = sanitize_user_html(`<img src="https://cdn.example.com/a.png" alt="pic" width="200">`)
+  if (!(img.includes('src="https://cdn.example.com/a.png"') && img.includes('alt="pic"'))) fail(`http image stripped: ${img}`)
+
+  const dataimg = sanitize_user_html(`<img src="data:image/png;base64,iVBORw0KGgo=">`)
+  if (!dataimg.includes('data:image/png')) fail(`data: image stripped: ${dataimg}`)
+
+  const fmt = sanitize_user_html(`<p><strong>b</strong> <em>i</em> <span style="font-size:14px">s</span></p><blockquote>q</blockquote>`)
+  if (!(fmt.includes('<strong>') && fmt.includes('<span') && fmt.toLowerCase().includes('font-size'))) fail(`formatting stripped: ${fmt}`)
+
+  const mixed = sanitize_user_html(`<p>Hello <b>name</b></p><img src=x onerror="steal()">`)
+  if (!(mixed.includes('<b>name</b>') && !/\son[a-z]+\s*=/.test(mixed.toLowerCase()))) fail(`mixed content not handled: ${mixed}`)
+
+  console.log("✅ F-0013/F-0014 sanitize_user_html XSS regression tests passed")
+}
+
+if (require.main === module) {
+  sanitize_user_html_xss_tests()
+    .then(() => { console.log("✅ suite completed"); process.exit(0) })
+    .catch((err) => { console.error("❌ suite failed:", err); process.exit(1) })
+}

package/src/tests/api_tests/security/F-0016-prototype-pollution.test.ts

@@ -0,0 +1,50 @@
+import { add_value_for_dotted_key } from "@tellescope/utilities"
+
+// Regression test for F-0016 (pattern 17 — prototype pollution).
+// add_value_for_dotted_key must NOT write through __proto__/constructor/prototype path segments
+// (which would pollute Object.prototype process-wide), while still performing legitimate dotted assignment.
+//
+// Pure-function test — no Session needed. Runs in the main suite and standalone:
+//   ./build_cjs.sh && cd packages/public/sdk && node -r dotenv/config lib/cjs/tests/api_tests/security/F-0016-prototype-pollution.test.js
+
+const fail = (msg: string) => { throw new Error(msg) }
+
+export const prototype_pollution_tests = async () => {
+  console.log("Running F-0016 prototype-pollution regression tests")
+
+  // 1. __proto__ path must not pollute Object.prototype
+  add_value_for_dotted_key({ insurance: {} } as any, 'insurance.__proto__.__pp_a__', 'polluted')
+  const leakedA = ({} as any).__pp_a__
+  delete (Object.prototype as any).__pp_a__ // clean up regardless, so a failure here can't contaminate the rest of the suite
+  if (leakedA !== undefined) fail('Object.prototype polluted via __proto__ path')
+
+  // 2. constructor.prototype path must not pollute
+  add_value_for_dotted_key({ insurance: {} } as any, 'insurance.constructor.prototype.__pp_b__', 'polluted')
+  const leakedB = ({} as any).__pp_b__
+  delete (Object.prototype as any).__pp_b__
+  if (leakedB !== undefined) fail('Object.prototype polluted via constructor.prototype path')
+
+  // 3. a leading __proto__ segment must not pollute either
+  add_value_for_dotted_key({} as any, '__proto__.__pp_c__', 'polluted')
+  const leakedC = ({} as any).__pp_c__
+  delete (Object.prototype as any).__pp_c__
+  if (leakedC !== undefined) fail('Object.prototype polluted via leading __proto__ segment')
+
+  // 4. legitimate dotted assignment still works (existing intermediate objects)
+  const obj = { a: { b: {} } } as any
+  add_value_for_dotted_key(obj, 'a.b.c', 42)
+  if (obj.a.b.c !== 42) fail('legitimate dotted assignment broke')
+
+  // 5. single-key assignment still works
+  const flat = {} as any
+  add_value_for_dotted_key(flat, 'name', 'ok')
+  if (flat.name !== 'ok') fail('single-key assignment broke')
+
+  console.log("✅ F-0016 prototype-pollution regression tests passed")
+}
+
+if (require.main === module) {
+  prototype_pollution_tests()
+    .then(() => { console.log("✅ suite completed"); process.exit(0) })
+    .catch((err) => { console.error("❌ suite failed:", err); process.exit(1) })
+}