fix tokens expiration method names.

fix docs and tests.

Author: CosDiabos

docs/references/authentication/hmac.md

@@ -101,30 +101,30 @@ $user->revokeAllHmacTokens();
 
 By default, the HMAC keys don't expire unless they meet the HMAC Keys lifetime expiration after their last used date.
 
-HMAC keys can be set to expire through the `generateHmacToken()` method. This takes the expiration date as the $expiresAt argument. To update or remove an existing HMAC key expiration date use `setHmacTokenExpirationById($HmacTokenID, $expiresAt)`
+HMAC keys can be set to expire through the `generateHmacToken()` method. This takes the expiration date as the `$expiresAt` argument. To update an existing HMAC key expiration date use `updateHmacTokenExpiration($hmacTokenID, $expiresAt)` and to remove `removeHmacTokenExpiration($hmacTokenID)`.
 
-`$expiresAt` [Time](/libraries/time.html) object
+`$expiresAt` [Time](https://codeigniter.com/user_guide/libraries/time.html) object
 
 ```php
 // Expiration date = 2024-11-03 12:00:00
 $expiresAt = Time::parse('2024-11-03 12:00:00');
-$token = $this->user->generateHmacToken('foo', ['foo:bar'], $expiresAt);
+$token = $this->user->generateHmacToken('foo', ['foo.bar'], $expiresAt);
 
 // Expiration date = 2024-11-15 00:00:00
 $expiresAt = Time::parse('2024-11-15 00:00:00');
-$token = $user->setHmacTokenExpirationById($token->id, $expiresAt);
+$user->updateHmacTokenExpiration($token->id, $expiresAt);
 
 // Expiration date = 1 month + 15 days into the future
 $expiresAt = Time::now()->addMonths(1)->addDays(15);
-$token = $user->setHmacTokenExpirationById($token->id, $expiresAt);
+$user->updateHmacTokenExpiration($token->id, $expiresAt);
 
 // Remove the expiration date
-$token = $user->setHmacTokenExpirationById($token->id, null);
+$user->removeHmacTokenExpiration($token->id);
 ```
 
 The following support methods are also available:
 
-`hasHmacTokenExpired(AccessToken $HmacToken)` - Checks if the HMAC key has expired. Returns `true` if the HMAC key has expired, `false` if not.
+`isHmacTokenExpired(AccessToken $HmacToken)` - Checks if the HMAC key is expired. Returns `true` if the HMAC key is expired, `false` if not.
 
 ```php
 $expiresAt = Time::parse('2024-11-03 12:00:00');
@@ -133,7 +133,7 @@ $token = $this->user->generateHmacToken('foo', ['foo.bar'], $expiresAt);
 $this->user->hasHmacTokenExpired($token); // Returns true
 ```
 
-`canHmacTokenExpire(AccessToken $HmacToken)` - Checks if HMAC key has an expiration set. Returns `true` or `false` accordingly.
+`hasHmacTokenExpiry(AccessToken $HmacToken)` - Checks if HMAC key has an expiration set. Returns `true` or `false` accordingly.
 
 ```php
 $expiresAt = Time::parse('2024-11-03 12:00:00');
@@ -146,10 +146,12 @@ $this->user->canHmacTokenExpire($token2); // Returns false
 ```
 
 You can also easily set all existing HMAC keys/tokens as expired with the `spark` command:
-```
+```console
 php spark shield:hmac invalidateAll
 ```
-**Careful!** This command invalidates _all_ keys for _all_ users.
+
+!!! warning
+    This command invalidates _all_ keys for _all_ users.
 
 ## Retrieving HMAC Keys
 

docs/references/authentication/tokens.md

@@ -142,9 +142,9 @@ public $unusedTokenLifetime = YEAR;
 
 By default, the Access Tokens don't expire unless they meet the Access Token lifetime expiration after their last used date.
 
-Access Tokens can be set to expire through the `generateAccessToken()` method. This takes the expiration date as the $expiresAt argument. To update or remove an existing HMAC key expiration date use `setAccessTokenById($HmacTokenID, $expiresAt)`
+Access Tokens can be set to expire through the `generateAccessToken()` method. This takes the expiration date as the `$expiresAt` argument. To update an existing HMAC key expiration date use `updateAcessTokenExpiration($hmacTokenID, $expiresAt)` and to remove `removeAccessTokenExpiration($hmacTokenID)`.
 
-`$expiresAt` [Time](/libraries/time.html) object
+`$expiresAt` [Time](https://codeigniter.com/user_guide/libraries/time.html) object
 
 ```php
 // Expiration date = 2024-11-03 12:00:00
@@ -153,19 +153,19 @@ $token = $this->user->generateAccessToken('foo', ['foo.bar'], $expiresAt);
 
 // Expiration date = 2024-11-15 00:00:00
 $expiresAt = Time::parse('2024-11-15 00:00:00');
-$user->setAccessTokenExpirationById($token->id, $expiresAt);
+$user->updateAcessTokenExpiration($token->id, $expiresAt);
 
 // Or Expiration date = 1 month + 15 days into the future
 $expiresAt = Time::now()->addMonths(1)->addDays(15);
-$user->setAccessTokenExpirationById($token->id, $expiresAt);
+$user->updateAcessTokenExpiration($token->id, $expiresAt);
 
 // Remove the expiration date
-$token = $user->setAccessTokenExpirationById($token->id, null);
+$user->removeAccessTokenExpiration($token->id);
 ```
 
 The following support methods are also available:
 
-`hasAccessTokenExpired(AccessToken $accessToken)` - Checks if Access Token has expired. Returns `true` if the Access Token has expired, `false` if not.
+`isAccessTokenExpired(AccessToken $accessToken)` - Checks if Access Token is expired. Returns `true` if the Access Token is expired, `false` if not.
 
 ```php
 $expiresAt = Time::parse('2024-11-03 12:00:00');
@@ -175,7 +175,7 @@ $token = $this->user->generateAccessToken('foo', ['foo.bar'], $expiresAt);
 $this->user->hasAccessTokenExpired($token); // Returns true
 ```
 
-`canAccessTokenExpire(AccessToken $HmacToken)` - Checks if Access Token has an expiration set. Returns `true` or `false` accordingly.
+`hasAccessTokenExpiry(AccessToken $HmacToken)` - Checks if Access Token has an expiration set. Returns `true` or `false` accordingly.
 
 ```php
 $expiresAt = Time::parse('2024-11-03 12:00:00');

phpstan-baseline.php

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

src/Authentication/Traits/HasAccessTokens.php

@@ -39,7 +39,7 @@ trait HasAccessTokens
      *
      * @param string       $name      Token name
      * @param list<string> $scopes    Permissions the token grants
-     * @param Time         $expiresAt Expiration date
+     * @param Time|null    $expiresAt Expiration date
      *
      * @throws InvalidArgumentException
      */
@@ -173,11 +173,11 @@ public function setAccessToken(?AccessToken $accessToken): self
     }
 
     /**
-     * Checks if the provided Access Token has expired.
+     * Checks if the provided Access Token is expired.
      *
-     * @return bool Returns true if Access Token has expired, false if not
+     * @return bool Returns true if Access Token is expired, false if not
      */
