feat(terraform): declarative EFS file seeding via file_seeds in game_servers (#42)

## Summary

Closes #38

Adds a declarative file seeding system that pre-populates files on EFS
volumes before game servers start. This allows users to define
configuration files, mods, and other assets directly in Terraform
without manual setup.

## Key Changes

- **New EFS Seeder Lambda** (`terraform/efs-seeder.tf`): 
- Per-game Lambda function that mounts the first volume's EFS access
point
- Receives file seed declarations and writes them to the mounted EFS
volume
- Invocation is content-addressed (re-triggers only when seed content
changes)
  - Shared security group for all seeder Lambdas with NFS egress to EFS

- **Seeder Handler** (`app/packages/lambda/efs-seeder/src/handler.ts`):
- Validates seed paths against the container's `container_path` prefix
to prevent path traversal
- Supports both UTF-8 text (`content`) and binary (`content_base64`)
file content
- Creates parent directories as needed and sets file permissions via
optional `mode` field
  - Comprehensive logging for debugging

- **Build Configuration** (`app/packages/lambda/efs-seeder/`):
  - esbuild config for bundling TypeScript handler to CommonJS
  - Package.json with build/clean scripts
  - TypeScript configuration extending base tsconfig

- **Terraform Integration**:
  - Added `file_seeds` optional field to `game_servers` variable schema
  - Updated EFS security group to allow NFS ingress from seeder Lambdas
  - Updated documentation with usage examples and troubleshooting

- **Documentation**:
- Added `file_seeds` configuration guide with examples (text and binary
files)
  - Included troubleshooting section for common seeder issues
  - Example tfvars showing Palworld config and mod seeding patterns

## Notable Implementation Details

- **Content-Addressed Invocation**: Uses SHA256 hash of seed content as
trigger, making re-applies idempotent when seeds haven't changed
- **Path Safety**: Validates that all seed paths start with the volume's
`container_path` and resolves safely within the mount point to prevent
directory traversal attacks
- **No Secret Storage**: Documentation explicitly warns against storing
secrets in `file_seeds` since content is persisted in Terraform state
- **Removed Entries Not Deleted**: Seeder only writes files; removed
seed entries are not cleaned up from EFS (users must manually delete via
FileBrowser)
- **Binary File Support**: Base64 encoding allows seeding of non-UTF-8
files like game mods

https://claude.ai/code/session_01VTBPgzdvwxeEw6nBscSwn6

---------

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

Author: CoderCoco

app/package-lock.json

@@ -14,7 +14,7 @@
     "dev": "concurrently -n server,client -c cyan,magenta \"npm run dev -w @gsd/server\" \"npm run dev -w @gsd/web\"",
     "prebuild": "node scripts/embed-tfstate.mjs",
     "build": "npm run build -w @gsd/shared && npm run build -w @gsd/server && npm run build -w @gsd/web",
-    "build:lambdas": "npm run build -w @gsd/shared && npm run build -w @gsd/lambda-interactions -w @gsd/lambda-followup -w @gsd/lambda-update-dns -w @gsd/lambda-watchdog",
+    "build:lambdas": "npm run build -w @gsd/shared && npm run build -w @gsd/lambda-interactions -w @gsd/lambda-followup -w @gsd/lambda-update-dns -w @gsd/lambda-watchdog -w @gsd/lambda-efs-seeder",
     "start": "node packages/server/dist/main.js",
     "test": "vitest run",
     "test:watch": "vitest",

app/package.json

@@ -0,0 +1,16 @@
+import { build } from 'esbuild';
+import { mkdirSync } from 'fs';
+
+mkdirSync('dist', { recursive: true });
+
+await build({
+  entryPoints: ['src/handler.ts'],
+  outfile: 'dist/handler.cjs',
+  bundle: true,
+  platform: 'node',
+  target: 'node20',
+  format: 'cjs',
+  minify: true,
+  sourcemap: true,
+  logLevel: 'info',
+});

app/packages/lambda/efs-seeder/esbuild.config.mjs

@@ -0,0 +1,14 @@
+{
+  "name": "@gsd/lambda-efs-seeder",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "main": "./dist/handler.cjs",
+  "scripts": {
+    "build": "node esbuild.config.mjs",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0"
+  }
+}

app/packages/lambda/efs-seeder/package.json

@@ -0,0 +1,162 @@
+/**
+ * Tests for the EFS seeder Lambda handler.
+ *
+ * The handler receives a list of file seeds and writes them to the EFS
+ * access point mounted at /mnt/efs, resolving in-container paths by stripping
+ * the first volume's container_path prefix.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mkdirSyncMock = vi.fn();
+const writeFileSyncMock = vi.fn();
+
+vi.mock('fs', () => ({
+  mkdirSync: (...args: unknown[]) => mkdirSyncMock(...args),
+  writeFileSync: (...args: unknown[]) => writeFileSyncMock(...args),
+}));
+
+/** Import after mocks are registered so the handler uses the mocked fs. */
+const { handler } = await import('./handler.js');
+
+const GAME = 'palworld';
+const CONTAINER_PATH = '/palworld';
+
+describe('efs-seeder handler', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('should write a UTF-8 text seed to the correct EFS path', async () => {
+    await handler({
+      game: GAME,
+      seeds: [{ path: '/palworld/Pal/Saved/Config/settings.ini', content: '[Settings]\nkey=value' }],
+      container_path: CONTAINER_PATH,
+    });
+
+    expect(mkdirSyncMock).toHaveBeenCalledWith(
+      '/mnt/efs/Pal/Saved/Config',
+      { recursive: true },
+    );
+    expect(writeFileSyncMock).toHaveBeenCalledWith(
+      '/mnt/efs/Pal/Saved/Config/settings.ini',
+      Buffer.from('[Settings]\nkey=value', 'utf8'),
+      { flag: 'w', mode: 0o644 },
+    );
+  });
+
+  it('should write a binary seed decoded from base64', async () => {
+    const binaryContent = Buffer.from([0x50, 0x4b, 0x03, 0x04]);
+    const b64 = binaryContent.toString('base64');
+
+    await handler({
+      game: GAME,
+      seeds: [{ path: '/palworld/Pal/Content/Paks/MyMod.pak', content_base64: b64 }],
+      container_path: CONTAINER_PATH,
+    });
+
+    expect(writeFileSyncMock).toHaveBeenCalledWith(
+      '/mnt/efs/Pal/Content/Paks/MyMod.pak',
+      binaryContent,
+      { flag: 'w', mode: 0o644 },
+    );
+  });
+
+  it('should apply a custom mode when provided', async () => {
+    await handler({
+      game: GAME,
+      seeds: [{ path: '/palworld/server.sh', content: '#!/bin/sh', mode: '0755' }],
+      container_path: CONTAINER_PATH,
+    });
+
+    expect(writeFileSyncMock).toHaveBeenCalledWith(
+      '/mnt/efs/server.sh',
+      expect.any(Buffer),
+      { flag: 'w', mode: 0o755 },
+    );
+  });
+
+  it('should write multiple seeds in a single invocation', async () => {
+    await handler({
+      game: GAME,
+      seeds: [
+        { path: '/palworld/a.ini', content: 'a=1' },
+        { path: '/palworld/b.ini', content: 'b=2' },
+      ],
+      container_path: CONTAINER_PATH,
+    });
+
+    expect(writeFileSyncMock).toHaveBeenCalledTimes(2);
+  });
+
+  it('should throw when a seed path does not start with container_path', async () => {
+    await expect(
+      handler({
+        game: GAME,
+        seeds: [{ path: '/other/path/config.ini', content: 'x=1' }],
+        container_path: CONTAINER_PATH,
+      }),
+    ).rejects.toThrow('does not start with container_path');
+  });
+
+  it('should throw when the seed path equals container_path with no file component', async () => {
+    await expect(
+      handler({
+        game: GAME,
+        seeds: [{ path: '/palworld', content: 'x=1' }],
+        container_path: CONTAINER_PATH,
+      }),
+    ).rejects.toThrow('no file component after container_path');
+  });
+
+  it('should throw on path traversal attempts', async () => {
+    await expect(
+      handler({
+        game: GAME,
+        seeds: [{ path: '/palworld/../../../etc/passwd', content: 'evil' }],
+        container_path: CONTAINER_PATH,
+      }),
+    ).rejects.toThrow();
+  });
+
+  it('should throw when a seed has neither content nor content_base64', async () => {
+    await expect(
+      handler({
+        game: GAME,
+        seeds: [{ path: '/palworld/empty.txt' }],
+        container_path: CONTAINER_PATH,
+      }),
+    ).rejects.toThrow('neither content nor content_base64');
+  });
+
+  it('should throw when a seed sets both content and content_base64', async () => {
+    await expect(
+      handler({
+        game: GAME,
+        seeds: [{ path: '/palworld/a.ini', content: 'x=1', content_base64: 'eD0x' }],
+        container_path: CONTAINER_PATH,
+      }),
+    ).rejects.toThrow('sets both content and content_base64');
+  });
+
+  it('should throw when mode is not a valid octal string', async () => {
+    await expect(
+      handler({
+        game: GAME,
+        seeds: [{ path: '/palworld/a.ini', content: 'x=1', mode: 'rwxr-xr-x' }],
+        container_path: CONTAINER_PATH,
+      }),
+    ).rejects.toThrow('invalid mode');
+  });
+
+  it('should handle an empty seeds list without errors', async () => {
+    await expect(
+      handler({ game: GAME, seeds: [], container_path: CONTAINER_PATH }),
+    ).resolves.toBeUndefined();
+
+    expect(writeFileSyncMock).not.toHaveBeenCalled();
+  });
+});

