@awsmbiz/create-inbis-app 0.0.0-stage → 0.1.0

package/template/modules/access-control/files/test/access-control.test.ts

@@ -0,0 +1,78 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { choicesWith, json, migrate, newUser, seedAdmin, seedUser, signIn, testApp, type TestApp } from "./auth-fixtures.js";
+
+// Access control wired into the app, over HTTP: the example permission protects
+// GET /v1/example/protected, and administrators grant it through the role admin API.
+// @awsmbiz/inbis-access-control's own tests cover the rules in detail; these prove the wiring.
+
+const PROTECTED = "/v1/example/protected";
+
+beforeEach(async () => {
+  await migrate();
+});
+
+async function signedInUser(app: TestApp): Promise<{ cookie: string; id: string }> {
+  const user = newUser();
+  await seedUser(user);
+  const cookie = await signIn(app, user);
+  const me = await app.call("/api/me", { headers: { cookie } });
+  return { cookie, id: (await me.json<{ user: { id: string } }>()).user.id };
+}
+
+describe("a route protected by a permission", () => {
+  it("refuses a visitor who is not signed in", async () => {
+    const response = await testApp().call(PROTECTED);
+    expect(response.status).toBe(401);
+    expect(await response.json()).toMatchObject({ error: { code: "UNAUTHENTICATED" } });
+  });
+
+  it("refuses a signed-in user without the permission, and admits them once an administrator grants a role with it", async () => {
+    const app = testApp(choicesWith("invite-only"));
+    const user = await signedInUser(app);
+
+    const refused = await app.call(PROTECTED, { headers: { cookie: user.cookie } });
+    expect(refused.status).toBe(403);
+    expect(await refused.json()).toMatchObject({ error: { code: "FORBIDDEN", details: { permission: "example.read" } } });
+
+    const admin = await seedAdmin();
+    const granted = await app.call(`/api/admin/users/${user.id}/roles/viewer`, { ...json({}, { cookie: admin }), method: "PUT" });
+    expect(granted.status).toBe(200);
+    expect(await granted.json()).toMatchObject({ items: [{ id: "viewer", system: true }] });
+
+    const admitted = await app.call(PROTECTED, { headers: { cookie: user.cookie } });
+    expect(admitted.status).toBe(200);
+    expect(await admitted.json()).toEqual({ message: "You hold the example.read permission." });
+  });
+
+  it("is documented in the OpenAPI description", async () => {
+    const response = await testApp().call("/openapi.json");
+    const document = await response.json<{ paths: Record<string, unknown> }>();
+    expect(Object.keys(document.paths)).toContain(PROTECTED);
+  });
+});
+
+describe("the role admin API", () => {
+  it("lists the app's catalogue and seeded system roles to administrators", async () => {
+    const app = testApp(choicesWith("invite-only"));
+    const admin = await seedAdmin();
+
+    const permissions = await app.call("/api/admin/permissions", { headers: { cookie: admin } });
+    expect(permissions.status).toBe(200);
+    const { items: declared } = await permissions.json<{ items: { name: string }[] }>();
+    expect(declared.map((permission) => permission.name)).toContain("example.read");
+
+    const roles = await app.call("/api/admin/roles", { headers: { cookie: admin } });
+    const { items: seeded } = await roles.json<{ items: { id: string; name: string; system: boolean }[] }>();
+    expect(seeded.find((role) => role.id === "viewer")).toMatchObject({ name: "Viewer", system: true });
+  });
+
+  it("is for administrators only", async () => {
+    const app = testApp(choicesWith("invite-only"));
+    const anonymous = await app.call("/api/admin/roles");
+    expect(anonymous.status).toBe(401);
+
+    const user = await signedInUser(app);
+    const refused = await app.call("/api/admin/roles", { headers: { cookie: user.cookie } });
+    expect(refused.status).toBe(403);
+  });
+});

package/template/modules/access-control/module.json

