One Time Secret

One Time Secret is a lightweight, self‑hostable service that delivers single‑use, expiring links for sensitive data such as passwords or API keys. From a developer standpoint, the application exposes a RESTful API and a minimal web UI that can be toggled off for pure API deployments. The core concept is simple: a secret is stored in Redis, encrypted with a server‑side key, and served via a time‑bound URL that automatically deletes the payload after the first read or upon TTL expiration. This guarantees that secrets never persist longer than intended, mitigating risks associated with email or chat logs.

Technical Stack

The project is written in Node.js (ECMAScript 2020) and uses the Express framework for routing. Data persistence relies on Redis v7+, where all models are consolidated into database 0 starting with v0.23 to simplify connection pooling and compatibility with managed Redis services. Secrets are encrypted using AES‑256-GCM with a randomly generated 32‑byte key stored in the .ots_secret file, ensuring that even if Redis is compromised, payloads remain unreadable without the key. The UI layer is built with React and served as static assets bundled by Vite, allowing the same Docker image to function both as a web server and an API gateway.

Core Capabilities

• REST API – Create, retrieve, and delete secrets via JSON endpoints (POST /api/v1/secrets, GET /s/:id). The API accepts optional passphrases and custom TTL values, returning a one‑time URL.
• Passphrase Protection – Secrets can be wrapped in an additional HMAC‑based passphrase layer, adding a client‑side secret that is never stored on the server.
• Email Delivery – SMTP or SendGrid integration allows automatic email of secret links, useful for automated workflows.
• Custom Domains – The HOST environment variable can point to any domain, enabling branded self‑hosted deployments.
• Webhooks – Post‑creation and post‑view events can be exposed via configurable webhook URLs, facilitating audit trails or downstream actions.

Deployment & Infrastructure

The application ships as a Docker image, but can also be run natively on any Linux host with Node.js and Redis. Containerization is straightforward: expose ports 3000 (HTTP) and 6379 (Redis), mount a volume for the .ots_secret key, and set environment variables for SSL, authentication, and email. For production, the image recommends SSL=true and a reverse proxy (NGINX or Traefik) to terminate TLS. Horizontal scaling is supported by running multiple stateless API instances behind a load balancer; Redis acts as the single source of truth, so stateful data remains consistent across replicas.

Integration & Extensibility

Developers can extend One Time Secret in several ways:

• Plugin Hooks – The API accepts custom middleware, allowing integration with OAuth providers or internal authentication systems.
• Webhook Subscribers – External services can listen to secret events and trigger CI/CD pipelines, ticketing systems, or compliance logs.
• CLI Client – A lightweight command‑line tool (available in the repo) wraps API calls, making it easy to embed secret generation into scripts.
• Open Source – The codebase is MIT‑licensed, enabling modification of the encryption scheme or UI without vendor lock‑in.

Developer Experience

Configuration is declarative: a single config.yaml file plus environment variables controls all aspects of the application. Documentation is concise yet thorough, covering Docker usage, Redis migration, and API reference. The community is active on GitHub issues, with rapid responses to feature requests. The project’s lean footprint (under 200 MB for the Docker image) and minimal dependencies reduce maintenance overhead, making it suitable for internal tooling or security‑critical applications.

Use Cases

• Internal Password Sharing – DevOps teams can generate one‑time links for temporary credentials without leaving secure channels.
• Secure API Keys – CI/CD pipelines can inject secrets into build environments, guaranteeing keys expire after a single use.
• Incident Response – Security teams can share forensic artifacts or access tokens that self‑destruct after review.
• Compliance Auditing – With webhook integration, every secret access can be logged to a SIEM system for audit trails.

Advantages

One Time Secret offers performance (Redis in‑memory storage), flexibility (full control over encryption and TTLs), and cost‑effectiveness (free, open source). Unlike third‑party services that impose usage limits or require paid plans, self‑hosting eliminates vendor lock‑in and allows integration into existing infrastructure. The combination of a simple API, strong encryption, and container‑friendly deployment makes it an attractive choice for developers needing secure, transient data sharing without the overhead of building a custom solution.