@frontmcp/sdk 0.4.0 → 0.5.0

package/src/auth/session/transport-session.types.d.ts

@@ -0,0 +1,457 @@
+import { z } from 'zod';
+/**
+ * Transport protocol types supported by MCP
+ * These are the actual transport protocols for sessions (excludes 'delete-session' action)
+ */
+export type TransportProtocol = 'legacy-sse' | 'sse' | 'streamable-http' | 'stateful-http' | 'stateless-http';
+/**
+ * Session storage mode for distributed systems
+ */
+export type SessionStorageMode = 'stateless' | 'stateful';
+/**
+ * TransportSession represents a single client connection.
+ * Multiple sessions can share the same authorization.
+ * Each session is bound to a specific transport protocol.
+ */
+export interface TransportSession {
+    /** Unique session ID (encrypted JWT or UUID) */
+    id: string;
+    /** Reference to the authorization this session uses */
+    authorizationId: string;
+    /** Transport protocol for this session */
+    protocol: TransportProtocol;
+    /** Session creation timestamp (epoch ms) */
+    createdAt: number;
+    /** Session expiration (epoch ms, independent of auth expiration) */
+    expiresAt?: number;
+    /** Node ID for distributed systems */
+    nodeId: string;
+    /** Client fingerprint for rate limiting/tracking */
+    clientFingerprint?: string;
+    /** Transport-specific state */
+    transportState?: TransportState;
+}
+/**
+ * Transport-specific state that varies by protocol
+ */
+export type TransportState = SseTransportState | StreamableHttpTransportState | StatefulHttpTransportState | StatelessHttpTransportState | LegacySseTransportState;
+/**
+ * SSE (Server-Sent Events) transport state
+ */
+export interface SseTransportState {
+    type: 'sse';
+    /** Last event ID for reconnection (per SSE spec) */
+    lastEventId?: string;
+    /** Connection keep-alive timestamp */
+    lastPing?: number;
+    /** Connection state */
+    connectionState?: 'connecting' | 'open' | 'closed';
+}
+/**
+ * Streamable HTTP transport state
+ */
+export interface StreamableHttpTransportState {
+    type: 'streamable-http';
+    /** Request sequence number */
+    requestSeq: number;
+    /** Active stream ID if streaming */
+    activeStreamId?: string;
+    /** Pending request IDs */
+    pendingRequests?: string[];
+}
+/**
+ * Stateful HTTP transport state
+ */
+export interface StatefulHttpTransportState {
+    type: 'stateful-http';
+    /** Request sequence number */
+    requestSeq: number;
+    /** Pending responses awaiting delivery */
+    pendingResponses?: string[];
+    /** Last activity timestamp */
+    lastActivity?: number;
+}
+/**
+ * Stateless HTTP transport state
+ */
+export interface StatelessHttpTransportState {
+    type: 'stateless-http';
+    /** Request count for rate limiting */
+    requestCount: number;
+    /** Window start for rate limiting */
+    windowStart?: number;
+}
+/**
+ * Legacy SSE transport state (for backwards compatibility)
+ */
+export interface LegacySseTransportState {
+    type: 'legacy-sse';
+    /** Message endpoint path */
+    messagePath: string;
+    /** Last event ID */
+    lastEventId?: string;
+    /** Connection state */
+    connectionState?: 'connecting' | 'open' | 'closed';
+}
+/**
+ * Session JWT payload - encodes both auth ref and transport context
+ * This is the structure encrypted in the mcp-session-id header
+ */
+export interface SessionJwtPayload {
+    /** Session ID (UUID) */
+    sid: string;
+    /** Authorization ID (token signature fingerprint) */
+    aid: string;
+    /** Transport protocol */
+    proto: TransportProtocol;
+    /** Node ID (for distributed systems) */
+    nid: string;
+    /** Issued at (epoch seconds) */
+    iat: number;
+    /** Expiration (epoch seconds) */
+    exp?: number;
+}
+/**
+ * Extended session JWT payload for stateless mode
+ * Includes encrypted state and tokens
+ */
+export interface StatelessSessionJwtPayload extends SessionJwtPayload {
+    /** Encrypted transport state (AES-256-GCM) */
+    state?: string;
+    /** Encrypted provider tokens (AES-256-GCM, for orchestrated mode) */
+    tokens?: string;
+}
+/**
+ * Stored session record (for stateful mode in Redis/memory)
+ */
+export interface StoredSession {
+    /** The transport session data */
+    session: TransportSession;
+    /** Authorization ID reference */
+    authorizationId: string;
+    /** Encrypted provider tokens (for orchestrated mode) */
+    tokens?: Record<string, EncryptedBlob>;
+    /** Creation timestamp */
+    createdAt: number;
+    /** Last accessed timestamp */
+    lastAccessedAt: number;
+}
+/**
+ * Encrypted blob structure (AES-256-GCM)
+ */
+export interface EncryptedBlob {
+    /** Algorithm identifier */
+    alg: 'A256GCM';
+    /** Key ID (for rotation) */
+    kid?: string;
+    /** Initialization vector (base64url) */
+    iv: string;
+    /** Authentication tag (base64url) */
+    tag: string;
+    /** Ciphertext (base64url) */
+    data: string;
+    /** Expiration hint (epoch seconds) */
+    exp?: number;
+    /** Additional metadata */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Session store interface for stateful sessions
+ */
+export interface SessionStore {
+    /**
+     * Get a stored session by ID
+     */
+    get(sessionId: string): Promise<StoredSession | null>;
+    /**
+     * Store a session with optional TTL
+     */
+    set(sessionId: string, session: StoredSession, ttlMs?: number): Promise<void>;
+    /**
+     * Delete a session
+     */
+    delete(sessionId: string): Promise<void>;
+    /**
+     * Check if a session exists
+     */
+    exists(sessionId: string): Promise<boolean>;
+    /**
+     * Allocate a new session ID
+     */
+    allocId(): string;
+}
+/**
+ * Session storage configuration
+ */
+export type SessionStorageConfig = {
+    mode: 'stateless';
+} | {
+    mode: 'stateful';
+    store: 'memory';
+} | {
+    mode: 'stateful';
+    store: 'redis';
+    config: RedisConfig;
+};
+/**
+ * Redis configuration
+ */
+export interface RedisConfig {
+    host: string;
+    port?: number;
+    password?: string;
+    db?: number;
+    tls?: boolean;
+    keyPrefix?: string;
+}
+export declare const transportProtocolSchema: z.ZodEnum<{
+    "legacy-sse": "legacy-sse";
+    sse: "sse";
+    "streamable-http": "streamable-http";
+    "stateful-http": "stateful-http";
+    "stateless-http": "stateless-http";
+}>;
+export declare const sseTransportStateSchema: z.ZodObject<{
+    type: z.ZodLiteral<"sse">;
+    lastEventId: z.ZodOptional<z.ZodString>;
+    lastPing: z.ZodOptional<z.ZodNumber>;
+    connectionState: z.ZodOptional<z.ZodEnum<{
+        connecting: "connecting";
+        open: "open";
+        closed: "closed";
+    }>>;
+}, z.core.$strip>;
+export declare const streamableHttpTransportStateSchema: z.ZodObject<{
+    type: z.ZodLiteral<"streamable-http">;
+    requestSeq: z.ZodNumber;
+    activeStreamId: z.ZodOptional<z.ZodString>;
+    pendingRequests: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const statefulHttpTransportStateSchema: z.ZodObject<{
+    type: z.ZodLiteral<"stateful-http">;
+    requestSeq: z.ZodNumber;
+    pendingResponses: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    lastActivity: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const statelessHttpTransportStateSchema: z.ZodObject<{
+    type: z.ZodLiteral<"stateless-http">;
+    requestCount: z.ZodNumber;
+    windowStart: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const legacySseTransportStateSchema: z.ZodObject<{
+    type: z.ZodLiteral<"legacy-sse">;
+    messagePath: z.ZodString;
+    lastEventId: z.ZodOptional<z.ZodString>;
+    connectionState: z.ZodOptional<z.ZodEnum<{
+        connecting: "connecting";
+        open: "open";
+        closed: "closed";
+    }>>;
+}, z.core.$strip>;
+export declare const transportStateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"sse">;
+    lastEventId: z.ZodOptional<z.ZodString>;
+    lastPing: z.ZodOptional<z.ZodNumber>;
+    connectionState: z.ZodOptional<z.ZodEnum<{
+        connecting: "connecting";
+        open: "open";
+        closed: "closed";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"streamable-http">;
+    requestSeq: z.ZodNumber;
+    activeStreamId: z.ZodOptional<z.ZodString>;
+    pendingRequests: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"stateful-http">;
+    requestSeq: z.ZodNumber;
+    pendingResponses: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    lastActivity: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"stateless-http">;
+    requestCount: z.ZodNumber;
+    windowStart: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"legacy-sse">;
+    messagePath: z.ZodString;
+    lastEventId: z.ZodOptional<z.ZodString>;
+    connectionState: z.ZodOptional<z.ZodEnum<{
+        connecting: "connecting";
+        open: "open";
+        closed: "closed";
+    }>>;
+}, z.core.$strip>], "type">;
+export declare const transportSessionSchema: z.ZodObject<{
+    id: z.ZodString;
+    authorizationId: z.ZodString;
+    protocol: z.ZodEnum<{
+        "legacy-sse": "legacy-sse";
+        sse: "sse";
+        "streamable-http": "streamable-http";
+        "stateful-http": "stateful-http";
+        "stateless-http": "stateless-http";
+    }>;
+    createdAt: z.ZodNumber;
+    expiresAt: z.ZodOptional<z.ZodNumber>;
+    nodeId: z.ZodString;
+    clientFingerprint: z.ZodOptional<z.ZodString>;
+    transportState: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"sse">;
+        lastEventId: z.ZodOptional<z.ZodString>;
+        lastPing: z.ZodOptional<z.ZodNumber>;
+        connectionState: z.ZodOptional<z.ZodEnum<{
+            connecting: "connecting";
+            open: "open";
+            closed: "closed";
+        }>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"streamable-http">;
+        requestSeq: z.ZodNumber;
+        activeStreamId: z.ZodOptional<z.ZodString>;
+        pendingRequests: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"stateful-http">;
+        requestSeq: z.ZodNumber;
+        pendingResponses: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        lastActivity: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"stateless-http">;
+        requestCount: z.ZodNumber;
+        windowStart: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"legacy-sse">;
+        messagePath: z.ZodString;
+        lastEventId: z.ZodOptional<z.ZodString>;
+        connectionState: z.ZodOptional<z.ZodEnum<{
+            connecting: "connecting";
+            open: "open";
+            closed: "closed";
+        }>>;
+    }, z.core.$strip>], "type">>;
+}, z.core.$strip>;
+export declare const sessionJwtPayloadSchema: z.ZodObject<{
+    sid: z.ZodString;
+    aid: z.ZodString;
+    proto: z.ZodEnum<{
+        "legacy-sse": "legacy-sse";
+        sse: "sse";
+        "streamable-http": "streamable-http";
+        "stateful-http": "stateful-http";
+        "stateless-http": "stateless-http";
+    }>;
+    nid: z.ZodString;
+    iat: z.ZodNumber;
+    exp: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const statelessSessionJwtPayloadSchema: z.ZodObject<{
+    sid: z.ZodString;
+    aid: z.ZodString;
+    proto: z.ZodEnum<{
+        "legacy-sse": "legacy-sse";
+        sse: "sse";
+        "streamable-http": "streamable-http";
+        "stateful-http": "stateful-http";
+        "stateless-http": "stateless-http";
+    }>;
+    nid: z.ZodString;
+    iat: z.ZodNumber;
+    exp: z.ZodOptional<z.ZodNumber>;
+    state: z.ZodOptional<z.ZodString>;
+    tokens: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const encryptedBlobSchema: z.ZodObject<{
+    alg: z.ZodLiteral<"A256GCM">;
+    kid: z.ZodOptional<z.ZodString>;
+    iv: z.ZodString;
+    tag: z.ZodString;
+    data: z.ZodString;
+    exp: z.ZodOptional<z.ZodNumber>;
+    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const storedSessionSchema: z.ZodObject<{
+    session: z.ZodObject<{
+        id: z.ZodString;
+        authorizationId: z.ZodString;
+        protocol: z.ZodEnum<{
+            "legacy-sse": "legacy-sse";
+            sse: "sse";
+            "streamable-http": "streamable-http";
+            "stateful-http": "stateful-http";
+            "stateless-http": "stateless-http";
+        }>;
+        createdAt: z.ZodNumber;
+        expiresAt: z.ZodOptional<z.ZodNumber>;
+        nodeId: z.ZodString;
+        clientFingerprint: z.ZodOptional<z.ZodString>;
+        transportState: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"sse">;
+            lastEventId: z.ZodOptional<z.ZodString>;
+            lastPing: z.ZodOptional<z.ZodNumber>;
+            connectionState: z.ZodOptional<z.ZodEnum<{
+                connecting: "connecting";
+                open: "open";
+                closed: "closed";
+            }>>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"streamable-http">;
+            requestSeq: z.ZodNumber;
+            activeStreamId: z.ZodOptional<z.ZodString>;
+            pendingRequests: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"stateful-http">;
+            requestSeq: z.ZodNumber;
+            pendingResponses: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            lastActivity: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"stateless-http">;
+            requestCount: z.ZodNumber;
+            windowStart: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"legacy-sse">;
+            messagePath: z.ZodString;
+            lastEventId: z.ZodOptional<z.ZodString>;
+            connectionState: z.ZodOptional<z.ZodEnum<{
+                connecting: "connecting";
+                open: "open";
+                closed: "closed";
+            }>>;
+        }, z.core.$strip>], "type">>;
+    }, z.core.$strip>;
+    authorizationId: z.ZodString;
+    tokens: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        alg: z.ZodLiteral<"A256GCM">;
+        kid: z.ZodOptional<z.ZodString>;
+        iv: z.ZodString;
+        tag: z.ZodString;
+        data: z.ZodString;
+        exp: z.ZodOptional<z.ZodNumber>;
+        meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>>;
+    createdAt: z.ZodNumber;
+    lastAccessedAt: z.ZodNumber;
+}, z.core.$strip>;
+export declare const redisConfigSchema: z.ZodObject<{
+    host: z.ZodString;
+    port: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    password: z.ZodOptional<z.ZodString>;
+    db: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    tls: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    keyPrefix: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+}, z.core.$strip>;
+export declare const sessionStorageConfigSchema: z.ZodUnion<readonly [z.ZodObject<{
+    mode: z.ZodLiteral<"stateless">;
+}, z.core.$strip>, z.ZodObject<{
+    mode: z.ZodLiteral<"stateful">;
+    store: z.ZodLiteral<"memory">;
+}, z.core.$strip>, z.ZodObject<{
+    mode: z.ZodLiteral<"stateful">;
+    store: z.ZodLiteral<"redis">;
+    config: z.ZodObject<{
+        host: z.ZodString;
+        port: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        password: z.ZodOptional<z.ZodString>;
+        db: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        tls: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        keyPrefix: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    }, z.core.$strip>;
+}, z.core.$strip>]>;

package/src/auth/session/transport-session.types.js

@@ -0,0 +1,110 @@
+"use strict";
+// auth/session/transport-session.types.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sessionStorageConfigSchema = exports.redisConfigSchema = exports.storedSessionSchema = exports.encryptedBlobSchema = exports.statelessSessionJwtPayloadSchema = exports.sessionJwtPayloadSchema = exports.transportSessionSchema = exports.transportStateSchema = exports.legacySseTransportStateSchema = exports.statelessHttpTransportStateSchema = exports.statefulHttpTransportStateSchema = exports.streamableHttpTransportStateSchema = exports.sseTransportStateSchema = exports.transportProtocolSchema = void 0;
+const zod_1 = require("zod");
+// ============================================
+// Zod Schemas
+// ============================================
+exports.transportProtocolSchema = zod_1.z.enum([
+    'legacy-sse',
+    'sse',
+    'streamable-http',
+    'stateful-http',
+    'stateless-http',
+]);
+exports.sseTransportStateSchema = zod_1.z.object({
+    type: zod_1.z.literal('sse'),
+    lastEventId: zod_1.z.string().optional(),
+    lastPing: zod_1.z.number().optional(),
+    connectionState: zod_1.z.enum(['connecting', 'open', 'closed']).optional(),
+});
+exports.streamableHttpTransportStateSchema = zod_1.z.object({
+    type: zod_1.z.literal('streamable-http'),
+    requestSeq: zod_1.z.number(),
+    activeStreamId: zod_1.z.string().optional(),
+    pendingRequests: zod_1.z.array(zod_1.z.string()).optional(),
+});
+exports.statefulHttpTransportStateSchema = zod_1.z.object({
+    type: zod_1.z.literal('stateful-http'),
+    requestSeq: zod_1.z.number(),
+    pendingResponses: zod_1.z.array(zod_1.z.string()).optional(),
+    lastActivity: zod_1.z.number().optional(),
+});
+exports.statelessHttpTransportStateSchema = zod_1.z.object({
+    type: zod_1.z.literal('stateless-http'),
+    requestCount: zod_1.z.number(),
+    windowStart: zod_1.z.number().optional(),
+});
+exports.legacySseTransportStateSchema = zod_1.z.object({
+    type: zod_1.z.literal('legacy-sse'),
+    messagePath: zod_1.z.string(),
+    lastEventId: zod_1.z.string().optional(),
+    connectionState: zod_1.z.enum(['connecting', 'open', 'closed']).optional(),
+});
+exports.transportStateSchema = zod_1.z.discriminatedUnion('type', [
+    exports.sseTransportStateSchema,
+    exports.streamableHttpTransportStateSchema,
+    exports.statefulHttpTransportStateSchema,
+    exports.statelessHttpTransportStateSchema,
+    exports.legacySseTransportStateSchema,
+]);
+exports.transportSessionSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    authorizationId: zod_1.z.string(),
+    protocol: exports.transportProtocolSchema,
+    createdAt: zod_1.z.number(),
+    expiresAt: zod_1.z.number().optional(),
+    nodeId: zod_1.z.string(),
+    clientFingerprint: zod_1.z.string().optional(),
+    transportState: exports.transportStateSchema.optional(),
+});
+exports.sessionJwtPayloadSchema = zod_1.z.object({
+    sid: zod_1.z.string(),
+    aid: zod_1.z.string(),
+    proto: exports.transportProtocolSchema,
+    nid: zod_1.z.string(),
+    iat: zod_1.z.number(),
+    exp: zod_1.z.number().optional(),
+});
+exports.statelessSessionJwtPayloadSchema = exports.sessionJwtPayloadSchema.extend({
+    state: zod_1.z.string().optional(),
+    tokens: zod_1.z.string().optional(),
+});
+exports.encryptedBlobSchema = zod_1.z.object({
+    alg: zod_1.z.literal('A256GCM'),
+    kid: zod_1.z.string().optional(),
+    iv: zod_1.z.string(),
+    tag: zod_1.z.string(),
+    data: zod_1.z.string(),
+    exp: zod_1.z.number().optional(),
+    meta: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+});
+exports.storedSessionSchema = zod_1.z.object({
+    session: exports.transportSessionSchema,
+    authorizationId: zod_1.z.string(),
+    tokens: zod_1.z.record(zod_1.z.string(), exports.encryptedBlobSchema).optional(),
+    createdAt: zod_1.z.number(),
+    lastAccessedAt: zod_1.z.number(),
+});
+exports.redisConfigSchema = zod_1.z.object({
+    host: zod_1.z.string(),
+    port: zod_1.z.number().optional().default(6379),
+    password: zod_1.z.string().optional(),
+    db: zod_1.z.number().optional().default(0),
+    tls: zod_1.z.boolean().optional().default(false),
+    keyPrefix: zod_1.z.string().optional().default('mcp:session:'),
+});
+// Stateful storage options (discriminated by store type)
+const statefulStorageSchema = zod_1.z.discriminatedUnion('store', [
+    zod_1.z.object({ store: zod_1.z.literal('memory') }),
+    zod_1.z.object({ store: zod_1.z.literal('redis'), config: exports.redisConfigSchema }),
+]);
+// Session storage config using union instead of discriminatedUnion
+// to avoid duplicate mode values
+exports.sessionStorageConfigSchema = zod_1.z.union([
+    zod_1.z.object({ mode: zod_1.z.literal('stateless') }),
+    zod_1.z.object({ mode: zod_1.z.literal('stateful') }).merge(statefulStorageSchema.options[0]),
+    zod_1.z.object({ mode: zod_1.z.literal('stateful') }).merge(statefulStorageSchema.options[1]),
+]);
+//# sourceMappingURL=transport-session.types.js.map

