@bevel-software/platform-core-backend 0.1.0

package/dist/modules/access/roles-admin.service.d.ts

@@ -0,0 +1,240 @@
+/**
+ * Admin Roles & Members service — full CRUD on the default-branch `roles.yaml`.
+ *
+ * This is the deferred "Slice 2" of `manage-access-grant-revoke`: the in-product
+ * surface for creating/deleting roles, adding/removing members, and renaming a
+ * role. It is the ONLY writer of `roles.yaml` outside a hand-edit, and it is
+ * built around one non-negotiable safety property:
+ *
+ *   roles.yaml has NO admin-rescue (canWrite('roles.yaml') is a pure isAdmin
+ *   check) and loadModel HARD-THROWS on a parse failure (which isAdmin swallows
+ *   into false for EVERYONE). So a single malformed write = a permanent,
+ *   app-wide, in-app-unrecoverable admin lockout. Every mutation therefore runs
+ *   the candidate text through the resolver's OWN parser (validateRolesYaml)
+ *   before a byte hits disk; on any error it writes nothing.
+ *
+ * Two write paths, both gated by the same friendly pre-checks + validate gate:
+ *
+ *   Single-file ops (create/delete role, add/remove member) — `runEdit`:
+ *     pre-check roles.yaml isn't locked  → RolesAdminError 409
+ *     read CURRENT roles.yaml → parse → edit-in-memory → re-emit candidate
+ *     validateRolesYaml(candidate)       → RolesAdminError 422, write nothing
+ *     LockingFilesystem.writeFile(roles.yaml)  ← acquire → write → release;
+ *       release IS the commit + push (default per-file summary), so the commit
+ *       lands a beat after the write — same pipeline the human editor + agent
+ *       use. The HTTP roster reads the (synchronously written) working tree.
+ *
+ *   Rename (`renameRole`) — keeps an ATOMIC multi-file special case because it
+ *   rewrites roles.yaml + every reference in ONE commit (a partial rewrite =
+ *   silent access drop):
+ *     pre-check roles.yaml isn't locked  → RolesAdminError 409
+ *     parse + rewrite refs (fail-closed) → validate gate
+ *     LockingFilesystem.writeFiles(roles.yaml + refs)  ← acquires every path's
+ *       lock, commits the curated set as ONE change (via the workflow service's
+ *       commitChanges), then releases without a per-file commit.
+ *
+ * All reads and writes target the DEFAULT branch — the file admin status itself
+ * derives from. Editing any other branch's copy would show a roster that
+ * doesn't match who is actually an admin.
+ */
+import type { WorkflowEventBus } from '../workflow/event-bus.js';
+import type { AuthUser, IWorkspaceService, IWorkflowService } from '@bevel-software/platform-shared';
+import { WorkflowDomainError } from '../workflow/workflow.errors.js';
+import type { IAccessControl } from './access-control.interface.js';
+/** A mutation that cannot proceed (invariant violation, contention, not found). */
+export declare class RolesAdminError extends WorkflowDomainError {
+    constructor(message: string, status?: number, payload?: Record<string, unknown>);
+}
+/** One role as the Roles & Members page renders it. */
+export interface RoleRosterEntry {
+    canonical: string;
+    displayName: string;
+    members: string[];
+    isAdmin: boolean;
+    /**
+     * Every access rule referencing this role — folder `access.md` AND node
+     * frontmatter. Sound: this is the SAME scan the rename rewrite uses, so the
+     * delete warning's count matches what a delete/rename would actually touch.
+     */
+    referencedBy: {
+        path: string;
+        verb: string;
+    }[];
+}
+/** Health of the default-branch roles.yaml: does the resolver's parser accept it? */
+export interface RolesConfigHealth {
+    ok: boolean;
+    errors: string[];
+}
+export declare class RolesAdminService {
+    private readonly workspaceService;
+    private readonly workflowService;
+    private readonly accessControl;
+    private readonly kbDirName;
+    /** The branch whose roles.yaml is authoritative for admin status. */
+    private readonly defaultBranch;
+    /**
+     * Optional so existing tests can construct the service without an event
+     * bus. When present, every committed write announces itself so already-open
+     * clients re-fetch the changed files and re-evaluate their permissions —
+     * a roles.yaml / access.md change is an access change, and without this an
+     * open tab keeps a now-stale read verdict until a manual reload.
+     */
+    private readonly eventBus?;
+    constructor(workspaceService: IWorkspaceService, workflowService: IWorkflowService, accessControl: IAccessControl, kbDirName: string, 
+    /** The branch whose roles.yaml is authoritative for admin status. */
+    defaultBranch: string, 
+    /**
+     * Optional so existing tests can construct the service without an event
+     * bus. When present, every committed write announces itself so already-open
+     * clients re-fetch the changed files and re-evaluate their permissions —
+     * a roles.yaml / access.md change is an access change, and without this an
+     * open tab keeps a now-stale read verdict until a manual reload.
+     */
+    eventBus?: WorkflowEventBus | undefined);
+    private get workspaceId();
+    /**
+     * Announce committed writes so watching clients refresh. Emits one
+     * `file-changed` per written file (workspace-relative path — the form the
+     * frontend keys tabs on, NOT the bare repo-relative path `commitChanges` takes)
+     * plus a single `fs-tree-changed`. `newSha: null` — the roster response is the
+     * authoritative post-commit state; clients only need the "go refetch" nudge.
+     */
+    private emitWrites;
+    /** Ensure the authoritative clone exists, then return its workspace id. */
+    private ensureWorkspace;
+    private repoDir;
+    /**
+     * 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.
+     */
+    private lockingFsForActor;
+    /**
+     * Fail fast with a friendly 409 if roles.yaml is already locked by someone
+     * else. The actual lock is taken by the LockingFilesystem write that follows;
+     * this only preserves the explicit "being edited by X" contract (the raw
+     * LockingFilesystem contention error is status-less and would surface as 500).
+     */
+    private assertRolesUnlocked;
+    /**
+     * Run a lock-aware filesystem write, mapping its status-less contention error
+     * ("Skipped editing … — locked by …") to the friendly 409. {@link
+     * assertRolesUnlocked} pre-checks the common case (and names the holder), but
+     * it's a TOCTOU check — another admin can grab the lock between it and the
+     * actual acquire inside the write. This catches that race so contention always
+     * surfaces as a 409, never an unhandled 500.
+     */
+    private mapLockContention;
+    private readRolesYaml;
+    /** The roster: every role on the default branch with members + references. */
+    getRoster(): Promise<RoleRosterEntry[]>;
+    /**
+     * Whether the default-branch roles.yaml parses. Drives the "roles file
+     * corrupted" banner. Auth-only (never admin-gated): a corrupted file resolves
+     * NOBODY as admin, so an admin-gated health check could never report the very
+     * state it exists to detect. A missing/empty file counts as corrupted —
+     * loadModel hard-throws on it exactly as it does on malformed YAML.
+     */
+    getHealth(): Promise<RolesConfigHealth>;
+    /**
+     * Break-glass recovery for a corrupted roles.yaml (the "Bevel Recovery"
+     * button). Copies the corrupted file to `old-roles.yaml` and restores the
+     * known-good default in ONE atomic commit, then returns the fresh roster.
+     *
+     * Authorization: this is the ONE roles mutation that is NOT admin-gated —
+     * by construction a corrupted roles.yaml resolves nobody as admin, so an
+     * admin gate would make recovery impossible (the lockout the user reported).
+     * Instead it is gated on the file ACTUALLY being unparseable: if roles.yaml
+     * is valid, recovery is refused (409) so it can never be used as an
+     * unauthenticated roster reset. The "only press if you are from Bevel" UI
+     * copy is the honour-system layer on top of that hard gate.
+     *
+     * This works on the protected default branch because the commit/push access
+     * gate reads roles.yaml AT-REF and fails OPEN when it can't parse (treating a
+     * broken config as "no rules in force") — so the restoring write is allowed
+     * through precisely when the file is broken.
+     */
+    recover(actor: AuthUser): Promise<RoleRosterEntry[]>;
+    createRole(actor: AuthUser, displayName: string): Promise<RoleRosterEntry[]>;
+    deleteRole(actor: AuthUser, canonical: string): Promise<RoleRosterEntry[]>;
+    addMember(actor: AuthUser, canonical: string, email: string): Promise<RoleRosterEntry[]>;
+    /**
+     * Remove a member. Refuses to empty the Admin role (422). Removing the
+     * caller's OWN last Admin membership requires `confirm` (409 otherwise) — no
+     * silent self-lockout, since admin status is read live from this file.
+     */
+    removeMember(actor: AuthUser, canonical: string, email: string, confirm: boolean): Promise<RoleRosterEntry[]>;
+    /**
+     * Rename a role's display name.
+     *   - canonical UNCHANGED (casing/whitespace) → single roles.yaml edit.
+     *   - canonical CHANGES → rewrite every genuine role reference in access.md +
+     *     node frontmatter AND roles.yaml in ONE atomic commit.
+     *   - Admin canonical → non-admin canonical is refused (400): it would break
+     *     isAdminEmail's roles.has('admin') lookup. Casing-only Admin OK.
+     */
+    renameRole(actor: AuthUser, canonical: string, newDisplayName: string): Promise<RoleRosterEntry[]>;
+    /** Map a RolesEditError to a RolesAdminError (preserving status). */
+    private guardEdit;
+    private assertLoadable;
+    /**
+     * Single-file roles.yaml mutation. `pre` produces the candidate (and may throw
+     * RolesAdminError for invariant violations before any write). Skips on a no-op.
+     *
+     * The write goes through a {@link LockingFilesystem}: acquiring the per-file
+     * lock, writing, then releasing — and release IS the commit + push (attributed
+     * to `actor`), the same pipeline the human editor and agent use. So unlike the
+     * rename's synchronous atomic commit, the git commit here lands on release
+     * (a beat after the write); the HTTP response reads the working tree, which is
+     * already on disk, so the returned roster is correct.
+     */
+    private runEdit;
+    /**
+     * Find every genuine role reference to `oldCanonical` across folder access.md
+     * AND node frontmatter, and rewrite each to `newDisplayName`. Reference-aware:
+     * a line is rewritten ONLY if it PARSES as a role entry whose canonical name
+     * == oldCanonical. Prose, comments, `Name <email>` user entries, other keys,
+     * and substrings never match. Returns the repo-relative writes to commit.
+     */
+    private rewriteRoleReferences;
+    /**
+     * Repo-relative paths of every file that could carry a role reference: all
+     * `access.md` files plus every `.md` node (its own frontmatter). Sourced from
+     * the workspace file tree (which already skips `.git` and honours
+     * `.bevelignore`), filtered to `.md` under the KB dir and returned bare
+     * repo-relative. (`roles.yaml` isn't `.md`, so it's excluded; the rename
+     * commits it separately.) Under save=share the working tree matches the
+     * committed set, so this is the same candidate list git-tracking would give.
+     */
+    private collectCandidateFiles;
+    /**
+     * Sound scan of EVERY `.md` (folder `access.md` + node frontmatter)
+     * for genuine role references, indexed by canonical role name. Shares the
+     * candidate set and the config-region role-entry parse with the rename
+     * rewrite (`findRoleRefsInText` / `rewriteRoleTokensInText`), so the delete
+     * warning and the rename rewrite see the SAME references — the warning can no
+     * longer undercount frontmatter the rename would touch. A file we cannot read
+     * is skipped (this is an advisory read, not the atomic write path): missing a
+     * reference here only weakens the warning, it cannot drop access.
+     */
+    private scanRoleReferences;
+}
+/** Every genuine role reference in `text`'s config region, as {role, verb}. */
+export declare function findRoleRefsInText(text: string, isMarkdown?: boolean): {
+    role: string;
+    verb: string;
+}[];
+/**
+ * Rewrite every CONFIG-REGION line that PARSES as a role reference whose
+ * canonical name == `oldCanonical`, replacing the role token with
+ * `newDisplayName` (preserving any leading `deny ` and indentation). Only the
+ * frontmatter block of a markdown file is touched — the body is left
+ * byte-for-byte intact, so a prose line like `- Sales` is never corrupted.
+ * Lines that don't parse as a matching role entry (user entries, other keys,
+ * substrings) are also untouched. Exported for test.
+ *
+ * `isMarkdown` (default true) marks files that carry a markdown body below the
+ * frontmatter; pass false only for a pure-config file with no body.
+ */
+export declare function rewriteRoleTokensInText(text: string, oldCanonical: string, newDisplayName: string, isMarkdown?: boolean): string;
+//# sourceMappingURL=roles-admin.service.d.ts.map

package/dist/modules/access/roles-admin.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles-admin.service.d.ts","sourceRoot":"","sources":["../../../src/modules/access/roles-admin.service.ts"],"names":[],"mappings":"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"}