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

package/src/modules/access/admin-locked-commit.ts

@@ -0,0 +1,331 @@
+/**
+ * SHARED transactional lock/commit helper for the admin roster services
+ * (roles + groups). The two services used to carry twin copies of this
+ * machinery, which diverged once into a real bug — this is the single
+ * implementation both delegate to, parameterized only by the domain-error
+ * constructor, log tag, and contention wording.
+ *
+ * The shape of every roster write:
+ *
+ *   withFileLocks(paths, fn)          — acquire every path's lock (sorted,
+ *     all-or-nothing; strict even for the same user), run `fn`, release.
+ *     HOW each lock is released depends on the outcome (see the finally
+ *     block for the full reasoning):
+ *       - `fn` succeeded → releaseLockNoCommit for every path the batch
+ *         commit LANDED on (tracked by writeAndCommitLocked): the commit
+ *         landed AND pushed, so the tree there is clean (the discard
+ *         no-ops); releaseLock would instead ENQUEUE a commit before
+ *         dropping the row, and an enqueue failure then strands the lock
+ *         until TTL. A held path the batch never committed keeps
+ *         commit-on-release — it may carry a PRIOR holder's still-queued
+ *         work, which a discard would destroy.
+ *       - `fn` threw PushNeedsAgentResolutionError → releaseLock. The commit
+ *         landed but the push didn't; the enqueued release commit IS the
+ *         retry (the worker sees the clean tree, notices unpushed commits,
+ *         and re-runs the cooperative push ladder).
+ *       - `fn` threw anything else → releaseLock (commit-on-release): `fn`
+ *         restored its own bytes, so anything dirty at release time is
+ *         either clean (queued commit no-ops) or someone else's still-queued
+ *         work that must be preserved. The ONE exception: a path whose
+ *         restore itself failed (`unrestoredPaths` on the thrown error)
+ *         holds known-partial bytes → releaseLockNoCommit discards to HEAD.
+ *     Every release is per-path best-effort: one failed release logs and
+ *     moves on so it can never strand the REST of the held locks.
+ *
+ *   writeAndCommitLocked(files)       — the write half of a withFileLocks
+ *     flow: plain-write each file (the lock is already ours — strict
+ *     same-user acquire forbids LockingFilesystem here) and commit them as
+ *     ONE path-scoped change. On a PRE-commit failure, best-effort restore of
+ *     each file's original bytes (`original: null` = the file did not exist,
+ *     so restoration DELETES it). A POST-commit failure — the push after a
+ *     landed commit (`PushNeedsAgentResolutionError`, thrown with the commit
+ *     intact) — must NOT restore: the edit is committed locally and restoring
+ *     would publish a compensating revert of a landed change. It propagates
+ *     as-is ("saved locally … will be resolved"), locks release normally, and
+ *     the pending-commit ladder retries the share.
+ */
+
+import path from 'node:path';
+
+import { LockingFilesystem } from '../workflow/locking-filesystem.js';
+import { PushNeedsAgentResolutionError, WorkflowDomainError } from '../workflow/workflow.errors.js';
+import type { AuthUser, IWorkspaceService, IWorkflowService } from '@bevel-software/platform-shared';
+import type { FileContent } from '@mastra/core/workspace';
+
+export interface LockedCommitDeps {
+  workspaceService: IWorkspaceService;
+  workflowService: IWorkflowService;
+  kbDirName: string;
+  /** Live-binding thunk — DEFAULT_BRANCH stays empty until setup. */
+  defaultBranchOf: () => string;
+  /** Domain-error constructor (RolesAdminError / GroupsAdminError). */
+  makeError: (message: string, status: number, payload?: Record<string, unknown>) => WorkflowDomainError;
+  /** Log prefix, e.g. 'roles-admin' / 'groups-admin'. */
+  logTag: string;
+  /** Contention wording: what is "being edited by <holder>". */
+  contendedSubject: string;
+  /** Pre-disk write validator handed to LockingFilesystem writes. */
+  validateWrite?: (path: string, content: FileContent) => void;
+}
+
+export interface LockedWrite {
+  repoRel: string;
+  /** The new content; null = DELETE the file (restore writes `original` back). */
+  content: string | null;
+  /** null = the file did not exist before (restore DELETES it). */
+  original: string | null;
+}
+
+export class AdminLockedCommits {
+  /**
+   * Workspace-scoped ws-relative paths whose bytes a `writeAndCommitLocked`
+   * batch has committed (and pushed) while their locks are held — i.e. paths
+   * whose working tree is KNOWN clean. `withFileLocks` releases exactly these
+   * with `releaseLockNoCommit` on success (see the module doc) and clears
+   * each entry as it releases. Keyed `<workspaceId>\0<wsRelPath>` so two
+   * workspaces can't cross-talk.
+   */
+  private readonly committedCleanPaths = new Set<string>();
+
+  constructor(private readonly deps: LockedCommitDeps) {}
+
+  private cleanKey(workspaceId: string, wsRelPath: string): string {
+    return `${workspaceId}\0${wsRelPath}`;
+  }
+
+  private get defaultBranch(): string {
+    return this.deps.defaultBranchOf();
+  }
+
+  wsRel(repoRel: string): string {
+    return `${this.deps.kbDirName}/${repoRel}`;
+  }
+
+  async repoDir(workspaceId: string): Promise<string> {
+    const wsDir = await this.deps.workspaceService.getWorkspacePath(workspaceId);
+    return path.join(wsDir, this.deps.kbDirName);
+  }
+
+  /** Read a KB-root file; null when genuinely absent. */
+  async readKbFile(workspaceId: string, repoRel: string): Promise<string | null> {
+    try {
+      return await this.deps.workspaceService.readFile(
+        workspaceId,
+        path.posix.join(this.deps.kbDirName, repoRel),
+      );
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException | null)?.code;
+      if (code === 'ENOENT' || code === 'ENOTDIR') return null;
+      throw err;
+    }
+  }
+
+  /**
+   * A lock-aware filesystem scoped to `actor` — writes auto-commit + push as
+   * the actor on release, through the same pipeline as the human editor and
+   * agent. Built per-op because the lock context captures the acting user.
+   * Only for flows that do NOT already hold the file locks (acquire is strict
+   * even same-user); a withFileLocks flow writes via writeAndCommitLocked.
+   */
+  async lockingFsForActor(workspaceId: string, actor: AuthUser): Promise<LockingFilesystem> {
+    const basePath = await this.deps.workspaceService.getWorkspacePath(workspaceId);
+    return new LockingFilesystem(
+      { basePath, contained: true },
+      {
+        workflow: this.deps.workflowService,
+        workspaceId,
+        branch: this.defaultBranch,
+        user: actor,
+        validateWrite: this.deps.validateWrite,
+      },
+    );
+  }
+
+  /**
+   * Map LockingFilesystem's status-less contention error ("Skipped editing …
+   * — locked by …") to the friendly 409. Callers pre-check the common case,
+   * but that is a TOCTOU check — this catches the race so contention always
+   * surfaces as a 409, never an unhandled 500.
+   */
+  async mapLockContention<T>(write: () => Promise<T>): Promise<T> {
+    try {
+      return await write();
+    } catch (err) {
+      if (err instanceof Error && /locked by /.test(err.message)) {
+        throw this.deps.makeError(
+          `${this.deps.contendedSubject} are being edited by another admin. Try again in a moment.`,
+          409,
+        );
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * Run `fn` while HOLDING the named KB-file locks (sorted, all-or-nothing):
+   * read-modify-write flows must keep the lock across the READ too, or two
+   * concurrent edits (another tab, another admin, a conversion) both snapshot
+   * the same base and the second write silently discards the first. See the
+   * module doc for the release semantics.
+   *
+   * `opts.coordinationFiles` names files locked ONLY to serialize with their
+   * writer — `fn` never writes them. They're acquired with the workflow
+   * service's coordination flag (a pure mutex that skips the per-path write
+   * gate — required for machine-owned files like `synced-groups.yaml`, which
+   * a human actor may not, and need not, write) and always released with
+   * `releaseLockNoCommit`: there is never anything of ours to commit there,
+   * and enqueueing a release commit as an actor the path's write rule
+   * refuses would only feed the worker a doomed row. The discard inside that
+   * release no-ops: the machine writer commits synchronously under its own
+   * lock, so the path is clean whenever we could acquire it.
+   */
+  async withFileLocks<T>(
+    workspaceId: string,
+    actor: AuthUser,
+    repoRelFiles: string[],
+    fn: () => Promise<T>,
+    opts?: { coordinationFiles?: string[] },
+  ): Promise<T> {
+    const coordination = new Set((opts?.coordinationFiles ?? []).map((f) => this.wsRel(f)));
+    // One globally-sorted acquire order across BOTH kinds of path — a split
+    // order would reintroduce the deadlock the sort exists to prevent.
+    const paths = [...new Set([...repoRelFiles.map((f) => this.wsRel(f)), ...coordination])].sort();
+    const held: string[] = [];
+    let failure: unknown | null = null;
+    let unrestored: Set<string> | null = null;
+    try {
+      for (const p of paths) {
+        const res = await this.deps.workflowService.acquireLock(
+          workspaceId,
+          this.defaultBranch,
+          p,
+          actor,
+          coordination.has(p) ? { coordination: true } : undefined,
+        );
+        if (!res.acquired) {
+          throw this.deps.makeError(
+            `${this.deps.contendedSubject} are being edited by ${res.lock.holderName || 'another admin'}. Try again in a moment.`,
+            409,
+          );
+        }
+        held.push(p);
+      }
+      return await fn();
+    } catch (err) {
+      failure = err;
+      unrestored = (err as { unrestoredPaths?: Set<string> } | null)?.unrestoredPaths ?? null;
+      throw err;
+    } finally {
+      // Outcome-dependent release — see the module doc. The key hazard this
+      // guards: `releaseLock` ENQUEUES the release commit BEFORE dropping the
+      // lock row (deliberately, so a crash can't orphan bytes), which means an
+      // enqueue failure leaves the row held until TTL. After a SUCCESSFUL
+      // batch commit there is nothing left to commit — writeAndCommitLocked
+      // committed and pushed these exact paths, and we hold their locks, so
+      // the tree there is clean — so releaseLockNoCommit (whose discard
+      // no-ops on a clean path) releases without ever touching the queue.
+      //
+      // EXCEPT on the push-retry path: PushNeedsAgentResolutionError means
+      // the commit landed but the push didn't, and the enqueued release
+      // commit is what retries the push (runPendingCommit: clean tree +
+      // unpushed commits → pushWithRecovery). That path MUST releaseLock.
+      // Failures there log + continue so one bad enqueue strands at most its
+      // own lock (TTL backstop), never the rest.
+      const pushRetry = failure instanceof PushNeedsAgentResolutionError;
+      for (const h of held) {
+        const committedClean =
+          this.committedCleanPaths.delete(this.cleanKey(workspaceId, h)) && !pushRetry;
+        try {
+          if (coordination.has(h) || committedClean || unrestored?.has(h)) {
+            // Coordination-only hold (see the method doc): `fn` never wrote
+            // it, so no outcome — push-retry included — has anything to
+            // commit there; the no-commit release just drops the row. Or:
+            // Batch-committed path (clean tree — discard no-ops) — even when
+            // `fn` threw AFTER the commit+push landed: the failure says
+            // nothing about the tree, and releaseLock would enqueue a
+            // pointless commit whose enqueue failure strands a known-clean
+            // lock until TTL. Or known-partial bytes (restore failed —
+            // discarding to HEAD beats committing them).
+            await this.deps.workflowService.releaseLockNoCommit(workspaceId, this.defaultBranch, h, actor);
+          } else {
+            // Push-retry (the enqueued commit retries the share), the
+            // restored-failure path, and any held path the batch never
+            // committed (commit-on-release: a prior holder's still-queued
+            // work must be preserved, never discarded).
+            await this.deps.workflowService.releaseLock(workspaceId, this.defaultBranch, h, actor);
+          }
+        } catch (releaseErr) {
+          console.warn(
+            `[${this.deps.logTag}] could not release lock on ${h}${pushRetry ? ' (push-retry release)' : ''}; ` +
+              'it frees on TTL — continuing with the remaining locks:',
+            releaseErr instanceof Error ? releaseErr.message : releaseErr,
+          );
+        }
+      }
+    }
+  }
+
+  /**
+   * Plain-write `files` and commit them as ONE path-scoped change — the write
+   * half of a `withFileLocks` flow. See the module doc for the pre- vs
+   * post-commit failure split; only PRE-commit failures restore.
+   */
+  async writeAndCommitLocked(
+    workspaceId: string,
+    actor: AuthUser,
+    files: LockedWrite[],
+    summary: string,
+  ): Promise<void> {
+    const { workspaceService, workflowService, logTag } = this.deps;
+    try {
+      for (const f of files) {
+        if (f.content === null) {
+          // A DELETE entry. Tolerate an already-absent file — that IS the
+          // desired state (and the caller checked existence under the lock).
+          try {
+            await workspaceService.deleteFile(workspaceId, this.wsRel(f.repoRel));
+          } catch (err) {
+            if ((err as NodeJS.ErrnoException | null)?.code !== 'ENOENT') throw err;
+          }
+        } else {
+          await workspaceService.writeFile(workspaceId, this.wsRel(f.repoRel), f.content);
+        }
+      }
+      await workflowService.commitChanges(workspaceId, actor, summary, files.map((f) => this.wsRel(f.repoRel)));
+      // Commit landed AND pushed — the tree at these paths is clean. Mark
+      // them so withFileLocks releases them WITHOUT enqueueing a release
+      // commit (see the module doc — an enqueue failure would strand the
+      // lock until TTL for a commit there is nothing left to make).
+      for (const f of files) this.committedCleanPaths.add(this.cleanKey(workspaceId, this.wsRel(f.repoRel)));
+    } catch (err) {
+      // POST-commit failure: the commit landed and only the PUSH needs help
+      // (thrown "with the commit intact"). The bytes on disk match the landed
+      // commit — restoring pre-edit bytes here would publish a compensating
+      // revert of a change that exists. No restore; release proceeds
+      // normally; the error itself tells the caller "saved locally, sharing
+      // will be resolved" and the pending-commit ladder retries the push.
+      if (err instanceof PushNeedsAgentResolutionError) {
+        console.warn(
+          `[${logTag}] commit landed but the push needs resolution — edit saved; publishing will be retried`,
+        );
+        throw err;
+      }
+      const unrestored = new Set<string>();
+      for (const f of files) {
+        try {
+          if (f.original === null) await workspaceService.deleteFile(workspaceId, this.wsRel(f.repoRel));
+          else await workspaceService.writeFile(workspaceId, this.wsRel(f.repoRel), f.original);
+        } catch (restoreErr) {
+          // Deleting an already-absent file IS the original state.
+          if (f.original === null && (restoreErr as NodeJS.ErrnoException | null)?.code === 'ENOENT') continue;
+          unrestored.add(this.wsRel(f.repoRel));
+          console.warn(`[${logTag}] could not restore ${f.repoRel} after a failed commit`);
+        }
+      }
+      if (unrestored.size > 0 && typeof err === 'object' && err !== null) {
+        (err as { unrestoredPaths?: Set<string> }).unrestoredPaths = unrestored;
+      }
+      throw err;
+    }
+  }
+}

package/src/modules/access/admin-route-helpers.ts

@@ -0,0 +1,55 @@
+/**
+ * SHARED route plumbing for the access-family routers (access.routes,
+ * groups-admin.routes) — one error shape, one input-coercion rule, so the two
+ * surfaces can't drift apart again.
+ *
+ * Error shape: a sub-500 `WorkflowDomainError` renders as its own status +
+ * message + payload; everything else — a raw error OR a 500-status domain
+ * error (e.g. AccessMutationService wraps unexpected raw errors in a 500
+ * AccessMutationError, message included) — is an INTERNAL error: logged
+ * server-side in full, answered with a generic message. A raw `err.message`
+ * must never leak through a 500 (it can carry fs/db paths and internals the
+ * caller has no business seeing).
+ */
+
+import type express from 'express';
+import { WorkflowDomainError } from '../workflow/workflow.errors.js';
+
+/** One error shape for every access-family route. */
+export function toHttpError(
+  err: unknown,
+  logTag: string,
+): { status: number; body: Record<string, unknown> } {
+  if (err instanceof WorkflowDomainError && err.status < 500) {
+    // Spread the payload FIRST and assign `error` LAST — a payload key named
+    // `error` must never overwrite the message the client renders.
+    return { status: err.status, body: { ...(err.payload ?? {}), error: err.message } };
+  }
+  console.error(`[${logTag}] route failure:`, err instanceof Error ? err.stack ?? err.message : err);
+  const status = err instanceof WorkflowDomainError ? err.status : 500;
+  return { status, body: { error: 'Internal error.' } };
+}
+
+/** Answer `res` with the shared error shape. */
+export function sendError(res: express.Response, err: unknown, logTag: string): void {
+  const { status, body } = toHttpError(err, logTag);
+  res.status(status).json(body);
+}
+
+/**
+ * Coerce a request-body field that must be a non-empty string. Rejects arrays,
+ * objects, numbers, null — anything `String()` would silently stringify into a
+ * bogus principal name / email (`[object Object]`, `"a,b"`) — with a 400
+ * instead of persisting garbage. Returns the raw string (untrimmed by default
+ * — services trim; pass `trim: true` where the route owns normalization).
+ */
+export function requireNonEmptyString(
+  value: unknown,
+  field: string,
+  opts?: { trim?: boolean },
+): string {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new WorkflowDomainError(`${field} must be a non-empty string`, 400);
+  }
+  return opts?.trim ? value.trim() : value;
+}

