Moderation and the audit log

From mnema-talk v3.3.13, rendered on this site.

This page describes moderation (timeouts, bans, kicking, message moderation, reports) and the audit log that records it. Code: internal/auth/memberadmin/moderation.go, internal/perm and internal/audit. Permissions and the hierarchy are in roles-and-permissions.md.

Who may moderate whom

Every moderation action needs its permission and a highest role strictly above the member's. The Owner can never be targeted, and nobody can moderate themselves. The checks run on the server inside the transaction that changes the member, under the permission lock, so a concurrent role change cannot move the target out of reach between the check and the write.

ActionPermissionNotes
Timeout, end a timeoutTimeout membersPOST / DELETE /api/admin/users/{id}/timeout; /timeout in the composer
Ban, unban, list bansBan membersPOST / DELETE /api/admin/users/{id}/ban, GET /api/admin/bans; /ban in the composer
Disable an accountManage membersDisable: ends sessions and blocks sign-in until Enable. No record beyond the audit log
KickKick members/kick in the composer, see Kicks
Remove from a TalkDisconnect membersRemoves the member from that Talk only; they stay signed in. A role can hold it server-wide or through an overwrite on one Talk or category
Read and close reportsManage reportsSee Blocking and reports
Automod rulesAdministratorSee Automod; no new permission bit
Moderation history and notes of a memberManage reportsSee Moderation history and moderator notes

Timeouts

A timeout silences a member until a time passes: they can still read, and still delete or take back their own words, but they lose Send messages, Attach files, Add reactions, Mention @all and @here, Connect, Speak, Video, Send direct messages, Edit the wiki, Manage the wiki and Create invites (member invites) (perm.TimeoutMask). Durations run from 5 seconds to 28 days; the interface offers 1 min, 5 min, 1 h, 1 day, 1 week or a custom time, with an optional reason of up to 200 characters.

It is enforced in the permission snapshot, so every surface honours it with no extra check: REST (messages, replies, edits, reactions, uploads), the WebSocket hub (joining a Talk, typing), and the SFU (it drops audio and video without Speak and Video). Channel overwrites cannot hand back what a timeout took. Starting a timeout rebuilds the permission state at once, which removes the member from the Talk they are in (voice_kicked, missing_permission). It ends by itself: the end time is compared at every check, so nothing has to run, and the client counts down and refetches its permissions when it reaches zero.

The member gets a moderation_notice event (shown as "You were timed out for 1 h: spam") and sees a banner with the remaining time and the reason (GET /api/permissions carries timeout_until and timeout_reason). Everyone sees that a member is timed out in the member list (timeout_until), but not the reason.

Bans

A ban ends the member's sessions and connections and blocks signing in, with an optional reason and an optional duration (otherwise it lasts until someone lifts it). The account and its messages stay. A ban is its own state, separate from Disable: banning does not disable the account, and lifting a ban (or its expiry) never re-enables an account that was disabled before, just as Enable never lifts a ban. Every check of whether an account may act (sign-in, sessions, WebSockets, mentions, the member list) uses one condition (auth.ActiveSQL) that covers both, and a ban whose time has passed stops counting at once, before the expiry job (it runs every minute) clears it.

By default the invite the account registered with is revoked, so that code cannot create the account anew; untick it in the dialog (revoke_invite: false) for an invite shared with others. Deleting an invite is Manage invites territory, so the invite is only revoked when the person banning also holds that permission (or is the Owner); a moderator with Ban members alone bans the account and the invite stays valid. Registration remembers the invite (users.invite_id). Banning by IP address is deliberately not offered: behind a proxy an address is shared or spoofable, and the trusted-proxy model makes it a weak signal.

A banned member who signs in with the right password sees the reason and the end of the ban; with a wrong password the answer does not reveal the ban. The admin console has a Bans tab (for Ban members) listing active bans with reason, moderator and end, and Unban.

Kicks

A kick sends a member away for now and leaves no sanction. It is the "remove now, may come back" action: every session of the member ends (browser, desktop client and push devices), their live connections close, and they leave the Talk they are in. They can sign in again at once; nothing is stored against the account (compare Disable, which blocks sign-in, and Ban). The member first receives a kicked WebSocket event ({"reason": "..."}) and the web app shows a calm note; the connection closes a moment later.

The permission is Kick members (bit 1 << 23). It is off for @everyone and on for the seeded Moderator and Admin (migration 0097), so by default those roles, Administrators and the Owner can kick. The role hierarchy is enforced like for a ban: a highest role strictly above the member's, never the Owner, never oneself. The only way to kick is the built-in /kick @member [reason] command (POST /api/channels/{id}/interactions, bots): the server checks the permission again inside the command and writes the audit entry moderation.kick (details: reason, via: slash). /timeout and /ban run the same actions as the admin console and write the same moderation.timeout and moderation.ban entries, also marked via: slash.

Slow mode

A text or Talk-chat channel can make members wait between two messages (slow_mode_seconds, 0 to 86400, set with the channel edit by Manage channels; a channel chip shows it). It counts posts, thread replies and uploads of one member in that channel. Anyone who holds Manage messages in the channel (the Owner always) is exempt, and so are webhooks. The refusal is 429 RATE_LIMITED with Retry-After. The check and the insert share a transaction and concurrent posts of one member in one channel are serialized with an advisory lock, so a burst cannot slip several messages through the same gap.

Raid protection

