From 070b54b09de9acb3775e638c19633bc16b18f28a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michal=20Vav=C5=99=C3=ADk?= <mvavrik@redhat.com>
Date: Fri, 4 Oct 2024 18:01:35 +0200
Subject: [PATCH] Add @PermissionChecker annotation

---
 .../quarkus/security/PermissionChecker.java   | 66 +++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100644 src/main/java/io/quarkus/security/PermissionChecker.java

diff --git a/src/main/java/io/quarkus/security/PermissionChecker.java b/src/main/java/io/quarkus/security/PermissionChecker.java
new file mode 100644
index 0000000..fdedd4f
--- /dev/null
+++ b/src/main/java/io/quarkus/security/PermissionChecker.java
@@ -0,0 +1,66 @@
+package io.quarkus.security;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Used to annotate CDI bean methods that check if a user holds a permission specified by the {@link #value()}.
+ * Quarkus Security will augment every {@link io.quarkus.security.identity.SecurityIdentity} with this permission checker.
+ * Such a permission checker grants access to methods secured with the {@link PermissionsAllowed} security annotation.
+ * Following example shows how it works:
+ * <pre>
+ * {@code
+ * &#64;Path("hello")
+ * public class HelloResource {
+ *
+ *     &#64;PermissionsAllowed("speak")
+ *     &#64;GET
+ *     public String sayHello() {
+ *         return "Hello World!";
+ *     }
+ *
+ *     &#64;PermissionChecker("speak")
+ *     public boolean canSpeak(SecurityIdentity identity) {
+ *         return "speaker".equals(identity.getPrincipal().getName());
+ *     }
+ * }
+ * }
+ * </pre>
+ * The permission checker methods can include any of secured method parameters (matched by name).
+ * Consider the following secured method:
+ * <pre>
+ * {@code
+ * &#64;PermissionsAllowed("update")
+ * public String updateString(String a, String b, String c, String d) {
+ *     ...
+ * }
+ * }
+ * </pre>
+ * The permission checker that grants access to the {@code updateString} method can inject
+ * any arguments it requires and optionally even {@link io.quarkus.security.identity.SecurityIdentity}:
+ * <pre>
+ * {@code
+ * &#64;PermissionChecker("update")
+ * public boolean canUpdate(String c, String a, SecurityIdentity identity) {
+ *     ...
+ * }
+ * }
+ * </pre>
+ * The permission checker method parameters are matched with the secured method parameters in exactly same fashion
+ * as are constructor parameters of a custom permission. Please see {@link PermissionsAllowed#params()} for more information.
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface PermissionChecker {
+
+    /**
+     * Specifies a permission this checker grants.
+     *
+     * @see PermissionsAllowed#value()
+     * @return name of the permission this checker grants
+     */
+    String value();
+
+}