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

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

@@ -0,0 +1,47 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { choicesWith, migrate, newUser, seedAdmin, seedUser, signIn, testApp } from "./auth-fixtures.js";
+
+// The admin API the admin area (/admin) reads, over HTTP: every route applies the admin
+// policy (an administrator with 2FA). @awsmbiz/inbis-auth's own tests cover each route in
+// detail; these prove the wiring.
+
+const ADMIN_ROUTES = ["/api/admin/users", "/api/admin/auth-stats", "/api/admin/auth-settings", "/api/admin/auth-providers/status", "/api/admin/auth-audit-events"];
+
+beforeEach(async () => {
+  await migrate();
+});
+
+describe("the admin API", () => {
+  for (const path of ADMIN_ROUTES) {
+    it(`GET ${path} needs a signed-in administrator`, async () => {
+      const app = testApp(choicesWith("invite-only"));
+      expect((await app.call(path)).status).toBe(401);
+
+      const user = newUser();
+      await seedUser(user);
+      const cookie = await signIn(app, user);
+      const refused = await app.call(path, { headers: { cookie } });
+      expect(refused.status).toBe(403);
+    });
+  }
+
+  it("an administrator with 2FA reads the users, the dashboard counts and the auth settings", async () => {
+    const app = testApp(choicesWith("invite-only"));
+    const admin = newUser("Grace Admin");
+    const cookie = await seedAdmin(admin);
+
+    const users = await app.call("/api/admin/users?role=admin&limit=100", { headers: { cookie } });
+    expect(users.status).toBe(200);
+    const { users: admins } = await users.json<{ users: { email: string; role: string }[] }>();
+    expect(admins).toContainEqual(expect.objectContaining({ email: admin.email, role: "admin" }));
+
+    const stats = await app.call("/api/admin/auth-stats", { headers: { cookie } });
+    expect(stats.status).toBe(200);
+    const counts = await stats.json<{ totalUsers: number; failedSignIns24h: number }>();
+    expect(counts.totalUsers).toBeGreaterThanOrEqual(1);
+
+    const settings = await app.call("/api/admin/auth-settings", { headers: { cookie } });
+    expect(settings.status).toBe(200);
+    expect(await settings.json()).toHaveProperty("effective");
+  });
+});

package/template/modules/admin/files/web/src/admin-area.tsx

