feat(auth): two-role permission system (admin/member)

Adds an admin/member role to WebUI auth. /api/users and /api/audit
are now gated by a requireAdmin middleware; all other authenticated
endpoints accept both roles. Schema migration defaults all existing
users to admin to preserve access. POST /api/users defaults new users
to member; first-run setup always creates an admin. Adds PATCH
/api/users/:id/role with last-admin demotion and deletion guards.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/data/audit.ts

@@ -5,7 +5,8 @@ export type AuditAction =
   | "user.created"
   | "user.deleted"
   | "user.password_reset"
-  | "user.password_changed";
+  | "user.password_changed"
+  | "user.role_changed";
 
 export interface AuditEntry {
   id: number;

src/data/database.test.ts

@@ -33,7 +33,7 @@ describe("database", () => {
 
     const userCols = botDb.db.prepare("PRAGMA table_info(users)").all() as Array<{ name: string }>;
     const userColNames = userCols.map((c) => c.name).sort();
-    expect(userColNames).toEqual(["createdAt", "id", "passwordHash", "updatedAt", "username"]);
+    expect(userColNames).toEqual(["createdAt", "id", "passwordHash", "role", "updatedAt", "username"]);
 
     const sessionCols = botDb.db.prepare("PRAGMA table_info(sessions)").all() as Array<{ name: string }>;
     const sessionColNames = sessionCols.map((c) => c.name).sort();

src/data/database.ts

@@ -97,6 +97,12 @@ function migrateSchema(db: Database.Database): void {
   if (!names.includes("custom_avatar_path")) {
     db.exec("ALTER TABLE bot_instances ADD COLUMN custom_avatar_path TEXT");
   }
+
+  const userColumns = db.prepare("PRAGMA table_info(users)").all() as Array<{ name: string }>;
+  const userColNames = userColumns.map((c) => c.name);
+  if (!userColNames.includes("role")) {
+    db.exec("ALTER TABLE users ADD COLUMN role TEXT NOT NULL DEFAULT 'admin'");
+  }
 }
 
 function initTables(db: Database.Database): void {
@@ -133,7 +139,8 @@ function initTables(db: Database.Database): void {
       username TEXT NOT NULL UNIQUE COLLATE NOCASE,
       passwordHash TEXT NOT NULL,
       createdAt INTEGER NOT NULL,
-      updatedAt INTEGER NOT NULL
+      updatedAt INTEGER NOT NULL,
+      role TEXT NOT NULL DEFAULT 'admin'
     );
 
     CREATE TABLE IF NOT EXISTS sessions (

src/data/sessions.test.ts

@@ -18,7 +18,7 @@ describe("SessionStore", () => {
     botDb = createDatabase(":memory:");
     users = createUserStore(botDb.db);
     sessions = createSessionStore(botDb.db);
-    const u = await users.createUser("alice", "pw");
+    const u = await users.createUser("alice", "pw-alice", "admin");
     userId = u.id;
   });
 
@@ -40,6 +40,7 @@ describe("SessionStore", () => {
     expect(result).not.toBeNull();
     expect(result!.userId).toBe(userId);
     expect(result!.username).toBe("alice");
+    expect(result!.role).toBe("admin");
   });
 
   it("validateAndTouch returns null and deletes the row for an expired session", () => {

src/data/sessions.ts

@@ -7,6 +7,7 @@ export const SESSION_TOUCH_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
 export interface SessionValidation {
   userId: string;
   username: string;
+  role: "admin" | "member";
 }
 
 export interface SessionStore {
@@ -26,7 +27,7 @@ export function createSessionStore(db: Database.Database): SessionStore {
     "INSERT INTO sessions (id, userId, createdAt, expiresAt, lastSeenAt) VALUES (?, ?, ?, ?, ?)"
   );
   const selectStmt = db.prepare(`
-    SELECT s.id, s.userId, s.expiresAt, s.lastSeenAt, u.username
+    SELECT s.id, s.userId, s.expiresAt, s.lastSeenAt, u.username, u.role
     FROM sessions s INNER JOIN users u ON u.id = s.userId
     WHERE s.id = ?
   `);
@@ -54,7 +55,7 @@ export function createSessionStore(db: Database.Database): SessionStore {
       if (!rawToken) return null;
       const id = hashToken(rawToken);
       const row = selectStmt.get(id) as
-        | { id: string; userId: string; expiresAt: number; lastSeenAt: number; username: string }
+        | { id: string; userId: string; expiresAt: number; lastSeenAt: number; username: string; role: string }
         | undefined;
       if (!row) return null;
       const now = Date.now();
@@ -65,7 +66,7 @@ export function createSessionStore(db: Database.Database): SessionStore {
       if (now - row.lastSeenAt > SESSION_TOUCH_INTERVAL_MS) {
         touchStmt.run(now, now + SESSION_TTL_MS, id);
       }
-      return { userId: row.userId, username: row.username };
+      return { userId: row.userId, username: row.username, role: row.role as "admin" | "member" };
     },
 
     deleteSession(rawToken) {

src/data/users.test.ts

@@ -20,26 +20,26 @@ describe("UserStore", () => {
   });
 
   it("createUser stores the user and bumps countUsers", async () => {
-    const u = await users.createUser("alice", "pw-hunter2");
+    const u = await users.createUser("alice", "pw-hunter2", "member");
     expect(u.id).toMatch(/^[0-9a-f-]{36}$/);
     expect(u.username).toBe("alice");
     expect(users.countUsers()).toBe(1);
   });
 
   it("findByUsername is case-insensitive and returns null for missing", async () => {
-    await users.createUser("Alice", "pw");
+    await users.createUser("Alice", "pw-alice", "member");
     expect(users.findByUsername("ALICE")).not.toBeNull();
     expect(users.findByUsername("alice")).not.toBeNull();
     expect(users.findByUsername("bob")).toBeNull();
   });
 
   it("createUser rejects duplicate usernames (case-insensitive)", async () => {
-    await users.createUser("Alice", "pw");
-    await expect(users.createUser("alice", "pw2")).rejects.toBeInstanceOf(UsernameTakenError);
+    await users.createUser("Alice", "pw-alice", "member");
+    await expect(users.createUser("alice", "pw-alice-2", "member")).rejects.toBeInstanceOf(UsernameTakenError);
   });
 
   it("verifyPassword accepts correct password and rejects wrong one", async () => {
-    await users.createUser("alice", "correct-horse-battery-staple");
+    await users.createUser("alice", "correct-horse-battery-staple", "member");
     const row = users.findByUsername("alice");
     expect(row).not.toBeNull();
     expect(await users.verifyPassword("correct-horse-battery-staple", row!.passwordHash)).toBe(true);
@@ -47,16 +47,16 @@ describe("UserStore", () => {
   });
 
   it("changePassword updates the hash so the old password no longer verifies", async () => {
-    const u = await users.createUser("alice", "old");
-    await users.changePassword(u.id, "new");
+    const u = await users.createUser("alice", "old-pw-pw", "member");
+    await users.changePassword(u.id, "new-pw-pw");
     const row = users.findByUsername("alice");
-    expect(await users.verifyPassword("old", row!.passwordHash)).toBe(false);
-    expect(await users.verifyPassword("new", row!.passwordHash)).toBe(true);
+    expect(await users.verifyPassword("old-pw-pw", row!.passwordHash)).toBe(false);
+    expect(await users.verifyPassword("new-pw-pw", row!.passwordHash)).toBe(true);
   });
 
   it("listUsers returns id+username+createdAt ascending, no password hash", async () => {
-    await users.createUser("alice", "pw-alice");
-    await users.createUser("bob", "pw-bob");
+    await users.createUser("alice", "pw-alice", "member");
+    await users.createUser("bob", "pw-bob-bob", "member");
     const list = users.listUsers();
     expect(list).toHaveLength(2);
     expect(list[0].username).toBe("alice");
@@ -67,7 +67,7 @@ describe("UserStore", () => {
   });
 
   it("deleteUser removes the row and returns true; returns false for unknown id", async () => {
-    const u = await users.createUser("alice", "pw-alice");
+    const u = await users.createUser("alice", "pw-alice", "member");
     expect(users.deleteUser(u.id)).toBe(true);
     expect(users.countUsers()).toBe(0);
     expect(users.deleteUser("not-a-real-id")).toBe(false);
@@ -92,4 +92,34 @@ describe("UserStore", () => {
     expect(created).toHaveLength(1);
     expect(users.countUsers()).toBe(1);
   });
+
+  it("createFirstUser always creates an admin", async () => {
+    const u = await users.createFirstUser("alice", "pw-alice");
+    expect(u).not.toBeNull();
+    expect(u!.role).toBe("admin");
+  });
+
+  it("countAdmins reflects only role=admin", async () => {
+    await users.createUser("alice", "pw-alice", "admin");
+    await users.createUser("bob", "pw-bob-bob", "member");
+    expect(users.countUsers()).toBe(2);
+    expect(users.countAdmins()).toBe(1);
+  });
+
+  it("setRole changes the role and returns true; false for unknown id", async () => {
+    const u = await users.createUser("alice", "pw-alice", "member");
+    expect(users.setRole(u.id, "admin")).toBe(true);
+    expect(users.findById(u.id)!.role).toBe("admin");
+    expect(users.setRole("nope", "admin")).toBe(false);
+  });
+
+  it("listUsers includes role", async () => {
+    await users.createUser("alice", "pw-alice", "admin");
+    await users.createUser("bob", "pw-bob-bob", "member");
+    const list = users.listUsers();
+    const alice = list.find((u) => u.username === "alice")!;
+    const bob = list.find((u) => u.username === "bob")!;
+    expect(alice.role).toBe("admin");
+    expect(bob.role).toBe("member");
+  });
 });

src/data/users.ts

@@ -4,24 +4,29 @@ import bcrypt from "bcryptjs";
 
 const BCRYPT_ROUNDS = 12;
 
+export type UserRole = "admin" | "member";
+
 export interface UserRow {
   id: string;
   username: string;
   passwordHash: string;
   createdAt: number;
   updatedAt: number;
+  role: UserRole;
 }
 
 export interface UserStore {
   countUsers(): number;
-  createUser(username: string, password: string): Promise<UserRow>;
+  countAdmins(): number;
+  createUser(username: string, password: string, role: UserRole): Promise<UserRow>;
   createFirstUser(username: string, password: string): Promise<UserRow | null>;
   findByUsername(username: string): UserRow | null;
   findById(id: string): UserRow | null;
   verifyPassword(plain: string, hash: string): Promise<boolean>;
   changePassword(userId: string, newPassword: string): Promise<void>;
-  listUsers(): Array<{ id: string; username: string; createdAt: number }>;
+  setRole(userId: string, role: UserRole): boolean;
   deleteUser(id: string): boolean;
+  listUsers(): Array<{ id: string; username: string; createdAt: number; role: UserRole }>;
 }
 
 export class UsernameTakenError extends Error {
@@ -33,20 +38,24 @@ export class UsernameTakenError extends Error {
 
 export function createUserStore(db: Database.Database): UserStore {
   const countStmt = db.prepare("SELECT COUNT(*) AS n FROM users");
+  const countAdminsStmt = db.prepare("SELECT COUNT(*) AS n FROM users WHERE role = 'admin'");
   const insertStmt = db.prepare(
-    "INSERT INTO users (id, username, passwordHash, createdAt, updatedAt) VALUES (?, ?, ?, ?, ?)"
+    "INSERT INTO users (id, username, passwordHash, createdAt, updatedAt, role) VALUES (?, ?, ?, ?, ?, ?)"
   );
   const findByUsernameStmt = db.prepare(
-    "SELECT id, username, passwordHash, createdAt, updatedAt FROM users WHERE username = ? COLLATE NOCASE"
+    "SELECT id, username, passwordHash, createdAt, updatedAt, role FROM users WHERE username = ? COLLATE NOCASE"
   );
   const findByIdStmt = db.prepare(
-    "SELECT id, username, passwordHash, createdAt, updatedAt FROM users WHERE id = ?"
+    "SELECT id, username, passwordHash, createdAt, updatedAt, role FROM users WHERE id = ?"
   );
   const updatePasswordStmt = db.prepare(
     "UPDATE users SET passwordHash = ?, updatedAt = ? WHERE id = ?"
   );
+  const updateRoleStmt = db.prepare(
+    "UPDATE users SET role = ?, updatedAt = ? WHERE id = ?"
+  );
   const listUsersStmt = db.prepare(
-    "SELECT id, username, createdAt FROM users ORDER BY createdAt ASC"
+    "SELECT id, username, createdAt, role FROM users ORDER BY createdAt ASC"
   );
   const deleteUserStmt = db.prepare("DELETE FROM users WHERE id = ?");
 
@@ -55,19 +64,23 @@ export function createUserStore(db: Database.Database): UserStore {
       return (countStmt.get() as { n: number }).n;
     },
 
-    async createUser(username, password) {
+    countAdmins() {
+      return (countAdminsStmt.get() as { n: number }).n;
+    },
+
+    async createUser(username, password, role) {
       const hash = await bcrypt.hash(password, BCRYPT_ROUNDS);
       const id = randomUUID();
       const now = Date.now();
       try {
-        insertStmt.run(id, username, hash, now, now);
+        insertStmt.run(id, username, hash, now, now, role);
       } catch (err) {
         if (err && typeof err === "object" && (err as { code?: string }).code === "SQLITE_CONSTRAINT_UNIQUE") {
           throw new UsernameTakenError(username);
         }
         throw err;
       }
-      return { id, username, passwordHash: hash, createdAt: now, updatedAt: now };
+      return { id, username, passwordHash: hash, createdAt: now, updatedAt: now, role };
     },
 
     async createFirstUser(username, password) {
@@ -78,14 +91,14 @@ export function createUserStore(db: Database.Database): UserStore {
         const count = (countStmt.get() as { n: number }).n;
         if (count !== 0) return null;
         try {
-          insertStmt.run(id, username, hash, now, now);
+          insertStmt.run(id, username, hash, now, now, "admin");
         } catch (err) {
           if (err && typeof err === "object" && (err as { code?: string }).code === "SQLITE_CONSTRAINT_UNIQUE") {
             return null;
           }
           throw err;
         }
-        return { id, username, passwordHash: hash, createdAt: now, updatedAt: now } as UserRow;
+        return { id, username, passwordHash: hash, createdAt: now, updatedAt: now, role: "admin" } as UserRow;
       });
       return run();
     },
@@ -107,8 +120,13 @@ export function createUserStore(db: Database.Database): UserStore {
       updatePasswordStmt.run(hash, Date.now(), userId);
     },
 
+    setRole(userId, role) {
+      const result = updateRoleStmt.run(role, Date.now(), userId);
+      return result.changes > 0;
+    },
+
     listUsers() {
-      return listUsersStmt.all() as Array<{ id: string; username: string; createdAt: number }>;
+      return listUsersStmt.all() as Array<{ id: string; username: string; createdAt: number; role: UserRole }>;
     },
 
     deleteUser(id) {