@bevel-software/platform-core-backend 0.9.1 → 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.9.1",
+  "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",
@@ -34,7 +34,7 @@
     "@utcp/code-mode": "^1.2.12",
     "@utcp/direct-call": "^1.1.1",
     "@utcp/http": "^1.1.7",
-    "@utcp/mcp": "^1.1.3",
+    "@utcp/mcp": "^1.1.4",
     "@utcp/sdk": "^1.1.1",
     "adm-zip": "^0.6.0",
     "cors": "^2.8.5",
@@ -46,8 +46,8 @@
     "pg": "^8.20.0",
     "yaml": "^2.9.0",
     "zod": "^3.24.0",
-    "@bevel-software/platform-mcp-core": "0.9.1",
-    "@bevel-software/platform-shared": "0.9.1"
+    "@bevel-software/platform-mcp-core": "0.11.0",
+    "@bevel-software/platform-shared": "0.11.0"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.8",

package/src/__tests__/core-config.domain.test.ts

@@ -0,0 +1,92 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { CoreConfig } from '../core-config.js';
+
+/**
+ * The public-shape derivation from `DOMAIN`.
+ *
+ * Setting `DOMAIN` declares "the bundled Caddy `https` profile fronts this
+ * deployment": one proxy hop, origins = the domain. The config derives
+ * `PUBLIC_BACKEND_URL` / `PUBLIC_FRONTEND_URL` (`https://<DOMAIN>`) and
+ * `TRUST_PROXY` (`1`) from it — but only as DEFAULTS: an explicit value for
+ * any of the three always wins, so a CDN in front of Caddy or a frontend
+ * served elsewhere stays expressible.
+ */
+const REQUIRED = {
+  KB_REPO_URL: 'https://example.com/org/kb.git',
+  ADMIN_EMAIL: 'root@example.com',
+  ADMIN_PASSWORD: 'sup3r-secret',
+  JWT_SECRET: 'test-jwt-secret',
+  SECRETS_ENC_KEY: 'kToAi8FXWDpDn3A6yQ/60O39bv05N7XzVOIu/0CJrFc=',
+};
+
+let saved: NodeJS.ProcessEnv;
+
+beforeEach(() => {
+  saved = { ...process.env };
+  // A clean slate for the keys under test (a developer .env loaded by
+  // dotenv at import time may carry any of them).
+  for (const key of [
+    'DOMAIN',
+    'PUBLIC_BACKEND_URL',
+    'PUBLIC_FRONTEND_URL',
+    'TRUST_PROXY',
+    'NODE_ENV',
+    'PORT',
+  ]) {
+    delete process.env[key];
+  }
+  Object.assign(process.env, REQUIRED);
+});
+
+afterEach(() => {
+  process.env = saved;
+});
+
+describe('CoreConfig — DOMAIN derives the public shape', () => {
+  it('DOMAIN alone yields https origins and one proxy hop', () => {
+    process.env.DOMAIN = 'bevel.example.com';
+    const config = new CoreConfig();
+    expect(config.publicBackendUrl).toBe('https://bevel.example.com');
+    expect(config.publicFrontendUrl).toBe('https://bevel.example.com');
+    expect(config.trustProxy).toBe('1');
+  });
+
+  it('explicit PUBLIC_* and TRUST_PROXY always win over DOMAIN', () => {
+    // The CDN-in-front-of-Caddy shape: two hops, and a frontend served from
+    // somewhere the bundled proxy is not.
+    process.env.DOMAIN = 'bevel.example.com';
+    process.env.PUBLIC_BACKEND_URL = 'https://api.example.com';
+    process.env.PUBLIC_FRONTEND_URL = 'https://app.example.com';
+    process.env.TRUST_PROXY = '2';
+    const config = new CoreConfig();
+    expect(config.publicBackendUrl).toBe('https://api.example.com');
+    expect(config.publicFrontendUrl).toBe('https://app.example.com');
+    expect(config.trustProxy).toBe('2');
+  });
+
+  it('without DOMAIN the defaults are unchanged (dev shape)', () => {
+    const config = new CoreConfig();
+    expect(config.publicBackendUrl).toBe('http://localhost:3001');
+    expect(config.publicFrontendUrl).toBe('http://localhost:5173');
+    // Unset means "directly exposed": forwarded headers stay ignored.
+    expect(config.trustProxy).toBe('');
+  });
+
+  it('without DOMAIN in production, the frontend origin is the backend origin', () => {
+    // The backend serves the built SPA — under docker compose (which sets
+    // NODE_ENV=production and no PUBLIC_* by default) this is what keeps a
+    // bare `up -d` bouncing logins back to the container's own origin.
+    process.env.NODE_ENV = 'production';
+    const config = new CoreConfig();
+    expect(config.publicBackendUrl).toBe('http://localhost:3001');
+    expect(config.publicFrontendUrl).toBe('http://localhost:3001');
+    expect(config.trustProxy).toBe('');
+  });
+
+  it('an explicit production backend origin carries over to the frontend default', () => {
+    process.env.NODE_ENV = 'production';
+    process.env.PUBLIC_BACKEND_URL = 'https://bevel.example.com';
+    const config = new CoreConfig();
+    expect(config.publicFrontendUrl).toBe('https://bevel.example.com');
+  });
+});

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

