Security Considerations

This guide outlines the security-related aspects of running EventSourcingDB in production. It covers authentication, network isolation, secure deployment practices, and how the system fits into a secure infrastructure. The goal is to provide a clear understanding of what EventSourcingDB does — and does not — enforce, and what responsibilities fall to the application or operations team.

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 lacking a valid token is rejected with a 401 Unauthorized response.

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.

When generating an API token, choose a strong random value. A minimum length of 32 characters with 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.

Monitoring endpoints include /api/v1/ping and /api/v1/health. The former is unauthenticated and suitable for basic liveness checks. The latter requires a valid API token and returns health status metadata. 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.

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 avoids any background services, external databases, or automatic retries that might obscure behavior or introduce hidden risks.

What the system does guarantee is clear: all access is authenticated with a single token, all data is immutable and ordered, and no internal state becomes visible unless explicitly requested. There are no implicit operations, background schedulers, or message queues that could compromise data integrity or observability.

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.