@@ -0,0 +1,140 @@
+import {
+  AdminLink,
+  AdminShell,
+  AuthDashboardPage,
+  AuthInvitationsPage,
+  AuthSettingsPage,
+  AuthUserActions,
+  AuthUserDetailPage,
+  AuthUsersPage,
+  CreateUserButton,
+  type AdminNavItem,
+  type AdminPage,
+  type AdminPageProps,
+  type AdminViewer,
+  type StepUpRequest,
+} from "@awsmbiz/inbis-admin-ui";
+import { SignInScreen, StepUpScreen, usePublicAuthConfig } from "@awsmbiz/inbis-auth-ui";
+import { FlaskConical, KeyRound, LayoutDashboard, MailPlus, Users } from "lucide-react";
+import { Fragment, useCallback, useMemo } from "react";
+import { auth, dashboard, getJson } from "./admin-client.js";
+import { ExamplePage } from "./admin-example.js";
+import { client } from "./auth-client.js";
+import { t } from "./messages.js";
+import type { RouteContext } from "./routes.js";
+// inbis:wire admin.imports
+
+// The admin area on @awsmbiz/inbis-admin-ui, loaded lazily by AdminGate (admin-gate.tsx)
+// for administrators only. It mounts the platform's auth administration pages and the
+// app's own (admin-example.tsx). To add a page of your own: write a component (see
+// admin-example.tsx), then add it to `pages` and, to list it, to `navItems`.
+
+/** A user's page: the platform's sections (profile, sign-in methods, 2FA, sessions), then other modules' (`user` in scope). */
+function UserPage({ params }: AdminPageProps) {
+  return (
+    <AuthUserDetailPage
+      client={auth}
+      userId={params["userId"] ?? ""}
+      actions={(user) => <AuthUserActions client={auth} user={user} />}
+      revokeSessions={auth}
+      sections={(user) => (
+        // Keyed by the user, so other modules' sections start afresh on another user's page.
+        <Fragment key={user.id}>
+          {/* inbis:wire admin.userSections */}
+        </Fragment>
+      )}
+    />
+  );
+}
+
+/** Every admin page, by path under /admin (`:name` is a parameter). The first match wins. */
+const pages: AdminPage[] = [
+  { path: "", title: t("admin.nav.dashboard"), component: () => <AuthDashboardPage client={dashboard} /> },
+  { path: "users", title: t("admin.nav.users"), component: () => <AuthUsersPage client={auth} actions={<CreateUserButton client={auth} />} /> },
+  { path: "users/:userId", title: t("admin.page.user"), component: UserPage },
+  { path: "invitations", title: t("admin.nav.invitations"), component: () => <AuthInvitationsPage client={auth} /> },
+  { path: "settings", title: t("admin.nav.settings"), component: () => <AuthSettingsPage client={auth} /> },
+  // inbis:wire admin.pages
+  // The app's own pages. `component` may be React.lazy(() => import("./my-page.js")).
+  { path: "example", title: t("admin.nav.example"), component: ExamplePage },
+];
+
+/** Whether the app's registration mode lets administrators invite. */
+const invites = (mode: string) => mode === "open" || mode === "invite-only";
+
+/**
+ * The navigation, in order. `visible(viewer)` hides an item the administrator may not use
+ * (e.g. `(viewer) => viewer.permissions.includes("billing.read")`); the server still enforces access.
+ */
+function navItems(invitations: boolean): AdminNavItem[] {
+  return [
+    { to: "", label: t("admin.nav.dashboard"), icon: LayoutDashboard },
+    { to: "users", label: t("admin.nav.users"), icon: Users },
+    ...(invitations ? [{ to: "invitations", label: t("admin.nav.invitations"), icon: MailPlus }] : []),
+    { to: "settings", label: t("admin.nav.settings"), icon: KeyRound },
+    // inbis:wire admin.nav
+    { to: "example", label: t("admin.nav.example"), icon: FlaskConical },
+  ];
+}
+
+/**
+ * The signed-in administrator, from routes that apply the admin policy: an admin-only call
+ * first (refused with TWO_FACTOR_REQUIRED or STEP_UP_REQUIRED until the session meets the
+ * policy, which the shell turns into the step-up screen), then GET /api/me.
+ */
+async function loadViewer(): Promise<AdminViewer> {
+  await auth.admin.listUsers({ query: { limit: 1 } });
+  const { user } = await getJson<{ user: { id: string; name: string; email: string; role: string } }>("/api/me");
+  /** Business permissions, for `visible` predicates; none until the app grants some. */
+  const permissions: string[] = [];
+  // inbis:wire admin.viewer
+  return { id: user.id, name: user.name, email: user.email, role: user.role, permissions };
+}
+
+export function AdminArea({ path, search, navigate }: RouteContext) {
+  const router = useMemo(() => ({ path, search, navigate }), [path, search, navigate]);
+  const publicConfig = usePublicAuthConfig(client);
+  const invitations = publicConfig.status === "ready" && invites(publicConfig.config.registration.mode);
+  const nav = useMemo(() => navItems(invitations), [invitations]);
+  const toSignIn = useCallback(() => {
+    navigate(`/sign-in?next=${encodeURIComponent(window.location.pathname)}`);
+  }, [navigate]);
+  const stepUp = useCallback(
+    ({ reason, retry }: StepUpRequest) =>
+      reason.kind === "recent-sign-in" ? (
+        // A stale sign-in: sign in again right here (password, then the 2FA code). The new
+        // session is fresh, and the refused change runs again with the form as it was.
+        <SignInScreen client={client} onSignedIn={retry} />
+      ) : (
+        <StepUpScreen
+          client={client}
+          requirement={reason}
+          onSatisfied={retry}
+          onSignInAgain={() => {
+            const next = window.location.pathname;
+            void client.signOut().then(() => {
+              navigate(`/sign-in?next=${encodeURIComponent(next)}`);
+            });
+          }}
+        />
+      ),
+    [navigate],
+  );
+  return (
+    <AdminShell
+      title={t("admin.title")}
+      basePath="/admin"
+      router={router}
+      loadViewer={loadViewer}
+      navItems={nav}
+      pages={pages}
+      stepUp={stepUp}
+      onSignInRequired={toSignIn}
+      headerEnd={
+        <AdminLink to="/" className="rounded-md px-2 py-1 text-sm font-medium underline-offset-4 outline-none hover:underline focus-visible:ring-3 focus-visible:ring-ring/50">
+          {t("admin.backToApp")}
+        </AdminLink>
+      }
+    />
+  );
+}

