> ## Documentation Index
> Fetch the complete documentation index at: https://docs.razebot.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Guardian

> Per-actor 2FA confirmation layer that intercepts dangerous permission changes before they land.

# Guardian

> Per-actor 2FA confirmation layer that intercepts dangerous permission changes before they land.

## Overview

Guardian sits on top of antinuke as a second line of defense. Where antinuke punishes a whitelisted admin who nukes, Guardian asks **"is that really you?"** before the change even takes effect.

When a whitelisted admin's account is hijacked — stolen token, cookie theft, compromised session — the attacker inherits full trust and can bypass antinuke entirely. Guardian closes that gap by requiring the real admin's personal credential (a password in their head or a TOTP code from their authenticator) before any dangerous role or permission change is re-applied.

***

## How it works

When an admin or attacker grants a dangerous permission to a role or member:

<Accordion title="Intercept flow" icon="diagram-project">
  ```mermaid theme={null} theme={null}
  flowchart TD
      A[Role or member update fires] --> B{Guardian enabled?}
      B -- No --> C[Existing antinuke handles]
      B -- Yes --> D{Dangerous permission?}
      D -- No --> C
      D -- Yes --> E[Resolve actor via audit log]
      E --> F{Actor is a trusted bot?}
      F -- Yes --> G[Allow — no challenge opened]
      F -- No --> H{Challenge cap reached?}
      H -- Yes --> I[Revert silently — no DM]
      H -- No --> J[Revert the change]
      J --> K[Insert challenge into DB]
      K --> L[DM the actor — confirm within 60s]
      L --> M{Actor responds?}
      M -- Timeout --> N[Change stays reverted]
      M -- Wrong credential × 3 --> N
      M -- Correct credential --> O[Re-apply the change]
  ```
</Accordion>

### What counts as dangerous

| Trigger                     | When it fires                                                                                                                       |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `role_admin_grant`          | A role gains the `administrator` permission                                                                                         |
| `role_dangerous_perm_grant` | A role gains any of: ban, kick, manage server, manage roles, manage channels, manage webhooks, manage expressions, manage nicknames |
| `member_admin_role_grant`   | A member is granted any role that already has `administrator`                                                                       |
| `locked_role_grant`         | A member is granted a role you've pinned to the locked-role list, regardless of its permissions                                     |

### Credential ladder

When resolving a challenge, the input is checked in this order:

| Type                  | Format      | Notes                                  |
| --------------------- | ----------- | -------------------------------------- |
| TOTP                  | 6 digits    | ±1 step window (90s) for clock drift   |
| Recovery code         | 8 hex chars | Single-use, consumed on match          |
| User password         | Any         | argon2id verified                      |
| Guild master password | Any         | Always works as fallback for any actor |

Three wrong attempts on the same challenge locks it permanently — the change stays reverted.

***

## Setup

<Steps>
  <Step title="Server owner: set master password">
    ```bash theme={null} theme={null}
    ;guardian master set (strong-password)
    ```

    The command auto-deletes after running. Confirm with `;guardian master status`.
  </Step>

  <Step title="Each admin: enroll in DM">
    ```bash theme={null} theme={null}
    ;guardian enroll password (guild-id) (personal-password)
    ```

    Or use TOTP (see Enrollment section below). Run these in **DM with the bot** — they auto-delete.
  </Step>
</Steps>

<Note>
  Optionally lock high-value roles so any grant triggers a challenge regardless of permissions: `;guardian lock @AdminRole (master-pw)`

  Trust legitimate bots (reaction role bots, etc.) to skip challenges: `;guardian trust add @Bot (master-pw)`
</Note>

***

## Master password commands

Server owner only. All credential commands auto-delete after running.

<AccordionGroup>
  <Accordion title="Set master password">
    <Tabs>
      <Tab title="Syntax">
        ```bash theme={null} theme={null}
        ;guardian master set (password)
        ```

        First-time setup. Server owner only.
      </Tab>

      <Tab title="Example">
        ```bash theme={null} theme={null}
        ;guardian master set MyStr0ngP@ss
        ```

        First-time setup. Server owner only.
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Rotate master password">
    <Tabs>
      <Tab title="Syntax">
        ```bash theme={null} theme={null}
        ;guardian master change (old) (new)
        ```

        Rotate the master password without disabling Guardian.
      </Tab>

      <Tab title="Example">
        ```bash theme={null} theme={null}
        ;guardian master change OldPass NewStr0ngPass
        ```

        Rotate the master password without disabling Guardian.
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Enable / Disable">
    <Tabs>
      <Tab title="Syntax">
        ```bash theme={null} theme={null}
        ;guardian master enable (password)
        ;guardian master disable (password)
        ```

        Re-enable or pause Guardian. Disable requires master password confirmation.
      </Tab>

      <Tab title="Example">
        ```bash theme={null} theme={null}
        ;guardian master enable MyPass
        ;guardian master disable MyPass
        ```

        Re-enable or pause Guardian. Disable requires master password confirmation.
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Status">
    <Tabs>
      <Tab title="Syntax">
        ```bash theme={null} theme={null}
        ;guardian master status
        ```

        Show current config, active triggers, challenge window, enrollment counts, pending approvals, and enrollment policy.
      </Tab>

      <Tab title="Example">
        ```bash theme={null} theme={null}
        ;guardian master status
        ```

        Show current config, active triggers, challenge window, enrollment counts, pending approvals, and enrollment policy.
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Require enrollment approval">
    <Tabs>
      <Tab title="Syntax">
        ```bash theme={null} theme={null}
        ;guardian master require-approval (on|off) (master-password)
        ```

        Toggle whether new enrollments need owner approval before they can confirm a challenge. When `on`, anyone who enrolls is in a **pending** state until the owner approves them. The server owner is always auto-approved. Aliases: `approval`, `require_approval`.
      </Tab>

      <Tab title="Example">
        ```bash theme={null} theme={null}
        ;guardian master require-approval on MyMasterPass
        ;guardian master require-approval off MyMasterPass
        ```

        Turn on enrollment approval gating. Enrolled users stay in pending until you run `;guardian admin approve`.
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Manage triggers">
    <Tabs>
      <Tab title="Syntax">
        ```bash theme={null} theme={null}
        ;guardian master triggers add (name) (password)
        ;guardian master triggers remove (name) (password)
        ;guardian master triggers list (password)
        ```

        Add or remove which event types open a challenge. Valid trigger names: `role_admin_grant`, `role_dangerous_perm_grant`, `member_admin_role_grant`, `locked_role_grant`.
      </Tab>

      <Tab title="Example">
        ```bash theme={null} theme={null}
        ;guardian master triggers add locked_role_grant MyPass
        ;guardian master triggers remove role_admin_grant MyPass
        ;guardian master triggers list MyPass
        ```

        Add or remove which event types open a challenge.
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

***

## Enrollment

Run all enrollment commands in **DM with the bot**. They auto-delete on success.

<Note>
  If the server has **require-approval** enabled, your enrollment lands in a **pending** state after you enroll. The server owner gets a DM and must run `;guardian admin approve @you (master)` before your credential can confirm any challenge. The server owner is always auto-approved. If approval is not required, enrollment is active immediately.
</Note>

<AccordionGroup>
  <Accordion title="Set personal password">
    <Tabs>
      <Tab title="Syntax">
        ```bash theme={null} theme={null}
        ;guardian enroll password (guild-id) (password)
        ```

        Set your personal password for a specific server. DM only.
      </Tab>

      <Tab title="Example">
        ```bash theme={null} theme={null}
        ;guardian enroll password 123456789012345678 MyPersonalPass
        ```

        Set your personal password for a specific server. DM only.
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Set up TOTP (authenticator app)">
    <Tabs>
      <Tab title="Syntax">
        ```bash theme={null} theme={null}
        ;guardian enroll totp (guild-id)
        ```

        Start TOTP enrollment. Bot DMs you a QR code — scan with Authy, Aegis, Google Authenticator, or 1Password.
      </Tab>

      <Tab title="Example">
        ```bash theme={null} theme={null}
        ;guardian enroll totp 123456789012345678
        ```

        Start TOTP enrollment. Bot DMs you a QR code to scan with your authenticator app.
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Verify TOTP">
    <Tabs>
      <Tab title="Syntax">
        ```bash theme={null} theme={null}
        ;guardian enroll totp verify (guild-id) (code)
        ```

        Confirm your TOTP enrollment with a live code. On success, bot shows 8 single-use recovery codes — **save them now**.
      </Tab>

      <Tab title="Example">
        ```bash theme={null} theme={null}
        ;guardian enroll totp verify 123456789012345678 482910
        ```

        Confirm your TOTP enrollment. Bot replies with 8 single-use recovery codes.
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Check enrollment status">
    <Tabs>
      <Tab title="Syntax">
        ```bash theme={null} theme={null}
        ;guardian enroll status (guild-id)
        ```

        See which credentials you have enrolled for a server.
      </Tab>

      <Tab title="Example">
        ```bash theme={null} theme={null}
        ;guardian enroll status 123456789012345678
        ```

        See which credentials you have enrolled for a server.
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Remove enrollment">
    <Tabs>
      <Tab title="Syntax">
        ```bash theme={null} theme={null}
        ;guardian unenroll (guild-id) (credential)
        ```

        Drop your own enrollment. `credential` is `password`, `totp`, or `all`. DM only.
      </Tab>

      <Tab title="Example">
        ```bash theme={null} theme={null}
        ;guardian unenroll 123456789012345678 totp
        ```

        Drop your TOTP enrollment. DM only.
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

***

## Role locking

Lock a role so that **any grant of it** triggers a challenge, regardless of the role's permissions.

<AccordionGroup>
  <Accordion title="Lock a role">
    <Tabs>
      <Tab title="Syntax">
        ```bash theme={null} theme={null}
        ;guardian lock @role (master-password)
        ```

        Add a role to the locked list. Requires master password.
      </Tab>

      <Tab title="Example">
        ```bash theme={null} theme={null}
        ;guardian lock @Admin MyMasterPass
        ```

        Add a role to the locked list. Requires master password.
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Unlock a role">
    <Tabs>
      <Tab title="Syntax">
        ```bash theme={null} theme={null}
        ;guardian unlock @role (master-password)
        ```

        Remove a role from the locked list.
      </Tab>

      <Tab title="Example">
        ```bash theme={null} theme={null}
        ;guardian unlock @Admin MyMasterPass
        ```

        Remove a role from the locked list.
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="List locked roles">
    <Tabs>
      <Tab title="Syntax">
        ```bash theme={null} theme={null}
        ;guardian locked
        ```

        List all currently locked roles. Paginated, 10 per page.
      </Tab>

      <Tab title="Example">
        ```bash theme={null} theme={null}
        ;guardian locked
        ```

        List all currently locked roles. Paginated, 10 per page.
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

***

## Trusted bots

Bots in the trust list skip all Guardian challenges — useful for reaction role bots, auto-role bots, or any bot that legitimately grants roles.

<AccordionGroup>
  <Accordion title="Trust a bot">
    <Tabs>
      <Tab title="Syntax">
        ```bash theme={null} theme={null}
        ;guardian trust add @bot (master-password)
        ```

        Add a bot to the trust list. Server owner only.
      </Tab>

      <Tab title="Example">
        ```bash theme={null} theme={null}
        ;guardian trust add @ReactionRoleBot MyMasterPass
        ```

        Add a bot to the trust list. Server owner only.
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Untrust a bot">
    <Tabs>
      <Tab title="Syntax">
        ```bash theme={null} theme={null}
        ;guardian trust remove @bot (master-password)
        ```

        Remove a bot from the trust list.
      </Tab>

      <Tab title="Example">
        ```bash theme={null} theme={null}
        ;guardian trust remove @ReactionRoleBot MyMasterPass
        ```

        Remove a bot from the trust list.
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="List trusted bots">
    <Tabs>
      <Tab title="Syntax">
        ```bash theme={null} theme={null}
        ;guardian trust list
        ```

        Show all trusted bots. Paginated, 10 per page.
      </Tab>

      <Tab title="Example">
        ```bash theme={null} theme={null}
        ;guardian trust list
        ```

        Show all trusted bots. Paginated, 10 per page.
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

***

## Admin commands

<AccordionGroup>
  <Accordion title="Approve a pending enrollment">
    <Tabs>
      <Tab title="Syntax">
        ```bash theme={null} theme={null}
        ;guardian admin approve @user (master-password)
        ```

        Approve a member's pending guardian enrollment. Owner only. Once approved, their credential is active and can confirm future challenges. The member gets a DM on approval.
      </Tab>

      <Tab title="Example">
        ```bash theme={null} theme={null}
        ;guardian admin approve @wanderer MyMasterPass
        ```

        Activate wanderer's pending enrollment.
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Reject a pending enrollment">
    <Tabs>
      <Tab title="Syntax">
        ```bash theme={null} theme={null}
        ;guardian admin reject @user (master-password)
        ```

        Reject and delete a member's pending enrollment. Owner only. The member gets a DM. They can re-enroll if it was a mistake. Only works on unapproved enrollments — use `;guardian admin unenroll` to revoke an already-approved one.
      </Tab>

      <Tab title="Example">
        ```bash theme={null} theme={null}
        ;guardian admin reject @wanderer MyMasterPass
        ```

        Drop wanderer's pending enrollment.
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="List pending enrollments">
    <Tabs>
      <Tab title="Syntax">
        ```bash theme={null} theme={null}
        ;guardian admin pending
        ```

        List all members with unapproved enrollments. Shows user and submission time. Paginated, 10 per page.
      </Tab>

      <Tab title="Example">
        ```bash theme={null} theme={null}
        ;guardian admin pending
        ```

        View the queue of members waiting for enrollment approval.
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Force-unenroll a user">
    <Tabs>
      <Tab title="Syntax">
        ```bash theme={null} theme={null}
        ;guardian admin unenroll @user (master-password)
        ```

        Clear all of a user's enrollments for this server. Owner only. Use when someone loses access to their TOTP and has no recovery codes.
      </Tab>

      <Tab title="Example">
        ```bash theme={null} theme={null}
        ;guardian admin unenroll @zecroyn MyMasterPass
        ```

        Clear a user's enrollments so they can re-enroll.
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Temporarily disable">
    <Tabs>
      <Tab title="Syntax">
        ```bash theme={null} theme={null}
        ;guardian admin temp-disable (minutes) (master-password)
        ```

        Pause Guardian challenges for 1–60 minutes. Useful during planned maintenance or bulk role changes.
      </Tab>

      <Tab title="Example">
        ```bash theme={null} theme={null}
        ;guardian admin temp-disable 15 MyMasterPass
        ```

        Pause challenges for 15 minutes.
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="View audit log">
    <Tabs>
      <Tab title="Syntax">
        ```bash theme={null} theme={null}
        ;guardian admin audit
        ```

        View the last 200 Guardian events for this server. Paginated, 10 per page.
      </Tab>

      <Tab title="Example">
        ```bash theme={null} theme={null}
        ;guardian admin audit
        ```

        View the last 200 Guardian events for this server.
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

***

## Confirming a challenge

When Guardian intercepts a dangerous action, you receive a DM with a challenge ID. Reply in **DM** to confirm:

<Tabs>
  <Tab title="Syntax">
    ```bash theme={null} theme={null}
    ;guardian confirm (id) (credential)
    ```

    Resolve a pending challenge. `credential` is your TOTP code, recovery code, personal password, or the server master password. DM only — auto-deletes on success.
  </Tab>

  <Tab title="Example">
    ```bash theme={null} theme={null}
    ;guardian confirm pq3xa9wr 482910
    ```

    Confirm with a TOTP code. Or pass your password / recovery code instead.
  </Tab>
</Tabs>

<Note>
  If you didn't initiate the action — just ignore the DM. The change stays reverted automatically after 60 seconds.
</Note>

<Warning>
  Your credential must have been enrolled **and approved** before the challenge was created. A credential enrolled or approved after the dangerous action fired cannot confirm it — the change stays reverted. This prevents an attacker from enrolling under a compromised account and immediately confirming their own action.
</Warning>

***

## Recovery

| Situation                           | Fix                                                                                       |
| ----------------------------------- | ----------------------------------------------------------------------------------------- |
| Lost TOTP device, no recovery codes | Ask server owner: `;guardian admin unenroll @you (master)`, then re-enroll                |
| Lost server master password         | Contact raze support — bot owner verifies ownership and resets                            |
| Lost `GUARDIAN_KEY`                 | Generate new key, restart bot, ask enrolled users to re-enroll TOTP. Passwords still work |