@bevel-software/platform-core-backend 0.11.1 → 0.11.2

package/dist/modules/access-model/creator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"creator.d.ts","sourceRoot":"","sources":["../../../src/modules/access-model/creator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAA;CAAE,GACjF;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAA;CAAE,CAAC;AAEhE,mDAAmD;AACnD,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,aAAa,CACX,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,GAAG,KAAK,GACnB,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IAErC,oBAAoB,CAClB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAE1B,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAClD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,CAE5D"}

package/dist/modules/access-model/creator.js

@@ -0,0 +1,30 @@
+/**
+ * The pure half of the creator read-grant story: the creator identity, the
+ * grant-plan contract the creation surfaces consume, and the splice-safe
+ * principal for a creator. The service that DECIDES when a creation needs a
+ * grant (filesystem stats, access checks) is `modules/access/creator-access.ts`;
+ * this file carries only the types and pure helpers so downstream modules
+ * (kb-fs, plugins, tool-helpers) never need an edge into the access module.
+ */
+/**
+ * The splice-safe principal for a creator — exported because plugin
+ * provisioning (`PluginProvisionService`) writes the same `Name <email>`
+ * entries into the access.md files it seeds, and two spellings of the same
+ * person would read as two people.
+ */
+export function creatorPrincipal(creator) {
+    return { kind: 'user', email: creator.email, displayName: safeDisplayName(creator) };
+}
+/**
+ * `Name <email>`-safe display name: `validatePrincipal` rejects control
+ * chars, `<`, `>`, and `#`, so strip those from the user's name and fall
+ * back to the email local part (which the email regex already keeps free of
+ * `<>`/whitespace) when nothing usable remains.
+ */
+function safeDisplayName(creator) {
+    const strip = (s) => 
+    // eslint-disable-next-line no-control-regex -- same intentional control-char guard as access-splice
+    s.replace(/[<>#\u0000-\u001f\u007f]/g, ' ').replace(/\s+/g, ' ').trim();
+    return strip(creator.name) || strip(creator.email.split('@')[0] ?? '') || 'KB user';
+}
+//# sourceMappingURL=creator.js.map

package/dist/modules/access-model/creator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"creator.js","sourceRoot":"","sources":["../../../src/modules/access-model/creator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAkDH;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAgB;IAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,WAAW,EAAE,eAAe,CAAC,OAAO,CAAC,EAAE,CAAC;AACvF,CAAC;AAED;;;;;GAKG;AACH,SAAS,eAAe,CAAC,OAAgB;IACvC,MAAM,KAAK,GAAG,CAAC,CAAS,EAAE,EAAE;IAC1B,oGAAoG;IACpG,CAAC,CAAC,OAAO,CAAC,2BAA2B,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAC1E,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,SAAS,CAAC;AACtF,CAAC"}

package/dist/modules/access-model/group-files.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Group files — the "who you are" half of the roles/groups split.
+ *
+ * Groups are people-sets referenced by access grants ("GTM Team can read the
+ * battlecards"). A deployment has exactly ONE group source at a time — a mode
+ * derived from which file exists, so it holds at any git ref:
+ *
+ *   - `synced-groups.yaml` EXISTS  → IdP mode. The file is MACHINE-OWNED,
+ *     regenerated wholesale from the SCIM directory mirror; membership is
+ *     managed in the IdP. `groups.yaml` is ignored entirely.
+ *   - otherwise                    → manual mode. `groups.yaml` (UI-edited)
+ *     is the source.
+ *
+ * Both files share one format, the group twin of roles.yaml:
+ *
+ *   groups:
+ *     Engineering:
+ *       - ada@x.io
+ *       - bo@x.io
+ *     Empty Group: []
+ *
+ * Parsing is FORGIVING at the entry level by design — a malformed email or a
+ * reserved/duplicate name skips that entry with a warning, it never takes the
+ * whole file down. Only structural failures (unparsable YAML, `groups:` not a
+ * mapping) reject the file, and even then the RESOLVER degrades to "this file
+ * contributes nothing" rather than throwing: unlike roles.yaml there is no
+ * admin-lockout risk here, so groups must never be able to brick access
+ * resolution. Strict acceptance for WRITES is the job of the write-side
+ * validator (`validateGroupsFile` below), which treats warnings as refusals.
+ */
+export declare const GROUPS_YAML = "groups.yaml";
+export declare const SYNCED_GROUPS_YAML = "synced-groups.yaml";
+/**
+ * THE name-safety predicate for principal display names — the single source
+ * of truth every surface derives from (group creation/rename, IdP sync
+ * materialization; thin assert wrappers sit on top). Returns a human-readable
+ * reason the name is unsafe, or null when it is fine.
+ *
+ * The character rules keep the emitted YAML parseable and the entry grammar
+ * unambiguous:
+ *   `:`        mis-tokenises as a nested mapping key
+ *   `#`        truncated as a comment by the subset parser's stripComment
+ *   `<` / `>`  collide with the `Name <email>` user-reference shape
+ *   leading -  tokenises as a list item
+ *   \x00-\x1f  control chars / newlines break line structure outright
+ *   `role/…`   reserved: that spelling is the EXPLICIT role token in access
+ *              entries — a group carrying it could never be referenced.
+ */
+export declare function unsafeNameReason(displayName: string): string | null;
+/** One parsed group: display name + canonicalised member emails. */
+export interface GroupDefinition {
+    displayName: string;
+    emails: Set<string>;
+}
+/** Canonical group name → definition, in file order. */
+export type GroupsIndex = Map<string, GroupDefinition>;
+export interface ParsedGroupsFile {
+    ok: true;
+    groups: GroupsIndex;
+    /** Entry-level problems that were skipped over (bad email, dup name, …). */
+    warnings: string[];
+}
+export interface GroupsFileError {
+    ok: false;
+    errors: string[];
+}
+/**
+ * Parse a group file (either of the two — same grammar). See the module note
+ * for the forgiving-vs-structural split.
+ */
+export declare function parseGroupsFile(text: string, filename: string): ParsedGroupsFile | GroupsFileError;
+/**
+ * Write-gate twin of {@link parseGroupsFile}: strict — structural errors AND
+ * entry-level warnings both refuse the candidate, so a UI write can never land
+ * a group the resolver would silently skip.
+ */
+export declare function validateGroupsFile(text: string, filename: string): {
+    ok: true;
+} | {
+    ok: false;
+    errors: string[];
+};
+//# sourceMappingURL=group-files.d.ts.map

package/dist/modules/access-model/group-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-files.d.ts","sourceRoot":"","sources":["../../../src/modules/access-model/group-files.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,eAAO,MAAM,WAAW,gBAAgB,CAAC;AACzC,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AAEvD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAWnE;AAED,oEAAoE;AACpE,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACrB;AAED,wDAAwD;AACxD,MAAM,MAAM,WAAW,GAAG,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAEvD,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,IAAI,CAAC;IACT,MAAM,EAAE,WAAW,CAAC;IACpB,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf,gBAAgB,GAAG,eAAe,CAyFpC;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAWhD"}

package/dist/modules/access-model/group-files.js

@@ -0,0 +1,167 @@
+import { EMAIL_REGEX, GROUP_REF_PREFIX, RESERVED_ROLE_NAMES, ROLE_TOKEN_PREFIX, canonicalEmail, canonicalRoleName, parseYamlSubset, } from './access-grammar.js';
+/**
+ * Group files — the "who you are" half of the roles/groups split.
+ *
+ * Groups are people-sets referenced by access grants ("GTM Team can read the
+ * battlecards"). A deployment has exactly ONE group source at a time — a mode
+ * derived from which file exists, so it holds at any git ref:
+ *
+ *   - `synced-groups.yaml` EXISTS  → IdP mode. The file is MACHINE-OWNED,
+ *     regenerated wholesale from the SCIM directory mirror; membership is
+ *     managed in the IdP. `groups.yaml` is ignored entirely.
+ *   - otherwise                    → manual mode. `groups.yaml` (UI-edited)
+ *     is the source.
+ *
+ * Both files share one format, the group twin of roles.yaml:
+ *
+ *   groups:
+ *     Engineering:
+ *       - ada@x.io
+ *       - bo@x.io
+ *     Empty Group: []
+ *
+ * Parsing is FORGIVING at the entry level by design — a malformed email or a
+ * reserved/duplicate name skips that entry with a warning, it never takes the
+ * whole file down. Only structural failures (unparsable YAML, `groups:` not a
+ * mapping) reject the file, and even then the RESOLVER degrades to "this file
+ * contributes nothing" rather than throwing: unlike roles.yaml there is no
+ * admin-lockout risk here, so groups must never be able to brick access
+ * resolution. Strict acceptance for WRITES is the job of the write-side
+ * validator (`validateGroupsFile` below), which treats warnings as refusals.
+ */
+export const GROUPS_YAML = 'groups.yaml';
+export const SYNCED_GROUPS_YAML = 'synced-groups.yaml';
+/**
+ * THE name-safety predicate for principal display names — the single source
+ * of truth every surface derives from (group creation/rename, IdP sync
+ * materialization; thin assert wrappers sit on top). Returns a human-readable
+ * reason the name is unsafe, or null when it is fine.
+ *
+ * The character rules keep the emitted YAML parseable and the entry grammar
+ * unambiguous:
+ *   `:`        mis-tokenises as a nested mapping key
+ *   `#`        truncated as a comment by the subset parser's stripComment
+ *   `<` / `>`  collide with the `Name <email>` user-reference shape
+ *   leading -  tokenises as a list item
+ *   \x00-\x1f  control chars / newlines break line structure outright
+ *   `role/…`   reserved: that spelling is the EXPLICIT role token in access
+ *              entries — a group carrying it could never be referenced.
+ */
+export function unsafeNameReason(displayName) {
+    const trimmed = displayName.trim();
+    if (!trimmed)
+        return 'empty name';
+    if (/[:#<>]/.test(trimmed))
+        return "contains ':', '#', '<', or '>'";
+    // eslint-disable-next-line no-control-regex
+    if (/[\x00-\x1f]/.test(trimmed))
+        return 'contains control characters';
+    if (trimmed.startsWith('-'))
+        return "starts with '-'";
+    if (canonicalRoleName(trimmed).startsWith(ROLE_TOKEN_PREFIX)) {
+        return `starts with the reserved '${ROLE_TOKEN_PREFIX}' prefix (the explicit role token in access entries)`;
+    }
+    return null;
+}
+/**
+ * Parse a group file (either of the two — same grammar). See the module note
+ * for the forgiving-vs-structural split.
+ */
+export function parseGroupsFile(text, filename) {
+    // Tolerate empty keys at parse: this file's contract is ENTRY-level
+    // forgiveness (a blank group name is skipped with a warning below), and a
+    // hard tokenizer error here would retire every OTHER group fail-closed.
+    const parsed = parseYamlSubset(text, { tolerateEmptyKeys: true });
+    if (!parsed.ok)
+        return { ok: false, errors: [`${filename}: ${parsed.error}`] };
+    const root = parsed.value;
+    if (root == null || typeof root !== 'object' || Array.isArray(root)) {
+        return { ok: false, errors: [`${filename}: must be a top-level mapping`] };
+    }
+    const groupsNode = root.groups;
+    // An empty file (or one with no `groups:` key yet) is a valid empty set —
+    // a fresh deployment's groups.yaml starts this way.
+    if (groupsNode == null)
+        return { ok: true, groups: new Map(), warnings: [] };
+    if (typeof groupsNode !== 'object' || Array.isArray(groupsNode)) {
+        return { ok: false, errors: [`${filename}: 'groups' must be a mapping`] };
+    }
+    const groups = new Map();
+    const warnings = [];
+    for (const [displayName, value] of Object.entries(groupsNode)) {
+        const canonical = canonicalRoleName(displayName);
+        if (!canonical) {
+            warnings.push(`${filename}: empty group name — skipped`);
+            continue;
+        }
+        // THE shared name-safety predicate (see `unsafeNameReason` above) — the
+        // same rules every write surface asserts. The parser must apply it too:
+        // a name the writers refuse (control chars, `<`/`>`, a leading `-`, the
+        // reserved `role/` prefix) can still reach a group file by hand edit or
+        // through a skewed writer, and accepting it here would let the resolver
+        // honor — and `validateGroupsFile` pass — a name no editor can ever
+        // produce or reference safely.
+        const unsafe = unsafeNameReason(displayName);
+        if (unsafe) {
+            warnings.push(`${filename}: group ${JSON.stringify(displayName)} ${unsafe} — skipped`);
+            continue;
+        }
+        if (RESERVED_ROLE_NAMES.has(canonical)) {
+            warnings.push(`${filename}: group '${displayName}' uses reserved name '${canonical}' — skipped`);
+            continue;
+        }
+        if (groups.has(canonical)) {
+            warnings.push(`${filename}: group '${displayName}' canonicalises to '${canonical}', already declared as '${groups.get(canonical).displayName}' — skipped`);
+            continue;
+        }
+        if (value !== null && !Array.isArray(value)) {
+            warnings.push(`${filename}: group '${displayName}' must be a list of emails — skipped`);
+            continue;
+        }
+        const emails = new Set();
+        for (const raw of value ?? []) {
+            if (typeof raw !== 'string') {
+                warnings.push(`${filename}: group '${displayName}' has a non-string entry — entry skipped`);
+                continue;
+            }
+            const email = canonicalEmail(raw);
+            // The reserved `group:` prefix would PASS the email regex
+            // (`group:lee@x.io` shapes like an email) but it is the roles.yaml
+            // group-reference token, not an address — groups contain emails, never
+            // other groups. Skip it with its own warning so the write gate refuses
+            // it and the resolver never grants a colon-bearing "email".
+            if (email.startsWith(GROUP_REF_PREFIX)) {
+                warnings.push(`${filename}: group '${displayName}' has a '${GROUP_REF_PREFIX}'-prefixed entry ${JSON.stringify(raw)} — groups contain emails, not group references; entry skipped`);
+                continue;
+            }
+            if (!EMAIL_REGEX.test(email)) {
+                warnings.push(`${filename}: group '${displayName}' has malformed email '${raw}' — entry skipped`);
+                continue;
+            }
+            emails.add(email);
+        }
+        groups.set(canonical, { displayName: displayName.trim(), emails });
+    }
+    return { ok: true, groups, warnings };
+}
+/**
+ * Write-gate twin of {@link parseGroupsFile}: strict — structural errors AND
+ * entry-level warnings both refuse the candidate, so a UI write can never land
+ * a group the resolver would silently skip.
+ */
+export function validateGroupsFile(text, filename) {
+    // Strict PARSE first (no empty-key tolerance): the read side forgives a
+    // blank key entry-level so other groups keep resolving, but a WRITE that
+    // contains one — anywhere, including outside the `groups:` mapping — must
+    // refuse rather than land bytes the tolerant reader silently drops.
+    const strict = parseYamlSubset(text.trim() ? text : 'groups:');
+    if (!strict.ok)
+        return { ok: false, errors: [`${filename}: ${strict.error}`] };
+    const parsed = parseGroupsFile(text, filename);
+    if (!parsed.ok)
+        return { ok: false, errors: parsed.errors };
+    if (parsed.warnings.length > 0)
+        return { ok: false, errors: parsed.warnings };
+    return { ok: true };
+}
+//# sourceMappingURL=group-files.js.map

package/dist/modules/access-model/group-files.js.map

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

package/dist/modules/access-model/kb-read-filter.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared read-filter primitive.
+ *
+ * One place that knows how to turn workspace-relative paths into read verdicts,
+ * reused by every surface that must hide nodes a user can't read: the agent
+ * tools (`read_file`/`list_files`/`grep`), the file-explorer tree, the content
+ * routes, the diff/review routes, and the KB graph.
+ *
+ * It deliberately shares only the PRIMITIVE — the path mapping and the batched
+ * verdict map — NOT the inclusion policy. Callers differ on that: the agent's
+ * `list_files` keeps directory entries visible (a restricted child is filtered
+ * when read), whereas the explorer tree hides a restricted directory's whole
+ * subtree. Each caller applies the verdict to its own policy.
+ *
+ * It is parameterized by the access method to call (`ReadBatchFn`); every
+ * caller — the tree, the agent tools, and the graph — now uses the full
+ * `canReadBatch` (folder chain + per-node frontmatter `read:` rules), with the
+ * per-file frontmatter reads memoized inside the access service.
+ */
+/**
+ * A batched read check over KB-repo-relative paths. Returns a map keyed by the
+ * input paths. `IAccessControl.canReadBatch` satisfies this shape.
+ */
+export type ReadBatchFn = (workspaceId: string, userEmail: string, kbRelPaths: string[]) => Promise<Map<string, boolean>>;
+/**
+ * Map a workspace-relative path to its KB-repo-relative form (what the access
+ * tree is keyed on), or null when the path is outside the KB repo — reserved
+ * workspace files and the KB dir itself carry no `read:` rules and are never
+ * gated. Tolerates a leading `./` or `/` and a trailing `/`.
+ */
+export declare function toKbRelative(p: string, kbDirName: string): string | null;
+/**
+ * Resolve read verdicts for a set of workspace-relative paths in ONE batched
+ * access call. Non-KB paths (outside `kbDirName`) are always readable — they
+ * carry no `read:` rules. KB paths are checked via `batchFn`. Returns a map
+ * keyed by the original `wsPaths` (so callers can look up by the entry path
+ * they passed). A path absent from the access verdict resolves to `false`
+ * (fail-closed) — never silently readable.
+ */
+export declare function resolveReadableMap(batchFn: ReadBatchFn, workspaceId: string, userEmail: string, kbDirName: string, wsPaths: string[]): Promise<Map<string, boolean>>;
+//# sourceMappingURL=kb-read-filter.d.ts.map

package/dist/modules/access-model/kb-read-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kb-read-filter.d.ts","sourceRoot":"","sources":["../../../src/modules/access-model/kb-read-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,CACxB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAAE,KACjB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAEnC;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMxE;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,WAAW,EACpB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EAAE,GAChB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAiB/B"}

package/dist/modules/access-model/kb-read-filter.js

@@ -0,0 +1,60 @@
+/**
+ * Shared read-filter primitive.
+ *
+ * One place that knows how to turn workspace-relative paths into read verdicts,
+ * reused by every surface that must hide nodes a user can't read: the agent
+ * tools (`read_file`/`list_files`/`grep`), the file-explorer tree, the content
+ * routes, the diff/review routes, and the KB graph.
+ *
+ * It deliberately shares only the PRIMITIVE — the path mapping and the batched
+ * verdict map — NOT the inclusion policy. Callers differ on that: the agent's
+ * `list_files` keeps directory entries visible (a restricted child is filtered
+ * when read), whereas the explorer tree hides a restricted directory's whole
+ * subtree. Each caller applies the verdict to its own policy.
+ *
+ * It is parameterized by the access method to call (`ReadBatchFn`); every
+ * caller — the tree, the agent tools, and the graph — now uses the full
+ * `canReadBatch` (folder chain + per-node frontmatter `read:` rules), with the
+ * per-file frontmatter reads memoized inside the access service.
+ */
+/**
+ * Map a workspace-relative path to its KB-repo-relative form (what the access
+ * tree is keyed on), or null when the path is outside the KB repo — reserved
+ * workspace files and the KB dir itself carry no `read:` rules and are never
+ * gated. Tolerates a leading `./` or `/` and a trailing `/`.
+ */
+export function toKbRelative(p, kbDirName) {
+    const norm = p.replace(/^\.?\/+/, '').replace(/\/+$/, '');
+    const prefix = `${kbDirName}/`;
+    if (!norm.startsWith(prefix))
+        return null;
+    const rel = norm.slice(prefix.length);
+    return rel.length > 0 ? rel : null;
+}
+/**
+ * Resolve read verdicts for a set of workspace-relative paths in ONE batched
+ * access call. Non-KB paths (outside `kbDirName`) are always readable — they
+ * carry no `read:` rules. KB paths are checked via `batchFn`. Returns a map
+ * keyed by the original `wsPaths` (so callers can look up by the entry path
+ * they passed). A path absent from the access verdict resolves to `false`
+ * (fail-closed) — never silently readable.
+ */
+export async function resolveReadableMap(batchFn, workspaceId, userEmail, kbDirName, wsPaths) {
+    const relByWsPath = new Map();
+    for (const wp of wsPaths) {
+        const rel = toKbRelative(wp, kbDirName);
+        if (rel !== null)
+            relByWsPath.set(wp, rel);
+    }
+    const verdict = relByWsPath.size > 0
+        ? await batchFn(workspaceId, userEmail, [...new Set(relByWsPath.values())])
+        : new Map();
+    const out = new Map();
+    for (const wp of wsPaths) {
+        const rel = relByWsPath.get(wp);
+        // Non-KB path → always readable. KB path → the verdict, fail-closed if absent.
+        out.set(wp, rel === undefined ? true : verdict.get(rel) === true);
+    }
+    return out;
+}
+//# sourceMappingURL=kb-read-filter.js.map

package/dist/modules/access-model/kb-read-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kb-read-filter.js","sourceRoot":"","sources":["../../../src/modules/access-model/kb-read-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAYH;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,CAAS,EAAE,SAAiB;IACvD,MAAM,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC1D,MAAM,MAAM,GAAG,GAAG,SAAS,GAAG,CAAC;IAC/B,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACtC,OAAO,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AACrC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAAoB,EACpB,WAAmB,EACnB,SAAiB,EACjB,SAAiB,EACjB,OAAiB;IAEjB,MAAM,WAAW,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC9C,KAAK,MAAM,EAAE,IAAI,OAAO,EAAE,CAAC;QACzB,MAAM,GAAG,GAAG,YAAY,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;QACxC,IAAI,GAAG,KAAK,IAAI;YAAE,WAAW,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IAC7C,CAAC;IACD,MAAM,OAAO,GACX,WAAW,CAAC,IAAI,GAAG,CAAC;QAClB,CAAC,CAAC,MAAM,OAAO,CAAC,WAAW,EAAE,SAAS,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QAC3E,CAAC,CAAC,IAAI,GAAG,EAAmB,CAAC;IACjC,MAAM,GAAG,GAAG,IAAI,GAAG,EAAmB,CAAC;IACvC,KAAK,MAAM,EAAE,IAAI,OAAO,EAAE,CAAC;QACzB,MAAM,GAAG,GAAG,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChC,+EAA+E;QAC/E,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,CAAC;IACpE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/modules/access-model/render-roles-yaml.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Render a `roles.yaml` granting Admin to each email — the ONE renderer every
+ * generated roles.yaml goes through (empty-remote seeding, the startup
+ * top-up, and the break-glass recovery), so none of them can drift on
+ * validation and each fails with the same actionable message.
+ *
+ * Each email is validated first, because a malformed one renders a file with
+ * no working Admin — SILENTLY: a leading `#` turns the entry into a YAML
+ * comment, an embedded newline breaks the list, an all-whitespace value
+ * renders an empty entry. A bad ADMIN_EMAIL is operator error, and the
+ * callers' fail-closed contracts want a message naming the fix instead of an
+ * un-administrable knowledge base (or a write-validator rejection deep in the
+ * recovery path).
+ */
+export declare function renderRolesYaml(adminEmails: readonly string[], 
+/**
+ * Provenance comment appended to the header. The seed/top-up default names
+ * where the file came from; recovery passes `null` — claiming "generated at
+ * KB-seed time" on a recovery-restored file would mislead whoever reads it.
+ */
+provenance?: string | null): string;
+//# sourceMappingURL=render-roles-yaml.d.ts.map

package/dist/modules/access-model/render-roles-yaml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-roles-yaml.d.ts","sourceRoot":"","sources":["../../../src/modules/access-model/render-roles-yaml.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,SAAS,MAAM,EAAE;AAC9B;;;;GAIG;AACH,UAAU,GAAE,MAAM,GAAG,IAA0E,GAC9F,MAAM,CAwCR"}

package/dist/modules/access-model/render-roles-yaml.js

@@ -0,0 +1,56 @@
+import { parseRolesYaml } from './access-grammar.js';
+/**
+ * Render a `roles.yaml` granting Admin to each email — the ONE renderer every
+ * generated roles.yaml goes through (empty-remote seeding, the startup
+ * top-up, and the break-glass recovery), so none of them can drift on
+ * validation and each fails with the same actionable message.
+ *
+ * Each email is validated first, because a malformed one renders a file with
+ * no working Admin — SILENTLY: a leading `#` turns the entry into a YAML
+ * comment, an embedded newline breaks the list, an all-whitespace value
+ * renders an empty entry. A bad ADMIN_EMAIL is operator error, and the
+ * callers' fail-closed contracts want a message naming the fix instead of an
+ * un-administrable knowledge base (or a write-validator rejection deep in the
+ * recovery path).
+ */
+export function renderRolesYaml(adminEmails, 
+/**
+ * Provenance comment appended to the header. The seed/top-up default names
+ * where the file came from; recovery passes `null` — claiming "generated at
+ * KB-seed time" on a recovery-restored file would mislead whoever reads it.
+ */
+provenance = 'Generated by the Bevel platform at KB-seed time from ADMIN_EMAIL.') {
+    const emails = adminEmails.map((raw) => {
+        const email = raw.trim();
+        if (email === '') {
+            throw new Error('Seed admin email is empty — set ADMIN_EMAIL to a real address.');
+        }
+        if (email.startsWith('#')) {
+            throw new Error(`Seed admin email ${JSON.stringify(raw)} starts with "#", which YAML reads as a comment — fix ADMIN_EMAIL.`);
+        }
+        if (/\s/.test(email)) {
+            throw new Error(`Seed admin email ${JSON.stringify(raw)} contains whitespace, which would corrupt roles.yaml — fix ADMIN_EMAIL.`);
+        }
+        return email;
+    });
+    const lines = emails.map((e) => `    - ${e}`).join('\n');
+    const text = '# Identity → role mapping for access control.\n' +
+        '# Role names are case- and whitespace-insensitive. The `Admin` role is special:\n' +
+        '# only Admins may edit this file, and at least one Admin must always exist.\n' +
+        (provenance !== null ? `#\n# ${provenance}\n` : '') +
+        'roles:\n' +
+        '  Admin:\n' +
+        `${lines}\n`;
+    // Validate by PARSING with the real access parser, not by re-implementing
+    // its email grammar: whatever the parser would reject (a `<Name <email>`
+    // shape, a non-email string, tomorrow's new rule) must fail here, before an
+    // un-administrable roles.yaml gets committed. The checks above exist only
+    // to give the common mistakes sharper messages.
+    const parsed = parseRolesYaml(text);
+    if (!parsed.ok) {
+        throw new Error(`Generated roles.yaml from ADMIN_EMAIL would not parse — fix the configured address(es). ` +
+            parsed.errors.join('; '));
+    }
+    return text;
+}
+//# sourceMappingURL=render-roles-yaml.js.map

package/dist/modules/access-model/render-roles-yaml.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-roles-yaml.js","sourceRoot":"","sources":["../../../src/modules/access-model/render-roles-yaml.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAC7B,WAA8B;AAC9B;;;;GAIG;AACH,aAA4B,mEAAmE;IAE/F,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QACrC,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;QACzB,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,gEAAgE,CAAC,CAAC;QACpF,CAAC;QACD,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CACb,oBAAoB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,oEAAoE,CAC5G,CAAC;QACJ,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CACb,oBAAoB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,yEAAyE,CACjH,CAAC;QACJ,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzD,MAAM,IAAI,GACR,iDAAiD;QACjD,mFAAmF;QACnF,+EAA+E;QAC/E,CAAC,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,QAAQ,UAAU,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACnD,UAAU;QACV,YAAY;QACZ,GAAG,KAAK,IAAI,CAAC;IACf,0EAA0E;IAC1E,yEAAyE;IACzE,4EAA4E;IAC5E,0EAA0E;IAC1E,gDAAgD;IAChD,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,0FAA0F;YACxF,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAC3B,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/modules/access-model/roles-yaml-guard.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Pre-disk validity gate for `roles.yaml`.
+ *
+ * WHY this exists: `roles.yaml` is the single point of failure for the whole
+ * app. The runtime resolver's `loadModel` HARD-THROWS `AccessConfigError` on a
+ * parse failure, and `isAdmin` swallows that into `false` for EVERYONE — so a
+ * single malformed `roles.yaml` is an app-wide, in-app-unrecoverable admin
+ * lockout. The dedicated Roles & Members service already validates every
+ * candidate before writing (`assertLoadable`), but the two RAW write paths do
+ * not:
+ *   - the human editor save  (`PUT /workspace/:id/file`)
+ *   - the agent's file tools (`LockingFilesystem.writeFile` / `writeFiles`)
+ *
+ * Both of those let an admin (or an admin-driven agent) commit a broken file.
+ * This guard plugs them: it runs the resolver's OWN parser on the candidate
+ * BEFORE a byte hits disk, and refuses the write with a 422 on any error. A
+ * write that passes here is loadable by `loadModel`, so the lockout becomes
+ * structurally unreachable through normal edits.
+ *
+ * The break-glass recovery path (for a file that got broken some OTHER way —
+ * a direct git push, a pre-guard commit) lives in `roles-admin.service.ts`.
+ */
+import type { FileContent } from '@mastra/core/workspace';
+import { WorkflowDomainError } from '../../shared/domain-errors.js';
+/** Repo-relative basename of the roles file (it lives at the KB repo root). */
+export declare const ROLES_YAML_BASENAME = "roles.yaml";
+/**
+ * A raw write whose candidate `roles.yaml` would not parse. 422 (bad input) —
+ * the edit is refused and nothing is written. Carries the parser errors so the
+ * editor / agent can show exactly what's wrong.
+ */
+export declare class RolesYamlInvalidError extends WorkflowDomainError {
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+/**
+ * True iff `workspaceRelPath` targets the KB's `roles.yaml` (the file at
+ * `<kbDirName>/roles.yaml`). Both the human save route and the agent's
+ * `LockingFilesystem` speak workspace-relative paths, so this is the form we
+ * key on. A bare `roles.yaml` (no KB prefix) is also accepted defensively.
+ */
+export declare function isRolesYamlPath(workspaceRelPath: string, kbDirName: string): boolean;
+/**
+ * Throw {@link RolesYamlInvalidError} if `content` does not parse as a valid
+ * `roles.yaml` per the resolver's own parser. No-op on valid content.
+ */
+export declare function assertRolesYamlParsable(content: string): void;
+/**
+ * A `LockingFilesystem` write-validator scoped to a KB dir: refuses a raw write
+ * that would leave `roles.yaml` unparseable. Pass the returned closure as the
+ * filesystem's `validateWrite` hook. Only string writes are checked — every
+ * code path that writes `roles.yaml` writes it as text; a binary write to that
+ * path is nonsensical and left alone.
+ */
+export declare function makeRolesYamlWriteValidator(kbDirName: string): (path: string, content: FileContent) => void;
+//# sourceMappingURL=roles-yaml-guard.d.ts.map

package/dist/modules/access-model/roles-yaml-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles-yaml-guard.d.ts","sourceRoot":"","sources":["../../../src/modules/access-model/roles-yaml-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAEpE,+EAA+E;AAC/E,eAAO,MAAM,mBAAmB,eAAe,CAAC;AAEhD;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,mBAAmB;IAC5D,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;gBACd,MAAM,EAAE,MAAM,EAAE;CAS7B;AAOD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,gBAAgB,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAGpF;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAG7D;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,MAAM,GAChB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,KAAK,IAAI,CAM9C"}

package/dist/modules/access-model/roles-yaml-guard.js

@@ -0,0 +1,79 @@
+/**
+ * Pre-disk validity gate for `roles.yaml`.
+ *
+ * WHY this exists: `roles.yaml` is the single point of failure for the whole
+ * app. The runtime resolver's `loadModel` HARD-THROWS `AccessConfigError` on a
+ * parse failure, and `isAdmin` swallows that into `false` for EVERYONE — so a
+ * single malformed `roles.yaml` is an app-wide, in-app-unrecoverable admin
+ * lockout. The dedicated Roles & Members service already validates every
+ * candidate before writing (`assertLoadable`), but the two RAW write paths do
+ * not:
+ *   - the human editor save  (`PUT /workspace/:id/file`)
+ *   - the agent's file tools (`LockingFilesystem.writeFile` / `writeFiles`)
+ *
+ * Both of those let an admin (or an admin-driven agent) commit a broken file.
+ * This guard plugs them: it runs the resolver's OWN parser on the candidate
+ * BEFORE a byte hits disk, and refuses the write with a 422 on any error. A
+ * write that passes here is loadable by `loadModel`, so the lockout becomes
+ * structurally unreachable through normal edits.
+ *
+ * The break-glass recovery path (for a file that got broken some OTHER way —
+ * a direct git push, a pre-guard commit) lives in `roles-admin.service.ts`.
+ */
+import { parseRolesYaml } from './access-grammar.js';
+import { WorkflowDomainError } from '../../shared/domain-errors.js';
+/** Repo-relative basename of the roles file (it lives at the KB repo root). */
+export const ROLES_YAML_BASENAME = 'roles.yaml';
+/**
+ * A raw write whose candidate `roles.yaml` would not parse. 422 (bad input) —
+ * the edit is refused and nothing is written. Carries the parser errors so the
+ * editor / agent can show exactly what's wrong.
+ */
+export class RolesYamlInvalidError extends WorkflowDomainError {
+    errors;
+    constructor(errors) {
+        super(`roles.yaml would be invalid and was not saved: ${errors.join('; ')}`, 422, { kind: 'roles-yaml-invalid', rolesYamlErrors: errors });
+        this.name = 'RolesYamlInvalidError';
+        this.errors = errors;
+    }
+}
+/** Normalise a workspace-relative path: backslashes → `/`, strip a leading `./`. */
+function normalizeWsPath(p) {
+    return p.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+/**
+ * True iff `workspaceRelPath` targets the KB's `roles.yaml` (the file at
+ * `<kbDirName>/roles.yaml`). Both the human save route and the agent's
+ * `LockingFilesystem` speak workspace-relative paths, so this is the form we
+ * key on. A bare `roles.yaml` (no KB prefix) is also accepted defensively.
+ */
+export function isRolesYamlPath(workspaceRelPath, kbDirName) {
+    const norm = normalizeWsPath(workspaceRelPath);
+    return norm === `${kbDirName}/${ROLES_YAML_BASENAME}` || norm === ROLES_YAML_BASENAME;
+}
+/**
+ * Throw {@link RolesYamlInvalidError} if `content` does not parse as a valid
+ * `roles.yaml` per the resolver's own parser. No-op on valid content.
+ */
+export function assertRolesYamlParsable(content) {
+    const parsed = parseRolesYaml(content);
+    if (!parsed.ok)
+        throw new RolesYamlInvalidError(parsed.errors);
+}
+/**
+ * A `LockingFilesystem` write-validator scoped to a KB dir: refuses a raw write
+ * that would leave `roles.yaml` unparseable. Pass the returned closure as the
+ * filesystem's `validateWrite` hook. Only string writes are checked — every
+ * code path that writes `roles.yaml` writes it as text; a binary write to that
+ * path is nonsensical and left alone.
+ */
+export function makeRolesYamlWriteValidator(kbDirName) {
+    return (path, content) => {
+        if (typeof content !== 'string')
+            return;
+        if (!isRolesYamlPath(path, kbDirName))
+            return;
+        assertRolesYamlParsable(content);
+    };
+}
+//# sourceMappingURL=roles-yaml-guard.js.map