Built-in Roles & permissions admin screen (todo §5); /admin/roles list (search/sort/paginate) + create/delete + assign-to-users/groups + "effective access" (Keto expand → transitive members), writing only to Keto — gated admin-only + CSRF-guarded like Users/Groups (Kratos read only to label members). A role = Keto subject set Role:<name>#members; reuses the Groups membership helpers (now-exported pagedTuples/memberCandidates/safeDecode); added a Roles nav entry (i-shield) + a .plain-list CSS rule. Stability-reviewer run as a local PR: APPROVE, no Critical/High; addressed its explicit-expand-depth nit. Live boot-verify caught a real bug the tests missed — Keto v26.2.0 nests the expand subject under tuple (not node top-level as the §4 ExpandTree type guessed), so expandToEffectiveUsers returned []; fixed type+walker+fixtures, re-verified a group-only member surfaces in effective access. 237→243 units + typecheck green; expand chain boot-verified live then torn down.

AGENTS.md

@@ -56,3 +56,5 @@ docker compose -f compose.yml up --build -d              # production
   versions** — never ranges (`^`, `~`) and never digests/hashes. npm deps are kept
   exact by `.npmrc` (`save-exact=true`) + `npm ci`; the base image by tag (e.g.
   `node:24.16.0-alpine3.24`).
+- Run the stability reviewer agent after every implementation of something that can be like
+  a PR. That includes an implementation from the todo file that is pushed directly to master.

README.md

@@ -535,7 +535,8 @@ src/config.ts        Env loader — Ory endpoints, cookie/CSRF secrets, JWKS, po
 src/dashboard.ts     buildDashboardModel(): the home "/" People list view model (mock data, wires the §1 helpers)
 src/admin-users.ts   Built-in Users admin screen (§5): list Kratos identities (filter/sort/paginate) + create/edit/deactivate/delete/recovery; gated + CSRF-guarded
 src/admin-groups.ts  Built-in Groups admin screen (§5): list Keto subject sets + create/delete + membership (add/remove users & nested groups); writes only to Keto, gated + CSRF-guarded
-src/admin-nav.ts     adminNav(): the shared sidebar nav for the built-in admin screens (Dashboard · Users · Groups)
+src/admin-roles.ts   Built-in Roles admin screen (§5): list/create/delete Keto roles + assign to users/groups + "effective access" (Keto expand → transitive members); reuses the Groups membership helpers, writes only to Keto, gated + CSRF-guarded
+src/admin-nav.ts     adminNav(): the shared sidebar nav for the built-in admin screens (Dashboard · Users · Groups · Roles)
 src/shell-context.ts buildShellContext(): brand/theme/user view-model shared by the dashboard + admin screens (real signed-in user, no demo profile)
 src/icons.ts         Used-icon registry + sprite builder from lucide-static (regenerates partials/icons.ejs)
 src/list-query.ts    parseListQuery(): read a list URL → { q, filters, sort, page, pageSize }
@@ -546,7 +547,7 @@ src/discovery.ts     discoverPlugins(): scan plugins/, import + validate each pl
 src/router.ts        matchRoute()/allowedMethods()/isAuthorized(): map method+path → plugin route, params, permission gate (§2)
 src/view-resolver.ts renderPluginView(): render plugins/<id>/views/<view>.ejs; plugin views can include() core partials (§2)
 src/menu-config.ts   loadMenuConfig()/defineMenu(): read config/menu.ts (central override + branding), validated at boot (§2)
-views/               Core EJS templates (index = the app-shell People dashboard, admin/ = the Users list + create/edit form and the Groups list + create form + membership detail, auth = themed Kratos self-service page, 403/404/500, partials/ incl. app shell, nav tree, filter bar, data table, pagination, form field, auth card, alert, flow body, user-form/group-form/group-detail bodies, menu/popover, theme switch, icon sprite)
+views/               Core EJS templates (index = the app-shell People dashboard, admin/ = the Users list + create/edit form, the Groups list + create form + membership detail, and the Roles list + create form + assign/effective-access detail, auth = themed Kratos self-service page, 403/404/500, partials/ incl. app shell, nav tree, filter bar, data table, pagination, form field, auth card, alert, flow body, user-form/group-form/group-detail/role-form/role-detail bodies, menu/popover, theme switch, icon sprite)
 public/              Static assets under /public/ (css/styles.css + auth.css, favicon, robots.txt)
 config/menu.ts       Central menu override + branding (optional; defaults apply if absent)
 ory/                 Ory service config (kratos/: identity schema, kratos.yml, oidc/ SSO claims mapper, tokenizer/ session→JWT claims mapper + dev signing JWKS; keto/: keto.yml + namespaces.keto.ts OPL — role/group/resource; hydra/hydra.yml: OAuth2 issuer + login/consent URLs) + storage init (postgres/init/init.sql: one DB per service)

public/css/styles.css

@@ -677,6 +677,7 @@ th[aria-sort="descending"] .sort-ico { transform: rotate(180deg); }
 .inline-form { display: flex; flex-wrap: wrap; gap: 10px; align-items: center; }
 .admin-actions { flex-flow: row wrap; gap: 10px; align-items: center; }
 .admin-actions form { margin: 0; }
+.plain-list { display: flex; flex-direction: column; gap: 6px; }
 .btn-danger { color: var(--neg); border-color: var(--neg-bd); }
 .btn-danger:hover { background: var(--neg-bg); }
 .recovery-link { word-break: break-all; }

src/admin-groups.ts

@@ -291,8 +291,8 @@ export interface AdminGroupsDeps {
   render: (view: string, data: Record<string, unknown>) => Promise<string>;
 }
 
