homebridge-nas-power 0.1.0

package/README.md

@@ -0,0 +1,279 @@
+# homebridge-nas-power
+
+Homebridge plugin to expose your NAS as a switch in Apple HomeKit.
+
+- **ON** → Sends Wake-on-LAN magic packets, then retries SSH port check until the NAS responds
+- **OFF** → Connects via SSH and runs a shutdown command
+- **State** → Detected by polling SSH port connectivity (TOFU host key verification)
+
+Tested against OpenMediaVault (OMV). Should work with any Linux NAS that has SSH enabled.
+
+## Maintenance Status
+
+This project is **unmaintained**. The original author has no plans to actively maintain or update it. You are welcome to fork this repository and continue development at your leisure.
+
+---
+
+## Requirements
+
+- Homebridge ≥ 1.6.0
+- Node.js ≥ 18
+- SSH enabled on your NAS
+- The SSH user must have permission to run the shutdown command (see below)
+- WOL enabled in your NAS BIOS/UEFI and network switch (only required for power-on)
+
+---
+
+## Installation
+
+```bash
+npm install -g homebridge-nas-power
+```
+
+Or install via the Homebridge UI by searching `homebridge-nas-power`.
+
+---
+
+## OMV SSH Sudo Setup
+
+The plugin runs `sudo shutdown -h now` over SSH by default. On OMV, allow this without a password prompt:
+
+1. Verify the path to `shutdown` on your system:
+
+```bash
+which shutdown
+```
+
+2. Run `visudo` and add (substituting the correct path if different):
+
+```
+yourusername ALL=(ALL) NOPASSWD: /sbin/shutdown, /usr/sbin/shutdown
+```
+
+> **Note:** On modern systemd-based systems, `sudo systemctl poweroff` is often more reliable. Set this via the `shutdownCommand` config option.
+
+---
+
+## SSH Authentication
+
+One of `password` or `privateKeyPath` is required. Private key auth is strongly recommended.
+
+### Password auth
+
+Set `username` and `password` in your device config.
+
+### Private key auth (recommended)
+
+1. Generate a key pair on your Homebridge host:
+
+```bash
+ssh-keygen -t ed25519 -f ~/.homebridge/nas_key -C "homebridge-nas-power"
+```
+
+2. Copy the public key to your NAS:
+
+```bash
+ssh-copy-id -i ~/.homebridge/nas_key.pub yourusername@192.168.1.100
+```
+
+3. Set `privateKeyPath` in your device config.
+
+> **Note:** The private key is cached in memory at startup. If you rotate the key file on disk while Homebridge is running, the plugin will continue using the old key until Homebridge is restarted.
+
+---
+
+## Security: Shutdown Command
+
+The `shutdownCommand` config value is executed directly on the NAS over SSH without sanitization. **Only use trusted values here.** Do not expose your Homebridge `config.json` to untrusted users.
+
+---
+
+## Homebridge config.json
+
+### Password authentication example
+
+```json
+{
+  "platforms": [
+    {
+      "platform": "NasPower",
+      "name": "NAS Power",
+      "devices": [
+        {
+          "name": "NAS",
+          "host": "192.168.1.100",
+          "mac": "AA:BB:CC:DD:EE:FF",
+          "port": 22,
+          "username": "admin",
+          "password": "yourpassword",
+          "shutdownCommand": "sudo shutdown -h now",
+          "pollInterval": 30
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Private key authentication example (recommended)
+
+```json
+{
+  "platforms": [
+    {
+      "platform": "NasPower",
+      "name": "NAS Power",
+      "devices": [
+        {
+          "name": "NAS",
+          "host": "192.168.1.100",
+          "mac": "AA:BB:CC:DD:EE:FF",
+          "port": 22,
+          "username": "admin",
+          "privateKeyPath": "/home/homebridge/.homebridge/nas_key",
+          "shutdownCommand": "sudo shutdown -h now",
+          "pollInterval": 30
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Config options
+
+| Field | Required | Default | Description |
+|---|---|---|---|
+| `name` | Yes | — | Display name in HomeKit |
+| `host` | Yes | — | NAS IP address or hostname |
+| `mac` | No | — | MAC address for WOL. If omitted, power-on is unavailable |
+| `port` | No | `22` | SSH port |
+| `username` | Yes | — | SSH username |
+| `password` | Conditional | — | SSH password. Required if `privateKeyPath` not set |
+| `privateKeyPath` | Conditional | — | Path to SSH private key. Required if `password` not set |
+| `passphrase` | No | — | Passphrase for an encrypted private key. Only meaningful when `privateKeyPath` is set |
+| `shutdownCommand` | No | `sudo shutdown -h now` | Command to run over SSH to shut down the NAS |
+| `pollInterval` | No | `30` | Seconds between state polls (min 5) |
+| `wolVerifyDelay` | No | `10` | Duration in seconds of the boot verification window after WOL. The plugin retries every 5s within this window — increase for slow-booting hardware |
+| `shutdownCooldownDelay` | No | `30` | Seconds to suppress polling after a shutdown command to prevent the switch flickering back to ON. Cancelled immediately if the user toggles the switch again |
+| `execTimeout` | No | `30` | Seconds to wait for the SSH shutdown command before timing out. Increase for slow-shutting hardware |
+| `wolBroadcastAddress` | No | `255.255.255.255` | WOL broadcast address. Change for VLAN setups. IPv4 only — WOL does not support IPv6 |
+| `uuidOverride` | No | — | Advanced: manually specify the UUID seed string for this device. Use when you need a stable UUID that is independent of MAC address or name/host — for example, to rename a device without losing HomeKit history |
+| `knownHostsPath` | No | `$HOMEBRIDGE_USER_STORAGE_PATH/nas-power-known-hosts` | Path for SSH fingerprint storage. The directory is created automatically if it does not exist |
+| `manufacturer` | No | `OpenMediaVault` | Shown in HomeKit accessory info |
+| `model` | No | `NAS` | Shown in HomeKit accessory info |
+| `firmwareRevision` | No | — | Shown in HomeKit accessory info |
+| `hardwareRevision` | No | — | Shown in HomeKit accessory info |
+
+> **UUID stability:** Each device's HomeKit UUID is derived from its MAC address. If no MAC is provided, the UUID falls back to `name + host`. Changing the name or IP without a MAC causes HomeKit to treat it as a new accessory. Providing a MAC is strongly recommended.
+
+---
+
+## SSH Host Key Verification
+
+The plugin uses Trust On First Use (TOFU). On first connection it stores the host's SHA256 fingerprint. All subsequent connections verify against it, protecting against MITM attacks.
+
+**Known-hosts file format:** Each line stores one host entry:
+
+```
+host:port SHA256:base64encodedfingerprint
+```
+
+For example:
+
+```
+192.168.1.100:22 SHA256:AbCdEf1234...
+```
+
+You can pre-populate this file manually for scripted deployments, or delete individual lines to force re-verification of a specific host.
+
+If the fingerprint changes legitimately (e.g. after reinstalling OMV), verify the new key first:
+
+```bash
+ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
+```
+
+Then delete the stored fingerprints and restart Homebridge:
+
+```bash
+rm $HOMEBRIDGE_USER_STORAGE_PATH/nas-power-known-hosts
+sudo systemctl restart homebridge
+```
+
+---
+
+## Understanding State
+
+### What "OFF" means
+
+**"OFF" means SSH port unreachable — not necessarily powered off.** The following all appear identical to the plugin:
+
+- NAS is powered off
+- NAS is booting (SSH not yet started)
+- SSH daemon has crashed
+- Firewall blocking port 22
+- Network unreachable
+
+After 3 consecutive TCP failures the plugin reports OFF regardless of last known state — this handles hard power cuts so the switch doesn't stay stuck ON indefinitely.
+
+> **Note:** State is determined by a raw TCP port check, not a full SSH handshake. A device spoofing your NAS IP on port 22 would cause the plugin to report ON. Host key verification only applies to SSH shutdown commands. This is an acceptable trade-off for home networks.
+
+### Optimistic updates
+
+- The switch updates **immediately** when toggled — HomeKit gets instant feedback.
+- Verification (WOL retry loop or polling) corrects the state if the action fails.
+- When a power-on or shutdown attempt fails, the plugin reverts the switch and logs the reason (e.g. WOL failure, SSH failure).
+- Automations may briefly see the optimistic state before verification completes.
+
+### WOL verification behavior
+
+When power-on is triggered:
+
+1. Sends 3 magic packets with 200ms spacing.
+2. Starts a verification window (`wolVerifyDelay` seconds).
+3. **Polling is blocked immediately** — the plugin sets a guard before sending packets to prevent the poll from flickering the switch to OFF during the send window.
+4. Retries `isAlive()` every 5 seconds until:
+   - NAS responds → switch stays ON
+   - Deadline expires → switch reverts to OFF and polling resumes
+
+This means a NAS that takes 45 seconds to boot will be detected correctly as long as `wolVerifyDelay` is set high enough (default 10s — increase for slow hardware).
+
+### Shutdown behavior
+
+- The shutdown command is sent over SSH.
+- OMV (and most Linux systems) drops the SSH connection mid-shutdown — this is expected and treated as success, not an error.
+- Shutdown success is **not** verified by SSH exit code alone — the plugin relies on subsequent polling to confirm the NAS is offline.
+- Polling is suppressed for `shutdownCooldownDelay` seconds (default 30s) after the command is sent to prevent the switch flickering back to ON while the NAS powers down.
+- If the user toggles the switch during the cooldown window, the cooldown is cancelled immediately and the new action proceeds.
+
+### Polling and backoff
+
+- Polling checks SSH port reachability every `pollInterval` seconds (default 30s).
+- Polling is **suspended** during WOL verification and shutdown cooldown windows.
+- On consecutive failures, polling uses **exponential backoff** (interval × 2ⁿ) up to a maximum of 5 minutes, reducing network load during extended downtime.
+- On the next successful check or user-initiated action, the backoff resets.
+
+### Transition latency
+
+The HomeKit switch updates optimistically (immediately on user action). Actual state changes take time — shutdown may take 30s to several minutes; boot typically 30–120s depending on hardware.
+
+**HomeKit automation note:** Because `handleSet` returns immediately (to prevent the Home app spinner), HomeKit automations may briefly see a false-positive state before verification corrects it. This is a deliberate UX trade-off — the switch feels instantaneous but HomeKit loses direct transactional feedback. The optimistic update is corrected by WOL verification and polling within seconds.
+
+---
+
+## Wake-on-LAN Troubleshooting
+
+- **Wi-Fi:** Many wireless adapters do not support WOL. Homebridge should be on wired ethernet.
+- **Managed switches:** May require WOL to be explicitly enabled per-port.
+- **Energy Efficient Ethernet (EEE):** Can interfere with WOL. Disable in NAS network adapter settings.
+- **VLAN isolation:** Magic packets won't cross VLAN boundaries. Use `wolBroadcastAddress` with a subnet-directed broadcast (e.g. `192.168.1.255`).
+- **Router blocking broadcasts:** Use a directed broadcast address instead of `255.255.255.255`.
+- **Slow-booting hardware:** Increase `wolVerifyDelay` beyond the default 10s. The plugin retries every 5s until the deadline, so a value of 60–120s covers most hardware.
+
+---
+
+## Notes
+
+- The plugin supports multiple NAS devices — add additional entries to the `devices` array.
+- OMV drops the SSH connection during shutdown — the plugin treats this as expected, not an error.
+- WOL uses IPv4 UDP broadcast only. IPv6-only networks are not supported.

package/config.schema.json

@@ -0,0 +1,156 @@
+{
+  "pluginAlias": "NasPower",
+  "pluginType": "platform",
+  "singular": false,
+  "schema": {
+    "type": "object",
+    "required": ["name"],
+    "properties": {
+      "name": {
+        "title": "Platform Name",
+        "type": "string",
+        "default": "NAS Power"
+      },
+      "devices": {
+        "title": "NAS Devices",
+        "type": "array",
+        "items": {
+          "title": "NAS Device",
+          "type": "object",
+          "required": ["name", "host", "username"],
+          "properties": {
+            "name": {
+              "title": "Display Name",
+              "type": "string"
+            },
+            "host": {
+              "title": "IP Address or Hostname",
+              "type": "string",
+              "minLength": 1,
+              "description": "Local IP address (e.g. 192.168.1.100) or hostname of the NAS."
+            },
+            "mac": {
+              "title": "MAC Address (for WOL)",
+              "type": "string",
+              "pattern": "^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$",
+              "description": "MAC address used for Wake-on-LAN. Optional — if omitted, power-on will not be available.",
+              "placeholder": "AA:BB:CC:DD:EE:FF"
+            },
+            "port": {
+              "title": "SSH Port",
+              "type": "integer",
+              "default": 22,
+              "minimum": 1,
+              "maximum": 65535
+            },
+            "username": {
+              "title": "SSH Username",
+              "type": "string"
+            },
+            "password": {
+              "title": "SSH Password",
+              "type": "string",
+              "format": "password",
+              "minLength": 1,
+              "description": "SSH password. Required if privateKeyPath is not set. Both may be supplied; private key takes priority."
+            },
+            "privateKeyPath": {
+              "title": "SSH Private Key Path",
+              "type": "string",
+              "minLength": 1,
+              "description": "Absolute path to an SSH private key file. Recommended over password auth.",
+              "placeholder": "/home/homebridge/.ssh/id_ed25519"
+            },
+            "passphrase": {
+              "title": "Private Key Passphrase",
+              "type": "string",
+              "format": "password",
+              "description": "Passphrase for the private key, if encrypted."
+            },
+            "shutdownCommand": {
+              "title": "Shutdown Command",
+              "type": "string",
+              "default": "sudo shutdown -h now",
+              "description": "Command run over SSH to shut down the NAS. Only use trusted values — it is executed directly on the NAS without sanitization."
+            },
+            "pollInterval": {
+              "title": "Poll Interval (seconds)",
+              "type": "integer",
+              "default": 30,
+              "minimum": 5,
+              "maximum": 86400,
+              "description": "How often to check NAS power state via SSH port check. Min 5s, max 86400s (24h)."
+            },
+            "wolVerifyDelay": {
+              "title": "WOL Verify Delay (seconds)",
+              "type": "integer",
+              "default": 10,
+              "minimum": 1,
+              "maximum": 300,
+              "description": "How long to wait after sending WOL before checking if the NAS has booted. Increase for slow-booting hardware."
+            },
+            "shutdownCooldownDelay": {
+              "title": "Shutdown Cooldown Delay (seconds)",
+              "type": "integer",
+              "default": 15,
+              "minimum": 1,
+              "maximum": 300,
+              "description": "How long to suppress polling after a shutdown command. During this window, rapid power-on will not be detected until the cooldown expires. Default 15s covers most NAS shutdown speeds; increase for slower hardware."
+            },
+            "wolBroadcastAddress": {
+              "title": "WOL Broadcast Address",
+              "type": "string",
+              "default": "255.255.255.255",
+              "pattern": "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$",
+              "description": "Broadcast address for WOL magic packet. Change if your NAS is on a different VLAN or subnet.",
+              "placeholder": "255.255.255.255"
+            },
+            "knownHostsPath": {
+              "title": "Known Hosts File Path",
+              "type": "string",
+              "description": "Path to store verified SSH host fingerprints. Defaults to $HOMEBRIDGE_USER_STORAGE_PATH/nas-power-known-hosts.",
+              "placeholder": "/home/homebridge/.homebridge/nas-power-known-hosts"
+            },
+            "execTimeout": {
+              "title": "SSH Exec Timeout (seconds)",
+              "type": "integer",
+              "default": 30,
+              "minimum": 5,
+              "maximum": 300,
+              "description": "How long to wait for the SSH shutdown command to complete before treating it as a timeout. Increase for slow-shutting NAS hardware."
+            },
+            "uuidOverride": {
+              "title": "UUID Override",
+              "type": "string",
+              "description": "Advanced: manually specify the seed string for this device's HomeKit UUID. Use when two physical devices share the same MAC address and need to coexist in the same config."
+            },
+            "manufacturer": {
+              "title": "Manufacturer",
+              "type": "string",
+              "description": "Shown in HomeKit accessory info. Defaults to 'OpenMediaVault'."
+            },
+            "model": {
+              "title": "Model",
+              "type": "string",
+              "description": "Shown in HomeKit accessory info. Defaults to 'NAS'."
+            },
+            "firmwareRevision": {
+              "title": "Firmware Revision",
+              "type": "string",
+              "description": "Optional firmware version shown in HomeKit accessory info."
+            },
+            "hardwareRevision": {
+              "title": "Hardware Revision",
+              "type": "string",
+              "description": "Optional hardware version shown in HomeKit accessory info."
+            }
+          },
+          "anyOf": [
+            { "required": ["password"] },
+            { "required": ["privateKeyPath"] }
+          ]
+        }
+      }
+    }
+  }
+}

package/dist/accessory.d.ts

@@ -0,0 +1,39 @@
+import { PlatformAccessory, CharacteristicValue } from 'homebridge';
+import { NasPowerPlatform } from './platform';
+import { DeviceConfig } from './types';
+export declare class NasAccessory {
+    private readonly platform;
+    private readonly accessory;
+    private readonly service;
+    private readonly ssh;
+    private readonly name;
+    private readonly mac?;
+    private readonly shutdownCommand;
+    private readonly wolBroadcastAddress;
+    private readonly wolVerifyDelay;
+    private readonly pollInterval;
+    private readonly shutdownCooldownDelay;
+    private pollTimer;
+    private wolVerifyTimer;
+    private activeWolGeneration;
+    private shutdownCooldownTimer;
+    private isPolling;
+    private currentState;
+    private consecutiveFailures;
+    private destroyed;
+    private wolVerifyGeneration;
+    private readonly log;
+    private stateQueue;
+    constructor(platform: NasPowerPlatform, accessory: PlatformAccessory, config: DeviceConfig);
+    private initialise;
+    destroy(): void;
+    handleGet(): Promise<CharacteristicValue>;
+    handleSet(value: CharacteristicValue): Promise<void>;
+    private handleSetInternal;
+    private handleWakeOnLan;
+    private handleShutdown;
+    private poll;
+    private schedulePoll;
+    private revertState;
+}
+//# sourceMappingURL=accessory.d.ts.map

package/dist/accessory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accessory.d.ts","sourceRoot":"","sources":["../src/accessory.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EAEjB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAG9C,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAOvC,qBAAa,YAAY;IA6CrB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS;IA7C5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAa;IAEjC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAS;IAE/C,OAAO,CAAC,SAAS,CAA8C;IAC/D,OAAO,CAAC,cAAc,CAA8C;IAIpE,OAAO,CAAC,mBAAmB,CAAuB;IAClD,OAAO,CAAC,qBAAqB,CAA8C;IAC3E,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,YAAY,CAAwB;IAC5C,OAAO,CAAC,mBAAmB,CAAK;IAChC,OAAO,CAAC,SAAS,CAAS;IAK1B,OAAO,CAAC,mBAAmB,CAAK;IAIhC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAIlB;IAOF,OAAO,CAAC,UAAU,CAAoC;gBAGnC,QAAQ,EAAE,gBAAgB,EAC1B,SAAS,EAAE,iBAAiB,EAC7C,MAAM,EAAE,YAAY;YA2FR,UAAU;IAmBxB,OAAO,IAAI,IAAI;IAUT,SAAS,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAK/C,SAAS,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;YAiBtC,iBAAiB;YA6BjB,eAAe;YA0Ff,cAAc;YAiCd,IAAI;IA8ClB,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,WAAW;CAOpB"}