@fleetbase/fleetops-engine 0.6.60 → 0.6.62

package/server/src/Http/Controllers/Api/v1/Concerns/ResolvesPublicExpansions.php

@@ -0,0 +1,187 @@
+<?php
+
+namespace Fleetbase\FleetOps\Http\Controllers\Api\v1\Concerns;
+
+use Illuminate\Http\Request;
+
+/**
+ * Normalises the public `with` / `expand` parameters into an allowlisted set of
+ * real Eloquent relation names, and writes the result back onto the request.
+ *
+ * Core's `HasApiModelBehavior` reads `with`/`expand` itself and hands the value
+ * straight to `$result->load(...)`, with no allowlist and no mapping. Two things
+ * follow from that. A caller can name any string and reach `load()`, and an
+ * unknown one raises `RelationNotFoundException` — a 500 for a typo. And the
+ * public name is not always the relation name: `?with=subfleets` normalises to
+ * `subfleets`, while the relation is `subFleets`, so the documented expansion
+ * has never worked.
+ *
+ * Rewriting the request once, up front, fixes both at the only point where the
+ * query builder and the resource are guaranteed to agree on the list.
+ */
+trait ResolvesPublicExpansions
+{
+    /**
+     * Resolve the requested expansions and rewrite the request with them.
+     *
+     * @param array<string, string> $allowed public name => Eloquent relation name
+     *
+     * @return array<int, string> the resolved relation names, in request order
+     */
+    protected function applyPublicExpansions(Request $request, array $allowed): array
+    {
+        $resolved = $this->resolvePublicExpansions($request, $allowed);
+
+        // Both keys are rewritten: Core reads `with` or `expand`, whichever is
+        // present, so leaving the other one holding raw input would put the
+        // unmapped name back in front of load().
+        $request->merge(['with' => $resolved]);
+
+        if ($request->exists('expand')) {
+            $request->merge(['expand' => $resolved]);
+        }
+
+        return $resolved;
+    }
+
+    /**
+     * @param array<string, string> $allowed
+     *
+     * @return array<int, string>
+     */
+    protected function resolvePublicExpansions(Request $request, array $allowed): array
+    {
+        $requested = $this->publicExpansionInput($request);
+        $resolved  = [];
+
+        foreach ($requested as $relation) {
+            $mapped = $this->mapPublicExpansion($relation, $allowed);
+
+            // An unsupported expansion is ignored rather than rejected. A 422
+            // would turn a harmless unknown name into a failed request for
+            // every generated client that sends a relation this version does
+            // not have yet, and the alternative — passing it through — is a
+            // 500 from Eloquent.
+            if ($mapped !== null && !in_array($mapped, $resolved, true)) {
+                $resolved[] = $mapped;
+            }
+        }
+
+        return $resolved;
+    }
+
+    /**
+     * Every accepted input shape flattened to one list of trimmed, non-empty paths.
+     *
+     * `?with=vendor`, `?with[]=vendor`, `?with=vendor,driver` and the `expand`
+     * alias of each all arrive here and leave identical.
+     *
+     * @return array<int, string>
+     */
+    protected function publicExpansionInput(Request $request): array
+    {
+        $raw = $request->input('with');
+
+        if ($raw === null || $raw === '' || $raw === []) {
+            $raw = $request->input('expand');
+        }
+
+        if ($raw === null) {
+            return [];
+        }
+
+        $values = [];
+        foreach (is_array($raw) ? $raw : [$raw] as $entry) {
+            if (is_array($entry)) {
+                continue;
+            }
+
+            foreach (explode(',', (string) $entry) as $part) {
+                $part = trim($part);
+
+                if ($part !== '') {
+                    $values[] = $part;
+                }
+            }
+        }
+
+        return $values;
+    }
+
+    /**
+     * Map one public path onto its Eloquent relation path, or null if unsupported.
+     *
+     * Each dotted segment is resolved against the allowlist for the level it sits
+     * at, so `subfleets.drivers` is checked as `subfleets` then as `drivers` —
+     * a nested path cannot smuggle in a relation the top level would refuse.
+     *
+     * @param array<string, string> $allowed
+     */
+    protected function mapPublicExpansion(string $relation, array $allowed): ?string
+    {
+        $segments = explode('.', $relation);
+        $mapped   = [];
+
+        foreach ($segments as $index => $segment) {
+            $segment = trim($segment);
+
+            if ($segment === '') {
+                return null;
+            }
+
+            $candidates = $index === 0 ? $allowed : $this->nestedExpansionAllowList();
+            $key        = $this->matchExpansionKey($segment, $candidates);
+
+            if ($key === null) {
+                return null;
+            }
+
+            $mapped[] = $candidates[$key];
+        }
+
+        return implode('.', $mapped);
+    }
+
+    /**
+     * Relations reachable underneath an already-allowed relation.
+     *
+     * Deliberately shallow. Subfleets carry drivers and vehicles, which is the
+     * documented nested case; nothing here re-opens the tree, so
+     * `subfleets.subfleets` is refused and an expansion cannot recurse.
+     *
+     * @return array<string, string>
+     */
+    protected function nestedExpansionAllowList(): array
+    {
+        return [
+            'drivers'  => 'drivers',
+            'vehicles' => 'vehicles',
+        ];
+    }
+
+    /**
+     * Match a requested segment against the allowlist, spelling-insensitively.
+     *
+     * `service_area`, `serviceArea` and `ServiceArea` all name the same relation,
+     * and so do `subfleets`, `subFleets` and `sub_fleets`. Comparing on
+     * case-folded, separator-stripped forms accepts every spelling a client or a
+     * generated SDK might produce without widening what is actually allowed.
+     *
+     * @param array<string, string> $candidates
+     */
+    private function matchExpansionKey(string $segment, array $candidates): ?string
+    {
+        foreach ($candidates as $key => $relation) {
+            if ($this->expansionLookupKey($key) === $this->expansionLookupKey($segment)) {
+                return $key;
+            }
+        }
+
+        return null;
+    }
+
+    private function expansionLookupKey(string $value): string
+    {
+        return strtolower(str_replace(['_', '-'], '', $value));
+    }
+}

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

