Skip to content

SrinivasJoshi/oneTimeSecret

Repository files navigation

OneTimeSecret (Ephemeral Secret Sharing Service)

This project implements a secure service for sharing text-based secrets ephemerally. It follows a zero-knowledge principle, meaning the server never has access to the plaintext secrets or decryption keys. Secrets are encrypted client-side, stored temporarily on the server, and can only be viewed once within a 1-hour time limit.

Core Features

  • Client-Side Encryption: Secrets are encrypted/decrypted directly in the user's browser.
  • Zero-Knowledge Server: The server only stores encrypted data and cannot decrypt it.
  • View Once: Secrets are permanently deleted after being successfully viewed once.
  • Time-Limited: Secrets expire automatically after 1 hour.
  • Secure: Uses HTTPS, standard security headers (CSP, HSTS etc.), and API rate limiting.

Tech Stack

  • Backend: Node.js, Express.js
  • Database: PostgreSQL
  • Frontend: React, TailwindCSS, Web Crypto API
  • Containerization: Docker, Docker Compose
  • Testing: E2E Tests (Cypress)

Setup and Running

1. Prerequisites

  • Docker Desktop (or Docker Engine + Docker Compose) installed.
  • Node.js (for potential local development/testing outside Docker).

2. Environment Variables

Create a .env file in the project root directory by copying .env.example:

cp .env.example .env

Key environment variables to configure:

# PostgreSQL Settings
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_strong_password
POSTGRES_DB=onetimesecretdb

# Backend Settings
NODE_ENV=production
PORT=9000

# NGINX Settings
NGINX_ENVIRONMENT=local  # Options: local, production
VITE_API_URL=/api

For production, set:

NGINX_ENVIRONMENT=production

3. Build and Run with Docker Compose

docker-compose up --build -d
  • --build: Forces Docker to rebuild the images if changes were made.
  • -d: Runs the containers in detached mode (in the background).

4. Accessing the Application

  • In development: http://localhost:80
  • In production: Configure your domain in the Nginx configuration files

5. Stopping the Services

docker-compose down

To remove the persistent database volume as well (use with caution!):

docker-compose down -v

API Endpoints

  • POST /api/secrets: Creates a new secret.
    • Request Body: { "encryptedSecret": "base64-encoded-encrypted-text" }
    • Response (Success 201): { "referenceId": "unique-secret-id" }
    • Response (Error): Standard HTTP error codes (e.g., 400, 500).
  • POST /api/secrets/:id/consume: Attempts to validate and consume (view) a secret.
    • Request Body: (Empty)
    • Response (Success 200): { "encryptedSecret": "base64-encoded-encrypted-text" } - Contains the encrypted secret needed for client-side decryption.
    • Response (Error 404/410): If the secret is not found, already viewed, or expired.
    • Response (Error 429): If rate limit is exceeded.

Security Model

The system relies on client-side encryption. The server receives only the encrypted data and a referenceId. The decryption key is kept solely within the URL fragment (#key) generated by the client, which is never sent to the server. Security depends on the user sharing the full URL securely. The server ensures secrets are view-once and expire after 1 hour.

Production Deployment

SSL Configuration

For production deployment with HTTPS:

  1. Obtain SSL certificates for your domain:
sudo apt update
sudo apt install certbot
sudo certbot certonly --standalone -d yourdomain.com -d www.yourdomain.com
  1. Ensure your Nginx configuration maps the certificates correctly:
ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;
  1. Mount the certificates in your docker-compose.yml:
nginx:
  volumes:
    - /etc/letsencrypt:/etc/letsencrypt:ro
  1. Set the environment to production:
NGINX_ENVIRONMENT=production
  1. Rebuild and restart:
docker-compose down
docker-compose up --build -d

Firewall Configuration

Make sure ports 80 and 443 are open on your server:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

Development

Frontend Development

To work on the frontend independently:

cd frontend
npm install
npm run dev

Backend Development

To work on the backend independently:

cd backend
npm install
npm run dev

E2E Testing

The project includes Cypress tests in the frontend/cypress directory:

cd frontend
npm run test:e2e

Configuration Files

Nginx Configuration

The project includes multiple Nginx configuration files:

  • nginx/nginx.local.conf: Used for local development
  • nginx/nginx.conf: Used for production with SSL

The active configuration is determined by the NGINX_ENVIRONMENT variable in your .env file.

Frontend API URL

The API URL used by the frontend is configured through the VITE_API_URL environment variable. This is set at build time and passed to the frontend application.

Security Analysis & Testing

  • A basic threat model and mitigation analysis should be performed and documented separately.
  • The project includes E2E tests using Cypress to verify core flows and security features.

About

No description, website, or topics provided.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published