@frontmcp/auth 0.10.0 → 0.11.1

package/session/redis-session.store.d.ts

@@ -0,0 +1,93 @@
+import type { Redis } from 'ioredis';
+import { SessionStore, StoredSession, RedisConfig, SessionSecurityConfig } from './transport-session.types';
+import type { AuthLogger } from '../common/auth-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.
+ * Uses @frontmcp/utils RedisStorageAdapter internally.
+ *
+ * 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 storage;
+    private readonly keyPrefix;
+    private readonly defaultTtlMs;
+    private readonly logger?;
+    private externalInstance;
+    private readonly security;
+    private readonly rateLimiter?;
+    constructor(config: RedisSessionStoreConfig | {
+        redis: Redis;
+        keyPrefix?: string;
+        defaultTtlMs?: number;
+        security?: SessionSecurityConfig;
+    }, logger?: AuthLogger);
+    /**
+     * Get the full key for a session ID (without prefix, adapter handles it)
+     * @throws Error if sessionId is empty
+     */
+    private validateSessionId;
+    /**
+     * Ensure the storage adapter is connected
+     */
+    private ensureConnected;
+    /**
+     * Get a stored session by ID
+     *
+     * 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, 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 Redis (only if we created the connection)
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Get the underlying Redis client (for advanced use cases)
+     */
+    getRedisClient(): Redis | undefined;
+    /**
+     * Test Redis connection by sending a PING command.
+     * Useful for validating connection on startup.
+     *
+     * @returns true if connection is healthy, false otherwise
+     */
+    ping(): Promise<boolean>;
+}
+//# sourceMappingURL=redis-session.store.d.ts.map

package/session/redis-session.store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-session.store.d.ts","sourceRoot":"","sources":["../../src/session/redis-session.store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC,OAAO,EACL,YAAY,EACZ,aAAa,EACb,WAAW,EAEX,qBAAqB,EACtB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAKlE;;GAEG;AACH,MAAM,WAAW,uBAAwB,SAAQ,WAAW;IAC1D,iCAAiC;IACjC,QAAQ,CAAC,EAAE,qBAAqB,CAAC;CAClC;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,iBAAkB,YAAW,YAAY;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAa;IACrC,OAAO,CAAC,gBAAgB,CAAS;IAGjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwB;IACjD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAqB;gBAGhD,MAAM,EACF,uBAAuB,GACvB;QAAE,KAAK,EAAE,KAAK,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,qBAAqB,CAAA;KAAE,EACjG,MAAM,CAAC,EAAE,UAAU;IAyCrB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAMzB;;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;IAuIpG;;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;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAMjC;;OAEG;IACH,cAAc,IAAI,KAAK,GAAG,SAAS;IAInC;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;CAW/B"}

package/session/session-crypto.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 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.
+ *
+ * This module wraps the generic @frontmcp/utils HMAC signing utilities
+ * with session-specific types and environment-based secret handling.
+ */
+import { isSignedData, type SignedData } from '@frontmcp/utils';
+import type { StoredSession } from './transport-session.types';
+/**
+ * Signed session wrapper structure.
+ * Contains the session data and its HMAC signature.
+ */
+export type SignedSession = SignedData<StoredSession>;
+/**
+ * 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 { isSignedData as isSignedSession };
+/**
+ * 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;
+//# sourceMappingURL=session-crypto.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-crypto.d.ts","sourceRoot":"","sources":["../../src/session/session-crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAGL,YAAY,EAEZ,KAAK,UAAU,EAEhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAG/D;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,aAAa,CAAC,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA4BD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,CAAC,EAAE,oBAAoB,GAAG,MAAM,CAEzF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,oBAAoB,GAAG,aAAa,GAAG,IAAI,CAErG;AAED;;;;;;GAMG;AACH,OAAO,EAAE,YAAY,IAAI,eAAe,EAAE,CAAC;AAE3C;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,oBAAoB,GAAG,aAAa,GAAG,IAAI,CAEtG"}

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

@@ -0,0 +1,114 @@
+/**
+ * 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 RateLimitError(Math.ceil(result.retryAfterMs / 1000));
+ * }
+ * ```
+ */
+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;
+//# sourceMappingURL=session-rate-limiter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-rate-limiter.d.ts","sourceRoot":"","sources":["../../src/session/session-rate-limiter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,eAAe;IAC9B,qCAAqC;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoC;IAC7D,OAAO,CAAC,YAAY,CAA+B;gBAEvC,MAAM,GAAE,wBAA6B;IAajD;;;;;OAKG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe;IAuCnC;;;;;;OAMG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAWhC;;;;;OAKG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIxB;;;OAGG;IACH,OAAO,IAAI,IAAI;IAcf;;OAEG;IACH,QAAQ,IAAI;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE;IAWxD;;;OAGG;IACH,OAAO,IAAI,IAAI;CAOhB;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,oBAA2B,CAAC"}

