kashilo/README.md

kashilo.com

A privacy-first classifieds platform with Monero payments.

🎯 Vision

kashilo.com lets users post classifieds and trade goods/services securely via Monero (XMR).

• Anonymous: No personal data required
• Direct payments: Peer-to-peer via Monero, no payment intermediary
• Privacy-first: End-to-end encrypted communication

---

📊 Features

Feature	Complexity	Status
Listings CRUD	Low	✅ Done
Fiat/XMR price display	Low	✅ Done
Anonymous accounts (UUID + Hash)	Medium	✅ Done
PWA	Medium	✅ Done
Light/Dark Mode	Low	✅ Done
i18n (7 languages)	Low	✅ Done
Image gallery	Low	✅ Done
E2E Chat (NaCl box.before + secretbox)	High	✅ Done
PoW Captcha (server-side)	Medium	✅ Done
Rating & Reputation system	Medium	✅ Done
Verifiable Listings	Medium	✅ Done
Pseudonyms & Identicons	Low	✅ Done
Invite code system (alpha)	Low	✅ Done
2FA	Medium	🔲 Planned

---

🛠️ Tech Stack

Frontend

• Vanilla JavaScript (ES Modules)
• Web Components (Custom Elements)
• CSS Custom Properties (Theming)
• PWA (Service Worker, Manifest)

Backend

• Directus (Headless CMS, self-hosted)
  • REST API
  • Auth, roles, permissions

Services

• Directus backend: api.kashilo.com (Docker)
• PoW Captcha + Payment Proxy: pow.kashilo.com (PHP, HMAC-signed challenges, BTCPay proxy + webhook, OG meta proxy)
• BTCPay Server: pay.xmr.rocks (Monero payments, self-hosted)
• TweetNaCl: Self-hosted in js/vendor/ (E2E encryption)

Planned

• Push notifications (Web Push API)

---

🚀 Setup

Prerequisites

• Modern browser with ES Module support
• Python 3 (for local server) or any HTTP server

Installation

# Clone the repository
git clone https://gitea.pro/schmidt1024/kashilo.git
cd kashilo

# Start local server
python3 -m http.server 8080

# Or with live-reload (Node.js required)
npx live-server

Open http://localhost:8080

Deployment

Production requires only these files:

├── index.html
├── manifest.json
├── service-worker.js
├── favicon.png
├── js/
├── css/
├── locales/
└── assets/

Do not deploy: tests/, docs/, AGENTS.md, README.md, .git/, deploy.sh

Build (minification)

# One-time: install dependencies
pip3 install rjsmin rcssmin

# Run build (creates dist/ with minified files)
python3 build.py

The build script minifies all JS and CSS files (~111 KiB savings) and copies everything to dist/.

Deploy via script

# One-time: adjust SSH user and path
./deploy.sh user@kashilo.com /home/user/web/kashilo.com/public_html

# Or set defaults in the script and simply run:
./deploy.sh

The script automatically runs python3 build.py, then rsync from dist/ to the server.

Requirements:

• Python 3 + rjsmin + rcssmin (for build)
• SSH key authentication to server
• rsync installed locally and on the server

Running tests

# Start server
python3 -m http.server 8080

# Open in browser
# http://localhost:8080/tests/

Tests run in the browser using a minimal test runner without external dependencies.

Project structure

