Janady13/missionmatch / internal/platform/orgsettings/scope.go

1package orgsettings 2 3// RESOLVING A RECORD SCOPE INTO A PREDICATE. 4// 5// security.ResolveRecordScope decides WHICH scope a caller has, purely, with no database. This turns that 6// answer into the set of owners the caller may see, and into the SQL fragment a list query appends. 7// 8// IT IS ONE FUNCTION ON PURPOSE. The alternative, letting each module work out its own owner predicate, is 9// how a product ends up with six list endpoints that agree and a seventh that quietly does not, and the 10// seventh is the one that shows a recruiter the whole floor. 11// 12// THE FRAGMENT IS BUILT HERE, NEVER BY THE CALLER. A caller passes the column name and receives finished SQL 13// plus its argument. The column name is checked against a bare identifier rule before it is interpolated, 14// because a column name is the one thing in this path that is not a bound parameter. 15 16import ( 17 "context" 18 "errors" 19 "fmt" 20 21 "github.com/google/uuid" 22 "github.com/jackc/pgx/v5" 23 24 "github.com/missionworkforce/missionmatch/internal/platform/security" 25 "github.com/missionworkforce/missionmatch/internal/platform/tenant" 26) 27 28// Filter is a resolved record scope: who the caller may see, and whether records nobody owns count. 29type Filter struct { 30 Scope security.RecordScope 31 // OwnerIDs is the set of owning users whose records are visible. It is nil when the scope is 32 // organization wide, which is the case that needs no predicate at all. 33 OwnerIDs []uuid.UUID 34 // IncludeUnowned reports whether a record with a NULL owner is visible. It defaults to true, because an 35 // unowned candidate that nobody can see is a candidate nobody will ever work. 36 IncludeUnowned bool 37} 38 39// Unrestricted reports that no owner predicate is needed. 40func (f Filter) Unrestricted() bool { return f.Scope.Unrestricted() } 41 42// ResolveScopeTx works out the caller's filter inside an existing tenant transaction. 43func (s *Store) ResolveScopeTx(ctx context.Context, tx pgx.Tx) (Filter, error) { 44 p, ok := tenant.UserFromContext(ctx) 45 if !ok { 46 // NO PRINCIPAL MEANS NOTHING IS VISIBLE, matching the tenancy rule that no context yields zero rows. 47 // Returning an unrestricted filter here would be the single worst bug this file could contain. 48 return Filter{Scope: security.ScopeOwn, OwnerIDs: []uuid.UUID{}, IncludeUnowned: false}, nil 49 } 50 actorID, err := uuid.Parse(p.UserID) 51 if err != nil { 52 return Filter{Scope: security.ScopeOwn, OwnerIDs: []uuid.UUID{}, IncludeUnowned: false}, nil 53 } 54 st, err := s.LoadTx(ctx, tx) 55 if err != nil { 56 return Filter{}, err 57 } 58 scope := security.ResolveRecordScope(security.Role(p.Role), st.StaffRecordScope, st.ManagerRecordScope) 59 f := Filter{Scope: scope, IncludeUnowned: st.UnownedRecordsVisible} 60 switch scope { 61 case security.ScopeOrganization: 62 return f, nil 63 case security.ScopeOwn: 64 f.OwnerIDs = []uuid.UUID{actorID} 65 return f, nil 66 case security.ScopeTeam: 67 rows, err := tx.Query(ctx, `SELECT user_id FROM mm_team_peer_ids($1)`, actorID) 68 if err != nil { 69 return Filter{}, fmt.Errorf("orgsettings: resolve team peers: %w", err) 70 } 71 defer rows.Close() 72 for rows.Next() { 73 var id uuid.UUID 74 if err := rows.Scan(&id); err != nil { 75 return Filter{}, err 76 } 77 f.OwnerIDs = append(f.OwnerIDs, id) 78 } 79 if rows.Err() != nil { 80 return Filter{}, rows.Err() 81 } 82 // The resolver already includes the caller, but a belt on the braces costs nothing and protects 83 // against somebody rewriting that function later: a person on no team must always see their own work. 84 if len(f.OwnerIDs) == 0 { 85 f.OwnerIDs = []uuid.UUID{actorID} 86 } 87 return f, nil 88 default: 89 // Unreachable, because ResolveRecordScope only returns the three above. Narrowest answer anyway. 90 f.Scope, f.OwnerIDs, f.IncludeUnowned = security.ScopeOwn, []uuid.UUID{actorID}, false 91 return f, nil 92 } 93} 94 95// ResolveScope opens its own transaction for callers not already inside one. 96func (s *Store) ResolveScope(ctx context.Context) (Filter, error) { 97 var out Filter 98 err := s.db.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error { 99 var e error 100 out, e = s.ResolveScopeTx(ctx, tx) 101 return e 102 }) 103 return out, err 104} 105 106var errBadColumn = errors.New("orgsettings: an owner column must be a bare lowercase identifier") 107 108// SQL returns a predicate to AND into a list query, plus the argument it binds. 109// 110// nextArg is the position the caller's next placeholder would take, so this composes with a query that 111// already has parameters. An unrestricted filter returns an empty string and no argument, so the caller 112// appends nothing. 113// 114// The column is validated rather than trusted. It is the only part of this that is not a bound parameter. 115func (f Filter) SQL(column string, nextArg int) (string, []any, error) { 116 if f.Unrestricted() { 117 return "", nil, nil 118 } 119 if column == "" { 120 return "", nil, errBadColumn 121 } 122 for _, r := range column { 123 if (r < 'a' || r > 'z') && r != '_' && (r < '0' || r > '9') { 124 return "", nil, errBadColumn 125 } 126 } 127 // An empty owner set with no unowned records visible means NOTHING is visible. Expressed as a literal 128 // false rather than an empty ANY, because "= ANY('{}')" is subtly not false for a NULL column and this 129 // must be unambiguous. 130 if len(f.OwnerIDs) == 0 && !f.IncludeUnowned { 131 return "false", nil, nil 132 } 133 if len(f.OwnerIDs) == 0 { 134 return fmt.Sprintf("%s IS NULL", column), nil, nil 135 } 136 if f.IncludeUnowned { 137 return fmt.Sprintf("(%s = ANY($%d) OR %s IS NULL)", column, nextArg, column), []any{f.OwnerIDs}, nil 138 } 139 return fmt.Sprintf("%s = ANY($%d)", column, nextArg), []any{f.OwnerIDs}, nil 140} 141 142// Allows reports whether one record's owner is visible under this filter. Used on single record reads, where 143// building SQL would be heavier than answering directly. 144func (f Filter) Allows(owner *uuid.UUID) bool { 145 if f.Unrestricted() { 146 return true 147 } 148 if owner == nil { 149 return f.IncludeUnowned 150 } 151 for _, id := range f.OwnerIDs { 152 if id == *owner { 153 return true 154 } 155 } 156 return false 157} 158