@bevel-software/platform-core-backend 0.15.1 → 0.20.0

package/dist/modules/access/user-access-removal.service.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Removing a deleted account's ADDRESS from the knowledge base's access
+ * files — the optional half of account deletion ("Also remove them from
+ * roles, groups and access rules").
+ *
+ * Erasure (`AccountErasureService`) cleans the database; the address itself
+ * also sits in files: `roles.yaml` members, group files, `access.md` entries
+ * under any verb, and node-frontmatter grants. This service counts those
+ * places (for the confirmation dialog) and removes them in ONE commit on the
+ * default branch, authored by the acting admin, with a message that names the
+ * erased account by its anonymised id — never the email. Git history keeps
+ * the old entries, by policy (see AccountErasureService).
+ *
+ * Guards (the ones the roles admin already enforces stay in force here): the
+ * deployment owner (`ADMIN_EMAIL`) and the Admin role's last direct email
+ * member are never removed this way.
+ *
+ * `synced-groups.yaml` is machine-owned (only the directory-sync bot may
+ * write it), so it is counted but never written — its entries go away when
+ * the identity provider stops sending the person, and until then the file is
+ * reported as still naming them.
+ *
+ * The cleanup is NOT all-or-nothing across files the acting admin cannot
+ * write. A subfolder may exclude Admin, and the lock gate refuses per file, so
+ * one such grant would otherwise abort everything and leave the address in
+ * `roles.yaml`, the group file and every other `access.md` too. Those files
+ * are skipped, reported in `stillNamedIn`, and named in the confirmation
+ * dialog beforehand (`UserReferenceReport.unwritable`). A folder that cannot
+ * be LISTED remains a hard refusal: an incomplete scan would commit a partial
+ * cleanup that looks complete.
+ *
+ * That write pre-check is an optimisation over the lock gate, never a second
+ * authority. When it cannot be run at all, the dialog says so (`unwritable:
+ * null`, never `[]`) and the removal attempts every file: the gate still
+ * refuses what the admin may not write, and skipping files on a hunch could
+ * only clean less.
+ */
+import type { WorkflowEventBus } from '../workflow/event-bus.js';
+import type { AuthUser, IWorkspaceService, IWorkflowService } from '@bevel-software/platform-shared';
+import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import type { IAccessControl } from './access-control.interface.js';
+import type { ITreeWalker } from '../../shared/fs.contract.js';
+/** A removal this service refuses (guard) or cannot run. */
+export declare class UserAccessRemovalError extends WorkflowDomainError {
+    constructor(message: string, status?: number, payload?: Record<string, unknown>);
+}
+/** How many places in the knowledge base name one address, by kind. */
+export interface UserReferenceCounts {
+    /** Roles in `roles.yaml` listing the address as a member. */
+    roles: number;
+    /** Groups (manual and synced) listing the address. */
+    groups: number;
+    /** Entries in `access.md` files, any verb, frontmatter and body. */
+    accessRules: number;
+    /** Entries in other files' own frontmatter (`.md`, `.tool`). */
+    fileGrants: number;
+    total: number;
+    /** Repo-relative paths of every file that names the address, sorted. */
+    files: string[];
+}
+/** The confirmation dialog's view: counts plus whether removal may run. */
+export interface UserReferenceReport extends UserReferenceCounts {
+    removable: boolean;
+    /** Why removal is refused, in words the dialog shows; null when removable. */
+    blockedReason: string | null;
+    /**
+     * Of `files`, the ones the ACTING ADMIN may not write (a folder that
+     * excludes Admin, or the machine-owned `synced-groups.yaml`). The cleanup
+     * skips these and reports them; the dialog says so before the delete.
+     * `null` when write access could not be judged at all — never read as
+     * "none", same convention as {@link UserAccessRemovalResult.stillNamedIn}.
+     */
+    unwritable: string[] | null;
+}
+/** The outcome of a committed removal. */
+export interface UserAccessRemovalResult {
+    /** Files the commit changed. */
+    removedFrom: string[];
+    /**
+     * Files that still name the address afterwards (e.g. synced-groups.yaml);
+     * null when they could not be checked — never read as "none".
+     */
+    stillNamedIn: string[] | null;
+    /** The commit landed but its push did not; publishing is retried. */
+    publishPending?: boolean;
+}
+/**
+ * Entries naming `email` in one access-frontmatter file: its own frontmatter,
+ * plus — for a body-governed `access.md` — the body's folder rules. The
+ * resolver's own parsers, so the count is what is actually enforced.
+ */
+export declare function countUserEntriesInAccessText(text: string, repoRel: string, email: string): number;
+/**
+ * Remove every entry naming `email` from one access-frontmatter file, under
+ * every verb. Uses the share dialog's revoke splice, so comments, ordering
+ * and prose bodies stay byte-for-byte. A file the splice cannot edit safely
+ * (unterminated frontmatter) is returned unchanged.
+ */
+export declare function removeUserFromAccessText(text: string, repoRel: string, email: string): string;
+/**
+ * Remove `email` from the top-level verb keys of a file's own frontmatter in
+ * the forms the splice does not edit: a quoted scalar (`read: "A <a@x>"`), a
+ * one-line flow list (`read: [A <a@x>, "B <b@x>"]`) and quoted list items.
+ * Other lines stay byte-for-byte; a verb left empty becomes `verb: []`.
+ */
+export declare function removeQuotedOrFlowFrontmatterEntries(text: string, email: string): string;
+/**
+ * Remove `email` from every member list of a roles/groups file by deleting
+ * its list lines in place — comments, the header and ordering survive. A key
+ * left with no items becomes `Key: []`. Callers check the result parses to
+ * the model they expect and fall back to a canonical re-emit otherwise.
+ */
+export declare function removeEmailListLines(text: string, email: string): string;
+export declare class UserAccessRemovalService {
+    private readonly workspaceService;
+    private readonly accessControl;
+    /**
+     * The resolver's own walk. NOT `workspaceService.listFiles`: that honours
+     * `.bevelignore`, and the seeded template hides every `access.md` — a
+     * scan built on it finds no access rule at all.
+     */
+    private readonly disk;
+    private readonly kbDirName;
+    /** Live-binding thunk — DEFAULT_BRANCH stays empty until setup. */
+    private readonly defaultBranchOf;
+    private readonly eventBus?;
+    /** The deployment owner(s) (`ADMIN_EMAIL`) — never removed this way. */
+    private readonly deploymentOwners;
+    private readonly locked;
+    constructor(workspaceService: IWorkspaceService, workflowService: IWorkflowService, accessControl: IAccessControl, 
+    /**
+     * The resolver's own walk. NOT `workspaceService.listFiles`: that honours
+     * `.bevelignore`, and the seeded template hides every `access.md` — a
+     * scan built on it finds no access rule at all.
+     */
+    disk: ITreeWalker, kbDirName: string, 
+    /** Live-binding thunk — DEFAULT_BRANCH stays empty until setup. */
+    defaultBranchOf: () => string, eventBus?: WorkflowEventBus | undefined, 
+    /** The deployment owner(s) (`ADMIN_EMAIL`) — never removed this way. */
+    deploymentOwners?: readonly string[]);
+    private get defaultBranch();
+    private ensureWorkspace;
+    /**
+     * Every `access.md` and access-frontmatter file (`.md`, `.tool`) in the
+     * checkout, repo-relative — the walk the access resolver itself does, with
+     * `.bevelignore` NOT honoured, plus the folders that could not be listed.
+     */
+    private accessFiles;
+    /**
+     * Read every file that could name `email`: roles, both group files, and the
+     * access files whose text actually contains the address. Reads run through a
+     * bounded pool, and a candidate the address does not even appear in is
+     * dropped before either parser sees it — the parsers only ever confirm and
+     * count entries for this one address, so a file without the substring can
+     * hold none. The roster files are always kept: `blockedReason` reads
+     * `roles.yaml` whether or not the address is in it.
+     */
+    private readAll;
+    /**
+     * Of `files`, the ones `actorEmail` may not write on the default branch —
+     * or `null` when the question could not be ASKED (the lookup threw), which
+     * is not the same as "none".
+     *
+     * Since #210 a subfolder may exclude Admin, and the lock gate refuses per
+     * file: without this split ONE such grant would abort the whole cleanup —
+     * nothing committed, and the address left in `roles.yaml`, the group file
+     * and every other `access.md` too, with the admin learning it only from the
+     * outcome.
+     *
+     * A `null` VERDICT is a real answer, not uncertainty: it means no usable
+     * access config resolves at the ref, and `GitService.assertCanWriteAtRef`
+     * default-ALLOWS on exactly that signal (bootstrap — you cannot create
+     * `roles.yaml` if writing it needs `roles.yaml`). Reporting `[]` there
+     * matches the gate that will actually run. A THROWN lookup is different:
+     * nothing is known, so say so rather than claim "none".
+     */
+    private unwritableAmong;
+    private countIn;
+    /** Why `email` may not be removed from access files, or null when it may. */
+    private blockedReason;
+    /**
+     * Counts + guard verdict for the delete confirmation. `actorEmail` is the
+     * ADMIN doing the deleting (not the account being deleted): the same write
+     * check `remove` applies, so the dialog can say up front which files will
+     * keep the address because this admin may not write them.
+     */
+    report(rawEmail: string, actorEmail?: string): Promise<UserReferenceReport>;
+    /** Throws a 409 when the guards refuse removing `email`. */
+    assertRemovable(rawEmail: string): Promise<void>;
+    /** Files that still name `email` right now (best-effort reporting). */
+    filesNaming(rawEmail: string): Promise<string[]>;
+    /**
+     * Remove `email` from roles.yaml, groups.yaml and every access file the
+     * ACTING ADMIN may write, in ONE commit. `erasedId` names the account in the
+     * commit message. A file naming the address that this admin may not write is
+     * skipped rather than aborting the cleanup, and comes back in
+     * `stillNamedIn`. Throws on any failure BEFORE the commit (guard, a folder
+     * that cannot be listed, lock contention, invalid candidate, commit) with
+     * nothing committed. Once the commit has landed it never throws: a push that
+     * needs resolution is reported as `publishPending`, and a failed re-scan as
+     * `stillNamedIn: null`.
+     */
+    remove(actor: AuthUser, rawEmail: string, erasedId: string): Promise<UserAccessRemovalResult>;
+    /** The candidate text for one file with `email` removed (validated). */
+    private removeFrom;
+    /** Same nudge the roles/groups admins send: open clients refetch. */
+    private emitWrites;
+}
+//# sourceMappingURL=user-access-removal.service.d.ts.map

package/dist/modules/access/user-access-removal.service.d.ts.map

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