feat: grant Elysian role on auth and prompt non-members to join (#134)

## Summary

- Grants the Elysian Discord role to players on login/registration and persists an `inGuild` flag on the Player record
- Connects to the Discord Gateway via WebSocket to keep `inGuild` in sync as players join or leave the server
- Shows a dismissible "Join our community" modal to players who are not yet in the guild
- Hardens `inGuild` exposure through the load endpoint and game context
- Moves all non-secret Discord IDs (guild, role, client, redirect URI) out of env vars and into hardcoded constants; removes them from `prod.env`

## Test plan

- [ ] Lint, build, and test pipeline passes (100% coverage maintained)
- [ ] New player auth grants Elysian role and sets `inGuild: true`
- [ ] Existing player auth re-attempts role grant and updates `inGuild`
- [ ] Join community modal appears for players not in the guild
- [ ] Modal does not reappear within the same browser session after dismissal
- [ ] Gateway correctly sets `inGuild: true/false` on member add/remove events

✨ This issue was created with help from Hikari~ 🌸

Reviewed-on: #134
Co-authored-by: Hikari <hikari@nhcarrigan.com>
Co-committed-by: Hikari <hikari@nhcarrigan.com>

apps/api/src/index.ts

@@ -21,6 +21,7 @@ import { leaderboardRouter } from "./routes/leaderboards.js";
 import { prestigeRouter } from "./routes/prestige.js";
 import { profileRouter } from "./routes/profile.js";
 import { transcendenceRouter } from "./routes/transcendence.js";
+import { connectGateway } from "./services/gateway.js";
 import { logger } from "./services/logger.js";
 
 const app = new Hono();
@@ -68,6 +69,7 @@ const port = Number(process.env.PORT ?? 3001);
 try {
   serve({ fetch: app.fetch, port: port }, () => {
     process.stdout.write(`Elysium API running on port ${String(port)}\n`);
+    connectGateway();
   });
 } catch (error) {
   void logger.error(

apps/api/src/routes/auth.ts

@@ -16,6 +16,7 @@ import {
 } from "../services/discord.js";
 import { signToken } from "../services/jwt.js";
 import { logger } from "../services/logger.js";
+import { grantElysianRole } from "../services/webhook.js";
 import type { Player } from "@elysium/types";
 
 const authRouter = new Hono();
@@ -92,6 +93,12 @@ authRouter.get("/callback", async(context) => {
         },
       });
 
+      const inGuild = await grantElysianRole(player.discordId);
+      await prisma.player.update({
+        data:  { inGuild },
+        where: { discordId: player.discordId },
+      });
+
       const jwtToken = signToken(player.discordId);
       void logger.log("info", `New player registered: ${player.discordId}`);
       void logger.metric("user_registered", 1, { discordId: player.discordId });
@@ -104,10 +111,12 @@ authRouter.get("/callback", async(context) => {
       );
     }
 
+    const inGuild = await grantElysianRole(discordUser.id);
     const updated = await prisma.player.update({
       data: {
         avatar:        discordUser.avatar,
         discriminator: discordUser.discriminator,
+        inGuild:       inGuild,
         username:      discordUser.username,
       },
       where: { discordId: discordUser.id },

apps/api/src/routes/game.ts

@@ -760,6 +760,7 @@ gameRouter.get("/load", async(context) => {
         : computeHmac(JSON.stringify(freshState), secret);
       return context.json({
         currentSchemaVersion: currentSchemaVersion,
+        inGuild:              playerRecord.inGuild,
         loginBonus:           null,
         loginStreak:          playerRecord.loginStreak,
         offlineEssence:       0,
@@ -898,8 +899,10 @@ gameRouter.get("/load", async(context) => {
     const signature = secret === undefined
       ? undefined
       : computeHmac(JSON.stringify(state), secret);
+    const inGuild = playerRecord?.inGuild ?? false;
     return context.json({
       currentSchemaVersion,
+      inGuild,
       loginBonus,
       loginStreak,
       offlineEssence,

apps/api/src/services/discord.ts

@@ -7,6 +7,9 @@
 /* eslint-disable @typescript-eslint/naming-convention -- Discord API requires snake_case fields and HTTP headers require Pascal-Case */
 import { logger } from "./logger.js";
 
+const discordClientId = "1479551654264049908";
+const discordRedirectUri = "https://elysium.nhcarrigan.com/api/auth/callback";
+
 interface DiscordTokenResponse {
   access_token:  string;
   token_type:    string;
@@ -31,24 +34,18 @@ interface DiscordUser {
 const exchangeCode = async(
   code: string,
 ): Promise<DiscordTokenResponse> => {
-  const clientId = process.env.DISCORD_CLIENT_ID;
   const clientSecret = process.env.DISCORD_CLIENT_SECRET;
-  const redirectUri = process.env.DISCORD_REDIRECT_URI;
 
-  if (
-    clientId === undefined || clientId === ""
-    || clientSecret === undefined || clientSecret === ""
-    || redirectUri === undefined || redirectUri === ""
-  ) {
+  if (clientSecret === undefined || clientSecret === "") {
     throw new Error("Discord OAuth environment variables are required");
   }
 
   const parameters = new URLSearchParams({
-    client_id:     clientId,
+    client_id:     discordClientId,
     client_secret: clientSecret,
     code:          code,
     grant_type:    "authorization_code",
-    redirect_uri:  redirectUri,
+    redirect_uri:  discordRedirectUri,
   });
 
   try {
@@ -146,19 +143,9 @@ const fetchDiscordUserById = async(
  * @throws {Error} If OAuth environment variables are missing.
  */
 const buildOAuthUrl = (): string => {
-  const clientId = process.env.DISCORD_CLIENT_ID;
-  const redirectUri = process.env.DISCORD_REDIRECT_URI;
-
-  if (
-    clientId === undefined || clientId === ""
-    || redirectUri === undefined || redirectUri === ""
-  ) {
-    throw new Error("Discord OAuth environment variables are required");
-  }
-
   const parameters = new URLSearchParams({
-    client_id:     clientId,
-    redirect_uri:  redirectUri,
+    client_id:     discordClientId,
+    redirect_uri:  discordRedirectUri,
     response_type: "code",
     scope:         "identify",
   });

apps/api/src/services/gateway.ts

@@ -0,0 +1,182 @@
+/**
+ * @file Discord Gateway WebSocket client for listening to guild member events.
+ * @copyright nhcarrigan
+ * @license Naomi's Public License
+ * @author Naomi Carrigan
+ */
+/* eslint-disable max-lines-per-function -- WebSocket gateway requires sequential event handler setup */
+import { prisma } from "../db/client.js";
+import { logger } from "./logger.js";
+
+const discordGuildId = "1354624415861833870";
+
+/**
+ * Discord Gateway opcodes used by this client.
+ */
+const gatewayOpcodes = {
+  dispatch:     0,
+  heartbeat:    1,
+  heartbeatAck: 11,
+  hello:        10,
+  identify:     2,
+} as const;
+
+/**
+ * GUILD_MEMBERS privileged intent bitmask.
+ */
+/* eslint-disable-next-line no-bitwise -- Bitwise shift required for Discord intent bitmask */
+const guildMembersIntent = 1 << 1;
+
+/**
+ * Updates the inGuild flag for a player when they join the configured guild.
+ * No-ops silently if the Discord user has no player record.
+ * @param discordId - The Discord user ID of the member who joined.
+ * @param guildId - The ID of the guild they joined.
+ * @returns A promise that resolves when the update attempt completes.
+ */
+const handleGuildMemberAdd = async(
+  discordId: string,
+  guildId: string,
+): Promise<void> => {
+  if (guildId !== discordGuildId) {
+    return;
+  }
+  try {
+    await prisma.player.updateMany({
+      data:  { inGuild: true },
+      where: { discordId },
+    });
+  } catch (error) {
+    void logger.error(
+      "gateway_member_add",
+      error instanceof Error
+        ? error
+        : new Error(String(error)),
+    );
+  }
+};
+
+/**
+ * Updates the inGuild flag for a player when they leave the configured guild.
+ * No-ops silently if the Discord user has no player record.
+ * @param discordId - The Discord user ID of the member who left.
+ * @param guildId - The ID of the guild they left.
+ * @returns A promise that resolves when the update attempt completes.
+ */
+const handleGuildMemberRemove = async(
+  discordId: string,
+  guildId: string,
+): Promise<void> => {
+  if (guildId !== discordGuildId) {
+    return;
+  }
+  try {
+    await prisma.player.updateMany({
+      data:  { inGuild: false },
+      where: { discordId },
+    });
+  } catch (error) {
+    void logger.error(
+      "gateway_member_remove",
+      error instanceof Error
+        ? error
+        : new Error(String(error)),
+    );
+  }
+};
+
+// eslint-disable-next-line capitalized-comments -- v8 ignore directive must be lowercase
+/* v8 ignore next 95 -- @preserve */
+/**
+ * Connects to the Discord Gateway and listens for guild member events.
+ * Reconnects automatically on close or error.
+ * Requires the GUILD_MEMBERS privileged intent to be enabled in the Discord Developer Portal.
+ */
+const connectGateway = (): void => {
+  const botToken = process.env.DISCORD_BOT_TOKEN;
+  if (botToken === undefined || botToken === "") {
+    void logger.log("info", "Gateway: no bot token configured, skipping");
+    return;
+  }
+
+  const ws = new WebSocket("wss://gateway.discord.gg/?v=10&encoding=json");
+  let heartbeatInterval: ReturnType<typeof setInterval> | null = null;
+  let lastSequence: number | null = null;
+
+  const stopHeartbeat = (): void => {
+    if (heartbeatInterval !== null) {
+      clearInterval(heartbeatInterval);
+      heartbeatInterval = null;
+    }
+  };
+
+  ws.addEventListener("message", (event) => {
+    /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Gateway payload is JSON */
+    const payload = JSON.parse(event.data as string) as {
+      op: number;
+      d:  unknown;
+      s:  number | null;
+      t:  string | null;
+    };
+
+    if (payload.s !== null) {
+      lastSequence = payload.s;
+    }
+
+    if (payload.op === gatewayOpcodes.hello) {
+      /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions, @typescript-eslint/naming-convention -- HELLO d shape; Discord API snake_case */
+      const helloData = payload.d as { heartbeat_interval: number };
+      const heartbeatMs = helloData.heartbeat_interval;
+      heartbeatInterval = setInterval(() => {
+        ws.send(JSON.stringify({
+          d:  lastSequence,
+          op: gatewayOpcodes.heartbeat,
+        }));
+      }, heartbeatMs);
+
+      ws.send(JSON.stringify({
+        d: {
+          intents:    guildMembersIntent,
+          properties: { browser: "elysium", device: "elysium", os: "linux" },
+          token:      botToken,
+        },
+        op: gatewayOpcodes.identify,
+      }));
+    }
+
+    if (payload.op === gatewayOpcodes.dispatch && payload.t !== null) {
+      /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions, @typescript-eslint/naming-convention -- dispatch payload shape; Discord API snake_case */
+      const data = payload.d as { user?: { id: string }; guild_id?: string };
+      const discordId = data.user?.id;
+      const guildId = data.guild_id;
+
+      if (discordId === undefined || guildId === undefined) {
+        return;
+      }
+
+      if (payload.t === "GUILD_MEMBER_ADD") {
+        void handleGuildMemberAdd(discordId, guildId);
+      } else if (payload.t === "GUILD_MEMBER_REMOVE") {
+        void handleGuildMemberRemove(discordId, guildId);
+      }
+    }
+  });
+
+  ws.addEventListener("close", () => {
+    stopHeartbeat();
+    void logger.log("info", "Gateway: connection closed, reconnecting in 5s");
+    setTimeout(connectGateway, 5000);
+  });
+
+  ws.addEventListener("error", (event) => {
+    const message
+      = event instanceof ErrorEvent
+        ? event.message
+        : "WebSocket error";
+    void logger.error("gateway_error", new Error(message));
+    stopHeartbeat();
+    ws.close();
+  });
+};
+
+export { connectGateway, handleGuildMemberAdd, handleGuildMemberRemove };

apps/api/src/services/webhook.ts

@@ -15,6 +15,49 @@ const discordApi = "https://discord.com/api/v10";
  */
 const suppressNotifications = 4096;
 
+/**
+ * The Discord role ID for the Elysian role granted to all Elysium players.
+ */
+const discordGuildId = "1354624415861833870";
+const elysianRoleId = "1486144823684628490";
+const apotheosisRoleId = "1479966598210129991";
+
+/**
+ * Grants the Elysian Discord role to the given player and returns whether they are in the guild.
+ * Fails silently so role grant errors do not affect the auth flow.
+ * @param discordId - The Discord user ID to grant the role to.
+ * @returns True if the player is in the guild and the role was granted, false otherwise.
+ */
+const grantElysianRole = async(discordId: string): Promise<boolean> => {
+  const botToken = process.env.DISCORD_BOT_TOKEN;
+
+  if (botToken === undefined || botToken === "") {
+    return false;
+  }
+
+  try {
+    const response = await fetch(
+      `${discordApi}/guilds/${discordGuildId}/members/${discordId}/roles/${elysianRoleId}`,
+      {
+        headers: {
+          "Authorization": `Bot ${botToken}`,
+          "User-Agent":    "DiscordBot (https://elysium.nhcarrigan.com, 1.0.0)",
+        },
+        method: "PUT",
+      },
+    );
+    return response.ok || response.status === 204;
+  } catch (error) {
+    void logger.error(
+      "webhook_elysian_role",
+      error instanceof Error
+        ? error
+        : new Error(String(error)),
+    );
+    return false;
+  }
+};
+
 /**
  * Grants the apotheosis Discord role to the given player if configured.
  * Fails silently so role grant errors do not affect the game action.
@@ -23,23 +66,20 @@ const suppressNotifications = 4096;
  */
 const grantApotheosisRole = async(discordId: string): Promise<void> => {
   const botToken = process.env.DISCORD_BOT_TOKEN;
-  const guildId = process.env.DISCORD_GUILD_ID;
-  const roleId = process.env.DISCORD_APOTHEOSIS_ROLE_ID;
 
-  if (
-    botToken === undefined || botToken === ""
-    || guildId === undefined || guildId === ""
-    || roleId === undefined || roleId === ""
-  ) {
+  if (botToken === undefined || botToken === "") {
     return;
   }
 
   try {
     await fetch(
-      `${discordApi}/guilds/${guildId}/members/${discordId}/roles/${roleId}`,
+      `${discordApi}/guilds/${discordGuildId}/members/${discordId}/roles/${apotheosisRoleId}`,
       {
-        headers: { Authorization: `Bot ${botToken}` },
-        method:  "PUT",
+        headers: {
+          "Authorization": `Bot ${botToken}`,
+          "User-Agent":    "DiscordBot (https://elysium.nhcarrigan.com, 1.0.0)",
+        },
+        method: "PUT",
       },
     );
   } catch (error) {
@@ -109,4 +149,4 @@ const postMilestoneWebhook = async(
   }
 };
 
-export { grantApotheosisRole, postMilestoneWebhook };
+export { grantApotheosisRole, grantElysianRole, postMilestoneWebhook };