@bevel-software/platform-core-backend 0.1.0

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

@@ -0,0 +1,97 @@
+import express from 'express';
+import type { AuthService } from './auth.service.js';
+import { AUTH_COOKIE_NAME } from './auth.middleware.js'; // also imports Express Request augmentation
+
+/**
+ * Max age of the JWT cookie (seconds). Matches the JWT's own `expiresIn:
+ * '7d'` so the cookie expires when the token does — browsers stop
+ * sending it past expiry, sparing the auth middleware verifying tokens
+ * that are guaranteed to fail.
+ */
+export const AUTH_COOKIE_MAX_AGE_S = 7 * 24 * 60 * 60;
+
+/**
+ * A pluggable SSO login method. Core ships password login only; the
+ * composition root passes provider plugins (e.g. Microsoft OIDC, owned by the
+ * sharepoint module) which mount their own routes under `/auth/<key>/…` and
+ * are advertised to the login screen under `key` by the capability probe.
+ * A plugin is only passed in when its machinery is configured AND the
+ * instance hasn't switched it off — presence means enabled.
+ */
+export interface AuthProviderPlugin {
+  /** Probe key + route namespace (e.g. 'microsoft' → /auth/microsoft/…). */
+  readonly key: string;
+  /** Mount the provider's routes (login redirect, callback) on the auth router. */
+  mountRoutes(router: express.Router, authService: AuthService): void;
+}
+
+export function createAuthRoutes(
+  authService: AuthService,
+  authMiddleware: express.RequestHandler,
+  providers: AuthProviderPlugin[] = [],
+  passwordLoginEnabled = true,
+): express.Router {
+  const router = express.Router();
+
+  // POST /api/auth/login — email + shared-password login (unprotected)
+  router.post('/auth/login', async (req, res) => {
+    if (!passwordLoginEnabled) {
+      res.status(403).json({ error: 'Password login is disabled' });
+      return;
+    }
+    const { email, password } = req.body as { email?: string; password?: string };
+    if (!email || !password) {
+      res.status(400).json({ error: 'email and password are required' });
+      return;
+    }
+
+    try {
+      const result = await authService.loginWithPassword(email, password);
+      // Also set the JWT as an HttpOnly cookie so transports that can't
+      // carry headers (EventSource for SSE, image tags) authenticate
+      // automatically. JSON callers continue to use the Bearer header
+      // returned in the body. Secure in production; off in dev so the
+      // cookie survives `http://localhost` requests.
+      res.cookie(AUTH_COOKIE_NAME, result.token, {
+        httpOnly: true,
+        sameSite: 'lax',
+        secure: process.env.NODE_ENV === 'production',
+        maxAge: AUTH_COOKIE_MAX_AGE_S * 1000,
+        path: '/',
+      });
+      res.json(result);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : 'Unknown error';
+      console.error('Login error:', msg);
+      res.status(401).json({ error: 'Authentication failed' });
+    }
+  });
+
+  // GET /api/auth/providers — unprotected capability probe so the login screen
+  // knows which login methods to render. SSO providers appear under their key.
+  router.get('/auth/providers', (_req, res) => {
+    res.json({
+      password: passwordLoginEnabled,
+      ...Object.fromEntries(providers.map((p) => [p.key, true])),
+    });
+  });
+
+  for (const provider of providers) provider.mountRoutes(router, authService);
+
+  // GET /api/auth/me — validate stored JWT, return user info (protected)
+  router.get('/auth/me', authMiddleware, async (req, res) => {
+    try {
+      const user = await authService.getUserById(req.userId!);
+      if (!user) {
+        res.status(404).json({ error: 'User not found' });
+        return;
+      }
+      res.json(user);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : 'Unknown error';
+      res.status(500).json({ error: msg });
+    }
+  });
+
+  return router;
+}

package/src/modules/auth/auth.service.ts

