@similie/hyphen-rtsp-tunnel 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Similie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,497 @@
+# @similie/hyphen-rtsp-tunnel
+
+**Secure, low-cost RTSP snapshot tunneling for distributed environmental monitoring**
+
+---
+
+## Why this exists
+
+At **Similie**, we’re always looking for ways to make **low-cost technology have research-grade impact**.
+
+Many communities—especially in emerging and climate-vulnerable regions—already have access to **consumer-grade IP cameras**. These cameras are affordable, reliable, and widely available, but they’re rarely designed to operate in:
+
+- Intermittent connectivity environments
+- Outside local area networks (LAN) infrastructures
+- Horizontally scaled server architectures
+- Scientific or humanitarian data pipelines
+
+The outputs are often pushed to proprietary/paid services for home monitoring and security use cases. Similie seeks to bypass these limitations, by tapping into the RTSP outputs found on many consumer-grade cameras.
+
+This project bridges the gap between cost, access, deployability, and open operability.
+
+**`@similie/hyphen-rtsp-tunnel`** allows low-power edge devices (for example, ESP32-based gateways) to securely tunnel RTSP camera streams over WebSockets to a centralized server, capture snapshots, and feed them into modern processing pipelines—**without exposing cameras directly to the internet**.
+
+The result:
+
+> **Consumer hardware, safely integrated into professional-grade monitoring systems**
+
+---
+
+## What this module does
+
+This package implements a **Hyphen Command Center plugin** that:
+
+- Accepts **secure WebSocket connections** from edge devices
+- Authenticates devices using a challenge-response handshake (pluggable)
+- Creates a **temporary RTSP tunnel** over WebSockets
+- Captures a snapshot using `ffmpeg`
+- Emits structured events for downstream processing (storage, queues, AI, etc.)
+
+Design constraints:
+
+- The gateway **does not assume storage or cloud providers**
+- The gateway **does not block on uploads**
+- The gateway is **leader-aware** for horizontal scaling
+
+---
+
+## High-level architecture
+
+```
+┌─────────────┐
+│ IP Camera   │
+│ (RTSP)      │
+└─────┬───────┘
+│ 192.168.4.x (private AP)
+┌─────▼───────┐
+│ HyphenOS.   |
+| Enabled     │
+│ Device      │
+│ (ESP32)     │
+│             │
+│ RTSP ↔ WSS  │
+└─────┬───────┘
+│ Secure WebSocket
+▼
+┌───────────────────────┐
+│ Command Center API    │
+│                       │
+│  RTSP Tunnel Gateway  │
+│   - ffmpeg snapshot   │
+│   - auth handshake    │
+│   - leader-aware      │
+└─────────┬─────────────┘
+│ events
+▼
+┌────────────────────────────┐
+│ Storage / Queue / AI       │
+│ (pluggable, async)         │
+└────────────────────────────┘
+```
+
+---
+
+## Key design principles
+
+### 🔐 Secure by default
+
+- Cameras are **never exposed** to the public internet
+- RTSP traffic only flows inside a **temporary authenticated tunnel**
+- Device authentication is **pluggable** (RSA, certificates, future identity systems)
+
+### 🌍 Designed for constrained environments
+
+- Works with **low-power devices**
+- Handles **intermittent connectivity**
+- Snapshot windows automatically clean up on failure
+
+### ⚖️ Horizontally scalable
+
+- Leader-aware via Redis-based leader election
+- Only one gateway handles RTSP capture at a time
+- Multiple servers can process downstream jobs
+
+### 🧩 Modular & extensible
+
+- Storage is event-driven, not hard-coded
+- Queue notification is optional and pluggable
+- Designed to integrate with broader data pipelines
+
+---
+
+## Installation
+
+```bash
+npm install @similie/hyphen-rtsp-tunnel
+```
+
+This package is designed to be used inside a Hyphen Command Center API instance.
+It is not a standalone server binary.
+
+---
+
+## Requirements
+
+This module spans **device firmware** (HyphenOS) and **server infrastructure** (Hyphen Command Center + ffmpeg). Make sure the full stack meets the minimum versions below.
+
+### 1) Device Firmware (HyphenOS)
+
+You need **HyphenOS v1.0.19+** with the IPCamera + WiFi AP feature enabled.
+
+At minimum, your firmware build must include these `build_flags` (example shown using PlatformIO-style flags):
+
+```ini
+; --- Enable WiFi AP mode (camera LAN) ---
+-D HYPHEN_WIFI_AP_ENABLE=1
+-D HYPHEN_WIFI_AP_SSID=\"HyphenCam-001\"
+-D HYPHEN_WIFI_AP_PASS=\"hyphen1234\"
+-D HYPHEN_WIFI_AP_CHANNEL=6
+-D HYPHEN_WIFI_AP_MAX_CLIENTS=4
+-D HYPHEN_HIDE_WIFI_AP=0
+; --- Camera endpoint on AP LAN ---
+-D HYPHEN_CAM_HOST=\"192.168.4.216\"
+-D HYPHEN_CAM_PORT=554
+
+; --- WSS tunnel endpoint (Hyphen Command Center API) ---
+-D HYPHEN_WSS_HOST=\"192.168.18.215\"
+-D HYPHEN_WSS_PORT=7443
+-D HYPHEN_WSS_PATH=\"/\"
+
+; --- Snapshot cadence ---
+-D HYPHEN_IPCAM_OFFSET_DEFAULT=1   ; (publish() cadence multiplier)
+-D HYPHEN_IPCAM_TUNNEL_TIMEOUT_MS=45000
+
+; --- AP static network (optional but recommended for determinism) ---
+-D HYPHEN_WIFI_AP_IP_0=192
+-D HYPHEN_WIFI_AP_IP_1=168
+-D HYPHEN_WIFI_AP_IP_2=4
+-D HYPHEN_WIFI_AP_IP_3=1
+
+-D HYPHEN_WIFI_AP_MASK_0=255
+-D HYPHEN_WIFI_AP_MASK_1=255
+-D HYPHEN_WIFI_AP_MASK_2=255
+-D HYPHEN_WIFI_AP_MASK_3=0
+```
+
+Notes:
+
+- The camera is expected to be reachable on the Hyphen device’s AP LAN (e.g. 192.168.4.x).
+- The WSS host/port/path are compiled into the device firmware, so the server does not “discover” the camera endpoint.
+
+### 2) Hyphen Command Center Versions
+
+This module is designed to run inside the Hyphen Command Center stack.
+
+Minimum versions:
+
+- Hyphen Command Center API v1.1.1+
+- Hyphen Command Center (UI) v1.1.2+
+
+You can override env variable defaults if you include the following in the IP Camera "Sensor" metadata in Command Center:
+
+- CAM_PASS=admin
+- CAM_USER=mycamerapassword
+- RTSP_PATH=/stream2 # the RTSP stream to pull
+
+### 3) Server Runtime: ffmpeg
+
+The server process that hosts this plugin must have ffmpeg installed and available on the PATH (or wrapped in your runtime container image).
+Quick install:
+
+#### Ubuntu/Debian
+
+```bash
+sudo apt-get update
+sudo apt-get install -y ffmpeg
+```
+
+#### Fedora
+
+```bash
+sudo dnf install -y ffmpeg
+```
+
+#### macOS (Home)
+
+```bash
+brew install ffmpeg
+```
+
+#### Docker
+
+If you run Command Center in containers, ensure your image includes ffmpeg (for Debian-based images):
+
+```dockerfile
+RUN apt-get update && apt-get install -y ffmpeg && rm -rf /var/lib/apt/lists/*
+```
+
+### 4) Optional: AWS SQS (Downstream notifications)
+
+If you want the gateway to emit snapshot events to SQS, you must configure AWS credentials + region and provide:
+• AWS_REGION
+• SQS_QUEUE_URL
+
+If these are not set, the SQS notifier remains disabled and the module still works normally.
+
+---
+
+## Quick Debugging Checklist
+
+Before debugging code, verify these basics — **90% of issues show up here**.
+
+### Device (HyphenOS)
+
+- [ ] Device is running **HyphenOS v1.0.19+**
+- [ ] WiFi AP is visible (e.g. `HyphenCam-001`)
+- [ ] Camera is connected to the device AP
+- [ ] Camera responds from the device:
+  - RTSP reachable at `rtsp://<CAM_HOST>:<CAM_PORT><RTSP_PATH>`
+- [ ] Device can resolve and reach the Command Center WSS host
+- [ ] `HELLO` and `AUTH_OK` appear in Command Center logs
+
+### Network
+
+- [ ] **WSS port is reachable** from the device network
+- [ ] No firewall blocking:
+  - WebSocket port (`WS_PORT`)
+  - Local proxy port (`PROXY_PORT`) on the server
+- [ ] TLS certs are valid if `WS_TLS=1`
+
+### Command Center API
+
+- [ ] Running **Hyphen Command Center API v1.1.1+**
+- [ ] Module `@similie/hyphen-rtsp-tunnel` is loaded at startup
+- [ ] Redis is reachable (leader election + caching)
+- [ ] Device identity exists and resolves correctly
+
+### ffmpeg
+
+- [ ] `ffmpeg` is installed and on `PATH`
+- [ ] Running `ffmpeg -version` works in the same environment
+- [ ] `ffmpeg` can open the RTSP proxy URL:
+  ```bash
+  ffmpeg -rtsp_transport tcp -i rtsp://127.0.0.1:8554/stream2 -frames:v 1 test.jpg
+  ```
+- No other capture is already in progress (single-capture lock)
+
+### Storage / Output
+
+- OUT_DIR exists and is writable
+- Snapshot files appear on successful capture
+- Downstream listeners (SQS, workers, etc.) are optional and non-blocking
+
+## Usage: Command Center Plugin
+
+```bash
+# .env
+HYPHEN_MODULES=@similie/hyphen-rtsp-tunnel-module # comma-separated for additional modules
+```
+
+## Environment Variables
+
+The gateway is fully configured via environment variables.
+
+## Environment Variables
+
+All configuration for `@similie/hyphen-rtsp-tunnel` is provided via environment variables.
+
+### Gateway & Networking
+
+| Variable     | Default | Description                                       |
+| ------------ | ------- | ------------------------------------------------- |
+| `WS_PORT`    | `7443`  | Port for the WebSocket gateway                    |
+| `WS_TLS`     | `0`     | Enable TLS for WebSocket server (`1` = HTTPS/WSS) |
+| `TLS_CERT`   | —       | Path to TLS certificate (required if `WS_TLS=1`)  |
+| `TLS_KEY`    | —       | Path to TLS private key (required if `WS_TLS=1`)  |
+| `PROXY_PORT` | `8554`  | Local TCP proxy port used by FFmpeg               |
+
+---
+
+### RTSP / Camera
+
+| Variable    | Default    | Description          |
+| ----------- | ---------- | -------------------- |
+| `CAM_USER`  | `admin`    | RTSP camera username |
+| `CAM_PASS`  | —          | RTSP camera password |
+| `RTSP_PATH` | `/stream2` | RTSP stream path     |
+
+> **Note:**  
+> The camera **host and port are NOT configured server-side**.  
+> The ESP32 device determines the camera endpoint via its own build flags.
+
+---
+
+### Capture Behavior
+
+| Variable             | Default | Description                                  |
+| -------------------- | ------- | -------------------------------------------- |
+| `AUTO_CAPTURE`       | `1`     | Automatically capture on device connection   |
+| `CAPTURE_TIMEOUT_MS` | `45000` | Maximum capture duration before abort        |
+| `HELLO_WAIT_MS`      | `2000`  | Time to wait for HELLO before closing socket |
+
+---
+
+### Authentication
+
+| Variable       | Default | Description                           |
+| -------------- | ------- | ------------------------------------- |
+| `REQUIRE_AUTH` | `1`     | Require AUTH handshake before capture |
+
+Authentication is currently based on Command Center/Device Certificate Signatures.
+
+---
+
+### Storage
+
+| Variable  | Default           | Description                          |
+| --------- | ----------------- | ------------------------------------ |
+| `OUT_DIR` | OS temp directory | Local directory for snapshot storage |
+
+---
+
+### AWS / SQS (Optional)
+
+These are only required if using the SQS notifier.
+
+| Variable        | Description                    |
+| --------------- | ------------------------------ |
+| `AWS_REGION`    | AWS region                     |
+| `SQS_QUEUE_URL` | SQS queue URL (FIFO supported) |
+
+If these variables are not present, the notifier is automatically disabled.
+
+---
+
+## Device Handshake Flow
+
+```
+Server → READY
+Device → HELLO [payloadId] deviceId
+Server → CHAL
+Device → AUTH deviceId
+Server → AUTH_OK
+Server → OPEN
+```
+
+---
+
+## Events Emitted
+
+The RTSP tunnel gateway exposes an internal event emitter so that **capture, storage, and downstream processing can be fully decoupled**.
+
+### `snapshot:captured`
+
+Emitted when a snapshot is successfully captured and written to local temporary storage.
+
+```ts
+{
+  sessionId: string;
+  deviceId: string;
+  payloadId: string | null;
+  localPath: string;
+  capturedAt: string;
+}
+```
+
+Typical consumers of this event include:
+
+- Storage adapters (S3, NFS, local disk)
+- Queue notifiers (SQS, BullMQ, Redis)
+- Video stitching pipelines
+- AI / image-processing workers (e.g. 4Shadow)
+
+### `snapshot:failed`
+
+Emitted whenever a snapshot attempt fails at any stage.
+
+```ts
+{
+  stage: "auth" | "capture" | "timeout" | "ffmpeg";
+  error: string;
+}
+```
+
+This allows downstream systems to log, alert, retry, or back off without blocking the gateway.
+
+---
+
+## Storage Responsibility (Intentional Design)
+
+We have stubbed out this plugin to work well for our workflows, but out of the box you may need to implement logic to
+support your own workflows
+
+This module does not:
+
+- Upload images to S3 (without configuration)
+- Push messages to SQS or Redis (without configuration)
+- Persist database records
+- Perform AI or video processing
+
+The gateway’s responsibility ends at secure capture and local persistence.
+
+This keeps the system:
+
+- Non-blocking
+- Fault tolerant
+- Horizontally scalable
+- Easy to extend with new pipelines
+
+All heavy or slow work is expected to run in downstream workers.
+
+---
+
+## Scaling & High Availability
+
+The RTSP tunnel is designed to operate in clustered environments:
+
+- Uses leader election so only one instance captures
+- Other nodes remain idle and ready for failover
+- Safe to run behind load balancers
+- Compatible with Redis-backed horizontal scaling
+
+This avoids duplicate captures while preserving resilience.
+
+---
+
+## Security Model
+
+Security is enforced through layered constraints:
+
+- TLS-secured WebSocket transport
+- Device-initiated outbound connections only
+- Optional cryptographic authentication (nonce + signature)
+- No inbound RTSP exposure
+- Camera network remains isolated behind the device
+
+This design minimizes attack surface and removes the need to expose cameras directly to the internet.
+
+---
+
+### Who This Is For
+
+- Environmental sensing networks
+- Flood and climate early-warning systems
+- Research deployments using consumer-grade cameras
+- Edge-to-cloud ingestion pipelines
+- Teams who need secure camera access without RTSP exposure
+
+---
+
+## Philosophy
+
+At Similie, we believe that low-cost, open technology can deliver research-grade impact.
+
+This module is part of a broader effort to make climate monitoring, early warning, and environmental intelligence:
+
+- Accessible
+- Affordable
+- Open
+- Locally deployable
+- Globally scalable
+
+---
+
+### License
+
+MIT © Similie
+
+### Hyphen Ecosystem
+
+| Project                   | Description                                                                                                                       | Repository                                       |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| **HyphenOS**              | The device runtime environment for ultra-reliable IoT deployments. Includes OTA, telemetry queues, watchdogs, and sensor drivers. | https://github.com/similie/hyphen-os             |
+| **HyphenConnect**         | Network + MQTT abstraction layer for ESP32 / Cellular devices. Enables function calls, variable access, and secure OTA.           | https://github.com/similie/hyphen-connect        |
+| **Hyphen Command Center** | SvelteKit UI for managing your global device fleet, OTA updates, telemetry, and configuration.                                    | https://github.com/similie/hyphen-command-center |
+| **Hyphen Elemental**      | The hardware schematics Similie uses to for our Hyphen Elemental 4 line of Products.                                              | https://github.com/similie/hyphen-elemental      |
+| **Hyphen Video Encode**   | A video stream processor for the RTSP Camera Workflow. Turn snaps into daily images.                                              | https://github.com/similie/hyphen-videoencoder   |
+| **Ellipsies**             | Workflow + routing engine powering the API: device identity, build pipeline, users, orgs, storage, and message routing.           | https://github.com/similie/ellipsies             |

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import type { HyphenModule } from "@similie/hyphen-command-server-types";
+declare const moduleImpl: HyphenModule;
+export default moduleImpl;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAoBzE,QAAA,MAAM,UAAU,EAAE,YAqFjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,83 @@
+import { RtspTunnelGateway, S3StorageAdapter, LocalStorageAdapter, StorageWorker, SqsNotifier, NoopNotifier, } from "./services/index.js";
+function buildNotifierFromEnv() {
+    // Not implementing SQS yet — just leaving the slot.
+    // Example rule later:
+    if (process.env.SQS_QUEUE_URL && process.env.AWS_REGION)
+        return new SqsNotifier();
+    return new NoopNotifier();
+}
+const moduleImpl = {
+    name: "rtsp-tunnel",
+    version: "1.0.0",
+    async init(ctx) {
+        ctx.log("[rtsp-tunnel] init");
+        ctx.ellipsies.pgManager.datasource;
+        // --- choose storage adapter by env ---
+        const mode = process.env.STORAGE_MODE ?? "local";
+        const storage = mode === "s3"
+            ? new S3StorageAdapter(process.env.S3_BUCKET ?? "", process.env.S3_PREFIX ?? "hyphen/rtsp")
+            : new LocalStorageAdapter();
+        const gateway = new RtspTunnelGateway(ctx);
+        const storageWorker = new StorageWorker(ctx, gateway.events, storage);
+        const notifier = buildNotifierFromEnv();
+        await notifier.init(ctx);
+        // event -> notifier (does nothing if NoopNotifier)
+        gateway.events.on("snapshot:stored", async (e) => {
+            try {
+                ctx.log("[rtsp-tunnel] snapshot stored event", { event: e });
+                await notifier.send("snapshot:stored", e);
+            }
+            catch (err) {
+                ctx.log("[rtsp-tunnel] notifier error (stored)", err);
+            }
+        });
+        gateway.events.on("snapshot:failed", async (e) => {
+            try {
+                ctx.log("[rtsp-tunnel] snapshot failed event", { event: e });
+                await notifier.send("snapshot:failed", e);
+            }
+            catch (err) {
+                ctx.log("[rtsp-tunnel] notifier error (failed)", err);
+            }
+        });
+        const startAll = async () => {
+            // leader gating
+            if (ctx.leader && !ctx.leader.amLeader()) {
+                ctx.log("[rtsp-tunnel] not leader; gateway not started");
+                return;
+            }
+            // IMPORTANT: start worker first so we never miss captured events
+            storageWorker.start();
+            await gateway.start();
+        };
+        const stopAll = async () => {
+            await gateway.stop();
+            await storageWorker.stop();
+        };
+        // // Leader hooks (if present)
+        if (ctx.leader) {
+            ctx.leader.on("elected", async () => {
+                ctx.log("[rtsp-tunnel] leader elected; starting gateway+worker");
+                await startAll();
+            });
+            ctx.leader.on("revoked", async () => {
+                ctx.log("[rtsp-tunnel] leader revoked; stopping gateway+worker");
+                await stopAll();
+            });
+            ctx.leader.on("error", (err) => {
+                ctx.log("[rtsp-tunnel] leader error", err?.message ?? err);
+                // do not stop automatically; your choice
+            });
+        }
+        // Start now (leader or single-node)
+        await startAll();
+        return {
+            shutdown: async () => {
+                ctx.log("[rtsp-tunnel] shutdown");
+                await stopAll();
+            },
+        };
+    },
+};
+export default moduleImpl;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/services/day.d.ts

