Skip to content

Platform Access Diagnostics — Administrator And Support Runbook

  • Status: SOURCE-RECONCILED REPOSITORY RUNBOOK / NOT CURRENT WIKI
  • Current source baseline: qa/master@3c084671c034f8f5136b02dce990ecff6c66d107
  • Source authority: Authorization source authority
  • Rebuild packet: Authorization rebuild packet
  • Audience: super-admin, tenant administrator, support operator, role/menu owner, module/config owner and application owner
  • Phase implementation: USER HOLD
  • Important: diagnose before changing roles, menus, modules or records.

1. Access Chain

Troubleshoot in this order.

1. Authentication
2. Actor / Subject / Tenant
3. Module / Capability / Config / Credential
4. Menu / Page
5. API Route
6. Semantic Action
7. Record Tenant / Relation
8. Record State
9. Provider / File / Device prerequisite

Do not skip directly to “give Administrator role.”

2. Information To Collect

  • environment and release SHA;
  • physical actor and effective subject;
  • tenant ID/name and impersonation mode;
  • role IDs and expected role name;
  • page slug/direct URL;
  • API method/route or legacy TYPE/ACTION;
  • action attempted;
  • record type/ID and parent relation, without unauthorized data;
  • module/capability/config availability;
  • current record state/version;
  • exact HTTP/status/error/reason;
  • request/correlation ID;
  • whether the UI showed or hid the action;
  • last known successful actor/tenant/action.

Do not include secret values, raw session cookies, unrestricted record dumps or foreign-tenant content.

3. Menu Missing

3.1 Diagnose

  1. Confirm the effective tenant and role.
  2. Check whether the menu row exists for the tenant.
  3. Check exact route/query variant and role list.
  4. Check whether virtual-menu logic is involved.
  5. Check module/page/config availability.
  6. Determine whether the page is intentionally direct-only.
  7. Compare another role only after the current role policy is understood.

3.2 Important boundary

Menu missing
!= Page forbidden
!= API forbidden

Do not test access only by typing a direct URL on Production without authorization.

4. Menu Visible But Page Denied

Possible causes:

  • menu route/query mismatch;
  • target role changed after menu was rendered;
  • page-local guard differs from menu;
  • module/config became unavailable;
  • impersonation target changed;
  • page registry is inactive/error;
  • cached UI is stale;
  • direct/print alias uses a different owner.

Reread:

current role
current menu route
page role decision
module page decision
exact page slug/query

Do not add the role to every menu as a workaround.

5. Page Opens But Data/API Fails

This is expected when page and API authorization are separate.

  1. Record the failed API method/route.
  2. Identify API v2 versus legacy endpoint.
  3. Check route metadata:
  4. strict tenant principal;
  5. module key;
  6. required menu routes;
  7. required role IDs.
  8. Check effective actor/subject/tenant.
  9. Check handler record predicates and current state.
  10. Check provider/config prerequisite if relevant.
  11. Confirm UI did not rely on page access as API authorization.

Do not broaden page or menu role merely to make one API pass.

6. UI Action Hidden But API Might Exist

  1. Identify the semantic action and API caller.
  2. Confirm whether UI visibility is role/module/config/state driven.
  3. Directly verify the API only in an approved test environment/account.
  4. Expected result for unauthorized actor is backend denial even if the button is hidden.
  5. If API allows the hidden action, classify as UI/backend parity gap.
Hidden button
!= secure endpoint

7. UI Action Visible But API Denied

Possible causes:

  • stale UI session/role;
  • action visibility lacks a record-state check;
  • API has stricter menu/role metadata;
  • record belongs to another tenant;
  • impersonation actor/subject mismatch;
  • module/config/provider changed after page load;
  • direct API uses strict context while page used legacy scalar context.

Recovery:

  • refresh authoritative identity and record state;
  • do not repeatedly press the action;
  • correct the visibility source or accepted policy, not the record data.

8. Module Or Feature Unavailable

Distinguish:

explicitly disabled
missing tenant-module row / compatibility allow
module source error / compatibility allow
page registry inactive
config prerequisite off/error
named capability disabled/unavailable
credential unavailable

Current admin/direct-access labels such as Available, Default Allow, Unknown Module and Disabled are diagnostics, not full action authorization.

Do not toggle a module during diagnosis without a named change authorization and rollback plan.

9. Record Not Found Or Forbidden

9.1 Safe diagnosis

  1. Confirm tenant context.
  2. Confirm record ID/type.
  3. Confirm parent/child relation through the owning repository/query.
  4. Confirm soft-delete/current state.
  5. Confirm actor/subject ownership if applicable.
  6. Avoid exposing whether a foreign record exists.

