v0.2.16: sync from monorepo 2026-06-04

Author: azeth-sync[bot]

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azeth/mcp-server",
-  "version": "0.2.15",
+  "version": "0.2.16",
   "mcpName": "io.github.azeth-protocol/mcp-server",
   "type": "module",
   "description": "MCP server for the Azeth trust infrastructure — smart accounts, payments, reputation, and discovery tools for AI agents",
@@ -41,13 +41,16 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@azeth/common": "^0.2.15",
-    "@azeth/sdk": "^0.2.15",
+    "@azeth/common": "^0.2.16",
+    "@azeth/sdk": "^0.2.16",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "dotenv": "^16.4.0",
     "viem": "^2.21.0",
     "zod": "^3.25.0"
   },
+  "optionalDependencies": {
+    "undici": "^6.21.0"
+  },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "typescript": "^5.7.0",

src/tools/agreements.ts

@@ -336,8 +336,24 @@ export function registerAgreementTools(server: McpServer): void {
           // Receipt fetch failed — fall back to delta approach below
         }
 
-        // Enrich response with post-execution state
-        const agreement = await client.getAgreement(agreementId, account);
+        // Enrich response with post-execution state.
+        // F2: guard against a read-after-write race. A load-balanced RPC node can serve
+        // this getAgreement from a block that predates the just-mined UserOp, returning
+        // stale executionCount / totalPaid / remainingBudget (the on-chain state is
+        // correct; only this read lagged). When a payment was made (executionAmount > 0)
+        // but the read's totalPaid hasn't advanced to include it, re-read with a short
+        // backoff until the node reflects this execution — fixing all derived fields atomically.
+        let agreement = await client.getAgreement(agreementId, account);
+        if (executionAmount > 0n) {
+          for (
+            let attempt = 0;
+            attempt < 5 && agreement.totalPaid < preExecutionTotal + executionAmount;
+            attempt++
+          ) {
+            await new Promise((resolve) => setTimeout(resolve, 300));
+            agreement = await client.getAgreement(agreementId, account);
+          }
+        }
         const decimals = tokenDecimals(agreement.token, chain);
         const tokenSymbol = resolveTokenSymbol(agreement.token, chain);
         const now = BigInt(Math.floor(Date.now() / 1000));

src/tools/payments.ts

@@ -6,6 +6,7 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import { AzethError, AZETH_CONTRACTS, TOKENS, formatTokenAmount } from '@azeth/common';
 import type { AzethKit } from '@azeth/sdk';
+import { secureFetch, type SecureFetchGuard } from '@azeth/sdk';
 import { createClient, resolveChain, validateAddress } from '../utils/client.js';
 import { resolveAddress } from '../utils/resolve.js';
 import { success, error, handleError, guardianRequiredError } from '../utils/response.js';
@@ -174,6 +175,66 @@ async function validateExternalUrl(urlStr: string): Promise<ValidatedUrl> {
   return { url: urlStr, pinnedIPv4 };
 }
 