package/session/session.transport.d.ts

@@ -0,0 +1,11 @@
+export declare class TransportIdGenerator {
+    /**
+     * Create a transport session ID.
+     * Always generates JWT-style IDs for distributed session support.
+     *
+     * @param _mode - Deprecated parameter, kept for backwards compatibility
+     * @returns A JWT-style transport session ID (UUID without dashes)
+     */
+    static createId(_mode?: 'jwt'): string;
+}
+//# sourceMappingURL=session.transport.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session.transport.d.ts","sourceRoot":"","sources":["../../src/session/session.transport.ts"],"names":[],"mappings":"AAGA,qBAAa,oBAAoB;IAC/B;;;;;;OAMG;IACH,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM;CAIvC"}

package/session/session.types.d.ts

@@ -0,0 +1,66 @@
+import { SessionUser } from '../common/session-user.types';
+/** Session mode identifier. */
+export type SessionMode = 'mcp';
+/**
+ * How a single provider's access token is represented inside the session payload.
+ */
+export type ProviderEmbedMode = 'store-only' | 'encrypted' | 'plain' | 'ref';
+/** AES-256-GCM encrypted blob, base64url fields. */
+export type EncBlob = {
+    alg: 'A256GCM';
+    iv: string;
+    tag: string;
+    data: string;
+};
+export type ProviderSnapshot = {
+    id: string;
+    exp?: number;
+    payload?: Record<string, unknown>;
+    apps?: Array<{
+        id: string;
+        toolIds?: string[];
+    }>;
+    embedMode: ProviderEmbedMode;
+    token?: string;
+    tokenEnc?: {
+        alg: 'A256GCM';
+        iv: string;
+        tag: string;
+        data: string;
+    };
+    refreshTokenEnc?: {
+        alg: 'A256GCM';
+        iv: string;
+        tag: string;
+        data: string;
+    };
+    secretRefId?: string;
+    refreshRefId?: string;
+};
+/** Arguments required to create a session from verified auth data. */
+export type CreateSessionArgs = {
+    token: string;
+    sessionId?: string;
+    claims: Record<string, unknown>;
+    user: SessionUser;
+    authorizedProviders?: Record<string, ProviderSnapshot>;
+    authorizedProviderIds?: string[];
+    authorizedApps?: Record<string, {
+        id: string;
+        toolIds: string[];
+    }>;
+    authorizedAppIds?: string[];
+    authorizedResources?: string[];
+    scopes?: string[];
+    authorizedTools?: Record<string, {
+        executionPath: [string, string];
+        details?: Record<string, unknown>;
+    }>;
+    authorizedToolIds?: string[];
+    authorizedPrompts?: Record<string, {
+        executionPath: [string, string];
+        details?: Record<string, unknown>;
+    }>;
+    authorizedPromptIds?: string[];
+};
+//# sourceMappingURL=session.types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session.types.d.ts","sourceRoot":"","sources":["../../src/session/session.types.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAE3D,+BAA+B;AAC/B,MAAM,MAAM,WAAW,GAAG,KAAK,CAAC;AAEhC;;GAEG;AACH,MAAM,MAAM,iBAAiB,GACzB,YAAY,GACZ,WAAW,GACX,OAAO,GACP,KAAK,CAAC;AAEV,oDAAoD;AACpD,MAAM,MAAM,OAAO,GAAG;IAAE,GAAG,EAAE,SAAS,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,IAAI,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IACjD,SAAS,EAAE,iBAAiB,CAAC;IAG7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE;QAAE,GAAG,EAAE,SAAS,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACrE,eAAe,CAAC,EAAE;QAAE,GAAG,EAAE,SAAS,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAG5E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,sEAAsE;AACtE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,IAAI,EAAE,WAAW,CAAC;IAElB,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IACvD,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IACnE,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAElB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,aAAa,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IACzG,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,aAAa,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC3G,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;CAChC,CAAC"}

