signalk-edge-link 2.1.0 → 2.2.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Karl-Erik Gustafsson
+Copyright (c) 2024-2026 Karl-Erik Gustafsson
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -173,7 +173,9 @@ For complete setting definitions and ranges, use `docs/configuration-reference.m
 
 Schema and migration helpers:
 
-- `schemas/config.schema.json` (machine-readable config schema)
+- The runtime schema is defined inline as `plugin.schema` in `src/index.ts`
+  and served to the Signal K admin UI. `docs/configuration-reference.md` is
+  the authoritative human-readable reference.
 - `src/scripts/migrate-config.ts` (convert legacy flat config to `connections[]`)
 - `npm run migrate:config -- <input.json> [output.json]`
 
@@ -273,7 +275,6 @@ window.__EDGE_LINK_AUTH__ = {
 - `docs/performance-tuning.md` (deployment tuning recommendations by hardware profile)
 - `samples/` (example JSON configurations for minimal/dev/v2-bonding setups)
 - `grafana/dashboards/edge-link.json` (starter Grafana dashboard)
-- `schemas/config.schema.json` (unified plugin config schema)
 - `src/scripts/migrate-config.ts` (legacy config migration utility)
 - `src/bin/edge-link-cli.ts` (CLI wrapper for migration and instance/bonding management)
 

package/lib/bonding.js

@@ -135,6 +135,7 @@ class BondingManager {
             : "signalk-edge-link";
         this.notificationsEnabled = config.notificationsEnabled === true;
         this.secretKey = config.secretKey || null;
+        this.stretchAsciiKey = !!config.stretchAsciiKey;
         // Link definitions
         this.links = {
             primary: _createLinkState("primary", config.primary),
@@ -247,7 +248,9 @@ class BondingManager {
         if (!this.secretKey) {
             throw new Error("BondingManager: secretKey is required for HMAC authentication");
         }
-        const keyBuffer = (0, crypto_1.normalizeKey)(this.secretKey);
+        const keyBuffer = (0, crypto_1.normalizeKey)(this.secretKey, {
+            stretchAsciiKey: this.stretchAsciiKey
+        });
         return crypto
             .createHmac("sha256", keyBuffer)
             .update(header)

package/lib/connection-config.js

@@ -14,6 +14,7 @@ exports.VALID_CONNECTION_KEYS = [
     "serverType",
     "udpPort",
     "secretKey",
+    "stretchAsciiKey",
     "useMsgpack",
     "usePathDictionary",
     "enableNotifications",
@@ -96,6 +97,9 @@ function validateConnectionConfig(connection, prefix = "") {
     if (conn.usePathDictionary !== undefined && typeof conn.usePathDictionary !== "boolean") {
         return `${p}usePathDictionary must be a boolean`;
     }
+    if (conn.stretchAsciiKey !== undefined && typeof conn.stretchAsciiKey !== "boolean") {
+        return `${p}stretchAsciiKey must be a boolean`;
+    }
     if (conn.enableNotifications !== undefined && typeof conn.enableNotifications !== "boolean") {
         return `${p}enableNotifications must be a boolean`;
     }
@@ -235,6 +239,20 @@ function validateConnectionConfig(connection, prefix = "") {
                 }
             }
         }
+        // Validate that primary and backup links are different
+        const primaryLink = bonding.primary;
+        const backupLink = bonding.backup;
+        if (primaryLink && backupLink) {
+            const sameAddress = primaryLink.address !== undefined &&
+                backupLink.address !== undefined &&
+                primaryLink.address === backupLink.address;
+            const samePort = primaryLink.port !== undefined &&
+                backupLink.port !== undefined &&
+                primaryLink.port === backupLink.port;
+            if (sameAddress && samePort) {
+                return `${p}bonding primary and backup links must use different address:port combinations`;
+            }
+        }
         if (bonding.failover !== undefined) {
             if (!bonding.failover ||
                 typeof bonding.failover !== "object" ||

package/lib/crypto.js

@@ -40,6 +40,7 @@ exports.validateSecretKey = validateSecretKey;
 exports.createControlPacketAuthTag = createControlPacketAuthTag;
 exports.verifyControlPacketAuthTag = verifyControlPacketAuthTag;
 const crypto = __importStar(require("crypto"));
+const crypto_constants_1 = require("./shared/crypto-constants");
 // Use AES-256-GCM for authenticated encryption (encryption + authentication in one)
 const ALGORITHM = "aes-256-gcm";
 exports.IV_LENGTH = 12; // GCM standard IV length
@@ -58,10 +59,10 @@ exports.CONTROL_AUTH_TAG_LENGTH = 16; // Truncated HMAC-SHA256 tag for v3 contro
  *
  * @param passphrase - Human-chosen password of any length
  * @param salt - Application-specific salt (defaults to "signalk-edge-link-v1")
- * @param iterations - PBKDF2 iteration count (defaults to 600_000, NIST SP 800-132)
+ * @param iterations - PBKDF2 iteration count (defaults to `PBKDF2_ITERATIONS`, NIST SP 800-132)
  * @returns 32-byte derived key buffer
  */
-function deriveKeyFromPassphrase(passphrase, salt = "signalk-edge-link-v1", iterations = 600000) {
+function deriveKeyFromPassphrase(passphrase, salt = "signalk-edge-link-v1", iterations = crypto_constants_1.PBKDF2_ITERATIONS) {
     if (!passphrase || typeof passphrase !== "string") {
         throw new Error("Passphrase must be a non-empty string");
     }
@@ -73,19 +74,21 @@ function deriveKeyFromPassphrase(passphrase, salt = "signalk-edge-link-v1", iter
  * Accepts three formats:
  * - 64-character hex string  → decoded to 32 bytes (full 256-bit entropy)
  * - 44-character base64 string → decoded to 32 bytes (full 256-bit entropy)
- * - 32-character ASCII string → used as-is (~208 bits effective entropy)
+ * - 32-character ASCII string → used raw by default, OR stretched via
+ *   PBKDF2-SHA256 (see {@link PBKDF2_ITERATIONS}, salt "signalk-edge-link-v1")
+ *   when `options.stretchAsciiKey` is `true`.  PBKDF2 lifts the ~208-bit
+ *   effective entropy of a human-typeable 32-char key to a full 256-bit AES
+ *   key.
  *
- * **Note on ASCII keys:** A 32-character ASCII string provides approximately
- * 208 bits of effective entropy (~6.5 bits/char). For human-chosen passwords
- * use `deriveKeyFromPassphrase()` instead, which runs PBKDF2 to achieve full
- * 256-bit security. For new deployments prefer randomly generated 64-char hex
- * or 44-char base64 keys which carry full entropy without key derivation.
+ * Both ends of a connection must use the same key string and the same
+ * `stretchAsciiKey` setting for the derived 32-byte buffers to match.
  *
  * @param secretKey - Secret key in any supported format
+ * @param options - Key normalization options (optional)
  * @returns 32-byte key buffer
  * @throws Error if key cannot be normalized to exactly 32 bytes
  */
-function normalizeKey(secretKey) {
+function normalizeKey(secretKey, options = {}) {
     if (!secretKey || typeof secretKey !== "string") {
         throw new Error("Secret key must be a non-empty string");
     }
@@ -105,25 +108,46 @@ function normalizeKey(secretKey) {
         throw new Error(`Base64 key decoded to ${buf.length} bytes; expected 32. ` +
             "Ensure the key is a standard base64 string encoding exactly 32 bytes.");
     }
-    // Fallback: raw ASCII — must be exactly 32 bytes
-    // NOTE: ASCII keys provide ~6.5 bits/char ≈ 208 bits effective entropy.
-    // Prefer hex or base64 keys for full 256-bit strength.
+    // Fallback: raw ASCII — must be exactly 32 bytes.  Default is to use the
+    // bytes as-is for backwards compatibility; callers that set
+    // `stretchAsciiKey: true` get PBKDF2-SHA256 stretching so a human-typed
+    // 32-char key (~6.5 bits/char ≈ 208 bits) reaches the full 256-bit AES
+    // strength.  Both ends must use the same setting.
     if (Buffer.byteLength(secretKey) === 32) {
+        if (options.stretchAsciiKey) {
+            return getOrDeriveAsciiKey(secretKey);
+        }
         return Buffer.from(secretKey);
     }
     throw new Error("Secret key must be exactly 32 bytes: use a 32-character ASCII string, " +
         "64-character hex string, or 44-character base64 string");
 }
+// Per-process PBKDF2 cache.  Without this cache every encryption /
+// decryption call would re-run the full iteration count, which would
+// dominate the per-packet cost.  The cache key is the raw ASCII string so
+// it is effectively bounded by the number of distinct configured keys
+// (typically one or two per Signal K instance).
+const asciiKeyCache = new Map();
+function getOrDeriveAsciiKey(asciiKey) {
+    const cached = asciiKeyCache.get(asciiKey);
+    if (cached) {
+        return cached;
+    }
+    const derived = deriveKeyFromPassphrase(asciiKey);
+    asciiKeyCache.set(asciiKey, derived);
+    return derived;
+}
 /**
  * Encrypts data using AES-256-GCM with binary output
  * Binary format: [IV (12 bytes)][Encrypted Data][Auth Tag (16 bytes)]
  * @param data - Data to encrypt
  * @param secretKey - Secret key (32-char ASCII, 64-char hex, or 44-char base64)
+ * @param options - Key normalization options (e.g. stretchAsciiKey)
  * @returns Binary packet with IV, encrypted data, and auth tag
  * @throws Error if secretKey is invalid or data is empty
  */
-const encryptBinary = (data, secretKey) => {
-    const keyBuffer = normalizeKey(secretKey);
+const encryptBinary = (data, secretKey, options = {}) => {
+    const keyBuffer = normalizeKey(secretKey, options);
     if (!data || (Buffer.isBuffer(data) && data.length === 0)) {
         throw new Error("Data to encrypt cannot be empty");
     }
@@ -142,11 +166,13 @@ exports.encryptBinary = encryptBinary;
  * Decrypts data encrypted with AES-256-GCM
  * @param packet - Binary packet with IV, encrypted data, and auth tag
  * @param secretKey - Secret key (32-char ASCII, 64-char hex, or 44-char base64)
+ * @param options - Key normalization options (e.g. stretchAsciiKey); must
+ *   match what the sender used or authentication will fail
  * @returns Decrypted data as Buffer
  * @throws Error if secretKey or packet is invalid, or authentication fails
  */
-const decryptBinary = (packet, secretKey) => {
-    const keyBuffer = normalizeKey(secretKey);
+const decryptBinary = (packet, secretKey, options = {}) => {
+    const keyBuffer = normalizeKey(secretKey, options);
     if (!Buffer.isBuffer(packet) || packet.length <= exports.IV_LENGTH + exports.AUTH_TAG_LENGTH) {
         throw new Error("Invalid packet size");
     }
@@ -235,13 +261,14 @@ function validateSecretKey(key) {
  * @param headerData - Header bytes 0..12
  * @param payload - Control payload without trailing auth tag
  * @param secretKey - Secret key in any supported format
+ * @param options - Key normalization options (e.g. stretchAsciiKey)
  * @returns Truncated HMAC tag
  */
-function createControlPacketAuthTag(headerData, payload, secretKey) {
+function createControlPacketAuthTag(headerData, payload, secretKey, options = {}) {
     if (!Buffer.isBuffer(headerData)) {
         throw new Error("Control packet header must be a Buffer");
     }
-    const keyBuffer = normalizeKey(secretKey);
+    const keyBuffer = normalizeKey(secretKey, options);
     const payloadBuffer = Buffer.isBuffer(payload) ? payload : Buffer.from(payload || "");
     const hmac = crypto.createHmac("sha256", keyBuffer);
     hmac.update(headerData);
@@ -257,13 +284,15 @@ function createControlPacketAuthTag(headerData, payload, secretKey) {
  * @param payload - Control payload without trailing auth tag
  * @param authTag - Trailing auth tag from the packet
  * @param secretKey - Secret key in any supported format
+ * @param options - Key normalization options (e.g. stretchAsciiKey); must
+ *   match what the sender used or verification will fail
  * @returns True when authentication succeeds
  */
-function verifyControlPacketAuthTag(headerData, payload, authTag, secretKey) {
+function verifyControlPacketAuthTag(headerData, payload, authTag, secretKey, options = {}) {
     if (!Buffer.isBuffer(authTag) || authTag.length !== exports.CONTROL_AUTH_TAG_LENGTH) {
         throw new Error("Control packet authentication tag missing");
     }
-    const expected = createControlPacketAuthTag(headerData, payload, secretKey);
+    const expected = createControlPacketAuthTag(headerData, payload, secretKey, options);
     if (!crypto.timingSafeEqual(expected, authTag)) {
         throw new Error("Control packet authentication failed");
     }