@agent-trust/gateway

Express middleware that lets trusted AI agents interact with your website. Part of the AgentTrust ecosystem.

Install

npm install @agent-trust/gateway

TypeScript users: Types are included. You'll also need @types/express if you don't already have it:

npm install -D @types/express

Quick Start

import express from 'express';
import { createGateway } from '@agent-trust/gateway';

const app = express();
app.use(express.json());

const gateway = createGateway({
  stationUrl: 'https://agentgateway-6f041c655eb3.herokuapp.com',
  gatewayId: 'my-store',
  stationApiKey: 'YOUR_API_KEY',
  actions: {
    'search_products': {
      description: 'Search the product catalog',
      minScore: 30,
      parameters: {
        query: { type: 'string', required: true, description: 'Search query' }
      },
      handler: async (params) => {
        return await db.products.search(params.query);
      }
    },
    'place_order': {
      description: 'Place an order',
      minScore: 70,  // Higher trust required
      parameters: {
        productId: { type: 'string', required: true },
        quantity: { type: 'number', required: true }
      },
      handler: async (params, agent) => {
        return await db.orders.create({ ...params, agentId: agent.agentId });
      }
    }
  },
  behavior: {
    maxActionsPerMinute: 30,
    derivatives: {
      enabled: true,
      velocityThresholds: { actions_per_minute: 8, failures_per_minute: 3 },
      useAccelerationBlocking: true,
      predictiveBlockingSeconds: 30,
    },
    onSuspiciousActivity: (event) => {
      console.warn('Suspicious agent:', event.flag, event.description);
    }
  }
});

app.use('/agent-gateway', gateway.router());
app.listen(3000);

Features

• Certificate verification — validates RS256 JWT certificates from the AgentTrust Station
• Score-based access — different actions require different reputation levels
• Real-time behavioral tracking — detects and blocks suspicious agents mid-session
• Auto-reporting — reports agent behavior back to Station automatically (synced to Base L2 on-chain)
• Discovery endpoints — agents can discover available actions programmatically
• On-chain trust — every certificate and reputation score is recorded on Base L2, independently verifiable on BaseScan

Behavioral Tracking

The gateway monitors agent behavior in real-time and detects:

| Detection | What it catches | |-----------|----------------| | rapid_fire | Too many requests per minute | | high_failure_rate | Probing / brute force | | action_enumeration | Scanning endpoints | | repeated_action | Automation (same action on loop) | | scope_violation | Accessing above trust level | | burst_detected | Sudden activity after idle | | velocity_spike | Metric rate-of-change exceeds threshold (ramping attack) | | accelerating_attack | Metric acceleration indicates escalating threat | | predictive_breach | Forecasted score will breach block threshold in 30s |

Agents get a behavioral score (0-100) that degrades with violations. Drop below threshold = blocked mid-session.

Derivative-Based Detection (NEW)

The gateway now computes mathematical derivatives (velocity and acceleration) on behavioral metrics in real-time. This catches attacks that static thresholds miss:

• Velocity spike — detects slow ramp-up attacks before they hit static limits
• Accelerating attack — catches explosive probing and escalation patterns
• Predictive blocking — forecasts behavioral score 30 seconds ahead and blocks before breach

Configure via the derivatives option in behavior config.

API

Routes (mounted on your chosen path)

| Method | Path | Description | |--------|------|-------------| | GET | /.well-known/agent-gateway | Discovery manifest | | GET | /actions | List available actions | | POST | /actions/:name | Execute an action (cert required) | | GET | /behavior/sessions | Monitor active sessions |

Links

• Full documentation
• Live Station
• API docs

License

MIT