feat: replace requireAdmin with requirePermission on all routes

Migrate settings, teams, branding, and user management routes to use
the new permission-based authorization system. Remove requireAdmin
function entirely.

apps/api/src/index.ts

@@ -8,7 +8,8 @@ import { db, schema } from "./db/index.js";
 import { runMigrations } from "./db/migrate.js";
 import { startCleanupCron } from "./lib/cleanup.js";
 import { shutdownWorkerPool } from "./lib/worker-pool.js";
-import { authMiddleware, authRoutes, ensureDefaultAdmin, requireAdmin } from "./plugins/auth.js";
+import { requirePermission } from "./permissions.js";
+import { authMiddleware, authRoutes, ensureDefaultAdmin } from "./plugins/auth.js";
 import { registerStatic } from "./plugins/static.js";
 import { registerUpload } from "./plugins/upload.js";
 import { apiKeyRoutes } from "./routes/api-keys.js";
@@ -136,7 +137,7 @@ app.get("/api/v1/health", async (_request, reply) => {
 
 // Admin health check (full diagnostics)
 app.get("/api/v1/admin/health", async (request, reply) => {
-  const admin = requireAdmin(request, reply);
+  const admin = requirePermission("settings:read")(request, reply);
   if (!admin) return;
 
   let dbOk = false;

apps/api/src/plugins/auth.ts

@@ -85,17 +85,6 @@ export function requireAuth(request: FastifyRequest, reply: FastifyReply): AuthU
   return user;
 }
 
-/** Require an admin user, sending 403 if not admin. */
-export function requireAdmin(request: FastifyRequest, reply: FastifyReply): AuthUser | null {
-  const user = requireAuth(request, reply);
-  if (!user) return null;
-  if (user.role !== "admin") {
-    reply.status(403).send({ error: "Admin access required", code: "FORBIDDEN" });
-    return null;
-  }
-  return user;
-}
-
 // ── Session helpers ────────────────────────────────────────────────
 
 const SESSION_DURATION_MS = 24 * 60 * 60 * 1000; // 24 hours
@@ -341,8 +330,11 @@ export async function authRoutes(app: FastifyInstance): Promise<void> {
 
   // GET /api/auth/users (admin only)
   app.get("/api/auth/users", async (request: FastifyRequest, reply: FastifyReply) => {
-    const admin = requireAdmin(request, reply);
+    const admin = requireAuth(request, reply);
     if (!admin) return;
+    if (!getPermissions(admin.role as "admin" | "user").includes("users:manage")) {
+      return reply.status(403).send({ error: "Insufficient permissions", code: "FORBIDDEN" });
+    }
 
     const users = db
       .select({
@@ -371,8 +363,11 @@ export async function authRoutes(app: FastifyInstance): Promise<void> {
 
   // POST /api/auth/register (admin only)
   app.post("/api/auth/register", async (request: FastifyRequest, reply: FastifyReply) => {
-    const admin = requireAdmin(request, reply);
+    const admin = requireAuth(request, reply);
     if (!admin) return;
+    if (!getPermissions(admin.role as "admin" | "user").includes("users:manage")) {
+      return reply.status(403).send({ error: "Insufficient permissions", code: "FORBIDDEN" });
+    }
 
     const body = request.body as {
       username?: string;
@@ -487,12 +482,15 @@ export async function authRoutes(app: FastifyInstance): Promise<void> {
     });
   });
 
-  // PUT /api/auth/users/:id (admin only — update role/team)
+  // PUT /api/auth/users/:id (admin only -- update role/team)
   app.put(
     "/api/auth/users/:id",
     async (request: FastifyRequest<{ Params: { id: string } }>, reply: FastifyReply) => {
-      const admin = requireAdmin(request, reply);
+      const admin = requireAuth(request, reply);
       if (!admin) return;
+      if (!getPermissions(admin.role as "admin" | "user").includes("users:manage")) {
+        return reply.status(403).send({ error: "Insufficient permissions", code: "FORBIDDEN" });
+      }
 
       const { id } = request.params;
       const body = request.body as { role?: string; team?: string } | null;
@@ -551,8 +549,11 @@ export async function authRoutes(app: FastifyInstance): Promise<void> {
   app.post(
     "/api/auth/users/:id/reset-password",
     async (request: FastifyRequest<{ Params: { id: string } }>, reply: FastifyReply) => {
-      const admin = requireAdmin(request, reply);
+      const admin = requireAuth(request, reply);
       if (!admin) return;
+      if (!getPermissions(admin.role as "admin" | "user").includes("users:manage")) {
+        return reply.status(403).send({ error: "Insufficient permissions", code: "FORBIDDEN" });
+      }
 
       const { id } = request.params;
       const body = request.body as { newPassword?: string } | null;
@@ -605,8 +606,11 @@ export async function authRoutes(app: FastifyInstance): Promise<void> {
   app.delete(
     "/api/auth/users/:id",
     async (request: FastifyRequest<{ Params: { id: string } }>, reply: FastifyReply) => {
-      const admin = requireAdmin(request, reply);
+      const admin = requireAuth(request, reply);
       if (!admin) return;
+      if (!getPermissions(admin.role as "admin" | "user").includes("users:manage")) {
+        return reply.status(403).send({ error: "Insufficient permissions", code: "FORBIDDEN" });
+      }
 
       const { id } = request.params;
 
@@ -673,7 +677,7 @@ function isPublicRoute(url: string): boolean {
 
 export async function authMiddleware(app: FastifyInstance): Promise<void> {
   app.addHook("preHandler", async (request: FastifyRequest, reply: FastifyReply) => {
-    // When auth is disabled, attach the first admin user so requireAuth/requireAdmin pass
+    // When auth is disabled, attach the first admin user so requireAuth/requirePermission pass
     if (!env.AUTH_ENABLED) {
       const adminUser = db.select().from(schema.users).where(eq(schema.users.role, "admin")).get();
       if (adminUser) {

apps/api/src/routes/branding.ts

@@ -12,7 +12,7 @@ import { eq } from "drizzle-orm";
 import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
 import sharp from "sharp";
 import { db, schema } from "../db/index.js";
-import { requireAdmin } from "../plugins/auth.js";
+import { requirePermission } from "../permissions.js";
 
 const BRANDING_DIR = join(process.cwd(), "data", "branding");
 const LOGO_PATH = join(BRANDING_DIR, "logo.png");
@@ -33,7 +33,7 @@ function upsertSetting(key: string, value: string): void {
 export async function brandingRoutes(app: FastifyInstance): Promise<void> {
   // POST /api/v1/settings/logo — Upload logo (admin only)
   app.post("/api/v1/settings/logo", async (request: FastifyRequest, reply: FastifyReply) => {
-    const admin = requireAdmin(request, reply);
+    const admin = requirePermission("branding:manage")(request, reply);
     if (!admin) return;
 
     const file = await request.file();
@@ -86,7 +86,7 @@ export async function brandingRoutes(app: FastifyInstance): Promise<void> {
 
   // DELETE /api/v1/settings/logo — Remove logo (admin only)
   app.delete("/api/v1/settings/logo", async (request: FastifyRequest, reply: FastifyReply) => {
-    const admin = requireAdmin(request, reply);
+    const admin = requirePermission("branding:manage")(request, reply);
     if (!admin) return;
 
     if (existsSync(LOGO_PATH)) {

apps/api/src/routes/settings.ts

@@ -10,14 +10,14 @@ import { PYTHON_SIDECAR_TOOLS } from "@stirling-image/shared";
 import { eq } from "drizzle-orm";
 import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
 import { db, schema } from "../db/index.js";
-import { requireAdmin, requireAuth } from "../plugins/auth.js";
+import { requirePermission } from "../permissions.js";
 
 const HTML_TAG_PATTERN = /<[a-z/!][^>]*>/i;
 
 export async function settingsRoutes(app: FastifyInstance): Promise<void> {
   // GET /api/v1/settings — Get all settings as a key-value object
   app.get("/api/v1/settings", async (request: FastifyRequest, reply: FastifyReply) => {
-    const user = requireAuth(request, reply);
+    const user = requirePermission("settings:read")(request, reply);
     if (!user) return;
 
     const rows = db.select().from(schema.settings).all();
@@ -35,7 +35,7 @@ export async function settingsRoutes(app: FastifyInstance): Promise<void> {
 
   // PUT /api/v1/settings — Save settings (admin only)
   app.put("/api/v1/settings", async (request: FastifyRequest, reply: FastifyReply) => {
-    const admin = requireAdmin(request, reply);
+    const admin = requirePermission("settings:write")(request, reply);
     if (!admin) return;
 
     const body = request.body as Record<string, unknown> | null;
@@ -89,7 +89,7 @@ export async function settingsRoutes(app: FastifyInstance): Promise<void> {
   app.get(
     "/api/v1/settings/:key",
     async (request: FastifyRequest<{ Params: { key: string } }>, reply: FastifyReply) => {
-      const user = requireAuth(request, reply);
+      const user = requirePermission("settings:read")(request, reply);
       if (!user) return;
 
       const { key } = request.params;

apps/api/src/routes/teams.ts

@@ -11,7 +11,7 @@ import { randomUUID } from "node:crypto";
 import { eq, sql } from "drizzle-orm";
 import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
 import { db, schema } from "../db/index.js";
-import { requireAdmin, requireAuth } from "../plugins/auth.js";
+import { requirePermission } from "../permissions.js";
 
 function validateTeamName(name: unknown): string | null {
   if (typeof name !== "string") return "Team name is required";
@@ -24,7 +24,7 @@ function validateTeamName(name: unknown): string | null {
 export async function teamsRoutes(app: FastifyInstance): Promise<void> {
   // GET /api/v1/teams — List all teams with member count
   app.get("/api/v1/teams", async (request: FastifyRequest, reply: FastifyReply) => {
-    const user = requireAuth(request, reply);
+    const user = requirePermission("teams:manage")(request, reply);
     if (!user) return;
 
     const teams = db
@@ -47,7 +47,7 @@ export async function teamsRoutes(app: FastifyInstance): Promise<void> {
 
   // POST /api/v1/teams — Create team (admin only)
   app.post("/api/v1/teams", async (request: FastifyRequest, reply: FastifyReply) => {
-    const admin = requireAdmin(request, reply);
+    const admin = requirePermission("teams:manage")(request, reply);
     if (!admin) return;
 
     const body = request.body as { name?: string } | null;
@@ -81,7 +81,7 @@ export async function teamsRoutes(app: FastifyInstance): Promise<void> {
   app.put(
     "/api/v1/teams/:id",
     async (request: FastifyRequest<{ Params: { id: string } }>, reply: FastifyReply) => {
-      const admin = requireAdmin(request, reply);
+      const admin = requirePermission("teams:manage")(request, reply);
       if (!admin) return;
 
       const { id } = request.params;
@@ -122,7 +122,7 @@ export async function teamsRoutes(app: FastifyInstance): Promise<void> {
   app.delete(
     "/api/v1/teams/:id",
     async (request: FastifyRequest<{ Params: { id: string } }>, reply: FastifyReply) => {
-      const admin = requireAdmin(request, reply);
+      const admin = requirePermission("teams:manage")(request, reply);
       if (!admin) return;
 
       const { id } = request.params;