Accounts & access
Sign-up, email verification, sessions, two-factor with recovery codes, and wallet sign-in.
Ways in
| Method | Details |
|---|---|
| Email + password | Requires email verification before the account is usable. |
| Wallet sign-in | Prove control of an address by signing a fixed statement — no gas, no funds moved. |
| Two-factor | TOTP (any authenticator app) on top of either method. |
Sessions
- Sessions are signed cookies (HMAC-SHA256) over a server secret, verified in constant time.
- The secret must be at least 32 characters. If it is missing or too short, Elpis fails closed rather than issuing a weak session.
- A separate
TOTP_SECRETencrypts 2FA secrets at rest, so rotating the session secret does not lock anyone out of two-factor.
Two-factor and recovery codes
Enrolment shows a QR code, confirms one code, then displays recovery codes once — they are not retrievable again, because they are not stored in a recoverable form.
Password reset
POST /api/auth/password/request mails a single-use link that expires in an hour; POST /api/auth/password/reset sets the new password and revokes every session. A reset is usually a response to a suspected compromise, so leaving other devices signed in would defeat the point.
Throttling
Sign-in and 2FA verification are rate-limited per identity and per source. An unknown email takes a comparable path to a known one, so the response does not disclose which accounts exist.
What a wallet signature proves
It proves control of an address. It does not prove the person at the keyboard — so a wallet account is treated as one credential, and two-factor is available on top of it exactly as it is for a password account.
API keys
- Scopes:
read,propose,approve. A key holds only what it needs. - Secrets are shown once at creation and stored hashed.
- Keys can be revoked without affecting other keys on the account.
- Agent keys should never carry
approve— that is the line between a suggestion and an authorisation.