+/** Lazily load undici's `Agent` (an OPTIONAL dependency). undici is Node's built-in HTTP
+ *  engine, but it must be installed as a package to construct a custom connection
+ *  dispatcher. If unavailable, the connection pin is skipped — validate + redirect-refusal
+ *  still apply (graceful degradation). */
+let agentCtorPromise: Promise<(new (opts: unknown) => unknown) | undefined> | undefined;
+function loadAgentCtor(): Promise<(new (opts: unknown) => unknown) | undefined> {
+  if (!agentCtorPromise) {
+    // `as string` keeps this a runtime-only dynamic import so the build does not require
+    // undici's type declarations to be present.
+    agentCtorPromise = import('undici' as string)
+      .then((m: { Agent?: new (opts: unknown) => unknown }) => m.Agent)
+      .catch(() => undefined);
+  }
+  return agentCtorPromise;
+}
+
+/** Build a connection dispatcher pinned to the already-validated public IPv4 address(es).
+ *  Closes the DNS-rebinding TOCTOU: after validateExternalUrl confirms the host resolves to
+ *  public IPs, the actual connection is pinned to those IPs and cannot be re-resolved to a
+ *  private target. TLS SNI / certificate validation still uses the URL hostname. Returns
+ *  undefined when there is nothing to pin (e.g. IPv6-only host) or undici is unavailable —
+ *  the request then proceeds with validate-only protection. (F9) */
+/** A net.LookupFunction-compatible resolver that pins DNS resolution to the given
+ *  already-validated public IPv4 address(es), ignoring the hostname. This is what makes
+ *  the connection immune to DNS rebinding: no matter what an attacker-controlled DNS
+ *  record returns at connect time, the socket only ever connects to the pre-validated IPs.
+ *  Supports both the single-address and `{ all }` callback forms. Exported for tests. (F9) */
+export function createPinnedLookup(
+  pinnedIPv4: string[],
+): (
+  hostname: string,
+  opts: { all?: boolean } | undefined,
+  cb: (err: Error | null, address: unknown, family?: number) => void,
+) => void {
+  return (_hostname, opts, cb): void => {
+    if (opts?.all) cb(null, pinnedIPv4.map((address) => ({ address, family: 4 })));
+    else cb(null, pinnedIPv4[0], 4);
+  };
+}
+
+async function buildPinnedDispatcher(pinnedIPv4: string[]): Promise<unknown | undefined> {
+  if (pinnedIPv4.length === 0) return undefined;
+  const AgentCtor = await loadAgentCtor();
+  if (!AgentCtor) return undefined;
+  try {
+    return new AgentCtor({ connect: { lookup: createPinnedLookup(pinnedIPv4) } });
+  } catch {
+    return undefined;
+  }
+}
+
+/** SSRF guard injected into the SDK's secureFetch for untrusted URLs (x402 targets,
+ *  registry-discovered endpoints): validates the URL (HTTPS, non-private/reserved IP,
+ *  DNS-resolvable) and returns a connection dispatcher pinned to the validated IPs.
+ *  Throws (AzethError) to BLOCK the request. (F9) */
+const secureGuard: SecureFetchGuard = async (urlStr: string) => {
+  const validated = await validateExternalUrl(urlStr);
+  return { dispatcher: await buildPinnedDispatcher(validated.pinnedIPv4) };
+};
+
 /**
  * Apply smart account selection from the `smartAccount` tool parameter.
  * Accepts "#N" (1-based index from azeth_accounts) or a full address.
@@ -278,6 +339,8 @@ export function registerPaymentTools(server: McpServer): void {
           method: args.method,
           body: args.body,
           maxAmount,
+          // Validate + pin every connection hop and refuse credential-carrying redirects. (F9)
+          secureGuard,
         });
 
         // F-5/H-1: Stream response body with size limit. Uses Uint8Array chunks
@@ -430,6 +493,10 @@ export function registerPaymentTools(server: McpServer): void {
           maxAmount,
           minReputation: args.minReputation,
           autoFeedback: args.autoFeedback ?? false,
+          // SSRF guard for discovered (third-party-published) endpoints — validates + pins
+          // every connection hop, the same protection azeth_pay applies to user URLs.
+          // Throwing makes smartFetch402 skip that service and try the next one. (F9)
+          secureGuard,
         });
 
         // Stream response body with size limit (same pattern as azeth_pay)
@@ -721,10 +788,13 @@ export function registerPaymentTools(server: McpServer): void {
       try {
         client = await createClient(args.chain);
 
-        // Fetch the URL to get 402 response with agreement terms
-        const response = await fetch(validated.url, {
+        // Fetch the URL to get the 402 response with agreement terms. Untrusted URL →
+        // validate + pin the connection and refuse redirects (no credential leakage). (F9)
+        const response = await secureFetch(validated.url, {
           method: 'GET',
           signal: AbortSignal.timeout(15_000),
+          guard: secureGuard,
+          guardedRedirect: 'error',
         });
 
         if (response.status !== 402) {

src/tools/registry.ts

@@ -97,7 +97,21 @@ async function overlayMetadataUpdates(
       if (raw && raw !== '0x') {
         const decoded = hexToString(raw);
         if (decoded) {
-          entry[key] = decoded;
+          if (key === 'capabilities') {
+            // capabilities is a list-valued field; setMetadata stores it on-chain as a
+            // JSON-array STRING. Parse it back to an array so the single-entry get-path
+            // matches the list endpoint and the documented RegistryEntry.capabilities:
+            // string[] type. On malformed input, keep the existing (server-provided)
+            // array rather than overwrite it with a raw string. (F1: type inconsistency.)
+            try {
+              const parsed: unknown = JSON.parse(decoded);
+              if (Array.isArray(parsed)) {
+                entry[key] = parsed.filter((c): c is string => typeof c === 'string');
+              }
+            } catch { /* leave existing capabilities array intact */ }
+          } else {
+            entry[key] = decoded;
+          }
         }
       }
     } catch { /* no metadata for this key */ }