@@ -0,0 +1,3 @@
+export declare function sanitizeTzOffsetHours(v: any): number | null;
+export declare function dayFromCapturedAt(capturedAtIso: string, tzOffsetHours?: number | null): string;
+//# sourceMappingURL=day.d.ts.map

package/dist/services/day.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"day.d.ts","sourceRoot":"","sources":["../../src/services/day.ts"],"names":[],"mappings":"AAAA,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,GAAG,GAAG,MAAM,GAAG,IAAI,CAM3D;AAED,wBAAgB,iBAAiB,CAC/B,aAAa,EAAE,MAAM,EACrB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,GAC5B,MAAM,CAmBR"}

package/dist/services/day.js

@@ -0,0 +1,26 @@
+export function sanitizeTzOffsetHours(v) {
+    const n = typeof v === "number" ? v : Number(v);
+    if (!Number.isFinite(n))
+        return null;
+    // sanity bounds (common tz offsets)
+    if (n < -12 || n > 14)
+        return null;
+    return n;
+}
+export function dayFromCapturedAt(capturedAtIso, tzOffsetHours) {
+    const d = new Date(capturedAtIso);
+    if (Number.isNaN(d.getTime()))
+        throw new Error(`Invalid capturedAt ${capturedAtIso}`);
+    const hasOffset = process.env.USE_DEVICE_TZ_OFFSET === "1";
+    const off = hasOffset &&
+        typeof tzOffsetHours === "number" &&
+        Number.isFinite(tzOffsetHours)
+        ? tzOffsetHours
+        : 0;
+    const shifted = new Date(d.getTime() + Math.round(off * 3600 * 1000));
+    const yyyy = shifted.getUTCFullYear();
+    const mm = String(shifted.getUTCMonth() + 1).padStart(2, "0");
+    const dd = String(shifted.getUTCDate()).padStart(2, "0");
+    return `${yyyy}-${mm}-${dd}`;
+}
+//# sourceMappingURL=day.js.map

