@cyanheads/mcp-ts-core 0.1.0-beta.12

package/dist/utils/internal/performance.js

@@ -0,0 +1,227 @@
+/**
+ * @fileoverview Performance utility for tool execution with modern observability.
+ * Wraps tool logic to measure duration, payload sizes, and memory usage, and
+ * records results to OpenTelemetry plus structured logs. No manual spans beyond
+ * the single wrapper span here per project guidelines.
+ * @module src/utils/internal/performance
+ */
+import { SpanStatusCode, trace } from '@opentelemetry/api';
+import { config } from '../../config/index.js';
+import { McpError } from '../../types-global/errors.js';
+import { logger } from '../../utils/internal/logger.js';
+import { createCounter, createHistogram } from '../../utils/telemetry/metrics.js';
+import { ATTR_CODE_FUNCTION, ATTR_CODE_NAMESPACE, ATTR_MCP_TOOL_DURATION_MS, ATTR_MCP_TOOL_ERROR_CODE, ATTR_MCP_TOOL_INPUT_BYTES, ATTR_MCP_TOOL_MEMORY_HEAP_USED_AFTER, ATTR_MCP_TOOL_MEMORY_HEAP_USED_BEFORE, ATTR_MCP_TOOL_MEMORY_HEAP_USED_DELTA, ATTR_MCP_TOOL_MEMORY_RSS_AFTER, ATTR_MCP_TOOL_MEMORY_RSS_BEFORE, ATTR_MCP_TOOL_MEMORY_RSS_DELTA, ATTR_MCP_TOOL_NAME, ATTR_MCP_TOOL_OUTPUT_BYTES, ATTR_MCP_TOOL_SUCCESS, } from '../../utils/telemetry/semconv.js';
+// OTel metric instruments for tool execution (lazy-initialized on first use)
+let toolCallCounter;
+let toolCallDuration;
+let toolCallErrors;
+function getToolMetrics() {
+    toolCallCounter ??= createCounter('mcp.tool.calls', 'Total MCP tool invocations', '{calls}');
+    toolCallDuration ??= createHistogram('mcp.tool.duration', 'MCP tool execution duration', 'ms');
+    toolCallErrors ??= createCounter('mcp.tool.errors', 'Total MCP tool errors', '{errors}');
+    return { toolCallCounter, toolCallDuration, toolCallErrors };
+}
+// Environment-aware high-resolution timer
+let performanceNow = () => Date.now(); // Fallback
+/**
+ * Dynamically loads Node's `perf_hooks` module.
+ * Exposed as a named export so tests can inject a mock loader into
+ * {@link initHighResTimer} without patching the dynamic import machinery.
+ *
+ * @returns A promise resolving to the `perf_hooks` module shape (just the `performance` export).
+ */
+export async function loadPerfHooks() {
+    return await import('node:perf_hooks');
+}
+/**
+ * Initializes the module-level high-resolution timer used by {@link nowMs}.
+ *
+ * Resolution priority:
+ * 1. `globalThis.performance.now` — available in Cloudflare Workers and modern browsers.
+ * 2. `node:perf_hooks` `performance.now` — loaded dynamically to stay Workers-compatible.
+ * 3. `Date.now()` — millisecond-precision fallback; a warning is logged when this path is taken.
+ *
+ * Must be called once during server startup (before any tool executions) to ensure
+ * sub-millisecond timing accuracy. Subsequent calls are safe but no-ops in practice
+ * because the module-level `performanceNow` closure is overwritten each time.
+ *
+ * @param perfLoader - Optional override for the `perf_hooks` import; defaults to
+ *   {@link loadPerfHooks}. Inject a mock here in unit tests.
+ * @returns A promise that resolves once the timer is ready.
+ */
+export async function initHighResTimer(perfLoader = loadPerfHooks) {
+    // Use a type assertion to safely access `performance` on `globalThis`,
+    // which is present in browser-like environments (e.g., Cloudflare Workers)
+    // but not in Node.js's default global type.
+    const globalWithPerf = globalThis;
+    if (typeof globalWithPerf.performance?.now === 'function') {
+        const perf = globalWithPerf.performance;
+        performanceNow = () => perf.now();
+    }
+    else {
+        try {
+            const { performance: nodePerformance } = await perfLoader();
+            performanceNow = () => nodePerformance.now();
+        }
+        catch (_e) {
+            performanceNow = () => Date.now();
+            logger.warning('Could not import perf_hooks, falling back to Date.now() for performance timing.');
+        }
+    }
+}
+/**
+ * Returns the current time in milliseconds using the highest-resolution timer
+ * available in this environment.
+ *
+ * The precision depends on which timer was selected by {@link initHighResTimer}:
+ * sub-millisecond after a successful init, millisecond-granular otherwise.
+ * The returned value is suitable for computing durations but its epoch origin
+ * is implementation-defined — do not treat it as a wall-clock timestamp.
+ *
+ * @returns Current time in milliseconds.
+ */
+export const nowMs = () => performanceNow();
+const toBytes = (payload) => {
+    if (payload == null)
+        return 0;
+    try {
+        const json = JSON.stringify(payload);
+        // Prefer Buffer when available (Node), otherwise TextEncoder (Web/Workers)
+        if (typeof Buffer !== 'undefined' && typeof Buffer.byteLength === 'function') {
+            return Buffer.byteLength(json, 'utf8');
+        }
+        if (typeof TextEncoder !== 'undefined') {
+            return new TextEncoder().encode(json).length;
+        }
+        return json.length;
+    }
+    catch {
+        return 0;
+    }
+};
+const zeroMemory = {
+    rss: 0,
+    heapUsed: 0,
+    heapTotal: 0,
+    external: 0,
+    arrayBuffers: 0,
+};
+const getMemoryUsage = () => typeof process !== 'undefined' && typeof process.memoryUsage === 'function'
+    ? process.memoryUsage()
+    : zeroMemory;
+/**
+ * Wraps a tool's logic function with full observability: an OpenTelemetry span,
+ * OTel metric counters/histogram, structured log, and memory/payload size capture.
+ *
+ * The caller supplies the raw tool logic as `toolLogicFn`; this function handles
+ * all instrumentation so tool handlers stay free of telemetry boilerplate.
+ *
+ * On success the resolved value is passed through transparently.
+ * On failure the error is re-thrown after being recorded on the span and metrics;
+ * `McpError` instances surface their numeric `code` as the error code attribute.
+ *
+ * @template T - The resolved type of the tool's return value.
+ * @param toolLogicFn - Zero-argument async function containing the tool's business logic.
+ * @param context - Request context extended with `toolName`; used for span/log correlation.
+ * @param inputPayload - The raw input object passed to the tool, serialized to compute byte size.
+ * @returns A promise that resolves with the tool's return value or rejects with the original error.
+ *
+ * @example
+ * ```typescript
+ * const result = await measureToolExecution(
+ *   () => myToolHandler(parsedInput),
+ *   { ...requestContext, toolName: 'my_tool' },
+ *   parsedInput,
+ * );
+ * ```
+ */
+export async function measureToolExecution(toolLogicFn, context, inputPayload) {
+    const tracer = trace.getTracer(config.openTelemetry.serviceName, config.openTelemetry.serviceVersion);
+    const { toolName } = context;
+    return await tracer.startActiveSpan(`tool_execution:${toolName}`, async (span) => {
+        // Pre-capture lightweight metrics
+        const memBefore = getMemoryUsage();
+        const t0 = nowMs();
+        span.setAttributes({
+            [ATTR_CODE_FUNCTION]: toolName,
+            [ATTR_CODE_NAMESPACE]: 'mcp-tools',
+            [ATTR_MCP_TOOL_INPUT_BYTES]: toBytes(inputPayload),
+            [ATTR_MCP_TOOL_MEMORY_RSS_BEFORE]: memBefore.rss,
+            [ATTR_MCP_TOOL_MEMORY_HEAP_USED_BEFORE]: memBefore.heapUsed,
+        });
+        let ok = false;
+        let errorCode;
+        let output;
+        try {
+            const result = await toolLogicFn();
+            ok = true;
+            output = result;
+            span.setStatus({ code: SpanStatusCode.OK });
+            span.setAttribute(ATTR_MCP_TOOL_OUTPUT_BYTES, toBytes(output));
+            return result;
+        }
+        catch (err) {
+            if (err instanceof McpError)
+                errorCode = String(err.code);
+            else if (err instanceof Error)
+                errorCode = 'UNHANDLED_ERROR';
+            else
+                errorCode = 'UNKNOWN_ERROR';
+            if (err instanceof Error)
+                span.recordException(err);
+            span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: err instanceof Error ? err.message : String(err),
+            });
+            throw err;
+        }
+        finally {
+            const t1 = nowMs();
+            const durationMs = Number((t1 - t0).toFixed(2));
+            const memAfter = getMemoryUsage();
+            const rssDelta = memAfter.rss - memBefore.rss;
+            const heapUsedDelta = memAfter.heapUsed - memBefore.heapUsed;
+            span.setAttributes({
+                [ATTR_MCP_TOOL_DURATION_MS]: durationMs,
+                [ATTR_MCP_TOOL_SUCCESS]: ok,
+                [ATTR_MCP_TOOL_MEMORY_RSS_AFTER]: memAfter.rss,
+                [ATTR_MCP_TOOL_MEMORY_HEAP_USED_AFTER]: memAfter.heapUsed,
+                [ATTR_MCP_TOOL_MEMORY_RSS_DELTA]: rssDelta,
+                [ATTR_MCP_TOOL_MEMORY_HEAP_USED_DELTA]: heapUsedDelta,
+            });
+            if (errorCode)
+                span.setAttribute(ATTR_MCP_TOOL_ERROR_CODE, errorCode);
+            span.end();
+            // Record to OTel metric instruments (durable across restarts)
+            const m = getToolMetrics();
+            const metricAttrs = { [ATTR_MCP_TOOL_NAME]: toolName, [ATTR_MCP_TOOL_SUCCESS]: ok };
+            m.toolCallCounter.add(1, metricAttrs);
+            m.toolCallDuration.record(durationMs, metricAttrs);
+            if (!ok)
+                m.toolCallErrors.add(1, { [ATTR_MCP_TOOL_NAME]: toolName });
+            logger.info('Tool execution finished.', {
+                ...context,
+                metrics: {
+                    durationMs,
+                    isSuccess: ok,
+                    errorCode,
+                    inputBytes: toBytes(inputPayload),
+                    outputBytes: toBytes(output),
+                    memory: {
+                        rss: {
+                            before: memBefore.rss,
+                            after: memAfter.rss,
+                            delta: rssDelta,
+                        },
+                        heapUsed: {
+                            before: memBefore.heapUsed,
+                            after: memAfter.heapUsed,
+                            delta: heapUsedDelta,
+                        },
+                    },
+                },
+            });
+        }
+    });
+}
+//# sourceMappingURL=performance.js.map

