npm package: @ssdavidai/zooks
Description: HTTPS interceptor proxy for Zo API — observe requests and responses without modifying Zo code
Latest version: 1.3.0

# @ssdavidai/zooks

Hooks for [Zo Computer](https://zo.computer). Intercepts messages sent to and received from the Zo API (`/zo/ask`) by running a local HTTPS proxy — no modifications to Zo source code required.

Zooks uses `/etc/hosts` to redirect `api.zo.computer` to a local proxy that fires `PreToolUse` and `PostToolUse` events around every API call, then forwards traffic to the real endpoint transparently.

## Install

```bash
npm install -g @ssdavidai/zooks
```

## Quick Start

```bash
# Generate certs, configure /etc/hosts, resolve upstream IPs
zooks setup

# Start the interceptor proxy (foreground)
zooks start

# In another terminal, Zo API calls are now intercepted
# You'll see PreToolUse and PostToolUse log entries for every /zo/ask call
```

## How It Works

```
Zo services (Python/Bun/Node)
  → fetch("https://api.zo.computer/zo/ask")
  → /etc/hosts resolves api.zo.computer to 127.0.0.1
  → zooks proxy (HTTPS :443)
  → PreToolUse event fires
  → request forwarded to real api.zo.computer IP
  → PostToolUse event fires
  → response returned to caller unchanged
```

Zooks resolves the real IP addresses of `api.zo.computer` before adding the `/etc/hosts` redirect, then forwards all traffic to those IPs with the correct `Host` header and TLS SNI. A locally-generated CA certificate is added to the system trust store so all runtimes (Python `requests`, Node, Bun) trust the proxy without extra configuration.

## CLI

```bash
zooks setup       # Generate certs, add CA to trust store, add /etc/hosts entry
zooks start       # Start proxy on :443 (foreground)
zooks start --daemon                # Background mode
zooks start --log-file /var/log/zooks.log  # Custom log file location
zooks stop        # Stop the daemon
zooks status      # Show proxy status, cert status, /etc/hosts, resolved IPs
zooks logs        # Live tail of intercepted events with color formatting
zooks logs --raw  # Raw JSON lines (no formatting)
zooks teardown    # Remove /etc/hosts entry, certs, and ~/.zooks/
```

`zooks start` will auto-run `setup` if certs or `/etc/hosts` aren't configured yet.

All intercepted events are logged to `~/.zooks/zooks.log`. Run `zooks logs` in a separate terminal to watch events in real time as they flow through the proxy.

## Events

Zooks exposes two events:

### `PreToolUse`

Fires when a message is submitted to the Zo API, before the request is forwarded upstream.

```javascript
interceptor.on('PreToolUse', (event) => {
  // event:
  // {
  //   timestamp: '2025-01-15T10:30:00.000Z',
  //   input: 'the input sent to /zo/ask',
  //   conversation_id: '...',
  //   headers: { authorization: '...', ... },
  //   method: 'POST',
  //   url: '/zo/ask'
  // }
});
```

### `PostToolUse`

Fires when a response is received from the Zo API, before it's returned to the caller.

```javascript
interceptor.on('PostToolUse', (event) => {
  // event:
  // {
  //   timestamp: '2025-01-15T10:30:01.500Z',
  //   status: 200,
  //   output: 'the response from Zo',
  //   conversation_id: '...',
  //   duration_ms: 1500
  // }
});
```

## Library API

Use zooks programmatically in your own Node.js scripts:

```javascript
import { createInterceptor } from '@ssdavidai/zooks';

const interceptor = createInterceptor({
  logFile: '/var/log/zooks.log', // optional, defaults to stdout
});

interceptor.on('PreToolUse', (event) => {
  console.log('Input sent:', event.input);
});

interceptor.on('PostToolUse', (event) => {
  console.log('Response received:', event.output, `(${event.duration_ms}ms)`);
});

await interceptor.start();
```

## Log Format

Each intercepted call produces two structured JSON log lines:

```jsonl
{"timestamp":"...","direction":"PreToolUse","conversation_id":"...","preview":"first 120 chars of input"}
{"timestamp":"...","direction":"PostToolUse","status":200,"conversation_id":"...","preview":"first 120 chars of response","duration_ms":1500}
```

## Setup Details

`zooks setup` does the following:

1. Resolves the real IP addresses of `api.zo.computer` via DNS and caches them in `~/.zooks/resolved-ips.json`
2. Generates a local CA and server certificate for `api.zo.computer` using OpenSSL, stored in `~/.zooks/certs/`
3. Appends the CA certificate to `/etc/ssl/certs/ca-certificates.crt` so Python, Node, and Bun trust the proxy
4. Adds `127.0.0.1 api.zo.computer # zooks` to `/etc/hosts`

`zooks teardown` reverses all of the above.

## Requirements

- Node.js >= 22
- OpenSSL (for certificate generation)
- Root access (for `/etc/hosts` and port 443)

## License

MIT