From 7fe6b10788fb033ea0517041c5fafabb46d78178 Mon Sep 17 00:00:00 2001
From: fuomag9 <1580624+fuomag9@users.noreply.github.com>
Date: Mon, 6 Apr 2026 00:58:22 +0200
Subject: [PATCH] Add E2E tests for untested pages and enforce role-based
 access control

Allow non-admin users (user/viewer) to access / and /profile while
blocking admin-only pages. The dashboard layout now uses requireUser()
instead of requireAdmin(), and the sidebar filters nav items by role.
Non-admin users see a minimal welcome page without stat cards.

New test files (86 tests across 7 files):
- dashboard, users, groups, api-docs, portal, link-account specs
- role-access spec with full RBAC coverage for all 3 roles

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 app/(dashboard)/DashboardLayoutClient.tsx |  29 +-
 app/(dashboard)/layout.tsx                |   4 +-
 app/(dashboard)/page.tsx                  |  18 +-
 tests/e2e/api-docs.spec.ts                |  38 +++
 tests/e2e/dashboard.spec.ts               |  50 ++++
 tests/e2e/groups.spec.ts                  | 109 +++++++
 tests/e2e/link-account.spec.ts            |  42 +++
 tests/e2e/portal.spec.ts                  |  50 ++++
 tests/e2e/role-access.spec.ts             | 337 ++++++++++++++++++++++
 tests/e2e/users.spec.ts                   |  80 +++++
 10 files changed, 740 insertions(+), 17 deletions(-)
 create mode 100644 tests/e2e/api-docs.spec.ts
 create mode 100644 tests/e2e/dashboard.spec.ts
 create mode 100644 tests/e2e/groups.spec.ts
 create mode 100644 tests/e2e/link-account.spec.ts
 create mode 100644 tests/e2e/portal.spec.ts
 create mode 100644 tests/e2e/role-access.spec.ts
 create mode 100644 tests/e2e/users.spec.ts

