@bevel-software/platform-core-backend 0.1.0

package/src/modules/tool-auth/external-api-key.service.ts

@@ -0,0 +1,209 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { and, desc, eq, isNotNull, isNull } from 'drizzle-orm';
+import type { AuthUser } from '@bevel-software/platform-shared';
+import type { Database } from '../database/connection.js';
+import { externalApiKeys, users } from '../database/schema.js';
+import {
+  InvalidTokenLabelError,
+  TokenNotFoundError,
+  TokenStillActiveError,
+} from './external-api-key.errors.js';
+import type {
+  ExternalApiKeySummary,
+  IExternalApiKeyService,
+  MintedExternalApiKey,
+} from './external-api-key.interface.js';
+
+// Plaintext format: `<tenant>_<43 base64url chars>`. 32 random bytes encoded
+// base64url is 43 chars and gives 256 bits of entropy — overkill against
+// brute force, cheap to copy. The tenant prefix (default `bevel_`) lets the
+// auth middleware route key-vs-JWT requests without parsing both shapes.
+const TOKEN_BYTES = 32;
+
+const MAX_LABEL_LEN = 200;
+
+export class ExternalApiKeyService implements IExternalApiKeyService {
+  /**
+   * @param keyPrefix Tenant-derived plaintext prefix (e.g. `bevel_`) — injected
+   *   from {@link AppConfig.externalApiKeyPrefix} so a deploy can brand its keys.
+   */
+  constructor(
+    private readonly db: Database,
+    private readonly keyPrefix: string,
+  ) {}
+
+  /** True if a bearer string carries this tenant's external-API-key prefix. */
+  looksLikeExternalApiKey(token: string): boolean {
+    return typeof token === 'string' && token.startsWith(this.keyPrefix);
+  }
+
+  async mint(userId: string, label: string): Promise<MintedExternalApiKey> {
+    const trimmed = (label ?? '').trim();
+    if (trimmed.length === 0) {
+      throw new InvalidTokenLabelError('Label cannot be empty');
+    }
+    if (trimmed.length > MAX_LABEL_LEN) {
+      throw new InvalidTokenLabelError(
+        `Label cannot exceed ${MAX_LABEL_LEN} characters`,
+      );
+    }
+
+    const plaintext = this.keyPrefix + randomBytes(TOKEN_BYTES).toString('base64url');
+    const tokenHash = hashToken(plaintext);
+
+    const [row] = await this.db
+      .insert(externalApiKeys)
+      .values({ userId, tokenHash, label: trimmed })
+      .returning();
+
+    return {
+      plaintext,
+      summary: toSummary(row),
+    };
+  }
+
+  async verifyAndLoadUser(plaintext: string): Promise<AuthUser | null> {
+    const resolved = await this.verifyAndLoadToken(plaintext);
+    return resolved ? resolved.user : null;
+  }
+
+  async verifyAndLoadToken(
+    plaintext: string,
+  ): Promise<{ tokenId: string; user: AuthUser } | null> {
+    if (!this.looksLikeExternalApiKey(plaintext)) {
+      return null;
+    }
+    const tokenHash = hashToken(plaintext);
+
+    // Join users so a single round-trip resolves both "token is valid" and
+    // "load the user it belongs to". The unique index on token_hash makes
+    // this a point-lookup. `isNull(revokedAt)` is what enforces revocation
+    // — the row remains for audit.
+    const [row] = await this.db
+      .select({
+        tokenId: externalApiKeys.id,
+        userId: users.id,
+        email: users.email,
+        name: users.name,
+        avatarUrl: users.avatarUrl,
+      })
+      .from(externalApiKeys)
+      .innerJoin(users, eq(externalApiKeys.userId, users.id))
+      .where(and(eq(externalApiKeys.tokenHash, tokenHash), isNull(externalApiKeys.revokedAt)))
+      .limit(1);
+
+    if (!row) return null;
+
+    // Fire-and-forget so verification latency is bounded by the SELECT, not
+    // the UPDATE. A failed touch is logged but never blocks the caller —
+    // the worst case is a slightly stale `last_used_at`, which is fine for
+    // a "when was this key last used" audit view.
+    this.touchLastUsed(row.tokenId).catch((err) => {
+      console.warn('[external-api-key] touchLastUsed failed:', err);
+    });
+
+    return {
+      tokenId: row.tokenId,
+      user: {
+        id: row.userId,
+        email: row.email,
+        name: row.name,
+        avatarUrl: row.avatarUrl ?? undefined,
+      },
+    };
+  }
+
+  async listForUser(userId: string): Promise<ExternalApiKeySummary[]> {
+    const rows = await this.db
+      .select()
+      .from(externalApiKeys)
+      .where(eq(externalApiKeys.userId, userId))
+      .orderBy(desc(externalApiKeys.createdAt));
+    return rows.map(toSummary);
+  }
+
+  async revoke(id: string, userId: string): Promise<void> {
+    // Scope the WHERE by userId so a user can never revoke another user's
+    // token even if they learn the id. Idempotent on already-revoked rows
+    // because we only set `revokedAt` when it's currently null — re-revoking
+    // returns 0 rows changed but no error.
+    const result = await this.db
+      .update(externalApiKeys)
+      .set({ revokedAt: new Date() })
+      .where(
+        and(
+          eq(externalApiKeys.id, id),
+          eq(externalApiKeys.userId, userId),
+          isNull(externalApiKeys.revokedAt),
+        ),
+      )
+      .returning({ id: externalApiKeys.id });
+
+    if (result.length === 0) {
+      // Distinguish "doesn't exist / not yours" from "already revoked".
+      // The latter must stay idempotent (return success); only the former
+      // throws.
+      const [existing] = await this.db
+        .select({ id: externalApiKeys.id })
+        .from(externalApiKeys)
+        .where(and(eq(externalApiKeys.id, id), eq(externalApiKeys.userId, userId)))
+        .limit(1);
+      if (!existing) {
+        throw new TokenNotFoundError();
+      }
+    }
+  }
+
+  async remove(id: string, userId: string): Promise<void> {
+    // Only revoked rows may be hard-deleted — deleting an active key would
+    // silently cut off a live agent. Scope by userId so a user can only
+    // delete their own tokens. Validate first (so we can return a precise
+    // not-found vs still-active error), then delete inside a transaction.
+    const [existing] = await this.db
+      .select({ revokedAt: externalApiKeys.revokedAt })
+      .from(externalApiKeys)
+      .where(and(eq(externalApiKeys.id, id), eq(externalApiKeys.userId, userId)))
+      .limit(1);
+    if (!existing) {
+      throw new TokenNotFoundError();
+    }
+    if (existing.revokedAt === null) {
+      // Exists and is yours, but wasn't revoked — refuse rather than delete.
+      throw new TokenStillActiveError();
+    }
+
+    // Dependents (e.g. the enterprise LLM-usage metering rows) hang off this
+    // row via ON DELETE CASCADE foreign keys, so a bare delete takes any audit
+    // trail with it — this service doesn't have to know those tables exist.
+    await this.db
+      .delete(externalApiKeys)
+      .where(
+        and(
+          eq(externalApiKeys.id, id),
+          eq(externalApiKeys.userId, userId),
+          isNotNull(externalApiKeys.revokedAt),
+        ),
+      );
+  }
+
+  private async touchLastUsed(tokenId: string): Promise<void> {
+    await this.db
+      .update(externalApiKeys)
+      .set({ lastUsedAt: new Date() })
+      .where(eq(externalApiKeys.id, tokenId));
+  }
+}
+
+function hashToken(plaintext: string): string {
+  return createHash('sha256').update(plaintext).digest('hex');
+}
+
+function toSummary(row: typeof externalApiKeys.$inferSelect): ExternalApiKeySummary {
+  return {
+    id: row.id,
+    label: row.label,
+    createdAt: row.createdAt.getTime(),
+    lastUsedAt: row.lastUsedAt ? row.lastUsedAt.getTime() : null,
+    revokedAt: row.revokedAt ? row.revokedAt.getTime() : null,
+  };
+}

