feat: Add expiration date to access token & hmac keys (#1219)

* feat: add expiration date to access token & hmac keys/tokens.

* fix test assertion

* fix test for lower PHP version and PHPDoc blocks

* fix token expiration type, tests and docs references.
fix invalidateAll hmac cli command.
implements CanAccessTokenExpire() and CanHmacTokenExpire() methods.
removes hasAccessTokenExpired() and hasHmacTokenExpired() methods.

* fix file

* fix namespace case.
fix hmac invalidateAll() expires field.

* fix hasAccessTokenExpired()& hasHmacTokenExpired() args.
fix docs refinement.
fix test.

* fix token expiration args, support remove expiration.
fix tokens / hmac docs.
fix psalm xml attribute: ensureOverrideAttribute.

* fix tokens expiration method names.
fix docs and tests.

* fix hmac docs warning section

* fix hmac expiration docs sample

* fix comments and docs

* fix test assertion

* fix docs and comments.
fix updateHmacTokenExpiration() token refresh.

* fix tokens expire methods names.
fix check() expires type check.
updated docs & tests.

* fix name case

Author: CosDiabos

docs/references/authentication/hmac.md

@@ -97,6 +97,63 @@ You can revoke all HMAC Keys with the `revokeAllHmacTokens()` method.
 $user->revokeAllHmacTokens();
 ```
 
+## Expiring HMAC Keys
+
+By default, the HMAC keys don't expire unless they reach the HMAC keys' lifetime expiration after their last use date.
+
+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)`. To remove it, use `removeHmacTokenExpiration($hmacTokenID)`.
+
+`$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);
+
+// Expiration date = 2024-11-15 00:00:00
+$expiresAt = Time::parse('2024-11-15 00:00:00');
+$user->updateHmacTokenExpiration($token->id, $expiresAt);
+
+// Expiration date = 1 month + 15 days into the future
+$expiresAt = Time::now()->addMonths(1)->addDays(15);
+$user->updateHmacTokenExpiration($token->id, $expiresAt);
+
+// Remove the expiration date
+$user->removeHmacTokenExpiration($token->id);
+```
+
+The following support methods are also available:
+
+`isHmacTokenExpired(AccessToken $hmacToken)` - Checks if the HMAC key is expired. Returns `true` if the HMAC key is expired; otherwise, returns `false`.
+
+```php
+$expiresAt = Time::parse('2024-11-03 12:00:00');
+$token = $this->user->generateHmacToken('foo', ['foo.bar'], $expiresAt);
+
+$this->user->isHmacTokenExpired($token); // Returns true
+```
+
+`canHmacTokenExpire(AccessToken $hmacToken)` - Checks if HMAC key has an expiration set. Returns `true` if the HMAC key is expired; otherwise, returns `false`.
+
+```php
+$expiresAt = Time::parse('2024-11-03 12:00:00');
+
+$token = $this->user->generateHmacToken('foo', ['foo.bar'], $expiresAt);
+$this->user->canHmacTokenExpire($token); // Returns true
+
+$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:
+```console
+php spark shield:hmac invalidateAll
+```
+
+!!! warning
+
+    This command invalidates _all_ keys for _all_ users.
+
 ## Retrieving HMAC Keys
 
 The following methods are available to help you retrieve a user's HMAC keys:
@@ -217,7 +274,7 @@ Configure **app/Config/AuthToken.php** for your needs.
 
 ### HMAC Keys Lifetime
 
-HMAC Keys/Tokens will expire after a specified amount of time has passed since they have been used.
+HMAC Keys will expire after a specified amount of time has passed since they have been used.
 
 By default, this is set to 1 year. You can change this value by setting the `$unusedTokenLifetime`
 value. This is in seconds so that you can use the
@@ -228,6 +285,10 @@ that CodeIgniter provides.
 public $unusedTokenLifetime = YEAR;
 ```
 
+### HMAC Keys Expiration vs Lifetime
+
+Expiration and lifetime are two different concepts. The lifetime is the maximum time allowed for the HMAC Key to exist since its last use. HMAC Key expiration, on the other hand, is a set date in which the HMAC Key will cease to function.
+
 ### Login Attempt Logging
 
 By default, only failed login attempts are recorded in the `auth_token_logins` table.

docs/references/authentication/tokens.md

@@ -125,7 +125,7 @@ Configure **app/Config/AuthToken.php** for your needs.
 
 ### Access Token Lifetime
 
-Tokens will expire after a specified amount of time has passed since they have been used.
+Tokens will expire after a specified amount of time has passed since they have last been used.
 
 By default, this is set to 1 year.
 You can change this value by setting the `$unusedTokenLifetime` value. This is
@@ -137,6 +137,61 @@ that CodeIgniter provides.
 public $unusedTokenLifetime = YEAR;
 ```
 
+
+## Expiring Access Tokens
+
+By default, the Access Tokens don't expire unless they reach the Access Token's lifetime expiration after their last use date.
+
+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($accessTokenID, $expiresAt)`. To remove it, use `removeAccessTokenExpiration($accessTokenID)`.
+
+`$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->generateAccessToken('foo', ['foo.bar'], $expiresAt);
+
+// Expiration date = 2024-11-15 00:00:00
+$expiresAt = Time::parse('2024-11-15 00:00:00');
+$user->updateAcessTokenExpiration($token->id, $expiresAt);
+
+// Or Expiration date = 1 month + 15 days into the future
+$expiresAt = Time::now()->addMonths(1)->addDays(15);
+$user->updateAcessTokenExpiration($token->id, $expiresAt);
+
+// Remove the expiration date
+$user->removeAccessTokenExpiration($token->id);
+```
+
+The following support methods are also available:
+
+`isAccessTokenExpired(AccessToken $accessToken)` - Checks if Access Token is expired. Returns `true` if the Access Token is expired; otherwise, returns `false`.
+
+```php
+$expiresAt = Time::parse('2024-11-03 12:00:00');
+
+$token = $this->user->generateAccessToken('foo', ['foo.bar'], $expiresAt);
+
+$this->user->isAccessTokenExpired($token); // Returns true
+```
+
+`canAccessTokenExpire(AccessToken $accessToken)` - Returns `true` if the Access Token has a set expiration date; otherwise, returns `false`.
+
+```php
+$expiresAt = Time::parse('2024-11-03 12:00:00');
+
+$token = $this->user->generateAccessToken('foo', ['foo.bar'], $expiresAt);
+$this->user->canAccessTokenExpire($token2); // Returns false
+
+$token2 = $this->user->generateAccessToken('bar');
+$this->user->canAccessTokenExpire($token); // Returns true
+```
+
+
+### Access Token Expiration vs Lifetime
+
+Expiration and lifetime are two 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.
+
 ### Login Attempt Logging
 
 By default, only failed login attempts are recorded in the `auth_token_logins` table.

phpstan-baseline.php

@@ -168,7 +168,13 @@
 $ignoreErrors[] = [
 	'message' => '#^Cannot access property \\$id on array\\<string, string\\>\\|object\\.$#',
 	'identifier' => 'property.nonObject',
-	'count' => 7,
+	'count' => 9,
+	'path' => __DIR__ . '/src/Commands/Hmac.php',
+];
+$ignoreErrors[] = [
+	'message' => '#^Cannot access property \\$expires on array\\<string, string\\>\\|object\\.$#',
+	'identifier' => 'property.nonObject',
+	'count' => 3,
 	'path' => __DIR__ . '/src/Commands/Hmac.php',
 ];
 $ignoreErrors[] = [
@@ -259,7 +265,7 @@
 $ignoreErrors[] = [
 	'message' => '#^Call to function model with CodeIgniter\\\\Shield\\\\Models\\\\UserIdentityModel\\:\\:class is discouraged\\.$#',
 	'identifier' => 'codeigniter.factoriesClassConstFetch',
-	'count' => 19,
+	'count' => 23,
 	'path' => __DIR__ . '/src/Entities/User.php',
 ];
 $ignoreErrors[] = [

psalm.xml

@@ -11,6 +11,7 @@
     errorBaseline="psalm-baseline.xml"
     findUnusedBaselineEntry="false"
     findUnusedCode="false"
+    ensureOverrideAttribute="false"
 >
     <projectFiles>
         <directory name="src/" />

src/Authentication/Authenticators/AccessTokens.php

@@ -154,6 +154,19 @@ public function check(array $credentials): Result
 
         assert($token->last_used_at instanceof Time || $token->last_used_at === null);
 
+        // Is expired ?
+        if (
+            $token->expires instanceof Time
+            && $token->expires->isBefore(
+                Time::now(),
+            )
+        ) {
+            return new Result([
+                'success' => false,
+                'reason'  => lang('Auth.oldToken'),
+            ]);
+        }
+
         // Hasn't been used in a long time
         if (
             $token->last_used_at

src/Authentication/Traits/HasAccessTokens.php

@@ -13,8 +13,11 @@
 
 namespace CodeIgniter\Shield\Authentication\Traits;
 
+use CodeIgniter\I18n\Time;
+use CodeIgniter\Shield\Authentication\Authenticators\AccessTokens;
 use CodeIgniter\Shield\Entities\AccessToken;
 use CodeIgniter\Shield\Models\UserIdentityModel;
+use InvalidArgumentException;
 
 /**
  * Trait HasAccessTokens
@@ -34,15 +37,18 @@ trait HasAccessTokens
     /**
      * Generates a new personal access token for this user.
      *
-     * @param string       $name   Token name
-     * @param list<string> $scopes Permissions the token grants
+     * @param string       $name      Token name
+     * @param list<string> $scopes    Permissions the token grants
+     * @param Time|null    $expiresAt Expiration date
+     *
+     * @throws InvalidArgumentException
      */
-    public function generateAccessToken(string $name, array $scopes = ['*']): AccessToken
+    public function generateAccessToken(string $name, array $scopes = ['*'], ?Time $expiresAt = null): AccessToken
     {
         /** @var UserIdentityModel $identityModel */
         $identityModel = model(UserIdentityModel::class);
 
-        return $identityModel->generateAccessToken($this, $name, $scopes);
+        return $identityModel->generateAccessToken($this, $name, $scopes, $expiresAt);
     }
 
     /**
@@ -165,4 +171,63 @@ public function setAccessToken(?AccessToken $accessToken): self
 
         return $this;
     }
+
+    /**
+     * Checks if the provided Access Token is expired.
+     */
+    public function isAccessTokenExpired(AccessToken $accessToken): bool
+    {
+        return $accessToken->expires instanceof Time && $accessToken->expires->isBefore(Time::now());
+    }
+
+    /**
+     * Sets an expiration for Access Tokens by ID.
+     *
+     * @param int  $id        AccessTokens ID
+     * @param Time $expiresAt Expiration date
+     *
+     * @return bool Returns true if expiration date is set or updated.
+     */
+    public function updateAccessTokenExpiration(int $id, Time $expiresAt): bool
+    {
+        /** @var UserIdentityModel $identityModel */
+        $identityModel = model(UserIdentityModel::class);
+        $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
+            $this->currentAccessToken = $identityModel->getAccessTokenById($id, $this);
+        }
+
+        return $result;
+    }
+
+    /**
+     * Checks if the access token has a set expiration date
+     */
+    public function canAccessTokenExpire(AccessToken $accessToken): bool
+    {
+        return $accessToken->expires !== null;
+    }
 }