homebridge-openclaw 2.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Davide Vargas P.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,398 @@
+# homebridge-openclaw
+
+**EN** — Homebridge plugin that exposes a simplified REST API so an [OpenClaw](https://docs.openclaw.ai) agent can list and control HomeKit devices.
+
+**ES** — Plugin para Homebridge que expone una API REST simplificada para que un agente de [OpenClaw](https://docs.openclaw.ai) pueda listar y controlar dispositivos HomeKit.
+
+---
+
+- [English](#english)
+- [Español](#español)
+
+---
+
+## English
+
+### Requirements
+
+- **homebridge-config-ui-x** installed (included in the official Docker image).
+- Homebridge started with the **`-I`** (insecure) flag so the UI can read/write characteristics.
+
+### Installation
+
+```bash
+npm install homebridge-openclaw
+```
+
+Or via **Homebridge Config UI X**: Plugins → search “openclaw” → Install.
+
+### Minimum configuration
+
+Add to your Homebridge `config.json` under **`accessories`**:
+
+```json
+{
+  "accessory": "OpenClawAPI",
+  "name": "OpenClaw API"
+}
+```
+
+That’s it. The plugin will:
+
+- Detect the UI credentials automatically (reads `.uix-secrets` and `auth.json` from the filesystem).
+- Generate a unique API token and save it to `.openclaw-token`.
+- Listen on port 8899.
+
+### Advanced configuration
+
+```json
+{
+  "accessory": "OpenClawAPI",
+  "name": "OpenClaw API",
+  "apiPort": 8899,
+  "apiBind": "0.0.0.0",
+  "token": "my-custom-token",
+  "rateLimit": 100,
+  "homebridgeUiUrl": "http://localhost:8581",
+  "homebridgeUiUser": "admin",
+  "homebridgeUiPass": "admin"
+}
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `apiPort` | number | 8899 | REST server port |
+| `apiBind` | string | `0.0.0.0` | Bind address (`127.0.0.1` = local only) |
+| `token` | string | auto | Bearer token for OpenClaw API calls |
+| `rateLimit` | number | 100 | Max requests per minute per IP |
+| `homebridgeUiUrl` | string | `http://localhost:8581` | Config UI X URL (only if not default) |
+| `homebridgeUiUser` | string | auto | UI username (only if auto-detection fails) |
+| `homebridgeUiPass` | string | auto | UI password (only if auto-detection fails) |
+
+### Security
+
+**Internal auth (plugin → Config UI X)**  
+The plugin reads Homebridge internal files (`.uix-secrets` and `auth.json`) to sign valid JWTs. **No username or password is required in `config.json`.**  
+Only if those files are unavailable (e.g. non-Docker setups), `homebridgeUiUser` / `homebridgeUiPass` are used as fallback.
+
+**API token (OpenClaw → plugin)**  
+Resolved in this order:
+
+1. **Environment variable** `OPENCLAW_HB_TOKEN` — ideal for Docker Compose / Kubernetes.
+2. **File** `.openclaw-token` in Homebridge storage — ideal if OpenClaw has filesystem access (same NAS, shared volume).
+3. **`token`** in `config.json` — manual fallback.
+4. **Auto-generated** — if none of the above exist, a unique token is generated (HMAC of Homebridge secretKey), saved to `.openclaw-token`, and printed in the logs.
+
+**Rate limiting**  
+Default: 100 requests per minute per IP. Configurable via `rateLimit`.
+
+### Getting the token for OpenClaw
+
+**Option A: Read the file (recommended)**  
+After first start, the token is in:
+
+```
+/var/lib/homebridge/.openclaw-token
+```
+
+If using Docker with a mounted volume (e.g. `/Volumes/docker/HomeBridge`):
+
+```bash
+cat /Volumes/docker/HomeBridge/.openclaw-token
+```
+
+**Option B: Check the logs**  
+On first start, the token is printed in the Homebridge logs:
+
+```
+[homebridge-openclaw] ────────────────────────────────────────
+[homebridge-openclaw] API Token: abc123...
+[homebridge-openclaw] Configure this token in your OpenClaw agent.
+[homebridge-openclaw] ────────────────────────────────────────
+```
+
+**Option C: Environment variable**  
+In Docker Compose:
+
+```yaml
+environment:
+  - OPENCLAW_HB_TOKEN=my-shared-token
+```
+
+Configure the same value in OpenClaw.
+
+### REST API
+
+Base URL: `http://<homebridge-ip>:8899`
+
+All requests (except `/health`) require:
+
+```
+Authorization: Bearer <token>
+```
+
+| Endpoint | Method | Auth | Description |
+|----------|--------|------|-------------|
+| `/health` | GET | No | Health check |
+| `/api/devices` | GET | Yes | List all devices |
+| `/api/devices/type/<type>` | GET | Yes | List by type (e.g. `switch`, `lightbulb`) |
+| `/api/devices/<id>` | GET | Yes | Device state |
+| `/api/devices/<id>/control` | POST | Yes | Control one device |
+| `/api/devices/control` | POST | Yes | Control multiple devices |
+
+**Health (no auth)**
+
+```
+GET /health
+```
+
+**Control one device**
+
+```
+POST /api/devices/<id>/control
+Content-Type: application/json
+
+{ "action": "on", "value": true }
+```
+
+**Control multiple devices**
+
+```
+POST /api/devices/control
+Content-Type: application/json
+
+{
+  "devices": [
+    { "id": "xxx", "action": "on", "value": true },
+    { "id": "yyy", "action": "on", "value": false }
+  ]
+}
+```
+
+**Supported actions**
+
+| Action | Value | Devices |
+|--------|-------|---------|
+| `on` / `power` | `true` / `false` | switch, lightbulb, outlet, fan |
+| `brightness` / `dim` | 0–100 | lightbulb |
+| `hue` | 0–360 | RGB lightbulb |
+| `saturation` | 0–100 | RGB lightbulb |
+| `color` | `{ "hue": 240, "saturation": 100 }` | RGB lightbulb |
+| `colorTemperature` / `ct` | mired | lightbulb |
+| `targetTemperature` / `temperature` | 10–35 | thermostat |
+| `thermostatMode` / `mode` | `off` / `heat` / `cool` / `auto` | thermostat |
+| `lock` | `true` / `false` | lock |
+| `speed` / `rotationSpeed` | 0–100 | fan |
+| `position` / `targetPosition` | 0–100 | blinds |
+| `tilt` / `targetTilt` | -90 to 90 | blinds |
+| `garageDoor` / `garage` | `true`=open / `false`=close | garage |
+
+### Using from OpenClaw
+
+Example with `exec` and `curl`:
+
+```bash
+# List devices
+exec('curl -s -H "Authorization: Bearer TOKEN" http://HOMEBRIDGE_IP:8899/api/devices')
+
+# Turn on a light
+exec('curl -s -X POST -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" -d \'{"action":"on","value":true}\' http://HOMEBRIDGE_IP:8899/api/devices/DEVICE_ID/control')
+```
+
+### License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+## Español
+
+### Requisitos
+
+- **homebridge-config-ui-x** instalado (viene con la imagen Docker oficial).
+- Homebridge iniciado con la bandera **`-I`** (modo inseguro) para que el UI pueda leer/escribir características.
+
+### Instalación
+
+```bash
+npm install homebridge-openclaw
+```
+
+O desde **Homebridge Config UI X**: Plugins → buscar “openclaw” → Instalar.
+
+### Configuración mínima
+
+Añadir al `config.json` de Homebridge en la sección **`accessories`**:
+
+```json
+{
+  "accessory": "OpenClawAPI",
+  "name": "OpenClaw API"
+}
+```
+
+Con eso basta. El plugin:
+
+- Detecta automáticamente las credenciales del UI (lee `.uix-secrets` y `auth.json` del sistema de archivos).
+- Genera un token API único y lo guarda en `.openclaw-token`.
+- Escucha en el puerto 8899.
+
+### Configuración avanzada
+
+```json
+{
+  "accessory": "OpenClawAPI",
+  "name": "OpenClaw API",
+  "apiPort": 8899,
+  "apiBind": "0.0.0.0",
+  "token": "mi-token-personalizado",
+  "rateLimit": 100,
+  "homebridgeUiUrl": "http://localhost:8581",
+  "homebridgeUiUser": "admin",
+  "homebridgeUiPass": "admin"
+}
+```
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|-------------|-------------|
+| `apiPort` | number | 8899 | Puerto del servidor REST |
+| `apiBind` | string | `0.0.0.0` | Dirección de bind (`127.0.0.1` = solo local) |
+| `token` | string | auto | Token Bearer para autenticar llamadas de OpenClaw |
+| `rateLimit` | number | 100 | Máximo de peticiones por minuto por IP |
+| `homebridgeUiUrl` | string | `http://localhost:8581` | URL del Config UI X (solo si no es la por defecto) |
+| `homebridgeUiUser` | string | auto | Usuario del UI (solo si falla la auto-detección) |
+| `homebridgeUiPass` | string | auto | Contraseña del UI (solo si falla la auto-detección) |
+
+### Seguridad
+
+**Autenticación interna (plugin → Config UI X)**  
+El plugin lee los archivos internos de Homebridge (`.uix-secrets` y `auth.json`) para firmar JWTs válidos. **No necesita usuario ni contraseña en `config.json`.**  
+Solo si esos archivos no están disponibles (p. ej. instalaciones no-Docker), se usan `homebridgeUiUser` / `homebridgeUiPass` como respaldo.
+
+**Token API (OpenClaw → plugin)**  
+Se resuelve en este orden:
+
+1. **Variable de entorno** `OPENCLAW_HB_TOKEN` — ideal para Docker Compose / Kubernetes.
+2. **Archivo** `.openclaw-token` en el directorio de almacenamiento de Homebridge — ideal si OpenClaw tiene acceso al sistema de archivos (mismo NAS, volumen compartido).
+3. **Campo `token`** en `config.json` — respaldo manual.
+4. **Auto-generado** — si no existe ninguna de las anteriores, se genera un token único (HMAC del secretKey de Homebridge), se guarda en `.openclaw-token` y se muestra en los logs.
+
+**Rate limiting**  
+Por defecto: 100 peticiones por minuto por IP. Configurable con `rateLimit`.
+
+### Obtener el token para OpenClaw
+
+**Opción A: Leer el archivo (recomendado)**  
+Tras el primer arranque, el token está en:
+
+```
+/var/lib/homebridge/.openclaw-token
+```
+
+Si usas Docker y el volumen está montado (ej.: `/Volumes/docker/HomeBridge`):
+
+```bash
+cat /Volumes/docker/HomeBridge/.openclaw-token
+```
+
+**Opción B: Ver los logs**  
+En el primer arranque, el token aparece en los logs de Homebridge:
+
+```
+[homebridge-openclaw] ────────────────────────────────────────
+[homebridge-openclaw] API Token: abc123...
+[homebridge-openclaw] Configure this token in your OpenClaw agent.
+[homebridge-openclaw] ────────────────────────────────────────
+```
+
+**Opción C: Variable de entorno**  
+En Docker Compose:
+
+```yaml
+environment:
+  - OPENCLAW_HB_TOKEN=mi-token-compartido
+```
+
+Configurar el mismo valor en OpenClaw.
+
+### API REST
+
+URL base: `http://<ip-homebridge>:8899`
+
+Todas las peticiones (excepto `/health`) requieren:
+
+```
+Authorization: Bearer <token>
+```
+
+| Endpoint | Método | Auth | Descripción |
+|----------|--------|------|-------------|
+| `/health` | GET | No | Comprobación de estado |
+| `/api/devices` | GET | Sí | Listar todos los dispositivos |
+| `/api/devices/type/<tipo>` | GET | Sí | Listar por tipo (ej. `switch`, `lightbulb`) |
+| `/api/devices/<id>` | GET | Sí | Estado de un dispositivo |
+| `/api/devices/<id>/control` | POST | Sí | Controlar un dispositivo |
+| `/api/devices/control` | POST | Sí | Controlar varios dispositivos |
+
+**Health (sin auth)**
+
+```
+GET /health
+```
+
+**Controlar un dispositivo**
+
+```
+POST /api/devices/<id>/control
+Content-Type: application/json
+
+{ "action": "on", "value": true }
+```
+
+**Controlar varios dispositivos**
+
+```
+POST /api/devices/control
+Content-Type: application/json
+
+{
+  "devices": [
+    { "id": "xxx", "action": "on", "value": true },
+    { "id": "yyy", "action": "on", "value": false }
+  ]
+}
+```
+
+**Acciones soportadas**
+
+| Acción | Valor | Dispositivos |
+|--------|-------|--------------|
+| `on` / `power` | `true` / `false` | switch, lightbulb, outlet, fan |
+| `brightness` / `dim` | 0–100 | lightbulb |
+| `hue` | 0–360 | lightbulb RGB |
+| `saturation` | 0–100 | lightbulb RGB |
+| `color` | `{ "hue": 240, "saturation": 100 }` | lightbulb RGB |
+| `colorTemperature` / `ct` | mired | lightbulb |
+| `targetTemperature` / `temperature` | 10–35 | thermostat |
+| `thermostatMode` / `mode` | `off` / `heat` / `cool` / `auto` | thermostat |
+| `lock` | `true` / `false` | lock |
+| `speed` / `rotationSpeed` | 0–100 | fan |
+| `position` / `targetPosition` | 0–100 | blinds |
+| `tilt` / `targetTilt` | -90 a 90 | blinds |
+| `garageDoor` / `garage` | `true`=abrir / `false`=cerrar | garage |
+
+### Uso desde OpenClaw
+
+Ejemplo con `exec` y `curl`:
+
+```bash
+# Listar dispositivos
+exec('curl -s -H "Authorization: Bearer TOKEN" http://IP_HOMEBRIDGE:8899/api/devices')
+
+# Encender una luz
+exec('curl -s -X POST -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" -d \'{"action":"on","value":true}\' http://IP_HOMEBRIDGE:8899/api/devices/DEVICE_ID/control')
+```
+
+### Licencia
+
+MIT — ver [LICENSE](LICENSE).

package/config.schema.json

@@ -0,0 +1,89 @@
+{
+  "pluginAlias": "OpenClawAPI",
+  "pluginType": "accessory",
+  "singular": true,
+  "headerDisplay": "This plugin exposes a REST API so that [OpenClaw](https://docs.openclaw.ai) agents can list and control your HomeKit devices via Homebridge.",
+  "footerDisplay": "For full documentation see the [README](https://github.com/davidevp/homebridge-openclaw#readme).",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "title": "Name",
+        "type": "string",
+        "default": "OpenClaw API",
+        "description": "Display name for this accessory in Homebridge."
+      },
+      "apiPort": {
+        "title": "API Port",
+        "type": "integer",
+        "default": 8899,
+        "minimum": 1024,
+        "maximum": 65535,
+        "description": "Port for the REST API server (1024-65535)."
+      },
+      "apiBind": {
+        "title": "Bind Address",
+        "type": "string",
+        "default": "0.0.0.0",
+        "description": "Network interface to bind to. Use 127.0.0.1 for local-only access.",
+        "oneOf": [
+          { "title": "All interfaces (0.0.0.0)", "enum": ["0.0.0.0"] },
+          { "title": "Local only (127.0.0.1)", "enum": ["127.0.0.1"] }
+        ]
+      },
+      "token": {
+        "title": "API Token",
+        "type": "string",
+        "description": "Bearer token for authenticating OpenClaw requests. Leave empty to auto-generate."
+      },
+      "rateLimit": {
+        "title": "Rate Limit",
+        "type": "integer",
+        "default": 100,
+        "minimum": 1,
+        "maximum": 10000,
+        "description": "Maximum requests per minute per IP address (1-10000)."
+      },
+      "homebridgeUiUrl": {
+        "title": "Config UI X URL",
+        "type": "string",
+        "placeholder": "http://localhost:8581",
+        "description": "URL of Homebridge Config UI X. Only change if running on a non-default port."
+      },
+      "homebridgeUiUser": {
+        "title": "Config UI X Username",
+        "type": "string",
+        "description": "Only required if automatic credential detection fails (non-Docker setups)."
+      },
+      "homebridgeUiPass": {
+        "title": "Config UI X Password",
+        "type": "string",
+        "description": "Only required if automatic credential detection fails (non-Docker setups)."
+      }
+    },
+    "required": ["name"]
+  },
+  "layout": [
+    {
+      "type": "fieldset",
+      "title": "Server",
+      "items": [
+        { "key": "apiPort", "type": "number" },
+        "apiBind",
+        { "key": "rateLimit", "type": "number" }
+      ]
+    },
+    {
+      "type": "fieldset",
+      "title": "Authentication",
+      "description": "The token is auto-generated if left empty. Only fill the UI credentials if auto-detection does not work.",
+      "items": ["token"]
+    },
+    {
+      "type": "fieldset",
+      "title": "Advanced (Config UI X)",
+      "expandable": true,
+      "items": ["homebridgeUiUrl", "homebridgeUiUser", "homebridgeUiPass"]
+    }
+  ]
+}

package/index.js

@@ -0,0 +1,501 @@
+/**
+ * homebridge-openclaw v2.1.0
+ *
+ * Exposes a simplified REST API so that an OpenClaw agent can list and
+ * control HomeKit devices managed by Homebridge.
+ *
+ * Security:
+ *   - Authenticates with Config UI X internally via JWT (no plaintext
+ *     passwords in config.json). Reads .uix-secrets + auth.json directly.
+ *   - API token resolved from: env var → file → config → auto-generated.
+ *   - Rate-limited. Bind address configurable.
+ *
+ * Requirements:
+ *   - homebridge-config-ui-x (comes with the official Docker image)
+ *   - Homebridge started with -I flag (insecure mode)
+ */
+
+'use strict';
+
+const { readFileSync, writeFileSync, existsSync } = require('fs');
+const { createHmac } = require('crypto');
+const { resolve } = require('path');
+const express = require('express');
+const jwt = require('jsonwebtoken');
+const rateLimit = require('express-rate-limit');
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+const PLUGIN_NAME = 'homebridge-openclaw';
+const ACCESSORY_NAME = 'OpenClawAPI';
+const VERSION = '2.1.0';
+const DEFAULT_PORT = 8899;
+const DEFAULT_BIND = '0.0.0.0';
+const DEFAULT_RATE_LIMIT = 100; // requests per minute
+const DEFAULT_UI_URL = 'http://localhost:8581';
+const TOKEN_FILE_NAME = '.openclaw-token';
+const TOKEN_ENV_VAR = 'OPENCLAW_HB_TOKEN';
+
+// ─── Helpers: storage path detection ────────────────────────────────────────
+
+function detectStoragePath() {
+  if (process.env.UIX_STORAGE_PATH) return process.env.UIX_STORAGE_PATH;
+  const candidates = [
+    '/var/lib/homebridge',
+    resolve(require('os').homedir(), '.homebridge'),
+  ];
+  for (const p of candidates) {
+    if (existsSync(resolve(p, '.uix-secrets'))) return p;
+  }
+  return candidates[0];
+}
+
+// ─── Helpers: API token resolution (4 layers) ───────────────────────────────
+
+function resolveApiToken(config, storagePath, log) {
+  // Layer 1: environment variable
+  if (process.env[TOKEN_ENV_VAR]) {
+    log.info(`[${PLUGIN_NAME}] API token loaded from environment variable ${TOKEN_ENV_VAR}.`);
+    return { token: process.env[TOKEN_ENV_VAR], source: 'env' };
+  }
+
+  // Layer 2: token file
+  const tokenFilePath = resolve(storagePath, TOKEN_FILE_NAME);
+  if (existsSync(tokenFilePath)) {
+    try {
+      const fileToken = readFileSync(tokenFilePath, 'utf8').trim();
+      if (fileToken.length >= 16) {
+        log.info(`[${PLUGIN_NAME}] API token loaded from ${tokenFilePath}.`);
+        return { token: fileToken, source: 'file' };
+      }
+    } catch (_) { /* fall through */ }
+  }
+
+  // Layer 3: config.json field
+  if (config.token && config.token.length >= 8) {
+    log.info(`[${PLUGIN_NAME}] API token loaded from config.json.`);
+    return { token: config.token, source: 'config' };
+  }
+
+  // Layer 4: auto-generate from secretKey
+  let secretKey = 'openclaw-default-seed';
+  try {
+    const secrets = JSON.parse(readFileSync(resolve(storagePath, '.uix-secrets'), 'utf8'));
+    if (secrets.secretKey) secretKey = secrets.secretKey;
+  } catch (_) { /* use default seed */ }
+
+  const generated = createHmac('sha256', secretKey).update('openclaw-hb-api-token').digest('hex').slice(0, 48);
+
+  // Persist to file so OpenClaw can read it
+  try {
+    writeFileSync(tokenFilePath, generated + '\n', { mode: 0o600 });
+    log.info(`[${PLUGIN_NAME}] API token auto-generated and saved to ${tokenFilePath}.`);
+  } catch (err) {
+    log.warn(`[${PLUGIN_NAME}] Could not write token file: ${err.message}. Token only in logs.`);
+  }
+
+  log.info(`[${PLUGIN_NAME}] ────────────────────────────────────────`);
+  log.info(`[${PLUGIN_NAME}] API Token: ${generated}`);
+  log.info(`[${PLUGIN_NAME}] Configure this token in your OpenClaw agent.`);
+  log.info(`[${PLUGIN_NAME}] ────────────────────────────────────────`);
+
+  return { token: generated, source: 'auto' };
+}
+
+// ─── UiClient: talks to Config UI X API ─────────────────────────────────────
+
+class UiClient {
+  constructor({ storagePath, uiUrl, uiUser, uiPass, log }) {
+    this.storagePath = storagePath;
+    this.baseUrl = (uiUrl || DEFAULT_UI_URL).replace(/\/+$/, '');
+    this.uiUser = uiUser || null;
+    this.uiPass = uiPass || null;
+    this.log = log;
+    this.jwt = null;
+    this.jwtExpires = 0;
+    this.secretKey = null;
+    this.adminUser = null;
+    this.instanceId = null;
+    this.authMode = 'none'; // 'jwt-direct' | 'login' | 'none'
+
+    this._detectAuthMode();
+  }
+
+  /** Detect the best auth strategy available. */
+  _detectAuthMode() {
+    // Try reading .uix-secrets
+    try {
+      const secretsPath = resolve(this.storagePath, '.uix-secrets');
+      const secrets = JSON.parse(readFileSync(secretsPath, 'utf8'));
+      if (secrets.secretKey) {
+        this.secretKey = secrets.secretKey;
+        this.instanceId = require('crypto').createHash('sha256').update(secrets.secretKey).digest('hex');
+      }
+    } catch (_) { /* not available */ }
+
+    // Try reading auth.json for admin username
+    try {
+      const authPath = resolve(this.storagePath, 'auth.json');
+      const users = JSON.parse(readFileSync(authPath, 'utf8'));
+      const admin = Array.isArray(users) ? users.find(u => u.admin) : null;
+      if (admin) this.adminUser = admin.username;
+    } catch (_) { /* not available */ }
+
+    if (this.secretKey && this.adminUser) {
+      this.authMode = 'jwt-direct';
+      this.log.info(`[${PLUGIN_NAME}] Auth mode: JWT direct (no password needed).`);
+    } else if (this.uiUser && this.uiPass) {
+      this.authMode = 'login';
+      this.log.info(`[${PLUGIN_NAME}] Auth mode: login (credentials from config).`);
+    } else {
+      this.log.error(`[${PLUGIN_NAME}] Auth mode: none — cannot authenticate with Config UI X!`);
+      this.log.error(`[${PLUGIN_NAME}] Ensure .uix-secrets exists or provide homebridgeUiUser/homebridgeUiPass.`);
+    }
+  }
+
+  /** Sign a JWT using the same format Config UI X expects. */
+  _signJwt() {
+    const payload = {
+      username: this.adminUser,
+      name: this.adminUser,
+      admin: true,
+      instanceId: this.instanceId,
+    };
+    return jwt.sign(payload, this.secretKey, { expiresIn: '8h' });
+  }
+
+  /** Get a valid token (refresh if needed). */
+  async token() {
+    if (this.authMode === 'jwt-direct') {
+      if (!this.jwt || Date.now() >= this.jwtExpires) {
+        this.jwt = this._signJwt();
+        this.jwtExpires = Date.now() + 7 * 3600 * 1000; // refresh in 7h
+      }
+      return this.jwt;
+    }
+
+    if (this.authMode === 'login') {
+      if (!this.jwt || Date.now() >= this.jwtExpires) {
+        await this._loginAuth();
+      }
+      return this.jwt;
+    }
+
+    throw new Error('No authentication method available for Config UI X.');
+  }
+
+  /** Authenticate via HTTP login (fallback). */
+  async _loginAuth() {
+    const res = await fetch(`${this.baseUrl}/api/auth/login`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ username: this.uiUser, password: this.uiPass, otp: '' }),
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      throw new Error(`Config UI login failed (${res.status}): ${text}`);
+    }
+    const data = await res.json();
+    this.jwt = data.access_token;
+    this.jwtExpires = Date.now() + ((data.expires_in || 28800) - 60) * 1000;
+  }
+
+  /** GET /api/accessories */
+  async getAccessories() {
+    const tok = await this.token();
+    const res = await fetch(`${this.baseUrl}/api/accessories`, {
+      headers: { Authorization: `Bearer ${tok}`, Accept: 'application/json' },
+    });
+    if (!res.ok) throw new Error(`GET /api/accessories → ${res.status}`);
+    return res.json();
+  }
+
+  /** PUT /api/accessories/:uniqueId */
+  async setCharacteristic(uniqueId, characteristicType, value) {
+    const tok = await this.token();
+    const res = await fetch(`${this.baseUrl}/api/accessories/${encodeURIComponent(uniqueId)}`, {
+      method: 'PUT',
+      headers: { Authorization: `Bearer ${tok}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ characteristicType, value }),
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      throw new Error(`PUT ${characteristicType} → ${res.status}: ${text}`);
+    }
+    return res.json();
+  }
+}
+
+// ─── Accessory data parsing ─────────────────────────────────────────────────
+
+function parseAccessories(raw) {
+  const list = Array.isArray(raw) ? raw : [];
+  const devices = [];
+  for (const svc of list) {
+    const name = svc.serviceName || svc.accessoryInformation?.Name || '';
+    const type = svc.humanType || svc.type || 'Unknown';
+    const uid = svc.uniqueId;
+    if (!uid || type === 'AccessoryInformation' || type === 'ProtocolInformation') continue;
+    if (name.toLowerCase() === 'openclaw api') continue;
+
+    const chars = (svc.serviceCharacteristics || []);
+    const writableChars = chars.filter(c => c.canWrite).map(c => c.type);
+
+    devices.push({
+      id: uid,
+      name,
+      type: mapType(type),
+      humanType: type,
+      state: svc.values || {},
+      characteristics: writableChars,
+      manufacturer: svc.accessoryInformation?.Manufacturer || '',
+      model: svc.accessoryInformation?.Model || '',
+    });
+  }
+  return devices;
+}
+
+function mapType(humanType) {
+  const t = (humanType || '').toLowerCase();
+  if (t.includes('light') || t.includes('bulb')) return 'lightbulb';
+  if (t.includes('switch')) return 'switch';
+  if (t.includes('outlet')) return 'outlet';
+  if (t.includes('thermostat')) return 'thermostat';
+  if (t.includes('lock')) return 'lock';
+  if (t.includes('fan')) return 'fan';
+  if (t.includes('window') || t.includes('blind') || t.includes('covering')) return 'blinds';
+  if (t.includes('garage')) return 'garage';
+  if (t.includes('motion')) return 'motion';
+  if (t.includes('temperature')) return 'sensor';
+  if (t.includes('humidity')) return 'sensor';
+  if (t.includes('contact')) return 'sensor';
+  if (t.includes('camera')) return 'camera';
+  return 'other';
+}
+
+// ─── Action resolution ──────────────────────────────────────────────────────
+
+const MODE_MAP = { off: 0, heat: 1, cool: 2, auto: 3 };
+
+function resolveAction(action, value) {
+  switch (action) {
+    case 'on': case 'power':
+      return { characteristicType: 'On', value: Boolean(value) };
+    case 'toggle':
+      return { characteristicType: 'On', value: Boolean(value) };
+    case 'brightness': case 'dim':
+      return { characteristicType: 'Brightness', value: clamp(value, 0, 100) };
+    case 'hue':
+      return { characteristicType: 'Hue', value: clamp(value, 0, 360) };
+    case 'saturation':
+      return { characteristicType: 'Saturation', value: clamp(value, 0, 100) };
+    case 'color': {
+      const ops = [];
+      if (value?.hue !== undefined) ops.push({ characteristicType: 'Hue', value: Number(value.hue) });
+      if (value?.saturation !== undefined) ops.push({ characteristicType: 'Saturation', value: Number(value.saturation) });
+      return ops;
+    }
+    case 'colorTemperature': case 'ct':
+      return { characteristicType: 'ColorTemperature', value: Number(value) };
+    case 'targetTemperature': case 'temperature':
+      return { characteristicType: 'TargetTemperature', value: Number(value) };
+    case 'thermostatMode': case 'mode':
+      return { characteristicType: 'TargetHeatingCoolingState', value: MODE_MAP[String(value).toLowerCase()] ?? Number(value) };
+    case 'lock':
+      return { characteristicType: 'LockTargetState', value: value ? 1 : 0 };
+    case 'speed': case 'rotationSpeed':
+      return { characteristicType: 'RotationSpeed', value: clamp(value, 0, 100) };
+    case 'position': case 'targetPosition':
+      return { characteristicType: 'TargetPosition', value: clamp(value, 0, 100) };
+    case 'tilt': case 'targetTilt':
+      return { characteristicType: 'TargetHorizontalTiltAngle', value: clamp(value, -90, 90) };
+    case 'garageDoor': case 'garage':
+      return { characteristicType: 'TargetDoorState', value: value ? 0 : 1 };
+    default:
+      return null;
+  }
+}
+
+function clamp(v, min, max) { return Math.max(min, Math.min(max, Number(v))); }
+
+// ─── Express routes ─────────────────────────────────────────────────────────
+
+function setupRoutes(app, apiToken, uiClient) {
+  // Auth middleware
+  function auth(req, res, next) {
+    const h = req.headers.authorization || '';
+    if (!h.startsWith('Bearer ') || h.substring(7) !== apiToken) {
+      return res.status(401).json({ error: 'Unauthorized', message: 'Invalid or missing Bearer token.' });
+    }
+    next();
+  }
+
+  // Health (no auth, sanitized)
+  app.get('/health', async (_req, res) => {
+    let deviceCount = 0;
+    let connected = false;
+    try {
+      const raw = await uiClient.getAccessories();
+      deviceCount = parseAccessories(raw).length;
+      connected = true;
+    } catch (_) { /* silent */ }
+    res.json({
+      status: connected ? 'ok' : 'degraded',
+      plugin: PLUGIN_NAME,
+      version: VERSION,
+      timestamp: new Date().toISOString(),
+      devices: deviceCount,
+    });
+  });
+
+  // List devices
+  app.get('/api/devices', auth, async (_req, res) => {
+    try {
+      const raw = await uiClient.getAccessories();
+      const devices = parseAccessories(raw);
+      res.json({ success: true, count: devices.length, devices });
+    } catch (err) {
+      res.status(502).json({ error: 'Upstream error', message: err.message });
+    }
+  });
+
+  // List by type
+  app.get('/api/devices/type/:type', auth, async (req, res) => {
+    try {
+      const raw = await uiClient.getAccessories();
+      const devices = parseAccessories(raw).filter(d => d.type === req.params.type.toLowerCase());
+      res.json({ success: true, count: devices.length, devices });
+    } catch (err) {
+      res.status(502).json({ error: 'Upstream error', message: err.message });
+    }
+  });
+
+  // Get single device
+  app.get('/api/devices/:id', auth, async (req, res) => {
+    try {
+      const raw = await uiClient.getAccessories();
+      const device = parseAccessories(raw).find(d => d.id === req.params.id);
+      if (!device) return res.status(404).json({ error: 'Not Found', message: `Device '${req.params.id}' not found.` });
+      res.json({ success: true, device });
+    } catch (err) {
+      res.status(502).json({ error: 'Upstream error', message: err.message });
+    }
+  });
+
+  // Control single device
+  app.post('/api/devices/:id/control', auth, async (req, res) => {
+    const { action, value } = req.body || {};
+    if (!action) return res.status(400).json({ error: 'Bad Request', message: 'Missing "action".' });
+    const resolved = resolveAction(action, value);
+    if (!resolved) return res.status(400).json({ error: 'Bad Request', message: `Unknown action: ${action}.` });
+    try {
+      const ops = Array.isArray(resolved) ? resolved : [resolved];
+      const results = [];
+      for (const op of ops) {
+        results.push(await uiClient.setCharacteristic(req.params.id, op.characteristicType, op.value));
+      }
+      res.json({ success: true, id: req.params.id, action, results });
+    } catch (err) {
+      res.status(502).json({ error: 'Control error', message: err.message });
+    }
+  });
+
+  // Control multiple devices
+  app.post('/api/devices/control', auth, async (req, res) => {
+    const { devices } = req.body || {};
+    if (!Array.isArray(devices)) return res.status(400).json({ error: 'Bad Request', message: 'Expected "devices" array.' });
+    const results = [];
+    for (const item of devices) {
+      const resolved = resolveAction(item.action, item.value);
+      if (!resolved) { results.push({ id: item.id, success: false, error: `Unknown action: ${item.action}` }); continue; }
+      try {
+        const ops = Array.isArray(resolved) ? resolved : [resolved];
+        for (const op of ops) await uiClient.setCharacteristic(item.id, op.characteristicType, op.value);
+        results.push({ id: item.id, success: true });
+      } catch (err) {
+        results.push({ id: item.id, success: false, error: err.message });
+      }
+    }
+    res.json({ success: true, results });
+  });
+}
+
+// ─── Homebridge registration ────────────────────────────────────────────────
+
+module.exports = function (api) {
+  api.registerAccessory(PLUGIN_NAME, ACCESSORY_NAME, OpenClawAccessory);
+};
+
+class OpenClawAccessory {
+  constructor(log, config, api) {
+    this.log = log;
+    this.config = config;
+    this.api = api;
+    this.name = config.name || 'OpenClaw API';
+
+    const storagePath = detectStoragePath();
+    this.storagePath = storagePath;
+
+    // Resolve API token (what OpenClaw sends to us)
+    const { token: apiToken } = resolveApiToken(config, storagePath, log);
+    this.apiToken = apiToken;
+
+    // Create UI client (how we talk to Config UI X)
+    this.uiClient = new UiClient({
+      storagePath,
+      uiUrl: config.homebridgeUiUrl,
+      uiUser: config.homebridgeUiUser,
+      uiPass: config.homebridgeUiPass,
+      log,
+    });
+
+    api.on('didFinishLaunching', () => this._startServer());
+  }
+
+  async _startServer() {
+    const port = this.config.apiPort || DEFAULT_PORT;
+    const bind = this.config.apiBind || DEFAULT_BIND;
+    const rpmLimit = this.config.rateLimit || DEFAULT_RATE_LIMIT;
+
+    // Verify auth works
+    try {
+      await this.uiClient.token();
+      this.log.info(`[${PLUGIN_NAME}] Connected to Config UI X (${this.uiClient.authMode}).`);
+    } catch (err) {
+      this.log.error(`[${PLUGIN_NAME}] Config UI X auth failed: ${err.message}`);
+    }
+
+    const app = express();
+    app.use(express.json());
+    app.set('trust proxy', 1);
+
+    // Rate limiting
+    app.use(rateLimit({
+      windowMs: 60 * 1000,
+      max: rpmLimit,
+      standardHeaders: true,
+      legacyHeaders: false,
+      message: { error: 'Too Many Requests', message: `Rate limit: ${rpmLimit} requests per minute.` },
+    }));
+
+    setupRoutes(app, this.apiToken, this.uiClient);
+
+    const server = app.listen(port, bind, () => {
+      this.log.info(`[${PLUGIN_NAME}] REST API listening on ${bind}:${port}`);
+    });
+    server.on('error', err => {
+      this.log.error(`[${PLUGIN_NAME}] Server error: ${err.message}`);
+    });
+  }
+
+  getServices() {
+    const Service = this.api.hap.Service;
+    const Characteristic = this.api.hap.Characteristic;
+    const info = new Service.AccessoryInformation();
+    info
+      .setCharacteristic(Characteristic.Name, 'OpenClaw API')
+      .setCharacteristic(Characteristic.Manufacturer, 'OpenClaw')
+      .setCharacteristic(Characteristic.Model, 'REST API Bridge')
+      .setCharacteristic(Characteristic.SerialNumber, VERSION);
+    return [info];
+  }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "homebridge-openclaw",
+  "displayName": "OpenClaw API",
+  "version": "2.1.0",
+  "description": "Expose a REST API so OpenClaw agents can list and control HomeKit devices via Homebridge.",
+  "main": "index.js",
+  "keywords": [
+    "homebridge-plugin",
+    "homebridge",
+    "homekit",
+    "openclaw",
+    "smart-home",
+    "rest-api"
+  ],
+  "engines": {
+    "node": ">=18.0.0",
+    "homebridge": ">=1.6.0"
+  },
+  "dependencies": {
+    "express": "^4.18.2",
+    "express-rate-limit": "^7.5.0",
+    "jsonwebtoken": "^9.0.2"
+  },
+  "author": "",
+  "license": "MIT",
+  "files": [
+    "index.js",
+    "config.schema.json",
+    "homebridge-ui-logo.png",
+    "LICENSE",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/davidevp/homebridge-openclaw.git"
+  },
+  "homepage": "https://github.com/davidevp/homebridge-openclaw#readme",
+  "bugs": {
+    "url": "https://github.com/davidevp/homebridge-openclaw/issues"
+  }
+}