@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

``bash


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

`bash


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

`bash


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

$3

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

`bash
OBA_MODE=observe openbotauth-proxy
`

$3

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

`bash
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) |

$3

`javascript
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' });
}
});
`

$3

`python
@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:

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

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

Docker

`bash


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:

`yaml
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

`bash


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