The zero-knowledge architecture, in detail

What “zero-knowledge” means here

The phrase gets used loosely. In Crowdbook it has a precise meaning: all encryption and decryption happen on your devices, and the server never possesses the keys to read what it stores. Every sensitive value the server holds — shared attributes, group keys, even the wrapped copies of your private keys — arrives as ciphertext that was produced on a client. The server's job is to move opaque blobs between members and keep a version counter. It is not trusted with your data, because it is never given the ability to read it.

This is a stronger position than “encrypted in transit” or “encrypted at rest.” Those protect data from outsiders while the service itself can still read everything. Zero-knowledge means the service operator can't read it either.

Two keypairs, born on your device

When you register, your device generates two independent keypairs, each with a distinct job:

• An X25519 keypair — used for key wrapping via Elliptic-Curve Diffie–Hellman. This is how a group key gets sealed for you specifically, so only your device can unwrap it.
• An Ed25519 keypair — used purely for signing login challenges. It proves you are you, without your password ever travelling to the server.

The public halves are published so others can wrap keys for you and the server can verify your signatures. The private halves are stored only in wrapped (encrypted) form — see the master key below.

Your password becomes a key, not a secret the server keeps

Crowdbook stretches your password with Argon2id, a modern, memory-hard key-derivation function, in two domain-separated ways:

• A master key is derived on your device and never leaves it. It's what wraps your private keys.
• A separate authentication hash is derived with a distinct associated-data tag and sent to the server for login. Because the two derivations are domain-separated, the value the server stores cannot be turned back into the master key.

The upshot: the server holds something that lets it check your password on login, but nothing that lets it derive the key that decrypts your data. Those are deliberately different values from the same password.

Login is a signature, not a password on the wire

Signing in is challenge–response. Your device asks the server to start a login; the server returns a random 32-byte challenge (and your stored salt). Your device re-derives the master key from the password you just typed, unwraps your Ed25519 private key, signs the challenge, and returns only the signature. The server verifies it against your published public key.

Your password never crosses the network. And to avoid leaking which email addresses have accounts, a login request for an unknown address still returns a well-formed (dummy) salt, so “does this person have an account?” can't be read off the response.

Group keys: one secret, wrapped for each member

A group has a single symmetric group key, generated on a member's device. To let everyone use it without ever exposing it to the server, the key is wrapped once per member: for each person, the creating device performs X25519 ECDH against that member's public key and seals the group key with AES-256-GCM. Every member gets their own encrypted copy that only their private key can open.

Adding or removing someone, or rotating the key, means re-wrapping it for each remaining member and uploading the new set. The server simply stores the wrapped blobs and writes an audit record — it never sees the key itself.

Attributes: encrypted with AES-256-GCM before upload

The contact details you share into a group are encrypted with the group key using AES-256-GCM — authenticated encryption, so tampering is detectable — on your device, before anything is uploaded. What the server receives and stores is an opaque, authenticated ciphertext blob. Peers pull it, unwrap their copy of the group key, and decrypt locally.

Multiple devices, without ever trusting the server

Because your private keys are stored only in wrapped form, a second device can recover them: it authenticates with your password, receives the wrapped key blobs, and unwraps them locally with the master key it just re-derived. The server hands over ciphertext it still cannot read; only your correct password turns it back into usable keys on the new device.

Sync is version-counted and server-authoritative

Each group carries a version counter that the server increments on any change, atomically, so two members pushing at once can't lose an update. Devices pull with a per-group cursor and only fetch groups that actually moved — which keeps sync quick (targets: under 5 seconds for small groups) without the server ever needing to understand the payloads it's shuttling.

Deletion and data minimization

Only the attributes you explicitly share into a group are ever uploaded — Crowdbook never reads your private address book back out. When you delete your account, your device key material and encrypted blobs are purged, group key wrapping is revoked, and your shared attributes are tombstoned so peers' devices drop them on the next sync. This is the GDPR/CCPA posture by construction, not as an afterthought.

A note on honesty

Crowdbook is in active development, and we'd rather describe what the system actually does than a marketing ideal. The architecture above reflects the implemented design: client-side AES-256-GCM, X25519 key wrapping, Ed25519 challenge-response login, and Argon2id-derived keys. As the product matures we intend to publish more detail and invite outside review — because a privacy claim you can't inspect isn't worth much.