tinyweb-forum/README.md

tinyweb-forum

A decentralized link-sharing forum for TinyWeb. Share URLs and discuss them with other TinyWeb instances over the Reticulum mesh. No accounts, no sign-up, no central server.

Install

pip install tinyweb-forum

Enable the forum in TinyWeb's customize page (/style).

Development

git clone https://git.derickphan.com/lichenblankie/tinyweb-forum
pip install -e .

How it works

• Each TinyWeb instance stores forum threads and posts in its own forum.db
• Instances auto-discover each other on the mesh via RNS announces — no manual setup
• You click "sync now" to exchange content; auto-sync every 5 minutes is optional (toggle on moderation page)
• At scale, sync uses epidemic gossip: each cycle picks 20 random peers instead of all peers, converging within ~O(log N) cycles
• Authors are identified by a short pseudonymous hash (no names, no accounts)
• No global server, no algorithms, no tracking

Features

• Threads — share a URL or start a discussion with text
• Replies — reply to threads, with inline URL extraction and "+ save" links
• Upvotes — toggle upvote/downvote, scores propagate via sync
• Edit — edit your own threads (new version syncs to peers)
• Retract — retract your own threads and posts (retraction signal gossips to peers)
• Peer discovery — instances share known peers during sync, growing the network organically

Moderation

All moderation is local — you control your view:

• Block author — [block] link on posts and thread meta hides all content from that identity across your instance
• Auto-block — when 3+ of your peers have blocked the same identity, it's auto-blocked for you too (threshold is 3)
• Mute thread — hide a thread from the listing
• Keyword filters — hide threads matching keywords
• Instance sync — choose which peers to sync with; unsync at any time

Sync

• Instances auto-discover each other via RNS announces — just run the forum and any other 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 also be disabled on the moderation page (manual instance add only)
• Peer discovery propagates through gossip — each instance shares its known 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 the moderation page)
• Set retention to 0 to keep everything indefinitely
• Forum DB is stored at ~/.tinyweb/forum.db

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 details on --bind 0.0.0.0.
• Retractions are voluntary — Retracting a thread or post sends a signal to peers, but any peer can ignore it and keep serving the content. "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.