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.

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.
-async function pagedTuples(keto: KetoClient, query: RelationQuery): Promise<RelationTuple[]> {
+// Drain every page of a relation-tuple query. (Reused by the Roles screen — same membership model.)
+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
-// subject(s). Shape kept loose — callers walk it as needed (§5 "effective access" view).
+// Keto's expand tree: a node is a set operation (union/…) or a leaf. The resolved subject
+// (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;
-  subject_set?: SubjectSet;
+  tuple?: RelationTuple;
   type: string;
 }