thePR0M3TH3AN/VoxVera
1
0 Fork 0
mirror of https://github.com/PR0M3TH3AN/VoxVera.git synced 2026-10-27 09:40:40 +00:00
Code Issues Packages Projects Releases Wiki Activity

Remove legacy Tor app from main

Browse Source
This commit is contained in:
thePR0M3TH3AN committed 2026-06-05 10:13:41 -04:00
1 parent ee13d3fd03
commit 9aa90773e6
3028 files changed
+329 -488522
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

.devcontainer/devcontainer.json
-8
View File
@@ -1,8 +0,0 @@
{
"name": "VoxVera",
"build": {
"dockerfile": "../Dockerfile",
"context": ".."
},
"workspaceFolder": "/workspace/VoxVera"
}
.dockerignore
-16
View File
@@ -1,16 +0,0 @@
.git
.github
.pytest_cache
__pycache__
*.pyc
*.pyo
*.pyd
build
dist
ci-logs
docs
tests
imports
site
voxvera/host
voxvera/resources/bin
.flake8
-3
View File
@@ -1,3 +0,0 @@
[flake8]
max-line-length = 120
ignore = E501,E741,E401,E402
.github/workflows/binaries.yml
-173
View File
@@ -1,173 +0,0 @@
name: Build Standalone Binaries
on:
push:
tags:
- 'v*'
workflow_dispatch:
jobs:
build:
name: Build for ${{ matrix.os }}
runs-on: ${{ matrix.os }}
timeout-minutes: 60
strategy:
fail-fast: false
matrix:
os: [ubuntu-22.04, windows-latest, macos-latest]
include:
- os: ubuntu-22.04
artifact_name: voxvera-linux-x86_64
- os: windows-latest
artifact_name: voxvera-windows.exe
- os: macos-latest
artifact_name: voxvera-macos-x86_64
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.12'
- name: Install dependencies
run: |
pip install --upgrade setuptools pkg_resources || pip install --upgrade setuptools
pip install -r requirements.txt
pip install .
pip install pyinstaller pyinstaller-hooks-contrib
- name: Download Tor Binaries
shell: bash
run: |
chmod +x scripts/download_tor.sh
./scripts/download_tor.sh
- name: Build with PyInstaller
shell: bash
run: |
if [ "$RUNNER_OS" == "Windows" ]; then SEP=";"; else SEP=":"; fi
pyinstaller --onefile \
--collect-all pkg_resources \
--collect-all setuptools \
--hidden-import pkg_resources \
--hidden-import setuptools \
--hidden-import jaraco.text \
--hidden-import jaraco.functools \
--hidden-import jaraco.context \
--hidden-import more_itertools \
--hidden-import packaging \
--hidden-import platformdirs \
--collect-all onionshare_cli \
--collect-all flask_socketio \
--collect-all engineio \
--collect-all socketio \
--collect-all eventlet \
--collect-all gevent \
--add-data "voxvera/locales${SEP}voxvera/locales" \
--add-data "voxvera/src${SEP}voxvera/src" \
--add-data "voxvera/templates${SEP}voxvera/templates" \
--add-data "voxvera/resources/tor${SEP}voxvera/resources/tor" \
--add-data "support-matrix.json${SEP}." \
--add-data "requirements.txt${SEP}." \
--name "${{ matrix.artifact_name }}" \
voxvera/cli.py
- name: Validate built binary contract surface (Linux/macOS)
if: matrix.os != 'windows-latest'
shell: bash
run: |
./dist/${{ matrix.artifact_name }} platform-status --json
./dist/${{ matrix.artifact_name }} doctor --json
./dist/${{ matrix.artifact_name }} autostart status --json
- name: Validate built binary contract surface (Windows)
if: matrix.os == 'windows-latest'
shell: pwsh
run: |
& ".\dist\${{ matrix.artifact_name }}" platform-status --json
& ".\dist\${{ matrix.artifact_name }}" doctor --json
& ".\dist\${{ matrix.artifact_name }}" autostart status --json
- name: Build .deb (Linux)
if: matrix.os == 'ubuntu-22.04'
run: |
mkdir -p voxvera/resources/bin
cp dist/${{ matrix.artifact_name }} voxvera/resources/bin/voxvera-linux-x86_64
chmod +x packaging/build_deb.sh
./packaging/build_deb.sh dist/${{ matrix.artifact_name }}
- name: Build AppImage (Linux)
if: matrix.os == 'ubuntu-22.04'
run: |
mkdir -p voxvera/resources/bin
cp dist/${{ matrix.artifact_name }} voxvera/resources/bin/voxvera-linux-x86_64
chmod +x packaging/build_appimage.sh
./packaging/build_appimage.sh dist/${{ matrix.artifact_name }}
- name: Validate Linux release artifacts
if: matrix.os == 'ubuntu-22.04'
shell: bash
run: |
chmod +x scripts/validate-release-artifacts.sh
./scripts/validate-release-artifacts.sh
- name: Build Flatpak (Linux)
if: matrix.os == 'ubuntu-22.04'
run: |
mkdir -p voxvera/resources/bin
cp dist/${{ matrix.artifact_name }} voxvera/resources/bin/voxvera-linux-x86_64
sudo apt-get update
sudo apt-get install -y flatpak flatpak-builder
chmod +x packaging/build_flatpak.sh
./packaging/build_flatpak.sh dist/${{ matrix.artifact_name }} || echo "Flatpak build failed"
- name: Build .dmg (macOS)
if: matrix.os == 'macos-latest'
run: |
mkdir -p voxvera/resources/bin
cp dist/${{ matrix.artifact_name }} voxvera/resources/bin/voxvera-macos-x86_64
chmod +x packaging/build_dmg.sh
./packaging/build_dmg.sh dist/${{ matrix.artifact_name }}
- name: Upload artifacts
uses: actions/upload-artifact@v4
with:
name: binaries-${{ matrix.os }}
path: |
dist/${{ matrix.artifact_name }}
voxvera/resources/bin/*.deb
voxvera/resources/bin/*.dmg
voxvera/resources/bin/*.AppImage
voxvera/resources/bin/*.flatpak
publish:
name: Create GitHub Release
needs: build
runs-on: ubuntu-latest
if: startsWith(github.ref, 'refs/tags/')
permissions:
contents: write
steps:
- name: Download all artifacts
uses: actions/download-artifact@v4
with:
path: artifacts
- name: Flatten artifacts for release
run: |
mkdir -p release_assets
find artifacts -type f -exec cp {} release_assets/ \;
ls -R release_assets/
- name: Release
uses: softprops/action-gh-release@v2
with:
files: |
release_assets/*
fail_on_unmatched_files: false
overwrite: true
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
.github/workflows/ci.yml
+12 -57
View File
@@ -2,71 +2,26 @@ name: CI
on:
push:
branches: [ main ]
branches: [main]
pull_request:
jobs:
lint-test:
static-client:
runs-on: ubuntu-latest
timeout-minutes: 15
timeout-minutes: 10
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: "22"
- uses: actions/setup-python@v5
with:
python-version: '3.12'
- name: Install dependencies
run: |
sudo apt-get update
sudo apt-get install -y tor
python -m pip install --upgrade pip
pip install flake8
pip install -e ".[test]"
pip install git+https://github.com/onionshare/onionshare.git#subdirectory=cli
- name: Lint
run: flake8 voxvera tests --exclude=voxvera/vendor --ignore=E501,W503,W293,E402,E306,E704,E261,F841,E302,F401,E401,F541
- name: Test
run: pytest tests/ -v
- name: Platform smoke
run: bash scripts/platform-smoke.sh linux-cli
platform-contract:
runs-on: ${{ matrix.os }}
timeout-minutes: 15
strategy:
fail-fast: false
matrix:
include:
- os: macos-latest
smoke_target: macos-cli
- os: windows-latest
smoke_target: windows-cli
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.12'
- name: Install dependencies
shell: bash
python-version: "3.12"
- name: Install Python test dependencies
run: |
python -m pip install --upgrade pip
pip install -e ".[test]"
- name: Verify smoke target listing
shell: bash
run: bash scripts/platform-smoke.sh list
- name: Validate platform-status JSON
shell: bash
run: python -m voxvera.cli platform-status --json
- name: Validate doctor JSON
shell: bash
run: python -m voxvera.cli doctor --json
- name: Validate autostart JSON
shell: bash
run: python -m voxvera.cli autostart status --json
docker-runtime:
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@v4
- name: Docker runtime smoke
run: bash scripts/docker-runtime-smoke.sh
- name: Check frontend JavaScript
run: node --check site/nostr/nostr-client.js
- name: Run tests
run: pytest -q
.github/workflows/e2e.yml
-31
View File
@@ -1,31 +0,0 @@
name: E2E
on:
push:
pull_request:
jobs:
e2e:
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.12'
- name: Install dependencies
run: |
sudo apt-get update
sudo apt-get install -y tor
python -m pip install --upgrade pip
pip install -e ".[e2e]"
- name: Run end-to-end tests
run: ci/test-e2e.sh
continue-on-error: true
- name: Upload logs
if: always()
uses: actions/upload-artifact@v4
with:
name: ci-logs
path: ci-logs/
.gitignore
+17 -51
View File
@@ -1,59 +1,25 @@
# Temporary files
*.tmp
tmp*/
# Python
__pycache__/
*.py[cod]
.pytest_cache/
*.egg-info/
.venv/
venv/
.venv
!voxvera/
!voxvera/resources/**
!voxvera/src/**
# OS and editor files
# Node/browser tooling
node_modules/
# Build and local output
build/
dist/
ci-logs/
# OS/editor noise
.DS_Store
Thumbs.db
*~
*.swp
__pycache__/
*.pyc
# Build and distribution artifacts
dist/
build/
*.egg-info/
# Electron app artifacts
gui/electron/node_modules/
gui/electron/dist/
gui/electron/build/
gui/electron/out/
# Generated host directories
host/*
!host/voxvera/
# CI logs
ci-logs/
# Onionshare logs and session files
# Local browser/debug artifacts
*.log
*.onionshare-session
gui/electron/package-lock.json
voxvera/src/config.json
voxvera/src/index.html
voxvera/src/nostr.html
voxvera/src/qrcode-content.png
voxvera/src/qrcode-tear-offs.png
# PyInstaller
*.spec
dist_bin/
voxvera/resources/bin/*
!voxvera/resources/bin/.gitkeep
site/download/*.zip
!site/download/voxvera-source.zip
site/download/*.exe
site/download/*.deb
site/download/*.dmg
site/download/*.AppImage
site/download/*.flatpak
site/download/voxvera-linux
site/download/voxvera-linux-x86_64
*.pdf
AGENTS.md
+27 -31
View File
@@ -1,42 +1,38 @@
# AI Agent Instructions for VoxVera
# AI Agent Instructions For VoxVera
This guide is for AI agents (like Gemini, Claude, or GPT) contributing to the VoxVera project. Follow these protocols to maintain the architectural integrity and multi-language support.
`main` is the Nostr static-client branch. The old Tor/OnionShare CLI application is preserved on `legacy-tor`.
## Core Mandates
## Current Architecture
1. **Security-First**: VoxVera is a Tor-based tool. Never suggest features that leak IP addresses or use non-Tor external resources (CDNs, etc.).
2. **Local-First**: All assets (fonts, dependencies, binaries) must be self-contained within the `voxvera/` package to support the Universal Mirroring model.
3. **Tokenized UI**: Never hardcode user-facing strings. Always add them to `voxvera/locales/en.json` and use the `t('cli.token')` helper.
4. **Markdown Redaction**: Use `~~text~~` in locale JSONs for strike-through effects. Both the build system and the JS engine handle the conversion to `<span class="redacted">` automatically.
5. **Visual Width Testing**: When modifying UI or adding languages, verify that long or complex strings (e.g., Hindi ligatures or CJK characters) do not exceed the visual unit limits defined in the CLI.
- Active frontend: `site/nostr/`
- Static deployment root: `site`
- Browser dependencies: vendored under `site/nostr/vendor/`
- Python helper package: `voxvera/nostr/`
- Design plan: `docs/nostr-static-client-spec.md`
## Localization Protocol
## Guardrails
When adding a new language or updating an existing one:
- **CLI/Flyers**: Update `voxvera/locales/{lang}.json`. Include `meta`, `cli`, `web`, and `landing` categories.
- **Landing Page**:
- Directly update the `const locales` object in `site/index.html`.
- **Crucial**: Run `voxvera build-site` to generate the latest portable bundle and refresh the pre-rendered HTML.
- **Documentation**:
- Master templates live in `docs/templates/`.
- Localized overrides live in `voxvera/locales/{lang}/docs/`.
- **Crucial**: After any change to locales or templates, you MUST run `voxvera build-docs` to synchronize the output in `docs/{en,es,de}/`.
- Do not reintroduce the legacy Tor CLI, OnionShare runtime, installer, Electron manager, bundled Tor binaries, generated old flyer site, or packaging workflows on `main`.
- Keep the Nostr client static and host-agnostic.
- Do not load frontend dependencies from CDNs.
- Treat Nostr event content as untrusted. Escape rendered content and reject unsafe schema input.
- Preserve print behavior: app controls must not print or shift the flyer sheet in print output.
- Preserve the old flyer visual language unless the user explicitly asks for a redesign.
## Universal Mirroring
## Localization
VoxVera propagates through its own flyers.
- Every `voxvera build` and `voxvera build-site` generates `voxvera-portable.zip`.
- If you modify the core source code, ensure the `bundle_portable` function in `voxvera/cli.py` still correctly captures all necessary directories (especially `vendor/`, `locales/`, and `resources/`).
- Use `site/nostr/locales.js` for flyer content defaults.
- Use `NOSTR_UI` in `site/nostr/nostr-client.js` for editor/viewer controls and Nostr-specific labels.
- Add translations for every supported language when adding user-facing strings.
- Check right-to-left languages when touching layout.
## Verification Checklist
## Verification
Before finishing a task, ensure you have:
1. Run unit tests: `pytest tests/test_cli.py`.
2. Verified the localization: `voxvera --lang {lang} check`.
3. Rebuilt the documentation: `voxvera build-docs`.
4. Synchronized the public site: `voxvera build-site`.
5. Verified the portable bundle exists: `ls -l voxvera/host/*/download/voxvera-portable.zip` and `ls -l site/download/voxvera-portable.zip`.
Run:
---
```bash
node --check site/nostr/nostr-client.js
pytest -q
```
Follow these rules to ensure VoxVera remains a robust, viral, and decentralized tool for truth.
For visual or print changes, also run a local static server and inspect `/nostr/` in a browser.
CONTRIBUTING.md
+30 -38
View File
@@ -1,48 +1,40 @@
# Contributing to VoxVera
# Contributing To VoxVera
Thank you for your interest in contributing to VoxVera! This project aims to be a global, censorship-resistant tool, and your help—especially with translations—is vital.
VoxVera `main` is a static Nostr client. Keep contributions focused on the browser editor/viewer, Nostr event validation, printable flyer rendering, and static deployment.
## Adding a New Language
## Frontend
VoxVera uses a centralized token system for the CLI and Web components, and a template-based system for Documentation. To add a new language (e.g., French/`fr`), follow this checklist:
- Edit the active app under `site/nostr/`.
- Keep dependencies vendored under `site/nostr/vendor/`; do not rely on CDNs.
- Preserve viewer mode as a flyer-first experience.
- Keep editor, load, print, language, and other controls hidden from print output.
- Verify print layout after changes that affect the flyer surface.
### 1. The Token File
Create a new JSON file in `voxvera/locales/{lang_code}.json`.
- Use `en.json` as your master template.
- **`meta`**: Include the native language name and a flag emoji.
- **`cli`**: Translate all strings used in the terminal interface.
- **`web`**: Translate strings used on the generated landing pages and flyers.
- **`landing`**: Translate the specific content for the official VoxVera website.
- **Formatting**: You can use Markdown-style strike-throughs (`~~redacted text~~`) in any of these strings; they will be automatically converted to the stylized "redacted" effect on the flyers.
## Localization
### 2. The Landing Page
The main landing page is generated from the shared template and locale files.
- Add your language in `voxvera/locales/{lang_code}.json`.
- Do **not** edit `site/index.html` directly; it is generated output.
- Run `voxvera build-site` to refresh the public assets and inject your new locale into the generated HTML.
The static client currently uses `site/nostr/locales.js` plus the `NOSTR_UI` table in `site/nostr/nostr-client.js`.
### 3. Documentation
VoxVera uses the **Doc-Sync Engine** to keep manuals in sync.
- Create localized Markdown files in `voxvera/locales/{lang_code}/docs/`.
- Use the templates in `docs/templates/` as your guide.
- You can use `cli.token_name` to reference terminal commands automatically.
When adding user-facing text:
### 4. Build and Verify
Run the following commands to verify your changes:
- `voxvera --lang {lang_code} check` (Verify CLI translation)
- `voxvera build-docs` (Generate localized manuals)
- `voxvera build-site` (Synchronize the public website and generate the latest portable bundle)
- Open the generated `site/index.html` in a browser and test the language switcher.
- Add translations for every supported language.
- Check right-to-left languages in the browser where layout may be affected.
- Keep side-tab strings short enough for tear-off strips.
## Code Contributions
- **Dependencies**: if you add a new Python library to `requirements.txt`, you MUST run `voxvera vendorize` to include it in the portable distribution.
- **Layout Integrity**: VoxVera uses visual width validation. If you add new UI elements, ensure they respect the physical boundaries of an 8.5"x11" flyer.
- **Tests**: Ensure all tests pass: `pytest tests/`. Run the integrity suite specifically when modifying locales: `pytest tests/test_integrity.py`.
- **Recommended local check**: Run `bash scripts/check.sh` before opening a PR. It mirrors the main lint/test/build checks in one command.
- **Generated artifacts**: Treat `voxvera/resources/bin/` as local build output, not source files. Release binaries belong in GitHub Releases, not hand-edited repo state.
- **Style**: Follow the existing coding style (PEP 8 for Python).
- **Documentation**: If adding a new feature, update the master templates in `docs/templates/` and run `voxvera build-docs`.
## Nostr Schema
---
Python validation helpers live in `voxvera/nostr/`. Keep the schema conservative:
Together, we can ensure that truth remains accessible to everyone, everywhere.
- Reject raw HTML in user-supplied flyer fields.
- Reject unsupported URL schemes.
- Keep attachments out of V1 events unless the spec is deliberately expanded.
## Verification
Run:
```bash
node --check site/nostr/nostr-client.js
pytest -q
```
For UI work, also run a local static server and inspect `/nostr/` in a browser.
Dockerfile
-30
View File
@@ -1,30 +0,0 @@
FROM python:3.11-slim
# Experimental container path: Linux systemd remains the supported
# persistent-host deployment target.
# Install system dependencies (only runtime)
RUN apt-get update && apt-get install -y --no-install-recommends \
tini tor onionshare-cli \
&& rm -rf /var/lib/apt/lists/*
# Copy VoxVera source
COPY . /opt/voxvera
WORKDIR /opt/voxvera
# Install VoxVera and its Python dependencies
RUN pip install . \
&& chmod +x scripts/docker-entrypoint.sh scripts/docker-healthcheck.sh \
&& ln -sf /opt/voxvera/scripts/docker-entrypoint.sh /usr/local/bin/voxvera-docker-entrypoint \
&& ln -sf /opt/voxvera/scripts/docker-healthcheck.sh /usr/local/bin/voxvera-docker-healthcheck
# Prepare flyers volume
RUN mkdir /flyers
ENV VOXVERA_DIR=/flyers
ENV VOXVERA_RUNTIME=docker
VOLUME /flyers
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 CMD ["voxvera-docker-healthcheck"]
ENTRYPOINT ["tini", "--", "voxvera-docker-entrypoint"]
CMD []
MANIFEST.in
-5
View File
@@ -1,5 +0,0 @@
include voxvera/templates/**
include voxvera/src/**
include voxvera/resources/**
include voxvera/locales/**
include voxvera/resources/bin/**
README.md
+30 -68
View File
@@ -1,92 +1,54 @@
# VoxVera
**Anonymous Information Distribution Engine**
VoxVera is now a static Nostr-powered flyer client.
Generate printable flyers with QR codes linking to Tor (.onion) hidden services. VoxVera is built for activists, journalists, and anyone who needs to spread a message securely and anonymously.
The active app lives at [`site/nostr/`](site/nostr/). It lets a user author flyer content, publish it as a public Nostr event, and render the flyer later from an event ID or Nostr address. The frontend is intentionally self-contained: relays store the content, and any static host can serve the client.
---
The previous Tor/OnionShare CLI version is preserved on the `legacy-tor` branch.
## Installation
## What Is In `main`
VoxVera is designed for maximum portability and censorship resistance.
- `site/nostr/`: static editor/viewer client
- `site/nostr/vendor/`: vendored browser dependencies for Nostr and QR generation
- `site/CNAME`: custom-domain target
- `voxvera/nostr/`: small Python schema/validation helpers
- `docs/nostr-static-client-spec.md`: design notes and development plan
Linux with systemd is the supported persistent-host deployment target.
Windows, macOS, Docker, Flatpak, AppImage, Homebrew, and Chocolatey remain experimental until their background Tor hosting and auto-recovery paths are validated end-to-end.
## Local Development
See [docs/platform-support-matrix.md](docs/platform-support-matrix.md) for the canonical platform status table and [docs/roadmap-platform-parity.md](docs/roadmap-platform-parity.md) for the parity plan.
For the supported Linux hosting path, use [docs/linux-hosting-validation.md](docs/linux-hosting-validation.md) as the operational validation runbook.
Run the static site from the repo root:
### 1. Standalone Binaries (Recommended)
Download the executable for your OS:
- 🐧 [**Linux**](https://github.com/PR0M3TH3AN/VoxVera/releases/latest/download/voxvera-linux)
- 🪟 [**Windows (Experimental)**](https://github.com/PR0M3TH3AN/VoxVera/releases/latest/download/voxvera-windows.exe)
- 🍏 [**macOS (Experimental)**](https://github.com/PR0M3TH3AN/VoxVera/releases/latest/download/voxvera-macos)
### 2. Universal Mirroring (The "Viral" Method)
If you found a physical VoxVera flyer, scan it and click **"Download"**. You will receive a `voxvera-portable.zip` containing the full tool, all dependencies, and all 14 languages—ready to run offline.
### 3. One-Line Installer (Linux/macOS)
```bash
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
```
On Linux, this now installs the recurring `systemd --user` recovery timer used to retry hidden-service startup after boot or offline periods. On macOS, the installer path is still experimental.
### 4. Developer / Python Install
```bash
pip install .
voxvera vendorize # Optional: pull dependencies locally for offline use
python3 -m http.server 8768 --directory site
```
### 5. Local Validation
Run the full local validation sweep with:
```bash
bash scripts/check.sh
Then open:
```text
http://127.0.0.1:8768/nostr/
```
This runs linting, Python tests, Electron smoke tests, dependency checks, and the docs/site rebuild steps used during development.
---
No build command is required for the frontend.
## Key Features
## Vercel
* **Universal Mirroring**: Every flyer acts as a mirror for the tool itself. The "Download" button provides a portable version of VoxVera, creating a decentralized distribution network.
* **Standalone Binaries**: Zero-install executables for high-security environments.
* **Global Multi-Script Support**: Native support for 14 languages including **Arabic (RTL)**, **Hebrew (RTL)**, **Hindi (Devanagari)**, **Japanese/Chinese (CJK)**, and **Russian (Cyrillic)**.
* **Tor-Safe Architecture**: 100% static HTML flyers. Works perfectly in Tor "Safest" mode with **JavaScript completely disabled**.
* **Integrated Server Manager**: `voxvera manage` provides an interactive UI to handle multiple flyers, monitor Tor bootstrapping, and manage persistent .onion URLs.
* **Secure Migration**: Bulk export and import of flyers and their unique Tor identity keys via `~/voxvera-exports/`.
Point Vercel at this repository on `main`.
---
- Framework preset: Other
- Root directory: repo root
- Build command: leave empty
- Output directory: `site`
## Documentation
The root `site/index.html` redirects to `/nostr/`, so the domain can serve the current client without preserving the legacy Tor page.
VoxVera is available in multiple languages. Select your preferred language for the detailed usage guide:
## Verification
| Language | Documentation | Contributing | Agent Guide |
| :--- | :--- | :--- | :--- |
| 🇺🇸 **English** | [usage.md](docs/en/usage.md) | [CONTRIBUTING.md](docs/en/CONTRIBUTING.md) | [AGENTS.md](docs/en/AGENTS.md) |
| 🇪🇸 **Español** | [usage.md](docs/es/usage.md) | [CONTRIBUTING.md](docs/es/CONTRIBUTING.md) | [AGENTS.md](docs/es/AGENTS.md) |
| 🇩🇪 **Deutsch** | [usage.md](docs/de/usage.md) | [CONTRIBUTING.md](docs/de/CONTRIBUTING.md) | [AGENTS.md](docs/de/AGENTS.md) |
| 🇫🇷 **Français** | [usage.md](docs/fr/usage.md) | [CONTRIBUTING.md](docs/fr/CONTRIBUTING.md) | [AGENTS.md](docs/fr/AGENTS.md) |
| 🇷🇺 **Русский** | [usage.md](docs/ru/usage.md) | [CONTRIBUTING.md](docs/ru/CONTRIBUTING.md) | [AGENTS.md](docs/ru/AGENTS.md) |
| 🇮🇱 **עברית** | [usage.md](docs/he/usage.md) | [CONTRIBUTING.md](docs/he/CONTRIBUTING.md) | [AGENTS.md](docs/he/AGENTS.md) |
| 🇸🇦 **العربية** | [usage.md](docs/ar/usage.md) | [CONTRIBUTING.md](docs/ar/CONTRIBUTING.md) | [AGENTS.md](docs/ar/AGENTS.md) |
| 🇯🇵 **日本語** | [usage.md](docs/ja/usage.md) | [CONTRIBUTING.md](docs/ja/CONTRIBUTING.md) | [AGENTS.md](docs/ja/AGENTS.md) |
| 🇮🇳 **हिन्दी** | [usage.md](docs/hi/usage.md) | [CONTRIBUTING.md](docs/hi/CONTRIBUTING.md) | [AGENTS.md](docs/hi/AGENTS.md) |
| 🇰🇪 **Kiswahili** | [usage.md](docs/sw/usage.md) | [CONTRIBUTING.md](docs/sw/CONTRIBUTING.md) | [AGENTS.md](docs/sw/AGENTS.md) |
```bash
node --check site/nostr/nostr-client.js
pytest -q
```
---
## Roadmap (v0.2.0)
We are actively working on:
- **PGP Signing**: Cryptographic proof of tool integrity.
- **Nostr Integration**: Automated social amplification.
- **Template Gallery**: Visual styles for protests, alerts, and art.
- **Self-Healing Network**: Automated decentralized updates.
See [ROADMAP-v0.2.0.md](docs/roadmap-v0.2.0.md) for details.
---
The Python tests only cover the Nostr source schema. The frontend is static and should be checked in-browser for layout and print behavior after UI changes.
## License
RELEASE.md
-104
View File
@@ -1,104 +0,0 @@
# VoxVera Release Process
**⚠️ ATTENTION AI AGENTS (CRITICAL WORKFLOW):**
Do **NOT** automatically package, tag, or push a new release after completing a set of changes. Releases should **ONLY** be triggered when the user explicitly requests one (e.g., "Package a release now" or "Let's release this").
Instead of releasing immediately, you must append a summary of your completed work to the `UPCOMING_RELEASE.md` file. This allows development to span multiple context sessions and ensures that new releases contain a substantial amount of value. When a release is finally requested, use the contents of `UPCOMING_RELEASE.md` to format the GitHub Release notes, and then clear the document for the next cycle.
This document outlines the mandatory steps to perform before every release to ensure code quality, cross-language integrity, and professional distribution assets.
## 1. Pre-Flight Checks (Quality Assurance)
Before any release, the codebase must pass all internal quality checks **without taking any shortcuts**. All tests must be rigorous, use real data where appropriate, and passing them should be a true mark of quality.
### Run Tests
Ensure all core CLI, E2E, and Integrity tests pass:
```bash
pytest tests/
```
*Note: The `test_integrity.py` check is critical as it verifies that all 14+ language locales have synchronized keys and all binary bundles are 100% self-contained.*
### Run Linting
Ensure the code adheres to style guidelines (no trailing whitespace, proper spacing, etc.):
```bash
# Using flake8 (excluding vendored dependencies)
flake8 voxvera/ --exclude=voxvera/vendor/
```
## 2. Update & Generate Localized Assets
Before releasing, you must ensure that **all documentation accurately reflects the new features and functions** introduced in the release.
All documentation and site templates must be synchronized with the translation system. This ensures that any changes to documentation are reflected across all 14+ supported languages.
### Synchronize Documentation
If you have modified any documentation templates in `docs/templates/` (which you should, to cover new features), you **must** use the translation system to regenerate the localized documentation before release:
```bash
# Regenerate docs/ folders for all languages from templates and locales
python3 -m voxvera.cli build-docs
```
### Synchronize Site Assets
The main `site/` directory (including QRs, HTML, and portable Zips) must also be refreshed to include the latest binary names and locale strings:
```bash
# Refresh site/ directory
python3 -m voxvera.cli build-site
```
## 3. Build Distribution Binaries
Linux CLI delivery is the supported deployment target today. Other package formats should be treated as experimental release artifacts until their Tor/OnionShare background-hosting behavior is validated end-to-end.
Capture platform evidence before promoting any support tier: run `bash scripts/platform-smoke.sh linux-cli` locally for the supported Linux path, and keep CI/workflow evidence aligned with the same command.
As other runtime targets mature, use `bash scripts/platform-smoke.sh macos-cli`, `bash scripts/platform-smoke.sh windows-cli`, or `bash scripts/platform-smoke.sh docker-cli` on their native environments before changing their support labels.
### Standard Binary
Generates an architecture-specific binary (e.g., `voxvera-linux-x86_64`) in `voxvera/resources/bin/`.
```bash
./scripts/build_binaries.sh
```
This directory is local build output only. Do not treat old files in `voxvera/resources/bin/` as canonical release history; the GitHub Release artifacts are the publish surface.
### AppImage (Linux)
Wraps the standard binary into a self-contained AppImage.
```bash
./packaging/build_appimage.sh
```
Experimental package surface.
### Flatpak (Linux)
Generates a standalone `.flatpak` bundle. Requires `flatpak-builder`.
```bash
./packaging/build_flatpak.sh
```
Experimental package surface.
### Debian Package (Linux)
Generates a `.deb` package for Debian/Ubuntu systems.
```bash
./packaging/build_deb.sh
```
Experimental package surface unless its runtime dependencies and recovery behavior are explicitly validated for the release.
### DMG (macOS)
Generates a `.dmg` installer for macOS (must be run on macOS).
```bash
./packaging/build_dmg.sh
```
Experimental package surface.
## 4. Release Execution
1. **Version Bump:** Update `__version__` in `voxvera/__init__.py` and `version` in `pyproject.toml`.
2. **Commit & Tag:**
```bash
git add .
git commit -m "chore: release vX.Y.Z"
git tag -a vX.Y.Z -m "VoxVera vX.Y.Z"
git push origin main --tags
```
## 5. Automated Releases (GitHub Actions)
The repository is configured with a **Build Standalone Binaries** workflow that automatically runs when a new tag (`v*`) is pushed. This workflow:
- Builds native executables for **Linux**, **Windows (.exe)**, and **macOS**.
- Automatically attaches these binaries to the corresponding GitHub Release.
This ensures that Windows users receive a professional `voxvera-windows.exe` rather than having to rely on `.bat` or `.sh` scripts.
UPCOMING_RELEASE.md
-1
View File
@@ -1 +0,0 @@
# Upcoming Release Notes
ci/test-e2e.sh
-218
View File
@@ -1,218 +0,0 @@
#!/usr/bin/env bash
set -euo pipefail
# Robustness: ensure we are in the project root
cd "$(dirname "$0")/.."
LOG_DIR="$(pwd)/ci-logs"
mkdir -p "$LOG_DIR"
# Use a subshell for tee to avoid issues with some shell environments
exec > >(tee "$LOG_DIR/run.log") 2>&1
echo "Starting E2E verification at $(date)"
# Install VoxVera
if [ -n "${VOXVERA_BIN:-}" ] && [ -f "$VOXVERA_BIN" ]; then
voxvera_cmd="$VOXVERA_BIN"
echo "Using provided VoxVera binary: $voxvera_cmd" >&2
elif command -v voxvera >/dev/null 2>&1; then
voxvera_cmd="$(command -v voxvera)"
echo "Using existing VoxVera on PATH: $voxvera_cmd" >&2
else
echo "Installing VoxVera in editable mode..."
python3 -m pip install --break-system-packages --no-build-isolation -e ".[e2e]"
voxvera_cmd="$(command -v voxvera || echo "$HOME/.local/bin/voxvera")"
fi
echo "VoxVera command: $voxvera_cmd"
echo "Checking platform contract before workflow..."
bash scripts/platform-smoke.sh linux-cli
# Generate demo flyer
echo "Initializing demo flyer..."
"$voxvera_cmd" --lang en init --template voxvera <<EOI
DemoUser
voxvera
EOI
config_path="$HOME/host/voxvera/config.json"
if [ ! -f "$config_path" ]; then
echo "CRITICAL: Expected config file not found after init: $config_path" >&2
exit 1
fi
echo "Building demo flyer..."
"$voxvera_cmd" --lang en --config "$config_path" build
# Verify build output exists in host/
folder_name="voxvera"
host_dir="$HOME/host/$folder_name"
if [ ! -d "$host_dir" ]; then
echo "CRITICAL: Host directory $host_dir not found!" >&2
ls -R "$HOME/host/" || true
exit 1
fi
ls -R "$host_dir" >>"$LOG_DIR/tree.txt"
# Verify essential files
for f in index.html config.json; do
if [ ! -f "$host_dir/$f" ]; then
echo "CRITICAL: Missing $f in $host_dir" >&2
exit 1
fi
done
echo "Build output verified in $host_dir"
# Run pytest unit tests
echo "Running pytest unit tests..."
python3 -m pytest tests/ -v 2>&1 | tee "$LOG_DIR/pytest.log"
# Optional network tests
if [ "${VOXVERA_E2E_OFFLINE:-}" != "1" ]; then
echo "Starting network-dependent tests..."
# GitHub Actions Ubuntu runners have Tor pre-installed and running as a service.
# We stop it to ensure we can run our own instance with known configuration on default ports.
echo "Stopping system Tor service if running..."
sudo systemctl stop tor || true
# Kill any lingering tor processes
sudo pkill -x tor || true
echo "Starting a fresh Tor instance on default ports (9050/9051)..."
mkdir -p "$LOG_DIR/tor_data"
tor --SocksPort 9050 --ControlPort 9051 --CookieAuthentication 0 --DataDirectory "$LOG_DIR/tor_data" >"$LOG_DIR/tor.log" 2>&1 &
TOR_PID=$!
# Wait for Tor to bootstrap
echo "Waiting for Tor to bootstrap (up to 120s)..."
BOOTSTRAPPED=0
for i in {1..120}; do
if grep -q "Bootstrapped 100%" "$LOG_DIR/tor.log"; then
echo "Tor bootstrapped successfully."
BOOTSTRAPPED=1
break
fi
[ $((i % 10)) -eq 0 ] && echo "... still bootstrapping Tor ($i s) ..."
sleep 1
done
if [ $BOOTSTRAPPED -eq 0 ]; then
echo "CRITICAL: Tor failed to bootstrap after 120s" >&2
tail -n 20 "$LOG_DIR/tor.log"
kill ${TOR_PID:-} || true
exit 1
fi
echo "Checking platform contract with live Tor..."
VOXVERA_REQUIRE_TOR=1 bash scripts/platform-smoke.sh linux-cli
# Start OnionShare
echo "Starting OnionShare..."
# Explicitly set environment variables that OnionShare-cli respects
export TOR_SOCKS_PORT=9050
export TOR_CONTROL_PORT=9051
onionshare-cli --website --public \
--persistent "$host_dir/.onionshare-session" \
-v \
"$host_dir" >"$LOG_DIR/onionshare.log" 2>&1 &
OS_PID=$!
# Check if OnionShare process is still alive after a few seconds
sleep 5
if ! kill -0 $OS_PID 2>/dev/null; then
echo "CRITICAL: OnionShare-cli failed to start" >&2
cat "$LOG_DIR/onionshare.log"
kill ${TOR_PID:-} || true
exit 1
fi
# Wait for URL with timeout and feedback
echo "Waiting for OnionShare to generate URL (up to 120s)..."
URL=""
for i in {1..120}; do
# Use -a to process as text even if there are binary chars (ANSI codes)
if grep -aEo 'http[s]?://[a-z2-7]{56}\.onion' "$LOG_DIR/onionshare.log" | head -n1 >"$LOG_DIR/url.txt"; then
URL=$(cat "$LOG_DIR/url.txt" | tr -d '\r\n ')
if [ -n "$URL" ]; then
echo "Successfully generated Onion URL: $URL"
break
fi
fi
[ $((i % 10)) -eq 0 ] && echo "... still waiting ($i s) ..."
sleep 1
done
if [ -z "$URL" ]; then
echo "CRITICAL: Onion URL not found after 120s" >&2
echo "--- Last 20 lines of OnionShare log ---"
tail -n 20 "$LOG_DIR/onionshare.log"
kill $OS_PID || true
kill ${TOR_PID:-} || true
exit 1
fi
# Robustness: Manually update the config.json with the URL so verification passes
# and the site is actually using the live onion address.
echo "Updating $host_dir/config.json with live URL: $URL"
python3 <<EOF
import json
import os
path = "$host_dir/config.json"
with open(path, 'r') as f:
data = json.load(f)
data['url'] = "$URL"
with open(path + '.new', 'w') as f:
json.dump(data, f, indent=2)
os.replace(path + '.new', path)
EOF
echo "Verifying content of $host_dir/config.json:"
cat "$host_dir/config.json"
# Verify URL in config
if ! grep -Fq "$URL" "$host_dir/config.json"; then
echo "CRITICAL: URL $URL not found in $host_dir/config.json" >&2
cat "$host_dir/config.json"
kill $OS_PID || true
kill ${TOR_PID:-} || true
exit 1
fi
# Re-build to update QR codes with live onion URL
echo "Re-building site with live URL..."
"$voxvera_cmd" --lang en build --config "$host_dir/config.json"
# Fetch page via Tor (retry a few times as circuits can be flaky)
echo "Verifying reachability via Tor (on port 9050)..."
FETCHED=0
for attempt in {1..5}; do
echo "Attempt $attempt..."
if curl --socks5-hostname 127.0.0.1:9050 -fsSL "$URL" | grep -q '<title>'; then
echo "Success: Site is reachable via Tor."
FETCHED=1
break
fi
sleep 10
done
if [ $FETCHED -eq 0 ]; then
echo "WARNING: Site could not be reached via Tor after 5 attempts, but OnionShare is running."
# In CI, we might skip hard failure if Tor network is exceptionally slow/blocked
fi
# Clean up
echo "Cleaning up..."
kill $OS_PID || true
kill ${TOR_PID:-} || true
wait $OS_PID 2>/dev/null || true
else
echo "Skipping network-dependent tests (VOXVERA_E2E_OFFLINE=1)" >&2
fi
echo "E2E verification complete at $(date)"
exit 0
docs/ar/AGENTS.md
-42
View File
@@ -1,42 +0,0 @@
# AI Agent Instructions for VoxVera
This guide is for AI agents (like Gemini, Claude, or GPT) contributing to the VoxVera project. Follow these protocols to maintain the architectural integrity and multi-language support.
## Core Mandates
1. **Security-First**: VoxVera is a Tor-based tool. Never suggest features that leak IP addresses or use non-Tor external resources (CDNs, etc.).
2. **Local-First**: All assets (fonts, dependencies, binaries) must be self-contained within the `voxvera/` package to support the Universal Mirroring model.
3. **Tokenized UI**: Never hardcode user-facing strings. Always add them to `voxvera/locales/en.json` and use the `t('cli.token')` helper.
4. **Markdown Redaction**: Use `~~text~~` in locale JSONs for strike-through effects. Both the build system and the JS engine handle the conversion to `<span class="redacted">` automatically.
5. **Visual Width Testing**: When modifying UI or adding languages, verify that long or complex strings (e.g., Hindi ligatures or CJK characters) do not exceed the visual unit limits defined in the CLI.
## Localization Protocol
When adding a new language or updating an existing one:
- **CLI/Flyers**: Update `voxvera/locales/{lang}.json`. Include `meta`, `cli`, `web`, and `landing` categories.
- **Landing Page**:
- Directly update the `const locales` object in `site/index.html`.
- **Crucial**: Run `voxvera build-site` to generate the latest portable bundle and refresh the pre-rendered HTML.
- **Documentation**:
- Master templates live in `docs/templates/`.
- Localized overrides live in `voxvera/locales/{lang}/docs/`.
- **Crucial**: After any change to locales or templates, you MUST run `voxvera build-docs` to synchronize the output in `docs/{en,es,de}/`.
## Universal Mirroring
VoxVera propagates through its own flyers.
- Every `voxvera build` and `voxvera build-site` generates `voxvera-portable.zip`.
- If you modify the core source code, ensure the `bundle_portable` function in `voxvera/cli.py` still correctly captures all necessary directories (especially `vendor/`, `locales/`, and `resources/`).
## Verification Checklist
Before finishing a task, ensure you have:
1. Run unit tests: `pytest tests/test_cli.py`.
2. Verified the localization: `voxvera --lang {lang} check`.
3. Rebuilt the documentation: `voxvera build-docs`.
4. Synchronized the public site: `voxvera build-site`.
5. Verified the portable bundle exists: `ls -l voxvera/host/*/download/voxvera-portable.zip` and `ls -l site/download/voxvera-portable.zip`.
---
Follow these rules to ensure VoxVera remains a robust, viral, and decentralized tool for truth.
docs/ar/CONTRIBUTING.md
-47
View File
@@ -1,47 +0,0 @@
# Contributing to VoxVera
Thank you for your interest in contributing to VoxVera! This project aims to be a global, censorship-resistant tool, and your help—especially with translations—is vital.
## Adding a New Language
VoxVera uses a centralized token system for the CLI and Web components, and a template-based system for Documentation. To add a new language (e.g., French/`fr`), follow this checklist:
### 1. The Token File
Create a new JSON file in `voxvera/locales/{lang_code}.json`.
- Use `en.json` as your master template.
- **`meta`**: Include the native language name and a flag emoji.
- **`cli`**: Translate all strings used in the terminal interface.
- **`web`**: Translate strings used on the generated landing pages and flyers.
- **`landing`**: Translate the specific content for the official VoxVera website.
- **Formatting**: You can use Markdown-style strike-throughs (`~~redacted text~~`) in any of these strings; they will be automatically converted to the stylized "redacted" effect on the flyers.
### 2. The Landing Page
The main landing page is generated from the shared template and locale files.
- Add your language in `voxvera/locales/{lang_code}.json`.
- Do **not** edit `site/index.html` directly; it is generated output.
- Run `voxvera build-site` to refresh the public assets and inject your new locale into the generated HTML.
### 3. Documentation
VoxVera uses the **Doc-Sync Engine** to keep manuals in sync.
- Create localized Markdown files in `voxvera/locales/{lang_code}/docs/`.
- Use the templates in `docs/templates/` as your guide.
- You can use `cli.token_name` to reference terminal commands automatically.
### 4. Build and Verify
Run the following commands to verify your changes:
- `voxvera --lang {lang_code} check` (Verify CLI translation)
- `voxvera build-docs` (Generate localized manuals)
- `voxvera build-site` (Synchronize the public website and generate the latest portable bundle)
- Open the generated `site/index.html` in a browser and test the language switcher.
## Code Contributions
- **Dependencies**: if you add a new Python library to `requirements.txt`, you MUST run `voxvera vendorize` to include it in the portable distribution.
- **Layout Integrity**: VoxVera uses visual width validation. If you add new UI elements, ensure they respect the physical boundaries of an 8.5"x11" flyer.
- **Tests**: Ensure all tests pass: `pytest tests/`. Run the integrity suite specifically when modifying locales: `pytest tests/test_integrity.py`.
- **Generated artifacts**: Treat `voxvera/resources/bin/` as local build output, not source files. Release binaries belong in GitHub Releases, not hand-edited repo state.
- **Style**: Follow the existing coding style (PEP 8 for Python).
- **Documentation**: If adding a new feature, update the master templates in `docs/templates/` and run `voxvera build-docs`.
---
Together, we can ensure that truth remains accessible to everyone, everywhere.
docs/ar/docker.md
-48
View File
@@ -1,48 +0,0 @@
# Docker Usage
Experimental: the container path is not yet a production-grade hidden-service deployment target. Linux with `systemd --user` remains the supported persistent-host environment.
A prebuilt image containing Tor, OnionShare and the `voxvera` CLI is published to
`ghcr.io/voxvera/voxvera`.
```bash
# pull the image
docker pull ghcr.io/voxvera/voxvera:latest
# run the experimental container with flyers stored in ./flyers
mkdir -p flyers
docker run -d \
--name voxvera \
--restart unless-stopped \
-v "$(pwd)/flyers:/flyers" \
ghcr.io/voxvera/voxvera:latest
```
The container now uses a dedicated entrypoint that:
- stores runtime state under `/flyers`
- seeds `/flyers/config.json` if needed
- starts an in-container Tor daemon on `127.0.0.1:9050/9051`
- bootstraps a default site when `/flyers/host` is empty
- runs `voxvera start-all` on startup and retries it periodically
- exposes a container healthcheck based on `voxvera doctor --json`
Useful commands:
```bash
docker logs -f voxvera
docker exec -it voxvera voxvera doctor --json
docker exec -it voxvera voxvera autostart status --json
```
If you prefer Compose:
```yaml
services:
voxvera:
image: ghcr.io/voxvera/voxvera:latest
restart: unless-stopped
volumes:
- ./flyers:/flyers
```
Use this path for testing only until the container runtime and background recovery behavior are validated end-to-end.
docs/ar/templates.md
-14
View File
@@ -1,14 +0,0 @@
# Flyer Templates
Pre-built flyer templates live in the `templates/` directory. Use the CLI to copy one with:
```bash
voxvera init --template <name>
```
This will create a new folder under `dist/` named `<name>-<YYYYMMDD>` containing the template files.
Available templates:
- **blank** – minimal placeholder files, also used when extracting fields from a PDF.
- **voxvera** – example flyer showcasing the VoxVera project.
docs/ar/troubleshooting.md
-75
View File
@@ -1,75 +0,0 @@
# Troubleshooting
This page collects common issues encountered when hosting or accessing flyers.
## Tor connectivity
- Ensure Tor is allowed through your firewall. On systems using `ufw` you may need to run `sudo ufw allow tor`.
- Some networks block Tor entirely. If you cannot reach onion services, try connecting over a different network or use a Tor bridge.
## Supported deployment target
- The supported persistent-host setup is Linux with `systemd --user`.
- Windows, macOS, Docker, Flatpak, AppImage, Homebrew, and Chocolatey are currently experimental and may not recover hosting automatically after reboot or network interruptions.
## Tor port detection
`voxvera serve` auto-detects Tor by probing common ports (9050/9150 for SOCKS, 9051/9151 for control). If detection fails -- for example when Tor runs on non-standard ports -- you can override with environment variables:
```bash
TOR_SOCKS_PORT=19050 TOR_CONTROL_PORT=19051 voxvera serve
```
If no running Tor is found, the defaults (9050/9051) are used and OnionShare will attempt to connect on those ports.
## Firewall rules
- If `voxvera serve` fails to start OnionShare, verify that outbound connections on ports 9001 and 80 are permitted.
- Corporate or university firewalls can block the hidden service ports required by Tor.
## SELinux
- On SELinux-enabled distributions you may see `permission denied` errors when OnionShare writes to the `host` directory.
- Run `sudo chcon -Rt svirt_sandbox_file_t host` or disable SELinux enforcement for the folder.
## OnionShare crashes
If `voxvera serve` prints "OnionShare exited unexpectedly", check the log file
`host/<folder_name>/onionshare.log` for details. Common causes:
- Tor is not running (`sudo systemctl start tor`)
- A port conflict with another service
- Missing `onionshare-cli` (run `voxvera check`)
## Onion URL changed unexpectedly
The onion URL is tied to the Ed25519 keypair stored in
`host/<folder_name>/.onionshare-session`. If this file is deleted, a new
keypair (and URL) will be generated on the next `voxvera serve`. The
`voxvera import` command preserves this file automatically, but manual
deletion of the `host/` directory will destroy it.
## Hosting does not return after reboot or network loss
On Linux, install or verify the recovery timer:
```bash
voxvera autostart
systemctl --user status voxvera-start.timer
systemctl --user status voxvera-start.service
```
The supported recovery path is the recurring `systemd --user` timer, which reruns `voxvera start-all` every few minutes.
## QR codes not generated
If `voxvera build` reports "No URLs configured yet", this is expected before the first `voxvera serve`. QR codes for tear-off links are generated automatically once the .onion address is known. QR codes for the content link are generated if you provided a URL during `voxvera init`.
## Electron GUI
If `npm start` fails with `spawn voxvera ENOENT`, the `voxvera` command is not in your `PATH`. Install it with `pipx install git+https://github.com/PR0M3TH3AN/VoxVera.git` or run `./install.sh` from the repository.
## Missing dependencies
Run `voxvera check` to verify your setup. The command checks for required
Python packages (`qrcode`, `Pillow`, `jsmin`, `htmlmin`, `pypdf`) and
external tools (`onionshare-cli`), then prints a summary of anything
missing. To install everything:
```bash
# Recommended: use the install script (handles Tor + OnionShare too)
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
# Or reinstall just the Python package
pipx install --force 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
```
docs/ar/usage.md
-130
View File
@@ -1,130 +0,0 @@
# الاستخدام التفصيلي
يغطي هذا الدليل سير عمل واجهة سطر الأوامر (CLI) الشائعة. راجع `docs/docker.md` للحصول على تعليمات Docker و `docs/templates.md` لقوالب المنشورات المتاحة.
## المتطلبات الأساسية
تم تصميم VoxVera ليكون سهل النقل للغاية ويتطلب الحد الأدنى من تبعيات النظام.
### 1. الملفات الثنائية المستقلة (موصى به)
يمكنك تنزيل ملفات ثنائية مستقلة بدون تبعيات لنظام التشغيل الخاص بك:
- **Linux:** `voxvera-linux`
- **Windows:** `voxvera-windows.exe`
- **macOS:** `voxvera-macos`
تتضمن هذه الملفات الثنائية كل ما يلزم لتشغيل VoxVera (باستثناء `onionshare-cli`).
### 2. المثبت بنقرة واحدة
بدلاً من ذلك، قم بالتثبيت عبر البرمجية النصية المؤتمتة الخاصة بنا:
```bash
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
```
### 3. تثبيت Python اليدوي
إذا كنت تفضل التشغيل من المصدر:
```bash
pipx install 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
sudo apt install tor onionshare-cli # Debian/Ubuntu
```
## خطوة بخطوة
1. **التهيئة:** قم بتشغيل `voxvera init` واتبع المطالبات. سيُطلب منك اختيار لغتك أولاً.
2. **البناء:** قم بإنشاء أصول المنشور. ينشئ كل بناء تلقائياً ملف `voxvera-portable.zip` في مجلد المنشور، مما يسمح للآخرين بتنزيل الأداة الكاملة مباشرة من منشورك.
```bash
voxvera build
```
3. **الخدمة:** انشر المنشور عبر Tor:
```bash
voxvera serve
```
يكتشف هذا تلقائياً نسخة Tor الخاصة بك، ويبدأ OnionShare، ويكتب عنوان .onion الناتج في روابط المنشور القابلة للنزع.
## دعم اللغة
VoxVera مترجم بالكامل. يمكنك تغيير تفضيل اللغة الخاص بك بشكل دائم باستخدام المبدل التفاعلي أو اختصار مباشر:
- **المبدل التفاعلي:** `voxvera lang`
- **اختصار مباشر:** `voxvera --lang ar` (يضبط التفضيل على العربية)
### اللغات المدعومة:
- **الإنجليزية:** `en`
- **الإسبانية:** `es` (اسم مستعار: `--idioma`)
- **الألمانية:** `de` (اسم مستعار: `--sprache`)
- **العربية:** `ar`
يمكنك أيضاً فرض لغة معينة لأمر واحد دون تغيير تفضيلك الدائم:
- **الإنجليزية:** `voxvera --lang en check`
- **العربية:** `voxvera --lang ar check`
تكتشف المنشورات الناتجة تلقائياً لغة متصفح الزائر وتبدل نص واجهة المستخدم وفقاً لذلك.
## إدارة الخوادم
إدارة منشورات متعددة وهويات Tor الخاصة بها من قائمة تفاعلية واحدة:
```bash
voxvera manage
```
الميزات:
- **--- إنشاء موقع/منشور جديد ---**: ابدأ تسلسل الإعداد الكامل.
- **--- تشغيل جميع المواقع ---**: تشغيل أو إيقاف جميع المنشورات في أسطولك دفعة واحدة.
- **الحالة في الوقت الفعلي**: عرض روابط .onion النشطة ومؤشرات تقدم تمهيد Tor.
- **التحكم الفردي**: تصدير إلى Zip مواقع معينة إلى ZIP أو حذفها.
## مراجة شاملة (التوزيع الفيروسي)
لضمان بقاء VoxVera متاحاً حتى لو تم فرض رقابة على المستودعات المركزية، يعمل كل منشور كمرآة للأداة.
عندما تستضيف منشوراً، يوفر زر **"تحميل الأداة والكود"** في الصفحة المقصودة ملف `voxvera-portable.zip` يحتوي على:
- كود المصدر الكامل وجميع اللغات المدعومة.
- جميع تبعيات Python (مضمنة مسبقاً).
- ملفات Tor الثنائية لجميع الأنظمة.
يتيح ذلك لأي شخص يقوم بمسح منشورك أن يصبح موزعاً جديداً لأداة VoxVera.
## التصدير والنسخ الاحتياطي
قم بنسخ هويات Tor الفريدة الخاصة بك احتياطياً (حتى لا يتغير رابط .onion الخاص بك أبداً) أو انقل منشوراتك إلى جهاز آخر.
- **تصدير موقع واحد**: `voxvera export <folder_name>`
- **تصدير جميع المواقع**: `voxvera export-all`
**مكان التخزين:** يتم حفظ جميع الصادرات كملفات ZIP في مجلد يسمى `voxvera-exports` في دليل الصفحة الرئيسية للمستخدم (`~/voxvera-exports/`) على جميع الأنظمة.
## الاستيراد والاستعادة
استعد إعدادك بالكامل على جهاز جديد بنقل ملفات ZIP الخاصة بك إلى `~/voxvera-exports/` وتشغيل:
```bash
voxvera import-multiple
```
## النقل والتشغيل بدون إنترنت
إذا كنت بحاجة إلى تشغيل VoxVera على جهاز لا يتوفر فيه اتصال بالإنترنت، يمكنك "تضمين" التبعيات أولاً:
```bash
voxvera vendorize
```
يقوم هذا بتنزيل جميع مكتبات Python المطلوبة في `voxvera/vendor/`. ستعطي الأداة بعد ذلك الأولوية لهذه الملفات المحلية، مما يسمح لها بالعمل بدون `pip install`.
## استيراد جماعي (JSON)
لإنشاء منشورات بشكل جماعي من ملفات تكوين JSON متعددة، ضعها في مجلد `imports/` وشغل:
```bash
voxvera batch-import
```
## كيف تعمل الروابط
يحتوي كل منشور على رابطين منفصلين:
- **رابط قابل للنزع** (يتم إنشاؤه تلقائياً): عنوان .onion حيث يتم استضافة المنشور.
- **رابط المحتوى** (يتم تكوينه بواسطة المستخدم): URL خارجي يشير إلى موقع ويب أو فيديو أو تنزيل.
لا تحتاج إلى إدخال عنوان .onion يدوياً؛ يتولى VoxVera ذلك تلقائياً خلال مرحلة `serve`.
docs/de/AGENTS.md
-42
View File
@@ -1,42 +0,0 @@
# AI Agent Instructions for VoxVera
This guide is for AI agents (like Gemini, Claude, or GPT) contributing to the VoxVera project. Follow these protocols to maintain the architectural integrity and multi-language support.
## Core Mandates
1. **Security-First**: VoxVera is a Tor-based tool. Never suggest features that leak IP addresses or use non-Tor external resources (CDNs, etc.).
2. **Local-First**: All assets (fonts, dependencies, binaries) must be self-contained within the `voxvera/` package to support the Universal Mirroring model.
3. **Tokenized UI**: Never hardcode user-facing strings. Always add them to `voxvera/locales/en.json` and use the `t('cli.token')` helper.
4. **Markdown Redaction**: Use `~~text~~` in locale JSONs for strike-through effects. Both the build system and the JS engine handle the conversion to `<span class="redacted">` automatically.
5. **Visual Width Testing**: When modifying UI or adding languages, verify that long or complex strings (e.g., Hindi ligatures or CJK characters) do not exceed the visual unit limits defined in the CLI.
## Localization Protocol
When adding a new language or updating an existing one:
- **CLI/Flyers**: Update `voxvera/locales/{lang}.json`. Include `meta`, `cli`, `web`, and `landing` categories.
- **Landing Page**:
- Directly update the `const locales` object in `site/index.html`.
- **Crucial**: Run `voxvera build-site` to generate the latest portable bundle and refresh the pre-rendered HTML.
- **Documentation**:
- Master templates live in `docs/templates/`.
- Localized overrides live in `voxvera/locales/{lang}/docs/`.
- **Crucial**: After any change to locales or templates, you MUST run `voxvera build-docs` to synchronize the output in `docs/{en,es,de}/`.
## Universal Mirroring
VoxVera propagates through its own flyers.
- Every `voxvera build` and `voxvera build-site` generates `voxvera-portable.zip`.
- If you modify the core source code, ensure the `bundle_portable` function in `voxvera/cli.py` still correctly captures all necessary directories (especially `vendor/`, `locales/`, and `resources/`).
## Verification Checklist
Before finishing a task, ensure you have:
1. Run unit tests: `pytest tests/test_cli.py`.
2. Verified the localization: `voxvera --lang {lang} check`.
3. Rebuilt the documentation: `voxvera build-docs`.
4. Synchronized the public site: `voxvera build-site`.
5. Verified the portable bundle exists: `ls -l voxvera/host/*/download/voxvera-portable.zip` and `ls -l site/download/voxvera-portable.zip`.
---
Follow these rules to ensure VoxVera remains a robust, viral, and decentralized tool for truth.
docs/de/CONTRIBUTING.md
-47
View File
@@ -1,47 +0,0 @@
# Contributing to VoxVera
Thank you for your interest in contributing to VoxVera! This project aims to be a global, censorship-resistant tool, and your help—especially with translations—is vital.
## Adding a New Language
VoxVera uses a centralized token system for the CLI and Web components, and a template-based system for Documentation. To add a new language (e.g., French/`fr`), follow this checklist:
### 1. The Token File
Create a new JSON file in `voxvera/locales/{lang_code}.json`.
- Use `en.json` as your master template.
- **`meta`**: Include the native language name and a flag emoji.
- **`cli`**: Translate all strings used in the terminal interface.
- **`web`**: Translate strings used on the generated landing pages and flyers.
- **`landing`**: Translate the specific content for the official VoxVera website.
- **Formatting**: You can use Markdown-style strike-throughs (`~~redacted text~~`) in any of these strings; they will be automatically converted to the stylized "redacted" effect on the flyers.
### 2. The Landing Page
The main landing page is generated from the shared template and locale files.
- Add your language in `voxvera/locales/{lang_code}.json`.
- Do **not** edit `site/index.html` directly; it is generated output.
- Run `voxvera build-site` to refresh the public assets and inject your new locale into the generated HTML.
### 3. Documentation
VoxVera uses the **Doc-Sync Engine** to keep manuals in sync.
- Create localized Markdown files in `voxvera/locales/{lang_code}/docs/`.
- Use the templates in `docs/templates/` as your guide.
- You can use `cli.token_name` to reference terminal commands automatically.
### 4. Build and Verify
Run the following commands to verify your changes:
- `voxvera --lang {lang_code} check` (Verify CLI translation)
- `voxvera build-docs` (Generate localized manuals)
- `voxvera build-site` (Synchronize the public website and generate the latest portable bundle)
- Open the generated `site/index.html` in a browser and test the language switcher.
## Code Contributions
- **Dependencies**: if you add a new Python library to `requirements.txt`, you MUST run `voxvera vendorize` to include it in the portable distribution.
- **Layout Integrity**: VoxVera uses visual width validation. If you add new UI elements, ensure they respect the physical boundaries of an 8.5"x11" flyer.
- **Tests**: Ensure all tests pass: `pytest tests/`. Run the integrity suite specifically when modifying locales: `pytest tests/test_integrity.py`.
- **Generated artifacts**: Treat `voxvera/resources/bin/` as local build output, not source files. Release binaries belong in GitHub Releases, not hand-edited repo state.
- **Style**: Follow the existing coding style (PEP 8 for Python).
- **Documentation**: If adding a new feature, update the master templates in `docs/templates/` and run `voxvera build-docs`.
---
Together, we can ensure that truth remains accessible to everyone, everywhere.
docs/de/docker.md
-48
View File
@@ -1,48 +0,0 @@
# Docker Usage
Experimental: the container path is not yet a production-grade hidden-service deployment target. Linux with `systemd --user` remains the supported persistent-host environment.
A prebuilt image containing Tor, OnionShare and the `voxvera` CLI is published to
`ghcr.io/voxvera/voxvera`.
```bash
# pull the image
docker pull ghcr.io/voxvera/voxvera:latest
# run the experimental container with flyers stored in ./flyers
mkdir -p flyers
docker run -d \
--name voxvera \
--restart unless-stopped \
-v "$(pwd)/flyers:/flyers" \
ghcr.io/voxvera/voxvera:latest
```
The container now uses a dedicated entrypoint that:
- stores runtime state under `/flyers`
- seeds `/flyers/config.json` if needed
- starts an in-container Tor daemon on `127.0.0.1:9050/9051`
- bootstraps a default site when `/flyers/host` is empty
- runs `voxvera start-all` on startup and retries it periodically
- exposes a container healthcheck based on `voxvera doctor --json`
Useful commands:
```bash
docker logs -f voxvera
docker exec -it voxvera voxvera doctor --json
docker exec -it voxvera voxvera autostart status --json
```
If you prefer Compose:
```yaml
services:
voxvera:
image: ghcr.io/voxvera/voxvera:latest
restart: unless-stopped
volumes:
- ./flyers:/flyers
```
Use this path for testing only until the container runtime and background recovery behavior are validated end-to-end.
docs/de/templates.md
-14
View File
@@ -1,14 +0,0 @@
# Flyer Templates
Pre-built flyer templates live in the `templates/` directory. Use the CLI to copy one with:
```bash
voxvera init --template <name>
```
This will create a new folder under `dist/` named `<name>-<YYYYMMDD>` containing the template files.
Available templates:
- **blank** – minimal placeholder files, also used when extracting fields from a PDF.
- **voxvera** – example flyer showcasing the VoxVera project.
docs/de/troubleshooting.md
-75
View File
@@ -1,75 +0,0 @@
# Troubleshooting
This page collects common issues encountered when hosting or accessing flyers.
## Tor connectivity
- Ensure Tor is allowed through your firewall. On systems using `ufw` you may need to run `sudo ufw allow tor`.
- Some networks block Tor entirely. If you cannot reach onion services, try connecting over a different network or use a Tor bridge.
## Supported deployment target
- The supported persistent-host setup is Linux with `systemd --user`.
- Windows, macOS, Docker, Flatpak, AppImage, Homebrew, and Chocolatey are currently experimental and may not recover hosting automatically after reboot or network interruptions.
## Tor port detection
`voxvera serve` auto-detects Tor by probing common ports (9050/9150 for SOCKS, 9051/9151 for control). If detection fails -- for example when Tor runs on non-standard ports -- you can override with environment variables:
```bash
TOR_SOCKS_PORT=19050 TOR_CONTROL_PORT=19051 voxvera serve
```
If no running Tor is found, the defaults (9050/9051) are used and OnionShare will attempt to connect on those ports.
## Firewall rules
- If `voxvera serve` fails to start OnionShare, verify that outbound connections on ports 9001 and 80 are permitted.
- Corporate or university firewalls can block the hidden service ports required by Tor.
## SELinux
- On SELinux-enabled distributions you may see `permission denied` errors when OnionShare writes to the `host` directory.
- Run `sudo chcon -Rt svirt_sandbox_file_t host` or disable SELinux enforcement for the folder.
## OnionShare crashes
If `voxvera serve` prints "OnionShare exited unexpectedly", check the log file
`host/<folder_name>/onionshare.log` for details. Common causes:
- Tor is not running (`sudo systemctl start tor`)
- A port conflict with another service
- Missing `onionshare-cli` (run `voxvera check`)
## Onion URL changed unexpectedly
The onion URL is tied to the Ed25519 keypair stored in
`host/<folder_name>/.onionshare-session`. If this file is deleted, a new
keypair (and URL) will be generated on the next `voxvera serve`. The
`voxvera import` command preserves this file automatically, but manual
deletion of the `host/` directory will destroy it.
## Hosting does not return after reboot or network loss
On Linux, install or verify the recovery timer:
```bash
voxvera autostart
systemctl --user status voxvera-start.timer
systemctl --user status voxvera-start.service
```
The supported recovery path is the recurring `systemd --user` timer, which reruns `voxvera start-all` every few minutes.
## QR codes not generated
If `voxvera build` reports "No URLs configured yet", this is expected before the first `voxvera serve`. QR codes for tear-off links are generated automatically once the .onion address is known. QR codes for the content link are generated if you provided a URL during `voxvera init`.
## Electron GUI
If `npm start` fails with `spawn voxvera ENOENT`, the `voxvera` command is not in your `PATH`. Install it with `pipx install git+https://github.com/PR0M3TH3AN/VoxVera.git` or run `./install.sh` from the repository.
## Missing dependencies
Run `voxvera check` to verify your setup. The command checks for required
Python packages (`qrcode`, `Pillow`, `jsmin`, `htmlmin`, `pypdf`) and
external tools (`onionshare-cli`), then prints a summary of anything
missing. To install everything:
```bash
# Recommended: use the install script (handles Tor + OnionShare too)
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
# Or reinstall just the Python package
pipx install --force 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
```
docs/de/usage.md
-136
View File
@@ -1,136 +0,0 @@
# Detaillierte Verwendung
Diese Anleitung deckt gängige CLI-Workflows ab. Informationen zu Docker finden Sie unter `docs/docker.md` und verfügbare Flyer-Vorlagen unter `docs/templates.md`.
## Voraussetzungen
VoxVera ist auf hohe Portabilität ausgelegt und erfordert minimale Systemabhängigkeiten.
### 1. Eigenständige Binärdateien (Empfohlen)
Sie können eigenständige Binärdateien ohne Abhängigkeiten für Ihr Betriebssystem herunterladen:
- **Linux:** `voxvera-linux`
- **Windows:** `voxvera-windows.exe`
- **macOS:** `voxvera-macos`
Diese Binärdateien enthalten alles, was zum Ausführen von VoxVera erforderlich ist (außer `onionshare-cli`).
### 2. Ein-Zeilen-Installer
Alternativ können Sie die Installation über unser automatisiertes Skript vornehmen:
```bash
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
```
### 3. Manuelle Python-Installation
Wenn Sie lieber aus dem Quellcode ausführen möchten:
```bash
pipx install 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
sudo apt install tor onionshare-cli # Debian/Ubuntu
```
## Schritt für Schritt
1. **Initialisieren:** Führen Sie `voxvera init` aus und folgen Sie den Anweisungen. Sie werden zuerst aufgefordert, Ihre Sprache auszuwählen.
2. **Bauen:** Erstellen Sie die Flyer-Assets. Jeder Build erstellt automatisch eine `voxvera-portable.zip` im Flyer-Ordner, sodass andere das komplette Tool direkt von Ihrem Flyer herunterladen können.
```bash
voxvera build
```
3. **Bereitstellen:** Veröffentlichen Sie den Flyer über Tor:
```bash
voxvera serve
```
Dies erkennt automatisch Ihre Tor-Instanz, startet OnionShare und schreibt die generierte .onion-Adresse in die Abreiß-Links des Flyers.
## Sprachunterstützung
VoxVera ist vollständig lokalisiert. Sie können Ihre Sprachpräferenz dauerhaft über den interaktiven Selektor oder eine direkte Verknüpfung ändern:
- **Interaktiver Selektor:** `voxvera lang`
- **Direkte Verknüpfung:** `voxvera --lang de` (setzt die Präferenz auf Deutsch)
### Unterstützte Sprachen:
- **Englisch:** `en`
- **Spanisch:** `es` (Alias: `--idioma`)
- **Deutsch:** `de` (Alias: `--sprache`)
- **Russisch:** `ru`
- **Hebräisch:** `he`
- **Arabisch:** `ar`
- **Französisch:** `fr`
- **Japanisch:** `ja`
- **Hindi:** `hi`
- **Suaheli:** `sw`
Sie können auch eine bestimmte Sprache für einen einzelnen Befehl erzwingen, ohne Ihre dauerhafte Präferenz zu ändern:
- **Englisch:** `voxvera --lang en check`
- **Deutsch:** `voxvera --sprache de check`
Die generierten Flyer erkennen automatisch die Browsersprache des Besuchers und schalten den UI-Text entsprechend um.
## Server-Verwaltung
Verwalten Sie mehrere Flyer und deren Tor-Identitäten über ein einziges interaktives Menü:
```bash
voxvera manage
```
Funktionen:
- **--- Neue Website/Flyer erstellen ---**: Starten Sie die vollständige Setup-Sequenz.
- **--- Alle Websites starten ---**: Starten oder stoppen Sie alle Flyer in Ihrer Flotte auf einmal.
- **Echtzeit-Status**: Zeigen Sie aktive .onion-URLs und Tor-Bootstrapping-Fortschrittsanzeigen an.
- **Individuelle Steuerung**: Als Zip exportieren Sie bestimmte Seiten in eine ZIP-Datei oder löschen Sie sie.
## Universelle Spiegelung (Virale Verteilung)
Um sicherzustellen, dass VoxVera auch dann zugänglich bleibt, wenn zentrale Repositories zensiert werden, fungiert jeder Flyer als Spiegel für das Tool.
Wenn Sie einen Flyer hosten, bietet die Schaltfläche **"Tool & Quellcode herunterladen"** auf der Landingpage eine `voxvera-portable.zip` an, die Folgendes enthält:
- Den vollständigen Quellcode und alle unterstützten Sprachen.
- Alle Python-Abhängigkeiten (vorinstalliert).
- Plattformübergreifende Tor-Binärdateien.
Dies ermöglicht es jedem, der Ihren Flyer scannt, ein neuer Distributor des VoxVera-Tools zu werden.
## Export & Sicherung
Sichern Sie Ihre eindeutigen Tor-Identitäten (damit sich Ihre .onion-URL nie ändert) oder verschieben Sie Ihre Flyer auf einen anderen Computer.
- **Einzelne Seite exportieren:** `voxvera export <folder_name>`
- **Alle Seiten exportieren:** `voxvera export-all`
**Speicherort:** Alle Exporte werden als ZIP-Dateien in einem Ordner namens `voxvera-exports` im Home-Verzeichnis des Benutzers (`~/voxvera-exports/`) auf allen Plattformen gespeichert.
## Import & Wiederherstellung
Stellen Sie Ihr gesamtes Setup auf einem neuen Computer wieder her, indem Sie Ihre ZIP-Dateien nach `~/voxvera-exports/` verschieben und Folgendes ausführen:
```bash
voxvera import-multiple
```
## Portabilität & Offline-Nutzung
Wenn Sie VoxVera auf einem Computer ohne Internetzugang ausführen müssen, können Sie die Abhängigkeiten zuerst lokal bereitstellen:
```bash
voxvera vendorize
```
Dies lädt alle erforderlichen Python-Bibliotheken in `voxvera/vendor/` herunter. Das Tool priorisiert dann diese lokalen Dateien, sodass es ohne `pip install` ausgeführt werden kann.
## Batch-Import (JSON)
Um Flyer in großen Mengen aus mehreren JSON-Konfigurationsdateien zu generieren, legen Sie diese im Verzeichnis `imports/` ab und führen Sie Folgendes aus:
```bash
voxvera batch-import
```
## Wie URLs funktionieren
Jeder Flyer hat zwei separate URLs:
- **Abreiß-Link** (automatisch generiert): Die .onion-Adresse, unter der der Flyer gehostet wird.
- **Inhalts-Link** (vom Benutzer konfiguriert): Eine externe URL, die auf eine Website, ein Video oder einen Download verweist.
Sie müssen die .onion-Adresse nicht manuell eingeben; VoxVera erledigt dies automatisch während der `serve`-Phase.
docs/en/AGENTS.md
-42
View File
@@ -1,42 +0,0 @@
# AI Agent Instructions for VoxVera
This guide is for AI agents (like Gemini, Claude, or GPT) contributing to the VoxVera project. Follow these protocols to maintain the architectural integrity and multi-language support.
## Core Mandates
1. **Security-First**: VoxVera is a Tor-based tool. Never suggest features that leak IP addresses or use non-Tor external resources (CDNs, etc.).
2. **Local-First**: All assets (fonts, dependencies, binaries) must be self-contained within the `voxvera/` package to support the Universal Mirroring model.
3. **Tokenized UI**: Never hardcode user-facing strings. Always add them to `voxvera/locales/en.json` and use the `t('cli.token')` helper.
4. **Markdown Redaction**: Use `~~text~~` in locale JSONs for strike-through effects. Both the build system and the JS engine handle the conversion to `<span class="redacted">` automatically.
5. **Visual Width Testing**: When modifying UI or adding languages, verify that long or complex strings (e.g., Hindi ligatures or CJK characters) do not exceed the visual unit limits defined in the CLI.
## Localization Protocol
When adding a new language or updating an existing one:
- **CLI/Flyers**: Update `voxvera/locales/{lang}.json`. Include `meta`, `cli`, `web`, and `landing` categories.
- **Landing Page**:
- Directly update the `const locales` object in `site/index.html`.
- **Crucial**: Run `voxvera build-site` to generate the latest portable bundle and refresh the pre-rendered HTML.
- **Documentation**:
- Master templates live in `docs/templates/`.
- Localized overrides live in `voxvera/locales/{lang}/docs/`.
- **Crucial**: After any change to locales or templates, you MUST run `voxvera build-docs` to synchronize the output in `docs/{en,es,de}/`.
## Universal Mirroring
VoxVera propagates through its own flyers.
- Every `voxvera build` and `voxvera build-site` generates `voxvera-portable.zip`.
- If you modify the core source code, ensure the `bundle_portable` function in `voxvera/cli.py` still correctly captures all necessary directories (especially `vendor/`, `locales/`, and `resources/`).
## Verification Checklist
Before finishing a task, ensure you have:
1. Run unit tests: `pytest tests/test_cli.py`.
2. Verified the localization: `voxvera --lang {lang} check`.
3. Rebuilt the documentation: `voxvera build-docs`.
4. Synchronized the public site: `voxvera build-site`.
5. Verified the portable bundle exists: `ls -l voxvera/host/*/download/voxvera-portable.zip` and `ls -l site/download/voxvera-portable.zip`.
---
Follow these rules to ensure VoxVera remains a robust, viral, and decentralized tool for truth.
docs/en/CONTRIBUTING.md
-47
View File
@@ -1,47 +0,0 @@
# Contributing to VoxVera
Thank you for your interest in contributing to VoxVera! This project aims to be a global, censorship-resistant tool, and your help—especially with translations—is vital.
## Adding a New Language
VoxVera uses a centralized token system for the CLI and Web components, and a template-based system for Documentation. To add a new language (e.g., French/`fr`), follow this checklist:
### 1. The Token File
Create a new JSON file in `voxvera/locales/{lang_code}.json`.
- Use `en.json` as your master template.
- **`meta`**: Include the native language name and a flag emoji.
- **`cli`**: Translate all strings used in the terminal interface.
- **`web`**: Translate strings used on the generated landing pages and flyers.
- **`landing`**: Translate the specific content for the official VoxVera website.
- **Formatting**: You can use Markdown-style strike-throughs (`~~redacted text~~`) in any of these strings; they will be automatically converted to the stylized "redacted" effect on the flyers.
### 2. The Landing Page
The main landing page is generated from the shared template and locale files.
- Add your language in `voxvera/locales/{lang_code}.json`.
- Do **not** edit `site/index.html` directly; it is generated output.
- Run `voxvera build-site` to refresh the public assets and inject your new locale into the generated HTML.
### 3. Documentation
VoxVera uses the **Doc-Sync Engine** to keep manuals in sync.
- Create localized Markdown files in `voxvera/locales/{lang_code}/docs/`.
- Use the templates in `docs/templates/` as your guide.
- You can use `cli.token_name` to reference terminal commands automatically.
### 4. Build and Verify
Run the following commands to verify your changes:
- `voxvera --lang {lang_code} check` (Verify CLI translation)
- `voxvera build-docs` (Generate localized manuals)
- `voxvera build-site` (Synchronize the public website and generate the latest portable bundle)
- Open the generated `site/index.html` in a browser and test the language switcher.
## Code Contributions
- **Dependencies**: if you add a new Python library to `requirements.txt`, you MUST run `voxvera vendorize` to include it in the portable distribution.
- **Layout Integrity**: VoxVera uses visual width validation. If you add new UI elements, ensure they respect the physical boundaries of an 8.5"x11" flyer.
- **Tests**: Ensure all tests pass: `pytest tests/`. Run the integrity suite specifically when modifying locales: `pytest tests/test_integrity.py`.
- **Generated artifacts**: Treat `voxvera/resources/bin/` as local build output, not source files. Release binaries belong in GitHub Releases, not hand-edited repo state.
- **Style**: Follow the existing coding style (PEP 8 for Python).
- **Documentation**: If adding a new feature, update the master templates in `docs/templates/` and run `voxvera build-docs`.
---
Together, we can ensure that truth remains accessible to everyone, everywhere.
docs/en/docker.md
-48
View File
@@ -1,48 +0,0 @@
# Docker Usage
Experimental: the container path is not yet a production-grade hidden-service deployment target. Linux with `systemd --user` remains the supported persistent-host environment.
A prebuilt image containing Tor, OnionShare and the `voxvera` CLI is published to
`ghcr.io/voxvera/voxvera`.
```bash
# pull the image
docker pull ghcr.io/voxvera/voxvera:latest
# run the experimental container with flyers stored in ./flyers
mkdir -p flyers
docker run -d \
--name voxvera \
--restart unless-stopped \
-v "$(pwd)/flyers:/flyers" \
ghcr.io/voxvera/voxvera:latest
```
The container now uses a dedicated entrypoint that:
- stores runtime state under `/flyers`
- seeds `/flyers/config.json` if needed
- starts an in-container Tor daemon on `127.0.0.1:9050/9051`
- bootstraps a default site when `/flyers/host` is empty
- runs `voxvera start-all` on startup and retries it periodically
- exposes a container healthcheck based on `voxvera doctor --json`
Useful commands:
```bash
docker logs -f voxvera
docker exec -it voxvera voxvera doctor --json
docker exec -it voxvera voxvera autostart status --json
```
If you prefer Compose:
```yaml
services:
voxvera:
image: ghcr.io/voxvera/voxvera:latest
restart: unless-stopped
volumes:
- ./flyers:/flyers
```
Use this path for testing only until the container runtime and background recovery behavior are validated end-to-end.
docs/en/templates.md
-14
View File
@@ -1,14 +0,0 @@
# Flyer Templates
Pre-built flyer templates live in the `templates/` directory. Use the CLI to copy one with:
```bash
voxvera init --template <name>
```
This will create a new folder under `dist/` named `<name>-<YYYYMMDD>` containing the template files.
Available templates:
- **blank** – minimal placeholder files, also used when extracting fields from a PDF.
- **voxvera** – example flyer showcasing the VoxVera project.
docs/en/troubleshooting.md
-75
View File
@@ -1,75 +0,0 @@
# Troubleshooting
This page collects common issues encountered when hosting or accessing flyers.
## Tor connectivity
- Ensure Tor is allowed through your firewall. On systems using `ufw` you may need to run `sudo ufw allow tor`.
- Some networks block Tor entirely. If you cannot reach onion services, try connecting over a different network or use a Tor bridge.
## Supported deployment target
- The supported persistent-host setup is Linux with `systemd --user`.
- Windows, macOS, Docker, Flatpak, AppImage, Homebrew, and Chocolatey are currently experimental and may not recover hosting automatically after reboot or network interruptions.
## Tor port detection
`voxvera serve` auto-detects Tor by probing common ports (9050/9150 for SOCKS, 9051/9151 for control). If detection fails -- for example when Tor runs on non-standard ports -- you can override with environment variables:
```bash
TOR_SOCKS_PORT=19050 TOR_CONTROL_PORT=19051 voxvera serve
```
If no running Tor is found, the defaults (9050/9051) are used and OnionShare will attempt to connect on those ports.
## Firewall rules
- If `voxvera serve` fails to start OnionShare, verify that outbound connections on ports 9001 and 80 are permitted.
- Corporate or university firewalls can block the hidden service ports required by Tor.
## SELinux
- On SELinux-enabled distributions you may see `permission denied` errors when OnionShare writes to the `host` directory.
- Run `sudo chcon -Rt svirt_sandbox_file_t host` or disable SELinux enforcement for the folder.
## OnionShare crashes
If `voxvera serve` prints "OnionShare exited unexpectedly", check the log file
`host/<folder_name>/onionshare.log` for details. Common causes:
- Tor is not running (`sudo systemctl start tor`)
- A port conflict with another service
- Missing `onionshare-cli` (run `voxvera check`)
## Onion URL changed unexpectedly
The onion URL is tied to the Ed25519 keypair stored in
`host/<folder_name>/.onionshare-session`. If this file is deleted, a new
keypair (and URL) will be generated on the next `voxvera serve`. The
`voxvera import` command preserves this file automatically, but manual
deletion of the `host/` directory will destroy it.
## Hosting does not return after reboot or network loss
On Linux, install or verify the recovery timer:
```bash
voxvera autostart
systemctl --user status voxvera-start.timer
systemctl --user status voxvera-start.service
```
The supported recovery path is the recurring `systemd --user` timer, which reruns `voxvera start-all` every few minutes.
## QR codes not generated
If `voxvera build` reports "No URLs configured yet", this is expected before the first `voxvera serve`. QR codes for tear-off links are generated automatically once the .onion address is known. QR codes for the content link are generated if you provided a URL during `voxvera init`.
## Electron GUI
If `npm start` fails with `spawn voxvera ENOENT`, the `voxvera` command is not in your `PATH`. Install it with `pipx install git+https://github.com/PR0M3TH3AN/VoxVera.git` or run `./install.sh` from the repository.
## Missing dependencies
Run `voxvera check` to verify your setup. The command checks for required
Python packages (`qrcode`, `Pillow`, `jsmin`, `htmlmin`, `pypdf`) and
external tools (`onionshare-cli`), then prints a summary of anything
missing. To install everything:
```bash
# Recommended: use the install script (handles Tor + OnionShare too)
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
# Or reinstall just the Python package
pipx install --force 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
```
docs/en/usage.md
-156
View File
@@ -1,156 +0,0 @@
# Detailed Usage
This guide covers common CLI workflows. See `docs/docker.md` for Docker instructions and `docs/templates.md` for available flyer templates.
## Prerequisites
VoxVera is designed to be highly portable. You can run it directly from the source code on any platform with Python installed.
Linux with `systemd --user` is the supported persistent-host environment. Windows, macOS, Docker, Flatpak, AppImage, Homebrew, and Chocolatey are currently experimental and should not yet be treated as equally reliable hidden-service deployment targets.
### 1. Automated Install (Recommended)
The easiest way to install VoxVera is using the Linux-first installer script:
**Linux / macOS:**
```bash
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
```
On Linux, this also installs the recurring recovery timer used to retry hidden-service startup after boot and after missed/offline periods.
**Windows (PowerShell):**
```powershell
irm https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.ps1 | iex
```
The Windows installer is experimental and does not yet guarantee production-ready background hosting behavior.
### 2. Manual Source Install
If you have downloaded the source code ZIP:
1. **Extract** the ZIP file.
2. **Open a terminal** in the extracted folder.
3. **Run the setup script**:
- **Linux/macOS:** `./setup.sh`
- **Windows:** `.\voxvera-install.sh` (or run `python -m pip install .`)
## Uninstallation
If you wish to remove VoxVera from your system, you can use the provided uninstall scripts from the source directory. This will safely remove the CLI tool and any downloaded dependencies.
- **Linux / macOS:** Run `./uninstall.sh`
- **Windows (PowerShell):** Run `.\uninstall.ps1`
*Note: Uninstallation will not delete your generated flyers or your `.onion` keys stored in the `~/voxvera-exports` or local `host/` folders.*
## Step-by-Step
1. **Initialize:** Run `voxvera init` and follow the prompts. You will be asked to select your language first.
2. **Build:** Generate the flyer assets. Every build automatically creates a `voxvera-portable.zip` in the flyer's folder, allowing others to download the full tool directly from your flyer.
```bash
voxvera build
```
3. **Serve:** Publish the flyer over Tor:
```bash
voxvera serve
```
This automatically detects your Tor instance, starts OnionShare, and writes the generated .onion address into the flyer's tear-off links.
### Persistent Hosting On Linux
For a machine that should resume hosting automatically after boot or after being offline, install the autostart recovery timer:
```bash
voxvera autostart
```
This installs a `systemd --user` timer that reruns `voxvera start-all` every few minutes. The retry loop is the supported way to recover hidden-service hosting after suspend, reboot, or temporary network loss.
## Language Support
VoxVera is fully localized. You can change your language preference permanently using either the interactive selector or a direct shortcut:
- **Interactive Selector:** `voxvera lang`
- **Direct Shortcut:** `voxvera --lang de` (sets preference to German)
### Supported Languages:
- **English:** `en`
- **Spanish:** `es` (alias: `--idioma`)
- **German:** `de` (alias: `--sprache`)
You can also force a specific language for a single command without changing your permanent preference:
- **English:** `voxvera --lang en check`
- **German:** `voxvera --sprache de check`
- **Spanish:** `voxvera --idioma es check`
The generated flyers automatically detect the visitor's browser language and switch the UI text accordingly.
## Server Management
Manage multiple flyers and their Tor identities from a single interactive menu:
```bash
voxvera manage
```
Features:
- **--- Create New Site/Flyer ---**: Start the full setup sequence.
- **--- Start All Sites ---**: Launch or shut down every flyer in your fleet at once.
- **Real-time Status**: View active `.onion` URLs and Tor bootstrapping progress indicators.
- **Individual Control**: Export to Zip specific sites to ZIP or delete them.
## Universal Mirroring (Viral Distribution)
To ensure VoxVera remains accessible even if central repositories are censored, every flyer acts as a mirror for the tool.
When you host a flyer, the **"Download Source Code"** button on the landing page provides a `voxvera-source.zip` containing:
- The full source code and all supported languages.
- Installation and setup scripts for all platforms.
- Complete documentation and templates.
To keep the mirrored download practical for low-bandwidth redistribution, the
source archive does not ship pre-downloaded Tor binaries. Normal installer and
release builds still fetch or bundle those artifacts separately.
This allows anyone who scans your flyer to become a new distributor of the VoxVera tool.
## Export & Backup
Back up your unique Tor identities (so your `.onion` URL never changes) or move your flyers to another machine.
- **Export a single site**: `voxvera export <folder_name>`
- **Export all sites**: `voxvera export-all`
**Storage location:** All exports are saved to `~/voxvera-exports/` on all platforms.
## Import & Recovery
Restore your entire setup on a new machine by moving your ZIP files to `~/voxvera-exports/` and running:
```bash
voxvera import-multiple
```
## Portability & Offline Use
If you need to run VoxVera on a machine without internet access, you can "vendorize" the dependencies first:
```bash
voxvera vendorize
```
This downloads all required Python libraries into `voxvera/vendor/`. The tool will then prioritize these local files, allowing it to run without `pip install`.
## Batch Import (JSON)
To bulk-generate flyers from multiple JSON configuration files, place them in the `imports/` directory and run:
```bash
voxvera batch-import
```
## How URLs Work
Each flyer has two separate URLs:
- **Tear-off link** (auto-generated): The .onion address where the flyer is hosted.
- **Content link** (user-configured): An external URL pointing to a website, video, or download.
You do not need to manually enter the .onion address; VoxVera handles this automatically during the `serve` phase.
docs/es/AGENTS.md
-42
View File
@@ -1,42 +0,0 @@
# AI Agent Instructions for VoxVera
This guide is for AI agents (like Gemini, Claude, or GPT) contributing to the VoxVera project. Follow these protocols to maintain the architectural integrity and multi-language support.
## Core Mandates
1. **Security-First**: VoxVera is a Tor-based tool. Never suggest features that leak IP addresses or use non-Tor external resources (CDNs, etc.).
2. **Local-First**: All assets (fonts, dependencies, binaries) must be self-contained within the `voxvera/` package to support the Universal Mirroring model.
3. **Tokenized UI**: Never hardcode user-facing strings. Always add them to `voxvera/locales/en.json` and use the `t('cli.token')` helper.
4. **Markdown Redaction**: Use `~~text~~` in locale JSONs for strike-through effects. Both the build system and the JS engine handle the conversion to `<span class="redacted">` automatically.
5. **Visual Width Testing**: When modifying UI or adding languages, verify that long or complex strings (e.g., Hindi ligatures or CJK characters) do not exceed the visual unit limits defined in the CLI.
## Localization Protocol
When adding a new language or updating an existing one:
- **CLI/Flyers**: Update `voxvera/locales/{lang}.json`. Include `meta`, `cli`, `web`, and `landing` categories.
- **Landing Page**:
- Directly update the `const locales` object in `site/index.html`.
- **Crucial**: Run `voxvera build-site` to generate the latest portable bundle and refresh the pre-rendered HTML.
- **Documentation**:
- Master templates live in `docs/templates/`.
- Localized overrides live in `voxvera/locales/{lang}/docs/`.
- **Crucial**: After any change to locales or templates, you MUST run `voxvera build-docs` to synchronize the output in `docs/{en,es,de}/`.
## Universal Mirroring
VoxVera propagates through its own flyers.
- Every `voxvera build` and `voxvera build-site` generates `voxvera-portable.zip`.
- If you modify the core source code, ensure the `bundle_portable` function in `voxvera/cli.py` still correctly captures all necessary directories (especially `vendor/`, `locales/`, and `resources/`).
## Verification Checklist
Before finishing a task, ensure you have:
1. Run unit tests: `pytest tests/test_cli.py`.
2. Verified the localization: `voxvera --lang {lang} check`.
3. Rebuilt the documentation: `voxvera build-docs`.
4. Synchronized the public site: `voxvera build-site`.
5. Verified the portable bundle exists: `ls -l voxvera/host/*/download/voxvera-portable.zip` and `ls -l site/download/voxvera-portable.zip`.
---
Follow these rules to ensure VoxVera remains a robust, viral, and decentralized tool for truth.
docs/es/CONTRIBUTING.md
-47
View File
@@ -1,47 +0,0 @@
# Contributing to VoxVera
Thank you for your interest in contributing to VoxVera! This project aims to be a global, censorship-resistant tool, and your help—especially with translations—is vital.
## Adding a New Language
VoxVera uses a centralized token system for the CLI and Web components, and a template-based system for Documentation. To add a new language (e.g., French/`fr`), follow this checklist:
### 1. The Token File
Create a new JSON file in `voxvera/locales/{lang_code}.json`.
- Use `en.json` as your master template.
- **`meta`**: Include the native language name and a flag emoji.
- **`cli`**: Translate all strings used in the terminal interface.
- **`web`**: Translate strings used on the generated landing pages and flyers.
- **`landing`**: Translate the specific content for the official VoxVera website.
- **Formatting**: You can use Markdown-style strike-throughs (`~~redacted text~~`) in any of these strings; they will be automatically converted to the stylized "redacted" effect on the flyers.
### 2. The Landing Page
The main landing page is generated from the shared template and locale files.
- Add your language in `voxvera/locales/{lang_code}.json`.
- Do **not** edit `site/index.html` directly; it is generated output.
- Run `voxvera build-site` to refresh the public assets and inject your new locale into the generated HTML.
### 3. Documentation
VoxVera uses the **Doc-Sync Engine** to keep manuals in sync.
- Create localized Markdown files in `voxvera/locales/{lang_code}/docs/`.
- Use the templates in `docs/templates/` as your guide.
- You can use `cli.token_name` to reference terminal commands automatically.
### 4. Build and Verify
Run the following commands to verify your changes:
- `voxvera --lang {lang_code} check` (Verify CLI translation)
- `voxvera build-docs` (Generate localized manuals)
- `voxvera build-site` (Synchronize the public website and generate the latest portable bundle)
- Open the generated `site/index.html` in a browser and test the language switcher.
## Code Contributions
- **Dependencies**: if you add a new Python library to `requirements.txt`, you MUST run `voxvera vendorize` to include it in the portable distribution.
- **Layout Integrity**: VoxVera uses visual width validation. If you add new UI elements, ensure they respect the physical boundaries of an 8.5"x11" flyer.
- **Tests**: Ensure all tests pass: `pytest tests/`. Run the integrity suite specifically when modifying locales: `pytest tests/test_integrity.py`.
- **Generated artifacts**: Treat `voxvera/resources/bin/` as local build output, not source files. Release binaries belong in GitHub Releases, not hand-edited repo state.
- **Style**: Follow the existing coding style (PEP 8 for Python).
- **Documentation**: If adding a new feature, update the master templates in `docs/templates/` and run `voxvera build-docs`.
---
Together, we can ensure that truth remains accessible to everyone, everywhere.
docs/es/docker.md
-48
View File
@@ -1,48 +0,0 @@
# Docker Usage
Experimental: the container path is not yet a production-grade hidden-service deployment target. Linux with `systemd --user` remains the supported persistent-host environment.
A prebuilt image containing Tor, OnionShare and the `voxvera` CLI is published to
`ghcr.io/voxvera/voxvera`.
```bash
# pull the image
docker pull ghcr.io/voxvera/voxvera:latest
# run the experimental container with flyers stored in ./flyers
mkdir -p flyers
docker run -d \
--name voxvera \
--restart unless-stopped \
-v "$(pwd)/flyers:/flyers" \
ghcr.io/voxvera/voxvera:latest
```
The container now uses a dedicated entrypoint that:
- stores runtime state under `/flyers`
- seeds `/flyers/config.json` if needed
- starts an in-container Tor daemon on `127.0.0.1:9050/9051`
- bootstraps a default site when `/flyers/host` is empty
- runs `voxvera start-all` on startup and retries it periodically
- exposes a container healthcheck based on `voxvera doctor --json`
Useful commands:
```bash
docker logs -f voxvera
docker exec -it voxvera voxvera doctor --json
docker exec -it voxvera voxvera autostart status --json
```
If you prefer Compose:
```yaml
services:
voxvera:
image: ghcr.io/voxvera/voxvera:latest
restart: unless-stopped
volumes:
- ./flyers:/flyers
```
Use this path for testing only until the container runtime and background recovery behavior are validated end-to-end.
docs/es/templates.md
-14
View File
@@ -1,14 +0,0 @@
# Flyer Templates
Pre-built flyer templates live in the `templates/` directory. Use the CLI to copy one with:
```bash
voxvera init --template <name>
```
This will create a new folder under `dist/` named `<name>-<YYYYMMDD>` containing the template files.
Available templates:
- **blank** – minimal placeholder files, also used when extracting fields from a PDF.
- **voxvera** – example flyer showcasing the VoxVera project.
docs/es/troubleshooting.md
-75
View File
@@ -1,75 +0,0 @@
# Troubleshooting
This page collects common issues encountered when hosting or accessing flyers.
## Tor connectivity
- Ensure Tor is allowed through your firewall. On systems using `ufw` you may need to run `sudo ufw allow tor`.
- Some networks block Tor entirely. If you cannot reach onion services, try connecting over a different network or use a Tor bridge.
## Supported deployment target
- The supported persistent-host setup is Linux with `systemd --user`.
- Windows, macOS, Docker, Flatpak, AppImage, Homebrew, and Chocolatey are currently experimental and may not recover hosting automatically after reboot or network interruptions.
## Tor port detection
`voxvera serve` auto-detects Tor by probing common ports (9050/9150 for SOCKS, 9051/9151 for control). If detection fails -- for example when Tor runs on non-standard ports -- you can override with environment variables:
```bash
TOR_SOCKS_PORT=19050 TOR_CONTROL_PORT=19051 voxvera serve
```
If no running Tor is found, the defaults (9050/9051) are used and OnionShare will attempt to connect on those ports.
## Firewall rules
- If `voxvera serve` fails to start OnionShare, verify that outbound connections on ports 9001 and 80 are permitted.
- Corporate or university firewalls can block the hidden service ports required by Tor.
## SELinux
- On SELinux-enabled distributions you may see `permission denied` errors when OnionShare writes to the `host` directory.
- Run `sudo chcon -Rt svirt_sandbox_file_t host` or disable SELinux enforcement for the folder.
## OnionShare crashes
If `voxvera serve` prints "OnionShare exited unexpectedly", check the log file
`host/<folder_name>/onionshare.log` for details. Common causes:
- Tor is not running (`sudo systemctl start tor`)
- A port conflict with another service
- Missing `onionshare-cli` (run `voxvera check`)
## Onion URL changed unexpectedly
The onion URL is tied to the Ed25519 keypair stored in
`host/<folder_name>/.onionshare-session`. If this file is deleted, a new
keypair (and URL) will be generated on the next `voxvera serve`. The
`voxvera import` command preserves this file automatically, but manual
deletion of the `host/` directory will destroy it.
## Hosting does not return after reboot or network loss
On Linux, install or verify the recovery timer:
```bash
voxvera autostart
systemctl --user status voxvera-start.timer
systemctl --user status voxvera-start.service
```
The supported recovery path is the recurring `systemd --user` timer, which reruns `voxvera start-all` every few minutes.
## QR codes not generated
If `voxvera build` reports "No URLs configured yet", this is expected before the first `voxvera serve`. QR codes for tear-off links are generated automatically once the .onion address is known. QR codes for the content link are generated if you provided a URL during `voxvera init`.
## Electron GUI
If `npm start` fails with `spawn voxvera ENOENT`, the `voxvera` command is not in your `PATH`. Install it with `pipx install git+https://github.com/PR0M3TH3AN/VoxVera.git` or run `./install.sh` from the repository.
## Missing dependencies
Run `voxvera check` to verify your setup. The command checks for required
Python packages (`qrcode`, `Pillow`, `jsmin`, `htmlmin`, `pypdf`) and
external tools (`onionshare-cli`), then prints a summary of anything
missing. To install everything:
```bash
# Recommended: use the install script (handles Tor + OnionShare too)
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
# Or reinstall just the Python package
pipx install --force 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
```
docs/es/usage.md
-136
View File
@@ -1,136 +0,0 @@
# Uso detallado
Esta guía cubre los flujos de trabajo de CLI comunes. Consulte `docs/docker.md` para obtener instrucciones de Docker y `docs/templates.md` para conocer las plantillas de volantes disponibles.
## Prerrequisitos
VoxVera está diseñado para ser altamente portátil y requiere un mínimo de dependencias del sistema.
### 1. Binarios independientes (Recomendado)
Puede descargar binarios independientes sin dependencias para su sistema operativo:
- **Linux:** `voxvera-linux`
- **Windows:** `voxvera-windows.exe`
- **macOS:** `voxvera-macos`
Estos binarios incluyen todo lo necesario para ejecutar VoxVera (excepto `onionshare-cli`).
### 2. Instalador de una sola línea
Alternativamente, instale a través de nuestro script automatizado:
```bash
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
```
### 3. Instalación manual de Python
Si prefiere ejecutar desde la fuente:
```bash
pipx install 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
sudo apt install tor onionshare-cli # Debian/Ubuntu
```
## Paso a paso
1. **Inicializar:** Ejecute `voxvera init` y siga las instrucciones. Se le pedirá que seleccione su idioma primero.
2. **Construir:** Genere los activos del volante. Cada construcción crea automáticamente un `voxvera-portable.zip` en la carpeta del volante, lo que permite que otros descarguen la herramienta completa directamente desde su volante.
```bash
voxvera build
```
3. **Servir:** Publique el volante sobre Tor:
```bash
voxvera serve
```
Esto detecta automáticamente su instancia de Tor, inicia OnionShare y escribe la dirección .onion generada en los enlaces desprendibles del volante.
## Soporte de idiomas
VoxVera está totalmente localizado. Puede cambiar su preferencia de idioma de forma permanente utilizando el selector interactivo o un acceso directo:
- **Selector interactivo:** `voxvera lang`
- **Acceso directo:** `voxvera --lang es` (establece la preferencia en español)
### Idiomas soportados:
- **Inglés:** `en`
- **Español:** `es` (alias: `--idioma`)
- **Alemán:** `de` (alias: `--sprache`)
- **Ruso:** `ru`
- **Hebreo:** `he`
- **Árabe:** `ar`
- **Francés:** `fr`
- **Japonés:** `ja`
- **Hindi:** `hi`
- **Swahili:** `sw`
También puede forzar un idioma específico para un solo comando sin cambiar su preferencia permanente:
- **Inglés:** `voxvera --lang en check`
- **Español:** `voxvera --idioma es check`
Los volantes generados detectan automáticamente el idioma del navegador del visitante y cambian el texto de la interfaz en consecuencia.
## Gestión de servidores
Gestione múltiples volantes y sus identidades de Tor desde un único menú interactivo:
```bash
voxvera manage
```
Características:
- **--- Crear Nuevo Sitio/Volante ---**: Inicie la secuencia de configuración completa.
- **--- Iniciar Todos los Sitios ---**: Inicie o apague todos los volantes de su flota a la vez.
- **Estado en tiempo real**: Vea las URL .onion activas e indicadores de progreso de arranque de Tor.
- **Control individual**: Exportar a Zip sitios específicos a ZIP o elimínelos.
## Espejo universal (Distribución viral)
Para garantizar que VoxVera siga siendo accesible incluso si los repositorios centrales son censurados, cada volante actúa como un espejo para la herramienta.
Cuando hospeda un volante, el botón **"Descargar Herramienta y Código"** en la página de inicio proporciona un `voxvera-portable.zip` que contiene:
- El código fuente completo y todos los idiomas soportados.
- Todas las dependencias de Python (pre-vendeurizadas).
- Binarios de Tor multiplataforma.
Esto permite que cualquier persona que escanee su volante se convierta en un nuevo distribuidor de la herramienta VoxVera.
## Exportación y respaldo
Haga una copia de seguridad de sus identidades únicas de Tor (para que su URL .onion nunca cambie) o mueva sus volantes a otra máquina.
- **Exportar un solo sitio**: `voxvera export <nombre_carpeta>`
- **Exportar todos los servicios**: `voxvera export-all`
**Lugar de almacenamiento:** Todas las exportaciones se guardan como archivos ZIP en una carpeta llamada `voxvera-exports` en el directorio de inicio del usuario (`~/voxvera-exports/`) en todas las plataformas.
## Importación y recuperación
Restaure toda su configuración en una nueva máquina moviendo sus archivos ZIP a `~/voxvera-exports/` y ejecutando:
```bash
voxvera import-multiple
```
## Portabilidad y uso sin conexión
Si necesita ejecutar VoxVera en una máquina sin acceso a Internet, primero puede "vendeurizar" las dependencias:
```bash
voxvera vendorize
```
Esto descarga todas las librerías de Python requeridas en `voxvera/vendor/`. La herramienta dará prioridad a estos archivos locales, lo que le permitirá ejecutarse sin `pip install`.
## Importación por lotes (JSON)
Para generar volantes de forma masiva a partir de múltiples archivos de configuración JSON, colóquelos en el directorio `imports/` y ejecute:
```bash
voxvera batch-import
```
## Cómo funcionan las URL
Cada volante tiene dos URL separadas:
- **Enlace desprendible** (generado automáticamente): La dirección .onion donde se hospeda el volante.
- **Enlace de contenido** (configurado por el usuario): Una URL externa que apunta a un sitio web, video o descarga.
No es necesario ingresar manualmente la dirección .onion; VoxVera lo maneja automáticamente durante la fase de `serve`.
docs/fa/AGENTS.md
-42
View File
@@ -1,42 +0,0 @@
# AI Agent Instructions for VoxVera
This guide is for AI agents (like Gemini, Claude, or GPT) contributing to the VoxVera project. Follow these protocols to maintain the architectural integrity and multi-language support.
## Core Mandates
1. **Security-First**: VoxVera is a Tor-based tool. Never suggest features that leak IP addresses or use non-Tor external resources (CDNs, etc.).
2. **Local-First**: All assets (fonts, dependencies, binaries) must be self-contained within the `voxvera/` package to support the Universal Mirroring model.
3. **Tokenized UI**: Never hardcode user-facing strings. Always add them to `voxvera/locales/en.json` and use the `t('cli.token')` helper.
4. **Markdown Redaction**: Use `~~text~~` in locale JSONs for strike-through effects. Both the build system and the JS engine handle the conversion to `<span class="redacted">` automatically.
5. **Visual Width Testing**: When modifying UI or adding languages, verify that long or complex strings (e.g., Hindi ligatures or CJK characters) do not exceed the visual unit limits defined in the CLI.
## Localization Protocol
When adding a new language or updating an existing one:
- **CLI/Flyers**: Update `voxvera/locales/{lang}.json`. Include `meta`, `cli`, `web`, and `landing` categories.
- **Landing Page**:
- Directly update the `const locales` object in `site/index.html`.
- **Crucial**: Run `voxvera build-site` to generate the latest portable bundle and refresh the pre-rendered HTML.
- **Documentation**:
- Master templates live in `docs/templates/`.
- Localized overrides live in `voxvera/locales/{lang}/docs/`.
- **Crucial**: After any change to locales or templates, you MUST run `voxvera build-docs` to synchronize the output in `docs/{en,es,de}/`.
## Universal Mirroring
VoxVera propagates through its own flyers.
- Every `voxvera build` and `voxvera build-site` generates `voxvera-portable.zip`.
- If you modify the core source code, ensure the `bundle_portable` function in `voxvera/cli.py` still correctly captures all necessary directories (especially `vendor/`, `locales/`, and `resources/`).
## Verification Checklist
Before finishing a task, ensure you have:
1. Run unit tests: `pytest tests/test_cli.py`.
2. Verified the localization: `voxvera --lang {lang} check`.
3. Rebuilt the documentation: `voxvera build-docs`.
4. Synchronized the public site: `voxvera build-site`.
5. Verified the portable bundle exists: `ls -l voxvera/host/*/download/voxvera-portable.zip` and `ls -l site/download/voxvera-portable.zip`.
---
Follow these rules to ensure VoxVera remains a robust, viral, and decentralized tool for truth.
docs/fa/CONTRIBUTING.md
-47
View File
@@ -1,47 +0,0 @@
# Contributing to VoxVera
Thank you for your interest in contributing to VoxVera! This project aims to be a global, censorship-resistant tool, and your help—especially with translations—is vital.
## Adding a New Language
VoxVera uses a centralized token system for the CLI and Web components, and a template-based system for Documentation. To add a new language (e.g., French/`fr`), follow this checklist:
### 1. The Token File
Create a new JSON file in `voxvera/locales/{lang_code}.json`.
- Use `en.json` as your master template.
- **`meta`**: Include the native language name and a flag emoji.
- **`cli`**: Translate all strings used in the terminal interface.
- **`web`**: Translate strings used on the generated landing pages and flyers.
- **`landing`**: Translate the specific content for the official VoxVera website.
- **Formatting**: You can use Markdown-style strike-throughs (`~~redacted text~~`) in any of these strings; they will be automatically converted to the stylized "redacted" effect on the flyers.
### 2. The Landing Page
The main landing page is generated from the shared template and locale files.
- Add your language in `voxvera/locales/{lang_code}.json`.
- Do **not** edit `site/index.html` directly; it is generated output.
- Run `voxvera build-site` to refresh the public assets and inject your new locale into the generated HTML.
### 3. Documentation
VoxVera uses the **Doc-Sync Engine** to keep manuals in sync.
- Create localized Markdown files in `voxvera/locales/{lang_code}/docs/`.
- Use the templates in `docs/templates/` as your guide.
- You can use `cli.token_name` to reference terminal commands automatically.
### 4. Build and Verify
Run the following commands to verify your changes:
- `voxvera --lang {lang_code} check` (Verify CLI translation)
- `voxvera build-docs` (Generate localized manuals)
- `voxvera build-site` (Synchronize the public website and generate the latest portable bundle)
- Open the generated `site/index.html` in a browser and test the language switcher.
## Code Contributions
- **Dependencies**: if you add a new Python library to `requirements.txt`, you MUST run `voxvera vendorize` to include it in the portable distribution.
- **Layout Integrity**: VoxVera uses visual width validation. If you add new UI elements, ensure they respect the physical boundaries of an 8.5"x11" flyer.
- **Tests**: Ensure all tests pass: `pytest tests/`. Run the integrity suite specifically when modifying locales: `pytest tests/test_integrity.py`.
- **Generated artifacts**: Treat `voxvera/resources/bin/` as local build output, not source files. Release binaries belong in GitHub Releases, not hand-edited repo state.
- **Style**: Follow the existing coding style (PEP 8 for Python).
- **Documentation**: If adding a new feature, update the master templates in `docs/templates/` and run `voxvera build-docs`.
---
Together, we can ensure that truth remains accessible to everyone, everywhere.
docs/fa/docker.md
-48
View File
@@ -1,48 +0,0 @@
# Docker Usage
Experimental: the container path is not yet a production-grade hidden-service deployment target. Linux with `systemd --user` remains the supported persistent-host environment.
A prebuilt image containing Tor, OnionShare and the `voxvera` CLI is published to
`ghcr.io/voxvera/voxvera`.
```bash
# pull the image
docker pull ghcr.io/voxvera/voxvera:latest
# run the experimental container with flyers stored in ./flyers
mkdir -p flyers
docker run -d \
--name voxvera \
--restart unless-stopped \
-v "$(pwd)/flyers:/flyers" \
ghcr.io/voxvera/voxvera:latest
```
The container now uses a dedicated entrypoint that:
- stores runtime state under `/flyers`
- seeds `/flyers/config.json` if needed
- starts an in-container Tor daemon on `127.0.0.1:9050/9051`
- bootstraps a default site when `/flyers/host` is empty
- runs `voxvera start-all` on startup and retries it periodically
- exposes a container healthcheck based on `voxvera doctor --json`
Useful commands:
```bash
docker logs -f voxvera
docker exec -it voxvera voxvera doctor --json
docker exec -it voxvera voxvera autostart status --json
```
If you prefer Compose:
```yaml
services:
voxvera:
image: ghcr.io/voxvera/voxvera:latest
restart: unless-stopped
volumes:
- ./flyers:/flyers
```
Use this path for testing only until the container runtime and background recovery behavior are validated end-to-end.
docs/fa/templates.md
-14
View File
@@ -1,14 +0,0 @@
# Flyer Templates
Pre-built flyer templates live in the `templates/` directory. Use the CLI to copy one with:
```bash
voxvera init --template <name>
```
This will create a new folder under `dist/` named `<name>-<YYYYMMDD>` containing the template files.
Available templates:
- **blank** – minimal placeholder files, also used when extracting fields from a PDF.
- **voxvera** – example flyer showcasing the VoxVera project.
docs/fa/troubleshooting.md
-75
View File
@@ -1,75 +0,0 @@
# Troubleshooting
This page collects common issues encountered when hosting or accessing flyers.
## Tor connectivity
- Ensure Tor is allowed through your firewall. On systems using `ufw` you may need to run `sudo ufw allow tor`.
- Some networks block Tor entirely. If you cannot reach onion services, try connecting over a different network or use a Tor bridge.
## Supported deployment target
- The supported persistent-host setup is Linux with `systemd --user`.
- Windows, macOS, Docker, Flatpak, AppImage, Homebrew, and Chocolatey are currently experimental and may not recover hosting automatically after reboot or network interruptions.
## Tor port detection
`voxvera serve` auto-detects Tor by probing common ports (9050/9150 for SOCKS, 9051/9151 for control). If detection fails -- for example when Tor runs on non-standard ports -- you can override with environment variables:
```bash
TOR_SOCKS_PORT=19050 TOR_CONTROL_PORT=19051 voxvera serve
```
If no running Tor is found, the defaults (9050/9051) are used and OnionShare will attempt to connect on those ports.
## Firewall rules
- If `voxvera serve` fails to start OnionShare, verify that outbound connections on ports 9001 and 80 are permitted.
- Corporate or university firewalls can block the hidden service ports required by Tor.
## SELinux
- On SELinux-enabled distributions you may see `permission denied` errors when OnionShare writes to the `host` directory.
- Run `sudo chcon -Rt svirt_sandbox_file_t host` or disable SELinux enforcement for the folder.
## OnionShare crashes
If `voxvera serve` prints "OnionShare exited unexpectedly", check the log file
`host/<folder_name>/onionshare.log` for details. Common causes:
- Tor is not running (`sudo systemctl start tor`)
- A port conflict with another service
- Missing `onionshare-cli` (run `voxvera check`)
## Onion URL changed unexpectedly
The onion URL is tied to the Ed25519 keypair stored in
`host/<folder_name>/.onionshare-session`. If this file is deleted, a new
keypair (and URL) will be generated on the next `voxvera serve`. The
`voxvera import` command preserves this file automatically, but manual
deletion of the `host/` directory will destroy it.
## Hosting does not return after reboot or network loss
On Linux, install or verify the recovery timer:
```bash
voxvera autostart
systemctl --user status voxvera-start.timer
systemctl --user status voxvera-start.service
```
The supported recovery path is the recurring `systemd --user` timer, which reruns `voxvera start-all` every few minutes.
## QR codes not generated
If `voxvera build` reports "No URLs configured yet", this is expected before the first `voxvera serve`. QR codes for tear-off links are generated automatically once the .onion address is known. QR codes for the content link are generated if you provided a URL during `voxvera init`.
## Electron GUI
If `npm start` fails with `spawn voxvera ENOENT`, the `voxvera` command is not in your `PATH`. Install it with `pipx install git+https://github.com/PR0M3TH3AN/VoxVera.git` or run `./install.sh` from the repository.
## Missing dependencies
Run `voxvera check` to verify your setup. The command checks for required
Python packages (`qrcode`, `Pillow`, `jsmin`, `htmlmin`, `pypdf`) and
external tools (`onionshare-cli`), then prints a summary of anything
missing. To install everything:
```bash
# Recommended: use the install script (handles Tor + OnionShare too)
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
# Or reinstall just the Python package
pipx install --force 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
```
docs/fa/usage.md
-130
View File
@@ -1,130 +0,0 @@
# راهنمای استفاده تفصیلی
این راهنما جریان‌های کاری معمول رابط سطر فرمان (CLI) را پوشش می‌دهد. برای دستورالعمل‌های داکر به `docs/docker.md` و برای قالب‌های اعلامیه موجود به `docs/templates.md` مراجعه کنید.
## پیش‌نیازها
ووکس‌ورا (VoxVera) به گونه‌ای طراحی شده است که بسیار قابل حمل باشد و به حداقل وابستگی‌های سیستم نیاز داشته باشد.
### ۱. فایل‌های اجرایی مستقل (توصیه شده)
می‌توانید فایل‌های اجرایی (Binary) مستقل و بدون نیاز به وابستگی را برای سیستم‌عامل خود دانلود کنید:
- **لینوکس:** `voxvera-linux`
- **ویندوز:** `voxvera-windows.exe`
- **مک:** `voxvera-macos`
این فایل‌ها شامل تمام موارد لازم برای اجرای ووکس‌ورا هستند (به جز `onionshare-cli`).
### ۲. نصب‌کننده تک‌خطی
همچنین می‌توانید از طریق اسکریپت خودکار ما نصب را انجام دهید:
```bash
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
```
### ۳. نصب دستی پایتون
اگر ترجیح می‌دهید از سورس کد استفاده کنید:
```bash
pipx install 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
sudo apt install tor onionshare-cli # دبیان/اوبونتو
```
## گام به گام
۱. **راه‌اندازی:** دستور `voxvera init` را اجرا کرده و مراحل را دنبال کنید. در ابتدا از شما خواسته می‌شود زبان خود را انتخاب کنید.
۲. **ساخت:** دارایی‌های اعلامیه را ایجاد کنید. هر بار که عملیات ساخت انجام می‌شود، یک فایل `voxvera-portable.zip` به طور خودکار در پوشه اعلامیه ساخته می‌شود که به دیگران اجازه می‌دهد ابزار کامل را مستقیماً از اعلامیه شما دانلود کنند.
```bash
voxvera build
```
۳. **میزبانی:** اعلامیه را روی شبکه تور منتشر کنید:
```bash
voxvera serve
```
این دستور به طور خودکار تور شما را شناسایی کرده، OnionShare را راه‌اندازی می‌کند و آدرس .onion تولید شده را در پیوندهای جداشونده اعلامیه می‌نویسد.
## پشتیبانی از زبان‌ها
ووکس‌ورا کاملاً بومی‌سازی شده است. می‌توانید اولویت زبان خود را به طور دائم با استفاده از انتخاب‌گر تعاملی یا میان‌بر مستقیم تغییر دهید:
- **انتخاب‌گر تعاملی:** `voxvera lang`
- **میان‌بر مستقیم:** `voxvera --lang fa` (تنظیم اولویت روی فارسی)
### زبان‌های پشتیبانی شده:
- **انگلیسی:** `en`
- **اسپانیایی:** `es` (نام مستعار: `--idioma`)
- **آلمانی:** `de` (نام مستعار: `--sprache`)
- **فارسی:** `fa`
همچنین می‌توانید بدون تغییر اولویت دائمی، یک زبان خاص را برای یک دستور واحد اجبار کنید:
- **انگلیسی:** `voxvera --lang en check`
- **فارسی:** `voxvera --lang fa check`
اعلامیه‌های تولید شده به طور خودکار زبان مرورگر بازدیدکننده را تشخیص داده و متن رابط کاربری را بر اساس آن تغییر می‌دهند.
## مدیریت سرورها
چندین اعلامیه و هویت‌های تور آن‌ها را از یک منوی تعاملی واحد مدیریت کنید:
```bash
voxvera manage
```
ویژگی‌ها:
- **--- ایجاد سایت/اعلامیه جدید ---**: شروع توالی کامل تنظیمات.
- **--- اجرای همه سایت‌ها ---**: راه‌اندازی یا توقف همزمان تمام اعلامیه‌های شما.
- **وضعیت لحظه‌ای**: مشاهده آدرس‌های .onion فعال و نشانگرهای پیشرفت تور.
- **کنترل فردی**: صدور به صورت زیپ سایت‌های خاص به فرمت ZIP یا حذف آن‌ها.
## آینه‌سازی همگانی (توزیع ویروسی)
برای اطمینان از اینکه ووکس‌ورا حتی در صورت سانسور مخازن مرکزی در دسترس باقی می‌ماند، هر اعلامیه به عنوان یک آینه برای این ابزار عمل می‌کند.
وقتی اعلامیه‌ای را میزبانی می‌کنید، دکمه **"دانلود ابزار و کد منبع"** در صفحه فرود، یک فایل `voxvera-portable.zip` شامل موارد زیر ارائه می‌دهد:
- سورس کد کامل و تمامی زبان‌های پشتیبانی شده.
- تمامی وابستگی‌های پایتون (از پیش بسته‌بندی شده).
- فایل‌های اجرایی تور برای تمامی پلتفرم‌ها.
این کار به هر کسی که اعلامیه شما را اسکن می‌کند اجازه می‌دهد تا به توزیع‌کننده جدیدی برای ابزار ووکس‌ورا تبدیل شود.
## صدور و پشتیبان‌گیری
از هویت‌های تور منحصر به فرد خود پشتیبان بگیرید (تا آدرس .onion شما هرگز تغییر نکند) یا اعلامیه‌های خود را به سیستم دیگری منتقل کنید.
- **صدور یک سایت واحد:** `voxvera export <folder_name>`
- **صدور تمامی سایت‌ها:** `voxvera export-all`
**محل ذخیره‌سازی:** تمامی موارد صادر شده به صورت فایل ZIP در پوشه‌ای به نام `voxvera-exports` در پوشه خانگی کاربر (`~/voxvera-exports/`) در تمامی پلتفرم‌ها ذخیره می‌شوند.
## وارد کردن و بازیابی
با انتقال فایل‌های ZIP خود به پوشه `~/voxvera-exports/` و اجرای دستور زیر، کل تنظیمات خود را در یک سیستم جدید بازیابی کنید:
```bash
voxvera import-multiple
```
## قابلیت حمل و استفاده آفلاین
اگر نیاز دارید ووکس‌ورا را روی سیستمی بدون دسترسی به اینترنت اجرا کنید، می‌توانید ابتدا وابستگی‌ها را به صورت محلی ذخیره کنید:
```bash
voxvera vendorize
```
این دستور تمامی کتابخانه‌های پایتون مورد نیاز را در پوشه `voxvera/vendor/` دانلود می‌کند. ابزار سپس این فایل‌های محلی را در اولویت قرار می‌دهد و اجازه می‌دهد بدون نیاز به `pip install` اجرا شود.
## وارد کردن گروهی (JSON)
برای تولید انبوه اعلامیه‌ها از چندین فایل تنظیمات JSON، آن‌ها را در پوشه `imports/` قرار داده و اجرا کنید:
```bash
voxvera batch-import
```
## آدرس‌های URL چگونه کار می‌کنند
هر اعلامیه دارای دو آدرس URL جداگانه است:
- **پیوند جداشونده** (تولید خودکار): آدرس .onion که اعلامیه در آن میزبانی می‌شود.
- **پیوند محتوا** (تنظیم توسط کاربر): یک آدرس URL خارجی که به یک وب‌سایت، ویدیو یا فایل دانلود اشاره می‌کند.
نیازی نیست آدرس .onion را به صورت دستی وارد کنید؛ ووکس‌ورا در مرحله میزبانی (`serve`) این کار را به طور خودکار انجام می‌دهد.
docs/fr/AGENTS.md
-42
View File
@@ -1,42 +0,0 @@
# AI Agent Instructions for VoxVera
This guide is for AI agents (like Gemini, Claude, or GPT) contributing to the VoxVera project. Follow these protocols to maintain the architectural integrity and multi-language support.
## Core Mandates
1. **Security-First**: VoxVera is a Tor-based tool. Never suggest features that leak IP addresses or use non-Tor external resources (CDNs, etc.).
2. **Local-First**: All assets (fonts, dependencies, binaries) must be self-contained within the `voxvera/` package to support the Universal Mirroring model.
3. **Tokenized UI**: Never hardcode user-facing strings. Always add them to `voxvera/locales/en.json` and use the `t('cli.token')` helper.
4. **Markdown Redaction**: Use `~~text~~` in locale JSONs for strike-through effects. Both the build system and the JS engine handle the conversion to `<span class="redacted">` automatically.
5. **Visual Width Testing**: When modifying UI or adding languages, verify that long or complex strings (e.g., Hindi ligatures or CJK characters) do not exceed the visual unit limits defined in the CLI.
## Localization Protocol
When adding a new language or updating an existing one:
- **CLI/Flyers**: Update `voxvera/locales/{lang}.json`. Include `meta`, `cli`, `web`, and `landing` categories.
- **Landing Page**:
- Directly update the `const locales` object in `site/index.html`.
- **Crucial**: Run `voxvera build-site` to generate the latest portable bundle and refresh the pre-rendered HTML.
- **Documentation**:
- Master templates live in `docs/templates/`.
- Localized overrides live in `voxvera/locales/{lang}/docs/`.
- **Crucial**: After any change to locales or templates, you MUST run `voxvera build-docs` to synchronize the output in `docs/{en,es,de}/`.
## Universal Mirroring
VoxVera propagates through its own flyers.
- Every `voxvera build` and `voxvera build-site` generates `voxvera-portable.zip`.
- If you modify the core source code, ensure the `bundle_portable` function in `voxvera/cli.py` still correctly captures all necessary directories (especially `vendor/`, `locales/`, and `resources/`).
## Verification Checklist
Before finishing a task, ensure you have:
1. Run unit tests: `pytest tests/test_cli.py`.
2. Verified the localization: `voxvera --lang {lang} check`.
3. Rebuilt the documentation: `voxvera build-docs`.
4. Synchronized the public site: `voxvera build-site`.
5. Verified the portable bundle exists: `ls -l voxvera/host/*/download/voxvera-portable.zip` and `ls -l site/download/voxvera-portable.zip`.
---
Follow these rules to ensure VoxVera remains a robust, viral, and decentralized tool for truth.
docs/fr/CONTRIBUTING.md
-47
View File
@@ -1,47 +0,0 @@
# Contributing to VoxVera
Thank you for your interest in contributing to VoxVera! This project aims to be a global, censorship-resistant tool, and your help—especially with translations—is vital.
## Adding a New Language
VoxVera uses a centralized token system for the CLI and Web components, and a template-based system for Documentation. To add a new language (e.g., French/`fr`), follow this checklist:
### 1. The Token File
Create a new JSON file in `voxvera/locales/{lang_code}.json`.
- Use `en.json` as your master template.
- **`meta`**: Include the native language name and a flag emoji.
- **`cli`**: Translate all strings used in the terminal interface.
- **`web`**: Translate strings used on the generated landing pages and flyers.
- **`landing`**: Translate the specific content for the official VoxVera website.
- **Formatting**: You can use Markdown-style strike-throughs (`~~redacted text~~`) in any of these strings; they will be automatically converted to the stylized "redacted" effect on the flyers.
### 2. The Landing Page
The main landing page is generated from the shared template and locale files.
- Add your language in `voxvera/locales/{lang_code}.json`.
- Do **not** edit `site/index.html` directly; it is generated output.
- Run `voxvera build-site` to refresh the public assets and inject your new locale into the generated HTML.
### 3. Documentation
VoxVera uses the **Doc-Sync Engine** to keep manuals in sync.
- Create localized Markdown files in `voxvera/locales/{lang_code}/docs/`.
- Use the templates in `docs/templates/` as your guide.
- You can use `cli.token_name` to reference terminal commands automatically.
### 4. Build and Verify
Run the following commands to verify your changes:
- `voxvera --lang {lang_code} check` (Verify CLI translation)
- `voxvera build-docs` (Generate localized manuals)
- `voxvera build-site` (Synchronize the public website and generate the latest portable bundle)
- Open the generated `site/index.html` in a browser and test the language switcher.
## Code Contributions
- **Dependencies**: if you add a new Python library to `requirements.txt`, you MUST run `voxvera vendorize` to include it in the portable distribution.
- **Layout Integrity**: VoxVera uses visual width validation. If you add new UI elements, ensure they respect the physical boundaries of an 8.5"x11" flyer.
- **Tests**: Ensure all tests pass: `pytest tests/`. Run the integrity suite specifically when modifying locales: `pytest tests/test_integrity.py`.
- **Generated artifacts**: Treat `voxvera/resources/bin/` as local build output, not source files. Release binaries belong in GitHub Releases, not hand-edited repo state.
- **Style**: Follow the existing coding style (PEP 8 for Python).
- **Documentation**: If adding a new feature, update the master templates in `docs/templates/` and run `voxvera build-docs`.
---
Together, we can ensure that truth remains accessible to everyone, everywhere.
docs/fr/docker.md
-48
View File
@@ -1,48 +0,0 @@
# Docker Usage
Experimental: the container path is not yet a production-grade hidden-service deployment target. Linux with `systemd --user` remains the supported persistent-host environment.
A prebuilt image containing Tor, OnionShare and the `voxvera` CLI is published to
`ghcr.io/voxvera/voxvera`.
```bash
# pull the image
docker pull ghcr.io/voxvera/voxvera:latest
# run the experimental container with flyers stored in ./flyers
mkdir -p flyers
docker run -d \
--name voxvera \
--restart unless-stopped \
-v "$(pwd)/flyers:/flyers" \
ghcr.io/voxvera/voxvera:latest
```
The container now uses a dedicated entrypoint that:
- stores runtime state under `/flyers`
- seeds `/flyers/config.json` if needed
- starts an in-container Tor daemon on `127.0.0.1:9050/9051`
- bootstraps a default site when `/flyers/host` is empty
- runs `voxvera start-all` on startup and retries it periodically
- exposes a container healthcheck based on `voxvera doctor --json`
Useful commands:
```bash
docker logs -f voxvera
docker exec -it voxvera voxvera doctor --json
docker exec -it voxvera voxvera autostart status --json
```
If you prefer Compose:
```yaml
services:
voxvera:
image: ghcr.io/voxvera/voxvera:latest
restart: unless-stopped
volumes:
- ./flyers:/flyers
```
Use this path for testing only until the container runtime and background recovery behavior are validated end-to-end.
docs/fr/templates.md
-14
View File
@@ -1,14 +0,0 @@
# Flyer Templates
Pre-built flyer templates live in the `templates/` directory. Use the CLI to copy one with:
```bash
voxvera init --template <name>
```
This will create a new folder under `dist/` named `<name>-<YYYYMMDD>` containing the template files.
Available templates:
- **blank** – minimal placeholder files, also used when extracting fields from a PDF.
- **voxvera** – example flyer showcasing the VoxVera project.
docs/fr/troubleshooting.md
-75
View File
@@ -1,75 +0,0 @@
# Troubleshooting
This page collects common issues encountered when hosting or accessing flyers.
## Tor connectivity
- Ensure Tor is allowed through your firewall. On systems using `ufw` you may need to run `sudo ufw allow tor`.
- Some networks block Tor entirely. If you cannot reach onion services, try connecting over a different network or use a Tor bridge.
## Supported deployment target
- The supported persistent-host setup is Linux with `systemd --user`.
- Windows, macOS, Docker, Flatpak, AppImage, Homebrew, and Chocolatey are currently experimental and may not recover hosting automatically after reboot or network interruptions.
## Tor port detection
`voxvera serve` auto-detects Tor by probing common ports (9050/9150 for SOCKS, 9051/9151 for control). If detection fails -- for example when Tor runs on non-standard ports -- you can override with environment variables:
```bash
TOR_SOCKS_PORT=19050 TOR_CONTROL_PORT=19051 voxvera serve
```
If no running Tor is found, the defaults (9050/9051) are used and OnionShare will attempt to connect on those ports.
## Firewall rules
- If `voxvera serve` fails to start OnionShare, verify that outbound connections on ports 9001 and 80 are permitted.
- Corporate or university firewalls can block the hidden service ports required by Tor.
## SELinux
- On SELinux-enabled distributions you may see `permission denied` errors when OnionShare writes to the `host` directory.
- Run `sudo chcon -Rt svirt_sandbox_file_t host` or disable SELinux enforcement for the folder.
## OnionShare crashes
If `voxvera serve` prints "OnionShare exited unexpectedly", check the log file
`host/<folder_name>/onionshare.log` for details. Common causes:
- Tor is not running (`sudo systemctl start tor`)
- A port conflict with another service
- Missing `onionshare-cli` (run `voxvera check`)
## Onion URL changed unexpectedly
The onion URL is tied to the Ed25519 keypair stored in
`host/<folder_name>/.onionshare-session`. If this file is deleted, a new
keypair (and URL) will be generated on the next `voxvera serve`. The
`voxvera import` command preserves this file automatically, but manual
deletion of the `host/` directory will destroy it.
## Hosting does not return after reboot or network loss
On Linux, install or verify the recovery timer:
```bash
voxvera autostart
systemctl --user status voxvera-start.timer
systemctl --user status voxvera-start.service
```
The supported recovery path is the recurring `systemd --user` timer, which reruns `voxvera start-all` every few minutes.
## QR codes not generated
If `voxvera build` reports "No URLs configured yet", this is expected before the first `voxvera serve`. QR codes for tear-off links are generated automatically once the .onion address is known. QR codes for the content link are generated if you provided a URL during `voxvera init`.
## Electron GUI
If `npm start` fails with `spawn voxvera ENOENT`, the `voxvera` command is not in your `PATH`. Install it with `pipx install git+https://github.com/PR0M3TH3AN/VoxVera.git` or run `./install.sh` from the repository.
## Missing dependencies
Run `voxvera check` to verify your setup. The command checks for required
Python packages (`qrcode`, `Pillow`, `jsmin`, `htmlmin`, `pypdf`) and
external tools (`onionshare-cli`), then prints a summary of anything
missing. To install everything:
```bash
# Recommended: use the install script (handles Tor + OnionShare too)
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
# Or reinstall just the Python package
pipx install --force 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
```
docs/fr/usage.md
-130
View File
@@ -1,130 +0,0 @@
# Utilisation détaillée
Ce guide couvre les flux de travail CLI courants. Consultez `docs/docker.md` pour les instructions Docker et `docs/templates.md` pour les modèles de flyers disponibles.
## Prérequis
VoxVera est conçu pour être hautement portable et nécessite un minimum de dépendances système.
### 1. Binaires autonomes (Recommandé)
Vous pouvez télécharger des binaires autonomes sans dépendance pour votre système d'exploitation :
- **Linux :** `voxvera-linux`
- **Windows :** `voxvera-windows.exe`
- **macOS :** `voxvera-macos`
Ces binaires incluent tout le nécessaire pour exécuter VoxVera (sauf `onionshare-cli`).
### 2. Installateur en une ligne
Alternativement, installez via notre script automatisé :
```bash
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
```
### 3. Installation Python manuelle
Si vous préférez exécuter à partir des sources :
```bash
pipx install 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
sudo apt install tor onionshare-cli # Debian/Ubuntu
```
## Étape par étape
1. **Initialiser :** Exécutez `voxvera init` et suivez les instructions. Il vous sera demandé de choisir votre langue en premier.
2. **Construire :** Générez les fichiers du flyer. Chaque construction crée automatiquement un `voxvera-portable.zip` dans le dossier du flyer, permettant aux autres de télécharger l'outil complet directement depuis votre flyer.
```bash
voxvera build
```
3. **Servir :** Publiez le flyer sur Tor :
```bash
voxvera serve
```
Ceci détecte automatiquement votre instance Tor, démarre OnionShare et écrit l'adresse .onion générée dans les liens détachables du flyer.
## Support linguistique
VoxVera est entièrement localisé. Vous pouvez changer votre préférence linguistique de manière permanente en utilisant soit le sélecteur interactif, soit un raccourci direct :
- **Sélecteur interactif :** `voxvera lang`
- **Raccourci direct :** `voxvera --lang fr` (définit la préférence sur le français)
### Langues supportées :
- **Anglais :** `en`
- **Espagnol :** `es` (alias : `--idioma`)
- **Allemand :** `de` (alias : `--sprache`)
- **Français :** `fr`
Vous pouvez également forcer une langue spécifique pour une seule commande sans changer votre préférence permanente :
- **Anglais :** `voxvera --lang en check`
- **Français :** `voxvera --lang fr check`
Les flyers générés détectent automatiquement la langue du navigateur du visiteur et adaptent le texte de l'interface en conséquence.
## Gestion des serveurs
Gérez plusieurs flyers et leurs identités Tor à partir d'un seul menu interactif :
```bash
voxvera manage
```
Fonctionnalités :
- **--- Créer un nouveau site/flyer ---** : Démarre la séquence de configuration complète.
- **--- Démarrer tous les sites ---** : Lance ou arrête tous les flyers de votre flotte en une seule fois.
- **Statut en temps réel** : Visualisez les URL .onion actives et les indicateurs de progression de l'amorçage Tor.
- **Contrôle individuel** : Exporter en Zip des sites spécifiques vers ZIP ou supprimez-les.
## Mise en miroir universelle (Distribution virale)
Pour garantir que VoxVera reste accessible même si les dépôts centraux sont censurés, chaque flyer agit comme un miroir pour l'outil.
Lorsque vous hébergez un flyer, le bouton **"Télécharger l'outil et le code"** sur la page d'accueil fournit un `voxvera-portable.zip` contenant :
- Le code source complet et toutes les langues supportées.
- Toutes les dépendances Python (pré-vendues).
- Les binaires Tor multiplateformes.
Cela permet à quiconque scanne votre flyer de devenir un nouveau distributeur de l'outil VoxVera.
## Exportation & Sauvegarde
Sauvegardez vos identités Tor uniques (pour que votre URL .onion ne change jamais) ou déplacez vos flyers vers une autre machine.
- **Exporter un seul site** : `voxvera export <nom_du_dossier>`
- **Exporter tous les sites** : `voxvera export-all`
**Lieu de stockage :** Toutes les exportations sont sauvegardées dans `~/voxvera-exports/` sur toutes les plateformes.
## Importation & Récupération
Restaurez toute votre configuration sur une nouvelle machine en déplaçant vos fichiers ZIP vers `~/voxvera-exports/` et en exécutant :
```bash
voxvera import-multiple
```
## Portabilité & Utilisation hors ligne
Si vous devez exécuter VoxVera sur une machine sans accès à Internet, vous pouvez d'abord "vendeuriser" les dépendances :
```bash
voxvera vendorize
```
Ceci télécharge toutes les bibliothèques Python requises dans `voxvera/vendor/`. L'outil donnera alors la priorité à ces fichiers locaux, lui permettant de s'exécuter sans `pip install`.
## Importation par lot (JSON)
Pour générer en masse des flyers à partir de plusieurs fichiers de configuration JSON, placez-les dans le répertoire `imports/` et exécutez :
```bash
voxvera batch-import
```
## Comment fonctionnent les URL
Chaque flyer possède deux URL distinctes :
- **Lien détachable** (auto-généré) : L'adresse .onion où le flyer est hébergé.
- **Lien de contenu** (configuré par l'utilisateur) : Une URL externe pointant vers un site web, une vidéo ou un téléchargement.
Vous n'avez pas besoin de saisir manuellement l'adresse .onion ; VoxVera s'en occupe automatiquement pendant la phase `serve`.
docs/he/AGENTS.md
-42
View File
@@ -1,42 +0,0 @@
# AI Agent Instructions for VoxVera
This guide is for AI agents (like Gemini, Claude, or GPT) contributing to the VoxVera project. Follow these protocols to maintain the architectural integrity and multi-language support.
## Core Mandates
1. **Security-First**: VoxVera is a Tor-based tool. Never suggest features that leak IP addresses or use non-Tor external resources (CDNs, etc.).
2. **Local-First**: All assets (fonts, dependencies, binaries) must be self-contained within the `voxvera/` package to support the Universal Mirroring model.
3. **Tokenized UI**: Never hardcode user-facing strings. Always add them to `voxvera/locales/en.json` and use the `t('cli.token')` helper.
4. **Markdown Redaction**: Use `~~text~~` in locale JSONs for strike-through effects. Both the build system and the JS engine handle the conversion to `<span class="redacted">` automatically.
5. **Visual Width Testing**: When modifying UI or adding languages, verify that long or complex strings (e.g., Hindi ligatures or CJK characters) do not exceed the visual unit limits defined in the CLI.
## Localization Protocol
When adding a new language or updating an existing one:
- **CLI/Flyers**: Update `voxvera/locales/{lang}.json`. Include `meta`, `cli`, `web`, and `landing` categories.
- **Landing Page**:
- Directly update the `const locales` object in `site/index.html`.
- **Crucial**: Run `voxvera build-site` to generate the latest portable bundle and refresh the pre-rendered HTML.
- **Documentation**:
- Master templates live in `docs/templates/`.
- Localized overrides live in `voxvera/locales/{lang}/docs/`.
- **Crucial**: After any change to locales or templates, you MUST run `voxvera build-docs` to synchronize the output in `docs/{en,es,de}/`.
## Universal Mirroring
VoxVera propagates through its own flyers.
- Every `voxvera build` and `voxvera build-site` generates `voxvera-portable.zip`.
- If you modify the core source code, ensure the `bundle_portable` function in `voxvera/cli.py` still correctly captures all necessary directories (especially `vendor/`, `locales/`, and `resources/`).
## Verification Checklist
Before finishing a task, ensure you have:
1. Run unit tests: `pytest tests/test_cli.py`.
2. Verified the localization: `voxvera --lang {lang} check`.
3. Rebuilt the documentation: `voxvera build-docs`.
4. Synchronized the public site: `voxvera build-site`.
5. Verified the portable bundle exists: `ls -l voxvera/host/*/download/voxvera-portable.zip` and `ls -l site/download/voxvera-portable.zip`.
---
Follow these rules to ensure VoxVera remains a robust, viral, and decentralized tool for truth.
docs/he/CONTRIBUTING.md
-47
View File
@@ -1,47 +0,0 @@
# Contributing to VoxVera
Thank you for your interest in contributing to VoxVera! This project aims to be a global, censorship-resistant tool, and your help—especially with translations—is vital.
## Adding a New Language
VoxVera uses a centralized token system for the CLI and Web components, and a template-based system for Documentation. To add a new language (e.g., French/`fr`), follow this checklist:
### 1. The Token File
Create a new JSON file in `voxvera/locales/{lang_code}.json`.
- Use `en.json` as your master template.
- **`meta`**: Include the native language name and a flag emoji.
- **`cli`**: Translate all strings used in the terminal interface.
- **`web`**: Translate strings used on the generated landing pages and flyers.
- **`landing`**: Translate the specific content for the official VoxVera website.
- **Formatting**: You can use Markdown-style strike-throughs (`~~redacted text~~`) in any of these strings; they will be automatically converted to the stylized "redacted" effect on the flyers.
### 2. The Landing Page
The main landing page is generated from the shared template and locale files.
- Add your language in `voxvera/locales/{lang_code}.json`.
- Do **not** edit `site/index.html` directly; it is generated output.
- Run `voxvera build-site` to refresh the public assets and inject your new locale into the generated HTML.
### 3. Documentation
VoxVera uses the **Doc-Sync Engine** to keep manuals in sync.
- Create localized Markdown files in `voxvera/locales/{lang_code}/docs/`.
- Use the templates in `docs/templates/` as your guide.
- You can use `cli.token_name` to reference terminal commands automatically.
### 4. Build and Verify
Run the following commands to verify your changes:
- `voxvera --lang {lang_code} check` (Verify CLI translation)
- `voxvera build-docs` (Generate localized manuals)
- `voxvera build-site` (Synchronize the public website and generate the latest portable bundle)
- Open the generated `site/index.html` in a browser and test the language switcher.
## Code Contributions
- **Dependencies**: if you add a new Python library to `requirements.txt`, you MUST run `voxvera vendorize` to include it in the portable distribution.
- **Layout Integrity**: VoxVera uses visual width validation. If you add new UI elements, ensure they respect the physical boundaries of an 8.5"x11" flyer.
- **Tests**: Ensure all tests pass: `pytest tests/`. Run the integrity suite specifically when modifying locales: `pytest tests/test_integrity.py`.
- **Generated artifacts**: Treat `voxvera/resources/bin/` as local build output, not source files. Release binaries belong in GitHub Releases, not hand-edited repo state.
- **Style**: Follow the existing coding style (PEP 8 for Python).
- **Documentation**: If adding a new feature, update the master templates in `docs/templates/` and run `voxvera build-docs`.
---
Together, we can ensure that truth remains accessible to everyone, everywhere.
docs/he/docker.md
-48
View File
@@ -1,48 +0,0 @@
# Docker Usage
Experimental: the container path is not yet a production-grade hidden-service deployment target. Linux with `systemd --user` remains the supported persistent-host environment.
A prebuilt image containing Tor, OnionShare and the `voxvera` CLI is published to
`ghcr.io/voxvera/voxvera`.
```bash
# pull the image
docker pull ghcr.io/voxvera/voxvera:latest
# run the experimental container with flyers stored in ./flyers
mkdir -p flyers
docker run -d \
--name voxvera \
--restart unless-stopped \
-v "$(pwd)/flyers:/flyers" \
ghcr.io/voxvera/voxvera:latest
```
The container now uses a dedicated entrypoint that:
- stores runtime state under `/flyers`
- seeds `/flyers/config.json` if needed
- starts an in-container Tor daemon on `127.0.0.1:9050/9051`
- bootstraps a default site when `/flyers/host` is empty
- runs `voxvera start-all` on startup and retries it periodically
- exposes a container healthcheck based on `voxvera doctor --json`
Useful commands:
```bash
docker logs -f voxvera
docker exec -it voxvera voxvera doctor --json
docker exec -it voxvera voxvera autostart status --json
```
If you prefer Compose:
```yaml
services:
voxvera:
image: ghcr.io/voxvera/voxvera:latest
restart: unless-stopped
volumes:
- ./flyers:/flyers
```
Use this path for testing only until the container runtime and background recovery behavior are validated end-to-end.
docs/he/templates.md
-14
View File
@@ -1,14 +0,0 @@
# Flyer Templates
Pre-built flyer templates live in the `templates/` directory. Use the CLI to copy one with:
```bash
voxvera init --template <name>
```
This will create a new folder under `dist/` named `<name>-<YYYYMMDD>` containing the template files.
Available templates:
- **blank** – minimal placeholder files, also used when extracting fields from a PDF.
- **voxvera** – example flyer showcasing the VoxVera project.
docs/he/troubleshooting.md
-75
View File
@@ -1,75 +0,0 @@
# Troubleshooting
This page collects common issues encountered when hosting or accessing flyers.
## Tor connectivity
- Ensure Tor is allowed through your firewall. On systems using `ufw` you may need to run `sudo ufw allow tor`.
- Some networks block Tor entirely. If you cannot reach onion services, try connecting over a different network or use a Tor bridge.
## Supported deployment target
- The supported persistent-host setup is Linux with `systemd --user`.
- Windows, macOS, Docker, Flatpak, AppImage, Homebrew, and Chocolatey are currently experimental and may not recover hosting automatically after reboot or network interruptions.
## Tor port detection
`voxvera serve` auto-detects Tor by probing common ports (9050/9150 for SOCKS, 9051/9151 for control). If detection fails -- for example when Tor runs on non-standard ports -- you can override with environment variables:
```bash
TOR_SOCKS_PORT=19050 TOR_CONTROL_PORT=19051 voxvera serve
```
If no running Tor is found, the defaults (9050/9051) are used and OnionShare will attempt to connect on those ports.
## Firewall rules
- If `voxvera serve` fails to start OnionShare, verify that outbound connections on ports 9001 and 80 are permitted.
- Corporate or university firewalls can block the hidden service ports required by Tor.
## SELinux
- On SELinux-enabled distributions you may see `permission denied` errors when OnionShare writes to the `host` directory.
- Run `sudo chcon -Rt svirt_sandbox_file_t host` or disable SELinux enforcement for the folder.
## OnionShare crashes
If `voxvera serve` prints "OnionShare exited unexpectedly", check the log file
`host/<folder_name>/onionshare.log` for details. Common causes:
- Tor is not running (`sudo systemctl start tor`)
- A port conflict with another service
- Missing `onionshare-cli` (run `voxvera check`)
## Onion URL changed unexpectedly
The onion URL is tied to the Ed25519 keypair stored in
`host/<folder_name>/.onionshare-session`. If this file is deleted, a new
keypair (and URL) will be generated on the next `voxvera serve`. The
`voxvera import` command preserves this file automatically, but manual
deletion of the `host/` directory will destroy it.
## Hosting does not return after reboot or network loss
On Linux, install or verify the recovery timer:
```bash
voxvera autostart
systemctl --user status voxvera-start.timer
systemctl --user status voxvera-start.service
```
The supported recovery path is the recurring `systemd --user` timer, which reruns `voxvera start-all` every few minutes.
## QR codes not generated
If `voxvera build` reports "No URLs configured yet", this is expected before the first `voxvera serve`. QR codes for tear-off links are generated automatically once the .onion address is known. QR codes for the content link are generated if you provided a URL during `voxvera init`.
## Electron GUI
If `npm start` fails with `spawn voxvera ENOENT`, the `voxvera` command is not in your `PATH`. Install it with `pipx install git+https://github.com/PR0M3TH3AN/VoxVera.git` or run `./install.sh` from the repository.
## Missing dependencies
Run `voxvera check` to verify your setup. The command checks for required
Python packages (`qrcode`, `Pillow`, `jsmin`, `htmlmin`, `pypdf`) and
external tools (`onionshare-cli`), then prints a summary of anything
missing. To install everything:
```bash
# Recommended: use the install script (handles Tor + OnionShare too)
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
# Or reinstall just the Python package
pipx install --force 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
```
docs/he/usage.md
-156
View File
@@ -1,156 +0,0 @@
# Detailed Usage
This guide covers common CLI workflows. See `docs/docker.md` for Docker instructions and `docs/templates.md` for available flyer templates.
## Prerequisites
VoxVera is designed to be highly portable. You can run it directly from the source code on any platform with Python installed.
Linux with `systemd --user` is the supported persistent-host environment. Windows, macOS, Docker, Flatpak, AppImage, Homebrew, and Chocolatey are currently experimental and should not yet be treated as equally reliable hidden-service deployment targets.
### 1. Automated Install (Recommended)
The easiest way to install VoxVera is using the Linux-first installer script:
**Linux / macOS:**
```bash
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
```
On Linux, this also installs the recurring recovery timer used to retry hidden-service startup after boot and after missed/offline periods.
**Windows (PowerShell):**
```powershell
irm https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.ps1 | iex
```
The Windows installer is experimental and does not yet guarantee production-ready background hosting behavior.
### 2. Manual Source Install
If you have downloaded the source code ZIP:
1. **Extract** the ZIP file.
2. **Open a terminal** in the extracted folder.
3. **Run the setup script**:
- **Linux/macOS:** `./setup.sh`
- **Windows:** `.\voxvera-install.sh` (or run `python -m pip install .`)
## Uninstallation
If you wish to remove VoxVera from your system, you can use the provided uninstall scripts from the source directory. This will safely remove the CLI tool and any downloaded dependencies.
- **Linux / macOS:** Run `./uninstall.sh`
- **Windows (PowerShell):** Run `.\uninstall.ps1`
*Note: Uninstallation will not delete your generated flyers or your `.onion` keys stored in the `~/voxvera-exports` or local `host/` folders.*
## Step-by-Step
1. **Initialize:** Run `voxvera init` and follow the prompts. You will be asked to select your language first.
2. **Build:** Generate the flyer assets. Every build automatically creates a `voxvera-portable.zip` in the flyer's folder, allowing others to download the full tool directly from your flyer.
```bash
voxvera build
```
3. **Serve:** Publish the flyer over Tor:
```bash
voxvera serve
```
This automatically detects your Tor instance, starts OnionShare, and writes the generated .onion address into the flyer's tear-off links.
### Persistent Hosting On Linux
For a machine that should resume hosting automatically after boot or after being offline, install the autostart recovery timer:
```bash
voxvera autostart
```
This installs a `systemd --user` timer that reruns `voxvera start-all` every few minutes. The retry loop is the supported way to recover hidden-service hosting after suspend, reboot, or temporary network loss.
## Language Support
VoxVera is fully localized. You can change your language preference permanently using either the interactive selector or a direct shortcut:
- **Interactive Selector:** `voxvera lang`
- **Direct Shortcut:** `voxvera --lang de` (sets preference to German)
### Supported Languages:
- **English:** `en`
- **Spanish:** `es` (alias: `--idioma`)
- **German:** `de` (alias: `--sprache`)
You can also force a specific language for a single command without changing your permanent preference:
- **English:** `voxvera --lang en check`
- **German:** `voxvera --sprache de check`
- **Spanish:** `voxvera --idioma es check`
The generated flyers automatically detect the visitor's browser language and switch the UI text accordingly.
## Server Management
Manage multiple flyers and their Tor identities from a single interactive menu:
```bash
voxvera manage
```
Features:
- **--- צור אתר/פלייר חדש ---**: Start the full setup sequence.
- **--- הפעל את כל האתרים ---**: Launch or shut down every flyer in your fleet at once.
- **Real-time Status**: View active `.onion` URLs and Tor bootstrapping progress indicators.
- **Individual Control**: ייצא ל-Zip specific sites to ZIP or delete them.
## Universal Mirroring (Viral Distribution)
To ensure VoxVera remains accessible even if central repositories are censored, every flyer acts as a mirror for the tool.
When you host a flyer, the **"הורד כלי וקוד מקור"** button on the landing page provides a `voxvera-source.zip` containing:
- The full source code and all supported languages.
- Installation and setup scripts for all platforms.
- Complete documentation and templates.
To keep the mirrored download practical for low-bandwidth redistribution, the
source archive does not ship pre-downloaded Tor binaries. Normal installer and
release builds still fetch or bundle those artifacts separately.
This allows anyone who scans your flyer to become a new distributor of the VoxVera tool.
## Export & Backup
Back up your unique Tor identities (so your `.onion` URL never changes) or move your flyers to another machine.
- **Export a single site**: `voxvera export <folder_name>`
- **Export all sites**: `voxvera export-all`
**Storage location:** All exports are saved to `~/voxvera-exports/` on all platforms.
## Import & Recovery
Restore your entire setup on a new machine by moving your ZIP files to `~/voxvera-exports/` and running:
```bash
voxvera import-multiple
```
## Portability & Offline Use
If you need to run VoxVera on a machine without internet access, you can "vendorize" the dependencies first:
```bash
voxvera vendorize
```
This downloads all required Python libraries into `voxvera/vendor/`. The tool will then prioritize these local files, allowing it to run without `pip install`.
## Batch Import (JSON)
To bulk-generate flyers from multiple JSON configuration files, place them in the `imports/` directory and run:
```bash
voxvera batch-import
```
## How URLs Work
Each flyer has two separate URLs:
- **Tear-off link** (auto-generated): The .onion address where the flyer is hosted.
- **Content link** (user-configured): An external URL pointing to a website, video, or download.
You do not need to manually enter the .onion address; VoxVera handles this automatically during the `serve` phase.
docs/hi/AGENTS.md
-42
View File
@@ -1,42 +0,0 @@
# AI Agent Instructions for VoxVera
This guide is for AI agents (like Gemini, Claude, or GPT) contributing to the VoxVera project. Follow these protocols to maintain the architectural integrity and multi-language support.
## Core Mandates
1. **Security-First**: VoxVera is a Tor-based tool. Never suggest features that leak IP addresses or use non-Tor external resources (CDNs, etc.).
2. **Local-First**: All assets (fonts, dependencies, binaries) must be self-contained within the `voxvera/` package to support the Universal Mirroring model.
3. **Tokenized UI**: Never hardcode user-facing strings. Always add them to `voxvera/locales/en.json` and use the `t('cli.token')` helper.
4. **Markdown Redaction**: Use `~~text~~` in locale JSONs for strike-through effects. Both the build system and the JS engine handle the conversion to `<span class="redacted">` automatically.
5. **Visual Width Testing**: When modifying UI or adding languages, verify that long or complex strings (e.g., Hindi ligatures or CJK characters) do not exceed the visual unit limits defined in the CLI.
## Localization Protocol
When adding a new language or updating an existing one:
- **CLI/Flyers**: Update `voxvera/locales/{lang}.json`. Include `meta`, `cli`, `web`, and `landing` categories.
- **Landing Page**:
- Directly update the `const locales` object in `site/index.html`.
- **Crucial**: Run `voxvera build-site` to generate the latest portable bundle and refresh the pre-rendered HTML.
- **Documentation**:
- Master templates live in `docs/templates/`.
- Localized overrides live in `voxvera/locales/{lang}/docs/`.
- **Crucial**: After any change to locales or templates, you MUST run `voxvera build-docs` to synchronize the output in `docs/{en,es,de}/`.
## Universal Mirroring
VoxVera propagates through its own flyers.
- Every `voxvera build` and `voxvera build-site` generates `voxvera-portable.zip`.
- If you modify the core source code, ensure the `bundle_portable` function in `voxvera/cli.py` still correctly captures all necessary directories (especially `vendor/`, `locales/`, and `resources/`).
## Verification Checklist
Before finishing a task, ensure you have:
1. Run unit tests: `pytest tests/test_cli.py`.
2. Verified the localization: `voxvera --lang {lang} check`.
3. Rebuilt the documentation: `voxvera build-docs`.
4. Synchronized the public site: `voxvera build-site`.
5. Verified the portable bundle exists: `ls -l voxvera/host/*/download/voxvera-portable.zip` and `ls -l site/download/voxvera-portable.zip`.
---
Follow these rules to ensure VoxVera remains a robust, viral, and decentralized tool for truth.
docs/hi/CONTRIBUTING.md
-47
View File
@@ -1,47 +0,0 @@
# Contributing to VoxVera
Thank you for your interest in contributing to VoxVera! This project aims to be a global, censorship-resistant tool, and your help—especially with translations—is vital.
## Adding a New Language
VoxVera uses a centralized token system for the CLI and Web components, and a template-based system for Documentation. To add a new language (e.g., French/`fr`), follow this checklist:
### 1. The Token File
Create a new JSON file in `voxvera/locales/{lang_code}.json`.
- Use `en.json` as your master template.
- **`meta`**: Include the native language name and a flag emoji.
- **`cli`**: Translate all strings used in the terminal interface.
- **`web`**: Translate strings used on the generated landing pages and flyers.
- **`landing`**: Translate the specific content for the official VoxVera website.
- **Formatting**: You can use Markdown-style strike-throughs (`~~redacted text~~`) in any of these strings; they will be automatically converted to the stylized "redacted" effect on the flyers.
### 2. The Landing Page
The main landing page is generated from the shared template and locale files.
- Add your language in `voxvera/locales/{lang_code}.json`.
- Do **not** edit `site/index.html` directly; it is generated output.
- Run `voxvera build-site` to refresh the public assets and inject your new locale into the generated HTML.
### 3. Documentation
VoxVera uses the **Doc-Sync Engine** to keep manuals in sync.
- Create localized Markdown files in `voxvera/locales/{lang_code}/docs/`.
- Use the templates in `docs/templates/` as your guide.
- You can use `cli.token_name` to reference terminal commands automatically.
### 4. Build and Verify
Run the following commands to verify your changes:
- `voxvera --lang {lang_code} check` (Verify CLI translation)
- `voxvera build-docs` (Generate localized manuals)
- `voxvera build-site` (Synchronize the public website and generate the latest portable bundle)
- Open the generated `site/index.html` in a browser and test the language switcher.
## Code Contributions
- **Dependencies**: if you add a new Python library to `requirements.txt`, you MUST run `voxvera vendorize` to include it in the portable distribution.
- **Layout Integrity**: VoxVera uses visual width validation. If you add new UI elements, ensure they respect the physical boundaries of an 8.5"x11" flyer.
- **Tests**: Ensure all tests pass: `pytest tests/`. Run the integrity suite specifically when modifying locales: `pytest tests/test_integrity.py`.
- **Generated artifacts**: Treat `voxvera/resources/bin/` as local build output, not source files. Release binaries belong in GitHub Releases, not hand-edited repo state.
- **Style**: Follow the existing coding style (PEP 8 for Python).
- **Documentation**: If adding a new feature, update the master templates in `docs/templates/` and run `voxvera build-docs`.
---
Together, we can ensure that truth remains accessible to everyone, everywhere.
docs/hi/docker.md
-48
View File
@@ -1,48 +0,0 @@
# Docker Usage
Experimental: the container path is not yet a production-grade hidden-service deployment target. Linux with `systemd --user` remains the supported persistent-host environment.
A prebuilt image containing Tor, OnionShare and the `voxvera` CLI is published to
`ghcr.io/voxvera/voxvera`.
```bash
# pull the image
docker pull ghcr.io/voxvera/voxvera:latest
# run the experimental container with flyers stored in ./flyers
mkdir -p flyers
docker run -d \
--name voxvera \
--restart unless-stopped \
-v "$(pwd)/flyers:/flyers" \
ghcr.io/voxvera/voxvera:latest
```
The container now uses a dedicated entrypoint that:
- stores runtime state under `/flyers`
- seeds `/flyers/config.json` if needed
- starts an in-container Tor daemon on `127.0.0.1:9050/9051`
- bootstraps a default site when `/flyers/host` is empty
- runs `voxvera start-all` on startup and retries it periodically
- exposes a container healthcheck based on `voxvera doctor --json`
Useful commands:
```bash
docker logs -f voxvera
docker exec -it voxvera voxvera doctor --json
docker exec -it voxvera voxvera autostart status --json
```
If you prefer Compose:
```yaml
services:
voxvera:
image: ghcr.io/voxvera/voxvera:latest
restart: unless-stopped
volumes:
- ./flyers:/flyers
```
Use this path for testing only until the container runtime and background recovery behavior are validated end-to-end.
docs/hi/templates.md
-14
View File
@@ -1,14 +0,0 @@
# Flyer Templates
Pre-built flyer templates live in the `templates/` directory. Use the CLI to copy one with:
```bash
voxvera init --template <name>
```
This will create a new folder under `dist/` named `<name>-<YYYYMMDD>` containing the template files.
Available templates:
- **blank** – minimal placeholder files, also used when extracting fields from a PDF.
- **voxvera** – example flyer showcasing the VoxVera project.
docs/hi/troubleshooting.md
-75
View File
@@ -1,75 +0,0 @@
# Troubleshooting
This page collects common issues encountered when hosting or accessing flyers.
## Tor connectivity
- Ensure Tor is allowed through your firewall. On systems using `ufw` you may need to run `sudo ufw allow tor`.
- Some networks block Tor entirely. If you cannot reach onion services, try connecting over a different network or use a Tor bridge.
## Supported deployment target
- The supported persistent-host setup is Linux with `systemd --user`.
- Windows, macOS, Docker, Flatpak, AppImage, Homebrew, and Chocolatey are currently experimental and may not recover hosting automatically after reboot or network interruptions.
## Tor port detection
`voxvera serve` auto-detects Tor by probing common ports (9050/9150 for SOCKS, 9051/9151 for control). If detection fails -- for example when Tor runs on non-standard ports -- you can override with environment variables:
```bash
TOR_SOCKS_PORT=19050 TOR_CONTROL_PORT=19051 voxvera serve
```
If no running Tor is found, the defaults (9050/9051) are used and OnionShare will attempt to connect on those ports.
## Firewall rules
- If `voxvera serve` fails to start OnionShare, verify that outbound connections on ports 9001 and 80 are permitted.
- Corporate or university firewalls can block the hidden service ports required by Tor.
## SELinux
- On SELinux-enabled distributions you may see `permission denied` errors when OnionShare writes to the `host` directory.
- Run `sudo chcon -Rt svirt_sandbox_file_t host` or disable SELinux enforcement for the folder.
## OnionShare crashes
If `voxvera serve` prints "OnionShare exited unexpectedly", check the log file
`host/<folder_name>/onionshare.log` for details. Common causes:
- Tor is not running (`sudo systemctl start tor`)
- A port conflict with another service
- Missing `onionshare-cli` (run `voxvera check`)
## Onion URL changed unexpectedly
The onion URL is tied to the Ed25519 keypair stored in
`host/<folder_name>/.onionshare-session`. If this file is deleted, a new
keypair (and URL) will be generated on the next `voxvera serve`. The
`voxvera import` command preserves this file automatically, but manual
deletion of the `host/` directory will destroy it.
## Hosting does not return after reboot or network loss
On Linux, install or verify the recovery timer:
```bash
voxvera autostart
systemctl --user status voxvera-start.timer
systemctl --user status voxvera-start.service
```
The supported recovery path is the recurring `systemd --user` timer, which reruns `voxvera start-all` every few minutes.
## QR codes not generated
If `voxvera build` reports "No URLs configured yet", this is expected before the first `voxvera serve`. QR codes for tear-off links are generated automatically once the .onion address is known. QR codes for the content link are generated if you provided a URL during `voxvera init`.
## Electron GUI
If `npm start` fails with `spawn voxvera ENOENT`, the `voxvera` command is not in your `PATH`. Install it with `pipx install git+https://github.com/PR0M3TH3AN/VoxVera.git` or run `./install.sh` from the repository.
## Missing dependencies
Run `voxvera check` to verify your setup. The command checks for required
Python packages (`qrcode`, `Pillow`, `jsmin`, `htmlmin`, `pypdf`) and
external tools (`onionshare-cli`), then prints a summary of anything
missing. To install everything:
```bash
# Recommended: use the install script (handles Tor + OnionShare too)
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
# Or reinstall just the Python package
pipx install --force 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
```
docs/hi/usage.md
-130
View File
@@ -1,130 +0,0 @@
# विस्तृत उपयोग
यह गाइड सामान्य CLI वर्कफ्लो को कवर करती है। डॉकर निर्देशों के लिए `docs/docker.md` और उपलब्ध फ्लायर टेम्पलेट्स के लिए `docs/templates.md` देखें।
## पूर्वापेक्षाएँ (Prerequisites)
VoxVera को अत्यधिक पोर्टेबल बनाने के लिए डिज़ाइन किया गया है और इसके लिए न्यूनतम सिस्टम निर्भरता की आवश्यकता होती है।
### 1. स्टैंडअलोन बाइनरी (अनुशंसित)
आप अपने ऑपरेटिंग सिस्टम के लिए स्टैंडअलोन, शून्य-निर्भरता बाइनरी डाउनलोड कर सकते हैं:
- **Linux:** `voxvera-linux`
- **Windows:** `voxvera-windows.exe`
- **macOS:** `voxvera-macos`
इन बाइनरी में VoxVera चलाने के लिए आवश्यक सब कुछ शामिल है (`onionshare-cli` को छोड़कर)।
### 2. वन-लाइन इंस्टॉलर
वैकल्पिक रूप से, हमारी स्वचालित स्क्रिप्ट के माध्यम से इंस्टॉल करें:
```bash
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
```
### 3. मैनुअल पायथन इंस्टॉलेशन
यदि आप सोर्स से चलाना पसंद करते हैं:
```bash
pipx install 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
sudo apt install tor onionshare-cli # Debian/Ubuntu
```
## चरण-दर-चरण (Step-by-Step)
1. **आरंभ करें (Initialize):** `voxvera init` चलाएँ और संकेतों का पालन करें। आपसे सबसे पहले अपनी भाषा चुनने के लिए कहा जाएगा।
2. **बिल्ड (Build):** फ्लायर एसेट्स जेनरेट करें। प्रत्येक बिल्ड स्वचालित रूप से फ्लायर के फ़ोल्डर में एक `voxvera-portable.zip` बनाता है, जिससे अन्य लोग सीधे आपके फ्लायर से पूरा टूल डाउनलोड कर सकते हैं।
```bash
voxvera build
```
3. **सर्व (Serve):** फ्लायर को Tor पर प्रकाशित करें:
```bash
voxvera serve
```
यह स्वचालित रूप से आपके Tor इंस्टेंस का पता लगाता है, OnionShare शुरू करता है, और जेनरेट किए गए .onion एड्रेस को फ्लायर के टियर-ऑफ लिंक में लिख देता है।
## भाषा समर्थन (Language Support)
VoxVera पूरी तरह से स्थानीयकृत (localized) है। आप इंटरैक्टिव सेलेक्टर या सीधे शॉर्टकट का उपयोग करके अपनी भाषा प्राथमिकता को स्थायी रूप से बदल सकते हैं:
- **इंटरैक्टिव सेलेक्टर:** `voxvera lang`
- **सीधा शॉर्टकट:** `voxvera --lang hi` (प्राथमिकता को हिन्दी पर सेट करता है)
### समर्थित भाषाएं:
- **अंग्रेजी:** `en`
- **स्पेनिश:** `es` (उपनाम: `--idioma`)
- **जर्मन:** `de` (उपनाम: `--sprache`)
- **हिन्दी:** `hi`
आप अपनी स्थायी प्राथमिकता को बदले बिना किसी एक कमांड के लिए एक विशिष्ट भाषा को बाध्य (force) भी कर सकते हैं:
- **अंग्रेजी:** `voxvera --lang en check`
- **हिन्दी:** `voxvera --lang hi check`
जेनरेट किए गए फ्लायर्स स्वचालित रूप से विज़िटर की ब्राउज़र भाषा का पता लगाते हैं और उसके अनुसार UI टेक्स्ट बदलते हैं।
## सर्वर प्रबंधन (Server Management)
एक ही इंटरैक्टिव मेनू से कई फ्लायर्स और उनकी Tor पहचान प्रबंधित करें:
```bash
voxvera manage
```
विशेषताएं:
- **--- नई साइट/फ्लायर बनाएँ ---**: पूरा सेटअप अनुक्रम शुरू करें।
- **--- सभी साइटें शुरू करें ---**: अपने बेड़े के सभी फ्लायर्स को एक साथ शुरू या बंद करें।
- **वास्तविक समय स्थिति**: सक्रिय `.onion` URL और Tor बूटस्ट्रैपिंग प्रगति संकेतक देखें।
- **व्यक्तिगत नियंत्रण**: विशिष्ट साइटों को ZIP में ज़िप में निर्यात करें करें या उन्हें हटा दें।
## यूनिवर्सल मिररिंग (वायरल वितरण)
यह सुनिश्चित करने के लिए कि VoxVera केंद्रीय रिपॉजिटरी सेंसर होने पर भी सुलभ रहे, प्रत्येक फ्लायर टूल के लिए मिरर के रूप में कार्य करता है।
जब आप फ्लायर होस्ट करते हैं, तो लैंडिंग पेज पर **"टूल और कोड डाउनलोड करें"** बटन एक `voxvera-portable.zip` प्रदान करता है जिसमें शामिल हैं:
- पूरा सोर्स कोड और सभी समर्थित भाषाएं।
- सभी पायथन निर्भरताएँ (pre-vendored)।
- क्रॉस-प्लेटफ़ॉर्म Tor बाइनरी।
यह आपके फ्लायर को स्कैन करने वाले किसी भी व्यक्ति को VoxVera टूल का नया वितरक बनने की अनुमति देता है।
## निर्यात और बैकअप (Export & Backup)
अपनी अनूठी Tor पहचान का बैकअप लें (ताकि आपका `.onion` URL कभी न बदले) या अपने फ्लायर्स को दूसरी मशीन पर ले जाएं।
- **एकल साइट निर्यात करें**: `voxvera export <folder_name>`
- **सभी साइटें निर्यात करें**: `voxvera export-all`
**भंडारण स्थान:** सभी निर्यात सभी प्लेटफ़ॉर्म पर उपयोगकर्ता की होम डायरेक्टरी (`~/voxvera-exports/`) में ZIP फ़ाइलों के रूप में सहेजे जाते हैं।
## आयात और पुनर्प्राप्ति (Import & Recovery)
अपनी ZIP फ़ाइलों को `~/voxvera-exports/` में ले जाकर और चलाकर एक नई मशीन पर अपना पूरा सेटअप पुनर्स्थापित करें:
```bash
voxvera import-multiple
```
## पोर्टेबिलिटी और ऑफलाइन उपयोग
यदि आपको बिना इंटरनेट एक्सेस वाली मशीन पर VoxVera चलाने की आवश्यकता है, तो आप पहले निर्भरताओं को "वेंडराइज़" (vendorize) कर सकते हैं:
```bash
voxvera vendorize
```
यह `voxvera/vendor/` में सभी आवश्यक पायथन लाइब्रेरी डाउनलोड करता है। टूल फिर इन स्थानीय फ़ाइलों को प्राथमिकता देगा, जिससे यह `pip install` के बिना चल सकेगा।
## बैच आयात (JSON)
कई JSON कॉन्फ़िगरेशन फ़ाइलों से थोक में फ्लायर्स जेनरेट करने के लिए, उन्हें `imports/` डायरेक्टरी में रखें और चलाएँ:
```bash
voxvera batch-import
```
## URL कैसे काम करते हैं
प्रत्येक फ्लायर के दो अलग-अलग URL होते हैं:
- **टियर-ऑफ लिंक** (स्वचालित रूप से जेनरेट): वह .onion एड्रेस जहाँ फ्लायर होस्ट किया गया है।
- **सामग्री लिंक** (उपयोगकर्ता-कॉन्फ़िगर): वेबसाइट, वीडियो या डाउनलोड की ओर इशारा करने वाला एक बाहरी URL।
आपको मैन्युअल रूप से .onion एड्रेस दर्ज करने की आवश्यकता नहीं है; `serve` चरण के दौरान VoxVera इसे स्वचालित रूप से संभालता है।
docs/ja/AGENTS.md
-42
View File
@@ -1,42 +0,0 @@
# AI Agent Instructions for VoxVera
This guide is for AI agents (like Gemini, Claude, or GPT) contributing to the VoxVera project. Follow these protocols to maintain the architectural integrity and multi-language support.
## Core Mandates
1. **Security-First**: VoxVera is a Tor-based tool. Never suggest features that leak IP addresses or use non-Tor external resources (CDNs, etc.).
2. **Local-First**: All assets (fonts, dependencies, binaries) must be self-contained within the `voxvera/` package to support the Universal Mirroring model.
3. **Tokenized UI**: Never hardcode user-facing strings. Always add them to `voxvera/locales/en.json` and use the `t('cli.token')` helper.
4. **Markdown Redaction**: Use `~~text~~` in locale JSONs for strike-through effects. Both the build system and the JS engine handle the conversion to `<span class="redacted">` automatically.
5. **Visual Width Testing**: When modifying UI or adding languages, verify that long or complex strings (e.g., Hindi ligatures or CJK characters) do not exceed the visual unit limits defined in the CLI.
## Localization Protocol
When adding a new language or updating an existing one:
- **CLI/Flyers**: Update `voxvera/locales/{lang}.json`. Include `meta`, `cli`, `web`, and `landing` categories.
- **Landing Page**:
- Directly update the `const locales` object in `site/index.html`.
- **Crucial**: Run `voxvera build-site` to generate the latest portable bundle and refresh the pre-rendered HTML.
- **Documentation**:
- Master templates live in `docs/templates/`.
- Localized overrides live in `voxvera/locales/{lang}/docs/`.
- **Crucial**: After any change to locales or templates, you MUST run `voxvera build-docs` to synchronize the output in `docs/{en,es,de}/`.
## Universal Mirroring
VoxVera propagates through its own flyers.
- Every `voxvera build` and `voxvera build-site` generates `voxvera-portable.zip`.
- If you modify the core source code, ensure the `bundle_portable` function in `voxvera/cli.py` still correctly captures all necessary directories (especially `vendor/`, `locales/`, and `resources/`).
## Verification Checklist
Before finishing a task, ensure you have:
1. Run unit tests: `pytest tests/test_cli.py`.
2. Verified the localization: `voxvera --lang {lang} check`.
3. Rebuilt the documentation: `voxvera build-docs`.
4. Synchronized the public site: `voxvera build-site`.
5. Verified the portable bundle exists: `ls -l voxvera/host/*/download/voxvera-portable.zip` and `ls -l site/download/voxvera-portable.zip`.
---
Follow these rules to ensure VoxVera remains a robust, viral, and decentralized tool for truth.
docs/ja/CONTRIBUTING.md
-47
View File
@@ -1,47 +0,0 @@
# Contributing to VoxVera
Thank you for your interest in contributing to VoxVera! This project aims to be a global, censorship-resistant tool, and your help—especially with translations—is vital.
## Adding a New Language
VoxVera uses a centralized token system for the CLI and Web components, and a template-based system for Documentation. To add a new language (e.g., French/`fr`), follow this checklist:
### 1. The Token File
Create a new JSON file in `voxvera/locales/{lang_code}.json`.
- Use `en.json` as your master template.
- **`meta`**: Include the native language name and a flag emoji.
- **`cli`**: Translate all strings used in the terminal interface.
- **`web`**: Translate strings used on the generated landing pages and flyers.
- **`landing`**: Translate the specific content for the official VoxVera website.
- **Formatting**: You can use Markdown-style strike-throughs (`~~redacted text~~`) in any of these strings; they will be automatically converted to the stylized "redacted" effect on the flyers.
### 2. The Landing Page
The main landing page is generated from the shared template and locale files.
- Add your language in `voxvera/locales/{lang_code}.json`.
- Do **not** edit `site/index.html` directly; it is generated output.
- Run `voxvera build-site` to refresh the public assets and inject your new locale into the generated HTML.
### 3. Documentation
VoxVera uses the **Doc-Sync Engine** to keep manuals in sync.
- Create localized Markdown files in `voxvera/locales/{lang_code}/docs/`.
- Use the templates in `docs/templates/` as your guide.
- You can use `cli.token_name` to reference terminal commands automatically.
### 4. Build and Verify
Run the following commands to verify your changes:
- `voxvera --lang {lang_code} check` (Verify CLI translation)
- `voxvera build-docs` (Generate localized manuals)
- `voxvera build-site` (Synchronize the public website and generate the latest portable bundle)
- Open the generated `site/index.html` in a browser and test the language switcher.
## Code Contributions
- **Dependencies**: if you add a new Python library to `requirements.txt`, you MUST run `voxvera vendorize` to include it in the portable distribution.
- **Layout Integrity**: VoxVera uses visual width validation. If you add new UI elements, ensure they respect the physical boundaries of an 8.5"x11" flyer.
- **Tests**: Ensure all tests pass: `pytest tests/`. Run the integrity suite specifically when modifying locales: `pytest tests/test_integrity.py`.
- **Generated artifacts**: Treat `voxvera/resources/bin/` as local build output, not source files. Release binaries belong in GitHub Releases, not hand-edited repo state.
- **Style**: Follow the existing coding style (PEP 8 for Python).
- **Documentation**: If adding a new feature, update the master templates in `docs/templates/` and run `voxvera build-docs`.
---
Together, we can ensure that truth remains accessible to everyone, everywhere.
docs/ja/docker.md
-48
View File
@@ -1,48 +0,0 @@
# Docker Usage
Experimental: the container path is not yet a production-grade hidden-service deployment target. Linux with `systemd --user` remains the supported persistent-host environment.
A prebuilt image containing Tor, OnionShare and the `voxvera` CLI is published to
`ghcr.io/voxvera/voxvera`.
```bash
# pull the image
docker pull ghcr.io/voxvera/voxvera:latest
# run the experimental container with flyers stored in ./flyers
mkdir -p flyers
docker run -d \
--name voxvera \
--restart unless-stopped \
-v "$(pwd)/flyers:/flyers" \
ghcr.io/voxvera/voxvera:latest
```
The container now uses a dedicated entrypoint that:
- stores runtime state under `/flyers`
- seeds `/flyers/config.json` if needed
- starts an in-container Tor daemon on `127.0.0.1:9050/9051`
- bootstraps a default site when `/flyers/host` is empty
- runs `voxvera start-all` on startup and retries it periodically
- exposes a container healthcheck based on `voxvera doctor --json`
Useful commands:
```bash
docker logs -f voxvera
docker exec -it voxvera voxvera doctor --json
docker exec -it voxvera voxvera autostart status --json
```
If you prefer Compose:
```yaml
services:
voxvera:
image: ghcr.io/voxvera/voxvera:latest
restart: unless-stopped
volumes:
- ./flyers:/flyers
```
Use this path for testing only until the container runtime and background recovery behavior are validated end-to-end.
docs/ja/templates.md
-14
View File
@@ -1,14 +0,0 @@
# Flyer Templates
Pre-built flyer templates live in the `templates/` directory. Use the CLI to copy one with:
```bash
voxvera init --template <name>
```
This will create a new folder under `dist/` named `<name>-<YYYYMMDD>` containing the template files.
Available templates:
- **blank** – minimal placeholder files, also used when extracting fields from a PDF.
- **voxvera** – example flyer showcasing the VoxVera project.
docs/ja/troubleshooting.md
-75
View File
@@ -1,75 +0,0 @@
# Troubleshooting
This page collects common issues encountered when hosting or accessing flyers.
## Tor connectivity
- Ensure Tor is allowed through your firewall. On systems using `ufw` you may need to run `sudo ufw allow tor`.
- Some networks block Tor entirely. If you cannot reach onion services, try connecting over a different network or use a Tor bridge.
## Supported deployment target
- The supported persistent-host setup is Linux with `systemd --user`.
- Windows, macOS, Docker, Flatpak, AppImage, Homebrew, and Chocolatey are currently experimental and may not recover hosting automatically after reboot or network interruptions.
## Tor port detection
`voxvera serve` auto-detects Tor by probing common ports (9050/9150 for SOCKS, 9051/9151 for control). If detection fails -- for example when Tor runs on non-standard ports -- you can override with environment variables:
```bash
TOR_SOCKS_PORT=19050 TOR_CONTROL_PORT=19051 voxvera serve
```
If no running Tor is found, the defaults (9050/9051) are used and OnionShare will attempt to connect on those ports.
## Firewall rules
- If `voxvera serve` fails to start OnionShare, verify that outbound connections on ports 9001 and 80 are permitted.
- Corporate or university firewalls can block the hidden service ports required by Tor.
## SELinux
- On SELinux-enabled distributions you may see `permission denied` errors when OnionShare writes to the `host` directory.
- Run `sudo chcon -Rt svirt_sandbox_file_t host` or disable SELinux enforcement for the folder.
## OnionShare crashes
If `voxvera serve` prints "OnionShare exited unexpectedly", check the log file
`host/<folder_name>/onionshare.log` for details. Common causes:
- Tor is not running (`sudo systemctl start tor`)
- A port conflict with another service
- Missing `onionshare-cli` (run `voxvera check`)
## Onion URL changed unexpectedly
The onion URL is tied to the Ed25519 keypair stored in
`host/<folder_name>/.onionshare-session`. If this file is deleted, a new
keypair (and URL) will be generated on the next `voxvera serve`. The
`voxvera import` command preserves this file automatically, but manual
deletion of the `host/` directory will destroy it.
## Hosting does not return after reboot or network loss
On Linux, install or verify the recovery timer:
```bash
voxvera autostart
systemctl --user status voxvera-start.timer
systemctl --user status voxvera-start.service
```
The supported recovery path is the recurring `systemd --user` timer, which reruns `voxvera start-all` every few minutes.
## QR codes not generated
If `voxvera build` reports "No URLs configured yet", this is expected before the first `voxvera serve`. QR codes for tear-off links are generated automatically once the .onion address is known. QR codes for the content link are generated if you provided a URL during `voxvera init`.
## Electron GUI
If `npm start` fails with `spawn voxvera ENOENT`, the `voxvera` command is not in your `PATH`. Install it with `pipx install git+https://github.com/PR0M3TH3AN/VoxVera.git` or run `./install.sh` from the repository.
## Missing dependencies
Run `voxvera check` to verify your setup. The command checks for required
Python packages (`qrcode`, `Pillow`, `jsmin`, `htmlmin`, `pypdf`) and
external tools (`onionshare-cli`), then prints a summary of anything
missing. To install everything:
```bash
# Recommended: use the install script (handles Tor + OnionShare too)
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
# Or reinstall just the Python package
pipx install --force 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
```
docs/ja/usage.md
-130
View File
@@ -1,130 +0,0 @@
# 詳細な使い方
このガイドでは、一般的なCLIワークフローについて説明します。Dockerの手順については `docs/docker.md` を、利用可能なフライヤーテンプレートについては `docs/templates.md` を参照してください。
## 前提条件
VoxVeraは高いポータビリティを実現するように設計されており、システムへの依存関係は最小限です。
### 1. スタンドアロンバイナリ (推奨)
お使いのオペレーティングシステムに合わせて、依存関係のないスタンドアロンバイナリをダウンロードできます。
- **Linux:** `voxvera-linux`
- **Windows:** `voxvera-windows.exe`
- **macOS:** `voxvera-macos`
これらのバイナリには、VoxVeraの実行に必要なすべてのものが含まれています（`onionshare-cli` を除く）。
### 2. ワンラインインストーラー
または、自動スクリプトを使用してインストールします。
```bash
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
```
### 3. 手動でのPythonインストール
ソースから実行したい場合：
```bash
pipx install 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
sudo apt install tor onionshare-cli # Debian/Ubuntu
```
## ステップ・バイ・ステップ
1. **初期化:** `voxvera init` を実行し、プロンプトに従います。最初に言語を選択するよう求められます。
2. **ビルド:** フライヤーのアセットを生成します。ビルドを実行するたびに、フライヤーのフォルダ内に `voxvera-portable.zip` が自動的に作成されます。これにより、他の人があなたのフライヤーから直接ツール一式をダウンロードできるようになります。
```bash
voxvera build
```
3. **公開:** Torを介してフライヤーを公開します。
```bash
voxvera serve
```
これにより、実行中のTorインスタンスが自動的に検出され、OnionShareが起動し、生成された .onion アドレスがフライヤーの切り取りセクションのリンクに書き込まれます。
## 言語サポート
VoxVeraは完全にローカライズされています。インタラクティブセレクターまたは直接ショートカットを使用して、言語設定を永続的に変更できます。
- **インタラクティブセレクター:** `voxvera lang`
- **直接ショートカット:** `voxvera --lang ja` (日本語に設定)
### サポートされている言語:
- **英語:** `en`
- **スペイン語:** `es` (エイリアス: `--idioma`)
- **ドイツ語:** `de` (エイリアス: `--sprache`)
- **日本語:** `ja`
永続的な設定を変更せずに、単一のコマンドに対して特定の言語を強制することもできます。
- **英語:** `voxvera --lang en check`
- **日本語:** `voxvera --lang ja check`
生成されたフライヤーは、訪問者のブラウザ言語を自動的に検出し、UIテキストをそれに応じて切り替えます。
## サーバー管理
単一のインタラクティブメニューから、複数のフライヤーとそのTorアイデンティティを管理できます。
```bash
voxvera manage
```
機能:
- **--- 新規サイト/フライヤー作成 ---**: セットアップシーケンスを最初から開始します。
- **--- すべてのサイトを開始 ---**: 管理下のすべてのフライヤーを一括で起動またはシャットダウンします。
- **リアルタイムステータス**: アクティブな .onion URLやTorの起動プログレスインジケーターを表示します。
- **個別制御**: 特定のサイトをZIPに Zipとしてエクスポート したり、削除したりできます。
## ユニバーサルミラーリング（バイラル拡散）
中央のリポジトリが検閲された場合でもVoxVeraを利用し続けられるように、すべてのフライヤーがツールのミラーとして機能します。
フライヤーをホストすると、ランディングページの **「ツールとソースをダウンロード」** ボタンから以下のものを含む `voxvera-portable.zip` が提供されます。
- すべてのサポート言語を含む完全なソースコード。
- すべてのPython依存関係（事前ベンダー化済み）。
- クロスプラットフォームのTorバイナリ。
これにより、あなたのフライヤーをスキャンした誰もが、VoxVeraツールの新しい配布者になることができます。
## エクスポートとバックアップ
独自のTorアイデンティティ（.onion URLが変更されないようにするため）をバックアップしたり、フライヤーを別のマシンに移動したりできます。
- **単一サイトのエクスポート**: `voxvera export <フォルダ名>`
- **全サイトのエクスポート**: `voxvera export-all`
**保存場所:** すべてのエクスポートは、すべてのプラットフォームでユーザーのホームディレクトリにある `~/voxvera-exports/` フォルダに保存されます。
## インポートと復元
ZIPファイルを `~/voxvera-exports/` に移動して以下を実行することで、新しいマシンでセットアップ全体を復元できます。
```bash
voxvera import-multiple
```
## ポータビリティとオフライン利用
インターネット接続のないマシンでVoxVeraを実行する必要がある場合は、まず依存関係を「ベンダー化」できます。
```bash
voxvera vendorize
```
これにより、必要なすべてのPythonライブラリが `voxvera/vendor/` にダウンロードされます。ツールはこれらのローカルファイルを優先的に使用するため、 `pip install` なしで実行できるようになります。
## 一括インポート (JSON)
複数のJSON設定ファイルからフライヤーを一括生成するには、それらを `imports/` ディレクトリに配置して以下を実行します。
```bash
voxvera batch-import
```
## URLの仕組み
各フライヤーには2つの異なるURLがあります。
- **切り取り用リンク** (自動生成): フライヤーがホストされている .onion アドレス。
- **コンテンツリンク** (ユーザー設定): ウェブサイト、動画、またはダウンロードを指す外部URL。
.onion アドレスを手動で入力する必要はありません。VoxVeraが `serve` フェーズ中に自動的に処理します。
docs/linux-hosting-validation.md
-178
View File
@@ -1,178 +0,0 @@
# Linux Hosting Validation
This runbook defines the operational validation standard for VoxVera's only supported hosting target:
- Linux CLI with `systemd --user`
Everything else remains below that bar until equivalent evidence exists.
## Prerequisites
- `voxvera` installed and on `PATH`
- `tor` installed
- `onionshare-cli` available
- a user account that can run `systemctl --user`
## Quick Verification
Use the helper script first:
```bash
bash scripts/linux-recovery-check.sh
```
This checks:
- `platform-status --json`
- `doctor --json`
- `autostart status --json`
- expected Linux support tier and platform id
- presence of `~/host`
- Tor and OnionShare discovery
- autostart artifacts and timer state
- per-site state for `.onionshare-session`, `onionshare.log`, and `server.pid`
## Core Commands
Install autostart:
```bash
voxvera autostart
```
Inspect autostart:
```bash
voxvera autostart status
systemctl --user status voxvera-start.timer
systemctl --user status voxvera-start.service
```
Remove autostart:
```bash
voxvera autostart uninstall
```
Inspect runtime diagnostics:
```bash
voxvera doctor
voxvera doctor --json
```
## Validation Checklist
### 1. Fresh install
Run the Linux installer or install through the supported CLI path, then confirm:
```bash
voxvera platform-status --json
voxvera doctor --json
voxvera autostart status --json
```
Expected:
- `platform_id` is `linux_cli_systemd`
- support tier is `supported`
- `voxvera_cli`, `onionshare_cli`, and `tor_binary` pass
### 2. Build and serve
Create or edit a site, then build and serve it:
```bash
voxvera build
voxvera serve
```
Expected:
- site output appears under `~/host/<folder_name>/`
- `index.html` and QR code images exist
- `onionshare.log` is written
- `.onionshare-session` appears after the hidden service is started
### 3. Identity persistence
Confirm the site keeps its identity across rebuilds:
```bash
ls -la ~/host/<folder_name>/
voxvera build --config ~/host/<folder_name>/config.json
```
Expected:
- `.onionshare-session` still exists after rebuild
### 4. Autostart persistence
Confirm the recovery timer exists and is enabled:
```bash
voxvera autostart status
systemctl --user is-enabled voxvera-start.timer
systemctl --user is-active voxvera-start.timer
```
Expected:
- timer artifacts exist under `~/.config/systemd/user/`
- timer is enabled
### 5. Reboot recovery
After a reboot, verify:
```bash
bash scripts/linux-recovery-check.sh
systemctl --user status voxvera-start.timer
journalctl --user -u voxvera-start.service --no-pager -n 50
```
Expected:
- timer remains enabled
- service has retried `start-all`
- configured sites are restorable without manual reconfiguration
### 6. Offline/reconnect recovery
Temporarily disconnect the host from the network, reconnect, then wait through at least one timer interval.
Verify:
```bash
systemctl --user status voxvera-start.timer
journalctl --user -u voxvera-start.service --no-pager -n 50
bash scripts/linux-recovery-check.sh
```
Expected:
- timer is still active
- `start-all` retries appear in the service logs
- Tor becomes reachable again
## Paths That Matter
- `~/.config/systemd/user/voxvera-start.service`
- `~/.config/systemd/user/voxvera-start.timer`
- `~/host/<folder_name>/config.json`
- `~/host/<folder_name>/.onionshare-session`
- `~/host/<folder_name>/onionshare.log`
- `~/host/<folder_name>/server.pid`
## Failure Interpretation
If `bash scripts/linux-recovery-check.sh` fails:
- missing `onionshare_cli` or `tor_binary` means the runtime is incomplete
- missing `host_root` means no sites are built yet
- missing autostart artifacts means recovery was never installed or was removed
- `tor_socks_reachable` warning means Tor is not currently reachable even if it is installed
Linux should remain the only supported target until this runbook is repeatable on real hosts without caveats.
docs/macos-validation-checklist.md
-173
View File
@@ -1,173 +0,0 @@
# macOS Validation Checklist
This checklist is for validating the experimental macOS CLI path on a real macOS machine.
Do not promote macOS above `experimental` until this checklist has been completed successfully on at least one native host and the results have been reviewed.
## Goal
Validate whether the current macOS runtime can:
1. install cleanly
2. build and serve a flyer
3. preserve the OnionShare session identity
4. recover after login/reboot/offline periods
5. surface understandable logs and status
## Environment Notes
- This checklist assumes the CLI runtime, not the Electron GUI.
- Prefer a clean machine or disposable user account.
- Record the exact macOS version, machine type, and install path used.
## 1. Install Surface
Record which install path was used:
- raw binary
- DMG
- `pipx`
- `install.sh`
Capture:
```bash
voxvera --version
voxvera platform-status --json
voxvera doctor --json
voxvera autostart status --json
```
Pass criteria:
- VoxVera launches
- `platform-status` reports `macos_cli`
- `doctor` runs without crashing
- `autostart status` runs without crashing
## 2. Build + Serve
Create a fresh working directory and config:
```bash
mkdir -p ~/voxvera-test
export VOXVERA_DIR=~/voxvera-test
voxvera init --non-interactive
voxvera build
voxvera serve
```
Capture:
- whether `index.html` is created under `~/voxvera-test/host/voxvera/`
- whether `.onionshare-session` appears
- whether an `.onion` URL is printed
- whether `onionshare.log` is created
Pass criteria:
- build completes
- serve completes
- `.onionshare-session` exists
- `onionshare.log` exists
## 3. Identity Persistence
Stop and restart the site:
```bash
voxvera stop-all
voxvera start-all
```
Capture:
- whether the same `.onion` URL returns
- whether `.onionshare-session` remains unchanged
Pass criteria:
- the onion identity persists across restart
## 4. Autostart Install
Install the experimental `launchd` path:
```bash
voxvera autostart
voxvera autostart status --json
```
Capture:
- generated plist path
- any `launchctl` output or errors
Pass criteria:
- the plist is created
- `autostart status` reports installed artifacts
## 5. Login / Reboot Recovery
After autostart is installed:
1. reboot the Mac or log out and back in
2. wait a few minutes
3. check:
```bash
voxvera doctor --json
voxvera autostart status --json
voxvera start-all
```
Capture:
- whether hosting resumed automatically
- whether the onion identity persisted
- whether the process had to be restarted manually
## 6. Offline / Reconnect Recovery
While a site is running:
1. disconnect the machine from the network
2. wait at least 2 minutes
3. reconnect
4. wait a few minutes
Capture:
- whether hosting recovered automatically
- whether manual `voxvera start-all` was required
- any errors in `onionshare.log`
## 7. Logs And Status
Capture the practical debugging workflow:
```bash
voxvera doctor --json
voxvera autostart status --json
ls -la ~/voxvera-test/host/voxvera
```
Document:
- where logs live
- what failed if recovery did not work
- any permissions/path issues
## Report Back
A useful tester report should include:
- macOS version
- install path used
- whether build worked
- whether serve worked
- whether the onion identity persisted
- whether login/reboot recovery worked
- whether offline/reconnect recovery worked
- exact command output or error text for failures
docs/multi-language-support.md
-99
View File
@@ -1,99 +0,0 @@
# Multi-Language Support Developer Plan
This document outlines the strategy for implementing a token-based multi-language system in VoxVera, covering the CLI, the generated landing page, and documentation.
## 1. Core Architecture: The Token System
All translatable strings will be centralized in JSON files located in `voxvera/locales/`. This allows for easy addition of new languages by simply dropping a new file.
- **Storage:** `voxvera/locales/{lang_code}.json` (e.g., `en.json`, `es.json`).
- **Structure:**
```json
{
"meta": {
"language_name": "English",
"flag": "🇺🇸"
},
"cli": {
"welcome": "Welcome to VoxVera Setup",
"select_lang": "Select your preferred language",
"folder_prompt": "Enter folder name for this flyer:"
},
"web": {
"title": "VoxVera - Anonymous Flyers",
"download_btn": "Download Flyer",
"onion_link_desc": "Scan to view on Tor",
"change_lang": "Change Language"
}
}
```
## 2. CLI Implementation (`voxvera/cli.py`)
The CLI will be updated to handle localization from the start of the user interaction.
### Workflow:
1. **Initial Detection:** On startup, the CLI checks the system locale (`LANG` env var or `locale` module).
2. **Language Selection:** The first prompt in `voxvera init` will be a language selector, defaulting to the detected system locale.
3. **Session Loading:** Once selected, the CLI loads the corresponding JSON. All subsequent `InquirerPy` prompts will use these tokens.
4. **Configuration:** The chosen language code is saved in the flyer's `config.json` as a preference for that specific project.
## 3. Web Implementation (`voxvera/src/index-master.html`)
The landing page will support dynamic language switching without requiring server-side logic (essential for Tor-hidden services).
### Detection Logic:
- **Avoid IP-based Detection:** Since VoxVera is hosted on Tor, IP lookups return the Tor Exit Node location, not the user's.
- **Browser-based Detection:** Use `navigator.language` to detect the user's browser preference.
- **Persistence:** Save the user's manual choice in `localStorage`.
### Frontend Components:
1. **Attributes:** Use `data-i18n="web.token_name"` on HTML elements.
2. **Language Switcher:** A dropdown menu or text-link list (e.g., "EN | ES | FR") placed next to the **Download** button.
3. **I18n Engine:** A lightweight JavaScript snippet injected during the build process that:
- Loads the bundled locale data.
- Detects the best language (Manual Selection > Browser Setting > English Fallback).
- Updates all `data-i18n` elements.
## 4. Build System Updates (`voxvera/build.py`)
The `build` process will be updated to bundle the necessary translations.
- **Multi-bundle:** By default, all available `web` tokens from all locale files will be injected into a single `<script>` tag in the final `index.html`. This ensures instant switching even when offline or on slow Tor connections.
- **Asset Optimization:** Minify the locale JSON data before injection to keep the HTML lightweight.
## 5. Portable & Viral Distribution Model
To ensure VoxVera is truly censorship-resistant, every generated flyer will serve as a mirror for the entire tool, including all supported languages and dependencies.
### Key Requirements:
- **Zero-Dependency Execution:** All Python libraries (from `requirements.txt`) will be bundled into a `voxvera/vendor/` directory. The CLI will be updated to prioritize this local path.
- **Pre-Bundled Tor:** The existing `voxvera/resources/tor/` binaries for Linux, Mac, and Windows will be included in every distribution.
- **Universal Language Bundle:** Every `voxvera-portable.zip` will include the full `voxvera/locales/` directory, ensuring that a user who downloads the tool from an English flyer can immediately switch it to Spanish, French, or any other supported language.
### The "Mirror" Workflow:
1. **Build Phase:** When `voxvera build` is executed, it assembles a `voxvera-portable.zip` containing:
- The full `voxvera/` source code.
- The `vendor/` library directory.
- All `locales/*.json` files.
- Cross-platform Tor binaries.
- A `voxvera-run.sh` / `voxvera-run.bat` entry point.
2. **Injection:** This ZIP is automatically placed in the `voxvera/host/<folder_name>/download/` directory of the generated flyer.
3. **User Access:** The landing page's "Download" button is updated to explicitly offer the "Full Portable Tool & Source," allowing the recipient to become a new node in the distribution network.
## 6. Documentation (`docs/`)
Documentation will follow a subdirectory structure for maximum compatibility with GitHub/Markdown renderers.
- **Structure:**
- `docs/en/usage.md`
- `docs/es/usage.md`
- **Maintenance:** A master English file will serve as the source of truth for all translations.
## 6. Implementation Phases
1. **Phase 1 (Audit):** Extract all hardcoded strings from `cli.py` and `index-master.html` into `en.json`.
2. **Phase 2 (CLI):** Implement the language selector and token loader in `cli.py`.
3. **Phase 3 (Web):** Update the HTML template with `data-i18n` attributes and the JS switcher.
4. **Phase 4 (Build):** Update `build.py` to inject the locale bundle.
5. **Phase 5 (Expansion):** Add a second language (e.g., Spanish) to verify the system.
docs/native-tester-guide.md
-50
View File
@@ -1,50 +0,0 @@
# Native Tester Guide
Use this guide when asking someone on macOS or Windows to validate VoxVera.
## Scope
VoxVera is not just an installer test. The real question is whether it can function as a reliable Tor hidden-service host on that platform.
That means every tester should be asked to validate:
1. install
2. build
3. serve
4. onion identity persistence
5. login/reboot recovery
6. offline/reconnect recovery
7. logs and diagnostics
## Canonical Checklists
- macOS: `docs/macos-validation-checklist.md`
- Windows: `docs/windows-validation-checklist.md`
## What To Ask Testers To Send Back
- platform and OS version
- install path used
- `voxvera platform-status --json`
- `voxvera doctor --json`
- `voxvera autostart status --json`
- whether `voxvera serve` produced an `.onion` URL
- whether `.onionshare-session` persisted after restart
- whether hosting resumed after reboot/login
- whether hosting resumed after network reconnect
- exact error output for any failure
## What Not To Conclude Prematurely
- successful installation does not prove hosting works
- successful hosting once does not prove recovery works
- binary availability does not prove platform parity
## Current Repo Position
- Linux CLI with `systemd --user`: supported
- Docker CLI: experimental
- macOS CLI: experimental
- Windows CLI: experimental
Do not promote macOS or Windows above `experimental` without native recovery evidence.
docs/nostr-static-client-spec.md
+76 -425
View File
@@ -1,480 +1,131 @@
# VoxVera Nostr Static Client Spec
Status: Phase 1 CLI import implemented for local event JSON files. A first static Editor/Viewer client exists under `site/nostr/`; relay publish/fetch uses browser WebSockets. Viewer mode is flyer-first and keeps Nostr controls hidden behind a small drawer toggle. Browser-side QR generation is implemented with a vendored local QR library. Browser-side anonymous key generation/signing is implemented with a vendored Nostr library, so publishing does not require a NIP-07 login. Independent browser-side signature verification before accepting fetched events is pending.
Status: `main` is the Nostr static-client branch. The legacy Tor/OnionShare CLI version is preserved on `legacy-tor`.
Branch: `nostr-static-client`
## Goal
## Purpose
VoxVera should let anyone publish, fetch, and print flyer content without a centralized application server.
Build a Nostr-powered VoxVera mode where public Nostr events store flyer content and any static/offline VoxVera client can fetch, validate, and render that content into the existing VoxVera flyer.
The static client is responsible for:
The generated flyer frontend must remain visually and behaviorally identical to the current VoxVera flyer. Nostr is an input/source layer, not a redesign.
- rendering the flyer
- generating QR codes
- authoring a normalized Nostr flyer payload
- generating anonymous browser-side Nostr keys
- signing and publishing replaceable Nostr events
- fetching events by raw event ID, `note1`, `nevent1`, or `naddr`
- rendering fetched content safely
## Core Principle
Nostr relays store the flyer source content. Static hosts only serve the client.
## Active Files
```text
Nostr event -> validate -> normalize to existing config.json -> existing VoxVera build/render path
site/
index.html
CNAME
nostr/
index.html
nostr-client.css
nostr-client.js
locales.js
vendor/
nostr-tools/
qrcode-generator/
voxvera/
nostr/
schema.py
tests/
test_nostr_schema.py
```
The existing flyer template, QR layout, tear-off layout, typography, print behavior, download behavior, and Tor-safe static output stay unchanged.
## Deployment
## Goals
The deployable static root is `site`.
- Let anyone host the VoxVera client as static files, over the web, Tor, IPFS, local disk, USB drive, or other mirrors.
- Let Nostr relays store the flyer content as public events.
- Let the client fetch a VoxVera flyer event by `naddr`, `note1`, `nevent1`, raw event ID, or URL fragment.
- Let the CLI import/build/serve a Nostr-backed flyer without changing the generated flyer frontend.
- Generate QR codes locally from validated content.
- Keep the default QR behavior aligned with current VoxVera: QR points to the generated flyer URL unless explicitly configured otherwise.
- Support fully offline rendering once a Nostr event payload has been exported or cached.
No build command is required. Vercel should use:
## Non-Goals For V1
- root directory: repository root
- output directory: `site`
- build command: empty
- No redesign of `index-master.html`.
- No new visual style for the flyer.
- No server-side backend.
- No custody of user-managed Nostr keys.
- No required login or NIP-07 signer.
- No private/encrypted Nostr events.
- No remote images, fonts, scripts, CSS, CDNs, analytics, or trackers.
- No raw HTML injection from Nostr content.
- No dependency on a single relay.
`site/index.html` redirects root traffic to `/nostr/`.
## User Flows
## Event Model
### Static Client Flow
1. User opens a static VoxVera client.
2. User pastes a `naddr`, `note1`, `nevent1`, raw event ID, or URL containing one.
3. Client chooses relays from the identifier, user settings, or defaults.
4. Client fetches the event.
5. Client validates the event as a VoxVera flyer source.
6. Client normalizes content into the existing VoxVera config schema.
7. Client renders the existing flyer UI and generates QR codes locally.
8. User prints, exports, saves, or hosts the generated flyer.
Viewer mode must default to the rendered flyer, not the editor shell. Header text, event forms, normalized config JSON, and other loader UI stay hidden unless the user opens the viewer controls drawer. Printing from viewer mode must target only the 8.5x11 flyer surface.
Viewer mode must auto-load content when the URL includes an event reference. Supported forms include:
- `?addr=<naddr>`
- `?event=<raw-id-or-note1-or-nevent1-or-naddr>`
- `?id=<raw-64-character-event-id>`
- `#viewer/<raw-id-or-note1-or-nevent1-or-naddr>`
- pasted `nostr:note1...`, `nostr:nevent1...`, or `nostr:naddr...` values in the viewer lookup tool
The manual viewer lookup tool must accept the same raw ID, `note1`, `nevent1`, `naddr`, and `nostr:` values. `nevent1` and `naddr` relay hints should be merged with the default/user relay list.
The canonical poster URL should use `naddr`, not the raw event ID, because the flyer itself needs to include a URL that resolves back to the poster. Raw event IDs are hashes of the final event payload, so embedding a raw event-ID URL in the same event creates a circular dependency. A `naddr` is stable because it is derived from author pubkey, kind `30078`, and the `d` tag.
### CLI Flow
```bash
voxvera nostr import <note-or-nevent>
voxvera nostr build <note-or-nevent>
voxvera nostr serve <note-or-nevent>
```
Expected behavior:
- `import` writes a normal site folder under `~/host/<folder_name>/` with a standard `config.json`.
- `build` imports and builds the flyer assets.
- `serve` imports, builds, and runs the existing OnionShare hosting path.
The CLI should preserve the current config/build/serve contract so Nostr flyers can be exported, imported, and mirrored by existing VoxVera mechanisms.
## Event Format
V1 should use a deterministic JSON payload in event `content`.
Recommended Nostr event kind for prototype: `30078` parameterized replaceable event, with a `d` tag.
Rationale:
- It avoids inventing a custom kind before the format proves itself.
- It allows stable named flyer records per author.
- It can later be migrated to a dedicated custom kind if needed.
Recommended event kind: `30078` parameterized replaceable event.
Required tags:
```json
[
["d", "voxvera:<slug-or-id>"],
["t", "voxvera"],
["t", "flyer"]
]
```
- `["d", "voxvera:<slug>"]`
- `["t", "voxvera"]`
- `["t", "flyer"]`
Optional tags:
```json
[
["title", "OPERATION VOX VERA"],
["language", "en"],
["subject", "censorship"],
["relay", "wss://relay.example.org"]
]
```
Content schema:
Payload:
```json
{
"type": "voxvera_flyer",
"version": 1,
"folder_name": "voxvera",
"lang": "en",
"name": "Vox Vera Printable Flyers",
"lang": "en",
"title": "TOP SECRET",
"subtitle": "DO ~~NOT~~ DISTRIBUTE",
"headline": "OPERATION VOX VERA",
"content": "Main flyer text.",
"content": "Flyer body text",
"url_message": "Follow this link to learn more.",
"url": "https://example.com/",
"footer_message": "0110010 0101011 0110010 0111101 0110100",
"attachment_path": "",
"attachment_filename": "",
"url": "https://voxvera.org/",
"footer_message": "0110010",
"qr_target": "flyer_url"
}
```
`folder_name` remains the internal compatibility key for the existing VoxVera config/build path, but the static Nostr editor should label this field as `Flyer Name`. In Nostr mode it acts as the stable flyer slug used in the replaceable event `d` tag, not as a local Tor hosting folder name.
The UI labels `folder_name` as `Flyer Name`; it acts as the event slug, not a local hosting folder.
Allowed `qr_target` values:
## QR Target
- `flyer_url`: default; current VoxVera behavior.
- `nostr_event`: QR points to the source Nostr identifier.
- `content_url`: QR points to the `url` field.
Default behavior: `qr_target: "flyer_url"`.
The static Nostr editor should default to `flyer_url`, where the flyer URL is the hosted client URL with `?addr=<naddr>`. That avoids the raw event-ID circular dependency and lets a re-published replaceable event keep the same printed flyer URL.
When publishing, the client computes the replaceable-event `naddr` and updates the poster URL to the current hosted client URL with `?addr=<naddr>`. The tear-off tabs and QR code point at that resolved poster URL.
## Normalization Rules
Supported values:
The importer maps the Nostr payload to the existing `config.json` schema.
- `flyer_url`: QR points to the hosted client URL for the poster
- `content_url`: QR points to the payload's content URL
- `nostr_event`: QR points to the Nostr source identifier when available
Rules:
## Safety
- Missing optional fields use current VoxVera defaults.
- Unknown fields are ignored unless explicitly preserved in metadata.
- `folder_name` / editor `Flyer Name` must be slug-safe and length-limited.
- `lang` must be one of the supported locale keys or fall back to `en`.
- Text fields must be strings, not arrays or objects.
- Text fields must have length limits.
- URLs must be validated before use.
- Attachments are disabled for V1 unless represented as ordinary links.
- The normalized config must be buildable by the current `build_assets` path.
- The static Nostr viewer should preserve the old generated site's multilingual token behavior: `landing.*` and `web.*` token paths should resolve through the existing locale dictionaries, with browser/default language selection and RTL handling where applicable. This is not fully implemented in the first static preview renderer yet.
Nostr content is untrusted.
Suggested field limits:
The client and schema helper must:
- `folder_name`: 64 characters.
- `name`: 120 characters.
- `title`: 80 characters.
- `subtitle`: 120 characters.
- `headline`: 160 characters.
- `content`: 10000 characters.
- `url_message`: 240 characters.
- `url`: 2048 characters.
- `footer_message`: 240 characters.
- reject raw HTML in flyer text fields
- escape rendered flyer content
- reject unsafe URL schemes such as `javascript:` and `data:`
- keep attachments unsupported in V1
- avoid remote frontend dependencies
## Frontend Contract
## Localization
The flyer frontend must continue to use the existing generated HTML and print surface.
Flyer defaults come from `site/nostr/locales.js`.
Allowed changes:
Nostr editor/viewer controls and Nostr-specific flyer labels come from `NOSTR_UI` in `site/nostr/nostr-client.js`.
- Add a separate loader/import page or app shell.
- Add client-side Nostr fetch code in the loader.
- Add local QR generation in the loader or build path.
- Add metadata outside the flyer if needed.
- Add minimal viewer controls outside the flyer, preferably as a hidden drawer or compact toggle.
- Add anonymous local key generation/signing in the editor shell.
Language changes should:
Disallowed changes:
- update default flyer content while the flyer is still using default content
- preserve user-authored or fetched event content
- update editor/viewer tool labels
- update printed side-tab labels
- respect RTL direction metadata
- Changing the visual layout of the generated flyer.
- Adding visible Nostr branding to the flyer by default.
- Adding JavaScript dependency to the generated flyer.
- Adding remote assets to the generated flyer.
- Injecting raw Nostr content as HTML.
- Printing the loader shell, event form, normalized config JSON, or preview chrome.
## Static Client Architecture
Recommended structure:
```text
site/nostr/
index.html
nostr-client.js
nostr-schema.js
nostr-render.js
vendor/
qrcode-generator/
nostr-tools/
```
The static client should:
- Be self-contained.
- Work from `file://` where practical.
- Work with JavaScript enabled for fetching/rendering.
- Produce/export a final flyer that remains static and Tor-safe.
- Avoid service workers in V1.
- Open `/nostr/#viewer` into a flyer-only viewer surface with a small control toggle.
- Keep `/nostr/#editor` as the form-based event authoring surface.
- Publish with a locally generated anonymous `npub` by default, stored only in browser local storage.
- Allow regenerating/rotating the anonymous `npub` from the editor.
The generated flyer remains separate from the loader:
```text
loader client: interactive, fetches Nostr
generated flyer: static, print-safe, JS-free
```
## Relay Strategy
Inputs:
- Relays embedded in `naddr`, when present.
- Relays embedded in `nevent1`, when present.
- User-provided relay list.
- Built-in fallback relay list.
Rules:
- Query multiple relays in parallel.
- Resolve `naddr` by querying kind `30078` with the addressed author pubkey and `d` tag, then use the newest matching replaceable event returned.
- Use the first valid matching event, then continue briefly to detect conflicts.
- Prefer exact event ID matches over replaceable address matches.
- Show event author, event ID, creation time, and relays used in the loader.
- Do not bake relay-specific state into the generated flyer unless explicitly requested.
## Security Model
Nostr content is untrusted external input.
Required protections:
- Parse JSON with strict schema validation.
- Escape all rendered text.
- Reject raw HTML/script fields.
- Do not load remote assets referenced by events.
- Validate URL schemes: allow `https`, `http`, `onion` URLs via `http://*.onion`, and Nostr identifiers. Reject `javascript:`, `data:`, and similar schemes.
- Put strict length limits on all fields.
- Treat relay responses as untrusted even if signed.
- Verify event signatures before accepting content.
- Do not require users to enter private keys for V1.
- If the browser editor stores an anonymous generated signing key in local storage, label it as a disposable local identity and provide a rotation path.
## Privacy Model
Fetching from public relays leaks interest in an event to those relays and network observers.
Mitigations:
- Allow custom relay lists.
- Allow Tor Browser usage as an optional transport choice.
- Allow offline import from pasted event JSON.
- Document that using public relays is not private.
- Do not phone home to VoxVera infrastructure.
## CLI Architecture
Suggested module split:
```text
voxvera/nostr/
__init__.py
ids.py # parse note1/nevent1/event IDs
relays.py # fetch events
schema.py # validate payloads
importers.py # normalize to config
qrcode.py # QR target selection helpers if needed
```
CLI command group:
## Verification
```bash
voxvera nostr import <identifier> [--relay wss://...] [--folder-name ...]
voxvera nostr build <identifier> [--relay wss://...]
voxvera nostr serve <identifier> [--relay wss://...]
voxvera nostr validate <file-or-identifier>
node --check site/nostr/nostr-client.js
pytest -q
```
Implementation should keep Nostr code behind a command group so the current non-Nostr workflow remains stable.
## Browser Dependency Strategy
Prefer a small, vendored Nostr client implementation or a carefully vendored library.
Requirements:
- No CDN.
- No dynamic remote imports.
- Browser bundle stored in repo/package.
- CLI dependency either optional extra or small pure-Python implementation.
- Reproducible vendoring instructions.
Candidate directions:
- Browser: vendored `nostr-tools` bundle or a minimal NIP-01/NIP-19 fetch/verify implementation.
- Python CLI: optional `websockets` plus signature verification, or shell out to a bundled helper only if packaging remains clean.
Decision should happen during implementation after checking package size and offline portability impact.
## QR Behavior
V1 default:
- QR and tear-offs point to the generated poster URL, matching current VoxVera behavior without requiring Tor-specific wording.
Optional future modes:
- QR points to source Nostr event.
- QR points to original content URL.
- Flyer includes a separate source QR outside the current print layout.
Any QR mode that changes visible flyer output must be opt-in.
## Testing Plan
Unit tests:
- Parse `note1`, `nevent1`, raw IDs.
- Validate good schema.
- Reject invalid JSON.
- Reject wrong `type`.
- Reject unsupported `version`.
- Reject unsafe URL schemes.
- Enforce field length limits.
- Normalize payload to current config schema.
- Preserve current build output for existing configs.
Integration tests:
- Import fixture event into `~/host/<folder>/config.json`.
- Build imported fixture and compare required output files.
- Serve imported fixture through existing serve path with mocks.
- Static client fixture renders same fields as CLI normalization.
Security tests:
- Script tag in content is escaped.
- HTML event handler attributes are escaped.
- `javascript:` URL rejected.
- Oversized payload rejected.
- Unknown fields ignored.
Manual validation:
- Open static loader from local file.
- Fetch known fixture event from test relay or local mock relay.
- Render/print flyer.
- Verify generated flyer remains usable with JavaScript disabled.
- Verify Tor Browser Safest mode compatibility for generated flyer.
## Implementation Phases
### Phase 0: Design Lock
- Finalize this spec.
- Decide event kind strategy.
- Decide dependency strategy.
- Create fixture events.
- Define schema in code comments/docs before implementation.
### Phase 1: CLI Import
- Add `voxvera nostr validate`.
- Add `voxvera nostr import`.
- Use fixture JSON first.
- Normalize into existing `config.json`.
- Add tests.
Implemented initial local-file commands:
```bash
voxvera nostr validate ./event.json
voxvera nostr import ./event.json
voxvera nostr build ./event.json
voxvera nostr serve ./event.json
```
Phase 1 intentionally rejects non-file `note1` / `nevent1` identifiers with a clear message. Relay fetch, NIP-19 parsing, and signature verification belong to Phase 2.
### Phase 2: Relay Fetch
- Add relay fetching for public events.
- Add NIP-19 parsing.
- Add signature verification.
- Add relay selection options.
- Add tests with mocked relay responses.
### Phase 3: Static Loader
- Add self-contained static loader under `site/nostr/`.
- Fetch event by identifier.
- Validate and normalize payload.
- Render existing flyer output or produce config for existing render path.
- Add export/download option.
Initial implementation exists:
- `site/nostr/index.html`
- `site/nostr/nostr-client.css`
- `site/nostr/nostr-client.js`
Current behavior:
- Editor mode collects existing VoxVera flyer fields.
- Editor can export unsigned kind `30078` event JSON.
- Editor can sign/publish through a NIP-07 browser signer and returns the signed event ID.
- Viewer mode fetches a raw 64-character event ID from configured relays.
- Viewer normalizes event content into existing VoxVera config JSON.
- Preview is client-side and print-oriented, but it is not yet the final generated flyer artifact.
Pending hardening:
- Vendor or implement browser-side QR generation without CDN usage.
- Add independent event ID/signature verification in the browser.
- Decide whether the static viewer should generate a full standalone flyer HTML file for download.
### Phase 4: QR Modes
- Keep default QR as generated flyer URL.
- Add optional `qr_target` handling.
- Add tests and docs.
### Phase 5: Publishing Support
Deferred.
Possible future commands:
```bash
voxvera nostr publish config.json
voxvera nostr sign config.json
```
This requires a separate key-management spec.
## Open Questions
- Should V1 use kind `30078`, a custom kind, or both?
- Should replaceable events be accepted by default, or should exact immutable event IDs be preferred for anti-tamper stability?
- Should the static loader render HTML directly in browser, or should it generate/download a standard VoxVera project bundle?
- What relay list should be bundled by default, if any?
- Should `qr_target: nostr_event` encode `nevent1` with relay hints or a bare `note1`?
- Should the generated flyer include source attribution metadata in comments only, or not at all?
## Acceptance Criteria
- Existing non-Nostr VoxVera workflow continues to pass tests.
- Existing generated flyer visual output is unchanged for normal configs.
- Nostr fixture event can be validated, imported, built, and served through existing paths.
- Static loader is self-contained and does not use remote dependencies.
- Generated flyer remains static and JS-free.
- Unsafe Nostr payloads are rejected or escaped.
- Docs explain relay privacy tradeoffs.
For UI work, also verify browser rendering and print output from a local static server.
docs/platform-support-matrix.md
-59
View File
@@ -1,59 +0,0 @@
# Platform Support Matrix
This file is the canonical human-readable summary of VoxVera's actual platform support posture.
The machine-readable companion file is [`support-matrix.json`](/home/user/Documents/GitHub/VoxVera/support-matrix.json).
## Support Tiers
- **Supported**: validated for persistent hidden-service hosting with documented recovery behavior.
- **Beta**: feature-complete enough for broader testing, but not yet validated for production-grade recovery claims.
- **Experimental**: may install or run, but is not yet validated for reliable background hidden-service hosting.
- **Unsupported**: not currently a target for reliable hosting.
## Current Matrix
| Platform | Tier | Canonical Runtime Model | Distribution Surfaces | Notes |
| :--- | :--- | :--- | :--- | :--- |
| Linux CLI with `systemd --user` | Supported | System Tor or Tor Browser plus `onionshare-cli`, with recurring `systemd --user` timer recovery | `install.sh`, `voxvera-install.sh`, `pip/pipx`, Linux binary | Current reference implementation |
| Docker CLI | Experimental | Containerized runtime with `VOXVERA_DIR=/flyers` and periodic `start-all` retries | Dockerfile, GHCR image | Needs end-to-end restart validation |
| macOS CLI | Experimental | CLI runtime with `launchd` autostart path and external Tor/OnionShare dependencies | `install.sh`, `pip/pipx`, macOS binary, DMG | No validated recovery claim yet |
| Windows CLI | Experimental | CLI runtime with Task Scheduler path and external Tor/OnionShare dependencies | `install.ps1`, Windows binary, Chocolatey | Binary naming and runtime model need cleanup |
| Electron GUI | Experimental | GUI frontend over the CLI runtime | `gui/electron` | Must converge on shared runtime behavior |
| Flatpak/AppImage/Homebrew/Chocolatey/Deb | Experimental | Distribution-only until runtime parity exists | packaging scripts/manifests | Package availability does not imply hosting parity |
## What "Supported" Means For VoxVera
To move a platform to **Supported**, VoxVera should have evidence for all of the following:
1. Fresh install works on a clean machine.
2. Manual `build` and `serve` work.
3. `.onionshare-session` survives rebuilds and restarts.
4. Hosting returns after reboot or login.
5. Hosting returns after a temporary offline period.
6. Logs and status are inspectable with documented commands.
7. The docs and release artifacts do not overstate capability.
## Promotion Rules
- Do not promote a package surface before the underlying runtime model is validated.
- Do not call a platform "recommended" unless it is also `supported`.
- If a platform lacks validated auto-recovery after reboot or network interruption, it must remain `experimental` or `beta`.
## Current Recommendation
If your goal is reliable Tor hidden-service hosting today, use the Linux CLI path and install the recurring recovery timer with:
```bash
voxvera autostart
```
That is the current reference deployment model the rest of the platform work should converge toward.
## Native Validation
When validating the experimental non-Linux paths on real machines, use:
- [macOS checklist](/home/user/Documents/GitHub/VoxVera/docs/macos-validation-checklist.md)
- [Windows checklist](/home/user/Documents/GitHub/VoxVera/docs/windows-validation-checklist.md)
- [Native tester guide](/home/user/Documents/GitHub/VoxVera/docs/native-tester-guide.md)
docs/pt/AGENTS.md
-42
View File
@@ -1,42 +0,0 @@
# AI Agent Instructions for VoxVera
This guide is for AI agents (like Gemini, Claude, or GPT) contributing to the VoxVera project. Follow these protocols to maintain the architectural integrity and multi-language support.
## Core Mandates
1. **Security-First**: VoxVera is a Tor-based tool. Never suggest features that leak IP addresses or use non-Tor external resources (CDNs, etc.).
2. **Local-First**: All assets (fonts, dependencies, binaries) must be self-contained within the `voxvera/` package to support the Universal Mirroring model.
3. **Tokenized UI**: Never hardcode user-facing strings. Always add them to `voxvera/locales/en.json` and use the `t('cli.token')` helper.
4. **Markdown Redaction**: Use `~~text~~` in locale JSONs for strike-through effects. Both the build system and the JS engine handle the conversion to `<span class="redacted">` automatically.
5. **Visual Width Testing**: When modifying UI or adding languages, verify that long or complex strings (e.g., Hindi ligatures or CJK characters) do not exceed the visual unit limits defined in the CLI.
## Localization Protocol
When adding a new language or updating an existing one:
- **CLI/Flyers**: Update `voxvera/locales/{lang}.json`. Include `meta`, `cli`, `web`, and `landing` categories.
- **Landing Page**:
- Directly update the `const locales` object in `site/index.html`.
- **Crucial**: Run `voxvera build-site` to generate the latest portable bundle and refresh the pre-rendered HTML.
- **Documentation**:
- Master templates live in `docs/templates/`.
- Localized overrides live in `voxvera/locales/{lang}/docs/`.
- **Crucial**: After any change to locales or templates, you MUST run `voxvera build-docs` to synchronize the output in `docs/{en,es,de}/`.
## Universal Mirroring
VoxVera propagates through its own flyers.
- Every `voxvera build` and `voxvera build-site` generates `voxvera-portable.zip`.
- If you modify the core source code, ensure the `bundle_portable` function in `voxvera/cli.py` still correctly captures all necessary directories (especially `vendor/`, `locales/`, and `resources/`).
## Verification Checklist
Before finishing a task, ensure you have:
1. Run unit tests: `pytest tests/test_cli.py`.
2. Verified the localization: `voxvera --lang {lang} check`.
3. Rebuilt the documentation: `voxvera build-docs`.
4. Synchronized the public site: `voxvera build-site`.
5. Verified the portable bundle exists: `ls -l voxvera/host/*/download/voxvera-portable.zip` and `ls -l site/download/voxvera-portable.zip`.
---
Follow these rules to ensure VoxVera remains a robust, viral, and decentralized tool for truth.
docs/pt/CONTRIBUTING.md
-47
View File
@@ -1,47 +0,0 @@
# Contributing to VoxVera
Thank you for your interest in contributing to VoxVera! This project aims to be a global, censorship-resistant tool, and your help—especially with translations—is vital.
## Adding a New Language
VoxVera uses a centralized token system for the CLI and Web components, and a template-based system for Documentation. To add a new language (e.g., French/`fr`), follow this checklist:
### 1. The Token File
Create a new JSON file in `voxvera/locales/{lang_code}.json`.
- Use `en.json` as your master template.
- **`meta`**: Include the native language name and a flag emoji.
- **`cli`**: Translate all strings used in the terminal interface.
- **`web`**: Translate strings used on the generated landing pages and flyers.
- **`landing`**: Translate the specific content for the official VoxVera website.
- **Formatting**: You can use Markdown-style strike-throughs (`~~redacted text~~`) in any of these strings; they will be automatically converted to the stylized "redacted" effect on the flyers.
### 2. The Landing Page
The main landing page is generated from the shared template and locale files.
- Add your language in `voxvera/locales/{lang_code}.json`.
- Do **not** edit `site/index.html` directly; it is generated output.
- Run `voxvera build-site` to refresh the public assets and inject your new locale into the generated HTML.
### 3. Documentation
VoxVera uses the **Doc-Sync Engine** to keep manuals in sync.
- Create localized Markdown files in `voxvera/locales/{lang_code}/docs/`.
- Use the templates in `docs/templates/` as your guide.
- You can use `cli.token_name` to reference terminal commands automatically.
### 4. Build and Verify
Run the following commands to verify your changes:
- `voxvera --lang {lang_code} check` (Verify CLI translation)
- `voxvera build-docs` (Generate localized manuals)
- `voxvera build-site` (Synchronize the public website and generate the latest portable bundle)
- Open the generated `site/index.html` in a browser and test the language switcher.
## Code Contributions
- **Dependencies**: if you add a new Python library to `requirements.txt`, you MUST run `voxvera vendorize` to include it in the portable distribution.
- **Layout Integrity**: VoxVera uses visual width validation. If you add new UI elements, ensure they respect the physical boundaries of an 8.5"x11" flyer.
- **Tests**: Ensure all tests pass: `pytest tests/`. Run the integrity suite specifically when modifying locales: `pytest tests/test_integrity.py`.
- **Generated artifacts**: Treat `voxvera/resources/bin/` as local build output, not source files. Release binaries belong in GitHub Releases, not hand-edited repo state.
- **Style**: Follow the existing coding style (PEP 8 for Python).
- **Documentation**: If adding a new feature, update the master templates in `docs/templates/` and run `voxvera build-docs`.
---
Together, we can ensure that truth remains accessible to everyone, everywhere.
docs/pt/docker.md
-48
View File
@@ -1,48 +0,0 @@
# Docker Usage
Experimental: the container path is not yet a production-grade hidden-service deployment target. Linux with `systemd --user` remains the supported persistent-host environment.
A prebuilt image containing Tor, OnionShare and the `voxvera` CLI is published to
`ghcr.io/voxvera/voxvera`.
```bash
# pull the image
docker pull ghcr.io/voxvera/voxvera:latest
# run the experimental container with flyers stored in ./flyers
mkdir -p flyers
docker run -d \
--name voxvera \
--restart unless-stopped \
-v "$(pwd)/flyers:/flyers" \
ghcr.io/voxvera/voxvera:latest
```
The container now uses a dedicated entrypoint that:
- stores runtime state under `/flyers`
- seeds `/flyers/config.json` if needed
- starts an in-container Tor daemon on `127.0.0.1:9050/9051`
- bootstraps a default site when `/flyers/host` is empty
- runs `voxvera start-all` on startup and retries it periodically
- exposes a container healthcheck based on `voxvera doctor --json`
Useful commands:
```bash
docker logs -f voxvera
docker exec -it voxvera voxvera doctor --json
docker exec -it voxvera voxvera autostart status --json
```
If you prefer Compose:
```yaml
services:
voxvera:
image: ghcr.io/voxvera/voxvera:latest
restart: unless-stopped
volumes:
- ./flyers:/flyers
```
Use this path for testing only until the container runtime and background recovery behavior are validated end-to-end.
docs/pt/templates.md
-14
View File
@@ -1,14 +0,0 @@
# Flyer Templates
Pre-built flyer templates live in the `templates/` directory. Use the CLI to copy one with:
```bash
voxvera init --template <name>
```
This will create a new folder under `dist/` named `<name>-<YYYYMMDD>` containing the template files.
Available templates:
- **blank** – minimal placeholder files, also used when extracting fields from a PDF.
- **voxvera** – example flyer showcasing the VoxVera project.
docs/pt/troubleshooting.md
-75
View File
@@ -1,75 +0,0 @@
# Troubleshooting
This page collects common issues encountered when hosting or accessing flyers.
## Tor connectivity
- Ensure Tor is allowed through your firewall. On systems using `ufw` you may need to run `sudo ufw allow tor`.
- Some networks block Tor entirely. If you cannot reach onion services, try connecting over a different network or use a Tor bridge.
## Supported deployment target
- The supported persistent-host setup is Linux with `systemd --user`.
- Windows, macOS, Docker, Flatpak, AppImage, Homebrew, and Chocolatey are currently experimental and may not recover hosting automatically after reboot or network interruptions.
## Tor port detection
`voxvera serve` auto-detects Tor by probing common ports (9050/9150 for SOCKS, 9051/9151 for control). If detection fails -- for example when Tor runs on non-standard ports -- you can override with environment variables:
```bash
TOR_SOCKS_PORT=19050 TOR_CONTROL_PORT=19051 voxvera serve
```
If no running Tor is found, the defaults (9050/9051) are used and OnionShare will attempt to connect on those ports.
## Firewall rules
- If `voxvera serve` fails to start OnionShare, verify that outbound connections on ports 9001 and 80 are permitted.
- Corporate or university firewalls can block the hidden service ports required by Tor.
## SELinux
- On SELinux-enabled distributions you may see `permission denied` errors when OnionShare writes to the `host` directory.
- Run `sudo chcon -Rt svirt_sandbox_file_t host` or disable SELinux enforcement for the folder.
## OnionShare crashes
If `voxvera serve` prints "OnionShare exited unexpectedly", check the log file
`host/<folder_name>/onionshare.log` for details. Common causes:
- Tor is not running (`sudo systemctl start tor`)
- A port conflict with another service
- Missing `onionshare-cli` (run `voxvera check`)
## Onion URL changed unexpectedly
The onion URL is tied to the Ed25519 keypair stored in
`host/<folder_name>/.onionshare-session`. If this file is deleted, a new
keypair (and URL) will be generated on the next `voxvera serve`. The
`voxvera import` command preserves this file automatically, but manual
deletion of the `host/` directory will destroy it.
## Hosting does not return after reboot or network loss
On Linux, install or verify the recovery timer:
```bash
voxvera autostart
systemctl --user status voxvera-start.timer
systemctl --user status voxvera-start.service
```
The supported recovery path is the recurring `systemd --user` timer, which reruns `voxvera start-all` every few minutes.
## QR codes not generated
If `voxvera build` reports "No URLs configured yet", this is expected before the first `voxvera serve`. QR codes for tear-off links are generated automatically once the .onion address is known. QR codes for the content link are generated if you provided a URL during `voxvera init`.
## Electron GUI
If `npm start` fails with `spawn voxvera ENOENT`, the `voxvera` command is not in your `PATH`. Install it with `pipx install git+https://github.com/PR0M3TH3AN/VoxVera.git` or run `./install.sh` from the repository.
## Missing dependencies
Run `voxvera check` to verify your setup. The command checks for required
Python packages (`qrcode`, `Pillow`, `jsmin`, `htmlmin`, `pypdf`) and
external tools (`onionshare-cli`), then prints a summary of anything
missing. To install everything:
```bash
# Recommended: use the install script (handles Tor + OnionShare too)
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
# Or reinstall just the Python package
pipx install --force 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
```
docs/pt/usage.md
-130
View File
@@ -1,130 +0,0 @@
# Uso Detalhado
Este guia cobre os fluxos de trabalho comuns da CLI. Veja `docs/docker.md` para instruções do Docker e `docs/templates.md` para modelos de panfletos disponíveis.
## Pré-requisitos
O VoxVera foi projetado para ser altamente portátil e requer dependências mínimas do sistema.
### 1. Binários Independentes (Recomendado)
Você pode baixar binários independentes e sem dependências para o seu sistema operacional:
- **Linux:** `voxvera-linux`
- **Windows:** `voxvera-windows.exe`
- **macOS:** `voxvera-macos`
Estes binários incluem tudo o que é necessário para executar o VoxVera (exceto o `onionshare-cli`).
### 2. Instalador de Linha Única
Alternativamente, instale através do nosso script automatizado:
```bash
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
```
### 3. Instalação Manual via Python
Se preferir executar a partir do código-fonte:
```bash
pipx install 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
sudo apt install tor onionshare-cli # Debian/Ubuntu
```
## Passo a Passo
1. **Inicializar:** Execute `voxvera init` e siga as instruções. Você será solicitado a selecionar seu idioma primeiro.
2. **Construir:** Gere os arquivos do panfleto. Cada construção cria automaticamente um `voxvera-portable.zip` na pasta do panfleto, permitindo que outros baixem a ferramenta completa diretamente do seu panfleto.
```bash
voxvera build
```
3. **Servir:** Publique o panfleto via Tor:
```bash
voxvera serve
```
Isso detecta automaticamente sua instância do Tor, inicia o OnionShare e escreve o endereço .onion gerado nos links destacáveis do panfleto.
## Suporte a Idiomas
O VoxVera é totalmente localizado. Você pode alterar sua preferência de idioma permanentemente usando o seletor interativo ou um atalho direto:
- **Seletor Interativo:** `voxvera lang`
- **Atalho Direto:** `voxvera --lang pt` (define a preferência para português)
### Idiomas Suportados:
- **Inglês:** `en`
- **Espanhol:** `es` (alias: `--idioma`)
- **Alemão:** `de` (alias: `--sprache`)
- **Português:** `pt`
Você também pode forçar um idioma específico para um único comando sem alterar sua preferência permanente:
- **Inglês:** `voxvera --lang en check`
- **Português:** `voxvera --lang pt check`
Os panfletos gerados detectam automaticamente o idioma do navegador do visitante e alteram o texto da interface adequadamente.
## Gerenciamento de Servidores
Gerencie vários panfletos e suas identidades Tor a partir de um único menu interativo:
```bash
voxvera manage
```
Recursos:
- **--- Criar Novo Site/Panfleto ---**: Inicia a sequência completa de configuração.
- **--- Iniciar Todos os Sites ---**: Inicia ou encerra todos os panfletos da sua frota de uma só vez.
- **Status em Tempo Real**: Visualize URLs .onion ativas e indicadores de progresso de inicialização do Tor.
- **Controle Individual**: Exportar para Zip sites específicos para ZIP ou exclua-os.
## Espelhamento Universal (Distribuição Viral)
Para garantir que o VoxVera permaneça acessível mesmo se os repositórios centrais forem censurados, cada panfleto atua como um espelho para a ferramenta.
Quando você hospeda um panfleto, o botão **"Baixar Ferramenta e Código"** na página inicial fornece um `voxvera-portable.zip` contendo:
- O código-fonte completo e todos os idiomas suportados.
- Todas as dependências Python (pré-vendidas).
- Binários Tor multiplataforma.
Isso permite que qualquer pessoa que escaneie seu panfleto se torne um novo distribuidor da ferramenta VoxVera.
## Exportação e Backup
Faça backup de suas identidades Tor exclusivas (para que sua URL .onion nunca mude) ou mova seus panfletos para outra máquina.
- **Exportar um único site**: `voxvera export <nome_da_pasta>`
- **Exportar todos os sites**: `voxvera export-all`
**Local de armazenamento:** Todas as exportações são salvas como arquivos ZIP em uma pasta chamada `voxvera-exports` no diretório inicial do usuário (`~/voxvera-exports/`) em todas as plataformas.
## Importação e Recuperação
Restaure toda a sua configuração em uma nova máquina movendo seus arquivos ZIP para `~/voxvera-exports/` e executando:
```bash
voxvera import-multiple
```
## Portabilidade e Uso Offline
Se precisar executar o VoxVera em uma máquina sem acesso à internet, você pode "venderizar" as dependências primeiro:
```bash
voxvera vendorize
```
Isso baixa todas as bibliotecas Python necessárias para `voxvera/vendor/`. A ferramenta priorizará esses arquivos locais, permitindo que ela funcione sem `pip install`.
## Importação em Lote (JSON)
Para gerar panfletos em massa a partir de vários arquivos de configuração JSON, coloque-os no diretório `imports/` e execute:
```bash
voxvera batch-import
```
## Como as URLs Funcionam
Cada panfleto tem duas URLs separadas:
- **Link destacável** (gerado automaticamente): O endereço .onion onde o panfleto está hospedado.
- **Link de conteúdo** (configurado pelo usuário): Uma URL externa apontando para um site, vídeo ou download.
Você não precisa inserir manualmente o endereço .onion; o VoxVera lida com isso automaticamente durante a fase de `serve`.
docs/roadmap-platform-parity.md
-280
View File
@@ -1,280 +0,0 @@
# Platform Parity Roadmap
This roadmap focuses on one question:
How do we expand VoxVera beyond Linux without overstating reliability, while still converging on real cross-platform parity for Tor hidden-service hosting?
## Strategic Principle
Parity is not a packaging milestone. It is a runtime-contract milestone.
Every platform must eventually implement the same hosting contract:
1. install VoxVera
2. ensure Tor and OnionShare are available
3. build site assets
4. serve the hidden service
5. preserve `.onionshare-session`
6. recover hosting after reboot, login, suspend, or offline periods
7. surface logs and status
Package formats should inherit that contract. They should not define independent behavior.
## Phase 0: Truth Alignment
Goal: bring repo claims, docs, and release posture into line with current reality.
Deliverables:
- canonical support matrix
- machine-readable support declaration
- installer/package warnings for experimental paths
- README and docs aligned to the actual supported target
Definition of done:
- no docs imply parity that tests do not support
- every platform surface has an explicit support tier
- release artifacts are not treated as proof of hosting reliability
## Phase 1: Harden Linux As Reference
Goal: make Linux CLI with `systemd --user` the clearly defensible model that other platforms copy.
Work items:
1. Add `voxvera doctor` for runtime validation.
- Check Tor reachability.
- Check OnionShare availability.
- Check `start-all` surfaces.
- Check autostart timer installation.
- Check host directories and session files.
2. Add `voxvera autostart status`.
- Show service and timer files.
- Show whether the timer is enabled.
- Show next/last run timestamps if available.
3. Normalize Linux log/status guidance.
- Document host log paths.
- Document timer/service status commands.
- Document expected recovery flow after reboot/network loss.
4. Validate restart behavior.
- fresh install
- first serve
- reboot
- suspend/resume if possible
- temporary offline period followed by reconnect
Definition of done:
- Linux remains the only `supported` path until the above evidence exists and is documented.
## Phase 2: Platform Adapter Layer
Goal: stop encoding platform logic in ad hoc installer scripts.
Recommended structure:
- `voxvera/platforms/base.py`
- `voxvera/platforms/linux.py`
- `voxvera/platforms/macos.py`
- `voxvera/platforms/windows.py`
- `voxvera/platforms/docker.py`
Each adapter should define:
- support tier
- Tor discovery strategy
- OnionShare discovery strategy
- state root
- autostart installation strategy
- autostart status strategy
- log/status surface
- known limitations
CLI surfaces to add:
- `voxvera doctor`
- `voxvera platform-status`
- `voxvera autostart`
- `voxvera autostart status`
- `voxvera autostart uninstall`
Definition of done:
- shell installers become thin wrappers over shared Python logic instead of owning runtime policy themselves
## Phase 3: Docker Beta Candidate
Goal: make Docker a coherent, testable deployment surface.
Decisions to settle:
- single-container runtime vs compose-based runtime
- host Tor vs container Tor
- log and state persistence model
Recommended direction:
- keep runtime state under one explicit volume root
- document restart policy clearly
- make health and recovery behavior observable
Validation checklist:
- container restart preserves onion identity
- host reboot with restart policy restores hosting
- state remains in mounted volume
- logs remain inspectable
Promotion target:
- `experimental` -> `beta`
## Phase 4: macOS CLI
Goal: establish one honest CLI-based macOS hosting model before packaging.
Work items:
1. define Tor discovery strategy
2. define OnionShare discovery/install strategy
3. validate manual `build` + `serve`
4. implement and validate `launchd` recovery
5. document known limitations
Promotion target:
- remain `experimental` until `launchd` recovery is validated
- move to `beta` only after login/reboot/offline recovery evidence exists
## Phase 5: Windows CLI
Goal: establish one canonical Windows runtime model before claiming package parity.
Work items:
1. unify binary naming across installer, Chocolatey, docs, and release assets
2. define Tor discovery strategy
3. define OnionShare discovery strategy
4. validate manual `build` + `serve`
5. implement Task Scheduler recovery path
6. add Windows-specific status/log guidance
Promotion target:
- remain `experimental` until scheduled recovery and state persistence are proven
- move to `beta` only after reboot/login/offline recovery evidence exists
## Phase 6: Electron GUI Convergence
Goal: make the GUI a frontend to the supported runtime, not a separate runtime.
Work items:
1. route the GUI through shared CLI/runtime surfaces
2. reduce duplicated Tor startup behavior
3. add visibility for:
- Tor status
- OnionShare status
- hosting status
- onion URL
- logs
4. make window-close behavior explicit and safe
Promotion target:
- GUI remains `experimental` until it stops diverging from the CLI runtime contract
## Phase 7: Package Surface Promotion
Goal: package formats should become trustworthy wrappers around validated runtimes.
Work items:
1. Debian package
- declare actual runtime dependencies
- validate install + host + recovery path
2. AppImage
- decide whether it is distribution-only or a real hosting target
3. Homebrew
- fix artifact URL/sha/version policy
- clarify whether it installs a hosting target or just a CLI
4. Chocolatey
- align artifact naming and installer semantics
5. Flatpak
- decide whether Tor/OnionShare can be supported sanely in-sandbox
Rule:
- no package surface should be promoted above the support tier of its underlying runtime
## Testing Program
### 1. Unit tests
- config/state logic
- autostart file generation
- platform adapter selection
### 2. Mocked integration tests
- `serve`
- `autostart`
- `doctor`
- `platform-status`
### 3. Platform smoke tests
- fresh install
- build
- serve
- persist identity
- restart
- recover
Current smoke target names:
- `linux-cli`
- `macos-cli`
- `windows-cli`
- `docker-cli`
These target names are contract-level validation entry points. Only `linux-cli` currently represents a supported hosting path; the others should be used to validate experimental posture and dependency discovery on their native platforms until their recovery behavior is proven.
### 4. Release checks
- support matrix is current
- docs match support tiers
- artifact names match scripts and package manifests
## Immediate Next Tasks
1. Add `voxvera doctor`.
2. Add `voxvera autostart status`.
## Native Validation Assets
The repo now includes concrete native-host validation docs for the two major experimental desktop targets:
- `docs/macos-validation-checklist.md`
- `docs/windows-validation-checklist.md`
- `docs/native-tester-guide.md`
These should be used for the first real macOS/Windows validation cycles so testers capture the runtime evidence needed for future tier promotion.
3. Add the platform adapter scaffold.
4. Capture Linux reboot/offline recovery validation steps in docs and CI notes.
5. Pick Docker's canonical runtime model.
6. Normalize Windows binary naming before further Windows work.
## Non-Goals
- claiming parity before recovery behavior is validated
- treating package availability as support proof
- maintaining separate runtime semantics in GUI vs CLI
docs/roadmap-v0.2.0.md
-93
View File
@@ -1,93 +0,0 @@
# VoxVera Roadmap & Technical Specification (v0.2.0)
This document outlines the next major evolution of the VoxVera project, focusing on trust, social amplification, visual versatility, and network resilience.
---
## 1. Integrity & Trust (PGP Signing)
**Goal:** Provide cryptographic proof that the `voxvera-portable.zip` provided by a flyer has not been tampered with by the hoster.
### Technical Requirements
- **CLI:** Add `voxvera sign <folder_name>` command.
- **Dependency:** Use a lightweight PGP implementation (e.g., `python-gnupg` or `pgpy`) to sign the portable ZIP.
- **Storage:** Generate a `.sig` or `.asc` file alongside the ZIP in the `download/` folder.
- **Web:** The landing page will look for `voxvera-portable.zip.asc`. If found, a **"Verified Source"** badge with the signer's Fingerprint will appear next to the download button.
### Implementation Phases
1. **Phase 1:** Add PGP key generation/import logic to `voxvera init`.
2. **Phase 2:** Update `build_assets` to optionally sign the generated ZIP.
3. **Phase 3:** Update `index-master.html` to display verification status.
---
## 2. Nostr Integration (Social Amplification)
**Goal:** Bridge the physical world (flyers) with the decentralized digital world (Nostr) by automatically broadcasting live .onion sites.
### Technical Requirements
- **CLI:** Add `voxvera serve --nostr` flag.
- **Workflow:** When a site goes live and the `.onion` URL is generated, the tool posts a "Flyer Event" to a list of configured Nostr relays.
- **Identity:** Users can provide an existing NSEC or have VoxVera generate a "Flyer Identity" (new NPUB) for that specific server.
- **Metadata:** Include tags for the flyer title, headline, and the `.onion` link.
### Implementation Phases
1. **Phase 1:** Add `nostr` and `bech32` to the `vendor/` directory.
2. **Phase 2:** Implement a background broadcast thread in `serve()`.
3. **Phase 3:** Add "View on Nostr" links to the flyer footer.
---
## 3. The "Tear-off" Designer (Template Gallery)
**Goal:** Expand the utility of VoxVera to new use cases like missing person alerts, protest organizing, and artistic distribution.
### Technical Requirements
- **Restructuring:** Move from a single `voxvera` template to a category-based system:
- `/templates/default/` (The original Operation VoxVera style)
- `/templates/minimal/` (Clean, text-heavy)
- `/templates/alert/` (High-contrast, for emergencies)
- `/templates/art/` (Image-focused)
- **CLI:** Update `voxvera init` to include a visual description and selector for templates.
### Implementation Phases
1. **Phase 1:** Refactor `copy_template` to support categories.
2. **Phase 2:** Design and implement 3 new HTML/CSS templates.
3. **Phase 3:** Allow templates to define their own custom character limits (e.g., "Alert" might allow larger headlines).
---
## 4. Self-Healing Network (Update Logic)
**Goal:** Ensure the decentralized "Viral" network stays current with security fixes and features.
### Technical Requirements
- **Discovery:** The tool will check a "Source of Truth" (e.g., `voxvera.org/version.json` or a hardcoded list of onion mirrors).
- **Notification:** `voxvera manage` will show a 🌟 or ⚠️ next to the version number if an update is available.
- **Update Workflow:** Provide a `voxvera update` command that downloads the latest `voxvera-portable.zip` and safely replaces the `vendor/` and `voxvera/` directories.
### Implementation Phases
1. **Phase 1:** Implement version-checking logic via Tor SOCKS proxy.
2. **Phase 2:** Add update notifications to the management menu.
3. **Phase 3:** (Advanced) Implement "In-Place" updates for the vendored dependencies.
---
## 5. GUI Modernization
**Goal:** Transition the Electron wrapper from a CLI mirror to a rich, visual dashboard.
### Technical Requirements
- **Flyer Cards:** Replace the text list with visual "cards" showing the flyer's headline and a mini QR preview.
- **Tor Dashboard:** A dedicated tab showing all active hidden services, their uptime, and their `.onion` links.
- **One-Click Actions:** Visual buttons for "Export All," "Start All," and "New Flyer."
- **Direct Log Stream:** A collapsible panel to see the OnionShare logs in real-time.
### Implementation Phases
1. **Phase 1:** Update the IPC bridge between Electron and the Python CLI.
2. **Phase 2:** Redesign the frontend using a modern, dark-themed CSS framework (keeping it local-first).
3. **Phase 3:** Add a "Theme Preview" during the flyer creation process.
---
## Summary of Impact
By completing this roadmap, VoxVera moves from a standalone utility to a **Decentralized Information Ecosystem**.
- **Security** is solved via PGP.
- **Reach** is solved via Nostr.
- **Versatility** is solved via the Template Gallery.
- **Sustainability** is solved via Update Logic.
docs/ru/AGENTS.md
-42
View File
@@ -1,42 +0,0 @@
# AI Agent Instructions for VoxVera
This guide is for AI agents (like Gemini, Claude, or GPT) contributing to the VoxVera project. Follow these protocols to maintain the architectural integrity and multi-language support.
## Core Mandates
1. **Security-First**: VoxVera is a Tor-based tool. Never suggest features that leak IP addresses or use non-Tor external resources (CDNs, etc.).
2. **Local-First**: All assets (fonts, dependencies, binaries) must be self-contained within the `voxvera/` package to support the Universal Mirroring model.
3. **Tokenized UI**: Never hardcode user-facing strings. Always add them to `voxvera/locales/en.json` and use the `t('cli.token')` helper.
4. **Markdown Redaction**: Use `~~text~~` in locale JSONs for strike-through effects. Both the build system and the JS engine handle the conversion to `<span class="redacted">` automatically.
5. **Visual Width Testing**: When modifying UI or adding languages, verify that long or complex strings (e.g., Hindi ligatures or CJK characters) do not exceed the visual unit limits defined in the CLI.
## Localization Protocol
When adding a new language or updating an existing one:
- **CLI/Flyers**: Update `voxvera/locales/{lang}.json`. Include `meta`, `cli`, `web`, and `landing` categories.
- **Landing Page**:
- Directly update the `const locales` object in `site/index.html`.
- **Crucial**: Run `voxvera build-site` to generate the latest portable bundle and refresh the pre-rendered HTML.
- **Documentation**:
- Master templates live in `docs/templates/`.
- Localized overrides live in `voxvera/locales/{lang}/docs/`.
- **Crucial**: After any change to locales or templates, you MUST run `voxvera build-docs` to synchronize the output in `docs/{en,es,de}/`.
## Universal Mirroring
VoxVera propagates through its own flyers.
- Every `voxvera build` and `voxvera build-site` generates `voxvera-portable.zip`.
- If you modify the core source code, ensure the `bundle_portable` function in `voxvera/cli.py` still correctly captures all necessary directories (especially `vendor/`, `locales/`, and `resources/`).
## Verification Checklist
Before finishing a task, ensure you have:
1. Run unit tests: `pytest tests/test_cli.py`.
2. Verified the localization: `voxvera --lang {lang} check`.
3. Rebuilt the documentation: `voxvera build-docs`.
4. Synchronized the public site: `voxvera build-site`.
5. Verified the portable bundle exists: `ls -l voxvera/host/*/download/voxvera-portable.zip` and `ls -l site/download/voxvera-portable.zip`.
---
Follow these rules to ensure VoxVera remains a robust, viral, and decentralized tool for truth.
docs/ru/CONTRIBUTING.md
-47
View File
@@ -1,47 +0,0 @@
# Contributing to VoxVera
Thank you for your interest in contributing to VoxVera! This project aims to be a global, censorship-resistant tool, and your help—especially with translations—is vital.
## Adding a New Language
VoxVera uses a centralized token system for the CLI and Web components, and a template-based system for Documentation. To add a new language (e.g., French/`fr`), follow this checklist:
### 1. The Token File
Create a new JSON file in `voxvera/locales/{lang_code}.json`.
- Use `en.json` as your master template.
- **`meta`**: Include the native language name and a flag emoji.
- **`cli`**: Translate all strings used in the terminal interface.
- **`web`**: Translate strings used on the generated landing pages and flyers.
- **`landing`**: Translate the specific content for the official VoxVera website.
- **Formatting**: You can use Markdown-style strike-throughs (`~~redacted text~~`) in any of these strings; they will be automatically converted to the stylized "redacted" effect on the flyers.
### 2. The Landing Page
The main landing page is generated from the shared template and locale files.
- Add your language in `voxvera/locales/{lang_code}.json`.
- Do **not** edit `site/index.html` directly; it is generated output.
- Run `voxvera build-site` to refresh the public assets and inject your new locale into the generated HTML.
### 3. Documentation
VoxVera uses the **Doc-Sync Engine** to keep manuals in sync.
- Create localized Markdown files in `voxvera/locales/{lang_code}/docs/`.
- Use the templates in `docs/templates/` as your guide.
- You can use `cli.token_name` to reference terminal commands automatically.
### 4. Build and Verify
Run the following commands to verify your changes:
- `voxvera --lang {lang_code} check` (Verify CLI translation)
- `voxvera build-docs` (Generate localized manuals)
- `voxvera build-site` (Synchronize the public website and generate the latest portable bundle)
- Open the generated `site/index.html` in a browser and test the language switcher.
## Code Contributions
- **Dependencies**: if you add a new Python library to `requirements.txt`, you MUST run `voxvera vendorize` to include it in the portable distribution.
- **Layout Integrity**: VoxVera uses visual width validation. If you add new UI elements, ensure they respect the physical boundaries of an 8.5"x11" flyer.
- **Tests**: Ensure all tests pass: `pytest tests/`. Run the integrity suite specifically when modifying locales: `pytest tests/test_integrity.py`.
- **Generated artifacts**: Treat `voxvera/resources/bin/` as local build output, not source files. Release binaries belong in GitHub Releases, not hand-edited repo state.
- **Style**: Follow the existing coding style (PEP 8 for Python).
- **Documentation**: If adding a new feature, update the master templates in `docs/templates/` and run `voxvera build-docs`.
---
Together, we can ensure that truth remains accessible to everyone, everywhere.
docs/ru/docker.md
-48
View File
@@ -1,48 +0,0 @@
# Docker Usage
Experimental: the container path is not yet a production-grade hidden-service deployment target. Linux with `systemd --user` remains the supported persistent-host environment.
A prebuilt image containing Tor, OnionShare and the `voxvera` CLI is published to
`ghcr.io/voxvera/voxvera`.
```bash
# pull the image
docker pull ghcr.io/voxvera/voxvera:latest
# run the experimental container with flyers stored in ./flyers
mkdir -p flyers
docker run -d \
--name voxvera \
--restart unless-stopped \
-v "$(pwd)/flyers:/flyers" \
ghcr.io/voxvera/voxvera:latest
```
The container now uses a dedicated entrypoint that:
- stores runtime state under `/flyers`
- seeds `/flyers/config.json` if needed
- starts an in-container Tor daemon on `127.0.0.1:9050/9051`
- bootstraps a default site when `/flyers/host` is empty
- runs `voxvera start-all` on startup and retries it periodically
- exposes a container healthcheck based on `voxvera doctor --json`
Useful commands:
```bash
docker logs -f voxvera
docker exec -it voxvera voxvera doctor --json
docker exec -it voxvera voxvera autostart status --json
```
If you prefer Compose:
```yaml
services:
voxvera:
image: ghcr.io/voxvera/voxvera:latest
restart: unless-stopped
volumes:
- ./flyers:/flyers
```
Use this path for testing only until the container runtime and background recovery behavior are validated end-to-end.
docs/ru/templates.md
-14
View File
@@ -1,14 +0,0 @@
# Flyer Templates
Pre-built flyer templates live in the `templates/` directory. Use the CLI to copy one with:
```bash
voxvera init --template <name>
```
This will create a new folder under `dist/` named `<name>-<YYYYMMDD>` containing the template files.
Available templates:
- **blank** – minimal placeholder files, also used when extracting fields from a PDF.
- **voxvera** – example flyer showcasing the VoxVera project.
docs/ru/troubleshooting.md
-75
View File
@@ -1,75 +0,0 @@
# Troubleshooting
This page collects common issues encountered when hosting or accessing flyers.
## Tor connectivity
- Ensure Tor is allowed through your firewall. On systems using `ufw` you may need to run `sudo ufw allow tor`.
- Some networks block Tor entirely. If you cannot reach onion services, try connecting over a different network or use a Tor bridge.
## Supported deployment target
- The supported persistent-host setup is Linux with `systemd --user`.
- Windows, macOS, Docker, Flatpak, AppImage, Homebrew, and Chocolatey are currently experimental and may not recover hosting automatically after reboot or network interruptions.
## Tor port detection
`voxvera serve` auto-detects Tor by probing common ports (9050/9150 for SOCKS, 9051/9151 for control). If detection fails -- for example when Tor runs on non-standard ports -- you can override with environment variables:
```bash
TOR_SOCKS_PORT=19050 TOR_CONTROL_PORT=19051 voxvera serve
```
If no running Tor is found, the defaults (9050/9051) are used and OnionShare will attempt to connect on those ports.
## Firewall rules
- If `voxvera serve` fails to start OnionShare, verify that outbound connections on ports 9001 and 80 are permitted.
- Corporate or university firewalls can block the hidden service ports required by Tor.
## SELinux
- On SELinux-enabled distributions you may see `permission denied` errors when OnionShare writes to the `host` directory.
- Run `sudo chcon -Rt svirt_sandbox_file_t host` or disable SELinux enforcement for the folder.
## OnionShare crashes
If `voxvera serve` prints "OnionShare exited unexpectedly", check the log file
`host/<folder_name>/onionshare.log` for details. Common causes:
- Tor is not running (`sudo systemctl start tor`)
- A port conflict with another service
- Missing `onionshare-cli` (run `voxvera check`)
## Onion URL changed unexpectedly
The onion URL is tied to the Ed25519 keypair stored in
`host/<folder_name>/.onionshare-session`. If this file is deleted, a new
keypair (and URL) will be generated on the next `voxvera serve`. The
`voxvera import` command preserves this file automatically, but manual
deletion of the `host/` directory will destroy it.
## Hosting does not return after reboot or network loss
On Linux, install or verify the recovery timer:
```bash
voxvera autostart
systemctl --user status voxvera-start.timer
systemctl --user status voxvera-start.service
```
The supported recovery path is the recurring `systemd --user` timer, which reruns `voxvera start-all` every few minutes.
## QR codes not generated
If `voxvera build` reports "No URLs configured yet", this is expected before the first `voxvera serve`. QR codes for tear-off links are generated automatically once the .onion address is known. QR codes for the content link are generated if you provided a URL during `voxvera init`.
## Electron GUI
If `npm start` fails with `spawn voxvera ENOENT`, the `voxvera` command is not in your `PATH`. Install it with `pipx install git+https://github.com/PR0M3TH3AN/VoxVera.git` or run `./install.sh` from the repository.
## Missing dependencies
Run `voxvera check` to verify your setup. The command checks for required
Python packages (`qrcode`, `Pillow`, `jsmin`, `htmlmin`, `pypdf`) and
external tools (`onionshare-cli`), then prints a summary of anything
missing. To install everything:
```bash
# Recommended: use the install script (handles Tor + OnionShare too)
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
# Or reinstall just the Python package
pipx install --force 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
```
docs/ru/usage.md
-130
View File
@@ -1,130 +0,0 @@
# Подробное руководство
Это руководство охватывает основные рабочие процессы CLI. См. `docs/docker.md` для инструкций по Docker и `docs/templates.md` для доступных шаблонов листовок.
## Предварительные требования
VoxVera разработан как высокопортативный инструмент и требует минимум системных зависимостей.
### 1. Автономные бинарные файлы (Рекомендуется)
Вы можете скачать автономные исполняемые файлы без зависимостей для вашей операционной системы:
- **Linux:** `voxvera-linux`
- **Windows:** `voxvera-windows.exe`
- **macOS:** `voxvera-macos`
Эти файлы включают все необходимое для запуска VoxVera (кроме `onionshare-cli`).
### 2. Однострочный установщик
Или установите с помощью нашего автоматического скрипта:
```bash
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
```
### 3. Ручная установка через Python
Если вы предпочитаете запускать из исходного кода:
```bash
pipx install 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
sudo apt install tor onionshare-cli # Debian/Ubuntu
```
## Шаг за шагом
1. **Инициализация:** Запустите `voxvera init` и следуйте подсказкам. Вам будет предложено сначала выбрать язык.
2. **Сборка:** Сгенерируйте ресурсы листовки. Каждая сборка автоматически создает файл `voxvera-portable.zip` в папке листовки, позволяя другим скачивать полный инструмент прямо с вашей листовки.
```bash
voxvera build
```
3. **Запуск:** Опубликуйте листовку через Tor:
```bash
voxvera serve
```
Это автоматически обнаружит ваш экземпляр Tor, запустит OnionShare и запишет сгенерированный .onion адрес в отрывные ссылки листовки.
## Поддержка языков
VoxVera полностью локализован. Вы можете изменить свои языковые предпочтения навсегда, используя интерактивный селектор или прямой ярлык:
- **Интерактивный селектор:** `voxvera lang`
- **Прямой ярлык:** `voxvera --lang ru` (устанавливает русский язык)
### Поддерживаемые языки:
- **Английский:** `en`
- **Испанский:** `es` (алиас: `--idioma`)
- **Немецкий:** `de` (алиас: `--sprache`)
- **Русский:** `ru`
Вы также можете принудительно использовать определенный язык для одной команды, не меняя постоянные настройки:
- **Английский:** `voxvera --lang en check`
- **Русский:** `voxvera --lang ru check`
Сгенерированные листовки автоматически определяют язык браузера посетителя и соответствующим образом переключают текст интерфейса.
## Управление серверами
Управляйте несколькими листовками и их Tor-идентификаторами из единого интерактивного меню:
```bash
voxvera manage
```
Возможности:
- **--- Создать новый сайт/листовку ---**: Запуск полной последовательности настройки.
- **--- Запустить все сайты ---**: Запуск или остановка всех листовок в вашем парке одновременно.
- **Статус в реальном времени**: Просмотр активных .onion URL и индикаторов прогресса загрузки Tor.
- **Индивидуальный контроль**: Экспорт в Zip определенных сайтов в ZIP или их удаление.
## Универсальное зеркалирование (Вирусное распространение)
Чтобы VoxVera оставался доступным, даже если центральные репозитории будут подвергнуты цензуре, каждая листовка выступает в качестве зеркала для инструмента.
Когда вы хостите листовку, кнопка **"Скачать инструмент и код"** на целевой странице предоставляет `voxvera-portable.zip`, содержащий:
- Полный исходный код и все поддерживаемые языки.
- Все зависимости Python (пре-вендоризованные).
- Кроссплатформенные бинарные файлы Tor.
Это позволяет любому, кто сканирует вашу листовку, стать новым распространителем инструмента VoxVera.
## Экспорт и резервное копирование
Создавайте резервные копии своих уникальных Tor-идентификаторов (чтобы ваш .onion URL никогда не менялся) или переносите листовки на другую машину.
- **Экспорт одного сайта**: `voxvera export <имя_папки>`
- **Экспорт всех сайтов**: `voxvera export-all`
**Место хранения:** Все экспорты сохраняются в виде ZIP-файлов в папке `voxvera-exports` в домашнем каталоге пользователя (`~/voxvera-exports/`) на всех платформах.
## Импорт и восстановление
Восстановите всю свою настройку на новой машине, переместив ZIP-файлы в `~/voxvera-exports/` и запустив:
```bash
voxvera import-multiple
```
## Портативность и работа оффлайн
Если вам нужно запустить VoxVera на машине без доступа к Интернету, вы можете сначала «вендоризовать» зависимости:
```bash
voxvera vendorize
```
Это загрузит все необходимые библиотеки Python в `voxvera/vendor/`. Инструмент будет отдавать приоритет этим локальным файлам, что позволит ему работать без `pip install`.
## Пакетный импорт (JSON)
Чтобы массово генерировать листовки из нескольких конфигурационных файлов JSON, поместите их в директорию `imports/` и запустите:
```bash
voxvera batch-import
```
## Как работают URL-адреса
У каждой листовки есть два отдельных URL-адреса:
- **Отрывная ссылка** (автоматически генерируется): .onion адрес, по которому размещена листовка.
- **Ссылка на контент** (настраивается пользователем): Внешний URL, указывающий на веб-сайт, видео или загрузку.
Вам не нужно вручную вводить .onion адрес; VoxVera обрабатывает это автоматически на этапе `serve`.
docs/sw/AGENTS.md
-42
View File
@@ -1,42 +0,0 @@
# AI Agent Instructions for VoxVera
This guide is for AI agents (like Gemini, Claude, or GPT) contributing to the VoxVera project. Follow these protocols to maintain the architectural integrity and multi-language support.
## Core Mandates
1. **Security-First**: VoxVera is a Tor-based tool. Never suggest features that leak IP addresses or use non-Tor external resources (CDNs, etc.).
2. **Local-First**: All assets (fonts, dependencies, binaries) must be self-contained within the `voxvera/` package to support the Universal Mirroring model.
3. **Tokenized UI**: Never hardcode user-facing strings. Always add them to `voxvera/locales/en.json` and use the `t('cli.token')` helper.
4. **Markdown Redaction**: Use `~~text~~` in locale JSONs for strike-through effects. Both the build system and the JS engine handle the conversion to `<span class="redacted">` automatically.
5. **Visual Width Testing**: When modifying UI or adding languages, verify that long or complex strings (e.g., Hindi ligatures or CJK characters) do not exceed the visual unit limits defined in the CLI.
## Localization Protocol
When adding a new language or updating an existing one:
- **CLI/Flyers**: Update `voxvera/locales/{lang}.json`. Include `meta`, `cli`, `web`, and `landing` categories.
- **Landing Page**:
- Directly update the `const locales` object in `site/index.html`.
- **Crucial**: Run `voxvera build-site` to generate the latest portable bundle and refresh the pre-rendered HTML.
- **Documentation**:
- Master templates live in `docs/templates/`.
- Localized overrides live in `voxvera/locales/{lang}/docs/`.
- **Crucial**: After any change to locales or templates, you MUST run `voxvera build-docs` to synchronize the output in `docs/{en,es,de}/`.
## Universal Mirroring
VoxVera propagates through its own flyers.
- Every `voxvera build` and `voxvera build-site` generates `voxvera-portable.zip`.
- If you modify the core source code, ensure the `bundle_portable` function in `voxvera/cli.py` still correctly captures all necessary directories (especially `vendor/`, `locales/`, and `resources/`).
## Verification Checklist
Before finishing a task, ensure you have:
1. Run unit tests: `pytest tests/test_cli.py`.
2. Verified the localization: `voxvera --lang {lang} check`.
3. Rebuilt the documentation: `voxvera build-docs`.
4. Synchronized the public site: `voxvera build-site`.
5. Verified the portable bundle exists: `ls -l voxvera/host/*/download/voxvera-portable.zip` and `ls -l site/download/voxvera-portable.zip`.
---
Follow these rules to ensure VoxVera remains a robust, viral, and decentralized tool for truth.
docs/sw/CONTRIBUTING.md
-47
View File
@@ -1,47 +0,0 @@
# Contributing to VoxVera
Thank you for your interest in contributing to VoxVera! This project aims to be a global, censorship-resistant tool, and your help—especially with translations—is vital.
## Adding a New Language
VoxVera uses a centralized token system for the CLI and Web components, and a template-based system for Documentation. To add a new language (e.g., French/`fr`), follow this checklist:
### 1. The Token File
Create a new JSON file in `voxvera/locales/{lang_code}.json`.
- Use `en.json` as your master template.
- **`meta`**: Include the native language name and a flag emoji.
- **`cli`**: Translate all strings used in the terminal interface.
- **`web`**: Translate strings used on the generated landing pages and flyers.
- **`landing`**: Translate the specific content for the official VoxVera website.
- **Formatting**: You can use Markdown-style strike-throughs (`~~redacted text~~`) in any of these strings; they will be automatically converted to the stylized "redacted" effect on the flyers.
### 2. The Landing Page
The main landing page is generated from the shared template and locale files.
- Add your language in `voxvera/locales/{lang_code}.json`.
- Do **not** edit `site/index.html` directly; it is generated output.
- Run `voxvera build-site` to refresh the public assets and inject your new locale into the generated HTML.
### 3. Documentation
VoxVera uses the **Doc-Sync Engine** to keep manuals in sync.
- Create localized Markdown files in `voxvera/locales/{lang_code}/docs/`.
- Use the templates in `docs/templates/` as your guide.
- You can use `cli.token_name` to reference terminal commands automatically.
### 4. Build and Verify
Run the following commands to verify your changes:
- `voxvera --lang {lang_code} check` (Verify CLI translation)
- `voxvera build-docs` (Generate localized manuals)
- `voxvera build-site` (Synchronize the public website and generate the latest portable bundle)
- Open the generated `site/index.html` in a browser and test the language switcher.
## Code Contributions
- **Dependencies**: if you add a new Python library to `requirements.txt`, you MUST run `voxvera vendorize` to include it in the portable distribution.
- **Layout Integrity**: VoxVera uses visual width validation. If you add new UI elements, ensure they respect the physical boundaries of an 8.5"x11" flyer.
- **Tests**: Ensure all tests pass: `pytest tests/`. Run the integrity suite specifically when modifying locales: `pytest tests/test_integrity.py`.
- **Generated artifacts**: Treat `voxvera/resources/bin/` as local build output, not source files. Release binaries belong in GitHub Releases, not hand-edited repo state.
- **Style**: Follow the existing coding style (PEP 8 for Python).
- **Documentation**: If adding a new feature, update the master templates in `docs/templates/` and run `voxvera build-docs`.
---
Together, we can ensure that truth remains accessible to everyone, everywhere.
docs/sw/docker.md
-48
View File
@@ -1,48 +0,0 @@
# Docker Usage
Experimental: the container path is not yet a production-grade hidden-service deployment target. Linux with `systemd --user` remains the supported persistent-host environment.
A prebuilt image containing Tor, OnionShare and the `voxvera` CLI is published to
`ghcr.io/voxvera/voxvera`.
```bash
# pull the image
docker pull ghcr.io/voxvera/voxvera:latest
# run the experimental container with flyers stored in ./flyers
mkdir -p flyers
docker run -d \
--name voxvera \
--restart unless-stopped \
-v "$(pwd)/flyers:/flyers" \
ghcr.io/voxvera/voxvera:latest
```
The container now uses a dedicated entrypoint that:
- stores runtime state under `/flyers`
- seeds `/flyers/config.json` if needed
- starts an in-container Tor daemon on `127.0.0.1:9050/9051`
- bootstraps a default site when `/flyers/host` is empty
- runs `voxvera start-all` on startup and retries it periodically
- exposes a container healthcheck based on `voxvera doctor --json`
Useful commands:
```bash
docker logs -f voxvera
docker exec -it voxvera voxvera doctor --json
docker exec -it voxvera voxvera autostart status --json
```
If you prefer Compose:
```yaml
services:
voxvera:
image: ghcr.io/voxvera/voxvera:latest
restart: unless-stopped
volumes:
- ./flyers:/flyers
```
Use this path for testing only until the container runtime and background recovery behavior are validated end-to-end.
docs/sw/templates.md
-14
View File
@@ -1,14 +0,0 @@
# Flyer Templates
Pre-built flyer templates live in the `templates/` directory. Use the CLI to copy one with:
```bash
voxvera init --template <name>
```
This will create a new folder under `dist/` named `<name>-<YYYYMMDD>` containing the template files.
Available templates:
- **blank** – minimal placeholder files, also used when extracting fields from a PDF.
- **voxvera** – example flyer showcasing the VoxVera project.
docs/sw/troubleshooting.md
-75
View File
@@ -1,75 +0,0 @@
# Troubleshooting
This page collects common issues encountered when hosting or accessing flyers.
## Tor connectivity
- Ensure Tor is allowed through your firewall. On systems using `ufw` you may need to run `sudo ufw allow tor`.
- Some networks block Tor entirely. If you cannot reach onion services, try connecting over a different network or use a Tor bridge.
## Supported deployment target
- The supported persistent-host setup is Linux with `systemd --user`.
- Windows, macOS, Docker, Flatpak, AppImage, Homebrew, and Chocolatey are currently experimental and may not recover hosting automatically after reboot or network interruptions.
## Tor port detection
`voxvera serve` auto-detects Tor by probing common ports (9050/9150 for SOCKS, 9051/9151 for control). If detection fails -- for example when Tor runs on non-standard ports -- you can override with environment variables:
```bash
TOR_SOCKS_PORT=19050 TOR_CONTROL_PORT=19051 voxvera serve
```
If no running Tor is found, the defaults (9050/9051) are used and OnionShare will attempt to connect on those ports.
## Firewall rules
- If `voxvera serve` fails to start OnionShare, verify that outbound connections on ports 9001 and 80 are permitted.
- Corporate or university firewalls can block the hidden service ports required by Tor.
## SELinux
- On SELinux-enabled distributions you may see `permission denied` errors when OnionShare writes to the `host` directory.
- Run `sudo chcon -Rt svirt_sandbox_file_t host` or disable SELinux enforcement for the folder.
## OnionShare crashes
If `voxvera serve` prints "OnionShare exited unexpectedly", check the log file
`host/<folder_name>/onionshare.log` for details. Common causes:
- Tor is not running (`sudo systemctl start tor`)
- A port conflict with another service
- Missing `onionshare-cli` (run `voxvera check`)
## Onion URL changed unexpectedly
The onion URL is tied to the Ed25519 keypair stored in
`host/<folder_name>/.onionshare-session`. If this file is deleted, a new
keypair (and URL) will be generated on the next `voxvera serve`. The
`voxvera import` command preserves this file automatically, but manual
deletion of the `host/` directory will destroy it.
## Hosting does not return after reboot or network loss
On Linux, install or verify the recovery timer:
```bash
voxvera autostart
systemctl --user status voxvera-start.timer
systemctl --user status voxvera-start.service
```
The supported recovery path is the recurring `systemd --user` timer, which reruns `voxvera start-all` every few minutes.
## QR codes not generated
If `voxvera build` reports "No URLs configured yet", this is expected before the first `voxvera serve`. QR codes for tear-off links are generated automatically once the .onion address is known. QR codes for the content link are generated if you provided a URL during `voxvera init`.
## Electron GUI
If `npm start` fails with `spawn voxvera ENOENT`, the `voxvera` command is not in your `PATH`. Install it with `pipx install git+https://github.com/PR0M3TH3AN/VoxVera.git` or run `./install.sh` from the repository.
## Missing dependencies
Run `voxvera check` to verify your setup. The command checks for required
Python packages (`qrcode`, `Pillow`, `jsmin`, `htmlmin`, `pypdf`) and
external tools (`onionshare-cli`), then prints a summary of anything
missing. To install everything:
```bash
# Recommended: use the install script (handles Tor + OnionShare too)
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
# Or reinstall just the Python package
pipx install --force 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
```
docs/sw/usage.md
-130
View File
@@ -1,130 +0,0 @@
# Maelezo ya Matumizi
Mwongozo huu unashughulikia taratibu za kawaida za CLI. Angalia `docs/docker.md` kwa maelekezo ya Docker na `docs/templates.md` kwa violezo vya vipeperushi vinavyopatikana.
## Mahitaji ya Awali
VoxVera imeundwa kuwa rahisi kubebeka na inahitaji vitegemezi vichache vya mfumo.
### 1. Programu Zinazojitegemea (Zinazopendekezwa)
Unaweza kupakua programu zinazojitegemea na zisizo na vitegemezi kwa mfumo wako wa uendeshaji:
- **Linux:** `voxvera-linux`
- **Windows:** `voxvera-windows.exe`
- **macOS:** `voxvera-macos`
Programu hizi zinajumuisha kila kitu kinachohitajika ili kuendesha VoxVera (isipokuwa `onionshare-cli`).
### 2. Kisakinishi cha Mstari Mmoja
Vinginevyo, sakinisha kupitia hati yetu ya kiotomatiki:
```bash
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
```
### 3. Usakinishaji wa Mwongozo wa Python
Ikiwa unapendelea kuendesha kutoka kwenye chanzo:
```bash
pipx install 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
sudo apt install tor onionshare-cli # Debian/Ubuntu
```
## Hatua kwa Hatua
1. **Anzisha:** Endesha `voxvera init` na ufuate maelekezo. Utaulizwa kuchagua lugha yako kwanza.
2. **Jenga:** Tengeneza rasilimali za kipeperushi. Kila ujenzi huunda kiotomatiki faili ya `voxvera-portable.zip` kwenye folda ya kipeperushi, ikiruhusu wengine kupakua zana nzima moja kwa moja kutoka kwenye kipeperushi chako.
```bash
voxvera build
```
3. **Tumia:** Chapisha kipeperushi kupitia Tor:
```bash
voxvera serve
```
Hii hutambua kiotomatiki mfumo wako wa Tor, inaanzisha OnionShare, na kuandika anwani ya .onion iliyozalishwa kwenye viungo vya kipeperushi.
## Usaidizi wa Lugha
VoxVera imetafsiriwa kikamilifu. Unaweza kubadilisha upendeleo wako wa lugha kwa kudumu ukitumia kiteuzi shirikishi au njia ya mkato ya moja kwa moja:
- **Kiteuzi Shirikishi:** `voxvera lang`
- **Njia ya Mkato ya Moja kwa Moja:** `voxvera --lang sw` (inaweka upendeleo kuwa Kiswahili)
### Lugha Zinazotumika:
- **Kiingereza:** `en`
- **Kihispania:** `es` (jina mbadala: `--idioma`)
- **Kijerumani:** `de` (jina mbadala: `--sprache`)
- **Kiswahili:** `sw`
Unaweza pia kulazimisha lugha maalum kwa amri moja bila kubadilisha upendeleo wako wa kudumu:
- **Kiingereza:** `voxvera --lang en check`
- **Kiswahili:** `voxvera --lang sw check`
Vipeperushi vilivyozalishwa hutambua kiotomatiki lugha ya kivinjari cha mgeni na kubadilisha maandishi ya UI ipasavyo.
## Usimamizi wa Seva
Simamia vipeperushi vingi na utambulisho wao wa Tor kutoka kwenye menyu moja shirikishi:
```bash
voxvera manage
```
Vipengele:
- **--- Unda Tovuti/Kipeperushi Kipya ---**: Anza mchakato mzima wa usanidi.
- **--- Anzisha Tovuti Zote ---**: Anzisha au simamisha vipeperushi vyote kwenye kundi lako kwa mpigo mmoja.
- **Hali ya Wakati Halisi**: Angalia URL za .onion zinazofanya kazi na viashiria vya maendeleo ya kuanza kwa Tor.
- **Udhibiti wa Kibinafsi**: Hamisha kama Zip tovuti maalum kwenye ZIP au uzifute.
## Uakisi wa Ulimwengu (Usambazaji wa Virusi)
Ili kuhakikisha VoxVera inaendelea kupatikana hata kama hifadhi kuu zitadhibitiwa, kila kipeperushi hufanya kazi kama kioo cha zana hiyo.
Unapohifadhi kipeperushi, kitufe cha **"Pakua Zana na Chanzo"** kwenye ukurasa wa kutua hutoa `voxvera-portable.zip` iliyo na:
- Chanzo kamili na lugha zote zinazotumika.
- Vitegemezi vyote vya Python (vilivyowekwa mapema).
- Programu za Tor za mifumo mbalimbali.
Hii inaruhusu kila mtu anayekagua kipeperushi chako kuwa msambazaji mpya wa zana ya VoxVera.
## Hamisha na Hifadhi Nakala
Hifadhi nakala za utambulisho wako wa kipekee wa Tor (ili URL yako ya .onion isibadilike kamwe) au hamisha vipeperushi vyako kwenye mashine nyingine.
- **Hamisha tovuti moja**: `voxvera export <jina_la_folda>`
- **Hamisha tovuti zote**: `voxvera export-all`
**Mahali pa kuhifadhi:** Hamisho zote zinahifadhiwa kwenye `~/voxvera-exports/` kwenye mifumo yote.
## Ingiza na Rejesha
Rejesha usanidi wako wote kwenye mashine mpya kwa kuhamisha faili zako za ZIP kwenda `~/voxvera-exports/` na uendeshe:
```bash
voxvera import-multiple
```
## Uwezo wa Kubebeka na Matumizi ya Nje ya Mtandao
Ikiwa unahitaji kuendesha VoxVera kwenye mashine isiyo na ufikiaji wa mtandao, unaweza kupakua vitegemezi kwanza:
```bash
voxvera vendorize
```
Hii inapakua maktaba zote za Python zinazohitajika kwenye `voxvera/vendor/`. Kisha zana itatoa kipaumbele kwa faili hizi za kienyeji, ikiruhusu iendeshe bila `pip install`.
## Ingiza kwa Wingi (JSON)
Ili kuzalisha vipeperushi kwa wingi kutoka kwa faili nyingi za usanidi wa JSON, ziweke kwenye folda ya `imports/` na uendeshe:
```bash
voxvera batch-import
```
## Jinsi URL Zinavyofanya Kazi
Kila kipeperushi kina URL mbili tofauti:
- **Kiungo cha kutolewa** (kinachozalishwa kiotomatiki): Anwani ya .onion ambapo kipeperushi kinahifadhiwa.
- **Kiungo cha maudhui** (kilichosanidiwa na mtumiaji): URL ya nje inayoelekeza kwenye tovuti, video, au upakuaji.
Huna haja ya kuingiza anwani ya .onion kwa mikono; VoxVera inashughulikia hili kiotomatiki wakati wa awamu ya `serve`.
docs/templates/AGENTS.md
Vendored
-42
View File
@@ -1,42 +0,0 @@
# AI Agent Instructions for VoxVera
This guide is for AI agents (like Gemini, Claude, or GPT) contributing to the VoxVera project. Follow these protocols to maintain the architectural integrity and multi-language support.
## Core Mandates
1. **Security-First**: VoxVera is a Tor-based tool. Never suggest features that leak IP addresses or use non-Tor external resources (CDNs, etc.).
2. **Local-First**: All assets (fonts, dependencies, binaries) must be self-contained within the `voxvera/` package to support the Universal Mirroring model.
3. **Tokenized UI**: Never hardcode user-facing strings. Always add them to `voxvera/locales/en.json` and use the `t('cli.token')` helper.
4. **Markdown Redaction**: Use `~~text~~` in locale JSONs for strike-through effects. Both the build system and the JS engine handle the conversion to `<span class="redacted">` automatically.
5. **Visual Width Testing**: When modifying UI or adding languages, verify that long or complex strings (e.g., Hindi ligatures or CJK characters) do not exceed the visual unit limits defined in the CLI.
## Localization Protocol
When adding a new language or updating an existing one:
- **CLI/Flyers**: Update `voxvera/locales/{lang}.json`. Include `meta`, `cli`, `web`, and `landing` categories.
- **Landing Page**:
- Directly update the `const locales` object in `site/index.html`.
- **Crucial**: Run `voxvera build-site` to generate the latest portable bundle and refresh the pre-rendered HTML.
- **Documentation**:
- Master templates live in `docs/templates/`.
- Localized overrides live in `voxvera/locales/{lang}/docs/`.
- **Crucial**: After any change to locales or templates, you MUST run `voxvera build-docs` to synchronize the output in `docs/{en,es,de}/`.
## Universal Mirroring
VoxVera propagates through its own flyers.
- Every `voxvera build` and `voxvera build-site` generates `voxvera-portable.zip`.
- If you modify the core source code, ensure the `bundle_portable` function in `voxvera/cli.py` still correctly captures all necessary directories (especially `vendor/`, `locales/`, and `resources/`).
## Verification Checklist
Before finishing a task, ensure you have:
1. Run unit tests: `pytest tests/test_cli.py`.
2. Verified the localization: `voxvera --lang {lang} check`.
3. Rebuilt the documentation: `voxvera build-docs`.
4. Synchronized the public site: `voxvera build-site`.
5. Verified the portable bundle exists: `ls -l voxvera/host/*/download/voxvera-portable.zip` and `ls -l site/download/voxvera-portable.zip`.
---
Follow these rules to ensure VoxVera remains a robust, viral, and decentralized tool for truth.
docs/templates/CONTRIBUTING.md
Vendored
-47
View File
@@ -1,47 +0,0 @@
# Contributing to VoxVera
Thank you for your interest in contributing to VoxVera! This project aims to be a global, censorship-resistant tool, and your help—especially with translations—is vital.
## Adding a New Language
VoxVera uses a centralized token system for the CLI and Web components, and a template-based system for Documentation. To add a new language (e.g., French/`fr`), follow this checklist:
### 1. The Token File
Create a new JSON file in `voxvera/locales/{lang_code}.json`.
- Use `en.json` as your master template.
- **`meta`**: Include the native language name and a flag emoji.
- **`cli`**: Translate all strings used in the terminal interface.
- **`web`**: Translate strings used on the generated landing pages and flyers.
- **`landing`**: Translate the specific content for the official VoxVera website.
- **Formatting**: You can use Markdown-style strike-throughs (`~~redacted text~~`) in any of these strings; they will be automatically converted to the stylized "redacted" effect on the flyers.
### 2. The Landing Page
The main landing page is generated from the shared template and locale files.
- Add your language in `voxvera/locales/{lang_code}.json`.
- Do **not** edit `site/index.html` directly; it is generated output.
- Run `voxvera build-site` to refresh the public assets and inject your new locale into the generated HTML.
### 3. Documentation
VoxVera uses the **Doc-Sync Engine** to keep manuals in sync.
- Create localized Markdown files in `voxvera/locales/{lang_code}/docs/`.
- Use the templates in `docs/templates/` as your guide.
- You can use `{{t('cli.token_name')}}` to reference terminal commands automatically.
### 4. Build and Verify
Run the following commands to verify your changes:
- `voxvera --lang {lang_code} check` (Verify CLI translation)
- `voxvera build-docs` (Generate localized manuals)
- `voxvera build-site` (Synchronize the public website and generate the latest portable bundle)
- Open the generated `site/index.html` in a browser and test the language switcher.
## Code Contributions
- **Dependencies**: if you add a new Python library to `requirements.txt`, you MUST run `voxvera vendorize` to include it in the portable distribution.
- **Layout Integrity**: VoxVera uses visual width validation. If you add new UI elements, ensure they respect the physical boundaries of an 8.5"x11" flyer.
- **Tests**: Ensure all tests pass: `pytest tests/`. Run the integrity suite specifically when modifying locales: `pytest tests/test_integrity.py`.
- **Generated artifacts**: Treat `voxvera/resources/bin/` as local build output, not source files. Release binaries belong in GitHub Releases, not hand-edited repo state.
- **Style**: Follow the existing coding style (PEP 8 for Python).
- **Documentation**: If adding a new feature, update the master templates in `docs/templates/` and run `voxvera build-docs`.
---
Together, we can ensure that truth remains accessible to everyone, everywhere.
docs/templates/docker.md
Vendored
-48
View File
@@ -1,48 +0,0 @@
# Docker Usage
Experimental: the container path is not yet a production-grade hidden-service deployment target. Linux with `systemd --user` remains the supported persistent-host environment.
A prebuilt image containing Tor, OnionShare and the `voxvera` CLI is published to
`ghcr.io/voxvera/voxvera`.
```bash
# pull the image
docker pull ghcr.io/voxvera/voxvera:latest
# run the experimental container with flyers stored in ./flyers
mkdir -p flyers
docker run -d \
--name voxvera \
--restart unless-stopped \
-v "$(pwd)/flyers:/flyers" \
ghcr.io/voxvera/voxvera:latest
```
The container now uses a dedicated entrypoint that:
- stores runtime state under `/flyers`
- seeds `/flyers/config.json` if needed
- starts an in-container Tor daemon on `127.0.0.1:9050/9051`
- bootstraps a default site when `/flyers/host` is empty
- runs `voxvera start-all` on startup and retries it periodically
- exposes a container healthcheck based on `voxvera doctor --json`
Useful commands:
```bash
docker logs -f voxvera
docker exec -it voxvera voxvera doctor --json
docker exec -it voxvera voxvera autostart status --json
```
If you prefer Compose:
```yaml
services:
voxvera:
image: ghcr.io/voxvera/voxvera:latest
restart: unless-stopped
volumes:
- ./flyers:/flyers
```
Use this path for testing only until the container runtime and background recovery behavior are validated end-to-end.
docs/templates/templates.md
Vendored
-14
View File
@@ -1,14 +0,0 @@
# Flyer Templates
Pre-built flyer templates live in the `templates/` directory. Use the CLI to copy one with:
```bash
voxvera init --template <name>
```
This will create a new folder under `dist/` named `<name>-<YYYYMMDD>` containing the template files.
Available templates:
- **blank** – minimal placeholder files, also used when extracting fields from a PDF.
- **voxvera** – example flyer showcasing the VoxVera project.
docs/templates/troubleshooting.md
Vendored
-75
View File
@@ -1,75 +0,0 @@
# Troubleshooting
This page collects common issues encountered when hosting or accessing flyers.
## Tor connectivity
- Ensure Tor is allowed through your firewall. On systems using `ufw` you may need to run `sudo ufw allow tor`.
- Some networks block Tor entirely. If you cannot reach onion services, try connecting over a different network or use a Tor bridge.
## Supported deployment target
- The supported persistent-host setup is Linux with `systemd --user`.
- Windows, macOS, Docker, Flatpak, AppImage, Homebrew, and Chocolatey are currently experimental and may not recover hosting automatically after reboot or network interruptions.
## Tor port detection
`voxvera serve` auto-detects Tor by probing common ports (9050/9150 for SOCKS, 9051/9151 for control). If detection fails -- for example when Tor runs on non-standard ports -- you can override with environment variables:
```bash
TOR_SOCKS_PORT=19050 TOR_CONTROL_PORT=19051 voxvera serve
```
If no running Tor is found, the defaults (9050/9051) are used and OnionShare will attempt to connect on those ports.
## Firewall rules
- If `voxvera serve` fails to start OnionShare, verify that outbound connections on ports 9001 and 80 are permitted.
- Corporate or university firewalls can block the hidden service ports required by Tor.
## SELinux
- On SELinux-enabled distributions you may see `permission denied` errors when OnionShare writes to the `host` directory.
- Run `sudo chcon -Rt svirt_sandbox_file_t host` or disable SELinux enforcement for the folder.
## OnionShare crashes
If `voxvera serve` prints "OnionShare exited unexpectedly", check the log file
`host/<folder_name>/onionshare.log` for details. Common causes:
- Tor is not running (`sudo systemctl start tor`)
- A port conflict with another service
- Missing `onionshare-cli` (run `voxvera check`)
## Onion URL changed unexpectedly
The onion URL is tied to the Ed25519 keypair stored in
`host/<folder_name>/.onionshare-session`. If this file is deleted, a new
keypair (and URL) will be generated on the next `voxvera serve`. The
`voxvera import` command preserves this file automatically, but manual
deletion of the `host/` directory will destroy it.
## Hosting does not return after reboot or network loss
On Linux, install or verify the recovery timer:
```bash
voxvera autostart
systemctl --user status voxvera-start.timer
systemctl --user status voxvera-start.service
```
The supported recovery path is the recurring `systemd --user` timer, which reruns `voxvera start-all` every few minutes.
## QR codes not generated
If `voxvera build` reports "No URLs configured yet", this is expected before the first `voxvera serve`. QR codes for tear-off links are generated automatically once the .onion address is known. QR codes for the content link are generated if you provided a URL during `voxvera init`.
## Electron GUI
If `npm start` fails with `spawn voxvera ENOENT`, the `voxvera` command is not in your `PATH`. Install it with `pipx install git+https://github.com/PR0M3TH3AN/VoxVera.git` or run `./install.sh` from the repository.
## Missing dependencies
Run `voxvera check` to verify your setup. The command checks for required
Python packages (`qrcode`, `Pillow`, `jsmin`, `htmlmin`, `pypdf`) and
external tools (`onionshare-cli`), then prints a summary of anything
missing. To install everything:
```bash
# Recommended: use the install script (handles Tor + OnionShare too)
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
# Or reinstall just the Python package
pipx install --force 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
```
Loaded 100 of 3028 files, more files were not shown because too many files have changed in this diff. Show more