Raid protection keeps a sudden wave of new accounts calm. It has three parts, all under Admin > Sign-in & messages (the Raid protection section) (Owner and Administrators only; every change is audited as settings.raid or settings.lockdown). Code: internal/raid (the settings and the door), internal/perm (the waiting times). It sits beside the automod Raid protection rule, which times out a wave after it came in; this part keeps the wave out or holds it back.

Lockdown. One click shuts the door: while it is on nobody new can sign up, not even with a valid invite (503 UNAVAILABLE, "sign-ups are paused for now"). Also pause creating invites stops POST /api/admin/invites and POST /api/me/invites (member invites) as well (409). It ends by itself after 1, 6 or 24 hours if you choose, otherwise when you switch it off. Existing members, their sessions and the Owner are untouched. While it is on, administrators see a banner under the header with an End lockdown button.

Sign-up limit. At most N new members within M minutes (0 turns it off; the window is 1 to 1440 minutes). When the window is full, further sign-ups get the same calm "paused" answer until there is room again. The count is the accounts created within the window (bots and deleted accounts excluded); the check runs before the password is hashed, so a closed door costs nothing.

Waiting time of new members. Three settings, each 0 (off) to 30 days: how long after joining a member may write (send messages, polls, uploads, edit the wiki), react, and speak in Talks (the microphone, and with it camera and screen share). A member who is too new keeps reading, joining Talks and listening. The gate lives in the permission snapshot, like a timeout, so REST, the WebSocket hub (reactions) and the SFU (audio) enforce it from one place and it ends by itself without a reload. The refusal is 403 FORBIDDEN with the seconds left ("new members can write in 600 s"); the client shows it as "You can write in 10 min." in the composer, on the reaction button and on the Talk's microphone button, and fetches the permissions again when the wait is over. GET /api/permissions carries new_member (write_at, react_at, speak_at) while a wait is running.

When a wait ends the server tells the member's clients and the Talk they are in (one timer for all members, set again after every load of the permission snapshot), so the microphone and the Stage's raised hand work at that moment without rejoining. Turning a gate on later holds members who joined recently by their real sign-up time.

Direct messages follow the waits too, because DM spam is the classic raid vector. While the write wait runs a new member cannot start a conversation or a group, nor add people to one (403 with the seconds left; GET /api/permissions then says can_start_direct_messages: false). They can answer a conversation where the other person wrote first, but not write first, not even in an existing, still empty conversation (gateNewMemberFirstWrite in internal/chat/messages/dm_gate.go). Reactions in conversations follow the react wait, and joining or starting the call of a conversation (which includes speaking and video there) follows the speak wait.

Who never waits: the Owner, bots, Administrators, and members with a role that holds Bypass new member limits (bit 26, roles; Moderator and Admin roles get it by migration 0083). It is separate from the slow mode exemption. A member the permission snapshot does not know yet (it is reloaded at least every minute) is counted from the moment that snapshot was loaded (at most a minute short of the real sign-up time), and exactly from the next load on.

Auto-delete

Manage channels can let a channel forget: Channel settings > Delete old messages with a period of hours, days or weeks (1 hour to 365 days), of the messages with their files or of the files only, or Use the community default (off by default, and never for direct messages or their call Talks, which the database refuses; see timed messages). Turning it on asks for confirmation, because the deletion cannot be undone. The channel then shows a timer chip in its header and a line under it, so nobody writes unaware.

A sweeper runs every ten minutes, removes the messages older than the period in batches of 200 (at most 25 batches per channel and run, the rest on the next run) and deletes their attachments through the same path as a deleted message. Clients get message_delete for each. Pinned messages stay, and so does a thread root while it has a reply that is newer than the period or pinned (also one that is written or pinned while a run is underway); the old replies of such a thread go. With Files only the files of the old messages are removed instead and each shows a "File removed" tile; the text stays, and files of pinned messages stay. Turning auto-delete off stops a run at once. The Owner and Administrators can set a community default that every channel without a setting of its own follows. Every run that removed something is one channel.auto_delete_run audit entry with the counts; changing the setting is channel.auto_delete_set. The audit entries of message.delete are not written for these deletions (they would hold the text of everything the channel was told to forget).

Message moderation

Holders of Manage messages in a channel can:

  • Pin and unpin a message (PUT / DELETE /api/channels/{channelID}/messages/{messageID}/pin); a pin icon marks it. Manage messages is the pin permission as well (no separate bit): whoever may remove a message in a channel may also pin one there, and the Owner always may. A channel keeps at most 50 pins (a 51st answers 409); pinning a pinned message changes nothing. GET /api/channels/{channelID}/pins lists the pins, newest pin first, for anyone who can view the channel, and the channel header opens that list with a jump to each message. A real pin or unpin broadcasts message_update and pins_changed to the channel's viewers only; a pin also shows a compact note under the messages of every open client (it is not a stored message, so it is gone after a reload; the list is the record). Both actions are audited (message.pin, message.unpin). Deleting a message unpins it. A pinned message carries pinned_at and pinned_by (the member who pinned it, absent once that account is gone) on every payload and on the pins_changed event, and the pinned list shows "Pinned by".
  • Delete with a reason: DELETE /api/channels/{channelID}/messages/{messageID} takes an optional JSON body {"reason": "..."}. The author is told through a moderation_notice; the audit entry (message.delete, moderator: true) holds the full text and the reason. The Owner's messages can still only be deleted by the Owner.
  • Delete a member's latest messages (POST /api/channels/{channelID}/messages/bulk-delete with user_id, count 1 to 100 and a reason): replies and attachments go with them. It needs a higher role than the member (checked in the same transaction as the delete) and leaves threads that hold a reply of the Owner alone (also one whose reply is committed while the delete runs; the delete then takes fewer messages than asked, the summary has both numbers). Every message gets its own audit entry with its text, plus one moderation.bulk_delete summary.
  • Read the edit history of an edited message (GET /api/channels/{channelID}/messages/{messageID}/edits, "Edit history" in the message menu of an edited message). See below.

