Key Registry
A key registry is one kind of identity anchor. An anchor publishes
which public key is a user's current key. peers.app runs the default
anchor as part of peers-services. A user can also name an https URL that
serves the same document. With an empty anchor list, a peer with Peers
Services enabled accepts a different key only when its registry carries a
valid succession co-signature by the key on record. With Peers Services
disabled, a different key stays untrusted.
The registry stores only public keys and signatures. It never holds secret keys, password hashes, or recovery codes. Holding the current key proves you can speak as that key. It does not let you replace it.
The anchor document
GET /api/v1/keys/:subjectId returns a document signed by the registry
({ contents, signature, publicKey }). An https anchor serves the same
contents, with or without that envelope.
| Field | Meaning |
|---|---|
version | 1 |
userId | the Peers ID the document is about |
keys | keys that are active right now, oldest first. A listed key is current. Retired and revoked keys are omitted |
keys[].issuedAt | when that key was registered |
keys[].authorizedBy | { publicKey, signature } when the previous key co-signed the succession statement. Present means a rotation; absent means a recovery |
anchors | where else to look. A user document defaults to this registry's own URL. A package, group, or device document lists none |
updatedAt | when the registry signed the document |
The succession statement the previous key signs is
{ purpose: "peers-key-succession", userId, publicKey, issuedAt }, where
publicKey is the new key. authorizedBy.publicKey is the previous key and
authorizedBy.signature is its signature over that statement.
Responses send Cache-Control: public, max-age=60. A peer keeps a confirmed
answer for that long, or for the shortest max-age it was given.
How a peer decides
A peer resolves a new key against the anchors already stored for that
user (the on-record list, on the personal Users row). A list that arrives
with the new key is ignored. So is a synced Users row that tries to change
publicKey or anchors for someone else: the row is not written until the
anchors on record confirm the key, and a replacement anchor list is never
taken from that row.
Each anchor answers in one of three ways:
| Answer | When |
|---|---|
| Confirm | the document is for this user and lists the presented key |
| Veto | 404, the wrong user, a document that omits the key, or a body that is not a document (including one over the size cap) |
| Abstain | timeout, network error, a redirect, a 408 or 429, or a 5xx |
The presented key is confirmed only when at least one anchor confirms and
none veto. Any veto refuses it. Every anchor abstaining leaves the change
pending. When the record lists no anchors (a contact stored before anchors
existed, or one that removed them all), the peer asks its configured
registry's document for that user instead, and accepts only a rotation: a
key whose authorizedBy is signed by the key on record. Anything else the
registry says leaves the change pending; it cannot veto or start a recovery.
With services off there is nothing to ask, and the change stays pending.
A confirmed key whose authorizedBy is a valid
co-signature by the key on record is a rotation and replaces the personal
row immediately. A confirmed key without that co-signature is a recovery.
Peers wait 72 hours from when they first saw it, then adopt it if nobody who
holds the key on record has contested it. A contest is a signed statement
posted to POST /api/v1/account/contest and listed by
GET /api/v1/account/contest?userId=. The registry accepts it from an active
key or from the key the recovery retired as lost; a key its holder rotated
away from, or a revoked key, cannot contest. It stays pending until a peer
accepts the new key. A key that is no longer on the personal row is not accepted.
An anchor list changes the same way. The anchors already on record must
publish the new list: one confirming document and no veto. peers-services
stores that list when an anchor-write session POSTs
/api/v1/account/anchors. Until a user sets one, a user document lists this
registry itself. That default URL is the first PEERS_SERVICES_PUBLIC_URLS
origin, or the request host when that variable is unset. A public hostname is
advertised as https even when a TLS terminator leaves the process speaking
plain HTTP, so production lists https://peers.app. Loopback and private
addresses keep the request's scheme, which is how a local fleet stays on
http. An empty stored list is an opt-out. A browser that cannot
fetch an arbitrary https anchor reads it through
GET /api/v1/account/anchor-fetch?url=. That proxy returns the bytes. It does
not decide whether the document is trusted, and it refuses addresses that are
not public https hosts. It maps what it saw onto the three answers: a body
that is not JSON, or one over 64 KiB, returns 422 so the browser vetoes; a
redirect, a timeout, or no answer returns 502 so the browser abstains. Fetching
an https anchor directly applies the same bounds: 8 seconds, 64 KiB, and
redirects are not followed.
API
Base path: https://peers.app/api/v1/keys. Reads are public; everything is
rate limited per IP.
| Call | What it does |
|---|---|
GET /.well-known/peers-key-registry.json | The registry's own ID and signing key. Pin this; every signed read verifies against it. |
GET /api/v1/keys/:subjectId | The anchor document, signed by the registry. |
GET /api/v1/keys/:subjectId/:publicKey | One stored key record, signed, including retired and revoked rows. |
POST /api/v1/keys/:subjectId/challenge | { publicKey } → { challengeId, nonce, expiresAt }. Single use, bound to that subject and key. |
POST /api/v1/keys/:subjectId | Add a key: { challengeId, key, proofOfPossession, authorization? }. |
POST /api/v1/keys/:subjectId/:publicKey/status | Retire or revoke a package, group, or device key: { challengeId, status, reason, authorization }. |
Proof of possession – the new key signs
{ purpose: "peers-key-proof", subjectId, publicKey, nonce }. That is an
ISignedObject from signObjectWithSecretKey in @peers-app/peers-sdk.
A challenge is consumed by the first attempt that uses it.
A user's first key is registered by that proof alone. This is what a
device does the first time it reaches peers-services. A user who already
has a key can add a later one only during an anchor-write session opened with
the recovery email (see Writing to the peers-services anchor);
without that session both calls return 403. An operator records a rotation
with the seed tool, passing the previous key's succession signature. Either
write retires the user's previous keys.
Packages, groups, and devices cannot self-register a first key. An
operator seeds it. A later key is authorized by a key that is already active
for that subject, signing
{ purpose: "peers-key-authorization", subjectId, publicKey, nonce }. The
same kind of signature, with purpose peers-key-status, retires or revokes
it. A user's key is not in that rule.
Stored rows still use active, retired, and revoked. Revoked is final.
The anchor document only lists keys that are active. Signing in
(/api/v1/auth/authenticate) accepts an active key and refuses any other.
How peers-services uses it
- Signing in (
/api/v1/auth/authenticate) and the Socket.IO connection accept any active key of the user and refuse a revoked one. /api/v1/auth/registerreportsalready_registeredfor a key the registry knows and asks you to add an unknown key through the registry instead.- The legacy per‑user record keeps a copy of the newest active key so older readers see a rotation immediately.
The peers-core publisher key
The system package peers-core is signed by a publisher key whose public half
ships inside every host (peersCorePublishPublicKey in @peers-app/peers-sdk)
and is pinned on first install. The SDK also carries
peersCoreRevokedPublishPublicKeys, an append‑only list of publisher keys that
must never be trusted again:
- A version signed by a revoked key never verifies, whether it arrives from the update server or from another group on the mesh.
- A client whose pinned peers-core key has been revoked re‑pins to the current key on startup and before each remote update check, then accepts releases signed by the new key.
- Hosts that predate a rotation keep the old pin and reject the new releases until they update; they are never dual‑signed with a revoked key.
The registry mirrors this: the peers-core package ID is a subject whose old
key is revoked:compromised and whose current key is active. See
Releasing for how the key is generated, stored,
and rotated.
User key rotation
A different key in a handshake is accepted only when the anchors on record
confirm it as a rotation. Otherwise the handshake is Untrusted and the
stored key stays.
Peers refuse a key that any anchor on record vetoes, so a rotation commits only once every anchor on record lists the new key. One holdout changes nothing: the local key, the wrapped secrets, and the profile row stay as they were, and the command reports which anchor did not list the key.
peers keys rotate (and Rotate signing key on Identity → Account) writes
through a writer for each on-record anchor that has one and polls the rest.
The peers-services writer is installed when services are configured. It
accepts the new key only during a short-lived session opened with the recovery
email (see below); without that session the registry refuses the write. An
https anchor has no writer, so when one is on record the command first
prints the anchor document, signed by the current key, for you to place at
every https anchor on record, then waits until all anchors list the key. A
timeout changes nothing. With services off and no anchors on record, the
command reports that rotation needs an anchor.
peers keys rotate --manual writes nowhere. It prints the same document and
polls every anchor on record, including peers-services, which an operator
seeds with --authorized-by and --succession-signature.
A session write to peers-services replaces the key on record: the previous keys are retired in the same operation, so the document lists one key and a device that still presents the old one is refused.
Writing to the peers-services anchor
Holding the current key does not authorize a write. A user's first key is
still a self-registration. A later key, or a status change, needs a session
whose token carries scope: anchor-write. A normal sign-in token does not.
The recovery email lives in account_auth, separate from the public key
records. Binding it is signed by a current key, and the one-time code goes to
that mailbox. Opening a session mails a code to the verified address and does
not require the signing key, so the same step is what recovery uses. The
session lasts about ten minutes. A rotation sent during it includes the
previous key's succession signature when the device still holds that key.
Codes are stored as hashes. Production mail goes through Resend when
RESEND_API_KEY is set (PEERS_EMAIL_FROM overrides the from address,
default Peers <noreply@peers.app>). PEERS_EMAIL_TRANSPORT=console, or a
missing API key outside production, prints the code instead and keeps the
last one for dev and end-to-end tests. With NODE_ENV=production and no
key the service refuses to start rather than fall back to the console, since
that transport serves codes over /email/last-code; set the key, or set
PEERS_EMAIL_TRANSPORT=console deliberately. That last-code route answers
404 when Resend is the transport. Five wrong codes burn the code, and a code
expires after ten minutes.
A passkey opens the same kind of session. Registering one is signed by a
current key; a later assertion needs no key at all, which is what recovery
relies on. Set PEERS_WEBAUTHN_RP_ID to the registry's host (for example
peers.app) in production: the browser binds the credential to that relying
party, and the server accepts ceremonies only from that host and its
subdomains, plus any exact origins listed in PEERS_WEBAUTHN_ORIGINS
(comma-separated, for a dev UI on another host). With PEERS_WEBAUTHN_RP_ID
unset the relying party is taken from the request's origin, which is only
acceptable for local development. An origin that names no host (a page loaded
from a file, such as the desktop window) is refused. Each ceremony is held
for five minutes under its own challenge, so a sign-in started for a user by
someone else does not cancel the one that user has in flight, and a challenge
is accepted once. The four passkey/* routes share the per-user, per-IP
limit of the mailed-code routes (ten a minute).
Opting out means leaving the mailbox unbound. Peers Services then refuses every later key. Another anchor you already listed can still confirm a manual publish. If the signing key is lost and no mailbox is bound, the account cannot be recovered.
peers keys email bind --email you@example.com
peers keys email verify --email you@example.com --code 123456
peers keys email session
peers keys email session --code 123456
peers keys rotate
What is already in place, so that publish can land without re-encrypting databases:
- The host credential record stores
dbSecretseparately fromsecretKey. New identities mint a random database key. A record that predates the field derives it once from the secret key and keeps that value. A later rotation keepsdbSecretand appends the old public key topreviousPublicKeys. - Once every anchor lists the new key, the host stores it at once and keeps
the retired secret beside it (
rewrapFrom) while it re-encrypts secret persistent variables one by one and re-signs the profile row; the retired secret is dropped last. A host that dies in between finishes the re-encryption at its next start, so no secret is left under a key nobody holds. - A new user whose services URL is configured starts with one on-record anchor, the peers-services document for their user id. With services off, the list is empty.
peers keys showand the Signing key card report the current key, previous keys, and what the registry lists when it can be reached.
An operator records a rotation the registry will not accept over HTTP:
node dist/keys/seed-subject-key.js \
--subject <userId> --type user \
--public-key <new base64url> --status active \
--issued-at <ISO> \
--authorized-by <previous publicKey> \
--succession-signature <sig>
The signature is checked before it is stored. A signature that does not verify is refused.