@@ -0,0 +1,54 @@
+{
+  "name": "access-control",
+  "description": "Business permissions (@awsmbiz/inbis-access-control): a typed permission catalogue stub with a system role, requirePermission() on an example route and the role admin API; with admin, the roles pages and the user-roles section; with audit, role changes in the trail.",
+  "order": 20,
+  "requires": ["auth"],
+  "bindings": {
+    "ACCESS_CONTROL_DB": "the access-control tables (@awsmbiz/inbis-access-control migrations, same database)"
+  },
+  "dependencies": {
+    "@awsmbiz/inbis-access-control": "workspace:*"
+  },
+  "points": {
+    "access.permissions": { "file": "src/access-control.ts", "description": "Entries of APP_ACCESS.permissions: `\"name.action\": \"Description\",`." },
+    "access.roles": { "file": "src/access-control.ts", "description": "System roles of APP_ACCESS.roles: `id: { name, description?, permissions, inherits? },`." }
+  },
+  "wiring": {
+    "worker.imports": "wiring/worker.imports.ts",
+    "worker.routes": "wiring/worker.routes.ts",
+    "env.bindings": "wiring/env.bindings.ts",
+    "wrangler.d1": "wiring/d1.jsonc",
+    "test.env": "wiring/test.env.ts",
+    "test.migrate": "wiring/test.migrate.ts",
+    "vitest.bindings": "wiring/vitest.bindings.ts",
+    "readme.modules": "wiring/readme.modules.md"
+  },
+  "when": [
+    {
+      "modules": ["audit"],
+      "files": "with-audit",
+      "wiring": {
+        "audit.catalogues.imports": "wiring/audit/audit.catalogues.imports.ts",
+        "audit.catalogues": "wiring/audit/audit.catalogues.ts",
+        "web.messages": "wiring/audit/web.messages.ts",
+        "readme.modules": "wiring/audit/readme.modules.md"
+      }
+    },
+    {
+      "modules": ["admin"],
+      "files": "with-admin",
+      "dependencies": {
+        "@awsmbiz/inbis-admin-ui": "workspace:*",
+        "@awsmbiz/inbis-api-client": "workspace:*"
+      },
+      "wiring": {
+        "admin.imports": "wiring/admin/admin.imports.tsx",
+        "admin.nav": "wiring/admin/admin.nav.tsx",
+        "admin.pages": "wiring/admin/admin.pages.tsx",
+        "admin.userSections": "wiring/admin/admin.userSections.tsx",
+        "web.messages": "wiring/admin/web.messages.ts",
+        "readme.modules": "wiring/admin/readme.modules.md"
+      }
+    }
+  ]
+}

package/template/modules/access-control/wiring/admin/admin.imports.tsx

@@ -0,0 +1 @@
+import { NewRolePage, RolePage, RolesIcon, RolesPage, UserRoles } from "./admin-roles.js";

package/template/modules/access-control/wiring/admin/admin.nav.tsx

@@ -0,0 +1,2 @@
+// Roles and permissions (access-control module).
+{ to: "roles", label: t("accessControl.roles.title"), icon: RolesIcon },

package/template/modules/access-control/wiring/admin/admin.pages.tsx

@@ -0,0 +1,4 @@
+// Roles and permissions (access-control module).
+{ path: "roles", title: t("accessControl.roles.title"), component: RolesPage },
+{ path: "roles/new", title: t("accessControl.newRole.title"), component: NewRolePage },
+{ path: "roles/:roleId", title: t("accessControl.role.title"), component: RolePage },

package/template/modules/access-control/wiring/admin/admin.userSections.tsx

@@ -0,0 +1 @@
+<UserRoles user={user} />

package/template/modules/access-control/wiring/admin/readme.modules.md

@@ -0,0 +1,3 @@
+With the admin area (the `admin` module), administrators manage roles at `/admin/roles`
+(system roles read-only, custom roles editable) and assign them in the **Roles** section of
+a user's page (`web/src/admin-roles.tsx`).

package/template/modules/access-control/wiring/admin/web.messages.ts

@@ -0,0 +1,4 @@
+// Roles and permissions in the admin area (access-control module). The pages' own text comes from @awsmbiz/inbis-admin-ui.
+"accessControl.roles.title": "Roles",
+"accessControl.newRole.title": "New role",
+"accessControl.role.title": "Role",

package/template/modules/access-control/wiring/audit/audit.catalogues.imports.ts

@@ -0,0 +1 @@
+import { ACCESS_CONTROL_AUDIT_ACTIONS } from "@awsmbiz/inbis-access-control";

package/template/modules/access-control/wiring/audit/audit.catalogues.ts

@@ -0,0 +1 @@
+ACCESS_CONTROL_AUDIT_ACTIONS,