-// Drain every page of a relation-tuple query.
+// Drain every page of a relation-tuple query. (Reused by the Roles screen — same membership model.)
-async function pagedTuples(keto: KetoClient, query: RelationQuery): Promise<RelationTuple[]> {
+export async function pagedTuples(keto: KetoClient, query: RelationQuery): Promise<RelationTuple[]> {
   const out: RelationTuple[] = [];
   let pageToken: string | undefined;
   do {
@@ -305,7 +305,7 @@ async function pagedTuples(keto: KetoClient, query: RelationQuery): Promise<Rela
 
 // Build the member-picker options (every user by email + every existing group) and the id→email map
 // detail rows render with. One Kratos page + one Keto scan; ample for an admin tool.
-async function memberCandidates(keto: KetoClient, kratosAdmin: KratosAdmin): Promise<{ emailById: Map<string, string>; options: MemberOption[] }> {
+export async function memberCandidates(keto: KetoClient, kratosAdmin: KratosAdmin): Promise<{ emailById: Map<string, string>; options: MemberOption[] }> {
   const { identities } = await kratosAdmin.listIdentities({ pageSize: LIST_FETCH_SIZE });
   const emailById = new Map<string, string>();
   const userOptions: MemberOption[] = [];
@@ -326,7 +326,7 @@ async function groupExists(keto: KetoClient, name: string): Promise<boolean> {
 }
 
 // Decode a path segment without letting malformed %-encoding throw (→ caller treats it as not found).
-function safeDecode(seg: string): string | null {
+export function safeDecode(seg: string): string | null {
   try { return decodeURIComponent(seg); } catch { return null; }
 }
 

src/admin-nav.ts

@@ -9,8 +9,9 @@ import { composeNav, type NavNode } from "./nav.ts";
 export const ADMIN_PERMISSION = "admin"; // role token gating every admin screen
 export const ADMIN_USERS_BASE = "/admin/users";
 export const ADMIN_GROUPS_BASE = "/admin/groups";
+export const ADMIN_ROLES_BASE = "/admin/roles";
 
-type AdminScreen = "dashboard" | "groups" | "users";
+type AdminScreen = "dashboard" | "groups" | "roles" | "users";
 
 export function adminNav(roles: string[], menu: MenuConfig, current: AdminScreen): NavNode[] {
   const gated = (id: AdminScreen, href: string, icon: string, label: string): NavNode =>
@@ -19,5 +20,6 @@ export function adminNav(roles: string[], menu: MenuConfig, current: AdminScreen
     { href: "/", icon: "i-grid", id: "dashboard", label: "Dashboard" },
     gated("users", ADMIN_USERS_BASE, "i-users", "Users"),
     gated("groups", ADMIN_GROUPS_BASE, "i-layers", "Groups"),
+    gated("roles", ADMIN_ROLES_BASE, "i-shield", "Roles"),
   ]], menu.override, roles);
 }

src/admin-roles.test.ts

@@ -0,0 +1,106 @@
+// Built-in Roles & permissions admin screen (§5): the pure view-model + Keto builders. A role is a
+// Keto subject set (Role:<name>#members); members are users (subject_id) or groups (subject_set) —
+// "assign roles to users/groups". The "effective access" view flattens a Keto `expand` tree into the
+// distinct set of users who hold the role directly or transitively via a group. The HTTP
+// routing/gate/CSRF + live Keto/Kratos calls are exercised over HTTP in app.test.ts.
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { memberView } from "./admin-groups.ts";
+import {
+  buildRoleDetailModel,
+  buildRoleFormModel,
+  buildRolesListModel,
+  expandToEffectiveUsers,
+  isValidRoleName,
+  roleMemberTuple,
+} from "./admin-roles.ts";
+import type { ExpandTree, RelationTuple } from "./keto-client.ts";
+
+const uid = (n: number) => `01902d5e-7b6c-7e3a-9f21-3c8d1e0a4b${String(n).padStart(2, "0")}`;
+const userTuple = (role: string, n: number): RelationTuple =>
+  ({ namespace: "Role", object: role, relation: "members", subject_id: `user:${uid(n)}` });
+const groupTuple = (role: string, group: string): RelationTuple =>
+  ({ namespace: "Role", object: role, relation: "members", subject_set: { namespace: "Group", object: group, relation: "members" } });
+
+test("isValidRoleName + roleMemberTuple map the form value to a Role tuple over a user/group (else null)", () => {
+  for (const ok of ["admin", "editor", "team-a", "a1_b9"]) assert.equal(isValidRoleName(ok), true, ok);
+  for (const bad of ["", "Admin", "a b", "-bad", "a".repeat(65)]) assert.equal(isValidRoleName(bad), false, bad);
+
+  assert.deepEqual(roleMemberTuple("editor", `user:${uid(2)}`), { namespace: "Role", object: "editor", relation: "members", subject_id: `user:${uid(2)}` });
+  assert.deepEqual(roleMemberTuple("editor", "group:eng"), { namespace: "Role", object: "editor", relation: "members", subject_set: { namespace: "Group", object: "eng", relation: "members" } });
+  for (const bad of ["", "user:not-a-uuid", "group:Bad Name", "nope:x"]) assert.equal(roleMemberTuple("editor", bad), null, bad);
+});
+
+test("expandToEffectiveUsers flattens an expand tree → sorted distinct user ids, transitive through groups", () => {
+  // The subject rides on each node's `tuple` (Keto v26.2.0 shape, verified live).
+  const leaf = (n: number): ExpandTree => ({ tuple: { namespace: "", object: "", relation: "", subject_id: `user:${uid(n)}` }, type: "leaf" });
+  const tree: ExpandTree = {
+    children: [
+      leaf(1), // direct
+      {
+        children: [leaf(2), leaf(1)], // via group + dup
+        tuple: { namespace: "", object: "", relation: "", subject_set: { namespace: "Group", object: "eng", relation: "members" } }, // a member group, not a user
+        type: "union",
+      },
+    ],
+    tuple: { namespace: "", object: "", relation: "", subject_set: { namespace: "Role", object: "admin", relation: "members" } },
+    type: "union",
+  };
+  assert.deepEqual(expandToEffectiveUsers(tree), [uid(1), uid(2)]);
+  assert.deepEqual(expandToEffectiveUsers(null), []);
+  assert.deepEqual(expandToEffectiveUsers({ type: "leaf" }), []); // an empty role
+});
+
+test("buildRolesListModel filters by search, sorts, paginates; the name links to the detail page", () => {
+  const roles = Array.from({ length: 30 }, (_, i) => ({ memberCount: i + 1, name: `role-${String(i).padStart(2, "0")}` }));
+
+  const all = buildRolesListModel({ roles, url: "http://x/admin/roles" });
+  assert.equal(all.pagination.summary.total, 30);
+  assert.equal(all.table.rows.length, 25); // default page size
+  assert.equal(all.shell.title, "Roles");
+  const first = all.table.rows[0]!.cells[0] as { rowHeader: { href: string; text: string } };
+  assert.equal(first.rowHeader.text, "role-00");
+  assert.equal(first.rowHeader.href, "/admin/roles/role-00");
+
+  const one = buildRolesListModel({ roles, url: "http://x/admin/roles?q=role-07" });
+  assert.equal(one.pagination.summary.total, 1);
+  assert.deepEqual(one.filterBar.pills.map((p) => p.label), ["Search"]);
+
+  const desc = buildRolesListModel({ roles, url: "http://x/admin/roles?sort=-members" });
+  assert.equal((desc.table.rows[0]!.cells[0] as { rowHeader: { text: string } }).rowHeader.text, "role-29");
+});
+
+test("buildRoleFormModel: a create form with a required name field + member options (user or group)", () => {
+  const options = [{ label: "ada@example.com", value: `user:${uid(1)}` }, { label: "eng (group)", value: "group:eng" }];
+  const m = buildRoleFormModel({ csrfToken: "tok.sig", memberOptions: options });
+  assert.equal(m.shell.title, "New role");
+  assert.equal(m.form.action, "/admin/roles");
+  assert.equal(m.form.submitLabel, "Create role");
+  assert.equal(m.form.csrfToken, "tok.sig");
+  assert.equal(m.form.nameField.required, true);
+  assert.deepEqual(m.form.memberOptions, options);
+
+  const err = buildRoleFormModel({ error: "That name is taken.", memberOptions: options, values: { member: "group:eng", name: "Admin" } });
+  assert.equal(err.error, "That name is taken.");
+  assert.equal(err.form.nameField.value, "Admin");
+  assert.equal(err.form.selectedMember, "group:eng");
+});
+
+test("buildRoleDetailModel: members → rows, add-options exclude current members, effective access listed, actions wired", () => {
+  const members = [memberView(userTuple("admin", 1), new Map([[uid(1), "ada@example.com"]])), memberView(groupTuple("admin", "eng"), new Map())];
+  const candidates = [
+    { label: "ada@example.com", value: `user:${uid(1)}` }, // already a member → excluded
+    { label: "grace@example.com", value: `user:${uid(2)}` },
+    { label: "eng (group)", value: "group:eng" }, // already a member → excluded
+    { label: "ops (group)", value: "group:ops" },
+  ];
+  const effective = [{ label: "ada@example.com" }, { label: "grace@example.com" }]; // ada direct, grace via eng
+  const m = buildRoleDetailModel({ candidates, effective, members, role: { name: "admin" } });
+  assert.equal(m.shell.title, "admin");
+  assert.equal(m.members.rows.length, 2);
+  assert.equal(m.members.action, "/admin/roles/admin/members/delete");
+  assert.equal(m.add.action, "/admin/roles/admin/members");
+  assert.deepEqual(m.add.options.map((o) => o.value), [`user:${uid(2)}`, "group:ops"]);
+  assert.deepEqual(m.effective.map((e) => e.label), ["ada@example.com", "grace@example.com"]);
+  assert.equal(m.delete.action, "/admin/roles/admin/delete");
+});

src/admin-roles.ts

@@ -0,0 +1,375 @@
+// Built-in Roles & permissions admin screen (todo §5): list / create / delete Keto roles and assign
+// them to users and groups. A role is a Keto subject set `Role:<name>#members` (OPL: members are
+// users or groups, resolved transitively) — the source of truth for the JWT `roles` claim. It shares
+// the user|group membership model of the Groups screen, so the pure helpers (parseSubject, member
+// pickers, tuple paging) are reused from admin-groups. The one role-specific piece is the **effective
+// access** view: `keto.expand(Role:<name>#members)` returns the membership tree, which we flatten to
+// the distinct set of users who hold the role directly or transitively via a group. (The coarse JWT
+// projection reads only direct grants per the README's one-read-per-login design; this view is where
+// group→role inheritance is surfaced.) Writes go only to Keto; Kratos is read only to label members.
+// `handleAdminRoles` is the imperative shell app.ts dispatches to — gated admin-only, CSRF-guarded.
+
+import { ADMIN_PERMISSION, ADMIN_ROLES_BASE, adminNav } from "./admin-nav.ts";
+import {
+  type GroupView,
+  groupsFromTuples,
+  isValidGroupName,
+  memberCandidates,
+  type MemberOption,
+  type MemberView,
+  memberView,
+  pagedTuples,
+  parseSubject,
+  safeDecode,
+} from "./admin-groups.ts";
+import type { FieldConfig } from "./admin-users.ts";
+import { readFormBody } from "./body.ts";
+import type { RequestContext, User } from "./context.ts";
+import { CSRF_FIELD, verifyCsrfRequest } from "./csrf.ts";
+import { GuardError } from "./guards.ts";
+import type { ExpandTree, KetoClient, RelationTuple } from "./keto-client.ts";
+import type { KratosAdmin } from "./kratos-admin.ts";
+import { parseListQuery } from "./list-query.ts";
+import { DEFAULT_MENU, type MenuConfig } from "./menu-config.ts";
+import { paginate } from "./paginate.ts";
+import type { RouteResult } from "./plugin.ts";
+import { buildShellContext } from "./shell-context.ts";
+
+const ROLE_NS = "Role";
+const MEMBERS = "members";
+const DEFAULT_PAGE_SIZE = 25;
+const PAGE_SIZES = [25, 50, 100];
+// Expand far past any sane group-nesting depth so the effective-access view never silently
+// under-reports the deepest members (Keto's own default is shallow).
+const EXPAND_MAX_DEPTH = 50;
+
+// A role and a group share the URL-safe name rule and the user|group membership model.
+export type RoleView = GroupView;
+export const isValidRoleName = isValidGroupName;
+export const rolesFromTuples = groupsFromTuples;
+export interface EffectiveUser {
+  label: string; // email (or the raw id when unresolved)
+}
+
+// The full membership tuple for assigning/revoking `value` to/from `role` (null if value is invalid).
+export function roleMemberTuple(role: string, value: string): RelationTuple | null {
+  const subject = parseSubject(value);
+  return subject ? { namespace: ROLE_NS, object: role, relation: MEMBERS, ...subject } : null;
+}
+
+// Flatten a Keto `expand` tree → the sorted, distinct user ids that effectively hold the role
+// (direct leaves + users reached through member groups, any depth). The subject rides on each
+// node's `tuple`; subject-set nodes (the groups) contribute nothing directly — their members
+// surface as leaves under them.
+export function expandToEffectiveUsers(tree: ExpandTree | null | undefined): string[] {
+  const ids = new Set<string>();
+  const walk = (node?: ExpandTree | null): void => {
+    if (!node) return;
+    const subjectId = node.tuple?.subject_id;
+    if (subjectId?.startsWith("user:")) ids.add(subjectId.slice("user:".length));
+    node.children?.forEach(walk);
+  };
+  walk(tree);
+  return [...ids].sort();
+}
+
+// ---- list view model ----
+
+interface ListState {
+  page: number;
+  pageSize: number;
+  q: string;
+  sort: string | null;
+}
+
+const SORT: Record<string, (r: RoleView) => number | string> = {
+  members: (r) => r.memberCount,
+  name: (r) => r.name,
+};
+const COLUMNS = [
+  { key: "name", label: "Role" },
+  { key: "members", label: "Members" },
+];
+
+function detailHref(name: string): string {
+  return `${ADMIN_ROLES_BASE}/${encodeURIComponent(name)}`;
+}
+
+function listHref(state: ListState, overrides: Partial<ListState> = {}): string {
+  const s = { ...state, ...overrides };
+  const p = new URLSearchParams();
+  if (s.q) p.set("q", s.q);
+  if (s.sort) p.set("sort", s.sort);
+  if (s.page > 1) p.set("page", String(s.page));
+  if (s.pageSize !== DEFAULT_PAGE_SIZE) p.set("pageSize", String(s.pageSize));
+  const qs = p.toString();
+  return qs ? `${ADMIN_ROLES_BASE}?${qs}` : ADMIN_ROLES_BASE;
+}
+
+export function buildRolesListModel(opts: {
+  csrfToken?: string;
+  menu?: MenuConfig;
+  roles: RoleView[];
+  url: URL | URLSearchParams | string;
+  user?: User | null;
+}) {
+  const menu = opts.menu ?? DEFAULT_MENU;
+  const query = parseListQuery(opts.url, { defaultPageSize: DEFAULT_PAGE_SIZE });
+  const sort = query.sort && SORT[query.sort.field] ? query.sort : null;
+  const sortToken = sort ? (sort.dir === "desc" ? `-${sort.field}` : sort.field) : null;
+  const needle = query.q.toLowerCase();
+
+  let list = opts.roles.filter((r) => !needle || r.name.toLowerCase().includes(needle));
+  if (sort) {
+    const get = SORT[sort.field]!;
+    const dir = sort.dir === "desc" ? -1 : 1;
+    list = [...list].sort((a, b) => {
+      const av = get(a), bv = get(b);
+      const cmp = typeof av === "number" && typeof bv === "number" ? av - bv : String(av).localeCompare(String(bv));
+      return cmp * dir;
+    });
+  }
+
+  const page = paginate(list.length, query.page, query.pageSize, { boundaries: 1, siblings: 1 });
+  const start = (page.page - 1) * page.pageSize;
+  const rows = list.slice(start, start + page.pageSize);
+  const state: ListState = { page: page.page, pageSize: page.pageSize, q: query.q, sort: sortToken };
+
+  return {
+    filterBar: listFilterBar(state),
+    nav: adminNav(opts.user?.roles ?? [], menu, "roles"),
+    pagination: listPagination(state, page),
+    shell: buildShellContext({
+      breadcrumbs: [{ href: ADMIN_ROLES_BASE, label: "Admin" }, { label: "Roles" }],
+      csrfToken: opts.csrfToken ?? "",
+      menu,
+      title: "Roles",
+      user: opts.user ?? null,
+    }),
+    table: listTable(rows, state, sort),
+  };
+}
+
+function listTable(rows: RoleView[], state: ListState, sort: { dir: "asc" | "desc"; field: string } | null) {
+  return {
+    caption: "Roles",
+    columns: COLUMNS.map((c) => {
+      const dir = sort && sort.field === c.key ? sort.dir : undefined;
+      const next = dir === "asc" ? `-${c.key}` : c.key;
+      return { href: listHref(state, { page: 1, sort: next }), label: c.label, sort: dir, sortable: true };
+    }),
+    rows: rows.map((r) => ({
+      cells: [{ rowHeader: { href: detailHref(r.name), text: r.name } }, String(r.memberCount)],
+      name: r.name,
+    })),
+  };
+}
+
+function listFilterBar(state: ListState) {
+  const pills: { label: string; remove: string; value: string }[] = [];
+  if (state.q) pills.push({ label: "Search", remove: listHref(state, { page: 1, q: "" }), value: state.q });
+  return {
+    applyLabel: "Apply",
+    clearHref: ADMIN_ROLES_BASE,
+    label: "Filter roles",
+    pills,
+    rows: [[
+      { label: "Search roles", name: "q", placeholder: "Search role name…", type: "search", value: state.q },
+      { type: "spacer" },
+    ]],
+  };
+}
+
+function listPagination(state: ListState, page: ReturnType<typeof paginate>) {
+  const hidden: { name: string; value: string }[] = [];
+  if (state.q) hidden.push({ name: "q", value: state.q });
+  if (state.sort) hidden.push({ name: "sort", value: state.sort });
+  return {
+    label: "Roles pagination",
+    next: { href: page.next ? listHref(state, { page: page.next }) : undefined },
+    pages: page.pages.map((p) =>
+      p.ellipsis ? { ellipsis: true }
+        : p.current ? { current: true, label: String(p.page) }
+          : { href: listHref(state, { page: p.page as number }), label: String(p.page) }),
+    prev: { href: page.prev ? listHref(state, { page: page.prev }) : undefined },
+    rows: { hidden, label: "Rows", name: "pageSize", options: PAGE_SIZES, submitLabel: "Go", value: state.pageSize },
+    summary: { from: page.from, to: page.to, total: page.total },
+  };
+}
+
+// ---- create form + detail view models ----
+
+export function buildRoleFormModel(opts: {
+  csrfToken?: string;
+  error?: string;
+  memberOptions: MemberOption[];
+  menu?: MenuConfig;
+  user?: User | null;
+  values?: { member?: string; name?: string };
+}) {
+  const menu = opts.menu ?? DEFAULT_MENU;
+  const nameField: FieldConfig = {
+    autocomplete: "off", hint: "Lowercase letters, digits, dashes and underscores.", icon: "i-shield",
+    id: "name", label: "Role name", name: "name", required: true, value: opts.values?.name ?? "",
+  };
+  return {
+    error: opts.error,
+    form: {
+      action: ADMIN_ROLES_BASE,
+      cancelHref: ADMIN_ROLES_BASE,
+      csrfToken: opts.csrfToken ?? "",
+      memberOptions: opts.memberOptions,
+      nameField,
+      selectedMember: opts.values?.member ?? "",
+      submitLabel: "Create role",
+    },
+    nav: adminNav(opts.user?.roles ?? [], menu, "roles"),
+    shell: buildShellContext({
+      breadcrumbs: [{ href: ADMIN_ROLES_BASE, label: "Roles" }, { label: "New" }],
+      csrfToken: opts.csrfToken ?? "",
+      menu,
+      title: "New role",
+      user: opts.user ?? null,
+    }),
+  };
+}
+
+export function buildRoleDetailModel(opts: {
+  candidates: MemberOption[];
+  csrfToken?: string;
+  effective: EffectiveUser[];
+  error?: string;
+  members: MemberView[];
+  menu?: MenuConfig;
+  role: { name: string };
+  user?: User | null;
+}) {
+  const menu = opts.menu ?? DEFAULT_MENU;
+  const name = opts.role.name;
+  const base = detailHref(name);
+  const taken = new Set(opts.members.map((m) => m.subject));
+  const options = opts.candidates.filter((c) => !taken.has(c.value)); // members are users/groups, never the role itself
+  return {
+    add: { action: `${base}/members`, options },
+    csrfToken: opts.csrfToken ?? "",
+    delete: { action: `${base}/delete` },
+    effective: opts.effective,
+    error: opts.error,
+    members: { action: `${base}/members/delete`, rows: opts.members },
+    nav: adminNav(opts.user?.roles ?? [], menu, "roles"),
+    role: { name },
+    shell: buildShellContext({
+      breadcrumbs: [{ href: ADMIN_ROLES_BASE, label: "Roles" }, { label: name }],
+      csrfToken: opts.csrfToken ?? "",
+      menu,
+      title: name,
+      user: opts.user ?? null,
+    }),
+  };
+}
+
+// ---- request handler (imperative shell) ----
+
+export interface AdminRolesDeps {
+  csrfSecret: string;
+  keto: KetoClient;
+  kratosAdmin: KratosAdmin;
+  menu: MenuConfig;
+  render: (view: string, data: Record<string, unknown>) => Promise<string>;
+}
+
+// A role exists exactly while it has ≥1 member (Keto has no create-object).
+async function roleExists(keto: KetoClient, name: string): Promise<boolean> {
+  const page = await keto.listRelations({ namespace: ROLE_NS, object: name, relation: MEMBERS, pageSize: 1 });
+  return page.tuples.length > 0;
+}
+
+// The distinct users who effectively hold the role (expand → flatten → label by email). Skipped for
+// an empty role (no member tuples) so we don't expand a non-existent Keto object.
+async function effectiveUsers(keto: KetoClient, name: string, hasMembers: boolean, emailById: Map<string, string>): Promise<EffectiveUser[]> {
+  if (!hasMembers) return [];
+  const tree = await keto.expand({ namespace: ROLE_NS, object: name, relation: MEMBERS }, { maxDepth: EXPAND_MAX_DEPTH });
+  return expandToEffectiveUsers(tree)
+    .map((id) => ({ label: emailById.get(id) ?? `user:${id}` }))
+    .sort((a, b) => a.label.localeCompare(b.label));
+}
+
+export async function handleAdminRoles(ctx: RequestContext, csrfToken: string, deps: AdminRolesDeps): Promise<RouteResult | null> {
+  const path = ctx.url.pathname;
+  if (path !== ADMIN_ROLES_BASE && !path.startsWith(`${ADMIN_ROLES_BASE}/`)) return null;
+
+  if (!ctx.user) throw new GuardError(401, "authentication required", "/login");
+  if (!ctx.roles.includes(ADMIN_PERMISSION)) throw new GuardError(403, "admin role required");
+
+  const { keto, kratosAdmin, menu, render } = deps;
+  const user = ctx.user;
+  const method = (ctx.req.method ?? "GET").toUpperCase();
+  const seg = path.slice(ADMIN_ROLES_BASE.length).split("/").filter(Boolean);
+
+  let form: URLSearchParams | undefined;
+  if (method === "POST") {
+    form = await readFormBody(ctx.req);
+    if (!verifyCsrfRequest({ cookieHeader: ctx.req.headers.cookie, secret: deps.csrfSecret, submitted: form.get(CSRF_FIELD) })) {
+      throw new GuardError(403, "invalid CSRF token");
+    }
+  }
+
+  const renderList = async (): Promise<RouteResult> => {
+    const roles = rolesFromTuples(await pagedTuples(keto, { namespace: ROLE_NS, relation: MEMBERS }));
+    return { html: await render("admin/roles", { model: buildRolesListModel({ csrfToken, menu, roles, url: ctx.url, user }) }) };
+  };
+  const renderForm = async (extra: { error?: string; values?: { member?: string; name?: string } }): Promise<RouteResult> => {
+    const { options } = await memberCandidates(keto, kratosAdmin);
+    return { html: await render("admin/role-form", { model: buildRoleFormModel({ csrfToken, memberOptions: options, menu, user, ...extra }) }) };
+  };
+  const renderDetail = async (name: string): Promise<RouteResult> => {
+    const { emailById, options } = await memberCandidates(keto, kratosAdmin);
+    const tuples = await pagedTuples(keto, { namespace: ROLE_NS, object: name, relation: MEMBERS });
+    const members = tuples.map((t) => memberView(t, emailById));
+    const effective = await effectiveUsers(keto, name, tuples.length > 0, emailById);
+    return { html: await render("admin/role-detail", { model: buildRoleDetailModel({ candidates: options, csrfToken, effective, members, menu, role: { name }, user }) }) };
+  };
+
+  // /admin/roles — list (GET) · create (POST)
+  if (seg.length === 0) {
+    if (method === "GET") return renderList();
+    if (method === "POST") {
+      const name = (form!.get("name") ?? "").trim();
+      const tuple = roleMemberTuple(name, (form!.get("member") ?? "").trim());
+      const reject = (error: string): Promise<RouteResult> =>
+        renderForm({ error, values: { member: form!.get("member") ?? "", name } }).then((r) => ({ ...r, status: 400 }));
+      if (!isValidRoleName(name)) return reject("Role names use lowercase letters, digits, dashes and underscores.");
+      if (!tuple) return reject("Pick a user or group to assign the role to.");
+      if (await roleExists(keto, name)) return reject("A role with that name already exists.");
+      await keto.writeTuple(tuple);
+      return { redirect: detailHref(name) };
+    }
+    return null;
+  }
+
+  // /admin/roles/new — create form
+  if (seg.length === 1 && seg[0] === "new" && method === "GET") return renderForm({});
+
+  // /admin/roles/:name …
+  const name = safeDecode(seg[0]!);
+  if (name === null || !isValidRoleName(name)) return { html: await render("404", { title: "Not found" }), status: 404 };
+  const base = detailHref(name);
+
+  if (seg.length === 1 && method === "GET") return renderDetail(name);
+
+  if (seg.length === 2 && seg[1] === "members" && method === "POST") {
+    const tuple = roleMemberTuple(name, (form!.get("member") ?? "").trim());
+    if (tuple) await keto.writeTuple(tuple); // the picker only offers real users/groups
+    return { redirect: base };
+  }
+  if (seg.length === 2 && seg[1] === "delete" && method === "POST") {
+    await keto.deleteTuple({ namespace: ROLE_NS, object: name, relation: MEMBERS }); // removes every member tuple
+    return { redirect: ADMIN_ROLES_BASE };
+  }
+  if (seg.length === 3 && seg[1] === "members" && seg[2] === "delete" && method === "POST") {
+    const tuple = roleMemberTuple(name, (form!.get("member") ?? "").trim());
+    if (tuple) await keto.deleteTuple(tuple);
+    return { redirect: base };
+  }
+  return null;
+}

src/app.test.ts

@@ -10,7 +10,7 @@ import { createApp } from "./app.ts";
 import { CSRF_COOKIE, issueCsrfToken } from "./csrf.ts";
 import { can, check, GuardError, requireSession } from "./guards.ts";
 import { staticJwks } from "./jwks.ts";
-import type { KetoClient, RelationTuple, SubjectSet } from "./keto-client.ts";
+import type { ExpandTree, KetoClient, RelationTuple, SubjectSet } from "./keto-client.ts";
 import type { Identity, KratosAdmin } from "./kratos-admin.ts";
 import { KratosError, type Flow, type FlowType, type KratosPublic, type Session, type UiNode } from "./kratos-public.ts";
 import { SESSION_COOKIE } from "./login.ts";
@@ -616,6 +616,102 @@ test("admin Groups screen: gate, list, create, detail/membership, delete (CSRF-g
   assert.equal((await get("/admin/groups/%ZZ")).status, 404);
 });
 
+// Built-in Roles & permissions admin screen (§5): gate + list/create/assign/revoke/delete over HTTP
+// against a fake in-memory Keto whose `expand` mirrors Keto's transitive resolution, so the
+// effective-access view surfaces a user reachable only through a group.
+test("admin Roles screen: gate, list, create, assign user/group, effective access (expand), revoke, delete", async (t) => {
+  const ada = randomUUID();
+  const grace = randomUUID();
+  const identities: Identity[] = [
+    { id: ada, schema_id: "default", state: "active", traits: { email: "ada@example.com" } },
+    { id: grace, schema_id: "default", state: "active", traits: { email: "grace@example.com" } },
+  ];
+  // grace is in the `eng` group; `editor` is an existing role whose only direct member is ada.
+  const tuples: RelationTuple[] = [
+    { namespace: "Group", object: "eng", relation: "members", subject_id: `user:${grace}` },
+    { namespace: "Role", object: "editor", relation: "members", subject_id: `user:${ada}` },
+  ];
+  // Mirror Keto's expand shape: the subject rides on `tuple`, set nodes carry members as children.
+  const expandSet = (set: SubjectSet): ExpandTree => ({
+    children: tuples
+      .filter((tp) => tp.namespace === set.namespace && tp.object === set.object && tp.relation === set.relation)
+      .map((tp) => (tp.subject_id ? { tuple: { namespace: "", object: "", relation: "", subject_id: tp.subject_id }, type: "leaf" } : expandSet(tp.subject_set!))),
+    tuple: { namespace: "", object: "", relation: "", subject_set: set },
+    type: "union",
+  });
+  const keto: KetoClient = {
+    check: async () => false,
+    deleteTuple: async (f) => { for (let i = tuples.length - 1; i >= 0; i--) if (matchesTuple(tuples[i]!, f)) tuples.splice(i, 1); },
+    expand: async (set) => expandSet(set),
+    listRelations: async (q = {}) => ({ nextPageToken: null, tuples: tuples.filter((tp) => matchesTuple(tp, q)) }),
+    writeTuple: async (tp) => { if (!tuples.some((t) => matchesTuple(t, tp) && sameSet(t.subject_set, tp.subject_set))) tuples.push(tp); },
+  };
+  const kratosAdmin = stubAdmin({ listIdentities: async () => ({ identities, nextPageToken: null }) });
+  const csrfSecret = "roles-secret";
+  const app = createApp({ csrfSecret, jwks: staticJwks([ecJwk]), keto, kratosAdmin });
+  await new Promise<void>((r) => app.listen(0, r));
+  t.after(() => app.close());
+  const url = `http://localhost:${(app.address() as AddressInfo).port}`;
+  const nowSec = Math.floor(Date.now() / 1000);
+  const token = issueCsrfToken(csrfSecret);
+  const cookie = (roles: string[]) => `${SESSION_COOKIE}=${mintJwt({ email: "admin@x", exp: nowSec + 600, roles, sub: "admin1" })}; ${CSRF_COOKIE}=${token}`;
+  const get = (path: string, roles: string[] = ["admin"]) => fetch(url + path, { headers: { cookie: cookie(roles) }, redirect: "manual" });
+  const post = (path: string, body: string) =>
+    fetch(url + path, { body, headers: { "content-type": "application/x-www-form-urlencoded", cookie: cookie(["admin"]) }, method: "POST", redirect: "manual" });
+
+  // Gate: anonymous → /login; a signed-in non-admin → 403.
+  const anon = await fetch(url + "/admin/roles", { redirect: "manual" });
+  assert.equal(anon.status, 303);
+  assert.equal(anon.headers.get("location"), "/login");
+  assert.equal((await get("/admin/roles", [])).status, 403);
+
+  // List: the existing role shows + the "add" link.
+  const listHtml = await (await get("/admin/roles")).text();
+  assert.match(listHtml, /href="\/admin\/roles\/editor"/);
+  assert.match(listHtml, /href="\/admin\/roles\/new"/);
+
+  // Create: a valid post writes the first-member tuple and redirects to the detail.
+  assert.match(await (await get("/admin/roles/new")).text(), /Create role/);
+  const created = await post("/admin/roles", `_csrf=${token}&name=viewer&member=user:${ada}`);
+  assert.equal(created.status, 303);
+  assert.equal(created.headers.get("location"), "/admin/roles/viewer");
+  assert.ok(tuples.some((tp) => tp.namespace === "Role" && tp.object === "viewer" && tp.subject_id === `user:${ada}`));
+
+  // An invalid name, a duplicate name, or a missing CSRF token are all refused, nothing written.
+  const before = tuples.length;
+  assert.equal((await post("/admin/roles", `_csrf=${token}&name=Bad Name&member=user:${ada}`)).status, 400);
+  assert.equal((await post("/admin/roles", `_csrf=${token}&name=editor&member=user:${ada}`)).status, 400); // already exists
+  assert.equal((await post("/admin/roles", `name=x&member=user:${ada}`)).status, 403);
+  assert.equal(tuples.length, before);
+
+  // Detail: ada (direct) is in the effective-access list; grace (only reachable via a group) is not
+  // yet — though grace appears elsewhere as an assignable candidate, so target the effective <li>.
+  const effectiveLi = (email: string) => new RegExp(`<li><span class="cell-strong">${email.replace(".", "\\.")}`);
+  const detail = await (await get("/admin/roles/editor")).text();
+  assert.match(detail, effectiveLi("ada@example.com"));
+  assert.doesNotMatch(detail, effectiveLi("grace@example.com"));
+
+  // Assign the `eng` group to the role → grace now holds it transitively (effective access via expand).
+  await post("/admin/roles/editor/members", `_csrf=${token}&member=group:eng`);
+  assert.ok(tuples.some((tp) => tp.namespace === "Role" && tp.object === "editor" && tp.subject_set?.object === "eng"));
+  const withGroup = await (await get("/admin/roles/editor")).text();
+  assert.match(withGroup, effectiveLi("grace@example.com"));
+
+  // Revoke the group membership.
+  await post("/admin/roles/editor/members/delete", `_csrf=${token}&member=group:eng`);
+  assert.ok(!tuples.some((tp) => tp.namespace === "Role" && tp.object === "editor" && tp.subject_set?.object === "eng"));
+
+  // Delete the role: removes every member tuple, back to the list.
+  const del = await post("/admin/roles/editor/delete", `_csrf=${token}`);
+  assert.equal(del.status, 303);
+  assert.equal(del.headers.get("location"), "/admin/roles");
+  assert.ok(!tuples.some((tp) => tp.namespace === "Role" && tp.object === "editor"));
+
+  // An invalid role name in the path → 404; malformed %-encoding doesn't 500.
+  assert.equal((await get("/admin/roles/Bad%20Name")).status, 404);
+  assert.equal((await get("/admin/roles/%ZZ")).status, 404);
+});
+
 test("resolveStaticPath blocks traversal and control chars, allows nested files", () => {
   assert.equal(resolveStaticPath("/srv/public", "../app.ts"), null);
   assert.equal(resolveStaticPath("/srv/public", "a\x00b"), null);

src/app.ts

@@ -3,8 +3,9 @@ import { createServer, type Server, type ServerResponse } from "node:http";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import * as ejs from "ejs";
-import { ADMIN_GROUPS_BASE, ADMIN_USERS_BASE } from "./admin-nav.ts";
+import { ADMIN_GROUPS_BASE, ADMIN_ROLES_BASE, ADMIN_USERS_BASE } from "./admin-nav.ts";
 import { type AdminGroupsDeps, handleAdminGroups } from "./admin-groups.ts";
+import { type AdminRolesDeps, handleAdminRoles } from "./admin-roles.ts";
 import { type AdminUsersDeps, handleAdminUsers } from "./admin-users.ts";
 import { readFormBody } from "./body.ts";
 import { buildContext, type User } from "./context.ts";
@@ -79,6 +80,7 @@ export function createApp(options: AppOptions = {}): Server {
   // Users writes to Kratos; Groups writes to Keto and reads users from Kratos for the pickers.
   const adminDeps: AdminUsersDeps | null = kratosAdmin ? { csrfSecret, kratosAdmin, menu, render } : null;
   const adminGroupsDeps: AdminGroupsDeps | null = kratosAdmin && keto ? { csrfSecret, keto, kratosAdmin, menu, render } : null;
+  const adminRolesDeps: AdminRolesDeps | null = kratosAdmin && keto ? { csrfSecret, keto, kratosAdmin, menu, render } : null;
 
   const sendHtml = (res: ServerResponse, status: number, html: string): void => {
     res.writeHead(status, { "content-type": "text/html; charset=utf-8" });
@@ -166,6 +168,14 @@ export function createApp(options: AppOptions = {}): Server {
           return;
         }
       }
+      if (adminRolesDeps && pathname.startsWith(ADMIN_ROLES_BASE)) {
+        const result = await handleAdminRoles(ctx, csrf.token, adminRolesDeps);
+        if (result) {
+          if (csrf.fresh) res.appendHeader("set-cookie", csrfCookie(csrf.token, { secure: secureCookies }));
+          await sendResult(res, result, () => Promise.reject(new Error("admin screens return html, not view")));
+          return;
+        }
+      }
 
       // Themed Kratos self-service pages (login/registration/recovery/verification/settings).
       const flowType = AUTH_FLOWS[pathname];

src/keto-client.test.ts

@@ -72,7 +72,7 @@ test("listRelations builds the filter query + pagination and parses next_page_to
 });
 
 test("expand GETs the read API for a subject set and returns the tree (with max-depth)", async () => {
-  const tree = { children: [{ subject_id: USER, type: "leaf" }], subject_set: { namespace: "Role", object: "admin", relation: "members" }, type: "union" };
+  const tree = { children: [{ tuple: { namespace: "", object: "", relation: "", subject_id: USER }, type: "leaf" }], tuple: { namespace: "", object: "", relation: "", subject_set: { namespace: "Role", object: "admin", relation: "members" } }, type: "union" };
   const { calls, fetchImpl } = recorder(() => res(200, tree));
   const out = await keto(fetchImpl).expand({ namespace: "Role", object: "admin", relation: "members" }, { maxDepth: 3 });
   assert.deepEqual(out, tree);

src/keto-client.ts

@@ -30,12 +30,12 @@ export interface RelationList {
   tuples: RelationTuple[];
 }
 
-// Keto's expand tree: a node is a set operation (union/…) or a leaf, with the resolved
+// Keto's expand tree: a node is a set operation (union/…) or a leaf. The resolved subject
-// subject(s). Shape kept loose — callers walk it as needed (§5 "effective access" view).
+// (subject_id xor subject_set) rides on `tuple`, not the node itself — verified against Keto
+// v26.2.0. A `subject_set` node carries its members as `children` (§5 "effective access" view).
 export interface ExpandTree {
   children?: ExpandTree[];
-  subject_id?: string;
+  tuple?: RelationTuple;
-  subject_set?: SubjectSet;
   type: string;
 }
 

todo.md

@@ -1,7 +1,5 @@
 # Plainpages — implementation TODO
 
-General instruction - always run the stability reviewer after each todo is done.
-
 Build order is top → bottom; each phase is roughly independent and testable.
 Conventions: **write tests first** (node --test for units, Playwright for E2E),
 tear down test containers after runs, keep deps minimal, pin all versions, run
@@ -97,7 +95,7 @@ everything via Docker.
 ## 5. Built-in admin screens (writes go only to Keto/Kratos)
 - [x] Users: list (Kratos identities) with filter/sort/pagination; create/edit/deactivate/delete; trigger recovery. → `src/admin-users.ts`: pure view-model + Kratos-payload builders (`toUserView`, `buildUsersListModel`, `buildUserFormModel`, `create/updateIdentityPayload`, `setStatePayload`) + `handleAdminUsers` (the imperative shell app.ts dispatches `/admin/users*` to). Routes: `GET /admin/users` (list — filter by q/status, sortable headers, paginate; in-memory over one fetched Kratos page since the admin API has no search/sort), `GET|POST /admin/users/new`+`/` (create), `GET|POST /admin/users/:id` (edit; email is the read-only login identifier, name editable, optional initial password), `POST …/:id/state` (deactivate↔reactivate), `…/delete`, `…/recovery` (mints a code via the new `kratosAdmin.createRecoveryCode` admin endpoint, renders the link). Writes go **only to Kratos** (README "stateless"). Gated **admin-only** (anonymous→/login, non-admin→403 via `GuardError`) and every mutation is **CSRF-guarded** (signed double-submit, like logout); reuses the §1 building blocks (filter-bar/data-table/pagination/field) around the app shell. Reviewer's §5 opener done too: extracted `src/shell-context.ts` (`buildShellContext`/`shellUser`) shared by the dashboard + admin screens — kills the hardcoded "Sam Rivers" demo profile, threads the **real** signed-in user (email/derived initials; anonymous→Guest); `dashboard.ts` + `app.ts` now pass `ctx.user`. Added `readonly` to `field.ejs`, `admin` to `RESERVED_PLUGIN_IDS` (a plugin folder can't shadow the screens), `views:[viewsDir]` to the core renderer (so a subfolder view includes the shared `partials/` by root-relative name). Tests-first: `admin-users.test.ts` (mapping/selection/payload matrix), `app.test.ts` HTTP integration (gate/list-filter/create/edit/state/delete/recovery + CSRF reject), `shell-context.test.ts`, `kratos-admin.test.ts` (recovery endpoint), `discovery.test.ts` (reserved `admin`). typecheck + 228 units + 8 visual E2E green. Boot-verified live on the full Ory stack: seeded-admin login → JWT `roles:["admin"]` → `/admin/users` lists identities; create→303→listed, recovery→real Kratos code/link, state→inactive, delete→absent, forged CSRF→403; torn down. Groups/roles/menu-wiring are the next §5 items.
 - [x] Groups: Keto subject sets — list/create/delete + membership management. → `src/admin-groups.ts`: pure view-model + Keto-tuple builders (`groupsFromTuples`, `parseSubject`/`memberTuple`, `memberView`, `isValidGroupName`, `buildGroups{List,Detail,Form}Model`) + `handleAdminGroups` (the imperative shell app.ts dispatches `/admin/groups*` to). A group is a Keto subject set `Group:<name>#members`; a member is a user (`subject_id=user:<uuid>`) or a nested group (`subject_set=Group:<other>#members`). Keto has no create-object, so a group exists while it has ≥1 member: **create** writes the first-member tuple (requires a member, rejects a duplicate/invalid name), **delete** removes every member tuple (one delete-by-partial-filter), **add/remove member** write/delete one tuple. Routes: `GET /admin/groups` (list — search/sort/paginate over one Keto namespace scan), `GET|POST /admin/groups/new`+`/` (create), `GET /admin/groups/:name` (membership detail — members by email, add a user/nested group, remove, delete-group), `POST …/members` · `…/members/delete` · `…/delete`. Writes go **only to Keto** (README "stateless"); Kratos is read only to label the member pickers by email. Gated **admin-only** (anon→/login, non-admin→403) and every mutation **CSRF-guarded**, same as Users; reuses the §1 building blocks around the shell. Extracted `src/admin-nav.ts` (shared Dashboard·Users·Groups sidebar nav) so the two screens can't drift; added a generic `rowHeader` `<th scope=row>` data-table cell (the group name links to its detail). Tests-first: `admin-groups.test.ts` (builder/validation/subject matrix), `app.test.ts` HTTP integration (gate/list/create/dup-reject/detail/add/remove/delete + CSRF + invalid-name & malformed-`%`→404), `data-table.test.ts` (rowHeader). Stability-reviewer (treated as a local PR): APPROVE; fixed its nits — symmetric subject validation (UUID-check the user id), "already exists" feedback on create, malformed-`%`→404 (`safeDecode`). typecheck + 237 units green. Boot-verified the core Keto interactions live (namespace listing, group-collapse counts, delete-group-by-filter, single-member removal). The full-stack groups-CRUD Playwright E2E is §8's scope (line 123), as with the Users screen. Roles/permissions + global-menu wiring are the next §5 items.
-- [ ] Roles & permissions: Keto relations — assign roles to users/groups; "effective access" view via Keto expand.
+- [x] Roles & permissions: Keto relations — assign roles to users/groups; "effective access" view via Keto expand. → `src/admin-roles.ts`: a role is a Keto subject set `Role:<name>#members` (OPL: members are users or groups, resolved transitively — the source of truth the §4 login projects into the JWT). Same shape as the Groups screen, so the pure membership helpers are reused from `admin-groups.ts` (`parseSubject`, `isValidGroupName`, `memberView`, `groupsFromTuples`, and now-exported `pagedTuples`/`memberCandidates`/`safeDecode`). Routes (`handleAdminRoles`, dispatched by app.ts): `GET /admin/roles` (list — search/sort/paginate over one Keto scan), `GET|POST /admin/roles/new`+`/` (create = assign first member; rejects invalid/duplicate name), `GET /admin/roles/:name` (detail), `POST …/members` (assign a user/group) · `…/members/delete` (revoke) · `…/delete` (remove all member tuples). The one role-specific piece is **effective access**: `keto.expand(Role:<name>#members, {maxDepth:50})` → `expandToEffectiveUsers` flattens the tree to the distinct users who hold the role directly *or transitively via a group* (the coarse JWT projection stays direct-only per the README's one-read-per-login design; this view is where group→role inheritance is surfaced). Writes go **only to Keto**; Kratos is read only to label members. Gated admin-only (anon→/login, non-admin→403) + CSRF-guarded, like Users/Groups. Added a "Roles" entry (`i-shield`) to the shared `admin-nav.ts`; new `.plain-list` CSS rule. Tests-first: `admin-roles.test.ts` (builders + expand-flatten matrix) + `app.test.ts` HTTP integration (gate/list/create/dup-reject/assign user&group/effective-access-via-expand/revoke/delete + CSRF + malformed-name→404). Stability-reviewer run as a local PR: APPROVE, no Critical/High; addressed its expand-depth nit (explicit `maxDepth`). 237→243 units + typecheck green. **Live boot-verify caught a real bug the tests missed:** Keto v26.2.0's expand nests the subject under `tuple` (`{type:"leaf",tuple:{subject_id}}`), not at the node top-level as the §4 `ExpandTree` type had guessed — fixed the type + walker + the (wrongly-shaped) fixtures, then re-verified live that a user reachable only through a group surfaces in effective access; torn down. Global-menu wiring is the next §5 item.
 - [ ] Wire into the menu (admin section, permission-gated).
 - [ ] Run the architecture and the product  reviewer agents on the _whole_ project, not just the latest changes, and address their issues.
 - [ ] Go over all comments in the code and the README and try to make it shorter and more information dense. Remove not strictly needed stuff.

views/admin/role-detail.ejs

@@ -0,0 +1,16 @@
+<%#
+  Role admin detail page (todo §5): the role-detail body (members · effective access) in the shell.
+%><%
+  const nav = include("partials/nav-tree", { nodes: model.nav });
+  const body = include("partials/role-detail-body", { add: model.add, csrfToken: model.csrfToken, del: model.delete, effective: model.effective, error: model.error, members: model.members, role: model.role });
+-%>
+<%- include("partials/shell", {
+  body,
+  brand: model.shell.brand,
+  breadcrumbs: model.shell.breadcrumbs,
+  csrfToken: model.shell.csrfToken,
+  nav,
+  theme: model.shell.theme,
+  title: model.shell.title,
+  user: model.shell.user,
+}) %>

views/admin/role-form.ejs

@@ -0,0 +1,16 @@
+<%#
+  Role admin create page (todo §5): the role-form body captured into the app shell.
+%><%
+  const nav = include("partials/nav-tree", { nodes: model.nav });
+  const body = include("partials/role-form-body", { error: model.error, form: model.form });
+-%>
+<%- include("partials/shell", {
+  body,
+  brand: model.shell.brand,
+  breadcrumbs: model.shell.breadcrumbs,
+  csrfToken: model.shell.csrfToken,
+  nav,
+  theme: model.shell.theme,
+  title: model.shell.title,
+  user: model.shell.user,
+}) %>

views/admin/roles.ejs

@@ -0,0 +1,21 @@
+<%#
+  Roles admin list (todo §5): the same building blocks as the Groups screen, around the shell, backed
+  by live Keto Role subject sets (src/admin-roles.ts). Filter/sort/page round-trip the URL.
+%><%
+  const nav = include("partials/nav-tree", { nodes: model.nav });
+  const filters = include("partials/filter-bar", model.filterBar);
+  const table = include("partials/data-table", model.table);
+  const pager = include("partials/pagination", model.pagination);
+  const actions = '<a class="btn btn-primary" href="/admin/roles/new"><svg class="ico ico-sm" aria-hidden="true"><use href="#i-plus"/></svg>Add role</a>';
+-%>
+<%- include("partials/shell", {
+  actions,
+  body: filters + table + pager,
+  brand: model.shell.brand,
+  breadcrumbs: model.shell.breadcrumbs,
+  csrfToken: model.shell.csrfToken,
+  nav,
+  theme: model.shell.theme,
+  title: model.shell.title,
+  user: model.shell.user,
+}) %>

views/partials/role-detail-body.ejs

@@ -0,0 +1,57 @@
+<%#
+  Admin role detail body (todo §5), captured into the shell content slot. Config:
+    role      { name }
+    members   { action, rows: { kind:"group"|"user", label, subject }[] }   action = revoke endpoint
+    effective { label }[]                                                    users who hold the role (expand)
+    add       { action, options: {label,value}[] }                          action = assign endpoint
+    del       { action }                                                     delete the whole role
+    csrfToken, error?
+%><%
+  const role = locals.role;
+  const members = locals.members;
+  const effective = locals.effective;
+  const add = locals.add;
+  const del = locals.del;
+  const csrf = locals.csrfToken;
+-%>
+<div class="form-page">
+<% if (locals.error) { -%>
+<%- include("alert", { text: locals.error, tone: "neg" }) %>
+<% } -%>
+  <section class="form-card" aria-labelledby="members-h">
+    <h2 class="card-title" id="members-h">Assigned to</h2>
+<% if (members.rows.length) { -%>
+    <div class="table-wrap"><table class="table"><caption class="sr-only">Members of <%= role.name %></caption><thead><tr><th scope="col">Member</th><th scope="col">Type</th><th class="col-actions" scope="col"><span class="sr-only">Actions</span></th></tr></thead><tbody>
+<% members.rows.forEach((m) => { -%>
+      <tr><th scope="row"><span class="cell-strong"><%= m.label %></span></th><td><span class="badge info"><span class="dot"></span><%= m.kind === "group" ? "Group" : "User" %></span></td><td class="col-actions"><form method="post" action="<%= members.action %>"><input type="hidden" name="_csrf" value="<%= csrf %>"><input type="hidden" name="member" value="<%= m.subject %>"><button class="btn" type="submit"><svg class="ico ico-sm" aria-hidden="true"><use href="#i-x"/></svg>Revoke</button></form></td></tr>
+<% }) -%>
+    </tbody></table></div>
+<% } else { -%>
+    <p class="cell-muted">Not assigned to anyone yet.</p>
+<% } -%>
+  </section>
+  <section class="form-card" aria-labelledby="effective-h">
+    <h2 class="card-title" id="effective-h">Effective access</h2>
+    <p class="field-hint">Everyone who holds this role — directly or through a group (resolved by Keto).</p>
+<% if (effective.length) { -%>
+    <ul class="plain-list">
+<% effective.forEach((u) => { -%>
+      <li><span class="cell-strong"><%= u.label %></span></li>
+<% }) -%>
+    </ul>
+<% } else { -%>
+    <p class="cell-muted">No users hold this role yet.</p>
+<% } -%>
+  </section>
+  <section class="form-card" aria-labelledby="add-h">
+    <h2 class="card-title" id="add-h">Assign the role</h2>
+<% if (add.options.length) { -%>
+    <form class="inline-form" method="post" action="<%= add.action %>"><input type="hidden" name="_csrf" value="<%= csrf %>"><label class="sr-only" for="add-member">Member</label><span class="select"><select id="add-member" name="member" required><option value="" disabled selected>Choose a user or group…</option><% add.options.forEach((o) => { %><option value="<%= o.value %>"><%= o.label %></option><% }) %></select></span><button class="btn btn-primary" type="submit"><svg class="ico ico-sm" aria-hidden="true"><use href="#i-plus"/></svg>Assign</button></form>
+<% } else { -%>
+    <p class="cell-muted">All users and groups already have this role.</p>
+<% } -%>
+  </section>
+  <section class="form-card admin-actions" aria-label="Role actions">
+    <form method="post" action="<%= del.action %>"><input type="hidden" name="_csrf" value="<%= csrf %>"><button class="btn btn-danger" type="submit"><svg class="ico ico-sm" aria-hidden="true"><use href="#i-trash"/></svg>Delete role</button></form>
+  </section>
+</div>

views/partials/role-form-body.ejs

@@ -0,0 +1,26 @@
+<%#
+  Admin role create form body (todo §5), captured into the shell content slot. Config:
+    form  { action, csrfToken, submitLabel, cancelHref, nameField: field.ejs config,
+            memberOptions: {label,value}[], selectedMember }
+    error?  string  shown when a write was rejected
+%><%
+  const form = locals.form;
+-%>
+<div class="form-page">
+<% if (locals.error) { -%>
+<%- include("alert", { text: locals.error, tone: "neg" }) %>
+<% } -%>
+  <form class="form-card" method="post" action="<%= form.action %>">
+    <input type="hidden" name="_csrf" value="<%= form.csrfToken %>">
+    <%- include("field", form.nameField) %>
+    <div class="field">
+      <label for="member">Assign to</label>
+      <span class="select"><select id="member" name="member" required><option value="" disabled<% if (!form.selectedMember) { %> selected<% } %>>Choose a user or group…</option><% form.memberOptions.forEach((o) => { %><option value="<%= o.value %>"<% if (form.selectedMember === o.value) { %> selected<% } %>><%= o.label %></option><% }) %></select></span>
+      <span class="field-hint">A role exists once assigned; add more users or groups after creating it.</span>
+    </div>
+    <div class="form-actions">
+      <a class="btn" href="<%= form.cancelHref %>">Cancel</a>
+      <button class="btn btn-primary" type="submit"><%= form.submitLabel %></button>
+    </div>
+  </form>
+</div>