@pi-chamber/web 0.3.0 → 0.3.2

package/server/lib/server/core-routes.js

@@ -479,6 +479,38 @@ export const registerAuthAndAccessRoutes = (app, dependencies) => {
     }
   };
 
+  const runWithPairingCreateAuth = async (req, res, next, handler) => {
+    try {
+      if (typeof uiAuthController.resolveAuthContext === 'function') {
+        const context = await uiAuthController.resolveAuthContext(req, res, {
+          allowClientAuth: true,
+          allowUrlToken: false,
+        });
+        if (context?.type === 'session') {
+          await handler(context);
+          return;
+        }
+        if (context?.type === 'client') {
+          const client = await clientRecordFromAuthContext(context);
+          // Trusted desktop clients (local or remote) may create short-lived
+          // pairing tickets scoped to this server/user. Mobile or other
+          // client kinds remain prohibited from creating pairing sessions.
+          if (client?.clientKind === 'desktop-local' || client?.clientKind === 'desktop') {
+            await handler({ ...context, client });
+            return;
+          }
+          return res.status(403).json({ error: 'Client tokens cannot create pairing sessions' });
+        }
+      }
+
+      await runWithUiAuth(req, res, next, async () => {
+        await handler({ type: 'session' });
+      }, { sessionOnly: true });
+    } catch (error) {
+      next(error);
+    }
+  };
+
   const clientIdFromAuthContext = (context) => {
     const raw = context?.client?.id || context?.clientId;
     return typeof raw === 'string' && raw.length > 0 ? raw : null;
@@ -811,7 +843,7 @@ export const registerAuthAndAccessRoutes = (app, dependencies) => {
   });
 
   app.post('/api/client-auth/pairing/sessions', express.json({ limit: '64kb' }), async (req, res, next) => {
-    await runWithClientCreateAuth(req, res, next, async (authContext) => {
+    await runWithPairingCreateAuth(req, res, next, async (authContext) => {
       const candidates = await pairingServerCandidates(req, {
         preferredServerUrl: req.body?.serverUrl,
         includeRelay: typeof req.body?.includeRelay === 'boolean' ? req.body.includeRelay : undefined,
@@ -877,7 +909,7 @@ export const registerAuthAndAccessRoutes = (app, dependencies) => {
 
   // Direct transports the server can be reached on (for the create-device dialog).
   app.get('/api/client-auth/pairing/transports', async (req, res, next) => {
-    await runWithClientCreateAuth(req, res, next, async () => {
+    await runWithPairingCreateAuth(req, res, next, async () => {
       res.setHeader('Cache-Control', 'no-store');
       res.json(getPairingTransports(req));
     });
@@ -886,7 +918,7 @@ export const registerAuthAndAccessRoutes = (app, dependencies) => {
   // Pending pairing sessions (link created, device not yet connected) for the
   // "pending devices" list. Secrets are never included.
   app.get('/api/client-auth/pairing/sessions', async (req, res, next) => {
-    await runWithClientCreateAuth(req, res, next, async () => {
+    await runWithPairingCreateAuth(req, res, next, async () => {
       const pending = await clientPairingRuntime.listPendingSessions();
       res.setHeader('Cache-Control', 'no-store');
       res.json({ pending });
@@ -894,7 +926,7 @@ export const registerAuthAndAccessRoutes = (app, dependencies) => {
   });
 
   app.delete('/api/client-auth/pairing/sessions/:id', async (req, res, next) => {
-    await runWithClientCreateAuth(req, res, next, async () => {
+    await runWithPairingCreateAuth(req, res, next, async () => {
       const result = await clientPairingRuntime.cancelPairingSession(req.params?.id);
       if (!result.cancelled) {
         return res.status(404).json({ cancelled: false, error: 'Pairing session not found' });

package/server/lib/server/tunnel-service.DOCUMENTATION.md

@@ -0,0 +1,74 @@
+# Cloudflare Tunnel Service
+
+PiChamber exposes a PiChamber-hosted Cloudflare Tunnel that lets a browser or mobile client reach a private PiChamber server without opening inbound ports. The server dials outbound to Cloudflare with `cloudflared`; the public hostname then proxies to the local PiChamber HTTP endpoint.
+
+## Modes
+
+- **Quick** (`quick`): ephemeral `*.trycloudflare.com` URL, no account required, best-effort. Uses `cloudflared tunnel --url http://127.0.0.1:<port>`. Good for demos, not for production (no SLA, no SSE guarantees).
+- **Managed Remote** (`managed-remote`): persistent hostname backed by a Cloudflare Tunnel token. Requires `token` (from `cloudflared tunnel create` / dashboard) and `hostname` (e.g. `pichamber.example.com`). Uses `cloudflared tunnel run --token-file ...` and stores the token on disk with `0600`.
+- **Managed Local** (`managed-local`): uses a local `config.yml` (`~/.cloudflared/config.yml` by default) whose `ingress` hostname is proxied. Uses `cloudflared tunnel --config <path> run`.
+
+Quick is the default when no hostname/token is supplied.
+
+## Server component
+
+`createTunnelService({ dataDir, getPort, tunnelAuthController })` owns the tunnel child process and its public URL. It checks `cloudflared` availability via `checkCloudflaredAvailable` (plus `getTunnelDependencyInstallInfo` for the install command), validates mode inputs before touching the binary, and redacts tokens in every response.
+
+- `GET /api/pichamber/tunnel/check` – availability + install help
+- `GET /api/pichamber/tunnel/status` – active, url, mode, bootstrap token presence, managed-remote token presence (boolean only), hostname, sessions, localPort
+- `POST /api/pichamber/tunnel/start` – body `{ mode, token, hostname, configPath }`
+- `POST /api/pichamber/tunnel/stop` – stops the child and clears `tunnelAuthController`
+- `PUT /api/pichamber/tunnel/managed-remote-token` – stores token/hostname for later starts
+- `GET /api/pichamber/tunnel/doctor` – status + check for diagnostics
+
+All routes are behind `uiAuthController.requireAuth`, so a bearer client or UI session is required; anonymous callers get `401`.
+
+The service sets `tunnelAuthController.setActiveTunnel` and issues a one-time bootstrap token (`/connect?t=...`) when the tunnel becomes active. Stopping clears it. The bootstrap token is `HttpOnly`, short-lived (30 min), and revoked when the tunnel is replaced or stopped.
+
+Remote traffic is still authenticated by `tunnelAuthController` and `uiAuthController`; the tunnel only provides reachability, not authorization. `isSecureRequest` (X-Forwarded-Proto) and `isRequestOriginAllowed` continue to enforce origin and WebSocket upgrade checks even when traffic arrives via the tunnel.
+
+## Secret handling
+
+- Tokens are written to `<dataDir>/cloudflare-tunnel-token.json` with `0600`; the hostname is stored alongside so `status` can report it without exposing the token.
+- `status` never returns the raw token, only `hasManagedRemoteTunnelToken: boolean` and the hostname.
+- Logs and error messages use `redactToken` (`abcd***wxyz`).
+- `cloudflared` stdout/stderr is drained but not logged with token material.
+
+## Systemd on Linux remote servers
+
+The tunnel child is normally supervised by the PiChamber server process (it dies when the server stops, and `stop` kills `SIGINT`). On a Linux remote server the same `cloudflared` can be run as a managed systemd service if the operator prefers:
+
+```
+# /etc/systemd/system/pichamber-cloudflared.service
+[Unit]
+Description=PiChamber Cloudflare Tunnel
+After=network-online.target
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/cloudflared tunnel run --token-file /var/lib/pichamber/cloudflare-tunnel-token
+Restart=always
+
+[Install]
+WantedBy=multi-user.target
+```
+
+The PiChamber `pichamber.service` itself already supports both user (`~/.config/systemd/user/pichamber.service`, `systemctl --user`) and system (`/etc/systemd/system/pichamber.service`, `systemctl`) scopes; the tunnel service follows the same scope so a root VPS gets a system unit that works immediately after install without `loginctl enable-linger`.
+
+## Upgrade considerations
+
+`pichamber update` detects the owning package manager, upgrades the global package, and restarts the relevant systemd service (`systemctl --user restart pichamber.service` or `systemctl restart pichamber.service` when running as root). The tunnel token file and PiChamber `pi/settings.json` sidecar are preserved across upgrades because they live under `PICHAMBER_DATA_DIR` (or `~/.pichamber`), not in the package directory. A Docker deployment is not upgraded in-place; it must be redeployed via `docker pull`.
+
+## Testing
+
+- `tunnel-service.test.js` covers validation (missing token/hostname, unsupported mode), status shape, secret redaction, and that `missing_dependency` is reported when `cloudflared` is absent.
+- Integration smoke against a real `cloudflared` binary is manual: install `cloudflared`, run `pichamber serve`, `curl /api/pichamber/tunnel/check`, start a quick tunnel, verify `status.url` appears and `curl -H "Host: $url-host"` reaches the server through the tunnel with `Authorization` still required.
+
+## Cloudflare permissions for API-token flow
+
+If the operator wants PiChamber to create a tunnel automatically (rather than pasting a token), the Cloudflare API token needs:
+
+- `Zone:Read`, `DNS:Edit` on the zone that will host the hostname
+- `Account:Cloudflare Tunnel:Edit` (to create/list tunnels)
+
+PiChamber never asks for the Cloudflare account password. The manual token flow is the default; the API-token flow is an optional convenience that calls `https://api.cloudflare.com/client/v4/accounts/{accountId}/cfd_tunnel` with the scoped token. Secrets are still stored with `0600` and never returned in API responses.

package/server/lib/server/tunnel-service.js

@@ -0,0 +1,228 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import {
+  checkCloudflaredAvailable,
+  startCloudflareQuickTunnel,
+  startCloudflareManagedRemoteTunnel,
+  startCloudflareManagedLocalTunnel,
+} from '../cloudflare-tunnel.js';
+import { getTunnelDependencyInstallInfo } from '../tunnels/install-help.js';
+import { TUNNEL_PROVIDER_CLOUDFLARE } from '../tunnels/types.js';
+
+const TUNNEL_STATE_FILE = 'cloudflare-tunnel-state.json';
+const TUNNEL_TOKEN_FILE = 'cloudflare-tunnel-token.json';
+
+const sanitizeToken = (value) => {
+  if (typeof value !== 'string') return '';
+  return value.trim();
+};
+
+const redactToken = (value) => {
+  if (!value || typeof value !== 'string') return '';
+  if (value.length <= 8) return '***';
+  return `${value.slice(0, 4)}***${value.slice(-4)}`;
+};
+
+export const createTunnelService = ({
+  dataDir,
+  getPort,
+  tunnelAuthController,
+  getServerLabel = () => 'PiChamber',
+} = {}) => {
+  const statePath = path.join(dataDir, TUNNEL_STATE_FILE);
+  const tokenPath = path.join(dataDir, TUNNEL_TOKEN_FILE);
+  let activeController = null;
+  let activePublicUrl = null;
+  let activeMode = null;
+  let bootstrapToken = null;
+  let bootstrapExpiresAt = null;
+
+  const readTokenStore = () => {
+    try {
+      const raw = fs.readFileSync(tokenPath, 'utf8');
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed.token === 'string' && typeof parsed.hostname === 'string') {
+        return parsed;
+      }
+    } catch {}
+    return null;
+  };
+
+  const writeTokenStore = (token, hostname) => {
+    try {
+      fs.mkdirSync(path.dirname(tokenPath), { recursive: true, mode: 0o700 });
+      fs.writeFileSync(tokenPath, JSON.stringify({ token, hostname }), { mode: 0o600 });
+    } catch {}
+  };
+
+  const clearTokenStore = () => {
+    try { fs.unlinkSync(tokenPath); } catch {}
+  };
+
+  const getStatus = async () => {
+    const hasManagedRemoteTunnelToken = Boolean(readTokenStore()?.token);
+    const active = Boolean(activeController && activePublicUrl);
+    const providerMetadata = active ? { mode: activeMode } : null;
+    const hasBootstrapToken = Boolean(bootstrapToken && bootstrapExpiresAt && bootstrapExpiresAt > Date.now());
+    return {
+      active,
+      url: activePublicUrl,
+      mode: activeMode,
+      provider: TUNNEL_PROVIDER_CLOUDFLARE,
+      providerMetadata,
+      hasManagedRemoteTunnelToken,
+      managedRemoteTunnelHostname: readTokenStore()?.hostname ?? null,
+      hasBootstrapToken,
+      bootstrapExpiresAt: hasBootstrapToken ? bootstrapExpiresAt : null,
+      activeTunnelMode: activeMode,
+      activeSessions: tunnelAuthController?.listTunnelSessions?.() ?? [],
+      localPort: typeof getPort === 'function' ? getPort() : null,
+      policy: 'tunnel-gated',
+      ttlConfig: { bootstrapTtlMs: 30 * 60 * 1000, sessionTtlMs: 8 * 60 * 60 * 1000 },
+    };
+  };
+
+  const check = async () => {
+    const result = await checkCloudflaredAvailable();
+    if (result.available) {
+      return {
+        available: true,
+        provider: TUNNEL_PROVIDER_CLOUDFLARE,
+        version: result.version,
+        dependency: 'cloudflared',
+        installCommand: null,
+        platform: process.platform,
+        message: null,
+      };
+    }
+    const installInfo = getTunnelDependencyInstallInfo(TUNNEL_PROVIDER_CLOUDFLARE, process.platform);
+    return {
+      available: false,
+      provider: TUNNEL_PROVIDER_CLOUDFLARE,
+      version: null,
+      dependency: installInfo.dependency ?? 'cloudflared',
+      installCommand: installInfo.installCommand ?? installInfo.message,
+      platform: process.platform,
+      message: installInfo.message,
+    };
+  };
+
+  const start = async (options = {}) => {
+    const mode = typeof options.mode === 'string' ? options.mode : 'quick';
+    const hostname = sanitizeToken(options.hostname);
+    const token = sanitizeToken(options.token);
+
+    // Validate mode-specific inputs before checking binary availability so the
+    // user gets a actionable validation error even when cloudflared is missing.
+    if (mode === 'managed-remote') {
+      if (!token) {
+        const error = new Error('Managed remote tunnel token is required');
+        error.code = 'validation_error';
+        throw error;
+      }
+      if (!hostname) {
+        const error = new Error('Managed remote tunnel hostname is required');
+        error.code = 'validation_error';
+        throw error;
+      }
+    } else if (mode !== 'quick' && mode !== 'managed-local') {
+      const error = new Error(`Unsupported tunnel mode: ${mode}`);
+      error.code = 'mode_unsupported';
+      throw error;
+    }
+
+    if (activeController) {
+      await stop();
+    }
+
+    const availability = await checkCloudflaredAvailable();
+    if (!availability.available) {
+      const installInfo = getTunnelDependencyInstallInfo(TUNNEL_PROVIDER_CLOUDFLARE, process.platform);
+      const error = new Error(installInfo.message);
+      error.code = 'missing_dependency';
+      throw error;
+    }
+
+    const port = typeof getPort === 'function' ? getPort() : null;
+    const originUrl = port ? `http://127.0.0.1:${port}` : undefined;
+
+    let controller;
+    if (mode === 'quick') {
+      controller = await startCloudflareQuickTunnel({ originUrl });
+    } else if (mode === 'managed-remote') {
+      controller = await startCloudflareManagedRemoteTunnel({ token, hostname });
+      writeTokenStore(token, hostname);
+    } else if (mode === 'managed-local') {
+      const configPath = typeof options.configPath === 'string' ? options.configPath : undefined;
+      controller = await startCloudflareManagedLocalTunnel({ configPath, hostname });
+    } else {
+      const error = new Error(`Unsupported tunnel mode: ${mode}`);
+      error.code = 'mode_unsupported';
+      throw error;
+    }
+
+    activeController = controller;
+    activePublicUrl = controller.getPublicUrl?.() ?? (mode !== 'quick' ? `https://${hostname}` : null);
+    activeMode = mode;
+
+    if (tunnelAuthController && activePublicUrl) {
+      const tunnelId = crypto.randomUUID();
+      tunnelAuthController.setActiveTunnel({ tunnelId, publicUrl: activePublicUrl, mode });
+      try {
+        const issued = tunnelAuthController.issueBootstrapToken({ ttlMs: 30 * 60 * 1000 });
+        bootstrapToken = issued.token;
+        bootstrapExpiresAt = issued.expiresAt;
+      } catch {}
+    }
+
+    return {
+      ok: true,
+      url: activePublicUrl,
+      mode: activeMode,
+      provider: TUNNEL_PROVIDER_CLOUDFLARE,
+      providerMetadata: controller.getResolvedHostname ? { resolvedHostname: controller.getResolvedHostname() } : null,
+      connectUrl: bootstrapToken && activePublicUrl ? `${activePublicUrl.replace(/\/$/, '')}/connect?t=${encodeURIComponent(bootstrapToken)}` : null,
+      bootstrapExpiresAt,
+    };
+  };
+
+  const stop = async () => {
+    if (activeController?.stop) {
+      try { activeController.stop(); } catch {}
+    }
+    if (activeController?.process?.kill) {
+      try { activeController.process.kill('SIGINT'); } catch {}
+    }
+    activeController = null;
+    activePublicUrl = null;
+    activeMode = null;
+    bootstrapToken = null;
+    bootstrapExpiresAt = null;
+    if (tunnelAuthController) {
+      try { tunnelAuthController.clearActiveTunnel(); } catch {}
+    }
+    return { ok: true };
+  };
+
+  const saveManagedRemoteToken = async ({ token, hostname, presetName }) => {
+    const cleanToken = sanitizeToken(token);
+    const cleanHostname = sanitizeToken(hostname);
+    if (!cleanToken || !cleanHostname) {
+      const error = new Error('Token and hostname are required');
+      error.code = 'validation_error';
+      throw error;
+    }
+    writeTokenStore(cleanToken, cleanHostname);
+    return { ok: true };
+  };
+
+  return {
+    getStatus,
+    check,
+    start,
+    stop,
+    saveManagedRemoteToken,
+    _internals: { getActiveController: () => activeController, redactToken },
+  };
+};

package/server/lib/server/tunnel-service.test.js

@@ -0,0 +1,61 @@
+import { describe, expect, it, beforeEach, afterEach, vi } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { mkdtemp, rm } from 'node:fs/promises';
+
+import { createTunnelService } from './tunnel-service.js';
+
+const makeDataDir = async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), 'pichamber-tunnel-test-'));
+  return dir;
+};
+
+describe('tunnel service', () => {
+  let dataDir;
+
+  beforeEach(async () => {
+    dataDir = await makeDataDir();
+  });
+
+  afterEach(async () => {
+    await rm(dataDir, { recursive: true, force: true });
+  });
+
+  it('validates managed-remote mode requires token and hostname', async () => {
+    const service = createTunnelService({ dataDir, getPort: () => 3000, tunnelAuthController: { setActiveTunnel: () => {}, clearActiveTunnel: () => {}, issueBootstrapToken: () => ({ token: 't', expiresAt: Date.now() + 1000 }), listTunnelSessions: () => [] } });
+    await expect(service.start({ mode: 'managed-remote', token: '', hostname: '' })).rejects.toMatchObject({ code: 'validation_error' });
+    await expect(service.start({ mode: 'managed-remote', token: 'tok', hostname: '' })).rejects.toMatchObject({ code: 'validation_error' });
+  });
+
+  it('returns status with required fields and handles missing cloudflared gracefully', async () => {
+    const service = createTunnelService({ dataDir, getPort: () => 3000, tunnelAuthController: { listTunnelSessions: () => [] } });
+    const status = await service.getStatus();
+    expect(status).toHaveProperty('active');
+    expect(status).toHaveProperty('url');
+    expect(status).toHaveProperty('mode');
+    expect(typeof status.active).toBe('boolean');
+  });
+
+  it('does not expose secrets in status or logs', async () => {
+    const service = createTunnelService({ dataDir, getPort: () => 3000, tunnelAuthController: { listTunnelSessions: () => [] } });
+    await service.saveManagedRemoteToken({ token: 'secret-token-12345', hostname: 'example.trycloudflare.com' });
+    const status = await service.getStatus();
+    const serialized = JSON.stringify(status);
+    expect(serialized).not.toContain('secret-token-12345');
+    expect(status.hasManagedRemoteTunnelToken).toBe(true);
+    expect(status.managedRemoteTunnelHostname).toBe('example.trycloudflare.com');
+  });
+
+  it('redacts tokens when formatting for display', async () => {
+    const service = createTunnelService({ dataDir, getPort: () => 3000, tunnelAuthController: { listTunnelSessions: () => [] } });
+    const redacted = service._internals.redactToken('my-super-secret-token-value');
+    expect(redacted).not.toContain('super-secret');
+    expect(redacted.length).toBeGreaterThan(0);
+  });
+
+  it('handles unsupported mode with clear error', async () => {
+    const service = createTunnelService({ dataDir, getPort: () => 3000, tunnelAuthController: { setActiveTunnel: () => {}, clearActiveTunnel: () => {}, issueBootstrapToken: () => ({ token: 't', expiresAt: Date.now() + 1000 }), listTunnelSessions: () => [] } });
+    await expect(service.start({ mode: 'unknown-mode' })).rejects.toThrow('Unsupported tunnel mode');
+  });
+});

package/server/lib/ui-auth/DOCUMENTATION.md

@@ -7,6 +7,8 @@ Trusted-device access has one durable credential model: a remote client bearer t
 
 Pairing v2 is implemented by `packages/web/server/lib/client-auth/pairing.js`. It stores short-lived one-time pairing sessions with hashed secrets, exposes create/cancel/redeem routes under `/api/client-auth/pairing/*`, and redeems a valid pairing secret into the same remote client token used by password/passkey trusted-device flows.
 
+Browser WebSocket clients mint a 60-second `oc_url_token` through the authenticated `/auth/url-token` route because the WebSocket constructor cannot attach an Authorization header. The token is accepted only for the explicit WebSocket allowlist, currently `/api/terminal/ws`; ordinary API routes and unknown upgrade paths reject it. The token resolves to the UI session or remote-client identity that minted it.
+
 ## Entrypoints and structure
 - `packages/web/server/lib/ui-auth/ui-auth.js`: UI auth controller runtime, cookie/session issuance, rate limiting, and auth route handlers.
 - `packages/web/server/lib/ui-auth/ui-passkeys.js`: passkey store and WebAuthn registration/authentication verification helpers.

package/server/lib/ui-auth/ui-auth.js

@@ -293,7 +293,11 @@ const isWebSocketUpgrade = (req) => {
 
 const isUrlAuthReadableHttpPath = (pathname) => pathname === '/api/pi/events';
 
-const isUrlAuthWebSocketPath = () => false;
+const URL_AUTH_WEBSOCKET_PATHS = new Set([
+  '/api/terminal/ws',
+]);
+
+const isUrlAuthWebSocketPath = (pathname) => URL_AUTH_WEBSOCKET_PATHS.has(pathname);
 
 const canUseUrlAuthTokenForRequest = (req) => {
   const method = typeof req?.method === 'string' ? req.method.toUpperCase() : 'GET';

package/server/lib/ui-auth/ui-auth.test.js

@@ -182,6 +182,23 @@ describe('ui auth client credential seam', () => {
     expect(await auth.ensureSessionToken(urlReq, urlRes)).toBe('client:device-1');
     expect(await auth.resolveAuthContext(urlReq, urlRes, { allowUrlToken: false })).toBe(null);
 
+    const terminalWsReq = {
+      method: 'GET',
+      path: '/api/terminal/ws',
+      url: `/api/terminal/ws?oc_url_token=${encodeURIComponent(urlToken)}`,
+      headers: { connection: 'Upgrade', upgrade: 'websocket' },
+    };
+    const terminalWsRes = createResponse();
+    expect(await auth.ensureSessionToken(terminalWsReq, terminalWsRes)).toBe('client:device-1');
+
+    const arbitraryWsReq = {
+      method: 'GET',
+      path: '/api/not-allowed/ws',
+      url: `/api/not-allowed/ws?oc_url_token=${encodeURIComponent(urlToken)}`,
+      headers: { connection: 'Upgrade', upgrade: 'websocket' },
+    };
+    expect(await auth.ensureSessionToken(arbitraryWsReq, createResponse())).toBe(null);
+
     const arbitraryGetReq = { method: 'GET', path: '/api/config/settings', url: `/api/config/settings?oc_url_token=${encodeURIComponent(urlToken)}`, headers: { accept: 'application/json' } };
     const arbitraryGetRes = createResponse();
     let arbitraryGetCalled = false;