@frontmcp/sdk 0.7.2 → 0.8.0

package/elicitation/store/elicitation-store.factory.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Elicitation Store Factory
+ *
+ * Factory functions for creating elicitation stores using @frontmcp/utils storage.
+ * Supports Memory, Redis, and Upstash backends with automatic detection.
+ *
+ * Note: Vercel KV is NOT supported for elicitation because it doesn't support pub/sub
+ * operations which are required for cross-node result routing.
+ *
+ * @module elicitation/store/elicitation-store.factory
+ */
+import type { StorageConfig, RootStorage } from '@frontmcp/utils';
+import type { FrontMcpLogger, RedisOptionsInput } from '../../common';
+import type { ElicitationStore } from './elicitation.store';
+/**
+ * Options for creating an elicitation store.
+ */
+export interface ElicitationStoreOptions {
+    /**
+     * Storage configuration for the elicitation store.
+     * Uses @frontmcp/utils storage configuration format.
+     *
+     * @example Auto-detect
+     * ```typescript
+     * { type: 'auto' }
+     * ```
+     *
+     * @example Redis
+     * ```typescript
+     * {
+     *   type: 'redis',
+     *   redis: { url: 'redis://localhost:6379' }
+     * }
+     * ```
+     *
+     * @example Upstash
+     * ```typescript
+     * {
+     *   type: 'upstash',
+     *   upstash: { enablePubSub: true }
+     * }
+     * ```
+     */
+    storage?: StorageConfig;
+    /**
+     * Redis configuration for distributed deployments.
+     * This is a convenience option that maps to storage.redis.
+     * For new code, prefer using the `storage` option directly.
+     */
+    redis?: RedisOptionsInput;
+    /**
+     * Key prefix for all elicitation keys.
+     * @default 'mcp:elicit:'
+     */
+    keyPrefix?: string;
+    /**
+     * Logger instance for store operations.
+     */
+    logger?: FrontMcpLogger;
+    /**
+     * Whether running in Edge runtime (requires distributed storage).
+     * @default false
+     */
+    isEdgeRuntime?: boolean;
+    /**
+     * Whether to require pub/sub support.
+     * If true, will throw if the storage backend doesn't support pub/sub.
+     * @default true
+     */
+    requiresPubSub?: boolean;
+    /**
+     * Encryption configuration for elicitation data.
+     *
+     * When enabled, all elicitation data is encrypted using session-derived keys.
+     * This ensures that only requests with the actual sessionId can decrypt the data.
+     *
+     * @example Enable encryption (auto-detect secret from env)
+     * ```typescript
+     * { encryption: { enabled: true } }
+     * ```
+     *
+     * @example Explicit secret
+     * ```typescript
+     * { encryption: { enabled: true, secret: 'my-secret-key' } }
+     * ```
+     */
+    encryption?: {
+        /**
+         * Whether encryption is enabled.
+         * - true: Always encrypt (throws if no secret available)
+         * - false: Never encrypt
+         * - 'auto': Encrypt if secret is available (default)
+         * @default 'auto'
+         */
+        enabled?: boolean | 'auto';
+        /**
+         * Server secret for key derivation.
+         * Falls back to MCP_ELICITATION_SECRET, MCP_SESSION_SECRET, or MCP_SERVER_SECRET env vars.
+         */
+        secret?: string;
+    };
+}
+/**
+ * Result of creating an elicitation store.
+ */
+export interface ElicitationStoreResult {
+    /**
+     * The created elicitation store.
+     */
+    store: ElicitationStore;
+    /**
+     * The type of storage backend used.
+     */
+    type: 'memory' | 'redis' | 'upstash' | 'auto';
+    /**
+     * The underlying storage instance.
+     * Available for advanced use cases.
+     */
+    storage: RootStorage;
+    /**
+     * Whether encryption is enabled for the store.
+     */
+    encrypted: boolean;
+}
+/**
+ * Create an elicitation store based on configuration.
+ *
+ * Uses @frontmcp/utils storage abstractions for unified backend support.
+ *
+ * @param options - Store configuration
+ * @returns The created elicitation store with type information
+ *
+ * @example Auto-detect (recommended)
+ * ```typescript
+ * const { store, type } = await createElicitationStore({
+ *   keyPrefix: 'myapp:elicit:',
+ *   logger,
+ * });
+ * ```
+ *
+ * @example Redis
+ * ```typescript
+ * const { store, type } = await createElicitationStore({
+ *   storage: {
+ *     type: 'redis',
+ *     redis: { url: 'redis://localhost:6379' },
+ *   },
+ *   logger,
+ * });
+ * ```
+ *
+ * @example Memory (development)
+ * ```typescript
+ * const { store, type } = await createElicitationStore({
+ *   storage: { type: 'memory' },
+ *   logger,
+ * });
+ * ```
+ *
+ * @throws {ElicitationNotSupportedError} If Vercel KV is configured (no pub/sub support)
+ * @throws {ElicitationNotSupportedError} If running on Edge runtime without distributed storage
+ * @throws {ElicitationNotSupportedError} If pub/sub is required but not supported
+ */
+export declare function createElicitationStore(options?: ElicitationStoreOptions): Promise<ElicitationStoreResult>;
+/**
+ * Create an in-memory elicitation store explicitly.
+ * Use this when you know you want in-memory storage regardless of configuration.
+ *
+ * @param options - Optional configuration
+ * @returns An in-memory elicitation store
+ */
+export declare function createMemoryElicitationStore(options?: {
+    keyPrefix?: string;
+    logger?: FrontMcpLogger;
+    encryption?: {
+        enabled?: boolean | 'auto';
+        secret?: string;
+    };
+}): ElicitationStoreResult;
+/**
+ * Create an elicitation store from an existing storage instance.
+ * Use this when you want to share a storage connection with other systems.
+ *
+ * @param storage - Existing storage instance
+ * @param options - Optional configuration
+ * @returns An elicitation store using the provided storage
+ */
+export declare function createElicitationStoreFromStorage(storage: RootStorage, options?: {
+    keyPrefix?: string;
+    logger?: FrontMcpLogger;
+    requiresPubSub?: boolean;
+    encryption?: {
+        enabled?: boolean | 'auto';
+        secret?: string;
+    };
+}): ElicitationStoreResult;
+//# sourceMappingURL=elicitation-store.factory.d.ts.map

