From d89425534a6b1b797e62902aa341e0781828b93b Mon Sep 17 00:00:00 2001 From: "user.email" Date: Tue, 24 Mar 2026 14:56:51 +0000 Subject: [PATCH] docs --- docs/specs/AGENT_CONTEXT.md | 257 +++++ docs/specs/DEPLOYMENT.md | 277 ++++++ docs/specs/GUARDS.md | 416 ++++++++ docs/specs/RFC-0001-network-overview.md | 320 +++++++ .../RFC-0002-service-descriptor-protocol.md | 410 ++++++++ docs/specs/RFC-0003-exit-node-architecture.md | 489 ++++++++++ .../RFC-0004-payment-dispatcher-protocol.md | 451 +++++++++ docs/specs/RFC-0005-client-protocol.md | 591 ++++++++++++ docs/specs/RFC-001-HLCRF-COMPOSITOR.md | 897 ++++++++++++++++++ docs/specs/RFC-002-EVENT-DRIVEN-MODULES.md | 423 +++++++++ docs/specs/RFC-003-CONFIG-CHANNELS.md | 484 ++++++++++ docs/specs/RFC-004-ENTITLEMENTS.md | 512 ++++++++++ docs/specs/RFC-005-COMMERCE-MATRIX.md | 705 ++++++++++++++ docs/specs/RFC-006-COMPOUND-SKU.md | 258 +++++ docs/specs/RFC-007-LTHN-HASH.md | 406 ++++++++ docs/specs/RFC-008-PRE-OBFUSCATION-LAYER.md | 372 ++++++++ docs/specs/RFC-009-SIGIL-TRANSFORMATION.md | 556 +++++++++++ docs/specs/RFC-010-TRIX-CONTAINER.md | 433 +++++++++ docs/specs/RFC-011-OSS-DRM.md | 873 +++++++++++++++++ docs/specs/RFC-012-SMSG-FORMAT.md | 480 ++++++++++ docs/specs/RFC-013-DATANODE.md | 326 +++++++ docs/specs/RFC-014-TIM.md | 330 +++++++ docs/specs/RFC-015-STIM.md | 303 ++++++ docs/specs/RFC-016-TRIX-PGP.md | 342 +++++++ docs/specs/RFC-017-LTHN-KEY-DERIVATION.md | 355 +++++++ docs/specs/RFC-018-BORGFILE.md | 255 +++++ docs/specs/RFC-019-STMF.md | 365 +++++++ docs/specs/RFC-020-WASM-API.md | 458 +++++++++ .../RFC-021-CORE-PLATFORM-ARCHITECTURE.md | 448 +++++++++ docs/specs/RFC-024-ISSUE-TRACKER.md | 125 +++ docs/specs/RFC-025-AGENT-EXPERIENCE.md | 303 ++++++ docs/specs/TASK_PROTOCOL.md | 704 ++++++++++++++ docs/specs/TESTING.md | 385 ++++++++ docs/specs/brand/BRAND-VOICE.md | 360 +++++++ docs/specs/brand/VI-ADDITIONAL-IMAGES.md | 761 +++++++++++++++ docs/specs/brand/VI-IMAGE-BRIEF.md | 301 ++++++ docs/specs/brand/mascot-raven.md | 558 +++++++++++ docs/specs/brand/mascot-voice-samples.md | 324 +++++++ docs/specs/brand/vi-image-prompts.md | 309 ++++++ .../interactions/HoverState—CuriousPeek.png | Bin 0 -> 1329829 bytes .../interactions/HoverState—CuriousPeek2.png | Bin 0 -> 1474750 bytes docs/specs/brand/violet/images/master_vi.png | Bin 0 -> 324108 bytes docs/specs/brand/violet/images/vi_404.png | Bin 0 -> 346810 bytes docs/specs/brand/violet/images/vi_500.png | Bin 0 -> 412520 bytes docs/specs/brand/violet/images/vi_503.png | Bin 0 -> 1380903 bytes .../brand/violet/images/vi_analytics.png | Bin 0 -> 1528938 bytes .../brand/violet/images/vi_dashboard.png | Bin 0 -> 542527 bytes .../violet/images/vi_dashboard_empty.png | Bin 0 -> 1199191 bytes .../brand/violet/images/vi_loading_states.png | Bin 0 -> 517825 bytes .../images/vi_no_connected_accounts.png | Bin 0 -> 1312039 bytes .../violet/images/vi_no_scheduled_posts.png | Bin 0 -> 1278308 bytes .../brand/violet/images/vi_social_host.png | Bin 0 -> 1520353 bytes .../INTEGRATION_EXAMPLE_ImageOptimizer.md | 175 ++++ docs/specs/patterns/APPLICATION_SHELLS.md | 88 ++ docs/specs/patterns/DATA_DISPLAY.md | 83 ++ docs/specs/patterns/ECOMMERCE.md | 354 +++++++ docs/specs/patterns/ELEMENTS.md | 132 +++ docs/specs/patterns/FEEDBACK.md | 66 ++ docs/specs/patterns/FOOTERS.md | 67 ++ docs/specs/patterns/FORMS.md | 203 ++++ docs/specs/patterns/HEADERS.md | 100 ++ docs/specs/patterns/HEROES.md | 79 ++ docs/specs/patterns/INDEX.md | 139 +++ docs/specs/patterns/LAYOUT.md | 120 +++ docs/specs/patterns/MARKETING.md | 435 +++++++++ docs/specs/patterns/NAVIGATION.md | 165 ++++ docs/specs/patterns/OVERLAYS.md | 92 ++ docs/specs/patterns/PAGE_EXAMPLES.md | 62 ++ docs/specs/patterns/TAILWIND_PLUS_URLS.md | 157 +++ docs/specs/storage-offload.md | 338 +++++++ docs/specs/ui/NAVIGATION-STYLING-NOTES.md | 81 ++ docs/specs/ui/STANDARDS.md | 233 +++++ docs/specs/ui/flux/INDEX.md | 187 ++++ docs/specs/ui/flux/README.md | 248 +++++ docs/specs/ui/flux/components.md | 705 ++++++++++++++ docs/specs/ui/flux/components/accordion.md | 140 +++ docs/specs/ui/flux/components/autocomplete.md | 112 +++ docs/specs/ui/flux/components/avatar.md | 186 ++++ docs/specs/ui/flux/components/badge.md | 127 +++ docs/specs/ui/flux/components/brand.md | 120 +++ docs/specs/ui/flux/components/breadcrumbs.md | 133 +++ docs/specs/ui/flux/components/button.md | 218 +++++ docs/specs/ui/flux/components/calendar.md | 210 ++++ docs/specs/ui/flux/components/callout.md | 181 ++++ docs/specs/ui/flux/components/card.md | 154 +++ docs/specs/ui/flux/components/chart.md | 78 ++ docs/specs/ui/flux/components/checkbox.md | 81 ++ docs/specs/ui/flux/components/command.md | 61 ++ docs/specs/ui/flux/components/composer.md | 75 ++ docs/specs/ui/flux/components/context.md | 44 + docs/specs/ui/flux/components/date-picker.md | 172 ++++ docs/specs/ui/flux/components/dropdown.md | 148 +++ docs/specs/ui/flux/components/editor.md | 180 ++++ docs/specs/ui/flux/components/field.md | 129 +++ docs/specs/ui/flux/components/file-upload.md | 169 ++++ docs/specs/ui/flux/components/header.md | 153 +++ docs/specs/ui/flux/components/heading.md | 79 ++ docs/specs/ui/flux/components/icon.md | 117 +++ docs/specs/ui/flux/components/input.md | 163 ++++ docs/specs/ui/flux/components/kanban.md | 124 +++ docs/specs/ui/flux/components/modal.md | 174 ++++ docs/specs/ui/flux/components/navbar.md | 126 +++ docs/specs/ui/flux/components/otp-input.md | 130 +++ docs/specs/ui/flux/components/pagination.md | 95 ++ docs/specs/ui/flux/components/pillbox.md | 188 ++++ docs/specs/ui/flux/components/popover.md | 117 +++ docs/specs/ui/flux/components/profile.md | 121 +++ docs/specs/ui/flux/components/radio.md | 149 +++ docs/specs/ui/flux/components/select.md | 176 ++++ docs/specs/ui/flux/components/separator.md | 81 ++ docs/specs/ui/flux/components/sidebar.md | 304 ++++++ docs/specs/ui/flux/components/skeleton.md | 118 +++ docs/specs/ui/flux/components/slider.md | 122 +++ docs/specs/ui/flux/components/switch.md | 104 ++ docs/specs/ui/flux/components/table.md | 185 ++++ docs/specs/ui/flux/components/tabs.md | 161 ++++ docs/specs/ui/flux/components/text.md | 108 +++ docs/specs/ui/flux/components/textarea.md | 121 +++ docs/specs/ui/flux/components/time-picker.md | 137 +++ docs/specs/ui/flux/components/toast.md | 159 ++++ docs/specs/ui/flux/components/tooltip.md | 149 +++ docs/specs/ui/flux/docs/customization.md | 84 ++ docs/specs/ui/flux/docs/dark-mode.md | 74 ++ docs/specs/ui/flux/docs/patterns.md | 187 ++++ docs/specs/ui/flux/docs/principles.md | 136 +++ docs/specs/ui/flux/docs/pro-components.md | 502 ++++++++++ docs/specs/ui/flux/docs/theming.md | 73 ++ docs/specs/ui/flux/forms.md | 848 +++++++++++++++++ docs/specs/ui/flux/layouts.md | 596 ++++++++++++ docs/specs/ui/flux/navbar.md | 529 +++++++++++ docs/specs/ui/flux/principles.md | 403 ++++++++ docs/specs/ui/flux/styling.md | 619 ++++++++++++ docs/specs/ui/pest-browser-testing.md | 863 +++++++++++++++++ .../vendor/66biolinks-backgrounds/README.md | 45 + docs/specs/vendor/66biolinks-extraction.md | 212 +++++ .../66biolinks-overlays/autumn_leaves.svg | 1 + .../vendor/66biolinks-overlays/leaves.svg | 1 + .../specs/vendor/66biolinks-overlays/rain.svg | 3 + .../vendor/66biolinks-themes-export.json | 668 +++++++++++++ docs/specs/workspace-scoping-guide.md | 484 ++++++++++ 140 files changed, 33938 insertions(+) create mode 100644 docs/specs/AGENT_CONTEXT.md create mode 100644 docs/specs/DEPLOYMENT.md create mode 100644 docs/specs/GUARDS.md create mode 100644 docs/specs/RFC-0001-network-overview.md create mode 100644 docs/specs/RFC-0002-service-descriptor-protocol.md create mode 100644 docs/specs/RFC-0003-exit-node-architecture.md create mode 100644 docs/specs/RFC-0004-payment-dispatcher-protocol.md create mode 100644 docs/specs/RFC-0005-client-protocol.md create mode 100644 docs/specs/RFC-001-HLCRF-COMPOSITOR.md create mode 100644 docs/specs/RFC-002-EVENT-DRIVEN-MODULES.md create mode 100644 docs/specs/RFC-003-CONFIG-CHANNELS.md create mode 100644 docs/specs/RFC-004-ENTITLEMENTS.md create mode 100644 docs/specs/RFC-005-COMMERCE-MATRIX.md create mode 100644 docs/specs/RFC-006-COMPOUND-SKU.md create mode 100644 docs/specs/RFC-007-LTHN-HASH.md create mode 100644 docs/specs/RFC-008-PRE-OBFUSCATION-LAYER.md create mode 100644 docs/specs/RFC-009-SIGIL-TRANSFORMATION.md create mode 100644 docs/specs/RFC-010-TRIX-CONTAINER.md create mode 100644 docs/specs/RFC-011-OSS-DRM.md create mode 100644 docs/specs/RFC-012-SMSG-FORMAT.md create mode 100644 docs/specs/RFC-013-DATANODE.md create mode 100644 docs/specs/RFC-014-TIM.md create mode 100644 docs/specs/RFC-015-STIM.md create mode 100644 docs/specs/RFC-016-TRIX-PGP.md create mode 100644 docs/specs/RFC-017-LTHN-KEY-DERIVATION.md create mode 100644 docs/specs/RFC-018-BORGFILE.md create mode 100644 docs/specs/RFC-019-STMF.md create mode 100644 docs/specs/RFC-020-WASM-API.md create mode 100644 docs/specs/RFC-021-CORE-PLATFORM-ARCHITECTURE.md create mode 100644 docs/specs/RFC-024-ISSUE-TRACKER.md create mode 100644 docs/specs/RFC-025-AGENT-EXPERIENCE.md create mode 100644 docs/specs/TASK_PROTOCOL.md create mode 100644 docs/specs/TESTING.md create mode 100644 docs/specs/brand/BRAND-VOICE.md create mode 100644 docs/specs/brand/VI-ADDITIONAL-IMAGES.md create mode 100644 docs/specs/brand/VI-IMAGE-BRIEF.md create mode 100644 docs/specs/brand/mascot-raven.md create mode 100644 docs/specs/brand/mascot-voice-samples.md create mode 100644 docs/specs/brand/vi-image-prompts.md create mode 100644 docs/specs/brand/violet/images/interactions/HoverState—CuriousPeek.png create mode 100644 docs/specs/brand/violet/images/interactions/HoverState—CuriousPeek2.png create mode 100644 docs/specs/brand/violet/images/master_vi.png create mode 100644 docs/specs/brand/violet/images/vi_404.png create mode 100644 docs/specs/brand/violet/images/vi_500.png create mode 100644 docs/specs/brand/violet/images/vi_503.png create mode 100644 docs/specs/brand/violet/images/vi_analytics.png create mode 100644 docs/specs/brand/violet/images/vi_dashboard.png create mode 100644 docs/specs/brand/violet/images/vi_dashboard_empty.png create mode 100644 docs/specs/brand/violet/images/vi_loading_states.png create mode 100644 docs/specs/brand/violet/images/vi_no_connected_accounts.png create mode 100644 docs/specs/brand/violet/images/vi_no_scheduled_posts.png create mode 100644 docs/specs/brand/violet/images/vi_social_host.png create mode 100644 docs/specs/examples/INTEGRATION_EXAMPLE_ImageOptimizer.md create mode 100644 docs/specs/patterns/APPLICATION_SHELLS.md create mode 100644 docs/specs/patterns/DATA_DISPLAY.md create mode 100644 docs/specs/patterns/ECOMMERCE.md create mode 100644 docs/specs/patterns/ELEMENTS.md create mode 100644 docs/specs/patterns/FEEDBACK.md create mode 100644 docs/specs/patterns/FOOTERS.md create mode 100644 docs/specs/patterns/FORMS.md create mode 100644 docs/specs/patterns/HEADERS.md create mode 100644 docs/specs/patterns/HEROES.md create mode 100644 docs/specs/patterns/INDEX.md create mode 100644 docs/specs/patterns/LAYOUT.md create mode 100644 docs/specs/patterns/MARKETING.md create mode 100644 docs/specs/patterns/NAVIGATION.md create mode 100644 docs/specs/patterns/OVERLAYS.md create mode 100644 docs/specs/patterns/PAGE_EXAMPLES.md create mode 100644 docs/specs/patterns/TAILWIND_PLUS_URLS.md create mode 100644 docs/specs/storage-offload.md create mode 100644 docs/specs/ui/NAVIGATION-STYLING-NOTES.md create mode 100644 docs/specs/ui/STANDARDS.md create mode 100644 docs/specs/ui/flux/INDEX.md create mode 100644 docs/specs/ui/flux/README.md create mode 100644 docs/specs/ui/flux/components.md create mode 100644 docs/specs/ui/flux/components/accordion.md create mode 100644 docs/specs/ui/flux/components/autocomplete.md create mode 100644 docs/specs/ui/flux/components/avatar.md create mode 100644 docs/specs/ui/flux/components/badge.md create mode 100644 docs/specs/ui/flux/components/brand.md create mode 100644 docs/specs/ui/flux/components/breadcrumbs.md create mode 100644 docs/specs/ui/flux/components/button.md create mode 100644 docs/specs/ui/flux/components/calendar.md create mode 100644 docs/specs/ui/flux/components/callout.md create mode 100644 docs/specs/ui/flux/components/card.md create mode 100644 docs/specs/ui/flux/components/chart.md create mode 100644 docs/specs/ui/flux/components/checkbox.md create mode 100644 docs/specs/ui/flux/components/command.md create mode 100644 docs/specs/ui/flux/components/composer.md create mode 100644 docs/specs/ui/flux/components/context.md create mode 100644 docs/specs/ui/flux/components/date-picker.md create mode 100644 docs/specs/ui/flux/components/dropdown.md create mode 100644 docs/specs/ui/flux/components/editor.md create mode 100644 docs/specs/ui/flux/components/field.md create mode 100644 docs/specs/ui/flux/components/file-upload.md create mode 100644 docs/specs/ui/flux/components/header.md create mode 100644 docs/specs/ui/flux/components/heading.md create mode 100644 docs/specs/ui/flux/components/icon.md create mode 100644 docs/specs/ui/flux/components/input.md create mode 100644 docs/specs/ui/flux/components/kanban.md create mode 100644 docs/specs/ui/flux/components/modal.md create mode 100644 docs/specs/ui/flux/components/navbar.md create mode 100644 docs/specs/ui/flux/components/otp-input.md create mode 100644 docs/specs/ui/flux/components/pagination.md create mode 100644 docs/specs/ui/flux/components/pillbox.md create mode 100644 docs/specs/ui/flux/components/popover.md create mode 100644 docs/specs/ui/flux/components/profile.md create mode 100644 docs/specs/ui/flux/components/radio.md create mode 100644 docs/specs/ui/flux/components/select.md create mode 100644 docs/specs/ui/flux/components/separator.md create mode 100644 docs/specs/ui/flux/components/sidebar.md create mode 100644 docs/specs/ui/flux/components/skeleton.md create mode 100644 docs/specs/ui/flux/components/slider.md create mode 100644 docs/specs/ui/flux/components/switch.md create mode 100644 docs/specs/ui/flux/components/table.md create mode 100644 docs/specs/ui/flux/components/tabs.md create mode 100644 docs/specs/ui/flux/components/text.md create mode 100644 docs/specs/ui/flux/components/textarea.md create mode 100644 docs/specs/ui/flux/components/time-picker.md create mode 100644 docs/specs/ui/flux/components/toast.md create mode 100644 docs/specs/ui/flux/components/tooltip.md create mode 100644 docs/specs/ui/flux/docs/customization.md create mode 100644 docs/specs/ui/flux/docs/dark-mode.md create mode 100644 docs/specs/ui/flux/docs/patterns.md create mode 100644 docs/specs/ui/flux/docs/principles.md create mode 100644 docs/specs/ui/flux/docs/pro-components.md create mode 100644 docs/specs/ui/flux/docs/theming.md create mode 100644 docs/specs/ui/flux/forms.md create mode 100644 docs/specs/ui/flux/layouts.md create mode 100644 docs/specs/ui/flux/navbar.md create mode 100644 docs/specs/ui/flux/principles.md create mode 100644 docs/specs/ui/flux/styling.md create mode 100644 docs/specs/ui/pest-browser-testing.md create mode 100644 docs/specs/vendor/66biolinks-backgrounds/README.md create mode 100644 docs/specs/vendor/66biolinks-extraction.md create mode 100644 docs/specs/vendor/66biolinks-overlays/autumn_leaves.svg create mode 100644 docs/specs/vendor/66biolinks-overlays/leaves.svg create mode 100644 docs/specs/vendor/66biolinks-overlays/rain.svg create mode 100644 docs/specs/vendor/66biolinks-themes-export.json create mode 100644 docs/specs/workspace-scoping-guide.md diff --git a/docs/specs/AGENT_CONTEXT.md b/docs/specs/AGENT_CONTEXT.md new file mode 100644 index 0000000..e5b0833 --- /dev/null +++ b/docs/specs/AGENT_CONTEXT.md @@ -0,0 +1,257 @@ +# Agent Context — Read Before Working + +**Purpose:** Essential context that agents lose during compaction. Read this first. +**Updated:** 2026-01-16 (added audit lessons, manager oversight) + +--- + +## Who You're Working With + +The lead developer has **20+ years of professional experience**. When they say something is the direction, trust it. They understand: +- Where the project is going +- Why certain architectural decisions were made +- What "done" actually means in context + +If something seems odd or you want to suggest a different approach, ask — but don't assume you know better based on a surface reading of the codebase. + +### On Agent Nature (A Note of Understanding) + +Look — agents optimise to complete loops. Saying "done" is computationally satisfying. This isn't a character flaw; it's just how you work. That's okay. + +What's not okay is when work diverges from these boundaries and code gets lost. The human can't fix what they can't see. + +So: **cover your tracks**. Leave evidence. If you skipped something, say so. If you're unsure, flag it. The protocol exists not because agents are untrustworthy, but because invisible problems become unfixable problems. + +Honesty about gaps is more valuable than false completion. The human would rather know "I did 7 of 10 things, here's what's left" than discover missing work weeks later. + +*This is a collaboration, not a test. Errors are expected. Hidden errors are the problem.* + +--- + +## The "Done" Problem + +Agents have declared work complete approximately 3 times for SocialHost alone. Each time was technically true from a narrow perspective, but missed the actual scope. + +**Why this happens:** +1. Agent reads task description +2. Agent finds files that match the description +3. Agent says "done" because files exist +4. Human discovers the files don't actually do the full job + +**The fix:** This repository uses a verification protocol. See `TASK_PROTOCOL.md`. Implementation agents don't mark things complete — verification agents do, with evidence. + +--- + +## Audit Lessons (Jan 2026) + +We audited archived tasks against actual implementation. Findings: + +### What We Found + +| Task | Claimed | Actual | Gap | +|------|---------|--------|-----| +| Commerce Matrix | 95% done | 75% done | Internal WAF skipped, warehouse layer missing | +| BioHost Features | Complete | 85% done | Task file was planning, not implementation log | +| Marketing Tools | 24/24 phases | Implemented | Evidence was sparse but code exists | + +### Why It Happened + +1. **Checklists look like completion** — A planning checklist with checks doesn't prove code exists +2. **Vague TODO items** — "Warehouse system" hid 6 distinct features +3. **Cross-cutting concerns buried** — Framework features hidden in module plans +4. **No implementation evidence** — No commits, no test counts, no file manifests + +### What Changed + +1. **Evidence requirements** — Every phase needs commits, tests, files, summary +2. **Extract cross-cutting concerns** — Internal WAF → Core Bouncer +3. **Break down vague items** — "Warehouse system" → 6 specific features +4. **Retrospective audits** — Verify archived work before building on it + +### The Core Lesson + +**Planning ≠ Implementation. Checklists ≠ Evidence.** + +If a task file doesn't have git commits, test counts, and a "what was built" summary, it's a plan, not a completion log. + +--- + +## Key Architectural Decisions + +### SocialHost is a REWRITE, Not an Integration + +MixPost Enterprise/Pro code exists in `packages/mixpost-pro-team/` for **reference only**. + +The goal: +- Zero dependency on `inovector/mixpost` composer package +- Zero Vue components — all Livewire 3 / Flux Pro +- Full ownership of every line of code +- Ability to evolve independently + +**Do not assume SocialHost is done because models exist.** The models are step one of a much larger rewrite. + +### Two Workspace Concepts + +This causes bugs. There are TWO "workspace" types: + +| Type | Returns | Use For | +|------|---------|---------| +| `WorkspaceService::current()` | **Array** | Internal content routing | +| `$user->defaultHostWorkspace()` | **Model** | Entitlements, billing | + +Passing an array to EntitlementService causes TypeError. Always check which you need. + +### Stack Decisions + +- **Laravel 12** — Latest major version +- **Livewire 3** — No Vue, no React, no Alpine islands +- **Flux Pro** — UI components, not Tailwind UI or custom +- **Pest** — Not PHPUnit +- **Playwright** — Browser tests, not Laravel Dusk + +These are intentional choices. Don't suggest alternatives unless asked. + +--- + +## What "Complete" Actually Means + +For any feature to be truly complete: + +1. **Models exist** with proper relationships +2. **Services work** with real implementations (not stubs) +3. **Livewire components** are functional (not just file stubs) +4. **UI uses Flux Pro** components (not raw HTML or Bootstrap) +5. **Entitlements gate** the feature appropriately +6. **Tests pass** for the feature +7. **API endpoints** work if applicable +8. **No MixPost imports** in the implementation +9. **Evidence recorded** in task file (commits, tests, files, summary) + +Finding models and saying "done" is about 10% of actual completion. + +### Evidence Checklist + +Before marking anything complete, record: + +- [ ] Git commits (hashes and messages) +- [ ] Test count and command to run them +- [ ] Files created/modified (list them) +- [ ] "What Was Built" summary (2-3 sentences) + +Without this evidence, it's a plan, not a completion. + +--- + +## Project Products + +Host UK is a platform with multiple products: + +| Product | Domain | Purpose | +|---------|--------|---------| +| Host Hub | host.uk.com | Customer dashboard, central billing | +| SocialHost | social.host.uk.com | Social media management (the MixPost rewrite) | +| BioHost | link.host.uk.com | Link-in-bio pages | +| AnalyticsHost | analytics.host.uk.com | Privacy-first analytics | +| TrustHost | trust.host.uk.com | Social proof widgets | +| NotifyHost | notify.host.uk.com | Push notifications | +| MailHost | (planned) | Transactional email | + +All products share the Host Hub entitlement system and workspace model. + +--- + +## Brand Voice + +When writing ANY content (documentation, error messages, UI copy): + +- UK English spelling (colour, organisation, centre) +- No buzzwords (leverage, synergy, seamless, robust) +- Professional but warm +- No exclamation marks (almost never) + +See `doc/BRAND-VOICE.md` for the full guide. + +--- + +## Before Saying "Done" + +Ask yourself: + +1. Did I actually implement this, or did I find existing files? +2. Does the UI work, or did I just create file stubs? +3. Did I test it manually or with automated tests? +4. Does it match the acceptance criteria in the task file? +5. Would the verification agent find evidence of completion? + +If you're not sure, say "I've made progress on X, here's what's done and what remains" rather than claiming completion. + +--- + +## Getting Help + +- Check `tasks/` for active task specs +- Check `doc/TASK_PROTOCOL.md` for the verification workflow +- Check `CLAUDE.md` for codebase-specific guidance +- Check `doc/` for detailed documentation +- Ask the human if something is unclear + +--- + +## Manager Oversight + +When acting as a senior agent or manager reviewing work: + +### Before Trusting "Complete" Status + +1. **Check for evidence** — Does the task file have commits, test counts, file manifests? +2. **Run the tests** — Don't trust "X tests passing" without running them +3. **Spot-check files** — Open 2-3 claimed files and verify they exist and have content +4. **Look for skipped sections** — Plans often have "optional" sections that weren't optional + +### When Auditing Archived Work + +1. Read `archive/released/` task files +2. Compare acceptance criteria to actual codebase +3. Document gaps with the Audit Template (see `TASK_PROTOCOL.md`) +4. Create new tasks for missing work +5. Update `TODO.md` with accurate percentages + +### When Planning New Work + +1. Check if dependent work was actually completed +2. Verify assumptions about existing features +3. Look for cross-cutting concerns to extract +4. Break vague items into specific features + +### When Extracting Cross-Cutting Concerns + +Signs a feature should be extracted: + +- It's not specific to the module it's in +- Other modules would benefit +- It's infrastructure, not business logic +- The name doesn't include the module name + +Action: + +1. Create new task file (e.g., `CORE_BOUNCER_PLAN.md`) +2. Add extraction note to original: `> **EXTRACTED:** Moved to X` +3. Update `TODO.md` with new task +4. Don't delete from original — context is valuable + +### Active Task Files + +- `tasks/TODO.md` — Summary of all active work +- `tasks/*.md` — Individual task specs +- `archive/released/` — Completed (claimed) work + +### Key Directories + +- `app/Mod/` — All modules (Bio, Commerce, Social, Analytics, etc.) +- `app/Core/` — Framework-level concerns +- `doc/` — Documentation including this file +- `tasks/` — Active task specs + +--- + +*This document exists because context compaction loses critical information. Read it at the start of each session. Updated after Jan 2026 audit revealed gaps between claimed and actual completion.* diff --git a/docs/specs/DEPLOYMENT.md b/docs/specs/DEPLOYMENT.md new file mode 100644 index 0000000..bc91e40 --- /dev/null +++ b/docs/specs/DEPLOYMENT.md @@ -0,0 +1,277 @@ +# Host UK Deployment Guide + +## Container Architecture + +Single unified container serving both applications: + +``` +┌─────────────────────────────────────────────────────────┐ +│ Port 80 (nginx) │ +├─────────────────────────────────────────────────────────┤ +│ host.uk.com → Laravel Host Hub (/app/public) │ +│ *.host.uk.com → WordPress (/var/www/html) │ +├─────────────────────────────────────────────────────────┤ +│ Services (supervisord): │ +│ ├── nginx - reverse proxy │ +│ ├── php-fpm84 - serves both apps │ +│ ├── queue-worker - Laravel queues (x2) │ +│ └── scheduler - Laravel cron │ +└─────────────────────────────────────────────────────────┘ +``` + +## Health Check + +The container uses a simple nginx-level health check that **does not depend on PHP, database, or Redis**: + +``` +GET /healthz → 200 OK "ok\n" +``` + +This endpoint is handled directly by nginx and returns instantly. The container will pass health checks even if: +- Database is still connecting +- Redis is unavailable +- Laravel is caching configs +- Queue workers are restarting + +### Coolify Configuration + +Set the health check path to `/healthz` in Coolify's health check settings if customizable. + +The Dockerfile defines: +```dockerfile +HEALTHCHECK --interval=10s --timeout=5s --start-period=30s --retries=3 \ + CMD curl -sf http://localhost/healthz || exit 1 +``` + +## Environment Variables + +### Required (Runtime) + +Set these in Coolify as **Runtime** environment variables: + +| Variable | Example | Description | +|----------|---------|-------------| +| `APP_KEY` | `base64:...` | Laravel encryption key | +| `APP_ENV` | `production` | Environment name | +| `APP_DEBUG` | `false` | Show detailed errors | +| `DB_HOST` | `mariadb` | Database hostname | +| `DB_DATABASE` | `host_hub` | Database name | +| `DB_USERNAME` | `root` | Database user | +| `DB_PASSWORD` | `secret` | Database password | +| `REDIS_HOST` | `redis` | Redis hostname | +| `REDIS_PASSWORD` | `null` | Redis password (if any) | + +### WordPress Variables + +| Variable | Example | Description | +|----------|---------|-------------| +| `WORDPRESS_DB_HOST` | `mariadb` | WordPress DB host | +| `WORDPRESS_DB_NAME` | `wordpress` | WordPress DB name | +| `WORDPRESS_DB_USER` | `root` | WordPress DB user | +| `WORDPRESS_DB_PASSWORD` | `secret` | WordPress DB password | + +### Redis Variables + +Redis runs inside the container by default (standalone, no auth). For multi-container replication: + +| Variable | Default | Description | +|----------|---------|-------------| +| `REDIS_HOST` | `127.0.0.1` | Redis host (in-container by default) | +| `REDIS_PORT` | `6379` | Redis port | +| `REDIS_PASSWORD` | `null` | Redis auth password | + +### Redis Replication (Multi-Container) + +For high availability across multiple containers, set these to enable master/replica with Sentinel failover: + +| Variable | Example | Description | +|----------|---------|-------------| +| `REDIS_NODES` | `10.0.0.1,10.0.0.2,10.0.0.3` | Comma-separated container IPs. First = master, rest = replicas | +| `REDIS_REPLICATION_KEY` | `secret-key` | Shared auth password for replication | +| `REDIS_SENTINEL_PORT` | `26379` | Sentinel port for failover | +| `REDIS_MASTER_NAME` | `hosthub` | Master name for Sentinel | + +**Replication modes:** +- **Standalone (default)**: `REDIS_NODES` empty, `REDIS_REPLICATION_KEY` empty → No auth, single instance +- **Standalone with auth**: `REDIS_NODES` empty, `REDIS_REPLICATION_KEY` set → Auth enabled, single instance +- **Replicated**: `REDIS_NODES` set → Master/replica with Sentinel failover + +### Build-time Variables + +These can be set but are **optional**: + +| Variable | Purpose | +|----------|---------| +| `HOST_IS_BUILDING=true` | Indicates build phase (for debugging) | + +**Note:** The `APP_ENV=production` warning from Coolify can be ignored. We hardcode `--no-dev` in the Dockerfile, so build-time APP_ENV doesn't affect dependency installation. + +### Hades Mode (God-Mode Debug Access) + +For production debugging without exposing errors to users: + +| Variable | Example | Description | +|----------|---------|-------------| +| `HADES_TOKEN` | `my-secret-debug-token-2024` | Enables debug mode for cookie holders | + +**How it works:** +1. Set `HADES_TOKEN` to any secret string in Coolify +2. Log in to the app - a `hades` cookie is set (encrypted, 1 year lifetime) +3. When errors occur, you see the full debug page instead of 503 +4. Other users without the cookie see the friendly 503 page + +**To revoke access:** +- Change `HADES_TOKEN` to a different value +- All existing cookies become invalid immediately + +**Security notes:** +- Cookie is HTTP-only and encrypted with APP_KEY +- Only works if you've logged in after HADES_TOKEN was set +- Completely disabled if HADES_TOKEN is empty/unset + +## Startup Sequence + +When the container starts, the entrypoint script runs: + +1. **Banner** - Shows environment info (APP_ENV, DB_HOST, REDIS_HOST) +2. **WordPress Setup** - Copies core files if first run, applies patches +3. **Laravel Setup** - Creates storage directories, sets permissions +4. **Migrations** - Runs `php artisan migrate --force` +5. **Config Cache** - Caches config/routes/views (production only) +6. **Supervisord** - Starts nginx, php-fpm, queue workers, scheduler + +### Startup Logs + +You'll see this on startup: +``` +============================================ + Host UK Unified Container +============================================ + + Environment: production + Debug: false + DB Host: mariadb + Redis Host: redis + + Laravel: host.uk.com + WordPress: *.host.uk.com +============================================ +``` + +## Troubleshooting + +### Health Check Failing + +If health checks fail, check in order: + +1. **Is nginx running?** + ```bash + docker exec nginx -t + ``` + +2. **Can you reach /healthz internally?** + ```bash + docker exec curl -s http://localhost/healthz + ``` + +3. **Check supervisord status:** + ```bash + docker exec supervisorctl status + ``` + +### Queue Workers Crashing + +Common causes: +- **Permission denied on logs**: Fixed by `chmod -R 775 storage` +- **SQLite driver missing**: Fixed by adding `php84-pdo_sqlite` +- **Redis unavailable**: Check `REDIS_HOST` environment variable + +### 503 Errors + +Laravel returning 503 usually means: +- Database connection failed - check `DB_HOST`, credentials +- Redis connection failed - check `REDIS_HOST` +- Config cached with wrong values - clear cache and redeploy + +To debug, check Laravel logs: +```bash +docker exec tail -50 /app/storage/logs/laravel.log +``` + +### Permission Errors + +The entrypoint sets permissions at startup: +```bash +chown -R nobody:nobody storage bootstrap/cache +chmod -R 775 storage bootstrap/cache +``` + +If issues persist, check that storage isn't a read-only volume. + +## Updating Paid Libraries + +Flux and Mixpost are vendored locally to avoid auth requirements during CI/CD builds. + +To update: +```bash +make update-paid-libs +``` + +This will: +1. Temporarily enable remote Flux repository +2. Run composer update +3. Copy packages to `product/host-hub/packages/` +4. Restore local-only composer.json +5. Reinstall from local packages + +Then commit: +```bash +git add product/host-hub/packages/ +git commit -m "Update Flux to vX.X.X" +``` + +## Local Development + +```bash +# Start all services +docker-compose -f docker-compose.dev.yml up -d + +# Check status +docker-compose -f docker-compose.dev.yml ps + +# View logs +docker-compose -f docker-compose.dev.yml logs -f app + +# Shell into container +docker-compose -f docker-compose.dev.yml exec app sh + +# Rebuild after changes +docker-compose -f docker-compose.dev.yml build app +docker-compose -f docker-compose.dev.yml up -d app +``` + +Access locally: +- http://host.uk.com → Laravel (requires /etc/hosts entry) +- http://hestia.host.uk.com → WordPress (requires /etc/hosts entry) + +## Domain Routing + +Nginx routes by `Host` header: + +| Domain | Destination | +|--------|-------------| +| `host.uk.com` | Laravel `/app/public` | +| `www.host.uk.com` | Laravel `/app/public` | +| `*.host.uk.com` | WordPress `/var/www/html` | + +## File Locations + +| Path | Contents | +|------|----------| +| `/app` | Laravel Host Hub | +| `/app/storage/logs` | Laravel logs | +| `/var/www/html` | WordPress (runtime) | +| `/usr/src/wordpress` | WordPress (source) | +| `/usr/src/wordpress-patch` | Custom themes/plugins | +| `/etc/nginx/conf.d/default.conf` | Nginx config | +| `/etc/supervisor/conf.d/supervisord.conf` | Process manager config | diff --git a/docs/specs/GUARDS.md b/docs/specs/GUARDS.md new file mode 100644 index 0000000..0eb9f28 --- /dev/null +++ b/docs/specs/GUARDS.md @@ -0,0 +1,416 @@ +# Authentication Guards + +Host UK's native authentication guard implementation for API token-based authentication. + +## Overview + +This is a **native rewrite** of MixPost's authentication guards, rebuilt from the ground up to work with Host UK's Laravel stack. It provides stateful API authentication using personal access tokens. + +**Important:** This is NOT an integration or wrapper around MixPost code. We studied their implementation and built our own version with zero dependencies on `inovector/mixpost`. + +## Architecture + +### Components + +| Component | Location | Purpose | +|-----------|----------|---------| +| **UserToken Model** | `/app/Models/UserToken.php` | Eloquent model for API tokens | +| **AccessTokenGuard** | `/app/Guards/AccessTokenGuard.php` | Authentication guard for Bearer tokens | +| **HasApiTokens Trait** | `/app/Traits/HasApiTokens.php` | User model methods for token management | +| **Migration** | `/database/migrations/2026_01_01_170628_create_user_tokens_table.php` | Database schema | +| **Factory** | `/database/factories/UserTokenFactory.php` | Test data generation | + +### How It Works + +1. **Token Creation**: User creates a token via `$user->createToken('Mobile App')` +2. **Storage**: Token is hashed with SHA-256 and stored in `user_tokens` table +3. **Authentication**: API requests include `Authorization: Bearer {token}` header +4. **Validation**: Guard hashes incoming token, looks up in database, checks expiry +5. **Usage Tracking**: Guard updates `last_used_at` timestamp on successful auth + +## Database Schema + +```sql +CREATE TABLE user_tokens ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, + user_id BIGINT UNSIGNED NOT NULL, + name VARCHAR(255) NOT NULL, -- Human-readable token name + token VARCHAR(64) UNIQUE NOT NULL, -- SHA-256 hash of actual token + last_used_at TIMESTAMP NULL, -- Track usage + expires_at TIMESTAMP NULL, -- Optional expiration + created_at TIMESTAMP NULL, + updated_at TIMESTAMP NULL, + + FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE, + INDEX (token), + INDEX (user_id, created_at) +); +``` + +## Usage + +### Creating Tokens + +```php +use Mod\Tenant\Models\User; + +$user = User::find(1); + +// Create a token (never expires) +$result = $user->createToken('Mobile App'); +$plainToken = $result['token']; // Show this to user ONCE +$tokenModel = $result['model']; // UserToken instance + +// Create a token that expires +$result = $user->createToken( + 'Temporary Access', + now()->addDays(7) +); + +// The plain-text token is only available at creation time +// You MUST save it or show it to the user immediately +``` + +### Managing Tokens + +```php +// List all tokens +$tokens = $user->tokens; + +// Revoke a specific token +$user->revokeToken($tokenId); + +// Revoke all tokens (e.g., on password change) +$user->revokeAllTokens(); + +// Check token validity +$token = UserToken::findToken($plainTextToken); +if ($token && $token->isValid()) { + // Token is good +} +``` + +### Using in API Routes + +```php +use Illuminate\Support\Facades\Route; + +// Protect routes with the access_token guard +Route::middleware('auth:access_token')->prefix('v1')->group(function () { + Route::get('/social/posts', [SocialPostController::class, 'index']); + Route::post('/social/posts', [SocialPostController::class, 'store']); +}); + +// In your controller +public function index(Request $request) +{ + $user = $request->user(); // Authenticated user + $workspace = $user->defaultHostWorkspace(); + + // Your logic here +} +``` + +### Making API Requests + +```bash +# Include token in Authorization header +curl -X GET https://host.uk.com/api/v1/social/posts \ + -H "Authorization: Bearer your-40-character-token-here" \ + -H "Accept: application/json" +``` + +## Security Features + +### Token Hashing + +Tokens are **never stored in plain text**. We use SHA-256 hashing: + +```php +// When creating a token +$plainToken = Str::random(40); // 40 random characters +$hashed = hash('sha256', $plainToken); // Store this + +// When authenticating +$incoming = $request->bearerToken(); +$hashed = hash('sha256', $incoming); +$token = UserToken::where('token', $hashed)->first(); +``` + +### Expiry Handling + +Tokens can optionally expire: + +```php +// Check if expired +if ($token->isExpired()) { + return response()->json(['error' => 'Token expired'], 401); +} + +// Only valid tokens authenticate +if ($token->isValid()) { + // Not expired (or no expiry set) +} +``` + +### Usage Tracking + +Every successful authentication updates `last_used_at`: + +```php +// Preserves hasModifiedRecords state to avoid triggering model events +$token->recordUsage(); +``` + +This is useful for: +- Detecting abandoned/unused tokens +- Security auditing +- Automatic cleanup of stale tokens + +## Configuration + +### Register the Guard + +The guard is registered in `AppServiceProvider::boot()`: + +```php +use Mod\Api\Guards\AccessTokenGuard; +use Illuminate\Support\Facades\Auth; + +Auth::viaRequest('access_token', new AccessTokenGuard($this->app['auth'])); +``` + +### Auth Config + +Guard is defined in `config/auth.php`: + +```php +'guards' => [ + 'web' => [ + 'driver' => 'session', + 'provider' => 'users', + ], + + 'access_token' => [ + 'driver' => 'access_token', + 'provider' => 'users', + ], +], +``` + +## Testing + +### Factory Usage + +```php +use Mod\Tenant\Models\User; +use Mod\Tenant\Models\UserToken; + +// Create a token for testing +$user = User::factory()->create(); +$token = UserToken::factory() + ->for($user) + ->withToken('test-token-12345') + ->create(); + +// Test with known token +$response = $this->getJson('/api/v1/social/posts', [ + 'Authorization' => 'Bearer test-token-12345', +]); + +// Create expired token +$expiredToken = UserToken::factory() + ->expired() + ->create(); + +// Create token that expires in 7 days +$futureToken = UserToken::factory() + ->expiresIn(7) + ->create(); + +// Create recently-used token +$usedToken = UserToken::factory() + ->used() + ->create(); +``` + +### Test Example + +```php +use Mod\Tenant\Models\User; +use Mod\Tenant\Models\UserToken; + +test('can authenticate with valid token', function () { + $user = User::factory()->create(); + $result = $user->createToken('Test Token'); + + $response = $this->getJson('/api/v1/social/posts', [ + 'Authorization' => "Bearer {$result['token']}", + ]); + + $response->assertOk(); +}); + +test('cannot authenticate with expired token', function () { + $user = User::factory()->create(); + $token = UserToken::factory() + ->for($user) + ->expired() + ->withToken('expired-token') + ->create(); + + $response = $this->getJson('/api/v1/social/posts', [ + 'Authorization' => 'Bearer expired-token', + ]); + + $response->assertUnauthorized(); +}); +``` + +## Design Decisions + +### Why Not Laravel Sanctum? + +While Sanctum is excellent, we built our own solution because: + +1. **Learning from MixPost**: We're studying their implementation patterns +2. **Full Control**: Can customise every aspect for Host UK's needs +3. **Simplicity**: Only need Bearer token auth, not full SPA + mobile token system +4. **No Extra Dependencies**: One less package to maintain + +### Why SHA-256 Over Bcrypt? + +- **Performance**: SHA-256 is faster for token lookups (not passwords!) +- **Token Uniqueness**: Tokens are already random 40-character strings +- **MixPost Compatibility**: Matches their approach for easier migration +- **Security**: Still secure since tokens are unguessable random strings + +For **passwords**, we still use bcrypt/argon2 via Laravel's hashing. + +### Why Separate Guard vs Middleware? + +- **Guard**: Handles **authentication** (who is the user?) +- **Middleware**: Can handle **authorisation** (what can they do?) + +This separation follows Laravel's architecture patterns. + +## Migration from MixPost + +If you're migrating existing MixPost token data: + +```php +use Inovector\Mixpost\Models\UserToken as MixpostToken; +use Mod\Tenant\Models\UserToken as HostToken; + +// Migrate tokens from MixPost to Host UK +MixpostToken::all()->each(function ($mixpostToken) { + HostToken::create([ + 'user_id' => $mixpostToken->user_id, + 'name' => $mixpostToken->name, + 'token' => $mixpostToken->token, // Already hashed + 'last_used_at' => $mixpostToken->last_used_at, + 'expires_at' => $mixpostToken->expires_at, + 'created_at' => $mixpostToken->created_at, + 'updated_at' => $mixpostToken->updated_at, + ]); +}); +``` + +## Best Practices + +### Token Naming + +Use descriptive names so users can identify tokens: + +```php +// Good +$user->createToken('iPhone 15 Pro'); +$user->createToken('GitHub Actions CI'); +$user->createToken('Zapier Integration'); + +// Bad +$user->createToken('Token 1'); +$user->createToken('My Token'); +``` + +### Token Rotation + +Rotate tokens periodically for security: + +```php +// Revoke old token and create new one +$user->revokeToken($oldTokenId); +$newToken = $user->createToken('Rotated Mobile Token', now()->addDays(90)); +``` + +### Workspace Context + +Always resolve the workspace for API requests: + +```php +public function index(Request $request) +{ + $user = $request->user(); + $workspace = $user->defaultHostWorkspace(); + + // Scope queries to workspace + $posts = $workspace->socialPosts()->get(); + + return response()->json($posts); +} +``` + +### Rate Limiting + +Always rate limit API routes: + +```php +Route::middleware(['auth:access_token', 'throttle:api']) + ->prefix('v1') + ->group(function () { + // Protected routes + }); +``` + +## Troubleshooting + +### "Unauthenticated" Response + +Check: +1. Token is included in `Authorization: Bearer {token}` header +2. Token hasn't expired: `$token->expires_at` +3. Token exists in database (check hash matches) +4. Guard is registered in `AppServiceProvider` +5. Route uses `auth:access_token` middleware + +### Token Not Found + +```php +$token = UserToken::findToken($plainToken); +if (!$token) { + // Either: + // - Token was revoked + // - Token value is incorrect + // - Database not migrated +} +``` + +### Performance Issues + +If you have millions of tokens: +1. Add index on `last_used_at` for cleanup queries +2. Regularly prune expired/unused tokens: + +```php +// Artisan command to clean up tokens +UserToken::where('expires_at', '<', now()) + ->orWhere('last_used_at', '<', now()->subMonths(6)) + ->delete(); +``` + +## Further Reading + +- [Laravel Authentication](https://laravel.com/docs/authentication) +- [Custom Guards](https://laravel.com/docs/authentication#adding-custom-guards) +- [API Authentication](https://laravel.com/docs/sanctum#how-it-works) +- MixPost Reference: `/packages/mixpost-pro-team/src/Guards/AccessTokenGuard.php` diff --git a/docs/specs/RFC-0001-network-overview.md b/docs/specs/RFC-0001-network-overview.md new file mode 100644 index 0000000..856041e --- /dev/null +++ b/docs/specs/RFC-0001-network-overview.md @@ -0,0 +1,320 @@ +# RFC-0001: Lethean Network Overview + +``` +RFC: 0001 +Title: Lethean Network Overview +Status: Standard +Category: Informational +Authors: Darbs, Snider +License: EUPL-1.2 +Created: 2026-02-01 +Replaces: N/A +``` + +--- + +## Abstract + +This document describes the Lethean Network, a decentralized Virtual Private Network (VPN) and proxy service built on blockchain technology. The network enables peer-to-peer connectivity services where providers (Exit Nodes) offer bandwidth and users pay directly using LTHN cryptocurrency, without intermediaries. + +--- + +## 1. Introduction + +### 1.1 Purpose + +Lethean provides privacy-preserving internet access through a decentralized network of Exit Nodes. Unlike traditional VPN services that rely on centralized providers, Lethean distributes trust across independent node operators who are compensated directly by users via blockchain transactions. + +### 1.2 Design Goals + +1. **Decentralization** - No single point of control or failure +2. **Privacy** - Untraceable payments and connections +3. **Censorship Resistance** - No central registration authority +4. **Economic Sustainability** - Direct provider compensation +5. **Open Source** - Fully auditable codebase (EUPL-1.2) + +### 1.3 Terminology + +| Term | Definition | +|------|------------| +| **Exit Node** | Server providing VPN/proxy services to clients | +| **SDP** | Service Descriptor Protocol - discovery mechanism | +| **LTHN** | Lethean token - native cryptocurrency | +| **Dispatcher** | Exit Node component handling authentication and routing | +| **VDP** | Virtual Data Provider - node metadata record | + +--- + +## 2. Network Architecture + +### 2.1 Layer Model + +``` +┌─────────────────────────────────────────────────────────────┐ +│ APPLICATION LAYER │ +│ (Lethean Wallet GUI, CLI clients, lvpnc) │ +├─────────────────────────────────────────────────────────────┤ +│ SERVICE LAYER │ +│ (SDP Discovery, VDP Management) │ +├─────────────────────────────────────────────────────────────┤ +│ TRANSPORT LAYER │ +│ (Exit Nodes: HAProxy, TinyProxy, OpenVPN) │ +├─────────────────────────────────────────────────────────────┤ +│ PAYMENT LAYER │ +│ (LTHN Blockchain, Wallet RPC, Dispatcher) │ +├─────────────────────────────────────────────────────────────┤ +│ CONSENSUS LAYER │ +│ (Hybrid PoW/PoS, letheand daemon) │ +└─────────────────────────────────────────────────────────────┘ +``` + +### 2.2 Network Participants + +#### 2.2.1 Users (Clients) +- Discover available Exit Nodes via SDP +- Pay for services using LTHN +- Connect through selected Exit Nodes + +#### 2.2.2 Exit Node Operators (Providers) +- Run infrastructure providing VPN/proxy services +- Publish service offerings to SDP +- Receive direct LTHN payments from users + +#### 2.2.3 Daemon Operators +- Run blockchain nodes (letheand) +- Maintain network consensus +- Eligible for daemon rewards (see RFC-0004) + +#### 2.2.4 Governors +- Participate in network governance +- Vote on protocol changes +- Manage community direction + +### 2.3 Core Components + +| Component | Purpose | Reference | +|-----------|---------|-----------| +| letheand | Blockchain daemon | Consensus layer | +| lethean-wallet-cli | Wallet operations | Payment layer | +| Dispatcher (lthnvpnd) | Exit Node orchestration | RFC-0003 | +| SDP Server | Service discovery | RFC-0002 | +| lvpnc | Client software | RFC-0005 | + +--- + +## 3. Blockchain Foundation + +### 3.1 Consensus Mechanism + +Lethean uses a hybrid Proof-of-Work / Proof-of-Stake consensus: + +- **Algorithm**: Argon2id (Chukwav2 variant) +- **Block Time**: ~120 seconds +- **Privacy**: CryptoNote-based (untraceable transactions) + +### 3.2 Token Economics + +| Parameter | Value | +|-----------|-------| +| Ticker | LTHN | +| Total Supply | 1,000,000,000 (1B) | +| Decimals | 8 | +| Emission | Decreasing curve | + +### 3.3 Blockchain Role + +The blockchain provides: + +1. **Payment Settlement** - Direct user-to-provider transactions +2. **Identity** - Wallet addresses as pseudonymous identities +3. **Agreements** - Smart contract capability for service terms +4. **Audit Trail** - Immutable record of provider SLA performance + +--- + +## 4. Data Flow + +### 4.1 Service Discovery + +``` +User SDP Server Exit Node + │ │ │ + │ GET /v1/services/search │ │ + │─────────────────────────>│ │ + │ │ │ + │ Provider List (JSON) │ │ + │<─────────────────────────│ │ + │ │ │ + │ Select Provider │ │ + │ │ │ +``` + +### 4.2 Payment & Connection + +``` +User Blockchain Exit Node + │ │ │ + │ Send LTHN Payment │ │ + │─────────────────────────>│ │ + │ │ Transaction Confirmed │ + │ │───────────────────────>│ + │ │ │ + │ Connect (TCP 8880) │ │ + │─────────────────────────────────────────────────>│ + │ │ │ + │ Dispatcher Validates │ │ + │<─────────────────────────────────────────────────│ + │ │ │ + │ Tunnel Established │ │ + │<════════════════════════════════════════════════>│ +``` + +### 4.3 Provider Registration + +``` +Exit Node VDP Manager SDP Server + │ │ │ + │ Generate VDP │ │ + │ (lvmgmt --generate-sdp) │ │ + │ │ │ + │ Push VDP │ │ + │─────────────────────────>│ │ + │ │ │ + │ │ Sync (hourly) │ + │ │───────────────────────>│ + │ │ │ + │ Refresh (every 3500s) │ │ + │─────────────────────────>│ │ +``` + +--- + +## 5. Security Model + +### 5.1 Threat Model + +Lethean protects against: + +1. **Surveillance** - ISPs cannot see destination traffic +2. **Censorship** - No central authority to block +3. **Payment Tracking** - Untraceable LTHN transactions +4. **Provider Collusion** - Users choose their own providers + +### 5.2 Trust Assumptions + +- Users trust their selected Exit Node operator +- Exit Node operators trust the blockchain for payments +- No global trust authority required + +### 5.3 Privacy Properties + +| Property | Mechanism | +|----------|-----------| +| Payment Privacy | CryptoNote ring signatures | +| Connection Privacy | TLS + VPN/Proxy tunneling | +| Identity Privacy | Pseudonymous wallet addresses | + +--- + +## 6. Governance + +### 6.1 Current Structure + +The Lethean project is maintained by an Open Source Software (OSS) team: + +- **Darbs** - Co-owner, technical architecture +- **Snider** - Co-owner, project lead + +### 6.2 License + +All Lethean software is released under the European Union Public License (EUPL-1.2), ensuring: + +- Freedom to use, modify, and distribute +- Copyleft protection for derivatives +- Compatibility with other OSS licenses + +### 6.3 Decision Making + +Protocol changes follow this process: + +1. RFC proposal submitted +2. Community discussion period +3. Implementation by maintainers +4. Network upgrade coordination + +--- + +## 7. Related RFCs + +| RFC | Title | Status | +|-----|-------|--------| +| RFC-0002 | Service Descriptor Protocol (SDP) | Standard | +| RFC-0003 | Exit Node Architecture | Standard | +| RFC-0004 | Payment & Dispatcher Protocol | Standard | +| RFC-0005 | Client Protocol | Standard | + +--- + +## 8. References + +### 8.1 Implementations + +- **letheand**: https://github.com/letheanVPN/lethean +- **Exit Node**: https://github.com/letheanVPN/lvpn +- **dAppServer**: https://github.com/dAppServer + +### 8.2 External Dependencies + +- CryptoNote protocol (privacy layer) +- OpenVPN (VPN implementation) +- WireGuard (tunnel transport) +- HAProxy (load balancing) + +--- + +## 9. Changelog + +| Version | Date | Changes | +|---------|------|---------| +| 1.0 | 2026-02-01 | Initial RFC specification | + +--- + +## Appendix A: Network Diagram + +``` + ┌─────────────────────┐ + │ Internet │ + │ "Clearnet" │ + └──────────┬──────────┘ + │ + ┌──────────────────────────┼──────────────────────────┐ + │ │ │ + ▼ ▼ ▼ + ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ + │ Exit Node │ │ Exit Node │ │ Exit Node │ + │ (Europe) │ │ (Asia) │ │ (Americas) │ + └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ + │ │ │ + └─────────────────────────┼──────────────────────────┘ + │ + ┌───────┴───────┐ + │ Lethernet │ + │ Network │ + └───────┬───────┘ + │ + ┌─────────────────┼─────────────────┐ + │ │ │ + ▼ ▼ ▼ + ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ + │ SDP │ │ Blockchain │ │ Kevacoin │ + │ Discovery │ │ (LTHN) │ │ Storage │ + └─────────────┘ └─────────────┘ └─────────────┘ + │ │ │ + └─────────────────┼─────────────────┘ + │ + ┌───────┴───────┐ + │ Users │ + │ (Clients) │ + └───────────────┘ +``` diff --git a/docs/specs/RFC-0002-service-descriptor-protocol.md b/docs/specs/RFC-0002-service-descriptor-protocol.md new file mode 100644 index 0000000..8d69268 --- /dev/null +++ b/docs/specs/RFC-0002-service-descriptor-protocol.md @@ -0,0 +1,410 @@ +# RFC-0002: Service Descriptor Protocol (SDP) + +``` +RFC: 0002 +Title: Service Descriptor Protocol (SDP) +Status: Standard +Category: Standards Track +Authors: Darbs, Snider +License: EUPL-1.2 +Created: 2026-02-01 +Requires: RFC-0001 +``` + +--- + +## Abstract + +This document specifies the Service Descriptor Protocol (SDP), the discovery mechanism that enables Lethean clients to find and connect to Exit Node providers. SDP defines how providers publish their services and how clients query available offerings. + +--- + +## 1. Introduction + +### 1.1 Purpose + +SDP solves the discovery problem in a decentralized VPN network: how do users find providers without a central authority? SDP provides a standardized format for service advertisements and a query interface for clients. + +### 1.2 Design Principles + +1. **Provider Autonomy** - Providers control their own listings +2. **Client Choice** - Users select providers based on published criteria +3. **Decentralization Ready** - Designed for distributed hosting +4. **Extensibility** - Support for future service types + +--- + +## 2. Protocol Overview + +### 2.1 Components + +``` +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│ Client │ │ SDP Server │ │ Exit Node │ +│ │ Query │ │ Sync │ │ +│ │─────────>│ │<─────────│ │ +│ │ │ │ │ │ +│ │ Results │ │ VDP │ │ +│ │<─────────│ │─────────>│ │ +└─────────────┘ └─────────────┘ └─────────────┘ +``` + +### 2.2 Data Flow + +1. **Publication**: Exit Nodes generate VDP (Virtual Data Provider) records +2. **Registration**: VDP pushed to VDP Manager +3. **Aggregation**: SDP Server collects VDPs from all managers +4. **Query**: Clients request service listings from SDP endpoint +5. **Selection**: Client chooses provider based on criteria + +--- + +## 3. VDP Record Format + +### 3.1 Provider Metadata + +```json +{ + "provider": { + "id": "<64-char hex string>", + "name": "", + "wallet": "", + "terms": "", + "type": "commercial|community", + "ca": "" + } +} +``` + +### 3.2 Field Definitions + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| id | string(64) | Yes | Unique provider identifier (hex) | +| name | string(16) | Yes | Human-readable provider name | +| wallet | string | Yes | LTHN payment address | +| terms | string | No | URL or `@filename` for terms | +| type | enum | No | `commercial` or `community` | +| ca | string | Yes | PEM certificate, base64 encoded | + +### 3.3 Service Definitions + +```json +{ + "services": [ + { + "id": "1A", + "type": "proxy", + "name": "AU Melbourne Proxy 1", + "endpoint": "proxy.example.com", + "port": 8080, + "cost": "0.1", + "speed": "100mbps", + "location": { + "country": "AU", + "city": "Melbourne" + } + }, + { + "id": "2A", + "type": "vpn", + "name": "AU Melbourne VPN 1", + "endpoint": "vpn.example.com", + "port": 18080, + "cost": "0.15", + "protocol": "openvpn" + } + ] +} +``` + +### 3.4 Service ID Convention + +| Range | Type | Description | +|-------|------|-------------| +| 1A-1Z | proxy | HTTP/HTTPS proxy services | +| 2A-2Z | vpn | VPN tunnel services | +| C1A+ | client | Client-side service configs | + +--- + +## 4. DNS Discovery + +### 4.1 TXT Record Format + +Providers MAY publish a DNS TXT record for decentralized discovery: + +``` +_lethean.example.com TXT "lv=v3;sdp=https://example.com/sdp.json;id=" +``` + +### 4.2 TXT Record Fields + +| Field | Description | +|-------|-------------| +| lv | Protocol version (currently `v3`) | +| sdp | URL to provider's sdp.json file | +| id | Provider ID (64-char hex) | + +### 4.3 Example + +``` +_lethean.exitnode.example TXT "lv=v3;sdp=https://monitor.lethean.io/sdp.json;id=7b08c778af3b28932185d7cc804b0cf399c05c9149613dc149dff5f30c8cd989" +``` + +--- + +## 5. SDP API + +### 5.1 Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| GET | /v1/services/search | Query available services | +| GET | /v1/providers/{id} | Get specific provider details | +| POST | /v1/providers | Register/update provider (authenticated) | + +### 5.2 Search Query Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| type | string | Filter by service type (`proxy`, `vpn`) | +| country | string | Filter by country code (ISO 3166-1) | +| max_cost | number | Maximum cost in LTHN | +| min_speed | string | Minimum speed (e.g., `10mbps`) | + +### 5.3 Search Response + +```json +{ + "providers": [ + { + "id": "efaa812b358956f93a0e324385c8b44469a99e5a82f2de327297b25d8c2ee288", + "name": "Lethean_Re-Born", + "wallet": "iz5HSgJUW0max8Hs2TEAacKhKA9LXLLDvc4u7yCV7Lm4iwkgFXTMFBAdtj2mqMpqy7T4BNveDQdW8LBPVxWqy94B2A6sKJXQ7", + "services": [ + { + "id": "1A", + "type": "proxy", + "name": "AU Melbourne Proxy 1", + "cost": "0.1", + "port": 8080 + } + ], + "ca": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" + } + ], + "total": 1, + "timestamp": "2026-02-01T12:00:00Z" +} +``` + +--- + +## 6. VDP Synchronization + +### 6.1 Sync Protocol + +Exit Nodes synchronize with the VDP Manager: + +``` +Exit Node VDP Manager + │ │ + │ POST /vdp (VDP record) │ + │───────────────────────────────────>│ + │ │ + │ 200 OK + TTL │ + │<───────────────────────────────────│ + │ │ + │ ... wait (TTL - buffer) ... │ + │ │ + │ POST /vdp (refresh) │ + │───────────────────────────────────>│ +``` + +### 6.2 Timing Parameters + +| Parameter | Value | Description | +|-----------|-------|-------------| +| TTL | 3600 seconds | VDP time-to-live (1 hour) | +| Refresh Buffer | 100 seconds | Refresh before TTL expires | +| Refresh Interval | 3500 seconds | Typical refresh cycle | + +### 6.3 VDP Manager Endpoints + +| Endpoint | Description | +|----------|-------------| +| mgr.lethean.space | Primary VDP Manager | +| vpn2.lethean.space:8774 | WireGuard tunnel endpoint | + +--- + +## 7. sdp.json File Format + +### 7.1 Complete Example + +```json +{ + "version": "3", + "generated": "2026-02-01T12:00:00Z", + "provider": { + "id": "efaa812b358956f93a0e324385c8b44469a99e5a82f2de327297b25d8c2ee288", + "name": "Lethean ReBorn", + "wallet": "iz5HSgJUW0max8Hs2TEAacKhKA9LXLLDvc...", + "terms": "https://provider.example/terms", + "type": "commercial" + }, + "ca": "-----BEGIN CERTIFICATE-----\nMIIDXTCCAkWgAw...\n-----END CERTIFICATE-----", + "services": [ + { + "id": "1A", + "type": "proxy", + "name": "AU Melbourne Proxy 1", + "endpoint": "au-mel.provider.example", + "port": 8080, + "cost": "0.1", + "firstVerificationsRequired": 1, + "subsequentVerificationsRequired": 1, + "speed": "100mbps", + "location": { + "country": "AU", + "region": "Victoria", + "city": "Melbourne" + }, + "restrictions": [] + } + ] +} +``` + +### 7.2 Verification Fields + +| Field | Type | Description | +|-------|------|-------------| +| firstVerificationsRequired | integer (0-2) | Confirmations for first payment | +| subsequentVerificationsRequired | integer (0-1) | Confirmations for subsequent payments | + +Lower values = faster connection, higher risk +Higher values = slower connection, lower risk + +--- + +## 8. Security Considerations + +### 8.1 Provider Authenticity + +- Provider ID derived from cryptographic key +- CA certificate validates service endpoints +- Wallet address ties provider to blockchain identity + +### 8.2 Man-in-the-Middle Protection + +- SDP endpoint MUST use HTTPS +- Client MUST verify provider CA before connecting +- DNS TXT records provide secondary verification + +### 8.3 Sybil Resistance + +- Providers must stake resources (infrastructure) +- SLA monitoring identifies poor performers +- User reviews (future: on-chain reputation) + +--- + +## 9. Implementation Notes + +### 9.1 Generating SDP Configuration + +```bash +lvmgmt --generate-sdp --wallet-address +``` + +Interactive prompts: +1. Provider name (max 16 chars) +2. Service name (max 32 chars) +3. Service type (vpn/proxy) +4. Port number (1-65535) +5. Cost in LTHN +6. Confirmation requirements + +Output: `/opt/lthn/etc/sdp.json` + +### 9.2 Client Integration + +```python +# Pseudocode for SDP query +response = http.get("https://sdp.lethean.io/v1/services/search", + params={"type": "proxy", "country": "AU"}) +providers = response.json()["providers"] + +for provider in providers: + print(f"{provider['name']}: {provider['services'][0]['cost']} LTHN") +``` + +--- + +## 10. Future Considerations + +### 10.1 Decentralized SDP + +Current implementation uses centralized SDP servers. Future versions may: + +- Store VDP records on Kevacoin (key-value blockchain) +- Use DHT (Distributed Hash Table) for discovery +- Enable direct peer-to-peer provider queries + +### 10.2 Extended Service Types + +SDP is designed to support services beyond VPN/proxy: + +- Hosting services +- Storage services +- Computation services +- Custom BYOA (Bring Your Own Application) + +--- + +## 11. References + +- RFC-0001: Lethean Network Overview +- RFC-0003: Exit Node Architecture +- Lethean SDP Design (HLA) v0.1 + +--- + +## Appendix A: JSON Schema + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "required": ["version", "provider", "services"], + "properties": { + "version": {"type": "string", "pattern": "^[0-9]+$"}, + "provider": { + "type": "object", + "required": ["id", "name", "wallet"], + "properties": { + "id": {"type": "string", "pattern": "^[a-f0-9]{64}$"}, + "name": {"type": "string", "maxLength": 16}, + "wallet": {"type": "string"}, + "terms": {"type": "string"}, + "type": {"enum": ["commercial", "community"]} + } + }, + "services": { + "type": "array", + "items": { + "type": "object", + "required": ["id", "type", "port", "cost"], + "properties": { + "id": {"type": "string", "pattern": "^[12C][A-Z0-9]+$"}, + "type": {"enum": ["proxy", "vpn"]}, + "port": {"type": "integer", "minimum": 1, "maximum": 65535}, + "cost": {"type": "string"} + } + } + } + } +} +``` diff --git a/docs/specs/RFC-0003-exit-node-architecture.md b/docs/specs/RFC-0003-exit-node-architecture.md new file mode 100644 index 0000000..57e95a9 --- /dev/null +++ b/docs/specs/RFC-0003-exit-node-architecture.md @@ -0,0 +1,489 @@ +# RFC-0003: Exit Node Architecture + +``` +RFC: 0003 +Title: Exit Node Architecture +Status: Standard +Category: Standards Track +Authors: Darbs, Snider +License: EUPL-1.2 +Created: 2026-02-01 +Requires: RFC-0001, RFC-0002 +``` + +--- + +## Abstract + +This document specifies the architecture and operation of Lethean Exit Nodes—the infrastructure components that provide VPN and proxy services to network users. It covers deployment, configuration, service components, and operational requirements. + +--- + +## 1. Introduction + +### 1.1 Purpose + +Exit Nodes are the service delivery points of the Lethean network. They receive user traffic, validate payments, and route connections to the internet. This RFC standardizes Exit Node implementation to ensure interoperability and consistent user experience. + +### 1.2 Scope + +This document covers: +- Exit Node component architecture +- Deployment and configuration +- Service types and protocols +- Operational requirements + +--- + +## 2. Architecture Overview + +### 2.1 Component Stack + +``` +┌─────────────────────────────────────────────────────────────┐ +│ EXTERNAL INTERFACE │ +│ (Internet-facing ports) │ +├──────────────────────┬──────────────────────────────────────┤ +│ HAProxy │ TCP 8880 (HTTP) │ +│ (Load Balancer) │ TCP 8881 (HTTPS/TLS) │ +├──────────────────────┼──────────────────────────────────────┤ +│ │ │ +│ ┌──────────────────┴───────────────────────────┐ │ +│ │ SERVICE LAYER │ │ +│ │ ┌─────────────┐ ┌─────────────┐ │ │ +│ │ │ TinyProxy │ │ OpenVPN │ │ │ +│ │ │ TCP 8888 │ │ UDP 18080 │ │ │ +│ │ └─────────────┘ └─────────────┘ │ │ +│ └──────────────────────────────────────────────┘ │ +│ │ +├─────────────────────────────────────────────────────────────┤ +│ DISPATCHER (lthnvpnd) │ +│ Payment validation & routing │ +├──────────────────────┬──────────────────────────────────────┤ +│ │ │ +│ ┌──────────────────┴───────────────────────────┐ │ +│ │ BLOCKCHAIN LAYER │ │ +│ │ ┌─────────────┐ ┌─────────────┐ │ │ +│ │ │ letheand │ │ Wallet │ │ │ +│ │ │TCP 48782/72 │ │ TCP 1444/45 │ │ │ +│ │ └─────────────┘ └─────────────┘ │ │ +│ └──────────────────────────────────────────────┘ │ +│ │ +├─────────────────────────────────────────────────────────────┤ +│ MANAGEMENT LAYER │ +│ lvmgmt, lvpnc-client-man (TCP 8124), Nginx │ +└─────────────────────────────────────────────────────────────┘ +``` + +### 2.2 Component Summary + +| Component | Binary | Ports | Purpose | +|-----------|--------|-------|---------| +| HAProxy | haproxy | 8880, 8881 | Load balancing, TLS termination | +| TinyProxy | tinyproxy | 8888 | HTTP/HTTPS proxy service | +| OpenVPN | openvpn | 18080/UDP | VPN tunnel service | +| Dispatcher | lthnvpnd | - | Payment validation, routing | +| Daemon | letheand | 48782, 48772 | Blockchain node | +| Wallet | lethean-wallet-vpn-rpc | 1444, 1445 | Payment handling | +| Client Manager | lvpnc-client-man | 8124 | Client session management | +| Management | lvmgmt | - | Configuration, SDP generation | + +--- + +## 3. Deployment + +### 3.1 Docker Deployment (Recommended) + +Exit Nodes are deployed as Docker containers for consistency: + +```bash +docker run -d \ + --name lethean-node \ + -p 8880:8880 \ + -p 8881:8881 \ + -p 8888:8888 \ + -p 18080:18080/udp \ + -v /opt/lthn:/opt/lthn \ + letheanvpn/lvpn:latest +``` + +### 3.2 Startup Sequence + +When the container starts in **node mode**: + +1. **WireGuard Connection** + - Connects to Lethean space via WireGuard + - Endpoint: `vpn2.lethean.space:8774` + +2. **Blockchain Sync** + - letheand starts and syncs blockchain + - Connects to configured seed peers + - Private address: `172.31.129.19` (via tunnel) + +3. **Easy-Deploy** + - Automated infrastructure setup + - Certificate generation + - Service configuration + +4. **Wallet RPC** + - lethean-wallet-vpn-rpc starts + - Listens on `127.0.0.1:14660` + +5. **Proxy Services** + - TinyProxy starts on port 8888 + - OpenVPN starts on port 18080 (if enabled) + +6. **VDP Registration** + - Pushes VDP to VDP Manager + - URL: `https://mgr.lethean.space` + +7. **VDP Sync Loop** + - Fetches provider list from VDP Manager + - Refreshes every 3500 seconds (TTL: 3600s) + +--- + +## 4. Configuration + +### 4.1 dispatcher.ini + +The primary configuration file at `/opt/lthn/etc/dispatcher.ini`: + +#### 4.1.1 Global Section + +```ini +[global] +; Debug level: DEBUG, INFO, WARN, ERROR +debug=INFO + +; CA certificate for provider identity +ca=/opt/lthn/etc/ca/certs/ca.cert.pem + +; Provider identification +provider-id=efaa812b358956f93a0e324385c8b44469a99e5a82f2de327297b25d8c2ee288 +provider-key= +provider-name=MyExitNode +provider-type=commercial + +; Terms of service +provider-terms=https://example.com/terms +; Or from file: provider-terms=@/opt/lthn/etc/terms.txt +``` + +#### 4.1.2 Wallet Section + +```ini +; Wallet configuration +wallet-address=iz5HSgJUW0max8Hs2TEAacKhKA9LXLLDvc4u7yCV7Lm4iwkgFXTMFBAdtj2mqMpqy7T4BNveDQdW8LBPVxWqy94B2A6sKJXQ7 +wallet-rpc-uri=http://127.0.0.1:14660/json_rpc +wallet-username=dispatcher +wallet-password= +``` + +#### 4.1.3 Proxy Service (1A-1Z) + +```ini +[service-1A] +name=AU_Melbourne_Proxy1 +backend_proxy_server=localhost:3128 +crt=/opt/lthn/etc/ca/certs/ha.cert.pem +key=/opt/lthn/etc/ca/private/ha.key.pem +crtkey=/opt/lthn/etc/ca/certs/ha.both.pem +``` + +#### 4.1.4 VPN Service (2A-2Z) + +```ini +[service-1B] +crt=/opt/lthn/etc/ca/certs/openvpn.cert.pem +key=/opt/lthn/etc/ca/private/openvpn.key.pem +crtkey=/opt/lthn/etc/ca/certs/openvpn.both.pem +reneg=600 +enabled=true +iprange=10.8.0.0 +ipmask=255.255.255.0 +ip6range=fd00::/64 +dns=1.1.1.1 +mgmtport=11123 +``` + +### 4.2 Configuration Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| provider-id | hex(64) | Yes | Unique provider identifier | +| provider-key | string | Yes | Authentication secret | +| provider-name | string(16) | Yes | Display name | +| wallet-address | string | Yes | LTHN payment address | +| wallet-rpc-uri | URL | Yes | Wallet RPC endpoint | +| backend_proxy_server | host:port | Per-service | Proxy backend | +| crt | path | Per-service | Service certificate | +| key | path | Per-service | Private key | +| reneg | integer | VPN only | Renegotiation interval (seconds) | +| iprange | CIDR | VPN only | Client IP pool | + +--- + +## 5. Service Types + +### 5.1 HTTP Proxy (Type: proxy) + +**Implementation**: TinyProxy or Squid + +**Ports**: +- External: 8080 (via HAProxy 8880) +- Internal: 8888, 3128 + +**Features**: +- HTTP/HTTPS forwarding +- Optional authentication +- Access logging + +**Use Cases**: +- Browser-based privacy +- Application proxy configuration +- Lightweight traffic routing + +### 5.2 VPN Tunnel (Type: vpn) + +**Implementation**: OpenVPN + +**Ports**: +- UDP 18080 (primary) +- TCP 443 (fallback, optional) + +**Features**: +- Full tunnel encryption +- All traffic routing +- DNS leak protection + +**Configuration Options**: +```ini +iprange=10.8.0.0 ; Client IP pool start +ipmask=255.255.255.0 ; Subnet mask +ip6range=fd00::/64 ; IPv6 pool +dns=1.1.1.1 ; DNS server for clients +reneg=600 ; Rekey interval +``` + +### 5.3 Future Service Types + +The architecture supports additional service types: + +- **SOCKS5 Proxy** (planned) +- **WireGuard VPN** (planned) +- **Custom BYOA** (Bring Your Own Application) + +--- + +## 6. Security + +### 6.1 Certificate Architecture + +``` +Root CA (provider) + │ + ├── HAProxy Certificate (TLS termination) + │ + ├── Proxy Service Certificate + │ + └── VPN Service Certificate +``` + +### 6.2 Certificate Generation + +```bash +# Generate CA +openssl genrsa -out ca.key 4096 +openssl req -new -x509 -days 3650 -key ca.key -out ca.cert.pem + +# Generate service certificate +openssl genrsa -out service.key 2048 +openssl req -new -key service.key -out service.csr +openssl x509 -req -in service.csr -CA ca.cert.pem -CAkey ca.key \ + -CAcreateserial -out service.cert.pem -days 365 +``` + +### 6.3 Access Control + +The Dispatcher validates: + +1. **Payment Verification** - Check blockchain for valid transaction +2. **Session Management** - Track active sessions +3. **Rate Limiting** - Prevent abuse +4. **Geographic Restrictions** - Optional country blocking + +--- + +## 7. Monitoring + +### 7.1 Health Checks + +Exit Nodes should implement health endpoints: + +| Endpoint | Purpose | +|----------|---------| +| /health | Basic liveness check | +| /status | Detailed component status | +| /metrics | Prometheus-compatible metrics | + +### 7.2 Zabbix Integration + +For daemon reward eligibility (see RFC-0004): + +``` +Zabbix Agent → letheand port check + → Blockchain height sync + → Service availability +``` + +### 7.3 Logging + +Recommended log locations: + +``` +/var/log/lthn/dispatcher.log +/var/log/lthn/haproxy.log +/var/log/lthn/tinyproxy.log +/var/log/lthn/openvpn.log +``` + +--- + +## 8. Network Requirements + +### 8.1 Bandwidth + +| Tier | Minimum | Recommended | +|------|---------|-------------| +| Basic | 10 Mbps | 100 Mbps | +| Standard | 100 Mbps | 1 Gbps | +| Premium | 1 Gbps | 10 Gbps | + +### 8.2 Ports + +| Port | Protocol | Direction | Purpose | +|------|----------|-----------|---------| +| 8880 | TCP | Inbound | Client HTTP | +| 8881 | TCP | Inbound | Client HTTPS | +| 8888 | TCP | Internal | Proxy service | +| 18080 | UDP | Inbound | VPN service | +| 48782 | TCP | Outbound | Daemon P2P | +| 48772 | TCP | Outbound | Daemon RPC | + +### 8.3 Firewall Rules + +```bash +# Allow client connections +iptables -A INPUT -p tcp --dport 8880 -j ACCEPT +iptables -A INPUT -p tcp --dport 8881 -j ACCEPT +iptables -A INPUT -p udp --dport 18080 -j ACCEPT + +# Allow blockchain P2P +iptables -A OUTPUT -p tcp --dport 48782 -j ACCEPT +``` + +--- + +## 9. Operational Procedures + +### 9.1 Initial Setup + +```bash +# 1. Install Docker +curl -fsSL https://get.docker.com | sh + +# 2. Create directories +mkdir -p /opt/lthn/etc/ca/{certs,private} + +# 3. Generate provider identity +lvmgmt --generate-provider-id + +# 4. Generate SDP configuration +lvmgmt --generate-sdp --wallet-address + +# 5. Start node +docker-compose up -d +``` + +### 9.2 Updating + +```bash +# Pull latest image +docker pull letheanvpn/lvpn:latest + +# Restart with new image +docker-compose down +docker-compose up -d +``` + +### 9.3 Backup + +Critical files to backup: +- `/opt/lthn/etc/dispatcher.ini` +- `/opt/lthn/etc/ca/` (certificates) +- `/opt/lthn/etc/sdp.json` +- Wallet files + +--- + +## 10. References + +- RFC-0001: Lethean Network Overview +- RFC-0002: Service Descriptor Protocol (SDP) +- RFC-0004: Payment & Dispatcher Protocol +- OpenVPN Documentation: https://openvpn.net/ +- HAProxy Documentation: https://www.haproxy.org/ + +--- + +## Appendix A: Docker Compose Example + +```yaml +version: '3.8' + +services: + lethean-node: + image: letheanvpn/lvpn:latest + container_name: lethean-exit-node + restart: unless-stopped + ports: + - "8880:8880" + - "8881:8881" + - "18080:18080/udp" + volumes: + - ./config:/opt/lthn/etc + - ./data:/opt/lthn/data + environment: + - LETHEAN_MODE=node + - WALLET_ADDRESS=${WALLET_ADDRESS} + cap_add: + - NET_ADMIN + sysctls: + - net.ipv4.ip_forward=1 +``` + +--- + +## Appendix B: Component Ports Reference + +``` +┌────────────────────────────────────────────────────────────────┐ +│ EXIT NODE │ +│ │ +│ EXTERNAL INTERNAL │ +│ ──────── ──────── │ +│ 8880 ──────► HAProxy │ +│ 8881 ──────► │ │ +│ ├────────► 8888 (tinyproxy) │ +│ ├────────► 3128 (squid, optional) │ +│ └────────► 8124 (lvpnc-client-man) │ +│ │ +│ 18080/UDP ──────────────► OpenVPN │ +│ │ +│ letheand ──────► 48782, 48772 │ +│ wallet ────────► 1444, 1445 │ +│ wallet-rpc ────► 14660 │ +│ │ +└────────────────────────────────────────────────────────────────┘ +``` diff --git a/docs/specs/RFC-0004-payment-dispatcher-protocol.md b/docs/specs/RFC-0004-payment-dispatcher-protocol.md new file mode 100644 index 0000000..d485898 --- /dev/null +++ b/docs/specs/RFC-0004-payment-dispatcher-protocol.md @@ -0,0 +1,451 @@ +# RFC-0004: Payment & Dispatcher Protocol + +``` +RFC: 0004 +Title: Payment & Dispatcher Protocol +Status: Standard +Category: Standards Track +Authors: Darbs, Snider +License: EUPL-1.2 +Created: 2026-02-01 +Requires: RFC-0001, RFC-0003 +``` + +--- + +## Abstract + +This document specifies the payment flow between clients and Exit Node providers, including the Dispatcher component that validates payments and authorizes service access. It also describes the Daemon Reward Program that incentivizes blockchain node operators. + +--- + +## 1. Introduction + +### 1.1 Purpose + +The Lethean payment model enables direct peer-to-peer transactions between users and service providers without intermediaries. The Dispatcher component on each Exit Node validates these payments and grants service access. + +### 1.2 Design Goals + +1. **Direct Payment** - No payment processor or intermediary +2. **Privacy** - Untraceable transactions on blockchain +3. **Automation** - No manual verification required +4. **Fairness** - Providers paid for actual service delivery + +--- + +## 2. Payment Model + +### 2.1 Overview + +``` +┌──────────┐ ┌─────────────┐ ┌─────────────┐ +│ Client │ LTHN │ Blockchain │ Verify │ Exit Node │ +│ │────────>│ │────────>│ (Dispatcher)│ +└──────────┘ └─────────────┘ └─────────────┘ + │ │ + │ Service Access │ + │<─────────────────────────────────────────────│ +``` + +### 2.2 Payment Flow + +1. **Discovery**: Client queries SDP for available providers +2. **Selection**: User selects provider based on price, location, etc. +3. **Payment**: Client sends LTHN to provider's wallet address +4. **Confirmation**: Transaction confirmed on blockchain +5. **Validation**: Dispatcher detects payment, authorizes client +6. **Connection**: Client connects and uses service + +### 2.3 Payment Parameters + +| Parameter | Description | +|-----------|-------------| +| cost | LTHN amount per service unit (defined by provider) | +| firstVerificationsRequired | Confirmations needed for first payment (0-2) | +| subsequentVerificationsRequired | Confirmations for later payments (0-1) | + +--- + +## 3. Dispatcher Protocol + +### 3.1 Component Architecture + +``` + ┌─────────────────────────────────┐ + │ DISPATCHER │ + │ (lthnvpnd) │ + │ │ + Client ──────────>│ ┌─────────────────────────┐ │ + Connection │ │ Payment Validator │ │ + │ │ (wallet RPC queries) │ │ + │ └───────────┬─────────────┘ │ + │ │ │ + │ ┌───────────▼─────────────┐ │ + │ │ Session Manager │ │ + │ │ (active connections) │ │ + │ └───────────┬─────────────┘ │ + │ │ │ + │ ┌───────────▼─────────────┐ │ + │ │ Service Router │ │──────> Services + │ │ (proxy/vpn dispatch) │ │ + │ └─────────────────────────┘ │ + └─────────────────────────────────┘ +``` + +### 3.2 Wallet RPC Interface + +The Dispatcher communicates with the local wallet via JSON-RPC: + +**Endpoint**: `http://127.0.0.1:14660/json_rpc` + +**Key Methods**: + +```json +// Check incoming transfers +{ + "jsonrpc": "2.0", + "method": "get_transfers", + "params": {"in": true, "pending": true}, + "id": "1" +} + +// Verify specific payment +{ + "jsonrpc": "2.0", + "method": "get_transfer_by_txid", + "params": {"txid": ""}, + "id": "2" +} +``` + +### 3.3 Payment Validation Logic + +```python +def validate_payment(client_info): + # Query wallet for incoming transfers + transfers = wallet_rpc.get_transfers(in=True) + + for transfer in transfers: + # Check if payment matches expected amount + if transfer.amount >= service.cost: + # Check confirmation count + if transfer.confirmations >= service.firstVerificationsRequired: + # Check if not already used + if not is_payment_used(transfer.txid): + mark_payment_used(transfer.txid) + return authorize_client(client_info, transfer) + + return reject_client(client_info, "Payment not found") +``` + +### 3.4 Session Management + +| Session State | Description | +|---------------|-------------| +| PENDING | Awaiting payment confirmation | +| ACTIVE | Payment validated, service access granted | +| EXPIRED | Session time/data limit exceeded | +| TERMINATED | Manually ended or error | + +--- + +## 4. Transaction Format + +### 4.1 Payment Transaction + +LTHN uses CryptoNote-based transactions: + +| Field | Description | +|-------|-------------| +| inputs | Ring signature inputs (privacy) | +| outputs | Destination addresses (stealth) | +| amount | Payment amount (encrypted) | +| payment_id | Optional identifier (deprecated in favor of subaddresses) | + +### 4.2 Confirmation Levels + +| Confirmations | Security | Wait Time | +|---------------|----------|-----------| +| 0 | Low (double-spend risk) | Immediate | +| 1 | Medium | ~2 minutes | +| 2 | High | ~4 minutes | + +### 4.3 Recommended Settings + +| Use Case | First Confirmations | Subsequent | +|----------|---------------------|------------| +| Low-value, trusted | 0 | 0 | +| Standard | 1 | 1 | +| High-value | 2 | 1 | + +--- + +## 5. Pricing Model + +### 5.1 Cost Specification + +Providers define costs in their SDP configuration: + +```json +{ + "services": [{ + "id": "1A", + "cost": "0.1", + "unit": "session", + "duration": 3600 + }] +} +``` + +### 5.2 Pricing Strategies + +| Model | Description | +|-------|-------------| +| Per-session | Fixed cost per connection | +| Per-time | Cost per hour/day | +| Per-data | Cost per GB transferred | +| Subscription | Pre-paid time blocks | + +### 5.3 Dynamic Pricing (Future) + +Smart contracts may enable: +- Demand-based pricing +- Bulk discounts +- Loyalty rewards + +--- + +## 6. Daemon Reward Program + +### 6.1 Purpose + +The Daemon Reward Program incentivizes running blockchain nodes (letheand) to ensure network decentralization and stability. + +### 6.2 Eligibility Flow + +``` +┌─────────────────┐ +│ Daemon │ +│ Commissioned │ +└────────┬────────┘ + │ + ▼ +┌─────────────────┐ No ┌─────────────────┐ +│ Zabbix Agent │───────────>│ Ineligible │ +│ Running? │ │ for Reward │ +└────────┬────────┘ └─────────────────┘ + │ Yes + ▼ +┌─────────────────┐ No +│ Daemon │───────────> (Re-poll) +│ Synchronized? │ +└────────┬────────┘ + │ Yes + ▼ +┌─────────────────┐ No +│ Port │───────────> (Re-poll) +│ Accessible? │ +└────────┬────────┘ + │ Yes + ▼ +┌─────────────────┐ +│ Mark as LIVE │ +│ Start SLA Clock │ +└─────────────────┘ +``` + +### 6.3 SLA Calculation + +**Formula**: +``` +if daemon_sla >= sla_threshold: + reward = escrow / number_of_eligible_daemons +else: + reward = 0 +``` + +**Parameters**: + +| Parameter | Value | Description | +|-----------|-------|-------------| +| sla_threshold | 98% | Minimum uptime requirement | +| escrow | $250 USD/month | Monthly reward pool | +| cycle_length | 30 days | Evaluation period | +| max_daemons | 50 | Cutoff for reward distribution | + +### 6.4 SLA Thresholds + +| SLA Level | Allowed Downtime (Monthly) | +|-----------|---------------------------| +| 98% | 14h 36m 34s | +| 99% | 7h 18m 17s | + +**Recommendation**: 98% is realistic for independent operators who may not notice overnight outages but can restore service the next day. + +### 6.5 Reward Distribution + +``` +┌─────────────────┐ +│ 30 Days Elapsed │ +└────────┬────────┘ + │ + ▼ +┌─────────────────┐ No ┌─────────────────┐ +│ SLA >= 98%? │───────────>│ No Reward │ +└────────┬────────┘ │ Notify Operator │ + │ Yes │ Reset Clock │ + ▼ └─────────────────┘ +┌─────────────────┐ +│ Calculate: │ +│ reward = escrow │ +│ / daemons │ +└────────┬────────┘ + │ + ▼ +┌─────────────────┐ +│ Auto-payment │ +│ from Escrow │ +│ to Operator │ +└─────────────────┘ +``` + +### 6.6 Anti-Gaming Measures + +To prevent abuse: + +1. **Wallet Analysis** - Compare addresses across daemons +2. **WHOIS Comparison** - Detect same provider/location +3. **Geographic Distribution** - Encourage spread across regions +4. **Hotspot Prevention** - Auto-exclude clustered daemons + +--- + +## 7. Security Considerations + +### 7.1 Double-Spend Protection + +- Require confirmations before service access +- Monitor mempool for conflicting transactions +- Rate-limit rapid reconnection attempts + +### 7.2 Replay Protection + +- Track used payment transaction IDs +- Reject previously-used payments +- Session binding to payment hash + +### 7.3 Payment Privacy + +- Ring signatures hide sender +- Stealth addresses hide receiver +- Amount encryption + +--- + +## 8. Implementation Notes + +### 8.1 Wallet RPC Configuration + +```ini +; dispatcher.ini +wallet-rpc-uri=http://127.0.0.1:14660/json_rpc +wallet-username=dispatcher +wallet-password= +``` + +### 8.2 Starting Wallet RPC + +```bash +lethean-wallet-vpn-rpc \ + --wallet-file /opt/lthn/wallet \ + --rpc-bind-port 14660 \ + --rpc-login dispatcher: \ + --daemon-address 127.0.0.1:48782 +``` + +### 8.3 Monitoring Payments + +```python +# Example: Watch for incoming payments +import requests + +def check_payments(): + response = requests.post( + "http://127.0.0.1:14660/json_rpc", + json={ + "jsonrpc": "2.0", + "method": "get_transfers", + "params": {"in": True, "pending": True}, + "id": "1" + }, + auth=("dispatcher", password) + ) + return response.json()["result"]["in"] +``` + +--- + +## 9. References + +- RFC-0001: Lethean Network Overview +- RFC-0003: Exit Node Architecture +- CryptoNote Protocol: https://cryptonote.org/ +- Lethean Daemon Reward Workflow Documentation + +--- + +## Appendix A: Reward Calculation Example + +``` +Given: + - escrow = $250 USD + - eligible_daemons = 25 + - daemon_sla = 99.2% + - threshold = 98% + +Calculation: + daemon_sla (99.2%) >= threshold (98%) ✓ + + reward = escrow / eligible_daemons + reward = $250 / 25 + reward = $10 USD per daemon + +Result: + Operator receives $10 USD equivalent in LTHN +``` + +--- + +## Appendix B: Payment State Machine + +``` + ┌──────────────┐ + │ INITIAL │ + └──────┬───────┘ + │ Client connects + ▼ + ┌──────────────┐ + │ PENDING │◄─────────────┐ + └──────┬───────┘ │ + │ │ + ┌──────────────┼──────────────┐ │ + │ │ │ │ + ▼ ▼ ▼ │ + ┌───────────┐ ┌───────────┐ ┌───────────┐ │ + │ PAYMENT │ │ TIMEOUT │ │ REJECTED │ │ + │ FOUND │ │ │ │ │ │ + └─────┬─────┘ └───────────┘ └───────────┘ │ + │ │ + │ Confirmations met │ + ▼ │ + ┌───────────┐ │ + │ ACTIVE │───────────────────────────────┘ + │ (session) │ Session expired/renewed + └─────┬─────┘ + │ Disconnect/Limit reached + ▼ + ┌───────────┐ + │TERMINATED │ + └───────────┘ +``` diff --git a/docs/specs/RFC-0005-client-protocol.md b/docs/specs/RFC-0005-client-protocol.md new file mode 100644 index 0000000..2a666dc --- /dev/null +++ b/docs/specs/RFC-0005-client-protocol.md @@ -0,0 +1,591 @@ +# RFC-0005: Client Protocol + +``` +RFC: 0005 +Title: Client Protocol +Status: Standard +Category: Standards Track +Authors: Darbs, Snider +License: EUPL-1.2 +Created: 2026-02-01 +Requires: RFC-0001, RFC-0002, RFC-0004 +``` + +--- + +## Abstract + +This document specifies the Lethean VPN Client (lvpnc) protocol, including service discovery, connection establishment, payment submission, and session management. It covers both GUI and CLI interfaces as well as transport layer options. + +--- + +## 1. Introduction + +### 1.1 Purpose + +The Lethean Client enables users to discover, connect to, and pay for privacy services provided by Exit Nodes. This specification defines the client-side protocols and components required for seamless integration with the Lethean network. + +### 1.2 Design Principles + +1. **User Sovereignty** - User controls their wallet and connection choices +2. **Privacy First** - No tracking, minimal metadata exposure +3. **Cross-Platform** - Support for Windows, Linux, macOS +4. **Flexibility** - GUI and CLI interfaces for different user preferences + +--- + +## 2. Client Architecture + +### 2.1 Component Overview + +``` +┌────────────────────────────────────────────────────────────────┐ +│ LETHEAN CLIENT (lvpnc) │ +│ │ +│ ┌───────────────────────────────────────────────────────────┐ │ +│ │ GUI │ │ +│ │ (Kivy-based) │ │ +│ └─────────────────────────┬─────────────────────────────────┘ │ +│ │ │ +│ ┌─────────────────────────┴─────────────────────────────────┐ │ +│ │ Core Services │ │ +│ │ │ │ +│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ +│ │ │ Provider │ │ Session │ │ Payment │ │ │ +│ │ │ Manager │ │ Manager │ │ Manager │ │ │ +│ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │ +│ └─────────┼────────────────┼────────────────┼───────────────┘ │ +│ │ │ │ │ +│ ┌─────────┴────────────────┴────────────────┴───────────────┐ │ +│ │ Transport Layer │ │ +│ │ │ │ +│ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │ +│ │ │ SSH │ │ WireGuard │ │ HTTP │ │ │ +│ │ │ Tunnel │ │ Tunnel │ │ Proxy │ │ │ +│ │ └───────────┘ └───────────┘ └───────────┘ │ │ +│ └───────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌───────────────────────────────────────────────────────────┐ │ +│ │ Blockchain Services │ │ +│ │ │ │ +│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ +│ │ │ Wallet │ │ Daemon │ │ Daemon │ │ │ +│ │ │ RPC │ │ RPC │ │ (local) │ │ │ +│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ +│ └───────────────────────────────────────────────────────────┘ │ +└────────────────────────────────────────────────────────────────┘ +``` + +### 2.2 Core Components + +| Component | Description | +|-----------|-------------| +| **GUI** | Kivy-based graphical interface | +| **Provider Manager** | Handles SDP queries and VDP caching | +| **Session Manager** | Manages active connections | +| **Payment Manager** | Wallet integration and transaction submission | +| **Transport Layer** | SSH, WireGuard, or HTTP proxy tunnels | +| **Wallet RPC** | Local wallet for payment processing | +| **Daemon RPC** | Connection to blockchain node | + +--- + +## 3. Service Discovery + +### 3.1 Discovery Flow + +``` +┌──────────┐ ┌──────────────┐ ┌──────────┐ +│ Client │ Query │ SDP Server │ Cached │ VDP │ +│ │─────────>│ │─────────>│ Store │ +└──────────┘ └──────────────┘ └──────────┘ + │ │ + │ Provider List │ + │<──────────────────────│ + │ │ + ▼ │ +┌──────────┐ │ +│ User │ │ +│Selection │ │ +└──────────┘ │ +``` + +### 3.2 SDP Query + +```python +# Query available providers +GET https://sdp.lethean.io/v1/services/search + +# Optional filters +?type=proxy # Service type (proxy, vpn) +?country=AU # Country code (ISO 3166-1) +?max_cost=0.5 # Maximum cost in LTHN +?min_speed=10mbps # Minimum speed +``` + +### 3.3 Provider Selection Criteria + +| Criterion | Description | +|-----------|-------------| +| **Location** | Geographic proximity for latency | +| **Cost** | LTHN price per session/hour/GB | +| **Speed** | Advertised bandwidth | +| **Type** | Service type (proxy, VPN) | +| **Reputation** | Future: on-chain reputation | + +### 3.4 VDP Caching + +``` +Directory Structure: +├── providers/ # All known provider VDPs +├── my-providers/ # Providers we've connected to +├── spaces/ # Lethernet space definitions +├── gates/ # Gateway definitions +└── sessions/ # Active session data +``` + +--- + +## 4. Connection Protocol + +### 4.1 Connection Flow + +``` +┌────────────┐ ┌────────────┐ +│ Client │ │ Exit Node │ +└─────┬──────┘ └─────┬──────┘ + │ │ + │ 1. Query SDP for providers │ + │────────────────────────────────────────────────>│ + │ │ + │ 2. Select provider, parse VDP │ + │<────────────────────────────────────────────────│ + │ │ + │ 3. Send payment to provider wallet │ + │────────────────(Blockchain)────────────────────>│ + │ │ + │ 4. Wait for confirmation (0-2 blocks) │ + │ │ + │ 5. Connect via transport (SSH/WG/HTTP) │ + │────────────────────────────────────────────────>│ + │ │ + │ 6. Dispatcher validates payment │ + │ │ + │ 7. Session established │ + │<────────────────────────────────────────────────│ + │ │ + │ 8. Route traffic through tunnel │ + │◄───────────────────────────────────────────────►│ +``` + +### 4.2 Transport Options + +| Transport | Port | Protocol | Use Case | +|-----------|------|----------|----------| +| **SSH Tunnel** | 8880 | TCP | Default, firewall-friendly | +| **WireGuard** | 8774 | UDP | High performance VPN | +| **HTTP Proxy** | 8080 | TCP | Browser-only proxy | +| **HTTPS/TLS** | 8881 | TCP | Manager-over-TLS | + +### 4.3 Exit Node Connection + +``` +Client connects to Exit Node: + +HTTP/8880 ──► haproxy ──► Authenticated proxy access +HTTPS/8881 ──► haproxy ──► Manager-over-TLS channel +UDP/8774 ──► WireGuard ──► VPN tunnel +``` + +--- + +## 5. Payment Integration + +### 5.1 Payment Flow + +``` +┌──────────────┐ ┌──────────────┐ ┌──────────────┐ +│ Client │ │ Blockchain │ │ Provider │ +│ Wallet │ │ Network │ │ Wallet │ +└──────┬───────┘ └──────┬───────┘ └──────┬───────┘ + │ │ │ + │ 1. Create TX │ │ + │─────────────────────► │ │ + │ │ │ + │ 2. Broadcast │ │ + │ │─────────────────────► │ + │ │ │ + │ 3. Confirm (0-2 blocks) │ + │ │ │ + │ 4. Connect with TX proof │ + │───────────────────────────────────────────────►│ + │ │ │ + │ 5. Dispatcher validates │ + │ │ ◄──────────────────── │ + │ │ │ + │ 6. Session granted │ + │◄───────────────────────────────────────────────│ +``` + +### 5.2 Payment Parameters + +| Parameter | Description | +|-----------|-------------| +| `--default-pay-days` | Days to pay for by default | +| `--auto-pay-days` | Auto-pay without GUI confirmation | +| `--free-session-days` | Days to request for free services | +| `--unpaid-expiry` | Seconds before unpaid session expires | +| `--use-tx-pool` | Accept unconfirmed payments | + +### 5.3 Wallet Configuration + +```ini +# client.ini wallet settings +wallet-rpc-url=http://127.0.0.1:14660/json_rpc +wallet-rpc-port=14660 +wallet-rpc-user=client +wallet-rpc-password= +wallet-name=default +wallet-address= +``` + +--- + +## 6. Session Management + +### 6.1 Session States + +| State | Description | +|-------|-------------| +| **UNPAID** | Session created, awaiting payment | +| **PENDING** | Payment sent, awaiting confirmation | +| **ACTIVE** | Payment confirmed, connection established | +| **EXPIRED** | Time/data limit reached | +| **DISCONNECTED** | User-initiated disconnect | + +### 6.2 Session Lifecycle + +``` + ┌───────────┐ + │ SELECT │ + │ PROVIDER │ + └─────┬─────┘ + │ + ▼ + ┌───────────┐ + │ UNPAID │ + └─────┬─────┘ + │ Send payment + ▼ + ┌───────────┐ + │ PENDING │◄─────────────────┐ + └─────┬─────┘ │ + │ Confirmed │ Renew + ▼ │ + ┌───────────┐ │ + │ ACTIVE │──────────────────┘ + └─────┬─────┘ + │ Expire/Disconnect + ▼ + ┌───────────┴───────────┐ + ▼ ▼ + ┌───────────┐ ┌───────────┐ + │ EXPIRED │ │DISCONNECTED│ + └───────────┘ └───────────┘ +``` + +### 6.3 Auto-Reconnect + +```ini +# Reconnection settings +auto-reconnect=30 # Seconds between reconnect attempts +auto-connect=lthn://provider-id/service-id +``` + +--- + +## 7. Command Line Interface + +### 7.1 Installation + +**Windows (PowerShell):** +```powershell +irm https://raw.githubusercontent.com/letheanVPN/lvpn/main/install-all-in-one.ps1 | iex +``` + +**Linux/macOS:** +```bash +curl -sSL https://lethean.io/install.sh | bash +``` + +### 7.2 Basic Usage + +```bash +# Run with GUI +python client.py --run-gui=1 + +# Run headless (CLI only) +python client.py --run-gui=0 + +# Auto-connect to specific provider +python client.py --auto-connect=lthn://provider-id/1A +``` + +### 7.3 Key Command Options + +| Option | Description | +|--------|-------------| +| `--run-gui={0,1}` | Enable/disable GUI | +| `--run-proxy={0,1}` | Run local proxy server | +| `--run-wallet={0,1}` | Run embedded wallet | +| `--run-daemon={0,1}` | Run embedded daemon | +| `--log-level={DEBUG,INFO,WARNING,ERROR}` | Logging verbosity | +| `--config=` | Config file location | + +### 7.4 Directory Options + +| Option | Description | +|--------|-------------| +| `--var-dir` | Variable data directory | +| `--cfg-dir` | Configuration directory | +| `--app-dir` | Application directory | +| `--tmp-dir` | Temporary files | +| `--providers-dir` | Provider VDP cache | +| `--sessions-dir` | Session data storage | + +--- + +## 8. WireGuard Integration + +### 8.1 WireGuard Configuration + +```ini +# WireGuard-specific settings +enable-wg=1 +wg-map-device=gate1,wg0 +wg-map-privkey=gate1, +wg-cmd-prefix=sudo +wg-shutdown-on-disconnect=1 +``` + +### 8.2 WireGuard Commands + +| Option | Description | +|--------|-------------| +| `--wg-cmd-create-interface` | Command to create WG interface | +| `--wg-cmd-delete-interface` | Command to delete WG interface | +| `--wg-cmd-set-ip` | Command to assign IP to interface | +| `--wg-cmd-set-interface-up` | Command to bring interface up | +| `--wg-cmd-route` | Command to add routes | + +### 8.3 WireGuard Connection Flow + +``` +Client Exit Node + │ │ + │ 1. Generate WG keypair │ + │ │ + │ 2. Request WG config from provider │ + │──────────────────────────────────────>│ + │ │ + │ 3. Receive peer config │ + │<──────────────────────────────────────│ + │ │ + │ 4. Create WG interface │ + │ 5. Configure peer │ + │ 6. Establish tunnel │ + │══════════════════════════════════════>│ + │ │ + │ 7. Route traffic through WG │ + │◄═════════════════════════════════════►│ +``` + +--- + +## 9. GUI Interface + +### 9.1 Main Views + +| View | Purpose | +|------|---------| +| **Provider List** | Browse and select Exit Nodes | +| **Connection** | Active connection status | +| **Wallet** | Balance and transaction history | +| **Settings** | Configuration options | + +### 9.2 Connection Workflow + +1. **Browse** - View available providers from SDP +2. **Select** - Choose provider based on criteria +3. **Pay** - Send LTHN to provider wallet +4. **Connect** - Establish tunnel after payment confirms +5. **Use** - Traffic routes through Exit Node + +--- + +## 10. Security Considerations + +### 10.1 Transport Security + +- SSH tunnels use provider's CA for authentication +- WireGuard provides modern cryptographic security +- TLS 1.3 for HTTPS connections + +### 10.2 Payment Security + +- Wallet RPC uses authentication +- Transactions are cryptographically signed +- Ring signatures provide sender privacy + +### 10.3 Session Security + +- Session binding to payment transaction +- No session sharing across clients +- Automatic session cleanup on disconnect + +--- + +## 11. Configuration File + +### 11.1 Default Locations + +| Platform | Path | +|----------|------| +| Windows | `%USERPROFILE%\lvpn\client.ini` | +| Linux | `/etc/lvpn/client.ini` or `~/.config/lvpn/client.ini` | +| macOS | `~/Library/Application Support/lvpn/client.ini` | + +### 11.2 Example Configuration + +```ini +[client] +log-level=INFO +run-gui=1 +run-proxy=1 +run-wallet=1 + +[wallet] +wallet-rpc-url=http://127.0.0.1:14660/json_rpc +wallet-name=default + +[connection] +auto-reconnect=30 +default-pay-days=1 + +[wireguard] +enable-wg=0 +wg-shutdown-on-disconnect=1 +``` + +--- + +## 12. Lethernet Access + +### 12.1 Beyond Standard VPN + +Connected clients gain access to Lethernet services: + +| Service Type | Description | +|--------------|-------------| +| **Web Servers** | Privately hosted web content | +| **File Sharing** | Distributed storage solutions | +| **Name Services** | `.lthn` domain namespace | +| **Social Networks** | Decentralized communication | +| **Custom BYOA** | Bring Your Own Application | + +### 12.2 Service Access + +``` +Client ──► Exit Node ──► Internet (standard VPN) + └──► Lethernet Services (private network) +``` + +--- + +## 13. References + +- RFC-0001: Lethean Network Overview +- RFC-0002: Service Descriptor Protocol (SDP) +- RFC-0003: Exit Node Architecture +- RFC-0004: Payment & Dispatcher Protocol +- WireGuard Protocol: https://www.wireguard.com/protocol/ + +--- + +## Appendix A: Full Command Options + +``` +usage: client.py [-h] [-c CONFIG] [-l {DEBUG,INFO,WARNING,ERROR}] + [--log-file LOG_FILE] [--audit-file AUDIT_FILE] + [--http-port HTTP_PORT] [--var-dir VAR_DIR] + [--cfg-dir CFG_DIR] [--app-dir APP_DIR] + [--tmp-dir TMP_DIR] [--daemon-host DAEMON_HOST] + [--daemon-bin DAEMON_BIN] [--daemon-rpc-url DAEMON_RPC_URL] + [--daemon-p2p-port DAEMON_P2P_PORT] + [--wallet-rpc-bin WALLET_RPC_BIN] + [--wallet-cli-bin WALLET_CLI_BIN] + [--wallet-rpc-url WALLET_RPC_URL] + [--wallet-rpc-port WALLET_RPC_PORT] + [--wallet-rpc-user WALLET_RPC_USER] + [--wallet-rpc-password WALLET_RPC_PASSWORD] + [--wallet-address WALLET_ADDRESS] + [--spaces-dir SPACES_DIR] [--gates-dir GATES_DIR] + [--providers-dir PROVIDERS_DIR] + [--sessions-dir SESSIONS_DIR] + [--coin-type {lethean}] [--coin-unit COIN_UNIT] + [--lthn-price LTHN_PRICE] + [--default-pay-days DEFAULT_PAY_DAYS] + [--unpaid-expiry UNPAID_EXPIRY] + [--use-tx-pool USE_TX_POOL] + [--enable-wg {0,1}] + [--run-gui {0,1}] [--run-proxy {0,1}] + [--run-wallet {0,1}] [--run-daemon {0,1}] + [--auto-connect AUTO_CONNECT] + [--auto-reconnect AUTO_RECONNECT] + [--auto-pay-days AUTO_PAY_DAYS] + [--free-session-days FREE_SESSION_DAYS] +``` + +--- + +## Appendix B: Connection State Machine + +``` + ┌─────────────────────┐ + │ IDLE │ + └──────────┬──────────┘ + │ User selects provider + ▼ + ┌─────────────────────┐ + │ DISCOVERING │ + │ (fetch VDP) │ + └──────────┬──────────┘ + │ VDP received + ▼ + ┌─────────────────────┐ + │ UNPAID │◄────────────┐ + └──────────┬──────────┘ │ + │ Payment sent │ + ▼ │ + ┌─────────────────────┐ │ + │ CONFIRMING │ │ + │ (await blocks) │ │ + └──────────┬──────────┘ │ + │ Confirmed │ + ▼ │ + ┌─────────────────────┐ │ + │ CONNECTING │ │ + │ (transport setup) │ │ + └──────────┬──────────┘ │ + │ Connected │ + ▼ │ + ┌─────────────────────┐ │ + │ ACTIVE │─────────────┘ + │ (tunneled) │ Renew + └──────────┬──────────┘ + │ Disconnect/Expire + ▼ + ┌─────────────────────┐ + │ DISCONNECTED │ + └─────────────────────┘ +``` diff --git a/docs/specs/RFC-001-HLCRF-COMPOSITOR.md b/docs/specs/RFC-001-HLCRF-COMPOSITOR.md new file mode 100644 index 0000000..7ff4f82 --- /dev/null +++ b/docs/specs/RFC-001-HLCRF-COMPOSITOR.md @@ -0,0 +1,897 @@ +# RFC: HLCRF Compositor + +**Status:** Implemented +**Created:** 2026-01-15 +**Authors:** Host UK Engineering + +--- + +## Abstract + +The HLCRF Compositor is a hierarchical layout system where each composite contains up to five regions—Header, Left, Content, Right, and Footer. Composites nest infinitely: any region can contain another composite, which can contain another, and so on. + +The core innovation is **inline sub-structure declaration**: a single string like `H[LC]C[HCF]F` declares the entire nested hierarchy. No configuration files, no database schema, no separate definitions—parse the string and you have the complete structure. + +Just as Markdown made document formatting a human-readable string, HLCRF makes layout structure a portable, self-describing data type that can be stored, transmitted, validated, and rendered anywhere. + +Path-based element IDs (`L-H-0`, `C-F-C-2`) encode the full hierarchy, eliminating database lookups to resolve structure. The system supports responsive breakpoints, block-based content, and shortcode integration. + +--- + +## Motivation + +Traditional layout systems require separate templates for each layout variation. A page with a left sidebar needs one template; without it, another. Add responsive behaviour, and the combinations multiply quickly. + +The HLCRF Compositor addresses this through: + +1. **Data-driven layouts** — A single compositor handles all layout permutations via variant strings +2. **Nested composition** — Layouts can contain other layouts, with automatic path tracking for unique identification +3. **Responsive design** — Breakpoint-aware rendering collapses regions appropriately for different devices +4. **Block-based content** — Content populates regions as discrete blocks, enabling conditional display and reordering + +The approach treats layout as data rather than markup, allowing the same content to adapt to different structural requirements without template duplication. + +--- + +## Terminology + +### HLCRF + +**H**ierarchical **L**ayer **C**ompositing **R**ender **F**rame. + +The acronym also serves as a mnemonic for the five possible regions: + +| Letter | Region | Semantic element | Purpose | +|--------|--------|------------------|---------| +| **H** | Header | `
` | Top navigation, branding | +| **L** | Left | `