mirror of
https://codeberg.org/Kankys/doxa.git
synced 2026-11-11 06:44:36 +01:00
new-doxa-monorepo
This commit is contained in:
kankys committed
1 parent
b4401527a3
commit
5eacbb0182
162 files changed
+21820
-2
No files matched your search
@@ -0,0 +1,147 @@
|
||||
# 🦅 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.*
|
||||
Reference in new issue
Block a user