@bevel-software/platform-core-backend 0.34.0 → 0.36.1

package/src/core/__tests__/oauth-sign-in-real-file.test.ts

@@ -0,0 +1,179 @@
+import type { Server as HttpServer } from 'node:http';
+import { mkdtemp, rm, mkdir, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import express from 'express';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
+import { createSecretsVaultRoutes } from '../../modules/secrets-vault/index.js';
+import { KbPluginSource } from '../../modules/plugins/index.js';
+import type { WorkspaceService } from '../../modules/workspace/index.js';
+import type { IAccessControl } from '../../modules/access/index.js';
+// The two concrete services this suite wires, it wires the way the composition
+// root does (`create-core-services.ts`): their modules publish them as types
+// only, and the composition root is the one place that constructs them from
+// their files. This suite stands in for that root — the routes of one module
+// over the real parser of another — which is why it lives beside it.
+import { ToolManualService } from '../../modules/tool-manuals/tool-manuals.service.js';
+import { realDisk } from '../../__tests__/real-disk.js';
+import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import { testKbContext } from '../../__tests__/kb-context.js';
+
+/**
+ * The sign-in start against REAL tool files: the routes are wired to the real
+ * `ToolManualService` over a workspace on disk, so what the start answers is
+ * what the parser makes of the file, not what a stub says it makes of it.
+ *
+ * The case this exists for (Local Testing, 2026-10-27): a declaration edited to
+ * `tokenUrl: http://127.0.0.1/token` is refused by the parser before the vault
+ * ever validates it — and the start answered "Tool or variable not found"
+ * instead of the validation's message.
+ */
+
+const KB_DIR = 'knowledge-base';
+const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+const USER = 'owner@x.com';
+const AUTHORIZE = 'https://auth.crm.example/authorize';
+const TOKEN = 'https://auth.crm.example/token';
+
+let root: string;
+let httpServer: HttpServer | undefined;
+
+beforeEach(async () => {
+  root = await mkdtemp(join(tmpdir(), 'signin-live-'));
+  await mkdir(join(root, wsId, KB_DIR, 'Plugins', 'GTM'), { recursive: true });
+});
+afterEach(async () => {
+  await new Promise<void>((r) => (httpServer ? httpServer.close(() => r()) : r()));
+  httpServer = undefined;
+  await rm(root, { recursive: true, force: true });
+  vi.restoreAllMocks();
+});
+
+const toolPath = () => join(root, wsId, KB_DIR, 'Plugins', 'crm.tool');
+const writeTool = (oauth: Record<string, unknown>) =>
+  writeFile(
+    toolPath(),
+    JSON.stringify({
+      name: 'crm',
+      type: 'http',
+      url: 'https://api.crm.example/openapi.json',
+      variables: [{ name: 'SIGNIN', scope: 'user', oauth }],
+    }),
+  );
+const writePlugin = (oauth: Record<string, unknown>) =>
+  Promise.all([
+    writeFile(
+      join(root, wsId, KB_DIR, 'Plugins', 'GTM', 'mcp.json'),
+      JSON.stringify({ mcpServers: { hubspot: { type: 'streamable-http', url: 'https://mcp.hubspot.example/mcp' } } }),
+    ),
+    writeFile(
+      join(root, wsId, KB_DIR, 'Plugins', 'GTM', 'plugin.json'),
+      JSON.stringify({
+        name: 'gtm',
+        extensions: {
+          'software.bevel.hexis': {
+            mcpServers: {
+              hubspot: {
+                headers: { Authorization: 'Bearer ${HUBSPOT_TOKEN}' },
+                variables: [{ name: 'HUBSPOT_TOKEN', scope: 'user', oauth }],
+              },
+            },
+          },
+        },
+      }),
+    ),
+  ]);
+
+async function serve() {
+  const disk = realDisk();
+  const kb = testKbContext({ kbDirName: KB_DIR });
+  const accessControl = {
+    canRead: async () => true,
+    canWrite: async () => true,
+    canReadBatch: async (_w: string, _e: string, paths: string[]) => new Map(paths.map((p) => [p, true])),
+  } as unknown as IAccessControl;
+  const workspaceService = {
+    getOrCreateForBranch: async () => ({ id: wsId }),
+    getWorkspacePath: async (id: string) => join(root, id),
+  } as unknown as WorkspaceService;
+  const toolManualService = new ToolManualService(workspaceService, accessControl, kb, disk, new KbPluginSource(disk, kb));
+  toolManualService.setMcpAuthDiscovery({ statusFor: async () => ({ status: 'open' as const }) });
+  const beginToolOAuthByKey = vi.fn(async () => ({ id: 'row-1', url: `${AUTHORIZE}?client_id=x` }));
+  const deps = {
+    secretsVault: { beginToolOAuthByKey },
+    toolManualService,
+    accessControl,
+    connectionProbe: {},
+    kb: { defaultWorkspaceId: () => wsId },
+    stateSecret: 'state-secret',
+    publicBackendUrl: 'http://localhost:3000',
+    publicFrontendUrl: 'http://localhost:5173',
+  } as unknown as Parameters<typeof createSecretsVaultRoutes>[0];
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    req.userId = 'user-1';
+    req.userEmail = USER;
+    next();
+  });
+  app.use('/api', createSecretsVaultRoutes(deps));
+  httpServer = await new Promise<HttpServer>((resolve) => {
+    const s = app.listen(0, () => resolve(s));
+  });
+  const base = `http://127.0.0.1:${(httpServer.address() as { port: number }).port}/api/secrets/tools`;
+  const start = (slug: string, varName: string) => fetch(`${base}/${slug}/vars/${varName}/oauth/start`, { method: 'POST' });
+  return { toolManualService, beginToolOAuthByKey, start };
+}
+
+describe('POST …/oauth/start — through a real tool file', () => {
+  it('a client id edited in the .tool after the catalog was scanned is the one handed to the vault', async () => {
+    await writeTool({ clientId: 'client-A', authorizationUrl: AUTHORIZE, tokenUrl: TOKEN });
+    const s = await serve();
+    await s.toolManualService.listAccessible(USER); // the catalog caches client A
+    await writeTool({ clientId: 'client-B', authorizationUrl: AUTHORIZE, tokenUrl: TOKEN });
+
+    expect((await s.start('crm', 'SIGNIN')).status).toBe(200);
+    expect(s.beginToolOAuthByKey.mock.calls[0][0]).toMatchObject({
+      key: 'crm_SIGNIN',
+      provider: { clientId: 'client-B', authorizationUrl: AUTHORIZE, tokenUrl: TOKEN, pkce: true },
+    });
+  });
+
+  it.each([
+    ['an http:// token endpoint', 'http://127.0.0.1/token', '`variables[0].oauth.tokenUrl` must use https'],
+    ['a private token endpoint', 'https://10.0.0.5/token', '`variables[0].oauth.tokenUrl` host is not allowed'],
+  ])('a .tool naming %s is refused with the validation message, sending nothing', async (_n, tokenUrl, message) => {
+    await writeTool({ clientId: 'client-A', authorizationUrl: AUTHORIZE, tokenUrl: TOKEN });
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const s = await serve();
+    await s.toolManualService.listAccessible(USER); // the catalog still holds the valid version
+    await writeTool({ clientId: 'client-A', authorizationUrl: AUTHORIZE, tokenUrl });
+    const fetchSpy = vi.spyOn(globalThis, 'fetch');
+
+    const res = await s.start('crm', 'SIGNIN');
+    expect(res.status).toBe(422);
+    expect(((await res.json()) as { error: string }).error).toBe(message);
+    expect(s.beginToolOAuthByKey).not.toHaveBeenCalled();
+    // The one fetch is the test's own call to the route: nothing went to a provider.
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('a plugin.json sign-in naming an http:// token endpoint is refused with the validation message, sending nothing', async () => {
+    await writePlugin({ clientId: 'owner-app', authorizationUrl: AUTHORIZE, tokenUrl: 'http://127.0.0.1/token' });
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const s = await serve();
+    const fetchSpy = vi.spyOn(globalThis, 'fetch');
+
+    const res = await s.start('hubspot', 'HUBSPOT_TOKEN');
+    expect(res.status).toBe(422);
+    expect(((await res.json()) as { error: string }).error).toContain('`variables[0].oauth.tokenUrl` must use https');
+    expect(s.beginToolOAuthByKey).not.toHaveBeenCalled();
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('a slug no file declares is still not found', async () => {
+    const s = await serve();
+    expect((await s.start('nothing', 'SIGNIN')).status).toBe(404);
+  });
+});

package/src/core/catalog-cache-invalidation.ts

@@ -1,5 +1,5 @@
 import type { FileChangeNotifier } from '../modules/kb-fs/file-change-notifier.js';
-import type { WorkflowEventBus } from '../modules/workflow/event-bus.js';
+import type { VersionControlEventBus } from '../modules/version-control/event-bus.js';
 import type { KbContext } from '../shared/kb-context.js';
 
 /**
@@ -23,7 +23,7 @@ export interface InvalidatableCatalog {
  * Returns an unsubscribe that detaches all three.
  */
 export function registerCatalogCacheInvalidation(deps: {
-  eventBus: WorkflowEventBus;
+  eventBus: VersionControlEventBus;
   fileChangeNotifier: FileChangeNotifier;
   /**
    * The KB folder inside the workspace (`paths` are workspace-relative), the

package/src/core/compose-embed.ts

@@ -1,4 +1,4 @@
-import type { IGitService, IWorkflowService } from '@bevel-software/platform-shared';
+import type { IGitService, IVersionControlService } from '@bevel-software/platform-shared';
 import type { KbContext } from '../shared/kb-context.js';
 import type { IAccessControl } from '../modules/access/access-control.interface.js';
 import type { WriteValidator } from '../modules/kb-fs/index.js';
@@ -15,7 +15,7 @@ export interface EmbedComposition {
   workspaceService: EmbedWorkspacePort;
   accessControl: IAccessControl;
   authService: EmbedAuthPort;
-  workflowService: IWorkflowService;
+  versionControlService: IVersionControlService;
   gitService: IGitService;
   accountLinks: IAccountLinkService;
   /** The SAME extension-to-reader registry `read_file` dispatches on. */
@@ -40,7 +40,7 @@ export function composeEmbedService(deps: EmbedComposition, ports: Pick<CorePort
     deps.workspaceService,
     deps.accessControl,
     deps.authService,
-    deps.workflowService,
+    deps.versionControlService,
     deps.gitService,
     deps.accountLinks,
     deps.readers,

package/src/core/core-ports.ts

@@ -2,7 +2,7 @@ import type { ISessionSink } from '../modules/workspace/session-sink.js';
 import type {
   ISystemNoticeSink,
   RecoveryAgentRunner,
-} from '../modules/workflow/pending-commits.worker.js';
+} from '../modules/version-control/pending-commits.worker.js';
 import type { ILlmUsageMeter } from '../modules/tool-auth/llm-usage-meter.js';
 import type { AuthProviderPlugin } from '../modules/auth/auth.routes.js';
 import type { IErasureParticipant } from '../modules/auth/account-erasure.service.js';
@@ -12,6 +12,7 @@ import type { OnServerStart } from '../modules/workspace/startup/on-server-start
 import type { AgentGuideHook } from '../modules/agent-guide/agent-guide.js';
 import type { IAgentScopeResolver } from '../modules/agent-scope/index.js';
 import type { EmbedNodeIdResolver } from '../modules/embed/embed.interface.js';
+import type { ManagedSignInPort } from '../modules/secrets-vault/secrets-vault.contract.js';
 import type { IWorkspaceService } from '@bevel-software/platform-shared';
 import type { IAccessControl } from '../modules/access/index.js';
 import type { KbContext } from '../shared/kb-context.js';
@@ -64,10 +65,15 @@ export interface AgentScopeCollaborators {
  *   enterprise root overwrites the `CoreServices` fields (or pushes into the
  *   `authProviders` array) after construction, before the server is built.
  *
+ * - REQUEST-TIME seams (`managedSignIns`, the third of the three patterns): seeded onto `CoreServices` the same
+ *   way, but the routes that use it read the field on every request rather
+ *   than at mount, so the enterprise root may assign it at any point after
+ *   construction — even after the server is listening.
+ *
  * (Commit-time KB validation and the agent read/write hooks are NOT ports:
- * they are workflow lifecycle HOOKS the enterprise root registers on
- * `workflowService.hooks` after construction — see
- * `modules/workflow/workflow-hooks.ts`.)
+ * they are version-control lifecycle HOOKS the enterprise root registers on
+ * `versionControlService.hooks` after construction — see
+ * `modules/version-control/version-control-hooks.ts`.)
  */
 export interface CorePorts {
   /**
@@ -190,6 +196,15 @@ export interface CorePorts {
    * for an id that names nothing. See `modules/embed/embed.interface.ts`.
    */
   embedNodeIdResolver?: EmbedNodeIdResolver;
+  /**
+   * The distribution's side of a MANAGED sign-in (a `.tool` sign-in whose
+   * `oauth` block names a platform connector): what the Connect page shows
+   * for it and how a sign-in through the broker is opened. Core default:
+   * none, so such a sign-in is listed as waiting on the deployment. Also
+   * settable after construction (`CoreServices.managedSignIns`), like the
+   * session sink. See `modules/secrets-vault/secrets-vault.contract.ts`.
+   */
+  managedSignIns?: ManagedSignInPort;
 }
 
 /**

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

@@ -13,8 +13,12 @@ import { createAgentDownloadRoutes } from '../modules/workspace/agent-download.r
 import { createGitInternalsRouteGuard } from '../modules/workspace/git-internals.middleware.js';
 import { startCore } from './lifecycle.js';
 import { createDiffRoutes } from '../modules/diff/diff.routes.js';
-import { createWorkflowRoutes } from '../modules/workflow/workflow.routes.js';
-import { createEventAccess, createEventsRoutes, EventDelivery } from '../modules/workflow/index.js';
+import {
+  createEventAccess,
+  createEventsRoutes,
+  createVersionControlRoutes,
+  EventDelivery,
+} from '../modules/version-control/index.js';
 import { createAccessRoutes } from '../modules/access/access.routes.js';
 import { createAccessRequestRoutes } from '../modules/access/access-requests.routes.js';
 import { AccessRequestsService } from '../modules/access/access-requests.service.js';
@@ -32,12 +36,12 @@ import {
   createToolManualsBrowserRoutes,
   registerToolManualsTools,
 } from '../modules/tool-manuals/index.js';
-import { registerWorkflowTools } from '../modules/workflow/agent-tools/workflow.tools.js';
-import { changeRequestScope, registerChangeRequestReadTools } from '../modules/workflow/agent-tools/change-request-read.tools.js';
+import { registerVersionControlTools } from '../modules/version-control/agent-tools/version-control.tools.js';
+import { changeRequestScope, registerChangeRequestReadTools } from '../modules/version-control/agent-tools/change-request-read.tools.js';
 import { createOnboardingRoutes } from '../modules/onboarding/onboarding.routes.js';
 import { registerWorkspaceTools } from '../modules/workspace/workspace.tools.js';
 import { registerAgentGuideTool } from '../modules/agent-guide/index.js';
-import { RECOVERY_BOT_EMAIL } from '../modules/workflow/recovery-bot.js';
+import { RECOVERY_BOT_EMAIL } from '../modules/version-control/recovery-bot.js';
 import {
   registerSkillsTools,
   createSkillsRoutes,
@@ -433,6 +437,8 @@ export async function createCoreServer(
     publicBackendUrl: core.config.publicBackendUrl,
     publicFrontendUrl: core.config.publicFrontendUrl,
     kb: core.kb,
+    // Read at request time: the overlay binds the port after core is built.
+    managedSignIns: () => core.managedSignIns,
   };
   app.use('/api', createSecretsVaultPublicRoutes(secretsVaultRoutesDeps));
 
@@ -468,12 +474,12 @@ export async function createCoreServer(
   // Shared agent-access gate config, consumed by every tool surface that
   // touches the KB (file tools + graph tools). The gate decides nothing
   // itself: it calls the read and write hooks a deployment registered on
-  // `workflowService.hooks`, and carries the notes that deployment wants
+  // `versionControlService.hooks`, and carries the notes that deployment wants
   // agents to read about the gated tools. Core registers neither, so a
   // core-only deployment refuses nothing and says nothing extra.
   const agentAccessGate: AgentAccessGate = {
     recoveryBotEmail: RECOVERY_BOT_EMAIL,
-    hooks: core.workflowService.hooks,
+    hooks: core.versionControlService.hooks,
     notes: new ToolDescriptionNotes(),
   };
   // A skill's `allowed-tools`, checked against what the caller can see — on
@@ -482,12 +488,12 @@ export async function createCoreServer(
   const allowedToolsChecker = new AllowedToolsChecker(core.toolRegistry, core.toolManualService, core.kb);
   // `delete_branch` sees change requests as `get_change_request` does.
   // The history tools take the per-file read the file itself takes (`accessControl`).
-  registerWorkflowTools(core.toolRegistry, toolsRouter, ta, th, core.kb, changeRequestScope(core.accessControl, core.kb).maySee, core.accessControl, agentAccessGate);
-  // The five read tools over change requests. Separate from the workflow tools
+  registerVersionControlTools(core.toolRegistry, toolsRouter, ta, th, core.kb, changeRequestScope(core.accessControl, core.kb).maySee, core.accessControl, agentAccessGate);
+  // The five read tools over change requests. Separate from the version-control tools
   // because they are the only ones that gate their whole payload on the
   // caller's read access, so they take the access service and nothing else.
   registerChangeRequestReadTools(core.toolRegistry, toolsRouter, ta, th, core.accessControl, core.kb);
-  const workspaceTools = registerWorkspaceTools(core.toolRegistry, toolsRouter, ta, th, core.spillStore, core.docExtractService, core.accessControl, core.kb, agentAccessGate, core.routineWritePolicy, core.sessionSink, allowedToolsChecker, core.changeGate, core.agentUploadStore, core.agentGuide, core.agentDownloadStore, core.starterPackService, core.disk, core.patternMatcher);
+  const workspaceTools = registerWorkspaceTools(core.toolRegistry, toolsRouter, ta, th, core.spillStore, core.docExtractService, core.accessControl, core.kb, agentAccessGate, core.routineWritePolicy, core.sessionSink, allowedToolsChecker, core.changeGate, core.agentUploadStore, core.agentGuideStart, core.agentDownloadStore, core.starterPackService, core.disk, core.patternMatcher);
   // `open_page` — the knowledge-base page shown inside a chat. Registered
   // here, on the same router as the file tools, because it answers with
   // `read_file`'s own read: the read hook, the access gate and the
@@ -580,7 +586,14 @@ export async function createCoreServer(
   // What every connected agent is told at session start, as the hosted proxy
   // composes it: read by the local `hexis-mcp` bridge at startup and by the
   // External agent access card. Same `manualAuth`, same router, as `all-tools`.
-  toolsRouter.use(createAgentInstructionsRoutes(core.manualAuthMiddleware, core.readAgentPreamble, () => core.kb.layout));
+  toolsRouter.use(
+    createAgentInstructionsRoutes(
+      core.manualAuthMiddleware,
+      core.readAgentPreamble,
+      () => core.kb.layout,
+      () => core.kb.defaultBranch,
+    ),
+  );
   // The fingerprint of the caller's released catalog. The local `hexis-mcp`
   // server polls it to learn that a manual or a skill changed under a
   // connection it cannot be pushed to; nothing else consults it. Same
@@ -610,7 +623,7 @@ export async function createCoreServer(
   app.use('/api', toolsRouter);
 
   // The same guard on the PARSED body, for the WHOLE `/workspace/:id` prefix
-  // and ahead of EVERY router under it — the file routes, the review, workflow
+  // and ahead of EVERY router under it — the file routes, the review, version control
   // and access ones, and whatever an extension mounts below. Mounted here,
   // before the extension phase, so an overlay surface added there is covered
   // by its prefix rather than by remembering this. No auth in front of it: the
@@ -661,7 +674,7 @@ export async function createCoreServer(
   app.use('/api', core.authMiddleware, createWorkspaceRoutes(
     core.workspaceService,
     core.authService,
-    core.workflowService,
+    core.versionControlService,
     core.eventBus,
     core.accessControl,
     core.kb,
@@ -671,11 +684,12 @@ export async function createCoreServer(
     allowedToolsChecker,
     core.changeGate,
   ));
-  // Workflow is the only branches / changes / change-request surface. The
+  // Version control is the only branches / changes / change-request surface. The
   // former /git/*, /pr/*, /pr/:n/* routes are gone — every consumer goes
   // through /workflow/* now.
-  app.use('/api', core.authMiddleware, createWorkflowRoutes(
-    core.workflowService,
+  // The `/workflow/` prefix is kept for API compatibility until a core major.
+  app.use('/api', core.authMiddleware, createVersionControlRoutes(
+    core.versionControlService,
     core.workspaceService,
     core.authService,
     core.eventBus,
@@ -693,7 +707,7 @@ export async function createCoreServer(
   const eventDelivery = new EventDelivery(createEventAccess({
     accessControl: core.accessControl,
     kbDirName: core.kbDirName,
-    getChangeRequest: (number) => core.workflowService.getChangeRequest(number),
+    getChangeRequest: (number) => core.versionControlService.getChangeRequest(number),
     workspaces: {
       hasWorkspace: (workspaceId) => core.workspaceService.hasBootstrappedWorkspace(workspaceId),
       anyWorkspaceId: async () => (await core.workspaceService.findAnyWorkspaceId()) ?? core.kb.defaultWorkspaceId(),
@@ -703,7 +717,7 @@ export async function createCoreServer(
   app.use('/api', core.authMiddleware, createDiffRoutes(
     core.diffService,
     core.authService,
-    core.workflowService,
+    core.versionControlService,
     core.accessControl,
     core.kbDirName,
   ));
@@ -712,7 +726,7 @@ export async function createCoreServer(
     core.workspaceService,
     core.authService,
     core.authService,
-    core.workflowService,
+    core.versionControlService,
     core.eventBus,
     core.db,
     core.kb,
@@ -727,7 +741,7 @@ export async function createCoreServer(
     accessControl: core.accessControl,
     workspaceService: core.workspaceService,
     authService: core.authService,
-    workflow: core.workflowService,
+    versionControl: core.versionControlService,
     lifecycle: core.joinRequestsService,
     kb: core.kb,
   }));
@@ -744,9 +758,9 @@ export async function createCoreServer(
     createSkillAccessRequestRoutes({
       skillService: core.skillService,
       accessControl: core.accessControl,
-      workflow: core.workflowService,
+      versionControl: core.versionControlService,
       requests: new AccessRequestsService({
-        workflow: core.workflowService,
+        versionControl: core.versionControlService,
         workspaceService: core.workspaceService,
         lifecycle: core.joinRequestsService,
         kb: core.kb,
@@ -766,7 +780,7 @@ export async function createCoreServer(
   app.use('/api', core.authMiddleware, createPluginsRoutes(
     core.pluginIndexService,
     core.accessControl,
-    core.workflowService,
+    core.versionControlService,
     core.joinRequestsService,
     core.pluginJoinRequestJobs,
     core.pluginProvisionService,
@@ -869,12 +883,12 @@ export async function createCoreServer(
         githubApp: core.githubApp,
       },
       // What a move to another repository has to decide about, and what it
-      // runs under. Bound here rather than handed the whole workflow service:
+      // runs under. Bound here rather than handed the whole version-control service:
       // the setup routes ask two questions, hold the commit worker for the
       // move, and know nothing else about a request or a commit.
       {
-        countOpen: () => core.workflowService.countOpenChangeRequests(),
-        closeAsRepositoryReplaced: () => core.workflowService.closeOpenChangeRequestsAsRepositoryReplaced(),
+        countOpen: () => core.versionControlService.countOpenChangeRequests(),
+        closeAsRepositoryReplaced: () => core.versionControlService.closeOpenChangeRequestsAsRepositoryReplaced(),
         whileCommitsHeld: (work) => core.whileCommitsHeld(work),
       },
     ),