@fleetbase/fleetops-engine 0.6.59 → 0.6.60

package/server/tests/ApiCustomerControllerContractsTest.php

@@ -960,3 +960,171 @@ test('api customer controller handles verification delivery fallbacks and profil
             'name' => 'explode',
         ]))))->toBe(['error' => 'update failed']);
 });
+
+/**
+ * Run a callback with an app container that supports environment().
+ *
+ * The harness binds a bare Illuminate\Container\Container, which has no
+ * environment() — so CustomerController::verificationBypassMatches fatals with
+ * "Call to undefined method" without this. Mirrors the swap in
+ * NotificationAndMailContractsTest, but carries every existing binding across so
+ * the controller can still resolve config/request/db.
+ */
+function fleetopsApiCustomerWithEnvironment(string $environment, callable $callback): mixed
+{
+    $previousApp = Illuminate\Container\Container::getInstance();
+    $app         = new class extends Illuminate\Container\Container {
+        public string $fleetopsEnvironment = 'testing';
+
+        public function environment(...$environments)
+        {
+            if (empty($environments)) {
+                return $this->fleetopsEnvironment;
+            }
+
+            $environments = is_array($environments[0]) ? $environments[0] : $environments;
+
+            return in_array($this->fleetopsEnvironment, $environments, true);
+        }
+
+        public function hasDebugModeEnabled()
+        {
+            return false;
+        }
+    };
+    $app->fleetopsEnvironment = $environment;
+
+    $reflection = new ReflectionClass(Illuminate\Container\Container::class);
+    foreach (['bindings', 'instances', 'aliases', 'abstractAliases', 'resolved', 'scopedInstances'] as $property) {
+        if (!$reflection->hasProperty($property)) {
+            continue;
+        }
+        $handle = $reflection->getProperty($property);
+        $handle->setAccessible(true);
+        $handle->setValue($app, $handle->getValue($previousApp));
+    }
+
+    Illuminate\Container\Container::setInstance($app);
+
+    try {
+        return $callback();
+    } finally {
+        Illuminate\Container\Container::setInstance($previousApp);
+    }
+}
+
+test('api customer controller ignores the verification bypass unless it is configured', function () {
+    // Unset and empty-string are both inert. Without this the bypass would be a
+    // standing hole in every default install, which is the entire risk of shipping one.
+    foreach ([null, ''] as $bypassCode) {
+        config(['fleetops.customers.verification_bypass_code' => $bypassCode]);
+
+        fleetopsApiCustomerWithEnvironment('local', function () {
+            $create                     = fleetopsApiCustomerController();
+            $create->verificationExists = false;
+            $verify                     = fleetopsApiCustomerController();
+            $verify->verificationExists = false;
+            $reset                      = fleetopsApiCustomerController();
+            $reset->verificationCode    = null;
+
+            expect(fleetopsApiCustomerJson($create->create(new CreateCustomerRequest([
+                'code'     => '000000',
+                'identity' => 'jane@example.test',
+            ]))))->toBe(['error' => 'Invalid verification code provided.'])
+                ->and(fleetopsApiCustomerJson($verify->verifyCode(Request::create('/v1/customers/verify-code', 'POST', [
+                    'identity' => 'jane@example.test',
+                    'code'     => '000000',
+                ]))))->toBe(['error' => 'Invalid verification code.'])
+                ->and(fleetopsApiCustomerJson($reset->resetPassword(Request::create('/v1/customers/reset-password', 'POST', [
+                    'identity' => 'jane@example.test',
+                    'code'     => '000000',
+                    'password' => 'password-secret',
+                ]))))->toBe(['error' => 'Invalid reset code.']);
+        });
+    }
+
+    config(['fleetops.customers.verification_bypass_code' => null]);
+});
+
+test('api customer controller accepts a configured verification bypass for a listed review account', function () {
+    config([
+        'fleetops.customers.verification_bypass_code' => '000000',
+        'fleetops.customers.review_accounts'          => ['jane@example.test'],
+    ]);
+
+    // Deliberately production. App store reviewers test a release build against
+    // production, so refusing the bypass there made review impossible — that is the
+    // behaviour this replaces. Safety now comes from the allowlist, not the environment.
+    fleetopsApiCustomerWithEnvironment('production', function () {
+        $create                     = fleetopsApiCustomerController();
+        $create->verificationExists = false;
+        $verify                     = fleetopsApiCustomerController();
+        $verify->verificationExists = false;
+        // No VerificationCode row on the bypass path — resetPassword must not fatal
+        // calling ->delete() on null, and must still revoke existing sessions.
+        $reset                   = fleetopsApiCustomerController();
+        $reset->verificationCode = null;
+        // A non-matching code is still rejected while the bypass is live.
+        $wrong                     = fleetopsApiCustomerController();
+        $wrong->verificationExists = false;
+
+        expect($create->create(new CreateCustomerRequest([
+            'code'     => '000000',
+            'identity' => 'jane@example.test',
+            'name'     => 'Jane',
+            'password' => 'password-secret',
+        ])))->toMatchArray(['resource' => 'customer', 'token' => 'plain-token'])
+            ->and($verify->verifyCode(Request::create('/v1/customers/verify-code', 'POST', [
+                'identity' => 'jane@example.test',
+                'code'     => '000000',
+            ])))->toMatchArray(['resource' => 'customer', 'token' => 'plain-token'])
+            ->and(fleetopsApiCustomerJson($reset->resetPassword(Request::create('/v1/customers/reset-password', 'POST', [
+                'identity' => 'jane@example.test',
+                'code'     => '000000',
+                'password' => 'password-secret',
+            ]))))->toBe(['status' => 'ok'])
+            ->and($reset->genericUser->tokensDeleted)->toBeTrue()
+            ->and(fleetopsApiCustomerJson($wrong->create(new CreateCustomerRequest([
+                'code'     => '999999',
+                'identity' => 'jane@example.test',
+            ]))))->toBe(['error' => 'Invalid verification code provided.']);
+    });
+
+    config(['fleetops.customers.verification_bypass_code' => null, 'fleetops.customers.review_accounts' => []]);
+});
+
+test('api customer controller refuses the verification bypass for an identity that is not listed', function () {
+    // The point of the allowlist: holding the code is not sufficient. Previously
+    // anyone who learned it could authenticate as any customer.
+    foreach ([['someone-else@example.test'], []] as $reviewAccounts) {
+        config([
+            'fleetops.customers.verification_bypass_code' => '000000',
+            'fleetops.customers.review_accounts'          => $reviewAccounts,
+        ]);
+
+        fleetopsApiCustomerWithEnvironment('local', function () {
+            $create                     = fleetopsApiCustomerController();
+            $create->verificationExists = false;
+            $verify                     = fleetopsApiCustomerController();
+            $verify->verificationExists = false;
+            $reset                      = fleetopsApiCustomerController();
+            $reset->verificationCode    = null;
+
+            expect(fleetopsApiCustomerJson($create->create(new CreateCustomerRequest([
+                'code'     => '000000',
+                'identity' => 'jane@example.test',
+            ]))))->toBe(['error' => 'Invalid verification code provided.'])
+                ->and(fleetopsApiCustomerJson($verify->verifyCode(Request::create('/v1/customers/verify-code', 'POST', [
+                    'identity' => 'jane@example.test',
+                    'code'     => '000000',
+                ]))))->toBe(['error' => 'Invalid verification code.'])
+                ->and(fleetopsApiCustomerJson($reset->resetPassword(Request::create('/v1/customers/reset-password', 'POST', [
+                    'identity' => 'jane@example.test',
+                    'code'     => '000000',
+                    'password' => 'password-secret',
+                ]))))->toBe(['error' => 'Invalid reset code.']);
+        });
+    }
+
+    config(['fleetops.customers.verification_bypass_code' => null, 'fleetops.customers.review_accounts' => []]);
+});