@@ -0,0 +1,199 @@
+import { timingSafeEqual } from 'node:crypto';
+import jwt from 'jsonwebtoken';
+import { eq } from 'drizzle-orm';
+import type { Database } from '../database/connection.js';
+import type { CoreConfig } from '../../core-config.js';
+import { users } from '../database/schema.js';
+import type { AuthUser } from '@bevel-software/platform-shared';
+import { hashEmail } from '../../shared/hash-email.js';
+
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+function toAuthUser(user: {
+  id: string;
+  email: string;
+  name: string;
+  avatarUrl: string | null;
+}): AuthUser {
+  return {
+    id: user.id,
+    email: user.email,
+    name: user.name,
+    avatarUrl: user.avatarUrl ?? undefined,
+  };
+}
+
+export class AuthService {
+  constructor(
+    private readonly db: Database,
+    private readonly config: CoreConfig,
+  ) {}
+
+  async loginWithPassword(
+    email: string,
+    password: string,
+  ): Promise<{ token: string; user: AuthUser }> {
+    const normalizedEmail = (email ?? '').trim().toLowerCase();
+
+    if (!EMAIL_REGEX.test(normalizedEmail)) {
+      throw new Error('Invalid email');
+    }
+    this.assertAllowedDomain(normalizedEmail);
+    if (!this.checkPassword(password ?? '')) {
+      throw new Error('Invalid password');
+    }
+
+    // Derive a default display name from the local-part of the email
+    const defaultName = normalizedEmail.split('@')[0] || normalizedEmail;
+    const user = await this.upsertUserByEmail(normalizedEmail, defaultName);
+    return { token: this.signToken(user.id, user.email), user: toAuthUser(user) };
+  }
+
+  /**
+   * Establish a session for a user who authenticated via "Sign in with
+   * Microsoft". Same upsert-by-email + JWT path as password login — the only
+   * difference is identity came from a verified Microsoft id_token instead of
+   * the shared password. Email is the idempotency key, so a user who first
+   * used password login and later signs in with Microsoft (same email) keeps
+   * the same account/id.
+   */
+  async loginWithMicrosoft(
+    email: string,
+    name: string,
+  ): Promise<{ token: string; user: AuthUser }> {
+    const normalizedEmail = (email ?? '').trim().toLowerCase();
+    if (!EMAIL_REGEX.test(normalizedEmail)) {
+      throw new Error('Microsoft sign-in returned an invalid email');
+    }
+    this.assertAllowedDomain(normalizedEmail);
+    const displayName = (name ?? '').trim() || normalizedEmail.split('@')[0] || normalizedEmail;
+    const user = await this.upsertUserByEmail(normalizedEmail, displayName);
+    return { token: this.signToken(user.id, user.email), user: toAuthUser(user) };
+  }
+
+  private signToken(userId: string, email: string): string {
+    return jwt.sign({ userId, email }, this.config.jwtSecret, { expiresIn: '7d' });
+  }
+
+  /**
+   * Get-or-create a user record by email, without issuing a session token.
+   * Used by the embed surface: an Atlassian (Forge) editor whose identity was
+   * verified server-side needs a real user row so file-lock commits attribute
+   * to them — but they never get a Bevel browser session. Same email-keyed
+   * upsert as the login paths, so an embed editor who later logs in keeps the
+   * same account/id. Returns `null` for a malformed email.
+   */
+  async getOrCreateByEmail(
+    email: string,
+    name?: string,
+  ): Promise<{ id: string; email: string; name: string } | null> {
+    const normalizedEmail = (email ?? '').trim().toLowerCase();
+    if (!EMAIL_REGEX.test(normalizedEmail)) return null;
+    const displayName = (name ?? '').trim() || normalizedEmail.split('@')[0] || normalizedEmail;
+    const user = await this.upsertUserByEmail(normalizedEmail, displayName);
+    return { id: user.id, email: user.email, name: user.name };
+  }
+
+  private async upsertUserByEmail(email: string, name: string) {
+    const [user] = await this.db
+      .insert(users)
+      .values({ email, name })
+      .onConflictDoUpdate({ target: users.email, set: { updatedAt: new Date() } })
+      .returning();
+    return user;
+  }
+
+  verifyToken(token: string): { userId: string; email: string } {
+    const decoded = jwt.verify(token, this.config.jwtSecret) as {
+      userId: string;
+      email: string;
+    };
+    return { userId: decoded.userId, email: decoded.email };
+  }
+
+  /**
+   * Resolve a set of `authorId` hashes back to the app users that produced
+   * them. Used by the PR list to display the human who triggered each PR
+   * instead of the shared GitHub service account.
+   *
+   * Loads all users and hashes them in-process rather than indexing on a
+   * stored hash column — the user table is small (one row per team member)
+   * and refreshes are infrequent (PR list polls at 60s), so the cost is
+   * negligible and we avoid carrying a denormalised hash column.
+   */
+  async findUsersByEmailHash(
+    hashes: Set<string>,
+  ): Promise<Map<string, { id: string; email: string; name: string }>> {
+    const result = new Map<string, { id: string; email: string; name: string }>();
+    if (hashes.size === 0) return result;
+    const rows = await this.db.select().from(users);
+    for (const row of rows) {
+      const h = hashEmail(row.email);
+      if (!hashes.has(h)) continue;
+      result.set(h, { id: row.id, email: row.email, name: row.name });
+    }
+    return result;
+  }
+
+  async getUserById(userId: string): Promise<AuthUser | null> {
+    const [user] = await this.db
+      .select()
+      .from(users)
+      .where(eq(users.id, userId))
+      .limit(1);
+
+    if (!user) return null;
+
+    return {
+      id: user.id,
+      email: user.email,
+      name: user.name,
+      avatarUrl: user.avatarUrl ?? undefined,
+    };
+  }
+
+  /**
+   * Whether `email` passes the optional `ALLOWED_EMAIL_DOMAINS` guard. Returns
+   * true when no guard is configured (the default). Matches the email's domain
+   * exactly or as a subdomain, so `bevel.software` admits `a@bevel.software`
+   * and `a@eu.bevel.software` but not `a@notbevel.software`. When a guard IS
+   * configured, a missing/blank email fails closed. Exposed so non-login
+   * surfaces (the embed panel) can apply the same gate.
+   */
+  isEmailDomainAllowed(email: string): boolean {
+    const allowed = this.config.allowedEmailDomains;
+    if (allowed.length === 0) return true;
+    const domain = (email ?? '').trim().toLowerCase().split('@')[1] ?? '';
+    if (!domain) return false;
+    return allowed.some((d) => domain === d || domain.endsWith(`.${d}`));
+  }
+
+  /**
+   * Enforce {@link isEmailDomainAllowed} at the login paths. No-op when the
+   * guard is unset. Expects an already-normalized (trimmed, lower-cased,
+   * regex-validated) email.
+   */
+  private assertAllowedDomain(normalizedEmail: string): void {
+    if (!this.isEmailDomainAllowed(normalizedEmail)) {
+      throw new Error('Email domain is not allowed');
+    }
+  }
+
+  private checkPassword(provided: string): boolean {
+    const expected = this.config.testPassword;
+    // Reject if no password is configured on the server
+    if (!expected) return false;
+
+    const a = Buffer.from(provided, 'utf8');
+    const b = Buffer.from(expected, 'utf8');
+    // Pad both buffers to the same length so timingSafeEqual runs unconditionally —
+    // returning early on length mismatch would leak the expected password's length via timing.
+    const len = Math.max(a.length, b.length);
+    const aPadded = Buffer.alloc(len);
+    const bPadded = Buffer.alloc(len);
+    a.copy(aPadded);
+    b.copy(bPadded);
+    const equal = timingSafeEqual(aPadded, bPadded);
+    return equal && a.length === b.length;
+  }
+}

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

