@bevel-software/platform-core-backend 0.7.5 → 0.8.0

package/src/modules/auth/__tests__/auth.routes.test.ts

@@ -1,91 +1,91 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import express from 'express';
-import type { Server } from 'node:http';
-import { createAuthRoutes } from '../auth.routes.js';
-import type { AuthService } from '../auth.service.js';
-
-const authService = {
-  loginWithPassword: vi.fn(async () => {
-    throw new Error('Invalid credentials');
-  }),
-  changePassword: vi.fn(async () => {
-    throw new Error('Current password is incorrect');
-  }),
-  getUserById: vi.fn(async () => null),
-} as unknown as AuthService;
-
-const fakeAuthMiddleware: express.RequestHandler = (req, _res, next) => {
-  req.userId = 'user-1';
-  req.userEmail = 'alice@example.com';
-  next();
-};
-
-let server: Server;
-beforeEach(() => {
-  vi.mocked(authService.loginWithPassword).mockClear();
-});
-afterEach(() => {
-  server?.close();
-});
-
-async function listen(): Promise<string> {
-  const app = express();
-  app.use(express.json());
-  app.use('/api', createAuthRoutes(authService, fakeAuthMiddleware));
-  await new Promise<void>((resolve) => {
-    server = app.listen(0, resolve);
-  });
-  const address = server.address();
-  if (typeof address === 'string' || !address) throw new Error('no port');
-  return `http://127.0.0.1:${address.port}`;
-}
-
-function postLogin(base: string, email: string, password = 'wrong') {
-  return fetch(`${base}/api/auth/login`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ email, password }),
-  });
-}
-
-describe('auth routes — rate limiting', () => {
-  it('429s login for an (ip, email) pair after repeated failures; other emails unaffected', async () => {
-    const base = await listen();
-    for (let i = 0; i < 10; i++) {
-      expect((await postLogin(base, 'alice@example.com')).status).toBe(401);
-    }
-    const limited = await postLogin(base, 'alice@example.com');
-    expect(limited.status).toBe(429);
-    // The service is not even consulted once the limit is hit.
-    expect(authService.loginWithPassword).toHaveBeenCalledTimes(10);
-    // A different email from the same address still has pair budget (the
-    // wider per-ip budget is 50).
-    expect((await postLogin(base, 'bob@example.com')).status).toBe(401);
-  });
-
-  it('a successful login resets the pair budget', async () => {
-    const base = await listen();
-    for (let i = 0; i < 9; i++) await postLogin(base, 'alice@example.com');
-    vi.mocked(authService.loginWithPassword).mockResolvedValueOnce({
-      token: 'jwt',
-      user: { id: 'user-1', email: 'alice@example.com', name: 'Alice' },
-    });
-    expect((await postLogin(base, 'alice@example.com', 'right')).status).toBe(200);
-    // Budget is fresh again — failures start counting from zero.
-    expect((await postLogin(base, 'alice@example.com')).status).toBe(401);
-  });
-
-  it('429s change-password per account after repeated failures', async () => {
-    const base = await listen();
-    const post = () =>
-      fetch(`${base}/api/auth/change-password`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ currentPassword: 'wrong', newPassword: 'new-password-1' }),
-      });
-    for (let i = 0; i < 10; i++) {
-      expect((await post()).status).toBe(400);
-    }
-    expect((await post()).status).toBe(429);
-  });
-});
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import express from 'express';
+import type { Server } from 'node:http';
+import { createAuthRoutes } from '../auth.routes.js';
+import type { AuthService } from '../auth.service.js';
+
+const authService = {
+  loginWithPassword: vi.fn(async () => {
+    throw new Error('Invalid credentials');
+  }),
+  changePassword: vi.fn(async () => {
+    throw new Error('Current password is incorrect');
+  }),
+  getUserById: vi.fn(async () => null),
+} as unknown as AuthService;
+
+const fakeAuthMiddleware: express.RequestHandler = (req, _res, next) => {
+  req.userId = 'user-1';
+  req.userEmail = 'alice@example.com';
+  next();
+};
+
+let server: Server;
+beforeEach(() => {
+  vi.mocked(authService.loginWithPassword).mockClear();
+});
+afterEach(() => {
+  server?.close();
+});
+
+async function listen(): Promise<string> {
+  const app = express();
+  app.use(express.json());
+  app.use('/api', createAuthRoutes(authService, fakeAuthMiddleware));
+  await new Promise<void>((resolve) => {
+    server = app.listen(0, resolve);
+  });
+  const address = server.address();
+  if (typeof address === 'string' || !address) throw new Error('no port');
+  return `http://127.0.0.1:${address.port}`;
+}
+
+function postLogin(base: string, email: string, password = 'wrong') {
+  return fetch(`${base}/api/auth/login`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ email, password }),
+  });
+}
+
+describe('auth routes — rate limiting', () => {
+  it('429s login for an (ip, email) pair after repeated failures; other emails unaffected', async () => {
+    const base = await listen();
+    for (let i = 0; i < 10; i++) {
+      expect((await postLogin(base, 'alice@example.com')).status).toBe(401);
+    }
+    const limited = await postLogin(base, 'alice@example.com');
+    expect(limited.status).toBe(429);
+    // The service is not even consulted once the limit is hit.
+    expect(authService.loginWithPassword).toHaveBeenCalledTimes(10);
+    // A different email from the same address still has pair budget (the
+    // wider per-ip budget is 50).
+    expect((await postLogin(base, 'bob@example.com')).status).toBe(401);
+  });
+
+  it('a successful login resets the pair budget', async () => {
+    const base = await listen();
+    for (let i = 0; i < 9; i++) await postLogin(base, 'alice@example.com');
+    vi.mocked(authService.loginWithPassword).mockResolvedValueOnce({
+      token: 'jwt',
+      user: { id: 'user-1', email: 'alice@example.com', name: 'Alice' },
+    });
+    expect((await postLogin(base, 'alice@example.com', 'right')).status).toBe(200);
+    // Budget is fresh again — failures start counting from zero.
+    expect((await postLogin(base, 'alice@example.com')).status).toBe(401);
+  });
+
+  it('429s change-password per account after repeated failures', async () => {
+    const base = await listen();
+    const post = () =>
+      fetch(`${base}/api/auth/change-password`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ currentPassword: 'wrong', newPassword: 'new-password-1' }),
+      });
+    for (let i = 0; i < 10; i++) {
+      expect((await post()).status).toBe(400);
+    }
+    expect((await post()).status).toBe(429);
+  });
+});

