@tangle-network/agent-gateway 0.7.0 → 0.7.1

package/src/dispatch.ts

@@ -21,7 +21,13 @@ import type {
   GatewayConfig,
   PaymentMethod,
 } from './types'
-import { defaultVerifyApiKey, verifyMpp, verifyX402 } from './verify'
+import {
+  defaultVerifyApiKey,
+  isApiKeyAuthEnabled,
+  isMppAuthEnabled,
+  verifyMpp,
+  verifyX402,
+} from './verify'
 
 /** Single bundle of long-lived gateway state shared across all handlers in one createAgentGateway call. */
 export interface GatewayState {
@@ -68,7 +74,7 @@ export async function authenticateAndGuard(
   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) {
@@ -109,11 +115,11 @@ export async function authenticateAndGuard(
     }
     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'
+      const realm = config.mpp!.realm
+      const method = config.mpp!.method ?? 'blueprintevm'
       await state.obs?.onAuthFailure?.(ctx, {
         method: 'mpp',
         code: 'invalid_mpp_credential',
@@ -139,7 +145,18 @@ export async function authenticateAndGuard(
     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, {
@@ -179,13 +196,13 @@ export async function authenticateAndGuard(
       httpStatus: 402,
     })
     const methods: string[] = ['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: Record<string, string> = {
       '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'}"`
     }
@@ -201,14 +218,18 @@ export async function authenticateAndGuard(
             credits_address: config.x402.creditsAddress,
             estimated_amount_per_request: '20000',
           },
-          ...(config.mpp
+          ...(isMppAuthEnabled(config) && config.mpp
             ? { mpp: { realm: config.mpp.realm, method: config.mpp.method ?? 'blueprintevm' } }
             : {}),
-          api_key: {
-            purchase_url: config.baseUrl
-              ? `${config.baseUrl}/agents/${slug}/api-keys`
-              : undefined,
-          },
+          ...(isApiKeyAuthEnabled(config)
+            ? {
+                api_key: {
+                  purchase_url: config.baseUrl
+                    ? `${config.baseUrl}/agents/${slug}/api-keys`
+                    : undefined,
+                },
+              }
+            : {}),
         },
       },
       { status: 402, headers },

package/src/index.ts

@@ -1,5 +1,11 @@
 export { createAgentGateway } from './middleware'
-export { verifyX402, verifyMpp, defaultVerifyApiKey } from './verify'
+export {
+  verifyX402,
+  verifyMpp,
+  defaultVerifyApiKey,
+  isApiKeyAuthEnabled,
+  isMppAuthEnabled,
+} from './verify'
 export {
   filterConsumerMessages,
   filterConsumerMessagesStrict,

package/src/middleware.ts

@@ -14,6 +14,7 @@ import { MemoryNonceStore } from './nonce-store'
 import { type GatewayObserver, type RequestContext, generateRequestId } from './observer'
 import { MemoryRateLimitStore, type RateLimitStore } from './rate-limit'
 import type { ChatCompletionChunk, ChatCompletionRequest, GatewayConfig } from './types'
+import { isApiKeyAuthEnabled, isMppAuthEnabled } from './verify'
 
 /**
  * Create a Hono router that serves the agent gateway.
@@ -51,7 +52,7 @@ export function createAgentGateway(config: GatewayConfig) {
   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: Array<Record<string, unknown>> = [
       {
@@ -61,14 +62,14 @@ export function createAgentGateway(config: GatewayConfig) {
         credits_contract: config.x402.creditsAddress,
       },
     ]
-    if (config.mpp) {
+    if (isMppAuthEnabled(config)) {
       paymentMethods.push({
         type: 'mpp',
-        realm: config.mpp.realm,
-        method: config.mpp.method ?? 'blueprintevm',
+        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,
@@ -231,4 +232,3 @@ function streamChatCompletions(
     },
   })
 }
-

package/src/types.ts

@@ -93,6 +93,18 @@ export interface MppConfig {
   realm: string
   /** MPP method name (default: "blueprintevm") */
   method?: string
+  /**
+   * Production verifier for the method-specific credential. Return the
+   * authenticated consumer id, or null when the credential is invalid.
+   * The callback receives the decoded JSON payload when one exists plus the
+   * original decoded credential so non-JSON methods can verify their own form.
+   * Omit only when x402.demoMode is explicitly enabled for local testing, or
+   * when x402.verifySigner handles an x402-compatible MPP credential.
+   */
+  verifySigner?: (
+    payload: Record<string, unknown>,
+    context: { method: string; credential: string },
+  ) => Promise<string | null>
 }
 
 export interface PaymentResult {
@@ -194,12 +206,13 @@ export interface GatewayConfig {
   /** x402 payment configuration */
   x402: X402Config
 
-  /** MPP (Machine Payments Protocol) configuration. If provided, gateway accepts Authorization: Payment headers. */
+  /** MPP (Machine Payments Protocol) configuration. It is advertised only when a production verifier or explicit demo mode is available. */
   mpp?: MppConfig
 
   /**
    * Verify an API key. Return key info if valid, null if invalid.
-   * Default: accepts any `sk_agent_*` key (demo mode).
+   * In explicit x402 demo mode, the built-in verifier accepts `sk_agent_*` keys.
+   * Production gateways must provide this callback.
    */
   verifyApiKey?: (authHeader: string) => Promise<ApiKeyInfo | null>
 

package/src/verify.ts

@@ -1,6 +1,26 @@
-import type { X402Config, MppConfig, ApiKeyInfo } from './types'
+import type { X402Config, MppConfig, ApiKeyInfo, GatewayConfig } from './types'
 import type { NonceStore } from './nonce-store'
 
+/** Pure capability checks shared by discovery and every request protocol. */
+export function isApiKeyAuthEnabled(
+  config: Pick<GatewayConfig, 'verifyApiKey' | 'x402'>,
+): boolean {
+  return config.verifyApiKey !== undefined || config.x402.demoMode === true
+}
+
+/** MPP is enabled only when a real verifier or explicit demo mode exists. */
+export function isMppAuthEnabled(
+  config: Pick<GatewayConfig, 'mpp' | 'x402'>,
+): boolean {
+  const method = config.mpp?.method ?? 'blueprintevm'
+  return Boolean(
+    config.mpp &&
+      (config.mpp.verifySigner !== undefined ||
+        (method === 'blueprintevm' && config.x402.verifySigner !== undefined) ||
+        config.x402.demoMode === true),
+  )
+}
+
 /**
  * Verify x402 SpendAuth signature (EIP-712).
  * Returns the signer address (commitment) if valid, null otherwise.
@@ -32,14 +52,8 @@ export async function verifyX402(
     // Reject zero-amount payments
     if (amount <= 0n) return null
 
-    // Reject replayed nonces
     const nonceKey = `${raw.commitment}:${nonce.toString()}`
-    if (nonceStore) {
-      if (await nonceStore.hasSeen(nonceKey)) return null
-      // Mark seen with TTL matching the expiry window (max 1 hour)
-      const ttl = Math.min(Number(expiry) - Math.floor(Date.now() / 1000), 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)
@@ -48,6 +62,14 @@ export async function verifyX402(
       return null
     }
 
+    // Check and mark only after the signature is accepted. Otherwise an
+    // invalid request can burn a valid payer nonce and deny the real request.
+    if (nonceStore) {
+      // Mark seen with TTL matching the expiry window (max 1 hour)
+      const ttl = Math.min(Number(expiry) - Math.floor(Date.now() / 1000), 3600)
+      await nonceStore.markSeen(nonceKey, Math.max(ttl, 60))
+    }
+
     return raw.commitment
   } catch {
     return null
@@ -57,43 +79,88 @@ export async function verifyX402(
 /**
  * Verify MPP (Machine Payments Protocol) Authorization: Payment header.
  *
- * MPP uses `Authorization: Payment <method> <credential>` format where
- * the credential is a base64url-encoded JSON wrapping the same EIP-3009
- * payment payload that x402 uses. This means existing x402 wallets work
- * unchanged over the MPP wire format.
+ * MPP uses `Authorization: Payment <method> <credential>` format. The
+ * credential is method-specific; `MppConfig.verifySigner` owns verification
+ * and returns the consumer identity. The built-in `blueprintevm` path can
+ * reuse the x402 verifier for credentials with the compatible payload shape.
  *
  * Returns the signer address if valid, null otherwise.
- * In demo mode, accepts any well-formed Payment header.
+ * In demo mode, accepts any well-formed Payment header with an identity.
  */
 export async function verifyMpp(
   authHeader: string,
-  _config: MppConfig,
+  config: MppConfig,
   x402Config: X402Config,
+  nonceStore?: NonceStore,
 ): Promise<string | null> {
   // MPP format: "Payment <method> <base64url-credential>"
   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 {
-    // Decode base64url credential → JSON with the same EIP-3009 payload
+    if (!/^[A-Za-z0-9_-]+$/.test(credentialB64)) return null
     const decoded = Buffer.from(credentialB64, 'base64url').toString('utf-8')
-    const credential = JSON.parse(decoded)
+    let payload: Record<string, unknown> = {}
+    try {
+      const credential = JSON.parse(decoded) as unknown
+      if (credential && typeof credential === 'object' && !Array.isArray(credential)) {
+        const nested = (credential as Record<string, unknown>).payload
+        payload =
+          nested && typeof nested === 'object' && !Array.isArray(nested)
+            ? (nested as Record<string, unknown>)
+            : (credential as Record<string, unknown>)
+      }
+    } catch {
+      // Method-specific verifiers may accept a non-JSON credential format.
+    }
+
+    const nonceKey =
+      nonceStore && payload.nonce !== undefined
+        ? `mpp:${method}:${String(payload.commitment ?? payload.from ?? 'unknown')}:${String(payload.nonce)}`
+        : null
+    if (nonceKey && await nonceStore!.hasSeen(nonceKey)) return null
 
-    // The credential payload wraps the same fields x402 uses
-    const payload = credential.payload ?? credential
-    if (!payload.commitment && !payload.from) return null
+    let consumerId: string | null = 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
 
-    // Validate operator match (same as x402)
+    // Validate common EVM fields when present. Method-specific verifiers own
+    // the complete credential contract for non-EVM methods.
     const operator = payload.operator ?? payload.to
-    if (operator && operator.toLowerCase() !== x402Config.operatorAddress.toLowerCase()) return null
+    if (operator !== undefined) {
+      if (typeof operator !== 'string' || operator.toLowerCase() !== x402Config.operatorAddress.toLowerCase()) {
+        return null
+      }
+    }
+    if (payload.amount !== undefined && BigInt(String(payload.amount)) <= 0n) return null
+    if (payload.nonce !== undefined) BigInt(String(payload.nonce))
+    if (payload.expiry !== undefined && BigInt(String(payload.expiry)) < BigInt(Math.floor(Date.now() / 1000))) {
+      return null
+    }
 
-    // Validate bigint fields if present
-    if (payload.amount) BigInt(payload.amount)
-    if (payload.nonce) BigInt(payload.nonce)
+    if (nonceStore && payload.nonce !== undefined) {
+      const expiry = payload.expiry === undefined
+        ? Math.floor(Date.now() / 1000) + 3600
+        : Number(payload.expiry)
+      const ttl = Math.min(expiry - Math.floor(Date.now() / 1000), 3600)
+      await nonceStore.markSeen(nonceKey!, Math.max(ttl, 60))
+    }
 
-    return payload.commitment ?? payload.from ?? null
+    return consumerId
   } catch {
     return null
   }