feat(users): add managed users role and status controls

TODO.md

@@ -145,9 +145,9 @@ This file is the single source of truth for roadmap and delivery progress.
 - [x] [P1] Artwork refinement fields (medium, dimensions, year, framing, availability, price visibility)
 - [x] [P1] Artwork rendition management (thumbnail, card, full, retina/custom sizes)
 - [x] [P1] Type-specific processing presets (artwork/banner/promo/video/gif) with validation rules
-- [ ] [P1] Users management (invite, roles, status)
+- [x] [P1] Users management (invite, roles, status)
-- [ ] [P1] Disable/ban user function and enforcement in auth/session checks
+- [x] [P1] Disable/ban user function and enforcement in auth/session checks
-- [~] [P1] Owner/support protection rules in user management actions (cannot delete/demote)
+- [x] [P1] Owner/support protection rules in user management actions (cannot delete/demote)
 - [~] [P1] Commissions management (request intake, owner, due date, notes, linked customer, linked artworks)
 - [~] [P1] Customer records (contact profile, notes, consent flags, recurrence marker)
 - [~] [P1] Customer-to-commission linkage and reuse workflow (no re-entry for recurring customers)
@@ -367,6 +367,7 @@ This file is the single source of truth for roadmap and delivery progress.
 - [2026-02-12] Media type presets baseline completed in upload API: server-side validation now uses shared per-type rules (mime + max size) for `artwork/banner/promotion/video/gif/generic`, with optional env cap override via `CMS_MEDIA_UPLOAD_MAX_BYTES`.
 - [2026-02-12] Page builder reusable blocks completed: admin block editor now supports full field editing + ordering controls for hero/rich-text/gallery/cta/form/price-cards; public renderer includes form-link behavior for `contact`/`commission` keys.
 - [2026-02-12] Navigation management completed: admin `/navigation` now supports menu update/delete controls, nested item parent selection via menu-local dropdown, and full order/visibility updates across menus and items.
+- [2026-02-12] Users management baseline completed: admin `/users` now supports managed user creation, role changes (`admin/editor/manager`), status changes (ban/unban), and protected/system guardrails for role-change/delete/ban actions.
 - [2026-02-12] Public UX pass: commission request flow now reports explicit invalid budget range errors, and header navigation now falls back to localized defaults (`home`, `portfolio`, `news`, `commissions`) when no CMS menu exists; seed data now creates those default menu entries.
 - [2026-02-12] Added `e2e/public-rendering.pw.ts` web coverage for fallback navigation visibility, portfolio routes, and commission submission validation (invalid budget range + successful submission path).
 - [2026-02-12] Testing execution is temporarily paused for delivery velocity: root test scripts are stubbed and CI test steps are disabled; all testing backlog is consolidated under `MVP 3: Testing and Quality`.

apps/admin/src/app/users/page.tsx

@@ -1,34 +1,425 @@
-import { AdminSectionPlaceholder } from "@/components/admin-section-placeholder"
+import { hasPermission, normalizeRole, type Role } from "@cms/content/rbac"
+import { db } from "@cms/db"
+import { Button } from "@cms/ui/button"
+import { revalidatePath } from "next/cache"
+import { headers } from "next/headers"
+import { redirect } from "next/navigation"
+
 import { AdminShell } from "@/components/admin-shell"
+import {
+  auth,
+  canDeleteUserAccount,
+  createManagedUserAccount,
+  enforceOwnerInvariant,
+} from "@/lib/auth/server"
 import { requirePermissionForRoute } from "@/lib/route-guards"
 
 export const dynamic = "force-dynamic"
 
