Shhh

Shhh is a lightweight Flask‑based web service that lets users create, encrypt, and share secrets with fine‑grained control over expiration, access attempts, and automatic cleanup. The application’s core goal is to eliminate plain‑text sensitive data from emails or chat logs by providing a self‑hosted, end‑to‑end encrypted channel that can be deployed on any private server or cloud instance. From a developer’s perspective, Shhh is intentionally minimalistic yet extensible, making it an ideal starting point for building secure knowledge‑sharing pipelines or integrating encrypted payloads into existing workflows.

Key Features

• Zero‑knowledge storage – Secrets are encrypted with a per‑secret Fernet key derived from a user‑provided passphrase, random salt, and 100 000 PBKDF2 iterations. The database never stores the plaintext or any part of the key, ensuring that even a compromised DB cannot reveal secrets.
• Automatic lifecycle management – A background worker (Celery or a simple scheduler) deletes secrets once the expiry date passes, after successful decryption, or when the maximum number of failed attempts is reached.
• RESTful API – A Swagger‑documented API exposes endpoints for creating, retrieving, and deleting secrets. The shhh-cli Go client demonstrates how to consume this API programmatically.
• One‑click Heroku deployment – Pre‑configured Procfile, runtime.txt, and docker-compose files allow developers to spin up a fully functional instance behind Gunicorn, Nginx, and PostgreSQL with minimal effort.

Technical Stack

The codebase follows a classic Flask “app factory” pattern with blueprints for modularity. The secrets table stores only the ciphertext, a UUID link identifier, expiry timestamp, and attempt counters—no passphrase or key material.

Core Capabilities & APIs

• Create Secret (POST /api/v1/secrets) – accepts plaintext, expiry, passphrase, and optional metadata; returns a unique URL and the passphrase hash (for client display only).
• Retrieve Secret (GET /api/v1/secrets/<uuid>) – requires the correct passphrase; on success, returns decrypted payload and removes the record.
• Admin Endpoints – list pending secrets, audit logs, force deletion (protected by API key).
• Webhooks – optional payload to notify external services upon secret creation or deletion.

These endpoints are stateless and can be consumed by any HTTP client, making integration into CI/CD pipelines or custom UIs straightforward.

Deployment & Infrastructure

Shhh is designed for self‑hosting on any platform that supports Docker or Python. The repository ships with:

• docker-compose.yml for local development (Flask + Gunicorn + Nginx + PostgreSQL).
• A Heroku buildpack stack (Python 3, Gunicorn, Nginx) and a one‑click deploy button.
• Environment variable templates (dev-docker-postgres.env) that specify database URLs, secret keys, and optional Celery broker settings.

For larger deployments, the architecture scales horizontally by running multiple Flask workers behind a load balancer and using a shared PostgreSQL cluster. The background job can be distributed via Redis or RabbitMQ if Celery is enabled.

Integration & Extensibility

• Plugin System – The Flask application exposes a signal (secret_created, secret_deleted) that third‑party modules can hook into for custom actions (e.g., audit logging, Slack notifications).
• Custom Encryption – While Fernet is the default, developers can override the encryption routine by providing a custom encrypt/decrypt pair in the config.
• CLI Client – The Go‑based shhh-cli demonstrates how to call the API, and its source can be forked for custom tooling or batch secret uploads.
• Webhooks & Callbacks – Developers can register external URLs to be notified of secret lifecycle events, enabling integration with monitoring or compliance systems.

Developer Experience

The project adheres to standard Python packaging practices (setup.py, requirements.txt) and includes comprehensive unit tests (coverage badges on Codecov). Documentation is split between a human‑readable README, Swagger API docs, and inline docstrings. The community is active on GitHub Issues; contributors can easily add new features or fix bugs thanks to the clear modular structure.

Use Cases

1. Secure Ticketing – A support team can generate time‑bound API tokens for customers without exposing them in email.
2. One‑time Password Delivery – Integrate Shhh into a login flow to deliver OTPs via encrypted links.
3. Compliance‑aware Data Sharing – Organizations can enforce automatic deletion of sensitive documents after a policy‑defined window.
4. DevOps Secrets Rotation – CI pipelines can fetch encrypted secrets from Shhh, decrypt them at runtime, and discard them immediately.

Advantages Over Alternatives

• Performance – A single Flask process can handle thousands of concurrent secret requests; encryption/decryption is lightweight (AES‑256 in Fernet).
• Flexibility – Full control over storage, encryption algorithm