feat(branding): customize login page title and logo via env vars (#3773) (#3781)

* feat(branding): customize login page title and logo via env vars (#3773)

Add CUSTOM_TITLE and CUSTOM_LOGO_URL environment variables so operators
deploying MeshMonitor for a community/organization can rebrand the login
page without forking and rebuilding the image.

- environment.ts: parse both vars; validate CUSTOM_LOGO_URL scheme
  (http(s)/data:image/relative only, rejecting javascript: etc.)
- authRoutes /status: expose branding (null when unset) pre-auth so the
  login page can read it
- AuthContext: optional customTitle/customLogoUrl on AuthStatus
- LoginPage: render custom logo image + title, falling back to the
  built-in SVG and "MeshMonitor" heading when unset
- docs + .env.example: document the new variables
- tests: cover default/null, set values, and unsafe-scheme rejection

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011JEaCGwY9Wz8jeV4e22GW4

* address review: drop stray files, reject SVG data URIs, tighten types/tests

- Remove three unrelated files that `git add -A` swept into the branch
  (.claude/agent-memory/* and docs/internal/dev-notes/MCP_SERVER_PLAN.md)
- CUSTOM_LOGO_URL: reject data:image/svg+xml (SVG can embed scripts);
  whitelist raster data: URIs (png/jpeg/gif/webp/avif) only
- AuthStatus.customTitle/customLogoUrl are now non-optional (string | null)
  to match the runtime guarantee that /status always sends them
- Add edge-case tests: whitespace-only title, SVG data URI rejected,
  raster data URI accepted
- Docs/.env.example note the SVG exclusion and relative-path origin

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011JEaCGwY9Wz8jeV4e22GW4

* address review: remove branch-only stray files from PR

These were untracked working-tree artifacts at branch creation that a
prior `git add -A` swept in. Untrack them (kept on disk locally).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011JEaCGwY9Wz8jeV4e22GW4

* address review: drop redundant client-side trim on branding values

The server already trims and normalizes CUSTOM_TITLE/CUSTOM_LOGO_URL
(null when unset), so the client-side .trim() was dead code.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011JEaCGwY9Wz8jeV4e22GW4

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Yeraze

.env.example

@@ -150,6 +150,18 @@ ALLOWED_ORIGINS=http://localhost:8080
 # Default: false (anonymous access allowed)
 # DISABLE_ANONYMOUS=true
 
+# Branding Configuration (login page)
+# CUSTOM_TITLE: Overrides the "MeshMonitor" heading shown on the login page.
+# Useful when deploying as a dashboard for a specific community or organization.
+# Default: "MeshMonitor"
+# CUSTOM_TITLE=My Organization Base
+#
+# CUSTOM_LOGO_URL: Overrides the default logo on the login page with your own image.
+# Accepts an http(s) URL, a raster data:image URI (png/jpeg/gif/webp/avif), or a
+# same-origin relative path. data:image/svg+xml is rejected (SVG can embed scripts).
+# Falls back to the built-in logo when unset or invalid.
+# CUSTOM_LOGO_URL=https://example.com/logo.png
+
 # Logging Configuration
 # LOG_LEVEL: Controls the verbosity of log output
 # Valid values: debug, info, warn, error

docs/configuration/index.md

@@ -194,6 +194,15 @@ See the [Push Notifications guide](/features/notifications) for setup instructio
 
 **Note**: `LOG_LEVEL` controls log output independently of `NODE_ENV`. This lets you enable debug logging in production Docker deployments without changing rate limits, cookie warnings, or other `NODE_ENV`-dependent behavior.
 
+### Branding Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CUSTOM_TITLE` | Overrides the "MeshMonitor" heading on the login page | `MeshMonitor` |
+| `CUSTOM_LOGO_URL` | Overrides the login-page logo with your own image (http(s), raster `data:image` — png/jpeg/gif/webp/avif, or same-origin relative URL) | built-in SVG |
+
+**Note**: Both are optional and apply only to the login page. When unset — or when `CUSTOM_LOGO_URL` uses an unsupported scheme such as `javascript:` or a `data:image/svg+xml` URI (rejected because SVG can embed scripts) — MeshMonitor falls back to the default title and logo. Relative paths are resolved against the server's own origin.
+
 ### System Management Variables
 
 | Variable | Description | Default |

src/components/LoginPage.css

@@ -40,6 +40,13 @@
   margin-bottom: 10px;
 }
 
+.login-logo-image {
+  width: 120px;
+  height: 120px;
+  object-fit: contain;
+  margin-bottom: 10px;
+}
+
 .login-logo h1 {
   font-size: 32px;
   font-weight: 700;

src/components/LoginPage.tsx

@@ -30,6 +30,12 @@ const LoginPage: React.FC = () => {
   const localAuthDisabled = authStatus?.localAuthDisabled ?? false;
   const oidcEnabled = authStatus?.oidcEnabled ?? false;
 
+  // Optional login-page branding from CUSTOM_TITLE / CUSTOM_LOGO_URL env vars.
+  // The server already trims/validates these and sends null when unset, so we
+  // just fall back to the default MeshMonitor title and inline SVG here.
+  const customTitle = authStatus?.customTitle || 'MeshMonitor';
+  const customLogoUrl = authStatus?.customLogoUrl || null;
+
   const handleLocalLogin = async (e: React.FormEvent) => {
     e.preventDefault();
     setError(null);
@@ -114,30 +120,40 @@ const LoginPage: React.FC = () => {
   return (
     <div className="login-page">
       <div className="login-container">
-        {/* MeshMonitor Logo */}
+        {/* Logo — custom image when CUSTOM_LOGO_URL is set, otherwise the default SVG */}
         <div className="login-logo">
-          <svg
-            width="120"
-            height="120"
-            viewBox="0 0 24 24"
-            fill="none"
-            xmlns="http://www.w3.org/2000/svg"
-          >
-            <path
-              d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm0 18c-4.41 0-8-3.59-8-8s3.59-8 8-8 8 3.59 8 8-3.59 8-8 8z"
-              fill="currentColor"
-            />
-            <circle cx="7" cy="12" r="1.5" fill="currentColor" />
-            <circle cx="12" cy="7" r="1.5" fill="currentColor" />
-            <circle cx="17" cy="12" r="1.5" fill="currentColor" />
-            <circle cx="12" cy="17" r="1.5" fill="currentColor" />
-            <path
-              d="M7 12L12 7M12 7L17 12M17 12L12 17M12 17L7 12"
-              stroke="currentColor"
-              strokeWidth="1"
+          {customLogoUrl ? (
+            <img
+              src={customLogoUrl}
+              alt={customTitle}
+              width="120"
+              height="120"
+              className="login-logo-image"
             />
-          </svg>
-          <h1>MeshMonitor</h1>
+          ) : (
+            <svg
+              width="120"
+              height="120"
+              viewBox="0 0 24 24"
+              fill="none"
+              xmlns="http://www.w3.org/2000/svg"
+            >
+              <path
+                d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm0 18c-4.41 0-8-3.59-8-8s3.59-8 8-8 8 3.59 8 8-3.59 8-8 8z"
+                fill="currentColor"
+              />
+              <circle cx="7" cy="12" r="1.5" fill="currentColor" />
+              <circle cx="12" cy="7" r="1.5" fill="currentColor" />
+              <circle cx="17" cy="12" r="1.5" fill="currentColor" />
+              <circle cx="12" cy="17" r="1.5" fill="currentColor" />
+              <path
+                d="M7 12L12 7M12 7L17 12M17 12L12 17M12 17L7 12"
+                stroke="currentColor"
+                strokeWidth="1"
+              />
+            </svg>
+          )}
+          <h1>{customTitle}</h1>
         </div>
 
         {/* Login Form */}

src/contexts/AuthContext.test.tsx

@@ -69,6 +69,8 @@ const mockAuthStatus = {
   oidcEnabled: false,
   localAuthDisabled: false,
   anonymousDisabled: false,
+  customTitle: null,
+  customLogoUrl: null,
 };
 
 const wrapper = ({ children }: { children: React.ReactNode }) => (

src/contexts/AuthContext.tsx

@@ -42,6 +42,12 @@ export interface AuthStatus {
   oidcEnabled: boolean;
   localAuthDisabled: boolean;
   anonymousDisabled: boolean;
+  /**
+   * Login-page branding from CUSTOM_TITLE / CUSTOM_LOGO_URL env vars.
+   * Always present in the /status response (null when unset).
+   */
+  customTitle: string | null;
+  customLogoUrl: string | null;
 }
 
 export interface LoginResult {
@@ -123,6 +129,8 @@ export const AuthProvider: React.FC<{ children: React.ReactNode }> = ({ children
         oidcEnabled: false,
         localAuthDisabled: false,
         anonymousDisabled: false,
+        customTitle: null,
+        customLogoUrl: null,
       });
     } finally {
       setLoading(false);

src/server/config/environment.ts

@@ -311,6 +311,12 @@ export interface EnvironmentConfig {
   // Logging
   logLevel: 'debug' | 'info' | 'warn' | 'error';
   logLevelProvided: boolean;
+
+  // Branding (login page customization)
+  customTitle: string | undefined;
+  customTitleProvided: boolean;
+  customLogoUrl: string | undefined;
+  customLogoUrlProvided: boolean;
 }
 
 /**
@@ -693,6 +699,35 @@ export function loadEnvironmentConfig(): EnvironmentConfig {
   const logLevelDefault: 'debug' | 'info' | 'warn' | 'error' = nodeEnv.value === 'development' ? 'debug' : 'info';
   const logLevel = parseEnum('LOG_LEVEL', process.env.LOG_LEVEL?.toLowerCase(), ['debug', 'info', 'warn', 'error'] as const, logLevelDefault);
 
+  // Branding (login page customization)
+  // CUSTOM_TITLE overrides the "MeshMonitor" heading on the login page.
+  // CUSTOM_LOGO_URL overrides the inline SVG logo with an external/relative image.
+  const customTitleRaw = process.env.CUSTOM_TITLE?.trim();
+  const customTitle = {
+    value: customTitleRaw || undefined,
+    wasProvided: !!customTitleRaw
+  };
+
+  const customLogoUrlRaw = process.env.CUSTOM_LOGO_URL?.trim();
+  let customLogoUrl = { value: customLogoUrlRaw || undefined, wasProvided: !!customLogoUrlRaw };
+  // Only allow safe URL schemes for the logo image. http(s), protocol-relative,
+  // same-origin relative paths, and raster data:image URIs are accepted.
+  // data:image/svg+xml is intentionally rejected — SVG can embed <script>, and
+  // anything else (e.g. javascript:) is rejected to avoid surfacing a hostile
+  // URL in markup.
+  if (customLogoUrl.value) {
+    const v = customLogoUrl.value;
+    const safe =
+      /^https?:\/\//i.test(v) ||
+      /^\/\//.test(v) ||
+      /^data:image\/(png|jpe?g|gif|webp|avif)[;,]/i.test(v) ||
+      v.startsWith('/');
+    if (!safe) {
+      logger.warn(`⚠️  Invalid CUSTOM_LOGO_URL value: "${v}". Expected an http(s), raster data:image (png/jpeg/gif/webp/avif — not svg), or relative URL. Ignoring.`);
+      customLogoUrl = { value: undefined, wasProvided: false };
+    }
+  }
+
   // Log effective environment configuration at startup
   const src = (provided: boolean) => provided ? 'env' : 'default';
   logger.info('📋 Environment configuration:');
@@ -770,6 +805,11 @@ export function loadEnvironmentConfig(): EnvironmentConfig {
     logger.info(`   ACCESS_LOG_PATH: ${accessLogPath.value} (${src(accessLogPath.wasProvided)})`);
     logger.info(`   ACCESS_LOG_FORMAT: ${accessLogFormat.value} (${src(accessLogFormat.wasProvided)})`);
   }
+  if (customTitle.wasProvided || customLogoUrl.wasProvided) {
+    logger.info('   --- Branding ---');
+    if (customTitle.wasProvided) logger.info(`   CUSTOM_TITLE: ${customTitle.value}`);
+    if (customLogoUrl.wasProvided) logger.info(`   CUSTOM_LOGO_URL: ${customLogoUrl.value}`);
+  }
 
   return {
     // Node environment
@@ -904,7 +944,13 @@ export function loadEnvironmentConfig(): EnvironmentConfig {
 
     // Logging
     logLevel: logLevel.value,
-    logLevelProvided: logLevel.wasProvided
+    logLevelProvided: logLevel.wasProvided,
+
+    // Branding (login page customization)
+    customTitle: customTitle.value,
+    customTitleProvided: customTitle.wasProvided,
+    customLogoUrl: customLogoUrl.value,
+    customLogoUrlProvided: customLogoUrl.wasProvided
   };
 }
 

src/server/routes/authRoutes.test.ts

@@ -1083,4 +1083,89 @@ describe('Authentication Routes', () => {
       expect(response.status).toBe(400);
     });
   });
+
+  describe('Login Branding (CUSTOM_TITLE / CUSTOM_LOGO_URL)', () => {
+    let originalTitle: string | undefined;
+    let originalLogo: string | undefined;
+
+    beforeEach(() => {
+      originalTitle = process.env.CUSTOM_TITLE;
+      originalLogo = process.env.CUSTOM_LOGO_URL;
+    });
+
+    afterEach(async () => {
+      if (originalTitle !== undefined) process.env.CUSTOM_TITLE = originalTitle;
+      else delete process.env.CUSTOM_TITLE;
+      if (originalLogo !== undefined) process.env.CUSTOM_LOGO_URL = originalLogo;
+      else delete process.env.CUSTOM_LOGO_URL;
+
+      const { resetEnvironmentConfig } = await import('../config/environment.js');
+      resetEnvironmentConfig();
+    });
+
+    it('returns null branding by default', async () => {
+      delete process.env.CUSTOM_TITLE;
+      delete process.env.CUSTOM_LOGO_URL;
+      const { resetEnvironmentConfig } = await import('../config/environment.js');
+      resetEnvironmentConfig();
+
+      const response = await request(app).get('/api/auth/status').expect(200);
+
+      expect(response.body.customTitle).toBeNull();
+      expect(response.body.customLogoUrl).toBeNull();
+    });
+
+    it('exposes CUSTOM_TITLE and CUSTOM_LOGO_URL when set', async () => {
+      process.env.CUSTOM_TITLE = 'My Organization Base';
+      process.env.CUSTOM_LOGO_URL = 'https://example.com/logo.png';
+      const { resetEnvironmentConfig } = await import('../config/environment.js');
+      resetEnvironmentConfig();
+
+      const response = await request(app).get('/api/auth/status').expect(200);
+
+      expect(response.body.customTitle).toBe('My Organization Base');
+      expect(response.body.customLogoUrl).toBe('https://example.com/logo.png');
+    });
+
+    it('rejects an unsafe logo URL scheme', async () => {
+      process.env.CUSTOM_LOGO_URL = 'javascript:alert(1)';
+      const { resetEnvironmentConfig } = await import('../config/environment.js');
+      resetEnvironmentConfig();
+
+      const response = await request(app).get('/api/auth/status').expect(200);
+
+      expect(response.body.customLogoUrl).toBeNull();
+    });
+
+    it('treats a whitespace-only CUSTOM_TITLE as unset', async () => {
+      process.env.CUSTOM_TITLE = '   ';
+      const { resetEnvironmentConfig } = await import('../config/environment.js');
+      resetEnvironmentConfig();
+
+      const response = await request(app).get('/api/auth/status').expect(200);
+
+      expect(response.body.customTitle).toBeNull();
+    });
+
+    it('rejects an SVG data: URI logo (can embed scripts)', async () => {
+      process.env.CUSTOM_LOGO_URL = 'data:image/svg+xml,<svg onload="alert(1)"></svg>';
+      const { resetEnvironmentConfig } = await import('../config/environment.js');
+      resetEnvironmentConfig();
+
+      const response = await request(app).get('/api/auth/status').expect(200);
+
+      expect(response.body.customLogoUrl).toBeNull();
+    });
+
+    it('accepts a raster data: URI logo', async () => {
+      const png = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==';
+      process.env.CUSTOM_LOGO_URL = png;
+      const { resetEnvironmentConfig } = await import('../config/environment.js');
+      resetEnvironmentConfig();
+
+      const response = await request(app).get('/api/auth/status').expect(200);
+
+      expect(response.body.customLogoUrl).toBe(png);
+    });
+  });
 });

src/server/routes/authRoutes.ts

@@ -43,8 +43,15 @@ function regenerateSession(req: Request): Promise<void> {
 // Get authentication status
 router.get('/status', async (req: Request, res: Response) => {
   try {
-    const localAuthDisabled = getEnvironmentConfig().disableLocalAuth;
-    const anonymousDisabled = getEnvironmentConfig().disableAnonymous;
+    const envConfig = getEnvironmentConfig();
+    const localAuthDisabled = envConfig.disableLocalAuth;
+    const anonymousDisabled = envConfig.disableAnonymous;
+
+    // Public branding config for the login page (safe to expose pre-auth).
+    const branding = {
+      customTitle: envConfig.customTitle ?? null,
+      customLogoUrl: envConfig.customLogoUrl ?? null,
+    };
 
     if (!req.session.userId) {
       // Check if the session cookie exists at all
@@ -76,6 +83,7 @@ router.get('/status', async (req: Request, res: Response) => {
         oidcEnabled: isOIDCEnabled(),
         localAuthDisabled,
         anonymousDisabled,
+        ...branding,
       });
     }
 
@@ -101,6 +109,7 @@ router.get('/status', async (req: Request, res: Response) => {
         oidcEnabled: isOIDCEnabled(),
         localAuthDisabled,
         anonymousDisabled,
+        ...branding,
       });
     }
 
@@ -117,6 +126,7 @@ router.get('/status', async (req: Request, res: Response) => {
       oidcEnabled: isOIDCEnabled(),
       localAuthDisabled,
       anonymousDisabled,
+      ...branding,
     });
   } catch (error) {
     logger.error('Error getting auth status:', error);