tools/local-dev: docker-compose stack for UI development

Adds tools/local-dev/ with postgres + redis + mailpit + backend +
gateway plus a Make wrapper, so `make -C tools/local-dev up` brings
the full authenticated stack online and `pnpm -C ui/frontend dev`
talks to it directly. The committed `.env.development` already
points at the stack and pins the matching gateway response public
key from the dev keypair under tools/local-dev/keys/.

The backend ships a new opt-in env, BACKEND_AUTH_DEV_FIXED_CODE
(`tools/local-dev/.env` defaults it to 123456). When set,
ConfirmEmailCode accepts that literal in addition to the real
bcrypt-verified code; SendEmailCode still queues a real email so
Mailpit captures the issued code at http://localhost:8025/, and
both paths coexist. The override is rejected as non-six-digit by
config validation and emits a loud warning at backend startup.

The local-dev Dockerfiles mirror backend/Dockerfile and
gateway/Dockerfile but switch the runtime stage to alpine so
docker-compose healthchecks can wget /healthz; the gateway
Dockerfile additionally copies ui/core/ into the build context
because gateway/go.mod's `replace galaxy/core => ../ui/core` is
required to compile the gateway main.

Smoke tested:
- `make -C tools/local-dev up` boots all five services to healthy.
- send-email-code + confirm-email-code with code=123456 returns a
  device_session_id; a real code in Mailpit also redeems
  successfully.
- `pnpm test` 14/14, `pnpm exec playwright test` 44/44.
- `go test ./backend/internal/config/...` green.

Docs: tools/local-dev/README.md, tools/local-dev/keys/README.md,
new "Local development stack" section in ui/docs/testing.md, and a
short pointer in ui/README.md.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

backend/internal/auth/auth.go

@@ -76,9 +76,30 @@ func NewService(deps Deps) *Service {
 		// not a security primitive, so a constant key is acceptable.
 		copy(key, []byte("galaxy-backend-auth-fallback-key"))
 	}
+	if deps.Config.DevFixedCode != "" {
+		// Loud, repeated warning so a stray production deployment cannot
+		// claim the operator was unaware. The override is intended for
+		// `tools/local-dev/` and never reaches production binaries in
+		// normal operation.
+		deps.Logger.Warn("DEV-MODE: BACKEND_AUTH_DEV_FIXED_CODE is set; ConfirmEmailCode accepts the literal code in addition to the bcrypt-verified one. NEVER use in production.")
+	}
 	return &Service{deps: deps, emailHashKey: key}
 }
 
+// devFixedCodeMatches reports whether the dev-mode fixed-code override
+// is configured and the submitted code matches it verbatim. The
+// override is opt-in via `BACKEND_AUTH_DEV_FIXED_CODE`; production
+// deployments leave the field empty and devFixedCodeMatches always
+// returns false. See `tools/local-dev/README.md` for the full
+// rationale.
+func (s *Service) devFixedCodeMatches(code string) bool {
+	fixed := s.deps.Config.DevFixedCode
+	if fixed == "" {
+		return false
+	}
+	return code == fixed
+}
+
 // hashEmail returns a stable, hex-encoded HMAC-SHA256 prefix of email
 // suitable for use in structured logs. The key is per-process so the
 // same email maps to the same hash across log lines emitted by this

backend/internal/auth/auth_e2e_test.go

@@ -185,6 +185,35 @@ func authConfig() config.AuthConfig {
 	}
 }
 
+// buildServiceWithConfig wires every dependency around db using cfg as
+// the auth configuration. Returns only the service — assertions on the
+// dev-mode override path do not inspect the recording fakes.
+func buildServiceWithConfig(t *testing.T, db *sql.DB, cfg config.AuthConfig) *auth.Service {
+	t.Helper()
+	store := auth.NewStore(db)
+	cache := auth.NewCache()
+	if err := cache.Warm(context.Background(), store); err != nil {
+		t.Fatalf("warm cache: %v", err)
+	}
+	userStore := user.NewStore(db)
+	userSvc := user.NewService(user.Deps{
+		Store:              userStore,
+		Cache:              user.NewCache(),
+		UserNameMaxRetries: 10,
+		Now:                time.Now,
+	})
+	return auth.NewService(auth.Deps{
+		Store:  store,
+		Cache:  cache,
+		User:   userSvc,
+		Geo:    newStubGeo(),
+		Mail:   newRecordingMailer(),
+		Push:   newRecordingPush(),
+		Config: cfg,
+		Now:    time.Now,
+	})
+}
+
 // buildService wires every dependency around db and returns the service
 // plus the recording fakes for assertions.
 func buildService(t *testing.T, db *sql.DB) (*auth.Service, *recordingMailer, *recordingPush, *stubGeo) {
@@ -412,6 +441,55 @@ func TestSendEmailCodeThrottleReusesChallenge(t *testing.T) {
 	}
 }
 
