Codex Server
What is Codex?
Codex is Eon Phoenix’s per-domain public-key directory: a small standalone
service (binary eon-keyserver, from the separate Go module
eon-mail/keyserver) that you deploy alongside a mail domain’s existing
SMTP/IMAP server. The binary itself serves no web UI — it is an HTTP/JSON
API consumed by the Eon Phoenix client (and the eon-cli helper), plus an
optional administrative API on a separate listener that a standalone admin
console talks to.
Codex stores and serves hybrid post-quantum public key bundles keyed by
full email address, so that a Phoenix client anywhere can find and verify
the key for alice@yourdomain.example before encrypting to her. A bundle is
one signing identity (ML-DSA-87 + Ed25519) plus a set of encryption keys,
one per KEM algorithm — ML-KEM-1024 and FrodoKEM-1344 today — each paired
with X25519 and each carrying its own binding signature by that identity.
Codex never holds a private key and never sees message content — clients encrypt end-to-end; Codex and the mail server are both untrusted transport.
The two deployment modes
The same eon-keyserver binary runs in one of two modes, and a real
deployment typically runs both, as two separate instances:
| Mode | Typical hostname | Who it’s for | Publish auth |
|---|---|---|---|
| Authoritative | keys.<domain> | addresses on a domain you control | bound to mailbox login (Dovecot) |
| Directory (“Codex”) | codex.<domain> | any mailbox, including Gmail/Outlook/third-party domains you don’t control | email-challenge (a code mailed to the address) |
The authoritative instance is bound to your own mail domain: it only
lets a user publish keys for alice@yourdomain.example after they prove
they can log into that mailbox (via Dovecot). The directory instance
(commonly the one actually referred to by the name “Codex”) accepts
open enrollment from any mailbox — it mails an 8-digit code to the
address and issues the same kind of authorization token once the code is
confirmed back. This is the lever that lets a Gmail or Outlook user publish
and be discovered under Eon Phoenix’s post-quantum scheme without their
provider running any Eon software at all.
Both instances are the same binary, just started with different flags (see Configuration) and, in production, usually run as two separate systemd services with separate data directories.
Security model, in one paragraph
Private keys are generated on the client and never uploaded — Codex only
ever stores public key bundles, and verifies each bundle’s self-binding
before storing it, so a hijacked transport can’t substitute an attacker’s
encryption key. Every discovery response is signed by Codex’s own ML-DSA
signing key. For the authoritative instance, clients anchor that signing
key to a DNSSEC _eon-keysign TXT record; for the directory instance
(no domain of its own to anchor in DNS), clients instead pin the signing
key’s fingerprint directly. DKIM/SPF/DMARC on the surrounding mail
infrastructure only prove domain routing — sender authenticity inside a
message rests solely on the per-user ML-DSA+Ed25519 signature that Codex
never sees or touches.
In this section
- Install — build or download the package, install one or both instances, and set up DNS/TLS
- Configuration — flags, environment file, and the multi-instance layout
- Operations — the mailauth/email-challenge flow, key bundles, escrow tiers, signing-key rotation, and day-to-day service management