English

Fork of Rohithkadaveru/ha-pass, an MIT-licensed add-on for Home Assistant that creates shareable, time-limited guest links for controlling specific entities. All credit for the original design (scoped tokens, the guest PWA, service allowlisting, rate limiting, IP allowlisting) goes to the original author.

This fork adds advance/recurring scheduling and a few related features aimed at replacing what a smart-intercom "guest invitation" feature typically offers (invite someone for a specific future date/time, or a recurring weekly window), while staying self-hosted and auditable.

✨ What's new in this fork

• Advance scheduling — create a link today that only becomes active at a future date/time (starts_at), instead of always starting immediately.

• Recurring weekly windows — restrict a token to specific weekdays and a daily time range (e.g. every Tue/Thu 09:00–13:00), on top of the absolute expiry.

• "First use" event — a distinct first_use activity (alongside the existing page_load/ command events) fires exactly once, the first time a link is actually opened — useful for a "your guest has arrived" notification.

• button / input_button domain support — these single-action, stateless entities (e.g. a helper wired to a gate/door relay via shell_command/rest_command) can now be exposed to guests; they weren't in the original service allowlist.

• Narrow, opt-in entity suggestions — a "Suggest entities" action in the admin UI scans your HA entities for two categories (Access: locks/covers/buttons matching door/gate keywords; Lights: the light domain) and pre-selects matches — you still review and adjust the selection. Three ready-made invitation modes (Access only/Lights only/Access and lights) just apply this filter. Deliberately narrow: it only ever suggests plausible candidates, it never auto-adds a whole dashboard's worth of entities.

• Local-network-only command execution — for access-type domains only (lock, cover, button, input_button), the guest link and its live state stay viewable from anywhere, but actually triggering the action is refused unless the request comes from a configured home-network CIDR range. Honest limitation: this checks the request's source IP, i.e. the guest's device has to actually be joined to that network at the moment they tap the button — it is not GPS-based proximity detection. This is a fixed, whole-add-on setting (LOCAL_NETWORK_CIDRS), not something chosen per token.

• Country allowlist — per token, optionally restrict the entire link (viewing included, not just commands) to visitors whose public IP is located in one or more chosen countries (ISO codes, e.g. ES, PT). Resolved against the free ipdeny.com country IP blocks when the token is created, and again once a day, so a long-lived link follows the country's current ranges (each country's list is downloaded at most every 30 days; if it cannot be, the token keeps the ranges it had). Enforced the same way as the network-CIDR check above. Different guarantee than the local-network check: this only narrows down which country a connection comes from, not whether the guest is actually on the home Wi-Fi — the two are independent and can both apply to the same token.

• Single-device link binding — the first browser/device to open a guest link claims it (a signed, HttpOnly/SameSite=Strict cookie scoped to that one link); any other device that opens the same link afterwards is refused, so a guest can't casually forward the link onward. An "Unbind" action in the admin UI releases the claim (e.g. the guest changed phones).

• Single-use links — an optional "Single use" checkbox makes a link stop working after the guest's first action (opening a door, pressing a button...), on top of (or instead of) a normal expiry. Complements the pre-existing "Never expires" option for the opposite case — a permanent link, revoked by hand.

• Admin dashboard: bilingual English/Spanish. Auto-detects by default, but can be pinned to a specific language from its Profile menu regardless of the browser — useful if the admin's browser is in a language they don't want the dashboard rendered in.

• Guest PWA: all 24 official languages of the European Union. A guest link can end up in anyone's hands, so the guest-facing page (Bulgarian, Croatian, Czech, Danish, Dutch, English, Estonian, Finnish, French, German, Greek, Hungarian, Irish, Italian, Latvian, Lithuanian, Maltese, Polish, Portuguese, Romanian, Slovak, Slovenian, Spanish, Swedish) always auto-detects from the guest's own browser language — no override, since a guest link isn't "owned" by anyone who'd have a profile to set one.

