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

@@ -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();
});
});