@bevel-software/platform-core-backend 0.1.0

package/dist/modules/access/access-mutation.service.js

@@ -0,0 +1,307 @@
+/**
+ * AccessMutationService — the WRITE side of access control.
+ *
+ * `AccessControlService` resolves permissions (read-only); this service mutates
+ * them. It grants / revokes / re-verbs a principal on a KB path by surgically
+ * splicing the relevant `access.md` (folder target) or the node's own
+ * frontmatter (file target), then re-resolves the effective access so the
+ * caller can return an authoritative, fresh view.
+ *
+ * Invariants this service owns (the route wires the lock + commit around it):
+ *   - SURGICAL SPLICE, never parse→emit: comments + markdown bodies survive
+ *     (see access-splice.ts).
+ *   - INJECTION-SAFE: every principal is validated before it touches a file.
+ *   - INDEPENDENT VERBS: a grant adds the principal under exactly the verb asked
+ *     for and touches no other verb. Verbs are NOT a strict hierarchy — `read`,
+ *     `write`, `owner`, and `download` are independent lists, and a principal may
+ *     legitimately appear under several at once (e.g. `read` + `download`, or
+ *     `owner` + `download`). (The RESOLVER happens to let an `owner`/`write`
+ *     grant imply lower read access, but that's a read-side convenience, not a
+ *     rule the write side enforces by collapsing entries.) This keeps the model
+ *     open to future verbs that don't nest.
+ *   - FILE vs FOLDER: a file target edits the node's OWN frontmatter (no sibling
+ *     leak); a folder target edits the folder's `access.md`.
+ *   - UNCONDITIONAL REVOKE: a revoke always removes what it's asked to — there is
+ *     no last-owner guard and no self-lockout guard. `owner` names who validates a
+ *     file/folder, not a stronger privilege tier, so removing the last owner
+ *     creates no lockout; and a user may drop their own access (including write),
+ *     since admins keep rescue access regardless.
+ *
+ * Paths in/out of this service are REPO-RELATIVE (e.g. `Knowledge/Sales`,
+ * `Knowledge/Sales/Deal.md`). The route strips the `<kbDirName>/` prefix once at
+ * entry; everything here speaks repo-relative, matching `IAccessControl`.
+ */
+import path from 'node:path';
+import { KNOWN_VERBS } from './access-control.service.js';
+import { spliceRevoke, spliceGrant, validatePrincipal, AccessSpliceError, } from './access-splice.js';
+import { WorkflowDomainError } from '../workflow/workflow.errors.js';
+/** Bad-request-class mutation failure (invalid principal, unknown group, lockout). */
+export class AccessMutationError extends WorkflowDomainError {
+    constructor(message, status = 400, payload) {
+        super(message, status, payload);
+        this.name = 'AccessMutationError';
+    }
+}
+/**
+ * The `access.md` path that governs a folder. For the repo root (`''`) this is
+ * `access.md`; otherwise `<dir>/access.md`.
+ */
+export function accessMdPathForFolder(repoRelDir) {
+    return repoRelDir ? `${repoRelDir}/access.md` : 'access.md';
+}
+/**
+ * The file whose frontmatter governs a node — the node file itself. (A file
+ * target edits its OWN frontmatter, not the folder's access.md, so a per-file
+ * grant never leaks to siblings.)
+ */
+export function targetFileForNode(repoRelFile) {
+    return repoRelFile;
+}
+export class AccessMutationService {
+    workspaceService;
+    accessControl;
+    kbDirName;
+    constructor(workspaceService, accessControl, kbDirName) {
+        this.workspaceService = workspaceService;
+        this.accessControl = accessControl;
+        this.kbDirName = kbDirName;
+    }
+    /**
+     * Resolve the file we'll actually edit for a (kind, target) pair, repo-relative.
+     *   - folder → the folder's `access.md` (block-list form)
+     *   - file   → the node file itself (its own frontmatter, scalar form allowed)
+     */
+    fileToEdit(kind, repoRelTarget) {
+        if (kind === 'folder') {
+            return { editPath: accessMdPathForFolder(repoRelTarget), allowScalar: false };
+        }
+        return { editPath: targetFileForNode(repoRelTarget), allowScalar: true };
+    }
+    /**
+     * Read the to-be-edited file's current text, or '' when it's an expected
+     * missing file. `allowMissing` is true only where an absent file is normal
+     * (a folder that has no `access.md` yet); there we swallow ENOENT/ENOTDIR.
+     * Every other error — a typoed node target, a transient read failure — is
+     * rethrown so we never treat it as empty and write a brand-new access file.
+     */
+    async readOrEmpty(workspaceId, repoRelEditPath, allowMissing) {
+        const wsRelative = this.toWorkspaceRelative(repoRelEditPath);
+        try {
+            return await this.workspaceService.readFile(workspaceId, wsRelative);
+        }
+        catch (err) {
+            const code = err?.code;
+            if (allowMissing && (code === 'ENOENT' || code === 'ENOTDIR')) {
+                return '';
+            }
+            throw err;
+        }
+    }
+    toWorkspaceRelative(repoRelative) {
+        return path.posix.join(this.kbDirName, repoRelative);
+    }
+    /**
+     * Grant `principal` `verb` on `target`. Adds the principal under exactly this
+     * verb and touches no other verb — verbs are independent, so a principal may
+     * hold several at once (e.g. `read` + `download`). Idempotent: a no-op when the
+     * principal already holds the verb. Reads the current file FRESH (the caller
+     * holds the lock), splices, and writes back. Returns whether anything changed.
+     *
+     * Throws `AccessMutationError` for an invalid/unknown principal. The caller is
+     * responsible for the permission gate and the lock; this method only mutates
+     * file content.
+     */
+    async grant(workspaceId, kind, repoRelTarget, verb, principal) {
+        this.assertPrincipalSafe(principal); // injection/shape guard (role-exists is the route's job)
+        const { editPath, allowScalar } = this.fileToEdit(kind, repoRelTarget);
+        const current = await this.readOrEmpty(workspaceId, editPath, kind === 'folder');
+        let result;
+        try {
+            result = spliceGrant(current, verb, principal, { allowScalar });
+        }
+        catch (err) {
+            throw this.toMutationError(err);
+        }
+        if (result.changed) {
+            await this.workspaceService.writeFile(workspaceId, this.toWorkspaceRelative(editPath), result.text);
+            // Drop the resolver cache so any same-request re-resolve reads the new
+            // bytes (mirrors revoke()'s post-write invalidation).
+            this.accessControl.invalidate(workspaceId);
+        }
+        return { changed: result.changed, editPath };
+    }
+    /**
+     * Revoke `principal` from `target`. Removes them from ALL verbs on the edited
+     * file (a revoke is "no longer has access here", not "drop one verb"), or just
+     * the one `verb` when given. A revoke is UNCONDITIONAL — there is deliberately
+     * no last-owner guard and no self-lockout guard. `owner` is not a privilege
+     * tier (it names who validates a file/folder, not a stronger grant), so
+     * removing the last owner creates no lockout to protect against; and a user
+     * dropping their own access — including their own write — is a legitimate
+     * choice (admins keep rescue access regardless). The caller holds the lock and
+     * supplies the acting user (used for attribution / future per-principal checks).
+     */
+    async revoke(workspaceId, kind, repoRelTarget, principal, 
+    // Kept on the signature: the route supplies it and the upcoming
+    // revoke-vs-deny slice needs the acting user. Not consumed yet.
+    _actingUserEmail, 
+    // When present, strip ONLY this verb (a per-checkbox toggle in the share UI);
+    // absent strips the principal from every verb (the whole-principal Remove).
+    verb) {
+        void _actingUserEmail; // referenced to satisfy no-unused-vars until Slice 2 consumes it
+        this.assertPrincipalSafe(principal); // same injection/shape guard grant runs
+        const { editPath } = this.fileToEdit(kind, repoRelTarget);
+        // Allow a missing target only for a folder (no access.md yet is normal); a
+        // missing FILE node is a bad target and should surface, not silently no-op
+        // — same rule grant() uses.
+        const original = await this.readOrEmpty(workspaceId, editPath, kind === 'folder');
+        let next = original;
+        let changed = false;
+        try {
+            const verbsToRevoke = verb ? [verb] : KNOWN_VERBS;
+            for (const v of verbsToRevoke) {
+                const r = spliceRevoke(next, v, principal);
+                next = r.text;
+                changed = changed || r.changed;
+            }
+        }
+        catch (err) {
+            throw this.toMutationError(err);
+        }
+        if (!changed)
+            return { changed: false, editPath };
+        const wsRelative = this.toWorkspaceRelative(editPath);
+        await this.workspaceService.writeFile(workspaceId, wsRelative, next);
+        this.accessControl.invalidate(workspaceId);
+        return { changed: true, editPath };
+    }
+    /**
+     * Restrict access to JUST this target by adding a `deny <principal>` at the
+     * target — the per-item override for a principal whose access is inherited
+     * from a parent (Drive's "limited-access folder" analog). Closeness-first
+     * resolution makes the closer `deny` shadow the farther grant for the
+     * target's subtree, without touching any ancestor.
+     *
+     * Two subtleties this method owns (eng review D5 / D9):
+     *   1. STRIP-THEN-DENY: the resolver lets a grant in a scope override a deny
+     *      of the same principal in that SAME scope (`buildScope`'s "a grant
+     *      sticks"). So if the target already names the principal under a verb as
+     *      a grant, writing a bare `deny` next to it would be silently discarded.
+     *      We first revoke any same-scope grant for the principal, THEN add the
+     *      deny — so the deny actually takes effect.
+     *   2. POST-RESOLVE ASSERT: after writing, we re-resolve and confirm the
+     *      principal genuinely lost effective access on the target. If they
+     *      didn't (e.g. the deny had no effect for a reason we didn't model), we
+     *      roll the file back and error rather than report a no-op success — the
+     *      "never a silent no-op" invariant this whole slice exists to uphold.
+     *
+     * Folder target → the folder's `access.md`; file target → its own frontmatter.
+     * The caller holds the lock and has already authorized write on the target.
+     *
+     * `verb` scopes the restriction: when given, ONLY that verb is denied here
+     * (the per-checkbox "restrict just this verb on this item" — e.g. unchecking
+     * an inherited `write` while keeping a direct `download`); when absent, the
+     * whole principal is denied across every verb (the whole-row "block this
+     * person from this item"). The strip-then-deny and the effectiveness assert
+     * apply to whichever verbs were targeted.
+     */
+    async denyHere(workspaceId, kind, repoRelTarget, principal, verb) {
+        this.assertPrincipalSafe(principal);
+        const { editPath, allowScalar } = this.fileToEdit(kind, repoRelTarget);
+        const original = await this.readOrEmpty(workspaceId, editPath, kind === 'folder');
+        const verbsToDeny = verb ? [verb] : KNOWN_VERBS;
+        let next = original;
+        try {
+            for (const v of verbsToDeny) {
+                // (1) Strip any same-scope GRANT for this principal so grant-beats-deny
+                // can't silently swallow the deny we're about to add.
+                next = spliceRevoke(next, v, principal).text;
+                // (2) Add the deny under the same verb.
+                next = spliceGrant(next, v, principal, { allowScalar, deny: true }).text;
+            }
+        }
+        catch (err) {
+            throw this.toMutationError(err);
+        }
+        if (next === original) {
+            // The principal was already denied here (for the targeted verb[s]) — nothing to write.
+            return { changed: false, editPath };
+        }
+        const wsRelative = this.toWorkspaceRelative(editPath);
+        await this.workspaceService.writeFile(workspaceId, wsRelative, next);
+        this.accessControl.invalidate(workspaceId);
+        // (3) Assert the deny actually removed effective access on the targeted
+        // verb(s) — else roll back.
+        const stillHas = await this.principalStillHasAccess(workspaceId, kind, repoRelTarget, principal, verb);
+        if (stillHas) {
+            await this.workspaceService.writeFile(workspaceId, wsRelative, original);
+            this.accessControl.invalidate(workspaceId);
+            throw new AccessMutationError('The restriction had no effect — this person still has access here. Remove the grant at its source instead.', 409, { kind: 'deny-ineffective' });
+        }
+        return { changed: true, editPath };
+    }
+    /**
+     * True iff `principal` still effectively holds the targeted access on the
+     * target after a mutation — `verb` scopes it to that one verb, else it checks
+     * ANY verb. This is the deny-effectiveness check, so it must reflect REAL
+     * access — not just "is there a removable file entry."
+     *
+     * For a USER, that distinction matters: effective access includes admin-rescue
+     * on `access.md`/`roles.yaml`, group membership, and the built-in `everyone` —
+     * none of which `grantSources` reports (it is MECE over file-backed
+     * direct/ancestor entries only). So we ask the same `canRead/canWrite/
+     * canDownload/canOwner` resolver every real access decision uses; if the
+     * targeted verb is still true, the deny didn't take and `denyHere` rolls back.
+     * (This is why the admin-rescue case rolls back: the admin still `canWrite` the
+     * access.md even with no file entry. It also correctly catches a verb-scoped
+     * `deny write` that can't bite because the principal is an `owner` — `canWrite`
+     * stays true via the owner implication.)
+     *
+     * For a ROLE principal there is no per-role "can log in" check, but a role only
+     * ever holds access by being NAMED in a file (no rescue / role-via-role /
+     * everyone indirection applies to a role token), so `grantSources` IS its
+     * complete effective-access answer (scoped to `verb` when given).
+     */
+    async principalStillHasAccess(workspaceId, kind, repoRelTarget, principal, verb) {
+        if (principal.kind === 'user') {
+            const email = principal.email;
+            const canOf = {
+                read: () => this.accessControl.canRead(workspaceId, email, repoRelTarget),
+                write: () => this.accessControl.canWrite(workspaceId, email, repoRelTarget),
+                download: () => this.accessControl.canDownload(workspaceId, email, repoRelTarget),
+                owner: () => this.accessControl.canOwner(workspaceId, email, repoRelTarget),
+            };
+            const verbs = verb ? [verb] : KNOWN_VERBS;
+            const results = await Promise.all(verbs.map((v) => canOf[v]()));
+            return results.some(Boolean);
+        }
+        const sources = await this.accessControl.grantSources(workspaceId, kind, repoRelTarget, {
+            kind: 'role',
+            role: principal.role,
+        });
+        return verb ? sources[verb] !== undefined : Object.keys(sources).length > 0;
+    }
+    /**
+     * Sync placeholder for "is this a real principal" — role validity is checked
+     * asynchronously in the route (it needs the roles model). Here we only run the
+     * cheap injection/shape validation so a malformed principal never reaches the
+     * splice. Role-exists-in-roles.yaml is the route's job (so it can offer
+     * "Create Group" for an unknown group, an admin-only flow).
+     */
+    assertPrincipalSafe(principal) {
+        try {
+            validatePrincipal(principal);
+        }
+        catch (err) {
+            throw this.toMutationError(err);
+        }
+    }
+    toMutationError(err) {
+        if (err instanceof AccessMutationError)
+            return err;
+        if (err instanceof AccessSpliceError)
+            return new AccessMutationError(err.message, 400);
+        return new AccessMutationError(err instanceof Error ? err.message : 'mutation failed', 500);
+    }
+}
+//# sourceMappingURL=access-mutation.service.js.map

