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

package/migrations/meta/_journal.json

@@ -29,6 +29,13 @@
       "when": 1785943322636,
       "tag": "0003_deployment_settings",
       "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1787191920033,
+      "tag": "0004_file_lock_mode",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-core-backend",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Open-source core backend of the Bevel platform: git-backed knowledge workspace, workflow (branches/change requests/locks/SSE), skills, tools, secrets vault, access control and the remote MCP surface.",
   "type": "module",
   "main": "./dist/index.js",
@@ -46,8 +46,8 @@
     "pg": "^8.20.0",
     "yaml": "^2.9.0",
     "zod": "^3.24.0",
-    "@bevel-software/platform-mcp-core": "0.10.0",
-    "@bevel-software/platform-shared": "0.10.0"
+    "@bevel-software/platform-mcp-core": "0.11.0",
+    "@bevel-software/platform-shared": "0.11.0"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.8",

package/src/core/create-core-server.ts

@@ -28,6 +28,7 @@ import {
   createSecretsVaultPublicRoutes,
 } from '../modules/secrets-vault/index.js';
 import { createAdminAccessRoutes } from '../modules/admin/admin-access.routes.js';
+import { createGroupsAdminRoutes } from '../modules/access/groups-admin.routes.js';
 import { createUpdateCheckRoutes } from '../modules/update-check/update-check.routes.js';
 import { createAccountRoutes } from '../modules/auth/account.routes.js';
 import { createSetupRoutes } from '../modules/settings/setup.routes.js';
@@ -266,6 +267,11 @@ export async function createCoreServer(
     core.mcpAuthMiddleware,
     core.authMiddleware,
     core.usageMeter,
+    // The local-token exchange: verifies an MCP OAuth access token and mints
+    // the loopback internal token the local MCP server uses for its REST reads.
+    core.internalTokenService,
+    core.mcpOAuthProvider,
+    core.mcpResourceMetadataUrl,
   ));
 
   // MCP OAuth 2.1 authorization server: /authorize, /token, /register,
