Library

Library (programmatic API)

Since v1.3.0, zefer-cli also ships a zero-side-effect programmatic library: the same engine the web app and CLI use, importable from your own Node.js code (services, AWS Lambda, build scripts). It is published as both ESM and CommonJS, and the package "." export resolves to the library (not the CLI bundle). Web guide: https://zefer.carrillo.app/library

Install

npm install zefer-cli

Requires Node.js 20+. TypeScript types are included.

Import

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

// CommonJS
const { encodeZefer, decodeZefer } = require("zefer-cli");

Exposed API

encodeZefer(options) → Promise<Buffer>

Encrypts content into the ZEFB3/ZEFR3 binary format; returns the raw encrypted bytes.

Option	Type	Notes
content	string	text mode
fileData	Buffer	file mode
fileName	string | null
fileType	string	MIME type (file mode)
passphrase	string
expiresAt	number	Unix ms; 0 = never
compression	"none" | "gzip" | "deflate" | "deflate-raw"
iterations	number	explicit PBKDF2 iterations — never auto-benchmarks

decodeZefer(input, passphrase, options) → Promise<{ ok, payload? }>

Decrypts a .zefer file. payload may contain { content?, fileData?, fileName? }.

Parameter	Type	Notes
input	string	base64 or UTF-8 encoded
passphrase	string
options.rawBytes	Buffer	for ZEFB3/ZEFR3 binary input

generateWithOptions(mode, length, options) → string

Generates a scored key. mode: unicode \| secure \| alpha \| hex \| base58 \| pin \| uuid. length: 1–2048. options: { groupSize?, excludeAmbiguous?, ... }. (generateValue(mode, length) returns a raw key without scoring.)

analyzePassword(password) → report

Returns score (0–4), entropy, keyspace, post-quantum entropy, attack-scenario crack times, and NIST / OWASP / AES-128 / post-quantum compliance checks.

Usage examples

import { encodeZefer, decodeZefer, generateWithOptions, analyzePassword } from "zefer-cli";
import { writeFile, readFile } from "node:fs/promises";

// Encrypt text
const buf = await encodeZefer({
  content: "api_key=abc123",
  passphrase: "a-strong-passphrase",
  fileName: null,
  expiresAt: 0,
  compression: "gzip",
  iterations: 600_000,
});
await writeFile("secret.zefer", buf);

// Encrypt a file
const data = await readFile("photo.jpg");
const fileBuf = await encodeZefer({
  fileData: data, fileName: "photo.jpg", fileType: "image/jpeg",
  passphrase: "a-strong-passphrase", expiresAt: 0, iterations: 600_000,
});

// Decrypt
const bytes = await readFile("secret.zefer");
const res = await decodeZefer(bytes.toString("utf-8"), "a-strong-passphrase", { rawBytes: bytes });
if (res.ok) console.log(res.payload.content);

// Generate & analyze
const key = generateWithOptions("base58", 24, { groupSize: 6 });
const report = analyzePassword(key);
console.log(key, report.score, report.entropy);

Important notes

• No auto-benchmarking — always pass an explicit iterations value (e.g., 600000).
• In-memory operation — needs RAM roughly equal to input + output size. For Lambda/microservices, allocate ≥512 MB for ~100 MB payloads.
• Cross-compatibility — files produced by the library open in the web app and the CLI, and vice versa.
• Full API reference: docs/LIBRARY.md in the zefer-cli repository.

---

📖 Glossary — terms on this page: ZEFB3 / ZEFR3 · PBKDF2 · compression · entropy · post-quantum. Full list in the Glossary.