package/template/modules/access-control/wiring/audit/readme.modules.md

@@ -0,0 +1,4 @@
+With the audit trail (the `audit` module), role changes are recorded there
+(`access.role.assigned`, `.unassigned`, `.created`, `.updated`, `.deleted`;
+`ACCESS_CONTROL_AUDIT_ACTIONS`, registered in `src/audit-catalogues.ts`), with the
+administrator as the actor.

package/template/modules/access-control/wiring/audit/web.messages.ts

@@ -0,0 +1,6 @@
+// Role changes an administrator makes (access-control module), in their own activity.
+"activity.action.access.role.assigned": "Assigned a role",
+"activity.action.access.role.unassigned": "Removed a role",
+"activity.action.access.role.created": "Created a role",
+"activity.action.access.role.updated": "Changed a role",
+"activity.action.access.role.deleted": "Deleted a role",

package/template/modules/access-control/wiring/d1.jsonc

@@ -0,0 +1,8 @@
+{
+  // Access control (@awsmbiz/inbis-access-control): after auth's (user_role references user), before audit's and DB.
+  "binding": "ACCESS_CONTROL_DB",
+  "database_name": "{{database_name}}",
+  "database_id": "{{database_id}}",
+  "migrations_dir": "node_modules/@awsmbiz/inbis-access-control/migrations",
+  "migrations_table": "_inbis_access_control_migrations"
+},

package/template/modules/access-control/wiring/env.bindings.ts

@@ -0,0 +1,2 @@
+/** The access-control tables (@awsmbiz/inbis-access-control migrations); same database as DB. */
+ACCESS_CONTROL_DB: D1Database;

package/template/modules/access-control/wiring/readme.modules.md

@@ -0,0 +1,20 @@
+## Access control
+
+`@awsmbiz/inbis-access-control`: business permissions and roles, in the app's database
+through their own binding (`ACCESS_CONTROL_DB`, migrations shipped in the package, applied
+after auth's). They are separate from the platform administrator role: an administrator
+gets no business permission implicitly.
+
+- **Catalogue** — `src/access-control.ts` (`APP_ACCESS`) declares every permission the app
+  checks and the system roles that grant them. It starts as a stub (`example.read`, role
+  `viewer`): replace both with your own. Names are typed, so a typo is a compile error. The
+  catalogue is seeded into D1 on the first permission check after a deploy.
+- **Protecting a route** — `requireAuth()` (from `@awsmbiz/inbis-auth/hono`), then
+  `requirePermission("<permission>")` (from `src/access-control.ts`): `401` signed out,
+  `403 FORBIDDEN` without the permission. `src/access-control-routes.ts` shows it on
+  `GET /v1/example/protected`; `/v1` routes add auth's `sessionMiddleware` first (`/api/*`
+  already has it). In code: `(await accessControlOf(c)).authorize({ userId, permission })`.
+- **Roles** — administrators assign roles and create custom ones through the role admin
+  API under `/api/admin` (`/permissions`, `/roles`, `/users/:userId/roles`; changes need a
+  recent sign-in).
+- **Tests** — `test/access-control.test.ts` (Workers).

package/template/modules/access-control/wiring/test.env.ts

@@ -0,0 +1 @@
+ACCESS_CONTROL_MIGRATIONS: D1Migration[];

package/template/modules/access-control/wiring/test.migrate.ts

@@ -0,0 +1 @@
+await applyD1Migrations(env.ACCESS_CONTROL_DB, env.ACCESS_CONTROL_MIGRATIONS, "_inbis_access_control_migrations");

package/template/modules/access-control/wiring/vitest.bindings.ts

@@ -0,0 +1 @@
+ACCESS_CONTROL_MIGRATIONS: await readD1Migrations("./node_modules/@awsmbiz/inbis-access-control/migrations"),

package/template/modules/access-control/wiring/worker.imports.ts

@@ -0,0 +1 @@
+import { mountAccessControl } from "./access-control-routes.js";

package/template/modules/access-control/wiring/worker.routes.ts

@@ -0,0 +1,2 @@
+// Access control (access-control module): the role admin API and GET /v1/example/protected.
+mountAccessControl(app, deps.auth);

package/template/modules/access-control/with-admin/e2e/access-roles.spec.ts

