Server admin 21b: fluxer-devserver serveradmin scenario: channels, members, bans, invites, sudo (#689) #727

Closed
charles wants to merge 0 commits from serveradmin-21b-devserver-channels-members-sudo into serveradmin
Owner

Stacked on: serveradmin-21a-devserver-community-roles (already merged into serveradmin; the merge was a no-op)

What this builds

The second half of the serveradmin devserver scenario (Server administration spec §9, plan Task 21b), answered as the fork's API does at ba98441b. Everything is in crates/fluxer-devserver.

  • Channels (admin.rs): PATCH /channels/{id} for a guild channel or category: the §3.6 fields with the schema's limits (name normalised with #663's channel_name unless TEXT_CHANNEL_FLEXIBLE_NAMES, topic 1–1024 or null, slowmode 0–21600, type 0 ↔ 5, link url, voice bitrate 8000–384000 clamped to the guild's maximum, user_limit 0–99, voice_connection_limit 1–100, rtc_region from rest/rtc_regions.json with UPDATE_RTC_REGION), MANAGE_CHANNELS in the channel; permission_overwrites replaces the whole list (MANAGE_ROLES, a non-owner cannot grant a bit they lack in the channel, overwriteGrantedBits); a category's new list reaches its synced children; CHANNEL_UPDATE. PATCH /guilds/{id}/channels ports updateChannelPositionsByList / computeGuildChannelReorderPlan (GuildChannelOrdering.ts): parent, preceding sibling or position, categories move with their channels, the voice-below-text rule, 50 per category, lock_permissions, every channel renumbered from 1, CHANNEL_UPDATE_BULK with all of them (as the server sends). DELETE /channels/{id}: a category's channels lose their parent first (CHANNEL_UPDATE each), the channel's invites go, CHANNEL_DELETE. GET /channels/{id}/follower-stats.
  • Members, bans, search (moderation.rs): member PATCH (and @me) for nick, roles, communication_disabled_until / timeout_reason with the server's checks (CHANGE_NICKNAME / MANAGE_NICKNAMES, MODERATE_MEMBERS, never oneself or an administrator, 365 days); a body with only voice fields keeps the existing voice behaviour. Role PUT/DELETE, kick (GUILD_MEMBER_REMOVE; oneself or the owner reads as UNKNOWN_MEMBER, as removeMember does), ban (GUILD_BAN_ADD then GUILD_MEMBER_REMOVE), bans list, unban (GUILD_BAN_REMOVE, USER_IS_NOT_BANNED on user_id), and members-search (query, roles, dates, bots, join method with MANAGE_GUILD only, sort, paging; indexing: true first when [serveradmin] indexing_first). The target check is the gateway's check_target_member.
  • Invites (invites.rs): GET /guilds/{id}/invites (MANAGE_GUILD; serveradmin/invites.json plus the guild's other invites, each code once) and DELETE /invites/{code} (its inviter, else MANAGE_GUILD; INVITE_DELETE {code, channel_id, guild_id}).
  • Identity check (sudo.rs): POST /guilds/{id}/delete, transfer-ownership and an mfa_level change answer 403 SUDO_MODE_REQUIRED (has_mfa, methods) without a valid token or verification, 400 INVALID_FORM_BODY on password (INVALID_PASSWORD) or mfa_code (INVALID_MFA_CODE) for a wrong one, and succeed with X-Fluxer-Sudo-Mode-JWT (five minutes) for [serveradmin] password or, with account_has_2fa = true, totp_code. Delete sends GUILD_DELETE and later READYs lack the guild; transfer sends GUILD_UPDATE with the new owner_id (UNKNOWN_MEMBER, CANNOT_TRANSFER_OWNERSHIP_TO_BOT). An mfa_level change also needs 2FA on the account (MUST_ENABLE_2FA_BEFORE_REQUIRING_FOR_MODS).
  • Recording: every accepted administration request (21a's routes included) is recorded with its body and sudo header: AdminScript::recorded() -> Vec<RecordedRequest>. New AdminScript::index_members_first() and set_account_has_2fa(bool).
  • serveradmin.toml gains indexing_first, password = "demo", totp_code = "000000", account_has_2fa (the demo account's values, not secrets). README updated.

No new fixture file: the requests and events reuse the proto fixtures of Tasks 1–3; bodies are built from the fluxer-proto request types in the tests.

Tests

crates/fluxer-devserver/tests/serveradmin.rs: channel_patch_echoes_update, overwrites_replaced_whole, positions_apply_parent_and_sibling_and_emit_bulk, delete_category_orphans_children, follower_stats_count_following_channels, member_patch_nick_roles_timeout, kick_and_ban_events_in_order, unban_and_not_banned_error, members_search_filters_sort_paging, indexing_first_answer, invite_delete_event, sudo_required_then_password_then_token, wrong_password_field_error, totp_when_account_has_2fa, transfer_changes_owner_and_emits_guild_update, moderator_refusals; unit tests for the sudo state, the target check, the search limits and the nick rules. Written first and seen failing (commit test(devserver): …), then passing. FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci green locally. No display tests involved.

Deviations from the plan, and things to look at

  • The real server sends X-Fluxer-Sudo-Mode-JWT after a password only to accounts that can hold a token (TOTP or passkey enrolled); the plan asks for the header on every success, so the devserver issues one for the password too. Documented in sudo.rs and the README.
  • PATCH /guilds/{id}/channels's category limit and voice rule follow executeChannelReorder; categories with a parent are CATEGORIES_CANNOT_HAVE_PARENTS (from applySinglePositionUpdate, which runs before the planner's CATEGORIES_CANNOT_HAVE_PARENT_CHANNEL).
  • Touched outside the listed files, minimally: guild_channels.rs (channel_name made pub(crate) to reuse #663's normalisation instead of duplicating it) and lib.rs (registration: two mods, the RecordedRequest re-export, three AdminScript methods). chat.rs's Refused gained an optional data map that http::refused spreads into the body (for has_mfa / methods).
  • Not modelled: the op-14 member list after a kick or ban (it keeps reading the fixtures), protected thread bits in overrides, invites' guild-visit side effects.

Closes #689

🤖 Generated with Claude Code

Stacked on: serveradmin-21a-devserver-community-roles (already merged into `serveradmin`; the merge was a no-op) ## What this builds The second half of the `serveradmin` devserver scenario (Server administration spec §9, plan Task 21b), answered as the fork's API does at ba98441b. Everything is in `crates/fluxer-devserver`. - **Channels** (`admin.rs`): `PATCH /channels/{id}` for a guild channel or category: the §3.6 fields with the schema's limits (`name` normalised with #663's `channel_name` unless `TEXT_CHANNEL_FLEXIBLE_NAMES`, `topic` 1–1024 or null, slowmode 0–21600, `type` 0 ↔ 5, link `url`, voice `bitrate` 8000–384000 clamped to the guild's maximum, `user_limit` 0–99, `voice_connection_limit` 1–100, `rtc_region` from `rest/rtc_regions.json` with `UPDATE_RTC_REGION`), `MANAGE_CHANNELS` in the channel; `permission_overwrites` replaces the whole list (`MANAGE_ROLES`, a non-owner cannot grant a bit they lack in the channel, `overwriteGrantedBits`); a category's new list reaches its synced children; `CHANNEL_UPDATE`. `PATCH /guilds/{id}/channels` ports `updateChannelPositionsByList` / `computeGuildChannelReorderPlan` (`GuildChannelOrdering.ts`): parent, preceding sibling or position, categories move with their channels, the voice-below-text rule, 50 per category, `lock_permissions`, every channel renumbered from 1, `CHANNEL_UPDATE_BULK` with all of them (as the server sends). `DELETE /channels/{id}`: a category's channels lose their parent first (`CHANNEL_UPDATE` each), the channel's invites go, `CHANNEL_DELETE`. `GET /channels/{id}/follower-stats`. - **Members, bans, search** (`moderation.rs`): member `PATCH` (and `@me`) for `nick`, `roles`, `communication_disabled_until` / `timeout_reason` with the server's checks (`CHANGE_NICKNAME` / `MANAGE_NICKNAMES`, `MODERATE_MEMBERS`, never oneself or an administrator, 365 days); a body with only voice fields keeps the existing voice behaviour. Role `PUT`/`DELETE`, kick (`GUILD_MEMBER_REMOVE`; oneself or the owner reads as `UNKNOWN_MEMBER`, as `removeMember` does), ban (`GUILD_BAN_ADD` then `GUILD_MEMBER_REMOVE`), bans list, unban (`GUILD_BAN_REMOVE`, `USER_IS_NOT_BANNED` on `user_id`), and `members-search` (query, roles, dates, bots, join method with `MANAGE_GUILD` only, sort, paging; `indexing: true` first when `[serveradmin] indexing_first`). The target check is the gateway's `check_target_member`. - **Invites** (`invites.rs`): `GET /guilds/{id}/invites` (`MANAGE_GUILD`; `serveradmin/invites.json` plus the guild's other invites, each code once) and `DELETE /invites/{code}` (its inviter, else `MANAGE_GUILD`; `INVITE_DELETE {code, channel_id, guild_id}`). - **Identity check** (`sudo.rs`): `POST /guilds/{id}/delete`, `transfer-ownership` and an `mfa_level` change answer 403 `SUDO_MODE_REQUIRED` (`has_mfa`, `methods`) without a valid token or verification, 400 `INVALID_FORM_BODY` on `password` (`INVALID_PASSWORD`) or `mfa_code` (`INVALID_MFA_CODE`) for a wrong one, and succeed with `X-Fluxer-Sudo-Mode-JWT` (five minutes) for `[serveradmin] password` or, with `account_has_2fa = true`, `totp_code`. Delete sends `GUILD_DELETE` and later READYs lack the guild; transfer sends `GUILD_UPDATE` with the new `owner_id` (`UNKNOWN_MEMBER`, `CANNOT_TRANSFER_OWNERSHIP_TO_BOT`). An `mfa_level` change also needs 2FA on the account (`MUST_ENABLE_2FA_BEFORE_REQUIRING_FOR_MODS`). - **Recording**: every accepted administration request (21a's routes included) is recorded with its body and sudo header: `AdminScript::recorded() -> Vec<RecordedRequest>`. New `AdminScript::index_members_first()` and `set_account_has_2fa(bool)`. - `serveradmin.toml` gains `indexing_first`, `password = "demo"`, `totp_code = "000000"`, `account_has_2fa` (the demo account's values, not secrets). README updated. No new fixture file: the requests and events reuse the proto fixtures of Tasks 1–3; bodies are built from the `fluxer-proto` request types in the tests. ## Tests `crates/fluxer-devserver/tests/serveradmin.rs`: `channel_patch_echoes_update`, `overwrites_replaced_whole`, `positions_apply_parent_and_sibling_and_emit_bulk`, `delete_category_orphans_children`, `follower_stats_count_following_channels`, `member_patch_nick_roles_timeout`, `kick_and_ban_events_in_order`, `unban_and_not_banned_error`, `members_search_filters_sort_paging`, `indexing_first_answer`, `invite_delete_event`, `sudo_required_then_password_then_token`, `wrong_password_field_error`, `totp_when_account_has_2fa`, `transfer_changes_owner_and_emits_guild_update`, `moderator_refusals`; unit tests for the sudo state, the target check, the search limits and the nick rules. Written first and seen failing (commit `test(devserver): …`), then passing. `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` green locally. No display tests involved. ## Deviations from the plan, and things to look at - The real server sends `X-Fluxer-Sudo-Mode-JWT` after a password only to accounts that can hold a token (TOTP or passkey enrolled); the plan asks for the header on every success, so the devserver issues one for the password too. Documented in `sudo.rs` and the README. - `PATCH /guilds/{id}/channels`'s category limit and voice rule follow `executeChannelReorder`; categories with a parent are `CATEGORIES_CANNOT_HAVE_PARENTS` (from `applySinglePositionUpdate`, which runs before the planner's `CATEGORIES_CANNOT_HAVE_PARENT_CHANNEL`). - Touched outside the listed files, minimally: `guild_channels.rs` (`channel_name` made `pub(crate)` to reuse #663's normalisation instead of duplicating it) and `lib.rs` (registration: two `mod`s, the `RecordedRequest` re-export, three `AdminScript` methods). `chat.rs`'s `Refused` gained an optional `data` map that `http::refused` spreads into the body (for `has_mfa` / `methods`). - Not modelled: the op-14 member list after a kick or ban (it keeps reading the fixtures), protected thread bits in overrides, invites' guild-visit side effects. Closes #689 🤖 Generated with [Claude Code](https://claude.com/claude-code)
The Task 21b tests, before the endpoints exist: channel PATCH and the
whole-array overrides, the one-element reorder with parent and sibling,
deleting a category, member nick/roles/timeout, kick and ban event order,
unban, the member search, the indexing answer, invite revocation, and the
identity check (password, wrong password, TOTP, token reuse) with delete
and transfer, plus the moderator's refusals.

Refs #689

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The second half of the serveradmin scenario (Server administration spec §9),
answered as the fork's API does at ba98441b:

- PATCH /channels/{id} for guild channels and categories
  (channel_data/ChannelOperationsService.ts editChannel,
  ChannelRequestSchemas.ts): the §3.6 fields and limits, the whole-array
  permission_overwrites with the grant check, synced children; CHANNEL_UPDATE.
- PATCH /guilds/{id}/channels (guild/services/channel/
  ChannelOperationsService.ts updateChannelPositionsByList,
  GuildChannelOrdering.ts computeGuildChannelReorderPlan): parent and
  preceding sibling, the voice placement rule, 50 per category;
  CHANNEL_UPDATE_BULK with every channel.
- DELETE /channels/{id} (children orphaned first), follower-stats.
- Member PATCH (nick, roles, timeout; @me), role PUT/DELETE, kick, ban
  (GUILD_BAN_ADD then GUILD_MEMBER_REMOVE), bans list, unban
  (USER_IS_NOT_BANNED), members-search with filters, sort, paging and the
  indexing answer (GuildMemberOperationsService.ts,
  GuildModerationService.ts, GuildMemberSearchController.ts,
  GuildMemberSearchSchemas.ts; target check from guild_members_roles.erl).
- Guild invites list and DELETE /invites/{code} (InviteService.ts;
  INVITE_DELETE).
- The identity check (SudoVerificationService.ts, SudoModeMiddleware.ts):
  SUDO_MODE_REQUIRED, INVALID_PASSWORD / INVALID_MFA_CODE on the field, the
  X-Fluxer-Sudo-Mode-JWT token; POST /guilds/{id}/delete, transfer-ownership
  and an mfa_level change behind it.
- Every accepted administration request is recorded (AdminScript::recorded).

Refs #689

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Author
Owner

Independent review: Task 21b (devserver: channels, members, bans, invites, sudo)

Scope: git diff f1bf88fc..origin/serveradmin-21b-devserver-channels-members-sudo (69147a29).

Plan tests: all 15 named tests exist in crates/fluxer-devserver/tests/serveradmin.rs and check the spec's values: 32-char nick, 365-day timeout, ban duration 0 or 60–63072000 s, delete history ≤ 604800, USER_IS_NOT_BANNED on user_id, PRECEDING_CHANNEL_MUST_SHARE_PARENT, CATEGORIES_CANNOT_HAVE_PARENTS, VOICE_CHANNELS_CANNOT_BE_ABOVE_TEXT_CHANNELS, CANNOT_POSITION_CHANNEL_RELATIVE_TO_ITSELF, MAX_CATEGORY_CHANNELS at 50, SUDO_MODE_REQUIRED with has_mfa/methods, password and mfa_code field errors, the token header. They parse answers and events through the proto types. There is also an extra test, follower_stats_count_following_channels.
Interfaces: every endpoint and event in the Interfaces block is there. So are the [serveradmin] indexing_first / password / totp_code / account_has_2fa keys, and recording of accepted requests (AdminScript::recorded, RecordedRequest).
Invariants: only fluxer-devserver (and one scenario TOML) changed. Malformed bodies get INVALID_FORMAT and never panic. The only credentials are the demo password and code, which are not secrets.

Parity spot-checks against the fork (ba98441b4):

  • reorder_plan / sort_for_ordering / move_block match packages/schema/.../GuildChannelOrdering.ts (computeGuildChannelReorderPlan, the category span, orderUnchanged) line for line.
  • apply_channel_move matches applySinglePositionUpdate: the derived preceding sibling from position, voice at the end, text before the first voice, assertCategoryCapacity only on a parent change, and validateChannelVoicePlacement.
  • The overwrite grant check matches channel_data/ChannelOperationsService.ts and overwriteGrantedBits: (after.allow & ~before.allow) | (before.deny & ~after.deny), checked against the channel permissions for every target id, owner exempt. Synced children follow propagatePermissionsToSyncedChildren.
  • verifySudoMode matches: totp only with 2FA, the password only without it, INVALID_PASSWORD / INVALID_MFA_CODE.
  • removeMember matches: the owner or oneself gives UNKNOWN_MEMBER. So does banMember (self gives UNKNOWN_MEMBER, a non-member can be banned without the target check).
  • validateTimeout matches (an administrator target is refused, a past time clears the timeout), as do the GuildMemberSearchController permission set, the supplemental masking and the request and response shapes, and ChannelFollowerStatsResponse.

Findings

  1. minor: MAX_TIMEOUT_MS is 365 days. The server uses ms('1 year'), which is 365.25 days, so a timeout between 365 and 365.25 days is refused here but accepted by the server. This only matters at the edge.
  2. minor: reorder_plan returns "unchanged" before check_voice_placement runs. The server validates placement before its orderUnchanged early return, so a no-op move over an already invalid layout answers 204 here and 400 there.
  3. minor: the lock_permissions: true sync checks MANAGE_ROLES in the guild, not in the channel, and skips the server's allow/deny grant checks (syncPermissionsWithParent). The client always sends false (spec §3.8).
  4. minor: permission_overwrites with a duplicate id is kept twice. The server's Map keeps only the last one.
  5. minor: sudo.rs says the password and code are "never stored". RecordedRequest.body does keep them, in memory, which Task 22 needs to assert the replay (Review Focus 6). Reword the doc comment. The README's "supplemental is null" should say "an object with null fields". The code is right in both cases.
  6. minor (already noted by the implementer): PATCH …/members/@me with roles applies them, but the server ignores them. A body that mixes voice and moderation fields drops the voice ones. No client sends either.

Local gate: FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci in a fresh worktree at 69147a29: all steps passed.

Verdict: APPROVED. No blocking findings. The minor ones can be follow-ups or left as they are.

## Independent review: Task 21b (devserver: channels, members, bans, invites, sudo) Scope: `git diff f1bf88fc..origin/serveradmin-21b-devserver-channels-members-sudo` (69147a29). **Plan tests:** all 15 named tests exist in `crates/fluxer-devserver/tests/serveradmin.rs` and check the spec's values: 32-char nick, 365-day timeout, ban duration 0 or 60–63072000 s, delete history ≤ 604800, `USER_IS_NOT_BANNED` on `user_id`, `PRECEDING_CHANNEL_MUST_SHARE_PARENT`, `CATEGORIES_CANNOT_HAVE_PARENTS`, `VOICE_CHANNELS_CANNOT_BE_ABOVE_TEXT_CHANNELS`, `CANNOT_POSITION_CHANNEL_RELATIVE_TO_ITSELF`, `MAX_CATEGORY_CHANNELS` at 50, `SUDO_MODE_REQUIRED` with `has_mfa`/`methods`, password and `mfa_code` field errors, the token header. They parse answers and events through the proto types. There is also an extra test, `follower_stats_count_following_channels`. **Interfaces:** every endpoint and event in the Interfaces block is there. So are the `[serveradmin] indexing_first / password / totp_code / account_has_2fa` keys, and recording of accepted requests (`AdminScript::recorded`, `RecordedRequest`). **Invariants:** only `fluxer-devserver` (and one scenario TOML) changed. Malformed bodies get `INVALID_FORMAT` and never panic. The only credentials are the demo password and code, which are not secrets. **Parity spot-checks against the fork (ba98441b4):** - `reorder_plan` / `sort_for_ordering` / `move_block` match `packages/schema/.../GuildChannelOrdering.ts` (`computeGuildChannelReorderPlan`, the category span, `orderUnchanged`) line for line. - `apply_channel_move` matches `applySinglePositionUpdate`: the derived preceding sibling from `position`, voice at the end, text before the first voice, `assertCategoryCapacity` only on a parent change, and `validateChannelVoicePlacement`. - The overwrite grant check matches `channel_data/ChannelOperationsService.ts` and `overwriteGrantedBits`: (after.allow & ~before.allow) | (before.deny & ~after.deny), checked against the channel permissions for every target id, owner exempt. Synced children follow `propagatePermissionsToSyncedChildren`. - `verifySudoMode` matches: totp only with 2FA, the password only without it, `INVALID_PASSWORD` / `INVALID_MFA_CODE`. - `removeMember` matches: the owner or oneself gives `UNKNOWN_MEMBER`. So does `banMember` (self gives `UNKNOWN_MEMBER`, a non-member can be banned without the target check). - `validateTimeout` matches (an administrator target is refused, a past time clears the timeout), as do the `GuildMemberSearchController` permission set, the `supplemental` masking and the request and response shapes, and `ChannelFollowerStatsResponse`. **Findings** 1. *minor*: `MAX_TIMEOUT_MS` is 365 days. The server uses `ms('1 year')`, which is 365.25 days, so a timeout between 365 and 365.25 days is refused here but accepted by the server. This only matters at the edge. 2. *minor*: `reorder_plan` returns "unchanged" before `check_voice_placement` runs. The server validates placement before its `orderUnchanged` early return, so a no-op move over an already invalid layout answers 204 here and 400 there. 3. *minor*: the `lock_permissions: true` sync checks `MANAGE_ROLES` in the guild, not in the channel, and skips the server's allow/deny grant checks (`syncPermissionsWithParent`). The client always sends `false` (spec §3.8). 4. *minor*: `permission_overwrites` with a duplicate id is kept twice. The server's Map keeps only the last one. 5. *minor*: `sudo.rs` says the password and code are "never stored". `RecordedRequest.body` does keep them, in memory, which Task 22 needs to assert the replay (Review Focus 6). Reword the doc comment. The README's "`supplemental` is `null`" should say "an object with null fields". The code is right in both cases. 6. *minor (already noted by the implementer)*: `PATCH …/members/@me` with `roles` applies them, but the server ignores them. A body that mixes voice and moderation fields drops the voice ones. No client sends either. **Local gate:** `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` in a fresh worktree at 69147a29: **all steps passed**. **Verdict: APPROVED.** No blocking findings. The minor ones can be follow-ups or left as they are.
Author
Owner

Merged into serveradmin by hand (the merge API returns 405); the commits are in the branch.

Merged into `serveradmin` by hand (the merge API returns 405); the commits are in the branch.
charles closed this pull request 2026-11-16 01:28:31 +00:00

Pull request closed

Sign in to join this conversation.
No description provided.