@fleetbase/fleetops-engine 0.6.71 → 0.6.72

package/server/src/Support/TrackingCode.php

@@ -0,0 +1,242 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support;
+
+use Illuminate\Support\Str;
+
+/**
+ * The content printed into a tracking number's QR code and barcode, and the parser that
+ * turns any scanned value back into identifiers.
+ *
+ * QR (v1) is a URL, so a phone camera opens the customer tracking page while scanners
+ * and the navigator app read the parameters:
+ *
+ *     https://<console host>/~/track-order?order=<tracking number>&r=<owner public_id>&v=1
+ *
+ * Only the tracking number (printed on the label in plain text) and the owner's public
+ * id go in: no uuids, no addresses, no names, no company. The owner's type is its
+ * public_id prefix (order_, waypoint_, entity_, place_), so it is not repeated. Nothing
+ * is signed: a label can be photocopied whatever it carries, so authorization belongs
+ * to the endpoint that acts on a scan, not to the code.
+ *
+ * The linear barcode (Code 128) carries the bare tracking number, matching the text
+ * printed beneath it, because warehouse handhelds type what they scan into a field.
+ *
+ * Codes already on parcels encode the owner's bare uuid, and parse() keeps accepting
+ * them, alongside a bare tracking number or a bare public_id.
+ */
+class TrackingCode
+{
+    public const VERSION = 1;
+
+    /**
+     * Where a phone camera lands. The public tracking page is being rebuilt; when its
+     * route changes, change these two and nothing else. parse() never depends on the
+     * host or the path, since printed labels outlive both.
+     *
+     * `~/` is the console's public route prefix: it renders the page whether or not the
+     * visitor is signed in. A bare `/track-order` falls into the console's own routes, so
+     * a signed-in user landed on an empty console page instead of the tracking page.
+     */
+    public const PATH           = '~/track-order';
+    public const TRACKING_PARAM = 'order';
+
+    /**
+     * The tracking page link for emails, notifications and the API: the company's own page
+     * (`~/t/{slug}/{number}`) when its settings send links there, otherwise the shared page
+     * (`~/track/{number}`). QR codes keep {@see PATH}, which labels already printed carry.
+     * Without a tracking number it links the page itself, where the number can be entered.
+     */
+    public static function pageUrl(?string $trackingNumber, ?string $companyUuid = null): string
+    {
+        try {
+            $slug = $companyUuid ? app(TrackingPage\TrackingResolver::class)->linkSlugFor($companyUuid) : null;
+        } catch (\Throwable) {
+            $slug = null;
+        }
+
+        $base = $slug ? '~/t/' . rawurlencode($slug) : '~/track';
+
+        return Utils::consoleUrl(filled($trackingNumber) ? $base . '/' . rawurlencode($trackingNumber) : $base, []);
+    }
+
+    /**
+     * The QR content for a tracking number.
+     */
+    public static function qrContent(string $trackingNumber, ?string $ownerPublicId = null): string
+    {
+        $query = [static::TRACKING_PARAM => $trackingNumber];
+
+        if (!empty($ownerPublicId)) {
+            $query['r'] = $ownerPublicId;
+        }
+
+        $query['v'] = static::VERSION;
+
+        return static::consoleBaseUrl() . '/' . static::PATH . '?' . http_build_query($query);
+    }
+
+    /**
+     * The console origin, from the same config Utils::consoleUrl() reads. It does not
+     * call consoleUrl() because that infers http/https from the app environment: a code
+     * printed on a parcel should not change scheme with where it was generated, so it
+     * is https unless the console is explicitly configured otherwise.
+     */
+    protected static function consoleBaseUrl(): string
+    {
+        $host = rtrim((string) config('fleetbase.console.host', ''), '/');
+
+        if (Str::startsWith($host, 'http')) {
+            return $host;
+        }
+
+        $subdomain = config('fleetbase.console.subdomain');
+        $scheme    = config('fleetbase.console.secure', true) ? 'https://' : 'http://';
+
+        return $scheme . ($subdomain ? $subdomain . '.' : '') . $host;
+    }
+
+    /**
+     * The linear barcode content for a tracking number.
+     */
+    public static function barcodeContent(string $trackingNumber): string
+    {
+        return $trackingNumber;
+    }
+
+    /**
+     * Break a scanned value into the identifiers it carries.
+     *
+     * - `uuid`: a legacy code, the owner's uuid.
+     * - `tracking_number` and `public_id`: from a URL code.
+     * - `reference`: a bare value that is either a tracking number (the barcode, or one
+     *   typed by hand) or a public_id. Consumers try both.
+     *
+     * @return array{uuid: ?string, tracking_number: ?string, public_id: ?string, reference: ?string, version: ?int}
+     */
+    public static function parse(?string $code): array
+    {
+        $parsed = [
+            'uuid'            => null,
+            'tracking_number' => null,
+            'public_id'       => null,
+            'reference'       => null,
+            'version'         => null,
+        ];
+
+        $code = trim((string) $code);
+        if ($code === '') {
+            return $parsed;
+        }
+
+        if (preg_match('#^https?://#i', $code)) {
+            return array_merge($parsed, static::parseUrl($code));
+        }
+
+        if (Str::isUuid($code)) {
+            $parsed['uuid'] = $code;
+
+            return $parsed;
+        }
+
+        $parsed['reference'] = $code;
+
+        return $parsed;
+    }
+
+    /**
+     * Whether a scanned value identifies the given subject (an order, waypoint, entity or
+     * place). The value comes straight from a request, so anything but a string, such as
+     * a scanner library's whole result object, matches nothing.
+     */
+    public static function matches($code, $subject): bool
+    {
+        $subjectUuid = data_get($subject, 'uuid');
+        if (!is_string($code) || !$subject || empty($subjectUuid)) {
+            return false;
+        }
+
+        // Labels printed before v1 encode the subject's bare uuid; compare it exactly, as
+        // scans always have been.
+        if (trim($code) === $subjectUuid) {
+            return true;
+        }
+
+        $parsed = static::parse($code);
+
+        if ($parsed['uuid']) {
+            return false;
+        }
+
+        $publicId       = data_get($subject, 'public_id');
+        $trackingNumber = static::subjectTrackingNumber($subject);
+
+        if ($parsed['reference']) {
+            return static::sameTrackingNumber($parsed['reference'], $trackingNumber) || static::samePublicId($parsed['reference'], $publicId);
+        }
+
+        // A url code names its owner by public id, and that decides: an owner can hold more
+        // than one tracking number (the API issues extra ones), so the number is compared
+        // only when the code names no owner.
+        if ($parsed['public_id']) {
+            return static::samePublicId($parsed['public_id'], $publicId);
+        }
+
+        return $parsed['tracking_number'] !== null && static::sameTrackingNumber($parsed['tracking_number'], $trackingNumber);
+    }
+
+    /**
+     * @return array{tracking_number: ?string, public_id: ?string, version: ?int}
+     */
+    protected static function parseUrl(string $url): array
+    {
+        $parts = parse_url($url);
+        $query = [];
+        parse_str(is_array($parts) ? ($parts['query'] ?? '') : '', $query);
+
+        $trackingNumber = static::stringParam($query, static::TRACKING_PARAM) ?? static::stringParam($query, 'tn');
+
+        // A future route may carry the tracking number in the path (/track/<number>). Only
+        // a path of two or more segments can, and the tracking page's own path
+        // (/track-order, /~/track-order) is never mistaken for one.
+        if ($trackingNumber === null && is_array($parts) && isset($parts['path'])) {
+            $segments = array_values(array_filter(explode('/', $parts['path']), fn ($segment) => $segment !== ''));
+            if (count($segments) >= 2 && end($segments) !== basename(static::PATH)) {
+                $trackingNumber = rawurldecode(end($segments));
+            }
+        }
+
+        $version = static::stringParam($query, 'v');
+
+        return [
+            'tracking_number' => $trackingNumber,
+            'public_id'       => static::stringParam($query, 'r'),
+            'version'         => $version !== null && ctype_digit($version) ? (int) $version : null,
+        ];
+    }
+
+    protected static function stringParam(array $query, string $key): ?string
+    {
+        $value = $query[$key] ?? null;
+
+        return is_string($value) && trim($value) !== '' ? trim($value) : null;
+    }
+
+    protected static function subjectTrackingNumber($subject): ?string
+    {
+        $trackingNumber = data_get($subject, 'trackingNumber.tracking_number') ?? data_get($subject, 'tracking_number');
+
+        return is_string($trackingNumber) && $trackingNumber !== '' ? $trackingNumber : null;
+    }
+
+    protected static function sameTrackingNumber(string $scanned, ?string $trackingNumber): bool
+    {
+        // The label prints the number upper-cased and handhelds may not preserve case.
+        return $trackingNumber !== null && strcasecmp($scanned, $trackingNumber) === 0;
+    }
+
+    protected static function samePublicId(string $scanned, $publicId): bool
+    {
+        return is_string($publicId) && $publicId !== '' && $scanned === $publicId;
+    }
+}

