WI Arch fork. This repository is WI Arch's fork of carrilloapps/zefer (MIT license). Badges, live site and wiki links below refer to the upstream project, not to this fork.
Share secrets, not risks.
Client-side encryption tool that converts text and files into password-protected .zefer files using AES-256-GCM. Encryption and decryption run in the browser. The optional IP-restriction feature contacts external IP lookup providers; see the security notes below.
Live Demo · CLI (zefer-cli) · WI Arch security baseline · Report Bug · Request Feature · Security Report · Documentation
This repository is a fork of carrilloapps/zefer, which remains the upstream project and original source of the application.
WI Arch maintains this fork as its central reference for security engineering practices and client-side encrypted-file tooling. The shared rules are documented in the WI Arch Security Baseline, with a per-repository adoption checklist and source review.
Important: Zefer does not automatically secure other WI Arch applications. It is not an identity provider, authorization framework, KMS or server-side secrets manager. Every product must implement and test its own authentication, authorization, tenant isolation, secure storage, API protections, deployment controls and backups.
The WI Arch review also identifies hardening work still required in this fork. Do not interpret the upstream test coverage or security scanners as an independent audit or certification.
Encryption and decryption are performed locally by the browser. If the user enables IP restrictions, the application queries external IP lookup providers to determine the public IP. The user's IP is therefore disclosed to those providers for that feature. IP restrictions, expiration and attempt limits are client-side convenience controls, not substitutes for server-side authorization.
- 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
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
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.zeferStandalone 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.
|
Encryption
|
Security Layers
|
|
Developer Experience
|
Accessibility & i18n
|
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.
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 (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.
- Node.js 20+
- npm 10+
git clone https://github.com/carrilloapps/zefer.git
cd zefer
npm install
npm run devOpen http://localhost:3000.
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| 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 |
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)
| 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 |
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.
| 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 |
| Long | Short | Type |
|---|---|---|
passphrase |
p |
string |
passphrase2 |
p2 |
string (enables dual key) |
dual |
d |
flag |
answer |
a |
string |
/?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=maximumnpm 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.
- All encryption/decryption happens in the browser via Web Crypto API
- The server never sees plaintext, passphrases, or encryption keys
- The
.zeferfile header contains only minimal technical data - All security metadata (expiration, IPs, question) is inside the encrypted payload
- An attacker with the file cannot determine what security features are enabled
- Each file has unique encryption (random salt + IV per block)
- 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.
| 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 |
| 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.
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 |
Contributions are welcome! Please read the Contributing Guide and Code of Conduct before submitting a pull request.
- Fork the repository
- Create a feature branch (
git checkout -b feature/your-feature) - Run
npm run validate— typecheck, lint, tests and build must all pass - Submit a pull request
| 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 |
Jose Carrillo — Senior Fullstack Developer & Tech Lead
10+ years building scalable, efficient, and secure software. Based in Colombia.
If you find Zefer useful, consider supporting the project:
MIT © 2026 Jose Carrillo