@frontmcp/sdk 0.5.0 → 0.6.0

package/src/context/request-context-storage.d.ts

@@ -0,0 +1,89 @@
+/**
+ * RequestContextStorage - AsyncLocalStorage wrapper for request-scoped context
+ *
+ * Provides concurrent-safe request context propagation using Node.js AsyncLocalStorage.
+ * Access through DI only - never use static imports to access the storage directly.
+ *
+ * @example
+ * ```typescript
+ * // In a flow or middleware
+ * const storage = this.get(RequestContextStorage);
+ * await storage.runFromHeaders(request.headers, {
+ *   sessionId: sessionId,
+ *   authInfo: authInfo,
+ *   scopeId: scope.id,
+ * }, async () => {
+ *   // All code here can access the context via DI
+ *   const ctx = this.get(REQUEST_CONTEXT);
+ * });
+ * ```
+ */
+import { RequestContext, RequestContextArgs } from './request-context';
+/**
+ * RequestContextStorage provides request-scoped context via AsyncLocalStorage.
+ *
+ * This is a GLOBAL-scoped provider because it manages the storage itself,
+ * not the per-request data. The actual RequestContext is accessed via
+ * the REQUEST_CONTEXT token which is REQUEST-scoped.
+ */
+export declare class RequestContextStorage {
+    /**
+     * Run a callback with a new RequestContext.
+     *
+     * @param args - Arguments to create the context
+     * @param fn - Async function to run with the context
+     * @returns Result of the callback
+     */
+    run<T>(args: RequestContextArgs, fn: () => T | Promise<T>): T | Promise<T>;
+    /**
+     * Run with context extracted from HTTP headers.
+     *
+     * Automatically parses trace context from headers using W3C Trace Context
+     * specification with fallback to x-frontmcp-trace-id.
+     *
+     * @param headers - HTTP headers
+     * @param args - Additional context args (sessionId, authInfo, scopeId)
+     * @param fn - Async function to run
+     * @returns Result of the callback
+     */
+    runFromHeaders<T>(headers: Record<string, unknown>, args: Omit<RequestContextArgs, 'traceContext' | 'metadata'>, fn: () => T | Promise<T>): T | Promise<T>;
+    /**
+     * Run with an existing RequestContext.
+     *
+     * Useful when you need to propagate an existing context to a new async scope.
+     *
+     * @param context - Existing RequestContext
+     * @param fn - Async function to run
+     * @returns Result of the callback
+     */
+    runWithContext<T>(context: RequestContext, fn: () => T | Promise<T>): T | Promise<T>;
+    /**
+     * Get the current RequestContext.
+     *
+     * @returns Current context or undefined if not in a request scope
+     */
+    getStore(): RequestContext | undefined;
+    /**
+     * Get the current RequestContext, throwing if not available.
+     *
+     * @throws Error if not in a request scope
+     */
+    getStoreOrThrow(): RequestContext;
+    /**
+     * Check if currently running within a request context.
+     *
+     * @returns True if a RequestContext is available
+     */
+    hasContext(): boolean;
+    /**
+     * Update the authInfo in the current context.
+     *
+     * This mutates the existing context in place to preserve internal state
+     * (marks, store, sessionMetadata) while updating auth info.
+     *
+     * @param authInfo - Auth info fields to set/update (merged with existing)
+     * @param fn - Function to run after update
+     * @returns Result of the callback
+     */
+    updateAuthInfo<T>(authInfo: RequestContextArgs['authInfo'], fn: () => T | Promise<T>): T | Promise<T>;
+}

package/src/context/request-context-storage.js

