| Commit message (Collapse) | Author | Age | Files | Lines |
|---|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Move the remaining root-level .md files (except CLAUDE.md) into docs/:
devel-phases.md, devel-phases-next.md, first-review.md, second-review.md,
tmp-decisions.md. Update all inbound references in CLAUDE.md (now docs/-prefixed)
and strip the now-redundant docs/ prefix from links inside the moved files.
Consolidate the superseded material into docs/old-draft.md: architecture
drafts v1-v4, POC v1, and the Phase 1-12 development log, each under an
ARCHIVED banner with a preamble pointing at the current specs. Delete the
merged originals plus the unreferenced French translations (v1-fr, v2-fr,
poc-v1-fr). Repoint the surviving file-links in first-review.md,
second-review.md and meshbay-draft-v5.md at old-draft.md; prose "draft-v3 §x"
mentions are left as-is since the content now lives in the archive.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01J74kj44q6REczub8XR3DRy
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
A design discussion on 2026-08-17 settled Phase 13 and, in doing so, changed
four things the spec states. v6 restates only those; v5 stays authoritative for
everything it does not touch, per the convention v5 itself used with v4.
What changed:
* The native shell is **Electron**, not pywebview — structural decision 18
reversed. The SPA depends on Chromium-class APIs (WebRTC, WebCrypto
X25519/Ed25519, MSE, Service Workers), so keeping Chromium keeps
transport.js, crypto.js, keyderive.js, downloads.js and sw.js *as the
client*. A system webview meant reimplementing ~2500-3000 lines. The old
"69 % reused" figure was measured against an app.js of ~2600 lines; it is
4586.
* A group's content is **several named roots**, not one directory, because
the planned video and audio libraries will not live in one folder on one
disk.
* **Device linking**: one person may hold several devices on a node,
admitted by a key the node already pinned and bound by a one-time code the
new device generates. Without it a native client is refused where a browser
is not, and an account created natively could never be opened in a browser.
* **Authorship is authenticated, not asserted** — chat senders sign, uploads
have a provable owner, and delete authorization moves from the uploading
key to the account.
And one rule v5 assumed without writing down: **group-related server state
lives on the node.** Verified for multi-root — SwarmSource carries hashes and
endpoints, no paths.
Also here: the Caddy configuration, which was a snippet in the roadmap that
would have broken the SPA (it predates /a/<hash>/ asset versioning and would
have 404ed /sw.js, silently killing streamed downloads on Firefox and Safari);
and downloads.html, which becomes a security page once a release key exists.
Phase 15 was re-read against device linking and is wrong as written: a sender
key must be per **device**, never per person, or two devices sharing a chain
produce key and nonce reuse — C1 again, one level down. senderkeys.py already
fails this silently.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Two things a Files panel needs and did not have.
**Removing a directory** is privileged, where creating one is not: it
acts on a name other members are using, on the operator's disk. It is
refused unless the directory is empty, and that rule is the safety
property — whatever the browser sends, this cannot destroy content. The
check runs twice, once before the challenge and once after the signature
comes back, because a file can land during the round trip. A file also
accepts its uploader's key; a directory has no uploader, so only the
operator's key will do.
**Downloading a folder** produces a zip built in the browser, written
straight to disk as the chunks arrive. An archive of a group folder is
routinely tens of gigabytes, so nothing is held: peak memory is one chunk
plus a small record per file. The node is not involved at all — it serves
the same encrypted chunks as any other download, holds no temporary
files, and cannot be asked to compress anything.
zipstream.js is store-only. Group content is video and images, already
compressed, so deflate would spend CPU on every byte to save nothing, in
the thread that is also decrypting. Sizes and CRCs go in a data
descriptor after each file because a stream cannot seek back to patch a
header, and zip64 kicks in per entry past 4 GiB and for the archive
itself. Because none of that can be checked from the Python side of the
house, test_zipstream.py runs the real module under Node and reads what
it produces with zipfile — CRCs, UTF-8 names, zip64 records and all. The
archives also pass `unzip -t`.
Firefox and Safari have no File System Access API, so there is nowhere to
stream to: the fallback builds the archive in memory and says so, with
the size, before starting rather than after failing.
One mistake worth recording: the first version of deleteDirectory passed
the node's own answer as the value to check the challenge against, which
turns the comparison into a tautology. It checks the path we asked for.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
The connection log took the name from a join on `users`, and deletion
tombstones that row — so every record belonging to a deleted account
reported `deleted-3f9a1c`, which is the one answer that helps nobody. The
log is kept for a legal retention period precisely so it can say who did
what; losing the name at deletion kept the data and lost the point of it.
`ip_logs.username` is written as the account is erased, and stays NULL
while the account is alive, where the join is better because it cannot go
stale. The admin view prefers the stored name when there is one: the join
still answers after deletion, just with the tombstone.
Releasing the username for re-registration and keeping it in the log are
separate things, and the guide now says so.
On the node side, the pre-proof audit line records the username the
session already knew, instead of leaving the column empty.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Account deletion is the headline, in the user guide and in draft-v5 §6.1,
and the important half is what deletion does *not* do. It releases the
username, clears the email and password hash, drops memberships,
notifications, refresh tokens and node registrations, and refuses any
access token still inside its hour. It does not touch a node: files, the
pinned identity and the keypair bundle stay on machines the hub does not
command, which is the same sovereignty §5.5 relies on — so deleting a hub
account is not an erasure request to the operators hosting you. The IP log
survives too, attributable, for its legal retention period. The claims
table in §2 gets a row saying exactly this, adversary by adversary.
Notifications get a section: one entry per conversation rather than per
message, never one for your own message, invitations that clear when you
join, muting that lives on the hub so it works from any browser.
Then the corrections, which is most of the diff. The guide still described
a node HTTP API — `GET /index`, `GET /file/{id}`, an HLS playlist, and a
`player.js` that does not exist — with curl examples inviting the reader
to expose port 19001. That surface was removed in 0.2.0 as findings C1 and
C6, precisely because it served files outside the handshake that decides
what a peer may see. Sections 6, 7 and the API reference now describe MNP
message pairs, and the quickstart says the same in French. Also corrected:
the JWT table advertised a `pk_user` claim that no longer exists (it was
what let the token issuer decide who could delete a file), `/pubkeys` no
longer returns identity keys, and the GEK-distribution endpoints are gone
entirely rather than merely unused.
draft-v5 §5.2 had uploads landing in `.uploads/{user_id}/`; they land in
`uploads/`, chat attachments included. §6.1 now says the hub learns the
author's user_id from chat_notify — a stable identifier, and a metadata
leak worth naming rather than leaving as "by whom".
CLAUDE.md records why the deployed hub broke this week: create_all()
creates missing tables, never missing columns, so a schema change passes
every test (fresh DB per run) and never reaches production.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
One keypair was copied to every node its owner joined, so cracking the bundle on
any single node yielded the identity used on all of them: their content on other
operators' machines, and the ability to sign as them anywhere. That lateral reach
was the part of C4 worth attacking.
Each node now gets its own keypair, generated the first time its owner joins it
and left with that node alone. An operator who cracks what sits on their own disk
holds a key that is a stranger to every other node — and on their own node, one
that unlocks nothing they did not already hold: they serve the content, the index
and every byte of it by design.
Nothing changes for the user. A first contact with a node already needed that
operator's code, and the key is created in the same step; a second browser still
recovers it from the node with the passphrase alone. Two operators can also no
longer tell they host the same person by comparing keys.
BREAKING, and deliberately without a compatibility path — the deployment is wiped
for the next demo:
- users.pk_ed25519 / pk_x25519 dropped (migration a7c31f9e40b2)
- registration no longer sends or stores a key
- PUT /v1/users/me/keys and regenerateKeys() gone; rotation is now
`member unpin` plus a fresh code, decided on the machine that pinned it
- /pubkeys returns an account id and a node's linking key. It was the directory
H3 read, and nothing wraps for it any more
- the pk_user JWT claim is gone
That last one closed a live defect the inventory turned up: the node recorded
pk_user as the uploader's identity and authorized deletion against it, so a hub
issuing a token naming its own key could delete anyone's uploads on any node.
Attribution now uses the key the node itself pinned.
A simplification falls out. Registration generates nothing, so a scripted signup
is a real account: `demo.py bootstrap` takes a wiped hub and node to a working
demo with no browser, which was impossible while keys were born in one.
Also fixes, found by running it on a wiped deployment: the key handed back on a
join now belongs to the group the connection is for, not the group named in the
invitation — an operator pairs node-wide but redeems the code while opening a
group, and expects to read it.
Tests: 343, including the two that state the property — a key pinned by one node
is refused at another, and someone else's code does not admit it. Verified end to
end against a wiped hub and node: bootstrap, pair, invite, join, download,
stream, second browser, revoke.
Design: docs/per-node-identity-v1.md
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
draft-v5 §7 rewritten around the keypair bundle, because that is where the last
open finding actually lives. New §7.1 states the adversary (an operator holding
their own node's disk), what cracking a bundle yields (identity keys, hence
content on *other* nodes and the ability to sign as that user — not the content
they host in the clear by design), and the measured numbers rather than
adjectives: PBKDF2 241 ms vs Argon2id 88 ms natively, a GPU ceiling moving from
~8k to ~2k guesses/s, six days for a 10⁹ dictionary run, four random words
outlasting the sun. The honest summary is in there too — a factor of four on one
card, not a thousand; what it buys is the cost of scale.
§2 gains the row the table never had: **your identity keys stay yours**, ⚠️
against a malicious node operator. An operator hosts your content by design, and
that was documented; that they can also try to become *you* was not. That is the
difference between reading what they host and reading what other operators host.
§4 records that the challenge now carries `node_pk`, why (a first-time member
signs a transcript naming the node and has no GEK to complete a handshake with),
and that it is checked against the ack rather than trusted. Also that refusals
carry a code, and what `not_a_member` usually means.
§8.1 states the multi-browser property plainly — one identity across browsers,
recovered with the passphrase, no second code — together with its cost, since it
is the same mechanism as C4.
invite-pairing-v1 is no longer "a proposal": it shipped. §9bis gains the four
browser-found failures and their common thread — e2e.py is a second
implementation of the client, written in the right order by construction, so it
proves the protocol and nothing about app.js.
CLAUDE.md gets the two things a future session must not rediscover the hard way:
the KDF parameters live in three places held identical by a parity test, and an
unbounded await on the hub socket makes a node silently unreachable (three found).
second-review: C4 marked reduced, not closed. devel-phases-next: 12.2's CSP must
keep `wasm-unsafe-eval`, or the strict policy locks every user out of their keys.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Argon2id memory 64 → 128 MB. Memory is the lever, not time: it caps how many
guesses a card can hold at once, so the ceiling on one high-end GPU moves from
roughly 4k to roughly 2k guesses/s and its 24 GB fits ~187 lanes instead of ~375.
Measured through the vendored build: 640 ms, against 322 ms at 64 MB.
While measuring the real cost of a sign-in, found the SPA deriving the bundle key
twice — once for the key pair kept for the session, then again inside
decryptBundle() for the local bundle. At these parameters that is 0.6 s of pure
waste. Measured now, end to end:
auth_key (PBKDF2 600k) 239 ms
bundle v1 (PBKDF2 600k) 240 ms legacy, until every bundle is upgraded
bundle v2 (Argon2id 128MB) 650 ms
-----------------------------------
sign-in 1 129 ms (889 ms once no v1 bundles remain)
Once per sign-in, and only then: reopening a group, downloading, streaming and
reloading the page all reuse the key, which lives in IndexedDB from login.
Also bounds two waits in the node's hub WebSocket, found because the node went
silent again mid-deploy. It had reconnected after the hub restart, sent its auth
frame, and waited for a reply that never came — `ws.recv()` had no timeout, so a
hub that accepts a socket and then says nothing for a few seconds while starting
up parks the task forever: node running, logging nothing, invisible to everyone.
The auth exchange now times out at 15 s, connect at 15 s, and a refused auth
retries with a fresh token instead of ending the task for good.
QE harness signs in once per account and reuses the token — several clients there
stand for several browsers of one person, and what tells them apart is which keys
they hold, not which token, while the hub quite rightly rate-limits repeated
logins from one address.
Tests: 341, plus the live workflow.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Two corrections to yesterday's judgement, in the order they matter.
**The toggle is gone.** Asked to make the remote key backup optional, I shipped a
setting whose "off" position meant: no second browser, ever, and clearing your
storage destroys the account. I wrote the warning that says so without drawing
the conclusion. A control whose only effect is to break the ordinary case is not
a control, and removing an exposure by removing the feature is not a fix. Every
browser backs its keys up again, unconditionally.
**The exposure is fixed where it actually lives: the KDF.** The keypair bundle
rests on every node whose group its owner joins, protected by the passphrase
alone (finding C4). It used PBKDF2-SHA512 at 600k — compute-only, which is
exactly what a GPU eats. Measured on this machine: PBKDF2 600k costs 241 ms and
Argon2id 64 MB/t=3 costs 322 ms, near enough the same honest work, except only
one of them forces an attacker to find 64 MB per guess.
So the bundle key is now Argon2id 64 MB / t=3 / p=1, via a vendored WebAssembly
build (no external host — the CSP forbids one, and 12.2 will tighten it further).
Parameters chosen by measurement through that build: 19 MB is OWASP's floor at
118 ms, 256 MB is 1.3 s and too slow for a phone, 64 MB sits where a login should.
What this buys, stated honestly: cracking a bundle yields the owner's identity
keys, and with them content on OTHER nodes and the ability to sign as them — not
the content on the operator's own node, which they host in the clear by design.
Argon2id raises that price steeply; it does not remove it, and a weak passphrase
still loses. Hence the floor raised to 12 characters and ~60 bits in the same
breath, which can only be enforced client-side: with the password split (T1) the
hub never sees a passphrase.
Migration is automatic and invisible. Bundles carry an "MBK2" marker; the old
form is still readable, and is re-encrypted the first time a browser backs it up.
Both keys are derived at sign-in, because which one a bundle needs is only known
once it is read and the passphrase is deliberately not kept around.
Two implementations of the KDF now exist — the browser's WASM and argon2-cffi in
QE — so a parity test holds them byte-identical. A disagreement would not look
like an error; it would look like an account nobody can open.
keypair_bundle_delete stays, without a UI. It is the mechanism behind withdrawing
your data from a node, exercised end to end, and it will belong to a deliberate
"forget me on this node" action rather than a setting that quietly disables
multi-device.
Verified against the live deployment: the full workflow passes, including
recovering keys on a second client from the passphrase alone.
Tests: 341.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
draft-v5 §2: against an active hub, reading content moves from "❌ H3" to
"❌ T3 (browser) · ✅ native". The defensible sentence becomes "the hub cannot
read your content unless it ships you malicious client code" — T3 is now the only
path, it is an artifact rather than a silent directory lie, and it does not exist
for a native client. New §5.5 describes admission and key delivery, with the four
properties that carry it and the one exception (open-join groups, where the hub
can walk in the front door — a property of open joining, and the setting is read
from node.toml).
Corrected while writing it: §5.1 said the C5b fix stopped a group admin who does
not run the node from inviting, and that the redesign reverses this. It does not,
because delegation was deferred. What changed is the timing — the operator issues
a code and is then out of the loop.
devel-phases-next: 12.1 is done and NOT as written. The plan was key transparency
plus safety numbers; what shipped removes the directory read instead. Safety
numbers make substitution detectable by a human who checks, at first contact,
when there is nothing to check against. 12.2 (served-SPA integrity) is now the
highest-value item in that phase. Phase 14 marked for what landed.
second-review: H3 and M3 annotated closed at the finding, with what actually
closed them. The §7 verdict table is left intact — it is the record of an audit
on a date, and falsifying it would be worse than leaving it — with a note
pointing at draft-v5 §2 for current state.
CLAUDE.md matters most here, being loaded every session: NS4 read "admin_pk_ed25519
auto-pinned from keystore ✅ DONE", which is M3 described as a feature. Rewritten,
with the two fixes that must never be attempted (auto-pin, hub lookup).
QE/deploy/README.md: set-admin-pk retired from the walkthrough; the regression
checklist now exercises pairing, joining by code, recognition without a code, and
revocation.
USERGUIDE.md is beyond the invite work but was actively wrong: it told users to
POST GEK bundles to a hub endpoint deleted in Phase 12, and to re-wrap for every
remaining member on revocation. Both replaced with what the code does.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Every operator action lived behind a web UI on the node's own loopback
interface. For the normal deployment — a node on a server reached over SSH —
that is unusable: no browser on the host, and 11.5.3 added a per-run token that
had to be copied out of a log to get in.
status hub, node public key, daemon state, groups, admin-key pinning.
Reads the keystore directly so it works while the daemon is STOPPED,
which is exactly when it is needed: the daemon cannot stay up before
its key is linked or before a group exists.
ui prints the URL and the ssh -L line. It does not open a browser —
that was an assumption about the environment, and a wrong one.
gek-init initialises a group key through the daemon's loopback API. Same
operation as the admin UI button, no browser involved.
Also fixes a latent bug in QE/deploy/deploy-node.sh: the pkill pattern was
unanchored, so it matched any shell whose command line merely mentioned the
daemon — including the one running the script. It killed a session three times
before being pinned down. Anchored to the end of the command line.
Verified against the live deployment. grenet and cbesson both connect over
WebRTC through real NAT and can browse, download, stream, upload and chat. The
node audit log confirms the security properties in production: uploads land in
.uploads/{user_id}/ (C5a), the invite required the operator's signature over an
admin transcript (C5b, H5), the pre-proof bundle window is bounded and audited
(C4), and a non-member handshake was refused.
Docs updated: Phase 14 marked partially delivered with the reason, draft-v5 §5.3
records the two operator personas, QE/deploy/README.md documents the commands
and the remaining browser-only gaps (invite, delete).
Tests: 121 node.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Phase 11.5 is complete. All six critical and all seven high findings from the
second review are now closed, bounded, or deferred by explicit decision.
Updated in place rather than appended, so the document does not carry stale
"open" markers next to shipped work:
- §9 split into "closed since this document was drafted" and "still open",
with C6, 11.5.6, 11.5.8 and M8 moved across and the closing mechanism
recorded for each
- §2 claim table: node impersonation is no longer pending
- §3.1 QUIC now shows the unified handshake enforced
- §4.2 records what the QUIC binding actually turned out to be, including the
finding that a resumed TLS session carries no certificate, so the anchor
travels with the session ticket
- §4.4 states that the client pins pk_node and refuses a change
Added a scope note: with C6 closed, pinning is defence in depth, not the primary
control. A substituted node already fails the GEK proof; pinning covers the case
where an attacker holds the group key and swaps the node underneath.
H3 remains the last unfixed finding, and the document still says so.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
|
|
Supersedes draft-v4, which described a system the code did not implement and
made several claims that were simply wrong — "ALL operations require the GEK
proof" (true on one of four transports), "Argon2id 256 MB" (hub only), "hub
stores no content metadata" (private file hashes were registered with it).
Written as a delta over v4: sections not restated are unchanged. Carries an
explicit rule — a claim must name the adversary it holds against — and a
per-adversary table replacing v4's informal assurances.
Records the decisions: transport (aiortc primary, QUIC retained, TCP and the
node HTTP API removed), unified handshake with mutual authentication, admin
operation transcripts, node authority over GEK storage and activation, upload
confinement, hub node-registration and signaling authorization, and the client
architecture — hub keeps serving the web SPA, native client offered alongside,
hub minimization deferred.
States plainly what is NOT true. The defensible claim is "the hub cannot read
your content unless it actively attacks you", not "unreadable by other parties,
even the hub": H3 (hub is the key directory and can substitute a key at invite
time) is open until Phase 12.1, and T3 (hub serves the SPA) is accepted
permanently by decision. Content is also readable by every group member and by
the node operator, so "end-to-end" here means client-to-node, never
client-to-client.
Corrects the v4 NAT traversal account: punch_nat() is a single UDP probe with
no STUN, no candidate gathering and no fallback, validated on one ISP. ICE is
the traversal path, including for native clients.
Open items listed with status, including C6 on the QUIC path.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|