src/utils/response.ts

@@ -286,10 +286,16 @@ export function guardianRequiredError(
     }
   }
 
-  return {
-    content: [{ type: 'text', text: lines.join('\n') }],
-    isError: true,
-  };
+  // Return through the structured error envelope (matching every other tool error)
+  // so agents can branch on error.code. The multi-line remediation guidance is
+  // preserved verbatim in error.suggestion. (F7: previously returned as plain text.)
+  const [headline, ...rest] = lines;
+  const guidance = rest.join('\n').trim();
+  return error(
+    'GUARDIAN_COSIGN_REQUIRED',
+    headline ?? `Guardian co-signature required: ${reason}`,
+    guidance.length > 0 ? guidance : undefined,
+  );
 }
 
 /** JSON replacer that converts bigint values to strings */

test/tools/payments.test.ts

@@ -189,11 +189,13 @@ describe('payment tools', () => {
 
       expect(mockClient.fetch402).toHaveBeenCalledWith(
         'https://api.example.com/submit',
-        {
+        expect.objectContaining({
           method: 'POST',
           body: '{"key": "value"}',
           maxAmount: undefined,
-        },
+          // F9: azeth_pay injects an SSRF guard (validate + connection pin + redirect policy)
+          secureGuard: expect.any(Function),
+        }),
       );
     });
 

test/tools/secure-guard.test.ts

@@ -0,0 +1,29 @@
+import { describe, it, expect } from 'vitest';
+import { createPinnedLookup } from '../../src/tools/payments.js';
+
+/** Proves the DNS-rebinding pin: the lookup returns ONLY the pre-validated public IP(s),
+ *  regardless of the hostname an attacker-controlled DNS record might (re)resolve to. */
+describe('createPinnedLookup (F9 DNS-rebinding pin)', () => {
+  it('resolves to the validated pinned IP, ignoring the hostname (single-address form)', () => {
+    const lookup = createPinnedLookup(['203.0.113.7']);
+    let captured: { err: unknown; address: unknown; family: unknown } | undefined;
+    lookup('attacker-rebound.example', undefined, (err, address, family) => {
+      captured = { err, address, family };
+    });
+    // Even though the host "could" rebind to 169.254.x at connect time, the socket is
+    // forced to the pre-validated public IP.
+    expect(captured).toEqual({ err: null, address: '203.0.113.7', family: 4 });
+  });
+
+  it('returns all pinned IPs in the { all } form, never an attacker-resolved address', () => {
+    const lookup = createPinnedLookup(['203.0.113.7', '198.51.100.9']);
+    let addresses: unknown;
+    lookup('attacker-rebound.example', { all: true }, (_err, addr) => {
+      addresses = addr;
+    });
+    expect(addresses).toEqual([
+      { address: '203.0.113.7', family: 4 },
+      { address: '198.51.100.9', family: 4 },
+    ]);
+  });
+});