@@ -28,6 +28,8 @@ 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';
 import { DEFAULT_BRANCH, PROTECTED_BRANCHES, type AuthUser } from '@bevel-software/platform-shared';
@@ -265,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,
@@ -426,6 +433,20 @@ 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(
+    '/api',
+    core.authMiddleware,
+    createUpdateCheckRoutes(core.updateCheckService, core.adminAccess),
+  );
   // Account management (list/create password accounts, GDPR erasure) —
   // admin-gated inside.
   app.use('/api', core.authMiddleware, createAccountRoutes(

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,
@@ -82,6 +89,8 @@ import { ToolRegistry } from '../modules/tool-registry/tool-registry.js';
 import { createToolContextResolver } from '../modules/tool-helpers/tool-context.js';
 import { createToolHandlerFactory } from '../modules/tool-helpers/tool-handler.js';
 import { TokenCrypto } from '../shared/token-crypto.js';
+import { UpdateCheckService } from '../modules/update-check/update-check.service.js';
+import { resolveAppVersion } from '../version.js';
 import { noopRecoveryAgent, type CorePorts } from './core-ports.js';
 
 /**
@@ -131,6 +140,22 @@ 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. */
   settings: DeploymentSettingsService;
   /**
@@ -147,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>;
@@ -499,6 +530,15 @@ export async function createCoreServices(
     [config.adminEmail],
   );
 
+  // In-app update check: lazily compares the running release version against
+  // the newest published GitHub release, only when an admin's browser asks —
+  // no timers, so a deployment nobody looks at makes zero calls. The flag
+  // removes even that (air-gapped deployments; see CoreConfig).
+  const updateCheckService = new UpdateCheckService({
+    enabled: config.updateCheckEnabled,
+    currentVersion: resolveAppVersion(),
+  });
+
   // Secrets Vault: the per-user store of credentials (static API keys + OAuth
   // tokens) that back UTCP tool variables (`${FOO_API_KEY}`). Encrypted at rest
   // with the connector-config key; read only by the `bevel-secrets` variable
@@ -614,6 +654,7 @@ export async function createCoreServices(
     externalApiKeyService,
     mcpOAuthProvider,
     mcpResourceMetadataUrl,
+    internalTokenService,
   );
 
   // ── Unified tool surface ──────────────────────────────────────────────
@@ -712,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,
@@ -746,12 +824,16 @@ export async function createCoreServices(
     pendingCommitsWorker,
     recoveryBot,
     adminAccess,
+    groupsAdminService,
+    createSyncedGroupsMaterializer,
+    updateCheckService,
     secretsVaultService,
     externalApiKeyService,
     internalTokenService,
     mcpService,
     mcpAuthMiddleware,
     mcpOAuthProvider,
+    mcpResourceMetadataUrl,
     toolRegistry,
     toolAuthMiddleware,
     manualAuthMiddleware,

package/src/core-config.ts

@@ -144,6 +144,16 @@ export class CoreConfig {
    * `session-ontology.gate.ts`), so it must exist wherever the tracking runs.
    */
   readonly ontologySessionBlock: boolean;
+  /**
+   * In-app update check. When true (default), `GET /api/update-check` lazily
+   * asks api.github.com for the newest Hexis release — only when an admin's
+   * browser asks, cached for hours, never on a timer — so admins see a quiet
+   * banner when this deployment is behind. The request carries nothing but
+   * the request itself: no token, no identifier, no telemetry. Set
+   * `UPDATE_CHECK=false` for air-gapped deployments or anyone who objects to
+   * the phone-home; disabled, the server never makes the call.
+   */
+  readonly updateCheckEnabled: boolean;
   /**
    * Password-login toggle for the login screen. Default enabled; set
    * `LOGIN_PASSWORD=false` to hide the method AND reject `/auth/login`
@@ -203,14 +213,22 @@ export class CoreConfig {
    * but behind a proxy it makes every client share the proxy's IP (so the
    * per-IP login rate limit would pool all users). Set it to the actual hop
    * count — never a blanket trust — so clients can't spoof X-Forwarded-For.
+   * With `DOMAIN` set (the bundled Caddy fronts the deployment) it defaults
+   * to `1` instead — see the derivation in the constructor.
    */
   readonly trustProxy: string;
   /**
    * Public base URL of THIS backend, used to build OAuth redirect URIs.
    * Must match a redirect URI registered with the OAuth provider(s).
+   * Defaults to `https://<DOMAIN>` when `DOMAIN` is set.
    */
   readonly publicBackendUrl: string;
-  /** Public base URL of the frontend, where callbacks redirect post-login. */
+  /**
+   * Public base URL of the frontend, where callbacks redirect post-login.
+   * Defaults to `https://<DOMAIN>` when `DOMAIN` is set, else to the backend
+   * origin in production (the backend serves the SPA) and Vite's `:5173` in
+   * development.
+   */
   readonly publicFrontendUrl: string;
 
   constructor() {
@@ -304,6 +322,8 @@ export class CoreConfig {
     this.kbTemplateDir = process.env.KB_TEMPLATE_DIR || defaultKbTemplateDir();
     this.ontologySessionBlock =
       (process.env.ONTOLOGY_SESSION_BLOCK ?? 'true').trim().toLowerCase() !== 'false';
+    this.updateCheckEnabled =
+      (process.env.UPDATE_CHECK ?? 'true').trim().toLowerCase() !== 'false';
     this.allowedEmailDomains = (process.env.ALLOWED_EMAIL_DOMAINS || '')
       .split(/[\s,]+/)
       .map((d) => d.trim().toLowerCase().replace(/^[@.]+/, ''))
@@ -322,11 +342,35 @@ export class CoreConfig {
       );
     }
     this.internalTokenSecret = (process.env.INTERNAL_TOKEN_SECRET || '').trim();
-    this.trustProxy = (process.env.TRUST_PROXY || '').trim();
-    this.publicBackendUrl = (process.env.PUBLIC_BACKEND_URL || `http://localhost:${this.port}`)
+    // Setting DOMAIN declares "the bundled Caddy `https` profile fronts this
+    // deployment" — one proxy hop, and the public origin IS that domain. The
+    // three values below therefore default from it, so `DOMAIN=x.example.com`
+    // in `.env` is the whole configuration for that shape: TRUST_PROXY falls
+    // to 1 (Caddy is the hop) and both public URLs to `https://<DOMAIN>` (the
+    // backend serves the SPA, so they share an origin). Explicit
+    // PUBLIC_BACKEND_URL / PUBLIC_FRONTEND_URL / TRUST_PROXY always win — a
+    // CDN in front of Caddy (TRUST_PROXY=2) or a frontend served elsewhere
+    // stays expressible.
+    const domain = (process.env.DOMAIN || '').trim();
+    this.trustProxy = (process.env.TRUST_PROXY || (domain ? '1' : '')).trim();
+    this.publicBackendUrl = (
+      process.env.PUBLIC_BACKEND_URL ||
+      (domain ? `https://${domain}` : `http://localhost:${this.port}`)
+    )
       .trim()
       .replace(/\/+$/, '');
-    this.publicFrontendUrl = (process.env.PUBLIC_FRONTEND_URL || 'http://localhost:5173')
+    // Unset, the frontend origin is the backend's own in production (the
+    // backend serves the built SPA — under docker compose this is what makes
+    // a bare `up -d` bounce logins back to the right place), and Vite's dev
+    // server in development.
+    this.publicFrontendUrl = (
+      process.env.PUBLIC_FRONTEND_URL ||
+      (domain
+        ? `https://${domain}`
+        : this.nodeEnv === 'production'
+          ? this.publicBackendUrl
+          : 'http://localhost:5173')
+    )
       .trim()
       .replace(/\/+$/, '');
     // Parse-validate so a malformed URL fails at boot rather than producing a

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 () => {