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.

---

TABLE OF CONTENTS

1. Installation & Execution
2. Cipher Architecture & Schema
3. Interactive Interface & States
4. Keyboard Shortcuts Reference
5. Cipher Distribution & Import/Export
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:

   git clone https://codeberg.org/Kankys/doxa-secret.git
   cd doxa-secret
   

2. Run the installation script:

   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):

   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:

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:

{
  "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:

rm ~/.local/bin/doxa-secret
rm -rf ~/.doxa-secret

Caution: Deleting ~/.doxa-secret will permanently erase all your cipher keys.