@fleetbase/fleetops-engine 0.6.59 → 0.6.60

package/RELEASE.md

@@ -0,0 +1,36 @@
+> v0.6.60 ~ "Closes an authentication bypass, and clears a run of API 500s"
+
+---
+## Highlights
+A security fix and a broad sweep of public API defects surfaced by running the official Postman collection against a live stack. Several endpoints answered `500` where a `404` or `422` belonged, and a few were unreachable entirely.
+
+---
+## Security
+- **Closed a verify-code authentication bypass in the driver flow.** Please upgrade.
+- The non-production verification-code bypass is now scoped to explicitly designated review accounts, so a bypass code alone is not enough — the identity has to be on the allowlist too.
+
+---
+## Bug Fixes
+- **Driver `register-device` was unreachable on both driver routes.** Laravel never injects a class-typed parameter that declares a default, so the injected request was always null.
+- **Geofence driver history asked for a UUID the API never issues.** It now resolves the driver by the public id callers actually hold.
+- **`/from-qr` returned a 500**, and the QR code's content is now published in debug mode so the flow can be exercised.
+- **Fuel reports could not be created without a location**, and could not be updated.
+- **A sensor could not be created at all** — `last_position` had no default.
+- **Customer signup with a place failed** — the Place location now defaults.
+- Unknown onboard organization answers `404` instead of `500`.
+- Duplicate part SKU and fuel transaction answer `422` instead of `500`.
+- Restored the vehicle maintenance schedule workflows.
+
+---
+## Testing
+- Coverage restored to 100% across the QR, geofence, driver auth, customer request and navigator changes.
+
+---
+## Continuous Integration
+- The server, Ember and Postman workflows now run on `dev-v*` release branches.
+- The contract run tests this branch's API code rather than the published package.
+
+---
+## Need help?
+- [GitHub Discussions](https://github.com/fleetbase/fleetbase/discussions)
+- [Discord](https://discord.gg/HnTqQ6zAVn)

package/addon/components/vehicle/details/schedules.hbs

@@ -33,8 +33,8 @@
             <div class="flex flex-col items-center justify-center py-10 text-gray-400 dark:text-gray-600">
                 <FaIcon @icon="calendar-alt" @size="2x" class="mb-3" />
                 <p class="text-sm">No maintenance schedules for this vehicle.</p>
-                <Button @text="Add Schedule" @icon="plus" @size="xs" @type="primary" class="mt-3" @onClick={{fn this.maintenanceScheduleActions.modal.create (hash subject=@vehicle)}} />
+                <Button @text="Add Schedule" @icon="plus" @size="xs" @type="primary" class="mt-3" @onClick={{this.createSchedule}} />
             </div>
         {{/if}}
     {{/if}}
-</div>
+</div>

package/addon/components/vehicle/details/schedules.js

@@ -1,12 +1,14 @@
 import Component from '@glimmer/component';
 import { tracked } from '@glimmer/tracking';
 import { inject as service } from '@ember/service';
+import { action } from '@ember/object';
 import { task } from 'ember-concurrency';
 
 export default class VehicleDetailsSchedulesComponent extends Component {
     @service maintenanceScheduleActions;
     @service notifications;
     @service store;
+    @service vehicleActions;
     @tracked schedules = [];
 
     get resourceId() {
@@ -22,11 +24,15 @@ export default class VehicleDetailsSchedulesComponent extends Component {
         try {
             this.schedules = yield this.store.query('maintenance-schedule', {
                 subject_uuid: this.resourceId,
-                subject_type: 'vehicle',
+                subject_type: 'fleet-ops:vehicle',
                 sort: '-created_at',
             });
         } catch (err) {
             this.notifications.serverError(err);
         }
     }
+
+    @action createSchedule() {
+        return this.vehicleActions.scheduleMaintenance(this.args.vehicle, {}, { refresh: false, callback: () => this.loadSchedules.perform() });
+    }
 }

package/addon/controllers/maintenance/schedules/index/edit.js

@@ -21,12 +21,21 @@ export default class MaintenanceSchedulesIndexEditController extends Controller
             this.overlay?.close();
             yield this.hostRouter.refresh();
             yield this.hostRouter.transitionTo('console.fleet-ops.maintenance.schedules.index.details', schedule);
-            this.notifications.success(this.intl.t('common.resource-updated-success', { resource: this.intl.t('resource.maintenance-schedule') }));
+            this.notifyUpdateSuccess(schedule);
         } catch (err) {
             this.notifications.serverError(err);
         }
     }
 
+    notifyUpdateSuccess(schedule) {
+        this.notifications.success(
+            this.intl.t('common.resource-updated-success', {
+                resource: this.intl.t('resource.maintenance-schedule'),
+                resourceName: schedule.name,
+            })
+        );
+    }
+
     @action cancel() {
         return this.hostRouter.transitionTo('console.fleet-ops.maintenance.schedules.index');
     }

package/addon/services/vehicle-actions.js

@@ -184,8 +184,10 @@ export default class VehicleActionsService extends ResourceActionService {
         },
     };
 
