# 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](/security.md) describes.

## Keys and secrets

### Wrap `master.key` with a password

`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.key` then 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](/docs/server/operations/index.md#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](/docs/server/database/index.md) and
[Configuration → Bootstrap files](/docs/server/configuration/index.md#bootstrap-files).

### Guard the operator token

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](/docs/server/operations/index.md#daemon-bookclerkd).

### Keep secrets off the command line

- 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](/docs/server/diagnostics/index.md#redaction--privacy).

## Network

### Put a TLS proxy in front first

By default the daemon listens on loopback only (`127.0.0.1:8787` and
`[::1]:8787`). Before you change `daemon.listen`:

1. Put a reverse proxy that terminates TLS in front of Bookclerk.
2. Set `integrations.public_origin` to the proxy's `https://` address.
   Session cookies are then `Secure`, and sign-in links use that address.
3. 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 forged `X-Forwarded-For`.

Details: [Operations → Reverse proxy](/docs/server/operations/index.md#reverse-proxy--tls).

### Branches talk over TLS

Hosts of one library talk to each other over TLS, except on loopback.
Details: [Libraries and branches](/docs/server/branches/index.md).

### Store connections a branch receives

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](/docs/server/branches/index.md#store-connections-that-follow-the-person).

### Leave the web app's policy in place

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](/docs/server/integrations/index.md#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.

### Other sites can't use Bookclerk's responses

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-Origin` header, 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-origin` and
  `Cross-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.

## Sign-in

- **Ask for a second factor** on password sign-ins: **Settings → Sign-in**,
  the `require_second_factor` policy. Passkeys and single sign-on are
  other strong options. Details: [Sign-in](/docs/server/sign-in/index.md).
- **Give people the lowest role that works.** Only Owners and the operator
  manage sign-in options and other Administrators. See
  [Sharing with your household](/docs/guide/sharing/index.md).

## Plugins and media

### Keep isolation required

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](/docs/server/plugins/index.md#isolation-modes)
and [Media worker](/docs/server/media/index.md).

### Read what a plugin asks for

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](/docs/plugins/capabilities/index.md).

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](/docs/plugins/capabilities/index.md#user-agent).

Install only the plugins you use, and undeploy the rest.

## Backups

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](/docs/server/backups/index.md).

## Next steps

- [Running Bookclerk](/docs/server/operations/index.md): run the server as a service.
- [Sign-in](/docs/server/sign-in/index.md): passkeys, single sign-on and second factors.
- [Backups, updates, import and export](/docs/server/backups/index.md): recovery points.
