feat: implement Tier 3 utility IRC commands

Implement all 7 utility IRC commands from issue #87:

User commands:
- USERHOST: quick lookup of user@host for up to 5 nicks (RPL 302)
- VERSION: server version string using globals.Version (RPL 351)
- ADMIN: server admin contact info (RPL 256-259)
- INFO: server software info text (RPL 371/374)
- TIME: server local time in RFC format (RPL 391)

Oper commands:
- KILL: forcibly disconnect a user (requires is_oper), broadcasts
  QUIT to all shared channels, cleans up sessions
- WALLOPS: broadcast message to all users with +w usermode
  (requires is_oper)

Supporting changes:
- Add is_wallops column to sessions table in 001_initial.sql
- Add user mode +w tracking via MODE nick +w/-w
- User mode queries now return actual modes (+o, +w)
- MODE -o allows de-opering yourself; MODE +o rejected
- MODE for other users returns ERR_USERSDONTMATCH (502)
- Extract dispatch helpers to reduce dispatchCommand complexity

Tests cover all commands including error cases, oper checks,
user mode set/unset, KILL broadcast, WALLOPS delivery, and
edge cases (self-kill, nonexistent users, missing params).

closes #87

README.md

@@ -1079,8 +1079,8 @@ the server to the client (never C2S) and use 3-digit string codes in the
 | `001` | RPL_WELCOME         | After session creation | `{"command":"001","to":"alice","body":["Welcome to the network, alice"]}` |
 | `002` | RPL_YOURHOST        | After session creation | `{"command":"002","to":"alice","body":["Your host is neoirc, running version 0.1"]}` |
 | `003` | RPL_CREATED         | After session creation | `{"command":"003","to":"alice","body":["This server was created 2026-02-10"]}` |
-| `004` | RPL_MYINFO          | After session creation | `{"command":"004","to":"alice","params":["neoirc","0.1","","mnst"]}` |
+| `004` | RPL_MYINFO          | After session creation | `{"command":"004","to":"alice","params":["neoirc","0.1","","ikmnostl"]}` |
-| `005` | RPL_ISUPPORT        | After session creation | `{"command":"005","to":"alice","params":["CHANTYPES=#","NICKLEN=32","PREFIX=(ov)@+","CHANMODES=,,H,mnst","NETWORK=neoirc"],"body":["are supported by this server"]}` |
+| `005` | RPL_ISUPPORT        | After session creation | `{"command":"005","to":"alice","params":["CHANTYPES=#","NICKLEN=32","PREFIX=(ov)@+","CHANMODES=b,k,Hl,imnst","NETWORK=neoirc"],"body":["are supported by this server"]}` |
 | `221` | RPL_UMODEIS         | In response to user MODE query | `{"command":"221","to":"alice","body":["+"]}` |
 | `251` | RPL_LUSERCLIENT     | On connect or LUSERS command | `{"command":"251","to":"alice","body":["There are 5 users and 0 invisible on 1 servers"]}` |
 | `252` | RPL_LUSEROP         | On connect or LUSERS command | `{"command":"252","to":"alice","params":["0"],"body":["operator(s) online"]}` |
@@ -1128,12 +1128,15 @@ Inspired by IRC, simplified:
 
 | Mode | Name           | Meaning | Status |
 |------|----------------|---------|--------|
+| `+b` | Ban            | Prevents matching hostmasks from joining or sending (parameter: `nick!user@host` mask with wildcards) | **Enforced** |
+| `+i` | Invite-only    | Only invited users can join; use `INVITE nick #channel` to invite | **Enforced** |
+| `+k` | Channel key    | Requires a password to join (parameter: key string) | **Enforced** |
+| `+l` | User limit     | Maximum number of members allowed in the channel (parameter: integer) | **Enforced** |
 | `+m` | Moderated      | Only voiced (`+v`) users and operators (`+o`) can send | **Enforced** |
-| `+t` | Topic lock     | Only operators can change the topic (default: ON) | **Enforced** |
 | `+n` | No external    | Only channel members can send messages to the channel | **Enforced** |
+| `+s` | Secret         | Channel hidden from LIST and WHOIS for non-members | **Enforced** |
+| `+t` | Topic lock     | Only operators can change the topic (default: ON) | **Enforced** |
 | `+H` | Hashcash       | Requires proof-of-work for PRIVMSG (parameter: bits, e.g. `+H 20`) | **Enforced** |
-| `+i` | Invite-only    | Only invited users can join | Not yet enforced |
-| `+s` | Secret         | Channel hidden from LIST response | Not yet enforced |
 
 **User channel modes (set per-user per-channel):**
 
@@ -1145,6 +1148,42 @@ Inspired by IRC, simplified:
 **Channel creator auto-op:** The first user to JOIN a channel (creating it)
 automatically receives `+o` operator status.
 
+**Ban system (+b):** Operators can ban users by hostmask pattern with wildcard
+matching (`*` and `?`). `MODE #channel +b` with no argument lists current bans.
+Bans prevent both joining and sending messages.
+
+```
+MODE #channel +b *!*@*.example.com   — ban all users from example.com
+MODE #channel -b *!*@*.example.com   — remove the ban
+MODE #channel +b                     — list all bans (RPL_BANLIST 367/368)
+```
+
+**Invite-only (+i):** When set, users must be invited by an operator before
+joining. The `INVITE` command records an invite that is consumed on JOIN.
+
+```
+MODE #channel +i                     — set invite-only
+INVITE nick #channel                 — invite a user (operator only on +i channels)
+```
+
+**Channel key (+k):** Requires a password to join the channel.
+
+```
+MODE #channel +k secretpass          — set a channel key
+MODE #channel -k *                   — remove the key
+JOIN #channel secretpass             — join with key
+```
+
+**User limit (+l):** Caps the number of members in the channel.
+
+```
+MODE #channel +l 50                  — set limit to 50 members
+MODE #channel -l                     — remove the limit
+```
+
+**Secret (+s):** Hides the channel from `LIST` for non-members and from
+`WHOIS` channel lists when the querier is not in the same channel.
+
 **KICK command:** Channel operators can remove users with `KICK #channel nick
 [:reason]`. The kicked user and all channel members receive the KICK message.
 
@@ -1153,7 +1192,7 @@ RPL_AWAY), and skips hashcash validation on +H channels (servers and services
 use NOTICE).
 
 **ISUPPORT:** The server advertises `PREFIX=(ov)@+` and
-`CHANMODES=,,H,mnst` in RPL_ISUPPORT (005).
+`CHANMODES=b,k,Hl,imnst` in RPL_ISUPPORT (005).
 
 ### Per-Channel Hashcash (Anti-Spam)
 
@@ -2695,7 +2734,7 @@ guess is borne by the server (bcrypt), not the client.
 - [x] **Client output queue pruning** — delete old client output queue entries per `QUEUE_MAX_AGE`
 - [x] **Message rotation** — prune messages older than `MESSAGE_MAX_AGE`
 - [x] **Channel modes** — enforce `+m` (moderated), `+t` (topic lock), `+n` (no external)
-- [ ] **Channel modes (tier 2)** — enforce `+i` (invite-only), `+s` (secret), `+b` (ban), `+k` (key), `+l` (limit)
+- [x] **Channel modes (tier 2)** — enforce `+i` (invite-only), `+s` (secret), `+b` (ban), `+k` (key), `+l` (limit)
 - [x] **User channel modes** — `+o` (operator), `+v` (voice) with NAMES prefixes
 - [x] **KICK command** — operator-only channel kick with broadcast
 - [x] **MODE command** — query and set channel/user modes

internal/db/queries.go

@@ -9,6 +9,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"strconv"
+	"strings"
 	"time"
 
 	"git.eeqj.de/sneak/neoirc/pkg/irc"
@@ -1835,3 +1836,663 @@ func (database *Database) PruneSpentHashcash(
 
 	return deleted, nil
 }