package/src/modules/access/capability-registry.ts

@@ -0,0 +1,74 @@
+/**
+ * Capability registry — the "what you can do in the app" half of the
+ * roles/groups split.
+ *
+ * Roles are CODE-DEFINED capability bundles: the product decides which roles
+ * exist and what each unlocks; admins assign them (to individuals, and to
+ * groups via `group:` members in roles.yaml — every role, Admin included,
+ * kept safe by the parse-time at-least-one-direct-email invariant on Admin).
+ * Something like "Developer" is not a role; that's a group.
+ *
+ * Adding a future role (the planned Plugin Creator) is a registry entry plus
+ * capability gates at its feature surfaces — never a parser change: the
+ * roles.yaml grammar, expansion, and admin surfaces are already
+ * role-name-agnostic.
+ *
+ * A roles.yaml role NOT in this registry is a LEGACY people-set role from
+ * before the split (e.g. "Product") — still valid as a grant principal, but
+ * really a group; the roles admin surface flags it with a convert action.
+ */
+
+import { ADMIN_CANONICAL, canonicalRoleName } from './access-control.service.js';
+
+/** A capability an app surface gates on. Grow this union with the gates. */
+export type Capability =
+  | 'manage-deployment'
+  | 'manage-accounts'
+  | 'manage-roles'
+  | 'manage-groups'
+  | 'manage-directory';
+
+export interface CapabilityRole {
+  canonical: string;
+  displayName: string;
+  /** Admin-facing one-liner for the Roles page. */
+  description: string;
+  capabilities: readonly Capability[];
+  /**
+   * Whether the role may be assigned to groups. True for every role, Admin
+   * included — with the parse-time invariant that Admin ALWAYS keeps at least
+   * one direct email member (see `parseRolesYaml`), so a misconfigured or
+   * unreachable directory can never leave the deployment without a
+   * directory-independent admin.
+   */
+  groupAssignable: boolean;
+}
+
+export const CAPABILITY_ROLES: readonly CapabilityRole[] = [
+  {
+    canonical: ADMIN_CANONICAL,
+    displayName: 'Admin',
+    description:
+      'Detailed configuration: deployment settings, user accounts, roles & groups, and the directory connection.',
+    capabilities: [
+      'manage-deployment',
+      'manage-accounts',
+      'manage-roles',
+      'manage-groups',
+      'manage-directory',
+    ],
+    groupAssignable: true,
+  },
+  // Planned next (lands with its feature gates, not before):
+  // { canonical: 'plugin creator', displayName: 'Plugin Creator', … }
+];
+
+export function capabilityRoleFor(roleName: string): CapabilityRole | null {
+  const canonical = canonicalRoleName(roleName);
+  return CAPABILITY_ROLES.find((r) => r.canonical === canonical) ?? null;
+}
+
+/** A roles.yaml role that is NOT a capability role — a pre-split people-set. */
+export function isLegacyPeopleSetRole(roleName: string): boolean {
+  return capabilityRoleFor(roleName) === null;
+}