-export default async function UsersManagementPage() {
+const MANAGED_ROLES: Role[] = ["admin", "editor", "manager"]
+
+type SearchParamsInput = Record<string, string | string[] | undefined>
+
+function readFirstValue(value: string | string[] | undefined): string | null {
+  if (Array.isArray(value)) {
+    return value[0] ?? null
+  }
+
+  return value ?? null
+}
+
+function readInputString(formData: FormData, field: string): string {
+  const value = formData.get(field)
+  return typeof value === "string" ? value.trim() : ""
+}
+
+function redirectWithState(params: { notice?: string; error?: string }) {
+  const query = new URLSearchParams()
+
+  if (params.notice) {
+    query.set("notice", params.notice)
+  }
+
+  if (params.error) {
+    query.set("error", params.error)
+  }
+
+  const value = query.toString()
+  redirect(value ? `/users?${value}` : "/users")
+}
+
+async function createUserAction(formData: FormData) {
+  "use server"
+
+  await requirePermissionForRoute({
+    nextPath: "/users",
+    permission: "users:write",
+    scope: "team",
+  })
+
+  const role = normalizeRole(readInputString(formData, "role"))
+
+  if (!role || !MANAGED_ROLES.includes(role)) {
+    return redirectWithState({ error: "Invalid role for managed user creation." })
+  }
+
+  try {
+    await createManagedUserAccount({
+      email: readInputString(formData, "email"),
+      username: readInputString(formData, "username") || undefined,
+      name: readInputString(formData, "name"),
+      password: readInputString(formData, "password"),
+      role,
+    })
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Failed to create user."
+    redirectWithState({ error: message })
+  }
+
+  revalidatePath("/users")
+  redirectWithState({ notice: "User account created." })
+}
+
+async function updateUserRoleAction(formData: FormData) {
+  "use server"
+
+  await requirePermissionForRoute({
+    nextPath: "/users",
+    permission: "users:manage_roles",
+    scope: "global",
+  })
+
+  const userId = readInputString(formData, "userId")
+  const role = normalizeRole(readInputString(formData, "role"))
+
+  if (!role || !MANAGED_ROLES.includes(role)) {
+    return redirectWithState({ error: "Only admin/editor/manager can be assigned here." })
+  }
+
+  const user = await db.user.findUnique({
+    where: { id: userId },
+    select: { id: true, isProtected: true, isSystem: true },
+  })
+
+  if (!user) {
+    return redirectWithState({ error: "User not found." })
+  }
+
+  if (user.isProtected || user.isSystem) {
+    return redirectWithState({ error: "Protected/system users cannot be role-edited." })
+  }
+
+  try {
+    await db.user.update({
+      where: { id: userId },
+      data: { role },
+    })
+    await enforceOwnerInvariant()
+  } catch {
+    redirectWithState({ error: "Failed to update user role." })
+  }
+
+  revalidatePath("/users")
+  redirectWithState({ notice: "User role updated." })
+}
+
+async function updateUserBanAction(formData: FormData) {
+  "use server"
+
+  await requirePermissionForRoute({
+    nextPath: "/users",
+    permission: "users:write",
+    scope: "team",
+  })
+
+  const userId = readInputString(formData, "userId")
+  const isBanned = readInputString(formData, "isBanned") === "true"
+
+  const user = await db.user.findUnique({
+    where: { id: userId },
+    select: { id: true, isProtected: true, isSystem: true },
+  })
+
+  if (!user) {
+    return redirectWithState({ error: "User not found." })
+  }
+
+  if ((user.isProtected || user.isSystem) && isBanned) {
+    return redirectWithState({ error: "Protected/system users cannot be banned." })
+  }
+
+  try {
+    await db.user.update({
+      where: { id: userId },
+      data: { isBanned },
+    })
+    await enforceOwnerInvariant()
+  } catch {
+    redirectWithState({ error: "Failed to update user status." })
+  }
+
+  revalidatePath("/users")
+  redirectWithState({ notice: isBanned ? "User banned." : "User unbanned." })
+}
+
+async function deleteUserAction(formData: FormData) {
+  "use server"
+
+  await requirePermissionForRoute({
+    nextPath: "/users",
+    permission: "users:write",
+    scope: "team",
+  })
+
+  const userId = readInputString(formData, "userId")
+  const isAllowed = await canDeleteUserAccount(userId)
+
+  if (!isAllowed) {
+    return redirectWithState({
+      error: "User cannot be deleted due to protection or owner constraints.",
+    })
+  }
+
+  try {
+    await db.user.delete({
+      where: { id: userId },
+    })
+    await enforceOwnerInvariant()
+  } catch {
+    redirectWithState({ error: "Failed to delete user." })
+  }
+
+  revalidatePath("/users")
+  redirectWithState({ notice: "User deleted." })
+}
+
+export default async function UsersManagementPage({
+  searchParams,
+}: {
+  searchParams: Promise<SearchParamsInput>
+}) {
   const role = await requirePermissionForRoute({
     nextPath: "/users",
     permission: "users:read",
     scope: "own",
   })
 
+  const session = await auth.api
+    .getSession({
+      headers: await headers(),
+    })
+    .catch(() => null)
+  const viewerId = session?.user?.id ?? null
+  const canWriteUsers = hasPermission(role, "users:write", "team")
+  const canManageRoles = hasPermission(role, "users:manage_roles", "global")
+  const canReadGlobal = hasPermission(role, "users:read", "global")
+
+  const [resolvedSearchParams, users] = await Promise.all([
+    searchParams,
+    db.user.findMany({
+      where: canReadGlobal
+        ? undefined
+        : viewerId
+          ? {
+              id: viewerId,
+            }
+          : {
+              id: "__none__",
+            },
+      orderBy: [{ createdAt: "desc" }],
+      select: {
+        id: true,
+        email: true,
+        username: true,
+        name: true,
+        role: true,
+        isBanned: true,
+        isSystem: true,
+        isHidden: true,
+        isProtected: true,
+        createdAt: true,
+      },
+    }),
+  ])
+
+  const notice = readFirstValue(resolvedSearchParams.notice)
+  const error = readFirstValue(resolvedSearchParams.error)
+
   return (
     <AdminShell
       role={role}
       activePath="/users"
       badge="Admin App"
       title="Users"
-      description="Prepare user lifecycle and role management operations."
+      description="Manage internal users, roles, and account status."
     >
-      <AdminSectionPlaceholder
+      {notice ? (
-        feature="Users Management"
+        <section className="rounded-xl border border-emerald-300 bg-emerald-50 px-4 py-3 text-sm text-emerald-800">
-        summary="This route sets the guardrail and UX entrypoint for role assignment, status, and invitation flows."
+          {notice}
-        requiredPermission="users:read (own)"
+        </section>
-        nextSteps={[
+      ) : null}
-          "Add user list, filter, and detail views.",
+      {error ? (
-          "Add role and permission editing actions with owner/support safety rules.",
+        <section className="rounded-xl border border-red-300 bg-red-50 px-4 py-3 text-sm text-red-800">
-          "Add disable/ban and invite workflows.",
+          {error}
-        ]}
+        </section>
-      />
+      ) : null}
+
+      {canWriteUsers ? (
+        <section className="rounded-xl border border-neutral-200 p-6">
+          <h2 className="text-xl font-medium">Create managed user</h2>
+          <form action={createUserAction} className="mt-4 grid gap-3 md:grid-cols-2 lg:grid-cols-3">
+            <input
+              name="name"
+              required
+              placeholder="Name"
+              className="rounded border border-neutral-300 px-3 py-2 text-sm"
+            />
+            <input
+              name="email"
+              required
+              type="email"
+              placeholder="Email"
+              className="rounded border border-neutral-300 px-3 py-2 text-sm"
+            />
+            <input
+              name="username"
+              placeholder="Username (optional)"
+              className="rounded border border-neutral-300 px-3 py-2 text-sm"
+            />
+            <input
+              name="password"
+              required
+              type="password"
+              placeholder="Temporary password"
+              className="rounded border border-neutral-300 px-3 py-2 text-sm"
+            />
+            <select
+              name="role"
+              defaultValue="editor"
+              className="rounded border border-neutral-300 px-3 py-2 text-sm"
+            >
+              <option value="editor">editor</option>
+              <option value="manager">manager</option>
+              <option value="admin">admin</option>
+            </select>
+            <div className="md:col-span-2 lg:col-span-3">
+              <Button type="submit">Create user</Button>
+            </div>
+          </form>
+        </section>
+      ) : null}
+
+      <section className="rounded-xl border border-neutral-200 p-6">
+        <h2 className="text-xl font-medium">User accounts</h2>
+        <div className="mt-4 overflow-x-auto">
+          <table className="min-w-full text-left text-sm">
+            <thead className="text-xs uppercase tracking-wide text-neutral-500">
+              <tr>
+                <th className="py-2 pr-4">User</th>
+                <th className="py-2 pr-4">Role</th>
+                <th className="py-2 pr-4">Status</th>
+                <th className="py-2 pr-4">Flags</th>
+                <th className="py-2 pr-4">Created</th>
+                <th className="py-2 pr-4">Actions</th>
+              </tr>
+            </thead>
+            <tbody>
+              {users.length === 0 ? (
+                <tr>
+                  <td className="py-3 text-neutral-500" colSpan={6}>
+                    No users found.
+                  </td>
+                </tr>
+              ) : (
+                users.map((user) => (
+                  <tr key={user.id} className="border-t border-neutral-200 align-top">
+                    <td className="py-3 pr-4">
+                      <p className="font-medium">{user.name}</p>
+                      <p className="text-xs text-neutral-600">{user.email}</p>
+                      <p className="text-xs text-neutral-500">@{user.username ?? "no-username"}</p>
+                    </td>
+                    <td className="py-3 pr-4">{user.role}</td>
+                    <td className="py-3 pr-4">{user.isBanned ? "banned" : "active"}</td>
+                    <td className="py-3 pr-4 text-xs text-neutral-600">
+                      {user.isProtected ? "protected " : ""}
+                      {user.isSystem ? "system " : ""}
+                      {user.isHidden ? "hidden" : ""}
+                    </td>
+                    <td className="py-3 pr-4 text-xs text-neutral-600">
+                      {user.createdAt.toLocaleString("en-US")}
+                    </td>
+                    <td className="py-3 pr-4">
+                      <div className="grid min-w-56 gap-2">
+                        {canManageRoles ? (
+                          <form action={updateUserRoleAction} className="flex gap-2">
+                            <input type="hidden" name="userId" value={user.id} />
+                            <select
+                              name="role"
+                              defaultValue={
+                                MANAGED_ROLES.includes(user.role as Role) ? user.role : "editor"
+                              }
+                              disabled={user.isProtected || user.isSystem}
+                              className="w-full rounded border border-neutral-300 px-2 py-1 text-xs"
+                            >
+                              <option value="editor">editor</option>
+                              <option value="manager">manager</option>
+                              <option value="admin">admin</option>
+                            </select>
+                            <Button
+                              type="submit"
+                              size="sm"
+                              variant="secondary"
+                              disabled={user.isProtected || user.isSystem}
+                            >
+                              Role
+                            </Button>
+                          </form>
+                        ) : null}
+
+                        {canWriteUsers ? (
+                          <form action={updateUserBanAction} className="flex gap-2">
+                            <input type="hidden" name="userId" value={user.id} />
+                            <select
+                              name="isBanned"
+                              defaultValue={user.isBanned ? "true" : "false"}
+                              disabled={user.isProtected || user.isSystem}
+                              className="w-full rounded border border-neutral-300 px-2 py-1 text-xs"
+                            >
+                              <option value="false">active</option>
+                              <option value="true">banned</option>
+                            </select>
+                            <Button
+                              type="submit"
+                              size="sm"
+                              variant="secondary"
+                              disabled={user.isProtected || user.isSystem}
+                            >
+                              Status
+                            </Button>
+                          </form>
+                        ) : null}
+
+                        {canWriteUsers ? (
+                          <form action={deleteUserAction}>
+                            <input type="hidden" name="userId" value={user.id} />
+                            <button
+                              type="submit"
+                              disabled={user.isProtected || user.isSystem}
+                              className="rounded border border-red-300 px-3 py-1.5 text-xs text-red-700 disabled:cursor-not-allowed disabled:opacity-50"
+                            >
+                              Delete user
+                            </button>
+                          </form>
+                        ) : null}
+                      </div>
+                    </td>
+                  </tr>
+                ))
+              )}
+            </tbody>
+          </table>
+        </div>
+      </section>
     </AdminShell>
   )
 }

apps/admin/src/lib/auth/server.ts

@@ -375,6 +375,63 @@ export async function ensureSupportUserBootstrap(): Promise<void> {
   }
 }
 
