From 2384487838d8865278fbdc15daab0633f6b5f2cb Mon Sep 17 00:00:00 2001 From: Xavier V Date: Wed, 9 Sep 2026 18:24:09 -0400 Subject: [PATCH] Doc: Source of truth Documentation --- SoT.md | 260 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 260 insertions(+) create mode 100644 SoT.md diff --git a/SoT.md b/SoT.md new file mode 100644 index 0000000..488215c --- /dev/null +++ b/SoT.md @@ -0,0 +1,260 @@ +# ᛏ Cipher Master Engine — Technical & Operational Context Document + +This document serves as the single source of truth for **Cipher Master Engine**. It is designed to provide complete context to human developers, maintainers, and LLMs/AI assistants. It details the product requirements, system architecture, file structure, technology stack, cipher implementations, prompt engineering strategy, and software release procedures. + +--- + +## 1. Executive Summary & Product Specification + +* **Project Name**: Cipher Master Engine +* **Repository**: `https://github.com/ReVax-2007/cipher_master.git` +* **Target Platforms**: macOS (x86_64 / ARM64 `.dmg`) & Windows (x86_64 `.exe` / `.msi`) +* **Primary Objective**: Provide an offline-first desktop application that generates cryptanalytic challenges, structured hints, and solution keys. Outputs are automatically rendered and written to plain-text files on the user's Desktop. +* **License**: **CC BY-NC 4.0** (Creative Commons Attribution-NonCommercial 4.0 International). Commercial usage, reselling, or bundling into paid software is strictly prohibited. + +--- + +## 2. Technology Stack & Dependencies + +### Desktop Framework & Engine +* **Tauri v2 (`@tauri-apps/cli` v2)**: Native OS bindings, windowing, and IPC bridge. Chosen for its small memory footprint, security boundaries, and lightweight native builds compared to Electron. +* **Rust (2021 Edition / 1.75+)**: Backend logic, cipher encryption algorithms, file system IO, and HTTP client integration. + +### Frontend +* **HTML5 / CSS3 / JavaScript (ES6+)**: Plain, lightweight web interface located in the decoupled `./public` asset directory. Communicates with Rust strictly via Tauri IPC (`window.__TAURI__.core.invoke`). + +### Cargo Dependencies (`src-tauri/Cargo.toml`) +* `tauri`: Core framework features with `protocol-asset` and window controls. +* `serde` / `serde_json`: High-performance JSON serialization/deserialization for Rust-to-JS IPC payloads. +* `rand`: Pseudo-random number generation for cipher key generation, rotational offsets, and matrix shuffling. +* `ureq`: Synchronous, lightweight HTTP client used to query local LLM REST endpoints without pulling in heavy asynchronous runtimes. + +### External Integrations +* **Ollama (Optional)**: Connects via local HTTP REST API at `http://localhost:11434/api/generate` requesting the `llama3.2:1b` model. +* **Built-in Fallback**: Internal algorithmic phrase generator (`fallback_quote`) that operates when Ollama is unavailable, offline, or uninstalled. + +--- + +## 3. Directory & File Architecture + +```text +cipher_master/ +├── .github/ +│ └── workflows/ +│ └── release.yml # GitHub Actions CI/CD pipeline (macOS + Windows) +├── public/ +│ └── index.html # Isolated frontend web assets (Tauri frontendDist) +├── src-tauri/ +│ ├── Cargo.toml # Rust dependencies and binary metadata +│ ├── tauri.conf.json # Tauri app configuration, bundle ID, window specs +│ ├── icons/ # Multi-resolution platform icons (.icns, .ico, PNGs) +│ └── src/ +│ ├── lib.rs # Core cipher logic, file IO, IPC commands & AI client +│ └── main.rs # Execution entry point +├── app-icon.png # Master 1024x1024 high-resolution source icon +├── SUGGESTED_FEATURES.md # Feature roadmap +├── SUGGESTED_INTEGRATIONS.md # Third-party service integration roadmap +├── SUGGESTED_UPGRADES.md # Infrastructure and architectural upgrade roadmap +├── LICENSE # CC BY-NC 4.0 Legal terms +└── README.md # Primary repository documentation +``` + +--- + +## 4. Key Configurations (`tauri.conf.json`) + +To compile valid release installers, the bundle identifier must avoid default placeholders (`com.tauri.dev`). + +```json +{ + "$schema": "[https://schema.tauri.app/config/2](https://schema.tauri.app/config/2)", + "productName": "Cipher Master", + "version": "1.0.0", + "identifier": "com.xvoet.ciphermaster", + "build": { + "frontendDist": "../public" + }, + "app": { + "windows": [ + { + "title": "Cipher Master", + "width": 800, + "height": 600, + "resizable": true, + "fullscreen": false + } + ] + }, + "bundle": { + "active": true, + "targets": "all", + "icon": [ + "icons/32x32.png", + "icons/128x128.png", + "icons/128x128@2x.png", + "icons/icon.icns", + "icons/icon.ico" + ] + } +} +``` + +--- + +## 5. Core Engine Implementations & Methodologies + +### A. Supported Cipher Algorithms (`src-tauri/src/lib.rs`) + +1. **Elder Futhark Runes**: Maps standard Latin characters ($A..Z$) to Unicode Elder Futhark runic characters ($\text{ᚠ, ᚢ, ᚦ, ᚨ, ᚱ, ᚲ, \dots}$). +2. **Caesar Shift**: Rotates alphabetic index by a pseudo-random integer $k \in [1, 25]$: + +$$E(x) = (x + k) \pmod{26}$$ + + +3. **Atbash Cipher**: Reverses the alphabet index: + +$$E(x) = (25 - x) \pmod{26}$$ + + +4. **Monoalphabetic Substitution**: Generates a shuffled 26-character alphabet array via `rand::seq::SliceRandom` and maps $A..Z$ directly to the permutation. +5. **Vigenère Cipher**: Accepts a multi-character key phrase $K$; shifts character $i$ using offset $K[i \pmod{|K|}]$. +6. **Rail Fence (Zig-Zag)**: Constructs a $W \times H$ rail matrix based on $N$ rails, routes plaintext in a zig-zag movement, and reads row-by-row. +7. **Affine Cipher**: Multiplies and shifts characters using key pair $(a, b)$ where $\gcd(a, 26) = 1$: + +$$E(x) = (a \cdot x + b) \pmod{26}$$ + + +8. **A1Z26 Numeric**: Converts each letter to its 1-based numerical index separated by hyphens (e.g., $A=1, B=2, Z=26$). + +### B. Difficulty Formatting Pipeline + +* **Easy**: Maintains original spaces, lower/upper case, and punctuation. Appends detailed vowel count and frequency metrics in `cipher_hint.txt`. +* **Medium**: Converts string to uppercase and strips all spaces and non-alphanumeric characters. +* **Hard**: Uppercases, strips non-alphanumeric characters, and formats the output into uniform 5-character blocks (e.g., `HELL O WORL D` $\rightarrow$ `HELLO WORLD` $\rightarrow$ `HELLO WORLD`). + +### C. Desktop Output File Protocol + +Upon execution of the `generate_cipher_files` IPC command, the engine resolves the user's local Desktop path (`dirs::desktop_dir` or `dirs-next`) and writes three distinct files: + +1. `cipher_challenge.txt`: Contains difficulty level, cipher type name, and formatted ciphertext. +2. `cipher_hint.txt`: Contains character length, structural analysis, letter distribution metrics, and riddle clues. +3. `cipher_solution.txt`: Contains original plaintext, decryption parameters/keys, and step-by-step decoding notes. + +--- + +## 6. AI Prompting Strategy & Local Fallback + +### Ollama Prompt Strategy + +When an AI quote is requested, `ureq::post` issues a JSON payload to `http://localhost:11434/api/generate`: + +```json +{ + "model": "llama3.2:1b", + "prompt": "Generate a single inspirational, philosophical, or historical quote suitable for a cryptographic puzzle. Output ONLY the quote text itself. Do not include quotes, commentary, or attribution.", + "stream": false +} +``` + +### Algorithmic Fallback Engine + +If Ollama fails to respond within the socket timeout or is offline, `fallback_quote(length_choice)` executes deterministically: + +* Uses randomized array selection across pre-defined arrays (`TOPICS`, `ACTIONS`, `QUALIFIERS`). +* Concatenates items into structured uppercase sentences (e.g., `"KNOWLEDGE FAVORED THE BRAVE MINDS AND PROTECTED LIBERTY WITH SECRETS"`). + +--- + +## 7. Development, Replicating & Debugging + +### Running Dev Mode + +To run and inspect IPC events locally on macOS: + +```bash +cargo tauri dev +``` + +### Manual Quote Modifications + +If you want to alter or add static quotes without Ollama, update `fallback_quote` in `src-tauri/src/lib.rs`: + +```rust +fn fallback_quote(_length_choice: usize) -> String { + "CUSTOM PASSTHROUGH TEXT GOES HERE".to_string() +} +``` + +### Isolating IPC Mismatches + +When calling Rust commands from JS, parameter names must match verbatim in camelCase or snake_case as declared: + +* **Rust**: `pub fn generate_cipher_files(cipher_type: String, difficulty: String)` +* **JS**: `invoke('generate_cipher_files', { cipherType: 'caesar', difficulty: 'easy' })` + +--- + +## 8. CI/CD & Maintenance Rules + +### Branching Policy + +Direct pushes to `master` are strictly disabled in project guidelines. All modifications must follow: + +1. Feature branch creation (`git checkout -b feature/name`). +2. Local validation (`cargo tauri dev`). +3. PR submission and merge into `master`. + +### Triggering Production Releases (Maintainers Only) + +Releases are built via GitHub Actions (`.github/workflows/release.yml`) targeting `macos-latest`, `windows-latest` and `ubuntu-latest`. + +```bash +# Tag master commit +git tag v1.0.x +git push origin v1.0.x +``` + +GitHub Actions compiles `.dmg`, `.exe`, and `.msi` installers and attaches them directly as release binaries to the corresponding release draft. + +## 9. Foundation & Construction Prompts + +This section documents the foundational prompts and guidelines used to construct the Cipher Master Engine architecture, backend algorithms, and release workflows. + +### A. Initial Architectural Prompt (Foundation & Tech Stack Setup) +> **Goal:** Establish a lightweight, cross-platform Tauri v2 desktop application with Rust backend logic and isolated frontend assets. +> +> **Prompt:** +> "Act as a Senior Rust & Desktop Engineer. I want to build a desktop app named 'Cipher Master' using Tauri v2 and Rust. +> Key Requirements: +> 1. Separate backend logic into Rust (`src-tauri/src/lib.rs`) and keep web assets isolated in a `./public` folder. +> 2. Implement IPC communication between JavaScript (`window.__TAURI__.core.invoke`) and Rust commands. +> 3. Implement 8 cipher engines: Elder Futhark Runes, Caesar Shift, Atbash, Monoalphabetic Substitution, Vigenère, Rail Fence, Affine Cipher, and A1Z26. +> 4. Support three difficulty levels (Easy, Medium, Hard) that modify punctuation, casing, and 5-character block grouping. +> 5. Output three plain-text files directly to the user's Desktop upon execution: `cipher_challenge.txt`, `cipher_hint.txt`, and `cipher_solution.txt`." + +### B. Local AI Integration & Fallback Prompt +> **Goal:** Connect to local LLM instances while maintaining robust offline fallback functionality. +> +> **Prompt:** +> "Integrate a local Ollama API client using the synchronous `ureq` crate in Rust. +> Requirements: +> 1. Query `http://localhost:11434/api/generate` with model `llama3.2:1b` to pull a single short philosophical/inspirational quote. +> 2. Implement a non-blocking timeout strategy. If Ollama is offline or takes too long, seamlessly fall back to an internal algorithmic quote generator function (`fallback_quote`) without crashing or showing an error in the GUI." + +### C. Bundle Identifier & Asset Isolation Debugging Prompts +> **Goal:** Resolve Tauri production bundler errors regarding reserved identifiers and asset directory overlapping. +> +> **Prompt:** +> "Fix the Tauri build errors: +> 1. `Error You must change the bundle identifier`: Update `tauri.conf.json` with a unique reverse-DNS bundle identifier (`com.xvoet.ciphermaster`). +> 2. `Error The configured frontendDist includes the src-tauri folder`: Separate `index.html` into a dedicated `public/` directory and update `frontendDist` in `tauri.conf.json` to point to `../public`." + +### D. CI/CD Release Pipeline Prompt +> **Goal:** Automate cross-platform compilation for macOS and Windows using GitHub Actions. +> +> **Prompt:** +> "Create a GitHub Actions release workflow `.github/workflows/release.yml` triggered on version tags (`v*`). +> Requirements: +> 1. Use a matrix build targeting `macos-latest` and `windows-latest`. +> 2. Use `tauri-apps/tauri-action@v0` to build `.dmg`, `.exe`, and `.msi` installers. +> 3. Ensure source code tarballs/zips are not uploaded as standalone release binaries, attaching only compiled production installers to the GitHub Release draft." \ No newline at end of file