+
+// --- Tier 2: Ban system (+b) ---
+
+// BanInfo represents a channel ban entry.
+type BanInfo struct {
+	Mask      string
+	SetBy     string
+	CreatedAt time.Time
+}
+
+// AddChannelBan inserts a ban mask for a channel.
+func (database *Database) AddChannelBan(
+	ctx context.Context,
+	channelID int64,
+	mask, setBy string,
+) error {
+	_, err := database.conn.ExecContext(ctx,
+		`INSERT OR IGNORE INTO channel_bans
+		 (channel_id, mask, set_by, created_at)
+		 VALUES (?, ?, ?, ?)`,
+		channelID, mask, setBy, time.Now())
+	if err != nil {
+		return fmt.Errorf("add channel ban: %w", err)
+	}
+
+	return nil
+}
+
+// RemoveChannelBan removes a ban mask from a channel.
+func (database *Database) RemoveChannelBan(
+	ctx context.Context,
+	channelID int64,
+	mask string,
+) error {
+	_, err := database.conn.ExecContext(ctx,
+		`DELETE FROM channel_bans
+		 WHERE channel_id = ? AND mask = ?`,
+		channelID, mask)
+	if err != nil {
+		return fmt.Errorf("remove channel ban: %w", err)
+	}
+
+	return nil
+}
+
+// ListChannelBans returns all bans for a channel.
+//
+//nolint:dupl // different query+type vs filtered variant
+func (database *Database) ListChannelBans(
+	ctx context.Context,
+	channelID int64,
+) ([]BanInfo, error) {
+	rows, err := database.conn.QueryContext(ctx,
+		`SELECT mask, set_by, created_at
+		 FROM channel_bans
+		 WHERE channel_id = ?
+		 ORDER BY created_at ASC`,
+		channelID)
+	if err != nil {
+		return nil, fmt.Errorf("list channel bans: %w", err)
+	}
+
+	defer func() { _ = rows.Close() }()
+
+	var bans []BanInfo
+
+	for rows.Next() {
+		var ban BanInfo
+
+		if scanErr := rows.Scan(
+			&ban.Mask, &ban.SetBy, &ban.CreatedAt,
+		); scanErr != nil {
+			return nil, fmt.Errorf(
+				"scan channel ban: %w", scanErr,
+			)
+		}
+
+		bans = append(bans, ban)
+	}
+
+	if rowErr := rows.Err(); rowErr != nil {
+		return nil, fmt.Errorf(
+			"iterate channel bans: %w", rowErr,
+		)
+	}
+
+	return bans, nil
+}
+
+// IsSessionBanned checks if a session's hostmask matches
+// any ban in the channel. Returns true if banned.
+func (database *Database) IsSessionBanned(
+	ctx context.Context,
+	channelID, sessionID int64,
+) (bool, error) {
+	// Get the session's hostmask parts.
+	var nick, username, hostname string
+
+	err := database.conn.QueryRowContext(ctx,
+		`SELECT nick, username, hostname
+		 FROM sessions WHERE id = ?`,
+		sessionID,
+	).Scan(&nick, &username, &hostname)
+	if err != nil {
+		return false, fmt.Errorf(
+			"get session hostmask: %w", err,
+		)
+	}
+
+	hostmask := FormatHostmask(nick, username, hostname)
+
+	// Get all ban masks for the channel.
+	bans, banErr := database.ListChannelBans(ctx, channelID)
+	if banErr != nil {
+		return false, banErr
+	}
+
+	for _, ban := range bans {
+		if MatchBanMask(ban.Mask, hostmask) {
+			return true, nil
+		}
+	}
+
+	return false, nil
+}
+
+// MatchBanMask checks if hostmask matches a ban pattern
+// using IRC-style wildcard matching (* and ?).
+func MatchBanMask(pattern, hostmask string) bool {
+	return wildcardMatch(
+		strings.ToLower(pattern),
+		strings.ToLower(hostmask),
+	)
+}
+
+// wildcardMatch implements simple glob-style matching
+// with * (any sequence) and ? (any single character).
+func wildcardMatch(pattern, str string) bool {
+	for len(pattern) > 0 {
+		switch pattern[0] {
+		case '*':
+			// Skip consecutive asterisks.
+			for len(pattern) > 0 && pattern[0] == '*' {
+				pattern = pattern[1:]
+			}
+
+			if len(pattern) == 0 {
+				return true
+			}
+
+			for i := 0; i <= len(str); i++ {
+				if wildcardMatch(pattern, str[i:]) {
+					return true
+				}
+			}
+
+			return false
+		case '?':
+			if len(str) == 0 {
+				return false
+			}
+
+			pattern = pattern[1:]
+			str = str[1:]
+		default:
+			if len(str) == 0 || pattern[0] != str[0] {
+				return false
+			}
+
+			pattern = pattern[1:]
+			str = str[1:]
+		}
+	}
+
+	return len(str) == 0
+}
+
+// --- Tier 2: Invite-only (+i) ---
+
+// IsChannelInviteOnly checks if a channel has +i mode.
+func (database *Database) IsChannelInviteOnly(
+	ctx context.Context,
+	channelID int64,
+) (bool, error) {
+	var isInviteOnly int
+
+	err := database.conn.QueryRowContext(ctx,
+		`SELECT is_invite_only FROM channels
+		 WHERE id = ?`,
+		channelID,
+	).Scan(&isInviteOnly)
+	if err != nil {
+		return false, fmt.Errorf(
+			"check invite only: %w", err,
+		)
+	}
+
+	return isInviteOnly != 0, nil
+}
+
+// SetChannelInviteOnly sets or unsets +i mode.
+func (database *Database) SetChannelInviteOnly(
+	ctx context.Context,
+	channelID int64,
+	inviteOnly bool,
+) error {
+	val := 0
+	if inviteOnly {
+		val = 1
+	}
+
+	_, err := database.conn.ExecContext(ctx,
+		`UPDATE channels
+		 SET is_invite_only = ?, updated_at = ?
+		 WHERE id = ?`,
+		val, time.Now(), channelID)
+	if err != nil {
+		return fmt.Errorf(
+			"set invite only: %w", err,
+		)
+	}
+
+	return nil
+}
+
+// AddChannelInvite records that a session has been
+// invited to a channel.
+func (database *Database) AddChannelInvite(
+	ctx context.Context,
+	channelID, sessionID int64,
+	invitedBy string,
+) error {
+	_, err := database.conn.ExecContext(ctx,
+		`INSERT OR IGNORE INTO channel_invites
+		 (channel_id, session_id, invited_by, created_at)
+		 VALUES (?, ?, ?, ?)`,
+		channelID, sessionID, invitedBy, time.Now())
+	if err != nil {
+		return fmt.Errorf("add channel invite: %w", err)
+	}
+
+	return nil
+}
+
+// HasChannelInvite checks if a session has been invited
+// to a channel.
+func (database *Database) HasChannelInvite(
+	ctx context.Context,
+	channelID, sessionID int64,
+) (bool, error) {
+	var count int
+
+	err := database.conn.QueryRowContext(ctx,
+		`SELECT COUNT(*) FROM channel_invites
+		 WHERE channel_id = ? AND session_id = ?`,
+		channelID, sessionID,
+	).Scan(&count)
+	if err != nil {
+		return false, fmt.Errorf(
+			"check invite: %w", err,
+		)
+	}
+
+	return count > 0, nil
+}
+
+// ClearChannelInvite removes a session's invite to a
+// channel (called after successful JOIN).
+func (database *Database) ClearChannelInvite(
+	ctx context.Context,
+	channelID, sessionID int64,
+) error {
+	_, err := database.conn.ExecContext(ctx,
+		`DELETE FROM channel_invites
+		 WHERE channel_id = ? AND session_id = ?`,
+		channelID, sessionID)
+	if err != nil {
+		return fmt.Errorf("clear invite: %w", err)
+	}
+
+	return nil
+}
+
+// --- Tier 2: Secret (+s) ---
+
+// IsChannelSecret checks if a channel has +s mode.
+func (database *Database) IsChannelSecret(
+	ctx context.Context,
+	channelID int64,
+) (bool, error) {
+	var isSecret int
+
+	err := database.conn.QueryRowContext(ctx,
+		`SELECT is_secret FROM channels
+		 WHERE id = ?`,
+		channelID,
+	).Scan(&isSecret)
+	if err != nil {
+		return false, fmt.Errorf(
+			"check secret: %w", err,
+		)
+	}
+
+	return isSecret != 0, nil
+}
+
+// SetChannelSecret sets or unsets +s mode.
+func (database *Database) SetChannelSecret(
+	ctx context.Context,
+	channelID int64,
+	secret bool,
+) error {
+	val := 0
+	if secret {
+		val = 1
+	}
+
+	_, err := database.conn.ExecContext(ctx,
+		`UPDATE channels
+		 SET is_secret = ?, updated_at = ?
+		 WHERE id = ?`,
+		val, time.Now(), channelID)
+	if err != nil {
+		return fmt.Errorf("set secret: %w", err)
+	}
+
+	return nil
+}
+
+// ListAllChannelsWithCountsFiltered returns all channels
+// with member counts, excluding secret channels that
+// the given session is not a member of.
+//
+//nolint:dupl // different query+type vs ListChannelBans
+func (database *Database) ListAllChannelsWithCountsFiltered(
+	ctx context.Context,
+	sessionID int64,
+) ([]ChannelInfoFull, error) {
+	rows, err := database.conn.QueryContext(ctx,
+		`SELECT c.name, COUNT(cm.id) AS member_count,
+		        c.topic
+		 FROM channels c
+		 LEFT JOIN channel_members cm
+		   ON cm.channel_id = c.id
+		 WHERE c.is_secret = 0
+		    OR c.id IN (
+		       SELECT channel_id FROM channel_members
+		       WHERE session_id = ?
+		    )
+		 GROUP BY c.id
+		 ORDER BY c.name ASC`,
+		sessionID)
+	if err != nil {
+		return nil, fmt.Errorf(
+			"list channels filtered: %w", err,
+		)
+	}
+
+	defer func() { _ = rows.Close() }()
+
+	var channels []ChannelInfoFull
+
+	for rows.Next() {
+		var chanInfo ChannelInfoFull
+
+		if scanErr := rows.Scan(
+			&chanInfo.Name,
+			&chanInfo.MemberCount,
+			&chanInfo.Topic,
+		); scanErr != nil {
+			return nil, fmt.Errorf(
+				"scan channel: %w", scanErr,
+			)
+		}
+
+		channels = append(channels, chanInfo)
+	}
+
+	if rowErr := rows.Err(); rowErr != nil {
+		return nil, fmt.Errorf(
+			"iterate channels: %w", rowErr,
+		)
+	}
+
+	return channels, nil
+}
+
+// GetSessionChannelsFiltered returns channels a session
+// belongs to, optionally excluding secret channels for
+// WHOIS (when the querier is not in the same channel).
+// If querierID == targetID, returns all channels.
+func (database *Database) GetSessionChannelsFiltered(
+	ctx context.Context,
+	targetSID, querierSID int64,
+) ([]ChannelInfo, error) {
+	// If querying yourself, return all channels.
+	if targetSID == querierSID {
+		return database.GetSessionChannels(ctx, targetSID)
+	}
+
+	rows, err := database.conn.QueryContext(ctx,
+		`SELECT c.id, c.name, c.topic
+		 FROM channels c
+		 JOIN channel_members cm
+		   ON cm.channel_id = c.id
+		 WHERE cm.session_id = ?
+		   AND (c.is_secret = 0
+		        OR c.id IN (
+		           SELECT channel_id FROM channel_members
+		           WHERE session_id = ?
+		        ))
+		 ORDER BY c.name ASC`,
+		targetSID, querierSID)
+	if err != nil {
+		return nil, fmt.Errorf(
+			"get session channels filtered: %w", err,
+		)
+	}
+
+	defer func() { _ = rows.Close() }()
+
+	var channels []ChannelInfo
+
+	for rows.Next() {
+		var chanInfo ChannelInfo
+
+		if scanErr := rows.Scan(
+			&chanInfo.ID,
+			&chanInfo.Name,
+			&chanInfo.Topic,
+		); scanErr != nil {
+			return nil, fmt.Errorf(
+				"scan channel: %w", scanErr,
+			)
+		}
+
+		channels = append(channels, chanInfo)
+	}
+
+	if rowErr := rows.Err(); rowErr != nil {
+		return nil, fmt.Errorf(
+			"iterate channels: %w", rowErr,
+		)
+	}
+
+	return channels, nil
+}
+
+// --- Tier 2: Channel Key (+k) ---
+
+// GetChannelKey returns the key for a channel (empty
+// string means no key set).
+func (database *Database) GetChannelKey(
+	ctx context.Context,
+	channelID int64,
+) (string, error) {
+	var key string
+
+	err := database.conn.QueryRowContext(ctx,
+		`SELECT channel_key FROM channels
+		 WHERE id = ?`,
+		channelID,
+	).Scan(&key)
+	if err != nil {
+		return "", fmt.Errorf("get channel key: %w", err)
+	}
+
+	return key, nil
+}
+
+// SetChannelKey sets or clears the key for a channel.
+func (database *Database) SetChannelKey(
+	ctx context.Context,
+	channelID int64,
+	key string,
+) error {
+	_, err := database.conn.ExecContext(ctx,
+		`UPDATE channels
+		 SET channel_key = ?, updated_at = ?
+		 WHERE id = ?`,
+		key, time.Now(), channelID)
+	if err != nil {
+		return fmt.Errorf("set channel key: %w", err)
+	}
+
+	return nil
+}
+
+// --- Tier 2: User Limit (+l) ---
+
+// GetChannelUserLimit returns the user limit for a
+// channel (0 means no limit).
+func (database *Database) GetChannelUserLimit(
+	ctx context.Context,
+	channelID int64,
+) (int, error) {
+	var limit int
+
+	err := database.conn.QueryRowContext(ctx,
+		`SELECT user_limit FROM channels
+		 WHERE id = ?`,
+		channelID,
+	).Scan(&limit)
+	if err != nil {
+		return 0, fmt.Errorf(
+			"get channel user limit: %w", err,
+		)
+	}
+
+	return limit, nil
+}
+
+// SetChannelUserLimit sets the user limit for a channel.
+func (database *Database) SetChannelUserLimit(
+	ctx context.Context,
+	channelID int64,
+	limit int,
+) error {
+	_, err := database.conn.ExecContext(ctx,
+		`UPDATE channels
+		 SET user_limit = ?, updated_at = ?
+		 WHERE id = ?`,
+		limit, time.Now(), channelID)
+	if err != nil {
+		return fmt.Errorf(
+			"set channel user limit: %w", err,
+		)
+	}
+
+	return nil
+}
+
+// SetSessionWallops sets the wallops (+w) flag on a
+// session.
+func (database *Database) SetSessionWallops(
+	ctx context.Context,
+	sessionID int64,
+	enabled bool,
+) error {
+	val := 0
+	if enabled {
+		val = 1
+	}
+
+	_, err := database.conn.ExecContext(
+		ctx,
+		`UPDATE sessions SET is_wallops = ? WHERE id = ?`,
+		val, sessionID,
+	)
+	if err != nil {
+		return fmt.Errorf("set session wallops: %w", err)
+	}
+
+	return nil
+}
+
+// IsSessionWallops returns whether the session has the
+// wallops (+w) usermode set.
+func (database *Database) IsSessionWallops(
+	ctx context.Context,
+	sessionID int64,
+) (bool, error) {
+	var isWallops int
+
+	err := database.conn.QueryRowContext(
+		ctx,
+		`SELECT is_wallops FROM sessions WHERE id = ?`,
+		sessionID,
+	).Scan(&isWallops)
+	if err != nil {
+		return false, fmt.Errorf(
+			"check session wallops: %w", err,
+		)
+	}
+
+	return isWallops != 0, nil
+}
+
+// GetWallopsSessionIDs returns all session IDs that have
+// the wallops (+w) usermode set.
+func (database *Database) GetWallopsSessionIDs(
+	ctx context.Context,
+) ([]int64, error) {
+	rows, err := database.conn.QueryContext(
+		ctx,
+		`SELECT id FROM sessions WHERE is_wallops = 1`,
+	)
+	if err != nil {
+		return nil, fmt.Errorf(
+			"get wallops sessions: %w", err,
+		)
+	}
+
+	defer func() { _ = rows.Close() }()
+
+	var ids []int64
+
+	for rows.Next() {
+		var sessionID int64
+		if scanErr := rows.Scan(&sessionID); scanErr != nil {
+			return nil, fmt.Errorf(
+				"scan wallops session: %w", scanErr,
+			)
+		}
+
+		ids = append(ids, sessionID)
+	}
+
+	if err := rows.Err(); err != nil {
+		return nil, fmt.Errorf(
+			"iterate wallops sessions: %w", err,
+		)
+	}
+
+	return ids, nil
+}
+
+// UserhostInfo holds the data needed for RPL_USERHOST.
+type UserhostInfo struct {
+	Nick        string
+	Username    string
+	Hostname    string
+	IsOper      bool
+	AwayMessage string
+}
+
+// GetUserhostInfo returns USERHOST info for the given
+// nicks. Only nicks that exist are returned.
+func (database *Database) GetUserhostInfo(
+	ctx context.Context,
+	nicks []string,
+) ([]UserhostInfo, error) {
+	if len(nicks) == 0 {
+		return nil, nil
+	}
+
+	results := make([]UserhostInfo, 0, len(nicks))
+
+	for _, nick := range nicks {
+		var info UserhostInfo
+
+		err := database.conn.QueryRowContext(
+			ctx,
+			`SELECT nick, username, hostname,
+			        is_oper, away_message
+			 FROM sessions WHERE nick = ?`,
+			nick,
+		).Scan(
+			&info.Nick, &info.Username, &info.Hostname,
+			&info.IsOper, &info.AwayMessage,
+		)
+		if err != nil {
+			continue // nick not found, skip
+		}
+
+		results = append(results, info)
+	}
+
+	return results, nil
+}

internal/db/queries_test.go

@@ -1017,3 +1017,474 @@ func TestGetOperCount(t *testing.T) {
 		t.Fatalf("expected 1 oper, got %d", count)
 	}
 }
