Janady13/missionmatch / internal/platform/security/rbac.go

1package security 2 3import "sort" 4 5// Role is the tenant role enum already enforced by the users table CHECK constraint. The six roles 6// form an ordered hierarchy for the RequireRole comparison, but capabilities are assigned explicitly 7// per role below, not implied by rank alone. 8type Role string 9 10const ( 11 // RoleSuperuser sits above owner and is the only role permitted to create another of its own kind. 12 // It exists so the top of the ladder can survive its holders: owner cannot mint an owner, by the same 13 // separation of duties rule that stops an admin minting an admin, which means without a tier above it 14 // an organization that loses its owners cannot recover without direct database access. Superuser is 15 // that tier, held by a named few, and every other rule about it is ordinary. 16 RoleSuperuser Role = "superuser" 17 RoleOwner Role = "owner" 18 RoleAdmin Role = "admin" 19 RoleRecruiter Role = "recruiter" 20 // RoleManager is a recruiting team lead: they see the whole team's book and move work between 21 // people, and they hold none of the account or privacy authority an admin does. 22 RoleManager Role = "manager" 23 RoleMember Role = "member" 24 RoleViewer Role = "viewer" 25) 26 27// Capability is a fine grained permission checked at the API. Handlers gate on a Capability rather 28// than a role so the policy lives in one table and the UI never has to hide a control to enforce 29// access. 30type Capability string 31 32const ( 33 CapCandidateRead Capability = "candidate.read" 34 CapCandidateWrite Capability = "candidate.write" 35 CapRequirementEdit Capability = "requirement.write" 36 CapSlateEdit Capability = "slate.write" 37 CapSearchRun Capability = "search.run" 38 CapExportRun Capability = "export.run" 39 CapSourcingRead Capability = "sourcing.read" // see sourced candidate contact fields and the sourcing log 40 CapPrivacyErase Capability = "privacy.erase" // hard delete a sourced candidate and their PII 41 CapUserInvite Capability = "user.invite" 42 CapUserRoleChange Capability = "user.role.change" 43 CapUserDisable Capability = "user.disable" 44 CapOrgSettings Capability = "org.settings.write" 45 // CapDeskReassign moves an account or a job order between recruiters. It is the reason the manager 46 // tier exists: reassigning a desk is the most common thing a team lead does, and before this it 47 // required admin, which also carries PII deletion. 48 CapDeskReassign Capability = "desk.reassign" 49 CapAuditRead Capability = "audit.read" 50 CapComplianceRead Capability = "compliance.read" // adverse impact report, AEDT inventory and model registry, retention reads 51 CapComplianceWrite Capability = "compliance.write" // register an AEDT tool, run retention: governance writes 52 CapStaffingRecommend Capability = "staffing.recommend" // generate an AI staffing recommendation run; this WRITES recommendation rows, so it is a write capability, not a read 53 CapBrainQuery Capability = "brain.query" // ask the AI brain a natural language question (read only augmented generation over the tenant's own data) 54 CapCurationCurate Capability = "curation.curate" // approve a teaching curation proposal and verify the staged ontology edge, the two step WS8 human in the loop gate; a governance write held at the compliance tier 55) 56 57// roleRank orders the hierarchy for AtLeast and for bounding invited roles. Higher is more 58// privileged. 59var roleRank = map[Role]int{ 60 RoleViewer: 0, 61 RoleMember: 1, 62 RoleRecruiter: 2, 63 RoleManager: 3, 64 RoleAdmin: 4, 65 RoleOwner: 5, 66 RoleSuperuser: 6, 67} 68 69// capabilityRoles is the authoritative permission matrix. owner holds every capability. admin manages 70// recruiter, member, and viewer accounts and runs the recruiting workflow, but cannot change org 71// settings or manage other admins and owners (those are owner only and are further guarded by the 72// separation of duties checks in the auth service). The two privacy capabilities gate the sourced 73// candidate contact fields, the sourcing log, and erasure: sourcing.read goes to the roles that 74// actually source (owner, admin, recruiter) and the destructive privacy.erase is held tighter 75// (owner, admin). 76var capabilityRoles = map[Capability][]Role{ 77 CapCandidateRead: {RoleOwner, RoleAdmin, RoleManager, RoleRecruiter, RoleMember, RoleViewer}, 78 CapSearchRun: {RoleOwner, RoleAdmin, RoleManager, RoleRecruiter, RoleMember, RoleViewer}, 79 CapBrainQuery: {RoleOwner, RoleAdmin, RoleManager, RoleRecruiter, RoleMember, RoleViewer}, // same tier as search.run: a read only question over the tenant's own data 80 CapCandidateWrite: {RoleOwner, RoleAdmin, RoleManager, RoleRecruiter}, 81 CapRequirementEdit: {RoleOwner, RoleAdmin, RoleManager, RoleRecruiter}, 82 CapSlateEdit: {RoleOwner, RoleAdmin, RoleManager, RoleRecruiter}, 83 CapStaffingRecommend: {RoleOwner, RoleAdmin, RoleManager, RoleRecruiter}, // same roles that hold slate.write: generating staffing recommendations is the same authority tier 84 CapExportRun: {RoleOwner, RoleAdmin, RoleManager, RoleRecruiter}, 85 CapSourcingRead: {RoleOwner, RoleAdmin, RoleManager, RoleRecruiter}, 86 // A team lead moves work between people. This is the whole reason the tier exists, and it is 87 // deliberately the ONLY authority manager holds that recruiter does not, besides reading the audit 88 // trail for the team they are accountable for. 89 CapDeskReassign: {RoleOwner, RoleAdmin, RoleManager}, 90 CapAuditRead: {RoleOwner, RoleAdmin, RoleManager}, 91 // Everything below stays at admin and above. A manager who could erase a candidate or change an 92 // account's role would be an admin with a different name, and the tier would buy nothing. 93 CapPrivacyErase: {RoleOwner, RoleAdmin}, 94 CapUserInvite: {RoleOwner, RoleAdmin}, 95 CapUserRoleChange: {RoleOwner, RoleAdmin}, 96 CapUserDisable: {RoleOwner, RoleAdmin}, 97 CapComplianceRead: {RoleOwner, RoleAdmin}, 98 CapComplianceWrite: {RoleOwner, RoleAdmin}, 99 // Curation writes the GLOBAL skill ontology, which every tenant's scoring reads. It is therefore a 100 // platform operator action, not a tenant administrator one, and superuser is the only tier that is 101 // platform wide. 102 // 103 // It used to be {RoleOwner, RoleAdmin}, held by the owner and admin of EVERY tenant, while 104 // curation_proposals carries no organization_id and the approve and verify path reads proposals by 105 // bare primary key on the BYPASSRLS migrator pool. Any tenant's admin could therefore approve a 106 // proposal derived from another tenant's data, and a second admin IN THE SAME TENANT could verify it, 107 // since the separation of duties check only compares two user ids and never requires them to be in 108 // different organizations. The result is a live skill_relationships edge that alters match scores for 109 // everyone. Where tenants are competing primes bidding the same solicitations, that is a cross tenant 110 // integrity primitive, not a permissions nicety. 111 CapCurationCurate: {RoleSuperuser}, 112 CapOrgSettings: {RoleOwner}, 113} 114 115// capabilitySet is the matrix indexed for O(1) lookup, built once at init. 116var capabilitySet = func() map[Role]map[Capability]bool { 117 // Built from roleRank rather than from a second hand written role list. The literal that used to be 118 // here omitted superuser, so the first capability assigned to that role wrote to a nil map and PANICKED 119 // AT INIT, taking the binary down at boot rather than failing a request. Deriving the keys from the 120 // rank table means a role added there can never be missing here. 121 set := make(map[Role]map[Capability]bool, len(roleRank)) 122 for role := range roleRank { 123 set[role] = map[Capability]bool{} 124 } 125 for cap, roles := range capabilityRoles { 126 for _, role := range roles { 127 set[role][cap] = true 128 } 129 } 130 return set 131}() 132 133// ValidRole reports whether role is one of the six known roles. 134func ValidRole(role Role) bool { 135 _, ok := roleRank[role] 136 return ok 137} 138 139// Has reports whether role holds the capability. 140func Has(role Role, cap Capability) bool { 141 // Superuser holds every capability, resolved here rather than by adding RoleSuperuser to all 142 // nineteen rows of the matrix. Enumerating it would mean a capability added later silently omits the 143 // tier that is supposed to hold everything, and the omission would present as an unexplained refusal 144 // for the one account expected never to be refused. Owner remains explicitly enumerated, so the 145 // matrix still reads as the authority on every tier that is not the top. 146 if role == RoleSuperuser { 147 return cap != "" 148 } 149 caps, ok := capabilitySet[role] 150 if !ok { 151 return false 152 } 153 return caps[cap] 154} 155 156// AtLeast reports whether role is at or above min in the hierarchy. Unknown roles are never at least 157// anything. 158func AtLeast(role, min Role) bool { 159 r, ok := roleRank[role] 160 if !ok { 161 return false 162 } 163 m, ok := roleRank[min] 164 if !ok { 165 return false 166 } 167 return r >= m 168} 169 170// OutRanks reports whether actor is strictly more privileged than other. It is the core separation of 171// duties predicate: a user may only invite, role change, disable, or reset the MFA of someone they 172// outrank, never a peer or a superior, and never themselves. 173func OutRanks(actor, other Role) bool { 174 a, ok := roleRank[actor] 175 if !ok { 176 return false 177 } 178 o, ok := roleRank[other] 179 if !ok { 180 return false 181 } 182 return a > o 183} 184 185// CanGrantRole reports whether an actor may put another account into the given role, whether by invite 186// or by changing an existing user's role. Both paths MUST use this, or the two disagree and the weaker 187// one becomes the way around the stronger. 188// 189// The rule is: strictly below your own, with exactly one exception. 190// 191// The exception is superuser granting superuser. Every other tier is deliberately unable to reproduce 192// itself, which is what stops an admin quietly building a bench of admins. Applied to the top of the 193// ladder that same rule is a trap rather than a control: if no role can create a superuser, the tier can 194// only ever shrink, and an organization that loses its last holder is locked out of its own access 195// control with no in application recovery. Someone has to be able to mint the top tier, and the least 196// dangerous answer is that only the top tier can. It is a small, named group granting to each other, it 197// is audited like any other role change, and an actor still cannot change their OWN role, so no single 198// superuser can act alone on their own account. 199func CanGrantRole(actor, granted Role) bool { 200 if actor == RoleSuperuser && granted == RoleSuperuser { 201 return true 202 } 203 return OutRanks(actor, granted) 204} 205 206// CanInvite reports whether an actor may invite a user with the given role. It defers to CanGrantRole so 207// an invitation can never confer a role that a direct role change would refuse. 208func CanInvite(actor, invited Role) bool { return CanGrantRole(actor, invited) } 209 210// CapabilitiesOf returns every capability a role holds, sorted, for sending to a client. 211// 212// Derived from the same matrix Has consults, so the list a browser receives and the checks the server 213// performs cannot disagree. Sorted so the response is stable and diffable, and so a test can compare it 214// without ordering noise. 215func CapabilitiesOf(role Role) []string { 216 // Superuser holds everything, so it reports the full vocabulary rather than a matrix row it has none 217 // of. Derived from capabilityRoles, the same source Has consults, so the two cannot drift. 218 if role == RoleSuperuser { 219 out := make([]string, 0, len(capabilityRoles)) 220 for c := range capabilityRoles { 221 out = append(out, string(c)) 222 } 223 sort.Strings(out) 224 return out 225 } 226 caps, ok := capabilitySet[role] 227 if !ok { 228 return []string{} 229 } 230 out := make([]string, 0, len(caps)) 231 for c := range caps { 232 out = append(out, string(c)) 233 } 234 sort.Strings(out) 235 return out 236} 237