Document undocumented features: impersonation, custom adapters, middleware/policy, CLI commands

Audit of src/ vs docs/ surfaced public-facing functionality the original prose never described:

- New authentication/impersonation.md — PrimaryKeySessionAuthenticator with the impersonate() flow, full config table, start/detect/stop pattern
- New guide/custom-adapters.md — interfaces, return shapes for both Allow and ACL adapters, registration via TinyAuth.allowAdapter / aclAdapter, skeleton DB-driven example
- New authorization/middleware.md — RequestAuthorizationMiddleware config table, RequestPolicy reference, both unauthorized handlers (ForbiddenRedirect, ForbiddenCakeRedirect) with full options
- New reference/cli.md — tiny_auth add and tiny_auth sync with all arguments, options, interactive mode, and a typical project workflow

Sidebar updated to surface the four new pages.

Author: dereuromark

docs/.vitepress/config.ts

@@ -10,6 +10,7 @@ function unifiedSidebar() {
         { text: '5-min Quick Start', link: '/guide/quick-start' },
         { text: 'Installation', link: '/guide/install' },
         { text: 'Configuration', link: '/guide/configuration' },
+        { text: 'Custom Adapters', link: '/guide/custom-adapters' },
         { text: 'Troubleshooting', link: '/guide/troubleshooting' },
         { text: 'Upgrade Guide', link: '/guide/upgrade' },
       ],
@@ -19,6 +20,7 @@ function unifiedSidebar() {
       collapsed: false,
       items: [
         { text: 'Setup & INI', link: '/authentication/' },
+        { text: 'Impersonation', link: '/authentication/impersonation' },
         { text: 'Custom Adapter', link: '/authentication/adapter' },
       ],
     },
@@ -27,6 +29,7 @@ function unifiedSidebar() {
       collapsed: false,
       items: [
         { text: 'Setup & INI', link: '/authorization/' },
+        { text: 'Middleware & Policy', link: '/authorization/middleware' },
         { text: 'Custom Adapter', link: '/authorization/adapter' },
         { text: 'Multi-Role', link: '/authorization/multi-role' },
       ],
@@ -39,6 +42,13 @@ function unifiedSidebar() {
         { text: 'AuthPanel (DebugKit)', link: '/auth-panel' },
       ],
     },
+    {
+      text: 'Reference',
+      collapsed: true,
+      items: [
+        { text: 'CLI Commands', link: '/reference/cli' },
+      ],
+    },
   ]
 }
 

docs/authentication/impersonation.md