package/template/modules/admin/files/web/src/admin-client.ts

@@ -0,0 +1,49 @@
+import type { AuthDashboardClient } from "@awsmbiz/inbis-admin-ui";
+import { ApiError, createAuthAdminClient } from "@awsmbiz/inbis-api-client";
+
+/**
+ * One client for every auth administration page: the admin API (src/admin.ts) and Better
+ * Auth's admin routes. Admin pages of other modules import it from here.
+ */
+export const auth = createAuthAdminClient();
+
+/** A same-origin JSON GET; failures reject with an `ApiError` (what the admin pages' error states show). */
+export async function getJson<T>(url: string, init: { signal?: AbortSignal } = {}): Promise<T> {
+  let response: Response;
+  try {
+    response = await fetch(url, { credentials: "include", ...(init.signal === undefined ? {} : { signal: init.signal }) });
+  } catch (cause) {
+    throw ApiError.network(cause);
+  }
+  if (!response.ok) throw await ApiError.fromResponse(response);
+  return (await response.json()) as T;
+}
+
+interface AuthHistoryEvent {
+  id: string;
+  action: string;
+  actorId: string | null;
+  resource: string | null;
+  occurredAt: string;
+  requestId: string | null;
+  metadata: Record<string, unknown> | null;
+}
+
+/**
+ * The dashboard's data. Its recent activity reads GET /api/admin/auth-audit-events: auth's
+ * own history, or with the audit module the whole audit trail.
+ */
+export const dashboard: AuthDashboardClient = {
+  stats: (init) => auth.stats(init),
+  auditEvents: {
+    list: async (query = {}, init = {}) => {
+      const search = new URLSearchParams({ limit: String(query.limit ?? 10) });
+      if (query.cursor !== undefined) search.set("cursor", query.cursor);
+      const body = await getJson<{ items: AuthHistoryEvent[]; nextCursor: string | null }>(`/api/admin/auth-audit-events?${search.toString()}`, init);
+      return {
+        items: body.items.map(({ resource, occurredAt, ...event }) => ({ ...event, subjectId: resource, occurredAt: new Date(occurredAt) })),
+        nextCursor: body.nextCursor,
+      };
+    },
+  },
+};

package/template/modules/admin/files/web/src/admin-example.tsx

