mcpbox 0.0.1

package/dist/mcp/manager.js

@@ -0,0 +1,341 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport, getDefaultEnvironment, } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { validateToolName } from "@modelcontextprotocol/sdk/shared/toolNameValidation.js";
+import { logger } from "../logger.js";
+import { NAME, VERSION } from "../version.js";
+import { namespaceName, stripNamespace } from "./namespace.js";
+export class McpManager {
+    mcps = new Map();
+    toolToMcp = new Map(); // tool name -> mcp name
+    resourceToMcp = new Map(); // uri -> mcp name
+    promptToMcp = new Map(); // prompt name -> mcp name
+    mcpDebug;
+    useNamespacing = true;
+    constructor(logConfig) {
+        this.mcpDebug = logConfig?.mcpDebug ?? false;
+    }
+    async start(configs) {
+        if (configs.length === 0) {
+            logger.warn("No MCPs configured");
+            return;
+        }
+        //Can be disabled via internal env var for conformance test.
+        this.useNamespacing = process.env.__MCPBOX_SKIP_NAMESPACE !== "true";
+        logger.info({ count: configs.length, namespacing: this.useNamespacing }, "Starting MCPs");
+        let succeeded = 0;
+        let failed = 0;
+        for (const config of configs) {
+            try {
+                await this.startMcp(config);
+                succeeded++;
+            }
+            catch (error) {
+                failed++;
+                // Redact sensitive values from args for logging
+                const redactedArgs = config.args?.map((arg) => arg.replace(/(PASSWORD|SECRET|TOKEN|KEY|PIN)=.*/i, "$1=***"));
+                logger.error({
+                    mcp: config.name,
+                    error: error instanceof Error ? error.message : String(error),
+                    command: config.command,
+                    args: redactedArgs,
+                }, `MCP failed to start: ${config.name}`);
+            }
+        }
+        if (failed > 0) {
+            logger.warn({ succeeded, failed, total: configs.length }, `MCPs started with failures: ${succeeded}/${configs.length}`);
+        }
+        else {
+            logger.info({ count: succeeded }, "All MCPs started successfully");
+        }
+    }
+    async startMcp(config) {
+        logger.debug({ mcp: config.name }, `Starting MCP: ${config.name}`);
+        const transport = new StdioClientTransport({
+            command: config.command,
+            args: config.args,
+            env: { ...getDefaultEnvironment(), ...config.env },
+            stderr: this.mcpDebug ? "pipe" : "ignore",
+        });
+        // Forward MCP stderr to our logger when debug is enabled
+        if (this.mcpDebug && transport.stderr) {
+            transport.stderr.on("data", (data) => {
+                const message = data.toString().trim();
+                if (message) {
+                    logger.info(`[mcp:${config.name}] ${message}`);
+                }
+            });
+        }
+        const client = new Client({
+            name: NAME,
+            version: VERSION,
+        });
+        await client.connect(transport);
+        // Get tools from this MCP (filter by allowlist if configured, then namespace)
+        const { tools: rawTools } = await client.listTools();
+        const toolsAllowlist = config.tools;
+        const filteredTools = toolsAllowlist
+            ? rawTools.filter((tool) => toolsAllowlist.includes(tool.name))
+            : rawTools;
+        if (toolsAllowlist) {
+            const availableToolNames = rawTools.map((t) => t.name);
+            const unknownTools = toolsAllowlist.filter((name) => !availableToolNames.includes(name));
+            if (unknownTools.length > 0) {
+                logger.warn({
+                    mcp: config.name,
+                    unknownTools,
+                    availableTools: availableToolNames,
+                }, "Tools allowlist contains unknown tool names (possible typo)");
+            }
+            logger.info({
+                mcp: config.name,
+                allowed: filteredTools.length,
+                total: rawTools.length,
+            }, "Filtered tools by allowlist");
+        }
+        const tools = this.useNamespacing
+            ? filteredTools.map((tool) => ({
+                ...tool,
+                name: namespaceName(config.name, tool.name),
+            }))
+            : filteredTools;
+        for (const tool of tools) {
+            const validation = validateToolName(tool.name);
+            if (!validation.isValid || validation.warnings.length > 0) {
+                logger.warn({ tool: tool.name, warnings: validation.warnings }, `Tool name may not comply with SEP-986: ${tool.name}`);
+            }
+            this.toolToMcp.set(tool.name, config.name);
+        }
+        // Get resources from this MCP (namespace them if multiple servers)
+        let resources = [];
+        try {
+            const { resources: rawResources } = await client.listResources();
+            resources = this.useNamespacing
+                ? rawResources.map((resource) => ({
+                    ...resource,
+                    uri: namespaceName(config.name, resource.uri),
+                }))
+                : rawResources;
+            for (const resource of resources) {
+                this.resourceToMcp.set(resource.uri, config.name);
+            }
+        }
+        catch {
+            logger.info({ mcp: config.name }, "Server doesn't support resources");
+        }
+        // Get prompts from this MCP (namespace them if multiple servers)
+        let prompts = [];
+        try {
+            const { prompts: rawPrompts } = await client.listPrompts();
+            prompts = this.useNamespacing
+                ? rawPrompts.map((prompt) => ({
+                    ...prompt,
+                    name: namespaceName(config.name, prompt.name),
+                }))
+                : rawPrompts;
+            for (const prompt of prompts) {
+                this.promptToMcp.set(prompt.name, config.name);
+            }
+        }
+        catch {
+            logger.info({ mcp: config.name }, "Server doesn't support prompts");
+        }
+        this.mcps.set(config.name, {
+            name: config.name,
+            client,
+            transport,
+            tools,
+            resources,
+            prompts,
+        });
+        logger.info({
+            mcp: config.name,
+            tools: tools.length,
+            resources: resources.length,
+            prompts: prompts.length,
+        }, `MCP ready: ${config.name}`);
+    }
+    async stop() {
+        const stopPromises = [];
+        for (const [name, mcp] of this.mcps) {
+            logger.info(`Stopping MCP: ${name}`);
+            stopPromises.push(mcp.transport.close().catch((error) => {
+                logger.error({
+                    error: error instanceof Error ? error.message : String(error),
+                }, `Error stopping MCP: ${name}`);
+            }));
+        }
+        await Promise.all(stopPromises);
+        this.mcps.clear();
+        this.toolToMcp.clear();
+        this.resourceToMcp.clear();
+        this.promptToMcp.clear();
+        logger.info("All MCPs stopped");
+    }
+    get count() {
+        return this.mcps.size;
+    }
+    listTools() {
+        const allTools = [];
+        for (const mcp of this.mcps.values()) {
+            allTools.push(...mcp.tools);
+        }
+        return allTools;
+    }
+    listResources() {
+        const allResources = [];
+        for (const mcp of this.mcps.values()) {
+            allResources.push(...mcp.resources);
+        }
+        return allResources;
+    }
+    listPrompts() {
+        const allPrompts = [];
+        for (const mcp of this.mcps.values()) {
+            allPrompts.push(...mcp.prompts);
+        }
+        return allPrompts;
+    }
+    async checkHealth() {
+        const servers = {};
+        for (const [name, mcp] of this.mcps) {
+            try {
+                await mcp.client.ping();
+                servers[name] = {
+                    status: "up",
+                    tools: mcp.tools.length,
+                    resources: mcp.resources.length,
+                    prompts: mcp.prompts.length,
+                };
+            }
+            catch {
+                servers[name] = {
+                    status: "down",
+                    tools: mcp.tools.length,
+                    resources: mcp.resources.length,
+                    prompts: mcp.prompts.length,
+                };
+            }
+        }
+        return { servers };
+    }
+    async callTool(toolName, args) {
+        const mcpName = this.toolToMcp.get(toolName);
+        if (!mcpName) {
+            logger.warn(`Unknown tool called: ${toolName}`);
+            throw new Error(`Unknown tool: ${toolName}`);
+        }
+        const mcp = this.mcps.get(mcpName);
+        if (!mcp) {
+            logger.error({ mcpName }, `MCP not found for tool: ${toolName}`);
+            throw new Error(`MCP not found: ${mcpName}`);
+        }
+        // Strip namespace prefix to get original tool name
+        const originalName = this.useNamespacing
+            ? stripNamespace(mcpName, toolName)
+            : toolName;
+        logger.info({ args }, `Tool call: ${toolName}`);
+        const startTime = Date.now();
+        const result = await mcp.client.callTool({
+            name: originalName,
+            arguments: args,
+        });
+        const duration = Date.now() - startTime;
+        logger.info({
+            duration: `${duration}ms`,
+            isError: result.isError ?? false,
+        }, `Tool result: ${toolName}`);
+        return result;
+    }
+    async readResource(resourceUri) {
+        const mcpName = this.resourceToMcp.get(resourceUri);
+        if (!mcpName) {
+            logger.warn(`Unknown resource: ${resourceUri}`);
+            throw new Error(`Unknown resource: ${resourceUri}`);
+        }
+        const mcp = this.mcps.get(mcpName);
+        if (!mcp) {
+            logger.error({ mcpName }, `MCP not found for resource: ${resourceUri}`);
+            throw new Error(`MCP not found: ${mcpName}`);
+        }
+        // Strip namespace prefix to get original URI
+        const originalUri = this.useNamespacing
+            ? stripNamespace(mcpName, resourceUri)
+            : resourceUri;
+        logger.info(`Resource read: ${resourceUri}`);
+        const startTime = Date.now();
+        const result = await mcp.client.readResource({ uri: originalUri });
+        const duration = Date.now() - startTime;
+        logger.info({ duration: `${duration}ms` }, `Resource result: ${resourceUri}`);
+        return result;
+    }
+    async getPrompt(promptName, args) {
+        const mcpName = this.promptToMcp.get(promptName);
+        if (!mcpName) {
+            logger.warn(`Unknown prompt: ${promptName}`);
+            throw new Error(`Unknown prompt: ${promptName}`);
+        }
+        const mcp = this.mcps.get(mcpName);
+        if (!mcp) {
+            logger.error({ mcpName }, `MCP not found for prompt: ${promptName}`);
+            throw new Error(`MCP not found: ${mcpName}`);
+        }
+        // Strip namespace prefix to get original name
+        const originalName = this.useNamespacing
+            ? stripNamespace(mcpName, promptName)
+            : promptName;
+        logger.info({ args }, `Prompt get: ${promptName}`);
+        const startTime = Date.now();
+        const result = await mcp.client.getPrompt({
+            name: originalName,
+            arguments: args,
+        });
+        const duration = Date.now() - startTime;
+        logger.info({ duration: `${duration}ms` }, `Prompt result: ${promptName}`);
+        return result;
+    }
+    async complete(ref, argument) {
+        const { mcpName, originalRef } = this.resolveCompletionRef(ref);
+        const mcp = this.mcps.get(mcpName);
+        if (!mcp) {
+            logger.error({ mcpName }, "MCP not found for completion");
+            throw new Error(`MCP not found: ${mcpName}`);
+        }
+        logger.info({ ref, argument }, "Completion request");
+        const startTime = Date.now();
+        const result = await mcp.client.complete({ ref: originalRef, argument });
+        const duration = Date.now() - startTime;
+        logger.info({ duration: `${duration}ms` }, "Completion result");
+        return result;
+    }
+    resolveCompletionRef(ref) {
+        if (ref.type === "ref/prompt" && ref.name) {
+            const mcpName = this.promptToMcp.get(ref.name);
+            if (!mcpName) {
+                logger.warn(`Unknown prompt for completion: ${ref.name}`);
+                throw new Error(`Unknown prompt: ${ref.name}`);
+            }
+            const originalName = this.useNamespacing
+                ? stripNamespace(mcpName, ref.name)
+                : ref.name;
+            return {
+                mcpName,
+                originalRef: { type: "ref/prompt", name: originalName },
+            };
+        }
+        if (ref.type === "ref/resource" && ref.uri) {
+            const mcpName = this.resourceToMcp.get(ref.uri);
+            if (!mcpName) {
+                logger.warn(`Unknown resource for completion: ${ref.uri}`);
+                throw new Error(`Unknown resource: ${ref.uri}`);
+            }
+            const originalUri = this.useNamespacing
+                ? stripNamespace(mcpName, ref.uri)
+                : ref.uri;
+            return {
+                mcpName,
+                originalRef: { type: "ref/resource", uri: originalUri },
+            };
+        }
+        throw new Error(`Invalid completion ref type: ${ref.type}`);
+    }
+}

