Move admin screens (users/groups/roles/oauth2-clients) into a drop-in example plugin; add the ctx.system capability surface

examples/README.md

@@ -6,5 +6,6 @@ across (or bind-mount your own) and restart.
 | Path | Copy into | Example of |
 | --- | --- | --- |
 | [`plugins/scheduling/`](plugins/scheduling/) | `plugins/scheduling/` | The reference plugin: a list page over an upstream REST service, a CSRF-guarded form that forwards a write, and permission-gated nav — built from the core building blocks, holding no state. Imports the host surface as `#plugin-api`. See its [README](plugins/scheduling/README.md) and the [plugin contract](../README.md#building-plugins). |
+| [`plugins/admin/`](plugins/admin/) | `plugins/admin/` | The system-admin plugin: the Users / Groups / Roles / OAuth2-clients screens for running Plainpages itself. A *system* plugin — it administers the Ory identity stack via the privileged [`ctx.system`](../README.md#system-capabilities-the-ctxsystem-surface) surface instead of its own upstream. Copy it in to get a GUI for user & group admin. See its [README](plugins/admin/README.md). |
 | [`config/menu.ts`](config/menu.ts) | `config/menu.ts` | The central menu override + branding template (rename/group/order/hide nav, set app name/logo/theme). Imports its typed builder as `#menu-config`; `config/` ships empty, so defaults apply until you copy this in. See [The menu system](../README.md#the-menu-system). |
 | [`shifts-upstream/`](shifts-upstream/) | — (dev service) | A throwaway mock backend the reference plugin reads/writes — stdlib-only, in-memory, no auth. Stands in for your real service so `docker compose up` shows the plugin working out of the box; in production you point `SCHEDULING_UPSTREAM` at the real thing instead. |

examples/plugins/admin/README.md

@@ -0,0 +1,48 @@
+# Admin — the system-administration plugin
+
+The Users / Groups / Roles / OAuth2-clients screens for running Plainpages itself. These used to be
+built into the core; they now ship as a **drop-in example plugin** so a fresh clone has no admin GUI
+until you opt in. Copy this folder into `plugins/` (it keeps the id and mount path `admin`, so the
+screens live at `/admin/*`) and restart:
+
+```bash
+cp -r examples/plugins/admin plugins/admin
+docker compose restart web
+```
+
+The seeded `admin@plainpages.local` already holds the `admin` role, so the section appears in the
+menu and the screens work immediately.
+
+## What it demonstrates — a *system* plugin
+
+Most plugins fetch their data from an upstream service of their own (see the [scheduling
+reference](../scheduling/README.md)). The admin screens instead administer **Plainpages' own identity
+stack**, so they use the privileged **`ctx.system`** surface the host exposes to a system plugin:
+
+- **`ctx.system.kratosAdmin`** — create/edit/deactivate/delete Kratos identities (Users).
+- **`ctx.system.keto`** — read/write the Keto relationship graph (Groups, Roles).
+- **`ctx.system.hydra`** — register/list/delete Ory Hydra OAuth2 clients.
+- **`ctx.system.revoke(sub)`** — the optional instant-revoke hook: a deactivate/delete or a
+  user's role change kills that subject's live tokens at once instead of waiting out the JWT TTL.
+
+`ctx.system` is populated only when the host wired those services (the dev stack wires Kratos + Keto,
+and Hydra when configured). Where a capability is absent the screen degrades to a themed 503 rather
+than crashing — see `admin-shared.ts`. Everything else is an ordinary plugin: folder-discovered,
+gated per route by `permission: "admin"`, rendering the core building blocks in `views/`.
+
+## Layout
+
+- `plugin.ts` — the manifest: the gated Admin nav fragment, the `admin` permission token, and the
+  route table — one thin handler per method+path, all gated by `permission: "admin"`.
+- `admin-users.ts` · `admin-groups.ts` · `admin-roles.ts` · `admin-clients.ts` — each a set of pure
+  view-model builders (unit-tested in the matching `*.test.ts`) plus thin per-route handlers keyed on
+  `ctx.params` (the host extracts `:id`/`:name`), sharing a small `withX` wrapper that resolves the
+  admin gate + the needed `ctx.system` clients once.
+- `admin-shared.ts` — the shared gate (`requireAdmin`), CSRF form reader (`guardedForm`), confirm
+  model, nav fragment, and the not-found / unavailable helpers.
+- `views/` — the screens' EJS, plus the admin-specific body partials under `views/partials/`. They
+  `include()` the core building-block partials (shell, data-table, filter-bar, field, …).
+
+The four screens hold **no state** — everything lives in Ory. Handlers are thin, so their builders
+unit-test as pure functions with no host; the HTTP routing/gate/CSRF is covered in
+`src/http/app.test.ts` (which mounts this plugin) and end-to-end in `e2e-tests/full-flow.spec.ts`.

examples/plugins/admin/admin-clients.test.ts

@@ -0,0 +1,105 @@
+// Built-in OAuth2 clients admin screen: the pure view-model + Hydra-payload builders. A client
+// is an Ory Hydra OAuth2 client (apps that log in *through* us); writes go only to Hydra. The
+// HTTP routing/gate/CSRF + live Hydra calls (incl. the one-time secret) are exercised in app.test.ts.
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  buildClientDetailModel,
+  buildClientFormModel,
+  buildClientsListModel,
+  type ClientInput,
+  clientPayload,
+  parseRedirectUris,
+  toClientView,
+  validateClientInput,
+} from "./admin-clients.ts";
+
+const input = (over: Partial<ClientInput> = {}): ClientInput =>
+  ({ firstParty: false, name: "Acme", public: false, redirectUris: ["https://acme.example/cb"], scope: "openid offline_access", ...over });
+
+test("toClientView maps Hydra fields → view (public from auth method, first-party from metadata, scopes split)", () => {
+  assert.deepEqual(
+    toClientView({ client_id: "c1", client_name: "Acme", metadata: { first_party: true }, redirect_uris: ["https://a/cb"], scope: "openid email", token_endpoint_auth_method: "client_secret_basic" }),
+    { firstParty: true, id: "c1", name: "Acme", public: false, redirectUris: ["https://a/cb"], scopes: ["openid", "email"] },
+  );
+  // A public client + no name → falls back to the id; absent metadata/scope tolerated.
+  assert.deepEqual(
+    toClientView({ client_id: "c2", token_endpoint_auth_method: "none" }),
+    { firstParty: false, id: "c2", name: "c2", public: true, redirectUris: [], scopes: [] },
+  );
+});
+
+test("parseRedirectUris splits on newlines/whitespace/commas and drops empties", () => {
+  assert.deepEqual(parseRedirectUris("https://a/cb\n https://b/cb \n\n, https://c/cb"), ["https://a/cb", "https://b/cb", "https://c/cb"]);
+  assert.deepEqual(parseRedirectUris("   "), []);
+});
+
+test("clientPayload maps the input to Hydra's create body (auth-code + refresh, type via auth method)", () => {
+  assert.deepEqual(clientPayload(input()), {
+    client_name: "Acme",
+    grant_types: ["authorization_code", "refresh_token"],
+    metadata: { first_party: false },
+    redirect_uris: ["https://acme.example/cb"],
+    response_types: ["code"],
+    scope: "openid offline_access",
+    token_endpoint_auth_method: "client_secret_basic",
+  });
+  const pub = clientPayload(input({ firstParty: true, public: true }));
+  assert.equal(pub.token_endpoint_auth_method, "none");
+  assert.deepEqual(pub.metadata, { first_party: true });
+});
+
+test("validateClientInput requires a name, ≥1 redirect URI, and absolute redirect URLs", () => {
+  assert.equal(validateClientInput(input()), null);
+  assert.match(validateClientInput(input({ name: "" }))!, /name/i);
+  assert.match(validateClientInput(input({ redirectUris: [] }))!, /redirect/i);
+  assert.match(validateClientInput(input({ redirectUris: ["not a url"] }))!, /redirect URI/i);
+});
+
+test("buildClientsListModel filters by search, paginates; the name links to the detail page", () => {
+  const clients = Array.from({ length: 30 }, (_, i) => ({ client_id: `id-${String(i).padStart(2, "0")}`, client_name: `app-${String(i).padStart(2, "0")}`, token_endpoint_auth_method: "client_secret_basic" }));
+
+  const all = buildClientsListModel({ clients, url: "http://x/admin/clients" });
+  assert.equal(all.pagination.summary.total, 30);
+  assert.equal(all.table.rows.length, 25); // default page size
+  assert.equal(all.title, "OAuth2 clients");
+  const first = all.table.rows[0]!.cells[0] as { rowHeader: { href: string; text: string } };
+  assert.equal(first.rowHeader.text, "app-00");
+  assert.equal(first.rowHeader.href, "/admin/clients/id-00");
+
+  const one = buildClientsListModel({ clients, url: "http://x/admin/clients?q=app-07" });
+  assert.equal(one.pagination.summary.total, 1);
+  assert.deepEqual(one.filterBar.pills.map((p) => p.label), ["Search"]);
+});
+
+test("buildClientFormModel: a register form with name + scope fields; values reflected on error", () => {
+  const m = buildClientFormModel({ csrfToken: "tok.sig" });
+  assert.equal(m.title, "Register client");
+  assert.equal(m.form.action, "/admin/clients");
+  assert.equal(m.form.submitLabel, "Register client");
+  assert.equal(m.form.csrfToken, "tok.sig");
+  assert.equal(m.form.nameField.required, true);
+  assert.equal(m.form.scopeField.value, "openid offline_access"); // sensible default
+
+  const err = buildClientFormModel({ error: "Add at least one redirect URI.", values: { firstParty: true, name: "Acme", public: true, redirectUris: ["https://a/cb"], scope: "openid" } });
+  assert.equal(err.error, "Add at least one redirect URI.");
+  assert.equal(err.form.nameField.value, "Acme");
+  assert.equal(err.form.redirectUris, "https://a/cb");
+  assert.equal(err.form.public, true);
+  assert.equal(err.form.firstParty, true);
+});
+
+test("buildClientDetailModel: client info + delete action; the one-time secret + created banner show only right after create", () => {
+  const client = toClientView({ client_id: "c1", client_name: "Acme", redirect_uris: ["https://a/cb"], scope: "openid", token_endpoint_auth_method: "client_secret_basic" });
+
+  const plain = buildClientDetailModel({ client });
+  assert.equal(plain.title, "Acme");
+  assert.equal(plain.delete.action, "/admin/clients/c1/delete");
+  assert.equal(plain.created, false);
+  assert.equal(plain.secret, undefined);
+
+  const fresh = buildClientDetailModel({ client, created: true, secret: "s3cr3t" });
+  assert.equal(fresh.created, true);
+  assert.equal(fresh.secret, "s3cr3t");
+  assert.equal(fresh.title, "Client registered");
+});

examples/plugins/admin/admin-clients.ts

@@ -0,0 +1,310 @@
+// OAuth2 clients admin screen: register / list / delete the OAuth2 clients other
+// apps log in *through* us with (Ory Hydra, the login+consent handlers). A client is an Ory Hydra
+// OAuth2 client; writes go only to Hydra. Hydra returns the client_secret once, on create — so the
+// register POST renders the new client's detail page (with the one-time secret) directly instead of a
+// PRG redirect (mirrors the Users "trigger recovery" one-time code). Below the builders are thin
+// per-route handlers (keyed on ctx.params) over a shared `withClients` gate — admin-only, CSRF-guarded.
+
+import { type HydraAdmin, HydraError, type OAuth2Client, paginate, parseListQuery, type RequestContext, type RouteHandler, type RouteResult, type User } from "#plugin-api";
+import { ADMIN_CLIENTS_BASE, buildConfirmModel, guardedForm, notFound, requireAdmin, unavailable } from "./admin-shared.ts";
+import type { FieldConfig } from "./admin-users.ts";
+
+const DEFAULT_PAGE_SIZE = 25;
+const PAGE_SIZES = [25, 50, 100];
+// One Hydra page is fetched and filtered/paged in memory — its list API has no search. Ample for an
+// admin tool (the OAuth2 clients of a deployment number in the dozens); raise if one outgrows it.
+const LIST_FETCH_SIZE = 250;
+const DEFAULT_SCOPE = "openid offline_access";
+
+export interface ClientView {
+  firstParty: boolean;
+  id: string; // client_id
+  name: string;
+  public: boolean; // public (PKCE, no secret) vs confidential
+  redirectUris: string[];
+  scopes: string[];
+}
+
+export interface ClientInput {
+  firstParty: boolean;
+  name: string;
+  public: boolean;
+  redirectUris: string[];
+  scope: string;
+}
+
+export function toClientView(client: OAuth2Client): ClientView {
+  const id = client.client_id ?? "";
+  return {
+    firstParty: (client.metadata as { first_party?: unknown } | undefined)?.first_party === true,
+    id,
+    name: client.client_name?.trim() || id || "(unnamed)",
+    public: client.token_endpoint_auth_method === "none",
+    redirectUris: client.redirect_uris ?? [],
+    scopes: (client.scope ?? "").split(/\s+/).filter(Boolean),
+  };
+}
+
+// Split a textarea value into redirect URIs (one per line / whitespace / comma), dropping empties.
+export function parseRedirectUris(raw: string): string[] {
+  return raw.split(/[\s,]+/).map((s) => s.trim()).filter(Boolean);
+}
+
+// Hydra's create body. We register a standard authorization-code web/native client (+ refresh);
+// the type (confidential vs public/PKCE) and auto-consent ride the auth method + metadata.
+export function clientPayload(input: ClientInput): Record<string, unknown> {
+  return {
+    client_name: input.name,
+    grant_types: ["authorization_code", "refresh_token"],
+    metadata: { first_party: input.firstParty },
+    redirect_uris: input.redirectUris,
+    response_types: ["code"],
+    scope: input.scope,
+    token_endpoint_auth_method: input.public ? "none" : "client_secret_basic",
+  };
+}
+
+export function validateClientInput(input: ClientInput): string | null {
+  if (!input.name) return "Enter a name for the client.";
+  if (!input.redirectUris.length) return "Add at least one redirect URI.";
+  for (const uri of input.redirectUris) {
+    try {
+      new URL(uri); // must be an absolute URL — any scheme (public/native clients use custom ones)
+    } catch {
+      return `"${uri}" is not a valid redirect URI — use an absolute URL like https://app.example.com/callback.`;
+    }
+  }
+  return null;
+}
+
+// ---- list view model ----
+
+interface ListState {
+  page: number;
+  pageSize: number;
+  q: string;
+}
+
+function detailHref(id: string): string {
+  return `${ADMIN_CLIENTS_BASE}/${encodeURIComponent(id)}`;
+}
+
+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.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_CLIENTS_BASE}?${qs}` : ADMIN_CLIENTS_BASE;
+}
+
+export function buildClientsListModel(opts: {
+  clients: OAuth2Client[];
+  csrfToken?: string;
+  url: URL | URLSearchParams | string;
+}) {
+  const query = parseListQuery(opts.url, { defaultPageSize: DEFAULT_PAGE_SIZE });
+  const needle = query.q.toLowerCase();
+
+  const all = opts.clients.map(toClientView);
+  const list = all.filter((c) => !needle || c.name.toLowerCase().includes(needle) || c.id.toLowerCase().includes(needle));
+
+  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 };
+
+  return {
+    breadcrumbs: [{ href: ADMIN_CLIENTS_BASE, label: "Admin" }, { label: "OAuth2 clients" }],
+    filterBar: listFilterBar(state),
+    pagination: listPagination(state, page),
+    table: listTable(rows),
+    title: "OAuth2 clients",
+  };
+}
+
+function listTable(rows: ClientView[]) {
+  return {
+    caption: "OAuth2 clients",
+    columns: [{ label: "Name" }, { label: "Client ID" }, { label: "Type" }],
+    rows: rows.map((c) => ({
+      cells: [
+        { rowHeader: { href: detailHref(c.id), text: c.name } },
+        { className: "cell-muted", text: c.id },
+        { badge: { label: c.public ? "Public" : "Confidential", tone: c.public ? "warn" : "info" } },
+      ],
+      name: c.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_CLIENTS_BASE,
+    label: "Filter clients",
+    pills,
+    rows: [[
+      { label: "Search clients", name: "q", placeholder: "Search name or client ID…", 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 });
+  return {
+    label: "Clients 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 },
+  };
+}
+
+// ---- register form + detail view models ----
+
+export function buildClientFormModel(opts: {
+  csrfToken?: string;
+  error?: string;
+  values?: Partial<ClientInput>;
+}) {
+  const v = opts.values;
+  const nameField: FieldConfig = {
+    autocomplete: "off", icon: "i-box", id: "name", label: "Name", name: "name", required: true, value: v?.name ?? "",
+  };
+  const scopeField: FieldConfig = {
+    hint: "Space-separated scopes the client may request.", id: "scope", label: "Scopes", name: "scope",
+    value: v?.scope ?? DEFAULT_SCOPE,
+  };
+  return {
+    breadcrumbs: [{ href: ADMIN_CLIENTS_BASE, label: "OAuth2 clients" }, { label: "Register" }],
+    error: opts.error,
+    form: {
+      action: ADMIN_CLIENTS_BASE,
+      cancelHref: ADMIN_CLIENTS_BASE,
+      csrfToken: opts.csrfToken ?? "",
+      firstParty: v?.firstParty ?? false,
+      nameField,
+      public: v?.public ?? false,
+      redirectUris: (v?.redirectUris ?? []).join("\n"),
+      scopeField,
+      submitLabel: "Register client",
+    },
+    title: "Register client",
+  };
+}
+
+export function buildClientDetailModel(opts: {
+  client: ClientView;
+  created?: boolean; // just registered → success banner + the one-time secret (if any)
+  csrfToken?: string;
+  secret?: string; // one-time client_secret (confidential clients), shown once right after create
+}) {
+  const base = detailHref(opts.client.id);
+  return {
+    breadcrumbs: [{ href: ADMIN_CLIENTS_BASE, label: "OAuth2 clients" }, { label: opts.client.name }],
+    client: opts.client,
+    created: opts.created ?? false,
+    csrfToken: opts.csrfToken ?? "",
+    delete: { action: `${base}/delete` },
+    secret: opts.secret,
+    title: opts.created ? "Client registered" : opts.client.name,
+  };
+}
+
+// ---- request handler (imperative shell) ----
+
+function readClientInput(form: URLSearchParams): ClientInput {
+  return {
+    firstParty: form.get("firstParty") === "on",
+    name: (form.get("name") ?? "").trim(),
+    public: form.get("public") === "on",
+    redirectUris: parseRedirectUris(form.get("redirectUris") ?? ""),
+    scope: (form.get("scope") ?? "").trim(),
+  };
+}
+
+// Shared per-request deps for the OAuth2-clients screen, resolved by `withClients`: the gate + the
+// Hydra capability (else a themed 503). Each route below is a thin handler over these.
+interface ClientsDeps { ctx: RequestContext; hydra: HydraAdmin; user: User; }
+
+function withClients(inner: (deps: ClientsDeps) => Promise<RouteResult>): RouteHandler {
+  return async (ctx) => {
+    const user = requireAdmin(ctx);
+    const hydra = ctx.system?.hydra;
+    if (!hydra) return unavailable(ctx, "Hydra OAuth2 admin");
+    return inner({ ctx, hydra, user });
+  };
+}
+
+// Same, plus the target client from ctx.params.id (unknown → themed 404).
+function withClient(inner: (deps: ClientsDeps, client: OAuth2Client, id: string) => Promise<RouteResult>): RouteHandler {
+  return withClients(async (deps) => {
+    const id = deps.ctx.params["id"] ?? "";
+    const client = await deps.hydra.getClient(id);
+    if (!client) return notFound(deps.ctx);
+    return inner(deps, client, id);
+  });
+}
+
+const clientFormResult = (ctx: RequestContext, extra: { error?: string; values?: Partial<ClientInput> }): RouteResult =>
+  ({ data: { chrome: ctx.chrome, model: buildClientFormModel({ csrfToken: ctx.chrome.csrfToken, ...extra }) }, view: "client-form" });
+const clientDetailResult = (ctx: RequestContext, client: OAuth2Client, extra: { created?: boolean; secret?: string } = {}): RouteResult =>
+  ({ data: { chrome: ctx.chrome, model: buildClientDetailModel({ client: toClientView(client), csrfToken: ctx.chrome.csrfToken, ...extra }) }, view: "client-detail" });
+
+// GET /admin/clients — the list.
+export const clientsList = withClients(async ({ ctx, hydra }) => {
+  const { clients } = await hydra.listClients({ pageSize: LIST_FETCH_SIZE });
+  return { data: { chrome: ctx.chrome, model: buildClientsListModel({ clients, csrfToken: ctx.chrome.csrfToken, url: ctx.url }) }, view: "clients" };
+});
+
+// POST /admin/clients — register; on success show the one-time secret directly (no PRG, Hydra never
+// returns it again). A Hydra 4xx (bad redirect/scope) re-renders the form (400); a 5xx rethrows → 500.
+export const clientsCreate = withClients(async ({ ctx, hydra, user }) => {
+  const input = readClientInput((await guardedForm(ctx))!);
+  const error = validateClientInput(input);
+  if (error) return { ...clientFormResult(ctx, { error, values: input }), status: 400 };
+  let created: OAuth2Client;
+  try {
+    created = await hydra.createClient(clientPayload(input));
+  } catch (err) {
+    if (err instanceof HydraError && err.status < 500) return { ...clientFormResult(ctx, { error: "Hydra rejected the client — check the redirect URIs and scopes.", values: input }), status: 400 };
+    throw err;
+  }
+  ctx.log.info("admin: oauth2 client registered", { actor: user.id, client: created.client_id ?? "" });
+  return clientDetailResult(ctx, created, { created: true, ...(created.client_secret ? { secret: created.client_secret } : {}) });
+});
+
+// GET /admin/clients/new — the register form.
+export const clientsNewForm = withClients(({ ctx }) => Promise.resolve(clientFormResult(ctx, {})));
+
+// GET /admin/clients/:id — the detail (read-only; the secret is shown only once, at creation).
+export const clientsDetail = withClient((deps, client) => Promise.resolve(clientDetailResult(deps.ctx, client)));
+
+// GET /admin/clients/:id/delete — the deliberate confirm step.
+export const clientsDeleteConfirm = withClient((deps, client, id) => {
+  const base = detailHref(id);
+  const name = toClientView(client).name;
+  return Promise.resolve({ data: { chrome: deps.ctx.chrome, model: buildConfirmModel({
+    breadcrumbs: [{ href: ADMIN_CLIENTS_BASE, label: "OAuth2 clients" }, { href: base, label: name }, { label: "Delete" }],
+    cancelHref: base, confirmAction: `${base}/delete`, confirmLabel: "Delete client",
+    message: `Delete client ${name}? Apps using it can no longer sign in through Plainpages.`, title: "Delete client",
+  }) }, view: "confirm" });
+});
+
+// POST /admin/clients/:id/delete — perform it.
+export const clientsDelete = withClient(async ({ ctx, hydra, user }, _client, id) => {
+  await guardedForm(ctx); // CSRF-verify the POST
+  await hydra.deleteClient(id);
+  ctx.log.info("admin: oauth2 client deleted", { actor: user.id, client: id });
+  return { redirect: ADMIN_CLIENTS_BASE };
+});

examples/plugins/admin/admin-groups.test.ts

@@ -0,0 +1,112 @@
+// Built-in Groups admin screen: the pure view-model + Keto-tuple builders. A group is a
+// Keto subject set (Group:<name>#members); membership tuples carry users (subject_id) or nested
+// groups (subject_set). 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 {
+  buildGroupDetailModel,
+  buildGroupFormModel,
+  buildGroupsListModel,
+  groupsFromTuples,
+  isValidGroupName,
+  memberTuple,
+  memberView,
+  parseSubject,
+} from "./admin-groups.ts";
+import type { RelationTuple } from "#plugin-api";
+
+const uid = (n: number) => `01902d5e-7b6c-7e3a-9f21-3c8d1e0a4b${String(n).padStart(2, "0")}`;
+const userTuple = (group: string, n: number): RelationTuple =>
+  ({ namespace: "Group", object: group, relation: "members", subject_id: `user:${uid(n)}` });
+const groupTuple = (group: string, child: string): RelationTuple =>
+  ({ namespace: "Group", object: group, relation: "members", subject_set: { namespace: "Group", object: child, relation: "members" } });
+
+test("isValidGroupName accepts URL-safe names, rejects empties/spaces/uppercase/leading punctuation", () => {
+  for (const ok of ["eng", "team-a", "a1_b9", "x"]) assert.equal(isValidGroupName(ok), true, ok);
+  for (const bad of ["", "Eng", "a b", "-bad", "_bad", "a/b", "a".repeat(65)]) assert.equal(isValidGroupName(bad), false, bad);
+});
+
+test("parseSubject + memberTuple map the form value to the user/nested-group subject (else null)", () => {
+  assert.deepEqual(parseSubject(`user:${uid(1)}`), { subject_id: `user:${uid(1)}` });
+  assert.deepEqual(parseSubject("group:eng"), { subject_set: { namespace: "Group", object: "eng", relation: "members" } });
+  // Both forms are validated: a non-UUID user / invalid group name is rejected, not written blindly.
+  for (const bad of ["", "user:", "user:not-a-uuid", "group:", "group:Bad Name", "nope:x", "plain"]) assert.equal(parseSubject(bad), null, bad);
+
+  assert.deepEqual(memberTuple("design", `user:${uid(2)}`), { namespace: "Group", object: "design", relation: "members", subject_id: `user:${uid(2)}` });
+  assert.deepEqual(memberTuple("design", "group:eng"), { namespace: "Group", object: "design", relation: "members", subject_set: { namespace: "Group", object: "eng", relation: "members" } });
+  assert.equal(memberTuple("design", "bad"), null);
+});
+
+test("groupsFromTuples collapses membership tuples → distinct groups + member counts, sorted by name", () => {
+  const tuples = [userTuple("eng", 1), userTuple("eng", 2), groupTuple("eng", "design"), userTuple("design", 3)];
+  assert.deepEqual(groupsFromTuples(tuples), [
+    { memberCount: 1, name: "design" },
+    { memberCount: 3, name: "eng" },
+  ]);
+});
+
+test("memberView resolves a user subject to its email (else the raw id) and a subject_set to the group", () => {
+  const emails = new Map([[uid(1), "ada@example.com"]]);
+  assert.deepEqual(memberView(userTuple("eng", 1), emails), { kind: "user", label: "ada@example.com", subject: `user:${uid(1)}` });
+  assert.deepEqual(memberView(userTuple("eng", 9), emails), { kind: "user", label: `user:${uid(9)}`, subject: `user:${uid(9)}` });
+  assert.deepEqual(memberView(groupTuple("eng", "design"), emails), { kind: "group", label: "design", subject: "group:design" });
+});
+
+test("buildGroupsListModel filters by search, sorts, paginates; the name links to the detail page", () => {
+  const groups = Array.from({ length: 30 }, (_, i) => ({ memberCount: i + 1, name: `team-${String(i).padStart(2, "0")}` }));
+
+  const all = buildGroupsListModel({ groups, url: "http://x/admin/groups" });
+  assert.equal(all.pagination.summary.total, 30);
+  assert.equal(all.table.rows.length, 25); // default page size
+  assert.equal(all.title, "Groups");
+  // The group name is the row header, linking to its detail page.
+  const first = all.table.rows[0]!.cells[0] as { rowHeader: { href: string; text: string } };
+  assert.equal(first.rowHeader.text, "team-00");
+  assert.equal(first.rowHeader.href, "/admin/groups/team-00");
+
+  // Search narrows + shows a pill.
+  const one = buildGroupsListModel({ groups, url: "http://x/admin/groups?q=team-07" });
+  assert.equal(one.pagination.summary.total, 1);
+  assert.deepEqual(one.filterBar.pills.map((p) => p.label), ["Search"]);
+
+  // Sort by members descending puts the biggest group first.
+  const desc = buildGroupsListModel({ groups, url: "http://x/admin/groups?sort=-members" });
+  assert.equal((desc.table.rows[0]!.cells[0] as { rowHeader: { text: string } }).rowHeader.text, "team-29");
+});
+
+test("buildGroupFormModel: a create form with a required name field + member options, no group of its own", () => {
+  const options = [{ label: "ada@example.com", value: `user:${uid(1)}` }, { label: "eng (group)", value: "group:eng" }];
+  const m = buildGroupFormModel({ csrfToken: "tok.sig", memberOptions: options });
+  assert.equal(m.title, "New group");
+  assert.equal(m.form.action, "/admin/groups");
+  assert.equal(m.form.submitLabel, "Create group");
+  assert.equal(m.form.csrfToken, "tok.sig");
+  assert.equal(m.form.nameField.name, "name");
+  assert.equal(m.form.nameField.required, true);
+  assert.deepEqual(m.form.memberOptions, options);
+
+  // An error (e.g. a taken/invalid name) re-renders with the submitted values.
+  const err = buildGroupFormModel({ error: "That name is taken.", memberOptions: options, values: { member: "group:eng", name: "Eng" } });
+  assert.equal(err.error, "That name is taken.");
+  assert.equal(err.form.nameField.value, "Eng");
+  assert.equal(err.form.selectedMember, "group:eng");
+});
+
+test("buildGroupDetailModel: members → rows, add-options exclude current members + the group itself, delete/remove wired", () => {
+  const members = [memberView(userTuple("eng", 1), new Map([[uid(1), "ada@example.com"]])), memberView(groupTuple("eng", "design"), 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: "design (group)", value: "group:design" }, // already a member → excluded
+    { label: "eng (group)", value: "group:eng" }, // the group itself → excluded
+    { label: "ops (group)", value: "group:ops" },
+  ];
+  const m = buildGroupDetailModel({ candidates, group: { name: "eng" }, members });
+  assert.equal(m.title, "eng");
+  assert.equal(m.members.rows.length, 2);
+  assert.equal(m.members.action, "/admin/groups/eng/members/delete");
+  assert.equal(m.add.action, "/admin/groups/eng/members");
+  assert.deepEqual(m.add.options.map((o) => o.value), [`user:${uid(2)}`, "group:ops"]);
+  assert.equal(m.delete.action, "/admin/groups/eng/delete");
+});

examples/plugins/admin/admin-groups.ts

@@ -0,0 +1,374 @@
+// Groups admin screen: list / create / delete Keto groups and manage membership.
+// A group is a Keto subject set `Group:<name>#members`; a member is a user or a nested group (see
+// parseSubject). Writes go only to Keto (README "stateless"). Keto has no "create object" — a group
+// exists exactly while it has ≥1 member, so create writes its first-member tuple and delete removes
+// every member tuple. Pure builders turn tuples + the request URL into view models; below them are thin
+// per-route handlers (keyed on ctx.params) over a shared `withGroups` gate — admin-only, CSRF-guarded,
+// each returning a RouteResult.
+
+import { type KetoClient, type KratosAdmin, paginate, parseListQuery, type RelationQuery, type RelationTuple, type RequestContext, type RouteHandler, type RouteResult, type SubjectSet, type User } from "#plugin-api";
+import { ADMIN_GROUPS_BASE, buildConfirmModel, guardedForm, notFound, requireAdmin, unavailable } from "./admin-shared.ts";
+import type { FieldConfig } from "./admin-users.ts";
+
+const GROUP_NS = "Group";
+const MEMBERS = "members";
+const DEFAULT_PAGE_SIZE = 25;
+const PAGE_SIZES = [25, 50, 100];
+// One Keto page of candidate users is fetched for the member pickers (mirrors admin-users).
+const LIST_FETCH_SIZE = 250;
+const GROUP_NAME = /^[a-z0-9][a-z0-9_-]*$/; // URL-safe; doubles as the path segment
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i; // a Kratos identity id
+
+export interface GroupView {
+  memberCount: number;
+  name: string;
+}
+
+// A member's view model: a user (label = email) or a nested group (label = group name). `subject`
+// is the form value that round-trips it — `user:<id>` or `group:<name>` (see parseSubject).
+export interface MemberView {
+  kind: "group" | "user";
+  label: string;
+  subject: string;
+}
+
+// One option in a member <select>.
+export interface MemberOption {
+  label: string;
+  value: string; // `user:<id>` | `group:<name>`
+}
+
+export function isValidGroupName(name: string): boolean {
+  return name.length <= 64 && GROUP_NAME.test(name);
+}
+
+// Map a member-picker value → the Keto subject (subject_id for a user, subject_set for a nested
+// group). Returns null for anything unrecognised (a crafted/empty POST).
+export function parseSubject(value: string): { subject_id: string } | { subject_set: SubjectSet } | null {
+  const sep = value.indexOf(":");
+  if (sep <= 0) return null;
+  const rest = value.slice(sep + 1);
+  if (!rest) return null;
+  // Validate both subject forms so a crafted POST can't write a dangling tuple (the pickers only
+  // ever offer real users/groups): a user id is a Kratos UUID, a nested group a valid group name.
+  if (value.slice(0, sep) === "user") return UUID.test(rest) ? { subject_id: `user:${rest}` } : null;
+  if (value.slice(0, sep) === "group") return isValidGroupName(rest) ? { subject_set: { namespace: GROUP_NS, object: rest, relation: MEMBERS } } : null;
+  return null;
+}
+
+// The full membership tuple for adding/removing `value` to/from `group` (null if value is invalid).
+export function memberTuple(group: string, value: string): RelationTuple | null {
+  const subject = parseSubject(value);
+  return subject ? { namespace: GROUP_NS, object: group, relation: MEMBERS, ...subject } : null;
+}
+
+// Collapse the namespace's membership tuples → distinct groups + member counts, sorted by name.
+export function groupsFromTuples(tuples: RelationTuple[]): GroupView[] {
+  const counts = new Map<string, number>();
+  for (const t of tuples) counts.set(t.object, (counts.get(t.object) ?? 0) + 1);
+  return [...counts].map(([name, memberCount]) => ({ memberCount, name })).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function memberView(tuple: RelationTuple, emailById: Map<string, string>): MemberView {
+  if (tuple.subject_set) return { kind: "group", label: tuple.subject_set.object, subject: `group:${tuple.subject_set.object}` };
+  const subjectId = tuple.subject_id ?? "";
+  const id = subjectId.startsWith("user:") ? subjectId.slice("user:".length) : subjectId;
+  return { kind: "user", label: emailById.get(id) ?? subjectId, subject: subjectId };
+}
+
+// ---- list view model ----
+
+interface ListState {
+  page: number;
+  pageSize: number;
+  q: string;
+  sort: string | null;
+}
+
+const SORT: Record<string, (g: GroupView) => number | string> = {
+  members: (g) => g.memberCount,
+  name: (g) => g.name,
+};
+const COLUMNS = [
+  { key: "name", label: "Group" },
+  { key: "members", label: "Members" },
+];
+
+function detailHref(name: string): string {
+  return `${ADMIN_GROUPS_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_GROUPS_BASE}?${qs}` : ADMIN_GROUPS_BASE;
+}
+
+export function buildGroupsListModel(opts: {
+  csrfToken?: string;
+  groups: GroupView[];
+  url: URL | URLSearchParams | string;
+}) {
+  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.groups.filter((g) => !needle || g.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 {
+    breadcrumbs: [{ href: ADMIN_GROUPS_BASE, label: "Admin" }, { label: "Groups" }],
+    filterBar: listFilterBar(state),
+    pagination: listPagination(state, page),
+    table: listTable(rows, state, sort),
+    title: "Groups",
+  };
+}
+
+function listTable(rows: GroupView[], state: ListState, sort: { dir: "asc" | "desc"; field: string } | null) {
+  return {
+    caption: "Groups",
+    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((g) => ({
+      cells: [{ rowHeader: { href: detailHref(g.name), text: g.name } }, String(g.memberCount)],
+      name: g.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_GROUPS_BASE,
+    label: "Filter groups",
+    pills,
+    rows: [[
+      { label: "Search groups", name: "q", placeholder: "Search group 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: "Groups 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 buildGroupFormModel(opts: {
+  csrfToken?: string;
+  error?: string;
+  memberOptions: MemberOption[];
+  values?: { member?: string; name?: string };
+}) {
+  const nameField: FieldConfig = {
+    autocomplete: "off", hint: "Lowercase letters, digits, dashes and underscores.", icon: "i-layers",
+    id: "name", label: "Group name", name: "name", required: true, value: opts.values?.name ?? "",
+  };
+  return {
+    breadcrumbs: [{ href: ADMIN_GROUPS_BASE, label: "Groups" }, { label: "New" }],
+    error: opts.error,
+    form: {
+      action: ADMIN_GROUPS_BASE,
+      cancelHref: ADMIN_GROUPS_BASE,
+      csrfToken: opts.csrfToken ?? "",
+      memberOptions: opts.memberOptions,
+      nameField,
+      selectedMember: opts.values?.member ?? "",
+      submitLabel: "Create group",
+    },
+    title: "New group",
+  };
+}
+
+export function buildGroupDetailModel(opts: {
+  candidates: MemberOption[];
+  csrfToken?: string;
+  error?: string;
+  group: { name: string };
+  members: MemberView[];
+}) {
+  const name = opts.group.name;
+  const base = detailHref(name);
+  const taken = new Set(opts.members.map((m) => m.subject));
+  const self = `group:${name}`; // a group can't be a member of itself
+  const options = opts.candidates.filter((c) => c.value !== self && !taken.has(c.value));
+  return {
+    add: { action: `${base}/members`, options },
+    breadcrumbs: [{ href: ADMIN_GROUPS_BASE, label: "Groups" }, { label: name }],
+    csrfToken: opts.csrfToken ?? "",
+    delete: { action: `${base}/delete` },
+    error: opts.error,
+    group: { name },
+    members: { action: `${base}/members/delete`, rows: opts.members },
+    title: name,
+  };
+}
+
+// ---- request handler (imperative shell) ----
+
+// 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 {
+    const page = await keto.listRelations({ ...query, ...(pageToken ? { pageToken } : {}) });
+    out.push(...page.tuples);
+    pageToken = page.nextPageToken ?? undefined;
+  } while (pageToken);
+  return out;
+}
+
+// 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.
+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[] = [];
+  for (const it of identities) {
+    const trait = it.traits?.["email"];
+    const email = typeof trait === "string" ? trait : it.id;
+    emailById.set(it.id, email);
+    userOptions.push({ label: email, value: `user:${it.id}` });
+  }
+  const groups = groupsFromTuples(await pagedTuples(keto, { namespace: GROUP_NS, relation: MEMBERS }));
+  return { emailById, options: [...userOptions, ...groups.map((g) => ({ label: `${g.name} (group)`, value: `group:${g.name}` }))] };
+}
+
+// A group exists exactly while it has ≥1 member.
+async function groupExists(keto: KetoClient, name: string): Promise<boolean> {
+  const page = await keto.listRelations({ namespace: GROUP_NS, object: name, relation: MEMBERS, pageSize: 1 });
+  return page.tuples.length > 0;
+}
+
+// Shared per-request deps for the Groups screen, resolved by `withGroups`: the gate + the Keto and
+// Kratos capabilities (else a themed 503). Each route below is a thin handler over these.
+interface GroupsDeps { ctx: RequestContext; keto: KetoClient; kratosAdmin: KratosAdmin; user: User; }
+
+function withGroups(inner: (deps: GroupsDeps) => Promise<RouteResult>): RouteHandler {
+  return async (ctx) => {
+    const user = requireAdmin(ctx);
+    const keto = ctx.system?.keto;
+    const kratosAdmin = ctx.system?.kratosAdmin;
+    if (!keto || !kratosAdmin) return unavailable(ctx, "Keto and Kratos identity admin");
+    return inner({ ctx, keto, kratosAdmin, user });
+  };
+}
+
+// Same, plus the validated :name from ctx.params (an invalid group name → themed 404).
+function withGroupName(inner: (deps: GroupsDeps, name: string) => Promise<RouteResult>): RouteHandler {
+  return withGroups((deps) => {
+    const name = deps.ctx.params["name"] ?? "";
+    if (!isValidGroupName(name)) return Promise.resolve(notFound(deps.ctx));
+    return inner(deps, name);
+  });
+}
+
+const groupFormResult = async (deps: GroupsDeps, extra: { error?: string; values?: { member?: string; name?: string } }): Promise<RouteResult> => {
+  const { options } = await memberCandidates(deps.keto, deps.kratosAdmin);
+  return { data: { chrome: deps.ctx.chrome, model: buildGroupFormModel({ csrfToken: deps.ctx.chrome.csrfToken, memberOptions: options, ...extra }) }, view: "group-form" };
+};
+
+// GET /admin/groups — the list.
+export const groupsList = withGroups(async ({ ctx, keto }) => {
+  const groups = groupsFromTuples(await pagedTuples(keto, { namespace: GROUP_NS, relation: MEMBERS }));
+  return { data: { chrome: ctx.chrome, model: buildGroupsListModel({ csrfToken: ctx.chrome.csrfToken, groups, url: ctx.url }) }, view: "groups" };
+});
+
+// POST /admin/groups — create (a group exists once it has ≥1 member, so this writes the first tuple).
+export const groupsCreate = withGroups(async (deps) => {
+  const { ctx, keto, user } = deps;
+  const form = (await guardedForm(ctx))!;
+  const name = (form.get("name") ?? "").trim();
+  const member = (form.get("member") ?? "").trim();
+  const tuple = memberTuple(name, member);
+  const reject = async (error: string): Promise<RouteResult> => ({ ...(await groupFormResult(deps, { error, values: { member, name } })), status: 400 });
+  if (!isValidGroupName(name)) return reject("Group names use lowercase letters, digits, dashes and underscores.");
+  if (!tuple) return reject("Pick a member to add as the group's first member.");
+  if (await groupExists(keto, name)) return reject("A group with that name already exists.");
+  await keto.writeTuple(tuple);
+  ctx.log.info("admin: group created", { actor: user.id, group: name });
+  return { redirect: detailHref(name) };
+});
+
+// GET /admin/groups/new — the create form.
+export const groupsNewForm = withGroups((deps) => groupFormResult(deps, {}));
+
+// GET /admin/groups/:name — the detail + membership page.
+export const groupsDetail = withGroupName(async ({ ctx, keto, kratosAdmin }, name) => {
+  const { emailById, options } = await memberCandidates(keto, kratosAdmin);
+  const members = (await pagedTuples(keto, { namespace: GROUP_NS, object: name, relation: MEMBERS })).map((t) => memberView(t, emailById));
+  return { data: { chrome: ctx.chrome, model: buildGroupDetailModel({ candidates: options, csrfToken: ctx.chrome.csrfToken, group: { name }, members }) }, view: "group-detail" };
+});
+
+// POST /admin/groups/:name/members — add a member (skip an invalid member or a self-nest).
+export const groupsAddMember = withGroupName(async ({ ctx, keto }, name) => {
+  const form = (await guardedForm(ctx))!;
+  const tuple = memberTuple(name, (form.get("member") ?? "").trim());
+  if (tuple && tuple.subject_set?.object !== name) await keto.writeTuple(tuple);
+  return { redirect: detailHref(name) };
+});
+
+// GET /admin/groups/:name/delete — the deliberate confirm step.
+export const groupsDeleteConfirm = withGroupName((deps, name) => {
+  const base = detailHref(name);
+  return Promise.resolve({ data: { chrome: deps.ctx.chrome, model: buildConfirmModel({
+    breadcrumbs: [{ href: ADMIN_GROUPS_BASE, label: "Groups" }, { href: base, label: name }, { label: "Delete" }],
+    cancelHref: base, confirmAction: `${base}/delete`, confirmLabel: "Delete group",
+    message: `Delete group ${name}? This removes the group and all its memberships.`, title: "Delete group",
+  }) }, view: "confirm" });
+});
+
+// POST /admin/groups/:name/delete — remove every member tuple (the group ceases to exist).
+export const groupsDelete = withGroupName(async ({ ctx, keto, user }, name) => {
+  await guardedForm(ctx); // CSRF-verify the POST
+  await keto.deleteTuple({ namespace: GROUP_NS, object: name, relation: MEMBERS });
+  ctx.log.info("admin: group deleted", { actor: user.id, group: name });
+  return { redirect: ADMIN_GROUPS_BASE };
+});
+
+// POST /admin/groups/:name/members/delete — remove one member.
+export const groupsRemoveMember = withGroupName(async ({ ctx, keto }, name) => {
+  const form = (await guardedForm(ctx))!;
+  const tuple = memberTuple(name, (form.get("member") ?? "").trim());
+  if (tuple) await keto.deleteTuple(tuple);
+  return { redirect: detailHref(name) };
+});

examples/plugins/admin/admin-roles.test.ts

@@ -0,0 +1,106 @@
+// Built-in Roles & permissions admin screen: 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 "#plugin-api";
+
+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.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.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.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");
+});

examples/plugins/admin/admin-roles.ts

@@ -0,0 +1,367 @@
+// Roles & permissions admin screen: 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
+// Groups screen's membership model, so the pure helpers (parseSubject, member pickers, tuple paging)
+// are reused from admin-groups. The role-specific piece is the **effective access** view:
+// `keto.expand(Role:<name>#members)` flattened to the distinct users who hold the role directly or via
+// a group — matching what login projects into the JWT (login.ts readRoles). Writes go only to Keto;
+// Kratos is read only to label members. Below the builders are thin per-route handlers (keyed on
+// ctx.params) over a shared `withRoles` gate — admin-only, CSRF-guarded.
+
+import { type ExpandTree, type KetoClient, type KratosAdmin, paginate, parseListQuery, type RelationTuple, type RequestContext, type RouteHandler, type RouteResult, type User } from "#plugin-api";
+import { ADMIN_PERMISSION, ADMIN_ROLES_BASE, buildConfirmModel, guardedForm, notFound, requireAdmin, unavailable } from "./admin-shared.ts";
+import {
+  type GroupView,
+  groupsFromTuples,
+  isValidGroupName,
+  memberCandidates,
+  type MemberOption,
+  type MemberView,
+  memberView,
+  pagedTuples,
+  parseSubject,
+} from "./admin-groups.ts";
+import type { FieldConfig } from "./admin-users.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;
+  roles: RoleView[];
+  url: URL | URLSearchParams | string;
+}) {
+  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 {
+    breadcrumbs: [{ href: ADMIN_ROLES_BASE, label: "Admin" }, { label: "Roles" }],
+    filterBar: listFilterBar(state),
+    pagination: listPagination(state, page),
+    table: listTable(rows, state, sort),
+    title: "Roles",
+  };
+}
+
+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[];
+  values?: { member?: string; name?: string };
+}) {
+  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 {
+    breadcrumbs: [{ href: ADMIN_ROLES_BASE, label: "Roles" }, { label: "New" }],
+    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",
+    },
+    title: "New role",
+  };
+}
+
+export function buildRoleDetailModel(opts: {
+  candidates: MemberOption[];
+  csrfToken?: string;
+  effective: EffectiveUser[];
+  error?: string;
+  members: MemberView[];
+  role: { name: string };
+}) {
+  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 },
+    breadcrumbs: [{ href: ADMIN_ROLES_BASE, label: "Roles" }, { label: name }],
+    csrfToken: opts.csrfToken ?? "",
+    delete: { action: `${base}/delete` },
+    effective: opts.effective,
+    error: opts.error,
+    members: { action: `${base}/members/delete`, rows: opts.members },
+    role: { name },
+    title: name,
+  };
+}
+
+// ---- request handler (imperative shell) ----
+
+// instant-revoke: a role change for a `user:<id>` member must take effect now, so revoke that
+// user's live tokens (a re-mint then re-reads roles from Keto). A `group:<name>` change is
+// transitive across many users — left to lag (documented), so only direct user members revoke.
+function revokeUserMember(revoke: ((sub: string) => void) | undefined, member: string): void {
+  if (revoke && member.startsWith("user:")) revoke(member.slice("user:".length));
+}
+
+// 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));
+}
+
+// Shared per-request deps for the Roles screen, resolved by `withRoles`: the gate + the Keto and
+// Kratos capabilities (else a themed 503). Each route below is a thin handler over these.
+interface RolesDeps { ctx: RequestContext; keto: KetoClient; kratosAdmin: KratosAdmin; revoke: ((sub: string) => void) | undefined; user: User; }
+
+function withRoles(inner: (deps: RolesDeps) => Promise<RouteResult>): RouteHandler {
+  return async (ctx) => {
+    const user = requireAdmin(ctx);
+    const keto = ctx.system?.keto;
+    const kratosAdmin = ctx.system?.kratosAdmin;
+    if (!keto || !kratosAdmin) return unavailable(ctx, "Keto and Kratos identity admin");
+    return inner({ ctx, keto, kratosAdmin, revoke: ctx.system?.revoke, user });
+  };
+}
+
+// Same, plus the validated :name from ctx.params (an invalid role name → themed 404).
+function withRoleName(inner: (deps: RolesDeps, name: string) => Promise<RouteResult>): RouteHandler {
+  return withRoles((deps) => {
+    const name = deps.ctx.params["name"] ?? "";
+    if (!isValidRoleName(name)) return Promise.resolve(notFound(deps.ctx));
+    return inner(deps, name);
+  });
+}
+
+const roleFormResult = async (deps: RolesDeps, extra: { error?: string; values?: { member?: string; name?: string } }): Promise<RouteResult> => {
+  const { options } = await memberCandidates(deps.keto, deps.kratosAdmin);
+  return { data: { chrome: deps.ctx.chrome, model: buildRoleFormModel({ csrfToken: deps.ctx.chrome.csrfToken, memberOptions: options, ...extra }) }, view: "role-form" };
+};
+
+// The role detail (members + effective access). With `error` set it's a 400 (a rejected action).
+const roleDetailResult = async (deps: RolesDeps, name: string, error?: string): Promise<RouteResult> => {
+  const { emailById, options } = await memberCandidates(deps.keto, deps.kratosAdmin);
+  const tuples = await pagedTuples(deps.keto, { namespace: ROLE_NS, object: name, relation: MEMBERS });
+  const members = tuples.map((t) => memberView(t, emailById));
+  const effective = await effectiveUsers(deps.keto, name, tuples.length > 0, emailById);
+  const result: RouteResult = { data: { chrome: deps.ctx.chrome, model: buildRoleDetailModel({ candidates: options, csrfToken: deps.ctx.chrome.csrfToken, effective, members, role: { name }, ...(error ? { error } : {}) }) }, view: "role-detail" };
+  return error ? { ...result, status: 400 } : result;
+};
+
+// GET /admin/roles — the list.
+export const rolesList = withRoles(async ({ ctx, keto }) => {
+  const roles = rolesFromTuples(await pagedTuples(keto, { namespace: ROLE_NS, relation: MEMBERS }));
+  return { data: { chrome: ctx.chrome, model: buildRolesListModel({ csrfToken: ctx.chrome.csrfToken, roles, url: ctx.url }) }, view: "roles" };
+});
+
+// POST /admin/roles — create + assign the first member (a *user* grant revokes their live tokens).
+export const rolesCreate = withRoles(async (deps) => {
+  const { ctx, keto, revoke, user } = deps;
+  const form = (await guardedForm(ctx))!;
+  const name = (form.get("name") ?? "").trim();
+  const member = (form.get("member") ?? "").trim();
+  const tuple = roleMemberTuple(name, member);
+  const reject = async (error: string): Promise<RouteResult> => ({ ...(await roleFormResult(deps, { error, values: { member, name } })), 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);
+  revokeUserMember(revoke, member);
+  ctx.log.info("admin: role created + first member assigned", { actor: user.id, member, role: name });
+  return { redirect: detailHref(name) };
+});
+
+// GET /admin/roles/new — the create form.
+export const rolesNewForm = withRoles((deps) => roleFormResult(deps, {}));
+
+// GET /admin/roles/:name — the detail (members + effective access via Keto expand).
+export const rolesDetail = withRoleName((deps, name) => roleDetailResult(deps, name));
+
+// POST /admin/roles/:name/members — assign a user/group; a *user* grant revokes their live tokens.
+export const rolesAddMember = withRoleName(async (deps, name) => {
+  const { ctx, keto, revoke, user } = deps;
+  const form = (await guardedForm(ctx))!;
+  const member = (form.get("member") ?? "").trim();
+  const tuple = roleMemberTuple(name, member); // the picker only offers real users/groups
+  if (tuple) { await keto.writeTuple(tuple); revokeUserMember(revoke, member); ctx.log.info("admin: role assigned", { actor: user.id, member, role: name }); }
+  return { redirect: detailHref(name) };
+});
+
+// GET /admin/roles/:name/delete — confirm, except the admin role can't be deleted.
+export const rolesDeleteConfirm = withRoleName((deps, name) => {
+  if (name === ADMIN_PERMISSION) return roleDetailResult(deps, name, "The admin role can't be deleted — it would remove all admin access.");
+  const base = detailHref(name);
+  return Promise.resolve({ data: { chrome: deps.ctx.chrome, model: buildConfirmModel({
+    breadcrumbs: [{ href: ADMIN_ROLES_BASE, label: "Roles" }, { href: base, label: name }, { label: "Delete" }],
+    cancelHref: base, confirmAction: `${base}/delete`, confirmLabel: "Delete role",
+    message: `Delete role ${name}? This revokes it from everyone it's assigned to.`, title: "Delete role",
+  }) }, view: "confirm" });
+});
+
+// POST /admin/roles/:name/delete — remove every member tuple (a whole-role delete lags per the
+// documented instant-revoke tradeoff; the admin role is protected).
+export const rolesDelete = withRoleName(async (deps, name) => {
+  const { ctx, keto, user } = deps;
+  await guardedForm(ctx); // CSRF-verify the POST
+  if (name === ADMIN_PERMISSION) return roleDetailResult(deps, name, "The admin role can't be deleted — it would remove all admin access.");
+  await keto.deleteTuple({ namespace: ROLE_NS, object: name, relation: MEMBERS });
+  ctx.log.info("admin: role deleted", { actor: user.id, role: name });
+  return { redirect: ADMIN_ROLES_BASE };
+});
+
+// POST /admin/roles/:name/members/delete — unassign; a *user* unassign revokes their live tokens.
+// Self-protection: an admin can't revoke their own *direct* admin grant (a group-held admin isn't
+// covered — the robust "last effective admin" check is deferred).
+export const rolesRemoveMember = withRoleName(async (deps, name) => {
+  const { ctx, keto, revoke, user } = deps;
+  const form = (await guardedForm(ctx))!;
+  const member = (form.get("member") ?? "").trim();
+  if (name === ADMIN_PERMISSION && member === `user:${user.id}`) return roleDetailResult(deps, name, "You can't revoke your own admin access.");
+  const tuple = roleMemberTuple(name, member);
+  if (tuple) { await keto.deleteTuple(tuple); revokeUserMember(revoke, member); ctx.log.info("admin: role unassigned", { actor: user.id, member, role: name }); }
+  return { redirect: detailHref(name) };
+});

examples/plugins/admin/admin-shared.test.ts

@@ -0,0 +1,70 @@
+// Direct units for the admin plugin's shared nav + auth helpers. They're security-critical
+// (requireAdmin/guardedForm gate every admin write) and reused across all four screens, so pin the
+// contract here in isolation; the HTTP routing/gate/CSRF is exercised end-to-end in src/http/app.test.ts.
+// Import only from the #plugin-api barrel — the same contract boundary the plugin code uses.
+import assert from "node:assert/strict";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { Readable } from "node:stream";
+import { test } from "node:test";
+import { GuardError, type Log, type PageChrome, type RequestContext, type User } from "#plugin-api";
+import { ADMIN_NAV, ADMIN_PERMISSION, ADMIN_USERS_BASE, buildConfirmModel, guardedForm, requireAdmin } from "./admin-shared.ts";
+
+const admin: User = { email: "ada@x.io", id: "u1", roles: ["admin"] };
+const member: User = { email: "bo@x.io", id: "u2", roles: ["scheduling:read"] };
+const CHROME = { brand: { name: "Test" }, csrfToken: "tok", nav: [], signInHref: "/login", user: { email: "", initials: "T", name: "Tester" } } as PageChrome;
+
+function fakeCtx(opts: { body?: string; method?: string; user?: User | null; verifyCsrf?: (s: string | null | undefined) => boolean } = {}): RequestContext {
+  const url = new URL("http://localhost/admin/users");
+  const req = Readable.from(opts.body != null ? [Buffer.from(opts.body)] : []) as unknown as IncomingMessage;
+  req.method = opts.method ?? "GET";
+  return {
+    chrome: CHROME, log: {} as Log, params: {}, query: url.searchParams, req, res: {} as ServerResponse,
+    roles: opts.user?.roles ?? [], url, user: opts.user ?? null, verifyCsrf: opts.verifyCsrf ?? (() => true),
+  };
+}
+
+// ---- nav fragment ----
+
+test("ADMIN_NAV: a gated Admin header over the four screens; no per-request current/open state", () => {
+  assert.equal(ADMIN_NAV.id, "admin");
+  assert.equal(ADMIN_NAV.permission, ADMIN_PERMISSION); // gate on the header ⇒ composeNav drops the whole subtree for a non-admin
+  assert.equal(ADMIN_NAV.open, undefined); // the host current-marks + opens; the fragment stays static
+  assert.deepEqual(ADMIN_NAV.children?.map((c) => c.href), ["/admin/users", "/admin/groups", "/admin/roles", "/admin/clients"]);
+  assert.deepEqual(ADMIN_NAV.children?.map((c) => c.label), ["Users", "Groups", "Roles", "OAuth2 clients"]);
+  assert.ok(ADMIN_NAV.children?.every((c) => c.current === undefined && c.permission === undefined)); // the header's gate covers the subtree
+});
+
+// ---- auth gates ----
+
+test("requireAdmin: anonymous → 401→/login, signed-in non-admin → 403, admin → the user", () => {
+  assert.throws(() => requireAdmin(fakeCtx({ user: null })), (e: unknown) => e instanceof GuardError && e.status === 401 && e.location === "/login?return_to=%2Fadmin%2Fusers"); // bounce remembers the page
+  assert.throws(() => requireAdmin(fakeCtx({ user: member })), (e: unknown) => e instanceof GuardError && e.status === 403);
+  assert.equal(requireAdmin(fakeCtx({ user: admin })), admin);
+});
+
+test("guardedForm: valid double-submit → the parsed body, bad token → 403, non-POST → undefined", async () => {
+  const post = (over: { body?: string; verifyCsrf?: (s: string | null | undefined) => boolean }) => fakeCtx({ method: "POST", ...over });
+
+  const ok = await guardedForm(post({ body: "_csrf=tok&name=Bo", verifyCsrf: () => true }));
+  assert.equal(ok?.get("name"), "Bo");
+
+  await assert.rejects(guardedForm(post({ body: "_csrf=nope&name=Bo", verifyCsrf: () => false })), // ctx.verifyCsrf rejects
+    (e: unknown) => e instanceof GuardError && e.status === 403);
+
+  assert.equal(await guardedForm(fakeCtx({ method: "GET" })), undefined); // not a mutation → no gate, no body read
+});
+
+// ---- confirm-page model ----
+
+test("buildConfirmModel wires the danger action, message, breadcrumbs and title (shell comes from ctx.chrome)", () => {
+  const model = buildConfirmModel({
+    breadcrumbs: [{ href: ADMIN_USERS_BASE, label: "Users" }, { label: "Delete" }],
+    cancelHref: ADMIN_USERS_BASE, confirmAction: `${ADMIN_USERS_BASE}/u1/delete`, confirmLabel: "Delete user",
+    message: "Delete ada@x.io?", title: "Delete user",
+  });
+  assert.deepEqual(model.confirm, { action: `${ADMIN_USERS_BASE}/u1/delete`, label: "Delete user" });
+  assert.equal(model.message, "Delete ada@x.io?");
+  assert.equal(model.cancelHref, ADMIN_USERS_BASE);
+  assert.equal(model.title, "Delete user");
+  assert.deepEqual(model.breadcrumbs.at(-1), { label: "Delete" });
+});

examples/plugins/admin/admin-shared.ts

@@ -0,0 +1,78 @@
+// Shared plumbing for the admin example plugin: the section nav fragment, the admin-only gate, the
+// CSRF-guarded form reader, the destructive-confirm model builder, and small RouteResult helpers
+// (themed not-found / capability-unavailable). Ported from the former built-in admin screens;
+// everything imports the host only through the #plugin-api barrel.
+
+import { can, CSRF_FIELD, GuardError, type NavNode, readFormBody, type RequestContext, requireSession, type RouteResult, type User } from "#plugin-api";
+
+export const ADMIN_PERMISSION = "admin"; // role token gating the whole admin section
+export const ADMIN_USERS_BASE = "/admin/users";
+export const ADMIN_GROUPS_BASE = "/admin/groups";
+export const ADMIN_ROLES_BASE = "/admin/roles";
+export const ADMIN_CLIENTS_BASE = "/admin/clients";
+
+export type AdminScreen = "clients" | "groups" | "roles" | "users";
+
+// The plugin's nav fragment: the gated "Admin" header + its four screens. The host composes it into
+// the one global menu, filters per user (the header's `permission` drops the whole subtree for a
+// non-admin), and current-marks the active item — so there is no `current`/`open` state here.
+export const ADMIN_NAV: NavNode = {
+  children: [
+    { href: ADMIN_USERS_BASE, icon: "i-users", id: "users", label: "Users" },
+    { href: ADMIN_GROUPS_BASE, icon: "i-layers", id: "groups", label: "Groups" },
+    { href: ADMIN_ROLES_BASE, icon: "i-shield", id: "roles", label: "Roles" },
+    { href: ADMIN_CLIENTS_BASE, icon: "i-globe", id: "clients", label: "OAuth2 clients" },
+  ],
+  icon: "i-shield",
+  id: "admin",
+  label: "Admin",
+  permission: ADMIN_PERMISSION,
+};
+
+// The admin gate: a signed-in admin only. Each route already declares `permission: "admin"`, so the
+// host enforces this before the handler runs; this is defence-in-depth and what a direct unit test
+// relies on. Returns the (non-null) user for the handler to thread on. GuardError → /login or 403.
+export function requireAdmin(ctx: RequestContext): User {
+  const user = requireSession(ctx); // anonymous → GuardError → /login (return_to kept)
+  if (!can(ctx, ADMIN_PERMISSION)) throw new GuardError(403, "admin role required");
+  return user;
+}
+
+// Read + CSRF-verify a mutation's form body once (double-submit via ctx.verifyCsrf); non-POST ⇒
+// undefined. A POST without a valid token is refused (GuardError → 403).
+export async function guardedForm(ctx: RequestContext): Promise<URLSearchParams | undefined> {
+  if ((ctx.req.method ?? "GET").toUpperCase() !== "POST") return undefined;
+  const form = await readFormBody(ctx.req);
+  if (!ctx.verifyCsrf(form.get(CSRF_FIELD))) throw new GuardError(403, "invalid CSRF token");
+  return form;
+}
+
+// A themed "not found" (bad id/name in the path) rendered in the admin shell — 404, never a 500.
+export function notFound(ctx: RequestContext): RouteResult {
+  return { data: { chrome: ctx.chrome, message: "That item doesn't exist.", title: "Not found" }, status: 404, view: "notice" };
+}
+
+// A capability the plugin needs isn't on ctx.system (Ory not wired). Login already requires these in
+// a real deployment, so this is the honest 503 fallback for a misconfigured host, not a crash.
+export function unavailable(ctx: RequestContext, what: string): RouteResult {
+  return { data: { chrome: ctx.chrome, message: `${what} is not configured on this deployment.`, title: "Admin unavailable" }, status: 503, view: "notice" };
+}
+
+// Model for the shared destructive-confirm page (views/confirm.ejs). The view reads the shell fields
+// (brand/csrf/theme/user/nav) from ctx.chrome; this carries only the page body + title/breadcrumbs.
+export function buildConfirmModel(opts: {
+  breadcrumbs: { href?: string; label: string }[];
+  cancelHref: string;
+  confirmAction: string;
+  confirmLabel: string;
+  message: string;
+  title: string;
+}) {
+  return {
+    breadcrumbs: opts.breadcrumbs,
+    cancelHref: opts.cancelHref,
+    confirm: { action: opts.confirmAction, label: opts.confirmLabel },
+    message: opts.message,
+    title: opts.title,
+  };
+}

examples/plugins/admin/admin-users.test.ts

@@ -0,0 +1,125 @@
+// Users admin screen (example plugin): the pure view-model + Kratos-payload builders. The HTTP
+// routing/gate/CSRF + live Kratos calls are exercised over HTTP in src/http/app.test.ts.
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import type { Identity } from "#plugin-api";
+import {
+  buildUserFormModel,
+  buildUsersListModel,
+  createIdentityPayload,
+  setStatePayload,
+  toUserView,
+  updateIdentityPayload,
+} from "./admin-users.ts";
+
+const id = (n: number) => `01902d5e-7b6c-7e3a-9f21-3c8d1e0a4b${String(n).padStart(2, "0")}`;
+const identity = (n: number, over: Partial<Identity> = {}): Identity => ({
+  id: id(n),
+  schema_id: "default",
+  state: "active",
+  traits: { email: `user${n}@example.com`, name: { first: `First${n}`, last: `Last${n}` } },
+  ...over,
+});
+
+test("toUserView maps traits → name/initials/email/state; falls back to the email local part", () => {
+  const named = toUserView(identity(1));
+  assert.equal(named.name, "First1 Last1");
+  assert.equal(named.initials, "FL");
+  assert.equal(named.email, "user1@example.com");
+  assert.equal(named.state, "active");
+
+  // No name trait → derive from the email local part.
+  const bare = toUserView({ id: id(2), state: "inactive", traits: { email: "ada.lovelace@example.com" } });
+  assert.equal(bare.name, "ada.lovelace");
+  assert.equal(bare.initials, "AD");
+  assert.equal(bare.state, "inactive");
+});
+
+test("buildUsersListModel filters by search + status, sorts, and paginates", () => {
+  const people = Array.from({ length: 30 }, (_, i) => identity(i + 1, { state: i % 2 ? "inactive" : "active" }));
+
+  const all = buildUsersListModel({ identities: people, url: "http://x/admin/users" });
+  assert.equal(all.pagination.summary.total, 30);
+  assert.equal(all.table.rows.length, 25); // default page size
+  assert.equal(all.title, "Users");
+
+  // Search narrows to one and shows a pill.
+  const one = buildUsersListModel({ identities: people, url: "http://x/admin/users?q=user7%40example.com" });
+  assert.equal(one.pagination.summary.total, 1);
+  assert.deepEqual(one.filterBar.pills.map((p) => p.label), ["Search"]);
+
+  // Status filter keeps only inactive identities.
+  const inactive = buildUsersListModel({ identities: people, url: "http://x/admin/users?status=inactive" });
+  assert.equal(inactive.pagination.summary.total, 15);
+  assert.deepEqual(inactive.filterBar.pills.map((p) => p.label), ["Status"]);
+
+  // Sort by email descending reverses the order.
+  const emailOf = (m: ReturnType<typeof buildUsersListModel>, i: number) => (m.table.rows[i]!.cells[1]) as string;
+  const desc = buildUsersListModel({ identities: people, url: "http://x/admin/users?sort=-email" });
+  assert.ok(emailOf(desc, 0) > emailOf(desc, 1));
+
+  // Edit link points at the per-identity route.
+  assert.match(all.table.rows[0]!.actions![0]!.href!, new RegExp(`/admin/users/${people[0]!.id}$`));
+});
+
+test("buildUserFormModel: create mode has an editable email + password, no edit actions", () => {
+  const m = buildUserFormModel({ csrfToken: "tok.sig" });
+  assert.equal(m.title, "New user");
+  assert.equal(m.form.action, "/admin/users");
+  assert.equal(m.form.submitLabel, "Create user");
+  assert.equal(m.form.csrfToken, "tok.sig");
+  const names = m.form.fields.map((f) => f.name);
+  assert.deepEqual(names, ["email", "first", "last", "password"]);
+  assert.equal(m.form.fields.find((f) => f.name === "email")!.readonly, undefined); // editable on create
+  assert.equal(m.edit, undefined);
+});
+
+test("buildUserFormModel: edit mode prefills, locks email, and exposes state/delete/recovery actions", () => {
+  const m = buildUserFormModel({ identity: identity(3) });
+  assert.equal(m.title, "Edit user");
+  assert.equal(m.form.action, `/admin/users/${id(3)}`);
+  assert.equal(m.form.submitLabel, "Save changes");
+  const email = m.form.fields.find((f) => f.name === "email")!;
+  assert.equal(email.value, "user3@example.com");
+  assert.equal(email.readonly, true);
+  assert.ok(!m.form.fields.some((f) => f.name === "password")); // no password field when editing
+  assert.equal(m.form.fields.find((f) => f.name === "first")!.value, "First3");
+  assert.equal(m.edit!.nextLabel, "Deactivate"); // active → offers Deactivate
+  assert.match(m.edit!.deleteAction, /\/delete$/);
+  assert.match(m.edit!.recoveryAction, /\/recovery$/);
+
+  // An inactive identity offers Reactivate.
+  assert.equal(buildUserFormModel({ identity: identity(4, { state: "inactive" }) }).edit!.nextLabel, "Reactivate");
+});
+
+test("createIdentityPayload: schema/state/traits, name only when given, password only when set", () => {
+  assert.deepEqual(createIdentityPayload({ email: "a@b.c", first: "Ada", last: "Lovelace", password: "" }), {
+    schema_id: "default",
+    state: "active",
+    traits: { email: "a@b.c", name: { first: "Ada", last: "Lovelace" } },
+  });
+  // No name parts → omit the name trait; a password → credentials.
+  assert.deepEqual(createIdentityPayload({ email: "a@b.c", first: "", last: "", password: "s3cret" }), {
+    credentials: { password: { config: { password: "s3cret" } } },
+    schema_id: "default",
+    state: "active",
+    traits: { email: "a@b.c" },
+  });
+});
+
+test("updateIdentityPayload preserves email/schema/state and rewrites the name; setStatePayload flips state", () => {
+  const existing = identity(5);
+  assert.deepEqual(updateIdentityPayload(existing, { email: "ignored@x", first: "New", last: "Name", password: "" }), {
+    schema_id: "default",
+    state: "active",
+    traits: { email: "user5@example.com", name: { first: "New", last: "Name" } }, // email kept, not the submitted one
+  });
+  // Clearing both name parts drops the name trait.
+  assert.deepEqual(updateIdentityPayload(existing, { email: "", first: "", last: "", password: "" }).traits, { email: "user5@example.com" });
+
+  assert.deepEqual(setStatePayload(existing, "inactive"), {
+    schema_id: "default",
+    state: "inactive",
+    traits: { email: "user5@example.com", name: { first: "First5", last: "Last5" } },
+  });
+});

examples/plugins/admin/admin-users.ts

@@ -0,0 +1,378 @@
+// Users admin screen: list Kratos identities (filter/sort/paginate) +
+// create/edit/deactivate/delete/trigger-recovery. Writes go only to Kratos via the admin client
+// (README "stateless"). Pure builders turn identities + the request URL into building-block view
+// models; below them are thin per-route handlers (keyed on ctx.params) over a shared `withUser` gate
+// — admin-only, CSRF-guarded, each returning a RouteResult (a view, or a redirect after a write — PRG).
+
+import { type Identity, type KratosAdmin, KratosError, paginate, parseListQuery, type RecoveryCode, type RequestContext, type RouteHandler, type RouteResult, type User } from "#plugin-api";
+import { ADMIN_USERS_BASE, buildConfirmModel, guardedForm, notFound, requireAdmin, unavailable } from "./admin-shared.ts";
+
+const SCHEMA_ID = "default"; // matches kratos.yml identity.default_schema_id
+const DEFAULT_PAGE_SIZE = 25;
+const PAGE_SIZES = [25, 50, 100];
+// One Kratos page is fetched and filtered/sorted/paged in memory — the admin API offers no
+// full-text search or sort. Ample for an admin tool; raise if a deployment outgrows it.
+const LIST_FETCH_SIZE = 250;
+const STATE_TONE: Record<string, string> = { active: "pos", inactive: "warn" };
+
+export interface UserView {
+  email: string;
+  id: string;
+  initials: string;
+  name: string;
+  state: string; // Kratos identity state: "active" | "inactive"
+}
+
+export interface UserInput {
+  email: string;
+  first: string;
+  last: string;
+  password: string;
+}
+
+const cap = (s: string): string => s.charAt(0).toUpperCase() + s.slice(1);
+
+function nameParts(identity: Identity): { first: string; last: string } {
+  const nm = ((identity.traits?.name ?? {}) as { first?: unknown; last?: unknown });
+  return {
+    first: typeof nm.first === "string" ? nm.first.trim() : "",
+    last: typeof nm.last === "string" ? nm.last.trim() : "",
+  };
+}
+
+export function toUserView(identity: Identity): UserView {
+  const email = typeof identity.traits?.email === "string" ? (identity.traits.email as string) : "";
+  const { first, last } = nameParts(identity);
+  const full = `${first} ${last}`.trim();
+  const name = full || email.split("@")[0] || email;
+  const initials = (first && last ? first[0]! + last[0]! : name.slice(0, 2) || "U").toUpperCase();
+  return { email, id: identity.id, initials, name, state: identity.state ?? "active" };
+}
+
+// ---- Kratos payloads ----
+
+export function createIdentityPayload(input: UserInput): Record<string, unknown> {
+  const traits: Record<string, unknown> = { email: input.email };
+  if (input.first || input.last) traits.name = { first: input.first, last: input.last };
+  const payload: Record<string, unknown> = { schema_id: SCHEMA_ID, state: "active", traits };
+  if (input.password) payload.credentials = { password: { config: { password: input.password } } };
+  return payload;
+}
+
+// A full-identity PUT must carry schema/state/traits. Keep the existing email (the form's email is
+// read-only) and other traits; rewrite name from the input (cleared ⇒ drop it).
+export function updateIdentityPayload(identity: Identity, input: UserInput): Record<string, unknown> {
+  const traits: Record<string, unknown> = { ...(identity.traits ?? {}) };
+  if (input.first || input.last) traits.name = { first: input.first, last: input.last };
+  else delete traits.name;
+  return { schema_id: identity.schema_id ?? SCHEMA_ID, state: identity.state ?? "active", traits };
+}
+
+export function setStatePayload(identity: Identity, state: "active" | "inactive"): Record<string, unknown> {
+  return { schema_id: identity.schema_id ?? SCHEMA_ID, state, traits: { ...(identity.traits ?? {}) } };
+}
+
+// ---- view models ----
+
+interface ListState {
+  page: number;
+  pageSize: number;
+  q: string;
+  sort: string | null;
+  status: string;
+}
+
+const SORT: Record<string, (u: UserView) => string> = {
+  email: (u) => u.email,
+  name: (u) => u.name,
+  status: (u) => u.state,
+};
+const COLUMNS = [
+  { key: "name", label: "Name" },
+  { key: "email", label: "Email" },
+  { key: "status", label: "Status" },
+];
+
+// Canonical list URL from the current state + per-link overrides; omits defaults so links stay tidy.
+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.status && s.status !== "all") p.set("status", s.status);
+  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_USERS_BASE}?${qs}` : ADMIN_USERS_BASE;
+}
+
+export function buildUsersListModel(opts: {
+  csrfToken?: string;
+  identities: Identity[];
+  url: URL | URLSearchParams | string;
+}) {
+  const query = parseListQuery(opts.url, { defaultPageSize: DEFAULT_PAGE_SIZE });
+  const status = query.filters.status?.[0] ?? "all";
+  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();
+
+  const all = opts.identities.map(toUserView);
+  let list = all.filter((u) =>
+    (!needle || u.name.toLowerCase().includes(needle) || u.email.toLowerCase().includes(needle)) &&
+    (status === "all" || u.state === status));
+  if (sort) {
+    const get = SORT[sort.field] as (u: UserView) => string;
+    const dir = sort.dir === "desc" ? -1 : 1;
+    list = [...list].sort((a, b) => get(a).localeCompare(get(b)) * 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, status };
+
+  return {
+    breadcrumbs: [{ href: ADMIN_USERS_BASE, label: "Admin" }, { label: "Users" }],
+    filterBar: listFilterBar(state, all.length),
+    pagination: listPagination(state, page),
+    table: listTable(rows, state, sort),
+    title: "Users",
+  };
+}
+
+function listTable(rows: UserView[], state: ListState, sort: { dir: "asc" | "desc"; field: string } | null) {
+  return {
+    actions: true,
+    caption: "Users",
+    columns: COLUMNS.map((c) => {
+      const dir = sort && sort.field === c.key ? sort.dir : undefined;
+      const next = dir === "asc" ? `-${c.key}` : c.key; // asc→desc, else→asc
+      return { href: listHref(state, { page: 1, sort: next }), label: c.label, sort: dir, sortable: true };
+    }),
+    rows: rows.map((u) => ({
+      actions: [{ href: `${ADMIN_USERS_BASE}/${encodeURIComponent(u.id)}`, icon: "i-edit", label: "Edit" }],
+      cells: [
+        { user: { initials: u.initials, name: u.name } },
+        u.email,
+        { badge: { label: cap(u.state), tone: STATE_TONE[u.state] ?? "info" } },
+      ],
+      name: u.name,
+    })),
+  };
+}
+
+function listFilterBar(state: ListState, total: number) {
+  const pills: { label: string; remove: string; value: string }[] = [];
+  if (state.q) pills.push({ label: "Search", remove: listHref(state, { page: 1, q: "" }), value: state.q });
+  if (state.status !== "all") pills.push({ label: "Status", remove: listHref(state, { page: 1, status: "all" }), value: cap(state.status) });
+  return {
+    applyLabel: "Apply filters",
+    clearHref: ADMIN_USERS_BASE,
+    label: "Filter users",
+    pills,
+    rows: [[
+      { label: "Search users", name: "q", placeholder: "Search name or email…", type: "search", value: state.q },
+      { legend: "Status", name: "status", options: [
+        { count: total, label: "All", value: "all" },
+        { label: "Active", value: "active" },
+        { label: "Inactive", value: "inactive" },
+      ], type: "segmented", value: state.status },
+      { 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.status !== "all") hidden.push({ name: "status", value: state.status });
+  if (state.sort) hidden.push({ name: "sort", value: state.sort });
+  return {
+    label: "Users 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 },
+  };
+}
+
+export interface FieldConfig {
+  autocomplete?: string;
+  hint?: string;
+  icon?: string;
+  id: string;
+  label: string;
+  name: string;
+  optional?: boolean;
+  readonly?: boolean;
+  required?: boolean;
+  type?: string;
+  value?: string;
+}
+
+export function buildUserFormModel(opts: {
+  csrfToken?: string;
+  error?: string;
+  identity?: Identity | null;
+  recovery?: RecoveryCode;
+  values?: Partial<UserInput>;
+}) {
+  const editing = opts.identity != null;
+  const view = editing ? toUserView(opts.identity!) : null;
+  const np = editing ? nameParts(opts.identity!) : { first: opts.values?.first ?? "", last: opts.values?.last ?? "" };
+  const email = editing ? view!.email : (opts.values?.email ?? "");
+  const idPath = editing ? `${ADMIN_USERS_BASE}/${encodeURIComponent(view!.id)}` : ADMIN_USERS_BASE;
+
+  const fields: FieldConfig[] = [
+    { autocomplete: "email", icon: "i-mail", id: "email", label: "Email", name: "email", required: !editing, type: "email", value: email,
+      ...(editing ? { hint: "The login identifier — can't be changed here.", readonly: true } : {}) },
+    { id: "first", label: "First name", name: "first", optional: true, value: np.first },
+    { id: "last", label: "Last name", name: "last", optional: true, value: np.last },
+  ];
+  if (!editing) fields.push({ autocomplete: "new-password", hint: "Optional — leave blank to have the user set one via a recovery code.", icon: "i-lock", id: "password", label: "Password", name: "password", optional: true, type: "password" });
+
+  return {
+    breadcrumbs: [{ href: ADMIN_USERS_BASE, label: "Users" }, { label: editing ? "Edit" : "New" }],
+    edit: editing ? {
+      deleteAction: `${idPath}/delete`,
+      id: view!.id,
+      nextLabel: view!.state === "inactive" ? "Reactivate" : "Deactivate",
+      recoveryAction: `${idPath}/recovery`,
+      state: view!.state,
+      stateAction: `${idPath}/state`,
+    } : undefined,
+    error: opts.error,
+    form: { action: idPath, cancelHref: ADMIN_USERS_BASE, csrfToken: opts.csrfToken ?? "", fields, submitLabel: editing ? "Save changes" : "Create user" },
+    recovery: opts.recovery,
+    title: editing ? "Edit user" : "New user",
+  };
+}
+
+// ---- request handler (imperative shell) ----
+
+function readUserInput(form: URLSearchParams): UserInput {
+  return {
+    email: (form.get("email") ?? "").trim(),
+    first: (form.get("first") ?? "").trim(),
+    last: (form.get("last") ?? "").trim(),
+    password: form.get("password") ?? "",
+  };
+}
+
+// Shared per-request deps for the Users screen, resolved by `withUser`: the gate (admin only) and
+// the Kratos capability (else a themed 503). Each route below is a thin handler over these.
+interface UsersDeps { ctx: RequestContext; kratosAdmin: KratosAdmin; revoke: ((sub: string) => void) | undefined; user: User; }
+
+// Resolve the shared deps, then run `inner`. The route's `permission: "admin"` already gated at the
+// host; `requireAdmin` is defence-in-depth and yields the user. GuardError (auth/CSRF) → host maps it.
+function withUser(inner: (deps: UsersDeps) => Promise<RouteResult>): RouteHandler {
+  return async (ctx) => {
+    const user = requireAdmin(ctx);
+    const kratosAdmin = ctx.system?.kratosAdmin;
+    if (!kratosAdmin) return unavailable(ctx, "Kratos identity admin");
+    return inner({ ctx, kratosAdmin, revoke: ctx.system?.revoke, user });
+  };
+}
+
+// Same, plus the target identity from ctx.params.id (unknown id → themed 404). The router already
+// decoded the id and 404s malformed %-encoding, so no manual decode is needed here.
+function withTarget(inner: (deps: UsersDeps, identity: Identity, id: string) => Promise<RouteResult>): RouteHandler {
+  return withUser(async (deps) => {
+    const id = deps.ctx.params["id"] ?? "";
+    const identity = await deps.kratosAdmin.getIdentity(id);
+    if (!identity) return notFound(deps.ctx);
+    return inner(deps, identity, id);
+  });
+}
+
+const formResult = (ctx: RequestContext, extra: Parameters<typeof buildUserFormModel>[0]): RouteResult =>
+  ({ data: { chrome: ctx.chrome, model: buildUserFormModel({ csrfToken: ctx.chrome.csrfToken, ...extra }) }, view: "user-form" });
+
+// GET /admin/users — the filtered/sorted/paged list.
+export const usersList = withUser(async ({ ctx, kratosAdmin }) => {
+  const { identities } = await kratosAdmin.listIdentities({ pageSize: LIST_FETCH_SIZE });
+  return { data: { chrome: ctx.chrome, model: buildUsersListModel({ csrfToken: ctx.chrome.csrfToken, identities, url: ctx.url }) }, view: "users" };
+});
+
+// POST /admin/users — create; a Kratos 4xx re-renders the form (400), keeping the input.
+export const usersCreate = withUser(async ({ ctx, kratosAdmin, user }) => {
+  const input = readUserInput((await guardedForm(ctx))!);
+  try {
+    await kratosAdmin.createIdentity(createIdentityPayload(input));
+  } catch (err) {
+    if (err instanceof KratosError) return { ...formResult(ctx, { error: createError(err), values: input }), status: 400 };
+    throw err;
+  }
+  ctx.log.info("admin: user created", { actor: user.id, email: input.email });
+  return { redirect: ADMIN_USERS_BASE };
+});
+
+// GET /admin/users/new — the empty create form.
+export const usersNewForm = withUser(({ ctx }) => Promise.resolve(formResult(ctx, {})));
+
+// GET /admin/users/:id — the edit form, prefilled.
+export const usersEditForm = withTarget((deps, identity) => Promise.resolve(formResult(deps.ctx, { identity })));
+
+// POST /admin/users/:id — save edits; a Kratos 4xx re-renders the form (400).
+export const usersUpdate = withTarget(async ({ ctx, kratosAdmin }, identity, id) => {
+  const input = readUserInput((await guardedForm(ctx))!);
+  try {
+    await kratosAdmin.updateIdentity(id, updateIdentityPayload(identity, input));
+  } catch (err) {
+    if (err instanceof KratosError) return { ...formResult(ctx, { error: "Could not save changes — check the fields and try again.", identity }), status: 400 };
+    throw err;
+  }
+  return { redirect: `${ADMIN_USERS_BASE}/${encodeURIComponent(id)}` };
+});
+
+// POST /admin/users/:id/state — toggle active/inactive; a deactivation revokes the target's live
+// tokens now (not after the JWT TTL). Self-protection: an admin can't deactivate their own account.
+export const usersState = withTarget(async ({ ctx, kratosAdmin, revoke, user }, identity, id) => {
+  await guardedForm(ctx); // CSRF-verify the POST (no fields read)
+  if (id === user.id) return { ...formResult(ctx, { error: "You can't deactivate your own account.", identity }), status: 400 };
+  const nextState = identity.state === "inactive" ? "active" : "inactive";
+  await kratosAdmin.updateIdentity(id, setStatePayload(identity, nextState));
+  if (nextState === "inactive") revoke?.(id);
+  ctx.log.info("admin: user state changed", { actor: user.id, state: nextState, target: id });
+  return { redirect: `${ADMIN_USERS_BASE}/${encodeURIComponent(id)}` };
+});
+
+// GET /admin/users/:id/delete — the deliberate confirm step (zero-JS). Refuses self-delete.
+export const usersDeleteConfirm = withTarget((deps, identity, id) => {
+  if (id === deps.user.id) return Promise.resolve({ ...formResult(deps.ctx, { error: "You can't delete your own account.", identity }), status: 400 });
+  const back = `${ADMIN_USERS_BASE}/${encodeURIComponent(id)}`;
+  const view = toUserView(identity);
+  return Promise.resolve({ data: { chrome: deps.ctx.chrome, model: buildConfirmModel({
+    breadcrumbs: [{ href: ADMIN_USERS_BASE, label: "Users" }, { href: back, label: view.name }, { label: "Delete" }],
+    cancelHref: back, confirmAction: `${back}/delete`, confirmLabel: "Delete user",
+    message: `Delete ${view.email}? This permanently removes the account and can't be undone.`, title: "Delete user",
+  }) }, view: "confirm" });
+});
+
+// POST /admin/users/:id/delete — perform it; revoke the gone account's live tokens. Refuses self-delete.
+export const usersDelete = withTarget(async ({ ctx, kratosAdmin, revoke, user }, identity, id) => {
+  await guardedForm(ctx); // CSRF-verify the POST
+  if (id === user.id) return { ...formResult(ctx, { error: "You can't delete your own account.", identity }), status: 400 };
+  await kratosAdmin.deleteIdentity(id);
+  revoke?.(id);
+  ctx.log.info("admin: user deleted", { actor: user.id, target: id });
+  return { redirect: ADMIN_USERS_BASE };
+});
+
+// POST /admin/users/:id/recovery — mint a one-time recovery code, shown on the edit page.
+export const usersRecovery = withTarget(async ({ ctx, kratosAdmin }, identity, id) => {
+  await guardedForm(ctx); // CSRF-verify the POST
+  const recovery = await kratosAdmin.createRecoveryCode(id);
+  return formResult(ctx, { identity, recovery });
+});
+
+function createError(err: KratosError): string {
+  return err.status === 409
+    ? "A user with that email already exists."
+    : "Could not create the user — check the email and try again.";
+}

