Auth & the wallet

The project uses sign-in-with-wallet: there is no password, no email. Proving you own a wallet's secret key is your identity. This page explains the full flow and the JWT layer on top.

The core idea

A wallet is just an ed25519 keypair (secret + public) stored in the browser. The address is derived from the public key. So:

• The server cannot look up "your password" — there isn't one.
• To prove who you are, you prove you hold the secret key.
• Proving = signing a random challenge the server gives you.
• Once proven, the server issues a JWT so you don't have to sign every request.

The exact same keypair also signs transactions. One key, two uses. Frontend → see the frontend crypto page

The login flow, step by step

Why a challenge instead of just signing your address?

If the server asked you to sign the same string every time, an attacker who captured one signature could replay it forever. A fresh random challenge that's single-use and expires in 10 minutes kills replay attacks. The challenge is stored in Postgres with a used flag.

JWT — the session layer

JWT = JSON Web Token. A signed blob of JSON that says "this address is authenticated". Two tokens are issued:

1#[derive(Debug, Clone, Serialize, Deserialize)]
2pub struct Claims {
3    pub sub: String, // address  ("subject")
4    pub typ: String, // "access" | "refresh"
5    pub iat: i64,    // issued-at
6    pub exp: i64,    // expiry
7}

The JWT is signed with HS256 (a shared secret from JWT_SECRET). The middleware verifies the signature, checks the type is "access", and reads sub — the address — which it places in the request for handlers to use.

1pub async fn require_auth(
2    State(state): State<AppState>,
3    mut req: Request,
4    next: Next,
5) -> Result<Response, Response> {
6    let header = req.headers().get(AUTHORIZATION) ... unwrap_or("");
7    let token = header.strip_prefix("Bearer ")
8        .ok_or_else(|| 401 "missing bearer token")?;
9    match verify_token(&state.cfg.jwt_secret, token, "access") {
10        Ok(sub) => { req.extensions_mut().insert(AuthedAddress(sub)); Ok(next.run(req).await) }
11        Err(_) => Err(401 "invalid or expired token"),
12    }
13}

The verification function

This one function is the heart of the auth and transaction system. It checks two things: the claimed address must be the derivation of the supplied public key, and the signature must validate under that key:

1pub fn verify_signed_by(pubkey_hex: &str, sig_hex: &str, msg: &[u8], claimed_address: &str) -> bool {
2    let pk = hex::decode(pubkey_hex)...;
3    let sig = hex::decode(sig_hex)...;
4    derive_address(&pk) == claimed_address && verify(&pk, msg, &sig)
5}

Other middleware

Where this is used

• Frontend → Sign-in page — the UI that drives steps 1–5.
• Database → auth_challenges table — where challenges live.
• Backend → Transactions — the same key signs transfers.