From a5a4f1cdefcfcd70a196fa005acfc9b2b4bbd74f Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Thu, 27 Aug 2026 15:20:24 +0800
Subject: [PATCH 1/2] feat(map): configurable Leaflet tile provider + keyless
 OpenStreetMap default

CARTO's basemaps.cartocdn.com raster tiles now require an API key
(https://carto.com/basemaps/apikey/) and render 'API key required'
watermarks on every Fleetbase instance using the Leaflet map.

- Default all Leaflet maps to the keyless OpenStreetMap tile server
- Add Leaflet tile provider URL settings (light + dark mode) to
  Fleet-Ops map settings, persisted per-company via the existing
  fleet-ops/settings/map endpoint
- Resolve tile URLs through the map-settings service / a new
  leaflet-tile-url helper so a custom provider (including keyed
  CARTO URLs) applies across all console Leaflet maps
- Sanitize custom tile URLs server-side (http/https only)
---
 .template-lintrc.js                           |  2 ++
 addon/components/ai/route-preview-map.js      |  6 +---
 addon/components/customer/orders.js           |  3 +-
 addon/components/map/leaflet-live-map.js      | 23 +++-----------
 addon/components/modals/place-details.hbs     |  2 +-
 addon/components/modals/point-map.hbs         |  2 +-
 addon/components/orchestrator-workbench.js    |  3 +-
 addon/components/order-tracking-lookup.js     |  3 +-
 addon/components/place/details.hbs            |  2 +-
 addon/components/positions-replay.js          |  5 ++-
 addon/components/service-area/details.hbs     |  2 +-
 addon/components/widget/live-fleet.js         | 14 ++++-----
 addon/components/zone/details.hbs             |  2 +-
 addon/controllers/settings/map.js             | 16 ++++++++++
 addon/helpers/leaflet-tile-url.js             | 19 ++++++++++++
 addon/services/map-settings.js                | 22 +++++++++++++
 addon/templates/settings/map.hbs              | 10 ++++++
 addon/utils/leaflet-tile-url.js               | 31 +++++++++++++++++++
 app/helpers/leaflet-tile-url.js               |  1 +
 app/utils/leaflet-tile-url.js                 |  1 +
 .../Internal/v1/SettingController.php         | 22 +++++++++++++
 translations/en-us.yaml                       |  4 +++
 22 files changed, 155 insertions(+), 40 deletions(-)
 create mode 100644 addon/helpers/leaflet-tile-url.js
 create mode 100644 addon/utils/leaflet-tile-url.js
 create mode 100644 app/helpers/leaflet-tile-url.js
 create mode 100644 app/utils/leaflet-tile-url.js

diff --git a/.template-lintrc.js b/.template-lintrc.js
index 46748176d..09a3d8350 100644
--- a/.template-lintrc.js
+++ b/.template-lintrc.js
@@ -10,5 +10,7 @@ module.exports = {
         'link-href-attributes': 'off',
         'require-input-label': 'off',
         'no-array-prototype-extensions': 'off',
+        // `leaflet-tile-url` is a zero-argument helper resolving the configured tile provider
+        'no-implicit-this': { allow: ['leaflet-tile-url'] },
     },
 };
