Auth: Token: IAP: Google Claim

Author: iamacarpet

src/AffordableMobiles/GServerlessSupportLaravel/Auth/Token/Claims/Google.php

@@ -0,0 +1,125 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AffordableMobiles\GServerlessSupportLaravel\Auth\Token\Claims;
+
+use ArrayAccess;
+use Illuminate\Support\Arr;
+
+/**
+ * Represents the structured 'google' claim from a validated IAP JWT.
+ *
+ * This provides type-safe, convenient access to device and access level
+ * information required for Endpoint Verification checks. It validates the
+ * incoming claim structure upon instantiation and implements ArrayAccess
+ * for full backward compatibility without redundant data storage.
+ */
+class Google implements \ArrayAccess
+{
+    /**
+     * The unique identifier for the user's device.
+     *
+     * This is populated from the 'device_id' field in the JWT claim.
+     */
+    public readonly ?string $deviceId;
+
+    /**
+     * A list of access levels associated with the request.
+     *
+     * These correspond to the Endpoint Verification policies the
+     * user's device has satisfied.
+     *
+     * @var string[]
+     */
+    public readonly array $accessLevels;
+
+    /**
+     * @param array $claim the 'google' claim array from the decoded JWT
+     */
+    public function __construct(array $claim)
+    {
+        // Extract and assign the device_id and access_levels to readonly properties.
+        // The Arr::get helper provides a safe way to access array keys, with a
+        // default value if the key does not exist.
+        $this->deviceId     = Arr::get($claim, 'device_id');
+        $this->accessLevels = Arr::get($claim, 'access_levels', []);
+    }
+
+    /**
+     * Get the device ID from the claim.
+     */
+    public function getDeviceId(): ?string
+    {
+        return $this->deviceId;
+    }
+
+    /**
+     * Get the access levels from the claim.
+     */
+    public function getAccessLevels(): array
+    {
+        return $this->accessLevels;
+    }
+
+    /**
+     * Check if the claim contains a specific, required access level.
+     *
+     * @param string $requiredLevel the full name of the access level to check for
+     */
+    public function hasAccessLevel(string $requiredLevel): bool
+    {
+        return \in_array($requiredLevel, $this->accessLevels, true);
+    }
+
+    /**
+     * Determine if a claim key exists.
+     *
+     * @param mixed $offset
+     */
+    public function offsetExists($offset): bool
+    {
+        return \in_array($offset, ['device_id', 'access_levels'], true);
+    }
+
+    /**
+     * Get a claim value by key, emulating array access.
+     *
+     * @param mixed $offset
+     */
+    public function offsetGet($offset): mixed
+    {
+        return match ($offset) {
+            'device_id'     => $this->deviceId,
+            'access_levels' => $this->accessLevels,
+            default         => null,
+        };
+    }
+
+    /**
+     * Set a claim value (not supported).
+     *
+     * @param mixed $offset
+     * @param mixed $value
+     *
+     * @throws \LogicException
+     */
+    public function offsetSet($offset, $value): void
+    {
+        // This object is immutable; setting claims is not allowed.
+        throw new \LogicException('Cannot modify a Google Claim object.');
+    }
+
+    /**
+     * Unset a claim value (not supported).
+     *
+     * @param mixed $offset
+     *
+     * @throws \LogicException
+     */
+    public function offsetUnset($offset): void
+    {
+        // This object is immutable; unsetting claims is not allowed.
+        throw new \LogicException('Cannot modify a Google Claim object.');
+    }
+}

src/AffordableMobiles/GServerlessSupportLaravel/Auth/Token/IAP.php

@@ -6,6 +6,7 @@
 
 use AffordableMobiles\GServerlessSupportLaravel\Auth\Exception\InvalidTokenException;
 use AffordableMobiles\GServerlessSupportLaravel\Auth\Token\Type\JWT;
+use Illuminate\Support\Arr;
 
 class IAP
 {
@@ -27,20 +28,38 @@ class IAP
     ];
 
     /**
-     * Validate an IAP ID token.
+     * Validate an IAP ID token and check for a required access level.
      *
-     * @param string $iap_jwt           the JWT token to be validated
-     * @param string $expected_audience the expected audience of the provided JWT
+     * This method cryptographically verifies the JWT. On success, it returns the
+     * claims as an array, with the 'google' claim enriched into a `GoogleClaim` object.
      *
-     * @return array returns array containing "sub" and "email" if token is valid
+     * @param string      $iap_jwt               the JWT token to be validated
+     * @param string      $expected_audience     the expected audience of the provided JWT
+     * @param null|string $required_access_level the full name of the required Endpoint Verification access level
      *
-     * @throws InvalidTokenException if the token is invalid
+     * @return array the validated and enriched claims array
+     *
+     * @throws InvalidTokenException if the token is invalid or doesn't meet security requirements
      */
-    public static function validateToken($iap_jwt, $expected_audience)
+    public static function validateToken(string $iap_jwt, string $expected_audience, ?string $required_access_level = null): array
     {
-        $jwk_url = self::get_jwk_url();
+        // Perform base cryptographic validation and check standard claims.
+        $claims = JWT::validate($iap_jwt, $expected_audience, self::get_jwk_url(), self::JWT_SIG_ALG, self::JWT_ISSUERS);
+
+        // Enrich the 'google' claim into a structured object.
+        $googleClaim      = new Claims\Google(Arr::get($claims, 'google', []));
+        $claims['google'] = $googleClaim;
+
+        // If an access level is required, perform the Endpoint Verification check.
+        if ($required_access_level) {
+            if (!$googleClaim->hasAccessLevel($required_access_level)) {
+                throw new InvalidTokenException(
+                    'JWT is valid, but is missing the required access level for Endpoint Verification.'
+                );
+            }
+        }
 
-        return JWT::validate($iap_jwt, $expected_audience, $jwk_url, self::JWT_SIG_ALG, self::JWT_ISSUERS);
+        return $claims;
     }
 
     /**