@@ -0,0 +1,62 @@
+import { ErrorState, LoadingState, PageHeader, useAdmin } from "@awsmbiz/inbis-admin-ui";
+import { Button, Card, CardContent, Input, Label } from "@awsmbiz/inbis-ui";
+import { useQuery } from "@tanstack/react-query";
+import { useId, useState, type SyntheticEvent } from "react";
+import { getJson } from "./admin-client.js";
+import { t } from "./messages.js";
+
+/**
+ * An admin page of the app's own, next to the platform's: replace it with your product's
+ * administration. It uses what the platform's pages use: `useAdmin()` (step-up, navigation),
+ * `PageHeader` for the page's one <h1>, the page states, and TanStack Query (the admin shell
+ * provides the QueryClient). Its data comes from the app's own API (`GET /v1/hello`, src/v1.ts);
+ * guard your own admin routes with `requireAdmin()` from `@awsmbiz/inbis-auth/hono`.
+ * It is listed in `pages` and `navItems` in admin-area.tsx.
+ */
+export function ExamplePage() {
+  const { withStepUp } = useAdmin();
+  const nameId = useId();
+  const [draft, setDraft] = useState("");
+  const [name, setName] = useState<string | null>(null);
+  const greeting = useQuery({
+    queryKey: ["example", "hello", name],
+    enabled: name !== null,
+    // withStepUp: a call refused because the session must verify first re-runs once it has.
+    queryFn: ({ signal }) => withStepUp(() => getJson<{ message: string }>(`/v1/hello?name=${encodeURIComponent(name ?? "")}`, { signal })),
+  });
+
+  const submit = (event: SyntheticEvent) => {
+    event.preventDefault();
+    if (draft.trim() !== "") setName(draft.trim());
+  };
+
+  return (
+    <>
+      <PageHeader title={t("admin.example.title")} description={t("admin.example.description")} />
+      <Card>
+        <CardContent className="flex flex-col gap-4">
+          <form onSubmit={submit} className="flex flex-col gap-2 sm:flex-row sm:items-end">
+            <div className="flex flex-1 flex-col gap-2">
+              <Label htmlFor={nameId}>{t("admin.example.name")}</Label>
+              <Input
+                id={nameId}
+                value={draft}
+                maxLength={100}
+                onChange={(event) => {
+                  setDraft(event.target.value);
+                }}
+              />
+            </div>
+            <Button type="submit">{t("admin.example.submit")}</Button>
+          </form>
+          {name !== null && greeting.isPending ? <LoadingState label={t("admin.example.loading")} className="py-2" /> : null}
+          {greeting.isError ? <ErrorState title={t("admin.example.failed")} error={greeting.error} onRetry={() => void greeting.refetch()} /> : null}
+          {/* Always in the page, so screen readers announce the answer when it arrives. */}
+          <p role="status" className="text-sm">
+            {greeting.isSuccess ? greeting.data.message : ""}
+          </p>
+        </CardContent>
+      </Card>
+    </>
+  );
+}

package/template/modules/admin/files/web/src/admin-gate.tsx

