@bevel-software/platform-core-backend 0.15.1 → 0.20.0

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

@@ -31,8 +31,23 @@ export interface ExternalApiKeySummary {
   createdAt: number;
   lastUsedAt: number | null;
   revokedAt: number | null;
+  /**
+   * Who ended it, once `revokedAt` is set: the owner themselves, or an admin
+   * from the deployment overview. Null while live (and on rows revoked
+   * before this was recorded, which read as the owner's doing).
+   */
+  revokedBy: RevokedBy | null;
+  /**
+   * When the owner deleted the key for good from their own pages. Such a
+   * key is absent from the owner's listings and shown to admins as deleted;
+   * its row stays so the Audit log's events keep their principal.
+   */
+  deletedAt: number | null;
 }
 
+/** Who revoked a key: its owner, or an admin acting across the deployment. */
+export type RevokedBy = 'owner' | 'admin';
+
 /**
  * Result of minting a new connection key. `plaintext` is shown to the user
  * once (with a "you won't see this again" warning); the stored DB row only
@@ -43,14 +58,42 @@ export interface MintedExternalApiKey {
   summary: ExternalApiKeySummary;
 }
 
+/**
+ * One row of the admin "Connection keys" overview: a key summary plus the
+ * account it belongs to. Deployment-wide, so unlike {@link ExternalApiKeySummary}
+ * the owner is not implied by the caller.
+ */
+export interface AdminExternalApiKeySummary extends ExternalApiKeySummary {
+  user: {
+    id: string;
+    email: string;
+    name: string;
+  };
+}
+
 /** The kind of a key a person creates by hand. */
 export const DEFAULT_KEY_KIND = 'key';
 