app/packages/lambda/efs-seeder/src/handler.test.ts

@@ -0,0 +1,91 @@
+import { writeFileSync, mkdirSync } from 'fs';
+import { dirname, resolve, join } from 'path';
+
+interface FileSeed {
+  path: string;
+  content?: string;
+  content_base64?: string;
+  mode?: string;
+}
+
+/** Payload sent by `aws_lambda_invocation.efs_seeder` in Terraform. */
+interface SeederEvent {
+  game: string;
+  seeds: FileSeed[];
+  /** The first volume's `container_path`, used to resolve in-container paths to EFS-relative paths. */
+  container_path: string;
+}
+
+const MOUNT_POINT = '/mnt/efs';
+
+/**
+ * Strips the container_path prefix from a seed path and resolves it to an
+ * absolute destination under MOUNT_POINT.  Throws on path-traversal attempts
+ * or if the path resolves to the mount root (i.e. no file name was given).
+ */
+function resolveDestination(seedPath: string, containerPath: string): string {
+  const normalizedContainer = containerPath.replace(/\/$/, '');
+
+  if (seedPath === normalizedContainer) {
+    throw new Error(`Seed path "${seedPath}" has no file component after container_path`);
+  }
+
+  if (!seedPath.startsWith(normalizedContainer + '/')) {
+    throw new Error(
+      `Seed path "${seedPath}" does not start with container_path "${normalizedContainer}"`,
+    );
+  }
+
+  const relative = seedPath.slice(normalizedContainer.length).replace(/^\//, '');
+
+  const dest = resolve(join(MOUNT_POINT, relative));
+
+  if (!dest.startsWith(MOUNT_POINT + '/')) {
+    throw new Error(`Path traversal detected: "${seedPath}" resolves outside mount point`);
+  }
+
+  return dest;
+}
+
+/**
+ * Writes each `file_seeds` entry to the EFS access point mounted at
+ * `/mnt/efs`.  Invoked synchronously by `aws_lambda_invocation` during
+ * `terraform apply`; throws on any error so Terraform surfaces the failure.
+ */
+export const handler = async (event: SeederEvent): Promise<void> => {
+  const { game, seeds, container_path: containerPath } = event;
+
+  console.log(`Seeding ${seeds.length} file(s) for game "${game}" (mount: ${MOUNT_POINT})`);
+
+  for (const seed of seeds) {
+    const dest = resolveDestination(seed.path, containerPath);
+
+    if (seed.content !== undefined && seed.content_base64 !== undefined) {
+      throw new Error(
+        `Seed at path "${seed.path}" sets both content and content_base64 — use one or the other`,
+      );
+    }
+
+    let content: Buffer;
+    if (seed.content_base64 !== undefined) {
+      content = Buffer.from(seed.content_base64, 'base64');
+    } else if (seed.content !== undefined) {
+      content = Buffer.from(seed.content, 'utf8');
+    } else {
+      throw new Error(`Seed at path "${seed.path}" has neither content nor content_base64`);
+    }
+
+    const modeStr = seed.mode ?? '0644';
+    if (!/^0?[0-7]{3,4}$/.test(modeStr)) {
+      throw new Error(`Seed at path "${seed.path}" has invalid mode "${modeStr}" — expected an octal string such as "0644"`);
+    }
+    const mode = parseInt(modeStr, 8);
+
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, content, { flag: 'w', mode });
+
+    console.log(`Wrote ${dest} (${content.length} bytes, mode ${seed.mode ?? '0644'})`);
+  }
+
+  console.log(`Done — ${seeds.length} file(s) seeded for game "${game}"`);
+};

