docs(try): note hosted data is encrypted with the user's access key - #70
Merged
Conversation
Add a plain-language reassurance to the /try/ hosted-demo callout: hosted data is encrypted at rest with a key derived solely from the user's access token (node-KEK-independent per hosted_export.rs 'the token is the entire secret'), so when a user isn't actively connected the operator has no token and can't decrypt it. Verified against the freenet-core hosted secrets model before claiming it. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012jmCd1tvDH1EsVTtaDVnxJ
sanity
added a commit
that referenced
this pull request
Aug 9, 2026
* docs(quickstart): stop competing with /try/, and link to it
/quickstart/ was titled "Try Freenet: Join River", which collided with
/try/ ("Try Freenet in your browser"). The two were near-indistinguishable
in a tab strip or a search result, while the nav called the page a third
thing, "Quickstart".
The collision is a leftover of one-directional editing. /quickstart/ got
that title on 2026-05-04 (7e3cb08), two months before /try/ existed. The
/try/ work on 2026-07-07 (#68/#69/#70) added the new page and rewired the
homepage, but never came back to the older one.
The link was one-way for the same reason: /try/ pointed at /quickstart/
twice, /quickstart/ pointed at /try/ not at all. So anyone arriving from
the nav, a search result, /apps/, /river/ or the manual never learned the
no-install option existed, which is the direction that matters more since
the install page is the one carrying the friction.
- Title and <title> become "Install Freenet: Join River", matching the
homepage's primary CTA and freeing "Try Freenet" for /try/. The URL is
unchanged, so no redirects.
- A pointer to /try/ sits above Step 1, before the install friction rather
than buried in "What's Next?", and describes the demo the way /try/
describes itself ("hosted demo", runs on our server, a preview).
Both pages now name each other in the other's own vocabulary: /quickstart/
links "Try River in your browser", /try/ links "Install Freenet →".
Verified with cargo make check-links (self-test plus 222 pages, no broken
references) and by screenshotting both pages at 1280px and 390px.
[AI-assisted - Claude]
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KBzsn4BUH4dHQ9gMHSGj2P
* docs(quickstart): fix an inaccurate claim about the hosted demo
Review found the new paragraph described /try/ as running "on our server
rather than peer-to-peer". That is wrong, and it made /quickstart/ claim
more centralization than /try/ claims for itself.
try.freenet.org is a Freenet peer we run, not a non-P2P reimplementation.
It serves the same node-gateway path shape a local peer serves, for the
same contract key: /v1/contract/web/raAqMhMG7KUpXBU2SxgCQ3Vh4PYjttxdSWd9ftV7RLv/
against try.freenet.org, versus localhost:7509 for an installed peer (the
default base in themes/freenet/layouts/shortcodes/river-invite-button.html).
What is centralized is whose peer holds your session, not whether the
network is involved. Reworded to say that, matching how /try/ puts it
("your data lives with us").
Two more review findings:
- "fastest way to see the network in action" was contradicted one
paragraph later by a no-download option. Now "best way".
- Troubleshooting's network-requirements note was a dead end for exactly
the reader /try/ serves: someone whose firewall blocks UDP hole
punching, who has already tried to install and failed. It now points
there, since the browser demo reaches the network over HTTPS.
Not adopted: propagating /try/'s "export your data in one click" claim to
this page. The reviewer flagged it as unverified and I did not verify it,
so it stays on the one page that already asserts it.
Verified again with a clean build: check-links self-test passes, no broken
internal links across 222 pages.
[AI-assisted - Claude]
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KBzsn4BUH4dHQ9gMHSGj2P
* docs(quickstart): balance the hosted-demo caveats
Second review pass. Three copy findings, all in the text this PR added:
- "your data lives with us" carried the alarming half of /try/'s framing
without the mitigation that follows it there ("encrypted with your access
key, so while you're not using it even we can't read it"). A reader who
never clicks through got only the scary part. Dropped rather than
duplicated: "a preview rather than the real thing" already states the
tradeoff, and /try/ carries the full data story where the reader actually
decides to use it.
- The firewall note promised the demo "still works", unconditional. The
transport claim holds for the parts this repo can show (the page and the
invite API are both HTTPS/443), but River in the browser also needs a
WebSocket to the hosted node, which lives in another repo and was not
verified, and a DPI proxy can block WS upgrades while allowing HTTPS. Now
"usually still works", and says "over HTTPS" so the reason is legible.
- That same sentence called it "River in your browser" with no indication it
is hosted. Someone deep-linking to #troubleshooting from a search would
read it as the real thing. Now "the hosted demo".
- "best way to see the network in action" was still an unsupported
superlative sitting above a paragraph that offers a different path first.
Now "for real", which is the distinction that actually holds.
Clean rebuild: check-links self-test passes, no broken internal links across
222 pages, and both /try/ links plus the new wording confirmed present in the
built HTML. Re-screenshotted at 1280px.
[AI-assisted - Claude]
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KBzsn4BUH4dHQ9gMHSGj2P
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
DRAFT until review passes (merge auto-deploys freenet.org).
Problem
The /try/ callout says "your data lives with us" but omits a real, reassuring fact: hosted per-user data is encrypted at rest with a key derived SOLELY from the user access token, so the operator cannot read it when the user is not actively connected.
Approach
One added sentence in the callout: "It's encrypted with your access key, so while you're not using it even we can't read it."
Backing (verified, not assumed)
Confirmed against
freenet-core crates/core/src/server/client_api/hosted_export.rs("Threat model: the token is the entire secret"): the per-user DEK and bundle key are derived solely from the user token and are node-KEK-independent by design; there is no node-side second factor. The token is header-only, zeroized, and lives in the user's browser. Honest nuance: while the user IS actively connected the node holds the token and can decrypt to run the app; the claim is scoped to data at rest ("while you're not using it"), which the wording states.Testing
Rendered locally; callout reads correctly, no em/en-dashes. Copy-only change.
[AI-assisted - Claude]
🤖 Generated with Claude Code
https://claude.ai/code/session_012jmCd1tvDH1EsVTtaDVnxJ