@@ -0,0 +1,107 @@
+# Impersonation
+
+TinyAuth ships a `PrimaryKeySessionAuthenticator` that enables the classic "admin logs in as another user" pattern. The original (impersonator) identity is stored in a separate session key so you can return to it at any time.
+
+## Setup
+
+Replace the default Cake `SessionAuthenticator` with TinyAuth's variant in your `AuthenticationServiceProvider`:
+
+```php
+use TinyAuth\Authenticator\PrimaryKeySessionAuthenticator;
+
+$service->loadAuthenticator(PrimaryKeySessionAuthenticator::class, [
+    'sessionKey' => 'Auth',
+    'identifierKey' => 'key',          // identifier lookup key
+    'idField' => 'id',                  // user PK column
+    'impersonateSessionKey' => 'AuthImpersonator', // where the original user's id is stashed
+    'cache' => false,                   // optional in-process SessionCache
+]);
+```
+
+The authenticator only persists the user's primary key in the session — the rest of the identity is reloaded on each request via the configured identifier. That's what makes safe role/permission swaps possible.
+
+### Config keys
+
+| Key | Default | What it does |
+| --- | --- | --- |
+| `sessionKey` | from parent | Session key holding the active user's primary key. |
+| `identifierKey` | `key` | The identifier field used by the loaded `IdentifierInterface` to look up the user. |
+| `idField` | `id` | The column on the user record containing the primary key. |
+| `impersonateSessionKey` | (none — set this) | Session key that stores the ORIGINAL impersonator's id during an active impersonation. |
+| `cache` | `false` | If `true`, results are stored in `TinyAuth\Utility\SessionCache` to avoid re-loading the user every request. Cleared on logout. |
+
+## Start impersonating
+
+In your controller (typically an admin action), call `impersonate()`:
+
+```php
+use TinyAuth\Authenticator\PrimaryKeySessionAuthenticator;
+
+public function impersonate($targetUserId) {
+    $service = $this->Authentication->getAuthenticationService();
+    $authenticator = $service->authenticators()->get('PrimaryKeySession');
+
+    $impersonator = $this->Authentication->getIdentity()->getOriginalData();
+    $impersonated = $this->fetchTable('Users')->get($targetUserId);
+
+    $result = $authenticator->impersonate(
+        $this->getRequest(),
+        $this->getResponse(),
+        $impersonator,
+        $impersonated,
+    );
+
+    $this->setRequest($result['request']);
+
+    return $this->redirect(['controller' => 'Pages', 'action' => 'home']);
+}
+```
+
+After this, `$this->Authentication->getIdentity()` returns the **impersonated** user, and the original impersonator's id is in `$session->read('AuthImpersonator')`.
+
+## Detect an active impersonation
+
+```php
+$impersonatorId = $this->getRequest()->getSession()->read('AuthImpersonator');
+if ($impersonatorId) {
+    // Show "Stop impersonating" banner
+}
+```
+
+## Stop impersonating
+
+Reverse the swap by writing the impersonator's id back into the active session key and clearing the impersonate marker:
+
+```php
+public function stopImpersonating() {
+    $session = $this->getRequest()->getSession();
+    $impersonatorId = $session->read('AuthImpersonator');
+
+    if (!$impersonatorId) {
+        $this->Flash->error(__('Not currently impersonating.'));
+
+        return $this->redirect($this->referer());
+    }
+
+    $session->write('Auth', $impersonatorId);
+    $session->delete('AuthImpersonator');
+
+    return $this->redirect(['controller' => 'Pages', 'action' => 'home']);
+}
+```
+
+## Constraints
+
+- Calling `impersonate()` while already impersonating throws `Cake\Http\Exception\UnauthorizedException` — only one level deep.
+- `cache => true` is in-process only (`SessionCache` lives for the duration of the request). It's a micro-optimization, not a persistent cache.
+- The authenticator only stores the primary key, not the full user data. If your `IdentifierInterface` is slow, expect the cost on every request unless `cache` is enabled.
+
+## Authorization gate
+
+Don't forget to gate the `impersonate` and `stopImpersonating` actions in your `auth_acl.ini`:
+
+```ini
+[Admin/Users]
+impersonate = admin
+stopImpersonating = *
+```

docs/authorization/middleware.md

