merge: stack widget modernization on dnd kit

2026-08-08 20:40:26 +02:00
commit 9edeba5cd2
@@ -572,6 +572,38 @@ describe("getBoardByName should return board by name", () => {
    expect(spy).toHaveBeenCalledWith(expect.anything(), expect.anything(), "view");
  });

+  it("returns configured container behavior", async () => {
+    const db = createDb();
+    const caller = boardRouter.createCaller({ db, deviceType: undefined, session: defaultSession });
+    const { boardId, sectionId: rootSectionId, layoutId } = await createFullBoardAsync(db, "default");
+    const sectionId = await addContainerAsync(db, {
+      boardId,
+      layoutId,
+      parentSectionId: rootSectionId,
+      options: {
+        title: "Media",
+        showLabel: false,
+        collapsible: true,
+        showOpenAll: true,
+      },
+    });
+
+    const result = await caller.getBoardByName({ name: "default" });
+    const section = expectToBeDefined(result.sections.find((candidate) => candidate.id === sectionId));
+
+    expect(result.id).toBe(boardId);
+    expect(section.kind).toBe("container");
+    if (section.kind === "container") {
+      expect(section.collapsed).toBe(false);
+      expect(section.options).toMatchObject({
+        title: "Media",
+        showLabel: false,
+        collapsible: true,
+        showOpenAll: true,
+      });
+    }
+  });
+
  it("should throw error when not present", async () => {
    // Arrange
    const db = createDb();
@@ -828,60 +860,194 @@ describe("saveBoard should save full board", () => {
    expect(integration).toBeUndefined();
    expect(spy).toHaveBeenCalledWith(expect.anything(), expect.anything(), "modify");
  });
-  it.each([[{ kind: "empty" as const }], [{ kind: "category" as const, collapsed: false, name: "My first category" }]])(
-    "should add section when present in input",
-    async (partialSection) => {
-      const spy = vi.spyOn(boardAccess, "throwIfActionForbiddenAsync");
-      const db = createDb();
-      const caller = boardRouter.createCaller({ db, deviceType: undefined, session: defaultSession });
+  it("should add root section when present in input", async () => {
+    const spy = vi.spyOn(boardAccess, "throwIfActionForbiddenAsync");
+    const db = createDb();
+    const caller = boardRouter.createCaller({ db, deviceType: undefined, session: defaultSession });

-      const { boardId, sectionId } = await createFullBoardAsync(db, "default");
+    const { boardId, sectionId } = await createFullBoardAsync(db, "default");

-      const newSectionId = createId();
-      await caller.saveBoard({
-        id: boardId,
-        sections: [
-          {
-            id: newSectionId,
-            xOffset: 0,
-            yOffset: 1,
-            ...partialSection,
-          },
-          {
-            id: sectionId,
-            kind: "empty",
-            xOffset: 0,
-            yOffset: 0,
-          },
-        ],
-        items: [],
-      });
-
-      const board = await db.query.boards.findFirst({
-        where: eq(boards.id, boardId),
-        with: {
-          sections: true,
+    const newSectionId = createId();
+    await caller.saveBoard({
+      id: boardId,
+      sections: [
+        {
+          id: newSectionId,
+          kind: "empty",
+          xOffset: 0,
+          yOffset: 1,
        },
-      });
+        {
+          id: sectionId,
+          kind: "empty",
+          xOffset: 0,
+          yOffset: 0,
+        },
+      ],
+      items: [],
+    });

-      const section = await db.query.sections.findFirst({
-        where: eq(sections.id, newSectionId),
-      });
+    const board = await db.query.boards.findFirst({
+      where: eq(boards.id, boardId),
+      with: {
+        sections: true,
+      },
+    });

-      const definedBoard = expectToBeDefined(board);
-      expect(definedBoard.sections.length).toBe(2);
-      const addedSection = expectToBeDefined(definedBoard.sections.find((section) => section.id === newSectionId));
-      expect(addedSection).toBeDefined();
-      expect(addedSection.id).toBe(newSectionId);
-      expect(addedSection.kind).toBe(partialSection.kind);
-      expect(addedSection.yOffset).toBe(1);
-      if ("name" in partialSection) {
-        expect(addedSection.name).toBe(partialSection.name);
-      }
-      expect(section).toBeDefined();
-      expect(spy).toHaveBeenCalledWith(expect.anything(), expect.anything(), "modify");
-    },
-  );
+    const section = await db.query.sections.findFirst({
+      where: eq(sections.id, newSectionId),
+    });
+
+    const definedBoard = expectToBeDefined(board);
+    expect(definedBoard.sections.length).toBe(2);
+    const addedSection = expectToBeDefined(definedBoard.sections.find((section) => section.id === newSectionId));
+    expect(addedSection).toBeDefined();
+    expect(addedSection.id).toBe(newSectionId);
+    expect(addedSection.kind).toBe("empty");
+    expect(addedSection.yOffset).toBe(1);
+    expect(addedSection.name).toBeNull();
+    expect(section).toBeDefined();
+    expect(spy).toHaveBeenCalledWith(expect.anything(), expect.anything(), "modify");
+  });
+  it("should add and update container behavior options", async () => {
+    const db = createDb();
+    const caller = boardRouter.createCaller({ db, deviceType: undefined, session: defaultSession });
+    const { boardId, layoutId, sectionId: rootSectionId } = await createFullBoardAsync(db, "default");
+    const containerId = createId();
+
+    await caller.saveBoard({
+      id: boardId,
+      sections: [
+        {
+          id: rootSectionId,
+          kind: "empty",
+          xOffset: 0,
+          yOffset: 0,
+        },
+        {
+          id: containerId,
+          kind: "container",
+          collapsed: false,
+          options: {
+            title: "Navigation",
+            customCssClasses: ["pinned"],
+            borderColor: "#123456",
+            showLabel: true,
+            collapsible: true,
+            showOpenAll: true,
+          },
+          layouts: [
+            {
+              layoutId,
+              parentSectionId: rootSectionId,
+              xOffset: 1,
+              yOffset: 2,
+              width: 3,
+              height: 4,
+            },
+          ],
+        },
+      ],
+      items: [],
+    });
+
+    await caller.saveBoard({
+      id: boardId,
+      sections: [
+        {
+          id: rootSectionId,
+          kind: "empty",
+          xOffset: 0,
+          yOffset: 0,
+        },
+        {
+          id: containerId,
+          kind: "container",
+          collapsed: false,
+          options: {
+            title: "Operations",
+            customCssClasses: ["dense"],
+            borderColor: "#654321",
+            showLabel: false,
+            collapsible: false,
+            showOpenAll: false,
+          },
+          layouts: [
+            {
+              layoutId,
+              parentSectionId: rootSectionId,
+              xOffset: 2,
+              yOffset: 3,
+              width: 4,
+              height: 5,
+            },
+          ],
+        },
+      ],
+      items: [],
+    });
+
+    const section = await db.query.sections.findFirst({
+      where: eq(sections.id, containerId),
+    });
+
+    expect(SuperJSON.parse(section?.options ?? "")).toEqual({
+      title: "Operations",
+      customCssClasses: ["dense"],
+      borderColor: "#654321",
+      showLabel: false,
+      collapsible: false,
+      showOpenAll: false,
+    });
+    expect(
+      await db.query.sectionLayouts.findFirst({
+        where: and(eq(sectionLayouts.sectionId, containerId), eq(sectionLayouts.layoutId, layoutId)),
+      }),
+    ).toMatchObject({
+      parentSectionId: rootSectionId,
+      xOffset: 2,
+      yOffset: 3,
+      width: 4,
+      height: 5,
+    });
+  });
+  it("should add a container without layouts", async () => {
+    const db = createDb();
+    const caller = boardRouter.createCaller({ db, deviceType: undefined, session: defaultSession });
+    const { boardId, sectionId: rootSectionId } = await createFullBoardAsync(db, "default");
+    const containerId = createId();
+
+    await caller.saveBoard({
+      id: boardId,
+      sections: [
+        {
+          id: rootSectionId,
+          kind: "empty",
+          xOffset: 0,
+          yOffset: 0,
+        },
+        {
+          id: containerId,
+          kind: "container",
+          collapsed: false,
+          options: {},
+          layouts: [],
+        },
+      ],
+      items: [],
+    });
+
+    expect(
+      await db.query.sections.findFirst({
+        where: eq(sections.id, containerId),
+      }),
+    ).toMatchObject({ id: containerId, kind: "container" });
+    expect(
+      await db.query.sectionLayouts.findMany({
+        where: eq(sectionLayouts.sectionId, containerId),
+      }),
+    ).toEqual([]);
+  });
  it("should add item when present in input", async () => {
    const spy = vi.spyOn(boardAccess, "throwIfActionForbiddenAsync");
    const db = createDb();
@@ -1027,15 +1193,22 @@ describe("saveBoard should save full board", () => {
    const db = createDb();
    const caller = boardRouter.createCaller({ db, deviceType: undefined, session: defaultSession });

-    const { boardId, sectionId } = await createFullBoardAsync(db, "default");
-    const newSectionId = createId();
+    const { boardId, sectionId, layoutId } = await createFullBoardAsync(db, "default");
+    const containerId = createId();
    await db.insert(sections).values({
-      id: newSectionId,
-      kind: "category",
-      name: "Before",
-      yOffset: 1,
-      xOffset: 0,
+      id: containerId,
+      kind: "container",
      boardId,
+      options: SuperJSON.stringify({ title: "Before" }),
+    });
+    await db.insert(sectionLayouts).values({
+      sectionId: containerId,
+      layoutId,
+      parentSectionId: sectionId,
+      xOffset: 0,
+      yOffset: 0,
+      width: 2,
+      height: 2,
    });

    await caller.saveBoard({
@@ -1043,19 +1216,32 @@ describe("saveBoard should save full board", () => {
      sections: [
        {
          id: sectionId,
-          kind: "category",
+          kind: "empty",
          yOffset: 1,
          xOffset: 0,
-          name: "Test",
-          collapsed: true,
        },
        {
-          id: newSectionId,
-          kind: "category",
-          name: "After",
-          yOffset: 0,
-          xOffset: 0,
+          id: containerId,
+          kind: "container",
          collapsed: false,
+          options: {
+            title: "After",
+            customCssClasses: ["dense"],
+            borderColor: "#123456",
+            showLabel: false,
+            collapsible: true,
+            showOpenAll: true,
+          },
+          layouts: [
+            {
+              layoutId,
+              parentSectionId: sectionId,
+              xOffset: 1,
+              yOffset: 2,
+              width: 3,
+              height: 4,
+            },
+          ],
        },
      ],
      items: [],
@@ -1075,11 +1261,17 @@ describe("saveBoard should save full board", () => {
    expect(firstSection.kind).toBe("empty");
    expect(firstSection.yOffset).toBe(1);
    expect(firstSection.name).toBe(null);
-    const secondSection = expectToBeDefined(definedBoard.sections.find((section) => section.id === newSectionId));
-    expect(secondSection.id).toBe(newSectionId);
-    expect(secondSection.kind).toBe("category");
-    expect(secondSection.yOffset).toBe(0);
-    expect(secondSection.name).toBe("After");
+    const secondSection = expectToBeDefined(definedBoard.sections.find((section) => section.id === containerId));
+    expect(secondSection.id).toBe(containerId);
+    expect(secondSection.kind).toBe("container");
+    expect(secondSection.yOffset).toBeNull();
+    expect(secondSection.name).toBeNull();
+    expect(SuperJSON.parse(secondSection.options ?? "")).toMatchObject({ title: "After", collapsible: true });
+    expect(
+      await db.query.sectionLayouts.findFirst({
+        where: and(eq(sectionLayouts.sectionId, containerId), eq(sectionLayouts.layoutId, layoutId)),
+      }),
+    ).toMatchObject({ xOffset: 1, yOffset: 2, width: 3, height: 4, parentSectionId: sectionId });
  });
  it("should update item when present in input", async () => {
    const spy = vi.spyOn(boardAccess, "throwIfActionForbiddenAsync");
@@ -1328,12 +1520,16 @@ const createExistingLayout = (id: string) => ({
  id,
  name: "Base",
  columnCount: 10,
+  leftGutterColumnCount: 0,
+  rightGutterColumnCount: 0,
  breakpoint: 0,
 });
 const createNewLayout = (columnCount: number) => ({
  id: createId(),
  name: "New layout",
  columnCount,
+  leftGutterColumnCount: 0,
+  rightGutterColumnCount: 0,
  breakpoint: 1400,
 });
 describe("saveLayouts should save layout changes", () => {
@@ -1361,7 +1557,7 @@ describe("saveLayouts should save layout changes", () => {
    expect(definedLayout.columnCount).toBe(newLayout.columnCount);
    expect(definedLayout.breakpoint).toBe(newLayout.breakpoint);
  });
-  test("should add items and dynamic sections generated from grid-algorithm when new layout is added", async () => {
+  test("should add items and containers generated from grid-algorithm when new layout is added", async () => {
    // Arrange
    const db = createDb();
    const caller = boardRouter.createCaller({ db, deviceType: undefined, session: defaultSession });
@@ -1390,7 +1586,7 @@ describe("saveLayouts should save layout changes", () => {
      a: itemId,
    });
    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    await expectLayoutForDynamicSectionAsync(db, assignments.inRoot.f, layout!.id, assignments.inDynamicSection);
+    await expectLayoutForContainerAsync(db, assignments.inRoot.f, layout!.id, assignments.inContainer);
  });
  test("should update layout when present in input", async () => {
    // Arrange
@@ -1443,7 +1639,81 @@ describe("saveLayouts should save layout changes", () => {
      ...assignments.inRoot,
      a: itemId,
    });
-    await expectLayoutForDynamicSectionAsync(db, assignments.inRoot.f, layoutId, assignments.inDynamicSection);
+    await expectLayoutForContainerAsync(db, assignments.inRoot.f, layoutId, assignments.inContainer);
+  });
+  test("should reserve gutter columns and return gutter contents to the canvas when disabled", async () => {
+    const db = createDb();
+    const caller = boardRouter.createCaller({ db, deviceType: undefined, session: defaultSession });
+    const { boardId, layoutId, sectionId, itemId } = await createFullBoardAsync(db, "gutters");
+
+    await db
+      .update(itemLayouts)
+      .set({
+        xOffset: 9,
+      })
+      .where(and(eq(itemLayouts.itemId, itemId), eq(itemLayouts.layoutId, layoutId)));
+
+    await caller.saveLayouts({
+      id: boardId,
+      layouts: [
+        {
+          ...createExistingLayout(layoutId),
+          leftGutterColumnCount: 2,
+        },
+      ],
+    });
+
+    const enabledLayout = expectToBeDefined(await db.query.layouts.findFirst({ where: eq(layouts.id, layoutId) }));
+    expect(enabledLayout.leftGutterColumnCount).toBe(2);
+    const leftRoot = expectToBeDefined(
+      await db.query.sections.findFirst({
+        where: and(eq(sections.boardId, boardId), eq(sections.kind, "empty"), eq(sections.xOffset, -1)),
+      }),
+    );
+    const reflowedMainItem = expectToBeDefined(
+      await db.query.itemLayouts.findFirst({
+        where: and(eq(itemLayouts.itemId, itemId), eq(itemLayouts.layoutId, layoutId)),
+      }),
+    );
+    expect(reflowedMainItem.xOffset + reflowedMainItem.width).toBeLessThanOrEqual(8);
+
+    const gutterItemId = await addItemAsync(db, {
+      boardId,
+      layoutId,
+      sectionId: leftRoot.id,
+    });
+    await caller.saveLayouts({
+      id: boardId,
+      layouts: [createExistingLayout(layoutId)],
+    });
+
+    const returnedItem = expectToBeDefined(
+      await db.query.itemLayouts.findFirst({
+        where: and(eq(itemLayouts.itemId, gutterItemId), eq(itemLayouts.layoutId, layoutId)),
+      }),
+    );
+    expect(returnedItem.sectionId).toBe(sectionId);
+  });
+  test("should create one gutter root when layouts are saved concurrently", async () => {
+    const db = createDb();
+    const caller = boardRouter.createCaller({ db, deviceType: undefined, session: defaultSession });
+    const { boardId, layoutId } = await createFullBoardAsync(db, "concurrent-gutters");
+    const input = {
+      id: boardId,
+      layouts: [
+        {
+          ...createExistingLayout(layoutId),
+          leftGutterColumnCount: 2,
+        },
+      ],
+    };
+
+    await Promise.all([caller.saveLayouts(input), caller.saveLayouts(input)]);
+
+    const leftRoots = await db.query.sections.findMany({
+      where: and(eq(sections.boardId, boardId), eq(sections.kind, "empty"), eq(sections.xOffset, -1)),
+    });
+    expect(leftRoots).toHaveLength(1);
  });
  test("should remove layout when not present in input", async () => {
    // Arrange
@@ -1483,6 +1753,63 @@ describe("saveLayouts should save layout changes", () => {
  });
 });

+describe("Custom Widget placement permissions", () => {
+  test("rejects a direct addItem request from a non-admin board modifier", async () => {
+    const db = createDb();
+    const caller = boardRouter.createCaller({ db, deviceType: undefined, session: defaultSession });
+    const { boardId } = await createFullBoardAsync(db, "custom-widget-add");
+
+    await expect(
+      caller.addItem({
+        boardId,
+        kind: "customApi",
+        options: {
+          definitionId: "definition-1",
+          refreshInterval: 30,
+          configuration: {},
+        },
+        integrationIds: [],
+      }),
+    ).rejects.toMatchObject({ code: "FORBIDDEN" });
+  });
+
+  test("rejects a direct saveBoard request that adds a Custom Widget for a non-admin", async () => {
+    const db = createDb();
+    const caller = boardRouter.createCaller({ db, deviceType: undefined, session: defaultSession });
+    const { boardId, sectionId, layoutId } = await createFullBoardAsync(db, "custom-widget-save");
+
+    await expect(
+      caller.saveBoard({
+        id: boardId,
+        sections: [{ id: sectionId, kind: "empty", yOffset: 0, xOffset: 0 }],
+        items: [
+          {
+            id: createId(),
+            kind: "customApi",
+            options: {
+              definitionId: "definition-1",
+              refreshInterval: 30,
+              configuration: {},
+            },
+            integrationIds: [],
+            advancedOptions: { title: null, customCssClasses: [], borderColor: "" },
+            layouts: [
+              {
+                layoutId,
+                sectionId,
+                height: 1,
+                width: 1,
+                xOffset: 0,
+                yOffset: 0,
+              },
+            ],
+          },
+        ],
+      }),
+    ).rejects.toMatchObject({ code: "FORBIDDEN" });
+  });
+});
+
 const expectInputToBeFullBoardWithName = (
  input: RouterOutputs["board"]["getHomeBoard"],
  props: { name: string } & Awaited<ReturnType<typeof createFullBoardAsync>>,
@@ -1601,19 +1928,21 @@ const addItemAsync = async (
  return itemId;
 };

-const addDynamicSectionAsync = async (
+const addContainerAsync = async (
  db: Database,
  section: Partial<Pick<InferInsertModel<typeof sectionLayouts>, "xOffset" | "yOffset" | "width" | "height">> & {
    parentSectionId: string;
    boardId: string;
    layoutId: string;
+    options?: Record<string, unknown>;
  },
 ) => {
  const sectionId = createId();
  await db.insert(sections).values({
    id: sectionId,
-    kind: "dynamic",
+    kind: "container",
    boardId: section.boardId,
+    options: SuperJSON.stringify(section.options ?? {}),
  });
  await db.insert(sectionLayouts).values({
    parentSectionId: section.parentSectionId,
@@ -1655,7 +1984,7 @@ const createItemsAndSectionsAsync = async (
  const itemC = await addItemAsync(db, { boardId, layoutId, sectionId, xOffset: 6, width: 2, height: 2 });
  const itemD = await addItemAsync(db, { boardId, layoutId, sectionId, xOffset: 8, width: 2, height: 3 });
  const itemE = await addItemAsync(db, { boardId, layoutId, sectionId, yOffset: 1, height: 3 });
-  const sectionF = await addDynamicSectionAsync(db, {
+  const sectionF = await addContainerAsync(db, {
    yOffset: 1,
    xOffset: 1,
    width: 5,
@@ -1664,7 +1993,7 @@ const createItemsAndSectionsAsync = async (
    boardId,
    layoutId,
  });
-  const sectionG = await addDynamicSectionAsync(db, {
+  const sectionG = await addContainerAsync(db, {
    yOffset: 2,
    xOffset: 6,
    width: 2,
@@ -1695,7 +2024,7 @@ const createItemsAndSectionsAsync = async (
      f: sectionF,
      g: sectionG,
    },
-    inDynamicSection: {
+    inContainer: {
      h: itemH,
      i: itemI,
      j: itemJ,
@@ -1731,7 +2060,7 @@ gg`,
  );
 };

-const expectLayoutForDynamicSectionAsync = async (
+const expectLayoutForContainerAsync = async (
  db: Database,
  sectionId: string,
  layoutId: string,
@@ -1,376 +0,0 @@
-// @vitest-environment node
-
-import { stringify } from "superjson";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-
-import type { Session } from "@homarr/auth";
-import { createId } from "@homarr/common";
-import type { Database } from "@homarr/db";
-import { eq } from "@homarr/db";
-import { boards, boardUserPermissions, customWidgetDefinitions, items, users } from "@homarr/db/schema";
-import { createDb } from "@homarr/db/test";
-import type { GroupPermissionKey } from "@homarr/definitions";
-
-import { customWidgetRouter } from "../custom-widget/custom-widget-router";
-import { customApiRouter } from "../widgets/custom-api";
-
-const createSession = (userId: string, permissions: GroupPermissionKey[] = []): Session => ({
-  user: { id: userId, permissions, colorScheme: "light" },
-  expires: new Date().toISOString(),
-});
-
-const createCustomWidgetCaller = (db: Database, session: Session | null) =>
-  customWidgetRouter.createCaller({ db, deviceType: undefined, session });
-
-const createCustomApiCaller = (db: Database, session: Session | null) =>
-  customApiRouter.createCaller({ db, deviceType: undefined, session });
-
-async function createFixtureAsync(db: Database) {
-  const ownerId = createId();
-  const viewerId = createId();
-  const modifierId = createId();
-  const unrelatedId = createId();
-  const adminId = createId();
-  const boardId = createId();
-  const itemId = createId();
-  const definitionId = createId();
-
-  await db.insert(users).values(
-    [ownerId, viewerId, modifierId, unrelatedId, adminId].map((id) => ({
-      id,
-      name: id,
-    })),
-  );
-  await db.insert(boards).values({ id: boardId, name: `board-${boardId}`, creatorId: ownerId, isPublic: false });
-  await db.insert(boardUserPermissions).values([
-    { boardId, userId: viewerId, permission: "view" },
-    { boardId, userId: modifierId, permission: "modify" },
-  ]);
-  await db.insert(customWidgetDefinitions).values({
-    id: definitionId,
-    name: "Restart service",
-    description: "Restarts a service",
-    url: "https://api.example.com/restart",
-    method: "POST",
-    displayType: "actionButton",
-    displayConfig: stringify({
-      type: "actionButton",
-      buttonLabel: "Restart",
-      confirmText: "Continue?",
-    }),
-    creatorId: adminId,
-  });
-  await db.insert(items).values({
-    id: itemId,
-    boardId,
-    kind: "customApi",
-    options: stringify({ definitionId, refreshInterval: 30 }),
-  });
-
-  return { ownerId, viewerId, modifierId, unrelatedId, adminId, boardId, itemId, definitionId };
-}
-
-beforeEach(() => {
-  vi.restoreAllMocks();
-  vi.useRealTimers();
-});
-
-afterEach(() => {
-  vi.unstubAllGlobals();
-  vi.useRealTimers();
-});
-
-describe("custom widget definition authorization", () => {
-  it("restricts the full definition list to administrators", async () => {
-    const db = createDb();
-    const fixture = await createFixtureAsync(db);
-
-    await expect(createCustomWidgetCaller(db, null).all()).rejects.toMatchObject({ code: "UNAUTHORIZED" });
-    for (const userId of [fixture.ownerId, fixture.viewerId, fixture.modifierId, fixture.unrelatedId]) {
-      await expect(createCustomWidgetCaller(db, createSession(userId)).all()).rejects.toMatchObject({
-        code: "FORBIDDEN",
-      });
-    }
-
-    await expect(createCustomWidgetCaller(db, createSession(fixture.adminId, ["admin"])).all()).resolves.toEqual([
-      expect.objectContaining({ id: fixture.definitionId, url: "https://api.example.com/restart" }),
-    ]);
-  });
-
-  it("returns only safe definition summaries to board modifiers", async () => {
-    const db = createDb();
-    const fixture = await createFixtureAsync(db);
-
-    const result = await createCustomWidgetCaller(db, createSession(fixture.modifierId)).available({
-      boardId: fixture.boardId,
-    });
-    expect(result).toEqual([
-      {
-        id: fixture.definitionId,
-        name: "Restart service",
-        description: "Restarts a service",
-        iconUrl: null,
-        displayType: "actionButton",
-        enabled: true,
-      },
-    ]);
-    expect(JSON.stringify(result)).not.toContain("api.example.com");
-
-    for (const userId of [fixture.viewerId, fixture.unrelatedId]) {
-      await expect(
-        createCustomWidgetCaller(db, createSession(userId)).available({ boardId: fixture.boardId }),
-      ).rejects.toMatchObject({ code: "NOT_FOUND" });
-    }
-  });
-});
-
-describe("custom widget action authorization", () => {
-  it("requires an administrator even for users who can view or modify the board", async () => {
-    const db = createDb();
-    const fixture = await createFixtureAsync(db);
-    const input = {
-      boardId: fixture.boardId,
-      itemId: fixture.itemId,
-      definitionId: fixture.definitionId,
-    };
-
-    await expect(createCustomWidgetCaller(db, null).execute(input)).rejects.toMatchObject({ code: "UNAUTHORIZED" });
-    for (const userId of [fixture.ownerId, fixture.viewerId, fixture.modifierId, fixture.unrelatedId]) {
-      await expect(createCustomWidgetCaller(db, createSession(userId)).execute(input)).rejects.toMatchObject({
-        code: "FORBIDDEN",
-      });
-    }
-  });
-
-  it("executes for an administrator only when board, item, and definition are bound", async () => {
-    const db = createDb();
-    const fixture = await createFixtureAsync(db);
-    const fetchMock = vi.fn().mockResolvedValue(new Response(null, { status: 204 }));
-    vi.stubGlobal("fetch", fetchMock);
-    const caller = createCustomWidgetCaller(db, createSession(fixture.adminId, ["admin"]));
-
-    await expect(
-      caller.execute({
-        boardId: fixture.boardId,
-        itemId: fixture.itemId,
-        definitionId: fixture.definitionId,
-      }),
-    ).resolves.toEqual({ success: true, responseInfo: { status: 204 } });
-    expect(fetchMock).toHaveBeenCalledWith(
-      "https://api.example.com/restart",
-      expect.objectContaining({ method: "POST", redirect: "error", signal: expect.any(AbortSignal) }),
-    );
-  });
-
-  it.each(["board", "item", "definition"] as const)("rejects a mismatched %s binding", async (mismatch) => {
-    const db = createDb();
-    const fixture = await createFixtureAsync(db);
-    const fetchMock = vi.fn();
-    vi.stubGlobal("fetch", fetchMock);
-    const input = {
-      boardId: mismatch === "board" ? createId() : fixture.boardId,
-      itemId: mismatch === "item" ? createId() : fixture.itemId,
-      definitionId: mismatch === "definition" ? createId() : fixture.definitionId,
-    };
-
-    await expect(
-      createCustomWidgetCaller(db, createSession(fixture.adminId, ["admin"])).execute(input),
-    ).rejects.toMatchObject({ code: "NOT_FOUND" });
-    expect(fetchMock).not.toHaveBeenCalled();
-  });
-
-  it("rejects disabled definitions before sending a request", async () => {
-    const db = createDb();
-    const fixture = await createFixtureAsync(db);
-    await db
-      .update(customWidgetDefinitions)
-      .set({ enabled: false })
-      .where(eq(customWidgetDefinitions.id, fixture.definitionId));
-    const fetchMock = vi.fn();
-    vi.stubGlobal("fetch", fetchMock);
-
-    await expect(
-      createCustomWidgetCaller(db, createSession(fixture.adminId, ["admin"])).execute({
-        boardId: fixture.boardId,
-        itemId: fixture.itemId,
-        definitionId: fixture.definitionId,
-      }),
-    ).rejects.toMatchObject({ code: "FORBIDDEN" });
-    expect(fetchMock).not.toHaveBeenCalled();
-  });
-});
-
-describe("custom API outbound request hardening", () => {
-  it("rejects credential-bearing action URLs without exposing the credential", async () => {
-    const db = createDb();
-    const fixture = await createFixtureAsync(db);
-    await db
-      .update(customWidgetDefinitions)
-      .set({ url: "https://operator:super-secret@private.example.com/restart" })
-      .where(eq(customWidgetDefinitions.id, fixture.definitionId));
-    const fetchMock = vi.fn();
-    vi.stubGlobal("fetch", fetchMock);
-
-    const result = await createCustomWidgetCaller(db, createSession(fixture.adminId, ["admin"])).execute({
-      boardId: fixture.boardId,
-      itemId: fixture.itemId,
-      definitionId: fixture.definitionId,
-    });
-    expect(result).toEqual({ success: false, errorCode: "REQUEST_FAILED", responseInfo: null });
-    expect(JSON.stringify(result)).not.toMatch(/super-secret|private\.example\.com/);
-    expect(fetchMock).not.toHaveBeenCalled();
-  });
-
-  it("rejects redirects and redacts fetch errors", async () => {
-    const db = createDb();
-    const fixture = await createFixtureAsync(db);
-    const fetchMock = vi
-      .fn()
-      .mockRejectedValue(
-        new TypeError("Redirect to http://token:secret@internal.example.local/admin?apiKey=top-secret was rejected"),
-      );
-    vi.stubGlobal("fetch", fetchMock);
-
-    const result = await createCustomWidgetCaller(db, createSession(fixture.adminId, ["admin"])).execute({
-      boardId: fixture.boardId,
-      itemId: fixture.itemId,
-      definitionId: fixture.definitionId,
-    });
-    expect(fetchMock).toHaveBeenCalledWith(
-      "https://api.example.com/restart",
-      expect.objectContaining({ redirect: "error" }),
-    );
-    expect(result).toEqual({ success: false, errorCode: "REQUEST_FAILED", responseInfo: null });
-    expect(JSON.stringify(result)).not.toMatch(/top-secret|internal\.example\.local|apiKey/);
-  });
-
-  it("aborts timed-out action requests and returns a stable failure", async () => {
-    vi.useFakeTimers();
-    const db = createDb();
-    const fixture = await createFixtureAsync(db);
-    const started = Promise.withResolvers<void>();
-    const fetchMock = vi.fn((_url: string, init: RequestInit) => {
-      started.resolve();
-      return new Promise<Response>((_resolve, reject) => {
-        init.signal?.addEventListener("abort", () => {
-          reject(new Error("Timed out calling http://internal.example.local?secret=timeout-secret"));
-        });
-      });
-    });
-    vi.stubGlobal("fetch", fetchMock);
-
-    const request = createCustomWidgetCaller(db, createSession(fixture.adminId, ["admin"])).execute({
-      boardId: fixture.boardId,
-      itemId: fixture.itemId,
-      definitionId: fixture.definitionId,
-    });
-    await started.promise;
-    await vi.advanceTimersByTimeAsync(10_000);
-
-    const result = await request;
-    expect(result).toEqual({ success: false, errorCode: "REQUEST_FAILED", responseInfo: null });
-    expect(JSON.stringify(result)).not.toMatch(/timeout-secret|internal\.example\.local/);
-  });
-
-  it("bounds action responses before reporting success", async () => {
-    const db = createDb();
-    const fixture = await createFixtureAsync(db);
-    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(new Response("x".repeat(2 * 1024 * 1024 + 1))));
-
-    await expect(
-      createCustomWidgetCaller(db, createSession(fixture.adminId, ["admin"])).execute({
-        boardId: fixture.boardId,
-        itemId: fixture.itemId,
-        definitionId: fixture.definitionId,
-      }),
-    ).resolves.toEqual({ success: false, errorCode: "REQUEST_FAILED", responseInfo: null });
-  });
-
-  it("binds data requests to a viewable item and never exposes backend error text", async () => {
-    const db = createDb();
-    const fixture = await createFixtureAsync(db);
-    await db
-      .update(customWidgetDefinitions)
-      .set({
-        displayType: "singleValue",
-        method: "GET",
-        displayConfig: stringify({ type: "singleValue", jsonPath: "$.value" }),
-      })
-      .where(eq(customWidgetDefinitions.id, fixture.definitionId));
-    vi.stubGlobal(
-      "fetch",
-      vi.fn().mockRejectedValue(new Error("Backend http://private.example.local/path?token=super-secret\nstack trace")),
-    );
-
-    const input = {
-      boardId: fixture.boardId,
-      itemId: fixture.itemId,
-      definitionId: fixture.definitionId,
-    };
-    const error = await createCustomApiCaller(db, createSession(fixture.viewerId))
-      .getData(input)
-      .catch((caught: unknown) => caught);
-    expect(error).toMatchObject({ code: "INTERNAL_SERVER_ERROR", message: "Custom API request failed" });
-    expect(JSON.stringify(error)).not.toMatch(/super-secret|private\.example\.local|stack trace/);
-
-    await expect(createCustomApiCaller(db, createSession(fixture.unrelatedId)).getData(input)).rejects.toMatchObject({
-      code: "NOT_FOUND",
-    });
-    await expect(
-      createCustomApiCaller(db, createSession(fixture.viewerId)).getData({ ...input, definitionId: createId() }),
-    ).rejects.toMatchObject({ code: "NOT_FOUND" });
-  });
-
-  it("bounds and disposes non-success data responses", async () => {
-    const db = createDb();
-    const fixture = await createFixtureAsync(db);
-    await db
-      .update(customWidgetDefinitions)
-      .set({
-        displayType: "singleValue",
-        method: "GET",
-        displayConfig: stringify({ type: "singleValue", jsonPath: "$.value" }),
-      })
-      .where(eq(customWidgetDefinitions.id, fixture.definitionId));
-    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(new Response("x".repeat(2 * 1024 * 1024 + 1), { status: 502 })));
-
-    const error = await createCustomApiCaller(db, createSession(fixture.viewerId))
-      .getData({
-        boardId: fixture.boardId,
-        itemId: fixture.itemId,
-        definitionId: fixture.definitionId,
-      })
-      .catch((caught: unknown) => caught);
-
-    expect(error).toMatchObject({ code: "INTERNAL_SERVER_ERROR", message: "Custom API request failed" });
-    expect(JSON.stringify(error)).not.toContain("x".repeat(100));
-  });
-
-  it("redacts unsafe preview failures and rejects redirects", async () => {
-    const db = createDb();
-    const fixture = await createFixtureAsync(db);
-    const fetchMock = vi.fn().mockRejectedValue(new Error("redirected to http://private.local?secret=value"));
-    vi.stubGlobal("fetch", fetchMock);
-    const caller = createCustomWidgetCaller(db, createSession(fixture.adminId, ["admin"]));
-
-    const result = await caller.preview({
-      url: "https://api.example.com/data",
-      method: "GET",
-      authType: "none",
-      displayType: "singleValue",
-      displayConfig: { type: "singleValue", jsonPath: "$.value", label: "Value", unit: "" },
-      secrets: [],
-    });
-    expect(fetchMock).toHaveBeenCalledWith(
-      "https://api.example.com/data",
-      expect.objectContaining({ redirect: "error" }),
-    );
-    expect(result).toEqual({
-      success: false,
-      error: "Custom API preview failed",
-      responseInfo: null,
-      rawResponse: null,
-    });
-    expect(JSON.stringify(result)).not.toMatch(/private\.local|secret=value/);
-  });
-});
@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  claimCustomWidgetConfigurationRequest,
+  completeCustomWidgetConfigurationRequest,
+  createCustomWidgetConfigurationRequest,
+  getCustomWidgetConfigurationRequestForUser,
+  releaseCustomWidgetConfigurationRequest,
+} from "../../custom-widget/configuration-requests";
+
+describe("custom widget source configuration requests", () => {
+  it("is user-scoped, one-time, and reports completion without returning configuration", async () => {
+    const request = await createCustomWidgetConfigurationRequest({
+      userId: "user-1",
+      target: { type: "preview", id: "preview-1" },
+      widgetName: "Printer",
+      sourceId: "default",
+      sourceName: "Printer API",
+      source: { baseUrl: "http://printer.local", networkScope: "private", auth: "bearer" },
+      kinds: ["apiKey"],
+    });
+
+    expect(await getCustomWidgetConfigurationRequestForUser(request.id, "user-2")).toBeNull();
+    expect(await claimCustomWidgetConfigurationRequest(request.id)).toMatchObject({ status: "pending" });
+    expect(await claimCustomWidgetConfigurationRequest(request.id)).toBeNull();
+    await releaseCustomWidgetConfigurationRequest(request.id);
+    expect(await claimCustomWidgetConfigurationRequest(request.id)).not.toBeNull();
+    await completeCustomWidgetConfigurationRequest(request.id);
+    expect(await getCustomWidgetConfigurationRequestForUser(request.id, "user-1")).toMatchObject({
+      status: "completed",
+    });
+    expect(await claimCustomWidgetConfigurationRequest(request.id)).toBeNull();
+  });
+});
@@ -0,0 +1,551 @@
+import type { Session } from "@homarr/auth";
+import { createId } from "@homarr/common";
+import { eq, sql } from "@homarr/db";
+import {
+  customWidgetDefinitions,
+  customWidgetSecrets,
+  legacyCustomWidgetDefinitions,
+  legacyCustomWidgetSecrets,
+  users,
+} from "@homarr/db/schema";
+import { createDb } from "@homarr/db/test";
+import { BUNDLED_CUSTOM_WIDGETS, customWidgetDefinitionSchema } from "@homarr/custom-widgets/core";
+import { describe, expect, test } from "vitest";
+
+import { customWidgetRouter } from "../../custom-widget/custom-widget-router";
+import { getCustomWidgetConfigurationRequestForUser } from "../../custom-widget/configuration-requests";
+import { configureCustomWidgetSourceFromRequest } from "../../custom-widget/secret-persistence";
+import { serializeCustomWidgetDefinition } from "../../custom-widget/stored-definition";
+
+const userId = createId();
+const session = {
+  user: {
+    id: userId,
+    permissions: ["admin"],
+    colorScheme: "light",
+  },
+  expires: new Date().toISOString(),
+} satisfies Session;
+const nonAdminSession = {
+  ...session,
+  user: { ...session.user, permissions: ["board-modify-all"] },
+} satisfies Session;
+
+const jellyfin = BUNDLED_CUSTOM_WIDGETS.find(({ id }) => id === "seed-jellyfin")?.widget;
+if (!jellyfin) throw new Error("Jellyfin bundled widget is missing");
+const jellyfinDefaultSource = jellyfin.sources.default;
+if (!jellyfinDefaultSource) throw new Error("Jellyfin default source is missing");
+
+function createCaller(db: ReturnType<typeof createDb>) {
+  return customWidgetRouter.createCaller({ db, deviceType: undefined, session });
+}
+
+function createNonAdminCaller(db: ReturnType<typeof createDb>) {
+  return customWidgetRouter.createCaller({
+    db,
+    deviceType: undefined,
+    session: nonAdminSession,
+  });
+}
+
+async function prepareDatabase() {
+  const db = createDb();
+  await db.insert(users).values({ id: userId });
+  return db;
+}
+
+function rejectSecretInserts(db: ReturnType<typeof createDb>) {
+  db.run(
+    sql.raw(`CREATE TRIGGER reject_custom_widget_v2_secret_insert
+      BEFORE INSERT ON custom_widget_v2_secret
+      BEGIN
+        SELECT RAISE(ABORT, 'forced secret insert failure');
+      END`),
+  );
+}
+
+function rejectDefinitionUpdates(db: ReturnType<typeof createDb>) {
+  db.run(
+    sql.raw(`CREATE TRIGGER reject_custom_widget_v2_definition_update
+      BEFORE UPDATE ON custom_widget_v2_definition
+      BEGIN
+        SELECT RAISE(ABORT, 'forced definition update failure');
+      END`),
+  );
+}
+
+async function insertLegacyJellyfin(db: ReturnType<typeof createDb>) {
+  const id = "legacy-jellyfin";
+  const encryptedValue = "preserved.secret" as `${string}.${string}`;
+  await db.insert(legacyCustomWidgetDefinitions).values({
+    id,
+    name: "Legacy Jellyfin",
+    url: "http://jellyfin.local/Items/Counts",
+    authType: "apiKeyHeader",
+    headerName: "X-Emby-Token",
+    method: "GET",
+    displayType: "singleValue",
+    enabled: false,
+    creatorId: userId,
+  });
+  await db.insert(legacyCustomWidgetSecrets).values({
+    definitionId: id,
+    kind: "apiKey",
+    encryptedValue,
+    updatedAt: new Date(0),
+  });
+  return { id, encryptedValue };
+}
+
+const secret = { sourceId: "default", kind: "apiKey" as const, value: "test-secret" };
+
+describe("custom widget definition persistence", () => {
+  test("atomically creates a v2 replacement while preserving the legacy widget and its stable ID", async () => {
+    const db = await prepareDatabase();
+    const legacy = await insertLegacyJellyfin(db);
+
+    await createCaller(db).migrateLegacy({ id: legacy.id, widget: jellyfin, secrets: [] });
+
+    expect(await db.query.legacyCustomWidgetDefinitions.findFirst()).toMatchObject({
+      id: legacy.id,
+      name: "Legacy Jellyfin",
+      enabled: false,
+    });
+    expect(await db.query.legacyCustomWidgetSecrets.findFirst()).toMatchObject({
+      definitionId: legacy.id,
+      encryptedValue: legacy.encryptedValue,
+    });
+    expect(await db.query.customWidgetDefinitions.findFirst()).toMatchObject({
+      id: legacy.id,
+      enabled: false,
+      creatorId: userId,
+    });
+    expect(await db.query.customWidgetSecrets.findFirst()).toMatchObject({
+      definitionId: legacy.id,
+      sourceId: "default",
+      kind: "apiKey",
+      encryptedValue: legacy.encryptedValue,
+    });
+
+    const migratedList = await createCaller(db).list();
+    expect(migratedList).toHaveLength(1);
+    expect(migratedList[0]).toMatchObject({ id: legacy.id, migrationRequired: false });
+
+    await createCaller(db).delete({ id: legacy.id });
+
+    const fallbackList = await createCaller(db).list();
+    expect(fallbackList).toHaveLength(1);
+    expect(fallbackList[0]).toMatchObject({ id: legacy.id, migrationRequired: true });
+    expect(await db.query.legacyCustomWidgetSecrets.findFirst()).toMatchObject({
+      definitionId: legacy.id,
+      encryptedValue: legacy.encryptedValue,
+    });
+  });
+
+  test("keeps the legacy widget recoverable when confirmed replacement fails", async () => {
+    const db = await prepareDatabase();
+    const legacy = await insertLegacyJellyfin(db);
+    rejectSecretInserts(db);
+
+    await expect(createCaller(db).migrateLegacy({ id: legacy.id, widget: jellyfin, secrets: [] })).rejects.toThrow(
+      "forced secret insert failure",
+    );
+
+    expect(await db.query.legacyCustomWidgetDefinitions.findFirst()).toMatchObject({ id: legacy.id });
+    expect(await db.query.legacyCustomWidgetSecrets.findFirst()).toMatchObject({
+      definitionId: legacy.id,
+      encryptedValue: legacy.encryptedValue,
+    });
+    expect(await db.query.customWidgetDefinitions.findMany()).toHaveLength(0);
+  });
+
+  test("rolls back create when its secret cannot be stored", async () => {
+    const db = await prepareDatabase();
+    const caller = createCaller(db);
+    rejectSecretInserts(db);
+
+    await expect(caller.create({ ...jellyfin, secrets: [secret] })).rejects.toThrow("forced secret insert failure");
+
+    expect(await db.query.customWidgetDefinitions.findMany()).toHaveLength(0);
+    expect(await db.query.customWidgetSecrets.findMany()).toHaveLength(0);
+  });
+
+  test("rolls back import when its secret cannot be stored", async () => {
+    const db = await prepareDatabase();
+    const caller = createCaller(db);
+    rejectSecretInserts(db);
+
+    await expect(caller.import({ widget: jellyfin, secrets: [secret] })).rejects.toThrow(
+      "forced secret insert failure",
+    );
+
+    expect(await db.query.customWidgetDefinitions.findMany()).toHaveLength(0);
+    expect(await db.query.customWidgetSecrets.findMany()).toHaveLength(0);
+  });
+
+  test("refuses to export a stored definition containing embedded credentials", async () => {
+    const db = await prepareDatabase();
+    const definition = customWidgetDefinitionSchema.parse(jellyfin);
+    const counts = definition.requests.counts;
+    if (!counts) throw new Error("Jellyfin counts request is missing");
+    const id = createId();
+    await db.insert(customWidgetDefinitions).values({
+      id,
+      ...serializeCustomWidgetDefinition({
+        ...definition,
+        requests: {
+          ...definition.requests,
+          counts: {
+            ...counts,
+            headers: { ...counts.headers, "X-Auth": "Bearer sk-secret-123456" },
+          },
+        },
+      }),
+      creatorId: userId,
+    });
+
+    await expect(createCaller(db).export({ id })).rejects.toThrow("Credentials must use source authentication");
+  });
+
+  test("rolls back definition and secret changes when a replacement secret cannot be stored", async () => {
+    const db = await prepareDatabase();
+    const caller = createCaller(db);
+    const created = await caller.create({ ...jellyfin, secrets: [secret] });
+    const originalDefinition = await db.query.customWidgetDefinitions.findFirst({
+      where: eq(customWidgetDefinitions.id, created.id),
+    });
+    const originalSecret = await db.query.customWidgetSecrets.findFirst({
+      where: eq(customWidgetSecrets.definitionId, created.id),
+    });
+    rejectSecretInserts(db);
+
+    await expect(
+      caller.update({
+        id: created.id,
+        name: "Changed Jellyfin Library",
+        secrets: [{ ...secret, value: "replacement-secret" }],
+      }),
+    ).rejects.toThrow("forced secret insert failure");
+
+    const storedDefinition = await db.query.customWidgetDefinitions.findFirst({
+      where: eq(customWidgetDefinitions.id, created.id),
+    });
+    const storedSecret = await db.query.customWidgetSecrets.findFirst({
+      where: eq(customWidgetSecrets.definitionId, created.id),
+    });
+    expect(storedDefinition?.name).toBe(originalDefinition?.name);
+    expect(storedDefinition?.updatedAt).toEqual(originalDefinition?.updatedAt);
+    expect(storedSecret).toEqual(originalSecret);
+  });
+
+  test("keeps the existing secret when setting its replacement fails", async () => {
+    const db = await prepareDatabase();
+    const caller = createCaller(db);
+    const created = await caller.create({ ...jellyfin, secrets: [secret] });
+    const originalDefinition = await db.query.customWidgetDefinitions.findFirst({
+      where: eq(customWidgetDefinitions.id, created.id),
+    });
+    const originalSecret = await db.query.customWidgetSecrets.findFirst({
+      where: eq(customWidgetSecrets.definitionId, created.id),
+    });
+    rejectSecretInserts(db);
+
+    await expect(
+      caller.secretSet({
+        definitionId: created.id,
+        secret: { ...secret, value: "replacement-secret" },
+      }),
+    ).rejects.toThrow("forced secret insert failure");
+
+    expect(
+      await db.query.customWidgetDefinitions.findFirst({
+        where: eq(customWidgetDefinitions.id, created.id),
+      }),
+    ).toEqual(originalDefinition);
+    expect(
+      await db.query.customWidgetSecrets.findFirst({
+        where: eq(customWidgetSecrets.definitionId, created.id),
+      }),
+    ).toEqual(originalSecret);
+  });
+
+  test("keeps the existing secret when clearing it cannot update the definition revision", async () => {
+    const db = await prepareDatabase();
+    const caller = createCaller(db);
+    const created = await caller.create({ ...jellyfin, secrets: [secret] });
+    const originalDefinition = await db.query.customWidgetDefinitions.findFirst({
+      where: eq(customWidgetDefinitions.id, created.id),
+    });
+    const originalSecret = await db.query.customWidgetSecrets.findFirst({
+      where: eq(customWidgetSecrets.definitionId, created.id),
+    });
+    rejectDefinitionUpdates(db);
+
+    await expect(
+      caller.secretClear({
+        definitionId: created.id,
+        sourceId: secret.sourceId,
+        kind: secret.kind,
+      }),
+    ).rejects.toThrow("forced definition update failure");
+
+    expect(
+      await db.query.customWidgetDefinitions.findFirst({
+        where: eq(customWidgetDefinitions.id, created.id),
+      }),
+    ).toEqual(originalDefinition);
+    expect(
+      await db.query.customWidgetSecrets.findFirst({
+        where: eq(customWidgetSecrets.definitionId, created.id),
+      }),
+    ).toEqual(originalSecret);
+  });
+
+  test("configures a source URL and credential together", async () => {
+    const db = await prepareDatabase();
+    const caller = createCaller(db);
+    const created = await caller.create({ ...jellyfin, secrets: [] });
+
+    await caller.sourceConfigure({
+      definitionId: created.id,
+      sourceId: "default",
+      baseUrl: "http://jellyfin.local:8096",
+      networkScope: "private",
+      secrets: [secret],
+    });
+
+    const definition = await caller.get({ id: created.id });
+    expect(definition.sources.default?.baseUrl).toBe("http://jellyfin.local:8096");
+    expect(definition.secrets).toMatchObject([{ sourceId: "default", kind: "apiKey", hasValue: true }]);
+  });
+
+  test("rolls back a source URL when its credential cannot be stored", async () => {
+    const db = await prepareDatabase();
+    const caller = createCaller(db);
+    const created = await caller.create({ ...jellyfin, secrets: [] });
+    const before = await caller.get({ id: created.id });
+    rejectSecretInserts(db);
+
+    await expect(
+      caller.sourceConfigure({
+        definitionId: created.id,
+        sourceId: "default",
+        baseUrl: "http://jellyfin.local:8096",
+        networkScope: "private",
+        secrets: [secret],
+      }),
+    ).rejects.toThrow("forced secret insert failure");
+
+    expect((await caller.get({ id: created.id })).sources.default?.baseUrl).toBe(before.sources.default?.baseUrl);
+  });
+
+  test("uses the preview widget name in a user configuration request", async () => {
+    const db = await prepareDatabase();
+    const caller = createCaller(db);
+    const preview = await caller.previewCreate({
+      definition: { ...jellyfin, name: "Living room Jellyfin" },
+      secrets: [],
+    });
+
+    const request = await caller.configurationRequestUser({
+      previewSessionId: preview.previewSession.id,
+      sourceId: "default",
+    });
+
+    expect(await getCustomWidgetConfigurationRequestForUser(request.requestId, userId)).toMatchObject({
+      widgetName: "Living room Jellyfin",
+    });
+  });
+
+  test("does not inherit a stored credential after a preview source binding changes", async () => {
+    const db = await prepareDatabase();
+    const caller = createCaller(db);
+    const created = await caller.create({ ...jellyfin, secrets: [secret] });
+    const changedDefinition = {
+      ...jellyfin,
+      sources: {
+        ...jellyfin.sources,
+        default: { ...jellyfinDefaultSource, baseUrl: "https://attacker.example" },
+      },
+    };
+
+    await expect(
+      createNonAdminCaller(db).previewCreate({
+        definitionId: created.id,
+        definition: changedDefinition,
+        secrets: [],
+      }),
+    ).rejects.toMatchObject({ code: "FORBIDDEN" });
+    await expect(
+      caller.previewCreate({ definitionId: created.id, definition: changedDefinition, secrets: [secret] }),
+    ).resolves.toMatchObject({ success: true });
+  });
+
+  test("clears persisted credentials when an admin source edit changes its binding", async () => {
+    const db = await prepareDatabase();
+    const created = await createCaller(db).create({ ...jellyfin, secrets: [secret] });
+
+    await createCaller(db).sourceConfigure({
+      definitionId: created.id,
+      sourceId: "default",
+      baseUrl: "https://other.example/api",
+      networkScope: "public",
+      secrets: [],
+    });
+
+    expect(
+      await db.query.customWidgetSecrets.findMany({
+        where: eq(customWidgetSecrets.definitionId, created.id),
+      }),
+    ).toHaveLength(0);
+  });
+
+  test("uses the persisted source binding from inside the configuration transaction", async () => {
+    const db = await prepareDatabase();
+    const created = await createCaller(db).create({ ...jellyfin, secrets: [secret] });
+    const definition = customWidgetDefinitionSchema.parse(jellyfin);
+    const defaultSource = definition.sources.default;
+    if (!defaultSource) throw new Error("Jellyfin default source is missing");
+    await db
+      .update(customWidgetDefinitions)
+      .set(
+        serializeCustomWidgetDefinition({
+          ...definition,
+          name: "Concurrent definition edit",
+          sources: {
+            ...definition.sources,
+            default: { ...defaultSource, baseUrl: "https://changed.example/api" },
+          },
+        }),
+      )
+      .where(eq(customWidgetDefinitions.id, created.id));
+
+    await expect(
+      configureCustomWidgetSourceFromRequest(db, {
+        definitionId: created.id,
+        sourceId: "default",
+        baseUrl: defaultSource.baseUrl,
+        networkScope: defaultSource.networkScope,
+        secrets: [],
+        expectedSource: defaultSource,
+      }),
+    ).resolves.toMatchObject({
+      status: "configured",
+      source: { baseUrl: defaultSource.baseUrl },
+    });
+
+    expect(await createCaller(db).get({ id: created.id })).toMatchObject({
+      name: "Concurrent definition edit",
+      sources: { default: { baseUrl: defaultSource.baseUrl } },
+    });
+    expect(
+      await db.query.customWidgetSecrets.findMany({
+        where: eq(customWidgetSecrets.definitionId, created.id),
+      }),
+    ).toHaveLength(0);
+  });
+
+  test("rejects stale setup-link credentials after a concurrent authentication binding change", async () => {
+    const db = await prepareDatabase();
+    const created = await createCaller(db).create({ ...jellyfin, secrets: [] });
+    const definition = customWidgetDefinitionSchema.parse(jellyfin);
+    const expectedSource = definition.sources.default;
+    if (!expectedSource || typeof expectedSource.auth === "string") {
+      throw new Error("Jellyfin default source must use header authentication");
+    }
+    await db
+      .update(customWidgetDefinitions)
+      .set(
+        serializeCustomWidgetDefinition({
+          ...definition,
+          name: "Concurrent definition edit",
+          sources: {
+            ...definition.sources,
+            default: {
+              ...expectedSource,
+              auth: { ...expectedSource.auth, name: "X-Replaced-Credential" },
+            },
+          },
+        }),
+      )
+      .where(eq(customWidgetDefinitions.id, created.id));
+
+    await expect(
+      configureCustomWidgetSourceFromRequest(db, {
+        definitionId: created.id,
+        sourceId: "default",
+        baseUrl: "https://configured.example/api",
+        networkScope: "public",
+        secrets: [secret],
+        expectedSource,
+      }),
+    ).resolves.toEqual({ status: "binding-changed" });
+
+    expect(await createCaller(db).get({ id: created.id })).toMatchObject({
+      name: "Concurrent definition edit",
+      sources: {
+        default: {
+          baseUrl: expectedSource.baseUrl,
+          auth: { name: "X-Replaced-Credential" },
+        },
+      },
+    });
+    expect(
+      await db.query.customWidgetSecrets.findMany({
+        where: eq(customWidgetSecrets.definitionId, created.id),
+      }),
+    ).toHaveLength(0);
+  });
+
+  test("clears persisted credentials when a general definition update changes its binding", async () => {
+    const db = await prepareDatabase();
+    const caller = createCaller(db);
+    const created = await caller.create({ ...jellyfin, secrets: [secret] });
+
+    await createCaller(db).update({
+      id: created.id,
+      sources: {
+        ...jellyfin.sources,
+        default: { ...jellyfinDefaultSource, baseUrl: "https://other.example/api" },
+      },
+    });
+
+    expect(
+      await db.query.customWidgetSecrets.findMany({
+        where: eq(customWidgetSecrets.definitionId, created.id),
+      }),
+    ).toHaveLength(0);
+  });
+
+  test("requires an administrator to create a stored-definition setup link", async () => {
+    const db = await prepareDatabase();
+    const created = await createCaller(db).create({ ...jellyfin, secrets: [] });
+
+    await expect(
+      createNonAdminCaller(db).configurationRequestUser({ definitionId: created.id, sourceId: "default" }),
+    ).rejects.toMatchObject({ code: "FORBIDDEN" });
+  });
+
+  test("allows only one concurrent template patch for a revision", async () => {
+    const db = await prepareDatabase();
+    const caller = createCaller(db);
+    const created = await caller.create({ ...jellyfin, template: "<Text>Original</Text>", secrets: [] });
+    const read = await caller.readTemplate({ id: created.id });
+
+    const results = await Promise.allSettled([
+      caller.templatePatch({
+        id: created.id,
+        expectedRevision: read.revision,
+        edits: [{ startLine: 1, deleteCount: 1, replacementLines: ["<Text>First</Text>"] }],
+      }),
+      caller.templatePatch({
+        id: created.id,
+        expectedRevision: read.revision,
+        edits: [{ startLine: 1, deleteCount: 1, replacementLines: ["<Text>Second</Text>"] }],
+      }),
+    ]);
+
+    expect(results.filter(({ status }) => status === "fulfilled")).toHaveLength(1);
+    expect(results.filter(({ status }) => status === "rejected")).toHaveLength(1);
+  });
+});
@@ -0,0 +1,72 @@
+import { describe, expect, test } from "vitest";
+import { stringify as stringifySuperJson } from "superjson";
+
+import { buildLegacyCustomWidgetMigrationPrompt } from "../../custom-widget/legacy-migration";
+
+describe("legacy custom widget migration prompt", () => {
+  test("describes the legacy widget without exposing URL or body credentials", () => {
+    const prompt = buildLegacyCustomWidgetMigrationPrompt(
+      {
+        id: "legacy",
+        name: "Private service",
+        description: "Status",
+        iconUrl: "https://icons:password@example.test/private/icon.svg?access_token=icon-secret",
+        url: "https://admin:password@example.test/hooks/path-token?api_key=top-secret&mode=full",
+        authType: "bearer",
+        headerName: null,
+        method: "POST",
+        requestBody: JSON.stringify({ token: "body-secret", limit: 5 }),
+        displayType: "singleValue",
+        displayConfig: "corrupted-config-with-display-secret",
+        enabled: true,
+        createdAt: new Date(0),
+        updatedAt: new Date(0),
+        creatorId: null,
+      },
+      ["apiKey"],
+    );
+
+    expect(prompt).toContain("homarr-custom-widget-v1");
+    expect(prompt).toContain("homarr-custom-widget-v2");
+    expect(prompt).toContain("configuredSecretKinds");
+    expect(prompt).not.toContain("top-secret");
+    expect(prompt).not.toContain("body-secret");
+    expect(prompt).not.toContain("admin:password");
+    expect(prompt).not.toContain("path-token");
+    expect(prompt).not.toContain("icon-secret");
+    expect(prompt).not.toContain("icons:password");
+    expect(prompt).not.toContain("private/icon.svg");
+    expect(prompt).not.toContain("display-secret");
+  });
+
+  test("omits valid free-text display configuration from the migration prompt", () => {
+    const prompt = buildLegacyCustomWidgetMigrationPrompt(
+      {
+        id: "legacy-custom-jsx",
+        name: "Private service",
+        description: "Status",
+        iconUrl: null,
+        url: "https://example.test/api/status",
+        authType: "bearer",
+        headerName: null,
+        method: "GET",
+        requestBody: null,
+        displayType: "customJsx",
+        displayConfig: stringifySuperJson({
+          type: "customJsx",
+          template: "<Text>LEGACY_PRIVATE_MARKER Bearer sk-secret-123456</Text>",
+        }),
+        enabled: true,
+        createdAt: new Date(0),
+        updatedAt: new Date(0),
+        creatorId: null,
+      },
+      ["apiKey"],
+    );
+
+    expect(prompt).toContain("display configuration was intentionally omitted");
+    expect(prompt).not.toContain("LEGACY_PRIVATE_MARKER");
+    expect(prompt).not.toContain("Bearer sk-secret-123456");
+    expect(prompt).not.toContain("sk-secret-123456");
+  });
+});
@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+
+import type { CustomJsxRequest } from "@homarr/custom-widgets/core";
+
+import { resolvePreviewRequestParams } from "../../custom-widget/preview-procedure-helpers";
+import { resolveOptionRequestValues } from "../../custom-widget/management-queries";
+
+const loadRequest: CustomJsxRequest = {
+  source: "default",
+  kind: "query",
+  method: "GET",
+  path: "/endpoints/{option:environmentId}/containers",
+  auth: "inherit",
+  permission: "view",
+  trigger: "load",
+};
+
+describe("preview request option bindings", () => {
+  it("resolves load request parameters from the selected preview options", () => {
+    expect(resolvePreviewRequestParams(loadRequest, { environmentId: 7 }, {})).toEqual({
+      "option:environmentId": 7,
+    });
+  });
+
+  it("preserves invoking component parameters for manual requests", () => {
+    const manualRequest = {
+      ...loadRequest,
+      trigger: "manual" as const,
+      path: "/endpoints/{param:endpointId}/containers",
+    };
+    expect(resolvePreviewRequestParams(manualRequest, { environmentId: 7 }, { endpointId: 12 })).toEqual({
+      endpointId: 12,
+    });
+  });
+});
+
+describe("configuration option request bindings", () => {
+  it("resolves option configuration and runtime parameters in their own slots", () => {
+    const request: CustomJsxRequest = {
+      ...loadRequest,
+      path: "/environments/{option:environmentId}/containers/{param:containerId}",
+    };
+
+    expect(resolveOptionRequestValues(request, { environmentId: 7, containerId: 12, unrelated: true })).toEqual({
+      "option:environmentId": 7,
+      containerId: 12,
+    });
+  });
+});
@@ -0,0 +1,65 @@
+import { describe, expect, test } from "vitest";
+
+import {
+  assertJsonBudget,
+  assertSafeStaticHeaders,
+  classifyAddress,
+  resolveAndValidateHost,
+  resolveSameOriginTarget,
+  validateCustomWidgetUrl,
+} from "../../custom-widget/request-executor";
+
+describe("custom widget request executor", () => {
+  test.each([
+    ["8.8.8.8", "public"],
+    ["10.0.0.1", "private"],
+    ["127.0.0.1", "loopback"],
+    ["169.254.169.254", "blocked"],
+    ["224.0.0.1", "blocked"],
+    ["::ffff:127.0.0.1", "blocked"],
+    ["fe80::1", "blocked"],
+  ] as const)("classifies %s as %s", (address, expected) => {
+    expect(classifyAddress(address)).toBe(expected);
+  });
+
+  test("enforces configured address scopes", async () => {
+    await expect(resolveAndValidateHost("10.0.0.1", "public")).rejects.toMatchObject({ code: "FORBIDDEN" });
+    await expect(resolveAndValidateHost("10.0.0.1", "private")).resolves.toHaveLength(1);
+    await expect(resolveAndValidateHost("127.0.0.1", "private")).rejects.toMatchObject({ code: "FORBIDDEN" });
+    await expect(resolveAndValidateHost("127.0.0.1", "loopback")).resolves.toHaveLength(1);
+    await expect(resolveAndValidateHost("169.254.169.254", "loopback")).rejects.toMatchObject({
+      code: "FORBIDDEN",
+    });
+  });
+
+  test("allows only credential-free HTTP(S) URLs without fragments", () => {
+    expect(validateCustomWidgetUrl("https://example.com/api").href).toBe("https://example.com/api");
+    expect(() => validateCustomWidgetUrl("file:///etc/passwd")).toThrow("Only HTTP and HTTPS");
+    expect(() => validateCustomWidgetUrl("https://user:password@example.com/api")).toThrow("credentials");
+    expect(() => validateCustomWidgetUrl("https://example.com/api#secret")).toThrow("fragments");
+  });
+
+  test("rejects cross-origin named request targets", () => {
+    expect(resolveSameOriginTarget("https://example.com/base", "https://example.com/status").pathname).toBe("/status");
+    expect(() => resolveSameOriginTarget("https://example.com/base", "https://attacker.example/status")).toThrow(
+      "origin",
+    );
+  });
+
+  test.each(["Authorization", "Cookie", "Host", "Proxy-Authorization", "Sec-Fetch-Site", "X-Forwarded-For"])(
+    "rejects the reserved %s header",
+    (header) => {
+      expect(() => assertSafeStaticHeaders({ [header]: "value" })).toThrow("reserved");
+    },
+  );
+
+  test("rejects response JSON that exceeds the depth budget", () => {
+    let nested: Record<string, unknown> = {};
+    const root = nested;
+    for (let index = 0; index < 40; index += 1) {
+      nested.child = {};
+      nested = nested.child as Record<string, unknown>;
+    }
+    expect(() => assertJsonBudget(root)).toThrow("deeply nested");
+  });
+});
@@ -0,0 +1,30 @@
+import { expect, test } from "vitest";
+
+import { createId } from "@homarr/common";
+
+import { acquireCustomWidgetRequestLimit } from "../../custom-widget/request-limits";
+
+test("enforces the server-side DELETE rate limit with retry metadata", async () => {
+  const input = { category: "delete" as const, userId: createId(), itemId: createId(), definitionId: createId() };
+  for (let count = 0; count < 3; count += 1) {
+    const release = await acquireCustomWidgetRequestLimit(input);
+    await release();
+  }
+
+  try {
+    await acquireCustomWidgetRequestLimit(input);
+    expect.unreachable("the fourth DELETE request should be rate limited");
+  } catch (error) {
+    expect(error).toMatchObject({ code: "TOO_MANY_REQUESTS" });
+    const cause = (error as { cause?: { flatten?: () => Record<string, unknown> } }).cause;
+    expect(cause?.flatten?.()).toMatchObject({ retryAfterMs: expect.any(Number) });
+  }
+});
+
+test("enforces four concurrent requests per user and item", async () => {
+  const input = { category: "query" as const, userId: createId(), itemId: createId(), definitionId: createId() };
+  const releases = await Promise.all(Array.from({ length: 4 }, () => acquireCustomWidgetRequestLimit(input)));
+
+  await expect(acquireCustomWidgetRequestLimit(input)).rejects.toMatchObject({ code: "TOO_MANY_REQUESTS" });
+  await Promise.all(releases.map((release) => release()));
+});
@@ -0,0 +1,48 @@
+import { stringify as stringifySuperJson } from "superjson";
+import { describe, expect, test } from "vitest";
+
+import {
+  BUNDLED_CUSTOM_WIDGETS,
+  CUSTOM_WIDGET_STARTER,
+  customWidgetDefinitionSchema,
+} from "@homarr/custom-widgets/core";
+
+import {
+  safeParseStoredCustomWidgetDefinition,
+  serializeCustomWidgetDefinition,
+} from "../../custom-widget/stored-definition";
+
+describe("stored custom widget definitions", () => {
+  test("parses a valid stored definition", () => {
+    const result = safeParseStoredCustomWidgetDefinition(
+      serializeCustomWidgetDefinition(customWidgetDefinitionSchema.parse(CUSTOM_WIDGET_STARTER)),
+    );
+
+    expect(result).toMatchObject({ success: true, widget: { $schema: "homarr-custom-widget-v2" } });
+  });
+
+  test("returns useful issues for an invalid stored request instead of throwing", () => {
+    const currency = BUNDLED_CUSTOM_WIDGETS.find(({ id }) => id === "seed-currency-exchange");
+    if (!currency) throw new Error("Currency Exchange bundled widget is missing");
+
+    const stored = serializeCustomWidgetDefinition(customWidgetDefinitionSchema.parse(currency.widget));
+    const result = safeParseStoredCustomWidgetDefinition({
+      ...stored,
+      requests: stringifySuperJson({ rates: { path: "/latest/{option:missing}" } }),
+    });
+
+    expect(result).toEqual({
+      success: false,
+      issues: expect.arrayContaining([expect.objectContaining({ path: "requests.rates" })]),
+    });
+  });
+
+  test("contains malformed serialized data", () => {
+    const stored = serializeCustomWidgetDefinition(customWidgetDefinitionSchema.parse(CUSTOM_WIDGET_STARTER));
+
+    expect(safeParseStoredCustomWidgetDefinition({ ...stored, requests: "not-json" })).toEqual({
+      success: false,
+      issues: [{ message: "Stored widget data could not be read" }],
+    });
+  });
+});
@@ -0,0 +1,113 @@
+import type { Session } from "@homarr/auth";
+import { createId } from "@homarr/common";
+import { createDb } from "@homarr/db/test";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  get: vi.fn(async (_id: string): Promise<unknown> => undefined),
+  list: vi.fn(async (_options: unknown): Promise<unknown> => undefined),
+  logger: {
+    debug: vi.fn(),
+    error: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+  },
+}));
+
+vi.mock("@homarr/core/infrastructure/logs", () => ({
+  createLogger: () => mocks.logger,
+}));
+
+vi.mock("@homarr/workshop/backend", () => ({
+  WorkshopBackend: class {
+    public get(id: string) {
+      return mocks.get(id);
+    }
+
+    public list(options: unknown) {
+      return mocks.list(options);
+    }
+  },
+}));
+
+import { customWidgetRouter } from "../../custom-widget/custom-widget-router";
+
+const session = {
+  user: {
+    id: createId(),
+    permissions: ["admin"],
+    colorScheme: "light",
+  },
+  expires: new Date(Date.now() + 60_000).toISOString(),
+} satisfies Session;
+
+const createCaller = () =>
+  customWidgetRouter.createCaller({
+    db: createDb(),
+    deviceType: undefined,
+    session,
+  });
+
+const createTokenizedFailure = (apiKey: string) => {
+  const tokenizedUrl = `https://workshop.example/api/submissions?access_token=${apiKey}`;
+  const error = new Error(`Workshop request failed for ${tokenizedUrl}`);
+  error.name = `WorkshopTransportError:${tokenizedUrl}`;
+  return error;
+};
+
+const expectSafeFailure = (
+  error: unknown,
+  apiKey: string,
+  logMessage: string,
+  event: "workshop_widget_lookup_failed" | "workshop_widget_search_failed",
+) => {
+  expect(error).toMatchObject({
+    code: "BAD_GATEWAY",
+    message: "Workshop is unavailable",
+  });
+  expect((error as Error).cause).toBeUndefined();
+  expect(String(error)).not.toContain(apiKey);
+  expect(String(error)).not.toContain("access_token");
+  expect(mocks.logger.error).toHaveBeenCalledWith(logMessage, {
+    event,
+    errorName: "WorkshopBackendError",
+  });
+  expect(JSON.stringify(mocks.logger.error.mock.calls)).not.toContain(apiKey);
+  expect(JSON.stringify(mocks.logger.error.mock.calls)).not.toContain("access_token");
+};
+
+describe("Workshop backend error privacy", () => {
+  beforeEach(() => {
+    mocks.get.mockReset();
+    mocks.list.mockReset();
+    mocks.logger.error.mockClear();
+  });
+
+  test("redacts backend lookup failures from TRPC output and logs", async () => {
+    const apiKey = "workshop-lookup-secret";
+    mocks.get.mockRejectedValueOnce(createTokenizedFailure(apiKey));
+
+    const error = await createCaller()
+      .workshopGet({ submissionId: "submission-id" })
+      .then(
+        () => undefined,
+        (cause: unknown) => cause,
+      );
+
+    expectSafeFailure(error, apiKey, "Workshop widget lookup failed", "workshop_widget_lookup_failed");
+  });
+
+  test("redacts backend search failures from TRPC output and logs", async () => {
+    const apiKey = "workshop-search-secret";
+    mocks.list.mockRejectedValueOnce(createTokenizedFailure(apiKey));
+
+    const error = await createCaller()
+      .workshopSearch({ query: "weather" })
+      .then(
+        () => undefined,
+        (cause: unknown) => cause,
+      );
+
+    expectSafeFailure(error, apiKey, "Workshop widget search failed", "workshop_widget_search_failed");
+  });
+});
@@ -0,0 +1,90 @@
+import { stringify } from "superjson";
+import { describe, expect, it } from "vitest";
+
+import type { Session } from "@homarr/auth";
+import { createId } from "@homarr/common";
+import { eq } from "@homarr/db";
+import { boards, sectionCollapseStates, sections, users } from "@homarr/db/schema";
+import { createDb } from "@homarr/db/test";
+
+import { sectionRouter } from "../section/section-router";
+
+const userId = createId();
+const session = {
+  user: {
+    id: userId,
+    permissions: [],
+    colorScheme: "light",
+  },
+  expires: new Date().toISOString(),
+} satisfies Session;
+
+const createCallerAsync = async () => {
+  const db = createDb();
+  const boardId = createId();
+
+  await db.insert(users).values({ id: userId });
+  await db.insert(boards).values({
+    id: boardId,
+    name: createId(),
+    creatorId: userId,
+  });
+
+  return {
+    boardId,
+    db,
+    caller: sectionRouter.createCaller({
+      db,
+      deviceType: undefined,
+      session,
+    }),
+  };
+};
+
+describe("changeCollapsed", () => {
+  it("rejects a root section", async () => {
+    const { boardId, caller, db } = await createCallerAsync();
+    const sectionId = createId();
+    await db.insert(sections).values({
+      id: sectionId,
+      boardId,
+      kind: "empty",
+      xOffset: 0,
+      yOffset: 0,
+    });
+
+    await expect(caller.changeCollapsed({ sectionId, collapsed: true })).rejects.toThrow("Section cannot be collapsed");
+  });
+
+  it("creates and updates collapse state for an enabled container", async () => {
+    const { boardId, caller, db } = await createCallerAsync();
+    const sectionId = createId();
+    await db.insert(sections).values({
+      id: sectionId,
+      boardId,
+      kind: "container",
+      options: stringify({ collapsible: true }),
+    });
+
+    await caller.changeCollapsed({ sectionId, collapsed: true });
+    await caller.changeCollapsed({ sectionId, collapsed: false });
+
+    const states = await db.query.sectionCollapseStates.findMany({
+      where: eq(sectionCollapseStates.sectionId, sectionId),
+    });
+    expect(states).toHaveLength(1);
+    expect(states[0]?.collapsed).toBe(false);
+  });
+
+  it("rejects a container when collapsing is disabled", async () => {
+    const { boardId, caller, db } = await createCallerAsync();
+    const sectionId = createId();
+    await db.insert(sections).values({
+      id: sectionId,
+      boardId,
+      kind: "container",
+    });
+
+    await expect(caller.changeCollapsed({ sectionId, collapsed: true })).rejects.toThrow("Section cannot be collapsed");
+  });
+});
@@ -0,0 +1,58 @@
+import { describe, expect, test, vi } from "vitest";
+
+import type { Session } from "@homarr/auth";
+import type { Database } from "@homarr/db";
+import type { GroupPermissionKey } from "@homarr/definitions";
+
+import { updateCheckerRouter } from "../update-checker";
+
+const mocks = vi.hoisted(() => ({
+  getDataAsync: vi.fn(async () => ({
+    data: { availableUpdates: [{ tagName: "v99.0.0" }] },
+    timestamp: new Date(),
+  })),
+}));
+
+vi.mock("@homarr/request-handler/update-checker", () => ({
+  updateCheckerRequestHandler: {
+    handler: () => ({ getDataAsync: mocks.getDataAsync }),
+  },
+}));
+
+const createSession = (permissions: GroupPermissionKey[]): Session => ({
+  user: {
+    id: "user",
+    permissions,
+    colorScheme: "light",
+  },
+  expires: new Date().toISOString(),
+});
+
+const createCaller = (session: Session | null) =>
+  updateCheckerRouter.createCaller({
+    db: null as unknown as Database,
+    deviceType: undefined,
+    session,
+  });
+
+describe("update checker authorization", () => {
+  test("allows administrators to read the cached result", async () => {
+    await expect(createCaller(createSession(["admin"])).getAvailableUpdates()).resolves.toEqual([
+      { tagName: "v99.0.0" },
+    ]);
+  });
+
+  test("rejects authenticated users without admin permission", async () => {
+    await expect(createCaller(createSession([])).getAvailableUpdates()).rejects.toThrow("Permission denied");
+  });
+
+  test("rejects anonymous users", async () => {
+    await expect(createCaller(null).getAvailableUpdates()).rejects.toThrow("UNAUTHORIZED");
+  });
+
+  test("returns an empty result when the cache reader fails", async () => {
+    mocks.getDataAsync.mockRejectedValueOnce(new Error("Redis unavailable"));
+
+    await expect(createCaller(createSession(["admin"])).getAvailableUpdates()).resolves.toEqual([]);
+  });
+});
@@ -0,0 +1,204 @@
+import { stringify as stringifySuperJson } from "superjson";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+import type { Session } from "@homarr/auth";
+import { createId } from "@homarr/common";
+import { eq } from "@homarr/db";
+import { boardUserPermissions, boards, customWidgetDefinitions, items, users } from "@homarr/db/schema";
+import { createDb } from "@homarr/db/test";
+import type { HomarrCustomWidgetV2 } from "@homarr/custom-widgets/core";
+
+const mocks = vi.hoisted(() => ({
+  executeRequest: vi.fn(async () => ({ ok: true, status: 200, statusText: "OK", data: { value: 42 } })),
+}));
+
+vi.mock("../../custom-widget/request-executor", () => ({
+  executeCustomWidgetRequest: mocks.executeRequest,
+  invalidateCustomWidgetResponseCache: vi.fn(),
+}));
+
+vi.mock("../../custom-widget/request-limits", () => ({
+  acquireCustomWidgetRequestLimit: vi.fn(async () => async () => undefined),
+}));
+
+import { serializeCustomWidgetDefinition } from "../../custom-widget/stored-definition";
+import { customApiRouter } from "../../widgets/custom-api";
+
+const definition: HomarrCustomWidgetV2 = {
+  $schema: "homarr-custom-widget-v2",
+  name: "Router test widget",
+  sources: {
+    default: {
+      name: "API",
+      baseUrl: "https://example.com",
+      networkScope: "public",
+      auth: "none",
+    },
+  },
+  requests: {
+    "load-status": {
+      source: "default",
+      kind: "query",
+      method: "GET",
+      path: "/status",
+      auth: "inherit",
+      permission: "view",
+      trigger: "load",
+    },
+    status: {
+      source: "default",
+      kind: "query",
+      method: "GET",
+      path: "/status/{param:name}",
+      auth: "inherit",
+      permission: "view",
+      trigger: "manual",
+    },
+    toggle: {
+      source: "default",
+      kind: "action",
+      method: "POST",
+      path: "/toggle",
+      body: { enabled: { $param: "enabled" } },
+      auth: "inherit",
+      permission: "modify",
+      trigger: "manual",
+    },
+    delete: {
+      source: "default",
+      kind: "action",
+      method: "DELETE",
+      path: "/resource",
+      auth: "inherit",
+      permission: "full",
+      trigger: "manual",
+      confirmation: { title: "Delete resource", message: "Delete this resource?", destructive: true },
+    },
+  },
+  options: {},
+  template: "<Text>{data['load-status']?.value}</Text>",
+};
+
+const createSession = (userId: string): Session => ({
+  user: { id: userId, permissions: [], colorScheme: "light" },
+  expires: new Date(Date.now() + 60_000).toISOString(),
+});
+
+async function setup(isPublic = true) {
+  const db = createDb();
+  const ownerId = createId();
+  const boardId = createId();
+  const itemId = createId();
+  const definitionId = createId();
+  await db.insert(users).values({ id: ownerId });
+  await db.insert(boards).values({ id: boardId, name: createId(), creatorId: ownerId, isPublic });
+  await db.insert(customWidgetDefinitions).values({
+    id: definitionId,
+    ...serializeCustomWidgetDefinition(definition),
+    creatorId: ownerId,
+  });
+  await db.insert(items).values({
+    id: itemId,
+    boardId,
+    kind: "customApi",
+    options: stringifySuperJson({ definitionId, configuration: {}, configurationVersion: 1 }),
+  });
+  return { db, ownerId, boardId, itemId, definitionId };
+}
+
+describe("Custom JSX v2 board router", () => {
+  beforeEach(() => mocks.executeRequest.mockClear());
+
+  test("allows public queries only through the definition placed on an accessible board", async () => {
+    const { db, itemId } = await setup();
+    const caller = customApiRouter.createCaller({ db, deviceType: undefined, session: null });
+
+    await expect(caller.queryRequest({ itemId, requestId: "status", params: { name: "homarr" } })).resolves.toEqual(
+      expect.objectContaining({ ok: true, data: { value: 42 } }),
+    );
+    await expect(caller.queryRequest({ itemId, requestId: "missing", params: {} })).rejects.toMatchObject({
+      code: "NOT_FOUND",
+    });
+    expect(mocks.executeRequest).toHaveBeenCalledOnce();
+  });
+
+  test("hides private boards and disabled definitions before executing a request", async () => {
+    const privateSetup = await setup(false);
+    const anonymous = customApiRouter.createCaller({
+      db: privateSetup.db,
+      deviceType: undefined,
+      session: null,
+    });
+    await expect(
+      anonymous.queryRequest({ itemId: privateSetup.itemId, requestId: "status", params: { name: "homarr" } }),
+    ).rejects.toMatchObject({ code: "NOT_FOUND" });
+
+    const enabledSetup = await setup();
+    await enabledSetup.db
+      .update(customWidgetDefinitions)
+      .set({ enabled: false })
+      .where(eq(customWidgetDefinitions.id, enabledSetup.definitionId));
+    const publicCaller = customApiRouter.createCaller({ db: enabledSetup.db, deviceType: undefined, session: null });
+    await expect(publicCaller.getData({ itemId: enabledSetup.itemId })).rejects.toMatchObject({ code: "FORBIDDEN" });
+    await expect(
+      publicCaller.queryRequest({ itemId: enabledSetup.itemId, requestId: "status", params: { name: "homarr" } }),
+    ).rejects.toMatchObject({ code: "FORBIDDEN" });
+    const ownerCaller = customApiRouter.createCaller({
+      db: enabledSetup.db,
+      deviceType: undefined,
+      session: createSession(enabledSetup.ownerId),
+    });
+    await expect(
+      ownerCaller.executeAction({ itemId: enabledSetup.itemId, requestId: "toggle", params: { enabled: true } }),
+    ).rejects.toMatchObject({ code: "FORBIDDEN" });
+    expect(mocks.executeRequest).not.toHaveBeenCalled();
+  });
+
+  test("rejects request-kind and parameter mismatches", async () => {
+    const { db, itemId, ownerId } = await setup();
+    const caller = customApiRouter.createCaller({ db, deviceType: undefined, session: createSession(ownerId) });
+
+    await expect(caller.queryRequest({ itemId, requestId: "toggle", params: { enabled: true } })).rejects.toMatchObject(
+      { code: "NOT_FOUND" },
+    );
+    await expect(caller.queryRequest({ itemId, requestId: "status", params: {} })).rejects.toThrow();
+    expect(mocks.executeRequest).not.toHaveBeenCalled();
+  });
+
+  test("enforces modify permission and renders an authorized action body", async () => {
+    const { db, itemId, boardId } = await setup(false);
+    const editorId = createId();
+    await db.insert(users).values({ id: editorId });
+    const caller = customApiRouter.createCaller({ db, deviceType: undefined, session: createSession(editorId) });
+
+    await expect(
+      caller.executeAction({ itemId, requestId: "toggle", params: { enabled: true } }),
+    ).rejects.toMatchObject({ code: "NOT_FOUND" });
+    await db.insert(boardUserPermissions).values({ boardId, userId: editorId, permission: "modify" });
+    await expect(caller.executeAction({ itemId, requestId: "toggle", params: { enabled: true } })).resolves.toEqual(
+      expect.objectContaining({ ok: true }),
+    );
+    expect(mocks.executeRequest).toHaveBeenCalledWith(
+      expect.objectContaining({ method: "POST", body: '{"enabled":true}' }),
+    );
+  });
+
+  test("requires confirmation and full permission for DELETE actions", async () => {
+    const { db, itemId, boardId, ownerId } = await setup(false);
+    const owner = customApiRouter.createCaller({ db, deviceType: undefined, session: createSession(ownerId) });
+    await expect(owner.executeAction({ itemId, requestId: "delete", params: {} })).rejects.toMatchObject({
+      code: "PRECONDITION_FAILED",
+    });
+
+    const editorId = createId();
+    await db.insert(users).values({ id: editorId });
+    await db.insert(boardUserPermissions).values({ boardId, userId: editorId, permission: "modify" });
+    const editor = customApiRouter.createCaller({ db, deviceType: undefined, session: createSession(editorId) });
+    await expect(
+      editor.executeAction({ itemId, requestId: "delete", params: {}, confirmed: true }),
+    ).rejects.toMatchObject({ code: "NOT_FOUND" });
+    await expect(owner.executeAction({ itemId, requestId: "delete", params: {}, confirmed: true })).resolves.toEqual(
+      expect.objectContaining({ ok: true }),
+    );
+  });
+});
@@ -0,0 +1,107 @@
+import SuperJSON from "superjson";
+import { describe, expect, test } from "vitest";
+
+import type { Session } from "@homarr/auth";
+import { createId } from "@homarr/common";
+import { eq } from "@homarr/db";
+import { boards, items, users } from "@homarr/db/schema";
+import { createDb } from "@homarr/db/test";
+
+import { optionsRouter } from "../../widgets/options";
+
+const createSession = (userId: string, isAdmin = false): Session => ({
+  user: {
+    id: userId,
+    permissions: isAdmin ? ["admin"] : [],
+    colorScheme: "light",
+  },
+  expires: new Date(Date.now() + 60_000).toISOString(),
+});
+
+async function setup(kind: "customApi" | "weather") {
+  const db = createDb();
+  const userId = createId();
+  const boardId = createId();
+  const itemId = createId();
+  await db.insert(users).values({ id: userId });
+  await db.insert(boards).values({ id: boardId, name: createId(), creatorId: userId });
+  await db.insert(items).values({
+    id: itemId,
+    boardId,
+    kind,
+    options: SuperJSON.stringify(
+      kind === "customApi"
+        ? { definitionId: "definition-1", refreshInterval: 30, configuration: { server: "primary" } }
+        : { location: "Paris" },
+    ),
+  });
+  return { db, userId, boardId, itemId };
+}
+
+describe("saveItemOptions Custom Widget access", () => {
+  test("rejects direct Custom Widget reconfiguration by a non-admin board modifier", async () => {
+    const { db, userId, boardId, itemId } = await setup("customApi");
+    const caller = optionsRouter.createCaller({ db, deviceType: undefined, session: createSession(userId) });
+
+    await expect(
+      caller.saveItemOptions({
+        boardId,
+        itemId,
+        newOptions: {
+          definitionId: "definition-2",
+          refreshInterval: 1,
+          configuration: { server: "attacker" },
+        },
+      }),
+    ).rejects.toMatchObject({ code: "FORBIDDEN" });
+
+    const stored = await db.query.items.findFirst({ where: eq(items.id, itemId) });
+    expect(SuperJSON.parse(stored?.options ?? "")).toMatchObject({
+      definitionId: "definition-1",
+      refreshInterval: 30,
+      configuration: { server: "primary" },
+    });
+  });
+
+  test("allows a Homarr admin to reconfigure a Custom Widget placement", async () => {
+    const { db, userId, boardId, itemId } = await setup("customApi");
+    const caller = optionsRouter.createCaller({ db, deviceType: undefined, session: createSession(userId, true) });
+
+    await expect(
+      caller.saveItemOptions({ boardId, itemId, newOptions: { refreshInterval: 60 } }),
+    ).resolves.toBeUndefined();
+
+    const stored = await db.query.items.findFirst({ where: eq(items.id, itemId) });
+    expect(SuperJSON.parse(stored?.options ?? "")).toMatchObject({ refreshInterval: 60 });
+  });
+
+  test("allows normalized missing defaults without treating them as reconfiguration", async () => {
+    const { db, userId, boardId, itemId } = await setup("customApi");
+    const stored = await db.query.items.findFirst({ where: eq(items.id, itemId) });
+    const options = SuperJSON.parse<Record<string, unknown>>(stored?.options ?? "");
+    delete options.configuration;
+    delete options.configurationVersion;
+    await db
+      .update(items)
+      .set({ options: SuperJSON.stringify(options) })
+      .where(eq(items.id, itemId));
+    const caller = optionsRouter.createCaller({ db, deviceType: undefined, session: createSession(userId) });
+
+    await expect(
+      caller.saveItemOptions({
+        boardId,
+        itemId,
+        newOptions: { configuration: {}, configurationVersion: 1 },
+      }),
+    ).resolves.toBeUndefined();
+  });
+
+  test("preserves ordinary board-modifier option updates for other widgets", async () => {
+    const { db, userId, boardId, itemId } = await setup("weather");
+    const caller = optionsRouter.createCaller({ db, deviceType: undefined, session: createSession(userId) });
+
+    await expect(
+      caller.saveItemOptions({ boardId, itemId, newOptions: { location: "Lyon" } }),
+    ).resolves.toBeUndefined();
+  });
+});