examples/plugins/admin/plugin.ts

@@ -0,0 +1,65 @@
+// Admin example plugin: the Users / Groups / Roles / OAuth2-clients screens for running the system.
+// These used to ship inside the core; they were extracted here so a fresh clone has no built-in admin
+// GUI. Copy this folder to plugins/admin (then restart) to enable it — see README → Quick start.
+//
+// It is a *system* plugin: its handlers reach the host's Ory admin clients (Kratos/Keto/Hydra) and the
+// instant-revoke hook via ctx.system, which the host populates when those services are wired (the dev
+// stack wires all of them). Where a capability is absent the screen degrades to a themed 503.
+
+import { definePlugin, type HttpMethod, type Route, type RouteHandler } from "#plugin-api";
+import { clientsCreate, clientsDeleteConfirm, clientsDelete, clientsDetail, clientsList, clientsNewForm } from "./admin-clients.ts";
+import { groupsAddMember, groupsCreate, groupsDelete, groupsDeleteConfirm, groupsDetail, groupsList, groupsNewForm, groupsRemoveMember } from "./admin-groups.ts";
+import { rolesAddMember, rolesCreate, rolesDelete, rolesDeleteConfirm, rolesDetail, rolesList, rolesNewForm, rolesRemoveMember } from "./admin-roles.ts";
+import { usersCreate, usersDeleteConfirm, usersDelete, usersEditForm, usersList, usersNewForm, usersRecovery, usersState, usersUpdate } from "./admin-users.ts";
+import { ADMIN_NAV, ADMIN_PERMISSION } from "./admin-shared.ts";
+
+// Every admin route is gated by the one `admin` permission — the host redirects an anonymous visitor
+// to /login, gives a signed-in non-admin the 403 page, and filters the nav the same way. Handlers are
+// thin and keyed on ctx.params (the host extracts :id / :name), the idiomatic per-route style.
+const r = (method: HttpMethod, path: string, handler: RouteHandler): Route => ({ handler, method, path, permission: ADMIN_PERMISSION });
+
+export default definePlugin({
+  apiVersion: "1.0.0", // the host contract this was built against — a literal, never HOST_API_VERSION
+
+  nav: [ADMIN_NAV],
+
+  permissions: [{ description: "Administer users, groups, roles, and OAuth2 clients", token: ADMIN_PERMISSION }],
+
+  routes: [
+    // Users
+    r("GET", "/users", usersList),
+    r("POST", "/users", usersCreate),
+    r("GET", "/users/new", usersNewForm),
+    r("GET", "/users/:id", usersEditForm),
+    r("POST", "/users/:id", usersUpdate),
+    r("POST", "/users/:id/state", usersState),
+    r("GET", "/users/:id/delete", usersDeleteConfirm),
+    r("POST", "/users/:id/delete", usersDelete),
+    r("POST", "/users/:id/recovery", usersRecovery),
+    // Groups
+    r("GET", "/groups", groupsList),
+    r("POST", "/groups", groupsCreate),
+    r("GET", "/groups/new", groupsNewForm),
+    r("GET", "/groups/:name", groupsDetail),
+    r("POST", "/groups/:name/members", groupsAddMember),
+    r("GET", "/groups/:name/delete", groupsDeleteConfirm),
+    r("POST", "/groups/:name/delete", groupsDelete),
+    r("POST", "/groups/:name/members/delete", groupsRemoveMember),
+    // Roles
+    r("GET", "/roles", rolesList),
+    r("POST", "/roles", rolesCreate),
+    r("GET", "/roles/new", rolesNewForm),
+    r("GET", "/roles/:name", rolesDetail),
+    r("POST", "/roles/:name/members", rolesAddMember),
+    r("GET", "/roles/:name/delete", rolesDeleteConfirm),
+    r("POST", "/roles/:name/delete", rolesDelete),
+    r("POST", "/roles/:name/members/delete", rolesRemoveMember),
+    // OAuth2 clients
+    r("GET", "/clients", clientsList),
+    r("POST", "/clients", clientsCreate),
+    r("GET", "/clients/new", clientsNewForm),
+    r("GET", "/clients/:id", clientsDetail),
+    r("GET", "/clients/:id/delete", clientsDeleteConfirm),
+    r("POST", "/clients/:id/delete", clientsDelete),
+  ],
+});