package/elicitation/store/elicitation-store.factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elicitation-store.factory.d.ts","sourceRoot":"","sources":["../../../src/elicitation/store/elicitation-store.factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAElE,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAM5D;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IAExB;;;;OAIG;IACH,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAE1B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;IAExB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;;;;;;;;;;;;;OAeG;IACH,UAAU,CAAC,EAAE;QACX;;;;;;WAMG;QACH,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;QAE3B;;;WAGG;QACH,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,KAAK,EAAE,gBAAgB,CAAC;IAExB;;OAEG;IACH,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;IAE9C;;;OAGG;IACH,OAAO,EAAE,WAAW,CAAC;IAErB;;OAEG;IACH,SAAS,EAAE,OAAO,CAAC;CACpB;AAgBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,GAAE,uBAA4B,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAwInH;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,GAAE;IACP,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,UAAU,CAAC,EAAE;QACX,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;QAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;CACE,GACL,sBAAsB,CAwBxB;AAED;;;;;;;GAOG;AACH,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,WAAW,EACpB,OAAO,GAAE;IACP,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,UAAU,CAAC,EAAE;QACX,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;QAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;CACE,GACL,sBAAsB,CAsCxB"}

package/elicitation/store/elicitation.store.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Elicitation Store Interface
+ *
+ * Abstraction for storing and routing elicitation state across distributed systems.
+ * Supports storage backends with pub/sub for multi-node deployments and in-memory fallback for
+ * single-node/development environments.
+ *
+ * Key design decisions:
+ * - Pending records are keyed by sessionId (only one elicit per session allowed)
+ * - Pub/sub channels are keyed by elicitId (for result routing)
+ * - This separation allows form mode (lookup by session) and URL mode (direct elicitId)
+ */
+import { ElicitResult, ElicitMode, PendingElicitFallback, ResolvedElicitResult, FallbackExecutionResult, FallbackResultCallback } from '../elicitation.types';
+/**
+ * Record stored for each pending elicitation.
+ * Keyed by sessionId since only one pending elicit per session is allowed.
+ */
+export interface PendingElicitRecord {
+    /** Unique identifier for this elicit request (used for pub/sub routing) */
+    elicitId: string;
+    /** Session ID that initiated the elicitation (used as storage key) */
+    sessionId: string;
+    /** Timestamp when the elicitation was created */
+    createdAt: number;
+    /** Absolute timestamp when the elicitation expires */
+    expiresAt: number;
+    /** Message displayed to the user */
+    message: string;
+    /** Elicitation mode (form or url) */
+    mode: ElicitMode;
+    /** JSON Schema for validating result content (optional for backward compat) */
+    requestedSchema?: Record<string, unknown>;
+}
+/**
+ * Callback type for elicitation result subscriptions.
+ */
+export type ElicitResultCallback<T = unknown> = (result: ElicitResult<T>) => void;
+/**
+ * Unsubscribe function returned by subscribeResult.
+ */
+export type ElicitUnsubscribe = () => Promise<void>;
+/**
+ * Elicitation store interface.
+ *
+ * Provides storage and pub/sub for elicitation state. In distributed deployments,
+ * this enables routing elicitation responses to the correct node via Redis pub/sub.
+ *
+ * Storage is keyed by sessionId (only one pending elicit per session).
+ * Pub/sub is keyed by elicitId (for cross-node result routing).
+ *
+ * @example
+ * ```typescript
+ * // Store pending elicitation (keyed by sessionId)
+ * await store.setPending({
+ *   elicitId: 'elicit-123',
+ *   sessionId: 'session-abc',
+ *   createdAt: Date.now(),
+ *   expiresAt: Date.now() + 300000,
+ *   message: 'Confirm action?',
+ *   mode: 'form',
+ * });
+ *
+ * // Subscribe to results by elicitId (on the node that sent the elicit)
+ * const unsubscribe = await store.subscribeResult('elicit-123', (result) => {
+ *   console.log('Got result:', result);
+ * });
+ *
+ * // On any node: lookup by sessionId, then publish result by elicitId
+ * const pending = await store.getPending('session-abc');
+ * if (pending) {
+ *   await store.publishResult(pending.elicitId, pending.sessionId, { status: 'accept', content: { confirmed: true } });
+ * }
+ * ```
+ */
+export interface ElicitationStore {
+    /**
+     * Store a pending elicitation with TTL.
+     * The record is keyed by sessionId and will auto-expire based on `expiresAt`.
+     *
+     * @param record - The pending elicitation record to store
+     */
+    setPending(record: PendingElicitRecord): Promise<void>;
+    /**
+     * Get a pending elicitation by session ID.
+     * Since only one elicit per session is allowed, sessionId is the lookup key.
+     *
+     * @param sessionId - The session ID to look up
+     * @returns The pending record, or null if not found or expired
+     */
+    getPending(sessionId: string): Promise<PendingElicitRecord | null>;
+    /**
+     * Delete a pending elicitation by session ID.
+     * Called after the elicitation is resolved or times out.
+     *
+     * @param sessionId - The session ID to delete
+     */
+    deletePending(sessionId: string): Promise<void>;
+    /**
+     * Subscribe to elicitation results for a specific elicit ID.
+     * In distributed mode, this creates a Redis pub/sub subscription.
+     *
+     * @param elicitId - The elicitation ID to subscribe to
+     * @param callback - Called when a result is published for this elicit ID
+     * @param sessionId - Optional session ID for encrypted stores (required for decryption)
+     * @returns Unsubscribe function to clean up the subscription
+     */
+    subscribeResult<T = unknown>(elicitId: string, callback: ElicitResultCallback<T>, sessionId?: string): Promise<ElicitUnsubscribe>;
+    /**
+     * Publish an elicitation result.
+     * In distributed mode, this publishes via Redis pub/sub to reach the
+     * correct node regardless of which node received the client response.
+     * Also cleans up the pending record.
+     *
+     * @param elicitId - The elicitation ID
+     * @param sessionId - The session ID (for cleanup)
+     * @param result - The elicitation result to publish
+     */
+    publishResult<T = unknown>(elicitId: string, sessionId: string, result: ElicitResult<T>): Promise<void>;
+    /**
+     * Clean up store resources.
+     * Called during server shutdown.
+     */
+    destroy?(): Promise<void>;
+    /**
+     * Store a pending elicitation fallback context.
+     * Keyed by elicitId since we need to look up by elicitId when
+     * sendElicitationResult is called.
+     *
+     * @param record - The pending fallback record to store
+     */
+    setPendingFallback(record: PendingElicitFallback): Promise<void>;
+    /**
+     * Get a pending elicitation fallback by elicit ID.
+     *
+     * @param elicitId - The elicitation ID to look up
+     * @param sessionId - Optional session ID for encrypted stores (required for decryption)
+     * @returns The pending fallback record, or null if not found or expired
+     */
+    getPendingFallback(elicitId: string, sessionId?: string): Promise<PendingElicitFallback | null>;
+    /**
+     * Delete a pending elicitation fallback by elicit ID.
+     *
+     * @param elicitId - The elicitation ID to delete
+     */
+    deletePendingFallback(elicitId: string): Promise<void>;
+    /**
+     * Store a resolved elicit result for re-invocation.
+     * Used to pass the result to the tool when it's re-invoked.
+     *
+     * @param elicitId - The elicitation ID
+     * @param result - The elicitation result from the user
+     * @param sessionId - Optional session ID for encrypted stores (required for encryption)
+     */
+    setResolvedResult(elicitId: string, result: ElicitResult<unknown>, sessionId?: string): Promise<void>;
+    /**
+     * Get a resolved elicit result by elicit ID.
+     *
+     * @param elicitId - The elicitation ID to look up
+     * @param sessionId - Optional session ID for encrypted stores (required for decryption)
+     * @returns The resolved result, or null if not found
+     */
+    getResolvedResult(elicitId: string, sessionId?: string): Promise<ResolvedElicitResult | null>;
+    /**
+     * Delete a resolved elicit result by elicit ID.
+     *
+     * @param elicitId - The elicitation ID to delete
+     */
+    deleteResolvedResult(elicitId: string): Promise<void>;
+    /**
+     * Subscribe to fallback execution results for a specific elicit ID.
+     * In distributed mode, this creates a Redis pub/sub subscription
+     * for the channel `fallback-result:{elicitId}`.
+     *
+     * @param elicitId - The elicitation ID to subscribe to
+     * @param callback - Called when a fallback result is published for this elicit ID
+     * @param sessionId - Optional session ID for encrypted stores (required for decryption)
+     * @returns Unsubscribe function to clean up the subscription
+     */
+    subscribeFallbackResult(elicitId: string, callback: FallbackResultCallback, sessionId?: string): Promise<ElicitUnsubscribe>;
+    /**
+     * Publish a fallback execution result.
+     * In distributed mode, this publishes via Redis pub/sub to reach the
+     * waiting node that originated the elicitation request.
+     *
+     * @param elicitId - The elicitation ID
+     * @param sessionId - The session ID (for encryption)
+     * @param result - The fallback execution result to publish
+     */
+    publishFallbackResult(elicitId: string, sessionId: string, result: FallbackExecutionResult): Promise<void>;
+}
+//# sourceMappingURL=elicitation.store.d.ts.map

