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

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/store.d.ts

@@ -0,0 +1,13 @@
+/**
+ * In-memory `McpConnectionStore` — Phase 1 default for tests and as a fallback
+ * runtime store. Production Web PS Lite is expected to back this with the same
+ * IndexedDB state mechanism used for server-identity and token storage.
+ *
+ * The PS-Lite browser adapter for this port lives in
+ * `packages/lite/src/mcp-store.ts` (not part of this change set yet) — that
+ * adapter mirrors `createIndexedDbPsLiteTokenStore()`.
+ */
+import type { McpConnectionStore, McpOAuthAuthorizationStore } from "./types.js";
+export declare function createInMemoryMcpConnectionStore(): McpConnectionStore;
+export declare function createInMemoryMcpOAuthAuthorizationStore(): McpOAuthAuthorizationStore;
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/mcp/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAEV,kBAAkB,EAElB,0BAA0B,EAC3B,MAAM,YAAY,CAAC;AAGpB,wBAAgB,gCAAgC,IAAI,kBAAkB,CAiErE;AAED,wBAAgB,wCAAwC,IAAI,0BAA0B,CAiDrF"}

package/dist/mcp/store.js

@@ -0,0 +1,119 @@
+/**
+ * In-memory `McpConnectionStore` — Phase 1 default for tests and as a fallback
+ * runtime store. Production Web PS Lite is expected to back this with the same
+ * IndexedDB state mechanism used for server-identity and token storage.
+ *
+ * The PS-Lite browser adapter for this port lives in
+ * `packages/lite/src/mcp-store.ts` (not part of this change set yet) — that
+ * adapter mirrors `createIndexedDbPsLiteTokenStore()`.
+ */
+import { isMcpTokenExpired, matchesMcpRefreshHash } from "./token-expiry.js";
+export function createInMemoryMcpConnectionStore() {
+    const byId = new Map();
+    const byTokenHash = new Map(); // tokenHash → id
+    return {
+        async create(record) {
+            if (byId.has(record.id)) {
+                throw new Error(`mcp connection ${record.id} already exists`);
+            }
+            byId.set(record.id, { ...record });
+            byTokenHash.set(record.tokenHash, record.id);
+        },
+        async list() {
+            return Array.from(byId.values()).map((r) => ({ ...r }));
+        },
+        async getById(id) {
+            const record = byId.get(id);
+            return record ? { ...record } : null;
+        },
+        async getByTokenHash(tokenHash) {
+            const id = byTokenHash.get(tokenHash);
+            if (!id)
+                return null;
+            const record = byId.get(id);
+            if (!record)
+                return null;
+            if (record.status !== "approved")
+                return null;
+            if (isMcpTokenExpired(record))
+                return null;
+            return { ...record };
+        },
+        async getByRefreshTokenHash(refreshTokenHash) {
+            // Scanned, not indexed: a presented token may match either the current
+            // or the rotated-out hash, and a store holds a handful of connections.
+            const record = Array.from(byId.values()).find((candidate) => matchesMcpRefreshHash(candidate, refreshTokenHash));
+            return record ? { ...record } : null;
+        },
+        async mutate(id, update) {
+            const record = byId.get(id);
+            if (!record)
+                return null;
+            const updated = update(structuredClone(record));
+            if (updated.tokenHash !== record.tokenHash) {
+                byTokenHash.delete(record.tokenHash);
+                byTokenHash.set(updated.tokenHash, id);
+            }
+            byId.set(id, structuredClone(updated));
+            return structuredClone(updated);
+        },
+        async update(id, patch) {
+            const record = byId.get(id);
+            if (!record)
+                return null;
+            if (patch.tokenHash && patch.tokenHash !== record.tokenHash) {
+                byTokenHash.delete(record.tokenHash);
+                byTokenHash.set(patch.tokenHash, id);
+            }
+            const updated = { ...record, ...patch };
+            byId.set(id, updated);
+            return { ...updated };
+        },
+    };
+}
+export function createInMemoryMcpOAuthAuthorizationStore() {
+    const byId = new Map();
+    const byCodeHash = new Map(); // authorizationCodeHash -> id
+    return {
+        async create(record) {
+            if (byId.has(record.id)) {
+                throw new Error(`mcp oauth authorization ${record.id} already exists`);
+            }
+            byId.set(record.id, { ...record });
+            if (record.authorizationCodeHash) {
+                byCodeHash.set(record.authorizationCodeHash, record.id);
+            }
+        },
+        async getById(id) {
+            const record = byId.get(id);
+            return record ? { ...record } : null;
+        },
+        async getByCodeHash(authorizationCodeHash) {
+            const id = byCodeHash.get(authorizationCodeHash);
+            if (!id)
+                return null;
+            const record = byId.get(id);
+            return record ? { ...record } : null;
+        },
+        async update(id, patch) {
+            const record = byId.get(id);
+            if (!record)
+                return null;
+            if (patch.authorizationCodeHash &&
+                patch.authorizationCodeHash !== record.authorizationCodeHash) {
+                byCodeHash.set(patch.authorizationCodeHash, id);
+            }
+            const updated = { ...record, ...patch };
+            byId.set(id, updated);
+            return { ...updated };
+        },
+        async delete(id) {
+            const record = byId.get(id);
+            if (record?.authorizationCodeHash) {
+                byCodeHash.delete(record.authorizationCodeHash);
+            }
+            byId.delete(id);
+        },
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/mcp/store.js.map

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

package/dist/mcp/token-expiry.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Lifetime and lookup policy for the two MCP OAuth credentials — one policy,
+ * shared by every store that resolves a token, so the fleet and local paths
+ * cannot diverge.
+ */
+import type { McpConnectionRecord } from "./types.js";
+/**
+ * 1 h. Short because the bearer is replayable and the store cannot revoke an
+ * already-issued one; the refresh grant below is what keeps the owner from
+ * re-consenting hourly.
+ */
+export declare const MCP_TOKEN_TTL_MS: number;
+/**
+ * 7 d. The refresh token is single-use and rotates on every exchange, so its
+ * lifetime bounds how long a connection survives without the owner touching
+ * it — not how long a leaked credential is usable. A week keeps an abandoned
+ * connection from lingering a month; an owner who uses the connection weekly
+ * never re-consents.
+ */
+export declare const MCP_REFRESH_TTL_MS: number;
+/** ISO expiry for an access token minted at `nowMs`. */
+export declare function mcpTokenExpiry(nowMs: number): string;
+/** ISO expiry for a refresh token minted at `nowMs`. */
+export declare function mcpRefreshExpiry(nowMs: number): string;
+/**
+ * Fail closed. A record written before `tokenExpiresAt` existed carries no
+ * proven lifetime, so it reads as expired: connections issued before this
+ * change need one re-consent rather than living forever.
+ */
+export declare function isMcpTokenExpired(record: Pick<McpConnectionRecord, "tokenExpiresAt">, nowMs?: number): boolean;
+/** Fail closed, same rule: no proven lifetime means no refresh. */
+export declare function isMcpRefreshExpired(record: Pick<McpConnectionRecord, "refreshExpiresAt">, nowMs?: number): boolean;
+/**
+ * True when `hash` is this record's current or rotated-out refresh hash. Every
+ * store resolves a refresh token through this one predicate.
+ */
+export declare function matchesMcpRefreshHash(record: Pick<McpConnectionRecord, "refreshTokenHash" | "previousRefreshTokenHash">, hash: string): boolean;
+//# sourceMappingURL=token-expiry.d.ts.map

package/dist/mcp/token-expiry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-expiry.d.ts","sourceRoot":"","sources":["../../src/mcp/token-expiry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,QAAiB,CAAC;AAE/C;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,QAA0B,CAAC;AAE1D,wDAAwD;AACxD,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,wDAAwD;AACxD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,IAAI,CAAC,mBAAmB,EAAE,gBAAgB,CAAC,EACnD,KAAK,GAAE,MAAmB,GACzB,OAAO,CAET;AAED,mEAAmE;AACnE,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,IAAI,CAAC,mBAAmB,EAAE,kBAAkB,CAAC,EACrD,KAAK,GAAE,MAAmB,GACzB,OAAO,CAET;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,IAAI,CACV,mBAAmB,EACnB,kBAAkB,GAAG,0BAA0B,CAChD,EACD,IAAI,EAAE,MAAM,GACX,OAAO,CAMT"}

package/dist/mcp/token-expiry.js

@@ -0,0 +1,55 @@
+/**
+ * Lifetime and lookup policy for the two MCP OAuth credentials — one policy,
+ * shared by every store that resolves a token, so the fleet and local paths
+ * cannot diverge.
+ */
+/**
+ * 1 h. Short because the bearer is replayable and the store cannot revoke an
+ * already-issued one; the refresh grant below is what keeps the owner from
+ * re-consenting hourly.
+ */
+export const MCP_TOKEN_TTL_MS = 60 * 60 * 1000;
+/**
+ * 7 d. The refresh token is single-use and rotates on every exchange, so its
+ * lifetime bounds how long a connection survives without the owner touching
+ * it — not how long a leaked credential is usable. A week keeps an abandoned
+ * connection from lingering a month; an owner who uses the connection weekly
+ * never re-consents.
+ */
+export const MCP_REFRESH_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+/** ISO expiry for an access token minted at `nowMs`. */
+export function mcpTokenExpiry(nowMs) {
+    return new Date(nowMs + MCP_TOKEN_TTL_MS).toISOString();
+}
+/** ISO expiry for a refresh token minted at `nowMs`. */
+export function mcpRefreshExpiry(nowMs) {
+    return new Date(nowMs + MCP_REFRESH_TTL_MS).toISOString();
+}
+/**
+ * Fail closed. A record written before `tokenExpiresAt` existed carries no
+ * proven lifetime, so it reads as expired: connections issued before this
+ * change need one re-consent rather than living forever.
+ */
+export function isMcpTokenExpired(record, nowMs = Date.now()) {
+    return isExpired(record.tokenExpiresAt, nowMs);
+}
+/** Fail closed, same rule: no proven lifetime means no refresh. */
+export function isMcpRefreshExpired(record, nowMs = Date.now()) {
+    return isExpired(record.refreshExpiresAt, nowMs);
+}
+/**
+ * True when `hash` is this record's current or rotated-out refresh hash. Every
+ * store resolves a refresh token through this one predicate.
+ */
+export function matchesMcpRefreshHash(record, hash) {
+    if (!hash)
+        return false;
+    return (record.refreshTokenHash === hash || record.previousRefreshTokenHash === hash);
+}
+function isExpired(expiresAt, nowMs) {
+    if (!expiresAt)
+        return true;
+    const expiry = Date.parse(expiresAt);
+    return !Number.isFinite(expiry) || expiry <= nowMs;
+}
+//# sourceMappingURL=token-expiry.js.map

package/dist/mcp/token-expiry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-expiry.js","sourceRoot":"","sources":["../../src/mcp/token-expiry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAE/C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAE1D,wDAAwD;AACxD,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,OAAO,IAAI,IAAI,CAAC,KAAK,GAAG,gBAAgB,CAAC,CAAC,WAAW,EAAE,CAAC;AAC1D,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,OAAO,IAAI,IAAI,CAAC,KAAK,GAAG,kBAAkB,CAAC,CAAC,WAAW,EAAE,CAAC;AAC5D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAmD,EACnD,QAAgB,IAAI,CAAC,GAAG,EAAE;IAE1B,OAAO,SAAS,CAAC,MAAM,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;AACjD,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,mBAAmB,CACjC,MAAqD,EACrD,QAAgB,IAAI,CAAC,GAAG,EAAE;IAE1B,OAAO,SAAS,CAAC,MAAM,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;AACnD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAGC,EACD,IAAY;IAEZ,IAAI,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IAExB,OAAO,CACL,MAAM,CAAC,gBAAgB,KAAK,IAAI,IAAI,MAAM,CAAC,wBAAwB,KAAK,IAAI,CAC7E,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAAC,SAA6B,EAAE,KAAa;IAC7D,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IAE5B,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACrC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,KAAK,CAAC;AACrD,CAAC"}

package/dist/mcp/tools.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 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-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
+ * grantee, and uses the bounded sidecar read path — so reads are grant-gated,
+ * access-logged, and safe for large scopes.
+ */
+import { z } from "zod";
+import { type McpConnectionRecord } from "./types.js";
+import type { McpDataReadClient } from "./read-client.js";
+import type { McpActivityRecorder } from "./activity.js";
+export interface McpToolContext {
+    connection: McpConnectionRecord;
+    readClient: McpDataReadClient;
+    activityRecorder?: McpActivityRecorder;
+    requestScopeAccess?(input: {
+        scopes: string[];
+        reason?: string;
+    }): Promise<{
+        connection: McpConnectionRecord;
+        requestRecorded: boolean;
+    }>;
+}
+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;
+    structuredContent?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/**
+ * Zod raw-shape input schema. The SDK's `registerTool` accepts this and
+ * derives a JSON schema for clients.
+ */
+export type McpToolInputShape = Record<string, z.ZodTypeAny>;
+export interface McpToolDefinition {
+    name: string;
+    title: string;
+    description: string;
+    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 function parseScopeAccessRequestArguments(value: unknown): {
+    scopes: string[];
+    reason?: string;
+} | null;
+/**
+ * Resolve a concrete requested scope to a covering grant id from the
+ * connection's approved grants. A scope is "covered" when an approved grant's
+ * scopes either contains the exact scope or contains a wildcard like
+ * `instagram.*` that matches a concrete child scope like `instagram.profile`.
+ *
+ * Mirrors `scopeCoveredByGrant` semantics from `policy/data-read.ts` so the
+ * tool surface never offers Claude a scope its grant won't actually pass
+ * server-side.
+ */
+export declare function resolveGrantForScope(connection: McpConnectionRecord, scope: string): {
+    grantId: string;
+    scopes: string[];
+} | null;
+export declare const MCP_TOOLS: readonly McpToolDefinition[];
+//# sourceMappingURL=tools.d.ts.map

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

@@ -0,0 +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,EAEL,KAAK,mBAAmB,EACzB,MAAM,YAAY,CAAC;AACpB,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;IACvC,kBAAkB,CAAC,CAAC,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QACzE,UAAU,EAAE,mBAAmB,CAAC;QAChC,eAAe,EAAE,OAAO,CAAC;KAC1B,CAAC,CAAC;CACJ;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;AAqGD;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAmD9C,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,OAAO,GACb;IAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAO9C;AAkBD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,mBAAmB,EAC/B,KAAK,EAAE,MAAM,GACZ;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CAkB9C;AAs+CD,eAAO,MAAM,SAAS,EAAE,SAAS,iBAAiB,EAQxC,CAAC"}