examples/plugins/admin/views/client-detail.ejs

@@ -0,0 +1,17 @@
+<%#
+  OAuth2 client detail page: the client-detail body (info · one-time secret · delete) in the
+  shell. Doubles as the post-register page when `created`/`secret` are set.
+%><%
+  const nav = include("partials/nav-tree", { nodes: chrome.nav });
+  const body = include("partials/client-detail-body", { client: model.client, created: model.created, csrfToken: chrome.csrfToken, del: model.delete, secret: model.secret });
+-%>
+<%- include("partials/shell", {
+  body,
+  brand: chrome.brand,
+  breadcrumbs: model.breadcrumbs,
+  csrfToken: chrome.csrfToken,
+  nav,
+  theme: chrome.theme,
+  title: model.title,
+  user: chrome.user,
+}) %>

examples/plugins/admin/views/client-form.ejs

@@ -0,0 +1,16 @@
+<%#
+  OAuth2 client register page: the client-form body captured into the app shell.
+%><%
+  const nav = include("partials/nav-tree", { nodes: chrome.nav });
+  const body = include("partials/client-form-body", { error: model.error, form: model.form });
+-%>
+<%- include("partials/shell", {
+  body,
+  brand: chrome.brand,
+  breadcrumbs: model.breadcrumbs,
+  csrfToken: chrome.csrfToken,
+  nav,
+  theme: chrome.theme,
+  title: model.title,
+  user: chrome.user,
+}) %>