• Survives Home Assistant being down. Both run as ordinary containers with no ordering between them, so a host that reboots can easily bring this one up first. It used to treat that as fatal and exit; now it serves the panel anyway and a watchdog reconnects on its own the moment Home Assistant answers. The dashboard says so plainly while it waits, and a guest is asked to try again rather than burning a one-shot pairing on a page that could show no devices. /health reports it too, but keeps a 200: a neighbour's outage must not paint this container red.

• Guest page grouped by room. When a guest's devices span more than one Home Assistant area, the page shows them room by room, in Home Assistant's own area order; devices with no area go last under "Other". An entity takes its device's area unless it has one of its own, as in Home Assistant. Only the rooms the guest has something in are named. If the areas cannot be read, the page keeps the usual list by kind of device.

None of the above touches the original security model: the same entity/service allowlist, forbidden-key stripping, rate limiting, and IP allowlisting from upstream still apply — these are additive restrictions and scheduling features, not a rewrite of the trust boundary.

📦 Installation

Home Assistant Add-on

1. Add this repository in Settings → Add-ons → Add-on Store → ⋮ → Repositories:

   https://github.com/Nebur692/ha-pass-invitations
   

2. Find HAPass in the store and click Install.

3. Go to the Configuration tab and set your options (see below — a few are new in this fork).

4. Start the add-on.

5. Click Open Web UI or find HAPass in the HA sidebar.