package/dist/utils/internal/performance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"performance.js","sourceRoot":"","sources":["../../../src/utils/internal/performance.ts"],"names":[],"mappings":"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"}

package/dist/utils/internal/requestContext.d.ts

@@ -0,0 +1,200 @@
+import type { AuthInfo } from '../../mcp-server/transports/auth/lib/authTypes.js';
+/**
+ * Processed authentication data extracted from a validated JWT or OAuth token
+ * and attached to a {@link RequestContext} by {@link requestContextService.withAuthInfo}.
+ *
+ * Fields map directly to standard JWT claims: `clientId` ← `cid`/`client_id`,
+ * `scopes` ← `scp`/`scope` (split to array), `sub` ← `sub`, `tenantId` ← `tid`.
+ *
+ * @example
+ * ```typescript
+ * const auth: AuthContext = ctx.auth!;
+ * if (auth.scopes.includes('tool:my_tool:read')) {
+ *   // authorized
+ * }
+ * ```
+ */
+export interface AuthContext {
+    /** The client application identifier (`cid` or `client_id` JWT claim). */
+    clientId: string;
+    /** Granted permission scopes derived from the `scp` or `scope` JWT claim. */
+    scopes: string[];
+    /** Subject identifier — the user or service principal (`sub` JWT claim). Falls back to `clientId` when `sub` is absent. */
+    sub: string;
+    /** Tenant identifier from the `tid` JWT claim. Present only for multi-tenant tokens. */
+    tenantId?: string;
+    /** The raw JWT or OAuth bearer token string. */
+    token: string;
+    /** Additional token payload properties not mapped to named fields. */
+    [key: string]: unknown;
+}
+/**
+ * Core context object associated with a single request or operation.
+ *
+ * Every handler invocation receives a `RequestContext` (wrapped in `Context`).
+ * It is the authoritative source for log correlation (`requestId`, `traceId`,
+ * `spanId`), multi-tenancy isolation (`tenantId`), and auth (`auth`).
+ *
+ * Optional fields (`traceId`, `spanId`) are injected automatically when an
+ * OpenTelemetry active span exists at context-creation time.
+ *
+ * @example
+ * ```typescript
+ * // Read-only access in a handler
+ * ctx.log.info('Handling request', { requestId: ctx.requestId, tenantId: ctx.tenantId });
+ * ```
+ */
+export interface RequestContext {
+    /**
+     * Authentication data populated by {@link requestContextService.withAuthInfo}.
+     * `undefined` when the request is unauthenticated or auth mode is `none`.
+     */
+    auth?: AuthContext;
+    /**
+     * Unique identifier for this request, used to correlate log entries across
+     * service boundaries. Inherited from a parent context when provided;
+     * otherwise generated by {@link generateRequestContextId}.
+     */
+    requestId: string;
+    /**
+     * OpenTelemetry span ID from the active span at context-creation time.
+     * `undefined` when no active span exists.
+     */
+    spanId?: string;
+    /**
+     * Tenant identifier used for multi-tenancy data isolation.
+     * Resolved in priority order: `additionalContext.tenantId` →
+     * rest params → `parentContext.tenantId` → AsyncLocalStorage auth store.
+     */
+    tenantId?: string;
+    /**
+     * ISO 8601 UTC timestamp recorded at the moment this context was created.
+     */
+    timestamp: string;
+    /**
+     * OpenTelemetry trace ID from the active span at context-creation time.
+     * `undefined` when no active span exists.
+     */
+    traceId?: string;
+    /**
+     * Additional arbitrary key-value pairs for operation-specific context.
+     * Consumers must type-check before accessing extended properties.
+     */
+    [key: string]: unknown;
+}
+/**
+ * Parameters accepted by {@link requestContextService.createRequestContext}.
+ *
+ * Named fields (`parentContext`, `additionalContext`, `operation`) receive
+ * special handling. All other properties are spread directly onto the resulting
+ * {@link RequestContext} as-is, allowing ad-hoc context extension without
+ * modifying this interface.
+ *
+ * @example
+ * ```typescript
+ * const ctx = requestContextService.createRequestContext({
+ *   operation: 'fetchUser',
+ *   parentContext: incomingCtx,
+ *   additionalContext: { userId: '123' },
+ * });
+ * ```
+ */
+export interface CreateRequestContextParams {
+    /**
+     * Key-value pairs merged into the context after `parentContext` properties
+     * but before `requestId`/`timestamp` are pinned. Takes precedence over
+     * `parentContext` for overlapping keys. `requestId` and `timestamp` keys in
+     * `additionalContext` are silently stripped to prevent overwrites.
+     */
+    additionalContext?: Record<string, unknown>;
+    /**
+     * Human-readable label for the operation creating this context.
+     * Written onto the context as `context.operation` when provided.
+     */
+    operation?: string;
+    /**
+     * Parent context whose properties are inherited as the base. When
+     * `parentContext.requestId` is a non-empty string it is reused as-is,
+     * preserving the same request ID across a call chain.
+     */
+    parentContext?: Record<string, unknown> | RequestContext | undefined;
+    /** Any additional key-value pairs spread directly onto the resulting context. */
+    [key: string]: unknown;
+}
+/**
+ * Service for creating and enriching {@link RequestContext} instances.
+ *
+ * The two primary methods cover the full lifecycle:
+ * - {@link requestContextService.createRequestContext} — general-purpose context
+ *   creation with parent propagation and OTel integration.
+ * - {@link requestContextService.withAuthInfo} — enriches a context with
+ *   structured auth data from a validated token.
+ *
+ * @example
+ * ```typescript
+ * import { requestContextService } from '../../utils/internal/requestContext.js';
+ *
+ * // Create a root context for an incoming request
+ * const ctx = requestContextService.createRequestContext({ operation: 'handleRequest' });
+ *
+ * // Enrich with auth after token verification
+ * const authCtx = requestContextService.withAuthInfo(verifiedAuthInfo, ctx);
+ * ```
+ */
+export declare const requestContextService: {
+    /**
+     * Creates a new {@link RequestContext} with a guaranteed unique `requestId`
+     * and current ISO 8601 `timestamp`.
+     *
+     * Merge order (later entries win, except `requestId`/`timestamp` which are
+     * always generated fresh or inherited):
+     * 1. `parentContext` properties (base)
+     * 2. Remaining spread params (everything in `params` except named fields)
+     * 3. `additionalContext` properties (`requestId`/`timestamp` stripped)
+     * 4. Resolved `requestId` and `timestamp` (canonical, never overwritten)
+     * 5. Resolved `tenantId` (see priority order in {@link RequestContext.tenantId})
+     * 6. `operation` (written as `context.operation` when provided)
+     * 7. OTel `traceId`/`spanId` from the active span (when present)
+     *
+     * @param params - Context creation parameters. Defaults to `{}`.
+     * @returns A fully constructed `RequestContext`.
+     *
+     * @example
+     * ```typescript
+     * // Minimal — generates a fresh requestId and timestamp
+     * const ctx = requestContextService.createRequestContext();
+     *
+     * // Propagate an existing request ID across a call chain
+     * const childCtx = requestContextService.createRequestContext({
+     *   parentContext: incomingCtx,
+     *   operation: 'processItem',
+     *   additionalContext: { itemId: item.id },
+     * });
+     * ```
+     */
+    createRequestContext(params?: CreateRequestContextParams): RequestContext;
+    /**
+     * Creates a new {@link RequestContext} enriched with authentication information.
+     * This method populates the context with auth data from a validated token,
+     * including tenant ID, client ID, scopes, and subject.
+     *
+     * **Note:** This method builds and returns a `RequestContext` object only.
+     * It does NOT propagate auth into `AsyncLocalStorage`. ALS propagation is
+     * handled by the auth middleware via `authContext.run()`. If you need
+     * scope enforcement via `withRequiredScopes()`, ensure the call runs
+     * inside the middleware's ALS continuation.
+     *
+     * @param authInfo - The validated authentication information from JWT/OAuth token.
+     * @param parentContext - Optional parent context to inherit properties from.
+     * @returns A new `RequestContext` object with auth information populated.
+     *
+     * @example
+     * ```typescript
+     * const authInfo = await jwtStrategy.verify(token);
+     * const context = requestContextService.withAuthInfo(authInfo);
+     * // context now includes: { requestId, timestamp, tenantId, auth: {...}, ... }
+     * ```
+     */
+    withAuthInfo(authInfo: AuthInfo, parentContext?: Record<string, unknown> | RequestContext): RequestContext;
+};
+//# sourceMappingURL=requestContext.d.ts.map

