@tangle-network/agent-gateway 0.7.0 → 0.7.1

package/README.md

@@ -1,6 +1,7 @@
 # @tangle-network/agent-gateway
 
-Hono middleware that turns any Tangle agent app into a paid API. Wrap your chat endpoint to accept API keys, x402 SpendAuth, or MPP credentials — with scope enforcement, per-key rate limits, nonce replay protection, prompt-injection detection, and publish routes for the marketplace.
+Hono middleware that turns any Tangle agent app into a paid API.
+It exposes one shared request pipeline for API keys, x402 SpendAuth, and MPP credentials, with scope enforcement, per-key rate limits, nonce replay protection, prompt-injection detection, and publish routes for the marketplace.
 
 ## Install
 
@@ -11,17 +12,37 @@ npm install @tangle-network/agent-gateway
 ## Usage
 
 ```ts
-import { createAgentGateway } from '@tangle-network/agent-gateway'
+import {
+  createAgentGateway,
+  verifyApiKeyFromStore,
+} from '@tangle-network/agent-gateway'
 import { Hono } from 'hono'
 
 const app = new Hono()
-app.use('/chat/*', createAgentGateway({
-  apiKeyStore: myKeyStore,
-  x402: { verifierUrl: 'https://router.tangle.tools/x402/verify' },
-  rateLimits: { perKey: { rpm: 60 } },
+app.route('/v1/agents', createAgentGateway({
+  resolveAgent: loadPublishedAgent,
+  getSandbox: openAgentSandbox,
+  recordUsage: recordUsageEvent,
+  x402: {
+    operatorAddress: '0x…',
+    chainId: 3799,
+    verifySigner: verifySpendAuthSignature,
+  },
+  verifyApiKey: (authHeader) => verifyApiKeyFromStore(authHeader, apiKeyStore),
 }))
 ```
 
+`x402.verifySigner` is required for production.
+Set `x402.demoMode: true` only for local development and tests; that explicit mode also enables the built-in `sk_agent_*` demo key verifier.
+
+MPP is method-specific.
+Configure `mpp.verifySigner` for production MPP credentials; it receives the decoded JSON payload when available plus the original decoded credential, and returns the authenticated consumer ID or `null`.
+The default `blueprintevm` method may reuse `x402.verifySigner` when its credential has the compatible x402 payload shape.
+Other methods are not accepted until they have their own verifier.
+
+The same authentication, authorization, rate-limit, filtering, sandbox, settlement, and usage-recording pipeline is used by the OpenAI-compatible and A2A endpoints.
+Wire protocol handlers only translate their request and response shapes.
+
 ## A2A protocol
 
 The gateway speaks Google's A2A protocol alongside its OpenAI-compatible surface: discovery via `.well-known/agent.json`, JSON-RPC 2.0 dispatch for `message/send`, `message/stream`, `tasks/get`, `tasks/cancel`, `tasks/resubscribe`, and the four `tasks/pushNotificationConfig/*` methods. Long-horizon agents — durable tasks across worker restarts, webhook delivery on terminal state, `input-required` pauses with multi-turn continuation — are documented in [`docs/a2a-long-horizon.md`](./docs/a2a-long-horizon.md).

package/dist/{chunk-3IKQWFKX.js → chunk-Q4YAIEZY.js}

@@ -260,6 +260,15 @@ function generateRequestId() {
 }
 
 // src/verify.ts
