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

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

@@ -5,7 +5,7 @@
  * 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
+ * lockout. The dedicated App roles service already validates every
  * candidate before writing (`assertLoadable`), but the two RAW write paths do
  * not:
  *   - the human editor save  (`PUT /workspace/:id/file`)
@@ -21,7 +21,9 @@
  * a direct git push, a pre-guard commit) lives in `roles-admin.service.ts`.
  */
 import type { FileContent } from '@mastra/core/workspace';
+import type { GroupsIndex } from './group-files.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import type { WriteValidator } from '../kb-fs/locking-filesystem.js';
 /** Repo-relative basename of the roles file (it lives at the KB repo root). */
 export declare const ROLES_YAML_BASENAME = "roles.yaml";
 /**
@@ -52,5 +54,74 @@ export declare function assertRolesYamlParsable(content: string): void;
  * 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;
+export declare function makeRolesYamlWriteValidator(kbDirName: string): WriteValidator & ((path: string, content: FileContent) => void);
+/** What an agent is told to do instead of creating a role. */
+export declare const NEW_ROLE_GUIDANCE = "App roles are pre-set \u2014 add people to existing roles, and use a GROUP for a task- or team-scoped set of people.";
+/**
+ * An AGENT write whose candidate `roles.yaml` declares a role the current file
+ * does not. Same 422 shape as {@link RolesYamlInvalidError}; the message is
+ * self-contained because a tool error reaches the agent as its message alone,
+ * and the agent relays it to its user.
+ */
+export declare class RolesYamlNewRoleError extends WorkflowDomainError {
+    readonly roleNames: string[];
+    constructor(roleNames: string[]);
+}
+/**
+ * Throw {@link RolesYamlNewRoleError} if `candidate` declares a role name
+ * (compared canonically, so a respelling is not new) absent from `current`.
+ * A rename is a delete plus a create, so it is refused for the created name.
+ */
+export declare function assertNoNewRoles(current: string | null, candidate: string): void;
+/**
+ * The active group source an agent write is checked against: its groups and
+ * the file they came from (`groups.yaml`, or `synced-groups.yaml` in IdP mode).
+ * `null` when the source exists but could not be read — group entries are then
+ * left unchecked rather than every one refused.
+ */
+export type ActiveGroupsForValidation = {
+    groups: GroupsIndex;
+    sourceFile: string;
+} | null;
+/**
+ * An AGENT write whose candidate `roles.yaml` adds a `- group:<Name>` entry
+ * naming no group in the active group source. The resolver ignores such an
+ * entry with only a log warning — the role silently reaches nobody — so it is
+ * refused up front, naming each entry, in the same 422 shape as the others.
+ */
+export declare class RolesYamlUnknownGroupError extends WorkflowDomainError {
+    readonly entries: {
+        role: string;
+        entry: string;
+    }[];
+    constructor(entries: {
+        role: string;
+        entry: string;
+    }[], sourceFile: string);
+}
+/**
+ * Throw {@link RolesYamlUnknownGroupError} if `candidate` adds a group entry
+ * whose name (compared canonically) the active group source does not declare.
+ * Only ADDED entries are checked: an entry already in `current` whose group
+ * has since been retired is left alone, so it cannot block an unrelated
+ * membership edit.
+ */
+export declare function assertKnownGroups(current: string | null, candidate: string, active: ActiveGroupsForValidation): void;
+/**
+ * The agent's `roles.yaml` gate: everything {@link makeRolesYamlWriteValidator}
+ * refuses, plus any role the current file does not declare and — when
+ * `loadGroups` is given — any added `- group:<Name>` entry naming a group the
+ * active group source does not declare. Agents manage
+ * membership only; the human editor and the App roles service keep the plain
+ * validator. `readCurrent` returns the file's current text, null when absent.
+ * Content of any type is checked — decoded as UTF-8 — so bytes cannot slip past.
+ *
+ * `readCurrent` is read afresh on every call, never cached: `LockingFilesystem`
+ * calls this validator before taking the lock (a cheap early refusal) and again
+ * once the `roles.yaml` lock is held, on the bytes that land. That second call
+ * is the decisive one — it compares against the file as the other roles.yaml
+ * writers, which coordinate on the same lock, left it — so a role deleted while
+ * the write waited cannot be reinstated, and one added meanwhile is not refused.
+ */
+export declare function makeAgentRolesYamlWriteValidator(kbDirName: string, readCurrent: () => Promise<string | null>, loadGroups?: () => Promise<ActiveGroupsForValidation>): WriteValidator;
 //# sourceMappingURL=roles-yaml-guard.d.ts.map

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

