API key implementation

config/vufind/config.ini

@@ -2641,6 +2641,20 @@ description = "The REST API provides access to search functions and records cont
 ; URL pointing to a Terms of Service page (optional, default is none):
 ;termsOfServiceUrl = "https://something"
 
+; These settings control usage of API keys
+[API_Keys]
+; Mode for using API keys.
+; 'disabled' means API keys are not in use and cannot be created. Default.
+; 'enabled' allows users to create API keys and use them, but it is not mandatory.
+; 'enforced' forces users to create and provide an API key in X-API-KEY header field.
+;mode = 'enabled'
+; Token salt to add when generating a new API key for a user.
+;token_salt =
+; Which header field key should the API key be provided. Default is X-API-KEY.
+;header_field = 'X-API-KEY'
+; Uncomment to allow logging requests using API keys
+;log_requests = true
+
 [Sorting]
 ; By default, VuFind sorts text in a locale-agnostic way; if this setting is
 ; turned on, the current user-selected locale will impact sort order.

languages/Developer/ar.ini

@@ -0,0 +1 @@
+api_key_delete = "حذف"

languages/Developer/bn.ini

@@ -0,0 +1 @@
+api_key_delete = "মুছুন"

languages/Developer/ca.ini

@@ -0,0 +1 @@
+api_key_delete = "Eliminar"

languages/Developer/cs.ini

@@ -0,0 +1 @@
+api_key_delete = "Odstranit"

languages/Developer/cy.ini

@@ -0,0 +1 @@
+api_key_delete = "Dileu"

languages/Developer/da.ini

@@ -0,0 +1 @@
+api_key_delete = "Slet"

languages/Developer/de.ini

@@ -0,0 +1 @@
+api_key_delete = "Löschen"

languages/Developer/el.ini

@@ -0,0 +1 @@
+api_key_delete = "Διαγραφή"

languages/Developer/en.ini

@@ -0,0 +1,11 @@
+api_key = "API key"
+api_key_delete = "Delete"
+api_key_deletion_failed = "API key deletion failed"
+api_key_deletion_success = "API key was deleted successfully"
+api_key_generate = "Generate new"
+api_key_generation_failed = "API key generation failed"
+api_key_generation_success = "API key was generated successfully. Key will be displayed only once so save it: %%TOKEN%%"
+api_key_locked = "API key is locked. Please contact support if you have questions"
+settings = "Developer settings"
+show_developer_settings = "Show developer settings"
+verify_email_address = "Please verify your email-address to generate an API key"

languages/Developer/es.ini

@@ -0,0 +1 @@
+api_key_delete = "Borrar"

languages/Developer/eu.ini

@@ -0,0 +1 @@
+api_key_delete = "Ezabatu"

languages/Developer/fi.ini

@@ -0,0 +1,11 @@
+api_key = "API-avain"
+api_key_delete = "Poista"
+api_key_deletion_failed = "API-avaimen poistaminen epäonnistui"
+api_key_deletion_success = "API-avaimen poistaminen onnistui"
+api_key_generate = "Luo uusi"
+api_key_generation_failed = "API-avaimen luonti epäonnistui"
+api_key_generation_success = "API-avaimen luonti onnistui. Avain näytetään vain kerran, joten tallenna se muistiin: %%TOKEN%%"
+api_key_locked = "API-avain on lukittu. Ota yhteyttä tukeen, jos sinulla on kysyttävää"
+settings = "Kehittäjäasetukset"
+show_developer_settings = "Näytä kehittäjäasetukset"
+verify_email_address = "Vahvista sähköpostiosoitteesi luodaksesi API-avaimen"

languages/Developer/fr.ini

@@ -0,0 +1 @@
+api_key_delete = "Supprimer"

languages/Developer/ga.ini

@@ -0,0 +1 @@
+api_key_delete = "Scrios"

languages/Developer/gl.ini

@@ -0,0 +1 @@
+api_key_delete = "Borrar"

languages/Developer/he.ini

@@ -0,0 +1 @@
+api_key_delete = "מחק"

languages/Developer/hi.ini

