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.
| Operation | Services |
|---|---|
| Create, edit, delete, archive and restore appliances | add_asset, update_asset, update_managed_asset, delete_asset, archive_asset, restore_asset |
| Appliance documents and part files | add_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 history | delete_archived_completion |
| Delete every orphaned task (a task whose managing integration is not loaded) | delete_orphaned_tasks |
| Spare-part stock adjustments | adjust_part_stock |
| Settings, profiles and notification delivery | set_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_assetsandhome_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.
Files and links
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.