@opendatalabs/personal-server-ts-core 1.3.5 → 1.5.0

package/dist/mcp/session.js

@@ -0,0 +1,234 @@
+/**
+ * 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 { 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) {
+                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.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;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;AA84C9C,eAAO,MAAM,SAAS,EAAE,SAAS,iBAAiB,EAQxC,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"}

package/dist/mcp/tools.js

@@ -582,6 +582,10 @@ const readScope = {
             .min(1000)
             .max(MAX_READ_SCOPE_TIMEOUT_MS)
             .optional(),
+        payment: z
+            .string()
+            .optional()
+            .describe("Base64 X-PAYMENT proof (x402). Provide it after a prior call returned payment_required."),
     },
     async handler(args, { connection, readClient }) {
         const scope = typeof args.scope === "string" ? args.scope : null;
@@ -630,12 +634,14 @@ const readScope = {
                 // Advisory only — serve the read without guidance.
             });
         }
+        const payment = typeof args.payment === "string" ? args.payment : undefined;
         try {
             const result = await withTimeout(readClient.readScopeBlocks({
                 scope,
                 grantId: grant.grantId,
                 cursor,
                 maxBytes,
+                payment,
                 ...(blockIds.length > 0 ? { blockIds } : {}),
             }), timeoutMs, `read blocks for ${scope}`);
             const nextCursor = result.nextCursor ?? null;
@@ -668,6 +674,30 @@ const readScope = {
                 }, true);
             }
             if (err instanceof McpDataReadError) {
+                if (err.status === 402) {
+                    const body = err.body;
+                    const challenge = body?.error?.details?.challenge;
+                    // Only a genuine PAYMENT_REQUIRED with a challenge is signable. A
+                    // gateway failure that also surfaces as 402 (e.g. PAYMENT_GATEWAY_ERROR
+                    // — insufficient escrow balance) is NOT signable; presenting it as a
+                    // challenge would make the client sign an error envelope in a loop.
+                    if (body?.error?.errorCode === "PAYMENT_REQUIRED" && challenge) {
+                        return textResult({
+                            payment_required: true,
+                            status: 402,
+                            challenge,
+                            message: "This read requires payment. Sign the x402 challenge and call read_scope again with the `payment` argument.",
+                        }, true);
+                    }
+                    // Gateway-side payment failure — surface the real error + remediation.
+                    return textResult({
+                        error: "payment_failed",
+                        status: 402,
+                        errorCode: body?.error?.errorCode ?? "PAYMENT_ERROR",
+                        message: body?.error?.message ??
+                            "Payment could not be completed (e.g. insufficient escrow balance). This is not a signable challenge; resolve the gateway error and retry.",
+                    }, true);
+                }
                 if (err.status === 503) {
                     return textResult({
                         error: "bounded_data_unavailable",
@@ -817,7 +847,7 @@ function decodeSearchCursor(raw) {
 const searchPersonalContext = {
     name: "search_personal_context",
     title: "Search personal context",
-    description: "Search approved scopes. Omit scopes for default sweep; name scopes for targeted search. Continue with nextSearchCursor.",
+    description: "Search approved scopes. Omit scopes for default sweep; name scopes for targeted search. Continue with nextSearchCursor. Free discovery/preview — it does not settle payments; chargeable scopes are returned in paymentRequiredScopes, fetch those via read_scope with a `payment` proof.",
     inputSchema: {
         query: z.string().min(1).max(SEARCH_QUERY_MAX_CHARS),
         scopes: z
@@ -865,6 +895,11 @@ const searchPersonalContext = {
         const matches = [];
         const searchedScopes = [];
         const truncatedScopes = [];
+        // Chargeable scopes hit on a paid (self-signing) session. Search is a free
+        // discovery/preview surface and does not settle x402 payments — it surfaces
+        // these explicitly so the client retrieves them via read_scope with a
+        // `payment` proof, instead of burying the 402 as an opaque scope error.
+        const paymentRequiredScopes = [];
         const errors = [...resolved.errors];
         // When resuming, start from the scope index encoded in the cursor
         const startScopeIndex = resumeCursor
@@ -884,7 +919,12 @@ const searchPersonalContext = {
             const grant = resolveGrantForScope(connection, scope);
             if (!grant)
                 continue;
-            if (!resumeCursor && typeof readClient.searchScopeIndex === "function") {
+            // The index preview path bypasses the data API auth port (and thus
+            // x402). Skip it when reads are payment-enforced so paid content is never
+            // previewed for free — search falls back to the paid bounded block read.
+            if (!resumeCursor &&
+                !readClient.enforcesPayment &&
+                typeof readClient.searchScopeIndex === "function") {
                 const remainingMs = deadline - Date.now();
                 if (remainingMs <= 0) {
                     nextSearchCursor = encodeSearchCursor({ scopeIndex });
@@ -1021,18 +1061,32 @@ const searchPersonalContext = {
                 }
             }
             catch (err) {
-                errors.push({
-                    scope,
-                    error: err instanceof OperationTimeoutError
-                        ? "scope_search_timeout"
-                        : "scope_read_failed",
-                    status: err instanceof McpDataReadError ? err.status : undefined,
-                    bodyPreview: stringifyPreview(err instanceof McpDataReadError
-                        ? err.body
-                        : err instanceof OperationTimeoutError
-                            ? err.message
-                            : "unexpected scope read failure"),
-                });
+                const paymentChallenge = err instanceof McpDataReadError &&
+                    err.status === 402 &&
+                    err.body?.error?.errorCode ===
+                        "PAYMENT_REQUIRED";
+                if (paymentChallenge) {
+                    // Paid session hit a chargeable scope. Surface it as payment-required
+                    // (retrieve via read_scope with `payment`) rather than a scope error.
+                    // A gateway 402 (PAYMENT_GATEWAY_ERROR) falls through to `errors`.
+                    if (!paymentRequiredScopes.includes(scope)) {
+                        paymentRequiredScopes.push(scope);
+                    }
+                }
+                else {
+                    errors.push({
+                        scope,
+                        error: err instanceof OperationTimeoutError
+                            ? "scope_search_timeout"
+                            : "scope_read_failed",
+                        status: err instanceof McpDataReadError ? err.status : undefined,
+                        bodyPreview: stringifyPreview(err instanceof McpDataReadError
+                            ? err.body
+                            : err instanceof OperationTimeoutError
+                                ? err.message
+                                : "unexpected scope read failure"),
+                    });
+                }
             }
             if (matches.length >= limit) {
                 // Result limit hit — if more scopes remain, offer cursor for next scope.
@@ -1067,6 +1121,13 @@ const searchPersonalContext = {
             ],
             truncatedScopes,
             errors,
+            ...(paymentRequiredScopes.length > 0
+                ? {
+                    payment_required: true,
+                    paymentRequiredScopes,
+                    paymentHint: "These scopes are chargeable; search does not settle x402 payments. Retrieve each with read_scope (it returns a payment_required challenge; sign it and re-call read_scope with the `payment` argument).",
+                }
+                : {}),
             ...(nextSearchCursor ? { nextSearchCursor } : {}),
             elapsedMs,
             limits: {
@@ -1091,6 +1152,8 @@ const getScopeFile = {
     description: "Fetch an approved file/PDF scope. Defaults to metadata plus a resource link; set includeContent=true only when the client supports inline resource blobs. Use search_personal_context for extracted text.",
     inputSchema: {
         ...rawScopeFileInputSchema,
+        // x402 proof (see read_scope's `payment`); provide after a payment_required.
+        payment: z.string().optional(),
         timeoutMs: z
             .number()
             .int()
@@ -1117,12 +1180,14 @@ const getScopeFile = {
         const maxBytes = clampInteger(args.maxBytes, DEFAULT_READ_FILE_MAX_BYTES, 1, MAX_READ_FILE_MAX_BYTES);
         const timeoutMs = clampInteger(args.timeoutMs, DEFAULT_READ_FILE_TIMEOUT_MS, 1000, MAX_READ_FILE_TIMEOUT_MS);
         const resourceUri = rawScopeResourceUri({ scope, at, fileId });
+        const payment = typeof args.payment === "string" ? args.payment : undefined;
         try {
             const raw = await withTimeout(readClient.readRawScopeFile({
                 scope,
                 grantId: grant.grantId,
                 at,
                 fileId,
+                payment,
             }), timeoutMs, `read raw file for ${scope}`);
             const metadata = rawScopeMetadata(raw);
             const base = {
@@ -1133,7 +1198,24 @@ const getScopeFile = {
                 maxBytes,
                 timeoutMs,
             };
-            if (!includeContent || raw.sizeBytes > maxBytes) {
+            // A paid read settles a SINGLE-USE x402 payment for this fetch. A resource
+            // link would force a second, unpaid resources/read → another 402 that
+            // cannot be satisfied, so a paid read returns the bytes inline (regardless
+            // of includeContent) — BUT the hard size cap is still enforced to protect
+            // server/client memory and the MCP transport. An oversized paid file
+            // returns a structured error, never an inline dump; clients size maxBytes
+            // from the payment challenge's `sizeBytes` before paying.
+            const paidRead = Boolean(payment);
+            if (paidRead && raw.sizeBytes > maxBytes) {
+                return textResult({
+                    error: "paid_file_exceeds_max_bytes",
+                    status: 413,
+                    sizeBytes: raw.sizeBytes,
+                    maxBytes,
+                    message: "Payment settled, but the file exceeds maxBytes and is not returned inline. Retry with a larger maxBytes (and a fresh payment); files above the inline ceiling cannot be delivered over MCP.",
+                }, true);
+            }
+            if (!paidRead && (!includeContent || raw.sizeBytes > maxBytes)) {
                 return {
                     content: [
                         {
@@ -1199,6 +1281,44 @@ const getScopeFile = {
                 }, true);
             }
             if (err instanceof McpDataReadError) {
+                if (err.status === 402) {
+                    const body = err.body;
+                    const challenge = body?.error?.details?.challenge;
+                    // Only a genuine PAYMENT_REQUIRED with a challenge is signable; a
+                    // gateway 402 (e.g. insufficient escrow) is surfaced as an error.
+                    if (body?.error?.errorCode === "PAYMENT_REQUIRED" && challenge) {
+                        // Surface the file size so the client can set maxBytes >= sizeBytes
+                        // BEFORE paying — a paid read must fit the inline size cap (the
+                        // single-use payment can't fund a second resources/read).
+                        let meta = null;
+                        try {
+                            meta = await readClient.getScopeMetadata(scope);
+                        }
+                        catch {
+                            meta = null;
+                        }
+                        const sizeBytes = meta?.sizeBytes;
+                        return textResult({
+                            payment_required: true,
+                            status: 402,
+                            challenge,
+                            ...(typeof sizeBytes === "number"
+                                ? { sizeBytes, recommendedMaxBytes: sizeBytes }
+                                : {}),
+                            message: "This file requires payment. Sign the x402 challenge and call get_scope_file again with the `payment` argument" +
+                                (typeof sizeBytes === "number"
+                                    ? ` and maxBytes >= ${sizeBytes}.`
+                                    : "."),
+                        }, true);
+                    }
+                    return textResult({
+                        error: "payment_failed",
+                        status: 402,
+                        errorCode: body?.error?.errorCode ?? "PAYMENT_ERROR",
+                        message: body?.error?.message ??
+                            "Payment could not be completed. This is not a signable challenge; resolve the gateway error and retry.",
+                    }, true);
+                }
                 return textResult({
                     error: err.status === 404
                         ? "scope_file_not_found"