@@ -1 +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"}
+{"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,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAErE,+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,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,KAAK,IAAI,CAAC,CAQjE;AAED,8DAA8D;AAC9D,eAAO,MAAM,iBAAiB,yHACqF,CAAC;AAEpH;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,mBAAmB;IAC5D,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC;gBACjB,SAAS,EAAE,MAAM,EAAE;CAWhC;AAqBD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAMhF;AAED;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GAAG;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC;AAU3F;;;;;GAKG;AACH,qBAAa,0BAA2B,SAAQ,mBAAmB;IACjE,QAAQ,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;gBACxC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,EAAE,UAAU,EAAE,MAAM;CAY3E;AA2BD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,GAAG,IAAI,EACtB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,yBAAyB,GAChC,IAAI,CAQN;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gCAAgC,CAC9C,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,EACzC,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,yBAAyB,CAAC,GACpD,cAAc,CAWhB"}

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

@@ -5,7 +5,7 @@
  * 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
+ * lockout. The dedicated App roles service already validates every
  * candidate before writing (`assertLoadable`), but the two RAW write paths do
  * not:
  *   - the human editor save  (`PUT /workspace/:id/file`)
@@ -20,7 +20,7 @@
  * 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 { GROUP_REF_PREFIX, canonicalRoleName, parseRolesYaml, parseYamlSubset } 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';
