Role configuration

Do not add a role-configuration shortcut that bypasses the dedicated capability gate, exact role allowlist, existing guild read scope, pinned application and bot identities, exact guild and role IDs, complete role inventory, complete role-holder counts, effective and post-change permission evidence, strict hierarchy 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, one partial PATCH, complete response validation, or exact role, full inventory, and holder-count readback. If a client cannot support MCP elicitation, keep role configuration unavailable in that client.

Keep the surface partial and exact. Permit only an explicit role name, modern colors, hoist, mentionability, and named permission grant or revoke deltas. Preserve omitted fields and unrelated permission bits. Never target @everyone or a managed role, and never add deletion, reordering, assignment, creation, icons, Unicode emoji, bulk reconciliation, or raw permission-bitfield input. Allow ADMINISTRATOR revocation but reject every attempted grant.

Validate exactly one @everyone role, unique role IDs, arbitrary-width permission bitfields, modern color structure, managed-role provenance, bounded role inventory, exact connector membership, and the complete role-holder-count map. Require the target to be a configured standard unmanaged role strictly below the connector's highest role. Fail closed on unknown target fields, invalid modern colors, missing MANAGE_ROLES, unknown permission bits during a permission change, a complete desired known-permission set outside the connector's effective permission set when the permission bitfield would change, or a change that would remove the connector's own MANAGE_ROLES authority. Metadata-only changes may preserve existing permissions outside the connector's grantable set, but the plan must report that fact and must not include the permission field in the PATCH. Surface every logical-name collision as an explicit warning while retaining exact-ID targeting. Return only an aggregate affected-member count and never enumerate member identities for impact review.

Exclude the raw operation key from plan material, signed request state, activity, receipts, results, and errors while binding its domain-separated hash into the plan. Bind the verified identities, exact guild, connector membership and authority, full normalized role inventory, full holder-count map, current and desired target, requested and effective permission deltas, name collisions, impact, risks, and warnings. Reserve the hash durably before the write and permanently spend it after every outcome, including known failure, local record failure, or uncertainty.

Send one non-retried PATCH containing changed fields only and validate the complete returned role. Then fetch the exact role, complete role inventory, and role-holder counts again. Return completed-with-drift for safe observed divergence. Treat a transport error, Discord 5xx response, malformed response, or any failure after a response may have been applied as uncertain and potentially completed. Never retry, compensate, or roll back automatically.

Serialize the same exact guild and role across operation keys inside one process as defense in depth. The production facade also acquires durable exact role and guild roles-collection claims, so connector processes sharing the activity-state root exclude overlapping role configuration and retain the claims after uncertainty. Persist only exact guild and role IDs, requested field names, plan digest, operation-key hash, timestamps, fixed verification and outcome values, activity ID, and sanitized error category. Never persist role names, colors, permissions, member counts or identities, audit reasons, raw keys, or raw Discord responses.

Canonical source: SECURITY.md