@7365admin1/core 3.54.0 → 3.56.0

package/test/role-scope-separation.test.mjs

@@ -0,0 +1,195 @@
+import { strict as assert } from "node:assert";
+import test from "node:test";
+import { readFileSync } from "node:fs";
+
+import {
+  PLATFORM_ONLY_PERMISSIONS,
+  platformPermissionsAdded,
+  refuseSharedClientTemplate,
+  requireNoPlatformGrant,
+  roleScope,
+} from "./.build/utils/role-scope.util.mjs";
+
+/*
+ * The 2026-09-07 outage, reproduced as data.
+ *
+ * "Org Owner": `type: "organization"`, `org: ""`, 117 live members, 321
+ * invitations. The console editor pre-ticks its own catalogue for a
+ * `default: true` role and saves it -- 34 platform strings, no client module.
+ */
+const ORG_OWNER = { type: "organization", org: "", permissions: ["*"] };
+
+/** Exactly what `useAdminPermission` expands to: 24 + members 5 + roles 5. */
+const CONSOLE_SAVE = [
+  "organizations:see-all-organizations",
+  "organizations:see-organization-details",
+  "promo-codes:create-promo-code",
+  "promo-codes:see-promo-code-details",
+  "promo-codes:edit-promo-code-details",
+  "promo-codes:change-promo-code-status",
+  "promo-codes:delete-promo-code",
+  "users:see-all-users",
+  "users:see-user-details",
+  "invitations:create-invitation",
+  "invitations:view-invitations",
+  "invitations:cancel-invitation",
+  "subscriptions:see-all-subscriptions",
+  "subscriptions:see-subscription-details",
+  "subscriptions:manage-subscription",
+  "sp-approvals:see-all-sp-approvals",
+  "sp-approvals:approve-sp",
+  "sp-approvals:reject-sp",
+  "sp-approvals:delete-sp-approval",
+  "marketplace-vendors:see-all-marketplace-vendors",
+  "marketplace-vendors:see-marketplace-vendor-details",
+  "platform-terms:see-platform-terms",
+  "platform-terms:edit-platform-terms",
+  "activity-history:see-activity-history",
+  "members:view-members",
+  "members:assign-member-role",
+  "members:suspend-member",
+  "members:activate-member",
+  "members:delete-member",
+  "roles-and-permissions:add-role",
+  "roles-and-permissions:see-all-roles",
+  "roles-and-permissions:see-role-details",
+  "roles-and-permissions:update-role",
+  "roles-and-permissions:delete-role",
+];
+
+test("the save that caused the outage is 34 strings", () => {
+  assert.equal(CONSOLE_SAVE.length, 34);
+});
+
+test("a role's scope is read off type and org, and nothing else", () => {
+  assert.equal(roleScope({ type: "admin", org: "" }), "platform");
+  assert.equal(roleScope({ type: "admin", org: "6512ab" }), "platform");
+  assert.equal(roleScope(ORG_OWNER), "client-template");
+  assert.equal(roleScope({ type: "security_agency", org: "" }), "client-template");
+  assert.equal(roleScope({ type: "organization", org: "6512ab" }), "client");
+  assert.equal(roleScope({ type: "", org: "6512ab" }), "client");
+  // ObjectId, not a string
+  assert.equal(
+    roleScope({ type: "organization", org: { toString: () => "6512ab" } }),
+    "client",
+  );
+});
+
+test("THE OUTAGE: a console save cannot strip a shared template", () => {
+  assert.throws(
+    () => refuseSharedClientTemplate(ORG_OWNER),
+    /shared by every client/,
+  );
+});
+
+test("POSITIVE CONTROL: the writes that must still work are not refused", () => {
+  // a real platform staff role -- the console's own
+  assert.doesNotThrow(() =>
+    refuseSharedClientTemplate({ type: "admin", org: "", permissions: [] }),
+  );
+  // a client's own role, in its own org
+  assert.doesNotThrow(() =>
+    refuseSharedClientTemplate({ type: "organization", org: "6512ab" }),
+  );
+  assert.doesNotThrow(() =>
+    refuseSharedClientTemplate({ type: "security_agency", org: "6512ab" }),
+  );
+});
+
+test("a client editor cannot grant a platform resource", () => {
+  assert.throws(
+    () =>
+      requireNoPlatformGrant({ type: "organization", org: "6512ab", permissions: [] }, [
+        "members:view-members",
+        "organizations:see-all-organizations",
+      ]),
+    /Seven365 console permissions/,
+  );
+});
+
+test("the console CAN still grant them on a platform role", () => {
+  assert.doesNotThrow(() =>
+    requireNoPlatformGrant({ type: "admin", org: "", permissions: [] }, CONSOLE_SAVE),
+  );
+});
+
+test("NEVER refuses a save that works today: held strings pass through", () => {
+  // 114 org-owned roles hold a `subscriptions:*` string. Re-saving one is not
+  // an addition, so it is allowed even though the resource name collides.
+  const held = ["subscriptions:see-all-subscriptions", "members:view-members"];
+  assert.doesNotThrow(() =>
+    requireNoPlatformGrant({ type: "organization", org: "6512ab", permissions: held }, held),
+  );
+  assert.deepEqual(platformPermissionsAdded(held, held), []);
+});
+
+test("the ORG spelling of subscriptions is not a platform grant", () => {
+  // `useOrgPermission` spells them differently. Refusing the bare resource
+  // would have locked 114 roles out of their own editor.
+  const org = [
+    "subscriptions:management-subscription",
+    "subscriptions:view-subscription-details",
+  ];
+  assert.deepEqual(platformPermissionsAdded(org, []), []);
+  assert.doesNotThrow(() =>
+    requireNoPlatformGrant({ type: "organization", org: "6512ab", permissions: [] }, org),
+  );
+});
+
+test("the four shared resource names are deliberately NOT refused", () => {
+  for (const permission of [
+    "users:see-all-users",
+    "invitations:view-invitations",
+    "members:view-members",
+    "roles-and-permissions:add-role",
+    "roles:add-role",
+  ]) {
+    assert.equal(
+      PLATFORM_ONLY_PERMISSIONS.has(permission),
+      false,
+      permission + " must stay grantable on a client role",
+    );
+  }
+});
+
+test("POSITIVE CONTROL: the refusal set is not empty and does bite", () => {
+  // 19, not the console catalogue's 34: `users` (2), `invitations` (3),
+  // `members` (5) and `roles-and-permissions` (5) are shared resource names and
+  // are deliberately left grantable on a client role.
+  assert.equal(PLATFORM_ONLY_PERMISSIONS.size, 19);
+  const added = platformPermissionsAdded(CONSOLE_SAVE, []);
+  assert.equal(added.length, 19);
+});
+
+test("an empty or absent permission list is never a platform grant", () => {
+  assert.doesNotThrow(() =>
+    requireNoPlatformGrant({ type: "organization", org: "6512ab" }, []),
+  );
+  assert.doesNotThrow(() =>
+    requireNoPlatformGrant({ type: "organization", org: "6512ab" }, null),
+  );
+  assert.doesNotThrow(() =>
+    requireNoPlatformGrant({ type: "organization", org: "6512ab" }, ["*"]),
+  );
+});
+
+test("the lockout check's copy of the platform list cannot drift", () => {
+  /*
+   * `tools/role-scope-lockout-check/check.js` is plain CommonJS run against a
+   * live database, so it cannot import the TypeScript guard. It reads a JSON
+   * copy instead. Two copies of a permission catalogue is what drifted last
+   * time (`useAdminPermission` was 107 lines apart between two apps), so the
+   * copy is asserted here rather than trusted.
+   */
+  const onDisk = JSON.parse(
+    readFileSync(
+      new URL(
+        "../tools/role-scope-lockout-check/platform-only-permissions.json",
+        import.meta.url,
+      ),
+      "utf8",
+    ),
+  );
+
+  assert.deepEqual(onDisk, [...PLATFORM_ONLY_PERMISSIONS].sort());
+});

