I kept hitting the same wall looking for an offline wiki. Kiwix is great, but it's an app plus multi-GB ZIM files. IPFS needs connectivity and setup. I just wanted something dead simple: a knowledge file you can open on any phone with no install, and hand to the next person over Bluetooth or a USB stick.
So I built Portable Knowledge Mesh. It's one reader.html (~19 KB). You open it — even straight from file:// — load a .mesh pack, and read/search offline. To share it, you just send the file; the other person opens it in any browser. The whole thing — reader plus a 21-article survival pack — is under 50 KB. It fits in a single chat message.
- 🔗 Code: https://github.com/by-sitnikov/portable-knowledge-mesh
- 🌐 Live demo (loads instantly, no backend): https://by-sitnikov.github.io/portable-knowledge-mesh/
🌐 Portable Knowledge Mesh — an offline wiki in a single file
A Wikipedia that spreads via Bluetooth, USB, and AirDrop — no server, no install, no internet required.
🇷🇺 Русский · 🇪🇸 Español · translations wanted — see #good-first-issue
What is this?
Portable Knowledge Mesh is a single HTML file that turns any phone or laptop into an offline wiki. It opens in a browser — even straight from a USB stick, an email attachment, or a Bluetooth share — and lets you read, search, and pass on curated knowledge without ever touching a server.
- 🚀 Zero install — double-click
reader.html, it works. No app store, no setup. - 📴 Fully offline — no internet, no backend, no API keys, no account.
- 🔒 Tamper-proof — every knowledge pack is cryptographically signed (ECDSA P-256, WebCrypto). Forgeries are rejected automatically.
- 🦠 Viral by design — send a
.meshfile over…
Here are the parts that turned out interesting to build.
A single file that runs from file://
The constraint "must work when double-clicked off a USB stick" kills a lot of the usual toolbox:
-
No Service Worker — they require a secure context;
file://isn't one. -
No IndexedDB — in a
file://(null) origin it's unreliable and non-portable across browsers.
So v0.1 keeps everything in memory + sessionStorage, and a .mesh is just a single JSON document (zero dependencies, trivially parseable). The fancy ZIP + CompressionStream container is a later optimization — for v0.1, plain JSON is what makes it bulletproof on file://.
Tamper-proof packs with WebCrypto (no libraries)
If knowledge spreads device-to-device with no server, "is this pack genuine?" matters. Each pack is signed: every article (block) is hashed with SHA-256, a Merkle root is computed over the sorted block hashes, and the publisher signs that root with ECDSA P-256 via the browser's built-in crypto.subtle. The reader re-derives everything and verifies — change one byte of a signed article and the badge turns red.
// recompute block hashes -> Merkle root -> verify the publisher's signature, all in-browser
async function verifyPack(mesh) {
const m = mesh.manifest;
const per = {};
for (const [id, md] of Object.entries(mesh.content.blocks)) {
per[id] = await sha256Hex(md);
}
const root = await sha256Hex(Object.keys(per).sort().map(id => per[id]).join(''));
if (root !== m.merkle_root) return 'tampered'; // content was modified
const key = await crypto.subtle.importKey(
'jwk', m.publisher.pubkey_jwk,
{ name: 'ECDSA', namedCurve: 'P-256' }, true, ['verify']
);
const ok = await crypto.subtle.verify(
{ name: 'ECDSA', hash: 'SHA-256' },
key, b64ToBytes(m.signature_b64),
new TextEncoder().encode(m.merkle_root)
);
return ok ? 'verified' : 'tampered'; // no private key = can't re-sign a forged root
}
Two attack paths, both covered: edit a block and the recomputed hash won't match the manifest; edit the manifest to match and the signature over the new root fails (you can't re-sign without the private key).
The CRDT trap I had to avoid (for v0.2 editing)
v0.2 will let local communities adapt articles. My first instinct was a CRDT like Yjs or Automerge — until I remembered the quota death spiral: sequence/text CRDTs accumulate tombstones, history grows without bound, and safe garbage collection needs coordination among all nodes. In an offline mesh where devices may not meet for months, there's no server to compact — so the document just bloats until QuotaExceededError.
The fix is choosing a lighter CRDT, not abandoning CRDTs:
- LWW-Map per block instead of a sequence CRDT — only the current value per field is kept, so no tombstone history.
- Lamport clocks, never wall-clock. Offline devices have unreliable, forgeable clocks (dead CMOS battery → 1970; set the date to 2099 and you always "win"). Conflicts resolve by logical time, tie-broken by author key.
- Trusted-snapshot compaction — a trusted editor publishes a signed snapshot that peers who trust them accept as a new baseline, dropping old ops. Compaction with no server.
Sneakernet first
WebRTC is tempting for sync, but without STUN/TURN it only connects inside one LAN — too fragile to be the critical path. So the primary transport is just moving the file: Bluetooth, AirDrop, USB, QR, email. WebRTC LAN-sync is a v0.3 bonus, never a dependency.
Where it is now
- ✅ v0.1 — portable read-only reader (this release)
- 🚧 v0.2 — editable overlay + local web of trust + Lamport sync over file exchange
- 📡 v0.3 — installed PWA mode + WebRTC LAN-sync + trusted-snapshot compaction
It ships with Barefoot Skills — 21 practical offline articles (water, energy, repair, food, shelter), risk-stratified so safety-critical topics are signed and read-only. Code is MIT, content CC BY-SA, all sourced from open corpora (Appropedia, Wikibooks, Practical Action).
I'd love your feedback
- Is the single-file / "sneakernet" approach genuinely useful, or a gimmick?
- What knowledge packs would be worth curating first — first aid, repair, farming, a specific language?
And if you want to poke holes in the crypto or the v0.2 merge design, please do — that's exactly the kind of review I'm hoping for.
Repo: https://github.com/by-sitnikov/portable-knowledge-mesh