arc-1 0.9.5 → 0.9.7

package/dist/server/mcp-rate-limit.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Layer 2 — Per-user MCP tool-call rate limiter.
+ *
+ * Applied at the top of `handleToolCall` in `src/handlers/intent.ts`. Returns an MCP
+ * tool error (NOT HTTP 429) on denial so the LLM client surfaces it as a tool failure
+ * and the agent loop backs off correctly. Per-user token bucket keyed on the resolved
+ * user identity (userName / clientId / __anon__).
+ *
+ * Design choices:
+ * - Per-instance, in-memory only. Multi-instance attackers cost `limit × instances` —
+ *   acceptable trade-off, matches stateless-DCR philosophy from PR #212.
+ * - Stdio mode is exempt because there's no authInfo to key on; the caller is
+ *   responsible for skipping the consume in that case.
+ * - When `perMinute === 0`, the factory returns a stub whose `consume` resolves
+ *   immediately with `{ allowed: true }` — no allocation, no per-key bookkeeping.
+ *   This is the clean opt-out for single-user deployments.
+ * - Cost weighting per tool is intentionally deferred to v2 — every consume call is
+ *   one point. See ADR-0004 for the rationale.
+ */
+import type { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
+export type RateLimitDecision = {
+    allowed: true;
+} | {
+    allowed: false;
+    retryAfterMs: number;
+    limitPerMinute: number;
+};
+/**
+ * Resolve the per-user rate-limit key from an `AuthInfo`, walking the most-
+ * specific identity claims first so distinct users never share a quota when
+ * they share an auth client / application.
+ *
+ * Order, by descending specificity:
+ *   1. `extra.userName`        — XSUAA logon name (`securityContext.getLogonName()`)
+ *   2. `extra.email`           — XSUAA / OIDC email when populated
+ *   3. `extra.sub`             — OIDC subject claim (guaranteed unique per user within issuer)
+ *   4. `extra.preferred_username` — sometimes set on OIDC tokens
+ *   5. `clientId`              — last resort. Note for OIDC this is `azp`
+ *      (the app's client id), shared by all users of that app — so falling here
+ *      collapses them into one bucket. The earlier checks exist specifically
+ *      to avoid that. Acceptable only for the API-key path where the clientId
+ *      is `api-key:<profile>` and the operator has chosen the profile granularity.
+ *   6. `'__anon__'`            — token with no usable identity claim. Single
+ *      shared bucket for anonymous traffic. Operators should configure auth so
+ *      this branch is never reached in production.
+ *
+ * Why not just `sub`? Because XSUAA tokens don't put `sub` on `extra`; they put
+ * the SAP logon name on `extra.userName`. OIDC does the inverse. We accept both
+ * shapes rather than forcing every auth provider to align on one claim.
+ */
+export declare function resolveRateLimitUserKey(authInfo: AuthInfo | undefined): string;
+export interface McpRateLimiter {
+    /**
+     * Try to consume one point for `userKey`. Resolves `{ allowed: true }` when the
+     * bucket has tokens, `{ allowed: false, retryAfterMs, limitPerMinute }` when it
+     * doesn't. Never throws — internal RateLimiterRes rejection is caught here.
+     *
+     * `tool` is recorded for the audit event at the call site; it doesn't affect
+     * the bucket.
+     */
+    consume(userKey: string, tool: string): Promise<RateLimitDecision>;
+}
+/**
+ * Build a per-user MCP rate limiter.
+ *
+ * @param perMinute Per-user requests per minute. `0` returns a no-op stub.
+ */
+export declare function createMcpRateLimiter(perMinute: number): McpRateLimiter;
+//# sourceMappingURL=mcp-rate-limit.d.ts.map

package/dist/server/mcp-rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-rate-limit.d.ts","sourceRoot":"","sources":["../../src/server/mcp-rate-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gDAAgD,CAAC;AAG/E,MAAM,MAAM,iBAAiB,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CAAC;AAErH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,GAAG,MAAM,CAa9E;AAED,MAAM,WAAW,cAAc;IAC7B;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACpE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAgCtE"}

package/dist/server/mcp-rate-limit.js

@@ -0,0 +1,92 @@
+/**
+ * Layer 2 — Per-user MCP tool-call rate limiter.
+ *
+ * Applied at the top of `handleToolCall` in `src/handlers/intent.ts`. Returns an MCP
+ * tool error (NOT HTTP 429) on denial so the LLM client surfaces it as a tool failure
+ * and the agent loop backs off correctly. Per-user token bucket keyed on the resolved
+ * user identity (userName / clientId / __anon__).
+ *
+ * Design choices:
+ * - Per-instance, in-memory only. Multi-instance attackers cost `limit × instances` —
+ *   acceptable trade-off, matches stateless-DCR philosophy from PR #212.
+ * - Stdio mode is exempt because there's no authInfo to key on; the caller is
+ *   responsible for skipping the consume in that case.
+ * - When `perMinute === 0`, the factory returns a stub whose `consume` resolves
+ *   immediately with `{ allowed: true }` — no allocation, no per-key bookkeeping.
+ *   This is the clean opt-out for single-user deployments.
+ * - Cost weighting per tool is intentionally deferred to v2 — every consume call is
+ *   one point. See ADR-0004 for the rationale.
+ */
+import { RateLimiterMemory, RateLimiterRes } from 'rate-limiter-flexible';
+/**
+ * Resolve the per-user rate-limit key from an `AuthInfo`, walking the most-
+ * specific identity claims first so distinct users never share a quota when
+ * they share an auth client / application.
+ *
+ * Order, by descending specificity:
+ *   1. `extra.userName`        — XSUAA logon name (`securityContext.getLogonName()`)
+ *   2. `extra.email`           — XSUAA / OIDC email when populated
+ *   3. `extra.sub`             — OIDC subject claim (guaranteed unique per user within issuer)
+ *   4. `extra.preferred_username` — sometimes set on OIDC tokens
+ *   5. `clientId`              — last resort. Note for OIDC this is `azp`
+ *      (the app's client id), shared by all users of that app — so falling here
+ *      collapses them into one bucket. The earlier checks exist specifically
+ *      to avoid that. Acceptable only for the API-key path where the clientId
+ *      is `api-key:<profile>` and the operator has chosen the profile granularity.
+ *   6. `'__anon__'`            — token with no usable identity claim. Single
+ *      shared bucket for anonymous traffic. Operators should configure auth so
+ *      this branch is never reached in production.
+ *
+ * Why not just `sub`? Because XSUAA tokens don't put `sub` on `extra`; they put
+ * the SAP logon name on `extra.userName`. OIDC does the inverse. We accept both
+ * shapes rather than forcing every auth provider to align on one claim.
+ */
+export function resolveRateLimitUserKey(authInfo) {
+    if (!authInfo)
+        return '__anon__';
+    const extra = (authInfo.extra ?? {});
+    const candidates = [extra.userName, extra.email, extra.sub, extra.preferred_username, authInfo.clientId];
+    for (const c of candidates) {
+        if (typeof c === 'string' && c.length > 0)
+            return c;
+    }
+    return '__anon__';
+}
+/**
+ * Build a per-user MCP rate limiter.
+ *
+ * @param perMinute Per-user requests per minute. `0` returns a no-op stub.
+ */
+export function createMcpRateLimiter(perMinute) {
+    if (perMinute === 0) {
+        return {
+            async consume(_userKey, _tool) {
+                return { allowed: true };
+            },
+        };
+    }
+    const limiter = new RateLimiterMemory({ points: perMinute, duration: 60 });
+    return {
+        async consume(userKey, _tool) {
+            try {
+                await limiter.consume(userKey, 1);
+                return { allowed: true };
+            }
+            catch (rejected) {
+                // RateLimiterRes is thrown on overflow; anything else is unexpected.
+                if (rejected instanceof RateLimiterRes) {
+                    return {
+                        allowed: false,
+                        retryAfterMs: rejected.msBeforeNext,
+                        limitPerMinute: perMinute,
+                    };
+                }
+                // Defensive: treat unexpected errors as "allowed" so a misbehaving limiter
+                // can never wedge legitimate traffic. The exception itself bubbles up via
+                // logging when the limiter is fixed; in the meantime users still get through.
+                return { allowed: true };
+            }
+        },
+    };
+}
+//# sourceMappingURL=mcp-rate-limit.js.map

package/dist/server/mcp-rate-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-rate-limit.js","sourceRoot":"","sources":["../../src/server/mcp-rate-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAI1E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,uBAAuB,CAAC,QAA8B;IACpE,IAAI,CAAC,QAAQ;QAAE,OAAO,UAAU,CAAC;IACjC,MAAM,KAAK,GAAG,CAAC,QAAQ,CAAC,KAAK,IAAI,EAAE,CAKlC,CAAC;IACF,MAAM,UAAU,GAAG,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,kBAAkB,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACzG,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAcD;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,SAAiB;IACpD,IAAI,SAAS,KAAK,CAAC,EAAE,CAAC;QACpB,OAAO;YACL,KAAK,CAAC,OAAO,CAAC,QAAgB,EAAE,KAAa;gBAC3C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;YAC3B,CAAC;SACF,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,iBAAiB,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC;IAE3E,OAAO;QACL,KAAK,CAAC,OAAO,CAAC,OAAe,EAAE,KAAa;YAC1C,IAAI,CAAC;gBACH,MAAM,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;gBAClC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;YAC3B,CAAC;YAAC,OAAO,QAAQ,EAAE,CAAC;gBAClB,qEAAqE;gBACrE,IAAI,QAAQ,YAAY,cAAc,EAAE,CAAC;oBACvC,OAAO;wBACL,OAAO,EAAE,KAAK;wBACd,YAAY,EAAE,QAAQ,CAAC,YAAY;wBACnC,cAAc,EAAE,SAAS;qBAC1B,CAAC;gBACJ,CAAC;gBACD,2EAA2E;gBAC3E,0EAA0E;gBAC1E,8EAA8E;gBAC9E,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;YAC3B,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/server/server.d.ts

@@ -7,13 +7,15 @@
  * - http-streamable: for remote/containerized deployments
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import type { BTPConfig, BTPProxyConfig } from '../adt/btp.js';
+import type { BTPConfig, BTPProxyConfig, PerUserAuthTokens } from '../adt/btp.js';
 import type { AdtClientConfig } from '../adt/config.js';
+import { Semaphore } from '../adt/semaphore.js';
 import { CachingLayer } from '../cache/caching-layer.js';
 import { type ToolDefinition } from '../handlers/tools.js';
+import { type McpRateLimiter } from './mcp-rate-limit.js';
 import type { ServerConfig } from './types.js';
 /** ARC-1 version */
-export declare const VERSION = "0.9.5";
+export declare const VERSION = "0.9.7";
 /**
  * Filter tools by user scope + server deny list.
  *
@@ -27,7 +29,25 @@ export declare function logAuthSummary(config: ServerConfig): void;
 /** Build the base ADT client config (without per-user auth) */
 export declare function buildAdtConfig(config: ServerConfig, btpProxy?: BTPProxyConfig, bearerTokenProvider?: () => Promise<string>, opts?: {
     perUser?: boolean;
-}): Partial<AdtClientConfig>;
+}, adtSemaphore?: Semaphore): Partial<AdtClientConfig>;
+/**
+ * Map per-user auth tokens from the BTP Destination Service onto an AdtClientConfig.
+ * Mutates and returns `adtConfig`. Exported for unit testing.
+ *
+ * Precedence (most-specific first):
+ *  1. ppProxyAuth         — Option 1: jwt-bearer exchanged token → Proxy-Authorization (Cloud Connector)
+ *  2. sapConnectivityAuth — Option 2: SAML assertion → SAP-Connectivity-Authentication (Cloud Connector)
+ *  3. bearerToken         — OAuth2UserTokenExchange / OAuth2SAMLBearerAssertion: a user-context Bearer
+ *                           token minted at the target's XSUAA → `Authorization: Bearer` (cloud-to-cloud,
+ *                           e.g. a BTP ABAP Environment over the Internet — no Cloud Connector / proxy).
+ *
+ * Throws when none is present (PP could not produce a usable per-user credential).
+ *
+ * In every success branch the SAP password is cleared and `username` is set to a display-only
+ * value — it is never used for auth or access control; the real SAP identity rides in the
+ * chosen token/assertion.
+ */
+export declare function applyPerUserAuthTokens(adtConfig: Partial<AdtClientConfig>, authTokens: PerUserAuthTokens, displayUsername: string | undefined, destName: string): Partial<AdtClientConfig>;
 /**
  * Run a one-time feature probe against the SAP system using the shared/default client.
  * Returns a promise that resolves once probe results are stored in cachedFeatures.
@@ -36,7 +56,7 @@ export declare function buildAdtConfig(config: ServerConfig, btpProxy?: BTPProxy
  * source_code from users who might have authorization.  Without btpConfig, PP cannot
  * create per-user clients, so shared-client auth failures are definitive.
  */
