Getting Started

Why this exists

A puzzle says "the key is LEMON" and I want the plaintext, not a lecture. An agent gets a ROT-47 string in a challenge and needs to flip it without leaving the process. Each cipher is small, but every one of them has conventions that decide whether your answer matches the author's: does Playfair fold J into I, does Bacon use 24 or 26 letters, which rotors is "Enigma" even. Every online tool picks something different and rarely says what.

So @agntn/ciphers picks once, writes it down, and gives every cipher the same two methods. No HTTP, no keys, no telemetry. It runs in your process and that's it.

Install

pnpm add @agntn/ciphers

First call

import { create } from "@agntn/ciphers";

const vigenere = create("vigenere");

const encoded = vigenere.encode("ATTACK AT DAWN", { key: "LEMON" });
console.log(encoded.text); // LXFOPV EF RNHR

const decoded = vigenere.decode(encoded.text, { key: "LEMON" });
console.log(decoded.text); // ATTACK AT DAWN

The package ships seventy-two ciphers from one list. create(name) gives you one cached instance and wants the exact registry name. resolveCipher("Rail Fence") lowercases, turns spaces into hyphens, and then also wants an exact match. No prefixes, no fuzzy matching, a typo is an UnknownCipherError. Guessing which cipher you meant is how you get the wrong plaintext with a straight face.

The shape

Every encode and decode returns this:

interface CipherResult {
  text: string; // the output
  cipher: string; // "vigenere"
  operation: "encode" | "decode";
  options: Record<string, unknown>; // what was actually applied, defaults included
  normalizedInput?: string; // optional, for a cipher that reshapes its input; the built-ins leave it out
}

Every classical cipher understands two options. preserveCase (default true) keeps lowercase letters lowercase. stripNonAlpha (default false) drops everything that isn't a letter before the cipher runs. The rest is per cipher: shift, key, secondKey, transposition, square, rotation, omit, orientation, indicator, indicatorUnder, blanks, separator, zero, book, address, pick, start, rails, width, corner, path, a, b, period, letters, positions, rings, plugboard, iv, segment, blockSize, nonce, aad, counter, tagLength, tweak, endian, bytes, digest, algorithm, count, keyLength, iterations, salt. Each cipher's page lists its own, and so does create(name).info().

What ships

Errors

import { CipherError, InvalidOptionError, MissingOptionError, UnknownCipherError } from "@agntn/ciphers";

try {
  create("caesar").encode("HELLO", { shift: 26 });
} catch (error) {
  if (error instanceof InvalidOptionError) {
    error.option; // "shift"
    error.reason; // why 26 is not a shift
  }
}

No key where a key is required, MissingOptionError. A name nobody registered, UnknownCipherError, and its message lists the names that are, so rot-13 comes back with rot13 in the same line. A value out of range, InvalidOptionError with the option, the value and the reason. Anything else a cipher throws gets wrapped by normalizeError into a CipherError that names the cipher. The CLI prints the message and exits 1. No stack trace. You did nothing wrong, the input did.

Next

• Encode and decode: options, case, what happens to punctuation, the round trip.
• Analysis: brute force a Caesar, read a histogram.
• CLI: the ciphers command.
• Agents: the tools over MCP, Pi and OMP.
• Custom ciphers: extend Cipher, register it.
• Playground: every cipher, in the page.