Files
Enterprise-Knowledge-Base/internal/router
wizardchen f832bce16d docs(rbac): document Contributor vs OwnedXxxOrAdmin selection rule
Adds a checklist comment at the top of internal/router/rbac.go that
explains how to pick between the four role-only guards
(Viewer / Contributor / Admin / Owner) and the ownership-or-role
guards (OwnedKBOrAdmin and friends) when wiring a new route.

The two questions encoded here:

  Q1. Does the resource have a creator?
        YES  → mutating routes use OwnedXxxOrAdmin
        NO   → tenant-wide infra → Admin()
        ENTRY POINT (creating a brand-new owned resource) → Contributor()

  Q2. Is the side effect "private to me" or "visible to others"?
        PRIVATE → Contributor() is fine (e.g. POST /agents/:id/copy)
        PUBLIC  → OwnedXxxOrAdmin or Admin (sharing, transferring,
                  tenant-wide toggles)

The recurring failure mode caught in this PR — FAQ entries, tag CRUD,
KB share, agent share, /shared-agents/disabled all gated to plain
Contributor while the matrix demanded OwnedXxxOrAdmin — is the
"sub-resource drift" anti-pattern: someone wires a new sub-resource
with a freshly-invented gate instead of inheriting from the parent
KB/Agent's matrix.

Also documents the user-facing invariant the guards together produce
("Contributor in their own KB acts like Owner; Contributor in someone
else's KB acts like Viewer") so reviewers have a UX-level sanity check
beyond the role labels.
2026-05-18 17:28:58 +08:00
..