| name | add-permission |
| description | Add a new permission end-to-end — server constant + endpoint gate, and (admin app) mirror it into the permissions catalog + route guard. Use when a new endpoint needs authorization. See modules/identity.md + frontend/admin.md. |
| argument-hint | [ModuleName] [Resource] [Action] |
Add Permission
A permission spans server + the admin app. The dashboard app does not mirror permissions — it reads
them from the JWT and relies on the server's 403.
Step 1 — Server constant (Modules.{X}.Contracts/Authorization/{X}Permissions.cs)
Add the constant to the resource group and ensure it's in the module's All collection. Convention:
Permissions.{Resource}.{Action}.
public static class {X}Permissions
{
public static class {Resources}
{
public const string View = "Permissions.{Resources}.View";
public const string Create = "Permissions.{Resources}.Create";
}
public static IReadOnlyList<FshPermission> All { get; } = [ ];
}
The module already calls PermissionConstants.Register({X}Permissions.All) in ConfigureServices, so a new entry in All is picked up automatically.
Step 2 — Gate the endpoint
.RequirePermission({X}Permissions.{Resources}.Create);
⚠️ RequiredPermissionAttribute implements IRequiredPermissionMetadata. Never let a second/duplicate of that interface exist — it silently disables all .RequirePermission() gates app-wide. (See .agents/rules/modules/identity.md.)
Step 3 — (admin only) mirror it
clients/admin/src/lib/permissions.ts — add the matching string to the frozen tree (no runtime catalog endpoint exists; mirror by hand):
export const {Module}Permissions = Object.freeze({
{Resources}: { View: "Permissions.{Resources}.View", Create: "Permissions.{Resources}.Create" },
} as const);
If it should appear in the Role editor UI, add a PERMISSION_CATALOG entry ({ name, description, root?, basic? } under the right category group).
Step 4 — (admin only) gate the route
{ path: "{resources}/new",
element: <RouteGuard perms={[{Module}Permissions.{Resources}.Create]}><Create{Resource}Page /></RouteGuard> },
Step 5 — (admin only) seed it in tests
So RouteGuard passes on first paint, add the new permission to the test seed set (ADMIN_PERMS in clients/admin/tests/helpers/shell-mocks.ts, used by seedAuthedSession).
Dashboard
No mirror, no RouteGuard. The JWT carries only role names — the app fetches the permission list from GET /api/v1/identity/permissions at hydration and the server enforces access; a missing permission yields a 403 the UI surfaces. Routes aren't permission-gated; to hide a nav entry, set perm/anyPerm on the item in src/components/layout/nav-data.ts. Permission-gated specs mock GET /identity/permissions with the grants they need (shell mocks stub it to []).
Checklist