+
+// --- Tier 2 Tests ---
+
+func TestWildcardMatch(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		pattern string
+		input   string
+		match   bool
+	}{
+		{"*!*@*", "nick!user@host", true},
+		{"*!*@*.example.com", "nick!user@foo.example.com", true},
+		{"*!*@*.example.com", "nick!user@other.net", false},
+		{"badnick!*@*", "badnick!user@host", true},
+		{"badnick!*@*", "goodnick!user@host", false},
+		{"nick!user@host", "nick!user@host", true},
+		{"nick!user@host", "nick!user@other", false},
+		{"*", "anything", true},
+		{"?ick!*@*", "nick!user@host", true},
+		{"?ick!*@*", "nn!user@host", false},
+		// Case-insensitive.
+		{"Nick!*@*", "nick!user@host", true},
+	}
+
+	for _, tc := range tests {
+		result := db.MatchBanMask(tc.pattern, tc.input)
+		if result != tc.match {
+			t.Errorf(
+				"MatchBanMask(%q, %q) = %v, want %v",
+				tc.pattern, tc.input, result, tc.match,
+			)
+		}
+	}
+}
+
+func TestChannelBanCRUD(t *testing.T) {
+	t.Parallel()
+
+	database := setupTestDB(t)
+	ctx := t.Context()
+
+	chID, err := database.GetOrCreateChannel(ctx, "#test")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// No bans initially.
+	bans, err := database.ListChannelBans(ctx, chID)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if len(bans) != 0 {
+		t.Fatalf("expected 0 bans, got %d", len(bans))
+	}
+
+	// Add a ban.
+	err = database.AddChannelBan(
+		ctx, chID, "*!*@evil.com", "op",
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	bans, err = database.ListChannelBans(ctx, chID)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if len(bans) != 1 {
+		t.Fatalf("expected 1 ban, got %d", len(bans))
+	}
+
+	if bans[0].Mask != "*!*@evil.com" {
+		t.Fatalf("wrong mask: %s", bans[0].Mask)
+	}
+
+	// Duplicate add is ignored (OR IGNORE).
+	err = database.AddChannelBan(
+		ctx, chID, "*!*@evil.com", "op2",
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	bans, _ = database.ListChannelBans(ctx, chID)
+	if len(bans) != 1 {
+		t.Fatalf("expected 1 ban after dup, got %d", len(bans))
+	}
+
+	// Remove ban.
+	err = database.RemoveChannelBan(
+		ctx, chID, "*!*@evil.com",
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	bans, _ = database.ListChannelBans(ctx, chID)
+	if len(bans) != 0 {
+		t.Fatalf("expected 0 bans after remove, got %d", len(bans))
+	}
+}
+
+func TestIsSessionBanned(t *testing.T) {
+	t.Parallel()
+
+	database := setupTestDB(t)
+	ctx := t.Context()
+
+	sid, _, _, err := database.CreateSession(
+		ctx, "victim", "victim", "evil.com", "",
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	chID, err := database.GetOrCreateChannel(ctx, "#bantest")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Not banned initially.
+	banned, err := database.IsSessionBanned(ctx, chID, sid)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if banned {
+		t.Fatal("should not be banned initially")
+	}
+
+	// Add ban matching the hostmask.
+	err = database.AddChannelBan(
+		ctx, chID, "*!*@evil.com", "op",
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	banned, err = database.IsSessionBanned(ctx, chID, sid)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if !banned {
+		t.Fatal("should be banned")
+	}
+}
+
+func TestChannelInviteOnly(t *testing.T) {
+	t.Parallel()
+
+	database := setupTestDB(t)
+	ctx := t.Context()
+
+	chID, err := database.GetOrCreateChannel(ctx, "#invite")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Default: not invite-only.
+	isIO, err := database.IsChannelInviteOnly(ctx, chID)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if isIO {
+		t.Fatal("should not be invite-only by default")
+	}
+
+	// Set invite-only.
+	err = database.SetChannelInviteOnly(ctx, chID, true)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	isIO, _ = database.IsChannelInviteOnly(ctx, chID)
+	if !isIO {
+		t.Fatal("should be invite-only")
+	}
+
+	// Unset.
+	err = database.SetChannelInviteOnly(ctx, chID, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	isIO, _ = database.IsChannelInviteOnly(ctx, chID)
+	if isIO {
+		t.Fatal("should not be invite-only")
+	}
+}
+
+func TestChannelInviteCRUD(t *testing.T) {
+	t.Parallel()
+
+	database := setupTestDB(t)
+	ctx := t.Context()
+
+	sid, _, _, err := database.CreateSession(
+		ctx, "invited", "", "", "",
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	chID, err := database.GetOrCreateChannel(ctx, "#inv")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// No invite initially.
+	has, err := database.HasChannelInvite(ctx, chID, sid)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if has {
+		t.Fatal("should not have invite")
+	}
+
+	// Add invite.
+	err = database.AddChannelInvite(ctx, chID, sid, "op")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	has, _ = database.HasChannelInvite(ctx, chID, sid)
+	if !has {
+		t.Fatal("should have invite")
+	}
+
+	// Clear invite.
+	err = database.ClearChannelInvite(ctx, chID, sid)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	has, _ = database.HasChannelInvite(ctx, chID, sid)
+	if has {
+		t.Fatal("invite should be cleared")
+	}
+}
+
+func TestChannelSecret(t *testing.T) {
+	t.Parallel()
+
+	database := setupTestDB(t)
+	ctx := t.Context()
+
+	chID, err := database.GetOrCreateChannel(ctx, "#secret")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Default: not secret.
+	isSec, err := database.IsChannelSecret(ctx, chID)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if isSec {
+		t.Fatal("should not be secret by default")
+	}
+
+	err = database.SetChannelSecret(ctx, chID, true)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	isSec, _ = database.IsChannelSecret(ctx, chID)
+	if !isSec {
+		t.Fatal("should be secret")
+	}
+}
+
+// createTestSession is a helper to create a session and
+// return only the session ID.
+func createTestSession(
+	t *testing.T,
+	database *db.Database,
+	nick string,
+) int64 {
+	t.Helper()
+
+	sid, _, _, err := database.CreateSession(
+		t.Context(), nick, "", "", "",
+	)
+	if err != nil {
+		t.Fatalf("create session %s: %v", nick, err)
+	}
+
+	return sid
+}
+
+func TestSecretChannelFiltering(t *testing.T) {
+	t.Parallel()
+
+	database := setupTestDB(t)
+	ctx := t.Context()
+
+	// Create two sessions.
+	sid1 := createTestSession(t, database, "member")
+	sid2 := createTestSession(t, database, "outsider")
+
+	// Create a secret channel.
+	chID, _ := database.GetOrCreateChannel(ctx, "#secret")
+	_ = database.SetChannelSecret(ctx, chID, true)
+	_ = database.JoinChannel(ctx, chID, sid1)
+
+	// Create a non-secret channel.
+	chID2, _ := database.GetOrCreateChannel(ctx, "#public")
+	_ = database.JoinChannel(ctx, chID2, sid1)
+
+	// Member should see both.
+	list, err := database.ListAllChannelsWithCountsFiltered(
+		ctx, sid1,
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if len(list) != 2 {
+		t.Fatalf("member should see 2 channels, got %d", len(list))
+	}
+
+	// Outsider should only see public.
+	list, _ = database.ListAllChannelsWithCountsFiltered(
+		ctx, sid2,
+	)
+	if len(list) != 1 {
+		t.Fatalf("outsider should see 1 channel, got %d", len(list))
+	}
+
+	if list[0].Name != "#public" {
+		t.Fatalf("outsider should see #public, got %s", list[0].Name)
+	}
+}
+
+func TestWhoisChannelFiltering(t *testing.T) {
+	t.Parallel()
+
+	database := setupTestDB(t)
+	ctx := t.Context()
+
+	sid1 := createTestSession(t, database, "target")
+	sid2 := createTestSession(t, database, "querier")
+
+	// Create secret channel, target joins it.
+	chID, _ := database.GetOrCreateChannel(ctx, "#hidden")
+	_ = database.SetChannelSecret(ctx, chID, true)
+	_ = database.JoinChannel(ctx, chID, sid1)
+
+	// Querier (non-member) should not see the channel.
+	channels, err := database.GetSessionChannelsFiltered(
+		ctx, sid1, sid2,
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if len(channels) != 0 {
+		t.Fatalf(
+			"querier should see 0 channels, got %d",
+			len(channels),
+		)
+	}
+
+	// Target querying self should see it.
+	channels, _ = database.GetSessionChannelsFiltered(
+		ctx, sid1, sid1,
+	)
+	if len(channels) != 1 {
+		t.Fatalf(
+			"self-query should see 1 channel, got %d",
+			len(channels),
+		)
+	}
+}
+
+//nolint:dupl // structurally similar to TestChannelUserLimit
+func TestChannelKey(t *testing.T) {
+	t.Parallel()
+
+	database := setupTestDB(t)
+	ctx := t.Context()
+
+	chID, err := database.GetOrCreateChannel(ctx, "#keyed")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Default: no key.
+	key, err := database.GetChannelKey(ctx, chID)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if key != "" {
+		t.Fatalf("expected empty key, got %q", key)
+	}
+
+	// Set key.
+	err = database.SetChannelKey(ctx, chID, "secret123")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	key, _ = database.GetChannelKey(ctx, chID)
+	if key != "secret123" {
+		t.Fatalf("expected secret123, got %q", key)
+	}
+
+	// Clear key.
+	err = database.SetChannelKey(ctx, chID, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	key, _ = database.GetChannelKey(ctx, chID)
+	if key != "" {
+		t.Fatalf("expected empty key, got %q", key)
+	}
+}
+
+//nolint:dupl // structurally similar to TestChannelKey
+func TestChannelUserLimit(t *testing.T) {
+	t.Parallel()
+
+	database := setupTestDB(t)
+	ctx := t.Context()
+
+	chID, err := database.GetOrCreateChannel(ctx, "#limited")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Default: no limit.
+	limit, err := database.GetChannelUserLimit(ctx, chID)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if limit != 0 {
+		t.Fatalf("expected 0 limit, got %d", limit)
+	}
+
+	// Set limit.
+	err = database.SetChannelUserLimit(ctx, chID, 50)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	limit, _ = database.GetChannelUserLimit(ctx, chID)
+	if limit != 50 {
+		t.Fatalf("expected 50, got %d", limit)
+	}
+
+	// Clear limit.
+	err = database.SetChannelUserLimit(ctx, chID, 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	limit, _ = database.GetChannelUserLimit(ctx, chID)
+	if limit != 0 {
+		t.Fatalf("expected 0, got %d", limit)
+	}
+}

internal/db/schema/001_initial.sql

@@ -10,6 +10,7 @@ CREATE TABLE IF NOT EXISTS sessions (
     hostname TEXT NOT NULL DEFAULT '',
     ip TEXT NOT NULL DEFAULT '',
     is_oper INTEGER NOT NULL DEFAULT 0,
+    is_wallops INTEGER NOT NULL DEFAULT 0,
     password_hash TEXT NOT NULL DEFAULT '',
     signing_key TEXT NOT NULL DEFAULT '',
     away_message TEXT NOT NULL DEFAULT '',
@@ -42,10 +43,36 @@ CREATE TABLE IF NOT EXISTS channels (
     hashcash_bits INTEGER NOT NULL DEFAULT 0,
     is_moderated INTEGER NOT NULL DEFAULT 0,
     is_topic_locked INTEGER NOT NULL DEFAULT 1,
+    is_invite_only INTEGER NOT NULL DEFAULT 0,
+    is_secret INTEGER NOT NULL DEFAULT 0,
+    channel_key TEXT NOT NULL DEFAULT '',
+    user_limit INTEGER NOT NULL DEFAULT 0,
     created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
     updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
 );
 
+-- Channel bans
+CREATE TABLE IF NOT EXISTS channel_bans (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    channel_id INTEGER NOT NULL REFERENCES channels(id) ON DELETE CASCADE,
+    mask TEXT NOT NULL,
+    set_by TEXT NOT NULL,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    UNIQUE(channel_id, mask)
+);
+CREATE INDEX IF NOT EXISTS idx_channel_bans_channel ON channel_bans(channel_id);
+
+-- Channel invites (in-memory would be simpler but DB survives restarts)
+CREATE TABLE IF NOT EXISTS channel_invites (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    channel_id INTEGER NOT NULL REFERENCES channels(id) ON DELETE CASCADE,
+    session_id INTEGER NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+    invited_by TEXT NOT NULL DEFAULT '',
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    UNIQUE(channel_id, session_id)
+);
+CREATE INDEX IF NOT EXISTS idx_channel_invites_channel ON channel_invites(channel_id);
+
 -- Channel members
 CREATE TABLE IF NOT EXISTS channel_members (
     id INTEGER PRIMARY KEY AUTOINCREMENT,

internal/handlers/api_test.go

@@ -4378,3 +4378,486 @@ func TestKickDefaultReason(t *testing.T) {
 		)
 	}
 }
+
+// --- Tier 2 Handler Tests ---
+
+const (
+	inviteCmd    = "INVITE"
+	joinedStatus = "joined"
+)
+
+// TestBanAddRemoveList verifies +b add, list, and -b
+// remove via MODE commands.
+func TestBanAddRemoveList(t *testing.T) {
+	tserver := newTestServer(t)
+	opToken := tserver.createSession("banop")
+
+	tserver.sendCommand(opToken, map[string]any{
+		commandKey: joinCmd, toKey: "#bans",
+	})
+
+	// Add a ban.
+	tserver.sendCommand(opToken, map[string]any{
+		commandKey: modeCmd,
+		toKey:      "#bans",
+		bodyKey:    []string{"+b", "*!*@evil.com"},
+	})
+
+	_, lastID := tserver.pollMessages(opToken, 0)
+
+	// List bans (+b with no argument).
+	tserver.sendCommand(opToken, map[string]any{
+		commandKey: modeCmd,
+		toKey:      "#bans",
+		bodyKey:    []string{"+b"},
+	})
+
+	msgs, _ := tserver.pollMessages(opToken, lastID)
+
+	// Should have RPL_BANLIST (367).
+	banMsg := findNumericWithParams(msgs, "367")
+	if banMsg == nil {
+		t.Fatalf("expected 367 RPL_BANLIST, got %v", msgs)
+	}
+
+	// Should have RPL_ENDOFBANLIST (368).
+	if !findNumeric(msgs, "368") {
+		t.Fatal("expected 368 RPL_ENDOFBANLIST")
+	}
+
+	// Remove the ban.
+	tserver.sendCommand(opToken, map[string]any{
+		commandKey: modeCmd,
+		toKey:      "#bans",
+		bodyKey:    []string{"-b", "*!*@evil.com"},
+	})
+
+	_, lastID = tserver.pollMessages(opToken, lastID)
+
+	// List again — should be empty (just end-of-list).
+	tserver.sendCommand(opToken, map[string]any{
+		commandKey: modeCmd,
+		toKey:      "#bans",
+		bodyKey:    []string{"+b"},
+	})
+
+	msgs, _ = tserver.pollMessages(opToken, lastID)
+	banMsg = findNumericWithParams(msgs, "367")
+	if banMsg != nil {
+		t.Fatal("expected no 367 after ban removal")
+	}
+
+	if !findNumeric(msgs, "368") {
+		t.Fatal("expected 368 RPL_ENDOFBANLIST")
+	}
+}
+
+// TestBanBlocksJoin verifies that a banned user cannot
+// join a channel.
+func TestBanBlocksJoin(t *testing.T) {
+	tserver := newTestServer(t)
+	opToken := tserver.createSession("banop2")
+	userToken := tserver.createSession("banned2")
+
+	// Op creates channel and sets a ban.
+	tserver.sendCommand(opToken, map[string]any{
+		commandKey: joinCmd, toKey: "#banjoin",
+	})
+	tserver.sendCommand(opToken, map[string]any{
+		commandKey: modeCmd,
+		toKey:      "#banjoin",
+		bodyKey:    []string{"+b", "banned2!*@*"},
+	})
+
+	// Banned user tries to join.
+	_, lastID := tserver.pollMessages(userToken, 0)
+	tserver.sendCommand(userToken, map[string]any{
+		commandKey: joinCmd, toKey: "#banjoin",
+	})
+
+	msgs, _ := tserver.pollMessages(userToken, lastID)
+
+	// Should get ERR_BANNEDFROMCHAN (474).
+	if !findNumeric(msgs, "474") {
+		t.Fatalf("expected 474 ERR_BANNEDFROMCHAN, got %v", msgs)
+	}
+}
+
+// TestBanBlocksPrivmsg verifies that a banned user who
+// is already in a channel cannot send messages.
+func TestBanBlocksPrivmsg(t *testing.T) {
+	tserver := newTestServer(t)
+	opToken := tserver.createSession("banmsgop")
+	userToken := tserver.createSession("banmsgusr")
+
+	// Both join.
+	tserver.sendCommand(opToken, map[string]any{
+		commandKey: joinCmd, toKey: "#banmsg",
+	})
+	tserver.sendCommand(userToken, map[string]any{
+		commandKey: joinCmd, toKey: "#banmsg",
+	})
+
+	// Op bans the user.
+	tserver.sendCommand(opToken, map[string]any{
+		commandKey: modeCmd,
+		toKey:      "#banmsg",
+		bodyKey:    []string{"+b", "banmsgusr!*@*"},
+	})
+
+	// User tries to send a message.
+	_, lastID := tserver.pollMessages(userToken, 0)
+	tserver.sendCommand(userToken, map[string]any{
+		commandKey: privmsgCmd,
+		toKey:      "#banmsg",
+		bodyKey:    []string{"hello"},
+	})
+
+	msgs, _ := tserver.pollMessages(userToken, lastID)
+
+	// Should get ERR_CANNOTSENDTOCHAN (404).
+	if !findNumeric(msgs, "404") {
+		t.Fatalf("expected 404 ERR_CANNOTSENDTOCHAN, got %v", msgs)
+	}
+}
+
+// TestInviteOnlyJoin verifies +i behavior: join rejected
+// without invite, accepted with invite.
+func TestInviteOnlyJoin(t *testing.T) {
+	tserver := newTestServer(t)
+	opToken := tserver.createSession("invop")
+	userToken := tserver.createSession("invusr")
+
+	// Op creates channel and sets +i.
+	tserver.sendCommand(opToken, map[string]any{
+		commandKey: joinCmd, toKey: "#invonly",
+	})
+	tserver.sendCommand(opToken, map[string]any{
+		commandKey: modeCmd,
+		toKey:      "#invonly",
+		bodyKey:    []string{"+i"},
+	})
+
+	// User tries to join without invite.
+	_, lastID := tserver.pollMessages(userToken, 0)
+	tserver.sendCommand(userToken, map[string]any{
+		commandKey: joinCmd, toKey: "#invonly",
+	})
+
+	msgs, _ := tserver.pollMessages(userToken, lastID)
+
+	if !findNumeric(msgs, "473") {
+		t.Fatalf(
+			"expected 473 ERR_INVITEONLYCHAN, got %v",
+			msgs,
+		)
+	}
+
+	// Op invites user.
+	tserver.sendCommand(opToken, map[string]any{
+		commandKey: inviteCmd,
+		bodyKey:    []string{"invusr", "#invonly"},
+	})
+
+	// User tries again — should succeed with invite.
+	_, result := tserver.sendCommand(userToken, map[string]any{
+		commandKey: joinCmd, toKey: "#invonly",
+	})
+
+	if result[statusKey] != joinedStatus {
+		t.Fatalf(
+			"expected join to succeed with invite, got %v",
+			result,
+		)
+	}
+}
+
+// TestSecretChannelHiddenFromList verifies +s hides a
+// channel from LIST for non-members.
+func TestSecretChannelHiddenFromList(t *testing.T) {
+	tserver := newTestServer(t)
+	opToken := tserver.createSession("secop")
+	outsiderToken := tserver.createSession("secout")
+
+	// Op creates secret channel.
+	tserver.sendCommand(opToken, map[string]any{
+		commandKey: joinCmd, toKey: "#secret",
+	})
+	tserver.sendCommand(opToken, map[string]any{
+		commandKey: modeCmd,
+		toKey:      "#secret",
+		bodyKey:    []string{"+s"},
+	})
+
+	// Outsider does LIST.
+	_, lastID := tserver.pollMessages(outsiderToken, 0)
+	tserver.sendCommand(outsiderToken, map[string]any{
+		commandKey: "LIST",
+	})
+
+	msgs, _ := tserver.pollMessages(outsiderToken, lastID)
+
+	// Should NOT see #secret in any 322 (RPL_LIST).
+	for _, msg := range msgs {
+		code, ok := msg["code"].(float64)
+		if !ok || int(code) != 322 {
+			continue
+		}
+
+		params := getNumericParams(msg)
+		for _, p := range params {
+			if p == "#secret" {
+				t.Fatal("outsider should not see #secret in LIST")
+			}
+		}
+	}
+
+	// Member does LIST — should see it.
+	_, lastID = tserver.pollMessages(opToken, 0)
+	tserver.sendCommand(opToken, map[string]any{
+		commandKey: "LIST",
+	})
+
+	msgs, _ = tserver.pollMessages(opToken, lastID)
+
+	found := false
+
+	for _, msg := range msgs {
+		code, ok := msg["code"].(float64)
+		if !ok || int(code) != 322 {
+			continue
+		}
+
+		params := getNumericParams(msg)
+		for _, p := range params {
+			if p == "#secret" {
+				found = true
+			}
+		}
+	}
+
+	if !found {
+		t.Fatal("member should see #secret in LIST")
+	}
+}
+
+// TestChannelKeyJoin verifies +k behavior: wrong/missing
+// key is rejected, correct key allows join.
+func TestChannelKeyJoin(t *testing.T) {
+	tserver := newTestServer(t)
+	opToken := tserver.createSession("keyop")
+	userToken := tserver.createSession("keyusr")
+
+	// Op creates keyed channel.
+	tserver.sendCommand(opToken, map[string]any{
+		commandKey: joinCmd, toKey: "#keyed",
+	})
+	tserver.sendCommand(opToken, map[string]any{
+		commandKey: modeCmd,
+		toKey:      "#keyed",
+		bodyKey:    []string{"+k", "mykey"},
+	})
+
+	// User tries without key.
+	_, lastID := tserver.pollMessages(userToken, 0)
+	tserver.sendCommand(userToken, map[string]any{
+		commandKey: joinCmd, toKey: "#keyed",
+	})
+
+	msgs, _ := tserver.pollMessages(userToken, lastID)
+
+	if !findNumeric(msgs, "475") {
+		t.Fatalf(
+			"expected 475 ERR_BADCHANNELKEY, got %v",
+			msgs,
+		)
+	}
+
+	// User tries with wrong key.
+	tserver.sendCommand(userToken, map[string]any{
+		commandKey: joinCmd,
+		toKey:      "#keyed",
+		bodyKey:    []string{"wrongkey"},
+	})
+
+	msgs, _ = tserver.pollMessages(userToken, lastID)
+	if !findNumeric(msgs, "475") {
+		t.Fatalf(
+			"expected 475 ERR_BADCHANNELKEY for wrong key, got %v",
+			msgs,
+		)
+	}
+
+	// User tries with correct key.
+	_, result := tserver.sendCommand(userToken, map[string]any{
+		commandKey: joinCmd,
+		toKey:      "#keyed",
+		bodyKey:    []string{"mykey"},
+	})
+
+	if result[statusKey] != joinedStatus {
+		t.Fatalf(
+			"expected join to succeed with correct key, got %v",
+			result,
+		)
+	}
+}
+
+// TestUserLimitEnforcement verifies +l behavior: blocks
+// join when at capacity.
+func TestUserLimitEnforcement(t *testing.T) {
+	tserver := newTestServer(t)
+	opToken := tserver.createSession("limop")
+	user1Token := tserver.createSession("limusr1")
+	user2Token := tserver.createSession("limusr2")
+
+	// Op creates channel with limit 2.
+	tserver.sendCommand(opToken, map[string]any{
+		commandKey: joinCmd, toKey: "#limited",
+	})
+	tserver.sendCommand(opToken, map[string]any{
+		commandKey: modeCmd,
+		toKey:      "#limited",
+		bodyKey:    []string{"+l", "2"},
+	})
+
+	// User1 joins — should succeed (2 members now: op + user1).
+	_, result := tserver.sendCommand(user1Token, map[string]any{
+		commandKey: joinCmd, toKey: "#limited",
+	})
+	if result[statusKey] != joinedStatus {
+		t.Fatalf("user1 should join, got %v", result)
+	}
+
+	// User2 tries to join — should fail (at limit: 2/2).
+	_, lastID := tserver.pollMessages(user2Token, 0)
+	tserver.sendCommand(user2Token, map[string]any{
+		commandKey: joinCmd, toKey: "#limited",
+	})
+
+	msgs, _ := tserver.pollMessages(user2Token, lastID)
+
+	if !findNumeric(msgs, "471") {
+		t.Fatalf(
+			"expected 471 ERR_CHANNELISFULL, got %v",
+			msgs,
+		)
+	}
+}
+
+// TestModeStringIncludesNewModes verifies that querying
+// channel mode returns the new modes (+i, +s, +k, +l).
+func TestModeStringIncludesNewModes(t *testing.T) {
+	tserver := newTestServer(t)
+	opToken := tserver.createSession("modestrop")
+
+	tserver.sendCommand(opToken, map[string]any{
+		commandKey: joinCmd, toKey: "#modestr",
+	})
+
+	// Set all tier 2 modes.
+	for _, modeChange := range [][]string{
+		{"+i"}, {"+s"}, {"+k", "pw"}, {"+l", "50"},
+	} {
+		tserver.sendCommand(opToken, map[string]any{
+			commandKey: modeCmd,
+			toKey:      "#modestr",
+			bodyKey:    modeChange,
+		})
+	}
+
+	_, lastID := tserver.pollMessages(opToken, 0)
+
+	// Query mode.
+	tserver.sendCommand(opToken, map[string]any{
+		commandKey: modeCmd, toKey: "#modestr",
+	})
+
+	msgs, _ := tserver.pollMessages(opToken, lastID)
+	modeMsg := findNumericWithParams(msgs, "324")
+
+	if modeMsg == nil {
+		t.Fatal("expected 324 RPL_CHANNELMODEIS")
+	}
+
+	params := getNumericParams(modeMsg)
+	if len(params) < 2 {
+		t.Fatalf("too few params in 324: %v", params)
+	}
+
+	modeString := params[1]
+
+	for _, c := range []string{"i", "s", "k", "l"} {
+		if !strings.Contains(modeString, c) {
+			t.Fatalf(
+				"mode string %q missing %q",
+				modeString, c,
+			)
+		}
+	}
+}
+
+// TestISUPPORT verifies the 005 numeric includes the
+// updated CHANMODES string.
+func TestISUPPORT(t *testing.T) {
+	tserver := newTestServer(t)
+	token := tserver.createSession("isupport")
+
+	msgs, _ := tserver.pollMessages(token, 0)
+
+	isupp := findNumericWithParams(msgs, "005")
+	if isupp == nil {
+		t.Fatal("expected 005 RPL_ISUPPORT")
+	}
+
+	body, _ := isupp["body"].(string)
+	params := getNumericParams(isupp)
+
+	combined := body + " " + strings.Join(params, " ")
+
+	if !strings.Contains(combined, "CHANMODES=b,k,Hl,imnst") {
+		t.Fatalf(
+			"ISUPPORT missing updated CHANMODES, got body=%q params=%v",
+			body, params,
+		)
+	}
+}
+
+// TestNonOpCannotSetModes verifies non-operators
+// cannot set +i, +s, +k, +l, +b.
+func TestNonOpCannotSetModes(t *testing.T) {
+	tserver := newTestServer(t)
+	opToken := tserver.createSession("modeopx")
+	userToken := tserver.createSession("modeusrx")
+
+	tserver.sendCommand(opToken, map[string]any{
+		commandKey: joinCmd, toKey: "#noperm",
+	})
+	tserver.sendCommand(userToken, map[string]any{
+		commandKey: joinCmd, toKey: "#noperm",
+	})
+
+	modes := [][]string{
+		{"+i"}, {"+s"}, {"+k", "key"}, {"+l", "10"},
+		{"+b", "bad!*@*"},
+	}
+
+	for _, modeChange := range modes {
+		_, lastID := tserver.pollMessages(userToken, 0)
+		tserver.sendCommand(userToken, map[string]any{
+			commandKey: modeCmd,
+			toKey:      "#noperm",
+			bodyKey:    modeChange,
+		})
+
+		msgs, _ := tserver.pollMessages(userToken, lastID)
+
+		// Should get 482 ERR_CHANOPRIVSNEEDED.
+		if !findNumeric(msgs, "482") {
+			t.Fatalf(
+				"expected 482 for %v, got %v",
+				modeChange, msgs,
+			)
+		}
+	}
+}

internal/handlers/utility.go

@@ -0,0 +1,727 @@
+package handlers
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"strings"
+	"time"
+
+	"git.eeqj.de/sneak/neoirc/internal/db"
+	"git.eeqj.de/sneak/neoirc/pkg/irc"
+)
+
+// maxUserhostNicks is the maximum number of nicks allowed
+// in a single USERHOST query (RFC 2812).
+const maxUserhostNicks = 5
+
+// dispatchBodyOnlyCommand routes commands that take
+// (writer, request, sessionID, clientID, nick, bodyLines).
+func (hdlr *Handlers) dispatchBodyOnlyCommand(
+	writer http.ResponseWriter,
+	request *http.Request,
+	sessionID, clientID int64,
+	nick, command string,
+	bodyLines func() []string,
+) {
+	switch command {
+	case irc.CmdAway:
+		hdlr.handleAway(
+			writer, request,
+			sessionID, clientID, nick, bodyLines,
+		)
+	case irc.CmdNick:
+		hdlr.handleNick(
+			writer, request,
+			sessionID, clientID, nick, bodyLines,
+		)
+	case irc.CmdPass:
+		hdlr.handlePass(
+			writer, request,
+			sessionID, clientID, nick, bodyLines,
+		)
+	case irc.CmdInvite:
+		hdlr.handleInvite(
+			writer, request,
+			sessionID, clientID, nick, bodyLines,
+		)
+	}
+}
+
+// dispatchOperCommand routes oper-related commands (OPER,
+// KILL, WALLOPS) to their handlers.
+func (hdlr *Handlers) dispatchOperCommand(
+	writer http.ResponseWriter,
+	request *http.Request,
+	sessionID, clientID int64,
+	nick, command string,
+	bodyLines func() []string,
+) {
+	switch command {
+	case irc.CmdOper:
+		hdlr.handleOper(
+			writer, request,
+			sessionID, clientID, nick, bodyLines,
+		)
+	case irc.CmdKill:
+		hdlr.handleKill(
+			writer, request,
+			sessionID, clientID, nick, bodyLines,
+		)
+	case irc.CmdWallops:
+		hdlr.handleWallops(
+			writer, request,
+			sessionID, clientID, nick, bodyLines,
+		)
+	}
+}
+
+// handleUserhost handles the USERHOST command.
+// Returns user@host info for up to 5 nicks.
+func (hdlr *Handlers) handleUserhost(
+	writer http.ResponseWriter,
+	request *http.Request,
+	sessionID, clientID int64,
+	nick string,
+	bodyLines func() []string,
+) {
+	ctx := request.Context()
+
+	lines := bodyLines()
+	if len(lines) == 0 {
+		hdlr.respondIRCError(
+			writer, request, clientID, sessionID,
+			irc.ErrNeedMoreParams, nick,
+			[]string{irc.CmdUserhost},
+			"Not enough parameters",
+		)
+
+		return
+	}
+
+	// Limit to 5 nicks per RFC 2812.
+	nicks := lines
+	if len(nicks) > maxUserhostNicks {
+		nicks = nicks[:maxUserhostNicks]
+	}
+
+	infos, err := hdlr.params.Database.GetUserhostInfo(
+		ctx, nicks,
+	)
+	if err != nil {
+		hdlr.log.Error(
+			"userhost query failed", "error", err,
+		)
+		hdlr.respondError(
+			writer, request,
+			"internal error",
+			http.StatusInternalServerError,
+		)
+
+		return
+	}
+
+	replyStr := hdlr.buildUserhostReply(infos)
+
+	hdlr.enqueueNumeric(
+		ctx, clientID, irc.RplUserHost, nick, nil,
+		replyStr,
+	)
+
+	hdlr.broker.Notify(sessionID)
+	hdlr.respondJSON(writer, request,
+		map[string]string{"status": "ok"},
+		http.StatusOK)
+}
+
+// buildUserhostReply builds the RPL_USERHOST reply
+// string per RFC 2812.
+func (hdlr *Handlers) buildUserhostReply(
+	infos []db.UserhostInfo,
+) string {
+	replies := make([]string, 0, len(infos))
+
+	for idx := range infos {
+		info := &infos[idx]
+
+		username := info.Username
+		if username == "" {
+			username = info.Nick
+		}
+
+		hostname := info.Hostname
+		if hostname == "" {
+			hostname = hdlr.serverName()
+		}
+
+		operStar := ""
+		if info.IsOper {
+			operStar = "*"
+		}
+
+		awayPrefix := "+"
+		if info.AwayMessage != "" {
+			awayPrefix = "-"
+		}
+
+		replies = append(replies,
+			info.Nick+operStar+"="+
+				awayPrefix+username+"@"+hostname,
+		)
+	}
+
+	return strings.Join(replies, " ")
+}
+
+// handleVersion handles the VERSION command.
+// Returns the server version string.
+func (hdlr *Handlers) handleVersion(
+	writer http.ResponseWriter,
+	request *http.Request,
+	sessionID, clientID int64,
+	nick string,
+) {
+	ctx := request.Context()
+	srvName := hdlr.serverName()
+	version := hdlr.serverVersion()
+
+	// 351 RPL_VERSION
+	hdlr.enqueueNumeric(
+		ctx, clientID, irc.RplVersion, nick,
+		[]string{version + ".", srvName},
+		"",
+	)
+
+	hdlr.broker.Notify(sessionID)
+	hdlr.respondJSON(writer, request,
+		map[string]string{"status": "ok"},
+		http.StatusOK)
+}
+
+// handleAdmin handles the ADMIN command.
+// Returns server admin contact info.
+func (hdlr *Handlers) handleAdmin(
+	writer http.ResponseWriter,
+	request *http.Request,
+	sessionID, clientID int64,
+	nick string,
+) {
+	ctx := request.Context()
+	srvName := hdlr.serverName()
+
+	// 256 RPL_ADMINME
+	hdlr.enqueueNumeric(
+		ctx, clientID, irc.RplAdminMe, nick,
+		[]string{srvName},
+		"Administrative info",
+	)
+
+	// 257 RPL_ADMINLOC1
+	hdlr.enqueueNumeric(
+		ctx, clientID, irc.RplAdminLoc1, nick, nil,
+		"neoirc server",
+	)
+
+	// 258 RPL_ADMINLOC2
+	hdlr.enqueueNumeric(
+		ctx, clientID, irc.RplAdminLoc2, nick, nil,
+		"IRC over HTTP",
+	)
+
+	// 259 RPL_ADMINEMAIL
+	hdlr.enqueueNumeric(
+		ctx, clientID, irc.RplAdminEmail, nick, nil,
+		"admin@"+srvName,
+	)
+
+	hdlr.broker.Notify(sessionID)
+	hdlr.respondJSON(writer, request,
+		map[string]string{"status": "ok"},
+		http.StatusOK)
+}
+
+// handleInfo handles the INFO command.
+// Returns server software information.
+func (hdlr *Handlers) handleInfo(
+	writer http.ResponseWriter,
+	request *http.Request,
+	sessionID, clientID int64,
+	nick string,
+) {
+	ctx := request.Context()
+	version := hdlr.serverVersion()
+
+	infoLines := []string{
+		"neoirc — IRC semantics over HTTP",
+		"Version: " + version,
+		"Written in Go",
+		"Started: " +
+			hdlr.params.Globals.StartTime.
+				Format(time.RFC1123),
+	}
+
+	for _, line := range infoLines {
+		// 371 RPL_INFO
+		hdlr.enqueueNumeric(
+			ctx, clientID, irc.RplInfo, nick, nil,
+			line,
+		)
+	}
+
+	// 374 RPL_ENDOFINFO
+	hdlr.enqueueNumeric(
+		ctx, clientID, irc.RplEndOfInfo, nick, nil,
+		"End of /INFO list",
+	)
+
+	hdlr.broker.Notify(sessionID)
+	hdlr.respondJSON(writer, request,
+		map[string]string{"status": "ok"},
+		http.StatusOK)
+}
+
+// handleTime handles the TIME command.
+// Returns the server's local time in RFC format.
+func (hdlr *Handlers) handleTime(
+	writer http.ResponseWriter,
+	request *http.Request,
+	sessionID, clientID int64,
+	nick string,
+) {
+	ctx := request.Context()
+	srvName := hdlr.serverName()
+
+	// 391 RPL_TIME
+	hdlr.enqueueNumeric(
+		ctx, clientID, irc.RplTime, nick,
+		[]string{srvName},
+		time.Now().Format(time.RFC1123),
+	)
+
+	hdlr.broker.Notify(sessionID)
+	hdlr.respondJSON(writer, request,
+		map[string]string{"status": "ok"},
+		http.StatusOK)
+}
+
+// handleKill handles the KILL command.
+// Forcibly disconnects a user (oper only).
+func (hdlr *Handlers) handleKill(
+	writer http.ResponseWriter,
+	request *http.Request,
+	sessionID, clientID int64,
+	nick string,
+	bodyLines func() []string,
+) {
+	ctx := request.Context()
+
+	// Check oper status.
+	isOper, err := hdlr.params.Database.IsSessionOper(
+		ctx, sessionID,
+	)
+	if err != nil || !isOper {
+		hdlr.respondIRCError(
+			writer, request, clientID, sessionID,
+			irc.ErrNoPrivileges, nick, nil,
+			"Permission Denied- You're not an IRC operator",
+		)
+
+		return
+	}
+
+	lines := bodyLines()
+	if len(lines) == 0 {
+		hdlr.respondIRCError(
+			writer, request, clientID, sessionID,
+			irc.ErrNeedMoreParams, nick,
+			[]string{irc.CmdKill},
+			"Not enough parameters",
+		)
+
+		return
+	}
+
+	targetNick := strings.TrimSpace(lines[0])
+	if targetNick == "" {
+		hdlr.respondIRCError(
+			writer, request, clientID, sessionID,
+			irc.ErrNeedMoreParams, nick,
+			[]string{irc.CmdKill},
+			"Not enough parameters",
+		)
+
+		return
+	}
+
+	reason := "KILLed"
+	if len(lines) > 1 {
+		reason = lines[1]
+	}
+
+	targetSID, lookupErr := hdlr.params.Database.
+		GetSessionByNick(ctx, targetNick)
+	if lookupErr != nil {
+		hdlr.respondIRCError(
+			writer, request, clientID, sessionID,
+			irc.ErrNoSuchNick, nick,
+			[]string{targetNick},
+			"No such nick/channel",
+		)
+
+		return
+	}
+
+	// Do not allow killing yourself.
+	if targetSID == sessionID {
+		hdlr.respondIRCError(
+			writer, request, clientID, sessionID,
+			irc.ErrCantKillServer, nick, nil,
+			"You cannot KILL yourself",
+		)
+
+		return
+	}
+
+	hdlr.executeKillUser(
+		request, targetSID, targetNick, nick, reason,
+	)
+
+	hdlr.respondJSON(writer, request,
+		map[string]string{"status": "ok"},
+		http.StatusOK)
+}
+
+// executeKillUser forcibly disconnects a user: broadcasts
+// QUIT to their channels, parts all channels, and deletes
+// the session.
+func (hdlr *Handlers) executeKillUser(
+	request *http.Request,
+	targetSID int64,
+	targetNick, killerNick, reason string,
+) {
+	ctx := request.Context()
+
+	quitMsg := "Killed (" + killerNick + " (" + reason + "))"
+
+	quitBody, err := json.Marshal([]string{quitMsg})
+	if err != nil {
+		hdlr.log.Error(
+			"marshal kill quit body", "error", err,
+		)
+
+		return
+	}
+
+	channels, _ := hdlr.params.Database.
+		GetSessionChannels(ctx, targetSID)
+
+	notified := map[int64]bool{}
+
+	var dbID int64
+
+	if len(channels) > 0 {
+		dbID, _, _ = hdlr.params.Database.InsertMessage(
+			ctx, irc.CmdQuit, targetNick, "",
+			nil, json.RawMessage(quitBody), nil,
+		)
+	}
+
+	for _, chanInfo := range channels {
+		memberIDs, _ := hdlr.params.Database.
+			GetChannelMemberIDs(ctx, chanInfo.ID)
+
+		for _, mid := range memberIDs {
+			if mid != targetSID && !notified[mid] {
+				notified[mid] = true
+
+				_ = hdlr.params.Database.EnqueueToSession(
+					ctx, mid, dbID,
+				)
+
+				hdlr.broker.Notify(mid)
+			}
+		}
+
+		_ = hdlr.params.Database.PartChannel(
+			ctx, chanInfo.ID, targetSID,
+		)
+
+		_ = hdlr.params.Database.DeleteChannelIfEmpty(
+			ctx, chanInfo.ID,
+		)
+	}
+
+	_ = hdlr.params.Database.DeleteSession(
+		ctx, targetSID,
+	)
+}
+
+// handleWallops handles the WALLOPS command.
+// Broadcasts a message to all users with +w usermode
+// (oper only).
+func (hdlr *Handlers) handleWallops(
+	writer http.ResponseWriter,
+	request *http.Request,
+	sessionID, clientID int64,
+	nick string,
+	bodyLines func() []string,
+) {
+	ctx := request.Context()
+
+	// Check oper status.
+	isOper, err := hdlr.params.Database.IsSessionOper(
+		ctx, sessionID,
+	)
+	if err != nil || !isOper {
+		hdlr.respondIRCError(
+			writer, request, clientID, sessionID,
+			irc.ErrNoPrivileges, nick, nil,
+			"Permission Denied- You're not an IRC operator",
+		)
+
+		return
+	}
+
+	lines := bodyLines()
+	if len(lines) == 0 {
+		hdlr.respondIRCError(
+			writer, request, clientID, sessionID,
+			irc.ErrNeedMoreParams, nick,
+			[]string{irc.CmdWallops},
+			"Not enough parameters",
+		)
+
+		return
+	}
+
+	message := strings.Join(lines, " ")
+
+	wallopsSIDs, err := hdlr.params.Database.
+		GetWallopsSessionIDs(ctx)
+	if err != nil {
+		hdlr.log.Error(
+			"get wallops sessions failed", "error", err,
+		)
+		hdlr.respondError(
+			writer, request,
+			"internal error",
+			http.StatusInternalServerError,
+		)
+
+		return
+	}
+
+	if len(wallopsSIDs) > 0 {
+		body, mErr := json.Marshal([]string{message})
+		if mErr != nil {
+			hdlr.log.Error(
+				"marshal wallops body", "error", mErr,
+			)
+			hdlr.respondError(
+				writer, request,
+				"internal error",
+				http.StatusInternalServerError,
+			)
+
+			return
+		}
+
+		_ = hdlr.fanOutSilent(
+			request, irc.CmdWallops, nick, "*",
+			json.RawMessage(body), wallopsSIDs,
+		)
+	}
+
+	hdlr.respondJSON(writer, request,
+		map[string]string{"status": "ok"},
+		http.StatusOK)
+}
+
+// handleUserMode handles user mode queries and changes
+// (e.g., MODE nick, MODE nick +w).
+func (hdlr *Handlers) handleUserMode(
+	writer http.ResponseWriter,
+	request *http.Request,
+	sessionID, clientID int64,
+	nick, target string,
+	bodyLines func() []string,
+) {
+	ctx := request.Context()
+
+	lines := bodyLines()
+
+	// Mode change requested.
+	if len(lines) > 0 {
+		// Users can only change their own modes.
+		if target != nick && target != "" {
+			hdlr.respondIRCError(
+				writer, request, clientID, sessionID,
+				irc.ErrUsersDoNotMatch, nick, nil,
+				"Can't change mode for other users",
+			)
+
+			return
+		}
+
+		hdlr.applyUserModeChange(
+			writer, request,
+			sessionID, clientID, nick, lines[0],
+		)
+
+		return
+	}
+
+	// Mode query — build the current mode string.
+	modeStr := hdlr.buildUserModeString(ctx, sessionID)
+
+	hdlr.enqueueNumeric(
+		ctx, clientID, irc.RplUmodeIs, nick, nil,
+		modeStr,
+	)
+	hdlr.broker.Notify(sessionID)
+	hdlr.respondJSON(writer, request,
+		map[string]string{"status": "ok"},
+		http.StatusOK)
+}
+
+// buildUserModeString constructs the mode string for a
+// user (e.g., "+ow" for oper+wallops).
+func (hdlr *Handlers) buildUserModeString(
+	ctx context.Context,
+	sessionID int64,
+) string {
+	modes := "+"
+
+	isOper, err := hdlr.params.Database.IsSessionOper(
+		ctx, sessionID,
+	)
+	if err == nil && isOper {
+		modes += "o"
+	}
+
+	isWallops, err := hdlr.params.Database.IsSessionWallops(
+		ctx, sessionID,
+	)
+	if err == nil && isWallops {
+		modes += "w"
+	}
+
+	return modes
+}
+
+// applyUserModeChange applies a user mode change string
+// (e.g., "+w", "-w").
+func (hdlr *Handlers) applyUserModeChange(
+	writer http.ResponseWriter,
+	request *http.Request,
+	sessionID, clientID int64,
+	nick, modeStr string,
+) {
+	ctx := request.Context()
+
+	if len(modeStr) < 2 { //nolint:mnd // +/- and mode char
+		hdlr.respondIRCError(
+			writer, request, clientID, sessionID,
+			irc.ErrUmodeUnknownFlag, nick, nil,
+			"Unknown MODE flag",
+		)
+
+		return
+	}
+
+	adding := modeStr[0] == '+'
+	modeChar := modeStr[1:]
+
+	applied, err := hdlr.applyModeChar(
+		ctx, writer, request,
+		sessionID, clientID, nick,
+		modeChar, adding,
+	)
+	if err != nil || !applied {
+		return
+	}
+
+	newModes := hdlr.buildUserModeString(ctx, sessionID)
+
+	hdlr.enqueueNumeric(
+		ctx, clientID, irc.RplUmodeIs, nick, nil,
+		newModes,
+	)
+
+	hdlr.broker.Notify(sessionID)
+	hdlr.respondJSON(writer, request,
+		map[string]string{"status": "ok"},
+		http.StatusOK)
+}
+
+// applyModeChar applies a single user mode character.
+// Returns (applied, error).
+func (hdlr *Handlers) applyModeChar(
+	ctx context.Context,
+	writer http.ResponseWriter,
+	request *http.Request,
+	sessionID, clientID int64,
+	nick, modeChar string,
+	adding bool,
+) (bool, error) {
+	switch modeChar {
+	case "w":
+		err := hdlr.params.Database.SetSessionWallops(
+			ctx, sessionID, adding,
+		)
+		if err != nil {
+			hdlr.log.Error(
+				"set wallops mode failed", "error", err,
+			)
+			hdlr.respondError(
+				writer, request,
+				"internal error",
+				http.StatusInternalServerError,
+			)
+
+			return false, fmt.Errorf(
+				"set wallops: %w", err,
+			)
+		}
+	case "o":
+		// +o cannot be set via MODE, only via OPER.
+		if adding {
+			hdlr.respondIRCError(
+				writer, request, clientID, sessionID,
+				irc.ErrUmodeUnknownFlag, nick, nil,
+				"Unknown MODE flag",
+			)
+
+			return false, nil
+		}
+
+		err := hdlr.params.Database.SetSessionOper(
+			ctx, sessionID, false,
+		)
+		if err != nil {
+			hdlr.log.Error(
+				"clear oper mode failed", "error", err,
+			)
+			hdlr.respondError(
+				writer, request,
+				"internal error",
+				http.StatusInternalServerError,
+			)
+
+			return false, fmt.Errorf(
+				"clear oper: %w", err,
+			)
+		}
+	default:
+		hdlr.respondIRCError(
+			writer, request, clientID, sessionID,
+			irc.ErrUmodeUnknownFlag, nick, nil,
+			"Unknown MODE flag",
+		)
+
+		return false, nil
+	}
+
+	return true, nil
+}

internal/handlers/utility_test.go

@@ -0,0 +1,982 @@
+// Tests for Tier 3 utility IRC commands: USERHOST,
+// VERSION, ADMIN, INFO, TIME, KILL, WALLOPS.
+//
+//nolint:paralleltest
+package handlers_test
+
+import (
+	"strings"
+	"testing"
+)
+
+// --- USERHOST ---
+
+func TestUserhostSingleNick(t *testing.T) {
+	tserver := newTestServer(t)
+
+	token := tserver.createSession("alice")
+	_, lastID := tserver.pollMessages(token, 0)
+
+	tserver.sendCommand(token, map[string]any{
+		commandKey: "USERHOST",
+		bodyKey:    []string{"alice"},
+	})
+
+	msgs, _ := tserver.pollMessages(token, lastID)
+
+	// Expect 302 RPL_USERHOST.
+	msg := findNumericWithParams(msgs, "302")
+	if msg == nil {
+		t.Fatalf(
+			"expected RPL_USERHOST (302), got %v",
+			msgs,
+		)
+	}
+
+	// Body should contain "alice" with the
+	// nick=+user@host format.
+	body := getNumericBody(msg)
+	if !strings.Contains(body, "alice") {
+		t.Fatalf(
+			"expected body to contain 'alice', got %q",
+			body,
+		)
+	}
+
+	// '+' means not away.
+	if !strings.Contains(body, "=+") {
+		t.Fatalf(
+			"expected not-away prefix '=+', got %q",
+			body,
+		)
+	}
+}
+
+func TestUserhostMultipleNicks(t *testing.T) {
+	tserver := newTestServer(t)
+
+	token1 := tserver.createSession("bob")
+	token2 := tserver.createSession("carol")
+
+	_ = token2
+
+	_, lastID := tserver.pollMessages(token1, 0)
+
+	tserver.sendCommand(token1, map[string]any{
+		commandKey: "USERHOST",
+		bodyKey:    []string{"bob", "carol"},
+	})
+
+	msgs, _ := tserver.pollMessages(token1, lastID)
+
+	msg := findNumericWithParams(msgs, "302")
+	if msg == nil {
+		t.Fatalf(
+			"expected RPL_USERHOST (302), got %v",
+			msgs,
+		)
+	}
+
+	body := getNumericBody(msg)
+	if !strings.Contains(body, "bob") {
+		t.Fatalf(
+			"expected body to contain 'bob', got %q",
+			body,
+		)
+	}
+
+	if !strings.Contains(body, "carol") {
+		t.Fatalf(
+			"expected body to contain 'carol', got %q",
+			body,
+		)
+	}
+}
+
+func TestUserhostNonexistentNick(t *testing.T) {
+	tserver := newTestServer(t)
+
+	token := tserver.createSession("dave")
+	_, lastID := tserver.pollMessages(token, 0)
+
+	tserver.sendCommand(token, map[string]any{
+		commandKey: "USERHOST",
+		bodyKey:    []string{"nobody"},
+	})
+
+	msgs, _ := tserver.pollMessages(token, lastID)
+
+	// Should still get 302 but with empty body.
+	msg := findNumericWithParams(msgs, "302")
+	if msg == nil {
+		t.Fatalf(
+			"expected RPL_USERHOST (302), got %v",
+			msgs,
+		)
+	}
+}
+
+func TestUserhostNoParams(t *testing.T) {
+	tserver := newTestServer(t)
+
+	token := tserver.createSession("eve")
+	_, lastID := tserver.pollMessages(token, 0)
+
+	tserver.sendCommand(token, map[string]any{
+		commandKey: "USERHOST",
+	})
+
+	msgs, _ := tserver.pollMessages(token, lastID)
+
+	// Expect 461 ERR_NEEDMOREPARAMS.
+	if !findNumeric(msgs, "461") {
+		t.Fatalf(
+			"expected ERR_NEEDMOREPARAMS (461), got %v",
+			msgs,
+		)
+	}
+}
+
+func TestUserhostShowsOper(t *testing.T) {
+	tserver := newTestServerWithOper(t)
+
+	token := tserver.createSession("opernick")
+	_, lastID := tserver.pollMessages(token, 0)
+
+	// Authenticate as oper.
+	tserver.sendCommand(token, map[string]any{
+		commandKey: "OPER",
+		bodyKey:    []string{testOperName, testOperPassword},
+	})
+
+	_, lastID = tserver.pollMessages(token, lastID)
+
+	// USERHOST should show '*' for oper.
+	tserver.sendCommand(token, map[string]any{
+		commandKey: "USERHOST",
+		bodyKey:    []string{"opernick"},
+	})
+
+	msgs, _ := tserver.pollMessages(token, lastID)
+
+	msg := findNumericWithParams(msgs, "302")
+	if msg == nil {
+		t.Fatalf(
+			"expected RPL_USERHOST (302), got %v",
+			msgs,
+		)
+	}
+
+	body := getNumericBody(msg)
+	if !strings.Contains(body, "opernick*=") {
+		t.Fatalf(
+			"expected oper '*' in reply, got %q",
+			body,
+		)
+	}
+}
+
+func TestUserhostShowsAway(t *testing.T) {
+	tserver := newTestServer(t)
+
+	token := tserver.createSession("awaynick")
+	_, lastID := tserver.pollMessages(token, 0)
+
+	// Set away.
+	tserver.sendCommand(token, map[string]any{
+		commandKey: "AWAY",
+		bodyKey:    []string{"gone fishing"},
+	})
+
+	_, lastID = tserver.pollMessages(token, lastID)
+
+	// USERHOST should show '-' for away.
+	tserver.sendCommand(token, map[string]any{
+		commandKey: "USERHOST",
+		bodyKey:    []string{"awaynick"},
+	})
+
+	msgs, _ := tserver.pollMessages(token, lastID)
+
+	msg := findNumericWithParams(msgs, "302")
+	if msg == nil {
+		t.Fatalf(
+			"expected RPL_USERHOST (302), got %v",
+			msgs,
+		)
+	}
+
+	body := getNumericBody(msg)
+	if !strings.Contains(body, "=-") {
+		t.Fatalf(
+			"expected away prefix '=-' in reply, got %q",
+			body,
+		)
+	}
+}
+
+// --- VERSION ---
+
+func TestVersion(t *testing.T) {
+	tserver := newTestServer(t)
+
+	token := tserver.createSession("frank")
+	_, lastID := tserver.pollMessages(token, 0)
+
+	tserver.sendCommand(token, map[string]any{
+		commandKey: "VERSION",
+	})
+
+	msgs, _ := tserver.pollMessages(token, lastID)
+
+	// Expect 351 RPL_VERSION.
+	msg := findNumericWithParams(msgs, "351")
+	if msg == nil {
+		t.Fatalf(
+			"expected RPL_VERSION (351), got %v",
+			msgs,
+		)
+	}
+
+	params := getNumericParams(msg)
+	if len(params) == 0 {
+		t.Fatal("expected VERSION params, got none")
+	}
+
+	// First param should contain version string.
+	if !strings.Contains(params[0], "test") {
+		t.Fatalf(
+			"expected version to contain 'test', got %q",
+			params[0],
+		)
+	}
+}
+
+// --- ADMIN ---
+
+func TestAdmin(t *testing.T) {
+	tserver := newTestServer(t)
+
+	token := tserver.createSession("grace")
+	_, lastID := tserver.pollMessages(token, 0)
+
+	tserver.sendCommand(token, map[string]any{
+		commandKey: "ADMIN",
+	})
+
+	msgs, _ := tserver.pollMessages(token, lastID)
+
+	// Expect 256 RPL_ADMINME.
+	if !findNumeric(msgs, "256") {
+		t.Fatalf(
+			"expected RPL_ADMINME (256), got %v",
+			msgs,
+		)
+	}
+
+	// Expect 257 RPL_ADMINLOC1.
+	if !findNumeric(msgs, "257") {
+		t.Fatalf(
+			"expected RPL_ADMINLOC1 (257), got %v",
+			msgs,
+		)
+	}
+
+	// Expect 258 RPL_ADMINLOC2.
+	if !findNumeric(msgs, "258") {
+		t.Fatalf(
+			"expected RPL_ADMINLOC2 (258), got %v",
+			msgs,
+		)
+	}
+
+	// Expect 259 RPL_ADMINEMAIL.
+	if !findNumeric(msgs, "259") {
+		t.Fatalf(
+			"expected RPL_ADMINEMAIL (259), got %v",
+			msgs,
+		)
+	}
+}
+
+// --- INFO ---
+
+func TestInfo(t *testing.T) {
+	tserver := newTestServer(t)
+
+	token := tserver.createSession("hank")
+	_, lastID := tserver.pollMessages(token, 0)
+
+	tserver.sendCommand(token, map[string]any{
+		commandKey: "INFO",
+	})
+
+	msgs, _ := tserver.pollMessages(token, lastID)
+
+	// Expect 371 RPL_INFO (at least one).
+	if !findNumeric(msgs, "371") {
+		t.Fatalf(
+			"expected RPL_INFO (371), got %v",
+			msgs,
+		)
+	}
+
+	// Expect 374 RPL_ENDOFINFO.
+	if !findNumeric(msgs, "374") {
+		t.Fatalf(
+			"expected RPL_ENDOFINFO (374), got %v",
+			msgs,
+		)
+	}
+}
+
+// --- TIME ---
+
+func TestTime(t *testing.T) {
+	tserver := newTestServer(t)
+
+	token := tserver.createSession("iris")
+	_, lastID := tserver.pollMessages(token, 0)
+
+	tserver.sendCommand(token, map[string]any{
+		commandKey: "TIME",
+	})
+
+	msgs, _ := tserver.pollMessages(token, lastID)
+
+	// Expect 391 RPL_TIME.
+	msg := findNumericWithParams(msgs, "391")
+	if msg == nil {
+		t.Fatalf(
+			"expected RPL_TIME (391), got %v",
+			msgs,
+		)
+	}
+}
+
+// --- KILL ---
+
+func TestKillSuccess(t *testing.T) {
+	tserver := newTestServerWithOper(t)
+
+	// Create the victim first.
+	victimToken := tserver.createSession("victim")
+	_ = victimToken
+
+	// Create oper user.
+	operToken := tserver.createSession("killer")
+	_, lastID := tserver.pollMessages(operToken, 0)
+
+	// Authenticate as oper.
+	tserver.sendCommand(operToken, map[string]any{
+		commandKey: "OPER",
+		bodyKey:    []string{testOperName, testOperPassword},
+	})
+
+	_, lastID = tserver.pollMessages(operToken, lastID)
+
+	// Kill the victim.
+	status, result := tserver.sendCommand(
+		operToken, map[string]any{
+			commandKey: "KILL",
+			bodyKey:    []string{"victim", "go away"},
+		},
+	)
+
+	if status != 200 {
+		t.Fatalf("expected 200, got %d: %v", status, result)
+	}
+
+	resultStatus, _ := result[statusKey].(string)
+	if resultStatus != "ok" {
+		t.Fatalf(
+			"expected status ok, got %v",
+			result,
+		)
+	}
+
+	// Verify the victim's session is gone by trying
+	// to WHOIS them.
+	tserver.sendCommand(operToken, map[string]any{
+		commandKey: "WHOIS",
+		toKey:      "victim",
+	})
+
+	msgs, _ := tserver.pollMessages(operToken, lastID)
+
+	// Should get 401 ERR_NOSUCHNICK.
+	if !findNumeric(msgs, "401") {
+		t.Fatalf(
+			"expected victim to be gone (401), got %v",
+			msgs,
+		)
+	}
+}
+
+func TestKillNotOper(t *testing.T) {
+	tserver := newTestServer(t)
+
+	_ = tserver.createSession("target")
+
+	token := tserver.createSession("notoper")
+	_, lastID := tserver.pollMessages(token, 0)
+
+	tserver.sendCommand(token, map[string]any{
+		commandKey: "KILL",
+		bodyKey:    []string{"target", "no reason"},
+	})
+
+	msgs, _ := tserver.pollMessages(token, lastID)
+
+	// Expect 481 ERR_NOPRIVILEGES.
+	if !findNumeric(msgs, "481") {
+		t.Fatalf(
+			"expected ERR_NOPRIVILEGES (481), got %v",
+			msgs,
+		)
+	}
+}
+
+func TestKillNoParams(t *testing.T) {
+	tserver := newTestServerWithOper(t)
+
+	token := tserver.createSession("opertest")
+	_, lastID := tserver.pollMessages(token, 0)
+
+	tserver.sendCommand(token, map[string]any{
+		commandKey: "OPER",
+		bodyKey:    []string{testOperName, testOperPassword},
+	})
+
+	_, lastID = tserver.pollMessages(token, lastID)
+
+	tserver.sendCommand(token, map[string]any{
+		commandKey: "KILL",
+	})
+
+	msgs, _ := tserver.pollMessages(token, lastID)
+
+	// Expect 461 ERR_NEEDMOREPARAMS.
+	if !findNumeric(msgs, "461") {
+		t.Fatalf(
+			"expected ERR_NEEDMOREPARAMS (461), got %v",
+			msgs,
+		)
+	}
+}
+
+// sendOperKillCommand is a helper that creates an oper
+// session, authenticates, then sends KILL with the given
+// target nick, and returns the resulting messages.
+func sendOperKillCommand(
+	t *testing.T,
+	tserver *testServer,
+	operNick, targetNick string,
+) []map[string]any {
+	t.Helper()
+
+	token := tserver.createSession(operNick)
+	_, lastID := tserver.pollMessages(token, 0)
+
+	tserver.sendCommand(token, map[string]any{
+		commandKey: "OPER",
+		bodyKey:    []string{testOperName, testOperPassword},
+	})
+
+	_, lastID = tserver.pollMessages(token, lastID)
+
+	tserver.sendCommand(token, map[string]any{
+		commandKey: "KILL",
+		bodyKey:    []string{targetNick},
+	})
+
+	msgs, _ := tserver.pollMessages(token, lastID)
+
+	return msgs
+}
+
+func TestKillNonexistentUser(t *testing.T) {
+	tserver := newTestServerWithOper(t)
+
+	msgs := sendOperKillCommand(
+		t, tserver, "opertest2", "ghost",
+	)
+
+	// Expect 401 ERR_NOSUCHNICK.
+	if !findNumeric(msgs, "401") {
+		t.Fatalf(
+			"expected ERR_NOSUCHNICK (401), got %v",
+			msgs,
+		)
+	}
+}
+
+func TestKillSelf(t *testing.T) {
+	tserver := newTestServerWithOper(t)
+
+	msgs := sendOperKillCommand(
+		t, tserver, "selfkiller", "selfkiller",
+	)
+
+	// Expect 483 ERR_CANTKILLSERVER.
+	if !findNumeric(msgs, "483") {
+		t.Fatalf(
+			"expected ERR_CANTKILLSERVER (483), got %v",
+			msgs,
+		)
+	}
+}
+
+func TestKillBroadcastsQuit(t *testing.T) {
+	tserver := newTestServerWithOper(t)
+
+	// Create victim and join a channel.
+	victimToken := tserver.createSession("vuser")
+
+	tserver.sendCommand(victimToken, map[string]any{
+		commandKey: joinCmd,
+		toKey:      "#killtest",
+	})
+
+	// Create observer and join same channel.
+	observerToken := tserver.createSession("observer")
+
+	tserver.sendCommand(observerToken, map[string]any{
+		commandKey: joinCmd,
+		toKey:      "#killtest",
+	})
+
+	_, lastObs := tserver.pollMessages(observerToken, 0)
+
+	// Create oper.
+	operToken := tserver.createSession("theoper2")
+
+	tserver.pollMessages(operToken, 0)
+
+	tserver.sendCommand(operToken, map[string]any{
+		commandKey: "OPER",
+		bodyKey:    []string{testOperName, testOperPassword},
+	})
+
+	tserver.pollMessages(operToken, 0)
+
+	// Kill the victim.
+	tserver.sendCommand(operToken, map[string]any{
+		commandKey: "KILL",
+		bodyKey:    []string{"vuser", "testing kill"},
+	})
+
+	// Observer should see a QUIT message.
+	msgs, _ := tserver.pollMessages(observerToken, lastObs)
+
+	foundQuit := false
+
+	for _, msg := range msgs {
+		cmd, _ := msg["command"].(string)
+		if cmd == "QUIT" {
+			from, _ := msg["from"].(string)
+			if from == "vuser" {
+				foundQuit = true
+
+				break
+			}
+		}
+	}
+
+	if !foundQuit {
+		t.Fatalf(
+			"expected QUIT from vuser, got %v",
+			msgs,
+		)
+	}
+}
+
+// --- WALLOPS ---
+
+func TestWallopsSuccess(t *testing.T) {
+	tserver := newTestServerWithOper(t)
+
+	// Create receiver with +w.
+	receiverToken := tserver.createSession("receiver")
+
+	tserver.sendCommand(receiverToken, map[string]any{
+		commandKey: "MODE",
+		toKey:      "receiver",
+		bodyKey:    []string{"+w"},
+	})
+
+	_, lastRecv := tserver.pollMessages(receiverToken, 0)
+
+	// Create oper.
+	operToken := tserver.createSession("walloper")
+
+	tserver.pollMessages(operToken, 0)
+
+	tserver.sendCommand(operToken, map[string]any{
+		commandKey: "OPER",
+		bodyKey:    []string{testOperName, testOperPassword},
+	})
+
+	tserver.pollMessages(operToken, 0)
+
+	// Also set +w on oper so they receive it too.
+	tserver.sendCommand(operToken, map[string]any{
+		commandKey: "MODE",
+		toKey:      "walloper",
+		bodyKey:    []string{"+w"},
+	})
+
+	tserver.pollMessages(operToken, 0)
+
+	// Send WALLOPS.
+	tserver.sendCommand(operToken, map[string]any{
+		commandKey: "WALLOPS",
+		bodyKey:    []string{"server going down"},
+	})
+
+	// Receiver should get the WALLOPS message.
+	msgs, _ := tserver.pollMessages(receiverToken, lastRecv)
+
+	foundWallops := false
+
+	for _, msg := range msgs {
+		cmd, _ := msg["command"].(string)
+		if cmd == "WALLOPS" {
+			foundWallops = true
+
+			break
+		}
+	}
+
+	if !foundWallops {
+		t.Fatalf(
+			"expected WALLOPS message, got %v",
+			msgs,
+		)
+	}
+}
+
+func TestWallopsNotOper(t *testing.T) {
+	tserver := newTestServer(t)
+
+	token := tserver.createSession("notoper2")
+	_, lastID := tserver.pollMessages(token, 0)
+
+	tserver.sendCommand(token, map[string]any{
+		commandKey: "WALLOPS",
+		bodyKey:    []string{"hello"},
+	})
+
+	msgs, _ := tserver.pollMessages(token, lastID)
+
+	// Expect 481 ERR_NOPRIVILEGES.
+	if !findNumeric(msgs, "481") {
+		t.Fatalf(
+			"expected ERR_NOPRIVILEGES (481), got %v",
+			msgs,
+		)
+	}
+}
+
+func TestWallopsNoParams(t *testing.T) {
+	tserver := newTestServerWithOper(t)
+
+	token := tserver.createSession("operempty")
+	_, lastID := tserver.pollMessages(token, 0)
+
+	tserver.sendCommand(token, map[string]any{
+		commandKey: "OPER",
+		bodyKey:    []string{testOperName, testOperPassword},
+	})
+
+	_, lastID = tserver.pollMessages(token, lastID)
+
+	tserver.sendCommand(token, map[string]any{
+		commandKey: "WALLOPS",
+	})
+
+	msgs, _ := tserver.pollMessages(token, lastID)
+
+	// Expect 461 ERR_NEEDMOREPARAMS.
+	if !findNumeric(msgs, "461") {
+		t.Fatalf(
+			"expected ERR_NEEDMOREPARAMS (461), got %v",
+			msgs,
+		)
+	}
+}
+
+func TestWallopsNotReceivedWithoutW(t *testing.T) {
+	tserver := newTestServerWithOper(t)
+
+	// Create receiver WITHOUT +w.
+	receiverToken := tserver.createSession("nowallops")
+	_, lastRecv := tserver.pollMessages(receiverToken, 0)
+
+	// Create oper.
+	operToken := tserver.createSession("walloper2")
+
+	tserver.pollMessages(operToken, 0)
+
+	tserver.sendCommand(operToken, map[string]any{
+		commandKey: "OPER",
+		bodyKey:    []string{testOperName, testOperPassword},
+	})
+
+	tserver.pollMessages(operToken, 0)
+
+	// Send WALLOPS.
+	tserver.sendCommand(operToken, map[string]any{
+		commandKey: "WALLOPS",
+		bodyKey:    []string{"secret message"},
+	})
+
+	// Receiver should NOT get the WALLOPS message.
+	msgs, _ := tserver.pollMessages(receiverToken, lastRecv)
+
+	for _, msg := range msgs {
+		cmd, _ := msg["command"].(string)
+		if cmd == "WALLOPS" {
+			t.Fatalf(
+				"did not expect WALLOPS for user "+
+					"without +w, got %v",
+				msgs,
+			)
+		}
+	}
+}
+
+// --- User Mode +w ---
+
+func TestUserModeSetW(t *testing.T) {
+	tserver := newTestServer(t)
+
+	token := tserver.createSession("wmoder")
+	_, lastID := tserver.pollMessages(token, 0)
+
+	// Set +w.
+	tserver.sendCommand(token, map[string]any{
+		commandKey: "MODE",
+		toKey:      "wmoder",
+		bodyKey:    []string{"+w"},
+	})
+
+	msgs, lastID := tserver.pollMessages(token, lastID)
+
+	// Expect 221 RPL_UMODEIS with "+w".
+	msg := findNumericWithParams(msgs, "221")
+	if msg == nil {
+		t.Fatalf(
+			"expected RPL_UMODEIS (221), got %v",
+			msgs,
+		)
+	}
+
+	body := getNumericBody(msg)
+	if !strings.Contains(body, "w") {
+		t.Fatalf(
+			"expected mode string to contain 'w', got %q",
+			body,
+		)
+	}
+
+	// Now query mode.
+	tserver.sendCommand(token, map[string]any{
+		commandKey: "MODE",
+		toKey:      "wmoder",
+	})
+
+	msgs, _ = tserver.pollMessages(token, lastID)
+
+	msg = findNumericWithParams(msgs, "221")
+	if msg == nil {
+		t.Fatalf(
+			"expected RPL_UMODEIS (221) on query, got %v",
+			msgs,
+		)
+	}
+
+	body = getNumericBody(msg)
+	if !strings.Contains(body, "w") {
+		t.Fatalf(
+			"expected mode '+w' in query, got %q",
+			body,
+		)
+	}
+}
+
+func TestUserModeUnsetW(t *testing.T) {
+	tserver := newTestServer(t)
+
+	token := tserver.createSession("wunsetter")
+	_, lastID := tserver.pollMessages(token, 0)
+
+	// Set +w first.
+	tserver.sendCommand(token, map[string]any{
+		commandKey: "MODE",
+		toKey:      "wunsetter",
+		bodyKey:    []string{"+w"},
+	})
+
+	_, lastID = tserver.pollMessages(token, lastID)
+
+	// Unset -w.
+	tserver.sendCommand(token, map[string]any{
+		commandKey: "MODE",
+		toKey:      "wunsetter",
+		bodyKey:    []string{"-w"},
+	})
+
+	msgs, _ := tserver.pollMessages(token, lastID)
+
+	msg := findNumericWithParams(msgs, "221")
+	if msg == nil {
+		t.Fatalf(
+			"expected RPL_UMODEIS (221), got %v",
+			msgs,
+		)
+	}
+
+	body := getNumericBody(msg)
+	if strings.Contains(body, "w") {
+		t.Fatalf(
+			"expected 'w' to be removed, got %q",
+			body,
+		)
+	}
+}
+
+func TestUserModeUnknownFlag(t *testing.T) {
+	tserver := newTestServer(t)
+
+	token := tserver.createSession("badmode")
+	_, lastID := tserver.pollMessages(token, 0)
+
+	tserver.sendCommand(token, map[string]any{
+		commandKey: "MODE",
+		toKey:      "badmode",
+		bodyKey:    []string{"+z"},
+	})
+
+	msgs, _ := tserver.pollMessages(token, lastID)
+
+	// Expect 501 ERR_UMODEUNKNOWNFLAG.
+	if !findNumeric(msgs, "501") {
+		t.Fatalf(
+			"expected ERR_UMODEUNKNOWNFLAG (501), got %v",
+			msgs,
+		)
+	}
+}
+
+func TestUserModeCannotSetO(t *testing.T) {
+	tserver := newTestServer(t)
+
+	token := tserver.createSession("tryoper")
+	_, lastID := tserver.pollMessages(token, 0)
+
+	// Try to set +o via MODE (should fail).
+	tserver.sendCommand(token, map[string]any{
+		commandKey: "MODE",
+		toKey:      "tryoper",
+		bodyKey:    []string{"+o"},
+	})
+
+	msgs, _ := tserver.pollMessages(token, lastID)
+
+	// Expect 501 ERR_UMODEUNKNOWNFLAG.
+	if !findNumeric(msgs, "501") {
+		t.Fatalf(
+			"expected ERR_UMODEUNKNOWNFLAG (501), got %v",
+			msgs,
+		)
+	}
+}
+
+func TestUserModeDeoper(t *testing.T) {
+	tserver := newTestServerWithOper(t)
+
+	token := tserver.createSession("deoper")
+	_, lastID := tserver.pollMessages(token, 0)
+
+	// Authenticate as oper.
+	tserver.sendCommand(token, map[string]any{
+		commandKey: "OPER",
+		bodyKey:    []string{testOperName, testOperPassword},
+	})
+
+	_, lastID = tserver.pollMessages(token, lastID)
+
+	// Use MODE -o to de-oper.
+	tserver.sendCommand(token, map[string]any{
+		commandKey: "MODE",
+		toKey:      "deoper",
+		bodyKey:    []string{"-o"},
+	})
+
+	msgs, _ := tserver.pollMessages(token, lastID)
+
+	msg := findNumericWithParams(msgs, "221")
+	if msg == nil {
+		t.Fatalf(
+			"expected RPL_UMODEIS (221), got %v",
+			msgs,
+		)
+	}
+
+	body := getNumericBody(msg)
+	if strings.Contains(body, "o") {
+		t.Fatalf(
+			"expected 'o' to be removed, got %q",
+			body,
+		)
+	}
+}
+
+func TestUserModeCannotChangeOtherUser(t *testing.T) {
+	tserver := newTestServer(t)
+
+	_ = tserver.createSession("other")
+
+	token := tserver.createSession("changer")
+	_, lastID := tserver.pollMessages(token, 0)
+
+	// Try to change another user's mode.
+	tserver.sendCommand(token, map[string]any{
+		commandKey: "MODE",
+		toKey:      "other",
+		bodyKey:    []string{"+w"},
+	})
+
+	msgs, _ := tserver.pollMessages(token, lastID)
+
+	// Expect 502 ERR_USERSDONTMATCH.
+	if !findNumeric(msgs, "502") {
+		t.Fatalf(
+			"expected ERR_USERSDONTMATCH (502), got %v",
+			msgs,
+		)
+	}
+}
+
+// getNumericBody extracts the body text from a numeric
+// message. The body is stored as a JSON array; this
+// returns the first element.
+func getNumericBody(msg map[string]any) string {
+	raw, exists := msg["body"]
+	if !exists || raw == nil {
+		return ""
+	}
+
+	arr, isArr := raw.([]any)
+	if !isArr || len(arr) == 0 {
+		return ""
+	}
+
+	str, isStr := arr[0].(string)
+	if !isStr {
+		return ""
+	}
+
+	return str
+}

pkg/irc/commands.go

@@ -2,24 +2,32 @@ package irc
 
 // IRC command names (RFC 1459 / RFC 2812).
 const (
-	CmdAway    = "AWAY"
+	CmdAdmin    = "ADMIN"
-	CmdJoin    = "JOIN"
+	CmdAway     = "AWAY"
-	CmdKick    = "KICK"
+	CmdInfo     = "INFO"
-	CmdList    = "LIST"
+	CmdInvite   = "INVITE"
-	CmdLusers  = "LUSERS"
+	CmdJoin     = "JOIN"
-	CmdMode    = "MODE"
+	CmdKick     = "KICK"
-	CmdMotd    = "MOTD"
+	CmdKill     = "KILL"
-	CmdNames   = "NAMES"
+	CmdList     = "LIST"
-	CmdNick    = "NICK"
+	CmdLusers   = "LUSERS"
-	CmdNotice  = "NOTICE"
+	CmdMode     = "MODE"
-	CmdOper    = "OPER"
+	CmdMotd     = "MOTD"
-	CmdPass    = "PASS"
+	CmdNames    = "NAMES"
-	CmdPart    = "PART"
+	CmdNick     = "NICK"
-	CmdPing    = "PING"
+	CmdNotice   = "NOTICE"
-	CmdPong    = "PONG"
+	CmdOper     = "OPER"
-	CmdPrivmsg = "PRIVMSG"
+	CmdPass     = "PASS"
-	CmdQuit    = "QUIT"
+	CmdPart     = "PART"
-	CmdTopic   = "TOPIC"
+	CmdPing     = "PING"
-	CmdWho     = "WHO"
+	CmdPong     = "PONG"
-	CmdWhois   = "WHOIS"
+	CmdPrivmsg  = "PRIVMSG"
+	CmdQuit     = "QUIT"
+	CmdTime     = "TIME"
+	CmdTopic    = "TOPIC"
+	CmdUserhost = "USERHOST"
+	CmdVersion  = "VERSION"
+	CmdWallops  = "WALLOPS"
+	CmdWho      = "WHO"
+	CmdWhois    = "WHOIS"
 )