API key implementation

config/constants.config.php

@@ -42,3 +42,6 @@
 
 // Define default latest year offset from current year for date ranges
 defined('VUFIND_DEFAULT_LATEST_YEAR_OFFSET') || define('VUFIND_DEFAULT_LATEST_YEAR_OFFSET', 1);
+
+// Define default API key header field name
+defined('VUFIND_API_KEY_DEFAULT_HEADER_FIELD') || define('VUFIND_API_KEY_DEFAULT_HEADER_FIELD', 'X-API-KEY');

config/vufind/config.ini

@@ -2689,6 +2689,24 @@ 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.
+; 'optional' 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 a header field (see
+; header_field setting below).
+;mode = 'optional'
+; Token salt to add when generating a new API key for a user.
+; Minimum allowed length for salt is 10 characters.
+; Example command for creating a salt in terminal:
+; php -r "echo hash('sha256', random_bytes(16)) . PHP_EOL;"
+;token_salt = 
+; The header field key that should be used to provide the API key. Default is X-API-KEY.
+;header_field = 'X-API-KEY'
+; How many API keys can a user have at maximum. Default is 5.
+;key_limit = 5
+
 [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.

config/vufind/permissionBehavior.ini

@@ -83,6 +83,10 @@ defaultDeniedTemplateBehavior = false
 [access.EITModule]
 deniedTemplateBehavior = showTemplate:error/loginForAccess
 
+; Configuration for developer settings
+[feature.Developer]
+deniedTemplateBehavior = "showTemplate:error/developer-settings-denied"
+
 ; Example configuration for non-standard favorites permission behavior:
 ;[feature.Favorites]
 ;deniedTemplateBehavior = "showMessage:Login for Favorites"

config/vufind/permissions.ini

@@ -13,6 +13,10 @@
 ;              combined may vary from provider to provider (see below).
 ; permission - The name(s) of the permission(s) to grant. May be a single string or
 ;              an array of strings.
+; assertion  - The name(s) of the assertion(s) class(es) to check for permission.
+;              May be a single assertion name or an array of assertion names.
+;            - Currently supported assertions:
+;               - VerifiedEmail: Asserts that the user has a verified email.
 ;
 ; Any other keys in the section should be the names of permission provider services.
 ; The values associated with these keys will be passed along to the services.
@@ -75,6 +79,7 @@
 ; ipRange[] = "1.2.3.7-1.2.5.254"
 ; insecureCookie = "VUFIND_CUSTOM_COOKIE_NAME"
 ; permission = sample.permission
+; assertion[] = VerifiedEmail
 ; sessionKey = "VUFIND_SESSION_KEY_NAME"
 
 ; Example configuration (grants the "sample.permission" permission to users
@@ -118,6 +123,13 @@ permission = access.StaffViewTab
 role[] = loggedin
 permission = feature.Favorites
 
+; This default example configuration allows logged in users
+; with verified email addresses to use developer settings.
+[default.Developer]
+role[] = loggedin
+permission = feature.Developer
+assertion[] = VerifiedEmail
+
 ; Example for dynamic debug mode
 ;[default.DebugMode]
 ;username[] = admin

module/VuFind/config/module.config.php

@@ -170,6 +170,7 @@
             'VuFind\Controller\AjaxController' => 'VuFind\Controller\AjaxControllerFactory',
             'VuFind\Controller\AlmaController' => 'VuFind\Controller\AbstractBaseFactory',
             'VuFind\Controller\AlphabrowseController' => 'VuFind\Controller\AbstractBaseFactory',
+            'VuFind\Controller\DeveloperSettingsController' => 'VuFind\Controller\AbstractBaseFactory',
             'VuFind\Controller\AuthorController' => 'VuFind\Controller\AbstractBaseFactory',
             'VuFind\Controller\AuthorityController' => 'VuFind\Controller\AbstractBaseFactory',
             'VuFind\Controller\AuthorityRecordController' => 'VuFind\Controller\AbstractBaseFactory',
@@ -246,6 +247,8 @@
             'alma' => 'VuFind\Controller\AlmaController',
             'Alphabrowse' => 'VuFind\Controller\AlphabrowseController',
             'alphabrowse' => 'VuFind\Controller\AlphabrowseController',
+            'DeveloperSettings' => 'VuFind\Controller\DeveloperSettingsController',
+            'developersettings' => 'VuFind\Controller\DeveloperSettingsController',
             'Author' => 'VuFind\Controller\AuthorController',
             'author' => 'VuFind\Controller\AuthorController',
             'Authority' => 'VuFind\Controller\AuthorityController',
@@ -424,6 +427,7 @@
             'League\CommonMark\MarkdownConverter' => 'VuFind\Service\MarkdownFactory',
             'VuFind\Account\UserAccountService' => 'VuFind\Account\UserAccountServiceFactory',
             'VuFind\AjaxHandler\PluginManager' => 'VuFind\ServiceManager\AbstractPluginManagerFactory',
+            'VuFind\DeveloperSettings\DeveloperSettingsService' => 'VuFind\DeveloperSettings\DeveloperSettingsServiceFactory',
             'VuFind\Auth\EmailAuthenticator' => 'VuFind\Auth\EmailAuthenticatorFactory',
             'VuFind\Auth\ILSAuthenticator' => 'VuFind\Auth\ILSAuthenticatorFactory',
             'VuFind\Auth\LoginTokenManager' => 'VuFind\Auth\LoginTokenManagerFactory',
@@ -571,6 +575,7 @@
             'VuFindHttp\HttpService' => 'VuFind\Service\HttpServiceFactory',
             'VuFindSearch\Service' => 'VuFind\Service\SearchServiceFactory',
             'Laminas\Session\SessionManager' => 'VuFind\Session\ManagerFactory',
+            'Lmc\Rbac\Mvc\Service\AuthorizationService' => 'VuFind\Service\AuthorizationServiceFactory',
         ],
         'delegators' => [
             'Laminas\Mvc\I18n\Translator' => [
@@ -787,6 +792,14 @@
             ],
         ],
         'vufind_permission_provider_manager' => [ /* see VuFind\Role\PermissionProvider\PluginManager for defaults */ ],
+        'assertion_manager' => [
+            'factories' => [
+                'VuFind\Role\Assertion\HasVerifiedEmailAssertion' => 'Laminas\ServiceManager\Factory\InvokableFactory',
+            ],
+            'aliases' => [
+                'VerifiedEmail' => 'VuFind\Role\Assertion\HasVerifiedEmailAssertion',
+            ],
+        ],
     ],
 ];
 
