Group Member and Ban Management Methods

Group hosting protocol · Common method conventions

group.member.leave

A current non-owner member leaves immediately.

Request Parameters

Response Object

None.

Processing and Errors

Check account/session equality and that the account remains a current unbanned non-owner at activation.

Invalid fixed fields/account format returns bad_request; missing group returns not_found; account mismatch, nonmembership, owner status, or ban returns forbidden; concurrency conflict returns state_conflict.

Resubmitting the same request with a valid session returns forbidden because the caller is no longer a member.

Success removes membership, closes all account device intervals, deletes its pending reset, generates a new relay secret, advances one epoch, and appends the leave event. If rotation preparation exists, the same atomic commit MUST remove this member's staged box under group.secret.rotation.prepare, retaining other boxes and original expiry. Voluntary departure does not invalidate preparation. After persistence, send group.timeline.changed; actual deletion of a pending reset additionally requires group.member.recovery.changed under the deletion recipient scope.

Clients verifying leave events MUST confirm that the referenced certificate belongs to account, verify the body signature and prior-state leave permission, then apply departure by that account.

group.member.remove

Owner or administrators remove one or more members. Owners may remove any non-owner; administrators only ordinary members. Neither the calling account nor current owner may be targeted.

Request Parameters

Response Object

None.

Processing and Errors

Invalid fixed fields, empty batch, or duplicate accounts returns bad_request; missing group returns not_found; insufficient owner/administrator role, caller ban, targeting owner/caller, or administrator targeting an administrator returns forbidden. Any noncurrent target or concurrent membership change returns state_conflict.

Validate all targets first, then atomically remove the entire batch, close target intervals, clean pending resets, generate one relay secret, advance one epoch, and append one event. Existing rotation preparation MUST lose these members' staged boxes in the same commit under group.secret.rotation.prepare, retaining others and original expiry. Removal does not invalidate preparation.

After persistence, send group.timeline.changed; actual pending-reset deletion also sends group.member.recovery.changed under deletion recipient scope.

group.member.ban

Owners may ban any non-owner account; administrators only ordinary members or nonmembers. Bans add targets to the set and prohibit group interfaces and rejoining.

Request Parameters

Response Object

None.

Processing and Errors

Validation and Ban Count Limits

Invalid fixed values, empty array/accounts, or duplicates returns bad_request; missing group returns not_found; insufficient role, caller ban, targeting owner, or administrator targeting administrator returns forbidden. New bans causing the merged count to exceed the configured cap, or concurrency conflicts, return state_conflict.

Calculate additions and total from current ban state at activation; already banned targets do not count twice. After cap reduction, requests targeting only already banned accounts cannot be rejected solely because the existing total exceeds the new cap, but still require permission, signatures, and current head. Mixed batches with additions exceeding the cap are rejected entirely.

State Changes and Notifications

Validate the whole batch's permissions and cap, then atomically merge bans, delete all targets' pending join applications, remove current members among them, close their device intervals, and clean their pending resets. Application deletion consumes no invitation uses. If any members were removed, generate one relay secret and advance one epoch. In the same commit, existing rotation preparation MUST remove actually removed members' boxes under group.secret.rotation.prepare, preserving others and original expiry. Banning does not invalidate preparation. If no targets are current members, membership, intervals, keys, and staged rotation remain unchanged. Any failed check prevents the entire batch from taking effect.

Each success appends exactly one complete signed meshline.group.member.ban administration event and atomically advances the chain, without extra removal events.

After persistence, send group.timeline.changed; deleted applications additionally trigger group.application.changed; actual pending-reset deletion triggers group.member.recovery.changed under deletion recipient scope.

Clients verify permission from preceding membership, remove target members, and update bans together.

group.member.unban

Owner or administrators lift one or more bans at once.

Request Parameters

Response Object

None.

Processing and Errors

Invalid fixed values, empty array/accounts, or duplicates returns bad_request; missing group returns not_found; insufficient role or caller ban returns forbidden; concurrency conflict returns state_conflict.

Atomically remove listed existing bans, append the complete signed request, and advance the chain. Unbanning restores no deleted applications, membership, roles, or closed message/key intervals. Rejoining follows ordinary application/approval. Membership and epoch remain unchanged; clients update bans through the chain.

After persistence, send group.timeline.changed.