kashilo/
├── index.html              # Entry point
├── manifest.json           # PWA Manifest
├── service-worker.js       # Offline support
├── css/
│   ├── fonts.css           # Web Fonts (Inter, Space Grotesk)
│   ├── variables.css       # Theming (Light/Dark)
│   ├── base.css            # Reset, base styles
│   └── components.css      # UI components
├── js/
│   ├── app.js              # App initialization
│   ├── router.js           # Hash-based routing
│   ├── i18n.js             # Translation system
│   ├── services/
│   │   ├── directus.js     # Directus API client
│   │   ├── auth.js         # UUID auth (SHA-256 hash)
│   │   ├── listings.js     # Listings service
│   │   ├── categories.js   # Categories service
│   │   ├── locations.js    # Locations service
│   │   ├── conversations.js# Zero-knowledge chat
│   │   ├── crypto.js       # NaCl encryption (box.before + secretbox)
│   │   ├── currency.js     # XMR/fiat conversion (Kraken + CoinGecko)
│   │   ├── pow-captcha.js  # PoW captcha (server-first, local fallback)
│   │   ├── btcpay.js       # BTCPay Server integration
│   │   ├── favorites.js    # Favorites (localStorage + Directus sync)
│   │   ├── notifications.js# Notifications (polling, badge)
│   │   ├── reputation.js   # Reputation (deals, ratings, levels)
│   │   ├── verification.js # Verifiable listings (proof of possession)
│   │   └── identity.js     # Pseudonyms & identicon avatars
│   ├── vendor/
│   │   ├── nacl-fast.min.js    # TweetNaCl (self-hosted)
│   │   ├── nacl-util.min.js    # TweetNaCl Utils
│   │   └── cropper.min.js      # Image Cropper
│   └── components/
│       ├── app-shell.js    # Layout container
│       ├── app-header.js   # Header with navigation
│       ├── app-footer.js   # Footer
│       ├── auth-modal.js   # Login/Register modal
│       ├── chat-widget.js  # E2E chat widget
│       └── pages/          # Page components
├── locales/
│   ├── de.json             # Deutsch
│   ├── en.json             # English
│   ├── fr.json             # Français
│   ├── it.json             # Italiano
│   ├── es.json             # Español
│   ├── pt.json             # Português (BR)
│   └── ru.json             # Русский
├── tests/
│   ├── index.html          # Test runner UI
│   ├── test-runner.js      # Test framework
│   └── *.test.js           # Unit tests
└── assets/
    └── fonts/              # Self-hosted fonts

---

📋 Roadmap

Phase 1: Frontend ✅

• Project structure, routing, i18n (7 languages)
• Light/Dark mode, PWA shell
• Home page with search, categories, listings grid
• Listing detail page with image gallery
• Create/edit listing form
• Skeleton loading, error boundary, offline indicator

Phase 2: Backend integration ✅

• Directus setup (api.kashilo.com)
• Listings, categories, locations collections
• Anonymous auth (UUID + SHA-256 hash)
• Image upload, favorites, my listings, messages, settings pages

Phase 3: Communication & Security ✅

• E2E encrypted chat (NaCl box.before + secretbox)
• Favorites with Directus sync (union merge on login)
• PoW captcha (server-side via pow.kashilo.com)
• TweetNaCl self-hosted (no CDN)
• In-app notifications (polling, badge)
• Open Graph & X Card meta tags

Phase 4: Payments ✅

• XMR rate API (Kraken primary, CoinGecko fallback)
• Fiat ↔ XMR conversion (dual price display)
• BTCPay Server integration (self-hosted)
• Listing fee: $1 via Monero
• Webhook for auto-publish after blockchain confirmation
• Expired listings (Directus flow, status badges)

Phase 5: Trust & Safety ✅

• Rating & reputation system (deals, levels, badges)
• Verifiable listings (proof of possession)
• Pseudonyms & identicon avatars
• Terms of service, privacy policy, legal notice (7 languages)
• 2FA
• Reporting/moderation
• Push notifications (Web Push API)

---

🎨 Design

Typography

• Headlines: Space Grotesk (Medium, Bold)
• Body: Inter (Regular, Medium, SemiBold, Bold)
• Self-hosted fonts (SIL Open Font License)

Color palette

• Warm Teal Theme
• Light Mode: BG #FAFAF9, Text #1C1917, Accent #0D9488
• Dark Mode: BG #171717, Text #F5F5F4, Accent #2DD4BF

Mobile-first

• Responsive grid (2 columns mobile, 5 columns desktop)
• Touch-optimized buttons
• Icon-only buttons on small screens

---

🤝 Contributing

1. Create a feature branch
2. Commit your changes
3. Open a pull request

Code conventions

• ES Modules
• Web Components for UI
• CSS Custom Properties for theming
• Translation keys for all user-facing text
• No semicolons in JavaScript (except for-loops, CSS)
• English comments in code

---

📄 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

Source code is freely available. Forks and modifications must also be published under AGPL-3.0.

kashilo is a registered trademark. The name and logo may not be used for derivative projects without permission.

---

📞 Contact

• Issues: gitea.pro/schmidt1024/kashilo/issues
• Website: kashilo.com