@casys/mcp-bridge 0.2.0

package/esm/resource-server/server.js

@@ -0,0 +1,483 @@
+/**
+ * HTTP resource server for MCP Apps Bridge.
+ *
+ * Serves `ui://` resources as HTTP pages, injects bridge.js, sets CSP
+ * headers, and provides a WebSocket endpoint for bidirectional JSON-RPC
+ * communication between the BridgeClient (in the webview) and the MCP server.
+ *
+ * Endpoints:
+ * - `GET /app/<server>/<path>` — Serve MCP App HTML with injected bridge.js
+ * - `GET /bridge.js?platform=<p>&session=<s>` — Serve the bridge client script
+ * - `GET /health` — Health check
+ * - `WS  /bridge?session=<id>` — WebSocket for JSON-RPC messaging
+ *
+ * Uses Deno.serve() for the HTTP server.
+ */
+import { isJsonRpcMessage } from "../core/protocol.js";
+import { buildCspHeader } from "./csp.js";
+import { injectBridgeScript } from "./injector.js";
+import { SessionStore } from "./session.js";
+import { validateTelegramInitData } from "./telegram-auth.js";
+// ---------------------------------------------------------------------------
+// MIME types
+// ---------------------------------------------------------------------------
+const MIME_MAP = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "application/javascript; charset=utf-8",
+    ".mjs": "application/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".svg": "image/svg+xml",
+    ".ico": "image/x-icon",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+    ".ttf": "font/ttf",
+};
+function mimeType(path) {
+    const ext = path.slice(path.lastIndexOf("."));
+    return MIME_MAP[ext] ?? "application/octet-stream";
+}
+/** Normalize a path by resolving `.` and `..` segments without filesystem access. */
+function normalizePath(p) {
+    const parts = p.split("/");
+    const result = [];
+    for (const part of parts) {
+        if (part === "..") {
+            result.pop();
+        }
+        else if (part !== "." && part !== "") {
+            result.push(part);
+        }
+    }
+    return (p.startsWith("/") ? "/" : "") + result.join("/");
+}
+/** Normalize a directory path, ensuring it ends with `/`. */
+function normalizeDir(p) {
+    const n = normalizePath(p);
+    return n.endsWith("/") ? n : n + "/";
+}
+// ---------------------------------------------------------------------------
+// Start server
+// ---------------------------------------------------------------------------
+/**
+ * Start the resource server.
+ *
+ * @returns A running ResourceServer with baseUrl and stop() method.
+ */
+export function startResourceServer(config) {
+    // -----------------------------------------------------------------------
+    // Fail-fast: telegram requires botToken
+    // -----------------------------------------------------------------------
+    if (config.platform === "telegram" && !config.telegramBotToken) {
+        throw new Error("[ResourceServer] telegramBotToken is required when platform is 'telegram'. " +
+            "Provide the Telegram Bot token for initData HMAC-SHA256 validation.");
+    }
+    const requiresAuth = !!config.telegramBotToken;
+    const port = config.options?.resourceServerPort ?? 0;
+    const allowedOrigins = config.options?.allowedOrigins ?? ["*"];
+    const debug = config.options?.debug ?? false;
+    const MAX_SESSIONS = 10_000;
+    const sessions = new SessionStore();
+    const wsConnections = new Map();
+    // Tool result store: ref -> data (auto-expires after 5 min)
+    const toolResultStore = new Map();
+    const toolResultTimers = new Map();
+    const TOOL_RESULT_TTL = 5 * 60 * 1000;
+    function storeToolResult(result) {
+        const ref = generateRef();
+        toolResultStore.set(ref, result);
+        const timer = setTimeout(() => {
+            toolResultStore.delete(ref);
+            toolResultTimers.delete(ref);
+        }, TOOL_RESULT_TTL);
+        toolResultTimers.set(ref, timer);
+        return ref;
+    }
+    function consumeToolResult(ref) {
+        const result = toolResultStore.get(ref);
+        if (result) {
+            toolResultStore.delete(ref);
+            const timer = toolResultTimers.get(ref);
+            if (timer) {
+                clearTimeout(timer);
+                toolResultTimers.delete(ref);
+            }
+        }
+        return result;
+    }
+    // Periodic session cleanup + stale WebSocket eviction
+    const cleanupInterval = setInterval(() => {
+        const removed = sessions.cleanup();
+        if (removed > 0) {
+            log("Cleaned up", removed, "expired session(s)");
+        }
+        // Close WebSocket connections whose session has expired
+        for (const [sessionId, ws] of wsConnections) {
+            if (!sessions.get(sessionId)) {
+                log("Closing stale WebSocket:", sessionId);
+                try {
+                    ws.close(4002, "Session expired");
+                }
+                catch { /* already closed */ }
+                wsConnections.delete(sessionId);
+            }
+        }
+    }, 60_000);
+    function log(...args) {
+        if (debug) {
+            console.log("[ResourceServer]", ...args);
+        }
+    }
+    function corsHeaders(request) {
+        let origin;
+        if (allowedOrigins.includes("*")) {
+            origin = "*";
+        }
+        else if (request) {
+            // Reflect the request origin if it's in the allowlist (HTTP spec: only one origin allowed)
+            const reqOrigin = request.headers.get("origin") ?? "";
+            origin = allowedOrigins.includes(reqOrigin) ? reqOrigin : allowedOrigins[0];
+        }
+        else {
+            origin = allowedOrigins[0];
+        }
+        return {
+            "Access-Control-Allow-Origin": origin,
+            "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+            "Access-Control-Allow-Headers": "Content-Type",
+        };
+    }
+    async function handleRequest(request) {
+        const url = new URL(request.url);
+        const path = url.pathname;
+        log(request.method, path);
+        // CORS preflight
+        if (request.method === "OPTIONS") {
+            return new Response(null, { status: 204, headers: corsHeaders(request) });
+        }
+        // Health check
+        if (path === "/health") {
+            return Response.json({ status: "ok", sessions: sessions.size }, { headers: corsHeaders(request) });
+        }
+        // Serve bridge.js client script
+        if (path === "/bridge.js") {
+            return await serveBridgeScript(corsHeaders(request));
+        }
+        // Session creation (rate-limited to prevent memory exhaustion DoS)
+        if (path === "/session" && request.method === "POST") {
+            if (sessions.size >= MAX_SESSIONS) {
+                log("Session creation rejected: max sessions reached (", MAX_SESSIONS, ")");
+                return new Response("Too many active sessions", { status: 429, headers: corsHeaders(request) });
+            }
+            const session = sessions.create(config.platform);
+            log("Session created:", session.id);
+            return Response.json({ sessionId: session.id }, { headers: corsHeaders(request) });
+        }
+        // WebSocket bridge endpoint
+        if (path === "/bridge") {
+            const sessionId = url.searchParams.get("session");
+            if (!sessionId) {
+                return new Response("Missing session parameter", { status: 400 });
+            }
+            // Session must exist (created via POST /session or HTML page load)
+            const session = sessions.get(sessionId);
+            if (!session) {
+                return new Response("Unknown or expired session. Create one via POST /session first.", { status: 403 });
+            }
+            const upgrade = request.headers.get("upgrade")?.toLowerCase();
+            if (upgrade !== "websocket") {
+                return new Response("Expected WebSocket upgrade", { status: 426 });
+            }
+            // deno-lint-ignore no-explicit-any
+            const { socket, response } = Deno.upgradeWebSocket(request);
+            socket.onopen = () => {
+                wsConnections.set(sessionId, socket);
+                sessions.touch(sessionId);
+                log("WebSocket connected:", sessionId);
+                // Flush pending notifications immediately — bridge.js queues
+                // them until the app has called ui/initialize, then replays.
+                if (session.pendingNotifications && session.pendingNotifications.length > 0) {
+                    const pending = session.pendingNotifications;
+                    session.pendingNotifications = undefined;
+                    for (const notification of pending) {
+                        if (socket.readyState === 1 /* OPEN */) {
+                            const payload = JSON.stringify(notification);
+                            log("Flushing pending notification:", notification.method);
+                            socket.send(payload);
+                        }
+                    }
+                }
+            };
+            socket.onmessage = async (event) => {
+                sessions.touch(sessionId);
+                try {
+                    const data = typeof event.data === "string"
+                        ? JSON.parse(event.data)
+                        : event.data;
+                    // -------------------------------------------------------------------
+                    // Auth-on-first-message: handle auth before any JSON-RPC
+                    // -------------------------------------------------------------------
+                    if (requiresAuth && !session.authenticated) {
+                        if (data && data.type === "auth" && typeof data.initData === "string") {
+                            const authResult = await validateTelegramInitData(data.initData, config.telegramBotToken);
+                            if (authResult.valid) {
+                                session.authenticated = true;
+                                session.userId = authResult.userId;
+                                session.username = authResult.username;
+                                log("Authenticated session", sessionId, "userId:", authResult.userId);
+                                if (socket.readyState === 1) {
+                                    socket.send(JSON.stringify({ type: "auth_ok", userId: authResult.userId }));
+                                }
+                            }
+                            else {
+                                log("Auth failed for", sessionId, ":", authResult.error);
+                                if (socket.readyState === 1) {
+                                    socket.send(JSON.stringify({ type: "auth_error", error: authResult.error }));
+                                    socket.close(4001, "Authentication failed");
+                                }
+                            }
+                            return;
+                        }
+                        // Non-auth message on unauthenticated session — reject
+                        log("Unauthenticated message from", sessionId, "— closing");
+                        if (socket.readyState === 1) {
+                            socket.send(JSON.stringify({ type: "auth_error", error: "Authentication required. Send { type: 'auth', initData: '...' } first." }));
+                            socket.close(4003, "Authentication required");
+                        }
+                        return;
+                    }
+                    // -------------------------------------------------------------------
+                    // Normal JSON-RPC message handling (authenticated or auth not required)
+                    // -------------------------------------------------------------------
+                    if (!isJsonRpcMessage(data)) {
+                        log("Non-JSON-RPC message from", sessionId);
+                        return;
+                    }
+                    const message = data;
+                    log("Received from", sessionId, ":", message.method ?? "response");
+                    if (config.onMessage) {
+                        const response = await config.onMessage(session, message);
+                        if (response && socket.readyState === 1 /* OPEN */) {
+                            socket.send(JSON.stringify(response));
+                        }
+                    }
+                }
+                catch (err) {
+                    log("Error handling message from", sessionId, ":", err);
+                }
+            };
+            socket.onclose = () => {
+                wsConnections.delete(sessionId);
+                log("WebSocket disconnected:", sessionId);
+            };
+            socket.onerror = (e) => {
+                log("WebSocket error:", sessionId, e);
+            };
+            return response;
+        }
+        // Serve MCP App assets: /app/<server>/<path>
+        if (path.startsWith("/app/")) {
+            return await serveAppAsset(path.slice(5), config, corsHeaders(request));
+        }
+        // Custom HTTP request handler (proxy, additional routes, etc.)
+        if (config.onHttpRequest) {
+            const result = await config.onHttpRequest(request);
+            if (result) {
+                if (result instanceof Response) {
+                    return result;
+                }
+                // { html, pendingNotifications? } — inject bridge.js, create session, set CSP
+                // The original request is passed so serveProxiedHtml can auto-resolve ?ref=
+                return serveProxiedHtml(result.html, config, corsHeaders(request), request, result.pendingNotifications);
+            }
+        }
+        return new Response("Not Found", { status: 404, headers: corsHeaders(request) });
+    }
+    async function serveAppAsset(assetPath, cfg, headers) {
+        // Parse: <server>/<file-path>
+        const slashIdx = assetPath.indexOf("/");
+        if (slashIdx < 0) {
+            return new Response("Invalid asset path", { status: 400, headers });
+        }
+        const serverName = assetPath.slice(0, slashIdx);
+        const filePath = assetPath.slice(slashIdx + 1) || "index.html";
+        const baseDir = cfg.assetDirectories[serverName];
+        if (!baseDir) {
+            return new Response(`Unknown app server: ${serverName}`, {
+                status: 404,
+                headers,
+            });
+        }
+        // Prevent path traversal: normalize both paths and compare
+        const normalizedBase = normalizeDir(baseDir);
+        const resolved = normalizePath(`${normalizedBase}/${filePath}`);
+        if (!resolved.startsWith(normalizedBase)) {
+            return new Response("Forbidden", { status: 403, headers });
+        }
+        try {
+            const mime = mimeType(filePath);
+            const isText = mime.startsWith("text/") ||
+                mime.startsWith("application/javascript") ||
+                mime.startsWith("application/json") ||
+                mime.startsWith("image/svg+xml");
+            if (isText) {
+                const content = await Deno.readTextFile(resolved);
+                // For HTML files, inject bridge script and set CSP
+                if (mime.startsWith("text/html")) {
+                    const session = sessions.create(cfg.platform);
+                    const bridgeScriptUrl = `/bridge.js?platform=${cfg.platform}&session=${session.id}`;
+                    const injected = injectBridgeScript(content, bridgeScriptUrl);
+                    const cspHeader = buildCspHeader(cfg.csp);
+                    return new Response(injected, {
+                        status: 200,
+                        headers: {
+                            ...headers,
+                            "Content-Type": mime,
+                            "Content-Security-Policy": cspHeader,
+                        },
+                    });
+                }
+                return new Response(content, {
+                    status: 200,
+                    headers: { ...headers, "Content-Type": mime },
+                });
+            }
+            // Binary files (images, fonts, etc.)
+            const content = await Deno.readFile(resolved);
+            return new Response(content, {
+                status: 200,
+                headers: { ...headers, "Content-Type": mime },
+            });
+        }
+        catch (err) {
+            log("Asset not found:", resolved, err instanceof Error ? err.message : err);
+            return new Response("File not found", { status: 404, headers });
+        }
+    }
+    /**
+     * Serve externally-fetched HTML with bridge.js injection.
+     * Creates a session, injects bridge script, and sets CSP — same as local assets.
+     *
+     * Automatically checks for a `?ref=` query parameter on the original request.
+     * If found, looks up the stored tool result and builds a
+     * `ui/notifications/tool-result` notification buffered on the session.
+     *
+     * Additional `notifications` (from the `onHttpRequest` handler) are also
+     * buffered. The `?ref=` auto-notification is prepended before any extras.
+     */
+    function serveProxiedHtml(html, cfg, headers, originalRequest, notifications) {
+        const session = sessions.create(cfg.platform);
+        // Auto-resolve ?ref= from the original request URL
+        const allNotifications = [];
+        if (originalRequest) {
+            const reqUrl = new URL(originalRequest.url);
+            const dataRef = reqUrl.searchParams.get("ref");
+            if (dataRef) {
+                const toolResult = consumeToolResult(dataRef);
+                if (toolResult) {
+                    log("Auto-attaching tool-result for ref=" + dataRef);
+                    allNotifications.push(buildToolResultFromData(toolResult));
+                }
+            }
+        }
+        if (notifications && notifications.length > 0) {
+            allNotifications.push(...notifications);
+        }
+        if (allNotifications.length > 0) {
+            session.pendingNotifications = allNotifications;
+            log("Buffered", allNotifications.length, "notification(s) for session", session.id);
+        }
+        const bridgeScriptUrl = `/bridge.js?platform=${cfg.platform}&session=${session.id}`;
+        const injected = injectBridgeScript(html, bridgeScriptUrl);
+        const cspHeader = buildCspHeader(cfg.csp);
+        return new Response(injected, {
+            status: 200,
+            headers: {
+                ...headers,
+                "Content-Type": "text/html; charset=utf-8",
+                "Content-Security-Policy": cspHeader,
+            },
+        });
+    }
+    // Resolve the path to bridge.js relative to this module
+    const bridgeJsPath = new URL("../client/bridge.js", import.meta.url);
+    async function serveBridgeScript(headers) {
+        try {
+            const content = await (await fetch(bridgeJsPath)).text();
+            return new Response(content, {
+                status: 200,
+                headers: {
+                    ...headers,
+                    "Content-Type": "application/javascript; charset=utf-8",
+                    "Cache-Control": "no-cache",
+                },
+            });
+        }
+        catch (err) {
+            log("Failed to serve bridge.js:", err instanceof Error ? err.message : err);
+            return new Response("bridge.js not found", { status: 500, headers });
+        }
+    }
+    // Start the server
+    // deno-lint-ignore no-explicit-any
+    const server = Deno.serve({
+        port,
+        handler: handleRequest,
+        onListen: (addr) => {
+            log(`Listening on http://localhost:${addr.port}`);
+        },
+    });
+    // Wait for the server to be ready and get the actual port
+    // Deno.serve returns a server with addr
+    const addr = server.addr;
+    const actualPort = addr?.port ?? port;
+    const baseUrl = `http://localhost:${actualPort}`;
+    return {
+        baseUrl,
+        sessions,
+        storeToolResult,
+        consumeToolResult,
+        async stop() {
+            clearInterval(cleanupInterval);
+            // Close all WebSocket connections
+            for (const [, ws] of wsConnections) {
+                try {
+                    ws.close();
+                }
+                catch (err) {
+                    log("Error closing WebSocket:", err instanceof Error ? err.message : err);
+                }
+            }
+            wsConnections.clear();
+            sessions.clear();
+            // Clear tool result timers to prevent leaks
+            for (const timer of toolResultTimers.values()) {
+                clearTimeout(timer);
+            }
+            toolResultTimers.clear();
+            toolResultStore.clear();
+            await server.shutdown();
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Generate a random ref ID (32 hex chars = 128 bits of entropy). */
+function generateRef() {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+/** Build a `ui/notifications/tool-result` pending notification from ToolResultData. */
+export function buildToolResultFromData(data) {
+    return {
+        jsonrpc: "2.0",
+        method: "ui/notifications/tool-result",
+        params: data,
+    };
+}

package/esm/resource-server/session.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Session management for the resource server.
+ *
+ * Each connected webview gets a session that tracks:
+ * - The platform type
+ * - The current tool context (if a tool call is in flight)
+ * - Activity timestamps for cleanup
+ */
+/** A JSON-RPC notification to be sent to the app when the WebSocket connects. */
+export interface PendingNotification {
+    readonly jsonrpc: "2.0";
+    readonly method: string;
+    readonly params?: Record<string, unknown>;
+}
+/** A bridge session representing one connected webview. */
+export interface BridgeSession {
+    /** Unique session ID. */
+    readonly id: string;
+    /** Platform identifier (e.g. "telegram", "line"). */
+    readonly platform: string;
+    /** When the session was created (Unix ms). */
+    readonly createdAt: number;
+    /** Last activity timestamp (Unix ms). Updated on each message. */
+    lastActivity: number;
+    /** Whether the session has been authenticated (e.g. Telegram initData validated). */
+    authenticated: boolean;
+    /** Telegram user ID (set after successful auth). */
+    userId?: number;
+    /** Telegram username (set after successful auth). */
+    username?: string;
+    /** Notifications to send when the WebSocket connects (e.g. tool-result). */
+    pendingNotifications?: PendingNotification[];
+}
+/**
+ * In-memory session store.
+ *
+ * Sessions are created when a webview connects via WebSocket and
+ * cleaned up when the connection closes or after a timeout.
+ */
+export declare class SessionStore {
+    private readonly sessions;
+    private readonly maxAge;
+    /** @param maxAgeMs - Session TTL in ms. Defaults to 30 minutes. */
+    constructor(maxAgeMs?: number);
+    /** Create a new session. */
+    create(platform: string): BridgeSession;
+    /** Get a session by ID. Returns undefined if not found or expired. */
+    get(id: string): BridgeSession | undefined;
+    /** Update the last activity timestamp. */
+    touch(id: string): void;
+    /** Remove a session. */
+    remove(id: string): boolean;
+    /** Remove all expired sessions. */
+    cleanup(): number;
+    /** Number of active sessions. */
+    get size(): number;
+    /** Clear all sessions. */
+    clear(): void;
+}
+//# sourceMappingURL=session.d.ts.map

package/esm/resource-server/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/resource-server/session.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED,2DAA2D;AAC3D,MAAM,WAAW,aAAa;IAC5B,yBAAyB;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAC;IACrB,qFAAqF;IACrF,aAAa,EAAE,OAAO,CAAC;IACvB,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,oBAAoB,CAAC,EAAE,mBAAmB,EAAE,CAAC;CAC9C;AAED;;;;;GAKG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoC;IAC7D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC,mEAAmE;gBACvD,QAAQ,SAAiB;IAIrC,4BAA4B;IAC5B,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa;IAcvC,sEAAsE;IACtE,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAY1C,0CAA0C;IAC1C,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAOvB,wBAAwB;IACxB,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAI3B,mCAAmC;IACnC,OAAO,IAAI,MAAM;IAYjB,iCAAiC;IACjC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,0BAA0B;IAC1B,KAAK,IAAI,IAAI;CAGd"}

package/esm/resource-server/session.js

@@ -0,0 +1,86 @@
+/**
+ * Session management for the resource server.
+ *
+ * Each connected webview gets a session that tracks:
+ * - The platform type
+ * - The current tool context (if a tool call is in flight)
+ * - Activity timestamps for cleanup
+ */
+/**
+ * In-memory session store.
+ *
+ * Sessions are created when a webview connects via WebSocket and
+ * cleaned up when the connection closes or after a timeout.
+ */
+export class SessionStore {
+    sessions = new Map();
+    maxAge;
+    /** @param maxAgeMs - Session TTL in ms. Defaults to 30 minutes. */
+    constructor(maxAgeMs = 30 * 60 * 1000) {
+        this.maxAge = maxAgeMs;
+    }
+    /** Create a new session. */
+    create(platform) {
+        const id = generateSessionId();
+        const now = Date.now();
+        const session = {
+            id,
+            platform,
+            createdAt: now,
+            lastActivity: now,
+            authenticated: false,
+        };
+        this.sessions.set(id, session);
+        return session;
+    }
+    /** Get a session by ID. Returns undefined if not found or expired. */
+    get(id) {
+        const session = this.sessions.get(id);
+        if (!session)
+            return undefined;
+        if (Date.now() - session.lastActivity > this.maxAge) {
+            this.sessions.delete(id);
+            return undefined;
+        }
+        return session;
+    }
+    /** Update the last activity timestamp. */
+    touch(id) {
+        const session = this.sessions.get(id);
+        if (session) {
+            session.lastActivity = Date.now();
+        }
+    }
+    /** Remove a session. */
+    remove(id) {
+        return this.sessions.delete(id);
+    }
+    /** Remove all expired sessions. */
+    cleanup() {
+        const now = Date.now();
+        let removed = 0;
+        for (const [id, session] of this.sessions) {
+            if (now - session.lastActivity > this.maxAge) {
+                this.sessions.delete(id);
+                removed++;
+            }
+        }
+        return removed;
+    }
+    /** Number of active sessions. */
+    get size() {
+        return this.sessions.size;
+    }
+    /** Clear all sessions. */
+    clear() {
+        this.sessions.clear();
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function generateSessionId() {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}

package/esm/resource-server/telegram-auth.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Telegram Mini App initData HMAC-SHA256 server-side validation.
+ *
+ * Implements the algorithm documented at:
+ * @see https://core.telegram.org/bots/webapps#validating-data-received-via-the-mini-app
+ *
+ * Uses the Web Crypto API exclusively (works in Deno and Node.js 18+).
+ */
+/** Result of validating Telegram initData. */
+export interface TelegramAuthResult {
+    /** Whether the initData is valid. */
+    readonly valid: boolean;
+    /** Telegram user ID (from the `user` JSON field). */
+    readonly userId?: number;
+    /** Telegram username. */
+    readonly username?: string;
+    /** User's first name. */
+    readonly firstName?: string;
+    /** User's last name. */
+    readonly lastName?: string;
+    /** Parsed auth_date as a Date object. */
+    readonly authDate?: Date;
+    /** Human-readable error message when valid is false. */
+    readonly error?: string;
+}
+/**
+ * Validate Telegram Mini App `initData`.
+ *
+ * Algorithm:
+ *  1. Parse the initData query string.
+ *  2. Extract and remove the `hash` parameter.
+ *  3. Sort remaining key=value pairs alphabetically by key.
+ *  4. Join them with `\n` to form data_check_string.
+ *  5. Derive secret_key = HMAC-SHA256(key="WebAppData", data=botToken).
+ *  6. Compute expected = HMAC-SHA256(key=secret_key, data=data_check_string).
+ *  7. Compare hex(expected) with hash using constant-time comparison.
+ *  8. Check auth_date freshness.
+ *
+ * @param initData - The raw initData query string from Telegram.
+ * @param botToken - The bot token used to sign the data.
+ * @param maxAgeSeconds - Maximum acceptable age of auth_date. Defaults to 86400 (24h).
+ * @returns A promise resolving to the validation result.
+ */
+export declare function validateTelegramInitData(initData: string, botToken: string, maxAgeSeconds?: number): Promise<TelegramAuthResult>;
+//# sourceMappingURL=telegram-auth.d.ts.map

package/esm/resource-server/telegram-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram-auth.d.ts","sourceRoot":"","sources":["../../src/resource-server/telegram-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,8CAA8C;AAC9C,MAAM,WAAW,kBAAkB;IACjC,qCAAqC;IACrC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,qDAAqD;IACrD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,yBAAyB;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,yBAAyB;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,wBAAwB;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC;IACzB,wDAAwD;IACxD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AASD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,aAAa,GAAE,MAAgC,GAC9C,OAAO,CAAC,kBAAkB,CAAC,CA+G7B"}