-export declare function runStartupProbe(config: ServerConfig, btpProxy?: BTPProxyConfig, bearerTokenProvider?: () => Promise<string>, btpConfig?: BTPConfig): Promise<void>;
+export declare function runStartupProbe(config: ServerConfig, btpProxy?: BTPProxyConfig, bearerTokenProvider?: () => Promise<string>, btpConfig?: BTPConfig, adtSemaphore?: Semaphore): Promise<void>;
 export interface StartupAuthPreflightResult {
     status: 'ok' | 'failed' | 'inconclusive' | 'skipped';
     /** When true, shared-client SAP tool calls must be blocked to prevent repeated auth failures. */
@@ -58,7 +78,7 @@ export interface StartupAuthPreflightResult {
  * - 401/403 are blocking failures
  * - Network/other failures are inconclusive (non-blocking)
  */
-export declare function runStartupAuthPreflight(config: ServerConfig, btpProxy?: BTPProxyConfig, bearerTokenProvider?: () => Promise<string>): Promise<StartupAuthPreflightResult>;
+export declare function runStartupAuthPreflight(config: ServerConfig, btpProxy?: BTPProxyConfig, bearerTokenProvider?: () => Promise<string>, adtSemaphore?: Semaphore): Promise<StartupAuthPreflightResult>;
 export declare function formatStartupAuthPreflightToolError(preflight: StartupAuthPreflightResult): string;
 /**
  * Create the MCP server with registered tool handlers.
@@ -70,7 +90,7 @@ export declare function formatStartupAuthPreflightToolError(preflight: StartupAu
  * @param startupProbePromise Promise from runStartupProbe() — ListTools waits on this
  * @param startupAuthPreflightPromise Promise from runStartupAuthPreflight() — CallTool blocks on auth failure in shared mode
  */
-export declare function createServer(config: ServerConfig, btpProxy?: BTPProxyConfig, btpConfig?: BTPConfig, bearerTokenProvider?: () => Promise<string>, cachingLayer?: CachingLayer, startupProbePromise?: Promise<void>, startupAuthPreflightPromise?: Promise<StartupAuthPreflightResult>): Server;
+export declare function createServer(config: ServerConfig, btpProxy?: BTPProxyConfig, btpConfig?: BTPConfig, bearerTokenProvider?: () => Promise<string>, cachingLayer?: CachingLayer, startupProbePromise?: Promise<void>, startupAuthPreflightPromise?: Promise<StartupAuthPreflightResult>, adtSemaphore?: Semaphore, mcpRateLimiter?: McpRateLimiter): Server;
 /**
  * Create and start the MCP server.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/server/server.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAGnE,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAMxD,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AASzD,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAK/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,oBAAoB;AACpB,eAAO,MAAM,OAAO,UAAU,CAAC;AAuD/B;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,cAAc,EAAE,EACvB,MAAM,EAAE,MAAM,EAAE,EAChB,WAAW,GAAE,MAAM,EAAO,GACzB,cAAc,EAAE,CA0BlB;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAgCzD;AAED,+DAA+D;AAG/D,wBAAgB,cAAc,CAC5B,MAAM,EAAE,YAAY,EACpB,QAAQ,CAAC,EAAE,cAAc,EACzB,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,EAC3C,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAC3B,OAAO,CAAC,eAAe,CAAC,CAkC1B;AAqFD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,YAAY,EACpB,QAAQ,CAAC,EAAE,cAAc,EACzB,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,EAC3C,SAAS,CAAC,EAAE,SAAS,GACpB,OAAO,CAAC,IAAI,CAAC,CA8Cf;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,IAAI,GAAG,QAAQ,GAAG,cAAc,GAAG,SAAS,CAAC;IACrD,iGAAiG;IACjG,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAqCD;;;;;;;;;;;GAWG;AACH,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,YAAY,EACpB,QAAQ,CAAC,EAAE,cAAc,EACzB,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GAC1C,OAAO,CAAC,0BAA0B,CAAC,CAmDrC;AAED,wBAAgB,mCAAmC,CAAC,SAAS,EAAE,0BAA0B,GAAG,MAAM,CASjG;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,YAAY,EACpB,QAAQ,CAAC,EAAE,cAAc,EACzB,SAAS,CAAC,EAAE,SAAS,EACrB,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,EAC3C,YAAY,CAAC,EAAE,YAAY,EAC3B,mBAAmB,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,EACnC,2BAA2B,CAAC,EAAE,OAAO,CAAC,0BAA0B,CAAC,GAChE,MAAM,CA4JR;AAoCD;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,YAAY,EACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,YAAY,EAAE,YAAY,CAAC,GAC1D,OAAO,CAAC,MAAM,CAAC,CA4QjB"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/server/server.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAGnE,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAElF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAKxD,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAGhD,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AASzD,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAI/E,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAEhF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,oBAAoB;AACpB,eAAO,MAAM,OAAO,UAAU,CAAC;AAuD/B;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,cAAc,EAAE,EACvB,MAAM,EAAE,MAAM,EAAE,EAChB,WAAW,GAAE,MAAM,EAAO,GACzB,cAAc,EAAE,CA0BlB;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAgCzD;AAED,+DAA+D;AAO/D,wBAAgB,cAAc,CAC5B,MAAM,EAAE,YAAY,EACpB,QAAQ,CAAC,EAAE,cAAc,EACzB,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,EAC3C,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,EAC5B,YAAY,CAAC,EAAE,SAAS,GACvB,OAAO,CAAC,eAAe,CAAC,CAmC1B;AAiED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,OAAO,CAAC,eAAe,CAAC,EACnC,UAAU,EAAE,iBAAiB,EAC7B,eAAe,EAAE,MAAM,GAAG,SAAS,EACnC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,eAAe,CAAC,CAyB1B;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,YAAY,EACpB,QAAQ,CAAC,EAAE,cAAc,EACzB,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,EAC3C,SAAS,CAAC,EAAE,SAAS,EACrB,YAAY,CAAC,EAAE,SAAS,GACvB,OAAO,CAAC,IAAI,CAAC,CA2Df;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,IAAI,GAAG,QAAQ,GAAG,cAAc,GAAG,SAAS,CAAC;IACrD,iGAAiG;IACjG,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAqCD;;;;;;;;;;;GAWG;AACH,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,YAAY,EACpB,QAAQ,CAAC,EAAE,cAAc,EACzB,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,EAC3C,YAAY,CAAC,EAAE,SAAS,GACvB,OAAO,CAAC,0BAA0B,CAAC,CAmDrC;AAED,wBAAgB,mCAAmC,CAAC,SAAS,EAAE,0BAA0B,GAAG,MAAM,CASjG;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,YAAY,EACpB,QAAQ,CAAC,EAAE,cAAc,EACzB,SAAS,CAAC,EAAE,SAAS,EACrB,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,EAC3C,YAAY,CAAC,EAAE,YAAY,EAC3B,mBAAmB,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,EACnC,2BAA2B,CAAC,EAAE,OAAO,CAAC,0BAA0B,CAAC,EACjE,YAAY,CAAC,EAAE,SAAS,EACxB,cAAc,CAAC,EAAE,cAAc,GAC9B,MAAM,CA+JR;AAoCD;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,YAAY,EACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,YAAY,EAAE,YAAY,CAAC,GAC1D,OAAO,CAAC,MAAM,CAAC,CAoSjB"}

package/dist/server/server.js

@@ -12,7 +12,9 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprot
 import { AdtClient } from '../adt/client.js';
 import { resolveCookies } from '../adt/cookies.js';
 import { AdtApiError } from '../adt/errors.js';
+import { shouldWarnPreStatefulRelease } from '../adt/release.js';
 import { deriveUserSafety, deriveUserSafetyFromProfile } from '../adt/safety.js';
+import { Semaphore } from '../adt/semaphore.js';
 import { getActionPolicy, hasRequiredScope } from '../authz/policy.js';
 import { CachingLayer } from '../cache/caching-layer.js';
 import { MemoryCache } from '../cache/memory.js';
@@ -21,9 +23,10 @@ import { getToolDefinitions } from '../handlers/tools.js';
 import { API_KEY_PROFILES } from './config.js';
 import { isActionDenied } from './deny-actions.js';
 import { initLogger, logger } from './logger.js';
+import { createMcpRateLimiter } from './mcp-rate-limit.js';
 import { FileSink } from './sinks/file.js';
 /** ARC-1 version */
-export const VERSION = '0.9.5'; // x-release-please-version
+export const VERSION = '0.9.7'; // x-release-please-version
 /**
  * Prune a tool's action OR type enum (or both) based on the user's scopes and
  * the server's denyActions list. Uses ACTION_POLICY as the single source of truth.
@@ -159,7 +162,11 @@ export function logAuthSummary(config) {
 /** Build the base ADT client config (without per-user auth) */
 // When perUser=true, strips shared credentials (username/password/cookies)
 // so per-user PP clients never inherit admin auth.
-export function buildAdtConfig(config, btpProxy, bearerTokenProvider, opts) {
+//
+// adtSemaphore (Layer 3): when provided, the constructed AdtClient shares this single
+// server-wide semaphore with every other client built from this server. This is what
+// makes ARC1_MAX_CONCURRENT a true server-wide cap rather than per-client.
+export function buildAdtConfig(config, btpProxy, bearerTokenProvider, opts, adtSemaphore) {
     const adtConfig = {
         baseUrl: config.url,
         client: config.client,
@@ -169,6 +176,7 @@ export function buildAdtConfig(config, btpProxy, bearerTokenProvider, opts) {
         btpProxy,
         bearerTokenProvider,
         maxConcurrent: config.maxConcurrent,
+        adtSemaphore,
         safety: {
             allowWrites: config.allowWrites,
             allowDataPreview: config.allowDataPreview,
@@ -203,7 +211,7 @@ export function buildAdtConfig(config, btpProxy, bearerTokenProvider, opts) {
  * The Cloud Connector uses this header to generate an X.509 cert
  * mapped to the SAP user via CERTRULE.
  */
-async function createPerUserClient(config, btpConfig, btpProxy, userJwt) {
+async function createPerUserClient(config, btpConfig, btpProxy, userJwt, adtSemaphore) {
     const { lookupDestinationWithUserToken } = await import('../adt/btp.js');
     // Use SAP_BTP_PP_DESTINATION if set, otherwise fall back to SAP_BTP_DESTINATION.
     // This enables a dual-destination approach:
@@ -222,7 +230,7 @@ async function createPerUserClient(config, btpConfig, btpProxy, userJwt) {
     const effectiveProxy = btpProxy && destination.CloudConnectorLocationId !== undefined
         ? { ...btpProxy, locationId: destination.CloudConnectorLocationId }
         : btpProxy;
-    const adtConfig = buildAdtConfig(config, effectiveProxy, undefined, { perUser: true });
+    const adtConfig = buildAdtConfig(config, effectiveProxy, undefined, { perUser: true }, adtSemaphore);
     // Override URL from destination (in case it differs from startup-resolved URL)
     adtConfig.baseUrl = destination.URL;
     // Set per-user auth for principal propagation.
@@ -240,22 +248,42 @@ async function createPerUserClient(config, btpConfig, btpProxy, userJwt) {
     catch {
         displayUsername = undefined;
     }
+    applyPerUserAuthTokens(adtConfig, authTokens, displayUsername, destName);
+    return new AdtClient(adtConfig);
+}
+/**
+ * Map per-user auth tokens from the BTP Destination Service onto an AdtClientConfig.
+ * Mutates and returns `adtConfig`. Exported for unit testing.
+ *
+ * Precedence (most-specific first):
+ *  1. ppProxyAuth         — Option 1: jwt-bearer exchanged token → Proxy-Authorization (Cloud Connector)
+ *  2. sapConnectivityAuth — Option 2: SAML assertion → SAP-Connectivity-Authentication (Cloud Connector)
+ *  3. bearerToken         — OAuth2UserTokenExchange / OAuth2SAMLBearerAssertion: a user-context Bearer
+ *                           token minted at the target's XSUAA → `Authorization: Bearer` (cloud-to-cloud,
+ *                           e.g. a BTP ABAP Environment over the Internet — no Cloud Connector / proxy).
+ *
+ * Throws when none is present (PP could not produce a usable per-user credential).
+ *
+ * In every success branch the SAP password is cleared and `username` is set to a display-only
+ * value — it is never used for auth or access control; the real SAP identity rides in the
+ * chosen token/assertion.
+ */
+export function applyPerUserAuthTokens(adtConfig, authTokens, displayUsername, destName) {
     if (authTokens.ppProxyAuth) {
-        // Option 1: exchanged token replaces Proxy-Authorization
         adtConfig.ppProxyAuth = authTokens.ppProxyAuth;
-        adtConfig.username = displayUsername;
-        adtConfig.password = undefined;
     }
     else if (authTokens.sapConnectivityAuth) {
-        // Option 2: SAML assertion from Destination Service
         adtConfig.sapConnectivityAuth = authTokens.sapConnectivityAuth;
-        adtConfig.username = displayUsername;
-        adtConfig.password = undefined;
     }
     else if (authTokens.bearerToken) {
-        // TODO: Bearer token auth for OAuth2SAMLBearerAssertion destinations
-        // This would replace basic auth with Bearer token
-        logger.warn('Bearer token auth from destination not yet implemented — falling back to basic auth');
+        // createPerUserClient runs per request and the Cloud SDK caches the exchanged token per
+        // user (TTL-bounded), so a provider returning the already-resolved token is fresh for the
+        // request's lifetime.
+        const bearer = authTokens.bearerToken;
+        adtConfig.bearerTokenProvider = async () => bearer;
+        logger.debug('PP: using destination-exchanged Bearer token (OAuth2UserTokenExchange)', {
+            destination: destName,
+        });
     }
     else {
         // No per-user auth token received.
@@ -263,7 +291,9 @@ async function createPerUserClient(config, btpConfig, btpProxy, userJwt) {
             'no SAP-Connectivity-Authentication header, Bearer token, or jwt-bearer exchange token returned. ' +
             'Check Cloud Connector status, destination configuration, and user JWT validity.');
     }
-    return new AdtClient(adtConfig);
+    adtConfig.username = displayUsername;
+    adtConfig.password = undefined;
+    return adtConfig;
 }
 /**
  * Run a one-time feature probe against the SAP system using the shared/default client.
@@ -273,8 +303,8 @@ async function createPerUserClient(config, btpConfig, btpProxy, userJwt) {
  * source_code from users who might have authorization.  Without btpConfig, PP cannot
  * create per-user clients, so shared-client auth failures are definitive.
  */
-export function runStartupProbe(config, btpProxy, bearerTokenProvider, btpConfig) {
-    const client = new AdtClient(buildAdtConfig(config, btpProxy, bearerTokenProvider));
+export function runStartupProbe(config, btpProxy, bearerTokenProvider, btpConfig, adtSemaphore) {
+    const client = new AdtClient(buildAdtConfig(config, btpProxy, bearerTokenProvider, undefined, adtSemaphore));
     return (async () => {
         try {
             const { defaultFeatureConfig } = await import('../adt/config.js');
@@ -313,6 +343,17 @@ export function runStartupProbe(config, btpProxy, bearerTokenProvider, btpConfig
                 }
             }
             setCachedFeatures(features);
+            // Proactive warning: on SAP_BASIS < 7.51 the ADT REST handler does not honor the
+            // stateful-session header over HTTP, so object writes fail with 423 "invalid lock
+            // handle" until the abapfs_extensions enhancement is installed. Warn at startup —
+            // before the first cryptic 423 — but only when writes are enabled (issue #293).
+            if (shouldWarnPreStatefulRelease(config.allowWrites, features.abapRelease)) {
+                logger.warn(`SAP_BASIS ${features.abapRelease} is below 7.51 and does not natively honor stateful ADT ` +
+                    'HTTP sessions — object writes will fail with 423 "invalid lock handle" UNLESS the ' +
+                    'abapfs_extensions enhancement is installed on the SAP system ' +
+                    '(https://github.com/marcellourbani/abapfs_extensions). If writes already work, this is ' +
+                    'installed and you can ignore this. See docs/sap-trial-setup.md (423 troubleshooting).');
+            }
             setCachedDiscovery(features.discoveryMap ?? new Map());
         }
         catch {
@@ -358,7 +399,7 @@ function buildStartupAuthFailureReason(statusCode, config) {
  * - 401/403 are blocking failures
  * - Network/other failures are inconclusive (non-blocking)
  */
-export async function runStartupAuthPreflight(config, btpProxy, bearerTokenProvider) {
+export async function runStartupAuthPreflight(config, btpProxy, bearerTokenProvider, adtSemaphore) {
     const checkedAt = new Date().toISOString();
     const endpoint = STARTUP_AUTH_ENDPOINT;
     if (config.ppEnabled) {
@@ -372,7 +413,7 @@ export async function runStartupAuthPreflight(config, btpProxy, bearerTokenProvi
         return { status: 'skipped', blocking: false, endpoint, checkedAt, reason };
     }
     try {
-        const client = new AdtClient(buildAdtConfig(config, btpProxy, bearerTokenProvider));
+        const client = new AdtClient(buildAdtConfig(config, btpProxy, bearerTokenProvider, undefined, adtSemaphore));
         await client.http.get(endpoint);
         const reason = 'Startup auth preflight succeeded for shared SAP credentials.';
         logger.info(reason, { endpoint });
@@ -424,10 +465,12 @@ export function formatStartupAuthPreflightToolError(preflight) {
  * @param startupProbePromise Promise from runStartupProbe() — ListTools waits on this
  * @param startupAuthPreflightPromise Promise from runStartupAuthPreflight() — CallTool blocks on auth failure in shared mode
  */
-export function createServer(config, btpProxy, btpConfig, bearerTokenProvider, cachingLayer, startupProbePromise, startupAuthPreflightPromise) {
+export function createServer(config, btpProxy, btpConfig, bearerTokenProvider, cachingLayer, startupProbePromise, startupAuthPreflightPromise, adtSemaphore, mcpRateLimiter) {
     const server = new Server({ name: 'arc-1', version: VERSION }, { capabilities: { tools: {} } });
-    // Create default ADT client (shared, uses startup-time credentials or OAuth bearer)
-    const defaultClient = new AdtClient(buildAdtConfig(config, btpProxy, bearerTokenProvider));
+    // Create default ADT client (shared, uses startup-time credentials or OAuth bearer).
+    // Passes the shared server-wide semaphore so per-user PP clients (created at request
+    // time) share the same Layer 3 concurrency cap.
+    const defaultClient = new AdtClient(buildAdtConfig(config, btpProxy, bearerTokenProvider, undefined, adtSemaphore));
     // Cookie-auth preflight propagation: when startup preflight returned a non-blocking
     // 401 in SAP_COOKIE_FILE mode, the throwaway preflight client marked itself stale —
     // but the long-lived defaultClient was constructed independently with cookies read at
@@ -487,7 +530,7 @@ export function createServer(config, btpProxy, btpConfig, bearerTokenProvider, c
             const ppUser = (extra.authInfo?.extra?.userName ?? extra.authInfo?.clientId);
             const ppDest = process.env.SAP_BTP_PP_DESTINATION ?? process.env.SAP_BTP_DESTINATION ?? '';
             try {
-                client = await createPerUserClient(config, btpConfig, btpProxy, token);
+                client = await createPerUserClient(config, btpConfig, btpProxy, token, adtSemaphore);
                 isPerUserClient = true;
                 logger.emitAudit({
                     timestamp: new Date().toISOString(),
@@ -558,7 +601,7 @@ export function createServer(config, btpProxy, btpConfig, bearerTokenProvider, c
             effectiveClient = client.withSafety(effectiveSafety);
         }
         effectiveClient.http.setDiscoveryMap(getCachedDiscovery());
-        const result = await handleToolCall(effectiveClient, config, toolName, args, extra.authInfo, server, cachingLayer, isPerUserClient);
+        const result = await handleToolCall(effectiveClient, config, toolName, args, extra.authInfo, server, cachingLayer, isPerUserClient, mcpRateLimiter);
         return { ...result };
     });
     return server;
@@ -705,6 +748,22 @@ export async function createAndStartServer(config, sources) {
             ppEnabled: config.ppEnabled,
         });
     }
+    // ─── Layer 3: shared SAP-bound Semaphore (server-wide cap) ────────
+    // One Semaphore for the whole process. Threaded into the shared startup client AND
+    // every per-user PP client built at request time, so ARC1_MAX_CONCURRENT is a true
+    // server-wide ceiling rather than a per-client one (the latter would multiply the cap
+    // by the number of active PP users — see ADR-0004).
+    const adtSemaphore = new Semaphore(config.maxConcurrent);
+    logger.info('SAP semaphore', { maxConcurrent: config.maxConcurrent, scope: 'server-wide' });
+    // ─── Layer 2: per-user MCP tool-call rate limiter ─────────────────
+    // Applied inside handleToolCall. Stdio (no authInfo) is exempt — there's no user
+    // identity to key on. When rateLimit=0 the factory returns a no-op stub.
+    // See docs_page/rate-limiting.md.
+    const mcpRateLimiter = createMcpRateLimiter(config.rateLimit);
+    logger.info('MCP rate limiting', {
+        perMinute: config.rateLimit,
+        disabled: config.rateLimit === 0,
+    });
     // ─── Cache Setup ───────────────────────────────────────────────────
     const cachingLayer = await createCachingLayer(config);
     if (cachingLayer) {
@@ -720,7 +779,7 @@ export async function createAndStartServer(config, sources) {
     if (config.cacheWarmup && cachingLayer && config.url) {
         try {
             const { runWarmup } = await import('../cache/warmup.js');
-            const warmupClient = new AdtClient(buildAdtConfig(config, btpProxy, bearerTokenProvider));
+            const warmupClient = new AdtClient(buildAdtConfig(config, btpProxy, bearerTokenProvider, undefined, adtSemaphore));
             const result = await runWarmup(warmupClient, cachingLayer, config.cacheWarmupPackages || undefined, config.systemType);
             logger.info('Cache warmup completed', {
                 objects: result.totalObjects,
@@ -740,7 +799,7 @@ export async function createAndStartServer(config, sources) {
     // Run feature probe once at startup — shared across all requests (stdio and HTTP).
     // First run startup auth preflight in shared mode. If it blocks (401/403), skip feature probe
     // to avoid firing many failing requests with invalid technical credentials.
-    const startupAuthPreflightPromise = runStartupAuthPreflight(config, btpProxy, bearerTokenProvider);
+    const startupAuthPreflightPromise = runStartupAuthPreflight(config, btpProxy, bearerTokenProvider, adtSemaphore);
     const startupProbePromise = (async () => {
         const authPreflight = await startupAuthPreflightPromise;
         if (authPreflight.blocking) {
@@ -748,9 +807,9 @@ export async function createAndStartServer(config, sources) {
             setCachedDiscovery(new Map());
             return;
         }
-        await runStartupProbe(config, btpProxy, bearerTokenProvider, btpConfig);
+        await runStartupProbe(config, btpProxy, bearerTokenProvider, btpConfig, adtSemaphore);
     })();
-    const server = createServer(config, btpProxy, btpConfig, bearerTokenProvider, cachingLayer, startupProbePromise, startupAuthPreflightPromise);
+    const server = createServer(config, btpProxy, btpConfig, bearerTokenProvider, cachingLayer, startupProbePromise, startupAuthPreflightPromise, adtSemaphore, mcpRateLimiter);
     // Shutdown hook for SQLite cache cleanup (guard against double-close from multiple signals).
     // IMPORTANT: registering a SIGINT/SIGTERM listener suppresses Node's default exit behavior,
     // so we must call process.exit() explicitly after cleanup — otherwise Ctrl+C hangs the process.
@@ -820,7 +879,7 @@ export async function createAndStartServer(config, sources) {
             }
         }
         const { startHttpServer } = await import('./http.js');
-        await startHttpServer(() => createServer(config, btpProxy, btpConfig, bearerTokenProvider, cachingLayer, startupProbePromise, startupAuthPreflightPromise), config, xsuaaCredentials);
+        await startHttpServer(() => createServer(config, btpProxy, btpConfig, bearerTokenProvider, cachingLayer, startupProbePromise, startupAuthPreflightPromise, adtSemaphore, mcpRateLimiter), config, xsuaaCredentials);
     }
     return server;
 }