@@ -0,0 +1,112 @@
+import { accessRequirementOf, type AccessRequirement } from "@awsmbiz/inbis-auth/client";
+import { StepUpScreen } from "@awsmbiz/inbis-auth-ui";
+import { Button, Card, CardContent, CardDescription, CardHeader, CardTitle } from "@awsmbiz/inbis-ui";
+import { lazy, Suspense, useEffect, useState } from "react";
+import { client } from "./auth-client.js";
+import { t } from "./messages.js";
+import type { RouteContext } from "./routes.js";
+
+// The admin area (@awsmbiz/inbis-admin-ui and its pages) is its own chunk, downloaded only
+// once GET /api/me says the visitor is an administrator (plan Q16).
+const AdminArea = lazy(() => import("./admin-area.js").then((module) => ({ default: module.AdminArea })));
+
+type Gate = { kind: "checking" } | { kind: "admin" } | { kind: "refused" } | { kind: "failed" } | { kind: "challenge"; requirement: AccessRequirement };
+
+function Checking() {
+  return (
+    <main className="p-4">
+      <h1 className="sr-only">{t("admin.title")}</h1>
+      <p role="status" className="text-sm text-muted-foreground">
+        {t("common.loading")}
+      </p>
+    </main>
+  );
+}
+
+/**
+ * `/admin` and below. Checks the signed-in user's role before loading any admin code:
+ * a signed-out visitor goes to sign-in (and comes back), a session that needs a second
+ * factor completes it here, and anyone else but an administrator is refused without
+ * downloading the admin bundle. The admin API enforces access itself (src/admin.ts);
+ * this only decides what to load.
+ */
+export function AdminGate({ path, search, navigate }: RouteContext) {
+  const [gate, setGate] = useState<Gate>({ kind: "checking" });
+  const [attempt, setAttempt] = useState(0);
+
+  useEffect(() => {
+    let active = true;
+    fetch("/api/me", { credentials: "include" }).then(
+      async (response) => {
+        if (!active) return;
+        if (response.status === 401) {
+          navigate(`/sign-in?next=${encodeURIComponent(window.location.pathname)}`, { replace: true });
+          return;
+        }
+        const requirement = await accessRequirementOf(response.clone());
+        if (requirement !== null) setGate({ kind: "challenge", requirement });
+        else if (!response.ok) setGate({ kind: "failed" });
+        else {
+          const { user } = (await response.json()) as { user: { role: string } };
+          setGate({ kind: user.role === "admin" ? "admin" : "refused" });
+        }
+      },
+      () => {
+        if (active) setGate({ kind: "failed" });
+      },
+    );
+    return () => {
+      active = false;
+    };
+    // The role is checked once per visit to the admin area, not on every admin page.
+  }, [navigate, attempt]);
+
+  if (gate.kind === "checking") return <Checking />;
+  if (gate.kind === "admin") {
+    return (
+      <Suspense fallback={<Checking />}>
+        <AdminArea path={path} search={search} navigate={navigate} />
+      </Suspense>
+    );
+  }
+  if (gate.kind === "challenge") {
+    return (
+      <StepUpScreen
+        client={client}
+        requirement={gate.requirement}
+        onSatisfied={() => {
+          setGate({ kind: "checking" });
+          setAttempt((n) => n + 1);
+        }}
+        onSignInAgain={() => {
+          const next = window.location.pathname;
+          void client.signOut().then(() => {
+            navigate(`/sign-in?next=${encodeURIComponent(next)}`);
+          });
+        }}
+      />
+    );
+  }
+  return (
+    <main className="flex min-h-svh items-center justify-center bg-muted/40 p-4">
+      <Card className="w-full max-w-sm">
+        <CardHeader>
+          <CardTitle>
+            <h1>{t("admin.notAllowed")}</h1>
+          </CardTitle>
+          <CardDescription>{gate.kind === "refused" ? t("admin.refused") : t("admin.failed")}</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <Button
+            variant="outline"
+            onClick={() => {
+              navigate("/");
+            }}
+          >
+            {t("admin.home")}
+          </Button>
+        </CardContent>
+      </Card>
+    </main>
+  );
+}

package/template/modules/admin/module.json

