DOCSEARCHbyAlgolia
Submit Docs

eufy-security-ws

repository·master·Indexed 42 days ago

https://github.com/bropat/eufy-security-ws

A Node.js WebSocket server implementation that wraps the eufy-security-client library to provide remote access and integration for Eufy security devices. Version 3.1.0 supports device management, live stream control (Standard and RTSP), PTZ calibration, and event retrieval. Note: Active development has moved to eufy-sdk.

Tokens
28.8K
Snippets
62
Records
99
Agent score
54%

What's inside eufy-security-ws

  1. What is eufy-security-ws

    master

    eufy-security-ws is a server wrapper around the eufy-security-client library that exposes device control via a WebSocket API. It enables interaction with Eufy security devices by connecting to Eufy cloud servers, local/remote stations, and establishing P2P or MQTT connections where supported.

    To use the server, you must provide your Eufy cloud login credentials. The server uses these to request device data via HTTPS and manage connections to the Eufy ecosystem.

  2. Overview of eufy-security-ws

    master
    eufy-security-ws is a small server wrapper around the eufy-security-client library. It allows you to access Eufy security device functionality via a WebSocket interface, making it easier to integrate Eufy devices into other systems or home automation platforms that communicate over WebSockets.

  4. Securing the eufy-security-ws WebSocket API

    master

    By default, eufy-security-ws does not implement its own authentication layer and allows all incoming WebSocket connections.

    To secure your instance, you must implement authentication using one of the following methods:

    1. Express Middleware: Add authentication middleware directly to your Express instance.
    2. Reverse Proxy: Run NGINX (or a similar reverse proxy) in front of your Express instance to handle authentication before traffic reaches the WebSocket server.

  5. Understand the eufy-security-ws API lifecycle

    master

    The API follows a specific sequence of events to establish communication and receive device updates:

    1. Connection & Versioning: Upon connection, the server immediately sends a version message containing driver and server versions, as well as the supported minSchemaVersion and maxSchemaVersion.
    2. Schema Negotiation: The client should ideally send a set_api_schema command to specify which API version it wants to use. If omitted, the server defaults to the minimum supported schema (currently 0).
    3. Start Listening: To receive device states and events, the client must send the start_listening command.
    4. State Initialization: After start_listening, the server responds with a result message containing the current state (driver info, stations, and devices) and begins streaming real-time events for any state changes.
    // 1. Server sends version on connect
// { type: "version", driverVersion: "...", serverVersion: "...", minSchemaVersion: 0, maxSchemaVersion: 13 }

// 2. Client sets schema (optional but recommended)
// { command: "set_api_schema", messageId: 1, schemaVersion: 1 }

// 3. Client starts listening for events
// { messageId: "unique-id", command: "start_listening" }

// 4. Server responds with initial state
// { type: "result", messageId: "unique-id", success: true, result: { state: { ... } } }

  6. Handle RSA_PKCS1_PADDING and CVE-2023-46809 in Node.js 24+

    master

    The Eufy cloud handshake requires RSA_PKCS1_PADDING. Due to CVE-2023-46809, newer versions of Node.js (24+) no longer support the --security-revert=CVE-2023-46809 flag, which previously allowed this padding.

    To ensure compatibility with Node 24+ without using insecure Node flags, eufy-security-ws uses an embedded pure-JS PKCS#1 implementation.

    • Default Behavior: The embedded implementation is enabled by default (enableEmbeddedPKCS1Support: true). No action is required for most users.
    • Opting Out: If you need to disable this, set "enableEmbeddedPKCS1Support": false in your configuration file.

  9. Start the eufy-security-client

    master

    The client CLI allows you to interact with the running server. It defaults to connecting to ws://localhost:3000.

    Use --host and --port to connect to a remote server, and --schemaVersion to specify the supported schema version.

    tsx src/bin/client.ts

# Connect to a specific host and port
tsx src/bin/client.ts --host 192.168.1.100 --port 6000

# Specify a schema version
tsx src/bin/client.ts --schemaVersion 0

  10. Deploy eufy-security-ws

    master

    To deploy a new version of eufy-security-ws, follow these steps to ensure dependencies and branches are synchronized:

    1. Update all npm dependencies and ensure the latest published version of eufy-security-client is included.
    2. Review and merge relevant Pull Requests into the develop branch.
    3. Merge the develop branch into master.
    4. Create and publish a new GitHub release and tag from the master branch.
    5. Publish the new version of the eufy-security-ws npm package using the code from the master branch.

  11. Run eufy-security-ws using Docker Dev image

    master

    The bropat/eufy-security-ws-dev Docker image is intended for testing specific branches for users or developers.

    Important: To enable local auto-discovery (UDP broadcasting) of Eufy stations, you must run the container with --network host. If you use standard port mapping (-p), local discovery will fail and the system will fall back to cloud discovery.

    The image uses a /data volume which corresponds to the persistentDir in the application configuration.

    docker run --network host -it \
    -e USERNAME=user \
    -e PASSWORD=password \
    -e PORT=3000 \
    -e COUNTRY=UK \
    -e EUFY_CLIENT_GIT_URL=<url> \
    -e EUFY_CLIENT_GIT_BRANCH=<branch> \
    -v "$(PWD)"/data:/data \
    bropat/eufy-security-ws:latest

  12. Negotiate API Schema Version

    master

    To ensure compatibility between different client and server versions, use the set_api_schema command. This allows the client to tell the server exactly which API version it is prepared to handle.

    • Supported Range: Check the minSchemaVersion and maxSchemaVersion provided in the initial version message sent by the server upon connection.
    • Default Behavior: If you do not send this command, the server defaults to the minimum supported schema (currently 0).
    • Error Handling: If you request a schemaVersion that is outside the server's supported range, the server will return an error with the code schema_incompatible.
    // Command to set schema
{
  "command": "set_api_schema",
  "messageId": 1,
  "schemaVersion": 1
}

// Error response for out-of-range version
{
  "type": "result",
  "success": false,
  "messageId": 1,
  "errorCode": "schema_incompatible"
}