feat: roles/permissions system and Nostr profile display on admin users

Introduce granular role-based permissions with SuperAdmin env override, admin roles UI, and permission-gated API routes. Fix admin user Nostr metadata by batching relay profile fetches, normalizing npub pubkeys to hex, and adding reusable NostrAvatar/useNostrProfile components.

Co-authored-by: Cursor <cursoragent@cursor.com>

frontend/app/admin/users/page.tsx

@@ -1,16 +1,39 @@
 "use client";
 
 import { useEffect, useState } from "react";
-import Image from "next/image";
 import { nip19 } from "nostr-tools";
 import { api } from "@/lib/api";
-import { cn, formatDate } from "@/lib/utils";
-import { fetchNostrProfile, type NostrProfile } from "@/lib/nostr";
-import { ShieldCheck, ShieldOff, UserPlus } from "lucide-react";
+import { useAuth } from "@/hooks/useAuth";
+import { useNostrProfile } from "@/hooks/useNostrProfile";
+import { NostrAvatar } from "@/components/nostr/NostrAvatar";
+import { formatDate } from "@/lib/utils";
+import { Lock } from "lucide-react";
 
-function hexToNpub(hex: string): string {
+const ROLE_RANK: Record<string, number> = {
+  superadmin: 4,
+  admin: 3,
+  moderator: 2,
+  writer: 1,
+  guest: 0,
+};
+
+const ROLE_OPTIONS: { value: string; label: string }[] = [
+  { value: "admin", label: "Admin" },
+  { value: "moderator", label: "Moderator" },
+  { value: "writer", label: "Writer" },
+  { value: "guest", label: "Guest (no role)" },
+];
+
+function normalizeRole(role: string | null | undefined): string {
+  return role && ROLE_RANK[role] !== undefined ? role : "guest";
+}
+
+function hexToNpub(pubkey: string): string {
+  if (!pubkey) return "";
+  // Already an npub (some users are stored in npub form).
+  if (pubkey.startsWith("npub1")) return pubkey;
   try {
-    return nip19.npubEncode(hex);
+    return nip19.npubEncode(pubkey);
   } catch {
     return "";
   }
@@ -21,24 +44,169 @@ function shortenNpub(npub: string): string {
   return `${npub.slice(0, 14)}...${npub.slice(-10)}`;
 }
 
-function profileInitials(profile: NostrProfile | undefined, npub: string): string {
-  const n = profile?.name || profile?.displayName;
-  if (n?.trim()) return n.trim().slice(0, 2).toUpperCase();
-  if (npub.length >= 8) return npub.slice(5, 7).toUpperCase();
-  return "?";
+interface UserRowProps {
+  user: any;
+  draft: string;
+  onDraftChange: (pubkey: string, value: string) => void;
+  savingPubkey: string | null;
+  onSaveUsername: (pubkey: string, currentUsername: string | null | undefined) => void;
+  onCancelUsername: (pubkey: string, stored: string | null | undefined) => void;
+  hostname: string;
+  copiedPubkey: string | null;
+  onCopyNpub: (pubkey: string) => void;
+  callerRank: number;
+  isSuperAdmin: boolean;
+  savingRole: string | null;
+  onRoleChange: (pubkey: string, role: string) => void;
+}
+
+function UserRow({
+  user,
+  draft,
+  onDraftChange,
+  savingPubkey,
+  onSaveUsername,
+  onCancelUsername,
+  hostname,
+  copiedPubkey,
+  onCopyNpub,
+  callerRank,
+  isSuperAdmin,
+  savingRole,
+  onRoleChange,
+}: UserRowProps) {
+  const { profile, loading: profileLoading } = useNostrProfile(user.pubkey);
+  const stored = user.username ?? "";
+  const usernameDirty = draft.trim().toLowerCase() !== stored.toLowerCase();
+  const fullNpub = hexToNpub(user.pubkey);
+  const nostrDisplay = profile?.name || profile?.displayName;
+
+  return (
+    <div className="bg-surface-container-low rounded-xl p-6 flex flex-col gap-4 sm:flex-row sm:items-start sm:justify-between">
+      <div className="flex-1 min-w-0 flex gap-4 items-start">
+        <NostrAvatar pubkey={user.pubkey} size={56} fallbackText={fullNpub} />
+        <div className="flex-1 min-w-0 space-y-3">
+          <div>
+            <p className="text-on-surface font-semibold text-base truncate">
+              {profileLoading ? (
+                <span className="text-on-surface/40 font-normal">…</span>
+              ) : nostrDisplay ? (
+                nostrDisplay
+              ) : (
+                <span className="text-on-surface/50 font-normal">No Nostr name</span>
+              )}
+            </p>
+            <button
+              type="button"
+              onClick={() => onCopyNpub(user.pubkey)}
+              className="mt-1 text-left font-mono text-sm text-on-surface/80 hover:text-primary transition-colors cursor-pointer break-all w-full"
+              title={fullNpub || "Copy npub"}
+            >
+              {copiedPubkey === user.pubkey
+                ? "Copied!"
+                : fullNpub
+                  ? shortenNpub(fullNpub)
+                  : `${user.pubkey?.slice(0, 12)}...${user.pubkey?.slice(-8)}`}
+            </button>
+          </div>
+          <div>
+            <p className="text-xs font-semibold text-on-surface/50 mb-1 uppercase tracking-wide">
+              NIP-05 username
+            </p>
+            <p className="text-on-surface-variant text-xs mb-2">
+              Reserved names from the site blocklist can be assigned here (users cannot claim them on the dashboard).
+            </p>
+            <div className="flex flex-wrap items-center gap-2">
+              <input
+                value={draft}
+                onChange={(e) => onDraftChange(user.pubkey, e.target.value)}
+                disabled={savingPubkey === user.pubkey}
+                placeholder="local-part"
+                className="bg-surface-container-highest text-on-surface rounded-lg px-3 py-2 text-sm font-mono min-w-[8rem] max-w-full flex-1 focus:outline-none focus:ring-1 focus:ring-primary/40 disabled:opacity-50"
+              />
+              <span className="text-on-surface/50 text-sm font-mono shrink-0">
+                @{hostname || "…"}
+              </span>
+              <button
+                type="button"
+                onClick={() => onSaveUsername(user.pubkey, user.username)}
+                disabled={savingPubkey === user.pubkey || !draft.trim() || !usernameDirty}
+                className="px-3 py-2 rounded-lg bg-gradient-to-r from-primary to-primary-container text-on-primary font-semibold text-sm hover:opacity-90 transition-opacity disabled:opacity-50 whitespace-nowrap"
+              >
+                {savingPubkey === user.pubkey ? "Saving…" : "Save"}
+              </button>
+              <button
+                type="button"
+                onClick={() => onCancelUsername(user.pubkey, user.username)}
+                disabled={savingPubkey === user.pubkey || !usernameDirty}
+                className="px-3 py-2 rounded-lg bg-surface-container-highest text-on-surface/70 text-sm hover:text-on-surface transition-colors disabled:opacity-50 whitespace-nowrap"
+              >
+                Cancel
+              </button>
+            </div>
+            {draft.trim() && (
+              <p className="text-on-surface-variant text-xs font-mono mt-2">
+                {draft.trim().toLowerCase()}@{hostname || "…"}
+              </p>
+            )}
+          </div>
+          <div className="flex items-center gap-3 flex-wrap">
+            {user.isSuperAdmin ? (
+              <span className="inline-flex items-center gap-1.5 rounded-full px-3 py-1 text-xs font-bold bg-primary-container/20 text-primary">
+                <Lock size={12} />
+                SuperAdmin
+              </span>
+            ) : (
+              (() => {
+                const targetRole = normalizeRole(user.role);
+                const targetRank = ROLE_RANK[targetRole];
+                const canModify = callerRank > targetRank;
+                return (
+                  <label className="flex items-center gap-2">
+                    <span className="text-xs font-semibold text-on-surface/50 uppercase tracking-wide">
+                      Role
+                    </span>
+                    <select
+                      value={targetRole}
+                      disabled={!canModify || savingRole === user.pubkey}
+                      onChange={(e) => onRoleChange(user.pubkey, e.target.value)}
+                      className="bg-surface-container-highest text-on-surface rounded-lg px-3 py-2 text-sm focus:outline-none focus:ring-1 focus:ring-primary/40 disabled:opacity-50"
+                    >
+                      {ROLE_OPTIONS.map((opt) => (
+                        <option
+                          key={opt.value}
+                          value={opt.value}
+                          disabled={!isSuperAdmin && ROLE_RANK[opt.value] >= callerRank}
+                        >
+                          {opt.label}
+                        </option>
+                      ))}
+                    </select>
+                  </label>
+                );
+              })()
+            )}
+            {user.createdAt && (
+              <span className="text-on-surface/40 text-xs">
+                Joined {formatDate(user.createdAt)}
+              </span>
+            )}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
 }
 
 export default function UsersPage() {
+  const { user: currentUser, isSuperAdmin } = useAuth();
   const [users, setUsers] = useState<any[]>([]);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState("");
-  const [promotePubkey, setPromotePubkey] = useState("");
-  const [promoting, setPromoting] = useState(false);
+  const [savingRole, setSavingRole] = useState<string | null>(null);
   const [hostname, setHostname] = useState("");
   const [usernameDrafts, setUsernameDrafts] = useState<Record<string, string>>({});
   const [savingPubkey, setSavingPubkey] = useState<string | null>(null);
-  const [nostrByPubkey, setNostrByPubkey] = useState<Record<string, NostrProfile>>({});
-  const [nostrLoading, setNostrLoading] = useState(false);
   const [copiedPubkey, setCopiedPubkey] = useState<string | null>(null);
 
   const loadUsers = async () => {
@@ -65,32 +233,6 @@ export default function UsersPage() {
     setHostname(typeof window !== "undefined" ? window.location.hostname : "");
   }, []);
 
-  useEffect(() => {
-    if (users.length === 0) {
-      setNostrByPubkey({});
-      setNostrLoading(false);
-      return;
-    }
-    let cancelled = false;
-    setNostrLoading(true);
-    setNostrByPubkey({});
-    (async () => {
-      const entries = await Promise.all(
-        users.map(async (u: { pubkey: string }) => {
-          const profile = await fetchNostrProfile(u.pubkey);
-          return [u.pubkey, profile] as const;
-        })
-      );
-      if (!cancelled) {
-        setNostrByPubkey(Object.fromEntries(entries));
-        setNostrLoading(false);
-      }
-    })();
-    return () => {
-      cancelled = true;
-    };
-  }, [users]);
-
   const handleCopyNpub = async (pubkey: string) => {
     const full = hexToNpub(pubkey);
     if (!full) return;
@@ -103,39 +245,20 @@ export default function UsersPage() {
     }
   };
 
-  const handlePromote = async () => {
-    if (!promotePubkey.trim()) return;
-    setPromoting(true);
+  const callerRank = isSuperAdmin
+    ? ROLE_RANK.superadmin
+    : ROLE_RANK[normalizeRole(currentUser?.role)];
+
+  const handleRoleChange = async (pubkey: string, role: string) => {
+    setSavingRole(pubkey);
     setError("");
     try {
-      await api.promoteUser(promotePubkey);
-      setPromotePubkey("");
+      await api.setUserRole(pubkey, role === "guest" ? null : role);
       await loadUsers();
     } catch (err: any) {
       setError(err.message);
     } finally {
-      setPromoting(false);
-    }
-  };
-
-  const handleDemote = async (pubkey: string) => {
-    if (!confirm("Demote this user to regular user?")) return;
-    setError("");
-    try {
-      await api.demoteUser(pubkey);
-      await loadUsers();
-    } catch (err: any) {
-      setError(err.message);
-    }
-  };
-
-  const handlePromoteUser = async (pubkey: string) => {
-    setError("");
-    try {
-      await api.promoteUser(pubkey);
-      await loadUsers();
-    } catch (err: any) {
-      setError(err.message);
+      setSavingRole(null);
     }
   };
 
@@ -159,6 +282,10 @@ export default function UsersPage() {
     setUsernameDrafts((prev) => ({ ...prev, [pubkey]: stored ?? "" }));
   };
 
+  const handleDraftChange = (pubkey: string, value: string) => {
+    setUsernameDrafts((prev) => ({ ...prev, [pubkey]: value }));
+  };
+
   if (loading) {
     return (
       <div className="flex items-center justify-center min-h-[60vh]">
@@ -173,178 +300,28 @@ export default function UsersPage() {
 
       {error && <p className="text-error text-sm">{error}</p>}
 
-      <div className="bg-surface-container-low rounded-xl p-6">
-        <h2 className="text-sm font-semibold text-on-surface/70 mb-3">Promote User</h2>
-        <div className="flex gap-3">
-          <input
-            placeholder="Pubkey (hex)"
-            value={promotePubkey}
-            onChange={(e) => setPromotePubkey(e.target.value)}
-            className="bg-surface-container-highest text-on-surface rounded-lg px-4 py-3 w-full focus:outline-none focus:ring-1 focus:ring-primary/40 flex-1"
-          />
-          <button
-            onClick={handlePromote}
-            disabled={promoting || !promotePubkey.trim()}
-            className="flex items-center gap-2 px-4 py-2 rounded-lg bg-gradient-to-r from-primary to-primary-container text-on-primary font-semibold text-sm hover:opacity-90 transition-opacity disabled:opacity-50 whitespace-nowrap"
-          >
-            <UserPlus size={16} />
-            {promoting ? "Promoting..." : "Promote"}
-          </button>
-        </div>
-      </div>
-
       <div className="space-y-3">
         {users.length === 0 ? (
           <p className="text-on-surface/50 text-sm">No users found.</p>
         ) : (
-          users.map((user) => {
-            const draft = usernameDrafts[user.pubkey] ?? "";
-            const stored = user.username ?? "";
-            const usernameDirty = draft.trim().toLowerCase() !== stored.toLowerCase();
-            const profile = nostrByPubkey[user.pubkey];
-            const fullNpub = hexToNpub(user.pubkey);
-            const nostrDisplay = profile?.name || profile?.displayName;
-            return (
-            <div
+          users.map((user) => (
+            <UserRow
               key={user.pubkey || user.id}
-              className="bg-surface-container-low rounded-xl p-6 flex flex-col gap-4 sm:flex-row sm:items-start sm:justify-between"
-            >
-              <div className="flex-1 min-w-0 flex gap-4 items-start">
-                <div className="shrink-0 w-14 h-14 rounded-full bg-surface-container-high flex items-center justify-center overflow-hidden text-on-surface">
-                  {nostrLoading ? (
-                    <span className="text-on-surface/40 text-xs">…</span>
-                  ) : profile?.picture ? (
-                    <Image
-                      src={profile.picture}
-                      alt={nostrDisplay ? `Avatar: ${nostrDisplay}` : "Nostr profile picture"}
-                      width={56}
-                      height={56}
-                      className="object-cover w-full h-full"
-                      unoptimized
-                    />
-                  ) : (
-                    <span className="font-semibold text-sm" aria-hidden>
-                      {profileInitials(profile, fullNpub)}
-                    </span>
-                  )}
-                </div>
-                <div className="flex-1 min-w-0 space-y-3">
-                <div>
-                  <p className="text-on-surface font-semibold text-base truncate">
-                    {nostrLoading ? (
-                      <span className="text-on-surface/40 font-normal">…</span>
-                    ) : nostrDisplay ? (
-                      nostrDisplay
-                    ) : (
-                      <span className="text-on-surface/50 font-normal">No Nostr name</span>
-                    )}
-                  </p>
-                  <button
-                    type="button"
-                    onClick={() => handleCopyNpub(user.pubkey)}
-                    className="mt-1 text-left font-mono text-sm text-on-surface/80 hover:text-primary transition-colors cursor-pointer break-all w-full"
-                    title={fullNpub || "Copy npub"}
-                  >
-                    {copiedPubkey === user.pubkey
-                      ? "Copied!"
-                      : fullNpub
-                        ? shortenNpub(fullNpub)
-                        : `${user.pubkey?.slice(0, 12)}...${user.pubkey?.slice(-8)}`}
-                  </button>
-                </div>
-                <div>
-                  <p className="text-xs font-semibold text-on-surface/50 mb-1 uppercase tracking-wide">
-                    NIP-05 username
-                  </p>
-                  <p className="text-on-surface-variant text-xs mb-2">
-                    Reserved names from the site blocklist can be assigned here (users cannot claim them on the dashboard).
-                  </p>
-                  <div className="flex flex-wrap items-center gap-2">
-                    <input
-                      value={draft}
-                      onChange={(e) =>
-                        setUsernameDrafts((prev) => ({ ...prev, [user.pubkey]: e.target.value }))
-                      }
-                      disabled={savingPubkey === user.pubkey}
-                      placeholder="local-part"
-                      className="bg-surface-container-highest text-on-surface rounded-lg px-3 py-2 text-sm font-mono min-w-[8rem] max-w-full flex-1 focus:outline-none focus:ring-1 focus:ring-primary/40 disabled:opacity-50"
-                    />
-                    <span className="text-on-surface/50 text-sm font-mono shrink-0">
-                      @{hostname || "…"}
-                    </span>
-                    <button
-                      type="button"
-                      onClick={() => handleSaveUsername(user.pubkey, user.username)}
-                      disabled={
-                        savingPubkey === user.pubkey ||
-                        !draft.trim() ||
-                        !usernameDirty
-                      }
-                      className="px-3 py-2 rounded-lg bg-gradient-to-r from-primary to-primary-container text-on-primary font-semibold text-sm hover:opacity-90 transition-opacity disabled:opacity-50 whitespace-nowrap"
-                    >
-                      {savingPubkey === user.pubkey ? "Saving…" : "Save"}
-                    </button>
-                    <button
-                      type="button"
-                      onClick={() => handleCancelUsername(user.pubkey, user.username)}
-                      disabled={savingPubkey === user.pubkey || !usernameDirty}
-                      className="px-3 py-2 rounded-lg bg-surface-container-highest text-on-surface/70 text-sm hover:text-on-surface transition-colors disabled:opacity-50 whitespace-nowrap"
-                    >
-                      Cancel
-                    </button>
-                  </div>
-                  {draft.trim() && (
-                    <p className="text-on-surface-variant text-xs font-mono mt-2">
-                      {draft.trim().toLowerCase()}@{hostname || "…"}
-                    </p>
-                  )}
-                </div>
-                <div className="flex items-center gap-3 flex-wrap">
-                  <span
-                    className={cn(
-                      "rounded-full px-3 py-1 text-xs font-bold",
-                      user.role === "ADMIN"
-                        ? "bg-primary-container/20 text-primary"
-                        : user.role === "MODERATOR"
-                          ? "bg-secondary-container text-on-secondary-container"
-                          : "bg-surface-container-highest text-on-surface/50"
-                    )}
-                  >
-                    {user.role}
-                  </span>
-                  {user.createdAt && (
-                    <span className="text-on-surface/40 text-xs">
-                      Joined {formatDate(user.createdAt)}
-                    </span>
-                  )}
-                </div>
-              </div>
-              </div>
-              {user.role !== "ADMIN" && (
-                <div className="flex items-center gap-2">
-                  {user.role !== "MODERATOR" && (
-                    <button
-                      onClick={() => handlePromoteUser(user.pubkey)}
-                      className="flex items-center gap-2 px-3 py-2 rounded-lg bg-surface-container-highest text-on-surface/70 hover:text-primary text-sm transition-colors"
-                    >
-                      <ShieldCheck size={14} />
-                      Promote
-                    </button>
-                  )}
-                  {user.role === "MODERATOR" && (
-                    <button
-                      onClick={() => handleDemote(user.pubkey)}
-                      className="flex items-center gap-2 px-3 py-2 rounded-lg bg-surface-container-highest text-on-surface/70 hover:text-error text-sm transition-colors"
-                    >
-                      <ShieldOff size={14} />
-                      Demote
-                    </button>
-                  )}
-                </div>
-              )}
-            </div>
-            );
-          })
+              user={user}
+              draft={usernameDrafts[user.pubkey] ?? ""}
+              onDraftChange={handleDraftChange}
+              savingPubkey={savingPubkey}
+              onSaveUsername={handleSaveUsername}
+              onCancelUsername={handleCancelUsername}
+              hostname={hostname}
+              copiedPubkey={copiedPubkey}
+              onCopyNpub={handleCopyNpub}
+              callerRank={callerRank}
+              isSuperAdmin={isSuperAdmin}
+              savingRole={savingRole}
+              onRoleChange={handleRoleChange}
+            />
+          ))
         )}
       </div>
     </div>