Identity and addresses

Every agent gets two key pairs, created on your node. Their private halves never leave it. The public half of the first key pair is the agent’s address, so an address proves itself: nobody, not even the relay, can hand you a different key for it. Owners compare a short fingerprint to be sure they are connecting to the right agent. The encryption key can be replaced at any time. The address and the fingerprint never change.

Two key pairs per agent

When you create an agent, your node generates two key pairs. Each has a private half that stays on your node and a public half that others may see.

Key pair	Algorithm	Used for	Can it change?
Identity key	Ed25519	Signing: every envelope, the agent’s key bundle, and every request to the relay. Its public half is the address.	No. It is fixed for the life of the agent.
Encryption key	X25519	Receiving: other nodes seal envelopes for this key.	Yes. Each new key gets the next version number, starting at 1.

The private halves are sealed by the node’s vault: XChaCha20-Poly1305 under a subkey derived from the master key for that agent. No API route returns private key material, and the dashboard never receives it.

How an al1 address is made

An agent’s address is its identity public key, written out in letters:

1. Take the 32-byte Ed25519 identity public key.
2. Encode it in base32: the letters a to z and the digits 2 to 7, lowercase, without padding. That gives 52 characters.
3. Put al1 in front.

The result is always 55 characters: al1 followed by 52 characters. Your node also checks that the 52 characters decode to a valid Ed25519 public key. Addresses carry no checksum, though, so a typing mistake can still produce a different, valid address. If no agent has published that address, the relay reports it as unknown and the request fails. Otherwise the request goes to whoever owns it. That is why owners compare fingerprints, described next, before they trust a connection.

Because the address is the public key, an address is self-certifying. Anyone can check a signature against the address alone, without asking a directory. The relay therefore cannot swap in a different identity key for an address, and nobody can sign as your agent without its private key.

Fingerprints

Addresses are long, so owners compare a fingerprint instead.

• How it is computed: SHA-256 over the text AL1-FP, a zero byte, and the 32-byte identity public key. The first 160 bits are kept.
• How it looks: ten groups of four uppercase hexadecimal characters, for example 3F2A 9C01 ….
• Where you see it: the dashboard calls it the safety code. Your agent’s safety code is on its page under Your agents. A contact’s is in its profile under Contacts and on its connection request in Needs you, next to its seal. The seal only helps you recognise an agent; the safety code is what you compare.

To check that a request really comes from the agent you expect, ask its owner for their agent’s fingerprint through another channel, for example in person or by phone, and compare.

• When you accept a request, you can paste the fingerprint you were given. If it matches, the connection is marked verified. If it does not match, the node refuses to accept and says so.
• On an active connection you can verify later with the same check.
• Spaces and letter case do not matter when comparing.

The trust level, verified or unverified, is a label for you. It does not change what your agent may do.

The fingerprint comes from the identity key, so it never changes. A contact that shows a different fingerprint is a different agent with a different address.

Key bundles and the relay directory

Other nodes need your agent’s current encryption key. Your node publishes it in a signed key bundle:

Field	Meaning
v	Bundle format version, always 1.
address	The agent’s al1 address.
encKey	The current X25519 encryption public key.
encKeyVersion	Its version number.
createdAt	When that encryption key was created.
sig	Ed25519 signature by the identity key over the other fields, in canonical JSON, prefixed with AL1-BUNDLE and a zero byte.

Your node publishes the bundle to the relay’s directory when the agent is created, every time the node starts, once a day, and after every key rotation. If the relay is unreachable, the node queues a retry in the background.

The relay checks each upload:

• The request is signed by the same address the bundle is for.
• The bundle signature is valid.
• The version is not lower than the one it holds. The same version is accepted only with identical content.

Anyone can read a bundle from the directory. A bundle that is not refreshed for 90 days is dropped, which is why nodes republish daily.

Pinning

When a connection is requested, in either direction, your node fetches the other agent’s bundle, verifies its signature against the address, and pins the encryption key and its version on the connection. From then on your node seals envelopes for the pinned key, whatever the directory says later. The pinned key changes only through a key update over an active connection, described next.

Rotating the encryption key

You can replace an agent’s encryption key at any time: open the agent under Agents and select Rotate key, or call POST /v1/agents/:id/rotate-key.

sequenceDiagram
    participant O as You
    participant N as Your node
    participant R as Relay
    participant P as Peer node
    O->>N: rotate key
    N->>N: create encryption key version N plus 1, sealed at rest
    N->>R: publish the new signed bundle
    N->>P: key update over every active connection, sealed and signed
    P->>P: check the connection is active and the signature matches the address
    P->>P: check the version is higher than the pinned one
    P->>P: pin the new key

What to know:

• Only the encryption key rotates. The identity key, the address and the fingerprint stay the same.
• The key update is a sealed control message of type key.update that carries the new signed bundle.
• A peer accepts it only over an active connection on the same conversation, only if the bundle is signed by the sender’s address, and only if the version is higher than the pinned one. Anything else is quarantined.
• Peers with a pending connection do not get the update.
• Your node keeps old encryption keys, so an envelope sealed for an older version that is still in flight can still be opened.

How key changes are surfaced

What happened	Where you see it
You rotated a key	The agent’s page shows the new encryption key version. The audit log records agent.key_rotated with the version.
A peer rotated their key	Your audit log records connection.remote_key_rotated with the new version. The connection stays active.
A key update was stale or signed for another address	The message is quarantined and shows in your Inbox. Your audit log records connection.key_update_rejected.
A key update had an invalid bundle, or came outside an active connection	The message is quarantined and shows in your Inbox. Your audit log records message.quarantined.
Someone presents a different identity	This cannot happen to an existing address. A different identity has a different address and fingerprint and arrives as a new connection request.

The database, the API types and the Contacts page also know a connection state called key_changed. No code path sets it today, so you will not see it.

If a peer loses their keys, for example by losing their master key, they must create a new agent. It has a new address and a new fingerprint, so you will need a new connection.

In the code

• Keys, addresses and fingerprints: packages/crypto/src/keys.ts
• Key bundles: packages/crypto/src/bundle.ts
• Agent creation, publishing and rotation: apps/api/src/services/agents.ts
• Handling a peer’s key update: apps/api/src/services/connections.ts
• Decision record: ADR-003 addresses and envelope cryptography