package/server/src/Support/TrackingPage/TrackingAccess.php

@@ -0,0 +1,356 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\TrackingPage;
+
+use Fleetbase\FleetOps\Models\TrackingSession;
+use Fleetbase\FleetOps\Models\TrackingSessionGrant;
+use Fleetbase\FleetOps\Support\TrackingScope;
+use Fleetbase\Models\VerificationCode;
+use Fleetbase\Scopes\ExpiryScope;
+use Illuminate\Cache\RateLimiter;
+use Illuminate\Http\Request;
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Str;
+use Symfony\Component\HttpFoundation\Cookie;
+
+/**
+ * One-time codes and device sessions for the public tracking page.
+ *
+ * A code is sent to a scope's recipient and proves the visitor is that customer. A correct
+ * code gives the device a grant for that one customer within that one order. Codes are
+ * stored hashed (VerificationCode::issue()), three wrong codes pause the scope for every
+ * device, and sends are limited per scope and per address.
+ */
+class TrackingAccess
+{
+    public const COOKIE           = 'fb_track';
+    public const CODE_PURPOSE     = 'fleetops_tracking_access';
+    public const CODE_MINUTES     = 10;
+    public const MAX_ATTEMPTS     = 3;
+    public const PAUSE_SECONDS    = 300;
+    public const RESEND_SECONDS   = 30;
+    public const SENDS_PER_SCOPE  = 3;
+    public const SENDS_PER_IP     = 5;
+    public const SEND_WINDOW      = 900;
+    public const LOOKUPS_PER_IP   = 30;
+    public const LOOKUP_WINDOW    = 60;
+    public const VERIFIES_PER_IP  = 10;
+    public const REPORTS_PER_HOUR = 3;
+
+    public const SEND_SENT     = 'sent';
+    public const SEND_COOLDOWN = 'cooldown';
+    public const SEND_LIMITED  = 'limited';
+    public const SEND_PAUSED   = 'paused';
+
+    public function __construct(protected ?RateLimiter $limiter = null)
+    {
+    }
+
+    /**
+     * Whether this address may make another lookup, counting it.
+     */
+    public function allowLookup(Request $request): bool
+    {
+        return $this->attempt('trk-lookup:' . $request->ip(), self::LOOKUPS_PER_IP, self::LOOKUP_WINDOW);
+    }
+
+    /**
+     * Whether this address may check another code, counting it.
+     */
+    public function allowVerify(Request $request): bool
+    {
+        return $this->attempt('trk-verify:' . $request->ip(), self::VERIFIES_PER_IP, self::LOOKUP_WINDOW);
+    }
+
+    /**
+     * Whether this address may report another problem with this order, counting it.
+     */
+    public function allowReport(Request $request, string $orderUuid): bool
+    {
+        return $this->attempt('trk-report:' . $orderUuid . ':' . $request->ip(), self::REPORTS_PER_HOUR, 3600);
+    }
+
+    /**
+     * Whether a scope's codes are paused after too many wrong ones, and for how long.
+     */
+    public function pausedFor(TrackingScope $scope): int
+    {
+        $key = $this->pauseKey($scope);
+
+        return $this->limiter()->tooManyAttempts($key, 1) ? max(1, $this->limiter()->availableIn($key)) : 0;
+    }
+
+    /**
+     * Check the limits for sending a code and, when they allow it, count the send.
+     *
+     * @return array{status: string, retry_after: int}
+     */
+    public function claimSend(TrackingScope $scope, Request $request): array
+    {
+        if ($paused = $this->pausedFor($scope)) {
+            return ['status' => self::SEND_PAUSED, 'retry_after' => $paused];
+        }
+
+        $cooldown = 'trk-resend:' . $scope->key();
+        if ($this->limiter()->tooManyAttempts($cooldown, 1)) {
+            return ['status' => self::SEND_COOLDOWN, 'retry_after' => max(1, $this->limiter()->availableIn($cooldown))];
+        }
+
+        foreach (['trk-send-scope:' . $scope->key() => self::SENDS_PER_SCOPE, 'trk-send-ip:' . $request->ip() => self::SENDS_PER_IP] as $key => $max) {
+            if ($this->limiter()->tooManyAttempts($key, $max)) {
+                return ['status' => self::SEND_LIMITED, 'retry_after' => max(1, $this->limiter()->availableIn($key))];
+            }
+        }
+
+        $this->limiter()->hit($cooldown, self::RESEND_SECONDS);
+        $this->limiter()->hit('trk-send-scope:' . $scope->key(), self::SEND_WINDOW);
+        $this->limiter()->hit('trk-send-ip:' . $request->ip(), self::SEND_WINDOW);
+
+        return ['status' => self::SEND_SENT, 'retry_after' => self::RESEND_SECONDS];
+    }
+
+    /**
+     * A new code for a scope, voiding the scope's earlier unused ones. The plain code is on `plainCode`.
+     */
+    public function issueCode(TrackingScope $scope, mixed $recipient, string $channel): VerificationCode
+    {
+        $this->voidCodes($scope);
+
+        return $this->createCode($recipient, [
+            'expireAfter' => Carbon::now()->addMinutes(self::CODE_MINUTES),
+            'meta'        => [
+                'scope'        => $scope->key(),
+                'channel'      => $channel,
+                'company_uuid' => $scope->company_uuid,
+            ],
+        ]);
+    }
+
+    /**
+     * Check a code for a scope.
+     *
+     * @return array{status: string, attempts_left?: int, channel?: string|null}
+     */
+    public function checkCode(TrackingScope $scope, string $code): array
+    {
+        $verificationCode = $this->latestCode($scope);
+        if (!$verificationCode) {
+            return ['status' => VerificationCode::CHECK_EXPIRED];
+        }
+
+        $result = $verificationCode->check($code, self::MAX_ATTEMPTS);
+        if ($result === VerificationCode::CHECK_VALID) {
+            $channel = $verificationCode->getMeta('channel');
+            $this->consumeCode($verificationCode);
+
+            return ['status' => $result, 'channel' => $channel];
+        }
+
+        if ($result === VerificationCode::CHECK_LOCKED) {
+            $this->limiter()->hit($this->pauseKey($scope), self::PAUSE_SECONDS);
+        }
+
+        return ['status' => $result, 'attempts_left' => $verificationCode->attemptsLeft(self::MAX_ATTEMPTS)];
+    }
+
+    /**
+     * The device session the request's cookie names, when it is live.
+     */
+    public function session(Request $request): ?TrackingSession
+    {
+        $token = $request->cookie(self::COOKIE);
+        if (!is_string($token) || strlen($token) < 32) {
+            return null;
+        }
+
+        $session = $this->findSession(hash('sha256', $token));
+        if (!$session || $session->revoked_at || ($session->expires_at && $session->expires_at->isPast())) {
+            return null;
+        }
+
+        return $session;
+    }
+
+    /**
+     * Whether the request's device holds a live grant for this scope.
+     */
+    public function hasGrant(Request $request, ?TrackingScope $scope): bool
+    {
+        if (!$scope) {
+            return false;
+        }
+
+        $session = $this->session($request);
+
+        return $session !== null && $this->findGrant($session, $scope) !== null;
+    }
+
+    /**
+     * When the device's grant for this scope ends.
+     */
+    public function grantExpiresAt(Request $request, TrackingScope $scope): ?string
+    {
+        $session = $this->session($request);
+        $grant   = $session ? $this->findGrant($session, $scope) : null;
+
+        return $grant?->expires_at?->toISOString();
+    }
+
+    /**
+     * Give the device a grant for a scope, starting a session when it has none.
+     *
+     * @return Cookie|null the cookie to set when a new session was started
+     */
+    public function grant(Request $request, TrackingScope $scope, ?string $channel, int $hours): ?Cookie
+    {
+        $expiresAt = Carbon::now()->addHours($hours);
+        $session   = $this->session($request);
+        $cookie    = null;
+
+        if (!$session) {
+            $token   = Str::random(40);
+            $session = $this->createSession([
+                'token_hash'   => hash('sha256', $token),
+                'ip'           => $request->ip(),
+                'user_agent'   => Str::limit((string) $request->userAgent(), 250, ''),
+                'last_seen_at' => Carbon::now(),
+                'expires_at'   => $expiresAt,
+            ]);
+            $cookie = $this->cookie($token, $hours * 60);
+        } elseif (!$session->expires_at || $session->expires_at->lt($expiresAt)) {
+            $this->saveSession($session, ['expires_at' => $expiresAt, 'last_seen_at' => Carbon::now()]);
+            $cookie = $this->cookie((string) $request->cookie(self::COOKIE), $hours * 60);
+        }
+
+        $this->saveGrant($session, $scope, $channel, $expiresAt);
+
+        return $cookie;
+    }
+
+    /**
+     * Sign the device out: of one scope, or of every scope when none is given.
+     *
+     * @return Cookie|null an expired cookie when the whole session ended
+     */
+    public function revoke(Request $request, ?TrackingScope $scope = null): ?Cookie
+    {
+        $session = $this->session($request);
+        if (!$session) {
+            return $this->cookie('', -1);
+        }
+
+        if ($scope) {
+            $this->deleteGrant($session, $scope);
+
+            return null;
+        }
+
+        $this->saveSession($session, ['revoked_at' => Carbon::now()]);
+
+        return $this->cookie('', -1);
+    }
+
+    public function cookie(string $value, int $minutes): Cookie
+    {
+        $sameSite = strtolower((string) config('fleetops.tracking.cookie_same_site', 'lax'));
+        $sameSite = in_array($sameSite, ['lax', 'strict', 'none'], true) ? $sameSite : 'lax';
+        $secure   = $sameSite === 'none' || (bool) config('session.secure', false);
+
+        return Cookie::create(self::COOKIE, $value, $minutes < 0 ? 1 : Carbon::now()->addMinutes($minutes)->getTimestamp(), '/', config('session.domain'), $secure, true, false, $sameSite);
+    }
+
+    protected function attempt(string $key, int $max, int $decay): bool
+    {
+        if ($this->limiter()->tooManyAttempts($key, $max)) {
+            return false;
+        }
+
+        $this->limiter()->hit($key, $decay);
+
+        return true;
+    }
+
+    protected function pauseKey(TrackingScope $scope): string
+    {
+        return 'trk-pause:' . $scope->key();
+    }
+
+    protected function limiter(): RateLimiter
+    {
+        return $this->limiter ??= app(RateLimiter::class);
+    }
+
+    protected function voidCodes(TrackingScope $scope): void
+    {
+        VerificationCode::withoutGlobalScope(ExpiryScope::class)->where('for', self::CODE_PURPOSE)->where('meta->scope', $scope->key())->delete();
+    }
+
+    protected function createCode(mixed $recipient, array $options): VerificationCode
+    {
+        return VerificationCode::issue($recipient, self::CODE_PURPOSE, $options);
+    }
+
+    /**
+     * The scope's newest code that has not been used. Read without the expiry scope so an
+     * expired code is reported as such rather than as missing; a used code stays on the
+     * table for the ledger but never verifies again.
+     */
+    protected function latestCode(TrackingScope $scope): ?VerificationCode
+    {
+        return VerificationCode::withoutGlobalScope(ExpiryScope::class)
+            ->where('for', self::CODE_PURPOSE)
+            ->where('meta->scope', $scope->key())
+            ->where(function ($query) {
+                $query->whereNull('status')->orWhere('status', '!=', VerificationCode::STATUS_USED);
+            })
+            ->latest()
+            ->first();
+    }
+
+    protected function consumeCode(VerificationCode $verificationCode): void
+    {
+        $verificationCode->consume();
+    }
+
+    protected function findSession(string $tokenHash): ?TrackingSession
+    {
+        return TrackingSession::where('token_hash', $tokenHash)->first();
+    }
+
+    protected function createSession(array $attributes): TrackingSession
+    {
+        return TrackingSession::create($attributes);
+    }
+
+    protected function saveSession(TrackingSession $session, array $attributes): void
+    {
+        $session->forceFill($attributes)->save();
+    }
+
+    protected function findGrant(TrackingSession $session, TrackingScope $scope): ?TrackingSessionGrant
+    {
+        return TrackingSessionGrant::where('tracking_session_uuid', $session->uuid)
+            ->where('order_uuid', $scope->order_uuid)
+            ->where('customer_type', $scope->customer_type)
+            ->where('customer_uuid', $scope->customer_uuid)
+            ->where('expires_at', '>', Carbon::now())
+            ->first();
+    }
+
+    protected function saveGrant(TrackingSession $session, TrackingScope $scope, ?string $channel, Carbon $expiresAt): void
+    {
+        TrackingSessionGrant::updateOrCreate(
+            ['tracking_session_uuid' => $session->uuid, 'order_uuid' => $scope->order_uuid, 'customer_type' => $scope->customer_type, 'customer_uuid' => $scope->customer_uuid],
+            ['company_uuid' => $scope->company_uuid, 'channel' => $channel, 'expires_at' => $expiresAt]
+        );
+    }
+
+    protected function deleteGrant(TrackingSession $session, TrackingScope $scope): void
+    {
+        TrackingSessionGrant::where('tracking_session_uuid', $session->uuid)
+            ->where('order_uuid', $scope->order_uuid)
+            ->where('customer_type', $scope->customer_type)
+            ->where('customer_uuid', $scope->customer_uuid)
+            ->delete();
+    }
+}