@@ -68,12 +68,162 @@ export function assertRolesYamlParsable(content) {
  * path is nonsensical and left alone.
  */
 export function makeRolesYamlWriteValidator(kbDirName) {
-    return (path, content) => {
+    const validate = (path, content) => {
         if (typeof content !== 'string')
             return;
         if (!isRolesYamlPath(path, kbDirName))
             return;
         assertRolesYamlParsable(content);
     };
+    validate.appliesTo = (path) => isRolesYamlPath(path, kbDirName);
+    return validate;
+}
+/** What an agent is told to do instead of creating a role. */
+export const NEW_ROLE_GUIDANCE = 'App roles are pre-set — add people to existing roles, and use a GROUP for a task- or team-scoped set of people.';
+/**
+ * An AGENT write whose candidate `roles.yaml` declares a role the current file
+ * does not. Same 422 shape as {@link RolesYamlInvalidError}; the message is
+ * self-contained because a tool error reaches the agent as its message alone,
+ * and the agent relays it to its user.
+ */
+export class RolesYamlNewRoleError extends WorkflowDomainError {
+    roleNames;
+    constructor(roleNames) {
+        const quoted = roleNames.map((n) => `'${n}'`).join(', ');
+        super(`roles.yaml was not saved: agents never create app roles, and ${quoted} ` +
+            `${roleNames.length === 1 ? 'is not an existing role' : 'are not existing roles'}. ${NEW_ROLE_GUIDANCE}`, 422, { kind: 'roles-yaml-new-role', roleNames });
+        this.name = 'RolesYamlNewRoleError';
+        this.roleNames = roleNames;
+    }
+}
+/**
+ * The role names `text` declares, canonical → display spelling. Lenient on
+ * purpose: a current file with a bad email still vouches for its role names.
+ * Text that is absent or not a `roles:` mapping declares none.
+ */
+function declaredRoleNames(text) {
+    const names = new Map();
+    if (text === null)
+        return names;
+    const parsed = parseYamlSubset(text);
+    if (!parsed.ok)
+        return names;
+    const roles = parsed.value?.roles;
+    if (roles == null || typeof roles !== 'object' || Array.isArray(roles))
+        return names;
+    for (const display of Object.keys(roles)) {
+        const canonical = canonicalRoleName(display);
+        if (canonical && !names.has(canonical))
+            names.set(canonical, display.trim());
+    }
+    return names;
+}
+/**
+ * Throw {@link RolesYamlNewRoleError} if `candidate` declares a role name
+ * (compared canonically, so a respelling is not new) absent from `current`.
+ * A rename is a delete plus a create, so it is refused for the created name.
+ */
+export function assertNoNewRoles(current, candidate) {
+    const existing = declaredRoleNames(current);
+    const created = [...declaredRoleNames(candidate)]
+        .filter(([canonical]) => !existing.has(canonical))
+        .map(([, display]) => display);
+    if (created.length > 0)
+        throw new RolesYamlNewRoleError(created);
+}
+/**
+ * An AGENT write whose candidate `roles.yaml` adds a `- group:<Name>` entry
+ * naming no group in the active group source. The resolver ignores such an
+ * entry with only a log warning — the role silently reaches nobody — so it is
+ * refused up front, naming each entry, in the same 422 shape as the others.
+ */
+export class RolesYamlUnknownGroupError extends WorkflowDomainError {
+    entries;
+    constructor(entries, sourceFile) {
+        const listed = entries.map((e) => `'- ${e.entry}' under role '${e.role}'`).join(', ');
+        super(`roles.yaml was not saved: ${listed} ${entries.length === 1 ? 'names a group' : 'name groups'} ` +
+            `that ${sourceFile} does not declare. Group names are matched case- and whitespace-insensitively; ` +
+            'use an existing group, or create the group first.', 422, { kind: 'roles-yaml-unknown-group', entries, sourceFile });
+        this.name = 'RolesYamlUnknownGroupError';
+        this.entries = entries;
+    }
+}
+/** Every `- group:<Name>` entry `text` declares, in file order. Lenient, like {@link declaredRoleNames}. */
+function groupEntries(text) {
+    const out = [];
+    if (text === null)
+        return out;
+    const parsed = parseYamlSubset(text);
+    if (!parsed.ok)
+        return out;
+    const roles = parsed.value?.roles;
+    if (roles == null || typeof roles !== 'object' || Array.isArray(roles))
+        return out;
+    for (const [display, members] of Object.entries(roles)) {
+        if (!Array.isArray(members))
+            continue;
+        for (const member of members) {
+            if (typeof member !== 'string')
+                continue;
+            const entry = member.trim();
+            if (!entry.toLowerCase().startsWith(GROUP_REF_PREFIX))
+                continue;
+            out.push({
+                role: display.trim(),
+                roleCanonical: canonicalRoleName(display),
+                entry,
+                group: canonicalRoleName(entry.slice(GROUP_REF_PREFIX.length)),
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Throw {@link RolesYamlUnknownGroupError} if `candidate` adds a group entry
+ * whose name (compared canonically) the active group source does not declare.
+ * Only ADDED entries are checked: an entry already in `current` whose group
+ * has since been retired is left alone, so it cannot block an unrelated
+ * membership edit.
+ */
+export function assertKnownGroups(current, candidate, active) {
+    if (active === null)
+        return;
+    const key = (e) => `${e.roleCanonical}\n${e.group}`;
+    const existing = new Set(groupEntries(current).map(key));
+    const unknown = groupEntries(candidate)
+        .filter((e) => !existing.has(key(e)) && !active.groups.has(e.group))
+        .map(({ role, entry }) => ({ role, entry }));
+    if (unknown.length > 0)
+        throw new RolesYamlUnknownGroupError(unknown, active.sourceFile);
+}
+/**
+ * The agent's `roles.yaml` gate: everything {@link makeRolesYamlWriteValidator}
+ * refuses, plus any role the current file does not declare and — when
+ * `loadGroups` is given — any added `- group:<Name>` entry naming a group the
+ * active group source does not declare. Agents manage
+ * membership only; the human editor and the App roles service keep the plain
+ * validator. `readCurrent` returns the file's current text, null when absent.
+ * Content of any type is checked — decoded as UTF-8 — so bytes cannot slip past.
+ *
+ * `readCurrent` is read afresh on every call, never cached: `LockingFilesystem`
+ * calls this validator before taking the lock (a cheap early refusal) and again
+ * once the `roles.yaml` lock is held, on the bytes that land. That second call
+ * is the decisive one — it compares against the file as the other roles.yaml
+ * writers, which coordinate on the same lock, left it — so a role deleted while
+ * the write waited cannot be reinstated, and one added meanwhile is not refused.
+ */
+export function makeAgentRolesYamlWriteValidator(kbDirName, readCurrent, loadGroups) {
+    const validate = async (path, content) => {
+        if (!isRolesYamlPath(path, kbDirName))
+            return;
+        const text = typeof content === 'string' ? content : Buffer.from(content).toString('utf-8');
+        assertRolesYamlParsable(text);
+        const current = await readCurrent();
+        assertNoNewRoles(current, text);
+        if (loadGroups)
+            assertKnownGroups(current, text, await loadGroups());
+    };
+    validate.appliesTo = (path) => isRolesYamlPath(path, kbDirName);
+    return validate;
 }
 //# sourceMappingURL=roles-yaml-guard.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"roles-yaml-guard.js","sourceRoot":"","sources":["../../../src/modules/access-model/roles-yaml-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAEpE,+EAA+E;AAC/E,MAAM,CAAC,MAAM,mBAAmB,GAAG,YAAY,CAAC;AAEhD;;;;GAIG;AACH,MAAM,OAAO,qBAAsB,SAAQ,mBAAmB;IACnD,MAAM,CAAW;IAC1B,YAAY,MAAgB;QAC1B,KAAK,CACH,kDAAkD,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EACrE,GAAG,EACH,EAAE,IAAI,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,EAAE,CACxD,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED,oFAAoF;AACpF,SAAS,eAAe,CAAC,CAAS;IAChC,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AACpD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,gBAAwB,EAAE,SAAiB;IACzE,MAAM,IAAI,GAAG,eAAe,CAAC,gBAAgB,CAAC,CAAC;IAC/C,OAAO,IAAI,KAAK,GAAG,SAAS,IAAI,mBAAmB,EAAE,IAAI,IAAI,KAAK,mBAAmB,CAAC;AACxF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAe;IACrD,MAAM,MAAM,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IACvC,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,MAAM,IAAI,qBAAqB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AACjE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,2BAA2B,CACzC,SAAiB;IAEjB,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE;QACvB,IAAI,OAAO,OAAO,KAAK,QAAQ;YAAE,OAAO;QACxC,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,SAAS,CAAC;YAAE,OAAO;QAC9C,uBAAuB,CAAC,OAAO,CAAC,CAAC;IACnC,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"roles-yaml-guard.js","sourceRoot":"","sources":["../../../src/modules/access-model/roles-yaml-guard.ts"],"names":[],"mappings":"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"}

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

@@ -1 +1 @@
-{"version":3,"file":"admin-access.service.d.ts","sourceRoot":"","sources":["../../../src/modules/admin/admin-access.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAC5E,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAE1E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE;;;;;;;;;GASG;AACH,qBAAa,kBAAmB,YAAW,mBAAmB;IAE1D,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,mFAAmF;IACnF,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,iBAAiB;gBAXjB,aAAa,EAAE,cAAc,EAC7B,gBAAgB,EAAE,gBAAgB;IACnD,mFAAmF;IAClE,MAAM,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC;IAChD;;;;;;OAMG;IACc,iBAAiB,GAAE,MAAM,EAAO;IAG7C,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC;CAkB3D"}
+{"version":3,"file":"admin-access.service.d.ts","sourceRoot":"","sources":["../../../src/modules/admin/admin-access.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAI5E,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAG1E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE;;;;;;;;;GASG;AACH,qBAAa,kBAAmB,YAAW,mBAAmB;IAE1D,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,mFAAmF;IACnF,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,iBAAiB;gBAXjB,aAAa,EAAE,cAAc,EAC7B,gBAAgB,EAAE,gBAAgB;IACnD,mFAAmF;IAClE,MAAM,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC;IAChD;;;;;;OAMG;IACc,iBAAiB,GAAE,MAAM,EAAO;IAG7C,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC;CAkB3D"}

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

@@ -1,4 +1,7 @@
+import { logger } from '../../shared/logging.js';
+const log = logger('admin');
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import { canonicalEmail } from '../../shared/email-identity.js';
 /**
  * Admin = holder of the `Admin` role in `roles.yaml`. We resolve it through the
  * access model exactly as the rest of the app does — `canWrite('roles.yaml')` is
@@ -33,7 +36,7 @@ export class AdminAccessService {
     async isAdmin(email) {
         if (!email)
             return false;
-        const normalized = email.trim().toLowerCase();
+        const normalized = canonicalEmail(email);
         if (this.alwaysAdminEmails.includes(normalized))
             return true;
         try {
@@ -47,7 +50,7 @@ export class AdminAccessService {
         catch (err) {
             // Log so an admin lockout caused by a clone / roles.yaml failure is
             // diagnosable rather than a silent denial.
-            console.warn('[admin] isAdmin resolution failed:', err instanceof Error ? err.message : String(err));
+            log.warn('isAdmin resolution failed:', { err });
             return false;
         }
     }

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

@@ -1 +1 @@
-{"version":3,"file":"admin-access.service.js","sourceRoot":"","sources":["../../../src/modules/admin/admin-access.service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAGpE;;;;;;;;;GASG;AACH,MAAM,OAAO,kBAAkB;IAEV;IACA;IAEA;IAQA;IAZnB,YACmB,aAA6B,EAC7B,gBAAkC;IACnD,mFAAmF;IAClE,MAA+B;IAChD;;;;;;OAMG;IACc,oBAA8B,EAAE;QAXhC,kBAAa,GAAb,aAAa,CAAgB;QAC7B,qBAAgB,GAAhB,gBAAgB,CAAkB;QAElC,WAAM,GAAN,MAAM,CAAyB;QAQ/B,sBAAiB,GAAjB,iBAAiB,CAAe;IAChD,CAAC;IAEJ,KAAK,CAAC,OAAO,CAAC,KAAyB;QACrC,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QACzB,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC9C,IAAI,IAAI,CAAC,iBAAiB,CAAC,QAAQ,CAAC,UAAU,CAAC;YAAE,OAAO,IAAI,CAAC;QAC7D,IAAI,CAAC;YACH,qEAAqE;YACrE,gEAAgE;YAChE,uEAAuE;YACvE,MAAM,MAAM,GAAG,OAAO,IAAI,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;YAC/E,MAAM,IAAI,CAAC,gBAAgB,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC;YACzD,OAAO,MAAM,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,oBAAoB,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;QAC9F,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,oEAAoE;YACpE,2CAA2C;YAC3C,OAAO,CAAC,IAAI,CAAC,oCAAoC,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;YACrG,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"admin-access.service.js","sourceRoot":"","sources":["../../../src/modules/admin/admin-access.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEjD,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;AAE5B,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAGhE;;;;;;;;;GASG;AACH,MAAM,OAAO,kBAAkB;IAEV;IACA;IAEA;IAQA;IAZnB,YACmB,aAA6B,EAC7B,gBAAkC;IACnD,mFAAmF;IAClE,MAA+B;IAChD;;;;;;OAMG;IACc,oBAA8B,EAAE;QAXhC,kBAAa,GAAb,aAAa,CAAgB;QAC7B,qBAAgB,GAAhB,gBAAgB,CAAkB;QAElC,WAAM,GAAN,MAAM,CAAyB;QAQ/B,sBAAiB,GAAjB,iBAAiB,CAAe;IAChD,CAAC;IAEJ,KAAK,CAAC,OAAO,CAAC,KAAyB;QACrC,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QACzB,MAAM,UAAU,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;QACzC,IAAI,IAAI,CAAC,iBAAiB,CAAC,QAAQ,CAAC,UAAU,CAAC;YAAE,OAAO,IAAI,CAAC;QAC7D,IAAI,CAAC;YACH,qEAAqE;YACrE,gEAAgE;YAChE,uEAAuE;YACvE,MAAM,MAAM,GAAG,OAAO,IAAI,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;YAC/E,MAAM,IAAI,CAAC,gBAAgB,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC;YACzD,OAAO,MAAM,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,oBAAoB,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;QAC9F,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,oEAAoE;YACpE,2CAA2C;YAC3C,GAAG,CAAC,IAAI,CAAC,4BAA4B,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;YAChD,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACF"}

package/dist/modules/agent-instructions/agent-instructions.routes.d.ts

@@ -0,0 +1,21 @@
+import express, { type RequestHandler } from 'express';
+import type { AgentPreambleReader } from './read-preamble.js';
+/**
+ * The agent-facing instructions route, mounted on the tools router beside
+ * `GET /agent/all-tools` and behind the same `manualAuth` (a connection key,
+ * an internal token or a browser JWT):
+ *
+ *   GET /agent/instructions   the composed text both channels are built from,
+ *                             as the composer returns it. The local `hexis-mcp`
+ *                             bridge reads it at startup; the External agent
+ *                             access card reads it to show what agents get.
+ *
+ * The hosted proxy does NOT call this: it composes in-process while building
+ * each request's server (see `McpService.createRequestServer`).
+ * `Cache-Control: no-store`
+ * because the text is privileged: it is read with platform rights and may
+ * name folders the caller cannot open. A reader throw is a 500, never an
+ * empty preamble, so the caller's own fallback decides what to send.
+ */
+export declare function createAgentInstructionsRoutes(manualAuth: RequestHandler, readPreamble: AgentPreambleReader): express.Router;
+//# sourceMappingURL=agent-instructions.routes.d.ts.map

package/dist/modules/agent-instructions/agent-instructions.routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-instructions.routes.d.ts","sourceRoot":"","sources":["../../../src/modules/agent-instructions/agent-instructions.routes.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,EAAE,EAAE,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AAKvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,6BAA6B,CAAC,UAAU,EAAE,cAAc,EAAE,YAAY,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAgB3H"}

package/dist/modules/agent-instructions/agent-instructions.routes.js

@@ -0,0 +1,38 @@
+import express from 'express';
+import { logger } from '../../shared/logging.js';
+const log = logger('agent-instructions');
+import { composeAgentInstructions } from './compose.js';
+/**
+ * The agent-facing instructions route, mounted on the tools router beside
+ * `GET /agent/all-tools` and behind the same `manualAuth` (a connection key,
+ * an internal token or a browser JWT):
+ *
+ *   GET /agent/instructions   the composed text both channels are built from,
+ *                             as the composer returns it. The local `hexis-mcp`
+ *                             bridge reads it at startup; the External agent
+ *                             access card reads it to show what agents get.
+ *
+ * The hosted proxy does NOT call this: it composes in-process while building
+ * each request's server (see `McpService.createRequestServer`).
+ * `Cache-Control: no-store`
+ * because the text is privileged: it is read with platform rights and may
+ * name folders the caller cannot open. A reader throw is a 500, never an
+ * empty preamble, so the caller's own fallback decides what to send.
+ */
+export function createAgentInstructionsRoutes(manualAuth, readPreamble) {
+    const router = express.Router();
+    router.get('/agent/instructions', manualAuth, async (_req, res) => {
+        // Set before the read, so a failure answer is no more cacheable than a
+        // successful one: the contract is on the route, not on the happy path.
+        res.setHeader('Cache-Control', 'no-store');
+        try {
+            res.json(composeAgentInstructions(await readPreamble()));
+        }
+        catch (err) {
+            log.error('reading mcp-description.md failed:', { err });
+            res.status(500).json({ error: 'Failed to read the agent instructions' });
+        }
+    });
+    return router;
+}
+//# sourceMappingURL=agent-instructions.routes.js.map

package/dist/modules/agent-instructions/agent-instructions.routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-instructions.routes.js","sourceRoot":"","sources":["../../../src/modules/agent-instructions/agent-instructions.routes.ts"],"names":[],"mappings":"AAAA,OAAO,OAAgC,MAAM,SAAS,CAAC;AACvD,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEjD,MAAM,GAAG,GAAG,MAAM,CAAC,oBAAoB,CAAC,CAAC;AACzC,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAGxD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,6BAA6B,CAAC,UAA0B,EAAE,YAAiC;IACzG,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAEhC,MAAM,CAAC,GAAG,CAAC,qBAAqB,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QAChE,uEAAuE;QACvE,uEAAuE;QACvE,GAAG,CAAC,SAAS,CAAC,eAAe,EAAE,UAAU,CAAC,CAAC;QAC3C,IAAI,CAAC;YACH,GAAG,CAAC,IAAI,CAAC,wBAAwB,CAAC,MAAM,YAAY,EAAE,CAAC,CAAC,CAAC;QAC3D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,GAAG,CAAC,KAAK,CAAC,oCAAoC,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;YACzD,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,uCAAuC,EAAE,CAAC,CAAC;QAC3E,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/modules/agent-instructions/compose.d.ts

@@ -0,0 +1,71 @@
+/**
+ * What a connected agent is told at the start of an MCP session, composed
+ * from two layers: a platform header the code owns, and the deployment
+ * preamble an admin writes in `mcp-description.md` at the repository root.
+ *
+ * Two channels carry the result. The full text goes out as `instructions` on
+ * the initialize handshake, which Claude Code, Claude Desktop and Cursor place
+ * in the model's system prompt. claude.ai on the web, the Agent SDK and Cline
+ * drop that field, so a short prefix is also prepended to the descriptions of
+ * the four knowledge-base tools (the one pre-call channel every client shows
+ * the model). Both are capped, because both land in every conversation.
+ *
+ * Pure: no IO, no clock. The reader beside it (`read-preamble.ts`) does the
+ * file access; the hosted proxy, the agent-facing route and the local bridge
+ * all read this one composer's output.
+ */
+import { PREAMBLE_CAP, PREAMBLE_FILE, TOOL_PREFIX_CAP } from '@bevel-software/platform-shared';
+export { PREAMBLE_CAP, PREAMBLE_FILE, TOOL_PREFIX_CAP };
+/** The tools whose descriptions carry the prefix. Every other tool is untouched. */
+export declare const PREFIXED_TOOLS: ReadonlySet<string>;
+/**
+ * The platform header, owned by the code. What Hexis is, that its content is
+ * not in the model's training data, the order in which to search it, and that
+ * skills are reachable as prompts and through the two skill tools.
+ */
+export declare const PLATFORM_HEADER: string;
+/**
+ * The fixed first line of the tool prefix. It always leads, so an admin's
+ * first edit never removes the instruction from the clients that only see
+ * tool descriptions, and a preamble that opens with a heading still yields a
+ * sensible purpose line.
+ */
+export declare const TOOL_PREFIX_LINE = "This organisation's knowledge base. Search it before answering from memory.";
+/** The one-line marker that replaces everything past the preamble cap. */
+export declare const PREAMBLE_TRUNCATION_MARKER: string;
+export interface ComposedAgentInstructions {
+    /** The header, then the preamble body when there is one. Sent on the initialize handshake. */
+    instructions: string;
+    /** The platform header alone, so a card can show the fixed part apart from the admin's. */
+    header: string;
+    /** The preamble body as sent (cut and marked when over the cap); empty when there is none. */
+    preamble: string;
+    /** The fixed first line of the prefix, so a card can show which part of it the admin owns. */
+    toolPrefixLine: string;
+    /** The fixed line, then the preamble's first non-heading paragraph. Prepended to the four tools' descriptions. */
+    toolPrefix: string;
+    /** The preamble exceeded {@link PREAMBLE_CAP} and was cut, marker appended. */
+    truncated: boolean;
+    /** Length of the stripped preamble BEFORE the cut, so a card can show `N / 6,000`. */
+    preambleChars: number;
+    /** The prefix exceeded {@link TOOL_PREFIX_CAP} and was cut. */
+    toolPrefixTruncated: boolean;
+    /** Length of the prefix BEFORE the cut, so a card can show `N / 300`. */
+    toolPrefixChars: number;
+    /** The file has a `<!--` with no `-->`: everything from it to the end was withheld. */
+    unterminatedComment: boolean;
+}
+/**
+ * Compose the two texts from the raw file content (`null` when the file is
+ * absent). HTML comments are private notes and never leave the file; an
+ * unterminated `<!--` strips everything after it, so the most likely editing
+ * slip withholds text rather than leaking it.
+ */
+export declare function composeAgentInstructions(preamble: string | null): ComposedAgentInstructions;
+/**
+ * A tool description with the prefix ahead of it: the prefix, a blank line,
+ * then the original. Purpose line first, because claude.ai cuts descriptions
+ * near 500 characters.
+ */
+export declare function prefixToolDescription(toolPrefix: string, description: string | undefined): string;
+//# sourceMappingURL=compose.d.ts.map

package/dist/modules/agent-instructions/compose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../../../src/modules/agent-instructions/compose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,OAAO,EACL,YAAY,EACZ,aAAa,EACb,eAAe,EAEhB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,CAAC;AAExD,oFAAoF;AACpF,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,MAAM,CAAiE,CAAC;AAEjH;;;;GAIG;AACH,eAAO,MAAM,eAAe,QAMkD,CAAC;AAE/E;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,gFAAgF,CAAC;AAE9G,0EAA0E;AAC1E,eAAO,MAAM,0BAA0B,QAAyG,CAAC;AAEjJ,MAAM,WAAW,yBAAyB;IACxC,8FAA8F;IAC9F,YAAY,EAAE,MAAM,CAAC;IACrB,2FAA2F;IAC3F,MAAM,EAAE,MAAM,CAAC;IACf,8FAA8F;IAC9F,QAAQ,EAAE,MAAM,CAAC;IACjB,8FAA8F;IAC9F,cAAc,EAAE,MAAM,CAAC;IACvB,kHAAkH;IAClH,UAAU,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,SAAS,EAAE,OAAO,CAAC;IACnB,sFAAsF;IACtF,aAAa,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,mBAAmB,EAAE,OAAO,CAAC;IAC7B,yEAAyE;IACzE,eAAe,EAAE,MAAM,CAAC;IACxB,uFAAuF;IACvF,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,yBAAyB,CA8B3F;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAEjG"}