package/server/tests/ApiDriverControllerContractsTest.php

@@ -550,6 +550,38 @@ test('api driver controller registers a device for the authenticated driver with
     ]);
 });
 
+test('api driver controller falls back to the container request when the router injects null', function () {
+    // Laravel's ResolvesRouteDependencies::transformDependency() returns null — it does
+    // NOT resolve from the container — for any class-typed parameter that declares a
+    // default value. registerDevice() has to declare one, because the internal controller
+    // delegates with an id only, so every routed call arrived with $request === null.
+    // Every other test here passes a request explicitly, which is why they stayed green
+    // while POST /v1/drivers/{id}/register-device answered 500.
+    $driver = new FleetOpsApiDriverFake();
+    $driver->setRawAttributes([
+        'uuid'      => 'driver-uuid',
+        'public_id' => 'driver_public',
+        'user_uuid' => 'user-uuid',
+    ], true);
+
+    $controller         = new FleetOpsApiDriverControllerProbe();
+    $controller->driver = $driver;
+
+    $bound = new FleetOpsApiDriverRegisterDeviceRequest(['token' => 'push-token', 'platform' => 'android']);
+    app()->instance('request', $bound);
+
+    expect($controller->registerDevice('driver_public', null))->toBe([
+        'json'   => ['device' => 'device_public'],
+        'status' => 200,
+    ])
+        ->and($controller->deviceCreates)->toBe([
+            [
+                ['token' => 'push-token', 'platform' => 'android'],
+                ['user_uuid' => 'user-uuid', 'platform' => 'android', 'token' => 'push-token', 'status' => 'active'],
+            ],
+        ]);
+});
+
 test('api driver controller reports missing driver branches', function () {
     $controller                 = new FleetOpsApiDriverControllerProbe();
     $controller->driverNotFound = true;

package/server/tests/CompactResourceSerializationTest.php

@@ -2697,6 +2697,10 @@ test('tracking number and waypoint webhook resources serialize tracking contract
         'scheduled_at'       => '2026-07-30 09:00:00',
     ]);
 
+    // The decoded QR content is a debug-only field and must never ride along on a webhook,
+    // which is a separate literal payload rather than a filtered toArray().
+    expect(array_key_exists('qr_code_content', (new TrackingNumberResource($trackingNumber))->toWebhookPayload()))->toBeFalse();
+
     expect((new TrackingNumberResource($trackingNumber))->toWebhookPayload())->toMatchArray([
         'id'              => 'fixture_public',
         'tracking_number' => 'TN-ZERO',
@@ -2743,3 +2747,92 @@ test('tracking number and waypoint webhook resources serialize tracking contract
             'meta'            => ['sequence' => 2],
         ]);
 });
