@bevel-software/platform-core-backend 0.9.1 → 0.11.0

package/src/modules/access/roles-edit.ts

@@ -6,7 +6,8 @@
  * markdown BODY below the frontmatter (the repo-root one is a whole README)
  * that a parse→emit round-trip would silently delete. `roles.yaml` has no body
  * and no frontmatter fence — it is a plain `roles:` mapping of display-name →
- * email list — and no real `roles.yaml` in the repo carries comments. So we
+ * member list (emails and `group:<name>` refs) — and no real `roles.yaml` in
+ * the repo carries comments. So we
  * parse the file into a model, apply the edit, and re-emit a canonical,
  * deterministic file. Re-emit is idempotent (re-emitting an unchanged model
  * yields byte-identical text), so a single edit moves only the lines it
@@ -23,8 +24,8 @@
  *
  * Every mutation returns `{ text, changed }`; `changed: false` means the edit
  * was a no-op (e.g. adding a member who already exists) and the caller should
- * skip the commit. Role ORDER is preserved as parsed; a newly created role is
- * appended last. Member emails within a role are canonicalised + de-duplicated.
+ * skip the commit. Role ORDER is preserved as parsed. Member entries within a
+ * role are canonicalised + de-duplicated.
  *
  * This module does NOT enforce the Admin-must-exist / no-self-lockout
  * invariants — those are policy and live in `roles-admin.service.ts`. It only
@@ -37,7 +38,7 @@ import {
   canonicalRoleName,
   canonicalEmail,
   EMAIL_REGEX,
-  RESERVED_ROLE_NAMES,
+  GROUP_REF_PREFIX,
 } from './access-control.service.js';
 
 /** Bad-input failure when editing roles.yaml (invalid name/email, unknown role). */
@@ -50,7 +51,8 @@ export class RolesEditError extends Error {
   }
 }
 