@@ -0,0 +1,50 @@
+{
+  "name": "admin",
+  "description": "The admin area: a lazily loaded, admin-gated /admin on @awsmbiz/inbis-admin-ui with the auth administration pages (dashboard, users, invitations, settings; activity with audit) and an example page of the app's own.",
+  "order": 40,
+  "requires": ["auth"],
+  "dependencies": {
+    "@awsmbiz/inbis-admin-ui": "workspace:*",
+    "@awsmbiz/inbis-api-client": "workspace:*",
+    "@awsmbiz/inbis-ui": "workspace:*",
+    "@tanstack/react-query": "5.104.3",
+    "lucide-react": "1.65.0"
+  },
+  "points": {
+    "admin.server.imports": { "file": "src/admin.ts", "description": "Imports for the admin API wiring." },
+    "admin.stats": { "file": "src/admin.ts", "description": "Properties of mountAuthStats' options (failedSignIns, activeUsers), comma-terminated." },
+    "admin.authAudit": { "file": "src/admin.ts", "description": "Properties of mountAuthAudit's options (list), comma-terminated." },
+    "admin.imports": { "file": "web/src/admin-area.tsx", "description": "Imports for the admin area. Import from a file of the module's own (not from packages admin-area.tsx already imports)." },
+    "admin.pages": { "file": "web/src/admin-area.tsx", "description": "AdminPage entries (path relative to /admin, title, component), comma-terminated; before the app's own pages." },
+    "admin.nav": { "file": "web/src/admin-area.tsx", "description": "AdminNavItem entries (to, label, icon, visible), comma-terminated; before the app's own items." },
+    "admin.userSections": { "file": "web/src/admin-area.tsx", "description": "JSX sections of a user's admin page, inside the `sections={(user) => …}` fragment (`user`: AdminUserDetail in scope); wrap each in UserDetailSection." },
+    "admin.viewer": { "file": "web/src/admin-area.tsx", "description": "Statements in loadViewer that add the administrator's business permissions to `permissions` (for `visible` predicates); `user` is in scope." }
+  },
+  "wiring": {
+    "worker.imports": "wiring/worker.imports.ts",
+    "worker.routes": "wiring/worker.routes.ts",
+    "web.routes.imports": "wiring/web.routes.imports.tsx",
+    "web.routes": "wiring/web.routes.tsx",
+    "web.messages": "wiring/web.messages.ts",
+    "web.styles": "wiring/web.styles.css",
+    "account.sections": "wiring/account.sections.tsx",
+    "readme.modules": "wiring/readme.modules.md"
+  },
+  "when": [
+    {
+      "modules": ["audit"],
+      "files": "with-audit",
+      "wiring": {
+        "admin.server.imports": "wiring/audit/admin.server.imports.ts",
+        "admin.stats": "wiring/audit/admin.stats.ts",
+        "admin.authAudit": "wiring/audit/admin.authAudit.ts",
+        "admin.imports": "wiring/audit/admin.imports.tsx",
+        "admin.pages": "wiring/audit/admin.pages.tsx",
+        "admin.nav": "wiring/audit/admin.nav.tsx",
+        "admin.userSections": "wiring/audit/admin.userSections.tsx",
+        "web.messages": "wiring/audit/web.messages.ts",
+        "readme.modules": "wiring/audit/readme.modules.md"
+      }
+    }
+  ]
+}

package/template/modules/admin/wiring/account.sections.tsx

@@ -0,0 +1,16 @@
+{/* The admin area (admin module), for administrators. */}
+{me.user.role === "admin" ? (
+  <Card>
+    <CardHeader>
+      <CardTitle>
+        <h2>{t("account.administration")}</h2>
+      </CardTitle>
+      <CardDescription>{t("account.administrationDescription")}</CardDescription>
+    </CardHeader>
+    <CardContent>
+      <Link href="/admin" navigate={navigate} className={linkClass}>
+        {t("account.openAdministration")}
+      </Link>
+    </CardContent>
+  </Card>
+) : null}

package/template/modules/admin/wiring/audit/admin.authAudit.ts

@@ -0,0 +1,2 @@
+// Read from the audit trail (audit module), in auth's record shape.
+list: (c, input) => listAuthAuditEvents(auditLog(c.env, { logger: c.var.logger }), input),

package/template/modules/admin/wiring/audit/admin.imports.tsx

@@ -0,0 +1 @@
+import { activityNavItem, activityPage, UserActivity } from "./admin-activity.js";

package/template/modules/admin/wiring/audit/admin.nav.tsx

@@ -0,0 +1 @@
+activityNavItem,

package/template/modules/admin/wiring/audit/admin.pages.tsx

@@ -0,0 +1 @@
+activityPage,

package/template/modules/admin/wiring/audit/admin.server.imports.ts

@@ -0,0 +1,3 @@
+import { AUTH_AUDIT_ACTIONS } from "@awsmbiz/inbis-auth";
+import { listAuthAuditEvents } from "@awsmbiz/inbis-audit";
+import { auditLog } from "./audit-log.js";

