fa-mcp-sdk 0.4.141 → 0.11.2

package/dist/core/web/cors.js

@@ -2,21 +2,42 @@ import cors from 'cors';
 import { config } from '../bootstrap/init-config.js';
 const { originHosts } = config.webServer;
 const originTestRe = new RegExp(`https?:\\/\\/(${originHosts.join('|')})(:\\d+)?`, 'i');
+/**
+ * CORS guard (standard §6). Requests carrying an `Origin` header that is NOT covered by
+ * `webServer.originHosts` are rejected with HTTP 403 + a JSON-RPC error body. Same-origin
+ * requests (no `Origin` header) and tools (curl, MCP test clients) pass through.
+ *
+ * Production-time refusal of the "allow everything" configuration is enforced in
+ * `validateProductionWebServerConfig()` so the server never starts in that state.
+ */
 export const applyCors = (app) => {
     const corsOptions = {
-        // https://www.npmjs.com/package/cors#configuring-cors
-        // origin: /https?:\/\/(localhost|any-service.corp.com)(:\d+)?/
         origin(origin, callback) {
-            if (originTestRe.test(origin) || !origin) {
+            if (!origin || originTestRe.test(origin)) {
                 callback(null, true);
             }
             else {
-                callback(null, true);
-                // callback(new Error('Not allowed by CORS'));
+                callback(new Error('CORS_ORIGIN_NOT_ALLOWED'));
             }
         },
     };
     app.use(cors(corsOptions));
+    // Convert the CORS rejection into a 403 with a structured JSON-RPC error instead of letting
+    // Express fall through to the generic 500 handler.
+    app.use((err, _req, res, next) => {
+        if (err && err.message === 'CORS_ORIGIN_NOT_ALLOWED') {
+            return res.status(403).json({
+                jsonrpc: '2.0',
+                id: null,
+                error: {
+                    code: -32600,
+                    message: 'Origin not allowed by CORS policy',
+                    data: { reason: 'origin_not_allowed' },
+                },
+            });
+        }
+        return next(err);
+    });
     return corsOptions;
 };
 //# sourceMappingURL=cors.js.map

package/dist/core/web/cors.js.map

@@ -1 +1 @@
-{"version":3,"file":"cors.js","sourceRoot":"","sources":["../../../src/core/web/cors.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AAGxB,OAAO,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAErD,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,CAAC,SAAS,CAAC;AAEzC,MAAM,YAAY,GAAG,IAAI,MAAM,CAAC,iBAAiB,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;AAExF,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,GAAY,EAAE,EAAE;IACxC,MAAM,WAAW,GAAG;QAClB,sDAAsD;QACtD,+DAA+D;QAC/D,MAAM,CAAC,MAAW,EAAE,QAAkB;YACpC,IAAI,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;gBACzC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YACvB,CAAC;iBAAM,CAAC;gBACN,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;gBACrB,8CAA8C;YAChD,CAAC;QACH,CAAC;KACF,CAAC;IAEF,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;IAC3B,OAAO,WAAW,CAAC;AACrB,CAAC,CAAC"}
+{"version":3,"file":"cors.js","sourceRoot":"","sources":["../../../src/core/web/cors.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AAGxB,OAAO,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAErD,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,CAAC,SAAS,CAAC;AAEzC,MAAM,YAAY,GAAG,IAAI,MAAM,CAAC,iBAAiB,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;AAExF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,GAAY,EAAE,EAAE;IACxC,MAAM,WAAW,GAAG;QAClB,MAAM,CAAC,MAAW,EAAE,QAAsD;YACxE,IAAI,CAAC,MAAM,IAAI,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;gBACzC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YACvB,CAAC;iBAAM,CAAC;gBACN,QAAQ,CAAC,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC,CAAC;YACjD,CAAC;QACH,CAAC;KACF,CAAC;IAEF,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;IAE3B,4FAA4F;IAC5F,mDAAmD;IACnD,GAAG,CAAC,GAAG,CAAC,CAAC,GAAQ,EAAE,IAAa,EAAE,GAAa,EAAE,IAAkB,EAAE,EAAE;QACrE,IAAI,GAAG,IAAI,GAAG,CAAC,OAAO,KAAK,yBAAyB,EAAE,CAAC;YACrD,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;gBAC1B,OAAO,EAAE,KAAK;gBACd,EAAE,EAAE,IAAI;gBACR,KAAK,EAAE;oBACL,IAAI,EAAE,CAAC,KAAK;oBACZ,OAAO,EAAE,mCAAmC;oBAC5C,IAAI,EAAE,EAAE,MAAM,EAAE,oBAAoB,EAAE;iBACvC;aACF,CAAC,CAAC;QACL,CAAC;QACD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;IACnB,CAAC,CAAC,CAAC;IAEH,OAAO,WAAW,CAAC;AACrB,CAAC,CAAC"}

package/dist/core/web/event-store.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Standard §6 (MAY) — in-memory EventStore for Streamable HTTP SSE resumability.
+ *
+ * When a client reconnects to `GET /mcp` carrying a `Last-Event-ID` header, the SDK transport
+ * calls {@link InMemoryEventStore.replayEventsAfter} to re-send the messages the client missed.
+ * This implementation keeps a bounded ring buffer of the most recent events in process memory:
+ * it survives only within a single running server instance and is lost on restart. For
+ * multi-instance deployments a shared/persistent store (Redis etc.) would be required — that
+ * is intentionally out of scope here.
+ */
+import { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+import type { EventStore, EventId, StreamId } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+/**
+ * Ring-buffer EventStore. Event ids are `<streamId>_<paddedSeq>` where `seq` is a process-global
+ * monotonic counter, zero-padded so lexicographic ordering matches insertion order (the SDK
+ * compares ids as strings during replay). Once the buffer exceeds `maxStoredEvents`, the oldest
+ * event is evicted; a `Last-Event-ID` pointing past the retained window yields no replay (the
+ * client simply resumes from the current moment, without error).
+ */
+export declare class InMemoryEventStore implements EventStore {
+    private readonly events;
+    private readonly maxStoredEvents;
+    private seq;
+    constructor(maxStoredEvents?: number);
+    private nextEventId;
+    private static streamIdFromEventId;
+    storeEvent(streamId: StreamId, message: JSONRPCMessage): Promise<EventId>;
+    getStreamIdForEventId(eventId: EventId): Promise<StreamId | undefined>;
+    replayEventsAfter(lastEventId: EventId, { send }: {
+        send: (eventId: EventId, message: JSONRPCMessage) => Promise<void>;
+    }): Promise<StreamId>;
+}
+//# sourceMappingURL=event-store.d.ts.map

package/dist/core/web/event-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-store.d.ts","sourceRoot":"","sources":["../../../src/core/web/event-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,oDAAoD,CAAC;AASxG;;;;;;GAMG;AACH,qBAAa,kBAAmB,YAAW,UAAU;IACnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoC;IAE3D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IAEzC,OAAO,CAAC,GAAG,CAAK;gBAEJ,eAAe,GAAE,MAA2B;IAIxD,OAAO,CAAC,WAAW;IAMnB,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAK5B,UAAU,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IAczE,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IAKtE,iBAAiB,CACrB,WAAW,EAAE,OAAO,EACpB,EAAE,IAAI,EAAE,EAAE;QAAE,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,GAC/E,OAAO,CAAC,QAAQ,CAAC;CAsBrB"}

package/dist/core/web/event-store.js

@@ -0,0 +1,65 @@
+const DEFAULT_MAX_EVENTS = 1000;
+/**
+ * Ring-buffer EventStore. Event ids are `<streamId>_<paddedSeq>` where `seq` is a process-global
+ * monotonic counter, zero-padded so lexicographic ordering matches insertion order (the SDK
+ * compares ids as strings during replay). Once the buffer exceeds `maxStoredEvents`, the oldest
+ * event is evicted; a `Last-Event-ID` pointing past the retained window yields no replay (the
+ * client simply resumes from the current moment, without error).
+ */
+export class InMemoryEventStore {
+    events = new Map();
+    maxStoredEvents;
+    seq = 0;
+    constructor(maxStoredEvents = DEFAULT_MAX_EVENTS) {
+        this.maxStoredEvents = maxStoredEvents > 0 ? maxStoredEvents : DEFAULT_MAX_EVENTS;
+    }
+    nextEventId(streamId) {
+        // 16-digit zero-padded counter keeps ids lexicographically ordered for the lifetime of the process.
+        const padded = String(this.seq++).padStart(16, '0');
+        return `${streamId}_${padded}`;
+    }
+    static streamIdFromEventId(eventId) {
+        const idx = eventId.lastIndexOf('_');
+        return idx === -1 ? '' : eventId.slice(0, idx);
+    }
+    async storeEvent(streamId, message) {
+        const eventId = this.nextEventId(streamId);
+        this.events.set(eventId, { streamId, message });
+        // FIFO eviction via Map insertion order keeps the buffer bounded.
+        while (this.events.size > this.maxStoredEvents) {
+            const oldest = this.events.keys().next().value;
+            if (oldest === undefined) {
+                break;
+            }
+            this.events.delete(oldest);
+        }
+        return eventId;
+    }
+    async getStreamIdForEventId(eventId) {
+        const stored = this.events.get(eventId);
+        return stored?.streamId;
+    }
+    async replayEventsAfter(lastEventId, { send }) {
+        // Unknown id (never stored or already evicted) → no replay; the transport starts a fresh stream.
+        if (!lastEventId || !this.events.has(lastEventId)) {
+            return '';
+        }
+        const streamId = InMemoryEventStore.streamIdFromEventId(lastEventId);
+        if (!streamId) {
+            return '';
+        }
+        let afterLast = false;
+        // Map iteration follows insertion order, which equals seq order — no sort needed.
+        for (const [eventId, stored] of this.events) {
+            if (eventId === lastEventId) {
+                afterLast = true;
+                continue;
+            }
+            if (afterLast && stored.streamId === streamId) {
+                await send(eventId, stored.message);
+            }
+        }
+        return streamId;
+    }
+}
+//# sourceMappingURL=event-store.js.map

package/dist/core/web/event-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-store.js","sourceRoot":"","sources":["../../../src/core/web/event-store.ts"],"names":[],"mappings":"AAkBA,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEhC;;;;;;GAMG;AACH,MAAM,OAAO,kBAAkB;IACZ,MAAM,GAAG,IAAI,GAAG,EAAyB,CAAC;IAE1C,eAAe,CAAS;IAEjC,GAAG,GAAG,CAAC,CAAC;IAEhB,YAAY,kBAA0B,kBAAkB;QACtD,IAAI,CAAC,eAAe,GAAG,eAAe,GAAG,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,kBAAkB,CAAC;IACpF,CAAC;IAEO,WAAW,CAAC,QAAkB;QACpC,oGAAoG;QACpG,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;QACpD,OAAO,GAAG,QAAQ,IAAI,MAAM,EAAE,CAAC;IACjC,CAAC;IAEO,MAAM,CAAC,mBAAmB,CAAC,OAAgB;QACjD,MAAM,GAAG,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QACrC,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACjD,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,QAAkB,EAAE,OAAuB;QAC1D,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;QAC3C,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;QAChD,kEAAkE;QAClE,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC;YAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;YAC/C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,MAAM;YACR,CAAC;YACD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC7B,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,KAAK,CAAC,qBAAqB,CAAC,OAAgB;QAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACxC,OAAO,MAAM,EAAE,QAAQ,CAAC;IAC1B,CAAC;IAED,KAAK,CAAC,iBAAiB,CACrB,WAAoB,EACpB,EAAE,IAAI,EAA0E;QAEhF,iGAAiG;QACjG,IAAI,CAAC,WAAW,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;YAClD,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,MAAM,QAAQ,GAAG,kBAAkB,CAAC,mBAAmB,CAAC,WAAW,CAAC,CAAC;QACrE,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,IAAI,SAAS,GAAG,KAAK,CAAC;QACtB,kFAAkF;QAClF,KAAK,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAC5C,IAAI,OAAO,KAAK,WAAW,EAAE,CAAC;gBAC5B,SAAS,GAAG,IAAI,CAAC;gBACjB,SAAS;YACX,CAAC;YACD,IAAI,SAAS,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;gBAC9C,MAAM,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;YACtC,CAAC;QACH,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF"}

package/dist/core/web/oauth-router.d.ts

@@ -0,0 +1,37 @@
+/**
+ * OAuth / OIDC discovery + token endpoints for fa-mcp-sdk.
+ *
+ * Mounted only when jwtToken.mode !== 'legacyAesCtr'.
+ *
+ * Endpoints:
+ *   GET /.well-known/oauth-protected-resource (always, any non-legacy mode)
+ *   GET /.well-known/openid-configuration     (only mode=embedded)
+ *   GET /.well-known/jwks.json                (only mode=embedded; also mode=localKey)
+ *   POST /oauth/token                          (only when KeyResolver canSign())
+ *
+ * The flow:
+ *   - Resource servers ALWAYS expose /.well-known/oauth-protected-resource so MCP-aware
+ *     clients can discover where to obtain tokens (per the MCP Authorization spec).
+ *   - Embedded mode additionally exposes a full local IdP (jwks + openid-configuration +
+ *     /oauth/token grant_type=password). The token endpoint reuses the configured
+ *     Basic-auth credentials as the password store — no separate user DB.
+ */
+import { Request, Router } from 'express';
+/**
+ * Build the express router with discovery + token endpoints.
+ */
+export declare function createOAuthRouter(): Router;
+/**
+ * Build the `WWW-Authenticate: Bearer ...` header advertised on 401 responses.
+ *
+ * Compliance:
+ *   - Standard §7.4: realm="<service>" is REQUIRED in every challenge.
+ *   - `error="invalid_token"` is added only when the verifier could read the token
+ *     (signature OK, claims invalid/expired) — distinguishes "no creds" vs "bad creds".
+ *   - In non-legacy modes the MCP Authorization spec mandates resource_metadata=...
+ */
+export declare function buildWwwAuthenticateHeader(req: Request, ctx?: {
+    errorReason?: string | undefined;
+    isTokenDecrypted?: boolean | undefined;
+} | string): string;
+//# sourceMappingURL=oauth-router.d.ts.map

package/dist/core/web/oauth-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-router.d.ts","sourceRoot":"","sources":["../../../src/core/web/oauth-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EAAE,OAAO,EAAY,MAAM,EAAE,MAAM,SAAS,CAAC;AA+CpD;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CA4H1C;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,OAAO,EACZ,GAAG,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,gBAAgB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAAE,GAAG,MAAW,GAC9F,MAAM,CAmBR"}

package/dist/core/web/oauth-router.js

@@ -0,0 +1,207 @@
+/**
+ * OAuth / OIDC discovery + token endpoints for fa-mcp-sdk.
+ *
+ * Mounted only when jwtToken.mode !== 'legacyAesCtr'.
+ *
+ * Endpoints:
+ *   GET /.well-known/oauth-protected-resource (always, any non-legacy mode)
+ *   GET /.well-known/openid-configuration     (only mode=embedded)
+ *   GET /.well-known/jwks.json                (only mode=embedded; also mode=localKey)
+ *   POST /oauth/token                          (only when KeyResolver canSign())
+ *
+ * The flow:
+ *   - Resource servers ALWAYS expose /.well-known/oauth-protected-resource so MCP-aware
+ *     clients can discover where to obtain tokens (per the MCP Authorization spec).
+ *   - Embedded mode additionally exposes a full local IdP (jwks + openid-configuration +
+ *     /oauth/token grant_type=password). The token endpoint reuses the configured
+ *     Basic-auth credentials as the password store — no separate user DB.
+ */
+import chalk from 'chalk';
+import { Router } from 'express';
+import { appConfig } from '../bootstrap/init-config.js';
+import { logger as lgr } from '../logger.js';
+import { checkBasicAuth } from '../auth/basic.js';
+import { generateToken } from '../auth/jwt.js';
+import { buildLocalJwks, getJwtRuntimeConfig, getKeyResolver } from '../auth/key-resolver.js';
+const logger = lgr.getSubLogger({ name: chalk.bgYellow('oauth-router') });
+/**
+ * Compose the canonical issuer URL for embedded mode. Resolution order:
+ *   1. expectedIssuer (config) — explicit, wins always
+ *   2. Public webServer.host + port (if usable)
+ *   3. http://localhost:<port>
+ */
+function getEmbeddedIssuer(req) {
+    const { expectedIssuer } = getJwtRuntimeConfig();
+    if (expectedIssuer) {
+        return expectedIssuer;
+    }
+    if (req) {
+        const protocol = req.protocol || 'http';
+        const host = req.get('host');
+        if (host) {
+            return `${protocol}://${host}`;
+        }
+    }
+    const port = appConfig.webServer?.port;
+    return `http://localhost:${port}`;
+}
+/**
+ * Public URL of THIS resource server (used as `resource` in protected-resource metadata).
+ */
+function getResourceUrl(req) {
+    const protocol = req.protocol || 'http';
+    const host = req.get('host');
+    if (host) {
+        return `${protocol}://${host}`;
+    }
+    return `http://localhost:${appConfig.webServer?.port}`;
+}
+const TTL_MULTIPLIERS = { s: 1, m: 60, d: 86400, y: 31536000 };
+/**
+ * Build the express router with discovery + token endpoints.
+ */
+export function createOAuthRouter() {
+    const router = Router();
+    const { mode } = getJwtRuntimeConfig();
+    // ──────────────────────────────────────────────────────────────────────
+    // RFC 9728 — Protected Resource Metadata (any non-legacy mode)
+    // ──────────────────────────────────────────────────────────────────────
+    router.get('/.well-known/oauth-protected-resource', (req, res) => {
+        const resource = getResourceUrl(req);
+        const issuer = getEmbeddedIssuer(req);
+        res.json({
+            resource,
+            authorization_servers: [issuer],
+            bearer_methods_supported: ['header'],
+            scopes_supported: ['mcp:read', 'mcp:write'],
+            resource_documentation: `${resource}/docs`,
+        });
+    });
+    // ──────────────────────────────────────────────────────────────────────
+    // OIDC discovery + JWKS (embedded / localKey when keys are available)
+    // ──────────────────────────────────────────────────────────────────────
+    if (mode === 'embedded' || mode === 'localKey') {
+        router.get('/.well-known/openid-configuration', (req, res) => {
+            const issuer = getEmbeddedIssuer(req);
+            res.json({
+                issuer,
+                jwks_uri: `${issuer}/.well-known/jwks.json`,
+                token_endpoint: `${issuer}/oauth/token`,
+                response_types_supported: ['token'],
+                grant_types_supported: ['password'],
+                token_endpoint_auth_methods_supported: ['client_secret_basic', 'none'],
+                id_token_signing_alg_values_supported: [getJwtRuntimeConfig().algorithm],
+                subject_types_supported: ['public'],
+                scopes_supported: ['mcp:read', 'mcp:write'],
+            });
+        });
+        router.get('/.well-known/jwks.json', async (_req, res) => {
+            try {
+                const jwks = await buildLocalJwks();
+                res.json(jwks);
+            }
+            catch (error) {
+                logger.error('Failed to build JWKS', error);
+                res.status(500).json({ error: 'jwks_unavailable', error_description: error?.message });
+            }
+        });
+    }
+    // ──────────────────────────────────────────────────────────────────────
+    // POST /oauth/token (grant_type=password) — embedded / localKey with privateKey
+    // ──────────────────────────────────────────────────────────────────────
+    router.post('/oauth/token', async (req, res) => {
+        try {
+            const resolver = await getKeyResolver();
+            if (!resolver || !resolver.canSign()) {
+                return res.status(400).json({
+                    error: 'unsupported_grant_type',
+                    error_description: 'This server does not issue tokens. Obtain a token from the configured IdP.',
+                });
+            }
+            const grantType = (req.body?.grant_type ?? req.query?.grant_type ?? '').toString();
+            if (grantType !== 'password') {
+                return res.status(400).json({
+                    error: 'unsupported_grant_type',
+                    error_description: `Only grant_type=password is supported (got "${grantType}")`,
+                });
+            }
+            const username = (req.body?.username ?? '').toString().trim();
+            const password = (req.body?.password ?? '').toString();
+            if (!username || !password) {
+                return res.status(400).json({
+                    error: 'invalid_request',
+                    error_description: 'username and password are required',
+                });
+            }
+            const encoded = Buffer.from(`${username}:${password}`).toString('base64');
+            const auth = checkBasicAuth(encoded);
+            if (!auth.success) {
+                return res.status(401).json({
+                    error: 'invalid_grant',
+                    error_description: auth.error || 'Invalid credentials',
+                });
+            }
+            const scope = (req.body?.scope ?? '').toString().trim() || undefined;
+            const requestedTtl = (req.body?.ttl ?? '').toString().trim();
+            let liveTimeSec = getJwtRuntimeConfig().defaultTtl;
+            if (requestedTtl) {
+                const match = /^(\d+)([smdy])$/.exec(requestedTtl);
+                if (!match) {
+                    return res.status(400).json({
+                        error: 'invalid_request',
+                        error_description: `Invalid ttl "${requestedTtl}". Format: <N>s | <N>m | <N>d | <N>y`,
+                    });
+                }
+                liveTimeSec = parseInt(match[1], 10) * TTL_MULTIPLIERS[match[2]];
+            }
+            const payload = {};
+            if (scope) {
+                payload.scope = scope;
+            }
+            const token = await generateToken(username, liveTimeSec, payload);
+            return res.json({
+                access_token: token,
+                token_type: 'Bearer',
+                expires_in: liveTimeSec,
+                ...(scope ? { scope } : {}),
+            });
+        }
+        catch (error) {
+            logger.error('oauth/token failed', error);
+            return res.status(500).json({
+                error: 'server_error',
+                error_description: error?.message ?? 'unknown error',
+            });
+        }
+    });
+    return router;
+}
+/**
+ * Build the `WWW-Authenticate: Bearer ...` header advertised on 401 responses.
+ *
+ * Compliance:
+ *   - Standard §7.4: realm="<service>" is REQUIRED in every challenge.
+ *   - `error="invalid_token"` is added only when the verifier could read the token
+ *     (signature OK, claims invalid/expired) — distinguishes "no creds" vs "bad creds".
+ *   - In non-legacy modes the MCP Authorization spec mandates resource_metadata=...
+ */
+export function buildWwwAuthenticateHeader(req, ctx = {}) {
+    const opts = typeof ctx === 'string' ? { errorReason: ctx, isTokenDecrypted: true } : ctx;
+    const { mode } = getJwtRuntimeConfig();
+    const realm = appConfig.name || 'mcp';
+    const errParts = [];
+    if (opts.isTokenDecrypted && opts.errorReason) {
+        errParts.push(`error="invalid_token"`);
+        errParts.push(`error_description="${String(opts.errorReason).replace(/"/g, '')}"`);
+    }
+    if (mode === 'legacyAesCtr') {
+        return [`Bearer realm="${realm}"`, ...errParts].join(', ');
+    }
+    const resource = getResourceUrl(req);
+    return [
+        `Bearer realm="${realm}"`,
+        `resource_metadata="${resource}/.well-known/oauth-protected-resource"`,
+        ...errParts,
+    ].join(', ');
+}
+//# sourceMappingURL=oauth-router.js.map

package/dist/core/web/oauth-router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-router.js","sourceRoot":"","sources":["../../../src/core/web/oauth-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAqB,MAAM,EAAE,MAAM,SAAS,CAAC;AAEpD,OAAO,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AACxD,OAAO,EAAE,MAAM,IAAI,GAAG,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAE9F,MAAM,MAAM,GAAG,GAAG,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC;AAE1E;;;;;GAKG;AACH,SAAS,iBAAiB,CAAC,GAAa;IACtC,MAAM,EAAE,cAAc,EAAE,GAAG,mBAAmB,EAAE,CAAC;IACjD,IAAI,cAAc,EAAE,CAAC;QACnB,OAAO,cAAc,CAAC;IACxB,CAAC;IACD,IAAI,GAAG,EAAE,CAAC;QACR,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,IAAI,MAAM,CAAC;QACxC,MAAM,IAAI,GAAG,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC7B,IAAI,IAAI,EAAE,CAAC;YACT,OAAO,GAAG,QAAQ,MAAM,IAAI,EAAE,CAAC;QACjC,CAAC;IACH,CAAC;IACD,MAAM,IAAI,GAAG,SAAS,CAAC,SAAS,EAAE,IAAI,CAAC;IACvC,OAAO,oBAAoB,IAAI,EAAE,CAAC;AACpC,CAAC;AAED;;GAEG;AACH,SAAS,cAAc,CAAC,GAAY;IAClC,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,IAAI,MAAM,CAAC;IACxC,MAAM,IAAI,GAAG,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7B,IAAI,IAAI,EAAE,CAAC;QACT,OAAO,GAAG,QAAQ,MAAM,IAAI,EAAE,CAAC;IACjC,CAAC;IACD,OAAO,oBAAoB,SAAS,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC;AACzD,CAAC;AAED,MAAM,eAAe,GAA2B,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC;AAEvF;;GAEG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC;IACxB,MAAM,EAAE,IAAI,EAAE,GAAG,mBAAmB,EAAE,CAAC;IAEvC,yEAAyE;IACzE,+DAA+D;IAC/D,yEAAyE;IACzE,MAAM,CAAC,GAAG,CAAC,uCAAuC,EAAE,CAAC,GAAY,EAAE,GAAa,EAAE,EAAE;QAClF,MAAM,QAAQ,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;QACrC,MAAM,MAAM,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;QACtC,GAAG,CAAC,IAAI,CAAC;YACP,QAAQ;YACR,qBAAqB,EAAE,CAAC,MAAM,CAAC;YAC/B,wBAAwB,EAAE,CAAC,QAAQ,CAAC;YACpC,gBAAgB,EAAE,CAAC,UAAU,EAAE,WAAW,CAAC;YAC3C,sBAAsB,EAAE,GAAG,QAAQ,OAAO;SAC3C,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,yEAAyE;IACzE,sEAAsE;IACtE,yEAAyE;IACzE,IAAI,IAAI,KAAK,UAAU,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;QAC/C,MAAM,CAAC,GAAG,CAAC,mCAAmC,EAAE,CAAC,GAAY,EAAE,GAAa,EAAE,EAAE;YAC9E,MAAM,MAAM,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;YACtC,GAAG,CAAC,IAAI,CAAC;gBACP,MAAM;gBACN,QAAQ,EAAE,GAAG,MAAM,wBAAwB;gBAC3C,cAAc,EAAE,GAAG,MAAM,cAAc;gBACvC,wBAAwB,EAAE,CAAC,OAAO,CAAC;gBACnC,qBAAqB,EAAE,CAAC,UAAU,CAAC;gBACnC,qCAAqC,EAAE,CAAC,qBAAqB,EAAE,MAAM,CAAC;gBACtE,qCAAqC,EAAE,CAAC,mBAAmB,EAAE,CAAC,SAAS,CAAC;gBACxE,uBAAuB,EAAE,CAAC,QAAQ,CAAC;gBACnC,gBAAgB,EAAE,CAAC,UAAU,EAAE,WAAW,CAAC;aAC5C,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,GAAG,CAAC,wBAAwB,EAAE,KAAK,EAAE,IAAa,EAAE,GAAa,EAAE,EAAE;YAC1E,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,MAAM,cAAc,EAAE,CAAC;gBACpC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACjB,CAAC;YAAC,OAAO,KAAU,EAAE,CAAC;gBACpB,MAAM,CAAC,KAAK,CAAC,sBAAsB,EAAE,KAAK,CAAC,CAAC;gBAC5C,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;YACzF,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED,yEAAyE;IACzE,gFAAgF;IAChF,yEAAyE;IACzE,MAAM,CAAC,IAAI,CAAC,cAAc,EAAE,KAAK,EAAE,GAAY,EAAE,GAAa,EAAE,EAAE;QAChE,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,cAAc,EAAE,CAAC;YACxC,IAAI,CAAC,QAAQ,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC;gBACrC,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;oBAC1B,KAAK,EAAE,wBAAwB;oBAC/B,iBAAiB,EAAE,4EAA4E;iBAChG,CAAC,CAAC;YACL,CAAC;YAED,MAAM,SAAS,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,UAAU,IAAI,GAAG,CAAC,KAAK,EAAE,UAAU,IAAI,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC;YACnF,IAAI,SAAS,KAAK,UAAU,EAAE,CAAC;gBAC7B,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;oBAC1B,KAAK,EAAE,wBAAwB;oBAC/B,iBAAiB,EAAE,+CAA+C,SAAS,IAAI;iBAChF,CAAC,CAAC;YACL,CAAC;YAED,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,IAAI,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC;YAC9D,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,IAAI,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC;YACvD,IAAI,CAAC,QAAQ,IAAI,CAAC,QAAQ,EAAE,CAAC;gBAC3B,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;oBAC1B,KAAK,EAAE,iBAAiB;oBACxB,iBAAiB,EAAE,oCAAoC;iBACxD,CAAC,CAAC;YACL,CAAC;YAED,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,QAAQ,IAAI,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAC1E,MAAM,IAAI,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;YACrC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;gBAClB,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;oBAC1B,KAAK,EAAE,eAAe;oBACtB,iBAAiB,EAAE,IAAI,CAAC,KAAK,IAAI,qBAAqB;iBACvD,CAAC,CAAC;YACL,CAAC;YAED,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,SAAS,CAAC;YACrE,MAAM,YAAY,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC;YAC7D,IAAI,WAAW,GAAW,mBAAmB,EAAE,CAAC,UAAU,CAAC;YAC3D,IAAI,YAAY,EAAE,CAAC;gBACjB,MAAM,KAAK,GAAG,iBAAiB,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;gBACnD,IAAI,CAAC,KAAK,EAAE,CAAC;oBACX,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;wBAC1B,KAAK,EAAE,iBAAiB;wBACxB,iBAAiB,EAAE,gBAAgB,YAAY,sCAAsC;qBACtF,CAAC,CAAC;gBACL,CAAC;gBACD,WAAW,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAE,EAAE,EAAE,CAAC,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC,CAAE,CAAE,CAAC;YACtE,CAAC;YAED,MAAM,OAAO,GAAwB,EAAE,CAAC;YACxC,IAAI,KAAK,EAAE,CAAC;gBACV,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC;YACxB,CAAC;YAED,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,QAAQ,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;YAClE,OAAO,GAAG,CAAC,IAAI,CAAC;gBACd,YAAY,EAAE,KAAK;gBACnB,UAAU,EAAE,QAAQ;gBACpB,UAAU,EAAE,WAAW;gBACvB,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC5B,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YACpB,MAAM,CAAC,KAAK,CAAC,oBAAoB,EAAE,KAAK,CAAC,CAAC;YAC1C,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;gBAC1B,KAAK,EAAE,cAAc;gBACrB,iBAAiB,EAAE,KAAK,EAAE,OAAO,IAAI,eAAe;aACrD,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,0BAA0B,CACxC,GAAY,EACZ,MAA6F,EAAE;IAE/F,MAAM,IAAI,GACR,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,GAAG,EAAE,gBAAgB,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;IAC/E,MAAM,EAAE,IAAI,EAAE,GAAG,mBAAmB,EAAE,CAAC;IACvC,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,IAAI,KAAK,CAAC;IACtC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,IAAI,IAAI,CAAC,gBAAgB,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;QAC9C,QAAQ,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;QACvC,QAAQ,CAAC,IAAI,CAAC,sBAAsB,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC;IACrF,CAAC;IACD,IAAI,IAAI,KAAK,cAAc,EAAE,CAAC;QAC5B,OAAO,CAAC,iBAAiB,KAAK,GAAG,EAAE,GAAG,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7D,CAAC;IACD,MAAM,QAAQ,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;IACrC,OAAO;QACL,iBAAiB,KAAK,GAAG;QACzB,sBAAsB,QAAQ,wCAAwC;QACtE,GAAG,QAAQ;KACZ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/core/web/request-id.d.ts

@@ -0,0 +1,44 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { RequestHandler } from 'express';
+/**
+ * Standard §15.1 — sticky correlation id for every request, plus optional W3C
+ * trace context. The middleware stores them in {@link AsyncLocalStorage} so the
+ * rest of the call chain (logger, JSON-RPC error serializer, debug-trace) can
+ * pick them up without explicit plumbing.
+ */
+export interface ITraceContext {
+    /** 32 hex chars (W3C trace-id). */
+    traceId: string;
+    /** 16 hex chars (W3C parent-id / span-id of the incoming span). */
+    parentId: string;
+    /** 2 hex chars (W3C trace flags). */
+    flags: string;
+}
+export interface IRequestContext {
+    /** Sticky id propagated end-to-end (HTTP `X-Request-Id` or stdio-generated). */
+    requestId: string;
+    /** Echoed verbatim to downstream services in `tracestate` (W3C). */
+    tracestate?: string;
+    /** Populated only when a valid W3C `traceparent` header was supplied. */
+    traceContext?: ITraceContext;
+    /** JSON-RPC id of the incoming message (stdio path) — never the same as `requestId`. */
+    jsonRpcId?: string | number | null;
+}
+declare const requestIdStorage: AsyncLocalStorage<IRequestContext>;
+/**
+ * Express middleware that materialises {@link IRequestContext} for the lifetime
+ * of a request. Always sets the `X-Request-Id` response header (BEHAVIOUR
+ * change introduced in 0.8.0) and echoes a valid `tracestate` back unchanged.
+ */
+export declare function requestIdMW(): RequestHandler;
+/**
+ * Run a callback with an explicit request context. Used by the stdio bootstrap
+ * to wrap every incoming JSON-RPC message.
+ */
+export declare function runWithRequestContext<T>(ctx: IRequestContext, fn: () => T): T;
+export declare function getCurrentRequestContext(): IRequestContext | undefined;
+export declare function getCurrentRequestId(): string | undefined;
+export declare function getCurrentJsonRpcId(): string | number | null | undefined;
+export declare function getCurrentTraceContext(): ITraceContext | undefined;
+export { requestIdStorage };
+//# sourceMappingURL=request-id.d.ts.map

package/dist/core/web/request-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-id.d.ts","sourceRoot":"","sources":["../../../src/core/web/request-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGrD,OAAO,EAAyB,cAAc,EAAY,MAAM,SAAS,CAAC;AAE1E;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,gFAAgF;IAChF,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B,wFAAwF;IACxF,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CACpC;AAED,QAAA,MAAM,gBAAgB,oCAA2C,CAAC;AAwClE;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,cAAc,CAqB5C;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,GAAG,EAAE,eAAe,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAE7E;AAED,wBAAgB,wBAAwB,IAAI,eAAe,GAAG,SAAS,CAEtE;AAED,wBAAgB,mBAAmB,IAAI,MAAM,GAAG,SAAS,CAExD;AAED,wBAAgB,mBAAmB,IAAI,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAExE;AAED,wBAAgB,sBAAsB,IAAI,aAAa,GAAG,SAAS,CAElE;AAED,OAAO,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/core/web/request-id.js

@@ -0,0 +1,82 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+const requestIdStorage = new AsyncLocalStorage();
+const REQUEST_ID_REGEX = /^[A-Za-z0-9._-]{8,128}$/;
+const TRACEPARENT_REGEX = /^00-([a-f0-9]{32})-([a-f0-9]{16})-([a-f0-9]{2})$/;
+const TRACESTATE_MAX_LEN = 4096;
+function sanitizeRequestId(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return REQUEST_ID_REGEX.test(trimmed) ? trimmed : undefined;
+}
+function parseTraceparent(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const match = TRACEPARENT_REGEX.exec(value.trim().toLowerCase());
+    if (!match) {
+        return undefined;
+    }
+    const [, traceId, parentId, flags] = match;
+    if (!traceId || !parentId || !flags || /^0+$/.test(traceId) || /^0+$/.test(parentId)) {
+        return undefined;
+    }
+    return { traceId, parentId, flags };
+}
+function sanitizeTracestate(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    if (!trimmed || trimmed.length > TRACESTATE_MAX_LEN) {
+        return undefined;
+    }
+    return trimmed;
+}
+/**
+ * Express middleware that materialises {@link IRequestContext} for the lifetime
+ * of a request. Always sets the `X-Request-Id` response header (BEHAVIOUR
+ * change introduced in 0.8.0) and echoes a valid `tracestate` back unchanged.
+ */
+export function requestIdMW() {
+    return (req, res, next) => {
+        const requestId = sanitizeRequestId(req.headers['x-request-id']) ?? randomUUID();
+        const traceContext = parseTraceparent(req.headers['traceparent']);
+        const tracestate = sanitizeTracestate(req.headers['tracestate']);
+        const ctx = { requestId };
+        if (traceContext) {
+            ctx.traceContext = traceContext;
+        }
+        if (tracestate) {
+            ctx.tracestate = tracestate;
+        }
+        res.setHeader('X-Request-Id', requestId);
+        if (tracestate) {
+            res.setHeader('tracestate', tracestate);
+        }
+        requestIdStorage.run(ctx, () => next());
+    };
+}
+/**
+ * Run a callback with an explicit request context. Used by the stdio bootstrap
+ * to wrap every incoming JSON-RPC message.
+ */
+export function runWithRequestContext(ctx, fn) {
+    return requestIdStorage.run(ctx, fn);
+}
+export function getCurrentRequestContext() {
+    return requestIdStorage.getStore();
+}
+export function getCurrentRequestId() {
+    return requestIdStorage.getStore()?.requestId;
+}
+export function getCurrentJsonRpcId() {
+    return requestIdStorage.getStore()?.jsonRpcId;
+}
+export function getCurrentTraceContext() {
+    return requestIdStorage.getStore()?.traceContext;
+}
+export { requestIdStorage };
+//# sourceMappingURL=request-id.js.map

package/dist/core/web/request-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-id.js","sourceRoot":"","sources":["../../../src/core/web/request-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA8BzC,MAAM,gBAAgB,GAAG,IAAI,iBAAiB,EAAmB,CAAC;AAElE,MAAM,gBAAgB,GAAG,yBAAyB,CAAC;AACnD,MAAM,iBAAiB,GAAG,kDAAkD,CAAC;AAC7E,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEhC,SAAS,iBAAiB,CAAC,KAAc;IACvC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,OAAO,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AAC9D,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAc;IACtC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,KAAK,GAAG,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;IACjE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,GAAG,KAAK,CAAC;IAC3C,IAAI,CAAC,OAAO,IAAI,CAAC,QAAQ,IAAI,CAAC,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QACrF,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AACtC,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAc;IACxC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,kBAAkB,EAAE,CAAC;QACpD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB,EAAE,EAAE;QACzD,MAAM,SAAS,GAAG,iBAAiB,CAAC,GAAG,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,IAAI,UAAU,EAAE,CAAC;QACjF,MAAM,YAAY,GAAG,gBAAgB,CAAC,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC;QAClE,MAAM,UAAU,GAAG,kBAAkB,CAAC,GAAG,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC;QAEjE,MAAM,GAAG,GAAoB,EAAE,SAAS,EAAE,CAAC;QAC3C,IAAI,YAAY,EAAE,CAAC;YACjB,GAAG,CAAC,YAAY,GAAG,YAAY,CAAC;QAClC,CAAC;QACD,IAAI,UAAU,EAAE,CAAC;YACf,GAAG,CAAC,UAAU,GAAG,UAAU,CAAC;QAC9B,CAAC;QAED,GAAG,CAAC,SAAS,CAAC,cAAc,EAAE,SAAS,CAAC,CAAC;QACzC,IAAI,UAAU,EAAE,CAAC;YACf,GAAG,CAAC,SAAS,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;QAC1C,CAAC;QAED,gBAAgB,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1C,CAAC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAI,GAAoB,EAAE,EAAW;IACxE,OAAO,gBAAgB,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,wBAAwB;IACtC,OAAO,gBAAgB,CAAC,QAAQ,EAAE,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,OAAO,gBAAgB,CAAC,QAAQ,EAAE,EAAE,SAAS,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,OAAO,gBAAgB,CAAC,QAAQ,EAAE,EAAE,SAAS,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,sBAAsB;IACpC,OAAO,gBAAgB,CAAC,QAAQ,EAAE,EAAE,YAAY,CAAC;AACnD,CAAC;AAED,OAAO,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/core/web/server-http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-http.d.ts","sourceRoot":"","sources":["../../../src/core/web/server-http.ts"],"names":[],"mappings":"AAkDA,eAAO,MAAM,cAAc,SAAyC,CAAC;AAsCrE;;GAEG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CA2oBrD"}
+{"version":3,"file":"server-http.d.ts","sourceRoot":"","sources":["../../../src/core/web/server-http.ts"],"names":[],"mappings":"AA+DA,eAAO,MAAM,cAAc,SAAyC,CAAC;AA6DrE;;GAEG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CA4wBrD"}