Edit history

Every edit keeps the version it replaces: its text, when that version was written (the creation time for the original) and who wrote it. Only members who hold Manage messages in the channel and can view it (the Owner always) can read the versions, newest first. There is no dedicated permission: reading what a message used to say is the same trust as deleting it, and a new bit would need a default, a migration of existing roles and one more switch in the roles screen for no gain. The author and other members get 403; reading is not audited (it changes nothing) but is rate limited to 60 reads a minute per member (edit_history in the rate-limit metrics).

  • Not exposed elsewhere. The versions are not in the message list, the thread, WebSocket events, search, push or notification previews, webhook payloads, bot or gateway events, or any export except the author's own (edits.json in "Export my data", at most the newest 2,000 versions; a member never receives anybody else's earlier text). The audit log's message.edit entry (full before and after, see above) is a separate record with its own access and retention.
  • Bounded. At most 50 versions are kept per message, the oldest go first. EDIT_HISTORY_RETENTION_DAYS (default 0: keep) additionally drops versions replaced longer ago than that many days; the worker runs every six hours.
  • Removed with their source. Deleting the message deletes its versions (cascade); the message.delete entry keeps them first (edit_versions, newest first, with the same text policy as the entry's own text). Deleting an account deletes the versions of that person's messages together with the message text; the messages stay as emptied tombstones. Edits made before this feature (migration 0047) have no history.

Blocking and reports

Blocking a member

Any member can block any other member (PUT /api/me/blocks/{userID}; at most 500 blocks). Blocking is private: the blocked member is never told, and no response, event, list or error text they can read depends on it. For the blocker it means:

  • the web app collapses the blocked member's messages to "Blocked message · show" (the client reads GET /api/me/blocks and the block_updated event) wherever another member's words are shown: the message list and threads, the "replied to" line, forwarded quotes, search hits and their thread roots, the pin list, forum post cards and titles, event comments, saved messages and reminders (their note and remove button stay). Showing one message shows it everywhere until the page is reloaded; in search, Enter or a click on a folded hit shows it first. Search, the forum filter and these lists are not filtered by the server; the client folds them, so a hit still counts in the number of results. A due reminder's in-app notice leaves the text out; its push, which the blocker set up themselves, still names the message;
  • the blocked member's mentions and replies create no entry in the mentions inbox (which excludes direct messages entirely), no mention count and no push, whatever the channel's notification level, and a plain message of theirs sends no push either. It is decided when the entry is listed or the push is sent, so it also covers messages that were written before the block;
  • in any direct message conversation (group or two-person), unread and mention counts and the conversation's last-activity time leave out messages by members the reader blocked, and push recipients skip blockers;
  • in a direct message conversation of two, a block stops writing in both directions: new messages (uploads, polls and commands included), edits of earlier messages, reactions, poll votes, forwards into the conversation and starting a Talk from it are refused with a 403 that does not say why (the other side only sees that the member cannot be written to). The chat of the conversation's Talk, if one was open before the block, follows the same rule with the same answers, and its messages by the blocked member do not count as unread for the blocker. New messages and edits in both are refused the same way when the other side's account is disabled or erased. Taking back stays possible in both: each side may still delete their own messages, remove their own reactions and withdraw their votes. The Talk itself is not touched: it stays open, and whoever sits in it keeps their seat and can still be heard (removing them would tell the blocked member). In a group, the conversation continues, but nobody can add a member who blocked them;
  • unblocking brings the earlier inbox entries back, because nothing was deleted.

A block is not a sanction: it changes nothing for anybody else and is not audited. Blocking the Owner or a moderator only mutes them for the blocker. Deleting an account removes the blocks to and from it; the export lists the member's own blocks by id (blocks.json).

Direct messages

Moderators have no way into a direct message conversation. The Owner and Administrators are treated like any other non-member: they get the same answer as for a conversation that does not exist. The only route to the text of a direct message is a report by one of its members (below). Moderation actions that target a member (timeout, ban, kick) work as usual, and a timeout also takes Send direct messages. The Owner and Administrators can switch direct messages off for the community under Admin > Sign-in & messages: existing conversations stay readable, and nothing new can be started or written.

Reporting a message

Any member can report a message they can see (POST /api/messages/{messageID}/report, with a category of spam, harassment, illegal or other and an optional note of up to 500 characters). A message the member cannot see answers 404, like a missing one; their own message is refused. At most 10 reports an hour and 50 open reports per member, and repeating an open report returns the first one.

The report stores its own copy of the message and up to 20 messages around it (15 before, 5 after) with author names, text and the names, types and sizes of attachments (never the files). The copy is the point: the author deleting or editing the message afterwards does not change what was reported. It is also the only way a moderator ever reads a direct message: moderators and Administrators have no path into a direct message conversation, and a report shows only what the reporter chose to report and its context.

Members with Manage reports (the Owner and Administrators always) work the queue under Admin > Reports (the tab shows only where the server lists the reports feature; GET /api/admin/reports, status filter, newest first; GET /api/admin/reports/{id} for the copy). They close a report as resolved or dismissed with an optional note, and can delete a closed one, which removes the copy. The reporter is not notified of the outcome. Reading a report needs only this permission, not access to the channel: a report of a private channel is readable by its handlers.

The number of open reports shows as a small amber count on the community header and the Admin console menu entry, for these members only. It is read once from GET /api/admin/reports/open-count and then follows the reports_open WebSocket event, which the server sends only to sessions that hold Manage reports whenever a report is filed, closed or raised by Automod.

  • Audited without text. report.create, report.resolve and report.delete are in the audit log for the Owner and Administrators only, with the category and ids but never message text or the note.
  • Erasure. When an account is erased, its text is blanked in every report copy (as the reported message or as context) and its links to reports are cut; the reports stay.

Automod

Automod checks every new and edited message, and every sign-up, against rules the Owner or an Administrator sets under Admin > Automod (the tab shows only where the server lists the automod feature). Code: internal/automod (the rules), internal/moderation (the REST routes).

Rules

RuleWhat it does
Blocked wordsWords and phrases, matched as whole words, without regard to case. * in an entry stands for any run of letters and digits (cheat* catches cheat and cheating). Spaces inside a phrase match any white space; invisible characters (zero-width spaces, soft hyphens) are ignored, so they do not hide a word.
LinksOne mode: block every link, allow only the listed domains, or block the listed domains. A domain covers its subdomains. A link is anything starting with http://, https:// or www., also one inside another link (https://allowed.example/r?u=https://other.example is judged by both hosts). The host is read the way a browser reads it: after any user name (the part before the last @), without the port, with percent escapes, full-width forms and accents mapped as the browser maps them, on the text as written (accents and invisible characters stay part of the host). Where the app could end a link earlier (Markdown such as ** or || around it, punctuation after it, the ) of text), every possible host is judged and each must pass. A link whose host cannot be read exactly counts as a link for every link and the new-account rule, and as not allowed for an allow list; a block list blocks it when the best reading of its host falls under a listed domain. A host no resolver can answer for (https://allowed.example's) leads nowhere, so an allow list lets it be. Two kinds of link are refused by every mode because nobody can say where the app would lead: one whose address part is longer than 2,000 characters (the app cuts a link target there), and one in a message so tangled with links that reading it would cost more than the fixed amount of work a message gets.
Mention spamA message with more than N different mentions (@name, @all and @here count once each; the same name twice counts once).
New accountsAccounts younger than a time (1 minute to 30 days) may not post links, may not attach files, may not do either, or may not post at all.
Raid protectionMore than N accounts joining within M seconds. Every account of that window, and everyone who joins while the raid lasts, is timed out for the restriction time (1 minute to a day), and one entry in the reports queue announces the raid. A moderator lifts a timeout like any other. At most one such rule.

Each rule except raid protection has an action: block (the message is refused with a 400 that names the rule, so the author knows why; nothing is stored) or flag (the message is delivered and only marked in the queue). It may also time the author out for a set time. A longer timeout the member already has is never shortened. Each rule has exempt roles and exempt channels, which skip it. The Owner, holders of Administrator, bots and incoming webhooks are never checked.

A rule is edited as a whole (PUT); its kind cannot change. At most 25 rules. The rules are compiled once per version of the configuration and kept in memory; a change through the API takes effect on the next message, and a change made behind the server's back (a restore) within 30 seconds. The check in the send path reads no table except the creation time of the author's account, and that is remembered.

Automod covers every way a member's message is created: plain messages, uploads, thread replies, polls, forwards, slash command replies and edits (an edit that breaks a blocking rule is refused and the message stays as it was). It screens this other text the same way, with the same refusal, exemptions and actions: forum post titles and their edits, a forum's tags (name and emoji) and guidelines, the new name of a temporary Talk, comments under a community event and their edits, and an event's title, description and location when it is created or an edit sets them (Manage events does not exempt; the event's Talk, if it has one, counts as the channel for exempt channels). Tags, guidelines, Talk names and event text are not messages, so their queue entries have no message id; an entry about event text names the event's title as the place. Other text, such as profiles, wiki pages and the names of an event's roles, is not screened.

Direct messages

In a direct message only the link and mention spam rules apply. A hit there is queued without any text: the entry says which member broke which rule in a direct message, nothing more. Automod never keeps the text of a direct message (a blocked one is dropped, a flagged one stays where it was written, and the recipients can still report it themselves, which is then the only way a moderator reads it).

The queue

Every hit is an entry in Admin > Reports, marked Automod, with the rule's name as it was when it hit (the entry outlives the rule) and source: "automod" in the API. It has no reporter. For a blocked message in a channel the entry keeps the refused text (and nothing around it: no context), exactly the part a member's report would keep; a flagged message is referenced by id. While an entry of one member and one rule is open, further hits only count up on it (hit_count), so a spammer cannot flood the queue; closing it lets the next hit open a new one. A raid alert has kind: "alert" and no message. Closing, dismissing and deleting work as for any report (Manage reports).

Audit entries: automod.rule_create, automod.rule_update, automod.rule_delete (by the Administrator), automod.timeout and automod.raid (actor Automod). Messages and hits are not audited; the queue is their record.

Defaults

New servers and upgraded ones start with the same conservative rules (migration 0066), all editable and deletable: mention spam above 10 mentions (block), new accounts under 10 minutes may not post links (block), raid protection at more than 10 joins in 10 seconds (restriction of 10 minutes, flag). Blocked words (empty word list) and Links are present and off. See the upgrade notes.