@@ -0,0 +1,38 @@
+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.
+ */
+
+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;
+}

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

@@ -0,0 +1,117 @@
+import '@utcp/direct-call';
+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';
+
+export function createCallToolChainTool(
+  client: CodeModeUtcpClient,
+  spillStore: SpillStore,
+) {
+  return createTool({
+    id: 'call_tool_chain',
+    description: [
+      CodeModeUtcpClient.AGENT_PROMPT_TEMPLATE,
+      'Execute JavaScript code with direct access to all registered UTCP tools as hierarchical functions (e.g. `manual.tool(args)`, synchronous, no await). The runtime is plain JavaScript — no type annotations or other TypeScript-only syntax. Return the final value with `return`. Use `list_tools` and `tools_info` first to discover available tools and their interfaces.',
+      'Error handling inside the chain: a failing tool call THROWS, and the thrown error\'s `.message` holds the server\'s actual reason (e.g. a 403 with the explanation, not just a status code). If you catch it, surface `err.message` (and `err.status` / `err.data` when present) — NEVER `return { error: err }` or otherwise return the raw Error object, because an Error serializes to `{}` (its `message` is non-enumerable) and the reason is lost. If you don\'t need to handle it, just let it throw — the runtime already reports `err.message` back to you.',
+      'Large return values: if the returned value exceeds `max_output_size`, the full JSON is auto-spilled to a shared spill store (outside any workspace, never committed) and the response contains only a `__tool_chain_spill__/…` ref + a truncated marker. You can read the spill back with the regular `read_file` tool — pass that ref as `path` (its `branch` is ignored) plus `offset` / `limit` to slice it, never read a multi-MB file in full. Order of preference: (1) re-run `call_tool_chain` with a follow-up code chain that filters/maps the data inline and returns just what you need; (2) narrow the API call — shorter `fields`, tighter date window, lower `limit`; (3) last resort — `read_file` against the spill ref with `offset` / `limit`. The spill is read-only context only; do NOT use it as a way to persist KB content — for KB writes use the regular `write_file` / `edit_file` tools, which go through the lock/commit pipeline.',
+    ].join('\n\n'),
+    inputSchema: z.object({
+      code: z
+        .string()
+        .min(1)
+        .describe('JavaScript code to execute with access to all registered tools.'),
+      timeout: z
+        .number()
+        .int()
+        .min(1_000)
+        .max(120_000)
+        .optional()
+        .default(30_000)
+        .describe('Timeout in milliseconds (default: 30000).'),
+      max_output_size: z
+        .number()
+        .int()
+        .min(1_000)
+        .max(1_000_000)
+        .optional()
+        .default(200_000)
+        .describe('Max size of the stringified result in characters (default: 200000, max: 1000000). If exceeded, the full result is spilled to the shared spill store and only a `__tool_chain_spill__/…` ref is returned.'),
+    }),
+    execute: async (input) => {
+      const timeout = input.timeout ?? 30_000;
+      const maxOutputSize = input.max_output_size ?? 200_000;
+      try {
+        const { result, logs } = await client.callToolChain(input.code, timeout);
+        const json = JSON.stringify({ success: true, result, logs });
+        if (json.length <= maxOutputSize) {
+          return { success: true, result, logs };
+        }
+        const fullJson = JSON.stringify({ result, logs }, null, 2);
+        const { ref, bytes } = await spillStore.write(fullJson);
+        return {
+          success: true,
+          truncated: true,
+          result_ref: ref,
+          result_bytes: bytes,
+          message: `Combined result+logs payload was ${fullJson.length} characters (exceeded max_output_size of ${maxOutputSize}). Full JSON (both \`result\` and \`logs\`) saved to the shared spill store as \`${ref}\` (outside any workspace, uncommitted). Read it back with \`read_file\` — pass that ref as \`path\` (\`branch\` is ignored) plus \`offset\` / \`limit\` for a slice — or, usually better, narrow the next \`call_tool_chain\` call (smaller fields list, tighter date window, lower limit) so the result fits inline.`,
+        };
+      } catch (e) {
+        // A failed tool call inside the chain surfaces here. When the UTCP http
+        // transport carries the server's status + body on the thrown error
+        // (so non-2xx tool errors aren't reduced to a bare status code), pass
+        // them through to the agent — `e.message` already holds the server's
+        // reason, and `status` / `data` give it the structured detail.
+        const message = e instanceof Error ? e.message : String(e);
+        const status = (e as { status?: unknown })?.status;
+        const data = (e as { data?: unknown })?.data;
+        return {
+          success: false,
+          error: message,
+          ...(typeof status === 'number' ? { status } : {}),
+          ...(data !== undefined ? { data } : {}),
+        };
+      }
+    },
+  });
+}
+
+export function createListToolsTool(client: CodeModeUtcpClient) {
+  return createTool({
+    id: 'list_tools',
+    description: 'Returns a list of all UTCP tool names currently registered, in their TypeScript-accessible form (e.g. `manual.tool`).',
+    inputSchema: z.object({}),
+    execute: async () => {
+      const tools = await client.config.tool_repository.getTools();
+      return { tools: tools.map((t) => utcpNameToTsInterfaceName(t.name)) };
+    },
+  });
+}
+
+export function createToolsInfoTool(client: CodeModeUtcpClient) {
+  return createTool({
+    id: 'tools_info',
+    description:
+      'Get complete information about a specified list of tools, including TypeScript interface definitions. Accepts either UTCP names or sanitized TS-accessible names (from `list_tools`).',
+    inputSchema: z.object({
+      tool_names: z
+        .array(z.string())
+        .min(1)
+        .describe('Names of the tools to get complete information for.'),
+    }),
+    execute: async (input) => {
+      const interfaces: string[] = [];
+      const notFound: 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);
+        }
+      }
+      return { interfaces: interfaces.join('\n\n'), not_found: notFound };
+    },
+  });
+}

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

@@ -0,0 +1,6 @@
+export { CodeModeUtcpClient } from '@utcp/code-mode';
+export {
+  createCallToolChainTool,
+  createListToolsTool,
+  createToolsInfoTool,
+} from './code-mode.tool.js';

package/src/modules/database/connection.ts

@@ -0,0 +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>;