app/packages/lambda/efs-seeder/src/handler.ts

@@ -0,0 +1,13 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "moduleResolution": "node",
+    "module": "ESNext",
+    "noEmit": true,
+    "composite": false
+  },
+  "include": ["src/**/*"],
+  "exclude": ["src/**/*.test.ts", "dist", "node_modules"]
+}

app/packages/lambda/efs-seeder/tsconfig.json

@@ -17,6 +17,7 @@ step 3 of the [setup guide](/setup) for details.
 | `alb.tf` | Conditional on any game having `https = true`: ACM certificate (DNS-validated), ALB + target groups per HTTPS game, HTTPS listener + HTTP→HTTPS redirect, Route 53 ALIAS records. |
 | `route53.tf` | Route 53 zone **data source** (zone must exist); the `update-dns` Lambda with its IAM, EventBridge rule on `ECS Task State Change`. |
 | `watchdog.tf` | `watchdog` Lambda with its IAM, EventBridge schedule at `rate(${watchdog_interval_minutes} minute(s))`. |
+| `efs-seeder.tf` | Conditional on any game having `file_seeds`: shared seeder SG, per-game IAM role + policy, CloudWatch log group, Lambda (VPC + EFS mount), and `aws_lambda_invocation` that re-triggers only when seed content changes. |
 | `interactions.tf` | `interactions` Lambda with IAM + Function URL (`auth_type = NONE`, CORS for `https://discord.com`). Exposes `interactions_invoke_url`. |
 | `followup.tf` | `followup` Lambda with IAM (`ecs:RunTask`, `StopTask`, `DescribeTasks`, `iam:PassRole`, `dynamodb:GetItem`/`PutItem`, `ec2:DescribeNetworkInterfaces`). Async-invoked by interactions. |
 | `discord_store.tf` | DynamoDB table (pk+sk, TTL on `expiresAt`), two Secrets Manager secrets (`${project_name}/discord/bot-token`, `/discord/public-key`) with `recovery_window_in_days = 0` and `lifecycle.ignore_changes` on seeded secret values. Optional `CONFIG#discord` DynamoDB item seeded from tfvars. Optional `BASE#discord` item holding the Terraform-managed base allowlist/admins (see `base_allowed_guilds` / `base_admin_*` variables). When `discord_bot_token`, `discord_application_id`, and at least one `base_allowed_guilds` entry are set, a `null_resource` runs `curl` to register slash commands in each base guild during apply; re-runs on token rotation or command-descriptor changes. |
