@frontmcp/sdk 0.6.1 → 0.6.3

package/{src/auth → auth}/instances/instance.local-primary-auth.d.ts

@@ -1,6 +1,6 @@
 import { URL } from 'url';
 import { FrontMcpAuth, FrontMcpLogger, ScopeEntry, ServerRequest, JWK } from '../../common';
-import { PublicAuthOptions, OrchestratedLocalOptions, OrchestratedRemoteOptions } from '../../common/types/options/auth.options';
+import { PublicAuthOptions, OrchestratedLocalOptions, OrchestratedRemoteOptions } from '../../common/types/options/auth';
 import ProviderRegistry from '../../provider/provider.registry';
 import { AuthorizationStore } from '../session/authorization.store';
 /**

package/{src/auth → auth}/instances/instance.remote-primary-auth.d.ts

@@ -1,5 +1,5 @@
 import { FrontMcpAuth, ScopeEntry, ServerRequest } from '../../common';
-import { TransparentAuthOptions } from '../../common/types/options/auth.options';
+import { TransparentAuthOptions } from '../../common/types/options/auth';
 import { URL } from 'url';
 import ProviderRegistry from '../../provider/provider.registry';
 export declare class RemotePrimaryAuth extends FrontMcpAuth<TransparentAuthOptions> {

package/auth/session/index.d.ts

@@ -0,0 +1,8 @@
+export * from './transport-session.types';
+export { TransportSessionManager, InMemorySessionStore } from './transport-session.manager';
+export { RedisSessionStore, RedisSessionStoreConfig } from './redis-session.store';
+export { VercelKvSessionStore, VercelKvSessionConfig } from './vercel-kv-session.store';
+export { SessionRateLimiter, SessionRateLimiterConfig, RateLimitResult, defaultSessionRateLimiter, } from './session-rate-limiter';
+export { signSession, verifySession, verifyOrParseSession, isSignedSession, SignedSession, SessionSigningConfig, } from './session-crypto';
+export * from './authorization.store';
+export * from './authorization-vault';

package/{src/auth → auth}/session/redis-session.store.d.ts

@@ -1,11 +1,23 @@
 import { Redis } from 'ioredis';
-import { SessionStore, StoredSession, RedisConfig } from './transport-session.types';
+import { SessionStore, StoredSession, RedisConfig, SessionSecurityConfig } from './transport-session.types';
 import { FrontMcpLogger } from '../../common/interfaces/logger.interface';
+/**
+ * Extended Redis configuration with security options.
+ */
+export interface RedisSessionStoreConfig extends RedisConfig {
+    /** Security hardening options */
+    security?: SessionSecurityConfig;
+}
 /**
  * Redis-backed session store implementation
  *
  * Provides persistent session storage for distributed deployments.
  * Sessions are stored as JSON with optional TTL.
+ *
+ * Security features (configurable via security option):
+ * - HMAC signing: Detects session data tampering
+ * - Rate limiting: Prevents session enumeration attacks
+ * - Max lifetime: Prevents indefinite session extension
  */
 export declare class RedisSessionStore implements SessionStore {
     private readonly redis;
@@ -13,10 +25,13 @@ export declare class RedisSessionStore implements SessionStore {
     private readonly defaultTtlMs;
     private readonly logger?;
     private externalInstance;
-    constructor(config: RedisConfig | {
+    private readonly security;
+    private readonly rateLimiter?;
+    constructor(config: RedisSessionStoreConfig | {
         redis: Redis;
         keyPrefix?: string;
         defaultTtlMs?: number;
+        security?: SessionSecurityConfig;
     }, logger?: FrontMcpLogger);
     /**
      * Get the full Redis key for a session ID
@@ -28,8 +43,16 @@ export declare class RedisSessionStore implements SessionStore {
      *
      * Note: Uses atomic GETEX to extend TTL while reading, preventing race conditions
      * where concurrent readers might resurrect expired sessions.
+     *
+     * @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): Promise<StoredSession | null>;
+    get(sessionId: string, options?: {
+        clientIdentifier?: string;
+    }): Promise<StoredSession | null>;
     /**
      * Store a session with optional TTL
      */

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

@@ -0,0 +1,86 @@
+/**
+ * Session Cryptographic Utilities
+ *
+ * Provides HMAC signing and verification for stored session data.
+ * Protects against session data tampering when stored in external
+ * systems like Redis that don't provide application-level integrity.
+ */
+import type { StoredSession } from './transport-session.types';
+/**
+ * Signed session wrapper structure.
+ * Contains the session data and its HMAC signature.
+ */
+export interface SignedSession {
+    /** The session data */
+    data: StoredSession;
+    /** HMAC-SHA256 signature in base64url format */
+    sig: string;
+    /** Signature version for future algorithm changes */
+    v: 1;
+}
+/**
+ * Configuration for session signing.
+ */
+export interface SessionSigningConfig {
+    /**
+     * The secret key used for HMAC signing.
+     * Should be at least 32 bytes for security.
+     * Uses MCP_SESSION_SECRET environment variable if not provided.
+     */
+    secret?: string;
+}
+/**
+ * Sign a stored session with HMAC-SHA256.
+ *
+ * Creates a tamper-evident wrapper around the session data.
+ * Any modification to the session will invalidate the signature.
+ *
+ * @param session - The session to sign
+ * @param config - Optional signing configuration
+ * @returns JSON string containing signed session
+ *
+ * @example
+ * ```typescript
+ * const signed = signSession(session);
+ * await redis.set(key, signed);
+ * ```
+ */
+export declare function signSession(session: StoredSession, config?: SessionSigningConfig): string;
+/**
+ * Verify and extract a signed session.
+ *
+ * Validates the HMAC signature and returns the session if valid.
+ * Returns null if the signature is invalid or the data is corrupted.
+ *
+ * @param signedData - JSON string from signSession()
+ * @param config - Optional signing configuration
+ * @returns The verified session or null if invalid
+ *
+ * @example
+ * ```typescript
+ * const raw = await redis.get(key);
+ * const session = verifySession(raw);
+ * if (!session) {
+ *   // Session was tampered with or corrupted
+ *   await redis.del(key);
+ * }
+ * ```
+ */
+export declare function verifySession(signedData: string, config?: SessionSigningConfig): StoredSession | null;
+/**
+ * Check if a stored value is a signed session.
+ * Useful for migrating from unsigned to signed sessions.
+ *
+ * @param data - Raw data from storage
+ * @returns true if the data appears to be a signed session
+ */
+export declare function isSignedSession(data: string): boolean;
+/**
+ * Verify or parse a session, supporting both signed and unsigned formats.
+ * Useful for backwards compatibility during migration.
+ *
+ * @param data - Raw data from storage
+ * @param config - Optional signing configuration
+ * @returns The session (verified if signed, parsed if unsigned) or null
+ */
+export declare function verifyOrParseSession(data: string, config?: SessionSigningConfig): StoredSession | null;

package/auth/session/session-rate-limiter.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Session Rate Limiter
+ *
+ * Simple sliding window rate limiter for session lookup operations.
+ * Protects against session enumeration attacks by limiting the rate
+ * of session lookups per client IP or identifier.
+ */
+export interface SessionRateLimiterConfig {
+    /**
+     * Time window in milliseconds for rate limiting.
+     * @default 60000 (1 minute)
+     */
+    windowMs?: number;
+    /**
+     * Maximum requests allowed per window per key.
+     * @default 100
+     */
+    maxRequests?: number;
+    /**
+     * Interval in milliseconds for automatic cleanup of expired entries.
+     * Set to 0 to disable automatic cleanup.
+     * @default 60000 (1 minute)
+     */
+    cleanupIntervalMs?: number;
+}
+export interface RateLimitResult {
+    /** Whether the request is allowed */
+    allowed: boolean;
+    /** Number of remaining requests in the current window */
+    remaining: number;
+    /** Timestamp when the rate limit resets (epoch ms) */
+    resetAt: number;
+    /** Time to wait before retry (only set if not allowed) */
+    retryAfterMs?: number;
+}
+/**
+ * Sliding window rate limiter for session operations.
+ *
+ * Uses an in-memory sliding window algorithm to track request timestamps
+ * per key (typically client IP). Automatically cleans up expired entries.
+ *
+ * @example
+ * ```typescript
+ * const rateLimiter = new SessionRateLimiter({ maxRequests: 50, windowMs: 60000 });
+ *
+ * // In session store get()
+ * const clientIp = getClientIp(req);
+ * const result = rateLimiter.check(clientIp);
+ * if (!result.allowed) {
+ *   throw new Error(`Rate limit exceeded. Retry after ${result.retryAfterMs}ms`);
+ * }
+ * ```
+ */
+export declare class SessionRateLimiter {
+    private readonly windowMs;
+    private readonly maxRequests;
+    private readonly requests;
+    private cleanupTimer;
+    constructor(config?: SessionRateLimiterConfig);
+    /**
+     * Check if a request is allowed for the given key.
+     *
+     * @param key - Identifier for rate limiting (e.g., client IP, session ID prefix)
+     * @returns Rate limit result with allowed status and metadata
+     */
+    check(key: string): RateLimitResult;
+    /**
+     * Check if a request would be allowed without recording it.
+     * Useful for pre-checking without consuming quota.
+     *
+     * @param key - Identifier for rate limiting
+     * @returns true if request would be allowed
+     */
+    wouldAllow(key: string): boolean;
+    /**
+     * Reset rate limit for a specific key.
+     * Useful for testing or after successful authentication.
+     *
+     * @param key - Identifier to reset
+     */
+    reset(key: string): void;
+    /**
+     * Clean up expired entries from all keys.
+     * Called automatically on configured interval, but can be called manually.
+     */
+    cleanup(): void;
+    /**
+     * Get current statistics for monitoring.
+     */
+    getStats(): {
+        totalKeys: number;
+        totalRequests: number;
+    };
+    /**
+     * Stop the automatic cleanup timer.
+     * Call this when disposing of the rate limiter.
+     */
+    dispose(): void;
+}
+/**
+ * Default shared rate limiter instance for simple single-process scenarios.
+ *
+ * WARNING: This singleton shares state across all usages in the same process.
+ * For most use cases, create a new SessionRateLimiter instance per session store.
+ *
+ * @example
+ * // Preferred: Create instance per store
+ * this.rateLimiter = new SessionRateLimiter({ windowMs: 60000, maxRequests: 100 });
+ *
+ * // Only use default for simple single-tenant scenarios
+ * import { defaultSessionRateLimiter } from './session-rate-limiter';
+ */
+export declare const defaultSessionRateLimiter: SessionRateLimiter;

package/{src/auth → auth}/session/transport-session.types.d.ts

@@ -135,6 +135,14 @@ export interface StoredSession {
     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)
@@ -206,6 +214,47 @@ export interface RedisConfig {
     /** 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";
@@ -345,22 +394,6 @@ export declare const sessionJwtPayloadSchema: z.ZodObject<{
     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>;
@@ -431,6 +464,8 @@ export declare const storedSessionSchema: z.ZodObject<{
     }, 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;
@@ -441,21 +476,3 @@ export declare const redisConfigSchema: z.ZodObject<{
     keyPrefix: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     defaultTtlMs: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
 }, 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>>;
-        defaultTtlMs: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
-    }, z.core.$strip>;
-}, z.core.$strip>]>;

package/{src/auth → auth}/session/vercel-kv-session.store.d.ts

@@ -4,9 +4,15 @@
  * Session store implementation using Vercel KV (edge-compatible REST-based key-value store).
  * Uses dynamic import to avoid bundling @vercel/kv for non-Vercel deployments.
  *
+ * @warning **Atomicity Limitation**: Vercel KV does not support atomic GET+EXPIRE (GETEX).
+ * The `get()` method uses separate GET and PEXPIRE 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 } from './transport-session.types';
+import { SessionStore, StoredSession, SessionSecurityConfig } from './transport-session.types';
 import { FrontMcpLogger } from '../../common/interfaces/logger.interface';
 import type { VercelKvProviderOptions } from '../../common/types/options/redis.options';
 export interface VercelKvSessionConfig {
@@ -30,6 +36,10 @@ export interface VercelKvSessionConfig {
      * @default 3600000 (1 hour)
      */
     defaultTtlMs?: number;
+    /**
+     * Security hardening options
+     */
+    security?: SessionSecurityConfig;
 }
 /**
  * Vercel KV-backed session store implementation
@@ -44,6 +54,8 @@ export declare class VercelKvSessionStore implements SessionStore {
     private readonly defaultTtlMs;
     private readonly logger?;
     private readonly config;
+    private readonly security;
+    private readonly rateLimiter?;
     constructor(config: VercelKvSessionConfig | VercelKvProviderOptions, logger?: FrontMcpLogger);
     /**
      * Connect to Vercel KV
@@ -63,8 +75,16 @@ export declare class VercelKvSessionStore implements SessionStore {
      *
      * Note: Vercel KV doesn't support GETEX, so we use GET + PEXPIRE 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): Promise<StoredSession | null>;
+    get(sessionId: string, options?: {
+        clientIdentifier?: string;
+    }): Promise<StoredSession | null>;
     /**
      * Store a session with optional TTL
      */

package/{src/common → common}/interfaces/internal/primary-auth-provider.interface.d.ts

@@ -26,13 +26,10 @@ export declare abstract class FrontMcpAuth<Options extends AuthOptions = AuthOpt
     abstract fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
     abstract validate(request: ServerRequest): Promise<void>;
     abstract get issuer(): string;
-    /**
-     * Default transport configuration when not specified
-     */
-    private static readonly DEFAULT_TRANSPORT;
     /**
      * Get transport configuration with all defaults applied.
      * Returns default values when transport is not configured.
+     * Uses DEFAULT_TRANSPORT_CONFIG as single source of truth for defaults.
      */
     get transport(): TransportConfig;
 }