API

All under /api/admin, Administrator only: GET /automod, POST /automod/rules, PUT /automod/rules/{id}, DELETE /automod/rules/{id}. See api/openapi.json.

Moderation history and moderator notes

A member's profile has a Moderation tab for everyone with Manage reports (never for yourself, for bots, or on a server without the moderation.history feature). It shows

  • a timeline: timeouts, ended timeouts, bans, unbans, expired bans, kicks, removals from a Talk, role changes made by moderators, reports about the member (category and status, never the reporter, the note or the text), and automod hits (rule, outcome, count). It is read from the audit log and the reports table; the latest 200 events;
  • notes: short private texts (up to 1000 characters, at most 100 per member) that moderators write about a member. A note can count as a strike; the strike count is the small badge on the tab.

A moderator edits and deletes their own notes; an Administrator (or the Owner) deletes any note, and edits only their own. Nobody opens the history or the notes of themselves, whatever they hold.

The timeline needs Manage reports only, not View audit log, even though it shows reasons, role changes and Talk kicks: handling a report needs the history. Grant Manage reports with that in mind.

GET /api/admin/users/{id}/moderation, POST .../moderation/notes, PUT and DELETE .../moderation/notes/{noteID}, all Manage reports. Reading is open to every holder; writing a note (POST, PUT) also needs a highest role strictly above the member's, and never about the Owner, like every other moderation action (403).

Moderator notes are moderator data

  • Never visible to the member they are about, in no response, event, list or search, and never in their data export (the export holds what the person wrote and what they filed, not what moderators keep about them).
  • Audited without text: moderation.note_add, moderation.note_edit and moderation.note_delete are in the audit log for the Owner and Administrators only, and never carry the note.
  • Erasure. When an account is erased the notes stay, because they are the moderators' record (for example against a returning member): the member they are about is shown as the account's tombstone, "Deleted member", and a note written by an erased moderator shows "Deleted member" as its author. The notes are not erased with the account, and the privacy page lists them under Moderation records; an Administrator can delete any of them. Operators who need a shorter retention delete notes by hand.

Audit log

An append-only record of what was done to the instance and by whom.

What an entry holds

FieldMeaning
id, created_atOrder and time
actor_id, actor_nameThe member who acted (the name as it was then); empty for the server itself
actiongroup.verb, for example role.update, user.disable, invite.create
target_type, target_id, target_nameWhat the action was done to
detailsSanitized: the request, a before snapshot of the audited fields, and changes (from/to)
request_idThe X-Request-Id of the request, to find the matching server log lines

What is recorded

Every successful mutating request below /api/admin is recorded by one middleware that works from a route table (internal/audit/routes.go), so a handler cannot forget it: roles (create, edit, delete, reorder, assignment), channel and category overwrites, channels and categories (create, edit, delete, duplicate, layout), invites (created, changed, revoked), members (disable, enable, end sessions, status line, password set or reset, login unlock, the admin-wide Talk kick user.talk_kick, which names no Talk), incoming and outgoing webhooks (create, edit, regenerate or rotate, delete), media pruning and deletion, and self-update. The wiki is edited by members, not through /api/admin, so it records its own actions: wiki.create, wiki.edit, wiki.move, wiki.delete, wiki.restore, wiki.lock and wiki.image (a picture uploaded) (wiki). A test walks the router and fails when an admin route is missing from the table; an unlisted route is still recorded under a generic admin.<method> action. Refused or failed requests leave no entry. Reading the log is not recorded.

When an entry can be missing

The entries of a message deletion or edit, a report, a registration, an account deletion, a new wiki page and a new event (not a series) are written in the same database transaction as the change: the change and its entry exist together or not at all, and a failed entry fails the change. Every other entry is written right after the change committed, in a statement of its own: all of the /api/admin middleware's, and the entries of a bulk delete (message.delete per message and moderation.bulk_delete), pins, ending a poll, the forum (post updates, settings, tags), Talks (voice.join and voice.leave, removing a member from one Talk, Talk settings, the removal of a temporary Talk), event edits, cancellations, series, covers, roles, role templates and comment removals, wiki edits, moves, deletions, restores, locks and images, role self-assignment, auto-delete settings and runs, automod timeouts and raid mode, expired bans, removed avatars, the moderation slash commands, the edit-history view, and the auth events (sign-in and failed sign-in, password change and reset mail, e-mail, second factor, sessions, data export). That write does not end with the request: a client that disconnects in that moment still leaves its entry (the write has five seconds of its own). What is left is a crash of the server or a database failure (an error, a restart) in that moment: the change stays, its request answered success, the entry is missing, and the server logs audit log write failed with the action. A deploy shuts the server down gracefully and does not cut that moment. The admin middleware works outside the handlers' transactions by design (it snapshots before and after any handler), so it cannot join them.

Events besides admin actions