package/dist/modules/access/access-mutation.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-mutation.service.js","sourceRoot":"","sources":["../../../src/modules/access/access-mutation.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAI7B,OAAO,EAAa,WAAW,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EACL,YAAY,EACZ,WAAW,EACX,iBAAiB,EACjB,iBAAiB,GAElB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAKrE,sFAAsF;AACtF,MAAM,OAAO,mBAAoB,SAAQ,mBAAmB;IAC1D,YAAY,OAAe,EAAE,MAAM,GAAG,GAAG,EAAE,OAAiC;QAC1E,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,UAAkB;IACtD,OAAO,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,YAAY,CAAC,CAAC,CAAC,WAAW,CAAC;AAC9D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,WAAmB;IACnD,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,MAAM,OAAO,qBAAqB;IAEb;IACA;IACA;IAHnB,YACmB,gBAAkC,EAClC,aAA6B,EAC7B,SAAiB;QAFjB,qBAAgB,GAAhB,gBAAgB,CAAkB;QAClC,kBAAa,GAAb,aAAa,CAAgB;QAC7B,cAAS,GAAT,SAAS,CAAQ;IACjC,CAAC;IAEJ;;;;OAIG;IACH,UAAU,CAAC,IAAgB,EAAE,aAAqB;QAChD,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACtB,OAAO,EAAE,QAAQ,EAAE,qBAAqB,CAAC,aAAa,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;QAChF,CAAC;QACD,OAAO,EAAE,QAAQ,EAAE,iBAAiB,CAAC,aAAa,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;IAC3E,CAAC;IAED;;;;;;OAMG;IACK,KAAK,CAAC,WAAW,CACvB,WAAmB,EACnB,eAAuB,EACvB,YAAqB;QAErB,MAAM,UAAU,GAAG,IAAI,CAAC,mBAAmB,CAAC,eAAe,CAAC,CAAC;QAC7D,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;QACvE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,GAAI,GAAoC,EAAE,IAAI,CAAC;YACzD,IAAI,YAAY,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,SAAS,CAAC,EAAE,CAAC;gBAC9D,OAAO,EAAE,CAAC;YACZ,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAEO,mBAAmB,CAAC,YAAoB;QAC9C,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;IACvD,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,KAAK,CACT,WAAmB,EACnB,IAAgB,EAChB,aAAqB,EACrB,IAAU,EACV,SAAoB;QAEpB,IAAI,CAAC,mBAAmB,CAAC,SAAS,CAAC,CAAC,CAAC,yDAAyD;QAC9F,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;QACvE,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,WAAW,EAAE,QAAQ,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC;QACjF,IAAI,MAAM,CAAC;QACX,IAAI,CAAC;YACH,MAAM,GAAG,WAAW,CAAC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC;QAClE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;QAClC,CAAC;QACD,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,MAAM,IAAI,CAAC,gBAAgB,CAAC,SAAS,CACnC,WAAW,EACX,IAAI,CAAC,mBAAmB,CAAC,QAAQ,CAAC,EAClC,MAAM,CAAC,IAAI,CACZ,CAAC;YACF,uEAAuE;YACvE,sDAAsD;YACtD,IAAI,CAAC,aAAa,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;QAC7C,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,QAAQ,EAAE,CAAC;IAC/C,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,MAAM,CACV,WAAmB,EACnB,IAAgB,EAChB,aAAqB,EACrB,SAAoB;IACpB,gEAAgE;IAChE,gEAAgE;IAChE,gBAAwB;IACxB,8EAA8E;IAC9E,4EAA4E;IAC5E,IAAW;QAEX,KAAK,gBAAgB,CAAC,CAAC,iEAAiE;QACxF,IAAI,CAAC,mBAAmB,CAAC,SAAS,CAAC,CAAC,CAAC,wCAAwC;QAC7E,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;QAC1D,2EAA2E;QAC3E,2EAA2E;QAC3E,4BAA4B;QAC5B,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,WAAW,EAAE,QAAQ,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC;QAClF,IAAI,IAAI,GAAG,QAAQ,CAAC;QACpB,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,aAAa,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC;YAClD,KAAK,MAAM,CAAC,IAAI,aAAa,EAAE,CAAC;gBAC9B,MAAM,CAAC,GAAG,YAAY,CAAC,IAAI,EAAE,CAAC,EAAE,SAAS,CAAC,CAAC;gBAC3C,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC;gBACd,OAAO,GAAG,OAAO,IAAI,CAAC,CAAC,OAAO,CAAC;YACjC,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;QAClC,CAAC;QACD,IAAI,CAAC,OAAO;YAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;QAElD,MAAM,UAAU,GAAG,IAAI,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;QACtD,MAAM,IAAI,CAAC,gBAAgB,CAAC,SAAS,CAAC,WAAW,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC;QACrE,IAAI,CAAC,aAAa,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;QAE3C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IACrC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,KAAK,CAAC,QAAQ,CACZ,WAAmB,EACnB,IAAgB,EAChB,aAAqB,EACrB,SAAoB,EACpB,IAAW;QAEX,IAAI,CAAC,mBAAmB,CAAC,SAAS,CAAC,CAAC;QACpC,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;QACvE,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,WAAW,EAAE,QAAQ,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC;QAElF,MAAM,WAAW,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC;QAChD,IAAI,IAAI,GAAG,QAAQ,CAAC;QACpB,IAAI,CAAC;YACH,KAAK,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC;gBAC5B,wEAAwE;gBACxE,sDAAsD;gBACtD,IAAI,GAAG,YAAY,CAAC,IAAI,EAAE,CAAC,EAAE,SAAS,CAAC,CAAC,IAAI,CAAC;gBAC7C,wCAAwC;gBACxC,IAAI,GAAG,WAAW,CAAC,IAAI,EAAE,CAAC,EAAE,SAAS,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC;YAC3E,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;QAClC,CAAC;QAED,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACtB,uFAAuF;YACvF,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;QACtC,CAAC;QAED,MAAM,UAAU,GAAG,IAAI,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;QACtD,MAAM,IAAI,CAAC,gBAAgB,CAAC,SAAS,CAAC,WAAW,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC;QACrE,IAAI,CAAC,aAAa,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;QAE3C,wEAAwE;QACxE,4BAA4B;QAC5B,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,uBAAuB,CACjD,WAAW,EACX,IAAI,EACJ,aAAa,EACb,SAAS,EACT,IAAI,CACL,CAAC;QACF,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,IAAI,CAAC,gBAAgB,CAAC,SAAS,CAAC,WAAW,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC;YACzE,IAAI,CAAC,aAAa,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;YAC3C,MAAM,IAAI,mBAAmB,CAC3B,4GAA4G,EAC5G,GAAG,EACH,EAAE,IAAI,EAAE,kBAAkB,EAAE,CAC7B,CAAC;QACJ,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IACrC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACK,KAAK,CAAC,uBAAuB,CACnC,WAAmB,EACnB,IAAgB,EAChB,aAAqB,EACrB,SAAoB,EACpB,IAAW;QAEX,IAAI,SAAS,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAC9B,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC;YAC9B,MAAM,KAAK,GAAyC;gBAClD,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,WAAW,EAAE,KAAK,EAAE,aAAa,CAAC;gBACzE,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,WAAW,EAAE,KAAK,EAAE,aAAa,CAAC;gBAC3E,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,WAAW,CAAC,WAAW,EAAE,KAAK,EAAE,aAAa,CAAC;gBACjF,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,WAAW,EAAE,KAAK,EAAE,aAAa,CAAC;aAC5E,CAAC;YACF,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC;YAC1C,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YAChE,OAAO,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC/B,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,YAAY,CAAC,WAAW,EAAE,IAAI,EAAE,aAAa,EAAE;YACtF,IAAI,EAAE,MAAM;YACZ,IAAI,EAAE,SAAS,CAAC,IAAI;SACrB,CAAC,CAAC;QACH,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;IAC9E,CAAC;IAED;;;;;;OAMG;IACK,mBAAmB,CAAC,SAAoB;QAC9C,IAAI,CAAC;YACH,iBAAiB,CAAC,SAAS,CAAC,CAAC;QAC/B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAEO,eAAe,CAAC,GAAY;QAClC,IAAI,GAAG,YAAY,mBAAmB;YAAE,OAAO,GAAG,CAAC;QACnD,IAAI,GAAG,YAAY,iBAAiB;YAAE,OAAO,IAAI,mBAAmB,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QACvF,OAAO,IAAI,mBAAmB,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC;IAC9F,CAAC;CACF"}