@@ -0,0 +1,108 @@
+# Middleware & Policy
+
+The component-based authorization documented in [Authorization Setup](/authorization/) covers most apps. For middleware-based authorization (or routes that bypass controllers entirely), TinyAuth ships its own middleware and policy.
+
+## RequestAuthorizationMiddleware
+
+A drop-in replacement for `Authorization\Middleware\RequestAuthorizationMiddleware` that applies the TinyAuth allow / ACL rules instead of policies. Works with any controller / route (no per-controller wiring needed).
+
+> **Order matters:** add this AFTER `AuthorizationMiddleware`, `AuthenticationMiddleware`, and `RoutingMiddleware`.
+
+### Wiring
+
+```php
+use TinyAuth\Middleware\RequestAuthorizationMiddleware;
+
+// in Application::middleware()
+$middlewareQueue
+    ->add(new \Authentication\Middleware\AuthenticationMiddleware($this))
+    ->add(new \Authorization\Middleware\AuthorizationMiddleware($this))
+    ->add(new RequestAuthorizationMiddleware([
+        'identityAttribute' => 'identity',
+        'method' => 'access',
+        'unauthorizedHandler' => 'TinyAuth.ForbiddenCakeRedirect',
+    ]));
+```
+
+### Config keys
+
+| Key | Default | What it does |
+| --- | --- | --- |
+| `identityAttribute` | inherits parent | Request attribute name that holds the authenticated identity. |
+| `method` | inherits parent | Policy method invoked to check access (defaults to the parent middleware's). |
+| `unauthorizedHandler` | inherits parent | Handler used when authorization fails. Use TinyAuth's two flavors below. |
+
+The middleware picks up TinyAuth's full Configure block (`Configure::read('TinyAuth')`) automatically — no need to repeat keys here.
+
+## RequestPolicy
+
+Used internally by `RequestAuthorizationMiddleware` to evaluate the allow / ACL rules against the current request. You generally don't instantiate it directly, but if you wire `Authorization\Middleware\RequestAuthorizationMiddleware` yourself (instead of TinyAuth's subclass), point its `RequestAuthorizationMiddleware` at TinyAuth's policy:
+
+```php
+use Authorization\Policy\MapResolver;
+use Cake\Http\ServerRequest;
+use TinyAuth\Policy\RequestPolicy;
+
+$resolver = new MapResolver();
+$resolver->map(ServerRequest::class, RequestPolicy::class);
+```
+
+`RequestPolicy::canAccess(?IdentityInterface $identity, ServerRequest $request): bool` returns `true` if the current user (or guest) may access the route.
+
+## Unauthorized handlers
+
+When authorization fails, the middleware throws `Authorization\Exception\ForbiddenException`. TinyAuth ships two handlers for converting that into a redirect.
+
+### `TinyAuth.ForbiddenRedirect`
+
+Redirects to a fixed URL string. Useful for landing on a generic "/" or a public error page.
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `exceptions` | `[ForbiddenException::class]` | Exception classes this handler responds to. |
+| `url` | `/` | Target URL (string). |
+| `queryParam` | `redirect` | Query parameter that captures the original URL (so you can come back after login). |
+| `statusCode` | `302` | Redirect status. |
+| `unauthorizedMessage` | localized "You are not authorized to access that location." | Flash message. Set to `false` to suppress. |
+
+```php
+'unauthorizedHandler' => [
+    'className' => 'TinyAuth.ForbiddenRedirect',
+    'url' => '/',
+    'queryParam' => 'redirect',
+    'unauthorizedMessage' => __('Please log in.'),
+],
+```
+
+### `TinyAuth.ForbiddenCakeRedirect`
+
+Redirects to a CakePHP URL array — typically the login action.
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `exceptions` | `[ForbiddenException::class]` | |
+| `url` | `['controller' => 'Users', 'action' => 'login']` | Cake URL array. |
+| `queryParam` | `redirect` | |
+| `statusCode` | `302` | |
+| `unauthorizedMessage` | same default | |
+
+```php
+'unauthorizedHandler' => [
+    'className' => 'TinyAuth.ForbiddenCakeRedirect',
+    'url' => ['plugin' => null, 'prefix' => false, 'controller' => 'Users', 'action' => 'login'],
+],
+```
+
+### Non-HTML requests
+
+Both handlers re-throw the original `ForbiddenException` if the request has a non-HTML extension (`_ext` other than `'html'`). API consumers get a proper 403 instead of a 302 to a login page.
+
+## When to use middleware vs component
+
+| Use the **component** | Use the **middleware** |
+| --- | --- |
+| Standard MVC apps where every request hits a controller | Routes that bypass controllers (custom routing, JSON-RPC, etc.) |
+| You want fine-grained per-controller config | You want a single global rule application |
+| Easier to debug (per-controller `beforeFilter`) | Cleaner stack — auth runs before routing dispatches |
+
+The two approaches are not mutually exclusive but typically you pick one. The component is the simpler choice; the middleware is the right choice when you need authorization to run regardless of the controller.

docs/guide/custom-adapters.md

