ocremote 1.3.0

package/README.md

@@ -0,0 +1,277 @@
+# oc-remote companion
+
+Proceso Node sin dependencias externas (solo APIs nativas de Node 22+) que
+convierte un Mac en un host de **opencode** accesible desde la app iOS
+OpenCode Remote, con autenticacion por token, pairing por QR y notificaciones
+push opcionales.
+
+```
+ iOS ──token──► 0.0.0.0:4190  ┌──────────────┐
+                              │  oc-remote    │  inyecta Basic interno
+                              │  (proxy+auth) │──────────────► 127.0.0.1:4191
+                              └──────────────┘                 opencode serve
+                                QR / mDNS / ntfy                (solo loopback)
+```
+
+- El companion genera un **token propio** (32 hex) y lo guarda en
+  `~/.config/oc-remote/config.json` (0600). Solo rota con `--new-token`.
+- Arranca `opencode serve` en `127.0.0.1:<opencode-port>` con un **password
+  interno aleatorio distinto** (`OPENCODE_SERVER_PASSWORD`) que se regenera en
+  cada arranque y **nunca sale del Mac**: el companion lo inyecta en cada
+  peticion upstream. La red solo ve el token del companion.
+- Escucha en `0.0.0.0:<port>` y hace proxy streaming (SSE sin buffering) a
+  `http://127.0.0.1:<opencode-port>`.
+
+## Requisitos
+
+- macOS con Node 22 o superior (`node --version`).
+- El binario `opencode` (por defecto `~/.opencode/bin/opencode`).
+- Opcional: `tailscale` (acceso remoto), `ntfy` (push, no requiere instalar
+  nada en el Mac), `dns-sd` (viene con macOS).
+
+## Arranque manual
+
+```bash
+node companion/oc-remote.mjs --dir /ruta/al/proyecto
+```
+
+Salida (stderr): hostname, URLs candidatas (LAN, Tailscale, `--public-url`),
+token, y el **QR ASCII** con el deep link de pairing (`--print-qr` esta activo
+por defecto; `--no-print-qr` lo desactiva).
+
+Flags:
+
+| Flag | Default | Descripcion |
+|---|---|---|
+| `--dir <path>` | cwd | Directorio de proyecto que usa opencode (debe existir) |
+| `--port <n>` | 4190 | Puerto publico del companion |
+| `--opencode-port <n>` | 4191 | Puerto loopback del `opencode serve` interno |
+| `--host <ip>` | 0.0.0.0 | Interfaz de escucha |
+| `--token <str>` | — | Fija el token (se persiste en config.json) |
+| `--new-token` | — | Rota el token y lo persiste |
+| `--tunnel <mode>` | `auto` | `auto` \| `cloudflare` \| `tailscale` \| `none` (ver Acceso remoto) |
+| `--ntfy <topic\|url>` | — | Activa notificaciones push |
+| `--public-url <url>` | — | URL publica a anunciar (tu propio tunel; salta `--tunnel`) |
+| `--no-auth` | — | Desactiva auth (**peligroso**, avisa por stderr) |
+| `--opencode <path>` | `~/.opencode/bin/opencode` | Binario de opencode |
+| `--no-mdns` | mDNS activo | No publicar `_ocremote._tcp` por Bonjour |
+| `--print-qr` / `--no-print-qr` | on | Imprimir el QR al arrancar |
+| `--help` | | Ayuda |
+
+Variables de entorno: `OCREMOTE_CONFIG_DIR` (cambia `~/.config/oc-remote`),
+`OPENCODE_BIN` (alternativa a `--opencode`), `OCREMOTE_CLOUDFLARED` (ruta a un
+binario cloudflared propio), `OCREMOTE_TAILSCALE` (ruta al CLI `tailscale`; útil
+para tests).
+
+## Subcomandos
+
+| Comando | Qué hace |
+|---|---|
+| `oc-remote doctor` | Verifica toda la cadena: binario de opencode, token, puerto, auth, upstream, LaunchAgent, LAN, Tailscale/Funnel, endpoint público y ntfy. Salida `ok`/`FAIL` con el arreglo de cada fallo |
+| `oc-remote status` | Config, estado del LaunchAgent, endpoint actual (de `endpoint.json`) y prueba de auth |
+| `oc-remote restart` | `launchctl kickstart -k` del LaunchAgent |
+| `oc-remote logs` | Ruta del log y últimas 40 líneas |
+| `oc-remote funnel on\|off\|status` | Activa/desactiva el Funnel de Tailscale (la primera vez imprime el link de aprobación). El daemon en `auto` lo adopta solo |
+| `oc-remote version` | Versión |
+
+## Beacons de endpoint (auto-reparación)
+
+Con `--ntfy <topic|url>`, además de las notificaciones push el companion publica
+un **beacon** con el endpoint actual: al arrancar, cada vez que cambia la URL
+pública, y como heartbeat cada 5 minutos. Formato (mensaje ntfy con tag
+`ocremote-endpoint`):
+
+```json
+{"type":"endpoint","id":"1887884bfde3","name":"MacBook","version":"1.2.0",
+ "url":"https://mac.tailnet.ts.net","urls":[{"url":"...","label":"tunnel"}],
+ "provider":"funnel","auth":true,"port":4190,"ts":1789547880425}
+```
+
+- `id` es un **hash** del token (nunca el token): sirve para que la app ignore
+  beacons de otros Macs.
+- La app guarda esa lista de `urls` y prueba los candidatos en orden cuando la
+  URL actual falla; si todos fallan, consulta el último beacon del topic
+  (`/json?poll=1`) y se actualiza sola. El QR incluye el topic (`ntfy=...`) y la
+  lista inicial (`urls=...`), así que un solo escaneo lo configura todo.
+- El beacon también se escribe en `~/.config/oc-remote/endpoint.json` (0600) para
+  `oc-remote status/doctor`.
+
+## Watchdog
+
+- `opencode serve` se relanza solo si muere (backoff exponencial), y un chequeo
+  cada 30 s vía `/global/health` lo reinicia si queda colgado (3 fallos).
+- `cloudflared` se relanza solo; el Funnel se re-aplica si deja de servir.
+- El puerto del companion no cambia entre reinicios: la app solo necesita el
+  endpoint actual, no un puerto nuevo.
+- Con `auto`, el companion **se adapta en caliente**: si aparece un Funnel activo
+  pasa a la URL estable, y si desaparece vuelve al quick tunnel o a LAN/Tailscale.
+
+## Pairing
+
+1. **QR del terminal**: contiene el deep link
+   `ocremote://pair?v=1&name=<hostname>&url=http%3A%2F%2F<ip>%3A<port>&token=<token>`.
+2. **Pagina de pairing**: `http://127.0.0.1:4190/_ocremote/pair` (solo
+   loopback sin token; desde otra maquina requiere `?token=<token>`). Muestra
+   el QR como PNG, la URL, el token y botones de copiar.
+3. **Manual**: URL `http://<ip>:<port>` + token.
+
+La app envia `Authorization: Basic base64("opencode:"+token)` (llama "token" a
+la password) y para SSE puede usar `?auth_token=<base64(opencode:token)>`.
+El companion acepta ademas `Authorization: Bearer <token>` y `?token=<token>`.
+`token`/`auth_token` se eliminan de la query antes de reenviar al upstream.
+
+### Payload del QR
+
+```
+ocremote://pair?v=1&name=<hostname>&url=http%3A%2F%2F<ip>%3A<port>&token=<token>
+```
+
+| Parametro | Significado |
+|---|---|
+| `v` | Version del esquema de pairing (1) |
+| `name` | `os.hostname()` del Mac, URL-encoded |
+| `url` | Base URL a la que conectarse, URL-encoded |
+| `token` | Token del companion, URL-encoded |
+
+## Endpoints propios
+
+| Endpoint | Auth | Respuesta |
+|---|---|---|
+| `GET /_ocremote/health` | no | `{"ok":true}` (monitor local) |
+| `GET /_ocremote/status` | token | `{name, version, directory, uptime, port, opencodePort, clients, tunnel}` |
+| `GET /_ocremote/pair` | loopback o token | Pagina HTML con QR PNG, URL y token |
+
+Todo lo demas se proxya a opencode. Los `Upgrade`/WebSocket responden
+`501` (PTY fuera de alcance). Metodos fuera de
+`GET/HEAD/POST/PUT/PATCH/DELETE/OPTIONS` responden `405`. Errores de upstream
+responden `502` JSON.
+
+## Acceso remoto
+
+`--tunnel` decide como se anuncia la URL (y cual va dentro del QR):
+
+| Modo | Que hace |
+|---|---|
+| `auto` (default) | Si `cloudflared` ya esta instalado lo usa; si no, Tailscale si esta conectado; si no, solo LAN con un aviso |
+| `cloudflare` | Quick tunnel: descarga `cloudflared` la primera vez (a `~/.config/oc-remote/bin/`), arranca el tunel y publica la URL HTTPS |
+| `tailscale` | Anuncia la IP de Tailscale (URL estable) |
+| `none` | Solo LAN |
+
+### Cloudflare quick tunnel (cero configuracion)
+
+```bash
+oc-remote --dir ~/Projects/my-app --tunnel cloudflare
+# [oc-remote] cloudflare quick tunnel ready: https://calm-river-1234.trycloudflare.com
+```
+
+No necesita cuenta. La URL cambia en cada reinicio: para una URL fija usa
+Tailscale o un tunel con nombre propio. Si `cloudflared` muere, el companion lo
+relanza con backoff; cuando hay URL nueva reimprime el QR.
+
+### Tailscale (URL estable)
+
+Es una VPN mesh: el trafico va cifrado y solo tus dispositivos entran, sin
+abrir puertos ni exponer nada a Internet.
+
+```bash
+brew install --cask tailscale   # o la app de la Mac App Store
+tailscale up                    # login
+tailscale ip -4                 # 100.x.y.z
+```
+
+Con `--tunnel tailscale` (o `auto` sin cloudflared) el companion imprime
+`http://100.x.y.z:4190`. Desde el iPhone con Tailscale activo:
+
+- por IP: `http://100.x.y.z:4190`
+- por MagicDNS (mas comodo): `http://<nombre-maquina>.<tailnet>.ts.net:4190`
+
+Opcional: `--host <tailscale-ip>` para escuchar solo en la VPN. La primera vez
+macOS puede pedir permiso de firewall para `node`.
+
+### Tunel propio
+
+```bash
+cloudflared tunnel --url http://127.0.0.1:4190
+# imprime una URL https://xxxx.trycloudflare.com
+oc-remote --public-url https://xxxx.trycloudflare.com
+```
+
+Con `--public-url` esa URL se usa en el QR, en los logs y en el `click` de
+ntfy (y se salta `--tunnel`). El tunel expone el companion a Internet: el token
+es la unica barrera, con rate limit de 20 intentos fallidos por minuto y IP
+(respuesta `429 too_many_requests`). Prefiere Tailscale para uso diario.
+
+## ntfy (opcional)
+
+```bash
+node companion/oc-remote.mjs --ntfy ocremote-raul-a8f3k2
+```
+
+- `permission.asked` → `opencode: permission required` (priority 4, tags
+  `warning`, click a la URL).
+- `session.status busy` seguido de `session.idle` → `opencode: task finished`.
+- Se abre una conexion SSE propia a `/event` con el Basic interno; si falla,
+  se reintenta cada 5 s y nunca afecta al proxy.
+- Acepta un topic de ntfy.sh o una URL completa (self-hosted):
+  `--ntfy https://ntfy.midominio.dev/mi-topic`.
+- Los topics de ntfy.sh son publicos: usa uno largo y aleatorio.
+
+## Instalacion como LaunchAgent
+
+```bash
+bash companion/install.sh --dir /Users/raul/Desktop/Projects/opencode-remote
+bash companion/install.sh --port 4190 --token mi-token      # idempotente
+bash companion/install.sh --uninstall
+```
+
+Crea:
+
+- symlink `~/.local/bin/oc-remote` → `companion/oc-remote.mjs`
+- `~/Library/LaunchAgents/com.raul.ocremote.plist` (`KeepAlive`, `RunAtLoad`,
+  `WorkingDirectory`, `ThrottleInterval` 10 s, permisos 0600)
+- logs en `~/Library/Logs/oc-remote.log` (stdout y stderr)
+
+El QR y el token quedan en el log: `tail -f ~/Library/Logs/oc-remote.log`.
+`--no-load` genera los ficheros sin cargar el agente (util para inspeccionar
+el plist). No borra `~/.config/oc-remote/config.json` al desinstalar.
+
+## Seguridad
+
+- Token de 32 hex comparado con `crypto.timingSafeEqual`; el config se escribe
+  0600 (directorio 0700).
+- El opencode interno escucha solo en `127.0.0.1` con password aleatorio de 32
+  hex regenerado en cada arranque; la LAN no puede hablar con el directamente.
+- Sin TLS: no expongas el puerto a Internet directamente. Usa Tailscale
+  (recomendado) o un tunel con HTTPS.
+- `--no-auth` deja el control de opencode al alcance de cualquiera en la red:
+  usalo solo en loopback.
+- `GET /config/providers` y `/provider.env` exponen API keys de OpenCode a
+  quien tenga el token: tratalo como un secreto.
+- La pagina `/_ocremote/pair` solo se sirve sin token a clientes loopback.
+
+## Troubleshooting
+
+- `port 4190 is already in use`: cambia `--port` (o `--opencode-port`).
+  Comprueba con `lsof -nP -iTCP:4190 -sTCP:LISTEN`.
+- `401`: token distinto (rota con `--new-token` y vuelve a emparejar), o el
+  cliente manda `Bearer`/Basic mal formado. Prueba
+  `curl -H 'Authorization: Bearer <token>' http://127.0.0.1:4190/_ocremote/status`.
+- `opencode binary not found`: pasa `--opencode /ruta/al/opencode`.
+- `opencode did not become healthy within 30s`: mira los logs con prefijo
+  `[opencode]` en stderr; suele ser un puerto ocupado o falta de login.
+- El child muere: el companion lo relanza con backoff exponencial (1 s → 15 s).
+- mDNS: anuncio Bonjour `_ocremote._tcp.local` via `dns-sd -R` (el responder
+  del sistema). Comprueba con `dns-sd -B _ocremote._tcp local`; desactiva con
+  `--no-mdns` si no lo quieres. Si `dns-sd` no existe, solo avisa.
+- `node --test companion/test/`: en Node ≤ 22.13 el runner no expande
+  directorios, por eso `companion/test/package.json` apunta a `index.mjs`, que
+  importa la suite. Tambien puedes usar
+  `node --test companion/test/proxy.test.mjs`.
+
+## Limitaciones
+
+- Sin WebSocket/PTY (501), sin TLS, sin rate limiting, sin HTTP/2.
+- Los clientes SSE se cuentan en `status.clients` mientras la conexion sigue
+  abierta.
+- mDNS anuncia el servicio del companion (`_ocremote._tcp`), no el de opencode:
+  el `--mdns` de opencode no se usa porque anunciaria el puerto interno.