@@ -427,6 +433,13 @@ export async function createCoreServer(
   // Admin-status resolver (CORE — see the note in admin-access.routes.ts;
   // the full admin router is an enterprise `ext.authed` extension).
   app.use('/api', core.authMiddleware, createAdminAccessRoutes(core.adminAccess));
+  // Groups admin (manual-mode CRUD; typed refusals in IdP mode) —
+  // admin-gated inside.
+  app.use('/api', core.authMiddleware, createGroupsAdminRoutes({
+    groupsAdmin: core.groupsAdminService,
+    adminAccess: core.adminAccess,
+    getUserById: async (id) => (await core.authService.getUserById(id)) ?? null,
+  }));
   // Update check (admin-only inside): the newest published release vs the
   // running version, cached server-side — see update-check.service.ts.
   app.use(

package/src/core/create-core-services.ts

@@ -35,6 +35,7 @@ import { OidcAuthProvider } from '../modules/auth/oidc-auth-provider.js';
 import { createAuthMiddleware } from '../modules/auth/auth.middleware.js';
 import { AccessControlService } from '../modules/access/access-control.service.js';
 import { CreatorAccessService } from '../modules/access/creator-access.js';
+import { GroupsAdminService } from '../modules/access/groups-admin.service.js';
 import { PendingSkillsService, SkillService } from '../modules/skills/index.js';
 import { ToolManualService } from '../modules/tool-manuals/index.js';
 import { McpServerEditService } from '../modules/tool-manuals/mcp-server-edit.service.js';
@@ -63,6 +64,12 @@ import {
 } from '../modules/workflow/pending-commits.worker.js';
 import { ensureRecoveryBotUser } from '../modules/workflow/recovery-bot.js';
 import { AdminAccessService } from '../modules/admin/admin-access.service.js';
+import {
+  SyncedGroupsWriter,
+  type SyncedGroupsSource,
+} from '../modules/access/synced-groups-writer.js';
+import { createSyncedGroupsCommitter } from '../modules/access/synced-groups-committer.js';
+import { ensureDirectorySyncBot } from '../modules/access/directory-sync-bot.js';
 import { ExternalApiKeyService } from '../modules/tool-auth/external-api-key.service.js';
 import {
   InternalTokenService,
@@ -133,6 +140,20 @@ export interface CoreServices {
   pendingCommitsWorker: PendingCommitsWorker;
   recoveryBot: AuthUser;
   adminAccess: AdminAccessService;
+  /** Manual-mode groups CRUD + the manual→IdP retirement half. */
+  groupsAdminService: GroupsAdminService;
+  /**
+   * Build the debounced directory → `synced-groups.yaml` materializer for a
+   * directory source an OVERLAY provides (e.g. a SCIM mirror fed by the IdP's
+   * provisioning engine — core ships no directory integration of its own).
+   * Ensures the directory-sync bot user and closes over the git commit
+   * pipeline; the overlay only implements {@link SyncedGroupsSource} and
+   * calls `notifyMutation()` after each directory change.
+   */
+  createSyncedGroupsMaterializer: (
+    source: SyncedGroupsSource,
+    opts?: { debounceMs?: number; log?: (message: string) => void },
+  ) => Promise<SyncedGroupsWriter>;
   /** Newest-release lookup behind `GET /api/update-check` (admin-only). */
   updateCheckService: UpdateCheckService;
   /** Deployment settings, env-first — the KB remote resolves through these. */
@@ -151,6 +172,12 @@ export interface CoreServices {
   mcpService: McpService;
   mcpAuthMiddleware: ReturnType<typeof createMcpAuthMiddleware>;
   mcpOAuthProvider: BevelOAuthProvider;
+  /**
+   * RFC 9728 protected-resource-metadata URL carried on MCP 401 challenges.
+   * Published so the route layer's own challenges (the local-token exchange)
+   * advertise the same pointer the auth middleware does.
+   */
+  mcpResourceMetadataUrl: string;
   toolRegistry: ToolRegistry;
   toolAuthMiddleware: ReturnType<typeof createToolAuthMiddleware>;
   manualAuthMiddleware: ReturnType<typeof createManualAuthMiddleware>;
@@ -627,6 +654,7 @@ export async function createCoreServices(
     externalApiKeyService,
     mcpOAuthProvider,
     mcpResourceMetadataUrl,
+    internalTokenService,
   );
 
   // ── Unified tool surface ──────────────────────────────────────────────
@@ -725,6 +753,43 @@ export async function createCoreServices(
     );
   }
 
+  // Materializer factory for an overlay-provided directory source: every
+  // provisioning burst regenerates `synced-groups.yaml` on the default branch
+  // (debounced), committed by the sync bot — that file is what puts access
+  // resolution in IdP mode. Core itself ships no directory integration, so
+  // nothing is constructed here until an overlay brings a source.
+  const createSyncedGroupsMaterializer = async (
+    source: SyncedGroupsSource,
+    opts?: { debounceMs?: number; log?: (message: string) => void },
+  ): Promise<SyncedGroupsWriter> => {
+    const bot = await ensureDirectorySyncBot(db);
+    return new SyncedGroupsWriter({
+      source,
+      ...createSyncedGroupsCommitter({
+        workspaceService,
+        workflowService,
+        accessControl,
+        eventBus,
+        kbDirName,
+        bot,
+        defaultBranchOf: () => DEFAULT_BRANCH,
+      }),
+      debounceMs: opts?.debounceMs,
+      log: opts?.log ?? ((message) => console.warn(message)),
+    });
+  };
+  // Groups — the "who you are" principal sets. Manual-mode CRUD on
+  // groups.yaml, IdP-mode refusals, and the connect-time retirement the
+  // directory token route drives.
+  const groupsAdminService = new GroupsAdminService(
+    workspaceService,
+    workflowService,
+    accessControl,
+    kbDirName,
+    () => DEFAULT_BRANCH,
+    eventBus,
+  );
+
   return {
     config,
     db,
@@ -759,6 +824,8 @@ export async function createCoreServices(
     pendingCommitsWorker,
     recoveryBot,
     adminAccess,
+    groupsAdminService,
+    createSyncedGroupsMaterializer,
     updateCheckService,
     secretsVaultService,
     externalApiKeyService,
@@ -766,6 +833,7 @@ export async function createCoreServices(
     mcpService,
     mcpAuthMiddleware,
     mcpOAuthProvider,
+    mcpResourceMetadataUrl,
     toolRegistry,
     toolAuthMiddleware,
     manualAuthMiddleware,

package/src/index.ts

@@ -52,6 +52,16 @@ export type {
 } from './modules/tool-auth/external-api-key.interface.js';
 
 // Key port/seam types an overlay implements.
+// SyncedGroupsWriter is a CLASS — exported by VALUE so an overlay can
+// construct one; the seam types (including the writer's deps) stay type-only.
+export { SyncedGroupsWriter } from './modules/access/synced-groups-writer.js';
+export type {
+  SyncedGroupsSource,
+  SyncedGroupRecord,
+  SyncedGroupMember,
+  SyncedGroupsWriteResult,
+  SyncedGroupsWriterDeps,
+} from './modules/access/synced-groups-writer.js';
 export type { ISessionSink } from './modules/workspace/session-sink.js';
 export type {
   ISystemNoticeSink,

package/src/modules/access/__tests__/access-control.service.test.ts

@@ -283,6 +283,12 @@ describe('AccessControlService', () => {
     const e = await svc.eligibleWriters(workspaceId, 'Knowledge/Foo.md');
     expect(e.roles).toEqual(['Admin']);
     expect(e.users.map((u) => u.email)).toEqual(['felix@example.com']);
+    // The kinded twin of `roles`: a roles.yaml principal reads kind 'role'.
+    expect(e.principals).toEqual([{ name: 'Admin', kind: 'role' }]);
+    // The Admin-override insertion (write on an access.md is admin-rescued)
+    // also carries kind 'role' — it is the role's capability, never a group's.
+    const onAccessMd = await svc.eligibleWriters(workspaceId, 'access.md');
+    expect(onAccessMd.principals).toContainEqual({ name: 'Admin', kind: 'role' });
   });
 
   it('throws AccessConfigError when roles.yaml is missing', async () => {
@@ -947,7 +953,7 @@ describe('AccessControlService', () => {
 
         const svc = new AccessControlService(stubWorkspaceService(workspaceId, workspaceDir), PROCESS_MAP_DIR);
         const e = await svc.eligibleReaders(workspaceId, 'Knowledge/Foo.md');
-        expect(e).toEqual({ restricted: true, roles: [], users: [] });
+        expect(e).toEqual({ restricted: true, principals: [], roles: [], users: [] });
       });
 
       it('reports restricted=false when read: everyone applies', async () => {
@@ -957,7 +963,7 @@ describe('AccessControlService', () => {
 
         const svc = new AccessControlService(stubWorkspaceService(workspaceId, workspaceDir), PROCESS_MAP_DIR);
         const e = await svc.eligibleReaders(workspaceId, 'Knowledge/Foo.md');
-        expect(e).toEqual({ restricted: false, roles: [], users: [] });
+        expect(e).toEqual({ restricted: false, principals: [], roles: [], users: [] });
       });
 
       it('restricted=false when a closer everyone grant shadows a farther by-name deny', async () => {
@@ -972,7 +978,7 @@ describe('AccessControlService', () => {
         // node really is readable by everyone — not restricted.
         expect(await svc.canRead(workspaceId, 'felix@example.com', 'Knowledge/Open/Foo.md')).toBe(true);
         const e = await svc.eligibleReaders(workspaceId, 'Knowledge/Open/Foo.md');
-        expect(e).toEqual({ restricted: false, roles: [], users: [] });
+        expect(e).toEqual({ restricted: false, principals: [], roles: [], users: [] });
       });
 
       it('restricted=true when a same-scope by-name deny carves someone out of read: everyone', async () => {