@tangle-network/agent-gateway 0.6.0 → 0.7.1

package/src/types.ts

@@ -55,6 +55,18 @@ export interface AgentMeta {
    * Only meaningful when `harness` is set; ignored otherwise.
    */
   harnessModel?: string
+  /**
+   * Optional human description surfaced in the A2A Agent Card. Defaults to
+   * `"{slug} agent"` when absent.
+   */
+  description?: string
+  /**
+   * Optional A2A skill descriptors. Each entry advertises what the agent
+   * can do so non-Tangle A2A clients can select agents by capability. When
+   * absent, the gateway synthesizes a single default `chat` skill from
+   * `slug` + `description`.
+   */
+  skills?: import('./a2a/types').AgentSkill[]
 }
 
 // --- Payment ---
@@ -81,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 {
@@ -141,6 +165,15 @@ export interface SandboxStreamEvent {
     part?: { type?: string; text?: string }
     delta?: string
     finalText?: string
+    /**
+     * Optional sandbox-side signal that the agent has paused and is waiting
+     * for additional input from the caller. The A2A gateway translates this
+     * into an `input-required` task status; the caller can then submit a
+     * follow-up `message/send` with the same `taskId` to continue. Ignored
+     * by the OpenAI-compat path. Carry an optional `prompt` to surface to
+     * the caller (rendered as the input-required message body).
+     */
+    inputRequired?: { prompt?: string }
   }
 }
 
@@ -173,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>
 
@@ -218,6 +252,46 @@ export interface GatewayConfig {
    * ConsoleObserver / CompositeObserver implementations.
    */
   observer?: import('./observer').GatewayObserver
+
+  /**
+   * A2A protocol configuration. When set, the gateway exposes the A2A
+   * surface alongside its OpenAI-compatible endpoints:
+   *   GET  /:slug/.well-known/agent.json   — AgentCard discovery
+   *   POST /:slug                          — JSON-RPC 2.0 endpoint
+   *     methods: message/send, message/stream, tasks/get, tasks/cancel
+   * Auth + rate-limit + injection-filter + authorization all share the
+   * same pipeline as the OpenAI-compat path. `taskStore` defaults to
+   * `InMemoryTaskStore`; swap in D1/postgres/DO for durable deployments.
+   */
+  a2a?: {
+    /**
+     * Where tasks live. Defaults to `InMemoryTaskStore`; swap in
+     * `SqlTaskStore` (D1, postgres, sqlite, libSQL) for durability across
+     * gateway restarts.
+     */
+    taskStore?: import('./a2a/task-store').TaskStore
+    /**
+     * Where push notification configs live. When set, the gateway advertises
+     * `capabilities.pushNotifications: true` and exposes the four
+     * `tasks/pushNotificationConfig/*` JSON-RPC methods. Defaults to
+     * undefined (push support disabled), so the agent card honestly reflects
+     * what the gateway will actually do.
+     */
+    pushStore?: import('./a2a/push-notifications').PushNotificationStore
+    /**
+     * Shared HMAC secret used to sign webhook deliveries (`X-A2A-Signature:
+     * sha256=<hex>`). The consumer's webhook verifies the body against this
+     * secret to confirm the call originated from this gateway. Required when
+     * `pushStore` is set; without it, deliveries fire unsigned and a
+     * malicious party that knows the webhook URL can forge deliveries.
+     */
+    webhookSecret?: string
+    /**
+     * Optional fetcher override for webhook delivery. Defaults to global
+     * `fetch`. Override for tests or to wire a queue-backed sender.
+     */
+    pushFetcher?: typeof fetch
+  }
 }
 
 // --- Chat completion types (OpenAI-compatible) ---

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
   }