Recipe

JWT Auth

Stateless session tokens with Ed25519 signing, refresh rotation, and device fingerprint binding.

Overview

This recipe issues a short-lived access token (15 min) and a long-lived refresh token (7 days). Both are signed with Ed25519. The refresh token is bound to a hardware fingerprint hash, making token theft useless on a different machine.

Token Flow

1. Login

Client sends credentials + device fingerprint. Server validates, returns access + refresh token pair.

2. Authenticate

Access token in Authorization header. Server verifies Ed25519 signature and expiry.

3. Refresh

When access token expires, client sends refresh token. Server validates fingerprint binding, rotates both tokens.

Payload Structure

{
  "sub": "user_id",
  "iat": 1716500000,
  "exp": 1716500900,
  "jti": "random_nonce",
  "fp_hash": "sha256_of_device_fingerprint"
}

Security Notes

•Refresh tokens are single-use; each rotation invalidates the previous.
•Fingerprint binding prevents replay on a different device.
•Store refresh tokens in httpOnly, Secure, SameSite=Strict cookies.