@opendatalabs/personal-server-ts-core 0.0.1-canary.01ca694 → 0.0.1-canary.052d47e

package/dist/mcp/session.js

@@ -0,0 +1,243 @@
+/**
+ * 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 { generateMcpGrantee } from "./grantee.js";
+import { hashConnectionToken } from "./connection-api.js";
+import { verifyDataReadPolicy } from "../policy/data-read.js";
+import { assertScopeNotDeleted, handleX402Cycle } from "../api/index.js";
+import { GrantOwnerMismatchError, GrantRequiredError, GrantRevokedError, InvalidSignatureError, ProtocolError, UnregisteredBuilderError, } from "../errors/catalog.js";
+/**
+ * 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 function createInMemoryMcpSessionStore() {
+    const byHash = new Map();
+    return {
+        async create(record) {
+            byHash.set(record.tokenHash, record);
+        },
+        async getByTokenHash(tokenHash) {
+            const record = byHash.get(tokenHash);
+            if (!record)
+                return null;
+            if (record.expiresAtMs <= Date.now()) {
+                byHash.delete(tokenHash);
+                return null;
+            }
+            return record;
+        },
+    };
+}
+/**
+ * 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 function createInMemoryMcpProofReplayStore() {
+    const seen = new Map();
+    return {
+        async consume(proofId, expiresAtMs) {
+            const now = Date.now();
+            for (const [id, exp] of seen) {
+                if (exp <= now)
+                    seen.delete(id);
+            }
+            const existing = seen.get(proofId);
+            if (existing !== undefined && existing > now)
+                return true;
+            seen.set(proofId, expiresAtMs);
+            return false;
+        },
+        async release(proofId) {
+            seen.delete(proofId);
+        },
+    };
+}
+const DEFAULT_SESSION_TTL_MS = 60 * 60 * 1000;
+/**
+ * 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 async function createMcpSession(input, options) {
+    const builder = await options.authSessionVerifier.getBuilder(input.builderAddress);
+    if (!builder)
+        throw new UnregisteredBuilderError();
+    const grant = await options.grantVerifier.getGrant(input.grantId);
+    if (!grant) {
+        throw new GrantRequiredError({
+            reason: "Grant not found",
+            grantId: input.grantId,
+        });
+    }
+    if (grant.revokedAt !== null) {
+        throw new GrantRevokedError({ grantId: grant.id });
+    }
+    if (builder.id.toLowerCase() !== grant.granteeId.toLowerCase()) {
+        throw new InvalidSignatureError({
+            reason: "Handshake signer is not the grant builder",
+            expected: grant.granteeId,
+            actual: input.builderAddress,
+        });
+    }
+    // Ownership binding — the grant MUST have been issued by THIS server's
+    // owner (same check as `verifyDataReadPolicy`, which stays authoritative at
+    // read time). A wrong-owner grant can never become valid for this server,
+    // so reject at handshake with a clear error instead of minting a token
+    // whose every read would 403. Fail closed on a grantor-less grant: gateway
+    // responses are untrusted runtime data, despite their type.
+    if (!grant.grantorAddress ||
+        grant.grantorAddress.toLowerCase() !== options.serverOwner.toLowerCase()) {
+        throw new GrantOwnerMismatchError({
+            grantId: grant.id,
+            expected: options.serverOwner,
+            actual: grant.grantorAddress ?? null,
+        });
+    }
+    // Prepare the token first (deterministic, can't meaningfully fail) so the
+    // only fallible step after consuming the proof is persistence.
+    const token = options.randomToken();
+    const tokenHash = await hashConnectionToken(token);
+    const ttlMs = options.ttlMs ?? DEFAULT_SESSION_TTL_MS;
+    const nowMs = options.now?.() ?? Date.now();
+    // Replay guard: a still-valid handshake proof must mint at most one token.
+    // Consume ONLY after identity validation, and roll the reservation back if
+    // persistence fails — so a transient failure never burns a valid proof.
+    // consume() is an atomic check-and-set, so concurrent duplicates still
+    // resolve to exactly one winner.
+    const usingReplayGuard = Boolean(input.proof && options.replayStore);
+    if (input.proof && options.replayStore) {
+        const replayed = await options.replayStore.consume(input.proof.id, input.proof.expiresAtMs);
+        if (replayed) {
+            throw new ProtocolError(401, "MCP_SESSION_PROOF_REPLAY", "Handshake proof already used; sign a fresh proof");
+        }
+    }
+    try {
+        await options.store.create({
+            tokenHash,
+            builderAddress: input.builderAddress,
+            grantId: grant.id,
+            scopes: grant.scopes ?? [],
+            createdAt: new Date(nowMs).toISOString(),
+            expiresAtMs: nowMs + ttlMs,
+        });
+    }
+    catch (err) {
+        // Persistence failed — release the reservation so a legitimate retry with
+        // the same still-valid proof isn't rejected as a replay.
+        if (usingReplayGuard && input.proof && options.replayStore?.release) {
+            await options.replayStore.release(input.proof.id);
+        }
+        throw err;
+    }
+    return {
+        accessToken: token,
+        expiresInSeconds: Math.floor(ttlMs / 1000),
+        grantId: grant.id,
+        scopes: grant.scopes ?? [],
+    };
+}
+export function createMcpSessionAuthPort(params) {
+    return {
+        async authorizeOwner() {
+            throw new InvalidSignatureError({
+                reason: "MCP session cannot perform owner operations",
+            });
+        },
+        async authorizeBuilderList() {
+            // Allowed: the session builder may list its own granted scopes.
+        },
+        async authorizeBuilderRead(input) {
+            const grant = await verifyDataReadPolicy({
+                signer: params.builderAddress,
+                grantId: params.grantId,
+                requestedScope: input.scope,
+                fileId: input.fileId,
+                serverOwner: params.serverOwner,
+            }, {
+                authSessionVerifier: params.authSessionVerifier,
+                grantVerifier: params.grantVerifier,
+                runtimeAvailability: params.runtimeAvailability,
+            });
+            // Paid session: enforce x402 per read (reuses the exact HTTP cycle). The
+            // read client forwards the app's `X-PAYMENT` proof on `input.request`.
+            if (params.payment) {
+                // Settlement happens here, ahead of the HTTP handler's own deletion
+                // gate, so the gate must run here too: never challenge or settle a
+                // read of a scope the owner deleted.
+                const deps = params.payment.dataApiDeps;
+                await assertScopeNotDeleted(deps, input.scope, deps.storage.findEntry({
+                    scope: input.scope,
+                    fileId: input.fileId,
+                    at: input.at,
+                }));
+                const cycle = await handleX402Cycle({
+                    deps: params.payment.dataApiDeps,
+                    request: input.request,
+                    scope: input.scope,
+                    fileIdParam: input.fileId,
+                    // Bind the payment to the exact data version being served (a
+                    // cursor-pinned or `at=`-pinned read may serve an older version
+                    // than the latest entry) — otherwise the challenge/accessRecord
+                    // would settle against different bytes than were returned.
+                    atParam: input.at,
+                    grantId: params.grantId,
+                    builder: params.builderAddress,
+                    gateway: params.payment.gateway,
+                    gatewayConfig: params.payment.gatewayConfig,
+                    gatewayUrl: params.payment.gatewayUrl,
+                });
+                if (cycle.kind === "challenge") {
+                    throw new ProtocolError(402, "PAYMENT_REQUIRED", "Payment required for this read", { challenge: cycle.body });
+                }
+                if (cycle.kind === "gateway-error") {
+                    throw new ProtocolError(cycle.status, "PAYMENT_GATEWAY_ERROR", "Payment gateway rejected the payment", { body: cycle.body });
+                }
+                // cycle.kind === "ok" — payment settled; proceed to read.
+            }
+            return { builder: params.builderAddress, grantId: grant.id };
+        },
+    };
+}
+/**
+ * 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 function buildMcpSessionConnection(session, options = {}) {
+    const ephemeral = generateMcpGrantee();
+    const nowIso = new Date(options.now?.() ?? Date.now()).toISOString();
+    const connection = {
+        id: options.id ?? `mcp-session-${session.grantId}`,
+        displayName: "MCP session",
+        granteeAddress: session.builderAddress,
+        granteePublicKey: ephemeral.key.publicKey,
+        encryptedGranteePrivateKey: ephemeral.key.encryptedPrivateKey,
+        tokenHash: "",
+        status: "approved",
+        grants: [{ grantId: session.grantId, scopes: session.scopes }],
+        createdAt: nowIso,
+        approvedAt: nowIso,
+    };
+    return { connection, account: ephemeral.account };
+}
+//# sourceMappingURL=session.js.map

package/dist/mcp/session.js.map

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

package/dist/mcp/tools.d.ts

@@ -2,7 +2,7 @@
  * MCP tool surface. Phase 1 / §4 of 260604-PLAN-vana-mcp-personal-server.md.
  *
  * Read-only, small, and only over scopes that the connection's grants cover.
- * No write tools. No grant-management tools. No raw owner/admin status tools.
+ * No write tools. No grant-approval tools. No raw owner/admin status tools.
  *
  * Every tool that returns data first picks a covering grant from the
  * connection's grant list, signs a Web3Signed request as the per-connection
@@ -18,10 +18,26 @@ export interface McpToolContext {
     readClient: McpDataReadClient;
     activityRecorder?: McpActivityRecorder;
 }
-export interface McpToolResultContent {
+export type McpToolResultContent = {
     type: "text";
     text: string;
-}
+} | {
+    type: "resource_link";
+    uri: string;
+    name: string;
+    title?: string;
+    description?: string;
+    mimeType?: string;
+    size?: number;
+} | {
+    type: "resource";
+    resource: {
+        uri: string;
+        mimeType?: string;
+        blob: string;
+        _meta?: Record<string, unknown>;
+    };
+};
 export interface McpToolResult {
     content: McpToolResultContent[];
     isError?: boolean;
@@ -40,5 +56,15 @@ export interface McpToolDefinition {
     inputSchema: McpToolInputShape;
     handler(args: Record<string, unknown>, ctx: McpToolContext): Promise<McpToolResult>;
 }
+/**
+ * Hard ceiling the MCP dispatcher enforces on any tool call (see
+ * `clampToolTimeout` in `server.ts`, which imports this).
+ *
+ * Tools must never advertise a larger `timeoutMs` than the dispatcher allows: a
+ * client that trusts the advertised maximum gets killed with a hard
+ * `tool_timeout` instead of the graceful "budget exhausted, here are partial
+ * results plus nextSearchCursor" path the tools implement.
+ */
+export declare const MAX_MCP_TOOL_TIMEOUT_MS = 90000;
 export declare const MCP_TOOLS: readonly McpToolDefinition[];
 //# sourceMappingURL=tools.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAGzD,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,mBAAmB,CAAC;IAChC,UAAU,EAAE,iBAAiB,CAAC;IAC9B,gBAAgB,CAAC,EAAE,mBAAmB,CAAC;CACxC;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,oBAAoB,EAAE,CAAC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAG5C,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC;AAE7D,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,iBAAiB,CAAC;IAC/B,OAAO,CACL,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,aAAa,CAAC,CAAC;CAC3B;AA8lCD,eAAO,MAAM,SAAS,EAAE,SAAS,iBAAiB,EAKxC,CAAC"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AASzD,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,mBAAmB,CAAC;IAChC,UAAU,EAAE,iBAAiB,CAAC;IAC9B,gBAAgB,CAAC,EAAE,mBAAmB,CAAC;CACxC;AAED,MAAM,MAAM,oBAAoB,GAC5B;IACE,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,GACD;IACE,IAAI,EAAE,eAAe,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GACD;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,GAAG,EAAE,MAAM,CAAC;QACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACjC,CAAC;CACH,CAAC;AAEN,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,oBAAoB,EAAE,CAAC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAG5C,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC;AAE7D,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,iBAAiB,CAAC;IAC/B,OAAO,CACL,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,aAAa,CAAC,CAAC;CAC3B;AAiGD;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,QAAS,CAAC;AA4iD9C,eAAO,MAAM,SAAS,EAAE,SAAS,iBAAiB,EAQxC,CAAC"}