effective_user_id Definition in Thalabus ACL

Short Answer

effective_user_id is the same as user_uuid. It is the authenticated user's unique identifier and corresponds to the User.id property in the Neo4j graph database.

---

Detailed Explanation

What is effective_user_id?

effective_user_id is a parameter used throughout the Thalabus system to represent the authenticated user performing an action, for the purpose of ACL permission checking.

• Type: Optional[str] — A string UUID, or None for unauthenticated/administrative access
• Source: Obtained via get_user_service().get_user_uuid()
• Neo4j representation: Matches the id property on :User nodes: (u:User {id: $effectiveUserId})

Relationship to user_uuid

effective_user_id and user_uuid refer to the same value:

# In service code throughout the codebase:
effective_user_id = get_user_service().get_user_uuid()  # Same thing!

The term effective_user_id is used in ACL and permission-checking contexts because it emphasizes the role of the user as an effective user (an entity performing actions that require authorization). The term user_uuid is used in other contexts to emphasize the user's unique identity.

Where is effective_user_id Set?

The user's UUID is established when a session is created:

# From UserService
def set_user_uuid(self, user_uuid: Optional[str]) -> None:
    """Store the authenticated user's UUID for the current session."""
    self._user_uuid = user_uuid or None
    os.environ['USER_UUID'] = self._user_uuid

def get_user_uuid(self) -> Optional[str]:
    """Return the authenticated user's UUID for the current session."""
    return self._user_uuid

The API sets this value when creating a new session via POST /session/<session_id>:

{
  "user_uuid": "<uuid>"
}

When is effective_user_id Used in ACL?

effective_user_id is used in all ACL permission checks to:

1. Identify the user making the request
2. Traverse the Neo4j graph to find groups the user belongs to: (u:User {id: $effectiveUserId})-[:MEMBER_OF]->(g:Group)
3. Check permissions via GRANT relationships: (g:Group)-[:\GRANT:READ`]->(resource)`
4. Enforce tenant-admin bypass by checking for the tenant-admin capability

Example: How effective_user_id Flows Through ACL

# DocumentsService.get_document()
def get_document(self, document_id: str, effective_user_id: Optional[str] = None, ...):
    if effective_user_id:
        # Use effective_user_id in ACL WHERE clause
        acl_clause = acl_document_where_clause("d")  
        # This generates:
        # AND (
        #   EXISTS { MATCH (u:User {id: $effectiveUserId})-[:MEMBER_OF]->(g:Group)-[:HAS_ROLE]->(:UserRole)-[:HAS_CAPABILITY]->(:UserCapability:SystemAcl {id: 'tenant-admin'}) }
        #   OR EXISTS { ... GRANT:READ ... }
        # )
        query = f"MATCH (d:Document) WHERE {query_conditions}{acl_clause}"
        execute_neo4j_query(query, {"effectiveUserId": effective_user_id})

When effective_user_id is None

When effective_user_id = None:

• ACL checks are skipped entirely
• The query returns all matching records (no permission filtering)
• This is used for:
• Internal/administrative operations that should bypass ACL
• Background jobs that process data without a specific user context

# Example: Skip ACL for an internal operation
documents = docs_service.get_documents(doc_ids, effective_user_id=None)  # No ACL filtering

---

Key Points Summary

Aspect	Value
Same as?	user_uuid — exactly the same value
Type	Optional[str] (UUID or None)
Neo4j Node	User.id property on :User nodes
Set by	API when creating a session (POST /session/<session_id>)
Accessed via	get_user_service().get_user_uuid()
Used for	ACL permission checking and user identification
When None	ACL is bypassed (internal/admin operations only)

---

Code References

• Service that manages effective_user_id: UserService
• ACL WHERE clause generation: acl_cypher_utils.py
• Example usage in documents: DocumentsService
• Example usage in dossiers: DossiersService