docs: add HTTP/auth/SSH/API reference guides and fix tool reference inaccuracies

docs/config/api-reference.mdx

@@ -0,0 +1,177 @@
+---
+title: "API Reference"
+description: "REST API endpoints for querying data sources and request traces"
+---
+
+DBHub exposes REST API endpoints for integrating with external tools and the Workbench frontend. These are only available when running with HTTP transport.
+
+## List Sources
+
+```http
+GET /api/sources
+```
+
+Returns all configured database sources.
+
+**Example response:**
+
+```json
+[
+  {
+    "id": "local_pg",
+    "type": "postgres",
+    "description": "Production PostgreSQL",
+    "host": "localhost",
+    "port": 5432,
+    "database": "mydb",
+    "user": "myuser",
+    "tools": [
+      { "name": "execute_sql", "readonly": true },
+      { "name": "search_objects", "readonly": true }
+    ]
+  }
+]
+```
+
+Sensitive fields (passwords, SSH keys) are excluded from the response.
+
+**Response fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Source identifier |
+| `type` | string | Database type: `postgres`, `mysql`, `mariadb`, `sqlserver`, `sqlite` |
+| `description` | string? | Optional description from TOML config |
+| `host` | string? | Database hostname |
+| `port` | number? | Database port |
+| `database` | string? | Database name or SQLite file path |
+| `user` | string? | Database username |
+| `ssh_tunnel` | object? | SSH tunnel configuration (if enabled) |
+| `tools` | array | Available MCP tools for this source |
+
+**Errors:**
+
+| Status | Meaning |
+|--------|---------|
+| 200 | Success |
+| 500 | Internal server error |
+
+---
+
+## Get Source
+
+```http
+GET /api/sources/:sourceId
+```
+
+Returns a single source by ID.
+
+**Example response:**
+
+```json
+{
+  "id": "local_pg",
+  "type": "postgres",
+  "host": "localhost",
+  "port": 5432,
+  "database": "mydb",
+  "user": "myuser",
+  "tools": [
+    { "name": "execute_sql", "readonly": true },
+    { "name": "search_objects", "readonly": true }
+  ]
+}
+```
+
+**Errors:**
+
+| Status | Meaning |
+|--------|---------|
+| 200 | Success |
+| 404 | Source not found |
+| 500 | Internal server error |
+
+---
+
+## List Requests
+
+```http
+GET /api/requests?source_id=prod_pg
+```
+
+Returns recent tool execution traces. The `source_id` query parameter is optional — omit it to get requests from all sources.
+
+**Example response:**
+
+```json
+{
+  "requests": [
+    {
+      "id": "req_abc123",
+      "source_id": "local_pg",
+      "tool": "execute_sql",
+      "sql": "SELECT * FROM users LIMIT 5",
+      "started_at": "2026-08-03T12:00:00Z",
+      "duration_ms": 12,
+      "row_count": 5,
+      "status": "success"
+    }
+  ],
+  "total": 1
+}
+```
+
+**Query parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `source_id` | string? | Filter by source ID |
+
+**Response fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `requests` | array | Tool execution traces |
+| `total` | number | Total number of requests returned |
+
+**Errors:**
+
+| Status | Meaning |
+|--------|---------|
+| 200 | Success |
+| 500 | Internal server error |
+
+<Note>
+Request traces are stored in memory and reset on server restart. The latest 100 requests per source are retained.
+</Note>
+
+## Health Check
+
+```http
+GET /healthz
+```
+
+Returns `200 OK` without any authentication. Uptime monitors and load balancer probes can use this endpoint without a token.
+
+**Example:**
+
+```bash
+curl http://localhost:8080/healthz
+# OK
+```
+
+## Authentication
+
+All API endpoints (except `/healthz`) require a bearer token if `--auth-token` is configured:
+
+```bash
+curl -H "Authorization: Bearer s3cr3t-token" http://localhost:8080/api/sources
+```
+
+See [Authentication](/config/auth-token) for complete setup.
+
+## See Also
+
+- [HTTP Server](/config/http-server) — Server configuration and endpoints
+- [Authentication](/config/auth-token) — Bearer token setup
+- [Workbench](/workbench/overview) — Browser-based interface

