@fleetbase/fleetops-engine 0.6.70 → 0.6.72

package/server/tests/Unit/Support/TrackingChannelTest.php

@@ -0,0 +1,232 @@
+<?php
+
+use Fleetbase\FleetOps\Models\Contact;
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Models\Vendor;
+use Fleetbase\FleetOps\Models\Waypoint;
+use Fleetbase\FleetOps\Support\TrackingChannel;
+use Fleetbase\FleetOps\Support\TrackingScope;
+use Fleetbase\Support\SocketCluster\SocketToken;
+use Illuminate\Database\ConnectionResolver;
+use Illuminate\Database\Eloquent\Model as EloquentModel;
+use Illuminate\Database\SQLiteConnection;
+
+/**
+ * Covers the public tracking channel: the per-customer TrackingScope, the opaque channel id
+ * (deterministic, keyed, distinct per customer), and the scoped tracking token.
+ */
+const TRACKING_CHANNEL_KEY = 'fleetops-tracking-channel-test-key-0123456789';
+
+function trackingChannelModel(string $class, array $attributes): EloquentModel
+{
+    $model = (new ReflectionClass($class))->newInstanceWithoutConstructor();
+    $model->setRawAttributes($attributes, true);
+
+    return $model;
+}
+
+function trackingChannelOrder(array $attributes = []): Order
+{
+    return trackingChannelModel(Order::class, array_merge([
+        'uuid'          => 'order-1111',
+        'company_uuid'  => 'company-1111',
+        'customer_type' => 'Fleetbase\\FleetOps\\Models\\Contact',
+        'customer_uuid' => 'contact-1111',
+        'payload_uuid'  => 'payload-1111',
+    ], $attributes));
+}
+
+function trackingChannelWaypoint(?string $customerUuid, string $customerType = 'Fleetbase\\FleetOps\\Models\\Contact'): Waypoint
+{
+    return trackingChannelModel(Waypoint::class, ['uuid' => 'waypoint-' . ($customerUuid ?? 'none'), 'customer_uuid' => $customerUuid, 'customer_type' => $customerUuid ? $customerType : null]);
+}
+
+/**
+ * Independent base32 (RFC 4648, lowercase, unpadded) to check the channel id against.
+ */
+function trackingChannelBase32(string $bytes): string
+{
+    $alphabet = 'abcdefghijklmnopqrstuvwxyz234567';
+    $buffer   = 0;
+    $bits     = 0;
+    $out      = '';
+    foreach (unpack('C*', $bytes) as $byte) {
+        $buffer = ($buffer << 8) | $byte;
+        $bits += 8;
+        while ($bits >= 5) {
+            $bits -= 5;
+            $out .= $alphabet[($buffer >> $bits) & 31];
+        }
+    }
+    if ($bits > 0) {
+        $out .= $alphabet[($buffer << (5 - $bits)) & 31];
+    }
+
+    return $out;
+}
+
+function trackingChannelEnable(?string $key = TRACKING_CHANNEL_KEY): void
+{
+    // Socket authentication needs both the switch and the signing key.
+    config([
+        'broadcasting.connections.socketcluster.auth_enabled' => $key !== null,
+        'broadcasting.connections.socketcluster.auth_key'     => $key,
+    ]);
+}
+
+afterEach(function () {
+    trackingChannelEnable(null);
+});
+
+test('a tracking scope identifies one customer of one order', function () {
+    $order = trackingChannelOrder();
+    $scope = TrackingScope::forOrder($order);
+
+    expect($scope->order_uuid)->toBe('order-1111')
+        ->and($scope->customer_type)->toBe('Fleetbase\\FleetOps\\Models\\Contact')
+        ->and($scope->customer_uuid)->toBe('contact-1111')
+        ->and($scope->company_uuid)->toBe('company-1111')
+        ->and($scope->key())->toBe('order-1111:Fleetbase\\FleetOps\\Models\\Contact:contact-1111')
+        ->and($scope->toArray())->toBe(['order_uuid' => 'order-1111', 'customer_type' => 'Fleetbase\\FleetOps\\Models\\Contact', 'customer_uuid' => 'contact-1111'])
+        ->and(json_encode($scope))->toBe(json_encode($scope->toArray()))
+        ->and($scope->order())->toBe($order)
+        ->and($scope->isOrderCustomer($order))->toBeTrue();
+
+    // A leading backslash on a stored morph type does not change the scope.
+    expect((new TrackingScope('order-1111', '\\Fleetbase\\FleetOps\\Models\\Contact', 'contact-1111'))->key())->toBe($scope->key())
+        ->and($scope->is('\\Fleetbase\\FleetOps\\Models\\Contact', 'contact-1111'))->toBeTrue()
+        ->and($scope->is('Fleetbase\\FleetOps\\Models\\Vendor', 'contact-1111'))->toBeFalse()
+        ->and($scope->is('Fleetbase\\FleetOps\\Models\\Contact', null))->toBeFalse();
+
+    // An order without a customer has no order scope.
+    expect(TrackingScope::forOrder(trackingChannelOrder(['customer_uuid' => null])))->toBeNull();
+
+    expect(fn () => new TrackingScope('order-1111', '', 'contact-1111'))->toThrow(InvalidArgumentException::class);
+});
+
+test('each stop belongs to its waypoint customer, else to the order customer', function () {
+    $order      = trackingChannelOrder();
+    $own        = trackingChannelWaypoint(null);
+    $neighbour  = trackingChannelWaypoint('contact-2222');
+    $vendorStop = trackingChannelWaypoint('vendor-3333', 'Fleetbase\\FleetOps\\Models\\Vendor');
+
+    $orderScope     = TrackingScope::forOrder($order);
+    $neighbourScope = TrackingScope::forStop($order, $neighbour);
+
+    expect(TrackingScope::forStop($order, $own)->key())->toBe($orderScope->key())
+        ->and(TrackingScope::forStop($order)->key())->toBe($orderScope->key())
+        ->and($neighbourScope->customer_uuid)->toBe('contact-2222')
+        ->and($orderScope->ownsStop($order, $own))->toBeTrue()
+        ->and($orderScope->ownsStop($order, null))->toBeTrue()
+        ->and($orderScope->ownsStop($order, $neighbour))->toBeFalse()
+        ->and($neighbourScope->ownsStop($order, $neighbour))->toBeTrue()
+        ->and($neighbourScope->ownsStop($order, $own))->toBeFalse()
+        ->and($neighbourScope->isOrderCustomer($order))->toBeFalse();
+
+    $scopes = TrackingScope::allForOrder($order, [$own, $neighbour, $vendorStop, $neighbour, 'not a waypoint']);
+    expect(array_map(fn (TrackingScope $scope) => $scope->customer_uuid, $scopes))->toBe(['contact-1111', 'contact-2222', 'vendor-3333'])
+        ->and($scopes[2]->customer_type)->toBe(Vendor::class);
+
+    // An explicit customer model.
+    $contact = trackingChannelModel(Contact::class, ['uuid' => 'contact-2222']);
+    expect(TrackingScope::forCustomer($order, $contact)->key())->toBe($neighbourScope->key());
+});
+
+test('a tracking scope loads its order and its waypoints when not given', function () {
+    $connection = new SQLiteConnection(new PDO('sqlite::memory:'));
+    $resolver   = new ConnectionResolver(['default' => $connection, 'mysql' => $connection]);
+    $resolver->setDefaultConnection('mysql');
+    EloquentModel::setConnectionResolver($resolver);
+    $schema = $connection->getSchemaBuilder();
+    foreach (['orders', 'waypoints'] as $table) {
+        $schema->create($table, function ($blueprint) {
+            $blueprint->increments('id');
+            foreach (['uuid', 'public_id', 'company_uuid', 'payload_uuid', 'place_uuid', 'customer_uuid', 'customer_type'] as $column) {
+                $blueprint->string($column)->nullable();
+            }
+            $blueprint->timestamps();
+            $blueprint->timestamp('deleted_at')->nullable();
+        });
+    }
+    $connection->table('orders')->insert(['uuid' => 'order-1111', 'company_uuid' => 'company-1111', 'customer_uuid' => 'contact-1111', 'customer_type' => 'Fleetbase\\FleetOps\\Models\\Contact', 'payload_uuid' => 'payload-1111']);
+    $connection->table('waypoints')->insert([
+        ['uuid' => 'waypoint-1', 'payload_uuid' => 'payload-1111', 'customer_uuid' => 'contact-2222', 'customer_type' => 'Fleetbase\\FleetOps\\Models\\Contact'],
+        ['uuid' => 'waypoint-2', 'payload_uuid' => 'payload-1111', 'customer_uuid' => null, 'customer_type' => null],
+        ['uuid' => 'waypoint-3', 'payload_uuid' => 'payload-other', 'customer_uuid' => 'contact-9999', 'customer_type' => 'Fleetbase\\FleetOps\\Models\\Contact'],
+    ]);
+
+    $scope = new TrackingScope('order-1111', 'Fleetbase\\FleetOps\\Models\\Contact', 'contact-1111');
+    expect($scope->company_uuid)->toBeNull()
+        ->and($scope->order()?->uuid)->toBe('order-1111');
+
+    $order = $scope->order();
+    expect(array_map(fn (TrackingScope $scope) => $scope->customer_uuid, TrackingScope::allForOrder($order)))->toBe(['contact-1111', 'contact-2222'])
+        ->and(TrackingScope::allForOrder(trackingChannelOrder(['payload_uuid' => null])))->toHaveCount(1);
+
+    // A scope given another order's model ignores it.
+    expect((new TrackingScope('order-1111', 'Fleetbase\\FleetOps\\Models\\Contact', 'contact-1111', trackingChannelOrder(['uuid' => 'order-other'])))->company_uuid)->toBeNull();
+});
+
+test('the channel id is an unguessable keyed hmac of the scope, distinct per customer', function () {
+    trackingChannelEnable();
+    $order     = trackingChannelOrder();
+    $scope     = TrackingScope::forOrder($order);
+    $neighbour = TrackingScope::forStop($order, trackingChannelWaypoint('contact-2222'));
+
+    $trackingKey = hash_hmac('sha256', 'fleetbase-socket:tracking', TRACKING_CHANNEL_KEY);
+    $expected    = substr(trackingChannelBase32(hash_hmac('sha256', 'order-1111:Fleetbase\\FleetOps\\Models\\Contact:contact-1111', $trackingKey, true)), 0, 26);
+
+    expect(TrackingChannel::opaqueId($scope))->toBe($expected)
+        ->and(TrackingChannel::opaqueId($scope))->toMatch('/^[a-z2-7]{26}$/')
+        ->and(TrackingChannel::name($scope))->toBe('tracking.' . $expected)
+        ->and(TrackingChannel::name(TrackingScope::forOrder(trackingChannelOrder())))->toBe('tracking.' . $expected)
+        ->and(TrackingChannel::name($neighbour))->not->toBe(TrackingChannel::name($scope))
+        ->and(trackingChannelBase32('foobar'))->toBe('mzxw6ytboi');
+
+    // Another key yields other channels: the id cannot be computed without the key.
+    trackingChannelEnable('another-fleetops-tracking-channel-key-987654321');
+    expect(TrackingChannel::opaqueId($scope))->not->toBe($expected);
+});
+
+test('channels and tokens need socket authentication to be configured', function () {
+    trackingChannelEnable(null);
+    $scope = TrackingScope::forOrder(trackingChannelOrder());
+
+    expect(fn () => TrackingChannel::name($scope))->toThrow(RuntimeException::class)
+        ->and(fn () => TrackingChannel::token($scope))->toThrow(RuntimeException::class);
+});
+
+test('a tracking token may subscribe to its own channel only', function () {
+    trackingChannelEnable();
+    $scope = TrackingScope::forOrder(trackingChannelOrder());
+
+    $minted    = TrackingChannel::token($scope);
+    $principal = SocketToken::verify($minted['token']);
+
+    expect($minted['expires_in'])->toBe(1800)
+        ->and($minted['expires_at'])->toBeString()
+        ->and($principal->kind)->toBe('tracking')
+        ->and($principal->sub)->toBe(TrackingChannel::opaqueId($scope))
+        ->and($principal->scp)->toBe([TrackingChannel::name($scope)])
+        ->and($principal->cid)->toBe('company-1111')
+        ->and($principal->adm)->toBeFalse();
+
+    // A scope without its order model still mints a token scoped to its channel.
+    $connection = new SQLiteConnection(new PDO('sqlite::memory:'));
+    $resolver   = new ConnectionResolver(['default' => $connection, 'mysql' => $connection]);
+    $resolver->setDefaultConnection('mysql');
+    EloquentModel::setConnectionResolver($resolver);
+    $connection->getSchemaBuilder()->create('orders', function ($blueprint) {
+        $blueprint->increments('id');
+        $blueprint->string('uuid')->nullable();
+        $blueprint->string('company_uuid')->nullable();
+        $blueprint->timestamps();
+        $blueprint->timestamp('deleted_at')->nullable();
+    });
+    $connection->table('orders')->insert(['uuid' => 'order-2222', 'company_uuid' => 'company-2222']);
+
+    $scope  = new TrackingScope('order-2222', Contact::class, 'contact-1111');
+    $loaded = SocketToken::verify(TrackingChannel::token($scope)['token']);
+    expect($loaded->cid)->toBe('company-2222')
+        ->and($loaded->scp)->toBe([TrackingChannel::name($scope)]);
+});

