uplink-cli 0.1.26 → 0.1.28

package/docs/guides/QUICKSTART.md

@@ -0,0 +1,280 @@
+# Quick Start: Expose Your Localhost to the Internet
+
+This guide shows you how to expose a local development server to the internet using Uplink tunnels.
+
+## Prerequisites
+
+- Node.js installed
+- A local server running on a port (e.g., `localhost:3000`)
+- An API token (minted admin/user token; dev-token only for local SQLite dev)
+- Install the user CLI (pick one):
+  - Public npm (best UX once published):
+    ```bash
+    npm install -g uplink-cli
+    # or run without global install:
+    npx uplink-cli
+    ```
+  - Private repo via SSH (requires GitHub SSH access):
+    ```bash
+    npm install -g git+ssh://git@github.com/firstprinciplecode/agentcloud.git#master
+    ```
+  - Private repo via HTTPS with token in env (safer than embedding in URL):
+    ```bash
+    GITHUB_TOKEN=<your-github-pat-with-repo-scope> \
+      npm install -g https://github.com/firstprinciplecode/agentcloud.git#master
+    ```
+  - Prebuilt tarball (no git, no token):
+    ```bash
+    npm install -g ./uplink-cli-0.1.0.tgz
+    ```
+  
+## Get an API token
+
+- If you are an admin and have break-glass `ADMIN_TOKENS` on the server, mint a proper token and use that going forward:
+  ```bash
+  uplink admin tokens create --role admin --label "my-laptop"
+  export AGENTCLOUD_TOKEN=<printed-admin-token>
+  ```
+- If you are not an admin, ask an admin to mint a user token for you:
+  ```bash
+  uplink admin tokens create --role user --label "teammate"
+  ```
+- Keep tokens out of shell history; prefer env vars over inline CLI args.
+  
+Then set your token before running `uplink`:
+```bash
+export AGENTCLOUD_TOKEN=<your-token>
+uplink
+```
+
+**Security note:** do not paste tokens into command lines/URLs (they land in shell history). Use `GITHUB_TOKEN` env for private installs and rotate any PAT that was previously pasted.
+
+**Note:** The CLI connects to `https://api.uplink.spot` by default. To use a local API server, set:
+```bash
+export AGENTCLOUD_API_BASE=http://localhost:4000
+```
+
+## The Simplest Way (Recommended)
+
+### Step 1: Start Your Local Server
+
+Start your development server on any port:
+
+```bash
+# Example: Start a Node.js server
+npm start
+
+# Or start a Python server
+python3 -m http.server 3000
+
+# Or any other server - just make sure it's running!
+```
+
+**Verify it's working:** Open `http://localhost:3000` (or your port) in your browser.
+
+---
+
+### Step 2: Run Uplink and Start Tunnel
+
+**Important:** Run `uplink` on your **local machine** (where your dev server is running), not on the server!
+
+```bash
+# On your LOCAL machine, open the interactive menu
+uplink
+```
+
+Then:
+1. Select **"Manage Tunnels"** → **"Start Tunnel"**
+2. The system will scan for active servers on your **local machine**
+3. Use arrow keys to select the port your server is running on (or choose "Enter custom port")
+4. Press "Back" if you want to cancel
+5. Done! Your tunnel is created and started automatically
+
+**That's it!** You'll see your public URL like:
+```
+✓ Tunnel created and client started
+
+→ Public URL    https://abc123def456.t.uplink.spot
+→ Token         abc123def456
+→ Local port    3000
+
+Tunnel client running in background.
+Use "Stop Tunnel" to disconnect.
+```
+
+---
+
+## Alternative Methods
+
+### Method 2: Direct CLI Command
+
+If you know the port number:
+
+```bash
+# Set your API token (if not using default)
+export AGENTCLOUD_TOKEN=dev-token
+
+# Create tunnel and connect automatically
+npm run dev:cli -- dev --tunnel --port 3000
+```
+
+### Method 3: Manual Steps (Advanced)
+
+**3a. Create tunnel via API:**
+
+```bash
+curl -X POST https://api.uplink.spot/v1/tunnels \
+  -H "Authorization: Bearer dev-token" \
+  -H "Content-Type: application/json" \
+  -d '{"port": 3000}'
+```
+
+**Response:**
+```json
+{
+  "id": "tun_abc123...",
+  "token": "abc123def456",
+  "url": "https://abc123def456.t.uplink.spot",
+  "targetPort": 3000,
+  "status": "active"
+}
+```
+
+**3b. Start the tunnel client:**
+
+Copy the `token` from the response above, then run:
+
+```bash
+node scripts/tunnel/client-improved.js \
+  --token abc123def456 \
+  --port 3000 \
+  --ctrl tunnel.uplink.spot:7071
+```
+
+---
+
+## Complete Example
+
+Here's a complete example from start to finish:
+
+```bash
+# Terminal 1: Start your local server
+cd my-app
+npm start
+# Server running on http://localhost:3000
+
+# Terminal 2: Start tunnel (easiest way)
+uplink
+# Select "Manage Tunnels" → "Start Tunnel"
+# Choose port 3000 from the list (use arrow keys)
+# Done! Your tunnel URL is displayed
+
+# Or use direct command:
+export AGENTCLOUD_TOKEN=dev-token
+npm run dev:cli -- dev --tunnel --port 3000
+
+# Output:
+# ✓ Tunnel created and client started
+# → Public URL    https://abc123def456.t.uplink.spot
+# Open https://abc123def456.t.uplink.spot in your browser!
+```
+
+---
+
+## Environment Variables
+
+You can customize the tunnel behavior with environment variables:
+
+```bash
+# API endpoint (default: https://api.uplink.spot)
+export AGENTCLOUD_API_BASE=https://api.uplink.spot
+
+# Your API token (default: dev-token)
+export AGENTCLOUD_TOKEN=dev-token
+
+# Tunnel control server (default: tunnel.uplink.spot:7071)
+export TUNNEL_CTRL=tunnel.uplink.spot:7071
+
+# Tunnel domain (default: t.uplink.spot)
+export TUNNEL_DOMAIN=t.uplink.spot
+
+# Optional: show relay status in the menu (set if you want the banner)
+# Set these before running `uplink` locally:
+# RELAY_HEALTH_URL points to the relay /health endpoint
+# RELAY_INTERNAL_SECRET must match the relay/backend secret if set
+export RELAY_HEALTH_URL=http://t.uplink.spot:7070/health
+# export RELAY_INTERNAL_SECRET=<your-relay-secret>
+```
+
+### Ops notes (relay/backend)
+- Relay binds HTTP ingress to loopback by default: `TUNNEL_RELAY_HTTP_HOST=127.0.0.1`
+- Protect internal endpoints with a shared secret: `RELAY_INTERNAL_SECRET=<same-secret-on-backend>`
+- Set the same `RELAY_INTERNAL_SECRET` on the backend service so admin tunnel status works.
+- Admin-only menus/features require an admin token. Users with normal tokens only see their own tunnels/databases by default.
+
+---
+
+## Troubleshooting
+
+### "Connection refused" error
+- **Check:** Is your local server running on the specified port?
+- **Fix:** Start your server first, then create the tunnel
+
+### "Cannot connect to relay" error
+- **Check:** Is the relay server running?
+- **Fix:** Verify the `TUNNEL_CTRL` address is correct
+
+### Tunnel URL returns "Gateway timeout"
+- **Check:** Is the tunnel client still running?
+- **Fix:** Make sure the client process didn't exit. Restart it if needed.
+
+### "Tunnel client failed to register"
+- **Check:** Is the token correct?
+- **Fix:** Create a new tunnel and use the new token
+
+---
+
+## Stopping the Tunnel
+
+**If using CLI:** Press `Ctrl+C` in the terminal where the CLI is running.
+
+**If using manual client:** Press `Ctrl+C` in the terminal where the client is running.
+
+The tunnel will remain in the database but won't be accessible until you reconnect the client.
+
+---
+
+## Next Steps
+
+- **Multiple tunnels:** Create multiple tunnels for different ports
+- **Persistent tunnels:** Keep the client running to maintain the tunnel
+- **Production use:** Replace `dev-token` with a proper authentication token
+
+---
+
+## Quick Reference
+
+```bash
+# Easiest: Interactive menu (auto-detects ports)
+uplink
+# Select "Manage Tunnels" → "Start Tunnel"
+
+# Direct command (if you know the port)
+npm run dev:cli -- dev --tunnel --port <PORT>
+
+# Manual: Create tunnel via API
+curl -X POST https://api.uplink.spot/v1/tunnels \
+  -H "Authorization: Bearer dev-token" \
+  -H "Content-Type: application/json" \
+  -d '{"port": <PORT>}'
+
+# Manual: Connect client
+node scripts/tunnel/client-improved.js \
+  --token <TOKEN> \
+  --port <PORT> \
+  --ctrl tunnel.uplink.spot:7071
+
+# Test tunnel
+curl https://<TOKEN>.t.uplink.spot
+```
+

