Security checklist
Work through this list before a Bookclerk server can be reached from any computer but its own. Each item links to the page that explains it.
Important
Found a vulnerability? Report it privately, as the security policy describes.
master.key in the files directory seals every secret Bookclerk stores:
store sign-ins, the operator token and plugin secrets.
- Set
BOOKCLERK_AUTH_PASSWORD(or[auth].password) so the key is wrapped at rest. - To wrap a key that already exists, run
bookclerk config master-key wrap. - On a machine with an OS keychain, keep the key there instead:
bookclerk config master-key move keychain.master.keythen only names the keychain item, so a copy of the files directory doesn't carry the key. The desktop window does this by default. - On a Linux server with systemd 256 or later, seal it to the machine
(its TPM when it has one) with
key_store = "systemd-creds"; see Running Bookclerk → Sealing the key with systemd-creds.
Warning
Back up the key together with the database: a copy of master.key, or
for a key in the keychain or sealed with systemd-creds a recovery copy from
bookclerk config master-key export or Settings → Server Settings.
Without the key, sealed values cannot be read.
Details: Database and Configuration → Bootstrap files.
The operator token is the key to the server itself.
- Show it with
bookclerk daemon token. - Replace it with
bookclerk daemon token rotate.
Once an Owner exists, the web sign-in no longer accepts the token. Owners use elevation instead. Details: Operations.
- Enter store passwords in Accounts.
- Set plugin secrets with
bookclerk plugins config set --secret, which reads the value from stdin.
Logs and diagnostics reports redact every registered secret. An upload is abandoned if a secret would remain in it. Details: Diagnostics.
By default the daemon listens on loopback only (127.0.0.1:8787 and
[::1]:8787). Before you change daemon.listen:
- Put a reverse proxy that terminates TLS in front of Bookclerk.
- Set
integrations.public_originto the proxy'shttps://address. Session cookies are thenSecure, and sign-in links use that address. - List the proxy in
daemon.trusted_proxies. Otherwise Bookclerk ignores forwarded headers, and sign-in throttling sees only the proxy's address. Behind several proxies, list them all: throttling uses the rightmost forwarded address that isn't a listed proxy, so a client can't pick its own key by sending a forgedX-Forwarded-For.
Details: Operations → Reverse proxy.
Hosts of one library talk to each other over TLS, except on loopback. Details: Libraries and branches.
A person who joins a branch may bring their store connections. Only stores
that declare their sign-in shareable travel, and the user must tick the
box for it on the library. The library seals the accounts' secrets to the
joining branch's own box key, so the code, the browser and any proxy on
the way never see them. The branch re-seals each secret with its own
master.key before it writes it. Neither side logs the values, and the
library audits what it sent, without them. Each operator can stop a
member from connecting store accounts on their server. A branch's person
can later add connections to a library over the branch's link; that bundle
is sealed to the library's per-connection box key, so it opens only on
that connection, and the library keeps it only for the user who let the
branch join. Details:
Store connections that follow the person.
The web app is served with a Content-Security-Policy. Pages run only
Bookclerk's own scripts, load images only from Bookclerk, talk only to
Bookclerk, and can't be framed by another site. Covers, store icons and
profile pictures are downloaded by Bookclerk and served from its own
address (How covers are served).
If your proxy adds its own Content-Security-Policy header, it must still
allow Bookclerk's own scripts, images and connections. A stricter header,
such as script-src 'none', stops the app from loading.
Every response from Bookclerk, the web app, the API, covers and error pages alike, tells browsers that it belongs to Bookclerk alone:
- Other sites can't show Bookclerk's covers, scripts or files in their pages
(
Cross-Origin-Resource-Policy: same-origin). - Scripts on other sites can't read Bookclerk's answers: no response carries
an
Access-Control-Allow-Originheader, so browsers refuse the read. - The app runs in its own browser process, apart from any page that opens it
or that it opens (
Cross-Origin-Opener-Policy: same-originandCross-Origin-Embedder-Policy: require-corp). - No site can frame it (
X-Frame-Options: DENY), and browsers keep to the declared content type (X-Content-Type-Options: nosniff).
These headers bind browsers only. The CLI, other hosts of your library and integrations that call the API from their own servers are unaffected.
Note
A proxy that adds Access-Control-Allow-Origin, or loosens
Cross-Origin-Resource-Policy, opens your library to other sites. Leave
these headers as Bookclerk sends them.
- Ask for a second factor on password sign-ins: Settings → Sign-in,
the
require_second_factorpolicy. Passkeys and single sign-on are other strong options. Details: Sign-in. - Give people the lowest role that works. Only Owners and the operator manage sign-in options and other Administrators. See Sharing with your household.
Leave plugins.isolation and media.isolation at "required", the
default:
- Every plugin runs in its own jail.
- Untrusted audio is decoded only by the confined media worker.
- When either helper is missing, Bookclerk refuses the work instead of running it unconfined.
Details: Managing plugins → Isolation modes and Media worker.
A plugin reaches only the web addresses and network ranges its approved grant names. If it later asks for more (a new version, or a changed manifest), it stops running until you approve it again. Details: Capabilities and consent.
Plugin requests identify as bookclerk/<version> (+https://bookclerk.app).
A plugin that follows a store's app API can ask to send its own
User-Agent to that store's hosts; the consent form lists those hosts and
the plugin's reason, and you can refuse each one. See
User-Agent.
Install only the plugins you use, and undeploy the rest.
Keep recovery points, and a copy of master.key (or a recovery copy of a
key in the keychain), somewhere other than the server. See Backups, updates, import and export.
- Running Bookclerk: run the server as a service.
- Sign-in: passkeys, single sign-on and second factors.
- Backups, updates, import and export: recovery points.
Source: docs/server/security.md at main · View as Markdown