@@ -0,0 +1,143 @@
+# Custom Adapters
+
+TinyAuth's two INI-based stores (`auth_allow.ini` for public actions, `auth_acl.ini` for role permissions) are just the default backends. You can swap either one out for a database-driven, API-driven, or any other source by implementing a small interface.
+
+## When you'd want a custom adapter
+
+- **Live editing** — admins editing rules from a UI rather than redeploying a file. The [TinyAuthBackend plugin](https://github.com/dereuromark/cakephp-tinyauth-backend) already provides this.
+- **Multi-tenant rules** — different rule sets per host / customer / region.
+- **Remote source** — central auth service, central feature flags, etc.
+
+If your rules are stable and per-environment, the INI files are usually fine. Don't overbuild this.
+
+## Authentication: the AllowAdapterInterface
+
+```php
+namespace TinyAuth\Auth\AllowAdapter;
+
+interface AllowAdapterInterface {
+    public function getAllow(array $config): array;
+}
+```
+
+`getAllow()` returns the **public-action whitelist**, keyed by section. The reference implementation is [`IniAllowAdapter`](https://github.com/dereuromark/cakephp-tinyauth/blob/master/src/Auth/AllowAdapter/IniAllowAdapter.php).
+
+Each entry should look like:
+
+```php
+[
+    'Articles' => [
+        'controller' => 'Articles',
+        'plugin' => null,
+        'prefix' => null,
+        'allow' => ['index', 'view'],
+        'deny' => [],
+    ],
+    'Admin/Users' => [
+        'controller' => 'Users',
+        'plugin' => null,
+        'prefix' => 'Admin',
+        'allow' => ['login'],
+        'deny' => [],
+    ],
+];
+```
+
+`controller`, `plugin`, `prefix` come from parsing the section key (e.g. `MyPlugin.Admin/Articles` → `plugin='MyPlugin'`, `prefix='Admin'`, `controller='Articles'`). The `Utility::deconstructIniKey()` helper does this for you.
+
+`allow` is the list of public actions. `deny` is the list of explicitly-denied actions (using the `!action` syntax in INI).
+
+## Authorization: the AclAdapterInterface
+
+```php
+namespace TinyAuth\Auth\AclAdapter;
+
+interface AclAdapterInterface {
+    public function getAcl(array $availableRoles, array $config): array;
+}
+```
+
+`getAcl()` returns the **role-permission map**, keyed by section. The reference implementation is [`IniAclAdapter`](https://github.com/dereuromark/cakephp-tinyauth/blob/master/src/Auth/AclAdapter/IniAclAdapter.php).
+
+`$availableRoles` is `['admin' => 1, 'user' => 2, ...]` so you can look up role IDs by name.
+
+Each entry should look like:
+
+```php
+[
+    'Articles' => [
+        'controller' => 'Articles',
+        'plugin' => null,
+        'prefix' => null,
+        'allow' => [
+            'index'  => ['admin' => 1, 'user' => 2],
+            'edit'   => ['admin' => 1],
+        ],
+        'deny' => [
+            'delete' => ['user' => 2],
+        ],
+    ],
+];
+```
+
+`allow` is `[action => [roleName => roleId, ...]]` — a single action can have multiple roles. `deny` follows the same shape and is checked first; an action denied for a role overrides any allow.
+
+## Registering your adapter
+
+Set the relevant config key in `app.php`:
+
+```php
+'TinyAuth' => [
+    // For authentication (allow whitelist):
+    'allowAdapter' => \App\Auth\DatabaseAllowAdapter::class,
+
+    // For authorization (ACL):
+    'aclAdapter' => \App\Auth\DatabaseAclAdapter::class,
+],
+```
+
+That's it — TinyAuth instantiates the adapter and calls `getAllow()` / `getAcl()` once per request (cached, see [Configuration](/guide/configuration#cache-busting)).
+
+## Skeleton example
+
+```php
+namespace App\Auth;
+
+use TinyAuth\Auth\AclAdapter\AclAdapterInterface;
+
+class DatabaseAclAdapter implements AclAdapterInterface {
+
+    public function getAcl(array $availableRoles, array $config): array {
+        $acl = [];
+
+        $rows = $this->fetchTable('AuthRules')->find()->toArray();
+
+        foreach ($rows as $row) {
+            $key = $row->section; // e.g. "Admin/Articles"
+            if (!isset($acl[$key])) {
+                $acl[$key] = $this->_parseSectionKey($key);
+                $acl[$key]['allow'] = [];
+                $acl[$key]['deny'] = [];
+            }
+
+            $bucket = $row->is_deny ? 'deny' : 'allow';
+            $roleId = $availableRoles[$row->role] ?? null;
+            if ($roleId === null) {
+                continue;
+            }
+            $acl[$key][$bucket][$row->action][$row->role] = $roleId;
+        }
+
+        return $acl;
+    }
+
+    protected function _parseSectionKey(string $key): array {
+        return \TinyAuth\Utility\Utility::deconstructIniKey($key);
+    }
+}
+```
+
+## See also
+
+- [TinyAuthBackend](https://github.com/dereuromark/cakephp-tinyauth-backend) — a ready-made admin GUI for editing both stores.
+- [Configuration: Custom adapters](/guide/configuration#custom-adapters) — the config key reference.