# Siparu

Kept aboard, proven ashore. A Signal K plugin that records your boat's bridge
data - position, speed, heading, wind, depth, and whatever engine, tank and
generator gauges she exposes - into an on-board history with voyage detection,
and serves it through a built-in dashboard and a read-only REST API.

The dashboard shows the bridge: speed, heading, wind, depth, position, the
logbook, voyages and the chart. Engine, tank and generator gauges have panels of
their own, built from what she reports rather than from a list: a boat with three
engines gets three sets of readings, and a boat with no generator gets no
generator tab. The same gauges are also served over the API (`GET /live`,
`GET /inventory`).

## Principles

- **Read-only.** The plugin never writes to your boat: no deltas are emitted,
  no PUT handlers registered, no action handlers, no NMEA out. The CI proves it
  on every commit - grep this codebase and see for yourself.
- **Nothing leaves until you pair her**, and pairing takes a deliberate tap at
  the helm. Unpair and it stops the same minute.
- **What she sends once paired.** Her bridge, every two seconds under way and
  once a minute at rest: position,
  speed and course over ground, heading, rate of turn, magnetic variation and
  deviation, navigation state, apparent and true wind with gust and direction,
  depth, air and water temperature, barometric pressure, and GPS satellite count.
  Plus any engine, tank or generator gauges she exposes (`propulsion.*`,
  `tanks.*`, `electrical.generators.*`). That is what makes the remote screen a
  bridge instead of a dot on a map, and it is more than a position: if that is
  more than you want to share, do not pair her.
- **Your history stays on board.** It is recorded on the boat as plain NDJSON
  with hourly and daily summaries. There is no bulk upload and the shore keeps no
  copy: a paired screen may ask her for one gauge's series in order to draw a
  graph, and she answers that from her own store. That question is the only thing
  she accepts from ashore. She takes no commands, because there are none to take.
- **The relay keeps her name and the time she was last seen.** Nothing else. Live
  frames pass through it to whatever screen you have open and are stored by
  nobody, so when she is offline the shore has nothing to show and says so.
- **One runtime dependency, pure JavaScript.** `ws`, which carries the uplink, and
  nothing else. It has no install script and no dependency of its own, and its two
  native helpers are optional peers - which is what lets the AppStore install this
  plugin with `npm --ignore-scripts` and have it work, on anything from a Raspberry
  Pi to a Victron Cerbo GX (Venus OS Large). Nothing here needs node-gyp.
- **Compatibility floor:** Node 20 + signalk-server 2.18.

## Not a safety system

Siparu is not a navigation, safety or alarm system, and it is not a substitute for
seamanship, a watchkeeper, or going aboard to look. It reads instruments that
drift, break and lie, and it carries what they say over networks that fail,
starting with the boat's own uplink: a screen with nothing wrong on it is not the
same thing as a boat that is fine, and the plugin raises no alarm to tell you
otherwise. The chart is for looking, not for navigating, and a depth reading is
whichever plane the boat's own sounder reports, which is not always the water
under the keel. Do not rely on this software to protect life or property.

## Before you pair: turn on Signal K security

Signal K ships with security switched off, and nothing in the setup makes you turn
it on. With it off, every plugin's HTTP surface is open to anyone who can reach
your boat's network, this one included. (The relay credential itself is out of
reach: it lives in a mode-600 file under the plugin's data directory, not in the
config. The relay address is not a plugin option at all - it comes from the
server process's environment, so nothing that writes plugin options can redirect
the boat.)

Because of that, the plugin locks its own writes while security is off: pairing,
unpairing and log edits refuse until you either add an admin user in Signal K or
tick "Allow pairing and log edits while Signal K security is off" in the plugin
settings. The tick exists for installs that cannot easily turn security on; it is
an acceptance of the risk, not a removal of it.

The lock cannot make an unsecured server safe. On such a server
`GET /skServer/plugins` already discloses every plugin's configuration, the
server's own config route can change any plugin's settings - including that very
tick - and the App Store will install code. The consequence peculiar to Siparu is
what a stranger on the marina wifi could do with an open door: link your boat to
**their** account while your own screen goes on saying "paired".

So before you pair, add an admin user in Signal K (Security > Users). It takes a
minute and it is the difference between a boat you share and a boat you leak.

## The chart, and where its tiles come from

The dashboard's chart draws its coastline and place names from a basemap tile
server. The default is a free, keyless, planet-wide host, and like any tile
server it receives the requesting IP address and the tile coordinates being
viewed. Those coordinates are roughly where the boat is: opening the chart
reveals her approximate position to that host, whether or not remote viewing is
on, and whether or not she is paired.

To keep the chart fully offline, drop a `basemap.pmtiles` file into the plugin's
`charts` data folder; the chart then loads from it and asks no third party for
anything. The basemap server can also be pointed at your own OpenMapTiles host
in the plugin's advanced settings. The seamark overlay, fonts and sprites are
served from Siparu's own host by default and can be redirected the same way.

## REST API

Mounted at `/plugins/siparu`:

| Endpoint | Description |
|---|---|
| `GET /live` | Current state of all recorded paths + data age |
| `GET /inventory` | Dynamic paths the boat exposes right now, narrowed to the families the dashboard understands, with units metadata |
| `GET /snapshots?bucket=1\|60\|360\|1440&from=&to=&limit=&offset=&order=` | History rows. `bucket=1` serves raw rows (today only); larger buckets read materialized rollups |
| `GET /health` | Recording status, signature diagnosis, per-path freshness, storage usage, rollup state |
| `GET /voyages?limit=` | Auto-detected voyages, newest first |
| `GET /voyages/current` | Currently open voyage, or `null` |
| `GET /voyages/stats` | Today / yesterday / rolling 7 days / season aggregates |
| `GET /voyages/:id/track` | Minute-cadence GPS track of one voyage |
| `GET /ais/targets?max_nm=&max_age_min=&limit=` | Nearby AIS targets, from the vessels the server already tracks |
| `GET /rollups/hourly?from=&to=` | Raw hourly rollup lines the dashboard derives its history series from |
| `GET /map-config` | Resolved chart asset URLs, so the dashboard loads local charts or the remote tile server without guessing |
| `GET /config/fuel-paths` | Which engine fuel-rate paths feed the per-voyage fuel figure, and the paths available to choose from |
| `GET /voyages/edits` | Which voyages were joined by hand, and so can be separated again |

The reading surface above is GET-only. Three flows move the plugin's own state and
never touch the vessel's: pairing, the fuel-source picker, and correcting a voyage
the detector split or joined in the wrong place. CI proves the point on every
commit, names each write route, and an eighth one fails the build.

| Endpoint | Description |
|---|---|
| `GET /pair/status` | Current pairing state |
| `POST /pair/start` | Ask the relay for a code to show at the helm |
| `POST /pair/approve` · `POST /pair/deny` | Answer a claim - the tap at the helm |
| `POST /pair/reset` | Unpair |
| `POST /config/fuel-paths` | Choose which engine fuel-rate paths feed the per-voyage fuel figure |
| `POST /voyages/:id/merge-previous` | Join this passage to the one before it, when one trip was recorded as two |
| `POST /voyages/:id/undo-merge` | Separate a passage back into what it was made of |

Those seven, and `GET /pair/status` with them, answer only requests that came from the
boat's own screen. A browser marks every request with its origin, and one from a page on
another site gets 403: on a server with security off, which is the default, an advert
frame in any tab on the boat's network could otherwise unpair her or lift the pairing
code off the helm. A caller with no browser headers, curl or a script on her own network,
is not affected. Neither is the reading surface above.

The two voyage edits are reachable from the boat's own network only. What the
shore can ask her is a closed set of ten questions, all of them reads
(`history`, `snapshots`, `voyages`, `track`, `phases`, `rollups`, `stats`,
`fuel`, `ais`, `health`); nothing on that socket changes anything aboard, and
the REST surface above is not proxied to it.

### The uplink, when she is paired

She opens a WebSocket out to the relay and sends the live frame described above
every two seconds under way, once a minute at rest; if that socket cannot hold -
marina networks mangle WebSockets - she falls back to an HTTPS call once a
minute that carries her clock and nothing else. There is no key exchange behind
that call, so it could not encrypt a frame even if it were handed one: it says
she is still there, not where she is. Either way the shore keeps none of it:
when she drops off, all that remains ashore is her name and when she was last
seen. Both are outbound: she dials the relay, the relay never dials her.

Five kinds of message travel the other way, and every one of them is a read of
the store she wrote herself:

| Inbound | Description |
|---|---|
| `{ type: 'history', id, path, query }` | One gauge's recorded series, shaped for a graph. Answered from the same NDJSON the local `GET /snapshots` serves. |
| `{ type: 'snapshots', id, query }` | Whole snapshot rows over a window: the logbook read, as the local `GET /snapshots` gives it. |
| `{ type: 'voyages', id, limit }` | Her recent voyages, newest first. She clamps the count, so a request cannot ask for more than she will give. |
| `{ type: 'track', id, voyageId }` | One voyage's recorded path, decimated aboard before it goes over the wire. |
| `{ type: 'phases', id, limit }` | The activity band beneath the voyages, newest first, clamped the same way. |

Anything else the shore sends is ignored, because a boat takes no command and so
there is nothing else to hear.

She reports encrypted or she does not report. Until the account has named a
device to seal to, nothing goes ashore at all: she keeps recording her own
history, and her own screen says why nothing is leaving. There is no fallback
that sends a position in the clear, because a boat whose privacy depends on the
state of a list held elsewhere does not have any.

Once a device is named, the report is encrypted to it and the relay carries a
block it cannot read. Two things stay legible beside it, and they are worth
stating plainly because they are what a carrier can see: her identifier and
the time she sent the frame, so it can be routed at all. Both are inside her
signature, so neither can be rewritten in transit.

Voyage detection opens after sustained movement, closes after sustained
stillness, and folds short docking manoeuvres into the preceding voyage. Its
behavior is pinned by a golden-fixture test against a reference implementation
on ten days of a procedurally generated track (`plugin/test/fixtures/`, laid
down from a seeded PRNG; no vessel's real movements are involved).

All timestamps are epoch milliseconds (UTC). Values use Signal K's SI units
(m/s, radians, Kelvin, Pascal).

## Development

```
npm install
npm run build   # compile plugin TypeScript to plugin/dist
npm test        # unit tests (vitest)
```

## License

Apache-2.0