package/dist/modules/access/access-splice.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Surgical text-splice editor for `access.md` frontmatter and node-frontmatter
+ * access verbs.
+ *
+ * WHY a splice and not parse→model→emit: the resolver's parser
+ * (`parseYamlSubset` / `extractFrontmatter` / `stripComment`) deliberately
+ * throws away comments, blank lines, key order, AND the markdown body below the
+ * closing `---`. Re-serialising from the parsed model would silently DELETE the
+ * prose bodies the real `access.md` files carry (the repo-root one is a whole
+ * README) — and a `parse(emit(x))` round-trip test would PASS anyway because
+ * parse ignores the body. So every mutation here edits the RAW text: we locate
+ * the verb's block, splice exactly one list line in or out, and leave every
+ * other byte — comments, ordering, blank lines, the body — untouched.
+ *
+ *   ---
+ *   write:                 (verb key line, indent 0)
+ *     - Admin              (list item, indent 2)  <- splice point
+ *     - Felix <f@x.eu>     (list item)
+ *   # a comment            (preserved verbatim)
+ *   owner: []              (inline-empty list)
+ *   ---
+ *   # Body prose           (preserved verbatim)
+ *
+ * The same engine serves node-frontmatter, which additionally accepts a scalar
+ * form (`owner: Felix <f@x.eu>`). Adding a second principal to a scalar verb
+ * normalises it to the block-list form.
+ */
+import { type Verb } from './access-control.service.js';
+/** A principal to grant/revoke, in the resolver's canonical terms. */
+export type Principal = {
+    kind: 'user';
+    email: string;
+    displayName: string;
+} | {
+    kind: 'role';
+    role: string;
+};
+/** Result of a splice — the new full file text and whether anything changed. */
+export interface SpliceResult {
+    text: string;
+    changed: boolean;
+}
+/** Thrown when the input can't be spliced safely (malformed frontmatter, etc.). */
+export declare class AccessSpliceError extends Error {
+    constructor(message: string);
+}
+/**
+ * Render a principal as the canonical access-entry line value the parser reads
+ * back (`Name <email>` or a bare role display name). The caller is responsible
+ * for having validated the principal first (see `validatePrincipal`).
+ *
+ * `deny` prefixes the entry with `deny ` so the resolver reads it as a denial
+ * (the `deny-here` per-item override) — same line shape, opposite verdict.
+ */
+export declare function renderEntry(p: Principal, deny?: boolean): string;
+/**
+ * Validate a principal before it is spliced into a file. Rejects anything that
+ * could break frontmatter or smuggle in extra YAML — newlines, control chars,
+ * and emails / names that don't match the resolver's own regexes. This is the
+ * injection guard: a principal that survives this is safe to render verbatim
+ * into a `  - ` list line.
+ *
+ * Returns the canonical principal (lowercased email / canonical role) on
+ * success, or throws `AccessSpliceError`.
+ */
+export declare function validatePrincipal(p: Principal): Principal;
+/**
+ * Add `principal` under `verb`. Idempotent: if an equivalent entry already
+ * exists with the SAME deny-ness (a grant when granting, a deny when denying),
+ * returns `changed: false`. Creates the verb key (and the frontmatter fence,
+ * for a fresh file) as needed. Preserves everything else byte-for-byte.
+ *
+ * `allowScalar` controls whether a fresh single-entry verb may be written in
+ * the node-frontmatter scalar form (`owner: Name <email>`). access.md always
+ * uses the block-list form; node frontmatter prefers scalar for a lone entry.
+ *
+ * `deny` writes the entry as a `deny <principal>` denial instead of a grant
+ * (the `deny-here` per-item override). The block/scalar/empty-list handling is
+ * identical — only the rendered line and the idempotency check differ — so the
+ * deny path reuses this engine rather than a parallel `spliceDeny`. NOTE: the
+ * resolver lets a same-scope grant override a same-scope deny of the same
+ * principal, so a caller adding a deny where a grant already exists must strip
+ * that grant first (see `AccessMutationService`); this function only writes the
+ * one entry it's asked to.
+ */
+export declare function spliceGrant(text: string, verb: Verb, rawPrincipal: Principal, opts?: {
+    allowScalar?: boolean;
+    deny?: boolean;
+}): SpliceResult;
+/**
+ * Remove every entry naming `principal` under `verb` (grant or deny). Idempotent:
+ * returns `changed: false` when the principal isn't present. If removing the
+ * last item empties the verb, the `verb:` key is collapsed to `verb: []` so the
+ * file still parses cleanly (the resolver reads `[]` as an empty list).
+ * Preserves everything else.
+ */
+export declare function spliceRevoke(text: string, verb: Verb, rawPrincipal: Principal): SpliceResult;
+//# sourceMappingURL=access-splice.d.ts.map

package/dist/modules/access/access-splice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-splice.d.ts","sourceRoot":"","sources":["../../../src/modules/access/access-splice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EACL,KAAK,IAAI,EAKV,MAAM,6BAA6B,CAAC;AAErC,sEAAsE;AACtE,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnC,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,mFAAmF;AACnF,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAMD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,UAAQ,GAAG,MAAM,CAG9D;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,SAAS,GAAG,SAAS,CAgDzD;AAgKD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,IAAI,EACV,YAAY,EAAE,SAAS,EACvB,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,GACnD,YAAY,CAwDd;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,YAAY,EAAE,SAAS,GAAG,YAAY,CAgC5F"}