How to wire a new module, page, or endpoint into the module-access enforcement built in Module Access Control Phase 3, so it respects who's allowed where for free. If you skip this, your new code is an open door — a restricted analyst can reach it by typing the URL.

This is the module-access twin of the "Adding a new System feature" checklist on Admin Access Control; the two guards behave the same way and follow the same discipline.

The one rule to remember: every page and every endpoint gets a guard - reads included. A read used by several modules gets requireAnyModuleAccessJson([...]) naming all of them; only an endpoint that genuinely has no module (sign-in, your own account, a token feed, the bell on every page) stays open, and it goes on the allow-list in tests/module-access-coverage.php with the reason. That test fails on anything else.

⚠️ Changed in 2.10.2. Until then the rule was "guard writes, leave reads open", and it left 188 reads - ticket threads, contracts, asset lists, software API keys, decrypted settings - readable by any signed-in analyst whose team was never given the module. See Restricted analysts could read other modules' data.

Both live in includes/functions.php, take only the module key, open their own DB connection, and fail closed. 'system' is not a module key here — it defers to is_admin (see Admin Access Control); any unknown key is denied.

Both need includes/functions.php loaded first, and must run before any output (pages) or any DB write (APIs).

session_start();
require_once '../config.php';
require_once '../includes/functions.php';   // <-- must be loaded
require_once '../includes/i18n.php';
// ... theme / timezone init ...

requireModuleAccess('assets');              // <-- before any HTML

$current_page = 'assets';
?>
<!DOCTYPE html> ...

session_start(['read_and_close' => true]);
require_once '../../config.php';
require_once '../../includes/functions.php'; // <-- must be loaded

if (!isset($_SESSION['analyst_id'])) { /* existing 401 auth check */ }
requireModuleAccessJson('assets');           // <-- right after auth, before writes

Note the include depth: pages are one level deep (../includes/…), API endpoints two (../../includes/…).

The canonical list of module keys is getModuleRegistry() in includes/functions.php. The guards, the summary screen, and the effective-access tool all iterate it. The key you pass to a guard must be one of these.

Several keys don't match their directory — pass the key, not the folder name:

A module isn't "known" to access control until its key is in the registry. Wire these, in this order:

1. Register the key — add it to the $keys array in getModuleRegistry() (includes/functions.php). This is what makes it appear on System → Modules, in the effective-access tool, and gate correctly.
2. Launcher entry — add a '<key>' => ['name' => t('common.modules.<key>.name'), 'path' => '<dir>/', 'icon' => '…'] row to $modules in includes/waffle-menu.php.
3. Landing-page card — in the root index.php, wrap your card in the standard visibility check so it auto-hides for denied analysts:

   <?php if ($allowed_modules === null || in_array('<key>', $allowed_modules)): ?> … card … <?php endif; ?>

4. Display name — add '<key>' => ['name' => '…', 'description' => '…'] under modules in every lang/<locale>/common.php (at least en).
5. Page gate — put requireModuleAccess('<key>') on every user-facing page in the module's directory (index + any sub-pages / help pages).
6. API gate — put requireModuleAccessJson('<key>') on every endpoint in api/<dir>/, reads included; a read other modules also call gets requireAnyModuleAccessJson([...]) (see below).

Steps 1–4 make the module visible and configurable; steps 5–6 make it enforced. Do all six — visibility without enforcement is the exact hole Phase 3 closed.

One line: requireModuleAccess('<moduleKey>'), after config.php + functions.php load and before any HTML. If the page didn't already require_once functions.php, add it. That's it — the rest is inherited.

Every endpoint gets a guard, right after its existing analyst_id auth check (add the functions.php require if missing). The only question is which modules, and the callers answer it:

Finding the callers: most front-end code calls an endpoint by its bare name (API_BASE + 'get_x.php'), so grep the file name, then check which API_BASE each hit uses - get.php, list.php and get_attachment.php exist in a dozen folders. For a shared assets/js/*.js file, find which pages load it. In the 2.10.2 audit the module had to be worked out from the callers for every one of 188 reads; guessing from the folder name would have broken the Teams screen (it calls api/tickets/).

Endpoints that are analyst-triggered UI actions but run through an engine/webhook/cron (e.g. the workflow "test fire") still get the guard as long as they carry their own analyst_id session check — they're reached from the UI, not by the headless worker (the worker calls the engine PHP directly, not the HTTP endpoint).

• functions.php must be loaded, or the guard is an undefined-function fatal. Most endpoints already require it; add it if not.
• Order matters — the page guard must run before any byte is sent (it uses header()), and the API guard before any write.
• Fail closed — both guards deny on any DB/exception. Don't wrap them in a try that swallows the exit.
• Restricted analysts don't auto-inherit new modules. A restricted analyst's access is a fixed list; when you ship a new module, all-access analysts get it immediately (their access is "all"), but restricted ones won't until an admin grants it on System → Modules. That's correct — new surface area shouldn't silently open to someone who was deliberately restricted.
• system means administrator — 'system' is not a module an analyst is given; passing it resolves to analystIsAdmin(). Use it inside requireAnyModuleAccessJson([...]) when the System screens share a read with a module, and for a System-only endpoint either it or includes/admin_api_guard.php - they are the same check. See Admin Access Control.
• Key, not directory — pass 'assets', not 'asset-management' (see the table above).

1. Lint everything you touched: php -l <file> — must be clean.
2. Coverage test — php tests/module-access-coverage.php fails on any endpoint with neither a guard nor a listed reason. Then confirm the module's pages carry one too:

   grep -rl "requireModuleAccess" <dir>/ api/<dir>/
   

3. Live test with the effective-access tool — on System → Modules, use the Access level panel to restrict a test analyst, then the effective-access checker to confirm your module shows ❌, and try to open its page/POST its write endpoint as that analyst — you should be bounced (302) / 403. Then grant it and confirm access returns. This tool doubles as the verification harness for the whole feature.

• Module Access Control — the model, resolver, most/least policy, and management screen this guide plugs into
• Admin Access Control — the is_admin System gate + the "guard the mutations, not the shared reads" discipline this mirrors
• Architecture