@@ -0,0 +1,51 @@
+import { expect, test, type BrowserContext } from "@playwright/test";
+import { adminApi } from "./auth-helpers.js";
+import { adminsCanSignIn } from "./auth-seeded.js";
+import { expectNoPageScroll, expectNoViolations, THEMES, VIEWPORTS } from "./axe.js";
+
+// The roles pages in the admin area, as the seeded administrator (signed in once, through
+// the API: one authenticator code for the whole file). The role admin API itself is
+// covered by test/access-control.test.ts.
+
+test.skip(!adminsCanSignIn, "administrators need email + password and 2FA (src/auth-choices.ts)");
+test.describe.configure({ mode: "serial" });
+
+let session: Awaited<ReturnType<BrowserContext["storageState"]>>;
+
+test.beforeAll(async ({ playwright, baseURL }) => {
+  const admin = await adminApi(playwright, baseURL);
+  session = await admin.storageState();
+  await admin.dispose();
+});
+
+test.beforeEach(async ({ context }) => {
+  await context.addCookies(session.cookies);
+});
+
+test("an administrator finds the app's system role in the admin area and opens it", async ({ page }) => {
+  await page.goto("/admin/roles");
+  await expect(page.getByRole("heading", { name: "Roles", level: 1 })).toBeVisible();
+  await page.getByRole("link", { name: "Viewer" }).click();
+  await expect(page).toHaveURL(/\/admin\/roles\/viewer$/);
+  await expect(page.getByRole("heading", { name: "Viewer", level: 1 })).toBeVisible();
+  await expect(page.getByText("example.read")).toBeVisible();
+});
+
+for (const [name, path, heading] of [
+  ["Roles", "/admin/roles", "Roles"],
+  ["A system role", "/admin/roles/viewer", "Viewer"],
+  ["New role", "/admin/roles/new", "New role"],
+] as const) {
+  for (const theme of THEMES) {
+    for (const [viewport, size] of Object.entries(VIEWPORTS)) {
+      test(`${name} (${theme}, ${viewport}) has no accessibility violations`, async ({ page }) => {
+        await page.emulateMedia({ colorScheme: theme });
+        await page.setViewportSize(size);
+        await page.goto(path);
+        await expect(page.getByRole("heading", { name: heading, level: 1 })).toBeVisible();
+        await expectNoPageScroll(page);
+        await expectNoViolations(page);
+      });
+    }
+  }
+}

package/template/modules/access-control/with-admin/web/src/admin-roles.tsx

@@ -0,0 +1,38 @@
+import { AccessRolePage, AccessRolesPage, UserRolesSection, type AdminPageProps } from "@awsmbiz/inbis-admin-ui";
+import { createAuthAdminClient } from "@awsmbiz/inbis-api-client";
+
+// Roles and permissions in the admin area (access-control module), over the role admin
+// API that src/access-control-routes.ts mounts: the roles list, a role's page (system
+// roles read-only, custom roles editable) and the roles section of a user's page.
+
+const client = createAuthAdminClient();
+
+/** `roles`: every role, system roles first. */
+export function RolesPage() {
+  return <AccessRolesPage client={client} />;
+}
+
+/** `roles/new`: a custom role from the app's permissions. */
+export function NewRolePage() {
+  return <AccessRolePage client={client} />;
+}
+
+/** `roles/:roleId`: one role. */
+export function RolePage({ params }: AdminPageProps) {
+  return <AccessRolePage client={client} roleId={params["roleId"] ?? ""} />;
+}
+
+/** The roles section of a user's page: assign and remove roles. */
+export function UserRoles({ user }: { user: { id: string; name: string } }) {
+  return <UserRolesSection client={client} userId={user.id} userName={user.name} />;
+}
+
+/** The roles nav item's icon (a shield). */
+export function RolesIcon(props: { className?: string; "aria-hidden"?: boolean | "true" }) {
+  return (
+    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2} strokeLinecap="round" strokeLinejoin="round" {...props}>
+      <path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z" />
+      <path d="m9 12 2 2 4-4" />
+    </svg>
+  );
+}

package/template/modules/access-control/with-audit/test/access-control-audit.test.ts

