feat(authorization): Introduce InvalidHierarchyIdException

This is a new exception class that is thrown by `DbAuthorizationService`
when it cannot resolve a hierarchy ID. Throwing a special exception in
this case allows handling this error condition differently from normal
authorization errors. For instance, the REST API should return a 404
response if users provide non-existing IDs.

Signed-off-by: Oliver Heger <[email protected]>

Author: oheger-bosch

components/authorization/backend/src/main/kotlin/service/DbAuthorizationService.kt

@@ -96,13 +96,8 @@ class DbAuthorizationService(
         userId: String,
         hierarchyId: HierarchyId,
         checker: PermissionChecker
-    ): EffectiveRole? {
-        val compoundHierarchyId = resolveCompoundId(hierarchyId)
-
-        return compoundHierarchyId.takeUnless { it.isInvalid() }?.let {
-            checkPermissions(userId, it, checker)
-        }
-    }
+    ): EffectiveRole? =
+        checkPermissions(userId, resolveCompoundId(hierarchyId), checker)
 
     override suspend fun getEffectiveRole(
         userId: String,
@@ -129,21 +124,8 @@ class DbAuthorizationService(
     override suspend fun getEffectiveRole(
         userId: String,
         hierarchyId: HierarchyId
-    ): EffectiveRole {
-        val compoundHierarchyId = resolveCompoundId(hierarchyId)
-
-        return if (compoundHierarchyId.isInvalid()) {
-            logger.warn("Failed to resolve hierarchy ID $hierarchyId.")
-
-            EffectiveRoleImpl(
-                elementId = compoundHierarchyId,
-                isSuperuser = false,
-                permissions = PermissionChecker()
-            )
-        } else {
-            getEffectiveRole(userId, compoundHierarchyId)
-        }
-    }
+    ): EffectiveRole =
+        getEffectiveRole(userId, resolveCompoundId(hierarchyId))
 
     override suspend fun assignRole(
         userId: String,
@@ -273,6 +255,11 @@ class DbAuthorizationService(
                 val (orgId, prodId) = resolveOrganizationAndProduct(hierarchyId)
                 CompoundHierarchyId.forRepository(orgId, prodId, hierarchyId)
             }
+        }.also {
+            if (it.isInvalid()) {
+                logger.warn("Failed to resolve hierarchy ID $hierarchyId.")
+                throw InvalidHierarchyIdException(hierarchyId)
+            }
         }
 
     /**

components/authorization/backend/src/main/kotlin/service/InvalidHierarchyIdException.kt

@@ -0,0 +1,31 @@
+/*
+ * Copyright (C) 2025 The ORT Server Authors (See <https://github.com/eclipse-apoapsis/ort-server/blob/main/NOTICE>)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ * License-Filename: LICENSE
+ */
+
+package org.eclipse.apoapsis.ortserver.components.authorization.service
+
+import org.eclipse.apoapsis.ortserver.model.HierarchyId
+
+/**
+ * An exception class that is thrown by the [AuthorizationService] when it cannot resolve a [HierarchyId]. This
+ * typically means that users have called the API with the ID of a non-existing hierarchy element. Thus, such exceptions
+ * should lead to HTTP 404 responses.
+ */
+class InvalidHierarchyIdException(
+    val hierarchyId: HierarchyId
+) : RuntimeException("Could not resolve hierarchy ID: $hierarchyId.")

components/authorization/backend/src/test/kotlin/service/DbAuthorizationServiceTest.kt

@@ -19,6 +19,7 @@
 
 package org.eclipse.apoapsis.ortserver.components.authorization.service
 
+import io.kotest.assertions.throwables.shouldThrow
 import io.kotest.core.spec.style.WordSpec
 import io.kotest.inspectors.forAll
 import io.kotest.matchers.collections.shouldBeSingleton
@@ -29,6 +30,7 @@ import io.kotest.matchers.nulls.beNull
 import io.kotest.matchers.nulls.shouldNotBeNull
 import io.kotest.matchers.should
 import io.kotest.matchers.shouldBe
+import io.kotest.matchers.string.shouldContain
 
 import org.eclipse.apoapsis.ortserver.components.authorization.db.RoleAssignmentsTable
 import org.eclipse.apoapsis.ortserver.components.authorization.rights.EffectiveRole
@@ -105,36 +107,33 @@ class DbAuthorizationServiceTest : WordSpec() {
                 }
             }
 
-            "return an object with no permissions if resolving the product ID fails" {
+            "throw an InvalidHierarchyIdException if resolving the product ID fails" {
                 val service = createService()
-
                 val missingProductId = ProductId(-1L)
 
-                val effectiveRole = service.getEffectiveRole(
-                    USER_ID,
-                    missingProductId
-                )
+                val exception = shouldThrow<InvalidHierarchyIdException> {
+                    service.getEffectiveRole(
+                        USER_ID,
+                        missingProductId
+                    )
+                }
 
-                effectiveRole.elementId shouldBe CompoundHierarchyId.forProduct(OrganizationId(-1L), missingProductId)
-                checkPermissions(effectiveRole)
+                exception.hierarchyId shouldBe missingProductId
             }
 
-            "return an object with no permissions if resolving the repository ID fails" {
+            "throw an IllegalHierarchyIdException if resolving the repository ID fails" {
                 val service = createService()
 
                 val missingRepositoryId = RepositoryId(-1L)
 
-                val effectiveRole = service.getEffectiveRole(
-                    USER_ID,
-                    missingRepositoryId
-                )
+                val exception = shouldThrow<InvalidHierarchyIdException> {
+                    service.getEffectiveRole(
+                        USER_ID,
+                        missingRepositoryId
+                    )
+                }
 
-                effectiveRole.elementId shouldBe CompoundHierarchyId.forRepository(
-                    OrganizationId(-1L),
-                    ProductId(-1L),
-                    missingRepositoryId
-                )
-                checkPermissions(effectiveRole)
+                exception.hierarchyId shouldBe missingRepositoryId
             }
 
             "return an object with no permissions for a user without role assignments" {
@@ -434,16 +433,20 @@ class DbAuthorizationServiceTest : WordSpec() {
                 }
             }
 
-            "handle an invalid compound hierarchy ID gracefully" {
+            "throw an InvalidHierarchyIdException for an invalid hierarchy ID" {
                 val service = createService()
+                val invalidId = ProductId(-1L)
 
-                val effectiveRole = service.checkPermissions(
-                    USER_ID,
-                    ProductId(-1L),
-                    HierarchyPermissions.permissions(ProductPermission.READ)
-                )
+                val exception = shouldThrow<InvalidHierarchyIdException> {
+                    service.checkPermissions(
+                        USER_ID,
+                        invalidId,
+                        HierarchyPermissions.permissions(ProductPermission.READ)
+                    )
+                }
 
-                effectiveRole should beNull()
+                exception.hierarchyId shouldBe invalidId
+                exception.message shouldContain "Could not resolve hierarchy ID"
             }
         }