package/src/auth/session/transport-session.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport-session.types.js","sourceRoot":"","sources":["../../../../src/auth/session/transport-session.types.ts"],"names":[],"mappings":"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","sourcesContent":["// auth/session/transport-session.types.ts\n\nimport { z } from 'zod';\n\n/**\n * Transport protocol types supported by MCP\n * These are the actual transport protocols for sessions (excludes 'delete-session' action)\n */\nexport type TransportProtocol = 'legacy-sse' | 'sse' | 'streamable-http' | 'stateful-http' | 'stateless-http';\n\n/**\n * Session storage mode for distributed systems\n */\nexport type SessionStorageMode = 'stateless' | 'stateful';\n\n/**\n * TransportSession represents a single client connection.\n * Multiple sessions can share the same authorization.\n * Each session is bound to a specific transport protocol.\n */\nexport interface TransportSession {\n  /** Unique session ID (encrypted JWT or UUID) */\n  id: string;\n\n  /** Reference to the authorization this session uses */\n  authorizationId: string;\n\n  /** Transport protocol for this session */\n  protocol: TransportProtocol;\n\n  /** Session creation timestamp (epoch ms) */\n  createdAt: number;\n\n  /** Session expiration (epoch ms, independent of auth expiration) */\n  expiresAt?: number;\n\n  /** Node ID for distributed systems */\n  nodeId: string;\n\n  /** Client fingerprint for rate limiting/tracking */\n  clientFingerprint?: string;\n\n  /** Transport-specific state */\n  transportState?: TransportState;\n}\n\n/**\n * Transport-specific state that varies by protocol\n */\nexport type TransportState =\n  | SseTransportState\n  | StreamableHttpTransportState\n  | StatefulHttpTransportState\n  | StatelessHttpTransportState\n  | LegacySseTransportState;\n\n/**\n * SSE (Server-Sent Events) transport state\n */\nexport interface SseTransportState {\n  type: 'sse';\n  /** Last event ID for reconnection (per SSE spec) */\n  lastEventId?: string;\n  /** Connection keep-alive timestamp */\n  lastPing?: number;\n  /** Connection state */\n  connectionState?: 'connecting' | 'open' | 'closed';\n}\n\n/**\n * Streamable HTTP transport state\n */\nexport interface StreamableHttpTransportState {\n  type: 'streamable-http';\n  /** Request sequence number */\n  requestSeq: number;\n  /** Active stream ID if streaming */\n  activeStreamId?: string;\n  /** Pending request IDs */\n  pendingRequests?: string[];\n}\n\n/**\n * Stateful HTTP transport state\n */\nexport interface StatefulHttpTransportState {\n  type: 'stateful-http';\n  /** Request sequence number */\n  requestSeq: number;\n  /** Pending responses awaiting delivery */\n  pendingResponses?: string[];\n  /** Last activity timestamp */\n  lastActivity?: number;\n}\n\n/**\n * Stateless HTTP transport state\n */\nexport interface StatelessHttpTransportState {\n  type: 'stateless-http';\n  /** Request count for rate limiting */\n  requestCount: number;\n  /** Window start for rate limiting */\n  windowStart?: number;\n}\n\n/**\n * Legacy SSE transport state (for backwards compatibility)\n */\nexport interface LegacySseTransportState {\n  type: 'legacy-sse';\n  /** Message endpoint path */\n  messagePath: string;\n  /** Last event ID */\n  lastEventId?: string;\n  /** Connection state */\n  connectionState?: 'connecting' | 'open' | 'closed';\n}\n\n/**\n * Session JWT payload - encodes both auth ref and transport context\n * This is the structure encrypted in the mcp-session-id header\n */\nexport interface SessionJwtPayload {\n  /** Session ID (UUID) */\n  sid: string;\n  /** Authorization ID (token signature fingerprint) */\n  aid: string;\n  /** Transport protocol */\n  proto: TransportProtocol;\n  /** Node ID (for distributed systems) */\n  nid: string;\n  /** Issued at (epoch seconds) */\n  iat: number;\n  /** Expiration (epoch seconds) */\n  exp?: number;\n}\n\n/**\n * Extended session JWT payload for stateless mode\n * Includes encrypted state and tokens\n */\nexport interface StatelessSessionJwtPayload extends SessionJwtPayload {\n  /** Encrypted transport state (AES-256-GCM) */\n  state?: string;\n  /** Encrypted provider tokens (AES-256-GCM, for orchestrated mode) */\n  tokens?: string;\n}\n\n/**\n * Stored session record (for stateful mode in Redis/memory)\n */\nexport interface StoredSession {\n  /** The transport session data */\n  session: TransportSession;\n  /** Authorization ID reference */\n  authorizationId: string;\n  /** Encrypted provider tokens (for orchestrated mode) */\n  tokens?: Record<string, EncryptedBlob>;\n  /** Creation timestamp */\n  createdAt: number;\n  /** Last accessed timestamp */\n  lastAccessedAt: number;\n}\n\n/**\n * Encrypted blob structure (AES-256-GCM)\n */\nexport interface EncryptedBlob {\n  /** Algorithm identifier */\n  alg: 'A256GCM';\n  /** Key ID (for rotation) */\n  kid?: string;\n  /** Initialization vector (base64url) */\n  iv: string;\n  /** Authentication tag (base64url) */\n  tag: string;\n  /** Ciphertext (base64url) */\n  data: string;\n  /** Expiration hint (epoch seconds) */\n  exp?: number;\n  /** Additional metadata */\n  meta?: Record<string, unknown>;\n}\n\n/**\n * Session store interface for stateful sessions\n */\nexport interface SessionStore {\n  /**\n   * Get a stored session by ID\n   */\n  get(sessionId: string): Promise<StoredSession | null>;\n\n  /**\n   * Store a session with optional TTL\n   */\n  set(sessionId: string, session: StoredSession, ttlMs?: number): Promise<void>;\n\n  /**\n   * Delete a session\n   */\n  delete(sessionId: string): Promise<void>;\n\n  /**\n   * Check if a session exists\n   */\n  exists(sessionId: string): Promise<boolean>;\n\n  /**\n   * Allocate a new session ID\n   */\n  allocId(): string;\n}\n\n/**\n * Session storage configuration\n */\nexport type SessionStorageConfig =\n  | { mode: 'stateless' }\n  | { mode: 'stateful'; store: 'memory' }\n  | { mode: 'stateful'; store: 'redis'; config: RedisConfig };\n\n/**\n * Redis configuration\n */\nexport interface RedisConfig {\n  host: string;\n  port?: number;\n  password?: string;\n  db?: number;\n  tls?: boolean;\n  keyPrefix?: string;\n}\n\n// ============================================\n// Zod Schemas\n// ============================================\n\nexport const transportProtocolSchema = z.enum([\n  'legacy-sse',\n  'sse',\n  'streamable-http',\n  'stateful-http',\n  'stateless-http',\n]);\n\nexport const sseTransportStateSchema = z.object({\n  type: z.literal('sse'),\n  lastEventId: z.string().optional(),\n  lastPing: z.number().optional(),\n  connectionState: z.enum(['connecting', 'open', 'closed']).optional(),\n});\n\nexport const streamableHttpTransportStateSchema = z.object({\n  type: z.literal('streamable-http'),\n  requestSeq: z.number(),\n  activeStreamId: z.string().optional(),\n  pendingRequests: z.array(z.string()).optional(),\n});\n\nexport const statefulHttpTransportStateSchema = z.object({\n  type: z.literal('stateful-http'),\n  requestSeq: z.number(),\n  pendingResponses: z.array(z.string()).optional(),\n  lastActivity: z.number().optional(),\n});\n\nexport const statelessHttpTransportStateSchema = z.object({\n  type: z.literal('stateless-http'),\n  requestCount: z.number(),\n  windowStart: z.number().optional(),\n});\n\nexport const legacySseTransportStateSchema = z.object({\n  type: z.literal('legacy-sse'),\n  messagePath: z.string(),\n  lastEventId: z.string().optional(),\n  connectionState: z.enum(['connecting', 'open', 'closed']).optional(),\n});\n\nexport const transportStateSchema = z.discriminatedUnion('type', [\n  sseTransportStateSchema,\n  streamableHttpTransportStateSchema,\n  statefulHttpTransportStateSchema,\n  statelessHttpTransportStateSchema,\n  legacySseTransportStateSchema,\n]);\n\nexport const transportSessionSchema = z.object({\n  id: z.string(),\n  authorizationId: z.string(),\n  protocol: transportProtocolSchema,\n  createdAt: z.number(),\n  expiresAt: z.number().optional(),\n  nodeId: z.string(),\n  clientFingerprint: z.string().optional(),\n  transportState: transportStateSchema.optional(),\n});\n\nexport const sessionJwtPayloadSchema = z.object({\n  sid: z.string(),\n  aid: z.string(),\n  proto: transportProtocolSchema,\n  nid: z.string(),\n  iat: z.number(),\n  exp: z.number().optional(),\n});\n\nexport const statelessSessionJwtPayloadSchema = sessionJwtPayloadSchema.extend({\n  state: z.string().optional(),\n  tokens: z.string().optional(),\n});\n\nexport const encryptedBlobSchema = z.object({\n  alg: z.literal('A256GCM'),\n  kid: z.string().optional(),\n  iv: z.string(),\n  tag: z.string(),\n  data: z.string(),\n  exp: z.number().optional(),\n  meta: z.record(z.string(), z.unknown()).optional(),\n});\n\nexport const storedSessionSchema = z.object({\n  session: transportSessionSchema,\n  authorizationId: z.string(),\n  tokens: z.record(z.string(), encryptedBlobSchema).optional(),\n  createdAt: z.number(),\n  lastAccessedAt: z.number(),\n});\n\nexport const redisConfigSchema = z.object({\n  host: z.string(),\n  port: z.number().optional().default(6379),\n  password: z.string().optional(),\n  db: z.number().optional().default(0),\n  tls: z.boolean().optional().default(false),\n  keyPrefix: z.string().optional().default('mcp:session:'),\n});\n\n// Stateful storage options (discriminated by store type)\nconst statefulStorageSchema = z.discriminatedUnion('store', [\n  z.object({ store: z.literal('memory') }),\n  z.object({ store: z.literal('redis'), config: redisConfigSchema }),\n]);\n\n// Session storage config using union instead of discriminatedUnion\n// to avoid duplicate mode values\nexport const sessionStorageConfigSchema = z.union([\n  z.object({ mode: z.literal('stateless') }),\n  z.object({ mode: z.literal('stateful') }).merge(statefulStorageSchema.options[0]),\n  z.object({ mode: z.literal('stateful') }).merge(statefulStorageSchema.options[1]),\n]);\n"]}

