@frontmcp/auth 0.10.0 → 0.11.0

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

@@ -0,0 +1,479 @@
+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;
+    /** Whether the MCP protocol initialization handshake was completed */
+    initialized?: boolean;
+    /**
+     * Absolute maximum lifetime timestamp (epoch ms).
+     * Session is invalid after this time regardless of access patterns.
+     * This prevents indefinite session extension via sliding expiration.
+     */
+    maxLifetimeAt?: 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;
+    /** Default TTL in milliseconds for session extension on access (sliding expiration) */
+    defaultTtlMs?: number;
+}
+/**
+ * Security configuration options for session stores.
+ * These options enable additional security hardening features.
+ */
+export interface SessionSecurityConfig {
+    /**
+     * Default maximum session lifetime in milliseconds.
+     * Sessions will be invalidated after this time regardless of access.
+     * Set to prevent indefinite session extension via sliding expiration.
+     * @example 86400000 // 24 hours
+     */
+    maxLifetimeMs?: number;
+    /**
+     * Enable HMAC signing for stored sessions.
+     * When enabled, sessions are signed to detect tampering.
+     * Requires MCP_SESSION_SECRET environment variable or signing.secret config.
+     * @default false
+     */
+    enableSigning?: boolean;
+    /**
+     * Secret key for HMAC signing.
+     * If not provided, falls back to MCP_SESSION_SECRET environment variable.
+     */
+    signingSecret?: string;
+    /**
+     * Enable rate limiting for session lookups.
+     * Protects against session enumeration attacks.
+     * @default false
+     */
+    enableRateLimiting?: boolean;
+    /**
+     * Rate limiting configuration.
+     * Only used if enableRateLimiting is true.
+     */
+    rateLimiting?: {
+        /** Time window in milliseconds. @default 60000 */
+        windowMs?: number;
+        /** Maximum requests per window. @default 100 */
+        maxRequests?: number;
+    };
+}
+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 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;
+    initialized: z.ZodOptional<z.ZodBoolean>;
+    maxLifetimeAt: z.ZodOptional<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>>;
+    defaultTtlMs: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, z.core.$strip>;
+//# sourceMappingURL=transport-session.types.d.ts.map

package/session/transport-session.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport-session.types.d.ts","sourceRoot":"","sources":["../../src/session/transport-session.types.ts"],"names":[],"mappings":"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"}

package/session/utils/auth-token.utils.d.ts

@@ -0,0 +1,12 @@
+import { UserClaim } from '../../common/session.types';
+export declare function isJwt(token: string | undefined): boolean;
+/**
+ * If the token is a JWT, returns the raw signature segment (3rd part) as base64url.
+ * Otherwise, returns a stable SHA-256(base64url) fingerprint of the whole token,
+ * so we can still bind a session id to "this Authorization" deterministically.
+ */
+export declare function getTokenSignatureFingerprint(token: string): string;
+/** Best-effort typed user derivation from claims */
+export declare function deriveTypedUser(claims: Record<string, unknown>): UserClaim;
+export declare function extractBearerToken(header?: string): string | undefined;
+//# sourceMappingURL=auth-token.utils.d.ts.map

package/session/utils/auth-token.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-token.utils.d.ts","sourceRoot":"","sources":["../../../src/session/utils/auth-token.utils.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAGvD,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAGxD;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMlE;AAkBD,oDAAoD;AACpD,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAe1E;AAED,wBAAgB,kBAAkB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAItE"}

package/session/utils/index.d.ts

@@ -2,4 +2,6 @@
  * Session utilities
  */
 export { TinyTtlCache } from './tiny-ttl-cache';
+export { isJwt, getTokenSignatureFingerprint, deriveTypedUser, extractBearerToken } from './auth-token.utils';
+export { getKey, encryptJson, decryptSessionJson, safeDecrypt, resetCachedKey } from './session-crypto.utils';
 //# sourceMappingURL=index.d.ts.map

package/session/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/session/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/session/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,KAAK,EAAE,4BAA4B,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC9G,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,kBAAkB,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC"}

package/session/utils/session-crypto.utils.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Symmetric key derived from secret or machine id (stable for the process).
+ * Uses getMachineId() from authorization module as single source of truth.
+ *
+ * SECURITY: In production, MCP_SESSION_SECRET is REQUIRED.
+ * Falls back to getMachineId() only in development/test environments.
+ *
+ * @throws Error if MCP_SESSION_SECRET is not set in production
+ */
+export declare function getKey(): Uint8Array;
+/**
+ * Encrypt an object to a compact session ID format (iv.tag.ct).
+ */
+export declare function encryptJson(obj: unknown): string;
+/**
+ * Low-level decryption that returns the raw JSON payload or null if the
+ * session ID format is invalid. Crypto/parsing errors may throw; use
+ * {@link safeDecrypt} for a version that catches all errors and returns null.
+ */
+export declare function decryptSessionJson(sessionId: string): unknown;
+/**
+ * Safe wrapper around decryptSessionJson that catches crypto/parse errors.
+ */
+export declare function safeDecrypt(sessionId: string): unknown;
+/**
+ * Reset the cached key. Useful for testing.
+ * @internal
+ */
+export declare function resetCachedKey(): void;
+//# sourceMappingURL=session-crypto.utils.d.ts.map

