api/services/nginx/app/classes/auth/scope_registry.php

<?php

namespace classes\auth;

/**
 * Scope registry: the source of truth for API key scopes and
 * role → scope defaults.
 *
 * This class is the canonical implementation that the parallel
 * `app\auth\Scope` stub (introduced by TRU-149 / branch
 * feat/TRU-149-route-scopes) will be replaced with once
 * `feat/api-key-foundation` is merged. Until then the two can
 * coexist; the middleware in `scope_middleware.php` continues
 * to use the legacy stub.
 *
 * Scopes follow a "resource:action" pattern (e.g. `booking:read`).
 * Two wildcard forms are recognised:
 *   - `*`                 — matches every scope.
 *   - `resource:*`        — matches every action on a resource.
 *
 * Role defaults:
 *   - superuser: every scope (via "*" wildcard).
 *   - admin:     customer:*, booking:*, subuser:*, invoice:*
 *   - customer:  customer:read, booking:read, invoice:read
 *   - subuser:   booking:read, booking:write
 *
 * The "self" / "assigned" qualifiers from the spec are *enforcement
 * layer* concerns, not scope concerns — they live in the resolver
 * that maps an authenticated principal to a customer/subuser record.
 * Scopes only encode "can the caller read bookings at all", not
 * "which bookings".
 */
final class scope_registry
{
    // --- Customer resource ---
    public const CUSTOMER_READ  = 'customer:read';
    public const CUSTOMER_WRITE = 'customer:write';

    // --- Booking resource ---
    public const BOOKING_READ  = 'booking:read';
    public const BOOKING_WRITE = 'booking:write';

    // --- Subuser resource ---
    public const SUBUSER_READ  = 'subuser:read';
    public const SUBUSER_WRITE = 'subuser:write';

    // --- Invoice resource ---
    public const INVOICE_READ  = 'invoice:read';
    public const INVOICE_WRITE = 'invoice:write';

    // --- Superuser / admin resource ---
    public const SUPERUSER_READ  = 'superuser:read';
    public const SUPERUSER_WRITE = 'superuser:write';

    /**
     * Canonical list of every concrete scope (no wildcards).
     *
     * @return array<int, string>
     */
    public static function all(): array
    {
        return [
            self::CUSTOMER_READ, self::CUSTOMER_WRITE,
            self::BOOKING_READ, self::BOOKING_WRITE,
            self::SUBUSER_READ, self::SUBUSER_WRITE,
            self::INVOICE_READ, self::INVOICE_WRITE,
            self::SUPERUSER_READ, self::SUPERUSER_WRITE,
        ];
    }

    /**
     * Return the default scope set carried by a role. Wildcards are
     * returned as-is; resolve them with `expand()` before checking
     * membership if you need a flat list.
     *
     * @return array<int, string>
     */
    public static function scopesForRole(string $role): array
    {
        switch (strtolower(trim($role))) {
            case 'superuser':
                return ['*'];
            case 'admin':
                return [
                    'customer:*',
                    'booking:*',
                    'subuser:*',
                    'invoice:*',
                ];
            case 'customer':
                return [
                    self::CUSTOMER_READ,
                    self::BOOKING_READ,
                    self::INVOICE_READ,
                ];
            case 'subuser':
                return [
                    self::BOOKING_READ,
                    self::BOOKING_WRITE,
                ];
            default:
                return [];
        }
    }

    /**
     * Does the granted scope (or wildcard) match the required scope?
     *
     *   - "*" matches anything.
     *   - "customer:*" matches "customer:read" and "customer:write".
     *   - "customer:read" matches itself exactly.
     *
     * @param array<int, string> $granted
     */
    public static function hasScope(array $granted, string $required): bool
    {
        $required = trim($required);
        if ($required === '') {
            return false;
        }
        foreach ($granted as $candidate) {
            if (!is_string($candidate)) {
                continue;
            }
            if (self::matches($candidate, $required)) {
                return true;
            }
        }
        return false;
    }

    /**
     * Expand a list of scopes (which may include wildcards) into the
     * full set of concrete scopes they grant. Useful for showing a
     * user what their key can do, or for caching decisions.
     *
     * The wildcard "*" expands to the full `all()` set. A wildcard
     * like "customer:*" expands to every concrete scope starting with
     * "customer:". Duplicate entries are removed.
     *
     * @param array<int, string> $scopes
     * @return array<int, string>
     */
    public static function expand(array $scopes): array
    {
        $concrete = self::all();
        $expanded = [];

        foreach ($scopes as $scope) {
            if (!is_string($scope)) {
                continue;
            }
            $scope = trim($scope);
            if ($scope === '') {
                continue;
            }
            if ($scope === '*') {
                $expanded = array_merge($expanded, $concrete);
                continue;
            }
            if (str_ends_with($scope, ':*')) {
                $prefix = substr($scope, 0, -2) . ':';
                foreach ($concrete as $candidate) {
                    if (str_starts_with($candidate, $prefix)) {
                        $expanded[] = $candidate;
                    }
                }
                continue;
            }
            // Already concrete — pass through if it looks canonical.
            if (in_array($scope, $concrete, true)) {
                $expanded[] = $scope;
            }
        }

        return array_values(array_unique($expanded));
    }

    /**
     * Internal wildcard matcher — public for testing.
     */
    public static function matches(string $granted, string $required): bool
    {
        $granted = trim($granted);
        $required = trim($required);
        if ($granted === '' || $required === '') {
            return false;
        }
        if ($granted === '*') {
            return true;
        }
        if (str_ends_with($granted, ':*')) {
            $prefix = substr($granted, 0, -2);
            return str_starts_with($required, $prefix . ':');
        }
        return $granted === $required;
    }

    /**
     * Validate a scope string. Returns true iff the value is either
     * a canonical concrete scope, "*", or a "<resource>:*" wildcard
     * for a known resource.
     */
    public static function isValid(string $scope): bool
    {
        $scope = trim($scope);
        if ($scope === '' || $scope === '*') {
            return $scope !== '';
        }
        if (str_ends_with($scope, ':*')) {
            $prefix = substr($scope, 0, -2);
            foreach (self::all() as $concrete) {
                if (str_starts_with($concrete, $prefix . ':')) {
                    return true;
                }
            }
            return false;
        }
        return in_array($scope, self::all(), true);
    }
}