dashboard: User-aware dashboard navigation and route access

[kevmtt]

Summary

The React dashboard has no way to decide navigation or route access based on who is logged in. The only per-viewer condition anywhere in the nav pipeline is NavMenuItem.requiresPermission, and no route is guarded at all. This proposal adds a small user context shared by three new extension points: reactive nav modifiers, a per-item isVisible predicate, and route access rules. I would like to implement it.

Motivation

Two concrete cases.

1. Floor staff in a retail store use one custom POS page and nothing else. They need ReadCatalog and ReadOrder for the POS itself to work, so permissions cannot express "everything except POS is hidden and unreachable". Today the only options are to accept a sidebar full of entries they must not use, or to invent a parallel set of custom permissions purely to drive the UI.
2. Marketplace sellers, as raised in discussion plugin/config control over the base navigation menu #2189: "the visibility of the menu items on the left is controlled by roles, and so does not give me the control I desire". Discussion How can I remove items from the navigation menu in the admin UI? #2368 asks the same for removing built-in items. Both were answered for the Angular admin-ui. The React dashboard has no equivalent.

The common thread is that permissions answer "what may this user call on the API", which is not the same question as "what should this user see and be able to open". Today the second question can only be answered by the first.

Current behaviour in 3.7.2

Verified in the packages/dashboard source:

• src/lib/components/layout/nav-main.tsx is the only per-viewer filter. isItemAllowed checks requiresPermission via usePermissions(), sections whose items are all filtered out are dropped, and a top-level link is checked directly.
• src/lib/hooks/use-permissions.ts: a permission list is OR (permissions.some), evaluated against the currently selected channel.
• src/lib/framework/extension-api/define-dashboard-extension.ts: the function form of navSections runs once, at extension load, in phase 2, and its result is written into the global registry. It receives only NavMenuConfig. It is not React, it cannot see the user, and it does not re-run on channel switch.
• src/app/routes/_authenticated.tsx: beforeLoad checks isAuthenticated and nothing else. DashboardRouteDefinition has no field for access control, and src/lib/framework/page/use-extended-router.tsx skips any extension route whose path already exists, so a core route cannot be shadowed by a restricted one.
• src/lib/providers/auth.tsx: CurrentUserInformation selects activeAdministrator { id firstName lastName emailAddress } and me { channels { id token code permissions } }. Roles are not fetched, and unlike profile.tsx the query is not wrapped in addCustomFields(), so administrator custom fields are not available either.
• src/lib/components/shared/permission-guard.tsx exists but renders null, and is used for buttons and page blocks, never for routes. There is no "not authorized" screen in the package.

What is missing

1. The client has no notion of the current user beyond id, name, email and per-channel permissions.
2. Nav configuration is a static snapshot, so no rule about it can depend on the viewer.
3. Nothing guards routes, so any nav-level rule is cosmetic by construction.

Proposal

One user context object, three consumers. The three parts are separable and could land as three PRs.

1. A shared user context

Extend CurrentUserInformation with activeAdministrator { user { roles { id code description permissions } } } and wrap it in addCustomFields(), then expose:

/**
 * @description
 * Information about the current user, available to navigation and route
 * access rules.
 *
 * @since 3.8.0
 */
export interface DashboardUserContext {
    user: ActiveAdministrator | undefined;
    channels: CurrentUserChannel[];
    activeChannel: CurrentUserChannel | undefined;
    /** Permissions on the active channel. */
    permissions: string[];
    /** Same OR semantics as `requiresPermission`. */
    hasPermissions: (permissions: string[]) => boolean;
}

This part is useful on its own. Administrator custom fields and roles are a common thing to branch dashboard UI on, and today every plugin that needs them re-queries activeAdministrator itself.

2. Nav resolution becomes a pipeline

Keep the registry as the source config and resolve it at render time in a new useNavMenu() hook:

registry config (built-ins + extension registrations)
  -> reactive modifiers: (config, ctx) => config
  -> per-item predicates: requiresPermission AND isVisible(ctx)
  -> filters registered as hooks (for async or app state)
  -> prune empty sections, sort
  -> render

NavMain becomes a consumer of that hook, which also makes the filtering unit-testable without rendering a sidebar.

New extension surface:

defineDashboardExtension({
    navMenu: {
        // Runs on every render with the user context. Can add, remove,
        // reorder and rename anything, including built-ins.
        modifiers: [(config, ctx) => NavMenuConfig],
        // Escape hatch for state the context cannot carry, e.g. data you
        // fetch yourself. Each entry is a hook, called unconditionally in
        // registration order. Returning undefined abstains.
        filters: [() => (item, section) => boolean | undefined],
    },
});