package/src/modules/access/directory-sync-bot.ts

@@ -0,0 +1,76 @@
+import { eq } from 'drizzle-orm';
+import type { AuthUser } from '@bevel-software/platform-shared';
+import type { Database } from '../database/connection.js';
+import { users } from '../database/core-schema.js';
+
+/**
+ * Synthetic identity for the synced-groups materializer's commits: every
+ * `synced-groups.yaml` regeneration lands attributed to this bot, so the git
+ * history reads as "the system mirrored the IdP", never as any human.
+ * Same `<role>-bot@<host>` convention (and race-safe ensure shape) as the
+ * recovery bot.
+ */
+
+// Trimmed BEFORE the empty-fallback so a whitespace-only override falls back,
+// and so the constant always compares equal to a trimmed caller email (the
+// machine-owned write rule trims the caller's side).
+export const DIRECTORY_SYNC_BOT_EMAIL = (
+  process.env.DIRECTORY_SYNC_BOT_EMAIL?.trim() || 'directory-sync@bevel.local'
+).toLowerCase();
+
+export const DIRECTORY_SYNC_BOT_NAME = 'Directory Sync Bot';
+
+export async function ensureDirectorySyncBot(db: Database): Promise<AuthUser> {
+  const inserted = await db
+    .insert(users)
+    .values({ email: DIRECTORY_SYNC_BOT_EMAIL, name: DIRECTORY_SYNC_BOT_NAME })
+    .onConflictDoNothing({ target: users.email })
+    .returning();
+  if (inserted.length > 0) {
+    const row = inserted[0];
+    console.log(`[directory-sync] created sync-bot user id=${row.id} email=${row.email}`);
+    return { id: row.id, email: row.email, name: row.name, avatarUrl: row.avatarUrl ?? undefined };
+  }
+  const [row] = await db
+    .select()
+    .from(users)
+    .where(eq(users.email, DIRECTORY_SYNC_BOT_EMAIL))
+    .limit(1);
+  if (!row) {
+    throw new Error(
+      `directory-sync bot (${DIRECTORY_SYNC_BOT_EMAIL}) disappeared between insert-conflict and re-select`,
+    );
+  }
+  // The bot's IDENTITY is its email: the machine-owned write rule on
+  // synced-groups.yaml authorizes by DIRECTORY_SYNC_BOT_EMAIL alone. If the
+  // email already belongs to a pre-existing HUMAN account (a person signed up
+  // with it, or the override points at someone's address), silently binding
+  // the materializer to that row would attribute every sync commit to them —
+  // and, worse, hand their interactive session the bot's exclusive write
+  // authority. The users schema carries no dedicated bot/provenance column,
+  // so adoption gates on the strongest invariants the row can carry:
+  //   1. NO PASSWORD. The bot is only ever created by this function, without
+  //      credentials, and never signs in — nothing legitimate ever provisions
+  //      it a password. A row with a password hash is a login-capable account
+  //      (a person, or a credential a person could use) no matter what its
+  //      display name says, so the hash is the hard evidence a name can't be.
+  //   2. THE EXPECTED NAME. A display name is mutable and a human account
+  //      could carry the bot's name (e.g. an SSO service account), so this is
+  //      only a tripwire — it still catches password-less human rows created
+  //      under their real names.
+  // A password-less SSO account that also mimics the bot's exact display name
+  // is indistinguishable at this layer; that shape only arises from the
+  // operator deliberately configuring it. Refuse loudly instead of adopting.
+  if (row.passwordHash !== null || row.name !== DIRECTORY_SYNC_BOT_NAME) {
+    const evidence =
+      row.passwordHash !== null
+        ? `it can sign in with a password (name '${row.name}')`
+        : `its name is '${row.name}'`;
+    throw new Error(
+      `directory-sync bot email ${DIRECTORY_SYNC_BOT_EMAIL} already belongs to an existing account ` +
+        `(id=${row.id}) that is not the sync bot — ${evidence}. Refusing to bind the materializer ` +
+        `to it. Set DIRECTORY_SYNC_BOT_EMAIL to an address no person uses.`,
+    );
+  }
+  return { id: row.id, email: row.email, name: row.name, avatarUrl: row.avatarUrl ?? undefined };
+}