@apocaliss92/nodelink-js 0.1.9 → 0.1.17

package/README.md

@@ -1,12 +1,12 @@
-<p align="center">
-  <img src="assets/icon.png" alt="nodelink.js" width="128" height="128">
-</p>
-
-<h1 align="center">nodelink.js</h1>
-
-<p align="center">
-  A TypeScript library for interacting with Reolink IP cameras and NVRs using the proprietary Baichuan protocol and CGI API.
-</p>
+<table>
+  <tr>
+    <td><img src="app/client/public/icon-512x512.png" alt="nodelink.js" width="256" height="256"></td>
+    <td>
+      <h1>nodelink.js</h1>
+      <p>A TypeScript library for interacting with Reolink IP cameras and NVRs using the proprietary Baichuan protocol and CGI API.</p>
+    </td>
+  </tr>
+</table>
 
 ## Credits
 
@@ -30,6 +30,254 @@ This library is inspired by and based on the reverse engineering work done by:
 
 ---
 
+## 🖥️ Manager UI (Web Dashboard)
+
+The library includes a **complete web-based management interface** for easy camera configuration and streaming control without writing code.
+
+<p align="center">
+  <b>Features:</b>
+</p>
+
+- 🎛️ **Camera Management** - Add, configure, and monitor multiple cameras
+- 📹 **Live Streaming** - Preview streams via MJPEG, WebRTC, or RTSP
+- 📊 **Real-time Logs** - Monitor camera events and system logs
+- ⚙️ **Settings** - Configure RTSP proxy, ports, and auto-start options
+- 📱 **PWA Support** - Install as a Progressive Web App on mobile devices
+- 🌐 **Responsive Design** - Works on desktop, tablet, and mobile
+
+### External Requirements
+
+To run the Manager UI outside Docker, you need:
+
+Some features also rely on external binaries that must be available on the host when running outside Docker:
+
+Install examples:
+
+```bash
+# macOS
+brew install ffmpeg
+
+# Debian/Ubuntu
+sudo apt-get update && sudo apt-get install -y ffmpeg
+```
+
+If you use the Docker image, FFmpeg is already included (see Docker Deployment below).
+
+### Quick Start (Development)
+
+```bash
+cd app
+npm install
+npm run dev
+```
+
+## Trusted Proxy Authentication (NGINX + Authentik)
+
+If you want to hide the UI behind SSO (e.g. Authentik), you can delegate authentication to a reverse proxy and let this app **trust** specific headers **only** when requests come from an allowlisted proxy IP.
+
+### Server configuration
+
+Set these env vars for the app:
+
+- `AUTH_ENABLED=1`
+- `TRUST_PROXY_AUTH=1`
+- `TRUST_PROXY_IPS=127.0.0.1,::1` (comma-separated allowlist; use the _real_ proxy/container IPs)
+- `TRUST_PROXY_USERNAME_HEADER=x-authentik-username`
+- `TRUST_PROXY_GROUPS_HEADER=x-authentik-groups`
+- `TRUST_PROXY_ADMIN_GROUP=admin` (if present in groups header → user becomes `admin`)
+
+Security notes:
+
+- **Never expose the app directly to the Internet** when `TRUST_PROXY_AUTH=1`.
+- Always put it behind your reverse proxy and restrict inbound traffic to the proxy only.
+- The app will ignore trusted headers unless the TCP peer IP matches `TRUST_PROXY_IPS`.
+
+### NGINX example (Authentik outpost)
+
+This example assumes:
+
+- Authentik outpost is available at `http://authentik-outpost:9000`.
+- The app is at `http://nodelink-manager:3000`.
+
+```nginx
+# Authentik integration (auth_request)
+location = /outpost.goauthentik.io/auth/nginx {
+  internal;
+  proxy_pass http://authentik-outpost:9000/outpost.goauthentik.io/auth/nginx;
+  proxy_pass_request_body off;
+  proxy_set_header Content-Length "";
+  proxy_set_header X-Original-URL $scheme://$http_host$request_uri;
+  proxy_set_header X-Original-Method $request_method;
+  proxy_set_header X-Original-Host $http_host;
+}
+
+location / {
+  auth_request /outpost.goauthentik.io/auth/nginx;
+  error_page 401 = @ak_unauthorized;
+
+  # Pull identity from Authentik response
+  auth_request_set $ak_username $upstream_http_x_authentik_username;
+  auth_request_set $ak_groups   $upstream_http_x_authentik_groups;
+
+  proxy_pass http://nodelink-manager:3000;
+
+  # Forward identity headers to the app
+  proxy_set_header X-Authentik-Username $ak_username;
+  proxy_set_header X-Authentik-Groups $ak_groups;
+
+  # Good hygiene
+  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;
+}
+
+location @ak_unauthorized {
+  return 302 /outpost.goauthentik.io/start?rd=$scheme://$http_host$request_uri;
+}
+```
+
+If you run NGINX and the app on the same Docker network, set `TRUST_PROXY_IPS` to the **NGINX container IP** (or keep it `127.0.0.1,::1` only if NGINX is on the same host network namespace).
+
+### Production Build
+
+```bash
+cd app
+npm run build
+npm start
+```
+
+Open http://localhost:3000 in your browser.
+
+### Docker Deployment (Recommended)
+
+The easiest way to run the Manager UI is with Docker:
+
+```bash
+# Using pre-built image
+docker pull ghcr.io/apocaliss92/nodelink-js-manager:latest
+
+docker run -d \
+  --name nodelink-manager \
+  --network host \
+  -v nodelink-data:/data \
+  ghcr.io/apocaliss92/nodelink-js-manager:latest
+```
+
+Or with Docker Compose:
+
+```bash
+docker-compose up -d
+```
+
+**Environment Variables:**
+
+| Variable    | Default | Description                          |
+| ----------- | ------- | ------------------------------------ |
+| `PORT`      | `3000`  | HTTP server port                     |
+| `RTSP_PORT` | `8554`  | RTSP proxy port                      |
+| `DATA_PATH` | `/data` | Directory for settings.json and logs |
+
+**Dashboard authentication (optional):**
+
+| Variable         | Default | Description                                                                                                             |
+| ---------------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `AUTH_ENABLED`   | (unset) | Enable auth when set to `1/true` (or disable with `0/false`). If unset, auth auto-enables when `ADMIN_PASSWORD` is set. |
+| `ADMIN_PASSWORD` | (unset) | Sets the `admin` password. This credential works for both the web login form and HTTP Basic auth.                       |
+
+### Streaming Authentication (RTSP / MJPEG / HLS / WebRTC)
+
+When authentication is enabled (see `AUTH_ENABLED` / `ADMIN_PASSWORD`), **all streaming endpoints are protected**.
+
+#### Step-by-step
+
+1. **Login to the Manager UI** (or use the API login) to obtain an auth token.
+2. (Recommended) **Generate a long-lived personal token** from **Settings → Personal token**.
+3. Use the correct auth mechanism depending on the streaming protocol:
+
+- RTSP: **Digest** with username/password
+- MJPEG/HLS: token in query string `?token=...`
+- WebRTC signaling + status endpoints: `Authorization: Bearer ...`
+- WebSocket logs: `?token=...` in the WS URL
+
+There are two auth mechanisms depending on the protocol:
+
+1. **RTSP (RTSP proxy): Digest auth with username/password**
+
+- URL format: `rtsp://<host>:<RTSP_PORT>/<camera>/<main|sub|ext>`
+- Credentials: the same **Users** list used by the dashboard.
+- Digest realm: `RTSP Proxy`
+- You can toggle whether auth is required via the Manager UI setting **“Require auth for RTSP connections”**.
+
+Examples:
+
+```bash
+# ffmpeg (Digest)
+ffmpeg -rtsp_transport tcp -i "rtsp://USERNAME:PASSWORD@HOST:8554/camera/main" -f null -
+
+# VLC (it will prompt for credentials, or use URL user:pass)
+vlc "rtsp://USERNAME:PASSWORD@HOST:8554/camera/main"
+```
+
+2. **HTTP-based streaming (MJPEG / HLS): token in query string**
+
+Browsers cannot reliably attach custom headers (like `Authorization`) to media tags (`<img>`, `<video>`), so MJPEG/HLS streams must be accessed with the auth token in the URL query string:
+
+- MJPEG: `/api/mpeg/<camera>/<profile>?token=...`
+- HLS playlist: `/api/hls/<camera>/<profile>/playlist.m3u8?token=...` (and segment requests will inherit the query param)
+
+Examples:
+
+```text
+MJPEG:
+  http://HOST:3000/api/mpeg/camera/main?token=YOUR_TOKEN
+
+HLS:
+  http://HOST:3000/api/hls/camera/main/playlist.m3u8?token=YOUR_TOKEN
+```
+
+Security note: query tokens may end up in logs/history. Treat them like passwords.
+
+3. **WebRTC control endpoints: Bearer token in Authorization header**
+
+WebRTC signaling uses JSON endpoints (create session, send ICE candidates, send answer) and supports standard Bearer auth:
+
+```bash
+# 1) Login to obtain a token
+curl -sS -X POST http://HOST:3000/api/auth/login \
+  -H 'content-type: application/json' \
+  -d '{"username":"admin","password":"YOUR_PASSWORD"}'
+
+# 2) Use the returned token for WebRTC signaling
+curl -sS http://HOST:3000/api/webrtc/status \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+
+You can also generate a personal token via API (requires an existing valid token):
+
+```bash
+curl -sS -X POST http://HOST:3000/api/auth/personal-token \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H 'content-type: application/json' \
+  -d '{}'
+```
+
+4. **WebSocket logs: token in query string**
+
+The browser WebSocket handshake cannot reliably attach custom headers, so use:
+
+```text
+ws://HOST:3000/ws/logs?token=YOUR_TOKEN
+```
+
+If authentication is disabled, these endpoints work without credentials.
+
+Tip: a personal token is ideal for integrations (Home Assistant, scripts, etc.) because it does not expire.
+
+📖 **[Full Docker documentation →](./DOCKER.md)**
+
+---
+
 ## 📚 Full API Documentation
 
 For detailed method-by-method documentation, see the [documentation](./documentation/) folder:

package/dist/{DiagnosticsTools-EC7DADEQ.js → DiagnosticsTools-6WEMO4L4.js}

@@ -9,7 +9,7 @@ import {
   runMultifocalDiagnosticsConsecutively,
   sampleStreams,
   testChannelStreams
-} from "./chunk-TZFZ5WJX.js";
+} from "./chunk-ZE7D7LI4.js";
 export {
   collectCgiDiagnostics,
   collectMultifocalDiagnostics,
@@ -22,4 +22,4 @@ export {
   sampleStreams,
   testChannelStreams
 };
-//# sourceMappingURL=DiagnosticsTools-EC7DADEQ.js.map
+//# sourceMappingURL=DiagnosticsTools-6WEMO4L4.js.map