package/template/modules/admin/wiring/audit/admin.stats.ts

@@ -0,0 +1,3 @@
+// The audit trail (audit module) counts: failed sign-ins, and distinct users who signed in.
+failedSignIns: (c, since) => auditLog(c.env, { logger: c.var.logger }).count({ action: AUTH_AUDIT_ACTIONS.signInFailed, from: since }),
+activeUsers: (c, since) => auditLog(c.env, { logger: c.var.logger }).countActors({ action: AUTH_AUDIT_ACTIONS.signInSucceeded, from: since }),

package/template/modules/admin/wiring/audit/admin.userSections.tsx

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

package/template/modules/admin/wiring/audit/readme.modules.md

@@ -0,0 +1,4 @@
+With the audit trail (the `audit` module), the admin area adds an **Activity** page (every
+event, `GET /api/admin/audit-events`) and each user's recent activity on their page
+(`web/src/admin-activity.tsx`), and the dashboard's counts and recent activity read the
+trail (`src/admin.ts`).

package/template/modules/admin/wiring/audit/web.messages.ts

@@ -0,0 +1 @@
+"admin.nav.activity": "Activity",

package/template/modules/admin/wiring/readme.modules.md

@@ -0,0 +1,26 @@
+## Admin area (admin module)
+
+`@awsmbiz/inbis-admin-ui` (the admin shell and the auth administration pages) on
+`@awsmbiz/inbis-api-client`, at `/admin`.
+
+- **Who gets in** — administrators (`role` `admin`) with 2FA, signed in with an allowed
+  admin method (the admin policy). `web/src/admin-gate.tsx` checks `GET /api/me` before
+  loading anything: visitors go to sign-in and come back, a session that needs a second
+  factor completes it in place, and other users are refused without downloading the admin
+  code (`web/src/admin-area.tsx` is its own chunk). Administrators find the area on their
+  account page.
+- **API** — `src/admin.ts` mounts the admin API (`/api/admin/users`, `/api/admin/auth-stats`,
+  `/api/admin/auth-settings`, `/api/admin/auth-providers/status`,
+  `/api/admin/auth-audit-events`); Better Auth's admin routes (`/api/auth/admin/*`) and the
+  invitation routes come with sign-in. Every route applies the admin policy; changes also
+  need a recent sign-in, which the area asks for in place and then runs the change again.
+- **Pages** — dashboard, users (create, change role, ban, revoke sessions, reset 2FA,
+  delete), invitations (when the registration mode allows them) and auth settings.
+- **Your own pages** — `web/src/admin-example.tsx` is an example page on the app's own API.
+  Copy it, add the component to `pages` and an item to `navItems` in
+  `web/src/admin-area.tsx`, and guard its API routes with `requireAdmin()` (plus
+  `requireRecentAdminSignIn()` for changes) from `@awsmbiz/inbis-auth/hono`. Delete the
+  example when you have pages of your own.
+- **Tests** — `test/admin.test.ts` (Workers) and `e2e/admin-*.spec.ts` (Playwright + axe:
+  the gate, a change that needs a recent sign-in, every page in both themes at desktop and
+  phone sizes).

package/template/modules/admin/wiring/web.messages.ts

@@ -0,0 +1,22 @@
+// The admin area (admin module). The platform's admin pages bring their own text (@awsmbiz/inbis-admin-ui).
+"admin.title": "Administration",
+"admin.notAllowed": "Not allowed",
+"admin.refused": "The admin area is for administrators.",
+"admin.failed": "The admin area could not be loaded. Check your connection and try again.",
+"admin.home": "Go to the home page",
+"admin.backToApp": "Back to the app",
+"admin.nav.dashboard": "Dashboard",
+"admin.nav.users": "Users",
+"admin.nav.invitations": "Invitations",
+"admin.nav.settings": "Auth settings",
+"admin.nav.example": "Example",
+"admin.page.user": "User",
+"admin.example.title": "Example page",
+"admin.example.description": "A page of the app's own, next to the platform's. Replace it with your product's administration (web/src/admin-example.tsx).",
+"admin.example.name": "Name",
+"admin.example.submit": "Greet",
+"admin.example.loading": "Asking the API…",
+"admin.example.failed": "The API did not answer",
+"account.administration": "Administration",
+"account.administrationDescription": "Manage users, invitations and sign-in settings.",
+"account.openAdministration": "Open the admin area",

