diff -rN -u old-smederee/modules/hub/src/main/scala/de/smederee/ssh/SshAuthenticationRepository.scala new-smederee/modules/hub/src/main/scala/de/smederee/ssh/SshAuthenticationRepository.scala
--- old-smederee/modules/hub/src/main/scala/de/smederee/ssh/SshAuthenticationRepository.scala	1970-01-01 00:00:00.000000000 +0000
+++ new-smederee/modules/hub/src/main/scala/de/smederee/ssh/SshAuthenticationRepository.scala	2025-02-01 22:09:00.861123461 +0000
@@ -0,0 +1,68 @@
+/*
+ * Copyright (C) 2022  Contributors as noted in the AUTHORS.md file
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * 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 Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package de.smederee.ssh
+
+import java.util.UUID
+
+import de.smederee.hub._
+
+/** The base class for needed repository functionality releated to ssh authentication like loading/providing keys.
+  *
+  * ### General notes ###
+  *
+  * {{{
+  * 1. An account is considered *locked* **NOT** by the presence of an unlock token **BUT** by the presence
+  *    of the `locked_at` date!
+  * 2. All functions MUST work only on *unlocked* accounts!
+  * }}}
+  *
+  * @tparam F
+  *   A higher kinded type which wraps the actual return values.
+  */
+abstract class SshAuthenticationRepository[F[_]] {
+
+  /** Search for the ssh key with the given fingerprint for the specified owner who must not be locked.
+    *
+    * @param fingerprint
+    *   The unique fingerprint of the ssh key.
+    * @return
+    *   An option to the ssh key if it exists.
+    */
+  def findSshKey(fingerprint: KeyFingerprint): F[Option[PublicSshKey]]
+
+  /** Search for the vcs repository entry with the given owner and name.
+    *
+    * @param ownerName
+    *   The name of the repository owner.
+    * @param repoName
+    *   The repository name which must be unique in regard to the owner.
+    * @return
+    *   An option to the successfully found vcs repository entry.
+    */
+  def findVcsRepository(ownerName: Username, repoName: VcsRepositoryName): F[Option[VcsRepository]]
+
+  /** Update the last used column for the key in the database.
+    *
+    * @param keyId
+    *   The unique id of the public ssh key.
+    * @return
+    *   The number of affected database rows.
+    */
+  def updateLastUsed(keyId: UUID): F[Int]
+
+}
diff -rN -u old-smederee/modules/hub/src/main/scala/de/smederee/ssh/SshAuthenticator.scala new-smederee/modules/hub/src/main/scala/de/smederee/ssh/SshAuthenticator.scala
--- old-smederee/modules/hub/src/main/scala/de/smederee/ssh/SshAuthenticator.scala	2025-02-01 22:09:00.857123461 +0000
+++ new-smederee/modules/hub/src/main/scala/de/smederee/ssh/SshAuthenticator.scala	2025-02-01 22:09:00.861123461 +0000
@@ -24,6 +24,21 @@
 import org.apache.sshd.common.AttributeRepository
 import org.slf4j.LoggerFactory
 
+/** A custom PublickeyAuthenticator implementation for restricting access via ssh.
+  *
+  * Currently we follow this flow:
+  * {{{
+  * 1. Find the key and thus the related user account via the key fingerprint.
+  * 2. Find the repository via the requested URI (owner/repo).
+  * 3. Check if the user is permitted ssh access to the repository.
+  * }}}
+  *
+  * @todo
+  *   Currently we only permit ssh access for the repository owner. This should be extended.
+  *
+  * @param genericUser
+  *   A name which represents a ssh user name that can be used for generic access.
+  */
 final class SshAuthenticator(genericUser: SshUsername) extends PublickeyAuthenticator {
   private val log = LoggerFactory.getLogger(getClass)