+
+test('tracking number resource publishes the qr code content only in debug mode', function () {
+    // qr_code is a base64 PNG generated from owner_uuid, and the endpoints that consume a
+    // scanned code match on that uuid. Debug builds publish the value beside the image so
+    // an automated client can follow the flow without decoding a PNG; production must not.
+    $trackingNumber = fleetopsCompactResourceFixture([
+        'tracking_number' => 'TN-DEBUG',
+        'owner_uuid'      => 'owner-uuid-under-the-qr',
+        'owner_type'      => 'Fleetbase\\FleetOps\\Models\\Order',
+        'region'          => 'sg',
+        'qr_code'         => 'qr-data',
+        'barcode'         => 'barcode-data',
+        'last_status'     => 'created',
+        'last_status_code' => 'CREATED',
+    ]);
+    $request = Request::create('/v1/tracking-numbers', 'GET');
+
+    // The full resource builds a console url, which needs app()->environment(). The bare
+    // container this suite runs on has no such method, which is why the tests above only
+    // cover the index resource and the webhook payload.
+    $previousContainer = Illuminate\Container\Container::getInstance();
+    $container         = new class extends Illuminate\Container\Container {
+        public bool $debugMode = false;
+
+        public function environment(...$environments)
+        {
+            return in_array('testing', $environments, true) || $environments === [] ? 'testing' : false;
+        }
+
+        // Stands in for the framework's Application::hasDebugModeEnabled().
+        public function hasDebugModeEnabled()
+        {
+            return $this->debugMode;
+        }
+    };
+    $container->instance('config', new Illuminate\Config\Repository([
+        'fleetbase' => ['console' => ['host' => 'console.fleetbase.test', 'subdomain' => null, 'secure' => true]],
+    ]));
+    Illuminate\Container\Container::setInstance($container);
+
+    // Drive the REAL accessor through the container rather than overriding it, so the
+    // debug check itself is exercised and not just the resource's use of it.
+    $container->debugMode = true;
+    $withDebug            = new TrackingNumberResource($trackingNumber);
+
+    try {
+        $debugPayload = $withDebug->resolve($request);
+
+        $container->debugMode = false;
+        $productionPayload    = (new TrackingNumberResource($trackingNumber))->resolve($request);
+    } finally {
+        Illuminate\Container\Container::setInstance($previousContainer);
+    }
+
+    // Present and exactly the value the QR was generated from — not a public id.
+    expect($debugPayload['qr_code_content'])->toBe('owner-uuid-under-the-qr')
+        ->and($debugPayload['qr_code'])->toBe('qr-data')
+        // Absent, not null: `when()` drops the key entirely, so a production response is
+        // byte-identical to one from before the field existed.
+        ->and(array_key_exists('qr_code_content', $productionPayload))->toBeFalse()
+        ->and($productionPayload['qr_code'])->toBe('qr-data');
+});
+
+test('tracking number resource fails closed when the debug state cannot be determined', function () {
+    // Any failure to resolve the debug state must answer false rather than defaulting to
+    // exposure. The real accessor is exercised here with no usable application bound.
+    $expose = new ReflectionMethod(TrackingNumberResource::class, 'exposesQrCodeContent');
+    $expose->setAccessible(true);
+
+    $previous = Illuminate\Container\Container::getInstance();
+
+    try {
+        // A container that is not an Application has no hasDebugModeEnabled().
+        Illuminate\Container\Container::setInstance(new Illuminate\Container\Container());
+        expect($expose->invoke(null))->toBeFalse();
+
+        // And an accessor that throws must also answer false rather than propagating —
+        // a resource must not be able to fail serialization over a debug check.
+        Illuminate\Container\Container::setInstance(new class extends Illuminate\Container\Container {
+            public function hasDebugModeEnabled()
+            {
+                throw new RuntimeException('debug state unavailable');
+            }
+        });
+        expect($expose->invoke(null))->toBeFalse();
+    } finally {
+        Illuminate\Container\Container::setInstance($previous);
+    }
+});