+/**
+ * How the plaintext of one kind of key is spelled: the prefix the outside
+ * world sees (and that routes the bearer back here), and the shape of the
+ * random part after it. `base64url` is the platform's own — 43 characters
+ * from a 32-byte draw. `github-token` is what a GitHub OAuth token looks
+ * like after its `gho_`: letters and digits only, 40 of them, so a consumer
+ * that validates the shape of a GitHub token (they are documented as
+ * alphanumeric) keeps it. Both hash the same way; the shape is only what a
+ * client is shown.
+ */
+export interface KeyKindSpec {
+  prefix: string;
+  shape?: 'base64url' | 'github-token';
+}
+
 /**
  * How a key is minted. `kind` names one of the kinds the service was built
- * with, each of which carries its own plaintext prefix (the tenant's for the
- * default kind, `gho_` for a Claude link); an unknown kind is refused, since
- * nothing would route its bearer back.
+ * with, each of which carries its own spelling (the tenant's prefix for the
+ * default kind, a GitHub-shaped token for a Claude link); an unknown kind is
+ * refused, since nothing would route its bearer back.
  */
 export interface MintOptions {
   kind?: string;
@@ -100,6 +143,13 @@ export interface IExternalApiKeyService {
   /** Active + revoked tokens for the user, newest-first. */
   listForUser(userId: string): Promise<ExternalApiKeySummary[]>;
 
+  /**
+   * The account a key belongs to, live or revoked, or null when no such key
+   * exists. The ownership check behind a per-key read or revoke that is
+   * offered to owners and admins alike (the Audit log's).
+   */
+  ownerOf(id: string): Promise<string | null>;
+
   /**
    * Mark a token revoked. Idempotent — revoking an already-revoked token
    * is a no-op (the row's `revokedAt` is not overwritten). Throws
@@ -108,11 +158,31 @@ export interface IExternalApiKeyService {
   revoke(id: string, userId: string): Promise<void>;
 
   /**
-   * Permanently delete a token row, dropping its audit trail. Only permitted
-   * on an already-revoked token — an active key must be disconnected first,
-   * so a live agent's access is never yanked by a single click. Throws
-   * TokenNotFoundError if the token doesn't belong to the user, and
-   * TokenStillActiveError if it hasn't been revoked yet.
+   * Every token on the deployment, active and revoked, with its owner —
+   * the admin overview. Ordered by owner email, then newest-first, so the
+   * caller can group per account without re-sorting.
+   */
+  listForDeployment(): Promise<AdminExternalApiKeySummary[]>;
+
+  /**
+   * Admin revoke: mark a token revoked WITHOUT scoping by owner, recording
+   * `revokedBy: 'admin'` so the owner's page can say it was taken rather than
+   * disconnected. Same idempotency as {@link revoke}; throws
+   * TokenNotFoundError when no such token exists. Only reachable through an
+   * admin-gated route — the per-user route must keep using {@link revoke}.
+   */
+  revokeAny(id: string): Promise<void>;
+
+  /**
+   * Delete a token for good, from the owner's point of view: it leaves their
+   * listings and can never be used or reconnected. The row itself stays,
+   * marked deleted, so the Audit log keeps the key's events under their
+   * principal — a log its subject could erase would not be one. Only
+   * permitted on an already-revoked token — an active key must be
+   * disconnected first, so a live agent's access is never yanked by a single
+   * click. Throws TokenNotFoundError if the token doesn't belong to the user
+   * (or is already deleted), and TokenStillActiveError if it hasn't been
+   * revoked yet.
    */
   remove(id: string, userId: string): Promise<void>;
 }

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

@@ -1,5 +1,8 @@
 import { createHash, randomBytes } from 'node:crypto';
-import { and, desc, eq, isNotNull, isNull } from 'drizzle-orm';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('external-api-key');
+import { and, asc, desc, eq, isNotNull, isNull, type SQL } 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';
@@ -10,9 +13,12 @@ import {
 } from './external-api-key.errors.js';
 import {
   DEFAULT_KEY_KIND,
+  type AdminExternalApiKeySummary,
   type ExternalApiKeySummary,
   type IExternalApiKeyService,
+  type KeyKindSpec,
   type MintOptions,
+  type RevokedBy,
   type MintedExternalApiKey,
 } from './external-api-key.interface.js';
 
@@ -21,6 +27,9 @@ import {
 // brute force, cheap to copy. The prefix lets the auth middleware route
 // key-vs-JWT requests without parsing both shapes.
 const TOKEN_BYTES = 32;
+// A GitHub-shaped token: 20 random bytes as 40 hex digits — alphanumeric,
+// as GitHub's own are, and 160 bits, which a hash lookup never exhausts.
+const GITHUB_TOKEN_BYTES = 20;
 
 const MAX_LABEL_LEN = 200;
 
@@ -31,19 +40,19 @@ 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.
    *   Every key of the default kind is minted with it.
-   * @param kinds Other kinds a key may be minted as, each with the plaintext
-   *   prefix that kind is spelled with — a Claude link's `gho_`, the shape
-   *   claude.ai expects from a GitHub host. Same key, same table, same
+   * @param kinds Other kinds a key may be minted as, each with the spelling
+   *   that kind has — a Claude link's `gho_` and GitHub's alphabet, the
+   *   shape claude.ai expects from a GitHub host. Same key, same table, same
    *   revocation; the KIND is stored on the row and is what tells such keys
-   *   apart (a label is the person's to edit), the prefix is only what the
+   *   apart (a label is the person's to edit), the spelling is only what the
    *   outside world sees and what routes the bearer back here.
    */
   constructor(
     private readonly db: Database,
     private readonly keyPrefix: string,
-    private readonly kinds: Readonly<Record<string, string>> = {},
+    private readonly kinds: Readonly<Record<string, KeyKindSpec>> = {},
   ) {
-    this.prefixes = [keyPrefix, ...Object.values(kinds)];
+    this.prefixes = [keyPrefix, ...Object.values(kinds).map((k) => k.prefix)];
   }
 
   /** True if a bearer string carries one of this service's key prefixes. */
@@ -53,8 +62,8 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
 
   async mint(userId: string, label: string, options: MintOptions = {}): Promise<MintedExternalApiKey> {
     const kind = options.kind ?? DEFAULT_KEY_KIND;
-    const prefix = kind === DEFAULT_KEY_KIND ? this.keyPrefix : this.kinds[kind];
-    if (!prefix) throw new Error(`Unknown key kind "${kind}"`);
+    const spec: KeyKindSpec | undefined = kind === DEFAULT_KEY_KIND ? { prefix: this.keyPrefix } : this.kinds[kind];
+    if (!spec) throw new Error(`Unknown key kind "${kind}"`);
     const trimmed = (label ?? '').trim();
     if (trimmed.length === 0) {
       throw new InvalidTokenLabelError('Label cannot be empty');
@@ -65,7 +74,11 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
       );
     }
 
-    const plaintext = prefix + randomBytes(TOKEN_BYTES).toString('base64url');
+    const random =
+      spec.shape === 'github-token'
+        ? randomBytes(GITHUB_TOKEN_BYTES).toString('hex')
+        : randomBytes(TOKEN_BYTES).toString('base64url');
+    const plaintext = spec.prefix + random;
     const tokenHash = hashToken(plaintext);
 
     const [row] = await this.db
@@ -116,7 +129,7 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
     // 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);
+      log.warn('touchLastUsed failed:', { err });
     });
 
     return {
@@ -131,39 +144,84 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
   }
 
   async listForUser(userId: string): Promise<ExternalApiKeySummary[]> {
+    // A key the owner deleted for good is gone from THEIR listings — that is
+    // what the deletion means to them; the row lives on for the Audit log.
     const rows = await this.db
       .select()
       .from(externalApiKeys)
-      .where(eq(externalApiKeys.userId, userId))
+      .where(and(eq(externalApiKeys.userId, userId), isNull(externalApiKeys.deletedAt)))
       .orderBy(desc(externalApiKeys.createdAt));
     return rows.map(toSummary);
   }
 
+  async ownerOf(id: string): Promise<string | null> {
+    const [row] = await this.db
+      .select({ userId: externalApiKeys.userId })
+      .from(externalApiKeys)
+      .where(eq(externalApiKeys.id, id))
+      .limit(1);
+    return row?.userId ?? null;
+  }
+
+  async listForDeployment(): Promise<AdminExternalApiKeySummary[]> {
+    // Owner joined in so the admin overview is one round-trip; ordered by
+    // owner email so per-account grouping is a linear pass, newest key
+    // first within an account (same order the owner sees on their own page).
+    const rows = await this.db
+      .select({
+        key: externalApiKeys,
+        userId: users.id,
+        email: users.email,
+        name: users.name,
+      })
+      .from(externalApiKeys)
+      .innerJoin(users, eq(externalApiKeys.userId, users.id))
+      .orderBy(asc(users.email), desc(externalApiKeys.createdAt));
+    return rows.map((row) => ({
+      ...toSummary(row.key),
+      user: { id: row.userId, email: row.email, name: row.name },
+    }));
+  }
+
   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.
+    // Scope by userId so a user can never revoke another user's token even
+    // if they learn the id.
+    await this.markRevoked(
+      and(eq(externalApiKeys.id, id), eq(externalApiKeys.userId, userId))!,
+      'owner',
+    );
+  }
+
+  async revokeAny(id: string): Promise<void> {
+    // No owner scope: the caller is an admin acting across the deployment.
+    // The route that exposes this is admin-gated; nothing user-facing may
+    // reach it. Recorded as such so the owner is told it was taken, not
+    // that they disconnected it.
+    await this.markRevoked(eq(externalApiKeys.id, id), 'admin');
+  }
+
+  /**
+   * Set `revokedAt` (and who did it) on the rows matching `scope`. Idempotent
+   * on already-revoked rows because we only write when `revokedAt` is
+   * currently null — re-revoking returns 0 rows changed but no error, and
+   * never rewrites who ended it first. Throws TokenNotFoundError when `scope`
+   * matches nothing at all.
+   */
+  private async markRevoked(scope: SQL, by: RevokedBy): Promise<void> {
     const result = await this.db
       .update(externalApiKeys)
-      .set({ revokedAt: new Date() })
-      .where(
-        and(
-          eq(externalApiKeys.id, id),
-          eq(externalApiKeys.userId, userId),
-          isNull(externalApiKeys.revokedAt),
-        ),
-      )
+      .set({ revokedAt: new Date(), revokedBy: by })
+      .where(and(scope, isNull(externalApiKeys.revokedAt)))
       .returning({ id: externalApiKeys.id });
 
     if (result.length === 0) {
-      // Distinguish "doesn't exist / not yours" from "already revoked".
+      // Distinguish "doesn't exist / out of scope" 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)))
+        .where(scope)
         .limit(1);
       if (!existing) {
         throw new TokenNotFoundError();
@@ -172,14 +230,16 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
   }
 
   async remove(id: string, userId: string): Promise<void> {
-    // Only revoked rows may be hard-deleted — deleting an active key would
+    // Only revoked rows may be 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.
+    // not-found vs still-active error), then mark the row deleted.
     const [existing] = await this.db
       .select({ revokedAt: externalApiKeys.revokedAt })
       .from(externalApiKeys)
-      .where(and(eq(externalApiKeys.id, id), eq(externalApiKeys.userId, userId)))
+      .where(
+        and(eq(externalApiKeys.id, id), eq(externalApiKeys.userId, userId), isNull(externalApiKeys.deletedAt)),
+      )
       .limit(1);
     if (!existing) {
       throw new TokenNotFoundError();
@@ -189,16 +249,19 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
       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.
+    // A deletion in name: the row stays, marked, because the Audit log's
+    // events hang off it and the trail must outlive the key's owner's wish
+    // to be rid of it. The key was revoked already, so nothing can use it;
+    // deleting hides it from the owner and tells an admin it was deleted.
     await this.db
-      .delete(externalApiKeys)
+      .update(externalApiKeys)
+      .set({ deletedAt: new Date() })
       .where(
         and(
           eq(externalApiKeys.id, id),
           eq(externalApiKeys.userId, userId),
           isNotNull(externalApiKeys.revokedAt),
+          isNull(externalApiKeys.deletedAt),
         ),
       );
   }
@@ -223,5 +286,7 @@ function toSummary(row: typeof externalApiKeys.$inferSelect): ExternalApiKeySumm
     createdAt: row.createdAt.getTime(),
     lastUsedAt: row.lastUsedAt ? row.lastUsedAt.getTime() : null,
     revokedAt: row.revokedAt ? row.revokedAt.getTime() : null,
+    revokedBy: (row.revokedBy as RevokedBy | null) ?? null,
+    deletedAt: row.deletedAt ? row.deletedAt.getTime() : null,
   };
 }

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

@@ -37,6 +37,16 @@ export interface InternalTokenClaim {
    * expected to carry `sessionId` on the tool body, not in the token.
    */
   externalProxy?: boolean;
+  /**
+   * The agent connection (`agent_connections.id`) an external-proxy token
+   * stands in for. The LOCAL MCP server swaps its OAuth grant for one of these
+   * at `/api/mcp/local-token` and presents it everywhere the grant would have
+   * gone, so without this claim every call it makes would arrive with a user
+   * and no agent — unattributable in the Audit log. Carried, never decided:
+   * the exchange copies it from the verified grant. Absent on every other
+   * internal token.
+   */
+  connectionId?: string;
 }
 
 interface SignedPayload extends InternalTokenClaim {
@@ -99,8 +109,11 @@ export class InternalTokenService {
     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. */
+  /** @param ttlMs Override the default lifetime — for a caller whose token
+   *   must live a different span than the default: the MCP proxy's loopback
+   *   bearer (`MCP_LOOPBACK_TOKEN_TTL_MS`, longer, so a long tool call is not
+   *   cut off mid-way) and the external-proxy token minted for a grant, whose
+   *   life is bounded by the grant's remaining time (`mcp.routes.ts`). */
   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'));
@@ -134,6 +147,7 @@ export class InternalTokenService {
       ...(typeof payload.sessionId === 'string' ? { sessionId: payload.sessionId } : {}),
       ...(typeof payload.focusedBranch === 'string' ? { focusedBranch: payload.focusedBranch } : {}),
       ...(payload.externalProxy === true ? { externalProxy: true } : {}),
+      ...(typeof payload.connectionId === 'string' ? { connectionId: payload.connectionId } : {}),
     };
   }
 

package/src/modules/tool-auth/key-or-session.middleware.ts

@@ -0,0 +1,45 @@
+import type { NextFunction, Request, RequestHandler, Response } from 'express';
+
+/**
+ * One gate for an endpoint that serves the app AND agents: a bearer that
+ * looks like a tool credential (a `bevel_…` connection key, an internal
+ * token) goes through the tool-auth middleware; anything else — the
+ * browser's session JWT, its cookie — goes through the session middleware.
+ * Whichever admitted the caller, `req.userId` names them afterwards, so a
+ * handler written for sessions (`resolveUser` → `req.userId`) serves both.
+ *
+ * Composition, not a third verifier: each credential is still checked by
+ * the code that owns it. Deliberately NOT the read-only-manuals gate
+ * (`createManualAuthMiddleware`), which is documented as the one place a
+ * session may stand in for a tool credential; here it is the other way
+ * round — a tool credential is admitted to an app endpoint — and only for
+ * endpoints a tool definition describes.
+ */
+export function keyOrSessionAuth(deps: {
+  sessionAuth: RequestHandler;
+  toolAuth: RequestHandler;
+  /** Whether a bearer value is a tool credential rather than a session token. */
+  isToolCredential(token: string): boolean;
+}): RequestHandler {
+  return (req: Request, res: Response, next: NextFunction) => {
+    const header = req.headers.authorization;
+    const token =
+      header && header.toLowerCase().startsWith('bearer ') ? header.slice(header.indexOf(' ') + 1).trim() : '';
+    if (!token || !deps.isToolCredential(token)) {
+      deps.sessionAuth(req, res, next);
+      return;
+    }
+    deps.toolAuth(req, res, (err?: unknown) => {
+      if (err) {
+        next(err);
+        return;
+      }
+      // The tool gate names the caller on `req.toolAuth`; the endpoint reads
+      // `req.userId`, as it does for a session. Assigned unconditionally: the
+      // credential this gate accepted is who the caller is, whatever an
+      // earlier middleware may have written there.
+      if (req.toolAuth) req.userId = req.toolAuth.userId;
+      next();
+    });
+  };
+}

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

@@ -1,7 +1,11 @@
 import type { Request, Response, NextFunction, RequestHandler } from 'express';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('tools');
 import type { IExternalApiKeyService } from './external-api-key.interface.js';
 import type { AuthService } from '../auth/auth.service.js';
 import { InternalTokenService } from './internal-token.service.js';
+import { INVALID_CONNECTION_KEY_CHALLENGE, INVALID_CONNECTION_KEY_MESSAGE } from './connection-key-rejection.js';
 
 /**
  * What the `toolAuth` middleware resolves a bearer to, before the per-call
@@ -30,6 +34,14 @@ export interface ToolAuth {
    * never carries it and must name the branch explicitly.
    */
   focusedBranch?: string;
+  /**
+   * The agent connection an `externalProxy` token stands in for — the local
+   * server's exchanged grant names one (see `InternalTokenClaim.connectionId`).
+   * Only that grant carries it: the hosted proxy's own loopback tokens do
+   * not, and a connection key has a `tokenId` instead. What the REST audit
+   * recorder attributes a direct tool call to.
+   */
+  connectionId?: 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';
 }
@@ -88,10 +100,15 @@ export const requireExternalSource: RequestHandler = (req, res, next) => {
   next();
 };
 
-/** Outcome of verifying a bearer token — either a normalized identity or a status+message to surface. */
+/**
+ * Outcome of verifying a bearer token — either a normalized identity or a
+ * status+message to surface. `challenge` overrides the default
+ * `WWW-Authenticate` value on a 401 (a rejected connection key answers with
+ * its own plain `invalid_token` challenge).
+ */
 export type VerifyResult =
   | { ok: true; auth: ToolAuth }
-  | { ok: false; status: number; message: string };
+  | { ok: false; status: number; message: string; challenge?: string };
 
 /**
  * The framework-agnostic verify core: bearer token (the value AFTER `Bearer `) →
@@ -120,7 +137,15 @@ export function createTokenVerifier(
       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: 'external',
+              userId: claim.userId,
+              ...(claim.connectionId ? { connectionId: claim.connectionId } : {}),
+              scope: 'write',
+            },
+          }
         : { ok: true, auth: { source: 'internal', userId: claim.userId, sessionId: claim.sessionId, focusedBranch: claim.focusedBranch, scope: 'write' } };
     }
 
@@ -129,7 +154,7 @@ export function createTokenVerifier(
       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' };
+        : { ok: false, status: 401, message: INVALID_CONNECTION_KEY_MESSAGE, challenge: INVALID_CONNECTION_KEY_CHALLENGE };
     }
 
     return missing;
@@ -158,14 +183,14 @@ export function createToolAuthMiddleware(
     try {
       const result = await verify(token);
       if (!result.ok) {
-        if (result.status === 401) res.setHeader('WWW-Authenticate', WWW_AUTH);
+        if (result.status === 401) res.setHeader('WWW-Authenticate', result.challenge ?? 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);
+      log.error('connection-key verification failed:', { err });
       res.status(500).json({ error: 'Authentication backend unavailable' });
     }
   };
@@ -202,14 +227,14 @@ export function createManualAuthMiddleware(
       try {
         const result = await verify(token);
         if (!result.ok) {
-          if (result.status === 401) res.setHeader('WWW-Authenticate', WWW_AUTH);
+          if (result.status === 401) res.setHeader('WWW-Authenticate', result.challenge ?? 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);
+        log.error('connection-key verification failed:', { err });
         res.status(500).json({ error: 'Authentication backend unavailable' });
       }
       return;