HealthLog/docs/self-hosting/account-sharing.md

Sharing a health record with another account

Two accounts on the same instance can be connected so that one of them can open the other's health record. A parent and an adult child, two partners, somebody keeping an eye on a relative's blood pressure — the case this exists for is a household, not an organisation.

This page describes what that connection does, what it deliberately does not do, and which of the instance's existing trust properties it leaves exactly as they were.

The shape of it

One account shares; the other is given access. In the code and in the settings copy these are the owner and the person they invited.

• The owner opens Settings → Shared access and invites somebody by the username or e-mail address that person signs in with. They need an account on this instance already; there is no invite-by-e-mail flow.
• The invitation confers nothing. Until the other person accepts it, it is an offer sitting in their own settings. Being handed read access to somebody's health record is not something the product imposes silently, and the acceptance — with its timestamp and the accepting IP — is what the row records.
• Once accepted, the record shows up in that person's user menu under "Open a record". Opening it reloads the app into the owner's record.
• A banner across the top of every page names whose record is open and says it is read-only, with a button back to the person's own. It is loud on purpose: somebody who forgets they are switched will log their own reading into another person's record, and there is no undo for an entry that was never theirs.
• Either side can end it at any time. The owner withdraws access; the other person hands it back. Both are one click with no second factor and no typed confirmation — reducing access must never be harder than granting it was.

What the other person can and cannot do

Read the health record. Measurements, medications, mood, labs, the illness journal, preventive-care reminders, documents. In this release that is the whole of it: every grant is read-only. The write level exists in the data model so that adding it later is enforcement work rather than a migration, and no invitation can create one today.

Nothing about the account around the record. This is the line the whole feature is built on, and it is drawn on the server:

Not reachable	Why it would matter
Password, passkeys, second factor, recovery codes	Silent takeover, surviving any revocation
Sessions, trusted devices, sign-out-everywhere	Ending or enumerating the owner's logins
API tokens, the MCP connector	A durable credential that outlives the access
Connected services (Withings, Fitbit, WHOOP, Google Health, Polar, Oura, Strava, Nightscout)	Re-pointing a sync, or feeding somebody else's wearable into this record
Notification channels and push devices	The owner's health alerts redirected to another phone or chat
Exports, the health-record archive, clinician share links	A one-click copy of everything, or a new door that outlives the access
Insights and the Coach	AI processing of the owner's data, under the owner's own consent
Sharing itself	Inviting somebody else, widening the access, or passing it on
Locale, theme, dashboard layout	Presentation belongs to the person, not to the record

The last two rows are worth a sentence each. Sharing is not transferable: somebody given access cannot invite a third person, cannot raise their own level, and cannot hand it on. And display preferences stay with the person at the keyboard, so reading somebody else's record does not change your own theme, language or dashboard.

The AI row is the one that looks arbitrary and is not. Server-managed AI features send the record's data to a provider under a consent the record's OWNER gave, for their own use. Somebody else triggering that would create a consent-shaped act the owner never made, so those surfaces stay owner-only.

These are not checks that a page forgot to render. Every route in the product refuses by default while a browser is acting on another account; a route becomes reachable only by declaring it, and the set of declared routes is frozen by a test.

Revocation, and what it cannot undo

Ending access takes effect on the other person's next request, not at their next login. The grant is checked against the database on every single request, so there is no cached verdict to wait out. If their browser is sitting inside the record when the owner ends it, the same database transaction puts that browser back into its own account — they land at home rather than on a wall of refusals.

What revocation cannot do is take back what was already seen. A person who had read access could have read, remembered, screenshotted or written down anything in the record. The product can close the door; it cannot reach through it. Nothing in the interface implies otherwise, and neither does this page.

Ending access never deletes the record of it. The row stays with the dates and with who ended it, because "who had access, from when to when, and who ended it" is a question a deleted row cannot answer. Re-inviting the same person creates a new row beside the old one.

Seeing what happened

Settings → Shared access answers three questions for the owner, at any time: who can open this record, since when, and when they last did. Below that, a list of the days somebody else opened it and how many times — one line per person per day, rather than a line per request.

That list is bounded by the instance's audit retention, and the page says so with the actual number rather than a hardcoded one. The default is 365 days (AUDIT_LOG_RETENTION_DAYS); an operator who shortens it shortens this view too, and the sentence under the heading changes to match. An empty list means nobody opened the record within that window — not that nobody ever did.

What this does not change about the instance

Stated plainly, because a sharing feature is exactly the moment somebody re-reads the trust model:

• The operator could always read the database. Anyone with server or database access, and anyone with an admin account on this instance, can reach health data directly. That was true before sharing existed and is unchanged by it. On a household instance the operator is usually one of the people using it; on an instance hosting other people, it is worth saying out loud.
• Encryption at rest is instance-keyed, not per-user. The encrypted columns are protected by the key in ENCRYPTION_KEYS, which belongs to the instance. Sharing does not weaken that, and it never did protect one account's data from the operator of the same instance.
• AI processing stays under the record owner's consent, because the AI surfaces are not part of what sharing covers.

For operators

Nothing to configure. Sharing is available on every instance, needs no environment variable, and does nothing until one account invites another.

Two operational notes:

• Invitations disclose whether a username exists. An invitation to a name nobody uses is refused with "no account with that name". That is deliberate: the alternative is a silent pending row that will never be accepted because the owner mistyped. The caller is already authenticated and the endpoint allows ten invitations an hour per account, which bounds how fast the surface could be walked.
• Deleting an account removes the grants it is party to. The audit rows naming that account as the one who opened somebody's record stay, and render as "a deleted account" — nulling them would turn "your daughter opened your record" into "you opened your record", which is worse than an unresolvable id.