ADR: Patron scopes and linked sign-in
- Status: Accepted
- Date: 2026-11-17
- Related: First-party identity, Plugin-provided OIDC clients, Metadata claims and file sync
Every Member sees the whole library. A household with children, or a library shared with friends, has no way to show one person only part of it.
Audiobookshelf already solves this, and many people run it beside
Bookclerk. Each Audiobookshelf user has a type (root, admin, user or
guest) and, below admin, a set of permissions: which libraries they can
open, an allow or deny list of tags, whether they see explicit content,
and whether they can download, upload, edit or delete.
The two servers can be linked in either direction:
- Bookclerk relies on Audiobookshelf. The Audiobookshelf plugin signs people in to Bookclerk with their Audiobookshelf credentials, and mints claim tickets for new Audiobookshelf users.
- Audiobookshelf relies on Bookclerk. Audiobookshelf's OpenID login
uses Bookclerk as its provider, through the plugin's
audiobookshelfclient.
Today neither direction carries permissions or suspension. Any Audiobookshelf user, a guest or a child restricted to one library included, can claim a ticket that opens the whole Bookclerk library. A patron disabled in Bookclerk stays signed in to Audiobookshelf, because Audiobookshelf's own session outlives the provider.
Audiobookshelf's OpenID login, as of its current source, already reads
two claims when they are configured: a group claim that sets the user's
type, and an advanced permissions claim (allowedLibraries,
allowedTags, tagsAreDenylist, canAccessExplicitContent,
canDownload, canUpload, canUpdate, canDelete,
canCreateEReader). It applies them at every login. It ignores the
permissions claim for admin and root users, refuses to change a
root user's type, and checks isActive on every token.
A Member has a scope: which part of the library they see and what they may do with it. Owners and Administrators are never scoped.
| Field | Meaning |
|---|---|
| Rules | Which books are visible: a list of rules, each a field, a value, and include or exclude |
| Explicit content | Whether editions marked explicit are visible. Store listings carry an is_explicit flag from storefront metadata (and sidecars, once file claims reach the library); the Library hides a work when any of its listings is marked explicit. |
| Member controls | What the Member may do, one switch each (see Member controls) |
A rule's field is one of collection, tag, genre, series, author or
narrator, and it matches one value of that field: "genre Kids", "series
Discworld", "author X". A collection is a named part of the library,
defined by storage key prefixes (for example kids/). A tag is a
free-form label an Administrator sets on a work, or one read from a
sidecar file. With no include rules every book passes; with any, a book
must match at least one. An exclude rule always wins over an include.
Collections cover files. A book held only through a store account has no storage key until it is downloaded, so it belongs to no collection. A collection-scoped Member sees the downloaded books inside their collections. A Member always sees, and can open, every book they own through their own store accounts, whatever their scope says.
Rules on metadata fields and the explicit content rule also filter books the library does not hold, by their metadata: Discover shelves and storefront search results show a scoped Member only what their scope allows.
The scope is enforced by one filter in the host's library queries, not by a check per screen. It applies to the Library, search, facets and book pages (covers included), Discover and the Wishlist, file download and streaming, library cards and the clerk socket, and listening progress. It runs on the library that holds the books, so a clerk or a window only ever learns of the books the patron may see.
Existing patrons are unrestricted when scopes ship. New patrons get the library's default scope, which an Administrator sets; out of the box it has no rules and allows explicit content, because explicit flags will be incomplete at first.
Beside the rules, six switches say what a Member may do. Each is on out of the box except Upload, which stays off until an Administrator turns it on.
| Control | Turning it off stops |
|---|---|
| Link store accounts | Connecting a store account, signing in to one again, and bringing accounts from another library. Accounts already connected keep working, and an Administrator can still remove them. |
| Download | Taking copies of the library's files: downloads to a branch or clerk, an app's offline downloads, and library-card sync. Listening by streaming is not a copy and stays allowed (playback ADR) |
| Edit metadata | Changing book metadata. Patrons can't change metadata yet, so this switch is stored but does not restrict anything until they can. |
| Upload | Adding books by uploading files, folders or archives (uploads). Off by default. |
| Request books | Asking a branch for a book it listed (interlibrary requests) |
| See prices | Prices and store links in Discover, catalog search and the Wishlist; the library drops them from its answers, so the patron's browser never receives them, and the app builds no store links of its own |
The library has a default for every switch, which an Administrator sets, and an Administrator can set single switches for one Member. A switch set for one Member overrides only that switch; the others keep following the default, so a later change of the default still reaches them. This differs from the rules, where a Member's own rules replace the default rules as a whole. A disabled user may do none of it.
An Owner or the operator can also set single switches for an Administrator (an Administrator manages Members alone, so never another Administrator's switches). The default is for patrons: it never limits an Administrator, whom only the switches set for them alone limit. Owners are never limited.
"Link store accounts" replaces the earlier per-member rule "may connect store accounts here". Like that rule it is checked again inside each account's import batch, so turning it off stops a join that is still adding accounts.
An Owner or the operator also keeps control over what an Administrator
may do, with seven switches: manage members, set patron limits,
library-wide scan and acquire, run the job queue, fix the catalog,
invite branches, and approve interlibrary requests. Each has a library
default (the core.admin_controls configuration document) and a
per-Administrator override in the same shape as the member controls. All
are on by default, an Administrator can read but never change their own,
and Owners are never limited. Because a library tag can decide what a
scoped patron sees, setting tags, and defining collections, falls under "set patron limits". A route
a switch guards answers 403 when
it is off; with library-wide scan off, an Administrator scans and
acquires like a Member, with only their own accounts.
A person linked between Bookclerk and another server has one authority: the side their account came from. The authority's scope and suspension are copied to the other side, which enforces them. Bookclerk never writes back to its own authority. When a person is linked in both directions, the side the account was created on stays the authority, and an Administrator can switch it.
- The other server is the authority. Its plugin translates the person's permissions into a scope at each sign-in and each user poll. The host stores it on the patron as managed, so it can't be edited in Bookclerk. When the person is disabled, locked or loses every mapped library there, the host disables the patron, which ends their sessions and library cards. A guest account there is never admitted.
- Bookclerk is the authority. When Bookclerk's provider issues a token
to a plugin's client, the plugin adds the claims its server reads (for
Audiobookshelf, the group and advanced permissions claims). Owners and
Administrators map to
admin, Members touser. The plugin also pushes scope changes and suspensions to the server's API at once, so they don't wait for the next login. The token endpoint already refuses a disabled patron.
Audiobookshelf's permissions hold less than a scope: a list of
libraries, one list of tags that either allows or denies, and the
explicit switch. From Audiobookshelf to Bookclerk nothing is lost:
libraries become collection includes and the tag list becomes tag
includes or excludes. From Bookclerk to Audiobookshelf, collection rules
become the library list, and the plugin expresses the rest with tags of
its own: for each distinct scope it computes the books that pass and
keeps a bookclerk:scope-<id> tag on exactly those Audiobookshelf items,
then gives the person an allow list of that one tag. It updates the tags
when a scope changes and when items are added or their metadata
changes. Tags Audiobookshelf users set themselves are left alone.
The claim formats belong to the other server, so plugins build them; the
host only stores scopes and asks for claims. The plugin interface grows
by appending to plugin.capnp: a user report carries a scope and a
status (new, changed or withdrawn), and an OpenID client template can
declare extra claims that the plugin fills at token time.
The Audiobookshelf plugin replaces its single library_id setting with a
table of mappings: an Audiobookshelf library and folder, the Bookclerk
storage key prefix it shows, and the Bookclerk collection it corresponds
to. Keying on the storage key, rather than Bookclerk's own path, lets the
two servers mount the same files at different paths. There is no
migration from library_id; there has been no release.
- Patron scopes are a host feature with uses beyond Audiobookshelf: Plex, Jellyfin or any OpenID client can carry the same scope.
- Every library query takes the scope filter, so a new screen that forgets it shows too much. The filter lives in one place, and tests check each screen against a scoped Member.
- When Bookclerk is the authority, the Audiobookshelf plugin writes its own tags onto Audiobookshelf items, so its API key needs permission to update items, and those tags are visible to Audiobookshelf admins.
- A scope can't restrict an Audiobookshelf admin, and linking
Audiobookshelf's
rootaccount to a Bookclerk Member would deny that login. The plugin warns before such a link. - A suspension made in Audiobookshelf reaches Bookclerk at the next user poll, which the live channel usually makes a matter of seconds.
- Settings gain a
tabletype for the mappings. Rows are records on the wire and in storage, typed per SDK, so adding a column keeps old rows working; the CLI also takes a row in column order.
Source: docs/adr/patron-scopes.md at main · View as Markdown