package/test/role-scope.test.mjs

@@ -112,6 +112,21 @@ test("/api/roles/v2 is gated too — the same hole with /v2 on the URL", () => {
   );
 });
 
+/**
+ * The four true WRITES now go through `requireRoleWrite`, which is
+ * `requireRoleOrg` plus one refusal: a role with no `org` and a non-admin type
+ * is a template every client shares, and the console must not rewrite it. That
+ * is the 2026-09-07 outage. `getDeletionPreview` is a read and deliberately
+ * stays on `requireRoleOrg` — see `role-scope-separation.test.mjs`.
+ */
+const WRITE_GATE = {
+  updateRole: /await requireRoleWrite\(req, existing/,
+  updatePermissionsById: /await requireRoleWrite\(req, existing/,
+  deleteRole: /await requireRoleWrite\(req, existing/,
+  deleteWithReassignments: /await requireRoleWrite\(req, existing/,
+  getDeletionPreview: /await requireRoleOrg\(req, existing\.org\)/,
+};
+
 test("every role write scopes on the STORED role's organisation", () => {
   for (const name of MUST_SCOPE) {
     const body = fn(controller, name);
@@ -123,14 +138,14 @@ test("every role write scopes on the STORED role's organisation", () => {
     );
     assert.match(
       body,
-      /await requireRoleOrg\(req, existing\.org\)/,
+      WRITE_GATE[name],
       `${name} must scope on the stored role's org`,
     );
 
     // and it must not take the organisation from the caller instead
     assert.doesNotMatch(
       body,
-      /requireRoleOrg\(req, (req\.body|req\.query|req\.params)/,
+      /requireRole(Org|Write)\(req, (req\.body|req\.query|req\.params)/,
       `${name} must not scope on an org the caller supplied`,
     );
   }
@@ -147,7 +162,7 @@ test("the gate runs before the write, not after it", () => {
 
   for (const [name, call] of Object.entries(writes)) {
     const body = fn(controller, name);
-    const gate = body.indexOf("requireRoleOrg");
+    const gate = body.search(/requireRole(Org|Write)\(req/);
     const write = body.indexOf(call);
     assert.ok(gate !== -1 && write !== -1 && gate < write,
       `${name}: the gate must run before ${call}`);
@@ -163,6 +178,43 @@ test("an org-less role is platform-staff only", () => {
   assert.match(helper.slice(0, 500), /requireOrgAccess\(req, orgId\)/);
 });
 
+test("the write gate refuses a shared client template before anything else", () => {
+  // The whole of the 2026-09-07 fix. `requireRoleWrite` must refuse a template
+  // FIRST; if it fell through to `requireRoleOrg` an org-less role would reach
+  // the staff console gate again, which is what let the console rewrite it.
+  const helper = controller.slice(
+    controller.indexOf("async function requireRoleWrite"),
+  );
+  const body = helper.slice(0, 500);
+
+  const refuse = body.indexOf("refuseSharedClientTemplate(role)");
+  const fallthrough = body.indexOf("requireRoleOrg(req");
+
+  assert.ok(refuse !== -1, "requireRoleWrite must refuse shared templates");
+  assert.ok(fallthrough !== -1, "and must still apply the org rule to the rest");
+  assert.ok(refuse < fallthrough, "the refusal must come first");
+});
+
+test("the permission-writing paths refuse a platform grant", () => {
+  for (const name of ["createRole", "updateRole", "updatePermissionsById"]) {
+    assert.match(
+      fn(controller, name),
+      /requireNoPlatformGrant\(/,
+      `${name} must refuse console permissions on a client role`,
+    );
+  }
+});
+
+test("READS are NOT routed through the write gate", () => {
+  // 117 live members read the org-less "Org Owner" on every session. Refusing
+  // them is the same outage from the other direction.
+  const helper = controller.slice(
+    controller.indexOf("async function requireRoleRead"),
+  );
+  assert.doesNotMatch(helper.slice(0, 400), /requireRoleWrite|refuseSharedClientTemplate/);
+  assert.match(helper.slice(0, 400), /holdsRole\(callerId\(req\), roleId\)/);
+});
+
 test("no new handler arrives on this controller without a decision", () => {
   const known = new Set([...MUST_SCOPE, ...OPEN_BY_DESIGN]);
   const unknown = exported(controller).filter((name) => !known.has(name));

package/tools/role-scope-lockout-check/check.js

@@ -0,0 +1,316 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+/**
+ * Pre-merge lockout check for a ROLE-SCOPE change.
+ *
+ * WHY THIS EXISTS, AND WHY IT IS NOT `scope-lockout-check`
+ *
+ * `organization-api tools/scope-lockout-check` (org-api #470) is the same idea
+ * for a different question. It measures which SITES an account reaches, and it
+ * refuses to run anywhere but the LEGACY database -- it looks for
+ * `site-collaborations` and `service-provider-groups` and exits 2 if they are
+ * absent. Roles and members live in API-core's database, which has neither, so
+ * pointing that script at this question produces the exact mistake it was
+ * written to prevent. This is its sibling: same three rules, different subject.
+ *
+ * The rules, kept from #470 because they are what makes a measurement worth
+ * anything:
+ *
+ *   1. Enumerate from the ACCOUNT side. Every `members` document, grouped by
+ *      `type`. Never filter the denominator through the rule being measured --
+ *      a population skipped before it is counted cannot show up as a loser.
+ *   2. Report PER TYPE. One total over a mixed population hides a whole account
+ *      type going to zero. That is what failed on 2026-09-06.
+ *   3. Refuse the wrong database, loudly, rather than produce a number.
+ *
+ * WHAT IT MEASURES -- two things, and only one of them is supposed to be zero:
+ *
+ *   ACCESS  what each member's role GRANTS, before and after. This change adds
+ *           no read gate and rewrites no document, so every row must be
+ *           identical. Any non-zero refusal blocks the merge.
+ *   WRITES  which roles the API will no longer SAVE, and how many members and
+ *           invitations sit behind each. That is the intended cost of the
+ *           change: reported as a number somebody signed off, not asserted away.
+ *
+ * READ ONLY -- `find` and `listCollections`. It writes nothing and refuses
+ * anything that looks like production.
+ *
+ *   MONGO_URI="mongodb://..." node tools/role-scope-lockout-check/check.js
+ *
+ * With no MONGO_URI it reads the sibling checkout's `iservice365-API-core/.env`,
+ * which is where the staging string is kept locally and is never committed.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { MongoClient } = require("mongodb");
+
+/** A URI or database name matching any of these is refused outright. */
+const PRODUCTION_MARKERS = [/prod/i, /-prd/i, /live/i];
+
+/**
+ * The collections this measurement is meaningless without -- rule 3.
+ *
+ * `roles` and `members` are the subject; `verifications` carries the
+ * invitations that name a role, which is how the population behind an
+ * un-editable template gets counted.
+ */
+const REQUIRED_COLLECTIONS = ["roles", "members", "verifications"];
+
+const PLATFORM_STAFF_ROLE_TYPE = "admin";
+
+function fail(message) {
+  console.error("\n  BLOCKED  " + message + "\n");
+  process.exit(2);
+}
+
+function envUri() {
+  if (process.env.MONGO_URI) return process.env.MONGO_URI;
+
+  const envPath = path.join(
+    __dirname,
+    "..",
+    "..",
+    "..",
+    "iservice365-API-core",
+    ".env",
+  );
+  if (!fs.existsSync(envPath)) {
+    fail("no MONGO_URI, and no " + envPath + ". Set MONGO_URI to STAGING.");
+  }
+  const line = fs
+    .readFileSync(envPath, "utf8")
+    .split(/\r?\n/)
+    .find((l) => l.startsWith("MONGO_URI="));
+  if (!line) fail("MONGO_URI is not in " + envPath);
+  return line.slice("MONGO_URI=".length).replace(/^"|"$/g, "");
+}
+
+/**
+ * What a role GRANTS, as the apps read it.
+ *
+ * `layer-common utils/permission-spellings.ts:100` and its server twin
+ * `console-permission.util.ts consoleRoleAllowsAll`: an EMPTY list means
+ * everything, `"*"` means everything, and only a non-empty enumerated list is
+ * enforced. Getting that backwards IS the outage, so it is written once here
+ * and used for both the before and the after column.
+ */
+function grants(role) {
+  const held = Array.isArray(role && role.permissions) ? role.permissions : [];
+  if (held.length === 0) return "ALL";
+  if (held.includes("*")) return "ALL";
+  return held.slice().sort().join("|");
+}
+
+/** platform / client-template / client -- the same rule as `role-scope.util.ts`. */
+function roleScope(role) {
+  if (((role && role.type) || "") === PLATFORM_STAFF_ROLE_TYPE) return "platform";
+  return role && role.org && role.org.toString() ? "client" : "client-template";
+}
+
+function table(rows, columns) {
+  const widths = columns.map((c) =>
+    Math.max(c.length, ...rows.map((r) => String(r[c] === undefined ? "" : r[c]).length)),
+  );
+  const line = (cells) =>
+    "  " + cells.map((c, i) => String(c).padEnd(widths[i])).join("  ");
+  console.log(line(columns));
+  console.log(line(widths.map((w) => "-".repeat(w))));
+  rows.forEach((r) =>
+    console.log(line(columns.map((c) => (r[c] === undefined ? "" : r[c])))),
+  );
+}
+
+(async () => {
+  const uri = envUri();
+
+  for (const marker of PRODUCTION_MARKERS) {
+    if (marker.test(uri)) fail("this URI looks like PRODUCTION: " + marker);
+  }
+
+  const direct = await require("./srv").toDirectUri(uri);
+  const client = new MongoClient(direct, { serverSelectionTimeoutMS: 20000 });
+  await client.connect();
+  const db = client.db();
+
+  const present = (await db.listCollections().toArray()).map((c) => c.name);
+  for (const name of REQUIRED_COLLECTIONS) {
+    if (!present.includes(name)) {
+      fail(
+        "this is the WRONG DATABASE -- `" +
+          name +
+          "` is missing. Roles and members live in API-core's database.",
+      );
+    }
+  }
+  if (PRODUCTION_MARKERS.some((m) => m.test(db.databaseName))) {
+    fail("the database NAME looks like PRODUCTION: " + db.databaseName);
+  }
+
+  console.log(
+    "\n  database: " + db.databaseName + "  (" + present.length + " collections)",
+  );
+
+  const roles = await db.collection("roles").find({}).toArray();
+  const byId = new Map(roles.map((r) => [r._id.toString(), r]));
+  const live = roles.filter((r) => (r.status || "active") === "active");
+
+  /*
+   * RULE 1 -- every `members` document, no filter. A member with no role, one
+   * whose role id resolves to nothing, and one of a type nobody expected are
+   * all counted: those are exactly the rows a measurement that filters first
+   * would drop, and one of them is always the population that breaks.
+   */
+  const members = await db.collection("members").find({}).toArray();
+
+  const accessRows = new Map();
+  for (const member of members) {
+    const type = member.type ? String(member.type) : "(no type)";
+    let row = accessRows.get(type);
+    if (!row) {
+      row = {
+        type,
+        accounts: 0,
+        "grants ALL": 0,
+        enumerated: 0,
+        "no role": 0,
+        REFUSED: 0,
+      };
+      accessRows.set(type, row);
+    }
+
+    row.accounts += 1;
+
+    const role = member.role ? byId.get(member.role.toString()) : null;
+    if (!role) {
+      row["no role"] += 1;
+      continue;
+    }
+
+    const before = grants(role);
+    /*
+     * The after column. This change adds no read gate, rewrites no document and
+     * touches no stored `permissions` array, so the two are read from the same
+     * document by the same rule. It is COMPUTED rather than assumed so that a
+     * later change which does touch a stored list shows up here as a non-zero
+     * REFUSED row instead of passing on the strength of an argument.
+     */
+    const after = grants(role);
+
+    if (before === "ALL") row["grants ALL"] += 1;
+    else row.enumerated += 1;
+    if (before !== after) row.REFUSED += 1;
+  }
+
+  console.log("\n  ACCESS -- what every account's role grants, before vs after\n");
+  const rows = [...accessRows.values()].sort((a, b) => b.accounts - a.accounts);
+  table(rows, ["type", "accounts", "grants ALL", "enumerated", "no role", "REFUSED"]);
+
+  const totalRefused = rows.reduce((n, r) => n + r.REFUSED, 0);
+  console.log(
+    "\n  " +
+      members.length +
+      " accounts across " +
+      rows.length +
+      " types. Refusals: " +
+      totalRefused,
+  );
+
+  /*
+   * The write half. Counted, not asserted to be zero -- refusing these saves is
+   * the change -- with the population behind each role so the cost is explicit.
+   */
+  const memberCount = new Map();
+  members.forEach((m) => {
+    if (!m.role) return;
+    const key = m.role.toString();
+    memberCount.set(key, (memberCount.get(key) || 0) + 1);
+  });
+
+  const inviteCount = new Map();
+  const verifications = await db
+    .collection("verifications")
+    .find({}, { projection: { metadata: 1 } })
+    .toArray();
+  for (const v of verifications) {
+    const role = v && v.metadata && v.metadata.role;
+    if (!role) continue;
+    const key = role.toString();
+    inviteCount.set(key, (inviteCount.get(key) || 0) + 1);
+  }
+
+  const templates = live.filter((r) => roleScope(r) === "client-template");
+
+  console.log("\n  WRITES -- roles the API will no longer save (the intended cost)\n");
+  table(
+    templates
+      .map((r) => ({
+        name: String(r.name === undefined ? "" : r.name).slice(0, 34),
+        type: r.type || "",
+        perms: (r.permissions || []).length,
+        grants: grants(r) === "ALL" ? "ALL" : "enumerated",
+        members: memberCount.get(r._id.toString()) || 0,
+        invitations: inviteCount.get(r._id.toString()) || 0,
+      }))
+      .sort((a, b) => b.members - a.members),
+    ["name", "type", "perms", "grants", "members", "invitations"],
+  );
+
+  /*
+   * The one assertion on the permission guard: no role as it stands today may
+   * fail its OWN re-save. The guard refuses ADDITIONS only, so a role already
+   * holding a platform string keeps its editor. A non-zero count here would
+   * mean the guard locks somebody out of a role they can edit today, which is
+   * the failure mode this whole file exists to catch.
+   */
+  const platformOnly = new Set(
+    JSON.parse(
+      fs.readFileSync(
+        path.join(__dirname, "platform-only-permissions.json"),
+        "utf8",
+      ),
+    ),
+  );
+  const wouldFailResave = live.filter((r) => {
+    if (roleScope(r) === "platform") return false;
+    const held = new Set(r.permissions || []);
+    return (r.permissions || []).some((p) => platformOnly.has(p) && !held.has(p));
+  });
+
+  /*
+   * And the reverse reading of the same data, which is the number a lead
+   * actually wants: client roles that hold a platform string at all. Those
+   * saves keep working; the count says how big a catalogue merge would be.
+   */
+  const holdPlatformString = live.filter(
+    (r) =>
+      roleScope(r) !== "platform" &&
+      (r.permissions || []).some((p) => platformOnly.has(p)),
+  );
+
+  console.log(
+    "\n  client roles holding a platform string: " +
+      holdPlatformString.length +
+      "   of those, unable to re-save: " +
+      wouldFailResave.length,
+  );
+
+  await client.close();
+
+  if (totalRefused > 0) {
+    fail(
+      rows
+        .filter((r) => r.REFUSED > 0)
+        .map((r) => r.type + ": " + r.REFUSED)
+        .join(", ") + " -- an account type loses access. This blocks the merge.",
+    );
+  }
+  if (wouldFailResave.length > 0) {
+    fail(
+      wouldFailResave.length +
+        " roles could no longer be re-saved as they stand. This blocks the merge.",
+    );
+  }
+
+  console.log("\n  PASS  zero refusals in every account type.\n");
+})().catch((e) => fail(e.message));

package/tools/role-scope-lockout-check/platform-only-permissions.json

@@ -0,0 +1,21 @@
+[
+  "activity-history:see-activity-history",
+  "marketplace-vendors:see-all-marketplace-vendors",
+  "marketplace-vendors:see-marketplace-vendor-details",
+  "organizations:see-all-organizations",
+  "organizations:see-organization-details",
+  "platform-terms:edit-platform-terms",
+  "platform-terms:see-platform-terms",
+  "promo-codes:change-promo-code-status",
+  "promo-codes:create-promo-code",
+  "promo-codes:delete-promo-code",
+  "promo-codes:edit-promo-code-details",
+  "promo-codes:see-promo-code-details",
+  "sp-approvals:approve-sp",
+  "sp-approvals:delete-sp-approval",
+  "sp-approvals:reject-sp",
+  "sp-approvals:see-all-sp-approvals",
+  "subscriptions:manage-subscription",
+  "subscriptions:see-all-subscriptions",
+  "subscriptions:see-subscription-details"
+]

package/tools/role-scope-lockout-check/srv.js

@@ -0,0 +1,39 @@
+// This machine's DNS resolver REFUSES SRV lookups (querySrv ECONNREFUSED), so
+// `mongodb+srv://` URIs cannot connect. Resolve the SRV+TXT records via a public
+// resolver and hand the driver a plain `mongodb://` URI instead. Read-only helper.
+const { Resolver } = require("dns");
+
+function resolveVia (server, method, name) {
+  return new Promise((resolve, reject) => {
+    const r = new Resolver();
+    r.setServers([server]);
+    r[method](name, (err, res) => (err ? reject(err) : resolve(res)));
+  });
+}
+
+/** Turn a mongodb+srv:// URI into a direct mongodb:// URI. Passes others through. */
+async function toDirectUri (uri, server = "8.8.8.8") {
+  if (!uri.startsWith("mongodb+srv://")) return uri;
+  const rest = uri.slice("mongodb+srv://".length);
+  const at = rest.lastIndexOf("@");
+  const creds = at === -1 ? "" : rest.slice(0, at + 1);
+  const after = rest.slice(at + 1);
+  const slash = after.search(/[/?]/);
+  const host = slash === -1 ? after : after.slice(0, slash);
+  const tail = slash === -1 ? "" : after.slice(slash);
+
+  const srv = await resolveVia(server, "resolveSrv", `_mongodb._tcp.${host}`);
+  const txt = await resolveVia(server, "resolveTxt", host).catch(() => []);
+  const hosts = srv.map((s) => `${s.name}:${s.port}`).join(",");
+
+  const [pathPart, queryPart = ""] = tail.startsWith("/")
+    ? [tail.slice(1).split("?")[0], tail.split("?")[1] || ""]
+    : ["", tail.replace(/^\?/, "")];
+  const opts = new URLSearchParams(queryPart);
+  for (const [k, v] of new URLSearchParams(txt.flat().join("&"))) if (!opts.has(k)) opts.set(k, v);
+  opts.set("tls", "true");
+
+  return `mongodb://${creds}${hosts}/${pathPart}?${opts.toString()}`;
+}
+
+module.exports = { toDirectUri };