+function isApiKeyAuthEnabled(config) {
+  return config.verifyApiKey !== void 0 || config.x402.demoMode === true;
+}
+function isMppAuthEnabled(config) {
+  const method = config.mpp?.method ?? "blueprintevm";
+  return Boolean(
+    config.mpp && (config.mpp.verifySigner !== void 0 || method === "blueprintevm" && config.x402.verifySigner !== void 0 || config.x402.demoMode === true)
+  );
+}
 async function verifyX402(spendAuthHeader, config, nonceStore) {
   try {
     const raw = JSON.parse(spendAuthHeader);
@@ -271,36 +280,72 @@ async function verifyX402(spendAuthHeader, config, nonceStore) {
     if (expiry < BigInt(Math.floor(Date.now() / 1e3))) return null;
     if (amount <= 0n) return null;
     const nonceKey = `${raw.commitment}:${nonce.toString()}`;
-    if (nonceStore) {
-      if (await nonceStore.hasSeen(nonceKey)) return null;
-      const ttl = Math.min(Number(expiry) - Math.floor(Date.now() / 1e3), 3600);
-      await nonceStore.markSeen(nonceKey, Math.max(ttl, 60));
-    }
+    if (nonceStore && await nonceStore.hasSeen(nonceKey)) return null;
     if (config.verifySigner) {
       const verified = await config.verifySigner(raw);
       if (!verified) return null;
     } else if (!config.demoMode) {
       return null;
     }
+    if (nonceStore) {
+      const ttl = Math.min(Number(expiry) - Math.floor(Date.now() / 1e3), 3600);
+      await nonceStore.markSeen(nonceKey, Math.max(ttl, 60));
+    }
     return raw.commitment;
   } catch {
     return null;
   }
 }
-async function verifyMpp(authHeader, _config, x402Config) {
+async function verifyMpp(authHeader, config, x402Config, nonceStore) {
   const match = authHeader.match(/^Payment\s+(\S+)\s+(\S+)$/i);
   if (!match) return null;
-  const [, , credentialB64] = match;
+  const [, method, credentialB64] = match;
+  if (config.method && method !== config.method) return null;
   try {
+    if (!/^[A-Za-z0-9_-]+$/.test(credentialB64)) return null;
     const decoded = Buffer.from(credentialB64, "base64url").toString("utf-8");
-    const credential = JSON.parse(decoded);
-    const payload = credential.payload ?? credential;
-    if (!payload.commitment && !payload.from) return null;
+    let payload = {};
+    try {
+      const credential = JSON.parse(decoded);
+      if (credential && typeof credential === "object" && !Array.isArray(credential)) {
+        const nested = credential.payload;
+        payload = nested && typeof nested === "object" && !Array.isArray(nested) ? nested : credential;
+      }
+    } catch {
+    }
+    const nonceKey = nonceStore && payload.nonce !== void 0 ? `mpp:${method}:${String(payload.commitment ?? payload.from ?? "unknown")}:${String(payload.nonce)}` : null;
+    if (nonceKey && await nonceStore.hasSeen(nonceKey)) return null;
+    let consumerId = null;
+    if (config.verifySigner) {
+      consumerId = await config.verifySigner(payload, { method, credential: decoded });
+    } else if (method === "blueprintevm" && x402Config.verifySigner && payload.commitment) {
+      const verified = await x402Config.verifySigner(payload);
+      consumerId = verified ? String(payload.commitment) : null;
+    } else if (x402Config.demoMode) {
+      const identity = payload.commitment ?? payload.from;
+      if (typeof identity !== "string" || identity.length === 0) return null;
+      consumerId = identity;
+    } else {
+      return null;
+    }
+    if (!consumerId) return null;
     const operator = payload.operator ?? payload.to;
-    if (operator && operator.toLowerCase() !== x402Config.operatorAddress.toLowerCase()) return null;
-    if (payload.amount) BigInt(payload.amount);
-    if (payload.nonce) BigInt(payload.nonce);
-    return payload.commitment ?? payload.from ?? null;
+    if (operator !== void 0) {
+      if (typeof operator !== "string" || operator.toLowerCase() !== x402Config.operatorAddress.toLowerCase()) {
+        return null;
+      }
+    }
+    if (payload.amount !== void 0 && BigInt(String(payload.amount)) <= 0n) return null;
+    if (payload.nonce !== void 0) BigInt(String(payload.nonce));
+    if (payload.expiry !== void 0 && BigInt(String(payload.expiry)) < BigInt(Math.floor(Date.now() / 1e3))) {
+      return null;
+    }
+    if (nonceStore && payload.nonce !== void 0) {
+      const expiry = payload.expiry === void 0 ? Math.floor(Date.now() / 1e3) + 3600 : Number(payload.expiry);
+      const ttl = Math.min(expiry - Math.floor(Date.now() / 1e3), 3600);
+      await nonceStore.markSeen(nonceKey, Math.max(ttl, 60));
+    }
+    return consumerId;
   } catch {
     return null;
   }
@@ -321,7 +366,7 @@ async function authenticateAndGuard(c, slug, messages, config, state) {
   const ctx = { requestId, agentSlug: slug, startMs };
   await state.obs?.onRequestStart?.(ctx);
   const agent = await config.resolveAgent(slug);
-  if (!agent) {
+  if (!agent || !agent.enabled) {
     return c.json({ error: { message: "Agent not found", type: "not_found" } }, 404);
   }
   if (!messages?.length) {
@@ -359,8 +404,8 @@ async function authenticateAndGuard(c, slug, messages, config, state) {
     }
     consumerId = signer;
     paymentMethod = "x402";
-  } else if (config.mpp && authHeader.toLowerCase().startsWith("payment ")) {
-    const signer = await verifyMpp(authHeader, config.mpp, config.x402);
+  } else if (isMppAuthEnabled(config) && authHeader.toLowerCase().startsWith("payment ")) {
+    const signer = await verifyMpp(authHeader, config.mpp, config.x402, state.nonceStore);
     if (!signer) {
       const realm = config.mpp.realm;
       const method = config.mpp.method ?? "blueprintevm";
@@ -389,7 +434,18 @@ async function authenticateAndGuard(c, slug, messages, config, state) {
     consumerId = signer;
     paymentMethod = "mpp";
   } else if (authHeader.startsWith("Bearer ")) {
-    const verify = config.verifyApiKey ?? defaultVerifyApiKey;
+    const verify = config.verifyApiKey ?? (config.x402.demoMode ? defaultVerifyApiKey : null);
+    if (!verify || !isApiKeyAuthEnabled(config)) {
+      await state.obs?.onAuthFailure?.(ctx, {
+        method: "apikey",
+        code: "api_keys_not_configured",
+        httpStatus: 401
+      });
+      return c.json(
+        { error: { message: "API key authentication is not configured", type: "authentication_error" } },
+        { status: 401, headers: { "X-Request-Id": requestId } }
+      );
+    }
     const key = await verify(authHeader);
     if (!key) {
       await state.obs?.onAuthFailure?.(ctx, {
@@ -429,13 +485,13 @@ async function authenticateAndGuard(c, slug, messages, config, state) {
       httpStatus: 402
     });
     const methods = ["x402"];
-    if (config.mpp) methods.push("mpp");
-    methods.push("api_key");
+    if (isMppAuthEnabled(config)) methods.push("mpp");
+    if (isApiKeyAuthEnabled(config)) methods.push("api_key");
     const headers = {
       "X-Payment-Required": methods.join(", "),
       "X-Request-Id": requestId
     };
-    if (config.mpp) {
+    if (isMppAuthEnabled(config) && config.mpp) {
       headers["WWW-Authenticate"] = `Payment realm="${config.mpp.realm}", method="${config.mpp.method ?? "blueprintevm"}"`;
     }
     return c.json(
@@ -450,10 +506,12 @@ async function authenticateAndGuard(c, slug, messages, config, state) {
             credits_address: config.x402.creditsAddress,
             estimated_amount_per_request: "20000"
           },
-          ...config.mpp ? { mpp: { realm: config.mpp.realm, method: config.mpp.method ?? "blueprintevm" } } : {},
-          api_key: {
-            purchase_url: config.baseUrl ? `${config.baseUrl}/agents/${slug}/api-keys` : void 0
-          }
+          ...isMppAuthEnabled(config) && config.mpp ? { mpp: { realm: config.mpp.realm, method: config.mpp.method ?? "blueprintevm" } } : {},
+          ...isApiKeyAuthEnabled(config) ? {
+            api_key: {
+              purchase_url: config.baseUrl ? `${config.baseUrl}/agents/${slug}/api-keys` : void 0
+            }
+          } : {}
         }
       },
       { status: 402, headers }
@@ -631,8 +689,8 @@ function estimateTokens(text) {
 // src/a2a/agent-card.ts
 function buildAgentCard(agent, config, agentUrl) {
   const schemes = ["x402"];
-  if (config.mpp) schemes.push("mpp");
-  schemes.push("Bearer");
+  if (isMppAuthEnabled(config)) schemes.push("mpp");
+  if (isApiKeyAuthEnabled(config)) schemes.push("Bearer");
   const skills = agent.skills && agent.skills.length > 0 ? agent.skills : [
     {
       id: "chat",
@@ -940,7 +998,7 @@ function createA2AHandlers(deps) {
     const slug = c.req.param("slug");
     if (!slug) return c.json({ error: "slug required" }, 400);
     const agent = await deps.config.resolveAgent(slug);
-    if (!agent) {
+    if (!agent || !agent.enabled) {
       return c.json({ error: "Agent not found or not published" }, 404);
     }
     const url = new URL(c.req.url);
@@ -1535,7 +1593,7 @@ function createAgentGateway(config) {
   gw.get("/:slug/chat/completions", async (c) => {
     const slug = c.req.param("slug");
     const agent = await config.resolveAgent(slug);
-    if (!agent) return c.json({ error: "Agent not found or not published" }, 404);
+    if (!agent || !agent.enabled) return c.json({ error: "Agent not found or not published" }, 404);
     const paymentMethods = [
       {
         type: "x402",
@@ -1544,14 +1602,14 @@ function createAgentGateway(config) {
         credits_contract: config.x402.creditsAddress
       }
     ];
-    if (config.mpp) {
+    if (isMppAuthEnabled(config)) {
       paymentMethods.push({
         type: "mpp",
         realm: config.mpp.realm,
         method: config.mpp.method ?? "blueprintevm"
       });
     }
-    paymentMethods.push({ type: "api_key", prefix: "sk_agent_" });
+    if (isApiKeyAuthEnabled(config)) paymentMethods.push({ type: "api_key", prefix: "sk_agent_" });
     return c.json({
       slug: agent.slug,
       pricing: {
@@ -1690,6 +1748,8 @@ export {
   ConsoleObserver,
   CompositeObserver,
   generateRequestId,
+  isApiKeyAuthEnabled,
+  isMppAuthEnabled,
   verifyX402,
   verifyMpp,
   defaultVerifyApiKey,
@@ -1700,4 +1760,4 @@ export {
   InMemoryTaskStore,
   createAgentGateway
 };
-//# sourceMappingURL=chunk-3IKQWFKX.js.map
+//# sourceMappingURL=chunk-Q4YAIEZY.js.map