docs/config/auth-token.mdx

@@ -0,0 +1,168 @@
+---
+title: "Authentication"
+description: "Secure your DBHub HTTP server with bearer token authentication"
+---
+
+When running DBHub with HTTP transport, anybody who can reach the server URL can access your database. To protect it, configure **bearer token authentication** with `--auth-token`.
+
+## How It Works
+
+DBHub checks every HTTP request for a valid `Authorization: Bearer <token>` header. Requests without a valid token are rejected with `401 Unauthorized` and a `WWW-Authenticate: Bearer` header.
+
+The `/healthz` endpoint is exempt from authentication so uptime monitors and load balancer probes don't need a token.
+
+<Note>
+Configuring a token **is** the opt-in — there is no separate "--require-auth" flag to remember. Auth is disabled by default; set `--auth-token` or `DBHUB_AUTH_TOKEN` and it turns on.
+</Note>
+
+## Setting the Token
+
+### CLI Flag
+
+```bash
+npx @bytebase/dbhub@latest --transport http --port 8080 \
+  --auth-token "s3cr3t-token" \
+  --dsn "postgres://user:***@localhost:5432/dbname"
+```
+
+### Environment Variable
+
+```bash
+export DBHUB_AUTH_TOKEN="s3cr3t-token"
+npx @bytebase/dbhub@latest --transport http --port 8080 --dsn "..."
+```
+
+### .env File
+
+```bash
+# .env
+DBHUB_AUTH_TOKEN="s3cr3t-token"
+```
+
+```bash
+npx @bytebase/dbhub@latest --transport http --port 8080 --dsn "..."
+```
+
+### Docker
+
+```bash
+docker run --rm --init \
+  --name dbhub \
+  --publish 8080:8080 \
+  -e DBHUB_AUTH_TOKEN="s3cr3t-token" \
+  bytebase/dbhub \
+  --transport http --port 8080 \
+  --dsn "postgres://user:***@localhost:5432/dbname"
+```
+
+## Client Configuration
+
+### curl
+
+```bash
+curl -H "Authorization: Bearer s3cr3t-token" http://localhost:8080/api/sources
+```
+
+### MCP Client (Claude Code, etc.)
+
+Configure the `Authorization` header in your MCP client's HTTP configuration:
+
+```json .mcp.json
+{
+  "mcpServers": {
+    "dbhub": {
+      "type": "http",
+      "url": "http://localhost:8080/mcp",
+      "headers": {
+        "Authorization": "Bearer s3cr3t-token"
+      }
+    }
+  }
+}
+```
+
+### Claude Code CLI
+
+```bash
+claude mcp add --transport http dbhub http://localhost:8080/mcp
+```
+
+Then add the `Authorization` header in your Claude Code settings or `.mcp.json`.
+
+## Multiple Tokens
+
+`--auth-token` accepts a comma-separated list. This enables two common scenarios:
+
+### Zero-Downtime Rotation
+
+1. Add the new token alongside the old one:
+   ```bash
+   --auth-token "old-token,new-token"
+   ```
+2. Redeploy DBHub.
+3. Update all clients to use `new-token`.
+4. Remove `old-token` from the list and redeploy again.
+
+### Per-Client Tokens
+
+Issue different tokens to different clients so one can be revoked without affecting the others:
+
+```bash
+--auth-token "token-for-ci,token-for-agent,token-for-workbench"
+```
+
+## Security Considerations
+
+### Constant-Time Comparison
+
+DBHub uses Node.js `timingSafeEqual` to compare tokens, preventing timing side-channel attacks that could leak the token character by character.
+
+### Shared Secret, Not OAuth
+
+This is a flat shared-secret check, not OAuth 2.1. It answers "does this request have the secret," not "who is this user" — there are no per-user scopes, rate limits, or audit trails.
+
+<Warning>
+If you need real identity-based authorization (per-user access control, audit logging, integration with your IdP), front DBHub with your own OAuth-aware proxy or IdP-integrated gateway instead of relying on the built-in token check.
+</Warning>
+
+### Defense in Depth
+
+- Always use HTTPS in production (put DBHub behind a reverse proxy like nginx or Caddy that terminates TLS).
+- The token is sent in the `Authorization` header on every request — without HTTPS, it's visible in plaintext on the network.
+- Use a strong, random token (at least 32 characters). `openssl rand -base64 32` is a good way to generate one.
+
+## Verify It's Working
+
+When DBHub starts with a token configured, it logs:
+
+```
+Auth: bearer token required (2 token(s) configured via command line argument)
+```
+
+Without a token:
+
+```
+Auth: disabled (set --auth-token or DBHUB_AUTH_TOKEN to require a bearer token)
+```
+
+Test that a request without a token is rejected:
+
+```bash
+curl -i http://localhost:8080/api/sources
+# Expected: 401 Unauthorized
+```
+
+Test that a request with a valid token succeeds:
+
+```bash
+curl -i -H "Authorization: Bearer s3cr3t-token" http://localhost:8080/api/sources
+# Expected: 200 OK
+```
+
+## Reference
+
+| Flag | Env | Default | Description |
+|------|-----|---------|-------------|
+| `--auth-token` | `DBHUB_AUTH_TOKEN` | (disabled) | Comma-separated bearer token(s) |
+
+See [Command-Line Options](/config/command-line) for all flags.

