feat(moderation): appeals (6c) + Discord reversal on approve (6d)

Players whose linked Discord identity was banned or muted can now submit
an appeal from the portal and track it; staff get a queue in the admin
moderation section to claim and resolve (approve/deny) appeals. Approving
a ban/mute appeal best-effort asks the Discord bot to reverse the action
(unban / clear timeout) via the internal API and posts a mod-log embed; a
down bot never fails the resolution (reversal_status is recorded).

- Schema: new server-owned `appeals` table (no cross-owner FK to
  mod_actions; existence validated in app code).
- Server: model/appeals/* + player appeals controller (submit/mine/
  eligible/withdraw) and admin queue handlers (list/claim/resolve/
  per-user) under the existing admin+moderator gate; one-active-appeal
  enforced app-side; eligibility keyed on the caller's linked Discord id.
- 6d: bot POST /internal/mod-reverse (+ modLog.postReversal) and
  server botInternalClient.reverseModAction, wired into resolve().
- Client: admin Appeals queue + resolve modal, ModerationUser appeals
  tab, player Appeals page (submit/withdraw), nav + routes + api methods.
- Docs: swagger annotations + component schemas, regenerated output.
- Tests: appeals controller + pure suites (server npm test 224 green).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XmHdsbnLzDMAVQkAoTQSBe

bot/src/discord/modLog.js

@@ -43,6 +43,34 @@ async function record({ client, guildId, actionType, target, staffUser, reason,
   }
 }
 
+// Post an "appeal approved → action reversed" embed to the mod-log channel.
+// Unlike record() this NEVER inserts a mod_actions row — the reversal is an
+// out-of-band correction driven by the site's appeals flow, not a new staff
+// action. Best-effort: a missing channel or send failure is logged, not thrown.
+async function postReversal({ client, guildId, actionType, discordUserId, appealId }) {
+  try {
+    const channelId = await guildConfig.getModLogChannelId(guildId)
+    if (!channelId) return
+    const channel = await client.channels.fetch(channelId)
+    if (!channel || !channel.isTextBased()) return
+
+    const reversed = actionType === 'ban' ? 'Ban lifted (unbanned)' : 'Mute cleared (timeout removed)'
+    const embed = new EmbedBuilder()
+      .setColor(0x88c0a0)
+      .setTitle('APPEAL APPROVED')
+      .addFields(
+        { name: 'Action reversed', value: reversed, inline: true },
+        { name: 'Target id', value: `${discordUserId}`, inline: true },
+        { name: 'Appeal', value: `#${appealId}`, inline: true },
+      )
+      .setTimestamp()
+
+    await channel.send({ embeds: [embed] })
+  } catch (err) {
+    log.warn('failed to post appeal-reversal embed', { message: err.message })
+  }
+}
+
 function formatDuration(seconds) {
   if (seconds % 86400 === 0) return `${seconds / 86400}d`
   if (seconds % 3600 === 0) return `${seconds / 3600}h`
@@ -50,4 +78,4 @@ function formatDuration(seconds) {
   return `${seconds}s`
 }
 
-module.exports = { record }
+module.exports = { record, postReversal }

bot/src/internal/internal.controller.js

@@ -1,9 +1,14 @@
 const discordManager = require('../discord/discordManager')
 const newsAnnounce = require('../discord/newsAnnounce')
+const modLog = require('../discord/modLog')
 const createLogger = require('../utils/logger')
 
 const log = createLogger('internal')
 
+const REVERSIBLE = new Set(['ban', 'mute'])
+// discord.js REST error code for removing a ban that no longer exists.
+const UNKNOWN_BAN = 10026
+
 // POST /internal/config — called by the main server right after an admin
 // saves the Discord Bot panel, and by the bot's own bootstrap on startup
 // (via a GET to the server for the current config, then this same start/stop
@@ -47,4 +52,51 @@ async function announce(req, res) {
   }
 }
 
-module.exports = { setConfig, getStatus: getStatusHandler, announce }
+// POST /internal/mod-reverse — called by the main server when a staffer APPROVES
+// a moderation appeal (Phase 6d). Body: { discord_user_id, action_type, appeal_id }.
+// Reverses the Discord action: 'ban' → lift the ban, 'mute' → clear the timeout.
+// Idempotent-friendly: an already-lifted ban ("Unknown Ban") or a member who has
+// left the guild is treated as success (the desired end state already holds).
+async function reverseModAction(req, res) {
+  const { discord_user_id: discordUserId, action_type: actionType, appeal_id: appealId } = req.body || {}
+
+  if (!REVERSIBLE.has(actionType)) {
+    return res.status(400).json({ message: 'action_type must be ban or mute' })
+  }
+
+  const connection = discordManager.getConnection()
+  if (!connection) return res.status(503).json({ message: 'Bot is not connected' })
+
+  const reason = `Appeal #${appealId} approved`
+  try {
+    const guild = await connection.client.guilds.fetch(connection.guildId)
+
+    if (actionType === 'ban') {
+      try {
+        await guild.bans.remove(discordUserId, reason)
+      } catch (err) {
+        // Unknown Ban → already unbanned; anything else is a real failure.
+        if (err.code !== UNKNOWN_BAN) throw err
+      }
+    } else {
+      // mute: clear the timeout. If the member has left, there's nothing to clear.
+      const member = await guild.members.fetch(discordUserId).catch(() => null)
+      if (member) await member.timeout(null, reason)
+    }
+
+    await modLog.postReversal({
+      client: connection.client,
+      guildId: connection.guildId,
+      actionType,
+      discordUserId,
+      appealId,
+    })
+
+    return res.json({ reversed: true })
+  } catch (err) {
+    log.error('mod-reverse failed', { message: err.message, actionType, discordUserId })
+    return res.status(500).json({ message: err.message })
+  }
+}
+
+module.exports = { setConfig, getStatus: getStatusHandler, announce, reverseModAction }

bot/src/internal/internal.routes.js

@@ -10,5 +10,6 @@ router.use(requireInternalKey)
 router.post('/config', ctrl.setConfig)
 router.get('/status', ctrl.getStatus)
 router.post('/announce', ctrl.announce)
+router.post('/mod-reverse', ctrl.reverseModAction)
 
 module.exports = router