Admin access works through the HA sidebar — no separate login needed. Guest links use the direct port (http://<your-ha-ip>:5880/g/{slug}) so visitors don't need HA accounts.

Unraid

This is a standalone Docker container, not a Home Assistant Supervisor add-on — use this method if your Home Assistant runs as homeassistant/home-assistant (Core only, no Supervisor), which can't use the Add-on method above.

1. Docker → Add Container → scroll down → Template repositories, add:

   https://github.com/Nebur692/unraid-community-apps
   

2. Save, then start a new Add Container again — pick ha-pass-invitations from the template dropdown.

3. Fill in HA_BASE_URL, HA_TOKEN and ADMIN_PASSWORD (required); the rest have sensible defaults. See Configuration below for what each variable does.

4. Apply. The admin dashboard is at http://<unraid-ip>:5880/admin/dashboard.

Not yet listed in the Community Applications search — the template repository step above works immediately regardless, without waiting on that.

Docker Compose

Pushing a vX.Y.Z tag to this repo triggers a GitHub Actions build that publishes to ghcr.io/nebur692/ha-pass-invitations. Until a version has been tagged, build the image locally from the Dockerfile instead of pulling a pre-built one.

services:
  ha-pass:
    image: ghcr.io/nebur692/ha-pass-invitations:latest
    restart: unless-stopped
    ports:
      - 5880:5880
    volumes:
      - ./data:/data
    environment:
      - ADMIN_USERNAME=admin
      - ADMIN_PASSWORD=changeme
      - HA_BASE_URL=http://homeassistant.local:8123
      - HA_TOKEN=your_long_lived_token_here
      - TIMEZONE=Europe/Madrid

docker compose up -d

Note: Docker deployments need a long-lived access token from Home Assistant (Profile → Security → Long-Lived Access Tokens). The add-on handles this automatically.

⚙️ Configuration

In addition to every option from upstream (admin credentials, app name, contact message, branding, log retention, guest URL — see DOCS.md), this fork adds:

Since 1.6.0 most of these are editable from the admin panel, under the Settings button, and apply without a restart. The environment seeds the value; once you change it in the panel the stored value wins, and you can revert it. Only credentials and connection details — HA_BASE_URL, HA_TOKEN, DB_PATH, PORT, ADMIN_USERNAME, ADMIN_PASSWORD, TRUSTED_PROXIES — stay environment-only: the app cannot read its own database to find out where its database is.

Upgrading keeps whatever you were already running with: values that differ from the defaults are stored on first start, so you can then delete those variables from your container without anything reverting.

Bluetooth presence

Requiring the guest to be on your WiFi means handing out the WiFi password. ha_ble replaces that: the Android app advertises over Bluetooth, the scanners already wired into Home Assistant hear it, and Home Assistant streams every advertisement to the add-on over the WebSocket connection it already holds.

This matters for what the proof is worth. The adversary is the guest — they hold a valid link — so anything their own phone merely asserts is worthless, because they can patch the app and lie. Here the sighting is made by your hardware and delivered over your Home Assistant, exactly like the source IP is today.

The advertised value is a single service UUID: a fixed prefix plus a code derived from the token's binding secret and the current 15-second window. It is deliberately not a static device id — that would be copyable, and a cheap board hidden by the door replaying it would open the lock forever. It also means a guest is not trackable by a fixed identifier between visits.

Set the door scanner from Presence & Bluetooth in the admin panel: start listening and walk a Bluetooth gadget from another room to the door. Home Assistant only ever reports the nearest scanner, so the entry follows you and the door scanner ends up highlighted. Copy its MAC into BLE_SCANNERS.

With PRESENCE_POLICY=any (the default) browser guests keep using the home network while app guests use Bluetooth. ha_ble fails closed when BLE_SCANNERS is empty: "heard by any scanner in the house" is not "at the door".

What this does not stop. A guest with a rooted phone can drive the app and relay codes to a radio left by the door. No cryptography inside a phone can prove the phone is there — that is distance bounding, and it needs the physical layer. It is the same class of attack that defeats car keys, it takes premeditation and hardware, and whoever does it already holds a valid link.

Per-token scheduling and access rules (starts_at, recurrence, ip_allowlist, country_allowlist) are set from the admin dashboard's Create Token form — there's nothing to configure at the add-on level for those.

🧭 Supported Entity Types

Same as upstream, plus:

lock, cover, button, and input_button are also the domains gated by LOCAL_NETWORK_CIDRS when it's set.

💙 Support

None of this would be possible without the community's support. If this project has been useful to you, consider supporting it via GitHub Sponsors, Ko-fi or PayPal — every bit helps keep it maintained.

⚠️ Disclaimer

Not affiliated with, endorsed by, or associated with Home Assistant or Nabu Casa Inc. "Home Assistant" is a trademark of Nabu Casa Inc. Not affiliated with the original HAPass author beyond this being an open, credited fork under the same MIT license.

📜 License

MIT — original copyright retained, fork changes are contributed under the same terms.

Español

Fork de Rohithkadaveru/ha-pass, un complemento con licencia MIT para Home Assistant que crea enlaces de invitado, compartibles y con caducidad, para controlar entidades concretas. Todo el crédito del diseño original (tokens acotados, la PWA de invitado, lista blanca de servicios, rate limiting, lista blanca de IP) es del autor original.

Este fork añade programación por adelantado/recurrente y varias funciones relacionadas, pensadas para sustituir lo que suele ofrecer la función de "invitación de invitados" de un telefonillo inteligente (invitar a alguien para una fecha/hora futura concreta, o una ventana semanal recurrente), manteniéndolo autoalojado y auditable.

✨ Novedades de este fork

• Programación por adelantado — crear hoy un enlace que solo se activa en una fecha/hora futura (starts_at), en vez de activarse siempre de inmediato.

• Ventanas semanales recurrentes — restringir un token a días concretos de la semana y una franja horaria diaria (p.ej. todos los martes/jueves 09:00–13:00), además de la caducidad absoluta.

• Evento de "primer uso" — una actividad first_use distinta (junto a las ya existentes page_load/command) se dispara una única vez, la primera vez que el enlace se abre de verdad — útil para un aviso de "tu invitado ha llegado".

• Soporte de dominio button/input_button — estas entidades de acción única y sin estado (p.ej. un helper conectado a un relé de puerta/portón vía shell_command/rest_command) ya se pueden exponer a invitados; no estaban en la lista blanca de servicios original.

• Sugerencias de entidades acotadas y opcionales — una acción "Sugerir entidades" en el panel de administración escanea tus entidades de HA en dos categorías (Accesos: cerraduras/toldos/ botones que coincidan con palabras clave de puerta/portón; Luces: dominio light) y preselecciona coincidencias — tú sigues revisando y ajustando la selección. Tres modos de invitación ya montados (Solo accesos/Solo luces/Accesos y luces) simplemente aplican ese filtro. Deliberadamente acotado: solo sugiere candidatos plausibles, nunca añade automáticamente todo un panel de entidades.

• Ejecución de comandos restringida a la red local — solo para dominios de tipo acceso (lock, cover, button, input_button), el enlace y su estado en vivo se siguen viendo desde cualquier sitio, pero la acción en sí se rechaza si la petición no viene de un rango CIDR configurado como "red de casa". Limitación honesta: esto comprueba la IP de origen de la petición, es decir, el dispositivo del invitado debe estar realmente unido a esa red en el momento de pulsar — no es detección de proximidad por GPS. Es un ajuste fijo de todo el complemento (LOCAL_NETWORK_CIDRS), no algo que se elija por token.

• Lista blanca de países — por token, restringe opcionalmente todo el enlace (incluida su visualización, no solo los comandos) a visitantes cuya IP pública esté en uno o varios países elegidos (códigos ISO, p.ej. ES, PT). Se resuelve contra los bloques de IP por país gratuitos de ipdeny.com al crear el token y otra vez cada día, así que un enlace de larga duración sigue los rangos actuales del país (la lista de cada país se descarga como mucho cada 30 días; si no se puede, el token conserva los rangos que tenía). Se aplica igual que la comprobación de red local de arriba. Garantía distinta a la de red local: esto solo acota de qué país viene la conexión, no si el invitado está de verdad en el WiFi de casa — son independientes y pueden aplicarse ambas al mismo token.

• Vinculación del enlace a un solo dispositivo — el primer navegador/dispositivo que abre un enlace de invitado lo reclama (una cookie firmada, HttpOnly/SameSite=Strict, acotada a ese enlace concreto); cualquier otro dispositivo que abra después el mismo enlace queda rechazado, así el invitado no puede reenviarlo sin más. Una acción "Desvincular" en el panel de administración libera la reclamación (p.ej. si el invitado cambia de móvil).

• Enlaces de un solo uso — una casilla opcional "Un solo uso" hace que el enlace deje de funcionar tras la primera acción del invitado (abrir una puerta, pulsar un botón...), además de (o en vez de) una caducidad normal. Complementa la opción ya existente "No caduca nunca" para el caso contrario — un enlace permanente, revocado a mano.

• Panel de administración: bilingüe español/inglés. Detecta automáticamente por defecto, pero se puede fijar a un idioma concreto desde su menú de Perfil sin depender del navegador — útil si el navegador del administrador está en un idioma en el que no quiere ver el panel.

• PWA del invitado: los 24 idiomas oficiales de la Unión Europea. Un enlace de invitado puede acabar en manos de cualquiera, así que la página de cara al invitado (búlgaro, croata, checo, danés, neerlandés, inglés, estonio, finés, francés, alemán, griego, húngaro, irlandés, italiano, letón, lituano, maltés, polaco, portugués, rumano, eslovaco, esloveno, español, sueco) siempre detecta automáticamente el idioma del navegador del invitado — sin opción manual, ya que un enlace de invitado no tiene "dueño" con un perfil donde fijar uno.

• Aguanta que Home Assistant esté caído. Los dos corren como contenedores normales sin ningún orden entre ellos, así que un servidor que reinicia puede levantar este primero sin problema. Antes eso era fatal y se salía; ahora sirve el panel igual y un vigilante reconecta solo en cuanto Home Assistant responda. El panel lo dice claramente mientras espera, y al invitado se le pide que lo intente de nuevo en vez de gastar una vinculación de un solo uso en una página que no podría enseñar ningún dispositivo. /health también lo informa, pero sigue devolviendo 200: la caída del vecino no debe pintar de rojo a este contenedor.

• Página del invitado agrupada por habitaciones. Cuando los dispositivos de un invitado están en más de un área de Home Assistant, la página los enseña habitación por habitación, en el mismo orden de áreas que Home Assistant; los que no tienen área van al final, en "Otros". Una entidad toma el área de su dispositivo salvo que tenga una propia, igual que en Home Assistant. Solo se nombran las habitaciones en las que el invitado tiene algo. Si no se pueden leer las áreas, la página sigue con la lista de siempre por tipo de dispositivo.

Nada de lo anterior toca el modelo de seguridad original: la misma lista blanca de entidad/ servicio, el filtrado de claves prohibidas, el rate limiting y la lista blanca de IP de la versión original siguen aplicando — son restricciones y funciones de programación añadidas, no una reescritura del límite de confianza.

📦 Instalación

Complemento de Home Assistant

1. Añade este repositorio en Ajustes → Complementos → Tienda de complementos → ⋮ → Repositorios:

   https://github.com/Nebur692/ha-pass-invitations
   

2. Busca HAPass en la tienda y pulsa Instalar.

3. Ve a la pestaña Configuración y ajusta tus opciones (ver abajo — algunas son nuevas de este fork).

4. Arranca el complemento.

5. Pulsa Abrir interfaz web o búscalo en la barra lateral de HA.

El acceso de administrador funciona a través de la barra lateral de HA — no hace falta iniciar sesión aparte. Los enlaces de invitado usan el puerto directo (http://<tu-ip-de-ha>:5880/g/{slug}) para que los visitantes no necesiten cuenta de HA.

Unraid

Esto es un contenedor Docker independiente, no un complemento del Supervisor de Home Assistant — usa este método si tu Home Assistant corre como homeassistant/home-assistant (solo Core, sin Supervisor), que no puede usar el método de complemento de arriba.

1. Docker → Add Container → baja hasta Template repositories, añade:

   https://github.com/Nebur692/unraid-community-apps
   

2. Guarda, y vuelve a pulsar Add Container — elige ha-pass-invitations en el desplegable de plantillas.

3. Rellena HA_BASE_URL, HA_TOKEN y ADMIN_PASSWORD (obligatorias); el resto ya trae valores por defecto razonables. Consulta Configuración más abajo para saber qué hace cada variable.

4. Aplica. El panel de administración queda en http://<ip-de-unraid>:5880/admin/dashboard.

Todavía no aparece en el buscador de Community Applications — el paso de arriba (repositorio de plantillas) funciona ya mismo igualmente, sin depender de eso.

Docker Compose

Al subir un tag vX.Y.Z a este repositorio se dispara una build de GitHub Actions que publica en ghcr.io/nebur692/ha-pass-invitations. Hasta que exista una versión etiquetada, construye la imagen en local desde el Dockerfile en vez de descargar una ya construida.

services:
  ha-pass:
    image: ghcr.io/nebur692/ha-pass-invitations:latest
    restart: unless-stopped
    ports:
      - 5880:5880
    volumes:
      - ./data:/data
    environment:
      - ADMIN_USERNAME=admin
      - ADMIN_PASSWORD=changeme
      - HA_BASE_URL=http://homeassistant.local:8123
      - HA_TOKEN=your_long_lived_token_here
      - TIMEZONE=Europe/Madrid

docker compose up -d

Nota: los despliegues Docker necesitan un token de acceso de larga duración de Home Assistant (Perfil → Seguridad → Tokens de acceso de larga duración). El complemento lo gestiona automáticamente.

⚙️ Configuración

Además de todas las opciones ya existentes (credenciales de admin, nombre de la app, mensaje de contacto, marca, retención de logs, URL de invitado — ver DOCS.md), este fork añade:

Desde la 1.6.0 la mayoría se editan desde el panel de administración, en el botón Ajustes, y se aplican sin reiniciar. El entorno da el valor inicial; en cuanto lo cambias en el panel manda el guardado, y puedes revertirlo. Solo las credenciales y los datos de conexión —HA_BASE_URL, HA_TOKEN, DB_PATH, PORT, ADMIN_USERNAME, ADMIN_PASSWORD, TRUSTED_PROXIES— siguen siendo exclusivos del entorno: la aplicación no puede leer su propia base de datos para averiguar dónde está su base de datos.

Al actualizar se conserva lo que ya tenías: los valores distintos de los de por defecto se guardan en el primer arranque, así que después puedes borrar esas variables de tu contenedor sin que nada se revierta.

Presencia por Bluetooth

Exigir que el invitado esté en tu WiFi obliga a darle la contraseña de la WiFi. ha_ble lo sustituye: la app Android emite por Bluetooth, los escáneres que ya tienes conectados a Home Assistant la oyen, y Home Assistant envía cada anuncio al complemento por el WebSocket que ya mantiene abierto.

Esto es lo que hace que la prueba valga algo. El adversario es el invitado —tiene un enlace válido—, así que cualquier cosa que solo afirme su móvil no sirve, porque puede modificar la app y mentir. Aquí la detección la hace tu hardware y llega por tu Home Assistant, igual que hoy llega la IP de origen.

Lo que se anuncia es un único UUID de servicio: un prefijo fijo más un código derivado del secreto de vinculación del token y de la ventana de 15 segundos actual. Deliberadamente no es un identificador estático — sería copiable, y bastaría una placa barata escondida junto a la puerta reemitiéndolo para abrir la cerradura para siempre. Además evita que el invitado sea rastreable por un identificador fijo entre visitas.

El escáner de la puerta se elige desde Presencia y Bluetooth en el panel de administración: empieza a escuchar y lleva un cacharro Bluetooth desde otra habitación hasta la puerta. Home Assistant solo informa del escáner más cercano, así que la entrada te va siguiendo y el de la puerta acaba resaltado. Copia su MAC en BLE_SCANNERS.

Con PRESENCE_POLICY=any (el valor por defecto) los invitados por navegador siguen usando la red de casa mientras los de la app usan Bluetooth. ha_ble falla cerrado si BLE_SCANNERS está vacío: "oído por cualquier escáner de la casa" no es "en la puerta".

Lo que esto no impide. Un invitado con el móvil rooteado puede manejar la app y retransmitir códigos a una radio dejada junto a la puerta. Ninguna criptografía dentro de un teléfono puede demostrar que el teléfono está allí — eso es acotamiento de distancia y necesita la capa física. Es la misma clase de ataque que vence a las llaves de coche, exige premeditación y hardware, y quien lo hace ya tiene un enlace válido.

La programación y las reglas de acceso por token (starts_at, recurrence, ip_allowlist, country_allowlist) se configuran desde el formulario de creación de token del panel de administración — no hay nada que configurar a nivel de complemento para eso.

🧭 Tipos de entidad soportados

Igual que la versión original, más:

lock, cover, button e input_button son también los dominios afectados por LOCAL_NETWORK_CIDRS cuando está configurado.

💙 Apoya el proyecto

Sin el apoyo de la comunidad estos proyectos no serían posibles. Si te ha resultado útil, puedes apoyarlo vía GitHub Sponsors, Ko-fi o PayPal — cualquier aportación ayuda a seguir manteniéndolo.

⚠️ Aviso legal

No afiliado, respaldado ni asociado con Home Assistant ni Nabu Casa Inc. "Home Assistant" es una marca registrada de Nabu Casa Inc. No afiliado con el autor original de HAPass más allá de ser un fork abierto y con crédito bajo la misma licencia MIT.

📜 Licencia

MIT — se mantiene el copyright original; los cambios del fork se aportan bajo los mismos términos.