Janady13/missionmatch / internal/platform/tenant/tenant.go

1// Package tenant is the multi-tenancy correctness boundary. 2// 3// Tenant isolation is enforced by Postgres Row-Level Security, NOT by Go WHERE clauses. Every 4// tenant-scoped request runs inside a transaction whose `app.current_org_id` GUC is set 5// transaction-locally, so Postgres discards it at COMMIT/ROLLBACK and it can never leak to the next 6// request that reuses a pooled connection (the pgx-pool gotcha, see docs/STACK_DECISIONS.md §2). 7// 8// Two safeguards stack here: 9// - Go side: no validated org in context => RunInTenantTx refuses to run (fail closed). 10// - DB side: an unset GUC makes current_setting(...,true) NULL, so the RLS policy matches zero 11// rows (default deny). 12// 13// The org id MUST originate from a verified session/JWT claim resolved by auth middleware, never 14// from a client-supplied body, header, or query parameter. 15package tenant 16 17import ( 18 "context" 19 "errors" 20 "fmt" 21 "net/http" 22 23 "github.com/google/uuid" 24 "github.com/jackc/pgx/v5" 25 "github.com/jackc/pgx/v5/pgxpool" 26) 27 28// ErrNoTenant is returned when tenant-scoped DB work is attempted without a validated organization. 29var ErrNoTenant = errors.New("tenant: no organization_id in context (refusing to run unscoped query)") 30 31// ctxKey is an unexported context key so a client cannot spoof the org via a context-key collision. 32type ctxKey struct{} 33 34var orgKey = ctxKey{} 35 36// WithOrg stores the validated org id in ctx. Call this ONLY from auth middleware, with a value 37// taken from verified claims. 38func WithOrg(ctx context.Context, orgID string) context.Context { 39 return context.WithValue(ctx, orgKey, orgID) 40} 41 42// OrgFromContext returns the validated org id and whether a non-empty one is present. 43func OrgFromContext(ctx context.Context) (string, bool) { 44 v, ok := ctx.Value(orgKey).(string) 45 return v, ok && v != "" 46} 47 48// principalCtxKey is a SEPARATE key type from ctxKey. Reusing ctxKey for the user would collide with 49// orgKey, because every empty struct value of the same type is equal, so the two context lookups 50// would return each other's value. A distinct type keeps the org and the principal independent. 51type principalCtxKey struct{} 52 53var principalKey = principalCtxKey{} 54 55// Principal is the authenticated actor resolved from a validated session: the user id and the role 56// used for authorization. Like the org, it MUST originate from auth middleware reading verified 57// session state, never a client supplied value. 58type Principal struct { 59 UserID string 60 Role string 61 // Tools is the granted product set (missionmatch, screenmatch, slatematch, recruitmatch) resolved 62 // with the session. It rides on the principal so the per tool API gate is a context read rather than 63 // a database round trip on every request, and so a change to entitlement takes effect on the next 64 // session resolve rather than being cached indefinitely. 65 // 66 // Empty means entitled to nothing, which is the intended fail closed default; it is never a signal 67 // that the set was simply not loaded. 68 Tools []string 69} 70 71// WithUser stores the validated principal in ctx. Call this ONLY from auth middleware. 72func WithUser(ctx context.Context, p Principal) context.Context { 73 return context.WithValue(ctx, principalKey, p) 74} 75 76// UserFromContext returns the validated principal and whether one with a non-empty user id is 77// present. 78func UserFromContext(ctx context.Context) (Principal, bool) { 79 p, ok := ctx.Value(principalKey).(Principal) 80 return p, ok && p.UserID != "" 81} 82 83// Router resolves the leaf tenant DB for an organization under the database per tenant model: it 84// acquires that tenant's own pool plus a release the caller must invoke. The per tenant pool manager 85// satisfies it. A DB with a nil router is shared mode, where every request uses the one static Pool and 86// isolation rests entirely on Row Level Security. With a router the DB is per tenant mode, where each 87// request physically routes to its own tenant's database and RLS becomes defense in depth. 88type Router interface { 89 Acquire(ctx context.Context, org uuid.UUID) (*DB, func(), error) 90} 91 92// DB wraps either a single pgxpool.Pool (shared mode, authenticating as the NOBYPASSRLS application 93// role) or a Router (per tenant mode) that resolves the request's tenant pool. Pool is nil in per 94// tenant mode. 95type DB struct { 96 Pool *pgxpool.Pool 97 router Router 98} 99 100// New wraps a pool as a tenant-scoped DB: shared mode, or a leaf tenant DB the manager hands back. 101func New(pool *pgxpool.Pool) *DB { return &DB{Pool: pool} } 102 103// NewRouting builds a routing DB with no static pool: every access resolves the caller's tenant 104// database from the router using the validated org in context. This is how per tenant mode reaches 105// tenant data while leaving every handler and every RunInTenantTx call site unchanged. 106func NewRouting(r Router) *DB { return &DB{router: r} } 107 108// Ready reports whether this DB can reach a database at all. It is the ONLY correct way for a service to 109// ask "am I configured", and services must not test Pool themselves. 110// 111// Pool is nil BY DESIGN in per tenant mode, where the database is resolved per request through the 112// router. Roughly twenty services were written against `db.Pool == nil` as a stand in for "no database 113// configured" and returned 503 before ever calling RunInTenantTx, which would have routed correctly. The 114// effect was that enabling per tenant routing permanently disabled the audit trail, adverse impact 115// reporting, governance, alerts, sourcing, awards, wages, and both opportunity surfaces, while the boot 116// log cheerfully reported the routed compliance pool as active. The routing layer worked; the guard in 117// front of it did not know routing existed. 118func (db *DB) Ready() bool { return db != nil && (db.Pool != nil || db.router != nil) } 119 120// Close releases the underlying pool. It is a no op for a routing DB, because the manager owns the 121// tenant pools and closing one here would pull it out from under other in flight requests. 122func (db *DB) Close() { 123 if db.Pool != nil { 124 db.Pool.Close() 125 } 126} 127 128// resolveLeaf returns the DB to actually run against for this request plus a release the caller MUST 129// invoke. In shared mode that is the DB itself with a no op release. In per tenant mode it acquires the 130// tenant's leaf DB by the validated org in context, failing closed when there is no validated org so a 131// request without one still reaches zero data rather than an arbitrary tenant. 132func (db *DB) resolveLeaf(ctx context.Context) (*DB, func(), error) { 133 if db.router == nil { 134 return db, func() {}, nil 135 } 136 orgStr, ok := OrgFromContext(ctx) 137 if !ok { 138 return nil, nil, ErrNoTenant 139 } 140 org, err := uuid.Parse(orgStr) 141 if err != nil { 142 return nil, nil, ErrNoTenant 143 } 144 return db.router.Acquire(ctx, org) 145} 146 147// Acquire exposes the request's leaf DB, and a release the caller MUST invoke, for the readers that 148// touch a pool directly rather than going through RunInTenantTx: the global reference catalog reads and 149// the stored skill matcher. In shared mode it is a no op wrapper over the single pool; in per tenant 150// mode it routes to the tenant's own database. 151func (db *DB) Acquire(ctx context.Context) (*DB, func(), error) { return db.resolveLeaf(ctx) } 152 153// RunInTenantTx is THE correctness boundary. It: 154// 1. requires a validated org id (fail-closed: no org => no query, before the pool is touched), 155// 2. opens a transaction on a single pooled connection, 156// 3. sets app.current_org_id transaction-locally via set_config(..., is_local=true) so it 157// auto-resets at COMMIT/ROLLBACK and cannot leak across the pool, 158// 4. runs fn against that same tx, then commits (rolling back on any error). 159// 160// All tenant-scoped repository work MUST go through this method. 161func (db *DB) RunInTenantTx(ctx context.Context, fn func(ctx context.Context, tx pgx.Tx) error) (err error) { 162 orgID, ok := OrgFromContext(ctx) 163 if !ok { 164 return ErrNoTenant 165 } 166 167 // In per tenant mode this routes to the org's own database, and refuses without a validated org. In 168 // shared mode leaf is this DB and release is a no op. The org GUC is still set below either way, so 169 // RLS stays armed inside the tenant database as defense in depth rather than as the only barrier. 170 leaf, release, err := db.resolveLeaf(ctx) 171 if err != nil { 172 return err 173 } 174 defer release() 175 if leaf.Pool == nil { 176 return ErrNoTenant 177 } 178 179 tx, err := leaf.Pool.Begin(ctx) 180 if err != nil { 181 return fmt.Errorf("begin tenant tx: %w", err) 182 } 183 // Rollback is a no-op once Commit succeeds; this guarantees the connection is released on every path. 184 defer func() { _ = tx.Rollback(ctx) }() 185 186 // Transaction-local GUC, parameterized (no SQL-injection surface). is_local=true is what makes 187 // this safe on a pooled connection. 188 if _, err = tx.Exec(ctx, "SELECT set_config('app.current_org_id', $1, true)", orgID); err != nil { 189 return fmt.Errorf("set tenant guc: %w", err) 190 } 191 192 if err = fn(ctx, tx); err != nil { 193 return err // defer rolls back 194 } 195 if err = tx.Commit(ctx); err != nil { 196 return fmt.Errorf("commit tenant tx: %w", err) 197 } 198 return nil 199} 200 201// Middleware resolves the org id from an already-validated request and stores it in context. 202// resolveOrg MUST read verified session/JWT claims, never a raw client value. A request whose org 203// cannot be resolved is rejected with 403 before any downstream handler runs. 204func Middleware(resolveOrg func(*http.Request) (string, bool)) func(http.Handler) http.Handler { 205 return func(next http.Handler) http.Handler { 206 return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { 207 orgID, ok := resolveOrg(r) 208 if !ok { 209 http.Error(w, "forbidden", http.StatusForbidden) 210 return 211 } 212 next.ServeHTTP(w, r.WithContext(WithOrg(r.Context(), orgID))) 213 }) 214 } 215} 216