package/dist/utils/internal/requestContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requestContext.d.ts","sourceRoot":"","sources":["../../../src/utils/internal/requestContext.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,+CAA+C,CAAC;AAG9E;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,WAAW;IAC1B,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,2HAA2H;IAC3H,GAAG,EAAE,MAAM,CAAC;IACZ,wFAAwF;IACxF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE5C;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,cAAc,GAAG,SAAS,CAAC;IAErE,iFAAiF;IACjF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AA8ID;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,qBAAqB;IA3JhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;kCAC0B,0BAA0B,GAAQ,cAAc;IAuD7E;;;;;;;;;;;;;;;;;;;;;OAqBG;2BAES,QAAQ,kBACF,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,cAAc,GACvD,cAAc;CA6C+C,CAAC"}

package/dist/utils/internal/requestContext.js

@@ -0,0 +1,163 @@
+/**
+ * @fileoverview Utilities for creating and managing request contexts.
+ *
+ * A request context is an immutable-by-convention object that carries a unique
+ * request ID, ISO 8601 timestamp, optional tenant ID, and optional auth data.
+ * It is the primary carrier for log correlation, distributed tracing, and
+ * multi-tenancy isolation throughout the server.
+ *
+ * Key behaviors:
+ * - `requestId` is inherited from a parent context when provided, otherwise a
+ *   new unique ID is generated via {@link generateRequestContextId}.
+ * - `tenantId` is resolved with the following priority (highest to lowest):
+ *   `additionalContext.tenantId` → spread rest params → `parentContext.tenantId`
+ *   → AsyncLocalStorage auth store (`authContext`).
+ * - OpenTelemetry `traceId` and `spanId` are automatically injected from the
+ *   active span when one exists.
+ * - Auth data is populated separately via {@link requestContextService.withAuthInfo}
+ *   and is NOT stored in AsyncLocalStorage by this module — ALS propagation is
+ *   the responsibility of auth middleware.
+ *
+ * @module src/utils/internal/requestContext
+ */
+import { trace } from '@opentelemetry/api';
+import { authContext as alsAuthContext } from '../../mcp-server/transports/auth/lib/authContext.js';
+import { generateRequestContextId } from '../../utils/security/idGenerator.js';
+/**
+ * Singleton-like service object for managing request context operations.
+ * @private
+ */
+const requestContextServiceInstance = {
+    /**
+     * Creates a new {@link RequestContext} with a guaranteed unique `requestId`
+     * and current ISO 8601 `timestamp`.
+     *
+     * Merge order (later entries win, except `requestId`/`timestamp` which are
+     * always generated fresh or inherited):
+     * 1. `parentContext` properties (base)
+     * 2. Remaining spread params (everything in `params` except named fields)
+     * 3. `additionalContext` properties (`requestId`/`timestamp` stripped)
+     * 4. Resolved `requestId` and `timestamp` (canonical, never overwritten)
+     * 5. Resolved `tenantId` (see priority order in {@link RequestContext.tenantId})
+     * 6. `operation` (written as `context.operation` when provided)
+     * 7. OTel `traceId`/`spanId` from the active span (when present)
+     *
+     * @param params - Context creation parameters. Defaults to `{}`.
+     * @returns A fully constructed `RequestContext`.
+     *
+     * @example
+     * ```typescript
+     * // Minimal — generates a fresh requestId and timestamp
+     * const ctx = requestContextService.createRequestContext();
+     *
+     * // Propagate an existing request ID across a call chain
+     * const childCtx = requestContextService.createRequestContext({
+     *   parentContext: incomingCtx,
+     *   operation: 'processItem',
+     *   additionalContext: { itemId: item.id },
+     * });
+     * ```
+     */
+    createRequestContext(params = {}) {
+        const { parentContext, additionalContext, operation, ...rest } = params;
+        const inheritedContext = parentContext && typeof parentContext === 'object' ? { ...parentContext } : {};
+        const authStore = alsAuthContext.getStore();
+        const tenantIdFromAuth = authStore?.authInfo?.tenantId;
+        const requestId = typeof inheritedContext.requestId === 'string' && inheritedContext.requestId
+            ? inheritedContext.requestId
+            : generateRequestContextId();
+        const timestamp = new Date().toISOString();
+        const extractTenantId = (obj) => obj != null && typeof obj.tenantId === 'string' ? obj.tenantId : undefined;
+        const resolvedTenantId = extractTenantId(additionalContext) ??
+            extractTenantId(rest) ??
+            extractTenantId(inheritedContext) ??
+            tenantIdFromAuth;
+        // Strip system fields from additionalContext to prevent overwriting requestId/timestamp
+        const { requestId: _r, timestamp: _t, ...safeAdditional } = additionalContext && typeof additionalContext === 'object' ? additionalContext : {};
+        const context = {
+            ...inheritedContext,
+            ...rest, // Spread any other properties from the params object
+            ...safeAdditional,
+            requestId,
+            timestamp,
+            ...(resolvedTenantId ? { tenantId: resolvedTenantId } : {}),
+            ...(operation && typeof operation === 'string' ? { operation } : {}),
+        };
+        // --- OpenTelemetry Integration ---
+        const activeSpan = trace.getActiveSpan();
+        if (activeSpan && typeof activeSpan.spanContext === 'function') {
+            const spanContext = activeSpan.spanContext();
+            if (spanContext) {
+                context.traceId = spanContext.traceId;
+                context.spanId = spanContext.spanId;
+            }
+        }
+        // --- End OpenTelemetry Integration ---
+        return context;
+    },
+    /**
+     * Creates a new {@link RequestContext} enriched with authentication information.
+     * This method populates the context with auth data from a validated token,
+     * including tenant ID, client ID, scopes, and subject.
+     *
+     * **Note:** This method builds and returns a `RequestContext` object only.
+     * It does NOT propagate auth into `AsyncLocalStorage`. ALS propagation is
+     * handled by the auth middleware via `authContext.run()`. If you need
+     * scope enforcement via `withRequiredScopes()`, ensure the call runs
+     * inside the middleware's ALS continuation.
+     *
+     * @param authInfo - The validated authentication information from JWT/OAuth token.
+     * @param parentContext - Optional parent context to inherit properties from.
+     * @returns A new `RequestContext` object with auth information populated.
+     *
+     * @example
+     * ```typescript
+     * const authInfo = await jwtStrategy.verify(token);
+     * const context = requestContextService.withAuthInfo(authInfo);
+     * // context now includes: { requestId, timestamp, tenantId, auth: {...}, ... }
+     * ```
+     */
+    withAuthInfo(authInfo, parentContext) {
+        const baseContext = this.createRequestContext({
+            operation: 'withAuthInfo',
+            parentContext,
+            additionalContext: {
+                tenantId: authInfo.tenantId,
+            },
+        });
+        // Populate auth property with structured authentication context
+        const authContext = {
+            sub: authInfo.subject ?? authInfo.clientId,
+            scopes: authInfo.scopes,
+            clientId: authInfo.clientId,
+            token: authInfo.token,
+            ...(authInfo.tenantId ? { tenantId: authInfo.tenantId } : {}),
+        };
+        return {
+            ...baseContext,
+            auth: authContext,
+        };
+    },
+};
+/**
+ * Service for creating and enriching {@link RequestContext} instances.
+ *
+ * The two primary methods cover the full lifecycle:
+ * - {@link requestContextService.createRequestContext} — general-purpose context
+ *   creation with parent propagation and OTel integration.
+ * - {@link requestContextService.withAuthInfo} — enriches a context with
+ *   structured auth data from a validated token.
+ *
+ * @example
+ * ```typescript
+ * import { requestContextService } from '../../utils/internal/requestContext.js';
+ *
+ * // Create a root context for an incoming request
+ * const ctx = requestContextService.createRequestContext({ operation: 'handleRequest' });
+ *
+ * // Enrich with auth after token verification
+ * const authCtx = requestContextService.withAuthInfo(verifiedAuthInfo, ctx);
+ * ```
+ */
+export const requestContextService = requestContextServiceInstance;
+//# sourceMappingURL=requestContext.js.map