package/src/modules/tool-auth/internal-token.service.ts

@@ -0,0 +1,124 @@
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+
+/**
+ * What an internal token authorizes: a user identity, nothing more. Minted when
+ * an agent's code-mode client is built and seeded into that client's UTCP config.
+ * Deliberately identity-only — the SAME shape a `bevel_…` connection key resolves
+ * to: the workspace is chosen per call from the tool's `branch` argument, and the
+ * scope is always write (the middleware sets it, exactly as for connection keys).
+ */
+export interface InternalTokenClaim {
+  userId: string;
+  /**
+   * The agent run / conversation id (the Mastra thread id) this token is scoped
+   * to, when minted per-run. Surfaced as `ToolContext.sessionId` so the
+   * ontology-session boundary can scope to one run for the in-process agent
+   * (the external/MCP path carries `sessionId` on the tool body instead).
+   * Absent for identity-only tokens.
+   */
+  sessionId?: string;
+  /**
+   * True when this token is the LOOPBACK identity of an external caller — the
+   * MCP proxy mints one per OAuth/JWT MCP session (which has no `bevel_…`
+   * connection key to pass through). The verifier resolves such tokens to
+   * `source: 'external'`: the caller IS an external agent, and must be treated
+   * like one everywhere — admitted to external-only surfaces (`start_session`,
+   * `ask`), refused from internal-only ones (`execute_command`, …), and
+   * expected to carry `sessionId` on the tool body, not in the token.
+   */
+  externalProxy?: boolean;
+}
+
+interface SignedPayload extends InternalTokenClaim {
+  /** Expiry, epoch ms. */
+  exp: number;
+}
+
+const DEFAULT_PREFIX = 'bevel-int_';
+
+function b64url(buf: Buffer): string {
+  return buf.toString('base64url');
+}
+
+/**
+ * Mints + verifies stateless HMAC internal tokens. No DB: the token is
+ * self-contained `(claim, exp)` signed with a process secret, so it is
+ * multi-replica safe for verification within a deploy and costs nothing to
+ * issue. Tokens carry only `userId` and are short-lived; the agent factory
+ * mints one per code-mode client (per user).
+ *
+ * Distinct from connection keys (`bevel_…`, long-lived, user-wide): internal
+ * tokens are the least-privilege credential for the in-process loopback surface
+ * and are rejected by the external endpoints, and vice-versa.
+ */
+export class InternalTokenService {
+  private readonly secret: Buffer;
+  private readonly ttlMs: number;
+  private readonly now: () => number;
+  private readonly prefix: string;
+
+  constructor(
+    opts: { secret?: string; ttlMs?: number; now?: () => number; prefix?: string } = {},
+  ) {
+    // A per-boot random secret is fine: tokens are minted per turn-ish and
+    // re-minted after a restart. A caller may inject a stable secret (tests, or
+    // a future multi-replica deploy) instead.
+    this.secret = opts.secret ? Buffer.from(opts.secret, 'utf8') : randomBytes(32);
+    this.ttlMs = opts.ttlMs ?? 60 * 60 * 1000; // 1h
+    this.now = opts.now ?? Date.now;
+    // Tenant-derived prefix (default `bevel-int_`), injected from
+    // AppConfig.internalTokenPrefix so internal tokens brand with the deploy's tenant.
+    this.prefix = opts.prefix ?? DEFAULT_PREFIX;
+  }
+
+  /** Token lifetime in ms — so callers caching a minted token can refresh it before expiry. */
+  get tokenTtlMs(): number {
+    return this.ttlMs;
+  }
+
+  /** @param ttlMs Override the default lifetime — e.g. the MCP proxy mints
+   *   session-loopback tokens that must outlive its 4h session idle TTL. */
+  mint(claim: InternalTokenClaim, ttlMs?: number): string {
+    const payload: SignedPayload = { ...claim, exp: this.now() + (ttlMs ?? this.ttlMs) };
+    const body = b64url(Buffer.from(JSON.stringify(payload), 'utf8'));
+    const sig = b64url(this.sign(body));
+    return `${this.prefix}${body}.${sig}`;
+  }
+
+  /** Returns the claim for a valid, unexpired token; null otherwise. */
+  verify(token: string): InternalTokenClaim | null {
+    if (!this.looksLikeInternalToken(token)) return null;
+    const rest = token.slice(this.prefix.length);
+    const dot = rest.indexOf('.');
+    if (dot < 0) return null;
+    const body = rest.slice(0, dot);
+    const sig = rest.slice(dot + 1);
+
+    const expected = b64url(this.sign(body));
+    if (sig.length !== expected.length) return null;
+    if (!timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) return null;
+
+    let payload: SignedPayload;
+    try {
+      payload = JSON.parse(Buffer.from(body, 'base64url').toString('utf8'));
+    } catch {
+      return null;
+    }
+    if (typeof payload.exp !== 'number' || payload.exp < this.now()) return null;
+    if (typeof payload.userId !== 'string') return null;
+    return {
+      userId: payload.userId,
+      ...(typeof payload.sessionId === 'string' ? { sessionId: payload.sessionId } : {}),
+      ...(payload.externalProxy === true ? { externalProxy: true } : {}),
+    };
+  }
+
+  /** True if the bearer string looks like an internal token (vs an external API key). */
+  looksLikeInternalToken(token: string): boolean {
+    return token.startsWith(this.prefix);
+  }
+
+  private sign(body: string): Buffer {
+    return createHmac('sha256', this.secret).update(body).digest();
+  }
+}

