fix(auth): treat "anonymous" as a built-in credential-less role

src/auth/role-mutex.test.ts

@@ -0,0 +1,36 @@
+import { describe, it, expect } from 'vitest';
+import { RoleMutex } from './role-mutex.js';
+import type { AuthConfig } from '../types.js';
+
+const NONE: AuthConfig = { kind: 'none' };
+const BASE = 'http://127.0.0.1:4104';
+
+describe('RoleMutex — built-in anonymous role', () => {
+  it('returns an unauthenticated session for "anonymous" even when roles[] is empty', async () => {
+    // BugHunter exercises the public surface as role "anonymous". SurfaceMCP must
+    // not reject it with "Unknown role" just because the config declares no roles.
+    const mutex = new RoleMutex(BASE, NONE, []);
+    const session = await mutex.refresh('anonymous');
+    expect(session.cookies).toEqual([]);
+    expect(session.token).toBeUndefined();
+  });
+
+  it('caches the anonymous session via ensureSession', async () => {
+    const mutex = new RoleMutex(BASE, NONE, []);
+    const first = await mutex.ensureSession('anonymous');
+    const second = await mutex.ensureSession('anonymous');
+    expect(second).toBe(first);
+  });
+
+  it('still throws for a genuinely unknown (non-anonymous) role', async () => {
+    const mutex = new RoleMutex(BASE, NONE, []);
+    await expect(mutex.refresh('owner')).rejects.toThrow('Unknown role: owner');
+  });
+
+  it('honors an explicitly declared "anonymous" role identically', async () => {
+    const mutex = new RoleMutex(BASE, NONE, [{ name: 'anonymous' }]);
+    const session = await mutex.refresh('anonymous');
+    expect(session.cookies).toEqual([]);
+    expect(session.token).toBeUndefined();
+  });
+});

src/auth/role-mutex.ts

@@ -7,6 +7,13 @@ import { log } from '../log.js';
 
 type LoginFn = () => Promise<RoleSession>;
 
+/**
+ * The canonical anonymous role. A built-in: it need not be declared in
+ * surfacemcp.config.json roles[]. Requests made as this role go unauthenticated,
+ * so the public surface can always be exercised (BugHunter's no-login default).
+ */
+const ANONYMOUS_ROLE_NAME = 'anonymous';
+
 /**
  * Per-role mutex: ensures only one login is in-flight at a time per role.
  * Concurrent callers that arrive during a refresh queue and reuse the result.
@@ -39,7 +46,13 @@ export class RoleMutex {
     const existing = this.inflight.get(roleName);
     if (existing) return existing;
 
-    const role = this.roles.find((r) => r.name === roleName);
+    let role = this.roles.find((r) => r.name === roleName);
+    // 'anonymous' is a built-in credential-less role — synthesize it when the
+    // config declares no matching role, so doLogin() returns an unauthenticated
+    // session instead of throwing "Unknown role: anonymous".
+    if (!role && roleName === ANONYMOUS_ROLE_NAME) {
+      role = { name: ANONYMOUS_ROLE_NAME };
+    }
     if (!role) throw new Error(`Unknown role: ${roleName}`);
 
     const promise = this.doLogin(role);