@@ -0,0 +1,183 @@
+"use strict";
+/**
+ * RequestContextStorage - AsyncLocalStorage wrapper for request-scoped context
+ *
+ * Provides concurrent-safe request context propagation using Node.js AsyncLocalStorage.
+ * Access through DI only - never use static imports to access the storage directly.
+ *
+ * @example
+ * ```typescript
+ * // In a flow or middleware
+ * const storage = this.get(RequestContextStorage);
+ * await storage.runFromHeaders(request.headers, {
+ *   sessionId: sessionId,
+ *   authInfo: authInfo,
+ *   scopeId: scope.id,
+ * }, async () => {
+ *   // All code here can access the context via DI
+ *   const ctx = this.get(REQUEST_CONTEXT);
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequestContextStorage = void 0;
+const tslib_1 = require("tslib");
+const node_async_hooks_1 = require("node:async_hooks");
+const decorators_1 = require("../common/decorators");
+const metadata_1 = require("../common/metadata");
+const request_context_1 = require("./request-context");
+const trace_context_1 = require("./trace-context");
+/**
+ * Module-level AsyncLocalStorage instance.
+ *
+ * This is the ONLY place where the storage is created.
+ * Access should be through DI, not through static imports.
+ */
+const requestContextStorage = new node_async_hooks_1.AsyncLocalStorage();
+/**
+ * RequestContextStorage provides request-scoped context via AsyncLocalStorage.
+ *
+ * This is a GLOBAL-scoped provider because it manages the storage itself,
+ * not the per-request data. The actual RequestContext is accessed via
+ * the REQUEST_CONTEXT token which is REQUEST-scoped.
+ */
+let RequestContextStorage = class RequestContextStorage {
+    /**
+     * Run a callback with a new RequestContext.
+     *
+     * @param args - Arguments to create the context
+     * @param fn - Async function to run with the context
+     * @returns Result of the callback
+     */
+    run(args, fn) {
+        const context = new request_context_1.RequestContext(args);
+        return requestContextStorage.run(context, fn);
+    }
+    /**
+     * Run with context extracted from HTTP headers.
+     *
+     * Automatically parses trace context from headers using W3C Trace Context
+     * specification with fallback to x-frontmcp-trace-id.
+     *
+     * @param headers - HTTP headers
+     * @param args - Additional context args (sessionId, authInfo, scopeId)
+     * @param fn - Async function to run
+     * @returns Result of the callback
+     */
+    runFromHeaders(headers, args, fn) {
+        const traceContext = (0, trace_context_1.parseTraceContext)(headers);
+        const metadata = extractMetadata(headers);
+        const context = new request_context_1.RequestContext({
+            ...args,
+            traceContext,
+            metadata,
+        });
+        return requestContextStorage.run(context, fn);
+    }
+    /**
+     * Run with an existing RequestContext.
+     *
+     * Useful when you need to propagate an existing context to a new async scope.
+     *
+     * @param context - Existing RequestContext
+     * @param fn - Async function to run
+     * @returns Result of the callback
+     */
+    runWithContext(context, fn) {
+        return requestContextStorage.run(context, fn);
+    }
+    /**
+     * Get the current RequestContext.
+     *
+     * @returns Current context or undefined if not in a request scope
+     */
+    getStore() {
+        return requestContextStorage.getStore();
+    }
+    /**
+     * Get the current RequestContext, throwing if not available.
+     *
+     * @throws Error if not in a request scope
+     */
+    getStoreOrThrow() {
+        const ctx = this.getStore();
+        if (!ctx) {
+            throw new Error('RequestContext not available. Ensure operation runs within request scope.');
+        }
+        return ctx;
+    }
+    /**
+     * Check if currently running within a request context.
+     *
+     * @returns True if a RequestContext is available
+     */
+    hasContext() {
+        return requestContextStorage.getStore() !== undefined;
+    }
+    /**
+     * Update the authInfo in the current context.
+     *
+     * This mutates the existing context in place to preserve internal state
+     * (marks, store, sessionMetadata) while updating auth info.
+     *
+     * @param authInfo - Auth info fields to set/update (merged with existing)
+     * @param fn - Function to run after update
+     * @returns Result of the callback
+     */
+    updateAuthInfo(authInfo, fn) {
+        const current = this.getStoreOrThrow();
+        // Mutate in place to preserve marks, store, and sessionMetadata
+        current.updateAuthInfo(authInfo);
+        return fn();
+    }
+};
+exports.RequestContextStorage = RequestContextStorage;
+exports.RequestContextStorage = RequestContextStorage = tslib_1.__decorate([
+    (0, decorators_1.Provider)({
+        name: 'RequestContextStorage',
+        description: 'Manages request-scoped context via AsyncLocalStorage',
+        scope: metadata_1.ProviderScope.GLOBAL,
+    })
+], RequestContextStorage);
+/**
+ * Extract request metadata from headers.
+ */
+function extractMetadata(headers) {
+    const customHeaders = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase().startsWith('x-frontmcp-') && typeof value === 'string') {
+            customHeaders[key.toLowerCase()] = value;
+        }
+    }
+    return {
+        userAgent: typeof headers['user-agent'] === 'string' ? headers['user-agent'] : undefined,
+        contentType: typeof headers['content-type'] === 'string' ? headers['content-type'] : undefined,
+        accept: typeof headers['accept'] === 'string' ? headers['accept'] : undefined,
+        clientIp: extractClientIp(headers),
+        customHeaders,
+    };
+}
+/**
+ * Extract client IP from headers.
+ * Handles both string and array header values (some adapters pass arrays).
+ */
+function extractClientIp(headers) {
+    // x-forwarded-for can be comma-separated list; first is client IP
+    const xff = headers['x-forwarded-for'];
+    if (typeof xff === 'string') {
+        return xff.split(',')[0]?.trim();
+    }
+    // Some adapters pass arrays for multi-value headers
+    if (Array.isArray(xff) && typeof xff[0] === 'string') {
+        return xff[0].split(',')[0]?.trim();
+    }
+    const realIp = headers['x-real-ip'];
+    if (typeof realIp === 'string') {
+        return realIp;
+    }
+    if (Array.isArray(realIp) && typeof realIp[0] === 'string') {
+        return realIp[0];
+    }
+    return undefined;
+}
+//# sourceMappingURL=request-context-storage.js.map