package/src/auth/session/utils/session-id.utils.d.ts

@@ -1,5 +1,11 @@
-import { HttpRequestIntent, SessionIdPayload } from '../../../common';
+import { SessionIdPayload, TransportProtocolType } from '../../../common';
+import type { PlatformDetectionConfig } from '../../../common/types/options/session.options';
 export declare function encryptJson(obj: unknown): string;
+/**
+ * Decrypt a public session ID without signature verification.
+ * Public sessions use authSig: 'public' and isPublic: true
+ */
+export declare function decryptPublicSession(sessionId: string): SessionIdPayload | null;
 /**
  * Validates an existing session header OR creates a fresh one.
  * - Valid: nodeId matches local, authSig matches current Authorization
@@ -9,7 +15,13 @@ export declare function parseSessionHeader(sessionHeader: string | undefined, to
     id: string;
     payload: SessionIdPayload;
 } | undefined;
-export declare function createSessionId(protocol: HttpRequestIntent, token: string): {
+export interface CreateSessionOptions {
+    /** User-Agent header for pre-initialize platform detection */
+    userAgent?: string;
+    /** Platform detection configuration from scope */
+    platformDetectionConfig?: PlatformDetectionConfig;
+}
+export declare function createSessionId(protocol: TransportProtocolType, token: string, options?: CreateSessionOptions): {
     id: string;
     payload: SessionIdPayload;
 };