saros-proxy 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saros Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,620 @@
+# Saros
+
+[![CI](https://github.com/vitorvilaca3011/saros-proxy/actions/workflows/ci.yml/badge.svg)](https://github.com/vitorvilaca3011/saros-proxy/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/saros-proxy.svg)](https://www.npmjs.com/package/saros-proxy)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D%2022.0.0-brightgreen.svg)](https://nodejs.org/)
+
+Saros — like the eclipse cycle, this proxy predicts exhaustion and rotates accounts before they run out. Built for the OpenCode-Go API.
+
+Manage multiple OpenCode-Go API keys behind a single endpoint. When one key is rate-limited, revoked, or returns server errors, the proxy automatically fails over to the next healthy key — with zero downtime.
+
+---
+
+## Contents
+
+- [Features](#features)
+- [Architecture](#architecture)
+- [Installation](#installation)
+- [Docker](#docker)
+- [Quick Start](#quick-start)
+- [Configuration Reference](#configuration-reference)
+- [Usage Examples](#usage-examples)
+- [OpenCode Integration](#opencode-integration)
+- [Troubleshooting](#troubleshooting)
+- [Development](#development)
+- [LLM Quick Reference](#llm-quick-reference)
+- [Security](#security)
+- [License](#license)
+
+---
+
+## Features
+
+- **Multi-key rotation** — Round-robin distribution across API keys.
+- **Automatic failover** — Retry failed requests with the next available key.
+- **Circuit breaker** — Disable failing keys after a configurable threshold, then lazily re-enable them after a cooldown period.
+- **Streaming support** — SSE pass-through with mid-stream error detection.
+- **Request timeout** — Configurable timeout with graceful 504 response.
+- **Graceful shutdown** — Drains active requests before exiting.
+- **Security hardening** — API key masking in logs, SSRF prevention (HTTPS-only upstream), configurable CORS, host binding validation.
+- **Config validation** — CLI args, YAML file, and environment variables with sensible defaults.
+- **Health endpoint** — `GET /health` returns key status, active requests, and circuit-breaker state.
+- **No database** — Stateless proxy, zero external dependencies beyond Node.js.
+
+---
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────┐
+│                   Client / OpenCode                  │
+│  ┌──────────┐   ┌──────────┐   ┌──────────┐          │
+│  │ Request 1│   │ Request 2│   │ Request 3│  ...     │
+│  └────┬─────┘   └────┬─────┘   └────┬─────┘          │
+└───────┼──────────────┼──────────────┼────────────────┘
+        │              │              │
+        ▼              ▼              ▼
+┌──────────────────────────────────────────────────────┐
+│                    Saros (:3000)                     │
+│                                                      │
+│  ┌─────────────┐   ┌────────────┐   ┌─────────────┐  │
+│  │ Key Selector│──▶│ Circuit    │──▶│ Request    │  │
+│  │ Round-robin │   │ Breaker    │   │ Forwarder   │  │
+│  │ + Failover  │   │ Threshold  │   │ + Timeout   │  │
+│  └─────────────┘   │ + Cooldown │   └──────┬──────┘  │
+│                    └────────────┘          │         │
+│  ┌─────────────────────────────────────────┘         │
+│  │  ┌─────────────────────┐                          │
+│  └──▶ Streaming Detector  │  SSE passthrough         │
+│     └─────────────────────┘                          │
+└──────────────────────┬───────────────────────────────┘
+                       │
+           ┌────────────┼────────────┐
+           ▼            ▼            ▼
+    ┌──────────┐ ┌──────────┐ ┌──────────┐
+    │ Key A    │ │ Key B    │ │ Key C    │
+    │ sk-abc…  │ │ sk-def…  │ │ sk-ghi…  │
+    └────┬─────┘ └────┬─────┘ └────┬─────┘
+         │            │            │
+         ▼            ▼            ▼
+    ┌───────────────────────────────────────┐
+    │        OpenCode-Go API (upstream)     │
+    │        https://opencode.ai            │
+    └───────────────────────────────────────┘
+```
+
+### How Request Distribution Works
+
+The proxy uses **two layers** to decide which API key handles each request:
+
+#### Layer 1: Round-Robin (always active)
+Every new request cycles to the next key in order:
+
+```
+Request 1 → Key A
+Request 2 → Key B
+Request 3 → Key C
+Request 4 → Key A (wraps around)
+```
+
+This gives you **even distribution by default** — no manual odd/even logic needed. If you have 2 accounts, odd requests go to account 1 and even to account 2 automatically.
+
+#### Layer 2: Usage-Based Gating (optional)
+If you enable [dashboard scraping](#usage-based-key-selection), the proxy checks each account's quota usage before selecting a key:
+
+- If an account's usage is **≥ threshold** (default 70%), that key is skipped
+- If **all** keys are over threshold, the proxy falls back to the **lowest-usage** key
+- If no usage data is available, round-robin continues unchanged
+
+| Scenario | Behavior |
+|---|---|
+| Scraping disabled | Pure round-robin across all keys |
+| Scraping enabled + data available | Round-robin, skipping over-quota accounts |
+| Scraping enabled + no data | Falls back to pure round-robin |
+
+#### Concurrent Request Safety
+The proxy tracks which keys are **currently in use** by active requests. A key already handling a streaming request won't be assigned to another request until it completes. This prevents double-booking the same account under load.
+
+---
+
+## Installation
+
+### From npm (when published)
+
+```bash
+npm install -g saros-proxy
+```
+
+### From source
+
+```bash
+git clone https://github.com/vitorvilaca3011/saros-proxy.git
+cd proxy
+npm install
+npm run build
+```
+
+> **Requirements**: Node.js >= 22.0.0
+
+---
+
+## Docker
+
+Run the proxy in a clean Linux container without installing Node.js locally.
+
+### Prerequisites
+
+- [Docker](https://docs.docker.com/get-docker/) (with Compose v2)
+
+### Quick start
+
+```bash
+# 1. Create config.yaml from the example (edit with your API keys)
+cp config.example.yaml config.yaml
+
+# 2. Build the image
+npm run docker:build
+
+# 3. Start the proxy
+npm run docker:run
+```
+
+The proxy is now available at `http://127.0.0.1:3000`.
+
+### Run tests in Docker
+
+```bash
+# Run the full test suite inside a Linux container
+npm run docker:test
+```
+
+### Manual Docker commands
+
+```bash
+# Build
+docker compose build proxy
+
+# Run in foreground
+docker compose up proxy
+
+# Run in background (detached)
+docker compose up -d proxy
+
+# View logs
+docker compose logs -f proxy
+
+# Stop
+docker compose down
+
+# Run tests
+docker compose run --rm test
+```
+
+### Configuration with Docker
+
+Mount a custom `config.yaml` or use environment variables:
+
+```bash
+# Using environment variables (no config.yaml needed)
+docker compose run --rm -e OPENCODE_GO_KEYS="home:sk-xxx,work:sk-yyy" proxy
+
+# Or edit docker-compose.yml to set env vars directly, then:
+docker compose up proxy
+```
+
+---
+
+## Quick Start
+
+### Option A: Interactive Setup (Recommended)
+
+```bash
+# Run the setup wizard — it will guide you through everything
+npx saros-proxy setup
+
+# Or if installed globally:
+saros-proxy setup
+```
+
+The wizard will:
+1. Ask for your proxy port (default: 3000)
+2. Ask for your API keys (name + key value)
+3. Generate `config.yaml` automatically
+4. Run a smoke test to verify everything works
+
+### Option B: Manual Setup
+
+#### 1. Create a configuration file
+
+```yaml
+# config.yaml
+port: 3000
+host: 127.0.0.1
+upstreamBaseUrl: https://opencode.ai
+keys:
+  - label: primary
+    key: sk-your-primary-key-here-12345678
+  - label: secondary
+    key: sk-your-secondary-key-here-87654321
+circuitBreakerThreshold: 3
+circuitBreakerCooldownMs: 60000
+requestTimeoutMs: 30000
+```
+
+#### 2. Run the proxy
+
+```bash
+# Using tsx (development)
+npx tsx src/index.ts
+
+# Using built JavaScript
+node dist/index.js
+```
+
+#### 3. Test it
+
+```bash
+curl http://127.0.0.1:3000/health
+
+# Query models
+curl http://127.0.0.1:3000/zen/go/v1/models
+
+# Chat completion
+curl http://127.0.0.1:3000/zen/go/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{"model":"gpt-4","messages":[{"role":"user","content":"Hello"}]}'
+```
+
+---
+
+## Configuration Reference
+
+All configuration options can be set via YAML file (`config.yaml`), environment variables, or CLI flags. Priority order: CLI > YAML > env vars > defaults.
+
+### YAML / Environment Variables
+
+| Option | CLI Flag | Env Variable | Default | Description |
+|---|---|---|---|---|
+| `port` | `--port` | `PROXY_PORT` | `3000` | Listening port (1–65535) |
+| `host` | `--host` | `PROXY_HOST` | `127.0.0.1` | Bind address |
+| `upstreamBaseUrl` | — | `UPSTREAM_BASE_URL` | `https://opencode.ai` | Upstream API base URL (HTTPS only) |
+| `circuitBreakerThreshold` | — | `CIRCUIT_BREAKER_THRESHOLD` | `3` | Consecutive failures before disabling a key (1–10) |
+| `circuitBreakerCooldownMs` | — | `CIRCUIT_BREAKER_COOLDOWN_MS` | `60000` | Cooldown in ms before re-enabling a key (1000–3600000) |
+| `requestTimeoutMs` | — | `REQUEST_TIMEOUT_MS` | `30000` | Upstream request timeout in ms (1000–300000) |
+| `allowedOrigins` | — | — | `["http://localhost:*", "http://127.0.0.1:*"]` | CORS allowed origins (use `[]` to allow all) |
+| `keys` | — | `OPENCODE_GO_KEYS` | — | Array of `{label, key}` objects or comma-separated env format |
+| `config` | `--config` | — | `config.yaml` | Path to YAML config file |
+
+### API Key Format
+
+Keys must start with `sk-` and be at least 20 characters.
+
+**YAML:**
+```yaml
+keys:
+  - label: my-account
+    key: sk-your-key-here...
+```
+
+**Environment variable:**
+```bash
+OPENCODE_GO_KEYS="account1:sk-xxx,account2:sk-yyy"
+```
+
+### API Key Encryption
+
+API keys can be encrypted at rest using AES-256-GCM with scrypt key derivation. When encrypted, keys are stored as `enc:scrypt:...` in `config.yaml` and decrypted at startup using the `OPENCODE_GO_ENCRYPTION_KEY` environment variable.
+
+**Setup with encryption:**
+```bash
+npm run setup
+# When prompted, choose to encrypt keys and enter a master key (min 16 characters)
+```
+
+**Running with encrypted keys:**
+```bash
+export OPENCODE_GO_ENCRYPTION_KEY="your-master-key"
+npx tsx src/index.ts
+```
+
+**Docker with encrypted keys:**
+```yaml
+# docker-compose.yml
+environment:
+  - OPENCODE_GO_ENCRYPTION_KEY=your-master-key
+```
+
+**Notes:**
+- Encrypted keys use AES-256-GCM with scrypt KDF (N=16384, r=8, p=1)
+- Each key is encrypted with a random salt and IV
+- Plaintext keys (starting with `sk-`) are still supported for backward compatibility
+- The `OPENCODE_GO_KEYS` environment variable always uses plaintext keys (for CI/CD)
+- If keys are encrypted but `OPENCODE_GO_ENCRYPTION_KEY` is not set, the proxy will fail to start with a clear error message
+
+### CLI Flags
+
+```bash
+tsx src/index.ts --config my-config.yaml --port 4000 --host 0.0.0.0
+```
+
+---
+
+## Usage Examples
+
+### Basic: Run with YAML config
+
+```bash
+# Create config.yaml (see Quick Start), then:
+npx tsx src/index.ts
+```
+
+### Advanced: Run with environment variables only
+
+```bash
+export PROXY_PORT=4000
+export PROXY_HOST=127.0.0.1
+export OPENCODE_GO_KEYS="home:sk-abc123...,work:sk-def456..."
+export CIRCUIT_BREAKER_THRESHOLD=5
+export CIRCUIT_BREAKER_COOLDOWN_MS=120000
+export REQUEST_TIMEOUT_MS=45000
+export LOG_LEVEL=debug
+export NODE_ENV=development
+
+npx tsx src/index.ts
+```
+
+### Custom config path
+
+```bash
+npx tsx src/index.ts --config /etc/saros/config.yaml
+```
+
+### Run as a background service (Linux)
+
+```bash
+nohup npx tsx src/index.ts > proxy.log 2>&1 &
+```
+
+---
+
+## OpenCode Integration
+
+Configure OpenCode to route API requests through the proxy. Create or edit your OpenCode config file:
+
+**Location:** `~/.config/opencode/opencode.json` (global) or `opencode.json` in your project root
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "saros-proxy": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "Saros",
+      "options": {
+        "baseURL": "http://127.0.0.1:3000/zen/go/v1",
+        "apiKey": "not-used"
+      },
+      "models": {
+        "glm-5": { "name": "GLM-5" },
+        "kimi-k2.5": { "name": "Kimi K2.5" },
+        "qwen3.7-plus": { "name": "Qwen 3.7 Plus" }
+      }
+    }
+  }
+}
+```
+
+**Key points:**
+- `baseURL` must end at `/v1` — OpenCode appends route paths internally
+- `apiKey` can be any placeholder — the proxy handles real key selection
+- Model IDs must match what the upstream API expects (e.g., `glm-5`, not `opencode-go/glm-5`)
+- After editing the config, restart OpenCode
+
+**Alternative: Environment variable substitution**
+
+```jsonc
+{
+  "provider": {
+    "saros-proxy": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "Saros",
+      "options": {
+        "baseURL": "{env:OPENCODE_PROXY_URL}",
+        "apiKey": "{env:OPENCODE_PROXY_KEY}"
+      }
+    }
+  }
+}
+```
+
+Then set: `export OPENCODE_PROXY_URL=http://127.0.0.1:3000/zen/go/v1`
+
+**Using the proxy in OpenCode:**
+
+Once configured, select the proxy provider in OpenCode's model picker, or set it as default:
+
+```jsonc
+{
+  "provider": { /* ... as above ... */ },
+  "model": "saros-proxy/glm-5"
+}
+```
+
+---
+
+## Troubleshooting
+
+### Check proxy health
+
+```bash
+curl http://127.0.0.1:3000/health
+```
+
+Returns JSON with key counts, active requests, and circuit-breaker state.
+
+### View logs
+
+```bash
+# Development (pretty-printed, colorized)
+NODE_ENV=development npx tsx src/index.ts
+
+# Production (structured JSON)
+NODE_ENV=production npx tsx src/index.ts
+```
+
+### Verify which key served a request
+
+The proxy returns two debug headers on every successful response:
+
+| Header | Example | Meaning |
+|---|---|---|
+| `X-Proxy-Key-Label` | `primary` | Which configured key was used |
+| `X-Proxy-Request-Id` | `550e8400-e29b-41d4-a716-446655440000` | Unique request ID for log correlation |
+
+```bash
+# Check which key handled your request
+curl -s -D - http://127.0.0.1:3000/zen/go/v1/models | grep -i x-proxy
+# X-Proxy-Key-Label: primary
+# X-Proxy-Request-Id: 550e8400-e29b-41d4-a716-446655440000
+```
+
+### Common issues
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `No valid API keys configured` | Missing or invalid keys | Check `keys` in config.yaml or `OPENCODE_GO_KEYS` env var |
+| `ECONNREFUSED` on startup | Port already in use | Change `port` or kill the existing process |
+| `504 Gateway Timeout` | Upstream request exceeded timeout | Increase `requestTimeoutMs` or check upstream latency |
+| `All API keys are temporarily unavailable` | All keys disabled by circuit breaker | Wait for cooldown or check upstream status |
+| `CORS violation` | Client origin not in `allowedOrigins` | Add the origin to `allowedOrigins` in config |
+
+---
+
+## Development
+
+### Run tests
+
+```bash
+# Unit tests
+npm test
+
+# E2E tests (requires network)
+npx vitest run test/e2e.test.ts
+
+# Watch mode
+npm test -- --watch
+```
+
+### Type check
+
+```bash
+npm run lint
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+Output goes to `dist/`.
+
+### Project structure
+
+```
+src/
+  index.ts          — Entry point, server startup, graceful shutdown
+  proxy.ts          — Hono HTTP app, routing, streaming, failover
+  proxy-logic.ts    — Pure logic: key selection, circuit breaker, error classification
+  proxy-logic.test.ts — Unit tests for proxy logic
+  config.ts         — Configuration loading from YAML, env vars, CLI
+  logger.ts         — Structured logging with Pino + key masking
+  cli/
+    setup.ts        — Interactive setup wizard
+test/
+  e2e.test.ts       — End-to-end tests with mock upstream
+```
+
+### Contributing
+
+1. Fork the repository.
+2. Create a feature branch: `git checkout -b feat/my-feature`
+3. Commit changes: `git commit -am 'Add my feature'`
+4. Push: `git push origin feat/my-feature`
+5. Open a pull request.
+
+---
+
+## LLM Quick Reference
+
+If you're an AI assistant helping a user install this proxy, use these exact commands:
+
+**Prerequisites check:**
+```bash
+node --version  # Must be >= 22.0.0
+```
+
+**Install from source:**
+```bash
+git clone https://github.com/vitorvilaca3011/saros-proxy.git
+cd proxy
+npm install
+npm run build
+```
+
+**Configure:**
+```bash
+npm run setup  # Interactive wizard
+# OR manually: cp config.example.yaml config.yaml && edit config.yaml
+```
+
+**Run:**
+```bash
+npm run dev         # Development
+node dist/index.js  # Production
+```
+
+**Verify:**
+```bash
+curl http://127.0.0.1:3000/health
+```
+
+**Docker quick start:**
+```bash
+cp config.example.yaml config.yaml  # Edit with your keys
+npm run docker:build
+npm run docker:run
+```
+
+**Add to OpenCode config:**
+```bash
+# Run setup wizard and choose "Update OpenCode config automatically"
+npm run setup
+
+# Or manually edit ~/.config/opencode/opencode.json and add:
+{
+  "provider": {
+    "saros-proxy": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "Saros",
+      "options": {
+        "baseURL": "http://127.0.0.1:3000/zen/go/v1",
+        "apiKey": "not-used"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Security
+
+For vulnerability reporting, see [SECURITY.md](SECURITY.md).
+
+---
+
+## License
+
+[MIT](LICENSE) © 2026 Saros Contributors

package/dist/cli/opencode-config.d.ts

@@ -0,0 +1,28 @@
+/**
+ * opencode-config.ts — OpenCode client configuration management.
+ *
+ * Handles reading, merging, and writing the user's opencode.json
+ * to add or update the proxy provider configuration.
+ */
+/** Return the default opencode.json path for the current platform. */
+export declare function getDefaultOpencodeConfigPath(): string;
+export interface OpencodeConfigResult {
+    success: boolean;
+    path?: string;
+    created?: boolean;
+    error?: string;
+}
+/**
+ * Update or create the user's opencode.json with the proxy provider.
+ *
+ * @param port — The proxy port to use in baseURL
+ * @param options.configPath — Explicit path to opencode.json (optional)
+ * @returns Result object with success status and path
+ */
+export declare function updateOpencodeConfig(port: number, options?: {
+    configPath?: string;
+}): OpencodeConfigResult;
+/**
+ * Generate a manual configuration snippet that users can paste.
+ */
+export declare function generateManualConfigSnippet(port: number): string;