package/template/modules/admin/wiring/web.routes.imports.tsx

@@ -0,0 +1 @@
+import { AdminGate } from "./admin-gate.js";

package/template/modules/admin/wiring/web.routes.tsx

@@ -0,0 +1,2 @@
+// The admin area (admin module): gated on the administrator role, loaded lazily (web/src/admin-gate.tsx).
+{ path: "/admin/*", title: "admin.title", bare: true, render: (c) => <AdminGate {...c} /> },

package/template/modules/admin/wiring/web.styles.css

@@ -0,0 +1 @@
+@import "@awsmbiz/inbis-admin-ui/styles.css";

package/template/modules/admin/wiring/worker.imports.ts

@@ -0,0 +1 @@
+import { mountAppAdmin } from "./admin.js";

package/template/modules/admin/wiring/worker.routes.ts

@@ -0,0 +1,2 @@
+// Admin area API (admin module, src/admin.ts): users, dashboard counts, auth settings, auth history.
+mountAppAdmin(app);

package/template/modules/admin/with-audit/e2e/admin-activity.spec.ts

@@ -0,0 +1,37 @@
+import { expect, test } from "@playwright/test";
+import { signInAsAdmin } from "./admin-helpers.js";
+import { adminsCanSignIn, USERS } from "./auth-seeded.js";
+import { expectNoPageScroll, expectNoViolations, THEMES, VIEWPORTS } from "./axe.js";
+
+// With the audit trail (audit module), the admin area has an Activity page over every
+// event, and each user's page lists their recent activity.
+
+test.skip(!adminsCanSignIn, "administrators need email + password and 2FA (src/auth-choices.ts)");
+
+test("an administrator finds their own sign-in in the activity, and on their user page", async ({ page, baseURL }) => {
+  await signInAsAdmin(page, baseURL);
+  await page.goto("/admin");
+  await page.getByRole("navigation", { name: "Administration" }).getByRole("link", { name: "Activity" }).click();
+  await expect(page.getByRole("heading", { level: 1, name: "Activity" })).toBeVisible();
+  await expect(page.getByRole("table", { name: "Activity" }).getByText("auth.sign_in.succeeded").first()).toBeVisible();
+
+  await page.goto("/admin/users");
+  await page.getByRole("table", { name: "Users" }).getByRole("link", { name: USERS.admin.name }).click();
+  await expect(page.getByRole("heading", { level: 1, name: USERS.admin.name })).toBeVisible();
+  await expect(page.getByRole("region", { name: "Recent activity" })).toContainText("auth.sign_in.succeeded");
+});
+
+for (const theme of THEMES) {
+  for (const [viewport, size] of Object.entries(VIEWPORTS)) {
+    test(`the activity page (${theme}, ${viewport}) has no accessibility violations`, async ({ page, baseURL }) => {
+      await page.emulateMedia({ colorScheme: theme });
+      await page.setViewportSize(size);
+      await signInAsAdmin(page, baseURL);
+      await page.goto("/admin/activity");
+      await expect(page.getByRole("heading", { level: 1, name: "Activity" })).toBeVisible();
+      await expect(page.getByRole("table", { name: "Activity" }).getByRole("row").nth(1)).toBeVisible();
+      await expectNoPageScroll(page);
+      await expectNoViolations(page);
+    });
+  }
+}