-    @action scheduleMaintenance(vehicle) {
-        this.maintenanceScheduleActions.modal.create({ subject: vehicle });
+    @action async scheduleMaintenance(vehicle, options = {}, saveOptions = {}) {
+        vehicle = await this.resolveVehicleResource(vehicle);
+
+        return this.maintenanceScheduleActions.modal.create({ subject: vehicle }, options, saveOptions);
     }
 
     @action createWorkOrder(vehicle) {

package/composer.json

@@ -1,6 +1,6 @@
 {
     "name": "fleetbase/fleetops-api",
-    "version": "0.6.59",
+    "version": "0.6.60",
     "description": "Fleet & Transport Management Extension for Fleetbase",
     "keywords": [
         "fleetbase-extension",

package/extension.json

@@ -1,6 +1,6 @@
 {
     "name": "Fleet-Ops",
-    "version": "0.6.59",
+    "version": "0.6.60",
     "description": "Fleet & Transport Management Extension for Fleetbase",
     "repository": "https://github.com/fleetbase/fleetops",
     "license": "AGPL-3.0-or-later",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@fleetbase/fleetops-engine",
-    "version": "0.6.59",
+    "version": "0.6.60",
     "description": "Fleet & Transport Management Extension for Fleetbase",
     "fleetbase": {
         "route": "fleet-ops"

package/server/config/fleetops.php

@@ -96,10 +96,54 @@ return [
     |--------------------------------------------------------------------------
     */
     'navigator' => [
+        /*
+        | App store reviewers cannot receive our SMS, so a fixed verification code has
+        | to keep working for them — including in production, which is where a review
+        | build is tested. Blocking the bypass outside production made review
+        | impossible; restricting it to named accounts makes it safe instead.
+        |
+        | Both values are required, and neither has a default. The code alone is not
+        | sufficient: it is only accepted for an identity listed in review_accounts, so
+        | a leaked code cannot be used to authenticate as an arbitrary driver.
+        |
+        |   NAVIGATOR_BYPASS_VERIFICATION_CODE=<a secret, rotated code>
+        |   NAVIGATOR_REVIEW_ACCOUNTS=+15555550100,apple-review@example.com
+        */
         'bypass_verification_code' => env('SMS_AUTH_BYPASS_CODE', env('NAVIGATOR_BYPASS_VERIFICATION_CODE')),
+        'review_accounts'          => array_values(array_filter(array_map(
+            'trim',
+            explode(',', (string) env('NAVIGATOR_REVIEW_ACCOUNTS', ''))
+        ))),
         'app_identifier'           => env('NAVIGATOR_APP_IDENTIFIER', 'io.fleetbase.navigator'),
     ],
 
+    /*
+    |--------------------------------------------------------------------------
+    | Customers
+    |--------------------------------------------------------------------------
+    |
+    | Testing-only verification-code bypass for the customer auth flows
+    | (POST /v1/customers, /customers/verify-code, /customers/reset-password).
+    | Intended for local development and staging QA, where signing up means
+    | waiting on a real email or paying for a real SMS.
+    |
+    | MUST be left unset in production. It is ignored outright when the app
+    | environment is `production`, and when unset no bypass is possible.
+    |
+    | Deliberately NOT wired to SMS_AUTH_BYPASS_CODE: that variable already
+    | gates operator console login and driver login, and reusing it here would
+    | make one leaked value unlock three different privilege tiers.
+    |
+    */
+    'customers' => [
+        'verification_bypass_code' => env('FLEETOPS_CUSTOMER_VERIFICATION_BYPASS_CODE'),
+        // Identities the bypass code is accepted for. See the note on navigator below.
+        'review_accounts'          => array_values(array_filter(array_map(
+            'trim',
+            explode(',', (string) env('FLEETOPS_CUSTOMER_REVIEW_ACCOUNTS', ''))
+        ))),
+    ],
+
     /*
     |--------------------------------------------------------------------------
     | API Events

package/server/config/geocoder.php

@@ -57,7 +57,7 @@ return [
     'providers' => [
         Chain::class => [
             GoogleMaps::class => [
-                config('services.google_maps.locale', env('GOOGLE_MAPS_LOCALE', 'us')),
+                config('services.google_maps.locale', env('GOOGLE_MAPS_LOCALE', 'en')),
                 config('services.google_maps.api_key', env('GOOGLE_MAPS_API_KEY')),
             ]
         ],

package/server/migrations/2026_08_08_000001_make_sku_and_provider_transaction_unique_indexes_soft_delete_aware.php

@@ -0,0 +1,152 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Both `parts` and `fuel_provider_transactions` soft-delete, but their unique
+ * indexes were not soft-delete aware.  A deleted row kept occupying the key, so
+ * re-creating a Part with a previously used SKU (or re-ingesting a fuel provider
+ * transaction that had been deleted) raised a UniqueConstraintViolationException.
+ * On the public v1 API that surfaced as an HTTP 500, and because there is no
+ * restore/force-delete route the key was unusable from then on.
+ *
+ * The fix follows the pattern already used for alrashed contract numbers in
+ * 2026_05_25_000001_make_contract_number_unique_for_active_contracts: a STORED
+ * generated column that is NULL for soft-deleted rows.  MySQL permits any number
+ * of NULLs in a unique index, so tombstones stop colliding while live rows stay
+ * constrained.
+ *
+ * `fuel_provider_transactions` additionally gains `company_uuid` in the key.  The
+ * old index was global, so one company's provider transaction id blocked — or,
+ * via FuelProviderService::ingestTransaction()'s updateOrCreate, silently
+ * overwrote — another company's.  Provider transaction ids are only unique within
+ * the account they were issued for, so the key belongs per tenant.
+ *
+ * Both new indexes are strictly more permissive than the ones they replace, so no
+ * existing row can violate them and no backfill is required.
+ */
+return new class extends Migration {
+    /**
+     * Run the migrations.
+     *
+     * @return void
+     */
+    public function up()
+    {
+        // ---- parts: (company_uuid, sku) -> (company_uuid, active_sku) ----
+        if (!Schema::hasColumn('parts', 'active_sku')) {
+            Schema::table('parts', function (Blueprint $table) {
+                $table->string('active_sku')->nullable()->storedAs('IF(`deleted_at` IS NULL, `sku`, NULL)');
+            });
+        }
+
+        // The replacement index MUST be created before the old one is dropped:
+        // parts_company_uuid_sku_unique is currently the only index covering
+        // company_uuid, and parts_company_uuid_foreign depends on it. Adding an
+        // index that also leads with company_uuid lets it take over as the
+        // covering index, otherwise the drop below fails with errno 150.
+        if (!$this->indexExists('parts', 'parts_company_uuid_active_sku_unique')) {
+            Schema::table('parts', function (Blueprint $table) {
+                $table->unique(['company_uuid', 'active_sku'], 'parts_company_uuid_active_sku_unique');
+            });
+        }
+
+        if ($this->indexExists('parts', 'parts_company_uuid_sku_unique')) {
+            Schema::table('parts', function (Blueprint $table) {
+                $table->dropUnique('parts_company_uuid_sku_unique');
+            });
+        }
+
+        // ---- fuel_provider_transactions: (provider, provider_transaction_id)
+        //      -> (company_uuid, provider, active_provider_transaction_id) ----
+        if (!Schema::hasColumn('fuel_provider_transactions', 'active_provider_transaction_id')) {
+            Schema::table('fuel_provider_transactions', function (Blueprint $table) {
+                $table->string('active_provider_transaction_id', 191)->nullable()->storedAs('IF(`deleted_at` IS NULL, `provider_transaction_id`, NULL)');
+            });
+        }
+
+        if (!$this->indexExists('fuel_provider_transactions', 'fuel_provider_txn_company_provider_unique')) {
+            Schema::table('fuel_provider_transactions', function (Blueprint $table) {
+                $table->unique(['company_uuid', 'provider', 'active_provider_transaction_id'], 'fuel_provider_txn_company_provider_unique');
+            });
+        }
+
+        if ($this->indexExists('fuel_provider_transactions', 'fuel_provider_txn_provider_unique')) {
+            Schema::table('fuel_provider_transactions', function (Blueprint $table) {
+                $table->dropUnique('fuel_provider_txn_provider_unique');
+            });
+        }
+    }
+
+    /**
+     * Reverse the migrations.
+     *
+     * Restoring the old global index can fail if rows now exist that only the new
+     * key permits (two tenants sharing a provider transaction id, or a live row
+     * whose SKU matches a soft-deleted one). That is inherent to reversing a
+     * relaxed constraint, so the old indexes are restored on a best-effort basis
+     * and the generated columns are dropped either way.
+     *
+     * @return void
+     */
+    public function down()
+    {
+        if (!$this->indexExists('parts', 'parts_company_uuid_sku_unique')) {
+            try {
+                Schema::table('parts', function (Blueprint $table) {
+                    $table->unique(['company_uuid', 'sku'], 'parts_company_uuid_sku_unique');
+                });
+            } catch (Throwable $e) {
+                // Duplicate SKUs the new index allowed now block the old one.
+            }
+        }
+
+        if ($this->indexExists('parts', 'parts_company_uuid_active_sku_unique')) {
+            Schema::table('parts', function (Blueprint $table) {
+                $table->dropUnique('parts_company_uuid_active_sku_unique');
+            });
+        }
+
+        if (Schema::hasColumn('parts', 'active_sku')) {
+            Schema::table('parts', function (Blueprint $table) {
+                $table->dropColumn('active_sku');
+            });
+        }
+
+        if (!$this->indexExists('fuel_provider_transactions', 'fuel_provider_txn_provider_unique')) {
+            try {
+                Schema::table('fuel_provider_transactions', function (Blueprint $table) {
+                    $table->unique(['provider', 'provider_transaction_id'], 'fuel_provider_txn_provider_unique');
+                });
+            } catch (Throwable $e) {
+                // Cross-tenant duplicates the new index allows now block the old one.
+            }
+        }
+
+        if ($this->indexExists('fuel_provider_transactions', 'fuel_provider_txn_company_provider_unique')) {
+            Schema::table('fuel_provider_transactions', function (Blueprint $table) {
+                $table->dropUnique('fuel_provider_txn_company_provider_unique');
+            });
+        }
+
+        if (Schema::hasColumn('fuel_provider_transactions', 'active_provider_transaction_id')) {
+            Schema::table('fuel_provider_transactions', function (Blueprint $table) {
+                $table->dropColumn('active_provider_transaction_id');
+            });
+        }
+    }
+
+    private function indexExists(string $table, string $index): bool
+    {
+        $database = DB::connection()->getDatabaseName();
+
+        return DB::table('information_schema.statistics')
+            ->where('table_schema', $database)
+            ->where('table_name', $table)
+            ->where('index_name', $index)
+            ->exists();
+    }
+};

package/server/src/Http/Controllers/Api/v1/CustomerController.php

@@ -19,6 +19,7 @@ use Fleetbase\FleetOps\Models\ServiceQuote;
 use Fleetbase\FleetOps\Support\CustomerAuth;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\Http\Controllers\Controller;
+use Fleetbase\LaravelMysqlSpatial\Types\Point as SpatialPoint;
 use Fleetbase\Models\File;
 use Fleetbase\Models\User;
 use Fleetbase\Models\UserDevice;
@@ -41,6 +42,8 @@ use Illuminate\Support\Str;
  */
 class CustomerController extends Controller
 {
+    use \Fleetbase\FleetOps\Http\Controllers\Concerns\ResolvesReviewAccountBypass;
+
     /* ============================================================
      | Public auth flows (API credential only, no Customer-Token)
      * ============================================================ */
@@ -144,7 +147,7 @@ class CustomerController extends Controller
             'for'            => 'fleetops_create_customer',
             'meta->identity' => $identity,
         ]);
-        if (!$verificationCode) {
+        if (!$verificationCode && !$this->verificationBypassMatches($identity, $code)) {
             return response()->apiError('Invalid verification code provided.');
         }
 
@@ -312,6 +315,14 @@ class CustomerController extends Controller
                 'company_uuid' => $companyUuid,
                 'owner_uuid'   => $contact->uuid,
                 'owner_type'   => get_class($contact),
+                // `places.location` is a NOT NULL POINT column with no database default,
+                // and $allowed above is address-only — a caller cannot supply coordinates
+                // here. Without this the insert fails with SQLSTATE[HY000] 1364 ("Field
+                // 'location' doesn't have a default value"), turning a documented signup
+                // payload into a 500. Point(0, 0) is the same placeholder the geocoding
+                // helpers fall back to when an address cannot be resolved — see
+                // Place::getGoogleAddressArray and Place::findExistingSharedPlace.
+                'location'     => new SpatialPoint(0, 0),
             ],
             $attributes,
         ));
@@ -417,7 +428,7 @@ class CustomerController extends Controller
             'code'         => $code,
             'for'          => $for,
         ]);
-        if (!$verificationCode) {
+        if (!$verificationCode && !$this->verificationBypassMatches($identity, $code)) {
             return response()->apiError('Invalid verification code.');
         }
 
@@ -503,7 +514,9 @@ class CustomerController extends Controller
             'for'            => 'fleetops_customer_password_reset',
             'meta->identity' => $needle,
         ]);
-        if (!$verificationCode) {
+        // $needle, not $identity: the other verify paths normalise in place, so an
+        // allowlisted phone must be compared in the same normalised form here too.
+        if (!$verificationCode && !$this->verificationBypassMatches($needle, $code)) {
             return response()->apiError('Invalid reset code.');
         }
 
@@ -517,7 +530,10 @@ class CustomerController extends Controller
         $user->save();
         // Invalidate all existing sessions for this user after a password reset.
         $this->deleteUserTokens($user);
-        $verificationCode->delete();
+        // Null on the testing-bypass path — there is no row to consume.
+        if ($verificationCode) {
+            $verificationCode->delete();
+        }
 
         return response()->json(['status' => 'ok']);
     }
@@ -918,6 +934,36 @@ class CustomerController extends Controller
         return VerificationCode::generateSmsVerificationFor($user, $for, $options);
     }
 