-/** One role in parse order: display name + its de-duplicated member emails. */
+/** One role in parse order: display name + its de-duplicated member entries
+ *  (emails and `group:<canonical>` refs). */
 export interface RoleModel {
   displayName: string;
   /** canonicalised, de-duplicated, in first-seen order */
@@ -64,34 +66,6 @@ export interface EditResult {
   changed: boolean;
 }
 
-/**
- * Reject role display names whose characters would corrupt the emitted YAML.
- * `canonicalRoleName` only trims/lowercases/collapses spaces — it does NOT
- * reject structural characters, so a name like `Sales: West` or `#temp` would
- * round-trip into a broken file. This guard is the structural complement to the
- * reserved/duplicate checks the service layer applies.
- *
- *   `:`        mis-tokenises as a nested mapping key
- *   `#`        truncated as a comment by the subset parser's stripComment
- *   `<` / `>`  collide with the `Name <email>` user-reference shape
- *   leading -  tokenises as a list item
- *   \x00-\x1f  control chars / newlines break line structure outright
- */
-export function assertSafeRoleDisplayName(displayName: string): void {
-  const trimmed = displayName.trim();
-  if (!trimmed) throw new RolesEditError('role name must not be empty');
-  if (/[:#<>]/.test(trimmed)) {
-    throw new RolesEditError(`role name must not contain ':', '#', '<', or '>': ${JSON.stringify(displayName)}`);
-  }
-  // eslint-disable-next-line no-control-regex
-  if (/[\x00-\x1f]/.test(trimmed)) {
-    throw new RolesEditError(`role name must not contain control characters: ${JSON.stringify(displayName)}`);
-  }
-  if (trimmed.startsWith('-')) {
-    throw new RolesEditError(`role name must not start with '-': ${JSON.stringify(displayName)}`);
-  }
-}
-
 /**
  * Parse `roles.yaml` text into the ordered model. Tolerant of an empty/missing
  * file (yields `[]`). Throws RolesEditError on structurally-broken YAML — the
@@ -178,22 +152,13 @@ function reemit(original: string, model: RolesModel): EditResult {
   return { text, changed: text !== originalCanonical };
 }
 
-/** Create a new empty role. 422 on reserved/duplicate/structurally-unsafe name. */
-export function createRole(text: string, displayName: string): EditResult {
-  assertSafeRoleDisplayName(displayName);
-  const canonical = canonicalRoleName(displayName);
-  if (RESERVED_ROLE_NAMES.has(canonical)) {
-    throw new RolesEditError(`'${displayName.trim()}' is a reserved name and cannot be a role`);
-  }
-  const model = parseRolesModel(text);
-  if (findRole(model, canonical)) {
-    throw new RolesEditError(`a role named '${displayName.trim()}' already exists`);
-  }
-  model.push({ displayName: displayName.trim(), members: [] });
-  return reemit(text, model);
-}
-
-/** Delete a role by canonical name. 404 if absent. */
+/**
+ * Delete a role by canonical name. 404 if absent.
+ *
+ * NOTE: roles are app-defined capabilities now — there is no create/rename
+ * editor anymore. This deletion survives ONLY as the roles.yaml half of
+ * `convertRoleToGroup` (a LEGACY people-set role migrating to a group).
+ */
 export function deleteRole(text: string, canonical: string): EditResult {
   const model = parseRolesModel(text);
   const idx = model.findIndex((r) => canonicalRoleName(r.displayName) === canonical);
@@ -205,6 +170,14 @@ export function deleteRole(text: string, canonical: string): EditResult {
 /** Add a member email to a role. Idempotent. 422 bad email; 404 unknown role. */
 export function addMember(text: string, canonical: string, rawEmail: string): EditResult {
   const email = canonicalEmail(rawEmail);
+  // A `group:`-prefixed value is a GROUP REFERENCE, not an email — and
+  // `group:lee@x.io` would pass the email regex, landing a dead ref the
+  // resolver reads as an unknown group. Route the caller to the right editor.
+  if (email.startsWith(GROUP_REF_PREFIX)) {
+    throw new RolesEditError(
+      `member ${JSON.stringify(rawEmail)} starts with '${GROUP_REF_PREFIX}' — to assign this role to a group, use the group assignment (addRoleGroupRef / the role's Groups control), not a member email`,
+    );
+  }
   if (!EMAIL_REGEX.test(email)) throw new RolesEditError(`malformed email: ${JSON.stringify(rawEmail)}`);
   const model = parseRolesModel(text);
   const role = findRole(model, canonical);
@@ -227,22 +200,122 @@ export function removeMember(text: string, canonical: string, rawEmail: string):
 }
 
 /**
- * Rename a role's display name. The canonical name MAY change (the service
- * layer is responsible for the reference rewrite + Admin guard when it does).
- * 404 unknown source; 422 reserved/duplicate/unsafe target.
+ * A role member entry that assigns the role to a GROUP (`group:<name>`).
+ * Kept in `members` as the normalized `group:<canonical>` string — the
+ * parse/emit round-trip preserves it, so unrelated edits can never strip a
+ * group assignment.
  */
-export function renameRoleDisplay(text: string, canonical: string, newDisplayName: string): EditResult {
-  assertSafeRoleDisplayName(newDisplayName);
-  const newCanonical = canonicalRoleName(newDisplayName);
-  if (RESERVED_ROLE_NAMES.has(newCanonical)) {
-    throw new RolesEditError(`'${newDisplayName.trim()}' is a reserved name and cannot be a role`);
-  }
+export function isGroupRefMember(member: string): boolean {
+  return member.startsWith(GROUP_REF_PREFIX);
+}
+
+function groupRefFor(groupName: string): string {
+  const canonical = canonicalRoleName(groupName);
+  if (!canonical) throw new RolesEditError('group name must not be empty');
+  return `${GROUP_REF_PREFIX}${canonical}`;
+}
+
+/**
+ * The canonical group name a member entry references, or null for non-refs.
+ * Matching MUST go through this rather than string equality on the ref: a
+ * hand-edited file may carry an un-normalized ref (`group:GTM  Team`) that
+ * the RESOLVER honors (it canonicalizes the suffix) — an equality match would
+ * then no-op the unassign/rename while the roster still shows the group.
+ */
+function groupRefCanonical(member: string): string | null {
+  return isGroupRefMember(member)
+    ? canonicalRoleName(member.slice(GROUP_REF_PREFIX.length))
+    : null;
+}
+
+/**
+ * Assign a role to a group. Allowed on every role, Admin included — the
+ * resolver's parse-time invariant (Admin keeps at least one DIRECT email
+ * member) is what protects the rescue story, and the service validates every
+ * candidate through that parser before a byte lands. Idempotent; 404 unknown
+ * role.
+ */
+export function addRoleGroupRef(text: string, canonical: string, groupName: string): EditResult {
+  const ref = groupRefFor(groupName);
+  const refCanonical = canonicalRoleName(groupName);
   const model = parseRolesModel(text);
   const role = findRole(model, canonical);
   if (!role) throw new RolesEditError(`role not found: ${canonical}`, 404);
-  if (newCanonical !== canonical && findRole(model, newCanonical)) {
-    throw new RolesEditError(`a role named '${newDisplayName.trim()}' already exists`);
+  if (role.members.some((m) => groupRefCanonical(m) === refCanonical)) {
+    return { text: emitRolesModel(model), changed: false };
+  }
+  role.members.push(ref);
+  return reemit(text, model);
+}
+
+/**
+ * Rewrite every role's `group:<oldCanonical>` assignment to name
+ * `group:<newCanonical>` — the roles.yaml half of a group rename. Refs are
+ * STORED canonical, so a canonical-changing group rename would otherwise
+ * strand them: `mergeGroupsIntoRoles` ignores an unknown ref with a warning,
+ * silently shrinking the role's membership. Already-present target refs
+ * dedupe rather than duplicate. No-op when nothing references the old name.
+ */
+export function renameGroupRefs(text: string, oldCanonical: string, newCanonical: string): EditResult {
+  const newRef = `${GROUP_REF_PREFIX}${newCanonical}`;
+  const model = parseRolesModel(text);
+  let changed = false;
+  for (const role of model) {
+    // A role may carry SEVERAL differently-formatted refs to the same group
+    // (un-normalized hand edits) — rewrite them all, or the stragglers point
+    // at the renamed-away name and accumulate resolver warnings. Exactly one
+    // ref to the new name survives.
+    let hasNew = role.members.some((m) => groupRefCanonical(m) === newCanonical);
+    for (let i = role.members.length - 1; i >= 0; i--) {
+      if (groupRefCanonical(role.members[i]) !== oldCanonical) continue;
+      if (hasNew) role.members.splice(i, 1);
+      else {
+        role.members[i] = newRef;
+        hasNew = true;
+      }
+      changed = true;
+    }
   }
-  role.displayName = newDisplayName.trim();
+  if (!changed) return { text: emitRolesModel(model), changed: false };
+  return reemit(text, model);
+}
+
+/**
+ * Remove every role's `group:<canonical>` assignment — the roles.yaml half of
+ * a group DELETION (mirror of {@link renameGroupRefs}): a deleted group's
+ * refs would otherwise dangle, silently shrinking each assigned role's
+ * membership with only a resolver log warning. Canonical-suffix matching, so
+ * un-normalized hand-edited refs are removed too. No-op when nothing
+ * references the group.
+ */
+export function removeGroupRefsEverywhere(text: string, canonical: string): EditResult {
+  const model = parseRolesModel(text);
+  let changed = false;
+  for (const role of model) {
+    for (let i = role.members.length - 1; i >= 0; i--) {
+      if (groupRefCanonical(role.members[i]) !== canonical) continue;
+      role.members.splice(i, 1);
+      changed = true;
+    }
+  }
+  if (!changed) return { text: emitRolesModel(model), changed: false };
+  return reemit(text, model);
+}
+
+/** Remove a role's group assignment. 404 unknown role; no-op if not assigned.
+ *  Removes EVERY member whose ref canonicalises to the group — a hand-edited
+ *  file may carry several differently-formatted refs to the same group
+ *  (`group:gtm team` + `group:GTM  Team`), and stripping only the first would
+ *  leave stragglers the resolver still honors, so the role silently keeps the
+ *  group after an apparently-successful unassign. */
+export function removeRoleGroupRef(text: string, canonical: string, groupName: string): EditResult {
+  const refCanonical = canonicalRoleName(groupName);
+  if (!refCanonical) throw new RolesEditError('group name must not be empty');
+  const model = parseRolesModel(text);
+  const role = findRole(model, canonical);
+  if (!role) throw new RolesEditError(`role not found: ${canonical}`, 404);
+  const kept = role.members.filter((m) => groupRefCanonical(m) !== refCanonical);
+  if (kept.length === role.members.length) return { text: emitRolesModel(model), changed: false };
+  role.members = kept;
   return reemit(text, model);
 }

package/src/modules/access/synced-groups-committer.ts

@@ -0,0 +1,177 @@
+import path from 'node:path';
+import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
+import type { WorkspaceService } from '../workspace/workspace.service.js';
+import { workspaceIdForBranch } from '../workspace/workspace.service.js';
+import type { AccessControlService } from './access-control.service.js';
+import { SYNCED_GROUPS_YAML } from './group-files.js';
+import type { WorkflowEventBus } from '../workflow/event-bus.js';
+import { LockingFilesystem } from '../workflow/locking-filesystem.js';
+import { PushNeedsAgentResolutionError, WorkflowDomainError } from '../workflow/workflow.errors.js';
+import type { SyncedGroupsWriterDeps } from './synced-groups-writer.js';
+
+/**
+ * The git half of the synced-groups materializer: reads/commits
+ * `synced-groups.yaml` on the DEFAULT branch through the same lock-aware
+ * pipeline every other in-app write uses, attributed to the directory-sync
+ * bot. Split from {@link SyncedGroupsWriter} so the writer's render/debounce
+ * logic stays testable against plain fakes.
+ *
+ * All three functions are resilient to an UNCONFIGURED deployment (no branch
+ * model yet): reads answer null and writes throw a descriptive error — the
+ * writer logs it; a SCIM push arriving before setup completes is a
+ * configuration race, not a crash.
+ */
+export function createSyncedGroupsCommitter(deps: {
+  workspaceService: WorkspaceService;
+  workflowService: IWorkflowService;
+  accessControl: AccessControlService;
+  eventBus: WorkflowEventBus;
+  kbDirName: string;
+  bot: AuthUser;
+  /** Thunk — DEFAULT_BRANCH is a live binding that stays empty until setup. */
+  defaultBranchOf: () => string;
+}): Pick<SyncedGroupsWriterDeps, 'readCurrent' | 'persist' | 'onWritten'> {
+  const {
+    workspaceService,
+    workflowService,
+    accessControl,
+    eventBus,
+    kbDirName,
+    bot,
+    defaultBranchOf,
+  } = deps;
+
+  const repoRelPath = SYNCED_GROUPS_YAML;
+  const wsRelPath = `${kbDirName}/${SYNCED_GROUPS_YAML}`;
+
+  return {
+    readCurrent: async () => {
+      const branch = defaultBranchOf();
+      if (!branch) return null;
+      await workspaceService.getOrCreateForBranch(branch);
+      try {
+        return await workspaceService.readFile(
+          workspaceIdForBranch(branch),
+          path.posix.join(kbDirName, repoRelPath),
+        );
+      } catch (err) {
+        const code = (err as NodeJS.ErrnoException | null)?.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR') return null;
+        throw err;
+      }
+    },
+
+    persist: async (content: string) => {
+      const branch = defaultBranchOf();
+      if (!branch) {
+        throw new Error('deployment has no default branch configured yet — cannot materialize synced groups');
+      }
+      await workspaceService.getOrCreateForBranch(branch);
+      const workspaceId = workspaceIdForBranch(branch);
+      const basePath = await workspaceService.getWorkspacePath(workspaceId);
+      // Lock-aware write: acquires the file's lock, writes, and commits the
+      // batch as ONE change with a descriptive summary — same pipeline the
+      // roles admin's atomic writes use.
+      const fsys = new LockingFilesystem(
+        { basePath, contained: true },
+        { workflow: workflowService, workspaceId, branch, user: bot },
+      );
+      try {
+        await fsys.writeFiles(
+          [{ path: wsRelPath, content }],
+          'Sync directory groups from the identity provider',
+        );
+      } catch (err) {
+        if (err instanceof PushNeedsAgentResolutionError) {
+          // POST-commit failure: the update IS committed locally — only the
+          // push needs help, and the pending-commits ladder retries it. But
+          // the ladder is only armed if a pending-commit row for this path
+          // actually EXISTS — the writeFiles push-retry release that enqueues
+          // it is best-effort (a failure is logged and swallowed), and
+          // without a row there is no retry vehicle: the next sync reads the
+          // committed bytes, sees a no-op, and the update stays unpublished
+          // forever. So PROVE the vehicle before reporting success:
+          //   1. Release our lock once more. Success means THIS release
+          //      enqueued the row (releaseLock enqueues BEFORE dropping the
+          //      row) → armed, lock freed.
+          //   2. Lock already gone → ambiguous: the earlier release either
+          //      enqueued-then-dropped (armed) or died BEFORE its enqueue
+          //      with the lock expired/stolen (NOT armed) — both leave the
+          //      same lock-not-held answer. Only the queue itself can tell
+          //      them apart: ask it directly for a live row on this path.
+          //   2b. No live row → one more possibility before giving up: the
+          //      worker may have DRAINED the row (and pushed) between the
+          //      first release and this probe. Nothing left unpushed on the
+          //      branch proves exactly that — the update is already
+          //      published, which is better than armed.
+          //   3. Anything else (or no proof either way) → no proven vehicle:
+          //      rethrow, so the writer logs a real failure instead of a
+          //      phantom success.
+          // Rejecting is still the LAST resort — a landed commit routed
+          // through the failure path stays locally live but unpublished until
+          // an operator (or any later write on the branch) pushes it.
+          let armed = false;
+          try {
+            await workflowService.releaseLock(workspaceId, branch, wsRelPath, bot);
+            armed = true;
+          } catch (armErr) {
+            const lockAlreadyReleased =
+              armErr instanceof WorkflowDomainError && armErr.payload?.kind === 'lock-not-held';
+            if (lockAlreadyReleased) {
+              try {
+                armed = await workflowService.hasQueuedCommit(workspaceId, branch, wsRelPath);
+                if (!armed) {
+                  // The row may already be gone because the worker WON the
+                  // race: drained it and pushed. A branch with nothing left
+                  // unpushed cannot be holding our landed commit hostage.
+                  armed = !(await workflowService.hasUnpushedCommits(workspaceId));
+                }
+              } catch (queueErr) {
+                console.warn(
+                  '[directory-sync] could not verify the pending-commit queue:',
+                  queueErr instanceof Error ? queueErr.message : queueErr,
+                );
+              }
+            } else {
+              console.warn(
+                '[directory-sync] the retry re-arm release failed:',
+                armErr instanceof Error ? armErr.message : armErr,
+              );
+            }
+          }
+          if (!armed) {
+            console.warn(
+              '[directory-sync] synced-groups commit landed, the push needs resolution, and no retry vehicle could be proven — surfacing the failure',
+            );
+            throw err;
+          }
+          console.warn(
+            '[directory-sync] synced-groups commit landed but the push needs resolution — publishing will be retried',
+          );
+          return;
+        }
+        throw err;
+      }
+    },
+
+    onWritten: () => {
+      const branch = defaultBranchOf();
+      if (!branch) return;
+      const workspaceId = workspaceIdForBranch(branch);
+      // A synced-groups change IS an access change: drop the resolver cache
+      // and nudge open clients to re-fetch + re-evaluate, mirroring
+      // RolesAdminService.emitWrites.
+      accessControl.invalidate(workspaceId);
+      eventBus.emit({
+        kind: 'file-changed',
+        workspaceId,
+        branch,
+        path: wsRelPath,
+        newSha: null,
+        byUserId: bot.id,
+        byUserName: bot.name,
+      });
+      eventBus.emit({ kind: 'fs-tree-changed', workspaceId, branch });
+    },
+  };
+}