@@ -0,0 +1,25 @@
+import { env } from "cloudflare:workers";
+import { beforeEach, expect, it } from "vitest";
+import { auditLog } from "../src/audit-log.js";
+import { choicesWith, json, migrate, newUser, seedAdmin, seedUser, signIn, testApp } from "./auth-fixtures.js";
+
+beforeEach(async () => {
+  await migrate();
+});
+
+it("an administrator's role assignment is recorded in the audit trail", async () => {
+  const app = testApp(choicesWith("invite-only"));
+  const user = newUser();
+  await seedUser(user);
+  const cookie = await signIn(app, user);
+  const userId = (await (await app.call("/api/me", { headers: { cookie } })).json<{ user: { id: string } }>()).user.id;
+  const admin = await seedAdmin();
+
+  const granted = await app.call(`/api/admin/users/${userId}/roles/viewer`, { ...json({}, { cookie: admin }), method: "PUT" });
+  expect(granted.status).toBe(200);
+
+  const { items } = await auditLog(env).list({ action: "access.role.assigned", subjectId: `user:${userId}` });
+  expect(items).toHaveLength(1);
+  expect(items[0]).toMatchObject({ action: "access.role.assigned", metadata: { roleId: "viewer" } });
+  expect(items[0]?.actorId).not.toBeNull();
+});

package/template/modules/admin/files/e2e/admin-accessibility.spec.ts

@@ -0,0 +1,86 @@
+import { expect, test, type Page } from "@playwright/test";
+import { signInAsAdmin } from "./admin-helpers.js";
+import { adminsCanSignIn, invitationsAllowed, USERS } from "./auth-seeded.js";
+import { expectNoPageScroll, expectNoViolations, THEMES, VIEWPORTS } from "./axe.js";
+
+// Zero axe violations (WCAG 2.2 AA, plan Q56) on every admin page, the refusal and the
+// phone navigation, in light and dark at desktop and phone sizes. Read-only.
+
+test.skip(!adminsCanSignIn, "administrators need email + password and 2FA (src/auth-choices.ts)");
+
+interface Screen {
+  path: string | ((page: Page) => Promise<void>);
+  heading: string;
+  on?: boolean;
+  /** Something that shows the page has its data. */
+  ready?: (page: Page) => Promise<void>;
+}
+
+const usersTable = (page: Page) => page.getByRole("table", { name: "Users" });
+
+const SCREENS: Screen[] = [
+  // The account page, with its link to the admin area.
+  { path: "/account", heading: "Your account", ready: (p) => expect(p.getByRole("link", { name: "Open the admin area" })).toBeVisible() },
+  { path: "/admin", heading: "Dashboard", ready: (p) => expect(p.getByText("Total users")).toBeVisible() },
+  { path: "/admin/users", heading: "Users", ready: (p) => expect(usersTable(p).getByRole("rowheader").first()).toBeVisible() },
+  {
+    path: async (page) => {
+      await page.goto("/admin/users");
+      await usersTable(page).getByRole("link", { name: USERS.admin.name }).click();
+    },
+    heading: USERS.admin.name,
+    ready: (p) => expect(p.getByRole("region", { name: "Two-factor authentication" })).toContainText("Enrolled"),
+  },
+  { path: "/admin/invitations", heading: "Invitations", on: invitationsAllowed },
+  { path: "/admin/settings", heading: "Auth settings", ready: (p) => expect(p.getByRole("table", { name: "Methods and providers" })).toBeVisible() },
+  { path: "/admin/example", heading: "Example page", ready: (p) => expect(p.getByLabel("Name")).toBeVisible() },
+  { path: "/admin/nowhere", heading: "Page not found" },
+];
+
+/** The page's heading, with nothing left loading. */
+async function settled(page: Page, heading: string) {
+  await expect(page.getByRole("heading", { level: 1, name: heading })).toBeVisible();
+  await expect(page.getByRole("status").filter({ hasText: /^Loading/ })).toHaveCount(0);
+}
+
+for (const theme of THEMES) {
+  for (const [viewport, size] of Object.entries(VIEWPORTS)) {
+    test.describe(`${theme}, ${viewport}`, () => {
+      test.use({ viewport: size, colorScheme: theme });
+
+      test("every admin page has no accessibility violations", async ({ page, baseURL }) => {
+        test.setTimeout(120_000);
+        await signInAsAdmin(page, baseURL);
+        for (const screen of SCREENS.filter((s) => s.on !== false)) {
+          await test.step(typeof screen.path === "string" ? screen.path : screen.heading, async () => {
+            if (typeof screen.path === "string") await page.goto(screen.path);
+            else await screen.path(page);
+            await screen.ready?.(page);
+            await settled(page, screen.heading);
+            await expectNoPageScroll(page);
+            await expectNoViolations(page);
+          });
+        }
+        if (viewport === "phone") {
+          await test.step("navigation menu", async () => {
+            await page.goto("/admin");
+            await page.getByRole("button", { name: "Open navigation" }).click();
+            const sheet = page.getByRole("dialog", { name: "Navigation" });
+            await expect(sheet.getByRole("link", { name: "Example" })).toBeVisible();
+            await expectNoViolations(page);
+          });
+        }
+      });
+
+      test("the refusal has no accessibility violations", async ({ page }) => {
+        await page.goto("/sign-in?next=%2Fadmin");
+        await page.getByLabel("Email").fill(USERS.axe.email);
+        await page.getByLabel("Password").fill(USERS.axe.password);
+        await page.getByRole("button", { name: "Sign in" }).click();
+        await expect(page.getByRole("heading", { level: 1, name: "Not allowed" })).toBeVisible();
+        await expectNoPageScroll(page);
+        await expectNoViolations(page);
+      });
+    });
+  }
+}

package/template/modules/admin/files/e2e/admin-area.spec.ts

@@ -0,0 +1,109 @@
+import { expect, test, type Page } from "@playwright/test";
+import { totpCode } from "../test/totp.js";
+import { adminsCreateUsers, newUser, patchAuthSettings, signInAsAdmin } from "./admin-helpers.js";
+import { adminApi, signInWithPassword } from "./auth-helpers.js";
+import { ADMIN_TOTP_SECRET, adminsCanSignIn, USERS } from "./auth-seeded.js";
+
+// The admin area (/admin): gated on the administrator role before any admin code loads
+// (plan Q16), the auth administration pages, the app's own example page, and a user
+// action that needs a recent sign-in, refused and run again after signing in.
+
+test.skip(!adminsCanSignIn, "administrators need email + password and 2FA (src/auth-choices.ts)");
+test.describe.configure({ mode: "serial" });
+
+const dashboard = (page: Page) => page.getByRole("heading", { level: 1, name: "Dashboard" });
+
+test("a signed-out visitor is sent to sign in, and an administrator comes back to the admin area", async ({ page }) => {
+  await page.goto("/admin");
+  await expect(page).toHaveURL(/\/sign-in\?next=%2Fadmin$/);
+  await signInWithPassword(page, USERS.admin, "/admin");
+  await expect(page.getByRole("heading", { name: "Two-factor authentication" })).toBeVisible();
+  await page.getByLabel("6-digit code").fill(await totpCode(ADMIN_TOTP_SECRET));
+  await page.getByRole("button", { name: "Verify" }).click();
+
+  await expect(page).toHaveURL(/\/admin$/);
+  await expect(dashboard(page)).toBeVisible();
+  await expect(page.getByText("Total users")).toBeVisible();
+  // Without the audit module, recent activity is auth's own history; it loads either way.
+  await expect(page.getByRole("list", { name: "Recent activity" }).or(page.getByText("No activity yet"))).toBeVisible();
+});
+
+test("a regular user is refused the admin area and never downloads its code", async ({ page }) => {
+  const adminCode: string[] = [];
+  page.on("request", (request) => {
+    if (/admin-area|inbis-admin-ui/.test(request.url())) adminCode.push(request.url());
+  });
+  await signInWithPassword(page, USERS.axe, "/account");
+  await expect(page.getByRole("heading", { level: 1, name: "Your account" })).toBeVisible();
+  await expect(page.getByRole("link", { name: "Open the admin area" })).toHaveCount(0);
+
+  await page.goto("/admin");
+  await expect(page.getByRole("heading", { level: 1, name: "Not allowed" })).toBeVisible();
+  await expect(page.getByText("The admin area is for administrators.")).toBeVisible();
+  await expect(dashboard(page)).toHaveCount(0);
+  expect(adminCode).toEqual([]);
+});
+
+test("an administrator goes from the account page to the admin area, its pages and the app's own page", async ({ page, baseURL }) => {
+  await signInAsAdmin(page, baseURL);
+  await page.goto("/account");
+  await page.getByRole("link", { name: "Open the admin area" }).click();
+  await expect(dashboard(page)).toBeVisible();
+
+  const nav = page.getByRole("navigation", { name: "Administration" });
+  await nav.getByRole("link", { name: "Users" }).click();
+  await expect(page.getByRole("heading", { level: 1, name: "Users" })).toBeVisible();
+  await expect(page.getByRole("table", { name: "Users" }).getByRole("link", { name: USERS.admin.name })).toBeVisible();
+
+  await nav.getByRole("link", { name: "Auth settings" }).click();
+  await expect(page.getByRole("heading", { level: 1, name: "Auth settings" })).toBeVisible();
+
+  // The app's own admin page (web/src/admin-example.tsx), on the app's own API.
+  await nav.getByRole("link", { name: "Example" }).click();
+  await expect(page.getByRole("heading", { level: 1, name: "Example page" })).toBeVisible();
+  await page.getByLabel("Name").fill("Ada");
+  await page.getByRole("button", { name: "Greet" }).click();
+  await expect(page.getByRole("status").filter({ hasText: "Hello, Ada" })).toBeVisible();
+
+  await page.getByRole("link", { name: "Back to the app" }).click();
+  await expect(page).toHaveURL(/\/$/);
+});
+
+test("a ban refused for a stale sign-in runs again once the administrator has signed in again", async ({ page, baseURL, playwright }) => {
+  test.skip(!adminsCreateUsers, "registration is closed: administrators create no accounts");
+  test.setTimeout(300_000);
+  const target = await newUser(playwright, baseURL, "Stale Ban");
+  // The shortest re-authentication window for administrators (60 s), so the page's sign-in goes stale.
+  const setup = await adminApi(playwright, baseURL);
+  await patchAuthSettings(setup, { sessions: { admin: { freshAge: 60 } } });
+  await setup.dispose();
+  try {
+    await signInAsAdmin(page, baseURL);
+    await page.goto(`/admin/users?q=${encodeURIComponent(target.name)}`);
+    await page.getByRole("table", { name: "Users" }).getByRole("link", { name: target.name }).click();
+    await expect(page.getByRole("heading", { level: 1, name: target.name })).toBeVisible();
+    // Waited in the test runner: page.waitForTimeout runs on the page's (throttled) timers.
+    await new Promise((resolve) => setTimeout(resolve, 61_000));
+
+    await page.getByRole("button", { name: "Ban user" }).click();
+    const dialog = page.getByRole("dialog", { name: `Ban ${target.name}?` });
+    await dialog.getByRole("button", { name: "Ban user" }).click();
+
+    // SESSION_NOT_FRESH: the dialog steps aside and the administrator signs in again right here.
+    await expect(page.getByRole("heading", { name: "Sign in" })).toBeVisible();
+    const signIn = page.locator("form").filter({ has: page.getByRole("button", { name: "Sign in" }) });
+    await signIn.getByLabel("Email", { exact: true }).fill(USERS.admin.email);
+    await signIn.getByLabel("Password", { exact: true }).fill(USERS.admin.password);
+    await signIn.getByRole("button", { name: "Sign in" }).click();
+    await page.getByLabel("6-digit code").fill(await totpCode(ADMIN_TOTP_SECRET));
+    await page.getByRole("button", { name: "Verify", exact: true }).click();
+
+    // The refused ban ran again.
+    await expect(page.getByRole("region", { name: /Notifications/ })).toContainText(`${target.name} is banned`);
+    await expect(page.getByRole("button", { name: "Unban user" })).toBeVisible();
+  } finally {
+    const restore = await adminApi(playwright, baseURL);
+    await patchAuthSettings(restore, { sessions: { admin: { freshAge: null } } });
+    await restore.dispose();
+  }
+});

package/template/modules/admin/files/e2e/admin-helpers.ts

@@ -0,0 +1,39 @@
+import { expect, type APIRequestContext, type Page, type PlaywrightWorkerArgs } from "@playwright/test";
+import { totpCode } from "../test/totp.js";
+import { adminApi } from "./auth-helpers.js";
+import { ADMIN_TOTP_SECRET, AUTH_CHOICES, TURNSTILE_TEST_TOKEN, USERS } from "./auth-seeded.js";
+
+/** Whether administrators may create accounts (every registration mode but `closed`). */
+export const adminsCreateUsers = AUTH_CHOICES.registration !== "closed";
+
+/** Signs the page in as the seeded administrator (password, then the authenticator code), without the UI. */
+export async function signInAsAdmin(page: Page, baseURL: string | undefined): Promise<void> {
+  const headers = { origin: baseURL ?? "", "x-captcha-response": TURNSTILE_TEST_TOKEN };
+  const signIn = await page.request.post("/api/auth/sign-in/email", { data: { email: USERS.admin.email, password: USERS.admin.password }, headers });
+  expect(signIn.status()).toBe(200);
+  const verified = await page.request.post("/api/auth/two-factor/verify-totp", { data: { code: await totpCode(ADMIN_TOTP_SECRET) }, headers });
+  expect(verified.status()).toBe(200);
+}
+
+let counter = 0;
+
+/** A new user (unique name and email), created by the seeded administrator through the API. */
+export async function newUser(playwright: PlaywrightWorkerArgs["playwright"], baseURL: string | undefined, label: string) {
+  counter += 1;
+  const stamp = `${String(Date.now())}${String(counter)}`;
+  const user = { name: `${label} ${stamp}`, email: `${label.toLowerCase().replace(/\s+/g, "-")}-${stamp}@example.test` };
+  const admin = await adminApi(playwright, baseURL);
+  const created = await admin.post("/api/auth/admin/create-user", {
+    data: { ...user, password: "a long enough password", data: { emailVerified: true } },
+  });
+  expect(created.status(), await created.text()).toBe(200);
+  await admin.dispose();
+  return user;
+}
+
+/** Changes runtime auth settings (a JSON merge patch of the overrides) as the administrator. */
+export async function patchAuthSettings(admin: APIRequestContext, settings: unknown): Promise<void> {
+  const { version } = (await (await admin.get("/api/admin/auth-settings")).json()) as { version: number };
+  const response = await admin.patch("/api/admin/auth-settings", { data: { version, settings } });
+  expect(response.status(), await response.text()).toBe(200);
+}