@@ -0,0 +1 @@
+api_key_delete = "हटाना"

languages/Developer/hr.ini

@@ -0,0 +1 @@
+api_key_delete = "Izbriši"

languages/Developer/hy.ini

@@ -0,0 +1 @@
+api_key_delete = "Ջնջել"

languages/Developer/it.ini

@@ -0,0 +1 @@
+api_key_delete = "Cancella"

languages/Developer/ja.ini

@@ -0,0 +1 @@
+api_key_delete = "削除"

languages/Developer/mi.ini

@@ -0,0 +1 @@
+api_key_delete = "Muku"

languages/Developer/mn.ini

@@ -0,0 +1 @@
+api_key_delete = "Устгах"

languages/Developer/nl.ini

@@ -0,0 +1 @@
+api_key_delete = "Verwijderen"

languages/Developer/pl.ini

@@ -0,0 +1 @@
+api_key_delete = "Usuń"

languages/Developer/pt-br.ini

@@ -0,0 +1 @@
+api_key_delete = "Apagar"

languages/Developer/pt.ini

@@ -0,0 +1 @@
+api_key_delete = "Apagar"

languages/Developer/ru.ini

@@ -0,0 +1 @@
+api_key_delete = "Удалить"

languages/Developer/se.ini

@@ -0,0 +1 @@
+api_key_delete = "Sihko"

languages/Developer/sl.ini

@@ -0,0 +1 @@
+api_key_delete = "Zbriši"

languages/Developer/sv.ini

@@ -0,0 +1 @@
+api_key_delete = "Radera"

languages/Developer/tr.ini

@@ -0,0 +1 @@
+api_key_delete = "Sil"

languages/Developer/uk.ini

@@ -0,0 +1 @@
+api_key_delete = "Видалити"

languages/Developer/vi.ini

@@ -0,0 +1 @@
+api_key_delete = "Xóa"

languages/Developer/zh-cn.ini

@@ -0,0 +1 @@
+api_key_delete = "删除"

languages/Developer/zh.ini

@@ -0,0 +1 @@
+api_key_delete = "刪除"

module/VuFind/config/module.config.php

@@ -168,6 +168,7 @@
             'VuFind\Controller\AjaxController' => 'VuFind\Controller\AjaxControllerFactory',
             'VuFind\Controller\AlmaController' => 'VuFind\Controller\AbstractBaseFactory',
             'VuFind\Controller\AlphabrowseController' => 'VuFind\Controller\AbstractBaseFactory',
+            'VuFind\Controller\ApiKeyController' => 'VuFind\Controller\AbstractBaseFactory',
             'VuFind\Controller\AuthorController' => 'VuFind\Controller\AbstractBaseFactory',
             'VuFind\Controller\AuthorityController' => 'VuFind\Controller\AbstractBaseFactory',
             'VuFind\Controller\AuthorityRecordController' => 'VuFind\Controller\AbstractBaseFactory',
@@ -243,6 +244,8 @@
             'alma' => 'VuFind\Controller\AlmaController',
             'Alphabrowse' => 'VuFind\Controller\AlphabrowseController',
             'alphabrowse' => 'VuFind\Controller\AlphabrowseController',
+            'ApiKey' => 'VuFind\Controller\ApiKeyController',
+            'apikey' => 'VuFind\Controller\ApiKeyController',
             'Author' => 'VuFind\Controller\AuthorController',
             'author' => 'VuFind\Controller\AuthorController',
             'Authority' => 'VuFind\Controller\AuthorityController',
@@ -419,6 +422,7 @@
             'League\CommonMark\ConverterInterface' => 'VuFind\Service\MarkdownFactory',
             'VuFind\Account\UserAccountService' => 'VuFind\Account\UserAccountServiceFactory',
             'VuFind\AjaxHandler\PluginManager' => 'VuFind\ServiceManager\AbstractPluginManagerFactory',
+            'VuFind\ApiKey\ApiKeyService' => 'VuFind\ApiKey\ApiKeyServiceFactory',
             'VuFind\Auth\EmailAuthenticator' => 'VuFind\Auth\EmailAuthenticatorFactory',
             'VuFind\Auth\ILSAuthenticator' => 'VuFind\Auth\ILSAuthenticatorFactory',
             'VuFind\Auth\LoginTokenManager' => 'VuFind\Auth\LoginTokenManagerFactory',
