arc-1 0.9.25 → 1.0.0

package/dist/server/http.d.ts

@@ -26,7 +26,9 @@
  */
 import type { XsuaaCredentials } from '@arc-mcp/xsuaa-auth';
 import type { Server as McpServer } from '@modelcontextprotocol/sdk/server/index.js';
+import type { Request, Response } from 'express';
 import express from 'express';
+import type { DestinationRegistry, TargetDescriptor } from './destination-registry.js';
 import type { ServerConfig } from './types.js';
 import { type UiServerDeps } from './ui.js';
 /**
@@ -53,10 +55,50 @@ import { type UiServerDeps } from './ui.js';
  * Exported for unit tests; also called from `startHttpServer` below.
  */
 export declare function applySecurityMiddleware(app: express.Application, allowedOrigins: string[]): void;
+/**
+ * Create an Express handler that processes MCP requests.
+ * Each request gets a fresh Server + Transport pair.
+ * Exported for the era-contract regression tests (tests/unit/server/mcp-era-contract.test.ts).
+ */
+export declare function createMcpHandler(serverFactory: () => McpServer): (req: Request, res: Response) => Promise<void>;
+export interface MultiTargetRouting {
+    registry: DestinationRegistry;
+    aggregateFactory: () => McpServer;
+    createPinnedServer: (target: TargetDescriptor) => McpServer;
+}
+export declare function createPinnedTargetMcpHandler(multi: MultiTargetRouting): (req: Request, res: Response) => Promise<void>;
+export declare function createAggregateMcpHandler(multi: MultiTargetRouting): (req: Request, res: Response) => Promise<void>;
+export declare function resolveMcpHttpRateLimit(config: Pick<ServerConfig, 'authRateLimit' | 'mcpHttpRateLimit'>): number;
+export declare function multiTargetHealthStatus(registry: DestinationRegistry): 'ready' | 'error';
+export declare const MULTI_TARGET_SCOPES_SUPPORTED: readonly string[];
 /**
  * Start the HTTP Streamable server.
  */
