Security and storage

Application access

Brokerr protects its UI and API with an authenticated session. Session cookies are HTTP-only, use a path scope, and receive the Secure flag when the request is known to be HTTPS through a trusted proxy. State-changing browser requests are checked against trusted origins.

Allowed hosts are enforced. Forwarded client and scheme headers are honored only when the immediate peer belongs to the configured trusted proxy IP/CIDR list.

Credential encryption

Provider credentials are encrypted with AES-256-GCM before SQLite storage. The master key must decode to exactly 32 random bytes and comes from exactly one of:

• security.master_key_file (recommended), or
• security.master_key in bootstrap YAML.

Authenticated additional data binds ciphertext to credential scope, owner ID, and name. Keep the master key separate from the database backup. Losing it makes credentials unrecoverable; exposing it together with the database exposes them.

Use the supported CLI key-rotation command when replacing the key. Do not edit encrypted rows manually.

SQLite

Brokerr automatically configures existing and new databases with:

journal_mode=WAL
synchronous=NORMAL
busy_timeout=10000 ms
foreign_keys=ON

WAL lets readers continue during frequent run/log writes. synchronous=NORMAL is the intended durability/performance balance for this application. No database recreation is required when WAL is first enabled.

Back up SQLite using a consistent database backup while Brokerr is stopped or a SQLite-aware online backup. Do not copy only app.db while an active WAL contains uncheckpointed transactions, and never delete -wal or -shm files while running.

Logs and telemetry

Structured run logs attribute sanitized HTTP operations to source, target, or core. Stored request telemetry excludes query strings, headers, authorization, cookies, tokens, and bodies. Provider payloads are reduced to safe operation details before UI display.

Brokerr does not include a remote crash-report upload service or general usage telemetry. Data leaves the instance only for configured provider APIs, the hosted auth handoff/refresh when selected, Plex account services used by enabled features, and AniBridge mapping release retrieval.

Containers and files

Persist the database, config.yml, master key file, artwork, mappings, exports, and source observations. Restrict filesystem access to the service user. Use a reverse proxy for HTTPS and request limits; never expose the database or data directory through the web server.