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} 62 63// WithUser stores the validated principal in ctx. Call this ONLY from auth middleware. 64func WithUser(ctx context.Context, p Principal) context.Context { 65 return context.WithValue(ctx, principalKey, p) 66} 67 68// UserFromContext returns the validated principal and whether one with a non-empty user id is 69// present. 70func UserFromContext(ctx context.Context) (Principal, bool) { 71 p, ok := ctx.Value(principalKey).(Principal) 72 return p, ok && p.UserID != "" 73} 74 75// Router resolves the leaf tenant DB for an organization in the database per tenant model: it acquires 76// that tenant's own pool (and a release the caller must invoke). The per tenant pool manager satisfies 77// it. A DB with a nil router is shared mode, where every request uses the one static Pool and tenant 78// isolation is Row Level Security; with a router the DB is per_tenant mode, where each request physically 79// routes to its tenant's database and RLS is defense in depth. 80type Router interface { 81 Acquire(ctx context.Context, org uuid.UUID) (*DB, func(), error) 82} 83 84// DB wraps either a single pgxpool.Pool (shared mode, authenticating as the NOBYPASSRLS application role) 85// or a Router (per_tenant mode) that resolves the request's tenant pool. Pool is nil in per_tenant mode. 86type DB struct { 87 Pool *pgxpool.Pool 88 router Router 89} 90 91// New wraps a pool as a tenant-scoped DB (shared mode, or a leaf tenant DB the manager hands back). 92func New(pool *pgxpool.Pool) *DB { return &DB{Pool: pool} } 93 94// NewRouting builds a routing DB with no static pool: every access resolves the caller's tenant database 95// from the router using the validated org in context. This is how per_tenant mode reaches tenant data 96// while keeping every handler and RunInTenantTx call site unchanged. 97func NewRouting(r Router) *DB { return &DB{router: r} } 98 99// Close releases the underlying pool (a no op for a routing DB; the manager owns the tenant pools). 100func (db *DB) Close() { 101 if db.Pool != nil { 102 db.Pool.Close() 103 } 104} 105 106// resolveLeaf returns the DB to actually run against for this request plus a release the caller MUST 107// invoke. In shared mode it is the DB itself (no op release). In per_tenant mode it acquires the tenant's 108// leaf DB by the validated org in context (fail closed when there is no validated org, so a request with 109// no org still reaches zero data). 110func (db *DB) resolveLeaf(ctx context.Context) (*DB, func(), error) { 111 if db.router == nil { 112 return db, func() {}, nil 113 } 114 orgStr, ok := OrgFromContext(ctx) 115 if !ok { 116 return nil, nil, ErrNoTenant 117 } 118 org, err := uuid.Parse(orgStr) 119 if err != nil { 120 return nil, nil, ErrNoTenant 121 } 122 return db.router.Acquire(ctx, org) 123} 124 125// Acquire exposes the request's leaf DB (and a release the caller MUST invoke) for the readers that touch 126// a pool directly: the global reference catalog reads and the stored skill matcher. In shared mode it is 127// a no op wrapper over the single pool; in per_tenant mode it routes to the tenant's own database. 128func (db *DB) Acquire(ctx context.Context) (*DB, func(), error) { return db.resolveLeaf(ctx) } 129 130// RunInTenantTx is THE correctness boundary. It: 131// 1. requires a validated org id (fail-closed: no org => no query, before the pool is touched), 132// 2. opens a transaction on a single pooled connection, 133// 3. sets app.current_org_id transaction-locally via set_config(..., is_local=true) so it 134// auto-resets at COMMIT/ROLLBACK and cannot leak across the pool, 135// 4. runs fn against that same tx, then commits (rolling back on any error). 136// 137// All tenant-scoped repository work MUST go through this method. 138func (db *DB) RunInTenantTx(ctx context.Context, fn func(ctx context.Context, tx pgx.Tx) error) (err error) { 139 orgID, ok := OrgFromContext(ctx) 140 if !ok { 141 return ErrNoTenant 142 } 143 // In per_tenant mode this routes to the org's own database (and refuses without a validated org); 144 // in shared mode leaf is this DB and release is a no op. The org GUC is still set below either way, 145 // so RLS stays armed as defense in depth inside the tenant database. 146 leaf, release, err := db.resolveLeaf(ctx) 147 if err != nil { 148 return err 149 } 150 defer release() 151 if leaf.Pool == nil { 152 return ErrNoTenant 153 } 154 155 tx, err := leaf.Pool.Begin(ctx) 156 if err != nil { 157 return fmt.Errorf("begin tenant tx: %w", err) 158 } 159 // Rollback is a no-op once Commit succeeds; this guarantees the connection is released on every path. 160 defer func() { _ = tx.Rollback(ctx) }() 161 162 // Transaction-local GUC, parameterized (no SQL-injection surface). is_local=true is what makes 163 // this safe on a pooled connection. 164 if _, err = tx.Exec(ctx, "SELECT set_config('app.current_org_id', $1, true)", orgID); err != nil { 165 return fmt.Errorf("set tenant guc: %w", err) 166 } 167 168 if err = fn(ctx, tx); err != nil { 169 return err // defer rolls back 170 } 171 if err = tx.Commit(ctx); err != nil { 172 return fmt.Errorf("commit tenant tx: %w", err) 173 } 174 return nil 175} 176 177// Middleware resolves the org id from an already-validated request and stores it in context. 178// resolveOrg MUST read verified session/JWT claims, never a raw client value. A request whose org 179// cannot be resolved is rejected with 403 before any downstream handler runs. 180func Middleware(resolveOrg func(*http.Request) (string, bool)) func(http.Handler) http.Handler { 181 return func(next http.Handler) http.Handler { 182 return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { 183 orgID, ok := resolveOrg(r) 184 if !ok { 185 http.Error(w, "forbidden", http.StatusForbidden) 186 return 187 } 188 next.ServeHTTP(w, r.WithContext(WithOrg(r.Context(), orgID))) 189 }) 190 } 191} 192