# Libraries and branches

This page is the operator's guide to joining Bookclerk installs together:
letting branches in on a library, joining one from a branch, adding a
branch on the library's own database, and what each side runs and shares.

## Libraries and branches

- A **library** is one library database and the daemons that share it.
- A **branch** is a separate Bookclerk install, with its own database and
  its own operator, that joins a library to do work for it. It runs the
  library's scans and acquires on its own machine and sends the results
  back. A branch never holds the library's database credentials or DEK,
  and it runs one of the library's plugins only after its own operator
  approves it.
- A **shared branch** is the other way to join: an empty install that
  shares the library's database and keys and serves the same library. Its
  operator is the library's operator. See
  [Shared branches](#shared-branches).
- A **clerk** signs in to a library as its person with a **library
  card** and shows that library's books, the person's own marked. It isn't a node: the library
  never sends it work, and it holds no node key. See
  [Library cards](/docs/server/sign-in/index.md#library-cards).

The web UI says *library* and *branch*. The code, the API and the CLI keep
the older names:

| Web UI | Code, API and CLI |
| --- | --- |
| Library | Library (`libraries`) |
| The library's own daemons, shared branches included | Shared nodes (`kind = shared`) |
| Branch | Branch node (`nodes`, `kind = branch`) |
| Remote branch, local branch, shared branch | `relationship` on each node: `remote_branch`, `local_branch` or `shared_branch` |
| Branch invite | Enrollment link |
| "Let new branches join" | `core.branch_enrollment` |

The design record is
[ADR: Control plane](/docs/adr/control-plane/index.md#branch-node-enrollment-and-transport)
(H-4).

## First start

A fresh install, with no Owner or Administrator yet and no library joined,
opens a welcome screen for its operator with two choices:

- **Start a new library**: the usual first run. Settings → User
  management sets up the first Owner, and you carry on from there.
- **Join a library**: the wizard [below](#on-the-branch-join-a-library).
  The install keeps its own operator, its own database and its own
  consent screen, and needs no local users first.

The welcome screen is operator-only, reached the way Settings is (loopback,
the tray, or the operator token). Choosing "Start a new library" closes it
in that browser. Later, **Settings → Library → Join a library** opens the
same wizard.

## On the library: let branches in

1. **Pick a transport.** Branches reach the node API over TLS, except on
   loopback. Set `integrations.public_origin` to the address branches will
   use (the same one people open the library at), and choose a
   `[daemon.node_api]` mode: `acme`, `proxy`, `self_signed`, `tunnel` or
   `loopback`. With an [ingress plugin](/docs/server/ingress/index.md) (`tunnel` mode) the
   plugin reports the address, so `public_origin` can stay unset.
   The modes, their required settings and what each refuses are in
   [Configuration → Branch nodes](/docs/server/configuration/index.md#branch-nodes).
2. **Let new branches join.** **Settings → Branches** (operator or Owner)
   has the switch, on by default, and shows the address to join. In
   `self_signed` mode it also shows the certificate fingerprint that a
   joining operator checks.

> [!IMPORTANT]
> There is no plain-HTTP fallback. A LAN address over plain HTTP gets
> `403 transport_insecure`. In `acme` and `self_signed` mode the TLS
> listener serves the whole web app, not only the node API, because a
> joining branch's user signs in there.

To stop new branches joining from the command line:

```sh
bookclerk config set branch_enrollment.enabled false
```

Turning it off stops new sign-ins and invites. Branches already joined
keep working.

### What a branch is trusted with

A branch's node appears among the nodes (`bookclerk nodes list`,
`kind = branch`), owned by the user who signed in, or the invite's user.
**Trust follows that user's role**:

- A Member's branch receives only jobs whose store accounts
  belong to that user.
- An Administrator's or Owner's branch may receive any job, but takes
  only that user's own work unless the branch's operator turns on
  **Download for other members** for the library (see
  [Work settings on the branch](#work-settings-on-the-branch)).

Revoke a branch at any time from **Settings → Nodes** or with
`bookclerk nodes revoke <node_id>`. Its socket closes with 4403 and it
stops dialing.

### Remote and local branches

Each heartbeat a branch sends carries its own `integrations.public_origin`
when its operator set one. The library keeps it when it is a plain
`http` or `https` origin (no path, query or user) of at most 255 bytes,
and shows it as the branch's `status.public_origin`:

- A branch that reports an address is a **remote branch**: a core branch
  other installs can reach.
- A branch that reports none, or one the library does not keep, is a
  **local branch**.
- The library's own daemons, shared branches included, are **shared
  branches** whatever they report.

**Status**, **Settings → Nodes**, `GET /api/config/nodes` (`relationship`)
and `bookclerk nodes list` show the label. It follows the latest heartbeat,
so a branch that sets or clears its address changes label within one
heartbeat, without joining again. A remote branch and a local branch are
trusted, and work, the same way.

### Branch invites

Joining with a sign-in needs no link. A branch invite is the other way in,
for a branch whose operator can't sign in to the library themselves.

To make one in the web app:

1. Open **Settings → User management**, then a user's actions, then
   **Add a branch**. The operator or an Owner may make one for anyone.
   Every signed-in user also has **Add a branch** in their own menu, for
   a branch of their own.
2. Copy the invite. The dialog shows it **once**, with a countdown to
   expiry (24 hours by default).
3. Hand it to the branch's operator over a private channel.

Below the invite are the user's outstanding invites, each with its expiry
and **Revoke**. Listings never carry a secret.

On the command line, this prints one invite once:

```sh
bookclerk nodes invite --user riley --ttl 24h
```

An Administrator whose **Invite branches** switch an Owner turned off is
refused (`403`); see
[Sharing](/docs/guide/sharing/index.md#limit-what-an-administrator-may-do).

An invite looks like
`<public_origin>/enroll#bcn1.<link_id>.<secret>[.<spki_pin>]`. It is a
single-use secret:

- The secret sits in the URL fragment, so proxies and access logs never
  see it.
- The database keeps only its hash.
- It expires, and it can be revoked.
- The dialog's answer is sent `Cache-Control: no-store`. The invite is
  never kept in stored SPA state or logged, and is dropped when the
  dialog closes.

## On the branch: Join a library

Open **Settings → Library → Join a library**, or the welcome screen.

1. **Address.** Enter the library's address: `https://library.example`,
   or `host:port`, which means `https://`. This daemon, not the browser,
   reads `GET <library>/api/node/v1/info` under the transport policy. That
   gives the library's name, its canonical origin, its transport mode, and
   whether it lets new branches join.
   - If you typed another spelling of the library's address, the wizard
     offers the one it answers to.
   - If the library isn't accepting new branches, the wizard says so and
     stops.
2. **Fingerprint** (self-signed libraries only). The wizard shows the
   fingerprint of the certificate the library presented. Check it matches
   the one on the library's **Settings → Branches** page and tick "It
   matches". The fingerprint is pinned with the link (trust on first use).
   Other modes need the certificate to chain to the public web roots.
3. **Sign in.** Name the branch (the library's users see this name; it
   defaults to this machine's name) and choose **Sign in to <library>**.
   The browser goes to the library, which shows its normal sign-in
   (password, SSO, passkey, MFA) and then asks: "Let **<branch>** join
   **<library>** as yours?" The page says what joining means: the library
   can send that branch work for your accounts, and the branch's operator
   approves each plugin. Choose **Allow** or **Deny**.
4. **Connected.** The library sends the browser back to this install's
   `/join/callback`. The daemon finishes the join and starts the branch's
   connection at once, with no restart. The page shows "Connected to
   <library>" with a link to the
   [plugin requests](#consent-what-the-library-may-run-here).

**I have an invite**, the wizard's second tab, takes a pasted branch
invite instead. The SPA sends it straight to this daemon in a POST body
and keeps nothing. A pinned invite trusts exactly the library's
self-signed key.

### How the sign-in works

The library is already an OAuth authorization server (`/oidc/authorize`).
Joining uses it with one built-in public client, `bookclerk-branch`:

- It is never stored with the registered clients, and that id can't be
  registered.
- Its redirect URI must be a loopback URL (RFC 8252) or an `https://` URL.
- Its only scope is `node:enroll`, and it needs an S256 code challenge.

The exchange runs in five steps:

1. **Start** (`POST /api/config/join/start`, operator only). The joining
   daemon makes the PKCE verifier, the `state`, and the node's Ed25519 and
   X25519 key pairs, and keeps them sealed in a **pending join** for 10
   minutes. It answers only the authorize URL. The redirect URI is this
   install's own `/join/callback`.
2. **Consent** (on the library). `/oidc/authorize` checks the request and
   sends it to the consent page `/join/approve`. A malformed request is
   refused there and never redirected. Allowing checks that the signed-in
   user is active, that new branches may join, and that the connection
   passes the transport policy. Then it issues a single-use code that
   lives 60 seconds.
3. **Callback** (`POST /api/config/join/callback`). The SPA relays `code`
   and `state` to its own daemon. The daemon takes the pending join for
   that `state` (once) and redeems the code with the verifier only it
   holds. The code alone is useless, so no enrollment secret passes
   through the SPA.
4. **Redeem** (`POST <library>/api/node/v1/enroll/oauth`). The library
   consumes the code and checks its client, redirect URI, scope and
   verifier. It checks again that new branches may join and the user is
   active. Then it runs the **same canonical redeem batch** as an invite:
   one `nodes` row (`kind = branch`, owned by the signed-in user),
   `node_credentials` and a receipt.
5. **Done.** The daemon checks that the answer names the library it read.
   It seals both private keys into its `encrypted_secrets`, records the
   link in `library_links`, and starts the link's client. A library card
   this install held for the library is signed out, as with
   `POST /api/config/clerk/sign-out`: the branch replaces it. The answer's
   `replaced_card.card_removed` says whether the card is gone here (if not,
   it stays under Library cards and the branch join still stands), and
   `replaced_card.library_signed_out` whether the library ended the card's
   session too. An invite join does the same.

`POST /api/config/join/start` `{ from_card }` (a library id instead of
`address` and `fingerprint`) joins a library this install holds an active
card for. The address and pinned certificate come from the card, and the
branch name defaults to the card's name. The library must still answer
with the same library id (409 `origin_mismatch`) and certificate (409
`fingerprint_unconfirmed`). It can't be a shared branch join (400
`invalid_request`), and a library with no such card answers 404
`not_found`. In the web app this is **Make this server a branch** beside
a card in Settings → Library → **Library cards**.

A clerk's library card uses the same authorization server with a
second built-in public client, `bookclerk-clerk` (scope
`library:member`). Its code is redeemed at `POST /api/clerk/v1/token`
for a session token, not at the node API, and no node row is made. See
[Library cards](/docs/server/sign-in/index.md#library-cards).

### Store connections that follow the person

On the consent page the user may tick **Bring my store connections to this
branch** (off by default). The page lists the user's connected store
accounts and which of them would travel.

- **What travels.** The user's own connected store accounts whose
  storefront declares `credentials = "shareable"` in every `plugin.toml`
  the library knows for it, discovered or installed (see
  [`credentials`](/docs/plugins/manifest/index.md#credentials-storefronts)), and
  those of a single-keeper store, such as Audible, that no other branch
  keeps yet. The branch then keeps that account fresh for the library
  (see [One refresh keeper](#one-refresh-keeper)). At most 64 accounts go
  with one join.
- **How.** The choice is kept on the enrollment link. The redeem answer
  carries the accounts and their secrets as one bundle sealed to the
  branch's X25519 box key (the same sealed box as the bootstrap for a shared branch,
  with its own associated-data domain). A retried redeem answers it
  again, but only while the user is still active and the branch has not
  been revoked. The library records each account as sent to that node in
  `account_shares` and audits `branch_connections_sent` (without the
  secrets). A bundle that can't be made is logged and left out: the
  branch still joins.
- **On the branch.** The daemon opens and checks the bundle, then keeps
  each account for the Owner who signed in to run the join, or else the
  branch's single active Owner. Each account is one atomic batch: the
  account row, its secrets re-sealed with the branch's own key, the link
  to the person, and a `received` row in `account_shares`. An account
  the person already has there keeps its own credentials but still gets
  the `received` row, so disconnecting everywhere reaches that library
  too. An account already linked to someone else on the branch is left
  as it is, and one
  that came without a secret is not added. The join's answer counts what
  was added, already there, taken, or not kept.
- **The branch operator's rule.** Each operator decides whether members
  may connect store accounts there with the **Link store accounts**
  member control, for every member or one (**Settings → User
  Management**, `PUT /api/users/default-controls` and
  `PUT /api/users/{id}/controls`; see
  [Sharing](/docs/guide/sharing/index.md#limit-what-a-patron-may-do)). It is on
  by default and nobody can change their own. An Owner or the operator
  can turn it off for one Administrator too; Owners are never limited. A member it is off for adds nothing from a join,
  and the connect routes answer `403`. A sign-in that finishes after the
  control was turned off is not linked, and an account it newly stored
  (or found revoked) is revoked again and its secrets deleted. That
  cleanup, an allowed sign-in's link and a revoke of the same store
  account each take the account's write lock (`bookclerk_slots`) first,
  so an allowed sign-in of the same account either links before the
  cleanup (which then keeps it) or finds its credentials gone and asks the
  member to sign in again. A join already adding accounts when the control
  is turned off (or the member is disabled) stops: each account is added
  in its own batch that checks the member's controls again, and the ones
  not yet added count as not kept.

### Adding connections later, and disconnecting everywhere

A branch's person can add store connections to a library the branch
already joined, and take one back from every library at once. The join
binds each link to its person: the Owner who signed in to run the join,
or else the branch's single active Owner (a join that can name neither
binds nobody). Only an active Owner may call these routes, and only
through the links they joined: anyone else, or an add through another
Owner's link, gets `403 not_branch_person`, and a disconnect leaves other
Owners' libraries alone.
Each call to a library is bounded at 12 seconds, inside the routes'
30-second deadline; the branch runs one such request at a time, so an
offer never reaches a library after a disconnect reported the account
gone.

- **Add to a library.** On the branch, **Accounts** shows **Add to
  *library*** beside each connection
  (`POST /api/config/join/connections` with `{library_id, accounts}`, at
  most 64). The branch picks the person's own connected accounts, records
  each as sent to `link:<library id>` in
  `account_shares`, and sends them over the link's socket as
  `accounts.add`: one bundle sealed to the connection's owner box key from
  `welcome`, bound to the library and node ids under its own
  associated-data domain, so a joining bundle never opens as an offer.
- **On the library.** The library keeps the accounts for the user its node
  row names as the branch's owner (the user who let the branch join),
  under its own per-member rule, exactly as a branch keeps a joining
  bundle: one guarded atomic batch per account, a `received` row against
  `node:<node id>`, and an audit row `branch_connections_added`. Accounts
  of storefronts not installed there are not kept, nor single-keeper
  accounts another branch already keeps. The answer,
  `accounts.added`, counts what was added, already there, taken, or not
  kept, and whether the rule refused them all. The library handles
  `accounts.add`, `accounts.remove`, `accounts.update` and the
  connections a join sends one at a time, so two branches never both
  become an account's keeper. It refuses a branch's request
  (`superseded`) unless the connection it came on is still the branch's
  live one, so a request the branch gave up on can't land after a later
  one.
- **Disconnect everywhere.** **Revoke everywhere** on the branch
  (`POST /api/config/join/connections/disconnect` with
  `everywhere: true`) disconnects it on the branch first, then sends
  `accounts.remove` up every link the account was shared with, in either
  direction, all at once. A link the branch left or lost is named in
  `unreached`. Each library removes the person's links to the account and, in
  the same atomic batch, deletes its secrets and marks it revoked when no
  other member's link holds it. When it is the only holder, the library
  first marks the account revoked, so a scan still running can't write
  more, then removes its holdings (each with a `holding_removed` event)
  and its scan checkpoints, as any revocation does, and only then the
  links: a failed step is retried by disconnecting again. A library that can't be reached is named
  in the answer's `unreached`, and the account stays connected there.
  **Revoke here** (or `everywhere: false`) disconnects it on the branch
  only.

### One refresh keeper

A single-keeper store (Audible) breaks a sign-in that two places refresh
on their own, so each such account has one keeper per library. Which side
keeps it follows from `account_shares`: the library sees the branch it
first recorded the account against (`node:<id>`), and that branch sees a
share with `link:<library id>`. A library with no such share keeps the
account itself.

- **On the branch.** The branch's copy is the one that refreshes: Accounts
  sign-ins, refreshes its own scans hand back, and refreshes a job for
  that library hands back are all saved there. Once a minute, and each
  time the link connects, the branch looks for accounts whose secrets
  changed since what it last pushed, and sends each up the link as
  `accounts.update`: one account sealed to the connection's owner box key
  like an offer, with a revision above the last one it sent there. Any
  secret write counts as a new sign-in (the branch compares a fingerprint
  of the secrets, not their times), so neither a clock that went back nor
  two writes in one millisecond can hide one. A push the library applies
  is recorded so it isn't sent again; one it already had a revision for
  (`stale`, as after a lost answer) is sent again above it.
- **On the library.** The library applies a push only from the account's
  keeper, for the person who owns the branch, and only when its revision
  is newer than the last one applied (`account_credential_revisions`), in
  one guarded atomic batch, and audits `branch_sign_in_applied`. A push
  retried or overtaken by a newer one changes nothing. Once the keeper's
  first push is applied, the library doesn't save its own scans' refreshes
  of the account, and refuses a job's write-back of it (`kept_by_branch`),
  so neither overwrites the keeper's newer sign-in. Until then the library
  keeps refreshing it itself, so a branch that was sent the account but
  couldn't keep it (no Owner to keep it for, or its member rule refused it)
  never leaves it stale.
- **Elsewhere.** A kept account travels back only to its keeper, never to
  a second branch, and a second branch's offer of it is not kept.
- **A new keeper.** When the account is disconnected everywhere on the
  library (no member's link holds it), the library forgets its keeper, so
  the branch the person adds it from next keeps it. Adding it again
  from a branch makes that branch push its current sign-in again, even
  an unchanged one, so the library takes it as keeper anew. A push the library
  doesn't take from the branch yet (`not_shared`, as when it overtook the
  branch's offer) is sent again on the next pass.

Disconnecting on a library does not yet reach its branches.

> [!NOTE]
> A retry of the same exchange (a lost answer) replays the same node, and
> two concurrent redeems still make one node. Anything else, such as a
> used, expired or unknown code, or a wrong verifier or redirect URI, is
> `403 enrollment_refused`.

### On the command line

```sh
bookclerk libraries join --url https://library.example [--name "Den PC"] [--fingerprint <fingerprint>]
bookclerk libraries join             # prompts for a branch invite
bookclerk libraries join < invite.txt
bookclerk libraries list             # library id, origin, node id, state
```

`--url` is the same sign-in, for an operator with a browser on the same
machine. The command:

1. Prints the authorize URL, and opens a browser when it can (set
   `BOOKCLERK_NO_BROWSER=1` to stop that).
2. Listens on a loopback port for the library's answer, for 10 minutes.
3. Records the link.

A self-signed library's fingerprint is confirmed with `--fingerprint` or
by typing `yes`.

Without `--url`, `join` reads a branch invite from stdin or a prompt. It
never takes an invite on the command line, so the invite stays out of
shell history and process listings.

A running daemon picks up a link joined on the command line within 5
seconds. From then on the daemon connects to the library, heartbeats every
15 s, and reconnects with backoff (1 s up to 60 s) whenever the connection
drops, resuming any job it still holds.

## Shared branches

A shared branch is a second (or third) server for the
**same** library. It is a shared node that opens the library's database
with the library's key, serves the web UI, plans jobs, and can take over
maintenance leases when another shared node goes down. Any other branch
keeps its own database; a shared branch has none of its own.

### Who can add one

Only an **Owner** of the library. When an Owner signs in from the Join
wizard, the consent page asks "How should it join?", with **Join as a
branch with its own database** (the default) and **Join as a branch on
this library's database**. Everyone else sees only the branch page.

The second choice is shown but disabled, with the reason, when:

- the library's database is the default SQLite file (only PostgreSQL or
  Cloudflare D1 can be opened by more than one server);
- the joining server didn't offer it (it isn't empty, see below);
- the Owner has neither an authenticator app nor a passkey.

### On the joining server

The Join wizard shows **Offer to join as a shared branch** only on an empty
install. That means no users, store accounts, books or joined libraries of
its own, and no `BOOKCLERK_DATABASE_*` or `BOOKCLERK_D1_*` environment
override of the database settings. (`BOOKCLERK_D1_API_TOKEN` isn't one: it
stays this server's own.)

Ticking it asks you to confirm that the server's own database settings and
keys are replaced. The daemon checks again when the sign-in starts and
when it comes back.

> [!NOTE]
> For a D1 library, set this server's own `BOOKCLERK_D1_API_TOKEN` (the
> token is never sent between servers). For any branch on the library's
> database, install the library's database plugin (`postgres` or `d1`) first.

### Approving

Joining as a shared branch needs a fresh second factor on the consent page: the
6-digit code from your authenticator app, or your passkey. The code the
library issues is bound to the choice, so a code approved for a branch can
never be redeemed for the library's database. Consent and redeem need TLS (or loopback
with both ends on one machine), as for a branch.

### What is handed over

In its redeem answer the library sends the `[database]` connection and the
data-encryption key, sealed to the joining daemon's own X25519 node key.
It never sends the passphrase-wrapped `master.key` file. The browser never
sees either, and neither is logged.

The joining daemon writes them as its own bootstrap:

- `config.toml` `[database]`. A PostgreSQL URL goes into
  `database-postgres.url`, mode `0600`, named by `url_file`, and never
  into the TOML.
- `node-identity.json`, with the node id the library recorded.
- `master.key`, wrapped with this server's own `BOOKCLERK_AUTH_PASSWORD`
  (or `[auth].password`) when set, and unwrapped otherwise. When this
  server keeps its key in the OS keychain or `systemd-creds`
  (`[auth].key_store`, or the desktop window's default), the key goes
  into a new item there and `master.key` only names it.

Then `bookclerkd` restarts itself cleanly. It stops its listeners as on
SIGTERM and re-executes the same binary with the same arguments and
environment (on Unix the PID stays the same). It comes back as an owner
node of the library. Sign in there with your library account.

### If the first start fails

The originals of those files are kept, as `<name>.pre-shared-branch` with a
`shared-branch-join.json` record, until that first start opens the library's
database.

If it can't (for example the PostgreSQL address only works on the
library's own machine, or the D1 token has no access to the database), the
start tries a few more times. Then it puts this server's own settings,
node identity and key back and stops. To recover:

1. Start it again to run as before.
2. Remove the branch under **Settings → Shared branches** on the library before
   joining again.

If a join or its undoing is cut short (a crash, a power cut), the next
start finishes undoing it, or refuses with instructions naming each file.

### On the command line

```sh
bookclerk libraries join --url https://library.example --as shared branch
```

`--as` is `branch` by default. With `--as shared-branch` the CLI writes the same
bootstrap files and asks you to restart `bookclerkd`.

### Listing and removing

**Settings → Shared branches** on the library (operator or Owner) lists every owner
node, this server first, and who approved it (`GET /api/config/shared-branches`).
Another user sees only the ones they own.

A shared branch that isn't running can be removed there
(`DELETE /api/config/nodes/{node_id}`) by the operator, or by an Owner after
elevating, since removing one deletes its records. Stop Bookclerk on it
first.

> [!WARNING]
> Removing a shared branch doesn't take back the database credentials or key it
> held. Rotate them if it is no longer trusted.

Audit events:

- On the library: `shared_branch_authorize`, `shared_branch_authorize_refused`,
  `shared_branch_enroll_refused` and `shared_branch_enrolled`.
- On the joining server: `shared_branch_joined`.
- When one is removed: `shared_node_removed`.

## Consent: what the library may run here

The library deploys plugin instances to the branch as to any node, but the
branch's daemon spawns none of them until its operator approves. Each
deployed plugin shows up as a **request**, with:

- the version the owner wants to run;
- what that version asks for: network mode and domains, TCP targets,
  address ranges, host bindings such as `config`, `secrets` or `kv`, the
  hosts that keep the plugin's own
  [User-Agent](/docs/plugins/capabilities/index.md#user-agent) with its reason, and
  memory, CPU and disk budgets;
- the archive URL and digest this host would fetch;
- a `request_digest` covering all of it.

```sh
bookclerk libraries consents [--library <id>]
bookclerk libraries approve <plugin_key> --request <request_digest> \
    [--deny-domain cdn.store.example]... [--deny-binding secrets]... \
    [--deny-own-user-agent api.store.example]... [--deny-network]
bookclerk libraries revoke <plugin_key>
```

The same is in the web UI under **Settings → Library** (operator only; an
Owner sees only the [sharing settings](#branches-of-branches)). It lists
pending requests with their domains, bindings and own-agent hosts, a deny
checkbox on each,
a deny-network switch, and Approve and Revoke.

The HTTP routes behind it are operator-only:

| Route | Body |
| --- | --- |
| `GET /api/config/library-consents` | → `{libraries, consents}` (links carry ids, origin, state and whether they are pinned; never keys) |
| `POST /api/config/library-consents/approve` | `{library_id, plugin_key, request_digest, deny_domains?, deny_bindings?, deny_own_user_agent_hosts?, deny_network?}` |
| `POST /api/config/library-consents/revoke` | `{library_id, plugin_key}` |

### Consent rules

- **Only what is asked for can be approved.** Denying a domain, binding or
  own-agent host the request doesn't ask for is refused
  (`400 invalid_approval`, with the reason in `detail`). Unless network
  access is denied too, so is denying an own-agent host that an approved
  wildcard still covers. A host the owner stops asking for is dropped from
  the approval.
- **You approve the request you reviewed.** `--request` (the UI always
  sends it) makes the approval a compare-and-swap. If the owner has since
  changed the request (another version, grant or archive), the approval
  is refused with `409 approval_refused` rather than applied unseen.
- **Asking for more waits again.** A later version that asks for anything
  outside what was approved is `awaiting_host_reapproval` and doesn't run
  until approved. That covers a domain, TCP target, address range,
  binding, compatibility flag, entrypoint, a larger budget, or network at
  all. Asking for less needs nothing. `libraries consents`, the web UI
  and the API (`pending` on each consent) list what changed since the
  approval, in the same words the
  [local consent flow](/docs/plugins/capabilities/index.md#upgrades) uses.
- **Platform plugins** are approved automatically
  (`approved_by = "platform"`) only when this host's own install of the
  same platform key is bundled with the same payload digest as the
  owner's artifact, and the request stays inside the platform envelope.
- **Revoke stops work.** A revoke (CLI or UI) is seen within 5 seconds.
  The plugin's held jobs are cancelled and handed back to the owner
  unspent, and none of its jobs is claimed again until approved.

The states are `consented`, `awaiting_host_consent`,
`awaiting_host_reapproval` and `invalid_grant`. The host sends the set of
consented plugin keys with every claim, so the owner never hands it a job
it would refuse.

For an approved plugin, the host fetches the owner's archive over the
signed artifact endpoint and checks its digest. It runs it jailed under
the approved grant through `bookclerk-workerd`, exactly as it runs its own
plugins (see [The guest jail](/docs/internals/guest-jail/index.md#the-guest-jail)).
There is no in-process fallback.

### Plugin state on a branch

A branch keeps each joined library's plugin state apart from every other
library's and from its own. A guest that runs for a library gets
`plugin-state/link-<32 hex>/<PluginKey fs-id>/data` and `…/tmp`. The leaf
is the first 128 bits of the SHA-256 of that library's id. The
branch's own guests keep `plugin-state/<PluginKey fs-id>/`. So when two
libraries deploy the same plugin, their guests never see each other's
caches, cookies or logins. The plugin code cache under
`plugins/.versions/` stays shared, because it is read-only and addressed
by digest.

The design record is
[ADR: Library catalog network](/docs/adr/library-catalog-network/index.md).

## What a branch runs

### Scans

The guest's rows come back to the owner in fenced `scan.results` batches,
of at most 200 rows (a row over 32 KiB is skipped). On every batch the
owner:

1. Re-checks the job's fence and the node's trust.
2. Refuses the whole batch if any row names an account outside the job,
   or, for a Member's host, outside that user's accounts.
3. Writes the rows through its own store API.

A host never writes library SQL.

### Acquires

A host takes acquires a person started. Acquires that wait for a store
account's [download pace](/docs/internals/jobs/index.md#download-pacing), such as
auto-acquire, run only on nodes that share the library database, because
the pace lives there; so do forced and PDF-only acquires. Each title a
host uploads still counts toward its account's pace: the owner records it
when it commits the upload.

1. The host asks the owner for the job's titles (`acquire.plan`). As for
   a local acquire, a title whose edition another store account already
   acquired is left out: the library already has its files.
2. The answer, `acquire.targets`, lists the titles still to fetch and every output
   destination deployed on the shared node that answered, each with its own
   naming options (templates, replacement characters, path limits). Each
   title carries its store account's holding id on the owner, which its
   upload names, and its call number on the owner, so the `<call number>`
   naming tag writes the owner's id rather than the host's scratch one.
   It also carries the store listing the acquire needs (store, product id,
   marketplace, title, people, series and dates), read from the owner's
   holdings and editions, and a podcast episode carries its show's
   listing the same way.
3. The host acquires each title into a per-title outbox, with one
   sub-directory per owner destination. So each destination's file names
   come out exactly as a local acquire on the owner would name them.
4. The host **uploads** the title, as described in [Uploads](#uploads).

The host also keeps a copy of each of its owner's own titles in its own
deployed destinations. A title acquired for another member is copied
there only when **Keep copies of other members' books** is on (see
[Work settings on the branch](#work-settings-on-the-branch)). The owner
says which titles are whose with each job.

Once the owner has committed one of the owner's own titles, the host also
adds it to its own library: the title, acquired, with its copy's files,
held by the store account that bought it. This happens only when that
store account is connected on the host to its Owner (for example brought
along when joining). Another member's title is never added, even when its
copy is kept. A title added this way is marked as coming from that
library, so it is never shared back to it. A title acquired for two
libraries is marked for both and shared back to neither.

### Sharing this computer between libraries

A branch of several libraries splits its work between them, so no one
library can take the whole machine.

1. **The machine's job slots** come from the branch's own heartbeat: its
   CPU budget over 0.8 of a core and its memory budget over 512 MiB (what
   one guest is assumed to need), whichever is smaller, from 1 to 16. A
   drained branch (`bookclerk nodes set --drain`) has none, so its
   libraries stop handing it work too. Until the branch records its first
   heartbeat after starting (within seconds) it also has none.
2. **The branch's own work comes first.** Each job its own workers run
   takes a slot.
3. **The rest is split equally** between the libraries it is a branch of,
   one slot at a time in library id order. A library capped below its
   equal share leaves its unused slots to the others.

Each library sees only its share:

- The branch claims no more of the library's jobs than its share. A share
  that shrinks cancels nothing: jobs already running finish, and claims
  wait until enough of them have.
- The branch's heartbeat to that library reports its share of the
  machine's CPU and memory, and of that share only what the machine has
  free now, so the library's scheduler never counts on the whole machine
  or on headroom other work already took. The library then applies its
  own budget for the branch (`bookclerk nodes set` there) as it does for any
  node; the branch's budget decides how many slots there are. Free disk is
  reported whole.

For example, a branch of two libraries with four slots runs up to two
jobs for each. While it runs one job of its own, the first library (by
library id) keeps two slots and the second gets one.

**Settings → Library → Work for <library> on this computer** caps one
library: **Equal share** (the default), **None** (no work for that
library), or **Up to N jobs**. B's operator or an Owner of B may change
it. The route is `POST /api/config/join/capacity`
`{library_id, max_jobs}` (required; `null` for an equal share, 0 to 16), and the
listing routes report each running library's `job_share` now.

## Asking the owner for a scan

```sh
bookclerk libraries scan [--library <id>] [--account <id>] [--instance <id>] [--no-wait]
```

The host's operator asks the library to queue a scan, through this
install's running daemon and its link
(`POST /api/config/libraries/{library_id}/scan`, a `scan.request` frame).
It runs as the user who owns this node:

- An Owner or Administrator scanning every account gets one job per
  scan-enabled account, spread over every shared node and host trusted with
  each.
  An Administrator whose **Scan and acquire library-wide** switch is off
  counts as anyone else.
- Anyone else scans only their own accounts. A named account that isn't
  theirs is refused (403).
- A node trusted with nothing (no owner, a disabled owner, or revoked) is
  refused.

The command then polls the jobs (`job.status`), which shows only jobs this
node would be trusted to claim.

## Uploads

Files stream **through** the owner to its destinations. Nothing is staged
on a shared node's disk.

Each title goes only to the destinations whose filter takes it (see
[Choosing which books a destination takes](/docs/server/output/index.md#choosing-which-books-a-destination-takes)).
The owner's `acquire.targets` answer lists, for each title, the ids of
those destinations in `destinations`. An empty list means none takes the
title, and the host fails it without fetching anything.

1. **Grant.** The host sends `upload.grant` over the node socket, with
   the title's holding id from the plan and a manifest. The manifest lists each distinct file content once (`size`,
   `sha256`, `content_type`), with a list of **copies**, one
   `{destination, key}` per destination the title goes to, and no
   other. An audio file the host
   could probe also carries `probe` (`bitrate_kbps`, `lossless`,
   `source_store`), which the owner keeps on the file's row once the
   upload commits (see [What a stored file's row
   says](/docs/server/media/index.md#what-a-stored-files-row-says)). The owner answers
   `upload.granted` with an upload id and a bearer token **sealed to the
   host's box key**. Only its hash is stored, and it lives one hour.
2. **Send.** The host sends
   `PUT /api/node/v1/uploads/{upload_id}/files/{n}` per file, with
   `Authorization: Bookclerk-Upload <token>`. The owner tees the body,
   chunk by chunk, into each of those destinations under that
   destination's key. If the title's destinations change before the
   commit (one is deployed or undeployed, or a filter is edited), the
   upload is refused with `destinations_changed` and the title fails on
   the host.
   It checks the size and SHA-256 as it streams, and re-checks the job's
   fence about once a second.

   A file larger than 64 MiB goes in parts, so a relay that caps
   request bodies (such as an ingress plugin's Cloudflare Worker, 100 MB
   on the Free plan) passes it. Each part is its own `PUT` of the same
   URL with `Content-Range: bytes <first>-<last>/<size>`, in order. The
   owner answers `200 partial` with the `offset` it needs next until the
   last part, which is answered like a whole file. The parts feed one
   write per destination, so the file is still never staged and the
   checks cover the whole file.

   An interrupted file resumes. Before sending, and after a part breaks,
   the host sends an empty `PUT` with `Content-Range: bytes */<size>`;
   the owner answers `200 partial` with the offset of the next byte it
   needs (or `received` when it has the whole file), and the host sends
   only the rest. A part that doesn't start there gets `503` with reason
   `resume` and that offset. The owner keeps an open file for 10 minutes
   without a part; after that, or once the owner restarts, it starts
   again from byte 0. A file small enough to send whole starts again
   too.
3. **Commit.** The host sends `POST /api/node/v1/uploads/{upload_id}/commit`.
   One canonical batch, gated on the live fence, marks the title
   acquired, records a stored copy of the edition on each destination
   the primary audio was written to (`edition_copies`), publishes
   `book_acquired`, and (for the job's last title) completes the job.

A destination sees the end of its stream only after the whole body
matched. A mismatch or a lost fence ends every destination's stream with
an error, so each discards what it wrote. So does a broken connection
while a file is sent whole. A part whose connection breaks keeps the
bytes that arrived: the file stays open at that offset until its last
part, an abort, or 10 minutes without a part.

| Refusal | Meaning |
| --- | --- |
| `401 unauthorized` | Unknown upload, or a wrong or expired token |
| `421 misdirected` | Another shared node granted it |
| `409 lost` | The fence is gone |
| `422 refused`, `422 destinations_changed` | The shared node's destinations aren't the ones the manifest was written for. The upload is aborted and the title fails on the host, to be retried |
| `422 invalid_range` | A part's `Content-Range` isn't exactly a part of the declared file |
| `503 unavailable`, reason `resume` | A part didn't start where the open file stands; send from `offset` |

Limits: 512 files per title, 8 GiB per file, 16 copies per file and 1 KiB
keys.

These routes sit outside the cookie and operator-auth layers, because the
sealed token is the credential. They run the transport policy first.

## Taking a copy from the library

A branch can take the files the library already holds of an edition,
instead of downloading the book from the store again. Nothing new has to
be turned on: the library answers a branch it trusts, for the person the
branch belongs to.

1. **Grant.** The branch sends `copy.grant` over the node socket, naming
   the edition by its store listing (`store`, `marketplace`,
   `product_id`). The library answers `copy.granted` with a copy id, what
   the copy is (media type, bitrate, source store, version, as the
   [list of books in other libraries](#books-in-other-libraries) states it), the list of files with their
   sizes, and a bearer token **sealed to the branch's box key**. Only the
   token's hash is stored, and it lives one hour.
2. **Download.** The branch sends
   `GET /api/copies/v1/{copy_id}/files/{n}` per file, with
   `Authorization: Bookclerk-Copy <token>`. The library streams the file
   from its destination; nothing is staged on its disk. One `Range`
   (`bytes=a-b`, `bytes=a-` or `bytes=-n`) is honoured with `206`, so a
   broken download resumes where it stopped.

The reader writes each file to disk as it arrives and takes it only when
the answer states exactly the bytes it asked for: `200` with the size the
grant listed, or `206` from the byte it resumes at to the end of the
file. An answer with another length or range, or with a chunked body, is
refused, and what the reader already holds is kept for the next try. A
`416` on a resumed download starts that file over once. A branch linked
to several libraries sends a copy's token only to the library that
granted it.

The library sends a copy of an edition when it holds the edition's audio
and the person may see the edition: their
[patron scope](/docs/guide/sharing/index.md#limit-what-a-patron-sees) shows it, or
it is on a store account of their own, and their member controls allow
**Download**. An edition outside the scope gets the same `not_found` as
one the library doesn't hold. The primary audio file comes first,
then the files stored in the same folder (parts, chapters, cover, PDF,
sidecars). File names are relative to that folder. They say what a file
is; the branch names the files its own way.

The library checks the grant again on **every** download, not only when
it hands out the token: the branch is still trusted, it still belongs to
the same person, that person may still see the edition, and the files
are still the ones the grant listed. A token outlives none of them.

### When a branch takes the copy

A branch asks for a copy when it acquires one of its **own** titles: a
book on a store account connected to the branch, found by the branch's
own scan. Before it fetches the title from the store, it asks each
library it joined, in turn, for the copy of that listing.

- **Same store: the library's copy is used.** When the library downloaded
  its copy from the same store as the branch's title, and holds it as
  one audio file, the branch downloads the library's audio and cover and
  the store is not asked. The files then go through the branch's own
  acquire like a store download: converted to the branch's output
  format, named by its templates, tagged, probed and recorded. Chapters
  are read from the downloaded file in the confined media worker.
- **Several audio files: the store.** A book the library holds as parts
  or as one file per chapter is fetched from the branch's store. The
  grant lists those files by name, which need not be playing order.
- **Split by chapter: MP4 audio only.** A branch whose output is split
  into chapter files takes the library's copy only when it is an M4B,
  M4A or MP4 file; otherwise it fetches from the store.
- **Another store: the better copy is kept.** When no library has a copy
  from the title's store but one has a copy of the same edition from a
  different store, the branch downloads from its own store first,
  probes that download and asks its libraries again (a store download
  can outlast the hour a library's answer is good for). If the library's probe says its copy is better
  (lossless beats lossy, then the higher bitrate wins), the branch
  downloads the library's copy too, probes it itself, and stores it in
  place of its own download only when its own probe agrees. Otherwise it
  keeps its own, as it does when the two don't fit in the acquire's
  scratch budget together. A branch whose output re-encodes or
  repackages the audio takes only a copy the media worker reads (AAC,
  ALAC, FLAC or MP3; see [what audio it reads](/docs/server/media/index.md#what-audio-it-reads)),
  so a copy in another encoding, such as Opus, is taken only by a branch
  that keeps files as delivered. The comparison runs once, in that acquire. The stored
  file's row names the store the audio really came from, and the cover
  and companion PDF of the branch's own download are kept (the library's
  cover is used only when the store sent none).
- **Unknown store: the branch fetches its own.** A copy whose store the
  library doesn't know is never offered.
- **Any problem: the store.** If the copy doesn't arrive whole, is larger
  than the acquire's scratch budget, or holds audio the media worker
  can't read, the branch removes what it downloaded and fetches from the
  store.
- **Audio that doesn't package: the store.** The copy is checked by its
  tags before it is taken, so a copy whose tags read but whose audio
  doesn't decode fails only when the output repackages or re-encodes it.
  The branch then removes the copy and fetches the title from its store
  (again, for a copy from another store that replaced the download) and
  stores the copy that failed, and every copy after it, from that
  download. Nothing of a copy reaches a destination before its audio is
  packaged, so no destination is left with the library's broken audio;
  copies already stored keep the library's audio, which was recorded as
  taken before anything was stored.

Only the audio, the cover and the companion PDF are taken. The branch
writes its own sidecars (`.cue`, chapter JSON). The PDF is taken only
when companion PDFs are turned on at the branch and the library holds
one; it is the file the store gives for the edition, and the branch
stores it without opening it. The store is not asked for a PDF the
library doesn't hold, because a store's only way to a PDF is a whole
download of the title; a later acquire of the same title asks the store
for a missing PDF as it does for any title whose audio is already
stored.

The branch asks a library only while that link's **Keep copies on this
computer** setting is on and its connection is up; a library that is
offline is skipped, not waited for. A book taken this way is recorded
for that library before the branch stores any of it, so the branch never
shares it back to the library it came from (see
[Shared catalog](#shared-catalog)); a copy that can't be recorded isn't
used. The job log line
`acquired` carries `from_library=true` for such a title.

A clerk takes copies the same way, for the person its library card
belongs to. Its own acquire asks each library it holds an active card
for, after any library it joined as a branch, by sending `copy.grant` on
that card's clerk socket; a library whose socket isn't connected is
skipped. The same-store rule and the fall-back to the store apply, and a
taken book is recorded for that library too. The grant's token is not
sealed (a clerk has no box key; the socket is the card's own connection,
TLS except on loopback), and each download checks that the card is still
signed in instead of a branch's trust. See
[The clerk socket](/docs/server/sign-in/index.md#the-clerk-socket).

| Refusal | Meaning |
| --- | --- |
| `error` `refused` (socket) | Not a branch this library trusts |
| `error` `not_found` (socket) | The person may not take the edition, or the library holds no copy of it. The two are not told apart. The only refusal a clerk gets besides `invalid` and `unavailable` |
| `error` `unavailable` (socket), `503 unavailable` | The library's storage can't be read right now. Try again later |
| `401 unauthorized` | Unknown copy, a wrong or expired token, or a grant that no longer holds (for a clerk: its card was signed out or expired, or its user disabled) |
| `421 misdirected` | Another library node granted it |
| `404 unknown_file` | The copy has no file `{n}` |
| `416 range_not_satisfiable` | The range starts at or past the end of the file |

Limits: 1000 files per copy and 512-byte names. A grant is dropped once
it expires.

## Node-local instances

An instance can be **local to one node**: it deploys only on that node and
the scheduler never places it. The usual case is a node's own `local`
output (its own disk), which adds to the library's outputs on that node
rather than replacing them.

```sh
bookclerk plugins instances create local --name "nas disk" --node <node_id>
bookclerk plugins deploy <instance_id> --node <node_id>
```

`POST /api/config/plugin-instances` takes the same as
`{plugin_key, display_name, node_id}`. Deploying the instance to another
node, or handing it to the scheduler (`--replicas`), is refused.

Uploads reach every destination deployed on the shared node that granted
them whose filter takes the title, node-local ones included.

## Branches of branches

A branch is a full library of its own, so its users can join their own
branches to it. The result is a tree: A ← B ← C, where B is A's branch and
C is B's.

- **One hop at a time.** A knows B as a branch owned by one of A's users.
  A has no record of C and never learns it exists. A's work runs on B
  itself and is never passed on to C. No store account, store token or
  user of B or C is ever sent to A.
- **Books flow up.** B shares its owner's books with A: those held on B
  by a store account connected there to B's Owner whose edition B has
  acquired (whichever of B's store accounts downloaded it), and (when "Include
  books from my own branches" is on) those C shared with B. B's other
  members' books stay on B, unless A requests one or A's operator turns on
  **Acquire all of this branch's members' books** (see below). Each title
  carries its store, product id, marketplace, metadata (with its ASIN,
  ISBN and kind) and file list, nothing else. A matches each one to the edition it already knows, as a
  store scan would, and records B as holding it, so C's books are simply
  B's books there, belonging to the A user who owns B. A title B got from
  A, or acquired for A and added to its own library, isn't sent back.
- **Files** stream to A's outputs through the same upload endpoint a
  branch's acquire uses (nothing staged on A), under the keys they have on
  B. A title whose files would land on a key another book in A already
  uses is recorded, but its files aren't sent. Neither are the files of an
  edition A already has (acquired there, or delivered by another branch),
  so each edition arrives once. If A has no output deployed, it records
  the titles without files.
- **Sync** runs when the branch connects, every 5 minutes, and at once
  when a setting changes. It is incremental and resumes after a
  reconnect. A full pass (after a setting changes, and once a day) also
  withdraws titles B no longer has.

### Sharing settings on the branch

**Settings → Library** on B has these settings for each library joined,
all on by default:

- **Share this branch's books with <library>.** Off: nothing new is sent,
  and A no longer counts B as holding what it got from B. Files already
  delivered stay in A's outputs. B also lists nothing in answer to A's
  catalog questions.
- **Include books from my own branches.** Off: B shares only books
  acquired on B itself, and C's titles are withdrawn from A on the next
  pass.
- **List my members' books to <library>.** Off: B answers A's catalog
  questions with its owner's books only (see
  [Shared catalog](#shared-catalog)).
- **Keep copies on this computer.** On: when B acquires one of its own
  titles and A already holds a copy from the same store, B takes A's copy
  instead of downloading from the store (see
  [When a branch takes the copy](#when-a-branch-takes-the-copy)). Off: B
  leaves A's copies at A and downloads its own titles from their stores.
  B still takes A's work, lists its books to A and shows A's books (see
  [Books in other libraries](#books-in-other-libraries)).

B's operator or an Owner of B may change them. An Owner sees only the
libraries, these settings and each library's job cap (see
[Sharing this computer between libraries](#sharing-this-computer-between-libraries));
joining, leaving and plugin approvals stay the operator's. Anyone else is
refused (403).

The routes are `GET /api/config/join/sharing` (→ `{libraries}`) and
`POST /api/config/join/sharing`
`{library_id, share_books, include_branches, list_members_books?, keep_copies?}`
(`list_members_books` and `keep_copies` are left as they are when absent),
which also takes the [work settings](#work-settings-on-the-branch).

### Work settings on the branch

**Settings → Library** on B also has two work settings for each library
joined, both off by default:

- **Download for other members of <library>.** Off: B asks A only for
  work on the store accounts of the A user who owns B, its owner's own
  books (including jobs pinned to one plugin instance). On: B also takes
  work for A's other members, where A trusts B with it (an
  Administrator's or Owner's branch). A still hands B only
  work it is trusted with, so this setting never widens trust.
- **Keep copies of other members' books.** Off: a book B acquires for
  another member goes only to A's outputs. On: it is also written to B's
  own outputs, as B's owner's books always are. It only matters while the
  first setting is on.

They apply to the next job B asks for; a job already running finishes.
The same people may change them, through the same routes:
`POST /api/config/join/sharing` takes `work_for_members` and
`keep_member_copies` too, and a body that leaves one out keeps it as it is.

### Branch titles on the library

**Settings → Branches** on A lists each branch with its owner, what it
shares (read-only, because B's operator or an Owner of B sets it), counts
of its titles, and A's **Acquire all of this branch's members' books**
(see [Acquiring all of a branch's members'
books](#acquiring-all-of-a-branchs-members-books)).

When a branch stops sharing, withdraws a title or leaves, A no longer
counts it as holding those titles. Files it already delivered are kept.
When nothing else in A holds that book either, its files are marked as
from a branch that left, until the owner removes the entries with
**Remove** (or `POST /api/config/branches/titles/remove {node_id?}`). The
files themselves stay in A's outputs. A book a store account or another
branch in A still holds keeps its files as that book's. If the branch
shares the title again later, it is delivered again.

### Shared catalog

A library can ask its branches whether they can supply works its people
are looking at, without copying their catalogs. The answers say "available
through B", and nothing is fetched until someone asks for it.

1. **The library asks.** Each Discover candidate fetch ends with an ask,
   at most every 15 minutes per daemon: A stores one question per trusted
   branch and work (works of open wishes and Discover candidates) and
   wakes each branch. A question already waiting, or answered within a
   day, isn't asked again.
2. **The branch pulls the questions.** On the wake, when it connects, and
   every 15 minutes, B sends `catalog.questions` and gets up to 100
   questions. A question that goes unanswered for 10 minutes is sent
   again.
3. **The branch answers.** B looks each work up in its own library and
   sends `catalog.found` with the editions it holds: store, product id,
   the formats it has, and metadata. A work it can't supply is named as
   missing.
4. **The library records the answers.** Each edition becomes a listing in
   A's shared listing pool, from source `branch:<B's node id>`. A listing
   counts for two days after B last named it. A later answer that no
   longer names it expires it.
5. **Discover and search show them.** When a Discover feed or a catalog
   search page is read, each card or hit is matched to its work (the
   card's own work, or the work of a store listing A's pool holds for one
   of its store editions) and gets `available_through`: one entry per
   current listing from a trusted branch, with A's work id (what a
   request names), the branch's node id, its owner's display name, and the
   store and product id. The field is never
   stored with the ranked feed, so it is current on every read.

Questions name works by identifier only, because work ids differ between
libraries:

- A asks with the ASINs (and marketplace), ISBNs and OpenLibrary ids of its
  editions of the work. Titles and authors are never compared.
- B maps them to one of its works by a strong identifier (an ASIN or an
  OpenLibrary id), or, when none matches, by ISBNs that reach one work
  only. A question that reaches no work, or more than one, is answered as
  missing.
- A keeps an answered edition only when it lands on an edition A already
  has of the asked work. An answer can't add works or editions to A.
  An edition B names by ISBN only is dropped for now: the resolver places a
  weak identifier only on an expression with a known language and
  abridgement, which most store-scanned editions lack.

An answer names no store account, user, or other library. A asks only
branches it still trusts, and records answers only for questions it sent
that branch.

**What B lists.** B always lists its owner's books. It never lists books on a store account linked to no one, such as one a member disconnected. It lists its members'
books too while **List my members' books to <library>** is on (the
default, set per library in the sharing settings below). A member can keep
their own books out with **Settings → Account → List my books to joined
libraries** (`PUT /api/auth/profile/catalog-listing` `{"listed": false}`;
`GET` also returns `libraries`, the number of libraries B is currently a
branch of, and the app shows the setting only when it is above zero, and
`always_listed`, true for an Owner, whose books are always listed, so the
app shows that instead of the toggle). With **Share this branch's books with <library>**
off, B lists nothing to that library and answers every question as
missing.

> [!NOTE]
> Turning a listing setting off, or a member opting out, takes effect at
> B's next answer. A asks again a day after B last answered, and a listing
> stops counting two days after B last named it, so A can still show B as
> a source for up to two days.

### Requesting a book from a branch

When a work is available through a branch, any signed-in user of A can ask
for it. In the app, the title's details show **Available through Riley's
branch** with a **Request from Riley's branch** button. The API is
`POST /api/branch-requests` `{"work_id": "...", "node_id": "..."}`, where
`work_id` and `node_id` come from one of the work's `available_through`
entries; leave `node_id` out to ask the first branch that lists the work.
A clerk holding a library card for A asks through the same route with the
card, from the books only A's branches hold on its clerk pages (see
[Signing in with a library card](/docs/server/sign-in/index.md#signing-in-with-a-library-card)).

1. **A queues the request.** It becomes a `branch_request` job on A,
   pinned to B and naming the edition B listed (store, marketplace and
   product id) and the work's strong identifiers. A work no trusted branch
   currently lists is refused (404). Asking again while a request for the
   same work and branch waits returns that request (`already_queued`).
   A wakes B.
2. **B claims it.** On the wake, when it connects, and every 15 minutes,
   B sends `requests.claim` and gets up to 16 requests, each leased to B
   for 5 minutes. No other node, and no ordinary job claim, ever takes a
   request.
3. **B decides, automatically.** B accepts a request only for a book it
   still lists to A, under the same rules as its catalog answers (see
   **What B lists** above): its owner's books always, a member's while
   **List my members' books to <library>** is on and the member has not
   opted out, and nothing while **Share this branch's books with
   <library>** is off. B's listing settings are where B's
   operator draws the line; there is no per-request approval.
4. **B fetches and sends the book.** An accepted book not yet downloaded
   is queued as an ordinary acquire in B's own library, on the store
   account on B that holds it. B records the book as requested by A, so
   its catalog sync sends it to A although it is a member's book. The book
   goes up with the sync's next pass after it is downloaded, and A holds
   it through B like B's other titles.
5. **A records the answer.** B answers each request with
   `requests.finish`: accepted (the job succeeds), not listed (the job
   fails as `not_listed` and isn't retried), or failed on B (the job fails
   as `branch_failed` and is retried up to the job's attempt limit). A
   request whose work has lost every strong identifier fails as
   `work_gone`.

A request names no store account, user, or other library, and A never
learns whose copy B sent. Requests made before B stopped listing a book
are answered "not listed".

> [!NOTE]
> A book B sends because of a request keeps going to A only while B
> still lists it: turning off **Share this branch's books** or **List my
> members' books**, or the member opting out, stops it at the next sync
> pass. Files A already received stay there.

### Asking the library to download a book

A clerk lists every book on A's store accounts that the patron's
[scope](/docs/guide/sharing/index.md#limit-what-a-patron-sees) shows them,
including ones A hasn't downloaded yet. For those, a patron can ask A to download the book so the
clerk can then take A's copy. The API is `POST /api/download-requests`
`{"work_id": "..."}`, where `work_id` is A's work id. A signed-in patron
of A may call it, and so may a clerk with a library card for A (see
[Signing in with a library card](/docs/server/sign-in/index.md#signing-in-with-a-library-card)).
The patron's member controls must allow **Request books** (403 otherwise).

1. **A picks the edition.** A reads the work's editions in edition id
   order and takes the first one a store account of A holds. A work A
   already has a copy of is refused (409); one no account of A holds is
   not found (404).
2. **A queues the download.** It is an ordinary `acquire` job for that
   edition, on the account that holds it, whoever's account that is. Like
   other downloads A starts on someone's behalf, it waits for the
   account's pace. Asking again while that download waits or runs returns
   it (`already_queued`).
3. **The clerk takes the copy.** Once A has the copy, the next read of
   A's books states it, and the clerk uses it like any copy A holds.

### Acquiring all of a branch's members' books

By default A receives B's owner's books, plus the books A requests. To
receive every book B lists instead, A's operator (or an Owner) turns on
**Acquire all of this branch's members' books** for B in **Settings →
Branches**. The API is `PUT /api/config/branches/members-books`
`{"node_id": "...", "acquire": true}`.

- **B still decides what it lists.** B sends a member's books only while
  **Share this branch's books with <library>** and **List my members'
  books to <library>** are on and the member has not opted out, the same
  rules as its catalog answers.
- **Only books already downloaded on B are sent.** B doesn't download
  anything for this setting. A book a member downloads later goes up with
  the next sync pass.
- **A change restarts B's sync.** B picks up the new setting within one
  sync interval (5 minutes) and starts a full pass. Turned off, the
  members' books B stops sending are withdrawn when that pass ends. Files
  A already received stay there.
- Each change is written to A's security audit log
  (`branch_members_books_set`).

### Books in other libraries

Every branch shows the books of the library it joined, whatever its
**Keep copies on this computer** setting says. That setting only decides
whether B takes A's copies of its person's books; B takes A's work and
answers A's catalog questions and requests either way.

For each library A it joined, B:

- **Reads A's books.** On every connection and every 30 minutes, B sends
  `window.books` page by page. A answers each page (`window.page`) with
  the titles on all of A's store accounts, as A's own Library page lists
  them for a member, at most 100 works per page, grouped by A's works
  with each work's identifiers. Each edition is marked `yours` when a
  store account linked to B's owner holds it, and carries `copy` when A
  already holds its audio: the file's media type, its bitrate and the
  store it came from when A has probed it, whether it is lossless, and a
  version that changes when A's file does. Each page ends with an opaque
  cursor string, which B sends back to get the next page. A answers only
  a branch it trusts, and the frame names no user, so the mark is always
  for B's own person.
- **Keeps one copy of the list per library.** B stores each page as it
  arrives, with the copy A stated for each edition. Once the last page is
  in, it drops the books A no longer named. A read cut short keeps the
  list from the last complete read. Leaving A clears that library's list.

B's **Library** page then shows **Books in other libraries** to B's
operator and Owners: every library B is a branch of, merged into one list
by work, the person's own books marked **Yours**, with an **Only yours**
filter. Two books are the same work when their identifiers reach the
same work in B's own library, when they share a strong identifier (an
ASIN with its marketplace, or an OpenLibrary edition or work id), or when
one library groups them under one work. An ISBN alone doesn't join two
libraries' books, since one ISBN can sit on several editions. Titles are
never compared,
because work ids differ between libraries. Each entry shows which
libraries hold it, from which stores, and in which formats.

The list also has the books of every library B holds a library card for
(see [Signing in with a library card](/docs/server/sign-in/index.md#signing-in-with-a-library-card)).

The route is `GET /api/config/join/window` (→ `{libraries, cards, books}`),
for B's operator or an Owner of B.

### No loops

`GET /api/node/v1/info` reports the library's ancestry: its own library id
and every library above it.

- Joining refuses a library whose ancestry contains the joining install's
  own library id (`409 join_cycle`). So neither A ← B ← A nor
  A ← B ← C ← A can be made.
- A tree holds at most 64 libraries along one path. A join that would take
  the joining install's ancestry past that is refused
  (`409 ancestry_too_deep`).

A shared branch is the same point in the tree as its
library.

## Leaving

Open **Settings → Library → Leave library**, or run
`bookclerk libraries leave [--library <id>]`.

1. The branch tells the library first, with a `node.leaving` frame. The
   library revokes the node's credential, drops its live status, and
   closes the socket with 4403, instead of waiting for missed heartbeats.
2. The link is marked `left` and its node keys are deleted, so this
   install can never sign as that node again.
3. The link's client stops.
4. Once it has stopped, the branch deletes that library's plugin state
   (`plugin-state/link-<32 hex>/`). A Windows ACL journal still recorded
   there is revoked first; if that is refused, the state stays and the
   delete is tried again every few seconds.

A revoked branch deletes the library's plugin state the same way.

> [!NOTE]
> If the library can't be reached within 10 seconds, the branch leaves
> anyway and says the library wasn't told. Revoke the node there
> (**Settings → Nodes** or `bookclerk nodes revoke <node_id>`).

To keep a library card instead, choose **Use a library card instead**
beside the library. The branch is left only once the library hands over
the card (see
[Signing in with a library card](/docs/server/sign-in/index.md#signing-in-with-a-library-card)).

Joining again needs a new sign-in or invite. Files of books the branch
shared stay in the library, marked as from a branch that left (see
[Branch titles on the library](#branch-titles-on-the-library)).

## Not built yet

- The sharing settings and job caps are set in **Settings → Library**
  (the operator or an Owner). There is no CLI command for them yet.
- A branch answers only from its own library, not from other libraries it
  joined.
- A branch takes a library's copy only for a title its own scan found on
  a store account connected to the branch, and only when the library's
  copy came from the same store or is better than the branch's own
  download. It doesn't take a book the library holds as several audio
  files, and it doesn't compare again after the title is acquired, so a
  better copy the library gets later isn't picked up. A clerk works the
  same way.
- A clerk always takes a library's copy when it can: there is no setting
  per library card to turn it off.
- The library's name is the host of its public origin. There is no
  separate name setting.
- Uploaded objects carry content type, length and digest, but not the
  title metadata (ASIN, title, timestamps) a local acquire writes beside
  its files.
- Hosts receive jobs only. Event deliveries, and the KV, queue and EVENTS
  bindings over the node socket, aren't served to hosts. Instance
  `SECRETS` reach only a node trusted with every job.
- Pebble (ACME) doesn't run in CI.
- Store connections travel only with a sign-in join, not an invite.
- A library keeps a branch-kept account's sign-in only as fresh as the
  branch's last push: while the branch is offline, a token the branch
  refreshed is not yet there. Moving the keeper to another branch means
  disconnecting the account everywhere and adding it again.
- Adding connections later and disconnecting everywhere work only
  through links the join could bind to a person.

## Next steps

- [Node API and the live socket](/docs/internals/node-api/index.md): the
  `/api/node/v1/` routes, the node socket's handshake and frames, and the
  web app's `/api/live` socket.
- [Configuration → Branch nodes](/docs/server/configuration/index.md#branch-nodes): the
  transport modes.
- [Managing plugins](/docs/server/plugins/index.md): deploy plugins to nodes.
- [Branches](/docs/guide/branches/index.md) on the Use Bookclerk shelf: joining a
  library in plain language.
