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

package/dist/mcp/grantee.js

@@ -0,0 +1,91 @@
+/**
+ * Per-connection MCP grantee key generation + Web3Signed request signing.
+ *
+ * Each MCP connection gets a fresh secp256k1 keypair. The PS route uses this
+ * keypair to sign every read it performs on behalf of the connection so:
+ *
+ *  1. The data read flows through `authorizeBuilderRead` exactly like any
+ *     external builder request.
+ *  2. The access log records the per-connection grantee address, not the
+ *     owner.
+ *  3. Disconnecting one MCP client cannot affect another or the owner.
+ *
+ * This module does NOT do encryption-at-rest. The caller chooses the storage
+ * representation (`McpEncryptedPrivateKey`) — for Node the `plaintext` variant
+ * is fine (same trust boundary as the on-disk server key); for Web PS Lite the
+ * caller should wrap with the owner-derived master key.
+ */
+import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
+import { buildWeb3SignedHeader } from "@opendatalabs/vana-sdk/browser";
+/**
+ * Generate a new MCP grantee keypair and return both the persisted
+ * (plaintext-wrapped) form and a ready-to-sign `ServerAccount`.
+ */
+export function generateMcpGrantee() {
+    const privateKey = generatePrivateKey();
+    const account = privateKeyToAccount(privateKey);
+    const serverAccount = {
+        address: account.address,
+        publicKey: account.publicKey,
+        async signTypedData(params) {
+            return account.signTypedData({
+                domain: params.domain,
+                types: params.types,
+                primaryType: params.primaryType,
+                message: params.message,
+            });
+        },
+        async signMessage(message) {
+            return account.signMessage({ message });
+        },
+    };
+    return {
+        key: {
+            address: account.address,
+            publicKey: account.publicKey,
+            encryptedPrivateKey: { kind: "plaintext", privateKey },
+        },
+        account: serverAccount,
+    };
+}
+/**
+ * Reconstruct a `ServerAccount` from a persisted MCP grantee record.
+ * Only `plaintext` is supported here; Web PS Lite must decrypt to plaintext
+ * before calling.
+ */
+export function loadMcpGranteeAccount(key) {
+    if (key.encryptedPrivateKey.kind !== "plaintext") {
+        throw new Error("loadMcpGranteeAccount: only plaintext keys are supported here; decrypt first");
+    }
+    const account = privateKeyToAccount(key.encryptedPrivateKey.privateKey);
+    return {
+        address: account.address,
+        publicKey: account.publicKey,
+        async signTypedData(params) {
+            return account.signTypedData({
+                domain: params.domain,
+                types: params.types,
+                primaryType: params.primaryType,
+                message: params.message,
+            });
+        },
+        async signMessage(message) {
+            return account.signMessage({ message });
+        },
+    };
+}
+/**
+ * Build a Web3Signed Authorization header that authenticates the bearer as the
+ * MCP connection's grantee for a given grant id and request URL.
+ */
+export async function signMcpGranteeRequest(params) {
+    return buildWeb3SignedHeader({
+        signMessage: (message) => params.account.signMessage(message),
+        aud: params.aud,
+        method: params.method,
+        uri: params.uri,
+        body: params.body,
+        grantId: params.grantId,
+    });
+}
+//# sourceMappingURL=grantee.js.map

package/dist/mcp/grantee.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grantee.js","sourceRoot":"","sources":["../../src/mcp/grantee.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAevE;;;GAGG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,UAAU,GAAG,kBAAkB,EAAE,CAAC;IACxC,MAAM,OAAO,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAC;IAChD,MAAM,aAAa,GAAkB;QACnC,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,KAAK,CAAC,aAAa,CAAC,MAAM;YACxB,OAAO,OAAO,CAAC,aAAa,CAAC;gBAC3B,MAAM,EAAE,MAAM,CAAC,MAED;gBACd,KAAK,EAAE,MAAM,CAAC,KAED;gBACb,WAAW,EAAE,MAAM,CAAC,WAAW;gBAC/B,OAAO,EAAE,MAAM,CAAC,OAAO;aACxB,CAAC,CAAC;QACL,CAAC;QACD,KAAK,CAAC,WAAW,CAAC,OAAO;YACvB,OAAO,OAAO,CAAC,WAAW,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;QAC1C,CAAC;KACF,CAAC;IACF,OAAO;QACL,GAAG,EAAE;YACH,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,mBAAmB,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE;SACvD;QACD,OAAO,EAAE,aAAa;KACvB,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAkB;IACtD,IAAI,GAAG,CAAC,mBAAmB,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QACjD,MAAM,IAAI,KAAK,CACb,8EAA8E,CAC/E,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,mBAAmB,CAAC,GAAG,CAAC,mBAAmB,CAAC,UAAU,CAAC,CAAC;IACxE,OAAO;QACL,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,KAAK,CAAC,aAAa,CAAC,MAAM;YACxB,OAAO,OAAO,CAAC,aAAa,CAAC;gBAC3B,MAAM,EAAE,MAAM,CAAC,MAED;gBACd,KAAK,EAAE,MAAM,CAAC,KAED;gBACb,WAAW,EAAE,MAAM,CAAC,WAAW;gBAC/B,OAAO,EAAE,MAAM,CAAC,OAAO;aACxB,CAAC,CAAC;QACL,CAAC;QACD,KAAK,CAAC,WAAW,CAAC,OAAO;YACvB,OAAO,OAAO,CAAC,WAAW,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;QAC1C,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,MAO3C;IACC,OAAO,qBAAqB,CAAC;QAC3B,WAAW,EAAE,CAAC,OAAe,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC;QACrE,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,OAAO,EAAE,MAAM,CAAC,OAAO;KACxB,CAAC,CAAC;AACL,CAAC"}