package/session/token.refresh.d.ts

@@ -0,0 +1,61 @@
+import type { ProviderSnapshot } from './session.types';
+import type { TokenStore } from './token.store';
+import type { TokenVault } from './token.vault';
+export type TokenRefreshCtx = {
+    /** The provider we're refreshing for. */
+    providerId: string;
+    /** Caller-provided session facade (only what a refresher may need). */
+    session: {
+        id: string;
+        scopeId: string;
+        /** Current snapshot (mutable by the session after refresh). */
+        authorizedProviders: Record<string, ProviderSnapshot>;
+        /** Optional helper if the refresher wants to call other providers. */
+        getToken?: (pid: string, opts?: {
+            refreshSkewSec?: number;
+            forceRefresh?: boolean;
+        }) => Promise<string | undefined>;
+    };
+    /** Current access token (if known); may be undefined/expired. */
+    accessToken?: string;
+    /**
+     * Refresh token (if accessible by the embedding mode).
+     * For `ref` mode this is usually `undefined`; the refresher should use `store`/`vault`.
+     */
+    refreshToken?: string;
+    /** The snapshot we're refreshing (same as authorizedProviders[providerId]). */
+    snapshot: ProviderSnapshot;
+    /**
+     * External storage interfaces, present for `ref` mode to avoid revealing plaintext tokens.
+     * - `store` holds opaque encrypted blobs
+     * - `vault` handles AEAD encryption/decryption of secrets
+     */
+    store?: TokenStore;
+    vault?: TokenVault;
+};
+export type TokenRefreshResult = {
+    /** New access token (if rotated). */
+    accessToken?: string;
+    /** New refresh token (optional). */
+    refreshToken?: string;
+    /** New absolute expiry (seconds since epoch preferred; ms also accepted). */
+    exp: number;
+    /** Optional opaque payload returned by the AS (id_token claims, etc.). */
+    payload?: Record<string, unknown>;
+};
+export type TokenRefresher = (ctx: TokenRefreshCtx) => Promise<TokenRefreshResult>;
+/** Convert seconds/ms epoch or Date to epoch seconds. */
+export declare function toEpochSeconds(exp?: number | Date): number | undefined;
+/** Returns true if `exp` will occur within `skewSec` from now (or already past). */
+export declare function isSoonExpiring(exp?: number | Date, skewSec?: number): boolean;
+/**
+ * Synchronous check against a provider snapshot's `exp` field.
+ * Note: In `ref` mode the exact expiry may live in the store; this helper
+ * intentionally remains synchronous and only uses the snapshot's `exp`.
+ */
+export declare function isSoonExpiringProvider(sessionLike: {
+    authorizedProviders: Record<string, ProviderSnapshot>;
+}, providerId: string, skewSec?: number): boolean;
+/** Best-effort extraction of `exp` from a JWT without verification. */
+export declare function tryJwtExp(token?: string): number | undefined;
+//# sourceMappingURL=token.refresh.d.ts.map

package/session/token.refresh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.refresh.d.ts","sourceRoot":"","sources":["../../src/session/token.refresh.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAOhD,MAAM,MAAM,eAAe,GAAG;IAC5B,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;IAEnB,uEAAuE;IACvE,OAAO,EAAE;QACP,EAAE,EAAE,MAAM,CAAC;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,+DAA+D;QAC/D,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;QACtD,sEAAsE;QACtE,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;YAAE,cAAc,CAAC,EAAE,MAAM,CAAC;YAAC,YAAY,CAAC,EAAE,OAAO,CAAA;SAAE,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;KACrH,CAAC;IAEF,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,+EAA+E;IAC/E,QAAQ,EAAE,gBAAgB,CAAC;IAE3B;;;;OAIG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,qCAAqC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,GAAG,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAMnF,yDAAyD;AACzD,wBAAgB,cAAc,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAKtE;AAED,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,SAAK,GAAG,OAAO,CAKzE;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE;IAAE,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;CAAE,EACtE,UAAU,EAAE,MAAM,EAClB,OAAO,SAAK,GACX,OAAO,CAIT;AAMD,uEAAuE;AACvE,wBAAgB,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAW5D"}