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

package/dist/modules/access/groups-edit.js

@@ -0,0 +1,162 @@
+/**
+ * Pure parse → edit → re-emit editor for `groups.yaml` — the manual-mode
+ * group file. Mirrors `roles-edit.ts` (same re-emit rationale: no body, no
+ * comments to preserve, deterministic canonical output), with two deliberate
+ * differences:
+ *
+ *   - No Admin invariants — groups carry no capabilities, so there is no
+ *     lockout class of mistake here.
+ *   - Members are EMAILS ONLY. `group:` references are a roles.yaml grammar
+ *     (a role assigned to a group); a group containing a group is nesting,
+ *     which is a deliberate non-goal.
+ *
+ * Policy that needs more than this file's text — IdP-mode gating, collision
+ * with role names — lives in `groups-admin.service.ts`.
+ */
+import { canonicalRoleName, canonicalEmail, EMAIL_REGEX, GROUP_REF_PREFIX, RESERVED_ROLE_NAMES, } from './access-control.service.js';
+import { GROUPS_YAML, parseGroupsFile, unsafeNameReason } from './group-files.js';
+/** Bad-input failure when editing groups.yaml. */
+export class GroupsEditError extends Error {
+    status;
+    constructor(message, status = 422) {
+        super(message);
+        this.name = 'GroupsEditError';
+        this.status = status;
+    }
+}
+/** Thin assert wrapper over the SHARED name-safety predicate (`group-files.ts`
+ *  `unsafeNameReason`) — one namespace, one set of rules, including the
+ *  reserved `role/` prefix. */
+export function assertSafeGroupDisplayName(displayName) {
+    const reason = unsafeNameReason(displayName);
+    if (reason) {
+        throw new GroupsEditError(`group name ${reason}: ${JSON.stringify(displayName)}`);
+    }
+}
+/**
+ * Parse groups.yaml into the ordered model; `[]` for an empty/missing file.
+ *
+ * DERIVED from the resolver's own `parseGroupsFile` — one parser for the
+ * grammar, so the editor's skip rules (empty/reserved/duplicate names,
+ * malformed member emails) can never drift from the resolver's: the admin
+ * roster and the edit surface must never show an entry the resolver ignores,
+ * or an admin "manages" a group that grants nothing. Consequence, deliberate:
+ * the next edit's re-emit garbage-collects those dead entries from the file.
+ * Structural failures throw GroupsEditError (422) — the caller reads under
+ * the lock, so a broken on-disk file is an operator problem surfaced loudly,
+ * not a silent reset.
+ */
+export function parseGroupsModel(text) {
+    if (!text.trim())
+        return [];
+    const parsed = parseGroupsFile(text, GROUPS_YAML);
+    if (!parsed.ok)
+        throw new GroupsEditError(parsed.errors.join('; '));
+    return [...parsed.groups.values()].map((def) => ({
+        displayName: def.displayName,
+        members: [...def.emails],
+    }));
+}
+/** Deterministic canonical emit; empty groups as `Name: []`. */
+export function emitGroupsModel(model) {
+    const lines = ['groups:'];
+    for (const group of model) {
+        if (group.members.length === 0) {
+            lines.push(`  ${group.displayName}: []`);
+        }
+        else {
+            lines.push(`  ${group.displayName}:`);
+            for (const email of group.members)
+                lines.push(`    - ${email}`);
+        }
+    }
+    return lines.join('\n') + '\n';
+}
+function findGroup(model, canonical) {
+    return model.find((g) => canonicalRoleName(g.displayName) === canonical);
+}
+function reemit(original, model) {
+    const text = emitGroupsModel(model);
+    let originalCanonical;
+    try {
+        originalCanonical = emitGroupsModel(parseGroupsModel(original));
+    }
+    catch {
+        originalCanonical = original;
+    }
+    return { text, changed: text !== originalCanonical };
+}
+export function createGroup(text, displayName) {
+    assertSafeGroupDisplayName(displayName);
+    const canonical = canonicalRoleName(displayName);
+    if (RESERVED_ROLE_NAMES.has(canonical)) {
+        throw new GroupsEditError(`'${displayName.trim()}' is a reserved name and cannot be a group`);
+    }
+    const model = parseGroupsModel(text);
+    if (findGroup(model, canonical)) {
+        throw new GroupsEditError(`a group named '${displayName.trim()}' already exists`);
+    }
+    model.push({ displayName: displayName.trim(), members: [] });
+    return reemit(text, model);
+}
+export function deleteGroup(text, canonical) {
+    const model = parseGroupsModel(text);
+    const idx = model.findIndex((g) => canonicalRoleName(g.displayName) === canonical);
+    if (idx < 0)
+        throw new GroupsEditError(`group not found: ${canonical}`, 404);
+    model.splice(idx, 1);
+    return reemit(text, model);
+}
+export function addGroupMember(text, canonical, rawEmail) {
+    const email = canonicalEmail(rawEmail);
+    // A `group:`-prefixed value is roles.yaml grammar (a role assigned to a
+    // group) — and `group:lee@x.io` would pass the email regex, landing a dead
+    // entry the resolver reads as a plain (never-matching) address. Mirrors
+    // `roles-edit.ts` addMember; groups do not nest, so there is no "right
+    // editor" to route to — a group member is always an email.
+    if (email.startsWith(GROUP_REF_PREFIX)) {
+        throw new GroupsEditError(`member ${JSON.stringify(rawEmail)} starts with '${GROUP_REF_PREFIX}' — a group member is always a person's email (groups cannot contain other groups). Drop the '${GROUP_REF_PREFIX}' prefix and add the email itself`);
+    }
+    if (!EMAIL_REGEX.test(email)) {
+        throw new GroupsEditError(`malformed email: ${JSON.stringify(rawEmail)}`);
+    }
+    const model = parseGroupsModel(text);
+    const group = findGroup(model, canonical);
+    if (!group)
+        throw new GroupsEditError(`group not found: ${canonical}`, 404);
+    if (group.members.includes(email))
+        return { text: emitGroupsModel(model), changed: false };
+    group.members.push(email);
+    return reemit(text, model);
+}
+export function removeGroupMember(text, canonical, rawEmail) {
+    const email = canonicalEmail(rawEmail);
+    const model = parseGroupsModel(text);
+    const group = findGroup(model, canonical);
+    if (!group)
+        throw new GroupsEditError(`group not found: ${canonical}`, 404);
+    const idx = group.members.indexOf(email);
+    if (idx < 0)
+        return { text: emitGroupsModel(model), changed: false };
+    group.members.splice(idx, 1);
+    return reemit(text, model);
+}
+/** Rename a group's display name (canonical may change — service layer owns
+ *  the reference rewrite when it does). */
+export function renameGroupDisplay(text, canonical, newDisplayName) {
+    assertSafeGroupDisplayName(newDisplayName);
+    const newCanonical = canonicalRoleName(newDisplayName);
+    if (RESERVED_ROLE_NAMES.has(newCanonical)) {
+        throw new GroupsEditError(`'${newDisplayName.trim()}' is a reserved name and cannot be a group`);
+    }
+    const model = parseGroupsModel(text);
+    const group = findGroup(model, canonical);
+    if (!group)
+        throw new GroupsEditError(`group not found: ${canonical}`, 404);
+    if (newCanonical !== canonical && findGroup(model, newCanonical)) {
+        throw new GroupsEditError(`a group named '${newDisplayName.trim()}' already exists`);
+    }
+    group.displayName = newDisplayName.trim();
+    return reemit(text, model);
+}
+//# sourceMappingURL=groups-edit.js.map

