This document introduces the Abracadabra (魔曰) system, a text encryption tool that transforms plaintext data into classical Chinese ciphertext resembling authentic 文言文 (Classical Chinese) prose. This overview covers the system's purpose, core capabilities, and architectural organization.
For detailed feature descriptions and security characteristics, see Purpose and Features. For in-depth architectural documentation including module dependencies and pipeline design, see System Architecture.
Abracadabra is a JavaScript-based encryption library that implements a multi-layered encryption pipeline combining cryptographic security with linguistic steganography. The system encrypts arbitrary data (text or binary) and outputs Chinese characters arranged in grammatically correct classical Chinese sentences that reference ancient texts such as 古文观止 (Guwen Guanzhi), 经史百家杂钞, and 古文辞类纂.
The core implementation resides in src/javascript/main.js which exposes the Abracadabra class as the primary API interface. The system is distributed as an NPM package (abracadabra-cn version 3.3.3), static web application, browser extensions (Chrome/Edge/Firefox), Android APK, and WebAssembly binary.
Sources: README.md38-39 README.md72-73 docs/index.md72-73
| Capability | Description | Code Reference |
|---|---|---|
| Wenyan Simulation Encryption | Modern encryption mode generating classical Chinese ciphertext with configurable grammar styles | WenyanInput() method docs/document/js-deploy.md47-49 |
| Traditional Encryption | Legacy mode using direct character mapping (deprecated) | OldInput() method docs/document/js-deploy.md201-212 |
| BearDecode Function | Decrypts external 熊曰 (Xiongyue) ciphertexts via reverse-engineered algorithm | BearDecode() method docs/document/js-deploy.md248-273 |
| AES-256-CTR Encryption | Core cryptographic security with optional advanced suite (HMAC, PBKDF2, TOTP) | README.md144-161 |
| Intelligent Compression | Dual compression using Unishox2 for short texts and GZIP for data >1KB | README.md175-182 |
| Cross-Platform Distribution | Runs on browsers, Node.js, Android WebView, and WASI runtimes | README.md83-118 |
| Offline Operation | All encryption/decryption executes locally without network dependencies | README.md114 |
Sources: README.md48-62 docs/index.md75-89
The following diagram maps the major code entities and their relationships in the Abracadabra system:
Sources: docs/document/js-deploy.md18-43 src/javascript/main.js (referenced), src/javascript/CoreHandler.js (referenced)
The system processes data through a sequential pipeline with distinct stages. Each stage is implemented by specialized helper classes:
Key Processing Stages:
| Stage | Implementation | Output Format |
|---|---|---|
| Compression | CompressionHelper.js using Unishox2 or pako | Compressed bytes |
| Encryption | EncryptHelper.js with crypto-js | AES-encrypted bytes (+optional HMAC) |
| Encoding | js-base64 library | Base64 string |
| Obfuscation | RoundObfusHelper.js using 6 rotors | Obfuscated Base64 |
| Mapping | WenyanSimulator.mapCharactersToWenyan() | Chinese characters |
| Construction | WenyanSimulator.constructSentences() | Grammatical 文言文 |
Sources: README.md126-132 README.md164-173 README.md175-182
Abracadabra supports multiple deployment configurations, each targeting different runtime environments:
Platform-Specific Details:
crx branch containing extension-specific code README.md89-106JavyInputAppendix.js for WASI stdin/stdout interface (referenced in system diagrams)Sources: README.md79-118 docs/document/js-deploy.md1-16 docs/document/js-deploy.md291-312
The Abracadabra class supports two I/O type modes configured at instantiation:
Mode Configuration:
Abracadabra.TEXT (default): Accepts String input, returns String outputAbracadabra.UINT8: Accepts Uint8Array input, returns Uint8Array outputThis dual-mode design enables both text encryption and arbitrary binary file encryption, though binary encryption is not recommended due to ciphertext expansion docs/document/js-deploy.md22-45
Sources: docs/document/js-deploy.md18-45
The system provides three distinct encryption/decryption modes exposed as methods on the Abracadabra class:
| Method | Purpose | Status | Configuration Objects |
|---|---|---|---|
WenyanInput() | Modern classical Chinese simulation | Active development | WenyanConfig, AdvancedEncConfig |
OldInput() | Legacy direct character mapping | Deprecated, maintained for compatibility | None (simple mode flag) |
BearDecode() | External ciphertext decryption | Read-only, reverse-engineered | None (decryption only) |
Mode Selection Logic:
Sources: README.md58-62 docs/document/js-deploy.md47-273
The WenyanInput() method accepts two configuration objects defined in TypeScript interfaces:
WenyanConfig Interface:
PunctuationMark?: boolean - Add punctuation to ciphertext (default: true)RandomIndex?: number - Randomness level 0-100 (default: 50)PianwenMode?: boolean - Use parallel prose style 骈文 (default: false)LogicMode?: boolean - Use logical argumentation style (default: false)Traditional?: boolean - Output Traditional Chinese (default: false)AdvancedEncConfig Interface:
Enable?: boolean - Enable advanced encryption suite (default: false)UseStrongIV?: boolean - Use 16-byte IV (default: true)UseHMAC?: boolean - Add HMAC-SHA256 signature (default: false)UsePBKDF2?: boolean - Apply key derivation with 100k iterations (default: false)UseTOTP?: boolean - Use time-based salt (default: false)TOTPTimeStep?: number - Time window 0-15 (default: 4)TOTPEpoch?: number - Unix timestamp in milliseconds (default: system time)TOTPBaseKey?: string - Pre-shared TOTP key (default: encryption key)Sources: docs/document/js-deploy.md84-165
The system relies on seven open-source dependencies, all with permissive licenses compatible with the project's AIPL 1.1 license:
| Dependency | Purpose | License |
|---|---|---|
crypto-js | AES encryption, SHA256 hashing | MIT |
pako | GZIP compression/decompression | MIT |
js-base64 | Base64 encoding/decoding | BSD-3-Clause |
Unishox2 | Short string compression | Apache-2.0 |
mersenne-twister | Pseudorandom number generation | BSD-3-Clause |
opencc-js | Simplified/Traditional Chinese conversion | MIT |
otplib | TOTP time-based authentication | MIT |
The complete dependency tree and licensing information is documented in README.md219-236
Sources: README.md219-236 docs/index.md104-121
For detailed information on specific aspects of the Abracadabra system, see: