#682 serve-auth: auth config schema and mode flag for swamp serve

Parent

Sub-issue of #662 (serve authentication & authorization). Layer 4, item 1.

Summary

Add an authentication config schema to `swamp serve` — the foundation for all layer 4 work. This introduces `--auth-mode none|token|oauth` and related flags that control whether and how the server authenticates connections. Everything else in layer 4 (token support, OAuth, admin materialization) depends on this config existing.

What to build

CLI flags on `swamp serve`

```bash swamp serve \ --auth-mode token \ --admins 'sub:oauth|user-123' \ --cert-file server.crt --key-file server.key ```

New flags:

• `--auth-mode mode:string` — `none` (default), `token`, or `oauth`. Controls authentication behavior.
• `--admins principals:string` — comma-separated list of principal IDs that get `admin` on `access:*`. Required when auth-mode is `token` or `oauth` (server refuses to start without at least one admin).
• `--allowed-collectives list:string` — comma-separated collective slugs for admission policy (OAuth mode)
• `--allowed-users list:string` — comma-separated `sub:...` identifiers for admission policy (OAuth mode)
• `--oauth-provider url:string` — OAuth authorization server URL (default: `https://swamp-club.com\`)
• `--oauth-client-id id:string` — OAuth client ID
• `--groups-field field:string` — field name on userinfo response containing group/collective memberships (default: `collectives`)

Validation at startup

The serve command validates the config before starting:

• `mode: none` — no other auth flags needed (today's behavior)
• `mode: token` — `--admins` is required. Server refuses to start without at least one admin.
• `mode: oauth` — `--admins`, `--oauth-client-id` required. `--oauth-provider` defaults to swamp-club.
• `--admins` without an enforcing mode is a warning (you configured admins but auth is off)

Config type

A typed config object parsed from the CLI flags, available to downstream layer 4 work:

```typescript interface ServeAuthConfig { mode: "none" | "token" | "oauth"; admins: string[]; // principal IDs allowedCollectives?: string[]; // admission policy allowedUsers?: string[]; // admission policy oauthProvider?: string; // authorization server URL oauthClientId?: string; // client ID groupsField: string; // userinfo groups field name } ```

Pass through ConnectionContext

The parsed auth config should be available on `ConnectionContext` (or a sibling) so server-side handlers can access it. Layer 4 items 2-4 will use it.

Scope

• Add CLI flags to `src/cli/commands/serve.ts`
• Parse and validate auth config at startup
• Type definition for `ServeAuthConfig`
• Validation logic (required fields per mode, refuse-to-start rules)
• Pass config through to ConnectionContext
• Tests for validation (each mode's requirements, missing admins, invalid combos)
• No authentication implementation — just the config schema and validation

Out of scope

• `mode: token` authentication logic — layer 4, item 2
• OAuth device grant flow — layer 4, item 3
• Admin materialization — layer 4, item 4
• Enforcement — layer 5

References

• Serve command: `src/cli/commands/serve.ts`
• Existing serve flags: `--host`, `--port`, `--cert-file`, `--key-file`, `--grant-reload`
• ConnectionContext: `src/serve/connection.ts`
• Design decisions from #662 phase breakdown ripple