+func TestConfirmEmailCodeDevFixedCodeBypass(t *testing.T) {
+	db := startPostgres(t)
+	cfg := authConfig()
+	cfg.DevFixedCode = "999999"
+	svc := buildServiceWithConfig(t, db, cfg)
+	ctx := context.Background()
+
+	id, err := svc.SendEmailCode(ctx, "dev-bypass@example.test", "en", "", "")
+	if err != nil {
+		t.Fatalf("send: %v", err)
+	}
+
+	session, err := svc.ConfirmEmailCode(ctx, auth.ConfirmInputs{
+		ChallengeID:     id,
+		Code:            "999999",
+		ClientPublicKey: randomKey(t),
+		TimeZone:        "UTC",
+	})
+	if err != nil {
+		t.Fatalf("ConfirmEmailCode with dev fixed code: %v", err)
+	}
+	if session.DeviceSessionID == uuid.Nil {
+		t.Fatalf("dev fixed code did not produce a session")
+	}
+}
+
+func TestConfirmEmailCodeDevFixedCodeStillRejectsWrong(t *testing.T) {
+	db := startPostgres(t)
+	cfg := authConfig()
+	cfg.DevFixedCode = "999999"
+	svc := buildServiceWithConfig(t, db, cfg)
+	ctx := context.Background()
+
+	id, err := svc.SendEmailCode(ctx, "dev-bypass-wrong@example.test", "en", "", "")
+	if err != nil {
+		t.Fatalf("send: %v", err)
+	}
+
+	_, err = svc.ConfirmEmailCode(ctx, auth.ConfirmInputs{
+		ChallengeID:     id,
+		Code:            "111111",
+		ClientPublicKey: randomKey(t),
+		TimeZone:        "UTC",
+	})
+	if !errors.Is(err, auth.ErrCodeMismatch) {
+		t.Fatalf("ConfirmEmailCode with neither real nor dev code = %v, want ErrCodeMismatch", err)
+	}
+}
+
 func TestConfirmEmailCodeWrongCode(t *testing.T) {
 	db := startPostgres(t)
 	svc, mailer, _, _ := buildService(t, db)

backend/internal/auth/challenge.go

@@ -171,15 +171,21 @@ func (s *Service) ConfirmEmailCode(ctx context.Context, in ConfirmInputs) (Sessi
 		return Session{}, ErrTooManyAttempts
 	}
 
-	if err := verifyCode(loaded.CodeHash, in.Code); err != nil {
-		if errors.Is(err, ErrCodeMismatch) {
-			s.deps.Logger.Info("auth challenge code mismatch",
-				zap.String("challenge_id", in.ChallengeID.String()),
-				zap.Int32("attempts", loaded.Attempts),
-			)
-			return Session{}, ErrCodeMismatch
+	if !s.devFixedCodeMatches(in.Code) {
+		if err := verifyCode(loaded.CodeHash, in.Code); err != nil {
+			if errors.Is(err, ErrCodeMismatch) {
+				s.deps.Logger.Info("auth challenge code mismatch",
+					zap.String("challenge_id", in.ChallengeID.String()),
+					zap.Int32("attempts", loaded.Attempts),
+				)
+				return Session{}, ErrCodeMismatch
+			}
+			return Session{}, err
 		}
-		return Session{}, err
+	} else {
+		s.deps.Logger.Warn("auth challenge accepted via dev-mode fixed code override",
+			zap.String("challenge_id", in.ChallengeID.String()),
+		)
 	}
 
 	// Re-check permanent_block after verifying the code. SendEmailCode

backend/internal/config/config.go

@@ -71,6 +71,7 @@ const (
 	envAuthChallengeThrottleWindow = "BACKEND_AUTH_CHALLENGE_THROTTLE_WINDOW"
 	envAuthChallengeThrottleMax = "BACKEND_AUTH_CHALLENGE_THROTTLE_MAX"
 	envAuthUserNameMaxRetries = "BACKEND_AUTH_USERNAME_MAX_RETRIES"
+	envAuthDevFixedCode = "BACKEND_AUTH_DEV_FIXED_CODE"
 
 	envLobbySweeperInterval = "BACKEND_LOBBY_SWEEPER_INTERVAL"
 	envLobbyPendingRegistrationTTL = "BACKEND_LOBBY_PENDING_REGISTRATION_TTL"
@@ -293,6 +294,16 @@ type AuthConfig struct {
 	ChallengeMaxAttempts int
 	ChallengeThrottle AuthChallengeThrottleConfig
 	UserNameMaxRetries int
+
+	// DevFixedCode, when non-empty, makes ConfirmEmailCode accept this
+	// literal as a valid code in addition to the bcrypt-verified one
+	// stored on the challenge row. The override is intended for the
+	// `tools/local-dev` stack so a developer can log in without
+	// reading codes out of Mailpit. The variable MUST stay unset in
+	// production: validation requires a six-digit decimal value, and
+	// the auth service emits a loud startup warning when it picks the
+	// override up.
+	DevFixedCode string
 }
 
 // AuthChallengeThrottleConfig bounds how many un-consumed, non-expired
@@ -566,6 +577,7 @@ func LoadFromEnv() (Config, error) {
 	if cfg.Auth.UserNameMaxRetries, err = loadInt(envAuthUserNameMaxRetries, cfg.Auth.UserNameMaxRetries); err != nil {
 		return Config{}, err
 	}
+	cfg.Auth.DevFixedCode = loadString(envAuthDevFixedCode, cfg.Auth.DevFixedCode)
 
 	if cfg.Lobby.SweeperInterval, err = loadDuration(envLobbySweeperInterval, cfg.Lobby.SweeperInterval); err != nil {
 		return Config{}, err
@@ -745,6 +757,11 @@ func (c Config) Validate() error {
 	if c.Auth.UserNameMaxRetries <= 0 {
 		return fmt.Errorf("%s must be positive", envAuthUserNameMaxRetries)
 	}
+	if c.Auth.DevFixedCode != "" {
+		if !isDecimalString(c.Auth.DevFixedCode, 6) {
+			return fmt.Errorf("%s must be a six-digit decimal string when set", envAuthDevFixedCode)
+		}
+	}
 
 	if c.Lobby.SweeperInterval <= 0 {
 		return fmt.Errorf("%s must be positive", envLobbySweeperInterval)
@@ -809,6 +826,18 @@ func (c Config) Validate() error {
 	return nil
 }
 
+func isDecimalString(value string, length int) bool {
+	if len(value) != length {
+		return false
+	}
+	for _, r := range value {
+		if r < '0' || r > '9' {
+			return false
+		}
+	}
+	return true
+}
+
 func loadString(name, fallback string) string {
 	raw, ok := os.LookupEnv(name)
 	if !ok {

backend/internal/config/config_test.go

@@ -77,6 +77,40 @@ func TestValidateRejectsUnknownTracesExporter(t *testing.T) {
 	}
 }
 
+func TestLoadFromEnvAcceptsDevFixedCode(t *testing.T) {
+	env := validEnv()
+	env["BACKEND_AUTH_DEV_FIXED_CODE"] = "123456"
+	setEnv(t, env)
+
+	cfg, err := LoadFromEnv()
+	if err != nil {
+		t.Fatalf("LoadFromEnv returned error: %v", err)
+	}
+	if cfg.Auth.DevFixedCode != "123456" {
+		t.Fatalf("Auth.DevFixedCode = %q, want \"123456\"", cfg.Auth.DevFixedCode)
+	}
+}
+
+func TestValidateRejectsDevFixedCodeWrongLength(t *testing.T) {
+	env := validEnv()
+	env["BACKEND_AUTH_DEV_FIXED_CODE"] = "12345"
+	setEnv(t, env)
+
+	if _, err := LoadFromEnv(); err == nil || !strings.Contains(err.Error(), "BACKEND_AUTH_DEV_FIXED_CODE") {
+		t.Fatalf("expected DEV fixed-code length error, got %v", err)
+	}
+}
+
+func TestValidateRejectsDevFixedCodeNonDecimal(t *testing.T) {
+	env := validEnv()
+	env["BACKEND_AUTH_DEV_FIXED_CODE"] = "abcdef"
+	setEnv(t, env)
+
+	if _, err := LoadFromEnv(); err == nil || !strings.Contains(err.Error(), "BACKEND_AUTH_DEV_FIXED_CODE") {
+		t.Fatalf("expected DEV fixed-code decimal error, got %v", err)
+	}
+}
+
 func TestValidateRejectsPrometheusWithoutAddr(t *testing.T) {
 	cfg := DefaultConfig()
 	cfg.Postgres.DSN = "postgres://x:y@127.0.0.1/galaxy"