Security Considerations

EventSourcingDB is designed to operate in internal, trusted environments. It assumes that infrastructure-level protections are in place and focuses on providing secure defaults for core interactions without introducing unnecessary complexity. There are no user accounts, no built-in encryption, and no roles or permissions. Instead, the system relies on simple and well-understood security measures, including token-based access and strict network boundaries.

API Token and Access Control#

All access to EventSourcingDB – including the HTTP API and the management UI – is gated by a single API token. This token must be passed in the Authorization header using the Bearer scheme. Any request for your data that lacks a valid token is rejected with a 401 Unauthorized response; only the few routes that check liveness or describe the API answer without it, as listed under Logging, Monitoring, and Surface Area.

There is no concept of users, sessions, or roles. Anyone who knows the token has full access to all functionality. This all-or-nothing model is intentional. It eliminates ambiguity and simplifies both deployment and auditing. While more granular access control may be introduced in the future, the current model ensures that authentication is deterministic and easily enforced at the network level.

Changed in 1.3When generating an API token, choose a strong random value. A server on a data directory requires a length of at least 32 characters, and refuses to start with a shorter token, since a short one could be guessed by trying; a mix of uppercase, lowercase, and digits is recommended. Avoid predictable values or shared secrets across environments. Tokens should never be transmitted in URLs or logged by clients or reverse proxies.

Network Isolation and Secure Deployment#

EventSourcingDB is not designed to be exposed to the public internet. It should be deployed behind firewalls, within private subnets, or in otherwise secured environments where only trusted systems have network access. This includes both production environments and staging setups where real data may be present.

Recommended deployment options include placing EventSourcingDB behind a reverse proxy, API gateway, or ingress controller that handles TLS termination, request validation, or additional authentication. The database should only be accessible to internal services and automation tools that are authorized to read or write events.

When deploying with Docker, ensure that HTTP is not enabled. The system supports HTTPS by default, and TLS certificates must be provided explicitly via configuration. The recommended production setup includes mounting a persistent data directory, supplying certificate and key files, and disabling HTTP even if it is not enabled by default. This prevents accidental misconfiguration and ensures that all communication is encrypted in transit.

Logging, Monitoring, and Surface Area#

All log output from EventSourcingDB is written to standard output in JSON format. This output can be collected and aggregated using standard log forwarding pipelines. The system logs startup information, warnings, errors, and fatal conditions but does not log incoming requests or sensitive values like API tokens. This reduces the risk of accidental data leakage and supports compliance with common operational policies.

Changed in 1.3Monitoring endpoints include /api/v2/system/ping and /api/v2/system/health. The former is unauthenticated and suitable for basic liveness checks. The latter requires a valid API token and returns health status metadata. Besides ping, which the v1 API still answers at /api/v1/ping as well, the OpenAPI definitions at /api/v2/system/openapi and, for the v1 API, at /.well-known/openapi, and the API catalog at /.well-known/api-catalog answer without a token as well; they describe the API, not your data. While these endpoints are read-only, they may expose internal state or configuration details and should therefore be protected by the same network isolation as the rest of the system.

The management UI is optional and disabled by default. If enabled, it exposes a visual interface for exploring stored data and monitoring system health. It is subject to the same token-based access as the API and should not be exposed outside of trusted environments. If other observability tooling is already in use, the UI may be unnecessary and can be omitted from production deployments.

Added in 1.3The UI is served with security headers under which it runs no scripts from elsewhere and cannot be shown in a frame of another page, see Using the Management UI.

Secure by Simplicity#

EventSourcingDB follows a principle of minimalism in its security design. Instead of introducing partial role models, complex authorization rules, or plugin-based policies, it keeps the surface area small and behavior predictable. It does not make assumptions about the user's infrastructure and relies on no external services or external databases that might obscure behavior or introduce hidden risks.

What the system does guarantee is clear: all access to your data is authenticated with a single token, all data is immutable and ordered, and no internal state becomes visible unless explicitly requested. There are no message queues and no hidden data flows that could compromise data integrity or observability. What EventSourcingDB does in the background concerns only its own data, such as watching the free disk space so that it stops accepting writes when the disk runs low.

Added in 1.3In the background, EventSourcingDB also writes what its write-ahead log holds into its data files in checkpoints, and rebuilds its indexes once after an upgrade. If either fails, it logs the failure and tries again until it succeeds.

The result is a system that is easy to reason about and straightforward to secure. With proper deployment practices – especially network isolation and careful token handling – EventSourcingDB offers a strong foundation for secure and compliant event storage, suitable for both development and production environments.

For how to configure the API token and restrict network access, see Security and Access Control.