package/server/tests/Unit/Support/TrackingCodeTest.php

@@ -0,0 +1,186 @@
+<?php
+
+use Fleetbase\FleetOps\Support\TrackingCode;
+
+beforeEach(function () {
+    $this->previousConsoleConfig = config('fleetbase.console');
+    config(['fleetbase.console' => ['host' => 'console.fleetbase.test', 'subdomain' => null, 'secure' => true]]);
+});
+
+afterEach(function () {
+    config(['fleetbase.console' => $this->previousConsoleConfig]);
+});
+
+test('qr content is a versioned tracking url naming the owner by public id', function () {
+    expect(TrackingCode::qrContent('ACM1234567890SG', 'order_a1b2c3d'))
+        ->toBe('https://console.fleetbase.test/~/track-order?order=ACM1234567890SG&r=order_a1b2c3d&v=1')
+        // No owner: the tracking number alone still resolves.
+        ->and(TrackingCode::qrContent('ACM1234567890SG'))
+        ->toBe('https://console.fleetbase.test/~/track-order?order=ACM1234567890SG&v=1')
+        // Tracking numbers start with the company name, which may hold spaces.
+        ->and(TrackingCode::qrContent('A B1234567890SG', ''))
+        ->toBe('https://console.fleetbase.test/~/track-order?order=A+B1234567890SG&v=1');
+});
+
+test('qr content follows the configured console origin but never the app environment', function () {
+    config(['fleetbase.console' => ['host' => 'fleetbase.test', 'subdomain' => 'console', 'secure' => false]]);
+    expect(TrackingCode::qrContent('TN1', 'order_x'))->toBe('http://console.fleetbase.test/~/track-order?order=TN1&r=order_x&v=1');
+
+    config(['fleetbase.console' => ['host' => 'https://tracking.example.test/', 'subdomain' => 'ignored']]);
+    expect(TrackingCode::qrContent('TN1'))->toBe('https://tracking.example.test/~/track-order?order=TN1&v=1');
+
+    // Unset `secure` defaults to https, whatever environment generated the label.
+    config(['fleetbase.console' => ['host' => 'console.fleetbase.test']]);
+    expect(TrackingCode::qrContent('TN1'))->toStartWith('https://console.fleetbase.test/');
+});
+
+test('barcode content is the bare tracking number printed beneath it', function () {
+    expect(TrackingCode::barcodeContent('ACM1234567890SG'))->toBe('ACM1234567890SG');
+});
+
+test('parse reads every code format in circulation', function () {
+    $empty = ['uuid' => null, 'tracking_number' => null, 'public_id' => null, 'reference' => null, 'version' => null];
+
+    // Generated codes round-trip.
+    expect(TrackingCode::parse(TrackingCode::qrContent('ACM1234567890SG', 'waypoint_a1b2c3d')))->toBe(array_merge($empty, [
+        'tracking_number' => 'ACM1234567890SG',
+        'public_id'       => 'waypoint_a1b2c3d',
+        'version'         => 1,
+    ]))
+        // Legacy labels encode the owner's bare uuid.
+        ->and(TrackingCode::parse(' 6f1c2a4e-8b3d-4c5f-9a7e-1d2c3b4a5f60 '))->toBe(array_merge($empty, [
+            'uuid' => '6f1c2a4e-8b3d-4c5f-9a7e-1d2c3b4a5f60',
+        ]))
+        // A barcode, or a value typed by hand, may be a tracking number or a public id.
+        ->and(TrackingCode::parse('ACM1234567890SG'))->toBe(array_merge($empty, ['reference' => 'ACM1234567890SG']))
+        ->and(TrackingCode::parse(''))->toBe($empty)
+        ->and(TrackingCode::parse(null))->toBe($empty);
+});
+
+test('parse ignores host and path and tolerates hostile or partial urls', function () {
+    // Any host, a `tn` alias, and a tracking number carried in a deeper path.
+    expect(TrackingCode::parse('HTTPS://old-domain.example/track-order?tn=TN9&r=entity_e1&v=2'))->toMatchArray([
+        'tracking_number' => 'TN9',
+        'public_id'       => 'entity_e1',
+        'version'         => 2,
+    ])
+        ->and(TrackingCode::parse('https://console.example/~/track/TN%2042?r=order_o1'))->toMatchArray([
+            'tracking_number' => 'TN 42',
+            'public_id'       => 'order_o1',
+            'version'         => null,
+        ])
+        // The tracking page's own path is not mistaken for a tracking number.
+        ->and(TrackingCode::parse('https://console.example/track-order?r=order_o1'))->toMatchArray([
+            'tracking_number' => null,
+            'public_id'       => 'order_o1',
+        ])
+        // Array or blank parameters and a non-numeric version are dropped, not trusted.
+        ->and(TrackingCode::parse('https://console.example/track-order?order[]=a&r=%20&v=1x'))->toMatchArray([
+            'tracking_number' => null,
+            'public_id'       => null,
+            'version'         => null,
+        ])
+        // parse_url() rejects this outright.
+        ->and(TrackingCode::parse('http:///track-order'))->toMatchArray([
+            'tracking_number' => null,
+            'public_id'       => null,
+            'version'         => null,
+        ]);
+});
+
+test('matches accepts legacy and new codes for the scanned subject only', function () {
+    $order = (object) [
+        'uuid'           => '6f1c2a4e-8b3d-4c5f-9a7e-1d2c3b4a5f60',
+        'public_id'      => 'order_a1b2c3d',
+        'trackingNumber' => (object) ['tracking_number' => 'ACM1234567890SG'],
+    ];
+
+    expect(TrackingCode::matches('6f1c2a4e-8b3d-4c5f-9a7e-1d2c3b4a5f60', $order))->toBeTrue()
+        ->and(TrackingCode::matches('00000000-0000-4000-8000-000000000000', $order))->toBeFalse()
+        ->and(TrackingCode::matches(TrackingCode::qrContent('ACM1234567890SG', 'order_a1b2c3d'), $order))->toBeTrue()
+        // Handhelds may not preserve case.
+        ->and(TrackingCode::matches('acm1234567890sg', $order))->toBeTrue()
+        ->and(TrackingCode::matches('order_a1b2c3d', $order))->toBeTrue()
+        ->and(TrackingCode::matches('order_other', $order))->toBeFalse()
+        ->and(TrackingCode::matches(TrackingCode::qrContent('ACM1234567890SG'), $order))->toBeTrue()
+        ->and(TrackingCode::matches('https://console.example/track-order?r=order_a1b2c3d', $order))->toBeTrue()
+        // The owner named in the code decides: another owner is refused even with this
+        // subject's tracking number, while a second tracking number issued for this
+        // subject still names it and matches.
+        ->and(TrackingCode::matches(TrackingCode::qrContent('ACM1234567890SG', 'order_other'), $order))->toBeFalse()
+        ->and(TrackingCode::matches(TrackingCode::qrContent('ACM0000000000SG', 'order_a1b2c3d'), $order))->toBeTrue()
+        // Without an owner, the number must be this subject's.
+        ->and(TrackingCode::matches(TrackingCode::qrContent('ACM0000000000SG'), $order))->toBeFalse()
+        // A URL that names nothing matches nothing.
+        ->and(TrackingCode::matches('https://console.example/track-order', $order))->toBeFalse()
+        ->and(TrackingCode::matches('', $order))->toBeFalse()
+        // A request may carry a scanner's whole result object instead of its value.
+        ->and(TrackingCode::matches(['type' => 'qr', 'value' => 'order_a1b2c3d'], $order))->toBeFalse()
+        ->and(TrackingCode::matches(null, $order))->toBeFalse()
+        ->and(TrackingCode::matches('order_a1b2c3d', null))->toBeFalse()
+        ->and(TrackingCode::matches('order_a1b2c3d', (object) ['public_id' => 'order_a1b2c3d']))->toBeFalse();
+});
+
+test('matches decides a subject without its own tracking number by public id', function () {
+    // A service stop resolves to a place, which has no tracking number of its own.
+    $place = (object) ['uuid' => 'place-uuid', 'public_id' => 'place_p1'];
+
+    expect(TrackingCode::matches(TrackingCode::qrContent('ACM1234567890SG', 'place_p1'), $place))->toBeTrue()
+        ->and(TrackingCode::matches(TrackingCode::qrContent('ACM1234567890SG'), $place))->toBeFalse()
+        ->and(TrackingCode::matches('ACM1234567890SG', $place))->toBeFalse()
+        ->and(TrackingCode::matches('place_p1', $place))->toBeTrue()
+        // A tracking number may also sit directly on the subject.
+        ->and(TrackingCode::matches('TN-FLAT', (object) ['uuid' => 'u', 'public_id' => '', 'tracking_number' => 'TN-FLAT']))->toBeTrue()
+        ->and(TrackingCode::matches('TN-FLAT', (object) ['uuid' => 'u', 'public_id' => null]))->toBeFalse();
+});
+
+test('the tracking page path itself is never read as a tracking number', function () {
+    expect(TrackingCode::parse('https://console.example/~/track-order?r=order_o1'))->toMatchArray([
+        'tracking_number' => null,
+        'public_id'       => 'order_o1',
+    ])
+        ->and(TrackingCode::parse('https://console.example/~/track-order?order=TN1&v=1'))->toMatchArray([
+            'tracking_number' => 'TN1',
+            'version'         => 1,
+        ]);
+});
+
+test('tracking page links name the company page when its settings send links there', function () {
+    // Page links are built by Utils::consoleUrl(), which needs app()->environment(). The
+    // bare container this suite runs on has no such method, so swap in one that does.
+    $previousContainer = Illuminate\Container\Container::getInstance();
+    $container         = new class extends Illuminate\Container\Container {
+        public function environment(...$environments)
+        {
+            return in_array('testing', $environments, true) || $environments === [] ? 'testing' : false;
+        }
+    };
+    $container->instance('config', new Illuminate\Config\Repository([
+        'fleetbase' => ['console' => ['host' => 'console.fleetbase.test', 'subdomain' => null, 'secure' => true]],
+    ]));
+    Illuminate\Container\Container::setInstance($container);
+
+    $container->instance(Fleetbase\FleetOps\Support\TrackingPage\TrackingResolver::class, new class extends Fleetbase\FleetOps\Support\TrackingPage\TrackingResolver {
+        public function linkSlugFor(string $companyUuid): ?string
+        {
+            if ($companyUuid === 'broken') {
+                throw new RuntimeException('settings unavailable');
+            }
+
+            return $companyUuid === 'co-1' ? 'northwind' : null;
+        }
+    });
+
+    try {
+        expect(TrackingCode::pageUrl('NOR1', 'co-1'))->toEndWith('/~/t/northwind/NOR1')
+            ->and(TrackingCode::pageUrl('NOR1', 'co-2'))->toEndWith('/~/track/NOR1')
+            ->and(TrackingCode::pageUrl('NOR1', 'broken'))->toEndWith('/~/track/NOR1')
+            ->and(TrackingCode::pageUrl('NOR1'))->toEndWith('/~/track/NOR1')
+            ->and(TrackingCode::pageUrl('A B/1'))->toBe('https://console.fleetbase.test/~/track/A%20B%2F1')
+            // Notifications pass a nullable number; without one the link opens the page itself.
+            ->and(TrackingCode::pageUrl(null))->toBe('https://console.fleetbase.test/~/track')
+            ->and(TrackingCode::pageUrl('', 'co-1'))->toEndWith('/~/t/northwind');
+    } finally {
+        Illuminate\Container\Container::setInstance($previousContainer);
+    }
+});

