@homebridge-plugins/homebridge-eufy-security 4.7.2 → 5.0.0-beta.1

package/AUTHORS

@@ -0,0 +1,4 @@
+# Current maintainer of Homebridge Eufy. This does not replace repository history or claim sole
+# authorship of prior contributions.
+
+lenoxys

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,30 @@
+# Code of conduct
+
+## The short version
+
+Be decent. Assume the other person is trying to help. Argue about the code, not the person behind it.
+
+This project is maintained in spare time. Nobody is on call or owes anyone a fix, and a maintainer
+who says "not now" or "won't do" is answering, not being rude.
+
+## Not acceptable
+
+- Harassment, insults, personal attacks, or discriminatory language.
+- Unwelcome attention or comments about someone's experience, English, or contribution quality.
+- Publishing private information, credentials, device data, account details, logs, or captures.
+- Demanding, entitled, or repeated pressure on maintainers.
+
+## Scope
+
+This applies in issues, pull requests, commits, discussions, Discord, and anywhere someone acts as
+part of this project.
+
+## Enforcement
+
+Maintainers may remove, edit, or reject contributions that do not fit these expectations. Repeated or
+severe behavior may result in a block. Report conduct concerns privately to a maintainer; reports are
+handled discreetly.
+
+## Attribution
+
+Adapted in spirit from the [Contributor Covenant](https://www.contributor-covenant.org).

package/CONTRIBUTING.md

@@ -0,0 +1,77 @@
+# Contributing
+
+Thanks for helping. This file covers setup, development workflow, and pull requests. Architecture and
+code rules are in [AGENTS.md](./AGENTS.md); read them before changing the plugin.
+
+## License
+
+The project is licensed under [Apache-2.0](./LICENSE). By opening a pull request, you agree that your
+contribution is provided under the same license.
+
+## Setup
+
+```bash
+nvm use
+npm install
+npm run verify
+```
+
+Node 24.5.0 or newer is required. `npm run verify` runs the same local quality gate expected before a
+pull request: formatting, the guard against restoring `eufy-security-client`, the build, and the
+hermetic Vitest contracts.
+
+## Architecture
+
+The SDK owns verified Eufy device truth and transport behavior. This plugin owns Homebridge lifecycle
+and HomeKit representation. Use explicit capability and bundle adapters; do not infer services from
+primitive SDK shapes and do not bypass evidence-gated SDK operations.
+
+The current vocabulary is in [CONTEXT.md](./CONTEXT.md).
+
+## Development workflow
+
+- Start from the active `beta-X.Y.Z` branch and open the pull request against that branch unless a
+  maintainer says otherwise.
+- Use Conventional Commits.
+- Keep each change focused and run `npm run verify` before requesting review.
+- Do not add `Co-authored-by` trailers automatically.
+- Explain new runtime dependencies, including why existing dependencies or `node:*` APIs are
+  insufficient and what transitive/audit cost is introduced.
+- Treat real-device access as read-only unless the owner explicitly approves a write operation.
+
+### Live qualification
+
+`npm run verify` stays hermetic, so anything needing a real account, camera, or transport is
+qualified by a script in [scripts/](./scripts/). Its index,
+[scripts/README.md](./scripts/README.md), describes every procedure and says which scripts write.
+
+## Pull requests
+
+Keep the body concise and developer-focused:
+
+- what changed and why;
+- what was verified;
+- device, Homebridge, or Home app evidence used;
+- anything unverified, intentionally omitted, or deferred;
+- migration or release impact.
+
+Never include real serials, P2P identifiers, account or user IDs, device names, addresses,
+credentials, tokens, keys, logs, or captures. Use synthetic placeholders and review the diff before
+submission.
+
+## Release notes
+
+Release notes are for users. Put required actions, compatibility changes, removed settings, and
+behavior changes first. Avoid internal milestones and implementation detail.
+
+## Working with AI agents
+
+- Point the agent at [AGENTS.md](./AGENTS.md), [CONTEXT.md](./CONTEXT.md), and relevant ADRs.
+- Verify every claimed SDK symbol and behavior against the current checkout.
+- Do not let an agent infer protocol behavior from an older third-party Eufy client.
+- Review generated output for secrets, real device data, incompatible code, and unsupported claims.
+- The contributor remains responsible for every submitted line.
+
+## Reporting security issues
+
+Do not open a public issue. Follow [SECURITY.md](./SECURITY.md).

package/README.md

@@ -1,67 +1,170 @@
-<p align="center">
-   <a href="https://github.com/homebridge-plugins/homebridge-eufy-security"><img src="https://raw.githubusercontent.com/wiki/homebridge-eufy-security/plugin/img/homebridge-eufy-security.png" width="456px"></a>
-</p>
-
-<p align="center">
-  <strong>Control your Eufy Security devices from Apple HomeKit</strong>
-</p>
-
-<p align="center">
-  <a href="https://www.npmjs.com/package/@homebridge-plugins/homebridge-eufy-security"><img src="https://img.shields.io/npm/v/@homebridge-plugins/homebridge-eufy-security?color=green&label=stable" alt="stable"></a>
-  <a href="https://github.com/homebridge-plugins/homebridge-eufy-security/wiki/Special-Version-(BETA---RC---HKSV)"><img src="https://img.shields.io/npm/v/@homebridge-plugins/homebridge-eufy-security/beta?label=beta" alt="beta"></a>
-  <a href="https://github.com/homebridge/plugins/wiki/Scoped-Plugins"><img src="https://badgen.net/badge/homebridge/scoped/purple" alt="scoped"></a>
-  <a href="https://www.npmjs.com/package/@homebridge-plugins/homebridge-eufy-security"><img src="https://img.shields.io/npm/dt/@homebridge-plugins/homebridge-eufy-security" alt="downloads"></a>
-  <a href="https://discord.com/channels/432663330281226270/876907345962229791"><img src="https://img.shields.io/discord/432663330281226270?color=728ED5&logo=discord&label=discord" alt="discord"></a>
-</p>
+<div align="center">
 
----
+<!-- The suffix names the mode: logo-dark.svg is the white glyph for dark backgrounds. -->
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/homebridge-plugins/homebridge-eufy/beta-5.0.0/homebridge-ui/public/assets/logo-dark.svg">
+  <img src="https://raw.githubusercontent.com/homebridge-plugins/homebridge-eufy/beta-5.0.0/homebridge-ui/public/assets/logo.svg" alt="Homebridge Eufy" height="96">
+</picture>
 
-## ✨ Features
+**Bring verified eufy device capabilities into Apple Home through Homebridge.**
 
-| | |
-|---|---|
-| 🎥 **Live Streaming** | P2P & RTSP livestream in the Home app |
-| 📹 **HomeKit Secure Video** | Record and review clips natively in HomeKit |
-| 🔔 **Doorbell & Sensors** | Ring notifications, motion & entry sensors |
-| 🔐 **Locks & Guard Modes** | Smart lock control, arm/disarm your station |
-| 🏠 **Bridged & Unbridged** | Run cameras as separate accessories for performance |
+[![verified-by-homebridge](https://img.shields.io/badge/homebridge-verified-blueviolet?color=%23491F59&style=flat)](https://github.com/homebridge/homebridge/wiki/Verified-Plugins)
+[![npm](https://img.shields.io/npm/v/@homebridge-plugins/homebridge-eufy-security?logo=npm&color=cb3837)](https://www.npmjs.com/package/@homebridge-plugins/homebridge-eufy-security)
 
-> **Supported devices** — Cameras, doorbells, floodlights, indoor cams, locks, sensors, stations & more.  
-> See the full [Supported Devices](https://github.com/homebridge-plugins/homebridge-eufy-security/wiki/Supported-Devices) list.
+[Documentation](https://homebridge-plugins.github.io/homebridge-eufy/) · [Contributing](./CONTRIBUTING.md) · [Security](./SECURITY.md) · [Releases](https://github.com/homebridge-plugins/homebridge-eufy/releases)
+
+</div>
 
 ---
 
-## 🚀 Getting Started
+> [!IMPORTANT]
+> **V5 is a beta and not yet a replacement for the stable V4 plugin.** Every capability area is
+> implemented, covered by the contract suite, and exercised against a real device fleet. What remains is
+> qualifying one immutable artifact and approving the public beta.
+>
+> **V5 does not adopt V4 HomeKit accessories.** It registers its own, so expect to remove the V4
+> accessories and reassign rooms, names, and automations once. A V4 configuration block is not loaded
+> either. A device the SDK recognizes is not automatically represented in HomeKit: representation requires
+> an explicit adapter for a primary-purpose member.
 
-| Requirement | |
-|---|---|
-| [Homebridge](https://homebridge.io) | `>=2.0.0` |
-| Node.js | `>=24.5.0` |
-| Eufy Account | A [dedicated guest account](https://support.eufylife.com/s/article/Share-Your-eufySecurity-Devices-With-Your-Family) is **mandatory** |
+## What it is
 
-> **💡 Node.js & RSA_PKCS1_PADDING** — Node.js `24.5.0+` restores native `RSA_PKCS1_PADDING`, so P2P livestream works out of the box and no workaround is needed. See the [compatibility guide](https://github.com/homebridge-plugins/homebridge-eufy-security/wiki/Node.js-Compatibility-with-Eufy-Security-Plugin) for details.
+Homebridge Eufy is a Homebridge 2 platform plugin for the eufy ecosystem. It maintains one persisted
+eufy session, discovers the account's devices through
+[`@mega-yfue/eufy-sdk`](https://github.com/mega-yfue/eufy-sdk), and maps verified SDK capabilities to
+official HomeKit services through explicit capability adapters.
 
----
+The SDK owns device and transport truth. This plugin owns Homebridge lifecycle, stable accessory
+identity, HomeKit representation and policy, configuration, diagnostics, and media adaptation. It
+does not infer HomeKit meaning from raw value shapes or manufacture controls that the SDK cannot
+verify.
 
-## 📖 Documentation
+## Requirements
 
-| Setup | Features | Help |
-|---|---|---|
-| [Installation](https://github.com/homebridge-plugins/homebridge-eufy-security/wiki/Installation-and-Configuration#installation) | [Streaming](https://github.com/homebridge-plugins/homebridge-eufy-security/wiki/Streaming-Settings) | [Troubleshooting](https://github.com/homebridge-plugins/homebridge-eufy-security/wiki/Basic-Troubleshooting) |
-| [Configuration](https://github.com/homebridge-plugins/homebridge-eufy-security/wiki/Installation-and-Configuration#configuration) | [HomeKit Secure Video](https://github.com/homebridge-plugins/homebridge-eufy-security/wiki/HomeKit-Secure-Video) | [Common Issues](https://github.com/homebridge-plugins/homebridge-eufy-security/wiki/Common-Issues) |
-| [Bridged & Unbridged](https://github.com/homebridge-plugins/homebridge-eufy-security/wiki/Bridged-and-Unbridged-Mode-and-Problems) | [Supported Devices](https://github.com/homebridge-plugins/homebridge-eufy-security/wiki/Supported-Devices) | [Report a Bug](https://github.com/homebridge-plugins/homebridge-eufy-security/issues/new/choose) |
-| [Beta Versions](https://github.com/homebridge-plugins/homebridge-eufy-security/wiki/Special-Version-(BETA---RC---HKSV)) | | [Changelog](https://github.com/homebridge-plugins/homebridge-eufy-security/blob/master/CHANGELOG.md) |
+- [Homebridge](https://homebridge.io/) 2.4 or newer
+- Node.js 24.5.0 or newer
+- A dedicated guest eufy account with the relevant home and devices shared to it
 
----
+Using a guest account keeps the personal eufy app and Homebridge from competing for one session. See
+eufy's [sharing guide](https://support.eufylife.com/s/article/Share-Your-eufySecurity-Devices-With-Your-Family).
 
-## 💛 Supporting
+## Install
 
-| Active Contributors |
-|---|
-| [Lenoxys](https://github.com/sponsors/lenoxys) |
+Install stable releases through the Homebridge UI by searching for **Homebridge Eufy**, or
+from npm:
 
-**Founded by** [samemory](https://ko-fi.com/S6S24XCVJ) · **Powered by** [bropat](https://ko-fi.com/bropat)'s [eufy-security-client](https://github.com/bropat/eufy-security-client)
+```bash
+npm install -g @homebridge-plugins/homebridge-eufy-security
+```
 
----
+While V5 is a beta, it is published under the `beta` dist-tag rather than `latest`:
 
-<sub>This project is not affiliated with Anker or Eufy Security. Use entirely at your own risk — see [LICENSE](LICENSE) for details.</sub>
+```bash
+npm install -g @homebridge-plugins/homebridge-eufy-security@beta
+```
+
+## First-time setup
+
+1. Create a dedicated guest eufy account and share the required home and devices with it.
+2. Install the plugin and open its custom UI from Homebridge.
+3. Enter the guest account details and complete captcha or two-factor verification if requested.
+4. Wait for authentication and complete discovery to finish.
+5. Restart Homebridge so the long-lived runtime can acquire the persisted session.
+
+V5 uses the new `HomebridgeEufy` platform alias. A V4 block using `EufySecurity` is not loaded and must
+be replaced with a fresh V5 configuration block.
+
+Credentials are persisted in Homebridge/plugin configuration. Challenge answers stay inside the
+temporary authentication flow, and the runtime never falls back to interactive login.
+
+## Current V5 scope
+
+| Area | Status |
+|---|---|
+| Interactive login, captcha, and two-factor continuation | Implemented |
+| Persisted session restore and single runtime ownership | Implemented |
+| Complete device discovery, runtime snapshot, and dashboard | Implemented |
+| Contact sensors, motion, and doorbell presses | Implemented |
+| Camera live video and audio, snapshots, and talkback | Implemented |
+| HomeKit Secure Video recording | Implemented |
+| Security system arming, locks, sirens, and lights | Implemented |
+| Battery, charging, and low-battery enrichment | Implemented |
+| Guided diagnostics and redacted support archives | Implemented |
+| Continuous validation against a real device fleet | Ongoing |
+| Qualification of an immutable pilot artifact, then public beta approval | Remaining |
+
+Support is capability-led rather than model-led, so capability evidence decides coverage instead of product
+naming, and a newly recognized model that exposes an already-adapted capability works without an allowlist.
+Of the 303 rows in the coverage matrix, 57 have an admitted HomeKit adapter, 230 remain diagnostic-only, and
+16 are blocked by a declared SDK gap. Recognized devices therefore appear in the dashboard before, or
+without, an explicit HomeKit adapter for their primary purpose.
+
+Device behaviour is grounded in measurement rather than inference: [`docs/architecture.md`](./docs/architecture.md)
+records the observed timings and outcomes behind the live, recording, and control decisions, and
+[`scripts/`](./scripts/README.md) holds the checks that produce them against real cameras.
+
+## Documentation
+
+The [documentation site](https://homebridge-plugins.github.io/homebridge-eufy/) contains the
+current V5 contract and a clearly separated migration of useful legacy V4 wiki material. Current V5
+work is tracked in the [beta issues](https://github.com/homebridge-plugins/homebridge-eufy/issues)
+and release notes.
+
+- [Installation](https://homebridge-plugins.github.io/homebridge-eufy/guide/installation)
+- [Configuration](https://homebridge-plugins.github.io/homebridge-eufy/reference/configuration)
+- [Troubleshooting](https://homebridge-plugins.github.io/homebridge-eufy/troubleshooting/)
+- [Current releases](https://github.com/homebridge-plugins/homebridge-eufy/releases)
+- [SDK documentation](https://mega-yfue.github.io/)
+
+## Design
+
+V5 uses one dependency direction:
+
+```text
+Homebridge lifecycle
+  -> runtime and temporary authentication owners
+  -> @mega-yfue/eufy-sdk
+  -> canonical device registry and complete snapshot
+  -> explicit capability and bundle adapters
+  -> official HomeKit services and characteristics
+```
+
+Capability adapters are closed-world and semantic. Unsupported SDK capabilities remain visible as
+diagnostics but do not receive a generic HomeKit fallback. The domain vocabulary lives in
+[`CONTEXT.md`](./CONTEXT.md).
+
+## Develop
+
+```bash
+nvm use
+npm install
+npm run verify
+```
+
+For local SDK development, replace the SDK dependency with `file:../eufy-sdk` and run `npm install`
+again. `npm run verify` is the complete repository gate: formatting, dependency guard, TypeScript
+build, packed-artifact import, and contract tests.
+
+## Contributing
+
+Pull requests are welcome. [`CONTRIBUTING.md`](./CONTRIBUTING.md) covers setup and workflow;
+[`AGENTS.md`](./AGENTS.md) defines the code and architecture rules. Report security issues through
+[`SECURITY.md`](./SECURITY.md), never through a public issue.
+
+## Funding and credits
+
+Development is supported by [Lenoxys](https://github.com/sponsors/lenoxys). The project was founded by
+[samemory](https://ko-fi.com/S6S24XCVJ). Earlier releases were built on bropat's
+[`eufy-security-client`](https://github.com/bropat/eufy-security-client); V5 uses
+[`@mega-yfue/eufy-sdk`](https://github.com/mega-yfue/eufy-sdk).
+
+## License
+
+[Apache-2.0](./LICENSE). Contributions are accepted under the same license.
+
+## Disclaimer
+
+Independent and unofficial, built for interoperability with eufy devices you own. **Not affiliated
+with, endorsed by, or sponsored by Anker Innovations or eufy.** "eufy" and "Anker" are trademarks of
+their respective owners and appear here only to identify compatible hardware. Use responsibly: rapid
+or failed login attempts can trigger captcha challenges or temporary account cooldowns.

package/SECURITY.md

@@ -0,0 +1,30 @@
+# Security policy
+
+## Reporting a vulnerability
+
+**Do not open a public issue.** Report privately through GitHub Security Advisories:
+
+> [Report a vulnerability](https://github.com/homebridge-plugins/homebridge-eufy/security/advisories/new)
+
+Include the affected version, reproduction steps, and impact where possible. Reports are handled
+privately, and reporters are credited unless they prefer anonymity.
+
+## Scope
+
+In scope are vulnerabilities in this repository that weaken a user's Homebridge host, Eufy account,
+devices, or private data, including credential and session handling, UI/runtime IPC, diagnostics,
+media processing, configuration, and reachable dependency vulnerabilities.
+
+Vulnerabilities in Eufy, Anker, Apple, or Homebridge services themselves are out of scope and should
+be reported to the relevant vendor. A flaw in how this plugin integrates with those systems is in
+scope.
+
+## Supported versions
+
+Only the latest stable release and current published beta receive security fixes.
+
+## Credentials and diagnostics
+
+Never commit Homebridge configuration, SDK sessions, diagnostics, or recordings. If Eufy credentials
+or a session may have been exposed, invalidate active sessions from the Eufy app and change the
+account password. Treat unencrypted diagnostics as sensitive even after automated redaction.

package/config.schema.json

@@ -1,6 +1,95 @@
 {
-  "pluginAlias": "EufySecurity",
+  "pluginAlias": "HomebridgeEufy",
   "pluginType": "platform",
   "singular": true,
-  "customUi": true
-}
+  "customUi": true,
+  "schema": {
+    "type": "object",
+    "properties": {
+      "username": {
+        "title": "Eufy account email",
+        "type": "string"
+      },
+      "password": {
+        "title": "Eufy account password",
+        "format": "password",
+        "type": "string"
+      },
+      "country": {
+        "title": "Account country",
+        "description": "Two-letter country code used to select the Eufy account region.",
+        "default": "US",
+        "pattern": "^[A-Za-z]{2}$",
+        "type": "string"
+      },
+      "trustedDeviceName": {
+        "title": "Trusted-device name",
+        "default": "Homebridge Eufy",
+        "minLength": 1,
+        "type": "string"
+      },
+      "pollingIntervalMinutes": {
+        "title": "Polling interval in minutes",
+        "default": 10,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "maxConcurrentMediaSessions": {
+        "title": "Concurrent camera media limit",
+        "description": "How many cameras may stream live video or take a fresh still at the same time. Use 0 for unlimited, which is the default. A camera refused because the limit is reached is never interrupted once it has started, and a still that cannot be taken now is answered with the camera’s most recent picture instead. Set this if several cameras at once make live view stutter on this host.",
+        "default": 0,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "warmUpEvents": {
+        "title": "Warm up camera connections",
+        "description": "Events that open a camera’s connection as soon as it reports one, so the live view or snapshot straight afterwards starts immediately. Every camera is independent: an event opens only the camera that reported it, and only for the events chosen here. A camera on its own battery is kept awake for several minutes each time; wired cameras and those behind a HomeBase are unaffected. Choose these in the plugin interface, which offers whatever your devices actually report.",
+        "type": "array",
+        "default": [
+          "doorbellPress"
+        ],
+        "uniqueItems": true,
+        "items": {
+          "type": "string"
+        }
+      },
+      "ffmpegPath": {
+        "title": "FFmpeg path",
+        "description": "Leave unset to use the FFmpeg executable bundled with the plugin.",
+        "minLength": 1,
+        "type": "string"
+      },
+      "entityPreferences": {
+        "title": "Entity preferences",
+        "additionalProperties": false,
+        "default": {},
+        "type": "object",
+        "patternProperties": {
+          "^.+$": {
+            "additionalProperties": false,
+            "properties": {
+              "represented": {
+                "default": true,
+                "type": "boolean"
+              },
+              "audio": {
+                "default": true,
+                "type": "boolean"
+              },
+              "snapshotMode": {
+                "default": "Refresh",
+                "enum": [
+                  "Cloud",
+                  "Live",
+                  "Refresh"
+                ],
+                "type": "string"
+              }
+            },
+            "type": "object"
+          }
+        }
+      }
+    }
+  }
+}