# Architecture Internal design of the ChaosCrypt package: how the modules fit together, what each one is responsible for, and how data flows through the algorithm. --- ## Module map ``` chaoscrypt/ ├── __init__.py Public API, the ChaosCrypt facade, module-level helpers ├── _core.py The algorithm (ChaosCryptCore) ├── errors.py The unified error hierarchy ├── cli.py Argument-driven command line interface ├── tui.py Interactive bilingual interface ├── i18n.py UI strings for the TUI ├── py.typed PEP 561 marker ├── tests/ Test suite ├── examples/ Runnable examples └── legacy/ The original single-file implementation ``` ### Dependency graph ``` __init__.py / \ errors.py _core.py \ / \ / \ / cli.py tui.py \ | \ | i18n.py ``` Arrows point from user to dependency. Two properties follow from this shape: - **`errors.py` and `_core.py` are leaves.** They import nothing from the rest of the package, so they can be tested standalone. - **`tui.py` and `i18n.py` are optional.** A library user importing `chaoscrypt` never loads them, so the TUI costs nothing when unused. --- ## Module responsibilities ### `errors.py` Defines `ChaosCryptError` and its sixteen subclasses. Each subclass carries a class-level `CODE` and `DETAIL`, and instances render as `ChaosCrypt_ERR__`. The hierarchy exists so that callers can catch a single type and still branch on a stable code, rather than matching on message text. ### `_core.py` The algorithm. `ChaosCryptCore` owns: - random key material generation; - key file serialisation and parsing; - the encryption and decryption pipelines. It performs **no file I/O beyond reading and writing the key file it is given**, and no user interaction at all. Every failure raises a `ChaosCryptError` subclass. This module is a behaviour-preserving port of the original implementation. The compatibility contract it upholds is described under [Compatibility](#compatibility-invariants) below. ### `__init__.py` Two jobs: 1. **Public API surface.** Re-exports the classes, errors and constants that make up the supported interface, together with `__version__` and `__license__`. 2. **The `ChaosCrypt` facade.** Wraps `ChaosCryptCore` with key file management, binary helpers and file-level convenience methods. The split lets callers choose their level of control: `ChaosCrypt` for everyday work, `ChaosCryptCore` when key material is managed elsewhere. ### `cli.py` Argument parsing and command dispatch. Contains no cryptographic logic — it resolves passwords, reads input, calls the facade, and formats output. The invocation contract lives in `main()`: ```python def main(argv=None) -> int: raw = sys.argv[1:] if argv is None else argv if not raw: # no arguments -> interactive return run_tui() ... # arguments -> scriptable ``` Dispatch is a plain `if` chain rather than a dynamic registry, so the control flow is readable at a glance. ### `tui.py` The interactive interface. Menu-driven, dependency-free, and bilingual. Input is read through three helpers with defined fallback behaviour: | Helper | Behaviour | |---|---| | `_ask()` | Prompt with optional default; raises `_Abort` on EOF or Ctrl-C | | `_ask_secret()` | `getpass` on a TTY, plain `input` when piped | | `_ask_yes_no()` | Confirmation prompt | The `_Abort` exception is the mechanism by which Ctrl-C or EOF at any prompt returns control to the main menu instead of tearing down the process. ### `i18n.py` A flat dictionary of UI strings keyed by name and language code, plus a lookup function `t(key, lang)`. Every string is present in both English and Chinese; a test enforces this. English is the default. The TUI can switch language at runtime without restarting. --- ## Data flow: encryption Each stage is a bijection on its input domain, which is what makes the composition invertible. ``` plaintext (str) │ │ utf-8 encode arbitrary bytes ▼ bytes │ │ Base64 (RFC 4648) printable ASCII, A-Z a-z 0-9 + / = ▼ Base64 string │ │ character remap '+'→'.', '/'→"'", '=' records count ▼ remapped string │ │ substitution (encrypt_map) two independent 26! bijections ▼ substituted string │ │ conditional case flip (flip_pattern) 10-bit pattern, non-linear ▼ flipped string │ │ reverse destroys locality ▼ reversed string ── append "|" + encoded padding count ──► │ │ XOR with K_long (hex output) 4096-nibble keystream ▼ intermediate hex ── append "|" + encoded length ──► │ │ XOR with DeriveKey(password, K_short, n) password-derived keystream ▼ ciphertext (hexadecimal string) ``` The two `|` separators carry metadata between stages. They never appear in the final output, because the XOR stages fold them into the keystream. ## Data flow: decryption The exact inverse, applied in reverse order: ``` ciphertext │ XOR with derived keystream ▼ length marker recovered ──► inner hex │ XOR with K_long ▼ padding marker recovered ──► reversed string │ reverse ▼ │ conditional case flip (same pattern) ▼ │ inverse substitution (decrypt_map) ▼ │ undo character remap ▼ │ Base64 decode ▼ │ utf-8 decode ▼ plaintext ``` --- ## Key derivation `DeriveKey(K_user, K_short, n)` produces a keystream of exactly `n` printable characters: ``` K_user ──┐ ├──► interleave ──► bit ops ──► group permute ──► reverse ──► expand ──► keystream K_short ─┘ ``` The pipeline is deterministic and length-extensible. Two consequences matter: 1. **Message length is a derivation parameter.** Two messages of different lengths produce unrelated keystreams, so recovering one does not help with another. 2. **The transformation is not invertible.** Recovering a keystream does not reveal `K_user` or `K_short`. Together these mean a known-plaintext attack yields nothing reusable, which is analysed in [SECURITY.md §6.2](../SECURITY.md). --- ## Key file format A key file is a single line of hexadecimal text. ``` key file (hex text) │ │ XOR with repeated key file password ▼ obfuscated payload │ │ Base64 decode → reverse → shift by -1 → Base64 decode ▼ JSON ``` The JSON contains: ```json { "upper_mapping": "26 characters", "lower_mapping": "26 characters", "digit_mapping": {"0": "X", "...": "..."}, "equal_mapping": {"0": "X", "1": "Y", "2": "Z", "3": "W"}, "flip_pattern": [1, 0, 1, 0, 0, 1, 0, 0, 1, 0], "long_key": "4096 hex nibbles", "short_key": "512 hex nibbles", "generated_at": "ISO 8601 timestamp" } ``` Confidentiality comes from the password-derived XOR, not from the Base64 layers, which are a transport encoding. ### Failure classification Because a wrong password and a damaged file both produce unparseable output, the loader distinguishes them explicitly: | Condition | Result | |---|---| | Not valid hexadecimal | `E002` corrupted file | | Empty contents | `E002` corrupted file | | Parses, but structure is invalid | `E003` wrong password | | Decodes, but required fields missing | `E002` corrupted file | The structural validation step is what separates "you typed the wrong password" from "this file is damaged", which is the difference between a useful error message and a confusing one. --- ## Error design Every error class follows the same shape: ```python class ChaosCryptError(Exception): CODE = "E000" DETAIL = "UnknownError" def __init__(self, detail=None, code=None): self.detail = detail or self.DETAIL self.code = code or self.CODE self.message = f"ChaosCrypt_ERR_{self.detail}_{self.code}" super().__init__(self.message) ``` Three attributes serve three audiences: | Attribute | Audience | Stability | |---|---|---| | `code` | Programs | Stable across releases | | `detail` | Logs and diagnostics | Stable in meaning | | `message` | Humans | Wording may change | `code` is the contract. Branch on it; do not parse `message`. --- ## Compatibility invariants The following are guaranteed within a major version, and are enforced by the test suite rather than merely documented: 1. **Algorithm equivalence.** The encryption pipeline matches the original implementation bit for bit. A reference-vector test pins the output for fixed key material, so any accidental change is caught immediately. 2. **Key file format.** The on-disk format is unchanged, and the default file name remains `encryption.key`. 3. **Bidirectional interoperability.** Ciphertext and key files move freely between this library and the original script, in both directions. Dedicated tests load `legacy/chaoscrypt_legacy.py` and exercise the real code path. 4. **Error codes.** Codes are never renumbered. The `legacy/` directory exists to make invariant 3 testable against the actual original implementation rather than a reimplementation of it. --- ## Design decisions **Why two classes rather than one.** `ChaosCryptCore` has no opinion about where key material comes from. `ChaosCrypt` assumes it comes from a file. Users who store keys in a database or a secrets manager want the first; users protecting their own files want the second. Neither has to compromise. **Why the TUI is in its own module.** Importing `chaoscrypt` should be cheap and should not pull in terminal handling. The TUI is imported only when actually launched. **Why `_core.py` is underscore-prefixed.** It signals that the internals of the algorithm are not part of the stable contract, while `ChaosCryptCore` itself is public and supported. The distinction is between the class and its underscore-prefixed members. **Why errors carry codes as well as messages.** Human-readable messages get improved, translated, or reworded. Programs need something that does not shift underneath them. Separating the two means both can evolve safely. **Why validation happens before processing.** A malformed ciphertext is rejected before any decryption work begins. Without this, garbage input would produce garbage output that is indistinguishable from success — a failure mode that is easy to miss precisely because it does not raise. --- ## Testing strategy | Layer | Approach | |---|---| | Algorithm | Round-trip across text, binary and edge cases; reference vectors pin output | | Compatibility | Load the legacy implementation and exchange data in both directions | | Errors | Assert on codes, not messages; verify codes are unique | | CLI | Subprocess invocation, checking exit codes and JSON payloads | | TUI | Piped key sequences, checking rendered output | | i18n | Verify every string exists in both languages | TUI tests work because the interface degrades to plain `input` when stdin is not a TTY. That fallback is required for automation anyway, so it serves both purposes. --- ## Performance notes - **Encryption is linear in message length.** The dominant cost is the two XOR passes, giving O(n) time and O(n) memory. - **Longer messages are not disproportionately slower**, because the long key is cycled rather than stretched — `_get_dynamic_key` repeats `K_long` to cover the message rather than generating fresh material. - **The short key covers 512 nibbles**, so key derivation work is bounded and independent of message size. - **Base64 introduces a constant 4/3 expansion**, and the hexadecimal encoding a further 2×. A 1 MB file therefore yields roughly 2.7 MB of ciphertext. None of these are bottlenecks in the intended use cases: personal files, notes, and document-sized payloads.