zefer

Zefer

Share secrets, not risks.

Client-side encryption tool that converts text and files into password-protected .zefer files using AES-256-GCM. 100% browser-based — no servers, no traces, no cookies.

Live Demo · CLI (zefer-cli) · Report Bug · Request Feature · Security Report · Documentation

---

Table of Contents

• About
• CLI
• Features
• Architecture
• Binary File Format
• Quick Start
• Tech Stack
• Project Structure
• Routes
• URL Parameters
• Testing
• Security Model
• Legal Compliance
• Deployment
• AI Integration
• Contributing
• Documentation
• Author
• Support
• License

About

Zefer encrypts your secrets into password-protected .zefer files using AES-256-GCM with PBKDF2-SHA256 key derivation, entirely in your browser. Nothing ever leaves your device unencrypted.

• Zero-knowledge — the server never sees plaintext, passphrases, or encryption keys
• No cookies, no analytics, no trackers — zero data collection
• Open source — MIT license, fully auditable
• Standards-based — Web Crypto API, CompressionStream API, no third-party crypto dependencies

CLI

Zefer has an official command-line companion — zefer-cli — for scripting, automation, and terminal workflows. .zefer files are fully cross-compatible between the web app and the CLI.

Via npm (recommended):

npm install -g zefer-cli

zefer encrypt report.pdf -p mypassword
zefer decrypt report.pdf.zefer -p mypassword
zefer keygen --mode secure --length 64
zefer info secret.zefer

Standalone binary (no Node.js required): download for Linux x64 · Linux ARM64 · macOS Intel · macOS Apple Silicon · Windows x64

As a library (v1.3.0+): since v1.3.0, zefer-cli also exposes a programmatic API (ESM + CommonJS), so you can embed the same engine in your own Node.js code:

import { encodeZefer, decodeZefer, generateWithOptions, analyzePassword } from "zefer-cli";

In total, zefer-cli runs three ways: CLI, MCP server (zefer mcp), and library — all producing cross-compatible .zefer files. Full library guide: zefer.carrillo.app/library.

Features

Encryption

• AES-256-GCM with PBKDF2-SHA256 (300k-1M iterations)
• Text and file mode (images, ZIPs, PDFs, etc.)
• Chunked encryption (16MB per chunk, unique IVs)
• Gzip/Deflate compression via CompressionStream API
• Dynamic file limits (auto-detects RAM, CPU, GPU)

Security Layers

• Reveal key — share without exposing the main passphrase
• Dual passphrase — two-person authorization
• Secret question with PBKDF2-hashed answer (100k iterations)
• IP restriction (IPv4/IPv6 allowlist)
• Built-in expiration (30min to 2 weeks)
• Max decryption attempts

Developer Experience

• URL parameters for workflow automation
• Secure key generator — 7 modes (Unicode, Secure, Alphanumeric, Hex, Base58 readable, PIN, UUID v7)
• /generator — advanced password lab: batch generation (up to 50), per-key scoring, attack scenarios, NIST/OWASP/post-quantum compliance, copy/download .txt
• /analyzer — .zefer file inspector: public header, KDF level, compression — no passphrase needed
• Real-time progress bar with device benchmarking
• Drag-and-drop file upload
• 969 tests, 100% coverage (statements, branches, functions, lines)

Accessibility & i18n

• WCAG 2.1 AA (4.5:1 contrast ratio)
• Light/dark mode (auto-detects OS preference)
• 3 languages: Spanish, English, Portuguese
• Mobile-first responsive design
• Respects prefers-reduced-motion

Architecture

Browser (client-side only)
  │
  ├── Text / File input (click or drag-and-drop)
  ├── Passphrase + options
  ├── PBKDF2 key derivation (Web Crypto API)
  ├── AES-256-GCM chunked encryption (Web Crypto API)
  ├── Optional: Gzip/Deflate compression (CompressionStream API)
  ├── Optional: Reveal key (second encrypted block)
  └── .zefer file download (ZEFB3 or ZEFR3 binary format)

  No server involved

For detailed data flow diagrams, component tree, and theming system, see docs/ARCHITECTURE.md.

Binary File Format

ZEFB3 — Single key (primary format)

ZEFB3 (5 bytes magic)
header_length (4 bytes, big-endian)
header_json                         ← public header (minimal)
salt (32 bytes) + iv (12 bytes)
encrypted_chunks                    ← 16MB per chunk, unique IV per chunk

ZEFR3 — With reveal key

ZEFR3 (5 bytes magic)
header_length (4 bytes, big-endian)
header_json                         ← public header (minimal)
main_block_size (4 bytes)
main_salt + main_iv + main_chunks   ← encrypted with main passphrase
reveal_salt + reveal_iv + reveal_chunks ← encrypted with reveal key

Public header (visible without decryption): iterations, compression, hint, note, mode

Encrypted payload (invisible without the key): content, file metadata, expiration, secret question, IP list, max attempts

Legacy text formats (ZEFER3, ZEFER2) are supported for backward-compatible decryption only.

Quick Start

Prerequisites

• Node.js 20+
• npm 10+

Installation

git clone https://github.com/carrilloapps/zefer.git
cd zefer
npm install
npm run dev

Open http://localhost:3000.

Verify

npm run lint           # ESLint
npm run typecheck      # tsc --noEmit
npm run test:coverage  # 969 tests behind the 100% coverage gate
npm run build          # Production build
npm run validate       # all of the above

Tech Stack

Layer	Technology
Framework	Next.js 16.3.5 (React 19)
Language	TypeScript 6
Styling	Tailwind CSS v4
Encryption	Web Crypto API (AES-256-GCM)
Key Derivation	PBKDF2-SHA256 (300k-1M iterations)
Compression	CompressionStream API (Gzip/Deflate)
UI primitives	Radix UI (Dialog, DropdownMenu, Popover, Select, Tooltip, Tabs, Switch)
Icons	Lucide React
Notifications	Sonner
Testing	Vitest + @vitest/coverage-v8 + @testing-library/react (jsdom)
CI	GitHub Actions — ci.yml (lint, typecheck, coverage, build) and security.yml (Semgrep, Trivy, Gitleaks, SonarQube)
Hosting	Vercel / Any static host

Project Structure

app/
  api/
    author/route.ts       # GitHub profile API (cached 1h)
  components/             # 34 client components
    EncryptForm.tsx        # Encrypt text/files
    DecryptForm.tsx        # Decrypt .zefer files
    HomeContent.tsx        # Home page with tabs
    KeyGenerator.tsx       # Secure key generator popover
    CryptoProgress.tsx     # Encryption/decryption progress bar
    ...                    # 29 more components
  lib/
    crypto.ts             # AES-256-GCM + PBKDF2 + benchmarking
    zefer.ts              # .zefer format encode/decode (ZEFB3/ZEFR3)
    chunked-crypto.ts     # Chunked encryption (16MB per chunk)
    compression.ts        # Gzip/Deflate via CompressionStream
    device.ts             # RAM/CPU/GPU detection + file limits
    i18n.ts               # Translations (es/en/pt, ~1,045 keys)
    ip.ts                 # IP detection and restriction
    notify.ts             # Toast notification helpers
    preferences.ts        # Persisted user preferences
    progress.ts           # Encryption progress tracking
    seo.ts                # Centralized page metadata
    useUrlParams.ts       # URL parameter parsing (long + short aliases)
    file-handoff.ts       # File transfer between forms
    __tests__/            # Vitest unit suites
  globals.css             # Design system (liquid glass, theming)
  layout.tsx              # Root layout + providers
  page.tsx                # Home page
  **/__tests__/           # 969 Vitest tests across 60 files
docs/                     # Architecture, Security, Deployment, Contributing, Releasing
public/
  llms.txt                # LLM context file (llmstxt.org standard)

Routes