package/server/tests/CustomerEndpointTest.php

@@ -231,8 +231,11 @@ test('FormRequest validators are present and authorize via api credential', func
     $create = file_get_contents(dirname(__DIR__) . '/src/Http/Requests/CreateCustomerRequest.php');
     $verify = file_get_contents(dirname(__DIR__) . '/src/Http/Requests/VerifyCreateCustomerRequest.php');
 
+    // These match against source text, so they have to be updated whenever the rule
+    // strings change. `code` is presence-only by design — the controller's own check
+    // (code + for + meta->identity) is strictly stronger than exists:verification_codes.
     expect($create)
-        ->toContain("'code'     => 'required|exists:verification_codes,code'")
+        ->toContain("'code'     => 'required|string'")
         ->toContain("'password' => 'required|string|min:8'")
         ->and($verify)->toContain("'mode'     => 'required|in:email,sms'");
 });

package/server/tests/Feature/Http/Api/DriverControllerAuthFlowsTest.php

@@ -84,8 +84,59 @@ class FleetOpsDriverAuthMailerFake
     }
 }
 
+/**
+ * Swap in a container that answers environment().
+ *
+ * verificationBypassMatches() asks app()->environment('production'), which the bare
+ * Illuminate\Container\Container used by this harness does not implement. Mirrors
+ * fleetopsCustomerHelperContainer() in CustomerControllerHelperSeamsTest.
+ */
+function fleetopsDriverAuthContainer(): void
+{
+    $current = Illuminate\Container\Container::getInstance();
+    if (method_exists($current, 'hasDebugModeEnabled')) {
+        return;
+    }
+
+    $replacement = new class extends Illuminate\Container\Container {
+        public function environment(...$environments)
+        {
+            if (empty($environments)) {
+                return 'testing';
+            }
+
+            $checks = is_array($environments[0]) ? $environments[0] : $environments;
+
+            return in_array('testing', $checks, true);
+        }
+
+        public function hasDebugModeEnabled()
+        {
+            return true;
+        }
+    };
+
+    foreach (['bindings', 'instances', 'aliases', 'abstractAliases', 'resolved', 'extenders', 'tags', 'contextual', 'scopedInstances', 'reboundCallbacks', 'globalBeforeResolvingCallbacks', 'globalResolvingCallbacks', 'globalAfterResolvingCallbacks', 'beforeResolvingCallbacks', 'resolvingCallbacks', 'afterResolvingCallbacks'] as $property) {
+        if (!property_exists(Illuminate\Container\Container::class, $property)) {
+            continue;
+        }
+        $reflection = new ReflectionProperty(Illuminate\Container\Container::class, $property);
+        $reflection->setAccessible(true);
+        if ($reflection->isInitialized($current)) {
+            $reflection->setValue($replacement, $reflection->getValue($current));
+        }
+    }
+
+    Illuminate\Container\Container::setInstance($replacement);
+    Illuminate\Support\Facades\Facade::setFacadeApplication($replacement);
+}
+
 function fleetopsDriverAuthBoot(): SQLiteConnection
 {
+    // Must run before the app()->instance() calls below, so those bindings land on
+    // the replacement container rather than the one it supersedes.
+    fleetopsDriverAuthContainer();
+
     $connection = new SQLiteConnection(new PDO('sqlite::memory:'));
     $resolver   = new ConnectionResolver(['default' => $connection, 'mysql' => $connection]);
     $resolver->setDefaultConnection('mysql');
@@ -231,6 +282,7 @@ test('code verification handles unknown users invalid codes bypass and success',
 
     // Bypass code from config authenticates without a stored code
     config()->set('fleetops.navigator.bypass_verification_code', '777777');
+    config()->set('fleetops.navigator.review_accounts', ['driver@example.test']);
     $bypassed = $controller->verifyCode(Request::create('/x', 'POST', ['identity' => 'driver@example.test', 'code' => '777777']));
     expect($bypassed)->toBeInstanceOf(DriverResource::class);
 
@@ -346,6 +398,7 @@ test('code verification reports token issuance failures', function () {
     // A bypass code authenticates without a stored verification code, so the
     // flow reaches token issuance; without the token table that send fails
     config()->set('fleetops.navigator.bypass_verification_code', '777777');
+    config()->set('fleetops.navigator.review_accounts', ['driver@example.test']);
     $connection->getSchemaBuilder()->drop('personal_access_tokens');
 
     $response = $controller->verifyCode(Request::create('/x', 'POST', [
@@ -400,6 +453,7 @@ test('token persistence failures are reported to sentry', function () {
     }
 
     config()->set('fleetops.navigator.bypass_verification_code', '777777');
+    config()->set('fleetops.navigator.review_accounts', ['driver@example.test']);
     $response = $controller->verifyCode(Request::create('/x', 'POST', [
         'identity' => 'driver@example.test',
         'code'     => '777777',
@@ -416,14 +470,16 @@ test('current driver resolves the authenticated users driver profile', function
     $connection->table('users')->insert(['uuid' => 'user-current-1', 'public_id' => 'user_current1', 'company_uuid' => 'company-1', 'name' => 'Current Driver', 'email' => 'current@example.test', 'type' => 'driver']);
     $connection->table('drivers')->insert(['uuid' => 'driver-current-1', 'public_id' => 'driver_current1', 'company_uuid' => 'company-1', 'user_uuid' => 'user-current-1']);
 
-    // registerDevice without an id resolves the driver from the request user
+    // registerDevice without an id resolves the driver from the authenticated user
     // rather than a route parameter, so exercise the real seam here — the
     // contract probe overrides it and never runs this body
     $currentDriver = new ReflectionMethod(DriverController::class, 'currentDriver');
     $currentDriver->setAccessible(true);
 
     $request = Request::create('/v1/drivers/register-device', 'POST');
-    $request->setUserResolver(fn () => $connection->table('users')->where('uuid', 'user-current-1')->first());
+    // Auth::getUserFromSession only accepts a User model from the resolver — anything
+    // else falls through to the session, so this must be a real model, not a row object.
+    $request->setUserResolver(fn () => User::query()->where('uuid', 'user-current-1')->first());
 
     $resolved = $currentDriver->invoke(new DriverController(), $request);
 
@@ -431,8 +487,31 @@ test('current driver resolves the authenticated users driver profile', function
         ->and($resolved->uuid)->toBe('driver-current-1');
 });
 
+test('current driver resolves from the session when the request has no user resolver', function () {
+    $connection = fleetopsDriverAuthBoot();
+    $connection->table('users')->insert(['uuid' => 'user-session-1', 'public_id' => 'user_session1', 'company_uuid' => 'company-1', 'name' => 'Session Driver', 'email' => 'session@example.test', 'type' => 'driver']);
+    $connection->table('drivers')->insert(['uuid' => 'driver-session-1', 'public_id' => 'driver_session1', 'company_uuid' => 'company-1', 'user_uuid' => 'user-session-1']);
+
+    // This is the production path for the public API. `fleetbase.api` authenticates with
+    // Auth::setSession($apiCredential), which writes session('user') but does NOT bind a
+    // user resolver — so reading $request->user() directly resolved nothing and
+    // POST /v1/drivers/register-device answered 404 for every consumer.
+    session(['user' => 'user-session-1']);
+
+    $currentDriver = new ReflectionMethod(DriverController::class, 'currentDriver');
+    $currentDriver->setAccessible(true);
+
+    $resolved = $currentDriver->invoke(new DriverController(), Request::create('/v1/drivers/register-device', 'POST'));
+
+    expect($resolved)->toBeInstanceOf(Driver::class)
+        ->and($resolved->uuid)->toBe('driver-session-1');
+});
+
 test('current driver fails when the request has no matching driver', function () {
     fleetopsDriverAuthBoot();
+    // Explicit, because the session survives between tests and a leftover `user` key
+    // would silently resolve a driver and make this assertion vacuous.
+    session(['user' => null]);
 
     $currentDriver = new ReflectionMethod(DriverController::class, 'currentDriver');
     $currentDriver->setAccessible(true);

package/server/tests/Feature/Http/Api/GeofenceControllerContractsTest.php

@@ -1,6 +1,7 @@
 <?php
 
 use Fleetbase\FleetOps\Http\Controllers\Api\v1\GeofenceController;
+use Fleetbase\FleetOps\Models\Driver;
 use Fleetbase\FleetOps\Models\GeofenceEventLog;
 use Illuminate\Http\Request;
 use Illuminate\Support\Carbon;
@@ -183,6 +184,16 @@ class FleetOpsGeofenceControllerFake extends GeofenceController
     public ?FleetOpsGeofenceQueryFake $nextEventQuery = null;
     public array $serializedEvents                    = [];
 
+    public ?Fleetbase\FleetOps\Models\Driver $historyDriver = null;
+    public array $historyDriverLookups                      = [];
+
+    protected function findDriverForHistory(string $driverId): ?Fleetbase\FleetOps\Models\Driver
+    {
+        $this->historyDriverLookups[] = $driverId;
+
+        return $this->historyDriver;
+    }
+
     protected function geofenceEventLogQuery(?string $companyUuid): mixed
     {
         $query                = $this->nextEventQuery ?? new FleetOpsGeofenceQueryFake($companyUuid);
@@ -351,10 +362,17 @@ test('api geofence driver history applies driver filter and caps pagination', fu
         'per_page' => 75,
     ]);
 
-    $controller->driverHistory($request, 'driver-9');
+    // The endpoint is addressed by public_id and resolves the driver itself; the query
+    // still filters on the driver's uuid.
+    $historyDriver = new Fleetbase\FleetOps\Models\Driver();
+    $historyDriver->setRawAttributes(['uuid' => 'driver-9', 'public_id' => 'driver_public9'], true);
+    $controller->historyDriver = $historyDriver;
+
+    $controller->driverHistory($request, 'driver_public9');
     $query = $controller->eventQueries[0];
 
-    expect($query->companyUuid)->toBe('company-4')
+    expect($controller->historyDriverLookups)->toBe(['driver_public9'])
+        ->and($query->companyUuid)->toBe('company-4')
         ->and($query->calls)->toContain(
             ['where', 'driver_uuid', 'driver-9'],
             ['with', ['driver.vehicle', 'vehicle', 'order']],
@@ -362,3 +380,82 @@ test('api geofence driver history applies driver filter and caps pagination', fu
             ['paginate', 75],
         );
 });
+
+test('driver history answers 404 when the driver does not resolve', function () {
+    // The endpoint's own not-found branch: findDriverForHistory returns null and the
+    // request must not proceed to a query keyed on nothing.
+    $controller = new FleetOpsGeofenceControllerFake();
+    $controller->historyDriver = null;
+
+    $response = $controller->driverHistory(Request::create('/geofences/driver/driver_missing/history', 'GET'), 'driver_missing');
+
+    expect($response->getStatusCode())->toBe(404)
+        ->and($response->getData(true))->toBe(['error' => 'Driver resource not found.'])
+        ->and($controller->historyDriverLookups)->toBe(['driver_missing'])
+        // and no event query was ever built
+        ->and($controller->eventQueries)->toBe([]);
+});
+
+test('driver history resolves by public id, and by uuid only for internal requests', function () {
+    // The contract tests above stub findDriverForHistory(), so the real lookup needs its
+    // own coverage. It is the whole point of the change: the public endpoint used to take
+    // a uuid, which the public API never issues.
+    $connection = new Illuminate\Database\SQLiteConnection(new PDO('sqlite::memory:'));
+    $resolver   = new Illuminate\Database\ConnectionResolver(['default' => $connection, 'mysql' => $connection]);
+    $resolver->setDefaultConnection('mysql');
+    Illuminate\Database\Eloquent\Model::setConnectionResolver($resolver);
+
+    $schema = $connection->getSchemaBuilder();
+    // Driver carries a global scope requiring a related user, so both tables are needed.
+    $schema->create('users', function ($table) {
+        $table->increments('id');
+        $table->string('uuid')->nullable();
+        $table->timestamp('deleted_at')->nullable();
+        $table->timestamps();
+    });
+    $schema->create('drivers', function ($table) {
+        $table->increments('id');
+        $table->string('uuid')->nullable();
+        $table->string('public_id')->nullable();
+        $table->string('company_uuid')->nullable();
+        $table->string('user_uuid')->nullable();
+        $table->timestamp('deleted_at')->nullable();
+        $table->timestamps();
+    });
+    $connection->table('users')->insert(['uuid' => 'user-uuid-1']);
+    $connection->table('drivers')->insert([
+        'uuid'      => 'driver-uuid-1',
+        'public_id' => 'driver_public1',
+        'user_uuid' => 'user-uuid-1',
+    ]);
+
+    $resolve = new ReflectionMethod(GeofenceController::class, 'findDriverForHistory');
+    $resolve->setAccessible(true);
+    $controller = new GeofenceController();
+
+    $byPublicId = $resolve->invoke($controller, 'driver_public1');
+    // A uuid is NOT accepted on a public request — that is the contract this restores.
+    $byUuidPublic = $resolve->invoke($controller, 'driver-uuid-1');
+    $missing      = $resolve->invoke($controller, 'driver_nope');
+
+    expect($byPublicId)->toBeInstanceOf(Driver::class)
+        ->and($byPublicId->uuid)->toBe('driver-uuid-1')
+        ->and($byUuidPublic)->toBeNull()
+        ->and($missing)->toBeNull();
+
+    // The console reaches the same method through the internal route with a uuid.
+    // Http::isInternalRequest() decides from the ROUTE's uri — any route with an "int"
+    // segment — so the request has to carry one, not a header.
+    $internalRequest = Request::create('/fleet-ops/int/v1/geofences/driver/driver-uuid-1/history', 'GET');
+    $internalRequest->setRouteResolver(fn () => new Illuminate\Routing\Route(
+        ['GET'],
+        'fleet-ops/int/v1/geofences/driver/{driverUuid}/history',
+        ['uses' => fn () => null]
+    ));
+    app()->instance('request', $internalRequest);
+
+    $byUuidInternal = $resolve->invoke($controller, 'driver-uuid-1');
+
+    expect($byUuidInternal)->toBeInstanceOf(Driver::class)
+        ->and($byUuidInternal->public_id)->toBe('driver_public1');
+});

package/server/tests/Feature/Http/Api/TrackingNumberControllerHelpersTest.php

@@ -138,8 +138,14 @@ test('tracking number helpers look up owners create records and wrap resources',
     expect($qrModel)->not->toBeNull()
         ->and($helper('qrModelResource', $qrModel))->toBeInstanceOf(Fleetbase\FleetOps\Http\Resources\v1\Entity::class);
 
-    // Tables with no eloquent mapping are skipped and fall back to a raw row
-    // lookup, so the record still resolves but arrives unhydrated
+    // A table with no eloquent mapping resolves to null rather than a raw row.
+    //
+    // The raw-row fallback was removed: it passed the ARRAY of table names to
+    // DB::table(), which stringified it to the literal table "Array" and threw
+    // SQLSTATE[42S02], so every unresolvable QR code answered 500 instead of the 400 the
+    // caller already handles. It could not have helped either way — qrModelResource()
+    // serializes through a typed resource keyed on the model class, and a raw stdClass
+    // row has none.
     $connection->table('tracking_statuses')->insert([
         'uuid'      => '44444444-4444-4444-8444-444444444403',
         'public_id' => 'tracking_status_tnhelper1',
@@ -147,8 +153,8 @@ test('tracking number helpers look up owners create records and wrap resources',
         'status'    => 'Dispatched',
     ]);
 
-    $unmapped = $helper('findQrModel', ['tracking_statuses'], ['public_id' => 'tracking_status_tnhelper1']);
-    expect($unmapped)->not->toBeNull()
-        ->and($unmapped)->not->toBeInstanceOf(EloquentModel::class)
-        ->and($unmapped->uuid)->toBe('44444444-4444-4444-8444-444444444403');
+    expect($helper('findQrModel', ['tracking_statuses'], ['public_id' => 'tracking_status_tnhelper1']))->toBeNull()
+        // And a mapped table that simply matches nothing is also null, which is the path
+        // an unknown or unresolved code takes.
+        ->and($helper('findQrModel', ['entities', 'orders'], ['uuid' => '{{qr_code}}']))->toBeNull();
 });