DOCSEARCHbyAlgolia
Submit Docs

Hemmelig Documentation

repository·v7·Indexed 22 days ago

https://github.com/hemmeligorg/hemmelig.app

An encrypted secret sharing platform featuring a zero-knowledge architecture using client-side AES-256-GCM encryption. Hemmelig allows users to share sensitive information via self-destructing links with configurable expiration and view limits. The project includes a Go-based CLI, a TypeScript library with a `createSecret` function, and a Hono-based application server deployable via Docker.

Tokens
34.1K
Snippets
83
Records
159
Agent score
75%

What's inside Hemmelig

  1. How Hemmelig works and its security model

    v7

    Hemmelig is an encrypted secret sharing platform using a zero-knowledge architecture.

    The Workflow:

    1. Users enter a secret on the web interface or a self-hosted instance.
    2. Users configure expiration times, view limits, and optional passwords.
    3. A unique link is generated and shared with the recipient.
    4. The secret is automatically deleted after it has been viewed or the expiration time is reached.

    Security Model: All encryption is performed via client-side AES-256-GCM encryption in the user's browser. The server only stores the encrypted data and never has access to the plaintext secrets or the encryption keys.

  2. Implement Client-Side Encryption

    v7

    Critical Security Requirement: Generated SDKs only handle API communication; they do not encrypt data. You must implement client-side encryption using AES-256-GCM before sending any secrets to the Hemmelig API.

    To ensure security, the decryption key should be passed via URL fragments (e.g., #decryptionKey=...). URL fragments are handled by the client and are never sent to the server, preventing the key from being exposed to the API.

  3. Understand the E2E test database and credentials

    v7

    The end-to-end tests use a dedicated, isolated test database located at database/hemmelig-test.db.

    Lifecycle:

    1. Created fresh before each test run.
    2. Migrated with the latest schema.
    3. Seeded with a test user.
    4. Deleted after tests complete.

    Automatic Test User Credentials:

    • Email: e2e-test@hemmelig.local
    • Username: e2etestuser
    • Password: E2ETestPassword123!

  4. Configure Hemmelig via Environment Variables

    v7
    When HEMMELIG_MANAGED is set to true, you can configure the following categories of settings using environment variables. Note that once enabled, database-stored settings are ignored, but the database is still used for secrets, users, and other application data.

  5. How Hemmelig security works

    v7

    Hemmelig uses a zero-knowledge, client-side encryption model to ensure privacy:

    • Client-side encryption: All encryption happens locally on your machine before data is sent to the server.
    • Zero-knowledge: The server never sees your plaintext secrets or encryption keys.
    • URL fragments: When not using a password, the decryption key is stored in the URL fragment (#decryptionKey=...). Because fragments are not sent to the server in HTTP requests, the server remains unaware of the key.
    • Self-destructing: Secrets are automatically deleted from the server after the specified number of views or when the expiration time is reached.

  6. How Hemmelig's zero-knowledge architecture works

    v7

    Hemmelig employs a zero-knowledge architecture where all encryption and decryption occur exclusively within the user's browser using the Web Crypto API. The server is never exposed to plaintext secrets or encryption keys.

    The Workflow

    1. Secret Creation: The secret is encrypted in the browser before transmission to the server.
    2. Key Transmission: The decryption key is passed via a URL fragment (#decryptionKey=...). Because URL fragments are not sent to the server by browsers (per RFC 3986), the key remains invisible to the Hemmelig server, reverse proxies, CDNs, and server logs.
    3. Secret Retrieval: The browser fetches the encrypted data and performs decryption locally.

    Security Visibility

    ComponentSees the Key?
    Your browser✅ Yes
    Hemmelig server❌ No
    Reverse proxies (nginx, etc.)❌ No
    CDNs (Cloudflare, etc.)❌ No
    Server access logs❌ No
    Network monitoring tools❌ No

    Warning: Browser history and bookmarks may store the full URL including the fragment. Use with caution in shared environments.

  7. Security model of Hemmelig CLI

    v7

    Hemmelig uses a client-side encryption model to ensure the server never sees plaintext data:

    • Local Encryption: All encryption happens locally on your machine using AES-256-GCM.
    • Key Derivation: Keys are derived using PBKDF2 with 600,000 iterations.
    • Zero-Knowledge Transfer: The decryption key is passed via the URL fragment (#decryptionKey=...), which is a client-side mechanism that is never sent to the server.
    • Server Role: The server only stores the encrypted data blobs.

  8. How Secret Requests work

    v7

    Secret Requests allow you to securely request sensitive information from others. Instead of receiving a secret directly, you provide a link that allows the creator to submit an encrypted secret to you.

    The Workflow:

    1. Create a Request: You configure settings (expiration, max views, etc.) and receive a unique request link.
    2. Share the Link: Send the link to the person who holds the secret.
    3. Submission: The creator enters the secret in their browser. The secret is encrypted locally in their browser. They receive a decryption key which they must send back to you.
    4. Viewing: You use the secret URL from your dashboard and provide the decryption key received from the creator to view the content.

    Security Model:

    • Client-side encryption: Secrets are encrypted in the creator's browser before being sent to the server.
    • Decryption key isolation: The decryption key is passed via a URL fragment (#decryptionKey=...), meaning it never reaches the Hemmelig server.
    • Token Security: Request links use 256-bit cryptographically secure tokens and utilize timing-safe validation.

  9. Security Best Practices for Hemmelig API

    v7

    When building clients for the Hemmelig API, follow these security principles:

    • Client-side encryption: Encrypt all secret content locally. The server is a zero-knowledge storage provider for the secret content.
    • Decryption keys: Never transmit decryption keys to the server. Use URL fragments (e.g., https://your-instance.com/api/secrets/abc123xyz#key=your_key) to pass keys to the client; fragments are not sent to the server by browsers.
    • Rate limiting: Be prepared for rate limiting based on the specific instance's configuration.

  11. Configure Generic OAuth 2.0 / OpenID Connect Providers

    v7
    You can integrate any OAuth 2.0 or OpenID Connect compatible provider (like Authentik, Authelia, Keycloak, or Okta) using the HEMMELIG_AUTH_GENERIC_OAUTH environment variable. This variable accepts a JSON array of provider configuration objects.

  12. Deploy Hemmelig using Docker

    v7

    The recommended way to deploy Hemmelig is via Docker. You must provide a DATABASE_URL, a BETTER_AUTH_SECRET, and a BETTER_AUTH_URL via environment variables. It is recommended to use volumes for persistent storage of the database and uploads.

    docker run -d \
  --name hemmelig \
  -p 3000:3000 \
  -v hemmelig-data:/app/database \
  -v hemmelig-uploads:/app/uploads \
  -e DATABASE_URL="file:/app/database/hemmelig.db" \
  -e BETTER_AUTH_SECRET="$(openssl rand -base64 32)" \
  -e BETTER_AUTH_URL="https://your-domain.com" \
  hemmelig/hemmelig:v7