ADR-0005: Use Root Entity Scoped Authorization

Date: 2026-06-06

Status: Accepted

Context

Eco Manager uses a Universal Entity Platform with parent_entity_id and ltree paths. This makes it possible to represent a customer, organisation, or tenant as a root entity and all of its managed objects as descendants.

The product needs a reusable way to answer a common question:

Is this user allowed to perform this action on this entity or object?

Decision

Users will be scoped to one or more root entities. Application services must verify that the target entity is inside at least one allowed root entity tree before allowing reads, writes, deletes, secret reveals, remote sessions, or audit access.

Conceptually:

target.path <@ allowed_root.path

This check will be implemented first as an application-level authorization utility. Future PostgreSQL RLS policies can reuse the same root-path model as a defense-in-depth layer.

Consequences

Positive

• One consistent scoping model across entities, properties, assets, credentials, Vault records, Admin Studio, and remote sessions.
• Natural fit for tenant/customer isolation.
• Easy to reason about in service code.
• Strong path-based foundation for future RLS.

Trade-offs

• Services must consistently call the authorization helper.
• Reparenting across root boundaries must be treated as a privileged operation.
• Multi-root users require careful query construction and testing.