examples/plugins/admin/views/clients.ejs

@@ -0,0 +1,21 @@
+<%#
+  OAuth2 clients admin list: apps that log in *through* us (Hydra). Same building blocks as
+  the Roles screen, around the shell, backed by live Hydra OAuth2 clients (admin-clients.ts).
+%><%
+  const nav = include("partials/nav-tree", { nodes: chrome.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/clients/new"><svg class="ico ico-sm" aria-hidden="true"><use href="#i-plus"/></svg>Register client</a>';
+-%>
+<%- include("partials/shell", {
+  actions,
+  body: filters + table + pager,
+  brand: chrome.brand,
+  breadcrumbs: model.breadcrumbs,
+  csrfToken: chrome.csrfToken,
+  nav,
+  theme: chrome.theme,
+  title: model.title,
+  user: chrome.user,
+}) %>

examples/plugins/admin/views/confirm.ejs

@@ -0,0 +1,17 @@
+<%#
+  Admin destructive-action confirmation page: the confirm body in the app shell. Model
+  from buildConfirmModel: { message, confirm:{action,label}, cancelHref, nav, shell }.
+%><%
+  const nav = include("partials/nav-tree", { nodes: chrome.nav });
+  const body = include("partials/confirm-body", { cancelHref: model.cancelHref, confirm: model.confirm, csrfToken: chrome.csrfToken, message: model.message });
+-%>
+<%- include("partials/shell", {
+  body,
+  brand: chrome.brand,
+  breadcrumbs: model.breadcrumbs,
+  csrfToken: chrome.csrfToken,
+  nav,
+  theme: chrome.theme,
+  title: model.title,
+  user: chrome.user,
+}) %>

examples/plugins/admin/views/group-detail.ejs

@@ -0,0 +1,16 @@
+<%#
+  Group admin detail / membership page: the group-detail body in the app shell.
+%><%
+  const nav = include("partials/nav-tree", { nodes: chrome.nav });
+  const body = include("partials/group-detail-body", { add: model.add, csrfToken: model.csrfToken, del: model.delete, error: model.error, group: model.group, members: model.members });
+-%>
+<%- include("partials/shell", {
+  body,
+  brand: chrome.brand,
+  breadcrumbs: model.breadcrumbs,
+  csrfToken: chrome.csrfToken,
+  nav,
+  theme: chrome.theme,
+  title: model.title,
+  user: chrome.user,
+}) %>

examples/plugins/admin/views/group-form.ejs

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

examples/plugins/admin/views/groups.ejs

@@ -0,0 +1,21 @@
+<%#
+  Groups admin list: the same building blocks as the Users screen, around the shell, but
+  backed by live Keto subject sets (admin-groups.ts). Filter/sort/page round-trip the URL.
+%><%
+  const nav = include("partials/nav-tree", { nodes: chrome.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/groups/new"><svg class="ico ico-sm" aria-hidden="true"><use href="#i-plus"/></svg>Add group</a>';
+-%>
+<%- include("partials/shell", {
+  actions,
+  body: filters + table + pager,
+  brand: chrome.brand,
+  breadcrumbs: model.breadcrumbs,
+  csrfToken: chrome.csrfToken,
+  nav,
+  theme: chrome.theme,
+  title: model.title,
+  user: chrome.user,
+}) %>

examples/plugins/admin/views/notice.ejs

@@ -0,0 +1,17 @@
+<%#
+  Admin notice page — a single message in the app shell, reused for not-found (404) and
+  capability-unavailable (503). The shell renders `title` as the page <h1>; the body is one line.
+  Data: chrome, title, message.
+%><%
+  const navHtml = include("partials/nav-tree", { nodes: chrome.nav });
+  const body = include("partials/notice-body", { message });
+-%>
+<%- include("partials/shell", {
+  body,
+  brand: chrome.brand,
+  csrfToken: chrome.csrfToken,
+  nav: navHtml,
+  theme: chrome.theme,
+  title,
+  user: chrome.user,
+}) %>

examples/plugins/admin/views/partials/client-detail-body.ejs

@@ -0,0 +1,38 @@
+<%#
+  Admin OAuth2 client detail body, captured into the shell content slot. Config:
+    client  { firstParty, id, name, public, redirectUris[], scopes[] }
+    created bool        just registered → success banner
+    secret? string      one-time client secret (confidential clients), shown once right after create
+    del     { action }  delete the client
+    csrfToken
+%><%
+  const c = locals.client;
+  const del = locals.del;
+-%>
+<div class="form-page">
+<% if (locals.created) { -%>
+<%- include("partials/alert", { text: "Client registered.", tone: "pos" }) %>
+<% } -%>
+<% if (locals.secret) { -%>
+  <section class="form-card" aria-labelledby="secret-h">
+    <h2 class="card-title" id="secret-h">Client secret</h2>
+    <p class="field-hint">Copy these now — the secret can't be shown again. Store them where the app reads its credentials.</p>
+    <div class="field"><label for="cid">Client ID</label><input class="input" id="cid" type="text" value="<%= c.id %>" readonly></div>
+    <div class="field"><label for="csecret">Client secret</label><input class="input" id="csecret" type="text" value="<%= locals.secret %>" readonly></div>
+  </section>
+<% } -%>
+  <section class="form-card" aria-labelledby="client-h">
+    <h2 class="card-title" id="client-h"><%= c.name %></h2>
+    <dl class="detail-list">
+      <dt>Client ID</dt><dd><%= c.id %></dd>
+      <dt>Type</dt><dd><%= c.public ? "Public (PKCE)" : "Confidential" %></dd>
+      <dt>Consent</dt><dd><%= c.firstParty ? "First-party (auto-granted)" : "Shows the consent screen" %></dd>
+      <dt>Scopes</dt><dd><%= c.scopes.length ? c.scopes.join(" ") : "—" %></dd>
+      <dt>Redirect URIs</dt><dd><% if (c.redirectUris.length) { %><ul class="plain-list"><% c.redirectUris.forEach((u) => { %><li><%= u %></li><% }) %></ul><% } else { %>—<% } %></dd>
+    </dl>
+  </section>
+  <section class="form-card admin-actions" aria-label="Client actions">
+    <p class="field-hint">To change a client, delete and re-register — this issues a new client ID and secret. The secret is shown only once, at registration.</p>
+    <a class="btn btn-danger" href="<%= del.action %>"><svg class="ico ico-sm" aria-hidden="true"><use href="#i-trash"/></svg>Delete client</a>
+  </section>
+</div>

examples/plugins/admin/views/partials/client-form-body.ejs

@@ -0,0 +1,30 @@
+<%#
+  Admin OAuth2 client register form body, captured into the shell content slot. Config:
+    form { action, csrfToken, submitLabel, cancelHref, nameField, scopeField (field.ejs configs),
+           redirectUris: string (newline-separated), public: bool, firstParty: bool }
+    error? string shown when a write was rejected
+%><%
+  const form = locals.form;
+-%>
+<div class="form-page">
+<% if (locals.error) { -%>
+<%- include("partials/alert", { text: locals.error, tone: "neg" }) %>
+<% } -%>
+  <form class="form-card" method="post" action="<%= form.action %>">
+    <input type="hidden" name="_csrf" value="<%= form.csrfToken %>">
+    <%- include("partials/field", form.nameField) %>
+    <div class="field">
+      <label for="redirectUris">Redirect URIs</label>
+      <textarea class="input" id="redirectUris" name="redirectUris" rows="3" placeholder="https://app.example.com/callback"><%= form.redirectUris %></textarea>
+      <span class="field-hint">One per line — where the app is sent back after sign-in.</span>
+    </div>
+    <%- include("partials/field", form.scopeField) %>
+    <label class="check"><input type="checkbox" name="public"<% if (form.public) { %> checked<% } %>> Public client (SPA / native app, PKCE — no secret)</label>
+    <span class="field-hint">Browser and mobile apps can't keep a secret — choose Public. Server-side apps that can store one — leave it Confidential.</span>
+    <label class="check"><input type="checkbox" name="firstParty"<% if (form.firstParty) { %> checked<% } %>> First-party (auto-grant consent — skip the consent screen)</label>
+    <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>

examples/plugins/admin/views/partials/confirm-body.ejs

@@ -0,0 +1,17 @@
+<%#
+  Destructive-action confirm body, captured into the shell content slot. Zero-JS: the
+  delete is a deliberate second step (a POST form), with a cancel link back. Config:
+    message    string
+    confirm    { action, label }   the danger POST endpoint + button label
+    cancelHref string
+    csrfToken
+%>
+<div class="form-page">
+  <section class="form-card admin-actions" aria-label="Confirm action">
+    <p><%= locals.message %></p>
+    <div class="form-actions">
+      <a class="btn" href="<%= locals.cancelHref %>">Cancel</a>
+      <form method="post" action="<%= locals.confirm.action %>"><input type="hidden" name="_csrf" value="<%= locals.csrfToken %>"><button class="btn btn-danger" type="submit"><svg class="ico ico-sm" aria-hidden="true"><use href="#i-trash"/></svg><%= locals.confirm.label %></button></form>
+    </div>
+  </section>
+</div>

examples/plugins/admin/views/partials/group-detail-body.ejs

@@ -0,0 +1,42 @@
+<%#
+  Admin group membership body, captured into the shell content slot. Config:
+    group   { name }
+    members { action, rows: { kind:"group"|"user", label, subject }[] }   action = remove-member endpoint
+    add     { action, options: {label,value}[] }                          action = add-member endpoint
+    del     { action }                                                     delete the whole group
+    csrfToken, error?
+%><%
+  const group = locals.group;
+  const members = locals.members;
+  const add = locals.add;
+  const del = locals.del;
+  const csrf = locals.csrfToken;
+-%>
+<div class="form-page">
+<% if (locals.error) { -%>
+<%- include("partials/alert", { text: locals.error, tone: "neg" }) %>
+<% } -%>
+  <section class="form-card" aria-labelledby="members-h">
+    <h2 class="card-title" id="members-h">Members</h2>
+<% if (members.rows.length) { -%>
+    <div class="table-wrap"><table class="table"><caption class="sr-only">Members of <%= group.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>Remove</button></form></td></tr>
+<% }) -%>
+    </tbody></table></div>
+<% } else { -%>
+    <p class="cell-muted">No members yet.</p>
+<% } -%>
+  </section>
+  <section class="form-card" aria-labelledby="add-h">
+    <h2 class="card-title" id="add-h">Add a member</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>Add</button></form>
+<% } else { -%>
+    <p class="cell-muted">All users and groups are already members.</p>
+<% } -%>
+  </section>
+  <section class="form-card admin-actions" aria-label="Group actions">
+    <a class="btn btn-danger" href="<%= del.action %>"><svg class="ico ico-sm" aria-hidden="true"><use href="#i-trash"/></svg>Delete group</a>
+  </section>
+</div>

examples/plugins/admin/views/partials/group-form-body.ejs

@@ -0,0 +1,26 @@
+<%#
+  Admin group create form body, 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("partials/alert", { text: locals.error, tone: "neg" }) %>
+<% } -%>
+  <form class="form-card" method="post" action="<%= form.action %>">
+    <input type="hidden" name="_csrf" value="<%= form.csrfToken %>">
+    <%- include("partials/field", form.nameField) %>
+    <div class="field">
+      <label for="member">First member</label>
+      <span class="select"><select id="member" name="member" required><option value="" disabled<% if (!form.selectedMember) { %> selected<% } %>>Choose a member…</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 group exists once it has a member; add more 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>

