feat: add configurable headers and instance branding (#6690)

packages/api/src/router/assistant.ts

@@ -495,7 +495,7 @@ export const assistantRouter = createTRPCRouter({
         models: [
           {
             id: "homarr-assistant",
-            name: "Homarr Assistant (Demo)",
+            name: "Assistant (Demo)",
             description: null,
             contextLength: null,
             promptPrice: null,
@@ -507,7 +507,7 @@ export const assistantRouter = createTRPCRouter({
       };
     }
     if (!configuration?.enabled || !configuration.modelId) {
-      throw new TRPCError({ code: "PRECONDITION_FAILED", message: "Homarr Assistant is not configured." });
+      throw new TRPCError({ code: "PRECONDITION_FAILED", message: "Assistant is not configured." });
     }
     const discoveredModels = await getAssistantModelsAsync(configuration).catch(() => []);
     const resolvedDefaultId = resolveAssistantModelId(discoveredModels, configuration.modelId) ?? configuration.modelId;
@@ -708,7 +708,7 @@ export const assistantRouter = createTRPCRouter({
         getConfigurationAsync(ctx.db),
       ]);
       if (!configuration?.enabled || !configuration.modelId) {
-        throw new TRPCError({ code: "PRECONDITION_FAILED", message: "Homarr Assistant is not configured." });
+        throw new TRPCError({ code: "PRECONDITION_FAILED", message: "Assistant is not configured." });
       }
       const selectedModel = await getSelectedModelDetailsAsync(configuration, input.modelId).catch(() => null);
       if (input.modelId !== configuration.modelId && !selectedModel) {

packages/api/src/router/board.ts

@@ -87,7 +87,9 @@ interface BoardItemPlacementRectangle {
 
 const boardItemPlacementTails = new Map<string, Promise<void>>();
 const maxManageOverviewPreviewRows = 12;
-const manageOverviewInputSchema = z.object({ fullPreview: z.boolean().default(false) }).optional();
+const manageOverviewInputSchema = z
+  .object({ fullPreview: z.boolean().default(false), userId: z.string().optional() })
+  .optional();
 
 const serializeBoardItemPlacementAsync = async <T>(boardId: string, operation: () => Promise<T>) => {
   const previous = boardItemPlacementTails.get(boardId) ?? Promise.resolve();
@@ -140,6 +142,7 @@ const searchAccessibleBoardsAsync = async (
       group: {
         with: {
           boardPermissions: {},
+          permissions: {},
         },
       },
     },
@@ -300,9 +303,14 @@ export const boardRouter = createTRPCRouter({
       }));
     }),
   getManageOverview: publicProcedure.input(manageOverviewInputSchema).query(async ({ ctx, input }) => {
-    const userId = ctx.session?.user.id;
+    const sessionUserId = ctx.session?.user.id;
+    const userId = input?.userId ?? sessionUserId;
+    if (userId !== sessionUserId && !ctx.session?.user.permissions.includes("admin")) {
+      throw new TRPCError({ code: "FORBIDDEN", message: "You are not allowed to view boards for this user" });
+    }
     const { boardIds, currentUser, groupMemberships } = await getBoardAccessContextAsync(ctx.db, userId);
     const groupPermissionWhere = getBoardGroupPermissionWhere(groupMemberships);
+    const canViewAllBoards = getCanViewAllBoards(groupMemberships);
 
     const dbBoards = await ctx.db.query.boards.findMany({
       columns: {
@@ -352,7 +360,7 @@ export const boardRouter = createTRPCRouter({
           orderBy: (section, { asc }) => [asc(section.xOffset), asc(section.id)],
         },
       },
-      where: getAccessibleBoardsWhere(ctx.session?.user.permissions.includes("board-view-all"), userId, boardIds),
+      where: getAccessibleBoardsWhere(canViewAllBoards, userId, boardIds),
     });
 
     const previewLayoutIds = dbBoards.flatMap((board) => board.layouts.map((layout) => layout.id));
@@ -2577,6 +2585,7 @@ const getBoardAccessContextAsync = async (db: Database, userId: string | undefin
         group: {
           with: {
             boardPermissions: {},
+            permissions: {},
           },
         },
       },
@@ -2600,6 +2609,24 @@ const getBoardAccessContextAsync = async (db: Database, userId: string | undefin
   return { boardIds, currentUser, groupMemberships };
 };
 
+const getCanViewAllBoards = (
+  groupMemberships: Awaited<ReturnType<typeof getBoardAccessContextAsync>>["groupMemberships"],
+) => {
+  const permissions = new Set(
+    groupMemberships.flatMap((membership) => membership.group.permissions.map(({ permission }) => permission)),
+  );
+  return getPermissionsWithChildren([...permissions]).includes("board-view-all");
+};
+
+export const getAccessibleBoardIdsForUserAsync = async (db: Database, userId: string) => {
+  const { boardIds, groupMemberships } = await getBoardAccessContextAsync(db, userId);
+  const accessibleBoards = await db.query.boards.findMany({
+    columns: { id: true },
+    where: getAccessibleBoardsWhere(getCanViewAllBoards(groupMemberships), userId, boardIds),
+  });
+  return new Set(accessibleBoards.map(({ id }) => id));
+};
+
 const getBoardGroupPermissionWhere = (
   groupMemberships: Awaited<ReturnType<typeof getBoardAccessContextAsync>>["groupMemberships"],
 ) =>

packages/api/src/router/serverSettings.ts

@@ -10,7 +10,12 @@ import {
 } from "@homarr/db/queries";
 import { boards, serverSettings } from "@homarr/db/schema";
 import type { ServerSettings } from "@homarr/server-settings";
-import { defaultServerSettingsKeys } from "@homarr/server-settings";
+import {
+  authBrandingSchema,
+  brandingServerSettingsSchema,
+  defaultServerSettingsKeys,
+  parseBrandingSettings,
+} from "@homarr/server-settings";
 
 import { createTRPCRouter, permissionRequiredProcedure, publicProcedure } from "../trpc";
 
@@ -22,7 +27,14 @@ const boardServerSettingsSchema = z.object({
 }) satisfies z.ZodType<ServerSettings["board"]>;
 
 const boardServerSettingsUpdateSchema = boardServerSettingsSchema.partial();
-
+const brandingServerSettingsUpdateSchema = brandingServerSettingsSchema.partial().extend({
+  authBranding: authBrandingSchema.partial().optional(),
+});
+const legacyAuthBrandingUpdateSchema = z.object({
+  showCustomAppNameOnLogin: z.boolean().optional(),
+  showCustomLogoOnLogin: z.boolean().optional(),
+  showCustomGreetingOnLogin: z.boolean().optional(),
+});
 export const serverSettingsRouter = createTRPCRouter({
   getCulture: publicProcedure.query(async ({ ctx }) => {
     return await getServerSettingByKeyAsync(ctx.db, "culture");
@@ -30,6 +42,14 @@ export const serverSettingsRouter = createTRPCRouter({
   getAll: permissionRequiredProcedure.requiresPermission("admin").query(async ({ ctx }) => {
     return await getServerSettingsAsync(ctx.db);
   }),
+  getBranding: publicProcedure
+    .meta({
+      mcp: { enabled: true, description: "Returns the public instance branding configuration." },
+    })
+    .query(async ({ ctx }) => {
+      const branding = await getServerSettingByKeyAsync(ctx.db, "branding");
+      return parseBrandingSettings(branding);
+    }),
   getBoardSettings: permissionRequiredProcedure
     .requiresPermission("admin")
     .meta({
@@ -100,10 +120,27 @@ export const serverSettingsRouter = createTRPCRouter({
       }),
     )
     .mutation(async ({ ctx, input }) => {
+      if (input.settingsKey === "branding") {
+        const current = await getServerSettingByKeyAsync(ctx.db, "branding");
+        const parsedInput = brandingServerSettingsUpdateSchema.parse(input.value);
+        const legacyInput = legacyAuthBrandingUpdateSchema.parse(input.value);
+        const authBranding = { ...current.authBranding };
+        authBranding.showAppName = legacyInput.showCustomAppNameOnLogin ?? authBranding.showAppName;
+        authBranding.showLogo = legacyInput.showCustomLogoOnLogin ?? authBranding.showLogo;
+        authBranding.showGreeting = legacyInput.showCustomGreetingOnLogin ?? authBranding.showGreeting;
+        Object.assign(authBranding, parsedInput.authBranding);
+        const value = brandingServerSettingsSchema.parse({
+          ...parseBrandingSettings(current),
+          ...parsedInput,
+          authBranding,
+        });
+        await updateServerSettingByKeyAsync(ctx.db, "branding", value);
+        return;
+      }
       const current = await getServerSettingByKeyAsync(ctx.db, input.settingsKey);
       await updateServerSettingByKeyAsync(ctx.db, input.settingsKey, {
         ...current,
         ...input.value,
-      } as ServerSettings[keyof ServerSettings]);
+      } as ServerSettings[typeof input.settingsKey]);
     }),
 });

packages/api/src/router/test/serverSettings.spec.ts

@@ -79,7 +79,7 @@ describe("saveSettings", () => {
     });
 
     const dbSettings = await db.select().from(serverSettings);
-    expect(dbSettings).toStrictEqual([
+    expect(dbSettings.filter(({ settingKey }) => settingKey === "analytics")).toStrictEqual([
       {
         settingKey: "analytics",
         value: stringify({
@@ -124,7 +124,7 @@ describe("board settings API", () => {
       forceDisableStatus: true,
     });
     const dbSettings = await db.select().from(serverSettings);
-    expect(dbSettings).toStrictEqual([
+    expect(dbSettings.filter(({ settingKey }) => settingKey === "board")).toStrictEqual([
       {
         settingKey: "board",
         value: stringify(result),
@@ -155,7 +155,7 @@ describe("board settings API", () => {
       enableStatusByDefault: false,
     });
     const dbSettings = await db.select().from(serverSettings);
-    expect(dbSettings).toStrictEqual([
+    expect(dbSettings.filter(({ settingKey }) => settingKey === "board")).toStrictEqual([
       {
         settingKey: "board",
         value: stringify(result),

packages/api/src/router/user.ts

@@ -15,8 +15,11 @@ import { selectUserSchema } from "@homarr/db/validationSchemas";
 import type { SupportedAuthProvider } from "@homarr/definitions";
 import { credentialsAdminGroup, supportedAuthProviders } from "@homarr/definitions";
 import { byIdSchema } from "@homarr/validation/common";
-import type { userBaseCreateSchema } from "@homarr/validation/user";
+import type { HeaderPreferences, userBaseCreateSchema } from "@homarr/validation/user";
 import {
+  getHeaderItems,
+  headerPreferencesMutationSchema,
+  parseHeaderPreferences,
   userChangeColorSchemeSchema,
   userChangeHomeBoardsSchema,
   userChangePasswordApiSchema,
@@ -30,6 +33,7 @@ import {
   userPingIconsEnabledSchema,
   userRegistrationApiSchema,
 } from "@homarr/validation/user";
+import { serializeHeaderPreferences } from "@homarr/validation/header-preferences";
 
 import { convertIntersectionToZodObject } from "../schema-merger";
 import {
@@ -40,6 +44,7 @@ import {
   protectedProcedure,
   publicProcedure,
 } from "../trpc";
+import { getAccessibleBoardIdsForUserAsync } from "./board";
 import { throwIfActionForbiddenAsync } from "./board/board-access";
 import { throwIfCredentialsDisabled } from "./invite/checks";
 import { changeSearchPreferencesAsync, changeSearchPreferencesInputSchema } from "./user/change-search-preferences";
@@ -368,6 +373,7 @@ export const userRouter = createTRPCRouter({
         firstDayOfWeek: true,
         pingIconsEnabled: true,
         enableRightClickOnWidgets: true,
+        headerPreferences: true,
         defaultSearchEngineId: true,
         openSearchInNewTab: true,
         ddgBangs: true,
@@ -405,6 +411,7 @@ export const userRouter = createTRPCRouter({
           firstDayOfWeek: true,
           pingIconsEnabled: true,
           enableRightClickOnWidgets: true,
+          headerPreferences: true,
           defaultSearchEngineId: true,
           openSearchInNewTab: true,
           ddgBangs: true,
@@ -719,6 +726,63 @@ export const userRouter = createTRPCRouter({
         })
         .where(eq(users.id, input.id));
     }),
+  changeHeaderPreferences: protectedProcedure
+    .meta({
+      openapi: {
+        method: "PATCH",
+        path: "/api/users/header-preferences",
+        tags: ["users"],
+        protect: true,
+      },
+      mcp: {
+        enabled: true,
+        description:
+          "Update the header layout preferences of a user. REQUIRED: id (user ID), headerPreferences (zones for left, center and right, visible flag, searchDisplay and logoDisplay). Admins can change any user; other users can only change their own. Board shortcut items must reference boards the target user can view",
+      },
+    })
+    .input(z.object({ id: z.string(), headerPreferences: headerPreferencesMutationSchema }))
+    .output(z.void())
+    .mutation(async ({ input, ctx }) => {
+      if (!ctx.session.user.permissions.includes("admin") && ctx.session.user.id !== input.id) {
+        throw new TRPCError({
+          code: "NOT_FOUND",
+          message: "User not found",
+        });
+      }
+
+      const targetUser = await ctx.db.query.users.findFirst({
+        columns: { headerPreferences: true },
+        where: eq(users.id, input.id),
+      });
+      if (!targetUser) {
+        throw new TRPCError({
+          code: "NOT_FOUND",
+          message: "User not found",
+        });
+      }
+
+      const submittedBoardIds = getBoardShortcutIds(input.headerPreferences);
+      if (submittedBoardIds.length > 0) {
+        const existingBoardIds = new Set(getBoardShortcutIds(parseHeaderPreferences(targetUser.headerPreferences)));
+        const accessibleBoardIds = await getAccessibleBoardIdsForUserAsync(ctx.db, input.id);
+        const hasUnavailableShortcut = submittedBoardIds.some(
+          (boardId) => !accessibleBoardIds.has(boardId) && !existingBoardIds.has(boardId),
+        );
+        if (hasUnavailableShortcut) {
+          throw new TRPCError({
+            code: "BAD_REQUEST",
+            message: "One or more board shortcuts are unavailable to this user",
+          });
+        }
+      }
+
+      await ctx.db
+        .update(users)
+        .set({
+          headerPreferences: serializeHeaderPreferences(input.headerPreferences),
+        })
+        .where(eq(users.id, input.id));
+    }),
   changeDdgBangs: protectedProcedure
     .input(convertIntersectionToZodObject(userDdgBangsSchema.and(byIdSchema)))
     .output(z.void())
@@ -829,6 +893,9 @@ export const userRouter = createTRPCRouter({
   }),
 });
 
+const getBoardShortcutIds = (preferences: HeaderPreferences) =>
+  getHeaderItems(preferences.zones).flatMap((item) => (item.type === "board" ? [item.boardId] : []));
+
 const createUserAsync = async (db: Database, input: Omit<z.infer<typeof userBaseCreateSchema>, "groupIds">) => {
   const hashedPassword = await hashPasswordAsync(input.password);
 

packages/api/src/test/mcp.spec.ts

@@ -65,6 +65,7 @@ const MCP_TOOL_ALLOWLIST = {
     "mediaServer_getCurrentStreams",
     "patchmon_getStats",
     "serverSettings_getBoardSettings",
+    "serverSettings_getBranding",
     "smartHome_entityDetails",
     "smartHome_entityState",
     "widgetSecrets_getConfiguredKinds",

packages/api/src/user-server.ts

@@ -13,6 +13,7 @@ export const getRscUserSettingsAsync = cache(async (userId: string) =>
       firstDayOfWeek: true,
       pingIconsEnabled: true,
       enableRightClickOnWidgets: true,
+      headerPreferences: true,
       defaultSearchEngineId: true,
       openSearchInNewTab: true,
       ddgBangs: true,