@bevel-software/platform-core-backend 0.14.0 → 0.19.0

package/src/modules/mcp/manual-failure-memo.ts

@@ -3,37 +3,67 @@
  *
  * Registering a `.tool` manual with a present-but-broken credential (an
  * expired OAuth session, a revoked key) fails with a live network round-trip —
- * and sessions are rebuilt constantly (every external MCP connection runs a
- * full discovery), so one stale credential otherwise re-dials its provider on
- * every build, forever. Besides the log noise, each failed attempt on the
- * MCP transport layer's long-lived shared session leaks an abort listener
- * upstream — the memo starves that loop.
+ * and the tool surface is rebuilt on every MCP request, so one stale credential
+ * otherwise re-dials its provider on every request, forever.
+ *
+ * The "manual" key is whatever the caller passes; the MCP service passes the
+ * manual's name plus a fingerprint of its definition, so editing a manual that
+ * just failed (a corrected URL in `mcp.json`) is retried on the next request
+ * instead of waiting out the TTL.
  *
  * Failures are remembered for a few minutes only: a repaired credential is
  * picked up at the next build after expiry (or immediately after a restart).
  * Successes are never cached here — this is a circuit breaker, not a catalog
- * cache. Expired entries are pruned opportunistically so the map stays
+ * cache. Expired failures are pruned opportunistically so the map stays
  * bounded by the number of DISTINCT recently-failing (user, manual) pairs.
  */
 export class ManualFailureMemo {
   private readonly failures = new Map<string, { message: string; expiresAt: number }>();
+
+  /**
+   * Out-of-order protection. Every clear takes the next value of a monotonic
+   * counter and remembers it for the scope it cleared: one pair, one user, or
+   * everyone. A registration attempt starts with {@link beginAttempt}, which
+   * captures the counter BEFORE its (slow, awaited) network call; its failure is
+   * discarded only when a clear covering THAT pair ran in between. A success of
+   * an unrelated manual, or a clear for another user, never discards it — no
+   * matter how long the attempt takes.
+   */
+  private counter = 0;
+  private allClearedAt = 0;
+  private readonly userClears = new Map<string, number>();
+  private readonly pairClears = new Map<string, number>();
   /**
-   * Advanced by every clear operation. A registration attempt captures the
-   * generation BEFORE its (slow, awaited) network call and hands it back to
-   * {@link recordFailure} — if a clear happened in between (the user just
-   * repaired the credential), the stale in-flight failure is discarded instead
-   * of resurrecting a memo entry the clear was meant to remove.
+   * Generations captured by attempts still in flight (generation → count). A
+   * clear record matters only to an attempt that started before it, so a record
+   * is kept exactly while such an attempt is running — which bounds the clear
+   * maps by what concurrent attempts can still observe.
    */
-  private generation = 0;
+  private readonly inFlight = new Map<number, number>();
 
   constructor(
     private readonly ttlMs: number = 5 * 60_000,
     private readonly now: () => number = Date.now,
   ) {}
 
-  /** Capture before an awaited registration attempt; pass to {@link recordFailure}. */
-  get currentGeneration(): number {
-    return this.generation;
+  /**
+   * Start a registration attempt. Pass the returned generation to
+   * {@link recordFailure}, and ALWAYS to {@link endAttempt} when the attempt is
+   * over (try/finally) — an attempt never ended keeps later clear records alive.
+   */
+  beginAttempt(): number {
+    const generation = this.counter;
+    this.inFlight.set(generation, (this.inFlight.get(generation) ?? 0) + 1);
+    return generation;
+  }
+
+  /** The attempt started at `generation` is over (after any `recordFailure`/`clear` it made). */
+  endAttempt(generation: number): void {
+    const count = this.inFlight.get(generation);
+    if (count === undefined) return;
+    if (count <= 1) this.inFlight.delete(generation);
+    else this.inFlight.set(generation, count - 1);
+    this.pruneClears();
   }
 
   private key(userId: string, manualName: string): string {
@@ -50,12 +80,13 @@ export class ManualFailureMemo {
   }
 
   /**
-   * Record a failure — unless `generation` (captured before the attempt) is
-   * stale, meaning a clear ran while the attempt was in flight. Dropping the
-   * record is the conservative direction: the worst case is one extra retry.
+   * Record a failure — unless `generation` (from {@link beginAttempt}) is stale
+   * for this pair, meaning a clear covering it ran while the attempt was in
+   * flight. Dropping the record is the conservative direction: the worst case
+   * is one extra retry.
    */
   recordFailure(userId: string, manualName: string, message: string, generation?: number): void {
-    if (generation !== undefined && generation !== this.generation) return;
+    if (generation !== undefined && this.clearedSince(userId, manualName, generation)) return;
     this.failures.set(this.key(userId, manualName), {
       message,
       expiresAt: this.now() + this.ttlMs,
@@ -64,8 +95,10 @@ export class ManualFailureMemo {
 
   /** Forget a pair (e.g. after a successful registration proves the credential works again). */
   clear(userId: string, manualName: string): void {
-    this.generation += 1;
-    this.failures.delete(this.key(userId, manualName));
+    const key = this.key(userId, manualName);
+    this.pairClears.set(key, this.nextGeneration());
+    this.failures.delete(key);
+    this.pruneClears();
   }
 
   /**
@@ -74,16 +107,41 @@ export class ManualFailureMemo {
    * waiting out the TTL.
    */
   clearUser(userId: string): void {
-    this.generation += 1;
+    this.userClears.set(userId, this.nextGeneration());
     const prefix = `${userId} `;
     for (const k of this.failures.keys()) {
       if (k.startsWith(prefix)) this.failures.delete(k);
     }
+    this.pruneClears();
   }
 
   /** Forget everything — a SHARED secret changed, which can affect any user. */
   clearAll(): void {
-    this.generation += 1;
+    this.allClearedAt = this.nextGeneration();
     this.failures.clear();
   }
+
+  private nextGeneration(): number {
+    this.counter += 1;
+    return this.counter;
+  }
+
+  private clearedSince(userId: string, manualName: string, generation: number): boolean {
+    return (
+      this.allClearedAt > generation ||
+      (this.userClears.get(userId) ?? 0) > generation ||
+      (this.pairClears.get(this.key(userId, manualName)) ?? 0) > generation
+    );
+  }
+
+  /** Drop clear records no in-flight attempt predates: none of them can ever be consulted again. */
+  private pruneClears(): void {
+    let oldest = Infinity;
+    for (const generation of this.inFlight.keys()) oldest = Math.min(oldest, generation);
+    for (const clears of [this.userClears, this.pairClears]) {
+      for (const [k, generation] of clears) {
+        if (generation <= oldest) clears.delete(k);
+      }
+    }
+  }
 }

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

@@ -1,8 +1,12 @@
 import type { Request, Response, NextFunction } from 'express';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('mcp-auth');
 import { InvalidTokenError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
 import type { AuthService } from '../auth/auth.service.js';
 import type { IExternalApiKeyService } from '../tool-auth/external-api-key.interface.js';
 import type { InternalTokenService } from '../tool-auth/internal-token.service.js';
+import { rejectConnectionKey } from '../tool-auth/connection-key-rejection.js';
 import type { BevelOAuthProvider } from './oauth/bevel-oauth-provider.js';
 import '../tool-auth/external-api-key.interface.js'; // Express Request augmentation (req.externalApiKeyId)
 
@@ -15,7 +19,8 @@ import '../tool-auth/external-api-key.interface.js'; // Express Request augmenta
  *      authorization server after the /connect consent flow, resolved via
  *      BevelOAuthProvider.
  *   3. An internal token (Bearer `<tenant>-int_…`) — minted server-side only
- *      (createSession's loopback bearer, the /mcp/local-token exchange). The
+ *      (the per-request loopback bearer `createRequestServer` mints, the
+ *      /mcp/local-token exchange). The
  *      local MCP server (hexis-mcp) exchanges its OAuth grant for one and
  *      then uses it EVERYWHERE a connection key goes — the agent REST surface
  *      already accepts it, and refusing it here made OAuth-mode hexis-mcp
@@ -28,13 +33,16 @@ import '../tool-auth/external-api-key.interface.js'; // Express Request augmenta
  *      hit the MCP endpoint from their browser if we ever need it
  *      (e.g. an in-app debugger). Keeps the surface from forking.
  *
- * The middleware **must** run before the MCP transport handler — the
- * transport pulls `req.userId` to populate the session row at `initialize`.
+ * The middleware **must** run before the MCP transport handler — every
+ * request's server is built from `req.userId` (there is no session row to
+ * carry it; the endpoint is stateless per request).
  *
  * Failures return 401 with a `WWW-Authenticate` challenge carrying
  * `resource_metadata` (RFC 9728) so an OAuth-capable MCP client discovers our
- * authorization server and starts the flow, while clients configured with a
- * key simply prompt for it.
+ * authorization server and starts the flow — EXCEPT a bearer shaped like a
+ * connection key that does not verify: that caller configured a key, so it
+ * gets a plain `invalid_token` answer and no sign-in invitation (see
+ * `connection-key-rejection.ts`).
  */
 export function createMcpAuthMiddleware(
   authService: AuthService,
@@ -77,7 +85,7 @@ export function createMcpAuthMiddleware(
         // `externalApiKeyId` unset and are not metered.
         const resolved = await externalApiKeyService.verifyAndLoadToken(token);
         if (!resolved) {
-          unauthorized(res, 'Invalid or revoked connection key');
+          rejectConnectionKey(res);
           return;
         }
         req.userId = resolved.user.id;
@@ -88,7 +96,7 @@ export function createMcpAuthMiddleware(
       } catch (err) {
         // A DB error during verification is a 500, not a 401 — the caller's
         // credentials may be valid; we just can't check them right now.
-        console.error('[mcp-auth] connection-key verification failed:', err);
+        log.error('connection-key verification failed:', { err });
         res.status(500).json({ error: 'Authentication backend unavailable' });
         return;
       }
@@ -111,7 +119,7 @@ export function createMcpAuthMiddleware(
         if (err instanceof InvalidTokenError) {
           unauthorized(res, 'Invalid, expired, or revoked access token');
         } else {
-          console.error('[mcp-auth] OAuth token verification failed:', err);
+          log.error('OAuth token verification failed:', { err });
           res.status(500).json({ error: 'Authentication backend unavailable' });
         }
         return;
@@ -130,13 +138,14 @@ export function createMcpAuthMiddleware(
     // downstream resolve access against it.
     //
     // ONLY the `externalProxy` shape is admitted: that claim marks the
-    // loopback identity of an external caller (createSession's session
-    // bearer, the /mcp/local-token exchange), which is the one internal-token
-    // kind that has any business arriving here as an MCP client. A plain
-    // in-process internal token — the per-run credential the agent factory
-    // mints for its own code-mode client — is a loopback-surface credential,
-    // and accepting it would let it open an MCP session (createSession would
-    // even mint it a fresh externalProxy bearer, upgrading it).
+    // loopback identity of an external caller (the per-request bearer
+    // `createRequestServer` mints, the /mcp/local-token exchange), which is
+    // the one internal-token kind that has any business arriving here as an
+    // MCP client. A plain in-process internal token — the per-run credential
+    // the agent factory mints for its own code-mode client — is a
+    // loopback-surface credential, and accepting it would let it drive the
+    // MCP endpoint (createRequestServer would even mint it a fresh
+    // externalProxy bearer, upgrading it).
     if (internalTokens.looksLikeInternalToken(token)) {
       // `verify` answers null for the invalid/expired cases it can see coming,
       // but a malformed token of plausible shape can still THROW from inside
@@ -157,7 +166,7 @@ export function createMcpAuthMiddleware(
       try {
         user = await authService.getUserById(claim.userId);
       } catch (err) {
-        console.error('[mcp-auth] internal-token user lookup failed:', err);
+        log.error('internal-token user lookup failed:', { err });
         res.status(500).json({ error: 'Authentication backend unavailable' });
         return;
       }