npm package: @openbotauth/sidecar
Description: Web Bot Auth / OpenBotAuth reverse-proxy sidecar for verifying RFC 9421 HTTP signatures
Author: OpenBotAuth
Latest version: 0.1.5
Deprecated: This package has been renamed to @openbotauth/proxy. Please install @openbotauth/proxy instead.

# @openbotauth/sidecar

Reverse-proxy sidecar for verifying [Web Bot Auth](https://datatracker.ietf.org/doc/draft-meunier-web-bot-auth-architecture/) / [OpenBotAuth](https://openbotauth.org) signed HTTP requests. Works with any HTTP backend (Apache, Nginx, Node.js, Python, Go, Ruby, etc.).

Web Bot Auth is an IETF draft standard for authenticating AI agents and bots using RFC 9421 HTTP Message Signatures. OpenBotAuth provides the reference implementation, registry, and hosted verifier service.

This sidecar:
- **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/sidecar

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

# pnpm
pnpm add -g @openbotauth/sidecar

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

# Docker
docker run -p 8088:8088 openbotauth/sidecar
```

## Quick Start

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

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/sidecar

# Or if installed globally
oba-sidecar

# 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 \
oba-sidecar
```

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `8088` | Sidecar 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 sidecar adds `X-OBAuth-*` headers indicating verification status. Use this for:
- Logging and analytics
- Gradual rollout
- Understanding bot traffic before enforcing

```bash
OBA_MODE=observe oba-sidecar
```

### Require-Verified Mode

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 \
oba-sidecar
```

## 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)

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

### Example Backend Usage (Python/Flask)

```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 sidecar exposes a health check endpoint:

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

Response:
```json
{
  "status": "ok",
  "service": "openbotauth-sidecar",
  "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 \
  openbotauth/sidecar
```

Docker Compose example:

```yaml
version: '3.8'
services:
  sidecar:
    image: openbotauth/sidecar
    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 sidecar is public
```

See `infra/sidecar/` in the [OpenBotAuth repository](https://github.com/OpenBotAuth/openbotauth) for more Docker Compose examples.

## Architecture

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

1. Bot sends signed HTTP request to sidecar
2. Sidecar extracts RFC 9421 signature headers
3. Sidecar calls verifier service to validate signature
4. Sidecar 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/sidecar

# 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](https://datatracker.ietf.org/doc/draft-meunier-web-bot-auth-architecture/) - The IETF draft specification for bot authentication
- [RFC 9421](https://www.rfc-editor.org/rfc/rfc9421.html) - HTTP Message Signatures
- [RFC 7517](https://www.rfc-editor.org/rfc/rfc7517.html) - JSON Web Key (JWK)
- [OpenBotAuth](https://openbotauth.org) - Reference implementation and hosted services
- [OpenBotAuth GitHub](https://github.com/OpenBotAuth/openbotauth) - Source code and documentation

## Related Packages

- [@openbotauth/verifier-client](https://www.npmjs.com/package/@openbotauth/verifier-client) - Client library for Node.js/Express/Next.js integration
- [@openbotauth/bot-cli](https://www.npmjs.com/package/@openbotauth/bot-cli) - CLI for testing signed requests

## License

Apache-2.0