feat: add backend permission map and requirePermission middleware

Create the RBAC permission module that maps roles to permissions and
provides a requirePermission middleware to replace requireAdmin. Update
the test server to use requirePermission for the admin health check.

apps/api/src/permissions.ts

@@ -0,0 +1,44 @@
+import type { Permission, Role } from "@stirling-image/shared";
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { getAuthUser } from "./plugins/auth.js";
+
+const ROLE_PERMISSIONS: Record<Role, Permission[]> = {
+  admin: [
+    "tools:use",
+    "files:own",
+    "files:all",
+    "apikeys:own",
+    "apikeys:all",
+    "pipelines:own",
+    "pipelines:all",
+    "settings:read",
+    "settings:write",
+    "users:manage",
+    "teams:manage",
+    "branding:manage",
+  ],
+  user: ["tools:use", "files:own", "apikeys:own", "pipelines:own", "settings:read"],
+};
+
+export function getPermissions(role: Role): Permission[] {
+  return ROLE_PERMISSIONS[role] ?? [];
+}
+
+export function hasPermission(role: Role, permission: Permission): boolean {
+  return getPermissions(role).includes(permission);
+}
+
+export function requirePermission(permission: Permission) {
+  return (request: FastifyRequest, reply: FastifyReply) => {
+    const user = getAuthUser(request);
+    if (!user) {
+      reply.status(401).send({ error: "Authentication required", code: "AUTH_REQUIRED" });
+      return null;
+    }
+    if (!hasPermission(user.role as Role, permission)) {
+      reply.status(403).send({ error: "Insufficient permissions", code: "FORBIDDEN" });
+      return null;
+    }
+    return user;
+  };
+}

tests/integration/test-server.ts

@@ -29,12 +29,8 @@ import Fastify from "fastify";
 import { env } from "../../apps/api/src/config.js";
 import { db, schema } from "../../apps/api/src/db/index.js";
 import { runMigrations } from "../../apps/api/src/db/migrate.js";
-import {
+import { requirePermission } from "../../apps/api/src/permissions.js";
-  authMiddleware,
+import { authMiddleware, authRoutes, ensureDefaultAdmin } from "../../apps/api/src/plugins/auth.js";
-  authRoutes,
-  ensureDefaultAdmin,
-  requireAdmin,
-} from "../../apps/api/src/plugins/auth.js";
 import { registerUpload } from "../../apps/api/src/plugins/upload.js";
 import { apiKeyRoutes } from "../../apps/api/src/routes/api-keys.js";
 import { registerBatchRoutes } from "../../apps/api/src/routes/batch.js";
@@ -123,7 +119,7 @@ export async function buildTestApp(): Promise<TestApp> {
 
   // 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;

tests/unit/api/permissions.test.ts

@@ -0,0 +1,76 @@
+/**
+ * Unit tests for the permission map and helper functions.
+ *
+ * Verifies that each role gets the correct set of permissions
+ * and that the hasPermission check works as expected.
+ */
+
+import type { Role } from "@stirling-image/shared";
+import { describe, expect, it } from "vitest";
+import { getPermissions, hasPermission } from "../../../apps/api/src/permissions.js";
+
+describe("permissions", () => {
+  describe("getPermissions", () => {
+    it("returns all 12 permissions for admin", () => {
+      const perms = getPermissions("admin");
+      expect(perms).toHaveLength(12);
+      expect(perms).toContain("tools:use");
+      expect(perms).toContain("files:own");
+      expect(perms).toContain("files:all");
+      expect(perms).toContain("apikeys:own");
+      expect(perms).toContain("apikeys:all");
+      expect(perms).toContain("pipelines:own");
+      expect(perms).toContain("pipelines:all");
+      expect(perms).toContain("settings:read");
+      expect(perms).toContain("settings:write");
+      expect(perms).toContain("users:manage");
+      expect(perms).toContain("teams:manage");
+      expect(perms).toContain("branding:manage");
+    });
+
+    it("returns only basic permissions for user role", () => {
+      const perms = getPermissions("user");
+      expect(perms).toEqual([
+        "tools:use",
+        "files:own",
+        "apikeys:own",
+        "pipelines:own",
+        "settings:read",
+      ]);
+    });
+
+    it("does NOT contain admin-only permissions for user role", () => {
+      const perms = getPermissions("user");
+      expect(perms).not.toContain("files:all");
+      expect(perms).not.toContain("apikeys:all");
+      expect(perms).not.toContain("pipelines:all");
+      expect(perms).not.toContain("settings:write");
+      expect(perms).not.toContain("users:manage");
+      expect(perms).not.toContain("teams:manage");
+      expect(perms).not.toContain("branding:manage");
+    });
+
+    it("returns empty array for unknown role", () => {
+      const perms = getPermissions("unknown" as Role);
+      expect(perms).toEqual([]);
+    });
+  });
+
+  describe("hasPermission", () => {
+    it("returns true for admin with users:manage", () => {
+      expect(hasPermission("admin", "users:manage")).toBe(true);
+    });
+
+    it("returns true for user with tools:use", () => {
+      expect(hasPermission("user", "tools:use")).toBe(true);
+    });
+
+    it("returns false for user with users:manage", () => {
+      expect(hasPermission("user", "users:manage")).toBe(false);
+    });
+
+    it("returns false for user with settings:write", () => {
+      expect(hasPermission("user", "settings:write")).toBe(false);
+    });
+  });
+});