A modern and easy to use dashboard. 80+ integrations. 20K+ icons built in. Authentication out of the box. No YAML, drag and drop configuration.
import { readFileSync } from "node:fs";
import { X509Certificate } from "node:crypto";
import { createServer as createHttpsServer } from "node:https";
import { createServer } from "node:http";
import type { AddressInfo } from "node:net";
import { brotliCompressSync, deflateSync, gzipSync } from "node:zlib";
import { createOpenApiFetchHandler } from "trpc-to-openapi";
import { afterAll, beforeAll, describe, expect, test, vi } from "vitest";
import type { z } from "zod/v4";
import type { Session } from "@homarr/auth";
import { encryptSecret } from "@homarr/common/server";
import { executeCustomWidgetRequest } from "@homarr/custom-widgets/server";
import { eq } from "@homarr/db";
import { createDb } from "@homarr/db/test";
import { integrations, integrationSecrets, integrationUserPermissions, users } from "@homarr/db/schema";
import type { IntegrationPermission } from "@homarr/definitions";
import { getIntegrationHttpAuthenticationAsync } from "@homarr/integrations/factory";
import { callMcpTool, extractMcpToolsFromProcedures } from "../mcp-tools";
import { openApiRouter } from "../open-api";
import { createTRPCRouter } from "../trpc";
import {
integrationRequestProcedure,
integrationRequestSchema,
redactIntegrationResponse,
resolveIntegrationRequestUrl,
} from "../router/integration/integration-request";
vi.mock("@homarr/auth", () => ({}));
const trust = vi.hoisted(() => ({
certificates: vi.fn(async (): Promise<string[]> => []),
hostnames: vi.fn(async (): Promise<{ hostname: string; thumbprint: string }[]> => []),
}));
vi.mock("@homarr/core/infrastructure/certificates", () => ({
getAllTrustedCertificatesAsync: trust.certificates,
getTrustedCertificateHostnamesAsync: trust.hostnames,
}));
const router = createTRPCRouter({ request: integrationRequestProcedure });
const secret = "test-credential-not-for-output";
const calls: { method: string | undefined; path: string | undefined; auth: string | undefined; body: string }[] = [];
const server = createServer(async (req, res) => {
let body = "";
for await (const chunk of req) body += String(chunk);
calls.push({
method: req.method,
path: req.url,
auth: (req.headers["x-api-key"] ?? req.headers.authorization) as string | undefined,
body,
});
if (req.url === "/slow") return;
if (req.url === "/inspect") {
res.setHeader("Content-Type", "application/json");
res.end(JSON.stringify({ body, contentType: req.headers["content-type"], auth: req.headers["x-api-key"] }));
return;
}
if (req.method === "HEAD") {
res.writeHead(200, { "Content-Length": "9000000", "Content-Encoding": "gzip" });
res.end();
return;
}
if (req.url?.startsWith("/compressed")) {
const encoding = req.headers["accept-encoding"] ?? "gzip";
let bytes = Buffer.from(JSON.stringify({ value: "decoded", secret }));
if (req.url === "/compressed-large") bytes = Buffer.from("x".repeat(1024 * 1024 + 1));
for (const name of encoding.split(", ")) {
switch (name) {
case "gzip":
bytes = gzipSync(bytes);
break;
case "deflate":
bytes = deflateSync(bytes);
break;
case "br":
bytes = brotliCompressSync(bytes);
break;
}
}
if (req.url === "/compressed-invalid") bytes = Buffer.from(secret);
res.writeHead(200, { "Content-Type": "application/json", "Content-Encoding": encoding });
res.end(bytes);
return;
}
if (req.url === "/redirect") {
res.writeHead(302, { Location: "/echo" });
res.end();
return;
}
if (req.url === "/large") {
res.end("x".repeat(1024 * 1024 + 1));
return;
}
if (req.url === "/echo") {
res.writeHead(400, { "Content-Type": "application/json" });
res.end(JSON.stringify({ [secret]: [secret, encodeURIComponent(secret), Buffer.from(secret).toString("base64")] }));
return;
}
if (req.url === "/text") {
res.writeHead(500, { "Content-Type": "application/json" });
res.end(`invalid JSON ${secret}`);
return;
}
if (req.url === "/boolean") {
res.setHeader("Content-Type", "application/json");
res.end(JSON.stringify({ healthy: true }));
return;
}
if (req.method === "DELETE") {
res.writeHead(204);
res.end();
return;
}
res.setHeader("Content-Type", "application/json");
res.end(JSON.stringify([{ id: 42, title: "Example series" }]));
});
let baseUrl: string;
beforeAll(async () => {
await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
baseUrl = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
});
afterAll(async () => {
server.closeAllConnections();
await new Promise<void>((resolve, reject) =>
server.close((error) => {
if (error) reject(error);
else resolve();
}),
);
});
async function fixtureContext(
permission?: IntegrationPermission,
setup?: (db: ReturnType<typeof createDb>) => Promise<void>,
) {
const db = createDb();
await db.insert(users).values([{ id: "reader" }, { id: "other" }]);
await db.insert(integrations).values({ id: "sonarr", name: "Sonarr", kind: "sonarr", url: baseUrl });
await db.insert(integrationSecrets).values({ integrationId: "sonarr", kind: "apiKey", value: encryptSecret(secret) });
// Another user's full permission must never grant this caller access.
await db.insert(integrationUserPermissions).values({ integrationId: "sonarr", userId: "other", permission: "full" });
if (permission)
await db.insert(integrationUserPermissions).values({ integrationId: "sonarr", userId: "reader", permission });
const session = {
user: { id: "reader", permissions: [], colorScheme: "light" },
expires: new Date().toISOString(),
} satisfies Session;
await setup?.(db);
return { db, session, deviceType: undefined };
}
async function fixture(permission?: IntegrationPermission, setup?: (db: ReturnType<typeof createDb>) => Promise<void>) {
return router.createCaller(await fixtureContext(permission, setup));
}
const get = { integrationId: "sonarr", method: "GET", path: "/api/v3/series" } as const;
describe("integration_request validation", () => {
test.each([
"https://evil.com/x",
"https://example.com/x",
"//evil.com/x",
"\\\\evil.com/x",
"/\\evil.com",
" https://evil.com",
"https:\nevil.com",
"/x#fragment",
])("rejects %s", (path) => {
expect(() => resolveIntegrationRequestUrl("https://example.com/base/", path)).toThrow();
});
test.each(["../series", "../../series", "%2e%2e/series"])(
"rejects traversal outside the configured path %s",
(path) => {
expect(() => resolveIntegrationRequestUrl("https://example.com/base/", path)).toThrow();
},
);
test("preserves URL resolution semantics and query parameters", () => {
expect(resolveIntegrationRequestUrl("https://example.com/base/", "series?id=42").href).toBe(
"https://example.com/base/series?id=42",
);
expect(resolveIntegrationRequestUrl("https://example.com/base/", "/series").pathname).toBe("/base/series");
});
test("accepts only JSON bodies and the specified methods", () => {
expect(integrationRequestSchema.safeParse({ ...get, body: new Date() }).success).toBe(false);
expect(integrationRequestSchema.safeParse({ ...get, method: "TRACE" }).success).toBe(false);
});
test("resolves native authentication and rejects incomplete credentials", async () => {
const input = {
id: "test",
name: "Test",
externalUrl: null,
url: baseUrl,
decryptedSecrets: [{ kind: "apiKey" as const, value: secret }],
};
await expect(getIntegrationHttpAuthenticationAsync({ ...input, kind: "sonarr" })).resolves.toMatchObject({
headers: { "X-API-Key": secret },
});
await expect(getIntegrationHttpAuthenticationAsync({ ...input, kind: "homeAssistant" })).resolves.toMatchObject({
headers: { Authorization: `Bearer ${secret}` },
});
await expect(getIntegrationHttpAuthenticationAsync({ ...input, kind: "qBittorrent" })).resolves.toMatchObject({
headers: { Authorization: `Bearer ${secret}` },
});
await expect(
getIntegrationHttpAuthenticationAsync({ ...input, kind: "sonarr", decryptedSecrets: [] }),
).rejects.toThrow();
});
test.each([42, true, false, null])("redacts echoed primitive credential %s", (value) => {
expect(redactIntegrationResponse(value, [{ kind: "password", value: String(value) }])).toBe("[REDACTED]");
});
test("redacts JSON-escaped credentials embedded in text", () => {
const password = 'quoted"password\\with-newline\n';
const encoded = JSON.stringify(password).slice(1, -1);
expect(
redactIntegrationResponse({ message: `password=${encoded}` }, [{ kind: "password", value: password }]),
).toEqual({ message: "password=[REDACTED]" });
});
test("redacts basic credentials and JSON keys without damaging JSON", () => {
const credentials = Buffer.from(`user:${secret}`).toString("base64");
expect(
redactIntegrationResponse({ [secret]: `Basic ${credentials}` }, [
{ kind: "username", value: "user" },
{ kind: "password", value: secret },
]),
).toEqual({ "[REDACTED]": "Basic [REDACTED]" });
});
});
describe("integration_request with a mock integration server", () => {
test("GET authenticates with stored credentials and full permission", async () => {
const caller = await fixture("full");
await expect(caller.request(get)).resolves.toMatchObject({
status: 200,
data: [{ id: 42, title: "Example series" }],
});
expect(calls.at(-1)).toMatchObject({ method: "GET", path: "/api/v3/series", auth: secret });
});
test.each([
["ical", "iCalendar feeds"],
["truenas", "TrueNAS uses a WebSocket API"],
] as const)("rejects %s before sending a generic HTTP request", async (kind, message) => {
const caller = await fixture("full", async (db) => {
await db.update(integrations).set({ kind }).where(eq(integrations.id, "sonarr"));
});
const previousCalls = calls.length;
await expect(caller.request(get)).rejects.toMatchObject({
code: "BAD_REQUEST",
message: expect.stringContaining(message),
});
expect(calls).toHaveLength(previousCalls);
});
test("reuses the Custom Widget authentication resolver for every HTTP-capable kind", async () => {
const caller = await fixture("full", async (db) => {
await db.update(integrations).set({ kind: "mealie" }).where(eq(integrations.id, "sonarr"));
});
await expect(caller.request({ ...get, path: "/api/households/statistics" })).resolves.toMatchObject({
status: 200,
});
expect(calls.at(-1)?.auth).toBe(`Bearer ${secret}`);
});
test("adds saved query credentials to a generic request", async () => {
const caller = await fixture("full", async (db) => {
await db.update(integrations).set({ kind: "jackett" }).where(eq(integrations.id, "sonarr"));
});
await caller.request({ ...get, path: "/api/v2/indexers?apikey=ignored" });
expect(calls.at(-1)?.path).toBe(`/api/v2/indexers?apikey=${secret}`);
});
test("prefixes saved JSON-RPC credentials before caller parameters", async () => {
const caller = await fixture("full", async (db) => {
await db.update(integrations).set({ kind: "aria2" }).where(eq(integrations.id, "sonarr"));
});
await caller.request({
...get,
method: "POST",
path: "/jsonrpc",
body: { jsonrpc: "2.0", method: "aria2.getVersion", params: ["token:ignored"] },
});
expect(JSON.parse(calls.at(-1)?.body ?? "null")).toMatchObject({
params: [`token:${secret}`, "token:ignored"],
});
});
test("does not redact ordinary response values that match constant adapter headers", async () => {
const caller = await fixture("full", async (db) => {
await db.update(integrations).set({ kind: "nextcloud" }).where(eq(integrations.id, "sonarr"));
await db.delete(integrationSecrets).where(eq(integrationSecrets.integrationId, "sonarr"));
await db.insert(integrationSecrets).values([
{ integrationId: "sonarr", kind: "username", value: encryptSecret("reader") },
{ integrationId: "sonarr", kind: "password", value: encryptSecret(secret) },
]);
});
await expect(caller.request({ ...get, path: "/boolean" })).resolves.toMatchObject({
status: 200,
data: { healthy: true },
});
});
test("keeps credentials and URL from the same integration snapshot", async () => {
const rotated = "credential-for-the-new-origin";
const caller = await fixture("full", async (db) => {
const snapshot = await db.query.integrations.findFirst({
where: eq(integrations.id, "sonarr"),
with: {
secrets: true,
userPermissions: { where: eq(integrationUserPermissions.userId, "reader") },
groupPermissions: true,
},
});
// Simulate a URL/key rotation immediately after the first SELECT completed.
await db.update(integrations).set({ url: "https://new-origin.example" }).where(eq(integrations.id, "sonarr"));
await db.update(integrationSecrets).set({ value: encryptSecret(rotated) });
vi.spyOn(db.query.integrations, "findFirst").mockResolvedValueOnce(snapshot);
});
await caller.request(get);
expect(calls.at(-1)?.auth).toBe(secret);
});
test("uses Homarr's trusted certificates and hostname exceptions without disabling TLS checks", async () => {
// This committed certificate/key pair is only for the loopback mock server.
const cert = readFileSync(new URL("./fixtures/integration-request-cert.pem", import.meta.url), "utf8");
const key = readFileSync(new URL("./fixtures/integration-request-key.pem", import.meta.url), "utf8");
const https = createHttpsServer({ cert, key }, (_req, res) => res.end('{"trusted":true}'));
await new Promise<void>((resolve) => https.listen(0, "127.0.0.1", resolve));
try {
const caller = await fixture("full", async (db) => {
await db.update(integrations).set({ url: `https://127.0.0.1:${(https.address() as AddressInfo).port}` });
});
await expect(caller.request(get)).rejects.toMatchObject({ code: "BAD_GATEWAY" });
trust.certificates.mockResolvedValue([cert]);
await expect(caller.request(get)).rejects.toMatchObject({ code: "BAD_GATEWAY" });
trust.hostnames.mockResolvedValue([
{ hostname: "127.0.0.1", thumbprint: new X509Certificate(cert).fingerprint256 },
]);
await expect(caller.request(get)).resolves.toMatchObject({ status: 200, data: { trusted: true } });
} finally {
trust.certificates.mockResolvedValue([]);
trust.hostnames.mockResolvedValue([]);
https.closeAllConnections();
await new Promise<void>((resolve) => https.close(() => resolve()));
}
});
test("denies GET without full permission even when another user has full access", async () => {
const caller = await fixture();
const before = calls.length;
await expect(caller.request(get)).rejects.toMatchObject({
code: "FORBIDDEN",
message: "Arbitrary integration requests require full integration access",
});
expect(calls).toHaveLength(before);
});
test.each(["GET", "POST", "PUT", "PATCH", "DELETE"] as const)(
"denies %s with only use permission",
async (method) => {
const caller = await fixture("use");
const before = calls.length;
await expect(caller.request({ ...get, method, confirmed: true })).rejects.toMatchObject({
code: "FORBIDDEN",
message: "Arbitrary integration requests require full integration access",
});
expect(calls).toHaveLength(before);
},
);
test("interact access does not authorize arbitrary endpoints", async () => {
const caller = await fixture("interact");
await expect(caller.request(get)).rejects.toMatchObject({
code: "FORBIDDEN",
message: "Arbitrary integration requests require full integration access",
});
});
test("DELETE requires confirmation and preserves deleteFiles", async () => {
const caller = await fixture("full");
const input = { ...get, method: "DELETE", path: "/api/v3/series/42?deleteFiles=true" } as const;
const before = calls.length;
await expect(caller.request(input)).rejects.toMatchObject({ code: "PRECONDITION_FAILED" });
expect(calls).toHaveLength(before);
await expect(caller.request({ ...input, confirmed: true })).resolves.toMatchObject({ status: 204, data: null });
expect(calls.at(-1)).toMatchObject({ method: "DELETE", path: input.path, auth: secret });
});
test("sends a JSON body with full access", async () => {
const caller = await fixture("full");
await caller.request({ ...get, method: "PATCH", body: { monitored: false } });
expect(calls.at(-1)?.body).toBe('{"monitored":false}');
});
test.each(["https://evil.com/x", "//evil.com/x"])("rejects %s before HTTP", async (path) => {
const caller = await fixture("full");
const before = calls.length;
await expect(caller.request({ ...get, path })).rejects.toMatchObject({ code: "BAD_REQUEST" });
expect(calls).toHaveLength(before);
});
test("never follows a redirect", async () => {
const caller = await fixture("full");
const before = calls.length;
await expect(caller.request({ ...get, path: "/redirect" })).rejects.toMatchObject({ code: "BAD_GATEWAY" });
expect(calls).toHaveLength(before + 1);
});
test("enforces the response and request caps", async () => {
const caller = await fixture("full");
await expect(caller.request({ ...get, path: "/large" })).rejects.toMatchObject({ code: "PAYLOAD_TOO_LARGE" });
await expect(caller.request({ ...get, method: "POST", body: "x".repeat(10 * 1024) })).rejects.toMatchObject({
code: "PAYLOAD_TOO_LARGE",
});
});
test("redacts upstream JSON and text, including error responses", async () => {
const caller = await fixture("full");
await expect(caller.request({ ...get, path: "/echo" })).resolves.toMatchObject({
status: 400,
data: { "[REDACTED]": ["[REDACTED]", "[REDACTED]", "[REDACTED]"] },
});
await expect(caller.request({ ...get, path: "/text" })).resolves.toMatchObject({
status: 500,
data: "invalid JSON [REDACTED]",
});
});
test("honors the executor's total deadline without logging credentials", async () => {
const logError = vi.fn();
await expect(
executeCustomWidgetRequest({
baseUrl,
targetUrl: `${baseUrl}/slow`,
method: "GET",
kind: "action",
timeoutMs: 30,
auth: { type: "apiKeyHeader", secrets: [{ kind: "apiKey", value: secret }] },
logError,
}),
).rejects.toMatchObject({ code: "BAD_GATEWAY", reason: "timeout" });
expect(JSON.stringify(logError.mock.calls)).not.toContain(secret);
});
});
describe("integration proxy public contract", () => {
test.each([{ integrationKind: "sonarr" as const }, { integrationName: "Sonarr" }])(
"selects the first authorized instance with %j",
async (selector) => {
const caller = await fixture(undefined, async (db) => {
await db.insert(integrations).values([
{ id: "b", name: "Sonarr", kind: "sonarr", url: baseUrl },
{ id: "a-denied", name: "Sonarr", kind: "sonarr", url: baseUrl },
{ id: "c", name: "Sonarr", kind: "sonarr", url: baseUrl },
]);
for (const id of ["b", "c"]) {
await db
.insert(integrationSecrets)
.values({ integrationId: id, kind: "apiKey", value: encryptSecret(secret) });
await db
.insert(integrationUserPermissions)
.values({ integrationId: id, userId: "reader", permission: "full" });
}
});
await expect(caller.request({ ...selector, path: "/api/v3/series" })).resolves.toMatchObject({
integration: { id: "b", name: "Sonarr", kind: "sonarr" },
ok: true,
});
},
);
test.each<z.input<typeof integrationRequestSchema>>([
{ path: "/x" },
{ integrationId: "sonarr", integrationName: "Sonarr", path: "/x" },
{ integrationName: "missing", path: "/x" },
{ integrationId: "sonarr", method: "HEAD" as const, path: "/x", body: "invalid" },
{ integrationId: "sonarr", method: "POST" as const, path: "/x", bodyEncoding: "raw" as const, body: {} },
{ integrationId: "sonarr", path: "/x", headers: { Host: "another-host" } },
{ integrationId: "sonarr", path: "/x", headers: { Authorization: "another-credential" } },
{ integrationId: "sonarr", path: "/x", headers: { a: "x".repeat(8192), b: "y".repeat(8192) } },
])("rejects invalid or unauthorized input before transmission (%#)", async (input) => {
const caller = await fixture("full");
const count = calls.length;
await expect(caller.request(input)).rejects.toThrow();
expect(calls).toHaveLength(count);
});
test("preserves reverse-proxy subpaths and rejects encoded path escapes before transmission", async () => {
const caller = await fixture("full", async (db) => {
await db.update(integrations).set({ url: `${baseUrl}/sonarr` });
});
await caller.request(get);
expect(calls.at(-1)?.path).toBe("/sonarr/api/v3/series");
const count = calls.length;
for (const path of ["../escape", "/%252e%252e/escape", "/%2f..%2fescape"])
await expect(caller.request({ ...get, path })).rejects.toMatchObject({ code: "BAD_REQUEST" });
expect(calls).toHaveLength(count);
});
test("keeps native authentication while forwarding raw form bodies and their content type", async () => {
const caller = await fixture("full");
await expect(
caller.request({
...get,
method: "POST",
path: "/inspect",
bodyEncoding: "raw",
body: "name=Example&enabled=true",
headers: { "Content-Type": "application/x-www-form-urlencoded", "X-API-Key": "caller-cannot-override" },
}),
).resolves.toMatchObject({
data: {
body: "name=Example&enabled=true",
contentType: "application/x-www-form-urlencoded",
auth: "[REDACTED]",
},
});
expect(calls.at(-1)?.auth).toBe(secret);
});
test.each(["HEAD", "OPTIONS"] as const)("supports %s without a body", async (method) => {
const caller = await fixture("full");
const result = await caller.request({ ...get, method });
expect(result.ok).toBe(true);
if (method === "HEAD") expect(result.data).toBeNull();
expect(calls.at(-1)).toMatchObject({ method, body: "" });
});
test.each(["gzip", "deflate", "br", "gzip, br"])("decodes %s and bounds expanded responses", async (encoding) => {
const caller = await fixture("full");
const input = { ...get, headers: { "Accept-Encoding": encoding } };
await expect(caller.request({ ...input, path: "/compressed" })).resolves.toMatchObject({
ok: true,
data: { value: "decoded", secret: "[REDACTED]" },
});
await expect(caller.request({ ...input, path: "/compressed-large" })).rejects.toMatchObject({
code: "PAYLOAD_TOO_LARGE",
});
});
test("sanitizes malformed compressed responses", async () => {
const caller = await fixture("full");
await expect(caller.request({ ...get, path: "/compressed-invalid" })).rejects.toMatchObject({
code: "BAD_GATEWAY",
message: "Invalid compressed upstream response",
});
});
test("REST and MCP expose the same result and permission boundary", async () => {
const context = await fixtureContext("full");
const request = () =>
new Request("http://homarr.local/api/integrations/request", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ ...get, path: "/echo" }),
});
const response = await createOpenApiFetchHandler({
req: request(),
endpoint: "/",
router: openApiRouter,
createContext: () => context,
});
expect(response.status).toBe(200);
const result = await response.json();
expect(result).toMatchObject({ ok: false, status: 400, integration: { id: "sonarr" } });
expect(JSON.stringify(result)).not.toContain(secret);
const tool = extractMcpToolsFromProcedures(router).tools.find((entry) => entry.name === "request");
expect(tool).toBeDefined();
if (!tool) throw new Error("Missing request MCP tool");
await expect(callMcpTool(router.createCaller(context), tool, { ...get, path: "/echo" })).resolves.toEqual(result);
const deniedContext = { ...context, session: null };
const count = calls.length;
const denied = await createOpenApiFetchHandler({
req: request(),
endpoint: "/",
router: openApiRouter,
createContext: () => deniedContext,
});
expect(denied.status).toBe(401);
await expect(callMcpTool(router.createCaller(deniedContext), tool, get)).rejects.toMatchObject({
code: "UNAUTHORIZED",
});
expect(calls).toHaveLength(count);
});
});