@@ -6,6 +6,9 @@ use Fleetbase\FleetOps\Events\DriverLocationChanged;
 use Fleetbase\FleetOps\Events\GeofenceEntered;
 use Fleetbase\FleetOps\Events\GeofenceExited;
 use Fleetbase\FleetOps\Events\VehicleLocationChanged;
+use Fleetbase\FleetOps\Exceptions\PublicRelationNotFoundException;
+use Fleetbase\FleetOps\Http\Controllers\Api\v1\Concerns\ResolvesFleetOpsApiResources;
+use Fleetbase\FleetOps\Http\Controllers\Api\v1\Concerns\ResolvesPublicExpansions;
 use Fleetbase\FleetOps\Http\Requests\CreateDriverRequest;
 use Fleetbase\FleetOps\Http\Requests\DriverSimulationRequest;
 use Fleetbase\FleetOps\Http\Requests\UpdateDriverRequest;
@@ -16,6 +19,7 @@ use Fleetbase\FleetOps\Jobs\SimulateDrivingRoute;
 use Fleetbase\FleetOps\Models\Driver;
 use Fleetbase\FleetOps\Models\Order;
 use Fleetbase\FleetOps\Models\Vehicle;
+use Fleetbase\FleetOps\Models\Vendor;
 use Fleetbase\FleetOps\Support\GeofenceIntersectionService;
 use Fleetbase\FleetOps\Support\OSRM;
 use Fleetbase\FleetOps\Support\Utils;