package/session/utils/session-crypto.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-crypto.utils.d.ts","sourceRoot":"","sources":["../../../src/session/utils/session-crypto.utils.ts"],"names":[],"mappings":"AAYA;;;;;;;;GAQG;AACH,wBAAgB,MAAM,IAAI,UAAU,CAqBnC;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAKhD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAS7D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAMtD;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAErC"}

package/session/vercel-kv-session.store.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Vercel KV Session Store
+ *
+ * Session store implementation using Vercel KV (edge-compatible REST-based key-value store).
+ * Uses @frontmcp/utils VercelKvStorageAdapter internally.
+ *
+ * @warning **Atomicity Limitation**: Vercel KV does not support atomic GET+EXPIRE (GETEX).
+ * The `get()` method uses separate GET and EXPIRE calls, creating a small race window
+ * where the session could expire between these two operations. For mission-critical
+ * session handling requiring strict atomicity guarantees, consider using Redis directly
+ * via `RedisSessionStore`.
+ *
+ * @see https://vercel.com/docs/storage/vercel-kv
+ */
+import { SessionStore, StoredSession, SessionSecurityConfig } from './transport-session.types';
+import type { AuthLogger } from '../common/auth-logger.interface';
+export interface VercelKvSessionConfig {
+    /**
+     * KV REST API URL
+     * @default process.env.KV_REST_API_URL
+     */
+    url?: string;
+    /**
+     * KV REST API Token
+     * @default process.env.KV_REST_API_TOKEN
+     */
+    token?: string;
+    /**
+     * Key prefix for session keys
+     * @default 'mcp:session:'
+     */
+    keyPrefix?: string;
+    /**
+     * Default TTL in milliseconds for session extension on access
+     * @default 3600000 (1 hour)
+     */
+    defaultTtlMs?: number;
+    /**
+     * Security hardening options
+     */
+    security?: SessionSecurityConfig;
+}
+/**
+ * Vercel KV-backed session store implementation
+ *
+ * Provides persistent session storage for edge deployments using Vercel KV.
+ * Sessions are stored as JSON with optional TTL.
+ * Uses @frontmcp/utils VercelKvStorageAdapter internally.
+ */
+export declare class VercelKvSessionStore implements SessionStore {
+    private readonly storage;
+    private readonly keyPrefix;
+    private readonly defaultTtlMs;
+    private readonly logger?;
+    private readonly security;
+    private readonly rateLimiter?;
+    constructor(config: VercelKvSessionConfig | {
+        provider?: string;
+        url?: string;
+        token?: string;
+        keyPrefix?: string;
+        defaultTtlMs?: number;
+        security?: SessionSecurityConfig;
+    }, logger?: AuthLogger);
+    /**
+     * Validate session ID
+     * @throws Error if sessionId is empty
+     */
+    private validateSessionId;
+    /**
+     * Connect to Vercel KV
+     * Thread-safe: concurrent calls will share the same connection via adapter.
+     */
+    connect(): Promise<void>;
+    /**
+     * Ensure the storage adapter is connected
+     */
+    private ensureConnected;
+    /**
+     * Get a stored session by ID
+     *
+     * Note: Vercel KV doesn't support GETEX, so we use GET + EXPIRE separately.
+     * This is slightly less atomic than Redis GETEX but sufficient for most use cases.
+     *
+     * @param sessionId - The session ID to look up
+     * @param options - Optional parameters for rate limiting
+     * @param options.clientIdentifier - Client identifier (e.g., IP address) for rate limiting.
+     *   When provided, rate limiting is applied per-client to prevent session enumeration.
+     *   If not provided, falls back to sessionId which provides DoS protection per-session.
+     */
+    get(sessionId: string, options?: {
+        clientIdentifier?: 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;
+    /**
+     * Disconnect from Vercel KV
+     * Vercel KV uses REST API, so this just clears internal state
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Test Vercel KV connection by checking if we can access the API.
+     * Useful for validating connection on startup.
+     *
+     * @returns true if connection is healthy, false otherwise
+     */
+    ping(): Promise<boolean>;
+}
+//# sourceMappingURL=vercel-kv-session.store.d.ts.map

package/session/vercel-kv-session.store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vercel-kv-session.store.d.ts","sourceRoot":"","sources":["../../src/session/vercel-kv-session.store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAuB,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AACpH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAKlE,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,EAAE,qBAAqB,CAAC;CAClC;AAED;;;;;;GAMG;AACH,qBAAa,oBAAqB,YAAW,YAAY;IACvD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAa;IAGrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwB;IACjD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAqB;gBAGhD,MAAM,EACF,qBAAqB,GACrB;QACE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,EAAE,qBAAqB,CAAC;KAClC,EACL,MAAM,CAAC,EAAE,UAAU;IAyBrB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAMzB;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAK9B;;OAEG;YACW,eAAe;IAK7B;;;;;;;;;;;OAWG;IACG,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAsHpG;;OAEG;IACG,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BnF;;OAEG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM9C;;OAEG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAMjD;;OAEG;IACH,OAAO,IAAI,MAAM;IAIjB;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAIjC;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;CAW/B"}