@openbotauth/proxy

Reverse proxy for verifying Web Bot Auth / OpenBotAuth signed HTTP requests. Works with any HTTP backend (Apache, Nginx, Node.js, Python, Go, Ruby, etc.).

Web Bot Auth is an IETF Internet-Draft for authenticating AI agents and bots using RFC 9421 HTTP Message Signatures. OpenBotAuth provides an open-source implementation aligned with the draft, along with a registry and hosted verifier service.

This proxy:

• Verifies RFC 9421 signatures on incoming HTTP requests
• Injects X-OBAuth- headers* with verification results for your backend
• Protects any HTTP server without code changes to your application
• Supports observe and enforce modes for gradual rollout

Installation

# npm (global)
npm install -g @openbotauth/proxy

# npx (no install required)
npx @openbotauth/proxy

# pnpm
pnpm add -g @openbotauth/proxy

# Homebrew (coming soon)
brew install openbotauth/tap/openbotauth-proxy

# Docker (Docker Hub)
docker run -p 8088:8088 hammadtariq/openbotauth-proxy

# Docker (GitHub Container Registry)
docker run -p 8088:8088 ghcr.io/openbotauth/openbotauth-proxy

Quick Start

# Start the proxy in front of your backend
UPSTREAM_URL=http://localhost:3000 npx @openbotauth/proxy

All requests to localhost:8088 are proxied to your backend at localhost:3000 with verification headers injected.

Usage

# Basic usage (proxies to localhost:8080 by default)
npx @openbotauth/proxy

# Or if installed globally
openbotauth-proxy
# or
oba-proxy

# Production configuration
PORT=8088 \
UPSTREAM_URL=http://localhost:3000 \
OBA_VERIFIER_URL=https://verifier.openbotauth.org/verify \
OBA_MODE=require-verified \
OBA_PROTECTED_PATHS=/api,/protected \
openbotauth-proxy

Configuration

| Variable | Default | Description | |----------|---------|-------------| | PORT | 8088 | Proxy listen port | | UPSTREAM_URL | http://localhost:8080 | Backend server URL to proxy to | | OBA_VERIFIER_URL | https://verifier.openbotauth.org/verify | OpenBotAuth verifier endpoint | | OBA_MODE | observe | observe or require-verified | | OBA_TIMEOUT_MS | 5000 | Verifier request timeout in ms | | OBA_PROTECTED_PATHS | /protected | Comma-separated paths requiring verification |

Modes

Observe Mode (Default)

All requests pass through to your backend. The proxy adds X-OBAuth-* headers indicating verification status. Use this for:

• Logging and analytics
• Gradual rollout
• Understanding bot traffic before enforcing

OBA_MODE=observe openbotauth-proxy

Require-Verified Mode

Protected paths return 401 Unauthorized if the request is unsigned or verification fails. Unprotected paths still pass through.

OBA_MODE=require-verified \
OBA_PROTECTED_PATHS=/api,/protected \
openbotauth-proxy

Headers Injected

Your backend receives these headers on every request:

| Header | Description | |--------|-------------| | X-OBAuth-Verified | true if signature verified, false otherwise | | X-OBAuth-Agent | Bot's client_name (if verified) | | X-OBAuth-JWKS-URL | Bot's JWKS URL for key lookup | | X-OBAuth-Kid | Key ID used for signing | | X-OBAuth-Error | Error message (on verification failure) |

Example Backend Usage (Node.js)

app.get('/api/data', (req, res) => {
  if (req.headers['x-obauth-verified'] === 'true') {
    // Verified bot request
    console.log('Bot:', req.headers['x-obauth-agent']);
    res.json({ data: 'full access' });
  } else {
    // Unverified or human request
    res.json({ data: 'limited access' });
  }
});

Example Backend Usage (Python/Flask)

@app.route('/api/data')
def api_data():
    if request.headers.get('X-OBAuth-Verified') == 'true':
        agent = request.headers.get('X-OBAuth-Agent')
        return jsonify({'data': 'full access', 'bot': agent})
    return jsonify({'data': 'limited access'})

Health Check

The proxy exposes a health check endpoint:

curl http://localhost:8088/.well-known/health

Response:

{
  "status": "ok",
  "service": "openbotauth-proxy",
  "upstream": "http://localhost:8080",
  "verifier": "https://verifier.openbotauth.org/verify",
  "mode": "observe"
}

Docker

# Run with Docker
docker run -p 8088:8088 \
  -e UPSTREAM_URL=http://host.docker.internal:3000 \
  -e OBA_MODE=observe \
  hammadtariq/openbotauth-proxy

Docker Compose example:

version: '3.8'
services:
  proxy:
    image: hammadtariq/openbotauth-proxy
    ports:
      - "8088:8088"
    environment:
      - UPSTREAM_URL=http://backend:3000
      - OBA_MODE=require-verified
      - OBA_PROTECTED_PATHS=/api

  backend:
    image: your-backend
    # No need to expose port - only proxy is public

See the OpenBotAuth repository for more Docker Compose examples.

Architecture

                         +----------------+
                         |    Verifier    |
                         |    Service     |
                         +-------^--------+
                                 |
+----------+    +----------+     |     +----------+
|  Client  |--->|   Proxy  |-----+---->|  Backend |
| (AI Bot) |    |          |           | (Your App)|
+----------+    +----------+           +----------+

1. Bot sends signed HTTP request to proxy
2. Proxy extracts RFC 9421 signature headers
3. Proxy calls verifier service to validate signature
4. Proxy injects X-OBAuth-* headers with results
5. Backend receives request with verification info

Development

# Clone the repository
git clone https://github.com/OpenBotAuth/openbotauth.git
cd openbotauth/packages/proxy

# Install dependencies
pnpm install

# Start with hot reload
pnpm dev

# Run tests
pnpm test

# Build for production
pnpm build

Standards & References

• Web Bot Auth IETF Draft - The IETF draft specification for bot authentication
• RFC 9421 - HTTP Message Signatures
• RFC 7517 - JSON Web Key (JWK)
• OpenBotAuth - Reference implementation and hosted services
• OpenBotAuth GitHub - Source code and documentation

Related Packages

• @openbotauth/verifier-client - Client library for Node.js/Express/Next.js integration
• @openbotauth/bot-cli - CLI for testing signed requests

License

Apache-2.0