@opendatalabs/personal-server-ts-core 0.0.1-canary.00328bf

package/dist/mcp/server.js

@@ -0,0 +1,447 @@
+/**
+ * MCP Streamable-HTTP server adapter. Per-request, stateless.
+ *
+ * Pattern adopted from `@pdpp/mcp-server`'s `handleStreamableHttpRequest`:
+ * a fresh `McpServer` + `WebStandardStreamableHTTPServerTransport` per
+ * inbound request. This keeps authorization checks fresh — the route
+ * resolves the connection token, hands us the `McpConnectionRecord`, and we
+ * build the server bound to that connection. There is NO MCP session.
+ *
+ * The transport supports Streamable HTTP (GET=SSE, POST=JSON-RPC,
+ * DELETE=close). Claude Web's remote connector speaks this.
+ */
+import { McpServer, ResourceTemplate, } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { MAX_MCP_TOOL_TIMEOUT_MS, MCP_TOOLS, resolveGrantForScope, } from "./tools.js";
+import { READ_FULFILLMENT_NONE, reportPersonalServerReadDenial, } from "../api/index.js";
+import { RAW_SCOPE_RESOURCE_TEMPLATES, readRawScopeResource, } from "./resources.js";
+const DEFAULT_SERVER_NAME = "vana-personal-server-mcp";
+const DEFAULT_SERVER_VERSION = "0.0.1";
+/** Stateless: no MCP session id is issued and POST answers with JSON, not SSE. */
+const TRANSPORT_OPTIONS = {
+    sessionIdGenerator: undefined,
+    enableJsonResponse: true,
+};
+/** Methods whose answer is the same for every connection: the tool table is a
+ * static constant and no session is retained. e.g. a fresh remote connector
+ * probes with initialize + notifications/initialized + tools/list. */
+const HANDSHAKE_METHODS = new Set([
+    "initialize",
+    "notifications/initialized",
+    "ping",
+    "tools/list",
+]);
+const RAW_SCOPE_RESOURCE_CONFIG = {
+    title: "Raw scope file",
+    description: "Original binary/unstructured file bytes for an approved Vana scope.",
+    mimeType: "application/octet-stream",
+};
+const DEFAULT_MCP_TOOL_TIMEOUT_MS = 30_000;
+const MCP_TOOL_TIMEOUT_GRACE_MS = 1_000;
+const QUERY_PREVIEW_CHARS = 120;
+const textEncoder = new TextEncoder();
+class McpToolTimeoutError extends Error {
+    tool;
+    timeoutMs;
+    constructor(tool, timeoutMs) {
+        super(`${tool} timed out after ${timeoutMs}ms`);
+        this.tool = tool;
+        this.timeoutMs = timeoutMs;
+        this.name = "McpToolTimeoutError";
+    }
+}
+function clampToolTimeout(value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return DEFAULT_MCP_TOOL_TIMEOUT_MS;
+    }
+    return Math.min(MAX_MCP_TOOL_TIMEOUT_MS, Math.max(1000, Math.trunc(value)));
+}
+function toolTimeoutMs(tool, args) {
+    if (tool === "read_scope" ||
+        tool === "search_personal_context" ||
+        tool === "get_scope_file") {
+        return clampToolTimeout(args.timeoutMs) + MCP_TOOL_TIMEOUT_GRACE_MS;
+    }
+    return DEFAULT_MCP_TOOL_TIMEOUT_MS;
+}
+async function withToolTimeout(promise, tool, timeoutMs) {
+    let timeout;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_resolve, reject) => {
+                timeout = setTimeout(() => reject(new McpToolTimeoutError(tool, timeoutMs)), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+    }
+}
+function buildActivityStartParams(tool, args) {
+    const params = {
+        tool,
+    };
+    if ((tool === "read_scope" || tool === "get_scope_file") &&
+        typeof args.scope === "string") {
+        params.scopes = [args.scope];
+    }
+    if (tool === "search_personal_context") {
+        if (typeof args.query === "string") {
+            params.queryPreview = args.query.slice(0, QUERY_PREVIEW_CHARS);
+        }
+        if (Array.isArray(args.scopes) && args.scopes.length > 0) {
+            params.scopes = args.scopes
+                .filter((s) => typeof s === "string")
+                .slice(0, 20);
+        }
+    }
+    return params;
+}
+/**
+ * Tools that reach the owner's data. Only these produce access records — the
+ * discovery tools (`list_granted_*`, `request_scope_access`) touch none.
+ */
+const DATA_TOOLS = new Set([
+    "get_scope_file",
+    "list_scope_blocks",
+    "read_scope",
+    "search_personal_context",
+]);
+/**
+ * Tool error codes that mean "the read was refused", as opposed to a failure
+ * (timeout, storage error). Only these are worth an access record: they are
+ * decisions about the grantee's access, not incidents.
+ */
+const DENY_CODES = new Set([
+    "payment_required",
+    "scope_deleted",
+    "scope_not_granted",
+    "unauthorized",
+]);
+const PAYMENT_REQUIRED_CODE = "payment_required";
+/**
+ * Extract the deny code from a tool result, or undefined when the call was
+ * served or failed for a non-deny reason. `read_scope` signals a chargeable
+ * scope with a top-level `payment_required: true` rather than an error code.
+ */
+function denyCode(result) {
+    if (!result.isError)
+        return undefined;
+    const first = result.content[0];
+    if (first?.type !== "text")
+        return undefined;
+    let body;
+    try {
+        body = JSON.parse(first.text);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof body.error === "string" && DENY_CODES.has(body.error)) {
+        return body.error;
+    }
+    return body[PAYMENT_REQUIRED_CODE] === true
+        ? PAYMENT_REQUIRED_CODE
+        : undefined;
+}
+/**
+ * One access record per denied data tool call. Fire-and-forget by contract:
+ * the tool result is already computed and is returned regardless.
+ */
+function reportToolDenial(options, tool, args, result) {
+    if (!options.reporterDeps || !DATA_TOOLS.has(tool))
+        return;
+    const reason = denyCode(result);
+    if (!reason)
+        return;
+    // The denied scope, if the call named one; a multi-scope search records the
+    // first, since the owner's decision is one record per tool call.
+    const scope = buildActivityStartParams(tool, args).scopes?.[0] ?? READ_FULFILLMENT_NONE;
+    // A refusal is filed under the grant the call arrived on. A scope no grant
+    // covers has no grant of its own, but the connection's grant is the access
+    // relationship the owner's feed groups by — and the Gateway only stores a
+    // 32-byte grant id, so `READ_FULFILLMENT_NONE` here is refused on ingest and
+    // takes its whole batch down with it. A connection left with no grant at all
+    // has nothing to attribute the refusal to, so it reports nothing.
+    const grantId = resolveGrantForScope(options.connection, scope)?.grantId ??
+        options.connection.grants[0]?.grantId;
+    if (!grantId)
+        return;
+    reportPersonalServerReadDenial(options.reporterDeps, {
+        builder: options.connection.granteeAddress,
+        denyReason: reason,
+        grantId,
+        logId: crypto.randomUUID(),
+        outcome: "denied",
+        scope,
+        servedAt: new Date().toISOString(),
+        source: "mcp",
+        tool,
+    });
+}
+function extractActivityFinishParams(tool, result) {
+    if (result.isError || result.content.length === 0) {
+        try {
+            const firstText = result.content[0]?.type === "text" ? result.content[0].text : "{}";
+            const body = JSON.parse(firstText);
+            return {
+                errorCode: typeof body.error === "string" ? body.error : undefined,
+                errorMessage: typeof body.message === "string" ? body.message : undefined,
+            };
+        }
+        catch {
+            return {};
+        }
+    }
+    if (tool === "search_personal_context") {
+        try {
+            const firstText = result.content[0]?.type === "text" ? result.content[0].text : "{}";
+            const body = JSON.parse(firstText);
+            return {
+                resultCount: Array.isArray(body.results)
+                    ? body.results.length
+                    : Array.isArray(body.matches)
+                        ? body.matches.length
+                        : undefined,
+                skippedCount: Array.isArray(body.skippedScopes)
+                    ? body.skippedScopes.length
+                    : undefined,
+            };
+        }
+        catch {
+            return {};
+        }
+    }
+    if (tool === "read_scope") {
+        try {
+            const firstText = result.content[0]?.type === "text" ? result.content[0].text : "{}";
+            const body = JSON.parse(firstText);
+            return {
+                resultCount: Array.isArray(body.blocks)
+                    ? body.blocks.length
+                    : undefined,
+            };
+        }
+        catch {
+            return {};
+        }
+    }
+    return {};
+}
+function bytes(value) {
+    return textEncoder.encode(value).byteLength;
+}
+function estimatePayloadMetrics(result) {
+    const textBytes = result.content?.reduce((total, item) => {
+        if (item.type === "text")
+            return total + bytes(item.text);
+        if (item.type === "resource") {
+            return total + bytes(item.resource.blob);
+        }
+        return total + bytes(JSON.stringify(item));
+    }, 0) ?? 0;
+    // The SDK serializes both text content and structuredContent. Avoid a second
+    // JSON stringify over very large payloads here; the pretty text body is a
+    // conservative estimate for the structured JSON copy created by textResult.
+    const structuredContentBytes = result.structuredContent !== undefined ? textBytes : undefined;
+    return {
+        textBytes,
+        ...(structuredContentBytes !== undefined ? { structuredContentBytes } : {}),
+        payloadBytes: textBytes + (structuredContentBytes ?? 0),
+    };
+}
+function buildErrorResult(body) {
+    return {
+        isError: true,
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(body, null, 2),
+            },
+        ],
+    };
+}
+function markResponsePreparing(recorder, activityId, finish) {
+    recorder.update(activityId, {
+        phase: "response_preparing",
+        handlerDurationMs: finish.handlerDurationMs,
+        payloadBytes: finish.payloadBytes,
+        textBytes: finish.textBytes,
+        structuredContentBytes: finish.structuredContentBytes,
+        resultCount: finish.resultCount,
+        skippedCount: finish.skippedCount,
+        errorCode: finish.errorCode,
+        errorMessage: finish.errorMessage,
+    });
+}
+/** What a client sees of a tool in `tools/list`: owner-independent metadata. */
+function toolConfig(tool) {
+    return {
+        title: tool.title,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+    };
+}
+/**
+ * Build a fresh `McpServer` instance bound to a single connection + read
+ * client. Tools delegate to `MCP_TOOLS` so the surface stays in one place.
+ */
+export function createMcpServerForConnection(options) {
+    const server = new McpServer({
+        name: options.serverName ?? DEFAULT_SERVER_NAME,
+        version: options.serverVersion ?? DEFAULT_SERVER_VERSION,
+    });
+    const pendingActivityFinishes = new Map();
+    const ctx = {
+        connection: options.connection,
+        readClient: options.readClient,
+        activityRecorder: options.activityRecorder,
+        requestScopeAccess: options.requestScopeAccess,
+    };
+    for (const tool of MCP_TOOLS) {
+        server.registerTool(tool.name, toolConfig(tool), async (args) => {
+            const recorder = options.activityRecorder;
+            const activityId = recorder
+                ? recorder.start(buildActivityStartParams(tool.name, args))
+                : undefined;
+            const handlerStartedAt = performance.now();
+            try {
+                const timeoutMs = toolTimeoutMs(tool.name, args);
+                const result = await withToolTimeout(tool.handler(args, ctx), tool.name, timeoutMs);
+                reportToolDenial(options, tool.name, args, result);
+                if (activityId && recorder) {
+                    const handlerDurationMs = Math.round(performance.now() - handlerStartedAt);
+                    const payload = extractActivityFinishParams(tool.name, result);
+                    const finish = {
+                        status: result.isError ? "failed" : "succeeded",
+                        handlerDurationMs,
+                        ...estimatePayloadMetrics(result),
+                        ...payload,
+                    };
+                    markResponsePreparing(recorder, activityId, finish);
+                    pendingActivityFinishes.set(activityId, finish);
+                }
+                return result;
+            }
+            catch (err) {
+                if (err instanceof McpToolTimeoutError) {
+                    const result = buildErrorResult({
+                        error: "tool_timeout",
+                        message: err.message,
+                        timeoutMs: err.timeoutMs,
+                    });
+                    if (activityId && recorder) {
+                        const finish = {
+                            status: "timed_out",
+                            handlerDurationMs: Math.round(performance.now() - handlerStartedAt),
+                            ...estimatePayloadMetrics(result),
+                            errorCode: "tool_timeout",
+                            errorMessage: err.message,
+                        };
+                        markResponsePreparing(recorder, activityId, finish);
+                        pendingActivityFinishes.set(activityId, finish);
+                    }
+                    return result;
+                }
+                const result = buildErrorResult({
+                    error: "tool_handler_error",
+                    message: err instanceof Error ? err.message : String(err),
+                });
+                if (activityId && recorder) {
+                    const finish = {
+                        status: "failed",
+                        handlerDurationMs: Math.round(performance.now() - handlerStartedAt),
+                        ...estimatePayloadMetrics(result),
+                        errorCode: "tool_handler_error",
+                        errorMessage: err instanceof Error ? err.message : String(err),
+                    };
+                    markResponsePreparing(recorder, activityId, finish);
+                    pendingActivityFinishes.set(activityId, finish);
+                }
+                return result;
+            }
+        });
+    }
+    RAW_SCOPE_RESOURCE_TEMPLATES.forEach((template, index) => {
+        server.registerResource(`raw-scope-file-${index}`, new ResourceTemplate(template, { list: undefined }), RAW_SCOPE_RESOURCE_CONFIG, async (uri) => readRawScopeResource(uri, ctx));
+    });
+    function finishPendingActivities(override) {
+        for (const [activityId, finish] of pendingActivityFinishes) {
+            options.activityRecorder?.finish(activityId, {
+                ...finish,
+                ...override,
+            });
+            pendingActivityFinishes.delete(activityId);
+        }
+    }
+    return { server, finishPendingActivities };
+}
+/**
+ * Process one inbound MCP request (GET/POST/DELETE) end-to-end. Per-request
+ * server + transport; stateless; no MCP session id retained.
+ *
+ * Returns a Web `Response` suitable to send back to the client.
+ */
+export async function handleMcpStreamableHttpRequest(request, options) {
+    const { server, finishPendingActivities } = createMcpServerForConnection(options);
+    const transport = new WebStandardStreamableHTTPServerTransport(TRANSPORT_OPTIONS);
+    try {
+        await server.connect(transport);
+        const response = await transport.handleRequest(request);
+        finishPendingActivities();
+        return response;
+    }
+    catch (err) {
+        finishPendingActivities({
+            status: "failed",
+            errorCode: "transport_error",
+            errorMessage: err instanceof Error ? err.message : String(err),
+        });
+        throw err;
+    }
+    finally {
+        await Promise.allSettled([transport.close(), server.close()]);
+    }
+}
+/**
+ * True when every JSON-RPC message in `body` is one this file can answer
+ * without the owner's data — see `HANDSHAKE_METHODS`. A batch qualifies only
+ * as a whole, so a tool call travelling with a handshake still reaches the
+ * owner's server.
+ */
+export function isMcpHandshake(body) {
+    const messages = Array.isArray(body) ? body : [body];
+    return (messages.length > 0 &&
+        messages.every((message) => !!message &&
+            typeof message === "object" &&
+            HANDSHAKE_METHODS.has(message.method)));
+}
+/**
+ * Answer a handshake request from the static tool table. Same server identity,
+ * same registered surface and same transport as the full engine, so the bytes
+ * match what a dispatched call returns; the tool handlers are unreachable
+ * because no handshake method invokes one.
+ */
+export async function handleMcpHandshake(request) {
+    const server = new McpServer({
+        name: DEFAULT_SERVER_NAME,
+        version: DEFAULT_SERVER_VERSION,
+    });
+    const unreachable = () => {
+        throw new Error("Handshake server cannot serve data");
+    };
+    for (const tool of MCP_TOOLS)
+        server.registerTool(tool.name, toolConfig(tool), unreachable);
+    RAW_SCOPE_RESOURCE_TEMPLATES.forEach((template, index) => server.registerResource(`raw-scope-file-${index}`, new ResourceTemplate(template, { list: undefined }), RAW_SCOPE_RESOURCE_CONFIG, unreachable));
+    const transport = new WebStandardStreamableHTTPServerTransport(TRANSPORT_OPTIONS);
+    try {
+        await server.connect(transport);
+        return await transport.handleRequest(request);
+    }
+    finally {
+        await Promise.allSettled([transport.close(), server.close()]);
+    }
+}
+//# sourceMappingURL=server.js.map

