plugins: let a plugin claim top-level paths and divert /api by header

Restores the setup the vault extraction regressed: paste the bare Officer URL
into a Bitwarden client and log in. Nothing else.

The extraction moved the Bitwarden door to /api/vault/bw, which is correct and
unusable — a client derives /api, /identity, /icons and /notifications from ONE
url it is given, so a prefixed base turns setup into five fields copied by hand
into an advanced pane. That is not a feature anyone completes, and the owner
said so. My regression, my wrong call: I treated "a plugin cannot serve
top-level paths" as a fact about the platform when it was a fact about what had
been built.

Two additions, both manifest-declared, both narrow:

  unauthenticatedRootPaths  single lowercase segments (`/identity`), served
                            above the gate. Refused if reserved (`/api`,
                            `/auth`, `/plugins`, `/dav`, …), refused if another
                            plugin already claims it, refused if it is anything
                            more structural than one name.

  protocolHeaders           hands `/api/*` to the plugin when the request
                            carries one. Needed because /api is the one
                            namespace both servers claim — Vaultwarden has
                            /api/sync, Officer has /api/chat — and the path
                            cannot tell them apart, so the client says who it
                            is. ROUTING, not authentication: a forged header
                            reaches the plugin, which demands its own
                            credential, and cannot reach anything of Officer's.
                            The worst it does is cost that caller Officer's API.

The Bun route table gets an entry per claimed segment, built from the plugin
set — `refreshPluginMounts` runs at line ~204, long before serve() at ~378, so
the claims are known. This is the constraint I earlier asserted made the whole
thing impossible, without checking it. The real cost is smaller and stated in
the code: a plugin claiming a root path is not fully installed until
`pm2 restart officer`, because the table is fixed once serve() is called.

Every claim is logged at boot by plugin — a root path answering without a
session should not be something you read a manifest to discover.

13 more tests (30 in the file): reserved segments, malformed segments, two
plugins colliding, and segment-not-substring matching so `/identityx` never
matches `/identity`. Suite 1074 pass / 0 fail.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

src/servers/plugins/public-paths.test.ts

@@ -1,5 +1,14 @@
 import { describe, expect, test, afterEach } from 'bun:test';
-import { isPluginPublicPath, resolvePluginPublicPaths, setPluginPublicPaths } from './public-paths';
+import {
+  isPluginPublicPath,
+  pluginForProtocolHeaders,
+  pluginForRootPath,
+  resolvePluginPublicPaths,
+  resolvePluginRootPaths,
+  setPluginProtocolHeaders,
+  setPluginPublicPaths,
+  setPluginRootClaims,
+} from './public-paths';
 import type { DiscoveredPlugin } from './manifest';
 
 // This is an auth boundary: everything matched here skips `userMiddleware` AND the permission gate. The
@@ -27,7 +36,11 @@ const plugin = (appName: string, unauthenticatedPaths?: string[], publisher = 'o
     web: null,
   }) as DiscoveredPlugin;
 
-afterEach(() => setPluginPublicPaths([]));
+afterEach(() => {
+  setPluginPublicPaths([]);
+  setPluginRootClaims([]);
+  setPluginProtocolHeaders([]);
+});
 
 describe('resolving a plugin’s declared paths', () => {
   test('resolves against the plugin’s own mount', () => {
@@ -100,3 +113,58 @@ describe('matching a request path', () => {
     expect(isPluginPublicPath('/api/users')).toBe(false);
   });
 });
+
+describe('top-level claims', () => {
+  const withRoots = (appName: string, roots: string[]) => {
+    const p = plugin(appName);
+    (p.manifest as { unauthenticatedRootPaths?: string[] }).unauthenticatedRootPaths = roots;
+    return p;
+  };
+
+  test('a single lowercase segment is claimed', () => {
+    const { segments, refused } = resolvePluginRootPaths(withRoots('vault', ['/identity', '/icons']), new Set());
+    expect(segments).toEqual(['identity', 'icons']);
+    expect(refused).toEqual([]);
+  });
+
+  // The whole point of the reserved list: a plugin claiming these would shadow the platform for every
+  // request, and `/api` in particular is where all of Officer lives.
+  test.each([['/api'], ['/auth'], ['/plugins'], ['/dav']])('refuses the reserved segment %s', (root) => {
+    const { segments, refused } = resolvePluginRootPaths(withRoots('evil', [root]), new Set());
+    expect(segments).toEqual([]);
+    expect(refused).toHaveLength(1);
+  });
+
+  test.each([['/a/b'], ['identity'], ['/Identity'], ['/']])('refuses the malformed segment %s', (root) => {
+    expect(resolvePluginRootPaths(withRoots('evil', [root]), new Set()).segments).toEqual([]);
+  });
+
+  test('two plugins cannot both claim one segment — first come, loser named', () => {
+    const taken = new Set<string>();
+    expect(resolvePluginRootPaths(withRoots('vault', ['/identity']), taken).segments).toEqual(['identity']);
+    const second = resolvePluginRootPaths(withRoots('other', ['/identity']), taken);
+    expect(second.segments).toEqual([]);
+    expect(second.refused[0]).toContain('already claimed');
+  });
+
+  test('matching a claimed root is by segment, not string prefix', () => {
+    setPluginRootClaims([{ segment: 'identity', appName: 'vault' }]);
+    expect(pluginForRootPath('/identity')).toBe('vault');
+    expect(pluginForRootPath('/identity/connect/token')).toBe('vault');
+    expect(pluginForRootPath('/identityx')).toBeNull();
+    expect(pluginForRootPath('/other')).toBeNull();
+  });
+
+  test('a protocol header hands /api over, and its absence does not', () => {
+    setPluginProtocolHeaders([{ header: 'bitwarden-client-name', appName: 'vault' }]);
+    expect(pluginForProtocolHeaders(new Headers({ 'bitwarden-client-name': 'browser' }))).toBe('vault');
+    expect(pluginForProtocolHeaders(new Headers({ authorization: 'Bearer x' }))).toBeNull();
+  });
+
+  test('nothing is claimed by default', () => {
+    setPluginRootClaims([]);
+    setPluginProtocolHeaders([]);
+    expect(pluginForRootPath('/identity')).toBeNull();
+    expect(pluginForProtocolHeaders(new Headers({ 'bitwarden-client-name': 'browser' }))).toBeNull();
+  });
+});