package/elicitation/store/elicitation.store.d.ts.map

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

package/elicitation/store/encrypted-elicitation.store.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Encrypted Elicitation Store
+ *
+ * Wraps an underlying ElicitationStore with session-based encryption.
+ * All data is encrypted using session-derived keys before storage.
+ *
+ * Security Model:
+ * - Pending records: encrypted with record.sessionId
+ * - Fallback records: keyed by {sessionId}:{elicitId}, encrypted with sessionId
+ * - Resolved results: keyed by {sessionId}:{elicitId}, encrypted with sessionId
+ * - Pub/sub messages: encrypted with sessionId before publish
+ *
+ * Migration Support:
+ * - Reads attempt decryption first, falls back to plaintext for migration
+ * - All new writes are encrypted
+ * - Old data expires via TTL (5-10 minutes)
+ *
+ * @module elicitation/store/encrypted-elicitation.store
+ */
+import type { FrontMcpLogger } from '../../common';
+import type { ElicitationStore, PendingElicitRecord, ElicitResultCallback, ElicitUnsubscribe } from './elicitation.store';
+import type { ElicitResult, PendingElicitFallback, ResolvedElicitResult, FallbackExecutionResult, FallbackResultCallback } from '../elicitation.types';
+/**
+ * Options for creating an encrypted elicitation store.
+ */
+export interface EncryptedElicitationStoreOptions {
+    /**
+     * Server secret for key derivation.
+     * Falls back to env vars if not provided.
+     */
+    secret?: string;
+    /**
+     * Logger instance for store operations.
+     */
+    logger?: FrontMcpLogger;
+}
+/**
+ * Encrypted wrapper around an ElicitationStore.
+ *
+ * Provides transparent encryption/decryption of all stored data using
+ * session-derived keys. This ensures that:
+ * 1. Data at rest is encrypted
+ * 2. Only requests with the correct sessionId can decrypt
+ * 3. Different sessions cannot access each other's data
+ */
+export declare class EncryptedElicitationStore implements ElicitationStore {
+    private readonly store;
+    private readonly secret?;
+    private readonly logger?;
+    constructor(store: ElicitationStore, options?: EncryptedElicitationStoreOptions);
+    /**
+     * Store a pending elicitation with encryption.
+     * The record is encrypted using its own sessionId.
+     */
+    setPending(record: PendingElicitRecord): Promise<void>;
+    /**
+     * Get a pending elicitation by session ID.
+     * Attempts decryption, falls back to plaintext for migration.
+     */
+    getPending(sessionId: string): Promise<PendingElicitRecord | null>;
+    /**
+     * Delete a pending elicitation by session ID.
+     */
+    deletePending(sessionId: string): Promise<void>;
+    /**
+     * Subscribe to elicitation results with decryption.
+     */
+    subscribeResult<T = unknown>(elicitId: string, callback: ElicitResultCallback<T>, sessionId?: string): Promise<ElicitUnsubscribe>;
+    /**
+     * Publish an elicitation result with encryption.
+     */
+    publishResult<T = unknown>(elicitId: string, sessionId: string, result: ElicitResult<T>): Promise<void>;
+    /**
+     * Store a pending elicitation fallback context with encryption.
+     */
+    setPendingFallback(record: PendingElicitFallback): Promise<void>;
+    /**
+     * Get a pending elicitation fallback by elicit ID.
+     * Requires sessionId for decryption.
+     */
+    getPendingFallback(elicitId: string, sessionId?: string): Promise<PendingElicitFallback | null>;
+    /**
+     * Delete a pending elicitation fallback by elicit ID.
+     */
+    deletePendingFallback(elicitId: string): Promise<void>;
+    /**
+     * Store a resolved elicit result with encryption.
+     */
+    setResolvedResult(elicitId: string, result: ElicitResult<unknown>, sessionId?: string): Promise<void>;
+    /**
+     * Get a resolved elicit result by elicit ID.
+     * Requires sessionId for decryption.
+     */
+    getResolvedResult(elicitId: string, sessionId?: string): Promise<ResolvedElicitResult | null>;
+    /**
+     * Delete a resolved elicit result by elicit ID.
+     */
+    deleteResolvedResult(elicitId: string): Promise<void>;
+    /**
+     * Subscribe to fallback execution results with decryption.
+     */
+    subscribeFallbackResult(elicitId: string, callback: FallbackResultCallback, sessionId?: string): Promise<ElicitUnsubscribe>;
+    /**
+     * Publish a fallback execution result with encryption.
+     */
+    publishFallbackResult(elicitId: string, sessionId: string, result: FallbackExecutionResult): Promise<void>;
+    destroy(): Promise<void>;
+    /**
+     * Decrypt a pending record.
+     */
+    private decryptPendingRecord;
+    /**
+     * Decrypt a fallback record.
+     */
+    private decryptFallbackRecord;
+    /**
+     * Decrypt a resolved record.
+     */
+    private decryptResolvedRecord;
+}
+//# sourceMappingURL=encrypted-elicitation.store.d.ts.map