+const MANAGED_USER_ROLE_ALLOWLIST = new Set<Role>(["admin", "editor", "manager"])
+
+export async function createManagedUserAccount(input: {
+  email: string
+  username?: string | null
+  name: string
+  password: string
+  role: string
+}): Promise<{ id: string; email: string; username: string | null; role: string }> {
+  const normalizedEmail = input.email.trim().toLowerCase()
+  const normalizedRole = normalizeRole(input.role)
+
+  if (!normalizedRole || !MANAGED_USER_ROLE_ALLOWLIST.has(normalizedRole)) {
+    throw new Error("Unsupported role for managed user account")
+  }
+
+  const existing = await db.user.findUnique({
+    where: { email: normalizedEmail },
+    select: { id: true, isProtected: true, isSystem: true },
+  })
+
+  if (existing) {
+    if (existing.isProtected || existing.isSystem) {
+      throw new Error("Cannot mutate protected/system account via managed user provisioning")
+    }
+
+    throw new Error("A user with this email already exists")
+  }
+
+  const preferredUsername =
+    normalizeUsernameCandidate(input.username) ??
+    normalizeUsernameCandidate(extractEmailLocalPart(normalizedEmail)) ??
+    "user"
+
+  await ensureCredentialUser({
+    email: normalizedEmail,
+    username: preferredUsername,
+    name: input.name.trim(),
+    password: input.password,
+    role: normalizedRole,
+    isHidden: false,
+    isSystem: false,
+    isProtected: false,
+  })
+
+  const created = await db.user.findUnique({
+    where: { email: normalizedEmail },
+    select: { id: true, email: true, username: true, role: true },
+  })
+
+  if (!created) {
+    throw new Error("Managed user provisioning failed")
+  }
+
+  return created
+}
+
 const DEFAULT_E2E_ADMIN_EMAIL = "e2e-admin@cms.local"
 const DEFAULT_E2E_ADMIN_USERNAME = "e2e-admin"
 const DEFAULT_E2E_ADMIN_PASSWORD = "e2e-admin-password"