@phake/mcp 0.0.1

package/dist/shared/mcp/dispatcher.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Shared MCP JSON-RPC dispatcher.
+ * Used by both Node.js (via SDK wrapper) and Cloudflare Workers (directly).
+ */
+import type { ToolContext } from "../tools/types.js";
+export declare const LATEST_PROTOCOL_VERSION = "2025-06-18";
+export declare const SUPPORTED_PROTOCOL_VERSIONS: string[];
+/** JSON-RPC error codes */
+export declare const JsonRpcErrorCode: {
+    readonly ParseError: -32700;
+    readonly InvalidRequest: -32600;
+    readonly MethodNotFound: -32601;
+    readonly InvalidParams: -32602;
+    readonly InternalError: -32603;
+};
+/** MCP server configuration */
+export interface McpServerConfig {
+    title: string;
+    version: string;
+    instructions?: string;
+}
+/** Session state for MCP connections */
+export interface McpSessionState {
+    initialized: boolean;
+    clientInfo?: {
+        name: string;
+        version: string;
+    };
+    protocolVersion?: string;
+}
+/** Cancellation controller registry for in-flight requests */
+export type CancellationRegistry = Map<string | number, AbortController>;
+/** Context for MCP request handling */
+export interface McpDispatchContext {
+    sessionId: string;
+    auth: ToolContext;
+    config: McpServerConfig;
+    getSessionState: () => McpSessionState | undefined;
+    setSessionState: (state: McpSessionState) => void;
+    /** Registry for tracking in-flight requests that can be cancelled */
+    cancellationRegistry?: CancellationRegistry;
+    /** Custom tools (if not provided, uses sharedTools) */
+    tools?: import("../tools/types.js").SharedToolDefinition[];
+}
+/** JSON-RPC response */
+export interface JsonRpcResult {
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+/**
+ * Get the current log level set by the client.
+ */
+export declare function getLogLevel(): string;
+/**
+ * Dispatch an MCP JSON-RPC method.
+ *
+ * @param method - The JSON-RPC method name
+ * @param params - The method parameters
+ * @param ctx - Dispatch context with session and auth info
+ * @param requestId - Optional request ID for cancellation tracking
+ * @returns JSON-RPC result or error
+ */
+export declare function dispatchMcpMethod(method: string | undefined, params: Record<string, unknown> | undefined, ctx: McpDispatchContext, requestId?: string | number): Promise<JsonRpcResult>;
+/** Parameters for notifications/cancelled */
+export interface CancelledNotificationParams {
+    requestId: string | number;
+    reason?: string;
+}
+/**
+ * Handle MCP notification (no response expected).
+ *
+ * @param method - The notification method name
+ * @param params - Notification parameters
+ * @param ctx - Dispatch context
+ * @returns true if handled, false if unknown
+ */
+export declare function handleMcpNotification(method: string, params: Record<string, unknown> | undefined, ctx: McpDispatchContext): boolean;

package/dist/shared/mcp/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./dispatcher.js";
+export * from "./security.js";
+export * from "./server-internals.js";

package/dist/shared/mcp/security.d.ts

@@ -0,0 +1,23 @@
+export declare function validateOrigin(headers: Headers, isDev: boolean): void;
+export declare function validateProtocolVersion(headers: Headers, _expected: string): void;
+export type UnauthorizedChallenge = {
+    status: 401;
+    headers: Record<string, string>;
+    body: {
+        jsonrpc: "2.0";
+        error: {
+            code: -32000;
+            message: string;
+        };
+        id: null;
+    };
+};
+/**
+ * Build a 401 Unauthorized challenge response for MCP
+ */
+export declare function buildUnauthorizedChallenge(args: {
+    origin: string;
+    sid: string;
+    resourcePath?: string;
+    message?: string;
+}): UnauthorizedChallenge;

package/dist/shared/mcp/server-internals.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Type-safe access to internal MCP SDK Server properties.
+ *
+ * The McpServer class wraps a lower-level Server instance that provides
+ * direct access to request/notification methods and client capabilities.
+ * This module provides typed helpers to access these internals safely.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Shape of the internal server with commonly used methods.
+ * These are not part of the public McpServer API but are needed
+ * for advanced features like client requests and capability checks.
+ */
+interface LowLevelServer {
+    request?: (params: {
+        method: string;
+        params?: unknown;
+    }, schema?: {
+        parse: (r: unknown) => unknown;
+    }) => Promise<unknown>;
+    notification?: (params: {
+        method: string;
+        params?: unknown;
+    }) => Promise<void>;
+    setRequestHandler?: (method: string, handler: (request: unknown) => Promise<unknown>) => void;
+    getClientCapabilities?: () => ClientCapabilities;
+    getClientVersion?: () => string;
+    oninitialized?: () => void;
+}
+/**
+ * Client capabilities shape for type-safe access.
+ */
+interface ClientCapabilities {
+    roots?: {
+        listChanged?: boolean;
+    };
+    sampling?: {
+        tools?: boolean;
+    };
+    elicitation?: {
+        form?: unknown;
+        url?: boolean;
+    };
+    [key: string]: unknown;
+}
+/**
+ * McpServer with internal methods typed (use with type assertion).
+ */
+interface McpServerWithInternals {
+    server?: LowLevelServer;
+    sendResourceUpdated?: (params: {
+        uri: string;
+    }) => void;
+}
+/**
+ * Get the low-level server instance from McpServer.
+ * Returns the internal Server or falls back to the McpServer itself.
+ */
+export declare function getLowLevelServer(server: McpServer): LowLevelServer;
+/**
+ * Get McpServer with internal methods typed.
+ */
+export declare function getServerWithInternals(server: McpServer): McpServerWithInternals;
+/**
+ * JSON-RPC error with code property.
+ */
+export interface JsonRpcError extends Error {
+    code?: number;
+    data?: unknown;
+}
+/**
+ * Check if an error is a JSON-RPC error with a specific code.
+ */
+export declare function isJsonRpcError(error: unknown, code?: number): error is JsonRpcError;
+/**
+ * JSON-RPC error code for method not found.
+ */
+export declare const JSON_RPC_METHOD_NOT_FOUND = -32601;
+export {};

package/dist/shared/oauth/cimd.d.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+/**
+ * Client metadata document schema (RFC 7591 compatible)
+ */
+export declare const ClientMetadataSchema: z.ZodObject<{
+    client_id: z.ZodString;
+    client_name: z.ZodOptional<z.ZodString>;
+    redirect_uris: z.ZodArray<z.ZodString>;
+    client_uri: z.ZodOptional<z.ZodString>;
+    logo_uri: z.ZodOptional<z.ZodString>;
+    tos_uri: z.ZodOptional<z.ZodString>;
+    policy_uri: z.ZodOptional<z.ZodString>;
+    jwks_uri: z.ZodOptional<z.ZodString>;
+    software_statement: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ClientMetadata = z.infer<typeof ClientMetadataSchema>;
+export type CimdConfig = {
+    /** Fetch timeout in milliseconds (default: 5000) */
+    timeoutMs?: number;
+    /** Maximum response size in bytes (default: 65536) */
+    maxBytes?: number;
+    /** List of allowed domains (if set, only these domains are allowed) */
+    allowedDomains?: string[];
+};
+export type CimdFetchResult = {
+    success: true;
+    metadata: ClientMetadata;
+} | {
+    success: false;
+    error: string;
+};
+/**
+ * Check if a client_id is a CIMD URL (HTTPS with non-root path)
+ */
+export declare function isClientIdUrl(clientId: string): boolean;
+/**
+ * Fetch and validate client metadata from a CIMD URL
+ */
+export declare function fetchClientMetadata(clientIdUrl: string, config?: CimdConfig): Promise<CimdFetchResult>;
+/**
+ * Validate that a redirect_uri is allowed by the client metadata
+ */
+export declare function validateRedirectUri(metadata: ClientMetadata, redirectUri: string): boolean;

package/dist/shared/oauth/discovery-handlers.d.ts

@@ -0,0 +1,14 @@
+import type { UnifiedConfig } from "../config/env.js";
+import { buildAuthorizationServerMetadata, buildProtectedResourceMetadata } from "./discovery.js";
+type DiscoveryStrategy = {
+    resolveAuthBaseUrl(requestUrl: URL, config: UnifiedConfig): string;
+    resolveAuthorizationServerUrl(requestUrl: URL, config: UnifiedConfig): string;
+    resolveResourceBaseUrl(requestUrl: URL, config: UnifiedConfig): string;
+};
+export declare function createDiscoveryHandlers(config: UnifiedConfig, strategy: DiscoveryStrategy): {
+    authorizationMetadata: (requestUrl: URL) => ReturnType<typeof buildAuthorizationServerMetadata>;
+    protectedResourceMetadata: (requestUrl: URL, sid?: string) => ReturnType<typeof buildProtectedResourceMetadata>;
+};
+export declare const workerDiscoveryStrategy: DiscoveryStrategy;
+export declare const nodeDiscoveryStrategy: DiscoveryStrategy;
+export {};

package/dist/shared/oauth/discovery.d.ts

@@ -0,0 +1,26 @@
+export type AuthorizationServerMetadata = {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    revocation_endpoint: string;
+    registration_endpoint: string;
+    response_types_supported: string[];
+    grant_types_supported: string[];
+    code_challenge_methods_supported: string[];
+    token_endpoint_auth_methods_supported: string[];
+    scopes_supported: string[];
+    /** SEP-991: CIMD support flag */
+    client_id_metadata_document_supported?: boolean;
+};
+export type ProtectedResourceMetadata = {
+    authorization_servers: string[];
+    resource: string;
+};
+export declare function buildAuthorizationServerMetadata(baseUrl: string, scopes: string[], overrides?: {
+    authorizationEndpoint?: string;
+    tokenEndpoint?: string;
+    revocationEndpoint?: string;
+    /** Enable CIMD support (SEP-991) */
+    cimdEnabled?: boolean;
+}): AuthorizationServerMetadata;
+export declare function buildProtectedResourceMetadata(resourceUrl: string, authorizationServerUrl: string, sid?: string): ProtectedResourceMetadata;

package/dist/shared/oauth/endpoints.d.ts

@@ -0,0 +1,11 @@
+import type { RegisterInput, RegisterResult } from "./types.js";
+/**
+ * Handle dynamic client registration (RFC7591)
+ */
+export declare function handleRegister(input: RegisterInput, baseUrl: string, defaultRedirectUri: string): Promise<RegisterResult>;
+/**
+ * Handle token revocation (no-op in this implementation)
+ */
+export declare function handleRevoke(): Promise<{
+    status: string;
+}>;

package/dist/shared/oauth/flow.d.ts

@@ -0,0 +1,31 @@
+import type { TokenStore } from "../storage/interface.js";
+import { type CimdConfig } from "./cimd.js";
+import type { AuthorizeInput, AuthorizeResult, CallbackInput, CallbackResult, OAuthConfig, ProviderConfig, TokenInput, TokenResult } from "./types.js";
+/**
+ * Generate a cryptographically secure opaque token.
+ */
+export declare function generateOpaqueToken(bytes?: number): string;
+/**
+ * Handle authorization request - redirect to provider or issue dev code
+ */
+export declare function handleAuthorize(input: AuthorizeInput, store: TokenStore, providerConfig: ProviderConfig, oauthConfig: OAuthConfig, options: {
+    baseUrl: string;
+    isDev: boolean;
+    callbackPath?: string;
+    /** CIMD configuration (SEP-991) */
+    cimd?: CimdConfig & {
+        enabled?: boolean;
+    };
+}): Promise<AuthorizeResult>;
+/**
+ * Handle provider callback - exchange code for tokens using oauth4webapi
+ */
+export declare function handleProviderCallback(input: CallbackInput, store: TokenStore, providerConfig: ProviderConfig, oauthConfig: OAuthConfig, options: {
+    baseUrl: string;
+    isDev: boolean;
+    callbackPath?: string;
+}): Promise<CallbackResult>;
+/**
+ * Handle token exchange (authorization_code or refresh_token grant)
+ */
+export declare function handleToken(input: TokenInput, store: TokenStore, providerConfig?: ProviderConfig): Promise<TokenResult>;

package/dist/shared/oauth/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./cimd.js";
+export * from "./discovery.js";
+export * from "./discovery-handlers.js";
+export * from "./endpoints.js";
+export * from "./flow.js";
+export * from "./input-parsers.js";
+export * from "./refresh.js";
+export * from "./ssrf.js";
+export * from "./types.js";

package/dist/shared/oauth/input-parsers.d.ts

@@ -0,0 +1,43 @@
+import type { UnifiedConfig } from "../config/env.js";
+import type { AuthorizeInput, OAuthConfig, ProviderConfig, TokenInput } from "./types.js";
+/**
+ * Parse authorization request from URL search params.
+ */
+export declare function parseAuthorizeInput(url: URL, sessionId?: string): AuthorizeInput;
+/**
+ * Parse callback request from URL search params.
+ */
+export declare function parseCallbackInput(url: URL): {
+    code: string | null;
+    state: string | null;
+};
+/**
+ * Parse token request from form data or JSON body.
+ */
+export declare function parseTokenInput(request: Request): Promise<URLSearchParams>;
+/**
+ * Build TokenInput from parsed form data.
+ */
+export declare function buildTokenInput(form: URLSearchParams): TokenInput | {
+    error: string;
+};
+/**
+ * Build ProviderConfig from UnifiedConfig.
+ */
+export declare function buildProviderConfig(config: UnifiedConfig): ProviderConfig;
+/**
+ * Build OAuthConfig from UnifiedConfig.
+ */
+export declare function buildOAuthConfig(config: UnifiedConfig): OAuthConfig;
+/**
+ * Build flow options from request URL.
+ */
+export declare function buildFlowOptions(url: URL, config: UnifiedConfig, overrides?: {
+    callbackPath?: string;
+    tokenEndpointPath?: string;
+}): {
+    baseUrl: string;
+    isDev: boolean;
+    callbackPath: string;
+    tokenEndpointPath: string;
+};

package/dist/shared/oauth/refresh.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Proactive token refresh utilities using oauth4webapi.
+ *
+ * This module provides token refresh functionality that can be used
+ * during tool execution to ensure tokens are fresh before making API calls.
+ */
+import type { ProviderTokens, TokenStore } from "../storage/interface.js";
+/** Provider configuration for token refresh */
+export interface ProviderRefreshConfig {
+    clientId: string;
+    clientSecret: string;
+    accountsUrl: string;
+    tokenEndpointPath?: string;
+}
+/**
+ * Build provider refresh config from unified config.
+ * Returns undefined if required fields are missing.
+ */
+export declare function buildProviderRefreshConfig(config: {
+    PROVIDER_CLIENT_ID?: string;
+    PROVIDER_CLIENT_SECRET?: string;
+    PROVIDER_ACCOUNTS_URL?: string;
+    OAUTH_TOKEN_URL?: string;
+}): ProviderRefreshConfig | undefined;
+/** Token refresh result */
+export interface RefreshResult {
+    success: boolean;
+    tokens?: ProviderTokens;
+    error?: string;
+}
+/**
+ * Refresh provider token using refresh_token grant via oauth4webapi.
+ *
+ * @param refreshToken - The provider refresh token
+ * @param config - Provider configuration
+ * @returns New provider tokens or error
+ */
+export declare function refreshProviderToken(refreshToken: string, config: ProviderRefreshConfig): Promise<RefreshResult>;
+/**
+ * Check if a token is expired or will expire soon.
+ *
+ * @param expiresAt - Token expiry timestamp (ms)
+ * @param bufferMs - Buffer time before expiry to consider "near expiry"
+ * @returns true if token is expired or expiring within buffer
+ */
+export declare function isTokenExpiredOrExpiring(expiresAt: number | undefined, bufferMs?: number): boolean;
+/**
+ * Proactively refresh token if near expiry.
+ *
+ * This should be called before tool execution to ensure fresh tokens.
+ * Updates the token store with new tokens if refresh succeeds.
+ *
+ * @param rsAccessToken - The RS access token to check
+ * @param tokenStore - Token storage
+ * @param providerConfig - Provider configuration for refresh
+ * @returns Refreshed provider access token, or original if refresh not needed/failed
+ */
+export declare function ensureFreshToken(rsAccessToken: string, tokenStore: TokenStore, providerConfig: ProviderRefreshConfig | undefined): Promise<{
+    accessToken: string;
+    wasRefreshed: boolean;
+}>;

package/dist/shared/oauth/ssrf.d.ts

@@ -0,0 +1,31 @@
+export type SsrfCheckResult = {
+    safe: true;
+} | {
+    safe: false;
+    reason: string;
+};
+/**
+ * Validate a URL for SSRF safety before making outbound requests.
+ *
+ * Rules:
+ * - Must be HTTPS (HTTP blocked)
+ * - Must not target localhost or loopback
+ * - Must not target private IP ranges
+ * - Must not target internal domain patterns
+ * - Must have non-root pathname (for CIMD URLs)
+ */
+export declare function checkSsrfSafe(urlString: string, options?: {
+    requireNonRootPath?: boolean;
+}): SsrfCheckResult;
+/**
+ * Convenience function that returns boolean
+ */
+export declare function isSsrfSafe(urlString: string, options?: {
+    requireNonRootPath?: boolean;
+}): boolean;
+/**
+ * Throws if URL is not SSRF-safe
+ */
+export declare function assertSsrfSafe(urlString: string, options?: {
+    requireNonRootPath?: boolean;
+}): void;

package/dist/shared/oauth/types.d.ts

@@ -0,0 +1,78 @@
+export type AuthorizeInput = {
+    clientId?: string;
+    codeChallenge: string;
+    codeChallengeMethod: string;
+    redirectUri: string;
+    requestedScope?: string;
+    state?: string;
+    sid?: string;
+};
+export type { CimdConfig, ClientMetadata } from "./cimd.js";
+export type AuthorizeResult = {
+    redirectTo: string;
+    txnId: string;
+};
+export type CallbackInput = {
+    providerCode: string;
+    compositeState: string;
+};
+export type CallbackResult = {
+    redirectTo: string;
+    txnId: string;
+    providerTokens: {
+        access_token: string;
+        refresh_token?: string;
+        expires_at?: number;
+        scopes?: string[];
+    };
+};
+export type TokenInput = {
+    grant: "authorization_code";
+    code: string;
+    codeVerifier: string;
+} | {
+    grant: "refresh_token";
+    refreshToken: string;
+};
+export type TokenResult = {
+    access_token: string;
+    refresh_token: string;
+    token_type: "bearer";
+    expires_in: number;
+    scope: string;
+};
+export type RegisterInput = {
+    redirect_uris?: string[];
+    grant_types?: string[];
+    response_types?: string[];
+    client_name?: string;
+};
+export type RegisterResult = {
+    client_id: string;
+    client_id_issued_at: number;
+    client_secret_expires_at: number;
+    token_endpoint_auth_method: string;
+    redirect_uris: string[];
+    grant_types: string[];
+    response_types: string[];
+    registration_client_uri: string;
+    registration_access_token: string;
+    client_name?: string;
+};
+export type ProviderConfig = {
+    clientId?: string;
+    clientSecret?: string;
+    accountsUrl: string;
+    oauthScopes: string;
+    /** Extra query params for authorization URL (e.g., "access_type=offline&prompt=consent") */
+    extraAuthParams?: string;
+    /** Path to authorization endpoint (default: /authorize for most providers) */
+    authorizationEndpointPath?: string;
+    /** Path to token endpoint - varies by provider (Spotify: /api/token, Google: /token, GitHub: /login/oauth/access_token) */
+    tokenEndpointPath?: string;
+};
+export type OAuthConfig = {
+    redirectUri: string;
+    redirectAllowlist: string[];
+    redirectAllowAll: boolean;
+};

package/dist/shared/schemas/prompts.d.ts

@@ -0,0 +1 @@
+export type PromptArgs = Record<string, unknown>;

package/dist/shared/services/http-client.d.ts

@@ -0,0 +1,16 @@
+export type HttpClientInput = string | URL | {
+    url?: string;
+} | Request;
+export type HttpClient = (input: HttpClientInput, init?: RequestInit) => Promise<Response>;
+export interface HttpClientOptions {
+    baseHeaders?: Record<string, string>;
+    timeout?: number;
+    retries?: number;
+    retryDelay?: number;
+    rateLimit?: {
+        rps: number;
+        burst: number;
+    };
+    concurrency?: number;
+}
+export declare function createHttpClient(options?: HttpClientOptions): HttpClient;

package/dist/shared/services/index.d.ts

@@ -0,0 +1 @@
+export * from "./http-client.js";

package/dist/shared/storage/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./interface.js";
+export * from "./kv.js";
+export * from "./memory.js";
+export * from "./singleton.js";

package/dist/shared/storage/interface.d.ts

@@ -0,0 +1,99 @@
+export type ProviderTokens = {
+    access_token: string;
+    refresh_token?: string;
+    expires_at?: number;
+    scopes?: string[];
+};
+export type RsRecord = {
+    rs_access_token: string;
+    rs_refresh_token: string;
+    provider: ProviderTokens;
+    created_at: number;
+};
+export type Transaction = {
+    codeChallenge: string;
+    state?: string;
+    scope?: string;
+    createdAt: number;
+    sid?: string;
+    provider?: ProviderTokens;
+    /** Client's redirect_uri — stored at authorize time so callback can redirect without allowlist */
+    clientRedirectUri?: string;
+};
+export type SessionRecord = {
+    /** API key that owns this session (for multi-tenant support) */
+    apiKey?: string;
+    rs_access_token?: string;
+    rs_refresh_token?: string;
+    provider?: ProviderTokens | null;
+    created_at: number;
+    last_accessed: number;
+    /** Whether MCP initialize handshake completed */
+    initialized?: boolean;
+    /** Negotiated MCP protocol version */
+    protocolVersion?: string;
+};
+/**
+ * Token storage interface - all operations are async to support both
+ * sync (Node Map + File) and async (Cloudflare KV) backends
+ */
+export interface TokenStore {
+    storeRsMapping(rsAccess: string, provider: ProviderTokens, rsRefresh?: string): Promise<RsRecord>;
+    getByRsAccess(rsAccess: string): Promise<RsRecord | null>;
+    getByRsRefresh(rsRefresh: string): Promise<RsRecord | null>;
+    updateByRsRefresh(rsRefresh: string, provider: ProviderTokens, maybeNewRsAccess?: string): Promise<RsRecord | null>;
+    saveTransaction(txnId: string, txn: Transaction, ttlSeconds?: number): Promise<void>;
+    getTransaction(txnId: string): Promise<Transaction | null>;
+    deleteTransaction(txnId: string): Promise<void>;
+    saveCode(code: string, txnId: string, ttlSeconds?: number): Promise<void>;
+    getTxnIdByCode(code: string): Promise<string | null>;
+    deleteCode(code: string): Promise<void>;
+}
+/** Maximum sessions allowed per API key */
+export declare const MAX_SESSIONS_PER_API_KEY = 5;
+/**
+ * Session storage interface for multi-tenant MCP servers.
+ * Supports tracking sessions per API key with limits and LRU eviction.
+ */
+export interface SessionStore {
+    /**
+     * Create a new session for an API key.
+     * Automatically enforces MAX_SESSIONS_PER_API_KEY limit with LRU eviction.
+     */
+    create(sessionId: string, apiKey: string): Promise<SessionRecord>;
+    /**
+     * Get a session by ID. Returns null if not found or expired.
+     * Updates last_accessed timestamp on access.
+     */
+    get(sessionId: string): Promise<SessionRecord | null>;
+    /**
+     * Update session data (e.g., mark as initialized, store protocol version).
+     */
+    update(sessionId: string, data: Partial<SessionRecord>): Promise<void>;
+    /**
+     * Delete a session.
+     */
+    delete(sessionId: string): Promise<void>;
+    /**
+     * Get all sessions for an API key.
+     */
+    getByApiKey(apiKey: string): Promise<SessionRecord[]>;
+    /**
+     * Count active sessions for an API key.
+     */
+    countByApiKey(apiKey: string): Promise<number>;
+    /**
+     * Delete the oldest session for an API key (LRU eviction).
+     */
+    deleteOldestByApiKey(apiKey: string): Promise<void>;
+    /**
+     * Ensure a session exists (legacy compat). Creates minimal session if missing.
+     * @deprecated Use create() for new code
+     */
+    ensure(sessionId: string): Promise<void>;
+    /**
+     * Put a session record directly (legacy compat).
+     * @deprecated Use create() or update() for new code
+     */
+    put(sessionId: string, value: SessionRecord): Promise<void>;
+}