package/src/modules/auth/__tests__/rate-limit.test.ts

@@ -1,36 +1,36 @@
-import { describe, expect, it } from 'vitest';
-import { FixedWindowRateLimiter } from '../rate-limit.js';
-
-describe('FixedWindowRateLimiter', () => {
-  it('allows up to max attempts per window, then refuses', () => {
-    let now = 0;
-    const limiter = new FixedWindowRateLimiter(3, 1000, () => now);
-    expect(limiter.consume('k')).toBe(true);
-    expect(limiter.consume('k')).toBe(true);
-    expect(limiter.consume('k')).toBe(true);
-    expect(limiter.consume('k')).toBe(false);
-    // A different key has its own budget.
-    expect(limiter.consume('other')).toBe(true);
-    // Window rollover restores the budget.
-    now = 1001;
-    expect(limiter.consume('k')).toBe(true);
-  });
-
-  it('reset() clears a key immediately', () => {
-    const limiter = new FixedWindowRateLimiter(1, 60_000, () => 0);
-    expect(limiter.consume('k')).toBe(true);
-    expect(limiter.consume('k')).toBe(false);
-    limiter.reset('k');
-    expect(limiter.consume('k')).toBe(true);
-  });
-
-  it('prunes expired windows so the map stays bounded', () => {
-    let now = 0;
-    const limiter = new FixedWindowRateLimiter(1, 1000, () => now);
-    for (let i = 0; i < 100; i++) limiter.consume(`k${i}`);
-    now = 2000;
-    limiter.consume('fresh');
-    // Internal map pruned to just the fresh key.
-    expect((limiter as unknown as { hits: Map<string, unknown> }).hits.size).toBe(1);
-  });
-});
+import { describe, expect, it } from 'vitest';
+import { FixedWindowRateLimiter } from '../rate-limit.js';
+
+describe('FixedWindowRateLimiter', () => {
+  it('allows up to max attempts per window, then refuses', () => {
+    let now = 0;
+    const limiter = new FixedWindowRateLimiter(3, 1000, () => now);
+    expect(limiter.consume('k')).toBe(true);
+    expect(limiter.consume('k')).toBe(true);
+    expect(limiter.consume('k')).toBe(true);
+    expect(limiter.consume('k')).toBe(false);
+    // A different key has its own budget.
+    expect(limiter.consume('other')).toBe(true);
+    // Window rollover restores the budget.
+    now = 1001;
+    expect(limiter.consume('k')).toBe(true);
+  });
+
+  it('reset() clears a key immediately', () => {
+    const limiter = new FixedWindowRateLimiter(1, 60_000, () => 0);
+    expect(limiter.consume('k')).toBe(true);
+    expect(limiter.consume('k')).toBe(false);
+    limiter.reset('k');
+    expect(limiter.consume('k')).toBe(true);
+  });
+
+  it('prunes expired windows so the map stays bounded', () => {
+    let now = 0;
+    const limiter = new FixedWindowRateLimiter(1, 1000, () => now);
+    for (let i = 0; i < 100; i++) limiter.consume(`k${i}`);
+    now = 2000;
+    limiter.consume('fresh');
+    // Internal map pruned to just the fresh key.
+    expect((limiter as unknown as { hits: Map<string, unknown> }).hits.size).toBe(1);
+  });
+});

