homebridge-centsys 0.1.0-alpha.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dean van Niekerk
+
+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,39 @@
+# homebridge-centsys
+
+A Homebridge plugin in development for CENTURION / CENTSYS SMART+ gates, with a browser login wizard, gate-state monitoring and experimental open/close control.
+
+**Status: alpha.5 completed one owner-confirmed physical open-and-close cycle through Apple Home on iHost.** Both commands received success responses on their first attempt, and Home displayed Opening → Open → Closing → Closed. Reliability and real gate-offline testing remain in progress. Automatic account discovery is empty on this installation, so setup supports a manually supplied serial and validated protocol address.
+
+The tested controller is **D5 Evo SMART+**, Core and Comms Interface firmware **2.1.0.0**. Experimental command handling is limited to this profile in South Africa and is disabled by default. It requires a fresh MQTT session, serializes commands and never automatically repeats an uncertain activation. One explicit configuration-version mismatch permits a corrected-version retry; this negotiation is tested in simulation and awaits hardware validation.
+
+## Homebridge setup
+
+Use Homebridge 2.4.x and Node 22 or 24. The first public alpha is being prepared. Once published, install `homebridge-centsys@alpha` in the npm environment used by Homebridge, then restart Homebridge, open the plugin's settings and follow the phone/OTP wizard. Until then, use a development tarball as described in the installation guide. Select a discovered gate to fill its serial and available protocol MAC, or follow the [manual setup guide](docs/INSTALLATION.md#if-discovery-is-empty-or-the-protocol-mac-is-missing). For a D5 Evo SMART+ in South Africa, the experimental fallback takes the serial and Wi-Fi MAC from MyCentsys Pro and fills the protocol MAC only after controller authentication and live status succeed. The helper has passed a live identity/status verification on the tested installation; discovery remains empty there. Check status, save and restart. Session credentials live in Homebridge's persistent storage, so restarting or updating the plugin does not require another login unless the vendor rejects the session.
+
+See [installation, storage and control limitations](docs/INSTALLATION.md). No npm release has been published yet. Release metadata targets the `alpha` channel. Publishing follows the [AquaTemp-style GitHub Actions procedure](docs/RELEASING.md), with exact-version approval and npm trusted publishing.
+
+## Development and diagnostics
+
+```sh
+npm ci
+npm run check
+npm pack
+```
+
+The independent research CLI remains available:
+
+```sh
+npm run prepare:auth
+npm run diagnose -- login
+npm run diagnose -- status
+npm run diagnose -- status-known
+```
+
+`status-known` requires an owner-only `.local/auth/operator.json` containing your own controller serial. CLI credentials are separate from deployed Homebridge credentials. All diagnostic output omits identifying account/device fields and labels HTTP readings as potentially cached.
+
+- [Diagnostic CLI guide](https://github.com/deanvanniekerk/homebridge-centsys/blob/codex/cloud-read-client/docs/DIAGNOSTICS.md)
+- [Implementation and validation evidence](docs/VALIDATION.md)
+- [Feasibility and design](https://github.com/deanvanniekerk/homebridge-centsys/blob/codex/cloud-read-client/docs/FEASIBILITY.md)
+- [Protocol research](https://github.com/deanvanniekerk/homebridge-centsys/blob/codex/cloud-read-client/docs/research/connectivity.md)
+
+Independent project, not affiliated with CENTURION, Apple or Homebridge. Adaptation credits and the upstream MIT license are in [third-party notices](THIRD_PARTY_NOTICES.md).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,27 @@
+# Third-party notices
+
+The HTTPS authentication/discovery/overview/certificate contract, MQTT packet encoding, telemetry layout, status mappings and public broker CA certificate were adapted from [Lex-campbell/centsys_remote](https://github.com/Lex-campbell/centsys_remote) at commit `4d6daab50e4305fe2d3ea2c0d2df6e65737e1dba`. The implementation here is TypeScript and uses stricter decoding and bounded transport. Bootstrap preparation for the CLI and Homebridge settings UI extracts a credential from that same pinned MIT-licensed source into ignored local storage.
+
+The upstream copyright and permission notice follows:
+
+MIT License
+
+Copyright (c) 2026 Lex Campbell
+
+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/config.schema.json

@@ -0,0 +1,59 @@
+{
+  "pluginAlias": "Centsys",
+  "pluginType": "platform",
+  "singular": true,
+  "customUi": true,
+  "headerDisplay": "Sign in and configure your gates in the setup wizard.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "type": "string",
+        "default": "CENTSYS"
+      },
+      "pollInterval": {
+        "title": "Idle polling interval (seconds)",
+        "type": "integer",
+        "default": 15,
+        "minimum": 10,
+        "maximum": 300
+      },
+      "gates": {
+        "type": "array",
+        "maxItems": 10,
+        "items": {
+          "type": "object",
+          "required": ["serialNumber"],
+          "properties": {
+            "name": {
+              "type": "string",
+              "default": "Gate",
+              "minLength": 1,
+              "maxLength": 64
+            },
+            "serialNumber": {
+              "type": "string",
+              "pattern": "^[0-9a-fA-F]{24}$"
+            },
+            "macAddress": {
+              "type": "string",
+              "pattern": "^([0-9a-fA-F]{2}:){5}[0-9a-fA-F]{2}$"
+            },
+            "enableControl": {
+              "type": "boolean",
+              "default": false
+            },
+            "controlProfile": {
+              "type": "string",
+              "enum": ["d5-evo-smart-plus"]
+            },
+            "triggerModeConfirmed": {
+              "type": "boolean",
+              "default": false
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/dist/bootstrap.js

@@ -0,0 +1,44 @@
+import { createHash } from "node:crypto";
+import { CentsysError } from "./errors.js";
+import { credential } from "./protocol.js";
+// Source-pinned, opt-in setup step. Downloads data only; never executes Python.
+const revision = "4d6daab50e4305fe2d3ea2c0d2df6e65737e1dba";
+const sourceUrl = `https://api.github.com/repos/Lex-campbell/centsys_remote/contents/custom_components/centsys_remote/api/const.py?ref=${revision}`;
+const expectedHash = "a812a8a58d1b1359396ccfe1f605885420465ed5bb820279c4aacc2ee40cc5f1";
+export async function fetchBootstrap() {
+    try {
+        const response = await fetch(sourceUrl, {
+            redirect: "error",
+            signal: AbortSignal.timeout(10_000),
+            headers: {
+                Accept: "application/vnd.github.raw+json",
+                "User-Agent": "homebridge-centsys/0.0.0",
+            },
+        });
+        if (!response.ok || !response.body) {
+            await response.body?.cancel();
+            throw new CentsysError("http");
+        }
+        const chunks = [];
+        let bytes = 0;
+        for await (const chunk of response.body) {
+            bytes += chunk.byteLength;
+            if (bytes > 65_536)
+                throw new CentsysError("protocol");
+            chunks.push(chunk);
+        }
+        const source = Buffer.concat(chunks);
+        if (createHash("sha256").update(source).digest("hex") !== expectedHash)
+            throw new CentsysError("protocol");
+        const block = /GATEWAY_API_SERVICE_LEVEL_JWT\s*=\s*\(([\s\S]*?)\)/.exec(source.toString("utf8"))?.[1];
+        if (!block)
+            throw new CentsysError("protocol");
+        const token = credential([...block.matchAll(/"([A-Za-z0-9_.-]+)"/g)]
+            .map((match) => match[1])
+            .join(""));
+        return token;
+    }
+    catch (error) {
+        throw error instanceof CentsysError ? error : new CentsysError("transport");
+    }
+}

package/dist/cli.js

@@ -0,0 +1,108 @@
+import { createInterface } from "node:readline/promises";
+import { Writable } from "node:stream";
+import { CentsysReadClient } from "./client.js";
+import { CentsysError } from "./errors.js";
+import { diagnosticReport } from "./diagnostics.js";
+import { credential, normalizeNumber } from "./protocol.js";
+import { forgetSession, readPrivate, readKnownOperator, readSession, saveSession, } from "./storage.js";
+const shutdown = new AbortController();
+const abort = () => shutdown.abort();
+process.once("SIGINT", abort);
+process.once("SIGTERM", abort);
+async function login() {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        throw new CentsysError("configuration");
+    const bootstrapToken = credential((await readPrivate("bootstrap-token")).trim());
+    // readline's terminal echo goes to this sink; secrets never reach output/history.
+    const sink = new Writable({
+        write(_chunk, _encoding, callback) {
+            callback();
+        },
+    });
+    const prompt = createInterface({
+        input: process.stdin,
+        output: sink,
+        terminal: true,
+        historySize: 0,
+    });
+    prompt.on("SIGINT", abort);
+    async function ask(message) {
+        process.stdout.write(message);
+        const answer = await prompt.question("", { signal: shutdown.signal });
+        process.stdout.write("\n");
+        return answer.trim();
+    }
+    try {
+        process.stdout.write("Sign in to your own CENTSYS account. Input is hidden. No gate commands are available.\n");
+        const mobileNumber = normalizeNumber(await ask("Registered phone number, including +country code: "));
+        const regionInput = (await ask("Region [za/au, default za]: ")) || "za";
+        if (regionInput !== "za" && regionInput !== "au")
+            throw new CentsysError("configuration");
+        const channel = (await ask("Send one OTP via [whatsapp/sms, default whatsapp]: ")) ||
+            "whatsapp";
+        if (channel !== "whatsapp" && channel !== "sms")
+            throw new CentsysError("configuration");
+        const client = new CentsysReadClient({
+            mobileNumber,
+            region: regionInput,
+            bootstrapToken,
+        });
+        await client.sendOtp(channel, shutdown.signal);
+        process.stdout.write("The service accepted the OTP request. Delivery is not guaranteed.\n");
+        const token = await client.validateOtp(await ask("One-time code: "), shutdown.signal);
+        await saveSession({ mobileNumber, region: regionInput, token });
+        process.stdout.write("Signed in. Session saved privately under .local/auth/. Run: npm run diagnose -- status\n");
+    }
+    finally {
+        prompt.close();
+        sink.destroy();
+    }
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0 || (args.length === 1 && args[0] === "--help")) {
+        process.stdout.write("Read-only CENTSYS diagnostics\n\n  npm run prepare:auth          Fetch the pinned bootstrap credential locally\n  npm run diagnose -- login    Interactive phone/OTP sign-in (hidden input)\n  npm run diagnose -- status   Discover gates and print a sanitized cloud overview\n  npm run diagnose -- status-known   Read the operator in private operator.json\n  npm run diagnose -- logout   Remove the local session (does not revoke it remotely)\n");
+        return;
+    }
+    if (args.length !== 1)
+        throw new CentsysError("configuration");
+    if (args[0] === "login")
+        return login();
+    if (args[0] === "logout") {
+        await forgetSession();
+        process.stdout.write("Local session removed.\n");
+        return;
+    }
+    if (args[0] !== "status" && args[0] !== "status-known")
+        throw new CentsysError("configuration");
+    const manual = args[0] === "status-known";
+    const session = await readSession();
+    const client = new CentsysReadClient({
+        mobileNumber: session.mobileNumber,
+        region: session.region,
+        sessionToken: session.token,
+    });
+    const devices = manual
+        ? [await readKnownOperator()]
+        : await client.discover(shutdown.signal);
+    const overviews = await client.overview(devices, shutdown.signal);
+    process.stdout.write(`${JSON.stringify({ ...diagnosticReport(devices, overviews, new Date()), identitySource: manual ? "owner-configured" : "cloud-discovery" }, null, 2)}\n`);
+    if (devices.length === 0)
+        process.stderr.write("No linked operators were returned. This does not establish that the account has no locally paired devices.\n");
+}
+try {
+    await main();
+}
+catch (error) {
+    const safe = shutdown.signal.aborted
+        ? new CentsysError("cancelled")
+        : error instanceof CentsysError
+            ? error
+            : new CentsysError("local-storage");
+    process.stderr.write(`${safe.code}: ${safe.message}\n`);
+    process.exitCode = shutdown.signal.aborted ? 130 : 1;
+}
+finally {
+    process.removeListener("SIGINT", abort);
+    process.removeListener("SIGTERM", abort);
+}

package/dist/client.js

@@ -0,0 +1,162 @@
+import { CentsysError } from "./errors.js";
+import { credential, decodeDevices, decodeOverviews, normalizeNumber, record, } from "./protocol.js";
+const origins = {
+    za: "https://centsys.southafricanorth.cloudapp.azure.com:4445",
+    au: "https://centsys.australiaeast.cloudapp.azure.com:4445",
+};
+export class CentsysReadClient {
+    #mobileNumber;
+    #origin;
+    #fetch;
+    #timeoutMs;
+    #bootstrapToken;
+    #sessionToken;
+    constructor(options) {
+        this.#mobileNumber = normalizeNumber(options.mobileNumber);
+        if (options.region !== "za" && options.region !== "au")
+            throw new CentsysError("configuration");
+        this.#origin = origins[options.region];
+        this.#fetch = options.fetch ?? globalThis.fetch;
+        this.#timeoutMs = options.timeoutMs ?? 10_000;
+        if (!Number.isInteger(this.#timeoutMs) ||
+            this.#timeoutMs < 1 ||
+            this.#timeoutMs > 30_000) {
+            throw new CentsysError("configuration");
+        }
+        this.#bootstrapToken =
+            options.bootstrapToken === undefined
+                ? undefined
+                : credential(options.bootstrapToken);
+        this.#sessionToken =
+            options.sessionToken === undefined
+                ? undefined
+                : credential(options.sessionToken);
+    }
+    async #request(operation, body, authenticated, signal) {
+        const bearer = authenticated
+            ? this.#sessionToken
+            : (this.#sessionToken ?? this.#bootstrapToken);
+        if (!bearer)
+            throw new CentsysError("authentication");
+        const url = new URL(`/${operation}`, this.#origin);
+        if (operation === "GetDevicesByRemoteUserNumber")
+            url.searchParams.set("remoteUserNumber", this.#mobileNumber);
+        const deadline = AbortSignal.timeout(this.#timeoutMs);
+        const combined = signal ? AbortSignal.any([signal, deadline]) : deadline;
+        try {
+            combined.throwIfAborted();
+            const response = await this.#fetch(url, {
+                method: "POST",
+                redirect: "error",
+                headers: {
+                    Authorization: `Bearer ${bearer}`,
+                    "Content-Type": "application/json",
+                    Accept: "application/json",
+                    "Accept-Language": "en-US,en;q=0.9",
+                    "User-Agent": "homebridge-centsys/0.0.0",
+                },
+                ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+                signal: combined,
+            });
+            // Do not retain or print error responses; they may echo account data.
+            if (response.status !== 200) {
+                await response.body?.cancel();
+                if (response.status === 401 || response.status === 403)
+                    throw new CentsysError("authentication");
+                if (response.status === 429)
+                    throw new CentsysError("rate-limited");
+                throw new CentsysError("http");
+            }
+            const reader = response.body?.getReader();
+            if (!reader)
+                throw new CentsysError("protocol");
+            const chunks = [];
+            let bytes = 0;
+            try {
+                while (true) {
+                    const chunk = await reader.read();
+                    if (chunk.done)
+                        break;
+                    bytes += chunk.value.byteLength;
+                    if (bytes > 1_048_576)
+                        throw new CentsysError("protocol");
+                    chunks.push(chunk.value);
+                }
+            }
+            finally {
+                await reader.cancel().catch(() => { });
+                reader.releaseLock();
+            }
+            try {
+                return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+            }
+            catch {
+                throw new CentsysError("protocol");
+            }
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw new CentsysError("cancelled");
+            if (deadline.aborted)
+                throw new CentsysError("timeout");
+            if (error instanceof CentsysError)
+                throw error;
+            throw new CentsysError("transport");
+        }
+    }
+    async sendOtp(channel, signal) {
+        if (channel !== "whatsapp" && channel !== "sms")
+            throw new CentsysError("configuration");
+        const result = await this.#request("SendOtp", {
+            MobileNumber: this.#mobileNumber,
+            OtpPlatform: channel === "whatsapp" ? 1 : 2,
+            ThreeLetterIsoLanguageName: "eng",
+        }, false, signal);
+        if (result !== true)
+            throw new CentsysError("otp-not-sent");
+    }
+    async validateOtp(otp, signal) {
+        if (!/^\d{4,10}$/.test(otp))
+            throw new CentsysError("configuration");
+        const result = record(await this.#request("ValidateOtp", { MobileNumber: this.#mobileNumber, Otp: otp }, false, signal));
+        if (result.response === "")
+            throw new CentsysError("otp-rejected");
+        if (typeof result.response !== "string")
+            throw new CentsysError("protocol");
+        let token;
+        try {
+            token = credential(result.response);
+        }
+        catch {
+            throw new CentsysError("protocol");
+        }
+        this.#sessionToken = token;
+        return token;
+    }
+    async certificate(signal) {
+        const data = record(await this.#request("GetCertificate", {}, true, signal));
+        const fields = Object.fromEntries(Object.entries(data).map(([k, v]) => [k.toLowerCase(), v]));
+        const pfx = fields.certificatepfxbase64 ?? fields.pfxbase64;
+        const password = fields.certificatepassword ?? fields.password ?? "";
+        if (typeof pfx !== "string" ||
+            pfx.length < 4 ||
+            pfx.length > 131072 ||
+            !/^[A-Za-z0-9+/]+={0,2}$/.test(pfx) ||
+            pfx.length % 4 !== 0 ||
+            typeof password !== "string" ||
+            password.length > 4096)
+            throw new CentsysError("protocol");
+        return { pfx: Buffer.from(pfx, "base64"), password };
+    }
+    async discover(signal) {
+        return decodeDevices(await this.#request("GetDevicesByRemoteUserNumber", undefined, true, signal));
+    }
+    async overview(devices, signal) {
+        if (devices.length === 0)
+            return [];
+        // Revalidate identities even when a library consumer constructs the list manually.
+        const validated = decodeDevices(devices.map((device) => ({ serialNumber: device.serialNumber })));
+        const serials = validated.map((device) => device.serialNumber);
+        return decodeOverviews(await this.#request("GetOperatorOverview", { OperatorSerialNumbers: serials }, true, signal), new Set(serials));
+    }
+}