package/dist/services/day.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"day.js","sourceRoot":"","sources":["../../src/services/day.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,qBAAqB,CAAC,CAAM;IAC1C,MAAM,CAAC,GAAG,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAChD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,oCAAoC;IACpC,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,GAAG,EAAE;QAAE,OAAO,IAAI,CAAC;IACnC,OAAO,CAAC,CAAC;AACX,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,aAAqB,EACrB,aAA6B;IAE7B,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,aAAa,CAAC,CAAC;IAClC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,sBAAsB,aAAa,EAAE,CAAC,CAAC;IAEzD,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB,KAAK,GAAG,CAAC;IAE3D,MAAM,GAAG,GACP,SAAS;QACT,OAAO,aAAa,KAAK,QAAQ;QACjC,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC;QAC5B,CAAC,CAAC,aAAa;QACf,CAAC,CAAC,CAAC,CAAC;IACR,MAAM,OAAO,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC;IAEtE,MAAM,IAAI,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IACtC,MAAM,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC9D,MAAM,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACzD,OAAO,GAAG,IAAI,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC;AAC/B,CAAC"}

package/dist/services/device-auth.d.ts

@@ -0,0 +1,26 @@
+import type { ModuleContext } from "@similie/hyphen-command-server-types";
+export type AuthPayload = {
+    deviceId: string;
+    sigB64: string;
+};
+export declare class DeviceAuth {
+    private readonly ctx;
+    constructor(ctx: ModuleContext);
+    deviceSensors(identity: string): Promise<{
+        results: any;
+        values: Record<string, string>;
+    }>;
+    device(identity: string): Promise<import("@similie/ellipsies").ObjectLiteral | null>;
+    private ds;
+    /**
+     * Parse "AUTH <deviceId> <sigB64>"
+     * Returns null if invalid.
+     */
+    parseAuthLine(line: string): AuthPayload | null;
+    /**
+     * Lookup device certificate by identity and verify signature
+     * over `${deviceId}.${nonceB64}` using RSA-SHA256.
+     */
+    verify(deviceId: string, nonceB64: string, sigB64: string): Promise<boolean>;
+}
+//# sourceMappingURL=device-auth.d.ts.map

package/dist/services/device-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-auth.d.ts","sourceRoot":"","sources":["../../src/services/device-auth.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sCAAsC,CAAC;AAE1E,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,qBAAa,UAAU;IACT,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE,aAAa;IAElC,aAAa,CAAC,QAAQ,EAAE,MAAM;;;;IAU9B,MAAM,CAAC,QAAQ,EAAE,MAAM;IAMpC,OAAO,CAAC,EAAE;IAQV;;;OAGG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAY/C;;;OAGG;IACG,MAAM,CACV,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,CAAC;CAqDpB"}