package/server/tests/Unit/Support/TrackingPage/TrackingAccessTest.php

@@ -0,0 +1,200 @@
+<?php
+
+use Fleetbase\FleetOps\Models\Contact;
+use Fleetbase\FleetOps\Models\TrackingSession;
+use Fleetbase\FleetOps\Models\TrackingSessionGrant;
+use Fleetbase\FleetOps\Support\TrackingPage\TrackingAccess;
+use Fleetbase\FleetOps\Support\TrackingScope;
+use Fleetbase\Models\VerificationCode;
+use Fleetbase\Scopes\ExpiryScope;
+use Fleetbase\Tests\Support\TrackingPageDatabase;
+use Illuminate\Cache\ArrayStore;
+use Illuminate\Cache\RateLimiter;
+use Illuminate\Cache\Repository;
+use Illuminate\Database\Eloquent\Model as EloquentModel;
+use Illuminate\Http\Request;
+use Illuminate\Support\Carbon;
+
+beforeEach(function () {
+    config(['app.key' => 'base64:tracking-test-key', 'fleetops.tracking.cookie_same_site' => 'lax', 'session.secure' => false, 'session.domain' => null]);
+});
+
+afterEach(function () {
+    Carbon::setTestNow();
+    EloquentModel::unsetConnectionResolver();
+    EloquentModel::unsetEventDispatcher();
+});
+
+/**
+ * The tracking page tables, with model events on so sessions, grants and codes get their
+ * uuids (a grant is found through its session's uuid) as they do in the app.
+ */
+function trackingAccessDatabase(): void
+{
+    TrackingPageDatabase::boot();
+    EloquentModel::setEventDispatcher(new Illuminate\Events\Dispatcher());
+    app()->instance('responsecache', new class {
+        public function __call($method, $arguments)
+        {
+            return null;
+        }
+    });
+}
+
+function trackingAccess(): TrackingAccess
+{
+    return new TrackingAccess(new RateLimiter(new Repository(new ArrayStore())));
+}
+
+function trackingScope(string $customer = 'contact-1'): TrackingScope
+{
+    return new TrackingScope('order-1', Contact::class, $customer);
+}
+
+function trackingRequest(array $cookies = [], string $ip = '203.0.113.7'): Request
+{
+    return Request::create('/public/track/NOR1', 'GET', [], $cookies, [], ['REMOTE_ADDR' => $ip, 'HTTP_USER_AGENT' => 'PestBrowser']);
+}
+
+test('lookups, code checks and reports are limited per address', function () {
+    $access  = trackingAccess();
+    $request = trackingRequest();
+
+    foreach (range(1, TrackingAccess::LOOKUPS_PER_IP) as $attempt) {
+        expect($access->allowLookup($request))->toBeTrue();
+    }
+
+    expect($access->allowLookup($request))->toBeFalse()
+        ->and($access->allowLookup(trackingRequest([], '198.51.100.1')))->toBeTrue();
+
+    foreach (range(1, TrackingAccess::VERIFIES_PER_IP) as $attempt) {
+        $access->allowVerify($request);
+    }
+    expect($access->allowVerify($request))->toBeFalse();
+
+    foreach (range(1, TrackingAccess::REPORTS_PER_HOUR) as $attempt) {
+        expect($access->allowReport($request, 'order-1'))->toBeTrue();
+    }
+    expect($access->allowReport($request, 'order-1'))->toBeFalse()
+        ->and($access->allowReport($request, 'order-2'))->toBeTrue();
+});
+
+test('sending codes is limited by cooldown, per scope and per address', function () {
+    $access  = trackingAccess();
+    $request = trackingRequest();
+
+    expect($access->claimSend(trackingScope(), $request))->toBe(['status' => TrackingAccess::SEND_SENT, 'retry_after' => TrackingAccess::RESEND_SECONDS])
+        ->and($access->claimSend(trackingScope(), $request)['status'])->toBe(TrackingAccess::SEND_COOLDOWN);
+
+    // Three sends per scope in the window, even after each cooldown.
+    $limiter = new RateLimiter(new Repository(new ArrayStore()));
+    $access  = new TrackingAccess($limiter);
+    foreach (range(1, TrackingAccess::SENDS_PER_SCOPE) as $send) {
+        $limiter->clear('trk-resend:' . trackingScope()->key());
+        expect($access->claimSend(trackingScope(), trackingRequest([], '198.51.100.' . $send))['status'])->toBe(TrackingAccess::SEND_SENT);
+    }
+    $limiter->clear('trk-resend:' . trackingScope()->key());
+    expect($access->claimSend(trackingScope(), $request)['status'])->toBe(TrackingAccess::SEND_LIMITED);
+
+    // Five sends per address across scopes.
+    $access = trackingAccess();
+    foreach (range(1, TrackingAccess::SENDS_PER_IP) as $send) {
+        $access->claimSend(trackingScope('contact-' . $send), $request);
+    }
+    expect($access->claimSend(trackingScope('contact-9'), $request)['status'])->toBe(TrackingAccess::SEND_LIMITED);
+});
+
+test('codes are issued hashed, checked, and pause the scope after three wrong ones', function () {
+    trackingAccessDatabase();
+    $access = trackingAccess();
+    $scope  = trackingScope();
+
+    $first  = $access->issueCode($scope, null, 'sms');
+    $second = $access->issueCode($scope, null, 'email');
+
+    // Codes soft delete, like every Fleetbase model: a voided or used code is trashed, and
+    // the code lookups (which only lift the expiry scope) never see it again.
+    expect(VerificationCode::withoutGlobalScope(ExpiryScope::class)->count())->toBe(1)
+        ->and(VerificationCode::onlyTrashed()->withoutGlobalScope(ExpiryScope::class)->value('meta')['channel'] ?? null)->toBe('sms')
+        ->and($second->plainCode)->toMatch('/^\d{6}$/')
+        ->and($second->code)->not->toBe($second->plainCode)
+        ->and($second->getMeta('scope'))->toBe($scope->key())
+        ->and($second->getMeta('channel'))->toBe('email')
+        ->and($first->plainCode)->not->toBeNull();
+
+    $wrong = $second->plainCode === '111111' ? '222222' : '111111';
+    expect($access->checkCode($scope, $wrong))->toBe(['status' => VerificationCode::CHECK_INVALID, 'attempts_left' => 2])
+        ->and($access->pausedFor($scope))->toBe(0);
+
+    // A used code stays on the table for the ledger, marked used, and never verifies again.
+    expect($access->checkCode($scope, $second->plainCode))->toBe(['status' => VerificationCode::CHECK_VALID, 'channel' => 'email'])
+        ->and(VerificationCode::withoutGlobalScope(ExpiryScope::class)->count())->toBe(1)
+        ->and(VerificationCode::withoutGlobalScope(ExpiryScope::class)->value('status'))->toBe(VerificationCode::STATUS_USED)
+        ->and($access->checkCode($scope, $second->plainCode))->toBe(['status' => VerificationCode::CHECK_EXPIRED]);
+
+    $third = $access->issueCode($scope, null, 'sms');
+    $wrong = $third->plainCode === '111111' ? '222222' : '111111';
+    $access->checkCode($scope, $wrong);
+    $access->checkCode($scope, $wrong);
+    expect($access->checkCode($scope, $wrong))->toBe(['status' => VerificationCode::CHECK_LOCKED, 'attempts_left' => 0])
+        ->and($access->pausedFor($scope))->toBeGreaterThan(0)
+        ->and($access->claimSend($scope, trackingRequest())['status'])->toBe(TrackingAccess::SEND_PAUSED);
+});
+
+test('a correct code gives the device a session and a grant for that customer only', function () {
+    trackingAccessDatabase();
+    Carbon::setTestNow(Carbon::parse('2026-10-08 09:00:00'));
+    $access = trackingAccess();
+    $scope  = trackingScope();
+
+    expect($access->session(trackingRequest()))->toBeNull()
+        ->and($access->session(trackingRequest([TrackingAccess::COOKIE => 'short'])))->toBeNull()
+        ->and($access->hasGrant(trackingRequest(), null))->toBeFalse();
+
+    $cookie = $access->grant(trackingRequest(), $scope, 'sms', 24);
+    $token  = $cookie->getValue();
+    $device = trackingRequest([TrackingAccess::COOKIE => $token]);
+
+    expect($cookie->getName())->toBe(TrackingAccess::COOKIE)
+        ->and($cookie->isHttpOnly())->toBeTrue()
+        ->and($cookie->getSameSite())->toBe('lax')
+        ->and(TrackingSession::query()->value('token_hash'))->toBe(hash('sha256', $token))
+        ->and(TrackingSession::query()->first()->grants()->count())->toBe(1)
+        ->and($access->hasGrant($device, $scope))->toBeTrue()
+        ->and($access->hasGrant($device, trackingScope('contact-2')))->toBeFalse()
+        ->and($access->grantExpiresAt($device, $scope))->toBe('2026-10-09T09:00:00.000000Z')
+        ->and($access->grantExpiresAt(trackingRequest(), $scope))->toBeNull();
+
+    // A second customer on the same device; a longer session extends the cookie, a shorter one doesn't.
+    expect($access->grant($device, trackingScope('contact-2'), 'email', 12))->toBeNull()
+        ->and($access->grant($device, trackingScope('contact-2'), 'email', 48)?->getValue())->toBe($token)
+        ->and(TrackingSessionGrant::query()->count())->toBe(2);
+
+    // Signing out of one delivery keeps the others.
+    expect($access->revoke($device, $scope))->toBeNull()
+        ->and($access->hasGrant($device, $scope))->toBeFalse()
+        ->and($access->hasGrant($device, trackingScope('contact-2')))->toBeTrue();
+
+    $expired = $access->revoke($device);
+    expect($expired->getValue())->toBe('')
+        ->and($expired->getExpiresTime())->toBe(1)
+        ->and($access->session($device))->toBeNull()
+        ->and($access->revoke($device)->getExpiresTime())->toBe(1);
+
+    // Expired sessions don't count.
+    $fresh = $access->grant(trackingRequest(), $scope, 'sms', 1);
+    Carbon::setTestNow(Carbon::parse('2026-10-08 11:00:00'));
+    expect($access->session(trackingRequest([TrackingAccess::COOKIE => $fresh->getValue()])))->toBeNull();
+});
+
+test('the session cookie follows the same-site setting', function () {
+    $access = trackingAccess();
+
+    config(['fleetops.tracking.cookie_same_site' => 'none']);
+    $none = $access->cookie('value', 60);
+    expect($none->getSameSite())->toBe('none')->and($none->isSecure())->toBeTrue();
+
+    config(['fleetops.tracking.cookie_same_site' => 'bogus', 'session.secure' => true]);
+    $fallback = $access->cookie('value', 60);
+    expect($fallback->getSameSite())->toBe('lax')->and($fallback->isSecure())->toBeTrue();
+});