@@ -31,7 +32,7 @@ step 3 of the [setup guide](/setup) for details.
 | `aws_region` | `string` | `us-east-1` | AWS region for all resources. |
 | `project_name` | `string` | `game-servers` | Prefix for named resources and the Secrets Manager paths. |
 | `vpc_cidr` | `string` | `10.0.0.0/16` | Parent CIDR; subnets are /24s within it. |
-| `game_servers` | `map(object)` | — | The single source of truth. Per-game: `image`, `cpu`, `memory`, `ports[]`, `environment[]`, `volumes[]` (`name` + `container_path`), `https`. Each `volumes` entry creates its own EFS access point rooted at `/${game}/${name}`. |
+| `game_servers` | `map(object)` | — | The single source of truth. Per-game: `image`, `cpu`, `memory`, `ports[]`, `environment[]`, `volumes[]` (`name` + `container_path`), `https`, `file_seeds[]` (optional). Each `volumes` entry creates its own EFS access point rooted at `/${game}/${name}`. See `game_servers[].file_seeds` below. |
 | `hosted_zone_name` | `string` | _(required)_ | Existing Route 53 zone looked up as a data source (e.g. `example.com`). |
 | `acm_certificate_domain` | `string` | `null` → `*.{hosted_zone_name}` | Wildcard ACM cert for the ALB listener. |
 | `dns_ttl` | `number` | `30` | TTL on Route 53 A records the update-dns Lambda writes. Keep low for fast task churn. |