package/elicitation/store/encrypted-elicitation.store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encrypted-elicitation.store.d.ts","sourceRoot":"","sources":["../../../src/elicitation/store/encrypted-elicitation.store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EACV,gBAAgB,EAChB,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EAClB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EACV,YAAY,EACZ,qBAAqB,EACrB,oBAAoB,EACpB,uBAAuB,EACvB,sBAAsB,EACvB,MAAM,sBAAsB,CAAC;AAS9B;;GAEG;AACH,MAAM,WAAW,gCAAgC;IAC/C;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,qBAAa,yBAA0B,YAAW,gBAAgB;IAChE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmB;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAiB;gBAE7B,KAAK,EAAE,gBAAgB,EAAE,OAAO,GAAE,gCAAqC;IAUnF;;;OAGG;IACG,UAAU,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IA+B5D;;;OAGG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC;IASxE;;OAEG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQrD;;OAEG;IACG,eAAe,CAAC,CAAC,GAAG,OAAO,EAC/B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,oBAAoB,CAAC,CAAC,CAAC,EACjC,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,iBAAiB,CAAC;IA+B7B;;OAEG;IACG,aAAa,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAyB7G;;OAEG;IACG,kBAAkB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BtE;;;OAGG;IACG,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC;IASrG;;OAEG;IACG,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ5D;;OAEG;IACG,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyC3G;;;OAGG;IACG,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IASnG;;OAEG;IACG,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ3D;;OAEG;IACG,uBAAuB,CAC3B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,sBAAsB,EAChC,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,iBAAiB,CAAC;IA+B7B;;OAEG;IACG,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAyB1G,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ9B;;OAEG;YACW,oBAAoB;IAuClC;;OAEG;YACW,qBAAqB;IAiDnC;;OAEG;YACW,qBAAqB;CA4CpC"}

