hammadtariq/openbotauth-proxy

•Updated 10 months ago

Image

622

hammadtariq/openbotauth-proxy repository overview

⁠@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)|
+----------+    +----------+           +----------+

Bot sends signed HTTP request to proxy
Proxy extracts RFC 9421 signature headers
Proxy calls verifier service to validate signature
Proxy injects X-OBAuth-* headers with results
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

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

⁠License

Apache-2.0

Tag summary

Recent tags

Content type

Image

Digest

sha256:f38867eeb…

Size

73.5 MB

Last updated

10 months ago

docker pull hammadtariq/openbotauth-proxy