NPM / CLI

Run the OpenBotAuth Proxy using npm or npx.

Package: @openbotauth/proxy

Quick Start

# Run without installing (recommended)
npx @openbotauth/proxy

# Or install globally
npm install -g @openbotauth/proxy
openbotauth-proxy

Requirements: Node.js >= 18.0.0

Installation Methods

npx (No Install)

Run directly without installing:

npx @openbotauth/proxy

Global Install

# npm
npm install -g @openbotauth/proxy

# pnpm
pnpm add -g @openbotauth/proxy

# yarn
yarn global add @openbotauth/proxy

After global install, run with:

openbotauth-proxy
# or
oba-proxy

Local Install

Add to your project:

npm install @openbotauth/proxy

Then run via npm scripts in package.json:

{
  "scripts": {
    "proxy": "openbotauth-proxy"
  }
}

Configuration

All configuration is via environment variables:

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

Usage Examples

Basic Usage

Proxy requests from port 8088 to localhost:8080:

npx @openbotauth/proxy

Custom Backend

Proxy to a different backend:

UPSTREAM_URL=http://localhost:3000 npx @openbotauth/proxy

Custom Port

Run on a different port:

PORT=9000 npx @openbotauth/proxy

Require Verification

Enforce verification on all paths:

OBA_MODE=require-verified npx @openbotauth/proxy

Protected Paths Only

Require verification only on specific paths:

OBA_MODE=require-verified \
OBA_PROTECTED_PATHS=/api,/content,/premium \
npx @openbotauth/proxy

Full Configuration

PORT=8088 \
UPSTREAM_URL=http://localhost:3000 \
OBA_VERIFIER_URL=https://verifier.openbotauth.org/verify \
OBA_MODE=require-verified \
OBA_TIMEOUT_MS=3000 \
OBA_PROTECTED_PATHS=/api/v1,/protected \
npx @openbotauth/proxy

Process Managers

PM2

// ecosystem.config.js
module.exports = {
  apps: [{
    name: 'oba-proxy',
    script: 'npx',
    args: '@openbotauth/proxy',
    env: {
      PORT: 8088,
      UPSTREAM_URL: 'http://localhost:3000',
      OBA_MODE: 'observe'
    }
  }]
};

pm2 start ecosystem.config.js

systemd

# /etc/systemd/system/oba-proxy.service
[Unit]
Description=OpenBotAuth Proxy
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/oba-proxy
Environment=PORT=8088
Environment=UPSTREAM_URL=http://localhost:3000
Environment=OBA_MODE=observe
ExecStart=/usr/bin/npx @openbotauth/proxy
Restart=on-failure

[Install]
WantedBy=multi-user.target

sudo systemctl enable oba-proxy
sudo systemctl start oba-proxy

Programmatic Usage

You can also use the proxy programmatically in your Node.js application:

import { createProxyServer } from '@openbotauth/proxy';

const server = createProxyServer({
  port: 8088,
  upstream: 'http://localhost:3000',
  verifierUrl: 'https://verifier.openbotauth.org/verify',
  mode: 'observe',
  timeoutMs: 5000,
  protectedPaths: ['/api', '/protected']
});

server.listen();

Health Check

Verify the proxy is running:

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"
}

Logging

The proxy logs to stdout:

[OBA] Proxy started on port 8088
[OBA] Upstream: http://localhost:3000
[OBA] Mode: observe
[OBA] GET /api/content -> verified (agent: MyBot)
[OBA] GET /public -> unsigned

Troubleshooting

Proxy won't start

Check that the port is available:

lsof -i :8088

Verification always fails

1. Check the verifier URL is accessible

2. Verify the bot is sending correct RFC 9421 headers

3. Check clock synchronization (signatures expire)

Timeout errors

Increase the timeout:

OBA_TIMEOUT_MS=10000 npx @openbotauth/proxy

Backend not receiving requests

1. Verify UPSTREAM_URL is correct

2. Check backend is running and accessible

3. Test direct connection to backend

Links

• npm: https://www.npmjs.com/package/@openbotauth/proxy

• GitHub: https://github.com/OpenBotAuth/openbotauth