fix token expiration type, tests and docs references.

fix invalidateAll hmac cli command.
implements CanAccessTokenExpire() and CanHmacTokenExpire() methods.
removes hasAccessTokenExpired() and hasHmacTokenExpired() methods.

Author: CosDiabos

docs/references/authentication/hmac.md

@@ -103,51 +103,52 @@ By default, the HMAC keys don't expire unless they meet the HMAC Keys lifetime e
 
 HMAC keys can be set to expire through the `generateHmacToken()` method. This takes the expiration date as the $expiresAt argument. It's also possible to update an existing HMAC key using `setHmacTokenExpirationById($HmacTokenID, $expiresAt)`
 
-`$expiresAt` Accepts DateTime string formatted as 'Y-m-d h:i:s' or [DateTime relative formats](https://www.php.net/manual/en/datetime.formats.php#datetime.formats.relative) unit symbols (1 day, 2 weeks, 6 months, 1 year) to be added to DateTime 'now'
+`$expiresAt` [Time](/libraries/time.html) object
 
 ```php
 // Expiration date = 2024-11-03 12:00:00
-$token = $this->user->generateHmacToken('foo', ['foo:bar'], '2024-11-03 12:00:00');
+$expiresAt = Time::parse('2024-11-03 12:00:00');
+$token = $this->user->generateHmacToken('foo', ['foo:bar'], $expiresAt);
 
 // Expiration date = 2024-11-15 00:00:00
-$token = $user->setHmacTokenExpirationById($token->id, '2024-11-15 00:00:00');
-
-// Or Expiration date = now() + 1 month + 15 days
-$token = $user->setHmacTokenExpirationById($token->id, '1 month 15 days');
+$expiresAt = Time::parse('2024-11-15 00:00:00');
+$token = $user->setHmacTokenExpirationById($token->id, $expiresAt);
+
+// Or Expiration date = 1 month + 15 days into the future
+$expiresAt = Time::now();
+$expiresAt = $expiresAt->addMonths(1);
+$expiresAt = $expiresAt->addDays(15);
+$token = $user->setHmacTokenExpirationById($token->id, $expiresAt);
 ```
 
 The following support methods are also available:
 
-`hasHmacTokenExpired(AccessToken $HmacToken)` - Checks if the given HMAC key has expired. Returns `true` if the HMAC key has expired, `false` if not, and `null` if the expire date is null.
+`hasHmacTokenExpired(AccessToken $HmacToken)` - Checks if the HMAC key has expired. Returns `true` if the HMAC key has expired, `false` if not, and `null` if the expire date is null.
 
 ```php
-$token = $this->user->generateAccessToken('foo', ['foo:bar'], '2024-11-03 12:00:00');
+$expiresAt = Time::parse('2024-11-03 12:00:00');
+$token = $this->user->generateHmacToken('foo', ['foo:bar'], $expiresAt);
 
 $this->user->hasHmacTokenExpired($token); // Returns true
 ```
 
-`getHmacTokenTimeToExpire(AccessToken $accessToken, string $format = "date" | "human")` - Checks if the given HMAC key has expired. Returns `true` if HMAC key has expired, `false` if not, and `null` if the expire date is not set.
+`canHmacTokenExpire(AccessToken $HmacToken)` - Checks if HMAC key has an expiration set. Returns `true` or `false` accordingly.
 
 ```php
-$token = $this->user->generateHmacToken('foo', ['foo:bar']);
-
-$this->user->getHmacTokenTimeToExpire($token, 'date'); // Returns null
-
-// Assuming current time is: 2024-11-04 20:00:00
-$token = $this->user->generateHmacToken('foo', ['foo:bar'], '2024-11-03 12:00:00');
+$expiresAt = Time::parse('2024-11-03 12:00:00');
 
-$this->user->getHmacTokenTimeToExpire($token, 'date'); // 2024-11-03 12:00:00
-$this->user->getHmacTokenTimeToExpire($token, 'human'); // 1 day ago
+$token = $this->user->generateHmacToken('foo', ['foo:bar'], $expiresAt);
+$this->user->canHmacTokenExpire($token); // Returns true
 
-$token = $this->user->generateHmacToken('foo', ['foo:bar'], '2026-01-06 12:00:00');
-$this->user->getHmacTokenTimeToExpire($token, 'human'); // in 1 year
+$token2 = $this->user->generateHmacToken('bar');
+$this->user->canHmacTokenExpire($token2); // Returns false
 ```
 
 You can also easily set all existing HMAC keys/tokens as expired with the `spark` command:
 ```
-php spark shield:hmac expireAll
+php spark shield:hmac invalidateAll
 ```
-**Careful!** This command 'expires' _all_ keys for _all_ users.
+**Careful!** This command invalidates _all_ keys for _all_ users.
 
 ## Retrieving HMAC Keys
 

docs/references/authentication/tokens.md

@@ -144,46 +144,50 @@ By default, the Access Tokens don't expire unless they meet the Access Token lif
 
 Access Tokens can be set to expire through the `generateAccessToken()` method. This takes the expiration date as the $expiresAt argument. It's also possible to update an existing HMAC key using `setAccessTokenById($HmacTokenID, $expiresAt)`
 
-`$expiresAt` Accepts DateTime string formatted as 'Y-m-d h:i:s' or [DateTime relative formats](https://www.php.net/manual/en/datetime.formats.php#datetime.formats.relative) unit symbols (1 day, 2 weeks, 6 months, 1 year) to be added to DateTime 'now'
+`$expiresAt` [Time](/libraries/time.html) object
 
 ```php
 // Expiration date = 2024-11-03 12:00:00
-$token = $this->user->generateAccessToken('foo', ['foo:bar'], '2024-11-03 12:00:00');
+$expiresAt = Time::parse('2024-11-03 12:00:00');
+$token = $this->user->generateAccessToken('foo', ['foo:bar'], $expiresAt);
 
 // Expiration date = 2024-11-15 00:00:00
-$user->setAccessTokenExpirationById($token->id, '2024-11-15 00:00:00');
+$expiresAt = Time::parse('2024-11-15 00:00:00');
+$user->setAccessTokenExpirationById($token->id, $expiresAt);
 
-// Or Expiration date = now() + 1 month + 15 days
-$user->setAccessTokenExpirationById($token->id, '1 month 15 days');
+// Or Expiration date = 1 month + 15 days into the future
+$expiresAt = Time::now();
+$expiresAt = $expiresAt->addMonths(1);
+$expiresAt = $expiresAt->addDays(15);
+
+$user->setAccessTokenExpirationById($token->id, $expiresAt);
 ```
 
 The following support methods are also available:
 
-`hasAccessTokenExpired(AccessToken $accessToken)` - Checks if the given Access Token has expired. Returns `true` if the Access Token has expired, `false` if not, and `null` if the expire date is not set.
+`hasAccessTokenExpired(AccessToken $accessToken)` - Checks if Access Token has expired. Returns `true` if the Access Token has expired, `false` if not, and `null` if the expire date is not set.
 
 ```php
-$token = $this->user->generateAccessToken('foo', ['foo:bar'], '2024-11-03 12:00:00');
+$expiresAt = Time::parse('2024-11-03 12:00:00');
+
+$token = $this->user->generateAccessToken('foo', ['foo:bar'], $expiresAt);
 
 $this->user->hasAccessTokenExpired($token); // Returns true
 ```
 
-`getAccessTokenTimeToExpire(AccessToken $accessToken, string $format = "date" | "human")` - Checks if the given Access Token has expired. Returns `true` if Access Token has expired, `false` if not, and `null` if the expire date is null.
+`canAccessTokenExpire(AccessToken $HmacToken)` - Checks if Access Token has an expiration set. Returns `true` or `false` accordingly.
 
 ```php
-$token = $this->user->generateAccessToken('foo', ['foo:bar']);
-
-$this->user->getAccessTokenTimeToExpire($token, 'date'); // Returns null
+$expiresAt = Time::parse('2024-11-03 12:00:00');
 
-// Assuming current time is: 2024-11-04 20:00:00
-$token = $this->user->generateAccessToken('foo', ['foo:bar'], '2024-11-03 12:00:00');
+$token = $this->user->generateAccessToken('foo', ['foo:bar'], $expiresAt);
+$this->user->canAccessTokenExpire($token2); // Returns false
 
-$this->user->getAccessTokenTimeToExpire($token, 'date'); // 2024-11-03 12:00:00
-$this->user->getAccessTokenTimeToExpire($token, 'human'); // 1 day ago
-
-$token = $this->user->generateAccessToken('foo', ['foo:bar'], '2026-01-06 12:00:00');
-$this->user->getAccessTokenTimeToExpire($token, 'human'); // in 1 year
+$token2 = $this->user->generateAccessToken('bar');
+$this->user->canAccessTokenExpire($token); // Returns true
 ```
 
+
 ### Access Token Expiration vs Lifetime
 Expiration and Lifetime are different concepts. The lifetime is the maximum time allowed for the token to exist since its last use. Token expiration, on the other hand, is a set date in which the Access Token will cease to function.
 

phpstan-baseline.php

@@ -258,6 +258,7 @@
 ];
 $ignoreErrors[] = [
 	'message' => '#^Call to function model with CodeIgniter\\\\Shield\\\\Models\\\\UserIdentityModel\\:\\:class is discouraged\\.$#',
+	'identifier' => 'codeigniter.factoriesClassConstFetch',
 	'count' => 21,
 	'path' => __DIR__ . '/src/Entities/User.php',
 ];

src/Authentication/Authenticators/AccessTokens.php

@@ -158,7 +158,7 @@ public function check(array $credentials): Result
         if (
             $token->expires !== null
             && $token->expires->isBefore(
-                Time::now()
+                Time::now(),
             )
         ) {
             return new Result([

src/Authentication/Traits/HasAccessTokens.php

@@ -39,11 +39,11 @@ trait HasAccessTokens
      *
      * @param string       $name      Token name
      * @param list<string> $scopes    Permissions the token grants
-     * @param string       $expiresAt Sets token expiration date. Accepts DateTime string formatted as 'Y-m-d h:i:s' or DateTime relative formats (1 day, 2 weeks, 6 months, 1 year) to be added to DateTime 'now'
+     * @param Time         $expiresAt Expiration date
      *
      * @throws InvalidArgumentException
      */
-    public function generateAccessToken(string $name, array $scopes = ['*'], ?string $expiresAt = null): AccessToken
+    public function generateAccessToken(string $name, array $scopes = ['*'], ?Time $expiresAt = null): AccessToken
     {
         /** @var UserIdentityModel $identityModel */
         $identityModel = model(UserIdentityModel::class);
@@ -175,50 +175,22 @@ public function setAccessToken(?AccessToken $accessToken): self
     /**
      * Checks if the provided Access Token has expired.
      *
-     * @return bool|null Returns true if Access Token has expired, false if not, and null if the expire field is null
+     * @return bool Returns true if Access Token has expired, false if not
      */
-    public function hasAccessTokenExpired(?AccessToken $accessToken): bool|null
+    public function hasAccessTokenExpired(?AccessToken $accessToken): bool
     {
-        return $accessToken->expires !== null ? $accessToken->expires->isBefore(Time::now()) : null;
-    }
-
-    /**
-     * Returns formatted date to expiration for provided AccessToken
-     *
-     * @param AccessToken $accessToken AccessToken
-     * @param string      $format      The return format - "date" or "human".  Date is 'Y-m-d h:i:s', human is 'in 2 weeks'
-     *
-     * @return string|null Returns a formatted expiration date or null if the expire field is not set.
-     *
-     * @throws InvalidArgumentException
-     */
-    public function getAccessTokenTimeToExpire(?AccessToken $accessToken, string $format = 'date'): string|null
-    {
-        if (null === $accessToken->expires) {
-            return null;
-        }
-
-        switch ($format) {
-            case 'date':
-                return $accessToken->expires->toLocalizedString();
-
-            case 'human':
-                return $accessToken->expires->humanize();
-
-            default:
-                throw new InvalidArgumentException('getAccessTokenTimeToExpire(): $format argument is invalid. Expects string with "date" or "human".');
-        }
+        return $accessToken->expires !== null && $accessToken->expires->isBefore(Time::now());
     }
 
     /**
      * Sets an expiration for Access Tokens by ID.
      *
-     * @param int    $id        AccessTokens ID
-     * @param string $expiresAt Expiration date. Accepts DateTime string formatted as 'Y-m-d h:i:s' or DateTime relative formats (1 day, 2 weeks, 6 months, 1 year) to be added to DateTime 'now'
+     * @param int  $id        AccessTokens ID
+     * @param Time $expiresAt Expiration date
      *
      * @return bool Returns true if expiration date is set or updated.
      */
-    public function setAccessTokenExpirationById(int $id, string $expiresAt): bool
+    public function setAccessTokenExpirationById(int $id, Time $expiresAt): bool
     {
         /** @var UserIdentityModel $identityModel */
         $identityModel = model(UserIdentityModel::class);
@@ -231,4 +203,14 @@ public function setAccessTokenExpirationById(int $id, string $expiresAt): bool
 
         return $result;
     }
+
+    /**
+     * Checks if the current Hmac token can expire
+     *
+     * @return bool Returns true if AccessToken can expire.
+     */
+    public function canAccessTokenExpire(AccessToken $accessToken): bool
+    {
+        return isset($accessToken->expires);
+    }
 }

src/Authentication/Traits/HasHmacTokens.php

@@ -40,12 +40,12 @@ trait HasHmacTokens
      *
      * @param string       $name      Token name
      * @param list<string> $scopes    Permissions the token grants
-     * @param string       $expiresAt Sets token expiration date. Accepts DateTime string formatted as 'Y-m-d h:i:s' or DateTime relative formats (1 day, 2 weeks, 6 months, 1 year) to be added to DateTime 'now'
+     * @param Time         $expiresAt Expiration date
      *
      * @throws InvalidArgumentException
      * @throws ReflectionException
      */
-    public function generateHmacToken(string $name, array $scopes = ['*'], ?string $expiresAt = null): AccessToken
+    public function generateHmacToken(string $name, array $scopes = ['*'], ?Time $expiresAt = null): AccessToken
     {
         /** @var UserIdentityModel $identityModel */
         $identityModel = model(UserIdentityModel::class);
@@ -165,50 +165,22 @@ public function setHmacToken(?AccessToken $accessToken): self
     /**
      * Checks if the provided Access Token has expired.
      *
-     * @return bool|null Returns true if Access Token has expired, false if not, and null if the expire field is null
+     * @return bool Returns true if Access Token has expired, false if not
      */
-    public function hasHmacTokenExpired(?AccessToken $accessToken): bool|null
+    public function hasHmacTokenExpired(?AccessToken $accessToken): bool
     {
-        return $accessToken->expires !== null ? $accessToken->expires->isBefore(Time::now()) : null;
-    }
-
-    /**
-     * Returns formatted date to expiration for provided Hmac Key/Token.
-     *
-     * @param AccessToken $accessToken AccessToken
-     * @param string      $format      The return format - "date" or "human".  Date is 'Y-m-d h:i:s', human is 'in 2 weeks'
-     *
-     * @return string|null Returns a formatted expiration date or null if the expire field is not set.
-     *
-     * @throws InvalidArgumentException
-     */
-    public function getHmacTokenTimeToExpire(?AccessToken $accessToken, string $format = 'date'): string|null
-    {
-        if (null === $accessToken->expires) {
-            return null;
-        }
-
-        switch ($format) {
-            case 'date':
-                return $accessToken->expires->toLocalizedString();
-
-            case 'human':
-                return $accessToken->expires->humanize();
-
-            default:
-                throw new InvalidArgumentException('getHmacTokenTimeToExpire(): $format argument is invalid. Expects string with "date" or "human".');
-        }
+        return $accessToken->expires !== null && $accessToken->expires->isBefore(Time::now());
     }
 
     /**
      * Sets an expiration for Hmac Key/Token by ID.
      *
-     * @param int    $id        AccessToken ID
-     * @param string $expiresAt Expiration date. Accepts DateTime string formatted as 'Y-m-d h:i:s' or DateTime relative formats (1 day, 2 weeks, 6 months, 1 year) to be added to DateTime 'now'
+     * @param int  $id        AccessToken ID
+     * @param Time $expiresAt Expiration date
      *
      * @return bool Returns true if expiration date is set or updated.
      */
-    public function setHmacTokenExpirationById(int $id, string $expiresAt): bool
+    public function setHmacTokenExpirationById(int $id, Time $expiresAt): bool
     {
         /** @var UserIdentityModel $identityModel */
         $identityModel = model(UserIdentityModel::class);
@@ -221,4 +193,14 @@ public function setHmacTokenExpirationById(int $id, string $expiresAt): bool
 
         return $result;
     }
+
+    /**
+     * Checks if the current Hmac token can expire
+     *
+     * @return bool Returns true if Hmac Token can expire.
+     */
+    public function canHmacTokenExpire(AccessToken $accessToken): bool
+    {
+        return isset($accessToken->expires);
+    }
 }