package/src/context/request-context-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-context-storage.js","sourceRoot":"","sources":["../../../src/context/request-context-storage.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * RequestContextStorage - AsyncLocalStorage wrapper for request-scoped context\n *\n * Provides concurrent-safe request context propagation using Node.js AsyncLocalStorage.\n * Access through DI only - never use static imports to access the storage directly.\n *\n * @example\n * ```typescript\n * // In a flow or middleware\n * const storage = this.get(RequestContextStorage);\n * await storage.runFromHeaders(request.headers, {\n *   sessionId: sessionId,\n *   authInfo: authInfo,\n *   scopeId: scope.id,\n * }, async () => {\n *   // All code here can access the context via DI\n *   const ctx = this.get(REQUEST_CONTEXT);\n * });\n * ```\n */\n\nimport { AsyncLocalStorage } from 'node:async_hooks';\nimport { Provider } from '../common/decorators';\nimport { ProviderScope } from '../common/metadata';\nimport { RequestContext, RequestContextArgs, RequestMetadata } from './request-context';\nimport { parseTraceContext } from './trace-context';\n\n/**\n * Module-level AsyncLocalStorage instance.\n *\n * This is the ONLY place where the storage is created.\n * Access should be through DI, not through static imports.\n */\nconst requestContextStorage = new AsyncLocalStorage<RequestContext>();\n\n/**\n * RequestContextStorage provides request-scoped context via AsyncLocalStorage.\n *\n * This is a GLOBAL-scoped provider because it manages the storage itself,\n * not the per-request data. The actual RequestContext is accessed via\n * the REQUEST_CONTEXT token which is REQUEST-scoped.\n */\n@Provider({\n  name: 'RequestContextStorage',\n  description: 'Manages request-scoped context via AsyncLocalStorage',\n  scope: ProviderScope.GLOBAL,\n})\nexport class RequestContextStorage {\n  /**\n   * Run a callback with a new RequestContext.\n   *\n   * @param args - Arguments to create the context\n   * @param fn - Async function to run with the context\n   * @returns Result of the callback\n   */\n  run<T>(args: RequestContextArgs, fn: () => T | Promise<T>): T | Promise<T> {\n    const context = new RequestContext(args);\n    return requestContextStorage.run(context, fn);\n  }\n\n  /**\n   * Run with context extracted from HTTP headers.\n   *\n   * Automatically parses trace context from headers using W3C Trace Context\n   * specification with fallback to x-frontmcp-trace-id.\n   *\n   * @param headers - HTTP headers\n   * @param args - Additional context args (sessionId, authInfo, scopeId)\n   * @param fn - Async function to run\n   * @returns Result of the callback\n   */\n  runFromHeaders<T>(\n    headers: Record<string, unknown>,\n    args: Omit<RequestContextArgs, 'traceContext' | 'metadata'>,\n    fn: () => T | Promise<T>,\n  ): T | Promise<T> {\n    const traceContext = parseTraceContext(headers);\n    const metadata = extractMetadata(headers);\n    const context = new RequestContext({\n      ...args,\n      traceContext,\n      metadata,\n    });\n    return requestContextStorage.run(context, fn);\n  }\n\n  /**\n   * Run with an existing RequestContext.\n   *\n   * Useful when you need to propagate an existing context to a new async scope.\n   *\n   * @param context - Existing RequestContext\n   * @param fn - Async function to run\n   * @returns Result of the callback\n   */\n  runWithContext<T>(context: RequestContext, fn: () => T | Promise<T>): T | Promise<T> {\n    return requestContextStorage.run(context, fn);\n  }\n\n  /**\n   * Get the current RequestContext.\n   *\n   * @returns Current context or undefined if not in a request scope\n   */\n  getStore(): RequestContext | undefined {\n    return requestContextStorage.getStore();\n  }\n\n  /**\n   * Get the current RequestContext, throwing if not available.\n   *\n   * @throws Error if not in a request scope\n   */\n  getStoreOrThrow(): RequestContext {\n    const ctx = this.getStore();\n    if (!ctx) {\n      throw new Error('RequestContext not available. Ensure operation runs within request scope.');\n    }\n    return ctx;\n  }\n\n  /**\n   * Check if currently running within a request context.\n   *\n   * @returns True if a RequestContext is available\n   */\n  hasContext(): boolean {\n    return requestContextStorage.getStore() !== undefined;\n  }\n\n  /**\n   * Update the authInfo in the current context.\n   *\n   * This mutates the existing context in place to preserve internal state\n   * (marks, store, sessionMetadata) while updating auth info.\n   *\n   * @param authInfo - Auth info fields to set/update (merged with existing)\n   * @param fn - Function to run after update\n   * @returns Result of the callback\n   */\n  updateAuthInfo<T>(authInfo: RequestContextArgs['authInfo'], fn: () => T | Promise<T>): T | Promise<T> {\n    const current = this.getStoreOrThrow();\n    // Mutate in place to preserve marks, store, and sessionMetadata\n    current.updateAuthInfo(authInfo);\n    return fn();\n  }\n}\n\n/**\n * Extract request metadata from headers.\n */\nfunction extractMetadata(headers: Record<string, unknown>): RequestMetadata {\n  const customHeaders: Record<string, string> = {};\n\n  for (const [key, value] of Object.entries(headers)) {\n    if (key.toLowerCase().startsWith('x-frontmcp-') && typeof value === 'string') {\n      customHeaders[key.toLowerCase()] = value;\n    }\n  }\n\n  return {\n    userAgent: typeof headers['user-agent'] === 'string' ? headers['user-agent'] : undefined,\n    contentType: typeof headers['content-type'] === 'string' ? headers['content-type'] : undefined,\n    accept: typeof headers['accept'] === 'string' ? headers['accept'] : undefined,\n    clientIp: extractClientIp(headers),\n    customHeaders,\n  };\n}\n\n/**\n * Extract client IP from headers.\n * Handles both string and array header values (some adapters pass arrays).\n */\nfunction extractClientIp(headers: Record<string, unknown>): string | undefined {\n  // x-forwarded-for can be comma-separated list; first is client IP\n  const xff = headers['x-forwarded-for'];\n  if (typeof xff === 'string') {\n    return xff.split(',')[0]?.trim();\n  }\n  // Some adapters pass arrays for multi-value headers\n  if (Array.isArray(xff) && typeof xff[0] === 'string') {\n    return xff[0].split(',')[0]?.trim();\n  }\n\n  const realIp = headers['x-real-ip'];\n  if (typeof realIp === 'string') {\n    return realIp;\n  }\n  if (Array.isArray(realIp) && typeof realIp[0] === 'string') {\n    return realIp[0];\n  }\n\n  return undefined;\n}\n"]}

package/src/context/request-context.d.ts

@@ -0,0 +1,184 @@
+/**
+ * RequestContext - Production-ready request context for FrontMCP
+ *
+ * Provides request-scoped state that flows through the entire async execution
+ * chain via AsyncLocalStorage. Access via DI only using the REQUEST_CONTEXT token.
+ */
+import { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
+import { FrontMcpLogger } from '../common/interfaces/logger.interface';
+import { TraceContext } from './trace-context';
+import type { SessionIdPayload } from '../common/types';
+/**
+ * Request metadata extracted from HTTP headers.
+ */
+export interface RequestMetadata {
+    /** User-Agent header */
+    userAgent?: string;
+    /** Content-Type header */
+    contentType?: string;
+    /** Accept header */
+    accept?: string;
+    /** Client IP address (from x-forwarded-for or socket) */
+    clientIp?: string;
+    /** Custom headers matching x-frontmcp-* pattern */
+    customHeaders: Record<string, string>;
+}
+/**
+ * Arguments for creating a RequestContext.
+ */
+export interface RequestContextArgs {
+    /** Optional request ID (generated if not provided) */
+    requestId?: string;
+    /** Optional trace context (generated if not provided) */
+    traceContext?: TraceContext;
+    /** Session identifier (required) */
+    sessionId: string;
+    /** Authentication information (can be partial, progressively populated) */
+    authInfo: Partial<AuthInfo>;
+    /** Scope identifier (required) */
+    scopeId: string;
+    /** Optional timestamp (defaults to Date.now()) */
+    timestamp?: number;
+    /** Optional request metadata */
+    metadata?: RequestMetadata;
+}
+/**
+ * RequestContext provides per-request state that flows through
+ * the entire async execution chain via AsyncLocalStorage.
+ *
+ * Access via DI only using the REQUEST_CONTEXT token:
+ * ```typescript
+ * const ctx = this.get(REQUEST_CONTEXT);
+ * console.log(ctx.requestId, ctx.traceContext.traceId);
+ * ```
+ */
+export declare class RequestContext {
+    /** Unique request identifier (UUID v4) */
+    readonly requestId: string;
+    /** W3C Trace Context or generated trace ID */
+    readonly traceContext: TraceContext;
+    /** Session identifier (from mcp-session-id header or authorization) */
+    readonly sessionId: string;
+    /**
+     * Authentication information.
+     * Note: This is mutable to allow updating after authorization is verified.
+     * It's Partial<AuthInfo> because auth info is progressively populated
+     * throughout the request lifecycle (some fields like transport are only
+     * available after the transport is established).
+     */
+    private _authInfo;
+    /** Scope identifier */
+    readonly scopeId: string;
+    /** Request start timestamp */
+    readonly timestamp: number;
+    /** Request metadata (headers, user-agent, etc.) */
+    readonly metadata: RequestMetadata;
+    /** Timing marks for performance tracking */
+    private readonly marks;
+    /** Request-scoped data store */
+    private readonly store;
+    constructor(args: RequestContextArgs);
+    /**
+     * Get authentication information.
+     * Returns Partial<AuthInfo> because auth info is progressively populated.
+     */
+    get authInfo(): Partial<AuthInfo>;
+    /**
+     * Update auth info after authorization is verified.
+     * Called by checkAuthorization stage after session verification.
+     * Can be called multiple times to progressively add fields.
+     *
+     * @param authInfo - The auth info fields to set/update
+     * @internal
+     */
+    updateAuthInfo(authInfo: Partial<AuthInfo>): void;
+    /**
+     * Session metadata including protocol, platform type, and node info.
+     * Only available after session verification in authenticated flows.
+     */
+    private _sessionMetadata?;
+    /**
+     * Get session metadata.
+     *
+     * Contains protocol type, platform type, nodeId, and authSignature.
+     * Only available after session verification completes.
+     *
+     * @returns Session metadata or undefined if not yet verified
+     */
+    get sessionMetadata(): SessionIdPayload | undefined;
+    /**
+     * Update session metadata after session verification.
+     * Called by checkAuthorization stage after session verification.
+     *
+     * @param metadata - Session metadata from verified session
+     * @internal
+     */
+    updateSessionMetadata(metadata: SessionIdPayload): void;
+    /**
+     * Get a child logger with request context attached.
+     *
+     * Creates a child logger with a prefix containing the request ID and trace ID
+     * for easy request tracing in logs.
+     *
+     * @param parentLogger - The parent logger to create a child from
+     * @returns A logger with requestId and traceId in the prefix
+     */
+    getLogger(parentLogger: FrontMcpLogger): FrontMcpLogger;
+    /**
+     * Mark a timing point for performance tracking.
+     *
+     * @param name - Name of the timing mark
+     */
+    mark(name: string): void;
+    /**
+     * Get elapsed time in milliseconds between two marks.
+     *
+     * @param from - Start mark name (defaults to 'init')
+     * @param to - End mark name (defaults to current time)
+     * @returns Elapsed time in milliseconds
+     */
+    elapsed(from?: string, to?: string): number;
+    /**
+     * Get all timing marks.
+     *
+     * @returns Read-only map of mark names to timestamps
+     */
+    getMarks(): ReadonlyMap<string, number>;
+    /**
+     * Store request-scoped data.
+     *
+     * @param key - Storage key
+     * @param value - Value to store
+     */
+    set<T>(key: string | symbol, value: T): void;
+    /**
+     * Retrieve request-scoped data.
+     *
+     * @param key - Storage key
+     * @returns Stored value or undefined
+     */
+    get<T>(key: string | symbol): T | undefined;
+    /**
+     * Check if a key exists in the request-scoped store.
+     *
+     * @param key - Storage key
+     * @returns True if key exists
+     */
+    has(key: string | symbol): boolean;
+    /**
+     * Delete a key from the request-scoped store.
+     *
+     * @param key - Storage key
+     * @returns True if key was deleted
+     */
+    delete(key: string | symbol): boolean;
+    /**
+     * Get a summary of the context for logging.
+     *
+     * Note: sessionId is hashed to prevent accidental exposure of user-identifying
+     * session identifiers in logs while still allowing correlation.
+     *
+     * @returns Object with key context fields
+     */
+    toLogContext(): Record<string, unknown>;
+}

package/src/context/request-context.js

@@ -0,0 +1,209 @@
+"use strict";
+/**
+ * RequestContext - Production-ready request context for FrontMCP
+ *
+ * Provides request-scoped state that flows through the entire async execution
+ * chain via AsyncLocalStorage. Access via DI only using the REQUEST_CONTEXT token.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequestContext = void 0;
+const node_crypto_1 = require("node:crypto");
+const trace_context_1 = require("./trace-context");
+/**
+ * RequestContext provides per-request state that flows through
+ * the entire async execution chain via AsyncLocalStorage.
+ *
+ * Access via DI only using the REQUEST_CONTEXT token:
+ * ```typescript
+ * const ctx = this.get(REQUEST_CONTEXT);
+ * console.log(ctx.requestId, ctx.traceContext.traceId);
+ * ```
+ */
+class RequestContext {
+    /** Unique request identifier (UUID v4) */
+    requestId;
+    /** W3C Trace Context or generated trace ID */
+    traceContext;
+    /** Session identifier (from mcp-session-id header or authorization) */
+    sessionId;
+    /**
+     * Authentication information.
+     * Note: This is mutable to allow updating after authorization is verified.
+     * It's Partial<AuthInfo> because auth info is progressively populated
+     * throughout the request lifecycle (some fields like transport are only
+     * available after the transport is established).
+     */
+    _authInfo;
+    /** Scope identifier */
+    scopeId;
+    /** Request start timestamp */
+    timestamp;
+    /** Request metadata (headers, user-agent, etc.) */
+    metadata;
+    /** Timing marks for performance tracking */
+    marks = new Map();
+    /** Request-scoped data store */
+    store = new Map();
+    constructor(args) {
+        this.requestId = args.requestId ?? (0, node_crypto_1.randomUUID)();
+        this.traceContext = args.traceContext ?? (0, trace_context_1.generateTraceContext)();
+        this.sessionId = args.sessionId;
+        this._authInfo = args.authInfo;
+        this.scopeId = args.scopeId;
+        this.timestamp = args.timestamp ?? Date.now();
+        // Defensive normalization: ensure customHeaders is always an object
+        // even if args.metadata is partially defined at runtime (TS can't enforce this)
+        const metadata = args.metadata;
+        this.metadata = {
+            ...metadata,
+            customHeaders: metadata?.customHeaders ?? {},
+        };
+        // Initial mark
+        this.marks.set('init', this.timestamp);
+    }
+    /**
+     * Get authentication information.
+     * Returns Partial<AuthInfo> because auth info is progressively populated.
+     */
+    get authInfo() {
+        return this._authInfo;
+    }
+    /**
+     * Update auth info after authorization is verified.
+     * Called by checkAuthorization stage after session verification.
+     * Can be called multiple times to progressively add fields.
+     *
+     * @param authInfo - The auth info fields to set/update
+     * @internal
+     */
+    updateAuthInfo(authInfo) {
+        // Merge with existing auth info to support progressive updates
+        this._authInfo = { ...this._authInfo, ...authInfo };
+    }
+    /**
+     * Session metadata including protocol, platform type, and node info.
+     * Only available after session verification in authenticated flows.
+     */
+    _sessionMetadata;
+    /**
+     * Get session metadata.
+     *
+     * Contains protocol type, platform type, nodeId, and authSignature.
+     * Only available after session verification completes.
+     *
+     * @returns Session metadata or undefined if not yet verified
+     */
+    get sessionMetadata() {
+        return this._sessionMetadata;
+    }
+    /**
+     * Update session metadata after session verification.
+     * Called by checkAuthorization stage after session verification.
+     *
+     * @param metadata - Session metadata from verified session
+     * @internal
+     */
+    updateSessionMetadata(metadata) {
+        this._sessionMetadata = metadata;
+    }
+    /**
+     * Get a child logger with request context attached.
+     *
+     * Creates a child logger with a prefix containing the request ID and trace ID
+     * for easy request tracing in logs.
+     *
+     * @param parentLogger - The parent logger to create a child from
+     * @returns A logger with requestId and traceId in the prefix
+     */
+    getLogger(parentLogger) {
+        // FrontMcpLogger.child() takes a string prefix
+        const prefix = `[${this.requestId.slice(0, 8)}:${this.traceContext.traceId.slice(0, 8)}]`;
+        return parentLogger.child(prefix);
+    }
+    /**
+     * Mark a timing point for performance tracking.
+     *
+     * @param name - Name of the timing mark
+     */
+    mark(name) {
+        this.marks.set(name, Date.now());
+    }
+    /**
+     * Get elapsed time in milliseconds between two marks.
+     *
+     * @param from - Start mark name (defaults to 'init')
+     * @param to - End mark name (defaults to current time)
+     * @returns Elapsed time in milliseconds
+     */
+    elapsed(from, to) {
+        const fromTime = this.marks.get(from ?? 'init') ?? this.timestamp;
+        const toTime = to ? this.marks.get(to) ?? Date.now() : Date.now();
+        return toTime - fromTime;
+    }
+    /**
+     * Get all timing marks.
+     *
+     * @returns Read-only map of mark names to timestamps
+     */
+    getMarks() {
+        return this.marks;
+    }
+    /**
+     * Store request-scoped data.
+     *
+     * @param key - Storage key
+     * @param value - Value to store
+     */
+    set(key, value) {
+        this.store.set(key, value);
+    }
+    /**
+     * Retrieve request-scoped data.
+     *
+     * @param key - Storage key
+     * @returns Stored value or undefined
+     */
+    get(key) {
+        return this.store.get(key);
+    }
+    /**
+     * Check if a key exists in the request-scoped store.
+     *
+     * @param key - Storage key
+     * @returns True if key exists
+     */
+    has(key) {
+        return this.store.has(key);
+    }
+    /**
+     * Delete a key from the request-scoped store.
+     *
+     * @param key - Storage key
+     * @returns True if key was deleted
+     */
+    delete(key) {
+        return this.store.delete(key);
+    }
+    /**
+     * Get a summary of the context for logging.
+     *
+     * Note: sessionId is hashed to prevent accidental exposure of user-identifying
+     * session identifiers in logs while still allowing correlation.
+     *
+     * @returns Object with key context fields
+     */
+    toLogContext() {
+        return {
+            requestId: this.requestId,
+            traceId: this.traceContext.traceId,
+            parentId: this.traceContext.parentId,
+            // Hash sessionId to prevent logging user-identifying information
+            // while preserving ability to correlate logs for the same session
+            sessionIdHash: (0, node_crypto_1.createHash)('sha256').update(this.sessionId).digest('hex').slice(0, 12),
+            scopeId: this.scopeId,
+            elapsed: this.elapsed(),
+        };
+    }
+}
+exports.RequestContext = RequestContext;
+//# sourceMappingURL=request-context.js.map