The vault keeps a person's Hypermedia account keys for them, so they do not have to look after a recovery phrase. It works like a password manager. The browser encrypts the keys with a key that only the person can produce, and the server stores data it cannot read. The hosted vault is https://hyper.media/vault. The interface calls it "Identity".
In the vault a person can do five things:
Create an account.
Sign in with a passkey or a password.
Get back in with recovery words after they forget the password.
Approve a website that wants to act for them.
Connect the desktop app and the mobile app, so the same accounts appear there.
Keys covers the other ways to hold a key.
Where the code is
The code is in vault/, package @seed-hypermedia/vault. It is a separate Bun workspace, outside the pnpm workspace. The server is Bun.serve with bun:sqlite. The frontend is a React single-page app with react-router, and with Valtio for state. bun build.ts builds it. It uses @seed-hypermedia/client, @shm/shared and @shm/ui, three of the shared packages, through file: dependencies, which copy the packages at install time.
Path | What it holds |
|---|---|
| The HTTP server and route table. |
| Every flag, its environment variable and default. Configuration is read only here. |
| The request and response types, the encryption rule and the authentication rules. It is the one contract between client and server. |
| The handlers. |
| The schema and its version check. |
| The app's logic: login, decrypting the vault, publishing a profile, delegation and vault connect. |
| Browser crypto helpers (WebAuthn, PRF, recovery words) and the screens. |
The cryptography itself (making keys from secrets, and encryption) is in the SDK, in @seed-hypermedia/client/vault and /encryption. So the browser and the mobile app share one implementation. The daemon holds the desktop app's side of a connected vault, and it has its own implementation in Go.
The zero-knowledge design
"Zero-knowledge" means the server never learns the keys it stores.
Each person has one random data encryption key (DEK). The DEK encrypts the vault: the account private keys, the list of delegations the person approved, and settings such as the notify server. The server stores the encrypted data in users.encrypted_data with a version number. A save must name the version it changes. So when two devices save at the same time, one save fails and nothing is lost without notice.
Each way to sign in is a credential. A credential encrypts ("wraps") the DEK with its own key, and the server stores only the wrapped copy.
Credential | How the client derives its keys | What the server keeps |
|---|---|---|
Passkey | The WebAuthn PRF extension yields a secret the authenticator reproduces on every login. | Attestation data and the wrapped DEK. |
Password | Argon2id in the browser, with the email as salt. | An Argon2id hash of the authentication half and the wrapped DEK. |
Secret | A full-entropy random secret, used by the desktop app after vault connect; no Argon2id needed. | A SHA-256 hash of the authentication half and the wrapped DEK. |
Recovery words | 12 BIP-39 words chosen at password sign-up encode 128 bits, which HKDF turns into the secret of a secret credential tagged | The same as a secret. A person has at most one: saving new words deletes the old credential. |
The client makes two keys from each secret. The authentication key goes to the server and proves who you are. The encryption key never leaves the client, and it is the only thing that unwraps the DEK. Encryption is XChaCha20-Poly1305.
Recovery words. A person who signs up with a password also saves recovery words:
The vault shows the words once. The person copies them, downloads them as a text file, or writes them down.
If the person forgets the password, they type the words or upload that file. The words sign in through /vault/api/login/recovery and unwrap the DEK through their own credential.
Signing in this way does not reset the password. The person can change it in settings afterwards.
A password user without recovery words sees a reminder in the vault, and on the consent screen before they return to a site, until they save the words.
These words open the vault only. They are not the recovery phrase of an account key.
What cannot be recovered. If you lose every credential and have no exported key and no recovery phrase, nobody can recover your accounts. Email proves that you own an address, with a 4-digit code and three attempts, but it cannot decrypt anything. There is no credential on paper and no recovery through friends.
What the design trusts. The browser runs the JavaScript that the vault's origin serves, so the design trusts that origin to serve honest code. This is why the hosted vault is on hyper.media, and why other sites send people there to sign in.
How it talks to the daemon
The vault uses the daemon of the same site for three things.
Publishing. When a person creates an account or approves a delegation, the browser builds profile and capability blobs and signs them with the decrypted account key. It uploads them to <backend>/ipfs/<cid> on the site's daemon.
Reading accounts. GET /vault/api/accounts/:id calls the daemon's GetAccount over gRPC-web.
Saying an email is verified. When the vault returns a person's data, it signs {email, signer, host} with the first key in its daemon's keystore, through SignData. A notify service that trusts this vault accepts that signature and does not send its own verification email. The notify API has the rule. The desktop app reads the same signature through its daemon's GetVaultEmailPrevalidation and shows it to the Seed hosting service. So a new user can skip the email login there.
Delegation: Sign in with Seed
A website may want a visitor to comment or edit as their account. The website makes a session key in the browser and sends the visitor to /vault/delegate with a signed request that names that key. The vault then does this:
It signs the person in.
It shows a consent screen that names the origin of the site.
It signs an AGENT capability from the chosen account to the session key.
It records the delegation in the encrypted vault.
It sends the person back to the website.
The web app uses this for its own sign-in. Any other site can use it with the SDK. Sign in with Seed has the whole exchange, with the parameters and the checks.
Vault connect: desktop and mobile
The desktop app keeps a local vault in its daemon. It can connect that vault to a remote vault, so the same accounts appear everywhere. The connection is a short exchange through the vault server.
The app makes a 32-byte token. It opens /vault/connect in the browser with the token in the URL fragment. Then it asks /vault/api/vault-connect/<id> again and again, where the id is a hash of the token. This address is the mailbox.
After the person agrees, the browser creates a secret credential for the device. It encrypts the credential and the location of the vault with the token, and posts the result to the mailbox.
The app picks it up, the server deletes it, and the app can now open and sync the vault on its own. Pending mailboxes expire after 15 minutes.
The server only ever sees the encrypted message. The token travels in the URL fragment, which browsers do not send to the server. The daemon's code for the device side is in backend/storage/vault, and the mobile app has its own copy in frontend/apps/mobile/src/vault/connect.ts.
Routes
Route | Purpose |
|---|---|
| The app: login, choose credential, verify email, recovery words, create profile, delegate, connect, settings. |
| Public config: backend URL, notify server, web base URL. |
| Authentication, with an HTTP-only session cookie. |
| Read and save the encrypted vault. |
| Manage passkeys, passwords, device secrets and the email address. |
| The connect mailbox. |
| Account lookup through the daemon. |
| The app reports the public account IDs its vault holds, each claim signed by that account's key. See Running an invite-only vault. |
| Public lookup of an unused invitation: the email it is for, or 404. The invited-user screen uses it. |
| The admin API, for an enterprise node. A call must send the admin secret as |
Configuration
Every setting is a flag with an environment variable behind it.
Flag | Variable | Default |
|---|---|---|
|
| 3000 (3030 in development) |
|
|
|
|
| required; the WebAuthn relying party, |
|
|
|
|
|
|
|
| the relying-party origin |
|
| the backend HTTP URL |
|
| same origin |
|
| unset, which disables email |
|
| unset; when set, the vault sends verification emails through the Seed hosting email relay. Each email is one |
|
| off; |
|
| unset, which disables the admin API |
none |
|
|
The database schema has a version. Migrations are in src/sqlite.ts beside the schema, and they run at startup. If the version still does not match the code, the server starts in a mode that shows only a schema-mismatch page, which tells you to delete the database.
Running it
cd vault
bun run dev # :3030 with hot reload, against the web app on :3000 and notify through it (:3000/hm/api/notify โ :3060)
bun check # typecheck and format
bun test./dev up runs it as the vault pane. In development it proxies /hm/api/config to the web app on port 3000. The web app finds the vault through WEB_IDENTITY_ORIGIN or SEED_IDENTITY_DEFAULT_ORIGIN. The value is http://localhost:3030 in development and https://hyper.media by default. The images are seedhypermedia/vault:dev and seedhypermedia/vault:latest. On a site, the reverse proxy sends the /vault path to this service.
Working with it
In the Seed app
In the desktop app, the account settings switch between the local vault and a remote one, start vault connect, and manage the email, the password and the notify server of a connected vault. Connected accounts still sign through the local daemon.
CLI
SDK
@seed-hypermedia/client/hmauth, part of the SDK, has the client side of delegation: startAuth, handleCallback and createSessionSigner. The SDK also exports the vault's cryptography helpers for other clients.
Seed API
Everything under /vault/api is JSON over HTTPS and belongs to the vault app. It is separate from the Seed API. These routes are for the vault's own frontend. Other websites use the delegation redirect that Sign in with Seed describes.
Agents
Seed Agents and coding agents do not sign in through the vault. An agent acts with its own key and with a capability that an account gave to it. See Using Seed from your own agent.
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime