# Access and Permissions Reference

The **Access** tab in the GravityOps Forum dashboard is where you define who can see and participate in your community. Permission management uses a two-step process: defining **Access Sets** (capabilities) and mapping **WordPress Roles** to those sets.

---

## 1. Access Sets

An **Access Set** is a pre-defined group of permissions (capabilities). Currently, the plugin provides three default sets (**Standard User**, **Moderator**, and **Read Only**) that cover the most common use cases. You can map multiple WordPress roles to these sets to control access.

### Forum Capabilities

Each Access Set can enable or disable the following core capabilities (displayed in the admin UI as human-readable labels):

-   **View**: The ability to see boards, forums, and read topics/replies.
-   **Post**: The ability to create new topics within a forum.
-   **Reply**: The ability to post a reply to an existing topic.
-   **Edit Own**: Allows a user to edit their own submitted content. This also grants authors the ability to **Lock**, **Unlock**, or **Delete** their own topics and replies.
-   **Moderate**: Grants full management access to a forum. Moderators can lock/unlock, sticky/unsticky, edit, and delete **any** topic or reply, regardless of who created it.

---

## 2. Role Mapping

You must map your **WordPress User Roles** to these access sets. This determines which permission group each user belongs to.

If a role is **not mapped** to any Access Set, users with that role will have no access to the forum functionality (they cannot view boards, forums, topics, or replies), unless they are WordPress Administrators.

-   **WordPress Role**: Select any existing role in your WordPress installation (e.g., Administrator, Editor, Subscriber).
-   **Anonymous (Visitor)**: A special role representing users who are not logged into your site.
-   **Access Set**: Select the set that defines the permissions for the chosen role.

### Important: Hierarchical Access

-   **Superset Logic**: Access is hierarchical based on the capabilities defined in each set. If a forum requires the **Read Only** set (which only has the `view` capability), any user whose mapped Access Set includes `view` (like **Standard User** or **Moderator**) is granted access.
-   **Highest Capability Wins**: Once granted entry, users exercise the full range of capabilities defined in **their own** mapped Access Set, regardless of the minimum set required by the forum.
-   **Strict Separation**: Conversely, a user mapped to the **Standard User** set will be blocked from a forum that requires the **Moderator** set because their set lacks the `moderate` capability required for entry.
-   **Multiple Role Mappings**: If a user has multiple WordPress roles, the plugin checks each role's mapped set and grants access if **any** role meets the forum's requirements.

---

## 3. Permission Inheritance and Fail-safes

GravityOps Forum follows a strict "fail-closed" model for security.

-   **Administrative Access**: Users with the `manage_options` capability (Administrators) have full access to all forum actions by default, bypassing specific Access Set rules.
-   **No Access Set**: If a forum does not have an Access Set assigned, it will not be accessible to anyone except Administrators.
-   **Sensitive Actions**: Actions like `moderate`, `post`, and `reply` require a forum context. If the plugin cannot determine which forum a user is in, these actions are blocked by default.
-   **Anonymous Users**: By default, anonymous users only have access if you explicitly map the "Anonymous (Visitor)" role to an Access Set that includes the `view` capability.

---

## 4. Guest Experience and Login Prompts

When a guest (anonymous user) attempts to perform an action they don't have permission for (like posting or replying), the forum provides a guided experience:

-   **Inline Prompts**: Instead of just hiding action buttons, the forum displays a message: **"Log in or create an account to start a topic/reply."**
-   **Account Block**: This prompt includes toggles to reveal the **Login** or **Registration** forms inline, allowing users to authenticate without leaving the page.
-   **Redirection**: If a guest accesses a restricted URL directly, they are prompted to log in, and upon success, they are automatically redirected back to their original destination.
-   **Permission Denied**: If a logged-in user attempts to access a page they don't have permission for, they are redirected to the Forum Index with a `gofrm_notice=permission_denied` parameter, which can be used to display a custom notice.

---

## 5. Developer Hooks for Access Control

Developers can use the following filters to customize the inherited access behavior for WordPress child pages:

-   `gofrm_inherit_access_enabled`: (bool) Master toggle for the inherited access feature. Defaults to `true`.
-   `gofrm_inherit_access_bypass_strict_mode`: (bool) Bypasses inheritance if "Strict Pretty URLs" is enabled. Defaults to `true`.
-   `gofrm_inherit_access_is_forum_ancestor`: (bool) Manually flag a page as a forum ancestor for inheritance.
-   `gofrm_inherit_access_use_first_match`: (bool) If `true`, stops at the closest ancestor. If `false` (default), checks all ancestors and uses the most restrictive access requirement.
-   `gofrm_inherit_access_login_url`: (string) Customize the redirect URL for guests. Defaults to the Forum Profile page.
-   `gofrm_inherit_access_denied_url`: (string) Customize the redirect URL for logged-in users with insufficient permissions. Defaults to the Forum Index.
-   `gofrm_enable_profile_editing`: (bool) Master toggle for the profile editing feature. Defaults to `true`.