package/template/modules/admin/files/src/admin.ts

@@ -0,0 +1,46 @@
+import type { ApiEnv } from "@awsmbiz/inbis-api";
+import {
+  mountAuthAudit,
+  mountAuthSettings,
+  mountAuthStats,
+  mountAuthUsers,
+  type MountAuthAuditOptions,
+  type MountAuthStatsOptions,
+} from "@awsmbiz/inbis-auth/hono";
+import type { Hono } from "hono";
+// inbis:wire admin.server.imports
+
+/**
+ * Dashboard counts (`GET /api/admin/auth-stats`). Without an audit trail, auth counts failed
+ * sign-ins in its interim history and active users from sessions; with one, the trail counts.
+ */
+const stats: MountAuthStatsOptions<ApiEnv<Env>> = {
+  // inbis:wire admin.stats
+};
+
+/** The auth audit trail (`GET /api/admin/auth-audit-events`): auth's interim history, or the app's audit trail. */
+const authAudit: MountAuthAuditOptions<ApiEnv<Env>> = {
+  // inbis:wire admin.authAudit
+};
+
+/**
+ * Mounts the admin API the admin area (`/admin`) reads, after `mountAppAuth` (its session
+ * middleware covers these paths). Every route applies the admin policy (an administrator
+ * with 2FA, ADR-3); changes also need a recent sign-in (`403 SESSION_NOT_FRESH`).
+ *
+ * - `GET /api/admin/users[/:userId]`, `POST /api/admin/users/:userId/two-factor/reset`
+ * - `GET /api/admin/auth-stats` (dashboard counts)
+ * - `GET|PATCH /api/admin/auth-settings`, `GET /api/admin/auth-providers/status`
+ * - `GET /api/admin/auth-audit-events`
+ *
+ * Better Auth's admin routes (`/api/auth/admin/*`: create user, ban, set role, delete,
+ * sessions) and the invitation routes come with `mountAppAuth`. Your own admin routes go
+ * next to this call in `src/app.ts`, guarded with `requireAdmin()` (and
+ * `requireRecentAdminSignIn()` for changes) from `@awsmbiz/inbis-auth/hono`.
+ */
+export function mountAppAdmin(app: Hono<ApiEnv<Env>>): void {
+  mountAuthUsers(app);
+  mountAuthStats(app, stats);
+  mountAuthSettings(app);
+  mountAuthAudit(app, authAudit);
+}