Bind a role to an invite code, and make the binding survive the world changing (GRYT-893)

[sivert-io]

A secret link handed to trusted people should grant the right role on arrival, rather than somebody awarding it by hand afterwards.

Review-required path (src/db/**), so this is yours to merge.

Why this isn't just a column

Every other role grant here is checked with the actor in the room. resolveRoleChange asks for manage_roles, that the actor outranks the target, and that the role is strictly below the actor's own rank. An invite defers the grant to a moment nobody is present for, which breaks two of those three:

• The creator can lose standing. An admin binds moderator to a link, then is demoted. Nothing revisits the invite, so a former admin holds a link that still mints moderators.
• The role can move under the invite. Somebody with manage_roles binds a role near the bottom of the list, then drags that role to the top and ticks every permission. The link now grants near-owner, and no check ever failed.

The second needs no demotion and no second account. That is why a creation-time check alone is decoration, and why the rules run twice — at creation, and again at redemption against the world as it is then.

The four gates

All in src/services/inviteRoles.ts, pure and in one place:

1. grantable_by_invite, off by default. Rank alone would make every role below the creator silently grantable the moment it existed.
2. Never owner, never admin — by id. admin holds none of the escalation permissions (those are owner-only), so a permission-only test would let an invite hand it out. Admin is the role people mean when they say it has to be given by hand.
3. Never a role carrying manage_roles, manage_server, replace_identity or manage_bots. Re-checked at redemption, so widening a bound role later cannot smuggle it through.
4. A snapshot of where the role sat when it was bound. A role that has been dragged higher since is not the role that was agreed to. Being dragged lower is fine.

What to look at

Redemption deliberately ignores the creator's current standing. They may have left, and a link that dies when somebody leaves is a different bug. The snapshot plus the rules already bound what the link can do. It is the one judgement call here and it is the one I would most like a second opinion on.

The UPDATE in roleDefinitions.ts gained a placeholder; check the argument list still lines up. I got that wrong first time and it would have written the role id into the flag column.

Two properties fall out of existing code rather than being added, so they are worth confirming rather than trusting my reading:

• The invite block in join.ts is behind !isActiveMember, so a bound role can only land on a genuine first join, never on a reconnect carrying the same stored code. (That also answers the question of what happens when an existing member uses the link: they never reach the invite path at all, and never spend a use.)
• The grant is addMemberRole, not setServerRole, so an invite can raise somebody above the tier default and never below it.

Tests

14 on the rules, including both exploits above, named so a future reader knows what they are protecting. 679 pass, yarn build clean.

There is no integration test on the database path in applyInviteRole — the rules are covered, the wiring is only typechecked.

Not in this PR

The client half. Nothing sets the flag or binds a role from the UI yet, so this ships inert until that lands.

🤖 Generated with Claude Code

[sivert-io]

Migration verified against a populated database

The thing a real server does on upgrade, rather than only the fresh-database case the tests cover.

Built a pre-change database by hand — role_definitions and invites with the old columns and rows in them — then booted this branch against it:

• All three columns added to tables that already had rows. NOT NULL DEFAULT 0 on a populated table is the case that can fail, and does not.
• member and trusted kept their positions in the list.
• Both existing roles came out not invite-grantable. That is the fail-safe default doing its job: upgrading a server does not quietly make anything grantable.
• The existing invite still reads, keeps its consumed count, and grants nothing.

Also booted three times against the same database with no duplicate-column error, so the hasColumn guard holds and a restart is not a migration.

Scratch files used for this were deleted; the worktree is clean.