package/dist/mcp/namespace.d.ts

@@ -0,0 +1,29 @@
+/**
+ * MCP namespace utilities for prefixing and stripping server names
+ * from tool names, resource URIs, and prompt names.
+ *
+ * Format: `serverName__originalName`
+ */
+/**
+ * Add namespace prefix to a name.
+ * @example namespaceName("github", "create_issue") => "github__create_issue"
+ */
+export declare function namespaceName(serverName: string, name: string): string;
+/**
+ * Extract server name from a namespaced name.
+ * Returns null if the name doesn't contain the separator.
+ * @example extractServerName("github__create_issue") => "github"
+ * @example extractServerName("create_issue") => null
+ */
+export declare function extractServerName(namespacedName: string): string | null;
+/**
+ * Strip namespace prefix to get the original name.
+ * @example stripNamespace("github", "github__create_issue") => "create_issue"
+ */
+export declare function stripNamespace(serverName: string, namespacedName: string): string;
+/**
+ * Check if a name is namespaced (contains the separator).
+ * @example isNamespaced("github__create_issue") => true
+ * @example isNamespaced("create_issue") => false
+ */
+export declare function isNamespaced(name: string): boolean;

package/dist/mcp/namespace.js

@@ -0,0 +1,39 @@
+/**
+ * MCP namespace utilities for prefixing and stripping server names
+ * from tool names, resource URIs, and prompt names.
+ *
+ * Format: `serverName__originalName`
+ */
+const SEPARATOR = "__";
+/**
+ * Add namespace prefix to a name.
+ * @example namespaceName("github", "create_issue") => "github__create_issue"
+ */
+export function namespaceName(serverName, name) {
+    return `${serverName}${SEPARATOR}${name}`;
+}
+/**
+ * Extract server name from a namespaced name.
+ * Returns null if the name doesn't contain the separator.
+ * @example extractServerName("github__create_issue") => "github"
+ * @example extractServerName("create_issue") => null
+ */
+export function extractServerName(namespacedName) {
+    const idx = namespacedName.indexOf(SEPARATOR);
+    return idx > 0 ? namespacedName.substring(0, idx) : null;
+}
+/**
+ * Strip namespace prefix to get the original name.
+ * @example stripNamespace("github", "github__create_issue") => "create_issue"
+ */
+export function stripNamespace(serverName, namespacedName) {
+    return namespacedName.substring(serverName.length + SEPARATOR.length);
+}
+/**
+ * Check if a name is namespaced (contains the separator).
+ * @example isNamespaced("github__create_issue") => true
+ * @example isNamespaced("create_issue") => false
+ */
+export function isNamespaced(name) {
+    return name.includes(SEPARATOR);
+}

