Skip to main content

Security model

Home Keeper has one rule: only an admin can change the home. Any signed-in user can use it and read it. Admins control the configuration and the appliance records. Any user can see due tasks and complete them, and read the appliances in the panel.

Why this rule exists​

A Home Assistant instance usually has 1 or 2 admins and a few users, such as a partner, older children, a housemate, or a guest account on a wall tablet.

Home Assistant reserves Settings and Developer tools for admins. Home Assistant also restricts the changes that its own config/* commands make, such as changes to the device registry and the entity registry, and to config entries, to admins. Home Keeper follows the same rule.

The risks are small. A guest account must not:

  • delete or change appliance records
  • redirect notifications away from you
  • read data through Home Keeper that Home Assistant hides from it, such as the entities of an integration

Home Keeper data is household data. Any signed-in user can read all appliance data, which includes purchase prices, serial numbers and warranty dates. The settings are open to read too. They include the profiles and the names of the notify services. If an account must not see this data, do not give that account access to Home Assistant.

Admin only​

The Home Keeper panel in the Home Assistant sidebar is open to every user. For a non-admin user, the panel hides the controls that change appliances.

The Settings tab shows only an "admin only" card to a non-admin user. The backend gate below is the real check.

Home Keeper gates each admin operation in 2 places: the websocket API the panel uses, and the matching home_keeper.* service.

OperationServices
Create, edit, delete, archive and restore appliancesadd_asset, update_asset, update_managed_asset, delete_asset, archive_asset, restore_asset
Appliance documents and part filesadd_asset_document, update_asset_document, remove_asset_document, remove_part_file, and a file upload (POST) to /api/home_keeper/document/… or /api/home_keeper/part_document/…
Delete an archived completion from an appliance's historydelete_archived_completion
Delete every orphaned task (a task whose managing integration is not loaded)delete_orphaned_tasks
Spare-part stock adjustmentsadjust_part_stock
Settings, profiles and notification deliveryset_options
The appliance report (costs, serials, value totals)export_appliance_report
Data export and import (every task, note, serial and cost, with the companion sections, the files and the settings of a bundle)export_data, import_data, the bundle download (GET /api/home_keeper/export_bundle) and the import upload (POST /api/home_keeper/import_upload)
Companion registration (an import_export companion is called with the admin's context during an export or import)register_companion
Declarative companions (they read entities with templates)add_declarative_companion, update_declarative_companion, delete_declarative_companion

Home Keeper creates a Home Assistant device for each appliance and removes it with the appliance. Home Assistant reserves device registry changes for admins, so this is a second reason that appliance changes are admin-only.

Any signed-in user can read the device registry, which shows the name, make, model and area of each appliance. For this reason, Home Keeper keeps the serial number only in the appliance record and does not copy it to the device.

A websocket command and its service twin share one authenticated connection. If Home Keeper gates only the websocket command, call_service bypasses the gate. When you add a new admin operation, gate both the websocket command and the service.

Home Keeper trusts calls with no user, such as a scheduled automation, the same way Home Assistant does.

Companion panel tabs​

A companion integration can add a tab to the panel. A tab is JavaScript that runs in the admin panel with the session of the admin. For this reason, only Python code that runs in the Home Assistant process can add a tab, through panel_tabs.async_register_panel_tab. That code already has full access to Home Assistant, so the API adds no new risk.

The home_keeper.register_companion service does not accept a tab. That service is admin-only. An integration calls it from its own setup, which has no user.

Home Keeper accepts only a same-origin module path for a tab, with no scheme and no .. segment. The home_keeper/get_panel_tabs websocket command is admin-only, so only an admin sees the tabs of a companion.

Open to any signed-in user​

Any signed-in user can use these surfaces:

  • The to-do list, the calendar, and the per-task device-page entities.
  • The dashboard task card, with its document and product links.
  • The Home Keeper panel: the Tasks tab, and a read view of the appliances.
  • Create, edit, delete, complete, snooze and skip tasks.
  • Add, remove and reorder the photos of a task, from the panel or the card. A photo is task data, so it follows the task.
  • Read tasks and profiles.
  • Read the full record of each appliance, with its parts, documents, costs and serial numbers (home_keeper/get_assets and home_keeper.list_assets).
  • Read the spend and purchase totals, from the cost sensors and from home_keeper/get_spend. They add up the same costs that the 2 reads above give.

Notifications​

Home Keeper delivers only to 2 targets: companion-app notify services (notify.mobile_app_*) and persistent_notification.

Home Keeper rejects any other target. A saved notification with another target is dropped, with a warning in the log. A call to home_keeper.notify with another target fails.

This stops Home Keeper from relaying text through a channel the caller cannot reach directly, such as an email or chat integration an admin configured. persistent_notification is allowed because it never leaves the instance.

Home Keeper serves uploaded manuals, receipts and photos through an authenticated Home Assistant view.

To open a file, the panel creates a signed URL. The signed URL lasts 1 hour for the panel, and 15 minutes for the sign_document_url, sign_part_file_url and sign_task_photo_url services. A service result can leave the panel, so it gets the shorter lifetime.

A signed URL is a bearer credential. Anyone who has the link can get the file until it expires, without a login. A screenshot with a signed URL needs the same care as the file itself.

Home Assistant accepts a signature on GET and HEAD requests only. The upload endpoints also require a real authenticated user, so a link that can read a file can never replace it.

A signed URL is not admin-only. The card needs one to open a document or a photo on a task that any user can complete.

Home Keeper accepts one consequence: a non-admin user who guesses an appliance id and a document id learns whether that pair exists, from whether the request succeeds. The same applies to a task id and a photo id.

Home Keeper reads the whole image of a task photo to make its thumbnail. It refuses a file that is not a readable PNG, JPEG, WebP or GIF image.

The pixel limit is 50 million. A baseline RGB or greyscale JPEG is decoded at 1/8 of its size or less, so it gets the higher limit of Pillow itself: about 179 million. That limit is shared by all of Home Assistant, and Home Keeper leaves it as it is.

Home Assistant serves only the 2 built JavaScript bundles as a static path. Home Assistant serves static paths before authentication, so Home Keeper does not mount the panel's source tree or its dependencies.

Home Keeper escapes every URL it renders as a link, and it also checks that the URL scheme is safe, because an escaped javascript: link is still a live link. Some links come from other integrations through add_task, so the scheme check runs at render time even if the stored value was already validated.

Limits of this security model​

  • An admin is an admin. Home Keeper does not protect an instance from its own admins. Anyone who can read the Home Assistant configuration directory can read the integration's data.
  • Home Assistant's own authentication is the security perimeter. This page does not help if an account is shared or a long-lived token leaks.
  • A non-admin user can create and complete tasks. Home Keeper has no read-only user. Use Home Assistant's own user model for that.
  • Any user can read all appliance data. Home Keeper has no private appliance field.
  • Any user can fill the disk with photos. A task holds up to 6 photos of up to 25 MB each, and any user can create tasks. Home Keeper has no quota for each user.

Report a problem​

Open an issue at github.com/prestomation/ha-home-keeper/issues.

For a problem you do not want to post publicly, use GitHub's private vulnerability reporting on the same repository.