byhand · security

How a page is protected

Encrypted end to end with AES-256-GCM. The key is made on your device and travels only in the link, after the #: browsers never send that part to any server.
Signed by you. A page's id is an Ed25519 public key; every version is signed with its private key, which never leaves your devices. Readers check the signature and the hash before decrypting: whoever serves the page (the gateway, a guardian) can withhold it, not alter it. Being served an older version than one already seen in that browser shows a warning.
Private messages are for you only: sealed to your key (X25519, then AES-GCM), so a guardian that holds them while you are away cannot read them, even one that has the link.
The page runs in a sandbox with an opaque origin: its scripts cannot reach the viewer page, the key in the address, or the gateway's site. It talks to the outside only through window.byhand.
Directly when possible. The page, then the comments, votes and messages, go between your device and the reader's browser over WebRTC (DTLS-encrypted, on top of their own encryption); the gateway only passes the sealed offer and answer. With --hide-ip, your device never connects directly: the gateway passes the page on.
Nothing on a server. The gateway relays and forgets. Guardians keep encrypted copies they cannot read, and drop them after 30 days without news from you.

Who sees what

Who	Sees	Never sees
The gateway (https://byhand.page, or yours)	Page ids, when they are opened, readers' IP addresses, sizes (when the page comes directly, only that a reader asked); the public preview if you turned it on (`--preview`)	Pages, comments, messages, keys
Your device, for a reader served directly	The reader's IP address, and the reader sees yours (that is what a direct connection is)	—
STUN servers (Cloudflare, Google)	The public IP addresses of readers and of your device, when they look for a direct path	Pages, ids, keys, who talks to whom
A guardian	Encrypted versions and messages, when they change, which ids it keeps	Pages, messages, the link's key, your private page's key
Anyone with the link	The page, its versions, comments, shared state and files	Private messages of others, your other pages
Your devices, co-authors	Everything of the pages they share with you, and the right to publish them	—
Peer to peer services (DHT, pkarr relays, iroh relays)	That an id exists, which devices serve it and their IP addresses (unless `--hide-ip`), encrypted traffic between devices	Pages, keys
The chat app or email where you paste a link	The whole link, key included	—
Your AI provider (if you make pages with AI)	Your request, and the page when you change one	Your other pages, your links

Who sees your IP address

Nobody but your readers can read a page, whatever the setting. What the settings change is who sees your IP address and who learns that a page exists. With the defaults:

Who	Sees	When
The reader	Your IP address	Each time a page opens: your device's WebRTC answer carries it, even when the direct path then fails
STUN servers (Cloudflare, Google)	Both public addresses	Each direct attempt
The gateway	Your IP and the reader's, page ids, sizes and timing	Always (it introduces you, and carries the page when direct fails)
DHT nodes and pkarr relays	Your page ids and your device's IP address	For your devices and guardians to find each other

Less of it: byhand install --server (no DHT), your own pkarr relay, --hide-ip (your IP published nowhere, and no WebRTC with readers: they go through the gateway). Every option, with diagrams and side-by-side tables: network.

What byhand does not protect

The decryption code comes from the gateway. In a browser, the code that decrypts the page is served by the gateway. A compromised or coerced gateway could serve code that steals the key of the links opened through it. Mitigations: run your own gateway, or read with byhand get <link>, which decrypts with the app and trusts no gateway.
The link is the key. Whoever has it can read, and so can the app or mailbox it went through. Send it over a channel you trust. Single-use links (--once) tell you if someone opened it first.
Readers can keep a copy. Stopping a share stops new readers, not what was already opened, saved or photographed.
Metadata. The gateway and peer to peer services learn who shares and opens pages when, from which addresses, and how big they are, not what they say.
Your device. Its keys (pages, your private page, your AI key) are in files only your user can read, not encrypted at rest. Malware on your computer, or someone using it, has them.
Your private page's link (byhand me) controls all your shares, and can use your AI key. Keep it to yourself.
Viewer names are whatever readers type: anyone can sign a comment with any name.
A page is its author's content. It can run scripts and open pop-ups like any website, inside its sandbox: trust a page as much as whoever sent it.
One key per share, no forward secrecy: someone who records encrypted traffic today and gets the link later can read it.

If something leaks

A page's link: Stop sharing it (byhand share stop page.html, or "Stop sharing" on your private page). To share it again with a new link, delete its page.html.byhand.json first.
Your private page's link: byhand me --new: the old link stops working, your other devices get the new one.
A lost or stolen device: byhand me remove <device> from another one: the private link is replaced. Stop the shares it held, and revoke its AI key at your provider.
Your AI key: Revoke it at your provider, then byhand me ai with a new one. Set a spending limit there.

Going further

Your own gateway: nobody else's server between you and your readers.
Your own records relay (byhand gateway --pkarr) and iroh relay (--relay), or the gateway only (byhand share --only web): no public peer to peer service.
--hide-ip: your IP addresses in no record.
byhand get <link> to read without the gateway's code.