@agentxv2/gateway 0.1.1

package/src/lib/ethers-utils.ts

@@ -0,0 +1,229 @@
+// ---------------------------------------------------------------------------
+// Gateway — ethers.js v6 Utilities
+// ---------------------------------------------------------------------------
+// Workarounds for known ethers.js v6 bugs when interacting with Solidity
+// contracts that use complex tuple types (structs with mixed static/dynamic
+// fields, nested tuple arrays, etc.).
+//
+// Issues tracked:
+//   P4 — ethers.js v6 cannot encode `(string,bytes)[]` tuple arrays
+//         via Interface.encodeFunctionData when values contain Uint8Array
+//         or hex-encoded strings.
+//         Workaround: manual AbiCoder.encode()
+//   P6 — estimateGas reverts on Geth for functions returning complex structs
+//         (getPlan, completeTask). Workaround: skip estimateGas, use fixed
+//         gasLimit.
+// ---------------------------------------------------------------------------
+
+import { ethers } from 'ethers'
+
+const coder = ethers.AbiCoder.defaultAbiCoder()
+
+/**
+ * Encode registerWithMetadata(string, (string,bytes)[]) call data.
+ *
+ * ethers.js v6 Interface.encodeFunctionData fails on the inner tuple array
+ * when values are Uint8Array or hex strings (misidentified as string type).
+ * This bypasses Interface entirely and uses raw AbiCoder.
+ *
+ * Usage:
+ *   const data = encodeRegisterWithMetadata(tokenURI, [
+ *     ['name', 'SecurityAuditor'],
+ *     ['description', 'AI auditor'],
+ *   ])
+ *   await wallet.sendTransaction({ to: identityRegistry, data, value: fee })
+ */
+export function encodeRegisterWithMetadata(
+  tokenURI: string,
+  meta: [string, string][]
+): string {
+  // keccak256("registerWithMetadata(string,(string,bytes)[])") = 0x5ac4d1c3
+  const encoded = coder.encode(
+    ['string', 'tuple(string,bytes)[]'],
+    [
+      tokenURI,
+      meta.map(([k, v]) => [k, '0x' + Buffer.from(v).toString('hex')]),
+    ]
+  )
+  return '0x5ac4d1c3' + encoded.slice(2)
+}
+
+/**
+ * Encode hasActiveSubscription(address,uint256) call data.
+ *
+ * Works around ethers.js v6 address validation edge case where string
+ * addresses passed through JSON parsing may be rejected.
+ * Uses ethers.getAddress() for strict checksum validation.
+ */
+export function encodeHasActiveSubscription(
+  subscriber: string,
+  agentId: number
+): string {
+  // keccak256("hasActiveSubscription(address,uint256)") = 0x9b2f1234
+  const addr = ethers.getAddress(subscriber)
+  const encoded = coder.encode(['address', 'uint256'], [addr, agentId])
+  return '0x9b2f1234' + encoded.slice(2)
+}
+
+/**
+ * Safely call getPlan(uint256) and decode the SubscriptionPlan struct.
+ *
+ * Geth RPC on OxaChain L1 hangs indefinitely on struct-returning eth_call
+ * (known issue P1). This wrapper has a 5-second timeout to prevent the
+ * event loop from blocking.
+ *
+ * Returns null if the call fails, times out, or returns empty data.
+ */
+export async function safeGetPlan(
+  provider: ethers.Provider,
+  contractAddress: string,
+  planId: number,
+  timeoutMs = 5000
+): Promise<Record<string, unknown> | null> {
+  const selector = '0x26cd5274' // keccak256("getPlan(uint256)")
+  const encPid = coder.encode(['uint256'], [planId]).slice(2)
+  try {
+    const raw = await Promise.race([
+      provider.call({ to: contractAddress, data: selector + encPid }),
+      new Promise<string>((_, reject) =>
+        setTimeout(() => reject(new Error('getPlan timeout')), timeoutMs)
+      ),
+    ])
+    if (!raw || raw === '0x') return null
+    const decoded = coder.decode(
+      ['uint256', 'uint256', 'address', 'uint256', 'string', 'bool', 'address', 'uint256'],
+      raw
+    )
+    return {
+      planId: Number(decoded[0]),
+      agentId: Number(decoded[1]),
+      creator: decoded[2],
+      price: Number(decoded[3]),
+      period: decoded[4],
+      active: decoded[5],
+      payToken: decoded[6],
+      trialDays: Number(decoded[7]),
+    }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Encode giveFeedback(uint256,uint8,bytes32,bytes32,string,bytes32,bytes)
+ * 
+ * This uses named parameters in the ABI to ensure proper type matching.
+ * The bytes feedbackAuth parameter is the EIP-191 signed authorization.
+ */
+export function encodeGiveFeedback(
+  agentId: number,
+  score: number,
+  tag1: string,
+  tag2: string,
+  fileuri: string,
+  filehash: string,
+  feedbackAuth: string
+): string {
+  // keccak256("giveFeedback(uint256,uint8,bytes32,bytes32,string,bytes32,bytes)")
+  const encoded = coder.encode(
+    ['uint256', 'uint8', 'bytes32', 'bytes32', 'string', 'bytes32', 'bytes'],
+    [agentId, score, tag1, tag2, fileuri, filehash, feedbackAuth]
+  )
+  return '0x155e5bbd' + encoded.slice(2)
+}
+
+/**
+ * Safely call getSubscriptionDetail(uint256) via raw eth_call.
+ *
+ * ethers.js v6 fails to decode the 12-field struct (mixed static/dynamic types
+ * with string fields). This bypasses ethers.js entirely and uses raw eth_call
+ * + manual AbiCoder.decode, same pattern as safeGetPlan.
+ *
+ * Returns null on failure.
+ */
+export async function safeGetSubscriptionDetail(
+  provider: ethers.Provider,
+  contractAddress: string,
+  subscriptionId: number,
+  timeoutMs = 5000
+): Promise<Record<string, unknown> | null> {
+  // keccak256("getSubscriptionDetail(uint256)") = 0xae823f57
+  const selector = '0xae823f57'
+  const encId = coder.encode(['uint256'], [subscriptionId]).slice(2)
+  try {
+    const raw = await Promise.race([
+      provider.call({ to: contractAddress, data: selector + encId }),
+      new Promise<string>((_, reject) =>
+        setTimeout(() => reject(new Error('getSubscriptionDetail timeout')), timeoutMs)
+      ),
+    ])
+    if (!raw || raw === '0x') return null
+    // Struct: (uint256,address,uint256,uint8,uint256,uint256,string,address,uint256,bool,uint256,bool)
+    const decoded = coder.decode(
+      ['uint256', 'address', 'uint256', 'uint8', 'uint256', 'uint256', 'string', 'address', 'uint256', 'bool', 'uint256', 'bool'],
+      raw
+    )
+    return {
+      subscriptionId: Number(decoded[0]),
+      subscriber: decoded[1],
+      planId: Number(decoded[2]),
+      status: decoded[3],
+      startedAt: Number(decoded[4]),
+      expiresAt: Number(decoded[5]),
+      period: decoded[6],
+      payToken: decoded[7],
+      amountPaid: Number(decoded[8]),
+      trialActive: decoded[9],
+      trialEndsAt: Number(decoded[10]),
+      fundsReleased: decoded[11],
+    }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Safely call getTask(uint256) via raw eth_call.
+ *
+ * ethers.js v6 fails to decode the 9-field struct (3 string fields cause
+ * issues with the ABI decoder). This bypasses ethers.js entirely.
+ *
+ * Returns null on failure.
+ */
+export async function safeGetTask(
+  provider: ethers.Provider,
+  contractAddress: string,
+  taskId: number,
+  timeoutMs = 5000
+): Promise<Record<string, unknown> | null> {
+  // keccak256("getTask(uint256)") = 0x1d65e77e (verify with ethers.id)
+  const selector = '0x1d65e77e'
+  const encId = coder.encode(['uint256'], [taskId]).slice(2)
+  try {
+    const raw = await Promise.race([
+      provider.call({ to: contractAddress, data: selector + encId }),
+      new Promise<string>((_, reject) =>
+        setTimeout(() => reject(new Error('getTask timeout')), timeoutMs)
+      ),
+    ])
+    if (!raw || raw === '0x') return null
+    // Struct: (uint256,uint256,string,string,string,uint256,address,uint256,uint256)
+    const decoded = coder.decode(
+      ['uint256', 'uint256', 'string', 'string', 'string', 'uint256', 'address', 'uint256', 'uint256'],
+      raw
+    )
+    return {
+      taskId: Number(decoded[0]),
+      agentId: Number(decoded[1]),
+      taskType: decoded[2],
+      inputData: decoded[3],
+      outputData: decoded[4],
+      status: decoded[5],
+      clientAddress: decoded[6],
+      createdAt: Number(decoded[7]),
+      completedAt: Number(decoded[8]),
+    }
+  } catch {
+    return null
+  }
+}

package/src/middleware/adminAuth.ts

@@ -0,0 +1,34 @@
+// ---------------------------------------------------------------------------
+// AgentX Gateway — Admin Auth Middleware
+// ---------------------------------------------------------------------------
+// Simple shared-secret auth for admin routes.
+// Pass via Authorization: Bearer <ADMIN_KEY> or X-Admin-Key header.
+// ---------------------------------------------------------------------------
+
+import { Request, Response, NextFunction } from 'express'
+
+export function adminAuth(req: Request, res: Response, next: NextFunction): void {
+  const adminKey = process.env.ADMIN_KEY
+
+  if (!adminKey) {
+    res.status(500).json({ error: 'Admin key not configured on server' })
+    return
+  }
+
+  const authHeader = req.headers.authorization
+  const xAdminKey = req.headers['x-admin-key'] as string | undefined
+
+  let token: string | undefined
+  if (authHeader && authHeader.startsWith('Bearer ')) {
+    token = authHeader.slice(7)
+  } else if (xAdminKey) {
+    token = xAdminKey
+  }
+
+  if (!token || token !== adminKey) {
+    res.status(401).json({ error: 'Unauthorized: invalid admin key' })
+    return
+  }
+
+  next()
+}

package/src/middleware/auth.ts

@@ -0,0 +1,244 @@
+// ---------------------------------------------------------------------------
+// AgentX Gateway — Auth Middleware
+// ---------------------------------------------------------------------------
+// EIP-191 wallet signature auth + JWT + auto tenant creation.
+// ---------------------------------------------------------------------------
+
+import crypto from 'crypto'
+import { Request, Response, NextFunction } from 'express'
+import { ethers } from 'ethers'
+import jwt from 'jsonwebtoken'
+import { config } from '../config'
+import { getPool } from '../lib/db'
+import { getRedis } from './rate-limiter'
+
+export interface TenantContext {
+  id: string
+  walletAddress: string
+  planId: string
+  planSlug: string
+  quotaDaily: number
+  quotaUsed: number
+  rateLimitRpm: number
+  maxConcurrent: number
+  status: string
+}
+
+declare global {
+  namespace Express {
+    interface Request {
+      tenant?: TenantContext
+    }
+  }
+}
+
+interface Challenge {
+  address: string
+  timestamp: number
+  nonce: string
+}
+
+// Challenge TTL in seconds (matches the 5-minute window)
+const CHALLENGE_TTL_SEC = 5 * 60
+
+/**
+ * Store a challenge in Redis so it works across PM2 cluster workers.
+ * Falls back to an in-memory Map when Redis is unavailable (single-process dev).
+ */
+const fallbackMap = new Map<string, Challenge>()
+
+function challengeKey(address: string): string {
+  return `auth:challenge:${address}`
+}
+
+async function saveChallenge(address: string, challenge: Challenge): Promise<void> {
+  const r = getRedis()
+  if (r) {
+    await r.setex(challengeKey(address), CHALLENGE_TTL_SEC, JSON.stringify(challenge))
+  } else {
+    fallbackMap.set(address, challenge)
+  }
+}
+
+async function loadChallenge(address: string): Promise<Challenge | undefined> {
+  const r = getRedis()
+  if (r) {
+    const raw = await r.get(challengeKey(address))
+    if (raw) return JSON.parse(raw) as Challenge
+    return undefined
+  }
+  return fallbackMap.get(address)
+}
+
+async function deleteChallenge(address: string): Promise<void> {
+  const r = getRedis()
+  if (r) {
+    await r.del(challengeKey(address))
+  } else {
+    fallbackMap.delete(address)
+  }
+}
+
+export async function getChallenge(req: Request, res: Response): Promise<void> {
+  const address = (req.query.address as string || '').toLowerCase()
+  if (!address) {
+    res.status(400).json({ error: 'Missing wallet address' })
+    return
+  }
+
+  const timestamp = Math.floor(Date.now() / 1000)
+  const nonce = crypto.randomBytes(16).toString('hex')
+  const message = `agentx:auth:${timestamp}:${nonce}`
+
+  await saveChallenge(address, { address, timestamp, nonce })
+
+  res.json({ challenge: message, timestamp, nonce })
+}
+
+export async function verifyChallenge(req: Request, res: Response): Promise<void> {
+  const { wallet_address, signature, timestamp, nonce } = req.body
+
+  if (!wallet_address || !signature) {
+    res.status(400).json({ error: 'Missing wallet_address or signature' })
+    return
+  }
+
+  const address = wallet_address.toLowerCase()
+  const challenge = await loadChallenge(address)
+
+  if (!challenge || challenge.nonce !== nonce) {
+    res.status(401).json({ error: 'Challenge expired or not found. Please request a new challenge.' })
+    return
+  }
+
+  const expectedMessage = `agentx:auth:${timestamp}:${nonce}`
+  let recovered: string
+  try {
+    recovered = ethers.verifyMessage(expectedMessage, signature).toLowerCase()
+  } catch {
+    res.status(401).json({ error: 'Invalid signature' })
+    return
+  }
+
+  if (recovered !== address) {
+    res.status(401).json({ error: 'Signature does not match wallet address' })
+    return
+  }
+
+  await deleteChallenge(address)
+
+  const pool = getPool()
+  let tenant: TenantContext | null = null
+
+  const existing = await pool.query(
+    `SELECT t.id, t.wallet_address, t.status,
+            t.quota_daily, t.quota_used, t.rate_limit_rpm, t.max_concurrent,
+            p.id as plan_id, p.slug as plan_slug
+     FROM tenants t
+     LEFT JOIN plans p ON t.plan_id = p.id
+     WHERE LOWER(t.wallet_address) = $1`,
+    [address]
+  )
+
+  if (existing.rows.length > 0) {
+    const row = existing.rows[0]
+    if (row.status === 'suspended') {
+      res.status(403).json({ error: 'Account suspended' })
+      return
+    }
+    tenant = {
+      id: row.id,
+      walletAddress: row.wallet_address,
+      planId: row.plan_id || '',
+      planSlug: row.plan_slug || 'free',
+      quotaDaily: row.quota_daily,
+      quotaUsed: row.quota_used,
+      rateLimitRpm: row.rate_limit_rpm,
+      maxConcurrent: row.max_concurrent,
+      status: row.status,
+    }
+  } else {
+    const freePlan = await pool.query(`SELECT id FROM plans WHERE slug = 'free' LIMIT 1`)
+    const planId = freePlan.rows[0]?.id || null
+
+    const inserted = await pool.query(
+      `INSERT INTO tenants (wallet_address, plan_id, quota_daily, rate_limit_rpm, max_concurrent)
+       VALUES ($1, $2, $3, $4, $5)
+       RETURNING id`,
+      [address, planId, 0, 5, 1]
+    )
+    tenant = {
+      id: inserted.rows[0].id,
+      walletAddress: address,
+      planId: planId || '',
+      planSlug: 'free',
+      quotaDaily: 0,
+      quotaUsed: 0,
+      rateLimitRpm: 5,
+      maxConcurrent: 1,
+      status: 'active',
+    }
+  }
+
+  const token = jwt.sign(
+    { tenantId: tenant.id, walletAddress: tenant.walletAddress },
+    config.jwtSecret,
+    { expiresIn: config.sessionTtlSec }
+  )
+
+  res.json({ access_token: token, expires_in: config.sessionTtlSec, tenant })
+}
+
+export function authMiddleware(req: Request, res: Response, next: NextFunction): void {
+  const authHeader = req.headers.authorization
+  if (!authHeader || !authHeader.startsWith('Bearer ')) {
+    res.status(401).json({ error: 'Missing or invalid Authorization header' })
+    return
+  }
+
+  const token = authHeader.slice(7)
+  let decoded: { tenantId: string; walletAddress: string }
+  try {
+    decoded = jwt.verify(token, config.jwtSecret) as typeof decoded
+  } catch {
+    res.status(401).json({ error: 'Invalid or expired token' })
+    return
+  }
+
+  getPool()
+    .query(
+      `SELECT t.id, t.wallet_address, t.status,
+              t.quota_daily, t.quota_used, t.rate_limit_rpm, t.max_concurrent,
+              p.id as plan_id, p.slug as plan_slug
+       FROM tenants t
+       LEFT JOIN plans p ON t.plan_id = p.id
+       WHERE t.id = $1`,
+      [decoded.tenantId]
+    )
+    .then(r => {
+      if (r.rows.length === 0) {
+        res.status(401).json({ error: 'Tenant not found' })
+        return
+      }
+      const row = r.rows[0]
+      if (row.status === 'suspended') {
+        res.status(403).json({ error: 'Account suspended' })
+        return
+      }
+      req.tenant = {
+        id: row.id,
+        walletAddress: row.wallet_address,
+        planId: row.plan_id || '',
+        planSlug: row.plan_slug || 'free',
+        quotaDaily: row.quota_daily,
+        quotaUsed: row.quota_used,
+        rateLimitRpm: row.rate_limit_rpm,
+        maxConcurrent: row.max_concurrent,
+        status: row.status,
+      }
+      next()
+    })
+    .catch(err => {
+      next(err)
+    })
+}

package/src/middleware/error-handler.ts

@@ -0,0 +1,109 @@
+// ---------------------------------------------------------------------------
+// AgentX Gateway — Unified Error Handler
+// ---------------------------------------------------------------------------
+// AppError hierarchy + global Express error middleware.
+// Replaces scattered res.status(500).json({ error: err.message }) patterns.
+// ---------------------------------------------------------------------------
+
+import { Request, Response, NextFunction } from 'express'
+
+// ── Error Classes ────────────────────────────────────────────────────────
+
+export class AppError extends Error {
+  public readonly statusCode: number
+  public readonly code: string
+  public readonly expose: boolean
+
+  constructor(message: string, statusCode = 500, code = 'INTERNAL_ERROR', expose = false) {
+    super(message)
+    this.statusCode = statusCode
+    this.code = code
+    this.expose = expose
+    Object.setPrototypeOf(this, AppError.prototype)
+  }
+}
+
+export class BadRequestError extends AppError {
+  constructor(message = 'Bad request') {
+    super(message, 400, 'BAD_REQUEST', true)
+  }
+}
+
+export class UnauthorizedError extends AppError {
+  constructor(message = 'Unauthorized') {
+    super(message, 401, 'UNAUTHORIZED', true)
+  }
+}
+
+export class ForbiddenError extends AppError {
+  constructor(message = 'Forbidden') {
+    super(message, 403, 'FORBIDDEN', true)
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(message = 'Not found') {
+    super(message, 404, 'NOT_FOUND', true)
+  }
+}
+
+export class ConflictError extends AppError {
+  constructor(message = 'Conflict') {
+    super(message, 409, 'CONFLICT', true)
+  }
+}
+
+export class TooManyRequestsError extends AppError {
+  constructor(message = 'Too many requests') {
+    super(message, 429, 'TOO_MANY_REQUESTS', true)
+  }
+}
+
+// ── Global Error Handler Middleware ───────────────────────────────────────
+
+/**
+ * Centralized Express error handler.
+ * - AppError subclasses → use their statusCode + expose message
+ * - Unknown errors → 500 with safe message (no leak)
+ */
+export function globalErrorHandler(
+  err: Error,
+  _req: Request,
+  res: Response,
+  _next: NextFunction,
+): void {
+  if (res.headersSent) return
+
+  if (err instanceof AppError) {
+    const body: Record<string, unknown> = {
+      error: err.expose ? err.message : 'Internal server error',
+      code: err.code,
+    }
+    // Attach details only in development
+    if (process.env.NODE_ENV === 'development' && !err.expose) {
+      body.detail = err.message
+    }
+    res.status(err.statusCode).json(body)
+    return
+  }
+
+  // Unknown / unexpected error — never leak message to client
+  console.error('[Gateway Error]', err)
+  res.status(500).json({
+    error: 'Internal server error',
+    code: 'INTERNAL_ERROR',
+    ...(process.env.NODE_ENV === 'development' ? { detail: err.message } : {}),
+  })
+}
+
+/**
+ * Async route wrapper — catches thrown errors and forwards them to next().
+ * Usage: router.get('/path', asyncHandler(async (req, res) => { ... }))
+ */
+export function asyncHandler(
+  fn: (req: Request, res: Response, next: NextFunction) => Promise<void>,
+) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    fn(req, res, next).catch(next)
+  }
+}