Auth & Security · 04 Token Lifecycle

Two tokens, two jobs

The access token is used constantly and dies fast. The refresh token is used rarely and lives for days.

ONE 7-DAY SESSION

access · 15m

refresh · 7d

loginday 3day 7 → log in again

Access token

Refresh token

format

signed JWT

random 32 bytes (opaque)

lifetime

5–15 minutes

7–30 days

sent to

every API call

only /auth/refresh

checked by

signature (no DB)

lookup in Redis

revocable

not by itself

delete the key

→A stolen access token works for minutes, not days.

→The refresh token is stored server-side, so it can be revoked instantly.

Where the browser keeps them

Access token in memory, sent as a Bearer header. Refresh token in a cookie JavaScript cannot touch.

internal/auth/cookie.go

http.SetCookie(w, &http.Cookie{
    Name:     "refresh_token",
    Value:    refresh,
    Path:     "/auth/refresh", // sent nowhere else
    MaxAge:   int(refreshTTL.Seconds()),
    HttpOnly: true,  // invisible to JavaScript
    Secure:   true,  // HTTPS only
    SameSite: http.SameSiteStrictMode, // no cross-site
})

go run ./demos/04 · the response header

Set-Cookie: refresh_token=64d16837914bb63a; Path=/auth/refresh; Max-Age=604800; HttpOnly; Secure; SameSite=Strict

Threat

localStorage + Bearer

HttpOnly cookie

XSS reads it

yes — any script can

CSRF sends it

no — must be added by code

blocked by SameSite

works for mobile

yes

awkward

✓Web app: refresh in HttpOnly cookie, access in a JS variable (lost on reload → just refresh).

→Mobile / API clients: both in the Authorization header, stored in the OS keychain.

✗Never keep a refresh token in localStorage.

Rotation, reuse detection and the denylist

Every refresh swaps the old token for a new one. If an old one ever comes back, someone copied it.

internal/auth/refresh_store.go

func (s Store) Rotate(ctx context.Context,
    old string) (string, error) {
    v, err := s.rdb.GetDel(ctx, "rt:"+old).Result()
    if err == redis.Nil { // not live: reused or bogus?
        fam, _ := s.rdb.Get(ctx, "used:"+old).Result()
        if fam != "" {
            s.revokeFamily(ctx, fam)
            return "", ErrReuse
        }
        return "", ErrInvalid
    }
    if err != nil {
        return "", err // Redis down: fail closed
    }
    user, fam, _ := strings.Cut(v, "|")
    s.rdb.Set(ctx, "used:"+old, fam, refreshTTL)
    return s.Issue(ctx, user, fam), nil
}

// logout: deny this access token until it expires
s.rdb.Set(ctx, "deny:"+claims.ID, 1, time.Until(exp))

go run ./demos/04 · real Redis protocol (miniredis)

login     → refresh 64d16837…
refresh   → refresh 9848b325… <nil>
replay r1 → refresh token reused: family revoked
use r2    → refresh token invalid
jti-7f3a denied: true  ttl: 9m0s
10m later denied: false
# the denylist key expires by itself once the token would have

→GETDEL is atomic — two parallel refreshes cannot both win.

→Reuse = theft. Revoke the whole family: attacker and user are both logged out.

→Denylist TTL = time left on the token, so Redis never grows forever.

→If Redis errors, fail closed — refuse, never guess.

HANDS-ON · TOPIC 1

Stateless auth pipeline with dual tokens

POST /auth/login — bcrypt check → 15-min access JWT in the body + 7-day refresh in an HttpOnly cookie.
POST /auth/refresh — rotate the cookie, return a new access token; reuse → 401 and revoke the family.
POST /auth/logout — delete the refresh key, deny the access token's jti.
RequireAuth also rejects denied jtis.

Recap

Session 04 in four lines

1Access = short JWT, checked by signature. Refresh = long opaque token, checked in Redis.

2Refresh lives in an HttpOnly; Secure; SameSite=Strict cookie scoped to one path.

3Rotate on every refresh; a reused token revokes the whole family.

4Logout denies the access jti for exactly its remaining lifetime.