fix(integrations): gate mock integration server-side

.env.example

@@ -58,8 +58,8 @@ TURBO_TELEMETRY_DISABLED=1
 # Enable kubernetes tool
 # ENABLE_KUBERNETES=true
 
-# Enable mock integration
-UNSAFE_ENABLE_MOCK_INTEGRATION=true
+# Enable the development-only mock integration. Never enable this in production.
+# UNSAFE_ENABLE_MOCK_INTEGRATION=true
 
 # Public URL contract. Values must be absolute HTTP(S) URLs without credentials,
 # query strings, or fragments. Trailing slashes are normalized at startup.

apps/docs/docs/advanced/environment-variables/index.mdx

@@ -133,9 +133,10 @@ External redis is currently not supported with Proxmox Community Scripts
 The advanced deployments environment variables should only be used if you know what you are doing.
 :::
 
-| Environment Variable     | Description                                         |
-| ------------------------ | --------------------------------------------------- |
-| `DB_MIGRATIONS_DISABLED` | Disable db migrations. For example for helm charts. |
+| Environment Variable             | Description                                                                                                    | Default |
+| -------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------- |
+| `DB_MIGRATIONS_DISABLED`         | Disable database migrations. For example, when migrations are managed separately in Helm deployments.          | `false` |
+| `UNSAFE_ENABLE_MOCK_INTEGRATION` | Enable the development-only Mock integration. This exposes fabricated data and must not be used in production. | `false` |
 
 All public URL variables reject non-HTTP protocols, embedded credentials, query strings, and fragments, and normalize
 trailing slashes when Homarr or Docusaurus starts.

apps/nextjs/src/app/[locale]/manage/integrations/new/page.tsx