package/dist/mcp/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,SAAS,EACT,gBAAgB,GACjB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,wCAAwC,EAAE,MAAM,+DAA+D,CAAC;AAGzH,OAAO,EACL,uBAAuB,EACvB,SAAS,EACT,oBAAoB,GAGrB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,qBAAqB,EACrB,8BAA8B,GAE/B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,4BAA4B,EAC5B,oBAAoB,GACrB,MAAM,gBAAgB,CAAC;AAaxB,MAAM,mBAAmB,GAAG,0BAA0B,CAAC;AACvD,MAAM,sBAAsB,GAAG,OAAO,CAAC;AACvC,kFAAkF;AAClF,MAAM,iBAAiB,GAAG;IACxB,kBAAkB,EAAE,SAAS;IAC7B,kBAAkB,EAAE,IAAI;CAChB,CAAC;AACX;;sEAEsE;AACtE,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC;IAChC,YAAY;IACZ,2BAA2B;IAC3B,MAAM;IACN,YAAY;CACb,CAAC,CAAC;AACH,MAAM,yBAAyB,GAAG;IAChC,KAAK,EAAE,gBAAgB;IACvB,WAAW,EACT,qEAAqE;IACvE,QAAQ,EAAE,0BAA0B;CAC5B,CAAC;AACX,MAAM,2BAA2B,GAAG,MAAM,CAAC;AAC3C,MAAM,yBAAyB,GAAG,KAAK,CAAC;AAExC,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAChC,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC;AAEtC,MAAM,mBAAoB,SAAQ,KAAK;IAEnB;IACA;IAFlB,YACkB,IAAY,EACZ,SAAiB;QAEjC,KAAK,CAAC,GAAG,IAAI,oBAAoB,SAAS,IAAI,CAAC,CAAC;QAHhC,SAAI,GAAJ,IAAI,CAAQ;QACZ,cAAS,GAAT,SAAS,CAAQ;QAGjC,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED,SAAS,gBAAgB,CAAC,KAAc;IACtC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACzD,OAAO,2BAA2B,CAAC;IACrC,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,uBAAuB,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,aAAa,CAAC,IAAY,EAAE,IAA6B;IAChE,IACE,IAAI,KAAK,YAAY;QACrB,IAAI,KAAK,yBAAyB;QAClC,IAAI,KAAK,gBAAgB,EACzB,CAAC;QACD,OAAO,gBAAgB,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,yBAAyB,CAAC;IACtE,CAAC;IACD,OAAO,2BAA2B,CAAC;AACrC,CAAC;AAED,KAAK,UAAU,eAAe,CAC5B,OAAmB,EACnB,IAAY,EACZ,SAAiB;IAEjB,IAAI,OAAkD,CAAC;IACvD,IAAI,CAAC;QACH,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC;YACxB,OAAO;YACP,IAAI,OAAO,CAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE;gBAClC,OAAO,GAAG,UAAU,CAClB,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,mBAAmB,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,EACtD,SAAS,CACV,CAAC;YACJ,CAAC,CAAC;SACH,CAAC,CAAC;IACL,CAAC;YAAS,CAAC;QACT,IAAI,OAAO;YAAE,YAAY,CAAC,OAAO,CAAC,CAAC;IACrC,CAAC;AACH,CAAC;AAED,SAAS,wBAAwB,CAC/B,IAAY,EACZ,IAA6B;IAE7B,MAAM,MAAM,GAA+D;QACzE,IAAI;KACL,CAAC;IACF,IACE,CAAC,IAAI,KAAK,YAAY,IAAI,IAAI,KAAK,gBAAgB,CAAC;QACpD,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,EAC9B,CAAC;QACD,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IACD,IAAI,IAAI,KAAK,yBAAyB,EAAE,CAAC;QACvC,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YACnC,MAAM,CAAC,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,mBAAmB,CAAC,CAAC;QACjE,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzD,MAAM,CAAC,MAAM,GAAI,IAAI,CAAC,MAAoB;iBACvC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;iBACjD,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC;IACzB,gBAAgB;IAChB,mBAAmB;IACnB,YAAY;IACZ,yBAAyB;CAC1B,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC;IACzB,kBAAkB;IAClB,eAAe;IACf,mBAAmB;IACnB,cAAc;CACf,CAAC,CAAC;AAEH,MAAM,qBAAqB,GAAG,kBAAkB,CAAC;AAEjD;;;;GAIG;AACH,SAAS,QAAQ,CAAC,MAGjB;IACC,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAEtC,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAChC,IAAI,KAAK,EAAE,IAAI,KAAK,MAAM;QAAE,OAAO,SAAS,CAAC;IAE7C,IAAI,IAA6B,CAAC;IAClC,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAA4B,CAAC;IAC3D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,IAAI,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACjE,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,OAAO,IAAI,CAAC,qBAAqB,CAAC,KAAK,IAAI;QACzC,CAAC,CAAC,qBAAqB;QACvB,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,SAAS,gBAAgB,CACvB,OAAgC,EAChC,IAAY,EACZ,IAA6B,EAC7B,MAA8D;IAE9D,IAAI,CAAC,OAAO,CAAC,YAAY,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO;IAE3D,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC,MAAM;QAAE,OAAO;IAEpB,4EAA4E;IAC5E,iEAAiE;IACjE,MAAM,KAAK,GACT,wBAAwB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,IAAI,qBAAqB,CAAC;IAE5E,2EAA2E;IAC3E,2EAA2E;IAC3E,0EAA0E;IAC1E,6EAA6E;IAC7E,6EAA6E;IAC7E,kEAAkE;IAClE,MAAM,OAAO,GACX,oBAAoB,CAAC,OAAO,CAAC,UAAU,EAAE,KAAK,CAAC,EAAE,OAAO;QACxD,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC;IACxC,IAAI,CAAC,OAAO;QAAE,OAAO;IAErB,8BAA8B,CAAC,OAAO,CAAC,YAAY,EAAE;QACnD,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,cAAc;QAC1C,UAAU,EAAE,MAAM;QAClB,OAAO;QACP,KAAK,EAAE,MAAM,CAAC,UAAU,EAAE;QAC1B,OAAO,EAAE,QAAQ;QACjB,KAAK;QACL,QAAQ,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAClC,MAAM,EAAE,KAAK;QACb,IAAI;KACL,CAAC,CAAC;AACL,CAAC;AAED,SAAS,2BAA2B,CAClC,IAAY,EACZ,MAA8D;IAO9D,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,IAAI,CAAC;YACH,MAAM,SAAS,GACb,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;YACrE,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAA4B,CAAC;YAC9D,OAAO;gBACL,SAAS,EAAE,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;gBAClE,YAAY,EACV,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;aAC9D,CAAC;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IACD,IAAI,IAAI,KAAK,yBAAyB,EAAE,CAAC;QACvC,IAAI,CAAC;YACH,MAAM,SAAS,GACb,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;YACrE,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAA4B,CAAC;YAC9D,OAAO;gBACL,WAAW,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC;oBACtC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM;oBACrB,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC;wBAC3B,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM;wBACrB,CAAC,CAAC,SAAS;gBACf,YAAY,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC;oBAC7C,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM;oBAC3B,CAAC,CAAC,SAAS;aACd,CAAC;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IACD,IAAI,IAAI,KAAK,YAAY,EAAE,CAAC;QAC1B,IAAI,CAAC;YACH,MAAM,SAAS,GACb,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;YACrE,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAA4B,CAAC;YAC9D,OAAO;gBACL,WAAW,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC;oBACrC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM;oBACpB,CAAC,CAAC,SAAS;aACd,CAAC;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAiBD,SAAS,KAAK,CAAC,KAAa;IAC1B,OAAO,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,UAAU,CAAC;AAC9C,CAAC;AAED,SAAS,sBAAsB,CAAC,MAG/B;IACC,MAAM,SAAS,GACb,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;QACrC,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM;YAAE,OAAO,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1D,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAC7B,OAAO,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC3C,CAAC;QACD,OAAO,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;IAC7C,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IACb,6EAA6E;IAC7E,0EAA0E;IAC1E,4EAA4E;IAC5E,MAAM,sBAAsB,GAC1B,MAAM,CAAC,iBAAiB,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;IACjE,OAAO;QACL,SAAS;QACT,GAAG,CAAC,sBAAsB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,sBAAsB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3E,YAAY,EAAE,SAAS,GAAG,CAAC,sBAAsB,IAAI,CAAC,CAAC;KACxD,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CAAC,IAA6B;IAIrD,OAAO;QACL,OAAO,EAAE,IAAI;QACb,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;aACpC;SACF;KACF,CAAC;AACJ,CAAC;AAED,SAAS,qBAAqB,CAC5B,QAA6B,EAC7B,UAAkB,EAClB,MAA6B;IAE7B,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE;QAC1B,KAAK,EAAE,oBAAoB;QAC3B,iBAAiB,EAAE,MAAM,CAAC,iBAAiB;QAC3C,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,sBAAsB,EAAE,MAAM,CAAC,sBAAsB;QACrD,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,YAAY,EAAE,MAAM,CAAC,YAAY;KAClC,CAAC,CAAC;AACL,CAAC;AAED,gFAAgF;AAChF,SAAS,UAAU,CAAC,IAAgC;IAClD,OAAO;QACL,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;KAC9B,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,4BAA4B,CAC1C,OAAgC;IAUhC,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,OAAO,CAAC,UAAU,IAAI,mBAAmB;QAC/C,OAAO,EAAE,OAAO,CAAC,aAAa,IAAI,sBAAsB;KACzD,CAAC,CAAC;IACH,MAAM,uBAAuB,GAAG,IAAI,GAAG,EAAiC,CAAC;IAEzE,MAAM,GAAG,GAAmB;QAC1B,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,gBAAgB,EAAE,OAAO,CAAC,gBAAgB;QAC1C,kBAAkB,EAAE,OAAO,CAAC,kBAAkB;KAC/C,CAAC;IAEF,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QAC7B,MAAM,CAAC,YAAY,CACjB,IAAI,CAAC,IAAI,EACT,UAAU,CAAC,IAAI,CAAC,EAChB,KAAK,EAAE,IAA6B,EAAE,EAAE;YACtC,MAAM,QAAQ,GAAG,OAAO,CAAC,gBAAgB,CAAC;YAC1C,MAAM,UAAU,GAAG,QAAQ;gBACzB,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,wBAAwB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;gBAC3D,CAAC,CAAC,SAAS,CAAC;YACd,MAAM,gBAAgB,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;YAC3C,IAAI,CAAC;gBACH,MAAM,SAAS,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;gBACjD,MAAM,MAAM,GAAG,MAAM,eAAe,CAClC,IAAI,CAAC,OAAO,CAAC,IAA+B,EAAE,GAAG,CAAC,EAClD,IAAI,CAAC,IAAI,EACT,SAAS,CACV,CAAC;gBACF,gBAAgB,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;gBACnD,IAAI,UAAU,IAAI,QAAQ,EAAE,CAAC;oBAC3B,MAAM,iBAAiB,GAAG,IAAI,CAAC,KAAK,CAClC,WAAW,CAAC,GAAG,EAAE,GAAG,gBAAgB,CACrC,CAAC;oBACF,MAAM,OAAO,GAAG,2BAA2B,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;oBAC/D,MAAM,MAAM,GAA0B;wBACpC,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW;wBAC/C,iBAAiB;wBACjB,GAAG,sBAAsB,CAAC,MAAM,CAAC;wBACjC,GAAG,OAAO;qBACX,CAAC;oBACF,qBAAqB,CAAC,QAAQ,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;oBACpD,uBAAuB,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;gBAClD,CAAC;gBACD,OAAO,MAAM,CAAC;YAChB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,GAAG,YAAY,mBAAmB,EAAE,CAAC;oBACvC,MAAM,MAAM,GAAG,gBAAgB,CAAC;wBAC9B,KAAK,EAAE,cAAc;wBACrB,OAAO,EAAE,GAAG,CAAC,OAAO;wBACpB,SAAS,EAAE,GAAG,CAAC,SAAS;qBACzB,CAAC,CAAC;oBACH,IAAI,UAAU,IAAI,QAAQ,EAAE,CAAC;wBAC3B,MAAM,MAAM,GAA0B;4BACpC,MAAM,EAAE,WAAW;4BACnB,iBAAiB,EAAE,IAAI,CAAC,KAAK,CAC3B,WAAW,CAAC,GAAG,EAAE,GAAG,gBAAgB,CACrC;4BACD,GAAG,sBAAsB,CAAC,MAAM,CAAC;4BACjC,SAAS,EAAE,cAAc;4BACzB,YAAY,EAAE,GAAG,CAAC,OAAO;yBAC1B,CAAC;wBACF,qBAAqB,CAAC,QAAQ,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;wBACpD,uBAAuB,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;oBAClD,CAAC;oBACD,OAAO,MAAM,CAAC;gBAChB,CAAC;gBACD,MAAM,MAAM,GAAG,gBAAgB,CAAC;oBAC9B,KAAK,EAAE,oBAAoB;oBAC3B,OAAO,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;iBAC1D,CAAC,CAAC;gBACH,IAAI,UAAU,IAAI,QAAQ,EAAE,CAAC;oBAC3B,MAAM,MAAM,GAA0B;wBACpC,MAAM,EAAE,QAAQ;wBAChB,iBAAiB,EAAE,IAAI,CAAC,KAAK,CAC3B,WAAW,CAAC,GAAG,EAAE,GAAG,gBAAgB,CACrC;wBACD,GAAG,sBAAsB,CAAC,MAAM,CAAC;wBACjC,SAAS,EAAE,oBAAoB;wBAC/B,YAAY,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;qBAC/D,CAAC;oBACF,qBAAqB,CAAC,QAAQ,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;oBACpD,uBAAuB,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;gBAClD,CAAC;gBACD,OAAO,MAAM,CAAC;YAChB,CAAC;QACH,CAAC,CACF,CAAC;IACJ,CAAC;IAED,4BAA4B,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,KAAK,EAAE,EAAE;QACvD,MAAM,CAAC,gBAAgB,CACrB,kBAAkB,KAAK,EAAE,EACzB,IAAI,gBAAgB,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,EACnD,yBAAyB,EACzB,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,oBAAoB,CAAC,GAAG,EAAE,GAAG,CAAC,CAC9C,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,SAAS,uBAAuB,CAC9B,QAGC;QAED,KAAK,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,IAAI,uBAAuB,EAAE,CAAC;YAC3D,OAAO,CAAC,gBAAgB,EAAE,MAAM,CAAC,UAAU,EAAE;gBAC3C,GAAG,MAAM;gBACT,GAAG,QAAQ;aACZ,CAAC,CAAC;YACH,uBAAuB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,uBAAuB,EAAE,CAAC;AAC7C,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,8BAA8B,CAClD,OAAgB,EAChB,OAAgC;IAEhC,MAAM,EAAE,MAAM,EAAE,uBAAuB,EAAE,GACvC,4BAA4B,CAAC,OAAO,CAAC,CAAC;IACxC,MAAM,SAAS,GAAG,IAAI,wCAAwC,CAC5D,iBAAiB,CAClB,CAAC;IAEF,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAChC,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;QACxD,uBAAuB,EAAE,CAAC;QAC1B,OAAO,QAAQ,CAAC;IAClB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,uBAAuB,CAAC;YACtB,MAAM,EAAE,QAAQ;YAChB,SAAS,EAAE,iBAAiB;YAC5B,YAAY,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;SAC/D,CAAC,CAAC;QACH,MAAM,GAAG,CAAC;IACZ,CAAC;YAAS,CAAC;QACT,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC,SAAS,CAAC,KAAK,EAAE,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAChE,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,IAAa;IAC1C,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACrD,OAAO,CACL,QAAQ,CAAC,MAAM,GAAG,CAAC;QACnB,QAAQ,CAAC,KAAK,CACZ,CAAC,OAAO,EAAE,EAAE,CACV,CAAC,CAAC,OAAO;YACT,OAAO,OAAO,KAAK,QAAQ;YAC3B,iBAAiB,CAAC,GAAG,CAClB,OAAgC,CAAC,MAAgB,CACnD,CACJ,CACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,OAAgB;IACvD,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,mBAAmB;QACzB,OAAO,EAAE,sBAAsB;KAChC,CAAC,CAAC;IACH,MAAM,WAAW,GAAG,GAAG,EAAE;QACvB,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;IACxD,CAAC,CAAC;IAEF,KAAK,MAAM,IAAI,IAAI,SAAS;QAC1B,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC,CAAC;IAChE,4BAA4B,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,KAAK,EAAE,EAAE,CACvD,MAAM,CAAC,gBAAgB,CACrB,kBAAkB,KAAK,EAAE,EACzB,IAAI,gBAAgB,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,EACnD,yBAAyB,EACzB,WAAW,CACZ,CACF,CAAC;IAEF,MAAM,SAAS,GAAG,IAAI,wCAAwC,CAC5D,iBAAiB,CAClB,CAAC;IACF,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAChC,OAAO,MAAM,SAAS,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IAChD,CAAC;YAAS,CAAC;QACT,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC,SAAS,CAAC,KAAK,EAAE,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAChE,CAAC;AACH,CAAC"}

