Sessions & registration — server-side state

Code

Hashing, the session store, the Manager

First the new dependency (bcrypt lives in the Go team's extended crypto):

go get golang.org/x/crypto/bcrypt

Five files, as tabs, in dependency order: 00002_sessions.sql → sessions.sql → users.sql → password.go → session.go (the table, its queries, the user queries register needs, the hasher, then the Manager that ties sessions together). Then run sqlc generate so the new queries become Go.

1. db/migrations/00002_sessions.sql — the session store. Note what's here and what isn't:

token_hash TEXT NOT NULL UNIQUE,                        -- we store the HASH, not the token
user_id    UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
expires_at TIMESTAMPTZ NOT NULL

ON DELETE CASCADE means deleting a user removes their sessions automatically. token_hash is UNIQUE (one token → one session) and, crucially, it's the hash — the raw token never touches the database.

2. internal/db/queries/sessions.sql — CreateSession, GetUserBySessionToken (a join that resolves a token straight to a user, and filters expires_at > now()), and DeleteSession (logout, next lesson). GetUserBySessionToken uses sqlc.embed(users) so it returns a whole typed User.

3. internal/db/queries/users.sql (modify) — register needs two more queries: CreateUser (insert, RETURNING *) and GetUserByEmail (the duplicate check + login, next lesson). CountUsers from lesson 3 is untouched — the diff is pure additions.

4. internal/auth/password.go — HashPassword / CheckPassword. The length cap is the interesting line:

// MaxPasswordLen guards bcrypt's 72-byte input limit so passwords are never
// silently truncated. (A byte, not a rune, but 64 chars is plenty.)
MaxPasswordLen = 64

CheckPassword uses bcrypt.CompareHashAndPassword, which is constant-time — it can't be used as a timing oracle to guess the password.

5. internal/session/session.go — the Manager: Create (mint a random token, store its hash, set the cookie), User (cookie → hash → user, or ErrNoSession), Destroy (delete the row + expire the cookie). The cookie helper is where the flags live:

HttpOnly: true,                 // JS can't read it — mitigates XSS token theft
Secure:   m.secure,             // HTTPS-only in production (cfg.IsProd())
SameSite: http.SameSiteLaxMode, // sent on top-level navigations, not cross-site POSTs

Create is used this lesson (register); User and Destroy are the machinery lesson 5 will call for login and logout — written now because they're one cohesive unit.

00002_sessions.sql CREATE

Create this file in db/migrations/

-- +goose Up
-- +goose StatementBegin
-- Server-side session store. The cookie holds an opaque random token; we store
-- only the SHA-256 hash of it, so a database leak does not hand out live
-- sessions. This is the "session in a cookie" half of the sessions-vs-JWT
-- contrast the course teaches.
CREATE TABLE sessions (
    id         UUID        PRIMARY KEY DEFAULT gen_random_uuid(),
    token_hash TEXT        NOT NULL UNIQUE,
    user_id    UUID        NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    expires_at TIMESTAMPTZ NOT NULL
);
CREATE INDEX idx_sessions_user_id ON sessions(user_id);
-- +goose StatementEnd

-- +goose Down
-- +goose StatementBegin
DROP TABLE sessions;
-- +goose StatementEnd

sessions.sql CREATE

Create this file in internal/db/queries/

-- name: CreateSession :one
INSERT INTO sessions (token_hash, user_id, expires_at)
VALUES ($1, $2, $3)
RETURNING *;

-- name: GetUserBySessionToken :one
SELECT sqlc.embed(users)
FROM users
JOIN sessions ON sessions.user_id = users.id
WHERE sessions.token_hash = $1
  AND sessions.expires_at > now();

-- name: DeleteSession :exec
DELETE FROM sessions WHERE token_hash = $1;

users.sql MODIFY 8 lines changed

Edit this file in internal/db/queries/

-- name: CountUsers :one
SELECT count(*) FROM users;

-- name: CreateUser :one
INSERT INTO users (email, password_hash)
VALUES ($1, $2)
RETURNING *;

-- name: GetUserByEmail :one
SELECT * FROM users WHERE email = $1;

password.go CREATE

Create this file in internal/auth/

// Package auth handles password hashing and credential checks.
//
// Hashing choice: bcrypt (golang.org/x/crypto/bcrypt).
//
// Why bcrypt and not argon2id? For a teaching reference app the deciding factor
// is a small, hard-to-misuse surface:
//   - One tuning knob (cost). argon2id needs three (memory, time, parallelism)
//     that you must choose, store, and keep in sync — more to get wrong.
//   - The cost is embedded in the hash string, so verification needs no external
//     parameters and rehashing on cost bumps is trivial.
//   - It ships in the Go team's golang.org/x/crypto with a decade of scrutiny.
//
// The honest tradeoff: argon2id is memory-hard and is OWASP's first
// recommendation for new systems; bcrypt is GPU-friendlier and truncates input
// at 72 bytes. We accept that by capping password length (see MaxPasswordLen) so
// nothing is silently truncated, and we document argon2id as the upgrade path.
package auth

import (
	"errors"

	"golang.org/x/crypto/bcrypt"
)

const (
	// bcryptCost of 12 is ~250ms/hash on typical 2020s hardware — a sensible
	// balance of user-facing latency and brute-force resistance.
	bcryptCost = 12

	// MinPasswordLen is a floor; NIST guidance favours length over complexity.
	MinPasswordLen = 8
	// MaxPasswordLen guards bcrypt's 72-byte input limit so passwords are never
	// silently truncated. (A byte, not a rune, but 64 chars is plenty.)
	MaxPasswordLen = 64
)

var ErrPasswordLength = errors.New("password must be between 8 and 64 characters")

// HashPassword returns a bcrypt hash suitable for storage.
func HashPassword(plain string) (string, error) {
	if len(plain) < MinPasswordLen || len(plain) > MaxPasswordLen {
		return "", ErrPasswordLength
	}
	b, err := bcrypt.GenerateFromPassword([]byte(plain), bcryptCost)
	if err != nil {
		return "", err
	}
	return string(b), nil
}

// CheckPassword reports whether plain matches the stored bcrypt hash. It runs in
// constant time relative to the hash, so it is safe against timing attacks.
func CheckPassword(hash, plain string) bool {
	return bcrypt.CompareHashAndPassword([]byte(hash), []byte(plain)) == nil
}

session.go CREATE

Create this file in internal/session/

// Package session implements server-side sessions backed by Postgres.
//
// The browser only ever holds an opaque random token in an HttpOnly cookie. The
// authoritative session lives in the `sessions` table, keyed by the SHA-256 hash
// of that token. This is the deliberate counterpoint to the Pica app's JWT: no
// claims in the token, state on the server, and revocation is a single DELETE.
package session

import (
	"context"
	"crypto/rand"
	"crypto/sha256"
	"encoding/base64"
	"encoding/hex"
	"errors"
	"net/http"
	"time"

	"github.com/jackc/pgx/v5"
	"github.com/jackc/pgx/v5/pgtype"

	"github.com/programuoki/signflow/internal/db"
)

// CookieName is the session cookie. The __Host- prefix would be even stricter
// but requires HTTPS always; we keep a plain name so dev over http works.
const CookieName = "signflow_session"

// Lifetime is how long a session (and its cookie) stays valid.
const Lifetime = 30 * 24 * time.Hour

// ErrNoSession means the request carried no valid session.
var ErrNoSession = errors.New("no session")

// Manager creates, resolves, and destroys sessions.
type Manager struct {
	q      *db.Queries
	secure bool // set Secure flag on cookies (true in production)
}

func NewManager(q *db.Queries, secure bool) *Manager {
	return &Manager{q: q, secure: secure}
}

// Create issues a new session for userID and writes the cookie.
func (m *Manager) Create(ctx context.Context, w http.ResponseWriter, userID pgtype.UUID) error {
	token, err := randomToken()
	if err != nil {
		return err
	}
	expires := time.Now().Add(Lifetime)
	if _, err := m.q.CreateSession(ctx, db.CreateSessionParams{
		TokenHash: hashToken(token),
		UserID:    userID,
		ExpiresAt: pgtype.Timestamptz{Time: expires, Valid: true},
	}); err != nil {
		return err
	}
	http.SetCookie(w, m.cookie(token, expires))
	return nil
}

// User resolves the current user from the request's session cookie. It returns
// ErrNoSession when there is no cookie or the session is expired/unknown.
func (m *Manager) User(ctx context.Context, r *http.Request) (db.User, error) {
	c, err := r.Cookie(CookieName)
	if err != nil || c.Value == "" {
		return db.User{}, ErrNoSession
	}
	row, err := m.q.GetUserBySessionToken(ctx, hashToken(c.Value))
	if errors.Is(err, pgx.ErrNoRows) {
		return db.User{}, ErrNoSession
	}
	if err != nil {
		return db.User{}, err
	}
	return row.User, nil
}

// Destroy deletes the current session server-side and clears the cookie.
func (m *Manager) Destroy(ctx context.Context, w http.ResponseWriter, r *http.Request) error {
	if c, err := r.Cookie(CookieName); err == nil && c.Value != "" {
		if err := m.q.DeleteSession(ctx, hashToken(c.Value)); err != nil {
			return err
		}
	}
	// Expire the cookie in the browser.
	http.SetCookie(w, m.cookie("", time.Unix(0, 0)))
	return nil
}

// cookie builds the session cookie with security flags applied.
func (m *Manager) cookie(value string, expires time.Time) *http.Cookie {
	return &http.Cookie{
		Name:     CookieName,
		Value:    value,
		Path:     "/",
		Expires:  expires,
		HttpOnly: true,                 // JS can't read it — mitigates XSS token theft
		Secure:   m.secure,             // HTTPS-only in production
		SameSite: http.SameSiteLaxMode, // sent on top-level navigations, not cross-site POSTs
	}
}

// randomToken returns 32 bytes of CSPRNG entropy, URL-safe base64 encoded.
func randomToken() (string, error) {
	b := make([]byte, 32)
	if _, err := rand.Read(b); err != nil {
		return "", err
	}
	return base64.RawURLEncoding.EncodeToString(b), nil
}

// hashToken is what we actually store/look up, so a DB dump reveals no usable
// session tokens.
func hashToken(token string) string {
	sum := sha256.Sum256([]byte(token))
	return hex.EncodeToString(sum[:])
}