From ed1d230b4e997fda0ab4062899bcb3cb295e7ea8 Mon Sep 17 00:00:00 2001 From: "Aaron D. Lee" Date: Sun, 4 Jan 2026 03:09:02 -0500 Subject: [PATCH] Add template specification documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs/TEMPLATES.md - Quick reference for all Jinja2 templates, their routes, form fields, and JS dependencies. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- docs/TEMPLATES.md | 361 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 361 insertions(+) create mode 100644 docs/TEMPLATES.md diff --git a/docs/TEMPLATES.md b/docs/TEMPLATES.md new file mode 100644 index 0000000..8c3f834 --- /dev/null +++ b/docs/TEMPLATES.md @@ -0,0 +1,361 @@ +# Stegasoo Web Templates Specification + +Quick reference for all Jinja2 templates in `frontends/web/templates/`. + +## Table of Contents + +- [Layout](#layout) +- [Auth & Setup](#auth--setup) +- [Core Features](#core-features) +- [Tools & Account](#tools--account) +- [Admin](#admin) + +--- + +## Layout + +### `base.html` +**Purpose:** Master layout template - all pages extend this. + +| Block | Description | +|-------|-------------| +| `{% block title %}` | Page title | +| `{% block content %}` | Main page content | +| `{% block scripts %}` | Page-specific JS | + +**Key Elements:** +- `nav.navbar` - Bootstrap 5 navbar with logo, links, auth buttons +- `div.toast-container` - Flash message toasts (10s auto-dismiss) +- `main.container` - Content wrapper +- `footer` - Copyright + version + +**Variables:** `is_authenticated`, `username`, `is_admin` + +--- + +## Auth & Setup + +### `login.html` +**Route:** `/login` + +**Form:** `POST /login` +- `username` - text input +- `password` - password input +- "Forgot password?" link to `/recover` + +**JS:** `static/js/auth.js` - password toggle + +--- + +### `setup.html` +**Route:** `/setup` (first-run only) + +**Form:** `POST /setup` +- `username` - admin username +- `password` - password (min 8 chars) +- `password_confirm` - confirmation + +**JS:** Password confirmation validation + +--- + +### `setup_recovery.html` +**Route:** `/setup/recovery` + +**Form:** `POST /setup/recovery` +- `recovery_key` - hidden, pre-generated +- `action` - "save" or "skip" +- Checkbox confirmation required for save + +**Features:** +- Recovery key display (readonly input) +- Copy to clipboard button +- QR code image (if available) +- Download options: text file, QR image +- Stego backup upload form + +--- + +### `recover.html` +**Route:** `/recover` + +**Form:** `POST /recover` +- `recovery_key` - textarea for key input +- `new_password` - new password +- `new_password_confirm` - confirmation + +**Accordion:** "Extract from stego backup" +- `POST /recover/stego` with `stego_image` + `reference_image` +- Pre-fills recovery key on success + +--- + +### `regenerate_recovery.html` +**Route:** `/account/recovery/regenerate` (admin only) + +**Form:** `POST /account/recovery/regenerate` +- `recovery_key` - hidden field +- `action` - "save" or "cancel" +- Confirmation checkbox + +**Features:** +- New key display +- QR code (obfuscated) +- Download: text, QR, stego backup +- Warning if replacing existing key + +--- + +## Core Features + +### `index.html` +**Route:** `/` + +**Structure:** +- Hero section with tagline +- 3 action cards: Encode, Decode, Generate +- "How It Works" explainer section + +--- + +### `generate.html` +**Route:** `/generate` + +**Form:** `POST /generate` +- `words` - passphrase word count (3-12) +- `use_pin` - checkbox +- `pin_length` - PIN digits (6-9) +- `use_rsa` - checkbox +- `rsa_bits` - key size (2048/3072/4096) + +**Output panels:** +- Passphrase display +- PIN display (if enabled) +- RSA key + QR (if enabled) +- Entropy calculator + +**JS:** `static/js/generate.js` + +--- + +### `encode.html` +**Route:** `/encode` + +**Form:** `POST /encode` (multipart) +- `reference_photo` - file upload (drag-drop zone) +- `carrier_image` - file upload (drag-drop zone) +- `mode` - radio: DCT (default) / LSB +- `dct_format` - PNG / JPEG +- `dct_color` - Color / Grayscale +- `payload_type` - radio: Text / File +- `message` - textarea (if text) +- `embed_file` - file input (if file) +- `passphrase` - text input +- `pin` - text input +- `rsa_key` / `rsa_key_qr` - file inputs +- `rsa_key_password` - password +- `channel_key` - select (saved keys) or manual input + +**Panels:** +- Reference preview with "Hash Acquired" status +- Carrier preview with capacity info +- Character counter for message + +**JS:** `static/js/encode.js`, `static/js/stegasoo.js` + +--- + +### `encode_result.html` +**Route:** `/encode/result/` + +**Elements:** +- Success message +- Stego image preview +- Download button +- Share button (Web Share API) +- Mode/capacity info +- "Encode Another" link + +**Variables:** `file_id`, `filename`, `mode`, `capacity_used` + +--- + +### `decode.html` +**Route:** `/decode` + +**Form:** `POST /decode` (multipart) +- `reference_photo` - file upload +- `stego_image` - file upload +- `passphrase` - text input +- `pin` - text input +- `rsa_key` / `rsa_key_qr` - file inputs +- `rsa_key_password` - password +- `channel_key` - select or manual + +**Output:** +- Decoded message display +- File download (if file payload) + +**JS:** `static/js/decode.js`, `static/js/stegasoo.js` + +--- + +## Tools & Account + +### `tools.html` +**Route:** `/tools` + +**Tabbed interface:** + +| Tab | Endpoint | Description | +|-----|----------|-------------| +| Capacity | `POST /api/tools/capacity` | Image capacity analysis | +| Peek | `POST /api/tools/peek` | Check for Stegasoo header | +| Strip | `POST /api/tools/strip` | Remove hidden data | +| EXIF | `POST /api/tools/exif/*` | Metadata viewer/editor | + +**EXIF Editor features:** +- Upload image → view all EXIF fields +- Inline editing (click field to edit) +- "Clear All" button +- "Save" / "Download" buttons + +**JS:** `static/js/tools.js` + +--- + +### `account.html` +**Route:** `/account` + +**Sections:** + +1. **User Info** - Username, role badge, logout link + +2. **Recovery Key** (admin only) + - Status: Configured / Not Set + - Generate/Regenerate button + - Disable button + +3. **Password Change** + - `current_password` + - `new_password` + - `new_password_confirm` + +4. **Saved Channel Keys** + - List of saved keys with edit/delete + - "Add Key" form (name + key) + - Max 10 keys per user + +**Variables:** `username`, `is_admin`, `has_recovery`, `channel_keys` + +--- + +### `about.html` +**Route:** `/about` + +**Sections:** +- Version info + feature badges +- Security model explanation +- Channel key QR (if configured) +- Dependency status table +- Credits + links + +**Variables:** `version`, `has_dct`, `has_qr_write`, `has_qr_read`, `channel_key`, `channel_qr` + +--- + +## Admin + +### `admin/users.html` +**Route:** `/admin/users` + +**Table columns:** Username | Role | Created | Actions + +**Actions per user:** +- Reset Password button +- Delete button (disabled for self) + +**Header:** +- User count: "X of 16 users" +- "Add User" button (modal trigger) + +**Modal:** Add User form +- `username` input +- `role` select (admin/user) +- Auto-generated temp password display + +--- + +### `admin/user_new.html` +**Route:** `/admin/users/new` + +**Form:** `POST /admin/users/new` +- `username` - text input +- `role` - select (user/admin) + +Redirects to `user_created.html` on success. + +--- + +### `admin/user_created.html` +**Route:** `/admin/users/created` + +**Display:** +- Success message +- Username +- Temporary password (copy button) +- "User must change password on first login" notice +- Back to users link + +--- + +### `admin/password_reset.html` +**Route:** `/admin/users//password-reset` + +**Display:** +- Success message +- New temporary password +- Copy button +- Back link + +--- + +## Common Patterns + +### Drag-Drop Upload Zones +```html +
+ +
+
+
+``` + +### Password Toggle +```html +
+ + +
+``` + +### Toast Flash Messages +Rendered in `base.html`, auto-dismiss after 10 seconds: +- `success` → green +- `warning` → yellow +- `error` → red + +--- + +## External JS Files + +| File | Used By | +|------|---------| +| `static/js/stegasoo.js` | encode, decode, about | +| `static/js/auth.js` | login, setup, recover, account | +| `static/js/generate.js` | generate | +| `static/js/encode.js` | encode | +| `static/js/decode.js` | decode | +| `static/js/tools.js` | tools |