signalk-siparu 0.1.39 → 0.1.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signalk-siparu",
-  "version": "0.1.39",
+  "version": "0.1.41",
   "description": "Kept aboard, proven ashore. An impartial, timestamped record of every voyage: position, wind, depth and logbook, written on the boat and readable from anywhere. A read-only Signal K plugin with a built-in dashboard.",
   "keywords": [
     "signalk-node-server-plugin",

package/plugin/dist/alarms.d.ts

@@ -29,12 +29,37 @@ export declare const MAX_ACTIVE_ALARMS = 64;
 export declare const MAX_NOTE_MESSAGE = 160;
 /** The prefix that makes a path a notification rather than a gauge. */
 export declare const NOTIFICATIONS_PREFIX = "notifications.";
+/**
+ * How many distinct notification paths are remembered for the sake of offering them.
+ *
+ * The same misbehaving bus member that could flood {@link MAX_ACTIVE_ALARMS} can invent paths
+ * that clear immediately, and those would grow this set without ever standing. A screen
+ * offering a list to choose from stops being usable long before this, so the ceiling costs an
+ * honest boat nothing.
+ */
+export declare const MAX_KNOWN_PATHS = 256;
+/**
+ * Whether one standing condition is allowed to raise the flag.
+ *
+ * Supplied by the rule store; the default here is what a boat with no rules does, which is
+ * ring for everything. Passing nothing must therefore mean the loud answer: this file is
+ * about being heard, and a silence chosen by nobody is the one outcome not worth risking.
+ */
+export type Audible = (path: string, state: Exclude<AlertLevel, 'normal'>) => boolean;
 export declare class AlarmWatch {
     private readonly debug;
     /** Path to condition, for the ones standing right now. Normal is absence, not an entry. */
     private readonly standing;
     /** States that arrived in no vocabulary we know, so a boat reporting one can be diagnosed. */
     private readonly unknown;
+    /**
+     * Every notification path seen since start, standing or since cleared.
+     *
+     * Kept because a screen that offers the owner conditions to mute cannot offer him what is
+     * standing at that moment: a bilge alarm that comes and goes is exactly the one he wants to
+     * silence, and it is rarely raised while he is looking for it.
+     */
+    private readonly seen;
     constructor(debug?: (msg: string) => void);
     /**
      * Take one path/value pair from the delta stream.
@@ -43,8 +68,20 @@ export declare class AlarmWatch {
      * notice of notifications only.
      */
     ingest(path: string, value: unknown, now?: number): void;
-    /** The loudest condition standing, which is what travels beside the sealed body. */
-    level(): AlertLevel;
+    /**
+     * The loudest condition standing that the owner asked to hear about, which is what travels
+     * beside the sealed body.
+     *
+     * The filter belongs here rather than on the list: a muted condition stays in the body and
+     * on the screen of anybody who opens the app, and only this word is withheld. That is the
+     * whole difference between not being woken and being kept in the dark.
+     *
+     * What withholding the word buys is that the carrier cannot read which condition was muted
+     * and cannot decide that it was not. It does not hide that a condition is standing - an
+     * unpadded body grows by the length of one, and sizes are measurable. See the wiring in
+     * index.ts, where that limit is written down rather than assumed away.
+     */
+    level(audible?: Audible): AlertLevel;
     /**
      * What is actually wrong, for the sealed body.
      *
@@ -57,6 +94,13 @@ export declare class AlarmWatch {
     active(): number;
     /** States seen that are in no vocabulary we know, in the order they first arrived. */
     unknownStates(): string[];
+    /**
+     * Every notification path this boat has raised since start, in the order first seen.
+     *
+     * What a screen offers the owner to choose from. Sent only inside a sealed answer: the list
+     * of notifications a vessel is wired for says a good deal about what is aboard her.
+     */
+    knownPaths(): string[];
     /**
      * The one line a notification can show, or nothing when she is quiet.
      *
@@ -68,6 +112,6 @@ export declare class AlarmWatch {
      * on a path with a hard size limit, and a gateway is free to put a paragraph in a
      * notification.
      */
-    note(): AlertNote | undefined;
+    note(audible?: Audible): AlertNote | undefined;
     private quietest;
 }

package/plugin/dist/alarms.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AlarmWatch = exports.NOTIFICATIONS_PREFIX = exports.MAX_NOTE_MESSAGE = exports.MAX_ACTIVE_ALARMS = void 0;
+exports.AlarmWatch = exports.MAX_KNOWN_PATHS = exports.NOTIFICATIONS_PREFIX = exports.MAX_NOTE_MESSAGE = exports.MAX_ACTIVE_ALARMS = void 0;
 /**
  * The ceiling on simultaneously standing conditions.
  *
@@ -30,12 +30,30 @@ const LEVEL_OF = {
 const RANK = { normal: 0, warning: 1, alarm: 2 };
 /** The prefix that makes a path a notification rather than a gauge. */
 exports.NOTIFICATIONS_PREFIX = 'notifications.';
+/**
+ * How many distinct notification paths are remembered for the sake of offering them.
+ *
+ * The same misbehaving bus member that could flood {@link MAX_ACTIVE_ALARMS} can invent paths
+ * that clear immediately, and those would grow this set without ever standing. A screen
+ * offering a list to choose from stops being usable long before this, so the ceiling costs an
+ * honest boat nothing.
+ */
+exports.MAX_KNOWN_PATHS = 256;
+const ALWAYS = () => true;
 class AlarmWatch {
     debug;
     /** Path to condition, for the ones standing right now. Normal is absence, not an entry. */
     standing = new Map();
     /** States that arrived in no vocabulary we know, so a boat reporting one can be diagnosed. */
     unknown = new Set();
+    /**
+     * Every notification path seen since start, standing or since cleared.
+     *
+     * Kept because a screen that offers the owner conditions to mute cannot offer him what is
+     * standing at that moment: a bilge alarm that comes and goes is exactly the one he wants to
+     * silence, and it is rarely raised while he is looking for it.
+     */
+    seen = new Set();
     constructor(debug = () => { }) {
         this.debug = debug;
     }
@@ -71,6 +89,12 @@ class AlarmWatch {
             }
             return;
         }
+        // Remembered from here rather than at the top of the function: this is the point at which
+        // what arrived is known to be a real Signal K notification and not any object that happened
+        // to be published under the tree. Quiet ones are remembered too, because a path standing at
+        // normal is still one its owner may want silenced before it next goes off.
+        if (this.seen.size < exports.MAX_KNOWN_PATHS)
+            this.seen.add(path);
         if (level === 'normal') {
             this.standing.delete(path);
             return;
@@ -97,10 +121,24 @@ class AlarmWatch {
         const since = before !== undefined && before.state === level ? before.since : now;
         this.standing.set(path, { state: level, message, since });
     }
-    /** The loudest condition standing, which is what travels beside the sealed body. */
-    level() {
+    /**
+     * The loudest condition standing that the owner asked to hear about, which is what travels
+     * beside the sealed body.
+     *
+     * The filter belongs here rather than on the list: a muted condition stays in the body and
+     * on the screen of anybody who opens the app, and only this word is withheld. That is the
+     * whole difference between not being woken and being kept in the dark.
+     *
+     * What withholding the word buys is that the carrier cannot read which condition was muted
+     * and cannot decide that it was not. It does not hide that a condition is standing - an
+     * unpadded body grows by the length of one, and sizes are measurable. See the wiring in
+     * index.ts, where that limit is written down rather than assumed away.
+     */
+    level(audible = ALWAYS) {
         let loudest = 'normal';
-        for (const held of this.standing.values()) {
+        for (const [path, held] of this.standing) {
+            if (!audible(path, held.state))
+                continue;
             if (RANK[held.state] > RANK[loudest])
                 loudest = held.state;
         }
@@ -126,6 +164,15 @@ class AlarmWatch {
     unknownStates() {
         return [...this.unknown];
     }
+    /**
+     * Every notification path this boat has raised since start, in the order first seen.
+     *
+     * What a screen offers the owner to choose from. Sent only inside a sealed answer: the list
+     * of notifications a vessel is wired for says a good deal about what is aboard her.
+     */
+    knownPaths() {
+        return [...this.seen];
+    }
     /**
      * The one line a notification can show, or nothing when she is quiet.
      *
@@ -137,8 +184,11 @@ class AlarmWatch {
      * on a path with a hard size limit, and a gateway is free to put a paragraph in a
      * notification.
      */
-    note() {
-        const first = this.conditions()[0];
+    note(audible = ALWAYS) {
+        // Filtered by the same rule as the flag, and it has to be: the note is the sentence on the
+        // lock screen of the bell the flag rang. Taking it from the whole list would put a muted
+        // condition's words on a phone that rang for a different one.
+        const first = this.conditions().find((c) => audible(c.path, c.state));
         if (first === undefined)
             return undefined;
         return {

package/plugin/dist/alertrules.d.ts

@@ -0,0 +1,177 @@
+import type { AlertLevel, AlertRing, AlertRule } from './contract';
+export declare const RULES_VERSION = 1;
+/**
+ * The most rules one boat will hold.
+ *
+ * A vessel raising more distinct notification paths than this is not a vessel whose owner is
+ * curating them one by one, and the list is written to a flash card that has other work to do.
+ * Well past the tank, engine and generator notifications a real boat carries.
+ */
+export declare const MAX_ALERT_RULES = 128;
+/** The longest notification path a rule may name. Signal K's own are far shorter. */
+export declare const MAX_RULE_PATH = 256;
+/**
+ * How far ahead of the boat's own clock a list may be stamped.
+ *
+ * A phone and a boat disagree by seconds, not minutes, and the window exists so a device with
+ * a badly set clock cannot stamp a list in the next century and lock its owner out of every
+ * edit after it.
+ */
+export declare const MAX_CLOCK_SKEW_MS: number;
+/**
+ * What a boat with no rules does, and therefore what she does about a path nobody has named:
+ * everything rings. A default of anything else would mean a feature nobody switched on could
+ * silence an alarm, which is the one mistake this file must not make.
+ */
+export declare const DEFAULT_RING: AlertRing;
+/**
+ * A rule list as it arrives, parsed only as far as the proof needs it.
+ *
+ * Deliberately not validated here beyond "these are the right kinds of thing". The proof is
+ * computed over raw fields, so whether `ring_from` is a word this build knows is a question
+ * for after the sender has been established - a device sending a list this build cannot use
+ * deserves an answer saying so, and a stranger deserves nothing at all.
+ */
+export interface ParsedRuleWrite {
+    v: number;
+    id: string;
+    kid: string;
+    ts: number;
+    rules: {
+        path: string;
+        ring_from: string;
+    }[];
+    proof: string;
+}
+/**
+ * The exact bytes both implementations compute the proof over.
+ *
+ * Built from raw fields with explicit lengths rather than from re-serialised JSON, exactly as
+ * the frame signing input is, and for the same reason: the two implementations that have to
+ * agree on these bytes are written in different languages, and any disagreement between their
+ * JSON encoders about key order or spacing would refuse every write in the fleet at once.
+ *
+ * The rules are covered in the order they were sent rather than sorted, so a carrier that
+ * reordered them fails the check. That order is also the order the boat stores them in, so
+ * nothing has to be re-derived to verify the same list twice.
+ */
+export declare function proofInput(req: {
+    v: number;
+    boat: string;
+    kid: string;
+    id: string;
+    ts: number;
+    rules: readonly {
+        path: string;
+        ring_from: string;
+    }[];
+}): Buffer;
+/**
+ * Make the proof for one rule list. The device's side of the same agreement.
+ *
+ * Kept beside the check for the same reason `sealRequest` is kept beside `openRequest`: this
+ * file is where the format lives, and both ends have to agree on it byte for byte. The
+ * shipping client is the phone, in another language, held to the same committed vectors.
+ */
+export declare function makeRuleProof(opts: {
+    req: Omit<ParsedRuleWrite, 'proof'>;
+    boat: string;
+    /** The device's raw 32-byte X25519 private half, and the public one it implies. */
+    devicePriv: Buffer;
+    devicePub: Buffer;
+    /** The boat's raw 32-byte X25519 inbox public key. */
+    inboxPub: Buffer;
+}): string;
+/**
+ * Whether this write was made by the device it claims to be from.
+ *
+ * Returns false rather than throwing on anything malformed. This runs on whatever arrives over
+ * a socket, and "this is not a write from a device I know" is an answer rather than a fault:
+ * the two are the same thing to the caller, and only one of them is safe inside a live link.
+ */
+export declare function verifyRuleProof(opts: {
+    req: ParsedRuleWrite;
+    boat: string;
+    /** The boat's raw 32-byte X25519 inbox private half, and the public one it implies. */
+    inboxPriv: Buffer;
+    inboxPub: Buffer;
+    /** The raw 32-byte X25519 public key of the device named by `req.kid`. */
+    devicePub: Buffer;
+}): boolean;
+/**
+ * A rule write off the wire, parsed no further than the proof needs.
+ *
+ * Anything that is not shaped like one at all yields nothing, and the caller drops it in
+ * silence, exactly as it drops every other message that is not its own request.
+ */
+export declare function parseRuleWrite(msg: unknown): ParsedRuleWrite | undefined;
+/** Why a list this boat could not use was refused. Only ever told to a proven device. */
+export type RuleRefusal = {
+    code: 'UNSUPPORTED_VERSION';
+    message: string;
+} | {
+    code: 'BAD_RULES';
+    message: string;
+} | {
+    code: 'STALE';
+    message: string;
+} | {
+    code: 'WRITE_FAILED';
+    message: string;
+};
+/**
+ * The rules this boat is going by, and the file they survive a restart in.
+ *
+ * Held in the plugin's data directory rather than in its options, for the same reason the
+ * keys are: Signal K serves plugin options wholesale over GET /plugins/<id>/config, and with
+ * security off - the default install - that answers anyone on the boat's network. A list of
+ * what an owner has chosen not to be told about is not something to hand out on a marina wifi.
+ */
+export declare class AlertRuleStore {
+    private readonly debug;
+    private readonly file;
+    private byPath;
+    private order;
+    private appliedTs;
+    /** One write at a time. See {@link apply} - this is the replay floor, not tidiness. */
+    private queue;
+    constructor(dataDir: string, debug?: (msg: string) => void);
+    /**
+     * Read the stored list, if there is one.
+     *
+     * A file that cannot be read or understood leaves the boat with no rules, which is the loud
+     * side: every condition rings. The quiet side would have been a boat silently muted by a
+     * corrupt file, and nobody would notice until the night it mattered.
+     */
+    load(): void;
+    /** The list in force, in the order it was written. */
+    rules(): AlertRule[];
+    /** Epoch ms of the list in force. Zero on a boat that has never been given one. */
+    ts(): number;
+    /**
+     * Whether one standing condition is allowed to raise the flag.
+     *
+     * A path nobody has named rings, and so does a boat with no list at all: the flag is what
+     * reaches a pocket, and a silence chosen by nobody is the one outcome worth protecting
+     * against.
+     */
+    rings(conditionPath: string, state: Exclude<AlertLevel, 'normal'>): boolean;
+    /**
+     * Take a list from a device whose proof has already been checked.
+     *
+     * Runs one at a time, and the queue is not housekeeping - it is what makes the replay floor
+     * mean anything. The floor is a check against `appliedTs` followed by a disk write, and a
+     * disk write yields. Two writes arriving together would both read the floor before either
+     * raised it, both pass, and land in whatever order the filesystem finished them: a carrier
+     * holding an old sealed write only has to deliver it alongside a new one to have the old
+     * list win AND drag `appliedTs` backwards, which reopens every write it captured since.
+     * Serialising here is the whole of the fix; nothing below may assume it runs alone.
+     */
+    apply(req: ParsedRuleWrite, now: number): Promise<RuleRefusal | undefined>;
+    private applyAlone;
+    /** Wait for a queued write to land, so a stop does not return with a rename in flight. */
+    flush(): Promise<void>;
+    private adopt;
+    /** Callers reach this through the queue above, so it needs no chain of its own. */
+    private persist;
+}