# Developer notes (v1.7.2)

This document is intended for maintainers and contributors.

## Code structure

Core runtime classes:

- `includes/class-brenwp-csm.php` – core options, logging, cron retention.
- `includes/class-brenwp-csm-safe-mode.php` – per-user Safe Mode state + admin-post handlers.
- `includes/class-brenwp-csm-restrictions.php` – restriction coordinator (hooks + caching) using traits under `includes/restrictions/traits/`.

Admin UI:

- `includes/admin/class-brenwp-csm-admin.php` – thin coordinator class.
- `includes/admin/traits/trait-brenwp-csm-admin-settings-register.php` – settings registration + option sanitization + section callbacks.
- `includes/admin/traits/trait-brenwp-csm-admin-fields-general.php` – field renderers for General.
- `includes/admin/traits/trait-brenwp-csm-admin-fields-safe-mode.php` – field renderers for Safe Mode.
- `includes/admin/traits/trait-brenwp-csm-admin-fields-restrictions.php` – field renderers for Restrictions.
- `includes/admin/traits/trait-brenwp-csm-admin-actions.php` – admin-post handlers and action notices.
- `includes/admin/traits/trait-brenwp-csm-admin-ajax.php` – AJAX endpoints (user search).
- `includes/admin/traits/trait-brenwp-csm-admin-menu-assets.php` – menu registration + asset loading.
- `includes/admin/traits/trait-brenwp-csm-admin-ui-helpers.php` – shared UI helpers (switches, groups).
- `includes/admin/traits/trait-brenwp-csm-admin-render-dashboard.php` – dashboard rendering.
- `includes/admin/traits/trait-brenwp-csm-admin-render-page.php` – page layout and settings wrapper.
- `includes/admin/traits/trait-brenwp-csm-admin-render-tabs.php` – tab renderers (About, Logs, Privacy).


Restrictions internals (traits):

- `includes/restrictions/traits/trait-brenwp-csm-restrictions-core.php` – role checks + per-request caching.
- `includes/restrictions/traits/trait-brenwp-csm-restrictions-caps.php` – capability hardening (`user_has_cap`, app passwords, file mods).
- `includes/restrictions/traits/trait-brenwp-csm-restrictions-screens.php` – screen blocking + notices + custom screen matcher.
- `includes/restrictions/traits/trait-brenwp-csm-restrictions-ui.php` – menus/admin-bar/UI cleanup + media/profile hardening.

Notable in 1.7.2:

- Added an optional **Settings export download** toggle (General). When enabled, admins can download a JSON settings file via a nonce-protected `admin-post` endpoint.
- Added an optional, dismissible **2FA reminder notice** for restricted users (Restrictions). This is notice-only, with per-user dismissal stored in user meta.
- Hardened blocked-screen redirect behavior to prevent redirect loops when the configured destination is also restricted.
- Added inline Settings API validation notices when custom screen blocklists or redirect targets are pruned/cleared during sanitization.

The split uses PHP **traits** so the public method names stay the same (hooks remain stable), while keeping each file smaller and easier to review.

## Security conventions

- **State-changing actions** must be `POST`-only, with `check_admin_referer()` and a capability check.
- **Read-only parameters** (for navigation/screen detection) are sanitized but do not require nonce.
- **Sanitize early, escape late**: sanitize `$_GET/$_POST` immediately and escape on output (`esc_html`, `esc_attr`, `esc_url`).

## Activity log retention

Retention is bounded by:

- max entries (`general.log_max_entries`), and
- optional age-based pruning (`general.log_retention_days`) executed by the daily cron hook `brenwp_csm_prune_activity_log`.

## Multisite notes

- The plugin is site-admin scoped; it does not register menu pages in Network Admin.
- Non-super-admins cannot target super-admin accounts via admin tools.