# 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.

For how to configure the API token and restrict network access, see **[Security and Access Control](/docs/eventsourcingdb/security-and-access-control)**.