ADR-0004: Use Root Entity Scoped Authorization

Status

Accepted

Context

The platform models customer and organisation boundaries as root entities. Most application objects live inside one of these root trees.

The app needs a consistent way to verify whether a user can access or modify an object.

Decision

Users are assigned one or more root entity scopes. Most operations require the target entity to be inside one allowed root tree.

Core check:

target.path <@ allowed_root.path

Operations also require capabilities such as:

entity.read
entity.update
property.update
vault.secret.reveal

Consequences

Positive

• One consistent scoping model across the app.
• Natural tenant/customer isolation.
• Easy to reason about.
• Strong basis for future PostgreSQL RLS.

Negative

• All services must consistently call authorization helpers.
• Cross-root moves require privileged workflows.
• Multi-root users require careful query design.