feat(security): milestone5 scoped context and impersonation session

Author: shahar-biron

README.md

@@ -21,6 +21,7 @@ Spring Data FalkorDB provides JPA-style object-graph mapping for [FalkorDB](http
 - **💳 Transaction Support**: Built on Spring's robust transaction management
 - **⚡ High Performance**: Leverages FalkorDB's speed with the official JFalkorDB Java client
 - **🌐 RESP Protocol**: Uses the reliable RESP protocol for communication
+- **🔐 RBAC (Experimental)**: Optional security-aware repositories with `@Secured` and row-level filtering
 
 ## 📦 Installation
 
@@ -94,6 +95,26 @@ dependencies {
 }
 ```
 
+## 🔐 RBAC / Security (Experimental)
+
+Spring Data FalkorDB includes an experimental RBAC layer that can enforce action checks (`READ`, `WRITE`, `CREATE`, `DELETE`) and optional row-level security (`@RowLevelSecurity`).
+
+When using the Spring Boot starter, enable it via:
+
+```properties
+spring.data.falkordb.security.enabled=true
+```
+
+For non-web usage, you can set a thread-local context scope:
+
+```java
+try (var scope = FalkorSecurityContextHolder.withContext(ctx)) {
+    // repository calls here are authorized using ctx
+}
+```
+
+The starter also exposes a `FalkorDBSecuritySession` bean for loading contexts from the graph and admin-only impersonation.
+
 ## 🏃 Quick Start
 
 ### 1. Entity Mapping

spring-boot-starter-data-falkordb/README.md

@@ -103,6 +103,40 @@ public class PersonController {
 | `spring.data.falkordb.database` | Database/graph name **(required)** | - |
 | `spring.data.falkordb.repositories.enabled` | Enable/disable repository auto-configuration | `true` |
 
+## RBAC / Security (Optional)
+
+Enable security-aware repositories and RBAC integration:
+
+```properties
+spring.data.falkordb.security.enabled=true
+```
+
+When enabled, repositories are created using `SecureFalkorDBRepository` and will enforce `@Secured` / `@RowLevelSecurity` metadata.
+
+### Scoped context
+
+For non-web usage (tests, batch jobs), you can set the current `FalkorSecurityContext` using a try-with-resources scope:
+
+```java
+try (var scope = FalkorSecurityContextHolder.withContext(ctx)) {
+    // any repository calls here use ctx
+}
+```
+
+### Impersonation (admin-only)
+
+The starter exposes a `FalkorDBSecuritySession` bean that can load a user context from the graph and optionally impersonate:
+
+```java
+@Autowired FalkorDBSecuritySession session;
+
+try (var scope = session.impersonate("alice")) {
+    // runs as alice
+}
+```
+
+Impersonation requires the current thread context to contain the configured admin role (default: `admin`).
+
 > **Note:** The `@EnableFalkorDBRepositories` annotation is **optional**. Repositories are automatically
 > enabled by the starter. Use `spring.data.falkordb.repositories.enabled=false` to disable them.
 

spring-boot-starter-data-falkordb/src/main/java/org/springframework/boot/autoconfigure/data/falkordb/FalkorDBSecurityConfiguration.java

@@ -16,6 +16,7 @@
 import org.springframework.data.falkordb.security.manager.RBACManager;
 import org.springframework.data.falkordb.security.rls.RowLevelSecurityQueryRewriter;
 import org.springframework.data.falkordb.core.query.FalkorDBQueryRewriter;
+import org.springframework.data.falkordb.security.session.FalkorDBSecuritySession;
 import org.springframework.security.core.Authentication;
 import org.springframework.security.core.context.SecurityContextHolder;
 import org.springframework.web.filter.OncePerRequestFilter;
@@ -63,6 +64,12 @@ public RBACManager falkorDBRbacManager(FalkorDBTemplate template, FalkorDBSecuri
 		return new RBACManager(template, properties.getAdminRole());
 	}
 
+	@Bean
+	@ConditionalOnMissingBean
+	public FalkorDBSecuritySession falkorDBSecuritySession(FalkorDBTemplate template, FalkorDBSecurityProperties properties) {
+		return new FalkorDBSecuritySession(template, properties.getAdminRole(), properties.getDefaultRole());
+	}
+
 	@Bean
 	@ConditionalOnMissingBean
 	@ConditionalOnProperty(prefix = "spring.data.falkordb.security", name = "query-rewrite-enabled", havingValue = "true")

spring-boot-starter-data-falkordb/src/main/java/org/springframework/data/falkordb/security/integration/AuthenticationFalkorSecurityContextAdapter.java

@@ -71,8 +71,7 @@ public FalkorSecurityContext fromAuthentication(Authentication authentication) {
 	}
 
 	private User loadUserByUsername(String username) {
-		String cypher = "MATCH (u:_Security_User {username: $username})-[:HAS_ROLE]->(r:_Security_Role) "
-				+ "RETURN u";
+		String cypher = "MATCH (u:_Security_User {username: $username}) RETURN u as n, id(u) as nodeId";
 		return this.template.query(cypher, Collections.singletonMap("username", username), result -> {
 			for (org.springframework.data.falkordb.core.FalkorDBClient.Record record : result.records()) {
 				User u = this.template.getConverter().read(User.class, record);

spring-boot-starter-data-falkordb/src/main/java/org/springframework/data/falkordb/security/integration/PrivilegeService.java

@@ -94,7 +94,7 @@ private Set<Privilege> loadPrivilegesFromGraph(java.util.Collection<String> role
 		}
 
 		String cypher = "MATCH (r:_Security_Role)<-[:GRANTED_TO]-(p:_Security_Privilege) "
-				+ "WHERE r.name IN $roleNames RETURN p";
+				+ "WHERE r.name IN $roleNames RETURN p as n, id(p) as nodeId";
 		return new HashSet<>(this.template.query(cypher,
 				Collections.singletonMap("roleNames", roleNames), Privilege.class));
 	}

src/main/java/org/springframework/data/falkordb/core/mapping/DefaultFalkorDBEntityConverter.java

@@ -209,6 +209,9 @@ private Object convertValueForFalkorDB(final Object value, final FalkorDBPersist
 		if (value instanceof java.time.Instant) {
 			return DateTimeFormatter.ISO_INSTANT.format((java.time.Instant) value);
 		}
+		if (value instanceof Enum<?>) {
+			return ((Enum<?>) value).name();
+		}
 
 		// Apply intern() function for low-cardinality string properties
 		if (property != null && property.isInterned() && value instanceof String) {
@@ -349,6 +352,16 @@ else if (targetType == String.class) {
 		// Handle String conversions
 		if (value instanceof String) {
 			String strValue = (String) value;
+			if (targetType.isEnum()) {
+				try {
+					@SuppressWarnings({ "unchecked", "rawtypes" })
+					Object enumValue = Enum.valueOf((Class<? extends Enum>) targetType, strValue);
+					return enumValue;
+				}
+				catch (Exception ex) {
+					return null;
+				}
+			}
 			if (targetType == LocalDateTime.class) {
 				try {
 					return LocalDateTime.parse(strValue, DateTimeFormatter.ISO_LOCAL_DATE_TIME);
@@ -1193,7 +1206,7 @@ private Map<String, Object> extractRelationshipProperties(Object relatedEntity)
 	 */
 	private Object extractValueFromNodeObject(FalkorDBClient.Record record, String propertyName) {
 		try {
-			Object nodeObj = record.get("n");
+			Object nodeObj = findNodeObject(record);
 			if (nodeObj == null) {
 				return null;
 			}
@@ -1212,6 +1225,60 @@ private Object extractValueFromNodeObject(FalkorDBClient.Record record, String p
 		}
 	}
 
+	private Object findNodeObject(FalkorDBClient.Record record) {
+		if (record == null) {
+			return null;
+		}
+		// Preferred alias used by repository queries
+		Object n = safeRecordGet(record, "n");
+		if (n != null) {
+			return n;
+		}
+		// Fall back to first node-like object in the record.
+		try {
+			for (String key : record.keys()) {
+				Object v = safeRecordGet(record, key);
+				if (isNodeLike(v)) {
+					return v;
+				}
+			}
+		}
+		catch (Exception ignored) {
+			return null;
+		}
+		return null;
+	}
+
+	private Object safeRecordGet(FalkorDBClient.Record record, String key) {
+		try {
+			return record.get(key);
+		}
+		catch (Exception ex) {
+			return null;
+		}
+	}
+
+	private boolean isNodeLike(Object value) {
+		if (value == null) {
+			return false;
+		}
+		Class<?> type = value.getClass();
+		try {
+			type.getMethod("getProperty", String.class);
+			return true;
+		}
+		catch (NoSuchMethodException ignored) {
+			// ignore
+		}
+		try {
+			type.getMethod("getProperties");
+			return true;
+		}
+		catch (NoSuchMethodException ignored) {
+			return false;
+		}
+	}
+
 	private Object tryGetPropertyMethod(Object nodeObj, String propertyName) {
 		try {
 			java.lang.reflect.Method getPropertyMethod = nodeObj.getClass().getMethod("getProperty", String.class);

src/main/java/org/springframework/data/falkordb/security/context/FalkorSecurityContextHolder.java

@@ -12,6 +12,12 @@
 @API(status = API.Status.EXPERIMENTAL, since = "1.0")
 public final class FalkorSecurityContextHolder {
 
+	@FunctionalInterface
+	public interface Scope extends AutoCloseable {
+		@Override
+		void close();
+	}
+
 	private static final ThreadLocal<FalkorSecurityContext> CONTEXT = new ThreadLocal<>();
 
 	private FalkorSecurityContextHolder() {
@@ -29,4 +35,21 @@ public static void clearContext() {
 		CONTEXT.remove();
 	}
 
+	/**
+	 * Set the given context for the current thread and return a scope that restores
+	 * the previous context when closed.
+	 */
+	public static Scope withContext(FalkorSecurityContext context) {
+		final FalkorSecurityContext previous = getContext();
+		setContext(context);
+		return () -> {
+			if (previous == null) {
+				clearContext();
+			}
+			else {
+				setContext(previous);
+			}
+		};
+	}
+
 }