@@ -799,7 +803,9 @@
 
 // Define static routes -- Controller/Action strings
 $staticRoutes = [
-    'Alphabrowse/Home', 'Author/FacetList', 'Author/Home', 'Author/Search',
+    'Alphabrowse/Home', 'ApiKey/Delete', 'ApiKey/DisplaySettings',
+    'ApiKey/Generate', 'Author/FacetList',
+    'Author/Home', 'Author/Search',
     'Authority/FacetList', 'Authority/Home', 'Authority/Search',
     'Blender/Advanced', 'Blender/Home', 'Blender/Results',
     'Browse/Author', 'Browse/Dewey', 'Browse/Era', 'Browse/Genre', 'Browse/Home',

module/VuFind/src/VuFind/ApiKey/ApiKeyService.php

@@ -0,0 +1,172 @@
+<?php
+
+/**
+ * Service for managing API keys
+ *
+ * PHP version 8
+ *
+ * Copyright (C) The National Library of Finland 2025.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2,
+ * as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+ *
+ * @category VuFind
+ * @package  Service
+ * @author   Juha Luoma <[email protected]>
+ * @license  http://opensource.org/licenses/gpl-2.0.php GNU General Public License
+ * @link     https://vufind.org/wiki/development:plugins:database_gateways Wiki
+ */
+
+namespace VuFind\ApiKey;
+
+use VuFind\Db\Entity\AccessTokenEntityInterface;
+use VuFind\Db\Entity\UserEntityInterface;
+use VuFind\Db\Service\AccessTokenService;
+use VuFind\Db\Service\DbServiceAwareInterface;
+use VuFind\Db\Service\DbServiceAwareTrait;
+
+/**
+ * Service for managing API keys
+ *
+ * @category VuFind
+ * @package  Service
+ * @author   Juha Luoma <[email protected]>
+ * @license  http://opensource.org/licenses/gpl-2.0.php GNU General Public License
+ * @link     https://vufind.org/wiki/development:plugins:database_gateways Wiki
+ */
+class ApiKeyService implements DbServiceAwareInterface
+{
+    use DbServiceAwareTrait;
+
+    /**
+     * Constructor.
+     *
+     * @param array $apiKeySettings Section API_Keys from main configuration.
+     */
+    public function __construct(
+        protected array $apiKeySettings
+    ) {
+    }
+
+    /**
+     * Generate a new api key token
+     *
+     * @param UserEntityInterface $user User to create salt for
+     *
+     * @return string
+     */
+    protected function createRandomToken(UserEntityInterface $user): string
+    {
+        $salt = $this->apiKeySettings['token_salt'] ?? null;
+        if (!$salt) {
+            throw new \Exception('APIKeyService: Salt missing');
+        }
+        $valuesForToken = [
+            $user->getEmailVerified()->format('Y-m-d'),
+            $user->getFirstname(),
+            $user->getLastname(),
+            (string)strtotime('now'),
+            $salt,
+        ];
+        return hash('sha256', implode('|', $valuesForToken));
+    }
+
+    /**
+     * Retrieve an API key for a user. Return associative array containing token, revoked or empty
+     * array if not found.
+     *
+     * @param UserEntityInterface $user User
+     *
+     * @return ?AccessTokenEntityInterface
+     */
+    public function getApiKeyForUser(UserEntityInterface $user): ?AccessTokenEntityInterface
+    {
+        return $this->getDbService(AccessTokenService::class)->getByIdAndType(
+            (string)$user->getId(),
+            AccessTokenService::TYPE_API_KEY,
+            false
+        );
+    }
+
+    /**
+     * Check if API key is valid to be used.
+     *
+     * @param string $token Token to search for.
+     *
+     * @return bool If exists and the access token has not been revoked.
+     */
+    public function isTokenValid(string $token): bool
+    {
+        $token = $this->getDbService(AccessTokenService::class)->getByDataAndType(
+            $token,
+            AccessTokenService::TYPE_API_KEY
+        );
+        return $token && !$token->isRevoked();
+    }
+
+    /**
+     * Validate user can use API keys. It is expected that the user has a verified email address.
+     *
+     * @param UserEntityInterface $user User
+     *
+     * @return bool
+     */
+    public function isUserValid(UserEntityInterface $user): bool
+    {
+        return $user->getEmailVerified() !== null;
+    }
+
+    /**
+     * Generate an API key for a user.
+     *
+     * @param UserEntityInterface $user User
+     *
+     * @return string|false API key token on success, false on failure
+     */
+    public function generateApiKeyForUser(UserEntityInterface $user): string|false
+    {
+        // Check if the user has an existing token and the token has not been revoked.
+        $token = $this->getDbService(AccessTokenService::class)->getByIdAndType(
+            (string)$user->getId(),
+            AccessTokenService::TYPE_API_KEY
+        );
+        if (!$token || $token->isRevoked()) {
+            return false;
+        }
+        $tokenHash = $this->createRandomToken($user);
+        $token->setData($tokenHash);
+        $token->setUser($user);
+        $this->getDbService(AccessTokenService::class)->persistEntity($token);
+        return $tokenHash;
+    }
+
+    /**
+     * Delete an API key for a user
+     *
+     * @param UserEntityInterface $user User
+     *
+     * @return bool
+     */
+    public function deleteApiKeyForUser(UserEntityInterface $user): bool
+    {
+        $token = $this->getDbService(AccessTokenService::class)->getByIdAndType(
+            (string)$user->getId(),
+            AccessTokenService::TYPE_API_KEY
+        );
+        if ($token && !$token->isRevoked()) {
+            $this->getDbService(AccessTokenService::class)->deleteEntity($token);
+            return true;
+        }
+        return false;
+    }
+}

module/VuFind/src/VuFind/ApiKey/ApiKeyServiceFactory.php

@@ -0,0 +1,74 @@
+<?php
+
+/**
+ * Database API key service factory
+ *
+ * PHP version 8
+ *
+ * Copyright (C) The National Library of Finland 2025.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2,
+ * as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+ *
+ * @category VuFind
+ * @package  Database
+ * @author   Juha Luoma <[email protected]>
+ * @license  http://opensource.org/licenses/gpl-2.0.php GNU General Public License
+ * @link     https://vufind.org/wiki/development:plugins:database_gateways Wiki
+ */
+
+namespace VuFind\ApiKey;
+
+use Laminas\ServiceManager\Exception\ServiceNotCreatedException;
+use Laminas\ServiceManager\Exception\ServiceNotFoundException;
+use Laminas\ServiceManager\Factory\FactoryInterface;
+use Psr\Container\ContainerExceptionInterface as ContainerException;
+use Psr\Container\ContainerInterface;
+use VuFind\Config\ConfigManager;
+
+/**
+ * Database API key service factory
+ *
+ * @category VuFind
+ * @package  Database
+ * @author   Juha Luoma <[email protected]>
+ * @license  http://opensource.org/licenses/gpl-2.0.php GNU General Public License
+ * @link     https://vufind.org/wiki/development:plugins:database_gateways Wiki
+ */
+class ApiKeyServiceFactory implements FactoryInterface
+{
+    /**
+     * Create an object
+     *
+     * @param ContainerInterface $container     Service manager
+     * @param string             $requestedName Service being created
+     * @param null|array         $options       Extra options (optional)
+     *
+     * @return object
+     *
+     * @throws ServiceNotFoundException if unable to resolve the service.
+     * @throws ServiceNotCreatedException if an exception is raised when
+     * creating a service.
+     * @throws ContainerException&\Throwable if any other error occurs
+     */
+    public function __invoke(
+        ContainerInterface $container,
+        $requestedName,
+        ?array $options = null
+    ) {
+        if (!empty($options)) {
+            throw new \Exception('Unexpected options sent to factory!');
+        }
+        return new $requestedName($container->get(ConfigManager::class)->getConfigArray('config/API_Keys'));
+    }
+}