@johnnyboy11234/esg-idea-contest 0.2.4 → 0.3.1

package/backend/internal/auth/login_throttle_audit_integration_test.go

@@ -0,0 +1,88 @@
+//go:build integration
+
+package auth_test
+
+import (
+	"strconv"
+	"testing"
+)
+
+func (e loginEnv) throttledRows(t *testing.T) int {
+	t.Helper()
+	n := 0
+	for _, r := range e.audits(t) {
+		if r.Outcome == "THROTTLED" {
+			n++
+		}
+	}
+	return n
+}
+
+// A locked key answers 429 every time but is audited once per lock.
+func TestLoginKeyLockAuditedOncePerWindow(t *testing.T) {
+	e := newLockEnv(t)
+	e.addUser(t, "123456", "USER", true)
+	for range 5 {
+		e.fail(t, "123456")
+	}
+	for i := range 4 {
+		if rec := e.login(t, creds("123456", password)); rec.Code != 429 {
+			t.Fatalf("attempt %d: %d", i, rec.Code)
+		}
+	}
+	if n := e.throttledRows(t); n != 1 {
+		t.Fatalf("THROTTLED rows in one lock = %d, want 1", n)
+	}
+	// Another key is its own window.
+	for range 5 {
+		e.fail(t, "654321")
+	}
+	e.login(t, creds("654321", wrongPassword))
+	if n := e.throttledRows(t); n != 2 {
+		t.Fatalf("THROTTLED rows for two keys = %d, want 2", n)
+	}
+	// After the lock expires and the key locks again, a new window is audited.
+	e.ageLock(t, "123456", 16)
+	if _, err := e.db.Exec(`UPDATE login_throttle_audit SET audited_until = audited_until - INTERVAL 16 MINUTE`); err != nil {
+		t.Fatal(err)
+	}
+	for range 5 {
+		e.fail(t, "123456")
+	}
+	e.login(t, creds("123456", wrongPassword))
+	e.login(t, creds("123456", wrongPassword))
+	if n := e.throttledRows(t); n != 3 {
+		t.Fatalf("THROTTLED rows after second lock = %d, want 3", n)
+	}
+}
+
+// The IP limit is audited once per window too, and a different key from the
+// same address does not add a row.
+func TestLoginIPLimitAuditedOncePerWindow(t *testing.T) {
+	e := newLockEnv(t)
+	e.seed(t, "192.0.2.9", 30, 0)
+	for _, k := range []string{"111111", "222222", "333333"} {
+		if rec := e.loginFrom(t, "192.0.2.9", k, wrongPassword, nil); rec.Code != 429 {
+			t.Fatalf("%s: %d", k, rec.Code)
+		}
+	}
+	if n := e.throttledRows(t); n != 1 {
+		t.Fatalf("THROTTLED rows = %d, want 1", n)
+	}
+}
+
+// Both limits at once: the larger Retry-After, and a new window on either side is audited.
+func TestLoginBothLimitsLargerRetryAfter(t *testing.T) {
+	e := newLockEnv(t)
+	for range 5 {
+		e.fail(t, "123456")
+	}
+	e.seed(t, "192.0.2.9", 30, 10*60) // IP frees in ~5 min, key lock holds ~15 min
+	rec := e.login(t, creds("123456", wrongPassword))
+	if got, _ := strconv.Atoi(rec.Header().Get("Retry-After")); rec.Code != 429 || got < 890 || got > 900 {
+		t.Fatalf("%d Retry-After=%q, want ~900", rec.Code, rec.Header().Get("Retry-After"))
+	}
+	if n := e.throttledRows(t); n != 1 {
+		t.Fatalf("THROTTLED rows = %d, want 1", n)
+	}
+}

package/backend/internal/auth/purge.go

