harden v2 custom widgets and workshop

This commit is contained in:
ajnart committed 2026-07-28 14:12:14 +02:00
1 parent e8a2c87c2d
commit 723b46926a
194 files changed
+44862 -1265

No files matched your search

@@ -1,5 +1,6 @@
export * from "./router/custom-widget/configuration-requests";
export { configurePreviewSessionSource } from "./router/custom-widget/preview-sessions";
export { invalidateCustomWidgetResponseCache } from "./router/custom-widget/request-executor";
export {
parseStoredCustomWidgetDefinition,
serializeCustomWidgetDefinition,
@@ -0,0 +1,4 @@
export function useProcessLocalCustomWidgetState(runtime: { CI?: string; NODE_ENV?: string } = process.env): boolean {
if (runtime.NODE_ENV === "production") return false;
return runtime.NODE_ENV === "test" || runtime.CI === "true";
}
+22
View File
@@ -1,16 +1,38 @@
import { z } from "zod/v4";
import { createBooleanSchema, createEnv } from "@homarr/core/infrastructure/env";
import { normalizeHttpUrl } from "@homarr/workshop/schema";
const publicHttpUrl = (variableName: string) =>
z.string().transform((value, context) => {
try {
return normalizeHttpUrl(value, variableName);
} catch (error) {
context.addIssue({
code: "custom",
message: error instanceof Error ? error.message : `${variableName} is invalid`,
});
return z.NEVER;
}
});
export const env = createEnv({
server: {
KUBERNETES_SERVICE_ACCOUNT_NAME: z.string().optional(),
DEMO_MODE: createBooleanSchema(false),
DEMO_READ_ONLY: createBooleanSchema(true),
CUSTOM_WIDGETS_ENABLED: createBooleanSchema(true),
WORKSHOP_ENABLED: createBooleanSchema(true),
HOMARR_WEBSITE_URL: publicHttpUrl("HOMARR_WEBSITE_URL").default("https://homarr.dev"),
WORKSHOP_API_URL: publicHttpUrl("WORKSHOP_API_URL").optional(),
},
runtimeEnv: {
KUBERNETES_SERVICE_ACCOUNT_NAME: process.env.KUBERNETES_SERVICE_ACCOUNT_NAME,
DEMO_MODE: process.env.DEMO_MODE,
DEMO_READ_ONLY: process.env.DEMO_READ_ONLY,
CUSTOM_WIDGETS_ENABLED: process.env.CUSTOM_WIDGETS_ENABLED,
WORKSHOP_ENABLED: process.env.WORKSHOP_ENABLED,
HOMARR_WEBSITE_URL: process.env.HOMARR_WEBSITE_URL,
WORKSHOP_API_URL: process.env.WORKSHOP_API_URL,
},
});
+22
View File
@@ -59,8 +59,13 @@ import { zodUnionFromArray } from "@homarr/validation/enums";
import type { BoardItemAdvancedOptions } from "@homarr/validation/shared";
import { sectionSchema, sharedItemSchema } from "@homarr/validation/shared";
import { env } from "../env";
import { createTRPCRouter, permissionRequiredProcedure, protectedProcedure, publicProcedure } from "../trpc";
import { throwIfActionForbiddenAsync } from "./board/board-access";
import {
throwIfCustomWidgetBoardDuplicationForbidden,
throwIfCustomWidgetPlacementChangeForbidden,
} from "./board/custom-widget-placement-access";
import { generateResponsiveGridFor } from "./board/grid-algorithm";
export const boardRouter = createTRPCRouter({
@@ -372,6 +377,11 @@ export const boardRouter = createTRPCRouter({
}
const { sections: boardSections, items: boardItems, layouts: boardLayouts, ...boardProps } = board;
throwIfCustomWidgetBoardDuplicationForbidden(
ctx.session.user.permissions.includes("admin"),
env.CUSTOM_WIDGETS_ENABLED !== false,
boardItems,
);
const newBoardId = createId();
@@ -855,6 +865,12 @@ export const boardRouter = createTRPCRouter({
await throwIfActionForbiddenAsync(ctx, eq(boards.id, input.id), "modify");
const dbBoard = await getFullBoardWithWhereAsync(ctx.db, eq(boards.id, input.id), ctx.session.user.id);
throwIfCustomWidgetPlacementChangeForbidden({
isAdmin: ctx.session.user.permissions.includes("admin"),
customWidgetsEnabled: env.CUSTOM_WIDGETS_ENABLED !== false,
submittedItems: input.items,
storedItems: dbBoard.items,
});
await handleTransactionsAsync(ctx.db, {
async handleAsync(db, schema) {
@@ -1440,6 +1456,12 @@ export const boardRouter = createTRPCRouter({
.output(z.object({ itemId: z.string() }))
.mutation(async ({ ctx, input }) => {
await throwIfActionForbiddenAsync(ctx, eq(boards.id, input.boardId), "modify");
throwIfCustomWidgetPlacementChangeForbidden({
isAdmin: ctx.session.user.permissions.includes("admin"),
customWidgetsEnabled: env.CUSTOM_WIDGETS_ENABLED !== false,
submittedItems: [{ id: "", kind: input.kind, options: input.options }],
storedItems: [],
});
if (input.integrationIds.length > 0) {
const existing = await ctx.db.query.integrations.findMany({
@@ -0,0 +1,96 @@
import { isDeepStrictEqual } from "node:util";
import { TRPCError } from "@trpc/server";
interface BoardPlacement {
id: string;
kind: string;
options: Record<string, unknown>;
}
interface CustomWidgetPlacementGuardInput {
isAdmin: boolean;
customWidgetsEnabled: boolean;
submittedItems: readonly BoardPlacement[];
storedItems: readonly BoardPlacement[];
}
const throwAdminRequired = () => {
throw new TRPCError({
code: "FORBIDDEN",
message: "Only administrators can add or configure Custom Widgets",
});
};
const throwFeatureDisabled = () => {
throw new TRPCError({
code: "SERVICE_UNAVAILABLE",
message: "Custom Widgets are temporarily disabled by the server administrator",
});
};
const assertAuthoringAllowed = (isAdmin: boolean, customWidgetsEnabled: boolean) => {
if (!customWidgetsEnabled) throwFeatureDisabled();
if (!isAdmin) throwAdminRequired();
};
/**
* Protects the security-sensitive part of Custom Widget placements while
* leaving ordinary board operations (layout, presentation and removal) to the
* existing board permission checks.
*/
export const throwIfCustomWidgetPlacementChangeForbidden = ({
isAdmin,
customWidgetsEnabled,
submittedItems,
storedItems,
}: CustomWidgetPlacementGuardInput) => {
const storedById = new Map(storedItems.map((item) => [item.id, item]));
for (const submitted of submittedItems) {
const stored = storedById.get(submitted.id);
if (!stored) {
if (submitted.kind === "customApi") assertAuthoringAllowed(isAdmin, customWidgetsEnabled);
continue;
}
const wasCustomWidget = stored.kind === "customApi";
const isCustomWidget = submitted.kind === "customApi";
if (wasCustomWidget !== isCustomWidget) {
if (isCustomWidget) assertAuthoringAllowed(isAdmin, customWidgetsEnabled);
else if (!isAdmin) throwAdminRequired();
continue;
}
if (
wasCustomWidget &&
!isDeepStrictEqual(normalizeCustomWidgetOptions(submitted.options), normalizeCustomWidgetOptions(stored.options))
) {
assertAuthoringAllowed(isAdmin, customWidgetsEnabled);
}
}
};
export const throwIfCustomWidgetBoardDuplicationForbidden = (
isAdmin: boolean,
customWidgetsEnabled: boolean,
items: readonly Pick<BoardPlacement, "kind">[],
) => {
if (items.some((item) => item.kind === "customApi")) assertAuthoringAllowed(isAdmin, customWidgetsEnabled);
};
function normalizeCustomWidgetOptions(options: Record<string, unknown>) {
return {
...options,
configuration:
options.configuration !== null &&
typeof options.configuration === "object" &&
!Array.isArray(options.configuration)
? options.configuration
: {},
configurationVersion:
typeof options.configurationVersion === "number" && Number.isInteger(options.configurationVersion)
? options.configurationVersion
: 1,
refreshInterval: typeof options.refreshInterval === "number" ? options.refreshInterval : 30,
};
}
@@ -0,0 +1,137 @@
import { describe, expect, test } from "vitest";
import {
throwIfCustomWidgetBoardDuplicationForbidden,
throwIfCustomWidgetPlacementChangeForbidden,
} from "../custom-widget-placement-access";
const placement = {
id: "widget-1",
kind: "customApi",
options: {
definitionId: "definition-1",
refreshInterval: 30,
configuration: { server: "primary" },
},
};
describe("Custom Widget placement access", () => {
test("non-admins cannot add a Custom Widget placement", () => {
expect(() =>
throwIfCustomWidgetPlacementChangeForbidden({
isAdmin: false,
customWidgetsEnabled: true,
submittedItems: [{ ...placement, options: { ...placement.options, configurationVersion: 1 } }],
storedItems: [],
}),
).toThrowError("Only administrators can add or configure Custom Widgets");
});
test.each([
["definition", { ...placement, options: { ...placement.options, definitionId: "definition-2" } }],
["refresh interval", { ...placement, options: { ...placement.options, refreshInterval: 60 } }],
[
"option configuration",
{ ...placement, options: { ...placement.options, configuration: { server: "secondary" } } },
],
["widget kind", { ...placement, kind: "weather" }],
])("non-admins cannot change an existing Custom Widget %s", (_label, submitted) => {
expect(() =>
throwIfCustomWidgetPlacementChangeForbidden({
isAdmin: false,
customWidgetsEnabled: true,
submittedItems: [submitted],
storedItems: [placement],
}),
).toThrowError("Only administrators can add or configure Custom Widgets");
});
test("non-admins may move, resize and change presentation for an existing placement", () => {
const submitted = {
...placement,
layouts: [{ xOffset: 2, yOffset: 4, width: 6, height: 3 }],
advancedOptions: { title: "Status", customCssClasses: ["wide"], borderColor: "#fff" },
};
expect(() =>
throwIfCustomWidgetPlacementChangeForbidden({
isAdmin: false,
customWidgetsEnabled: true,
submittedItems: [submitted],
storedItems: [placement],
}),
).not.toThrow();
});
test("non-admins may remove an existing placement", () => {
expect(() =>
throwIfCustomWidgetPlacementChangeForbidden({
isAdmin: false,
customWidgetsEnabled: true,
submittedItems: [],
storedItems: [placement],
}),
).not.toThrow();
});
test("admins may create and reconfigure placements", () => {
expect(() =>
throwIfCustomWidgetPlacementChangeForbidden({
isAdmin: true,
customWidgetsEnabled: true,
submittedItems: [{ ...placement, options: { definitionId: "definition-2" } }],
storedItems: [],
}),
).not.toThrow();
});
test("duplicating a board with Custom Widgets requires admin", () => {
expect(() => throwIfCustomWidgetBoardDuplicationForbidden(false, true, [placement])).toThrowError(
"Only administrators can add or configure Custom Widgets",
);
expect(() => throwIfCustomWidgetBoardDuplicationForbidden(true, true, [placement])).not.toThrow();
expect(() => throwIfCustomWidgetBoardDuplicationForbidden(false, true, [{ kind: "weather" }])).not.toThrow();
});
test("treats missing persisted v2 defaults as equivalent during presentation-only edits", () => {
expect(() =>
throwIfCustomWidgetPlacementChangeForbidden({
isAdmin: false,
customWidgetsEnabled: true,
submittedItems: [placement],
storedItems: [
{
id: placement.id,
kind: placement.kind,
options: {
definitionId: placement.options.definitionId,
refreshInterval: placement.options.refreshInterval,
configuration: placement.options.configuration,
},
},
],
}),
).not.toThrow();
});
test("blocks authoring but still allows removal while the emergency switch is off", () => {
expect(() =>
throwIfCustomWidgetPlacementChangeForbidden({
isAdmin: true,
customWidgetsEnabled: false,
submittedItems: [placement],
storedItems: [],
}),
).toThrowError("temporarily disabled");
expect(() =>
throwIfCustomWidgetPlacementChangeForbidden({
isAdmin: false,
customWidgetsEnabled: false,
submittedItems: [],
storedItems: [placement],
}),
).not.toThrow();
expect(() => throwIfCustomWidgetBoardDuplicationForbidden(true, false, [placement])).toThrowError(
"temporarily disabled",
);
});
});
@@ -4,6 +4,8 @@ import type { RedisClient } from "@homarr/core/infrastructure/redis";
import type { CustomWidgetSecretKind } from "@homarr/custom-widgets/core";
import type { CustomWidgetSource } from "@homarr/custom-widgets/core";
import { useProcessLocalCustomWidgetState } from "../../custom-widget-state-mode";
const CONFIGURATION_REQUEST_TTL_MS = 10 * 60_000;
const CONFIGURATION_REQUEST_PREFIX = "custom-widget:configuration-request:";
const CONFIGURATION_REQUEST_LOCK_PREFIX = "custom-widget:configuration-request-lock:";
@@ -26,7 +28,7 @@ const localLocks = new Set<string>();
let redis: RedisClient | undefined;
function getRedis() {
if (process.env.CI !== undefined || process.env.NODE_ENV === "test") return undefined;
if (useProcessLocalCustomWidgetState()) return undefined;
redis ??= createRedisClient();
return redis;
}
@@ -12,8 +12,9 @@ import {
customWidgetUpdateSchema,
} from "@homarr/custom-widgets/core";
import { createTRPCRouter, permissionRequiredProcedure } from "../../trpc";
import { createTRPCRouter } from "../../trpc";
import { insertCustomWidgetDefinition } from "./definition-insert";
import { customWidgetAdminProcedure } from "./feature-flags";
import { managementQueryProcedures } from "./management-queries";
import { metadataProcedures } from "./metadata-procedures";
import { previewActionProcedures } from "./preview-action-procedures";
@@ -30,24 +31,17 @@ import { assertSecretSources, hasSameSecretBinding, requiredSecretKinds } from "
import { secretProcedures } from "./secret-procedures";
import { workshopProcedures } from "./workshop-procedures";
const manageProcedure = permissionRequiredProcedure.requiresPermission("custom-widget-manage");
const logger = createLogger({ module: "custom-widget" });
export const customWidgetRouter = createTRPCRouter({
...metadataProcedures,
...managementQueryProcedures,
create: manageProcedure
create: customWidgetAdminProcedure
.meta({ mcp: { enabled: true, description: "Create one validated Custom JSX widget." } })
.input(customWidgetCreateSchema)
.mutation(async ({ ctx, input }) => {
const { secrets, ...candidate } = input;
if (secrets.length > 0 && !ctx.session.user.permissions.includes("custom-widget-secret-write")) {
throw new TRPCError({
code: "FORBIDDEN",
message: "Writing custom widget secrets requires dedicated permission",
});
}
const definition = customWidgetDefinitionSchema.parse(candidate);
assertSecretSources(definition.sources, secrets);
const id = await insertCustomWidgetDefinition(ctx.db, definition, ctx.session.user.id, secrets);
@@ -55,7 +49,7 @@ export const customWidgetRouter = createTRPCRouter({
return { id };
}),
update: manageProcedure
update: customWidgetAdminProcedure
.meta({ mcp: { enabled: true, description: "Update one Custom JSX widget." } })
.input(customWidgetUpdateSchema)
.mutation(async ({ ctx, input }) => {
@@ -66,12 +60,6 @@ export const customWidgetRouter = createTRPCRouter({
const current = parseStoredCustomWidgetDefinition(existing);
const { id, secrets, ...changes } = input;
if (secrets?.length && !ctx.session.user.permissions.includes("custom-widget-secret-write")) {
throw new TRPCError({
code: "FORBIDDEN",
message: "Writing custom widget secrets requires dedicated permission",
});
}
const definition = customWidgetDefinitionSchema.parse({ ...current, ...changes });
if (secrets) assertSecretSources(definition.sources, secrets);
const definitionChanges = { ...serializeCustomWidgetDefinition(definition), updatedAt: new Date() };
@@ -194,7 +182,7 @@ export const customWidgetRouter = createTRPCRouter({
...secretProcedures,
...workshopProcedures,
toggleEnabled: manageProcedure
toggleEnabled: customWidgetAdminProcedure
.input(z.object({ id: z.string(), enabled: z.boolean() }))
.mutation(async ({ ctx, input }) => {
if (input.enabled) {
@@ -216,7 +204,7 @@ export const customWidgetRouter = createTRPCRouter({
.where(eq(customWidgetDefinitions.id, input.id));
}),
delete: manageProcedure
delete: customWidgetAdminProcedure
.meta({ mcp: { enabled: true, description: "Delete one Custom JSX widget." } })
.input(z.object({ id: z.string() }))
.mutation(async ({ ctx, input }) => {
@@ -224,7 +212,7 @@ export const customWidgetRouter = createTRPCRouter({
logger.info("Deleted custom widget definition", { id: input.id });
}),
duplicate: manageProcedure.input(z.object({ id: z.string() })).mutation(async ({ ctx, input }) => {
duplicate: customWidgetAdminProcedure.input(z.object({ id: z.string() })).mutation(async ({ ctx, input }) => {
const existing = await ctx.db.query.customWidgetDefinitions.findFirst({
where: eq(customWidgetDefinitions.id, input.id),
});
@@ -0,0 +1,32 @@
import { TRPCError } from "@trpc/server";
import { env } from "../../env";
import { permissionRequiredProcedure } from "../../trpc";
export function assertCustomWidgetsEnabled(): void {
// Environment validation is intentionally skipped in some build and test
// processes, where unset defaulted values are exposed as undefined.
if (env.CUSTOM_WIDGETS_ENABLED !== false) return;
throw new TRPCError({
code: "SERVICE_UNAVAILABLE",
message: "Custom Widgets are temporarily disabled by the server administrator",
});
}
export function assertWorkshopEnabled(): void {
if (env.WORKSHOP_ENABLED !== false) return;
throw new TRPCError({
code: "SERVICE_UNAVAILABLE",
message: "Workshop is temporarily disabled by the server administrator",
});
}
export const customWidgetAdminProcedure = permissionRequiredProcedure.requiresPermission("admin").use(({ next }) => {
assertCustomWidgetsEnabled();
return next();
});
export const workshopAdminProcedure = customWidgetAdminProcedure.use(({ next }) => {
assertWorkshopEnabled();
return next();
});
@@ -1,5 +1,3 @@
import { parse as parseSuperJson } from "superjson";
import type { legacyCustomWidgetDefinitions } from "@homarr/db/schema";
import { buildCustomWidgetAiPrompt } from "@homarr/custom-widgets/authoring-prompt";
@@ -13,14 +11,17 @@ export function buildLegacyCustomWidgetMigrationPrompt(
$schema: "homarr-custom-widget-v1",
name: definition.name,
description: definition.description,
iconUrl: definition.iconUrl,
iconUrl: definition.iconUrl ? redactLegacyUrl(definition.iconUrl) : null,
url: redactLegacyUrl(definition.url),
authType: definition.authType,
headerName: definition.headerName,
method: definition.method,
requestBody: redactLegacyRequestBody(definition.requestBody),
displayType: definition.displayType,
displayConfig: parseLegacyDisplayConfig(definition.displayConfig),
displayConfig: {
migrationNote:
"The preserved v1 display configuration was intentionally omitted because legacy free-text fields may contain credentials. Reconstruct it from the display type and visible behavior.",
},
configuredSecretKinds,
};
return buildCustomWidgetAiPrompt(
@@ -69,11 +70,3 @@ function redactAllValues(value: unknown): unknown {
if (value === null) return null;
return "[REDACTED VALUE]";
}
function parseLegacyDisplayConfig(value: string): unknown {
try {
return parseSuperJson(value) as unknown;
} catch {
return { migrationNote: "The stored v1 display configuration could not be decoded.", raw: value.slice(0, 4_000) };
}
}
@@ -6,8 +6,8 @@ import { eq, or } from "@homarr/db";
import { boards, customWidgetDefinitions, legacyCustomWidgetDefinitions } from "@homarr/db/schema";
import { collectCustomWidgetRequestReferences } from "@homarr/custom-widgets/core";
import { permissionRequiredProcedure, protectedProcedure } from "../../trpc";
import { throwIfActionForbiddenAsync } from "../board/board-access";
import { customWidgetAdminProcedure } from "./feature-flags";
import { parseStoredCustomWidgetDefinition } from "./stored-definition";
import { executeCustomWidgetRequest } from "./request-executor";
import {
@@ -26,10 +26,8 @@ import {
mapLegacyCustomWidgetListItem,
} from "./management-query-mappers";
const manageProcedure = permissionRequiredProcedure.requiresPermission("custom-widget-manage");
export const managementQueryProcedures = {
list: manageProcedure
list: customWidgetAdminProcedure
.meta({ mcp: { enabled: true, description: "List all Custom JSX widgets." } })
.query(async ({ ctx }) => {
const [definitions, legacyDefinitions] = await Promise.all([
@@ -43,11 +41,12 @@ export const managementQueryProcedures = {
}),
]);
const current = definitions.map(mapCustomWidgetListItem);
const legacy = legacyDefinitions.map(mapLegacyCustomWidgetListItem);
const currentIds = new Set(definitions.map(({ id }) => id));
const legacy = legacyDefinitions.filter(({ id }) => !currentIds.has(id)).map(mapLegacyCustomWidgetListItem);
return [...current, ...legacy].toSorted((left, right) => left.name.localeCompare(right.name));
}),
legacyMigrationPrompt: manageProcedure
legacyMigrationPrompt: customWidgetAdminProcedure
.meta({
mcp: {
enabled: true,
@@ -72,7 +71,7 @@ export const managementQueryProcedures = {
};
}),
get: manageProcedure
get: customWidgetAdminProcedure
.meta({ mcp: { enabled: true, description: "Get one Custom JSX widget without secret values." } })
.input(z.object({ id: z.string() }))
.query(async ({ ctx, input }) => {
@@ -96,7 +95,7 @@ export const managementQueryProcedures = {
};
}),
available: protectedProcedure
available: customWidgetAdminProcedure
.input(z.object({ boardId: z.string(), currentId: z.string().optional() }))
.query(async ({ ctx, input }) => {
await throwIfActionForbiddenAsync(ctx, eq(boards.id, input.boardId), "modify");
@@ -115,7 +114,7 @@ export const managementQueryProcedures = {
return [...available, mapLegacyAvailableCustomWidget(legacy)];
}),
optionRequest: protectedProcedure
optionRequest: customWidgetAdminProcedure
.input(
z.object({
boardId: z.string(),
@@ -139,16 +138,10 @@ export const managementQueryProcedures = {
await throwIfActionForbiddenAsync(ctx, eq(boards.id, input.boardId), request.permission);
const source = definition.sources[request.source];
if (!source) throw new TRPCError({ code: "NOT_FOUND", message: "Option query source not found" });
const release = await acquireCustomWidgetRequestLimit({
category: "query",
userId: ctx.session.user.id,
itemId: `configuration:${input.boardId}`,
definitionId: input.definitionId,
});
try {
const values = resolveOptionRequestValues(request, input.params);
const authType = typeof source.auth === "string" ? source.auth : source.auth.type;
const response = await executeCustomWidgetRequest({
const values = resolveOptionRequestValues(request, input.params);
const authType = typeof source.auth === "string" ? source.auth : source.auth.type;
const response = await executeCustomWidgetRequest(
{
baseUrl: source.baseUrl,
targetUrl: renderRequestTarget(source.baseUrl, request, values),
method: request.method,
@@ -173,16 +166,23 @@ export const managementQueryProcedures = {
kind: "query",
cacheKey: `custom-widget:options:${input.definitionId}:${getCustomWidgetCacheVersion(stored)}:${request.id}:${hashRuntimeParams(values)}`,
cacheTtlSeconds: request.cacheSeconds ?? 30,
});
return {
ok: response.ok,
status: response.status,
data: response.data,
error: response.ok ? undefined : `HTTP ${response.status}: ${response.statusText}`,
};
} finally {
await release();
}
},
{
acquireRequestLimit: () =>
acquireCustomWidgetRequestLimit({
category: "query",
userId: ctx.session.user.id,
itemId: `configuration:${input.boardId}`,
definitionId: input.definitionId,
}),
},
);
return {
ok: response.ok,
status: response.status,
data: response.data,
error: response.ok ? undefined : `HTTP ${response.status}: ${response.statusText}`,
};
}),
};
@@ -20,6 +20,7 @@ export function mapCustomWidgetListItem(definition: StoredDefinition & { secrets
const result = safeParseStoredCustomWidgetDefinition(definition);
if (!result.success) {
logger.warn("Skipped parsing invalid custom widget definition", {
event: "custom_widget_definition_invalid",
id: definition.id,
issueCount: result.issues.length,
});
@@ -88,7 +89,11 @@ export function mapLegacyCustomWidgetListItem(definition: LegacyDefinition) {
export function mapAvailableCustomWidget(definition: StoredDefinition) {
const result = safeParseStoredCustomWidgetDefinition(definition);
if (!result.success) {
logger.warn("Excluded invalid custom widget definition from board picker", { id: definition.id });
logger.warn("Excluded invalid custom widget definition from board picker", {
event: "custom_widget_definition_invalid",
id: definition.id,
surface: "board-picker",
});
return [];
}
@@ -4,15 +4,14 @@ import { CUSTOM_WIDGET_MCP_AUTHORING_PROMPT } from "@homarr/custom-widgets/autho
import { getCustomWidgetSkill } from "@homarr/custom-widgets/authoring-resources";
import { customWidgetImportSchema, getCustomWidgetJsonSchema } from "@homarr/custom-widgets/core";
import { permissionRequiredProcedure, publicProcedure } from "../../trpc";
import { customWidgetAdminProcedure } from "./feature-flags";
const manageProcedure = permissionRequiredProcedure.requiresPermission("custom-widget-manage");
export const metadataProcedures = {
schema: publicProcedure
schema: customWidgetAdminProcedure
.meta({ mcp: { enabled: true, description: "Get the current Custom JSX widget JSON Schema." } })
.query(() => getCustomWidgetJsonSchema()),
getAuthoringPrompt: publicProcedure
getAuthoringPrompt: customWidgetAdminProcedure
.meta({ mcp: { enabled: true, description: "Get the current Custom Widget authoring instructions." } })
.query(() => ({
version: 2,
@@ -25,11 +24,11 @@ export const metadataProcedures = {
httpResources: ["/api/custom-widgets/schema", "/api/custom-widgets/components", "/api/custom-widgets/skill"],
})),
getSkill: publicProcedure
getSkill: customWidgetAdminProcedure
.meta({ mcp: { enabled: true, description: "Get the portable Homarr Custom Widget skill." } })
.query(() => getCustomWidgetSkill()),
validate: manageProcedure
validate: customWidgetAdminProcedure
.meta({ mcp: { enabled: true, description: "Validate one Custom JSX widget without saving it." } })
.input(z.object({ widget: z.unknown() }))
.query(({ input }) => {
@@ -1,7 +1,7 @@
import { TRPCError } from "@trpc/server";
import { z } from "zod/v4";
import { permissionRequiredProcedure } from "../../trpc";
import { customWidgetAdminProcedure } from "./feature-flags";
import {
getPreviewRequestSource,
previewSessionRequestSchema,
@@ -12,10 +12,8 @@ import { renderRequestBody, renderRequestTarget, resolveCustomWidgetRequestValue
import { acquireCustomWidgetRequestLimit } from "./request-limits";
import { getPreviewSession } from "./preview-sessions";
const manageProcedure = permissionRequiredProcedure.requiresPermission("custom-widget-manage");
export const previewActionProcedures = {
previewAction: manageProcedure
previewAction: customWidgetAdminProcedure
.meta({
mcp: { enabled: true, description: "Simulate or run one named action in a custom widget preview session." },
})
@@ -46,15 +44,9 @@ export const previewActionProcedures = {
if ((request.confirmation || request.method === "DELETE") && input.confirmed !== true) {
throw new TRPCError({ code: "PRECONDITION_FAILED", message: "This action requires confirmation" });
}
const release = await acquireCustomWidgetRequestLimit({
category: request.method === "DELETE" ? "delete" : "action",
userId: ctx.session.user.id,
itemId: `preview:${session.id}`,
definitionId: session.definitionId ?? `preview:${session.id}`,
});
const startedAt = Date.now();
try {
const response = await executeCustomWidgetRequest({
const response = await executeCustomWidgetRequest(
{
baseUrl: resolved.source.baseUrl,
targetUrl,
method: request.method,
@@ -63,31 +55,38 @@ export const previewActionProcedures = {
auth: request.auth === "none" ? undefined : resolved.auth,
networkScope: resolved.source.networkScope,
kind: "action",
});
if (response.ok && request.invalidates?.length) {
invalidateCustomWidgetResponseCache(
request.invalidates.map((requestId) => `custom-jsx:preview:${session.id}:${requestId}:`),
);
}
await recordPreviewJournal(session, {
requestId: request.id,
kind: "action",
method: request.method,
path: request.path,
status: response.status,
durationMs: Date.now() - startedAt,
simulated: false,
});
return {
ok: response.ok,
status: response.status,
statusText: response.statusText,
data: response.data,
error: response.ok ? undefined : `HTTP ${response.status}: ${response.statusText}`,
simulated: false as const,
};
} finally {
await release();
},
{
acquireRequestLimit: () =>
acquireCustomWidgetRequestLimit({
category: request.method === "DELETE" ? "delete" : "action",
userId: ctx.session.user.id,
itemId: `preview:${session.id}`,
definitionId: session.definitionId ?? `preview:${session.id}`,
}),
},
);
if (response.ok && request.invalidates?.length) {
await invalidateCustomWidgetResponseCache(
request.invalidates.map((requestId) => `custom-jsx:preview:${session.id}:${requestId}:`),
);
}
await recordPreviewJournal(session, {
requestId: request.id,
kind: "action",
method: request.method,
path: request.path,
status: response.status,
durationMs: Date.now() - startedAt,
simulated: false,
});
return {
ok: response.ok,
status: response.status,
statusText: response.statusText,
data: response.data,
error: response.ok ? undefined : `HTTP ${response.status}: ${response.statusText}`,
simulated: false as const,
};
}),
};
@@ -12,13 +12,11 @@ import {
import { eq } from "@homarr/db";
import { customWidgetDefinitions } from "@homarr/db/schema";
import { permissionRequiredProcedure } from "../../trpc";
import { customWidgetAdminProcedure } from "./feature-flags";
import { createPreviewSession, getPreviewSession } from "./preview-sessions";
import { hasSameSecretBinding, requiredSecretKinds } from "./secret-policy";
import { parseStoredCustomWidgetDefinition } from "./stored-definition";
const manageProcedure = permissionRequiredProcedure.requiresPermission("custom-widget-manage");
const previewCreateInputSchema = z.object({
definition: customWidgetDefinitionSchema,
secrets: customWidgetSecretsInputSchema.default([]),
@@ -26,13 +24,10 @@ const previewCreateInputSchema = z.object({
options: z.record(z.string(), z.unknown()).optional(),
});
const previewCreateProcedure = manageProcedure
const previewCreateProcedure = customWidgetAdminProcedure
.meta({ mcp: { enabled: true, description: "Create a short-lived preview session for one unsaved custom widget." } })
.input(previewCreateInputSchema)
.mutation(async ({ ctx, input }) => {
if (input.secrets.length > 0 && !ctx.session.user.permissions.includes("custom-widget-secret-write")) {
throw new TRPCError({ code: "FORBIDDEN", message: "Writing preview secrets requires dedicated permission" });
}
const options = input.options ?? getCustomWidgetDefaultOptions(input.definition.options);
const optionIssues = validateCustomWidgetOptions(input.definition.options, options);
if (optionIssues.length > 0) {
@@ -62,7 +57,7 @@ const previewCreateProcedure = manageProcedure
);
if (missingReplacement) {
throw new TRPCError({
code: ctx.session.user.permissions.includes("custom-widget-secret-write") ? "BAD_REQUEST" : "FORBIDDEN",
code: "BAD_REQUEST",
message: "Source security settings changed; re-enter its credentials to preview this definition",
});
}
@@ -123,7 +118,7 @@ const previewCreateProcedure = manageProcedure
export const previewBaseProcedures = {
previewCreate: previewCreateProcedure,
previewGet: manageProcedure.input(z.object({ sessionId: z.string() })).query(async ({ ctx, input }) => {
previewGet: customWidgetAdminProcedure.input(z.object({ sessionId: z.string() })).query(async ({ ctx, input }) => {
const session = await getPreviewSession(input.sessionId, ctx.session.user.id);
return {
id: session.id,
@@ -1,7 +1,7 @@
import { TRPCError } from "@trpc/server";
import { z } from "zod/v4";
import { permissionRequiredProcedure } from "../../trpc";
import { customWidgetAdminProcedure } from "./feature-flags";
import {
getPreviewRequestSource,
previewSessionRequestSchema,
@@ -9,14 +9,13 @@ import {
resolvePreviewRequestParams,
} from "./preview-procedure-helpers";
import { executeCustomWidgetRequest } from "./request-executor";
import { invalidateCustomWidgetResponseCache } from "./request-executor";
import { hashRuntimeParams, renderRequestBody, renderRequestTarget } from "./request-manifest";
import { acquireCustomWidgetRequestLimit } from "./request-limits";
import { getPreviewJournal, getPreviewSession, setPreviewSessionLiveActions } from "./preview-sessions";
const manageProcedure = permissionRequiredProcedure.requiresPermission("custom-widget-manage");
export const previewQueryProcedures = {
previewQuery: manageProcedure
previewQuery: customWidgetAdminProcedure
.meta({
mcp: {
enabled: true,
@@ -35,15 +34,9 @@ export const previewQueryProcedures = {
const params = resolvePreviewRequestParams(request, session.options, input.params);
const targetUrl = renderRequestTarget(resolved.source.baseUrl, request, params);
const body = renderRequestBody(request, params);
const release = await acquireCustomWidgetRequestLimit({
category: "query",
userId: ctx.session.user.id,
itemId: `preview:${session.id}`,
definitionId: session.definitionId ?? `preview:${session.id}`,
});
const startedAt = Date.now();
try {
const response = await executeCustomWidgetRequest({
const response = await executeCustomWidgetRequest(
{
baseUrl: resolved.source.baseUrl,
targetUrl,
method: request.method,
@@ -54,35 +47,75 @@ export const previewQueryProcedures = {
kind: "query",
cacheKey: `custom-jsx:preview:${session.id}:${request.id}:${hashRuntimeParams(params)}`,
cacheTtlSeconds: request.cacheSeconds,
});
await recordPreviewJournal(session, {
requestId: request.id,
kind: "query",
method: request.method,
path: request.path,
status: response.status,
durationMs: Date.now() - startedAt,
simulated: false,
});
return {
ok: response.ok,
status: response.status,
statusText: response.statusText,
data: response.data,
error: response.ok ? undefined : `HTTP ${response.status}: ${response.statusText}`,
};
},
{
acquireRequestLimit: () =>
acquireCustomWidgetRequestLimit({
category: "query",
userId: ctx.session.user.id,
itemId: `preview:${session.id}`,
definitionId: session.definitionId ?? `preview:${session.id}`,
}),
},
);
await recordPreviewJournal(session, {
requestId: request.id,
kind: "query",
method: request.method,
path: request.path,
status: response.status,
durationMs: Date.now() - startedAt,
simulated: false,
});
return {
ok: response.ok,
status: response.status,
statusText: response.statusText,
data: response.data,
error: response.ok ? undefined : `HTTP ${response.status}: ${response.statusText}`,
};
}),
previewRefresh: customWidgetAdminProcedure
.input(
z.object({
sessionId: z.string().min(1),
requestIds: z.array(z.string().min(1).max(64)).max(64).default([]),
all: z.boolean().default(false),
}),
)
.mutation(async ({ ctx, input }) => {
const session = await getPreviewSession(input.sessionId, ctx.session.user.id);
const queryRequestIds = Object.entries(session.requests).flatMap(([requestId, request]) =>
request.kind === "query" ? [requestId] : [],
);
const requested = new Set(input.all ? queryRequestIds : input.requestIds);
const requestIds = queryRequestIds.filter((requestId) => requested.has(requestId));
if (requestIds.length === 0) return { requestIds };
const release = await acquireCustomWidgetRequestLimit({
category: "query",
userId: ctx.session.user.id,
itemId: `preview:${session.id}`,
definitionId: session.definitionId ?? `preview:${session.id}`,
});
try {
await invalidateCustomWidgetResponseCache(
requestIds.map((requestId) => `custom-jsx:preview:${session.id}:${requestId}:`),
);
} finally {
await release();
}
return { requestIds };
}),
setPreviewLiveActions: manageProcedure
setPreviewLiveActions: customWidgetAdminProcedure
.input(z.object({ sessionId: z.string().min(1), enabled: z.boolean() }))
.mutation(async ({ ctx, input }) =>
setPreviewSessionLiveActions(input.sessionId, ctx.session.user.id, input.enabled),
),
previewJournal: manageProcedure
previewJournal: customWidgetAdminProcedure
.meta({
mcp: {
enabled: true,
@@ -10,6 +10,7 @@ import type {
PreviewSessionStore,
} from "@homarr/custom-widgets/server";
import { useProcessLocalCustomWidgetState } from "../../custom-widget-state-mode";
import { toTrpcError } from "./domain-error";
const SESSION_PREFIX = "custom-widget:preview-session:";
@@ -69,7 +70,7 @@ class RedisPreviewSessionStore implements PreviewSessionStore {
let service: CustomWidgetPreviewSessionService | undefined;
function getService() {
if (service) return service;
const useLocal = process.env.CI !== undefined || process.env.NODE_ENV === "test";
const useLocal = useProcessLocalCustomWidgetState();
service = new CustomWidgetPreviewSessionService({
createId,
encrypt: encryptSecret,
@@ -1,10 +1,11 @@
import { TRPCError } from "@trpc/server";
import { createLogger } from "@homarr/core/infrastructure/logs";
import {
assertJsonBudget as assertDomainJsonBudget,
assertSafeStaticHeaders as assertDomainSafeStaticHeaders,
classifyAddress,
executeCustomWidgetRequest as executeDomainRequest,
invalidateCustomWidgetResponseCache as invalidateDomainResponseCache,
MAX_REQUEST_BODY_BYTES,
MAX_RESPONSE_BODY_BYTES,
MAX_RESPONSE_JSON_DEPTH,
@@ -14,8 +15,11 @@ import {
validateCustomWidgetUrl as validateDomainUrl,
} from "@homarr/custom-widgets/server";
import type { CustomWidgetHttpRequest, CustomWidgetHttpResponse } from "@homarr/custom-widgets/server";
import { CustomWidgetDomainError } from "@homarr/custom-widgets/server";
import { toTrpcError } from "./domain-error";
import { assertCustomWidgetsEnabled } from "./feature-flags";
import { invalidateCustomWidgetResponseCache, withCustomWidgetResponseCache } from "./response-cache";
export type {
CustomWidgetAuthConfig,
@@ -32,6 +36,10 @@ export {
const logger = createLogger({ module: "custom-widget:http" });
export interface CustomWidgetRequestExecutionOptions {
acquireRequestLimit?: () => Promise<() => Promise<void>>;
}
export function assertJsonBudget(value: unknown): void {
try {
assertDomainJsonBudget(value);
@@ -72,16 +80,65 @@ export async function resolveAndValidateHost(hostname: string, scope: CustomWidg
}
}
export async function executeCustomWidgetRequest(input: CustomWidgetHttpRequest): Promise<CustomWidgetHttpResponse> {
export async function executeCustomWidgetRequest(
input: CustomWidgetHttpRequest,
options: CustomWidgetRequestExecutionOptions = {},
): Promise<CustomWidgetHttpResponse> {
assertCustomWidgetsEnabled();
try {
return await executeDomainRequest({
...input,
logError: (event) => logger.error("Custom widget request failed", event),
return await withCustomWidgetResponseCache(input, async () => {
const release = await options.acquireRequestLimit?.();
try {
return await executeDomainRequest({
...input,
cacheKey: undefined,
cacheTtlSeconds: undefined,
logError: (event) => {
if (event.reason === "timeout") return;
logger.error("Custom widget request failed", {
event: "custom_widget_request_failed",
...event,
});
},
});
} finally {
await release?.();
}
});
} catch (error) {
toTrpcError(error);
if (error instanceof CustomWidgetDomainError) {
logger.warn("Custom widget request rejected", {
event:
error.reason === "timeout"
? "custom_widget_request_timeout"
: error.code === "FORBIDDEN"
? "custom_widget_network_scope_rejected"
: error.code === "BAD_GATEWAY"
? "custom_widget_upstream_failed"
: "custom_widget_request_rejected",
code: error.code,
origin: safeOrigin(input.baseUrl),
method: input.method,
});
toTrpcError(error);
}
if (error instanceof TRPCError) throw error;
logger.error("Custom widget request failed", {
event: "custom_widget_request_failed",
errorName: "UnexpectedTransportError",
origin: safeOrigin(input.baseUrl),
method: input.method,
});
throw new TRPCError({ code: "BAD_GATEWAY", message: "External request failed" });
}
}
export const invalidateCustomWidgetResponseCache = (prefixes: readonly string[]) =>
invalidateDomainResponseCache(prefixes);
export { invalidateCustomWidgetResponseCache };
function safeOrigin(value: string): string {
try {
return new URL(value).origin;
} catch {
return "invalid";
}
}
@@ -1,9 +1,10 @@
import { createLogger } from "@homarr/core/infrastructure/logs";
import { createRedisClient } from "@homarr/core/infrastructure/redis";
import type { RedisClient } from "@homarr/core/infrastructure/redis";
import { CustomWidgetRequestLimiter } from "@homarr/custom-widgets/server";
import { CustomWidgetDomainError, CustomWidgetRequestLimiter } from "@homarr/custom-widgets/server";
import type { RequestLimitInput, RequestLimitStore } from "@homarr/custom-widgets/server";
import { useProcessLocalCustomWidgetState } from "../../custom-widget-state-mode";
import { toTrpcError } from "./domain-error";
const logger = createLogger({ module: "custom-widget:limits" });
@@ -45,12 +46,13 @@ class RedisRequestLimitStore implements RequestLimitStore {
let limiter: CustomWidgetRequestLimiter | undefined;
function getLimiter() {
if (limiter) return limiter;
const useLocal = process.env.CI !== undefined || process.env.NODE_ENV === "test";
const useLocal = useProcessLocalCustomWidgetState();
const store = useLocal ? undefined : new RedisRequestLimitStore(createRedisClient());
limiter = new CustomWidgetRequestLimiter({
store,
onStoreError: (error) =>
logger.error("Custom widget rate limiter is unavailable", {
event: "custom_widget_rate_limit_store_unavailable",
errorName: error instanceof Error ? error.name : "UnknownError",
}),
});
@@ -70,6 +72,14 @@ export async function acquireCustomWidgetRequestLimit(input: RequestLimitInput):
}
};
} catch (error) {
if (error instanceof CustomWidgetDomainError && error.code === "TOO_MANY_REQUESTS") {
logger.warn("Rejected custom widget request at rate or concurrency limit", {
event: "custom_widget_rate_limit_rejected",
category: input.category,
authenticated: Boolean(input.userId),
retryAfterMs: error.retryAfterMs,
});
}
toTrpcError(error);
}
}
@@ -0,0 +1,296 @@
import { Buffer } from "node:buffer";
import { createHash } from "node:crypto";
import { createLogger } from "@homarr/core/infrastructure/logs";
import { createRedisClient } from "@homarr/core/infrastructure/redis";
import type { RedisClient } from "@homarr/core/infrastructure/redis";
import type { CustomWidgetHttpRequest, CustomWidgetHttpResponse } from "@homarr/custom-widgets/server";
import { useProcessLocalCustomWidgetState } from "../../custom-widget-state-mode";
const CACHE_KEY_PREFIX = "homarr:custom-widget:response:v1:";
const VERSION_KEY_PREFIX = "homarr:custom-widget:response-version:v1:";
const CACHE_INDEX_KEY = "homarr:custom-widget:response-index:v1";
const MAX_CACHE_ENTRIES = 1_000;
const MAX_CACHE_TTL_SECONDS = 3_600;
const MAX_CACHE_VALUE_BYTES = 1024 * 1024 + 1024;
const VERSION_TTL_SECONDS = MAX_CACHE_TTL_SECONDS * 2;
const logger = createLogger({ module: "custom-widget:response-cache" });
interface ResponseCacheStore {
getVersions(namespaces: readonly string[]): Promise<number[]>;
incrementVersion(namespace: string): Promise<void>;
get(key: string): Promise<string | null>;
set(key: string, namespace: string, value: string, ttlSeconds: number): Promise<void>;
}
class RedisResponseCacheStore implements ResponseCacheStore {
public constructor(private readonly redis: RedisClient) {}
public async getVersions(namespaces: readonly string[]): Promise<number[]> {
const values = await this.redis.mget(...namespaces.map(getVersionKey));
return values.map((value) => {
const parsed = Number(value ?? 0);
return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : 0;
});
}
public async incrementVersion(namespace: string): Promise<void> {
const key = getVersionKey(namespace);
await this.redis.multi().incr(key).expire(key, VERSION_TTL_SECONDS).exec();
}
public get(key: string): Promise<string | null> {
return this.redis.get(key);
}
public async set(key: string, _namespace: string, value: string, ttlSeconds: number): Promise<void> {
await this.redis.eval(
`
redis.call("SET", KEYS[1], ARGV[1], "EX", ARGV[2])
redis.call("ZADD", KEYS[2], ARGV[3] + (ARGV[2] * 1000), KEYS[1])
redis.call("ZREMRANGEBYSCORE", KEYS[2], "-inf", ARGV[3])
local count = redis.call("ZCARD", KEYS[2])
local maximum = tonumber(ARGV[4])
if count > maximum then
local victims = redis.call("ZRANGE", KEYS[2], 0, count - maximum - 1)
for _, victim in ipairs(victims) do
redis.call("DEL", victim)
redis.call("ZREM", KEYS[2], victim)
end
end
redis.call("EXPIRE", KEYS[2], ARGV[5])
return 1
`,
2,
key,
CACHE_INDEX_KEY,
value,
ttlSeconds,
Date.now(),
MAX_CACHE_ENTRIES,
VERSION_TTL_SECONDS,
);
}
}
class LocalResponseCacheStore implements ResponseCacheStore {
private readonly versions = new Map<string, number>();
private readonly responses = new Map<string, { namespace: string; value: string; expiresAt: number }>();
public async getVersions(namespaces: readonly string[]): Promise<number[]> {
return namespaces.map((namespace) => this.versions.get(namespace) ?? 0);
}
public async incrementVersion(namespace: string): Promise<void> {
this.versions.set(namespace, (this.versions.get(namespace) ?? 0) + 1);
}
public async get(key: string): Promise<string | null> {
const response = this.responses.get(key);
if (!response) return null;
if (response.expiresAt <= Date.now()) {
this.responses.delete(key);
return null;
}
return response.value;
}
public async set(key: string, namespace: string, value: string, ttlSeconds: number): Promise<void> {
for (const [candidate, response] of this.responses) {
if (response.expiresAt <= Date.now()) this.responses.delete(candidate);
}
while (this.responses.size >= MAX_CACHE_ENTRIES) {
const oldest = this.responses.keys().next().value as string | undefined;
if (!oldest) break;
this.responses.delete(oldest);
}
this.responses.set(key, {
namespace,
value,
expiresAt: Date.now() + ttlSeconds * 1000,
});
}
}
let defaultStore: ResponseCacheStore | undefined;
let defaultController: CustomWidgetResponseCacheController | undefined;
function getDefaultStore(): ResponseCacheStore {
if (defaultStore) return defaultStore;
const useLocal = useProcessLocalCustomWidgetState();
defaultStore = useLocal ? new LocalResponseCacheStore() : new RedisResponseCacheStore(createRedisClient());
return defaultStore;
}
export interface CustomWidgetResponseCacheController {
withCache(
input: CustomWidgetHttpRequest,
execute: () => Promise<CustomWidgetHttpResponse>,
): Promise<CustomWidgetHttpResponse>;
invalidate(prefixes: readonly string[]): Promise<void>;
}
class ResponseCacheController implements CustomWidgetResponseCacheController {
private readonly inFlight = new Map<string, Promise<CustomWidgetHttpResponse>>();
private readonly pendingInvalidations = new Set<string>();
public constructor(private readonly store: ResponseCacheStore) {}
public async withCache(
input: CustomWidgetHttpRequest,
execute: () => Promise<CustomWidgetHttpResponse>,
): Promise<CustomWidgetHttpResponse> {
const ttlSeconds = Math.min(Math.max(input.cacheTtlSeconds ?? 0, 0), MAX_CACHE_TTL_SECONDS);
if (input.kind !== "query" || !input.cacheKey || ttlSeconds <= 0) return execute();
const namespace = getCacheNamespace(input.cacheKey);
if (!namespace) {
logger.warn("Rejected malformed custom widget response cache key", {
event: "custom_widget_cache_key_rejected",
});
return execute();
}
let responseKey: string;
let pending: Promise<CustomWidgetHttpResponse> | undefined;
let cached: CustomWidgetHttpResponse | null = null;
try {
await this.flushPendingInvalidations();
const invalidationNamespaces = getInvalidationNamespaces(namespace);
const versions = await this.store.getVersions(invalidationNamespaces);
responseKey = getResponseKey(input.cacheKey, versions);
pending = this.inFlight.get(responseKey);
if (!pending) {
cached = parseCachedResponse(await this.store.get(responseKey));
if (!cached) pending = this.inFlight.get(responseKey);
}
} catch (error) {
logger.warn("Custom widget response cache unavailable; executing without cache", {
event: "custom_widget_cache_unavailable",
errorName: error instanceof Error ? error.name : "UnknownError",
});
return execute();
}
if (pending) return pending;
if (cached) return cached;
let request: Promise<CustomWidgetHttpResponse>;
request = Promise.resolve()
.then(execute)
.then(async (response) => {
if (!response.ok) return response;
try {
const serialized = JSON.stringify(response);
if (Buffer.byteLength(serialized, "utf8") > MAX_CACHE_VALUE_BYTES) {
logger.warn("Skipped oversized custom widget response cache entry", {
event: "custom_widget_cache_entry_rejected",
cacheNamespace: namespace,
});
return response;
}
await this.store.set(responseKey, namespace, serialized, ttlSeconds);
} catch (error) {
logger.warn("Failed to store custom widget response cache entry", {
event: "custom_widget_cache_write_failed",
errorName: error instanceof Error ? error.name : "UnknownError",
});
}
return response;
})
.finally(() => {
if (this.inFlight.get(responseKey) === request) this.inFlight.delete(responseKey);
});
this.inFlight.set(responseKey, request);
return request;
}
public async invalidate(prefixes: readonly string[]): Promise<void> {
const namespaces = [...new Set(prefixes.filter((prefix) => prefix.length > 0))];
if (namespaces.length === 0) return;
try {
await Promise.all(namespaces.map((namespace) => this.store.incrementVersion(namespace)));
for (const namespace of namespaces) this.pendingInvalidations.delete(namespace);
} catch (error) {
namespaces.forEach((namespace) => this.pendingInvalidations.add(namespace));
logger.error("Failed to invalidate custom widget response cache", {
event: "custom_widget_cache_invalidation_failed",
invalidationCount: namespaces.length,
errorName: error instanceof Error ? error.name : "UnknownError",
});
}
}
private async flushPendingInvalidations(): Promise<void> {
if (this.pendingInvalidations.size === 0) return;
const namespaces = [...this.pendingInvalidations];
await Promise.all(namespaces.map((namespace) => this.store.incrementVersion(namespace)));
namespaces.forEach((namespace) => this.pendingInvalidations.delete(namespace));
}
}
function getDefaultController(): CustomWidgetResponseCacheController {
defaultController ??= new ResponseCacheController(getDefaultStore());
return defaultController;
}
export function createRedisCustomWidgetResponseCache(redis: RedisClient): CustomWidgetResponseCacheController {
return new ResponseCacheController(new RedisResponseCacheStore(redis));
}
export function withCustomWidgetResponseCache(
input: CustomWidgetHttpRequest,
execute: () => Promise<CustomWidgetHttpResponse>,
): Promise<CustomWidgetHttpResponse> {
return getDefaultController().withCache(input, execute);
}
export function invalidateCustomWidgetResponseCache(prefixes: readonly string[]): Promise<void> {
return getDefaultController().invalidate(prefixes);
}
function getCacheNamespace(key: string): string | null {
const separator = key.lastIndexOf(":");
if (separator <= 0 || separator === key.length - 1) return null;
return key.slice(0, separator + 1);
}
function getInvalidationNamespaces(namespace: string): string[] {
const namespaces: string[] = [];
for (let separator = namespace.indexOf(":"); separator >= 0; separator = namespace.indexOf(":", separator + 1)) {
namespaces.push(namespace.slice(0, separator + 1));
}
return namespaces;
}
function getResponseKey(key: string, versions: readonly number[]): string {
return `${CACHE_KEY_PREFIX}${hash(`${versions.join(".")}:${key}`)}`;
}
function getVersionKey(namespace: string): string {
return `${VERSION_KEY_PREFIX}${hash(namespace)}`;
}
function hash(value: string): string {
return createHash("sha256").update(value).digest("hex");
}
function parseCachedResponse(value: string | null): CustomWidgetHttpResponse | null {
if (!value) return null;
try {
const parsed = JSON.parse(value) as Partial<CustomWidgetHttpResponse>;
if (
typeof parsed.ok !== "boolean" ||
typeof parsed.status !== "number" ||
typeof parsed.statusText !== "string" ||
!("data" in parsed)
) {
return null;
}
return parsed as CustomWidgetHttpResponse;
} catch {
return null;
}
}
@@ -11,7 +11,7 @@ import {
} from "@homarr/custom-widgets/core";
import type { CustomWidgetSource } from "@homarr/custom-widgets/core";
import { permissionRequiredProcedure } from "../../trpc";
import { customWidgetAdminProcedure } from "./feature-flags";
import {
createCustomWidgetConfigurationRequest,
getCustomWidgetConfigurationRequestForUser,
@@ -20,9 +20,6 @@ import { assertSecretSources, hasSameSecretBinding, requiredSecretKinds } from "
import { getPreviewSession } from "./preview-sessions";
import { parseStoredCustomWidgetDefinition, serializeCustomWidgetDefinition } from "./stored-definition";
const manageProcedure = permissionRequiredProcedure.requiresPermission("custom-widget-manage");
const secretWriteProcedure = permissionRequiredProcedure.requiresPermission("custom-widget-secret-write");
const secretRequestInputSchema = z
.object({
requestId: z.string().optional(),
@@ -44,7 +41,7 @@ const secretRequestInputSchema = z
});
export const secretProcedures = {
secretSet: secretWriteProcedure
secretSet: customWidgetAdminProcedure
.meta({ mcp: { enabled: true, description: "Set one encrypted secret for a custom widget source." } })
.input(z.object({ definitionId: z.string(), secret: customWidgetSecretInputSchema }))
.mutation(async ({ ctx, input }) => {
@@ -54,30 +51,58 @@ export const secretProcedures = {
if (!existing) throw new TRPCError({ code: "NOT_FOUND" });
const definition = parseStoredCustomWidgetDefinition(existing);
assertSecretSources(definition.sources, [input.secret]);
await ctx.db
.delete(customWidgetSecrets)
.where(
and(
eq(customWidgetSecrets.definitionId, input.definitionId),
eq(customWidgetSecrets.sourceId, input.secret.sourceId),
eq(customWidgetSecrets.kind, input.secret.kind),
),
);
await ctx.db.insert(customWidgetSecrets).values({
const updatedAt = new Date();
const secretRow = {
definitionId: input.definitionId,
sourceId: input.secret.sourceId,
kind: input.secret.kind,
encryptedValue: encryptSecret(input.secret.value),
updatedAt: new Date(),
updatedAt,
};
await handleTransactionsAsync(ctx.db, {
async handleAsync(db, schema) {
await db.transaction(async (transaction) => {
await transaction
.delete(schema.customWidgetSecrets)
.where(
and(
eq(schema.customWidgetSecrets.definitionId, input.definitionId),
eq(schema.customWidgetSecrets.sourceId, input.secret.sourceId),
eq(schema.customWidgetSecrets.kind, input.secret.kind),
),
);
await transaction.insert(schema.customWidgetSecrets).values(secretRow);
await transaction
.update(schema.customWidgetDefinitions)
.set({ updatedAt })
.where(eq(schema.customWidgetDefinitions.id, input.definitionId));
});
},
handleSync(db) {
db.transaction((transaction) => {
transaction
.delete(customWidgetSecrets)
.where(
and(
eq(customWidgetSecrets.definitionId, input.definitionId),
eq(customWidgetSecrets.sourceId, input.secret.sourceId),
eq(customWidgetSecrets.kind, input.secret.kind),
),
)
.run();
transaction.insert(customWidgetSecrets).values(secretRow).run();
transaction
.update(customWidgetDefinitions)
.set({ updatedAt })
.where(eq(customWidgetDefinitions.id, input.definitionId))
.run();
});
},
});
await ctx.db
.update(customWidgetDefinitions)
.set({ updatedAt: new Date() })
.where(eq(customWidgetDefinitions.id, input.definitionId));
return { sourceId: input.secret.sourceId, kind: input.secret.kind, isSet: true };
}),
sourceConfigure: manageProcedure
sourceConfigure: customWidgetAdminProcedure
.meta({ mcp: { enabled: true, description: "Configure one custom widget API source and its credentials." } })
.input(
z.object({
@@ -89,9 +114,6 @@ export const secretProcedures = {
}),
)
.mutation(async ({ ctx, input }) => {
if (input.secrets.length > 0 && !ctx.session.user.permissions.includes("custom-widget-secret-write")) {
throw new TRPCError({ code: "FORBIDDEN", message: "Writing source credentials requires dedicated permission" });
}
const stored = await ctx.db.query.customWidgetDefinitions.findFirst({
where: eq(customWidgetDefinitions.id, input.definitionId),
});
@@ -189,7 +211,7 @@ export const secretProcedures = {
};
}),
configurationRequestUser: manageProcedure
configurationRequestUser: customWidgetAdminProcedure
.meta({ mcp: { enabled: true, description: "Create or check a short-lived user source-configuration request." } })
.input(secretRequestInputSchema)
.mutation(async ({ ctx, input }) => {
@@ -203,12 +225,6 @@ export const secretProcedures = {
let source: { id: string; name: string; auth: string | { type: string }; value: CustomWidgetSource } | undefined;
let target: { type: "definition"; id: string } | { type: "preview"; id: string };
if (input.definitionId) {
if (!ctx.session.user.permissions.includes("custom-widget-secret-write")) {
throw new TRPCError({
code: "FORBIDDEN",
message: "Creating a stored credential setup link requires dedicated permission",
});
}
const stored = await ctx.db.query.customWidgetDefinitions.findFirst({
where: eq(customWidgetDefinitions.id, input.definitionId),
});
@@ -258,7 +274,7 @@ export const secretProcedures = {
};
}),
secretClear: secretWriteProcedure
secretClear: customWidgetAdminProcedure
.input(
z.object({ definitionId: z.string(), sourceId: z.string(), kind: z.enum(["apiKey", "username", "password"]) }),
)
@@ -267,19 +283,45 @@ export const secretProcedures = {
where: eq(customWidgetDefinitions.id, input.definitionId),
});
if (!existing) throw new TRPCError({ code: "NOT_FOUND" });
await ctx.db
.delete(customWidgetSecrets)
.where(
and(
eq(customWidgetSecrets.definitionId, input.definitionId),
eq(customWidgetSecrets.sourceId, input.sourceId),
eq(customWidgetSecrets.kind, input.kind),
),
);
await ctx.db
.update(customWidgetDefinitions)
.set({ updatedAt: new Date() })
.where(eq(customWidgetDefinitions.id, input.definitionId));
const updatedAt = new Date();
await handleTransactionsAsync(ctx.db, {
async handleAsync(db, schema) {
await db.transaction(async (transaction) => {
await transaction
.delete(schema.customWidgetSecrets)
.where(
and(
eq(schema.customWidgetSecrets.definitionId, input.definitionId),
eq(schema.customWidgetSecrets.sourceId, input.sourceId),
eq(schema.customWidgetSecrets.kind, input.kind),
),
);
await transaction
.update(schema.customWidgetDefinitions)
.set({ updatedAt })
.where(eq(schema.customWidgetDefinitions.id, input.definitionId));
});
},
handleSync(db) {
db.transaction((transaction) => {
transaction
.delete(customWidgetSecrets)
.where(
and(
eq(customWidgetSecrets.definitionId, input.definitionId),
eq(customWidgetSecrets.sourceId, input.sourceId),
eq(customWidgetSecrets.kind, input.kind),
),
)
.run();
transaction
.update(customWidgetDefinitions)
.set({ updatedAt })
.where(eq(customWidgetDefinitions.id, input.definitionId))
.run();
});
},
});
return { sourceId: input.sourceId, kind: input.kind, isSet: false };
}),
};
@@ -8,10 +8,9 @@ import { customWidgetDefinitionSchema } from "@homarr/custom-widgets/core";
import { and, eq } from "@homarr/db";
import { customWidgetDefinitions } from "@homarr/db/schema";
import { permissionRequiredProcedure } from "../../trpc";
import { customWidgetAdminProcedure } from "./feature-flags";
import { parseStoredCustomWidgetDefinition } from "./stored-definition";
const manageProcedure = permissionRequiredProcedure.requiresPermission("custom-widget-manage");
const logger = createLogger({ module: "custom-widget" });
const getTemplateRevision = (template: string) => createHash("sha256").update(template).digest("hex").slice(0, 16);
@@ -33,7 +32,7 @@ const validateTemplate = (definition: ReturnType<typeof parseStoredCustomWidgetD
};
export const templateProcedures = {
readTemplate: manageProcedure.input(z.object({ id: z.string() })).query(async ({ ctx, input }) => {
readTemplate: customWidgetAdminProcedure.input(z.object({ id: z.string() })).query(async ({ ctx, input }) => {
const definition = await ctx.db.query.customWidgetDefinitions.findFirst({
where: eq(customWidgetDefinitions.id, input.id),
});
@@ -48,7 +47,7 @@ export const templateProcedures = {
};
}),
writeTemplate: manageProcedure
writeTemplate: customWidgetAdminProcedure
.input(
z
.object({ id: z.string(), template: z.string().optional(), templateLines: z.array(z.string()).optional() })
@@ -74,7 +73,7 @@ export const templateProcedures = {
return { id: input.id, template, templateLines: template.split("\n"), revision: getTemplateRevision(template) };
}),
templatePatch: manageProcedure
templatePatch: customWidgetAdminProcedure
.meta({ mcp: { enabled: true, description: "Patch selected JSX template lines using an optimistic revision." } })
.input(
z.object({
@@ -7,16 +7,15 @@ import { eq, handleTransactionsAsync } from "@homarr/db";
import { customWidgetDefinitions, customWidgetSecrets, legacyCustomWidgetDefinitions } from "@homarr/db/schema";
import { customWidgetImportSchema, customWidgetSecretsInputSchema } from "@homarr/custom-widgets/core";
import { permissionRequiredProcedure } from "../../trpc";
import { insertCustomWidgetDefinition } from "./definition-insert";
import { customWidgetAdminProcedure } from "./feature-flags";
import { assertSecretSources, requiredSecretKinds } from "./secret-policy";
import { parseStoredCustomWidgetDefinition, serializeCustomWidgetDefinition } from "./stored-definition";
const manageProcedure = permissionRequiredProcedure.requiresPermission("custom-widget-manage");
const logger = createLogger({ module: "custom-widget" });
export const transferProcedures = {
export: manageProcedure.input(z.object({ id: z.string() })).query(async ({ ctx, input }) => {
export: customWidgetAdminProcedure.input(z.object({ id: z.string() })).query(async ({ ctx, input }) => {
const definition = await ctx.db.query.customWidgetDefinitions.findFirst({
where: eq(customWidgetDefinitions.id, input.id),
});
@@ -24,22 +23,16 @@ export const transferProcedures = {
return parseStoredCustomWidgetDefinition(definition);
}),
import: manageProcedure
import: customWidgetAdminProcedure
.input(z.object({ widget: customWidgetImportSchema, secrets: customWidgetSecretsInputSchema.default([]) }))
.mutation(async ({ ctx, input }) => {
if (input.secrets.length > 0 && !ctx.session.user.permissions.includes("custom-widget-secret-write")) {
throw new TRPCError({
code: "FORBIDDEN",
message: "Writing imported widget secrets requires dedicated permission",
});
}
assertSecretSources(input.widget.sources, input.secrets);
const id = await insertCustomWidgetDefinition(ctx.db, input.widget, ctx.session.user.id, input.secrets);
logger.info("Imported custom widget definition", { id, name: input.widget.name });
return { id };
}),
migrateLegacy: manageProcedure
migrateLegacy: customWidgetAdminProcedure
.meta({
mcp: {
enabled: true,
@@ -55,12 +48,6 @@ export const transferProcedures = {
}),
)
.mutation(async ({ ctx, input }) => {
if (input.secrets.length > 0 && !ctx.session.user.permissions.includes("custom-widget-secret-write")) {
throw new TRPCError({
code: "FORBIDDEN",
message: "Writing migrated widget secrets requires dedicated permission",
});
}
assertSecretSources(input.widget.sources, input.secrets);
const [legacy, current] = await Promise.all([
ctx.db.query.legacyCustomWidgetDefinitions.findFirst({
@@ -108,41 +95,21 @@ export const transferProcedures = {
await database.transaction(async (transaction) => {
await transaction.insert(schema.customWidgetDefinitions).values(definitionRow);
if (secretRows.length > 0) await transaction.insert(schema.customWidgetSecrets).values(secretRows);
await transaction
.delete(schema.legacyCustomWidgetDefinitions)
.where(eq(schema.legacyCustomWidgetDefinitions.id, legacy.id));
});
},
handleSync(database) {
database.transaction((transaction) => {
transaction.insert(customWidgetDefinitions).values(definitionRow).run();
if (secretRows.length > 0) transaction.insert(customWidgetSecrets).values(secretRows).run();
transaction
.delete(legacyCustomWidgetDefinitions)
.where(eq(legacyCustomWidgetDefinitions.id, legacy.id))
.run();
});
},
});
logger.info("Migrated legacy custom widget definition", {
logger.info("Created v2 replacement for preserved legacy custom widget definition", {
id: legacy.id,
preservedSecretCount: preservedSecrets.length,
});
return { id: legacy.id, preservedSecretCount: preservedSecrets.length };
}),
deleteLegacy: manageProcedure
.meta({
mcp: {
enabled: true,
description: "Permanently delete one preserved legacy Custom Widget that will not be migrated.",
},
})
.input(z.object({ id: z.string() }))
.mutation(async ({ ctx, input }) => {
await ctx.db.delete(legacyCustomWidgetDefinitions).where(eq(legacyCustomWidgetDefinitions.id, input.id));
logger.info("Deleted legacy custom widget definition", { id: input.id });
}),
};
function canPreserveLegacySecrets(
@@ -10,15 +10,35 @@ import {
getCustomWidgetSecretRequirements,
getCustomWidgetSourceSetups,
} from "@homarr/custom-widgets/core";
import { createLogger } from "@homarr/core/infrastructure/logs";
import { WorkshopBackend } from "@homarr/workshop/backend";
import { validateWorkshopWidget, WORKSHOP_API_URL } from "@homarr/workshop/schema";
import { resolveHomarrUrlConfig, validateWorkshopWidget } from "@homarr/workshop/schema";
import { permissionRequiredProcedure } from "../../trpc";
import { env } from "../../env";
import { workshopAdminProcedure } from "./feature-flags";
import { insertCustomWidgetDefinition } from "./definition-insert";
import { assertSecretSources } from "./secret-policy";
const manageProcedure = permissionRequiredProcedure.requiresPermission("custom-widget-manage");
const workshop = new WorkshopBackend(process.env.WORKSHOP_API_URL ?? WORKSHOP_API_URL);
const logger = createLogger({ module: "custom-widget:workshop" });
const workshopUrls = resolveHomarrUrlConfig({
homarrWebsiteUrl: env.HOMARR_WEBSITE_URL,
workshopApiUrl: env.WORKSHOP_API_URL,
});
const workshop = new WorkshopBackend(workshopUrls.workshopApiUrl);
function throwWorkshopUnavailable(
message: string,
event: "workshop_widget_lookup_failed" | "workshop_widget_search_failed",
): never {
logger.error(message, {
event,
errorName: "WorkshopBackendError",
});
throw new TRPCError({
code: "BAD_GATEWAY",
message: "Workshop is unavailable",
});
}
async function getWorkshopWidget(submissionId: string) {
try {
@@ -36,11 +56,7 @@ async function getWorkshopWidget(submissionId: string) {
return { submission, widget: validation.data };
} catch (error) {
if (error instanceof TRPCError) throw error;
throw new TRPCError({
code: "BAD_GATEWAY",
message: error instanceof Error ? error.message : "Workshop is unavailable",
cause: error,
});
throwWorkshopUnavailable("Workshop widget lookup failed", "workshop_widget_lookup_failed");
}
}
@@ -59,7 +75,7 @@ const sourceOverridesSchema = z.record(
);
export const workshopProcedures = {
workshopSearch: manageProcedure
workshopSearch: workshopAdminProcedure
.meta({ mcp: { enabled: true, description: "Search Workshop for Custom JSX widgets." } })
.input(workshopSearchInputSchema)
.query(async ({ input }) => {
@@ -86,16 +102,12 @@ export const workshopProcedures = {
reportCount: item.reportCount,
})),
};
} catch (error) {
throw new TRPCError({
code: "BAD_GATEWAY",
message: error instanceof Error ? error.message : "Workshop is unavailable",
cause: error,
});
} catch {
throwWorkshopUnavailable("Workshop widget search failed", "workshop_widget_search_failed");
}
}),
workshopGet: manageProcedure
workshopGet: workshopAdminProcedure
.meta({ mcp: { enabled: true, description: "Get and validate one Workshop Custom JSX widget." } })
.input(z.object({ submissionId: z.string().min(1) }))
.query(async ({ input }) => {
@@ -119,7 +131,7 @@ export const workshopProcedures = {
};
}),
workshopInstall: manageProcedure
workshopInstall: workshopAdminProcedure
.meta({ mcp: { enabled: true, description: "Install one validated Workshop Custom JSX widget." } })
.input(
z.object({
@@ -130,12 +142,6 @@ export const workshopProcedures = {
}),
)
.mutation(async ({ ctx, input }) => {
if (input.secrets.length > 0 && !ctx.session.user.permissions.includes("custom-widget-secret-write")) {
throw new TRPCError({
code: "FORBIDDEN",
message: "Writing Workshop widget credentials requires dedicated permission",
});
}
const { widget } = await getWorkshopWidget(input.submissionId);
const unknownSource = Object.keys(input.sources).find((sourceId) => !widget.sources[sourceId]);
if (unknownSource) {
@@ -1483,6 +1483,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>>,
@@ -9,24 +9,25 @@ import {
users,
} from "@homarr/db/schema";
import { createDb } from "@homarr/db/test";
import { BUNDLED_CUSTOM_WIDGETS } from "@homarr/custom-widgets/core";
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 { serializeCustomWidgetDefinition } from "../../custom-widget/stored-definition";
const userId = createId();
const session = {
user: {
id: userId,
permissions: ["custom-widget-manage", "custom-widget-secret-write"],
permissions: ["admin"],
colorScheme: "light",
},
expires: new Date().toISOString(),
} satisfies Session;
const manageOnlySession = {
const nonAdminSession = {
...session,
user: { ...session.user, permissions: ["custom-widget-manage"] },
user: { ...session.user, permissions: ["board-modify-all"] },
} satisfies Session;
const jellyfin = BUNDLED_CUSTOM_WIDGETS.find(({ id }) => id === "seed-jellyfin")?.widget;
@@ -38,11 +39,11 @@ function createCaller(db: ReturnType<typeof createDb>) {
return customWidgetRouter.createCaller({ db, deviceType: undefined, session });
}
function createManageOnlyCaller(db: ReturnType<typeof createDb>) {
function createNonAdminCaller(db: ReturnType<typeof createDb>) {
return customWidgetRouter.createCaller({
db,
deviceType: undefined,
session: manageOnlySession,
session: nonAdminSession,
});
}
@@ -54,14 +55,24 @@ async function prepareDatabase() {
function rejectSecretInserts(db: ReturnType<typeof createDb>) {
db.run(
sql.raw(`CREATE TRIGGER reject_custom_widget_secret_insert
BEFORE INSERT ON custom_widget_secret
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}`;
@@ -88,13 +99,21 @@ async function insertLegacyJellyfin(db: ReturnType<typeof createDb>) {
const secret = { sourceId: "default", kind: "apiKey" as const, value: "test-secret" };
describe("custom widget definition persistence", () => {
test("atomically replaces a confirmed legacy widget while preserving its stable ID and credential", async () => {
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.findMany()).toHaveLength(0);
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,
@@ -106,6 +125,20 @@ describe("custom widget definition persistence", () => {
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 () => {
@@ -149,6 +182,30 @@ describe("custom widget definition persistence", () => {
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);
@@ -180,6 +237,69 @@ describe("custom widget definition persistence", () => {
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);
@@ -249,7 +369,7 @@ describe("custom widget definition persistence", () => {
};
await expect(
createManageOnlyCaller(db).previewCreate({
createNonAdminCaller(db).previewCreate({
definitionId: created.id,
definition: changedDefinition,
secrets: [],
@@ -260,11 +380,11 @@ describe("custom widget definition persistence", () => {
).resolves.toMatchObject({ success: true });
});
test("clears persisted credentials when a manage-only source edit changes its binding", async () => {
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 createManageOnlyCaller(db).sourceConfigure({
await createCaller(db).sourceConfigure({
definitionId: created.id,
sourceId: "default",
baseUrl: "https://other.example/api",
@@ -284,7 +404,7 @@ describe("custom widget definition persistence", () => {
const caller = createCaller(db);
const created = await caller.create({ ...jellyfin, secrets: [secret] });
await createManageOnlyCaller(db).update({
await createCaller(db).update({
id: created.id,
sources: {
...jellyfin.sources,
@@ -299,12 +419,12 @@ describe("custom widget definition persistence", () => {
).toHaveLength(0);
});
test("requires secret-write permission to create a stored-definition setup link", async () => {
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(
createManageOnlyCaller(db).configurationRequestUser({ definitionId: created.id, sourceId: "default" }),
createNonAdminCaller(db).configurationRequestUser({ definitionId: created.id, sourceId: "default" }),
).rejects.toMatchObject({ code: "FORBIDDEN" });
});
@@ -1,4 +1,5 @@
import { describe, expect, test } from "vitest";
import { stringify as stringifySuperJson } from "superjson";
import { buildLegacyCustomWidgetMigrationPrompt } from "../../custom-widget/legacy-migration";
@@ -9,14 +10,14 @@ describe("legacy custom widget migration prompt", () => {
id: "legacy",
name: "Private service",
description: "Status",
iconUrl: null,
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: JSON.stringify({ json: { type: "singleValue", jsonPath: "$.status" } }),
displayConfig: "corrupted-config-with-display-secret",
enabled: true,
createdAt: new Date(0),
updatedAt: new Date(0),
@@ -32,5 +33,40 @@ describe("legacy custom widget migration prompt", () => {
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>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("<Text>");
expect(prompt).not.toContain("Bearer sk-secret-123456");
expect(prompt).not.toContain("sk-secret-123456");
});
});
@@ -0,0 +1,118 @@
import { createId } from "@homarr/common";
import type * as CustomWidgetServer from "@homarr/custom-widgets/server";
import { beforeEach, describe, expect, test, vi } from "vitest";
const mocks = vi.hoisted(() => ({
executeDomainRequest: vi.fn(async () => ({
ok: true,
status: 200,
statusText: "OK",
data: { value: 42 },
})),
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/custom-widgets/server", async (importOriginal) => {
const actual = await importOriginal<typeof CustomWidgetServer>();
return {
...actual,
executeCustomWidgetRequest: mocks.executeDomainRequest,
};
});
import { executeCustomWidgetRequest } from "../../custom-widget/request-executor";
describe("custom widget request execution limits", () => {
beforeEach(() => {
mocks.executeDomainRequest.mockClear();
mocks.logger.error.mockClear();
});
test("acquires capacity only for a query cache miss", async () => {
const release = vi.fn(async () => undefined);
const acquireRequestLimit = vi.fn(async () => release);
const input = {
baseUrl: "https://example.com",
targetUrl: "https://example.com/status",
method: "GET" as const,
networkScope: "public" as const,
kind: "query" as const,
cacheKey: `custom-jsx:${createId()}:version:status:params`,
cacheTtlSeconds: 60,
};
await executeCustomWidgetRequest(input, { acquireRequestLimit });
await executeCustomWidgetRequest(input, { acquireRequestLimit });
expect(mocks.executeDomainRequest).toHaveBeenCalledOnce();
expect(acquireRequestLimit).toHaveBeenCalledOnce();
expect(release).toHaveBeenCalledOnce();
});
test("keeps every action inside request accounting", async () => {
const release = vi.fn(async () => undefined);
const acquireRequestLimit = vi.fn(async () => release);
const input = {
baseUrl: "https://example.com",
targetUrl: "https://example.com/action",
method: "POST" as const,
networkScope: "public" as const,
kind: "action" as const,
};
await executeCustomWidgetRequest(input, { acquireRequestLimit });
await executeCustomWidgetRequest(input, { acquireRequestLimit });
expect(mocks.executeDomainRequest).toHaveBeenCalledTimes(2);
expect(acquireRequestLimit).toHaveBeenCalledTimes(2);
expect(release).toHaveBeenCalledTimes(2);
});
test("replaces an unexpected apiKeyQuery transport error with safe public and loggable metadata", async () => {
const apiKey = "api-key-query-secret";
const tokenizedUrl = `https://example.com/status?access_token=${apiKey}`;
const transportFailure = new Error(`Transport failed for ${tokenizedUrl}`);
transportFailure.name = `SocketError:${tokenizedUrl}`;
mocks.executeDomainRequest.mockRejectedValueOnce(transportFailure);
const error = await executeCustomWidgetRequest({
baseUrl: "https://example.com",
targetUrl: "https://example.com/status",
method: "GET",
networkScope: "public",
kind: "query",
auth: {
type: "apiKeyQuery",
headerName: "access_token",
secrets: [{ kind: "apiKey", value: apiKey }],
},
}).then(
() => undefined,
(cause: unknown) => cause,
);
expect(error).toMatchObject({
code: "BAD_GATEWAY",
message: "External request failed",
});
expect((error as Error).cause).toBeUndefined();
expect(mocks.logger.error).toHaveBeenCalledWith("Custom widget request failed", {
event: "custom_widget_request_failed",
errorName: "UnexpectedTransportError",
origin: "https://example.com",
method: "GET",
});
expect(JSON.stringify(mocks.logger.error.mock.calls)).not.toContain(apiKey);
expect(JSON.stringify(mocks.logger.error.mock.calls)).not.toContain("access_token");
expect(String(error)).not.toContain(apiKey);
});
});
@@ -0,0 +1,58 @@
import { randomUUID } from "node:crypto";
import { RedisContainer } from "@testcontainers/redis";
import type { StartedRedisContainer } from "@testcontainers/redis";
import { Redis } from "ioredis";
import { afterAll, beforeAll, describe, expect, test } from "vitest";
import { createRedisCustomWidgetResponseCache } from "../../custom-widget/response-cache";
describe("custom widget response cache across replicas", () => {
let container: StartedRedisContainer | undefined;
let redisA: Redis | undefined;
let redisB: Redis | undefined;
beforeAll(async () => {
container = await new RedisContainer("redis:7.4-alpine").start();
redisA = new Redis(container.getConnectionUrl());
redisB = new Redis(container.getConnectionUrl());
await Promise.all([redisA.ping(), redisB.ping()]);
}, 60_000);
afterAll(async () => {
await Promise.all([redisA?.quit(), redisB?.quit()]);
await container?.stop();
}, 30_000);
test("an action on one replica invalidates a query cached by another replica", async () => {
if (!redisA || !redisB) throw new Error("Redis test clients were not initialized");
const cacheA = createRedisCustomWidgetResponseCache(redisA);
const cacheB = createRedisCustomWidgetResponseCache(redisB);
const itemNamespace = `custom-jsx:${randomUUID()}:`;
const namespace = `${itemNamespace}definition-v1:status:`;
const input = {
baseUrl: "https://example.com",
method: "GET" as const,
networkScope: "public" as const,
kind: "query" as const,
cacheKey: `${namespace}same-options`,
cacheTtlSeconds: 60,
};
let calls = 0;
const execute = async () => ({
ok: true,
status: 200,
statusText: "OK",
data: { calls: ++calls },
});
await expect(cacheA.withCache(input, execute)).resolves.toMatchObject({ data: { calls: 1 } });
await expect(cacheB.withCache(input, execute)).resolves.toMatchObject({ data: { calls: 1 } });
expect(calls).toBe(1);
await cacheB.invalidate([itemNamespace]);
await expect(cacheA.withCache(input, execute)).resolves.toMatchObject({ data: { calls: 2 } });
expect(calls).toBe(2);
});
});
@@ -0,0 +1,91 @@
import { describe, expect, test, vi } from "vitest";
import { invalidateCustomWidgetResponseCache, withCustomWidgetResponseCache } from "../../custom-widget/response-cache";
const response = (calls: number) => ({
ok: true,
status: 200,
statusText: "OK",
data: { calls },
});
describe("custom widget shared response cache", () => {
test("deduplicates queries and invalidates them with a versioned namespace", async () => {
const itemNamespace = "custom-jsx:test-item:";
const namespace = `${itemNamespace}test-version:status:`;
const input = {
baseUrl: "https://example.com",
method: "GET" as const,
networkScope: "public" as const,
kind: "query" as const,
cacheKey: `${namespace}test-params`,
cacheTtlSeconds: 60,
};
let calls = 0;
const execute = async () => response(++calls);
await expect(
Promise.all([withCustomWidgetResponseCache(input, execute), withCustomWidgetResponseCache(input, execute)]),
).resolves.toEqual([response(1), response(1)]);
await expect(withCustomWidgetResponseCache(input, execute)).resolves.toEqual(response(1));
await invalidateCustomWidgetResponseCache([itemNamespace]);
await expect(withCustomWidgetResponseCache(input, execute)).resolves.toEqual(response(2));
});
test("does not cache actions or zero-TTL queries", async () => {
let calls = 0;
const execute = async () => response(++calls);
const baseInput = {
baseUrl: "https://example.com",
method: "GET" as const,
networkScope: "public" as const,
cacheKey: "custom-jsx:no-cache:version:status:params",
cacheTtlSeconds: 0,
};
await withCustomWidgetResponseCache({ ...baseInput, kind: "query" }, execute);
await withCustomWidgetResponseCache({ ...baseInput, kind: "query" }, execute);
await withCustomWidgetResponseCache({ ...baseInput, kind: "action" }, execute);
await withCustomWidgetResponseCache({ ...baseInput, kind: "action" }, execute);
expect(calls).toBe(4);
});
test("does not retry a rejected query execution", async () => {
const failure = new Error("upstream failed");
const execute = vi.fn(async () => {
throw failure;
});
const input = {
baseUrl: "https://example.com",
method: "GET" as const,
networkScope: "public" as const,
kind: "query" as const,
cacheKey: "custom-jsx:rejected:version:status:params",
cacheTtlSeconds: 60,
};
await expect(withCustomWidgetResponseCache(input, execute)).rejects.toBe(failure);
expect(execute).toHaveBeenCalledOnce();
});
test("does not retry a synchronous query execution failure", async () => {
const failure = new Error("failed before returning a promise");
const execute = vi.fn(() => {
throw failure;
});
const input = {
baseUrl: "https://example.com",
method: "GET" as const,
networkScope: "public" as const,
kind: "query" as const,
cacheKey: "custom-jsx:synchronous-failure:version:status:params",
cacheTtlSeconds: 60,
};
await expect(withCustomWidgetResponseCache(input, execute)).rejects.toBe(failure);
expect(execute).toHaveBeenCalledOnce();
});
});
@@ -0,0 +1,16 @@
import { describe, expect, test } from "vitest";
import { useProcessLocalCustomWidgetState } from "../../../custom-widget-state-mode";
describe("Custom Widget shared-state selection", () => {
test.each([
[{ NODE_ENV: "test", CI: undefined }, true],
[{ NODE_ENV: "development", CI: "true" }, true],
[{ NODE_ENV: "development", CI: "false" }, false],
[{ NODE_ENV: "production", CI: "true" }, false],
[{ NODE_ENV: "production", CI: "false" }, false],
[{ NODE_ENV: "production", CI: undefined }, false],
])("uses process-local state only in tests: %o", (runtime, expected) => {
expect(useProcessLocalCustomWidgetState(runtime)).toBe(expected);
});
});
@@ -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,46 @@
import { describe, expect, test } from "vitest";
import { ipAddressFromHeaders, rateLimitAddressFromHeaders } from "@homarr/common/server";
import { createTRPCContext } from "../../trpc";
describe("tRPC client address context", () => {
test("does not use a forged forwarded address as the anonymous rate-limit identity", () => {
const headers = new Headers({
"user-agent": "vitest",
"x-forwarded-for": " 198.51.100.10, 10.0.0.2 ",
"x-real-ip": "203.0.113.20",
});
expect(ipAddressFromHeaders(headers)).toBe("198.51.100.10");
expect(rateLimitAddressFromHeaders(headers)).toBe("203.0.113.20");
expect(createTRPCContext({ headers, session: null }).clientAddress).toBe("203.0.113.20");
});
test("canonicalizes a trusted IPv6 address", () => {
const headers = new Headers({
"user-agent": "vitest",
"x-real-ip": " 2001:0DB8:0000:0000:0000:0000:0000:0001 ",
});
expect(rateLimitAddressFromHeaders(headers)).toBe("2001:db8::1");
expect(createTRPCContext({ headers, session: null }).clientAddress).toBe("2001:db8::1");
});
test("uses a shared anonymous bucket without a valid trusted address", () => {
const headers = new Headers({
"user-agent": "vitest",
"x-forwarded-for": "198.51.100.10",
"x-real-ip": "not-an-ip",
});
expect(rateLimitAddressFromHeaders(headers)).toBeNull();
expect(createTRPCContext({ headers, session: null }).clientAddress).toBeUndefined();
});
test("retains the general client-address helper for existing API-key behavior", () => {
const headers = new Headers({ "user-agent": "vitest", "x-real-ip": " 203.0.113.20 " });
expect(ipAddressFromHeaders(headers)).toBe("203.0.113.20");
});
});
@@ -3,22 +3,47 @@ import { beforeEach, describe, expect, test, vi } from "vitest";
import type { Session } from "@homarr/auth";
import { createId } from "@homarr/common";
import { encryptSecret } from "@homarr/common/server";
import { eq } from "@homarr/db";
import { boardUserPermissions, boards, customWidgetDefinitions, items, users } from "@homarr/db/schema";
import {
boardUserPermissions,
boards,
customWidgetDefinitions,
customWidgetSecrets,
items,
legacyCustomWidgetDefinitions,
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 } })),
}));
const mocks = vi.hoisted(() => {
const executeRequestImplementation = async (
_input: unknown,
options?: { acquireRequestLimit?: () => Promise<() => Promise<void>> },
) => {
const release = await options?.acquireRequestLimit?.();
try {
return { ok: true, status: 200, statusText: "OK", data: { value: 42 } };
} finally {
await release?.();
}
};
return {
acquireRequestLimit: vi.fn(async () => async () => undefined),
invalidateCache: vi.fn(async () => undefined),
executeRequestImplementation,
executeRequest: vi.fn(executeRequestImplementation),
};
});
vi.mock("../../custom-widget/request-executor", () => ({
executeCustomWidgetRequest: mocks.executeRequest,
invalidateCustomWidgetResponseCache: vi.fn(),
invalidateCustomWidgetResponseCache: mocks.invalidateCache,
}));
vi.mock("../../custom-widget/request-limits", () => ({
acquireCustomWidgetRequestLimit: vi.fn(async () => async () => undefined),
acquireCustomWidgetRequestLimit: mocks.acquireRequestLimit,
}));
import { serializeCustomWidgetDefinition } from "../../custom-widget/stored-definition";
@@ -54,6 +79,15 @@ const definition: HomarrCustomWidgetV2 = {
permission: "view",
trigger: "manual",
},
"private-status": {
source: "default",
kind: "query",
method: "GET",
path: "/private-status",
auth: "inherit",
permission: "modify",
trigger: "manual",
},
toggle: {
source: "default",
kind: "action",
@@ -84,7 +118,7 @@ const createSession = (userId: string): Session => ({
expires: new Date(Date.now() + 60_000).toISOString(),
});
async function setup(isPublic = true) {
async function setup(isPublic = true, customDefinition = definition, apiKey?: string) {
const db = createDb();
const ownerId = createId();
const boardId = createId();
@@ -94,9 +128,18 @@ async function setup(isPublic = true) {
await db.insert(boards).values({ id: boardId, name: createId(), creatorId: ownerId, isPublic });
await db.insert(customWidgetDefinitions).values({
id: definitionId,
...serializeCustomWidgetDefinition(definition),
...serializeCustomWidgetDefinition(customDefinition),
creatorId: ownerId,
});
if (apiKey) {
await db.insert(customWidgetSecrets).values({
definitionId,
sourceId: "default",
kind: "apiKey",
encryptedValue: encryptSecret(apiKey),
updatedAt: new Date(),
});
}
await db.insert(items).values({
id: itemId,
boardId,
@@ -107,11 +150,21 @@ async function setup(isPublic = true) {
}
describe("Custom JSX v2 board router", () => {
beforeEach(() => mocks.executeRequest.mockClear());
beforeEach(() => {
mocks.acquireRequestLimit.mockClear();
mocks.executeRequest.mockReset();
mocks.executeRequest.mockImplementation(mocks.executeRequestImplementation);
mocks.invalidateCache.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 });
const caller = customApiRouter.createCaller({
db,
deviceType: undefined,
session: null,
clientAddress: "198.51.100.10",
});
await expect(caller.queryRequest({ itemId, requestId: "status", params: { name: "homarr" } })).resolves.toEqual(
expect.objectContaining({ ok: true, data: { value: 42 } }),
@@ -120,6 +173,156 @@ describe("Custom JSX v2 board router", () => {
code: "NOT_FOUND",
});
expect(mocks.executeRequest).toHaveBeenCalledOnce();
expect(mocks.acquireRequestLimit).toHaveBeenCalledWith(
expect.objectContaining({ userId: undefined, anonymousId: "198.51.100.10" }),
);
});
test("redacts apiKeyQuery transport details from anonymous load and manual query results", async () => {
const apiKey = "api-key-query-secret";
const credentialedDefinition: HomarrCustomWidgetV2 = {
...definition,
sources: {
default: {
name: "API",
baseUrl: "https://example.com",
networkScope: "public",
auth: { type: "apiKeyQuery", name: "access_token" },
},
},
};
const { db, itemId } = await setup(true, credentialedDefinition, apiKey);
mocks.executeRequest.mockImplementation(async (input) => {
const request = input as {
targetUrl: URL;
auth?: { headerName?: string | null; secrets: Array<{ kind: string; value: string }> };
};
const secret = request.auth?.secrets.find(({ kind }) => kind === "apiKey")?.value;
const tokenizedUrl = new URL(request.targetUrl);
tokenizedUrl.searchParams.set(request.auth?.headerName ?? "api_key", secret ?? "");
const failure = new Error(`Transport failed for ${tokenizedUrl.toString()}`);
failure.name = `SocketError:${tokenizedUrl.toString()}`;
throw failure;
});
const caller = customApiRouter.createCaller({
db,
deviceType: undefined,
session: null,
clientAddress: "198.51.100.10",
});
const loadResult = await caller.getData({ itemId });
const queryError = await caller.queryRequest({ itemId, requestId: "status", params: { name: "homarr" } }).then(
() => undefined,
(cause: unknown) => cause,
);
expect(loadResult.status["load-status"]).toMatchObject({
ok: false,
status: 0,
error: "Request failed",
});
expect(queryError).toMatchObject({
code: "BAD_GATEWAY",
message: "External request failed",
});
expect((queryError as Error).cause).toBeUndefined();
expect(mocks.executeRequest).toHaveBeenCalledWith(
expect.objectContaining({
auth: expect.objectContaining({
type: "apiKeyQuery",
headerName: "access_token",
secrets: [{ kind: "apiKey", value: apiKey }],
}),
}),
expect.any(Object),
);
expect(JSON.stringify(loadResult)).not.toContain(apiKey);
expect(JSON.stringify(loadResult)).not.toContain("access_token");
expect(String(queryError)).not.toContain(apiKey);
expect(String(queryError)).not.toContain("access_token");
});
test("requires authentication before invalidating board-authorized query caches", async () => {
const { db, itemId } = await setup();
const viewerId = createId();
await db.insert(users).values({ id: viewerId });
const anonymous = customApiRouter.createCaller({
db,
deviceType: undefined,
session: null,
clientAddress: "198.51.100.10",
});
await expect(anonymous.refreshQueries({ itemId, all: true })).rejects.toMatchObject({ code: "UNAUTHORIZED" });
expect(mocks.invalidateCache).not.toHaveBeenCalled();
const authenticated = customApiRouter.createCaller({
db,
deviceType: undefined,
session: createSession(viewerId),
clientAddress: "198.51.100.10",
});
await expect(authenticated.refreshQueries({ itemId, all: true })).resolves.toEqual({
requestIds: ["load-status", "status"],
});
expect(mocks.invalidateCache).toHaveBeenCalledOnce();
expect(mocks.invalidateCache).toHaveBeenCalledWith([
expect.stringMatching(new RegExp(`^custom-jsx:${itemId}:.+:load-status:$`, "u")),
expect.stringMatching(new RegExp(`^custom-jsx:${itemId}:.+:status:$`, "u")),
]);
expect(mocks.acquireRequestLimit).toHaveBeenCalledWith(
expect.objectContaining({
category: "query",
userId: viewerId,
itemId,
}),
);
expect(mocks.executeRequest).not.toHaveBeenCalled();
});
test("queues valid load requests within the per-viewer concurrency limit", async () => {
const requests = Object.fromEntries(
Array.from({ length: 6 }, (_, index) => [
`load-${index}`,
{
source: "default",
kind: "query" as const,
method: "GET" as const,
path: `/status/${index}`,
auth: "inherit" as const,
permission: "view" as const,
trigger: "load" as const,
},
]),
);
const { db, itemId } = await setup(true, { ...definition, requests });
let active = 0;
let maximumActive = 0;
mocks.executeRequest.mockImplementation(async (_input, options) => {
const release = await options?.acquireRequestLimit?.();
active += 1;
maximumActive = Math.max(maximumActive, active);
try {
await new Promise((resolve) => setTimeout(resolve, 5));
return { ok: true, status: 200, statusText: "OK", data: { value: active } };
} finally {
active -= 1;
await release?.();
}
});
const caller = customApiRouter.createCaller({
db,
deviceType: undefined,
session: null,
clientAddress: "198.51.100.10",
});
const result = await caller.getData({ itemId });
expect(Object.keys(result.data)).toHaveLength(6);
expect(mocks.executeRequest).toHaveBeenCalledTimes(6);
expect(maximumActive).toBe(4);
});
test("hides private boards and disabled definitions before executing a request", async () => {
@@ -154,6 +357,25 @@ describe("Custom JSX v2 board router", () => {
expect(mocks.executeRequest).not.toHaveBeenCalled();
});
test("surfaces a real preserved v1 placement as migration-required", async () => {
const { db, itemId, definitionId, ownerId } = await setup();
await db.delete(customWidgetDefinitions).where(eq(customWidgetDefinitions.id, definitionId));
await db.insert(legacyCustomWidgetDefinitions).values({
id: definitionId,
name: "Legacy weather",
url: "https://example.com/weather",
displayConfig: stringifySuperJson({ type: "singleValue", jsonPath: "$.temperature" }),
creatorId: ownerId,
});
const caller = customApiRouter.createCaller({ db, deviceType: undefined, session: null });
await expect(caller.getData({ itemId })).rejects.toMatchObject({
code: "PRECONDITION_FAILED",
message: "LEGACY_CUSTOM_WIDGET_MIGRATION_REQUIRED",
});
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) });
@@ -180,6 +402,7 @@ describe("Custom JSX v2 board router", () => {
);
expect(mocks.executeRequest).toHaveBeenCalledWith(
expect.objectContaining({ method: "POST", body: '{"enabled":true}' }),
expect.objectContaining({ acquireRequestLimit: expect.any(Function) }),
);
});
@@ -0,0 +1,124 @@
import SuperJSON 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 { boards, items, users } from "@homarr/db/schema";
import { createDb } from "@homarr/db/test";
const mocks = vi.hoisted(() => ({ env: { CUSTOM_WIDGETS_ENABLED: true } }));
vi.mock("../../../env", () => ({ env: mocks.env }));
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", () => {
beforeEach(() => {
mocks.env.CUSTOM_WIDGETS_ENABLED = true;
});
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("rejects direct admin reconfiguration while the emergency switch is off", async () => {
const { db, userId, boardId, itemId } = await setup("customApi");
mocks.env.CUSTOM_WIDGETS_ENABLED = false;
const caller = optionsRouter.createCaller({ db, deviceType: undefined, session: createSession(userId, true) });
await expect(
caller.saveItemOptions({ boardId, itemId, newOptions: { refreshInterval: 60 } }),
).rejects.toMatchObject({ code: "SERVICE_UNAVAILABLE" });
});
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();
});
});
+120 -60
View File
@@ -12,9 +12,11 @@ import {
validateCustomWidgetOptions,
} from "@homarr/custom-widgets/core";
import type { CustomJsxRequest, CustomWidgetSource } from "@homarr/custom-widgets/core";
import { CUSTOM_WIDGET_USER_ITEM_CONCURRENCY_LIMIT } from "@homarr/custom-widgets/server";
import { createTRPCRouter, protectedProcedure, publicProcedure } from "../../trpc";
import { throwIfActionForbiddenAsync } from "../board/board-access";
import { assertCustomWidgetsEnabled } from "../custom-widget/feature-flags";
import { executeCustomWidgetRequest, invalidateCustomWidgetResponseCache } from "../custom-widget/request-executor";
import {
hashRuntimeParams,
@@ -32,6 +34,10 @@ const namedRequestInputSchema = itemInputSchema.extend({
requestId: z.string().min(1).max(64),
params: runtimeParamsSchema.default({}),
});
const refreshQueriesInputSchema = itemInputSchema.extend({
requestIds: z.array(z.string().min(1).max(64)).max(64).default([]),
all: z.boolean().default(false),
});
interface CustomWidgetItemOptions {
definitionId: string;
@@ -40,7 +46,7 @@ interface CustomWidgetItemOptions {
refreshInterval?: number;
}
type RouterContext = Parameters<typeof throwIfActionForbiddenAsync>[0];
type RouterContext = Parameters<typeof throwIfActionForbiddenAsync>[0] & { clientAddress?: string };
type ResolvedDefinition = Awaited<ReturnType<typeof resolvePlacedDefinitionAsync>>;
const parseItemOptions = (raw: string): CustomWidgetItemOptions => {
@@ -67,6 +73,7 @@ const parseItemOptions = (raw: string): CustomWidgetItemOptions => {
};
async function resolvePlacedDefinitionAsync(ctx: RouterContext, itemId: string) {
assertCustomWidgetsEnabled();
const item = await ctx.db.query.items.findFirst({
where: eq(items.id, itemId),
columns: { id: true, boardId: true, kind: true, options: true },
@@ -142,28 +149,35 @@ const getAuth = (resolved: ResolvedDefinition, source: IdentifiedSource, mode: "
};
};
const withRequestLimit = async <T>(
ctx: RouterContext,
resolved: ResolvedDefinition,
request: IdentifiedRequest,
callback: () => Promise<T>,
) => {
const release = await acquireCustomWidgetRequestLimit({
const acquireRequestLimit = (ctx: RouterContext, resolved: ResolvedDefinition, request: IdentifiedRequest) =>
acquireCustomWidgetRequestLimit({
category: request.kind === "query" ? "query" : request.method === "DELETE" ? "delete" : "action",
userId: ctx.session?.user.id,
anonymousId: ctx.clientAddress,
itemId: resolved.item.id,
definitionId: resolved.stored.id,
});
try {
return await callback();
} finally {
await release();
}
};
const getCacheKey = (resolved: ResolvedDefinition, request: IdentifiedRequest, params: Record<string, unknown>) =>
`custom-jsx:${resolved.item.id}:${getCustomWidgetCacheVersion(resolved.stored)}:${request.id}:${hashRuntimeParams(params)}`;
async function mapLoadRequests<T, TResult>(
requests: readonly T[],
execute: (request: T) => Promise<TResult>,
): Promise<TResult[]> {
const results: TResult[] = [];
for (let index = 0; index < requests.length; index += CUSTOM_WIDGET_USER_ITEM_CONCURRENCY_LIMIT) {
results.push(
...(await Promise.all(
requests
.slice(index, index + CUSTOM_WIDGET_USER_ITEM_CONCURRENCY_LIMIT)
.map(async (request) => await execute(request)),
)),
);
}
return results;
}
const executeRequest = async (
ctx: RouterContext,
resolved: ResolvedDefinition,
@@ -174,20 +188,28 @@ const executeRequest = async (
const source = findSource(resolved, request.source);
const values = resolveCustomWidgetRequestValues(request, resolved.configuration, params);
const targetUrl = renderRequestTarget(source.baseUrl, request, values);
return withRequestLimit(ctx, resolved, request, () =>
executeCustomWidgetRequest({
baseUrl: source.baseUrl,
targetUrl,
method: request.method,
body: renderRequestBody(request, values),
staticHeaders: request.headers,
auth: getAuth(resolved, source, request.auth),
networkScope: source.networkScope,
kind: request.kind,
cacheKey: request.kind === "query" ? getCacheKey(resolved, request, values) : undefined,
cacheTtlSeconds: request.cacheSeconds,
}),
);
try {
return await executeCustomWidgetRequest(
{
baseUrl: source.baseUrl,
targetUrl,
method: request.method,
body: renderRequestBody(request, values),
staticHeaders: request.headers,
auth: getAuth(resolved, source, request.auth),
networkScope: source.networkScope,
kind: request.kind,
cacheKey: request.kind === "query" ? getCacheKey(resolved, request, values) : undefined,
cacheTtlSeconds: request.cacheSeconds,
},
{
acquireRequestLimit: () => acquireRequestLimit(ctx, resolved, request),
},
);
} catch (error) {
if (error instanceof TRPCError) throw error;
throw new TRPCError({ code: "BAD_GATEWAY", message: "External request failed" });
}
};
export const customApiRouter = createTRPCRouter({
@@ -196,39 +218,37 @@ export const customApiRouter = createTRPCRouter({
const loadRequests = Object.entries(resolved.definition.requests).filter(
([, request]) => request.kind === "query" && request.trigger === "load",
);
const entries = await Promise.all(
loadRequests.map(async ([requestId, request]) => {
try {
const response = await executeRequest(ctx, resolved, { id: requestId, ...request }, {});
return [
requestId,
{
data: response.data,
status: {
loading: false,
ok: response.ok,
status: response.status,
statusText: response.statusText,
error: response.ok ? undefined : `HTTP ${response.status}: ${response.statusText}`,
},
const entries = await mapLoadRequests(loadRequests, async ([requestId, request]) => {
try {
const response = await executeRequest(ctx, resolved, { id: requestId, ...request }, {});
return [
requestId,
{
data: response.data,
status: {
loading: false,
ok: response.ok,
status: response.status,
statusText: response.statusText,
error: response.ok ? undefined : `HTTP ${response.status}: ${response.statusText}`,
},
] as const;
} catch (error) {
return [
requestId,
{
data: null,
status: {
loading: false,
ok: false,
status: 0,
error: error instanceof Error ? error.message : "Request failed",
},
},
] as const;
} catch {
return [
requestId,
{
data: null,
status: {
loading: false,
ok: false,
status: 0,
error: "Request failed",
},
] as const;
}
}),
);
},
] as const;
}
});
return {
type: "customJsx" as const,
@@ -264,6 +284,46 @@ export const customApiRouter = createTRPCRouter({
};
}),
refreshQueries: protectedProcedure.input(refreshQueriesInputSchema).mutation(async ({ ctx, input }) => {
const resolved = await resolvePlacedDefinitionAsync(ctx, input.itemId);
const available = Object.entries(resolved.definition.requests).flatMap(([requestId, request]) =>
request.kind === "query" ? [{ id: requestId, ...request }] : [],
);
const requested = new Set(input.all ? available.map(({ id }) => id) : input.requestIds);
const authorized: IdentifiedRequest[] = [];
for (const request of available) {
if (!requested.has(request.id)) continue;
try {
await throwIfActionForbiddenAsync(
ctx,
eq(boards.id, resolved.item.boardId),
request.permission as BoardPermission,
);
authorized.push(request);
} catch (error) {
if (!(error instanceof TRPCError) || error.code !== "NOT_FOUND") throw error;
}
}
if (authorized.length === 0) return { requestIds: [] };
const release = await acquireCustomWidgetRequestLimit({
category: "query",
userId: ctx.session?.user.id,
anonymousId: ctx.clientAddress,
itemId: resolved.item.id,
definitionId: resolved.stored.id,
});
try {
const version = getCustomWidgetCacheVersion(resolved.stored);
await invalidateCustomWidgetResponseCache(
authorized.map((request) => `custom-jsx:${resolved.item.id}:${version}:${request.id}:`),
);
} finally {
await release();
}
return { requestIds: authorized.map(({ id }) => id) };
}),
executeAction: protectedProcedure
.input(namedRequestInputSchema.extend({ confirmed: z.boolean().optional() }))
.mutation(async ({ ctx, input }) => {
@@ -275,7 +335,7 @@ export const customApiRouter = createTRPCRouter({
}
const response = await executeRequest(ctx, resolved, request, input.params);
if (response.ok && request.invalidates?.length) {
invalidateCustomWidgetResponseCache(
await invalidateCustomWidgetResponseCache(
request.invalidates.flatMap((requestId) => [
`custom-jsx:${resolved.item.id}:${getCustomWidgetCacheVersion(resolved.stored)}:${requestId}:`,
`custom-widget:options:${resolved.stored.id}:${getCustomWidgetCacheVersion(resolved.stored)}:${requestId}:`,
+10 -2
View File
@@ -7,8 +7,10 @@ import { getServerSettingsAsync } from "@homarr/db/queries";
import { boards, items } from "@homarr/db/schema";
import type { WidgetOptionsSettings } from "../../../../widgets/src";
import { env } from "../../env";
import { createTRPCRouter, protectedProcedure, publicProcedure } from "../../trpc";
import { throwIfActionForbiddenAsync } from "../board/board-access";
import { throwIfCustomWidgetPlacementChangeForbidden } from "../board/custom-widget-placement-access";
export const optionsRouter = createTRPCRouter({
getWidgetOptionSettings: publicProcedure.query(async ({ ctx }): Promise<WidgetOptionsSettings> => {
@@ -46,10 +48,16 @@ export const optionsRouter = createTRPCRouter({
}
const options = SuperJSON.parse<Record<string, unknown>>(item.options);
Object.assign(options, input.newOptions);
const updatedOptions = { ...options, ...input.newOptions };
throwIfCustomWidgetPlacementChangeForbidden({
isAdmin: ctx.session.user.permissions.includes("admin"),
customWidgetsEnabled: env.CUSTOM_WIDGETS_ENABLED !== false,
submittedItems: [{ id: item.id, kind: item.kind, options: updatedOptions }],
storedItems: [{ id: item.id, kind: item.kind, options }],
});
await ctx.db
.update(items)
.set({ options: SuperJSON.stringify(options) })
.set({ options: SuperJSON.stringify(updatedOptions) })
.where(eq(items.id, input.itemId));
}),
});
+32 -19
View File
@@ -70,7 +70,6 @@ const MCP_TOOL_ALLOWLIST = {
"board_setHomeBoard",
"board_setMobileHomeBoard",
"customWidget_delete",
"customWidget_deleteLegacy",
"customWidget_previewAction",
"customWidget_templatePatch",
"dnsHole_disable",
@@ -171,19 +170,11 @@ describe("custom widget authoring procedure access", () => {
session: null,
});
test("executes promised public procedures without a session", async () => {
await expect(unauthenticatedCaller.customWidget.schema()).resolves.toMatchObject({ type: "object" });
await expect(unauthenticatedCaller.customWidget.getAuthoringPrompt()).resolves.toMatchObject({
version: 2,
prompt: expect.any(String),
});
await expect(unauthenticatedCaller.customWidget.getSkill()).resolves.toMatchObject({
name: expect.any(String),
});
});
test("rejects protected and permission-gated authoring procedures without a session", async () => {
test("rejects every authoring procedure without a session", async () => {
const calls = [
unauthenticatedCaller.customWidget.schema(),
unauthenticatedCaller.customWidget.getAuthoringPrompt(),
unauthenticatedCaller.customWidget.getSkill(),
unauthenticatedCaller.customWidget.list(),
unauthenticatedCaller.customWidget.validate({ widget: {} }),
unauthenticatedCaller.customWidget.secretSet({
@@ -196,17 +187,39 @@ describe("custom widget authoring procedure access", () => {
}
});
test("enforces the dedicated permission on secret tools", async () => {
const callerWithoutSecretPermission = mcpRouter.createCaller({
test("rejects authoring and secret tools for authenticated non-admins", async () => {
const nonAdminCaller = mcpRouter.createCaller({
db: null as never,
deviceType: undefined,
session: { user: { id: "user-1", permissions: ["custom-widget-manage"] } } as never,
session: { user: { id: "user-1", permissions: ["board-modify-all"] } } as never,
});
await expect(
callerWithoutSecretPermission.customWidget.secretSet({
const calls = [
nonAdminCaller.customWidget.schema(),
nonAdminCaller.customWidget.getAuthoringPrompt(),
nonAdminCaller.customWidget.getSkill(),
nonAdminCaller.customWidget.secretSet({
definitionId: "widget",
secret: { sourceId: "default", kind: "apiKey", value: "secret" },
}),
).rejects.toEqual(expect.objectContaining<Partial<TRPCError>>({ code: "FORBIDDEN" }));
];
for (const call of calls) {
await expect(call).rejects.toEqual(expect.objectContaining<Partial<TRPCError>>({ code: "FORBIDDEN" }));
}
});
test("allows admins to read authoring resources", async () => {
const adminCaller = mcpRouter.createCaller({
db: null as never,
deviceType: undefined,
session: { user: { id: "admin-1", permissions: ["admin"] } } as never,
});
await expect(adminCaller.customWidget.schema()).resolves.toMatchObject({ type: "object" });
await expect(adminCaller.customWidget.getAuthoringPrompt()).resolves.toMatchObject({
version: 2,
prompt: expect.any(String),
});
await expect(adminCaller.customWidget.getSkill()).resolves.toMatchObject({
name: expect.any(String),
});
});
});
+3 -1
View File
@@ -14,7 +14,7 @@ import { ZodError } from "zod/v4";
import type { Session } from "@homarr/auth";
import { extractBaseUrlFromHeaders, FlattenError } from "@homarr/common";
import { userAgent } from "@homarr/common/server";
import { rateLimitAddressFromHeaders, userAgent } from "@homarr/common/server";
import type { DeviceType } from "@homarr/common/server";
import { createLogger } from "@homarr/core/infrastructure/logs";
import { db } from "@homarr/db";
@@ -41,6 +41,7 @@ interface ApiContext {
session: Session | null;
deviceType: DeviceType;
baseUrl?: `${string}://${string}`;
clientAddress?: string;
db: typeof db;
}
@@ -58,6 +59,7 @@ export const createTRPCContext = (opts: { headers: Headers; session: Session | n
session,
deviceType: userAgent(opts.headers).device.type,
baseUrl: extractBaseUrlFromHeaders(opts.headers),
clientAddress: rateLimitAddressFromHeaders(opts.headers) ?? undefined,
db,
};
};