Let a plugin admin page declare a minimum role, so the sidebar hides it from roles that cannot open it

[marks-zyz]

Problem

A plugin admin page is visible in the sidebar for every signed-in role, but the route behind it is gated by role. When they disagree, the Editor clicks a menu item and gets a red "Plugin Error / Plugin responded with 403" page.

Where it is (0.37.0 and main):

• packages/core/src/plugins/types.ts:1266: PluginAdminPage is { path, label, icon? }. No role, no permission.
• packages/admin/src/components/Sidebar.tsx: every core item carries minRole (Comments and Menus are ROLE_EDITOR, Users and Plugins are ROLE_ADMIN) and the four groups go through filterNavItemsByRole(). The plugin loop pushes { to, label, icon } without minRole, so filterNavItemsByRole(pluginItems, userRole) is a no-op for plugin pages.
• packages/core/src/astro/routes/api/plugins/[pluginId]/[...path].ts:53: a route without permission requires plugins:manage, which is Admin.

So the default for a plugin author is: page shown to everyone, route closed to everyone below Admin. The Editor sees the item and cannot open it.

Two real cases on our sites:

1. A diagnostic page of our own e-mail plugin (checks credentials, sends a test message). Admin-only by design, and there is no way to keep it out of the Editor's menu.
2. The official forms plugin: every route defaults to plugins:manage, so the Editor sees "Forms" and "Submissions" and gets "Failed to load forms" / "No forms yet" (plugin-forms: all routes default to plugins:manage, so an Editor gets 403 and the admin shows "No forms yet" instead of a permission error #3033).

Current workarounds are all bad: drop admin.pages (page gone for the Admin too), open the route with permission: "plugins:read" (page works, but then it is open to a role it was not meant for), or hide the item with CSS from an integration (fragile, and the command palette still lists it).

Proposal

Let the page declare who should see it, and have the sidebar and command palette apply the same filter they already apply to core items:

export interface PluginAdminPage {
	path: string;
	label: string;
	icon?: string;
	/** Minimum role that sees this page in the nav. Default: every signed-in user (current behaviour). */
	minRole?: "contributor" | "author" | "editor" | "admin";
}

• Sidebar.tsx: map the string to the numeric role and set minRole on the plugin nav item; filterNavItemsByRole does the rest.
• Command palette: same filter.
• Sandboxed plugins: the same field in the manifest's admin.pages, passed through _buildManifest().
• The route guard stays as it is. minRole only decides visibility; the permission on the route keeps deciding access, so a hand-typed URL still gets the 403.

Backward compatible: without minRole nothing changes.

An alternative that needs no new field: derive visibility from the route. If a page in blocks mode calls a route whose effective permission the user does not hold, skip the item. It is cheaper for authors but couples the nav to route metadata, and a page can call more than one route, so the explicit field looks simpler to reason about.

Related: #866 and #1023 are about hiding core items; this one is the same gap on the plugin side.

[marks-zyz]

Follow-up with three things I did not have when I opened this: how often the same gap has been asked for, a workaround that actually covers the command palette, and the exact set of files a patch has to touch (it is larger than it looks).

This is a repeated request, not a one-off

Four open Ideas threads describe the same missing capability, the oldest from five months ago, none with a maintainer reply:

• Pluggable authorization layer — user RBAC is too coarse for multi-tenant/delegation scenarios #824 (2026-04-02) "Pluggable authorization layer". A comment from 2026-05-07 proposes literally "a per-page/per-route minRole on the manifest".
• Feature: hierarchical plugin admin navigation separate from admin.pages #1002 (2026-05-12) admin.nav with hidden.
• Bug Report + UX: Subscriber role has excessive admin access + login page needs overhaul #1132 (2026-05-21) a Subscriber seeing the full sidebar, asking for "role-gated admin UI".
• Feature Request: Declarative Admin Sidebar Navigation (Grouping & Role Guards) #2317 (2026-08-01) declarative admin.nav with grouping and Role Guards.

I searched all 443 discussions including the Roadmap category. The two Roadmap items about the sidebar (#1763, #1764) are about grouping and hiding collections by site config, not by the signed-in user's role.

Correction to my own workaround list

I wrote that hiding the item from an integration is fragile and leaves the command palette listing it. That is true for CSS, but there is a better workaround, and it works: filter the manifest on the server.

Both the sidebar and the command palette build plugin items from GET /_emdash/api/manifest. An Astro middleware registered before emdash() sees locals.user after await next(), so it can empty adminPages for a plugin when the session role is below a declared minimum. One interception, both surfaces, no DOM selector, no bundle anchor.

Measured on 0.37.0 by demoting the dev user in the local D1 and restoring it: role 40 receives adminPages: [] and 403 on the plugin route; role 50 receives the page and 200. The other plugin in the same site (@emdash-cms/plugin-forms) is untouched.

I mention it because it is evidence for the design, not against it: the manifest is already the single source both surfaces read, so minRole traveling in the manifest is all it takes. It also means sites are not blocked while this is decided, which I hope makes the change easier to weigh on its merits.

The patch is 8 files, and one of them is a trap

Reading main today:

1. packages/core/src/plugins/types.ts:1266, the field itself.
2. packages/core/src/plugins/manifest-schema.ts:215, adminPageSchema is a closed Zod object, so a sandboxed plugin declaring the field fails validation until it is added.
3. packages/core/src/emdash-runtime.ts:1963-1967, the trap: entry.adminPages?.map((p) => ({ path: p.path, label: p.label ?? p.path, icon: p.icon })) rebuilds the page field by field, so a new field is dropped silently on the sandboxed path. Tests that only cover native plugins would stay green.
4. packages/core/src/emdash-runtime.ts:260, the SandboxedPluginEntry type.
5. packages/core/src/api/types.ts:42.
6. packages/core/src/astro/types.ts, the copy of PluginAdminPage kept there to avoid circular deps.
7. packages/admin/src/lib/api/client.ts:186.
8. packages/admin/src/components/Sidebar.tsx:363 and packages/admin/src/components/AdminCommandPalette.tsx:259, the two pushes that just need minRole: page.minRole.

Happy to send the PR with tests, including one that demotes a user and asserts the sandboxed path keeps the field (point 3). Per CONTRIBUTING I am waiting for maintainer approval before opening it.