package/src/modules/auth/rate-limit.ts

@@ -1,45 +1,45 @@
-/**
- * Tiny fixed-window in-memory rate limiter for the password endpoints —
- * brute-force / scrypt-DoS protection, not traffic shaping. In-memory is the
- * right scope for the single-instance deployment model (same assumption as
- * the MCP session store); a multi-replica future moves this behind a shared
- * store.
- *
- * Expired windows are pruned opportunistically on each hit so the map stays
- * bounded by the number of DISTINCT active keys per window.
- */
-export class FixedWindowRateLimiter {
-  private readonly hits = new Map<string, { count: number; resetAt: number }>();
-
-  constructor(
-    /** Attempts allowed per window per key. */
-    private readonly max: number,
-    private readonly windowMs: number,
-    /** Injectable clock for tests. */
-    private readonly now: () => number = Date.now,
-  ) {}
-
-  /**
-   * Record one attempt for `key`; returns true when the attempt is ALLOWED
-   * (i.e. the key is within its budget for the current window).
-   */
-  consume(key: string): boolean {
-    const now = this.now();
-    for (const [k, entry] of this.hits) {
-      if (entry.resetAt <= now) this.hits.delete(k);
-    }
-    const entry = this.hits.get(key);
-    if (!entry || entry.resetAt <= now) {
-      this.hits.set(key, { count: 1, resetAt: now + this.windowMs });
-      return true;
-    }
-    entry.count += 1;
-    return entry.count <= this.max;
-  }
-
-  /** Clear a key's window — called after a SUCCESSFUL login so legitimate
-   * users who fumbled a few attempts aren't locked out of their next visit. */
-  reset(key: string): void {
-    this.hits.delete(key);
-  }
-}
+/**
+ * Tiny fixed-window in-memory rate limiter for the password endpoints —
+ * brute-force / scrypt-DoS protection, not traffic shaping. In-memory is the
+ * right scope for the single-instance deployment model (same assumption as
+ * the MCP session store); a multi-replica future moves this behind a shared
+ * store.
+ *
+ * Expired windows are pruned opportunistically on each hit so the map stays
+ * bounded by the number of DISTINCT active keys per window.
+ */
+export class FixedWindowRateLimiter {
+  private readonly hits = new Map<string, { count: number; resetAt: number }>();
+
+  constructor(
+    /** Attempts allowed per window per key. */
+    private readonly max: number,
+    private readonly windowMs: number,
+    /** Injectable clock for tests. */
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  /**
+   * Record one attempt for `key`; returns true when the attempt is ALLOWED
+   * (i.e. the key is within its budget for the current window).
+   */
+  consume(key: string): boolean {
+    const now = this.now();
+    for (const [k, entry] of this.hits) {
+      if (entry.resetAt <= now) this.hits.delete(k);
+    }
+    const entry = this.hits.get(key);
+    if (!entry || entry.resetAt <= now) {
+      this.hits.set(key, { count: 1, resetAt: now + this.windowMs });
+      return true;
+    }
+    entry.count += 1;
+    return entry.count <= this.max;
+  }
+
+  /** Clear a key's window — called after a SUCCESSFUL login so legitimate
+   * users who fumbled a few attempts aren't locked out of their next visit. */
+  reset(key: string): void {
+    this.hits.delete(key);
+  }
+}

package/src/modules/code-mode/__tests__/code-mode.tool.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { CodeModeUtcpClient } from '@utcp/code-mode';
+
+/**
+ * `tools_info` containment of a THROWING name lookup. `findToolByName`
+ * (mcp-core) throws on an ambiguous sanitized name — sanitization is lossy
+ * (`a-b` and `a+b` both become `a_b`) — and one ambiguous entry in a batch
+ * must cost that entry an error message, never the whole response. The
+ * lookup is mocked at the module seam so the test pins THIS module's
+ * per-name containment, not mcp-core's collision detection.
+ */
+
+vi.mock('../code-mode-names.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../code-mode-names.js')>();
+  return {
+    ...actual,
+    findToolByName: vi.fn(async (_client: unknown, name: string) => {
+      if (name === 'a_b.fetch') {
+        // The REAL sentinel class — the containment branches on instanceof,
+        // and a lookalike Error would test the wrong contract.
+        throw new actual.AmbiguousToolNameError(
+          'Tool name "a_b.fetch" is ambiguous: "a-b.fetch", "a+b.fetch" all sanitize to it. ' +
+            'Call the tool by its exact UTCP name instead.',
+        );
+      }
+      if (name === 'down.run') throw new Error('repository unavailable: ECONNREFUSED');
+      if (name === 'solo.run') return { tool: { name: 'solo.run' }, utcpName: 'solo.run' };
+      return null;
+    }),
+  };
+});
+
+const { createToolsInfoTool } = await import('../code-mode.tool.js');
+
+const client = {
+  toolToTypeScriptInterface: (tool: { name: string }) => `interface ${tool.name}`,
+} as unknown as CodeModeUtcpClient;
+
+type ToolsInfoResult = { interfaces: string; not_found: string[]; errors?: string[] };
+
+async function run(toolNames: string[]): Promise<ToolsInfoResult> {
+  const tool = createToolsInfoTool(client) as unknown as {
+    execute: (input: { tool_names: string[] }) => Promise<ToolsInfoResult>;
+  };
+  return tool.execute({ tool_names: toolNames });
+}
+
+describe('tools_info', () => {
+  it('answers every resolvable name even when one in the batch throws as ambiguous', async () => {
+    const result = await run(['a_b.fetch', 'solo.run', 'nope']);
+    expect(result.interfaces).toContain('interface solo.run');
+    expect(result.not_found).toEqual(['nope']);
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors?.[0]).toMatch(/^a_b\.fetch: .*ambiguous/);
+  });
+
+  it('omits the errors field entirely when every name resolves or misses cleanly', async () => {
+    const result = await run(['solo.run', 'nope']);
+    expect(result.interfaces).toBe('interface solo.run');
+    expect(result.not_found).toEqual(['nope']);
+    expect(result.errors).toBeUndefined();
+  });
+
+  it('contains ONLY ambiguity — an outage rethrows instead of posing as partial success', async () => {
+    await expect(run(['solo.run', 'down.run'])).rejects.toThrow(/repository unavailable/);
+  });
+});

