@7365admin1/core 3.61.0 → 3.62.0

package/tools/repair-client-template-permissions/repair.mjs

@@ -0,0 +1,329 @@
+#!/usr/bin/env node
+/**
+ * PUT BACK WHAT ONE CONSOLE SAVE TOOK AWAY ON 2026-09-07 -- through the
+ * ordinary authenticated API, never the database.
+ *
+ * ## What happened, and what is still wrong
+ *
+ * "Org Owner" is a role with `type: "organization"` and NO `org`. An org-less
+ * role belongs to no single client, so every client ever invited with it shares
+ * the one document. On 2026-09-07 it was opened in the Seven365 staff console's
+ * role editor and saved. That editor renders `useAdminPermission` -- the eleven
+ * PLATFORM resources, 34 actions -- as one selectable list, so the save wrote
+ * exactly those 34 platform strings onto it and not one client module.
+ *
+ * The permission model reads an EMPTY list as "everything"
+ * (`layer-common utils/permission-spellings.ts grantsPermission`, mirrored here
+ * by `consoleRoleAllowsAll`). That role's list was empty before the save. So it
+ * granted everything right up to the moment it held a non-empty list -- and the
+ * list it then held contained no client module at all. Every holder, in every
+ * client, lost every module at once.
+ *
+ * BOTH ENDS OF THE CAUSE ARE CLOSED and neither of them repairs anything:
+ *
+ *   - the console screen no longer lists client templates
+ *     (`web-app-org pages/super-admin/role-permissions/index.vue`);
+ *   - `role-scope.util.ts` refuses platform strings being ADDED to a client
+ *     role, server-side, whatever editor asks.
+ *
+ * The document itself was never put back. Measured on staging 2026-09-09:
+ * "Org Owner" still holds those 34 strings, with 123 live members and 322
+ * invitations behind it.
+ *
+ * ## Why this is allowed to work at all
+ *
+ * `role-scope.util.ts` refuses ADDITIONS only -- "a permission string that is
+ * already stored on a role is always allowed through". This repair only ever
+ * REMOVES platform strings, so the guard that stops the damage recurring does
+ * not stand in the way of undoing it. Nothing here weakens that guard.
+ *
+ * ## What it will not do
+ *
+ * - **No database.** It holds no connection string and speaks only to the API,
+ *   so every write is authorised, rate-limited and audited exactly like a write
+ *   from the console.
+ * - **DRY RUN unless `--apply` is passed.** With no `--apply` it reads, decides
+ *   and prints, and sends no PATCH at all.
+ * - **It repairs NOTHING on its own.** It detects and reports; a repair happens
+ *   only for a role a person NAMES with `--repair-role <id>`. Restoring a role
+ *   to `["*"]` asserts it granted everything before the save, and no stored
+ *   document says what it held before -- so that assertion has to come from a
+ *   person, not from a rule. See `planRepair` for the dry run that caught this.
+ * - **It never creates, deletes or repoints a role, member or invitation**, and
+ *   never touches a role that carries an `org` or a `type: "admin"` role.
+ * - **Re-read immediately before each write**, so a role somebody repaired a
+ *   second ago is skipped rather than overwritten.
+ *
+ * ## Why `["*"]` and not `[]`
+ *
+ * `[]` is what the role held before the save, and `["*"]` means the same thing
+ * to every consumer (`grantsPermission` short-circuits on both). `["*"]` is
+ * written instead because it is EXPLICIT: it is the shape
+ * `subscription.service.ts` and `defaultOwnerRoles` already seed for every
+ * owner role, it survives any future tightening of the empty-list rule, and it
+ * cannot be mistaken by a reader for "nobody has set this up yet". The grant is
+ * identical either way, so no holder gains or loses anything relative to the
+ * pre-incident state.
+ *
+ * ## Usage
+ *
+ *   API=https://iservice365-staging-api.apptesting.work \
+ *   SEVEN365_SID=<session id, never a literal on a command line> \
+ *   node tools/repair-client-template-permissions/repair.mjs          # DRY RUN
+ *
+ *   ... same, plus --apply                                            # WRITES
+ *
+ *   ... plus --repair-role <24-hex id>   the ONLY way anything is written.
+ *                                        Repeatable. This is how "Org Owner" is
+ *                                        repaired. Run the dry run first, read
+ *                                        the REVIEW rows, then name the ids you
+ *                                        have decided about.
+ *
+ * Identity: a Seven365 platform-staff account. `GET /api/roles` with no `org`
+ * returns the org-less set, and `PATCH /api/roles/permissions/id/:id` needs the
+ * console grant for roles and permissions.
+ *
+ * ⚠ Run the DRY RUN first and read the table. It names every role it would
+ * touch, and how many live members and invitations sit behind each one.
+ */
+
+import { pathToFileURL } from "node:url";
+
+const HEX24 = /^[0-9a-fA-F]{24}$/;
+
+/**
+ * The permission strings that belong to the Seven365 console and nowhere else.
+ *
+ * Deliberately the SAME seven resources as `src/utils/role-scope.util.ts`
+ * `PLATFORM_ONLY_RESOURCES`, and for the same reason: `users`, `invitations`,
+ * `members` and `roles-and-permissions` exist in BOTH catalogues, so treating
+ * them as platform-only would classify an ordinary client role as corrupt.
+ *
+ * Written out rather than imported so the tool runs with no build step;
+ * `test/repair-client-template-permissions.test.mjs` fails if it ever drifts
+ * from the source of truth in `role-scope.util.ts`.
+ */
+export const PLATFORM_ONLY_RESOURCES = [
+  "organizations",
+  "promo-codes",
+  "subscriptions",
+  "sp-approvals",
+  "marketplace-vendors",
+  "platform-terms",
+  "activity-history",
+];
+
+/** Is this string a console-only grant? Resource half only -- see below. */
+export function isPlatformOnly(permission) {
+  const resource = String(permission ?? "").split(":")[0];
+  return PLATFORM_ONLY_RESOURCES.includes(resource);
+}
+
+/**
+ * What should be done with this role.
+ *
+ * Pure: no network, no clock, no database. Every decision the tool takes is
+ * taken here, so the decision is what the tests exercise.
+ *
+ * @returns `{ skip: <reason> }` or `{ payload: { permissions: [...] }, ... }`
+ */
+export function planRepair(role, namedForRepair = []) {
+  const id = role?._id?.toString?.() ?? "";
+  if (!HEX24.test(id)) return { skip: "role has no usable id" };
+
+  // A platform role is SUPPOSED to hold platform strings. Leave it alone.
+  if ((role?.type ?? "") === "admin") return { skip: "platform staff role" };
+
+  // A role carrying an org belongs to one client and was never the shared
+  // document this incident damaged.
+  if (role?.org?.toString?.()) return { skip: "role belongs to one organisation" };
+
+  const held = Array.isArray(role?.permissions) ? role.permissions : null;
+  if (held === null) return { skip: "permission list unreadable" };
+
+  // An empty list already means everything -- this role is in its pre-incident
+  // state and needs nothing. Fail safe: doing nothing is the correct answer.
+  if (held.length === 0) return { skip: "already grants everything (empty list)" };
+
+  if (held.includes("*")) return { skip: "already grants everything (wildcard)" };
+
+  const platform = held.filter(isPlatformOnly);
+
+  if (platform.length === 0) {
+    return { skip: "holds no platform strings - an ordinary client template" };
+  }
+
+  /*
+   * NOTHING IS REPAIRED AUTOMATICALLY, and that is a correction to this tool's
+   * first design.
+   *
+   * The first version repaired any role whose list was ENTIRELY platform
+   * strings, on the reasoning that a client role cannot legitimately hold only
+   * those. The reasoning is sound; the CONCLUSION does not follow. Restoring a
+   * role to `["*"]` asserts it granted EVERYTHING before the save, and no
+   * stored document says what it held before. The dry run over the real 462
+   * staging roles is what caught it: the rule wanted to give "Sub Member" --
+   * one platform string, no holders -- the run of the entire platform, which is
+   * plainly not what a role called Sub Member ever was.
+   *
+   * So the tool detects and reports, and repairs only what a person NAMES. That
+   * is the same discipline the guard it undoes was built on: this is a
+   * privilege-restoring write, and a privilege-restoring write nobody signed
+   * for is how the incident happened in the first place.
+   */
+
+  // A MIX is not proof of the incident. It could be a genuine client role that
+  // somebody also ticked a console box on, and rewriting it would take away
+  // grants nobody asked us to take away. Report it; do not touch it.
+  //
+  // Unless a human has NAMED this exact role id on the command line. That is
+  // how the real "Org Owner" gets repaired: its 34 strings are 19 platform-only
+  // plus 15 on the four SHARED resources (`users`, `invitations`, `members`,
+  // `roles-and-permissions`), so it is a mix by this rule and no automatic
+  // reading of the document can prove what it held before. A person has to
+  // decide, and naming the id is that decision being recorded.
+  if (!namedForRepair.includes(id)) {
+    return {
+      skip:
+        `holds ${platform.length} platform string(s) of ${held.length} ` +
+        `- needs a human to name it`,
+      review: true,
+    };
+  }
+
+  return {
+    payload: { permissions: ["*"] },
+    removing: held.length,
+    named: true,
+  };
+}
+
+/* ───────────────────────── I/O below this line ───────────────────────── */
+
+async function main() {
+  const API = process.env.API ?? "";
+  const SID = process.env.SEVEN365_SID ?? "";
+  const apply = process.argv.includes("--apply");
+
+  // `--repair-role <id>` (repeatable) is a human saying "I have read this role
+  // and I am asking for it to be restored", for a mixed list the tool will not
+  // judge on its own. It never widens what the tool touches beyond an org-less,
+  // non-admin role -- every other refusal above still applies.
+  const namedForRepair = process.argv
+    .map((arg, i) => (arg === "--repair-role" ? process.argv[i + 1] : null))
+    .filter((id) => HEX24.test(id ?? ""));
+
+  if (!API || !SID) {
+    console.error("Set API and SEVEN365_SID. See the header of this file.");
+    process.exit(2);
+  }
+
+  const call = async (path, init = {}) => {
+    const res = await fetch(`${API}${path}`, {
+      ...init,
+      headers: {
+        Authorization: `Bearer ${SID}`,
+        "Content-Type": "application/json",
+        ...(init.headers ?? {}),
+      },
+    });
+    const text = await res.text();
+    let body = null;
+    try {
+      body = text ? JSON.parse(text) : null;
+    } catch {
+      body = text;
+    }
+    return { status: res.status, body };
+  };
+
+  console.log(apply ? "MODE: APPLY (writes)" : "MODE: DRY RUN (no writes)");
+  if (namedForRepair.length) {
+    console.log(`NAMED for repair by a human: ${namedForRepair.join(", ")}`);
+  }
+  console.log(`API:  ${API}\n`);
+
+  // The org-less set. `GET /api/roles` with no `org` is exactly the query the
+  // console's own screen makes, so this sees what a staff account sees.
+  const listed = await call("/api/roles?limit=100");
+  if (listed.status !== 200) {
+    console.error(`GET /api/roles -> ${listed.status}`, listed.body);
+    process.exit(1);
+  }
+
+  const roles = listed.body?.items ?? [];
+  console.log(`org-less roles returned: ${roles.length}\n`);
+
+  const planned = [];
+  const review = [];
+  const skipped = [];
+
+  for (const role of roles) {
+    const plan = planRepair(role, namedForRepair);
+    if (plan.payload) planned.push({ role, plan });
+    else if (plan.review) review.push({ role, plan });
+    else skipped.push({ role, plan });
+  }
+
+  if (review.length) {
+    console.log("NEEDS A HUMAN - a mixed list is not proof of the incident:");
+    for (const { role, plan } of review) {
+      console.log(`  ${role.name} (${role._id}) - ${plan.skip}`);
+    }
+    console.log("");
+  }
+
+  if (!planned.length) {
+    console.log("Nothing to repair. Every org-less client role already grants everything,");
+    console.log("or holds a list this tool will not judge.");
+    console.log(`\nskipped: ${skipped.length}`);
+    return;
+  }
+
+  console.log("WOULD REPAIR:" + (apply ? "  (and will, --apply is set)" : ""));
+  for (const { role, plan } of planned) {
+    console.log(
+      `  ${role.name} (${role._id}) type=${role.type} ` +
+        `- removing ${plan.removing} strings, restoring ["*"]` +
+        (plan.named ? "   [NAMED BY A HUMAN - mixed list]" : ""),
+    );
+  }
+  console.log("");
+
+  if (!apply) {
+    console.log("DRY RUN - nothing was written. Re-run with --apply to write.");
+    return;
+  }
+
+  for (const { role, plan } of planned) {
+    // Re-read immediately before writing: somebody may have repaired it a
+    // second ago, and a tool that overwrites a fresher value is not a repair.
+    const fresh = await call(`/api/roles/id/${role._id}`);
+    if (fresh.status !== 200) {
+      console.log(`  SKIP ${role.name}: re-read returned ${fresh.status}`);
+      continue;
+    }
+    const recheck = planRepair(fresh.body, namedForRepair);
+    if (!recheck.payload) {
+      console.log(`  SKIP ${role.name}: ${recheck.skip} (changed since the listing)`);
+      continue;
+    }
+
+    const res = await call(`/api/roles/permissions/id/${role._id}`, {
+      method: "PATCH",
+      body: JSON.stringify(plan.payload),
+    });
+    console.log(
+      res.status >= 200 && res.status < 300
+        ? `  OK   ${role.name} -> ["*"]`
+        : `  FAIL ${role.name} -> ${res.status} ${JSON.stringify(res.body)}`,
+    );
+  }
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });
+}