-export declare function startHttpServer(serverFactory: () => McpServer, config: ServerConfig, xsuaaCredentials?: XsuaaCredentials, uiDeps?: UiServerDeps): Promise<void>;
+export declare function startHttpServer(serverFactory: (() => McpServer) | undefined, config: ServerConfig, xsuaaCredentials?: XsuaaCredentials, uiDeps?: UiServerDeps, multiTargets?: MultiTargetRouting): Promise<void>;
+/**
+ * Build the RFC 9728 document ARC-1 publishes in OIDC mode.
+ *
+ * ARC-1 is only the resource server here: `authorization_servers` points at the
+ * external IdP, and clients discover its endpoints themselves (RFC 8414 with the
+ * OIDC-discovery fallbacks — Entra only answers the append form). `resource` is
+ * the canonical MCP endpoint URI; MCP clients reject a document whose `resource`
+ * is not same-origin with the server they called.
+ *
+ * `scopes_supported` is IdP-specific (`api://<client-id>/access_as_user` on Entra,
+ * arbitrary elsewhere) and cannot be derived from `SAP_OIDC_AUDIENCE` — it is
+ * omitted unless the admin sets `SAP_OIDC_SCOPES`.
+ */
+export declare function buildOidcResourceMetadata(config: ServerConfig, publicBase: string): import('@modelcontextprotocol/sdk/shared/auth.js').OAuthProtectedResourceMetadata;
+/**
+ * Mount the protected-resource metadata routes and return the URL that belongs in
+ * the `WWW-Authenticate` challenge. Caller gates on `oidcIssuer && oidcDiscovery`.
+ *
+ * URLs come from `getAppUrl()` (ARC1_PUBLIC_URL / VCAP), never from the request
+ * `Host` header, so a spoofed Host cannot redirect clients at an attacker's IdP.
+ * The SDK's `metadataHandler` supplies `cors()` + GET/OPTIONS-only, the same
+ * treatment the XSUAA branch's metadata gets — the document is public by design.
+ */
+export declare function mountOidcResourceMetadata(app: express.Application, config: ServerConfig, bindHost: string, port: number): Promise<string>;
 /**
  * Create a token verifier for standard auth mode (API key + OIDC).
  *

package/dist/server/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/server/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAe,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,KAAK,EAAE,MAAM,IAAI,SAAS,EAAE,MAAM,2CAA2C,CAAC;AAIrF,OAAO,OAAO,MAAM,SAAS,CAAC;AAM9B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAiB,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AA2B3D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,CAAC,WAAW,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,IAAI,CA6DhG;AAuCD;;GAEG;AACH,wBAAsB,eAAe,CACnC,aAAa,EAAE,MAAM,SAAS,EAC9B,MAAM,EAAE,YAAY,EACpB,gBAAgB,CAAC,EAAE,gBAAgB,EACnC,MAAM,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CAoaf;AAkDD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,qBAAqB,EAAE,QAAQ,CAAC,CAOlH"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/server/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAe,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,KAAK,EAAE,MAAM,IAAI,SAAS,EAAE,MAAM,2CAA2C,CAAC;AAGrF,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,OAAO,MAAM,SAAS,CAAC;AAK9B,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAevF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAiB,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AA2B3D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,CAAC,WAAW,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,IAAI,CAiEhG;AA4CD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,SAAS,SAC1C,OAAO,OAAO,QAAQ,mBAU1C;AAID,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,gBAAgB,EAAE,MAAM,SAAS,CAAC;IAClC,kBAAkB,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,SAAS,CAAC;CAC7D;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,kBAAkB,SACjD,OAAO,OAAO,QAAQ,mBAmB1C;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,kBAAkB,SAC9C,OAAO,OAAO,QAAQ,mBAM1C;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,eAAe,GAAG,kBAAkB,CAAC,GAAG,MAAM,CAMhH;AAED,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,OAAO,GAAG,OAAO,CAIxF;AAED,eAAO,MAAM,6BAA6B,mBAAkD,CAAC;AAE7F;;GAEG;AACH,wBAAsB,eAAe,CACnC,aAAa,EAAE,CAAC,MAAM,SAAS,CAAC,GAAG,SAAS,EAC5C,MAAM,EAAE,YAAY,EACpB,gBAAgB,CAAC,EAAE,gBAAgB,EACnC,MAAM,CAAC,EAAE,YAAY,EACrB,YAAY,CAAC,EAAE,kBAAkB,GAChC,OAAO,CAAC,IAAI,CAAC,CAggBf;AAkDD;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,YAAY,EACpB,UAAU,EAAE,MAAM,GACjB,OAAO,0CAA0C,EAAE,8BAA8B,CAQnF;AAED;;;;;;;;GAQG;AACH,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,OAAO,CAAC,WAAW,EACxB,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,CAAC,CA0BjB;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,qBAAqB,EAAE,QAAQ,CAAC,CAOlH"}

package/dist/server/http.js

@@ -28,10 +28,14 @@ import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/
 import cors from 'cors';
 import express from 'express';
 import helmet from 'helmet';
-import { expandScopes } from '../authz/policy.js';
+import { expandScopes, hasRequiredScope } from '../authz/policy.js';
 import { API_KEY_PROFILES } from './config.js';
+import { generateRequestId, requestContext } from './context.js';
 import { authLibLogger, logger } from './logger.js';
+import { PINNED_MCP_PATH_PATTERN, PINNED_RESOURCE_METADATA_PATH_PATTERN, targetFromPinnedMcpPath, } from './multi-target-identity.js';
+import { buildXsuaaSessionRefreshUrl, createOAuthLoggedOutHandler, OAUTH_LOGGED_OUT_PATH, withInvalidScopeSessionRecovery, } from './oauth-session-recovery.js';
 import { VERSION } from './server.js';
+import { sanitizeClientAgent, validateTraceparent, validateTracestate } from './trace-context.js';
 import { mountUiRoutes } from './ui.js';
 // ─── API Key Entry Mapping ───────────────────────────────────────────
 /**
@@ -113,7 +117,11 @@ export function applySecurityMiddleware(app, allowedOrigins) {
                 callback(null, allowed.has(origin));
             },
             methods: ['GET', 'POST', 'DELETE', 'OPTIONS'],
-            allowedHeaders: ['Content-Type', 'Authorization', 'mcp-session-id'],
+            // mcp-protocol-version: sent by every SDK client on post-initialize requests (spec 2025-06-18+).
+            // last-event-id: sent on SSE reconnects (fetch-based, so preflighted). 2026-07-28 headers
+            // (Mcp-Method/Mcp-Name/Mcp-Param-*) deliberately absent — v2 clients default to legacy mode,
+            // and Mcp-Param-* is dynamically named (can't be allow-listed under credentials). ADR-0006.
+            allowedHeaders: ['Content-Type', 'Authorization', 'mcp-session-id', 'mcp-protocol-version', 'last-event-id'],
             exposedHeaders: ['mcp-session-id'],
             credentials: true,
         }));
@@ -138,11 +146,49 @@ export function applySecurityMiddleware(app, allowedOrigins) {
     }
 }
 // ─── MCP Request Handler ─────────────────────────────────────────────
+/**
+ * Serve one MCP request with a fresh Server + Transport pair.
+ *
+ * IMPORTANT: Passes req.body as pre-parsed body (3rd argument).
+ * express.json() middleware consumes the raw request stream. Without this,
+ * the MCP SDK's transport tries to re-read the stream, gets nothing, and
+ * returns "Parse error: Invalid JSON" (-32700). The SDK explicitly supports
+ * this pattern — see their docs/comments in
+ * StreamableHTTPServerTransport.handleRequest().
+ */
+async function serveMcpRequest(serverFactory, req, res) {
+    try {
+        const server = serverFactory();
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined, // Stateless mode
+        });
+        await server.connect(transport);
+        // Seed the request context from the HTTP edge: trace context to forward to SAP, and the
+        // calling agent. handleToolCall opens its own nested context for the tool call and inherits
+        // both — but events emitted before it (auth, multi-target prep) are covered only here.
+        // `User-Agent` is the only agent signal available on this transport: stateless mode means the
+        // per-request Server never saw `initialize`, so `getClientVersion()` is always undefined.
+        const traceparent = validateTraceparent(req.headers.traceparent);
+        await requestContext.run({
+            requestId: generateRequestId(),
+            traceparent,
+            tracestate: validateTracestate(req.headers.tracestate, traceparent),
+            clientAgent: sanitizeClientAgent(req.headers['user-agent']),
+        }, () => transport.handleRequest(req, res, req.body));
+    }
+    catch (err) {
+        logger.error('MCP request error', { error: err instanceof Error ? err.message : String(err) });
+        if (!res.headersSent) {
+            res.status(500).json({ error: 'Internal server error' });
+        }
+    }
+}
 /**
  * Create an Express handler that processes MCP requests.
  * Each request gets a fresh Server + Transport pair.
+ * Exported for the era-contract regression tests (tests/unit/server/mcp-era-contract.test.ts).
  */
