@7365admin1/core 3.55.0 → 3.56.0

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 };