+    /**
+     * Whether the supplied code matches the configured testing bypass code.
+     *
+     * Three conditions, all required, mirroring the console equivalent in
+     * Fleetbase\Http\Controllers\Internal\v1\AuthController::authenticateWithVerificationCode:
+     * a bypass code must actually be configured, the app must not be running in
+     * production, and the comparison is constant-time.
+     *
+     * Fails safe by default: config/app.php resolves `env` to `production` when
+     * neither APP_ENV nor ENVIRONMENT is set, so an unconfigured install cannot
+     * be bypassed even accidentally.
+     *
+     * `!== null && !== ''` rather than `!empty()` — `!empty('0')` is false, so a
+     * configured bypass code of "0" would otherwise be silently ignored.
+     *
+     * Kept out of verificationCodeExists()/findVerificationCode() on purpose:
+     * those two are test seams that the controller contract tests override, so a
+     * policy living inside them would be stubbed away exactly where it matters.
+     */
+    protected function verificationBypassMatches(?string $identity, ?string $code): bool
+    {
+        return static::reviewAccountBypassMatches(
+            'fleetops.customers.verification_bypass_code',
+            'fleetops.customers.review_accounts',
+            $identity,
+            $code,
+            'fleetops-customer'
+        );
+    }
+
     protected function verificationCodeExists(array $attributes): bool
     {
         return VerificationCode::where($attributes)->exists();

package/server/src/Http/Controllers/Api/v1/DriverController.php

@@ -39,6 +39,8 @@ use Illuminate\Support\Str;
 
 class DriverController extends Controller
 {
+    use \Fleetbase\FleetOps\Http\Controllers\Concerns\ResolvesReviewAccountBypass;
+
     /**
      * Creates a new Fleetbase Driver resource.
      *
@@ -438,6 +440,15 @@ class DriverController extends Controller
      */
     public function registerDevice(?string $id = null, ?Request $request = null)
     {
+        // Laravel does NOT inject a class-typed parameter that declares a default value —
+        // RouteDependencyResolverTrait skips it and the default (null) is used. So the
+        // router always called this with $request === null, which made
+        // POST /v1/drivers/{id}/register-device fail with "Call to a member function
+        // input() on null" and POST /v1/drivers/register-device answer 404 (the driver was
+        // looked up by a null user_uuid). The default has to stay, because the internal
+        // controller delegates to this method with an id only.
+        $request = $request ?? request();
+
         try {
             // With an id (…/{id}/register-device) look the driver up directly; without
             // one (…/register-device and the internal delegation) resolve the driver
@@ -611,7 +622,7 @@ class DriverController extends Controller
 
         // find and verify code
         $verificationCode = VerificationCode::where(['subject_uuid' => $user->uuid, 'code' => $code, 'for' => $for])->exists();
-        if (!$verificationCode && $code !== config('fleetops.navigator.bypass_verification_code')) {
+        if (!$verificationCode && !static::verificationBypassMatches($identity, $code)) {
             return response()->apiError('Invalid verification code!');
         }
 
@@ -960,7 +971,21 @@ class DriverController extends Controller
      */
     protected function currentDriver(?Request $request): Driver
     {
-        return Driver::where('user_uuid', optional(optional($request)->user())->uuid)->firstOrFail();
+        // $request->user() is never populated on the public API: the `fleetbase.api`
+        // middleware calls Auth::setSession($apiCredential), which writes the session keys
+        // but leaves $login false, so no user resolver is ever bound. Reading it alone
+        // meant POST /v1/drivers/register-device looked a driver up by a null user_uuid
+        // and answered 404 for every consumer of the route.
+        //
+        // Auth::getUserFromSession() encodes this same order, but it also calls auth() and
+        // session()->has(), neither of which exists in the SQLite test harness — so the
+        // two sources are read directly here.
+        $user = optional($request)->user();
+        if (!$user instanceof User) {
+            $user = User::where('uuid', session('user'))->first();
+        }
+
+        return Driver::where('user_uuid', optional($user)->uuid)->firstOrFail();
     }
 
     protected function queryDrivers(Request $request)
@@ -1035,6 +1060,36 @@ class DriverController extends Controller
         return $company;
     }
 
+    /**
+     * Whether the supplied code matches the configured testing bypass code.
+     *
+     * Three conditions, all required, mirroring the console equivalent in
+     * Fleetbase\Http\Controllers\Internal\v1\AuthController::authenticateWithVerificationCode:
+     *
+     *  - a bypass code must actually be configured. The previous
+     *    `$code !== config(...)` comparison meant that on a default install --
+     *    where the config resolves to null -- omitting `code` entirely made the
+     *    check `null !== null`, i.e. false, so the guard never fired and any
+     *    caller with a valid org API credential could mint a driver token for
+     *    any driver in the install without a code at all;
+     *  - the app must not be in production, so a code left set in a deployed
+     *    .env cannot be used against a live fleet;
+     *  - the comparison is constant-time.
+     *
+     * Shared with Internal\v1\DriverController so both verify-code paths cannot
+     * drift apart.
+     */
+    public static function verificationBypassMatches(?string $identity, ?string $code): bool
+    {
+        return static::reviewAccountBypassMatches(
+            'fleetops.navigator.bypass_verification_code',
+            'fleetops.navigator.review_accounts',
+            $identity,
+            $code,
+            'navigator'
+        );
+    }
+
     /**
      * Patches phone number with international code.
      */

package/server/src/Http/Controllers/Api/v1/GeofenceController.php

@@ -4,6 +4,7 @@ namespace Fleetbase\FleetOps\Http\Controllers\Api\v1;
 
 use Fleetbase\FleetOps\Models\GeofenceEventLog;
 use Fleetbase\FleetOps\Support\Utils;
+use Fleetbase\FleetOps\Models\Driver;
 use Fleetbase\Http\Controllers\Controller;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
@@ -201,13 +202,22 @@ class GeofenceController extends Controller
      *
      * Returns the geofence event history for a specific driver.
      */
-    public function driverHistory(Request $request, string $driverUuid): JsonResponse
+    public function driverHistory(Request $request, string $driverId): JsonResponse
     {
         $companyUuid = session('company');
         $perPage     = min((int) $request->input('per_page', 50), 200);
 
+        // Addressed by public_id, like every other public endpoint. The route parameter
+        // was named driverUuid and matched against driver_uuid directly, so this was the
+        // one place in the public API asking a caller for an internal identifier — which
+        // the API does not hand out in the first place, making it unusable.
+        $driver = $this->findDriverForHistory($driverId);
+        if (!$driver) {
+            return response()->json(['error' => 'Driver resource not found.'], 404);
+        }
+
         $events = $this->geofenceEventLogQuery($companyUuid)
-            ->where('driver_uuid', $driverUuid)
+            ->where('driver_uuid', $driver->uuid)
             ->with(['driver.vehicle', 'vehicle', 'order'])
             ->orderBy('occurred_at', 'desc')
             ->paginate($perPage);
@@ -217,6 +227,28 @@ class GeofenceController extends Controller
         return response()->json($events);
     }
 
+    /**
+     * Resolve the driver a history request addresses.
+     *
+     * Public callers use the public_id, like every other v1 endpoint. The console reaches
+     * the same method through the internal route with a uuid, so that is accepted there
+     * and ONLY there — the public contract stays public_id-only rather than quietly
+     * taking either.
+     *
+     * A seam, like geofenceEventLogQuery above, so the contract tests can drive this
+     * without a database.
+     */
+    protected function findDriverForHistory(string $driverId): ?Driver
+    {
+        $driver = Driver::where('public_id', $driverId)->first();
+
+        if (!$driver && \Fleetbase\Support\Http::isInternalRequest()) {
+            $driver = Driver::where('uuid', $driverId)->first();
+        }
+
+        return $driver;
+    }
+
     protected function serializeEvent(GeofenceEventLog $event): array
     {
         $driver      = $event->driver;