Household identity & invitations

Status: Accepted · Audience: Both · Area: D — Content & household

---

Purpose

Get everyone else in the home an account, without the operator learning Jellyfin’s user administration.

Adding a household member currently means: open Jellyfin, find user management, create a user, set a password, decide library access and parental limits, then tell the person their credentials over a messaging app — which is both awkward and a poor way to handle a password.

The operator does this a handful of times, always from a cold start, always having forgotten where the settings are.

Behaviour

One account per person, covering everything

A household member’s Jellyfin account is their identity for both watching (Jellyfin) and requesting (Seerr, authenticating against it). One credential, created once.

Invitations rather than credential handover

The operator creates an invitation; the household member sets their own password.

$ lemonfiber invite ana
  ✓ ana can sign in — unclaimed until she sets a password, and expires in 48 hours

  Send this:
  http://192.168.1.20:8096

  [QR code]

  Tell her to sign in as `ana`. She will be asked to set a password.
  If she would rather not, she can decline it here:
  http://192.168.1.20:8097/decline/7f3c9a

Both addresses are answered by the stack, never by a process that lives only as long as an operator’s session. lemonfiber ui keeps nothing running once the operator closes it (G1-R5), so an invitation that only worked while it did would stop working the moment the operator went to bed. What matters is how long the process lives, not who built it: the decline page is served by a lemonfiber-built image that the stack runs under its restart policy (ADR-0029). Accepting is a state Jellyfin holds: the account is there, unclaimed, until somebody sets its password. Declining is a page, and the stack serves it from a service it keeps running under its restart policy, beside the household front door and at the same binding tier (C6), which is where the invitee already is. The front door itself is Seerr or Jellyfin, and lemonfiber adds no route to either.

A refusal is the invitation’s standing. The page declines the one invitation its address names and nothing else. The service answering it disables the account at once, so it can no longer be signed in to or claimed, and keeps the refusal until the core next reads the household, which reports the invitation as declined rather than expired. A declined account is kept, disabled, until the operator removes it or re-issues the invitation: it is not swept when 48 hours pass, because a refusal is something the operator should see before it goes.

The sign-in address is Jellyfin’s, which is not always the front door. Setting a first password happens in Jellyfin, and Seerr authenticates against Jellyfin rather than holding credentials of its own — so an account with no password yet cannot be claimed through Seerr, whichever service G5 picks as the door. What G5-R14 is for still holds, and is what the operator experiences: one address, chosen by lemonfiber, rather than four to choose between. After the account is claimed, the household member uses the front door like everyone else.

What invite does is create the account (D6-R12 says so plainly — an invitation issued while Seerr is down still creates it), leave it without a password, and record that it is unclaimed. The address is the same one the household is given for everything else.

That is also what makes it single-use and expiring in the way D6-R3 asks (D6-R4 covers the QR). It is claimed once, because setting a password is something that happens once and cannot be undone by a second arrival; and it expires because an account nobody claimed within 48 hours is removed rather than left standing as a way in that nobody is watching.

The stack takes an invitation back when its window closes, whether or not a lemonfiber process is running, because a way in that waits for the operator’s next command stands open for as long as the operator is away. The decline service checks once a minute. An account nobody was ever seen in is removed; one somebody has been in, which is a reset nobody took up, is switched off and kept, because it holds what they watched. It removes an account only where a read made just before the removal shows the account is the one the invitation names, under the same issue time, with no password, no administrator’s rights and nobody ever seen in it; anything else, or a read that does not answer, switches it off or leaves it as it is. The core reports an invitation taken back either way as expired, and never as an account that went missing (ADR-0029 §2a).

An invitation also opens the app. Beside the address somebody signs in at, the core mints a join link: the companion’s own address for this invitation, in the app’s own scheme, lemonfiber://join. It carries what the app needs to reach the house and know it — the address pairing material names, the fingerprint of the certificate that address presents, and the stack’s identifier — with the name the person signs in as, when the link stops being good, and a claim token. A phone that opens it adds the house, asks the person to choose a password, and lands them on Home (N3, N3-R26).