package/src/modules/code-mode/code-mode-names.ts

@@ -1,38 +1,12 @@
-import type { Tool } from '@utcp/sdk';
-import type { CodeModeUtcpClient } from '@utcp/code-mode';
-
 /**
- * Pure helpers for mapping UTCP tool names to their code-mode (TypeScript)
- * accessible form. Kept Mastra-free so both the agent's Mastra tools
- * (`code-mode.tool.ts`) and the MCP proxy can share them.
+ * Re-export of the code-mode name helpers, which now live in
+ * `@bevel-software/platform-mcp-core` so the local MCP server can share them
+ * without depending on this package. Kept as a module here because the agent's
+ * Mastra tools and the MCP proxy both import it by this path.
  */
-
-export function sanitizeIdentifier(name: string): string {
-  return name.replace(/[^a-zA-Z0-9_]/g, '_').replace(/^[0-9]/, '_$&');
-}
-
-/** `MANUAL.tool` → the `manual.tool` form the code-mode runtime exposes. */
-export function utcpNameToTsInterfaceName(utcpName: string): string {
-  if (utcpName.includes('.')) {
-    const [manualName, ...toolParts] = utcpName.split('.');
-    return `${sanitizeIdentifier(manualName!)}.${toolParts.map(sanitizeIdentifier).join('_')}`;
-  }
-  return sanitizeIdentifier(utcpName);
-}
-
-/** Resolve a tool by its raw UTCP name or its sanitized TS-accessible name. */
-export async function findToolByName(
-  client: CodeModeUtcpClient,
-  name: string,
-): Promise<{ tool: Tool; utcpName: string } | null> {
-  const direct = await client.config.tool_repository.getTool(name);
-  if (direct) return { tool: direct, utcpName: name };
-
-  const all = await client.config.tool_repository.getTools();
-  for (const tool of all) {
-    if (utcpNameToTsInterfaceName(tool.name) === name) {
-      return { tool, utcpName: tool.name };
-    }
-  }
-  return null;
-}
+export {
+  sanitizeIdentifier,
+  utcpNameToTsInterfaceName,
+  findToolByName,
+  AmbiguousToolNameError,
+} from '@bevel-software/platform-mcp-core';

