From c387083b8b4b64a8273a32d6912904d104739919 Mon Sep 17 00:00:00 2001 From: "Isaac J. Newton" Date: Tue, 17 Nov 2026 11:32:14 +0000 Subject: [PATCH 1/9] docs: inventory Console architecture and billing consistency boundaries --- docs/centralized/current-architecture.md | 154 +++++++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 docs/centralized/current-architecture.md diff --git a/docs/centralized/current-architecture.md b/docs/centralized/current-architecture.md new file mode 100644 index 0000000..bb84bcc --- /dev/null +++ b/docs/centralized/current-architecture.md @@ -0,0 +1,154 @@ +# Current architecture + +Inspected baseline: `fc396d63e31f7f8979cc031c880ceb73237fdbd8` on the fork's +`main`. This document describes that baseline, before the feature changes. +Inspection did not contact a gateway, meter, broker, contract or blockchain. + +## Startup and deployment + +`src/index.ts` loads backend extensions and UI extensions, initializes contracts, +runs `onBeforeInit`, initializes SQLite, runs `onDatabaseSetup`, starts MQTT, +starts HTTP, and runs `onAfterInit`. Terminal WebSocket registration happens when +the entry point is loaded. A startup failure invokes `onInitError` and exits. +Contract clients are also imported by billing dependencies; merely importing the +production entry point is not a safe integration-test harness. + +The image uses Node 20 Alpine and builds native dependencies with the distribution +toolchain. `entrypoint.sh` runs `scripts/install-modules.cjs` before its command. +The installer validates module references and prepares configured extensions. +`compose.yaml` runs one Console with host networking, the existing `.env`, a +bind-mounted `.data`, and extension volumes. Its health check requests `/healthz`. +`auto-compose.sh` updates the Console service, preserves configuration and volumes, +waits for health, and restores the prior image if startup fails. These are the +standalone deployment interfaces to preserve. + +## Billing pipeline and its boundaries + +`src/services/mqtt.ts` currently owns **one** MQTT client. It subscribes with QoS 1 +to `application/{APPLICATION_ID}/device/+/event/+`. The connection uses `MQTT_URL` +when present; otherwise it uses `CHIRPSTACK_HOST || 'localhost'`, port 1883. +The current session is clean, uses a random `console-` client ID, and reconnects. +Each event is independently offered to Manager ingestion. Only matching uplinks +with FPort 2 (or the legacy missing-port case) enter billing. There is no second +monitoring connection in this baseline; removing Manager must remove its fan-out, +not accidentally remove the collector. + +`handleMessage`: + +1. Validates the device identity and takes a process-local DevEUI lock. +2. Uses `uplinkPayload` and `decodePayload`, finds the public key from the packet + or stored device, and verifies the Ed25519 signature over bytes 0–7. +3. Takes a second lock by public key, preventing different DevEUIs from advancing + the same meter concurrently. +4. For a packet containing a public key, registers the meter through the contract + lookup or updates its DevEUI, then synchronizes its latest nonce. +5. For `latestNonce + 1`, atomically inserts the transaction and advances the + stored nonce. A repeated current nonce is accepted only if the stored + transaction exists and the reported energy has not decreased. It does not + insert or distribute that transaction again. Other nonzero nonces fail. +6. Initializes `is_on = false`, invokes `isOnStateCompute`, and leaves it false + if any extension throws. `runHook` combines boolean results with AND and + throws after collecting extension errors. Revenue/owed failures therefore + remain **off**; the reported ENS issue is outside this task. +7. Calls `encode` and gRPC enqueue. Nonce zero includes the stored nonce in the + reply; ordinary replies do not. Coordinates retain the existing float format. +8. In a `finally` after the enqueue attempt, notifies + `onTransactionDistribution` for a newly stored transaction. The hook does not + delay completion. Errors are caught; locks are released in `finally`. + +Manager-specific `collectorAccepted` observes the transaction after persistence +and is isolated by a catch. `ingestEvent` is separate from billing. Neither is +required to compute the billing decision. + +The transaction commit precedes enqueue. `src/services/grpc.ts` sends an +unconfirmed FPort 2 `DeviceQueueItem` and does not supply an idempotency key. +Consequently a crash between sending and receiving the enqueue response has an +unknown outcome. Neither the device locks nor SQLite uniqueness solve that +external side-effect ambiguity. A central timeout also cannot prove that the +central process stopped working. These constraints must inform the ownership +protocol, rather than assuming that retries are harmless. + +## Extensions and distribution + +`BACKEND_MODULES` and `UI_MODULES` are parsed by `src/lib/modules.ts`; `utils.ts` +loads their hooks and UI implementations. `src/types.ts` defines initialization, +MQTT, message lifecycle, meter registration, state computation/enqueue and +transaction distribution hooks. Hooks must retain their names and arguments. +UI actions are dispatched through `/api/actions/:moduleId/:actionId`. + +| Built-in module | Behavior | Existing idempotency boundary | +| --- | --- | --- | +| `core/is_on` | Reads cross-chain revenue and amount owed; compares them | Errors propagate, preserving fail-closed behavior | +| `core/arweave` | Uploads each new transaction through Turbo | No durable publication claim; a retry can upload twice | +| `core/prover` | Immediate transaction submission and scheduled batch publication | Cron excludes chain-confirmed nonces; an unconfirmed batch can be republished | +| `core/streamr` | Scheduled pending batches; UI also offers publication | Cron synchronizes chain nonces, but does not deduplicate repeated external publications | + +`getLatestTransactionNonce` reconciles chain and local state. Scheduled +`getSyncedPendingTransactions` only includes meters successfully synchronized +with chain and nonces above their chain nonce. This is not an exactly-once +external delivery guarantee: chain confirmation can lag publication. The managed +roles need explicit distribution ownership, including scheduled and UI paths. + +## Storage + +`src/store/sqlite.ts` opens `.data/m3tering.db`. `meters` stores public key, +DevEUI, token ID and latest nonce. `transactions` has unique `(nonce, identifier)`; +`recordMeterTransaction` inserts and advances the meter nonce in one transaction. +Read helpers frequently return null/empty on errors; persistence errors propagate. +Nonce synchronization prunes records according to the existing chain rules. + +Startup also calls `initializeManagerStore`. Manager owns events, command +history, usage readings, electrical readings, authentication/monitoring state and +per-device interpretation state in its modules under `src/m3ter`. Its rolling +telemetry limit is separate from billing records. Removal must stop initializing +or pruning these tables and leave existing tables and their data untouched. +`applicationId` currently lives in Manager's ChirpStack helper but is imported by +the collector: move that shared validation to a neutral module before removal. + +## HTTP and applications + +`server.ts` mounts ChirpStack before body parsers so gRPC-Web remains streamed, +then same-origin middleware, no-store headers, health, static assets, Manager +routes, desktop rendering and extension actions. There is no Console login. +`auth.ts` checks Fetch Metadata and Origin/Host; forwarded headers are not trusted. +`socket-router.ts` authorizes exact WebSocket paths and requires same-origin +browser upgrades. Central authentication must also precede proxy/static routes +and upgrade dispatch; agent upgrades need separate credential authentication. + +| App or endpoint | Current resources and behavior | Standalone / gateway target | Central target | +| --- | --- | --- | --- | +| Desktop `/`, static assets | Handlebars, client window manager | Existing LAN UI, no login | Login required; selected gateway displayed | +| Terminal `/terminal` | `ssh2` to `127.0.0.1:22`; browser supplies SSH credentials, resize and input | Keep direct local SSH | `ssh2` over purpose-limited agent TCP stream; audit sessions | +| ChirpStack `/chirpstack/*` | HTTP/gRPC-Web reverse proxy to optional ChefStack/web URL or `CHIRPSTACK_HOST:8080` | Keep local streaming proxy | Same proxy through selected agent, no central local-network access | +| M3ter Manager `/api/m3ter-manager/*`, live stream | Own login, MQTT observations, SQLite history, REST device/queue management | Remove | Remove | +| Browser | Explicit URLs framed; Google searches open another tab | Replace with optional remote engine; local traffic reaches this machine | Remote engine; private traffic reaches selected gateway only | +| Paint | Browser canvas, pointer drawing, undo, image export | Unchanged client-side | Unchanged client-side | +| Settings / themes / toggle / desktop preferences | Local storage, four themes, icon layout, window control | Unchanged | Unchanged, with gateway selection added separately | +| App feedback / actions | App-scoped dialogs, notifications, extension action calls | Unchanged | Authenticated actions; selected gateway context where relevant | +| Streamr extension UI | Server extension configuration and publisher | Preserve standalone behavior | Central distribution ownership; no independent gateway publishing | +| `/healthz` | HTTP liveness/readiness probe | Existing behavior | Local readiness mechanism without exposing unauthenticated central UI/API | +| `/api/actions/:moduleId/:actionId` | Configured UI extension callbacks | Existing behavior | Require login and managed-role side-effect policy | + +No independent Print application or METAS application is registered in this +baseline. Do not invent or remove unrelated functionality to satisfy those names. +ChirpStack forwards the user's bearer token, strips Console cookies and upstream +authentication headers, rewrites assets/redirects, and preserves streaming. The +gateway API token is never a substitute for the user's web login. + +## Tests and CI + +Jest runs after `tsc --noEmit`. Existing suites cover billing locks/nonces, +encoding/decoding, hooks, SQLite, proxy/origin handling, deployment scripts and +Manager-specific functionality. Playwright uses local fixture servers, a test SSH +server and fake ChirpStack/MQTT services. Manager fixtures and tests are removable; +unrelated assertions must remain covered. + +`.github/workflows/ci.yml` runs Node 20 tests and Playwright, then native AMD64 +and ARM64 builds on separate runners. Pushed platform digests are collected into +the existing multi-architecture manifest; PRs build without publishing. Signing +must be additive and conditional on publishing. No production startup, contract +RPC or gateway traffic belongs in verification of this feature. + +Firmware sources referenced in the task are not present in this checkout. +The stated nonce reset after more than three unanswered reports is therefore a +deployment assumption requiring validation against the actual firmware. From 3b46fa3283c11a6c77f04be88ef23caaea0629b8 Mon Sep 17 00:00:00 2001 From: "Isaac J. Newton" Date: Tue, 17 Nov 2026 11:32:16 +0000 Subject: [PATCH 2/9] refactor: remove Manager and preserve billing through an injected downlink sink --- README.md | 325 ++---------------- src/index.ts | 2 + src/lib/chirpstack-config.ts | 8 + src/lib/legacy-config.ts | 7 + src/{m3ter => lib/protocol}/decoder.ts | 4 +- src/{m3ter => lib/protocol}/electrical.ts | 0 src/m3ter/accumulator.ts | 39 --- src/m3ter/api.ts | 143 -------- src/m3ter/auth.ts | 63 ---- src/m3ter/chirpstack.ts | 61 ---- src/m3ter/commands.ts | 51 --- src/m3ter/config.ts | 10 - src/m3ter/electrical-store.ts | 79 ----- src/m3ter/monitor.ts | 136 -------- src/m3ter/store.ts | 196 ----------- src/public/css/m3ter-manager.css | 92 ----- src/public/js/desktop.js | 1 - src/public/js/m3ter-charts.js | 41 --- src/public/js/m3ter-commands.js | 120 ------- src/public/js/m3ter-electrical.js | 72 ---- src/public/js/m3ter-manager.js | 297 ---------------- src/services/downlink.ts | 8 + src/services/mqtt.ts | 43 +-- src/services/server.ts | 3 - src/store/sqlite.ts | 2 - src/views/index.hbs | 2 - src/views/layouts/main.hbs | 5 - src/views/partials/m3ter-manager.hbs | 56 --- tests/fixtures/handle-message-baseline.txt | 96 ++++++ tests/logic/electrical.test.ts | 4 +- tests/logic/manager-commands.test.ts | 38 -- ...decoder.test.ts => report-decoder.test.ts} | 2 +- tests/services/manager-auth.test.ts | 44 --- tests/services/manager-config.test.ts | 11 - tests/services/manager-removal.test.ts | 32 ++ tests/services/mqtt.test.ts | 59 +++- tests/store/electrical.test.ts | 87 ----- tests/store/manager.test.ts | 208 ----------- tests/ui/auth.spec.cjs | 6 +- tests/ui/browser.spec.cjs | 11 +- tests/ui/desktop.spec.cjs | 14 +- tests/ui/electrical.spec.cjs | 77 ----- tests/ui/manager-auth.spec.cjs | 25 -- tests/ui/manager-fixture.cjs | 100 ------ tests/ui/manager-preview.cjs | 23 -- tests/ui/manager-relay.spec.cjs | 105 ------ tests/ui/manager.spec.cjs | 197 ----------- tests/ui/network.spec.cjs | 9 +- tests/ui/serve-auth.cjs | 3 - tests/ui/serve.cjs | 6 +- 50 files changed, 272 insertions(+), 2751 deletions(-) create mode 100644 src/lib/chirpstack-config.ts create mode 100644 src/lib/legacy-config.ts rename src/{m3ter => lib/protocol}/decoder.ts (96%) rename src/{m3ter => lib/protocol}/electrical.ts (100%) delete mode 100644 src/m3ter/accumulator.ts delete mode 100644 src/m3ter/api.ts delete mode 100644 src/m3ter/auth.ts delete mode 100644 src/m3ter/chirpstack.ts delete mode 100644 src/m3ter/commands.ts delete mode 100644 src/m3ter/config.ts delete mode 100644 src/m3ter/electrical-store.ts delete mode 100644 src/m3ter/monitor.ts delete mode 100644 src/m3ter/store.ts delete mode 100644 src/public/css/m3ter-manager.css delete mode 100644 src/public/js/m3ter-charts.js delete mode 100644 src/public/js/m3ter-commands.js delete mode 100644 src/public/js/m3ter-electrical.js delete mode 100644 src/public/js/m3ter-manager.js create mode 100644 src/services/downlink.ts delete mode 100644 src/views/partials/m3ter-manager.hbs create mode 100644 tests/fixtures/handle-message-baseline.txt delete mode 100644 tests/logic/manager-commands.test.ts rename tests/logic/{manager-decoder.test.ts => report-decoder.test.ts} (97%) delete mode 100644 tests/services/manager-auth.test.ts delete mode 100644 tests/services/manager-config.test.ts create mode 100644 tests/services/manager-removal.test.ts delete mode 100644 tests/store/electrical.test.ts delete mode 100644 tests/store/manager.test.ts delete mode 100644 tests/ui/electrical.spec.cjs delete mode 100644 tests/ui/manager-auth.spec.cjs delete mode 100644 tests/ui/manager-fixture.cjs delete mode 100644 tests/ui/manager-preview.cjs delete mode 100644 tests/ui/manager-relay.spec.cjs delete mode 100644 tests/ui/manager.spec.cjs diff --git a/README.md b/README.md index d9d82f1..57112b5 100644 --- a/README.md +++ b/README.md @@ -76,297 +76,6 @@ npm install npm run dev ``` -## M3ter Manager - -**M3ter Manager** is a built-in desktop application for Switch Cumulus telemetry -and technician downlinks. Launch it from the desktop, dock, or application -launcher. Its Overview, Live monitoring, Analytics, Commands, Queue, and Meter -information sections share the selected device, desktop theme, and responsive -window environment. On phones the desktop presents one active full-screen window. - -### Configuration and startup - -Configure only the Manager login and existing ChirpStack connection: - -```dotenv -M3TER_MANAGER_USERNAME=operator -M3TER_MANAGER_PASSWORD=your-strong-manager-password -APPLICATION_ID=your-chirpstack-application-uuid -CHIRPSTACK_HOST=localhost -API_TOKEN=your-server-side-chirpstack-api-token -CHIRPSTACK_REST_URL=http://localhost:8090 -M3TER_INACTIVE_SECONDS=300 -``` - -`CHIRPSTACK_REST_URL` is the origin of **chirpstack-rest-api**, not the web UI. -It defaults to `http://CHIRPSTACK_HOST:8090`. The separately configured -`CHIRPSTACK_WEB_URL` continues to serve the embedded ChirpStack web application. -The REST proxy must be reachable from the console process/container. For a -loopback-only proxy connected to a local plaintext gRPC server, its command is: - -```sh -chirpstack-rest-api --server 127.0.0.1:8080 --bind 127.0.0.1:8090 --insecure -``` - -See the [official REST proxy documentation](https://github.com/chirpstack/chirpstack-rest-api) -for installation and TLS options. No browser CORS or direct access to port 8090 -is needed. The API token needs device/application/profile read access and device -queue enqueue/read/flush access for the configured application. MQTT requires -permission to subscribe to that application's events. Configure ChirpStack's -MQTT integration to publish JSON. Manager reuses the Console's original -`CHIRPSTACK_HOST` connection on port 1883 (localhost by default). Optional -`MQTT_URL=mqtt://broker.example:1883` overrides the shared broker address for both -consumers; `mqtts://`, `ws://`, and `wss://` are also supported. URL credentials, -when required by the broker, stay on the backend. No separate client is created. Opening or closing Manager does not own or stop this connection. -Both consumers receive messages independently; monitoring errors cannot disable -the collector. The old monitor-only toggle has been removed: collection remains enabled. - -```sh -npm run build -npm start -``` - -Then open the console on its configured port (3000 by default) and -launch **M3ter Manager**. The dashboard stays accessible while MQTT reconnects. - -If a relay rejects, stalls, or interrupts Manager's WebSocket, the dashboard -falls back to authenticated HTTP updates, waiting five seconds between completed -refreshes. The connection indicator identifies this fallback separately from -MQTT connectivity. WebSockets retry in the background every 30 seconds; receiving -a valid stream update restores live mode and stops polling. Closing Manager or -ending its session stops these retries. Requests time out after 15 seconds so a -stalled relay cannot leave a refresh pending indefinitely. This requires no new -configuration and does not change the Console's MQTT connection or authentication. - -### Architecture and API - -Console is public. Only Manager's API and live stream require a Manager session. -Set `M3TER_MANAGER_PASSWORD`; the optional username defaults to `admin`. -Missing passwords leave only Manager locked. Sessions use eight-hour HttpOnly, -SameSite cookies; logout, expiry, password changes and server restarts revoke them. -Credentials are never returned in API responses or browser storage. - -All manager operators share the configured administrator identity. Records and operations are scoped to `APPLICATION_ID`; -this does not introduce a separate multi-user/tenant authorization system. - -| Responsibility | Implementation | -| --- | --- | -| Desktop view and theme integration | `src/views/partials/m3ter-manager.hbs`, `src/public/css/m3ter-manager.css` | -| Selection, telemetry, navigation, live connection | `src/public/js/m3ter-manager.js` | -| Accessible SVG charts with pointer/keyboard inspection | `src/public/js/m3ter-charts.js` | -| Command forms, previews, confirmation, queue/history | `src/public/js/m3ter-commands.js` | -| Device discovery and scoped REST access | `src/m3ter/chirpstack.ts` | -| Decoder registry and existing decoder/signature reuse | `src/m3ter/decoder.ts` | -| MQTT ingestion, diagnostics, activity, delivery correlation | `src/m3ter/monitor.ts`, existing `src/services/mqtt.ts` | -| SQLite tables and historical queries | `src/m3ter/store.ts` | -| Command catalogue and exact frame generation | `src/m3ter/commands.ts` | -| Authenticated API and real-time stream | `src/m3ter/api.ts`, `src/services/socket-router.ts` | - -The shared WebSocket router checks browser request provenance without any origin -environment variable. `/m3ter-manager/live` also requires a Manager session; -`/terminal` uses the SSH credentials supplied inside its own application. - -All HTTP routes below are prefixed with `/api/m3ter-manager`: - -| Method | Route | Purpose | -| --- | --- | --- | -| GET / POST / DELETE | `/session` | Check access / sign in / sign out | -| GET | `/config` | Command catalogue, MQTT state, activity threshold | -| GET | `/devices?search=&offset=` | Name/DevEUI search, 50 devices per page | -| GET | `/devices/:devEui` | Sanitized device metadata, latest reading, known key | -| GET | `/devices/:devEui/history?from=&to=&offset=&limit=` | Millisecond UTC date range, reading page and chart samples | -| GET | `/devices/:devEui/events?offset=` | Device events and application-wide MQTT observations | -| GET | `/devices/:devEui/commands?offset=` | Persistent command history | -| POST | `/commands/preview` | Validate a command ID/parameter and produce exact bytes | -| POST | `/devices/:devEui/commands` | Validate and enqueue an unconfirmed downlink | -| GET | `/devices/:devEui/queue` | Up to 100 pending ChirpStack queue items | -| DELETE | `/devices/:devEui/queue` | Clear all queued items after explicit DevEUI confirmation | - -### Telemetry and historical data - -One MQTT client subscribes to -`application/{APPLICATION_ID}/device/+/event/+`. It validates both the topic and -event identity, handles `up`, `ack`, `txack`, `join`, `location`, `log`, and `status`, -and reconnects/resubscribes without creating another client when a meter changes. -Monitoring persistence and the existing collector are isolated consumers. A unique client ID is generated for each Console process. - -The usage-report decoder accepts **FPort 2, 74 or 106 bytes**. It wraps the -existing `decodePayload` implementation: uint32 BE nonce; uint32 BE energy divided -by 1,000,000; 64-byte Ed25519 signature; uint16 BE voltage divided by 10; optional -32-byte public key. Existing console keys and subsequently learned keys support -74-byte uplinks. Signature verification covers **only bytes 0–7**, not voltage. -A first-seen key establishes cryptographic consistency, not independently verified -device identity. Invalid/unverified signatures are labeled, never claimed valid. -No GPS is extracted from these payloads. Device location comes only from validated -ChirpStack device location events. A `phaseMode` device tag of `three-phase`, -`phase-a`, `phase-b`, or `phase-c` may describe configured metadata; it is not a -firmware acknowledgment. In three-phase metadata mode the dashboard separately -labels the transmitted voltage sum and calculated mean (sum / 3). - -Additive SQLite tables store raw MQTT payloads/metadata separately from decoded -readings, device state, and command audit history. Device/time indexes support -bounded queries. Uplinks deduplicate by ChirpStack event ID, or by a stable tuple -of device/event type/source time/frame counter/payload when an ID is absent. -Identical values with distinct events are preserved. Without an event ID or -source timestamp, events are retained separately rather than risking data loss. -Usage-report source timestamps are preserved in metadata; invalid timestamps use receipt time. The Overview's -Last Uplink uses the persisted console reception time of a successfully decoded, -non-duplicate FPort 2 uplink. FPort 4, MQTT heartbeats, connection events, UI refreshes and decode -errors cannot reset it. Source timestamps still drive the existing Analytics. - -MQTT payload transport is explicit: native ChirpStack `data` remains Base64; -hex producers supply `dataHex` or `data` with `dataEncoding: "hex"`. Hex must contain -complete byte pairs, without separators or a `0x` prefix. No alphabet guessing is -used. Both collector and Manager use the same byte conversion. Live Monitoring -shows the hexadecimal bytes and preserves the original field, encoding, and text -for inspection. The collector still receives only usage reports; monitoring never -causes an energy acknowledgment or a blockchain operation. - -#### FPort 4 electrical monitoring - -`src/m3ter/electrical.ts` implements the supplied Switch Cumulus version 1 layout: -exactly 97 bytes, big-endian, with signed active/reactive power, power factor, and -temperature. Other lengths/versions are retained as diagnostics without updating -meter state. Unsupported uplink ports are ignored. FPort 4 is never a downlink port. -Live Monitoring displays per-phase voltage/current/power/power factor, neutral -currents, frequency, temperature, cumulative forward/reverse counters, and reported -relay/phase/PGA status. No FPort 2 value substitutes for missing FPort 4 data. - -Native ChirpStack `data` is Base64. A valid `object` with `type: "telemetry"` is -preferred; unknown/incomplete schemas fall back to raw bytes. The current normalized -object adapter accepts `version`, `flags`, `uptime`, `voltage`/`current` (`a,b,c`), -`activePower`/`reactivePower`/`powerFactor`/`forwardEnergy`/`reverseEnergy` -(`a,b,c,total`), `neutralMeasured`, `neutralCalculated`, `frequency`, and `temperature`. -All values are already scaled in the units displayed. `type: "report"` objects -can supply `nonce`, `energy` (kWh), `voltage` (V), and `signature` (hex); raw report -bytes are still required for independent signature verification. Values are never -rescaled a second time. Original codec objects, payload text, and encoding are retained -for inspection. The referenced firmware files, `telemetry.md`, and upstream -`tools/chirpstack-codec.js` were not available in this checkout during implementation; -the adapter's compatibility with that codec's actual field names still needs verification. -Raw-byte support follows the complete layout supplied in the development request. - -Monitoring uses the actual ChirpStack `time`, retaining Console receipt time -separately. A missing/invalid measurement timestamp rejects that frame as a -diagnostic rather than substituting a UI refresh clock. Metadata includes device, -application, frame counter, deduplication ID, gateways, RSSI/SNR, and decoder source. -Deduplication uses the event ID, otherwise device/frame counter and observed boot -session (allowing counters to restart); a bounded persistent recent-key window -also protects against replay after history eviction. Delayed/equal-time frames -cannot replace the latest state or add energy. - -Per-channel forward/reverse differences are calculated in integer counter units. -The first frame establishes a baseline. Lower uptime starts a new boot baseline -without adding reset energy or erasing observed totals. An unexplained counter -decrease retains that channel's high-water baseline until recovery or reboot, -avoiding artificial consumption. Persistent totals mean **observed increases since -monitoring began**, not complete lifetime or billing totals. Gaps may omit power -samples but do not invalidate later counter differences. Average positive total -power × elapsed time / 3,600,000 is an advisory cross-check; a discrepancy greater -than max(0.01 kWh, 50% of the estimate) is explained, never used to rewrite counters. - -Freshness is separate from MQTT status and FPort 2 activity: stale after three -estimated intervals. Three consistent observed gaps establish cadence; otherwise -the last requested interval is explicitly provisional, or the 60-second firmware -default is labeled as cadence unknown. Enable/disable requests remain unverified; -subsequent frames provide evidence, and silence alone never proves disablement. - -Additive `manager_electrical_readings` and `manager_electrical_state` tables keep -monitoring separate from usage accounting. Raw frames remain in `manager_events`. -Both new tables are initialized safely on an existing database; no original table -is rebuilt. `GET /api/m3ter-manager/devices/:devEui/telemetry` provides the latest -state and paginated monitoring history (50 rows, `offset` parameter), protected by -the existing Manager session and application scope. - -Charts plot **raw accumulator snapshots**, not independent interval consumption. -Repeated and growing values with the same nonce stay pending. A consecutive nonce -advance closes the previous observed cycle: its high-water mark is a **lower bound**, -not proof of a billed or settled amount. Where the local collector recorded that -cycle, its exact accepted energy is shown separately. Nonce zero is not repeatedly -credited. Decreases, nonce gaps/regressions, invalid signatures and delayed reports -are flagged, not credited as fresh consumption. Manager sends no automatic acknowledgments. -Firmware source is not present here: observed transitions cannot establish unobserved -energy, reset causes, downlink execution, or blockchain settlement. - -The database retains **100 usage-report records globally by default**, including malformed -payloads. Set optional `M3TER_TELEMETRY_LIMIT` to a positive integer to change this -limit. Invalid values log a warning and safely fall back to 100. The limit applies -on startup and after every insertion, and prunes their raw event copies too. A separate small per-device state -preserves the pending nonce/high-water mark and latest reading after eviction or -restart. Existing history is replayed once before migration trims it. Non-telemetry activity, command history, device configuration and all -original Console tables are preserved. SQLite reuses freed pages; migration does -not rewrite or vacuum unrelated tables. Date ranges cover the retained window only. -FPort 4 has a separate **global cap using the same `M3TER_TELEMETRY_LIMIT`** (default -100), including monitoring decode failures and raw event copies. Thus up to 100 -usage reports plus 100 monitoring records are retained by default. FPort 4 cannot -evict usage history. Monitoring baselines, latest sample, and observed totals survive -both pruning and process restarts. Command records and original Console data are untouched. - -### Command safety and delivery evidence - -All existing command types remain, with four additional telemetry actions (three -firmware command codes) defined centrally: - -| Action | FPort | Hex | Base64 | -| --- | --- | --- | --- | -| Enable telemetry | 2 | `2301` | `IwE=` | -| Disable telemetry | 2 | `2300` | `IwA=` | -| Telemetry interval: 60 seconds | 2 | `24003C` | `JAA8` | -| Telemetry interval: 300 seconds | 2 | `24012C` | `JAEs` | -| Request Telemetry Now | 2 | `25` | `JQ==` | - -Intervals are 10–65535 seconds; disable requires confirmation. Firmware v1.0.4+ -is required for these new operations, and older-meter support is not inferred -merely from device discovery. Existing preview, idempotency, history, and queue -controls apply to all new actions. - -The backend reconstructs payloads from IDs and validated integer parameters, -enforces lengths and FPorts 2/3, and rejects raw payload/FPort overrides. Class B, -calibration, and FUOTA ports 200–202 are not exposed. Billing, restart, relay -hardware, and Class A controls require explicit confirmation. Queue clearing -requires a confirmation naming the selected DevEUI and removes all pending items, -including items created by other applications. - -Commands are recorded before enqueueing. A UUID request ID makes a repeated -submission idempotent, including retry after a lost HTTP response. A timeout or -ambiguous upstream failure is **unknown**, not automatically retried. Inspect the -queue before issuing a new request. A console restart marks interrupted enqueues -unknown. The upstream queue item uses the same UUID for event correlation. - -`queued` means REST acceptance; the Queue tab shows pending delivery. -`transmitted` means a gateway `txack`, **not** proven device delivery. Only an -acknowledged `ack` event marks `delivered`; even this does not prove firmware -execution. Commands default to unconfirmed, so device acknowledgments may never -arrive. Events match both DevEUI and queue item ID; no relay state or applied -configuration is inferred from queue acceptance. Confirmed deliveries are retained -when a queue is cleared. MQTT activity/inactivity is explicitly observational. - -### Validation and preview boundaries - -```sh -npm test -- --runInBand -npm run test:ui -npm run preview:ui -``` - -The preview at `http://127.0.0.1:4173` includes a **labeled simulated M3TER network**. -Sign in there with **`demo` / `demo-manager`** (preview only). -Its local REST and MQTT simulators never contact real meters; downlinks there only -modify fixture queues. Browser integration tests exercise the production API, -SQLite store, authenticated WebSocket routing, and a real MQTT.js TCP connection -to a simulator. Unit tests cover every supplied command Base64 value, parameter -boundaries, payload lengths and scaling, signatures, isolation, deduplication, -reset segments, persistence, and pagination. Browser tests cover switching meters, -MQTT reconnection, command confirmation/idempotency, queue operations, error -recovery, charts and all four themes on desktop/tablet/phone sizes. - -The referenced firmware source is not included in this checkout; implementation -uses the supplied firmware specification and existing console decoder. No live -ChirpStack/meter validation is implied by simulator test results. Richer telemetry -decoders and command-specific firmware acknowledgments are not implemented without -their firmware specifications. The current protocol cannot verify relay state, -the applied reporting interval, restart completion, or applied phase configuration. - ## ChirpStack desktop application Open **ChirpStack** from the desktop, dock, or application launcher. Its web @@ -381,7 +90,7 @@ or use an HTTPS origin. Only an origin is supported, without credentials or a subpath. In Docker this address must be reachable from the console container. Sign in with your **ChirpStack credentials** inside the app. There is no Console -login wrapping the proxy. Its Bearer token is forwarded; Manager cookies and the +login wrapping the proxy. Its Bearer token is forwarded; Console cookies and the server's `API_TOKEN` are never forwarded as browser credentials. ChirpStack browser storage is namespaced so its logout cannot erase desktop preferences. Reload restarts the embedded page; theme changes and minimizing @@ -961,7 +670,7 @@ Use the original project name and data directory to preserve the same volumes. The old **M3ters** meter-list application has been removed from the desktop, along with its exclusive `/delete-meter` UI endpoint. The collector's database, -MQTT service, and meter records are preserved. **M3ter Manager** remains available. +MQTT service, and meter records are preserved. The removed M3ter Manager is no longer available. The Browser starts with a Google search interface. Queries use `https://www.google.com/search?q=` with URL encoding and open in a new tab because @@ -969,9 +678,9 @@ Google blocks embedded search pages. HTTP(S) addresses can still open inside the Browser; its external link supports sites that block embedding. `compose.yaml` passes the existing `.env` into the single Console container, -which hosts both consumers. The update script leaves that file and persistent -volumes intact, including `MQTT_URL`, `CHEFSTACK_URL`, `M3TER_TELEMETRY_LIMIT`, and -`M3TER_MANAGER_PASSWORD`. No deployment-script or workflow changes are required. +which hosts the collector. The update script leaves that file and persistent +volumes intact, including `MQTT_URL` and `CHEFSTACK_URL`. Obsolete Manager settings +are ignored with one startup warning; their values are never logged. Application feedback is scoped to its owning window. Extension actions preserve the originating window even if another app is focused while a request completes. @@ -980,3 +689,27 @@ pass `null` for a desktop-wide notice. `AppFeedback.showDialog(dialog, appElemen provides an app-contained dialog; `AppFeedback.confirm(appElement, title, message)` returns a promise for confirmations. These dialogs allow switching to other apps and inherit the owning application's light/dark mode. + +## Changes on the centralized Console feature branch + +M3ter Manager has been removed in every role. This removes its meter command +controls (relay, interval, class, gain and phase), telemetry history, charts and +raw event inspector. Use the ChirpStack app's device queue for technician downlinks +and your monitoring platform for telemetry. The Console billing collector and +its protocol remain intact. + +Existing Manager database tables are not dropped or modified during startup. +To remove them manually, first stop Console and back up `.data/m3tering.db`, then +run the following only against the backup-reviewed deployment database: + +```sh +sqlite3 .data/m3tering.db 'BEGIN; DROP TABLE IF EXISTS manager_readings; DROP TABLE IF EXISTS manager_electrical_readings; DROP TABLE IF EXISTS manager_events; DROP TABLE IF EXISTS manager_commands; DROP TABLE IF EXISTS manager_accumulators; DROP TABLE IF EXISTS manager_electrical_state; DROP TABLE IF EXISTS manager_devices; DROP TABLE IF EXISTS manager_schema; COMMIT;' +``` + +This optional cleanup deletes historical Manager data permanently. It does not +touch `meters` or `transactions`. No update or startup runs it automatically. + +The feature's [architecture inventory](docs/centralized/current-architecture.md) +and [design decisions](docs/centralized/design.md) track the central/agent work. +The feature is not ready for deployment until its documented safety gates and +integration tests are complete. diff --git a/src/index.ts b/src/index.ts index 735df38..0ea51ad 100644 --- a/src/index.ts +++ b/src/index.ts @@ -6,8 +6,10 @@ attachTerminal(server); import { loadExtensionsFromConfig, loadUIExtensionsFromConfig, runHook, notifyHook } from './lib/utils'; import setupDatabase from './store/sqlite'; import { createLogger } from './utils/logger'; +import { warnRemovedManagerSettings } from './lib/legacy-config'; const logger = createLogger('[index]'); +warnRemovedManagerSettings(process.env, message => logger.warn(message)); (async function () { try { diff --git a/src/lib/chirpstack-config.ts b/src/lib/chirpstack-config.ts new file mode 100644 index 0000000..8d6a363 --- /dev/null +++ b/src/lib/chirpstack-config.ts @@ -0,0 +1,8 @@ +/** Shared collector/agent configuration. Never logs connection credentials. */ +export function applicationId(): string { + const id = process.env.APPLICATION_ID; + if (!id || !/^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/i.test(id)) { + throw new Error('Configure APPLICATION_ID with your ChirpStack application UUID.'); + } + return id.toLowerCase(); +} diff --git a/src/lib/legacy-config.ts b/src/lib/legacy-config.ts new file mode 100644 index 0000000..9141a22 --- /dev/null +++ b/src/lib/legacy-config.ts @@ -0,0 +1,7 @@ +/** Kept outside role configuration so obsolete settings cannot prevent startup. */ +export function warnRemovedManagerSettings(env: NodeJS.ProcessEnv, warn: (message: string) => void): void { + if (Object.keys(env).some(name => name.startsWith('M3TER_MANAGER_') || + name === 'M3TER_TELEMETRY_LIMIT' || name === 'M3TER_INACTIVE_SECONDS')) { + warn('M3ter Manager has been removed; its legacy environment settings are ignored.'); + } +} diff --git a/src/m3ter/decoder.ts b/src/lib/protocol/decoder.ts similarity index 96% rename from src/m3ter/decoder.ts rename to src/lib/protocol/decoder.ts index 7a102c9..441ec68 100644 --- a/src/m3ter/decoder.ts +++ b/src/lib/protocol/decoder.ts @@ -1,5 +1,5 @@ -import { decodePayload } from '../lib/decode'; -import { verifyPayloadSignature } from '../lib/utils'; +import { decodePayload } from '../decode'; +import { verifyPayloadSignature } from '../utils'; import { decodeElectrical, ElectricalTelemetry } from './electrical'; export type Telemetry = { diff --git a/src/m3ter/electrical.ts b/src/lib/protocol/electrical.ts similarity index 100% rename from src/m3ter/electrical.ts rename to src/lib/protocol/electrical.ts diff --git a/src/m3ter/accumulator.ts b/src/m3ter/accumulator.ts deleted file mode 100644 index ec81dc8..0000000 --- a/src/m3ter/accumulator.ts +++ /dev/null @@ -1,39 +0,0 @@ -/** Monitoring only. A snapshot is pending, never an independent billing interval. - * A consecutive nonce transition supports a completed-cycle observation, not - * proof of blockchain settlement. Only the collector supplies accepted energy. - */ -export type Accumulator = { - nonce: number; segment: number; highWater: number; timestamp: number; uncertain: boolean; - acceptedRaw: number | null; completedObserved: number; completedCollected: number; -}; -export function advance(previous: Accumulator | null, nonce: number, rawEnergy: number, timestamp: number) { - let accounting = 'pending'; - let completedNonce: number | null = null, intervalEnergy: number | null = null, collectedEnergy: number | null = null; - if (previous && timestamp < previous.timestamp) return { state: previous, accounting: 'late-report', completedNonce, intervalEnergy, collectedEnergy }; - const state: Accumulator = previous ? { ...previous, timestamp, segment: previous.segment || 0 } : { - nonce, segment: 0, highWater: rawEnergy, timestamp, uncertain: false, acceptedRaw: null, completedObserved: 0, completedCollected: 0, - }; - if (previous) { - if (nonce === previous.nonce) { - accounting = rawEnergy === previous.highWater ? 'repeated-total' : rawEnergy < previous.highWater ? 'counter-reset-uncertain' : 'pending'; - state.highWater = Math.max(previous.highWater, rawEnergy); - state.uncertain ||= rawEnergy < previous.highWater; - if (rawEnergy < previous.highWater) state.segment++; - } else { - state.segment++; - const consecutive = nonce === previous.nonce + 1; - if (consecutive && !previous.uncertain) { - completedNonce = previous.nonce; - intervalEnergy = previous.highWater / 1e6; // observed lower bound, not a billed amount - collectedEnergy = previous.acceptedRaw === null ? null : previous.acceptedRaw / 1e6; - state.completedObserved += intervalEnergy; - state.completedCollected += collectedEnergy || 0; - accounting = 'cycle-advanced'; - } else accounting = consecutive ? 'uncertain-cycle-ended' : 'nonce-reset-or-gap'; - state.nonce = nonce; state.highWater = rawEnergy; state.acceptedRaw = null; - // A consecutive transition establishes the next cycle's baseline. - state.uncertain = !consecutive; - } - } - return { state, accounting, completedNonce, intervalEnergy, collectedEnergy }; -} diff --git a/src/m3ter/api.ts b/src/m3ter/api.ts deleted file mode 100644 index b0db9e5..0000000 --- a/src/m3ter/api.ts +++ /dev/null @@ -1,143 +0,0 @@ -import { Router, Request, Response, NextFunction } from 'express'; -import type http from 'http'; -import WebSocket from 'ws'; -import { registerSocket } from '../services/socket-router'; -import { applicationId, chirpstackRest, deviceDetails, deviceId, getDevice, listDevices, ManagerError } from './chirpstack'; -import { commandCatalogue, generateCommand } from './commands'; -import { checkActivity, inactiveMilliseconds, managerEvents, monitoring } from './monitor'; -import * as store from './store'; -import { electricalSnapshot, electricalHistory } from './electrical-store'; -import { managerAuthRouter, requireManagerAuth, managerAuthenticated, managerSessions } from './auth'; - -export const managerRouter = Router(); -managerRouter.use(managerAuthRouter); -managerRouter.use(requireManagerAuth); -const wrap = (handler: (req: Request, res: Response) => Promise | void) => (req: Request, res: Response, next: NextFunction) => Promise.resolve().then(() => handler(req, res)).catch(next); -function integer(value: unknown, fallback: number, min: number, max: number): number { - if (value === undefined) return fallback; - const n = Number(value); - if (typeof value !== 'string' || !/^\d+$/.test(value) || !Number.isSafeInteger(n) || n < min || n > max) throw new ManagerError('Invalid pagination or date range.'); - return n; -} -function commandInput(body: any) { - if (!body || typeof body !== 'object' || Array.isArray(body) || Object.keys(body).some(key => !['commandId','value','confirmedSafety','requestId'].includes(key))) { - throw new ManagerError('Supply a supported command and parameter; raw payloads and FPorts are not accepted.'); - } - try { return generateCommand(body.commandId, body.value); } catch (error) { throw new ManagerError((error as Error).message); } -} -const busy = new Set(); -async function exclusive(devEui: string, work: () => Promise) { - if (busy.has(devEui)) throw new ManagerError('Another queue operation is in progress for this meter.', 409); - busy.add(devEui); try { await work(); } finally { busy.delete(devEui); } -} -managerRouter.get('/config', wrap((_req, res) => { - res.json({ commands: commandCatalogue, monitoring, inactiveMilliseconds: inactiveMilliseconds(), applicationId: applicationId(), - billingAutomationActive: true }); -})); -managerRouter.get('/devices', wrap(async (req, res) => { - const search = typeof req.query.search === 'string' ? req.query.search.trim() : ''; - if (search.length > 100) throw new ManagerError('Search is too long.'); - res.json(await listDevices(search, integer(req.query.offset, 0, 0, 1_000_000))); -})); -managerRouter.get('/devices/:devEui', wrap(async (req, res) => { - const devEui = deviceId(req.params.devEui), application = applicationId(); - const details = await deviceDetails(devEui); - store.updateDevice(application, devEui, details); - res.json({ device: details, state: store.deviceState(application, devEui), latest: store.latestReading(application, devEui), electrical: electricalSnapshot(application, devEui) }); -})); -managerRouter.get('/devices/:devEui/history', wrap((req, res) => { - const devEui = deviceId(req.params.devEui), application = applicationId(); - const to = integer(req.query.to, Date.now(), 1, 8640000000000000); - const from = integer(req.query.from, to - 86400000, 0, to); - if (to - from > 366 * 86400000) throw new ManagerError('Choose a range of at most 366 days.'); - res.json({ ...store.history(application, devEui, from, to, integer(req.query.offset, 0, 0, 1_000_000), integer(req.query.limit, 50, 1, 100)), - latest: store.latestReading(application, devEui), state: store.deviceState(application, devEui), monitoring, electrical: electricalSnapshot(application, devEui) }); -})); -managerRouter.get('/devices/:devEui/telemetry', wrap((req, res) => { - const application = applicationId(), devEui = deviceId(req.params.devEui); - res.json({ ...electricalSnapshot(application,devEui), ...electricalHistory(application,devEui,integer(req.query.offset,0,0,1_000_000)) }); -})); -managerRouter.get('/devices/:devEui/events', wrap((req, res) => { - res.json({ events: store.events(applicationId(), deviceId(req.params.devEui), integer(req.query.offset, 0, 0, 1_000_000)) }); -})); -managerRouter.get('/devices/:devEui/commands', wrap((req, res) => { - res.json({ commands: store.commandHistory(applicationId(), deviceId(req.params.devEui), integer(req.query.offset, 0, 0, 1_000_000)) }); -})); -managerRouter.post('/commands/preview', wrap((req, res) => { res.json(commandInput(req.body)); })); -managerRouter.post('/devices/:devEui/commands', wrap(async (req, res) => { - const devEui = deviceId(req.params.devEui), application = applicationId(), command = commandInput(req.body); - if (command.requiresConfirmation && req.body.confirmedSafety !== true) throw new ManagerError('Explicit safety confirmation is required.'); - const id = req.body.requestId; - if (typeof id !== 'string' || !/^[a-f\d]{8}-[a-f\d]{4}-4[a-f\d]{3}-[89ab][a-f\d]{3}-[a-f\d]{12}$/i.test(id)) throw new ManagerError('A UUID requestId is required.'); - const fingerprint = JSON.stringify([devEui, command.id, command.value]); - const previous = store.getCommand(application, id); - if (previous) { - if (previous.fingerprint !== fingerprint) throw new ManagerError('This request ID belongs to a different command.', 409); - res.json(previous); return; - } - await exclusive(devEui, async () => { - await getDevice(devEui); - store.insertCommand(application, devEui, id, command, fingerprint); - try { - await chirpstackRest(`/api/devices/${devEui}/queue`, 'POST', { queueItem: { id, devEui, confirmed: false, fPort: command.fPort, data: command.data } }); - store.commandStatus(application, devEui, id, 'queued', 'Accepted by ChirpStack; delivery and execution are not verified'); - store.applicationEvent(application, devEui, 'command-queued', `${command.name} accepted into the downlink queue`); - } catch (error) { - const uncertain = !(error instanceof ManagerError) || error.uncertain; - store.commandStatus(application, devEui, id, uncertain ? 'unknown' : 'failed', uncertain ? 'Enqueue outcome unknown. Inspect the queue before creating another command.' : (error as Error).message); - } - managerEvents.emit('update', { type: 'device', devEui, kind: 'command' }); - res.json(store.getCommand(application, id)); - }); -})); -managerRouter.get('/devices/:devEui/queue', wrap(async (req, res) => { - const devEui = deviceId(req.params.devEui); await getDevice(devEui); - const queue = await chirpstackRest(`/api/devices/${devEui}/queue?limit=100&offset=0`); - const items = (Array.isArray(queue.result) ? queue.result : []).map((item: any) => ({ - id: item.id || null, fPort: item.fPort, data: item.data || '', hex: typeof item.data === 'string' ? Buffer.from(item.data, 'base64').toString('hex').toUpperCase() : '', - confirmed: item.confirmed === true, isPending: item.isPending === true, fCntDown: item.fCntDown ?? null, - expiresAt: item.expiresAt || null, createdAt: item.createdAt || null, - })); - res.json({ items, total: Number(queue.totalCount) || items.length }); -})); -managerRouter.delete('/devices/:devEui/queue', wrap(async (req, res) => { - const devEui = deviceId(req.params.devEui), application = applicationId(); - if (req.body?.confirmDevEui !== devEui) throw new ManagerError('Confirm the selected DevEUI to clear all pending downlinks.'); - await exclusive(devEui, async () => { - await getDevice(devEui); await chirpstackRest(`/api/devices/${devEui}/queue`, 'DELETE'); - store.clearedCommands(application, devEui); - store.applicationEvent(application, devEui, 'queue-cleared', 'All pending downlinks cleared. Previously transmitted commands cannot be recalled.'); - managerEvents.emit('update', { type: 'device', devEui, kind: 'queue' }); res.json({ cleared: true }); - }); -})); -managerRouter.use((error: unknown, _req: Request, res: Response, _next: NextFunction) => { - res.status(error instanceof ManagerError ? error.status : 503).json({ error: error instanceof ManagerError ? error.message : 'Meter data is temporarily unavailable. Check database availability and retry.' }); -}); - -export function attachManagerStream(server: http.Server): void { - const wss = new WebSocket.Server({ noServer: true, maxPayload: 1024 }); - registerSocket(server, '/m3ter-manager/live', wss, managerAuthenticated); - const requests = new Map(); - const revoke = () => { for (const [ws, req] of requests) if (!managerAuthenticated(req)) { ws.close(4001, 'Sign in required'); requests.delete(ws); } }; - managerSessions.on('change', revoke); - const clients = new Map(); - const send = (ws: WebSocket, data: unknown) => { - if (ws.readyState === WebSocket.OPEN) { if (ws.bufferedAmount > 64 * 1024) ws.terminate(); else ws.send(JSON.stringify(data)); } - }; - const broadcast = (update: unknown) => { revoke(); for (const ws of clients.keys()) if (requests.has(ws)) send(ws, update); }; - managerEvents.on('update', broadcast); - wss.on('connection', (ws, req) => { - if (clients.size >= 100) { ws.close(1013, 'Too many monitoring clients'); return; } - requests.set(ws, req); clients.set(ws, true); send(ws, { type: 'connection', monitoring }); - ws.on('pong', () => clients.set(ws, true)); - ws.on('error', () => ws.terminate()); ws.on('close', () => { clients.delete(ws); requests.delete(ws); }); - ws.on('message', () => ws.close(1008, 'This is a receive-only monitoring stream')); - }); - const timer = setInterval(() => { - checkActivity(); - for (const [ws, alive] of clients) { if (!alive) { ws.terminate(); clients.delete(ws); } else { clients.set(ws, false); ws.ping(); } } - broadcast({ type: 'connection', monitoring }); - }, 30_000); - timer.unref(); - server.on('close', () => { clearInterval(timer); managerSessions.off('change', revoke); managerEvents.off('update', broadcast); for (const ws of clients.keys()) ws.terminate(); wss.close(); }); -} diff --git a/src/m3ter/auth.ts b/src/m3ter/auth.ts deleted file mode 100644 index 799cc5e..0000000 --- a/src/m3ter/auth.ts +++ /dev/null @@ -1,63 +0,0 @@ -import { createHash, randomBytes, timingSafeEqual } from 'crypto'; -import { EventEmitter } from 'events'; -import type { IncomingMessage } from 'http'; -import { Router, Request, Response, NextFunction } from 'express'; - -const cookie = 'm3ter_manager_session'; -const lifetime = 8 * 60 * 60 * 1000; -const sessions = new Map(); -const failures = new Map(); -export const managerSessions = new EventEmitter(); -const hash = (value: string) => createHash('sha256').update(value).digest(); -function configuredUsername() { return process.env.M3TER_MANAGER_USERNAME || 'admin'; } -function configured() { return !!process.env.M3TER_MANAGER_PASSWORD; } -function identity() { return hash(JSON.stringify([configuredUsername(), process.env.M3TER_MANAGER_PASSWORD])).toString('hex'); } -function token(req: IncomingMessage): string { - return (req.headers.cookie || '').split(';').map(part => part.trim()).find(part => part.startsWith(cookie + '='))?.slice(cookie.length + 1) || ''; -} -export function managerAuthenticated(req: IncomingMessage): boolean { - const session = sessions.get(token(req)); - return !!(configured() && session && session.expires > Date.now() && session.identity === identity()); -} -export function requireManagerAuth(req: Request, res: Response, next: NextFunction): void { - res.setHeader('Cache-Control', 'no-store'); - if (!managerAuthenticated(req)) { res.status(401).json({ error: 'Sign in to M3ter Manager to continue.' }); return; } - next(); -} -function setCookie(req: Request, res: Response, value: string, maxAge: number) { - res.cookie(cookie, value, { httpOnly: true, sameSite: 'strict', path: '/', maxAge, - secure: req.secure || req.headers.origin?.startsWith('https://') === true }); -} -export const managerAuthRouter = Router(); -managerAuthRouter.use((_req, res, next) => { res.setHeader('Cache-Control', 'no-store'); next(); }); -managerAuthRouter.get('/session', (req, res) => { - const authenticated = managerAuthenticated(req); - res.json({ authenticated, configured: configured() }); -}); -managerAuthRouter.post('/session', (req, res) => { - if (!configured()) { res.status(503).json({ error: 'Set M3TER_MANAGER_PASSWORD (and optionally M3TER_MANAGER_USERNAME) in .env, then restart the console.' }); return; } - const now = Date.now(), address = req.socket.remoteAddress || 'unknown'; - for (const [key, value] of failures) if (value.until <= now) failures.delete(key); - for (const [key, value] of sessions) if (value.expires <= now || value.identity !== identity()) sessions.delete(key); - const attempts = failures.get(address); - if (attempts && attempts.count >= 10) { res.setHeader('Retry-After', Math.ceil((attempts.until - now) / 1000)); res.status(429).json({ error: 'Too many sign-in attempts. Try again in 15 minutes.' }); return; } - const { username, password } = req.body || {}; - const validInput = typeof username === 'string' && typeof password === 'string' && username.length <= 256 && password.length <= 4096; - // Compare both fixed-length hashes, without exposing which field was incorrect. - const userMatches = timingSafeEqual(hash(validInput ? username : ''), hash(configuredUsername())); - const passwordMatches = timingSafeEqual(hash(validInput ? password : ''), hash(process.env.M3TER_MANAGER_PASSWORD!)); - if (!validInput || !userMatches || !passwordMatches) { - if (failures.size >= 10000 && !failures.has(address)) { res.status(429).json({ error: 'Sign-in is temporarily busy. Try again later.' }); return; } - failures.set(address, { count: (attempts?.count || 0) + 1, until: attempts?.until || now + 900000 }); - // Invalid credentials are distinct from an expired Manager session (401). - res.status(403).json({ error: 'Incorrect username or password.' }); return; - } - failures.delete(address); - if (sessions.size >= 1000) { res.status(503).json({ error: 'Too many active sessions. Try again later.' }); return; } - sessions.delete(token(req)); - const value = randomBytes(32).toString('hex'); sessions.set(value, { expires: now + lifetime, identity: identity() }); - setCookie(req, res, value, lifetime); res.json({ authenticated: true }); managerSessions.emit('change'); -}); -managerAuthRouter.delete('/session', (req, res) => { - sessions.delete(token(req)); setCookie(req, res, '', 0); managerSessions.emit('change'); res.json({ authenticated: false }); -}); diff --git a/src/m3ter/chirpstack.ts b/src/m3ter/chirpstack.ts deleted file mode 100644 index ed898f9..0000000 --- a/src/m3ter/chirpstack.ts +++ /dev/null @@ -1,61 +0,0 @@ -export class ManagerError extends Error { - constructor(message: string, public status = 400, public uncertain = false) { super(message); } -} -export function applicationId(): string { - const id = process.env.APPLICATION_ID; - if (!id || !/^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/i.test(id)) throw new ManagerError('Configure APPLICATION_ID with your ChirpStack application UUID.', 503); - return id.toLowerCase(); -} -export function deviceId(value: unknown): string { - if (typeof value !== 'string' || !/^[\da-f]{16}$/i.test(value)) throw new ManagerError('DevEUI must contain exactly 16 hexadecimal characters.'); - return value.toLowerCase(); -} -export async function chirpstackRest(path: string, method = 'GET', body?: unknown): Promise { - if (!process.env.API_TOKEN || process.env.API_TOKEN === '...') throw new ManagerError('Configure the ChirpStack API_TOKEN on the console server.', 503); - let origin: URL; - try { - const host = process.env.CHIRPSTACK_HOST || 'localhost'; - origin = new URL(process.env.CHIRPSTACK_REST_URL || `http://${host.includes(':') && !host.startsWith('[') ? `[${host}]` : host}:8090`); - if (!['http:', 'https:'].includes(origin.protocol) || origin.username || origin.password || origin.pathname !== '/' || origin.search || origin.hash) throw new Error(); - } catch { throw new ManagerError('CHIRPSTACK_REST_URL must be an HTTP(S) origin without credentials or a path.', 503); } - let response: globalThis.Response; - try { - response = await fetch(new URL(path, origin), { method, redirect: 'error', signal: AbortSignal.timeout(10_000), - headers: { Authorization: `Bearer ${process.env.API_TOKEN}`, 'Content-Type': 'application/json' }, body: body === undefined ? undefined : JSON.stringify(body) }); - } catch { throw new ManagerError('ChirpStack REST proxy is unreachable or timed out. Check its address and service status.', 502, method !== 'GET'); } - if (!response.ok) { - const message = response.status === 401 || response.status === 403 ? 'ChirpStack rejected the API token or its permissions.' : - response.status === 404 ? 'The device or ChirpStack REST endpoint was not found.' : 'ChirpStack rejected the request. Refresh the queue before retrying.'; - throw new ManagerError(message, response.status === 404 ? 404 : 502, method !== 'GET' && response.status >= 500); - } - if (response.status === 204) return {}; - try { const text = await response.text(); return text ? JSON.parse(text) : {}; } - catch { throw new ManagerError('ChirpStack returned an invalid response.', 502, method !== 'GET'); } -} -export async function listDevices(search: string, offset: number) { - const query = new URLSearchParams({ applicationId: applicationId(), limit: '50', offset: String(offset), search }); - const result = await chirpstackRest(`/api/devices?${query}`); - return { total: Number(result.totalCount) || 0, offset, limit: 50, devices: (Array.isArray(result.result) ? result.result : []).map((device: any) => ({ - devEui: deviceId(device.devEui), name: String(device.name || device.devEui), deviceProfileName: device.deviceProfileName || null, - deviceProfileId: device.deviceProfileId || null, lastSeenAt: device.lastSeenAt || null, description: device.description || null, - })) }; -} -export async function getDevice(devEui: string) { - const result = await chirpstackRest(`/api/devices/${deviceId(devEui)}`); - if (result.device?.applicationId !== applicationId()) throw new ManagerError('This meter is outside the configured application.', 403); - return result; -} -export async function deviceDetails(devEui: string) { - const result = await getDevice(devEui); - const device = result.device; - const [profile, application] = await Promise.allSettled([ - chirpstackRest(`/api/device-profiles/${encodeURIComponent(device.deviceProfileId || '')}`), - chirpstackRest(`/api/applications/${applicationId()}`), - ]); - const phase = device.tags?.phaseMode; - return { devEui, name: device.name || devEui, description: device.description || null, applicationId: applicationId(), - applicationName: application.status === 'fulfilled' ? application.value.application?.name || null : null, - deviceProfileId: device.deviceProfileId || null, deviceProfileName: profile.status === 'fulfilled' ? profile.value.deviceProfile?.name || null : null, - enabledClass: result.enabledClass || null, lastSeenAt: result.lastSeenAt || null, isDisabled: device.isDisabled === true, - phaseMode: ['three-phase', 'phase-a', 'phase-b', 'phase-c'].includes(phase) ? phase : null }; -} diff --git a/src/m3ter/commands.ts b/src/m3ter/commands.ts deleted file mode 100644 index 8210288..0000000 --- a/src/m3ter/commands.ts +++ /dev/null @@ -1,51 +0,0 @@ -export type CommandDefinition = { - id: string; name: string; category: string; fPort: 2 | 3; code: number; - description: string; confirmation?: string; options?: { value: number; label: string }[]; - min?: number; max?: number; defaultValue?: number; - fixedValue?: number; -}; -const gain = [1, 2, 4].map(value => ({ value, label: `×${value}` })); -const billing = 'The relay will change state, the energy accumulator will reset to zero, and the nonce will increment.'; -export const commandCatalogue: CommandDefinition[] = [ - { id: 'relay-on', name: 'Relay ON', category: 'Relay control', fPort: 2, code: 0x1b, description: 'Close the relay. Energy and nonce remain unchanged.' }, - { id: 'relay-off', name: 'Relay OFF', category: 'Relay control', fPort: 2, code: 0x1c, description: 'Open the relay. Energy and nonce remain unchanged.' }, - { id: 'billing-disconnect', name: 'Disconnect (Billing)', category: 'Billing connectivity', fPort: 2, code: 0, description: 'Open the relay and reset the billing accumulator.', confirmation: billing }, - { id: 'billing-connect', name: 'Connect (Billing)', category: 'Billing connectivity', fPort: 2, code: 1, description: 'Close the relay and reset the billing accumulator.', confirmation: billing }, - { id: 'report-interval', name: 'Set report interval', category: 'Reporting configuration', fPort: 2, code: 2, min: 10, max: 65535, defaultValue: 60, description: 'Set the reporting interval in seconds. Values below 60 seconds consume more LoRaWAN airtime.' }, - { id: 'restart', name: 'Restart meter', category: 'Maintenance', fPort: 2, code: 0x1d, description: 'Software reset and rejoin; telemetry may stop for approximately 10–60 seconds.', confirmation: 'Restart this meter? Telemetry may stop while it restarts and rejoins. Enqueueing does not confirm a restart.' }, - { id: 'relay-drive', name: 'Relay drive level', category: 'Relay hardware', fPort: 2, code: 0x1e, options: [{ value: 1, label: 'Active high' }, { value: 0, label: 'Active low' }], description: 'Set the output level that activates the physical relay.', confirmation: 'An incorrect drive level can invert relay ON/OFF behavior. Check the physical driver circuit before continuing.' }, - { id: 'relay-fitted', name: 'Relay fitted', category: 'Relay hardware', fPort: 2, code: 0x1f, options: [{ value: 1, label: 'Relay fitted' }, { value: 0, label: 'No relay fitted' }], description: 'Configure whether a relay is installed.', confirmation: 'When no relay is fitted, firmware ignores disconnect commands. Confirm the actual hardware configuration.' }, - { id: 'current-gain', name: 'Current gain (PGA)', category: 'Amplifier gain', fPort: 2, code: 0x20, options: gain, description: 'Firmware converts saved calibration. For 2000:1 CTs and a 5.6 Ω burden, ×2 suits up to approximately 128 A; ×4 suits lighter loads up to approximately 64 A.' }, - { id: 'voltage-gain', name: 'Voltage gain (PGA)', category: 'Amplifier gain', fPort: 2, code: 0x21, options: gain, description: 'Set voltage-channel gain. The normal configuration is ×1.' }, - { id: 'phase-mode', name: 'Phase mode', category: 'Phase configuration', fPort: 2, code: 0x22, options: [{ value: 0, label: 'Three-phase' }, { value: 1, label: 'Phase A' }, { value: 2, label: 'Phase B' }, { value: 3, label: 'Phase C' }], description: 'Select reported phases without resetting energy. Three-phase reports total energy and the SUM of phase voltages (about 690 V on a 230 V system). A queued mode is not verified configuration.' }, - { id: 'class-a', name: 'Switch to Class A', category: 'LoRaWAN class', fPort: 3, code: 0, description: 'Downlinks become available only after an uplink.', confirmation: 'Switch to Class A? Future downlinks must wait for an uplink. Class C is the normal operating mode.' }, - { id: 'class-c', name: 'Switch to Class C', category: 'LoRaWAN class', fPort: 3, code: 2, description: 'Request the normal Class C operating mode. A reachable Class C meter can receive downlinks without waiting for an uplink.' }, - { id: 'telemetry-enable', name: 'Enable telemetry', category: 'Monitoring telemetry', fPort: 2, code: 0x23, fixedValue: 1, description: 'Enable periodic FPort 4 electrical monitoring (firmware v1.0.4+). Subsequent frames provide evidence of operation; queue acceptance is not confirmation.' }, - { id: 'telemetry-disable', name: 'Disable telemetry', category: 'Monitoring telemetry', fPort: 2, code: 0x23, fixedValue: 0, description: 'Stop periodic monitoring; FPort 2 usage reports continue.', confirmation: 'Disable periodic FPort 4 telemetry? Monitoring will become stale. Silence alone cannot confirm that the setting was applied.' }, - { id: 'telemetry-interval', name: 'Set telemetry interval', category: 'Monitoring telemetry', fPort: 2, code: 0x24, min: 10, max: 65535, defaultValue: 60, description: 'Set the FPort 4 monitoring interval in seconds. Below 60 seconds uses more LoRaWAN airtime. This does not change the FPort 2 usage-report interval.' }, - { id: 'telemetry-now', name: 'Request Telemetry Now', category: 'Monitoring telemetry', fPort: 2, code: 0x25, description: 'Request one FPort 4 frame immediately, even when periodic monitoring is disabled (firmware v1.0.4+).' }, -]; - -export function generateCommand(id: unknown, value?: unknown) { - const command = commandCatalogue.find(item => item.id === id); - if (!command) throw new Error('Unsupported command'); - const bytes = [command.code]; - if (command.min !== undefined || command.options) { - if (typeof value !== 'number' || !Number.isInteger(value)) throw new Error('An integer parameter is required'); - if (command.options) { - if (!command.options.some(option => option.value === value)) throw new Error('Unsupported parameter value'); - bytes.push(value); - } else { - if (value < command.min! || value > command.max!) throw new Error('Report interval must be 10–65535 seconds'); - bytes.push(value >> 8, value & 255); - } - } else if (value !== undefined && value !== null) throw new Error('This command takes no parameters'); - if (command.fixedValue !== undefined) bytes.push(command.fixedValue); - const expectedLength = command.min !== undefined ? 3 : command.options || command.fixedValue !== undefined ? 2 : 1; - if (bytes.length !== expectedLength || ![2, 3].includes(command.fPort)) throw new Error('Invalid command frame'); - const payload = Buffer.from(bytes); - return { id: command.id, name: command.name, description: command.description, fPort: command.fPort, - hex: payload.toString('hex').toUpperCase(), data: payload.toString('base64'), length: payload.length, - value: value ?? null, parameter: command.options?.find(option => option.value === value)?.label || (command.min !== undefined ? `${value} seconds` : null), - requiresConfirmation: !!command.confirmation, confirmation: command.confirmation || null, confirmed: false }; -} diff --git a/src/m3ter/config.ts b/src/m3ter/config.ts deleted file mode 100644 index 8da3546..0000000 --- a/src/m3ter/config.ts +++ /dev/null @@ -1,10 +0,0 @@ -import { createLogger } from '../utils/logger'; - -const logger = createLogger('[manager]'); -export function telemetryLimit(): number { - const value = process.env.M3TER_TELEMETRY_LIMIT; - if (value === undefined) return 100; - if (/^[1-9]\d*$/.test(value) && Number.isSafeInteger(Number(value))) return Number(value); - logger.warn('Invalid M3TER_TELEMETRY_LIMIT; using the safe default of 100 records. Set a positive integer.'); - return 100; -} diff --git a/src/m3ter/electrical-store.ts b/src/m3ter/electrical-store.ts deleted file mode 100644 index b3665d2..0000000 --- a/src/m3ter/electrical-store.ts +++ /dev/null @@ -1,79 +0,0 @@ -import type { Database } from 'better-sqlite3'; -import type { ManagerEvent } from './store'; -import { ElectricalState, ElectricalTelemetry, trackElectrical } from './electrical'; -let db: Database, limit = 100; - -export function initializeElectricalStore(connection: Database, retentionLimit: number): void { - db = connection; limit = retentionLimit; - db.exec(`CREATE TABLE IF NOT EXISTS manager_electrical_state ( - application TEXT NOT NULL, devEui TEXT NOT NULL, state TEXT NOT NULL, PRIMARY KEY(application,devEui)); - CREATE TABLE IF NOT EXISTS manager_electrical_readings ( - id INTEGER PRIMARY KEY, application TEXT NOT NULL, devEui TEXT NOT NULL, - timestamp INTEGER NOT NULL, receivedAt INTEGER NOT NULL, decoded TEXT NOT NULL, tracking TEXT NOT NULL); - CREATE INDEX IF NOT EXISTS manager_electrical_device_time ON manager_electrical_readings(application,devEui,timestamp DESC,id DESC);`); - db.transaction(trim)(); -} -function trim(): void { - // Separate global cap using the SAME setting: FPort 4 cannot evict usage reports. - db.prepare(`DELETE FROM manager_electrical_readings WHERE id IN ( - SELECT id FROM manager_events WHERE kind IN ('telemetry','telemetry-error') ORDER BY timestamp DESC,id DESC LIMIT -1 OFFSET ?)`).run(limit); - db.prepare(`DELETE FROM manager_events WHERE kind IN ('telemetry','telemetry-error') AND id NOT IN ( - SELECT id FROM manager_events WHERE kind IN ('telemetry','telemetry-error') ORDER BY timestamp DESC,id DESC LIMIT ?)`).run(limit); -} -export function electricalState(application: string, devEui: string): ElectricalState | null { - const row: any = db.prepare('SELECT state FROM manager_electrical_state WHERE application=? AND devEui=?').get(application, devEui); - return row ? JSON.parse(row.state) : null; -} -export function recordElectrical(event: ManagerEvent, telemetry: ElectricalTelemetry | undefined, add: () => number | null): boolean { - return db.transaction(() => { - const previous = electricalState(event.application, event.devEui!); - if (previous?.seen.includes(event.eventKey)) return false; - const id = add(); if (id === null) return false; - if (telemetry) { - const state = trackElectrical(previous, { telemetry, timestamp: event.timestamp, receivedAt: event.receivedAt, - rawPayload: event.rawPayload ?? null, metadata: event.metadata }, event.eventKey); - const late = previous && event.timestamp <= previous.latest.timestamp; - db.prepare(`INSERT INTO manager_electrical_readings(id,application,devEui,timestamp,receivedAt,decoded,tracking) VALUES(?,?,?,?,?,?,?)`) - .run(id, event.application, event.devEui, event.timestamp, event.receivedAt, JSON.stringify(telemetry), JSON.stringify(late ? { status: 'late-frame', forward: null, reverse: null } : state.tracking)); - db.prepare(`INSERT INTO manager_electrical_state(application,devEui,state) VALUES(?,?,?) - ON CONFLICT(application,devEui) DO UPDATE SET state=excluded.state`).run(event.application,event.devEui,JSON.stringify(state)); - } - trim(); return true; - })(); -} -function request(application: string, devEui: string, ids: string[]): any { - const row: any = db.prepare(`SELECT timestamp,status,command FROM manager_commands WHERE application=? AND devEui=? - AND json_extract(command,'$.id') IN (${ids.map(() => '?').join(',')}) - ORDER BY timestamp DESC,rowid DESC LIMIT 1`).get(application,devEui,...ids); - return row ? { ...row, command: JSON.parse(row.command), applied: false } : null; -} -export function electricalSnapshot(application: string, devEui: string, now = Date.now()) { - const state = electricalState(application,devEui); - const intervalRequest = request(application,devEui,['telemetry-interval']); - const modeRequest = request(application,devEui,['telemetry-enable','telemetry-disable']); - const immediateRequest = request(application,devEui,['telemetry-now']); - const spacing = [...(state?.spacing || [])].sort((a,b) => a-b); - const median = spacing.length ? spacing[Math.floor(spacing.length / 2)] : 60; - const regular = spacing.length >= 3 && spacing.every(n => Math.abs(n-median) <= median * 0.2); - const pendingInterval = intervalRequest && !['failed','cleared'].includes(intervalRequest.status) ? intervalRequest.command.value : null; - const interval = regular ? median : pendingInterval || 60; - const staleAfter = interval * 3 * 1000; - const freshness = !state ? 'unavailable' : now - state.latest.timestamp > staleAfter ? 'stale' : 'fresh'; - let status = 'Unknown · no FPort 4 telemetry observed. It may be disabled or unsupported by this firmware.'; - if (state) status = 'Telemetry observed · periodic enable/disable state is unverified.'; - if (regular && freshness === 'fresh') status = 'Regular telemetry observed · periodic operation inferred, not acknowledged.'; - if (modeRequest && !['failed','cleared'].includes(modeRequest.status)) { - if (modeRequest.command.id === 'telemetry-disable') status = 'Disable requested · application is unverified; silence alone is not confirmation.'; - else status = state && state.latest.receivedAt > modeRequest.timestamp ? - 'Enable requested · subsequent telemetry observed; periodic operation is not definitively confirmed.' : 'Enable requested · awaiting telemetry evidence.'; - } - return { state: state ? { latest: state.latest, totals: state.totals, tracking: state.tracking, startedAt: state.startedAt } : null, freshness, status, expectedInterval: interval, - staleAfter, intervalRequest, modeRequest, immediateRequest, retentionLimit: limit, - intervalBasis: regular ? 'observed estimate' : pendingInterval ? 'requested interval; application unverified' : 'provisional firmware default; cadence unknown' }; -} -export function electricalHistory(application: string, devEui: string, offset = 0) { - const rows = db.prepare(`SELECT r.*,e.rawPayload,e.metadata,e.fPort FROM manager_electrical_readings r JOIN manager_events e ON e.id=r.id - WHERE r.application=? AND r.devEui=? ORDER BY r.timestamp DESC,r.id DESC LIMIT 50 OFFSET ?`).all(application,devEui,offset) as any[]; - const count: any = db.prepare('SELECT COUNT(*) AS total FROM manager_electrical_readings WHERE application=? AND devEui=?').get(application,devEui); - return { rows: rows.map(row => ({ ...row, decoded: JSON.parse(row.decoded), tracking: JSON.parse(row.tracking), metadata: JSON.parse(row.metadata) })), total: count.total, offset, limit: 50, retentionLimit: limit }; -} diff --git a/src/m3ter/monitor.ts b/src/m3ter/monitor.ts deleted file mode 100644 index 06089e2..0000000 --- a/src/m3ter/monitor.ts +++ /dev/null @@ -1,136 +0,0 @@ -import { EventEmitter } from 'events'; -import { createHash, randomUUID } from 'crypto'; -import { decodeTelemetry, reportObject } from './decoder'; -import { electricalObject, validateElectricalFrame } from './electrical'; -import { recordElectrical, electricalState } from './electrical-store'; -import * as store from './store'; -import { applicationId, deviceId } from './chirpstack'; -import { getMeterByDevEui } from '../store/sqlite'; -import { uplinkPayload } from '../lib/uplink-payload'; - -export const managerEvents = new EventEmitter(); -managerEvents.setMaxListeners(128); -export const monitoring = { state: 'disconnected', lastMessage: null as number | null, error: null as string | null, since: Date.now() }; -export function inactiveMilliseconds(): number { - const seconds = Number(process.env.M3TER_INACTIVE_SECONDS || 300); - return (Number.isFinite(seconds) && seconds >= 10 ? seconds : 300) * 1000; -} -export function connectionState(state: string, error: string | null = null): void { - const changed = monitoring.state !== state; - Object.assign(monitoring, { state, error, since: Date.now() }); - if (changed) { - try { store.applicationEvent(applicationId(), null, 'mqtt', `MQTT ${state}${error ? ': ' + error : ''}`); } catch { /* Startup/configuration errors remain visible in status. */ } - managerEvents.emit('update', { type: 'connection', monitoring }); - } -} -export function validLocation(value: any): { latitude: number; longitude: number } | null { - if (!value || typeof value.latitude !== 'number' || typeof value.longitude !== 'number' || - !Number.isFinite(value.latitude) || !Number.isFinite(value.longitude) || Math.abs(value.latitude) > 90 || Math.abs(value.longitude) > 180) return null; - return { latitude: value.latitude, longitude: value.longitude }; -} -export function ingestEvent(topic: string, blob: Buffer): boolean { - let application: string; - try { application = applicationId(); } catch { return false; } - let devEui: string | null = null; - try { - if (blob.length > 512 * 1024) throw new Error('MQTT event exceeds the size limit'); - const parts = topic.match(/^application\/([^/]+)\/device\/([\da-f]{16})\/event\/(up|ack|txack|join|location|log|status)$/i); - if (!parts || parts[1].toLowerCase() !== application) return false; - monitoring.lastMessage = Date.now(); - const event = JSON.parse(blob.toString()); - devEui = deviceId(event.deviceInfo?.devEui); - if (devEui !== parts[2].toLowerCase() || event.deviceInfo?.applicationId?.toLowerCase() !== application) throw new Error('MQTT topic and device identity do not match'); - const receivedAt = Date.now(), parsedTime = Date.parse(event.time); - const timestamp = Number.isFinite(parsedTime) && parsedTime > 0 && parsedTime < receivedAt + 300_000 ? parsedTime : receivedAt; - const kind = parts[3].toLowerCase(); - if (kind === 'up' && ![2,4].includes(event.fPort)) return false; - const fields = [event.time, event.fCnt, event.devAddr, event.data, event.queueItemId, event.acknowledged, event.downlinkId]; - if (event.fPort === 4 && event.object !== undefined) fields.push(event.object); - if (event.dataHex !== undefined || event.dataEncoding !== undefined) fields.push(event.dataHex, event.dataEncoding); - const identity = event.deduplicationId || (event.fPort === 4 && Number.isInteger(event.fCnt) ? ['fCnt',event.fCnt,event.devAddr || ''] : event.time ? fields : randomUUID()); - const eventKey = createHash('sha256').update(JSON.stringify(event.fPort === 4 ? [devEui,kind,4,identity] : [devEui,kind,identity])).digest('hex'); - const rx = Array.isArray(event.rxInfo) ? event.rxInfo[0] : null; - const metadata: Record = { sourceTime: typeof event.time === 'string' ? event.time.slice(0,100) : null, timestampSource: timestamp === parsedTime ? 'ChirpStack' : 'console receipt', name: String(event.deviceInfo.deviceName || devEui).slice(0, 200), - applicationName: String(event.deviceInfo.applicationName || '').slice(0, 200), deviceProfileName: String(event.deviceInfo.deviceProfileName || '').slice(0, 200), - fCnt: Number.isInteger(event.fCnt) ? event.fCnt : null, rssi: typeof rx?.rssi === 'number' ? rx.rssi : null, - snr: typeof rx?.snr === 'number' ? rx.snr : null, gatewayId: typeof rx?.gatewayId === 'string' ? rx.gatewayId.slice(0, 32) : null }; - metadata.applicationId = application; metadata.deduplicationId = typeof event.deduplicationId === 'string' ? event.deduplicationId.slice(0,200) : null; - metadata.gateways = Array.isArray(event.rxInfo) ? event.rxInfo.slice(0,32).map((r: any) => ({ gatewayId: r?.gatewayId, rssi: r?.rssi, snr: r?.snr, time: r?.time })) : []; - if (event.object !== undefined) metadata.originalCodecObject = JSON.stringify(event.object).slice(0,16384); - const suppliedPayload = event.dataHex !== undefined ? event.dataHex : event.data; - const rawPayload = typeof suppliedPayload === 'string' ? suppliedPayload.slice(0, 4096) : null; - metadata.payloadField = event.dataHex !== undefined ? 'dataHex' : 'data'; - metadata.payloadEncoding = event.dataHex !== undefined ? 'hex' : event.dataEncoding ?? 'base64'; - if (typeof event.data === 'string' && event.dataHex !== undefined) metadata.upstreamData = event.data.slice(0, 4096); - const record: store.ManagerEvent = { application, devEui, kind, source: 'ChirpStack', timestamp, receivedAt, eventKey, rawPayload, - fPort: Number.isInteger(event.fPort) ? event.fPort : null, metadata, message: `ChirpStack ${kind} event` }; - let inserted: boolean; - if (kind === 'up' && event.fPort === 4) { - record.kind = 'telemetry'; record.message = 'FPort 4 electrical telemetry received'; - let telemetry; - try { - if (timestamp !== parsedTime) throw new Error('FPort 4 requires a valid ChirpStack measurement time'); - const payload = suppliedPayload === undefined ? null : uplinkPayload(event); - if (payload) { validateElectricalFrame(payload.bytes); metadata.payloadHex = payload.hex; } - const object = electricalObject(event.object); - // Raw framing and object framing must agree; unknown schemas use raw fallback. - telemetry = object && (!payload || object.flags === payload.bytes[1] && object.uptime === payload.bytes.readUInt32BE(2)) ? object : - payload ? decodeTelemetry(4,payload.bytes) : undefined; - if (!telemetry) throw new Error('Missing valid FPort 4 payload or telemetry object'); - if (!event.deduplicationId && Number.isInteger(event.fCnt)) { - const previous = electricalState(application,devEui); - const restart = previous && timestamp > previous.latest.timestamp && telemetry.uptime < previous.latest.telemetry.uptime; - const session = (previous?.session || 0) + (restart ? 1 : 0); - record.eventKey = createHash('sha256').update(JSON.stringify([devEui,4,identity,session])).digest('hex'); - } - metadata.decodedSource = telemetry === object ? 'ChirpStack object' : 'raw payload'; - if (event.object && telemetry !== object) metadata.codecWarning = 'Unsupported or invalid telemetry object; decoded raw payload instead'; - } catch (error) { record.kind = 'telemetry-error'; record.message = (error as Error).message; } - inserted = recordElectrical(record,telemetry,() => store.addEvent(record)); - if (inserted) store.updateDevice(application,devEui,metadata); - } else if (kind === 'up') { - let telemetry; - try { - const payload = uplinkPayload(event); - metadata.payloadHex = payload.hex; - const knownKey = store.deviceState(application, devEui)?.publicKey || getMeterByDevEui(devEui)?.publicKey; - telemetry = reportObject(event.object,payload.bytes,knownKey); - metadata.decodedSource = telemetry ? 'ChirpStack object' : 'raw payload'; - telemetry = telemetry || decodeTelemetry(2, payload.bytes, knownKey); - record.message = telemetry.verification === 'invalid' ? 'Telemetry decoded; signature INVALID. Voltage is outside the signed fields.' : 'Uplink decoded'; - } catch (error) { record.kind = 'decode-error'; record.message = (error as Error).message; } - inserted = store.recordUplink(record, telemetry || undefined, inactiveMilliseconds()); - } else { - if (kind === 'location') { - const location = validLocation(event.location); - if (location) { - if (timestamp >= (store.deviceState(application, devEui)?.metadata?.locationTime || 0)) { - metadata.location = location; metadata.locationTime = timestamp; - } - record.message = 'Device location received from ChirpStack'; - } - } - if (kind === 'log') record.message = `ChirpStack diagnostic: ${String(event.code || 'unknown').slice(0, 80)}`; - if (kind === 'ack') record.message = event.acknowledged === true ? 'Confirmed downlink acknowledged by device; command execution is not verified' : 'Downlink was not acknowledged'; - if (kind === 'txack') record.message = 'Gateway reported downlink transmission; device delivery is not confirmed'; - inserted = store.addEvent(record) !== null; - if (inserted) { - store.updateDevice(application, devEui, metadata); - if (typeof event.queueItemId === 'string' && ['ack', 'txack'].includes(kind)) { - store.commandStatus(application, devEui, event.queueItemId, - kind === 'txack' ? 'transmitted' : event.acknowledged === true ? 'delivered' : 'failed', record.message); - } - } - } - if (inserted) managerEvents.emit('update', { type: 'device', devEui, kind: record.kind, timestamp }); - return inserted; - } catch { - // Do not persist an untrusted identity when the topic and payload disagree. - try { store.applicationEvent(application, null, 'diagnostic', 'Malformed MQTT event ignored; check event JSON and device identity.'); } catch { /* Database failures must not crash MQTT. */ } - managerEvents.emit('update', { type: 'diagnostic', message: 'Unable to process an MQTT event. Check diagnostics and database availability.' }); - return false; - } -} -export function checkActivity(): void { - try { store.markInactive(applicationId(), inactiveMilliseconds()); } catch { /* Exposed by API error and next reconnect. */ } -} diff --git a/src/m3ter/store.ts b/src/m3ter/store.ts deleted file mode 100644 index 287bb4c..0000000 --- a/src/m3ter/store.ts +++ /dev/null @@ -1,196 +0,0 @@ -import type { Database } from 'better-sqlite3'; -import { randomUUID } from 'crypto'; -import type { Telemetry } from './decoder'; -import { advance, Accumulator } from './accumulator'; -import { telemetryLimit } from './config'; -import { initializeElectricalStore } from './electrical-store'; -let db: Database; -let retentionLimit = 100; -export function initializeManagerStore(connection: Database): void { - retentionLimit = telemetryLimit(); - db = connection; - db.exec(` - CREATE TABLE IF NOT EXISTS manager_devices (application TEXT, devEui TEXT, metadata TEXT NOT NULL DEFAULT '{}', publicKey TEXT, - lastUplink INTEGER, activity TEXT, PRIMARY KEY(application, devEui)); - CREATE TABLE IF NOT EXISTS manager_events (id INTEGER PRIMARY KEY AUTOINCREMENT, application TEXT NOT NULL, devEui TEXT, - timestamp INTEGER NOT NULL, receivedAt INTEGER NOT NULL, kind TEXT NOT NULL, source TEXT NOT NULL, - eventKey TEXT NOT NULL, rawPayload TEXT, fPort INTEGER, metadata TEXT NOT NULL, message TEXT NOT NULL, - UNIQUE(application,eventKey)); - CREATE INDEX IF NOT EXISTS manager_events_device_time ON manager_events(application,devEui,timestamp DESC,id DESC); - CREATE TABLE IF NOT EXISTS manager_readings (id INTEGER PRIMARY KEY, application TEXT NOT NULL, devEui TEXT NOT NULL, - timestamp INTEGER NOT NULL, receivedAt INTEGER NOT NULL, fPort INTEGER NOT NULL, nonce INTEGER NOT NULL, - rawEnergy INTEGER NOT NULL, energy REAL NOT NULL, rawVoltage INTEGER NOT NULL, voltage REAL NOT NULL, - signature TEXT NOT NULL, publicKey TEXT, verification TEXT NOT NULL, decoded TEXT NOT NULL); - CREATE INDEX IF NOT EXISTS manager_readings_device_time ON manager_readings(application,devEui,timestamp DESC,id DESC); - CREATE TABLE IF NOT EXISTS manager_commands (id TEXT PRIMARY KEY, application TEXT NOT NULL, devEui TEXT NOT NULL, - timestamp INTEGER NOT NULL, updatedAt INTEGER NOT NULL, actor TEXT NOT NULL, command TEXT NOT NULL, - fingerprint TEXT NOT NULL, status TEXT NOT NULL, detail TEXT, queueId TEXT); - CREATE INDEX IF NOT EXISTS manager_commands_device_time ON manager_commands(application,devEui,timestamp DESC); - CREATE INDEX IF NOT EXISTS manager_commands_queue ON manager_commands(application,devEui,queueId); - `); - db.exec(`CREATE TABLE IF NOT EXISTS manager_accumulators ( - application TEXT NOT NULL, devEui TEXT NOT NULL, state TEXT, latest TEXT, - PRIMARY KEY(application,devEui)); - CREATE TABLE IF NOT EXISTS manager_schema (version INTEGER PRIMARY KEY); - CREATE INDEX IF NOT EXISTS manager_readings_retention ON manager_readings(timestamp,id); - CREATE INDEX IF NOT EXISTS manager_events_retention ON manager_events(timestamp,id);`); - const columns = new Set((db.prepare('PRAGMA table_info(manager_readings)').all() as any[]).map(row => row.name)); - for (const [name, type] of Object.entries({ accounting: 'TEXT', intervalEnergy: 'REAL', collectedEnergy: 'REAL', completedNonce: 'INTEGER', segment: 'INTEGER' })) { - if (!columns.has(name)) db.exec(`ALTER TABLE manager_readings ADD COLUMN ${name} ${type}`); - } - // Replay existing history once before trimming. Raw readings are never rewritten. - db.transaction(() => { - if (!db.prepare('SELECT version FROM manager_schema WHERE version=1').get()) { - // Finish each read before writing on this SQLite connection; bound memory - // during migration of an installation that previously retained all history. - let timestamp = -1, id = -1; - for (;;) { - const rows: any[] = db.prepare('SELECT * FROM manager_readings WHERE timestamp>? OR (timestamp=? AND id>?) ORDER BY timestamp,id LIMIT 500').all(timestamp,timestamp,id); - if (!rows.length) break; - for (const row of rows) account(row); - const last = rows[rows.length-1]; timestamp = last.timestamp; id = last.id; - } - db.prepare('INSERT INTO manager_schema(version) VALUES(1)').run(); - } - // Recover receipt times from persisted records, never from the startup clock. - if (!db.prepare('SELECT version FROM manager_schema WHERE version=2').get()) { - db.exec(`UPDATE manager_devices SET lastUplink=NULLIF(MAX( - COALESCE((SELECT MAX(receivedAt) FROM manager_readings r WHERE r.application=manager_devices.application AND r.devEui=manager_devices.devEui),0), - COALESCE((SELECT json_extract(latest,'$.receivedAt') FROM manager_accumulators a WHERE a.application=manager_devices.application AND a.devEui=manager_devices.devEui),0)),0); - INSERT INTO manager_schema(version) VALUES(2);`); - } - trimHistory(); - })(); - initializeElectricalStore(db, retentionLimit); - // A process may have stopped after the upstream accepted a command. Never resend automatically. - db.prepare("UPDATE manager_commands SET status='unknown', detail='Console restarted during enqueue; inspect the queue before retrying' WHERE status='enqueuing'").run(); -} -// Global cap includes malformed and unsupported uplinks, so their raw payloads -// cannot bypass retention. Device state survives deletion of any history row. -function trimHistory(): void { - db.prepare(`DELETE FROM manager_readings WHERE id IN ( - SELECT id FROM manager_events WHERE kind IN ('up','decode-error') - ORDER BY timestamp DESC,id DESC LIMIT -1 OFFSET ?)`).run(retentionLimit); - db.prepare(`DELETE FROM manager_events WHERE kind IN ('up','decode-error') AND id NOT IN ( - SELECT id FROM manager_events WHERE kind IN ('up','decode-error') ORDER BY timestamp DESC,id DESC LIMIT ?)`).run(retentionLimit); -} -export function accumulatorState(application: string, devEui: string): Accumulator | null { - const row: any = db.prepare('SELECT state FROM manager_accumulators WHERE application=? AND devEui=?').get(application, devEui); - return row?.state ? JSON.parse(row.state) : null; -} -function account(row: any): void { - const previous = accumulatorState(row.application, row.devEui); - const result = row.verification === 'invalid' ? { state: previous, accounting: 'invalid-signature', intervalEnergy: null, collectedEnergy: null, completedNonce: null } : - advance(previous, row.nonce, row.rawEnergy, row.timestamp); - const segment = result.state?.segment ?? 0; - db.prepare('UPDATE manager_readings SET accounting=?,intervalEnergy=?,collectedEnergy=?,completedNonce=?,segment=? WHERE id=?') - .run(result.accounting, result.intervalEnergy, result.collectedEnergy, result.completedNonce, segment, row.id); - const old: any = db.prepare('SELECT latest FROM manager_accumulators WHERE application=? AND devEui=?').get(row.application,row.devEui); - const latest = old?.latest ? JSON.parse(old.latest) : null; - db.prepare(`INSERT INTO manager_accumulators(application,devEui,state,latest) VALUES(?,?,?,?) - ON CONFLICT(application,devEui) DO UPDATE SET state=excluded.state,latest=excluded.latest`) - .run(row.application, row.devEui, JSON.stringify(result.state), JSON.stringify(!latest || row.timestamp >= latest.timestamp ? row : latest)); -} -/** Evidence from the existing collector only; this never sends an acknowledgment. */ -export function collectorAccepted(application: string, devEui: string, nonce: number, rawEnergy: number): void { - const current = accumulatorState(application,devEui); - if (current && nonce !== 0 && current.nonce === nonce && current.acceptedRaw === null) { - current.acceptedRaw = rawEnergy; - db.prepare('UPDATE manager_accumulators SET state=? WHERE application=? AND devEui=?').run(JSON.stringify(current),application,devEui); - } -} -export type ManagerEvent = { application: string; devEui: string | null; timestamp: number; receivedAt: number; - kind: string; source: string; eventKey: string; rawPayload?: string | null; fPort?: number | null; metadata: Record; message: string }; -export function addEvent(event: ManagerEvent): number | null { - const result = db.prepare(`INSERT OR IGNORE INTO manager_events(application,devEui,timestamp,receivedAt,kind,source,eventKey,rawPayload,fPort,metadata,message) - VALUES(@application,@devEui,@timestamp,@receivedAt,@kind,@source,@eventKey,@rawPayload,@fPort,@metadata,@message)`) - .run({ ...event, rawPayload: event.rawPayload ?? null, fPort: event.fPort ?? null, metadata: JSON.stringify(event.metadata) }); - return result.changes ? Number(result.lastInsertRowid) : null; -} -export function applicationEvent(application: string, devEui: string | null, kind: string, message: string): void { - addEvent({ application, devEui, kind, message, source: 'console observation', eventKey: randomUUID(), timestamp: Date.now(), receivedAt: Date.now(), metadata: {} }); -} -export function deviceState(application: string, devEui: string): any { - const row: any = db.prepare('SELECT * FROM manager_devices WHERE application=? AND devEui=?').get(application, devEui); - return row ? { ...row, metadata: JSON.parse(row.metadata), accumulation: accumulatorState(application, devEui) } : null; -} -export function updateDevice(application: string, devEui: string, metadata: Record): void { - const previous = deviceState(application, devEui); - db.prepare(`INSERT INTO manager_devices(application,devEui,metadata) VALUES(?,?,?) - ON CONFLICT(application,devEui) DO UPDATE SET metadata=excluded.metadata`).run(application, devEui, JSON.stringify({ ...previous?.metadata, ...metadata })); -} -export function recordUplink(event: ManagerEvent, telemetry?: Telemetry, inactiveAfter = 300000): boolean { - return db.transaction(() => { - const id = addEvent(event); if (id === null) return false; - const old = deviceState(event.application, event.devEui!); - updateDevice(event.application, event.devEui!, event.metadata); - if (!telemetry) { trimHistory(); return true; } - const recent = Math.max(event.receivedAt, old?.lastUplink || 0) >= Date.now() - inactiveAfter; - if (recent && (!old?.lastUplink || old.activity === 'inactive')) applicationEvent(event.application, event.devEui, 'active', 'Uplink observed after no recent activity'); - db.prepare('UPDATE manager_devices SET lastUplink=MAX(COALESCE(lastUplink,0),?),activity=? WHERE application=? AND devEui=?') - .run(event.receivedAt, recent ? 'active' : 'inactive', event.application, event.devEui); - db.prepare(`INSERT INTO manager_readings(id,application,devEui,timestamp,receivedAt,fPort,nonce,rawEnergy,energy,rawVoltage,voltage,signature,publicKey,verification,decoded) - VALUES(@id,@application,@devEui,@timestamp,@receivedAt,@fPort,@nonce,@rawEnergy,@energy,@rawVoltage,@voltage,@signature,@publicKey,@verification,@decoded)`) - .run({ id, application: event.application, devEui: event.devEui, timestamp: event.timestamp, receivedAt: event.receivedAt, fPort: event.fPort, - nonce: telemetry.nonce, rawEnergy: telemetry.rawEnergy, energy: telemetry.energy, rawVoltage: telemetry.rawVoltage, voltage: telemetry.voltage, - signature: telemetry.signature, publicKey: telemetry.publicKey, verification: telemetry.verification, decoded: JSON.stringify(telemetry) }); - account(db.prepare('SELECT * FROM manager_readings WHERE id=?').get(id)); - trimHistory(); - if (telemetry.verificationKey && telemetry.verification === 'verified' && !old?.publicKey) { - db.prepare('UPDATE manager_devices SET publicKey=? WHERE application=? AND devEui=?').run(telemetry.verificationKey, event.application, event.devEui); - applicationEvent(event.application, event.devEui, 'public-key', telemetry.publicKey ? 'Public key received; signature over nonce and energy verified (first-seen key)' : 'Existing console public key reused to verify nonce and energy'); - } - return true; - })(); -} -export function markInactive(application: string, threshold: number): void { - db.transaction(() => { - const rows: any[] = db.prepare("SELECT devEui FROM manager_devices WHERE application=? AND activity='active' AND lastUplink=@from AND r.timestamp<=@to'; - const rows = db.prepare(`SELECT r.*,e.rawPayload,e.metadata FROM manager_readings r JOIN manager_events e ON e.id=r.id ${where} - ORDER BY r.timestamp DESC,r.id DESC LIMIT @limit OFFSET @offset`).all({ ...args,limit,offset }); - const chart = db.prepare(`SELECT r.* FROM manager_readings r ${where} ORDER BY timestamp,id`).all(args); - const summary: any = db.prepare(`SELECT COUNT(*) AS reports, COALESCE(SUM(intervalEnergy),0) AS observedConsumption, - COALESCE(SUM(collectedEnergy),0) AS collectedEnergy, - COALESCE(SUM(accounting='cycle-advanced'),0) AS resets, - COALESCE(SUM(accounting IN ('nonce-reset-or-gap','counter-reset-uncertain','uncertain-cycle-ended','late-report','invalid-signature')),0) AS uncertainReports, - COALESCE(SUM(accounting='repeated-total'),0) AS repeatedReports FROM manager_readings r ${where}`).get(args); - return { rows, chart, total: summary.reports, offset, limit, summary, sampled: false, retentionLimit }; -} -export function events(application: string, devEui: string, offset = 0): any[] { - return db.prepare(`SELECT * FROM manager_events WHERE application=? AND (devEui=? OR devEui IS NULL) - ORDER BY timestamp DESC,id DESC LIMIT 100 OFFSET ?`).all(application, devEui, offset); -} -export function getCommand(application: string, id: string): any { - const row: any = db.prepare('SELECT * FROM manager_commands WHERE application=? AND id=?').get(application, id); - return row ? { ...row, actor: 'manager operator', command: JSON.parse(row.command) } : null; -} -export function commandHistory(application: string, devEui: string, offset = 0): any[] { - return (db.prepare('SELECT * FROM manager_commands WHERE application=? AND devEui=? ORDER BY timestamp DESC LIMIT 50 OFFSET ?').all(application, devEui, offset) as any[]) - .map(row => ({ ...row, actor: 'manager operator', command: JSON.parse(row.command) })); -} -export function insertCommand(application: string, devEui: string, id: string, command: unknown, fingerprint: string): void { - db.prepare(`INSERT INTO manager_commands(id,application,devEui,timestamp,updatedAt,actor,command,fingerprint,status,queueId) - VALUES(?,?,?,?,?,?,?,?,?,?)`).run(id, application, devEui, Date.now(), Date.now(), 'manager operator', JSON.stringify(command), fingerprint, 'enqueuing', id); -} -export function commandStatus(application: string, devEui: string, queueId: string, status: string, detail: string): void { - const predicate = status === 'queued' ? "status='enqueuing'" : "status NOT IN ('delivered','failed')"; - db.prepare(`UPDATE manager_commands SET status=?,detail=?,updatedAt=? WHERE application=? AND devEui=? AND queueId=? - AND ${predicate}`).run(status, detail, Date.now(), application, devEui, queueId); -} -export function clearedCommands(application: string, devEui: string): void { - db.prepare("UPDATE manager_commands SET status='cleared',detail='Queue cleared; any earlier transmission cannot be recalled',updatedAt=? WHERE application=? AND devEui=? AND status IN ('queued','pending','unknown')") - .run(Date.now(), application, devEui); -} diff --git a/src/public/css/m3ter-manager.css b/src/public/css/m3ter-manager.css deleted file mode 100644 index 01cdbb8..0000000 --- a/src/public/css/m3ter-manager.css +++ /dev/null @@ -1,92 +0,0 @@ -.mm-app { display:flex; flex-direction:column; min-height:0; flex:1; font-family:var(--font); color:var(--text); } -.app-art[data-icon="manager"] { background:var(--accent); color:var(--accent-ink); } -.mm-header { display:flex; align-items:center; justify-content:space-between; gap:12px; padding:18px 22px 12px; } -.mm-brand { display:flex; align-items:center; gap:12px; min-width:0; } -.mm-brand strong { font-size:18px; letter-spacing:-.5px; } -.mm-brand small { font-size:11px; } -.mm-mark { background:var(--accent); color:var(--accent-ink); width:42px; height:42px; display:grid; place-items:center; border-radius:var(--small-radius); } -.mm-connection { text-align:right; } -.mm-pill { display:inline-block; background:var(--surface-alt); border:1px solid var(--border); border-radius:var(--small-radius); padding:4px 9px; font-size:10px; line-height:1.5; } -.mm-pill[data-state="connected"],.mm-pill[data-state="active"] { color:var(--accent); border-color:var(--accent); } -.mm-selector { display:flex; gap:8px; padding:0 22px 14px; align-items:center; } -.mm-selector select { flex:1; min-width:0; max-width:100%; } -.mm-app input,.mm-app select { min-height:40px; padding:8px 10px; background:var(--surface); color:var(--text); border:1px solid var(--border); border-radius:var(--small-radius); max-width:100%; } -.mm-search { display:flex; align-items:center; width:38%; min-width:0; } -.mm-search svg { width:17px; margin-right:6px; } -.mm-search input { width:100%; min-width:0; } -.mm-nav { display:flex; flex-shrink:0; overflow:auto; padding:0 14px; gap:4px; border-bottom:1px solid var(--border); } -.mm-nav button { padding:12px 10px; font-size:12px; white-space:nowrap; border-bottom:2px solid transparent; min-height:44px; } -.mm-nav button[aria-current="page"] { color:var(--accent); border-color:var(--accent); font-weight:700; } -.mm-scroll { overflow:auto; padding:22px; min-height:0; flex:1; container-type:inline-size; } -.mm-identity { display:flex; align-items:center; justify-content:space-between; gap:12px; margin-bottom:20px; } -.mm-identity h2 { font-size:25px; margin:6px 0 0; overflow-wrap:anywhere; } -.mm-identity code { font-size:11px; color:var(--muted); } -.mm-metrics { display:grid; grid-template-columns:repeat(2,minmax(0,1fr)); gap:12px; } -.mm-metric { border:1px solid var(--border); border-radius:var(--radius); padding:16px; background:var(--surface-alt); min-width:0; } -.mm-metric>span { font-size:12px; } -.mm-metric>strong { display:block; font-size:32px; line-height:1.6; font-weight:550; font-variant-numeric:tabular-nums; letter-spacing:-1px; overflow-wrap:anywhere; } -.mm-metric em { font-size:14px; font-style:normal; color:var(--muted); letter-spacing:0; } -.mm-metric.mm-energy { background:var(--accent); color:var(--accent-ink); border-color:var(--accent); } -.mm-energy small,.mm-energy em { color:inherit; opacity:.85; } -.mm-metric .mm-small-number { font-size:23px; letter-spacing:-.5px; } -.mm-section-heading { display:flex; align-items:center; justify-content:space-between; gap:12px; margin:24px 0 14px; flex-wrap:wrap; } -.mm-section-heading h3 { margin:0 0 4px; } -.mm-section-heading label { font-size:12px; } -.mm-charts { display:grid; grid-template-columns:repeat(2,minmax(0,1fr)); gap:14px; } -.mm-chart-card { min-width:0; padding:16px 12px 10px; border:1px solid var(--border); border-radius:var(--radius); } -.mm-chart-card h3 { margin:0 0 12px; display:flex; flex-wrap:wrap; justify-content:space-between; gap:4px; } -.mm-chart { min-height:200px; position:relative; color:var(--accent); } -.mm-chart svg { display:block; width:100%; height:160px; overflow:visible; touch-action:pan-y; } -.mm-chart-axis { display:flex; justify-content:space-between; font-size:10px; color:var(--muted); gap:8px; margin:6px 0; } -.mm-chart-tooltip { min-height:36px; font-size:11px; color:var(--text); line-height:1.5; overflow-wrap:anywhere; } -.mm-note,.mm-notice { font-size:12px; line-height:1.7; color:var(--muted); padding:12px 14px; background:var(--surface-alt); border-radius:var(--small-radius); margin:14px 0; } -.mm-notice { border-left:3px solid var(--accent); color:var(--text); margin-top:0; } -.mm-error { border-left-color:#cc5b45; } -.mm-actions { display:flex; align-items:center; gap:8px; flex-wrap:wrap; } -.mm-app .nes-btn { min-height:40px; font-family:var(--font); font-size:12px; white-space:normal; } -.mm-table { width:100%; font-size:11px; border-collapse:collapse; } -.mm-table td,.mm-table th { padding:12px 8px; border-bottom:1px solid var(--border); text-align:left; } -.mm-table th { color:var(--muted); font-weight:500; } -.mm-pagination { display:flex; justify-content:space-between; align-items:center; gap:10px; font-size:11px; margin:14px 0; } -.mm-command-grid { display:grid; grid-template-columns:repeat(2,minmax(0,1fr)); gap:12px; } -.mm-command-card { border:1px solid var(--border); padding:16px; border-radius:var(--radius); display:flex; flex-direction:column; gap:8px; min-width:0; } -.mm-command-card h4 { font-size:14px; margin:0; } -.mm-command-card small { flex:1; } -.mm-command-card select,.mm-command-card input { width:100%; } -.mm-command-card .eyebrow { font-size:9px; } -.mm-command-card button { align-self:flex-start; } -.mm-record { padding:12px 0; border-bottom:1px solid var(--border); font-size:12px; overflow-wrap:anywhere; } -.mm-record strong { display:block; } -.mm-record summary { cursor:pointer; min-height:44px; } -.mm-record code { font-size:11px; } -.mm-info { display:grid; grid-template-columns:minmax(100px,1fr) minmax(0,2fr); gap:0; font-size:12px; } -.mm-info dt,.mm-info dd { margin:0; padding:10px 0; border-bottom:1px solid var(--border); overflow-wrap:anywhere; } -.mm-info dt { color:var(--muted); padding-right:12px; } -.mm-long-code { display:block; overflow-wrap:anywhere; font-size:11px; padding:12px; background:var(--surface-alt); margin-bottom:12px; white-space:pre-wrap; } -.mm-timeline { list-style:none; margin:0; padding:0 0 0 14px; border-left:1px solid var(--border); } -.mm-timeline li { position:relative; margin:0 0 18px; padding-left:12px; font-size:12px; overflow-wrap:anywhere; } -.mm-timeline li:before { content:''; position:absolute; left:-18px; top:5px; width:7px; height:7px; border-radius:50%; background:var(--accent); } -.mm-timeline small { font-size:10px; } -#mm-dialog { width:min(540px,calc(100vw - 24px)); max-height:85dvh; overflow:auto; } -#mm-dialog h2 { font-size:23px; margin:12px 0; } -.mm-confirm { display:flex; align-items:flex-start; gap:10px; font-size:12px; padding:14px 0; } -.mm-confirm input { flex-shrink:0; min-height:24px; width:24px; } -#mm-dialog-content { overflow-wrap:anywhere; font-size:13px; } -#mm-dialog-content p { margin-bottom:10px; } -@container (min-width:900px) { .mm-metrics { grid-template-columns:repeat(4,minmax(0,1fr)); } } -@container (max-width:520px) { .mm-charts,.mm-command-grid { grid-template-columns:1fr; } .mm-metric { padding:12px; } .mm-metric>strong { font-size:25px; } .mm-identity { align-items:flex-start; flex-direction:column; } .mm-info { grid-template-columns:1fr; } .mm-info dt { border:0; padding-bottom:0; } .mm-table td,.mm-table th { padding:8px 4px; font-size:10px; } } -@media(max-width:700px) { .mm-header { padding:10px 12px; } .mm-mark { display:none; } .mm-brand strong { font-size:15px; } .mm-header small { font-size:9px; } .mm-selector { padding:0 12px 10px; flex-wrap:wrap; } .mm-search { width:100%; } .mm-scroll { padding:14px; } .mm-nav { padding:0 6px; } .mm-nav button { padding:10px 8px; font-size:11px; } .mm-pill { font-size:9px; } .mm-identity h2 { font-size:22px; } } -.mm-login { flex:1; min-height:0; overflow:auto; display:grid; place-items:center; padding:24px; background:radial-gradient(ellipse at top,var(--surface-alt),var(--surface)); } -.mm-login-card { width:min(100%,360px); display:grid; gap:12px; color:var(--text); } -.mm-login-card h2 { margin:4px 0 0; font-size:24px; } -.mm-login-card p,.mm-login-card small { color:var(--muted); margin:0 0 8px; } -.mm-login-card input { width:100%; min-width:0; min-height:44px; background:var(--surface); color:var(--text); border:1px solid var(--border); border-radius:var(--small-radius); padding:10px 12px; } -.mm-login-card #mm-login-error { color:var(--text); border-left:3px solid #d45f69; padding-left:12px; } -.mm-login-card .mm-mark { width:52px; height:52px; } - -.mm-phase-grid { display:grid; grid-template-columns:repeat(3,minmax(0,1fr)); gap:12px; } -.mm-phase-grid .mm-info { grid-template-columns:1fr; } -.mm-phase-grid .mm-info dt { border:0; padding-bottom:0; } -#mm-electrical-main { margin-top:18px; } -#mm-electrical-tracking { overflow-wrap:anywhere; } -@container (max-width:520px) { .mm-phase-grid { grid-template-columns:1fr; } } diff --git a/src/public/js/desktop.js b/src/public/js/desktop.js index be6723b..0ed78bf 100644 --- a/src/public/js/desktop.js +++ b/src/public/js/desktop.js @@ -8,7 +8,6 @@ const all = (selector, parent = document) => [...parent.querySelectorAll(selector)]; const mobile = window.matchMedia('(max-width: 700px)'); const paths = { - manager: '', radio: '', meter: '', terminal: '', diff --git a/src/public/js/m3ter-charts.js b/src/public/js/m3ter-charts.js deleted file mode 100644 index 4ec09fd..0000000 --- a/src/public/js/m3ter-charts.js +++ /dev/null @@ -1,41 +0,0 @@ -(function () { - 'use strict'; - const svgNS = 'http://www.w3.org/2000/svg'; - const label = (tag, text, className) => { const node = document.createElement(tag); node.textContent = text; if (className) node.className = className; return node; }; - window.M3terCharts = { - render(container, readings, field) { - container.replaceChildren(); - const unit = field === 'energy' ? 'kWh' : 'V'; - const rows = readings.filter(row => Number.isFinite(row[field]) && Number.isFinite(row.timestamp)); - if (!rows.length) { container.append(label('p', 'No readings in this range. Waiting for a valid uplink.', 'mm-note')); return; } - const minTime = rows[0].timestamp, maxTime = rows[rows.length - 1].timestamp; - const values = rows.map(row => row[field]); - const bottom = Math.min(...values), top = Math.max(...values), pad = Math.max((top - bottom) * .12, field === 'energy' ? .000001 : 1); - const low = Math.max(0, bottom - pad), high = top + pad; - const x = row => maxTime === minTime ? 320 : 8 + (row.timestamp - minTime) / (maxTime - minTime) * 624; - const y = row => 150 - (row[field] - low) / (high - low) * 140; - const axes = label('div', '', 'mm-chart-axis'); axes.append(label('span', `${high.toFixed(field === 'energy' ? 6 : 1)} ${unit}`), label('span', `${low.toFixed(field === 'energy' ? 6 : 1)} ${unit}`)); - const svg = document.createElementNS(svgNS, 'svg'); svg.setAttribute('viewBox', '0 0 640 160'); svg.setAttribute('preserveAspectRatio', 'none'); svg.setAttribute('tabindex', '0'); svg.setAttribute('role', 'img'); - svg.setAttribute('aria-label', `${field === 'energy' ? 'Cumulative energy' : 'Voltage'} chart, ${rows.length} points. Use left and right arrows to inspect readings. Energy lines break at observed accumulator decreases.`); - const grid = document.createElementNS(svgNS, 'path'); grid.setAttribute('d', 'M0 10H640 M0 80H640 M0 150H640'); grid.setAttribute('stroke', 'var(--border)'); grid.setAttribute('stroke-width', '1'); svg.append(grid); - const line = document.createElementNS(svgNS, 'path'); - line.setAttribute('d', rows.map((row, i) => `${i === 0 || (field === 'energy' && row.segment !== rows[i - 1].segment) ? 'M' : 'L'}${x(row).toFixed(2)} ${y(row).toFixed(2)}`).join(' ')); - line.setAttribute('stroke-width', '2'); line.setAttribute('vector-effect', 'non-scaling-stroke'); line.setAttribute('fill', 'none'); svg.append(line); - const point = document.createElementNS(svgNS, 'circle'); point.setAttribute('r', '4'); point.setAttribute('fill', 'var(--accent)'); svg.append(point); - const times = label('div', '', 'mm-chart-axis'); times.append(label('span', new Date(minTime).toLocaleString()), label('span', new Date(maxTime).toLocaleString())); - const tooltip = label('div', '', 'mm-chart-tooltip'); tooltip.setAttribute('aria-live', 'polite'); - let index = rows.length - 1; - function inspect(next) { - index = Math.max(0, Math.min(rows.length - 1, next)); const row = rows[index]; - point.setAttribute('cx', x(row)); point.setAttribute('cy', y(row)); - tooltip.textContent = `${new Date(row.timestamp).toLocaleString()} · ${row[field].toFixed(field === 'energy' ? 6 : 1)} ${unit}`; - } - svg.addEventListener('pointermove', event => { - const bounds = svg.getBoundingClientRect(), target = (event.clientX - bounds.left) / bounds.width * 640; - let nearest = 0; rows.forEach((row, i) => { if (Math.abs(x(row) - target) < Math.abs(x(rows[nearest]) - target)) nearest = i; }); inspect(nearest); - }); - svg.addEventListener('keydown', event => { if (['ArrowLeft', 'ArrowRight', 'Home', 'End'].includes(event.key)) { event.preventDefault(); inspect(event.key === 'Home' ? 0 : event.key === 'End' ? rows.length - 1 : index + (event.key === 'ArrowLeft' ? -1 : 1)); } }); - inspect(index); container.append(axes, svg, times, tooltip); - }, - }; -})(); diff --git a/src/public/js/m3ter-commands.js b/src/public/js/m3ter-commands.js deleted file mode 100644 index bde202e..0000000 --- a/src/public/js/m3ter-commands.js +++ /dev/null @@ -1,120 +0,0 @@ -(function () { - 'use strict'; - window.M3terCommands = function ({ api, selected, showError, clearError, notice, element, refresh, text, node }) { - const $ = element; - const dialog = $('mm-dialog'), submit = $('mm-submit'), confirm = $('mm-confirm'); - let intent = null, working = false, catalogue = [], historyOffset = 0; - const uuid = () => crypto.randomUUID ? crypto.randomUUID() : '10000000-1000-4000-8000-100000000000'.replace(/[018]/g, c => (Number(c) ^ crypto.getRandomValues(new Uint8Array(1))[0] & 15 >> Number(c) / 4).toString(16)); - function display(title, content, button, sensitive) { - text('mm-dialog-title', title); $('mm-dialog-content').replaceChildren(...content); - submit.textContent = button || 'Close'; submit.hidden = !button; - $('mm-cancel').textContent = button ? 'Cancel' : 'Close'; - $('mm-confirm-label').hidden = !sensitive; confirm.checked = false; submit.disabled = !!sensitive; - if (!dialog.open) AppFeedback.showDialog(dialog, $('m3ter-manager')); - } - confirm.addEventListener('change', () => { submit.disabled = !confirm.checked; }); - $('mm-cancel').addEventListener('click', () => { if (!working) dialog.close(); }); - dialog.addEventListener('cancel', event => { if (working) event.preventDefault(); }); - dialog.addEventListener('close', () => { if (!working) intent = null; }); - async function preview(id, value) { - const device = selected(); if (!device?.devEui || working) return; - notice('Preparing command preview…'); - try { - const command = await api('/commands/preview', { method: 'POST', body: { commandId: id, ...(value === undefined ? {} : { value }) } }); - if (selected()?.devEui !== device.devEui) return; - intent = { type: 'command', devEui: device.devEui, command, requestId: uuid() }; - const parts = [node('p', `${device.name} · ${device.devEui}`), node('p', command.description), - node('code', `FPort ${command.fPort} · ${command.length} byte${command.length === 1 ? '' : 's'}\nHex: ${command.hex}\nBase64: ${command.data}`, 'mm-long-code'), - node('p', 'Unconfirmed downlink. Acceptance into the queue does not verify delivery or execution.', 'mm-note')]; - if (command.confirmation) parts.push(node('p', command.confirmation, 'mm-notice')); - if (command.parameter) parts.splice(1, 0, node('p', `Selected setting: ${command.parameter}`, 'mm-notice')); - if (['report-interval','telemetry-interval'].includes(id) && value < 60) parts.push(node('p', 'Short intervals consume more LoRaWAN airtime.', 'mm-notice')); - display(command.name, parts, 'Enqueue command', command.requiresConfirmation); notice(''); - } catch (error) { showError(error); } - } - $('mm-dialog-form').addEventListener('submit', async event => { - event.preventDefault(); if (!intent || working || (! $('mm-confirm-label').hidden && !confirm.checked)) return; - const current = intent; working = true; submit.disabled = true; $('mm-cancel').disabled = true; - try { - if (current.type === 'clear') { - notice('Clearing pending downlinks…'); - await api(`/devices/${current.devEui}/queue`, { method: 'DELETE', body: { confirmDevEui: current.devEui } }); - notice('Pending queue cleared. Previously transmitted commands cannot be recalled.'); - } else { - notice('Enqueuing command…'); - const result = await api(`/devices/${current.devEui}/commands`, { method: 'POST', body: { requestId: current.requestId, - commandId: current.command.id, value: current.command.value, confirmedSafety: confirm.checked } }); - notice(`${result.command.name}: ${result.status}. ${result.detail || ''}`); - } - intent = null; working = false; dialog.close(); - if (selected()?.devEui === current.devEui) await refresh(); - } catch (error) { - // Retain the request ID after a lost response so retry cannot enqueue twice. - showError(error); notice(current.type === 'clear' ? 'Queue clearing did not complete. Inspect the queue before retrying: another clear removes ALL items pending at that time.' : 'The request did not complete. Retry uses the same request ID; inspect the queue if the outcome is uncertain.'); - if (current.type === 'clear') confirm.checked = false; - $('mm-dialog-content').append(node('p', error.message, 'mm-notice mm-error')); - } finally { working = false; submit.disabled = !$('mm-confirm-label').hidden && !confirm.checked; $('mm-cancel').disabled = false; } - }); - $('mm-queue-clear').addEventListener('click', () => { - const device = selected(); if (!device?.devEui || working) return; - intent = { type: 'clear', devEui: device.devEui }; - display('Clear this meter’s queue?', [node('p', `${device.name} · ${device.devEui}`), node('p', 'This removes ALL currently queued downlinks for this meter, including commands queued outside M3ter Manager. Previously transmitted commands cannot be recalled.')], 'Clear all pending downlinks', true); - }); - function renderCatalogue(commands) { - catalogue = commands; const parent = $('mm-commands'); parent.replaceChildren(); - for (const command of catalogue) { - const card = node('article', '', 'mm-command-card'); card.append(node('span', command.category, 'eyebrow'), node('h4', command.name), node('small', command.description)); - let control; - if (command.options) { - control = node('select'); control.setAttribute('aria-label', command.name); - command.options.forEach(option => { const item = node('option', option.label); item.value = option.value; control.append(item); }); - } else if (command.min !== undefined) { - const presets = node('select'); presets.setAttribute('aria-label', command.id === 'telemetry-interval' ? 'Telemetry interval presets' : 'Report interval presets'); - [10,15,30,60,300,900,1800,3600].forEach(seconds => { const option = node('option', seconds < 60 ? `${seconds} seconds` : `${seconds / 60} minutes`); option.value = seconds; presets.append(option); }); - const custom = node('option', 'Custom'); custom.value = 'custom'; presets.append(custom); presets.value = '60'; - control = node('input'); control.type = 'number'; control.min = command.min; control.max = command.max; control.step = 1; control.value = command.defaultValue; control.setAttribute('aria-label', command.id === 'telemetry-interval' ? 'Telemetry interval seconds' : 'Report interval seconds'); - presets.addEventListener('change', () => { if (presets.value !== 'custom') control.value = presets.value; }); - control.addEventListener('input', () => { presets.value = 'custom'; }); card.append(presets); - } - if (control) card.append(control); - const button = node('button', 'Preview command', 'nes-btn'); button.dataset.commandId = command.id; - button.addEventListener('click', () => { if (control && !control.reportValidity()) return; preview(command.id, control ? Number(control.value) : undefined); }); card.append(button); parent.append(card); - } - } - function recordDetails(title, command, detail) { - const section = node('details', '', 'mm-record'); section.append(node('summary', title), node('p', detail || 'No additional delivery information'), - node('code', `FPort ${command.fPort} · HEX ${command.hex} · Base64 ${command.data}`, 'mm-long-code')); - return section; - } - async function loadHistory(append = false) { - const device = selected(); if (!device?.devEui) return; - if (!append) historyOffset = 0; - const data = await api(`/devices/${device.devEui}/commands?offset=${historyOffset}`); - if (selected()?.devEui !== device.devEui) return; - const parent = $('mm-command-history'); if (!append) parent.replaceChildren(); - if (!data.commands.length && !append) parent.append(node('p', 'No commands have been submitted from M3ter Manager.', 'mm-note')); - data.commands.forEach(row => parent.append(recordDetails(`${new Date(row.timestamp).toLocaleString()} · ${row.command.name}${row.command.parameter ? ' · ' + row.command.parameter : ''} · ${row.status}`, row.command, - `${row.detail || 'Awaiting delivery evidence.'} Queue ID: ${row.queueId || 'Unavailable'} · Submitted by ${row.actor}`))); - historyOffset += data.commands.length; $('mm-commands-more').hidden = data.commands.length < 50; - } - async function loadQueue() { - const device = selected(); if (!device?.devEui) return; - const parent = $('mm-queue'); parent.replaceChildren(node('p', 'Loading pending queue…', 'mm-note')); - try { - const data = await api(`/devices/${device.devEui}/queue`); if (selected()?.devEui !== device.devEui) return; - parent.replaceChildren(); - if (!data.items.length) parent.append(node('p', 'No pending downlinks.', 'mm-note')); - if (data.total > data.items.length) parent.append(node('p', `Showing ${data.items.length} of ${data.total} queued items. Clear queue applies to ALL items.`, 'mm-note')); - data.items.forEach(item => parent.append(recordDetails(`${item.id || 'Queue item'} · ${item.isPending ? 'Pending delivery' : 'Queued'} · ${item.confirmed ? 'Confirmed' : 'Unconfirmed'}`, item, - `Created: ${item.createdAt ? new Date(item.createdAt).toLocaleString() : 'Unavailable'} · Expires: ${item.expiresAt ? new Date(item.expiresAt).toLocaleString() : 'Unavailable'}`))); - } catch (error) { if (selected()?.devEui === device.devEui) { parent.replaceChildren(node('p', error.message, 'mm-note')); } throw error; } - } - $('mm-queue-refresh').addEventListener('click', () => { clearError(); loadQueue().catch(showError); }); - $('mm-commands-more').addEventListener('click', () => loadHistory(true).catch(showError)); - document.querySelectorAll('[data-mm-command]').forEach(button => button.addEventListener('click', () => preview(button.dataset.mmCommand))); - return { renderCatalogue, loadHistory, loadQueue, - inspect(title, details) { intent = null; display(title, [node('code', details, 'mm-long-code')], null, false); }, - close(force = false) { if (force || !working) { dialog.close(); intent = null; } }, - }; - }; -})(); diff --git a/src/public/js/m3ter-electrical.js b/src/public/js/m3ter-electrical.js deleted file mode 100644 index 1f21a00..0000000 --- a/src/public/js/m3ter-electrical.js +++ /dev/null @@ -1,72 +0,0 @@ -(function () { - 'use strict'; - const $ = id => document.getElementById(id); - const el = (tag, text = '', className = '') => { const e = document.createElement(tag); e.textContent = text; if (className) e.className = className; return e; }; - const fixed = (n, precision = 2) => typeof n === 'number' && Number.isFinite(n) ? n.toFixed(precision) : '—'; - const date = n => n ? new Date(n).toLocaleString() : 'Unavailable'; - let snapshot = null, rendered = ''; - function list(values) { - const dl = el('dl', '', 'mm-info'); - for (const [name, value] of values) dl.append(el('dt', name), el('dd', value)); - return dl; - } - function metric(name, value, unit) { - const card = el('article', '', 'mm-metric'), strong = el('strong', value); - strong.append(el('em', ' ' + unit)); card.append(el('span', name), strong); return card; - } - function tick() { - const state = snapshot?.state, latest = state?.latest; - const age = latest ? Math.max(0, Math.floor((Date.now() - latest.timestamp) / 1000)) : null; - const stale = latest && Date.now() - latest.timestamp > snapshot.staleAfter; - $('mm-telemetry-freshness').textContent = !latest ? 'Telemetry unavailable' : `${stale ? 'Stale' : 'Fresh'} telemetry · ${age < 60 ? age + 's' : age < 3600 ? Math.floor(age / 60) + 'm' : Math.floor(age / 3600) + 'h'} ago`; - $('mm-telemetry-freshness').dataset.state = latest && !stale ? 'active' : 'inactive'; - } - function render(next) { - snapshot = next; - const fingerprint = JSON.stringify(next); - if (fingerprint === rendered) { tick(); return; } - rendered = fingerprint; - const state = next?.state, sample = state?.latest, t = sample?.telemetry; - const status = next?.status || 'Unknown · monitoring telemetry has not been observed.'; - $('mm-telemetry-mode').textContent = status; - $('mm-telemetry-command-status').textContent = status + (next?.intervalRequest ? ` Last requested interval: ${next.intervalRequest.command.value}s (${next.intervalRequest.status}; application unverified).` : ''); - $('mm-telemetry-time').textContent = `FPort 4 measurement: ${date(sample?.timestamp)}`; - $('mm-telemetry-cadence').textContent = `Stale after ${fixed((next?.staleAfter || 180000) / 1000, 0)} seconds · ${next?.intervalBasis || 'cadence unknown'}. MQTT connectivity is separate from telemetry freshness.`; - $('mm-electrical-empty').hidden = !!t; $('mm-electrical-data').hidden = !t; - for (const id of ['mm-electrical-main','mm-electrical-phases','mm-electrical-neutral','mm-electrical-status','mm-electrical-energy','mm-electrical-tracking']) $(id).replaceChildren(); - $('mm-electrical-raw').textContent = ''; - if (!t) { tick(); return; } - $('mm-electrical-main').append(metric('Total active power',fixed(t.activePower.total,1),'W'), metric('Total reactive power',fixed(t.reactivePower.total,1),'var'), - metric('Total power factor',fixed(t.powerFactor.total,3),''), metric('Frequency',fixed(t.frequency),'Hz'), metric('Metering chip temperature',fixed(t.temperature,0),'°C')); - for (const phase of ['a','b','c']) { - const card = el('article','','mm-command-card'); card.dataset.phase = phase; - card.append(el('h4',`Phase ${phase.toUpperCase()}`), list([ - ['Voltage',`${fixed(t.voltage[phase])} V`],['Current',`${fixed(t.current[phase])} A`], - ['Active power',`${fixed(t.activePower[phase],1)} W`],['Reactive power',`${fixed(t.reactivePower[phase],1)} var`],['Power factor',fixed(t.powerFactor[phase],3)], - ])); $('mm-electrical-phases').append(card); - } - $('mm-electrical-neutral').append(metric('Measured neutral current',fixed(t.neutralMeasured),'A'),metric('Calculated neutral current',fixed(t.neutralCalculated),'A')); - $('mm-electrical-status').append(list([ - ['Uptime',`${Math.floor(t.uptime / 86400)}d ${Math.floor(t.uptime / 3600) % 24}h ${Math.floor(t.uptime / 60) % 60}m ${t.uptime % 60}s`], - ['Phase mode',t.phaseMode === 'three-phase' ? 'Three-phase' : `Phase ${t.phaseMode.toUpperCase()}`], - ['Relay',t.relayClosed ? 'Closed (reported)' : 'Open (reported)'],['Relay fitted',t.relayFitted ? 'Yes' : 'No'], - ['Current PGA',t.currentPga === null ? 'Unknown / reserved flag' : `×${t.currentPga}`], - ['Voltage PGA',t.voltagePga === null ? 'Unknown / reserved flag' : `×${t.voltagePga}`],['Received by Console',date(sample.receivedAt)], - ])); - for (const phase of ['a','b','c','total']) { - const card = el('article','','mm-command-card'); - card.append(el('h4',phase === 'total' ? 'Total energy' : `Phase ${phase.toUpperCase()} energy`),list([ - ['Forward counter',`${fixed(t.forwardEnergy[phase],5)} kWh`],['Reverse counter',`${fixed(t.reverseEnergy[phase],5)} kWh`], - ['Forward increase',`${fixed(state.tracking.forward?.[phase],5)} kWh`],['Reverse increase',`${fixed(state.tracking.reverse?.[phase],5)} kWh`], - ['Observed forward total',`${fixed(state.totals.forward[phase],5)} kWh`],['Observed reverse total',`${fixed(state.totals.reverse[phase],5)} kWh`], - ])); $('mm-electrical-energy').append(card); - } - const explanations = { baseline: 'First frame establishes a baseline; no prior consumption is inferred.', restart: 'Uptime decreased: restart detected. New baselines established; observed totals preserved.', - 'counter-decrease': 'Counter decrease without an uptime reset: affected increases are unknown. High-water baselines are retained to avoid double counting.', tracked: 'Counter increases tracked between valid frames.' }; - $('mm-electrical-tracking').append(el('p',explanations[state.tracking.status] || state.tracking.status),el('p',`Observed totals since ${date(state.startedAt)} exclude unknown energy before the first frame and across resets. They are not billing or guaranteed lifetime totals.`)); - if (state.tracking.estimatedForward !== null) $('mm-electrical-tracking').append(el('p',`Power-based estimate for this interval: ${fixed(state.tracking.estimatedForward,5)} kWh. ${state.tracking.discrepancy ? 'Counter increase differs by more than 50% or 0.01 kWh (whichever is larger). Sparse samples or changing loads can explain this; counters were not altered.' : 'Sanity check only; counters were not altered.'}`)); - $('mm-electrical-raw').textContent = `Measurement UTC: ${new Date(sample.timestamp).toISOString()}\nOriginal payload (${sample.metadata.payloadEncoding || 'unavailable'}): ${sample.rawPayload ?? 'Not supplied; decoded object used'}\nHex: ${sample.metadata.payloadHex || 'Not supplied'}\nMetadata: ${JSON.stringify(sample.metadata,null,2)}\nDecoded telemetry: ${JSON.stringify(t,null,2)}`; - tick(); - } - window.M3terElectrical = { render, tick }; -})(); diff --git a/src/public/js/m3ter-manager.js b/src/public/js/m3ter-manager.js deleted file mode 100644 index a441acf..0000000 --- a/src/public/js/m3ter-manager.js +++ /dev/null @@ -1,297 +0,0 @@ -(function () { - 'use strict'; - const root = document.getElementById('m3ter-manager'); if (!root) return; - const $ = id => document.getElementById(id); - const text = (id, value) => { $(id).textContent = value; }; - const node = (tag, value = '', className = '') => { const result = document.createElement(tag); result.textContent = value; if (className) result.className = className; return result; }; - const date = value => value ? new Date(value).toLocaleString() : 'Unavailable'; - const fixed = (value, places) => typeof value === 'number' && Number.isFinite(value) ? value.toFixed(places) : '—'; - let authenticated = false, authVersion = 0; - let active = false, device = null, latest = null, state = null, config = null, electrical = null, tab = 'overview', monitoring = { state: 'disconnected' }; - let socket, reconnectTimer, clockTimer, refreshTimer, searchTimer, streamTimer, pollTimer; - let polling = false, pollVersion = 0, snapshotVersion = 0, searchVersion = 0; - let devices = [], deviceOffset = 0, historyOffset = 0, eventOffset = 0, historyData = null; - function notice(message) { text('mm-notice', message); $('mm-notice').hidden = !message; } - function showError(error) { if (!authenticated) return; if (error?.name === 'AbortError') return; text('mm-error', error.message || 'Unable to load meter data. Retry using Refresh.'); $('mm-error').hidden = false; } - function clearError() { $('mm-error').hidden = true; } - async function api(path, options = {}) { - const version = authVersion, controller = new AbortController(); - const timeout = setTimeout(() => controller.abort(), 15000); - try { - const response = await fetch('/api/m3ter-manager' + path, { ...options, signal: controller.signal, cache: 'no-store', headers: { 'Content-Type': 'application/json' }, - body: options.body === undefined ? undefined : JSON.stringify(options.body) }); - let data; try { data = await response.json(); } catch (error) { - if (controller.signal.aborted) throw error; - const detail = response.status === 403 ? 'Request rejected by the server. Reload Console at its current address and retry.' : response.status === 404 ? 'The running backend does not have the Manager API. Deploy the matching Console build.' : 'Check the Console backend and proxy connection.'; - throw new Error(`Meter API returned HTTP ${response.status}. ${detail}`); - } - if (path !== '/session' && version !== authVersion) throw new DOMException('Session changed', 'AbortError'); - if (response.status === 401 && path !== '/session') lock('Your session ended. Sign in again.'); - if (!response.ok) throw new Error(data.error || 'Meter request failed. Please retry.'); return data; - } catch (error) { - if (controller.signal.aborted) throw new Error('Meter request timed out. Check the Console or relay connection and retry.'); - throw error; - } finally { clearTimeout(timeout); } - } - const commands = M3terCommands({ api, selected: () => device, showError, clearError, notice, element: $, refresh, text, node }); - function range() { - const selected = $('mm-range').value; - if (selected !== 'custom') { const to = Date.now(); return { from: to - Number(selected), to }; } - const from = new Date($('mm-from').value).getTime(), to = new Date($('mm-to').value).getTime(); - if (!Number.isFinite(from) || !Number.isFinite(to) || from >= to || to - from > 366 * 86400000) throw new Error('Choose a valid date range of at most 366 days.'); - return { from, to }; - } - function relative(timestamp) { - if (!timestamp) return 'Never observed'; - const seconds = Math.max(0, Math.floor((Date.now() - timestamp) / 1000)); - return seconds < 60 ? `${seconds}s ago` : seconds < 3600 ? `${Math.floor(seconds / 60)}m ago` : seconds < 86400 ? `${Math.floor(seconds / 3600)}h ago` : `${Math.floor(seconds / 86400)}d ago`; - } - function renderActivity() { - M3terElectrical.tick(); - const status = monitoring.state || 'disconnected'; text('mm-mqtt', `MQTT ${status}`); $('mm-mqtt').dataset.state = status; - text('mm-last-message', `Last MQTT message: ${date(monitoring.lastMessage)}`); - const last = state?.lastUplink || null, recent = last && Date.now() - last <= (config?.inactiveMilliseconds || 300000); - text('mm-age', relative(last)); text('mm-uplink-time', date(last)); - text('mm-activity', !last ? 'No uplink observed' : recent ? 'Recent uplink' : 'No recent uplink'); $('mm-activity').dataset.state = recent ? 'active' : 'inactive'; - $('mm-activity').title = `Activity threshold: ${(config?.inactiveMilliseconds || 300000) / 1000} seconds. Connectivity is not verified.`; - } - function renderInfo() { - if (!device) return; - text('mm-name', device.name || device.devEui); text('mm-eui', device.devEui); - text('mm-energy', fixed(latest?.energy, 6)); text('mm-voltage', fixed(latest?.voltage, 1)); text('mm-nonce', latest?.nonce ?? '—'); - text('mm-energy-time', latest ? date(latest.timestamp) : 'Awaiting telemetry'); - text('mm-voltage-note', device.phaseMode === 'three-phase' && latest ? `Sum of phases · calculated mean ${fixed(latest.voltage / 3, 1)} V (metadata mode)` : `Transmitted value · ${device.phaseMode || 'phase mode unknown'}`); - const values = [ - ['Meter', device.name], ['DevEUI', device.devEui], ['Application', device.applicationName || state?.metadata?.applicationName], - ['Device profile', device.deviceProfileName || state?.metadata?.deviceProfileName], ['LoRaWAN class (ChirpStack)', device.enabledClass], - ['Device enabled', device.isDisabled === undefined ? null : device.isDisabled ? 'Disabled in ChirpStack' : 'Enabled in ChirpStack'], - ['Last observed uplink', date(state?.lastUplink)], ['ChirpStack last seen', date(device.lastSeenAt)], ['Energy', latest ? `${fixed(latest.energy,6)} kWh` : null], - ['Voltage', latest ? `${fixed(latest.voltage,1)} V` : null], ['Nonce', latest?.nonce], ['Accumulation', state?.accumulation?.uncertain ? 'Uncertain reset or gap; awaiting a new cycle' : 'Pending acknowledgement; repeated snapshots are not separate consumption'], ['Pending cycle high-water (kWh)', state?.accumulation ? fixed(state.accumulation.highWater / 1e6,6) : null], ['Phase mode (metadata)', device.phaseMode], - ]; - $('mm-info').replaceChildren(...values.flatMap(([name, value]) => [node('dt', name), node('dd', value === null || value === undefined || value === '' ? 'Unavailable' : String(value))])); - const key = state?.publicKey || latest?.publicKey; - text('mm-public-key', key || 'Unavailable'); $('mm-copy-key').disabled = !key; - text('mm-verification', latest ? `Latest signed fields: ${latest.verification}. ${latest.verification === 'invalid' ? 'Do not treat this reading as authenticated.' : latest.verification === 'unverified' ? 'No known public key was available to verify this signature.' : 'Nonce and energy were checked with Ed25519.'}` : 'No signature available.'); - const location = state?.metadata?.location; $('mm-location').hidden = !location; - if (location) { - const link = node('a', 'View device location on OpenStreetMap ↗'); link.href = `https://www.openstreetmap.org/?mlat=${encodeURIComponent(location.latitude)}&mlon=${encodeURIComponent(location.longitude)}#map=15/${encodeURIComponent(location.latitude)}/${encodeURIComponent(location.longitude)}`; link.target = '_blank'; link.rel = 'noopener noreferrer'; - $('mm-location').replaceChildren(node('p', `Device location: ${location.latitude}, ${location.longitude} · ChirpStack location event`), link); - } - M3terElectrical.render(electrical); - renderActivity(); - } - function renderHistory() { - if (!historyData) return; - for (const view of ['overview', 'history']) for (const field of ['energy','voltage']) { - const container = $(`mm-${view}-${field}`); - M3terCharts.render(container, historyData.chart, field); - // Keep Analytics unchanged while simplifying the Overview for screen readers too. - if (view === 'overview') { - const svg = container.querySelector('svg'); - if (svg) svg.setAttribute('aria-label', `${field === 'energy' ? 'Energy in kWh' : 'Voltage in volts'}. Use left and right arrows to inspect readings.`); - } - } - const summary = historyData.summary; - text('mm-summary', `${historyData.total} retained reports (${historyData.retentionLimit} globally). Completed-cycle observed lower bounds: ${fixed(summary?.observedConsumption || 0, 6)} kWh. Collector-recorded energy in those completed cycles: ${fixed(summary?.collectedEnergy || 0, 6)} kWh. These are not blockchain settlement totals. Pending snapshots are not added. ${summary?.uncertainReports || 0} uncertain or delayed reports.`); - const parent = $('mm-readings'); parent.replaceChildren(); - historyData.rows.forEach(row => { - const tr = node('tr'); [date(row.timestamp), fixed(row.energy,6), fixed(row.voltage,1), row.nonce, row.fPort].forEach(value => tr.append(node('td', String(value)))); - const td = node('td'), button = node('button', 'Inspect', 'nes-btn'); button.addEventListener('click', () => commands.inspect('Uplink details', - `Meter: ${row.devEui}\nUTC: ${new Date(row.timestamp).toISOString()}\nReceived: ${new Date(row.receivedAt).toISOString()}\nFPort: ${row.fPort}\nNonce: ${row.nonce}\nRaw energy: ${row.rawEnergy}\nAccumulator: ${row.energy} kWh\nCompleted previous cycle lower bound: ${row.intervalEnergy ?? 'Pending / uncertain'} kWh\nCollector-recorded energy for completed cycle: ${row.collectedEnergy ?? 'Unavailable'} kWh\nCompleted nonce: ${row.completedNonce ?? 'None'}\nAccounting: ${row.accounting}\nRaw voltage: ${row.rawVoltage}\nVoltage: ${row.voltage} V\nSignature status: ${row.verification}\nSignature (hex): ${row.signature}\nPublic key: ${row.publicKey || 'Not present in this uplink'}\nRaw payload (${JSON.parse(row.metadata || '{}').payloadEncoding === 'hex' ? 'Hex' : 'Base64'}): ${row.rawPayload}\nRadio metadata: ${row.metadata}`)); td.append(button); tr.append(td); parent.append(tr); - }); - if (!historyData.rows.length) { const tr = node('tr'), cell = node('td', 'No readings in this range.'); cell.colSpan = 6; tr.append(cell); parent.append(tr); } - text('mm-history-count', `${historyData.total ? historyOffset + 1 : 0}–${Math.min(historyOffset + historyData.rows.length, historyData.total)} of ${historyData.total}`); - $('mm-history-prev').disabled = !historyOffset; $('mm-history-next').disabled = historyOffset + 50 >= historyData.total; - } - async function loadEvents(append = false) { - const current = device?.devEui; if (!current) return; - if (!append) eventOffset = 0; - const data = await api(`/devices/${current}/events?offset=${eventOffset}`); if (device?.devEui !== current) return; - const parent = $('mm-events'); if (!append) parent.replaceChildren(); - if (!data.events.length && !append) parent.append(node('li', 'No activity recorded yet.')); - data.events.forEach(event => { - const li = node('li'); li.append(node('strong', event.message), node('small', `${date(event.timestamp)} · ${event.source}${event.devEui ? '' : ' · application-wide'}`)); - if (event.rawPayload !== null && event.rawPayload !== undefined) { - const metadata = typeof event.metadata === 'string' ? JSON.parse(event.metadata) : event.metadata || {}; - const details = node('details'); details.append(node('summary', 'Inspect payload')); - if (metadata.payloadHex) details.append(node('small', 'Payload (hex)'), node('code', metadata.payloadHex, 'mm-long-code')); - details.append(node('small', `Original ${metadata.payloadField || 'data'} (${metadata.payloadEncoding || 'base64'})`), node('code', event.rawPayload, 'mm-long-code')); - li.append(details); - } - parent.append(li); - }); - eventOffset += data.events.length; $('mm-events-more').hidden = data.events.length < 100; - } - async function refresh(telemetryOnly = false, background = false) { - if (!device) return; - const current = device.devEui, version = ++snapshotVersion; - let times; try { times = range(); } catch (error) { showError(error); return; } - $('mm-selected').setAttribute('aria-busy', 'true'); - const results = await Promise.allSettled([ - telemetryOnly ? Promise.resolve({ device, state, latest }) : api(`/devices/${current}`), api(`/devices/${current}/history?${new URLSearchParams({ ...times, offset: historyOffset })}`), - ]); - if (version !== snapshotVersion || device?.devEui !== current || !active) return; - if (results[0].status === 'fulfilled') { device = { ...device, ...results[0].value.device }; state = results[0].value.state; latest = results[0].value.latest; if (!telemetryOnly) electrical = results[0].value.electrical || null; } - else if (!background) showError(results[0].reason); - if (results[1].status === 'fulfilled') { historyData = results[1].value; latest = historyData.latest; state = historyData.state; monitoring = historyData.monitoring; electrical = historyData.electrical || null; renderHistory(); } - else if (!background) showError(results[1].reason); - renderInfo(); $('mm-selected').setAttribute('aria-busy', 'false'); - if (tab === 'live') await loadEvents().catch(showError); - if (tab === 'commands') await commands.loadHistory().catch(showError); - if (tab === 'queue') await commands.loadQueue().catch(showError); - return results[1].status === 'fulfilled'; - } - async function loadDevices(append = false) { - const version = ++searchVersion, search = $('mm-search').value.trim(); - if (!append) deviceOffset = 0; - try { - const data = await api(`/devices?${new URLSearchParams({ search, offset: deviceOffset })}`); - if (version !== searchVersion || !active) return; - devices = append ? [...devices, ...data.devices] : data.devices; deviceOffset = data.offset + data.devices.length; - $('mm-more-devices').hidden = deviceOffset >= data.total; $('mm-device').replaceChildren(node('option', data.total ? 'Choose a meter…' : 'No matching meters')); - $('mm-device').firstChild.value = ''; - const available = device && !devices.some(item => item.devEui === device.devEui) ? [device, ...devices] : devices; - available.forEach(item => { const option = node('option', `${item.name} · ${item.devEui}`); option.value = item.devEui; $('mm-device').append(option); }); - $('mm-device').value = device?.devEui || ''; - if (!device) { - let saved; try { saved = localStorage.getItem('m3tering.manager.selected'); } catch { /* Optional preference. */ } - if (saved && devices.some(item => item.devEui === saved)) { $('mm-device').value = saved; selectDevice(saved); } - } - } catch (error) { if (version === searchVersion) showError(error); } - } - function selectDevice(devEui) { - snapshotVersion++; device = devices.find(item => item.devEui === devEui) || (device?.devEui === devEui ? device : null); - latest = null; state = null; electrical = null; M3terElectrical.render(null); historyData = null; historyOffset = 0; commands.close(); - $('mm-empty').hidden = !!device; $('mm-selected').hidden = !device; clearError(); notice(''); - for (const view of ['overview','history']) for (const field of ['energy','voltage']) $(`mm-${view}-${field}`).replaceChildren(node('p', 'Loading readings…', 'mm-note')); - ['mm-readings','mm-events','mm-command-history','mm-queue'].forEach(id => $(id).replaceChildren()); - if (device) { try { localStorage.setItem('m3tering.manager.selected', device.devEui); } catch { /* Optional preference. */ } renderInfo(); refresh().catch(showError); } - } - function selectTab(next) { - tab = next; - root.querySelectorAll('[data-mm-tab]').forEach(button => { if (button.dataset.mmTab === next) button.setAttribute('aria-current','page'); else button.removeAttribute('aria-current'); }); - root.querySelectorAll('[data-mm-panel]').forEach(panel => { panel.hidden = panel.dataset.mmPanel !== next; }); - if (next === 'live') loadEvents().catch(showError); - if (next === 'commands') commands.loadHistory().catch(showError); - if (next === 'queue') commands.loadQueue().catch(showError); - } - function stopPolling() { polling = false; pollVersion++; clearTimeout(pollTimer); } - function startPolling() { - if (polling || !active || !authenticated) return; - polling = true; - const version = ++pollVersion; - text('mm-feed', 'Live feed unavailable · checking HTTP updates…'); - $('mm-feed').title = 'The WebSocket could not be maintained. Authenticated HTTP requests keep readings updated without changing the MQTT connection.'; - async function poll() { - let available = false; - try { - if (device) available = await refresh(true, true); - else { - const result = await api('/config'); - if (version !== pollVersion || !active) return; - monitoring = result.monitoring; renderActivity(); available = true; - } - } catch { /* Status below reports failure; 401 is handled by the existing login boundary. */ } - if (version !== pollVersion || !active || !authenticated) return; - text('mm-feed', available ? 'Updates every 5s (HTTP fallback)' : 'Automatic updates unavailable · retrying'); - // Schedule after completion: a slow relay cannot accumulate overlapping polls. - pollTimer = setTimeout(poll, 5000); - } - void poll(); - } - function connectStream() { - if (!active || !authenticated || socket?.readyState === WebSocket.OPEN || socket?.readyState === WebSocket.CONNECTING) return; - if (!polling) { text('mm-feed', 'Live feed connecting…'); $('mm-feed').title = ''; } - let currentSocket; - try { currentSocket = new WebSocket(`${location.protocol === 'https:' ? 'wss:' : 'ws:'}//${location.host}/m3ter-manager/live`); } - catch { startPolling(); reconnectTimer = setTimeout(connectStream, 30000); return; } - socket = currentSocket; - let receivedUpdate = false; - function armTimeout(milliseconds) { - clearTimeout(streamTimer); - streamTimer = setTimeout(() => { - if (socket !== currentSocket || !active) return; - // Detach a stalled transport before retrying; some relays never finish a handshake. - socket = null; currentSocket.close(); startPolling(); reconnectTimer = setTimeout(connectStream, 30000); - }, milliseconds); - } - armTimeout(10000); - currentSocket.onopen = () => { if (socket === currentSocket && active) armTimeout(10000); }; - currentSocket.onmessage = event => { - if (socket !== currentSocket || !active) return; - let update; try { update = JSON.parse(event.data); } catch { return; } - if (!['connection','diagnostic','device'].includes(update?.type)) return; - armTimeout(75000); // The server sends a status heartbeat every 30 seconds. - if (!receivedUpdate) { - receivedUpdate = true; stopPolling(); text('mm-feed', 'Live feed connected'); $('mm-feed').title = ''; - if (device) refresh().catch(showError); - } - if (update.type === 'connection') { monitoring = update.monitoring; renderActivity(); } - if (update.type === 'diagnostic') showError(new Error(update.message)); - if (update.type === 'device' && update.devEui === device?.devEui && !refreshTimer) refreshTimer = setTimeout(() => { refreshTimer = null; if (active) refresh(true).catch(showError); }, 500); - }; - currentSocket.onerror = () => { if (socket === currentSocket && active) startPolling(); }; - currentSocket.onclose = event => { - if (socket !== currentSocket) return; - socket = null; clearTimeout(streamTimer); - if (!active) return; - if (event.code === 4001) { lock('Your session ended. Sign in again.'); return; } - startPolling(); reconnectTimer = setTimeout(connectStream, 30000); - }; - } - function lock(message = '') { - authVersion++; close(); authenticated = false; config = null; device = null; state = null; latest = null; electrical = null; M3terElectrical.render(null); historyData = null; devices = []; - commands.close(true); $('mm-workspace').hidden = true; $('mm-login').hidden = false; - $('mm-password').value = ''; $('mm-device').replaceChildren(node('option', 'Choose a meter…')); - ['mm-readings','mm-events','mm-command-history','mm-queue','mm-info','mm-dialog-content'].forEach(id => $(id).replaceChildren()); - $('mm-selected').hidden = true; $('mm-empty').hidden = false; - text('mm-login-error', message); $('mm-login-error').hidden = !message; - } - async function startSession() { - authenticated = true; active = true; $('mm-login').hidden = true; $('mm-workspace').hidden = false; - notice('Loading meters…'); clearError(); const version = authVersion; - try { config = await api('/config'); if (!active || version !== authVersion) return; monitoring = config.monitoring; commands.renderCatalogue(config.commands); - if (config.demo) root.querySelector('.mm-brand small').textContent = 'Demo network · simulated meters'; - await loadDevices(); if (!active || version !== authVersion) return; - notice(config.billingAutomationActive ? 'Existing console billing automation is enabled and may also control these meters. M3ter Manager only observes telemetry; it does not acknowledge energy reports automatically.' : ''); - connectStream(); clockTimer = setInterval(renderActivity, 1000); if (device) await refresh(); - } catch (error) { notice(''); showError(error); } - } - async function open() { - if (active) return; active = true; $('mm-workspace').hidden = true; $('mm-login').hidden = false; - const version = authVersion; - try { - const session = await api('/session'); if (!active || version !== authVersion) return; - text('mm-login-help', session.configured ? 'Use the manager credentials configured by your console administrator.' : 'Set M3TER_MANAGER_PASSWORD in .env, then restart the console. The username defaults to admin.'); - if (session.authenticated) await startSession(); - } catch (error) { text('mm-login-error', error.message); $('mm-login-error').hidden = false; } - } - $('mm-login-form').addEventListener('submit', async event => { - event.preventDefault(); $('mm-login-submit').disabled = true; $('mm-login-error').hidden = true; - try { - await api('/session', { method: 'POST', body: { username: $('mm-username').value, password: $('mm-password').value } }); - $('mm-password').value = ''; if (!root.hidden) await startSession(); - } catch (error) { text('mm-login-error', error.message); $('mm-login-error').hidden = false; } - finally { $('mm-login-submit').disabled = false; } - }); - $('mm-logout').addEventListener('click', async () => { - try { await api('/session', { method: 'DELETE' }); lock(); } - catch (error) { showError(new Error('Sign-out could not reach the server. Please retry.')); } - }); - function close() { active = false; snapshotVersion++; searchVersion++; stopPolling(); clearTimeout(streamTimer); clearTimeout(reconnectTimer); clearTimeout(refreshTimer); clearTimeout(searchTimer); clearInterval(clockTimer); refreshTimer = null; const previous = socket; socket = null; previous?.close(); text('mm-feed', 'Live feed closed'); commands.close(); } - $('mm-device').addEventListener('change', () => selectDevice($('mm-device').value)); - $('mm-search').addEventListener('input', () => { clearTimeout(searchTimer); searchTimer = setTimeout(() => loadDevices(), 250); }); - $('mm-more-devices').addEventListener('click', () => loadDevices(true)); - $('mm-refresh').addEventListener('click', async () => { if (!config) { close(); await open(); } else { clearError(); await loadDevices(); await refresh(); } }); - root.querySelectorAll('[data-mm-tab]').forEach(button => button.addEventListener('click', () => selectTab(button.dataset.mmTab))); - root.querySelectorAll('[data-mm-go]').forEach(button => button.addEventListener('click', () => selectTab(button.dataset.mmGo))); - $('mm-range').addEventListener('change', () => { $('mm-dates').hidden = $('mm-range').value !== 'custom'; historyOffset = 0; if ($('mm-range').value !== 'custom') { clearError(); refresh().catch(showError); } }); - $('mm-dates').addEventListener('submit', event => { event.preventDefault(); historyOffset = 0; clearError(); refresh().catch(showError); }); - $('mm-history-prev').addEventListener('click', () => { historyOffset = Math.max(0, historyOffset - 50); refresh().catch(showError); }); - $('mm-history-next').addEventListener('click', () => { historyOffset += 50; refresh().catch(showError); }); - $('mm-events-more').addEventListener('click', () => loadEvents(true).catch(showError)); - $('mm-copy-key').addEventListener('click', async () => { try { await navigator.clipboard.writeText(state?.publicKey || latest?.publicKey); notice('Public key copied.'); } catch { notice('Clipboard unavailable. Select and copy the displayed public key.'); } }); - window.addEventListener('desktop:open', event => { if (event.detail.id === 'm3ter-manager') open(); }); - window.addEventListener('desktop:close', event => { if (event.detail.id === 'm3ter-manager') close(); }); - window.addEventListener('pagehide', close); -})(); diff --git a/src/services/downlink.ts b/src/services/downlink.ts new file mode 100644 index 0000000..3848836 --- /dev/null +++ b/src/services/downlink.ts @@ -0,0 +1,8 @@ +/** A state reply for one signed usage report, not a technician command API. */ +export interface StateDownlink { + devEui: string; + fPort: 2; + confirmed: false; + bytes: number[]; +} +export type DownlinkSink = (decision: StateDownlink) => Promise; diff --git a/src/services/mqtt.ts b/src/services/mqtt.ts index 9ce587e..a23b657 100644 --- a/src/services/mqtt.ts +++ b/src/services/mqtt.ts @@ -1,9 +1,8 @@ import { connect, MqttClient } from 'mqtt'; import { randomUUID } from 'crypto'; -import { connectionState, ingestEvent } from '../m3ter/monitor'; -import { collectorAccepted } from '../m3ter/store'; -import { applicationId } from '../m3ter/chirpstack'; +import { applicationId } from '../lib/chirpstack-config'; import { enqueue } from './grpc'; +import type { DownlinkSink } from './downlink'; import { encode } from '../lib/encode'; import { getAllTransactionRecords, getMeterByDevEui, getMeterByPublicKey, @@ -20,9 +19,9 @@ import { meterIdFromPublicKeyContractCall } from '../utils/contracts'; const logger = createLogger('[mqtt]'); const deviceLocks = new Set(); const meterLocks = new Set(); -let monitoringClient: MqttClient | undefined; +let collectorClient: MqttClient | undefined; -// One address for the existing process-level service and both consumers. +// Existing process-level broker configuration, also reused by the opt-in agent. export function mqttConnection(): string | { host: string; port: number } { if (!process.env.MQTT_URL) return { host: process.env.CHIRPSTACK_HOST || 'localhost', port: 1883 }; try { @@ -33,20 +32,13 @@ export function mqttConnection(): string | { host: string; port: number } { } // Optional arguments are dependency injection for integration tests, not configuration. export async function handleUplinks(connection = mqttConnection(), collect = handleMessage): Promise { - if (monitoringClient) return true; + if (collectorClient) return true; const application = applicationId(); const topic = `application/${application}/device/+/event/+`; - const status = (state: string, message?: string) => { - try { connectionState(state, message); } catch { logger.error('Manager status update failed; MQTT collection continues'); } - }; - status('connecting'); const options = { clientId: `console-${randomUUID()}`, clean: true, resubscribe: false, connectTimeout: 9000, reconnectPeriod: 2000 }; - const client = monitoringClient = typeof connection === 'string' ? connect(connection, options) : connect({ ...connection, ...options }); - client.on('reconnect', () => { status('reconnecting'); void notifyHook('onMqttReconnect', client); }); - client.on('offline', () => status('disconnected')); - client.on('close', () => status('disconnected')); + const client = collectorClient = typeof connection === 'string' ? connect(connection, options) : connect({ ...connection, ...options }); + client.on('reconnect', () => { void notifyHook('onMqttReconnect', client); }); client.on('message', (receivedTopic, blob) => { - // Fan out independently. Neither consumer owns the other's lifecycle or errors. try { const match = receivedTopic.match(/^application\/([^/]+)\/device\/([a-f0-9]{16})\/event\/up$/i); if (match && match[1].toLowerCase() === application) { @@ -58,35 +50,33 @@ export async function handleUplinks(connection = mqttConnection(), collect = han } } } catch { logger.warn('Invalid collector MQTT event ignored'); } - try { ingestEvent(receivedTopic, blob); } - catch { logger.error('Manager ingestion failed; collector delivery was preserved'); } }); client.on('connect', () => { client.subscribe(topic, { qos: 1 }, (error, granted) => { if (error || granted?.some(subscription => subscription.qos === 128)) { logger.error('MQTT subscription rejected. Check broker permissions.'); - status('error', 'MQTT subscription rejected. Check broker permissions.'); client.stream.destroy(); return; // reconnect, then subscribe exactly once again } - logger.info('MQTT connected and subscribed for both collector and Manager'); - status('connected'); void notifyHook('onMqttSubscribed', client, topic); + logger.info('MQTT collector connected and subscribed'); + void notifyHook('onMqttSubscribed', client, topic); }); void notifyHook('onMqttConnect', client); }); client.on('error', error => { logger.error(`MQTT connection error: ${(error as NodeJS.ErrnoException).code || 'broker error'}`); - status('error', 'MQTT connection failed. Check the existing ChirpStack broker connection.'); void notifyHook('onMqttError', error, client); // MQTT.js owns reconnection. Do not end the client on a transient error. }); - return true; // The dashboard stays available while MQTT is connecting/reconnecting. + return true; // HTTP remains available while MQTT reconnects. } export function stopUplinks(): void { - monitoringClient?.end(true); monitoringClient = undefined; connectionState('disconnected'); + collectorClient?.end(true); collectorClient = undefined; } -export async function handleMessage(blob: Buffer): Promise { +const chirpstackSink: DownlinkSink = decision => enqueue(decision.devEui, decision.bytes); + +export async function handleMessage(blob: Buffer, downlink: DownlinkSink = chirpstackSink): Promise { let devEui: string | undefined; let lockedMeter: string | undefined; let ownsDeviceLock = false; @@ -143,8 +133,6 @@ export async function handleMessage(blob: Buffer): Promise { // Acknowledgement means both the transaction and its nonce are durable. recordMeterTransaction(key, record); newTransaction = true; - try { collectorAccepted(applicationId(), devEui!, decoded.nonce, transaction.readUInt32BE(4)); } - catch { log.warn('Manager collector observation unavailable; collection continues'); } } else if (decoded.nonce !== 0) { const previous = getTransactionByNonce(decoded.nonce, meter.tokenId); if (decoded.nonce !== meter.latestNonce || !previous || decoded.energy < decodePayload(Buffer.from(previous.raw, 'hex')).energy) { @@ -163,7 +151,8 @@ export async function handleMessage(blob: Buffer): Promise { void notifyHook('onIsOnStateComputed', meter.tokenId, is_on); const state = decoded.nonce === 0 ? { nonce: meter.latestNonce, is_on } : { is_on }; try { - await enqueue(devEui!, encode(state as State, decoded.extensions.latitude ?? 0, decoded.extensions.longitude ?? 0)); + await downlink({ devEui: devEui!, fPort: 2, confirmed: false, + bytes: encode(state as State, decoded.extensions.latitude ?? 0, decoded.extensions.longitude ?? 0) }); void notifyHook('onStateEnqueued', state, decoded.extensions.latitude ?? 0, decoded.extensions.longitude ?? 0); } finally { // Delivery services run after the downlink attempt and cannot prevent it. diff --git a/src/services/server.ts b/src/services/server.ts index 2d20610..99abae4 100644 --- a/src/services/server.ts +++ b/src/services/server.ts @@ -3,7 +3,6 @@ import { create } from 'express-handlebars'; import express, { Express, Request, Response } from 'express'; import { requireSameOrigin } from './auth'; import { proxyChirpstack } from './chirpstack'; -import { managerRouter, attachManagerStream } from '../m3ter/api'; import { createLogger } from '../utils/logger'; import { getUIComponents, invokeUIAction } from '../lib/utils'; @@ -32,7 +31,6 @@ app.get('/healthz', (_req, res) => res.json({ status: 'ok' })); app.use(express.json()); app.use(express.static('./src/public')); app.use(express.urlencoded({ extended: true })); -app.use('/api/m3ter-manager', managerRouter); app.get('/', async (req: Request, res: Response, next) => { try { @@ -63,7 +61,6 @@ app.post('/api/actions/:moduleId/:actionId', async (req: Request, res: Response, }); export const server = http.createServer(app); -attachManagerStream(server); export function startServer() { server.once('error', (error: NodeJS.ErrnoException) => { diff --git a/src/store/sqlite.ts b/src/store/sqlite.ts index 1b80716..6531536 100644 --- a/src/store/sqlite.ts +++ b/src/store/sqlite.ts @@ -3,7 +3,6 @@ import Database from "better-sqlite3"; import type { Database as DatabaseType, Statement as DatabaseStatementType } from "better-sqlite3"; import { MeterRecord, TransactionRecord } from "../types"; import { createLogger } from "../utils/logger"; -import { initializeManagerStore } from '../m3ter/store'; const logger = createLogger("[sqlite]"); @@ -34,7 +33,6 @@ export default function setupDatabase(databaseName = "m3tering.db") { initializeTransactionsTable(); initializeMetersTable(); prepareQueries(); - initializeManagerStore(db); } export function deleteDatabase(databaseName = "m3tering.db") { diff --git a/src/views/index.hbs b/src/views/index.hbs index 0820b21..19defc5 100644 --- a/src/views/index.hbs +++ b/src/views/index.hbs @@ -12,7 +12,6 @@ - {{#each icons}} {{/each}} @@ -43,7 +42,6 @@

Draw with a mouse, pen, or finger. Your drawing stays open when switching apps.

Drawing requires canvas support.
- {{> m3ter-manager}} {{#each windows}} {{/each}} diff --git a/src/views/layouts/main.hbs b/src/views/layouts/main.hbs index 072fab6..a615212 100644 --- a/src/views/layouts/main.hbs +++ b/src/views/layouts/main.hbs @@ -12,7 +12,6 @@ - {{{body}}} @@ -25,10 +24,6 @@ - - - - diff --git a/src/views/partials/m3ter-manager.hbs b/src/views/partials/m3ter-manager.hbs deleted file mode 100644 index 2975178..0000000 --- a/src/views/partials/m3ter-manager.hbs +++ /dev/null @@ -1,56 +0,0 @@ - diff --git a/tests/fixtures/handle-message-baseline.txt b/tests/fixtures/handle-message-baseline.txt new file mode 100644 index 0000000..2044131 --- /dev/null +++ b/tests/fixtures/handle-message-baseline.txt @@ -0,0 +1,96 @@ +export async function handleMessage(blob: Buffer): Promise { + let devEui: string | undefined; + let lockedMeter: string | undefined; + let ownsDeviceLock = false; + let log = logger; + try { + void notifyHook('onMessageReceived', blob); + const message = JSON.parse(blob.toString()); + if (typeof message?.deviceInfo?.devEui !== 'string' || !message.deviceInfo.devEui) { + throw new Error('Message has no valid device EUI'); + } + devEui = message.deviceInfo.devEui; + log = createMeterLogger({ devEui }); + if (deviceLocks.has(devEui!)) { + void notifyHook('onMessageDropped', 'locked', devEui!); + return; + } + deviceLocks.add(devEui!); + ownsDeviceLock = true; + const transaction = uplinkPayload(message).bytes; + const decoded = decodePayload(transaction); + const payloadHadPublicKey = !!decoded.extensions.deviceId; + const publicKey = decoded.extensions.deviceId || getMeterByDevEui(devEui!)?.publicKey.replace(/^0x/, ''); + if (!publicKey || !verifyPayloadSignature(transaction, Buffer.from(publicKey, 'hex'))) { + throw new Error('Unknown meter or invalid transaction signature'); + } + const key = `0x${publicKey}`; + // Two device EUIs can identify the same meter. Serialize that identity too. + if (meterLocks.has(key)) { + void notifyHook('onMessageDropped', 'meter-locked', devEui!); + return; + } + meterLocks.add(key); + lockedMeter = key; + if (payloadHadPublicKey) { + const existing = getMeterByPublicKey(key); + if (!existing) { + const tokenId = await meterIdFromPublicKeyContractCall(key); + const latestNonce = await getLatestTransactionNonce(tokenId); + const meter = { publicKey: key, devEui: devEui!, tokenId, latestNonce }; + saveMeter(meter); + void notifyHook('onMeterCreated', meter); + } else { + if (existing.devEui !== devEui && !updateMeterDevEui(key, devEui!)) throw new Error('Could not update meter device EUI'); + const latestNonce = await getLatestTransactionNonce(existing.tokenId); + if (!updateMeterNonce(key, latestNonce)) throw new Error('Could not synchronize meter nonce'); + } + } + const meter = getMeterByPublicKey(key); + if (!meter) throw new Error('Meter not found'); + const expectedNonce = meter.latestNonce + 1; + let newTransaction = false; + if (decoded.nonce === expectedNonce) { + const record: TransactionRecord = { nonce: decoded.nonce, identifier: meter.tokenId, receivedAt: Date.now(), raw: transaction.toString('hex') }; + // Acknowledgement means both the transaction and its nonce are durable. + recordMeterTransaction(key, record); + newTransaction = true; + try { collectorAccepted(applicationId(), devEui!, decoded.nonce, transaction.readUInt32BE(4)); } + catch { log.warn('Manager collector observation unavailable; collection continues'); } + } else if (decoded.nonce !== 0) { + const previous = getTransactionByNonce(decoded.nonce, meter.tokenId); + if (decoded.nonce !== meter.latestNonce || !previous || decoded.energy < decodePayload(Buffer.from(previous.raw, 'hex')).energy) { + throw new Error(`Invalid nonce. Expected ${expectedNonce}, got ${decoded.nonce}`); + } + // A lost acknowledgment may leave the same signed accumulator increasing. + // Re-acknowledge the durable transaction; never store/bill it twice. + // Additional uncollected energy is not silently rewritten into that transaction. + } + let is_on = false; + try { is_on = await runHook('isOnStateCompute', meter.tokenId); } + catch (error) { + log.error('Could not determine meter power state:', error); + void notifyHook('onIsOnStateComputeError', meter.tokenId, error); + } + void notifyHook('onIsOnStateComputed', meter.tokenId, is_on); + const state = decoded.nonce === 0 ? { nonce: meter.latestNonce, is_on } : { is_on }; + try { + await enqueue(devEui!, encode(state as State, decoded.extensions.latitude ?? 0, decoded.extensions.longitude ?? 0)); + void notifyHook('onStateEnqueued', state, decoded.extensions.latitude ?? 0, decoded.extensions.longitude ?? 0); + } finally { + // Delivery services run after the downlink attempt and cannot prevent it. + // notifyHook isolates failures so later delivery extensions still run. + if (newTransaction) void notifyHook('onTransactionDistribution', meter.tokenId, decoded, getAllTransactionRecords()); + } + } catch (error) { + log.error('Error handling MQTT message:', error); + void notifyHook('onMessageError', error); + } finally { + if (lockedMeter) meterLocks.delete(lockedMeter); + if (ownsDeviceLock && devEui) { + deviceLocks.delete(devEui); + void notifyHook('onDeviceUnlocked', devEui); + } + void notifyHook('onMessageProcessingComplete'); + } +} diff --git a/tests/logic/electrical.test.ts b/tests/logic/electrical.test.ts index 776f857..c04e348 100644 --- a/tests/logic/electrical.test.ts +++ b/tests/logic/electrical.test.ts @@ -1,5 +1,5 @@ -import { decodeElectrical, electricalObject, trackElectrical } from '../../src/m3ter/electrical'; -import { decodeTelemetry } from '../../src/m3ter/decoder'; +import { decodeElectrical, electricalObject, trackElectrical } from '../../src/lib/protocol/electrical'; +import { decodeTelemetry } from '../../src/lib/protocol/decoder'; const frame = require('../fixtures/electrical.cjs'); const sample = (options = {}, timestamp = 100000) => ({ telemetry: decodeElectrical(frame(options)), timestamp, receivedAt: timestamp + 100, rawPayload: frame(options).toString('base64'), metadata: {} }); diff --git a/tests/logic/manager-commands.test.ts b/tests/logic/manager-commands.test.ts deleted file mode 100644 index 1c3a799..0000000 --- a/tests/logic/manager-commands.test.ts +++ /dev/null @@ -1,38 +0,0 @@ -import { commandCatalogue, generateCommand } from '../../src/m3ter/commands'; -test.each([ - ['relay-on', undefined, 'Gw==', 2, 1], ['relay-off', undefined, 'HA==', 2, 1], - ['billing-disconnect', undefined, 'AA==', 2, 1], ['billing-connect', undefined, 'AQ==', 2, 1], ['restart', undefined, 'HQ==', 2, 1], - ['report-interval', 60, 'AgA8', 2, 3], ['report-interval', 900, 'AgOE', 2, 3], - ['relay-drive', 1, 'HgE=', 2, 2], ['relay-drive', 0, 'HgA=', 2, 2], ['relay-fitted', 1, 'HwE=', 2, 2], ['relay-fitted', 0, 'HwA=', 2, 2], - ['current-gain', 1, 'IAE=', 2, 2], ['current-gain', 2, 'IAI=', 2, 2], ['current-gain', 4, 'IAQ=', 2, 2], - ['voltage-gain', 1, 'IQE=', 2, 2], ['voltage-gain', 2, 'IQI=', 2, 2], ['voltage-gain', 4, 'IQQ=', 2, 2], - ['phase-mode', 0, 'IgA=', 2, 2], ['phase-mode', 1, 'IgE=', 2, 2], ['phase-mode', 2, 'IgI=', 2, 2], ['phase-mode', 3, 'IgM=', 2, 2], - ['telemetry-enable', undefined, 'IwE=', 2, 2], ['telemetry-disable', undefined, 'IwA=', 2, 2], - ['telemetry-interval', 60, 'JAA8', 2, 3], ['telemetry-interval', 300, 'JAEs', 2, 3], ['telemetry-now', undefined, 'JQ==', 2, 1], - ['class-a', undefined, 'AA==', 3, 1], ['class-c', undefined, 'Ag==', 3, 1], -])('%s %s matches the firmware frame', (id, value, data, fPort, length) => { - expect(generateCommand(id, value)).toMatchObject({ data, fPort, length, confirmed: false }); -}); -test('catalogue has existing commands plus four telemetry actions and explicit safety controls', () => { - expect(commandCatalogue).toHaveLength(17); - for (const id of ['billing-connect','billing-disconnect','restart','relay-drive','relay-fitted','class-a']) expect(generateCommand(id, id === 'relay-drive' || id === 'relay-fitted' ? 1 : undefined).requiresConfirmation).toBe(true); - for (const id of ['class-b', 'calibrate', 'fuota', 200, null]) expect(() => generateCommand(id)).toThrow(); -}); -test('report intervals use exact unsigned big endian boundaries', () => { - expect(generateCommand('report-interval', 10).hex).toBe('02000A'); - expect(generateCommand('report-interval', 65535).hex).toBe('02FFFF'); - for (const value of [9,65536,-1,1.1,NaN,Infinity,'60',null,undefined]) expect(() => generateCommand('report-interval',value)).toThrow(); -}); -test('unsupported parameters are never encoded', () => { - for (const id of ['current-gain','voltage-gain']) for (const value of [0,3,8,256,'2']) expect(() => generateCommand(id,value)).toThrow(); - for (const value of [-1,4,200,'1']) expect(() => generateCommand('phase-mode',value)).toThrow(); - expect(() => generateCommand('relay-on',1)).toThrow(); -}); - -test('telemetry intervals are big endian and bounded; new commands cannot use monitoring or FUOTA ports', () => { - expect(generateCommand('telemetry-interval',10).hex).toBe('24000A'); - expect(generateCommand('telemetry-interval',65535).hex).toBe('24FFFF'); - for(const value of [9,65536,-1,1.1,NaN,Infinity,'60',null,undefined]) expect(()=>generateCommand('telemetry-interval',value)).toThrow(); - expect(generateCommand('telemetry-disable').requiresConfirmation).toBe(true); - expect(commandCatalogue.every(c=>c.fPort===2 || c.fPort===3)).toBe(true); -}); diff --git a/tests/logic/manager-decoder.test.ts b/tests/logic/report-decoder.test.ts similarity index 97% rename from tests/logic/manager-decoder.test.ts rename to tests/logic/report-decoder.test.ts index 3541ade..d06ecc9 100644 --- a/tests/logic/manager-decoder.test.ts +++ b/tests/logic/report-decoder.test.ts @@ -1,5 +1,5 @@ import { generateKeyPairSync, sign } from 'crypto'; -import { decodeTelemetry, reportObject } from '../../src/m3ter/decoder'; +import { decodeTelemetry, reportObject } from '../../src/lib/protocol/decoder'; import { decodePayload } from '../../src/lib/decode'; const keys = generateKeyPairSync('ed25519'); const publicKey = keys.publicKey.export({ format: 'der', type: 'spki' }).subarray(-32); diff --git a/tests/services/manager-auth.test.ts b/tests/services/manager-auth.test.ts deleted file mode 100644 index ff93d98..0000000 --- a/tests/services/manager-auth.test.ts +++ /dev/null @@ -1,44 +0,0 @@ -import { managerAuthRouter, managerAuthenticated, requireManagerAuth } from '../../src/m3ter/auth'; -const original = process.env; -let address = 0; -beforeEach(() => { process.env = { ...original, M3TER_MANAGER_USERNAME: 'operator', M3TER_MANAGER_PASSWORD: 'unique-password' }; address++; }); -afterEach(() => { process.env = original; jest.restoreAllMocks(); }); -function request(body?: any, cookie = ''): any { return { body, headers: { cookie }, socket: { remoteAddress: String(address) }, secure: false }; } -function response(): any { - const res:any = { code: 200, headers: {}, status(n:number) { this.code=n;return this; }, json(body:any) { this.body=body;return this; }, - cookie(name:string,value:string,options:any) { this.value=name+'='+value;this.options=options; }, setHeader(name:string,value:any) { this.headers[name]=value; } }; - return res; -} -function call(method:string, req:any) { - const res=response(), route=managerAuthRouter.stack.find((layer:any)=>layer.route?.path==='/session' && layer.route.methods[method]); - route.route.stack[0].handle(req,res,()=>{}); return res; -} -function login() { return call('post',request({username:'operator',password:'unique-password'})); } -test('missing configuration fails closed and credentials never enter the response', () => { - delete process.env.M3TER_MANAGER_PASSWORD; - expect(login().code).toBe(503); expect(call('get',request()).body).toMatchObject({authenticated:false,configured:false}); - const res=response(); requireManagerAuth(request(),res,jest.fn()); expect(res.code).toBe(401); -}); -test('login, HttpOnly cookie, revocation, expiry and credential rotation', () => { - const first=login(); expect(first.code).toBe(200); - expect(first.options).toMatchObject({httpOnly:true,sameSite:'strict',path:'/'}); - expect(JSON.stringify(first.body)).not.toContain('password'); - const req=request(undefined,first.value); expect(managerAuthenticated(req)).toBe(true); - call('delete',req); expect(managerAuthenticated(req)).toBe(false); - const next=login(), later=Date.now()+8*3600000+1; - jest.spyOn(Date,'now').mockReturnValue(later); expect(managerAuthenticated(request(undefined,next.value))).toBe(false); - jest.restoreAllMocks(); const third=login(); process.env.M3TER_MANAGER_PASSWORD='rotated'; - expect(managerAuthenticated(request(undefined,third.value))).toBe(false); -}); -test('generic errors, bounded attempts and secure proxy cookies', () => { - for(let i=0;i<10;i++) expect(call('post',request({username:'operator',password:'wrong'})).code).toBe(403); - const locked=login(); expect(locked.code).toBe(429); expect(locked.headers['Retry-After']).toBeGreaterThan(0); - address++; const req=request({username:'operator',password:'unique-password'}); req.headers.origin='https://console.example.com'; expect(call('post',req).options.secure).toBe(true); -}); -test('password-only configuration uses admin without returning either credential',()=>{ - delete process.env.M3TER_MANAGER_USERNAME; - const result=call('post',request({username:'admin',password:'unique-password'})); - expect(result.code).toBe(200); - const session=call('get',request(undefined,result.value)).body; - expect(session).toEqual({authenticated:true,configured:true}); -}); diff --git a/tests/services/manager-config.test.ts b/tests/services/manager-config.test.ts deleted file mode 100644 index 9dd6b64..0000000 --- a/tests/services/manager-config.test.ts +++ /dev/null @@ -1,11 +0,0 @@ -import { telemetryLimit } from '../../src/m3ter/config'; -const original = process.env; -beforeEach(() => { process.env = {...original}; delete process.env.M3TER_TELEMETRY_LIMIT; }); -afterEach(() => { process.env = original; }); -test('retention defaults to 100 and supports positive integers', () => { - expect(telemetryLimit()).toBe(100); - for (const limit of ['1','7','250','10000']) { process.env.M3TER_TELEMETRY_LIMIT=limit; expect(telemetryLimit()).toBe(Number(limit)); } -}); -test.each(['0','-1','2.5','no','', 'NaN', 'Infinity','100oops','9007199254740992'])('invalid limit %s safely falls back', value => { - process.env.M3TER_TELEMETRY_LIMIT=value; expect(telemetryLimit()).toBe(100); -}); diff --git a/tests/services/manager-removal.test.ts b/tests/services/manager-removal.test.ts new file mode 100644 index 0000000..4601777 --- /dev/null +++ b/tests/services/manager-removal.test.ts @@ -0,0 +1,32 @@ +import fs from 'fs'; +import os from 'os'; +import path from 'path'; +import Database from 'better-sqlite3'; +import { warnRemovedManagerSettings } from '../../src/lib/legacy-config'; +import setupDatabase, { deleteDatabase } from '../../src/store/sqlite'; + +test('obsolete credentials are ignored with one warning containing no values', () => { + const warn = jest.fn(); + warnRemovedManagerSettings({ M3TER_MANAGER_PASSWORD: 'must-not-appear', M3TER_MANAGER_USERNAME: 'secret-user', M3TER_TELEMETRY_LIMIT: '-1' }, warn); + expect(warn).toHaveBeenCalledTimes(1); + expect(warn.mock.calls[0][0]).toContain('ignored'); + expect(warn.mock.calls[0][0]).not.toMatch(/must-not-appear|secret-user|-1/); + warn.mockClear(); warnRemovedManagerSettings({}, warn); + expect(warn).not.toHaveBeenCalled(); +}); + +test('billing initialization leaves legacy Manager tables and records intact', () => { + const cwd = process.cwd(), directory = fs.mkdtempSync(path.join(os.tmpdir(), 'console-removal-')); + process.chdir(directory); + try { + fs.mkdirSync('.data'); + const previous = new Database('.data/test.db'); + previous.exec("CREATE TABLE manager_events (id INTEGER PRIMARY KEY, message TEXT); INSERT INTO manager_events VALUES (1, 'retained');"); + previous.close(); + setupDatabase('test.db'); + const inspection = new Database('.data/test.db', { readonly: true }); + expect(inspection.prepare('SELECT * FROM manager_events').all()).toEqual([{ id: 1, message: 'retained' }]); + inspection.close(); + deleteDatabase('test.db'); + } finally { process.chdir(cwd); fs.rmSync(directory, { recursive: true, force: true }); } +}); diff --git a/tests/services/mqtt.test.ts b/tests/services/mqtt.test.ts index ca59527..5fec5f7 100644 --- a/tests/services/mqtt.test.ts +++ b/tests/services/mqtt.test.ts @@ -20,7 +20,7 @@ function uplink(nonce = 1, device = 'device-a', energy = 1000000) { Buffer.from(key.slice(2), 'hex').copy(data, 74); return Buffer.from(JSON.stringify({ deviceInfo: { devEui: device }, data: data.toString('base64') })); } -beforeEach(() => { +function resetFixture() { jest.resetAllMocks(); meter = { publicKey: key, tokenId: 1, latestNonce: 0, devEui: 'device-a' }; records = []; (verifyPayloadSignature as jest.Mock).mockReturnValue(true); @@ -35,7 +35,8 @@ beforeEach(() => { (store.getAllTransactionRecords as jest.Mock).mockImplementation(() => records); (store.getTransactionByNonce as jest.Mock).mockImplementation(nonce => records.find(record => record.nonce === nonce)); (store.recordMeterTransaction as jest.Mock).mockImplementation((_, record) => { records.push(record); meter.latestNonce = record.nonce; }); -}); +} +beforeEach(resetFixture); test.each(['{', '{}', 'null', '{"deviceInfo":{}}', '{"deviceInfo":{"devEui":"device-a"}}'])('malformed uplink %s stays inside the error boundary', async input => { await expect(handleMessage(Buffer.from(input))).resolves.toBeUndefined(); @@ -95,6 +96,14 @@ test('persistence failure never acknowledges uncommitted data and releases the l await handleMessage(uplink()); expect(enqueue).toHaveBeenCalledTimes(1); }); +test('the injected transport receives the identical billing reply without contacting gRPC', async () => { + const sink = jest.fn().mockResolvedValue(undefined); + await handleMessage(uplink(), sink); + expect(sink).toHaveBeenCalledWith({ devEui: 'device-a', fPort: 2, confirmed: false, bytes: [1,0,0,0,0,0,0,0,0] }); + expect(enqueue).not.toHaveBeenCalled(); + expect(records).toHaveLength(1); +}); + test('collector decodes explicitly marked hex using the same bytes as the existing transport', async () => { const event=JSON.parse(uplink().toString()), hex=Buffer.from(event.data,'base64').toString('hex'); event.data=hex;event.dataEncoding='hex'; @@ -117,16 +126,16 @@ test('shared MQTT URL preserves the original default, supports remote protocols, } finally {process.env=environment;} }); -test('one broker connection fans out independently, preserves collection on monitoring failure, and resubscribes once', async () => { +test('one collector broker connection delivers reports and resubscribes once', async () => { const { EventEmitter } = require('events'); - const mqtt = require('mqtt'), monitor = require('../../src/m3ter/monitor'); + const mqtt = require('mqtt'); const { handleUplinks, stopUplinks } = require('../../src/services/mqtt'); const oldApp=process.env.APPLICATION_ID, oldHost=process.env.CHIRPSTACK_HOST; process.env.APPLICATION_ID='11111111-1111-4111-8111-111111111111'; process.env.CHIRPSTACK_HOST='existing-broker'; const client = new EventEmitter(); client.end=jest.fn(); client.stream={destroy:jest.fn()}; client.subscribe=jest.fn((topic:any,options:any,done:any)=>done(null,[{qos:1}])); mqtt.connect.mockReturnValue(client); - const collect=jest.fn().mockResolvedValue(undefined), observed=jest.spyOn(monitor,'ingestEvent').mockImplementation(()=>{throw new Error('database unavailable');}); + const collect=jest.fn().mockResolvedValue(undefined); try { await handleUplinks(undefined,collect);await handleUplinks(undefined,collect); expect(mqtt.connect).toHaveBeenCalledTimes(1); @@ -135,11 +144,43 @@ test('one broker connection fans out independently, preserves collection on moni client.emit('connect');client.emit('connect');expect(client.subscribe).toHaveBeenCalledTimes(2); const body=Buffer.from(JSON.stringify({deviceInfo:{devEui:'0102030405060708'},fPort:2,data:'AAAA'})); client.emit('message',`application/${process.env.APPLICATION_ID}/device/0102030405060708/event/up`,body); - await Promise.resolve();expect(collect).toHaveBeenCalledWith(body);expect(observed).toHaveBeenCalled(); - observed.mockImplementation(()=>true);collect.mockRejectedValueOnce(new Error('collector unavailable')); + await Promise.resolve();expect(collect).toHaveBeenCalledWith(body); + collect.mockRejectedValueOnce(new Error('collector unavailable')); client.emit('message',`application/${process.env.APPLICATION_ID}/device/0102030405060708/event/up`,body); - await Promise.resolve();await Promise.resolve();expect(observed).toHaveBeenCalledTimes(2); + await Promise.resolve();await Promise.resolve();expect(collect).toHaveBeenCalledTimes(2); client.emit('error',Object.assign(new Error('network'),{code:'ECONNRESET'}));expect(client.end).not.toHaveBeenCalled(); stopUplinks();await handleUplinks(undefined,collect);expect(mqtt.connect.mock.calls[1][0].clientId).not.toBe(clientId); - } finally { stopUplinks();observed.mockRestore();if(oldApp===undefined)delete process.env.APPLICATION_ID;else process.env.APPLICATION_ID=oldApp;if(oldHost===undefined)delete process.env.CHIRPSTACK_HOST;else process.env.CHIRPSTACK_HOST=oldHost; } + } finally { stopUplinks();if(oldApp===undefined)delete process.env.APPLICATION_ID;else process.env.APPLICATION_ID=oldApp;if(oldHost===undefined)delete process.env.CHIRPSTACK_HOST;else process.env.CHIRPSTACK_HOST=oldHost; } +}); + +// Execute the frozen baseline body against the same doubles, rather than deriving +// expected decisions from the new implementation. +test.each(['valid', 'invalid-signature', 'stale', 'bootstrap', 'duplicate', 'extension-error'])('billing is identical to baseline: %s', async scenario => { + const fs = require('node:fs'), vm = require('node:vm'), ts = require('typescript'); + const source = fs.readFileSync(require('node:path').join(__dirname, '../fixtures/handle-message-baseline.txt'), 'utf8'); + const exports = {}; + const quiet = { info: jest.fn(), warn: jest.fn(), error: jest.fn() }; + const context = { exports, Buffer, Date, Set, logger: quiet, createMeterLogger: () => quiet, + deviceLocks: new Set(), meterLocks: new Set(), ...store, + getLatestTransactionNonce, runHook, notifyHook, verifyPayloadSignature, enqueue, + encode: require('../../src/lib/encode').encode, + decodePayload: require('../../src/lib/decode').decodePayload, + uplinkPayload: require('../../src/lib/uplink-payload').uplinkPayload, + meterIdFromPublicKeyContractCall: require('../../src/utils/contracts').meterIdFromPublicKeyContractCall, + applicationId: () => 'fixture', collectorAccepted: () => undefined }; + vm.runInNewContext(ts.transpileModule(source, { compilerOptions: { module: ts.ModuleKind.CommonJS, target: ts.ScriptTarget.ES2020 } }).outputText, context); + const outputs = []; + for (const implementation of [context.exports.handleMessage, handleMessage]) { + resetFixture(); + if (scenario === 'invalid-signature') (verifyPayloadSignature as jest.Mock).mockReturnValue(false); + if (scenario === 'extension-error') (runHook as jest.Mock).mockRejectedValue(new Error('fixture extension failure')); + if (scenario === 'stale') meter.latestNonce = 8; + await implementation(uplink(scenario === 'bootstrap' ? 0 : 1)); + if (scenario === 'duplicate') await implementation(uplink(1, 'device-a', 2000000)); + outputs.push({ downlinks: (enqueue as jest.Mock).mock.calls.map(([device, bytes]) => [device, bytes]), + records: records.map(({receivedAt, ...record}) => record), latestNonce: meter.latestNonce, + distribution: (notifyHook as jest.Mock).mock.calls.filter(([hook]) => hook === 'onTransactionDistribution').length, + errors: (notifyHook as jest.Mock).mock.calls.filter(([hook]) => hook === 'onMessageError').length }); + } + expect(outputs[1]).toEqual(outputs[0]); }); diff --git a/tests/store/electrical.test.ts b/tests/store/electrical.test.ts deleted file mode 100644 index 6ec0dac..0000000 --- a/tests/store/electrical.test.ts +++ /dev/null @@ -1,87 +0,0 @@ -import { randomUUID } from 'crypto'; -import setupDatabase, { deleteDatabase } from '../../src/store/sqlite'; -import * as store from '../../src/m3ter/store'; -import { electricalHistory, electricalState, electricalSnapshot } from '../../src/m3ter/electrical-store'; -import { decodeElectrical } from '../../src/m3ter/electrical'; -import { ingestEvent } from '../../src/m3ter/monitor'; -const frame=require('../fixtures/electrical.cjs'); -const application='11111111-1111-4111-8111-111111111111', a='0102030405060708', b='1112131415161718'; -const env=process.env; -beforeEach(()=>{process.env={...env,APPLICATION_ID:application};delete process.env.M3TER_TELEMETRY_LIMIT;setupDatabase('electrical-test.db');}); -afterEach(()=>{deleteDatabase('electrical-test.db');process.env=env;jest.restoreAllMocks();}); -function event(options:any={}) { - return {deduplicationId:randomUUID(),time:new Date(Date.now()-1000).toISOString(),deviceInfo:{devEui:a,applicationId:application,deviceName:'Meter A'}, - fPort:4,fCnt:1,data:frame().toString('base64'),rxInfo:[{gatewayId:'gateway',rssi:-80,snr:8}],...options}; -} -const ingest=(e:any)=>ingestEvent(`application/${application}/device/${e.deviceInfo.devEui}/event/up`,Buffer.from(JSON.stringify(e))); -test('both ports coexist, retain raw metadata, and unsupported ports are ignored',()=>{ - const usage=Buffer.alloc(74);usage.writeUInt32BE(1500000,4);usage.writeUInt16BE(2300,72); - ingest(event({fPort:2,data:usage.toString('base64')}));const original=store.deviceState(application,a); - const e=event();expect(ingest(e)).toBe(true); - expect(store.latestReading(application,a)).toMatchObject({nonce:0,energy:1.5,voltage:230}); - expect(store.deviceState(application,a).lastUplink).toBe(original.lastUplink); - const row=electricalHistory(application,a).rows[0];expect(row).toMatchObject({timestamp:Date.parse(e.time),rawPayload:e.data,fPort:4,metadata:{fCnt:1,deduplicationId:e.deduplicationId,rssi:-80,snr:8,applicationId:application}}); - expect(electricalState(application,a)?.latest.telemetry.voltage.a).toBe(230.12); - for(const fPort of [3,5,200,201,202])expect(ingest(event({fPort}))).toBe(false); -}); -test('deduplicates identifiers, frame counters and replay after eviction without advancing receipt time',()=>{ - process.env.M3TER_TELEMETRY_LIMIT='1';setupDatabase('electrical-test.db'); - const first=event();ingest(first);expect(ingest(first)).toBe(false); - const second=event({deduplicationId:undefined,fCnt:2,time:new Date(Date.now()).toISOString()});ingest(second);expect(ingest({...second,rxInfo:[]})).toBe(false); - expect(ingest(first)).toBe(false);expect(electricalHistory(application,a).total).toBe(1); -}); -test('codec objects and raw Base64 fallback produce equivalent telemetry; invalid objects fall back safely',()=>{ - const t=decodeElectrical(frame());ingest(event({object:t})); - expect(electricalState(application,a)?.latest.metadata.decodedSource).toBe('ChirpStack object'); - ingest(event({deviceInfo:{devEui:b,applicationId:application},object:{type:'report'}})); - expect(electricalState(application,b)?.latest.telemetry).toEqual(t); - expect(electricalState(application,b)?.latest.metadata.decodedSource).toBe('raw payload'); - const later=new Date(Date.now()).toISOString();ingest(event({time:later,data:undefined,object:t})); - expect(electricalState(application,a)?.latest.rawPayload).toBeNull(); -}); -test('malformed version, length and missing time never replace valid monitoring state',()=>{ - ingest(event());const prior=electricalState(application,a)?.latest; - for(const data of [frame({version:2}).toString('base64'),Buffer.alloc(96).toString('base64'),'ABC!'])ingest(event({data})); - ingest(event({time:undefined}));expect(electricalState(application,a)?.latest).toEqual(prior); - expect(store.events(application,a).filter(e=>e.kind==='telemetry-error')).toHaveLength(4); -}); -test('separate global cap protects usage history and persistent baselines on restart and limit changes',()=>{ - process.env.M3TER_TELEMETRY_LIMIT='3';setupDatabase('electrical-test.db'); - const now=Date.now()-100000; - ingest(event({fPort:2,data:Buffer.alloc(74).toString('base64'),time:new Date(now).toISOString()})); - for(let i=0;i<6;i++)ingest(event({deviceInfo:{devEui:i%2?a:b,applicationId:application},fCnt:i,time:new Date(now+i*1000).toISOString(),data:frame({uptime:100+i,forward:100000+i*1000}).toString('base64')})); - expect(electricalHistory(application,a).total+electricalHistory(application,b).total).toBe(3); - expect(store.history(application,a,0,Date.now(),0,50).total).toBe(1); - expect(electricalState(application,a)?.totals.forward.total).toBe(.04); - process.env.M3TER_TELEMETRY_LIMIT='1';setupDatabase('electrical-test.db'); - expect(electricalHistory(application,a).total+electricalHistory(application,b).total).toBe(1); - ingest(event({time:new Date(now+6000).toISOString(),data:frame({uptime:106,forward:106000}).toString('base64')})); - expect(electricalState(application,a)?.totals.forward.total).toBe(.05); - expect(store.accumulatorState(application,a)?.nonce).toBe(0); -}); -test('default cap keeps newest 100 monitoring records globally including decode failures',()=>{ - const now=Date.now()-200000; - for(let i=0;i<102;i++)ingest(event({deviceInfo:{devEui:i%2?a:b,applicationId:application},time:new Date(now+i*1000).toISOString(),fCnt:i})); - expect(electricalHistory(application,a).total+electricalHistory(application,b).total).toBe(100); - ingest(event({data:Buffer.alloc(2).toString('base64')})); - expect(electricalHistory(application,a).total+electricalHistory(application,b).total).toBe(99); - setupDatabase('electrical-test.db');expect(electricalHistory(application,a).total+electricalHistory(application,b).total).toBe(99); -}); -test('restart allows re-used frame counters; delayed frames never replace latest state or inflate totals',()=>{ - const now=Date.now()-5000; - const first=event({deduplicationId:undefined,fCnt:0,time:new Date(now).toISOString(),data:frame({uptime:100}).toString('base64')});ingest(first); - ingest({...first,fCnt:1,time:new Date(now+1000).toISOString(),data:frame({uptime:101,forward:71368}).toString('base64')}); - ingest({...first,time:new Date(now+2000).toISOString(),data:frame({uptime:1,forward:0}).toString('base64')}); - expect(electricalState(application,a)).toMatchObject({session:1,totals:{forward:{total:.01}},tracking:{status:'restart'}}); - const latest=electricalState(application,a)?.latest; - ingest(event({time:new Date(now+500).toISOString(),data:frame({forward:9999999}).toString('base64')})); - expect(electricalState(application,a)?.latest).toEqual(latest);expect(electricalState(application,a)?.totals.forward.total).toBe(.01); -}); -test('freshness uses measurement time, estimates cadence, and never claims applied settings from queue acceptance',()=>{ - const now=Date.now()-1000;ingest(event({time:new Date(now).toISOString()})); - expect(electricalSnapshot(application,a,now+181000).freshness).toBe('stale'); - const id=randomUUID();store.insertCommand(application,a,id,{id:'telemetry-disable'},'disable');store.commandStatus(application,a,id,'queued','Accepted'); - expect(electricalSnapshot(application,a).status).toContain('application is unverified'); - for(let i=1;i<4;i++)ingest(event({time:new Date(now+i*60000).toISOString(),data:frame({uptime:86461+i*60}).toString('base64')})); - expect(electricalSnapshot(application,a)).toMatchObject({expectedInterval:60,intervalBasis:'observed estimate'}); -}); diff --git a/tests/store/manager.test.ts b/tests/store/manager.test.ts deleted file mode 100644 index 6eccf12..0000000 --- a/tests/store/manager.test.ts +++ /dev/null @@ -1,208 +0,0 @@ -import { randomUUID, generateKeyPairSync, sign } from 'crypto'; -import setupDatabase, { deleteDatabase, saveMeter } from '../../src/store/sqlite'; -import * as store from '../../src/m3ter/store'; -import { ingestEvent } from '../../src/m3ter/monitor'; -const app = '11111111-1111-4111-8111-111111111111', a = '0102030405060708', b = '1112131415161718'; -const originalEnv = process.env; -beforeEach(() => { process.env = { ...originalEnv, APPLICATION_ID: app }; delete process.env.M3TER_TELEMETRY_LIMIT; setupDatabase('manager-test.db'); }); -afterEach(() => { jest.restoreAllMocks(); deleteDatabase('manager-test.db'); process.env = originalEnv; }); -function event(devEui = a, energy = 1000000, time = Date.now(), id = randomUUID(), port = 2, length = 74, nonce = 0) { - const bytes = Buffer.alloc(length); if (length >= 74) { bytes.writeUInt32BE(nonce,0); bytes.writeUInt32BE(energy,4); bytes.writeUInt16BE(2300,72); } - const topic = `application/${app}/device/${devEui}/event/up`; - return { topic, body: { deduplicationId: id, time: new Date(time).toISOString(), deviceInfo: { devEui, applicationId: app }, fPort: port, data: bytes.toString('base64') } }; -} -const ingest = (e: ReturnType) => ingestEvent(e.topic, Buffer.from(JSON.stringify(e.body))); -test('routes multiple devices correctly and deduplicates events, not equal readings', () => { - const first = event(); expect(ingest(first)).toBe(true); expect(ingest(first)).toBe(false); - ingest(event(a)); ingest(event(b,2000000)); - expect(store.history(app,a,0,Date.now()+1000,0,50).total).toBe(2); - expect(store.latestReading(app,b).energy).toBe(2); - expect(store.history('another-application',a,0,Date.now()+1000,0,50).total).toBe(0); -}); -test('history survives reopening and timestamps/raw payload remain intact', () => { - const first = event(a,1234567,Date.now()-60000); ingest(first); setupDatabase('manager-test.db'); - const history = store.history(app,a,0,Date.now()+1000,0,50); - expect(history.rows[0]).toMatchObject({ timestamp: Date.parse(first.body.time), rawPayload:first.body.data, energy:1.234567, fPort:2 }); -}); -test('new nonce cycles count their own accumulator while repeats add zero', () => { - const time = Date.now()-10000; [1,2,.1,.3].forEach((energy,index) => ingest(event(a,energy*1000000,time+index*1000,randomUUID(),2,74,index<2?7:8))); - const result = store.history(app,a,0,Date.now(),0,50); - expect(result.summary).toMatchObject({ observedConsumption:2, resets:1 }); - expect(result.chart.map((row:any) => row.segment)).toEqual([0,0,1,1]); - expect(result.chart.map((row:any) => row.intervalEnergy)).toEqual([null,null,2,null]); -}); -test('malformed lengths, FPorts and identity mismatches do not create readings', () => { - ingest(event(a,1,Date.now(),randomUUID(),2,73)); ingest(event(a,1,Date.now(),randomUUID(),3)); - const mismatch = event(); mismatch.body.deviceInfo.devEui = b; expect(ingest(mismatch)).toBe(false); - expect(ingestEvent(event().topic,Buffer.from('{'))).toBe(false); - expect(store.latestReading(app,a)).toBeNull(); expect(store.latestReading(app,b)).toBeNull(); - expect(store.events(app,a).filter(row => row.kind === 'decode-error')).toHaveLength(1); -}); -test('delivery events correlate by device and queue ID, never by selected meter or transmission alone', () => { - const id = randomUUID(); store.insertCommand(app,a,id,{name:'Relay ON'},'fingerprint'); - const topic = `application/${app}/device/${a}/event/txack`; - const data:any = { deviceInfo:{devEui:a,applicationId:app}, queueItemId:id, time:new Date().toISOString() }; - ingestEvent(topic,Buffer.from(JSON.stringify(data))); - expect(store.getCommand(app,id).status).toBe('transmitted'); - store.commandStatus(app,a,id,'queued','Late HTTP response'); expect(store.getCommand(app,id).status).toBe('transmitted'); - data.deviceInfo.devEui = b; data.acknowledged = true; - ingestEvent(topic.replace(a,b).replace('txack','ack'),Buffer.from(JSON.stringify(data))); expect(store.getCommand(app,id).status).toBe('transmitted'); - data.deviceInfo.devEui = a; ingestEvent(topic.replace('txack','ack'),Buffer.from(JSON.stringify(data))); expect(store.getCommand(app,id).status).toBe('delivered'); -}); -test('pagination and sampled charts stay bounded and preserve reset segments', () => { - const start = Date.now()-1000000; - for (let index=0;index<901;index++) ingest(event(a,(index%450)*1000,start+index*1000,randomUUID(),2,74,Math.floor(index/450))); - const result = store.history(app,a,0,Date.now(),50,50); - expect(result.rows).toHaveLength(50); expect(result.total).toBe(100); expect(result.chart.length).toBeLessThanOrEqual(401); - expect((result.summary as any).resets).toBe(1); -}); -test('normal uplinks reuse an existing console key without requiring another bootstrap', () => { - const keys = generateKeyPairSync('ed25519'), key = keys.publicKey.export({format:'der',type:'spki'}).subarray(-32).toString('hex'); - saveMeter({devEui:a,publicKey:'0x'+key,tokenId:42,latestNonce:0}); - const input = event(), bytes = Buffer.from(input.body.data,'base64'); - sign(null,bytes.subarray(0,8),keys.privateKey).copy(bytes,8); input.body.data = bytes.toString('base64'); ingest(input); - expect(store.latestReading(app,a)).toMatchObject({verification:'verified',publicKey:null}); - expect(store.deviceState(app,a).publicKey).toBe(key); -}); -test('location comes from valid device events and older locations cannot overwrite newer ones', () => { - const publish = (latitude:number, timestamp:number) => ingestEvent(`application/${app}/device/${a}/event/location`,Buffer.from(JSON.stringify({ - time:new Date(timestamp).toISOString(),deduplicationId:randomUUID(),deviceInfo:{devEui:a,applicationId:app},location:{latitude,longitude:10}, - }))); - publish(91,Date.now()); expect(store.deviceState(app,a).metadata.location).toBeUndefined(); - publish(51,Date.now()); publish(21,Date.now()-10000); - expect(store.deviceState(app,a).metadata.location).toEqual({latitude:51,longitude:10}); -}); -test('activity follows actual reception; inactivity does not change the last receipt', () => { - ingest(event(a,1,Date.now()-600000)); expect(store.deviceState(app,a).activity).toBe('active'); - ingest(event()); expect(store.deviceState(app,a).activity).toBe('active'); - const last=store.deviceState(app,a).lastUplink; - store.markInactive(app,-1); expect(store.deviceState(app,a).activity).toBe('inactive'); - expect(store.deviceState(app,a).lastUplink).toBe(last); - expect(store.events(app,a).find(row=>row.kind==='inactive').source).toBe('console observation'); -}); - -test('receipt time survives refresh/restart and ignores duplicates, connection events, and invalid payloads', () => { - const now=Date.now(), clock=jest.spyOn(Date,'now').mockReturnValue(now); - const input=event(a,1000000,now+60000); ingest(input); - expect(store.deviceState(app,a).lastUplink).toBe(now); - clock.mockReturnValue(now+120000); - ingest(input); ingest(event(a,1,now+120000,randomUUID(),2,73)); - const monitor=require('../../src/m3ter/monitor'); monitor.connectionState('reconnecting'); store.markInactive(app,1); - expect(store.deviceState(app,a).lastUplink).toBe(now); - setupDatabase('manager-test.db'); expect(store.deviceState(app,a).lastUplink).toBe(now); - ingest(event(a,2000000,now-100000)); expect(store.deviceState(app,a).lastUplink).toBe(now+120000); -}); - -test('custom global retention is enforced on insertion and restart while nonce state survives', () => { - process.env.M3TER_TELEMETRY_LIMIT='3'; setupDatabase('manager-test.db'); - const now=Date.now()-10000; - ingest(event(a,2000000,now,randomUUID(),2,74,1)); store.collectorAccepted(app,a,1,1500000); - for(let i=1;i<=4;i++) ingest(event(b,i*100,now+i*1000)); - expect(store.history(app,a,0,Date.now(),0,100).total).toBe(0); - expect(store.history(app,b,0,Date.now(),0,100).rows.map((r:any)=>r.rawEnergy)).toEqual([400,300,200]); - process.env.M3TER_TELEMETRY_LIMIT='1'; setupDatabase('manager-test.db'); - expect(store.history(app,b,0,Date.now(),0,100)).toMatchObject({total:1,retentionLimit:1}); - ingest(event(a,100000,now+6000,randomUUID(),2,74,2)); - expect(store.history(app,a,0,Date.now(),0,100).summary).toMatchObject({observedConsumption:2,collectedEnergy:1.5}); - expect(store.history(app,b,0,Date.now(),0,100).total).toBe(0); - process.env.M3TER_TELEMETRY_LIMIT='0'; setupDatabase('manager-test.db'); - expect(store.history(app,a,0,Date.now(),0,100)).toMatchObject({total:1,retentionLimit:100}); -}); - -test('configured retention can exceed 100, retaining the newest source records across meters', () => { - process.env.M3TER_TELEMETRY_LIMIT='120'; setupDatabase('manager-test.db'); - const now=Date.now()-200000; - for(let i=0;i<125;i++) ingest(event(i%2?a:b,i*100,now+i*1000)); - const rows=[...store.history(app,a,0,Date.now(),0,100).rows,...store.history(app,b,0,Date.now(),0,100).rows] as any[]; - expect(rows).toHaveLength(120);expect(Math.min(...rows.map(r=>r.rawEnergy))).toBe(500); - setupDatabase('manager-test.db');expect(store.history(app,a,0,Date.now(),0,100).total+store.history(app,b,0,Date.now(),0,100).total).toBe(120); -}); - -test('receipt migration replaces old source clocks without touching readings', () => { - const now=Date.now(), clock=jest.spyOn(Date,'now').mockReturnValue(now); - ingest(event(a,1000000,now+60000)); - const Database=require('better-sqlite3'), connection=new Database('./.data/manager-test.db'); - connection.prepare('UPDATE manager_devices SET lastUplink=?').run(now+60000); - connection.exec('DELETE FROM manager_schema WHERE version=2');connection.close(); - clock.mockReturnValue(now+300000);setupDatabase('manager-test.db'); - expect(store.deviceState(app,a).lastUplink).toBe(now); - expect(store.latestReading(app,a).timestamp).toBe(now+60000); -}); - -test('hex telemetry decodes identically and raw transport survives persistence', () => { - const input:any=event(a,1234567); const hex=Buffer.from(input.body.data,'base64').toString('hex').toUpperCase(); - delete input.body.data; input.body.dataHex=hex; expect(ingest(input)).toBe(true); - expect(store.latestReading(app,a)).toMatchObject({energy:1.234567,voltage:230,nonce:0}); - const row:any=store.history(app,a,0,Date.now()+1000,0,50).rows[0]; - expect(row.rawPayload).toBe(hex); expect(JSON.parse(row.metadata)).toMatchObject({payloadHex:hex,payloadEncoding:'hex',payloadField:'dataHex'}); - setupDatabase('manager-test.db'); expect(store.latestReading(app,a).energy).toBe(1.234567); - input.body.deduplicationId=randomUUID();input.body.dataHex='00GG';ingest(input); - expect(store.events(app,a).find(r=>r.rawPayload==='00GG').message).toContain('Invalid hex'); -}); - -test('acknowledgment cycles, high-water marks and range boundaries prevent double counting', () => { - const time = Date.now()-20000; - const reports = [[10,5],[10,6],[10,6],[11,8],[10,9],[11,7],[11,8],[11,9]]; - reports.forEach(([nonce,energy],index)=>ingest(event(a,energy*1e6,time+index*1000,randomUUID(),2,74,nonce))); - const full = store.history(app,a,0,Date.now(),0,50); - expect(full.chart.map((row:any)=>row.intervalEnergy)).toEqual([null,null,null,6,null,null,null,null]); - expect(full.summary).toMatchObject({observedConsumption:6,resets:1,repeatedReports:1,uncertainReports:2}); - const ranged = store.history(app,a,time+2000,Date.now(),0,2); - expect(ranged.summary.observedConsumption).toBe(6); // baseline comes from before the range - expect(ranged.rows).toHaveLength(2); - // A delayed report sorts into its source time and cannot create duplicate energy. - ingest(event(a,5500000,time+500,randomUUID(),2,74,10)); - expect(store.history(app,a,0,Date.now(),0,50).summary.observedConsumption).toBe(6); -}); -test('unexplained same-nonce decreases and nonce rollback are not fresh consumption', () => { - const time=Date.now()-10000; - [[8,2],[8,1],[8,2],[0,3],[1,4]].forEach(([nonce,energy],index)=>ingest(event(a,energy*1e6,time+index*1000,randomUUID(),2,74,nonce))); - expect(store.history(app,a,0,Date.now(),0,50).summary).toMatchObject({observedConsumption:0,resets:0,uncertainReports:3}); -}); - -test('nonce zero snapshots remain pending; only advance closes the previous observed cycle', () => { - const time=Date.now()-10000; - [1,1.5,2].forEach((energy,i)=>ingest(event(a,energy*1e6,time+i*1000))); - expect(store.history(app,a,0,Date.now(),0,100).summary.observedConsumption).toBe(0); - expect(store.accumulatorState(app,a)).toMatchObject({nonce:0,highWater:2000000}); - setupDatabase('manager-test.db'); - ingest(event(a,100000,time+4000,randomUUID(),2,74,1)); - expect(store.history(app,a,0,Date.now(),0,100).summary).toMatchObject({observedConsumption:2,collectedEnergy:0}); -}); -test('100 telemetry records globally, persistent state and collector evidence survive eviction', () => { - const time=Date.now()-1000000; - ingest(event(a,2000000,time,randomUUID(),2,74,1)); - store.collectorAccepted(app,a,1,1500000); - const commandId=randomUUID();store.insertCommand(app,a,commandId,{name:'Relay ON'},'preserve-history'); - store.applicationEvent(app,a,'command-queued','Preserve this command activity'); - for(let i=1;i<101;i++) ingest(event(b,i*100,time+i*1000)); - expect(store.history(app,a,0,Date.now(),0,100).total).toBe(0); - expect(store.history(app,b,0,Date.now(),0,100).total).toBe(100); - expect(store.latestReading(app,a).energy).toBe(2); - expect(store.getCommand(app,commandId)).toMatchObject({fingerprint:'preserve-history',actor:'manager operator'}); - expect(store.events(app,a).some(row=>row.message==='Preserve this command activity')).toBe(true); - setupDatabase('manager-test.db'); - ingest(event(a,100000,time+102000,randomUUID(),2,74,2)); - expect(store.history(app,a,0,Date.now(),0,100).summary).toMatchObject({observedConsumption:2,collectedEnergy:1.5}); - expect(store.history(app,b,0,Date.now(),0,100).total).toBe(99); - const delayed=event(a,9000000,time+500,randomUUID(),2,74,1);ingest(delayed);ingest(delayed); - expect(store.accumulatorState(app,a)).toMatchObject({nonce:2,highWater:100000,completedObserved:2}); - expect(store.history(app,a,0,Date.now(),0,100).total+store.history(app,b,0,Date.now(),0,100).total).toBe(100); -}); - -test('startup migration trims legacy rows, reconstructs cycle state and preserves Console tables',()=>{ - const Database=require('better-sqlite3');const connection=new Database('./.data/manager-test.db'); - const time=Date.now()-200000; - connection.prepare('INSERT INTO meters(publicKey,devEui,tokenId,latestNonce) VALUES(?,?,?,?)').run('preserve-console',b,7,4); - for(let i=0;i<120;i++){ - const id=connection.prepare(`INSERT INTO manager_events(application,devEui,timestamp,receivedAt,kind,source,eventKey,rawPayload,fPort,metadata,message) VALUES(?,?,?,?,?,?,?,?,?,?,?)`).run(app,a,time+i*1000,time+i*1000,'up','ChirpStack','legacy-'+i,'AAAA',2,'{}','legacy').lastInsertRowid; - connection.prepare(`INSERT INTO manager_readings(id,application,devEui,timestamp,receivedAt,fPort,nonce,rawEnergy,energy,rawVoltage,voltage,signature,verification,decoded) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?)`).run(id,app,a,time+i*1000,time+i*1000,2,0,i*1000,i/1000,2300,230,'','unverified','{}'); - } - connection.exec('DELETE FROM manager_schema; DELETE FROM manager_accumulators;');connection.close(); - setupDatabase('manager-test.db'); - expect(store.history(app,a,0,Date.now(),0,100).total).toBe(100); - expect(store.accumulatorState(app,a)).toMatchObject({nonce:0,highWater:119000,completedObserved:0}); - const check=new Database('./.data/manager-test.db'); - expect(check.prepare('SELECT COUNT(*) AS n FROM manager_events WHERE kind=\'up\'').get().n).toBe(100); - expect(check.prepare('SELECT latestNonce FROM meters WHERE publicKey=?').get('preserve-console').latestNonce).toBe(4);check.close(); -}); diff --git a/tests/ui/auth.spec.cjs b/tests/ui/auth.spec.cjs index 5debf3d..df0fa67 100644 --- a/tests/ui/auth.spec.cjs +++ b/tests/ui/auth.spec.cjs @@ -2,11 +2,11 @@ const { test, expect } = require('@playwright/test'); const base = 'http://127.0.0.1:4174'; const credentials = { username: 'test-console', password: 'test-only-browser-password' }; -test('Console and its assets are public; only Manager data is protected', async ({ browser, request }) => { - for (const route of ['/', '/healthz', '/js/desktop.js', '/vendor/xterm/xterm.js', '/api/m3ter-manager/session']) { +test('Local Console assets are public and removed Manager routes are absent', async ({ browser, request }) => { + for (const route of ['/', '/healthz', '/js/desktop.js', '/vendor/xterm/xterm.js']) { expect((await request.get(base + route)).status()).toBe(200); } - expect((await request.get(base + '/api/m3ter-manager/devices')).status()).toBe(401); + for (const route of ['/session', '/devices']) expect((await request.get(base + '/api/m3ter-manager' + route)).status()).toBe(404); const context = await browser.newContext({ httpCredentials: credentials }); expect((await context.request.get(base + '/js/desktop.js')).status()).toBe(200); expect((await context.request.post(base + '/api/actions/streamr/publish-now', { headers: { origin: 'https://foreign.example' } })).status()).toBe(403); diff --git a/tests/ui/browser.spec.cjs b/tests/ui/browser.spec.cjs index 827e66a..ccc7039 100644 --- a/tests/ui/browser.spec.cjs +++ b/tests/ui/browser.spec.cjs @@ -19,13 +19,8 @@ test('Google query is encoded in a top-level search; direct addresses still open await expect(page.locator('#browser iframe')).toHaveAttribute('src','http://127.0.0.1:4173/browser-home.html'); }); -test('only M3ter Manager remains in launcher and window naming', async ({page}) => { +test('removed Manager is absent from desktop, launcher and window registry', async ({page}) => { await page.route(/https:\/\//,route=>route.abort()); await page.goto('/'); - await expect(page.locator('[data-app-id="m3ters"], [data-app-id="metas"], #m3ters')).toHaveCount(0); - await expect(page.locator('#m3ter-manager-icon')).toHaveText('M3ter Manager'); - await expect(page.locator('.launcher-app[data-app-id="m3ter-manager"]')).toHaveText('M3ter Manager'); - await page.evaluate(()=>Desktop.launch('m3ter-manager')); - await expect(page.locator('#m3ter-manager .window-title')).toHaveText('M3ter Manager'); - await expect(page).toHaveTitle('M3ter Manager · M3tering Console'); - expect(await page.locator('body').textContent()).not.toContain('M3TER Manager'); + await expect(page.locator('[data-app-id="m3ters"], [data-app-id="metas"], [data-app-id="m3ter-manager"], #m3ter-manager')).toHaveCount(0); + await expect(page).toHaveTitle('M3tering Console · Desktop'); }); diff --git a/tests/ui/desktop.spec.cjs b/tests/ui/desktop.spec.cjs index fdd4821..c987e56 100644 --- a/tests/ui/desktop.spec.cjs +++ b/tests/ui/desktop.spec.cjs @@ -279,16 +279,16 @@ test('desktop visual references and large/small icon layouts remain usable', asy }); test('icon selection clears outside the desktop and applications retain independent color modes', async ({page})=>{ - await page.goto('/');await page.locator('[data-app-id="m3ter-manager"].desktop-icon').click(); - await page.locator('#m3ter-manager .window-titlebar').click();await expect(page.locator('.desktop-icon.selected')).toHaveCount(0); - await page.locator('#m3ter-manager .window-color-mode').selectOption('dark'); + await page.goto('/');await page.locator('[data-app-id="paint"].desktop-icon').click(); + await page.locator('#paint .window-titlebar').click();await expect(page.locator('.desktop-icon.selected')).toHaveCount(0); + await page.locator('#paint .window-color-mode').selectOption('dark'); await openSettings(page);await page.locator('#settings .window-color-mode').selectOption('light'); await page.locator('[data-theme-choice="linux"]').click(); - await expect(page.locator('#m3ter-manager')).toHaveAttribute('data-color-mode','dark');await expect(page.locator('#settings')).toHaveAttribute('data-color-mode','light'); + await expect(page.locator('#paint')).toHaveAttribute('data-color-mode','dark');await expect(page.locator('#settings')).toHaveAttribute('data-color-mode','light'); expect(await page.locator('#settings').evaluate(el=>getComputedStyle(el).colorScheme)).toBe('light'); - expect(await page.locator('#m3ter-manager').evaluate(el=>getComputedStyle(el).colorScheme)).toBe('dark'); - await page.reload();await page.evaluate(()=>{Desktop.launch('m3ter-manager');Desktop.launch('settings');}); - await expect(page.locator('#m3ter-manager')).toHaveAttribute('data-color-mode','dark');await expect(page.locator('#settings')).toHaveAttribute('data-color-mode','light'); + expect(await page.locator('#paint').evaluate(el=>getComputedStyle(el).colorScheme)).toBe('dark'); + await page.reload();await page.evaluate(()=>{Desktop.launch('paint');Desktop.launch('settings');}); + await expect(page.locator('#paint')).toHaveAttribute('data-color-mode','dark');await expect(page.locator('#settings')).toHaveAttribute('data-color-mode','light'); await page.locator('#settings .window-color-mode').selectOption('theme'); expect(await page.locator('#settings').evaluate(el=>getComputedStyle(el).colorScheme)).toBe('dark'); for(const width of [320,390,768,1440]) { diff --git a/tests/ui/electrical.spec.cjs b/tests/ui/electrical.spec.cjs deleted file mode 100644 index bb441c3..0000000 --- a/tests/ui/electrical.spec.cjs +++ /dev/null @@ -1,77 +0,0 @@ -const {test,expect}=require('@playwright/test'); -const {randomUUID}=require('node:crypto'); -test.use({baseURL:'http://127.0.0.1:4174'}); -const api='/api/m3ter-manager', a='0102030405060708', b='1112131415161718', empty='2122232425262728'; -test.beforeEach(async({page,request})=>{ - await page.route(/https:\/\//,route=>route.abort()); - await request.post(api+'/session',{data:{username:'test-manager',password:'test-only-manager-password'}}); -}); -async function open(page) { - await page.goto('/');await page.evaluate(()=>Desktop.launch('m3ter-manager')); - await page.locator('#mm-username').fill('test-manager');await page.locator('#mm-password').fill('test-only-manager-password');await page.locator('#mm-login-submit').click(); - await expect(page.locator('#mm-device option')).toHaveCount(4);await page.locator('#mm-device').selectOption(a); - await expect(page.locator('#mm-selected')).toHaveAttribute('aria-busy','false'); -} -const publish=(request,data)=>request.post('/__test/manager',{data}); -test('FPort 4 live readings stay separate from usage and collector; objects and raw data both work',async({page,request})=>{ - await open(page); - const usage=await page.locator('#mm-energy').textContent(), nonce=await page.locator('#mm-nonce').textContent(); - const before=(await(await publish(request,{action:'stats'})).json()).collectorCount; - await page.locator('[data-mm-tab="live"]').click();await expect(page.locator('#mm-electrical-empty')).toBeVisible(); - await publish(request,{fPort:4,devEui:a,forward:125000}); - await expect(page.locator('#mm-electrical-data')).toBeVisible();await expect(page.locator('#mm-electrical-main')).toContainText('400.4'); - await expect(page.locator('[data-phase="a"]')).toContainText('230.12 V');await expect(page.locator('[data-phase="a"]')).toContainText('-100.1 W'); - await expect(page.locator('#mm-electrical-main')).toContainText('-12'); - await expect(page.locator('#mm-electrical-energy')).toContainText('1.25000 kWh'); - await expect(page.locator('#mm-electrical-status')).toContainText('Closed (reported)'); - expect((await(await publish(request,{action:'stats'})).json()).collectorCount).toBe(before); - await publish(request,{fPort:4,devEui:b,power:-2000,object:true}); - await expect(page.locator('#mm-electrical-main')).toContainText('400.4'); - await page.locator('#mm-device').selectOption(b);await expect(page.locator('#mm-electrical-main')).toContainText('-200.0'); - const result=await(await request.get(`${api}/devices/${b}/telemetry`)).json();expect(result.rows[0].metadata.decodedSource).toBe('ChirpStack object'); - await page.locator('#mm-device').selectOption(a);await page.locator('[data-mm-tab="overview"]').click(); - await expect(page.locator('#mm-energy')).toHaveText(usage);await expect(page.locator('#mm-nonce')).toHaveText(nonce); - await page.locator('[data-mm-tab="live"]').click(); - const latest=(await(await request.get(`${api}/devices/${a}/telemetry`)).json()).state.latest; - await page.clock.setFixedTime(latest.timestamp+181000);await expect(page.locator('#mm-telemetry-freshness')).toContainText('Stale'); - await expect(page.locator('#mm-mqtt')).toHaveText('MQTT connected'); - await page.clock.setFixedTime(Date.now());await page.reload();await page.evaluate(()=>Desktop.launch('m3ter-manager')); - await page.locator('[data-mm-tab="live"]').click();await expect(page.locator('#mm-electrical-energy')).toContainText('1.25000 kWh'); - await page.locator('#mm-device').selectOption(empty);await expect(page.locator('#mm-electrical-empty')).toBeVisible(); - await expect(page.locator('#mm-electrical-data')).toBeHidden(); -}); -test('new command previews and queue requests use exact bytes, selected meter, and safe pending status',async({page,request})=>{ - await open(page);await page.locator('[data-mm-tab="commands"]').click(); - for(const [id,payload] of [['telemetry-enable','IwE='],['telemetry-disable','IwA='],['telemetry-now','JQ==']]) { - await page.locator(`[data-command-id="${id}"]`).click();await expect(page.locator('#mm-dialog-content')).toContainText(`Base64: ${payload}`); - await expect(page.locator('#mm-dialog-content')).toContainText('FPort 2');await expect(page.locator('#mm-dialog-content')).toContainText(a); - if(id==='telemetry-disable'){await expect(page.locator('#mm-submit')).toBeDisabled();await page.locator('#mm-confirm').check();} - await page.locator('#mm-submit').click();await expect(page.locator('#mm-notice')).toContainText('queued'); - } - await page.getByLabel('Telemetry interval presets').selectOption('300');await page.locator('[data-command-id="telemetry-interval"]').click(); - await expect(page.locator('#mm-dialog-content')).toContainText('JAEs');await expect(page.locator('#mm-dialog-content')).toContainText('300 seconds');await page.locator('#mm-submit').click(); - await expect(page.locator('#mm-telemetry-command-status')).toContainText('application unverified'); - const queue=(await(await request.get(`${api}/devices/${a}/queue`)).json()).items; - for(const data of ['IwE=','IwA=','JQ==','JAEs'])expect(queue).toContainEqual(expect.objectContaining({fPort:2,data,confirmed:false})); - const history=(await(await request.get(`${api}/devices/${a}/commands`)).json()).commands; - expect(history.filter(r=>r.command.id.startsWith('telemetry-'))).toHaveLength(4); - expect(history.filter(r=>r.command.id.startsWith('telemetry-')).every(r=>r.devEui===a && r.status==='queued')).toBe(true); - for(const body of [{commandId:'telemetry-interval',value:9},{commandId:'telemetry-interval',value:65536},{commandId:'telemetry-enable',fPort:4},{commandId:'telemetry-disable'}]) - expect((await request.post(`${api}/devices/${a}/commands`,{data:{requestId:randomUUID(),...body}})).status()).toBe(400); - await page.getByLabel('Telemetry interval presets').selectOption('10');await page.locator('[data-command-id="telemetry-interval"]').click(); - await expect(page.locator('#mm-dialog-content')).toContainText('LoRaWAN airtime'); -}); -test('electrical monitoring fits each desktop theme and mobile width',async({page,request})=>{ - await open(page);await publish(request,{fPort:4,devEui:a});await page.locator('[data-mm-tab="live"]').click(); - await expect(page.locator('#mm-electrical-data')).toBeVisible(); - const errors=[];page.on('pageerror',e=>errors.push(e.message)); - for(const width of [1440,768,390,320]) { - await page.setViewportSize({width,height:900}); - for(const theme of ['retro','macos','linux','windows']) { - await page.evaluate(()=>Desktop.launch('settings'));await page.locator(`[data-theme-choice="${theme}"]`).click();await page.evaluate(()=>Desktop.launch('m3ter-manager')); - expect(await page.locator('.mm-scroll').evaluate(e=>e.scrollWidth<=e.clientWidth+1)).toBe(true); - await expect(page.locator('[data-phase="a"]')).toContainText('230.12 V'); - } - } - expect(errors).toEqual([]); -}); diff --git a/tests/ui/manager-auth.spec.cjs b/tests/ui/manager-auth.spec.cjs deleted file mode 100644 index bb5c948..0000000 --- a/tests/ui/manager-auth.spec.cjs +++ /dev/null @@ -1,25 +0,0 @@ -const {test,expect}=require('@playwright/test'); -const base='http://127.0.0.1:4174',api='/api/m3ter-manager'; -test.use({baseURL:base}); -test('manager login protects data and live stream; logout revokes every open app session',async({page,context})=>{ - await page.route(/https:\/\//,route=>route.abort()); - for(const path of ['/config','/devices','/devices/0102030405060708/history','/devices/0102030405060708/queue']) expect((await context.request.get(api+path)).status()).toBe(401); - expect((await context.request.post(api+'/commands/preview',{data:{commandId:'relay-on'}})).status()).toBe(401); - await page.goto('/'); await page.evaluate(()=>Desktop.launch('m3ter-manager')); - await expect(page.locator('#mm-login')).toBeVisible(); await expect(page.locator('#mm-workspace')).toBeHidden(); - const anonymousStream=await page.evaluate(()=>new Promise(resolve=>{let opened=false;const ws=new WebSocket('ws://127.0.0.1:4174/m3ter-manager/live');ws.onopen=()=>{opened=true;ws.close();};ws.onclose=()=>resolve(opened);})); - expect(anonymousStream).toBe(false); - await page.locator('#mm-username').fill('test-manager');await page.locator('#mm-password').fill('wrong');await page.locator('#mm-login-submit').click(); - await expect(page.locator('#mm-login-error')).toHaveText('Incorrect username or password.'); - await page.locator('#mm-password').fill('test-only-manager-password');await page.locator('#mm-login-submit').click(); - await expect(page.locator('#mm-workspace')).toBeVisible();await expect(page.locator('#mm-feed')).toHaveText('Live feed connected'); - expect((await context.request.get(api+'/devices')).status()).toBe(200); - expect(await page.evaluate(()=>document.cookie)).not.toContain('m3ter_manager_session'); - const cookies=await context.cookies();expect(cookies.find(c=>c.name==='m3ter_manager_session')).toMatchObject({httpOnly:true,sameSite:'Strict'}); - await page.reload();await page.evaluate(()=>Desktop.launch('m3ter-manager'));await expect(page.locator('#mm-workspace')).toBeVisible(); - const second=await context.newPage();await second.route(/https:\/\//,route=>route.abort());await second.goto('/');await second.evaluate(()=>Desktop.launch('m3ter-manager')); - await expect(second.locator('#mm-feed')).toHaveText('Live feed connected'); - await page.locator('#mm-logout').click();await expect(page.locator('#mm-login')).toBeVisible(); - await expect(second.locator('#mm-login')).toBeVisible();expect((await context.request.get(api+'/devices')).status()).toBe(401); - expect(await page.evaluate(()=>JSON.stringify(localStorage))).not.toContain('test-only-manager-password'); -}); diff --git a/tests/ui/manager-fixture.cjs b/tests/ui/manager-fixture.cjs deleted file mode 100644 index ffdf606..0000000 --- a/tests/ui/manager-fixture.cjs +++ /dev/null @@ -1,100 +0,0 @@ -// Test infrastructure only: an HTTP ChirpStack REST stub and a real TCP MQTT broker. -const http = require('node:http'); -const net = require('node:net'); -const { randomUUID, generateKeyPairSync, sign } = require('node:crypto'); -const mqttPacket = require('mqtt-packet'); -const application = '11111111-1111-4111-8111-111111111111'; -const devices = [ - { devEui: '0102030405060708', name: 'Cumulus · Workshop' }, - { devEui: '1112131415161718', name: 'Cumulus · Solar room' }, - { devEui: '2122232425262728', name: 'Cumulus · Awaiting installation' }, -]; -module.exports = async function managerFixture(app) { - process.env.APPLICATION_ID = application; - process.env.API_TOKEN = 'fixture-backend-token-never-in-browser'; - const { ingestEvent } = require('../../dist/m3ter/monitor'); - const keys = new Map(devices.map(device => [device.devEui, generateKeyPairSync('ed25519')])); - const queues = new Map(devices.map(device => [device.devEui, []])); - let collectorCount = 0; - let enqueueCount = 0, listFailure = false, queueFailure = false; - const rest = http.createServer((req, res) => { - res.setHeader('Content-Type', 'application/json'); - const reply = (data, status = 200) => { res.statusCode = status; res.end(JSON.stringify(data)); }; - if (req.headers.authorization !== `Bearer ${process.env.API_TOKEN}`) { reply({error:'Unauthorized'},401); return; } - const url = new URL(req.url,'http://fixture'); - if (url.pathname === '/api/devices') { - if (listFailure) { reply({error:'Unavailable'},503); return; } - const search = (url.searchParams.get('search') || '').toLowerCase(); - const matches = devices.filter(device => (device.name + device.devEui).toLowerCase().includes(search)); - reply({ totalCount:matches.length, result:matches.map(device => ({...device,deviceProfileName:'Switch Cumulus',deviceProfileId:'profile-1'})) }); return; - } - if (url.pathname.startsWith('/api/device-profiles/')) { reply({deviceProfile:{name:'Switch Cumulus'}}); return; } - if (url.pathname.startsWith('/api/applications/')) { reply({application:{name:'Workshop network'}}); return; } - const match = url.pathname.match(/^\/api\/devices\/([a-f0-9]{16})(\/queue)?$/); - if (!match) { reply({},404); return; } - const id = match[1], device = devices.find(device => device.devEui === id); - if (!device) { reply({device:{devEui:id,applicationId:'22222222-2222-4222-8222-222222222222'} }); return; } - if (!match[2]) { reply({device:{...device,applicationId:application,deviceProfileId:'profile-1',tags:{phaseMode:'phase-a'},variables:{private:'must-not-leak'}},enabledClass:'CLASS_C'}); return; } - if (queueFailure) { reply({error:'upstream failure'},503); return; } - if (req.method === 'GET') { reply({totalCount:queues.get(id).length,result:queues.get(id)}); return; } - if (req.method === 'DELETE') { queues.set(id,[]); reply({}); return; } - let data = ''; req.on('data', chunk => data += chunk); req.on('end', () => { - const { queueItem } = JSON.parse(data); enqueueCount++; queues.get(id).push({...queueItem,isPending:true}); reply({id:queueItem.id}); - }); - }); - await new Promise(resolve => rest.listen(0,'127.0.0.1',resolve)); - process.env.CHIRPSTACK_REST_URL = `http://127.0.0.1:${rest.address().port}`; - const clients = new Set(); - const broker = net.createServer(socket => { - const parser = mqttPacket.parser(); socket.on('data', data => parser.parse(data)); socket.on('error',()=>{}); - socket.on('close',()=>clients.delete(socket)); parser.on('error',()=>socket.destroy()); - const send = packet => socket.write(mqttPacket.generate(packet)); - parser.on('packet', packet => { - if (packet.cmd === 'connect') send({cmd:'connack',returnCode:0,sessionPresent:false}); - if (packet.cmd === 'subscribe') { clients.add(socket); send({cmd:'suback',messageId:packet.messageId,granted:packet.subscriptions.map(()=>1)}); } - if (packet.cmd === 'pingreq') send({cmd:'pingresp'}); - if (packet.cmd === 'disconnect') socket.end(); - }); - }); - await new Promise(resolve => broker.listen(0,'127.0.0.1',resolve)); - const { handleUplinks, stopUplinks } = require('../../dist/services/mqtt'); - process.env.MQTT_URL = `mqtt://127.0.0.1:${broker.address().port}`; - await handleUplinks(undefined, async () => { collectorCount++; }); - function uplink(input = {}) { - const id = input.devEui || devices[0].devEui, key = keys.get(id); - if (input.fPort === 4) { - const bytes = require('../fixtures/electrical.cjs')(input); - return {deduplicationId:input.eventId || randomUUID(),time:new Date(input.timestamp || Date.now()).toISOString(), - deviceInfo:{devEui:id,applicationId:application,deviceName:devices.find(d=>d.devEui===id).name}, - data:bytes.toString('base64'),fPort:4,fCnt:input.fCnt ?? 1, - ...(input.object ? {object:require('../../dist/m3ter/electrical').decodeElectrical(bytes)} : {}),rxInfo:[{rssi:-70,snr:9.5,gatewayId:'aabbccddeeff0011'}]}; - } - const bytes = Buffer.alloc(input.length || ((input.nonce ?? 0) === 0 ? 106 : 74)); if (bytes.length >= 74) { - bytes.writeUInt32BE(input.nonce ?? 0,0); bytes.writeUInt32BE(Math.round((input.energy ?? 12.345678)*1e6),4); - sign(null,bytes.subarray(0,8),key.privateKey).copy(bytes,8); bytes.writeUInt16BE(Math.round((input.voltage ?? 230.1)*10),72); - if (bytes.length === 106) key.publicKey.export({format:'der',type:'spki'}).subarray(-32).copy(bytes,74); - } - return { deduplicationId:input.eventId || randomUUID(), time:new Date(input.timestamp || Date.now()).toISOString(), - deviceInfo:{ devEui:id, applicationId:application, deviceName:devices.find(d=>d.devEui===id).name, applicationName:'Workshop network',deviceProfileName:'Switch Cumulus' }, - ...(input.encoding === 'hex' ? {data:bytes.toString('hex').toUpperCase(),dataEncoding:'hex'} : input.encoding === 'dataHex' ? {dataHex:bytes.toString('hex').toUpperCase()} : {data:bytes.toString('base64')}), fPort:input.fPort ?? 2, fCnt:input.nonce ?? 0, rxInfo:[{rssi:-70,snr:9.5,gatewayId:'aabbccddeeff0011'}] }; - } - for (let i=0;i<80;i++) { - const event = uplink({nonce:i<40?1:2,energy:i<40?10+i*.01:(i-40)*.02,voltage:229+i%5,timestamp:Date.now()-(80-i)*60000}); - ingestEvent(`application/${application}/device/${event.deviceInfo.devEui}/event/up`,Buffer.from(JSON.stringify(event))); - } - const second = uplink({devEui:devices[1].devEui,energy:7.5,voltage:235}); - ingestEvent(`application/${application}/device/${second.deviceInfo.devEui}/event/up`,Buffer.from(JSON.stringify(second))); - app.post('/__test/manager', (req,res) => { - const body = req.body || {}; - if (body.action === 'stats') { res.json({enqueueCount,collectorCount,clients:clients.size}); return; } - if (body.action === 'list-failure') { listFailure = !!body.value; res.json({ok:true}); return; } - if (body.action === 'queue-failure') { queueFailure = !!body.value; res.json({ok:true}); return; } - if (body.action === 'disconnect') { for (const socket of clients) socket.destroy(); res.json({ok:true}); return; } - const event = body.kind && body.kind !== 'up' ? { deduplicationId:randomUUID(),time:new Date().toISOString(),deviceInfo:{devEui:body.devEui || devices[0].devEui,applicationId:application},queueItemId:body.queueItemId,acknowledged:body.acknowledged,location:body.location } : uplink(body); - const topic = `application/${application}/device/${event.deviceInfo.devEui}/event/${body.kind || 'up'}`; - const payload = body.action === 'malformed' ? '{' : JSON.stringify(event); - for (const socket of clients) socket.write(mqttPacket.generate({cmd:'publish',topic,payload,qos:0,retain:false,dup:false})); - res.json({event}); - }); - app.on('close', () => { stopUplinks(); for(const socket of clients) socket.destroy(); broker.close(); rest.close(); }); -}; diff --git a/tests/ui/manager-preview.cjs b/tests/ui/manager-preview.cjs deleted file mode 100644 index 754ab60..0000000 --- a/tests/ui/manager-preview.cjs +++ /dev/null @@ -1,23 +0,0 @@ -// UI preview only. All MQTT and REST endpoints are local simulators, never real meters. -module.exports = async function attachManagerPreview(app, server) { - process.env.M3TER_MANAGER_USERNAME = 'demo'; - process.env.M3TER_MANAGER_PASSWORD = 'demo-manager'; - const { requireManagerAuth, managerAuthenticated } = require('../../dist/m3ter/auth'); - const store = require('../../dist/store/sqlite'); - const database = `manager-preview-${process.pid}.db`; - store.default(database); process.on('exit',()=>store.deleteDatabase(database)); - await require('./manager-fixture.cjs')(app); - const { commandCatalogue } = require('../../dist/m3ter/commands'); - const { monitoring, managerEvents, inactiveMilliseconds } = require('../../dist/m3ter/monitor'); - app.get('/api/m3ter-manager/config',requireManagerAuth,(_req,res)=>res.json({commands:commandCatalogue,monitoring,inactiveMilliseconds:inactiveMilliseconds(),demo:true})); - app.use('/api/m3ter-manager',require('../../dist/m3ter/api').managerRouter); - const WebSocket = require('ws'); - const wss = new WebSocket.Server({noServer:true}); - server.on('upgrade',(req,socket,head)=>{ - if (req.url !== '/m3ter-manager/live' || !managerAuthenticated(req)) {socket.destroy();return;} - wss.handleUpgrade(req,socket,head,ws=>wss.emit('connection',ws,req)); - }); - const send = (ws,data)=>{if(ws.readyState===WebSocket.OPEN)ws.send(JSON.stringify(data));}; - wss.on('connection',(ws,req)=>{ ws.managerRequest=req; send(ws,{type:'connection',monitoring}); }); - managerEvents.on('update',data=>{for(const ws of wss.clients) { if(managerAuthenticated(ws.managerRequest))send(ws,data); else ws.close(4001,'Sign in required'); }}); -}; diff --git a/tests/ui/manager-relay.spec.cjs b/tests/ui/manager-relay.spec.cjs deleted file mode 100644 index 9c2ddcb..0000000 --- a/tests/ui/manager-relay.spec.cjs +++ /dev/null @@ -1,105 +0,0 @@ -const { test: base, expect } = require('@playwright/test'); -const http = require('node:http'); -const net = require('node:net'); -const meter = '0102030405060708', other = '1112131415161718'; -const upstream = 'http://127.0.0.1:4174'; - -// Exercise real browser upgrades through a relay, including rejected and stalled -// handshakes. No mocked WebSocket or changes to the production auth boundary. -const test = base.extend({ - relay: async ({}, use) => { - const state = { mode: 'reject', histories: 0, failHttp: false }, sockets = new Set(); - const server = http.createServer((req, res) => { - if (req.url.includes('/history?')) { - state.histories++; - if (state.failHttp) { res.writeHead(502); res.end('Relay unavailable'); return; } - } - const outgoing = http.request(upstream + req.url, { method: req.method, headers: req.headers }, response => { - res.writeHead(response.statusCode, response.headers); response.pipe(res); - }); - outgoing.on('error', () => { res.writeHead(502); res.end(); }); - req.pipe(outgoing); - }); - server.on('connection', socket => { sockets.add(socket); socket.on('close', () => sockets.delete(socket)); }); - server.on('upgrade', (req, socket, head) => { - if (state.mode === 'reject') { socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\nContent-Length: 0\r\n\r\n'); return; } - if (state.mode === 'stall') return; - const target = net.connect(4174, '127.0.0.1', () => { - const headers = req.rawHeaders.reduce((all, value, index, values) => index % 2 ? all : `${all}${value}: ${values[index + 1]}\r\n`, ''); - target.write(`${req.method} ${req.url} HTTP/${req.httpVersion}\r\n${headers}\r\n`); - if (head.length) target.write(head); - target.pipe(socket); socket.pipe(target); - }); - target.on('error', () => socket.destroy()); - socket.on('close', () => target.destroy()); - target.on('close', () => socket.destroy()); - }); - await new Promise(resolve => server.listen(0, '127.0.0.1', resolve)); - state.url = `http://127.0.0.1:${server.address().port}`; - await use(state); - for (const socket of sockets) socket.destroy(); - await new Promise(resolve => server.close(resolve)); - }, -}); - -async function open(page, relay) { - await page.route(/https:\/\//, route => route.abort()); - await page.goto(relay.url); - await page.evaluate(() => Desktop.launch('m3ter-manager')); - await page.locator('#mm-username').fill('test-manager'); - await page.locator('#mm-password').fill('test-only-manager-password'); - await page.locator('#mm-login-submit').click(); - await expect(page.locator('#mm-device option')).toHaveCount(4); - await page.locator('#mm-device').selectOption(meter); - await expect(page.locator('#mm-selected')).toHaveAttribute('aria-busy', 'false'); -} -const publish = (request, data) => request.post(upstream + '/__test/manager', { data }); -const fallback = page => expect(page.locator('#mm-feed')).toHaveText('Updates every 5s (HTTP fallback)', { timeout: 20000 }); - -test('rejected upgrade falls back to authenticated HTTP, filters meters, and cleans up on close', async ({ page, request, relay }) => { - await open(page, relay); await fallback(page); - const previous = await page.locator('#mm-energy').textContent(); - await publish(request, { devEui: other, energy: 9.123, nonce: 100 }); - const count = relay.histories; - await expect.poll(() => relay.histories, { timeout: 10000 }).toBeGreaterThan(count); - await expect(page.locator('#mm-energy')).toHaveText(previous); - await publish(request, { devEui: meter, energy: 3.456789, voltage: 232.1, nonce: 100 }); - await expect(page.locator('#mm-energy')).toHaveText('3.456789', { timeout: 10000 }); - await expect(page.locator('#mm-voltage')).toHaveText('232.1'); - await expect(page.locator('#mm-mqtt')).toHaveText('MQTT connected'); - const timestamp = await page.locator('#mm-uplink-time').textContent(); - await page.clock.setFixedTime(Date.now() + 120000); - await expect(page.locator('#mm-age')).toHaveText('2m ago'); - const before = relay.histories; - await expect.poll(() => relay.histories, { timeout: 10000 }).toBeGreaterThan(before); - await expect(page.locator('#mm-uplink-time')).toHaveText(timestamp); - await page.locator('#m3ter-manager .window-close').click(); - const closed = relay.histories; - await page.waitForTimeout(6000); // Cross a full polling interval to prove cleanup. - expect(relay.histories).toBe(closed); - await page.evaluate(() => Desktop.launch('m3ter-manager')); - await fallback(page); -}); - -test('stalled upgrade times out and revoked sessions lock HTTP fallback', async ({ page, relay }) => { - relay.mode = 'stall'; - await open(page, relay); await fallback(page); - expect((await page.request.delete(relay.url + '/api/m3ter-manager/session', { headers: { origin: relay.url } })).status()).toBe(200); - await expect(page.locator('#mm-login')).toBeVisible({ timeout: 10000 }); - await expect(page.locator('#mm-workspace')).toBeHidden(); - await expect(page.locator('#mm-login-error')).toContainText('Your session ended'); -}); - -test('HTTP failures are visible and WebSocket recovery stops fallback polling', async ({ page, relay }) => { - await open(page, relay); await fallback(page); - relay.failHttp = true; - await expect(page.locator('#mm-feed')).toHaveText('Automatic updates unavailable · retrying', { timeout: 10000 }); - relay.failHttp = false; - await fallback(page); - relay.mode = 'forward'; - await expect(page.locator('#mm-feed')).toHaveText('Live feed connected', { timeout: 35000 }); - await expect(page.locator('#mm-selected')).toHaveAttribute('aria-busy', 'false'); - const count = relay.histories; - await page.waitForTimeout(6000); - expect(relay.histories).toBe(count); -}); diff --git a/tests/ui/manager.spec.cjs b/tests/ui/manager.spec.cjs deleted file mode 100644 index fb1fe60..0000000 --- a/tests/ui/manager.spec.cjs +++ /dev/null @@ -1,197 +0,0 @@ -const { test, expect } = require('@playwright/test'); -const { randomUUID } = require('node:crypto'); -const base = 'http://127.0.0.1:4174', api = '/api/m3ter-manager'; -const a = '0102030405060708', b = '1112131415161718', empty = '2122232425262728'; -test.use({ baseURL: base }); -test.beforeEach(async ({ page, request }) => { await page.route(/https:\/\//, route => route.abort()); - expect((await request.post(api+'/session',{data:{username:'test-manager',password:'test-only-manager-password'}})).status()).toBe(200); -}); -async function open(page, id = a) { - await page.goto('/'); await page.evaluate(() => Desktop.launch('m3ter-manager')); - await page.locator('#mm-username').fill('test-manager'); await page.locator('#mm-password').fill('test-only-manager-password'); - await page.locator('#mm-login-submit').click(); - await expect(page.locator('#mm-device option')).toHaveCount(4); - await page.locator('#mm-device').selectOption(id); - await expect(page.locator('#mm-eui')).toHaveText(id); - await expect(page.locator('#mm-selected')).toHaveAttribute('aria-busy','false'); -} -const control = (request, body) => request.post('/__test/manager',{data:body}); - -test('real MQTT client receives multi-meter telemetry, reconnects, persists, and reports diagnostics', async ({ page, request }) => { - await open(page); - await expect(page.locator('#mm-mqtt')).toHaveText('MQTT connected'); - const before = await page.locator('#mm-energy').textContent(); - await control(request,{devEui:b,energy:22.5,nonce:5}); - await expect.poll(async () => (await (await request.get(`${api}/devices/${b}/history`)).json()).latest.energy).toBe(22.5); - await expect(page.locator('#mm-energy')).toHaveText(before); - const event = {devEui:a,energy:1.234567,voltage:231.2,nonce:82,eventId:randomUUID(),timestamp:Date.now()}; - await control(request,event); - await expect(page.locator('#mm-energy')).toHaveText('1.234567'); await expect(page.locator('#mm-voltage')).toHaveText('231.2'); - const total = (await (await request.get(`${api}/devices/${a}/history`)).json()).total; - await control(request,event); - expect((await (await request.get(`${api}/devices/${a}/history`)).json()).total).toBe(total); - await page.reload(); await page.evaluate(() => Desktop.launch('m3ter-manager')); - await expect(page.locator('#mm-energy')).toHaveText('1.234567'); - await control(request,{action:'disconnect'}); - await expect(page.locator('#mm-mqtt')).toHaveText(/disconnected|reconnecting/); - await expect(page.locator('#mm-mqtt')).toHaveText('MQTT connected',{timeout:15000}); - await control(request,{devEui:a,energy:1.3,nonce:83}); await expect(page.locator('#mm-energy')).toHaveText('1.300000'); - await page.locator('[data-mm-tab="live"]').click(); - await control(request,{devEui:a,length:73}); - await expect(page.locator('#mm-events')).toContainText('requires exactly 74 or 106 bytes'); - await control(request,{action:'malformed'}); await expect(page.locator('#mm-error')).toContainText('Unable to process'); - await page.locator('#mm-device').selectOption(b); await expect(page.locator('#mm-energy')).toHaveText('22.500000'); -}); - -test('backend validates scope, commands, safety confirmation, idempotency and exact queue payloads', async ({ request, playwright }) => { - expect((await fetch(base+api+'/devices')).status).toBe(401); - expect((await request.get(api+'/devices/not-a-device/history')).status()).toBe(400); - expect((await request.get(api+'/devices/ffffffffffffffff')).status()).toBe(403); - const details = await (await request.get(`${api}/devices/${a}`)).json(); - expect(JSON.stringify(details)).not.toContain('must-not-leak'); expect(JSON.stringify(details)).not.toContain('fixture-backend-token'); - for (const data of [ - {commandId:'relay-on',fPort:200,data:'AA=='}, {commandId:'current-gain',value:3}, {commandId:'phase-mode',value:4}, - {commandId:'report-interval',value:9}, {commandId:'report-interval',value:65536}, {commandId:'class-b'}, - {commandId:'billing-connect'}, {commandId:'restart'}, - ]) expect((await request.post(`${api}/devices/${a}/commands`,{data:{requestId:randomUUID(),...data}})).status()).toBe(400); - expect((await request.post(`${api}/devices/${a}/commands`,{headers:{origin:'https://foreign.example'},data:{commandId:'relay-on',requestId:randomUUID()}})).status()).toBe(403); - const count = (await (await control(request,{action:'stats'})).json()).enqueueCount; - const requestId = randomUUID(), body = {commandId:'report-interval',value:900,requestId}; - const accepted = await (await request.post(`${api}/devices/${a}/commands`,{data:body})).json(); - expect(accepted).toMatchObject({status:'queued',queueId:requestId,command:{fPort:2,data:'AgOE',hex:'020384',length:3}}); - await request.post(`${api}/devices/${a}/commands`,{data:body}); - expect((await (await control(request,{action:'stats'})).json()).enqueueCount).toBe(count+1); - expect((await request.post(`${api}/devices/${a}/commands`,{data:{...body,value:60}})).status()).toBe(409); - const queue = await (await request.get(`${api}/devices/${a}/queue`)).json(); - expect(queue.items).toEqual(expect.arrayContaining([expect.objectContaining({id:requestId,fPort:2,data:'AgOE',confirmed:false})])); - await control(request,{kind:'txack',devEui:a,queueItemId:requestId}); - const status = async () => (await (await request.get(`${api}/devices/${a}/commands`)).json()).commands.find(item=>item.id===requestId)?.status; - await expect.poll(status).toBe('transmitted'); - await control(request,{kind:'ack',devEui:a,queueItemId:requestId,acknowledged:true}); await expect.poll(status).toBe('delivered'); - expect((await request.delete(`${api}/devices/${a}/queue`,{data:{}})).status()).toBe(400); - expect((await request.delete(`${api}/devices/${a}/queue`,{data:{confirmDevEui:a}})).status()).toBe(200); - expect((await (await request.get(`${api}/devices/${a}/queue`)).json()).items).toHaveLength(0); - expect(await status()).toBe('delivered'); -}); - -test('command UI previews frames, protects billing and hardware controls, and clears the queue explicitly', async ({ page }) => { - await open(page); - await page.locator('[data-mm-command="relay-on"]').click(); - await expect(page.locator('#mm-dialog')).toBeVisible(); await expect(page.locator('#mm-dialog-content')).toContainText('Base64: Gw=='); - expect(await page.locator('#mm-dialog').evaluate(el=>el.closest('.app-window').id)).toBe('m3ter-manager'); - const dialogBox=await page.locator('#mm-dialog').boundingBox(), ownerBox=await page.locator('#m3ter-manager').boundingBox(); - expect(dialogBox.x).toBeGreaterThanOrEqual(ownerBox.x);expect(dialogBox.x+dialogBox.width).toBeLessThanOrEqual(ownerBox.x+ownerBox.width); - expect(dialogBox.y).toBeGreaterThanOrEqual(ownerBox.y);expect(dialogBox.y+dialogBox.height).toBeLessThanOrEqual(ownerBox.y+ownerBox.height); - await page.evaluate(()=>Desktop.launch('browser'));await page.locator('#browser-query').fill('Another app stays usable'); - await page.evaluate(()=>Desktop.launch('m3ter-manager')); - await page.locator('#mm-submit').click(); await expect(page.locator('#mm-notice')).toContainText('Relay ON: queued'); - await page.locator('[data-mm-tab="commands"]').click(); - await page.locator('[data-command-id="billing-disconnect"]').click(); - await expect(page.locator('#mm-submit')).toBeDisabled(); await expect(page.locator('#mm-dialog-content')).toContainText('energy accumulator will reset'); - await page.locator('#mm-confirm').check(); await page.locator('#mm-submit').click(); - await expect(page.locator('#mm-command-history')).toContainText('Disconnect (Billing)'); - await page.getByLabel('Report interval presets').selectOption('60'); await page.locator('[data-command-id="report-interval"]').click(); - await expect(page.locator('#mm-dialog-content')).toContainText('AgA8'); await expect(page.locator('#mm-dialog-content')).toContainText('Selected setting: 60 seconds'); await page.locator('#mm-cancel').click(); - await page.getByLabel('Current gain (PGA)',{exact:true}).selectOption('4'); await page.locator('[data-command-id="current-gain"]').click(); - await expect(page.locator('#mm-dialog-content')).toContainText('IAQ='); await page.locator('#mm-cancel').click(); - await page.locator('[data-mm-tab="queue"]').click(); await expect(page.locator('#mm-queue')).toContainText('Pending delivery'); - await page.locator('#mm-queue-clear').click(); await expect(page.locator('#mm-submit')).toBeDisabled(); - await expect(page.locator('#mm-dialog-content')).toContainText('ALL currently queued downlinks'); - await page.locator('#mm-confirm').check(); await page.locator('#mm-submit').click(); await expect(page.locator('#mm-queue')).toContainText('No pending downlinks'); -}); - -test('search, empty meters, analytics, raw reading inspection and error recovery work', async ({ page, request }) => { - await open(page); - await page.locator('#mm-search').fill('111213'); await expect(page.locator('#mm-device option')).toHaveCount(3); // current selection stays pinned - await page.locator('#mm-device').selectOption(b); await expect(page.locator('#mm-name')).toContainText('Solar room'); - await page.locator('#mm-search').fill(''); await expect(page.locator('#mm-device option')).toHaveCount(4); - await page.locator('#mm-device').selectOption(empty); await expect(page.locator('#mm-energy')).toHaveText('—'); await expect(page.locator('#mm-age')).toHaveText('Never observed'); - await page.locator('#mm-device').selectOption(a); await page.locator('[data-mm-tab="analytics"]').click(); - await expect(page.locator('#mm-summary')).toContainText('Pending snapshots are not added'); - await expect(page.locator('#mm-history-energy svg')).toBeVisible(); await page.locator('#mm-history-energy svg').focus(); await page.keyboard.press('ArrowLeft'); - await expect(page.locator('#mm-history-energy .mm-chart-tooltip')).toContainText('kWh'); - await page.locator('#mm-history-next').click(); await expect(page.locator('#mm-history-count')).toContainText('51–'); - await page.locator('#mm-readings button').first().click(); await expect(page.locator('#mm-dialog-content')).toContainText('Raw payload (Base64)'); await page.locator('#mm-cancel').click(); - await page.locator('#mm-range').selectOption('3600000'); await expect(page.locator('#mm-history-count')).toContainText('1–'); - await control(request,{action:'list-failure',value:true}); - try { await page.locator('#mm-refresh').click(); await expect(page.locator('#mm-error')).toBeVisible(); } - finally { await control(request,{action:'list-failure',value:false}); } - await page.locator('#mm-refresh').click(); await expect(page.locator('#mm-error')).toBeHidden(); - await control(request,{action:'queue-failure',value:true}); - try { await page.locator('[data-mm-tab="queue"]').click(); await expect(page.locator('#mm-queue')).toContainText('rejected the request'); } - finally { await control(request,{action:'queue-failure',value:false}); } - await page.locator('#mm-queue-refresh').click(); await expect(page.locator('#mm-queue')).toContainText('No pending downlinks'); -}); - -test('manager adapts to every desktop theme and desktop, tablet and phone dimensions', async ({ page }, testInfo) => { - await open(page); - const errors = []; page.on('pageerror',error=>errors.push(error.message)); - for (const [width,height] of [[1440,900],[768,1024],[390,844],[320,568]]) { - await page.setViewportSize({width,height}); - for (const theme of ['retro','macos','linux','windows']) { - await page.evaluate(()=>Desktop.launch('settings')); - await page.locator(`[data-theme-choice="${theme}"]`).click(); await page.evaluate(()=>Desktop.launch('m3ter-manager')); - await expect(page.locator('#mm-eui')).toHaveText(a); - const bounds = await page.locator('#m3ter-manager').boundingBox(); - expect(bounds.x).toBeGreaterThanOrEqual(0); expect(bounds.x+bounds.width).toBeLessThanOrEqual(width+1); - expect(await page.locator('.mm-scroll').evaluate(element=>element.scrollWidth<=element.clientWidth+1)).toBe(true); - await page.locator('[data-mm-tab="commands"]').click(); - expect(await page.locator('.mm-scroll').evaluate(element=>element.scrollWidth<=element.clientWidth+1)).toBe(true); - await page.locator('[data-mm-tab="overview"]').click(); - if (width===1440 || width===390) await page.screenshot({path:testInfo.outputPath(`manager-${theme}-${width}.png`)}); - } - } - expect(errors).toEqual([]); -}); - -test('closing Manager does not stop MQTT or the independent collector consumer', async ({page,request}) => { - await open(page); - const before=await (await control(request,{action:'stats'})).json(); - await page.locator('#m3ter-manager .window-close').click(); - await control(request,{devEui:a,nonce:90,energy:0.123}); - await expect.poll(async()=> (await (await control(request,{action:'stats'})).json()).collectorCount).toBe(before.collectorCount+1); - expect((await (await control(request,{action:'stats'})).json()).clients).toBe(1); - await page.evaluate(()=>Desktop.launch('m3ter-manager')); - await expect(page.locator('#mm-energy')).toHaveText('0.123000'); -}); - -test('Overview receipt age increases beyond a minute and updates only on new uplinks', async ({page,request}) => { - await open(page); - const received=await control(request,{devEui:a,nonce:91,energy:0.25,timestamp:Date.now()+60000}); - const event=(await received.json()).event; - await expect(page.locator('#mm-energy')).toHaveText('0.250000'); - const state=(await (await request.get(`${api}/devices/${a}`)).json()).state; - expect(state.lastUplink).toBeLessThan(Date.parse(event.time)); - await expect(page.locator('[data-mm-panel="overview"]')).not.toContainText(/accumulator|pending snapshot|uncertain cycle/i); - for (const [seconds,label] of [[30,'30s ago'],[70,'1m ago'],[300,'5m ago'],[7200,'2h ago']]) { - await page.clock.setFixedTime(state.lastUplink+seconds*1000); - await expect(page.locator('#mm-age')).toHaveText(label); - } - await control(request,{kind:'status',devEui:a}); - await page.locator('#mm-refresh').click(); await expect(page.locator('#mm-age')).toHaveText('2h ago'); - expect((await (await request.get(`${api}/devices/${a}`)).json()).state.lastUplink).toBe(state.lastUplink); - await page.clock.setFixedTime(Date.now()); - await control(request,{devEui:a,nonce:92,energy:0.1,timestamp:Date.now()+61000}); - await expect(page.locator('#mm-nonce')).toHaveText('92'); - await expect(page.locator('#mm-age')).toHaveText('0s ago'); -}); - -test('live hex payload travels through shared MQTT, retains bytes, and reaches both consumers', async ({page,request}) => { - await open(page); - const before=(await (await control(request,{action:'stats'})).json()).collectorCount; - for (const encoding of ['hex','dataHex']) { - const result=await (await control(request,{devEui:b,nonce:10,energy:1.234567,encoding})).json(); - await expect.poll(async()=> (await (await request.get(`${api}/devices/${b}/history`)).json()).latest.energy).toBe(1.234567); - await page.locator('#mm-device').selectOption(b); - await page.locator('[data-mm-tab="live"]').click(); - const hex=result.event.dataHex || result.event.data; - await expect(page.locator('#mm-events')).toContainText('Uplink decoded'); - await expect.poll(async()=> (await page.locator('#mm-events').textContent()).includes(hex)).toBe(true); - await page.locator('#mm-events details').first().locator('summary').click(); - await expect(page.locator('#mm-events details').first()).toContainText('Payload (hex)'); - const history=await (await request.get(`${api}/devices/${b}/history`)).json(); - const row=history.rows.find(row=>row.rawPayload===hex); - expect(JSON.parse(row.metadata).payloadHex).toBe(hex); - } - await expect.poll(async()=> (await (await control(request,{action:'stats'})).json()).collectorCount).toBe(before+2); -}); diff --git a/tests/ui/network.spec.cjs b/tests/ui/network.spec.cjs index 7a5b8ee..aba770f 100644 --- a/tests/ui/network.spec.cjs +++ b/tests/ui/network.spec.cjs @@ -1,16 +1,15 @@ const {test,expect}=require('@playwright/test'); const os=require('node:os'); -test('Console and Manager login work on localhost and LAN with no Console password or origin setting',async({browser,request})=>{ +test('Console opens on localhost and LAN without a login or origin setting',async({browser,request})=>{ const lan=Object.values(os.networkInterfaces()).flat().find(x=>x.family==='IPv4'&&!x.internal)?.address; expect(lan,'A LAN interface is needed for this integration check').toBeTruthy(); for(const host of ['localhost',lan]){ const base=`http://${host}:4174`; expect((await request.get(base+'/healthz')).status()).toBe(200); const context=await browser.newContext(),page=await context.newPage();await page.route(/https:\/\//,r=>r.abort()); - await page.goto(base);await page.evaluate(()=>Desktop.launch('m3ter-manager')); - await expect(page.locator('#mm-login')).toBeVisible(); - await page.locator('#mm-username').fill('test-manager');await page.locator('#mm-password').fill('test-only-manager-password');await page.locator('#mm-login-submit').click(); - await expect(page.locator('#mm-workspace')).toBeVisible();await expect(page.locator('#mm-feed')).toHaveText('Live feed connected'); + await page.goto(base);await expect(page.locator('#desktop')).toBeVisible(); + await page.evaluate(()=>Desktop.launch('settings'));await expect(page.locator('#settings')).toBeVisible(); + await expect(page.locator('[data-app-id="m3ter-manager"]')).toHaveCount(0); await context.close(); } }); diff --git a/tests/ui/serve-auth.cjs b/tests/ui/serve-auth.cjs index 71e060e..7ae9471 100644 --- a/tests/ui/serve-auth.cjs +++ b/tests/ui/serve-auth.cjs @@ -1,6 +1,4 @@ // Production HTTP/WebSocket access checks, with no MQTT, chain, or SSH login. -process.env.M3TER_MANAGER_USERNAME = 'test-manager'; -process.env.M3TER_MANAGER_PASSWORD = 'test-only-manager-password'; delete process.env.CONSOLE_USERNAME; delete process.env.CONSOLE_PASSWORD; process.env.BACKEND_MODULES = ''; @@ -18,6 +16,5 @@ upstream.listen(0, '127.0.0.1', async () => { const ssh = await require('./ssh-fixture.cjs')(); attachTerminal(server,ssh.target); server.on('close',()=>ssh.server.close()); - await require('./manager-fixture.cjs')(app); server.listen(4174, '0.0.0.0', () => console.log('Authentication test server ready on 4174')); }); diff --git a/tests/ui/serve.cjs b/tests/ui/serve.cjs index 892b809..32c6ec1 100644 --- a/tests/ui/serve.cjs +++ b/tests/ui/serve.cjs @@ -16,10 +16,8 @@ app.get('/', (req, res) => { icons.push({ id, label: i ? `Extension ${i}` : 'Streamr', iconHtml: '' }); windows.push({ id, title: i ? `Extension ${i}` : 'Streamr Publisher', contentHtml: '

Configuration

Pending transactions: 2

' }); } - res.render('index', { managerDemo: true, icons, windows }); + res.render('index', { icons, windows }); }); app.post('/api/actions/:moduleId/:actionId', (req, res) => res.json({ success: true, message: 'Published 2 transactions (test fixture)' })); const server = require('node:http').createServer(app); -require('./manager-preview.cjs')(app, server).then(() => { - server.listen(4173, '127.0.0.1', () => console.log('UI preview (simulated meters): http://127.0.0.1:4173')); -}).catch(error => { console.error(error); process.exit(1); }); +server.listen(4173, '127.0.0.1', () => console.log('UI fixture ready on 4173')); From 9a7cd7326d9ea410ed91288d8ee757dbaf3c1e5c Mon Sep 17 00:00:00 2001 From: "Isaac J. Newton" Date: Tue, 17 Nov 2026 11:36:17 +0000 Subject: [PATCH 3/9] feat: add tested central identity and agent protocol foundations --- .env.example | 26 ++-- docs/centralized/deployment.md | 47 ++++++++ docs/centralized/design.md | 80 ++++++++++++ docs/centralized/test-plan.md | 94 +++++++++++++++ src/central/auth.ts | 100 +++++++++++++++ src/central/config.ts | 67 +++++++++++ src/central/destinations.ts | 74 ++++++++++++ src/central/identity-store.ts | 154 ++++++++++++++++++++++++ src/central/protocol.ts | 102 ++++++++++++++++ src/central/secrets.ts | 49 ++++++++ tests/services/agent-protocol.test.ts | 45 +++++++ tests/services/central-auth.test.ts | 62 ++++++++++ tests/services/central-identity.test.ts | 91 ++++++++++++++ tests/services/destinations.test.ts | 34 ++++++ 14 files changed, 1015 insertions(+), 10 deletions(-) create mode 100644 docs/centralized/deployment.md create mode 100644 docs/centralized/design.md create mode 100644 docs/centralized/test-plan.md create mode 100644 src/central/auth.ts create mode 100644 src/central/config.ts create mode 100644 src/central/destinations.ts create mode 100644 src/central/identity-store.ts create mode 100644 src/central/protocol.ts create mode 100644 src/central/secrets.ts create mode 100644 tests/services/agent-protocol.test.ts create mode 100644 tests/services/central-auth.test.ts create mode 100644 tests/services/central-identity.test.ts create mode 100644 tests/services/destinations.test.ts diff --git a/.env.example b/.env.example index cc5f742..cdb604b 100644 --- a/.env.example +++ b/.env.example @@ -3,11 +3,6 @@ PORT=3000 # Listen on LAN interfaces as well as localhost. CONSOLE_HOST=0.0.0.0 -# Only M3ter Manager requires login. Console itself is public. -M3TER_MANAGER_USERNAME=admin -M3TER_MANAGER_PASSWORD= -# Optional global telemetry history limit; invalid values fall back to 100. -# M3TER_TELEMETRY_LIMIT=100 # Module Configuration BACKEND_MODULES="core/arweave,core/is_on,core/prover,core/streamr" @@ -22,13 +17,9 @@ CHIRPSTACK_HOST=localhost # CHEFSTACK_URL=http://localhost:8080 # CHIRPSTACK_WEB_URL remains supported; CHEFSTACK_URL takes precedence. # CHIRPSTACK_WEB_URL=http://localhost:8080 -# M3ter Manager uses the existing ChirpStack v4 REST proxy and the same API_TOKEN. -# This is the REST proxy's port, NOT the ChirpStack web UI port. -# CHIRPSTACK_REST_URL=http://localhost:8090 -# Both consumers share this optional broker URL (mqtt/mqtts/ws/wss). +# Optional broker URL (mqtt/mqtts/ws/wss). # When absent, preserve CHIRPSTACK_HOST on port 1883, default localhost. # MQTT_URL=mqtt://localhost:1883 -# M3TER_INACTIVE_SECONDS=300 # Contract & Network Configuration CONTRACT_LABEL=M3ters @@ -43,3 +34,18 @@ STREAMR_CRONSCHEDULE="0 * * * *" # Every hour # Optional: Prover Node (disabled publishing to prover if not set) # PREFERRED_PROVER_NODE="https://prover.m3ter.ing" # PROVER_CRONSCHEDULE="0 0 * * *" # Every 24 hours + +# Centralized Console feature branch — opt-in configuration contract. +# These settings are not a deployment recipe until docs/centralized/deployment.md +# marks the role runtime complete. Existing installations remain standalone. +# CONSOLE_ROLE=standalone +# CENTRAL_URL=wss://console.example.invalid +# AGENT_CREDENTIAL_PATH=/opt/app/.data/agent/credential +# FALLBACK_SECRET_PATH=/opt/app/.data/agent/fallback-secret +# CENTRAL_DECISION_TIMEOUT_MS=8000 +# CENTRAL_RECOVERY_HEALTHY_MS=15000 +# AGENT_QUEUE_LIMIT=10000 +# Never enable this outside isolated development fixtures. +# CENTRAL_ALLOW_INSECURE_DEVELOPMENT=false +# Only explicit reverse-proxy peer IPs; forwarded headers are otherwise ignored. +# CENTRAL_TRUSTED_PROXIES=127.0.0.1,::1 diff --git a/docs/centralized/deployment.md b/docs/centralized/deployment.md new file mode 100644 index 0000000..80c9b02 --- /dev/null +++ b/docs/centralized/deployment.md @@ -0,0 +1,47 @@ +# Deployment status + +This feature branch is **not deployable as a central system yet**. Do not set the +new role variables on an operating gateway. No real gateway has been contacted, +enrolled or updated during development. + +The implemented compatibility work removes Manager while preserving standalone +collection and the default deployment interfaces. The central configuration, +identity and protocol modules are currently tested components, not connected +services. Agent, tunnels, updater and browser-engine deployment still require +integration. Do not mistake example configuration for a working rollout recipe. + +## Existing standalone deployments + +Keep the current `.env`, `compose.yaml`, project name and data directory. The +deployment script still updates only the Console service and preserves data and +extension volumes. An explicitly selected previous image can be restored with: + +```sh +./auto-compose.sh --image ghcr.io/OWNER/console@sha256:PREVIOUS_IMAGE_DIGEST +``` + +Use the actual trusted repository and recorded digest; these are placeholders. +No task instruction authorizes testing this against a production device. + +## Planned opt-in topology + +- Central: TLS reverse proxy, authenticated Console, persistent central SQLite + database, optional isolated Chromium service. Explicit proxy peers are trusted; + arbitrary forwarded headers are not. +- Gateway: local Console and outbound-only agent with host networking; durable + agent state and owner-only secret files. Existing ChirpStack and MQTT settings + are reused. The agent has no Docker socket mount. +- Updater: separate local authenticated service, disabled by the gateway owner + unless opted in. It alone has Docker access. It must verify image provenance by + digest and replace agent and local Console together, retaining volumes and `.env`. + +Enrollment credentials are single-use and expire. Long-lived agent secrets must +never appear in URLs, Compose command arguments, logs, or git. Rotation overlaps +old and new credentials for two minutes and ends the overlap on acknowledgment. +Revocation must close the active connection as well as rejecting authentication. +The connection integration is not implemented yet. + +The future signing trust policy must constrain registry/repository, workflow +identity and allowed refs; enabling a test ref must be explicit on the gateway. +No unsigned updater fallback is acceptable. Automatic rollout and systemd +installation instructions will be added only with their tested implementations. diff --git a/docs/centralized/design.md b/docs/centralized/design.md new file mode 100644 index 0000000..c6f7146 --- /dev/null +++ b/docs/centralized/design.md @@ -0,0 +1,80 @@ +# Centralized Console design and decision record + +Status: implementation in progress on `feat/centralized-console`. This is a test +branch, not a production deployment. See `current-architecture.md` for the audited +baseline. Sections below distinguish decisions from unresolved requirements. + +## Compatibility and roles + +One Console image is the target, with separate Console and agent entry points. +The default role remains standalone. The existing deployment script and default +Compose file must not activate central features. The gateway role retains its +LAN desktop and local SSH service; central must authenticate before serving any +desktop, application API, WebSocket or tunnel. + +The Manager application is removed. Its former protocol decoder is retained under +`src/lib/protocol` with its companion decoder and protocol tests, because the task +explicitly protects decoder compatibility. This does not retain any Manager API, +monitoring subscription, command catalogue, persistence or UI. Existing database +tables remain untouched. Legacy Manager configuration produces one warning with +no values. Shared application UUID validation moves to `lib/chirpstack-config`. + +## Single-decider safety: decision required + +The baseline commits transactions before calling enqueue and invokes distribution +after the attempt. ChirpStack enqueue supplies no idempotency key. If a reply is +lost, neither retrying nor handing the report to another decider is safe merely +because a deadline expired. A network partition does not fence the remote worker. + +The proposed safe rule is durable ownership before side effects, with uncertain +committed events held for reconciliation. Fallback is permitted before ownership +is committed; a late offer cannot regain ownership. Before an enqueue call the +agent must durably mark the attempt; an interrupted attempt cannot be retried +automatically. This guarantees at-most-one attempt, at the cost of potentially +missing a downlink after a crash. An 8-second deadline would bound normal offer +waiting, not grant permission to duplicate a committed operation. + +**Pending user clarification:** may uncertain events be held instead of falling +back/retrying automatically? The requested unconditional deadline fallback and +exactly-one side effects cannot both be promised with the current external APIs. +Do not enable a billing failover path until this tradeoff is agreed. + +## Distribution boundary + +Chain-confirmed nonce filtering is useful but is not external publication +idempotency. Arweave, Streamr and prover retries can repeat an unconfirmed +publication. The proposed managed-mode policy is central-only publication, +including cron and UI actions, with durable per-module claims and reconciliation +records. Local billing can persist reports during an outage but must not +independently publish them. An uncertain external publication requires the same +explicit availability tradeoff; claiming exactly-once from an in-memory Set or +SQLite flag alone would be incorrect. Standalone behavior must remain unchanged. + +## Browser approach under evaluation + +A remote Chromium engine is required for ordinary sites: an iframe rewriting +proxy cannot generally preserve CSP, service workers, cookies and modern scripts. +Chromium should be optional so the default image remains usable on small gateways. +A missing engine must be visible in the app, not cause Console startup failure. + +Traffic must use a per-session controlled proxy and isolated browser profile. +DNS must be classified and pinned at the connection boundary. In central mode, +private destinations route only through the selected agent, never through the +central network. Cloud metadata is always refused. Gateway allowlists remain +owner-controlled and separate by tunnel purpose. + +A blind CONNECT proxy cannot inspect the requesting origin inside TLS. Therefore +public-to-private protection cannot be claimed from destination filtering alone. +An implementation must pair trusted request provenance with proxy enforcement +and prevent engine bypass, or terminate and inspect browser traffic in a +controlled trust boundary. This is an implementation/security gate, not a reason +to silently ship an unrestricted HTTP CONNECT proxy. + +## Deployment and verification constraints + +No production services are contacted. Contract, MQTT, ChirpStack and SSH tests use +doubles or local fixture services. No rollout is performed by this task. +The local host is AMD64; ARM64 runtime resource measurements require an ARM64 +test environment. Measurements must not be estimated and presented as observed. +Existing workflow publishing conventions are preserved; attestations will be +additive and run only when images are actually published. diff --git a/docs/centralized/test-plan.md b/docs/centralized/test-plan.md new file mode 100644 index 0000000..7e9f5d7 --- /dev/null +++ b/docs/centralized/test-plan.md @@ -0,0 +1,94 @@ +# Verification ledger and test plan + +This is a development ledger, not a declaration that the full feature passes. +No test contacts real MQTT/ChirpStack, a gateway, meter or blockchain. + +## Automated coverage implemented + +- Frozen baseline `handleMessage` versus the modified collector for signature + rejection, valid reports, stale nonces, nonce zero, repeated reports and an + extension exception. Downlink bytes, transaction content, latest nonce, + distribution count and error outcomes are compared. +- Existing codec, signature, hooks, nonce synchronization and SQLite tests. +- Manager removal: no desktop entry or HTTP API, old settings ignored without + logging values, initialization preserves an existing Manager table and data. +- Role configuration defaults, TLS opt-in validation and bounded settings. +- Hashed enrollment/credentials, single-use tokens, expiry, rotation overlap, + acknowledgment and revocation; hashed passwords and session expiry/logout. +- Credential file permissions and symlink refusal; bounded sign-in rate limiting. +- Strict protocol direction, message sizes, fixed vocabulary, billing-only + downlinks, FPort 2 uplinks, tunnel limits and image digest format. +- Address classification, unusual IPv4 encodings, IPv4-mapped IPv6, metadata + refusal, DNS pinning contract, mixed-address refusal and private routing policy. + +The completed `npm test -- --runInBand --silent` run passed **193 tests in 24 +suites**, including HTTP-auth injection tests, in approximately 15 seconds. +The desktop suite passed 24 of 25 tests; the remaining new removal assertion +expected the wrong desktop title. After correcting it, the two Browser tests +passed on a targeted rerun. No existing application behavior was changed to +satisfy that assertion. This is not a full post-fix suite rerun. + +A first attempt could not locate the Playwright browser; the successful runs used +the existing `/tmp/console-ci-browsers` installation. The required +`playwright install --with-deps chromium` was attempted but sudo +required an interactive password unavailable in this session. This is not a +successful reproduction of that CI installation step. + +## Coverage still required before publication + +The agent/central/local integration, durable ownership, uncertain outcomes, +reconciliation/distribution, lease handoff, bounded spool and crash recovery must +be implemented and tested. The required billing safety decision is recorded in +`design.md`. Browser engine/proxy/PNA tests, SSH tunnel tests, ChirpStack streaming +tunnel tests, updater verification and rollback tests, and central gateway UI +tests remain outstanding. Classifier tests alone do not prove proxy enforcement. + +Before any push run the exact dependency, unit, UI and Docker checks requested in +the task. Do not publish or report a green workflow before doing so. The local +host is AMD64; native ARM64 execution and physical gateway resource measurements +are unavailable here. Docker has other running services: never stop them or +prune unrelated images to make room for tests. + +## Manual plan: one explicitly authorized test gateway + +These steps are a future operator plan, **not executed by this task**. Use an +isolated meter/network and test contract environment; do not alter production +billing. Record gateway architecture, firmware, image digests and signing identity. + +1. Back up `.env` and database. Verify standalone starts without new settings and + serves the LAN desktop without login. Check that Manager is absent and billing + still produces the same fail-closed decision on an unavailable revenue read. +2. Start the opt-in central test deployment behind TLS and enroll the gateway + with a one-time token. Verify replay/expiry rejection, owner-only credentials, + no inbound gateway listener, and authenticated central pages and upgrades. +3. Send known signed FPort 2 reports. Check event IDs, the central transaction + records, and **exactly one** ChirpStack queue entry per processed report. Confirm + non-billing uplinks are ignored. +4. Stop central, continue reporting, then restart central. Check agreed fallback + ownership, local durable transactions, late-decision rejection and idempotent + replay. Inspect each publication destination for duplicate `(tokenId, nonce)`. + Explicitly test an enqueue response lost after the queue accepted it. +5. Restart the agent during each ownership/enqueue transition. Check the journal + and queue for duplicates; test both Consoles down, ordered drain, spool bounds, + lease handoff and firmware behavior after unanswered reports. +6. Open central Terminal for this gateway; authenticate against a test SSH user, + resize, disconnect and reconnect. Check host-key change refusal, idle/session + limits and purpose allowlists. Verify audit entries contain no credentials or + keystrokes. The local Terminal must still work directly. +7. Open ChirpStack through central, including a streaming gRPC-Web request. + Verify the destination gateway and that Console cookies/API_TOKEN do not leak. +8. Browse a non-frameable test website inside Browser, navigate back/forward and + open a target-blank link. Open an explicitly typed gateway-local page. Attempt + public-page fetches, forms, WebSockets and redirects to private/metadata hosts; + all unauthorized requests must fail at the proxy. Inspect destination logs. +9. Rotate and revoke the agent credential. Verify rotation keeps service and + revocation disconnects immediately. Test reconnect and session expiration. +10. Request an authorized signed digest update. Verify both containers change, + configuration/data remain, and an unhealthy or non-reconnecting image rolls + back. Wrongly signed/unsigned images must never start. Verify disabled owner + policy and cancellation before an update begins. +11. Restore the previous recorded digest, then return the gateway to standalone. + Confirm no double subscriptions and no orphaned tunnel/browser/updater jobs. + +Capture actual results and CI URLs when these tests become runnable. Do not tick +manual or architecture-specific checks based only on simulated unit fixtures. diff --git a/src/central/auth.ts b/src/central/auth.ts new file mode 100644 index 0000000..f58d5a0 --- /dev/null +++ b/src/central/auth.ts @@ -0,0 +1,100 @@ +import type { IncomingMessage } from 'http'; +import type { Request, Response, NextFunction, Express } from 'express'; +import express from 'express'; +import { TLSSocket } from 'tls'; +import type { IdentityStore, SessionIdentity } from './identity-store'; +import { hashPassword, verifyPassword } from './secrets'; +import { isSameOrigin } from '../services/auth'; + +const cookieName = '__Host-console_session'; +const loginPage = `Sign in · M3tering Console

M3tering Console

Sign in to the central workspace.

`; + +/** Bounded fixed-window limiter. Uses the socket peer, never untrusted XFF. */ +export class RateLimit { + private entries = new Map(); + constructor(private limit: number, private windowMs: number, private maxKeys = 10000, private now: () => number = Date.now) {} + allow(key: string): boolean { + const now = this.now(); + const found = this.entries.get(key); + if (found && found.until > now) return ++found.count <= this.limit; + for (const [id, entry] of this.entries) if (entry.until <= now) this.entries.delete(id); + if (this.entries.size >= this.maxKeys) return false; + this.entries.set(key, { until: now + this.windowMs, count: 1 }); + return true; + } +} + +export interface CentralAuthOptions { development: boolean; trustedProxies: string[] } +export class CentralAuth { + private limiter = new RateLimit(10, 60000); + private globalLimiter = new RateLimit(100, 60000, 1); + private dummyHash: Promise = hashPassword('non-user authentication timing placeholder'); + constructor(private store: IdentityStore, private options: CentralAuthOptions) {} + private name(): string { return this.options.development ? 'console_dev_session' : cookieName; } + private token(req: IncomingMessage): string { + const matches = (req.headers.cookie || '').split(';').map(part => part.trim()).filter(part => part.startsWith(this.name() + '=')); + return matches.length === 1 ? matches[0].slice(this.name().length + 1) : ''; + } + session(req: IncomingMessage): SessionIdentity | null { return this.store.session(this.token(req)); } + secure(req: IncomingMessage): boolean { + if (req.socket instanceof TLSSocket && req.socket.encrypted) return true; + const peer = req.socket.remoteAddress?.replace(/^::ffff:/, '') || ''; + return this.options.trustedProxies.includes(peer) && req.headers['x-forwarded-proto'] === 'https'; + } + authorize = (req: IncomingMessage): boolean => + (this.options.development || this.secure(req)) && isSameOrigin(req, true) && !!this.session(req); + private cookie(token: string, expired = false): string { + return `${this.name()}=${token}; Path=/; HttpOnly; SameSite=Strict; Max-Age=${expired ? 0 : 28800}${this.options.development ? '' : '; Secure'}`; + } + /** Mount before static files, reverse proxies, parsers and application routes. */ + mount(app: Express): void { + app.use((req, res, next) => { + res.setHeader('Cache-Control', 'no-store'); + res.setHeader('Referrer-Policy', 'no-referrer'); + if (!this.options.development && !this.secure(req)) { res.status(400).send('HTTPS is required.'); return; } + if (!isSameOrigin(req)) { res.status(403).send('Cross-site requests are not permitted.'); return; } + next(); + }); + app.get('/login', (_req, res) => { + res.setHeader('Content-Security-Policy', "default-src 'none'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'"); + res.type('html').send(loginPage); + }); + app.post('/login', (req, res, next) => { + if (!this.globalLimiter.allow('login') || !this.limiter.allow(req.socket.remoteAddress || 'unknown')) { res.status(429).send('Too many attempts. Try again later.'); return; } + next(); + }, express.urlencoded({ extended: false, limit: '3kb', parameterLimit: 2 }), (req, res, next) => { void this.login(req, res).catch(next); }); + app.use(this.requireLogin); + app.post('/logout', (req, res) => { + const session = this.session(req); + this.store.endSession(this.token(req)); + this.store.audit(session?.id || 'unknown', 'logout'); + res.setHeader('Set-Cookie', this.cookie('', true)); + res.redirect(303, '/login'); + }); + } + requireLogin = (req: Request, res: Response, next: NextFunction): void => { + const session = this.session(req); + if (!session) { + if (req.method === 'GET' && req.path === '/') res.redirect(303, '/login'); + else res.status(401).json({ error: 'Sign in to the central Console.' }); + return; + } + res.locals.centralUser = session; + next(); + }; + private async login(req: Request, res: Response): Promise { + const username = typeof req.body?.username === 'string' ? req.body.username : ''; + const user = /^[A-Za-z0-9_.@-]{1,100}$/.test(username) ? this.store.user(username) : null; + const valid = await verifyPassword(req.body?.password, user?.passwordHash || await this.dummyHash); + if (!user || !valid) { + // Do not audit the attacker-supplied username/password or the request body. + this.store.audit('anonymous', 'login-failure'); + res.status(401).send('Invalid username or password.'); return; + } + this.store.endSession(this.token(req)); + const session = this.store.createSession(user.id); + this.store.audit(user.id, 'login-success'); + res.setHeader('Set-Cookie', this.cookie(session)); + res.redirect(303, '/'); + } +} diff --git a/src/central/config.ts b/src/central/config.ts new file mode 100644 index 0000000..97b0491 --- /dev/null +++ b/src/central/config.ts @@ -0,0 +1,67 @@ +import path from 'path'; +import { isIP } from 'net'; + +export type ConsoleRole = 'standalone' | 'central' | 'gateway'; +export interface RoleConfig { + role: ConsoleRole; + development: boolean; + decisionTimeoutMs: number; + recoveryHealthyMs: number; + queueLimit: number; + centralUrl?: string; + credentialPath?: string; + fallbackSecretPath?: string; + trustedProxies: string[]; +} + +function integer(env: NodeJS.ProcessEnv, name: string, fallback: number, min: number, max: number): number { + const raw = env[name]; + if (raw === undefined) return fallback; + if (!/^\d+$/.test(raw)) throw new Error(`${name} must be an integer between ${min} and ${max}.`); + const value = Number(raw); + if (!Number.isSafeInteger(value) || value < min || value > max) throw new Error(`${name} must be an integer between ${min} and ${max}.`); + return value; +} + +function filePath(env: NodeJS.ProcessEnv, name: string): string | undefined { + const value = env[name]; + if (value === undefined) return undefined; + if (!path.isAbsolute(value) || value.includes('\0')) throw new Error(`${name} must be an absolute file path.`); + return value; +} + +/** No imports of contracts, MQTT or production services: also safe in the agent. */ +export function roleConfig(env: NodeJS.ProcessEnv = process.env): RoleConfig { + const role = env.CONSOLE_ROLE ?? 'standalone'; + if (role !== 'standalone' && role !== 'central' && role !== 'gateway') throw new Error('CONSOLE_ROLE must be standalone, central or gateway.'); + // Opt-in settings cannot break an unchanged standalone installation. + if (role === 'standalone') return { role, development: false, decisionTimeoutMs: 8000, recoveryHealthyMs: 15000, queueLimit: 10000, trustedProxies: [] }; + const development = env.CENTRAL_ALLOW_INSECURE_DEVELOPMENT === 'true'; + if (env.CENTRAL_ALLOW_INSECURE_DEVELOPMENT !== undefined && !['true', 'false'].includes(env.CENTRAL_ALLOW_INSECURE_DEVELOPMENT)) { + throw new Error('CENTRAL_ALLOW_INSECURE_DEVELOPMENT must be true or false.'); + } + const centralUrl = env.CENTRAL_URL; + if (centralUrl !== undefined) { + try { + const url = new URL(centralUrl); + if (url.username || url.password || url.hash || url.search || url.pathname !== '/' || + (url.protocol !== 'wss:' && !(development && url.protocol === 'ws:'))) throw new Error(); + } catch { throw new Error('CENTRAL_URL must be a wss origin without credentials, query or path. Plain ws requires explicit development mode.'); } + } + const trustedProxies = (env.CENTRAL_TRUSTED_PROXIES || '').split(',').map(value => value.trim()).filter(Boolean); + if (trustedProxies.length > 16 || trustedProxies.some(value => !isIP(value))) throw new Error('CENTRAL_TRUSTED_PROXIES must list at most 16 explicit IP addresses.'); + return { role, development, centralUrl, trustedProxies, + credentialPath: filePath(env, 'AGENT_CREDENTIAL_PATH'), + fallbackSecretPath: filePath(env, 'FALLBACK_SECRET_PATH'), + decisionTimeoutMs: integer(env, 'CENTRAL_DECISION_TIMEOUT_MS', 8000, 100, 120000), + recoveryHealthyMs: integer(env, 'CENTRAL_RECOVERY_HEALTHY_MS', 15000, 100, 300000), + queueLimit: integer(env, 'AGENT_QUEUE_LIMIT', 10000, 1, 1000000) }; +} + +export function requireAgentConfig(env: NodeJS.ProcessEnv = process.env): RoleConfig & { centralUrl: string; credentialPath: string; fallbackSecretPath: string } { + const config = roleConfig(env); + if (config.role !== 'gateway' || !config.centralUrl || !config.credentialPath || !config.fallbackSecretPath) { + throw new Error('The agent requires gateway role, CENTRAL_URL, AGENT_CREDENTIAL_PATH and FALLBACK_SECRET_PATH.'); + } + return { ...config, centralUrl: config.centralUrl, credentialPath: config.credentialPath, fallbackSecretPath: config.fallbackSecretPath }; +} diff --git a/src/central/destinations.ts b/src/central/destinations.ts new file mode 100644 index 0000000..d92fd26 --- /dev/null +++ b/src/central/destinations.ts @@ -0,0 +1,74 @@ +import { isIP } from 'net'; +import { lookup } from 'dns/promises'; + +export type AddressClass = 'public' | 'local' | 'blocked'; +export type ResolvedTarget = { hostname: string; address: string; family: 4 | 6; classification: AddressClass }; +export type Resolver = (host: string) => Promise>; + +/** WHATWG URL normalization covers decimal, octal and hex IPv4 spellings. Zone + * identifiers are refused rather than allowing interface-specific routing. */ +export function normalizeHost(input: string): string { + if (!input || input.length > 253 || /[%\s/@?#\\\x00-\x1f]/.test(input)) throw new Error('Invalid destination host.'); + const raw = input.startsWith('[') && input.endsWith(']') ? input.slice(1, -1) : input; + const parsed = new URL(`http://${raw.includes(':') ? `[${raw}]` : raw}/`); + if (parsed.port || parsed.username || parsed.password) throw new Error('Host must not include a port or credentials.'); + return parsed.hostname.replace(/^\[|\]$/g, '').replace(/\.$/, '').toLowerCase(); +} +function ipv6Parts(address: string): number[] { + const [left, right] = address.split('::'); + const a = left ? left.split(':') : [], b = right ? right.split(':') : []; + const expanded = right === undefined ? a : [...a, ...Array(8 - a.length - b.length).fill('0'), ...b]; + return expanded.map(part => parseInt(part, 16)); +} +export function classifyAddress(input: string): AddressClass { + const address = normalizeHost(input); + const family = isIP(address); + if (!family) throw new Error('Destination classification requires an IP address.'); + if (family === 4) { + const [a, b, c, d] = address.split('.').map(Number); + if ((a === 169 && b === 254 && c === 169 && d === 254) || + (a === 100 && b === 100 && c === 100 && d === 200) || a === 0 || a >= 224 || (a === 255 && b === 255)) return 'blocked'; + if (a === 10 || a === 127 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || + (a === 169 && b === 254) || (a === 100 && b >= 64 && b <= 127)) return 'local'; + // Non-routable/documentation ranges cannot be used to escape local classification. + if ((a === 192 && b === 0) || (a === 198 && (b === 18 || b === 19)) || + (a === 198 && b === 51 && c === 100) || (a === 203 && b === 0 && c === 113)) return 'blocked'; + return 'public'; + } + const words = ipv6Parts(address); + if (words.slice(0, 5).every(v => v === 0) && words[5] === 0xffff) { + return classifyAddress(`${words[6] >> 8}.${words[6] & 255}.${words[7] >> 8}.${words[7] & 255}`); + } + if (address === 'fd00:ec2::254' || address === '::' || (words[0] & 0xff00) === 0xff00) return 'blocked'; + if (address === '::1' || (words[0] & 0xfe00) === 0xfc00 || (words[0] & 0xffc0) === 0xfe80) return 'local'; + // Translation/transition forms can embed private IPv4 destinations; refuse + // them instead of treating them as normal public IPv6 addresses. + if ((words[0] === 0x64 && words[1] === 0xff9b) || words[0] === 0x2002 || + (words[0] === 0x2001 && (words[1] === 0 || words[1] === 0xdb8)) || words[0] < 0x2000 || words[0] >= 0x4000) return 'blocked'; + return 'public'; +} + +export async function resolveTarget(input: string, resolve: Resolver = host => lookup(host, { all: true, verbatim: true })): Promise { + const hostname = normalizeHost(input); + const literal = isIP(hostname); + const addresses = literal ? [{ address: hostname, family: literal }] : await resolve(hostname); + if (!addresses.length || addresses.length > 32) throw new Error('Destination did not resolve safely.'); + const classified = addresses.map(record => ({ hostname, address: normalizeHost(record.address), family: record.family, + classification: classifyAddress(record.address) })); + if (classified.some(value => value.classification === 'blocked' || ![4, 6].includes(value.family))) throw new Error('Destination is not permitted.'); + // Mixed public/private DNS answers are ambiguous and cannot authorize a public route. + if (new Set(classified.map(value => value.classification)).size !== 1) throw new Error('Mixed public and private DNS answers are not permitted.'); + const target = classified[0]; + if (hostname === 'localhost' || hostname.endsWith('.localhost') || /\.(local|lan)$/.test(hostname)) target.classification = 'local'; + return { ...target, family: target.family as 4 | 6 }; +} + +export type BrowsingContext = { pageClass: 'public' | 'local' | 'none'; userNavigation: boolean; topLevel: boolean }; +export function destinationRoute(role: 'standalone' | 'gateway' | 'central', target: ResolvedTarget, context: BrowsingContext, gateway?: string): 'internet' | 'local' | 'agent' { + if (target.classification === 'blocked') throw new Error('Destination is not permitted.'); + if (target.classification === 'public') return 'internet'; + if (!(context.userNavigation && context.topLevel) && context.pageClass !== 'local') throw new Error('Public pages cannot access private destinations.'); + if (role !== 'central') return 'local'; + if (!gateway) throw new Error('Select an online gateway before opening a local destination.'); + return 'agent'; +} diff --git a/src/central/identity-store.ts b/src/central/identity-store.ts new file mode 100644 index 0000000..4719252 --- /dev/null +++ b/src/central/identity-store.ts @@ -0,0 +1,154 @@ +import Database from 'better-sqlite3'; +import { randomUUID } from 'crypto'; +import { hashSecret, newSecret } from './secrets'; + +export type AuditAction = 'login-success' | 'login-failure' | 'logout' | 'enrolment-created' | 'enrolled' | + 'credential-rotated' | 'credential-rotation-acknowledged' | 'credential-revoked' | + 'terminal-start' | 'terminal-end' | 'browser-start' | 'browser-end' | 'state-downlink' | 'update-status'; +export interface GatewayIdentity { id: string; name: string; revoked: boolean; lastHeartbeat: number | null; version: string | null } +export interface UserIdentity { id: string; username: string; passwordHash: string } +export interface SessionIdentity { id: string; username: string; expires: number } +export interface IdentityStore { + createGateway(name: string, actor: string): GatewayIdentity; + gateways(): GatewayIdentity[]; + enrollment(gateway: string, actor: string, ttlMs?: number): string; + exchange(token: string): { gateway: string; credential: string } | null; + authenticateAgent(credential: string): string | null; + rotate(gateway: string, actor: string): string; + acknowledgeRotation(gateway: string, credential: string): boolean; + revoke(gateway: string, actor: string): void; + addUser(username: string, passwordHash: string): void; + user(username: string): UserIdentity | null; + createSession(user: string, ttlMs?: number): string; + session(token: string): SessionIdentity | null; + endSession(token: string): void; + audit(actor: string, action: AuditAction, gateway?: string, subject?: string): void; + close(): void; +} + +/** SQLite WAL is sufficient for the first single central process. The interface + * keeps credential/session operations independent of a future server database. + * Secrets only leave this class on creation; persisted material is always hashed. */ +export class SqliteIdentityStore implements IdentityStore { + private db: Database.Database; + constructor(filename: string, private now: () => number = Date.now) { + this.db = new Database(filename); + this.db.pragma('journal_mode = WAL'); + this.db.pragma('foreign_keys = ON'); + this.db.pragma('busy_timeout = 5000'); + this.db.transaction(() => this.db.exec(` + CREATE TABLE IF NOT EXISTS central_schema (version INTEGER PRIMARY KEY); + CREATE TABLE IF NOT EXISTS central_gateways ( + id TEXT PRIMARY KEY, name TEXT NOT NULL, credentialHash TEXT UNIQUE, + previousHash TEXT UNIQUE, previousUntil INTEGER, revoked INTEGER NOT NULL DEFAULT 0, + lastHeartbeat INTEGER, version TEXT); + CREATE TABLE IF NOT EXISTS central_enrollments ( + tokenHash TEXT PRIMARY KEY, gateway TEXT NOT NULL REFERENCES central_gateways(id), + expires INTEGER NOT NULL, consumed INTEGER NOT NULL DEFAULT 0); + CREATE TABLE IF NOT EXISTS central_users ( + id TEXT PRIMARY KEY, username TEXT NOT NULL UNIQUE, passwordHash TEXT NOT NULL); + CREATE TABLE IF NOT EXISTS central_sessions ( + tokenHash TEXT PRIMARY KEY, userId TEXT NOT NULL REFERENCES central_users(id), expires INTEGER NOT NULL); + CREATE INDEX IF NOT EXISTS central_session_expiry ON central_sessions(expires); + CREATE TABLE IF NOT EXISTS central_audit ( + id INTEGER PRIMARY KEY, timestamp INTEGER NOT NULL, actor TEXT NOT NULL, + action TEXT NOT NULL, gateway TEXT, subject TEXT); + INSERT OR IGNORE INTO central_schema VALUES (1); + `))(); + } + createGateway(name: string, actor: string): GatewayIdentity { + if (!name.trim() || name.length > 100 || /[\x00-\x1f]/.test(name)) throw new Error('Gateway name must contain 1–100 printable characters.'); + const id = randomUUID(); + this.db.prepare('INSERT INTO central_gateways (id,name) VALUES (?,?)').run(id, name.trim()); + this.audit(actor, 'enrolment-created', id); + return { id, name: name.trim(), revoked: false, lastHeartbeat: null, version: null }; + } + gateways(): GatewayIdentity[] { + return (this.db.prepare('SELECT id,name,revoked,lastHeartbeat,version FROM central_gateways ORDER BY name').all() as + Array & { revoked: number }>).map(row => ({ ...row, revoked: !!row.revoked })); + } + enrollment(gateway: string, actor: string, ttlMs = 10 * 60000): string { + if (!Number.isInteger(ttlMs) || ttlMs < 1000 || ttlMs > 3600000) throw new Error('Invalid enrollment lifetime.'); + const token = newSecret(); + this.db.transaction(() => { + const row = this.db.prepare('SELECT credentialHash,revoked FROM central_gateways WHERE id=?').get(gateway) as { credentialHash: string | null; revoked: number } | undefined; + if (!row || (row.credentialHash && !row.revoked)) throw new Error('Revoke an enrolled gateway before replacing its identity.'); + this.db.prepare('DELETE FROM central_enrollments WHERE gateway=? OR expires<=?').run(gateway, this.now()); + this.db.prepare('INSERT INTO central_enrollments (tokenHash,gateway,expires) VALUES (?,?,?)').run(hashSecret(token), gateway, this.now() + ttlMs); + this.audit(actor, 'enrolment-created', gateway); + })(); + return token; + } + exchange(token: string): { gateway: string; credential: string } | null { + if (!/^[A-Za-z0-9_-]{43}$/.test(token)) return null; + return this.db.transaction(() => { + const row = this.db.prepare('SELECT gateway FROM central_enrollments WHERE tokenHash=? AND consumed=0 AND expires>?').get(hashSecret(token), this.now()) as { gateway: string } | undefined; + if (!row) return null; + const credential = newSecret(); + this.db.prepare('UPDATE central_enrollments SET consumed=1 WHERE tokenHash=?').run(hashSecret(token)); + this.db.prepare('UPDATE central_gateways SET credentialHash=?, previousHash=NULL,previousUntil=NULL,revoked=0 WHERE id=?').run(hashSecret(credential), row.gateway); + this.audit('agent', 'enrolled', row.gateway); + return { gateway: row.gateway, credential }; + })(); + } + authenticateAgent(credential: string): string | null { + if (!/^[A-Za-z0-9_-]{43}$/.test(credential)) return null; + const digest = hashSecret(credential); + const row = this.db.prepare(`SELECT id FROM central_gateways WHERE revoked=0 AND + (credentialHash=? OR (previousHash=? AND previousUntil>?))`).get(digest, digest, this.now()) as { id: string } | undefined; + return row?.id || null; + } + rotate(gateway: string, actor: string): string { + const credential = newSecret(); + this.db.transaction(() => { + const result = this.db.prepare(`UPDATE central_gateways SET previousHash=credentialHash,previousUntil=?,credentialHash=? + WHERE id=? AND revoked=0 AND credentialHash IS NOT NULL AND (previousHash IS NULL OR previousUntil<=?)`) + .run(this.now() + 120000, hashSecret(credential), gateway, this.now()); + if (!result.changes) throw new Error('Gateway cannot rotate now; another rotation may be pending.'); + this.audit(actor, 'credential-rotated', gateway); + })(); + return credential; + } + acknowledgeRotation(gateway: string, credential: string): boolean { + return this.db.transaction(() => { + const result = this.db.prepare('UPDATE central_gateways SET previousHash=NULL,previousUntil=NULL WHERE id=? AND credentialHash=? AND revoked=0') + .run(gateway, hashSecret(credential)); + if (result.changes) this.audit('agent', 'credential-rotation-acknowledged', gateway); + return !!result.changes; + })(); + } + revoke(gateway: string, actor: string): void { + this.db.transaction(() => { + this.db.prepare('UPDATE central_gateways SET revoked=1,credentialHash=NULL,previousHash=NULL,previousUntil=NULL WHERE id=?').run(gateway); + this.db.prepare('DELETE FROM central_enrollments WHERE gateway=?').run(gateway); + this.audit(actor, 'credential-revoked', gateway); + })(); + // The connection registry must synchronously close this gateway's live link. + } + addUser(username: string, passwordHash: string): void { + if (!/^[A-Za-z0-9_.@-]{1,100}$/.test(username) || !/^scrypt\$[a-f0-9]{32}\$[a-f0-9]{128}$/.test(passwordHash)) throw new Error('Invalid user or password hash.'); + this.db.prepare('INSERT INTO central_users VALUES (?,?,?)').run(randomUUID(), username, passwordHash); + } + user(username: string): UserIdentity | null { + return this.db.prepare('SELECT * FROM central_users WHERE username=?').get(username) as UserIdentity | undefined || null; + } + createSession(user: string, ttlMs = 8 * 3600000): string { + if (!Number.isInteger(ttlMs) || ttlMs < 1000 || ttlMs > 86400000) throw new Error('Invalid session lifetime.'); + const token = newSecret(); + this.db.prepare('DELETE FROM central_sessions WHERE expires<=?').run(this.now()); + this.db.prepare('INSERT INTO central_sessions VALUES (?,?,?)').run(hashSecret(token), user, this.now() + ttlMs); + return token; + } + session(token: string): SessionIdentity | null { + if (!/^[A-Za-z0-9_-]{43}$/.test(token)) return null; + return this.db.prepare(`SELECT u.id,u.username,s.expires FROM central_sessions s + JOIN central_users u ON s.userId=u.id WHERE s.tokenHash=? AND s.expires>?`).get(hashSecret(token), this.now()) as SessionIdentity | undefined || null; + } + endSession(token: string): void { this.db.prepare('DELETE FROM central_sessions WHERE tokenHash=?').run(hashSecret(token)); } + audit(actor: string, action: AuditAction, gateway?: string, subject?: string): void { + // Callers supply identity IDs and fixed statuses only, never request bodies. + if ([actor, gateway, subject].some(value => value !== undefined && (value.length > 128 || /[\x00-\x1f]/.test(value)))) throw new Error('Invalid audit identity.'); + this.db.prepare('INSERT INTO central_audit(timestamp,actor,action,gateway,subject) VALUES (?,?,?,?,?)').run(this.now(), actor, action, gateway ?? null, subject ?? null); + } + close(): void { this.db.close(); } +} diff --git a/src/central/protocol.ts b/src/central/protocol.ts new file mode 100644 index 0000000..c805042 --- /dev/null +++ b/src/central/protocol.ts @@ -0,0 +1,102 @@ +/** Versioned, bounded vocabulary. There is deliberately no command/script RPC. */ +export const MAX_MESSAGE_BYTES = 65536; +export const MAX_TUNNEL_CHUNK = 16384; +export type TunnelPurpose = 'ssh' | 'chirpstack' | 'browser'; +export type Health = { version: string; uptime: number; mqtt: 'connected' | 'disconnected' | 'connecting'; + fallback: boolean; queueDepth: number; updatesEnabled: boolean; lastError: 'none' | 'mqtt' | 'central' | 'local' | 'storage' | 'update' }; +export type UplinkEvent = { fPort: 2; deviceInfo: { devEui: string; applicationId: string }; data?: string; dataHex?: string; dataEncoding?: 'hex' | 'base64'; deduplicationId?: string; fCnt?: number; time?: string }; +export type AgentMessage = + | { v: 1; type: 'health'; health: Health } + | { v: 1; type: 'uplink'; id: string; event: UplinkEvent } + | { v: 1; type: 'result'; id: string; outcome: 'enqueued' | 'locally-handled' | 'rejected' | 'uncertain' } + | { v: 1; type: 'rotated' } + | { v: 1; type: 'update-progress'; id: string; status: 'queued' | 'downloading' | 'verifying' | 'restarting' | 'succeeded' | 'failed' | 'rolled-back' } + | TunnelMessage | PingMessage; +export type CentralMessage = + | { v: 1; type: 'decision'; id: string; devEui: string; fPort: 2; confirmed: false; data: string } + | { v: 1; type: 'rotate'; credential: string } + | { v: 1; type: 'update'; id: string; image: string } + | { v: 1; type: 'tunnel-open'; id: string; purpose: TunnelPurpose; host: string; port: number } + | TunnelMessage | PingMessage; +export type PingMessage = { v: 1; type: 'ping' | 'pong'; id: string }; +export type TunnelMessage = + | { v: 1; type: 'tunnel-ready'; id: string } + | { v: 1; type: 'tunnel-data'; id: string; data: string } + | { v: 1; type: 'tunnel-credit'; id: string; bytes: number } + | { v: 1; type: 'tunnel-close'; id: string; reason: 'closed' | 'refused' | 'timeout' | 'limit' | 'disconnected' | 'error' }; + +const object = (value: unknown): value is Record => typeof value === 'object' && value !== null && !Array.isArray(value); +const integer = (v: unknown, min: number, max: number): v is number => Number.isSafeInteger(v) && Number(v) >= min && Number(v) <= max; +const id = (v: unknown): v is string => typeof v === 'string' && /^[a-zA-Z0-9_-]{1,128}$/.test(v); +const isOneOf = (v: unknown, allowed: readonly unknown[]): boolean => allowed.includes(v); +const exact = (v: Record, keys: string[]): boolean => Object.keys(v).length === keys.length && keys.every(key => Object.prototype.hasOwnProperty.call(v, key)); +function base64(value: unknown, min: number, max: number): value is string { + if (typeof value !== 'string' || value.length > Math.ceil(max / 3) * 4 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) return false; + const bytes = Buffer.from(value, 'base64'); + return bytes.length >= min && bytes.length <= max && bytes.toString('base64') === value; +} +function stateFrame(value: unknown): value is string { + if (!base64(value, 9, 13)) return false; + const bytes = Buffer.from(value, 'base64'); + if (![9, 13].includes(bytes.length) || bytes[0] > 1) return false; + return Number.isFinite(bytes.readFloatBE(bytes.length - 8)) && Number.isFinite(bytes.readFloatBE(bytes.length - 4)); +} +export function validImageDigest(value: unknown): value is string { + return typeof value === 'string' && value.length < 400 && /^ghcr\.io\/[a-z0-9][a-z0-9_.-]*\/[a-z0-9][a-z0-9_./-]*@sha256:[a-f0-9]{64}$/.test(value) && !value.includes('..'); +} +function validUplink(value: unknown): value is UplinkEvent { + if (!object(value) || value.fPort !== 2 || !object(value.deviceInfo)) return false; + const info = value.deviceInfo; + if (typeof info.devEui !== 'string' || !/^[a-fA-F0-9]{16}$/.test(info.devEui) || + typeof info.applicationId !== 'string' || !/^[a-fA-F0-9]{8}(?:-[a-fA-F0-9]{4}){3}-[a-fA-F0-9]{12}$/.test(info.applicationId)) return false; + if (value.deduplicationId !== undefined && !id(value.deduplicationId)) return false; + if (value.fCnt !== undefined && !integer(value.fCnt, 0, 0xffffffff)) return false; + if (value.time !== undefined && (typeof value.time !== 'string' || value.time.length > 40 || !Number.isFinite(Date.parse(value.time)))) return false; + // Use the original transport decoder, without alphabet heuristics or a second wire format. + try { + const bytes = requirePayload(value).bytes; + return [74, 106, 112].includes(bytes.length); + } catch { return false; } +} +import { uplinkPayload as requirePayload } from '../lib/uplink-payload'; + +export function parseMessage(input: Buffer | string, direction: 'agent'): AgentMessage; +export function parseMessage(input: Buffer | string, direction: 'central'): CentralMessage; +export function parseMessage(input: Buffer | string, direction: 'agent' | 'central'): AgentMessage | CentralMessage { + if (Buffer.byteLength(input) > MAX_MESSAGE_BYTES) throw new Error('Agent message exceeds the size limit.'); + let value: unknown; + try { value = JSON.parse(input.toString()); } catch { throw new Error('Invalid agent message.'); } + if (!object(value) || value.v !== 1 || typeof value.type !== 'string') throw new Error('Invalid agent protocol version or envelope.'); + const keys = (...fields: string[]) => exact(value, ['v', 'type', ...fields]); + let valid = false; + switch (value.type) { + case 'ping': case 'pong': case 'tunnel-ready': valid = keys('id') && id(value.id); break; + case 'tunnel-data': valid = keys('id', 'data') && id(value.id) && base64(value.data, 1, MAX_TUNNEL_CHUNK); break; + case 'tunnel-credit': valid = keys('id', 'bytes') && id(value.id) && integer(value.bytes, 1, 65536); break; + case 'tunnel-close': valid = keys('id', 'reason') && id(value.id) && isOneOf(value.reason, ['closed', 'refused', 'timeout', 'limit', 'disconnected', 'error']); break; + case 'tunnel-open': valid = direction === 'central' && keys('id', 'purpose', 'host', 'port') && id(value.id) && + isOneOf(value.purpose, ['ssh', 'chirpstack', 'browser']) && typeof value.host === 'string' && + value.host.length > 0 && value.host.length <= 253 && !/[\s\x00-\x1f/@?#%]/.test(value.host) && integer(value.port, 1, 65535); break; + case 'decision': valid = direction === 'central' && keys('id', 'devEui', 'fPort', 'confirmed', 'data') && id(value.id) && + typeof value.devEui === 'string' && /^[a-fA-F0-9]{16}$/.test(value.devEui) && value.fPort === 2 && value.confirmed === false && + stateFrame(value.data); break; + case 'rotate': valid = direction === 'central' && keys('credential') && typeof value.credential === 'string' && /^[A-Za-z0-9_-]{43}$/.test(value.credential); break; + case 'rotated': valid = direction === 'agent' && keys(); break; + case 'update': valid = direction === 'central' && keys('id', 'image') && id(value.id) && validImageDigest(value.image); break; + case 'update-progress': valid = direction === 'agent' && keys('id', 'status') && id(value.id) && + isOneOf(value.status, ['queued', 'downloading', 'verifying', 'restarting', 'succeeded', 'failed', 'rolled-back']); break; + case 'result': valid = direction === 'agent' && keys('id', 'outcome') && id(value.id) && isOneOf(value.outcome, ['enqueued', 'locally-handled', 'rejected', 'uncertain']); break; + case 'uplink': valid = direction === 'agent' && keys('id', 'event') && id(value.id) && validUplink(value.event); break; + case 'health': { + const h = value.health; + valid = direction === 'agent' && keys('health') && object(h) && exact(h, ['version', 'uptime', 'mqtt', 'fallback', 'queueDepth', 'updatesEnabled', 'lastError']) && + typeof h.version === 'string' && /^[\w.+-]{1,80}$/.test(h.version) && integer(h.uptime, 0, Number.MAX_SAFE_INTEGER) && + isOneOf(h.mqtt, ['connected', 'disconnected', 'connecting']) && typeof h.fallback === 'boolean' && integer(h.queueDepth, 0, 1000000) && + typeof h.updatesEnabled === 'boolean' && isOneOf(h.lastError, ['none', 'mqtt', 'central', 'local', 'storage', 'update']); + break; + } + } + if (!valid) throw new Error('Unknown or invalid agent message.'); + // All discriminants and fields were checked above, including direction. + return value as AgentMessage | CentralMessage; +} diff --git a/src/central/secrets.ts b/src/central/secrets.ts new file mode 100644 index 0000000..6ffc974 --- /dev/null +++ b/src/central/secrets.ts @@ -0,0 +1,49 @@ +import { randomBytes, createHash, timingSafeEqual, scrypt } from 'crypto'; +import fs from 'fs'; +import path from 'path'; + +export const newSecret = (): string => randomBytes(32).toString('base64url'); +export const hashSecret = (secret: string): string => createHash('sha256').update(secret).digest('hex'); +export function equalSecretHash(secret: string, expected: string): boolean { + if (!/^[a-f0-9]{64}$/.test(expected)) return false; + return timingSafeEqual(Buffer.from(hashSecret(secret), 'hex'), Buffer.from(expected, 'hex')); +} +const derive = (password: string, salt: string): Promise => new Promise((resolve, reject) => + scrypt(password, salt, 64, { N: 16384, r: 8, p: 1 }, (error, value) => error ? reject(error) : resolve(value))); +export async function hashPassword(password: string): Promise { + if (password.length < 16 || Buffer.byteLength(password) > 1024) throw new Error('Central passwords must contain 16–1024 bytes.'); + const salt = randomBytes(16).toString('hex'); + return `scrypt$${salt}$${(await derive(password, salt)).toString('hex')}`; +} +export async function verifyPassword(password: unknown, stored: string): Promise { + if (typeof password !== 'string' || Buffer.byteLength(password) > 1024) return false; + const match = /^scrypt\$([a-f0-9]{32})\$([a-f0-9]{128})$/.exec(stored); + if (!match) return false; + return timingSafeEqual(await derive(password, match[1]), Buffer.from(match[2], 'hex')); +} + +/** Refuse permissive files and symlinks; atomic writes never print a credential. */ +export function readOwnerSecret(filename: string): string { + const fd = fs.openSync(filename, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW); + try { + const stat = fs.fstatSync(fd); + if (!stat.isFile() || stat.size > 4096 || (stat.mode & 0o077) || + (typeof process.getuid === 'function' && stat.uid !== process.getuid())) throw new Error('Secret file must be owner-only and owned by this process user.'); + const value = fs.readFileSync(fd, 'utf8').trim(); + if (value.length < 32 || value.length > 512 || /\s/.test(value)) throw new Error('Secret file has an invalid format.'); + return value; + } finally { fs.closeSync(fd); } +} +export function writeOwnerSecret(filename: string, value: string): void { + if (value.length < 32 || value.length > 512 || /\s/.test(value)) throw new Error('Credential format is invalid.'); + const directory = path.dirname(filename); + fs.mkdirSync(directory, { recursive: true, mode: 0o700 }); + const temp = path.join(directory, `.credential-${randomBytes(12).toString('hex')}`); + const fd = fs.openSync(temp, 'wx', 0o600); + try { fs.writeFileSync(fd, value); fs.fsyncSync(fd); } finally { fs.closeSync(fd); } + try { + fs.renameSync(temp, filename); + const directoryFd = fs.openSync(directory, 'r'); + try { fs.fsyncSync(directoryFd); } finally { fs.closeSync(directoryFd); } + } catch { fs.rmSync(temp, { force: true }); throw new Error('Could not persist credential.'); } +} diff --git a/tests/services/agent-protocol.test.ts b/tests/services/agent-protocol.test.ts new file mode 100644 index 0000000..6d34601 --- /dev/null +++ b/tests/services/agent-protocol.test.ts @@ -0,0 +1,45 @@ +import { parseMessage, MAX_MESSAGE_BYTES, MAX_TUNNEL_CHUNK } from '../../src/central/protocol'; +const decode = (value: unknown, direction: 'agent' | 'central' = 'central') => direction === 'agent' + ? parseMessage(JSON.stringify(value), 'agent') : parseMessage(JSON.stringify(value), 'central'); + +test.each(['exec','shell','enqueue-command','script','__proto__','update-compose'])('rejects unsupported vocabulary %s', type => { + expect(() => decode({v:1,type,id:'x',command:'not executed'})).toThrow(); +}); +test('rejects invalid versions, primitives, extra keys, oversized messages and chunks', () => { + for (const value of [null,[],1,{}, {v:2,type:'ping',id:'x'}, {v:1,type:'ping',id:'x',extra:true}]) expect(()=>decode(value)).toThrow(); + expect(()=>parseMessage('x'.repeat(MAX_MESSAGE_BYTES+1),'agent')).toThrow('size limit'); + expect(()=>parseMessage('{','agent')).toThrow(); + expect(()=>decode({v:1,type:'tunnel-data',id:'x',data:Buffer.alloc(MAX_TUNNEL_CHUNK+1).toString('base64')})).toThrow(); +}); +test('state replies only permit exact billing frames on FPort 2, never generic meter commands', () => { + const reply={v:1,type:'decision',id:'event-1',devEui:'0102030405060708',fPort:2,confirmed:false,data:Buffer.alloc(9).toString('base64')}; + expect(decode(reply)).toEqual(reply); + for(const fPort of [3,4,200,201,202]) expect(()=>decode({...reply,fPort})).toThrow(); + for(const length of [0,1,2,3,8,10,11,12,14]) expect(()=>decode({...reply,data:Buffer.alloc(length).toString('base64')})).toThrow(); + const invalidState=Buffer.alloc(9);invalidState[0]=0x1b; + expect(()=>decode({...reply,data:invalidState.toString('base64')})).toThrow(); + invalidState[0]=0;invalidState.writeFloatBE(NaN,1); + expect(()=>decode({...reply,data:invalidState.toString('base64')})).toThrow(); + expect(()=>decode(reply,'agent')).toThrow(); +}); +test('agent forwards only FPort 2 and distinguishes Base64 from explicitly marked hex', () => { + const bytes=Buffer.alloc(74);bytes.writeUInt32BE(1); + const event={fPort:2,deviceInfo:{devEui:'0102030405060708',applicationId:'11111111-1111-4111-8111-111111111111'},data:bytes.toString('base64'),deduplicationId:'event-1',fCnt:2}; + const message={v:1,type:'uplink',id:'event-1',event}; + expect(decode(message,'agent')).toEqual(message); + expect(decode({...message,event:{...event,dataHex:bytes.toString('hex')}},'agent')).toMatchObject({type:'uplink'}); + for(const fPort of [3,4,200,201,202,undefined]) expect(()=>decode({...message,event:{...event,fPort}},'agent')).toThrow(); + expect(()=>decode({...message,event:{...event,data:'not base64'}},'agent')).toThrow(); + expect(()=>decode(message,'central')).toThrow(); +}); +test('updates accept digest references only; shell injection and arbitrary URLs are refused', () => { + const image='ghcr.io/fluxion9/console@sha256:'+'a'.repeat(64); + expect(decode({v:1,type:'update',id:'job',image})).toMatchObject({image}); + for(const bad of ['https://example.com/script','ghcr.io/fluxion9/console:main',image+';sh',image+'\n', 'ghcr.io/fluxion9/../console@sha256:'+'a'.repeat(64)]) expect(()=>decode({v:1,type:'update',id:'job',image:bad})).toThrow(); +}); +test('tunnels carry a fixed purpose and reject invalid hosts, ports and credits', () => { + const message={v:1,type:'tunnel-open',id:'tunnel',purpose:'ssh',host:'127.0.0.1',port:22}; + expect(decode(message)).toEqual(message); + for(const override of [{purpose:'docker'}, {host:'host@victim'}, {host:'fe80::1%eth0'}, {port:0}, {port:65536}]) expect(()=>decode({...message,...override})).toThrow(); + for(const bytes of [-1,0,65537,1.1]) expect(()=>decode({v:1,type:'tunnel-credit',id:'tunnel',bytes})).toThrow(); +}); diff --git a/tests/services/central-auth.test.ts b/tests/services/central-auth.test.ts new file mode 100644 index 0000000..8227ef0 --- /dev/null +++ b/tests/services/central-auth.test.ts @@ -0,0 +1,62 @@ +import express from 'express'; +import { IncomingMessage, ServerResponse } from 'http'; +import { Socket } from 'net'; +import { CentralAuth } from '../../src/central/auth'; +import { SqliteIdentityStore } from '../../src/central/identity-store'; +import { hashPassword } from '../../src/central/secrets'; + +// In-process HTTP injection: no listening port, gateway or upstream service. +function request(app: ReturnType, url: string, options: { method?: string; headers?: Record; body?: string } = {}) { + const socket = new Socket(); + Object.defineProperty(socket, 'remoteAddress', { value:'127.0.0.1' }); + const req=new IncomingMessage(socket); + req.url=url;req.method=options.method || 'GET';req.headers={host:'console.example',...options.headers}; + if(options.body) {req.headers['content-type']='application/x-www-form-urlencoded';req.headers['content-length']=String(Buffer.byteLength(options.body));} + req.push(options.body || null);if(options.body)req.push(null); + const res=new ServerResponse(req); + return new Promise<{status:number;headers:ReturnType;body:string}>(resolve=>{ + res.end=((chunk?: unknown)=>{resolve({status:res.statusCode,headers:res.getHeaders(),body:typeof chunk==='string'?chunk:Buffer.isBuffer(chunk)?chunk.toString():''});socket.destroy();return res;}) as typeof res.end; + app(req,res); + }); +} +let store:SqliteIdentityStore, auth:CentralAuth, app:ReturnType; +beforeEach(async()=>{ + store=new SqliteIdentityStore(':memory:'); + store.addUser('operator',await hashPassword('test-only-long-password')); + auth=new CentralAuth(store,{development:false,trustedProxies:['127.0.0.1']}); + app=express();auth.mount(app);app.use((_req,res)=>res.json({ok:true})); +}); +afterEach(()=>store.close()); +const secure={'x-forwarded-proto':'https'}; +test('every central app route is protected, including static assets, proxies and health',async()=>{ + for(const url of ['/','/healthz','/api/actions/streamr/publish-now','/chirpstack/','/js/desktop.js','/api/gateways','/api/browser']) { + const result=await request(app,url,{headers:secure});expect(result.status).toBe(url==='/'?303:401); + } + expect((await request(app,'/login',{headers:secure})).status).toBe(200); + expect((await request(app,'/login')).status).toBe(400); +}); +test('login creates a secure HttpOnly same-site cookie; logout invalidates it',async()=>{ + const logged=await request(app,'/login',{method:'POST',headers:{...secure,origin:'https://console.example'},body:'username=operator&password=test-only-long-password'}); + expect(logged.status).toBe(303); + const cookie=String(logged.headers['set-cookie']); + expect(cookie).toMatch(/^__Host-console_session=/);expect(cookie).toContain('HttpOnly');expect(cookie).toContain('SameSite=Strict');expect(cookie).toContain('Secure'); + const headers={...secure,cookie:cookie.split(';')[0]}; + expect((await request(app,'/api/gateways',{headers})).status).toBe(200); + expect((await request(app,'/logout',{method:'POST',headers:{...headers,origin:'https://console.example'}})).status).toBe(303); + expect((await request(app,'/api/gateways',{headers})).status).toBe(401); +}); +test('foreign origins and forged forwarding headers cannot bypass central authentication',async()=>{ + expect((await request(app,'/login',{method:'POST',headers:{...secure,origin:'https://foreign.example'},body:'username=operator&password=test-only-long-password'})).status).toBe(403); + const untrusted=new CentralAuth(store,{development:false,trustedProxies:[]});const untrustedApp=express();untrusted.mount(untrustedApp); + expect((await request(untrustedApp,'/login',{headers:secure})).status).toBe(400); + const req=new IncomingMessage(new Socket());req.headers={origin:'https://console.example',host:'console.example'}; + expect(auth.authorize(req)).toBe(false); + req.socket.destroy(); +}); +test('bad sign-ins use generic errors, never echo secrets, and are rate limited',async()=>{ + for(let i=0;i<10;i++) { + const reply=await request(app,'/login',{method:'POST',headers:secure,body:'username=operator&password=sensitive-fixture'}); + expect(reply.status).toBe(401);expect(reply.body).not.toContain('sensitive-fixture'); + } + expect((await request(app,'/login',{method:'POST',headers:secure,body:'username=operator&password=sensitive-fixture'})).status).toBe(429); +}); diff --git a/tests/services/central-identity.test.ts b/tests/services/central-identity.test.ts new file mode 100644 index 0000000..21ba3d2 --- /dev/null +++ b/tests/services/central-identity.test.ts @@ -0,0 +1,91 @@ +import fs from 'fs'; +import os from 'os'; +import path from 'path'; +import Database from 'better-sqlite3'; +import { SqliteIdentityStore } from '../../src/central/identity-store'; +import { hashPassword, verifyPassword, writeOwnerSecret, readOwnerSecret } from '../../src/central/secrets'; +import { roleConfig, requireAgentConfig } from '../../src/central/config'; +import { RateLimit } from '../../src/central/auth'; + +let store: SqliteIdentityStore, now: number; +beforeEach(() => { now = 10000; store = new SqliteIdentityStore(':memory:', () => now); }); +afterEach(() => store.close()); +test('standalone is default and opt-in settings cannot alter its configuration', () => { + expect(roleConfig({})).toEqual(roleConfig({ CENTRAL_URL: 'invalid', AGENT_QUEUE_LIMIT: '-1' })); + expect(roleConfig({}).role).toBe('standalone'); + expect(() => roleConfig({CONSOLE_ROLE:'unknown'})).toThrow(); +}); +test('agent requires explicit opt-in and validates configuration without exposing values', () => { + expect(() => requireAgentConfig({})).toThrow(); + const config = { CONSOLE_ROLE:'gateway', CENTRAL_URL:'wss://central.example', AGENT_CREDENTIAL_PATH:'/state/credential', FALLBACK_SECRET_PATH:'/state/fallback' }; + expect(requireAgentConfig(config).decisionTimeoutMs).toBe(8000); + for(const override of [{CENTRAL_URL:'ws://central.example'}, {CENTRAL_URL:'wss://user:secret@central.example'}, {AGENT_QUEUE_LIMIT:'0'}, {CENTRAL_DECISION_TIMEOUT_MS:'NaN'}, {AGENT_CREDENTIAL_PATH:'relative'}, {CENTRAL_TRUSTED_PROXIES:'*'}]) { + expect(() => requireAgentConfig({...config,...override})).toThrow(); + } + expect(requireAgentConfig({...config,CENTRAL_URL:'ws://127.0.0.1',CENTRAL_ALLOW_INSECURE_DEVELOPMENT:'true'}).development).toBe(true); +}); +test('enrollment is single-use, expires, and cannot replace an active identity', () => { + const gateway = store.createGateway('Test gateway','admin'); + const expired = store.enrollment(gateway.id,'admin',1000); now += 1001; + expect(store.exchange(expired)).toBeNull(); + const token = store.enrollment(gateway.id,'admin'); + const identity = store.exchange(token)!; + expect(store.exchange(token)).toBeNull(); + expect(store.authenticateAgent(identity.credential)).toBe(gateway.id); + expect(store.authenticateAgent(token)).toBeNull(); + expect(() => store.enrollment(gateway.id,'admin')).toThrow(); +}); +test('rotation overlaps credentials until acknowledgment; revocation rejects both immediately', () => { + const gateway = store.createGateway('Test gateway','admin'); + const original = store.exchange(store.enrollment(gateway.id,'admin'))!; + const rotated = store.rotate(gateway.id,'admin'); + expect(store.authenticateAgent(original.credential)).toBe(gateway.id); + expect(store.authenticateAgent(rotated)).toBe(gateway.id); + expect(() => store.rotate(gateway.id,'admin')).toThrow(); + expect(store.acknowledgeRotation(gateway.id,original.credential)).toBe(false); + expect(store.acknowledgeRotation(gateway.id,rotated)).toBe(true); + expect(store.authenticateAgent(original.credential)).toBeNull(); + store.revoke(gateway.id,'admin'); + expect(store.authenticateAgent(rotated)).toBeNull(); +}); +test('rotation grace expires even when acknowledgment is lost', () => { + const g = store.createGateway('Gateway','admin'), old = store.exchange(store.enrollment(g.id,'admin'))!; + const next = store.rotate(g.id,'admin'); now += 120001; + expect(store.authenticateAgent(old.credential)).toBeNull(); + expect(store.authenticateAgent(next)).toBe(g.id); +}); +test('passwords are salted; sessions expire and logout invalidates them', async () => { + const password='fixture-password-not-a-production-secret'; + const hash=await hashPassword(password); + expect(hash).not.toContain(password); expect(await hashPassword(password)).not.toBe(hash); + expect(await verifyPassword(password,hash)).toBe(true); expect(await verifyPassword('wrong',hash)).toBe(false); + store.addUser('operator',hash); const user=store.user('operator')!; + const token=store.createSession(user.id,1000); expect(store.session(token)?.username).toBe('operator'); + now+=1001; expect(store.session(token)).toBeNull(); + const second=store.createSession(user.id); store.endSession(second);expect(store.session(second)).toBeNull(); +}); +test('credentials and enrollment secrets never appear in database or audit rows', () => { + const dir=fs.mkdtempSync(path.join(os.tmpdir(),'central-identity-')); const filename=path.join(dir,'test.db'); + const persistent=new SqliteIdentityStore(filename); + try { + const g=persistent.createGateway('Test','admin'), token=persistent.enrollment(g.id,'admin'), identity=persistent.exchange(token)!; + const inspect=new Database(filename,{readonly:true}); + const rows=JSON.stringify(['central_gateways','central_enrollments','central_audit'].map(table=>inspect.prepare(`SELECT * FROM ${table}`).all())); + inspect.close(); expect(rows).not.toContain(token);expect(rows).not.toContain(identity.credential); + } finally {persistent.close();fs.rmSync(dir,{recursive:true,force:true});} +}); +test('credential files are atomic and owner-only, permissive files and symlinks are refused', () => { + const dir=fs.mkdtempSync(path.join(os.tmpdir(),'agent-credential-'));const file=path.join(dir,'identity'); + try { + writeOwnerSecret(file,'a'.repeat(43));expect(readOwnerSecret(file)).toBe('a'.repeat(43)); + expect(fs.statSync(file).mode&0o777).toBe(0o600); + fs.chmodSync(file,0o644);expect(()=>readOwnerSecret(file)).toThrow(); + const link=path.join(dir,'link');fs.symlinkSync(file,link);expect(()=>readOwnerSecret(link)).toThrow(); + } finally {fs.rmSync(dir,{recursive:true,force:true});} +}); +test('rate limiting has bounded cardinality and recovers after expiry', () => { + const limit=new RateLimit(2,1000,2,()=>now); + expect(limit.allow('a')).toBe(true);expect(limit.allow('a')).toBe(true);expect(limit.allow('a')).toBe(false); + expect(limit.allow('b')).toBe(true);expect(limit.allow('c')).toBe(false); + now+=1001;expect(limit.allow('c')).toBe(true); +}); diff --git a/tests/services/destinations.test.ts b/tests/services/destinations.test.ts new file mode 100644 index 0000000..2b9c3c4 --- /dev/null +++ b/tests/services/destinations.test.ts @@ -0,0 +1,34 @@ +import { normalizeHost, classifyAddress, resolveTarget, destinationRoute } from '../../src/central/destinations'; + +test.each(['127.0.0.1','127.1','2130706433','0177.0.0.1','0x7f000001','[::1]','[::ffff:127.0.0.1]','[::ffff:7f00:1]', '10.0.0.1','172.16.0.1','192.168.1.1','169.254.1.1','fc00::1','fe80::1234'])('classifies local address %s', address => { + expect(classifyAddress(address)).toBe('local'); +}); +test.each(['169.254.169.254','[fd00:ec2::254]','[::ffff:169.254.169.254]','0.0.0.0','::','224.0.0.1','ff02::1','64:ff9b::a00:1','2002:7f00:1::1'])('refuses metadata, unspecified, multicast and translation address %s', address => { + expect(classifyAddress(address)).toBe('blocked'); +}); +test.each(['fe80::1%eth0','[fe80::1%25eth0]','user@127.0.0.1','localhost/path','localhost?x','127.0.0.1\\@example.com'])('rejects ambiguous host %s', address=>expect(()=>normalizeHost(address)).toThrow()); +test('pins the classified address and rejects mixed DNS answers',async()=>{ + const resolve=jest.fn().mockResolvedValueOnce([{address:'8.8.8.8',family:4}]).mockResolvedValueOnce([{address:'127.0.0.1',family:4}]); + const first=await resolveTarget('site.example',resolve); + expect(first.address).toBe('8.8.8.8');expect(first.classification).toBe('public'); + // The transport must dial first.address, never perform a second DNS lookup. + expect(resolve).toHaveBeenCalledTimes(1); + const second=await resolveTarget('site.example',resolve);expect(second.classification).toBe('local'); + await expect(resolveTarget('mixed.example',async()=>[{address:'8.8.8.8',family:4},{address:'127.0.0.1',family:4}])).rejects.toThrow('Mixed'); +}); +test('routing never directs a private request to the central host', async()=>{ + const target=await resolveTarget('127.0.0.1'); + const typed={pageClass:'public' as const,userNavigation:true,topLevel:true}; + expect(destinationRoute('standalone',target,typed)).toBe('local'); + expect(destinationRoute('gateway',target,typed)).toBe('local'); + expect(destinationRoute('central',target,typed,'gateway-1')).toBe('agent'); + expect(()=>destinationRoute('central',target,typed)).toThrow('Select'); + for(const context of [{...typed,userNavigation:false},{...typed,topLevel:false}]) expect(()=>destinationRoute('central',target,context,'gateway-1')).toThrow('Public'); + expect(destinationRoute('central',target,{pageClass:'local',userNavigation:false,topLevel:false},'gateway-1')).toBe('agent'); +}); +test('redirects must be reclassified and lose the user-navigation authorization',async()=>{ + const target=await resolveTarget('8.8.8.8'); + expect(destinationRoute('central',target,{pageClass:'public',userNavigation:false,topLevel:false})).toBe('internet'); + const redirect=await resolveTarget('127.0.0.1'); + expect(()=>destinationRoute('central',redirect,{pageClass:'public',userNavigation:false,topLevel:true},'gateway-1')).toThrow(); +}); From 1b6d8ae3b21ea851aaa579671ea48cce8aa98c32 Mon Sep 17 00:00:00 2001 From: "Isaac J. Newton" Date: Tue, 17 Nov 2026 15:54:25 +0000 Subject: [PATCH 4/9] feat: fence managed uplinks and reconcile uncertain outcomes without retries --- .gitignore | 5 + src/central/billing-context.ts | 5 + src/central/billing.ts | 36 +++++ src/central/coordinator.ts | 106 +++++++++++++++ src/central/distribution.ts | 30 +++++ src/central/local-channel.ts | 50 +++++++ src/central/operations.ts | 142 ++++++++++++++++++++ src/central/processor.ts | 105 +++++++++++++++ src/central/protocol.ts | 23 +++- src/central/replication.ts | 27 ++++ src/central/rpc.ts | 86 ++++++++++++ src/lib/core/arweave/index.ts | 11 ++ src/lib/core/prover/index.ts | 4 + src/lib/core/streamr/index.ts | 8 ++ src/lib/core/streamr/ui.ts | 9 +- src/lib/mqtt-config.ts | 9 ++ src/lib/utils.ts | 18 +++ src/services/grpc.ts | 31 ++++- src/services/mqtt.ts | 19 +-- src/store/sqlite.ts | 30 +++++ src/utils/logger.ts | 44 +++++-- tests/services/managed-logging.test.ts | 17 +++ tests/services/managed-uplinks.test.ts | 176 +++++++++++++++++++++++++ tests/services/reconciliation.test.ts | 69 ++++++++++ 24 files changed, 1032 insertions(+), 28 deletions(-) create mode 100644 src/central/billing-context.ts create mode 100644 src/central/billing.ts create mode 100644 src/central/coordinator.ts create mode 100644 src/central/distribution.ts create mode 100644 src/central/local-channel.ts create mode 100644 src/central/operations.ts create mode 100644 src/central/processor.ts create mode 100644 src/central/replication.ts create mode 100644 src/central/rpc.ts create mode 100644 src/lib/mqtt-config.ts create mode 100644 tests/services/managed-logging.test.ts create mode 100644 tests/services/managed-uplinks.test.ts create mode 100644 tests/services/reconciliation.test.ts diff --git a/.gitignore b/.gitignore index 1d72804..7e2c1a6 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,9 @@ script.*.js # Database files *.db +*.db-wal +*.db-shm +.data*/ src/db # data files @@ -93,6 +96,8 @@ web_modules/ .env.test.local .env.production.local .env.local +.env.* +!.env.example # parcel-bundler cache (https://parceljs.org/) .cache diff --git a/src/central/billing-context.ts b/src/central/billing-context.ts new file mode 100644 index 0000000..dd2c0ce --- /dev/null +++ b/src/central/billing-context.ts @@ -0,0 +1,5 @@ +import { AsyncLocalStorage } from 'async_hooks'; +import type { TransactionRecord } from '../types'; + +export interface ManagedBillingContext { id:string; distribution:TransactionRecord[] } +export const managedBilling = new AsyncLocalStorage(); diff --git a/src/central/billing.ts b/src/central/billing.ts new file mode 100644 index 0000000..6b29156 --- /dev/null +++ b/src/central/billing.ts @@ -0,0 +1,36 @@ +import { handleMessage } from '../services/mqtt'; +import { getMeterByPublicKey, mergeBillingSnapshot, readBillingSnapshot } from '../store/sqlite'; +import { DurableProcessor, BillingSnapshot } from './processor'; +import { managedBilling } from './billing-context'; +import type { UplinkEvent } from './protocol'; +import { verifyPayloadSignature, distributeManaged } from '../lib/utils'; +import { meterIdFromPublicKeyContractCall, meterLatestNonceContractCall } from '../utils/contracts'; + +export function billingSnapshot(event:UplinkEvent):BillingSnapshot { + return readBillingSnapshot(event.deviceInfo.devEui); +} +export function createBillingProcessor(filename:string):DurableProcessor { + return new DurableProcessor(filename,async(event,sink)=>{ + const context={id:event.deduplicationId!,distribution:[]}; + await managedBilling.run(context,()=>handleMessage(Buffer.from(JSON.stringify(event)),sink)); + void distributeManaged(context.distribution).catch(()=>{}); + },billingSnapshot,async snapshot=>{ + const meter=snapshot.meter;if(!meter)return; + const known=getMeterByPublicKey(meter.publicKey); + const token=known?.tokenId ?? await meterIdFromPublicKeyContractCall(meter.publicKey); + if(token!==meter.tokenId)throw new Error('Reconciliation meter token does not match the contract.'); + const chainNonce=await meterLatestNonceContractCall(token); + if(!Number.isSafeInteger(chainNonce)||chainNonce<0)throw new Error('Cannot verify reconciliation against the chain.'); + let supportedNonce=Math.max(known?.latestNonce??-1,chainNonce); + for(const record of [...snapshot.transactions].sort((a,b)=>a.nonce-b.nonce)){ + const bytes=Buffer.from(record.raw,'hex'); + if(record.identifier!==token || record.nonce!==bytes.readUInt32BE(0) || + bytes.length<74 || !verifyPayloadSignature(bytes,Buffer.from(meter.publicKey.replace(/^0x/,''),'hex')))throw new Error('Invalid signed reconciliation record.'); + if(record.nonce>supportedNonce+1)throw new Error('Reconciliation has a gap before this nonce.'); + supportedNonce=Math.max(supportedNonce,record.nonce); + } + if(meter.latestNonce>supportedNonce)throw new Error('Reconciliation nonce is not supported by signed records or the chain.'); + mergeBillingSnapshot(snapshot); + void distributeManaged(snapshot.transactions).catch(()=>{}); + }); +} diff --git a/src/central/coordinator.ts b/src/central/coordinator.ts new file mode 100644 index 0000000..cfd7ff4 --- /dev/null +++ b/src/central/coordinator.ts @@ -0,0 +1,106 @@ +import type { StateDownlink } from '../services/downlink'; +import { OperationJournal, Owner } from './operations'; +import type { Decider, Outcome } from './processor'; +import type { UplinkEvent } from './protocol'; + +export interface QueueItem { id:string; devEui:string; fPort:number; confirmed:boolean; bytes:number[] } +export interface ChirpstackQueue { + list(devEui:string):Promise; + enqueue(decision:StateDownlink):Promise; +} +export interface CoordinatorOptions { + centralHealthy:()=>boolean; + timeoutMs:number; + reconcileSnapshot?:(owner:Owner,outcome:Outcome)=>Promise; +} +function deadline(promise:Promise,ms:number):Promise { + return new Promise((resolve,reject)=>{ + const timeout=setTimeout(()=>reject(new Error('Decision deadline elapsed.')),ms); + promise.then(value=>{clearTimeout(timeout);resolve(value);},()=>{clearTimeout(timeout);reject(new Error('Decider unavailable.'));}); + }); +} +const terminal = (state:string) => ['enqueued','queue-observed','superseded','rejected'].includes(state); + +/** Only this component may enqueue a managed state reply. Network code never + * retries enqueue. New reports revoke permission to send previous replies before + * any asynchronous work, including a pending queue-read or central response. */ +export class UplinkCoordinator { + private tasks=new Map>(); + private stopped=false; + constructor(readonly journal:OperationJournal, private central:Decider,private local:Decider, + private queue:ChirpstackQueue,private options:CoordinatorOptions) {} + receive(gateway:string,event:UplinkEvent):Promise { + if(this.stopped)throw new Error('Coordinator is stopping.'); + const {operation}=this.journal.receive(gateway,event); + return this.run(operation.id); + } + async drain():Promise {for(const operation of this.journal.pending()){if(this.stopped)return;await this.run(operation.id);}} + async stop():Promise{this.stopped=true;await Promise.allSettled(this.tasks.values());} + private run(id:string):Promise { + const existing=this.tasks.get(id);if(existing)return existing; + const task=this.process(id).finally(()=>this.tasks.delete(id));this.tasks.set(id,task);return task; + } + private async process(id:string):Promise { + let row=this.journal.get(id)!;if(terminal(row.state))return; + if(!row.owner) { + // If an older computation is still in flight, changing deciders could + // commit conflicting records for one nonce. Drop its reply, but reconcile + // its billing snapshot before handing the newer report to another side. + const prior=this.journal.previous(row); + if(prior?.owner) { + try { + const outcome=await deadline(this.decider(prior.owner).outcome(prior.gateway,prior.id),this.options.timeoutMs); + if(!outcome || outcome.active)return; + if(this.options.reconcileSnapshot)await this.options.reconcileSnapshot(prior.owner,outcome); + } catch {return;} + } + let chosen:Owner|null=null; + for(const owner of this.options.centralHealthy()?['central','local'] as const:['local'] as const) { + try {await deadline(this.decider(owner).offer(row.gateway,row.event),this.options.timeoutMs);chosen=owner;break;} + catch {/* Offers never process billing, so pre-commit fallback is safe. */} + } + if(!chosen || !this.journal.own(id,chosen))return; + row=this.journal.get(id)!; + try { + const outcome=await deadline(this.decider(chosen).commit(row.gateway,id),this.options.timeoutMs); + if(this.journal.get(id)!.state==='superseded')return; + if(this.options.reconcileSnapshot && !outcome.active)await this.options.reconcileSnapshot(chosen,outcome); + if(outcome.decision)this.journal.saveDecision(id,outcome.decision); + else {this.journal.uncertain(id);return;} + } catch {this.journal.uncertain(id);return;} + } + await this.reconcile(id); + } + async reconcile(id:string):Promise { + let row=this.journal.get(id);if(!row||!row.owner||terminal(row.state))return; + try { + // Always query the committed owner by the SAME deduplicationId. Never call + // commit again or ask the other Console to recompute an uncertain report. + const outcome=await deadline(this.decider(row.owner).outcome(row.gateway,id),this.options.timeoutMs); + if(!outcome || outcome.active || !outcome.decision){this.journal.uncertain(id);return;} + if(this.options.reconcileSnapshot)await this.options.reconcileSnapshot(row.owner,outcome); + if(!row.attempted)this.journal.saveDecision(id,outcome.decision); + row=this.journal.get(id)!;if(terminal(row.state))return; + const pending=await this.queue.list(row.devEui); + row=this.journal.get(id)!;if(terminal(row.state))return; + const decision=row.decision; + if(!decision){this.journal.uncertain(id);return;} + const matches=pending.filter(item=>item.devEui.toLowerCase()===row!.devEui && item.fPort===2 && !item.confirmed && + Buffer.from(item.bytes).equals(Buffer.from(decision.bytes))); + if(row.attempted) { + const observed=matches.find(item=>!row!.queueBefore.includes(item.id)); + if(observed)this.journal.finish(id,'queue-observed',observed.id); + else this.journal.uncertain(id); + // Empty queue may mean already delivered, not permission to retry. + return; + } + if(matches.length){this.journal.uncertain(id);return;} // Cannot attribute a preexisting identical manual downlink. + if(!this.journal.beginEnqueue(id,pending.map(item=>item.id)))return; + try { + const queueId=await this.queue.enqueue(decision); + this.journal.finish(id,'enqueued',queueId); + } catch {this.journal.uncertain(id);} + } catch {this.journal.uncertain(id);} + } + private decider(owner:Owner):Decider{return owner==='central'?this.central:this.local;} +} diff --git a/src/central/distribution.ts b/src/central/distribution.ts new file mode 100644 index 0000000..ce18d8a --- /dev/null +++ b/src/central/distribution.ts @@ -0,0 +1,30 @@ +import Database from 'better-sqlite3'; +import type { TransactionRecord } from '../types'; + +let publications:PublicationStore|undefined; +export const managedRole=()=>process.env.CONSOLE_ROLE==='central'||process.env.CONSOLE_ROLE==='gateway'; +export function configurePublications(filename:string):void {publications?.close();publications=new PublicationStore(filename);} +export class PublicationStore { + private db:Database.Database; + constructor(filename:string){ + this.db=new Database(filename);this.db.pragma('journal_mode = WAL');this.db.pragma('synchronous = FULL'); + this.db.exec(`CREATE TABLE IF NOT EXISTS managed_publications(destination TEXT,tokenId INTEGER,nonce INTEGER,state TEXT NOT NULL, + PRIMARY KEY(destination,tokenId,nonce)); UPDATE managed_publications SET state='uncertain' WHERE state='started';`); + } + async publish(destination:string,records:TransactionRecord[],send:(records:TransactionRecord[])=>Promise):Promise{ + const claimed=this.db.transaction(()=>records.filter(record=>this.db.prepare("INSERT OR IGNORE INTO managed_publications VALUES (?,?,?,'started')").run(destination,record.identifier,record.nonce).changes>0))(); + if(!claimed.length)return null; + try {const result=await send(claimed);this.finish(destination,claimed,'submitted');return result;} + catch {this.finish(destination,claimed,'uncertain');throw new Error('Publication outcome uncertain; it will not be submitted again automatically.');} + } + private finish(destination:string,records:TransactionRecord[],state:string):void { + this.db.transaction(()=>{for(const r of records)this.db.prepare('UPDATE managed_publications SET state=? WHERE destination=? AND tokenId=? AND nonce=?').run(state,destination,r.identifier,r.nonce);})(); + } + close():void{this.db.close();} +} +export function publishManaged(destination:string,records:TransactionRecord[],send:(records:TransactionRecord[])=>Promise):Promise{ + if(process.env.CONSOLE_ROLE==='gateway')return Promise.resolve(null); + if(!managedRole())return send(records); + if(!publications)return Promise.reject(new Error('Central publication journal is unavailable.')); + return publications.publish(destination,records,send); +} diff --git a/src/central/local-channel.ts b/src/central/local-channel.ts new file mode 100644 index 0000000..c0b4175 --- /dev/null +++ b/src/central/local-channel.ts @@ -0,0 +1,50 @@ +import http from 'http'; +import express from 'express'; +import type { Decider, Outcome } from './processor'; +import type { UplinkEvent } from './protocol'; +import { MAX_MESSAGE_BYTES } from './protocol'; +import { parseOperation, serveOperation, OperationRequest } from './rpc'; +import { hashSecret, equalSecretHash } from './secrets'; +import { eventIdentity } from './operations'; +import { randomUUID } from 'crypto'; +import { RateLimit } from './auth'; + +export function fallbackServer(processor:Decider,secret:string,gateway:string|(()=>string)):http.Server { + const app=express();const secretHash=hashSecret(secret);const limiter=new RateLimit(600,60000,1); + app.use((req,res,next)=>{ + if(!['127.0.0.1','::1','::ffff:127.0.0.1'].includes(req.socket.remoteAddress||'')){res.sendStatus(403);return;} + const bearer=req.headers.authorization?.match(/^Bearer ([^\s]+)$/)?.[1]; + if(!bearer||!equalSecretHash(bearer,secretHash)){res.sendStatus(401);return;} + if(!limiter.allow('fallback')){res.sendStatus(429);return;}next(); + }); + app.post('/operation',express.raw({type:'application/json',limit:MAX_MESSAGE_BYTES}),async(req,res)=>{ + try { + const operation=parseOperation(req.body as Buffer);if(operation.type!=='operation'){res.sendStatus(400);return;} + res.json(await serveOperation(processor,typeof gateway==='function'?gateway():gateway,operation)); + }catch{res.status(400).json({error:'Invalid fallback operation.'});} + }); + return http.createServer(app); +} +export class LocalDecider implements Decider { + constructor(private port:number,private secret:string,private timeoutMs=8000){ + if(!Number.isInteger(port)||port<1024||port>65535)throw new Error('Invalid fallback port.'); + } + offer(_gateway:string,event:UplinkEvent):Promise{return this.call('offer',eventIdentity(event),event).then(()=>{});} + commit(_gateway:string,id:string):Promise{return this.call('commit',id).then(outcome=>{if(!outcome)throw new Error('No local outcome.');return outcome;});} + outcome(_gateway:string,id:string):Promise{return this.call('outcome',id);} + reconcile(_gateway:string,event:UplinkEvent,outcome:Outcome):Promise{return this.call('reconcile',outcome.id,event,outcome).then(()=>{});} + private async call(action:OperationRequest['action'],id:string,event?:UplinkEvent,outcome?:Outcome):Promise { + const body:OperationRequest={v:1,type:'operation',requestId:randomUUID(),action,id,...(event?{event}:{}),...(outcome?{outcome}:{})}; + const response=await fetch(`http://127.0.0.1:${this.port}/operation`,{method:'POST',redirect:'error',signal:AbortSignal.timeout(this.timeoutMs), + headers:{Authorization:`Bearer ${this.secret}`,'Content-Type':'application/json'},body:JSON.stringify(body)}); + if(!response.ok)throw new Error('Local fallback is unavailable.'); + if(!response.body)throw new Error('Local response is empty.'); + const reader=response.body.getReader(),chunks:Uint8Array[]=[];let size=0; + try{for(;;){const chunk=await reader.read();if(chunk.done)break;size+=chunk.value.byteLength; + if(size>MAX_MESSAGE_BYTES){await reader.cancel();throw new Error('Local response exceeds limit.');}chunks.push(chunk.value); + }}finally{reader.releaseLock();} + const result=parseOperation(Buffer.concat(chunks)); + if(result.type!=='operation-result'||result.id!==id||result.requestId!==body.requestId||result.error)throw new Error('Local operation is unavailable.'); + return result.outcome; + } +} diff --git a/src/central/operations.ts b/src/central/operations.ts new file mode 100644 index 0000000..58fbf0e --- /dev/null +++ b/src/central/operations.ts @@ -0,0 +1,142 @@ +import Database from 'better-sqlite3'; +import { createHash } from 'crypto'; +import type { StateDownlink } from '../services/downlink'; +import type { Outcome } from './processor'; +import { parseMessage, UplinkEvent } from './protocol'; + +export type Owner = 'central' | 'local'; +export type OperationState = 'received' | 'owned' | 'decided' | 'enqueue-started' | 'uncertain' | 'enqueued' | 'queue-observed' | 'superseded' | 'rejected'; +export interface Operation { + id: string; gateway: string; devEui: string; event: UplinkEvent; owner: Owner | null; + state: OperationState; decision: StateDownlink | null; attempted: boolean; + queueBefore: string[]; queueId: string | null; sequence: number; uncertainCounted: boolean; +} +export interface GatewayCounts { uncertain: number; reconciled: number; superseded: number; pending: number } +export type OperationLog = (event: { gateway: string; id: string; state: OperationState }) => void; +type Row = Omit & { + event: string; decision: string | null; attempted: number; queueBefore: string; uncertainCounted: number; +}; + +export function eventIdentity(event: UplinkEvent): string { + // No generated IDs: transport retries must carry the original ChirpStack ID. + const id = event.deduplicationId; + if (typeof id !== 'string' || !/^[a-zA-Z0-9_-]{1,128}$/.test(id) || /\s/.test(id)) throw new Error('A ChirpStack deduplicationId is required for managed billing.'); + parseMessage(JSON.stringify({ v:1, type:'uplink', id, event }), 'agent'); + return id; +} +export function eventFingerprint(event: UplinkEvent): string { + // Gateway/radio metadata can vary on redelivery; signed report identity cannot. + const { uplinkPayload } = require('../lib/uplink-payload') as typeof import('../lib/uplink-payload'); + return createHash('sha256').update(JSON.stringify([event.deviceInfo.applicationId.toLowerCase(), event.deviceInfo.devEui.toLowerCase(), event.fPort, + event.fCnt ?? null, uplinkPayload(event).hex])).digest('hex'); +} + +/** Agent-side durable ownership and enqueue journal. Terminal entries are kept as + * tombstones: deleting them would turn an old MQTT delivery into a new command. + * Capacity is a hard bound, never an instruction to silently evict idempotency. */ +export class OperationJournal { + readonly db: Database.Database; + constructor(filename: string, private capacity = 100000, private log: OperationLog = () => {}) { + this.db = new Database(filename); + this.db.pragma('journal_mode = WAL'); this.db.pragma('synchronous = FULL'); this.db.pragma('busy_timeout = 5000'); + this.db.exec(`CREATE TABLE IF NOT EXISTS agent_operations ( + sequence INTEGER PRIMARY KEY AUTOINCREMENT, id TEXT NOT NULL UNIQUE, gateway TEXT NOT NULL, + devEui TEXT NOT NULL, fingerprint TEXT NOT NULL, event TEXT NOT NULL, owner TEXT, state TEXT NOT NULL, + decision TEXT, attempted INTEGER NOT NULL DEFAULT 0, queueBefore TEXT NOT NULL DEFAULT '[]', + queueId TEXT, uncertainCounted INTEGER NOT NULL DEFAULT 0); + CREATE INDEX IF NOT EXISTS agent_operations_device ON agent_operations(gateway,devEui,sequence); + CREATE TABLE IF NOT EXISTS agent_counters (gateway TEXT PRIMARY KEY, uncertain INTEGER NOT NULL DEFAULT 0, + reconciled INTEGER NOT NULL DEFAULT 0, superseded INTEGER NOT NULL DEFAULT 0); + CREATE TABLE IF NOT EXISTS agent_replays(id TEXT NOT NULL,target TEXT NOT NULL,outcome TEXT NOT NULL, + PRIMARY KEY(id,target));`); + // A process restart cannot turn a possibly delivered enqueue into a retry. + const interrupted = this.db.prepare("SELECT id FROM agent_operations WHERE state IN ('owned','enqueue-started')").all() as Array<{ id: string }>; + for (const row of interrupted) this.uncertain(row.id); + } + get(id: string): Operation | null { + const row = this.db.prepare('SELECT * FROM agent_operations WHERE id=?').get(id) as Row | undefined; + return row ? { ...row, event: JSON.parse(row.event) as UplinkEvent, decision: row.decision ? JSON.parse(row.decision) as StateDownlink : null, + attempted: !!row.attempted, queueBefore: JSON.parse(row.queueBefore) as string[], uncertainCounted: !!row.uncertainCounted } : null; + } + receive(gateway: string, event: UplinkEvent): { operation: Operation; fresh: boolean } { + const id = eventIdentity(event), fingerprint = eventFingerprint(event); + return this.db.transaction(() => { + const existing = this.db.prepare('SELECT fingerprint,gateway FROM agent_operations WHERE id=?').get(id) as { fingerprint: string; gateway: string } | undefined; + if (existing) { + if (existing.fingerprint !== fingerprint || existing.gateway !== gateway) throw new Error('Event identity conflicts with an existing report.'); + return { operation: this.get(id)!, fresh: false }; + } + const count = this.db.prepare('SELECT COUNT(*) AS n FROM agent_operations').get() as { n: number }; + if (count.n >= this.capacity) throw new Error('Agent journal is full; retain idempotency records and stop ingestion.'); + this.db.prepare('INSERT OR IGNORE INTO agent_counters(gateway) VALUES (?)').run(gateway); + const devEui = event.deviceInfo.devEui.toLowerCase(); + // The next distinct report cancels permission to send all older unsent replies. + const supersededIds=this.db.prepare("SELECT id FROM agent_operations WHERE gateway=? AND devEui=? AND state IN ('received','owned','decided','enqueue-started','uncertain')").all(gateway,devEui) as Array<{id:string}>; + const superseded = this.db.prepare(`UPDATE agent_operations SET state='superseded' WHERE gateway=? AND devEui=? + AND state IN ('received','owned','decided','enqueue-started','uncertain')`).run(gateway, devEui).changes; + if (superseded) this.db.prepare('UPDATE agent_counters SET superseded=superseded+? WHERE gateway=?').run(superseded,gateway); + this.db.prepare("INSERT INTO agent_operations(id,gateway,devEui,fingerprint,event,state) VALUES (?,?,?,?,?,'received')") + .run(id,gateway,devEui,fingerprint,JSON.stringify(event)); + for(const previous of supersededIds)this.emit(previous.id); + return { operation: this.get(id)!, fresh: true }; + })(); + } + own(id: string, owner: Owner): boolean { + const changed = this.db.prepare("UPDATE agent_operations SET owner=?,state='owned' WHERE id=? AND state='received' AND owner IS NULL").run(owner,id).changes; + if (changed) this.emit(id); return !!changed; + } + saveDecision(id: string, decision: StateDownlink): boolean { + const row = this.get(id); + if (!row || row.devEui !== decision.devEui.toLowerCase() || !row.owner || row.state === 'superseded' || row.attempted) return false; + parseMessage(JSON.stringify({v:1,type:'decision',id,devEui:decision.devEui,fPort:decision.fPort,confirmed:decision.confirmed,data:Buffer.from(decision.bytes).toString('base64')}),'central'); + if (row.decision && JSON.stringify(row.decision) !== JSON.stringify(decision)) throw new Error('A committed event cannot acquire a different decision.'); + const changed = this.db.prepare("UPDATE agent_operations SET decision=?,state='decided' WHERE id=? AND state IN ('owned','uncertain','decided') AND attempted=0") + .run(JSON.stringify(decision),id).changes; + if (changed) this.emit(id); return !!changed; + } + beginEnqueue(id: string, queueBefore: string[]): boolean { + const changed = this.db.prepare("UPDATE agent_operations SET attempted=1,state='enqueue-started',queueBefore=? WHERE id=? AND state='decided' AND attempted=0") + .run(JSON.stringify(queueBefore),id).changes; + if (changed) this.emit(id); return !!changed; + } + uncertain(id: string): void { + const changed=this.db.transaction(() => { + const row = this.get(id); + if (!row || ['superseded','enqueued','queue-observed','rejected'].includes(row.state)) return false; + if (!row.uncertainCounted) this.db.prepare('UPDATE agent_counters SET uncertain=uncertain+1 WHERE gateway=?').run(row.gateway); + this.db.prepare("UPDATE agent_operations SET state='uncertain',uncertainCounted=1 WHERE id=?").run(id); + return row.state!=='uncertain'; + })(); + if(changed)this.emit(id); + } + finish(id: string, state: 'enqueued' | 'queue-observed' | 'rejected', queueId?: string): void { + this.db.transaction(() => { + const row = this.get(id); + if (!row || ['superseded','enqueued','queue-observed','rejected'].includes(row.state)) return; + if (row.uncertainCounted && state !== 'rejected') this.db.prepare('UPDATE agent_counters SET reconciled=reconciled+1 WHERE gateway=?').run(row.gateway); + this.db.prepare('UPDATE agent_operations SET state=?,queueId=? WHERE id=?').run(state,queueId ?? null,id); + })(); this.emit(id); + } + pending(): Operation[] { + return (this.db.prepare("SELECT id FROM agent_operations WHERE state IN ('received','owned','decided','enqueue-started','uncertain') ORDER BY sequence").all() as Array<{id:string}>).map(row=>this.get(row.id)!); + } + previous(operation: Operation): Operation | null { + const row = this.db.prepare('SELECT id FROM agent_operations WHERE gateway=? AND devEui=? AND sequence | undefined; + const pending = this.db.prepare("SELECT COUNT(*) AS n FROM agent_operations WHERE gateway=? AND state IN ('owned','decided','enqueue-started','uncertain','received')").get(gateway) as {n:number}; + return {uncertain:0,reconciled:0,superseded:0,...row,pending:pending.n}; + } + rememberReplay(target:Owner,outcome:Outcome):void { + if(outcome.active||!outcome.snapshot)return; + this.db.prepare('INSERT INTO agent_replays(id,target,outcome) VALUES (?,?,?) ON CONFLICT(id,target) DO UPDATE SET outcome=excluded.outcome') + .run(outcome.id,target,JSON.stringify(outcome)); + } + replays(target:Owner):Outcome[] {return (this.db.prepare('SELECT outcome FROM agent_replays WHERE target=? ORDER BY rowid').all(target) as Array<{outcome:string}>).map(row=>JSON.parse(row.outcome) as Outcome);} + replayed(target:Owner,id:string):void {this.db.prepare('DELETE FROM agent_replays WHERE id=? AND target=?').run(id,target);} + private emit(id: string): void { const row=this.get(id); if(row) this.log({gateway:row.gateway,id:row.id,state:row.state}); } + close(): void { this.db.close(); } +} diff --git a/src/central/processor.ts b/src/central/processor.ts new file mode 100644 index 0000000..de919cd --- /dev/null +++ b/src/central/processor.ts @@ -0,0 +1,105 @@ +import Database from 'better-sqlite3'; +import type { DownlinkSink, StateDownlink } from '../services/downlink'; +import type { MeterRecord, TransactionRecord } from '../types'; +import type { UplinkEvent } from './protocol'; +import { eventIdentity, eventFingerprint } from './operations'; + +export interface BillingSnapshot { meter: MeterRecord | null; transactions: TransactionRecord[] } +export interface Outcome { + id: string; state: 'offered' | 'processing' | 'decided' | 'uncertain' | 'rejected'; + active: boolean; decision: StateDownlink | null; snapshot: BillingSnapshot | null; +} +export interface Decider { + offer(gateway: string, event: UplinkEvent): Promise; + commit(gateway: string, id: string): Promise; + outcome(gateway: string, id: string): Promise; + reconcile?(gateway:string,event:UplinkEvent,outcome:Outcome):Promise; +} +type ProcessorRow = { id:string; gateway:string; fingerprint:string; event:string; state:Outcome['state']; decision:string|null; snapshot:string|null }; + +/** Both central and fallback use this wrapper around the SAME billing handler. + * Offer does no billing. A durable processing claim precedes the handler. Once + * claimed, a missing result is never permission to recompute or change deciders. */ +export class DurableProcessor implements Decider { + private db: Database.Database; + private active = new Map>(); + private devices = new Map>(); + constructor(filename:string, private compute:(event:UplinkEvent,sink:DownlinkSink)=>Promise, + private snapshot:(event:UplinkEvent)=>BillingSnapshot = ()=>({meter:null,transactions:[]}), + private importSnapshot?:(snapshot:BillingSnapshot)=>Promise) { + this.db=new Database(filename); + this.db.pragma('journal_mode = WAL');this.db.pragma('synchronous = FULL');this.db.pragma('busy_timeout = 5000'); + this.db.exec(`CREATE TABLE IF NOT EXISTS managed_operations (id TEXT PRIMARY KEY, gateway TEXT NOT NULL, + fingerprint TEXT NOT NULL,event TEXT NOT NULL,state TEXT NOT NULL,decision TEXT,snapshot TEXT); + UPDATE managed_operations SET state='uncertain' WHERE state='processing';`); + } + async offer(gateway:string,event:UplinkEvent):Promise { + const id=eventIdentity(event),fingerprint=eventFingerprint(event); + const row=this.row(id); + if(row) { + if(row.gateway!==gateway || row.fingerprint!==fingerprint) throw new Error('Event identity conflicts with an existing report.'); + return; + } + this.db.prepare("INSERT INTO managed_operations (id,gateway,fingerprint,event,state) VALUES (?,?,?,?,'offered')").run(id,gateway,fingerprint,JSON.stringify(event)); + } + async commit(gateway:string,id:string):Promise { + const row=this.authorized(gateway,id); + const existing=this.active.get(id);if(existing)return existing; + if(row.state!=='offered')return this.result(row); + const event=JSON.parse(row.event) as UplinkEvent; + // Serialize by device as well as event. A newer report can supersede the + // reply, but cannot race an older handler's nonce/database updates. + const device=`${gateway}:${event.deviceInfo.devEui.toLowerCase()}`; + const previous=this.devices.get(device) || Promise.resolve(); + const task=previous.catch(()=>{}).then(async()=>{ + const claim=this.db.prepare("UPDATE managed_operations SET state='processing' WHERE id=? AND state='offered'").run(id); + if(!claim.changes)return this.result(this.authorized(gateway,id)); + try { + await this.compute(event,async decision=>{ + if(decision.devEui.toLowerCase()!==event.deviceInfo.devEui.toLowerCase())throw new Error('Decision belongs to a different device.'); + const updated=this.db.prepare("UPDATE managed_operations SET decision=?,state='decided' WHERE id=? AND state='processing' AND decision IS NULL") + .run(JSON.stringify(decision),id); + if(!updated.changes)throw new Error('An event may store only one decision.'); + }); + } catch { + // The handler may already have committed billing data. No automatic rerun. + } finally { + this.db.prepare("UPDATE managed_operations SET state='uncertain' WHERE id=? AND state='processing'").run(id); + const snapshot=this.snapshot(event); + this.db.prepare('UPDATE managed_operations SET snapshot=? WHERE id=?').run(JSON.stringify(snapshot),id); + } + return this.result(this.authorized(gateway,id),false); + }); + this.active.set(id,task);this.devices.set(device,task); + try {return await task;} finally {this.active.delete(id);if(this.devices.get(device)===task)this.devices.delete(device);} + } + async outcome(gateway:string,id:string):Promise { + const row=this.row(id);if(!row)return null; + if(row.gateway!==gateway)throw new Error('Gateway cannot inspect this event.'); + const result=this.result(row); + // After a process crash, return the durable billing state even if the last + // result snapshot was never written. Do not run the decision handler again. + if(!result.active && !result.snapshot && row.state!=='offered') result.snapshot=this.snapshot(JSON.parse(row.event) as UplinkEvent); + return result; + } + async reconcile(gateway:string,event:UplinkEvent,outcome:Outcome):Promise { + if(eventIdentity(event)!==outcome.id || outcome.active)throw new Error('Invalid reconciliation identity or active operation.'); + if(outcome.decision && outcome.decision.devEui.toLowerCase()!==event.deviceInfo.devEui.toLowerCase())throw new Error('Reconciliation decision belongs to another device.'); + if(outcome.snapshot?.meter && outcome.snapshot.meter.devEui?.toLowerCase()!==event.deviceInfo.devEui.toLowerCase())throw new Error('Reconciliation meter belongs to another device.'); + await this.offer(gateway,event); + const row=this.authorized(gateway,outcome.id); + if(this.active.has(outcome.id))throw new Error('Cannot reconcile an active operation.'); + if(row.decision && JSON.stringify(JSON.parse(row.decision))!==JSON.stringify(outcome.decision))throw new Error('Conflicting stored decisions.'); + if(outcome.snapshot && this.importSnapshot)await this.importSnapshot(outcome.snapshot); + if(row.state==='offered')this.db.prepare('UPDATE managed_operations SET state=?,decision=?,snapshot=? WHERE id=?') + .run(outcome.state==='decided'?'decided':'uncertain',outcome.decision?JSON.stringify(outcome.decision):null,JSON.stringify(outcome.snapshot),outcome.id); + } + private row(id:string):ProcessorRow|undefined {return this.db.prepare('SELECT * FROM managed_operations WHERE id=?').get(id) as ProcessorRow|undefined;} + private authorized(gateway:string,id:string):ProcessorRow { + const row=this.row(id);if(!row||row.gateway!==gateway)throw new Error('An authorized offer is required before commit.');return row; + } + private result(row:ProcessorRow,active=this.active.has(row.id)):Outcome { + return {id:row.id,state:row.state,active,decision:row.decision?JSON.parse(row.decision) as StateDownlink:null,snapshot:row.snapshot?JSON.parse(row.snapshot) as BillingSnapshot:null}; + } + close():void {if(this.active.size)throw new Error('Cannot close a processor with active operations.');this.db.close();} +} diff --git a/src/central/protocol.ts b/src/central/protocol.ts index c805042..c1a7c92 100644 --- a/src/central/protocol.ts +++ b/src/central/protocol.ts @@ -3,7 +3,8 @@ export const MAX_MESSAGE_BYTES = 65536; export const MAX_TUNNEL_CHUNK = 16384; export type TunnelPurpose = 'ssh' | 'chirpstack' | 'browser'; export type Health = { version: string; uptime: number; mqtt: 'connected' | 'disconnected' | 'connecting'; - fallback: boolean; queueDepth: number; updatesEnabled: boolean; lastError: 'none' | 'mqtt' | 'central' | 'local' | 'storage' | 'update' }; + fallback: boolean; queueDepth: number; updatesEnabled: boolean; uncertain: number; reconciled: number; superseded: number; + lastError: 'none' | 'mqtt' | 'central' | 'local' | 'storage' | 'update' }; export type UplinkEvent = { fPort: 2; deviceInfo: { devEui: string; applicationId: string }; data?: string; dataHex?: string; dataEncoding?: 'hex' | 'base64'; deduplicationId?: string; fCnt?: number; time?: string }; export type AgentMessage = | { v: 1; type: 'health'; health: Health } @@ -20,7 +21,8 @@ export type CentralMessage = | TunnelMessage | PingMessage; export type PingMessage = { v: 1; type: 'ping' | 'pong'; id: string }; export type TunnelMessage = - | { v: 1; type: 'tunnel-ready'; id: string } + | { v: 1; type: 'tunnel-ready'; id: string; origin?:string } + | { v: 1; type: 'tunnel-end'; id: string } | { v: 1; type: 'tunnel-data'; id: string; data: string } | { v: 1; type: 'tunnel-credit'; id: string; bytes: number } | { v: 1; type: 'tunnel-close'; id: string; reason: 'closed' | 'refused' | 'timeout' | 'limit' | 'disconnected' | 'error' }; @@ -49,7 +51,7 @@ function validUplink(value: unknown): value is UplinkEvent { const info = value.deviceInfo; if (typeof info.devEui !== 'string' || !/^[a-fA-F0-9]{16}$/.test(info.devEui) || typeof info.applicationId !== 'string' || !/^[a-fA-F0-9]{8}(?:-[a-fA-F0-9]{4}){3}-[a-fA-F0-9]{12}$/.test(info.applicationId)) return false; - if (value.deduplicationId !== undefined && !id(value.deduplicationId)) return false; + if (!id(value.deduplicationId)) return false; if (value.fCnt !== undefined && !integer(value.fCnt, 0, 0xffffffff)) return false; if (value.time !== undefined && (typeof value.time !== 'string' || value.time.length > 40 || !Number.isFinite(Date.parse(value.time)))) return false; // Use the original transport decoder, without alphabet heuristics or a second wire format. @@ -70,7 +72,14 @@ export function parseMessage(input: Buffer | string, direction: 'agent' | 'centr const keys = (...fields: string[]) => exact(value, ['v', 'type', ...fields]); let valid = false; switch (value.type) { - case 'ping': case 'pong': case 'tunnel-ready': valid = keys('id') && id(value.id); break; + case 'ping': case 'pong': case 'tunnel-end': valid = keys('id') && id(value.id); break; + case 'tunnel-ready': { + valid=id(value.id)&&keys('id'); + if(value.origin!==undefined&&typeof value.origin==='string'&&value.origin.length<512&&keys('id','origin')){ + try{const url=new URL(value.origin);valid=id(value.id)&&['http:','https:'].includes(url.protocol)&&url.origin===value.origin&&!url.username&&!url.password;}catch{valid=false;} + } + break; + } case 'tunnel-data': valid = keys('id', 'data') && id(value.id) && base64(value.data, 1, MAX_TUNNEL_CHUNK); break; case 'tunnel-credit': valid = keys('id', 'bytes') && id(value.id) && integer(value.bytes, 1, 65536); break; case 'tunnel-close': valid = keys('id', 'reason') && id(value.id) && isOneOf(value.reason, ['closed', 'refused', 'timeout', 'limit', 'disconnected', 'error']); break; @@ -86,13 +95,13 @@ export function parseMessage(input: Buffer | string, direction: 'agent' | 'centr case 'update-progress': valid = direction === 'agent' && keys('id', 'status') && id(value.id) && isOneOf(value.status, ['queued', 'downloading', 'verifying', 'restarting', 'succeeded', 'failed', 'rolled-back']); break; case 'result': valid = direction === 'agent' && keys('id', 'outcome') && id(value.id) && isOneOf(value.outcome, ['enqueued', 'locally-handled', 'rejected', 'uncertain']); break; - case 'uplink': valid = direction === 'agent' && keys('id', 'event') && id(value.id) && validUplink(value.event); break; + case 'uplink': valid = direction === 'agent' && keys('id', 'event') && id(value.id) && validUplink(value.event) && value.event.deduplicationId===value.id; break; case 'health': { const h = value.health; - valid = direction === 'agent' && keys('health') && object(h) && exact(h, ['version', 'uptime', 'mqtt', 'fallback', 'queueDepth', 'updatesEnabled', 'lastError']) && + valid = direction === 'agent' && keys('health') && object(h) && exact(h, ['version', 'uptime', 'mqtt', 'fallback', 'queueDepth', 'updatesEnabled', 'lastError', 'uncertain', 'reconciled', 'superseded']) && typeof h.version === 'string' && /^[\w.+-]{1,80}$/.test(h.version) && integer(h.uptime, 0, Number.MAX_SAFE_INTEGER) && isOneOf(h.mqtt, ['connected', 'disconnected', 'connecting']) && typeof h.fallback === 'boolean' && integer(h.queueDepth, 0, 1000000) && - typeof h.updatesEnabled === 'boolean' && isOneOf(h.lastError, ['none', 'mqtt', 'central', 'local', 'storage', 'update']); + typeof h.updatesEnabled === 'boolean' && integer(h.uncertain,0,Number.MAX_SAFE_INTEGER) && integer(h.reconciled,0,Number.MAX_SAFE_INTEGER) && integer(h.superseded,0,Number.MAX_SAFE_INTEGER) && isOneOf(h.lastError, ['none', 'mqtt', 'central', 'local', 'storage', 'update']); break; } } diff --git a/src/central/replication.ts b/src/central/replication.ts new file mode 100644 index 0000000..12dd5bb --- /dev/null +++ b/src/central/replication.ts @@ -0,0 +1,27 @@ +import { OperationJournal, Owner } from './operations'; +import type { Decider, Outcome } from './processor'; + +/** Synchronize the receiving decider BEFORE it may accept another report. Failed + * replication stays durable; it is not discarded when the reply was enqueued. */ +export class Replication { + constructor(private journal:OperationJournal,private central:Decider,private local:Decider) {} + async observe(owner:Owner,outcome:Outcome):Promise { + const target=owner==='central'?'local':'central'; + this.journal.rememberReplay(target,outcome); + try {await this.flush(target);} catch {/* durable backlog; the target cannot offer until it catches up */} + } + async flush(target:Owner):Promise { + const decider=target==='central'?this.central:this.local; + if(!decider.reconcile)throw new Error('Decider does not support reconciliation.'); + for(const outcome of this.journal.replays(target)){ + const operation=this.journal.get(outcome.id);if(!operation)throw new Error('Reconciliation event is missing.'); + await decider.reconcile(operation.gateway,operation.event,outcome); + this.journal.replayed(target,outcome.id); + } + } + guarded(owner:Owner):Decider { + const target=owner==='central'?this.central:this.local; + return {offer:async(gateway,event)=>{await this.flush(owner);await target.offer(gateway,event);}, + commit:(gateway,id)=>target.commit(gateway,id),outcome:(gateway,id)=>target.outcome(gateway,id),reconcile:target.reconcile?.bind(target)}; + } +} diff --git a/src/central/rpc.ts b/src/central/rpc.ts new file mode 100644 index 0000000..285d061 --- /dev/null +++ b/src/central/rpc.ts @@ -0,0 +1,86 @@ +import { randomUUID } from 'crypto'; +import WebSocket from 'ws'; +import type { Decider, Outcome, BillingSnapshot } from './processor'; +import { parseMessage, UplinkEvent, MAX_MESSAGE_BYTES } from './protocol'; +import { eventIdentity } from './operations'; + +export type OperationRequest = {v:1;type:'operation';requestId:string;action:'offer'|'commit'|'outcome'|'reconcile';id:string;event?:UplinkEvent;outcome?:Outcome}; +export type OperationResponse = {v:1;type:'operation-result';requestId:string;id:string;outcome:Outcome|null;error:boolean}; +const record=(value:unknown):value is Record=>typeof value==='object'&&value!==null&&!Array.isArray(value); +const identifier=(value:unknown):value is string=>typeof value==='string'&&/^[\w-]{1,128}$/.test(value)&&!/[\s]/.test(value); +const int=(v:unknown,min=0):v is number=>typeof v==='number'&&Number.isSafeInteger(v)&&v>=min; +function snapshot(value:unknown):value is BillingSnapshot { + if(!record(value)||!Array.isArray(value.transactions)||value.transactions.length>1000)return false; + if(value.meter===null)return value.transactions.length===0; + const m=value.meter; + if(!record(m)||typeof m.publicKey!=='string'||!/^0x[a-fA-F0-9]{64}$/.test(m.publicKey)||!int(m.tokenId)||!int(m.latestNonce,-1)|| + typeof m.devEui!=='string'||!/^[a-fA-F0-9]{16}$/.test(m.devEui))return false; + return value.transactions.every(t=>record(t)&&int(t.nonce)&&int(t.identifier)&&int(t.receivedAt)&&typeof t.raw==='string'&&/^[a-fA-F0-9]+$/.test(t.raw)&&[148,212,224].includes(t.raw.length)); +} +export function validOutcome(value:unknown,id:string):value is Outcome { + if(!record(value)||value.id!==id||!['offered','processing','decided','uncertain','rejected'].includes(String(value.state))||typeof value.active!=='boolean')return false; + if(value.snapshot!==null&&!snapshot(value.snapshot))return false; + if(value.decision===null)return true; + const d=value.decision;if(!record(d)||!Array.isArray(d.bytes)||!d.bytes.every(b=>int(b)&&b<=255))return false; + try {parseMessage(JSON.stringify({v:1,type:'decision',id,devEui:d.devEui,fPort:d.fPort,confirmed:d.confirmed,data:Buffer.from(d.bytes).toString('base64')}),'central');return true;}catch{return false;} +} +export function parseOperation(input:Buffer|string):OperationRequest|OperationResponse { + if(Buffer.byteLength(input)>MAX_MESSAGE_BYTES)throw new Error('Operation frame exceeds limit.'); + const value:unknown=JSON.parse(input.toString()); + if(!record(value)||value.v!==1||!identifier(value.requestId)||!identifier(value.id))throw new Error('Invalid operation envelope.'); + if(value.type==='operation-result'){ + if(Object.keys(value).length!==6||typeof value.error!=='boolean'||(value.outcome!==null&&!validOutcome(value.outcome,value.id)))throw new Error('Invalid operation result.'); + return value as OperationResponse; + } + if(value.type!=='operation'||!['offer','commit','outcome','reconcile'].includes(String(value.action)))throw new Error('Unknown operation.'); + const wantsEvent=value.action==='offer'||value.action==='reconcile'; + const wantsOutcome=value.action==='reconcile'; + if(Object.keys(value).length!==5+(wantsEvent?1:0)+(wantsOutcome?1:0))throw new Error('Unexpected operation fields.'); + if(wantsEvent){ + parseMessage(JSON.stringify({v:1,type:'uplink',id:value.id,event:value.event}),'agent'); + if(eventIdentity(value.event as UplinkEvent)!==value.id)throw new Error('Operation ID must be the uplink deduplicationId.'); + } + if(wantsOutcome&&!validOutcome(value.outcome,value.id))throw new Error('Invalid reconciliation outcome.'); + return value as OperationRequest; +} +export async function serveOperation(processor:Decider,gateway:string,request:OperationRequest):Promise { + let outcome:Outcome|null=null,error=false; + try { + if(request.action==='offer')await processor.offer(gateway,request.event!); + else if(request.action==='commit')outcome=await processor.commit(gateway,request.id); + else if(request.action==='outcome')outcome=await processor.outcome(gateway,request.id); + else if(processor.reconcile)await processor.reconcile(gateway,request.event!,request.outcome!); + else throw new Error('Reconciliation is unavailable.'); + } catch {error=true;} + return {v:1,type:'operation-result',requestId:request.requestId,id:request.id,outcome,error}; +} + +/** One bounded RPC channel over the agent's persistent outbound socket. The + * gateway identity is assigned by authentication, never by a frame's payload. */ +export class SocketDecider implements Decider { + private pending=new Mapvoid;reject:(error:Error)=>void;timer:ReturnType}>(); + constructor(private socket:()=>WebSocket|undefined,private timeoutMs=8000) {} + offer(_gateway:string,event:UplinkEvent):Promise{return this.call('offer',eventIdentity(event),event).then(()=>{});} + commit(_gateway:string,id:string):Promise{return this.call('commit',id).then(value=>{if(!value)throw new Error('No stored outcome.');return value;});} + outcome(_gateway:string,id:string):Promise{return this.call('outcome',id);} + reconcile(_gateway:string,event:UplinkEvent,outcome:Outcome):Promise{return this.call('reconcile',outcome.id,event,outcome).then(()=>{});} + receive(message:OperationResponse):void { + const pending=this.pending.get(message.requestId);if(!pending)return; + if(message.id!==pending.id){this.disconnect();return;} + clearTimeout(pending.timer);this.pending.delete(message.requestId); + if(message.error)pending.reject(new Error('Operation refused or unavailable.'));else pending.resolve(message.outcome); + } + disconnect():void {for(const p of this.pending.values()){clearTimeout(p.timer);p.reject(new Error('Agent link disconnected.'));}this.pending.clear();} + private call(action:OperationRequest['action'],id:string,event?:UplinkEvent,outcome?:Outcome):Promise { + const socket=this.socket(); + if(!socket||socket.readyState!==WebSocket.OPEN||this.pending.size>=64||socket.bufferedAmount>MAX_MESSAGE_BYTES*8)return Promise.reject(new Error('Agent link unavailable or busy.')); + const requestId=randomUUID(); + const message:OperationRequest={v:1,type:'operation',requestId,action,id,...(event?{event}:{}),...(outcome?{outcome}:{})}; + parseOperation(JSON.stringify(message)); + return new Promise((resolve,reject)=>{ + const timer=setTimeout(()=>{this.pending.delete(requestId);reject(new Error('Operation timed out.'));},this.timeoutMs); + this.pending.set(requestId,{id,resolve,reject,timer}); + socket.send(JSON.stringify(message),error=>{if(error){clearTimeout(timer);this.pending.delete(requestId);reject(new Error('Operation send failed.'));}}); + }); + } +} diff --git a/src/lib/core/arweave/index.ts b/src/lib/core/arweave/index.ts index 49d6db5..11bd795 100644 --- a/src/lib/core/arweave/index.ts +++ b/src/lib/core/arweave/index.ts @@ -3,11 +3,22 @@ import { Readable } from "stream"; import Arweave from "arweave"; import type { DecodedPayload, Hooks } from "../../../types"; import { createLogger } from "../../../utils/logger"; +import { managedRole, publishManaged } from '../../../central/distribution'; +import { getTransactionByNonce } from '../../../store/sqlite'; const logger = createLogger("[arweave]"); export default class implements Hooks { async onTransactionDistribution(m3terId: number, decoded: DecodedPayload) { + if (managedRole()) { + const record=getTransactionByNonce(decoded.nonce,m3terId); + if(record)await publishManaged('arweave', [record], () => this.upload(m3terId,decoded)); + return; + } + return this.upload(m3terId,decoded); + } + + private async upload(m3terId: number, decoded: DecodedPayload) { // encode transaction into standard format (payload[0]) // format: nonce | energy | signature | voltage | device_id | longitude | latitude const transactionHex = decoded.buf; diff --git a/src/lib/core/prover/index.ts b/src/lib/core/prover/index.ts index 75c0c91..00cdb06 100644 --- a/src/lib/core/prover/index.ts +++ b/src/lib/core/prover/index.ts @@ -4,6 +4,7 @@ import { buildBatchPayload, retry } from '../../utils'; import { getAllTransactionRecords, getTransactionByNonce } from '../../../store/sqlite'; import type { BatchTransactionPayload, DecodedPayload, Hooks, TransactionRecord } from '../../../types'; import { createLogger } from '../../../utils/logger'; +import { managedRole, publishManaged } from '../../../central/distribution'; const PREFERRED_PROVER_NODE = process.env.PREFERRED_PROVER_NODE; const logger = createLogger('[prover-job]'); @@ -12,6 +13,7 @@ export default class implements Hooks { private proverSchedule: string = process.env.PROVER_CRONSCHEDULE || '0 0 * * *'; // default to every 24 hours async onAfterInit() { + if (process.env.CONSOLE_ROLE === 'gateway') return; if (!PREFERRED_PROVER_NODE) { logger.warn('No PREFERRED_PROVER_NODE configured. Prover hooks will not be registered.'); return; @@ -106,6 +108,8 @@ export default class implements Hooks { } async sendPendingTransactionsToProver(proverURL: string, pendingTransactions: TransactionRecord[]) { + if (managedRole()) return publishManaged(`prover:${proverURL}`, pendingTransactions, + records => this.sendTransactionsToProver(proverURL, buildBatchPayload(records))); logger.info('[info] Sending', pendingTransactions.length, 'transactions to prover at', proverURL); const requestPayload = buildBatchPayload(pendingTransactions); diff --git a/src/lib/core/streamr/index.ts b/src/lib/core/streamr/index.ts index a3d7fae..aa25d86 100644 --- a/src/lib/core/streamr/index.ts +++ b/src/lib/core/streamr/index.ts @@ -5,6 +5,7 @@ import { buildBatchPayload, retry } from "../../utils"; import type { Hooks, TransactionRecord } from "../../../types"; import { getSyncedPendingTransactions } from "../../sync"; import { createLogger } from "../../../utils/logger"; +import { managedRole, publishManaged } from '../../../central/distribution'; const logger = createLogger("[streamr]"); @@ -19,6 +20,7 @@ export default class implements Hooks { private cronSchedule: string = process.env.STREAMR_CRONSCHEDULE || "0 * * * *"; async onAfterInit() { + if (process.env.CONSOLE_ROLE === 'gateway') return; logger.info( "Registering Streamr cron job... Schedule: ", this.cronSchedule, @@ -57,6 +59,12 @@ export default class implements Hooks { } async publishPendingTransactionsToStreamr(STREAMR_STREAM_ID: string, pendingTransactions: TransactionRecord[]) { + if (managedRole()) return publishManaged(`streamr:${STREAMR_STREAM_ID}`, pendingTransactions, + records => this.publishBatch(STREAMR_STREAM_ID, records)); + return this.publishBatch(STREAMR_STREAM_ID, pendingTransactions); + } + + private async publishBatch(STREAMR_STREAM_ID: string, pendingTransactions: TransactionRecord[]) { const streamrClient = new StreamrClient({ auth: { privateKey: ETHEREUM_PRIVATE_KEY!, diff --git a/src/lib/core/streamr/ui.ts b/src/lib/core/streamr/ui.ts index 42501ba..48d9336 100644 --- a/src/lib/core/streamr/ui.ts +++ b/src/lib/core/streamr/ui.ts @@ -1,5 +1,6 @@ import { getAllTransactionRecords } from "../../../store/sqlite"; import { buildBatchPayload, retry } from "../../utils"; +import { managedRole, publishManaged } from '../../../central/distribution'; import type { UIHooks, UIAppIcon, UIAppWindow, UIAction, TransactionRecord } from "../../../types"; import { StreamrClient } from "@streamr/sdk"; import { createLogger } from "../../../utils/logger"; @@ -76,6 +77,7 @@ export default class implements UIHooks { label: "Publish Now", buttonClass: "is-warning", handler: async () => { + if (process.env.CONSOLE_ROLE === 'gateway') return { message: 'Publication is owned by the central Console. Local reports are retained for reconciliation.' }; const pendingTransactions = await this.getPendingTransactions(); if (pendingTransactions.length === 0) { @@ -94,7 +96,7 @@ export default class implements UIHooks { this.lastPublishStatus = "success"; return { - message: `Published ${pendingTransactions.length} transactions to ${this.streamIds.length} stream(s)`, + message: managedRole() ? 'Central publication checked. Previously submitted or uncertain transactions are not resubmitted.' : `Published ${pendingTransactions.length} transactions to ${this.streamIds.length} stream(s)`, data: { count: pendingTransactions.length }, }; } catch (error: any) { @@ -122,6 +124,11 @@ export default class implements UIHooks { } private async publishToStreamr(streamId: string, pendingTransactions: TransactionRecord[]) { + if (managedRole()) return publishManaged(`streamr:${streamId}`, pendingTransactions, records => this.publishBatch(streamId, records)); + return this.publishBatch(streamId, pendingTransactions); + } + + private async publishBatch(streamId: string, pendingTransactions: TransactionRecord[]) { if (!ETHEREUM_PRIVATE_KEY) { throw new Error("Missing ETHEREUM_PRIVATE_KEY"); } diff --git a/src/lib/mqtt-config.ts b/src/lib/mqtt-config.ts new file mode 100644 index 0000000..e1a7e7e --- /dev/null +++ b/src/lib/mqtt-config.ts @@ -0,0 +1,9 @@ +/** Existing Console broker settings, shared with the opt-in agent. */ +export function mqttConnection(): string | { host: string; port: number } { + if (!process.env.MQTT_URL) return { host: process.env.CHIRPSTACK_HOST || 'localhost', port: 1883 }; + try { + const url = new URL(process.env.MQTT_URL); + if (!['mqtt:', 'mqtts:', 'ws:', 'wss:'].includes(url.protocol) || !url.hostname || url.hash) throw new Error(); + return process.env.MQTT_URL; + } catch { throw new Error('MQTT_URL must be a valid mqtt, mqtts, ws or wss broker URL.'); } +} diff --git a/src/lib/utils.ts b/src/lib/utils.ts index 1e1b0c0..8a44a90 100644 --- a/src/lib/utils.ts +++ b/src/lib/utils.ts @@ -11,6 +11,8 @@ import type { UIAction, } from "../types"; import { createLogger } from "../utils/logger"; +import { publishManaged } from '../central/distribution'; +import { decodePayload } from './decode'; const logger = createLogger("[utils]"); @@ -71,6 +73,22 @@ export async function notifyHook(hook: K, ...args: Parame catch (error) { logger.error(`Notification hook ${hook} failed:`, error); } } +/** Managed roles publish centrally with a durable claim per extension and nonce. + * Built-in cron/UI publishers additionally share destination-level claims. */ +export async function distributeManaged(records: TransactionRecord[]): Promise { + if (process.env.CONSOLE_ROLE !== 'central') return; + for (const [index, extension] of extensions.entries()) { + const publish = extension.onTransactionDistribution; + if (!publish) continue; + for (const record of records) { + try { + await publishManaged(`hook:${defaultConfigurations.modules[index]}`, [record], async () => + publish.call(extension, record.identifier, decodePayload(Buffer.from(record.raw, 'hex')), records)); + } catch { logger.error('Managed distribution remains uncertain; automatic resubmission is blocked.'); } + } + } +} + /** * Load UI extensions from configuration file * Looks for 'uiModules' key in config, which maps module IDs to their paths diff --git a/src/services/grpc.ts b/src/services/grpc.ts index e8f6565..fcfa53c 100644 --- a/src/services/grpc.ts +++ b/src/services/grpc.ts @@ -1,11 +1,15 @@ import { credentials, Metadata } from "@grpc/grpc-js"; import { DeviceServiceClient } from "@chirpstack/chirpstack-api/api/device_grpc_pb"; -import { DeviceQueueItem, EnqueueDeviceQueueItemRequest } from "@chirpstack/chirpstack-api/api/device_pb"; +import { DeviceQueueItem, EnqueueDeviceQueueItemRequest, GetDeviceQueueItemsRequest } from "@chirpstack/chirpstack-api/api/device_pb"; +import type { ChirpstackQueue } from '../central/coordinator'; import { createLogger } from "../utils/logger"; const logger = createLogger("[grpc]"); -const deviceService = new DeviceServiceClient(`${process.env.CHIRPSTACK_HOST}:8080`, credentials.createInsecure()); +let deviceService: DeviceServiceClient | undefined; +function client(): DeviceServiceClient { + return deviceService ??= new DeviceServiceClient(`${process.env.CHIRPSTACK_HOST}:8080`, credentials.createInsecure()); +} const metadata = new Metadata(); metadata.set("authorization", "Bearer " + process.env.API_TOKEN); @@ -21,10 +25,31 @@ export function enqueue(devEui: string, data: number[]): Promise { enqueueReq.setQueueItem(item); return new Promise((resolve, reject) => { - deviceService.enqueue(enqueueReq, metadata, (err, resp) => { + client().enqueue(enqueueReq, metadata, (err, resp) => { if (err || !resp) { reject(err || new Error("Missing enqueue response")); return; } logger.info(`${data} has been enqueued with id: ` + resp.getId()); resolve(); }); }); } + +/** Agent-only adapter: fixed FPort 2 replies, queue inspection and a bounded RPC + * deadline. A deadline error is ambiguous; the coordinator never retries it. */ +export const managedQueue: ChirpstackQueue = { + list: devEui => new Promise((resolve,reject) => { + const request=new GetDeviceQueueItemsRequest();request.setDevEui(devEui); + client().getQueue(request,metadata,{deadline:Date.now()+8000},(error,response)=>{ + if(error||!response){reject(new Error('ChirpStack queue inspection failed.'));return;} + resolve(response.getResultList().map(item=>({id:item.getId(),devEui:item.getDevEui(),fPort:item.getFPort(),confirmed:item.getConfirmed(),bytes:Array.from(item.getData_asU8())}))); + }); + }), + enqueue: decision => new Promise((resolve,reject)=>{ + if(decision.fPort!==2||decision.confirmed||![9,13].includes(decision.bytes.length)||![0,1].includes(decision.bytes[0])){reject(new Error('Invalid state reply.'));return;} + const item=new DeviceQueueItem();item.setDevEui(decision.devEui);item.setFPort(2);item.setConfirmed(false);item.setData(Uint8Array.from(decision.bytes)); + const request=new EnqueueDeviceQueueItemRequest();request.setQueueItem(item); + client().enqueue(request,metadata,{deadline:Date.now()+8000},(error,response)=>{ + if(error||!response){reject(new Error('ChirpStack enqueue outcome is uncertain.'));return;} + resolve(response.getId()); + }); + }), +}; diff --git a/src/services/mqtt.ts b/src/services/mqtt.ts index a23b657..c1bd9c5 100644 --- a/src/services/mqtt.ts +++ b/src/services/mqtt.ts @@ -3,6 +3,7 @@ import { randomUUID } from 'crypto'; import { applicationId } from '../lib/chirpstack-config'; import { enqueue } from './grpc'; import type { DownlinkSink } from './downlink'; +import { managedBilling } from '../central/billing-context'; import { encode } from '../lib/encode'; import { getAllTransactionRecords, getMeterByDevEui, getMeterByPublicKey, @@ -22,14 +23,8 @@ const meterLocks = new Set(); let collectorClient: MqttClient | undefined; // Existing process-level broker configuration, also reused by the opt-in agent. -export function mqttConnection(): string | { host: string; port: number } { - if (!process.env.MQTT_URL) return { host: process.env.CHIRPSTACK_HOST || 'localhost', port: 1883 }; - try { - const url = new URL(process.env.MQTT_URL); - if (!['mqtt:', 'mqtts:', 'ws:', 'wss:'].includes(url.protocol) || !url.hostname || url.hash) throw new Error(); - return process.env.MQTT_URL; - } catch { throw new Error('MQTT_URL must be a valid mqtt, mqtts, ws or wss broker URL.'); } -} +export { mqttConnection } from '../lib/mqtt-config'; +import { mqttConnection } from '../lib/mqtt-config'; // Optional arguments are dependency injection for integration tests, not configuration. export async function handleUplinks(connection = mqttConnection(), collect = handleMessage): Promise { if (collectorClient) return true; @@ -157,7 +152,13 @@ export async function handleMessage(blob: Buffer, downlink: DownlinkSink = chirp } finally { // Delivery services run after the downlink attempt and cannot prevent it. // notifyHook isolates failures so later delivery extensions still run. - if (newTransaction) void notifyHook('onTransactionDistribution', meter.tokenId, decoded, getAllTransactionRecords()); + if (newTransaction) { + const context = managedBilling.getStore(); + if (context) { + const record = getTransactionByNonce(decoded.nonce, meter.tokenId); + if (record) context.distribution.push(record); + } else void notifyHook('onTransactionDistribution', meter.tokenId, decoded, getAllTransactionRecords()); + } } } catch (error) { log.error('Error handling MQTT message:', error); diff --git a/src/store/sqlite.ts b/src/store/sqlite.ts index 6531536..92f919a 100644 --- a/src/store/sqlite.ts +++ b/src/store/sqlite.ts @@ -3,6 +3,7 @@ import Database from "better-sqlite3"; import type { Database as DatabaseType, Statement as DatabaseStatementType } from "better-sqlite3"; import { MeterRecord, TransactionRecord } from "../types"; import { createLogger } from "../utils/logger"; +import type { BillingSnapshot } from '../central/processor'; const logger = createLogger("[sqlite]"); @@ -29,6 +30,9 @@ export default function setupDatabase(databaseName = "m3tering.db") { if (db?.open) db.close(); fs.mkdirSync("./.data", { recursive: true }); db = new Database(`./.data/${databaseName}`, {}); + if(process.env.CONSOLE_ROLE==='central'||process.env.CONSOLE_ROLE==='gateway'){ + db.pragma('journal_mode = WAL');db.pragma('synchronous = FULL');db.pragma('busy_timeout = 5000'); + } initializeTransactionsTable(); initializeMetersTable(); @@ -276,6 +280,32 @@ export function getAllTransactionRecords(): TransactionRecord[] { } } +/** Managed reconciliation must distinguish an absent meter from a database + * failure; unlike legacy UI lookups, errors here are deliberately propagated. */ +export function readBillingSnapshot(devEui:string):BillingSnapshot { + const meter=getMeterByDevEuiQuery.get(devEui) as MeterRecord|undefined; + if(!meter)return {meter:null,transactions:[]}; + const transaction=getTransactionByNonceQuery.get(meter.latestNonce,meter.tokenId) as TransactionRecord|undefined; + return {meter,transactions:transaction?[transaction]:[]}; +} + +/** Authenticated managed-role reconciliation only. Validation of signatures and + * token ownership happens in the caller before this all-or-nothing merge. */ +export function mergeBillingSnapshot(snapshot: BillingSnapshot): void { + if (!snapshot.meter) return; + const meter = snapshot.meter; + db.transaction(() => { + const existing = getMeterByPublicKeyQuery.get(meter.publicKey) as MeterRecord|undefined; + if (existing && existing.tokenId !== meter.tokenId) throw new Error('Conflicting meter registration.'); + for (const record of snapshot.transactions) { + const previous = getTransactionByNonceQuery.get(record.nonce, record.identifier) as TransactionRecord|undefined; + if (previous && previous.raw !== record.raw) throw new Error('Conflicting transaction requires reconciliation; data was not overwritten.'); + if (!previous) createTransactionQuery.run(record); + } + insertMeterQuery.run({ ...meter, latestNonce: Math.max(existing?.latestNonce ?? -1, meter.latestNonce) }); + })(); +} + export function pruneTransactionsBefore(nonce: number, meterNumber: number) { try { const result = db diff --git a/src/utils/logger.ts b/src/utils/logger.ts index cd3f7be..6d20ad3 100644 --- a/src/utils/logger.ts +++ b/src/utils/logger.ts @@ -1,20 +1,48 @@ export interface Logger { - info: (message: string, ...args: any[]) => void; - warn: (message: string, ...args: any[]) => void; - error: (message: string, ...args: any[]) => void; - debug: (message: string, ...args: any[]) => void; + info: (message: string, ...args: unknown[]) => void; + warn: (message: string, ...args: unknown[]) => void; + error: (message: string, ...args: unknown[]) => void; + debug: (message: string, ...args: unknown[]) => void; } export interface MeterContext { devEui?: string; } +/** Managed roles cross an Internet trust boundary. Retain operational context, + * but never dump provider errors, credentials, or signed meter envelopes. */ +function managedLog(value:unknown,depth=0):unknown { + if(value instanceof Error)return '[operation failed; details withheld]'; + if(typeof value==='string'){ + let text=value; + for(const [name,secret] of Object.entries(process.env)){ + if(secret&&/(?:PASSWORD|SECRET|TOKEN|PRIVATE_KEY|CREDENTIAL)/i.test(name))text=text.split(secret).join('[redacted]'); + } + return text.replace(/(?:0x)?[a-fA-F0-9]{64,}/g,'[redacted bytes]') + .replace(/[A-Za-z0-9+/]{80,}={0,2}/g,'[redacted payload]') + .replace(/(https?:\/\/)[^/\s@]+@/gi,'$1[redacted]@') + .slice(0,512); + } + if(typeof value==='number'||typeof value==='boolean'||value===null||value===undefined)return value; + if(depth>2||Array.isArray(value))return '[details withheld]'; + if(typeof value==='object'){ + const allowed=new Set(['gateway','id','state','code','status','pending','uncertain','reconciled','superseded','count']); + return Object.fromEntries(Object.entries(value).filter(([key])=>allowed.has(key)).map(([key,item])=>[key,managedLog(item,depth+1)])); + } + return '[details withheld]'; +} export function createLogger(prefix: string): Logger { + const write=(level:string,message:string,args:unknown[])=>{ + const managed=process.env.CONSOLE_ROLE==='central'||process.env.CONSOLE_ROLE==='gateway'; + const text=`[${level}] ${prefix} ${message}`; + const output=managed?[managedLog(text),...args.map(arg=>managedLog(arg))]:[text,...args]; + if(level==='error')console.error(...output);else console.log(...output); + }; return { - info: (message: string, ...args: any[]) => console.log(`[info] ${prefix} ${message}`, ...args), - warn: (message: string, ...args: any[]) => console.log(`[warn] ${prefix} ${message}`, ...args), - error: (message: string, ...args: any[]) => console.error(`[error] ${prefix} ${message}`, ...args), - debug: (message: string, ...args: any[]) => console.log(`[debug] ${prefix} ${message}`, ...args), + info:(message,...args)=>write('info',message,args), + warn:(message,...args)=>write('warn',message,args), + error:(message,...args)=>write('error',message,args), + debug:(message,...args)=>write('debug',message,args), }; } diff --git a/tests/services/managed-logging.test.ts b/tests/services/managed-logging.test.ts new file mode 100644 index 0000000..06bed07 --- /dev/null +++ b/tests/services/managed-logging.test.ts @@ -0,0 +1,17 @@ +import { createLogger } from '../../src/utils/logger'; + +test('managed logs retain operation IDs but redact secrets, provider errors and signed payloads',()=>{ + const before={...process.env}; + process.env.CONSOLE_ROLE='central';process.env.API_TOKEN='test-fixture-api-secret'; + process.env.CENTRAL_ADMIN_PASSWORD='test-fixture-password'; + const log=jest.spyOn(console,'log').mockImplementation(()=>{}),error=jest.spyOn(console,'error').mockImplementation(()=>{}); + try{ + const logger=createLogger('[test]'); + logger.info('Operation status',{gateway:'gateway-test',id:'event-1',state:'uncertain',raw:'ab'.repeat(106),publicKey:'cd'.repeat(32)}); + logger.error('API test-fixture-api-secret',{password:'test-fixture-password',credential:'sensitive-credential'},new Error('sensitive-provider-response')); + logger.info(`Signed payload ${'ab'.repeat(74)}`); + const output=JSON.stringify([...log.mock.calls,...error.mock.calls]); + expect(output).toContain('event-1');expect(output).toContain('uncertain'); + for(const secret of ['test-fixture-api-secret','test-fixture-password','sensitive-credential','sensitive-provider-response','ab'.repeat(74),'cd'.repeat(32)])expect(output).not.toContain(secret); + }finally{log.mockRestore();error.mockRestore();process.env=before;} +}); diff --git a/tests/services/managed-uplinks.test.ts b/tests/services/managed-uplinks.test.ts new file mode 100644 index 0000000..479c165 --- /dev/null +++ b/tests/services/managed-uplinks.test.ts @@ -0,0 +1,176 @@ +import fs from 'fs'; +import os from 'os'; +import path from 'path'; +import { OperationJournal } from '../../src/central/operations'; +import { DurableProcessor, Decider } from '../../src/central/processor'; +import { UplinkCoordinator, QueueItem } from '../../src/central/coordinator'; +import type { DownlinkSink } from '../../src/services/downlink'; +import type { UplinkEvent } from '../../src/central/protocol'; + +const gateway='gateway-test'; +function event(id='event-1',device='0102030405060708'):UplinkEvent { + const bytes=Buffer.alloc(74);bytes.writeUInt32BE(1);bytes.writeUInt32BE(1000000,4); + return {deduplicationId:id,fPort:2,fCnt:Number(id.split('-').at(-1))||1,time:'2026-11-17T12:00:00Z', + deviceInfo:{applicationId:'11111111-1111-4111-8111-111111111111',devEui:device},data:bytes.toString('base64')}; +} +function setup(filename=':memory:') { + const logs:unknown[]=[]; + const journal=new OperationJournal(filename,100,entry=>logs.push(entry)); + const compute=jest.fn(async (report:UplinkEvent,sink:DownlinkSink)=>{await sink({devEui:report.deviceInfo.devEui,fPort:2,confirmed:false,bytes:[1,0,0,0,0,0,0,0,0]});}); + const localCompute=jest.fn(compute.getMockImplementation()!); + const central=new DurableProcessor(':memory:',compute), local=new DurableProcessor(':memory:',localCompute); + const items:QueueItem[]=[]; + const queue={list:jest.fn(async()=>items.slice()),enqueue:jest.fn(async decision=>{const id=`queue-${items.length}`;items.push({...decision,id});return id;})}; + const coordinator=new UplinkCoordinator(journal,central,local,queue,{centralHealthy:()=>true,timeoutMs:20}); + return {journal,central,local,compute,localCompute,queue,items,logs,coordinator,close:()=>{journal.close();central.close();local.close();}}; +} +test('central healthy: original deduplication ID produces one stored decision and one queue entry',async()=>{ + const f=setup();try { + await f.coordinator.receive(gateway,event()); + expect(f.journal.get('event-1')).toMatchObject({owner:'central',state:'enqueued',attempted:true}); + expect(f.compute).toHaveBeenCalledTimes(1);expect(f.localCompute).not.toHaveBeenCalled();expect(f.queue.enqueue).toHaveBeenCalledTimes(1); + expect(f.queue.list).toHaveBeenCalledTimes(1); + const first=await f.central.outcome(gateway,'event-1'); + expect(await f.central.commit(gateway,'event-1')).toEqual(first); + expect(f.compute).toHaveBeenCalledTimes(1); + }finally{f.close();} +}); +test('Console down before accept: local decides; restored central never reprocesses this ID',async()=>{ + const f=setup();try { + jest.spyOn(f.central,'offer').mockRejectedValue(new Error('offline')); + await f.coordinator.receive(gateway,event()); + expect(f.journal.get('event-1')).toMatchObject({owner:'local',state:'enqueued'}); + expect(f.localCompute).toHaveBeenCalledTimes(1);expect(f.compute).not.toHaveBeenCalled(); + await f.coordinator.receive(gateway,event());expect(f.queue.enqueue).toHaveBeenCalledTimes(1); + }finally{f.close();} +}); +test('response lost after enqueue: query stored outcome and queue; never retry an accepted reply',async()=>{ + const f=setup();try { + f.queue.enqueue.mockImplementationOnce(async decision=>{f.items.push({...decision,id:'accepted-but-response-lost'});throw new Error('response lost');}); + const lookup=jest.spyOn(f.central,'outcome'); + await f.coordinator.receive(gateway,event()); + expect(f.journal.get('event-1')?.state).toBe('uncertain'); + await f.coordinator.reconcile('event-1'); + expect(lookup).toHaveBeenCalledWith(gateway,'event-1');expect(f.queue.list).toHaveBeenCalledTimes(2); + expect(f.queue.enqueue).toHaveBeenCalledTimes(1); + expect(f.journal.get('event-1')).toMatchObject({state:'queue-observed',queueId:'accepted-but-response-lost'}); + expect(f.journal.counts(gateway)).toMatchObject({uncertain:1,reconciled:1,pending:0}); + expect(JSON.stringify(f.logs)).not.toContain(event().data); + }finally{f.close();} +}); +test('empty queue after a lost response is not evidence of failed delivery and never creates OFF',async()=>{ + const f=setup();try { + f.queue.enqueue.mockRejectedValueOnce(new Error('response lost after delivery')); + await f.coordinator.receive(gateway,event());await f.coordinator.reconcile('event-1');await f.coordinator.reconcile('event-1'); + expect(f.queue.enqueue).toHaveBeenCalledTimes(1);expect(f.queue.enqueue.mock.calls[0][0].bytes[0]).toBe(1); + expect(f.journal.get('event-1')?.state).toBe('uncertain');expect(f.localCompute).not.toHaveBeenCalled(); + }finally{f.close();} +}); +test('duplicate MQTT delivery, including concurrent deliveries, cannot recompute or enqueue twice',async()=>{ + const f=setup();try { + await Promise.all([f.coordinator.receive(gateway,event()),f.coordinator.receive(gateway,event()),f.coordinator.receive(gateway,event())]); + expect(f.compute).toHaveBeenCalledTimes(1);expect(f.queue.enqueue).toHaveBeenCalledTimes(1); + expect(()=>f.journal.receive('another-gateway',event())).toThrow('conflicts'); + expect(()=>f.journal.receive(gateway,{...event(),data:Buffer.alloc(74,1).toString('base64')})).toThrow('conflicts'); + }finally{f.close();} +}); +test('uncertain report overtaken by next report is dropped and only the new reply can enqueue',async()=>{ + const f=setup();try { + f.queue.list.mockRejectedValueOnce(new Error('queue unavailable')); + await f.coordinator.receive(gateway,event());expect(f.journal.get('event-1')?.state).toBe('uncertain'); + await f.coordinator.receive(gateway,event('event-2')); + await f.coordinator.reconcile('event-1'); + expect(f.journal.get('event-1')).toMatchObject({state:'superseded',attempted:false}); + expect(f.journal.get('event-2')?.state).toBe('enqueued'); + expect(f.queue.enqueue).toHaveBeenCalledTimes(1);expect(f.journal.counts(gateway).superseded).toBe(1); + }finally{f.close();} +}); +test('new report received during an old queue read prevents the old enqueue',async()=>{ + const f=setup();let release!:(queue:QueueItem[])=>void; + try { + f.queue.list.mockImplementationOnce(()=>new Promise(resolve=>{release=resolve;})); + const old=f.coordinator.receive(gateway,event()); + for(let i=0;i<20&&!release;i++)await Promise.resolve(); + expect(release).toBeDefined(); + await f.coordinator.receive(gateway,event('event-2'));release([]);await old; + expect(f.journal.get('event-1')?.state).toBe('superseded');expect(f.queue.enqueue).toHaveBeenCalledTimes(1); + }finally{f.close();} +}); +test('lost Console decision response is recovered by ID; local never takes committed ownership',async()=>{ + const f=setup();try { + const commit=f.central.commit.bind(f.central); + jest.spyOn(f.central,'commit').mockImplementationOnce(async(g,id)=>{await commit(g,id);throw new Error('lost response');}); + await f.coordinator.receive(gateway,event());expect(f.journal.get('event-1')?.state).toBe('uncertain'); + await f.coordinator.reconcile('event-1'); + expect(f.journal.get('event-1')?.state).toBe('enqueued');expect(f.compute).toHaveBeenCalledTimes(1);expect(f.localCompute).not.toHaveBeenCalled(); + }finally{f.close();} +}); +test('restart after enqueue started retains the at-most-once fence and counters',async()=>{ + const dir=fs.mkdtempSync(path.join(os.tmpdir(),'agent-journal-'));const file=path.join(dir,'state.db'); + let f=setup(file); + try { + f.queue.enqueue.mockRejectedValueOnce(new Error('interrupted')); + await f.coordinator.receive(gateway,event());f.journal.close(); + const journal=new OperationJournal(file);const second=new UplinkCoordinator(journal,f.central,f.local,f.queue,{centralHealthy:()=>true,timeoutMs:20}); + await second.receive(gateway,event());expect(f.queue.enqueue).toHaveBeenCalledTimes(1);expect(journal.counts(gateway).uncertain).toBe(1); + journal.close();f.central.close();f.local.close(); + }finally{fs.rmSync(dir,{recursive:true,force:true});} +}); +test('both Consoles down buffers reports durably and processes latest reports per device on recovery',async()=>{ + const f=setup();try { + const c=jest.spyOn(f.central,'offer').mockRejectedValue(new Error('offline')); + const l=jest.spyOn(f.local,'offer').mockRejectedValue(new Error('offline')); + await f.coordinator.receive(gateway,event());await f.coordinator.receive(gateway,event('event-2','0202030405060708')); + expect(f.queue.enqueue).not.toHaveBeenCalled();expect(f.journal.pending()).toHaveLength(2); + c.mockRestore();l.mockRestore();await f.coordinator.drain(); + expect(f.queue.enqueue).toHaveBeenCalledTimes(2); + expect(f.queue.enqueue.mock.calls.map(([decision])=>decision.devEui)).toEqual(['0102030405060708','0202030405060708']); + }finally{f.close();} +}); +test('processor restart returns its stored decision and never reruns the billing handler',async()=>{ + const dir=fs.mkdtempSync(path.join(os.tmpdir(),'decider-ledger-')),file=path.join(dir,'state.db'); + const compute=jest.fn(async(report:UplinkEvent,sink:DownlinkSink)=>sink({devEui:report.deviceInfo.devEui,fPort:2,confirmed:false,bytes:[1,0,0,0,0,0,0,0,0]})); + let processor=new DurableProcessor(file,compute); + try { + await processor.offer(gateway,event());const original=await processor.commit(gateway,'event-1');processor.close(); + processor=new DurableProcessor(file,compute);await processor.offer(gateway,event()); + expect(await processor.commit(gateway,'event-1')).toEqual(original);expect(compute).toHaveBeenCalledTimes(1); + }finally{processor.close();fs.rmSync(dir,{recursive:true,force:true});} +}); + +test('several newer reports cannot bypass an older committed computation while its response is held',async()=>{ + const f=setup();let release!:()=>void; + const waiting=new Promise(resolve=>{release=resolve;}); + const implementation=f.compute.getMockImplementation()!; + f.compute.mockImplementationOnce(async(report,sink)=>{await waiting;await implementation(report,sink);}); + try{ + const old=f.coordinator.receive(gateway,event()); + for(let i=0;i<20&&!f.compute.mock.calls.length;i++)await Promise.resolve(); + await f.coordinator.receive(gateway,event('event-2')); + await f.coordinator.receive(gateway,event('event-3')); + expect(f.compute).toHaveBeenCalledTimes(1); + expect(f.queue.enqueue).not.toHaveBeenCalled(); + expect(f.journal.get('event-3')?.owner).toBeNull(); + release();await old;await f.coordinator.drain(); + expect(f.compute).toHaveBeenCalledTimes(2); + expect(f.queue.enqueue).toHaveBeenCalledTimes(1); + expect(f.journal.get('event-1')?.state).toBe('superseded'); + expect(f.journal.get('event-2')?.state).toBe('superseded'); + expect(f.journal.get('event-3')?.state).toBe('enqueued'); + }finally{release();await f.coordinator.stop();f.close();} +}); + +test('a committed slow Console cannot trigger fallback after the decision deadline',async()=>{ + jest.useFakeTimers();const f=setup();let release!:()=>void; + const waiting=new Promise(resolve=>{release=resolve;});const implementation=f.compute.getMockImplementation()!; + f.compute.mockImplementationOnce(async(report,sink)=>{await waiting;await implementation(report,sink);}); + try{ + const pending=f.coordinator.receive(gateway,event()); + await jest.advanceTimersByTimeAsync(21);await pending; + expect(f.journal.get('event-1')).toMatchObject({state:'uncertain',owner:'central'}); + expect(f.localCompute).not.toHaveBeenCalled();expect(f.queue.enqueue).not.toHaveBeenCalled(); + release();await jest.advanceTimersByTimeAsync(0);await f.coordinator.reconcile('event-1'); + expect(f.compute).toHaveBeenCalledTimes(1);expect(f.queue.enqueue).toHaveBeenCalledTimes(1); + expect(f.journal.counts(gateway)).toMatchObject({uncertain:1,reconciled:1}); + }finally{release();await jest.advanceTimersByTimeAsync(0);f.close();jest.useRealTimers();} +}); diff --git a/tests/services/reconciliation.test.ts b/tests/services/reconciliation.test.ts new file mode 100644 index 0000000..5da5fc5 --- /dev/null +++ b/tests/services/reconciliation.test.ts @@ -0,0 +1,69 @@ +import fs from 'fs'; +import os from 'os'; +import path from 'path'; +import { DurableProcessor, BillingSnapshot } from '../../src/central/processor'; +import { OperationJournal } from '../../src/central/operations'; +import { PublicationStore } from '../../src/central/distribution'; +import { Replication } from '../../src/central/replication'; +import { UplinkCoordinator } from '../../src/central/coordinator'; +import type { UplinkEvent } from '../../src/central/protocol'; + +const report:UplinkEvent={deduplicationId:'replay-1',fPort:2,deviceInfo:{devEui:'0102030405060708',applicationId:'11111111-1111-4111-8111-111111111111'},data:Buffer.alloc(74).toString('base64')}; +const transaction={nonce:1,identifier:17,raw:Buffer.alloc(74).toString('hex'),receivedAt:1700000000}; +const snapshot:BillingSnapshot={meter:{devEui:report.deviceInfo.devEui,publicKey:`0x${'a'.repeat(64)}`,tokenId:17,latestNonce:1},transactions:[transaction]}; +const decision={devEui:report.deviceInfo.devEui,fPort:2 as const,confirmed:false as const,bytes:[1,0,0,0,0,0,0,0,0]}; + +test('fallback recovery replays stored outcomes idempotently without a second decision or publication',async()=>{ + const journal=new OperationJournal(':memory:');const publications=new PublicationStore(':memory:'); + const records=new Map();const publish=jest.fn(async()=>{}); + const importSnapshot=jest.fn(async(s:BillingSnapshot)=>{ + for(const t of s.transactions){const key=`${t.identifier}:${t.nonce}`;const prior=records.get(key);if(prior&&prior.raw!==t.raw)throw new Error('conflict');records.set(key,t);} + await publications.publish('fake-arweave',s.transactions,publish); + }); + const centralCompute=jest.fn(async()=>{}),localCompute=jest.fn(async(_event,sink)=>sink(decision)); + const central=new DurableProcessor(':memory:',centralCompute,()=>snapshot,importSnapshot); + const local=new DurableProcessor(':memory:',localCompute,()=>snapshot); + const reconcile=central.reconcile.bind(central); + const unavailable=jest.spyOn(central,'reconcile').mockRejectedValue(new Error('offline')); + let healthy=false; + const replication=new Replication(journal,central,local); + const queue={list:jest.fn(async()=>[]),enqueue:jest.fn(async()=>'queue-1')}; + const coordinator=new UplinkCoordinator(journal,replication.guarded('central'),replication.guarded('local'),queue, + {centralHealthy:()=>healthy,timeoutMs:50,reconcileSnapshot:(owner,outcome)=>replication.observe(owner,outcome)}); + try{ + await coordinator.receive('gateway',report); + expect(journal.get(report.deduplicationId!)?.owner).toBe('local'); + expect(journal.replays('central')).toHaveLength(1); + expect(publish).not.toHaveBeenCalled(); + unavailable.mockRestore();healthy=true; + await replication.flush('central'); + const stored=await local.outcome('gateway',report.deduplicationId!); + await reconcile('gateway',report,stored!);await reconcile('gateway',report,stored!); + await coordinator.receive('gateway',report); + expect(await central.commit('gateway',report.deduplicationId!)).toEqual(stored); + expect(records.size).toBe(1);expect(publish).toHaveBeenCalledTimes(1); + expect(centralCompute).not.toHaveBeenCalled();expect(localCompute).toHaveBeenCalledTimes(1);expect(queue.enqueue).toHaveBeenCalledTimes(1); + }finally{await coordinator.stop();journal.close();central.close();local.close();publications.close();} +}); + +test('unknown publication outcomes stay fenced across restart, independently for each destination',async()=>{ + const dir=fs.mkdtempSync(path.join(os.tmpdir(),'publication-test-')),file=path.join(dir,'state.db'); + let store=new PublicationStore(file);const send=jest.fn(async()=>{throw new Error('reply lost after remote accepted');}); + try{ + await expect(store.publish('streamr',[transaction],send)).rejects.toThrow('uncertain'); + store.close();store=new PublicationStore(file); + expect(await store.publish('streamr',[transaction],send)).toBeNull(); + const prover=jest.fn(async()=>{});await store.publish('prover',[transaction],prover);await store.publish('prover',[transaction],prover); + expect(send).toHaveBeenCalledTimes(1);expect(prover).toHaveBeenCalledTimes(1); + }finally{store.close();fs.rmSync(dir,{recursive:true,force:true});} +}); + +test('reconciliation cannot attach another device decision or meter snapshot to an event ID',async()=>{ + const processor=new DurableProcessor(':memory:',async()=>{}); + const outcome={id:report.deduplicationId!,state:'decided' as const,active:false,decision,snapshot}; + try{ + await expect(processor.reconcile('gateway',report,{...outcome,decision:{...decision,devEui:'9999999999999999'}})).rejects.toThrow('another device'); + await expect(processor.reconcile('gateway',report,{...outcome,snapshot:{...snapshot,meter:{...snapshot.meter!,devEui:'9999999999999999'}}})).rejects.toThrow('another device'); + expect(await processor.outcome('gateway',report.deduplicationId!)).toBeNull(); + }finally{processor.close();} +}); From 72970cf66d3c9188b15c291193b397c1f2353a50 Mon Sep 17 00:00:00 2001 From: "Isaac J. Newton" Date: Tue, 17 Nov 2026 15:55:52 +0000 Subject: [PATCH 5/9] feat: connect managed roles with authenticated RPC and gateway tunnels --- .env.example | 13 +++ compose.central.yaml | 37 +++++++ compose.gateway.yaml | 58 +++++++++++ deploy/Caddyfile | 7 ++ docs/centralized/deployment.md | 36 ++++++- docs/centralized/design.md | 117 ++++++++++++++++++++-- docs/centralized/test-plan.md | 36 ++++--- scripts/healthcheck.cjs | 7 +- src/agent/index.ts | 121 +++++++++++++++++++++++ src/central/auth.ts | 3 +- src/central/hub.ts | 99 +++++++++++++++++++ src/central/identity-store.ts | 20 +++- src/central/runtime.ts | 60 ++++++++++++ src/central/tunnels.ts | 145 ++++++++++++++++++++++++++++ src/index.ts | 27 +++++- src/public/css/gateways.css | 1 + src/public/js/gateways.js | 52 ++++++++++ src/services/chirpstack.ts | 13 ++- src/services/server.ts | 19 +++- src/services/socket-router.ts | 20 +++- src/services/ssh.ts | 27 ++++-- src/views/index.hbs | 5 + src/views/layouts/main.hbs | 2 + tests/services/central-link.test.ts | 88 +++++++++++++++++ tests/services/tunnels.test.ts | 90 +++++++++++++++++ tests/ui/gateways.spec.cjs | 34 +++++++ tests/ui/serve.cjs | 2 +- 27 files changed, 1088 insertions(+), 51 deletions(-) create mode 100644 compose.central.yaml create mode 100644 compose.gateway.yaml create mode 100644 deploy/Caddyfile create mode 100644 src/agent/index.ts create mode 100644 src/central/hub.ts create mode 100644 src/central/runtime.ts create mode 100644 src/central/tunnels.ts create mode 100644 src/public/css/gateways.css create mode 100644 src/public/js/gateways.js create mode 100644 tests/services/central-link.test.ts create mode 100644 tests/services/tunnels.test.ts create mode 100644 tests/ui/gateways.spec.cjs diff --git a/.env.example b/.env.example index cdb604b..e84da55 100644 --- a/.env.example +++ b/.env.example @@ -49,3 +49,16 @@ STREAMR_CRONSCHEDULE="0 * * * *" # Every hour # CENTRAL_ALLOW_INSECURE_DEVELOPMENT=false # Only explicit reverse-proxy peer IPs; forwarded headers are otherwise ignored. # CENTRAL_TRUSTED_PROXIES=127.0.0.1,::1 +# One-time token from central enrollment; remove it after the credential file exists. +# AGENT_ENROLLMENT_TOKEN=REPLACE_WITH_ONE_TIME_TOKEN +# Central bootstrap only; password must have at least 16 characters. +# CENTRAL_ADMIN_USERNAME=admin +# CENTRAL_ADMIN_PASSWORD=REPLACE_WITH_A_UNIQUE_LONG_PASSWORD +# Loopback authenticated fallback. Never publish this port through a proxy. +# GATEWAY_FALLBACK_PORT=3001 +# Gateway-owned tunnel policy; central cannot override these targets. +# AGENT_SSH_PORT=22 +# AGENT_BROWSER_ALLOW_LAN=false +# AGENT_BROWSER_PORTS=80,443,3000,8080,8090 +# Used only by compose.central.yaml's TLS proxy. +# CENTRAL_DOMAIN=console.example.invalid diff --git a/compose.central.yaml b/compose.central.yaml new file mode 100644 index 0000000..f3d7a20 --- /dev/null +++ b/compose.central.yaml @@ -0,0 +1,37 @@ +# Opt-in central test topology; supply CENTRAL_DOMAIN and central credentials. +services: + console: + image: ${CONSOLE_IMAGE:-ghcr.io/fluxion9/console:feat-centralized-console} + network_mode: host + restart: unless-stopped + env_file: [.env] + environment: + CONSOLE_ROLE: central + CONSOLE_HOST: 127.0.0.1 + CENTRAL_TRUSTED_PROXIES: 127.0.0.1,::1 + volumes: + - ./.data:/opt/app/.data + - console_extension_sources:/opt/app/src/extensions + - console_extension_builds:/opt/app/dist/extensions + healthcheck: + test: [CMD, node, scripts/healthcheck.cjs] + interval: 5s + timeout: 4s + start_period: 30s + retries: 24 + tls-proxy: + image: caddy:2-alpine + network_mode: host + restart: unless-stopped + environment: + CENTRAL_DOMAIN: ${CENTRAL_DOMAIN:?Set a DNS name for central TLS} + CONSOLE_PORT: ${PORT:-3000} + volumes: + - ./deploy/Caddyfile:/etc/caddy/Caddyfile:ro + - console_tls_data:/data + - console_tls_config:/config +volumes: + console_extension_sources: + console_extension_builds: + console_tls_data: + console_tls_config: diff --git a/compose.gateway.yaml b/compose.gateway.yaml new file mode 100644 index 0000000..022e49b --- /dev/null +++ b/compose.gateway.yaml @@ -0,0 +1,58 @@ +# Opt-in test topology. Default compose.yaml is unchanged. +services: + console: + image: ${CONSOLE_IMAGE:-ghcr.io/fluxion9/console:feat-centralized-console} + network_mode: host + restart: unless-stopped + env_file: [.env] + environment: + CONSOLE_ROLE: gateway + AGENT_CREDENTIAL_PATH: /opt/app/.data/agent/credential + FALLBACK_SECRET_PATH: /opt/app/.data/agent/fallback-secret + volumes: + - ./.data:/opt/app/.data + - console_extension_sources:/opt/app/src/extensions + - console_extension_builds:/opt/app/dist/extensions + healthcheck: + test: [CMD, node, scripts/healthcheck.cjs] + interval: 5s + timeout: 4s + start_period: 30s + retries: 24 + agent: + image: ${CONSOLE_IMAGE:-ghcr.io/fluxion9/console:feat-centralized-console} + # Agent does not initialize extensions, contracts or a blockchain wallet. + entrypoint: [node] + command: [dist/agent/index.js] + network_mode: host + restart: unless-stopped + environment: + CONSOLE_ROLE: gateway + CENTRAL_URL: ${CENTRAL_URL:?Set the central wss origin for this opt-in deployment} + CENTRAL_ALLOW_INSECURE_DEVELOPMENT: ${CENTRAL_ALLOW_INSECURE_DEVELOPMENT:-false} + AGENT_ENROLLMENT_TOKEN: ${AGENT_ENROLLMENT_TOKEN:-} + AGENT_CREDENTIAL_PATH: /opt/app/.data/agent/credential + FALLBACK_SECRET_PATH: /opt/app/.data/agent/fallback-secret + CENTRAL_DECISION_TIMEOUT_MS: ${CENTRAL_DECISION_TIMEOUT_MS:-8000} + CENTRAL_RECOVERY_HEALTHY_MS: ${CENTRAL_RECOVERY_HEALTHY_MS:-15000} + AGENT_QUEUE_LIMIT: ${AGENT_QUEUE_LIMIT:-10000} + GATEWAY_FALLBACK_PORT: ${GATEWAY_FALLBACK_PORT:-3001} + CHIRPSTACK_HOST: ${CHIRPSTACK_HOST:-localhost} + APPLICATION_ID: ${APPLICATION_ID:?Set the existing ChirpStack application ID} + API_TOKEN: ${API_TOKEN:?Set the existing ChirpStack API token} + MQTT_URL: ${MQTT_URL:-} + CHEFSTACK_URL: ${CHEFSTACK_URL:-} + CHIRPSTACK_WEB_URL: ${CHIRPSTACK_WEB_URL:-} + AGENT_SSH_PORT: ${AGENT_SSH_PORT:-22} + AGENT_BROWSER_ALLOW_LAN: ${AGENT_BROWSER_ALLOW_LAN:-false} + AGENT_BROWSER_PORTS: ${AGENT_BROWSER_PORTS:-80,443,3000,8080,8090} + volumes: + - ./.data/agent:/opt/app/.data/agent + read_only: true + tmpfs: [/tmp] + cap_drop: [ALL] + security_opt: [no-new-privileges:true] + # No Docker socket, wallet keys, contracts, or arbitrary command channel. +volumes: + console_extension_sources: + console_extension_builds: diff --git a/deploy/Caddyfile b/deploy/Caddyfile new file mode 100644 index 0000000..e308eb1 --- /dev/null +++ b/deploy/Caddyfile @@ -0,0 +1,7 @@ +# Caddy terminates TLS and forwards WebSocket upgrades. Console binds loopback. +{$CENTRAL_DOMAIN} { + reverse_proxy 127.0.0.1:{$CONSOLE_PORT:3000} { + header_up X-Forwarded-Proto https + header_up Host {http.request.host} + } +} diff --git a/docs/centralized/deployment.md b/docs/centralized/deployment.md index 80c9b02..f7a3b29 100644 --- a/docs/centralized/deployment.md +++ b/docs/centralized/deployment.md @@ -6,9 +6,9 @@ enrolled or updated during development. The implemented compatibility work removes Manager while preserving standalone collection and the default deployment interfaces. The central configuration, -identity and protocol modules are currently tested components, not connected -services. Agent, tunnels, updater and browser-engine deployment still require -integration. Do not mistake example configuration for a working rollout recipe. +identity, protocol, durable agent/fallback RPC and SSH/ChirpStack tunnels are +connected and tested with local fixtures. Signed updater and browser-engine +deployment still require integration. Do not mistake example configuration for a working rollout recipe. ## Existing standalone deployments @@ -39,9 +39,37 @@ Enrollment credentials are single-use and expire. Long-lived agent secrets must never appear in URLs, Compose command arguments, logs, or git. Rotation overlaps old and new credentials for two minutes and ends the overlap on acknowledgment. Revocation must close the active connection as well as rejecting authentication. -The connection integration is not implemented yet. +The connection registry now closes revoked sessions and fences replaced links. The future signing trust policy must constrain registry/repository, workflow identity and allowed refs; enabling a test ref must be explicit on the gateway. No unsigned updater fallback is acceptable. Automatic rollout and systemd installation instructions will be added only with their tested implementations. + +## Test topology files now present + +`compose.central.yaml` defines the loopback-bound Console plus a Caddy TLS proxy, +using explicit loopback trusted peers. `compose.gateway.yaml` defines the local +Console and agent using the same image and host network. The agent receives only +its MQTT/ChirpStack and connection settings, not blockchain wallet environment +variables, and mounts only its own state directory. No Docker socket is mounted. +Both files are opt-in and have passed Compose configuration validation with fake +values; neither has been deployed. Their default feature image tag is a planned +branch tag, not an assertion that this branch has been published. + +Caddy configuration follows its [reverse proxy documentation](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy). +Central health checking probes the login entry point over the trusted loopback +peer; it does not make `/healthz` or application APIs public. Gateway/standalone +health checking remains unchanged. + +The agent entry point is `node dist/agent/index.js`. It deliberately bypasses the +Console extension installer: the agent never initializes contracts or cron +publishers. Both processes need access to an owner-only fallback secret; the +agent creates its credential atomically after enrollment. File ownership must +match the runtime user (the current image defaults to root). Creating those files +as a different host user and mounting them into a root process is intentionally +rejected, even if their permissions are 0600. + +Do not switch an operating gateway to these files yet. Browser containment, signed +updater, end-to-end image checks and the remaining deployment instructions are +still incomplete. The current files are for review and isolated testing only. diff --git a/docs/centralized/design.md b/docs/centralized/design.md index c6f7146..f570d87 100644 --- a/docs/centralized/design.md +++ b/docs/centralized/design.md @@ -19,36 +19,90 @@ monitoring subscription, command catalogue, persistence or UI. Existing database tables remain untouched. Legacy Manager configuration produces one warning with no values. Shared application UUID validation moves to `lib/chirpstack-config`. -## Single-decider safety: decision required +## Single-decider safety: approved rule The baseline commits transactions before calling enqueue and invokes distribution after the attempt. ChirpStack enqueue supplies no idempotency key. If a reply is lost, neither retrying nor handing the report to another decider is safe merely because a deadline expired. A network partition does not fence the remote worker. -The proposed safe rule is durable ownership before side effects, with uncertain +The implemented safe rule is durable ownership before side effects, with uncertain committed events held for reconciliation. Fallback is permitted before ownership is committed; a late offer cannot regain ownership. Before an enqueue call the agent must durably mark the attempt; an interrupted attempt cannot be retried automatically. This guarantees at-most-one attempt, at the cost of potentially -missing a downlink after a crash. An 8-second deadline would bound normal offer +missing a downlink after a crash. An 8-second deadline bounds normal offer waiting, not grant permission to duplicate a committed operation. -**Pending user clarification:** may uncertain events be held instead of falling -back/retrying automatically? The requested unconditional deadline fallback and -exactly-one side effects cannot both be promised with the current external APIs. -Do not enable a billing failover path until this tradeoff is agreed. +The user approved holding uncertain operations once processing or enqueueing has +begun, and fallback only before ownership is committed. The ChirpStack +`deduplicationId` is mandatory end to end. Both processors return their stored +outcome for that ID; neither recomputes a decision after a processing claim. + +The agent first offers an event without side effects, then durably chooses a +decider before sending commit. An unanswered offer can fall back; an unanswered +commit cannot. Reconciliation queries the chosen Console by ID and inspects the +device queue before any enqueue. The enqueue-attempt fence is persisted BEFORE +the gRPC call. An empty queue after a lost response can mean delivery, so it never +authorizes a retry. A newly observed matching queue entry is recorded as +`queue-observed`, not proof of command execution or unique attribution. + +The next distinct report supersedes the previous unresolved reply. Checks after +every await prevent a late decision or queue inspection from sending that reply. +Already committed billing records are not deleted or rewritten. If an older +computation may still be writing records, its reply is dropped immediately, but +the newer report cannot switch deciders until its billing snapshot is reconciled. +This prevents conflicting signed values for the same nonce across two databases. +Uncertainty itself never creates an OFF reply. The ordinary revenue/owed hook +retains its existing fail-closed behavior for an actual new decision. + +Uncertain, reconciled and superseded counts are durable and included in gateway +health and the central selector/status panel. Logs contain event IDs and statuses, +not signed payloads, keys or credentials. Completed IDs remain tombstones. The +journal has a hard configured capacity; a full journal stops ingestion instead of +evicting deduplication state and making old events actionable again. + +### Agent failure and buffering decision + +The gateway Console does not autonomously take over MQTT when the agent process +dies. Docker restarts the agent; MQTT uses QoS 1 with a persistent, stable session +and the agent's disk journal survives. This deliberately chooses the alternative +permitted in section 3.5 of the task: automatic independent takeover would need +cross-process fencing over the same enqueue journal and could duplicate commands. +Operators can deliberately return the deployment to standalone after stopping the +agent and reconciling its journal. No hidden lease timeout creates a second +subscriber. While both Consoles are down, the latest unresolved report for each +device remains buffered in arrival order; the user's newer-report rule supersedes +older unresolved reports from that same device. ## Distribution boundary Chain-confirmed nonce filtering is useful but is not external publication idempotency. Arweave, Streamr and prover retries can repeat an unconfirmed -publication. The proposed managed-mode policy is central-only publication, +publication. The implemented managed-mode policy is central-only publication, including cron and UI actions, with durable per-module claims and reconciliation records. Local billing can persist reports during an outage but must not independently publish them. An uncertain external publication requires the same explicit availability tradeoff; claiming exactly-once from an in-memory Set or -SQLite flag alone would be incorrect. Standalone behavior must remain unchanged. +SQLite flag alone would be incorrect. Standalone behavior remains unchanged. + +`managed_publications` claims `(destination, tokenId, nonce)` before calling an +external publisher. A lost result is marked uncertain and never automatically +submitted again, even after restart. Arweave uses a destination claim; prover and +Streamr cron/UI paths share their respective destination claims. Extension hook +claims are separate so an interrupted extension is not called twice. The central +recovery dispatcher synchronizes with chain and excludes confirmed nonces before +trying pending records. Gateway cron and UI publishing are suppressed. Custom +third-party cron publishers must adopt the same guard before being enabled in +managed roles; arbitrary extension code cannot be made externally idempotent by +a wrapper. This guarantees at-most-one attempt, not guaranteed delivery. + +Fallback snapshots are replayed through a persistent agent outbox. The receiving +Console verifies signatures and contract token ownership, rejects conflicting +raw records for a nonce, and bounds nonce advancement by the chain, existing +state and contiguous signed records. A decider cannot accept a new report until +its replay backlog has been applied. An older committed handler remains a fence +even if several intervening, unowned reports have already been superseded. ## Browser approach under evaluation @@ -78,3 +132,48 @@ The local host is AMD64; ARM64 runtime resource measurements require an ARM64 test environment. Measurements must not be estimated and presented as observed. Existing workflow publishing conventions are preserved; attestations will be additive and run only when images are actually published. + +## Integrated transport and authentication + +The agent connects to `/agent` using an Authorization header. Browser sessions +are not accepted as agent credentials. The versioned operation RPC separates +`offer`, `commit`, `outcome` and `reconcile`; every envelope carries the original +ChirpStack ID and a transport request ID. The authenticated connection supplies +the gateway identity, never the message body. Duplicate commits return durable +outcomes. The loopback fallback uses the same RPC and a separate owner-only file +secret. Invalid messages are rejected before billing. Agent MQTT acknowledges +QoS 1 delivery only after the local journal has persisted the event. + +Central session authentication mounts before static assets and application +routes. Agent enrollment is the narrowly scoped token-authenticated exception. +Browser WebSockets require both the same origin and an unexpired human session; +active sessions are rechecked periodically. Revocation closes the agent link +immediately. Credential rotation persists the replacement locally before ack +and reconnect, with a two-minute overlap for interrupted handshakes. + +The gateway selector shows cumulative uncertain/reconciled/superseded counts and +current pending count. Switching gateway closes open network application windows +to prevent a window from silently changing its target. Each app title identifies +the selected gateway. Managed logs omit credentials and raw signed envelopes. + +## SSH and ChirpStack tunnels + +Both services use independent multiplexed duplex streams over the outbound link. +Streams have 64 KiB credit windows, 16 KiB frames, an eight-session default cap, +one MiB/s per-stream limit, and a two-minute idle timeout. Closing the link closes +all streams. The SSH purpose resolves only the owner-configured loopback SSH +port; ChirpStack resolves only the gateway's existing configured web endpoint. +Browser-purpose targets cannot access SSH, Docker or fallback/updater ports. + +Central SSH2 uses the stream as its `sock`, so passwords and shell traffic are +inside SSH encryption through the relay. Host keys use trust on first use and +are refused on change; re-enrollment does not silently replace a saved key. +Operators must investigate a change before manually removing the saved key. +Audits record user, gateway and start/end session IDs, including after logout. +The local Terminal keeps its existing direct loopback connection. ChirpStack +uses the existing response rewriting and Bearer-only forwarding over the tunnel, +including streaming gRPC-Web bytes; Console cookies and API_TOKEN are not passed. + +These integrations have only been tested with local fixture servers. The remote +browser engine and signed updater remain separate unfinished work; these tested +transports do not make the entire feature ready for deployment. diff --git a/docs/centralized/test-plan.md b/docs/centralized/test-plan.md index 7e9f5d7..7649e7c 100644 --- a/docs/centralized/test-plan.md +++ b/docs/centralized/test-plan.md @@ -21,12 +21,21 @@ No test contacts real MQTT/ChirpStack, a gateway, meter or blockchain. - Address classification, unusual IPv4 encodings, IPv4-mapped IPv6, metadata refusal, DNS pinning contract, mixed-address refusal and private routing policy. -The completed `npm test -- --runInBand --silent` run passed **193 tests in 24 -suites**, including HTTP-auth injection tests, in approximately 15 seconds. -The desktop suite passed 24 of 25 tests; the remaining new removal assertion -expected the wrong desktop title. After correcting it, the two Browser tests -passed on a targeted rerun. No existing application behavior was changed to -satisfy that assertion. This is not a full post-fix suite rerun. +The latest full `npm test -- --runInBand --silent` run passed **217 tests in +29 suites**. The full `PLAYWRIGHT_BROWSERS_PATH=/tmp/console-ci-browsers npm run +test:ui` run passed **27 tests**, including the new gateway status/selection UI +and existing Paint, Terminal, ChirpStack, themes, touch and responsive behavior. +All three Compose files passed `docker compose config --quiet` using disposable +placeholder configuration. No containers were started by this validation. + +Added safety coverage includes response loss after enqueue, down before offer, +duplicate delivery, overtaken uncertain reports, several newer reports while an +older handler remains active, slow committed decisions, process restart fences, +empty queues after delivery, durable replay and destination publication claims. +Central/local RPC tests verify stored decisions, human versus agent +authentication, heartbeat counters, secret exclusion and immediate revocation. +SSH fixtures exercise authentication, bidirectional data, resize and cleanup. +A 180 kB binary HTTP/gRPC-Web stream exercises tunnel flow control. A first attempt could not locate the Playwright browser; the successful runs used the existing `/tmp/console-ci-browsers` installation. The required @@ -36,12 +45,13 @@ successful reproduction of that CI installation step. ## Coverage still required before publication -The agent/central/local integration, durable ownership, uncertain outcomes, -reconciliation/distribution, lease handoff, bounded spool and crash recovery must -be implemented and tested. The required billing safety decision is recorded in -`design.md`. Browser engine/proxy/PNA tests, SSH tunnel tests, ChirpStack streaming -tunnel tests, updater verification and rollback tests, and central gateway UI -tests remain outstanding. Classifier tests alone do not prove proxy enforcement. +The four explicitly requested uncertain-operation scenarios are covered. More +coverage is still needed for full agent MQTT lifecycle, production-mode TLS +proxies, complete gateway application routing, and real hardware behavior. +Browser engine/proxy/PNA tests, signed updater verification/rollback and full +architecture builds remain outstanding. Classifier tests alone do not prove +proxy enforcement. The agent-failure policy intentionally has no automatic +lease takeover; see the safety rationale in `design.md`. Before any push run the exact dependency, unit, UI and Docker checks requested in the task. Do not publish or report a green workflow before doing so. The local @@ -70,7 +80,7 @@ billing. Record gateway architecture, firmware, image digests and signing identi Explicitly test an enqueue response lost after the queue accepted it. 5. Restart the agent during each ownership/enqueue transition. Check the journal and queue for duplicates; test both Consoles down, ordered drain, spool bounds, - lease handoff and firmware behavior after unanswered reports. + the documented no-takeover policy and firmware behavior after unanswered reports. 6. Open central Terminal for this gateway; authenticate against a test SSH user, resize, disconnect and reconnect. Check host-key change refusal, idle/session limits and purpose allowlists. Verify audit entries contain no credentials or diff --git a/scripts/healthcheck.cjs b/scripts/healthcheck.cjs index 622239d..7c64862 100644 --- a/scripts/healthcheck.cjs +++ b/scripts/healthcheck.cjs @@ -1,8 +1,11 @@ -// The public readiness endpoint requires no password or external services. +// Standalone/gateway readiness remains public. Central probes only its login +// entry point through its explicitly trusted loopback TLS-proxy peer; it does +// not bypass authentication on /healthz or any application endpoint. const http = require('node:http'); const host = process.env.CONSOLE_HOST; const request = http.get({ hostname: !host || host === '0.0.0.0' ? '127.0.0.1' : host === '::' ? '::1' : host, - port: Number(process.env.PORT || 3000), path: '/healthz', timeout: 2500 }, response => { + port: Number(process.env.PORT || 3000), path: process.env.CONSOLE_ROLE === 'central' ? '/login' : '/healthz', + headers: process.env.CONSOLE_ROLE === 'central' ? { 'X-Forwarded-Proto': 'https' } : {}, timeout: 2500 }, response => { response.resume(); process.exitCode = response.statusCode === 200 ? 0 : 1; }); request.on('timeout', () => request.destroy(new Error('timeout'))); diff --git a/src/agent/index.ts b/src/agent/index.ts new file mode 100644 index 0000000..d7e0202 --- /dev/null +++ b/src/agent/index.ts @@ -0,0 +1,121 @@ +import 'dotenv/config'; +import fs from 'fs'; +import path from 'path'; +import { connect, MqttClient } from 'mqtt'; +import WebSocket from 'ws'; +import { requireAgentConfig } from '../central/config'; +import { readOwnerSecret, writeOwnerSecret } from '../central/secrets'; +import { OperationJournal, eventIdentity } from '../central/operations'; +import { UplinkCoordinator } from '../central/coordinator'; +import { LocalDecider } from '../central/local-channel'; +import { SocketDecider, parseOperation } from '../central/rpc'; +import { parseMessage, MAX_MESSAGE_BYTES, Health, UplinkEvent } from '../central/protocol'; +import { Replication } from '../central/replication'; +import { mqttConnection } from '../lib/mqtt-config'; +import { applicationId } from '../lib/chirpstack-config'; +import { managedQueue } from '../services/grpc'; +import { createLogger } from '../utils/logger'; +import { TunnelMux, gatewayTarget } from '../central/tunnels'; + +const logger=createLogger('[agent]'); +export async function runAgent():Promise<()=>Promise> { + const config=requireAgentConfig(); + let identity:string; + if(fs.existsSync(config.credentialPath))identity=readOwnerSecret(config.credentialPath); + else { + const token=process.env.AGENT_ENROLLMENT_TOKEN; + if(!token)throw new Error('Provide a one-time AGENT_ENROLLMENT_TOKEN for initial enrollment.'); + const url=new URL('/api/agent/enroll',config.centralUrl);url.protocol=url.protocol==='wss:'?'https:':'http:'; + const response=await fetch(url,{method:'POST',redirect:'error',signal:AbortSignal.timeout(8000),headers:{'Content-Type':'application/json'},body:JSON.stringify({token})}); + if(!response.ok)throw new Error('Agent enrollment failed; request a fresh token if its response was lost.'); + const result:unknown=await response.json(); + if(typeof result!=='object'||result===null||!('gateway' in result)||!('credential' in result)||typeof result.gateway!=='string'|| + !/^[\w-]{36}$/.test(result.gateway)||typeof result.credential!=='string'||!/^[\w-]{43}$/.test(result.credential))throw new Error('Invalid enrollment response.'); + identity=`${result.gateway}:${result.credential}`;writeOwnerSecret(config.credentialPath,identity); + } + const [gateway,credential]=identity.split(':'); + if(!/^[\w-]{36}$/.test(gateway)||!/^[\w-]{43}$/.test(credential||''))throw new Error('Invalid agent credential file.'); + let currentCredential=credential; + const stateDirectory=path.dirname(config.credentialPath); + const journal=new OperationJournal(path.join(stateDirectory,'operations.db'),config.queueLimit,event=>logger.info('Operation status',event)); + const local=new LocalDecider(Number(process.env.GATEWAY_FALLBACK_PORT||3001),readOwnerSecret(config.fallbackSecretPath),config.decisionTimeoutMs); + let socket:WebSocket|undefined,stopped=false,reconnect:ReturnType|undefined; + let connectedAt=0,attempt=0,mqttState:Health['mqtt']='connecting',lastError:Health['lastError']='none'; + const central=new SocketDecider(()=>socket,config.decisionTimeoutMs); + const replication=new Replication(journal,central,local); + const healthy=()=>socket?.readyState===WebSocket.OPEN&&Date.now()-connectedAt>=config.recoveryHealthyMs; + const coordinator=new UplinkCoordinator(journal,replication.guarded('central'),replication.guarded('local'),managedQueue, + {centralHealthy:healthy,timeoutMs:config.decisionTimeoutMs,reconcileSnapshot:(owner,outcome)=>replication.observe(owner,outcome)}); + const sendHealth=()=>{ + if(socket?.readyState!==WebSocket.OPEN)return; + const counts=journal.counts(gateway); + const health:Health={version:'centralized-v1',uptime:Math.floor(process.uptime()),mqtt:mqttState,fallback:!healthy(),queueDepth:counts.pending, + uncertain:counts.uncertain,reconciled:counts.reconciled,superseded:counts.superseded,updatesEnabled:false,lastError}; + socket.send(JSON.stringify({v:1,type:'health',health})); + }; + const connectCentral=()=>{ + if(stopped)return; + const ws=socket=new WebSocket(new URL('/agent',config.centralUrl),{headers:{Authorization:`Bearer ${currentCredential}`},maxPayload:MAX_MESSAGE_BYTES, + perMessageDeflate:false,handshakeTimeout:8000,followRedirects:false}); + const tunnels=new TunnelMux(ws,request=>gatewayTarget(request)); + ws.on('open',()=>{connectedAt=Date.now();attempt=0;lastError='none';sendHealth();}); + ws.on('message',data=>{ + try { + const value:unknown=JSON.parse(data.toString()); + if(typeof value==='object'&&value!==null&&'type' in value&&value.type==='operation-result'){ + const result=parseOperation(data.toString());if(result.type==='operation-result')central.receive(result);return; + } + const message=parseMessage(data.toString(),'central'); + if(message.type==='tunnel-open'||message.type==='tunnel-data'||message.type==='tunnel-credit'||message.type==='tunnel-ready'||message.type==='tunnel-close'||message.type==='tunnel-end')tunnels.receive(message); + else if(message.type==='ping')ws.send(JSON.stringify({v:1,type:'pong',id:message.id})); + else if(message.type==='rotate'){ + writeOwnerSecret(config.credentialPath,`${gateway}:${message.credential}`);currentCredential=message.credential; + ws.send(JSON.stringify({v:1,type:'rotated'})); + } else if(message.type!=='pong')ws.close(1008,'Unsupported operation for this agent version'); + }catch{lastError='central';ws.close(1008,'Invalid central message');} + }); + ws.on('error',()=>{lastError='central';}); + ws.on('close',()=>{ + central.disconnect();connectedAt=0;lastError='central'; + if(!stopped){const delay=Math.min(60000,1000*2**Math.min(attempt++,6))*(.75+Math.random()*.5);reconnect=setTimeout(connectCentral,delay);} + }); + }; + const broker=mqttConnection(); + const options={clientId:`m3tering-agent-${gateway}`,clean:false,resubscribe:false,reconnectPeriod:2000,connectTimeout:9000}; + const mqtt:MqttClient=typeof broker==='string'?connect(broker,options):connect({...broker,...options}); + const application=applicationId(),topic=`application/${application}/device/+/event/up`; + mqtt.on('connect',()=>{mqtt.subscribe(topic,{qos:1},(error,granted)=>{ + if(error||granted?.some(grant=>grant.qos===128)){mqttState='disconnected';lastError='mqtt';mqtt.stream.destroy();} + else mqttState='connected';sendHealth(); + });}); + mqtt.on('reconnect',()=>{mqttState='connecting';});mqtt.on('close',()=>{mqttState='disconnected';}); + mqtt.on('error',()=>{lastError='mqtt';logger.warn('MQTT connection unavailable; reconnecting.');}); + mqtt.handleMessage=(packet,done)=>{ + try { + const match=packet.topic.match(/^application\/([^/]+)\/device\/([a-f0-9]{16})\/event\/up$/i); + if(!match||match[1].toLowerCase()!==application||Buffer.byteLength(packet.payload)>MAX_MESSAGE_BYTES){done();return;} + const event:UplinkEvent=JSON.parse(packet.payload.toString()); + if(event.fPort!==2||event.deviceInfo?.devEui?.toLowerCase()!==match[2].toLowerCase()||event.deviceInfo.applicationId?.toLowerCase()!==application){done();return;} + try{eventIdentity(event);}catch{logger.warn('Invalid billing event ignored.');done();return;} + // receive persists synchronously before returning its processing promise. + const processing=coordinator.receive(gateway,event); + done();void processing.then(sendHealth).catch(()=>{lastError='storage';logger.error('Managed operation unavailable; inspect gateway status.');}); + }catch(error){ + // Malformed packets are acknowledged; storage/identity failures retain the + // broker delivery and stop the connection, rather than losing signed work. + if(error instanceof SyntaxError){done();return;} + lastError='storage';logger.error('Agent journal refused a report; MQTT delivery retained.');mqtt.stream.destroy();done(new Error('Journal refused report.')); + } + }; + let draining:Promise|undefined; + const timer=setInterval(()=>{ + sendHealth();if(draining)return; + draining=(async()=>{try{await replication.flush('local');}catch{}try{await replication.flush('central');}catch{}await coordinator.drain();})() + .catch(()=>{lastError='storage';}).finally(()=>{draining=undefined;}); + },5000);timer.unref();connectCentral(); + return async()=>{stopped=true;clearTimeout(reconnect);clearInterval(timer);central.disconnect();socket?.terminate();await mqtt.endAsync(false);await coordinator.stop();await draining;journal.close();}; +} +if(require.main===module){ + void runAgent().then(stop=>{for(const signal of ['SIGINT','SIGTERM'] as const)process.once(signal,()=>{void stop().finally(()=>process.exit(0));});}) + .catch(()=>{logger.error('Agent startup failed. Check role, credential files and enrollment configuration.');process.exit(1);}); +} diff --git a/src/central/auth.ts b/src/central/auth.ts index f58d5a0..5397e09 100644 --- a/src/central/auth.ts +++ b/src/central/auth.ts @@ -47,7 +47,7 @@ export class CentralAuth { return `${this.name()}=${token}; Path=/; HttpOnly; SameSite=Strict; Max-Age=${expired ? 0 : 28800}${this.options.development ? '' : '; Secure'}`; } /** Mount before static files, reverse proxies, parsers and application routes. */ - mount(app: Express): void { + mount(app: Express, machineRoutes?: (app:Express)=>void): void { app.use((req, res, next) => { res.setHeader('Cache-Control', 'no-store'); res.setHeader('Referrer-Policy', 'no-referrer'); @@ -63,6 +63,7 @@ export class CentralAuth { if (!this.globalLimiter.allow('login') || !this.limiter.allow(req.socket.remoteAddress || 'unknown')) { res.status(429).send('Too many attempts. Try again later.'); return; } next(); }, express.urlencoded({ extended: false, limit: '3kb', parameterLimit: 2 }), (req, res, next) => { void this.login(req, res).catch(next); }); + machineRoutes?.(app); app.use(this.requireLogin); app.post('/logout', (req, res) => { const session = this.session(req); diff --git a/src/central/hub.ts b/src/central/hub.ts new file mode 100644 index 0000000..533e61d --- /dev/null +++ b/src/central/hub.ts @@ -0,0 +1,99 @@ +import type http from 'http'; +import express, { Express } from 'express'; +import WebSocket from 'ws'; +import { registerSocket } from '../services/socket-router'; +import { CentralAuth, RateLimit } from './auth'; +import type { IdentityStore } from './identity-store'; +import { parseMessage, MAX_MESSAGE_BYTES } from './protocol'; +import { parseOperation, serveOperation } from './rpc'; +import type { Decider } from './processor'; +import { TunnelMux, GatewayStream } from './tunnels'; +import type { Duplex } from 'stream'; +import type { TunnelPurpose } from './protocol'; + +export class GatewayHub { + readonly sockets=new Map(); + private tunnels=new Map(); + private connections=new WeakMap(); + private enrollmentLimit=new RateLimit(5,60000); + private upgradeLimit=new RateLimit(30,60000); + constructor(readonly identities:IdentityStore,readonly auth:CentralAuth,private processor:()=>Decider,private development=false) {} + machineRoutes=(app:Express):void=>{ + app.post('/api/agent/enroll',(req,res,next)=>{ + if(!this.enrollmentLimit.allow(req.socket.remoteAddress||'unknown')){res.status(429).json({error:'Try enrollment later.'});return;}next(); + },express.json({limit:'1kb'}),(req,res)=>{ + if(typeof req.body?.token!=='string'){res.status(400).json({error:'Enrollment token required.'});return;} + const identity=this.identities.exchange(req.body.token); + if(!identity){res.status(401).json({error:'Invalid or expired enrollment token.'});return;} + res.json(identity); + }); + }; + mount(app:Express,server:http.Server):void { + const wss=new WebSocket.Server({noServer:true,maxPayload:MAX_MESSAGE_BYTES,perMessageDeflate:false}); + registerSocket(server,'/agent',wss,req=>{ + if((!this.development&&!this.auth.secure(req))||!this.upgradeLimit.allow(req.socket.remoteAddress||'unknown'))return false; + const token=req.headers.authorization?.match(/^Bearer ([A-Za-z0-9_-]{43})$/)?.[1]; + const gateway=token?this.identities.authenticateAgent(token):null; + if(!gateway)return false;this.connections.set(req,gateway);return true; + },true); + wss.on('connection',(socket,req)=>{ + const gateway=this.connections.get(req)!; + // Replacement of an authenticated session fences the old socket first. + this.sockets.get(gateway)?.close(1008,'Session replaced');this.sockets.set(gateway,socket); + const token=req.headers.authorization!.slice(7);this.identities.acknowledgeRotation(gateway,token); + const tunnels=new TunnelMux(socket);this.tunnels.set(gateway,tunnels); + let alive=true;const rate=new RateLimit(512,1000,1);let inFlight=0; + socket.on('pong',()=>{alive=true;}); + const heartbeat=setInterval(()=>{if(!alive){socket.terminate();return;}alive=false;socket.ping();},30000);heartbeat.unref(); + socket.on('message',data=>{ + if(this.sockets.get(gateway)!==socket)return; + if(!rate.allow('frames')||inFlight>=64){socket.close(1008,'Agent rate limit exceeded');return;} + let value:unknown;try{value=JSON.parse(data.toString());}catch{socket.close(1008,'Invalid frame');return;} + if(typeof value==='object'&&value!==null&&'type' in value&&value.type==='operation'){ + let message;try{message=parseOperation(data.toString());if(message.type!=='operation')throw new Error();}catch{socket.close(1008,'Invalid operation');return;} + inFlight++; + void serveOperation(this.processor(),gateway,message).then(reply=>{if(socket.readyState===WebSocket.OPEN)socket.send(JSON.stringify(reply));}).finally(()=>inFlight--); + return; + } + try { + const message=parseMessage(data.toString(),'agent'); + if(message.type==='tunnel-data'||message.type==='tunnel-credit'||message.type==='tunnel-ready'||message.type==='tunnel-close'||message.type==='tunnel-end')tunnels.receive(message); + else if(message.type==='health')this.identities.heartbeat(gateway,message.health); + else if(message.type==='ping')socket.send(JSON.stringify({v:1,type:'pong',id:message.id})); + else if(message.type==='rotated'){ + // Agent confirms possession by reconnecting with the new credential. + socket.close(1012,'Reconnect with rotated credential'); + } else if(message.type==='result')this.identities.audit('agent','state-downlink',gateway,message.id); + }catch{socket.close(1008,'Invalid agent frame');} + }); + socket.once('close',()=>{clearInterval(heartbeat);tunnels.close();if(this.sockets.get(gateway)===socket){this.sockets.delete(gateway);this.tunnels.delete(gateway);}}); + socket.on('error',()=>socket.terminate()); + }); + server.once('close',()=>{for(const socket of this.sockets.values())socket.terminate();wss.close();}); + app.get('/api/gateways',(req,res)=>res.json({selected:this.selected(req),gateways:this.identities.gateways().map(g=>({...g,online:this.sockets.get(g.id)?.readyState===WebSocket.OPEN,health:this.identities.health(g.id)}))})); + app.post('/api/gateways/select',(req,res)=>{ + if(typeof req.body?.id!=='string'||!this.identities.gateways().some(g=>g.id===req.body.id&&!g.revoked)){res.status(400).json({error:'Choose an available gateway.'});return;} + res.setHeader('Set-Cookie',`console_gateway=${req.body.id}; Path=/; HttpOnly; SameSite=Strict${this.development?'':'; Secure'}`);res.json({selected:req.body.id}); + }); + app.post('/api/gateways',(req,res)=>{ + try{const g=this.identities.createGateway(String(req.body?.name||''),res.locals.centralUser.id);res.status(201).json({...g,token:this.identities.enrollment(g.id,res.locals.centralUser.id)});} + catch{res.status(400).json({error:'Provide a valid gateway name.'});} + }); + app.post('/api/gateways/:id/revoke',(req,res)=>{this.identities.revoke(req.params.id,res.locals.centralUser.id);this.sockets.get(req.params.id)?.terminate();res.json({revoked:true});}); + app.post('/api/gateways/:id/enrollment',(req,res)=>{ + try{res.json({token:this.identities.enrollment(req.params.id,res.locals.centralUser.id)});}catch{res.status(409).json({error:'Revoke the previous identity before enrolling again.'});} + }); + app.post('/api/gateways/:id/rotate',(req,res)=>{ + const socket=this.sockets.get(req.params.id);if(!socket||socket.readyState!==WebSocket.OPEN){res.status(409).json({error:'Gateway must be connected for rotation.'});return;} + try{const credential=this.identities.rotate(req.params.id,res.locals.centralUser.id);socket.send(JSON.stringify({v:1,type:'rotate',credential}));res.json({pending:true});} + catch{res.status(409).json({error:'Credential rotation is already pending or unavailable.'});} + }); + } + selected(req:http.IncomingMessage):string|null { + const id=(req.headers.cookie||'').split(';').map(v=>v.trim()).find(v=>v.startsWith('console_gateway='))?.slice(16); + return id&&this.identities.gateways().some(g=>g.id===id&&!g.revoked)?id:null; + } + open(gateway:string,purpose:TunnelPurpose,host:string,port:number):Promise{ + const tunnels=this.tunnels.get(gateway);if(!tunnels)return Promise.reject(new Error('Gateway is offline.'));return tunnels.open(purpose,host,port); + } +} diff --git a/src/central/identity-store.ts b/src/central/identity-store.ts index 4719252..508c3cd 100644 --- a/src/central/identity-store.ts +++ b/src/central/identity-store.ts @@ -1,6 +1,7 @@ import Database from 'better-sqlite3'; import { randomUUID } from 'crypto'; import { hashSecret, newSecret } from './secrets'; +import type { Health } from './protocol'; export type AuditAction = 'login-success' | 'login-failure' | 'logout' | 'enrolment-created' | 'enrolled' | 'credential-rotated' | 'credential-rotation-acknowledged' | 'credential-revoked' | @@ -23,6 +24,9 @@ export interface IdentityStore { session(token: string): SessionIdentity | null; endSession(token: string): void; audit(actor: string, action: AuditAction, gateway?: string, subject?: string): void; + heartbeat(gateway:string,health:Health):void; + health(gateway:string):Health|null; + verifyHostKey(gateway:string,hash:string):boolean; close(): void; } @@ -53,6 +57,8 @@ export class SqliteIdentityStore implements IdentityStore { CREATE TABLE IF NOT EXISTS central_audit ( id INTEGER PRIMARY KEY, timestamp INTEGER NOT NULL, actor TEXT NOT NULL, action TEXT NOT NULL, gateway TEXT, subject TEXT); + CREATE TABLE IF NOT EXISTS central_health (gateway TEXT PRIMARY KEY REFERENCES central_gateways(id), health TEXT NOT NULL); + CREATE TABLE IF NOT EXISTS central_hostkeys(gateway TEXT PRIMARY KEY REFERENCES central_gateways(id),hash TEXT NOT NULL); INSERT OR IGNORE INTO central_schema VALUES (1); `))(); } @@ -111,7 +117,7 @@ export class SqliteIdentityStore implements IdentityStore { } acknowledgeRotation(gateway: string, credential: string): boolean { return this.db.transaction(() => { - const result = this.db.prepare('UPDATE central_gateways SET previousHash=NULL,previousUntil=NULL WHERE id=? AND credentialHash=? AND revoked=0') + const result = this.db.prepare('UPDATE central_gateways SET previousHash=NULL,previousUntil=NULL WHERE id=? AND credentialHash=? AND revoked=0 AND previousHash IS NOT NULL') .run(gateway, hashSecret(credential)); if (result.changes) this.audit('agent', 'credential-rotation-acknowledged', gateway); return !!result.changes; @@ -151,4 +157,16 @@ export class SqliteIdentityStore implements IdentityStore { this.db.prepare('INSERT INTO central_audit(timestamp,actor,action,gateway,subject) VALUES (?,?,?,?,?)').run(this.now(), actor, action, gateway ?? null, subject ?? null); } close(): void { this.db.close(); } + heartbeat(gateway:string,health:Health):void { + this.db.transaction(()=>{ + this.db.prepare('UPDATE central_gateways SET lastHeartbeat=?,version=? WHERE id=? AND revoked=0').run(this.now(),health.version,gateway); + this.db.prepare('INSERT INTO central_health VALUES (?,?) ON CONFLICT(gateway) DO UPDATE SET health=excluded.health').run(gateway,JSON.stringify(health)); + })(); + } + health(gateway:string):Health|null {const row=this.db.prepare('SELECT health FROM central_health WHERE gateway=?').get(gateway) as {health:string}|undefined;return row?JSON.parse(row.health) as Health:null;} + verifyHostKey(gateway:string,hash:string):boolean { + if(!/^[a-fA-F0-9]{64}$/.test(hash))return false; + this.db.prepare('INSERT OR IGNORE INTO central_hostkeys VALUES (?,?)').run(gateway,hash); + const row=this.db.prepare('SELECT hash FROM central_hostkeys WHERE gateway=?').get(gateway) as {hash:string};return row.hash===hash; + } } diff --git a/src/central/runtime.ts b/src/central/runtime.ts new file mode 100644 index 0000000..3fd9515 --- /dev/null +++ b/src/central/runtime.ts @@ -0,0 +1,60 @@ +import fs from 'fs'; +import path from 'path'; +import type http from 'http'; +import { roleConfig } from './config'; +import { SqliteIdentityStore } from './identity-store'; +import { CentralAuth } from './auth'; +import { GatewayHub } from './hub'; +import { hashPassword, readOwnerSecret } from './secrets'; +import type { DurableProcessor } from './processor'; +import { fallbackServer } from './local-channel'; +import { configurePublications } from './distribution'; +import { distributeManaged } from '../lib/utils'; + + +export const config=roleConfig(); +let processor:DurableProcessor|undefined; +export const central=config.role==='central'?(()=>{ + fs.mkdirSync('.data',{recursive:true,mode:0o700}); + const identities=new SqliteIdentityStore('.data/central.db');fs.chmodSync('.data/central.db',0o600); + const auth=new CentralAuth(identities,{development:config.development,trustedProxies:config.trustedProxies}); + const hub=new GatewayHub(identities,auth,()=>{if(!processor)throw new Error('Billing processor not ready.');return processor;},config.development); + return {identities,auth,hub}; +})():undefined; + +export async function initializeManagedRole():Promise { + if(config.role==='standalone')return; + const {createBillingProcessor}=await import('./billing'); + if(central){ + const username=process.env.CENTRAL_ADMIN_USERNAME||'admin'; + if(!central.identities.user(username)){ + const password=process.env.CENTRAL_ADMIN_PASSWORD; + if(!password)throw new Error('CENTRAL_ADMIN_PASSWORD is required to bootstrap the first central administrator.'); + central.identities.addUser(username,await hashPassword(password)); + } + if(!config.development&&!config.trustedProxies.length)throw new Error('Configure an explicit TLS reverse proxy peer in CENTRAL_TRUSTED_PROXIES.'); + configurePublications('.data/central.db'); + processor=createBillingProcessor('.data/central.db'); + let publishing=false; + const recover=()=>{if(publishing)return;publishing=true; + void import('../lib/sync').then(module=>module.getSyncedPendingTransactions()).then(distributeManaged).catch(()=>{}).finally(()=>{publishing=false;}); + }; + const timer=setInterval(recover,60000);timer.unref();recover(); + return; + } + if(config.role==='gateway'){ + if(!config.fallbackSecretPath||!config.credentialPath)throw new Error('Gateway role requires FALLBACK_SECRET_PATH and AGENT_CREDENTIAL_PATH.'); + const secret=readOwnerSecret(config.fallbackSecretPath); + const directory=path.dirname(config.credentialPath);fs.mkdirSync(directory,{recursive:true,mode:0o700}); + processor=createBillingProcessor(path.join(directory,'local-outcomes.db')); + const getGateway=()=>{ + const identity=readOwnerSecret(config.credentialPath!).split(':')[0]; + if(!/^[\w-]{36}$/.test(identity))throw new Error('Agent enrollment is not ready.');return identity; + }; + const server=fallbackServer(processor,secret,getGateway); + const port=Number(process.env.GATEWAY_FALLBACK_PORT||3001); + if(!Number.isInteger(port)||port<1024||port>65535)throw new Error('GATEWAY_FALLBACK_PORT must be 1024–65535.'); + await new Promise((resolve,reject)=>{server.once('error',reject);server.listen(port,'127.0.0.1',()=>{server.off('error',reject);resolve();});}); + return server; + } +} diff --git a/src/central/tunnels.ts b/src/central/tunnels.ts new file mode 100644 index 0000000..a7efd84 --- /dev/null +++ b/src/central/tunnels.ts @@ -0,0 +1,145 @@ +import { Duplex } from 'stream'; +import net from 'net'; +import tls from 'tls'; +import { randomUUID } from 'crypto'; +import WebSocket from 'ws'; +import { CentralMessage, TunnelMessage, TunnelPurpose, MAX_TUNNEL_CHUNK } from './protocol'; +import { normalizeHost, resolveTarget } from './destinations'; +import { chirpstackTarget } from '../services/chirpstack'; + +type Open = Extract; +export interface TunnelLimits { sessions:number; idleMs:number; bytesPerSecond:number } +const defaults:TunnelLimits={sessions:8,idleMs:120000,bytesPerSecond:1024*1024}; +type ConnectTarget={host:string;port:number;secure?:boolean;servername?:string;origin?:string}; +export type GatewayStream=Duplex&{upstreamOrigin?:string}; +export async function gatewayTarget(request:Open,env:NodeJS.ProcessEnv=process.env):Promise { + if(request.purpose==='ssh'){ + if(request.host!=='ssh'||request.port!==22)throw new Error('SSH purpose requires the fixed SSH service.'); + const port=Number(env.AGENT_SSH_PORT||22);if(!Number.isInteger(port)||port<1||port>65535)throw new Error('Invalid gateway SSH port.'); + return {host:'127.0.0.1',port}; + } + if(request.purpose==='chirpstack'){ + if(request.host!=='chirpstack'||request.port!==8080)throw new Error('ChirpStack purpose requires the fixed service.'); + const target=chirpstackTarget();const resolved=await resolveTarget(target.hostname); + return {host:resolved.address,port:Number(target.port||(target.protocol==='https:'?443:80)),secure:target.protocol==='https:',servername:normalizeHost(target.hostname),origin:target.origin}; + } + const target=await resolveTarget(request.host); + if(target.classification!=='local')throw new Error('Browser tunnels are restricted to local destinations.'); + const loopback=target.address==='::1'||target.address.startsWith('127.')||/^::ffff:7f[\da-f]{2}:/.test(target.address); + if(!loopback&&env.AGENT_BROWSER_ALLOW_LAN!=='true')throw new Error('Gateway owner has not enabled browser access to the LAN.'); + const denied=new Set([22,2375,2376,Number(env.GATEWAY_FALLBACK_PORT||3001),Number(env.GATEWAY_UPDATER_PORT||3002)]); + if(denied.has(request.port))throw new Error('This infrastructure port is not a browser target.'); + const allowed=(env.AGENT_BROWSER_PORTS||'80,443,3000,8080,8090').split(',').map(Number); + if(!allowed.includes(request.port))throw new Error('Gateway owner has not allowed this browser port.'); + return {host:target.address,port:request.port}; +} + +class TunnelStream extends Duplex { + upstreamOrigin?:string; + private httpTimeout=0; + private txCredit=0;private rxCredit=0;private pending?:{bytes:Buffer;offset:number;done:(error?:Error|null)=>void}; + private sending=false;private peerClosed=false;private rateStart=Date.now();private received=0;private sent=0; + private retry?:ReturnType;private activity=Date.now();private idle:ReturnType; + constructor(readonly id:string,private send:(message:TunnelMessage,done?:(error?:Error)=>void)=>void,private release:()=>void,private limits:TunnelLimits){ + super({readableHighWaterMark:65536,writableHighWaterMark:65536,allowHalfOpen:true}); + this.on('error',()=>{}); + this.idle=setInterval(()=>{if(this.httpTimeout&&Date.now()-this.activity>this.httpTimeout)this.emit('timeout');if(Date.now()-this.activity>limits.idleMs)this.destroy(new Error('Tunnel idle timeout.'));},Math.min(1000,limits.idleMs));this.idle.unref(); + this.on('end',()=>{if(this.writableFinished)this.destroy();});this.on('finish',()=>{if(this.readableEnded)this.destroy();}); + } + start():void{this._read();} + setTimeout(ms:number,callback?:()=>void):this{this.httpTimeout=ms;if(callback)this.once('timeout',callback);return this;} + setNoDelay():this{return this;} + setKeepAlive():this{return this;} + _read():void { + const grant=65536-this.readableLength-this.rxCredit; + if(grant>0&&!this.destroyed){this.rxCredit+=grant;this.send({v:1,type:'tunnel-credit',id:this.id,bytes:grant});} + } + _write(bytes:Buffer,_encoding:BufferEncoding,done:(error?:Error|null)=>void):void {this.pending={bytes:Buffer.from(bytes),offset:0,done};this.flush();} + _final(done:(error?:Error|null)=>void):void {this.send({v:1,type:'tunnel-end',id:this.id},done);} + _destroy(error:Error|null,done:(error?:Error|null)=>void):void { + clearInterval(this.idle);clearTimeout(this.retry); + if(!this.peerClosed)this.send({v:1,type:'tunnel-close',id:this.id,reason:error?'error':'closed'}); + const pending=this.pending;this.pending=undefined;pending?.done(error||new Error('Tunnel closed.'));this.release();done(error); + } + receive(message:TunnelMessage):void { + this.activity=Date.now();this.resetRate(); + if(message.type==='tunnel-credit'){ + if(this.txCredit+message.bytes>65536){this.destroy(new Error('Invalid tunnel credit.'));return;} + this.txCredit+=message.bytes;this.flush(); + }else if(message.type==='tunnel-data'){ + const bytes=Buffer.from(message.data,'base64');this.received+=bytes.length; + if(bytes.length>this.rxCredit||this.received>this.limits.bytesPerSecond){this.destroy(new Error('Tunnel receive limit exceeded.'));return;} + this.rxCredit-=bytes.length;if(this.push(bytes))this._read(); + }else if(message.type==='tunnel-end')this.push(null); + else if(message.type==='tunnel-close'){this.peerClosed=true;this.destroy(message.reason==='closed'?undefined:new Error('Remote tunnel closed.'));} + } + private resetRate():void{if(Date.now()-this.rateStart>=1000){this.rateStart=Date.now();this.received=0;this.sent=0;}} + private flush():void { + if(this.sending||!this.pending||!this.txCredit||this.destroyed)return; + this.resetRate();const available=this.limits.bytesPerSecond-this.sent; + if(available<=0){if(!this.retry)this.retry=setTimeout(()=>{this.retry=undefined;this.flush();},Math.max(1,1000-(Date.now()-this.rateStart)));return;} + const pending=this.pending,len=Math.min(MAX_TUNNEL_CHUNK,this.txCredit,available,pending.bytes.length-pending.offset); + if(!len){this.pending=undefined;pending.done();return;} + const bytes=pending.bytes.subarray(pending.offset,pending.offset+len);pending.offset+=len;this.txCredit-=len;this.sent+=len;this.activity=Date.now();this.sending=true; + this.send({v:1,type:'tunnel-data',id:this.id,data:bytes.toString('base64')},error=>{ + this.sending=false;if(error){this.destroy(error);return;} + if(pending.offset===pending.bytes.length&&this.pending===pending){this.pending=undefined;pending.done();}this.flush(); + }); + } +} + +export class TunnelMux { + private streams=new Map(); + private closed=false; + private openings=new Mapvoid;reject:(error:Error)=>void;timer:ReturnType}>(); + private sockets=new Set();private accepting=new Set(); + private pendingSockets=new Map(); + constructor(private link:WebSocket,private resolveTarget?: (request:Open)=>Promise,private limits:TunnelLimits=defaults){link.once('close',()=>this.close());} + open(purpose:TunnelPurpose,host:string,port:number):Promise { + if(this.closed||this.streams.size+this.accepting.size>=this.limits.sessions||this.link.readyState!==WebSocket.OPEN)return Promise.reject(new Error('Gateway tunnel unavailable or at capacity.')); + const id=randomUUID(),stream=this.create(id); + return new Promise((resolve,reject)=>{ + const timer=setTimeout(()=>{this.openings.delete(id);stream.destroy();reject(new Error('Gateway tunnel timed out.'));},15000); + this.openings.set(id,{resolve,reject,timer});this.send({v:1,type:'tunnel-open',id,purpose,host,port}); + }); + } + receive(message:Open|TunnelMessage):void { + if(message.type==='tunnel-open'){ + if(!this.resolveTarget||this.streams.has(message.id)||this.accepting.has(message.id)||this.streams.size+this.accepting.size>=this.limits.sessions){this.send({v:1,type:'tunnel-close',id:message.id,reason:'refused'});return;} + this.accepting.add(message.id);void this.accept(message);return; + } + if(message.type==='tunnel-close'&&this.accepting.has(message.id)){this.accepting.delete(message.id);this.pendingSockets.get(message.id)?.destroy();return;} + const stream=this.streams.get(message.id);if(!stream)return; + if(message.type==='tunnel-ready'){ + const pending=this.openings.get(message.id);if(!pending)return; + clearTimeout(pending.timer);this.openings.delete(message.id);stream.upstreamOrigin=message.origin;stream.start();pending.resolve(stream); + }else stream.receive(message); + } + private async accept(message:Open):Promise{ + try { + const target=await this.resolveTarget!(message); + if(this.link.readyState!==WebSocket.OPEN||!this.accepting.has(message.id)){this.accepting.delete(message.id);return;} + const socket=target.secure?tls.connect({host:target.host,port:target.port,servername:target.servername,rejectUnauthorized:true}):net.connect({host:target.host,port:target.port,allowHalfOpen:true}); + this.sockets.add(socket);this.pendingSockets.set(message.id,socket);socket.setTimeout(15000,()=>socket.destroy(new Error('Tunnel connect timeout.'))); + socket.on('error',()=>{this.streams.get(message.id)?.destroy(new Error('Gateway service unavailable.'));this.send({v:1,type:'tunnel-close',id:message.id,reason:'error'});}); + socket.once(target.secure?'secureConnect':'connect',()=>{ + this.accepting.delete(message.id);this.pendingSockets.delete(message.id);socket.setTimeout(0);const stream=this.create(message.id); + this.send({v:1,type:'tunnel-ready',id:message.id,...(target.origin?{origin:target.origin}:{})});stream.start(); + socket.pipe(stream).pipe(socket);stream.once('close',()=>socket.destroy()); + }); + socket.once('close',()=>{this.sockets.delete(socket);this.pendingSockets.delete(message.id);this.streams.get(message.id)?.destroy();this.accepting.delete(message.id);}); + }catch{this.accepting.delete(message.id);this.send({v:1,type:'tunnel-close',id:message.id,reason:'refused'});} + } + private create(id:string):TunnelStream { + const stream=new TunnelStream(id,(message,done)=>this.send(message,done),()=>{ + this.streams.delete(id);const pending=this.openings.get(id);if(pending){clearTimeout(pending.timer);this.openings.delete(id);pending.reject(new Error('Gateway tunnel closed.'));} + },this.limits);this.streams.set(id,stream);return stream; + } + private send(message:CentralMessage|TunnelMessage,done?:(error?:Error)=>void):void { + if(this.closed||this.link.readyState!==WebSocket.OPEN||this.link.bufferedAmount>512*1024){ + done?.(new Error('Tunnel link unavailable or congested.'));this.close();return; + } + this.link.send(JSON.stringify(message),error=>{if(error)this.close();done?.(error||undefined);}); + } + close():void {if(this.closed)return;this.closed=true;this.accepting.clear();for(const socket of this.sockets)socket.destroy();for(const stream of this.streams.values())stream.destroy();this.streams.clear();} +} diff --git a/src/index.ts b/src/index.ts index 0ea51ad..f5a60ca 100644 --- a/src/index.ts +++ b/src/index.ts @@ -2,7 +2,28 @@ import 'dotenv/config'; import { handleUplinks } from './services/mqtt'; import { server, startServer } from './services/server'; import { attachTerminal } from './services/ssh'; -attachTerminal(server); +import { central, config, initializeManagedRole } from './central/runtime'; +if(!central)attachTerminal(server); +else { + const runtime=central; + const sessions=new Map(); + attachTerminal(server,undefined,{ + connection:async request=>{ + const gateway=runtime.hub.selected(request);if(!gateway)throw new Error('Select a gateway.'); + const sock=await runtime.hub.open(gateway,'ssh','ssh',22); + return {sock,hostHash:'sha256',hostVerifier:(hash:string)=>runtime.identities.verifyHostKey(gateway,hash)}; + }, + audit:(request,event,session)=>{ + if(event==='start'){ + const user=runtime.auth.session(request),gateway=runtime.hub.selected(request); + if(user&&gateway)sessions.set(session,{user:user.id,gateway}); + } + const actor=sessions.get(session); + if(actor)runtime.identities.audit(actor.user,event==='start'?'terminal-start':'terminal-end',actor.gateway,session); + if(event==='end')sessions.delete(session); + }, +}); +} import { loadExtensionsFromConfig, loadUIExtensionsFromConfig, runHook, notifyHook } from './lib/utils'; import setupDatabase from './store/sqlite'; import { createLogger } from './utils/logger'; @@ -34,11 +55,13 @@ warnRemovedManagerSettings(process.env, message => logger.warn(message)); await runHook('onDatabaseSetup'); + await initializeManagedRole(); + try { logger.info('Initializing MQTT handling...'); // Start MQTT handling - await handleUplinks(); + if(config.role==='standalone')await handleUplinks(); logger.info('MQTT handling initialized successfully'); } catch (mqttError) { diff --git a/src/public/css/gateways.css b/src/public/css/gateways.css new file mode 100644 index 0000000..a0ff3b5 --- /dev/null +++ b/src/public/css/gateways.css @@ -0,0 +1 @@ +.gateway-control{display:flex;align-items:center;gap:.5rem;min-width:0}.gateway-control form{margin:0}.gateway-control select{max-width:13rem;min-width:0;background:var(--surface);color:var(--text);border:1px solid var(--border);border-radius:8px;padding:.4rem}#gateway-status{position:absolute;bottom:78px;left:1rem;right:1rem;z-index:5;pointer-events:none;font:12px system-ui;color:var(--text);background:var(--surface);padding:.5rem;border-radius:8px;width:fit-content;max-width:calc(100% - 2rem)}#gateway-dialog{background:var(--surface);color:var(--text);border:1px solid var(--border);border-radius:14px;max-width:760px;width:calc(100% - 2rem);max-height:85dvh;overflow:auto;padding:1.5rem}#gateway-dialog::backdrop{background:#0008}#gateway-dialog header{display:flex;justify-content:space-between;align-items:center}#gateway-dialog h2{font-size:1.3rem}#gateway-list article{padding:1rem 0;border-bottom:1px solid var(--border)}#gateway-list article>div{display:flex;gap:.5rem;flex-wrap:wrap}#gateway-list p{font:14px system-ui}#gateway-create{display:flex;gap:1rem;align-items:end;flex-wrap:wrap;margin-top:1rem}#gateway-create label{display:grid;gap:.4rem}#gateway-enrollment code{display:block;overflow-wrap:anywhere;white-space:normal;margin-bottom:1rem}#gateway-error{color:var(--danger,#c44)}@media(max-width:600px){.gateway-control{gap:.15rem}.gateway-control select{max-width:9rem}.gateway-control button{font-size:11px}.topbar-location{display:none}#gateway-status{font-size:10px;bottom:70px}#gateway-dialog{padding:1rem}} diff --git a/src/public/js/gateways.js b/src/public/js/gateways.js new file mode 100644 index 0000000..4a50643 --- /dev/null +++ b/src/public/js/gateways.js @@ -0,0 +1,52 @@ +(() => { + const select=document.getElementById('gateway-select'),dialog=document.getElementById('gateway-dialog'),list=document.getElementById('gateway-list'); + let gateways=[],selected=null,busy=false; + const error=message=>{document.getElementById('gateway-error').textContent=message;}; + async function api(path,body){ + const response=await fetch(path,{method:body?'POST':'GET',headers:body?{'Content-Type':'application/json'}:{},body:body?JSON.stringify(body):undefined}); + if(response.status===401){location.assign('/login');throw new Error('Session expired.');} + const result=await response.json();if(!response.ok)throw new Error(result.error||'Gateway request failed.');return result; + } + function title(id){ + const win=document.getElementById(id),gateway=gateways.find(g=>g.id===selected);if(!win||!gateway)return; + win.dataset.gatewayBaseTitle ||= win.dataset.windowTitle; + win.dataset.windowTitle=`${win.dataset.gatewayBaseTitle} · ${gateway.name}`; + const label=win.querySelector('.window-title');if(label)label.textContent=win.dataset.windowTitle; + document.title=`${win.dataset.windowTitle} · M3tering Console`; + document.getElementById('active-app-name').textContent=win.dataset.windowTitle; + } + function render(){ + select.replaceChildren(new Option('Select a gateway','')); + for(const gateway of gateways)if(!gateway.revoked)select.add(new Option(`${gateway.name}${gateway.online?'':' · offline'}`,gateway.id)); + select.value=selected||''; + const current=gateways.find(g=>g.id===selected),h=current?.health; + document.getElementById('gateway-status').textContent=current?`${current.name} · ${current.online?'Agent connected':'Agent offline'} · ${h?.uncertain||0} uncertain seen · ${h?.reconciled||0} reconciled · ${h?.superseded||0} superseded · ${h?.queueDepth||0} pending`:'Choose a gateway to access its applications.'; + list.replaceChildren(); + for(const g of gateways){ + const item=document.createElement('article'),name=document.createElement('strong'),status=document.createElement('p'),actions=document.createElement('div'); + name.textContent=g.name;const s=g.health; + status.textContent=`${g.revoked?'Revoked':g.online?'Connected':'Offline'} · MQTT ${s?.mqtt||'unknown'} · ${s?.queueDepth||0} pending · ${s?.uncertain||0} uncertain seen · ${s?.reconciled||0} reconciled · ${s?.superseded||0} superseded`; + for(const [action,label] of [['rotate','Rotate credential'],['revoke','Revoke access'],['enrollment','New enrollment']]){ + const button=document.createElement('button');button.className='nes-btn';button.textContent=label; + button.disabled=action==='rotate'&&(!g.online||g.revoked); + button.onclick=async()=>{try{const result=await api(`/api/gateways/${encodeURIComponent(g.id)}/${action}`,{});if(result.token)showToken(result.token);await refresh();}catch(e){error(e.message);}}; + actions.append(button); + } + item.append(name,status,actions);list.append(item); + } + } + async function refresh(){if(busy)return;busy=true;try{const result=await api('/api/gateways');gateways=result.gateways;selected=result.selected;render();}catch(e){error(e.message);}finally{busy=false;}} + function showToken(token){document.getElementById('gateway-enrollment').hidden=false;document.getElementById('gateway-enrollment-token').textContent=token;} + select.onchange=async()=>{ + const id=select.value;if(!id)return; + for(const app of ['terminal','chirpstack','browser'])Desktop.close(app); + try{await api('/api/gateways/select',{id});await refresh();}catch(e){error(e.message);select.value=selected||'';} + }; + document.getElementById('manage-gateways').onclick=()=>{dialog.showModal();refresh();}; + document.getElementById('gateway-dialog-close').onclick=()=>dialog.close(); + dialog.addEventListener('close',()=>{document.getElementById('gateway-enrollment-token').textContent='';document.getElementById('gateway-enrollment').hidden=true;}); + document.getElementById('gateway-copy-token').onclick=()=>navigator.clipboard.writeText(document.getElementById('gateway-enrollment-token').textContent).catch(()=>error('Select and copy the token manually.')); + document.getElementById('gateway-create').onsubmit=async event=>{event.preventDefault();try{const result=await api('/api/gateways',{name:new FormData(event.target).get('name')});showToken(result.token);event.target.reset();await refresh();}catch(e){error(e.message);}}; + window.addEventListener('desktop:open',event=>{if(['terminal','chirpstack','browser'].includes(event.detail.id))title(event.detail.id);}); + const timer=setInterval(refresh,5000);window.addEventListener('pagehide',()=>clearInterval(timer));refresh(); +})(); diff --git a/src/services/chirpstack.ts b/src/services/chirpstack.ts index 01eb894..ea925f5 100644 --- a/src/services/chirpstack.ts +++ b/src/services/chirpstack.ts @@ -42,6 +42,12 @@ function unavailable(res: Response, configuration = false): void { /** Mount before JSON/body middleware: gRPC-Web bodies and event streams stay intact. */ export function proxyChirpstack(req: Request, res: Response): void { + proxy(req,res); +} +export function proxyChirpstackThrough(req:Request,res:Response,target:URL,agent:http.Agent):void { + proxy(req,res,{target,agent}); +} +function proxy(req:Request,res:Response,transport?:{target:URL;agent:http.Agent}):void { res.setHeader('Cache-Control', 'no-store'); res.setHeader('Referrer-Policy', 'no-referrer'); res.setHeader('X-Frame-Options', 'SAMEORIGIN'); @@ -52,7 +58,7 @@ export function proxyChirpstack(req: Request, res: Response): void { return; } let target: URL; - try { target = chirpstackTarget(); } catch { unavailable(res, true); return; } + try { target = transport?.target || chirpstackTarget(); } catch { unavailable(res, true); return; } const headers = cleanHeaders(req.headers); headers.host = target.host; headers['accept-encoding'] = 'identity'; @@ -62,8 +68,9 @@ export function proxyChirpstack(req: Request, res: Response): void { delete headers.referer; for (const name of Object.keys(headers)) if (name.startsWith('x-forwarded-') || name === 'forwarded') delete headers[name]; if (!/^Bearer /i.test(headers.authorization || '')) delete headers.authorization; - const upstream = (target.protocol === 'https:' ? https : http).request(target, { - method: req.method, path: req.url, headers, + const wireTarget=new URL(target.href);if(transport)wireTarget.protocol='http:'; + const upstream = (wireTarget.protocol === 'https:' ? https : http).request(wireTarget, { + method: req.method, path: req.url, headers, ...(transport?{agent:transport.agent}:{}), }, response => { const responseHeaders = cleanHeaders(response.headers); for (const name of ['set-cookie', 'www-authenticate', 'content-security-policy', 'content-security-policy-report-only', 'x-frame-options', 'cache-control', 'etag', 'last-modified']) delete responseHeaders[name]; diff --git a/src/services/server.ts b/src/services/server.ts index 99abae4..898edd8 100644 --- a/src/services/server.ts +++ b/src/services/server.ts @@ -2,9 +2,11 @@ import http from 'http'; import { create } from 'express-handlebars'; import express, { Express, Request, Response } from 'express'; import { requireSameOrigin } from './auth'; -import { proxyChirpstack } from './chirpstack'; +import { proxyChirpstack, proxyChirpstackThrough } from './chirpstack'; import { createLogger } from '../utils/logger'; import { getUIComponents, invokeUIAction } from '../lib/utils'; +import { central, config } from '../central/runtime'; +import { protectBrowserSockets } from './socket-router'; const logger = createLogger('[server]'); export const app: Express = express(); @@ -24,7 +26,17 @@ const hbs = create({ app.engine('hbs', hbs.engine); app.set('view engine', 'hbs'); app.set('views', './src/views'); -app.use('/chirpstack', proxyChirpstack); +central?.auth.mount(app,central.hub.machineRoutes); +const gatewayHub=central?.hub; +app.use('/chirpstack', gatewayHub ? (req,res) => { + const gateway=gatewayHub.selected(req);if(!gateway){res.status(409).send('Select a gateway first.');return;} + void gatewayHub.open(gateway,'chirpstack','chirpstack',8080).then(stream=>{ + if(req.destroyed||res.destroyed){stream.destroy();return;} + const agent=new http.Agent({keepAlive:false});agent.createConnection=()=>stream; + res.once('close',()=>{agent.destroy();stream.destroy();}); + proxyChirpstackThrough(req,res,new URL(stream.upstreamOrigin||'http://chirpstack:8080'),agent); + }).catch(()=>{if(!res.headersSent)res.status(502).send('Gateway ChirpStack is unavailable.');else res.destroy();}); +} : proxyChirpstack); app.use(requireSameOrigin); app.use((_req, res, next) => { res.setHeader('Cache-Control', 'no-store'); res.setHeader('Referrer-Policy', 'no-referrer'); next(); }); app.get('/healthz', (_req, res) => res.json({ status: 'ok' })); @@ -39,7 +51,7 @@ app.get('/', async (req: Request, res: Response, next) => { logger.info('Rendering index page with icons and windows'); - res.render('index', { icons, windows }); + res.render('index', { icons, windows, central:config.role==='central' }); logger.info('Server handled GET request at `/`'); } catch (error) { next(error); } }); @@ -61,6 +73,7 @@ app.post('/api/actions/:moduleId/:actionId', async (req: Request, res: Response, }); export const server = http.createServer(app); +if(central){protectBrowserSockets(server,central.auth.authorize);central.hub.mount(app,server);} export function startServer() { server.once('error', (error: NodeJS.ErrnoException) => { diff --git a/src/services/socket-router.ts b/src/services/socket-router.ts index 4d2ac13..73e3f26 100644 --- a/src/services/socket-router.ts +++ b/src/services/socket-router.ts @@ -2,21 +2,31 @@ import type http from 'http'; import { Socket } from 'net'; import WebSocket from 'ws'; import { isSameOrigin } from './auth'; -const servers = new WeakMap boolean }>>(); +const servers = new WeakMap boolean; machine: boolean }>>(); +const browserGuards = new WeakMap boolean>(); +export function protectBrowserSockets(server:http.Server,authorize:(req:http.IncomingMessage)=>boolean):void {browserGuards.set(server,authorize);} /** Shared origin-checked upgrade boundary for terminal and application streams. */ -export function registerSocket(server: http.Server, path: string, wss: WebSocket.Server, authorize?: (req: http.IncomingMessage) => boolean): void { +export function registerSocket(server: http.Server, path: string, wss: WebSocket.Server, authorize?: (req: http.IncomingMessage) => boolean, machine = false): void { + if(machine && !authorize)throw new Error('Machine sockets require explicit credential authorization.'); let routes = servers.get(server); if (!routes) { routes = new Map(); servers.set(server, routes); server.on('upgrade', (request, socket, head) => { const target = routes!.get(request.url || ''); - if (!target || !isSameOrigin(request, true) || (target.authorize && !target.authorize(request))) { + const guard=browserGuards.get(server); + if (!target || (!target.machine && (!isSameOrigin(request, true) || (guard && !guard(request)))) || (target.authorize && !target.authorize(request))) { socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n'); return; } if (!(socket instanceof Socket)) { socket.destroy(); return; } - target.wss.handleUpgrade(request, socket, head, ws => target.wss.emit('connection', ws, request)); + target.wss.handleUpgrade(request, socket, head, ws => { + if(guard&&!target.machine){ + const expiry=setInterval(()=>{if(!guard(request))ws.close(1008,'Session expired');},30000); + expiry.unref();ws.once('close',()=>clearInterval(expiry)); + } + target.wss.emit('connection', ws, request); + }); }); } - routes.set(path, { wss, authorize }); + routes.set(path, { wss, authorize, machine }); } diff --git a/src/services/ssh.ts b/src/services/ssh.ts index afd06fc..a7609c1 100644 --- a/src/services/ssh.ts +++ b/src/services/ssh.ts @@ -1,27 +1,34 @@ import http from 'http'; import WebSocket from 'ws'; -import { Client as SSHClient, ClientChannel } from 'ssh2'; +import { Client as SSHClient, ClientChannel, ConnectConfig } from 'ssh2'; +import { randomUUID } from 'crypto'; import { registerSocket } from './socket-router'; import { createLogger } from '../utils/logger'; const logger = createLogger('[ssh]'); -export function attachTerminal(httpServer: http.Server, target = { host: '127.0.0.1', port: 22 }): WebSocket.Server { +export interface TerminalOptions { + connection?:(request:http.IncomingMessage)=>Promise; + audit?:(request:http.IncomingMessage,event:'start'|'end',session:string)=>void; +} +export function attachTerminal(httpServer: http.Server, target = { host: '127.0.0.1', port: 22 }, options:TerminalOptions={}): WebSocket.Server { const wss = new WebSocket.Server({ noServer: true, maxPayload: 64 * 1024 }); registerSocket(httpServer, '/terminal', wss); - wss.on('connection', (ws: WebSocket) => { + wss.on('connection', (ws: WebSocket, request:http.IncomingMessage) => { logger.info('Terminal transport connected; waiting for SSH login'); let ssh: SSHClient | undefined; let stream: ClientChannel | undefined; let started = false; let shellTimer: ReturnType | undefined; let alive = true; + const session=randomUUID();let audited=false; ws.on('pong', () => { alive = true; }); const heartbeat = setInterval(() => { if (!alive) { ws.terminate(); return; } alive = false; if (ws.readyState === WebSocket.OPEN) ws.ping(); }, 30000); heartbeat.unref(); const send = (message: string | Buffer) => { if (ws.readyState === WebSocket.OPEN) ws.send(message); }; const timer = setTimeout(() => ws.close(1008, 'SSH credentials required'), 15000); - const cleanup = () => { clearInterval(heartbeat); clearTimeout(shellTimer); clearTimeout(timer); stream?.end(); ssh?.end(); }; + const cleanup = () => { clearInterval(heartbeat); clearTimeout(shellTimer); clearTimeout(timer); stream?.end(); ssh?.end(); + if(audited){audited=false;options.audit?.(request,'end',session);} }; ws.on('close', cleanup); ws.on('error', cleanup); const dimension = (value: unknown, fallback: number) => @@ -58,9 +65,15 @@ export function attachTerminal(httpServer: http.Server, target = { host: '127.0. }); ssh.on('error', () => { send('SSH connection failed. Check your credentials and host availability.'); ws.close(); ssh?.end(); }); ssh.on('close', () => ws.close()); - try { - ssh.connect({ ...target, keepaliveInterval: 10000, keepaliveCountMax: 3, username: auth.username, password: auth.password, readyTimeout: 15000 }); - } catch { send('Unable to connect to SSH.'); ws.close(); cleanup(); } + const connect=async()=>{ + try { + const connection:ConnectConfig=options.connection?await options.connection(request):target; + if(ws.readyState!==WebSocket.OPEN){connection.sock?.destroy();return;} + if(options.audit){options.audit(request,'start',session);audited=true;} + ssh!.connect({ ...connection, keepaliveInterval: 10000, keepaliveCountMax: 3, username: auth.username, password: auth.password, readyTimeout: 15000 }); + } catch { send(options.connection?'Gateway SSH is unavailable. Select a connected gateway and verify its SSH host key.':'Unable to connect to SSH.');ws.close();cleanup(); } + }; + void connect(); return; } if (!stream) return; diff --git a/src/views/index.hbs b/src/views/index.hbs index 19defc5..af46a5b 100644 --- a/src/views/index.hbs +++ b/src/views/index.hbs @@ -3,8 +3,13 @@
Desktop
+ {{#if central}}
{{/if}}
+ {{#if central}} +

Choose a gateway to access its applications.

+

Gateways

Uncertain replies are held for reconciliation. A newer report supersedes an older unresolved reply; uncertainty never sends a relay command.

+ {{/if}}
diff --git a/src/views/layouts/main.hbs b/src/views/layouts/main.hbs index a615212..ded59a7 100644 --- a/src/views/layouts/main.hbs +++ b/src/views/layouts/main.hbs @@ -12,6 +12,7 @@ + {{#if central}}{{/if}} {{{body}}} @@ -25,5 +26,6 @@ + {{#if central}}{{/if}} diff --git a/tests/services/central-link.test.ts b/tests/services/central-link.test.ts new file mode 100644 index 0000000..75b2245 --- /dev/null +++ b/tests/services/central-link.test.ts @@ -0,0 +1,88 @@ +import express from 'express'; +import http from 'http'; +import { once } from 'events'; +import WebSocket from 'ws'; +import { SqliteIdentityStore } from '../../src/central/identity-store'; +import { CentralAuth } from '../../src/central/auth'; +import { GatewayHub } from '../../src/central/hub'; +import { SocketDecider, parseOperation } from '../../src/central/rpc'; +import { DurableProcessor } from '../../src/central/processor'; +import { LocalDecider, fallbackServer } from '../../src/central/local-channel'; +import { protectBrowserSockets, registerSocket } from '../../src/services/socket-router'; +import { hashPassword } from '../../src/central/secrets'; +import type { UplinkEvent } from '../../src/central/protocol'; + +const report:UplinkEvent={deduplicationId:'wire-report',fPort:2,deviceInfo:{applicationId:'11111111-1111-4111-8111-111111111111',devEui:'0102030405060708'},data:Buffer.alloc(74).toString('base64')}; +const start=async(server:http.Server)=>{await new Promise(resolve=>server.listen(0,'127.0.0.1',resolve));return `http://127.0.0.1:${(server.address() as import('net').AddressInfo).port}`;}; +const close=async(server:http.Server)=>{server.closeAllConnections();await new Promise(resolve=>server.close(()=>resolve()));}; + +async function fixture(){ + const store=new SqliteIdentityStore(':memory:');store.addUser('test',await hashPassword('test-only-password-long')); + const cookie=`console_dev_session=${store.createSession(store.user('test')!.id)}`; + const auth=new CentralAuth(store,{development:true,trustedProxies:[]}); + const compute=jest.fn(async(event,sink)=>sink({devEui:event.deviceInfo.devEui,fPort:2,confirmed:false,bytes:[1,0,0,0,0,0,0,0,0]})); + const processor=new DurableProcessor(':memory:',compute); + const hub=new GatewayHub(store,auth,()=>processor,true),app=express(),server=http.createServer(app); + auth.mount(app,hub.machineRoutes);app.use(express.json());protectBrowserSockets(server,auth.authorize);hub.mount(app,server); + const terminal=new WebSocket.Server({noServer:true});registerSocket(server,'/terminal',terminal); + const base=await start(server); + const g=store.createGateway('Fixture gateway','test'),token=store.enrollment(g.id,'test'); + const response=await fetch(base+'/api/agent/enroll',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({token})}); + const enrolled=await response.json() as {gateway:string;credential:string}; + const sockets:WebSocket[]=[]; + const connect=async()=>{const ws=new WebSocket(base.replace('http:','ws:')+'/agent',{headers:{authorization:`Bearer ${enrolled.credential}`}});sockets.push(ws);await once(ws,'open');return ws;}; + return {store,cookie,processor,hub,compute,base,enrolled,token,connect,close:async()=>{ + for(const ws of sockets)ws.terminate();for(const ws of hub.sockets.values())ws.terminate(); + terminal.close();await close(server);processor.close();store.close(); + }}; +} + +test('authenticated outbound link returns the same stored decision by ChirpStack ID; health and revocation work',async()=>{ + const f=await fixture();let client:SocketDecider|undefined; + try{ + const ws=await f.connect();client=new SocketDecider(()=>ws,500); + ws.on('message',bytes=>{const frame=parseOperation(bytes.toString());if(frame.type==='operation-result')client!.receive(frame);}); + await client.offer(f.enrolled.gateway,report);const first=await client.commit(f.enrolled.gateway,report.deduplicationId!); + expect(await client.outcome(f.enrolled.gateway,report.deduplicationId!)).toEqual(first); + expect(await client.commit(f.enrolled.gateway,report.deduplicationId!)).toEqual(first);expect(f.compute).toHaveBeenCalledTimes(1); + ws.send(JSON.stringify({v:1,type:'health',health:{version:'test',uptime:10,mqtt:'connected',fallback:false,queueDepth:1,uncertain:2,reconciled:1,superseded:1,updatesEnabled:false,lastError:'none'}})); + // Ordered RPC response confirms that the preceding heartbeat was handled. + await client.outcome(f.enrolled.gateway,report.deduplicationId!); + const response=await fetch(f.base+'/api/gateways',{headers:{cookie:f.cookie}});const body=await response.text(); + expect(JSON.parse(body).gateways[0]).toMatchObject({online:true,health:{uncertain:2,reconciled:1,superseded:1,queueDepth:1}}); + expect(body).not.toContain(f.enrolled.credential);expect(body).not.toContain(f.token); + const closed=once(ws,'close'); + const revoked=await fetch(`${f.base}/api/gateways/${f.enrolled.gateway}/revoke`,{method:'POST',headers:{cookie:f.cookie,origin:f.base}}); + expect(revoked.status).toBe(200);await closed; + expect(f.store.authenticateAgent(f.enrolled.credential)).toBeNull(); + }finally{client?.disconnect();await f.close();} +}); + +test('central routes and socket upgrades refuse missing credentials and cross-site sessions',async()=>{ + const f=await fixture(); + try{ + for(const route of ['/api/gateways','/chirpstack/','/js/desktop.js','/healthz'])expect((await fetch(f.base+route)).status).toBe(401); + expect((await fetch(f.base+'/api/gateways',{headers:{cookie:f.cookie,origin:'https://foreign.invalid'}})).status).toBe(403); + for(const [endpoint,headers] of [ + ['/agent',{}],['/terminal',{origin:f.base}],['/terminal',{cookie:f.cookie,origin:'https://foreign.invalid'}], + ] as const){ + const status=await new Promise(resolve=>{ + const ws=new WebSocket(f.base.replace('http:','ws:')+endpoint,{headers}); + ws.on('unexpected-response',(request,response)=>{const code=response.statusCode!;response.resume();request.destroy();resolve(code);}); + ws.on('error',()=>{});ws.on('open',()=>{ws.terminate();resolve(101);}); + });expect(status).toBe(403); + } + }finally{await f.close();} +}); + +test('loopback fallback requires its own credential and returns persisted outcomes on repeated commits',async()=>{ + const compute=jest.fn(async(event,sink)=>sink({devEui:event.deviceInfo.devEui,fPort:2,confirmed:false,bytes:[1,0,0,0,0,0,0,0,0]})); + const processor=new DurableProcessor(':memory:',compute),server=fallbackServer(processor,'test-local-secret','gateway'); + const base=await start(server),client=new LocalDecider(Number(new URL(base).port),'test-local-secret',500); + try{ + expect((await fetch(base+'/operation',{method:'POST',headers:{'Content-Type':'application/json'},body:'{}'})).status).toBe(401); + await client.offer('gateway',report);const outcome=await client.commit('gateway',report.deduplicationId!); + expect(await client.outcome('gateway',report.deduplicationId!)).toEqual(outcome); + expect(await client.commit('gateway',report.deduplicationId!)).toEqual(outcome);expect(compute).toHaveBeenCalledTimes(1); + }finally{await close(server);processor.close();} +}); diff --git a/tests/services/tunnels.test.ts b/tests/services/tunnels.test.ts new file mode 100644 index 0000000..99ab1a0 --- /dev/null +++ b/tests/services/tunnels.test.ts @@ -0,0 +1,90 @@ +import { EventEmitter } from 'events'; +import { once } from 'events'; +import http from 'http'; +import { Client, Server } from 'ssh2'; +import { generateKeyPairSync } from 'crypto'; +import WebSocket from 'ws'; +import { TunnelMux, gatewayTarget } from '../../src/central/tunnels'; +import { parseMessage } from '../../src/central/protocol'; + +function pair(resolveTarget:ConstructorParameters[1],idleMs=10000){ + class Link extends EventEmitter { + readyState=WebSocket.OPEN;bufferedAmount=0;peer?:Link; + send(body:string,done?:(error?:Error)=>void){queueMicrotask(()=>{if(this.readyState===WebSocket.OPEN)this.peer?.emit('message',body);done?.();});} + close(){this.readyState=WebSocket.CLOSED;this.emit('close');} + } + const a=new Link(),b=new Link();a.peer=b;b.peer=a; + const central=new TunnelMux(a as unknown as WebSocket,undefined,{sessions:2,idleMs,bytesPerSecond:1024*1024}); + const agent=new TunnelMux(b as unknown as WebSocket,resolveTarget,{sessions:2,idleMs,bytesPerSecond:1024*1024}); + a.on('message',text=>{const msg=parseMessage(text,'agent');if(msg.type.startsWith('tunnel-'))central.receive(msg as Parameters[0]);}); + b.on('message',text=>{const msg=parseMessage(text,'central');if(msg.type.startsWith('tunnel-'))agent.receive(msg as Parameters[0]);}); + return {central,agent,close:()=>{a.close();b.close();central.close();agent.close();}}; +} +test('SSH2 over the multiplexed stream authenticates, exchanges bytes, resizes and cleans up',async()=>{ + const key=generateKeyPairSync('rsa',{modulusLength:2048}).privateKey.export({type:'pkcs1',format:'pem'}); + let resized!:()=>void;const resizedEvent=new Promise(resolve=>{resized=resolve;}); + const resize=jest.fn();const connections=new Set(); + const sshServer=new Server({hostKeys:[key]},connection=>{ + connections.add(connection);connection.on('error',()=>{});connection.once('close',()=>connections.delete(connection)); + connection.on('authentication',ctx=>{if(ctx.method==='password'&&ctx.username==='test'&&ctx.password==='test-only-password')ctx.accept();else ctx.reject();}); + connection.on('ready',()=>connection.on('session',accept=>{ + const session=accept();session.on('pty',accept=>accept());session.on('window-change',(accept,_reject,info)=>{resize(info);resized();accept?.();}); + session.on('shell',accept=>{const channel=accept();channel.on('data',bytes=>channel.write(bytes));}); + })); + }); + await new Promise(resolve=>sshServer.listen(0,'127.0.0.1',resolve)); + const port=(sshServer.address() as import('net').AddressInfo).port; + const link=pair(async request=>{if(request.purpose!=='ssh'||request.host!=='ssh'||request.port!==22)throw new Error('not allowed');return {host:'127.0.0.1',port};}); + const client=new Client();client.on('error',()=>{}); + try { + const sock=await link.central.open('ssh','ssh',22); + const ready=once(client,'ready');client.connect({sock,username:'test',password:'test-only-password',readyTimeout:2000});await ready; + const channel=await new Promise((resolve,reject)=>client.shell({cols:80,rows:24},(e,c)=>e?reject(e):resolve(c))); + const reply=once(channel,'data');channel.write('hello through agent');expect((await reply)[0].toString()).toBe('hello through agent'); + channel.setWindow(31,92,0,0); + await resizedEvent; + await expect(link.central.open('ssh','ssh',2375)).rejects.toThrow(); + channel.end();client.end(); + expect(resize).toHaveBeenCalledWith(expect.objectContaining({cols:92,rows:31})); + }finally{client.destroy();link.close();for(const c of connections)c.end();await new Promise(resolve=>sshServer.close(()=>resolve()));} +}); +test('HTTP and gRPC-Web bytes travel through the same stream with backpressure',async()=>{ + const body=Buffer.alloc(180000,42); + const upstream=http.createServer((req,res)=>{res.setHeader('Content-Type','application/grpc-web+proto');req.pipe(res);}); + await new Promise(resolve=>upstream.listen(0,'127.0.0.1',resolve)); + const port=(upstream.address() as import('net').AddressInfo).port; + const link=pair(async()=>({host:'127.0.0.1',port,origin:`http://127.0.0.1:${port}`})); + try { + const stream=await link.central.open('chirpstack','chirpstack',8080); + expect(stream.upstreamOrigin).toBe(`http://127.0.0.1:${port}`); + const agent=new http.Agent({keepAlive:false});agent.createConnection=()=>stream; + const result=await new Promise((resolve,reject)=>{ + const request=http.request({hostname:'not-resolved.invalid',port:8080,path:'/test',method:'POST',agent,headers:{'Content-Length':body.length}},response=>{ + const chunks:Buffer[]=[];response.on('data',chunk=>chunks.push(chunk));response.on('end',()=>resolve(Buffer.concat(chunks)));response.on('error',reject); + });request.on('error',reject);request.end(body); + }); + expect(result).toEqual(body);agent.destroy(); + }finally{link.close();upstream.closeAllConnections();await new Promise(resolve=>upstream.close(()=>resolve()));} +}); +test('gateway allowlists are purpose-specific and metadata, Docker and fallback ports are refused',async()=>{ + const request={v:1 as const,type:'tunnel-open' as const,id:'t',purpose:'ssh' as const,host:'ssh',port:22}; + expect(await gatewayTarget(request,{})).toEqual({host:'127.0.0.1',port:22}); + await expect(gatewayTarget({...request,port:2375},{})).rejects.toThrow(); + for(const [host,port] of [['169.254.169.254',80],['127.0.0.1',2375],['127.0.0.1',3001],['192.168.1.2',80]] as const){ + await expect(gatewayTarget({...request,purpose:'browser',host,port},{})).rejects.toThrow(); + } + expect(await gatewayTarget({...request,purpose:'browser',host:'192.168.1.2',port:80},{AGENT_BROWSER_ALLOW_LAN:'true'})).toEqual({host:'192.168.1.2',port:80}); +}); + +test('closing the agent link destroys active streams and refuses new sessions',async()=>{ + const upstream=http.createServer((_req,_res)=>{}); + await new Promise(resolve=>upstream.listen(0,'127.0.0.1',resolve)); + const port=(upstream.address() as import('net').AddressInfo).port; + const link=pair(async()=>({host:'127.0.0.1',port})); + try{ + const stream=await link.central.open('browser','localhost',80); + const closed=once(stream,'close');link.close();await closed; + expect(stream.destroyed).toBe(true); + await expect(link.central.open('browser','localhost',80)).rejects.toThrow('unavailable'); + }finally{link.close();upstream.closeAllConnections();await new Promise(resolve=>upstream.close(()=>resolve()));} +}); diff --git a/tests/ui/gateways.spec.cjs b/tests/ui/gateways.spec.cjs new file mode 100644 index 0000000..aabacf0 --- /dev/null +++ b/tests/ui/gateways.spec.cjs @@ -0,0 +1,34 @@ +const { test,expect }=require('@playwright/test'); + +test('central selector identifies the gateway and exposes uncertainty without sending relay commands',async({page})=>{ + let selected='gateway-one'; + const gateways=[ + {id:'gateway-one',name:'North gateway',online:true,revoked:false,health:{mqtt:'connected',queueDepth:1,uncertain:3,reconciled:2,superseded:1}}, + {id:'gateway-two',name:'South gateway',online:false,revoked:false,health:{mqtt:'disconnected',queueDepth:0,uncertain:0,reconciled:0,superseded:0}}, + ]; + await page.route('**/api/gateways',route=>route.fulfill({json:{selected,gateways}})); + await page.route('**/api/gateways/select',route=>{selected=route.request().postDataJSON().id;return route.fulfill({json:{selected}});}); + await page.goto('/?central=1'); + await expect(page.locator('#gateway-status')).toContainText('3 uncertain seen'); + await expect(page.locator('#gateway-status')).toContainText('2 reconciled'); + await page.evaluate(()=>Desktop.launch('chirpstack')); + await expect(page.locator('#chirpstack .window-title')).toContainText('North gateway'); + await page.locator('#gateway-select').selectOption('gateway-two'); + await expect(page.locator('#chirpstack')).toBeHidden(); + await page.evaluate(()=>Desktop.launch('chirpstack')); + await expect(page.locator('#chirpstack .window-title')).toContainText('South gateway'); + await page.getByRole('button',{name:'Gateways',exact:true}).click(); + await expect(page.locator('#gateway-dialog')).toBeVisible(); + await expect(page.locator('#gateway-dialog')).toContainText('uncertainty never sends a relay command'); + await expect(page.locator('#gateway-list')).toContainText('3 uncertain seen'); + await page.setViewportSize({width:390,height:844}); + const bounds=await page.locator('#gateway-dialog').boundingBox(); + expect(bounds.x).toBeGreaterThanOrEqual(0);expect(bounds.x+bounds.width).toBeLessThanOrEqual(390); +}); + +test('standalone desktop does not expose central enrollment or gateway controls',async({page})=>{ + await page.goto('/'); + await expect(page.locator('#gateway-select')).toHaveCount(0); + await expect(page.locator('#gateway-dialog')).toHaveCount(0); + await expect(page.locator('#chirpstack-icon')).toBeVisible(); +}); diff --git a/tests/ui/serve.cjs b/tests/ui/serve.cjs index 32c6ec1..d9ac864 100644 --- a/tests/ui/serve.cjs +++ b/tests/ui/serve.cjs @@ -16,7 +16,7 @@ app.get('/', (req, res) => { icons.push({ id, label: i ? `Extension ${i}` : 'Streamr', iconHtml: '' }); windows.push({ id, title: i ? `Extension ${i}` : 'Streamr Publisher', contentHtml: '

Configuration

Pending transactions: 2

' }); } - res.render('index', { icons, windows }); + res.render('index', { icons, windows, central:req.query.central==='1' }); }); app.post('/api/actions/:moduleId/:actionId', (req, res) => res.json({ success: true, message: 'Published 2 transactions (test fixture)' })); const server = require('node:http').createServer(app); From 7b97e1d21a4b2fef2466ee1853f9cb4f01af4a62 Mon Sep 17 00:00:00 2001 From: "Isaac J. Newton" Date: Tue, 17 Nov 2026 17:58:10 +0000 Subject: [PATCH 6/9] feat: stream isolated browser sessions through guarded gateway routing --- src/browser/cdp.ts | 26 +++++ src/browser/engine.ts | 147 +++++++++++++++++++++++++ src/browser/proxy.ts | 154 +++++++++++++++++++++++++++ src/browser/service.ts | 42 ++++++++ src/central/destinations.ts | 2 +- src/central/tunnels.ts | 6 +- src/public/css/global.css | 1 + src/public/js/browser.js | 68 ++++++++---- src/services/server.ts | 14 +++ src/views/index.hbs | 5 +- tests/services/browser-proxy.test.ts | 91 ++++++++++++++++ tests/services/tunnels.test.ts | 10 ++ tests/ui/browser.spec.cjs | 39 ++++--- tests/ui/serve-auth.cjs | 14 +++ 14 files changed, 578 insertions(+), 41 deletions(-) create mode 100644 src/browser/cdp.ts create mode 100644 src/browser/engine.ts create mode 100644 src/browser/proxy.ts create mode 100644 src/browser/service.ts create mode 100644 tests/services/browser-proxy.test.ts diff --git a/src/browser/cdp.ts b/src/browser/cdp.ts new file mode 100644 index 0000000..9ef222a --- /dev/null +++ b/src/browser/cdp.ts @@ -0,0 +1,26 @@ +import WebSocket from 'ws'; +import { EventEmitter } from 'events'; + +export class CDP extends EventEmitter { + private next=0; + private pending=new Mapvoid;reject:(error:Error)=>void;timer:ReturnType}>(); + private constructor(private socket:WebSocket){ + super();socket.on('message',bytes=>{ + try{const value=JSON.parse(bytes.toString()) as {id?:number;method?:string;params?:unknown;result?:unknown;error?:unknown}; + if(value.id){const pending=this.pending.get(value.id);if(!pending)return;this.pending.delete(value.id);clearTimeout(pending.timer);if(value.error)pending.reject(new Error('Browser engine command failed.'));else pending.resolve(value.result);} + else if(value.method)this.emit(value.method,value.params); + }catch{socket.close();} + });socket.on('close',()=>{for(const p of this.pending.values()){clearTimeout(p.timer);p.reject(new Error('Browser engine disconnected.'));}this.pending.clear();this.emit('closed');});socket.on('error',()=>socket.close()); + } + static async connect(url:string):Promise{ + const socket=new WebSocket(url,{maxPayload:8*1024*1024,handshakeTimeout:5000}); + await new Promise((resolve,reject)=>{socket.once('open',resolve);socket.once('error',reject);});return new CDP(socket); + } + call>(method:string,params:Record={}):Promise{ + if(this.socket.readyState!==WebSocket.OPEN||this.pending.size>256)return Promise.reject(new Error('Browser engine unavailable.')); + const id=++this.next; + return new Promise((resolve,reject)=>{const timer=setTimeout(()=>{this.pending.delete(id);reject(new Error('Browser command timeout.'));},10000); + this.pending.set(id,{resolve:value=>resolve(value as T),reject,timer});this.socket.send(JSON.stringify({id,method,params}));}); + } + close():void{this.socket.close();} +} diff --git a/src/browser/engine.ts b/src/browser/engine.ts new file mode 100644 index 0000000..abc21b3 --- /dev/null +++ b/src/browser/engine.ts @@ -0,0 +1,147 @@ +import fs from 'fs'; +import os from 'os'; +import path from 'path'; +import { spawn, execFile, ChildProcess } from 'child_process'; +import { promisify } from 'util'; +import { createHash, X509Certificate } from 'crypto'; +import type { Duplex } from 'stream'; +import { BrowserProxy, browserURL, browserAddress } from './proxy'; +import { CDP } from './cdp'; +import type { ConsoleRole } from '../central/config'; + +const execute=promisify(execFile); +interface Paused {requestId:string;networkId?:string;frameId:string;resourceType:string;request:{url:string;method:string;headers:Record}} +interface NetworkRequest {requestId:string;frameId:string;type:string;hasUserGesture?:boolean;redirectResponse?:unknown} +export interface EngineOptions {role:ConsoleRole;gateway?:string;executable:string;tunnel?:(host:string,port:number)=>Promise;emit:(message:Record)=>void;testUnsandboxed?:boolean} +export class BrowserEngine { + private browser?:CDP; + private directory='';private process?:ChildProcess;private proxy?:BrowserProxy;private cdp?:CDP; + private frames=new Map();private requests=new Map(); + private main='';private typed?:string;private closed=false;private ready=false; + private width=1024;private height=700;private current='about:blank';private activity=Date.now();private born=Date.now(); + private timer?:ReturnType;private queued=false; + constructor(private options:EngineOptions){} + async start():Promise{ + if(!path.isAbsolute(this.options.executable)||!fs.existsSync(this.options.executable))throw new Error('Browser engine not available. Install the optional browser image.'); + if(this.options.testUnsandboxed&&process.env.NODE_ENV!=='test')throw new Error('Unsandboxed browser is allowed only in test fixtures.'); + this.directory=fs.mkdtempSync(path.join(os.tmpdir(),'console-browser-'));fs.chmodSync(this.directory,0o700); + try{ + const key=path.join(this.directory,'proxy.key'),cert=path.join(this.directory,'proxy.crt'); + await execute('openssl',['req','-x509','-newkey','rsa:2048','-nodes','-keyout',key,'-out',cert,'-days','1','-subj','/CN=Console browser session'],{timeout:10000,maxBuffer:65536}); + if(this.closed)throw new Error('Browser session closed.'); + const certificate=fs.readFileSync(cert,'utf8');const spki=createHash('sha256').update(new X509Certificate(certificate).publicKey.export({type:'spki',format:'der'})).digest('base64'); + this.proxy=new BrowserProxy({role:this.options.role,gateway:this.options.gateway,key:fs.readFileSync(key,'utf8'),cert:certificate,tunnel:this.options.tunnel}); + const proxyPort=await this.proxy.listen(); + const args=['--headless=new','--remote-debugging-address=127.0.0.1','--remote-debugging-port=0',`--user-data-dir=${this.directory}/profile`, + `--proxy-server=http://127.0.0.1:${proxyPort}`,'--proxy-bypass-list=<-loopback>',`--ignore-certificate-errors-spki-list=${spki}`, + '--disable-background-networking','--disable-component-update','--disable-sync','--disable-extensions','--disable-default-apps','--no-first-run', + '--force-webrtc-ip-handling-policy=disable_non_proxied_udp','--disable-quic','--disable-features=MediaRouter','--js-flags=--max-old-space-size=128','--window-size=1024,700','about:blank']; + if(this.options.testUnsandboxed)args.push('--no-sandbox'); + this.process=spawn(this.options.executable,args,{stdio:['ignore','ignore','pipe'],env:{PATH:process.env.PATH,HOME:this.directory,TMPDIR:this.directory,XDG_CACHE_HOME:path.join(this.directory,'cache'),LANG:'C.UTF-8'}}); + let stderr='';this.process.stderr?.on('data',chunk=>{stderr=(stderr+chunk.toString()).slice(-8192);}); + const endpoint=await new Promise((resolve,reject)=>{ + const timeout=setTimeout(()=>{cleanup();reject(new Error('Browser engine could not start with its sandbox.'));},12000); + const poll=setInterval(()=>{const match=stderr.match(/DevTools listening on (ws:\/\/127\.0\.0\.1:\d+\/devtools\/browser\/[\w-]+)/);if(match){cleanup();resolve(match[1]);}},25); + const cleanup=()=>{clearTimeout(timeout);clearInterval(poll);}; + this.process!.once('error',()=>{cleanup();reject(new Error('Browser executable unavailable.'));}); + this.process!.once('exit',()=>{cleanup();reject(new Error('Browser engine exited. Check sandbox support.'));}); + }); + if(this.closed)throw new Error('Browser session closed.'); + const browser=this.browser=await CDP.connect(endpoint); + if(this.closed)throw new Error('Browser session closed.'); + await browser.call('Browser.setDownloadBehavior',{behavior:'deny'}); + const target=await browser.call<{targetInfos:Array<{type:string;targetId:string}>}>('Target.getTargets'); + const id=target.targetInfos.find(t=>t.type==='page')?.targetId;if(!id)throw new Error('Browser page unavailable.'); + this.cdp=await CDP.connect(endpoint.replace(/\/devtools\/browser\/.+$/,`/devtools/page/${id}`)); + if(this.closed)throw new Error('Browser session closed.'); + browser.on('Target.targetCreated',(event:{targetInfo:{targetId:string;type:string}})=>{if(event.targetInfo.type==='page'&&event.targetInfo.targetId!==id)void browser.call('Target.closeTarget',{targetId:event.targetInfo.targetId}).catch(()=>{});}); + await browser.call('Target.setDiscoverTargets',{discover:true}); + const cdp=this.cdp; + cdp.on('Fetch.requestPaused',(event:Paused)=>void this.route(event)); + cdp.on('Network.requestWillBeSent',(event:NetworkRequest)=>{this.requests.set(event.requestId,event);if(this.requests.size>512)this.requests.delete(this.requests.keys().next().value!);}); + cdp.on('Page.frameNavigated',(event:{frame:{id:string;parentId?:string;url:string}})=>{ + if(!event.frame.parentId){this.main=event.frame.id;this.current=event.frame.url;this.options.emit({type:'navigation',url:this.current});void this.status();} + }); + cdp.on('Page.frameDetached',(event:{frameId:string})=>this.frames.delete(event.frameId)); + cdp.on('Page.loadEventFired',()=>void this.status()); + cdp.on('Page.frameStartedLoading',()=>this.options.emit({type:'loading',value:true})); + cdp.on('Page.frameStoppedLoading',()=>this.options.emit({type:'loading',value:false})); + cdp.on('Page.windowOpen',(event:{url:string;userGesture:boolean})=>{if(event.userGesture)void this.navigate(event.url);}); + cdp.on('Page.screencastFrame',(frame:{data:string;sessionId:number})=>{ + this.options.emit({type:'frame',data:frame.data,width:this.width,height:this.height});void cdp.call('Page.screencastFrameAck',{sessionId:frame.sessionId}).catch(()=>{}); + }); + cdp.on('closed',()=>this.close()); + await cdp.call('Page.enable');await cdp.call('Network.enable'); + await cdp.call('Network.setBypassServiceWorker',{bypass:true}); + await cdp.call('Fetch.enable',{patterns:[{urlPattern:'*',requestStage:'Request'}]}); + await cdp.call('Page.setInterceptFileChooserDialog',{enabled:true}); + // Popup links stay in this single isolated page; no extra browser contexts. + await cdp.call('Page.addScriptToEvaluateOnNewDocument',{source:`addEventListener('click',e=>{const a=e.target.closest?.('a[target]');if(a)a.target='_self'},true);window.open=(u)=>{if(u)location.href=String(u);return window};`}); + const tree=await cdp.call<{frameTree:{frame:{id:string}}}>('Page.getFrameTree');this.main=tree.frameTree.frame.id; + await cdp.call('Page.startScreencast',{format:'jpeg',quality:75,maxWidth:1600,maxHeight:1200,everyNthFrame:1}); + if(this.closed)throw new Error('Browser session closed.'); + this.ready=true;this.options.emit({type:'ready',url:'about:blank'}); + this.timer=setInterval(()=>{if(Date.now()-this.activity>10*60000||Date.now()-this.born>60*60000)this.close();},5000);this.timer.unref(); + }catch(error){this.close();throw error;} + } + private async route(event:Paused):Promise{ + const cdp=this.cdp;if(!cdp||!this.proxy)return; + try{ + const url=browserURL(event.request.url);const network=event.networkId?this.requests.get(event.networkId):undefined; + const top=event.resourceType==='Document'&&event.frameId===this.main; + const explicit=top&&this.typed===url.href; + const clicked=top&&network?.hasUserGesture===true&&!network.redirectResponse; + const originClass=this.frames.get(event.frameId)||this.frames.get(this.main)||'none'; + if(explicit)this.typed=undefined; + const permit=await this.proxy.permit(url.href,event.request.method,{pageClass:originClass,userNavigation:explicit||clicked,topLevel:top}); + if(event.resourceType==='Document'){this.frames.set(event.frameId,permit.classification);this.proxy.registerOrigin(url.href,permit.classification);} + const headers=Object.entries(event.request.headers).filter(([name])=>name.toLowerCase()!=='x-console-request').map(([name,value])=>({name,value})); + headers.push({name:'X-Console-Request',value:permit.token});await cdp.call('Fetch.continueRequest',{requestId:event.requestId,headers}); + }catch{await cdp.call('Fetch.failRequest',{requestId:event.requestId,errorReason:'BlockedByClient'}).catch(()=>{});this.options.emit({type:'notice',message:'A request was blocked by browser network policy.'});} + } + async navigate(input:string):Promise{ + if(!this.ready||!this.cdp)throw new Error('Browser engine not ready.'); + const url=browserAddress(input);this.typed=url.href;this.activity=Date.now();await this.cdp.call('Page.navigate',{url:url.href}); + } + async action(message:Record):Promise{ + if(!this.ready||!this.cdp)throw new Error('Browser engine not ready.');this.activity=Date.now();const cdp=this.cdp; + if(message.type==='navigate'&&typeof message.url==='string')return this.navigate(message.url); + if(message.type==='reload'){if(this.current!=='about:blank')this.typed=browserURL(this.current).href;await cdp.call('Page.reload');return;} + if(message.type==='stop'){await cdp.call('Page.stopLoading');return;} + if(message.type==='history'&&(message.direction===-1||message.direction===1)){ + const h=await cdp.call<{currentIndex:number;entries:Array<{id:number;url:string}>}>('Page.getNavigationHistory');const entry=h.entries[h.currentIndex+message.direction];if(entry){if(entry.url!=='about:blank')this.typed=browserURL(entry.url).href;await cdp.call('Page.navigateToHistoryEntry',{entryId:entry.id});}return; + } + if(message.type==='resize'&&Number.isInteger(message.width)&&Number.isInteger(message.height)){ + this.width=Math.min(1600,Math.max(320,Number(message.width)));this.height=Math.min(1200,Math.max(200,Number(message.height))); + await cdp.call('Emulation.setDeviceMetricsOverride',{width:this.width,height:this.height,deviceScaleFactor:1,mobile:false});return; + } + if(message.type==='text'&&typeof message.text==='string'&&message.text.length<=8192){await cdp.call('Input.insertText',{text:message.text});return;} + if(message.type==='copy'){ + const result=await cdp.call<{result:{value?:string}}>('Runtime.evaluate',{expression:"(()=>{const e=document.activeElement;return e&&typeof e.selectionStart==='number'?String(e.value).slice(e.selectionStart,e.selectionEnd):String(getSelection())})()",returnByValue:true});this.options.emit({type:'clipboard',text:(result.result.value||'').slice(0,65536)});return; + } + if(message.type==='key'&&typeof message.key==='string'&&message.key.length<40&&['keyDown','keyUp'].includes(String(message.event))){ + await cdp.call('Input.dispatchKeyEvent',{type:message.event,key:message.key,code:typeof message.code==='string'?message.code.slice(0,40):'',modifiers:Number(message.modifiers)||0,windowsVirtualKeyCode:Number(message.keyCode)||0});return; + } + if(message.type==='pointer'&&['mousePressed','mouseReleased','mouseMoved','mouseWheel'].includes(String(message.event))&&Number.isFinite(message.x)&&Number.isFinite(message.y)){ + await cdp.call('Input.dispatchMouseEvent',{type:message.event,x:Math.max(0,Math.min(this.width,Number(message.x))),y:Math.max(0,Math.min(this.height,Number(message.y))), + button:['left','right','middle'].includes(String(message.button))?message.button:'none',clickCount:message.event==='mousePressed'||message.event==='mouseReleased'?Math.min(3,Number(message.clicks)||1):0, + deltaX:Math.max(-2000,Math.min(2000,Number(message.dx)||0)),deltaY:Math.max(-2000,Math.min(2000,Number(message.dy)||0))});return; + } + if(message.type==='zoom'&&typeof message.factor==='number'&&message.factor>=.5&&message.factor<=2){await cdp.call('Emulation.setPageScaleFactor',{pageScaleFactor:message.factor});return;} + throw new Error('Invalid browser interaction.'); + } + private async status():Promise{ + if(this.queued||!this.cdp)return;this.queued=true; + try{const title=await this.cdp.call<{result:{value?:string}}>('Runtime.evaluate',{expression:'document.title',returnByValue:true});this.options.emit({type:'navigation',url:this.current,title:(title.result.value||'Browser').slice(0,200)});}catch{}finally{this.queued=false;} + } + close():void{ + const first=!this.closed;this.closed=true;this.ready=false;clearInterval(this.timer); + const cdp=this.cdp,browser=this.browser,proxy=this.proxy,child=this.process,directory=this.directory; + this.cdp=undefined;this.browser=undefined;this.proxy=undefined;this.process=undefined; + cdp?.close();browser?.close();proxy?.close(); + const remove=()=>{if(directory)fs.rmSync(directory,{recursive:true,force:true});}; + if(child&&child.exitCode===null&&child.signalCode===null){child.kill('SIGTERM');const timer=setTimeout(()=>child.kill('SIGKILL'),2000);timer.unref();child.once('exit',()=>{clearTimeout(timer);remove();});} + else remove(); + if(first)this.options.emit({type:'closed'}); + } +} diff --git a/src/browser/proxy.ts b/src/browser/proxy.ts new file mode 100644 index 0000000..77d798e --- /dev/null +++ b/src/browser/proxy.ts @@ -0,0 +1,154 @@ +import http, { IncomingMessage, ServerResponse } from 'http'; +import https from 'https'; +import net from 'net'; +import tls from 'tls'; +import { Duplex } from 'stream'; +import { randomBytes } from 'crypto'; +import { resolveTarget, destinationRoute, BrowsingContext, ResolvedTarget, normalizeHost } from '../central/destinations'; +import type { ConsoleRole } from '../central/config'; + +type ProxyTarget=ResolvedTarget|{hostname:string;address:string;family:null;classification:'local'}; +interface Permit { url:string; method:string; target:ProxyTarget; route:'internet'|'local'|'agent'; expires:number } +export interface ProxyOptions { + role:ConsoleRole; gateway?:string; key:string; cert:string; + tunnel?:(address:string,port:number)=>Promise; + resolve?:(host:string)=>Promise; +} +const hop=['connection','proxy-connection','proxy-authorization','proxy-authenticate','keep-alive','transfer-encoding','upgrade','te','trailer','x-console-request']; +export function browserURL(input:string):URL { + const url=new URL(input); + if(!['http:','https:'].includes(url.protocol)||url.username||url.password||url.href.length>8192)throw new Error('Use an HTTP or HTTPS address without credentials.'); + url.hash='';return url; +} +export function browserAddress(input:string):URL { + let text=input.trim();if(!text)text='https://www.google.com/'; + if(!/^https?:\/\//i.test(text))text=/^(localhost|[\w.-]+\.[\w.-]+|\[[a-f\d:]+\])(:\d+)?([/?#]|$)/i.test(text)?`http://${text}`:`https://www.google.com/search?q=${encodeURIComponent(text)}`; + return browserURL(text); +} +/** The proxy, not page JavaScript, owns one-use request permits and pinned DNS + * results. TLS CONNECT terminates here; it is never a blind route into a LAN. */ +export class BrowserProxy { + private permits=new Map(); + private sockets=new Set(); + private contexts=new WeakMap(); + private origins=new Map>(); + private server=http.createServer((req,res)=>void this.request(req,res)); + private inner=http.createServer((req,res)=>void this.request(req,res)); + private secure:tls.SecureContext; + private closed=false; + constructor(private options:ProxyOptions){ + this.secure=tls.createSecureContext({key:options.key,cert:options.cert,minVersion:'TLSv1.2'}); + for(const server of [this.server,this.inner]){ + server.maxHeadersCount=100;server.headersTimeout=15000;server.requestTimeout=60000; + server.on('upgrade',(req,socket,head)=>void this.upgrade(req,socket as net.Socket,head)); + server.on('clientError',(_error,socket)=>socket.destroy()); + } + this.server.on('connection',socket=>{if(this.sockets.size>=32){socket.destroy();return;}this.sockets.add(socket);socket.once('close',()=>this.sockets.delete(socket));socket.setTimeout(120000,()=>socket.destroy());}); + this.server.on('connect',(req,socket,head)=>{ + try{ + const target=browserURL(`https://${req.url}/`); + if(target.pathname!=='/'||head.length)throw new Error(); + socket.write('HTTP/1.1 200 Connection Established\r\n\r\n'); + const secured=new tls.TLSSocket(socket,{isServer:true,secureContext:this.secure,ALPNProtocols:['http/1.1']}); + this.contexts.set(secured,target.origin); + secured.on('error',()=>secured.destroy());this.inner.emit('connection',secured); + }catch{socket.destroy();} + }); + } + async listen():Promise{await new Promise(resolve=>this.server.listen(0,'127.0.0.1',resolve));return (this.server.address() as net.AddressInfo).port;} + async permit(raw:string,method:string,context:BrowsingContext):Promise<{token:string;classification:'public'|'local';url:string}>{ + if(this.closed)throw new Error('Browser session closed.'); + const url=browserURL(raw),hostname=normalizeHost(url.hostname); + // Local service names belong to the selected gateway's DNS namespace. Its + // tunnel endpoint resolves, classifies and pins the address before connect; + // it refuses public results and still applies the owner's LAN/port policy. + const gatewayName=this.options.role==='central'&&(/\.(local|lan)$/.test(hostname)||hostname==='localhost'||hostname.endsWith('.localhost')); + const target:ProxyTarget=gatewayName?{hostname,address:hostname==='localhost'||hostname.endsWith('.localhost')?'127.0.0.1':hostname,family:null,classification:'local'}:await (this.options.resolve||resolveTarget)(hostname); + const route=destinationRoute(this.options.role,target,context,this.options.gateway); + for(const [token,p] of this.permits)if(p.expires=256)throw new Error('Too many browser requests.'); + const token=randomBytes(24).toString('base64url'); + this.permits.set(token,{url:url.href,method,target,route,expires:Date.now()+20000}); + return {token,classification:target.classification as 'public'|'local',url:url.href}; + } + registerOrigin(raw:string,classification:'public'|'local'):void{ + const origin=browserURL(raw).origin; + const classes=this.origins.get(origin)||new Set();classes.add(classification);this.origins.set(origin,classes); + if(this.origins.size>256)this.origins.delete(this.origins.keys().next().value!); + } + private url(req:IncomingMessage):URL { + const origin=this.contexts.get(req.socket); + const url=browserURL(origin?new URL(req.url||'/',origin).href:(req.url||'').replace(/^ws:/i,'http:').replace(/^wss:/i,'https:')); + if(origin&&url.origin!==origin)throw new Error('CONNECT authority mismatch.'); + return url; + } + private take(req:IncomingMessage,url:URL):Permit{ + const token=req.headers['x-console-request'];if(typeof token!=='string')throw new Error('Missing request provenance.'); + const permit=this.permits.get(token);this.permits.delete(token); + if(!permit||permit.expires{ + const port=Number(url.port||(url.protocol==='https:'?443:80)); + if(permit.route==='agent'){ + if(!this.options.tunnel)throw new Error('Selected gateway is unavailable.'); + return this.options.tunnel(permit.target.address,port); + } + // Central private addresses can never fall through to net.connect. + if(this.options.role==='central'&&permit.target.classification!=='public')throw new Error('Central private network is inaccessible.'); + return new Promise((resolve,reject)=>{ + const socket=net.connect({host:permit.target.address,port}); + socket.setTimeout(10000,()=>socket.destroy(new Error('Connection timed out.'))); + socket.once('error',reject);socket.once('connect',()=>{socket.setTimeout(0);resolve(socket);}); + }); + } + private async upstream(req:IncomingMessage,url:URL,permit:Permit,upgrade=false):Promise{ + const raw=await this.connect(permit,url); + let socket:Duplex=raw; + if(url.protocol==='https:')socket=tls.connect({socket:raw as net.Socket,servername:net.isIP(permit.target.hostname)?undefined:permit.target.hostname,checkServerIdentity:(_host,cert)=>tls.checkServerIdentity(permit.target.hostname,cert),rejectUnauthorized:true}); + const agent=new http.Agent({keepAlive:false});agent.createConnection=()=>socket; + const headers=this.headers(req,url);if(upgrade){headers.connection='Upgrade';headers.upgrade='websocket';} + // TLS is already on the provided stream, so the HTTP client must not wrap it again. + const upstream=http.request({method:req.method,path:url.pathname+url.search,host:'browser-stream.invalid',agent,headers}); + upstream.setTimeout(60000,()=>upstream.destroy(new Error('Browser upstream timed out.'))); + upstream.once('close',()=>agent.destroy());req.once('aborted',()=>upstream.destroy()); + return upstream; + } + private async request(req:IncomingMessage,res:ServerResponse):Promise{ + try{ + const url=this.url(req),permit=this.take(req,url),upstream=await this.upstream(req,url,permit); + upstream.on('response',response=>{const headers={...response.headers};for(const name of hop)delete headers[name];res.writeHead(response.statusCode||502,headers);response.pipe(res);response.on('error',()=>res.destroy());}); + upstream.on('error',()=>{if(!res.headersSent)res.writeHead(502);res.end('Browser destination unavailable.');}); + res.once('close',()=>upstream.destroy());req.pipe(upstream); + }catch{res.writeHead(403,{'Content-Type':'text/plain'});res.end('Browser network policy refused this request.');req.resume();} + } + private async upgrade(req:IncomingMessage,socket:net.Socket,head:Buffer):Promise{ + try{ + const url=this.url(req);let permit:Permit; + if(req.headers['x-console-request'])permit=this.take(req,url); + else{ + // WebSocket handshakes bypass CDP Fetch. Chromium owns the Origin header; + // a script cannot choose it. Only previously classified document origins + // may use this route; a public origin never authorizes private traffic. + const origin=typeof req.headers.origin==='string'?req.headers.origin:''; + const classes=this.origins.get(origin);if(!classes||classes.size!==1)throw new Error(); + const issued=await this.permit(url.href,req.method||'GET',{pageClass:[...classes][0],userNavigation:false,topLevel:false}); + req.headers['x-console-request']=issued.token;permit=this.take(req,url); + } + const upstream=await this.upstream(req,url,permit,true); + upstream.on('upgrade',(response,remote,extra)=>{ + const headers={...response.headers};delete headers['x-console-request']; + socket.write(`HTTP/1.1 ${response.statusCode} Switching Protocols\r\n`+Object.entries(headers).map(([k,v])=>`${k}: ${v}`).join('\r\n')+'\r\n\r\n'); + if(extra.length)socket.write(extra);if(head.length)remote.write(head); + remote.pipe(socket).pipe(remote);socket.once('close',()=>remote.destroy());remote.once('error',()=>socket.destroy()); + }); + upstream.on('response',()=>socket.destroy());upstream.on('error',()=>socket.destroy());upstream.end(); + }catch{socket.destroy();} + } + close():void{this.closed=true;this.permits.clear();for(const socket of this.sockets)socket.destroy();this.server.close();this.inner.close();} +} diff --git a/src/browser/service.ts b/src/browser/service.ts new file mode 100644 index 0000000..e07f3da --- /dev/null +++ b/src/browser/service.ts @@ -0,0 +1,42 @@ +import type http from 'http'; +import WebSocket from 'ws'; +import type { Duplex } from 'stream'; +import { registerSocket } from '../services/socket-router'; +import { RateLimit } from '../central/auth'; +import type { ConsoleRole } from '../central/config'; +import { BrowserEngine } from './engine'; + +interface BrowserServiceOptions { + role:ConsoleRole; executable?:string; testUnsandboxed?:boolean; + gateway?:(request:http.IncomingMessage)=>string|null; + owner?:(request:http.IncomingMessage)=>string; + tunnel?:(gateway:string,host:string,port:number)=>Promise; + audit?:(request:http.IncomingMessage,event:'browser-start'|'browser-end',gateway?:string)=>void; +} +export function attachBrowser(server:http.Server,options:BrowserServiceOptions):void{ + const wss=new WebSocket.Server({noServer:true,maxPayload:65536,perMessageDeflate:false}); + const engines=new Set(),owners=new Set(); + const starts=new RateLimit(12,60000); + registerSocket(server,'/browser/live',wss); + wss.on('connection',(ws,request)=>{ + const send=(message:Record)=>{if(ws.readyState===WebSocket.OPEN&&ws.bufferedAmount<2*1024*1024)ws.send(JSON.stringify(message));}; + const gateway=options.gateway?.(request)||undefined,owner=options.owner?.(request); + if(!starts.allow(owner||request.socket.remoteAddress||'local')||engines.size>=3||(owner&&owners.has(owner))){send({type:'error',message:'Browser session limit reached. Close another Browser window and retry.'});ws.close();return;} + if(options.role==='central'&&!gateway){send({type:'error',message:'Select a gateway before opening Browser.'});ws.close();return;} + const engine=new BrowserEngine({role:options.role,gateway,executable:options.executable||process.env.BROWSER_EXECUTABLE||'/usr/bin/chromium', + tunnel:options.tunnel&&gateway?(host,port)=>options.tunnel!(gateway,host,port):undefined,testUnsandboxed:options.testUnsandboxed,emit:message=>{send(message);if(message.type==='closed')ws.close();}}); + engines.add(engine);if(owner)owners.add(owner);let audited=false; + const limiter=new RateLimit(240,1000,1);let active=0; + ws.on('message',data=>{ + if(!limiter.allow('input')||active>32){ws.close(1008,'Browser interaction limit');return;} + try{const value:unknown=JSON.parse(data.toString());if(!value||typeof value!=='object'||Array.isArray(value))throw new Error(); + active++;void engine.action(value as Record).catch(()=>send({type:'notice',message:'Browser action unavailable.'})).finally(()=>active--); + }catch{ws.close(1008,'Invalid browser interaction');} + }); + const cleanup=()=>{engine.close();engines.delete(engine);if(owner)owners.delete(owner);if(audited){audited=false;options.audit?.(request,'browser-end',gateway);}}; + ws.once('close',cleanup);ws.on('error',cleanup); + void engine.start().then(()=>{if(ws.readyState!==WebSocket.OPEN){cleanup();return;}audited=true;options.audit?.(request,'browser-start',gateway);}) + .catch(()=>{send({type:'error',message:'Browser engine not available. Install the optional browser image with Chromium and working sandbox support.'});cleanup();ws.close();}); + }); + server.once('close',()=>{for(const engine of engines)engine.close();for(const ws of wss.clients)ws.terminate();wss.close();}); +} diff --git a/src/central/destinations.ts b/src/central/destinations.ts index d92fd26..20b6306 100644 --- a/src/central/destinations.ts +++ b/src/central/destinations.ts @@ -64,7 +64,7 @@ export async function resolveTarget(input: string, resolve: Resolver = host => l } export type BrowsingContext = { pageClass: 'public' | 'local' | 'none'; userNavigation: boolean; topLevel: boolean }; -export function destinationRoute(role: 'standalone' | 'gateway' | 'central', target: ResolvedTarget, context: BrowsingContext, gateway?: string): 'internet' | 'local' | 'agent' { +export function destinationRoute(role: 'standalone' | 'gateway' | 'central', target: Pick, context: BrowsingContext, gateway?: string): 'internet' | 'local' | 'agent' { if (target.classification === 'blocked') throw new Error('Destination is not permitted.'); if (target.classification === 'public') return 'internet'; if (!(context.userNavigation && context.topLevel) && context.pageClass !== 'local') throw new Error('Public pages cannot access private destinations.'); diff --git a/src/central/tunnels.ts b/src/central/tunnels.ts index a7efd84..f71bb75 100644 --- a/src/central/tunnels.ts +++ b/src/central/tunnels.ts @@ -4,7 +4,7 @@ import tls from 'tls'; import { randomUUID } from 'crypto'; import WebSocket from 'ws'; import { CentralMessage, TunnelMessage, TunnelPurpose, MAX_TUNNEL_CHUNK } from './protocol'; -import { normalizeHost, resolveTarget } from './destinations'; +import { normalizeHost, resolveTarget, classifyAddress } from './destinations'; import { chirpstackTarget } from '../services/chirpstack'; type Open = Extract; @@ -24,10 +24,10 @@ export async function gatewayTarget(request:Open,env:NodeJS.ProcessEnv=process.e return {host:resolved.address,port:Number(target.port||(target.protocol==='https:'?443:80)),secure:target.protocol==='https:',servername:normalizeHost(target.hostname),origin:target.origin}; } const target=await resolveTarget(request.host); - if(target.classification!=='local')throw new Error('Browser tunnels are restricted to local destinations.'); + if(target.classification!=='local'||classifyAddress(target.address)!=='local')throw new Error('Browser tunnels are restricted to local destinations.'); const loopback=target.address==='::1'||target.address.startsWith('127.')||/^::ffff:7f[\da-f]{2}:/.test(target.address); if(!loopback&&env.AGENT_BROWSER_ALLOW_LAN!=='true')throw new Error('Gateway owner has not enabled browser access to the LAN.'); - const denied=new Set([22,2375,2376,Number(env.GATEWAY_FALLBACK_PORT||3001),Number(env.GATEWAY_UPDATER_PORT||3002)]); + const denied=new Set([22,Number(env.AGENT_SSH_PORT||22),2375,2376,Number(env.GATEWAY_FALLBACK_PORT||3001),Number(env.GATEWAY_UPDATER_PORT||3002)]); if(denied.has(request.port))throw new Error('This infrastructure port is not a browser target.'); const allowed=(env.AGENT_BROWSER_PORTS||'80,443,3000,8080,8090').split(',').map(Number); if(!allowed.includes(request.port))throw new Error('Gateway owner has not allowed this browser port.'); diff --git a/src/public/css/global.css b/src/public/css/global.css index ed2ebd6..08b9ea7 100644 --- a/src/public/css/global.css +++ b/src/public/css/global.css @@ -363,3 +363,4 @@ dialog::backdrop { background:#14232e88; backdrop-filter:blur(3px); }dialog h2 { .app-dialog-layer > #mm-dialog { width:min(540px,100%); max-height:100%; } @media(max-width:700px) { .app-dialog-layer { padding:8px; } .app-dialog-layer > dialog.app-dialog { padding:18px; } } @media(max-height:500px) and (min-width:701px) { .app-dialog-layer { top:40px; } } +.browser-controls{flex-wrap:wrap;gap:6px}.browser-controls button,.browser-controls select{min-height:34px;background:var(--surface);color:var(--text);border:1px solid var(--border);border-radius:var(--small-radius);padding:4px 8px}.browser-controls #browser-search{min-width:180px}#browser-status{font:12px var(--font);padding:7px 12px;background:var(--surface-alt);color:var(--muted)}#browser-view{position:relative;flex:1;min-height:0;overflow:hidden;background:var(--surface);touch-action:none}#browser-canvas{display:block;width:100%;height:100%;object-fit:fill}#browser-input{position:absolute;left:0;bottom:0;width:1px;height:1px;opacity:.01;border:0;padding:0;resize:none} diff --git a/src/public/js/browser.js b/src/public/js/browser.js index a000a71..aafd0b8 100644 --- a/src/public/js/browser.js +++ b/src/public/js/browser.js @@ -1,21 +1,53 @@ (() => { - const form = document.getElementById('browser-search'); - form.addEventListener('submit', event => { - const input = document.getElementById('browser-query').value.trim(); - if (!input) { event.preventDefault(); return; } - const external = document.getElementById('browser-external'); - if (/^https?:\/\//i.test(input)) { - event.preventDefault(); - try { - const url = new URL(input); - if (url.username || url.password) throw new Error(); - document.querySelector('#browser iframe').src = url.href; - external.href = url.href; - } catch { showNotification('Enter a valid HTTP or HTTPS address without credentials.', 'error', document.getElementById('browser')); } - return; - } - document.getElementById('browser-query').value = input; - external.href = `https://www.google.com/search?q=${encodeURIComponent(input)}`; - // Native GET form submission performs URL encoding and opens Google top-level. + const win=document.getElementById('browser'),view=document.getElementById('browser-view'),canvas=document.getElementById('browser-canvas'),input=document.getElementById('browser-input'); + const query=document.getElementById('browser-query'),status=document.getElementById('browser-status'); + let socket,ready=false,remoteWidth=1024,remoteHeight=700,framePending=false; + const send=value=>{if(socket?.readyState===WebSocket.OPEN)socket.send(JSON.stringify(value));}; + const size=()=>{if(ready)send({type:'resize',width:Math.round(view.clientWidth),height:Math.round(view.clientHeight)});}; + function open(){ + if(socket&&[WebSocket.OPEN,WebSocket.CONNECTING].includes(socket.readyState))return; + status.textContent='Starting isolated Browser…'; + socket=new WebSocket(`${location.protocol==='https:'?'wss:':'ws:'}//${location.host}/browser/live`); + socket.onmessage=event=>{ + const message=JSON.parse(event.data); + if(message.type==='closed'&&ready){ready=false;status.textContent='Browser session ended. Close and reopen to start a new session.';} + if(message.type==='ready'){ready=true;status.textContent='Ready. Search or enter an address. Downloads and uploads are disabled.';size();} + if(message.type==='error'||message.type==='notice')status.textContent=message.message; + if(message.type==='loading')status.textContent=message.value?'Loading…':'Ready'; + if(message.type==='navigation'){ + if(message.url&&message.url!=='about:blank'&&document.activeElement!==query)query.value=message.url; + if(message.title){win.dataset.gatewayBaseTitle=`${message.title} · Browser`;const title=win.dataset.gatewayBaseTitle+(win.dataset.gatewayName?` · ${win.dataset.gatewayName}`:'');win.dataset.windowTitle=title;win.querySelector('.window-title').textContent=title;document.title=`${title} · M3tering Console`;} + } + if(message.type==='frame'&&!framePending){framePending=true;const image=new Image();image.onload=()=>{canvas.width=remoteWidth=image.width;canvas.height=remoteHeight=image.height;canvas.getContext('2d').drawImage(image,0,0);framePending=false;};image.onerror=()=>{framePending=false;};image.src=`data:image/jpeg;base64,${message.data}`;} + if(message.type==='clipboard')navigator.clipboard.writeText(message.text).then(()=>{status.textContent='Selected text copied.';}).catch(()=>{status.textContent='Clipboard permission unavailable.';}); + }; + socket.onclose=()=>{ready=false;if(status.textContent==='Starting isolated Browser…')status.textContent='Browser engine not available. Install the optional Chromium browser image.';}; + socket.onerror=()=>{status.textContent='Browser connection unavailable. Close and reopen the application to retry.';}; + } + document.getElementById('browser-search').onsubmit=event=>{event.preventDefault();try{if(/^[a-z][a-z0-9+.-]*:\/\//i.test(query.value)){const url=new URL(query.value);if(!['http:','https:'].includes(url.protocol)||url.username||url.password)throw new Error('Use an HTTP or HTTPS address without credentials.');}}catch(error){showNotification(error.message,'error',win);return;}if(ready)send({type:'navigate',url:query.value});else status.textContent='Browser engine not available yet.';}; + for(const [id,value] of [['back',{type:'history',direction:-1}],['forward',{type:'history',direction:1}],['reload',{type:'reload'}],['stop',{type:'stop'}],['home',{type:'navigate',url:'https://www.google.com/'}],['copy',{type:'copy'}]])document.getElementById(`browser-${id}`).onclick=()=>send(value); + document.getElementById('browser-zoom').onchange=event=>send({type:'zoom',factor:Number(event.target.value)}); + const point=event=>{const rect=canvas.getBoundingClientRect();return {x:(event.clientX-rect.left)*remoteWidth/rect.width,y:(event.clientY-rect.top)*remoteHeight/rect.height};}; + const button=event=>['left','middle','right'][event.button]||'none'; + let touch; + view.onpointerdown=event=>{if(!ready)return;event.preventDefault();input.focus({preventScroll:true});view.setPointerCapture(event.pointerId);if(event.pointerType==='touch'){touch={x:event.clientX,y:event.clientY,start:point(event),moved:false};return;}send({type:'pointer',event:'mousePressed',...point(event),button:button(event),clicks:event.detail||1});}; + view.onpointermove=event=>{if(touch){const dx=touch.x-event.clientX,dy=touch.y-event.clientY;if(touch.moved||Math.abs(dx)+Math.abs(dy)>6){touch.moved=true;send({type:'pointer',event:'mouseWheel',...point(event),dx,dy});touch.x=event.clientX;touch.y=event.clientY;}return;}if(ready)send({type:'pointer',event:'mouseMoved',...point(event),button:event.buttons?'left':'none'});}; + view.onpointercancel=()=>{touch=undefined;}; + view.onpointerup=event=>{if(touch){if(!touch.moved){send({type:'pointer',event:'mousePressed',...touch.start,button:'left',clicks:1});send({type:'pointer',event:'mouseReleased',...touch.start,button:'left',clicks:1});}touch=undefined;return;}if(ready)send({type:'pointer',event:'mouseReleased',...point(event),button:button(event),clicks:event.detail||1});}; + view.addEventListener('wheel',event=>{event.preventDefault();send({type:'pointer',event:'mouseWheel',...point(event),dx:event.deltaX,dy:event.deltaY});},{passive:false}); + view.oncontextmenu=event=>event.preventDefault(); + input.addEventListener('input',event=>{if(event.isComposing)return;if(input.value)send({type:'text',text:input.value});input.value='';}); + input.addEventListener('compositionend',()=>{if(input.value)send({type:'text',text:input.value});input.value='';}); + input.addEventListener('paste',event=>{event.preventDefault();send({type:'text',text:event.clipboardData.getData('text').slice(0,8192)});}); + for(const name of ['keydown','keyup'])input.addEventListener(name,event=>{ + if(event.isComposing)return; + if((event.ctrlKey||event.metaKey)&&event.key.toLowerCase()==='c'){event.preventDefault();if(name==='keydown')send({type:'copy'});return;} + if((event.ctrlKey||event.metaKey)&&event.key.toLowerCase()==='v')return; + if(event.key.length===1&&!event.ctrlKey&&!event.metaKey&&!event.altKey)return; + event.preventDefault();send({type:'key',event:name==='keydown'?'keyDown':'keyUp',key:event.key,code:event.code,keyCode:event.keyCode,modifiers:(event.altKey?1:0)|(event.ctrlKey?2:0)|(event.metaKey?4:0)|(event.shiftKey?8:0)}); }); + new ResizeObserver(size).observe(view); + window.addEventListener('desktop:open',event=>{if(event.detail.id==='browser')open();}); + window.addEventListener('desktop:close',event=>{if(event.detail.id==='browser'){socket?.close();socket=undefined;ready=false;}}); + window.addEventListener('pagehide',()=>socket?.close()); })(); diff --git a/src/services/server.ts b/src/services/server.ts index 898edd8..5d0b07d 100644 --- a/src/services/server.ts +++ b/src/services/server.ts @@ -6,6 +6,7 @@ import { proxyChirpstack, proxyChirpstackThrough } from './chirpstack'; import { createLogger } from '../utils/logger'; import { getUIComponents, invokeUIAction } from '../lib/utils'; import { central, config } from '../central/runtime'; +import { attachBrowser } from '../browser/service'; import { protectBrowserSockets } from './socket-router'; const logger = createLogger('[server]'); @@ -75,6 +76,19 @@ app.post('/api/actions/:moduleId/:actionId', async (req: Request, res: Response, export const server = http.createServer(app); if(central){protectBrowserSockets(server,central.auth.authorize);central.hub.mount(app,server);} +const browserRuntime=central; +const browserActors=new WeakMap(); +attachBrowser(server,{role:config.role,gateway:request=>browserRuntime?.hub.selected(request)||null, + owner:browserRuntime?request=>browserRuntime.auth.session(request)?.id||'unauthorized':undefined, + tunnel:browserRuntime?(gateway,host,port)=>browserRuntime.hub.open(gateway,'browser',host,port):undefined, + audit:browserRuntime?(request,event,gateway)=>{ + if(event==='browser-start'){const actor=browserRuntime.auth.session(request)?.id;if(actor)browserActors.set(request,actor);} + const actor=browserActors.get(request);if(actor)browserRuntime.identities.audit(actor,event,gateway); + if(event==='browser-end')browserActors.delete(request); + }:undefined, + testUnsandboxed:process.env.NODE_ENV==='test'&&process.env.BROWSER_UNSANDBOXED_TEST==='true', +}); + export function startServer() { server.once('error', (error: NodeJS.ErrnoException) => { logger.error(error.code === 'EADDRINUSE' ? `Port ${port} is already occupied. Stop the duplicate Console instance or correct the conflicting service port mapping.` : `Console listener failed: ${error.code || 'unknown'}`); diff --git a/src/views/index.hbs b/src/views/index.hbs index af46a5b..f7b03ef 100644 --- a/src/views/index.hbs +++ b/src/views/index.hbs @@ -35,8 +35,9 @@