feat(discord): add Terraform-managed base allowlist and admins (#34)

## Summary
Introduces a Terraform-managed baseline for Discord allowlists and admin
lists that cannot be removed via the management UI. This allows
operators to enforce a permanent floor of allowed guilds and admins
while still permitting the UI to manage additional entries.

## Key Changes

- **New `BaseDiscordConfig` type** in shared types representing the
read-only Terraform baseline (allowedGuilds and admins)

- **New DynamoDB row `BASE#discord`** written by Terraform on every
apply when any base list is non-empty, with three new Terraform
variables:
  - `base_allowed_guilds`: Guild IDs permanently allowlisted
  - `base_admin_user_ids`: User IDs with permanent admin privileges
  - `base_admin_role_ids`: Role IDs with permanent admin privileges

- **New `getBaseDiscordConfig()` function** reads the BASE#discord row
with strongly consistent reads, returning an empty base when absent

- **New `getEffectiveDiscordConfig()` function** merges the Terraform
base and dynamic CONFIG#discord rows, deduplicating entries. This is now
used by both Lambda handlers for permission checks

- **Updated `DiscordConfigService`** to:
- Cache and load the base config separately with coalesced concurrent
reads
  - Expose `getBaseConfig()` method for retrieving the base config
- Prevent removal of guilds/admins that exist in the Terraform base
(returns error with explanation)
  - Include base lists in the redacted config sent to the web client

- **Updated REST API endpoints** to return both dynamic and base lists:
- `GET /discord/guilds` and `GET /discord/admins` now include
`baseGuilds` and `baseAdmins`
- `DELETE /discord/guilds/:guildId` returns 400 if the guild is in the
base config
- All mutation endpoints return the updated base lists alongside dynamic
lists

- **Updated Lambda handlers** (interactions and followup) to use
`getEffectiveDiscordConfig()` instead of `getDiscordConfig()` for
permission checks, ensuring base entries are always enforced

## Implementation Details

- Base config is cached in `DiscordConfigService` and invalidated
alongside the dynamic config
- Terraform resource uses `count` to skip creation when all base lists
are empty (UI-only deployments)
- Defensive parsing sanitizes malformed base data without throwing
- Web client can render base entries as locked/non-removable based on
the new `baseAllowedGuilds` and `baseAdmins` fields in the redacted
config

https://claude.ai/code/session_01GxkgH9sABMbHDCQqXehHP1

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: CoderCoco

CLAUDE.md

@@ -133,6 +133,15 @@ The full deploy IAM policy (`GameServerDeployAll`) lives in **`docs/setup.md`**
 
 All resources inherit `default_tags` from `provider "aws"` (`Project = "game-servers-poc"`, `Environment = "poc"`, `ManagedBy = "terraform"`). For Cost Explorer breakdowns, the `Project` cost allocation tag must be activated manually in AWS Billing — this is a one-time console action, not Terraform-managed.
 
+## Checklist for Terraform variable changes
+
+Any time you add or remove Terraform variables, update **all four** of these in the same commit — failing to touch any one of them is a common oversight:
+
+1. `terraform/variables.tf` — the variable declaration itself.
+2. `terraform/terraform.tfvars.example` — a commented-out example entry with a short explanation so operators know how to use it.
+3. `docs/docs/components/terraform.md` — the Variables table row.
+4. `docs/docs/setup.md` — any relevant step in the setup guide (especially if the variable affects the Discord bot or a core workflow).
+
 ## Code & Test Conventions
 
 - **Test names**: every `it(...)` case must read as a natural-language sentence starting with "should" — e.g. `it('should return null when state file is missing')`, not `it('returns null...')`.

app/packages/lambda/followup/src/handler.test.ts

@@ -16,13 +16,13 @@ import {
   EC2Client,
 } from '@aws-sdk/client-ec2';
 
-const getDiscordConfigMock = vi.fn();
+const getEffectiveDiscordConfigMock = vi.fn();
 const putPendingMock = vi.fn();
 vi.mock('@gsd/shared', async () => {
   const actual = await vi.importActual<typeof import('@gsd/shared')>('@gsd/shared');
   return {
     ...actual,
-    getDiscordConfig: (...args: unknown[]) => getDiscordConfigMock(...args),
+    getEffectiveDiscordConfig: (...args: unknown[]) => getEffectiveDiscordConfigMock(...args),
     putPending: (...args: unknown[]) => putPendingMock(...args),
   };
 });
@@ -69,9 +69,9 @@ beforeEach(() => {
   ecsMock.reset();
   ec2Mock.reset();
   fetchMock.mockReset();
-  getDiscordConfigMock.mockReset();
+  getEffectiveDiscordConfigMock.mockReset();
   putPendingMock.mockReset();
-  getDiscordConfigMock.mockResolvedValue(PERMISSIVE_CONFIG);
+  getEffectiveDiscordConfigMock.mockResolvedValue(PERMISSIVE_CONFIG);
   fetchMock.mockResolvedValue({ ok: true, text: async () => '' });
 });
 
@@ -116,7 +116,7 @@ describe('FollowupLambda: start', () => {
   });
 
   it('should deny the start when canRun() rejects the caller', async () => {
-    getDiscordConfigMock.mockResolvedValue({
+    getEffectiveDiscordConfigMock.mockResolvedValue({
       ...PERMISSIVE_CONFIG,
       admins: { userIds: [], roleIds: [] },
       gamePermissions: { palworld: { userIds: [], roleIds: [], actions: [] } },
@@ -193,7 +193,7 @@ describe('FollowupLambda: status', () => {
 
 describe('FollowupLambda: list', () => {
   it('should only fetch status for games the caller can view, and join lines with newlines', async () => {
-    getDiscordConfigMock.mockResolvedValue({
+    getEffectiveDiscordConfigMock.mockResolvedValue({
       ...PERMISSIVE_CONFIG,
       admins: { userIds: [], roleIds: [] },
       gamePermissions: {
@@ -211,7 +211,7 @@ describe('FollowupLambda: list', () => {
   });
 
   it('should return a helpful message when the caller can see nothing', async () => {
-    getDiscordConfigMock.mockResolvedValue({
+    getEffectiveDiscordConfigMock.mockResolvedValue({
       ...PERMISSIVE_CONFIG,
       admins: { userIds: [], roleIds: [] },
       gamePermissions: {},

app/packages/lambda/followup/src/handler.ts

@@ -24,7 +24,7 @@ import {
   EC2Client,
   DescribeNetworkInterfacesCommand,
 } from '@aws-sdk/client-ec2';
-import { canRun, formatGameStatus, getDiscordConfig, putPending } from '@gsd/shared';
+import { canRun, formatGameStatus, getEffectiveDiscordConfig, putPending } from '@gsd/shared';
 import type { DiscordAction, DiscordConfig, GameStatus } from '@gsd/shared';
 
 interface FollowupEvent {
@@ -252,7 +252,7 @@ function recheck(event: FollowupEvent, cfg: DiscordConfig, action: DiscordAction
  */
 export const handler = async (event: FollowupEvent): Promise<void> => {
   const tableName = requireEnv('TABLE_NAME');
-  const cfg = await getDiscordConfig(tableName);
+  const cfg = await getEffectiveDiscordConfig(tableName);
 
   let content: string;
   try {

app/packages/lambda/interactions/src/handler.test.ts

@@ -20,13 +20,13 @@ vi.mock('@noble/ed25519', () => ({
 
 // Mock the shared config + secrets stores so we never hit AWS.
 const getPublicKeyMock = vi.fn();
-const getDiscordConfigMock = vi.fn();
+const getEffectiveDiscordConfigMock = vi.fn();
 vi.mock('@gsd/shared', async () => {
   const actual = await vi.importActual<typeof import('@gsd/shared')>('@gsd/shared');
   return {
     ...actual,
     getPublicKey: (...args: unknown[]) => getPublicKeyMock(...args),
-    getDiscordConfig: (...args: unknown[]) => getDiscordConfigMock(...args),
+    getEffectiveDiscordConfig: (...args: unknown[]) => getEffectiveDiscordConfigMock(...args),
   };
 });
 
@@ -69,9 +69,9 @@ beforeEach(() => {
   lambdaMock.reset();
   verifyAsyncMock.mockReset();
   getPublicKeyMock.mockReset();
-  getDiscordConfigMock.mockReset();
+  getEffectiveDiscordConfigMock.mockReset();
   getPublicKeyMock.mockResolvedValue('0a'.repeat(32));
-  getDiscordConfigMock.mockResolvedValue({
+  getEffectiveDiscordConfigMock.mockResolvedValue({
     clientId: 'app-id',
     allowedGuilds: ['G1'],
     admins: { userIds: ['ADMIN'], roleIds: [] },
@@ -261,7 +261,7 @@ describe('InteractionsLambda: APPLICATION_COMMAND_AUTOCOMPLETE', () => {
   it('should cap autocomplete choices at 25 to satisfy the Discord limit', async () => {
     const manyGames = Array.from({ length: 50 }, (_, i) => `game${i}`);
     process.env['GAME_NAMES'] = manyGames.join(',');
-    getDiscordConfigMock.mockResolvedValueOnce({
+    getEffectiveDiscordConfigMock.mockResolvedValueOnce({
       clientId: 'app-id',
       allowedGuilds: ['G1'],
       admins: { userIds: ['U1'], roleIds: [] },

app/packages/lambda/interactions/src/handler.ts

@@ -17,7 +17,7 @@
 import { verifyAsync } from '@noble/ed25519';
 import { LambdaClient, InvokeCommand } from '@aws-sdk/client-lambda';
 import type { APIGatewayProxyEventV2, APIGatewayProxyResultV2 } from 'aws-lambda';
-import { canRun, getDiscordConfig, getPublicKey } from '@gsd/shared';
+import { canRun, getEffectiveDiscordConfig, getPublicKey } from '@gsd/shared';
 import type { DiscordAction, DiscordConfig } from '@gsd/shared';
 
 /** Discord interaction types we care about. Full list in discord-api-types. */
@@ -297,7 +297,7 @@ export const handler = async (event: APIGatewayProxyEventV2): Promise<APIGateway
   }
 
   const tableName = requireEnv('TABLE_NAME');
-  const cfg = await getDiscordConfig(tableName);
+  const cfg = await getEffectiveDiscordConfig(tableName);
 
   if (interaction.type === INTERACTION_APPLICATION_COMMAND_AUTOCOMPLETE) {
     return handleAutocomplete(interaction, cfg);

app/packages/server/src/controllers/discord.controller.ts

@@ -90,13 +90,17 @@ export class DiscordController {
     };
   }
 
-  /** Returns the list of allowlisted guild IDs. The interactions Lambda rejects any command from a guild not in this list. */
+  /**
+   * Returns the dynamic allowlisted guild IDs and the Terraform-managed base guild IDs.
+   * The UI should render base guilds as locked (non-removable).
+   */
   @Get('guilds')
   async listGuilds() {
-    return { guilds: (await this.discord.getConfig()).allowedGuilds };
+    const [cfg, base] = await Promise.all([this.discord.getConfig(), this.discord.getBaseConfig()]);
+    return { guilds: cfg.allowedGuilds, baseGuilds: base.allowedGuilds };
   }
 
-  /** Adds a guild ID to the allowlist persisted in DynamoDB. Takes effect on the next interaction (Lambda re-reads per invocation). */
+  /** Adds a guild ID to the dynamic allowlist persisted in DynamoDB. Takes effect on the next interaction (Lambda re-reads per invocation). */
   @Post('guilds')
   async addGuild(@Body() body: { guildId?: unknown } = {}) {
     if (typeof body.guildId !== 'string') {
@@ -105,16 +109,25 @@ export class DiscordController {
     const guildId = body.guildId.trim();
     if (!guildId) throw new BadRequestException({ success: false, error: 'guildId required' });
     await this.discord.addAllowedGuild(guildId);
-    return { success: true, guilds: (await this.discord.getConfig()).allowedGuilds };
+    const [cfg, base] = await Promise.all([this.discord.getConfig(), this.discord.getBaseConfig()]);
+    return { success: true, guilds: cfg.allowedGuilds, baseGuilds: base.allowedGuilds };
   }
 
-  /** Removes a guild ID from the allowlist. Already-registered slash commands remain in Discord until manually cleaned up. */
+  /**
+   * Removes a guild ID from the dynamic allowlist. Returns 400 if the guild is
+   * in the Terraform base config — those entries require a tfvars edit + re-apply.
+   * Already-registered slash commands remain in Discord until manually cleaned up.
+   */
   @Delete('guilds/:guildId')
   async removeGuild(@Param('guildId') guildIdRaw: string) {
     const guildId = (guildIdRaw ?? '').trim();
     if (!guildId) throw new BadRequestException({ success: false, error: 'guildId required' });
-    await this.discord.removeAllowedGuild(guildId);
-    return { success: true, guilds: (await this.discord.getConfig()).allowedGuilds };
+    const result = await this.discord.removeAllowedGuild(guildId);
+    if (!result.ok) {
+      throw new BadRequestException({ success: false, error: result.reason });
+    }
+    const [cfg, base] = await Promise.all([this.discord.getConfig(), this.discord.getBaseConfig()]);
+    return { success: true, guilds: cfg.allowedGuilds, baseGuilds: base.allowedGuilds };
   }
 
   /**
@@ -130,19 +143,27 @@ export class DiscordController {
     return this.registrar.registerForGuild(guildId);
   }
 
-  /** Returns the global admin user/role lists. Admins bypass per-game permission gates in `canRun()`. */
+  /**
+   * Returns the dynamic admin user/role lists and the Terraform-managed base admin lists.
+   * The UI should render base admins as locked (non-removable).
+   */
   @Get('admins')
   async getAdmins() {
-    return (await this.discord.getConfig()).admins;
+    const [cfg, base] = await Promise.all([this.discord.getConfig(), this.discord.getBaseConfig()]);
+    return { ...cfg.admins, baseAdmins: base.admins };
   }
 
-  /** Replaces the admin user/role lists atomically. Omitted fields are treated as empty arrays (not "leave alone"). */
+  /**
+   * Replaces the dynamic admin user/role lists atomically. Omitted fields are treated as empty arrays
+   * (not "leave alone"). Base admins set via Terraform are unaffected by this endpoint.
+   */
   @Put('admins')
   async putAdmins(@Body() body: { userIds?: unknown; roleIds?: unknown } = {}) {
     const userIds = requireStringArray('userIds', body.userIds);
     const roleIds = requireStringArray('roleIds', body.roleIds);
     await this.discord.setAdmins({ userIds, roleIds });
-    return { success: true, admins: (await this.discord.getConfig()).admins };
+    const [cfg, base] = await Promise.all([this.discord.getConfig(), this.discord.getBaseConfig()]);
+    return { success: true, admins: cfg.admins, baseAdmins: base.admins };
   }
 
   /** Returns the per-game permission map (user/role IDs allowed to run specific actions on each game). */

app/packages/server/src/services/DiscordConfigService.test.ts

@@ -13,6 +13,7 @@ import { DiscordConfigService } from './DiscordConfigService.js';
 import { ConfigService, type TfOutputs } from './ConfigService.js';
 
 const getDiscordConfigMock = vi.fn();
+const getBaseDiscordConfigMock = vi.fn();
 const putDiscordConfigMock = vi.fn();
 const getBotTokenMock = vi.fn();
 const getPublicKeyMock = vi.fn();
@@ -25,6 +26,7 @@ vi.mock('@gsd/shared', async () => {
   return {
     ...actual,
     getDiscordConfig: (...args: unknown[]) => getDiscordConfigMock(...args),
+    getBaseDiscordConfig: (...args: unknown[]) => getBaseDiscordConfigMock(...args),
     putDiscordConfig: (...args: unknown[]) => putDiscordConfigMock(...args),
     getBotToken: (...args: unknown[]) => getBotTokenMock(...args),
     getPublicKey: (...args: unknown[]) => getPublicKeyMock(...args),
@@ -61,6 +63,7 @@ function makeService(outputs: TfOutputs | null = TF): DiscordConfigService {
 
 beforeEach(() => {
   getDiscordConfigMock.mockReset();
+  getBaseDiscordConfigMock.mockReset();
   putDiscordConfigMock.mockReset();
   getBotTokenMock.mockReset();
   getPublicKeyMock.mockReset();
@@ -73,6 +76,10 @@ beforeEach(() => {
     admins: { userIds: [], roleIds: [] },
     gamePermissions: {},
   });
+  getBaseDiscordConfigMock.mockResolvedValue({
+    allowedGuilds: [],
+    admins: { userIds: [], roleIds: [] },
+  });
   putDiscordConfigMock.mockResolvedValue(undefined);
   getBotTokenMock.mockResolvedValue(null);
   getPublicKeyMock.mockResolvedValue(null);
@@ -127,6 +134,23 @@ describe('DiscordConfigService.getRedacted', () => {
     expect(redacted.botTokenSet).toBe(false);
     expect(redacted.publicKeySet).toBe(false);
   });
+
+  it('should include base guild and admin lists from the BASE#discord row', async () => {
+    getBaseDiscordConfigMock.mockResolvedValue({
+      allowedGuilds: ['G-base'],
+      admins: { userIds: ['U-base'], roleIds: ['R-base'] },
+    });
+    const redacted = await makeService().getRedacted();
+    expect(redacted.baseAllowedGuilds).toEqual(['G-base']);
+    expect(redacted.baseAdmins).toEqual({ userIds: ['U-base'], roleIds: ['R-base'] });
+  });
+
+  it('should return empty base lists when no BASE#discord row exists', async () => {
+    getBaseDiscordConfigMock.mockResolvedValue({ allowedGuilds: [], admins: { userIds: [], roleIds: [] } });
+    const redacted = await makeService().getRedacted();
+    expect(redacted.baseAllowedGuilds).toEqual([]);
+    expect(redacted.baseAdmins).toEqual({ userIds: [], roleIds: [] });
+  });
 });
 
 describe('DiscordConfigService.setCredentials', () => {
@@ -188,21 +212,33 @@ describe('DiscordConfigService.allowedGuilds mutations', () => {
     );
   });
 
-  it('should remove a guild from the allowlist', async () => {
+  it('should remove a guild from the dynamic allowlist and return ok', async () => {
     getDiscordConfigMock.mockResolvedValue({
       clientId: '',
       allowedGuilds: ['G1', 'G2'],
       admins: { userIds: [], roleIds: [] },
       gamePermissions: {},
     });
     const svc = makeService();
-    await svc.removeAllowedGuild('G1');
+    const result = await svc.removeAllowedGuild('G1');
+    expect(result).toEqual({ ok: true });
     expect(putDiscordConfigMock).toHaveBeenCalledWith(
       'test-discord',
       expect.objectContaining({ allowedGuilds: ['G2'] }),
     );
   });
 
+  it('should refuse to remove a guild that is in the Terraform base config', async () => {
+    getBaseDiscordConfigMock.mockResolvedValue({
+      allowedGuilds: ['G-base'],
+      admins: { userIds: [], roleIds: [] },
+    });
+    const svc = makeService();
+    const result = await svc.removeAllowedGuild('G-base');
+    expect(result).toMatchObject({ ok: false });
+    expect(putDiscordConfigMock).not.toHaveBeenCalled();
+  });
+
   it('should dedupe and drop empty strings when setAllowedGuilds is called', async () => {
     const svc = makeService();
     await svc.setAllowedGuilds(['G1', '', 'G1', 'G2']);