package/dist/mcp/session.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Self-signing MCP session (Option A / chatbot-first).
+ *
+ * A third-party app that holds its OWN key and a DCR grant proves control of
+ * that key ONCE — a Web3Signed handshake to `POST /mcp/session` — and the PS
+ * mints a short-lived bearer session token bound to `{ builderAddress, grantId }`.
+ * MCP tool calls then present that token as `Authorization: Bearer …`; each read
+ * authorizes as the builder via `verifyDataReadPolicy` (signer == grantee) with
+ * NO per-read signature and NO PS-held key.
+ *
+ * Contrast with the owner's-Claude flow, where the PS generates and holds a
+ * per-connection grantee key and signs reads itself. Here the app is
+ * self-custody; the PS only ever recovered its address (at handshake).
+ */
+import type { McpConnectionRecord } from "./types.js";
+import type { ServerAccount } from "../keys/server-account.js";
+import type { AuthSessionVerifierPort, GrantVerifierPort, RuntimeAvailabilityPort } from "../ports/index.js";
+import type { PersonalServerApiAuthPort, PersonalServerDataApiDeps } from "../api/index.js";
+import type { DataPortabilityGatewayConfig, GatewayClient } from "@opendatalabs/vana-sdk/browser";
+export interface McpSessionRecord {
+    /** SHA-256 hex of the raw session token. Only the hash is stored. */
+    tokenHash: string;
+    /** The self-custody app's address (recovered from the handshake proof). */
+    builderAddress: `0x${string}`;
+    /** DCR grant id the app was issued (grantee == builderAddress). */
+    grantId: string;
+    scopes: string[];
+    createdAt: string;
+    expiresAtMs: number;
+}
+export interface McpSessionStore {
+    create(record: McpSessionRecord): Promise<void>;
+    /** Returns a live (non-expired) session, or null. */
+    getByTokenHash(tokenHash: string): Promise<McpSessionRecord | null>;
+}
+/**
+ * KNOWN LIMITATION: in-memory only. A process restart (or a second instance)
+ * starts with an empty store, so live session tokens die with the process and
+ * the client must re-handshake. Acceptable for today's single-instance
+ * Personal Server; persist via the host's state store before multi-instance.
+ */
+export declare function createInMemoryMcpSessionStore(): McpSessionStore;
+/**
+ * Records consumed handshake-proof identifiers until they expire, so a still-
+ * valid Web3Signed proof cannot be replayed to mint a second session token.
+ */
+export interface McpProofReplayStore {
+    /**
+     * Atomically record `proofId` (remembered until `expiresAtMs`) and report
+     * whether it was ALREADY present and live — i.e. a replay. Returns `true`
+     * on replay, `false` when the proof is fresh (and now recorded).
+     */
+    consume(proofId: string, expiresAtMs: number): Promise<boolean>;
+    /**
+     * Roll back a prior `consume` for `proofId` (e.g. when session persistence
+     * failed after the reservation). Optional — stores that can't release safely
+     * omit it and callers must tolerate its absence.
+     */
+    release?(proofId: string): Promise<void>;
+}
+/**
+ * KNOWN LIMITATION: in-memory only. A process restart (or a second instance)
+ * forgets consumed proof ids, so a still-valid handshake proof could be
+ * replayed once against the fresh process. The blast radius is bounded by the
+ * proof's own expiry, and today's Personal Server runs single-instance, so we
+ * document rather than persist. Persist via the host's state store (do not
+ * invent a new storage layer) before running multiple instances.
+ */
+export declare function createInMemoryMcpProofReplayStore(): McpProofReplayStore;
+export interface CreateMcpSessionInput {
+    builderAddress: `0x${string}`;
+    grantId: string;
+    /**
+     * Handshake-proof replay guard. When supplied together with a `replayStore`,
+     * a proof id already seen (and still live) is rejected instead of minting a
+     * fresh token. `expiresAtMs` bounds how long the id is remembered (the
+     * proof's own expiry).
+     */
+    proof?: {
+        id: string;
+        expiresAtMs: number;
+    };
+}
+export interface CreateMcpSessionOptions {
+    store: McpSessionStore;
+    authSessionVerifier: AuthSessionVerifierPort;
+    grantVerifier: GrantVerifierPort;
+    /**
+     * This server's owner address. The grant's grantor MUST equal it — mirrors
+     * `verifyDataReadPolicy`'s ownership binding (see policy/data-read.ts).
+     * Required (not optional) so TypeScript flags any caller that would mint a
+     * session for a grant issued by a different owner.
+     */
+    serverOwner: `0x${string}`;
+    randomToken: () => string;
+    ttlMs?: number;
+    now?: () => number;
+    /** Optional replay guard for the handshake proof (see `input.proof`). */
+    replayStore?: McpProofReplayStore;
+}
+export interface CreateMcpSessionResult {
+    accessToken: string;
+    expiresInSeconds: number;
+    grantId: string;
+    scopes: string[];
+}
+/**
+ * Validate the handshake identity and mint a session token. Per-scope / expiry
+ * enforcement is authoritative at read time (`verifyDataReadPolicy`), so this
+ * does the minimal checks that give a clear handshake error: builder registered,
+ * grant exists + not revoked, and grantee == builder.
+ */
+export declare function createMcpSession(input: CreateMcpSessionInput, options: CreateMcpSessionOptions): Promise<CreateMcpSessionResult>;
+/**
+ * An auth port bound to one session's `{ builderAddress, grantId }`. Reads
+ * authorize by running `verifyDataReadPolicy` with the builder address proven at
+ * handshake — no signature needed. Owner ops are refused.
+ */
+/**
+ * x402 payment binding for a paid (self-signing) session. When present, every
+ * read runs the same challenge-or-settle cycle as an external builder's
+ * `GET /v1/data/:scope`. Omit it (owner's-Claude path) to keep reads free.
+ */
+export interface McpSessionPaymentConfig {
+    /** Payment-enabled data-API deps (storage, serverSigner, serverAddress, …). */
+    dataApiDeps: PersonalServerDataApiDeps;
+    gateway: Pick<GatewayClient, "getGrant">;
+    gatewayConfig: DataPortabilityGatewayConfig;
+    gatewayUrl: string;
+}
+export declare function createMcpSessionAuthPort(params: {
+    builderAddress: `0x${string}`;
+    grantId: string;
+    authSessionVerifier: AuthSessionVerifierPort;
+    grantVerifier: GrantVerifierPort;
+    /**
+     * This server's owner address, required by `verifyDataReadPolicy` to bind
+     * every session read to a grant issued by THIS server's owner.
+     */
+    serverOwner: `0x${string}`;
+    runtimeAvailability?: RuntimeAvailabilityPort;
+    /** Present only for paid self-signing sessions; absent = free. */
+    payment?: McpSessionPaymentConfig;
+}): PersonalServerApiAuthPort;
+export interface McpSessionConnection {
+    connection: McpConnectionRecord;
+    account: ServerAccount;
+}
+/**
+ * Build a synthetic connection record + a throwaway signing account for the
+ * streamable `/mcp` handler. The MCP read client still signs its in-process
+ * request (the read path requires an account), but the session auth port
+ * ignores that signature and authorizes as the real builder — so this key is
+ * disposable and never leaves the process.
+ */
+export declare function buildMcpSessionConnection(session: Pick<McpSessionRecord, "builderAddress" | "grantId" | "scopes">, options?: {
+    id?: string;
+    now?: () => number;
+}): McpSessionConnection;
+//# sourceMappingURL=session.d.ts.map

package/dist/mcp/session.d.ts.map

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