-function createMcpHandler(serverFactory) {
+export function createMcpHandler(serverFactory) {
     return async (req, res) => {
         logger.debug('MCP handler invoked', {
             method: req.method,
@@ -151,32 +197,56 @@ function createMcpHandler(serverFactory) {
             bodyMethod: req.body?.method,
             bodyId: req.body?.id,
         });
-        try {
-            const server = serverFactory();
-            const transport = new StreamableHTTPServerTransport({
-                sessionIdGenerator: undefined, // Stateless mode
-            });
-            await server.connect(transport);
-            // IMPORTANT: Pass req.body as pre-parsed body (3rd argument).
-            // express.json() middleware (line 91) consumes the raw request stream.
-            // Without this, the MCP SDK's transport tries to re-read the stream,
-            // gets nothing, and returns "Parse error: Invalid JSON" (-32700).
-            // The SDK explicitly supports this pattern — see their docs/comments
-            // in StreamableHTTPServerTransport.handleRequest().
-            await transport.handleRequest(req, res, req.body);
+        await serveMcpRequest(serverFactory, req, res);
+    };
+}
+export function createPinnedTargetMcpHandler(multi) {
+    return async (req, res) => {
+        if (!multi.registry.available) {
+            res.status(503).json({ error: 'Multi-target registry unavailable' });
+            return;
         }
-        catch (err) {
-            logger.error('MCP request error', { error: err instanceof Error ? err.message : String(err) });
-            if (!res.headersSent) {
-                res.status(500).json({ error: 'Internal server error' });
-            }
+        const targetId = targetFromPinnedMcpPath(req.path);
+        const target = targetId ? multi.registry.get(targetId) : undefined;
+        if (!target) {
+            res.status(404).json({ error: 'Not found' });
+            return;
         }
+        logger.debug('MCP handler invoked (pinned target)', {
+            target: target.target,
+            method: req.method,
+            bodyMethod: req.body?.method,
+            bodyId: req.body?.id,
+        });
+        await serveMcpRequest(() => multi.createPinnedServer(target), req, res);
     };
 }
+export function createAggregateMcpHandler(multi) {
+    return async (req, res) => {
+        // Keep the aggregate MCP transport reachable when discovery fails so an
+        // administrator can call SAPTargets and inspect secret-safe diagnostics.
+        // Other tool calls return a structured registry-unavailable result.
+        await serveMcpRequest(multi.aggregateFactory, req, res);
+    };
+}
+export function resolveMcpHttpRateLimit(config) {
+    if (config.mcpHttpRateLimit !== undefined)
+        return config.mcpHttpRateLimit;
+    // OAuth and MCP traffic are separate edge buckets. Disabling only the OAuth
+    // bucket must not also remove MCP protection; ARC1_MCP_HTTP_RATE_LIMIT=0 is
+    // the explicit opt-out for MCP traffic.
+    return Math.max(config.authRateLimit * 30, 600);
+}
+export function multiTargetHealthStatus(registry) {
+    // Zero targets and individually quarantined destinations are valid snapshots.
+    // Only a registry-wide failure makes multi-target routing unavailable.
+    return registry.available ? 'ready' : 'error';
+}
+export const MULTI_TARGET_SCOPES_SUPPORTED = Object.freeze(['read', 'data', 'sql', 'admin']);
 /**
  * Start the HTTP Streamable server.
  */
-export async function startHttpServer(serverFactory, config, xsuaaCredentials, uiDeps) {
+export async function startHttpServer(serverFactory, config, xsuaaCredentials, uiDeps, multiTargets) {
     const [host, portStr] = config.httpAddr.split(':');
     const port = Number.parseInt(portStr || '8080', 10);
     const bindHost = host || '0.0.0.0';
@@ -186,28 +256,41 @@ export async function startHttpServer(serverFactory, config, xsuaaCredentials, u
     app.set('trust proxy', 1);
     applySecurityMiddleware(app, config.allowedOrigins);
     // ─── Layer 1: HTTP-edge rate limiter helper ──────────────────────────
-    // One operator-facing knob (`ARC1_AUTH_RATE_LIMIT`, default 20/min/IP) controls all
-    // OAuth endpoints uniformly. `/mcp` gets `max(value × 30, 600)/min/IP` so legitimate
-    // batched tool-call traffic isn't choked while pre-bearer-auth probing is still gated.
-    // Per-endpoint differentiation lives here, not in env, so the operator surface stays tiny.
+    // `ARC1_AUTH_RATE_LIMIT` (default 20/min/IP) controls OAuth endpoints uniformly.
+    // MCP traffic derives `max(value × 30, 600)/min/IP` unless the operator sets the
+    // independent `ARC1_MCP_HTTP_RATE_LIMIT`; this keeps pre-bearer probing gated even
+    // when OAuth limiting is delegated to an upstream proxy.
     // See docs_page/rate-limiting.md (Layer 1) and ADR-0004.
     //
     // Implementation note: the limiter is mounted DIRECTLY via createAuthRateLimiter →
     // express-rate-limit. The disabled path skips the mount entirely rather than going
     // through a noop indirection — this keeps the dataflow `rateLimit({...}) → app.use`
     // direct and makes CodeQL's `js/missing-rate-limiting` query close cleanly.
-    const { createAuthRateLimiter, isCopilotJsonRpc } = await import('./auth-rate-limit.js');
-    const rateLimitEnabled = config.authRateLimit > 0;
-    const mcpRatePerMinute = rateLimitEnabled ? Math.max(config.authRateLimit * 30, 600) : 0;
+    const { createAuthRateLimiter, isCopilotJsonRpc, isMcpHttpTraffic } = await import('./auth-rate-limit.js');
+    const authRateLimitEnabled = config.authRateLimit > 0;
+    const mcpRatePerMinute = resolveMcpHttpRateLimit(config);
+    const mcpRateLimitEnabled = mcpRatePerMinute > 0;
     logger.info('Auth rate limiting', {
         perMinute: config.authRateLimit,
         mcpPerMinute: mcpRatePerMinute,
-        endpoints: rateLimitEnabled ? ['/register', '/authorize', '/token', '/revoke', '/mcp'] : [],
-        disabled: !rateLimitEnabled,
+        endpoints: [
+            ...(authRateLimitEnabled ? ['/register', '/authorize', '/token', '/revoke'] : []),
+            ...(mcpRateLimitEnabled ? ['/mcp'] : []),
+        ],
+        disabled: !authRateLimitEnabled && !mcpRateLimitEnabled,
     });
     app.use(express.json());
     app.use(express.urlencoded({ extended: false }));
-    const mcpHandler = createMcpHandler(serverFactory);
+    if (mcpRateLimitEnabled) {
+        // One middleware instance means one MemoryStore and therefore one per-IP
+        // bucket across single-target, pinned, aggregate, and Copilot routes.
+        // Mount after body parsing so the Copilot JSON-RPC predicate can inspect
+        // `req.body`, but before every authentication and route handler.
+        app.use(createAuthRateLimiter('/mcp', mcpRatePerMinute, { skip: (req) => !isMcpHttpTraffic(req) }));
+    }
+    const mcpHandler = serverFactory ? createMcpHandler(serverFactory) : undefined;
+    const pinnedMcpHandler = multiTargets ? createPinnedTargetMcpHandler(multiTargets) : undefined;
+    const aggregateMcpHandler = multiTargets ? createAggregateMcpHandler(multiTargets) : undefined;
     const hasAdminApiKey = config.apiKeys?.some((entry) => entry.profile === 'admin') ?? false;
     if (uiDeps && !(hasAdminApiKey || config.oidcIssuer || (config.xsuaaAuth && xsuaaCredentials))) {
         throw new Error('ARC1_UI=web requires an admin API key, OIDC, or XSUAA HTTP authentication.');
@@ -230,7 +313,15 @@ export async function startHttpServer(serverFactory, config, xsuaaCredentials, u
     // they're talking to the CORRECT process (not a zombie from a previous deploy).
     const startedAt = new Date().toISOString();
     app.get('/health', (_req, res) => {
-        res.json({ status: 'ok', version: VERSION, startedAt, pid: process.pid });
+        res.json({
+            status: 'ok',
+            version: VERSION,
+            startedAt,
+            pid: process.pid,
+            ...(multiTargets
+                ? { components: { multiTarget: { status: multiTargetHealthStatus(multiTargets.registry) } } }
+                : {}),
+        });
     });
     // ─── XSUAA OAuth Proxy Mode ──────────────────────────────
     if (config.xsuaaAuth && xsuaaCredentials) {
@@ -252,6 +343,8 @@ export async function startHttpServer(serverFactory, config, xsuaaCredentials, u
         // URL sent to XSUAA as redirect_uri; the Express route is mounted at the root
         // `/oauth/callback` below since the proxy strips the prefix before forwarding.
         const oauthCallbackUrl = `${oauthFullBase}/oauth/callback`;
+        const oauthLoggedOutUrl = `${oauthFullBase}${OAUTH_LOGGED_OUT_PATH}`;
+        const xsuaaSessionRefreshUrl = buildXsuaaSessionRefreshUrl(xsuaaCredentials, oauthLoggedOutUrl);
         // Create XSUAA provider + chained verifier.
         //
         // The package defaults its client_id prefix + KDF labels to `mcp-*`. ARC-1
@@ -286,6 +379,42 @@ export async function startHttpServer(serverFactory, config, xsuaaCredentials, u
             verifier: { verifyAccessToken: chainedVerifier },
             resourceMetadataUrl,
         });
+        // Multi-target routes accept XSUAA identities only. Define this once and
+        // reuse it for explicit routes and the Copilot `/authorize` compatibility
+        // alias so multi mode cannot fall back to API-key/OIDC or a single target.
+        const multiBearerAuth = multiTargets && pinnedMcpHandler && aggregateMcpHandler
+            ? (req, res, next) => {
+                // `app.use('/authorize', ...)` temporarily trims req.path to `/`.
+                // originalUrl preserves the public route, so the Copilot alias can
+                // advertise the aggregate PRM instead of a non-existent root PRM.
+                const originalPath = req.originalUrl?.split('?', 1)[0] || req.path;
+                const lowerPath = originalPath.toLowerCase();
+                const resourcePath = lowerPath === '/authorize' ? '/multi/mcp' : originalPath;
+                const multiResourceMetadataUrl = `${oauthFullBase}/.well-known/oauth-protected-resource${resourcePath}`;
+                const authenticate = requireBearerAuth({
+                    verifier: { verifyAccessToken: xsuaaVerifier },
+                    resourceMetadataUrl: multiResourceMetadataUrl,
+                });
+                authenticate(req, res, (error) => {
+                    if (error) {
+                        next(error);
+                        return;
+                    }
+                    // Keep route membership behind the global read scope without putting
+                    // `scope=read` in the initial 401 challenge. MCP clients can therefore
+                    // request the four mutation-free scopes advertised by the route PRM;
+                    // XSUAA still grants only the subset assigned to the authenticated user.
+                    if (!req.auth || !hasRequiredScope(req.auth.scopes, 'read')) {
+                        res
+                            .set('WWW-Authenticate', `Bearer error="insufficient_scope", error_description="Insufficient scope", scope="read", resource_metadata="${multiResourceMetadataUrl}"`)
+                            .status(403)
+                            .json({ error: 'insufficient_scope', error_description: 'Insufficient scope' });
+                        return;
+                    }
+                    next();
+                });
+            }
+            : undefined;
         if (uiDeps) {
             const uiBearerAuth = requireBearerAuth({
                 verifier: { verifyAccessToken: chainedVerifier },
@@ -300,33 +429,19 @@ export async function startHttpServer(serverFactory, config, xsuaaCredentials, u
         // rate-limited — they're cheap, cacheable, and legitimate clients hit them on
         // every reconnect. See docs_page/rate-limiting.md.
         //
-        // Every `app.use(path, …)` here receives a fresh `rateLimit({...})` middleware
+        // Every OAuth `app.use(path, …)` here receives a fresh `rateLimit({...})` middleware
         // DIRECTLY. No conditional dispatchers, no helper wrappers. CodeQL's
         // `js/missing-rate-limiting` query only recognises that exact pattern; going
         // through an inline arrow function with branch-based delegation makes it
         // re-open the alert (verified — see PR #276 review history).
         //
-        // Copilot Studio quirk: that client POSTs MCP JSON-RPC bodies to `/authorize`
-        // (see routing handler below). To stop those tool calls being choked at the
-        // low OAuth cap, we mount TWO limiters on `/authorize`:
-        //   1. OAuth cap, with `skip` returning true for Copilot JSON-RPC traffic.
-        //   2. /mcp cap, with `skip` returning true for everything BUT Copilot JSON-RPC.
-        // Each request hits one bucket — the OAuth bucket for real OAuth flows, the
-        // higher /mcp bucket for Copilot. The `isCopilotJsonRpc` predicate is shared
-        // with auth-rate-limit.ts so the two mounts can never drift.
-        //
-        // Trade-off: the /authorize-JSON-RPC bucket is a separate store from the
-        // direct /mcp bucket. An attacker alternating routes effectively gets
-        // `mcpCap + mcpCap = 2 × mcpCap`/min/IP. At default config that's still
-        // 1200/min, well below abuse thresholds. Sharing the store would require
-        // injecting a custom MemoryStore into both `rateLimit({...})` calls — not
-        // worth the complexity for a 2× headroom on an already loose cap.
-        if (rateLimitEnabled) {
+        // Copilot Studio JSON-RPC on `/authorize` skips the low OAuth bucket. The
+        // root-mounted MCP limiter above counts it in the same higher-cap bucket as
+        // every other MCP endpoint style.
+        if (authRateLimitEnabled) {
             app.use('/register', createAuthRateLimiter('/register', config.authRateLimit));
             // /authorize OAuth limiter — skips Copilot Studio MCP JSON-RPC traffic.
             app.use('/authorize', createAuthRateLimiter('/authorize', config.authRateLimit, { skip: isCopilotJsonRpc }));
-            // /authorize MCP limiter — only applies to Copilot Studio JSON-RPC; uses /mcp cap.
-            app.use('/authorize', createAuthRateLimiter('/mcp', mcpRatePerMinute, { skip: (req) => !isCopilotJsonRpc(req) }));
             app.use('/token', createAuthRateLimiter('/token', config.authRateLimit));
             app.use('/revoke', createAuthRateLimiter('/revoke', config.authRateLimit));
             // /oauth/callback is unauthenticated and does an HMAC verify per hit —
@@ -337,7 +452,7 @@ export async function startHttpServer(serverFactory, config, xsuaaCredentials, u
         // Copilot Studio sends MCP JSON-RPC requests to /authorize instead of
         // /mcp after completing the OAuth flow. When we detect a JSON-RPC body
         // (has "jsonrpc" field) on POST /authorize, we bypass the OAuth handler
-        // and route directly to bearerAuth + mcpHandler.
+        // and route directly to the applicable bearer verifier + MCP handler.
         //
         // For normal OAuth requests, merge query params into body as fallback
         // (some clients send POST /authorize with params in query string).
@@ -352,13 +467,24 @@ export async function startHttpServer(serverFactory, config, xsuaaCredentials, u
                     id: req.body.id,
                     userAgent: req.headers['user-agent']?.slice(0, 60),
                 });
-                // Run bearerAuth, then mcpHandler — skip the OAuth authorize handler
-                bearerAuth(req, res, (err) => {
+                // The compatibility alias is necessarily target-ambiguous. Whenever
+                // multi-target mode is enabled, resolve it to the mutation-free
+                // aggregate route and its XSUAA-only verifier, even if a separately
+                // configured (and potentially writable) single-target /mcp coexists.
+                // Only a single-target-only deployment may use the chained verifier.
+                const useAggregateAlias = !!(aggregateMcpHandler && multiBearerAuth);
+                const authorizeBearerAuth = useAggregateAlias ? multiBearerAuth : bearerAuth;
+                authorizeBearerAuth(req, res, (err) => {
                     if (err) {
                         next(err);
                         return;
                     }
-                    mcpHandler(req, res);
+                    const handler = useAggregateAlias ? aggregateMcpHandler : mcpHandler;
+                    if (!handler) {
+                        res.status(404).json({ error: 'Not found' });
+                        return;
+                    }
+                    handler(req, res);
                 });
                 return;
             }
@@ -408,7 +534,8 @@ export async function startHttpServer(serverFactory, config, xsuaaCredentials, u
         // XSUAA as oauthCallbackUrl. A strip-prefix proxy maps the public path
         // back to this root route. Handler is extracted (exported) so the
         // state-round-trip contract is unit-testable without a live XSUAA.
-        app.get('/oauth/callback', createOAuthCallbackHandler(stateCodec, clientStore, { logger: authLibLogger }));
+        app.get(OAUTH_LOGGED_OUT_PATH, createOAuthLoggedOutHandler());
+        app.get('/oauth/callback', withInvalidScopeSessionRecovery(createOAuthCallbackHandler(stateCodec, clientStore, { logger: authLibLogger }), xsuaaSessionRefreshUrl));
         // ─── Path-prefix-aware OAuth metadata override ────────────────
         // The MCP SDK's `mcpAuthRouter` builds endpoint URLs with
         // `new URL("/authorize", baseUrl).href`, which strips any path component
@@ -464,6 +591,27 @@ export async function startHttpServer(serverFactory, config, xsuaaCredentials, u
                 basePath,
             });
         }
+        // Registry-independent multi-target PRM routes must precede the SDK router.
+        // Syntactically valid unknown targets intentionally receive the same metadata as known ones.
+        if (multiTargets && pinnedMcpHandler && aggregateMcpHandler) {
+            app.get(/^\/\.well-known\/oauth-protected-resource\/multi\/mcp$/, (_req, res) => {
+                res.json({
+                    resource: `${oauthFullBase}/multi/mcp`,
+                    authorization_servers: [`${oauthFullBase}/`],
+                    scopes_supported: MULTI_TARGET_SCOPES_SUPPORTED,
+                    resource_name: 'ARC-1 SAP MCP Server (multi-target)',
+                });
+            });
+            app.get(PINNED_RESOURCE_METADATA_PATH_PATTERN, (req, res) => {
+                const match = req.path.match(PINNED_RESOURCE_METADATA_PATH_PATTERN);
+                res.json({
+                    resource: `${oauthFullBase}/${match?.[1]}/${match?.[2]}/mcp`,
+                    authorization_servers: [`${oauthFullBase}/`],
+                    scopes_supported: MULTI_TARGET_SCOPES_SUPPORTED,
+                    resource_name: 'ARC-1 SAP MCP Server (pinned target)',
+                });
+            });
+        }
         // Install MCP SDK auth router at root (OAuth endpoints + DCR).
         // For root-path deployments (no basePath) the SDK's metadata is correct
         // as-is and serves both well-known endpoints. For prefix deployments the
@@ -478,14 +626,13 @@ export async function startHttpServer(serverFactory, config, xsuaaCredentials, u
             scopesSupported,
             resourceName: 'ARC-1 SAP MCP Server',
         }));
-        // Layer 1: rate-limit /mcp BEFORE bearer auth so anonymous probing is gated.
-        // Direct `app.use(path, rateLimit({...}))` mount — no helper indirection —
-        // so CodeQL's `js/missing-rate-limiting` query sees the dataflow cleanly.
-        if (rateLimitEnabled) {
-            app.use('/mcp', createAuthRateLimiter('/mcp', mcpRatePerMinute));
+        if (multiTargets && pinnedMcpHandler && aggregateMcpHandler && multiBearerAuth) {
+            app.all(/^\/multi\/mcp$/, multiBearerAuth, aggregateMcpHandler);
+            app.all(PINNED_MCP_PATH_PATTERN, multiBearerAuth, pinnedMcpHandler);
         }
         // Protected MCP endpoint with chained token verification
-        app.all('/mcp', bearerAuth, mcpHandler);
+        if (mcpHandler)
+            app.all('/mcp', bearerAuth, mcpHandler);
         logger.info('XSUAA OAuth proxy enabled', {
             xsappname: xsuaaCredentials.xsappname,
             appUrl,
@@ -496,30 +643,34 @@ export async function startHttpServer(serverFactory, config, xsuaaCredentials, u
         // No JWKS pre-warm needed: the package's OIDC verifier lazy-imports jose and
         // memoizes the remote JWKS on the first verify (and retries on a transient
         // discovery failure instead of caching the rejection).
-        // Layer 1 on /mcp also applies outside XSUAA mode — API-key / OIDC / no-auth
-        // deployments get the same anonymous-probing protection. OAuth endpoints don't
-        // exist in non-XSUAA mode so only /mcp needs mounting here.
-        if (rateLimitEnabled) {
-            app.use('/mcp', createAuthRateLimiter('/mcp', mcpRatePerMinute));
-        }
         if (config.apiKeys || config.oidcIssuer) {
             // Use requireBearerAuth so that authInfo is populated on the MCP request context.
             // This enables scope enforcement, per-request safety, and principal propagation.
             const { requireBearerAuth } = await import('@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js');
             const verifier = await createStandardVerifier(config);
-            const bearerAuth = requireBearerAuth({ verifier: { verifyAccessToken: verifier } });
+            // ─── RFC 9728 protected-resource metadata (OIDC mode) ─────────
+            // ARC-1 is a pure resource server here: it publishes WHERE the external
+            // IdP lives and mints no tokens. Skipped for api-key-only mode (no
+            // authorization server to advertise) and when the admin opted out.
+            const resourceMetadataUrl = config.oidcIssuer && config.oidcDiscovery
+                ? await mountOidcResourceMetadata(app, config, bindHost, port)
+                : undefined;
+            const bearerAuth = requireBearerAuth({ verifier: { verifyAccessToken: verifier }, resourceMetadataUrl });
             if (uiDeps) {
                 const uiBearerAuth = requireBearerAuth({
                     verifier: { verifyAccessToken: verifier },
                     requiredScopes: ['admin'],
+                    resourceMetadataUrl,
                 });
                 mountUiRoutes(app, uiDeps, uiBearerAuth);
             }
-            app.all('/mcp', bearerAuth, mcpHandler);
+            if (mcpHandler)
+                app.all('/mcp', bearerAuth, mcpHandler);
         }
         else {
             // No auth configured — open access
-            app.all('/mcp', mcpHandler);
+            if (mcpHandler)
+                app.all('/mcp', mcpHandler);
         }
     }
     // ─── 404 for anything else ─────────────────────────────────
@@ -541,7 +692,8 @@ export async function startHttpServer(serverFactory, config, xsuaaCredentials, u
         logger.info('ARC-1 HTTP server started', {
             addr: `${bindHost}:${port}`,
             health: `http://${bindHost}:${port}/health`,
-            mcp: `http://${bindHost}:${port}/mcp`,
+            mcp: serverFactory ? `http://${bindHost}:${port}/mcp` : undefined,
+            multi: multiTargets ? `http://${bindHost}:${port}/multi/mcp` : undefined,
             ui: uiDeps ? `http://${bindHost}:${port}/ui/` : undefined,
             auth: authMode,
         });
@@ -598,6 +750,64 @@ function buildPackageOidcVerifier(config, createOidcVerifier) {
         logger: authLibLogger,
     });
 }
+// ─── OIDC Protected-Resource Metadata (RFC 9728) ────────────────────
+/**
+ * Build the RFC 9728 document ARC-1 publishes in OIDC mode.
+ *
+ * ARC-1 is only the resource server here: `authorization_servers` points at the
+ * external IdP, and clients discover its endpoints themselves (RFC 8414 with the
+ * OIDC-discovery fallbacks — Entra only answers the append form). `resource` is
+ * the canonical MCP endpoint URI; MCP clients reject a document whose `resource`
+ * is not same-origin with the server they called.
+ *
+ * `scopes_supported` is IdP-specific (`api://<client-id>/access_as_user` on Entra,
+ * arbitrary elsewhere) and cannot be derived from `SAP_OIDC_AUDIENCE` — it is
+ * omitted unless the admin sets `SAP_OIDC_SCOPES`.
+ */
+export function buildOidcResourceMetadata(config, publicBase) {
+    return {
+        resource: `${publicBase}/mcp`,
+        authorization_servers: [config.oidcIssuer],
+        bearer_methods_supported: ['header'],
+        resource_name: 'ARC-1 SAP MCP Server',
+        ...(config.oidcScopes?.length ? { scopes_supported: config.oidcScopes } : {}),
+    };
+}
+/**
+ * Mount the protected-resource metadata routes and return the URL that belongs in
+ * the `WWW-Authenticate` challenge. Caller gates on `oidcIssuer && oidcDiscovery`.
+ *
+ * URLs come from `getAppUrl()` (ARC1_PUBLIC_URL / VCAP), never from the request
+ * `Host` header, so a spoofed Host cannot redirect clients at an attacker's IdP.
+ * The SDK's `metadataHandler` supplies `cors()` + GET/OPTIONS-only, the same
+ * treatment the XSUAA branch's metadata gets — the document is public by design.
+ */
+export async function mountOidcResourceMetadata(app, config, bindHost, port) {
+    const { metadataHandler } = await import('@modelcontextprotocol/sdk/server/auth/handlers/metadata.js');
+    const { getAppUrl } = await import('./app-url.js');
+    const parsed = new URL(getAppUrl() ?? `http://${bindHost}:${port}`);
+    const basePath = parsed.pathname.replace(/\/$/, ''); // '' for root, '/arc1' behind a prefix proxy
+    const publicBase = `${parsed.origin}${basePath}`;
+    const metadata = buildOidcResourceMetadata(config, publicBase);
+    // Order matters: '/.well-known/oauth-protected-resource' is a mount PREFIX, so
+    // it must come after the '/mcp' route or it would swallow it.
+    app.use('/.well-known/oauth-protected-resource/mcp', metadataHandler(metadata)); // RFC 9728 §3.1 path insertion
+    if (basePath)
+        app.use(`/.well-known/oauth-protected-resource${basePath}/mcp`, metadataHandler(metadata));
+    // Root fallback (spec 2025-11-25 lists it; the SDK client probes sub-path → root).
+    // As a prefix mount it also answers unknown sub-paths — harmless: clients validate
+    // `resource` against the URL they called, and OIDC mode has no other MCP routes.
+    app.use('/.well-known/oauth-protected-resource', metadataHandler(metadata));
+    const resourceMetadataUrl = `${publicBase}/.well-known/oauth-protected-resource/mcp`;
+    // Key is `issuer`, not `authorizationServer` — the logger redacts any key
+    // containing "authorization", which would hide the one value operators need.
+    logger.info('OIDC protected-resource metadata enabled', {
+        resource: metadata.resource,
+        issuer: config.oidcIssuer,
+        scopesSupported: config.oidcScopes?.length ?? 0,
+    });
+    return resourceMetadataUrl;
+}
 // ─── Standard Mode Verifier ─────────────────────────────────────────
 /**
  * Create a token verifier for standard auth mode (API key + OIDC).