@nevermined-io/payments 1.7.0 → 1.9.0

package/dist/mcp/core/auth.js

@@ -1,10 +1,10 @@
 import { decodeAccessToken } from '../../utils.js';
 import { getCurrentRequestContext } from '../http/mcp-handler.js';
-import { ERROR_CODES, createRpcError } from '../utils/errors.js';
+import { PaymentRequiredError } from '../utils/errors.js';
 import { isValidScheme } from '../../common/types.js';
 import { buildLogicalMetaUrl, buildLogicalUrl } from '../utils/logical-url.js';
 import { extractAuthHeader, stripBearer } from '../utils/request.js';
-import { buildPaymentRequired } from '../../x402/facilitator-api.js';
+import { buildPaymentRequired, buildPaymentRequiredForPlans, } from '../../x402/facilitator-api.js';
 /**
  * Handles authentication and authorization for MCP requests
  */
@@ -95,24 +95,67 @@ export class PaywallAuthenticator {
                 // HTTP fallback also failed
             }
         }
-        // Both attempts failed — enrich denial with suggested plans (best-effort)
-        let plansMsg = '';
-        try {
-            const plans = await this.payments.agents.getAgentPlans(agentId);
-            if (plans && Array.isArray(plans.plans) && plans.plans.length > 0) {
-                const top = plans.plans.slice(0, 3);
-                const summary = top
-                    .map((p) => `${p.planId || p.id || 'plan'}${p.name ? ` (${p.name})` : ''}`)
-                    .join(', ');
-                plansMsg = summary ? ` Available plans: ${summary}...` : '';
+        // Both attempts failed — surface a spec-shaped PaymentRequired error
+        // (converted in-band to a tool-result error for tools; propagates as a
+        // JSON-RPC error for resources/prompts).
+        throw await this.buildPaymentRequiredError(agentId, logicalUrl, 'Payment required.', planIdOverride);
+    }
+    /**
+     * Build a spec-shaped {@link PaymentRequiredError} from the agent's plans.
+     *
+     * Fetches the agent's plans (best-effort) to populate the `accepts` array of
+     * the `PaymentRequired` object and a human-readable list of plan names in the
+     * error message. Falls back to an empty plan id when no plans can be resolved
+     * so the structured shape is still valid.
+     *
+     * @param agentId - Agent identifier used to look up purchasable plans.
+     * @param endpoint - Logical resource URL placed in `PaymentRequired.resource`.
+     * @param message - Leading human-readable message (e.g. "Authorization required.").
+     * @returns A `PaymentRequiredError` carrying the `PaymentRequired` object.
+     */
+    async buildPaymentRequiredError(agentId, endpoint, message = 'Payment required.', fallbackPlanId) {
+        const planIds = [];
+        const names = [];
+        let plansLookupFailed = false;
+        // Only look up the agent's plans when an agentId is configured. Under the
+        // plan-centric model agentId is optional, so we advertise the configured
+        // plan directly (below) instead of requiring an agent lookup.
+        if (agentId) {
+            try {
+                const plans = await this.payments.agents.getAgentPlans(agentId);
+                if (plans && Array.isArray(plans.plans)) {
+                    for (const p of plans.plans) {
+                        const pid = p.planId || p.id;
+                        if (pid)
+                            planIds.push(pid);
+                        if (pid)
+                            names.push(`${pid}${p.name ? ` (${p.name})` : ''}`);
+                    }
+                }
+            }
+            catch (error) {
+                // Best-effort: a backend failure must not look like a clean "unpaid".
+                plansLookupFailed = true;
+                console.error(`[x402] Failed to fetch agent plans while building payment-required (agentId=${agentId}): ${error instanceof Error ? error.message : String(error)}`);
             }
         }
-        catch {
-            // Ignore errors fetching plans - best effort only
+        // Plan-centric fallback: advertise the configured plan when no plans were
+        // resolved via the agent (or no agentId was provided).
+        if (planIds.length === 0 && fallbackPlanId) {
+            planIds.push(fallbackPlanId);
         }
-        throw createRpcError(ERROR_CODES.PaymentRequired, `Payment required.${plansMsg}`, {
-            reason: 'invalid',
+        const plansMsg = names.length > 0 ? ` Available plans: ${names.slice(0, 3).join(', ')}...` : '';
+        const paymentRequired = buildPaymentRequiredForPlans(planIds, {
+            endpoint,
+            agentId,
+            httpVerb: 'POST',
+            environment: this.payments.getEnvironmentName(),
         });
+        // When the plans lookup itself failed (backend outage) the `accepts` array
+        // falls back to an empty plan id; flag it so a client can't mistake the
+        // resulting payment-required for a clean "free / no plan needed" response.
+        paymentRequired.error = plansLookupFailed ? 'plans unavailable' : 'payment required';
+        return new PaymentRequiredError(paymentRequired, `${message}${plansMsg}`);
     }
     /**
      * Verify permissions against a single endpoint URL.
@@ -126,7 +169,8 @@ export class PaywallAuthenticator {
         let planId = planIdOverride ?? decodedAccessToken.accepted?.planId;
         const subscriberAddress = decodedAccessToken.payload?.authorization?.from;
         // If planId is not available, try to get it from the agent's plans
-        if (!planId) {
+        // (only possible when an agentId is configured).
+        if (!planId && agentId) {
             try {
                 const agentPlans = await this.payments.agents.getAgentPlans(agentId);
                 if (agentPlans && Array.isArray(agentPlans.plans) && agentPlans.plans.length > 0) {
@@ -140,7 +184,9 @@ export class PaywallAuthenticator {
         if (!planId || !subscriberAddress) {
             throw new Error('Cannot determine plan_id or subscriber_address from token (expected accepted.planId and payload.authorization.from)');
         }
-        const scheme = isValidScheme(decodedAccessToken?.accepted?.scheme) ? decodedAccessToken.accepted.scheme : 'nvm:erc4337';
+        const scheme = isValidScheme(decodedAccessToken?.accepted?.scheme)
+            ? decodedAccessToken.accepted.scheme
+            : 'nvm:erc4337';
         const paymentRequired = buildPaymentRequired(planId, {
             endpoint,
             agentId,
@@ -162,15 +208,14 @@ export class PaywallAuthenticator {
      * Authenticate an MCP request
      */
     async authenticate(extra, options = {}, agentId, serverName, name, kind, argsOrVars) {
+        const logicalUrl = buildLogicalUrl({ kind, serverName, name, argsOrVars });
         const authHeader = this.extractAuthHeaderFromContext(extra);
         if (!authHeader) {
-            throw createRpcError(ERROR_CODES.PaymentRequired, 'Authorization required', {
-                reason: 'missing',
-            });
+            throw await this.buildPaymentRequiredError(agentId, logicalUrl, 'Authorization required.', options.planId);
         }
         return this.verifyWithFallback({
             accessToken: stripBearer(authHeader),
-            logicalUrl: buildLogicalUrl({ kind, serverName, name, argsOrVars }),
+            logicalUrl,
             httpUrl: this.buildHttpUrlFromContext(),
             maxAmount: options.maxAmount ?? 1n,
             agentId,
@@ -182,15 +227,14 @@ export class PaywallAuthenticator {
      * Returns an AuthResult compatible with paywall flows (without redeem step).
      */
     async authenticateMeta(extra, options = {}, agentId, serverName, method) {
+        const logicalUrl = buildLogicalMetaUrl(serverName, method);
         const authHeader = this.extractAuthHeaderFromContext(extra);
         if (!authHeader) {
-            throw createRpcError(ERROR_CODES.PaymentRequired, 'Authorization required', {
-                reason: 'missing',
-            });
+            throw await this.buildPaymentRequiredError(agentId, logicalUrl, 'Authorization required.', options.planId);
         }
         return this.verifyWithFallback({
             accessToken: stripBearer(authHeader),
-            logicalUrl: buildLogicalMetaUrl(serverName, method),
+            logicalUrl,
             httpUrl: this.buildHttpUrlFromContext(),
             maxAmount: options.maxAmount ?? 1n,
             agentId,

package/dist/mcp/core/auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../../src/mcp/core/auth.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Authentication handler for MCP paywall using X402 tokens\n */\nimport type { Payments } from '../../payments.js'\nimport { decodeAccessToken } from '../../utils.js'\nimport { getCurrentRequestContext } from '../http/mcp-handler.js'\nimport { AuthResult } from '../types/paywall.types.js'\nimport { ERROR_CODES, createRpcError } from '../utils/errors.js'\nimport { Address, isValidScheme } from '../../common/types.js'\nimport { buildLogicalMetaUrl, buildLogicalUrl } from '../utils/logical-url.js'\nimport { extractAuthHeader, stripBearer } from '../utils/request.js'\nimport { buildPaymentRequired, type X402PaymentRequired } from '../../x402/facilitator-api.js'\n\ninterface VerifyContext {\n  accessToken: string\n  logicalUrl: string\n  httpUrl: string | undefined\n  maxAmount: bigint\n  agentId: string\n  planIdOverride?: string\n}\n\n/**\n * Handles authentication and authorization for MCP requests\n */\nexport class PaywallAuthenticator {\n  constructor(private payments: Payments) {}\n\n  /**\n   * Extract authorization header from extra context or AsyncLocalStorage.\n   * Tries SDK's extra context first, then falls back to HTTP request context.\n   *\n   * @param extra - MCP extra context from SDK\n   * @returns Authorization header value or undefined\n   */\n  private extractAuthHeaderFromContext(extra: any): string | undefined {\n    // Try to extract auth header from SDK's extra context first\n    let authHeader = extractAuthHeader(extra)\n\n    if (!authHeader) {\n      const requestContext = getCurrentRequestContext()\n      if (requestContext?.headers) {\n        // Build an extra-like object for extractAuthHeader\n        authHeader = extractAuthHeader({ requestInfo: { headers: requestContext.headers } })\n      }\n    }\n\n    return authHeader\n  }\n\n  /**\n   * Build HTTP endpoint URL from request context.\n   *\n   * @returns HTTP endpoint URL or undefined if context is not available\n   */\n  private buildHttpUrlFromContext(): string | undefined {\n    const requestContext = getCurrentRequestContext()\n    if (!requestContext) {\n      return undefined\n    }\n\n    try {\n      const host = requestContext.headers?.['host'] || requestContext.headers?.['x-forwarded-host']\n      if (!host || typeof host !== 'string') {\n        return undefined\n      }\n\n      const protocol = requestContext.headers?.['x-forwarded-proto'] || 'http'\n      const baseUrl = `${protocol}://${host}`\n\n      // Use requestContext.url if available (e.g., '/mcp'), otherwise default to '/mcp'\n      const path = requestContext.url || '/mcp'\n      return `${baseUrl}${path}`\n    } catch {\n      return undefined\n    }\n  }\n\n  /**\n   * Core verification logic shared by authenticate and authenticateMeta.\n   * Tries logical URL first, falls back to HTTP URL if available.\n   */\n  private async verifyWithFallback(ctx: VerifyContext): Promise<AuthResult> {\n    const { accessToken, logicalUrl, httpUrl, maxAmount, agentId, planIdOverride } = ctx\n\n    // Try logical URL first\n    try {\n      const result = await this.verifyWithEndpoint(\n        accessToken,\n        logicalUrl,\n        agentId,\n        maxAmount,\n        planIdOverride,\n      )\n      return {\n        token: accessToken,\n        agentId,\n        logicalUrl,\n        httpUrl,\n        planId: result.planId,\n        subscriberAddress: result.subscriberAddress,\n        agentRequest: result.agentRequest,\n      }\n    } catch {\n      // If logical URL fails and we have an HTTP URL, try that\n    }\n\n    if (httpUrl) {\n      try {\n        const result = await this.verifyWithEndpoint(\n          accessToken,\n          httpUrl,\n          agentId,\n          maxAmount,\n          planIdOverride,\n        )\n        return {\n          token: accessToken,\n          agentId,\n          logicalUrl,\n          httpUrl,\n          planId: result.planId,\n          subscriberAddress: result.subscriberAddress,\n          agentRequest: result.agentRequest,\n        }\n      } catch {\n        // HTTP fallback also failed\n      }\n    }\n\n    // Both attempts failed — enrich denial with suggested plans (best-effort)\n    let plansMsg = ''\n    try {\n      const plans = await this.payments.agents.getAgentPlans(agentId)\n      if (plans && Array.isArray(plans.plans) && plans.plans.length > 0) {\n        const top = plans.plans.slice(0, 3)\n        const summary = top\n          .map((p: any) => `${p.planId || p.id || 'plan'}${p.name ? ` (${p.name})` : ''}`)\n          .join(', ')\n        plansMsg = summary ? ` Available plans: ${summary}...` : ''\n      }\n    } catch {\n      // Ignore errors fetching plans - best effort only\n    }\n\n    throw createRpcError(ERROR_CODES.PaymentRequired, `Payment required.${plansMsg}`, {\n      reason: 'invalid',\n    })\n  }\n\n  /**\n   * Verify permissions against a single endpoint URL.\n   * Resolves planId from the token or from the agent's plans as fallback.\n   */\n  private async verifyWithEndpoint(\n    accessToken: string,\n    endpoint: string,\n    agentId: string,\n    maxAmount: bigint,\n    planIdOverride?: string,\n  ): Promise<{ planId: string; subscriberAddress: Address; agentRequest?: any }> {\n    const decodedAccessToken = decodeAccessToken(accessToken)\n    if (!decodedAccessToken) {\n      throw new Error('Invalid access token')\n    }\n\n    let planId = planIdOverride ?? decodedAccessToken.accepted?.planId\n    const subscriberAddress = decodedAccessToken.payload?.authorization?.from\n\n    // If planId is not available, try to get it from the agent's plans\n    if (!planId) {\n      try {\n        const agentPlans = await this.payments.agents.getAgentPlans(agentId)\n        if (agentPlans && Array.isArray(agentPlans.plans) && agentPlans.plans.length > 0) {\n          planId = agentPlans.plans[0].planId || agentPlans.plans[0].id\n        }\n      } catch {\n        // Ignore errors fetching plans\n      }\n    }\n\n    if (!planId || !subscriberAddress) {\n      throw new Error(\n        'Cannot determine plan_id or subscriber_address from token (expected accepted.planId and payload.authorization.from)',\n      )\n    }\n\n    const scheme = isValidScheme(decodedAccessToken?.accepted?.scheme) ? decodedAccessToken.accepted.scheme : 'nvm:erc4337'\n    const paymentRequired: X402PaymentRequired = buildPaymentRequired(planId, {\n      endpoint,\n      agentId,\n      httpVerb: 'POST',\n      scheme,\n      environment: this.payments.getEnvironmentName(),\n    })\n\n    const result = await this.payments.facilitator.verifyPermissions({\n      paymentRequired,\n      x402AccessToken: accessToken,\n      maxAmount,\n    })\n\n    if (!result.isValid) {\n      throw new Error('Permission verification failed')\n    }\n\n    return { planId, subscriberAddress, agentRequest: result.agentRequest }\n  }\n\n  /**\n   * Authenticate an MCP request\n   */\n  async authenticate(\n    extra: any,\n    options: { planId?: string; maxAmount?: bigint } = {},\n    agentId: string,\n    serverName: string,\n    name: string,\n    kind: 'tool' | 'resource' | 'prompt',\n    argsOrVars: any,\n  ): Promise<AuthResult> {\n    const authHeader = this.extractAuthHeaderFromContext(extra)\n    if (!authHeader) {\n      throw createRpcError(ERROR_CODES.PaymentRequired, 'Authorization required', {\n        reason: 'missing',\n      })\n    }\n\n    return this.verifyWithFallback({\n      accessToken: stripBearer(authHeader),\n      logicalUrl: buildLogicalUrl({ kind, serverName, name, argsOrVars }),\n      httpUrl: this.buildHttpUrlFromContext(),\n      maxAmount: options.maxAmount ?? 1n,\n      agentId,\n      planIdOverride: options.planId,\n    })\n  }\n\n  /**\n   * Authenticate generic MCP meta operations (e.g., initialize, tools/list, resources/list, prompts/list).\n   * Returns an AuthResult compatible with paywall flows (without redeem step).\n   */\n  async authenticateMeta(\n    extra: any,\n    options: { planId?: string; maxAmount?: bigint } = {},\n    agentId: string,\n    serverName: string,\n    method: string,\n  ): Promise<AuthResult> {\n    const authHeader = this.extractAuthHeaderFromContext(extra)\n    if (!authHeader) {\n      throw createRpcError(ERROR_CODES.PaymentRequired, 'Authorization required', {\n        reason: 'missing',\n      })\n    }\n\n    return this.verifyWithFallback({\n      accessToken: stripBearer(authHeader),\n      logicalUrl: buildLogicalMetaUrl(serverName, method),\n      httpUrl: this.buildHttpUrlFromContext(),\n      maxAmount: options.maxAmount ?? 1n,\n      agentId,\n      planIdOverride: options.planId,\n    })\n  }\n}\n"]}
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../../src/mcp/core/auth.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Authentication handler for MCP paywall using X402 tokens\n */\nimport type { Payments } from '../../payments.js'\nimport { decodeAccessToken } from '../../utils.js'\nimport { getCurrentRequestContext } from '../http/mcp-handler.js'\nimport { AuthResult } from '../types/paywall.types.js'\nimport { PaymentRequiredError } from '../utils/errors.js'\nimport { Address, isValidScheme } from '../../common/types.js'\nimport { buildLogicalMetaUrl, buildLogicalUrl } from '../utils/logical-url.js'\nimport { extractAuthHeader, stripBearer } from '../utils/request.js'\nimport {\n  buildPaymentRequired,\n  buildPaymentRequiredForPlans,\n  type X402PaymentRequired,\n} from '../../x402/facilitator-api.js'\n\ninterface VerifyContext {\n  accessToken: string\n  logicalUrl: string\n  httpUrl: string | undefined\n  maxAmount: bigint\n  agentId?: string\n  planIdOverride?: string\n}\n\n/**\n * Handles authentication and authorization for MCP requests\n */\nexport class PaywallAuthenticator {\n  constructor(private payments: Payments) {}\n\n  /**\n   * Extract authorization header from extra context or AsyncLocalStorage.\n   * Tries SDK's extra context first, then falls back to HTTP request context.\n   *\n   * @param extra - MCP extra context from SDK\n   * @returns Authorization header value or undefined\n   */\n  private extractAuthHeaderFromContext(extra: any): string | undefined {\n    // Try to extract auth header from SDK's extra context first\n    let authHeader = extractAuthHeader(extra)\n\n    if (!authHeader) {\n      const requestContext = getCurrentRequestContext()\n      if (requestContext?.headers) {\n        // Build an extra-like object for extractAuthHeader\n        authHeader = extractAuthHeader({ requestInfo: { headers: requestContext.headers } })\n      }\n    }\n\n    return authHeader\n  }\n\n  /**\n   * Build HTTP endpoint URL from request context.\n   *\n   * @returns HTTP endpoint URL or undefined if context is not available\n   */\n  private buildHttpUrlFromContext(): string | undefined {\n    const requestContext = getCurrentRequestContext()\n    if (!requestContext) {\n      return undefined\n    }\n\n    try {\n      const host = requestContext.headers?.['host'] || requestContext.headers?.['x-forwarded-host']\n      if (!host || typeof host !== 'string') {\n        return undefined\n      }\n\n      const protocol = requestContext.headers?.['x-forwarded-proto'] || 'http'\n      const baseUrl = `${protocol}://${host}`\n\n      // Use requestContext.url if available (e.g., '/mcp'), otherwise default to '/mcp'\n      const path = requestContext.url || '/mcp'\n      return `${baseUrl}${path}`\n    } catch {\n      return undefined\n    }\n  }\n\n  /**\n   * Core verification logic shared by authenticate and authenticateMeta.\n   * Tries logical URL first, falls back to HTTP URL if available.\n   */\n  private async verifyWithFallback(ctx: VerifyContext): Promise<AuthResult> {\n    const { accessToken, logicalUrl, httpUrl, maxAmount, agentId, planIdOverride } = ctx\n\n    // Try logical URL first\n    try {\n      const result = await this.verifyWithEndpoint(\n        accessToken,\n        logicalUrl,\n        agentId,\n        maxAmount,\n        planIdOverride,\n      )\n      return {\n        token: accessToken,\n        agentId,\n        logicalUrl,\n        httpUrl,\n        planId: result.planId,\n        subscriberAddress: result.subscriberAddress,\n        agentRequest: result.agentRequest,\n      }\n    } catch {\n      // If logical URL fails and we have an HTTP URL, try that\n    }\n\n    if (httpUrl) {\n      try {\n        const result = await this.verifyWithEndpoint(\n          accessToken,\n          httpUrl,\n          agentId,\n          maxAmount,\n          planIdOverride,\n        )\n        return {\n          token: accessToken,\n          agentId,\n          logicalUrl,\n          httpUrl,\n          planId: result.planId,\n          subscriberAddress: result.subscriberAddress,\n          agentRequest: result.agentRequest,\n        }\n      } catch {\n        // HTTP fallback also failed\n      }\n    }\n\n    // Both attempts failed — surface a spec-shaped PaymentRequired error\n    // (converted in-band to a tool-result error for tools; propagates as a\n    // JSON-RPC error for resources/prompts).\n    throw await this.buildPaymentRequiredError(agentId, logicalUrl, 'Payment required.', planIdOverride)\n  }\n\n  /**\n   * Build a spec-shaped {@link PaymentRequiredError} from the agent's plans.\n   *\n   * Fetches the agent's plans (best-effort) to populate the `accepts` array of\n   * the `PaymentRequired` object and a human-readable list of plan names in the\n   * error message. Falls back to an empty plan id when no plans can be resolved\n   * so the structured shape is still valid.\n   *\n   * @param agentId - Agent identifier used to look up purchasable plans.\n   * @param endpoint - Logical resource URL placed in `PaymentRequired.resource`.\n   * @param message - Leading human-readable message (e.g. \"Authorization required.\").\n   * @returns A `PaymentRequiredError` carrying the `PaymentRequired` object.\n   */\n  private async buildPaymentRequiredError(\n    agentId: string | undefined,\n    endpoint: string,\n    message = 'Payment required.',\n    fallbackPlanId?: string,\n  ): Promise<PaymentRequiredError> {\n    const planIds: string[] = []\n    const names: string[] = []\n    let plansLookupFailed = false\n    // Only look up the agent's plans when an agentId is configured. Under the\n    // plan-centric model agentId is optional, so we advertise the configured\n    // plan directly (below) instead of requiring an agent lookup.\n    if (agentId) {\n      try {\n        const plans = await this.payments.agents.getAgentPlans(agentId)\n        if (plans && Array.isArray(plans.plans)) {\n          for (const p of plans.plans) {\n            const pid = p.planId || p.id\n            if (pid) planIds.push(pid)\n            if (pid) names.push(`${pid}${p.name ? ` (${p.name})` : ''}`)\n          }\n        }\n      } catch (error) {\n        // Best-effort: a backend failure must not look like a clean \"unpaid\".\n        plansLookupFailed = true\n        console.error(\n          `[x402] Failed to fetch agent plans while building payment-required (agentId=${agentId}): ${\n            error instanceof Error ? error.message : String(error)\n          }`,\n        )\n      }\n    }\n\n    // Plan-centric fallback: advertise the configured plan when no plans were\n    // resolved via the agent (or no agentId was provided).\n    if (planIds.length === 0 && fallbackPlanId) {\n      planIds.push(fallbackPlanId)\n    }\n\n    const plansMsg = names.length > 0 ? ` Available plans: ${names.slice(0, 3).join(', ')}...` : ''\n\n    const paymentRequired = buildPaymentRequiredForPlans(planIds, {\n      endpoint,\n      agentId,\n      httpVerb: 'POST',\n      environment: this.payments.getEnvironmentName(),\n    }) as X402PaymentRequired & { error?: string }\n    // When the plans lookup itself failed (backend outage) the `accepts` array\n    // falls back to an empty plan id; flag it so a client can't mistake the\n    // resulting payment-required for a clean \"free / no plan needed\" response.\n    paymentRequired.error = plansLookupFailed ? 'plans unavailable' : 'payment required'\n\n    return new PaymentRequiredError(paymentRequired, `${message}${plansMsg}`)\n  }\n\n  /**\n   * Verify permissions against a single endpoint URL.\n   * Resolves planId from the token or from the agent's plans as fallback.\n   */\n  private async verifyWithEndpoint(\n    accessToken: string,\n    endpoint: string,\n    agentId: string | undefined,\n    maxAmount: bigint,\n    planIdOverride?: string,\n  ): Promise<{ planId: string; subscriberAddress: Address; agentRequest?: any }> {\n    const decodedAccessToken = decodeAccessToken(accessToken)\n    if (!decodedAccessToken) {\n      throw new Error('Invalid access token')\n    }\n\n    let planId = planIdOverride ?? decodedAccessToken.accepted?.planId\n    const subscriberAddress = decodedAccessToken.payload?.authorization?.from\n\n    // If planId is not available, try to get it from the agent's plans\n    // (only possible when an agentId is configured).\n    if (!planId && agentId) {\n      try {\n        const agentPlans = await this.payments.agents.getAgentPlans(agentId)\n        if (agentPlans && Array.isArray(agentPlans.plans) && agentPlans.plans.length > 0) {\n          planId = agentPlans.plans[0].planId || agentPlans.plans[0].id\n        }\n      } catch {\n        // Ignore errors fetching plans\n      }\n    }\n\n    if (!planId || !subscriberAddress) {\n      throw new Error(\n        'Cannot determine plan_id or subscriber_address from token (expected accepted.planId and payload.authorization.from)',\n      )\n    }\n\n    const scheme = isValidScheme(decodedAccessToken?.accepted?.scheme)\n      ? decodedAccessToken.accepted.scheme\n      : 'nvm:erc4337'\n    const paymentRequired: X402PaymentRequired = buildPaymentRequired(planId, {\n      endpoint,\n      agentId,\n      httpVerb: 'POST',\n      scheme,\n      environment: this.payments.getEnvironmentName(),\n    })\n\n    const result = await this.payments.facilitator.verifyPermissions({\n      paymentRequired,\n      x402AccessToken: accessToken,\n      maxAmount,\n    })\n\n    if (!result.isValid) {\n      throw new Error('Permission verification failed')\n    }\n\n    return { planId, subscriberAddress, agentRequest: result.agentRequest }\n  }\n\n  /**\n   * Authenticate an MCP request\n   */\n  async authenticate(\n    extra: any,\n    options: { planId?: string; maxAmount?: bigint } = {},\n    agentId: string | undefined,\n    serverName: string,\n    name: string,\n    kind: 'tool' | 'resource' | 'prompt',\n    argsOrVars: any,\n  ): Promise<AuthResult> {\n    const logicalUrl = buildLogicalUrl({ kind, serverName, name, argsOrVars })\n\n    const authHeader = this.extractAuthHeaderFromContext(extra)\n    if (!authHeader) {\n      throw await this.buildPaymentRequiredError(\n        agentId,\n        logicalUrl,\n        'Authorization required.',\n        options.planId,\n      )\n    }\n\n    return this.verifyWithFallback({\n      accessToken: stripBearer(authHeader),\n      logicalUrl,\n      httpUrl: this.buildHttpUrlFromContext(),\n      maxAmount: options.maxAmount ?? 1n,\n      agentId,\n      planIdOverride: options.planId,\n    })\n  }\n\n  /**\n   * Authenticate generic MCP meta operations (e.g., initialize, tools/list, resources/list, prompts/list).\n   * Returns an AuthResult compatible with paywall flows (without redeem step).\n   */\n  async authenticateMeta(\n    extra: any,\n    options: { planId?: string; maxAmount?: bigint } = {},\n    agentId: string | undefined,\n    serverName: string,\n    method: string,\n  ): Promise<AuthResult> {\n    const logicalUrl = buildLogicalMetaUrl(serverName, method)\n\n    const authHeader = this.extractAuthHeaderFromContext(extra)\n    if (!authHeader) {\n      throw await this.buildPaymentRequiredError(\n        agentId,\n        logicalUrl,\n        'Authorization required.',\n        options.planId,\n      )\n    }\n\n    return this.verifyWithFallback({\n      accessToken: stripBearer(authHeader),\n      logicalUrl,\n      httpUrl: this.buildHttpUrlFromContext(),\n      maxAmount: options.maxAmount ?? 1n,\n      agentId,\n      planIdOverride: options.planId,\n    })\n  }\n}\n"]}

package/dist/mcp/core/paywall.d.ts

@@ -24,6 +24,12 @@ export declare class PaywallDecorator {
      * Internal method to create the wrapped handler
      */
     private createWrappedHandler;
+    /**
+     * Build a spec-shaped `PaymentRequired` dict for a settlement failure, from
+     * the authenticated request context. Surfaced (with tool content suppressed)
+     * when settlement fails after the tool has executed.
+     */
+    private buildPaymentRequiredFromAuth;
     /**
      * Redeem credits after successful request
      */

package/dist/mcp/core/paywall.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paywall.d.ts","sourceRoot":"","sources":["../../../src/mcp/core/paywall.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAOjD,OAAO,EACL,SAAS,EAET,aAAa,EACb,eAAe,EACf,WAAW,EACZ,MAAM,2BAA2B,CAAA;AAElC,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AAChD,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AAE7D;;GAEG;AACH,qBAAa,gBAAgB;IAQzB,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,aAAa;IACrB,OAAO,CAAC,cAAc;IARxB,OAAO,CAAC,MAAM,CAGb;gBAGS,QAAQ,EAAE,QAAQ,EAClB,aAAa,EAAE,oBAAoB,EACnC,cAAc,EAAE,sBAAsB;IAGhD;;OAEG;IACH,SAAS,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI;IAOnC;;OAEG;IAEH,OAAO,CAAC,KAAK,GAAG,GAAG,EACjB,OAAO,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,GAAG,GAAG,EACzD,OAAO,EAAE,WAAW,GAAG,aAAa,GACnC,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC;IAC7C,OAAO,CACL,OAAO,EAAE,CACP,GAAG,EAAE,GAAG,EACR,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,EAC5C,KAAK,CAAC,EAAE,GAAG,KACR,OAAO,CAAC,GAAG,CAAC,GAAG,GAAG,EACvB,OAAO,EAAE,eAAe,GACvB,CAAC,GAAG,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC;IAKxF;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAiH5B;;OAEG;YACW,aAAa;CAoE5B"}
+{"version":3,"file":"paywall.d.ts","sourceRoot":"","sources":["../../../src/mcp/core/paywall.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAQjD,OAAO,EAEL,SAAS,EAET,aAAa,EACb,eAAe,EACf,WAAW,EACZ,MAAM,2BAA2B,CAAA;AAalC,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AAChD,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AAM7D;;GAEG;AACH,qBAAa,gBAAgB;IAQzB,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,aAAa;IACrB,OAAO,CAAC,cAAc;IARxB,OAAO,CAAC,MAAM,CAGb;gBAGS,QAAQ,EAAE,QAAQ,EAClB,aAAa,EAAE,oBAAoB,EACnC,cAAc,EAAE,sBAAsB;IAGhD;;OAEG;IACH,SAAS,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI;IAQnC;;OAEG;IAEH,OAAO,CAAC,KAAK,GAAG,GAAG,EACjB,OAAO,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,GAAG,GAAG,EACzD,OAAO,EAAE,WAAW,GAAG,aAAa,GACnC,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC;IAC7C,OAAO,CACL,OAAO,EAAE,CACP,GAAG,EAAE,GAAG,EACR,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,EAC5C,KAAK,CAAC,EAAE,GAAG,KACR,OAAO,CAAC,GAAG,CAAC,GAAG,GAAG,EACvB,OAAO,EAAE,eAAe,GACvB,CAAC,GAAG,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC;IAKxF;;OAEG;IACH,OAAO,CAAC,oBAAoB;IA6K5B;;;;OAIG;IACH,OAAO,CAAC,4BAA4B;IAYpC;;OAEG;YACW,aAAa;CAyE5B"}

package/dist/mcp/core/paywall.js

@@ -2,9 +2,13 @@
  * Main paywall decorator for MCP handlers (tools, resources, prompts)
  */
 import { isValidScheme } from '../../common/types.js';
-import { decodeAccessToken } from '../../utils.js';
-import { buildPaymentRequired, } from '../../x402/facilitator-api.js';
-import { ERROR_CODES, createRpcError } from '../utils/errors.js';
+import { decodeAccessToken, encodeAccessToken } from '../../utils.js';
+import { buildPaymentRequired, buildPaymentRequiredForPlans, } from '../../x402/facilitator-api.js';
+import { ERROR_CODES, PaymentRequiredError, SettlementFailedError, createRpcError, } from '../utils/errors.js';
+import { NEVERMINED_CREDITS_META_KEY, X402_PAYMENT_RESPONSE_META_KEY, paymentRequiredResult, readPaymentPayload, } from '../utils/meta.js';
+// Emit the Authorization-header deprecation notice at most once per process to
+// avoid log spam on high-traffic servers still using the legacy header path.
+let authHeaderDeprecationWarned = false;
 /**
  * Main class for creating paywall-protected MCP handlers
  */
@@ -15,7 +19,7 @@ export class PaywallDecorator {
         this.creditsContext = creditsContext;
         // Internal config ensures serverName is always a concrete string
         this.config = {
-            agentId: '',
+            planId: '',
             serverName: 'mcp-server',
         };
     }
@@ -24,7 +28,8 @@ export class PaywallDecorator {
      */
     configure(options) {
         this.config = {
-            agentId: options.agentId || this.config.agentId,
+            planId: options.planId || this.config.planId,
+            agentId: options.agentId ?? this.config.agentId,
             serverName: options.serverName ?? this.config.serverName,
         };
     }
@@ -36,9 +41,12 @@ export class PaywallDecorator {
      */
     createWrappedHandler(handler, options) {
         return async (...allArgs) => {
-            // Validate configuration
-            if (!this.config.agentId) {
-                throw createRpcError(ERROR_CODES.Misconfiguration, 'Server misconfiguration: missing agentId');
+            // Validate configuration: a planId must be resolvable (per-tool option or
+            // server-level config). agentId is optional under the plan-centric model
+            // (the facilitator resolves everything from planId + token).
+            const configuredPlanId = options?.planId ?? this.config.planId;
+            if (!configuredPlanId) {
+                throw createRpcError(ERROR_CODES.Misconfiguration, 'Server misconfiguration: missing planId');
             }
             const kind = options?.kind ?? 'tool';
             const name = options?.name ?? 'unnamed';
@@ -46,81 +54,150 @@ export class PaywallDecorator {
             const isResource = allArgs.length >= 2 && allArgs[0] instanceof URL;
             const extra = isResource ? allArgs[2] : allArgs[1];
             const argsOrVars = isResource ? allArgs[1] : allArgs[0];
-            // 1. Authenticate request
-            const authResult = await this.authenticator.authenticate(extra, { planId: options?.planId, maxAmount: options?.maxAmount }, this.config.agentId, this.config.serverName, name, kind, argsOrVars);
-            // 2. Pre-calculate credits if they are fixed (not a function)
-            // This allows handlers to access credits during execution
-            const creditsOption = options?.credits;
-            const isFixedCredits = typeof creditsOption === 'bigint' || creditsOption === undefined;
-            const preCalculatedCredits = isFixedCredits
-                ? this.creditsContext.resolve(creditsOption, argsOrVars, null, authResult)
-                : undefined;
-            // Determine effective planId: explicit option overrides token-derived value
-            const effectivePlanId = options?.planId ?? authResult.planId;
-            // 3. Build PaywallContext for handler (with extra wrapper for backward compatibility)
-            const paywallContext = {
-                authResult,
-                credits: preCalculatedCredits,
-                planId: authResult.planId,
-                subscriberAddress: authResult.subscriberAddress,
-                agentRequest: authResult.agentRequest,
-            };
-            // 4. Execute original handler with context
-            const result = await handler(...allArgs, paywallContext);
-            // 5. Resolve final credits to burn (may be different if credits are dynamic)
-            const credits = isFixedCredits
-                ? (preCalculatedCredits ?? 1n)
-                : this.creditsContext.resolve(creditsOption, argsOrVars, result, authResult);
-            // Update context with final resolved credits
-            paywallContext.credits = credits;
-            // 6. If the result is an AsyncIterable (stream), redeem on completion
-            if (isAsyncIterable(result)) {
-                const onFinally = async () => {
-                    return await this.redeemCredits(effectivePlanId, authResult.token, authResult.subscriberAddress, credits, options, authResult.agentId, authResult.logicalUrl, authResult.httpUrl, 'POST');
+            try {
+                // x402 v2 MCP transport: prefer the in-band payment payload from
+                // params._meta["x402/payment"]. Re-encode it into the access token
+                // string the verify/settle path expects and present it via the same
+                // extra/headers shape the auth flow reads, so the in-band payload takes
+                // precedence over the Authorization header (kept as a deprecated
+                // fallback when the in-band payload is absent). The RAW extra is still
+                // forwarded to the user handler below.
+                const paymentPayload = readPaymentPayload(extra);
+                let authExtra = extra;
+                if (paymentPayload) {
+                    const token = encodeAccessToken(paymentPayload);
+                    // Synthesize an auth-only extra carrying the in-band token. This
+                    // intentionally drops the rest of `extra` for the AUTH call only; the
+                    // RAW `extra` (with `_meta`) is still forwarded to the user handler below.
+                    authExtra = { requestInfo: { headers: { authorization: `Bearer ${token}` } } };
+                }
+                else if (!authHeaderDeprecationWarned) {
+                    authHeaderDeprecationWarned = true;
+                    console.warn('[x402] No _meta["x402/payment"] on the MCP request; falling back to the ' +
+                        'Authorization header (deprecated under the x402 v2 MCP transport).');
+                }
+                // 1. Authenticate request
+                const authResult = await this.authenticator.authenticate(authExtra, { planId: configuredPlanId, maxAmount: options?.maxAmount }, this.config.agentId, this.config.serverName, name, kind, argsOrVars);
+                // 2. Pre-calculate credits if they are fixed (not a function)
+                // This allows handlers to access credits during execution
+                const creditsOption = options?.credits;
+                const isFixedCredits = typeof creditsOption === 'bigint' || creditsOption === undefined;
+                const preCalculatedCredits = isFixedCredits
+                    ? this.creditsContext.resolve(creditsOption, argsOrVars, null, authResult)
+                    : undefined;
+                // Determine effective planId: explicit option overrides token-derived value
+                const effectivePlanId = options?.planId ?? authResult.planId;
+                // 3. Build PaywallContext for handler (with extra wrapper for backward compatibility)
+                const paywallContext = {
+                    authResult,
+                    credits: preCalculatedCredits,
+                    planId: authResult.planId,
+                    subscriberAddress: authResult.subscriberAddress,
+                    agentRequest: authResult.agentRequest,
                 };
-                return wrapAsyncIterable(result, onFinally, effectivePlanId, authResult.subscriberAddress, credits);
+                // 4. Execute original handler with context
+                const result = await handler(...allArgs, paywallContext);
+                // 5. Resolve final credits to burn (may be different if credits are dynamic)
+                const credits = isFixedCredits
+                    ? (preCalculatedCredits ?? 1n)
+                    : this.creditsContext.resolve(creditsOption, argsOrVars, result, authResult);
+                // Update context with final resolved credits
+                paywallContext.credits = credits;
+                // 6. If the result is an AsyncIterable (stream), redeem on completion
+                if (isAsyncIterable(result)) {
+                    const onFinally = async () => {
+                        return await this.redeemCredits(effectivePlanId, authResult.token, authResult.subscriberAddress, credits, options, authResult.agentId, authResult.logicalUrl, authResult.httpUrl, 'POST');
+                    };
+                    return wrapAsyncIterable(result, onFinally, effectivePlanId, authResult.subscriberAddress, credits);
+                }
+                // 7. Non-streaming: redeem immediately
+                const creditsResult = await this.redeemCredits(effectivePlanId, authResult.token, authResult.subscriberAddress, credits, options, authResult.agentId, authResult.logicalUrl, 
+                // fix: pre-existing arg order — fallbackEndpoint=httpUrl, httpVerb='POST'
+                // (matches the streaming site above)
+                authResult.httpUrl, 'POST');
+                // Settlement failed AFTER the tool executed: per the x402 v2 MCP
+                // transport spec, do NOT return the tool's content — surface only the
+                // payment error so a paid result is never delivered without payment
+                // landing. (onRedeemError "ignore" therefore no longer delivers paid
+                // content; "propagate" already threw a Misconfiguration in redeemCredits.)
+                if (creditsResult && !creditsResult.success) {
+                    console.error(`[x402] settlement failed after tool execution; suppressing tool content. reason=${creditsResult.errorReason}`);
+                    throw new SettlementFailedError(this.buildPaymentRequiredFromAuth(authResult));
+                }
+                // creditsResult is undefined for free / no-credit calls (no settlement
+                // performed) — in that case the spec receipt is omitted. On success the
+                // full receipt goes under the spec key; Nevermined observability is kept
+                // under a namespaced key so it never collides with the spec shape.
+                result._meta = {
+                    ...result._meta,
+                    ...(creditsResult && { [X402_PAYMENT_RESPONSE_META_KEY]: creditsResult }),
+                    [NEVERMINED_CREDITS_META_KEY]: {
+                        ...(creditsResult?.transaction && { txHash: creditsResult.transaction }),
+                        creditsRedeemed: creditsResult?.success
+                            ? (creditsResult.creditsRedeemed ?? credits.toString())
+                            : '0',
+                        remainingBalance: creditsResult?.remainingBalance,
+                        planId: authResult.planId,
+                        subscriberAddress: authResult.subscriberAddress,
+                        success: creditsResult ? creditsResult.success : true,
+                    },
+                };
+                return result;
+            }
+            catch (error) {
+                // Payment-required (pre-execution, from auth) and settlement-failure
+                // (post-execution) are surfaced in band as an error tool result for
+                // tools. Resources/prompts have no tool-result error channel, so the
+                // error propagates as a JSON-RPC error instead.
+                if (error instanceof PaymentRequiredError && kind === 'tool') {
+                    return paymentRequiredResult(error.paymentRequired);
+                }
+                throw error;
             }
-            // 7. Non-streaming: redeem immediately
-            const creditsResult = await this.redeemCredits(effectivePlanId, authResult.token, authResult.subscriberAddress, credits, options, authResult.agentId, authResult.logicalUrl, 'POST', authResult.httpUrl);
-            result._meta = {
-                ...result._meta,
-                ...(creditsResult.transaction && { txHash: creditsResult.transaction }),
-                creditsRedeemed: creditsResult.success ? (creditsResult.creditsRedeemed ?? credits.toString()) : '0',
-                remainingBalance: creditsResult.remainingBalance,
-                planId: authResult.planId,
-                subscriberAddress: authResult.subscriberAddress,
-                success: creditsResult.success,
-                ...(creditsResult.errorReason && { errorReason: creditsResult.errorReason }),
-            };
-            return result;
         };
     }
+    /**
+     * Build a spec-shaped `PaymentRequired` dict for a settlement failure, from
+     * the authenticated request context. Surfaced (with tool content suppressed)
+     * when settlement fails after the tool has executed.
+     */
+    buildPaymentRequiredFromAuth(authResult) {
+        const planId = authResult.planId || '';
+        const paymentRequired = buildPaymentRequiredForPlans(planId ? [planId] : [''], {
+            endpoint: authResult.logicalUrl || authResult.httpUrl,
+            agentId: authResult.agentId,
+            httpVerb: 'POST',
+            environment: this.payments.getEnvironmentName(),
+        });
+        paymentRequired.error = 'settlement failed';
+        return paymentRequired;
+    }
     /**
      * Redeem credits after successful request
      */
     async redeemCredits(planId, token, subscriberAddress, credits, options, agentId, endpoint, fallbackEndpoint, httpVerb) {
-        let ret = {
-            success: true,
-            transaction: '',
-            network: '',
-        };
+        // No settlement for free / no-credit calls — signalled to the caller as
+        // `undefined` so the spec receipt (_meta["x402/payment-response"]) is omitted.
+        if (!(credits && credits > 0n && subscriberAddress && planId)) {
+            return undefined;
+        }
         const decoded = decodeAccessToken(token);
-        const scheme = isValidScheme(decoded?.accepted?.scheme) ? decoded.accepted.scheme : 'nvm:erc4337';
+        const scheme = isValidScheme(decoded?.accepted?.scheme)
+            ? decoded.accepted.scheme
+            : 'nvm:erc4337';
         try {
-            if (credits && credits > 0n && subscriberAddress && planId) {
-                const paymentRequired = buildPaymentRequired(planId, {
-                    endpoint: endpoint || '',
-                    agentId,
-                    httpVerb,
-                    scheme,
-                    environment: this.payments.getEnvironmentName(),
-                });
-                ret = await this.payments.facilitator.settlePermissions({
-                    paymentRequired,
-                    x402AccessToken: token,
-                    maxAmount: credits,
-                });
-            }
+            const paymentRequired = buildPaymentRequired(planId, {
+                endpoint: endpoint || '',
+                agentId,
+                httpVerb,
+                scheme,
+                environment: this.payments.getEnvironmentName(),
+            });
+            return await this.payments.facilitator.settlePermissions({
+                paymentRequired,
+                x402AccessToken: token,
+                maxAmount: credits,
+            });
         }
         catch (primaryError) {
             // If logical URL fails and we have an HTTP URL fallback, retry with it
@@ -134,26 +211,27 @@ export class PaywallDecorator {
                         scheme,
                         environment: this.payments.getEnvironmentName(),
                     });
-                    ret = await this.payments.facilitator.settlePermissions({
+                    return await this.payments.facilitator.settlePermissions({
                         paymentRequired,
                         x402AccessToken: token,
                         maxAmount: credits,
                     });
-                    return ret;
                 }
                 catch (fallbackError) {
                     // Fallback also failed, use fallback error as the reported error
                     lastError = fallbackError;
                 }
             }
-            ret.success = false;
-            ret.errorReason = lastError instanceof Error ? lastError.message : String(lastError);
+            const errorReason = lastError instanceof Error ? lastError.message : String(lastError);
+            console.error(`[x402] settle failed: ${errorReason}`);
             if (options.onRedeemError === 'propagate') {
-                throw createRpcError(ERROR_CODES.Misconfiguration, `Failed to redeem credits: ${ret.errorReason}`);
+                throw createRpcError(ERROR_CODES.Misconfiguration, `Failed to redeem credits: ${errorReason}`);
             }
-            // Default: attach error to result but don't throw
+            // Default ("ignore"): return a failed result so the caller suppresses the
+            // tool content and surfaces the in-band payment error (always-suppress
+            // under the x402 v2 MCP transport).
+            return { success: false, transaction: '', network: '', errorReason };
         }
-        return ret;
     }
 }
 /**
@@ -176,17 +254,29 @@ function wrapAsyncIterable(iterable, onFinally, planId, subscriberAddress, credi
         finally {
             creditsResult = await onFinally();
         }
-        // Yield a _meta chunk at the end with the redemption result
+        // Yield a _meta chunk at the end with the redemption result.
+        // NOTE: a stream cannot retroactively suppress already-yielded chunks, so a
+        // post-execution settlement failure on a stream is only reported here in the
+        // final _meta chunk (under nevermined/credits) — it cannot withhold content
+        // the way a non-streaming tool result does. `creditsResult` is undefined for
+        // free / no-credit calls.
+        const settlement = creditsResult || undefined;
         const metadataChunk = {
             _meta: {
-                // Only include txHash if it has a value
-                ...(creditsResult?.transaction && { txHash: creditsResult.transaction }),
-                creditsRedeemed: creditsResult?.success ? (creditsResult.creditsRedeemed ?? credits.toString()) : '0',
-                remainingBalance: creditsResult?.remainingBalance,
-                planId,
-                subscriberAddress,
-                success: creditsResult?.success || false,
-                ...(creditsResult?.errorReason && { errorReason: creditsResult.errorReason }),
+                // Spec receipt only on a successful settlement.
+                ...(settlement?.success && { [X402_PAYMENT_RESPONSE_META_KEY]: settlement }),
+                // Nevermined-namespaced observability (NOT part of the x402 spec).
+                [NEVERMINED_CREDITS_META_KEY]: {
+                    ...(settlement?.transaction && { txHash: settlement.transaction }),
+                    creditsRedeemed: settlement?.success
+                        ? (settlement.creditsRedeemed ?? credits.toString())
+                        : '0',
+                    remainingBalance: settlement?.remainingBalance,
+                    planId,
+                    subscriberAddress,
+                    success: settlement ? settlement.success : true,
+                    ...(settlement?.errorReason && { errorReason: settlement.errorReason }),
+                },
             },
         };
         yield metadataChunk;