package/dist/mcp/index.d.ts

@@ -0,0 +1,12 @@
+export * from "./types.js";
+export * from "./store.js";
+export * from "./token-expiry.js";
+export * from "./grantee.js";
+export * from "./builder-registration.js";
+export * from "./read-client.js";
+export * from "./tools.js";
+export * from "./server.js";
+export * from "./connection-api.js";
+export * from "./session.js";
+export * from "./activity.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC"}

package/dist/mcp/index.js

@@ -0,0 +1,12 @@
+export * from "./types.js";
+export * from "./store.js";
+export * from "./token-expiry.js";
+export * from "./grantee.js";
+export * from "./builder-registration.js";
+export * from "./read-client.js";
+export * from "./tools.js";
+export * from "./server.js";
+export * from "./connection-api.js";
+export * from "./session.js";
+export * from "./activity.js";
+//# sourceMappingURL=index.js.map

package/dist/mcp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC"}

package/dist/mcp/read-client.d.ts

@@ -0,0 +1,176 @@
+/**
+ * In-process MCP read client.
+ *
+ * The MCP route accepts a tool call from an MCP client, then needs to read scoped data
+ * from the user's Personal Server *as the per-connection grantee*. We do NOT
+ * round-trip through the public HTTP origin for this — the relay/tunnel is only
+ * for inbound MCP traffic. Instead we:
+ *
+ *  1. Build a Web Request signed by the connection's grantee, with the
+ *     existing grantId in the Web3Signed payload.
+ *  2. Use the same auth and access-log ports as `/v1/data`, then read bounded
+ *     block sidecars from storage. MCP tools must not fall back to full envelope
+ *     reads when sidecars are unavailable.
+ *
+ * This guarantees parity: the MCP read goes through the same policy check
+ * (`verifyDataReadPolicy`) and access-log path as an external builder read.
+ * No special owner-mode code path; no shared global grantee; logs record the
+ * per-connection grantee address.
+ */
+import type { ServerAccount } from "../keys/server-account.js";
+import type { ScopeSummary } from "../storage/index/types.js";
+import type { DataBlockManifest, ReadScopeBlocksResponse } from "../storage/blocks/types.js";
+import type { SearchHit } from "./search/index.js";
+import { type PersonalServerDataApiDeps } from "../api/index.js";
+export interface McpScopeMetadata {
+    scope: string;
+    collectedAt: string;
+    sizeBytes: number;
+    /** True when the bounded block read path is available for this scope. */
+    hasBlocks: boolean;
+}
+export interface McpDataReadClient {
+    /**
+     * True when reads through this client are x402-payment-enforced (a paid
+     * self-signing session). Payment-bypassing shortcuts — notably the optional
+     * `searchScopeIndex` preview path, which does not route through the data API
+     * auth port — MUST NOT be used when this is set.
+     */
+    enforcesPayment?: boolean;
+    /**
+     * Perform `GET /v1/data?scopePrefix=…` as the connection grantee. This is
+     * used only for discovery/expanding wildcard grants before a grant-gated
+     * read; it does not return scope contents.
+     */
+    listScopes(params?: {
+        scopePrefix?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<McpDataListResult>;
+    /**
+     * Return lightweight planning metadata for a scope using the storage index
+     * only — no network call, no block read, no auth. Used by list_granted_scopes
+     * to populate sizeBytes/sizeClass/recommendedAccess without reading data.
+     * Returns null when the scope has no local index entry.
+     */
+    getScopeMetadata(scope: string): Promise<McpScopeMetadata | null>;
+    /**
+     * Perform a grant-gated bounded block read for MCP. This is the path used by
+     * MCP tools that need pagination and must not fall back to full envelope
+     * reads when the bounded storage path is unavailable.
+     *
+     * `blockIds` switches the read to block-addressed mode: only those blocks are
+     * returned, `cursor` is ignored, and no `nextCursor` is produced. `maxBytes`
+     * still bounds the response.
+     */
+    readScopeBlocks(params: {
+        scope: string;
+        grantId: string;
+        cursor?: string;
+        maxBytes?: number;
+        /**
+         * Optional base64 `X-PAYMENT` proof (x402). Forwarded as a header on the
+         * in-process read request so a payment-enforcing auth port (self-signing
+         * MCP sessions) can settle it. The owner/OAuth path never sets this.
+         */
+        payment?: string;
+        blockIds?: readonly string[];
+        /** MCP tool the read came from, stamped onto the served access record. */
+        tool?: string;
+    }): Promise<McpDataReadBlocksResult>;
+    /**
+     * Read a scope's block manifest (ids, paths, sizes) as a table of contents.
+     * Grant-gated like `readScopeBlocks`, but returns no block values. Resolves
+     * null when the scope has no manifest — older scopes and scopes that are
+     * still indexing must degrade, not fail.
+     */
+    readBlockManifest?(params: {
+        scope: string;
+        grantId: string;
+    }): Promise<DataBlockManifest | null>;
+    /**
+     * Perform a grant-gated raw binary read for an approved binary scope. This
+     * reuses `/v1/data/{scope}?content=raw` so policy checks and access logs stay
+     * identical to normal builder reads.
+     */
+    readRawScopeFile(params: {
+        scope: string;
+        grantId: string;
+        at?: string;
+        fileId?: string;
+        /**
+         * Optional base64 `X-PAYMENT` proof (x402), forwarded like
+         * `readScopeBlocks` so a paid self-signing session can settle raw reads.
+         */
+        payment?: string;
+    }): Promise<McpDataReadRawFileResult>;
+    /**
+     * Optional indexed search path. Implementations may return `missing` while
+     * an index is absent/stale; callers must keep the bounded block read path as
+     * fallback so full data remains accessible.
+     */
+    searchScopeIndex?(params: {
+        scope: string;
+        grantId: string;
+        query: string;
+        maxResults: number;
+    }): Promise<{
+        status: "hit";
+        hits: SearchHit[];
+    } | {
+        status: "missing";
+    }>;
+}
+export interface McpDataListResult {
+    status: number;
+    scopes: ScopeSummary[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+export interface McpDataReadBlocksResult extends ReadScopeBlocksResponse {
+    status: number;
+}
+export interface McpDataReadRawFileResult {
+    status: number;
+    scope: string;
+    collectedAt?: string;
+    fileId?: string;
+    mimeType: string;
+    filename?: string;
+    sizeBytes: number;
+    contentBase64: string;
+    metadata?: unknown;
+}
+export declare class McpDataReadError extends Error {
+    status: number;
+    body: unknown;
+    constructor(status: number, body: unknown);
+}
+export interface CreateMcpDataReadClientOptions {
+    /**
+     * Origin the Web3Signed payload's `aud` claim is bound to. This MUST match
+     * the `serverOrigin` configured on the data API auth port — otherwise the
+     * signature audience check will fail.
+     */
+    serverOrigin: string;
+    granteeAccount: ServerAccount;
+    /**
+     * The data API deps used to mount `/v1/data` for external traffic. We reuse
+     * the exact same handler + ports so policy and access-logging are identical.
+     */
+    dataApiDeps: PersonalServerDataApiDeps;
+    /**
+     * Base path the data API was mounted under externally — required so the
+     * Web3Signed signature URI matches what `handlePersonalServerDataRequest`
+     * expects after strip-base-path. Defaults to `/v1/data`.
+     */
+    basePath?: string;
+    /**
+     * Marks reads through this client as x402-enforced (paid self-signing
+     * session). Surfaced as `McpDataReadClient.enforcesPayment`.
+     */
+    enforcesPayment?: boolean;
+}
+export declare function createMcpDataReadClient(options: CreateMcpDataReadClientOptions): McpDataReadClient;
+//# sourceMappingURL=read-client.d.ts.map

package/dist/mcp/read-client.d.ts.map

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