examples/plugins/admin/views/partials/notice-body.ejs

@@ -0,0 +1,2 @@
+<%# One-line notice body (not-found / unavailable). Data: message. %>
+<section class="notice"><p><%= message %></p></section>

examples/plugins/admin/views/partials/role-detail-body.ejs

@@ -0,0 +1,57 @@
+<%#
+  Admin role detail body, 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("partials/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">
+    <a class="btn btn-danger" href="<%= del.action %>"><svg class="ico ico-sm" aria-hidden="true"><use href="#i-trash"/></svg>Delete role</a>
+  </section>
+</div>

examples/plugins/admin/views/partials/role-form-body.ejs

@@ -0,0 +1,26 @@
+<%#
+  Admin role create form body, 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("partials/alert", { text: locals.error, tone: "neg" }) %>
+<% } -%>
+  <form class="form-card" method="post" action="<%= form.action %>">
+    <input type="hidden" name="_csrf" value="<%= form.csrfToken %>">
+    <%- include("partials/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>

examples/plugins/admin/views/partials/user-form-body.ejs

@@ -0,0 +1,36 @@
+<%#
+  Admin user create/edit form body, captured into the shell content slot. Config:
+    form  { action, csrfToken, submitLabel, cancelHref, fields: field.ejs config[] }
+    edit? { nextLabel, stateAction, recoveryAction, deleteAction }   (edit mode only)
+    recovery? { code? }   shown after a recovery code is generated (recovery is code-based)
+    error?   string              shown when a write was rejected
+%><%
+  const form = locals.form;
+  const edit = locals.edit;
+  const recovery = locals.recovery;
+-%>
+<div class="form-page">
+<% if (locals.error) { -%>
+<%- include("partials/alert", { text: locals.error, tone: "neg" }) %>
+<% } -%>
+<% if (recovery) { -%>
+  <div class="alert alert-pos" role="status"><svg class="ico ico-sm" aria-hidden="true"><use href="#i-check-circle"/></svg><div class="alert-body"><strong>Recovery code generated</strong><span>Give it to the user — they enter it on the <a href="/recovery">password-reset screen</a> to set a new password (generate a fresh one if it has expired).</span><% if (recovery.code) { %><span class="recovery-code"><code><%= recovery.code %></code></span><% } %></div></div>
+<% } -%>
+  <form class="form-card" method="post" action="<%= form.action %>">
+    <input type="hidden" name="_csrf" value="<%= form.csrfToken %>">
+<% form.fields.forEach((field) => { -%>
+    <%- include("partials/field", field) %>
+<% }) -%>
+    <div class="form-actions">
+      <a class="btn" href="<%= form.cancelHref %>">Cancel</a>
+      <button class="btn btn-primary" type="submit"><%= form.submitLabel %></button>
+    </div>
+  </form>
+<% if (edit) { -%>
+  <section class="form-card admin-actions" aria-label="Account actions">
+    <form method="post" action="<%= edit.recoveryAction %>"><input type="hidden" name="_csrf" value="<%= form.csrfToken %>"><button class="btn" type="submit"><svg class="ico ico-sm" aria-hidden="true"><use href="#i-mail"/></svg>Generate recovery code</button></form>
+    <form method="post" action="<%= edit.stateAction %>"><input type="hidden" name="_csrf" value="<%= form.csrfToken %>"><button class="btn" type="submit"><%= edit.nextLabel %></button></form>
+    <a class="btn btn-danger" href="<%= edit.deleteAction %>"><svg class="ico ico-sm" aria-hidden="true"><use href="#i-trash"/></svg>Delete user</a>
+  </section>
+<% } -%>
+</div>

examples/plugins/admin/views/role-detail.ejs

@@ -0,0 +1,16 @@
+<%#
+  Role admin detail page: the role-detail body (members · effective access) in the shell.
+%><%
+  const nav = include("partials/nav-tree", { nodes: chrome.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: chrome.brand,
+  breadcrumbs: model.breadcrumbs,
+  csrfToken: chrome.csrfToken,
+  nav,
+  theme: chrome.theme,
+  title: model.title,
+  user: chrome.user,
+}) %>

examples/plugins/admin/views/role-form.ejs

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

examples/plugins/admin/views/roles.ejs

@@ -0,0 +1,21 @@
+<%#
+  Roles admin list: the same building blocks as the Groups screen, around the shell, backed
+  by live Keto Role subject sets (admin-roles.ts). Filter/sort/page round-trip the URL.
+%><%
+  const nav = include("partials/nav-tree", { nodes: chrome.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: chrome.brand,
+  breadcrumbs: model.breadcrumbs,
+  csrfToken: chrome.csrfToken,
+  nav,
+  theme: chrome.theme,
+  title: model.title,
+  user: chrome.user,
+}) %>

examples/plugins/admin/views/user-form.ejs

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

examples/plugins/admin/views/users.ejs

@@ -0,0 +1,21 @@
+<%#
+  Users admin list: the same building blocks as the dashboard, around the shell, but
+  backed by live Kratos identities (admin-users.ts). Filter/sort/page all round-trip the URL.
+%><%
+  const nav = include("partials/nav-tree", { nodes: chrome.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/users/new"><svg class="ico ico-sm" aria-hidden="true"><use href="#i-plus"/></svg>Add user</a>';
+-%>
+<%- include("partials/shell", {
+  actions,
+  body: filters + table + pager,
+  brand: chrome.brand,
+  breadcrumbs: model.breadcrumbs,
+  csrfToken: chrome.csrfToken,
+  nav,
+  theme: chrome.theme,
+  title: model.title,
+  user: chrome.user,
+}) %>

examples/plugins/scheduling/README.md

@@ -10,7 +10,7 @@ What it demonstrates:
   service and renders the rows with the core building blocks (`shifts.ejs` → app shell, filter-bar,
   data-table). Search round-trips the URL; zero-JS. (It fetches **all** rows for brevity — for a
   large list, parse `page`/`pageSize` from `parseListQuery`, forward them upstream as a `?limit`/
-  `?offset`, and render `pagination.ejs` with `paginate()`, exactly as the built-in admin screens do.)
+  `?offset`, and render `pagination.ejs` with `paginate()`, exactly as the admin example plugin does.)
 - **A form that forwards a write upstream** — `GET /scheduling/shifts/new` renders the form,
   `POST /scheduling/shifts` CSRF-verifies it (`ctx.verifyCsrf`) and forwards the create upstream,
   then POST-redirect-GET. The form body lives in the plugin's own `views/partials/shift-form.ejs`,