# Public address

An ingress plugin gives the library an address on the internet without
port forwarding, a reverse proxy or a certificate of your own. Branches
and clerks away from home reach the library there.

There are two kinds of ingress plugin:

- A **relay** keeps an outbound connection to a provider (such as a
  relay Worker in your own Cloudflare account). Requests arrive over that
  connection and the plugin hands them to the library. TLS ends at the
  provider's edge.
- A **direct** plugin keeps a DNS name pointing at this computer.
  Traffic comes to the built-in TLS listener (`acme` mode), so TLS ends
  at home.

The design is in the
[ingress plugins ADR](/docs/adr/ingress-plugins/index.md). Plugin authors start
at [Public addresses](/docs/plugins/abi/index.md#public-addresses-ingress).

## Before you start

- **Claim the library first.** Ingress stays off until an Owner account
  exists, so first-run setup is never public.
- **Keep operator auth on.** Ingress stays off while
  `daemon.auth.enabled = false`, because public traffic would reach the
  library without signing in.
- **Run the daemon as a server.** Only `bookclerkd` serves a public
  address; the desktop window does not.

## Turn ingress on

1. Install and approve the ingress plugin, then deploy it on the
   computer that runs the library (see [Managing plugins](/docs/server/plugins/index.md)).
2. Make it the library's active ingress:

   ```sh
   bookclerk ingress activate <plugin>
   ```

   `<plugin>` is a plugin key (its default instance) or a plugin instance
   UUID. A library has at most one active ingress.
3. Check that it is serving:

   ```sh
   bookclerk ingress status
   ```

   `serving as` shows the public origin once the plugin reports it.

The plugin starts within a few seconds. The first origin it reports is
adopted as the library's public origin and stored in the library
database, so it survives restarts and needs no `config.toml` change.

Turn it off with `bookclerk ingress deactivate`. The adopted origin is
kept, so turning the same provider back on serves under the same name.

The same settings are on the web API as `GET` and `POST
/api/config/ingress` (the operator, or an elevated Owner).

## What the public address serves

Choose what public traffic may reach:

```sh
bookclerk ingress exposure branches   # the default
bookclerk ingress exposure library
```

| Exposure | Serves |
| --- | --- |
| `branches` (default) | The node API, the clerk and copy routes, sign-in (password, passkey, authenticator app and OIDC), the branch and clerk consent screens, and the web app's pages. Nothing else under `/api/`, and none of the legacy control routes (`/status`, `/scan`, `/acquire`, `/jobs`, `/integrations`). |
| `library` | The whole library, web app included. |

Some things never pass, whatever the exposure:

- the operator token, as a bearer token or through operator sign-in
  (`/api/auth/login`), and the operator session cookie;
- the tray handoff, operator elevation and first-Owner setup.

A refused request gets `403` with `"error": "operator_only"` or
`"error": "not_exposed"`.

> [!NOTE]
> Every request through a relay is treated as public `https` traffic,
> never as loopback. Its client address is the one the plugin reports
> from the provider's own connection metadata; forwarding headers in the
> request are dropped.

## The library's name

`integrations.public_origin` in `config.toml` still wins when it is set.
Leave it unset to use the ingress origin.

If the active plugin later reports a different name, the library keeps
serving under the old one and `bookclerk ingress status` shows the new
one as `reported origin`. Accept it with:

```sh
bookclerk ingress accept-origin
```

> [!WARNING]
> Renaming the library breaks passkeys registered under the old name and
> sign-in redirects that name it. Patrons sign in another way and add
> their passkeys again.

## Branches over the public address

Set `[daemon.node_api] mode = "tunnel"` so the node API accepts requests
the relay carries (see
[Configuration → Node API transport](/docs/server/configuration/index.md#node-api-transport)).
Branches verify the relay's edge certificate against the public roots,
as in `acme` and `proxy` mode; it can't be pinned.

Invite links name the public origin, from the daemon and from
`bookclerk nodes invite` alike.

## Not built yet

- No first-party ingress plugin ships yet. The Cloudflare relay comes
  next, then ngrok, Cloudflare Tunnel and dynamic DNS.
- `ORIGIN` carries plain HTTP requests, not WebSocket upgrades. A
  branch's live socket and a clerk's live link need one, so over a relay
  they don't connect yet; enrollment, sign-in, uploads and copies work.
- There is no web app screen yet; use the CLI or the web API.

## Next steps

- [Libraries and branches](/docs/server/branches/index.md): join a library and let branches
  in.
- [Security checklist](/docs/server/security/index.md): before you expose a server.