diff --git a/app/(dashboard)/DashboardLayoutClient.tsx b/app/(dashboard)/DashboardLayoutClient.tsx
index b521400f..2f8a0290 100644
--- a/app/(dashboard)/DashboardLayoutClient.tsx
+++ b/app/(dashboard)/DashboardLayoutClient.tsx
@@ -21,21 +21,22 @@ type User = {
   name?: string | null;
   email?: string | null;
   image?: string | null;
+  role?: string;
 };
 
 const NAV_ITEMS = [
-  { href: "/",               label: "Overview",       icon: LayoutDashboard },
-  { href: "/proxy-hosts",    label: "Proxy Hosts",    icon: ArrowLeftRight  },
-  { href: "/l4-proxy-hosts", label: "L4 Proxy Hosts", icon: Cable           },
-  { href: "/access-lists",   label: "Access Lists",   icon: KeyRound        },
-  { href: "/groups",          label: "Groups",          icon: Users           },
-  { href: "/users",           label: "Users",           icon: UserCog         },
-  { href: "/certificates",   label: "Certificates",   icon: ShieldCheck     },
-  { href: "/waf",            label: "WAF",            icon: ShieldOff       },
-  { href: "/analytics",      label: "Analytics",      icon: BarChart2       },
-  { href: "/audit-log",      label: "Audit Log",      icon: History         },
-  { href: "/api-docs",       label: "API Docs",       icon: FileJson2       },
-  { href: "/settings",       label: "Settings",       icon: Settings        },
+  { href: "/",               label: "Overview",       icon: LayoutDashboard, adminOnly: false },
+  { href: "/proxy-hosts",    label: "Proxy Hosts",    icon: ArrowLeftRight,  adminOnly: true  },
+  { href: "/l4-proxy-hosts", label: "L4 Proxy Hosts", icon: Cable,           adminOnly: true  },
+  { href: "/access-lists",   label: "Access Lists",   icon: KeyRound,        adminOnly: true  },
+  { href: "/groups",          label: "Groups",          icon: Users,           adminOnly: true  },
+  { href: "/users",           label: "Users",           icon: UserCog,         adminOnly: true  },
+  { href: "/certificates",   label: "Certificates",   icon: ShieldCheck,     adminOnly: true  },
+  { href: "/waf",            label: "WAF",            icon: ShieldOff,       adminOnly: true  },
+  { href: "/analytics",      label: "Analytics",      icon: BarChart2,       adminOnly: true  },
+  { href: "/audit-log",      label: "Audit Log",      icon: History,         adminOnly: true  },
+  { href: "/api-docs",       label: "API Docs",       icon: FileJson2,       adminOnly: true  },
+  { href: "/settings",       label: "Settings",       icon: Settings,        adminOnly: true  },
 ] as const;
 
 function ThemeToggle() {
@@ -59,6 +60,8 @@ function NavContent({ pathname, user, onNavigate }: {
   onNavigate?: () => void;
 }) {
   const router = useRouter();
+  const isAdmin = user.role === "admin";
+  const visibleItems = NAV_ITEMS.filter((item) => !item.adminOnly || isAdmin);
 
   return (
     <div className="flex flex-col h-full">
@@ -74,7 +77,7 @@ function NavContent({ pathname, user, onNavigate }: {
       {/* Nav items */}
       <ScrollArea className="flex-1 px-2 py-2">
         <nav className="flex flex-col gap-0.5">
-          {NAV_ITEMS.map(({ href, label, icon: Icon }) => {
+          {visibleItems.map(({ href, label, icon: Icon }) => {
             const active = pathname === href;
             return (
               <Button
diff --git a/app/(dashboard)/layout.tsx b/app/(dashboard)/layout.tsx
index 498f2dd0..bde3fb40 100644
--- a/app/(dashboard)/layout.tsx
+++ b/app/(dashboard)/layout.tsx
@@ -1,8 +1,8 @@
 import type { ReactNode } from "react";
-import { requireAdmin } from "@/src/lib/auth";
+import { requireUser } from "@/src/lib/auth";
 import DashboardLayoutClient from "./DashboardLayoutClient";
 
 export default async function DashboardLayout({ children }: { children: ReactNode }) {
-  const session = await requireAdmin();
+  const session = await requireUser();
   return <DashboardLayoutClient user={session.user}>{children}</DashboardLayoutClient>;
 }
diff --git a/app/(dashboard)/page.tsx b/app/(dashboard)/page.tsx
index 226ae954..22ef1a50 100644
--- a/app/(dashboard)/page.tsx
+++ b/app/(dashboard)/page.tsx
@@ -1,5 +1,5 @@
 import db, { toIso } from "@/src/lib/db";
-import { requireAdmin } from "@/src/lib/auth";
+import { requireUser } from "@/src/lib/auth";
 import OverviewClient from "./OverviewClient";
 import {
   accessLists,
@@ -43,7 +43,21 @@ async function loadStats(): Promise<StatCard[]> {
 }
 
 export default async function OverviewPage() {
-  const session = await requireAdmin();
+  const session = await requireUser();
+  const isAdmin = session.user.role === "admin";
+
+  // Non-admin users see a minimal welcome page
+  if (!isAdmin) {
+    return (
+      <OverviewClient
+        userName={session.user.name ?? session.user.email ?? "User"}
+        stats={[]}
+        trafficSummary={null}
+        recentEvents={[]}
+      />
+    );
+  }
+
   const [stats, trafficSummary, recentEventsRaw] = await Promise.all([
     loadStats(),
     getAnalyticsSummary(Math.floor(Date.now() / 1000) - 86400, Math.floor(Date.now() / 1000), []).catch(() => null),
diff --git a/tests/e2e/api-docs.spec.ts b/tests/e2e/api-docs.spec.ts
new file mode 100644
index 00000000..c84dc6d0
--- /dev/null
+++ b/tests/e2e/api-docs.spec.ts
@@ -0,0 +1,38 @@
+/**
+ * E2E tests: API Docs page (OpenAPI / Swagger UI).
+ *
+ * Verifies the page loads and Swagger UI renders the OpenAPI spec.
+ * The page requires admin role.
+ */
+import { test, expect } from '@playwright/test';
+
+test.describe('API Docs page', () => {
+  test('page loads without error', async ({ page }) => {
+    await page.goto('/api-docs');
+    await expect(page).not.toHaveURL(/login/);
+  });
+
+  test('Swagger UI renders with API information', async ({ page }) => {
+    await page.goto('/api-docs');
+
+    // Swagger UI loads the spec and renders info — wait for the info container
+    await expect(page.locator('.swagger-ui')).toBeVisible({ timeout: 30_000 });
+  });
+
+  test('OpenAPI spec endpoint returns valid JSON', async ({ request }) => {
+    const response = await request.get('/api/v1/openapi.json');
+    expect(response.status()).toBe(200);
+    const body = await response.json();
+    expect(body).toHaveProperty('openapi');
+    expect(body).toHaveProperty('paths');
+  });
+});
+
+test.describe('API Docs page — unauthenticated access', () => {
+  test.use({ storageState: { cookies: [], origins: [] } });
+
+  test('unauthenticated access to /api-docs redirects to /login', async ({ page }) => {
+    await page.goto('/api-docs');
+    await expect(page).toHaveURL(/\/login/);
+  });
+});
diff --git a/tests/e2e/dashboard.spec.ts b/tests/e2e/dashboard.spec.ts
new file mode 100644
index 00000000..09ee5797
--- /dev/null
+++ b/tests/e2e/dashboard.spec.ts
@@ -0,0 +1,50 @@
+/**
+ * E2E tests: Dashboard (overview) home page.
+ *
+ * Verifies stat cards, navigation links, welcome header, and recent activity.
+ */
+import { test, expect } from '@playwright/test';
+
+test.describe('Dashboard home page', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/');
+  });
+
+  test('displays welcome header with user name', async ({ page }) => {
+    await expect(page.getByText(/welcome back/i)).toBeVisible();
+  });
+
+  test('shows stat cards for Proxy Hosts, Certificates, and Access Lists', async ({ page }) => {
+    await expect(page.getByText('Proxy Hosts')).toBeVisible();
+    await expect(page.getByText('Certificates')).toBeVisible();
+    await expect(page.getByText('Access Lists')).toBeVisible();
+  });
+
+  test('shows Traffic (24h) card', async ({ page }) => {
+    await expect(page.getByText('Traffic (24h)')).toBeVisible();
+  });
+
+  test('stat card links navigate to correct pages', async ({ page }) => {
+    await page.getByRole('link', { name: /proxy hosts/i }).first().click();
+    await expect(page).toHaveURL(/\/proxy-hosts/);
+  });
+
+  test('Certificates stat card navigates to /certificates', async ({ page }) => {
+    await page.getByRole('link', { name: /certificates/i }).first().click();
+    await expect(page).toHaveURL(/\/certificates/);
+  });
+
+  test('Access Lists stat card navigates to /access-lists', async ({ page }) => {
+    await page.getByRole('link', { name: /access lists/i }).first().click();
+    await expect(page).toHaveURL(/\/access-lists/);
+  });
+
+  test('Traffic card navigates to /analytics', async ({ page }) => {
+    await page.getByRole('link', { name: /traffic/i }).first().click();
+    await expect(page).toHaveURL(/\/analytics/);
+  });
+
+  test('shows Recent Activity section', async ({ page }) => {
+    await expect(page.getByText(/recent activity/i)).toBeVisible();
+  });
+});
diff --git a/tests/e2e/groups.spec.ts b/tests/e2e/groups.spec.ts
new file mode 100644
index 00000000..e6273841
--- /dev/null
+++ b/tests/e2e/groups.spec.ts
@@ -0,0 +1,109 @@
+/**
+ * E2E tests: Groups management page.
+ *
+ * Verifies group creation, member management, and deletion.
+ * Runs as admin (testadmin) — the page requires admin role.
+ */
+import { test, expect } from '@playwright/test';
+
+test.describe('Groups page', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/groups');
+  });
+
+  test('page loads with Groups heading', async ({ page }) => {
+    await expect(page.getByRole('heading', { name: 'Groups' })).toBeVisible();
+    await expect(page.getByText('Organize users into groups for forward auth access control.')).toBeVisible();
+  });
+
+  test('New Group button is visible', async ({ page }) => {
+    await expect(page.getByRole('button', { name: /new group/i })).toBeVisible();
+  });
+
+  test('clicking New Group toggles create form', async ({ page }) => {
+    await page.getByRole('button', { name: /new group/i }).click();
+
+    // Form fields should appear
+    await expect(page.getByLabel('Name')).toBeVisible();
+    await expect(page.getByLabel('Description')).toBeVisible();
+    await expect(page.getByRole('button', { name: 'Create' })).toBeVisible();
+    await expect(page.getByRole('button', { name: 'Cancel' })).toBeVisible();
+  });
+
+  test('clicking Cancel hides the create form', async ({ page }) => {
+    await page.getByRole('button', { name: /new group/i }).click();
+    await expect(page.getByLabel('Name')).toBeVisible();
+
+    await page.getByRole('button', { name: 'Cancel' }).click();
+    await expect(page.getByLabel('Name')).not.toBeVisible();
+  });
+
+  test('create a new group', async ({ page }) => {
+    await page.getByRole('button', { name: /new group/i }).click();
+
+    await page.getByLabel('Name').fill('E2E Test Group');
+    await page.getByLabel('Description').fill('Created by E2E test');
+    await page.getByRole('button', { name: 'Create' }).click();
+
+    // Group should appear in the list
+    await expect(page.getByText('E2E Test Group')).toBeVisible({ timeout: 10_000 });
+    await expect(page.getByText('Created by E2E test')).toBeVisible();
+    await expect(page.getByText('0 members')).toBeVisible();
+  });
+
+  test('add member to group', async ({ page }) => {
+    // Ensure the group exists
+    await expect(page.getByText('E2E Test Group')).toBeVisible({ timeout: 5_000 });
+
+    // Click add member button
+    await page.getByTitle('Add member').first().click();
+    await expect(page.getByText('Add a user to this group')).toBeVisible();
+
+    // Click the first available user to add them
+    const userButton = page.locator('button', { hasText: /testadmin/ });
+    if (await userButton.isVisible()) {
+      await userButton.click();
+
+      // Member should now appear in the group
+      await expect(page.getByText('1 member')).toBeVisible({ timeout: 10_000 });
+    }
+  });
+
+  test('remove member from group', async ({ page }) => {
+    // If the group has a member, remove it
+    const removeMemberBtn = page.getByTitle('Remove member').first();
+    if (await removeMemberBtn.isVisible({ timeout: 3_000 }).catch(() => false)) {
+      await removeMemberBtn.click();
+      await expect(page.getByText('0 members')).toBeVisible({ timeout: 10_000 });
+    }
+  });
+
+  test('delete group via confirm dialog', async ({ page }) => {
+    await expect(page.getByText('E2E Test Group')).toBeVisible({ timeout: 5_000 });
+
+    // Accept the confirm dialog
+    page.on('dialog', (dialog) => dialog.accept());
+    await page.getByTitle('Delete group').first().click();
+
+    // Group should be removed
+    await expect(page.getByText('E2E Test Group')).not.toBeVisible({ timeout: 10_000 });
+  });
+
+  test('shows empty state when no groups exist', async ({ page }) => {
+    // If there are no groups, the empty state text should be visible
+    // (This may or may not show depending on existing data)
+    const emptyText = page.getByText('No groups yet. Create one to organize user access.');
+    const newGroupBtn = page.getByRole('button', { name: /new group/i });
+    // At minimum the button should always be visible
+    await expect(newGroupBtn).toBeVisible();
+  });
+});
+
+test.describe('Groups page — unauthenticated access', () => {
+  test.use({ storageState: { cookies: [], origins: [] } });
+
+  test('unauthenticated access to /groups redirects to /login', async ({ page }) => {
+    await page.goto('/groups');
+    await expect(page).toHaveURL(/\/login/);
+  });
+});
diff --git a/tests/e2e/link-account.spec.ts b/tests/e2e/link-account.spec.ts
new file mode 100644
index 00000000..e0d4e38d
--- /dev/null
+++ b/tests/e2e/link-account.spec.ts
@@ -0,0 +1,42 @@
+/**
+ * E2E tests: Link Account page (/link-account).
+ *
+ * This page requires a valid LINKING_REQUIRED: error param with a valid JWT linking token.
+ * Without that, it redirects to /login. We test the redirect behavior and the fallback
+ * "Sign in with Password Instead" button.
+ */
+import { test, expect } from '@playwright/test';
+
+test.use({ storageState: { cookies: [], origins: [] } });
+
+test.describe('Link Account page', () => {
+  test('redirects to /login when no error param is provided', async ({ page }) => {
+    await page.goto('/link-account');
+    await expect(page).toHaveURL(/\/login/, { timeout: 10_000 });
+  });
+
+  test('redirects to /login with invalid linking token', async ({ page }) => {
+    await page.goto('/link-account?error=LINKING_REQUIRED:invalid-token');
+    await expect(page).toHaveURL(/\/login/, { timeout: 10_000 });
+    // Should include an error about expired or invalid token
+    await expect(page).toHaveURL(/error=/);
+  });
+
+  test('redirects to /login when error param is not LINKING_REQUIRED', async ({ page }) => {
+    await page.goto('/link-account?error=SomeOtherError');
+    await expect(page).toHaveURL(/\/login/, { timeout: 10_000 });
+  });
+
+  test('redirects authenticated users to /', async ({ page, context }) => {
+    // First log in
+    await page.goto('http://localhost:3000/login');
+    await page.getByRole('textbox', { name: /username/i }).fill('testadmin');
+    await page.getByRole('textbox', { name: /password/i }).fill('TestPassword2026!');
+    await page.getByRole('button', { name: /sign in/i }).click();
+    await expect(page).not.toHaveURL(/\/login/, { timeout: 10_000 });
+
+    // Now visit link-account — should redirect to /
+    await page.goto('/link-account?error=LINKING_REQUIRED:some-token');
+    await expect(page).toHaveURL(/^\/$|\/(?!link-account)/, { timeout: 10_000 });
+  });
+});
diff --git a/tests/e2e/portal.spec.ts b/tests/e2e/portal.spec.ts
new file mode 100644
index 00000000..66c78247
--- /dev/null
+++ b/tests/e2e/portal.spec.ts
@@ -0,0 +1,50 @@
+/**
+ * E2E tests: Forward Auth Portal login page (/portal).
+ *
+ * Verifies the portal login flow — error states, form rendering, credential submit.
+ * Portal tests run WITHOUT pre-authenticated state since this is a login page.
+ */
+import { test, expect } from '@playwright/test';
+
+test.use({ storageState: { cookies: [], origins: [] } });
+
+test.describe('Portal login page', () => {
+  test('shows error when no redirect URI is provided', async ({ page }) => {
+    await page.goto('/portal');
+    await expect(page.getByText('Authentication Required')).toBeVisible();
+    await expect(page.getByText('No redirect destination specified.')).toBeVisible();
+  });
+
+  test('shows login form when redirect URI is provided', async ({ page }) => {
+    await page.goto('/portal?rd=http://example.com');
+    await expect(page.getByText('Authentication Required')).toBeVisible();
+    await expect(page.getByText('Sign in to continue')).toBeVisible();
+
+    // Credential form fields
+    await expect(page.getByLabel('Username')).toBeVisible();
+    await expect(page.getByLabel('Password')).toBeVisible();
+    await expect(page.getByRole('button', { name: /sign in/i })).toBeVisible();
+  });
+
+  test('shows error with invalid credentials', async ({ page }) => {
+    await page.goto('/portal?rd=http://example.com');
+
+    await page.getByLabel('Username').fill('wronguser');
+    await page.getByLabel('Password').fill('wrongpass');
+    await page.getByRole('button', { name: /sign in/i }).click();
+
+    // Should show an error message
+    await expect(page.locator('[role="alert"]')).toBeVisible({ timeout: 10_000 });
+  });
+
+  test('username and password fields are required', async ({ page }) => {
+    await page.goto('/portal?rd=http://example.com');
+
+    // Fields have required attribute — clicking sign in with empty fields should not submit
+    const username = page.getByLabel('Username');
+    const password = page.getByLabel('Password');
+
+    await expect(username).toHaveAttribute('required', '');
+    await expect(password).toHaveAttribute('required', '');
+  });
+});
diff --git a/tests/e2e/role-access.spec.ts b/tests/e2e/role-access.spec.ts
new file mode 100644
index 00000000..c25a3a70
--- /dev/null
+++ b/tests/e2e/role-access.spec.ts
@@ -0,0 +1,337 @@
+/**
+ * E2E tests: Role-based access control.
+ *
+ * Verifies that:
+ * - Non-admin users (user, viewer) CAN access / and /profile
+ * - Non-admin users CANNOT access admin-only pages
+ * - Unauthenticated users are redirected to /login everywhere
+ * - Admin users can access all pages
+ *
+ * Test setup:
+ * - Creates "testuser" (role=user) and "testviewer" (role=viewer) in the database
+ *   via `docker compose exec` + bun script inside the web container.
+ * - Logs in as each role in separate browser contexts.
+ */
+import { test, expect, type BrowserContext } from '@playwright/test';
+import { execFileSync } from 'node:child_process';
+
+const COMPOSE_ARGS = [
+  'compose',
+  '-f', 'docker-compose.yml',
+  '-f', 'tests/docker-compose.test.yml',
+];
+
+// Pages that require admin role (via requireAdmin in their own page.tsx)
+const ADMIN_ONLY_PAGES = [
+  '/proxy-hosts',
+  '/l4-proxy-hosts',
+  '/certificates',
+  '/access-lists',
+  '/analytics',
+  '/waf',
+  '/audit-log',
+  '/settings',
+  '/users',
+  '/groups',
+  '/api-docs',
+];
+
+// Pages accessible to any authenticated user
+const USER_ACCESSIBLE_PAGES = [
+  '/',
+  '/profile',
+];
+
+// All dashboard pages (union of both sets)
+const ALL_DASHBOARD_PAGES = [...USER_ACCESSIBLE_PAGES, ...ADMIN_ONLY_PAGES];
+
+/**
+ * Create a test user inside the running web container using bun.
+ * Uses bcrypt to hash the password (same as the app does).
+ */
+function ensureTestUser(username: string, password: string, role: string) {
+  const script = `
+    const { Database } = require("bun:sqlite");
+    const bcrypt = require("bcryptjs");
+    const db = new Database("./data/caddy-proxy-manager.db");
+    const email = "${username}@localhost";
+    const hash = bcrypt.hashSync("${password}", 12);
+    const now = new Date().toISOString();
+    const existing = db.query("SELECT id FROM users WHERE email = ?").get(email);
+    if (existing) {
+      db.run("UPDATE users SET password_hash = ?, role = ?, status = 'active', updated_at = ? WHERE email = ?",
+        [hash, "${role}", now, email]);
+    } else {
+      db.run(
+        "INSERT INTO users (email, name, password_hash, role, provider, subject, status, created_at, updated_at) VALUES (?, ?, ?, ?, 'credentials', ?, 'active', ?, ?)",
+        [email, "${username}", hash, "${role}", "${username}", now, now]
+      );
+    }
+  `;
+  execFileSync('docker', [...COMPOSE_ARGS, 'exec', '-T', 'web', 'bun', '-e', script], {
+    cwd: process.cwd(),
+    stdio: 'pipe',
+  });
+}
+
+/**
+ * Log in as the given user and return an authenticated browser context.
+ */
+async function loginAs(
+  browser: import('@playwright/test').Browser,
+  username: string,
+  password: string
+): Promise<BrowserContext> {
+  const context = await browser.newContext();
+  const page = await context.newPage();
+
+  await page.goto('http://localhost:3000/login');
+  await page.getByRole('textbox', { name: /username/i }).fill(username);
+  await page.getByRole('textbox', { name: /password/i }).fill(password);
+  await page.getByRole('button', { name: /sign in/i }).click();
+
+  // Wait for login to complete (redirect away from /login or error)
+  await page.waitForURL((url) => !url.pathname.includes('/login'), { timeout: 15_000 });
+  await page.close();
+  return context;
+}
+
+// ── Unauthenticated access ────────────────────────────────────────────────
+
+test.describe('Unauthenticated access', () => {
+  test.use({ storageState: { cookies: [], origins: [] } });
+
+  for (const path of ALL_DASHBOARD_PAGES) {
+    test(`${path} redirects to /login`, async ({ page }) => {
+      await page.goto(path);
+      await expect(page).toHaveURL(/\/login/, { timeout: 10_000 });
+    });
+  }
+});
+
+// ── Role-based access ─────────────────────────────────────────────────────
+
+test.describe('Role-based access control', () => {
+  test.use({ storageState: { cookies: [], origins: [] } });
+
+  let userContext: BrowserContext;
+  let viewerContext: BrowserContext;
+
+  test.beforeAll(async ({ browser }) => {
+    // Create test users with non-admin roles
+    ensureTestUser('testuser', 'TestUserPass2026!', 'user');
+    ensureTestUser('testviewer', 'TestViewerPass2026!', 'viewer');
+
+    // Log in as each role
+    userContext = await loginAs(browser, 'testuser', 'TestUserPass2026!');
+    viewerContext = await loginAs(browser, 'testviewer', 'TestViewerPass2026!');
+  });
+
+  test.afterAll(async () => {
+    await userContext?.close();
+    await viewerContext?.close();
+  });
+
+  // ── "user" role — can access / and /profile ─────────────────────────
+
+  test('user role: / loads with welcome message', async () => {
+    const page = await userContext.newPage();
+    try {
+      await page.goto('/');
+      await expect(page).not.toHaveURL(/\/login/, { timeout: 10_000 });
+      await expect(page.getByText(/welcome back/i)).toBeVisible({ timeout: 5_000 });
+    } finally {
+      await page.close();
+    }
+  });
+
+  test('user role: / does not show admin stat cards', async () => {
+    const page = await userContext.newPage();
+    try {
+      await page.goto('/');
+      await expect(page.getByText(/welcome back/i)).toBeVisible({ timeout: 5_000 });
+      // Non-admin gets empty stats — no Proxy Hosts / Certificates / Access Lists cards
+      await expect(page.getByRole('link', { name: /proxy hosts/i })).not.toBeVisible({ timeout: 3_000 });
+    } finally {
+      await page.close();
+    }
+  });
+
+  test('user role: sidebar only shows Overview', async () => {
+    const page = await userContext.newPage();
+    try {
+      await page.goto('/');
+      await expect(page.getByText(/welcome back/i)).toBeVisible({ timeout: 5_000 });
+      // Overview should be in the nav
+      await expect(page.getByRole('link', { name: 'Overview' })).toBeVisible();
+      // Admin-only nav items should not be visible
+      await expect(page.getByRole('link', { name: 'Proxy Hosts' })).not.toBeVisible();
+      await expect(page.getByRole('link', { name: 'Settings' })).not.toBeVisible();
+      await expect(page.getByRole('link', { name: 'Users' })).not.toBeVisible();
+    } finally {
+      await page.close();
+    }
+  });
+
+  test('user role: /profile loads successfully', async () => {
+    const page = await userContext.newPage();
+    try {
+      await page.goto('/profile');
+      await expect(page).not.toHaveURL(/\/login/, { timeout: 10_000 });
+      await expect(page.getByText(/profile|password/i).first()).toBeVisible({ timeout: 5_000 });
+    } finally {
+      await page.close();
+    }
+  });
+
+  // ── "viewer" role — can access / and /profile ───────────────────────
+
+  test('viewer role: / loads with welcome message', async () => {
+    const page = await viewerContext.newPage();
+    try {
+      await page.goto('/');
+      await expect(page).not.toHaveURL(/\/login/, { timeout: 10_000 });
+      await expect(page.getByText(/welcome back/i)).toBeVisible({ timeout: 5_000 });
+    } finally {
+      await page.close();
+    }
+  });
+
+  test('viewer role: / does not show admin stat cards', async () => {
+    const page = await viewerContext.newPage();
+    try {
+      await page.goto('/');
+      await expect(page.getByText(/welcome back/i)).toBeVisible({ timeout: 5_000 });
+      await expect(page.getByRole('link', { name: /proxy hosts/i })).not.toBeVisible({ timeout: 3_000 });
+    } finally {
+      await page.close();
+    }
+  });
+
+  test('viewer role: sidebar only shows Overview', async () => {
+    const page = await viewerContext.newPage();
+    try {
+      await page.goto('/');
+      await expect(page.getByText(/welcome back/i)).toBeVisible({ timeout: 5_000 });
+      await expect(page.getByRole('link', { name: 'Overview' })).toBeVisible();
+      await expect(page.getByRole('link', { name: 'Proxy Hosts' })).not.toBeVisible();
+      await expect(page.getByRole('link', { name: 'Settings' })).not.toBeVisible();
+    } finally {
+      await page.close();
+    }
+  });
+
+  test('viewer role: /profile loads successfully', async () => {
+    const page = await viewerContext.newPage();
+    try {
+      await page.goto('/profile');
+      await expect(page).not.toHaveURL(/\/login/, { timeout: 10_000 });
+      await expect(page.getByText(/profile|password/i).first()).toBeVisible({ timeout: 5_000 });
+    } finally {
+      await page.close();
+    }
+  });
+
+  // ── "user" role — blocked from admin-only pages ─────────────────────
+
+  for (const path of ADMIN_ONLY_PAGES) {
+    test(`user role: ${path} is blocked`, async () => {
+      const page = await userContext.newPage();
+      try {
+        const response = await page.goto(path);
+        // requireAdmin() throws "Administrator privileges required".
+        // Next.js renders the error boundary or returns 500.
+        const status = response?.status() ?? 0;
+        const url = page.url();
+
+        const isBlocked =
+          status >= 400 ||
+          url.includes('/login') ||
+          await page.getByText(/administrator privileges|error|forbidden|not authorized/i)
+            .isVisible({ timeout: 3_000 }).catch(() => false);
+
+        expect(isBlocked).toBe(true);
+      } finally {
+        await page.close();
+      }
+    });
+  }
+
+  // ── "viewer" role — blocked from admin-only pages ───────────────────
+
+  for (const path of ADMIN_ONLY_PAGES) {
+    test(`viewer role: ${path} is blocked`, async () => {
+      const page = await viewerContext.newPage();
+      try {
+        const response = await page.goto(path);
+        const status = response?.status() ?? 0;
+        const url = page.url();
+
+        const isBlocked =
+          status >= 400 ||
+          url.includes('/login') ||
+          await page.getByText(/administrator privileges|error|forbidden|not authorized/i)
+            .isVisible({ timeout: 3_000 }).catch(() => false);
+
+        expect(isBlocked).toBe(true);
+      } finally {
+        await page.close();
+      }
+    });
+  }
+
+  // ── Admin user — can access all pages ───────────────────────────────
+
+  test('admin role: all dashboard pages are accessible', async ({ browser }) => {
+    const adminContext = await loginAs(browser, 'testadmin', 'TestPassword2026!');
+    try {
+      for (const path of ALL_DASHBOARD_PAGES) {
+        const page = await adminContext.newPage();
+        const response = await page.goto(path);
+        const status = response?.status() ?? 0;
+        expect(status).toBeLessThan(400);
+        expect(page.url()).not.toContain('/login');
+        await page.close();
+      }
+    } finally {
+      await adminContext.close();
+    }
+  });
+
+  test('admin role: sidebar shows all nav items', async ({ browser }) => {
+    const adminContext = await loginAs(browser, 'testadmin', 'TestPassword2026!');
+    try {
+      const page = await adminContext.newPage();
+      await page.goto('/');
+      await expect(page.getByRole('link', { name: 'Overview' })).toBeVisible();
+      await expect(page.getByRole('link', { name: 'Proxy Hosts' })).toBeVisible();
+      await expect(page.getByRole('link', { name: 'Settings' })).toBeVisible();
+      await expect(page.getByRole('link', { name: 'Users' })).toBeVisible();
+      await page.close();
+    } finally {
+      await adminContext.close();
+    }
+  });
+
+  // ── API endpoints — non-admin should be blocked ───────────────────────
+
+  test('user role: API v1 endpoints return 401/403', async () => {
+    const page = await userContext.newPage();
+    try {
+      const response = await page.request.get('/api/v1/proxy-hosts');
+      expect(response.status()).toBeGreaterThanOrEqual(400);
+    } finally {
+      await page.close();
+    }
+  });
+
+  test('viewer role: API v1 endpoints return 401/403', async () => {
+    const page = await viewerContext.newPage();
+    try {
+      const response = await page.request.get('/api/v1/proxy-hosts');
+      expect(response.status()).toBeGreaterThanOrEqual(400);
+    } finally {
+      await page.close();
+    }
+  });
+});
diff --git a/tests/e2e/users.spec.ts b/tests/e2e/users.spec.ts
new file mode 100644
index 00000000..46e17b56
--- /dev/null
+++ b/tests/e2e/users.spec.ts
@@ -0,0 +1,80 @@
+/**
+ * E2E tests: Users management page.
+ *
+ * Verifies user listing, search, edit, disable/enable, and delete functionality.
+ * Runs as admin (testadmin) — the page requires admin role.
+ */
+import { test, expect } from '@playwright/test';
+
+test.describe('Users page', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/users');
+  });
+
+  test('page loads with Users heading', async ({ page }) => {
+    await expect(page.getByRole('heading', { name: 'Users' })).toBeVisible();
+    await expect(page.getByText('Manage user accounts, roles, and access.')).toBeVisible();
+  });
+
+  test('displays at least one user (the admin)', async ({ page }) => {
+    await expect(page.getByText(/1 user/)).toBeVisible({ timeout: 5000 });
+  });
+
+  test('search input filters users', async ({ page }) => {
+    await page.getByPlaceholder('Search users...').fill('testadmin');
+    await expect(page.getByText(/1 user/)).toBeVisible({ timeout: 5000 });
+
+    await page.getByPlaceholder('Search users...').fill('nonexistent-zzz');
+    await expect(page.getByText('No users found.')).toBeVisible({ timeout: 5000 });
+  });
+
+  test('admin user shows admin role badge', async ({ page }) => {
+    await expect(page.getByText('admin', { exact: true }).first()).toBeVisible();
+  });
+
+  test('clicking edit button shows edit form', async ({ page }) => {
+    await page.getByTitle('Edit user').first().click();
+    await expect(page.getByText(/editing/i)).toBeVisible();
+    await expect(page.getByPlaceholder('Display name')).toBeVisible();
+    await expect(page.getByPlaceholder('Email address')).toBeVisible();
+    await expect(page.getByRole('button', { name: 'Save' })).toBeVisible();
+    await expect(page.getByRole('button', { name: 'Cancel' })).toBeVisible();
+  });
+
+  test('clicking cancel closes the edit form', async ({ page }) => {
+    await page.getByTitle('Edit user').first().click();
+    await expect(page.getByText(/editing/i)).toBeVisible();
+
+    await page.getByRole('button', { name: 'Cancel' }).click();
+    await expect(page.getByText(/editing/i)).not.toBeVisible();
+  });
+
+  test('edit form has role select with Admin, User, Viewer options', async ({ page }) => {
+    await page.getByTitle('Edit user').first().click();
+
+    // The role select trigger should be visible
+    const roleTrigger = page.getByRole('combobox').first();
+    await expect(roleTrigger).toBeVisible();
+    await roleTrigger.click();
+
+    // Check dropdown options
+    await expect(page.getByRole('option', { name: 'Admin' })).toBeVisible();
+    await expect(page.getByRole('option', { name: 'User' })).toBeVisible();
+    await expect(page.getByRole('option', { name: 'Viewer' })).toBeVisible();
+  });
+
+  test('user row shows action buttons (edit, disable, delete)', async ({ page }) => {
+    await expect(page.getByTitle('Edit user').first()).toBeVisible();
+    await expect(page.getByTitle('Disable user').first()).toBeVisible();
+    await expect(page.getByTitle('Delete user').first()).toBeVisible();
+  });
+});
+
+test.describe('Users page — unauthenticated access', () => {
+  test.use({ storageState: { cookies: [], origins: [] } });
+
+  test('unauthenticated access to /users redirects to /login', async ({ page }) => {
+    await page.goto('/users');
+    await expect(page).toHaveURL(/\/login/);
+  });
+});