docs/config/command-line.mdx

@@ -1,5 +1,6 @@
 ---
 title: "Command-Line Options"
+description: "Complete reference for all DBHub CLI flags, environment variables, and DSN formats"
 ---
 
 DBHub connects to your database in one of two ways:
@@ -289,20 +290,27 @@ This page covers command-line flags and environment variables. For TOML configur
 ### --id
 
 <ParamField path="--id" type="string" env="ID">
-  Instance identifier to suffix tool names. Useful when running multiple DBHub instances (e.g., in Cursor). Env: `ID`.
+  Instance identifier to suffix tool names. Useful when running multiple DBHub instances (e.g., connecting to different databases from Cursor or Claude Code). Env: `ID`.
 
-  Tools will be named `execute_sql_{id}` for each instance.
+  Tool names will be suffixed with the id: `execute_sql_{id}`, `search_objects_{id}`.
 
   ```bash
-  npx @bytebase/dbhub@latest --id prod --dsn "postgres://user:pass@prod-host:5432/db"
-  npx @bytebase/dbhub@latest --id staging --dsn "postgres://user:pass@staging-host:5432/db"
+  # Instance 1: production
+  npx @bytebase/dbhub@latest --id prod --dsn "postgres://user:***@prod-host:5432/db"
+
+  # Instance 2: staging
+  npx @bytebase/dbhub@latest --id staging --dsn "postgres://user:***@staging-host:5432/db"
   ```
 
-  Result: `execute_sql_prod` and `execute_sql_staging` tools
+  Result: `execute_sql_prod` and `execute_sql_staging` tools.
 
   <Warning>
-  Cannot be used with `--config` (TOML configuration). TOML config defines source IDs directly in the configuration file. Use command-line DSN configuration instead if you need the `--id` flag.
+  Cannot be used with `--config` (TOML configuration). TOML config defines source IDs directly in the configuration file (`[[sources]]` with `id` fields). Use command-line DSN configuration instead if you need the `--id` flag.
   </Warning>
+
+  <Tip>
+  **Multi-instance scenario:** Run two DBHub processes on different ports, each with a different `--id`, then configure your MCP client to connect to both. This gives you separate tool names for each database without needing a TOML file.
+  </Tip>
 </ParamField>
 
 ### --demo