@bevel-software/platform-core-backend 0.14.0 → 0.19.0

package/src/modules/access-model/group-files.ts

@@ -2,6 +2,7 @@ import {
   EMAIL_REGEX,
   GROUP_REF_PREFIX,
   RESERVED_ROLE_NAMES,
+  PLUGIN_TOKEN_PREFIX,
   ROLE_TOKEN_PREFIX,
   canonicalEmail,
   canonicalRoleName,
@@ -68,6 +69,9 @@ export function unsafeNameReason(displayName: string): string | null {
   if (canonicalRoleName(trimmed).startsWith(ROLE_TOKEN_PREFIX)) {
     return `starts with the reserved '${ROLE_TOKEN_PREFIX}' prefix (the explicit role token in access entries)`;
   }
+  if (canonicalRoleName(trimmed).startsWith(PLUGIN_TOKEN_PREFIX)) {
+    return `starts with the reserved '${PLUGIN_TOKEN_PREFIX}' prefix (the plugin-principal token in access entries)`;
+  }
   return null;
 }
 

package/src/modules/access-model/plugin-principals.ts

@@ -0,0 +1,130 @@
+import { comparePathComponents } from '../../shared/path-order.js';
+import {
+  EVERYONE_CANONICAL,
+  PLUGIN_TOKEN_PREFIX,
+  PLUGIN_TOKEN_VERBS,
+  pluginPrincipalKey,
+  sourceVerbsFor,
+  type AccessFile,
+  type PluginTokenVerb,
+  type RolesIndex,
+} from './access-grammar.js';
+
+/**
+ * Plugin principals — `plugin/<Name>/<verb>` — synthesised into the principal
+ * index from each plugin folder's own `access.md`, so a grant naming one
+ * resolves exactly like a group grant: the resolver sees a named principal
+ * with member emails and needs no plugin awareness at all.
+ *
+ * WHAT A PLUGIN'S ROSTER IS: the folder-governing rules of
+ * `Plugins/<Name>/access.md` — the file provisioning seeds and the join flow
+ * edits. Three principals per plugin, folded by the resolver's own
+ * `sourceVerbsFor` table — the ONE place the nesting is written down, so a
+ * roster can never drift from what resolution itself grants (`write` and
+ * `download` each imply `read`; `owner` implies all three):
+ *
+ *   plugin/<slug>/read    everyone under read, write, download or owner
+ *   plugin/<slug>/write   everyone under write or owner
+ *   plugin/<slug>/owner   everyone under owner
+ *
+ * The `<slug>` is the manifest slug of the folder (`pluginManifestName`), the
+ * identity `parseAccessEntry` canonicalises a hand-written token to.
+ *
+ * Deliberately NOT membership:
+ *   - the file's frontmatter (`read: everyone` there is DISCOVERABILITY of
+ *     the access.md itself, not membership) — `AccessFile.entries` already
+ *     holds only the folder block;
+ *   - rules inherited from above the plugin folder (the repo root's
+ *     `write: Admin`) — admins reach the skill through those same rules
+ *     anyway, and the roster should be what the plugin's page shows;
+ *   - `deny` entries — a denial subtracts nothing here; a plugin that wants
+ *     someone out removes the grant;
+ *   - other plugin tokens inside a plugin's rules — skipped, so synthesis is
+ *     one pass with no recursion and no cycle to detect.
+ *
+ * `everyone` in a plugin's own rules makes the corresponding principal
+ * PUBLIC: no email list can enumerate it, so its key is recorded in
+ * `index.publicKeys` and the resolver unions those into every caller's set.
+ *
+ * Runs AFTER groups are merged (so role and group entries expand through the
+ * finished index) and BEFORE unknown-role validation (so plugin tokens in
+ * access files count as known).
+ */
+export function synthesizePluginPrincipals(
+  index: RolesIndex,
+  accessFiles: ReadonlyMap<string, AccessFile>,
+  /**
+   * The repo-relative folders that ARE plugins — the ones carrying a
+   * `plugin.json` — each with its IDENTITY (the manifest's name, or the
+   * folder folded into one), as the model loader read them. A plugin is a
+   * folder with a manifest, at any depth; its access.md is its roster.
+   * Nothing else's is.
+   */
+  pluginDirs: ReadonlyMap<string, string>,
+): void {
+  const claimed = new Set<string>();
+  // The same path order discovery walks in, so "first by path" is the same
+  // plugin in both places — see `comparePathComponents`.
+  for (const [dir, slug] of [...pluginDirs].sort(([a], [b]) => comparePathComponents(a, b))) {
+    // Two plugins with one name: discovery keeps the first by path, so do we —
+    // and the claim is made BEFORE looking for a roster, or a first plugin
+    // without rules would leave its slug to a later twin's roster.
+    if (claimed.has(slug)) continue;
+    claimed.add(slug);
+    const file = accessFiles.get(dir);
+    if (!file) continue; // a plugin without rules has no roster
+    for (const verb of PLUGIN_TOKEN_VERBS) {
+      const { emails, everyone, sourceKeys } = holdersOf(index, file, verb);
+      const key = pluginPrincipalKey(slug, verb);
+      index.byCanonical.set(key, {
+        displayName: key,
+        emails,
+        kind: 'plugin',
+        pluginName: slug,
+        pluginDir: dir,
+        sourceKeys,
+      });
+      for (const email of emails) {
+        let set = index.byEmail.get(email);
+        if (!set) {
+          set = new Set();
+          index.byEmail.set(email, set);
+        }
+        set.add(key);
+      }
+      if (everyone) {
+        index.publicKeys ??= new Set();
+        index.publicKeys.add(key);
+      }
+    }
+  }
+}
+
+function holdersOf(
+  index: RolesIndex,
+  file: AccessFile,
+  verb: PluginTokenVerb,
+): { emails: Set<string>; everyone: boolean; sourceKeys: Set<string> } {
+  const emails = new Set<string>();
+  const sourceKeys = new Set<string>();
+  let everyone = false;
+  for (const source of sourceVerbsFor(verb)) {
+    for (const entry of file.entries[source]) {
+      if (entry.deny) continue;
+      if (entry.kind === 'user') {
+        emails.add(entry.email);
+        continue;
+      }
+      if (entry.role === EVERYONE_CANONICAL) {
+        everyone = true;
+        continue;
+      }
+      if (entry.role.startsWith(PLUGIN_TOKEN_PREFIX)) continue; // no recursion
+      const record = index.byCanonical.get(entry.role);
+      if (!record) continue; // an unknown role contributes nothing (loadModel warns separately)
+      sourceKeys.add(entry.role);
+      for (const email of record.emails) emails.add(email);
+    }
+  }
+  return { emails, everyone, sourceKeys };
+}

package/src/modules/access-model/roles-yaml-guard.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`)
@@ -22,8 +22,10 @@
  */
 
 import type { FileContent } from '@mastra/core/workspace';
-import { parseRolesYaml } from './access-grammar.js';
+import { GROUP_REF_PREFIX, canonicalRoleName, parseRolesYaml, parseYamlSubset } from './access-grammar.js';
+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 const ROLES_YAML_BASENAME = 'roles.yaml';
@@ -80,10 +82,186 @@ export function assertRolesYamlParsable(content: string): void {
  */
 export function makeRolesYamlWriteValidator(
   kbDirName: string,
-): (path: string, content: FileContent) => void {
-  return (path, content) => {
+): WriteValidator & ((path: string, content: FileContent) => void) {
+  const validate: WriteValidator & ((path: string, content: FileContent) => void) = (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 {
+  readonly roleNames: string[];
+  constructor(roleNames: string[]) {
+    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: string | null): Map<string, string> {
+  const names = new Map<string, string>();
+  if (text === null) return names;
+  const parsed = parseYamlSubset(text);
+  if (!parsed.ok) return names;
+  const roles = (parsed.value as Record<string, unknown> | null)?.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: string | null, candidate: string): void {
+  const existing = declaredRoleNames(current);
+  const created = [...declaredRoleNames(candidate)]
+    .filter(([canonical]) => !existing.has(canonical))
+    .map(([, display]) => display);
+  if (created.length > 0) throw new RolesYamlNewRoleError(created);
+}
+
+/**
+ * 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;
+
+/** One `- group:<Name>` member entry: the role it sits under and the entry as written. */
+interface GroupEntry {
+  role: string;
+  roleCanonical: string;
+  entry: string;
+  group: string;
+}
+
+/**
+ * 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 {
+  readonly entries: { role: string; entry: string }[];
+  constructor(entries: { role: string; entry: string }[], sourceFile: string) {
+    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: string | null): GroupEntry[] {
+  const out: GroupEntry[] = [];
+  if (text === null) return out;
+  const parsed = parseYamlSubset(text);
+  if (!parsed.ok) return out;
+  const roles = (parsed.value as Record<string, unknown> | null)?.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: string | null,
+  candidate: string,
+  active: ActiveGroupsForValidation,
+): void {
+  if (active === null) return;
+  const key = (e: GroupEntry) => `${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: string,
+  readCurrent: () => Promise<string | null>,
+  loadGroups?: () => Promise<ActiveGroupsForValidation>,
+): WriteValidator {
+  const validate: WriteValidator = 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;
 }

package/src/modules/admin/admin-access.service.ts

@@ -1,6 +1,10 @@
 import type { IAccessControl } from '../access/access-control.interface.js';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('admin');
 import { type WorkspaceService } from '../workspace/workspace.service.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import { canonicalEmail } from '../../shared/email-identity.js';
 import type { IAdminAccessService } from './admin.interface.js';
 
 /**
@@ -31,7 +35,7 @@ export class AdminAccessService implements IAdminAccessService {
 
   async isAdmin(email: string | undefined): Promise<boolean> {
     if (!email) return false;
-    const normalized = email.trim().toLowerCase();
+    const normalized = canonicalEmail(email);
     if (this.alwaysAdminEmails.includes(normalized)) return true;
     try {
       // Ensure the authoritative clone is on disk, then resolve Admin-role
@@ -43,7 +47,7 @@ export class AdminAccessService implements IAdminAccessService {
     } 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/src/modules/agent-instructions/__tests__/agent-instructions.route.test.ts

@@ -0,0 +1,100 @@
+import type { Server as HttpServer } from 'node:http';
+import express from 'express';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createManualAuthMiddleware } from '../../tool-auth/tool-auth.middleware.js';
+import type { IExternalApiKeyService } from '../../tool-auth/external-api-key.interface.js';
+import type { InternalTokenService } from '../../tool-auth/internal-token.service.js';
+import type { AuthService } from '../../auth/auth.service.js';
+import { createAgentInstructionsRoutes } from '../agent-instructions.routes.js';
+import { PLATFORM_HEADER, TOOL_PREFIX_LINE } from '../compose.js';
+
+/**
+ * `GET /agent/instructions` behind the REAL manual-auth gate, with the three
+ * credential stores faked at their seams: a connection key, an internal token
+ * and a browser JWT all get in, nothing else does, and the response is the
+ * composer's result with the no-store header. Absence and failure of the file
+ * stay distinguishable: ENOENT is the header alone, anything else is a 500.
+ */
+
+let httpServer: HttpServer | undefined;
+
+const CONNECTION_KEY = 'bevel_abc';
+const INTERNAL_TOKEN = 'bit_xyz';
+const BROWSER_JWT = 'jwt.session.token';
+
+async function serve(readPreamble: () => Promise<string | null>): Promise<string> {
+  const externalKeys = {
+    looksLikeExternalApiKey: (t: string) => t.startsWith('bevel_'),
+    verifyAndLoadToken: async (t: string) => (t === CONNECTION_KEY ? { user: { id: 'u-key' }, tokenId: 'tok-1' } : null),
+  } as unknown as IExternalApiKeyService;
+  const internalTokens = {
+    looksLikeInternalToken: (t: string) => t.startsWith('bit_'),
+    verify: (t: string) => (t === INTERNAL_TOKEN ? { userId: 'u-internal' } : null),
+  } as unknown as InternalTokenService;
+  const authService = {
+    verifyToken: (t: string) => {
+      if (t !== BROWSER_JWT) throw new Error('bad jwt');
+      return { userId: 'u-browser' };
+    },
+  } as unknown as AuthService;
+  const app = express();
+  app.use('/api', createAgentInstructionsRoutes(createManualAuthMiddleware(externalKeys, internalTokens, authService), readPreamble));
+  httpServer = await new Promise<HttpServer>((resolve) => {
+    const s = app.listen(0, () => resolve(s));
+  });
+  return `http://127.0.0.1:${(httpServer.address() as { port: number }).port}/api/agent/instructions`;
+}
+
+afterEach(async () => {
+  if (httpServer) await new Promise<void>((r) => httpServer!.close(() => r()));
+  httpServer = undefined;
+  vi.restoreAllMocks();
+});
+
+describe('GET /agent/instructions', () => {
+  it('answers 200 for a connection key, an internal token and a browser JWT alike', async () => {
+    const url = await serve(async () => 'Acme builds solar farms.\n');
+    for (const bearer of [CONNECTION_KEY, INTERNAL_TOKEN, BROWSER_JWT]) {
+      const res = await fetch(url, { headers: { Authorization: `Bearer ${bearer}` } });
+      expect(res.status, bearer).toBe(200);
+      expect(res.headers.get('cache-control')).toBe('no-store');
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body.instructions).toBe(`${PLATFORM_HEADER}\n\nAcme builds solar farms.`);
+      expect(body.toolPrefix).toBe(`${TOOL_PREFIX_LINE} Acme builds solar farms.`);
+      expect(body).toMatchObject({
+        truncated: false,
+        preambleChars: 'Acme builds solar farms.'.length,
+        toolPrefixTruncated: false,
+        unterminatedComment: false,
+      });
+    }
+  });
+
+  it('answers 401 without a credential, and for an invalid one', async () => {
+    const url = await serve(async () => 'x');
+    expect((await fetch(url)).status).toBe(401);
+    expect((await fetch(url, { headers: { Authorization: 'Bearer bevel_wrong' } })).status).toBe(401);
+    expect((await fetch(url, { headers: { Authorization: 'Bearer not-a-session' } })).status).toBe(401);
+  });
+
+  it('a missing file yields the header alone', async () => {
+    const url = await serve(async () => null);
+    const res = await fetch(url, { headers: { Authorization: `Bearer ${CONNECTION_KEY}` } });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { instructions: string; toolPrefix: string; preambleChars: number };
+    expect(body.instructions).toBe(PLATFORM_HEADER);
+    expect(body.toolPrefix).toBe(TOOL_PREFIX_LINE);
+    expect(body.preambleChars).toBe(0);
+  });
+
+  it('a read error other than ENOENT is a 500, never an empty preamble', async () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    const url = await serve(async () => {
+      throw Object.assign(new Error('disk'), { code: 'EIO' });
+    });
+    const res = await fetch(url, { headers: { Authorization: `Bearer ${CONNECTION_KEY}` } });
+    expect(res.status).toBe(500);
+    // The failure is no more cacheable than a success.
+    expect(res.headers.get('cache-control')).toBe('no-store');
+  });
+});