package/docs/guides/README.md

@@ -0,0 +1,22 @@
+# User Guides
+
+This directory contains user-facing documentation for Uplink.
+
+## Available Guides
+
+- **[Quick Start](QUICKSTART.md)** - Get started exposing your localhost to the internet
+- **[Manual](MANUAL.md)** - Complete feature reference and API documentation
+- **[Usage Guide](USAGE.md)** - Service usage examples and workflows
+- **[Tunnel Setup](TUNNEL_SETUP.md)** - Step-by-step tunnel setup instructions
+- **[Testing Guide](TESTING.md)** - How to test the system and new features
+
+## Quick Links
+
+- **New to Uplink?** Start with [Quick Start](QUICKSTART.md)
+- **Need detailed info?** Check the [Manual](MANUAL.md)
+- **Setting up tunnels?** See [Tunnel Setup](TUNNEL_SETUP.md)
+
+
+
+
+

package/docs/guides/TESTING.md

@@ -0,0 +1,408 @@
+# Testing Guide
+
+This guide covers how to test the Uplink system, including the new security and reliability features.
+
+## Quick Start
+
+### 1. Start the Backend API
+
+```bash
+# In one terminal
+npm run dev:api
+```
+
+The server will start on `http://localhost:4000` (or the port specified in `PORT` env var).
+
+### 2. Run Feature Tests
+
+```bash
+# Test new features (validation, rate limiting, logging, etc.)
+bash scripts/test-new-features.sh
+
+# Or test against production/staging
+AGENTCLOUD_API_BASE=https://api.uplink.spot \
+  AGENTCLOUD_TOKEN=your-token \
+  bash scripts/test-new-features.sh
+```
+
+### 3. Run Existing Smoke Tests
+
+```bash
+# All smoke tests
+npm run smoke:all
+
+# Individual tests
+npm run smoke:tunnel
+npm run smoke:db
+```
+
+## Testing New Features
+
+### Structured Logging
+
+**What to test:**
+- Logs are structured JSON in production
+- Pretty-printed in development
+- Audit events are logged
+
+**How to test:**
+1. Start the server: `npm run dev:api`
+2. Make some API calls (create tunnel, create token, etc.)
+3. Check console output for structured logs
+4. Look for audit events like:
+   - `event: "tunnel.created"`
+   - `event: "auth.success"`
+   - `event: "token.created"`
+
+**Example:**
+```bash
+# Start server
+npm run dev:api
+
+# In another terminal, create a tunnel
+curl -X POST http://localhost:4000/v1/tunnels \
+  -H "Authorization: Bearer dev-token" \
+  -H "Content-Type: application/json" \
+  -d '{"port": 3000}'
+
+# Check server logs for:
+# {"level":30,"time":1234567890,"event":"tunnel.created","userId":"...","tunnelId":"..."}
+```
+
+### Rate Limiting
+
+**What to test:**
+- API endpoints are rate limited
+- Different limits for different endpoints
+- Rate limit headers are returned
+
+**How to test:**
+```bash
+# Test general API rate limiting (100 req/15min)
+for i in {1..110}; do
+  curl -s -w "\n%{http_code}" http://localhost:4000/v1/tunnels \
+    -H "Authorization: Bearer dev-token" | tail -1
+  sleep 0.1
+done
+# Should eventually get 429
+
+# Test auth rate limiting (10 req/15min)
+for i in {1..15}; do
+  curl -s -w "\n%{http_code}" http://localhost:4000/v1/tunnels \
+    -H "Authorization: Bearer invalid-token" | tail -1
+done
+# Should get 429 after 10 requests
+
+# Test tunnel creation rate limiting (50 req/hour)
+for i in {1..55}; do
+  curl -s -X POST http://localhost:4000/v1/tunnels \
+    -H "Authorization: Bearer dev-token" \
+    -H "Content-Type: application/json" \
+    -d '{"port": 3000}' | tail -1
+done
+# Should get 429 after 50 requests
+```
+
+**Expected behavior:**
+- First requests succeed (200/201)
+- After limit, get 429 with error message
+- Rate limit info in response headers
+
+### Input Validation
+
+**What to test:**
+- Invalid inputs are rejected with 400
+- Clear error messages
+- Validation errors include field paths
+
+**How to test:**
+```bash
+# Missing required field
+curl -X POST http://localhost:4000/v1/tunnels \
+  -H "Authorization: Bearer dev-token" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+# Expected: 400 with validation error
+
+# Invalid type
+curl -X POST http://localhost:4000/v1/tunnels \
+  -H "Authorization: Bearer dev-token" \
+  -H "Content-Type: application/json" \
+  -d '{"port": "not-a-number"}'
+# Expected: 400 with validation error
+
+# Out of range
+curl -X POST http://localhost:4000/v1/tunnels \
+  -H "Authorization: Bearer dev-token" \
+  -H "Content-Type: application/json" \
+  -d '{"port": 99999}'
+# Expected: 400 with validation error
+
+# Valid input
+curl -X POST http://localhost:4000/v1/tunnels \
+  -H "Authorization: Bearer dev-token" \
+  -H "Content-Type: application/json" \
+  -d '{"port": 3000}'
+# Expected: 201 with tunnel data
+```
+
+**Expected response format:**
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid request body",
+    "details": {
+      "errors": [
+        {
+          "path": "port",
+          "message": "Expected number, received string"
+        }
+      ]
+    }
+  }
+}
+```
+
+### Security Headers
+
+**What to test:**
+- Helmet.js security headers are present
+- XSS protection headers
+- Content type options
+
+**How to test:**
+```bash
+curl -I http://localhost:4000/health
+
+# Should see headers like:
+# X-Content-Type-Options: nosniff
+# X-Frame-Options: DENY
+# X-XSS-Protection: 1; mode=block
+```
+
+### Configuration Validation
+
+**What to test:**
+- Server fails fast with clear errors for missing config
+- Validates on startup
+- Logs configuration summary
+
+**How to test:**
+```bash
+# Test with missing required config (if any)
+unset CONTROL_PLANE_DATABASE_URL
+npm run dev:api
+# Should fail with clear error message
+
+# Test with invalid config
+CONTROL_PLANE_DATABASE_URL="invalid://url" npm run dev:api
+# Should handle gracefully or fail with clear message
+```
+
+### Health Endpoints
+
+**What to test:**
+- `/health` - Basic health check
+- `/health/live` - Liveness probe (process running)
+- `/health/ready` - Readiness probe (can serve requests)
+
+**How to test:**
+```bash
+# Basic health
+curl http://localhost:4000/health
+# Expected: {"status":"ok","timestamp":"..."}
+
+# Liveness
+curl http://localhost:4000/health/live
+# Expected: {"status":"alive"}
+
+# Readiness (checks DB connection)
+curl http://localhost:4000/health/ready
+# Expected: {"status":"ready"} or {"status":"not ready"} if DB unavailable
+```
+
+### Audit Logging
+
+**What to test:**
+- Security events are logged
+- Token operations are audited
+- Tunnel operations are audited
+
+**How to test:**
+1. Perform security-sensitive operations:
+   ```bash
+   # Create token (if admin)
+   curl -X POST http://localhost:4000/v1/admin/tokens \
+     -H "Authorization: Bearer admin-token" \
+     -H "Content-Type: application/json" \
+     -d '{"role": "user"}'
+   
+   # Create tunnel
+   curl -X POST http://localhost:4000/v1/tunnels \
+     -H "Authorization: Bearer dev-token" \
+     -H "Content-Type: application/json" \
+     -d '{"port": 3000}'
+   
+   # Delete tunnel
+   curl -X DELETE http://localhost:4000/v1/tunnels/TUNNEL_ID \
+     -H "Authorization: Bearer dev-token"
+   ```
+
+2. Check server logs for audit entries:
+   ```json
+   {"level":30,"component":"audit","event":"token.created","userId":"...","tokenId":"..."}
+   {"level":30,"component":"audit","event":"tunnel.created","userId":"...","tunnelId":"..."}
+   {"level":30,"component":"audit","event":"tunnel.deleted","userId":"...","tunnelId":"..."}
+   ```
+
+## Manual Testing Checklist
+
+### Authentication & Authorization
+- [ ] Missing token returns 401
+- [ ] Invalid token returns 401
+- [ ] Valid token allows access
+- [ ] Admin-only endpoints require admin role
+- [ ] Users can only access their own resources
+
+### Rate Limiting
+- [ ] General API rate limit works (100/15min)
+- [ ] Auth rate limit works (10/15min)
+- [ ] Token creation rate limit works (20/hour)
+- [ ] Tunnel creation rate limit works (50/hour)
+- [ ] Rate limit headers are present
+- [ ] Rate limit errors are clear
+
+### Input Validation
+- [ ] Missing required fields return 400
+- [ ] Invalid types return 400
+- [ ] Out of range values return 400
+- [ ] Invalid formats return 400
+- [ ] Error messages are helpful
+
+### Logging
+- [ ] Structured logs in production
+- [ ] Pretty logs in development
+- [ ] Audit events are logged
+- [ ] Errors include stack traces
+- [ ] Request/response logging works
+
+### Security
+- [ ] Security headers are present
+- [ ] CORS is configured (if needed)
+- [ ] Input sanitization works
+- [ ] SQL injection prevention works
+
+### Reliability
+- [ ] Health endpoints work
+- [ ] Graceful shutdown works
+- [ ] Error handling is consistent
+- [ ] Configuration validation works
+
+## Integration Testing
+
+### End-to-End Tunnel Test
+
+```bash
+# 1. Start backend API
+npm run dev:api
+
+# 2. Create tunnel
+TUNNEL_RESPONSE=$(curl -s -X POST http://localhost:4000/v1/tunnels \
+  -H "Authorization: Bearer dev-token" \
+  -H "Content-Type: application/json" \
+  -d '{"port": 3000}')
+
+TUNNEL_ID=$(echo $TUNNEL_RESPONSE | grep -o '"id":"[^"]*' | cut -d'"' -f4)
+TOKEN=$(echo $TUNNEL_RESPONSE | grep -o '"token":"[^"]*' | cut -d'"' -f4)
+
+# 3. Start local server
+python3 -m http.server 3000 &
+
+# 4. Start tunnel client (if relay is running)
+node scripts/tunnel/client-improved.js \
+  --token $TOKEN \
+  --port 3000 \
+  --ctrl localhost:7071
+
+# 5. Test tunnel (if configured)
+curl https://${TOKEN}.t.uplink.spot
+
+# 6. Clean up
+curl -X DELETE http://localhost:4000/v1/tunnels/$TUNNEL_ID \
+  -H "Authorization: Bearer dev-token"
+```
+
+## Performance Testing
+
+### Load Testing
+
+```bash
+# Install Apache Bench if needed
+# macOS: brew install httpd
+# Linux: apt-get install apache2-utils
+
+# Test health endpoint
+ab -n 1000 -c 10 http://localhost:4000/health
+
+# Test authenticated endpoint
+ab -n 100 -c 5 -H "Authorization: Bearer dev-token" \
+  http://localhost:4000/v1/tunnels
+
+# Monitor rate limiting
+ab -n 200 -c 20 -H "Authorization: Bearer dev-token" \
+  http://localhost:4000/v1/tunnels
+# Should see some 429 responses
+```
+
+## Debugging
+
+### Check Logs
+
+```bash
+# Development - logs to console
+npm run dev:api
+
+# Production - check systemd logs
+journalctl -u backend-api -f
+
+# Check for specific events
+journalctl -u backend-api | grep "tunnel.created"
+journalctl -u backend-api | grep "auth.failed"
+```
+
+### Enable Debug Logging
+
+```bash
+LOG_LEVEL=debug npm run dev:api
+```
+
+### Test Configuration
+
+```bash
+# Test config validation
+node -e "require('./backend/src/utils/config.ts')"
+```
+
+## Continuous Testing
+
+Add to CI/CD pipeline:
+
+```bash
+# Run all tests
+npm run smoke:all
+
+# Run feature tests
+bash scripts/test-new-features.sh
+
+# Check for TypeScript errors
+npx tsc --noEmit
+
+# Check for linting errors (if configured)
+npm run lint
+```
+
+
+
+
+