diff --git a/addon/components/ai/route-preview-map.js b/addon/components/ai/route-preview-map.js
index be7e145f0..c5f3ee3dd 100644
--- a/addon/components/ai/route-preview-map.js
+++ b/addon/components/ai/route-preview-map.js
@@ -168,11 +168,7 @@ export default class AiRoutePreviewMapComponent extends Component {
     get tileUrl() {
         const theme = document.body?.dataset?.theme;
 
-        if (theme === 'dark') {
-            return 'https://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}{r}.png';
-        }
-
-        return 'https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png';
+        return this.mapSettings.getLeafletTileUrl(theme === 'dark' ? 'dark' : 'light');
     }
 
     get emptyText() {
diff --git a/addon/components/customer/orders.js b/addon/components/customer/orders.js
index c20df8d33..1de736c0b 100644
--- a/addon/components/customer/orders.js
+++ b/addon/components/customer/orders.js
@@ -9,6 +9,7 @@ import { debug } from '@ember/debug';
 import { task, timeout } from 'ember-concurrency';
 import { Control as RoutingControl } from '@fleetbase/leaflet-routing-machine';
 import engineService from '@fleetbase/ember-core/decorators/engine-service';
+import { DEFAULT_LEAFLET_TILE_URL } from '../../utils/leaflet-tile-url';
 import registerComponent from '@fleetbase/ember-core/utils/register-component';
 import OrderProgressCardComponent from '../order-progress-card';
 import DisplayPlaceComponent from '../display-place';
@@ -38,7 +39,7 @@ export default class CustomerOrdersComponent extends Component {
     @tracked longitude;
     @tracked route;
     @tracked query;
-    @tracked tileSourceUrl = 'https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png';
+    @tracked tileSourceUrl = DEFAULT_LEAFLET_TILE_URL;
     @tracked scheduledAt;
     @tracked deliveryInstructions = {};
 
diff --git a/addon/components/map/leaflet-live-map.js b/addon/components/map/leaflet-live-map.js
index fd4b44d86..ae7727f8a 100644
--- a/addon/components/map/leaflet-live-map.js
+++ b/addon/components/map/leaflet-live-map.js
@@ -48,7 +48,6 @@ export default class MapLeafletLiveMapComponent extends Component {
     @tracked latitude = this.location.getLatitude();
     @tracked longitude = this.location.getLongitude();
     @tracked contextmenuItems = [];
-    @tracked tileUrl = 'https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png';
     @tracked theme = 'light';
     @tracked routes = [];
     @tracked drivers = [];
@@ -57,6 +56,10 @@ export default class MapLeafletLiveMapComponent extends Component {
     @tracked leafletPluginsReady = hasLeafletPluginsReady();
     _viewportReloadLocks = new Set();
 
+    get tileUrl() {
+        return this.mapSettings.getLeafletTileUrl(this.theme);
+    }
+
     constructor() {
         super(...arguments);
 
@@ -888,22 +891,4 @@ export default class MapLeafletLiveMapComponent extends Component {
         // Fallback to default Singapore longitude
         return 103.8864;
     }
-
-    #changeTileSource(source) {
-        switch (source) {
-            case 'dark':
-                this.theme = 'dark';
-                this.tileUrl = 'https://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}{r}.png';
-                break;
-            case 'custom':
-                this.theme = 'custom';
-                this.tileUrl = source.startsWith('https://') ? source : 'https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png';
-                break;
-            case 'light':
-            default:
-                this.theme = 'light';
-                this.tileUrl = 'https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png';
-                break;
-        }
-    }
 }
diff --git a/addon/components/modals/place-details.hbs b/addon/components/modals/place-details.hbs
index 4b49a002b..6be51d8a1 100644
--- a/addon/components/modals/place-details.hbs
+++ b/addon/components/modals/place-details.hbs
@@ -3,7 +3,7 @@
         <div class="flex">
             <div class="w-48 mb-6 mr-6">
                 <LeafletMap class="w-full h-48 mb-2 rounded-md shadow-md" @lat={{@options.place.latitude}} @lng={{@options.place.longitude}} @zoom={{12}} as |layers|>
-                    <layers.tile @url="https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png" />
+                    <layers.tile @url={{leaflet-tile-url}} />
 
                     <layers.marker @location={{@options.place.coordinates}} />
                 </LeafletMap>
diff --git a/addon/components/modals/point-map.hbs b/addon/components/modals/point-map.hbs
index 0b78d5a35..308f5e2b7 100644
--- a/addon/components/modals/point-map.hbs
+++ b/addon/components/modals/point-map.hbs
@@ -1,7 +1,7 @@
 <Modal::Default @modalIsOpened={{@modalIsOpened}} @options={{@options}} @confirm={{@onConfirm}} @decline={{@onDecline}}>
     <div class="fleetbase-leaflet-map-container">
         <LeafletMap class="map-height-base" @lat={{@options.latitude}} @lng={{@options.longitude}} @zoom={{12}} as |layers|>
-            <layers.tile @url="https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png" />
+            <layers.tile @url={{leaflet-tile-url}} />
 
             <layers.marker @icon={{@options.icon}} @location={{point-to-coordinates @options.location}} @riseOnHover={{true}} as |marker|>
                 <marker.popup @maxWidth="500" @minWidth="180">
diff --git a/addon/components/orchestrator-workbench.js b/addon/components/orchestrator-workbench.js
index d748789c0..2c63fedd8 100644
--- a/addon/components/orchestrator-workbench.js
+++ b/addon/components/orchestrator-workbench.js
@@ -36,6 +36,7 @@ export default class OrchestratorWorkbenchComponent extends Component {
     @service modalsManager;
     @service location;
     @service mapManager;
+    @service mapSettings;
     @service routeEngine;
     @service('order-allocation') allocationService;
 
@@ -661,7 +662,7 @@ export default class OrchestratorWorkbenchComponent extends Component {
 
     get tileSourceUrl() {
         const isDark = document.documentElement.classList.contains('dark');
-        return isDark ? 'https://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}{r}.png' : 'https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}{r}.png';
+        return this.mapSettings.getLeafletTileUrl(isDark ? 'dark' : 'light');
     }
 
     // ── Computed helpers ──────────────────────────────────────────────────────
diff --git a/addon/components/order-tracking-lookup.js b/addon/components/order-tracking-lookup.js
index f341833e1..8067095f1 100644
--- a/addon/components/order-tracking-lookup.js
+++ b/addon/components/order-tracking-lookup.js
@@ -10,6 +10,7 @@ import { task } from 'ember-concurrency';
 import { OSRMv1, Control as RoutingControl } from '@fleetbase/leaflet-routing-machine';
 import getRoutingHost from '@fleetbase/ember-core/utils/get-routing-host';
 import engineService from '@fleetbase/ember-core/decorators/engine-service';
+import { DEFAULT_LEAFLET_TILE_URL } from '../utils/leaflet-tile-url';
 
 export default class OrderTrackingLookupComponent extends Component {
     @service urlSearchParams;
@@ -28,7 +29,7 @@ export default class OrderTrackingLookupComponent extends Component {
     @tracked latitude;
     @tracked longitude;
     @tracked route;
-    @tracked tileSourceUrl = 'https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png';
+    @tracked tileSourceUrl = DEFAULT_LEAFLET_TILE_URL;
 
     constructor() {
         super(...arguments);
diff --git a/addon/components/place/details.hbs b/addon/components/place/details.hbs
index bb057a8f8..cb2d9e7e4 100644
--- a/addon/components/place/details.hbs
+++ b/addon/components/place/details.hbs
@@ -75,7 +75,7 @@
             @zoomControl={{false}}
             as |layers|
         >
-            <layers.tile @url="https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png" />
+            <layers.tile @url={{leaflet-tile-url}} />
             <layers.marker
                 @id={{@resource.id}}
                 @icon={{icon iconUrl=(or @resource.avatar_url "/engines-dist/images/building-marker.png") iconSize=(array 40 40)}}
diff --git a/addon/components/positions-replay.js b/addon/components/positions-replay.js
index 51415a5c0..b7f9dcecc 100644
--- a/addon/components/positions-replay.js
+++ b/addon/components/positions-replay.js
@@ -15,6 +15,7 @@ export default class PositionsReplayComponent extends Component {
     @service positionPlayback;
     @service notifications;
     @service location;
+    @service mapSettings;
 
     /** Component ID */
     id = guidFor(this);
@@ -29,7 +30,9 @@ export default class PositionsReplayComponent extends Component {
     @tracked latitude = this.args.resource.latitude || this.location.getLatitude();
     @tracked longitude = this.args.resource.longitude || this.location.getLongitude();
     @tracked zoom = 14;
-    @tracked tileUrl = 'https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png';
+    get tileUrl() {
+        return this.mapSettings.getLeafletTileUrl('light');
+    }
 
     /** Computed properties - read state from service */
     get isReplaying() {
diff --git a/addon/components/service-area/details.hbs b/addon/components/service-area/details.hbs
index 7d28bdbb5..3068c00e7 100644
--- a/addon/components/service-area/details.hbs
+++ b/addon/components/service-area/details.hbs
@@ -27,7 +27,7 @@
             @zoomControl={{false}}
             as |layers|
         >
-            <layers.tile @url="https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png" />
+            <layers.tile @url={{leaflet-tile-url}} />
             <layers.polygon
                 @id={{@resource.id}}
                 @record={{@resource}}
diff --git a/addon/components/widget/live-fleet.js b/addon/components/widget/live-fleet.js
index 63e664e0f..84600f692 100644
--- a/addon/components/widget/live-fleet.js
+++ b/addon/components/widget/live-fleet.js
@@ -8,15 +8,11 @@ import { task } from 'ember-concurrency';
 import { renderCompleted, waitForInsertedAndSized } from '@fleetbase/ember-ui/utils/dom';
 import LeafletTrackingMarkerComponent from '../leaflet-tracking-marker';
 import ensureLeafletDrawEditNamespace from '../../utils/leaflet-draw-namespace-guard';
+import { DEFAULT_LEAFLET_TILE_ATTRIBUTION } from '../../utils/leaflet-tile-url';
 
 const DEFAULT_CENTER = [1.31, 103.85];
 const DEFAULT_ZOOM = 11;
-// Match the rest of fleetops' Leaflet maps (light Carto basemap), which keeps the
-// dashboard styling consistent with the operational live map. Falls back gracefully
-// in dark mode via the next-leaflet-container-map theming.
-const TILE_URL = 'https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png';
-const TILE_URL_DARK = 'https://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png';
-const TILE_ATTRIBUTION = '&copy; OpenStreetMap contributors &copy; CARTO';
+const TILE_ATTRIBUTION = DEFAULT_LEAFLET_TILE_ATTRIBUTION;
 const RECONCILE_INTERVAL_MS = 5 * 60_000;
 
 /**
@@ -30,6 +26,7 @@ export default class WidgetLiveFleetComponent extends Component {
     @service fetch;
     @service socket;
     @service currentUser;
+    @service mapSettings;
 
     @tracked data = null;
     @tracked error = null;
@@ -38,7 +35,7 @@ export default class WidgetLiveFleetComponent extends Component {
 
     get tileUrl() {
         const isDark = typeof document !== 'undefined' && document.documentElement?.dataset?.theme === 'dark';
-        return isDark ? TILE_URL_DARK : TILE_URL;
+        return this.mapSettings.getLeafletTileUrl(isDark ? 'dark' : 'light');
     }
 
     socketChannel = null;
@@ -78,6 +75,9 @@ export default class WidgetLiveFleetComponent extends Component {
         this.#ensureTrackingMarkerRegistered();
         this.#patchLeafletDrawInitHook();
         this.#resetMapDeferred();
+        // Widgets can render before the fleetops engine boots, so make sure the
+        // company's map settings (custom tile provider URL) are loaded.
+        this.mapSettings.load();
         this.load.perform();
         this.subscribe();
         this.reconcileTimer = setInterval(() => this.load.perform(), RECONCILE_INTERVAL_MS);
diff --git a/addon/components/zone/details.hbs b/addon/components/zone/details.hbs
index d7af87681..284582073 100644
--- a/addon/components/zone/details.hbs
+++ b/addon/components/zone/details.hbs
@@ -22,7 +22,7 @@
             @zoomControl={{false}}
             as |layers|
         >
-            <layers.tile @url="https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png" />
+            <layers.tile @url={{leaflet-tile-url}} />
             <layers.polygon
                 @id={{@resource.id}}
                 @record={{@resource}}
diff --git a/addon/controllers/settings/map.js b/addon/controllers/settings/map.js
index 2ac378e26..7639bdf3d 100644
--- a/addon/controllers/settings/map.js
+++ b/addon/controllers/settings/map.js
@@ -33,6 +33,8 @@ export default class SettingsMapController extends Controller {
      * @var {String}
      */
     @tracked mapProvider = 'leaflet';
+    @tracked leafletTileUrl = '';
+    @tracked leafletDarkTileUrl = '';
     @tracked googleMapsMapType = 'roadmap';
     @tracked showGoogleMapsTrafficLayer = false;
     @tracked showGoogleMapsTransitLayer = false;
@@ -62,6 +64,16 @@ export default class SettingsMapController extends Controller {
         return this.mapProvider === 'google';
     }
 
+    /**
+     * True when the user has selected Leaflet as the provider.
+     *
+     * @memberof SettingsMapController
+     * @return {Boolean}
+     */
+    get isLeafletSelected() {
+        return this.mapProvider === 'leaflet';
+    }
+
     // ─── Actions ───────────────────────────────────────────────────────────────
 
     /**
@@ -77,6 +89,8 @@ export default class SettingsMapController extends Controller {
     @task *saveSettings() {
         const settings = {
             mapProvider: this.mapProvider,
+            leafletTileUrl: (this.leafletTileUrl ?? '').trim(),
+            leafletDarkTileUrl: (this.leafletDarkTileUrl ?? '').trim(),
             googleMapsMapType: this.googleMapsMapType,
             showGoogleMapsTrafficLayer: this.showGoogleMapsTrafficLayer,
             showGoogleMapsTransitLayer: this.showGoogleMapsTransitLayer,
@@ -105,6 +119,8 @@ export default class SettingsMapController extends Controller {
             const response = yield this.mapSettings.load({ force: true });
 
             this.mapProvider = response?.mapProvider ?? 'leaflet';
+            this.leafletTileUrl = response?.leafletTileUrl ?? '';
+            this.leafletDarkTileUrl = response?.leafletDarkTileUrl ?? '';
             this.googleMapsMapType = response?.googleMapsMapType ?? 'roadmap';
             this.showGoogleMapsTrafficLayer = Boolean(response?.showGoogleMapsTrafficLayer);
             this.showGoogleMapsTransitLayer = Boolean(response?.showGoogleMapsTransitLayer);
diff --git a/addon/helpers/leaflet-tile-url.js b/addon/helpers/leaflet-tile-url.js
new file mode 100644
index 000000000..681cee375
--- /dev/null
+++ b/addon/helpers/leaflet-tile-url.js
@@ -0,0 +1,19 @@
+import Helper from '@ember/component/helper';
+import { inject as service } from '@ember/service';
+
+/**
+ * Resolves the Leaflet tile URL from Fleet-Ops map settings.
+ *
+ * Usage:
+ *   <layers.tile @url={{leaflet-tile-url}} />
+ *   <layers.tile @url={{leaflet-tile-url theme="dark"}} />
+ *
+ * Recomputes automatically when map settings load or change.
+ */
+export default class LeafletTileUrlHelper extends Helper {
+    @service mapSettings;
+
+    compute(_params, { theme = 'light' } = {}) {
+        return this.mapSettings.getLeafletTileUrl(theme);
+    }
+}
diff --git a/addon/services/map-settings.js b/addon/services/map-settings.js
index 4267c0b67..fae705bbd 100644
--- a/addon/services/map-settings.js
+++ b/addon/services/map-settings.js
@@ -1,9 +1,12 @@
 import Service from '@ember/service';
 import { tracked } from '@glimmer/tracking';
 import { inject as service } from '@ember/service';
+import { getLeafletTileUrl } from '../utils/leaflet-tile-url';
 
 const DEFAULT_SETTINGS = {
     mapProvider: 'leaflet',
+    leafletTileUrl: '',
+    leafletDarkTileUrl: '',
     googleMapsApiKey: '',
     googleMapsMapId: '',
     googleMapsMapType: 'roadmap',
@@ -45,6 +48,25 @@ export default class MapSettingsService extends Service {
         return this.mapProvider === 'google';
     }
 
+    get leafletTileUrl() {
+        return this.getLeafletTileUrl('light');
+    }
+
+    get leafletDarkTileUrl() {
+        return this.getLeafletTileUrl('dark');
+    }
+
+    /**
+     * Resolve the Leaflet tile URL for a theme, preferring the company's
+     * configured custom tile provider and falling back to the keyless default.
+     *
+     * @param {String} theme 'light' or 'dark'
+     * @return {String}
+     */
+    getLeafletTileUrl(theme = 'light') {
+        return getLeafletTileUrl(this.settings, theme);
+    }
+
     async load({ force = false } = {}) {
         if (!force && this.isLoaded) {
             return this.settings;
diff --git a/addon/templates/settings/map.hbs b/addon/templates/settings/map.hbs
index 065d99393..fe65273b5 100644
--- a/addon/templates/settings/map.hbs
+++ b/addon/templates/settings/map.hbs
@@ -31,6 +31,16 @@
                         />
                     </InputGroup>
 
+                    {{#if this.isLeafletSelected}}
+                        <InputGroup @name={{t "settings.map.leaflet-tile-url"}} @helpText={{t "settings.map.leaflet-tile-url-help-text"}}>
+                            <Input @type="text" @value={{this.leafletTileUrl}} placeholder="https://tile.openstreetmap.org/{z}/{x}/{y}.png" class="w-full form-input" />
+                        </InputGroup>
+
+                        <InputGroup @name={{t "settings.map.leaflet-dark-tile-url"}} @helpText={{t "settings.map.leaflet-dark-tile-url-help-text"}}>
+                            <Input @type="text" @value={{this.leafletDarkTileUrl}} placeholder="https://tile.openstreetmap.org/{z}/{x}/{y}.png" class="w-full form-input" />
+                        </InputGroup>
+                    {{/if}}
+
                     {{#if this.isGoogleMapsSelected}}
                         <InputGroup @name={{t "settings.map.google-maps-map-type"}} @helpText={{t "settings.map.google-maps-map-type-help-text"}}>
                             <Select
diff --git a/addon/utils/leaflet-tile-url.js b/addon/utils/leaflet-tile-url.js
new file mode 100644
index 000000000..d23d40fb0
--- /dev/null
+++ b/addon/utils/leaflet-tile-url.js
@@ -0,0 +1,31 @@
+/**
+ * Default Leaflet raster tile sources.
+ *
+ * CARTO's `basemaps.cartocdn.com` raster tiles now require an API key and
+ * render an "API key required" watermark without one, so the default basemap
+ * is the keyless OpenStreetMap tile server. Operators can point Leaflet at any
+ * other XYZ provider (including a keyed CARTO URL) via Fleet-Ops map settings.
+ */
+export const DEFAULT_LEAFLET_TILE_URL = 'https://tile.openstreetmap.org/{z}/{x}/{y}.png';
+export const DEFAULT_LEAFLET_DARK_TILE_URL = DEFAULT_LEAFLET_TILE_URL;
+export const DEFAULT_LEAFLET_TILE_ATTRIBUTION = '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors';
+
+/**
+ * Resolve the Leaflet tile URL for a theme from a map settings object.
+ *
+ * @param {Object} settings map settings, may contain `leafletTileUrl` and `leafletDarkTileUrl`
+ * @param {String} theme 'light' or 'dark'
+ * @return {String} the XYZ tile URL template to use
+ */
+export function getLeafletTileUrl(settings = {}, theme = 'light') {
+    const customLight = typeof settings.leafletTileUrl === 'string' ? settings.leafletTileUrl.trim() : '';
+    const customDark = typeof settings.leafletDarkTileUrl === 'string' ? settings.leafletDarkTileUrl.trim() : '';
+
+    if (theme === 'dark') {
+        return customDark || customLight || DEFAULT_LEAFLET_DARK_TILE_URL;
+    }
+
+    return customLight || DEFAULT_LEAFLET_TILE_URL;
+}
+
+export default getLeafletTileUrl;
diff --git a/app/helpers/leaflet-tile-url.js b/app/helpers/leaflet-tile-url.js
new file mode 100644
index 000000000..c868ed909
--- /dev/null
+++ b/app/helpers/leaflet-tile-url.js
@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/helpers/leaflet-tile-url';
diff --git a/app/utils/leaflet-tile-url.js b/app/utils/leaflet-tile-url.js
new file mode 100644
index 000000000..c37313da0
--- /dev/null
+++ b/app/utils/leaflet-tile-url.js
@@ -0,0 +1 @@
+export { default, DEFAULT_LEAFLET_TILE_URL, DEFAULT_LEAFLET_DARK_TILE_URL, DEFAULT_LEAFLET_TILE_ATTRIBUTION, getLeafletTileUrl } from '@fleetbase/fleetops-engine/utils/leaflet-tile-url';
diff --git a/server/src/Http/Controllers/Internal/v1/SettingController.php b/server/src/Http/Controllers/Internal/v1/SettingController.php
index 1b9bb1c00..3a1c568e5 100644
--- a/server/src/Http/Controllers/Internal/v1/SettingController.php
+++ b/server/src/Http/Controllers/Internal/v1/SettingController.php
@@ -328,6 +328,8 @@ public function getMapSettings()
     {
         $defaults = [
             'mapProvider'                 => 'leaflet',
+            'leafletTileUrl'              => '',
+            'leafletDarkTileUrl'          => '',
             'googleMapsMapType'           => 'roadmap',
             'showGoogleMapsTrafficLayer'  => false,
             'showGoogleMapsTransitLayer'  => false,
@@ -418,12 +420,32 @@ protected function normalizeCompanyMapSettings(array $settings): array
         return [
             ...$settings,
             'mapProvider'                => $mapProvider,
+            'leafletTileUrl'             => $this->sanitizeTileUrl(data_get($settings, 'leafletTileUrl', '')),
+            'leafletDarkTileUrl'         => $this->sanitizeTileUrl(data_get($settings, 'leafletDarkTileUrl', '')),
             'googleMapsMapType'          => $googleMapsMapType,
             'showGoogleMapsTrafficLayer' => filter_var(data_get($settings, 'showGoogleMapsTrafficLayer', false), FILTER_VALIDATE_BOOLEAN),
             'showGoogleMapsTransitLayer' => filter_var(data_get($settings, 'showGoogleMapsTransitLayer', false), FILTER_VALIDATE_BOOLEAN),
         ];
     }
 
+    /**
+     * Sanitize a Leaflet XYZ tile URL template — only http(s) URLs are accepted,
+     * anything else is discarded so the frontend falls back to the default tiles.
+     */
+    protected function sanitizeTileUrl($url): string
+    {
+        if (!is_string($url)) {
+            return '';
+        }
+
+        $url = trim($url);
+        if ($url === '' || !preg_match('/^https?:\/\//i', $url)) {
+            return '';
+        }
+
+        return $url;
+    }
+
     /**
      * Retrieve driver scheduling settings for the current company.
      *
diff --git a/translations/en-us.yaml b/translations/en-us.yaml
index f67d0ab61..460f00f78 100644
--- a/translations/en-us.yaml
+++ b/translations/en-us.yaml
@@ -2006,6 +2006,10 @@ settings:
         map-provider: Map Provider
         map-provider-help-text: Choose the map engine used to render the live operations map. Leaflet uses OpenStreetMap tiles and requires no API key. Google Maps requires a valid Google Maps JavaScript API key.
         select-map-provider: Select map provider
+        leaflet-tile-url: Leaflet Tile Provider URL
+        leaflet-tile-url-help-text: Optional custom XYZ tile provider URL template used by the Leaflet map. Leave blank to use the default OpenStreetMap tiles which require no API key. Use this to point Leaflet at your own tile provider, including keyed providers such as CARTO.
+        leaflet-dark-tile-url: Leaflet Dark Mode Tile Provider URL
+        leaflet-dark-tile-url-help-text: Optional tile provider URL used when the console is in dark mode. Leave blank to fall back to the tile provider URL above, or the default OpenStreetMap tiles.
         google-maps-map-type: Map Type
         google-maps-map-type-help-text: The default map style to display when Google Maps is active.
         select-map-type: Select map type

From 4eb74f97133bb3f3439a0dd2a981857570f06ef4 Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Fri, 28 Aug 2026 15:45:03 +0800
Subject: [PATCH 2/2] test(map): cover leaflet tile url sanitization in setting
 controller

CI enforces 100% line coverage on server/src; the new sanitizeTileUrl
branches (non-string input and valid custom URL passthrough) were the
two uncovered statements failing the coverage gate.
---
 .../tests/SettingControllerContractsTest.php  | 33 +++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/server/tests/SettingControllerContractsTest.php b/server/tests/SettingControllerContractsTest.php
index f4aca407b..1163a5f36 100644
--- a/server/tests/SettingControllerContractsTest.php
+++ b/server/tests/SettingControllerContractsTest.php
@@ -408,3 +408,36 @@ function fleetopsJsonPayload(mixed $response): array
             'settings' => ['standard' => ['tracking'], 'byConfig' => [], 'meta' => ['dense' => true]],
         ]);
 });
+
+test('setting controller sanitizes leaflet tile provider urls', function () {
+    $controller = new FleetOpsSettingControllerProbe();
+
+    $saved = fleetopsJsonPayload($controller->saveMapSettings(new Request([
+        'settings' => [
+            'leafletTileUrl'     => '  https://tile.openstreetmap.org/{z}/{x}/{y}.png  ',
+            'leafletDarkTileUrl' => 'javascript:alert(1)',
+        ],
+    ])));
+
+    expect($saved['leafletTileUrl'])->toBe('https://tile.openstreetmap.org/{z}/{x}/{y}.png')
+        ->and($saved['leafletDarkTileUrl'])->toBe('')
+        ->and($controller->configuredCompany['fleet-ops.map-settings'])->toMatchArray([
+            'leafletTileUrl'     => 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
+            'leafletDarkTileUrl' => '',
+        ]);
+
+    $savedNonString = fleetopsJsonPayload($controller->saveMapSettings(new Request([
+        'settings' => [
+            'leafletTileUrl'     => ['not' => 'a-string'],
+            'leafletDarkTileUrl' => 'ftp://tiles.example.com/{z}/{x}/{y}.png',
+        ],
+    ])));
+
+    expect($savedNonString['leafletTileUrl'])->toBe('')
+        ->and($savedNonString['leafletDarkTileUrl'])->toBe('');
+
+    $defaults = fleetopsJsonPayload((new FleetOpsSettingControllerProbe())->getMapSettings());
+
+    expect($defaults['leafletTileUrl'])->toBe('')
+        ->and($defaults['leafletDarkTileUrl'])->toBe('');
+});