Hemmelig

Hemmelig is a client‑side encrypted pastebin designed for developers who need a self‑hosted, privacy‑first secret sharing service. From the moment a user enters data in the browser, it is encrypted with TweetNaCl and never leaves the client as plaintext. Only a base64‑encoded ciphertext is persisted on the server, while the decryption key lives solely in the URL fragment (#…). This guarantees that even a full database dump yields no usable secrets.

Architecture

The service is intentionally stateless beyond the database; this simplifies horizontal scaling. Each instance can serve any number of secrets, and a load balancer can distribute traffic across replicas.

Core Capabilities

• API Endpoints – /api/secret for creation and /api/secret/:id for retrieval. Requests are authenticated via optional API keys (for organizational use) and all inputs are validated server‑side.
• Expiration & View Limits – Secrets can be configured to expire after a user‑defined time or after a maximum number of views. The server tracks view counts atomically using PostgreSQL UPDATE ... RETURNING.
• IP Restrictions – Optional whitelist/blacklist of IP ranges is enforced per secret; the middleware compares req.ip against stored CIDR blocks.
• Password Protection – If a password is set, the client derives a key via PBKDF2 and encrypts the decryption key. The server stores only the salted hash of the password; on retrieval, the client verifies locally before attempting decryption.
• File Uploads – Authenticated users can upload files that are encrypted client‑side and stored as binary blobs in the database. Size/type limits are configurable via environment variables.

Deployment & Infrastructure

Hemmelig is fully self‑hostable. The Docker image can be run on any Linux host, and the only external requirement is a PostgreSQL instance. For production deployments:

1. Container Orchestration – Deploy with Docker Swarm or Kubernetes; the stateless API can be replicated, and a shared PostgreSQL cluster (e.g., Patroni) provides HA.
2. Scaling – Because secrets are stored in a single database, read scaling can be achieved with read replicas. Write scaling is limited by the database write lock but remains modest due to the lightweight payloads.
3. HTTPS – The application expects HTTPS termination at a reverse proxy (NGINX/Traefik). Since the decryption key is only in the fragment, it never traverses the proxy.
4. Resource Footprint – A single instance comfortably handles thousands of secrets per day with <200 MiB RAM and a 0.5 GHz CPU.

Integration & Extensibility

• Webhooks – Developers can register a webhook URL to receive notifications when a secret is created or viewed. The payload includes metadata but never the plaintext.
• Plugin Hooks – The API exposes a simple middleware hook system; third‑party developers can inject custom authentication or analytics layers without modifying core code.
• Custom Domains – The service can be configured to serve on any domain; the client side reads window.location for URL generation, making it trivial to embed Hemmelig within a larger application.
• SDKs – While no official SDK exists, the minimal REST interface makes it straightforward to write wrappers in Go, Python, or Rust.

Developer Experience

• Configuration – All tunable parameters are environment variables (SECRET_TTL, MAX_VIEWS, IP_WHITELIST, etc.). The Docker Compose file ships with sensible defaults.
• Documentation – The README, API comments, and inline TypeScript types provide clear guidance. The project also publishes an OpenAPI spec generated by swagger-jsdoc.
• Community & Support – The repository is actively maintained, with a SonarCloud quality gate and continuous integration. Issues are triaged quickly, and contributors can submit PRs to add features or fix bugs.
• Licensing – The application is released under an MIT‑style license, allowing unrestricted use in commercial or private projects.

Use Cases