package/dist/modules/access/groups-edit.js.map

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

package/dist/modules/access/reference-scan.d.ts

@@ -0,0 +1,141 @@
+/**
+ * SHARED grant-reference machinery — the single implementation both admin
+ * services (roles + groups) drive for "which access rules name this
+ * principal" and "rewrite every reference atomically":
+ *
+ *   - `findRoleRefsInText` / `rewriteRoleTokensInText`: the config-region
+ *     parse that decides what IS a principal reference. One source of truth,
+ *     so the delete/rename warning and the rename rewrite can never disagree.
+ *   - `KbReferenceScanner`: candidate collection (every KB file with an
+ *     access-frontmatter extension — `.md` and `.tool`, the resolver's own
+ *     set), the advisory reference scan (cached — roster mutations must not
+ *     rerun a full-KB read sweep, invalidated by file-changed events and a
+ *     TTL backstop), and the fail-closed reference rewrite (returns each
+ *     file's ORIGINAL text too, so rollback snapshots reuse the read the
+ *     rewrite already did instead of a second full-KB pass).
+ *
+ * Tokens here are the ENTRY-GRAMMAR canonical tokens: a bare name (group
+ * first, then role) or an explicit `role/<name>`. Callers translate: a ROLE's
+ * references are its bare token plus its `role/` token; a GROUP's are its
+ * bare token only.
+ */
+import type { IWorkspaceService } from '@bevel-software/platform-shared';
+/**
+ * Every genuine role/group reference in `text`'s rule regions, as
+ * {role, verb} where `role` is the canonical ENTRY TOKEN (bare name or
+ * `role/<name>`). `isAccessMd` marks an `access.md` file, whose BODY is a
+ * rule source in the body-governed format — see {@link ruleLineRanges}.
+ */
+export declare function findRoleRefsInText(text: string, isMarkdown?: boolean, isAccessMd?: boolean): {
+    role: string;
+    verb: string;
+}[];
+/**
+ * Rewrite every RULE-REGION line that PARSES as a role reference whose
+ * canonical token == `oldToken`, replacing the token with `newDisplayName`
+ * (preserving any leading `deny ` and indentation). A prose body is never
+ * touched — a line like `- Sales` in a node file or a legacy `access.md`
+ * stays byte-for-byte intact; the body is eligible ONLY when the file is a
+ * body-governed `access.md` (`isAccessMd` + the body parses as rules), where
+ * the body IS what the resolver enforces — see {@link ruleLineRanges}. 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, oldToken: string, newDisplayName: string, isMarkdown?: boolean, isAccessMd?: boolean): string;
+export interface ReferenceHit {
+    path: string;
+    verb: string;
+}
+/** One rewritten file: the new content plus the ORIGINAL text the rewrite
+ *  read (rollback snapshots reuse it — no second full-KB read). */
+export interface ReferenceRewrite {
+    repoRelativePath: string;
+    content: string;
+    original: string;
+}
+/**
+ * The slice of the workflow event bus the scanner taps for cache
+ * invalidation. Structural (not the concrete class) so test doubles and the
+ * services' optional bus stay compatible.
+ */
+export interface ReferenceScanInvalidationBus {
+    /** Optional so record-only test doubles (emit-only stubs) stay valid. */
+    onEmit?(listener: (event: {
+        kind: string;
+        workspaceId?: string;
+        path?: string;
+    }) => void): () => void;
+}
+/**
+ * Candidate collection + cached scan + fail-closed rewrite over one KB.
+ * Constructed per admin service; the cache means roster MUTATIONS never rerun
+ * the full-KB reference sweep (only the roster GET pays it, at most once per
+ * TTL), and `invalidate` drops it whenever a write could have moved
+ * references (rename/delete rewrites, or any external change signal).
+ *
+ * FRESHNESS: an `access.md` grant/revoke (or any other write to a scanned
+ * file) lands OUTSIDE the admin services, so their explicit invalidations
+ * can't see it — the roster's `referencedBy` would serve up to `SCAN_TTL_MS`
+ * of staleness. When an `eventBus` is provided, the scanner taps its emits
+ * and drops the workspace's cache on every path-carrying event
+ * (`file-changed` from the commit pipeline, and `lock-released` — which the
+ * share routes emit synchronously at write time, before the async commit's
+ * `file-changed` lands) whose path has a scanned extension. The TTL stays as
+ * the backstop for deployments/tests without a bus.
+ */
+export declare class KbReferenceScanner {
+    private readonly workspaceService;
+    private readonly kbDirName;
+    private readonly cache;
+    /**
+     * Per-workspace in-flight scan state: a scan may only CACHE its result if
+     * no invalidation landed after it started — otherwise the pre-change
+     * snapshot would repopulate the cache and stick for a whole TTL. Tracked
+     * ONLY while scans run (a future scan reads post-write state by nature, so
+     * an invalidation with nothing in flight needs only the cache drop): the
+     * entry is created by the first concurrent scan and removed by the last,
+     * so the map never accumulates workspaces.
+     */
+    private readonly inFlight;
+    constructor(workspaceService: IWorkspaceService, kbDirName: string, eventBus?: ReferenceScanInvalidationBus);
+    invalidate(workspaceId: string): void;
+    /**
+     * Repo-relative paths of every file that could carry a principal reference:
+     * all `access.md` files plus every node file whose own frontmatter the
+     * resolver reads access verbs from — the shared
+     * `ACCESS_FRONTMATTER_EXTENSIONS` set (`.md` AND `.tool`; a rename that
+     * skipped `.tool` would strand a live frontmatter grant there). Sourced
+     * from the workspace file tree (which already skips `.git` and honours
+     * `.bevelignore`), filtered under the KB dir and returned bare
+     * repo-relative. (`roles.yaml` matches no scanned extension, so it's
+     * excluded; callers commit it separately.) Under save=share the working
+     * tree matches the committed set, so this is the same candidate list
+     * git-tracking would give.
+     */
+    collectCandidateFiles(workspaceId: string): Promise<string[]>;
+    /**
+     * Sound scan of EVERY candidate file (folder `access.md` + `.md`/`.tool`
+     * node frontmatter) for genuine principal references, indexed by canonical
+     * entry TOKEN. Shares the
+     * candidate set and the config-region parse with the rename rewrite, so the
+     * delete warning and the rewrite see the SAME references. A file we cannot
+     * read is skipped (this is an advisory read, not the atomic write path).
+     * Cached per workspace (see class doc); reads are batched with Promise.all
+     * rather than serial per-file awaits.
+     */
+    scan(workspaceId: string): Promise<Map<string, ReferenceHit[]>>;
+    /**
+     * Find every genuine reference to `oldToken` and rewrite it to
+     * `newDisplayName`. FAIL-CLOSED: a candidate we cannot read might reference
+     * the old token, and skipping it would commit a partial rewrite (a
+     * half-renamed principal still pointed at by stragglers = silent access
+     * drop) — so any read failure aborts via `makeError` with nothing written.
+     * Returns the writes WITH each file's original text (rollback snapshots).
+     */
+    rewriteReferences(workspaceId: string, oldToken: string, newDisplayName: string, makeError: (message: string, cause?: string) => Error): Promise<ReferenceRewrite[]>;
+    private repoDir;
+}
+//# sourceMappingURL=reference-scan.d.ts.map

