Users, roles & libraries

Tome is built around a three-tier role model — admin, member, guest — combined with a library-membership system that controls who sees which books. The intent: one Tome instance can comfortably serve a solo reader, a family with kids, or a small group of friends with overlapping but not identical libraries.

The three roles

Per-user book visibility

Visibility is enforced on the server. Every list endpoint filters books before returning them, so a guest literally cannot see (or download via OPDS) a private member book — not just "hidden in the UI."

The rules in words

• Admins see everything. No filtering.
• Members see: books uploaded by any admin, books they uploaded themselves, and books in libraries they're explicitly assigned to.
• Guests see: books uploaded by any admin, and books in libraries marked is_public = true.

The dashboard has a "My books / Shared library" toggle for members so they can flip between "only books I uploaded" and "everything I have access to."

Libraries

Libraries are how books get grouped and how visibility gets scoped. Every book belongs to one or more libraries (it's a many-to-many relationship).

• Global libraries (owner_id is null) — typically book-type buckets like "Novels", "Manga", "Comics" that Tome creates automatically when seeding book types.
• User-owned libraries — created by a member or admin, optionally assigned to specific other users.
• Public libraries (is_public = true) — visible to guests.
• Private libraries — only visible to the owner, assigned users, and admins.

Quick Connect

Quick Connect is the way to sign in on a new device — a phone, a tablet, an e-reader — without typing your password into a possibly-untrusted keyboard.

1. On the new device, open Tome and click Use a Quick Connect code.
2. A 6-character code appears (e.g. JX7-Q9P). The code is good for 5 minutes.
3. On a device you're already signed in on, open Settings → Quick Connect, enter the code, and confirm.
4. The new device gets a fresh JWT and signs in. The code is single-use.

Force password change

When an admin creates a new user, they pick a temporary password and Tome flags the user must_change_password. On first login, the user can't access anything until they pick a new password. Reduces the "I sent it in Slack and forgot" risk.

Impersonation

Admins can impersonate any non-admin user from the user management page — useful for "the UI is broken for them, but works for me" debugging. The session banner across the top makes it obvious you're impersonating, and the audit log records both the impersonator and the impersonated account on every action taken.

Setting up a family share — worked example

The most common multi-user setup. Parent is the admin, kids are guests.

1. Sign in as the admin (you).
2. In Users, create one guest account per kid. Tick Must change password on first login.
3. In Libraries, create a "Kids" library, mark it is_public = true. Add the age-appropriate books to it.
4. Your existing library (uploaded by you, the admin) is automatically visible to guests — adult titles will leak in unless you put them in a non-public library. Move anything you don't want kids browsing into a private member-or-admin-only library.
5. Hand each kid their device, get them past the force-password-change screen, and you're done.

Setting up a friend group — worked example

Co-admins, opt-in shared shelves.

1. Make each friend a member, not admin (unless you trust them to manage users).
2. Each member uploads their own books. By default those books are visible only to admins and the uploader — not to other members.
3. For books you want to share, the uploader creates a library, assigns the relevant friends, and adds the book to that library.
4. Each member can browse "All books I have access to" or filter to "Just mine" on the dashboard.