# Limited Admin Role — Documentation

Version 1.0.0 | Requires WordPress 6.0+ & WooCommerce (for product/order restrictions)

---

## Overview

This plugin adds a custom WordPress role called **Admin Panel Manager** that lets a user manage products, posts, pages, media, and SEO fields — but **cannot** view WooCommerce Orders, Customers, Users, or any analytics that expose customer data. A configurable session timeout (default: 12 hours) is also enforced for this role.

---

## Installation

1. Upload `limited-admin-role.zip` via **Plugins → Add New → Upload Plugin**.
2. Click **Activate Plugin**.
3. The role `Admin Panel Manager` is created automatically on activation.
4. Configure the plugin at **Settings → Limited Admin Role**.

---

## How to Create Users With This Role

### Method A — WordPress Admin UI
1. Go to **Users → Add New**.
2. Fill in username, email, and password.
3. In the **Role** dropdown, select **Admin Panel Manager**.
4. Click **Add New User**.

### Method B — WP-CLI
```bash
wp user create john john@example.com --role=admin_panel_manager --user_pass=StrongPassword123
```

### Method C — Programmatically
```php
wp_insert_user([
    'user_login' => 'john',
    'user_email' => 'john@example.com',
    'user_pass'  => 'StrongPassword123',
    'role'       => 'admin_panel_manager',
]);
```

---

## What the Role Can and Cannot Do

### ✅ Allowed

| Area | Details |
|------|---------|
| **Posts & Pages** | Create, edit, and publish posts and pages; cannot delete |
| **Media** | Upload and manage media files |
| **Menus & Widgets** | Edit navigation menus and widget areas |
| **WooCommerce Products** | Create/edit simple and variable products; manage categories, tags, attributes, pricing, inventory, shipping classes |
| **WooCommerce Coupons** | Create and edit coupons |
| **SEO Fields** | Edit SEO title, meta description, and schema for all post types (works with Rank Math and Yoast SEO out of the box — both plugins detect `edit_posts` / `manage_woocommerce` capabilities) |
| **Own Profile** | Can edit their own user profile (`profile.php`) |

### ❌ Blocked

| Area | Details |
|------|---------|
| **WooCommerce Orders** | No Orders menu item; direct URL access returns 403; REST API `/wc/v3/orders` returns 403 |
| **WooCommerce Customers** | No Customers menu; direct URL blocked; REST API `/wc/v3/customers` blocked |
| **Users Management** | No Users menu; `users.php`, `user-new.php`, `user-edit.php` blocked; REST `wp/v2/users` write endpoints blocked |
| **WooCommerce Reports / Analytics** | All WC Reports and Analytics pages hidden and blocked |
| **Delete Posts/Pages/Products** | Delete capability not granted |
| **Promote / Create Users** | Cannot grant roles or create new user accounts |

---

## How Session Logout Works

1. **On login**: The plugin records a Unix timestamp in user-meta (`lar_login_time`).
2. **On every admin page load**: The elapsed time is compared to the configured session limit (default 12 hours). If exceeded, all sessions for that user are destroyed and they are redirected to the login page.
3. **Auth-cookie clamping**: The `auth_cookie_expiration` filter caps the cookie lifetime to the configured hours — so checking "Remember Me" still results in a maximum 12-hour session.
4. **REST API validation**: The `auth_cookie_valid` filter is also hooked so REST API requests are rejected once the session expires.
5. **Login message**: After expiry, the login page displays: *"Session expired. Please log in again."*

### Changing the Timeout
Go to **Settings → Limited Admin Role** and change **Session Timeout (hours)**. The new value takes effect immediately for future logins; existing sessions will expire at the old limit or when the user next hits the admin (whichever comes first).

---

## Settings Reference

| Setting | Default | Description |
|---------|---------|-------------|
| Session Timeout (hours) | 12 | Hours until forced logout. Range: 1–720. |
| Block Orders | ✅ On | Hide/block WooCommerce Orders everywhere. |
| Block Customers | ✅ On | Hide/block WooCommerce Customers everywhere. |
| Block User Management | ✅ On | Hide Users menu and block user management pages. |
| Block Reports / Analytics | ✅ On | Hide WooCommerce Reports and Analytics pages. |
| Active SEO Plugin | Auto | Informational; role access to SEO meta boxes is automatic. |