package/dist/modules/access/reference-scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-scan.d.ts","sourceRoot":"","sources":["../../../src/modules/access/reference-scan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,OAAO,KAAK,EAAiB,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAoNxF;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,UAAU,UAAO,EACjB,UAAU,UAAQ,GACjB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,CAQlC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,EACtB,UAAU,UAAO,EACjB,UAAU,UAAQ,GACjB,MAAM,CAcR;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED;mEACmE;AACnE,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAOD;;;;GAIG;AACH,MAAM,WAAW,4BAA4B;IAC3C,yEAAyE;IACzE,MAAM,CAAC,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACvG;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,kBAAkB;IAiB3B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS;IAjB5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAGlB;IACJ;;;;;;;;OAQG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqD;gBAG3D,gBAAgB,EAAE,iBAAiB,EACnC,SAAS,EAAE,MAAM,EAClC,QAAQ,CAAC,EAAE,4BAA4B;IAczC,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAMrC;;;;;;;;;;;;OAYG;IACG,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAiBnE;;;;;;;;;OASG;IACG,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC;IA8CrE;;;;;;;OAOG;IACG,iBAAiB,CACrB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,KAAK,GACpD,OAAO,CAAC,gBAAgB,EAAE,CAAC;YAgChB,OAAO;CAItB"}