package/elicitation/store/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Elicitation Store Module
+ *
+ * Storage abstractions for elicitation state management.
+ * Uses @frontmcp/utils storage for unified backend support.
+ *
+ * @module elicitation/store
+ */
+export type { ElicitationStore, PendingElicitRecord, ElicitResultCallback, ElicitUnsubscribe, } from './elicitation.store';
+export { StorageElicitationStore } from './storage-elicitation.store';
+export { EncryptedElicitationStore, type EncryptedElicitationStoreOptions } from './encrypted-elicitation.store';
+export { deriveElicitationKey, encryptElicitationData, decryptElicitationData, isEncryptedBlob, serializeElicitationBlob, deserializeElicitationBlob, encryptAndSerialize, deserializeAndDecrypt, tryDecryptStoredValue, getElicitationSecret, isElicitationEncryptionAvailable, type ElicitationEncryptedBlob, type ElicitationEncryptionConfig, } from './elicitation-encryption';
+export { createElicitationStore, createMemoryElicitationStore, createElicitationStoreFromStorage, type ElicitationStoreOptions, type ElicitationStoreResult, } from './elicitation-store.factory';
+//# sourceMappingURL=index.d.ts.map

package/elicitation/store/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/elicitation/store/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,YAAY,EACV,gBAAgB,EAChB,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AACtE,OAAO,EAAE,yBAAyB,EAAE,KAAK,gCAAgC,EAAE,MAAM,+BAA+B,CAAC;AAGjH,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,sBAAsB,EACtB,eAAe,EACf,wBAAwB,EACxB,0BAA0B,EAC1B,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,gCAAgC,EAChC,KAAK,wBAAwB,EAC7B,KAAK,2BAA2B,GACjC,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EACL,sBAAsB,EACtB,4BAA4B,EAC5B,iCAAiC,EACjC,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,GAC5B,MAAM,6BAA6B,CAAC"}