@@ -0,0 +1,93 @@
+package auth
+
+import (
+	"context"
+	"database/sql"
+	"log/slog"
+	"time"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/auth/internal/store"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/db"
+)
+
+// Purge schedule (B1b-07). Expired rows already fail every check, so the purge
+// only bounds table size; a few minutes of delay change nothing.
+const (
+	PurgeInterval = 5 * time.Minute
+	PurgeJitter   = time.Minute
+	purgeBatch    = 1000
+)
+
+// Purger deletes dead rows of the session and throttle tables: expired
+// sessions, login_lock rows without an active lock whose last failure left the
+// window, login_attempt rows outside the IP window and expired
+// login_throttle_audit claims. Each DELETE removes at most Batch rows, so row
+// locks are held briefly, and repeats until a short batch.
+//
+// Every replica runs its own Purger and no leader is elected. That is safe:
+// each condition only matches rows that every reader already ignores, a
+// DELETE of a row that is already gone affects nothing, and two runners on the
+// same rows only wait for each other's row locks. A deadlock or lock-wait
+// timeout ends that table's turn without an error; the next run continues.
+type Purger struct {
+	DB    *sql.DB
+	Log   *slog.Logger
+	Batch int // rows per DELETE; 0 means 1000
+}
+
+// Purge runs one pass over all four tables. The returned error is the first
+// non-contention database error; the remaining tables are still purged.
+func (p Purger) Purge(ctx context.Context) error {
+	batch := p.Batch
+	if batch <= 0 {
+		batch = purgeBatch
+	}
+	tables := []struct {
+		name string
+		del  func(context.Context, *sql.DB, int) (int64, error)
+	}{
+		{"session", func(c context.Context, d *sql.DB, n int) (int64, error) { return store.DeleteExpired(c, d, limits, n) }},
+		{"login_lock", func(c context.Context, d *sql.DB, n int) (int64, error) {
+			return store.DeleteStaleLocks(c, d, lockPolicy, n)
+		}},
+		{"login_attempt", func(c context.Context, d *sql.DB, n int) (int64, error) {
+			return store.DeleteOldAttempts(c, d, ipPolicy, n)
+		}},
+		{"login_throttle_audit", store.DeleteExpiredThrottleAudits},
+	}
+	var first error
+	for _, t := range tables {
+		n, err := drain(ctx, p.DB, batch, t.del)
+		if ctx.Err() != nil {
+			return ctx.Err() // shutdown; not a failure
+		}
+		switch {
+		case err != nil && db.IsContention(err):
+			p.Log.Info("purge yielded to another runner", "table", t.name, "deleted", n)
+		case err != nil:
+			p.Log.Warn("purge failed", "table", t.name, "deleted", n, "error", err.Error())
+			if first == nil {
+				first = err
+			}
+		case n > 0:
+			p.Log.Info("purged", "table", t.name, "deleted", n)
+		}
+	}
+	return first
+}
+
+// drain repeats del until it deletes fewer than batch rows and returns the
+// total.
+func drain(ctx context.Context, d *sql.DB, batch int, del func(context.Context, *sql.DB, int) (int64, error)) (int64, error) {
+	var total int64
+	for {
+		n, err := del(ctx, d, batch)
+		total += n
+		if err != nil || n < int64(batch) {
+			return total, err
+		}
+		if err := ctx.Err(); err != nil {
+			return total, err
+		}
+	}
+}

package/backend/internal/auth/purge_integration_test.go