package/src/modules/tool-auth/llm-usage-meter.ts

@@ -0,0 +1,19 @@
+/**
+ * Metering view over connection-key LLM usage, consumed by the connection-key
+ * management routes (mcp) to show each key's spend against the daily budget.
+ * The enterprise LLM proxy's `LlmUsageService` satisfies this structurally; a
+ * core-only deployment (no LLM proxy, nothing to meter) passes
+ * {@link unmeteredLlmUsage}.
+ */
+export interface ILlmUsageMeter {
+  /** Daily per-key token cap shown in the UI, or null when unmetered. */
+  readonly dailyCap: number | null;
+  /** Today's usage per key id, as `{ [tokenId]: tokens }` — missing keys mean 0. */
+  usageForTokens(tokenIds: string[]): Promise<Record<string, number>>;
+}
+
+/** Core default: no proxy, no metering — every key reads as unused/uncapped. */
+export const unmeteredLlmUsage: ILlmUsageMeter = {
+  dailyCap: null,
+  usageForTokens: async () => ({}),
+};

package/src/modules/tool-auth/tool-auth.middleware.ts

@@ -0,0 +1,220 @@
+import type { Request, Response, NextFunction, RequestHandler } from 'express';
+import type { IExternalApiKeyService } from './external-api-key.interface.js';
+import type { AuthService } from '../auth/auth.service.js';
+import { InternalTokenService } from './internal-token.service.js';
+
+/**
+ * What the `toolAuth` middleware resolves a bearer to, before the per-call
+ * `ToolContext` is built. Internal and external are now the SAME shape — a user
+ * identity at write scope — resolving through one path; `source` only records
+ * which credential authenticated (so internal-only routes can be gated):
+ *  - `external`: a `bevel_…` connection key → user.
+ *  - `internal`: an identity-only HMAC token minted for an agent's code-mode client.
+ *  - `session`: a browser JWT — admitted ONLY on the read-only manual endpoint
+ *    (`createManualAuthMiddleware`), never on a tool-execution route, so it can
+ *    browse the catalog but cannot invoke tools.
+ * The workspace is chosen per call from the tool's `branch` argument (downstream
+ * ACL / protected-branch checks gate writes).
+ */
+export interface ToolAuth {
+  source: 'internal' | 'external' | 'session';
+  userId: string;
+  tokenId?: string;
+  /** The agent run id carried by a per-run internal token (in-process agent). The external path supplies `sessionId` on the tool body instead. */
+  sessionId?: string;
+  /** Always `'write'` now (the middleware sets it for both internal + external — neither credential carries scope). The read path is dormant until consumer agents are removed. */
+  scope: 'read' | 'write';
+}
+
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace Express {
+    interface Request {
+      toolAuth?: ToolAuth;
+    }
+  }
+}
+
+const WWW_AUTH = 'Bearer realm="bevel-tools"';
+
+/**
+ * Gate that admits ONLY in-process callers (those bearing an internal HMAC
+ * token). Mount it AFTER `toolAuth` on every internal-only surface — the
+ * internal tool catalog and the routes of tools registered with
+ * `registerInternalTool` but NOT `registerExternalTool` (e.g. `execute_command`,
+ * `switch_branch`, the `sharepoint_*` reads). `toolAuth` alone is not enough:
+ * an external connection key authenticates successfully, so without this gate it
+ * could invoke an internal-only route directly by guessing its name. The route
+ * MUST stay mounted (our own agent reaches it over the same loopback HTTP), so
+ * the restriction has to be enforced here at request time, not by hiding the
+ * route. 403 (authenticated, but not authorized for this surface).
+ */
+export const requireInternalSource: RequestHandler = (req, res, next) => {
+  if (req.toolAuth?.source !== 'internal') {
+    res.status(403).json({ error: 'This tool is internal-only.' });
+    return;
+  }
+  next();
+};
+
+/**
+ * Mirror of `requireInternalSource` for surfaces that must admit ONLY external
+ * callers. `start_session` mints a fresh chat thread as the caller's
+ * ontology-session id; an internal (in-process agent) token already carries
+ * its run's `sessionId`, so letting it mint a new thread mid-run would
+ * silently reset the one-ontology-per-conversation boundary.
+ *
+ * "External" is decided by the VERIFIER, not by which credential shape
+ * authenticated: a `bevel_…` connection key resolves external, and so does an
+ * `externalProxy` internal token — the loopback identity the MCP proxy mints
+ * for an OAuth/JWT MCP session, whose caller IS an external agent. (Gating on
+ * the raw credential shape used to 403 those sessions here, deadlocking them:
+ * they couldn't mint a sessionId, and every session-gated tool demands one.)
+ * Mount AFTER `toolAuth`. 403 (authenticated, but not authorized).
+ */
+export const requireExternalSource: RequestHandler = (req, res, next) => {
+  if (req.toolAuth?.source !== 'external') {
+    res.status(403).json({ error: 'This tool is external-only.' });
+    return;
+  }
+  next();
+};
+
+/** Outcome of verifying a bearer token — either a normalized identity or a status+message to surface. */
+export type VerifyResult =
+  | { ok: true; auth: ToolAuth }
+  | { ok: false; status: number; message: string };
+
+/**
+ * The framework-agnostic verify core: bearer token (the value AFTER `Bearer `) →
+ * normalized `ToolAuth`, accepting EITHER a `bevel_…` connection key (external —
+ * pipeline-agent, MCP) OR an internal HMAC token (our own agent's loopback). A
+ * bare JWT / unknown scheme is refused. Throws only if the connection-key store
+ * itself errors (backend down); the caller maps that to 500. This is the shared
+ * primitive both `createToolAuthMiddleware` (our Express hosting) and
+ * `validateToken` (the tool-author SDK) are built on, so there is ONE auth path.
+ */
+export function createTokenVerifier(
+  externalApiKeyService: IExternalApiKeyService,
+  internalTokenService: InternalTokenService,
+): (token: string | undefined) => Promise<VerifyResult> {
+  const missing = { ok: false as const, status: 401, message: 'A connection key or internal token is required' };
+  return async (token) => {
+    if (!token) return missing;
+
+    // Internal token → in-process loopback caller. Usually our own agent
+    // (source 'internal'), EXCEPT the `externalProxy` tokens the MCP proxy
+    // mints as the loopback identity of an OAuth/JWT MCP session — that
+    // caller is an external agent and resolves as one, so external-only
+    // surfaces admit it and internal-only surfaces refuse it, exactly like a
+    // connection key (it just has no tokenId to meter on).
+    if (internalTokenService.looksLikeInternalToken(token)) {
+      const claim = internalTokenService.verify(token);
+      if (!claim) return { ok: false, status: 401, message: 'Invalid or expired internal token' };
+      return claim.externalProxy
+        ? { ok: true, auth: { source: 'external', userId: claim.userId, scope: 'write' } }
+        : { ok: true, auth: { source: 'internal', userId: claim.userId, sessionId: claim.sessionId, scope: 'write' } };
+    }
+
+    // External API key → external caller. (verifyAndLoadToken may throw → propagates → caller maps to 500.)
+    if (externalApiKeyService.looksLikeExternalApiKey(token)) {
+      const resolved = await externalApiKeyService.verifyAndLoadToken(token);
+      return resolved
+        ? { ok: true, auth: { source: 'external', userId: resolved.user.id, tokenId: resolved.tokenId, scope: 'write' } }
+        : { ok: false, status: 401, message: 'Invalid or revoked connection key' };
+    }
+
+    return missing;
+  };
+}
+
+/**
+ * The one auth gate every tool endpoint applies — a THIN Express adapter over
+ * `createTokenVerifier`: parse the bearer header, run the shared verify core,
+ * normalize the result to `req.toolAuth` (or the matching status). All auth logic
+ * lives in the verifier; this only does header parsing + HTTP mapping.
+ */
+export function createToolAuthMiddleware(
+  externalApiKeyService: IExternalApiKeyService,
+  internalTokenService: InternalTokenService,
+): RequestHandler {
+  const verify = createTokenVerifier(externalApiKeyService, internalTokenService);
+  return async (req: Request, res: Response, next: NextFunction) => {
+    const header = req.headers.authorization;
+    if (!header || !header.toLowerCase().startsWith('bearer ')) {
+      res.setHeader('WWW-Authenticate', WWW_AUTH);
+      res.status(401).json({ error: 'Missing or invalid Authorization header' });
+      return;
+    }
+    const token = header.slice(header.indexOf(' ') + 1).trim();
+    try {
+      const result = await verify(token);
+      if (!result.ok) {
+        if (result.status === 401) res.setHeader('WWW-Authenticate', WWW_AUTH);
+        res.status(result.status).json({ error: result.message });
+        return;
+      }
+      req.toolAuth = result.auth;
+      next();
+    } catch (err) {
+      console.error('[tools] connection-key verification failed:', err);
+      res.status(500).json({ error: 'Authentication backend unavailable' });
+    }
+  };
+}
+
+/**
+ * Auth gate for the READ-ONLY discovery manuals (`GET /agent/utcp` +
+ * `/agent/internal/utcp`) ONLY. Superset of `createToolAuthMiddleware`: it
+ * accepts a `bevel_…` connection key, an internal token, OR a browser JWT —
+ * the last resolving to `source: 'session'`. This is what lets a logged-in user
+ * browse the catalog with their existing session (the manual is just a spec, no
+ * secrets, and may become per-user — hence one user-aware endpoint rather than a
+ * parallel route). It is deliberately NOT used on tool-execution routes, so a
+ * JWT can read the manual but can never invoke a tool. The internal manual stays
+ * `requireInternalSource`-gated downstream, so a session/key is 403'd there.
+ */
+export function createManualAuthMiddleware(
+  externalApiKeyService: IExternalApiKeyService,
+  internalTokenService: InternalTokenService,
+  authService: AuthService,
+): RequestHandler {
+  const verify = createTokenVerifier(externalApiKeyService, internalTokenService);
+  return async (req: Request, res: Response, next: NextFunction) => {
+    const header = req.headers.authorization;
+    if (!header || !header.toLowerCase().startsWith('bearer ')) {
+      res.setHeader('WWW-Authenticate', WWW_AUTH);
+      res.status(401).json({ error: 'Missing or invalid Authorization header' });
+      return;
+    }
+    const token = header.slice(header.indexOf(' ') + 1).trim();
+
+    // An external API key / internal token goes through the shared verify core.
+    if (internalTokenService.looksLikeInternalToken(token) || externalApiKeyService.looksLikeExternalApiKey(token)) {
+      try {
+        const result = await verify(token);
+        if (!result.ok) {
+          if (result.status === 401) res.setHeader('WWW-Authenticate', WWW_AUTH);
+          res.status(result.status).json({ error: result.message });
+          return;
+        }
+        req.toolAuth = result.auth;
+        next();
+      } catch (err) {
+        console.error('[tools] connection-key verification failed:', err);
+        res.status(500).json({ error: 'Authentication backend unavailable' });
+      }
+      return;
+    }
+
+    // Otherwise treat the bearer as a browser session JWT.
+    try {
+      const { userId } = authService.verifyToken(token);
+      req.toolAuth = { source: 'session', userId, scope: 'write' };
+      next();
+    } catch {
+      res.setHeader('WWW-Authenticate', WWW_AUTH);
+      res.status(401).json({ error: 'Invalid or expired token' });
+    }
+  };
+}