Skip to content

Latest commit

 

History

History
273 lines (196 loc) · 4.73 KB

npm.md

File metadata and controls

273 lines (196 loc) · 4.73 KB

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