package/install.sh

@@ -0,0 +1,261 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+LABEL="com.raul.ocremote"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ENTRY="$SCRIPT_DIR/oc-remote.mjs"
+BIN_DIR="$HOME/.local/bin"
+PLIST="$HOME/Library/LaunchAgents/$LABEL.plist"
+LOG_PATH="$HOME/Library/Logs/oc-remote.log"
+PROJECT_DIR=""
+PORT="4190"
+TOKEN=""
+TUNNEL="auto"
+NTFY=""
+RELAY=""
+DEVICE_NAME=""
+NO_LOAD="0"
+UNINSTALL="0"
+
+usage() {
+  cat <<USAGE
+oc-remote installer
+
+Usage:
+  companion/install.sh [--dir <path>] [--port <n>] [--token <str>] [--tunnel <mode>] [--ntfy <topic>]
+                       [--relay <wss://url>] [--device-name <name>]
+  companion/install.sh --uninstall
+
+Options:
+  --dir <path>     Project directory opencode runs in (default: repo root)
+  --port <n>       Companion port (default: 4190)
+  --token <str>    Pairing token to persist (default: companion generates one)
+  --tunnel <mode>  Remote access: auto | funnel | cloudflare | tailscale | none (default: auto)
+                   funnel     stable public HTTPS URL via Tailscale Funnel (one-time approval)
+                   cloudflare public URL from anywhere with zero setup (downloads cloudflared)
+  --ntfy <topic>   ntfy topic for push notifications + endpoint beacons
+  --relay <url>    Relay v2 URL (wss://...) for anywhere access without tunnels
+  --device-name <name>  Name shown on the phone when pairing (default: hostname)
+  --no-load        Write the symlink and plist but do not load the LaunchAgent
+  --uninstall      Unload the LaunchAgent, remove the plist and the symlink
+  -h, --help       Show this help
+
+Files:
+  symlink   $BIN_DIR/oc-remote
+  plist     $PLIST
+  log       $LOG_PATH
+  config    ~/.config/oc-remote/config.json (0600, written by oc-remote)
+USAGE
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dir)
+      [[ $# -ge 2 ]] || { echo "error: --dir needs a value" >&2; exit 2; }
+      PROJECT_DIR="$2"
+      shift 2
+      ;;
+    --port)
+      [[ $# -ge 2 ]] || { echo "error: --port needs a value" >&2; exit 2; }
+      PORT="$2"
+      shift 2
+      ;;
+    --token)
+      [[ $# -ge 2 ]] || { echo "error: --token needs a value" >&2; exit 2; }
+      TOKEN="$2"
+      shift 2
+      ;;
+    --tunnel)
+      [[ $# -ge 2 ]] || { echo "error: --tunnel needs a value" >&2; exit 2; }
+      case "$2" in
+        auto|funnel|cloudflare|tailscale|none) TUNNEL="$2" ;;
+        *) echo "error: invalid --tunnel: $2 (expected auto | funnel | cloudflare | tailscale | none)" >&2; exit 2 ;;
+      esac
+      shift 2
+      ;;
+    --ntfy)
+      [[ $# -ge 2 ]] || { echo "error: --ntfy needs a value" >&2; exit 2; }
+      NTFY="$2"
+      shift 2
+      ;;
+    --relay)
+      [[ $# -ge 2 ]] || { echo "error: --relay needs a value" >&2; exit 2; }
+      RELAY="$2"
+      shift 2
+      ;;
+    --device-name)
+      [[ $# -ge 2 ]] || { echo "error: --device-name needs a value" >&2; exit 2; }
+      DEVICE_NAME="$2"
+      shift 2
+      ;;
+    --no-load)
+      NO_LOAD="1"
+      shift
+      ;;
+    --uninstall)
+      UNINSTALL="1"
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "error: unknown argument: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+UID_NUM="$(id -u)"
+DOMAIN="gui/$UID_NUM"
+
+if [[ "$UNINSTALL" == "1" ]]; then
+  if launchctl bootout "$DOMAIN/$LABEL" >/dev/null 2>&1; then
+    echo "unloaded LaunchAgent $LABEL"
+  elif [[ -f "$PLIST" ]] && launchctl unload "$PLIST" >/dev/null 2>&1; then
+    echo "unloaded LaunchAgent $LABEL (legacy launchctl unload)"
+  else
+    echo "LaunchAgent $LABEL was not loaded"
+  fi
+  rm -f "$PLIST"
+  rm -f "$BIN_DIR/oc-remote"
+  echo "removed $PLIST"
+  echo "removed $BIN_DIR/oc-remote"
+  echo "kept ~/.config/oc-remote/config.json (delete it manually to forget the token)"
+  exit 0
+fi
+
+if [[ -z "$PROJECT_DIR" ]]; then
+  PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+fi
+if [[ ! -d "$PROJECT_DIR" ]]; then
+  echo "error: directory not found: $PROJECT_DIR" >&2
+  exit 1
+fi
+PROJECT_DIR="$(cd "$PROJECT_DIR" && pwd)"
+
+if [[ ! -f "$ENTRY" ]]; then
+  echo "error: oc-remote.mjs not found next to install.sh" >&2
+  exit 1
+fi
+
+if [[ ! "$PORT" =~ ^[0-9]+$ ]] || (( PORT < 1 || PORT > 65535 )); then
+  echo "error: invalid port: $PORT" >&2
+  exit 1
+fi
+
+NODE_BIN="$(command -v node || true)"
+if [[ -z "$NODE_BIN" ]]; then
+  echo "error: node not found in PATH" >&2
+  exit 1
+fi
+
+xml_escape() {
+  local value="$1"
+  value="${value//&/&amp;}"
+  value="${value//</&lt;}"
+  value="${value//>/&gt;}"
+  printf '%s' "$value"
+}
+
+mkdir -p "$BIN_DIR" "$HOME/Library/LaunchAgents" "$HOME/Library/Logs"
+chmod +x "$ENTRY"
+ln -sfn "$ENTRY" "$BIN_DIR/oc-remote"
+
+{
+  echo '<?xml version="1.0" encoding="UTF-8"?>'
+  echo '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">'
+  echo '<plist version="1.0">'
+  echo '<dict>'
+  echo '  <key>Label</key>'
+  echo "  <string>$LABEL</string>"
+  echo '  <key>ProgramArguments</key>'
+  echo '  <array>'
+  echo "    <string>$(xml_escape "$NODE_BIN")</string>"
+  echo "    <string>$(xml_escape "$BIN_DIR/oc-remote")</string>"
+  echo '    <string>--dir</string>'
+  echo "    <string>$(xml_escape "$PROJECT_DIR")</string>"
+  echo '    <string>--port</string>'
+  echo "    <string>$PORT</string>"
+  echo '    <string>--tunnel</string>'
+  echo "    <string>$TUNNEL</string>"
+  if [[ -n "$NTFY" ]]; then
+    echo '    <string>--ntfy</string>'
+    echo "    <string>$(xml_escape "$NTFY")</string>"
+  fi
+  if [[ -n "$RELAY" ]]; then
+    echo '    <string>--relay</string>'
+    echo "    <string>$(xml_escape "$RELAY")</string>"
+  fi
+  if [[ -n "$DEVICE_NAME" ]]; then
+    echo '    <string>--device-name</string>'
+    echo "    <string>$(xml_escape "$DEVICE_NAME")</string>"
+  fi
+  if [[ -n "$TOKEN" ]]; then
+    echo '    <string>--token</string>'
+    echo "    <string>$(xml_escape "$TOKEN")</string>"
+  fi
+  echo '  </array>'
+  echo '  <key>WorkingDirectory</key>'
+  echo "  <string>$(xml_escape "$PROJECT_DIR")</string>"
+  echo '  <key>EnvironmentVariables</key>'
+  echo '  <dict>'
+  echo '    <key>PATH</key>'
+  echo "    <string>$(xml_escape "$(dirname "$NODE_BIN"):/opt/homebrew/bin:/usr/local/bin:$BIN_DIR:$HOME/.opencode/bin:/usr/bin:/bin:/usr/sbin:/sbin")</string>"
+  echo '  </dict>'
+  echo '  <key>RunAtLoad</key>'
+  echo '  <true/>'
+  echo '  <key>KeepAlive</key>'
+  echo '  <true/>'
+  echo '  <key>ThrottleInterval</key>'
+  echo '  <integer>10</integer>'
+  echo '  <key>StandardOutPath</key>'
+  echo "  <string>$(xml_escape "$LOG_PATH")</string>"
+  echo '  <key>StandardErrorPath</key>'
+  echo "  <string>$(xml_escape "$LOG_PATH")</string>"
+  echo '</dict>'
+  echo '</plist>'
+} > "$PLIST"
+chmod 600 "$PLIST"
+
+plutil -lint "$PLIST"
+
+if [[ "$NO_LOAD" == "1" ]]; then
+  echo "wrote $PLIST (not loaded)"
+  echo "wrote $BIN_DIR/oc-remote -> $ENTRY"
+  exit 0
+fi
+
+launchctl bootout "$DOMAIN/$LABEL" >/dev/null 2>&1 || true
+if ! launchctl bootstrap "$DOMAIN" "$PLIST" >/dev/null 2>&1; then
+  launchctl load -w "$PLIST"
+fi
+launchctl kickstart -k "$DOMAIN/$LABEL" >/dev/null 2>&1 || true
+
+echo "installed LaunchAgent $LABEL"
+echo "  binary: $BIN_DIR/oc-remote -> $ENTRY"
+echo "  plist:  $PLIST"
+echo "  log:    $LOG_PATH"
+echo "  port:   $PORT"
+echo "  tunnel: $TUNNEL"
+[[ -n "$RELAY" ]] && echo "  relay:  $RELAY"
+echo
+ENDPOINT_JSON="$HOME/.config/oc-remote/endpoint.json"
+for _ in $(seq 1 15); do
+  [[ -f "$ENDPOINT_JSON" ]] && break
+  sleep 1
+done
+if [[ -f "$ENDPOINT_JSON" ]]; then
+  ENDPOINT_URL="$(node -e "try{const e=require('$ENDPOINT_JSON');process.stdout.write(e.url||'')}catch{}" 2>/dev/null || true)"
+  if [[ -n "$ENDPOINT_URL" ]]; then
+    echo "endpoint: $ENDPOINT_URL"
+  fi
+fi
+echo "Pairing details (URL, token, QR) are in the log:"
+echo "  tail -f \"$LOG_PATH\""
+echo
+echo "Verify the whole chain with:  oc-remote doctor"
+echo "Restart the daemon with:      oc-remote restart"
+echo "Uninstall with:               $0 --uninstall"

package/lib/crypto.mjs

@@ -0,0 +1,146 @@
+import crypto from 'node:crypto'
+
+export const PROTOCOL_VERSION = 2
+export const CHANNEL_CONTROL = 0x00
+export const CHANNEL_OPEN = 0x01
+export const CHANNEL_SEALED = 0x02
+export const DIR_CLIENT = 0x01
+export const DIR_COMPANION = 0x02
+export const AAD = Buffer.from('ocremote-v2', 'utf8')
+
+export function b64(buffer) {
+  return Buffer.from(buffer).toString('base64url')
+}
+
+export function unb64(text) {
+  return Buffer.from(String(text), 'base64url')
+}
+
+export function frame(channel, session, payload) {
+  const out = Buffer.alloc(3 + payload.length)
+  out[0] = channel
+  out.writeUInt16BE(session, 1)
+  payload.copy(out, 3)
+  return out
+}
+
+export function parseFrame(data) {
+  const buffer = Buffer.from(data)
+  if (buffer.length < 3) return null
+  return {
+    channel: buffer[0],
+    session: buffer.readUInt16BE(1),
+    payload: buffer.subarray(3),
+  }
+}
+
+export function control(payload) {
+  return frame(CHANNEL_CONTROL, 0, Buffer.from(JSON.stringify(payload), 'utf8'))
+}
+
+export function hkdf(ikm, salt, info, length = 32) {
+  return Buffer.from(crypto.hkdfSync('sha256', ikm, salt, info, length))
+}
+
+export function sessionKey(pairKey, clientNonce, serverNonce, pairID) {
+  const salt = crypto.createHash('sha256').update(Buffer.concat([clientNonce, serverNonce, Buffer.from(pairID)])).digest()
+  return hkdf(pairKey, salt, 'ocremote-v2 session', 32)
+}
+
+export function inviteSessionKey(secret, clientNonce, serverNonce) {
+  const salt = crypto.createHash('sha256').update(Buffer.concat([clientNonce, serverNonce])).digest()
+  return hkdf(secret, salt, 'ocremote invite session', 32)
+}
+
+export function pairKeyFromInvite(secret, clientNonce, serverNonce) {
+  const salt = crypto.createHash('sha256').update(Buffer.concat([clientNonce, serverNonce])).digest()
+  return hkdf(secret, salt, 'ocremote pairKey', 32)
+}
+
+export function nonceFor(dir, counter) {
+  const nonce = Buffer.alloc(12)
+  nonce[0] = dir
+  let value = BigInt(counter)
+  for (let index = 11; index >= 1; index--) {
+    nonce[index] = Number(value & 0xffn)
+    value >>= 8n
+  }
+  return nonce
+}
+
+export function seal(key, dir, counter, plaintext) {
+  const cipher = crypto.createCipheriv('aes-256-gcm', key, nonceFor(dir, counter))
+  cipher.setAAD(AAD)
+  const body = Buffer.concat([cipher.update(plaintext), cipher.final()])
+  return Buffer.concat([body, cipher.getAuthTag()])
+}
+
+export function open(key, dir, counter, sealed) {
+  if (sealed.length < 16) throw new Error('sealed frame too short')
+  const tag = sealed.subarray(sealed.length - 16)
+  const body = sealed.subarray(0, sealed.length - 16)
+  const decipher = crypto.createDecipheriv('aes-256-gcm', key, nonceFor(dir, counter))
+  decipher.setAAD(AAD)
+  decipher.setAuthTag(tag)
+  return Buffer.concat([decipher.update(body), decipher.final()])
+}
+
+export function sealWire(key, dir, counter, plaintext) {
+  const header = Buffer.alloc(12)
+  header[0] = dir
+  let value = BigInt(counter)
+  for (let index = 11; index >= 1; index--) {
+    header[index] = Number(value & 0xffn)
+    value >>= 8n
+  }
+  return Buffer.concat([header, seal(key, dir, counter, plaintext)])
+}
+
+export function openWire(key, expectedDir, payload, minCounter = -1n) {
+  if (payload.length < 12 + 16) throw new Error('short sealed frame')
+  const dir = payload[0]
+  if (dir !== expectedDir) throw new Error('bad direction')
+  let counter = 0n
+  for (const byte of payload.subarray(1, 12)) counter = (counter << 8n) | BigInt(byte)
+  if (counter <= minCounter) throw new Error('replayed counter')
+  const plaintext = open(key, dir, counter, payload.subarray(12))
+  return { counter: Number(counter), plaintext }
+}
+
+export function generateIdentityKeys() {
+  const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519')
+  return {
+    publicRaw: exportRawPublic(publicKey),
+    privateKey,
+  }
+}
+
+export function exportRawPublic(publicKey) {
+  const der = publicKey.export({ type: 'spki', format: 'der' })
+  return der.subarray(der.length - 32)
+}
+
+export function importRawPublic(raw) {
+  const prefix = Buffer.from('302a300506032b6570032100', 'hex')
+  return crypto.createPublicKey({ key: Buffer.concat([prefix, Buffer.from(raw)]), format: 'der', type: 'spki' })
+}
+
+export function sign(privateKey, message) {
+  return crypto.sign(null, Buffer.from(message, 'utf8'), privateKey)
+}
+
+export function verify(rawPublic, signature, message) {
+  try {
+    return crypto.verify(null, Buffer.from(message, 'utf8'), importRawPublic(rawPublic), Buffer.from(signature))
+  } catch {
+    return false
+  }
+}
+
+export function deviceIDFromPublic(rawPublic) {
+  return crypto.createHash('sha256').update(rawPublic).digest('hex').slice(0, 32)
+}
+
+export function randomBytes(length) {
+  return crypto.randomBytes(length)
+}