@@ -0,0 +1,220 @@
+//go:build integration
+
+package auth_test
+
+import (
+	"bytes"
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"log/slog"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/auth"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/dbtest"
+)
+
+// purgeFixture seeds every purged table with rows that must stay and rows that
+// must go. Each "dead" group is larger than the batch size so the drain loop
+// runs several DELETEs.
+type purgeFixture struct {
+	liveSessions []string
+	deadSessions int
+}
+
+func seedPurge(t *testing.T, db *sql.DB, s *auth.Sessions) purgeFixture {
+	t.Helper()
+	ctx := context.Background()
+	exec := func(q string, args ...any) {
+		t.Helper()
+		if _, err := db.Exec(q, args...); err != nil {
+			t.Fatalf("%s: %v", q, err)
+		}
+	}
+	var f purgeFixture
+	u := addUser(t, db, "200001", "USER", true)
+	for i := range 3 {
+		id, err := s.Create(ctx, u)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if i == 0 { // inside both timeouts, but close to both
+			age(t, db, id, 7*time.Hour+50*time.Minute, 29*time.Minute)
+		}
+		f.liveSessions = append(f.liveSessions, id)
+	}
+	for i := range 7 {
+		id, err := s.Create(ctx, u)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if i%2 == 0 {
+			age(t, db, id, time.Hour, 31*time.Minute) // idle timeout
+		} else {
+			age(t, db, id, 8*time.Hour+time.Minute, 0) // absolute timeout
+		}
+		f.deadSessions++
+	}
+
+	lock := func(key string, lastFailAgo time.Duration, lockedUntil string) {
+		exec(`INSERT INTO login_lock (lock_key, fail_count, last_fail_at, locked_until)
+		      VALUES (?, 5, NOW(6) - INTERVAL ? SECOND, `+lockedUntil+`)`, key, int(lastFailAgo.Seconds()))
+	}
+	lock("keep-recent", time.Minute, "NULL")                              // counting window still open
+	lock("keep-locked", 20*time.Minute, "NOW(6) + INTERVAL 5 MINUTE")     // lock active
+	lock("keep-just-unlocked", time.Minute, "NOW(6) - INTERVAL 1 SECOND") // window still open
+	for i := range 5 {
+		lock(fmt.Sprintf("dead-stale-%d", i), 16*time.Minute, "NULL")
+		lock(fmt.Sprintf("dead-unlocked-%d", i), 31*time.Minute, "NOW(6) - INTERVAL 1 MINUTE")
+	}
+
+	for range 4 {
+		exec(`INSERT INTO login_attempt (ip, attempted_at) VALUES ('192.0.2.1', NOW(6) - INTERVAL 14 MINUTE)`)
+	}
+	for range 9 {
+		exec(`INSERT INTO login_attempt (ip, attempted_at) VALUES ('192.0.2.2', NOW(6) - INTERVAL 901 SECOND)`)
+	}
+
+	exec(`INSERT INTO login_throttle_audit VALUES ('ip', 'keep', NOW(6) + INTERVAL 1 MINUTE)`)
+	for i := range 5 {
+		exec(`INSERT INTO login_throttle_audit VALUES ('key', ?, NOW(6) - INTERVAL 1 SECOND)`, fmt.Sprintf("dead-%d", i))
+	}
+	return f
+}
+
+func count(t *testing.T, db *sql.DB, q string) (n int) {
+	t.Helper()
+	if err := db.QueryRow(q).Scan(&n); err != nil {
+		t.Fatalf("%s: %v", q, err)
+	}
+	return n
+}
+
+func assertPurged(t *testing.T, db *sql.DB, s *auth.Sessions, f purgeFixture) {
+	t.Helper()
+	if n := count(t, db, `SELECT COUNT(*) FROM session`); n != len(f.liveSessions) {
+		t.Errorf("sessions = %d, want %d", n, len(f.liveSessions))
+	}
+	for _, id := range f.liveSessions {
+		if _, ok, err := s.Validate(context.Background(), id); err != nil || !ok {
+			t.Errorf("live session lost: %v", err)
+		}
+	}
+	rows, err := db.Query(`SELECT lock_key FROM login_lock ORDER BY lock_key`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = rows.Close() }()
+	var keys []string
+	for rows.Next() {
+		var k string
+		if err := rows.Scan(&k); err != nil {
+			t.Fatal(err)
+		}
+		keys = append(keys, k)
+	}
+	if got := strings.Join(keys, ","); got != "keep-just-unlocked,keep-locked,keep-recent" {
+		t.Errorf("login_lock keys = %s", got)
+	}
+	if n := count(t, db, `SELECT COUNT(*) FROM login_attempt WHERE ip = '192.0.2.1'`); n != 4 {
+		t.Errorf("attempts inside window = %d, want 4", n)
+	}
+	if n := count(t, db, `SELECT COUNT(*) FROM login_attempt WHERE ip = '192.0.2.2'`); n != 0 {
+		t.Errorf("attempts outside window = %d, want 0", n)
+	}
+	if n := count(t, db, `SELECT COUNT(*) FROM login_throttle_audit WHERE subject = 'keep'`); n != 1 {
+		t.Errorf("active throttle claim lost")
+	}
+	if n := count(t, db, `SELECT COUNT(*) FROM login_throttle_audit`); n != 1 {
+		t.Errorf("throttle claims = %d, want 1", n)
+	}
+}
+
+func TestPurgeDeletesDeadRowsOnly(t *testing.T) {
+	db := dbtest.New(t)
+	s := auth.New(db)
+	f := seedPurge(t, db, s)
+	var buf bytes.Buffer
+	p := auth.Purger{DB: db, Log: slog.New(slog.NewTextHandler(&buf, nil)), Batch: 2}
+	if err := p.Purge(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	assertPurged(t, db, s, f)
+	for _, want := range []string{
+		"table=session deleted=7", "table=login_lock deleted=10",
+		"table=login_attempt deleted=9", "table=login_throttle_audit deleted=5",
+	} {
+		if !strings.Contains(buf.String(), want) {
+			t.Errorf("log lacks %q: %s", want, buf.String())
+		}
+	}
+
+	// Idempotent: a second pass finds nothing and logs nothing.
+	buf.Reset()
+	if err := p.Purge(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	assertPurged(t, db, s, f)
+	if buf.Len() != 0 {
+		t.Errorf("second pass logged: %s", buf.String())
+	}
+}
+
+// Every replica runs the purge with no leader. Several runners on the same
+// rows must neither fail nor delete a row that is still live.
+func TestPurgeConcurrentRunnersDoNotConflict(t *testing.T) {
+	db := dbtest.New(t)
+	s := auth.New(db)
+	f := seedPurge(t, db, s)
+	const runners = 4
+	var wg sync.WaitGroup
+	errs := make(chan error, runners)
+	start := make(chan struct{})
+	for range runners {
+		wg.Go(func() {
+			<-start
+			p := auth.Purger{DB: db, Log: slog.New(slog.DiscardHandler), Batch: 1}
+			errs <- p.Purge(context.Background())
+		})
+	}
+	close(start)
+	wg.Wait()
+	close(errs)
+	for err := range errs {
+		if err != nil {
+			t.Errorf("runner failed: %v", err)
+		}
+	}
+	assertPurged(t, db, s, f)
+}
+
+func TestPurgeStopsOnCancel(t *testing.T) {
+	db := dbtest.New(t)
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	if err := (auth.Purger{DB: db, Log: slog.New(slog.DiscardHandler)}).Purge(ctx); !errors.Is(err, context.Canceled) {
+		t.Fatalf("err = %v, want context.Canceled", err)
+	}
+}
+
+// A database error on one table is returned, but the other tables still get
+// their turn and each failure is logged.
+func TestPurgeReportsDatabaseErrors(t *testing.T) {
+	db, err := sql.Open("mysql", dbtest.DSN("127.0.0.1:1"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	_ = db.Close()
+	var buf bytes.Buffer
+	err = (auth.Purger{DB: db, Log: slog.New(slog.NewTextHandler(&buf, nil))}).Purge(context.Background())
+	if err == nil || !strings.Contains(err.Error(), "purge sessions") {
+		t.Fatalf("err = %v", err)
+	}
+	if n := strings.Count(buf.String(), "purge failed"); n != 4 {
+		t.Errorf("logged %d failures, want 4: %s", n, buf.String())
+	}
+}

package/backend/internal/auth/purge_test.go

@@ -0,0 +1,51 @@
+package auth
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"testing"
+)
+
+func TestDrainRepeatsUntilShortBatch(t *testing.T) {
+	batches := []int64{3, 3, 1, 99}
+	var calls int
+	n, err := drain(context.Background(), nil, 3, func(_ context.Context, _ *sql.DB, limit int) (int64, error) {
+		if limit != 3 {
+			t.Fatalf("limit = %d", limit)
+		}
+		calls++
+		return batches[calls-1], nil
+	})
+	if err != nil || n != 7 || calls != 3 {
+		t.Fatalf("drain = %d, %v after %d calls; want 7 after 3", n, err, calls)
+	}
+}
+
+func TestDrainStopsOnError(t *testing.T) {
+	boom := errors.New("boom")
+	var calls int
+	n, err := drain(context.Background(), nil, 2, func(context.Context, *sql.DB, int) (int64, error) {
+		calls++
+		if calls == 2 {
+			return 0, boom
+		}
+		return 2, nil
+	})
+	if !errors.Is(err, boom) || n != 2 || calls != 2 {
+		t.Fatalf("drain = %d, %v after %d calls", n, err, calls)
+	}
+}
+
+func TestDrainStopsOnCancel(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	var calls int
+	n, err := drain(ctx, nil, 1, func(context.Context, *sql.DB, int) (int64, error) {
+		calls++
+		cancel()
+		return 1, nil
+	})
+	if !errors.Is(err, context.Canceled) || n != 1 || calls != 1 {
+		t.Fatalf("drain = %d, %v after %d calls", n, err, calls)
+	}
+}

package/backend/internal/auth/session.go

@@ -106,12 +106,6 @@ func (s *Sessions) RevokeAll(ctx context.Context, userID uuid.UUID) error {
 	return store.DeleteByUser(ctx, s.DB, userID)
 }
 
-// Purge deletes expired sessions and returns how many; a background ticker
-// calls it. Validation never depends on it: expired rows already fail Touch.
-func (s *Sessions) Purge(ctx context.Context) (int64, error) {
-	return store.DeleteExpired(ctx, s.DB, limits)
-}
-
 // Binding returns SHA-256 of the session ID, the value the CSRF token is bound
 // to (D40). ok is false for a malformed ID.
 func Binding(id string) (b []byte, ok bool) { return parse(id) }

package/backend/internal/auth/session_integration_test.go

@@ -7,6 +7,7 @@ import (
 	"crypto/sha256"
 	"database/sql"
 	"encoding/base64"
+	"log/slog"
 	"testing"
 	"time"
 
@@ -216,9 +217,8 @@ func TestSessions(t *testing.T) {
 		live, idle, old := create(t, u), create(t, u), create(t, u)
 		age(t, db, idle, time.Hour, time.Hour)
 		age(t, db, old, 9*time.Hour, 0)
-		n, err := s.Purge(ctx)
-		if err != nil || n < 2 {
-			t.Fatalf("purged %d, %v; want at least 2", n, err)
+		if err := (auth.Purger{DB: db, Log: slog.New(slog.DiscardHandler)}).Purge(ctx); err != nil {
+			t.Fatal(err)
 		}
 		if !valid(t, live) {
 			t.Fatal("live session purged")

package/backend/internal/auth/throttle.go

@@ -0,0 +1,122 @@
+package auth
+
+import (
+	"context"
+	"database/sql"
+	"net/netip"
+	"strings"
+	"time"
+	"unicode"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/auth/internal/store"
+)
+
+const (
+	loginMaxFailures = 5
+	loginWindow      = 15 * time.Minute
+	loginLockFor     = 15 * time.Minute
+	loginKeyMax      = 32
+
+	ipMaxFailures = 30
+	ipWindow      = 15 * time.Minute
+)
+
+// DBThrottle is the Throttle over the login_lock table: 5 consecutive
+// failures, each within 15 minutes of the previous one, lock the submitted
+// employee-ID string for a fixed 15 minutes (PRD §6.5, OI-12). The 5th failure
+// still answers 401; the lock shows from the 6th attempt. The counters live in
+// MariaDB so all replicas share them, and every time is database time.
+//
+// It also applies the per-IP limit: 30 failures from one address inside a
+// sliding 15-minute window answer 429 until the 30th newest failure leaves the
+// window (login_attempt). A throttled attempt is neither counted for the key
+// nor for the IP. An invalid (zero) ip skips the IP window.
+type DBThrottle struct{ DB *sql.DB }
+
+var lockPolicy = store.LockPolicy{
+	MaxFailures:   loginMaxFailures,
+	WindowSeconds: int(loginWindow / time.Second),
+	LockSeconds:   int(loginLockFor / time.Second),
+}
+
+var ipPolicy = store.IPPolicy{MaxFailures: ipMaxFailures, WindowSeconds: int(ipWindow / time.Second)}
+
+// LockKey normalises the submitted employee-ID string: control characters are
+// removed and the rest is cut to 32 characters.
+func LockKey(s string) string {
+	s = strings.Map(func(r rune) rune {
+		if unicode.IsControl(r) {
+			return -1
+		}
+		return r
+	}, s)
+	if r := []rune(s); len(r) > loginKeyMax {
+		s = string(r[:loginKeyMax])
+	}
+	return s
+}
+
+// Check implements Throttle. Both limits apply; the longer wait is returned.
+func (t DBThrottle) Check(ctx context.Context, key string, ip netip.Addr) (time.Duration, error) {
+	keyWait, err := store.LockRemaining(ctx, t.DB, LockKey(key))
+	if err != nil {
+		return 0, err
+	}
+	if !ip.IsValid() {
+		return keyWait, nil
+	}
+	ipWait, err := store.IPRetryAfter(ctx, t.DB, ipString(ip), ipPolicy)
+	if err != nil {
+		return 0, err
+	}
+	return max(keyWait, ipWait), nil
+}
+
+// AuditOnce implements Throttle: the first throttled attempt of a lock or IP
+// window claims the audit row; later ones in the same window do not. When both
+// limits apply, the attempt is audited if either window is new.
+func (t DBThrottle) AuditOnce(ctx context.Context, key string, ip netip.Addr) (bool, error) {
+	var first bool
+	if wait, err := store.LockRemaining(ctx, t.DB, LockKey(key)); err != nil {
+		return false, err
+	} else if wait > 0 {
+		won, err := store.ClaimThrottleAudit(ctx, t.DB, "key", LockKey(key), wait)
+		if err != nil {
+			return false, err
+		}
+		first = first || won
+	}
+	if ip.IsValid() {
+		wait, err := store.IPRetryAfter(ctx, t.DB, ipString(ip), ipPolicy)
+		if err != nil {
+			return false, err
+		}
+		if wait > 0 {
+			won, err := store.ClaimThrottleAudit(ctx, t.DB, "ip", ipString(ip), wait)
+			if err != nil {
+				return false, err
+			}
+			first = first || won
+		}
+	}
+	return first, nil
+}
+
+// Fail implements Throttle.
+func (t DBThrottle) Fail(ctx context.Context, key string, ip netip.Addr) error {
+	if err := store.RecordFailure(ctx, t.DB, LockKey(key), lockPolicy); err != nil {
+		return err
+	}
+	if !ip.IsValid() {
+		return nil
+	}
+	return store.RecordIPFailure(ctx, t.DB, ipString(ip))
+}
+
+// Succeed implements Throttle. The IP window is not cleared: its failures stay
+// until they leave the window.
+func (t DBThrottle) Succeed(ctx context.Context, key string) error {
+	return store.ClearFailures(ctx, t.DB, LockKey(key))
+}
+
+func ipString(ip netip.Addr) string { return ip.Unmap().WithZone("").String() }

package/backend/internal/deadline/gate.go

@@ -0,0 +1,80 @@
+package deadline
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/security"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/web"
+)
+
+// SubmissionGate is the one place that decides whether a state-limited write
+// may proceed (PRD 5, D34, OI-18).
+type SubmissionGate interface {
+	// Precheck is read-only. It runs before the request body is read, to keep
+	// the error precedence of PRD 6.1, and never replaces AssertOpenInTx.
+	Precheck(ctx context.Context, actor security.Principal) error
+	// AssertOpenInTx is the authoritative check. The tx parameter makes it
+	// impossible to call outside a write transaction (ADR G9).
+	AssertOpenInTx(ctx context.Context, tx *sql.Tx, actor security.Principal) error
+}
+
+// Gate implements SubmissionGate. Admins are exempt (PRD 5, OI-18).
+type Gate struct{ Store Store }
+
+var _ SubmissionGate = Gate{}
+
+// Precheck reads the deadline outside any transaction.
+func (g Gate) Precheck(ctx context.Context, actor security.Principal) error {
+	if actor.IsAdmin() {
+		return nil
+	}
+	snap, err := g.Store.Snapshot(ctx)
+	if err != nil {
+		return err
+	}
+	return check(snap.State())
+}
+
+// AssertOpenInTx reads the deadline and NOW(6) in one statement on tx, without
+// a lock (PRD 5): a write racing a deadline change may land on either side.
+func (g Gate) AssertOpenInTx(ctx context.Context, tx *sql.Tx, actor security.Principal) error {
+	if actor.IsAdmin() {
+		return nil
+	}
+	snap, err := TxStore{Tx: tx}.Snapshot(ctx)
+	if err != nil {
+		return err
+	}
+	return check(snap.State())
+}
+
+// TxStore reads the deadline through an open transaction.
+type TxStore struct{ Tx *sql.Tx }
+
+// Snapshot returns the deadline and NOW(6) from one statement.
+func (s TxStore) Snapshot(ctx context.Context) (Snapshot, error) {
+	var snap Snapshot
+	var d sql.NullTime
+	err := s.Tx.QueryRowContext(ctx, `SELECT deadline, NOW(6) FROM contest_setting WHERE id = 1`).Scan(&d, &snap.Now)
+	if err != nil {
+		return Snapshot{}, fmt.Errorf("read contest_setting: %w", err)
+	}
+	if d.Valid {
+		snap.Deadline = &d.Time
+	}
+	return snap, nil
+}
+
+// check maps a state to the 403 a User write gets in it.
+func check(s State) error {
+	switch s {
+	case "OPEN":
+		return nil
+	case "NOT_OPEN":
+		return web.NewError(web.CodeSubmissionNotOpen, "submissions are not open yet")
+	default:
+		return web.NewError(web.CodeSubmissionClosed, "the submission deadline has passed")
+	}
+}