doxa/doxa-secret/MANUAL.md

# 🦅 USER MANUAL (DOXA-SECRET)

**DOXA-SECRET** is a minimalist, local-first command-line text encryption and decryption tool. Designed with security and privacy in mind, it allows you to convert plain text messages into secret, encrypted strings using unique 5-character cipher codes stored locally as JSON files. Written in **Go**, it offers a modern Terminal User Interface (**TUI**) built with Charm's Bubble Tea and Lip Gloss.

<p align="center">
  <img src="https://img.shields.io/badge/go-1.22+-00ADD8?style=flat-square&logo=go&logoColor=white" alt="Go 1.22+">
  <img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="MIT license">
  <img src="https://img.shields.io/badge/tested-Linux-brightgreen?style=flat-square" alt="Tested on Linux">
</p>
<p align="center"> 
   <img src="https://img.shields.io/badge/freebsd-AB2B28?style=for-the-badge&logo=freebsd&logoColor=white" alt="freeBSD">
</p>

---

## TABLE OF CONTENTS
1. [Installation & Execution](#1-installation--execution)
2. [Cipher Architecture & Schema](#2-cipher-architecture--schema)
3. [Interactive Interface & States](#3-interactive-interface--states)
4. [Keyboard Shortcuts Reference](#4-keyboard-shortcuts-reference)
5. [Cipher Distribution & Import/Export](#5-cipher-distribution--importexport)
6. [Uninstallation](#6-uninstallation)

---

## 1. INSTALLATION & EXECUTION

### Prerequisites
Before installing, make sure you have **Go** installed on your system (version **1.20** or higher is recommended).

### Installation Steps (Linux / macOS / FreeBSD)
1. **Clone the repository:**
   ```bash
   git clone https://codeberg.org/Kankys/doxa-secret.git
   cd doxa-secret
   ```
2. **Run the installation script:**
   ```bash
   chmod +x install.sh
   ./install.sh
   ```
   *The script checks your Go installation, downloads all dependencies, compiles the binary, installs the executable `doxa-secret` to `~/.local/bin/`, and prepares the config directory `~/.doxa-secret/`.*

3. **Add to PATH (if necessary):**
   If the `doxa-secret` command is not recognized, add the following line to your shell profile (e.g., `~/.bashrc` or `~/.zshrc`):
   ```bash
   export PATH=$PATH:$HOME/.local/bin
   ```
   Then restart your terminal or reload your profile using `source ~/.bashrc`.

### Post-Installation Cleanup
Once completed, you can safely remove the cloned repository directory:
```bash
rm -rf doxa-secret
```

---

## 2. CIPHER ARCHITECTURE & SCHEMA

All ciphers are stored as JSON files inside the configuration directory `~/.doxa-secret/`.
When the application starts for the first time, a `default.json` cipher is automatically generated.

### Cipher JSON Structure
Each cipher maps basic Latin characters (excluding accents/diacritics, which are automatically normalized to basic Latin to avoid cross-system character encoding issues, and including spaces, commas, periods, numbers) to unique, randomly-generated **5-character alphanumeric codes**:

```json
{
  "version": "1.0",
  "mappings": {
    " ": "k9#pA",
    ",": "L5z2M",
    ".": "q7R1o",
    "a": "H3nK9",
    "b": "8vX1m"
  }
}
```

---

## 3. INTERACTIVE INTERFACE & STATES

The application supports multiple interactive states within the Terminal User Interface:

### A. Main Menu
Allows you to choose from three main options:
1. **Write Message**: Compose a plaintext message and save its encrypted output as a `.txt` file into the `~/doxa-secret/export/` directory.
2. **Decrypt Message**: Load an encrypted message from a `.txt` file (placed in the `~/doxa-secret/import/` directory) and read its decrypted contents.
3. **Manage Ciphers**: Create, switch, import, or export cipher keys.

### B. Write Screen
Includes a large message editor field and a filename input field. Switching between these fields is done with the `[Tab]` key. Pressing `[Ctrl+S]` encrypts the message and saves it to `~/doxa-secret/export/<filename>`.

### C. Decrypt Screen
Prompts you to enter the name of an encrypted `.txt` file (to be read from `~/doxa-secret/import/`) or an absolute path to a file. The application loads the file, decrypts it using the currently active cipher, and opens a viewport for reading.

---

## 4. KEYBOARD SHORTCUTS REFERENCE

| Key | Context | Action |
|-----|---------|--------|
| `ctrl+c` | Global | Force Quit |
| `l` | Main Menu | Toggle Language (Czech / English) |
| `1` | Main Menu | Open Write Message screen |
| `2` | Main Menu | Open Decrypt/Read Message screen |
| `3` | Main Menu | Open Cipher Management screen |
| `q` / `esc` | Main Menu | Quit application |
| `tab` | Write Screen | Toggle between message content and filename field |
| `ctrl+s` | Write Screen | Save encrypted message to file |
| `esc` | Editor / Forms | Cancel and return to previous menu |
| `up` / `down` / `k` / `j` | Ciphers List | Navigate through ciphers list |
| `enter` | Ciphers List | Activate selected cipher |
| `c` | Ciphers List | Create a new custom cipher |
| `i` | Ciphers List | Import a cipher file |
| `e` | Ciphers List | Export the active cipher file |
| `d` | Ciphers List | Delete the selected cipher |

---

## 5. CIPHER DISTRIBUTION & IMPORT/EXPORT

To share encrypted messages with another person, they must have the exact same cipher JSON file loaded in their `doxa-secret` configuration directory.

### Exporting a Cipher
1. In the **Cipher Management** screen, select the cipher you want to export and make sure it is active.
2. Press `e` to export.
3. Enter the destination path (e.g. `/path/to/my_cipher.json`).
4. Share this file with the recipient.

### Importing a Cipher
1. In the **Cipher Management** screen, press `i` to import.
2. Enter the path to the JSON file you received.
3. The cipher will be automatically validated, copied to your configuration folder, and made active.

---

## 6. UNINSTALLATION

To fully remove the tool and its configuration files from your system, execute:

```bash
rm ~/.local/bin/doxa-secret
rm -rf ~/.doxa-secret
```
*Caution: Deleting `~/.doxa-secret` will permanently erase all your cipher keys.*