@@ -40,6 +44,23 @@ use Illuminate\Support\Str;
 class DriverController extends Controller
 {
     use \Fleetbase\FleetOps\Http\Controllers\Concerns\ResolvesReviewAccountBypass;
+    use ResolvesFleetOpsApiResources;
+    use ResolvesPublicExpansions;
+
+    /**
+     * Public expansion name => Eloquent relation name.
+     *
+     * `user` and `company` are deliberately absent. Both are already published
+     * as public-id strings, and Navigator interpolates `driver.user` directly
+     * into a socket channel name — expanding either would retype a released
+     * field and break it silently.
+     */
+    public const EXPANDABLE = [
+        'vehicle'     => 'vehicle',
+        'vendor'      => 'vendor',
+        'current_job' => 'currentJob',
+        'fleets'      => 'fleets',
+    ];
 
     /**
      * Creates a new Fleetbase Driver resource.
@@ -48,11 +69,7 @@ class DriverController extends Controller
      */
     public function create(CreateDriverRequest $request)
     {
-        // get request input
-        $input = $request->except(['name', 'password', 'email', 'phone', 'location', 'altitude', 'heading', 'speed', 'meta']);
-
-        // Add default status
-        $input['status'] = $request->input('status', 'available');
+        $this->applyPublicExpansions($request, static::EXPANDABLE);
 
         // get user details for driver
         $userDetails                 = $request->only(['name', 'password', 'email', 'phone', 'timezone']);
@@ -65,6 +82,18 @@ class DriverController extends Controller
             return $this->apiError('Company not found.');
         }
 
+        // get request input. Relationship inputs resolve against the company the
+        // driver is being created in, which is not always the session company —
+        // a request may name one explicitly.
+        try {
+            $input = $this->driverInputFromRequest($request, $company->uuid);
+        } catch (PublicRelationNotFoundException $exception) {
+            return $this->jsonResponse(['error' => $exception->getMessage()], 404);
+        }
+
+        // Add default status
+        $input['status'] = $request->input('status', 'available');
+
         // Apply user infos
         $userDetails = $this->applyUserInfoFromRequest($request, $userDetails);
 
@@ -87,30 +116,6 @@ class DriverController extends Controller
         $input['user_uuid']    = $user->uuid;
         $input['company_uuid'] = $company->uuid;  // Ensure correct company_uuid is set
 
-        // vehicle assignment public_id -> uuid
-        if ($request->has('vehicle')) {
-            $input['vehicle_uuid'] = $this->getUuid('vehicles', [
-                'public_id'    => $request->input('vehicle'),
-                'company_uuid' => $company->uuid,  // Use $company->uuid instead of session
-            ]);
-        }
-
-        // vendor assignment public_id -> uuid
-        if ($request->has('vendor')) {
-            $input['vendor_uuid'] = $this->getUuid('vendors', [
-                'public_id'    => $request->input('vendor'),
-                'company_uuid' => $company->uuid,  // Use $company->uuid instead of session
-            ]);
-        }
-
-        // order|alias:job assignment public_id -> uuid
-        if ($request->has('job')) {
-            $input['current_job_uuid'] = $this->getUuid('orders', [
-                'public_id'    => $request->input('job'),
-                'company_uuid' => $company->uuid,  // Use $company->uuid instead of session
-            ]);
-        }
-
         // set default online
         if (!isset($input['online'])) {
             $input['online'] = 0;
@@ -130,7 +135,11 @@ class DriverController extends Controller
             $file = $this->resolveFile($request->input('photo'), $path);
 
             if ($file) {
-                $user->update(['photo_uuid' => $file->uuid]);
+                // `photo_uuid` is not a column on users — the avatar lives in
+                // `avatar_uuid`, and User guards mass assignment by fillable, so
+                // the old key was dropped without a word and every driver photo
+                // uploaded through the public API was discarded.
+                $user->update(['avatar_uuid' => $file->uuid]);
             }
         }
 
@@ -151,6 +160,8 @@ class DriverController extends Controller
      */
     public function update($id, UpdateDriverRequest $request)
     {
+        $this->applyPublicExpansions($request, static::EXPANDABLE);
+
         // find for the driver
         try {
             $driver = $this->findDriver($id, ['user']);
@@ -164,10 +175,23 @@ class DriverController extends Controller
         }
 
         // get request input
-        $input = $request->except(['name', 'password', 'email', 'phone', 'location', 'altitude', 'heading', 'speed', 'meta']);
+        try {
+            $input = $this->driverInputFromRequest($request);
+        } catch (PublicRelationNotFoundException $exception) {
+            return $this->jsonResponse(['error' => $exception->getMessage()], 404);
+        }
 
-        // get user details for driver
-        $userDetails = $request->only(['name', 'password', 'email', 'phone']);
+        /*
+         * Deliberately no `password` here. Setting one through a general update
+         * meant anyone holding a driver's token — or an unlocked handset —
+         * could take the account without proving they knew the existing
+         * password. Changing a password is its own operation with its own
+         * proof: see changePassword(), forgotPassword() and resetPassword().
+         */
+        // `timezone` is accepted and documented on update, but was never copied
+        // to the linked user — the request validated, answered 200, and dropped
+        // it. The driver's own record has no timezone column; the user's does.
+        $userDetails = $request->only(['name', 'email', 'phone', 'timezone']);
 
         // update driver user details
         $driverUser = $driver->getUser();
@@ -175,30 +199,6 @@ class DriverController extends Controller
             $driverUser->update($userDetails);
         }
 
-        // vehicle assignment public_id -> uuid
-        if ($request->has('vehicle')) {
-            $input['vehicle_uuid'] = $this->getUuid('vehicles', [
-                'public_id'    => $request->input('vehicle'),
-                'company_uuid' => $this->sessionCompany(),
-            ]);
-        }
-
-        // vendor assignment public_id -> uuid
-        if ($request->has('vendor')) {
-            $input['vendor_uuid'] = $this->getUuid('vendors', [
-                'public_id'    => $request->input('vendor'),
-                'company_uuid' => $this->sessionCompany(),
-            ]);
-        }
-
-        // order|alias:job assignment public_id -> uuid
-        if ($request->has('job')) {
-            $input['current_job_uuid'] = $this->getUuid('orders', [
-                'public_id'    => $request->input('job'),
-                'company_uuid' => $this->sessionCompany(),
-            ]);
-        }
-
         // latitude / longitude
         if ($request->has(['latitude', 'longitude'])) {
             $input['location'] = $this->pointFromCoordinates($request->only(['latitude', 'longitude']));
@@ -214,7 +214,7 @@ class DriverController extends Controller
             $file = $this->resolveFile($request->input('photo'), $path);
 
             if ($file) {
-                $driver->user->update(['photo_uuid' => $file->uuid]);
+                $driver->user->update(['avatar_uuid' => $file->uuid]);
             }
         }
 
@@ -232,6 +232,8 @@ class DriverController extends Controller
      */
     public function query(Request $request)
     {
+        $this->applyPublicExpansions($request, static::EXPANDABLE);
+
         $results = $this->queryDrivers($request);
 
         return $this->driverResourceCollection($results);
@@ -246,6 +248,11 @@ class DriverController extends Controller
      */
     public function find($id)
     {
+        // Retrieve carries no Request parameter, so the container's is used —
+        // otherwise an unsupported `with` on this endpoint would reach Eloquent
+        // unmapped.
+        $this->applyPublicExpansions(request(), static::EXPANDABLE);
+
         // find for the driver
         try {
             $driver = $this->findDriver($id, ['user', 'vehicle', 'vendor', 'currentJob']);
@@ -913,6 +920,41 @@ class DriverController extends Controller
         return response()->json($route);
     }
 
+    /**
+     * The explicit public input allowlist for a driver.
+     *
+     * Replaces an `except()` blocklist: anything not named here — `user_uuid`,
+     * `company_uuid`, `auth_token`, `signup_token_used`, `public_id`, `uuid`,
+     * `_key`, the generated `slug`, and the raw `*_uuid` relation columns — used
+     * to reach `Driver::create()` intact simply because nobody had thought to
+     * exclude it. `location`, `heading`, `altitude`, `speed` and `meta` were on
+     * that blocklist and so were dropped on every write, which is why a driver's
+     * metadata never persisted through the public API.
+     *
+     * @throws PublicRelationNotFoundException
+     */
+    protected function driverInputFromRequest(Request $request, ?string $companyUuid = null): array
+    {
+        $input = $request->only([
+            // Identity
+            'internal_id', 'drivers_license_number', 'license_expiry',
+            // Operational
+            'country', 'currency', 'city', 'online', 'current_status', 'status',
+            'location', 'heading', 'bearing', 'altitude', 'speed',
+            // Structured / orchestrator
+            'meta', 'skills', 'max_travel_time', 'max_distance',
+            'time_window_start', 'time_window_end',
+        ]);
+
+        $this->applyPublicIdRelations($input, [
+            'vehicle' => ['vehicle_uuid', Vehicle::class],
+            'vendor'  => ['vendor_uuid', Vendor::class],
+            'job'     => ['current_job_uuid', Order::class],
+        ], $request, $companyUuid);
+
+        return $input;
+    }
+
     protected function companyFromRequest(Request $request): ?Company
     {
         return Auth::getCompanyFromRequest($request);
@@ -935,7 +977,24 @@ class DriverController extends Controller
 
     protected function createUser(array $userDetails): User
     {
-        return User::create($userDetails);
+        /*
+         * `password` is guarded on User, so mass assignment drops it without a
+         * word. The create endpoint has always accepted and validated one, so a
+         * driver created through the API could never sign in with the password
+         * their operator chose for them. Set it after the fact, where the
+         * model's mutator hashes it.
+         */
+        $password = $userDetails['password'] ?? null;
+        unset($userDetails['password']);
+
+        $user = User::create($userDetails);
+
+        if (is_string($password) && strlen($password)) {
+            $user->password = $password;
+            $user->save();
+        }
+
+        return $user;
     }
 
     protected function getUuid(array|string $table, array $where, array $options = []): mixed
@@ -1177,4 +1236,198 @@ class DriverController extends Controller
             }
         }
     }
+
+    /**
+     * Change the authenticated driver's password, proving the current one.
+     *
+     * A password change is an authorisation decision, not an attribute update.
+     * Requiring the existing password is what stops a borrowed handset or a
+     * leaked token from becoming a permanent account takeover, and re-issuing
+     * the caller's token afterwards is what stops every *other* session from
+     * outliving the change.
+     */
+    public function changePassword(Request $request, string $id)
+    {
+        $current  = $request->input('current_password');
+        $password = $request->input('password');
+
+        if (!$current || !$password) {
+            return response()->apiError('current_password and password are required.', 400);
+        }
+
+        if (strlen($password) < 8) {
+            return response()->apiError('Password must be at least 8 characters.', 400);
+        }
+
+        if ($request->filled('password_confirmation') && $request->input('password_confirmation') !== $password) {
+            return response()->apiError('Password confirmation does not match.', 422);
+        }
+
+        try {
+            $driver = $this->findDriver($id, ['user']);
+        } catch (\Illuminate\Database\Eloquent\ModelNotFoundException $exception) {
+            return response()->apiError('Driver resource not found.', 404);
+        }
+
+        $user = static::findDriverUserRecord($driver);
+        if (!$user) {
+            return response()->apiError('Driver has no user account.', 422);
+        }
+
+        if (!static::passwordMatches($user, $current)) {
+            // Same wording whether the password was wrong or the account is odd
+            // — a change endpoint should not become an oracle.
+            return response()->apiError('The current password is incorrect.', 422);
+        }
+
+        $user->password = $password;
+        $user->save();
+
+        /*
+         * Every other session dies with the old password. The caller keeps
+         * working by being handed a fresh token in the same response, so a
+         * driver who changes their password mid-shift is not signed out of the
+         * device in their hand.
+         */
+        $user->tokens()->delete();
+        $token = $user->createToken($request->input('device_name', 'navigator'));
+
+        return response()->json([
+            'status' => 'ok',
+            'token'  => $token->plainTextToken,
+        ]);
+    }
+
+    /**
+     * Send a password reset code to a driver who cannot sign in.
+     *
+     * Answers identically whether or not the identity exists: a reset endpoint
+     * that 404s on an unknown phone number is a way to enumerate a company's
+     * drivers.
+     */
+    public function forgotPassword(Request $request)
+    {
+        $identity = $request->input('identity');
+        if (!$identity) {
+            return response()->apiError('Identity is required.', 400);
+        }
+
+        $user = static::findDriverUserByIdentity($identity);
+        if (!$user) {
+            return response()->json(['status' => 'ok']);
+        }
+
+        try {
+            static::sendResetCode($user, $identity);
+        } catch (\Throwable $e) {
+            return response()->apiError(static::debugEnabled() ? $e->getMessage() : 'Unable to send reset code.');
+        }
+
+        return response()->json(['status' => 'ok']);
+    }
+
+    /**
+     * Set a new password using a code sent by forgotPassword().
+     */
+    public function resetPassword(Request $request)
+    {
+        $identity = $request->input('identity');
+        $code     = $request->input('code');
+        $password = $request->input('password');
+
+        if (!$identity || !$code || !$password) {
+            return response()->apiError('identity, code, and password are required.', 400);
+        }
+
+        if (strlen($password) < 8) {
+            return response()->apiError('Password must be at least 8 characters.', 400);
+        }
+
+        $user = static::findDriverUserByIdentity($identity);
+        if (!$user) {
+            return response()->apiError('Invalid or expired reset code.', 422);
+        }
+
+        $verification = static::findResetCode($user, $code);
+
+        if (!$verification) {
+            // One message for a wrong code, an expired code and an unknown
+            // identity alike.
+            return response()->apiError('Invalid or expired reset code.', 422);
+        }
+
+        $user->password = $password;
+        $user->save();
+
+        $verification->delete();
+        $user->tokens()->delete();
+
+        return response()->json(['status' => 'ok']);
+    }
+
+    /** Whether the application is in debug mode, so an error may be echoed. */
+    protected static function debugEnabled(): bool
+    {
+        return app()->hasDebugModeEnabled();
+    }
+
+    /**
+     * Load a driver's user account with every column.
+     *
+     * The `user` relation selects a named subset of columns, and `password` is
+     * not among them — reading it through the relation yields an empty string,
+     * so a password comparison would fail for everyone regardless of what they
+     * typed. Anything checking a password has to load the record itself.
+     */
+    protected static function findDriverUserRecord(Driver $driver): ?User
+    {
+        if (!$driver->user_uuid) {
+            return null;
+        }
+
+        return User::where('uuid', $driver->user_uuid)->first();
+    }
+
+    /** Whether a plaintext password matches the stored hash. */
+    protected static function passwordMatches(User $user, string $plain): bool
+    {
+        return Hash::check($plain, $user->password);
+    }
+
+    /** The unexpired reset code for this user, if the one supplied matches. */
+    protected static function findResetCode(User $user, string $code)
+    {
+        return VerificationCode::where([
+            'subject_uuid' => $user->uuid,
+            'code'         => $code,
+            'for'          => 'driver_password_reset',
+        ])->where('expires_at', '>', now())->first();
+    }
+
+    /** Sends the reset code by whichever channel the identity names. */
+    protected static function sendResetCode(User $user, string $identity): void
+    {
+        // if/else rather than an early return: a `return` sitting after a call
+        // that can throw is a line no test can reach.
+        if (Utils::isEmail($identity)) {
+            VerificationCode::generateEmailVerificationFor($user, 'driver_password_reset', [
+                'subject'         => config('app.name') . ' password reset',
+                'messageCallback' => fn ($v) => 'Your ' . config('app.name') . ' password reset code is ' . $v->code,
+            ]);
+        } else {
+            VerificationCode::generateSmsVerificationFor($user, 'driver_password_reset', [
+                'messageCallback' => fn ($v) => 'Your ' . config('app.name') . ' password reset code is ' . $v->code,
+            ]);
+        }
+    }
+
+    /** Resolve a driver's user account from an email address or a phone number. */
+    protected static function findDriverUserByIdentity(string $identity): ?User
+    {
+        $isEmail = Utils::isEmail($identity);
+        $column  = $isEmail ? 'email' : 'phone';
+        $value   = $isEmail ? $identity : static::phone($identity);
+
+        return User::whereHas('driver')->where($column, $value)->first();
+    }
 }

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

@@ -271,7 +271,7 @@ class EntityController extends Controller
         return $value ? Utils::singularize($value) : null;
     }
 
-    protected function findPayloadByPublicId(string $publicId): ?Payload
+    protected function findPayloadByPublicId(?string $publicId): ?Payload
     {
         return Payload::where('public_id', $publicId)->first();
     }