Secret — Secure, Zero-Knowledge Encrypted Note & File Sharing

Share passwords, notes, and files securely with end-to-end encryption. Your data is encrypted in the browser using XChaCha20-Poly1305 — the server never sees your content. Self-hosted with a single Docker container. No accounts, no tracking, no logs.

A modern, open-source alternative to PrivateBin, OneTimeSecret, and Yopass — built with Svelte 5, Hono, and TypeScript.

Live demo: secret.larger.io

Table of Contents

• Features
• Comparison
• Quick Start
• SDK
• How It Works
• Configuration
  • S3 Storage (optional)
• Updating
• Reverse Proxy
• Development
• Security
• License
• Contributing

Features

• Zero-knowledge encryption — XChaCha20-Poly1305 (client) + AES-256-GCM (server)
• Text & files — Notes, documents, images, any file type. Up to 10 files per note, drag & drop.
• Burn after read — Destroyed after the first view
• Password protection — Optional, Argon2id key derivation
• Auto-expiry — 5 minutes to 30 days
• Read limits — Auto-delete after N reads
• Delete token — Manually delete a note at any time
• File previews — Images, PDF, video, audio rendered in-browser after decryption
• Chunked uploads — Stream large files in chunks with progress tracking (up to 500 MB)
• S3 storage — Optional S3-compatible backend (AWS, MinIO, R2) for large files
• QR codes — Share links easily on mobile
• i18n — 10 languages (en, fr, es, de, pt, it, ja, zh, ru, ko); add a new locale by dropping a JSON file in messages/
• Self-hostable — Single Docker container, customizable branding

Comparison

Comparison reflects publicly documented features at the time of writing. See each project's docs for the latest details.

Quick Start

git clone https://github.com/largerio/secret.git
cd secret
cp .env.example .env

# Generate a server encryption key (REQUIRED) — pick one
openssl rand -base64 32
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
# Paste the output into .env as SERVER_ENCRYPTION_KEY

docker compose up -d

Open http://localhost:3000. API documentation is available at /api/v1/docs (Scalar).

SDK

Use the JavaScript/TypeScript SDK to interact with any Secret instance programmatically:

npm install @secret/sdk-js

import { SecretClient } from "@secret/sdk-js";

const client = await SecretClient.create({
  baseUrl: "https://secret.example.com",
  apiKey: "your-api-key",
});

// Create a note
const { id, keyFragment } = await client.createNote({ text: "Hello, World!" });
const shareUrl = client.buildShareUrl(id, keyFragment);

// Read a note from a share URL
const parsed = SecretClient.parseShareUrl(shareUrl);
const { payload } = await client.readNote(parsed.id, parsed.keyFragment);
console.log(payload.text); // "Hello, World!"

How It Works

Browser                                   Server
┌──────────────────────┐             ┌──────────────────┐
│ 1. Generate key      │             │                  │
│ 2. Encrypt (XChaCha) │──ciphertext►│ 3. Encrypt (AES) │
│                      │             │ 4. Store         │
│ URL: /note/id#key    │             │                  │
│        └─ never sent │             │ Never sees key   │
└──────────────────────┘             └──────────────────┘

The encryption key lives in the URL fragment (#key), which browsers never send to the server.

Configuration

All settings via environment variables. See .env.example for the full list.

Warning: Never change SERVER_ENCRYPTION_KEY after deployment — all existing notes become unreadable.

S3 Storage (optional)

Files are stored locally by default. For larger files, enable S3-compatible storage:

STORAGE_BACKEND=s3
S3_BUCKET=my-bucket
S3_REGION=us-east-1
S3_ENDPOINT=http://minio:9000    # MinIO / R2
S3_ACCESS_KEY_ID=your-key
S3_SECRET_ACCESS_KEY=your-secret
S3_FORCE_PATH_STYLE=true         # Required for MinIO
MAX_FILE_SIZE=104857600           # 100 MB

Compatible with AWS S3, MinIO, and Cloudflare R2.

Updating

docker compose pull           # Pull new image
docker compose up -d          # Restart
docker image prune -f         # Clean up

Data lives in a Docker volume — updates never delete your notes.

Reverse Proxy

Caddy (automatic HTTPS):

secret.example.com {
    reverse_proxy localhost:3000
}

Nginx:

server {
    listen 443 ssl;
    server_name secret.example.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        client_max_body_size 600M;
    }
}

Set client_max_body_size to at least MAX_CHUNKED_FILE_SIZE (or MAX_FILE_SIZE if chunked uploads are not used). The example uses 600M as a safety margin above the 500 MB default.

Development

pnpm install
pnpm dev          # API + web dev servers
pnpm test         # 422 tests, 100% backend coverage
pnpm lint         # Biome lint + format
pnpm build        # Production build
pnpm typecheck    # TypeScript strict

Structure

apps/api/         Hono API (Node.js, SQLite, Drizzle ORM, OpenAPI)
apps/web/         SvelteKit frontend (Svelte 5, Tailwind CSS 4)
packages/sdk-js/  JS/TS SDK (SecretClient, encrypt/decrypt flows)
packages/crypto/  libsodium + AES-256-GCM encryption
packages/shared/  Zod schemas, types, constants, crypto test vectors
messages/         i18n (10 languages)

Security

See SECURITY.md for the vulnerability disclosure policy.

License

MIT

Contributing

See CONTRIBUTING.md.