Role creation

Do not add a role-creation shortcut that bypasses the capability gate, exact creation-guild allowlist, pinned bot identity, exact guild ID, complete role inventory, effective permission and strict hierarchy evidence, requested-permission subset, capacity and logical-name checks, process-keyed planning, signed interactive confirmation, write-aware client approval, final fresh-plan match, atomic one-shot operation-key reservation, pending activity journaling, single POST, or exact role readback. If a client cannot support MCP elicitation, keep role creation unavailable in that client.

Keep this surface additive-only. Do not silently expand it to role edits, moves, assignments, deletion, rollback, icons, emoji, gradients, or permission reconciliation. Never permit ADMINISTRATOR, and require every named permission to be present in the bot's complete effective guild permission set. Treat mentionable and high-risk permissions as explicit review warnings.

Validate a complete role inventory with exactly one valid @everyone role, unique IDs, arbitrary-width permission bitfields, Discord's solid colors object, managed-role provenance, and the documented guild-role bound. Fail closed on malformed evidence, unknown member role IDs, missing MANAGE_ROLES, a bot role no higher than @everyone, ambiguous logical-name matches, managed-role collisions, conflicting existing roles, or exhausted capacity.

Exclude the raw one-shot operation key from the role plan material, signed request state, activity log, receipts, results, and errors. Bind its domain-separated hash into the plan and reserve that hash durably before the write. A reserved key remains spent after every outcome, including known failure, local record failure, or uncertainty. The MCP execute tool must remain non-idempotent, and neither the REST client nor any wrapper may automatically retry the create-role POST.

Serialize the same guild and normalized logical role name across operation keys inside one process as defense in depth. Rebuild each queued plan after the preceding execution and block the queued request without reserving its key if that write ends uncertain. The production facade also acquires a durable exact guild roles-collection claim, so connector processes sharing the activity-state root exclude overlapping role creation and retain the claim after uncertainty. Do not imply logical-name uniqueness; Discord permits duplicate role names.

Never persist role names, named permission lists, colors, audit-log reasons, raw keys, or raw Discord responses. Role-creation activity and operation records may contain only the exact guild and created-role IDs, plan digest, operation-key hash, timestamps, fixed verification and outcome values, activity ID, and sanitized error category.

Canonical source: SECURITY.md