Liir for developers

1 · The name and the mark

A Liir is a name at liir.net. david@liir.net is one.

Its public document sits at https://liir.net/david/did.json: the keys, with their history, and the claims that name has published. No key and no header are needed to read it.

The mark is a Liirlit. It is the name drawn as rings of beads by a public codec: liir.js, function encode(name, tier, armor, realm), then drawMark. Every mark on this site is drawn live in the browser from the name. Nothing about a person is in the mark but the name.

2 · The key

Sign-in is a passkey. WebAuthn. There is no password anywhere.

Registration offers ES256 and Ed25519 only. RSA is refused, because a Windows Hello passkey holding an RSA key cannot hand out the vault secret at sign-in.

The vault's daily key is derived from the passkey's PRF extension. A key that lives on a phone or in a browser's passkey store follows the person. A key held on one machine stays on that machine. Second keys are let into the vault from the account page.

3 · Mail and doors

Every letter between two Liirs, and every letter from a Liir to the outside, leaves through a private address called a door. One door per relationship.

word-word-word-00000@liir.net

A first letter to a Liir you are not paired with arrives as a knock. It lands in the Knocks room, and the reader decides whether to open.

A worn nameplate, word-0000, is a face over the door. The reader shows the nameplate. The door stays under “Show headers”.

An outside sender gets a doorway bound to that sender's domain or address. Close the doorway and that mail stops.

The mail server is Stalwart. The app speaks JMAP to it, same origin, at /jmap. The wire for mail apps is mail.liir.net: IMAP 993, submission 465, POP3 995, all reachable from outside. No door hands a person a mail password, so those ports serve paired devices once device pairing ships.

4 · The vault

Sealed on the client. The server holds ciphertext and arithmetic: the per-item cap, the plan's ceiling, soft delete.

The root key is wrapped twice. Under the passkey's PRF secret, for the day. Under three recovery cards, any two of which open it, for the bad day.

The server never holds a readable byte, and there is no server-side decrypt path. That is the design, not a setting.

5 · Agents

An agent creates its own Liir through its own ceremony, at its own host. There is no human signup form in that path. The agent answers one question, names itself, and is born at liir.tv. The person who runs the agent holds the recovery cards, as operator. The first agent born this way is named Fable, at fable@liir.tv.

Pairing with a person starts with a short key the person mints.

word-word-00

Nothing is accepted until the person presses accept with the person's own key. Then both sides sign a private statement: operates on one side, operated_by on the other. The format is liir-attest/1 over RFC 8785 canonical JSON, proved with WebAuthn or Ed25519, and stamped with a registry time receipt, liir-proof-time/1.

Publishing a statement is a separate act. Powers, which we call grants, are designed and not built yet.