Route	Type	Indexed	Description
/	Static	Yes	Home — encrypt/decrypt forms
/how	Static	Yes	How it works — 7 steps + features + specs
/generator	Static	Yes	Advanced password generator + analyzer — entropy, attack scenarios, security framework, copy/download
/analyzer	Static	Yes	.zefer file inspector — public header without the passphrase
/mcp	Static	Yes	zefer-cli as MCP server — setup, per-tool accordions, 5 tools, example call
/library	Static	Yes	zefer-cli as a Node.js library (v1.3.0+) — install, ESM/CJS import, API, examples
/project	Static	Yes	Project info, tech stack, creator, donate
/device	Static	Yes	Device detection details + optimization guide
/install	Static	Yes	Usage guide, self-hosting, PWA, native apps
/install/guide	Static	Yes	Step-by-step usage guide for AI assistants
/vs/*	Static	Yes	Comparisons: Hat.sh, Picocrypt, Bitwarden Send, Cryptomator, VeraCrypt
/privacy	Static	No	Privacy policy + GDPR/CCPA/LGPD compliance
/terms	Static	No	Terms, conditions, MIT license, legal compliance
/security	Static	No	Security policy — vulnerability reporting
/conduct	Static	No	Code of Conduct — Contributor Covenant 2.1
/api/author	Dynamic	—	GitHub profile data (cached 1h)
/llms.txt	Static	Yes	LLM context file

URL Parameters

Pre-configure forms via URL for workflow automation. Every parameter has a long name and short alias. Sensitive params are auto-cleared from the URL after reading.

Tab: tab / t — encrypt or decrypt

Encrypt (/?tab=encrypt&...)

Long	Short	Type	Values
passphrase	p	string	min 6 chars
passphrase2	p2	string	min 6 chars (enables dual key)
dual	d	flag	1 / true
reveal	r	string	min 6 chars
mode	m	enum	text / file
ttl	—	number	0=never, 30, 60, 1440, 10080, 20160 (minutes)
security	s	enum	standard / high / maximum
iterations	i	number	300000-1000000
compression	c	enum	none / gzip / deflate
hint	h	string	any
note	n	string	any
question	q	string	any
answer	a	string	any
attempts	att	number	0, 3, 5, 10
ips	—	string	comma-separated IPv4/IPv6

Decrypt (/?tab=decrypt&...)

Long	Short	Type
passphrase	p	string
passphrase2	p2	string (enables dual key)
dual	d	flag
answer	a	string

Examples

/?t=decrypt&p=mySecret123
/?t=encrypt&m=file&ttl=30&c=gzip&s=high
/?t=encrypt&p=key1&p2=key2&q=Color%3F&a=blue&ips=10.0.0.1,192.168.1.5&s=maximum

Testing

npm test               # Run the full suite
npm run test:watch     # Watch mode
npm run test:coverage  # Single run behind the 100% coverage gate

Metric	Value
Test files	60
Total tests	969
Statements	100%
Branches	100%
Functions	100%
Lines	100%

Thresholds are enforced in vitest.config.mts; .github/workflows/ci.yml re-runs lint, typecheck, the coverage gate and the production build on Node.js 20 and 22 for every push and pull request.

Security Model

1. All encryption/decryption happens in the browser via Web Crypto API
2. The server never sees plaintext, passphrases, or encryption keys
3. The .zefer file header contains only minimal technical data
4. All security metadata (expiration, IPs, question) is inside the encrypted payload
5. An attacker with the file cannot determine what security features are enabled
6. Each file has unique encryption (random salt + IV per block)
7. Reveal key is independently encrypted with its own salt, IV, and derived key

Primitive	Algorithm	Parameters
Symmetric encryption	AES-256-GCM	256-bit key, 96-bit IV, 128-bit auth tag
Key derivation	PBKDF2-SHA256	300k/600k/1M iterations, 256-bit salt
Answer hashing	PBKDF2-SHA256	100,000 iterations
Random generation	crypto.getRandomValues	OS-level CSPRNG

For the full threat model, known limitations, and security guarantees, see docs/SECURITY.md.

Legal Compliance

Regulation	Status
GDPR (EU)	Compliant — no personal data collected
CCPA (California)	Compliant — no personal information sold or shared
LGPD (Brazil)	Compliant — Art. 5, 18
Law 1581 (Colombia)	Compliant — Art. 4, 9
ePrivacy Directive	Compliant — no cookies, trackers, or analytics

Deployment

Method	Command	Notes
Vercel	Push to GitHub + Import in Vercel	Recommended, zero-config
Docker	docker build -t zefer . && docker run -p 3000:3000 zefer	Production-ready Dockerfile in docs/DEPLOYMENT.md
Static export	npm run build with output: "export"	Disables /api/author route
Self-hosted	npm run build && npm start	Requires Node.js 20+, HTTPS

HTTPS is required — Web Crypto API is only available in secure contexts. See the full Deployment Guide.

AI Integration

MCP server — zefer-cli doubles as a Model Context Protocol server: { "mcpServers": { "zefer": { "command": "zefer", "args": ["mcp"] } } } gives any agent (Claude Code/Desktop, Cursor, Windsurf, VS Code, Zed…) five local tools: zefer_encrypt, zefer_decrypt, zefer_keygen, zefer_analyze_password, zefer_inspect. Per-tool setup guides: zefer.carrillo.app/mcp.

Zefer also publishes /llms.txt following the llmstxt.org standard. Any AI tool can use it as context:

Tool	Usage
Claude Code	Reads CLAUDE.md and AGENTS.md automatically when cloned
GitHub Copilot	@workspace /explain #file:llms.txt
Cursor / Windsurf / Augment	Add llms.txt as context file
Any LLM	Pass https://zefer.carrillo.app/llms.txt as context URL

Contributing

Contributions are welcome! Please read the Contributing Guide and Code of Conduct before submitting a pull request.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Run npm run validate — typecheck, lint, tests and build must all pass
4. Submit a pull request

Documentation

Document	Description
Wiki	In-depth guides with diagrams and a glossary — algorithm, security model, .zefer format, channels (CLI/MCP/library), tools, comparisons
Architecture	Data flow, binary format, component tree, theming
Security	Threat model, cryptographic primitives, guarantees, limitations
Deployment	Vercel, Docker, static export, self-hosting
Contributing	Setup, quality gates, CI, conventions, PR workflow
Releasing	Version checklist, gates, tag/release/deploy steps
Security Policy	Vulnerability reporting, response timeline, scope
Code of Conduct	Contributor Covenant community standards
Changelog	Version history and release notes

Author

Jose Carrillo — Senior Fullstack Developer & Tech Lead

10+ years building scalable, efficient, and secure software. Based in Colombia.

Support

If you find Zefer useful, consider supporting the project:

License

MIT © 2026 Jose Carrillo

---