-    public function hasAccessTokenExpired(AccessToken $accessToken): bool
+    public function isAccessTokenExpired(AccessToken $accessToken): bool
     {
         return $accessToken->expires !== null && $accessToken->expires->isBefore(Time::now());
     }
@@ -190,11 +190,32 @@ public function hasAccessTokenExpired(AccessToken $accessToken): bool
      *
      * @return bool Returns true if expiration date is set or updated.
      */
-    public function setAccessTokenExpirationById(int $id, ?Time $expiresAt): bool
+    public function updateAccessTokenExpiration(int $id, Time $expiresAt): bool
     {
         /** @var UserIdentityModel $identityModel */
         $identityModel = model(UserIdentityModel::class);
-        $result        = $identityModel->setIdentityExpirationById($id, $this, $expiresAt, AccessTokens::ID_TYPE_ACCESS_TOKEN);
+        $result        = $identityModel->setIdentityExpirationById($id, $this, $expiresAt);
+
+        if ($result) {
+            // refresh currentAccessToken with updated data
+            $this->currentAccessToken = $identityModel->getAccessTokenById($id, $this);
+        }
+
+        return $result;
+    }
+
+    /**
+     * Removes the expiration date for Access Tokens by ID.
+     *
+     * @param int $id AccessTokens ID
+     *
+     * @return bool Returns true if expiration date is set or updated.
+     */
+    public function removeAccessTokenExpiration(int $id): bool
+    {
+        /** @var UserIdentityModel $identityModel */
+        $identityModel = model(UserIdentityModel::class);
+        $result        = $identityModel->setIdentityExpirationById($id, $this);
 
         if ($result) {
             // refresh currentAccessToken with updated data
@@ -209,7 +230,7 @@ public function setAccessTokenExpirationById(int $id, ?Time $expiresAt): bool
      *
      * @return bool Returns true if AccessToken can expire.
      */
-    public function canAccessTokenExpire(AccessToken $accessToken): bool
+    public function hasAccessTokenExpiry(AccessToken $accessToken): bool
     {
         return $accessToken->expires !== null;
     }

src/Authentication/Traits/HasHmacTokens.php

@@ -14,7 +14,6 @@
 namespace CodeIgniter\Shield\Authentication\Traits;
 
 use CodeIgniter\I18n\Time;
-use CodeIgniter\Shield\Authentication\Authenticators\HmacSha256;
 use CodeIgniter\Shield\Entities\AccessToken;
 use CodeIgniter\Shield\Models\UserIdentityModel;
 use InvalidArgumentException;
@@ -40,7 +39,7 @@ trait HasHmacTokens
      *
      * @param string       $name      Token name
      * @param list<string> $scopes    Permissions the token grants
-     * @param Time         $expiresAt Expiration date
+     * @param Time|null    $expiresAt Expiration date
      *
      * @throws InvalidArgumentException
      * @throws ReflectionException
@@ -163,11 +162,11 @@ public function setHmacToken(?AccessToken $accessToken): self
     }
 
     /**
-     * Checks if the provided Access Token has expired.
+     * Checks if the provided Access Token is expired.
      *
-     * @return bool Returns true if Access Token has expired, false if not
+     * @return bool Returns true if Access Token is expired, false if not
      */
-    public function hasHmacTokenExpired(AccessToken $accessToken): bool
+    public function isHmacTokenExpired(AccessToken $accessToken): bool
     {
         return $accessToken->expires !== null && $accessToken->expires->isBefore(Time::now());
     }
@@ -180,11 +179,11 @@ public function hasHmacTokenExpired(AccessToken $accessToken): bool
      *
      * @return bool Returns true if expiration date is set or updated.
      */
-    public function setHmacTokenExpirationById(int $id, ?Time $expiresAt): bool
+    public function updateHmacTokenExpiration(int $id, Time $expiresAt): bool
     {
         /** @var UserIdentityModel $identityModel */
         $identityModel = model(UserIdentityModel::class);
-        $result        = $identityModel->setIdentityExpirationById($id, $this, $expiresAt, HmacSha256::ID_TYPE_HMAC_TOKEN);
+        $result        = $identityModel->setIdentityExpirationById($id, $this, $expiresAt);
 
         if ($result) {
             // refresh currentAccessToken with updated data
@@ -194,12 +193,33 @@ public function setHmacTokenExpirationById(int $id, ?Time $expiresAt): bool
         return $result;
     }
 
+    /**
+     * Removes the expiration date for Hmac Key/Token by ID.
+     *
+     * @param int $id AccessToken ID
+     *
+     * @return bool Returns true if expiration date is removed.
+     */
+    public function removeHmacTokenExpiration(int $id): bool
+    {
+        /** @var UserIdentityModel $identityModel */
+        $identityModel = model(UserIdentityModel::class);
+        $result        = $identityModel->setIdentityExpirationById($id, $this);
+
+        if ($result) {
+            // refresh currentAccessToken with updated data
+            $this->currentHmacToken = $identityModel->getHmacTokenById($id, $this);
+        }
+
+        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
+    public function hasHmacTokenExpiry(AccessToken $accessToken): bool
     {
         return $accessToken->expires !== null;
     }

src/Models/UserIdentityModel.php

@@ -230,21 +230,21 @@ public function getAllAccessTokens(User $user): array
     }
 
     /**
-     * Updates or sets expiration date of users' AccessToken or HMAC Token by ID. Returns updated row.
+     * Updates or sets expiration date of users' AccessToken or HMAC Token by ID.
      *
      * @param Time  $expiresAt Expiration date
      * @param mixed $id
      *
      * @return bool Returns true if expiration date was set or updated.
      */
-    public function setIdentityExpirationById($id, User $user, ?Time $expiresAt = null, ?string $type_token = null): bool
+    public function setIdentityExpirationById($id, User $user, ?Time $expiresAt = null): bool
     {
         $this->checkUserId($user);
 
         return $this->where('user_id', $user->id)
-            ->where('type', $type_token)
+            ->where('id', $id)
             ->set(['expires' => $expiresAt])
-            ->update($id);
+            ->update();
     }
 
     // HMAC

tests/Authentication/HasAccessTokensTest.php

@@ -164,8 +164,7 @@ public function testGenerateTokenWithExpiration(): void
 
         $this->assertSame($tokenExpiration->format('Y-m-d h:i:s'), $this->user->currentAccessToken()->expires->format('Y-m-d h:i:s'));
 
-        $tokenExpiration = $tokenExpiration->addMonths(1);
-        $tokenExpiration = $tokenExpiration->addYears(1);
+        $tokenExpiration = $tokenExpiration->addMonths(1)->addYears(1);
         $token           = $this->user->generateAccessToken('foo', ['foo.bar'], $tokenExpiration);
         $this->user->setAccessToken($token);
 
@@ -185,7 +184,7 @@ public function testSetTokenExpirationById(): void
 
         $tokenExpiration = Time::parse('2024-11-03 12:00:00');
 
-        $this->assertTrue($this->user->setAccessTokenExpirationById($token->id, $tokenExpiration));
+        $this->assertTrue($this->user->updateAccessTokenExpiration($token->id, $tokenExpiration));
         $this->assertSame($tokenExpiration->format('Y-m-d h:i:s'), $this->user->currentAccessToken()->expires->format('Y-m-d h:i:s'));
     }
 
@@ -198,16 +197,15 @@ public function testIsTokenExpired(): void
         $token           = $this->user->generateAccessToken('foo', ['foo.bar'], $tokenExpiration);
         $this->user->setAccessToken($token);
 
-        $this->assertTrue($this->user->hasAccessTokenExpired($this->user->currentAccessToken()));
+        $this->assertTrue($this->user->isAccessTokenExpired($this->user->currentAccessToken()));
     }
 
     /**
      * See https://github.com/codeigniter4/shield/issues/926
      */
     public function testTokenTimeToExpired(): void
     {
-        $tokenExpiration = Time::now();
-        $tokenExpiration = $tokenExpiration->addYears(1);
+        $tokenExpiration = Time::now()->addYears(1);
 
         $token = $this->user->generateAccessToken('foo', ['foo.bar'], $tokenExpiration);
         $this->user->setAccessToken($token);
@@ -218,34 +216,34 @@ public function testTokenTimeToExpired(): void
     /**
      * See https://github.com/codeigniter4/shield/issues/926
      */
-    public function testCanHmacTokenExpire(): void
+    public function testHasHmacTokenExpiry(): void
     {
-        $tokenExpiration = Time::now();
-        $tokenExpiration = $tokenExpiration->addYears(1);
+        $tokenExpiration = Time::now()->addYears(1);
 
         $token = $this->user->generateAccessToken('foo', ['foo.bar'], $tokenExpiration);
 
-        $this->assertTrue($this->user->canAccessTokenExpire($token));
+        $this->assertTrue($this->user->hasAccessTokenExpiry($token));
 
         $token = $this->user->generateAccessToken('foo', ['foo.bar']);
 
-        $this->assertFalse($this->user->canAccessTokenExpire($token));
+        $this->assertFalse($this->user->hasAccessTokenExpiry($token));
     }
 
     /**
      * See https://github.com/codeigniter4/shield/issues/926
      */
     public function testAccessTokenRemoveExpiration(): void
     {
-        $tokenExpiration = Time::now();
-        $tokenExpiration = $tokenExpiration->addYears(1);
+        $tokenExpiration = Time::now()->addYears(1);
 
         $token = $this->user->generateAccessToken('foo', ['foo.bar'], $tokenExpiration);
 
-        $this->assertTrue($this->user->canAccessTokenExpire($token));
+        $this->user->setAccessToken($token);
+
+        $this->assertTrue($this->user->hasAccessTokenExpiry($token));
 
-        $this->user->setAccessTokenExpirationById($token->id, null);
+        $this->assertTrue($this->user->removeAccessTokenExpiration($token->id));
 
-        $this->assertFalse($this->user->canAccessTokenExpire($this->user->currentAccessToken()));
+        $this->assertFalse($this->user->hasAccessTokenExpiry($this->user->currentAccessToken()));
     }
 }