and on the item itself, ANDed with requiresPermission so the two compose:

navMenuItem: {
    id: 'payouts',
    requiresPermission: ['ReadConsignorPayout'],
    isVisible: ctx => ctx.user?.user.roles.some(r => r.code === 'store-manager') ?? false,
}

The existing one-shot navSections function form stays exactly as it is. Reactive modifiers are a separate registration, so no existing extension changes behaviour.

Two small additions decide whether this is pleasant or miserable to use:

• Export the built-in nav ids as constants. They are already stable strings in framework/defaults.ts, but today an author has to read the source to learn them.
• Ship helpers for the common shapes, because otherwise everyone hand-rolls the nested map and filter and gets section pruning wrong: keepOnly(config, ids), removeItems(config, ids), updateItem(config, id, patch).

3. Route access

For extension routes, DashboardRouteDefinition gains the same two conditions:

routes: [{
    path: '/pos',
    component: PosPage,
    requiresPermission: ['ReadOrder'],
    canAccess: ctx => boolean,
}],

Built-in routes are file-based across the whole app/routes tree, so a per-file option is not realistic. Instead, a central registration matched by path, enforced in the _authenticated beforeLoad that already exists and already has context.auth in scope:

routeAccess: [
    { path: '/*', canAccess: ctx => !isFloorStaff(ctx) },
    { path: '/pos/*', canAccess: () => true },
],

Most specific match wins, and no match means allowed, so this is additive. A denied route renders a new NotAuthorizedPage rather than a blank screen, which the package currently has no equivalent of.

I considered deriving route access from the resolved nav ("if you cannot see it you cannot open it") and rejected it, because detail routes, deep links and modal routes have no nav entry and would break.

Worked example: floor staff

const isFloorStaff = (ctx: DashboardUserContext) =>
    ctx.user?.user.roles.some(r => r.code === 'floor-staff') ?? false;

export default defineDashboardExtension({
    routes: [{ path: '/pos', component: PosPage, navMenuItem: { sectionId: 'pos', id: 'pos' } }],
    navMenu: {
        modifiers: [(config, ctx) => (isFloorStaff(ctx) ? keepOnly(config, ['pos']) : config)],
    },
    routeAccess: [
        { path: '/*', canAccess: ctx => !isFloorStaff(ctx) },
        { path: '/pos/*', canAccess: () => true },
    ],
});

This is not an authorization boundary, and the docs should say so

Everything above is client-side. A user who can call orders on the Admin API can still call it with curl whatever the dashboard renders. The real boundary stays where it is: permissions, channel-scoped roles, and resolver-level guards. What this proposal fixes is that today there is no supported way to make the dashboard agree with a server-side rule, so plugin authors either ship a sidebar full of entries their users must not use, or invent custom permissions purely to drive the UI. I would add a note to this effect in the docs for both requiresPermission and the new API.

Backwards compatibility

Additive. No existing field changes meaning, the current one-shot navSections modifier keeps its exact semantics, and an absent canAccess or routeAccess entry means allowed. The one behavioural change is that nav resolution moves from load time to render time, so a modifier that previously ran once now runs on every sidebar render. That applies only to the new reactive lane.

Open questions

1. Roles are channel-scoped, so "has role X" is ambiguous for a user whose role applies to another channel. I would expose the raw roles and let the author decide, but a helper such as hasRoleOnActiveChannel may be worth adding.
2. Grouping. I have written navMenu: { modifiers, filters } above, but flat navMenuModifiers and navMenuFilters props would match the existing style of the extension API more closely.
3. The filters lane calls registered hooks in a loop. That is safe in practice, since AppSidebar renders behind extensionsLoaded and the registration count is fixed for the session, but it is the one part of this proposal that trades a sharp edge for reach. It could be dropped from a first version.
4. Should routeAccess also apply to the breadcrumbs and anywhere else that reads the same nav config?

Prior art

• Discussion plugin/config control over the base navigation menu #2189, plugin/config control over the base navigation menu
• Discussion How can I remove items from the navigation menu in the admin UI? #2368, removing items from the navigation menu

Implementation

I would like to implement this, against the minor branch, with @since 3.8.0 on the new public APIs, split into three PRs matching the three parts above and starting with the user context.