---

## SEO Plugin Compatibility

Both **Rank Math** and **Yoast SEO** show their meta boxes to any user who can `edit_posts` (for posts/pages) or who has WooCommerce product edit rights. Because `Admin Panel Manager` holds those capabilities, SEO fields appear and save normally without any extra configuration.

---

## Caching / CDN Compatibility (Cloudflare etc.)

- Admin pages (`/wp-admin/*`) are never cached by Cloudflare or standard page-cache plugins — session expiry checks are always live.
- The plugin does not set custom headers or interfere with cache-control headers on the front end.
- REST API endpoints (`/wp-json/*`) are also excluded from typical Cloudflare caching rules; no conflict expected.

---

## Testing Checklist

### As a Full Administrator

- [ ] Role `Admin Panel Manager` appears in **Users → Add New → Role** dropdown.
- [ ] Plugin settings page visible at **Settings → Limited Admin Role**.
- [ ] Changing session hours and saving reflects correctly.
- [ ] All toggles (block_orders, etc.) save and persist.

### As an Admin Panel Manager User

**Access / Products / Content**
- [ ] Can log in to wp-admin.
- [ ] Can create and publish a new Post.
- [ ] Can create and publish a new Page.
- [ ] Can upload an image via Media Library.
- [ ] Can create a new WooCommerce product (simple).
- [ ] Can create a new WooCommerce product (variable with attributes).
- [ ] Can set product price, inventory, and shipping class.
- [ ] Can create/edit a product category and tag.
- [ ] Rank Math or Yoast SEO meta box appears on post and product edit screens.
- [ ] SEO title and description save correctly.

**Blocked Areas — UI**
- [ ] WooCommerce → Orders does NOT appear in the sidebar.
- [ ] WooCommerce → Customers does NOT appear in the sidebar.
- [ ] WooCommerce → Reports / Analytics does NOT appear.
- [ ] Users menu does NOT appear.

**Blocked Areas — Direct URL**
- [ ] Visiting `/wp-admin/edit.php?post_type=shop_order` shows "Sorry, you are not allowed to access this page."
- [ ] Visiting `/wp-admin/admin.php?page=wc-orders` shows the same denial.
- [ ] Visiting `/wp-admin/users.php` shows the same denial.
- [ ] Visiting `/wp-admin/user-new.php` shows the same denial.
- [ ] Visiting `/wp-admin/admin.php?page=wc-reports` shows the same denial.
- [ ] Visiting `/wp-admin/admin.php?page=wc-admin&path=/analytics/overview` shows the same denial.

**Blocked Areas — REST API**
- [ ] `GET /wp-json/wc/v3/orders` returns HTTP 403.
- [ ] `GET /wp-json/wc/v3/customers` returns HTTP 403.
- [ ] `GET /wp-json/wp/v2/users` returns HTTP 403 (or 401 if not authenticated).

**Session Expiry**
- [ ] After the configured timeout (reduce to 1 hour for testing), the user is redirected to the login page.
- [ ] Login page shows "Session expired. Please log in again."
- [ ] Checking "Remember Me" at login does NOT extend the session beyond the configured hours.
- [ ] After expiry, refreshing a cached admin page still triggers redirect (session token is destroyed server-side).

---

## Uninstalling

1. Deactivate the plugin.
2. Click **Delete** in the Plugins list.
3. The plugin will automatically:
   - Remove the `admin_panel_manager` role from WordPress.
   - Delete plugin settings (`lar_settings` option).
   - Clean up `lar_login_time` user-meta for all users.

> **Note:** Users previously assigned this role will fall back to having no role (they will not be deleted).

---

## Changelog

### 1.0.0
- Initial release.
- Custom `admin_panel_manager` role with product/content capabilities.
- WooCommerce Orders, Customers, Users, Reports blocked (menu + URL + REST API).
- 12-hour session timeout with configurable settings page.
- Compatible with Rank Math, Yoast SEO, WooCommerce HPOS (High-Performance Order Storage).