package/dist/utils/internal/requestContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requestContext.js","sourceRoot":"","sources":["../../../src/utils/internal/requestContext.ts"],"names":[],"mappings":"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"}

package/dist/utils/internal/runtime.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @fileoverview Runtime capability detection for multi-environment support.
+ * Detects presence of Node features, Web/Workers APIs, and common globals.
+ * @module src/utils/internal/runtime
+ */
+/**
+ * Snapshot of runtime feature availability detected at module load time.
+ * All fields are booleans computed once via safe feature-detection; they never
+ * throw and never change after the module is first imported.
+ */
+export interface RuntimeCapabilities {
+    /** True when the Node.js `Buffer` global is available. */
+    hasBuffer: boolean;
+    /** True when `globalThis.performance.now` is a callable function. */
+    hasPerformanceNow: boolean;
+    /** True when the `process` global is defined (Node.js, Bun, or some bundled envs). */
+    hasProcess: boolean;
+    /** True when `TextEncoder` is available on `globalThis`. */
+    hasTextEncoder: boolean;
+    /** True when running in a browser main thread (has `window`, not a Worker or Node). */
+    isBrowserLike: boolean;
+    /**
+     * True when running under Bun.
+     * Bun sets both `process.versions.node` and `process.versions.bun`,
+     * so `isNode` is also true in Bun environments.
+     */
+    isBun: boolean;
+    /** True when `process.versions.node` is a string (Node.js or Bun). */
+    isNode: boolean;
+    /** True when running inside a Web Worker or Cloudflare Worker (`WorkerGlobalScope` is present). */
+    isWorkerLike: boolean;
+}
+/**
+ * Singleton snapshot of runtime capabilities for the current environment.
+ * Computed once at module load; safe to read at any time without async.
+ *
+ * @example
+ * ```typescript
+ * import { runtimeCaps } from './runtime.js';
+ *
+ * if (runtimeCaps.hasBuffer) {
+ *   // Node.js / Bun path — use Buffer for encoding
+ * } else {
+ *   // Worker / browser path — use Web APIs
+ * }
+ * ```
+ */
+export declare const runtimeCaps: RuntimeCapabilities;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/utils/internal/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../src/utils/internal/runtime.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,0DAA0D;IAC1D,SAAS,EAAE,OAAO,CAAC;IACnB,qEAAqE;IACrE,iBAAiB,EAAE,OAAO,CAAC;IAC3B,sFAAsF;IACtF,UAAU,EAAE,OAAO,CAAC;IACpB,4DAA4D;IAC5D,cAAc,EAAE,OAAO,CAAC;IACxB,uFAAuF;IACvF,aAAa,EAAE,OAAO,CAAC;IACvB;;;;OAIG;IACH,KAAK,EAAE,OAAO,CAAC;IACf,sEAAsE;IACtE,MAAM,EAAE,OAAO,CAAC;IAChB,mGAAmG;IACnG,YAAY,EAAE,OAAO,CAAC;CACvB;AAiED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,WAAW,EAAE,mBASzB,CAAC"}