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

1package security 2 3import ( 4 "net/http" 5 "sort" 6 7 "github.com/missionworkforce/missionmatch/internal/platform/tenant" 8) 9 10// Tool entitlement: what a person may SEE, kept separate from what they may DO. 11// 12// Role answers authority: may this person edit a requirement, run an export, disable an account. Tool 13// answers surface: does recruitMATCH appear for them at all. The two are genuinely independent, and 14// collapsing them would be wrong in both directions. One client's recruiter works only recruitMATCH and 15// slateMATCH while another's sees every product, and that is not a difference in authority, so it must 16// not be expressed by giving one of them a different role. Equally, hiding a tool must never be mistaken 17// for removing authority: a user with recruitMATCH hidden but CapCandidateWrite still held is refused by 18// the tool gate, not by the capability check, and the refusal has to be the tool's. 19// 20// Entitlement is per user and explicit. Absence of a grant is absence of access, in the API and in the 21// interface, so an account created without grants sees nothing rather than everything. The opposite 22// default fails toward silent over exposure of a whole product to someone who was never meant to have it. 23 24// Tool is one of the four products. The vocabulary is closed and matches the CHECK constraint on 25// user_tool_access, so a value that would be refused by the database is refused here first. 26type Tool string 27 28const ( 29 ToolMissionMatch Tool = "missionmatch" 30 ToolScreenMatch Tool = "screenmatch" 31 ToolSlateMatch Tool = "slatematch" 32 ToolRecruitMatch Tool = "recruitmatch" 33) 34 35// AllTools is the full vocabulary, in the order the navigation presents them. 36var AllTools = []Tool{ToolMissionMatch, ToolScreenMatch, ToolSlateMatch, ToolRecruitMatch} 37 38// ValidTool reports whether a string names a real tool. Used before any write, so an unknown value is a 39// 400 from the service rather than a constraint violation surfacing as a 500. 40func ValidTool(s string) bool { 41 for _, t := range AllTools { 42 if Tool(s) == t { 43 return true 44 } 45 } 46 return false 47} 48 49// ToolsOf normalizes a raw list into a sorted, deduplicated, valid set. Unknown values are DROPPED 50// rather than causing a failure, because this runs on the read path when turning stored rows into a 51// principal: a tool retired from the vocabulary while still present in old rows must degrade to that 52// tool being invisible, not to the user being unable to log in. 53func ToolsOf(raw []string) []string { 54 seen := make(map[string]bool, len(raw)) 55 out := make([]string, 0, len(raw)) 56 for _, s := range raw { 57 if !ValidTool(s) || seen[s] { 58 continue 59 } 60 seen[s] = true 61 out = append(out, s) 62 } 63 sort.Strings(out) 64 return out 65} 66 67// HasTool reports whether a principal's granted set includes a tool. Superuser is NOT special cased 68// here, deliberately: entitlement is data, and a superuser whose grants were narrowed should see the 69// narrowing rather than silently override it. The service grants a superuser every tool at creation, so 70// the common case is covered by the data being right rather than by an exception in the check. 71func HasTool(granted []string, want Tool) bool { 72 for _, g := range granted { 73 if Tool(g) == want { 74 return true 75 } 76 } 77 return false 78} 79 80// CanGrantTools reports whether an actor may change another user's tool entitlement, and is the tool 81// analogue of CanGrantRole. Two conditions, both required: 82// 83// 1. The actor must outrank the target. Same separation of duties as roles: nobody edits a peer's or a 84// superior's access, and nobody edits their own. 85// 2. The actor may only grant tools they themselves hold. Without this an admin entitled to two tools 86// could grant themselves a third by way of an account they control, so the ceiling on what an actor 87// can spread is what they already have. 88// 89// Revocation is bounded by the first condition only: an actor may remove any tool from someone they 90// outrank, including one the actor does not hold, because taking access away is the safe direction. 91func CanGrantTools(actorRole, targetRole Role, actorTools, wantTools []string) bool { 92 if !OutRanks(actorRole, targetRole) { 93 return false 94 } 95 return CanConferTools(actorTools, wantTools) 96} 97 98// CanConferTools is the POSSESSION half on its own: may this actor hand out these tools at all, setting 99// aside who the recipient is. 100// 101// It exists because the two halves answer to different authorities and one caller only needs the second. 102// On an INVITE, whether the actor may create an account at that role has already been decided by 103// CanGrantRole, which permits the one case OutRanks does not: a superuser creating another superuser. 104// Routing an invite through CanGrantTools would re impose strict outranking on top of that decision and 105// refuse the tools for an account the actor was just authorized to create, so the invitation fails as a 106// 403 with the role permitted and the entitlement denied. That is not a stricter policy, it is two rules 107// disagreeing. 108// 109// Editing an EXISTING user still goes through CanGrantTools, because there the outranking condition is 110// doing real work: it is what stops an actor rewriting a peer's or a superior's access. 111func CanConferTools(actorTools, wantTools []string) bool { 112 for _, w := range wantTools { 113 if !ValidTool(w) { 114 return false 115 } 116 if !HasTool(actorTools, Tool(w)) { 117 return false 118 } 119 } 120 return true 121} 122 123// RequireTool is the API side gate for a product surface. It is the enforcement that matters: hiding a 124// route in the navigation is a presentation choice, and a user who keeps a bookmark, or who reads the 125// bundle, reaches the same handler. Mounting this on the tool's route group means the entitlement is 126// enforced once, at the boundary, for every endpoint the tool owns including ones added later. 127// 128// It refuses with 404 rather than 403. A tool the caller is not entitled to should not be distinguishable 129// from a tool that does not exist: a 403 confirms the surface is real and tells an unentitled account 130// exactly which products the organization has bought. 131func RequireTool(tool Tool) func(http.Handler) http.Handler { 132 return func(next http.Handler) http.Handler { 133 return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { 134 p, ok := tenant.UserFromContext(r.Context()) 135 if !ok || !HasTool(p.Tools, tool) { 136 w.Header().Set("Content-Type", "application/json") 137 w.WriteHeader(http.StatusNotFound) 138 _, _ = w.Write([]byte(`{"error":{"code":"not_found","message":"not found"}}`)) 139 return 140 } 141 next.ServeHTTP(w, r) 142 }) 143 } 144} 145 146// RequireAnyTool gates a surface on holding AT LEAST ONE of the given tools. It exists for the shared 147// readers (the candidate and requirement pickers) that every product needs: gating them to a single tool 148// would break the other three, and leaving them ungated would expose the candidate list to an account 149// entitled to nothing at all. Same 404 posture as RequireTool, for the same reason. 150func RequireAnyTool(tools ...Tool) func(http.Handler) http.Handler { 151 return func(next http.Handler) http.Handler { 152 return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { 153 p, ok := tenant.UserFromContext(r.Context()) 154 if ok { 155 for _, t := range tools { 156 if HasTool(p.Tools, t) { 157 next.ServeHTTP(w, r) 158 return 159 } 160 } 161 } 162 w.Header().Set("Content-Type", "application/json") 163 w.WriteHeader(http.StatusNotFound) 164 _, _ = w.Write([]byte(`{"error":{"code":"not_found","message":"not found"}}`)) 165 }) 166 } 167} 168