@@ -889,6 +902,9 @@
     'Confirm/Confirm',
     'Cover/Show',
     'Cover/Unavailable',
+    'DeveloperSettings/DeleteApiKey',
+    'DeveloperSettings/DisplaySettings',
+    'DeveloperSettings/GenerateApiKey',
     'EDS/Advanced',
     'EDS/Home',
     'EDS/Search',

module/VuFind/sql/migrations/mysql/11.0/012-add-api-key-table.sql

@@ -0,0 +1,13 @@
+CREATE TABLE `api_key` (
+  `id` int NOT NULL AUTO_INCREMENT,
+  `user_id` int(11) NOT NULL,
+  `title` varchar(255) NOT NULL,
+  `token` varchar(255) NOT NULL,
+  `revoked` tinyint(1) NOT NULL DEFAULT 0,
+  `created` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  `last_used` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (`id`),
+  KEY `api_key_user_id_idx` (`user_id`),
+  KEY `api_key_token_idx` (`token`),
+  CONSTRAINT `api_key_ibfk_1` FOREIGN KEY (`user_id`) REFERENCES `user` (`id`) ON DELETE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE utf8mb4_unicode_ci;

module/VuFind/sql/migrations/pgsql/11.0/012-add-api-key-table.sql

@@ -0,0 +1,14 @@
+CREATE TABLE api_key (
+  id SERIAL,
+  user_id int NOT NULL,
+  title varchar(255) NOT NULL,
+  token varchar(255) NOT NULL,
+  revoked boolean NOT NULL DEFAULT '0',
+  created timestamp NOT NULL default CURRENT_TIMESTAMP,
+  last_used timestamp NOT NULL default CURRENT_TIMESTAMP,
+  PRIMARY KEY (id)
+);
+CREATE INDEX api_key_user_id_idx ON api_key (user_id);
+CREATE INDEX api_key_token_idx ON api_key (token);
+ALTER TABLE api_key
+ADD CONSTRAINT api_key_ibfk_1 FOREIGN KEY (user_id) REFERENCES "user" (id) ON DELETE CASCADE;

module/VuFind/sql/mysql.sql

@@ -421,6 +421,27 @@ CREATE TABLE `access_token` (
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE utf8mb4_unicode_ci;
 /*!40101 SET character_set_client = @saved_cs_client */;
 
+--
+-- Table structure for table `api_key`
+--
+
+/*!40101 SET @saved_cs_client     = @@character_set_client */;
+/*!40101 SET character_set_client = utf8mb4 */;
+CREATE TABLE `api_key` (
+  `id` int NOT NULL AUTO_INCREMENT,
+  `user_id` int(11) NOT NULL,
+  `title` varchar(255) NOT NULL,
+  `token` varchar(255) NOT NULL,
+  `revoked` tinyint(1) NOT NULL DEFAULT 0,
+  `created` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  `last_used` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (`id`),
+  KEY `api_key_user_id_idx` (`user_id`),
+  KEY `api_key_token_idx` (`token`),
+  CONSTRAINT `api_key_ibfk_1` FOREIGN KEY (`user_id`) REFERENCES `user` (`id`) ON DELETE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE utf8mb4_unicode_ci;
+/*!40101 SET character_set_client = @saved_cs_client */;
+
 --
 -- Table structure for table `login_token`
 --

module/VuFind/sql/pgsql.sql

@@ -393,6 +393,21 @@ PRIMARY KEY (id, type)
 );
 CREATE INDEX access_token_user_id_idx ON access_token (user_id);
 
+DROP TABLE IF EXISTS "api_key";
+
+CREATE TABLE api_key (
+  id SERIAL,
+  user_id int NOT NULL,
+  title varchar(255) NOT NULL,
+  token varchar(255) NOT NULL,
+  revoked boolean NOT NULL DEFAULT '0',
+  created timestamp NOT NULL default CURRENT_TIMESTAMP,
+  last_used timestamp NOT NULL default CURRENT_TIMESTAMP,
+  PRIMARY KEY (id)
+);
+CREATE INDEX api_key_user_id_idx ON api_key (user_id);
+CREATE INDEX api_key_token_idx ON api_key (token);
+
 --
 -- Table structure for table `login_token`
 --
@@ -614,3 +629,9 @@ ADD CONSTRAINT payment_fee_ibfk_1 FOREIGN KEY (payment_id) REFERENCES "payment"
 ALTER TABLE audit_event
 ADD CONSTRAINT audit_event_ibfk_1 FOREIGN KEY (user_id) REFERENCES "user" (id) ON DELETE SET NULL,
 ADD CONSTRAINT audit_event_ibfk_2 FOREIGN KEY (payment_id) REFERENCES "payment" (id) ON DELETE CASCADE;
+
+---
+-- Constraints for table api_key
+---
+ALTER TABLE api_key
+ADD CONSTRAINT api_key_ibfk_1 FOREIGN KEY (user_id) REFERENCES "user" (id) ON DELETE CASCADE;

module/VuFind/src/VuFind/Controller/AbstractBase.php

@@ -38,6 +38,7 @@
 use Laminas\View\Model\ViewModel;
 use VuFind\Config\Feature\EmailSettingsTrait;
 use VuFind\Controller\Feature\AccessPermissionInterface;
+use VuFind\Controller\Feature\RequestHelperTrait;
 use VuFind\Db\Entity\UserEntityInterface;
 use VuFind\Db\Service\AuditEventServiceInterface;
 use VuFind\Db\Service\PluginManager as DatabaseServiceManager;
@@ -82,6 +83,7 @@ class AbstractBase extends AbstractActionController implements AccessPermissionI
     use EmailSettingsTrait;
     use GetServiceTrait;
     use TranslatorAwareTrait;
+    use RequestHelperTrait;
 
     /**
      * Permission that must be granted to access this module (false for no

module/VuFind/src/VuFind/Controller/DeveloperSettingsController.php

@@ -0,0 +1,123 @@
+<?php
+
+/**
+ * Controller for developer settings i.e API keys
+ *
+ * PHP version 8
+ *
+ * Copyright (C) Villanova University 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, see
+ * <https://www.gnu.org/licenses/>.
+ *
+ * @category VuFind
+ * @package  Controller
+ * @author   Juha Luoma <juha.luoma@helsinki.fi>
+ * @license  http://opensource.org/licenses/gpl-2.0.php GNU General Public License
+ * @link     https://vufind.org Main Site
+ */
+
+namespace VuFind\Controller;
+
+use VuFind\DeveloperSettings\DeveloperSettingsService;
+use VuFind\Exception\Forbidden;
+
+/**
+ * Controller for developer settings i.e API keys
+ *
+ * @category VuFind
+ * @package  Controller
+ * @author   Juha Luoma <juha.luoma@helsinki.fi>
+ * @license  http://opensource.org/licenses/gpl-2.0.php GNU General Public License
+ * @link     https://vufind.org Main Site
+ */
+class DeveloperSettingsController extends AbstractBase
+{
+    /**
+     * Display developer settings
+     *
+     * @return mixed
+     */
+    public function displaySettingsAction()
+    {
+        if (!$user = $this->getUser()) {
+            return $this->forceLogin();
+        }
+        $developerSettingsService = $this->getService(DeveloperSettingsService::class);
+        if (!$developerSettingsService->apiKeysEnabled()) {
+            throw new Forbidden('Developer settings disabled.');
+        }
+        $view = $this->createViewModel();
+        $view->apiKeys = $developerSettingsService->getApiKeysForUser($user);
+        $view->createAllowed = !$developerSettingsService->apiKeysBlocked($view->apiKeys);
+        return $view;
+    }
+
+    /**
+     * Generate an API key for a user.
+     *
+     * @return mixed
+     */
+    public function generateApiKeyAction()
+    {
+        if (!$user = $this->getUser()) {
+            return $this->forceLogin();
+        }
+        $developerSettingsService = $this->getService(DeveloperSettingsService::class);
+        if (!$developerSettingsService->apiKeysEnabled() || !$this->permission()->isAuthorized('feature.Developer')) {
+            throw new Forbidden('Access denied.');
+        }
+
+        $view = $this->createViewModel();
+        if ($this->formWasSubmitted()) {
+            if ($title = $this->getParam('title', true)) {
+                if ($apiKey = $developerSettingsService->generateApiKeyForUser($user, $title)) {
+                    $successMsg = $this->translate(
+                        'Developer::api_key_generation_success',
+                        ['%%TOKEN%%' => $apiKey->getToken()]
+                    );
+                    $this->flashMessenger()->addSuccessMessage($successMsg);
+                    return $view;
+                }
+            }
+            $this->flashMessenger()->addErrorMessage('An error has occurred');
+        }
+
+        return $view;
+    }
+
+    /**
+     * Delete an API key for a user.
+     *
+     * @return mixed
+     */
+    public function deleteApiKeyAction()
+    {
+        if (!$user = $this->getUser()) {
+            return $this->forceLogin();
+        }
+        $developerSettingsService = $this->getService(DeveloperSettingsService::class);
+        if (!$developerSettingsService->apiKeysEnabled() || !$this->permission()->isAuthorized('feature.Developer')) {
+            throw new Forbidden('Access denied.');
+        }
+        if ($this->getParam('confirm') === '1') {
+            $id = $this->getParam('id');
+            if ($id && $developerSettingsService->deleteApiKeyForUser($user, $id)) {
+                $this->flashMessenger()->addSuccessMessage('Developer::api_key_deletion_success');
+            } else {
+                $this->flashMessenger()->addErrorMessage('An error has occurred');
+            }
+        }
+        return $this->redirect()->toRoute('developersettings-displaysettings');
+    }
+}