ActionWhenWhat it holds
message.deleteA message is deleted, by its author or a moderatorThe full text, the attachment names, types and sizes (not the files), author, channel, send time, moderator (true when someone else deleted it) and the thread replies (author and text, up to 50)
message.editAn author edits a messageText before and after, author, channel
message.edit_history_viewA moderator opens the earlier versions of someone else's messageMessage, author, channel and how many versions were shown, not their text. One entry per reader and message every ten minutes; reading your own message leaves none
poll.endA moderator ends a poll that someone else postedMessage, author, channel and the question. An author ending their own poll is not audited. No entry of any poll ever holds a vote: an anonymous poll does not store who chose what
role.self_assign, role.self_removeA member takes or drops a role an admin opened to everyone (see Roles members choose themselves)The role. The member is the actor; the same request again, which changes nothing, is not recorded
channel.auto_delete_setSomeone with Manage channels turns a channel's auto-delete on, off, to another period or scope, or back to the community defaultThe channel with its settings before and after (auto_delete_hours, auto_delete_scope; NULL hours: follows the default)
settings.auto_delete_default_setThe Owner or an Administrator changes the community's auto-delete defaultThe settings before and after (auto_delete_default_hours, auto_delete_default_scope)
settings.message_lifetimes_setThe Owner or an Administrator switches messages with a lifetime on or off or changes the longest lifetimeThe settings before and after (message_lifetimes_enabled, message_lifetime_max_seconds)
channel.auto_delete_runThe sweeper removed messages or files of a channelThe channel, the period (hours, and days for older readers), the scope, whether it came from the community default, how many messages and attachments went, and whether the run finished (complete). Written by the server itself, without an actor; a run that removes nothing writes nothing. Never the text
voice.join, voice.leaveA member enters or leaves a TalkMember and Talk with the time. A reload within the grace period is neither. High volume on a busy server: filter by the Talk presence group. Under a burst of more than about a thousand joins and leaves in a moment, the audit log may not record every one (the hub's voice join and voice leave log lines name the member and the Talk of each one at the default log level, and mnema_ws_dropped_total{reason="audit_presence"} counts the misses)
voice.disconnectA moderator removes a member from one Talk (Disconnect members there)The moderator, the member and the Talk. It says who was in which Talk, so it is read like voice.join; the moderation history lists it as a Talk removal without the Talk. A removal from a conversation's call Talk is not recorded, like voice.join there
report.create, report.resolve, report.deleteA member reports a message; a moderator closes or deletes the reportThe report id and category (and the closing status). Never message text or notes. See Blocking and reports
auth.loginSuccessful sign-inThe member
auth.login_failed, auth.login_lockedA wrong password, or a blocked attempt, for an existing accountThe member. At most one entry per account and kind per minute, and no address, password or typed name; a name that is no account is not stored at all
auth.register, auth.password_change, auth.logout_allOwn-account eventsThe member
auth.session_revoke, auth.sessions_revoke_othersA member signs out one of their sessions, or all others, under Settings > SessionsThe member
auth.email_set, auth.email_remove, auth.email_verified, auth.password_reset_mailA member sets, removes or confirms an e-mail address, or resets the password through the link in a mailThe member. The address itself is never stored in the log
auth.two_factor_enabled, auth.two_factor_disabled, auth.recovery_codes_regenerated, auth.recovery_code_usedA member changes or uses their second factorThe member. Never a code or secret
auth.two_factor_failed, auth.two_factor_alertA wrong second-step code (at most one entry per account and minute); five or more not yet reportedThe member. No code
user.two_factor_resetThe Owner (after confirming their own password and code, or via the host command mnema-talk reset-2fa) turns a member's second factor offWho did it and the member
auth.account_delete, auth.export_request, auth.export_downloadA member deletes their account or asks for / takes their data exportThe account id only. After a deletion, earlier entries about the account lose names and details
system.mail_testThe Owner sends a test mailWho did it; neither recipient nor mail text

Text channels have no membership (who may see one follows from roles and overwrites, which are audited), so there is no join entry for them.

What is never stored

Passwords, tokens, secrets, hashes, invite codes, cookies, authorization values and session ids are redacted by key name wherever they appear. A web address anywhere in a value is reduced to its scheme and host plus a short hash of the whole address (https://hooks.example.com [sha256:1a2b3c4d]), because webhook URLs carry tokens in the path as well as the query; the hash still shows that an address changed. Snapshots list columns one by one, so a secret column added to a table later does not leak by accident. Strings are clipped to 200 characters and an entry to 32 KiB.

Privacy. Message deletions and edits record the message text, and Talk joins and leaves record who was where and when. That is the point of an audit log, and it means the log holds personal data. Name it in your privacy notice, and set AUDIT_RETENTION_DAYS if you want old entries to expire.

Immutability and retention

Entries are inserted once. A database trigger refuses UPDATE, and the API has no write route. The only deletion is the retention job: AUDIT_RETENTION_DAYS=0 (default) keeps everything forever, like MEDIA_RETENTION_DAYS=0; a positive number deletes entries older than that many days (checked every six hours). Entries have no foreign key to users, so they outlive the accounts they mention.

The diff cannot be evaded

The request body is captured whatever its Content-Type says, and a body that is not a JSON object or is too large is marked (request_unparsed, request_truncated) instead of dropped. The changes of an edit do not come from the request at all: the audited fields are read before and after the change and compared, so they show what really happened. If an entry grows beyond its size limit, the request is trimmed first (request_truncated), then after, before and params; changes is kept.

Access

Only the Owner and holders of the View audit log permission may read it (GET /api/admin/audit-log; the permission also opens the admin console on the Audit log tab). Administrator includes it. What a reader sees depends on the class of the entry. The table lives in code (audit.Classes, pinned action by action in a test), so a new action cannot quietly default to something wider than intended; this is the same table. An action gets the class of the first row it matches. A test reads the server's source for every action an entry can be written with and fails for one without a row of its own, and the last row, which catches everything else, is the narrowest class (Owner and Administrators only): a forgotten action is hidden, not shown to every auditor. The Auditors class names each of its actions one by one. The class is applied when the log is read, so older entries follow the current table.

ClassWho reads itActions
AuditorsEvery holder of View audit logThe actions of roles (role.create, role.update, role.delete, role.reorder, role.self_assign, role.self_remove), members (user.disable, user.enable, user.sessions_revoke, user.status, user.roles_set, user.talk_kick: the admin-wide kick, which names no Talk), invites (invite.create, invite.vanity_link, invite.update, invite.revoke, invite.limits, invite.member_create, invite.member_revoke: the bounds of member invites and the invites members create and revoke themselves), moderation (moderation.timeout, moderation.timeout_remove, moderation.ban, moderation.unban, moderation.ban_expired, moderation.kick), automod (automod.rule_create, automod.rule_update, automod.rule_delete, automod.timeout, automod.raid), custom emoji (emoji.create, emoji.rename, emoji.delete), events without a Talk (event.create, event.edit, event.cancel, event.comment_delete, event.role_template_create, event.role_template_update, event.role_template_delete) and the wiki (wiki.create, wiki.edit, wiki.move, wiki.delete, wiki.restore, wiki.lock, wiki.image; the wiki is open to every member who may view it)
ChannelHolders of View audit log who can view the entry's channel when they read; an entry that names no channel is hidden from themmessage.*, poll.*, voice.* (with voice.disconnect, a removal from one Talk; older versions wrote that removal as user.talk_kick with the Talk in its details, and such entries are read the same way), forum.* (post titles, their authors and tag names of a possibly private forum), channel.* (a private channel's name, topic and overwrites are private too), event.talk_*, moderation.bulk_delete
Owner and Administrators onlyThe Owner and members with Administratorcategory.* and layout.apply (a private category's name and overwrites are private too, and a layout lists every placement), auth.* (sign-ins, failures, lockouts, password changes of other members), webhook.*, outgoing_webhook.*, bot.*, media.*, settings.*, system.*, import.*, moderation.note_*, user.password_set, user.password_reset, user.two_factor_reset, user.lockout_clear, report.* (a report may concern a private channel or a direct message), admin.* (routes not yet named in the route table), and every action without a row of its own

The check runs on every read against the current permissions, so access that is granted later also opens the older entries of that channel, and access that is taken away closes them. The Owner and Administrators see everything. Deleted thread replies are recorded by id only; a reply deleted on its own has its own entry with its text. The audit log is not sent to outgoing webhooks.

The admin.% row in audit.Classes is mapped to Owner and Administrators on purpose (VisPrivileged): unlisted admin routes are not known to be harmless. The parenthetical on admin.* in the table above is that catch-all. TestClassesPinTheVisibilityOfEveryAction pins admin.post to that class, and TestAuditCoversEveryMutatingAdminRoute checks the named mutating /api/admin routes. The catch-all stays.

Who may send, talk and moderate

Each cell is the function that enforces the action for that actor, and a test that already exercises it. gap means that pair is absent. The role bits are the Defaults section: Member is @everyone with perm.DefaultEveryone, Moderator and Admin are the seeded roles, and the Owner is the account users.role = 'admin'. There is no User role and no Owner role. Neither seeded role holds the Administrator bit. Both hold Manage reports and Kick members (migration 0097). TestStarterRolesAreSeededEmpty checks those bits and TestBuiltInModeratorAndAdminHandleReportsAndKick the report queue and /kick.

TestTimeoutTakesPostingAndSpeakingButNotReading builds its own "admin" with the Administrator bit. That user is separate from the seeded Admin role. Snapshot.silence still strips perm.TimeoutMask from every non-owner while a timeout is in the future, and Snapshot.Channel applies that after overwrites, so an overwrite cannot hand the mask back. Snapshot.Channel returns every permission for the Owner before that step.

Slow mode runs in InsertMessage unless the message has a WebhookID or the context is exempt. sendContext sets the exemption when the caller has Manage messages. botCreateMessage calls InsertMessage without that exemption, so a bot token is subject to slow mode. build sets WebhookID for an incoming webhook, so InsertMessage skips slow mode for it. TestBotAPIMessages and TestWebhookStandsOnItsOwn reach InsertMessage; neither turns slow mode on. TestSlowModeHoldsBackMembersButNotModerators covers a member, a holder of Manage messages, and the Owner.

A ban or a disable stops an account through auth.ActiveSQL (disabled_at, or a banned_at that is still in force). sessionUser loads a member session with that condition. TestActiveConditionsQualifyTheTable pins both columns.

Posting, reacting and uploading do not write an audit entry. The audit cell is the class of the entries that path does record.

ActorSend messageUploadReactEdit or delete own messageJoin a TalkSlow modeTimeout maskBan or disablePer-route rate limitAudit class
Member (@everyone)sendContext (TestChannelPermissionsGateTheirActions); DefaultsUploadContext (TestChannelPermissionsGateTheirActions); DefaultstoggleReaction (TestChannelPermissionsGateTheirActions); DefaultsEditMessage, DeleteMessageAs (TestChannelPermissionsGateTheirActions); DefaultsjoinVoice (TestJoinNeedsViewAndConnect); DefaultsInsertMessage (TestSlowModeHoldsBackMembersButNotModerators); DefaultsSnapshot.silence (TestTimeoutTakesPostingAndSpeakingButNotReading)sessionUser (TestBanBlocksSessionsLoginAndSocketsAndUnbanRestores, TestAdminDisablesAndEnablesUsers)n/a (not a per-route limit)ClassOf (TestClassesPinTheVisibilityOfEveryAction)
Moderator (seeded set)sendContext (TestChannelPermissionsGateTheirActions); DefaultsUploadContext (TestChannelPermissionsGateTheirActions); DefaultstoggleReaction (TestChannelPermissionsGateTheirActions); DefaultsEditMessage, DeleteMessageAs (TestChannelPermissionsGateTheirActions); DefaultsjoinVoice (TestJoinNeedsViewAndConnect); DefaultssendContext (TestSlowModeHoldsBackMembersButNotModerators); DefaultsSnapshot.silence (TestTimeoutTakesPostingAndSpeakingButNotReading)sessionUser (TestBanBlocksSessionsLoginAndSocketsAndUnbanRestores, TestAdminDisablesAndEnablesUsers)n/a (not a per-route limit)ClassOf (TestClassesPinTheVisibilityOfEveryAction)
Admin (seeded set)sendContext (TestChannelPermissionsGateTheirActions); DefaultsUploadContext (TestChannelPermissionsGateTheirActions); DefaultstoggleReaction (TestChannelPermissionsGateTheirActions); DefaultsEditMessage, DeleteMessageAs (TestChannelPermissionsGateTheirActions); DefaultsjoinVoice (TestJoinNeedsViewAndConnect); DefaultssendContext (TestSlowModeHoldsBackMembersButNotModerators); DefaultsSnapshot.silence (TestTimeoutTakesPostingAndSpeakingButNotReading)sessionUser (TestBanBlocksSessionsLoginAndSocketsAndUnbanRestores, TestAdminDisablesAndEnablesUsers)n/a (not a per-route limit)ClassOf (TestClassesPinTheVisibilityOfEveryAction)
Owner (the account)sendContext (TestTheOwnerCannotBeTouched); DefaultsUploadContext (TestPrivateChannelIsInvisibleEverywhereToOutsiders); DefaultstoggleReaction (TestGatewayDeliversOnlyWhatTheBotMaySee); DefaultsEditMessage (TestGatewayDeliversOnlyWhatTheBotMaySee); DeleteMessageAs (TestModeratorsCannotDeleteTheOwnersMessages)joinVoice (TestJoinNeedsViewAndConnect)sendContext (TestSlowModeHoldsBackMembersButNotModerators)Snapshot.Channel (TestTimeoutTakesPostingAndSpeakingButNotReading)checkTarget (TestModerationRespectsHierarchyAndPermissions); targetUser (TestTheOwnerCannotBeTouched)n/a (not a per-route limit)ClassOf (TestClassesPinTheVisibilityOfEveryAction)
Bot tokenbotCreateMessage (TestBotAPIMessages)botUpload (TestBotAPIUpload)setBotReaction (TestBotAPIReactions)botEditMessage, botDeleteMessage (TestBotAPIMessages)n/a (bots have no voice session)InsertMessage (TestBotAPIMessages)Snapshot.silence (TestTimedOutBotCannotSpeak)Lookup (TestBannedBotIsRefusedAndDisconnected)LimitSends (TestBotAPIRateLimits)ClassOf (TestClassesPinTheVisibilityOfEveryAction)
Incoming webhookpost (TestWebhookStandsOnItsOwn)checkAllowed (TestExecuteAppliesTheWebhooksSettings)n/a (posts through InsertMessage only)n/a (posts through InsertMessage only)n/a (posts through InsertMessage only)InsertMessage (TestWebhookStandsOnItsOwn)n/a (posts through InsertMessage only)n/a (posts through InsertMessage only)execute (TestWebhookRateLimits)n/a (posts are not audited)
Bot gatewayn/a (delivers events only)n/a (delivers events only)n/a (delivers events only)n/a (delivers events only)n/a (delivers events only)n/a (delivers events only)n/a (delivers events only)validTokens (TestBannedBotIsRefusedAndDisconnected)frameLimiter.allow (TestGatewayFrameRateLimit)n/a (events are not audited)

n/a means the actor does not do that action, or the limit is not per route. Chat sends have no per-route limiter. The limiters that exist are loginPerIP (login), LimitSends (bot token), execute (incoming webhook) and frameLimiter.allow (bot gateway). Signed-in member routes share perUser.By (api_user, 600 a minute) for writes and api_user_read (3000 a minute) for reads, one bucket of each per user, not per route. A bot token's edits and deletes are message.edit and message.delete, already classed with the member rows. An incoming webhook only posts, and the bot gateway only delivers events. Neither is audited, same as a member's post, so those audit cells are n/a.

API

GET /api/admin/audit-log takes the filters actor (user id), action (exact or a group: role matches every role.*), target_type, target_id, from and to (RFC 3339 or YYYY-MM-DD), before (an entry id, for the next page) and limit (1 to 200, default 50). It returns {entries, next_before}, newest first. See api/openapi.json.

Something wrong on this page? Tell us.