@@ -46,6 +47,22 @@ step 3 of the [setup guide](/setup) for details.
 | `base_admin_role_ids` | `list(string)` | `[]` | Discord role IDs with permanent server-wide admin rights. Same Terraform-managed floor as above. |
 | `tags` | `map(string)` | defaults | Merged into `default_tags` for cost allocation (`Project`). |
 
+### `game_servers[].file_seeds` (optional)
+
+Declare files to be written to a game's EFS volume during `terraform apply`.
+Each entry in the list is:
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `path` | `string` | _(required)_ | In-container path (e.g. `/palworld/Pal/Saved/Config/LinuxServer/PalWorldSettings.ini`). The first volume's `container_path` is stripped to resolve the EFS-relative destination. |
+| `content` | `string` | `null` | UTF-8 text content. Mutually exclusive with `content_base64`. |
+| `content_base64` | `string` | `null` | Base64-encoded binary content — use for non-UTF-8 files such as mod `.pak` files (`base64 -w0 MyMod.pak`). |
+| `mode` | `string` | `"0644"` | chmod octal string applied to the written file. |
+
+When `file_seeds` is non-empty, `efs-seeder.tf` creates a seeder Lambda for the game and invokes it immediately. The invocation re-runs only when the sha256 of `file_seeds` changes, making re-applies with unchanged seeds a no-op. Removed seed entries are **not** deleted from EFS — clean them up via FileBrowser.
+
+> **Do not store secrets in `file_seeds`** — content is written verbatim into Terraform state.
+
 ## Outputs
 
 | Output | Consumer |
@@ -95,6 +112,14 @@ step 3 of the [setup guide](/setup) for details.
 - **`events:TagResource` / `UntagResource` / `ListTagsForResource`** aren't
   in any AWS-managed policy — you need `events:*` (or at least those three)
   on the deploy user. The setup guide's inline policy already covers this.
+- **`file_seeds` targets the first volume only.** The seeder Lambda mounts the
+  EFS access point for `volumes[0]`, so all seed `path` values must use that
+  volume's `container_path` as a prefix. Multi-volume games with seeds across
+  different volumes are not supported in this release.
+- **`file_seeds` content lives in Terraform state.** Suitable for config files
+  and small binary assets (mods). Do not put passwords or tokens here.
+- **Removed seed entries are not deleted from EFS.** They are simply no longer
+  managed. Delete stale files via the FileBrowser task.
 - **Removing a game from the map deletes its task definition** but does not
   stop running tasks. Stop the game from the dashboard first, then remove
   the key.