f680931c8c
readme: document trust circle design readme: tone down trust circle language to match existing style remove forum_enabled toggle: subscribing IS trusting, no intermediate state
92 lines
4.7 KiB
Markdown
92 lines
4.7 KiB
Markdown
# tinyweb-forum
|
|
|
|
A link-sharing forum plugin for [TinyWeb](https://codeberg.org/tinyweb/tinyweb). Threads and posts are stored locally and exchanged with other TinyWeb instances over the Reticulum mesh.
|
|
|
|
## Contents
|
|
|
|
- [About this project](#about-this-project)
|
|
- [Install](#install)
|
|
- [How it works](#how-it-works)
|
|
- [Moderation](#moderation)
|
|
- [Sync](#sync)
|
|
- [Storage](#storage)
|
|
- [Known rough edges](#known-rough-edges)
|
|
- [Security](#security)
|
|
|
|
## About this project
|
|
|
|
Code generated by LLMs. Built by one person.
|
|
|
|
## Install
|
|
|
|
```bash
|
|
pip install tinyweb-forum
|
|
```
|
|
|
|
Enable it on TinyWeb's `/style` page under "Forum".
|
|
|
|
## How it works
|
|
|
|
- Threads and posts are stored in `~/.tinyweb/forum.db` (separate from TinyWeb's search index)
|
|
- Instances auto-discover each other via RNS announces — no manual setup
|
|
- Sync is manual by default: click "sync now" on the forum page. Auto-sync every 5 minutes is optional (toggle on moderation page)
|
|
- At scale, sync uses epidemic gossip: 20 random peers per cycle, converging within ~O(log N) cycles
|
|
- Authors are identified by a short pseudonymous identity hash (no accounts, no sign-up)
|
|
- Auto-discovery can be disabled in the moderation page
|
|
- Threads are auto-pruned after 30 days (configurable, or set to 0 to keep everything)
|
|
- Moderation is local: block authors, mute threads, keyword filters, and gossip block lists with peers (auto-block after 3 peer reports)
|
|
|
|
### Trust circle
|
|
|
|
Content exchange is gated by a trust graph derived from your TinyWeb subscriptions:
|
|
|
|
- Only peers you subscribe to (with forum enabled) are trusted sources of content
|
|
- Content from trusted peers propagates transitively: you see posts from their trusted peers, and theirs, and so on — no hop limit
|
|
- New identities have no trust path until a trusted peer vouches for them or you subscribe
|
|
- Trust is seeded from TinyWeb's subscription page — each subscribed peer's forum content (and their transitive trust network) enters your view automatically.
|
|
|
|
## Moderation
|
|
|
|
All moderation is local — it controls what you see:
|
|
|
|
- **Block author** — hides all content from that identity and cascades: the blocked peer's downstream trust network (peers they vouched for) is also removed from your view. If a downstream peer has an alternate trust path from another source you trust, they survive the cascade.
|
|
- **Auto-block** — when 3+ of your peers have blocked the same identity, it blocks for you too (with cascade)
|
|
- **Mute thread** — hides a thread from the listing
|
|
- **Keyword filters** — hides threads matching keywords
|
|
- **Instance sync** — choose which peers to sync with; unsync at any time
|
|
|
|
## Sync
|
|
|
|
- Instances discover each other via RNS announces — any forum on the mesh finds you
|
|
- Content is exchanged as JSON over RNS links
|
|
- **Manual by default** — click "sync now" on the forum listing or moderation page
|
|
- Auto-sync every 5 minutes can be enabled on the moderation page
|
|
- Auto-discovery can be disabled (manual instance add only)
|
|
- Known peers propagate through gossip — each instance shares its peers during sync
|
|
- Block lists and retractions are gossiped alongside content
|
|
- Only new/updated content is transferred (timestamp-based)
|
|
- When >20 peers, each cycle syncs with a random 20 — content converges epidemically
|
|
|
|
## Storage
|
|
|
|
- Threads older than 30 days are auto-pruned (configurable on moderation page)
|
|
- Set retention to 0 to keep everything indefinitely
|
|
- Database location: `~/.tinyweb/forum.db`
|
|
|
|
## Known rough edges
|
|
|
|
- Authors are pseudonymous — no identities, no accounts
|
|
- No rate limiting on forum POST endpoints
|
|
- Retractions are voluntary — peers can ignore them
|
|
- Block gossip can be gamed (requires collusion by 3+ peers on Reticulum)
|
|
- Threads prune after 30 days by default
|
|
- Discovery is through the subscription graph rather than topic-based blooms
|
|
- Best-effort maintenance
|
|
|
|
## Security
|
|
|
|
- **No authentication** — The forum inherits TinyWeb's access model. Anyone who can reach the HTTP port (localhost by default) can post, edit, retract, block, and change moderation settings. See TinyWeb's Security section for `--bind 0.0.0.0`.
|
|
- **Retractions are voluntary** — Retracting a thread or post sends a signal to peers, but any peer can ignore it. "Retract" is a polite request, not a guaranteed delete.
|
|
- **Block gossip can be gamed** — Auto-block triggers after 3 peer reports. On Reticulum this requires 3+ real instances to collude, which is impractical at mesh scale, but is not cryptographically enforced.
|
|
- **No rate limiting** — Forum POST endpoints have no throttling. Low risk since the HTTP port is localhost-only by default.
|
|
- **Trust circle** — Blocking a peer removes their downstream trust network from your view. A peer with multiple independent trust paths may survive a single block.
|