package/src/modules/code-mode/code-mode.tool.ts

@@ -3,7 +3,7 @@ import { createTool } from '@mastra/core/tools';
 import { z } from 'zod';
 import { CodeModeUtcpClient } from '@utcp/code-mode';
 import type { SpillStore } from '../workspace/spill-store.js';
-import { utcpNameToTsInterfaceName, findToolByName } from './code-mode-names.js';
+import { utcpNameToTsInterfaceName, findToolByName, AmbiguousToolNameError } from './code-mode-names.js';
 
 export function createCallToolChainTool(
   client: CodeModeUtcpClient,
@@ -103,15 +103,35 @@ export function createToolsInfoTool(client: CodeModeUtcpClient) {
     execute: async (input) => {
       const interfaces: string[] = [];
       const notFound: string[] = [];
+      const errors: string[] = [];
       for (const name of input.tool_names) {
-        const found = await findToolByName(client, name);
-        if (found) {
-          interfaces.push(client.toolToTypeScriptInterface(found.tool));
-        } else {
-          notFound.push(name);
+        // Per-name, not per-call: `findToolByName` THROWS on an ambiguous
+        // sanitized name (two UTCP tools collapsing to one TS name), and one
+        // ambiguous entry aborting the whole batch would cost the agent every
+        // other answer in it. The error text says how to disambiguate, so it
+        // is the per-name answer, not a failure of the tool.
+        try {
+          const found = await findToolByName(client, name);
+          if (found) {
+            interfaces.push(client.toolToTypeScriptInterface(found.tool));
+          } else {
+            notFound.push(name);
+          }
+        } catch (err) {
+          // Only AMBIGUITY is a per-name answer (the message says how to
+          // disambiguate). Anything else — a repository outage, a catalog
+          // failure — must fail the call: containing it would dress an
+          // outage up as a successful lookup with partial data. Typed, not
+          // message-matched: the wording belongs to another package.
+          if (!(err instanceof AmbiguousToolNameError)) throw err;
+          errors.push(`${name}: ${err.message}`);
         }
       }
-      return { interfaces: interfaces.join('\n\n'), not_found: notFound };
+      return {
+        interfaces: interfaces.join('\n\n'),
+        not_found: notFound,
+        ...(errors.length > 0 ? { errors } : {}),
+      };
     },
   });
 }

package/src/modules/database/connection.ts

@@ -1,15 +1,15 @@
-import { drizzle } from 'drizzle-orm/node-postgres';
-import pg from 'pg';
-import * as schema from './schema.js';
-
-let db: ReturnType<typeof drizzle<typeof schema>> | null = null;
-
-export function getDb(databaseUrl: string) {
-  if (!db) {
-    const pool = new pg.Pool({ connectionString: databaseUrl });
-    db = drizzle(pool, { schema });
-  }
-  return db;
-}
-
-export type Database = ReturnType<typeof getDb>;
+import { drizzle } from 'drizzle-orm/node-postgres';
+import pg from 'pg';
+import * as schema from './schema.js';
+
+let db: ReturnType<typeof drizzle<typeof schema>> | null = null;
+
+export function getDb(databaseUrl: string) {
+  if (!db) {
+    const pool = new pg.Pool({ connectionString: databaseUrl });
+    db = drizzle(pool, { schema });
+  }
+  return db;
+}
+
+export type Database = ReturnType<typeof getDb>;

package/src/modules/database/schema.ts

@@ -1,11 +1,11 @@
-/**
- * The database schema of the CORE platform.
- *
- * In this package `schema.ts` is a re-export of `core-schema.ts` ONLY — the
- * enterprise tables live with the enterprise product, whose own schema file
- * imports the FK targets (`users`, `apiTokens`) from
- * `@bevel-software/platform-core-backend/schema`. Kept as a separate module (rather
- * than folding the tables in here) so module code keeps importing
- * `./schema.js` unchanged.
- */
-export * from './core-schema.js';
+/**
+ * The database schema of the CORE platform.
+ *
+ * In this package `schema.ts` is a re-export of `core-schema.ts` ONLY — the
+ * enterprise tables live with the enterprise product, whose own schema file
+ * imports the FK targets (`users`, `apiTokens`) from
+ * `@bevel-software/platform-core-backend/schema`. Kept as a separate module (rather
+ * than folding the tables in here) so module code keeps importing
+ * `./schema.js` unchanged.
+ */
+export * from './core-schema.js';