From 99d5276cfa3c18357864995b4ac2b42202307d62 Mon Sep 17 00:00:00 2001
From: Linus Rath <139418639+rathlinus@users.noreply.github.com>
Date: Sun, 29 Mar 2026 00:47:35 +0100
Subject: [PATCH] feat: add support for custom JMAP server endpoints in login
 and settings

---
 .env.example                |  9 ++++++++-
 app/[locale]/login/page.tsx | 37 +++++++++++++++++++++++++++++++++----
 app/admin/settings/page.tsx |  8 ++++++++
 app/api/config/route.ts     |  1 +
 hooks/use-config.ts         |  4 ++++
 lib/admin/types.ts          |  1 +
 locales/en/common.json      |  3 +++
 7 files changed, 58 insertions(+), 5 deletions(-)

diff --git a/.env.example b/.env.example
index 86967030..777871b6 100644
--- a/.env.example
+++ b/.env.example
@@ -9,9 +9,16 @@
 # App name displayed in the UI
 APP_NAME=Bulwark Webmail
 
-# URL of your JMAP-compatible mail server (required)
+# URL of your JMAP-compatible mail server (required unless ALLOW_CUSTOM_JMAP_ENDPOINT is set)
 JMAP_SERVER_URL=https://your-jmap-server.com
 
+# Allow users to specify a custom JMAP server URL on the login form.
+# When enabled, a "JMAP Server" field appears on the login page.
+# Users can connect to any JMAP-compatible server.
+# NOTE: External JMAP servers must include this domain in their CORS
+# Access-Control-Allow-Origin header, or browser requests will be blocked.
+# ALLOW_CUSTOM_JMAP_ENDPOINT=true
+
 # =============================================================================
 # Stalwart Mail Server Integration
 # =============================================================================
diff --git a/app/[locale]/login/page.tsx b/app/[locale]/login/page.tsx
index 8741aefc..7ea19c32 100644
--- a/app/[locale]/login/page.tsx
+++ b/app/[locale]/login/page.tsx
@@ -32,13 +32,14 @@ export default function LoginPage() {
   const isAddAccountMode = searchParams.get("mode") === "add-account";
   const { login, loginDemo, isLoading, error, clearError, isAuthenticated } = useAuthStore();
   const { theme, setTheme, initializeTheme } = useThemeStore(useShallow((s) => ({ theme: s.theme, setTheme: s.setTheme, initializeTheme: s.initializeTheme })));
-  const { appName, jmapServerUrl: serverUrl, oauthEnabled, oauthOnly, oauthClientId, oauthIssuerUrl, rememberMeEnabled, devMode, demoMode, loginLogoLightUrl, loginLogoDarkUrl, loginCompanyName, loginImprintUrl, loginPrivacyPolicyUrl, loginWebsiteUrl, isLoading: configLoading, error: configError, autoSsoEnabled, embeddedMode: _embeddedMode } = useConfig();
+  const { appName, jmapServerUrl: serverUrl, oauthEnabled, oauthOnly, oauthClientId, oauthIssuerUrl, rememberMeEnabled, devMode, demoMode, loginLogoLightUrl, loginLogoDarkUrl, loginCompanyName, loginImprintUrl, loginPrivacyPolicyUrl, loginWebsiteUrl, isLoading: configLoading, error: configError, autoSsoEnabled, embeddedMode: _embeddedMode, allowCustomJmapEndpoint } = useConfig();
   const resolvedTheme = useThemeStore((s) => s.resolvedTheme);
 
   const [formData, setFormData] = useState({
     username: "",
     password: "",
   });
+  const [jmapEndpoint, setJmapEndpoint] = useState("");
   const [totpCode, setTotpCode] = useState("");
   const [showTotpField, setShowTotpField] = useState(false);
   const [rememberMe, setRememberMe] = useState(false);
@@ -73,6 +74,12 @@ export default function LoginPage() {
     }
   }, [appName, serverUrl]);
 