package/elicitation/store/storage-elicitation.store.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Storage-Based Elicitation Store
+ *
+ * Unified elicitation store implementation using @frontmcp/utils storage abstractions.
+ * Works with Memory, Redis, and Upstash backends.
+ *
+ * @module elicitation/store/storage-elicitation.store
+ */
+import type { NamespacedStorage } from '@frontmcp/utils';
+import type { FrontMcpLogger } from '../../common';
+import type { ElicitationStore, PendingElicitRecord, ElicitResultCallback, ElicitUnsubscribe } from './elicitation.store';
+import type { ElicitResult, PendingElicitFallback, ResolvedElicitResult, FallbackExecutionResult, FallbackResultCallback } from '../elicitation.types';
+/**
+ * Elicitation store using @frontmcp/utils storage abstractions.
+ *
+ * Features:
+ * - Uses TypedStorage for type-safe JSON serialization
+ * - Uses NamespacedStorage for key prefixing
+ * - Uses native pub/sub from storage adapter (works with Memory, Redis, Upstash)
+ * - Automatic TTL-based expiration
+ *
+ * Storage layout:
+ * - `pending:{sessionId}` - Pending elicitation records
+ * - `fallback:{elicitId}` - Fallback context for re-invocation
+ * - `resolved:{elicitId}` - Pre-resolved results for fallback flow
+ * - Pub/sub channel: `result:{elicitId}` - Result routing
+ */
+export declare class StorageElicitationStore implements ElicitationStore {
+    private readonly storage;
+    private readonly pending;
+    private readonly fallback;
+    private readonly resolved;
+    private readonly logger?;
+    /** Local callback registry for pub/sub (maps elicitId -> callbacks) */
+    private readonly localCallbacks;
+    /** Active subscriptions (maps elicitId -> unsubscribe function) */
+    private readonly activeSubscriptions;
+    /** Pending subscriptions guard to prevent duplicate concurrent subscribe calls */
+    private readonly pendingSubscriptions;
+    /** Local callback registry for fallback results (maps elicitId -> callbacks) */
+    private readonly fallbackResultCallbacks;
+    /** Active fallback subscriptions (maps elicitId -> unsubscribe function) */
+    private readonly activeFallbackSubscriptions;
+    /** Pending fallback subscriptions guard */
+    private readonly pendingFallbackSubscriptions;
+    constructor(storage: NamespacedStorage, logger?: FrontMcpLogger);
+    /**
+     * Store a pending elicitation with TTL.
+     */
+    setPending(record: PendingElicitRecord): Promise<void>;
+    /**
+     * Get a pending elicitation by session ID.
+     */
+    getPending(sessionId: string): Promise<PendingElicitRecord | null>;
+    /**
+     * Delete a pending elicitation by session ID.
+     */
+    deletePending(sessionId: string): Promise<void>;
+    /**
+     * Subscribe to elicitation results for a specific elicit ID.
+     * Uses in-flight subscription guard to prevent duplicate concurrent subscriptions.
+     */
+    subscribeResult<T = unknown>(elicitId: string, callback: ElicitResultCallback<T>, _sessionId?: string): Promise<ElicitUnsubscribe>;
+    /**
+     * Publish an elicitation result.
+     *
+     * When pub/sub is supported, we rely entirely on the pub/sub mechanism
+     * to deliver messages (even locally). This avoids double-invocation for
+     * memory-based storage where pub/sub IS local.
+     *
+     * When pub/sub is not supported, we invoke local callbacks directly.
+     */
+    publishResult<T = unknown>(elicitId: string, sessionId: string, result: ElicitResult<T>): Promise<void>;
+    /**
+     * Store a pending elicitation fallback context.
+     */
+    setPendingFallback(record: PendingElicitFallback): Promise<void>;
+    /**
+     * Get a pending elicitation fallback by elicit ID.
+     */
+    getPendingFallback(elicitId: string, _sessionId?: string): Promise<PendingElicitFallback | null>;
+    /**
+     * Delete a pending elicitation fallback by elicit ID.
+     */
+    deletePendingFallback(elicitId: string): Promise<void>;
+    /**
+     * Store a resolved elicit result for re-invocation.
+     */
+    setResolvedResult(elicitId: string, result: ElicitResult<unknown>, _sessionId?: string): Promise<void>;
+    /**
+     * Get a resolved elicit result by elicit ID.
+     */
+    getResolvedResult(elicitId: string, _sessionId?: string): Promise<ResolvedElicitResult | null>;
+    /**
+     * Delete a resolved elicit result by elicit ID.
+     */
+    deleteResolvedResult(elicitId: string): Promise<void>;
+    /**
+     * Subscribe to fallback execution results for a specific elicit ID.
+     * Uses in-flight subscription guard to prevent duplicate concurrent subscriptions.
+     */
+    subscribeFallbackResult(elicitId: string, callback: FallbackResultCallback, _sessionId?: string): Promise<ElicitUnsubscribe>;
+    /**
+     * Publish a fallback execution result.
+     *
+     * When pub/sub is supported, we rely entirely on the pub/sub mechanism
+     * to deliver messages (even locally). This avoids double-invocation for
+     * memory-based storage where pub/sub IS local.
+     *
+     * When pub/sub is not supported, we invoke local callbacks directly.
+     */
+    publishFallbackResult(elicitId: string, sessionId: string, result: FallbackExecutionResult): Promise<void>;
+    /**
+     * Clean up store resources.
+     */
+    destroy(): Promise<void>;
+}
+//# sourceMappingURL=storage-elicitation.store.d.ts.map

package/elicitation/store/storage-elicitation.store.d.ts.map

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