@tiflis-io/tiflis-code-tunnel 0.3.0

package/LICENSE

@@ -0,0 +1,100 @@
+# Functional Source License, Version 1.1 (No Future Conversion)
+
+## Abbreviation
+
+FSL-1.1-NC
+
+## Notice
+
+Copyright 2025 Roman Barinov <rbarinov@gmail.com>
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A "Competing
+Use" means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Commercial Licensing
+
+For commercial use that constitutes a Competing Use, you must obtain a separate
+commercial license from the Licensor.
+
+Contact: rbarinov@gmail.com
+
+## License Details
+
+| Field | Value |
+|-------|-------|
+| Licensor | Roman Barinov |
+| Software | Tiflis Code |
+| Use Grant | Any Permitted Purpose |

package/README.md

@@ -0,0 +1,285 @@
+# @tiflis/tiflis-code-tunnel
+
+<p align="center">
+  <img src="../../assets/branding/logo.svg" width="80" height="80" alt="Tiflis Code">
+</p>
+
+<p align="center">
+  <strong>WebSocket reverse proxy for Tiflis Code workstation connections</strong>
+</p>
+
+<p align="center">
+  <a href="#installation">Installation</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#configuration">Configuration</a> •
+  <a href="#docker">Docker</a> •
+  <a href="#reverse-proxy">Reverse Proxy</a>
+</p>
+
+---
+
+## Overview
+
+The Tunnel Server acts as a secure reverse proxy between mobile clients (iOS/watchOS) and workstations running the Tiflis Code workstation server. It enables remote access to your workstation without requiring a public IP address.
+
+```
+┌─────────────┐         ┌─────────────┐         ┌─────────────────┐
+│   Mobile    │◄───────►│   Tunnel    │◄───────►│   Workstation   │
+│  (iOS/Watch)│   WSS   │   Server    │   WS    │     Server      │
+└─────────────┘         └─────────────┘         └─────────────────┘
+```
+
+## Installation
+
+```bash
+# Using npm
+npm install @tiflis-io/tiflis-code-tunnel
+
+# Using pnpm
+pnpm add @tiflis-io/tiflis-code-tunnel
+```
+
+## Quick Start
+
+<p align="center">
+  <img src="../../assets/screenshots/tunnel/startup.png" alt="Tunnel Server Startup" width="700">
+</p>
+
+### 1. Set Environment Variables
+
+```bash
+# Required: API key for workstation registration (min 32 chars)
+export TUNNEL_REGISTRATION_API_KEY="your-secure-api-key-at-least-32-characters"
+
+# Optional
+export PORT=3001
+export LOG_LEVEL=info
+```
+
+### 2. Run the Server
+
+```bash
+# Create a working directory with config (avoid leading dot in name)
+mkdir -p ~/tiflis-tunnel && cd ~/tiflis-tunnel
+npm init -y
+npm install @tiflis-io/tiflis-code-tunnel
+
+# Create .env file with your configuration
+echo 'TUNNEL_REGISTRATION_API_KEY=your-secure-api-key-at-least-32-characters' > .env
+
+# Run with dotenv-cli
+npx dotenv-cli -e .env -- node node_modules/@tiflis-io/tiflis-code-tunnel/dist/main.js
+
+# Or set environment variables directly
+TUNNEL_REGISTRATION_API_KEY=your-secure-api-key-at-least-32-characters \
+node node_modules/@tiflis-io/tiflis-code-tunnel/dist/main.js
+
+# Development mode (from monorepo)
+pnpm dev
+```
+
+### 3. Verify It's Running
+
+```bash
+curl http://localhost:3001/health
+```
+
+## Configuration
+
+All configuration is done via environment variables:
+
+| Variable                      | Required | Default   | Description                                             |
+| ----------------------------- | -------- | --------- | ------------------------------------------------------- |
+| `TUNNEL_REGISTRATION_API_KEY` | ✅       | —         | API key for workstation registration (min 32 chars)     |
+| `PORT`                        | ❌       | `3001`    | HTTP/WebSocket port                                     |
+| `HOST`                        | ❌       | `0.0.0.0` | Host to bind to                                         |
+| `LOG_LEVEL`                   | ❌       | `info`    | Log level: `trace`, `debug`, `info`, `warn`, `error`    |
+| `TRUST_PROXY`                 | ❌       | `false`   | Set to `true` when behind a reverse proxy               |
+| `PUBLIC_BASE_URL`             | ❌       | auto      | Public WebSocket URL (e.g., `wss://tunnel.example.com`) |
+| `WS_PATH`                     | ❌       | `/ws`     | WebSocket endpoint path                                 |
+
+### Example `.env` File
+
+```bash
+NODE_ENV=production
+PORT=3001
+LOG_LEVEL=info
+TUNNEL_REGISTRATION_API_KEY=your-secure-api-key-at-least-32-characters
+
+# For reverse proxy setups
+TRUST_PROXY=true
+PUBLIC_BASE_URL=wss://tunnel.example.com
+```
+
+## Docker
+
+### Quick Start with Docker
+
+```bash
+docker run -d \
+  --name tiflis-tunnel \
+  -p 3001:3001 \
+  -e TUNNEL_REGISTRATION_API_KEY="your-api-key-here-32-chars-min!!" \
+  ghcr.io/tiflis-io/tiflis-code-tunnel:latest
+```
+
+### Docker Compose
+
+```yaml
+services:
+  tunnel:
+    image: ghcr.io/tiflis-io/tiflis-code-tunnel:latest
+    ports:
+      - "3001:3001"
+    environment:
+      NODE_ENV: production
+      LOG_LEVEL: info
+      TUNNEL_REGISTRATION_API_KEY: ${TUNNEL_REGISTRATION_API_KEY}
+    restart: unless-stopped
+```
+
+### Multi-Architecture Support
+
+The Docker image supports both architectures:
+
+- `linux/amd64` (x86_64)
+- `linux/arm64` (Apple Silicon, AWS Graviton, Raspberry Pi)
+
+## Reverse Proxy
+
+When deploying behind a reverse proxy with TLS termination:
+
+### Configuration
+
+```bash
+TRUST_PROXY=true
+PUBLIC_BASE_URL=wss://tunnel.example.com
+```
+
+### Nginx Example
+
+```nginx
+upstream tiflis_tunnel {
+    server 127.0.0.1:3001;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name tunnel.example.com;
+
+    ssl_certificate /path/to/cert.pem;
+    ssl_certificate_key /path/to/key.pem;
+
+    location /ws {
+        proxy_pass http://tiflis_tunnel;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_read_timeout 86400s;
+    }
+
+    location /health {
+        proxy_pass http://tiflis_tunnel;
+    }
+}
+```
+
+### Traefik with Docker Compose
+
+See `deploy/docker-compose.traefik.yml` for a complete example with automatic Let's Encrypt certificates.
+
+## API Endpoints
+
+| Endpoint   | Method    | Description                                 |
+| ---------- | --------- | ------------------------------------------- |
+| `/health`  | GET       | Detailed health check with connection stats |
+| `/healthz` | GET       | Simple liveness probe                       |
+| `/readyz`  | GET       | Readiness probe                             |
+| `/ws`      | WebSocket | Main WebSocket endpoint                     |
+
+### Health Check Response
+
+```json
+{
+  "status": "healthy",
+  "version": "0.1.0",
+  "uptime": 3600,
+  "connections": {
+    "workstations": 2,
+    "clients": 5
+  },
+  "timestamp": "2025-01-15T12:00:00.000Z"
+}
+```
+
+## Protocol
+
+The tunnel server implements the Tiflis Code WebSocket Protocol. See [PROTOCOL.md](../../PROTOCOL.md) for the full specification.
+
+### Key Message Types
+
+**Workstation Registration:**
+
+```json
+{
+  "type": "workstation.register",
+  "payload": {
+    "api_key": "your-api-key",
+    "name": "My MacBook Pro",
+    "auth_key": "client-auth-key",
+    "reconnect": true,
+    "previous_tunnel_id": "Z6q62aKz-F96"
+  }
+}
+```
+
+**Tunnel ID Persistence:**
+
+The tunnel server supports persistent `tunnel_id` values that survive tunnel server restarts:
+
+- **First registration**: Tunnel server generates a new `tunnel_id`
+- **Reconnection (same tunnel server)**: Workstation provides `previous_tunnel_id`, tunnel server restores it
+- **Reconnection (after tunnel restart)**: Workstation provides `previous_tunnel_id`, tunnel server allows reclaiming it if available
+
+This ensures workstations maintain stable identifiers even when the tunnel server is restarted.
+
+**Mobile Client Connection:**
+
+```json
+{
+  "type": "connect",
+  "payload": {
+    "tunnel_id": "abc123",
+    "auth_key": "client-auth-key",
+    "device_id": "device-uuid"
+  }
+}
+```
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/tiflis-io/tiflis-code.git
+cd tiflis-code/packages/tunnel
+
+# Install dependencies
+pnpm install
+
+# Run in development mode
+TUNNEL_REGISTRATION_API_KEY="dev-key-32-characters-minimum!!" pnpm dev
+
+# Run tests
+pnpm test
+
+# Build for production
+pnpm build
+```
+
+## License
+
+FSL-1.1-NC © [Roman Barinov](mailto:rbarinov@gmail.com)

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+
+export {  }