@@ -47,6 +47,9 @@ export default async function IntegrationsNewPage(props: NewIntegrationPageProps
   const tCreate = await getI18n("integration.page.create");
 
   const currentKind = result.data;
+  if (currentKind === "mock" && !env.UNSAFE_ENABLE_MOCK_INTEGRATION) {
+    notFound();
+  }
 
   return (
     <>

packages/api/src/env.ts

@@ -19,6 +19,7 @@ const publicHttpUrl = (variableName: string) =>
 export const env = createEnv({
   server: {
     KUBERNETES_SERVICE_ACCOUNT_NAME: z.string().optional(),
+    UNSAFE_ENABLE_MOCK_INTEGRATION: createBooleanSchema(false),
     DEMO_MODE: createBooleanSchema(false),
     DEMO_READ_ONLY: createBooleanSchema(true),
     HOMARR_WEBSITE_URL: publicHttpUrl("HOMARR_WEBSITE_URL").default("https://homarr.dev"),
@@ -27,6 +28,7 @@ export const env = createEnv({
   },
   runtimeEnv: {
     KUBERNETES_SERVICE_ACCOUNT_NAME: process.env.KUBERNETES_SERVICE_ACCOUNT_NAME,
+    UNSAFE_ENABLE_MOCK_INTEGRATION: process.env.UNSAFE_ENABLE_MOCK_INTEGRATION,
     DEMO_MODE: process.env.DEMO_MODE,
     DEMO_READ_ONLY: process.env.DEMO_READ_ONLY,
     HOMARR_WEBSITE_URL: process.env.HOMARR_WEBSITE_URL,

packages/api/src/router/integration/integration-router.ts

@@ -18,7 +18,12 @@ import {
   integrationSecrets,
   integrationUserPermissions,
 } from "@homarr/db/schema";
-import type { GroupPermissionKey, IntegrationPermission, IntegrationSecretKind } from "@homarr/definitions";
+import type {
+  GroupPermissionKey,
+  IntegrationKind,
+  IntegrationPermission,
+  IntegrationSecretKind,
+} from "@homarr/definitions";
 import {
   getIntegrationKindsByCategory,
   getPermissionsWithParents,
@@ -39,6 +44,7 @@ import {
 } from "@homarr/validation/integration";
 import { mediaRequestOptionsSchema, mediaRequestRequestSchema } from "@homarr/validation/widgets/media-request";
 
+import { env } from "../../env";
 import { createOneIntegrationMiddleware } from "../../middlewares/integration";
 import { createTRPCRouter, permissionRequiredProcedure, protectedProcedure, publicProcedure } from "../../trpc";
 import { throwIfActionForbiddenAsync } from "./integration-access";
@@ -48,6 +54,15 @@ import { mapTestConnectionError } from "./map-test-connection-error";
 const logger = createLogger({ module: "integrationRouter" });
 const mediaRequestSearchKinds = getIntegrationKindsByCategory("mediaSearch");
 
+const throwIfMockIntegrationIsDisabled = (kind: IntegrationKind) => {
+  if (kind !== "mock" || env.UNSAFE_ENABLE_MOCK_INTEGRATION) return;
+
+  throw new TRPCError({
+    code: "FORBIDDEN",
+    message: "Mock integrations are disabled",
+  });
+};
+
 export const integrationRouter = createTRPCRouter({
   getKinds: publicProcedure
     .meta({
@@ -58,12 +73,14 @@ export const integrationRouter = createTRPCRouter({
       },
     })
     .query(() => {
-      return objectEntries(integrationDefs).map(([kind, def]) => ({
-        kind,
-        name: def.name,
-        category: def.category,
-        requiredSecrets: def.secretKinds,
-      }));
+      return objectEntries(integrationDefs)
+        .filter(([kind]) => kind !== "mock" || env.UNSAFE_ENABLE_MOCK_INTEGRATION)
+        .map(([kind, def]) => ({
+          kind,
+          name: def.name,
+          category: def.category,
+          requiredSecrets: def.secretKinds,
+        }));
     }),
   all: protectedProcedure
     .meta({
@@ -229,6 +246,8 @@ export const integrationRouter = createTRPCRouter({
     })
     .input(integrationCreateSchema)
     .mutation(async ({ ctx, input }) => {
+      throwIfMockIntegrationIsDisabled(input.kind);
+
       logger.info("Creating integration", {
         name: input.name,
         kind: input.kind,

packages/api/src/router/onboard/onboard-router.ts

@@ -321,6 +321,13 @@ export const onboardRouter = createTRPCRouter({
     .requiresStep("setup")
     .input(onboardingCompleteSetupSchema)
     .mutation(async ({ ctx, input }) => {
+      if (
+        !env.UNSAFE_ENABLE_MOCK_INTEGRATION &&
+        input.integrations.some((integration) => integration.kind === "mock")
+      ) {
+        throw new TRPCError({ code: "FORBIDDEN", message: "Mock integrations are disabled" });
+      }
+
       const boardList = await ctx.db.query.boards.findMany({
         with: {
           sections: { with: { layouts: true } },

packages/integrations/src/nextcloud/nextcloud-url.ts

@@ -1,13 +0,0 @@
-export const createNextcloudCalendarServerUrl = (integrationUrl: string) => {
-  const calendarServerUrl = new URL(integrationUrl);
-  const integrationPath = calendarServerUrl.pathname.replace(/\/+$/, "");
-  const davPath = "/remote.php/dav";
-
-  calendarServerUrl.pathname = integrationPath.endsWith(davPath)
-    ? `${integrationPath}/`
-    : `${integrationPath}${davPath}/`;
-  calendarServerUrl.search = "";
-  calendarServerUrl.hash = "";
-
-  return calendarServerUrl.toString();
-};

packages/integrations/src/nextcloud/nextcloud.integration.ts

@@ -21,7 +21,6 @@ import type { ICalendarIntegration } from "../interfaces/calendar/calendar-integ
 import type { CalendarEvent } from "../interfaces/calendar/calendar-types";
 import type { Notification } from "../interfaces/notifications/notification-types";
 import type { INotificationsIntegration } from "../interfaces/notifications/notifications-integration";
-import { createNextcloudCalendarServerUrl } from "./nextcloud-url";
 
 // Register all existing timezones
 if (ICAL.TimezoneService.count === 0) {
@@ -190,7 +189,7 @@ export class NextcloudIntegration extends Integration implements ICalendarIntegr
 
   private async createCalendarClientAsync(agent?: Agent) {
     return new DAVClient({
-      serverUrl: createNextcloudCalendarServerUrl(this.integration.url),
+      serverUrl: this.integration.url,
       credentials: {
         username: this.getSecretValue("username"),
         password: this.getSecretValue("password"),

packages/integrations/src/nextcloud/test/nextcloud-integration.spec.ts

@@ -1,38 +0,0 @@
-import type { Agent } from "node:https";
-import { DAVClient } from "tsdav";
-import { beforeEach, describe, expect, test, vi } from "vitest";
-
-import { NextcloudIntegration } from "../nextcloud.integration";
-
-vi.mock("tsdav", () => ({ DAVClient: vi.fn() }));
-
-interface NextcloudCalendarClientFactory {
-  createCalendarClientAsync(agent: Agent): Promise<unknown>;
-}
-
-describe("NextcloudIntegration", () => {
-  beforeEach(() => {
-    vi.mocked(DAVClient).mockClear();
-  });
-
-  test("uses a calendar server URL that preserves the integration subpath", async () => {
-    const integration = new NextcloudIntegration({
-      id: "integration-id",
-      name: "Nextcloud",
-      url: "https://example.com/nextcloud",
-      externalUrl: null,
-      decryptedSecrets: [
-        { kind: "username", value: "admin" },
-        { kind: "password", value: "password" },
-      ],
-    });
-
-    await (integration as unknown as NextcloudCalendarClientFactory).createCalendarClientAsync({} as Agent);
-
-    expect(DAVClient).toHaveBeenCalledWith(
-      expect.objectContaining({
-        serverUrl: "https://example.com/nextcloud/remote.php/dav/",
-      }),
-    );
-  });
-});

packages/integrations/src/nextcloud/test/nextcloud-url.spec.ts

@@ -1,29 +0,0 @@
-import { describe, expect, test } from "vitest";
-
-import { createNextcloudCalendarServerUrl } from "../nextcloud-url";
-
-describe("createNextcloudCalendarServerUrl", () => {
-  test("uses the DAV endpoint for a root installation", () => {
-    expect(createNextcloudCalendarServerUrl("https://cloud.example.com")).toBe(
-      "https://cloud.example.com/remote.php/dav/",
-    );
-  });
-
-  test("preserves the base path for a subpath installation", () => {
-    expect(createNextcloudCalendarServerUrl("https://example.com/nextcloud")).toBe(
-      "https://example.com/nextcloud/remote.php/dav/",
-    );
-  });
-
-  test("does not duplicate a trailing slash", () => {
-    expect(createNextcloudCalendarServerUrl("https://example.com/nextcloud/")).toBe(
-      "https://example.com/nextcloud/remote.php/dav/",
-    );
-  });
-
-  test("does not duplicate an existing DAV endpoint", () => {
-    expect(createNextcloudCalendarServerUrl("https://example.com/nextcloud/remote.php/dav")).toBe(
-      "https://example.com/nextcloud/remote.php/dav/",
-    );
-  });
-});