package/dist/server.d.ts

@@ -0,0 +1,7 @@
+import type { Config } from "./config/types.js";
+import { McpManager } from "./mcp/manager.js";
+export declare function createServer(config: Config): Promise<{
+    server: import("@hono/node-server").ServerType;
+    mcpManager: McpManager;
+    close(): Promise<void>;
+}>;

package/dist/server.js

@@ -0,0 +1,246 @@
+import path from "node:path";
+import { serve } from "@hono/node-server";
+import { Hono } from "hono";
+import { LOGO_PNG_BASE64 } from "./assets.js";
+import { checkApiKey } from "./auth/apikey.js";
+import { OAuthServer } from "./auth/oauth.js";
+import { logger } from "./logger.js";
+import { handleCompletionComplete, handleInitialize, handleInitialized, handleMethodNotFound, handlePing, handlePromptsGet, handlePromptsList, handleResourcesList, handleResourcesRead, handleToolsCall, handleToolsList, } from "./mcp/handlers.js";
+import { McpManager } from "./mcp/manager.js";
+import { MemoryStore } from "./storage/memory.js";
+import { SqliteStore } from "./storage/sqlite.js";
+const LOGO_PNG = Buffer.from(LOGO_PNG_BASE64, "base64");
+async function createStore(config) {
+    if (config.storage?.type === "sqlite") {
+        const dbPath = config.storage.path ?? path.join(process.cwd(), "data", "mcpbox.db");
+        return SqliteStore.create(dbPath);
+    }
+    return new MemoryStore();
+}
+export async function createServer(config) {
+    // Start MCP servers
+    const mcpManager = new McpManager(config.log);
+    await mcpManager.start(config.mcps);
+    // Set up authentication
+    const auth = config.auth;
+    let apiKey;
+    let oauthServer = null;
+    let store = null;
+    if (auth?.type === "apikey") {
+        apiKey = auth.apiKey;
+    }
+    else if (auth?.type === "oauth") {
+        store = await createStore(config);
+        oauthServer = new OAuthServer({
+            issuer: auth.issuer ?? `http://localhost:${config.server.port}`,
+            users: auth.users,
+            clients: auth.clients,
+            dynamicRegistration: auth.dynamic_registration,
+        }, store);
+    }
+    // Warn if storage is configured but not used
+    if (config.storage && auth?.type !== "oauth") {
+        logger.warn("Storage config ignored: only used with OAuth authentication");
+    }
+    const app = new Hono();
+    // Request logging middleware (applies to all routes)
+    app.use("*", async (c, next) => {
+        const start = Date.now();
+        const method = c.req.method;
+        const pathname = new URL(c.req.url).pathname;
+        logger.debug({ method, path: pathname }, "Request received");
+        await next();
+        const duration = Date.now() - start;
+        const status = c.res.status;
+        logger.debug({ method, path: pathname, status, duration: `${duration}ms` }, "Request completed");
+    });
+    // --- Public routes (no auth required) ---
+    app.get("/health", (c) => c.json({ status: "ok" }));
+    app.get("/logo.png", (c) => {
+        c.header("Content-Type", "image/png");
+        return c.body(LOGO_PNG);
+    });
+    app.get("/favicon.ico", (c) => {
+        c.header("Content-Type", "image/png");
+        return c.body(LOGO_PNG);
+    });
+    app.get("/icon.png", (c) => {
+        c.header("Content-Type", "image/png");
+        return c.body(LOGO_PNG);
+    });
+    app.get("/favicon.png", (c) => {
+        c.header("Content-Type", "image/png");
+        return c.body(LOGO_PNG);
+    });
+    if (oauthServer) {
+        // RFC 9728: Protected Resource Metadata
+        app.get("/.well-known/oauth-protected-resource", (c) => {
+            return c.json(oauthServer.getProtectedResourceMetadata());
+        });
+        // RFC 8414: Authorization Server Metadata
+        app.get("/.well-known/oauth-authorization-server", (c) => {
+            return c.json(oauthServer.getAuthorizationServerMetadata());
+        });
+        // Authorization endpoint
+        app.get("/authorize", async (c) => {
+            const query = new URL(c.req.url).searchParams;
+            return oauthServer.handleAuthorize(c, query);
+        });
+        app.post("/authorize", async (c) => {
+            const query = new URL(c.req.url).searchParams;
+            const body = await c.req.text();
+            return oauthServer.handleAuthorize(c, query, body);
+        });
+        // Token endpoint
+        app.post("/token", async (c) => {
+            const body = await c.req.text();
+            return oauthServer.handleToken(c, body);
+        });
+        // Dynamic Client Registration endpoint (RFC 7591)
+        app.post("/register", async (c) => {
+            const body = await c.req.text();
+            return oauthServer.handleRegister(c, body);
+        });
+    }
+    // --- Protected routes (auth required) ---
+    const protectedRoutes = new Hono();
+    // Auth middleware for protected routes
+    protectedRoutes.use("*", async (c, next) => {
+        if (apiKey) {
+            const providedKey = c.req.header("x-api-key") ??
+                c.req.header("authorization")?.replace(/^(Bearer|ApiKey)\s+/i, "");
+            if (!checkApiKey(providedKey, apiKey)) {
+                return c.json({ error: "Unauthorized: Invalid or missing API key" }, 401);
+            }
+        }
+        else if (oauthServer) {
+            const authHeader = c.req.header("authorization");
+            const validation = oauthServer.validateToken(authHeader);
+            if (!validation.valid) {
+                return oauthServer.sendUnauthorized(c, validation.error);
+            }
+            logger.debug({ userId: validation.userId }, "OAuth token validated");
+        }
+        return next();
+    });
+    // MCP handler
+    const handleMcp = async (c) => {
+        let message;
+        try {
+            message = await c.req.json();
+        }
+        catch (e) {
+            logger.warn({ error: e instanceof Error ? e.message : String(e) }, "MCP parse error");
+            return c.json({
+                jsonrpc: "2.0",
+                error: { code: -32700, message: "Parse error" },
+                id: null,
+            }, 400);
+        }
+        const method = "method" in message ? message.method : undefined;
+        const id = "id" in message ? message.id : undefined;
+        logger.debug({ method, id }, "MCP request");
+        if (method === "initialize") {
+            return handleInitialize(c, message);
+        }
+        if (method === "notifications/initialized") {
+            return handleInitialized(c);
+        }
+        if (method === "tools/list") {
+            return handleToolsList(c, message, mcpManager);
+        }
+        if (method === "tools/call") {
+            const params = message.params;
+            return handleToolsCall(c, message, mcpManager, params);
+        }
+        if (method === "resources/list") {
+            return handleResourcesList(c, message, mcpManager);
+        }
+        if (method === "resources/read") {
+            const params = message.params;
+            return handleResourcesRead(c, message, mcpManager, params);
+        }
+        if (method === "prompts/list") {
+            return handlePromptsList(c, message, mcpManager);
+        }
+        if (method === "prompts/get") {
+            const params = message.params;
+            return handlePromptsGet(c, message, mcpManager, params);
+        }
+        if (method === "ping") {
+            return handlePing(c, message);
+        }
+        if (method === "completion/complete") {
+            const params = message.params;
+            return handleCompletionComplete(c, message, mcpManager, params);
+        }
+        return handleMethodNotFound(c, message, method ?? "unknown");
+    };
+    // Status endpoint (protected)
+    protectedRoutes.get("/status", async (c) => {
+        const health = await mcpManager.checkHealth();
+        return c.json({ servers: health.servers });
+    });
+    // MCP endpoints (protected)
+    protectedRoutes.post("/", handleMcp);
+    protectedRoutes.post("/mcp", handleMcp);
+    // Mount protected routes
+    app.route("/", protectedRoutes);
+    // 404 for other routes
+    app.notFound((c) => c.json({ error: "Not found" }, 404));
+    // Error handler
+    app.onError((err, c) => {
+        logger.error({ error: err.message }, "Server error");
+        return c.json({ error: "Internal server error" }, 500);
+    });
+    const server = serve({
+        fetch: app.fetch,
+        port: config.server.port,
+        hostname: "0.0.0.0",
+    }, () => {
+        // Log authentication configuration
+        if (!auth) {
+            logger.warn("No authentication configured");
+        }
+        else if (auth.type === "apikey") {
+            logger.info("Authentication: API key");
+        }
+        else if (auth.type === "oauth") {
+            const userCount = auth.users?.length ?? 0;
+            const clientCount = auth.clients?.length ?? 0;
+            const dynamicReg = auth.dynamic_registration ? "enabled" : "disabled";
+            logger.info({
+                users: userCount,
+                clients: clientCount,
+                dynamicRegistration: dynamicReg,
+            }, "Authentication: OAuth");
+        }
+        logger.info({ port: config.server.port, mcpCount: mcpManager.count }, `mcpbox listening on port ${config.server.port}`);
+    });
+    return {
+        server,
+        mcpManager,
+        async close() {
+            logger.info("Shutting down mcpbox...");
+            await mcpManager.stop();
+            if (oauthServer) {
+                oauthServer.close();
+            }
+            if (store) {
+                await store.close();
+            }
+            return new Promise((resolve, reject) => {
+                server.close((err) => {
+                    if (err) {
+                        logger.error({ error: err.message }, "Error closing server");
+                        reject(err);
+                    }
+                    else {
+                        logger.info("Server closed");
+                        resolve();
+                    }
+                });
+            });
+        },
+    };
+}

package/dist/storage/memory.d.ts

@@ -0,0 +1,20 @@
+import type { StateStore, StoredAccessToken, StoredClient, StoredRefreshToken } from "./types.js";
+export declare class MemoryStore implements StateStore {
+    private clients;
+    private accessTokens;
+    private refreshTokens;
+    constructor();
+    getClient(clientId: string): StoredClient | null;
+    saveClient(client: StoredClient): void;
+    deleteClient(clientId: string): void;
+    getAllDynamicClients(): StoredClient[];
+    getAccessToken(token: string): StoredAccessToken | null;
+    saveAccessToken(token: StoredAccessToken): void;
+    deleteAccessToken(token: string): void;
+    getRefreshToken(token: string): StoredRefreshToken | null;
+    saveRefreshToken(token: StoredRefreshToken): void;
+    deleteRefreshToken(token: string): void;
+    rotateRefreshToken(oldTokenHash: string, newToken: StoredRefreshToken): void;
+    cleanupExpired(): void;
+    close(): void;
+}