The claim token is the invitation in the app’s hands. It lets the person set their first password through the core, once, within the invitation’s window, acting as their own account at the media server and never as the administrator. The core keeps it only as a hash on the offer, as it keeps the decline token, so a copy of the record claims nothing, and every new offer or reissue mints a new one. Somebody already in the house is given a link with no claim token: it adds the house to their phone, and they sign in with the password they have.

The link is the app’s own scheme rather than a web address on the house, because a house on the home network has no public name and no publicly trusted certificate, and a phone opens a web address in an app only for names fixed when the app was built and checked over the internet. A scheme opens on any network, with nothing reached first. On a phone without the app it opens nothing, which is why the invitation still carries the address somebody signs in at in a browser.

Where the web surface has not been served encrypted on the network, the core has no address a phone could pin, so the invitation is made all the same, without a join link, and says why. It never composes an address to fill the gap.

The operator never chooses or transmits someone else’s password.

The QR code matters more than it looks: the recipient is usually holding the phone they’ll watch on, and typing a LAN URL and credentials on a phone keyboard is exactly the friction that makes people give up.

Access is decided at invitation, in plain terms

Which libraries, and any age limit (D8) — asked as “what should Ana be able to see?”, not as a permissions matrix.

Household members are listed and manageable in one place

Who exists, what they can access, when they last watched, and what they’ve requested — without opening two web UIs.

Removal is complete and honest

Removing someone revokes access to both Jellyfin and Seerr, and states what happens to their watch history and outstanding requests. Partial removal — no longer able to watch but requests still arriving — is a confusing state to leave behind.

What the removal says about watch history is part of its machine-readable answer, beside the requests it counts, so a surface that is not the terminal states it in the stack’s words rather than its own (D6-R18). And the yes to a removal is the offer its reading answered, not a bare confirmation: reading what removing somebody costs and agreeing to it are two requests, and between them a request can be made or an account can change. The removal builds the offer again from what the services hold when it runs and refuses by name where anything moved, so a yes agrees to the cost that was read (D6-R17).

LAN-only, and said plainly

Household access works on the home network. Watching from elsewhere is not supported in 1.0 (B7 deferred), and the invitation states this rather than letting someone discover it at a friend’s house.

On the companion

Access is decided at invitation, in plain terms becomes several requirements, because an invitation sent from a phone is the one most likely to be sent without its terms being read (N9). N9-R5 requires an invitation to state what it grants — libraries, filtering, unrated material, and whether requests may be made — before it is sent, and N9-R6 requires it to state when it lapses.

Afterwards, N9-R7 requires two outcomes kept apart: lapsed unaccepted, and declined by the invitee (D6-R16). From the operator’s end they look identical — nobody arrived — and each has a different next move, which is the argument D9 makes about content that never appeared, applied to people.

LAN-only, and said plainly becomes N9-R9: where something works only on the household network, the app says so. That matters more here than anywhere else, because the app is the thing most likely to be held at a friend’s house.

Removal is complete and honest is where rounding does the most damage. N13-R1 requires how far a revocation reached shown as everywhere, media-server-only or nothing, and N13-R2 forbids rendering the middle one as complete (N13). That middle state is precisely the one this feature refuses to leave behind — and flattening it into removed is how it gets left behind anyway. N13-R19 carries D6-R9 to the phone: what removal does to watch history and to requests is stated before it is agreed to, with every finding in the stack’s words.

A member’s name, and a member who is nobody in particular

A member’s session is answered with the member’s display name as the media server holds it, so a surface can greet them without asking. The operator can also be answered with what a member invited with the household’s defaults would be told and could watch — the household’s default access and allowance, read for nobody — so the member’s side can be seen without reading any member’s requests or watch history.

States

Per household member:

Edge cases

Acceptance criteria

Related

• D4 Household request flow — what the account is for
• D7 Approval & quotas · D8 Parental controls
• D1 Service auto-wiring — the identity connection
• G6 Client apps — getting them watching
• C6 Web security — the binding tier they reach