+  useEffect(() => {
+    if (serverUrl && !jmapEndpoint) {
+      setJmapEndpoint(serverUrl);
+    }
+  }, [serverUrl, jmapEndpoint]);
+
   useEffect(() => {
     try {
       if (sessionStorage.getItem('session_expired') === 'true') {
@@ -264,7 +271,7 @@ export default function LoginPage() {
     );
   }
 
-  if (!serverUrl && !demoMode) {
+  if (!serverUrl && !demoMode && !allowCustomJmapEndpoint) {
     return (
       <div className="min-h-screen flex items-center justify-center bg-gradient-to-br from-background to-muted/30">
         <div className="w-full max-w-md mx-auto px-4 text-center">
@@ -362,7 +369,7 @@ export default function LoginPage() {
 
     sessionStorage.setItem("oauth_code_verifier", verifier);
     sessionStorage.setItem("oauth_state", state);
-    sessionStorage.setItem("oauth_server_url", serverUrl!);
+    sessionStorage.setItem("oauth_server_url", allowCustomJmapEndpoint ? jmapEndpoint : serverUrl!);
     if (isAddAccountMode) {
       sessionStorage.setItem("oauth_add_account_mode", "true");
     }
@@ -382,8 +389,9 @@ export default function LoginPage() {
   const handleSubmit = async (e: React.FormEvent) => {
     e.preventDefault();
 
+    const effectiveServerUrl = allowCustomJmapEndpoint ? jmapEndpoint : serverUrl;
     const success = await login(
-      serverUrl,
+      effectiveServerUrl,
       formData.username,
       formData.password,
       totpCode || undefined,
@@ -749,6 +757,27 @@ export default function LoginPage() {
               /* Login Form */
               <form onSubmit={handleSubmit} className="space-y-5">
                 <fieldset disabled={isLoading} className="space-y-4">
+                  {/* JMAP Endpoint field (when custom endpoints are allowed) */}
+                  {allowCustomJmapEndpoint && (
+                    <div className="space-y-1.5">
+                      <label htmlFor="jmap-endpoint" className="block text-sm font-medium text-foreground">
+                        {t("jmap_endpoint_label")}
+                      </label>
+                      <Input
+                        id="jmap-endpoint"
+                        type="url"
+                        value={jmapEndpoint}
+                        onChange={(e) => setJmapEndpoint(e.target.value)}
+                        className="h-11 px-3.5 bg-muted/40 border-border/60 rounded-xl focus:bg-background focus:border-primary/50 transition-all duration-200"
+                        placeholder={t("jmap_endpoint_placeholder")}
+                        required
+                      />
+                      <p className="text-[11px] text-muted-foreground leading-snug">
+                        {t("jmap_endpoint_cors_hint")}
+                      </p>
+                    </div>
+                  )}
+
                   {/* Username field */}
                   <div className="space-y-1.5">
                     <label htmlFor="username" className="block text-sm font-medium text-foreground">
diff --git a/app/admin/settings/page.tsx b/app/admin/settings/page.tsx
index 804e12ba..24b12b35 100644
--- a/app/admin/settings/page.tsx
+++ b/app/admin/settings/page.tsx
@@ -112,6 +112,14 @@ export default function AdminSettingsPage() {
       <SettingsSection title="General">
         <TextSetting label="Application Name" configKey="appName" value={currentValue('appName') as string} source={config.appName?.source} onChange={handleChange} onRevert={handleRevert} />
         <TextSetting label="JMAP Server URL" configKey="jmapServerUrl" value={currentValue('jmapServerUrl') as string} source={config.jmapServerUrl?.source} onChange={handleChange} onRevert={handleRevert} placeholder="https://mail.example.com" />
+        <ToggleSetting label="Allow Custom JMAP Endpoint" description="Show a JMAP server URL field on the login form, allowing users to connect to any JMAP server" configKey="allowCustomJmapEndpoint" value={currentValue('allowCustomJmapEndpoint') as boolean} source={config.allowCustomJmapEndpoint?.source} onChange={handleChange} onRevert={handleRevert} />
+        {!!currentValue('allowCustomJmapEndpoint') && (
+          <div className="px-4 py-2.5 bg-amber-50 dark:bg-amber-950/30 border-l-2 border-amber-400 dark:border-amber-600">
+            <p className="text-xs text-amber-800 dark:text-amber-300 leading-relaxed">
+              <strong>CORS warning:</strong> External JMAP servers must include this domain in their CORS <code className="text-[11px] bg-amber-100 dark:bg-amber-900/50 px-1 py-0.5 rounded">Access-Control-Allow-Origin</code> header, or requests from the browser will be blocked.
+            </p>
+          </div>
+        )}
         <ToggleSetting label="Stalwart Features" description="Enable Stalwart Mail Server-specific features" configKey="stalwartFeaturesEnabled" value={currentValue('stalwartFeaturesEnabled') as boolean} source={config.stalwartFeaturesEnabled?.source} onChange={handleChange} onRevert={handleRevert} />
         <TextSetting label="Stalwart API URL" configKey="stalwartApiUrl" value={currentValue('stalwartApiUrl') as string} source={config.stalwartApiUrl?.source} onChange={handleChange} onRevert={handleRevert} placeholder="https://mail.example.com/api" />
         <ToggleSetting label="Demo Mode" description="Enable demo mode with sample data" configKey="demoMode" value={currentValue('demoMode') as boolean} source={config.demoMode?.source} onChange={handleChange} onRevert={handleRevert} />
diff --git a/app/api/config/route.ts b/app/api/config/route.ts
index c054c093..0b3f3bb8 100644
--- a/app/api/config/route.ts
+++ b/app/api/config/route.ts
@@ -47,6 +47,7 @@ export async function GET() {
     loginPrivacyPolicyUrl: configManager.get<string>('loginPrivacyPolicyUrl', ''),
     loginWebsiteUrl: configManager.get<string>('loginWebsiteUrl', ''),
     demoMode: configManager.get<boolean>('demoMode', false),
+    allowCustomJmapEndpoint: configManager.get<boolean>('allowCustomJmapEndpoint', false),
     autoSsoEnabled: configManager.get<boolean>('autoSsoEnabled', false),
     embeddedMode: !!allowedFrameAncestors && allowedFrameAncestors !== "'none'",
     parentOrigin: configManager.get<string>('parentOrigin', ''),
diff --git a/hooks/use-config.ts b/hooks/use-config.ts
index c7f9a004..c884ea05 100644
--- a/hooks/use-config.ts
+++ b/hooks/use-config.ts
@@ -25,6 +25,7 @@ interface ConfigData {
   loginWebsiteUrl: string;
   demoMode: boolean;
   autoSsoEnabled: boolean;
+  allowCustomJmapEndpoint: boolean;
   embeddedMode: boolean;
   parentOrigin: string;
 }
@@ -100,6 +101,7 @@ export function useConfig(): AppConfig {
     loginWebsiteUrl: configCache?.loginWebsiteUrl || '',
     demoMode: configCache?.demoMode || false,
     autoSsoEnabled: configCache?.autoSsoEnabled || false,
+    allowCustomJmapEndpoint: configCache?.allowCustomJmapEndpoint || false,
     embeddedMode: configCache?.embeddedMode || false,
     parentOrigin: configCache?.parentOrigin || '',
     isLoading: !configCache,
@@ -131,6 +133,7 @@ export function useConfig(): AppConfig {
         loginWebsiteUrl: configCache.loginWebsiteUrl,
         demoMode: configCache.demoMode,
         autoSsoEnabled: configCache.autoSsoEnabled,
+        allowCustomJmapEndpoint: configCache.allowCustomJmapEndpoint,
         embeddedMode: configCache.embeddedMode,
         parentOrigin: configCache.parentOrigin,
         isLoading: false,
@@ -163,6 +166,7 @@ export function useConfig(): AppConfig {
           loginWebsiteUrl: data.loginWebsiteUrl,
           demoMode: data.demoMode,
           autoSsoEnabled: data.autoSsoEnabled,
+          allowCustomJmapEndpoint: data.allowCustomJmapEndpoint,
           embeddedMode: data.embeddedMode,
           parentOrigin: data.parentOrigin,
           isLoading: false,
diff --git a/lib/admin/types.ts b/lib/admin/types.ts
index 37ac20b0..78797a3e 100644
--- a/lib/admin/types.ts
+++ b/lib/admin/types.ts
@@ -120,6 +120,7 @@ export const CONFIG_ENV_MAP: Record<string, { envVar: string; type: 'string' | '
   oauthClientId: { envVar: 'OAUTH_CLIENT_ID', type: 'string', defaultValue: '' },
   oauthClientSecret: { envVar: 'OAUTH_CLIENT_SECRET', type: 'string', defaultValue: '' },
   oauthIssuerUrl: { envVar: 'OAUTH_ISSUER_URL', type: 'url', defaultValue: '' },
+  allowCustomJmapEndpoint: { envVar: 'ALLOW_CUSTOM_JMAP_ENDPOINT', type: 'boolean', defaultValue: false },
   autoSsoEnabled: { envVar: 'AUTO_SSO_ENABLED', type: 'boolean', defaultValue: false },
   cookieSameSite: { envVar: 'COOKIE_SAME_SITE', type: 'enum', defaultValue: 'lax', enumValues: ['lax', 'strict', 'none'] },
   allowedFrameAncestors: { envVar: 'ALLOWED_FRAME_ANCESTORS', type: 'string', defaultValue: '' },
diff --git a/locales/en/common.json b/locales/en/common.json
index 21cdbd03..799f68b8 100644
--- a/locales/en/common.json
+++ b/locales/en/common.json
@@ -5,6 +5,9 @@
     "username_placeholder": "user@example.com",
     "password_label": "Password",
     "password_placeholder": "Enter your password",
+    "jmap_endpoint_label": "JMAP Server",
+    "jmap_endpoint_placeholder": "https://mail.example.com",
+    "jmap_endpoint_cors_hint": "The server must allow CORS requests from this domain.",
     "sign_in": "Sign in",
     "signing_in": "Signing in...",
     "loading": "Loading...",