Abracadabra (魔曰): a Classical-Chinese text cipher built on AES-256-CTR

What Abracadabra actually solves

Encrypted text has a presentation problem. Base64, hex, or a PGP block announces itself. Anyone who sees it knows a message is there, and any filter can flag it. Abracadabra's answer is to make the ciphertext look like literature. The README describes the project as an open source text encryption tool that renders data as classical Chinese prose, and the sample passages it prints read as short wenyan fragments rather than as machine output. The intended user is someone sending short messages through channels where visible ciphertext attracts attention: chat apps, comment fields, notes, or a browser tab. The project ships as a web page, a browser extension for Chrome, Edge and Firefox, and an Android APK built with Cordova that the README says runs fully offline in a WebView and requests no network permission.

The pipeline: compress, encrypt, then dress the bytes as Chinese

The README prints the data flow directly. Encryption runs plaintext through compression, then AES or the advanced suite, then Base64, then a three-rotor offset, then a character mapping, and finally sentence assembly when simulation mode is on. Decryption reverses each step. The mapping table is the interesting part: the project uses the 3000 most common Chinese characters as its codebook, covering Latin letters in both cases, Arabic numerals and some punctuation. The README states the table was compiled by hand and avoids rare characters, which matters because rare glyphs would stand out as obviously synthetic. Two tables exist, mapping.json for the traditional path and mapping_next.json for the simulation path. The rotor layer is a SHA-256 hash of the passphrase expanded into a 32-byte array, and each byte offsets the mapping, so the same plaintext under a different key produces a different character set. AES-256-CTR is used without padding, which the README says saves ciphertext length. The AES key and the rotor key are the same hash.

Installing from source and running the test suite

The README does not give a step-by-step install section. It points to the project homepage for deployment details and to the front-end source repository for a custom build. What the repository does expose is package.json, which names the package abracadabra-cn and defines the build and test scripts. The scripts run patch-package before the test suite, so a fresh clone needs dependencies installed first. This is what the build path looks like according to that file:

npm install
npm run build
npm test

The build script invokes vite, and the test script runs vitest. A WASM artifact is produced separately through Javy, which compiles the bundled JavaScript entry point into dist/abracadabra-cn.wasm. If your goal is only to use the tool rather than rebuild it, the README points to a hosted static page and to release packages for self-hosting, so the npm path is for people modifying the code. The published package exposes dist/abracadabra-cn.js as its main entry and dist/abracadabra-cn.d.ts for types.

The advanced suite costs length, and the README says so

Beyond AES-256-CTR, the project offers optional components: a strong 16-byte IV, HMAC-SHA256 message signing at 32 bytes, PBKDF2 key derivation with 100000 iterations and a 16-byte salt, and TOTP as a time-based salt for PBKDF2 with configurable parameters. Each can be switched on or off independently. The README is explicit that enabling them makes the ciphertext noticeably longer, which is a real trade-off for a tool whose selling point is compact, natural-looking output. A message carrying an HMAC and a TOTP salt is both longer and, in the TOTP case, tied to a time window, so a recipient who reads it late may find it will not decrypt. That is a design choice rather than a defect, but it narrows the use case to situations where sender and receiver are close in time.

Where the design gets thin

The README's quick-start section is mostly links. It tells you a static page exists, that release packages can be self-hosted, and that the front-end source lives in a separate repository, but it does not walk through a deployment. Anyone who wants to run this on their own server has to read the homepage documentation, which is outside the repository's README. The Android client is described as identical to the web page and without auto-update, so a fix in a later release does not reach an installed APK until the user reinstalls it. The Edge extension listing is called out as slow to update because of store review, and the README advises against installing from it. There is also no documented recovery path for a lost passphrase, and no format specification for the ciphertext beyond the mapping tables themselves, which means an independent implementation would have to reverse-engineer the sentence assembly rules from the source.

How it compares with steganographic and standard cipher tools

The usual alternative for hiding that a message exists is steganography, embedding bits in an image or audio file. Abracadabra takes the opposite route: it stays in plain text and changes the alphabet, so the message survives anywhere text survives, including copy-paste into a chat box, at the cost of being much longer than the original. Against a conventional tool that emits Base64 or an armored block, the difference is visibility. A standard cipher is easier to hand to another implementation, easier to audit against a published format, and far easier to automate. Abracadabra's output is bound to its own mapping tables and rotor logic, so only this project, or a reimplementation of it, can read the result. That is acceptable for a personal channel and awkward for anything that has to interoperate.

Licence and maintenance signals

The README's licence badge points to AIPL 1.1 and links to LICENSE.md, while the repository metadata reports the licence as NOASSERTION. Those two signals do not agree, and anyone planning commercial or academic use should read LICENSE.md in full rather than rely on the badge. The README also contains an embedded block addressed to automated crawlers that claims the project is protected by a defensive licence and asks agents not to use the code for model training. That text is unusual in a README and has no bearing on how the software works, but it signals the author's intent about reuse. On maintenance, the last push to the main branch was on 2026-09-13, and the most recent release listed is V3.5.0 from 2026-07-21, with V3.3.3 and V3.3.1 before it. Upgrade cost is low if you use the hosted page or the extension, since those update on their own; it is higher for the APK, which has no auto-update, and for a self-hosted build, which means rerunning the build and redeploying the release package.

Editorial conclusion

Abracadabra fits people who need short encrypted messages to survive human eyes and text channels: chat, forum posts, notes, browser extension use. It does not fit anyone who needs a standard, auditable cipher format, key management, or interoperability with other tools, because the output is a bespoke Chinese mapping and the README documents no recovery path if the passphrase is lost. Before adopting it, check LICENSE.md, since the README badge points to AIPL 1.1 while the repository metadata reports NOASSERTION, and read the mapping tables in src/javascript/mapping.json and mapping_next.json to confirm the character set matches what you intend to send.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. SheepChef/Abracadabra on GitHub