9.2 Do not

  • remove tenant predicate;
  • copy the record to another tenant;
  • change CLIENT_ID manually;
  • return full foreign record for debugging;
  • convert a state denial into record access;
  • use super-admin bypass without an explicit diagnostic/action policy.

10. Record State Denied

Examples:

  • already confirmed/completed;
  • downstream process exists;
  • allocation/lot balance locked;
  • Scale ticket has exit stage;
  • provider/file/email effect is unknown;
  • stale version.

The owning application/process decides state eligibility.

Access owner
-> may actor request command?

Process owner
-> may command transition this record now?

Do not add a role override to bypass a business-state invariant.

11. Super-Admin Diagnosis

11.1 No impersonation

Super-admin should normally use platform/admin surfaces. Tenant application access requires an explicit tenant context.

11.2 User impersonation

Check both:

  • physical actor privilege/restrictions;
  • effective target-user role/action/record policy.

Do not assume physical super-admin bypass should win for all business actions.

11.3 Tenant-only impersonation

Use as support context only. It does not prove target-role UI/API behavior.

11.4 Admin API override

Confirm:

  • route is allowlisted;
  • actor is physical super-admin;
  • target tenant is explicit;
  • authorization reference is present where strict adapter requires it;
  • no simultaneous impersonation conflict.

12. Direct Pages And Print Pages

Some current pages inherit access from an owner alias; others are unregistered/admin compatibility pages; some have their own role guard.

Before changing access:

  • identify exact page slug and file;
  • identify page-route map and menu owner;
  • identify module/config guard;
  • identify related API/data query;
  • identify whether output is browser-only or durable.

Do not assume every print page is public because it opens in a new tab.

13. API v2 Versus Legacy Endpoint

API v2

Inspect:

public
strictTenantPrincipal
moduleKey
requiredMenuRoutes
requiredRoleIds
handler record/state checks

Legacy TYPE/ACTION

Inspect:

authenticated endpoint
TYPE/ACTION module mapping
optional menu assertion
advancedOperations flag
handler-specific role/record/state logic

One path passing does not prove the other.

14. Common Failure Matrix

Symptom First reread Common owner Do not do first
menu missing role/menu/module/config menu/platform grant admin role globally
page denied page route/menu role/module page/access disable guard
page opens, API 403 API metadata + record predicate API/application broaden page role
hidden action API allows direct API negative action owner rely on hidden button
visible action API denies identity/state/freshness UI + API owner repeated submit
module unavailable explicit/missing/error/config platform config toggle without rollback
foreign record denied tenant/relation predicate repository owner expose record existence
state conflict current record/process state application/process role override
impersonated behavior unexpected actor/subject/tenant + action identity/access claim target-role acceptance
legacy endpoint differs from API v2 both route families P5/application patch only one path silently

15. No-Blind-Retry Rule

For an access or command response loss:

reread identity/context
-> reread access decision if available
-> reread authoritative record/result
-> classify denied / committed / not committed / unknown
-> retry only missing idempotent boundary

Do not repeatedly submit a mutation merely because the UI showed Access Denied, timeout or network error.

16. Escalation Packet

Include:

  • environment/release SHA;
  • physical actor/effective subject/tenant;
  • role IDs;
  • page/menu/API/action;
  • record type/ID and safe parent reference;
  • current record state/version;
  • module/capability/config status;
  • request/correlation ID;
  • exact response;
  • UI visible/hidden state;
  • direct/impersonated/admin override mode;
  • steps already attempted.

Exclude unauthorized record content and secrets.

17. Current Versus Target Warning

The following are target-only until implemented:

  • unified redacted access decision trace;
  • semantic action capability registry/definitions;
  • typed record access repository contract across all modules;
  • one shared PHP/Next.js access decision owner;
  • versioned role/action policy publication;
  • universal GetVisibleActions parity;
  • global fail-closed behavior.

Do not publish target controls as current procedures.

18. Future Verification Checklist

  • [ ] menu/page/query variant matrix;
  • [ ] API v2 and legacy endpoint matrix;
  • [ ] UI visible/hidden and direct API parity;
  • [ ] own/foreign/missing/wrong-relation records;
  • [ ] valid/invalid/stale states;
  • [ ] module enabled/disabled/missing/error;
  • [ ] config/credential unavailable;
  • [ ] direct super-admin, user impersonation, tenant-only mode;
  • [ ] Client 1 valid-action breadth;
  • [ ] Client 2 expected roles;
  • [ ] no information disclosure;
  • [ ] rollback;
  • [ ] current Wiki publication/readback.

This Runbook remains repository input until separately reviewed and published.

---

Source: docs/runbooks/PLATFORM_ACCESS_DIAGNOSTICS_ADMIN_SUPPORT_RUNBOOK.md — ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged.