Public: anyone can read this; nobody can change it.

workbenchthis machine

RBAC-7: DESIGN Forgejo-identity -> per-app postgres role/RLS (design only) #55

Merged opened this view on origin

Check · Review · Land done · Live — Landed; nothing deploys from this branch, so this is the end of its path.

Merged

feat/rbac-7-postgres-rls-design → main 1 commit

  • Merged. feat/rbac-7-postgres-rls-design was merged into main.

Review

Sign in to review this change.
1 file changed +245 −0
docs/design/forgejo-identity-to-postgres-rbac.md added +245
@@ -0,0 +1,245 @@
1 # DESIGN: Forgejo identity → per-app Postgres role / RLS propagation (RBAC-7)
2
3 **Status:** design only — no code changes. **Recommendation:** **DEFER** for the
4 single-client / early-stage platform (see [Recommendation](#recommendation)).
5
6 The RBAC vision is "propagate Forgejo identity everywhere." The edge is done
7 (RBAC-2 forwardAuth gates the whole app by Forgejo team). The Postgres leg has no
8 design: today CNPG provisions **one flat credential** with no link to Forgejo
9 teams, and better-auth stores _application_ users in that same database. This doc
10 decides whether the Postgres layer needs per-team roles / row-level security
11 (RLS) at all, and if so, specifies the mapping so a future agent can build it
12 without re-deciding.
13
14 ---
15
16 ## Problem
17
18 Trace one HTTP request from browser to a row:
19
20 1. **Edge (RBAC-2).** A Traefik `forwardAuth` middleware checks the caller's
21 Forgejo session/team membership and allows or blocks the request to the app.
22 This is coarse: it gates the **whole app** ("are you allowed to reach
23 `blog.acme.plat`?"), not individual rows or tables. _(RBAC-2 is landing in
24 this wave; there is no forwardAuth code in `mcp/src/server.ts` yet — this
25 design assumes its edge-gate semantics.)_
26 2. **App identity (better-auth).** The app authenticates the end user via Forgejo
27 OAuth and stores them in its own tables — `"user"`, `"session"`, `"account"`,
28 `"verification"` (`_app-template/src/auth.ts:70`). The app-level user id is
29 Forgejo's `sub`/`id` (`_app-template/src/auth.ts:181`). This is the _product's_
30 notion of a user, distinct from the _platform's_ Forgejo team RBAC.
31 3. **Database (today).** The app connects to its per-app CNPG Postgres as **one
32 role** — the database owner `${name}`, auto-generated with the database at
33 `mcp/src/server.ts:2328` (`bootstrap.initdb: { database: ${name}, owner:
34 ${name} }`). CNPG hands the app the `${name}-pg-app` Secret
35 (`mcp/src/server.ts:2302`) which the chart injects via `extraEnvFrom`
36 (`mcp/src/server.ts:2434`); the app reads discrete `host/user/password/dbname`
37 keys (`_app-template/src/auth.ts:39`). **Every query runs as the same
38 role.** There is no per-Forgejo-team Postgres role, no RLS, no `SET ROLE`.
39
40 So the question RBAC-7 must answer: **does the row layer need its own identity
41 propagation, given the edge already gates the whole app?**
42
43 ### The two things "Postgres RBAC" could mean
44
45 These are constantly conflated; the design separates them.
46
47 - **(A) Platform-tenant isolation — already solved.** Keeping app _X_ out of app
48 _Y_'s database. This is done structurally: a **separate CNPG cluster per app**
49 in the app's own namespace (`mcp/src/server.ts:2312`), reached only intra-
50 namespace, with NetworkPolicies fencing cross-namespace access
51 (`mcp/src/server.ts:2345`–`2402`). App _X_ has no credential, route, or network
52 path to app _Y_'s Postgres. **No per-team role is needed for this;** the
53 boundary is the cluster + namespace, not a SQL grant.
54 - **(B) Intra-app, sub-user authorization — the actual RBAC-7 question.** Within
55 _one_ app's database, should different Forgejo teams / end users see different
56 **rows** (RLS) or different **tables** (per-role grants)? e.g. "team `editors`
57 may `UPDATE` any post; team `authors` may only touch their own; `viewers` are
58 read-only."
59
60 RBAC-7 is entirely about **(B)**. (A) is a non-goal it must not regress.
61
62 ---
63
64 ## Design
65
66 If sub-app authorization is warranted, here is the buildable mapping. It is
67 specified so it _could_ be implemented — the recommendation to defer is separate.
68
69 ### Option 1 — Do nothing at the DB; authorize in app code (status quo)
70
71 The app enforces its own authorization in application code using the
72 better-auth session (which already carries the Forgejo identity). The single DB
73 role is an implementation detail; row/table decisions live in the handler.
74
75 - **Provisioner:** nobody — this is today's state (`mcp/src/server.ts:2328`).
76 - **Forgejo mapping:** the app reads the caller's Forgejo teams (from the
77 forwardAuth-injected header or a Forgejo API call) and branches in code.
78 - **better-auth interaction:** none new — the `"user"` table _is_ the identity;
79 the app joins its domain tables to `"user"."id"`.
80
81 ### Option 2 — Per-team Postgres roles + RLS (the "real" propagation)
82
83 Push authorization into Postgres so the database enforces it even if app code has
84 a bug.
85
86 **Mapping — Forgejo team → Postgres role → RLS policy:**
87
88 | Layer | Object | Source of truth |
89 | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
90 | Platform identity | Forgejo team (e.g. `acme/editors`) | Forgejo (RBAC-1 already resolves team membership: `mcp/src/server.ts:899`) |
91 | DB role | `app_<team>` login-less role, `GRANT`ed to the app's connection role via `SET ROLE` | provisioned once per team |
92 | Row gate | `CREATE POLICY … USING (current_setting('app.forgejo_team') = owner_team)` on each protected table | per-app migration |
93 | Request binding | app sets `SET LOCAL app.forgejo_user = '<sub>'; SET LOCAL app.forgejo_team = '<team>'` per transaction, from the forwardAuth-verified identity | app code |
94
95 **Mechanism.** The app keeps one _connection_ role (CNPG's `${name}` owner) but,
96 per request/transaction, sets session GUCs (`app.forgejo_user`,
97 `app.forgejo_team`) from the forwardAuth-verified headers and (optionally)
98 `SET ROLE app_<team>`. RLS `POLICY` expressions read those GUCs via
99 `current_setting(...)`. Because the identity is set with `SET LOCAL` inside a
100 transaction, it cannot leak across pooled connections.
101
102 **Who provisions what:**
103
104 - **The per-app RLS _schema_** (which tables have RLS, which columns are the
105 ownership key) is app-specific product logic. It belongs in the app's **own
106 migration** — the template already ships a migration entry point
107 (`_app-template/src/migrate.ts`, run as a Helm pre-install/pre-upgrade Job hook
108 per the file header). `mcp create_app` cannot know an app's row model, so it
109 must **not** own the RLS policies.
110 - **The _roles_ (`app_<team>`) and the GUC/`SET ROLE` plumbing** are generic and
111 _could_ be platform-provisioned. The natural seam is the CNPG bootstrap
112 (`mcp/src/server.ts:2328`) plus a small post-init SQL run as the superuser role
113 (CNPG generates `${name}-pg-superuser`, `mcp/src/server.ts:2303`), or a CNPG
114 `managed.roles` block. But the _set of teams_ is dynamic (owners create Forgejo
115 teams anytime), so a static bootstrap list goes stale — pointing at a
116 reconciler (watch Forgejo teams → ensure `app_<team>` roles), which is
117 substantial new machinery.
118
119 **better-auth interaction (the sharp edge).** better-auth owns `"user"`,
120 `"session"`, `"account"`, `"verification"` and **bootstraps them itself at
121 runtime** as the app's connection role (`ensureSchema`,
122 `_app-template/src/auth.ts:70`, run via `bootstrapSchema` after listen,
123 `:147`). Two frictions:
124
125 1. If we turn the app's connection role into a _restricted_ RLS-subject role,
126 better-auth's `CREATE TABLE IF NOT EXISTS` and its own reads/writes must still
127 work — its tables must be RLS-exempt (they are _platform_ identity plumbing,
128 not product rows) or owned by a role that bypasses RLS. Simplest: keep
129 better-auth's tables owned by the DB owner with `BYPASSRLS`, apply RLS only to
130 _product_ tables.
131 2. better-auth's user id **is** the Forgejo `sub` (`_app-template/src/auth.ts:181`),
132 so the RLS ownership key (`app.forgejo_user`) can be joined directly to
133 `"user"."id"` — the identity is already consistent end to end. This is the one
134 genuinely nice property: no identity-mapping table is needed.
135
136 ### Option 3 — Per-team Postgres roles, no RLS (table grants only)
137
138 Coarser middle ground: distinct login roles per team with table-level
139 `GRANT`/`REVOKE` (e.g. `viewers` get `SELECT` only), no row policies. Needs
140 per-team _connection_ credentials threaded to the app, which the current
141 single-Secret `extraEnvFrom` model (`mcp/src/server.ts:2434`) does not support —
142 the app would need to pick a credential per request. Strictly more plumbing than
143 Option 1 for less granularity than Option 2; documented only for completeness.
144
145 ---
146
147 ## Tradeoffs
148
149 | | Opt 1 (app-code authz) | Opt 2 (roles + RLS) | Opt 3 (role grants) |
150 | ----------------------------------------- | ---------------------- | ------------------------------------------------------------------- | ----------------------------- |
151 | Defense in depth | none at DB | **strong** (DB enforces) | table-level |
152 | Row granularity | yes (in code) | **yes (in DB)** | no |
153 | New platform machinery | none | Forgejo-team → role reconciler; GUC binding; RLS-exempt better-auth | per-team creds threading |
154 | better-auth friction | none | must exempt its tables | must exempt its tables |
155 | Fits current single-Secret conn model | yes | yes (one conn role + GUCs) | **no** (needs per-team creds) |
156 | Blast radius if app code has an authz bug | data exposed | **contained by RLS** | partial |
157
158 The _only_ thing Option 2 buys over Option 1 is **defense-in-depth**: if the app
159 code forgets a `WHERE owner = me`, RLS still stops the leak. That is real value
160 for a multi-tenant SaaS with untrusted-ish internal roles. It is near-zero value
161 for a single-client app whose _whole_ database is already fenced to one tenant by
162 (A), and whose end users are gated at the edge by forwardAuth.
163
164 ---
165
166 ## Recommendation
167
168 **DEFER Option 2/3. Ship Option 1 (status quo) for the single-client platform.**
169 Rationale, concretely:
170
171 1. **The edge already gates the app, and the DB is already single-tenant.** For
172 the client's one app, forwardAuth (RBAC-2) decides _who reaches the app_ and
173 the per-app CNPG cluster + NetworkPolicies (`mcp/src/server.ts:2312`, `:2345`)
174 decide _who reaches the database_ (nobody but this app). RLS would add a
175 _third_ gate for _intra-app row_ authorization the client does not yet have a
176 requirement for.
177
178 2. **Sub-app RLS is only warranted when one app has mutually-distrusting
179 internal roles over shared rows.** A single-client app typically does not:
180 its authorization is "logged-in Forgejo user of the client's org," already
181 expressible in app code against the better-auth session
182 (`_app-template/src/auth.ts:163`).
183
184 3. **The cost is real and mostly generic-but-stateful.** Option 2 needs a
185 Forgejo-team → Postgres-role reconciler (teams are dynamic), per-transaction
186 GUC binding wired through forwardAuth, and a carve-out so better-auth's own
187 schema bootstrap (`_app-template/src/auth.ts:70`) keeps working under a
188 restricted role. That is a meaningful build against a benefit (defense-in-
189 depth) with no current client driver.
190
191 4. **Deferring costs us nothing later.** RLS is additive: turning it on for a
192 future app is a per-app migration (`_app-template/src/migrate.ts`) plus role
193 provisioning; it does not require re-architecting today's single-role apps.
194 And the identity is _already_ consistent (better-auth id = Forgejo `sub`,
195 `_app-template/src/auth.ts:181`), so the future mapping has no schema debt to
196 pay down.
197
198 **Concretely, do now (near-zero cost, unblocks a future build):**
199
200 - Keep the single owner role (`mcp/src/server.ts:2328`) — no change.
201 - Document in `_app-template` that app-level authorization belongs in app code
202 against the better-auth/forwardAuth identity (the id is the Forgejo `sub`).
203 - Leave `create_app` **out** of RLS policy provisioning (it cannot know an app's
204 row model); reserve `src/migrate.ts` as the per-app seam if an app later opts
205 in.
206
207 **Build Option 2 when a triggering requirement appears:**
208
209 - A single app must host **mutually-distrusting tenants/teams over shared
210 tables** (true multi-tenant SaaS in one DB), **or**
211 - a compliance requirement demands **DB-enforced** row authorization (defense in
212 depth is contractually required, not just nice), **or**
213 - an app's authorization surface grows past what app code can be trusted to
214 enforce correctly.
215
216 At that point, implement the [Option 2 mapping](#option-2--per-team-postgres-roles--rls-the-real-propagation)
217 verbatim: `app_<team>` roles reconciled from Forgejo teams, `SET LOCAL` GUC
218 binding from the forwardAuth-verified identity, RLS policies in the app's own
219 migration, better-auth tables `BYPASSRLS`.
220
221 ---
222
223 ## Open questions (to resolve at build time, not now)
224
225 - **Reconciler home.** Should the Forgejo-team → `app_<team>` role reconciler
226 live in the mcp (extending the CNPG bootstrap at `mcp/src/server.ts:2328`) or in
227 a small controller? Teams are dynamic, so a static `managed.roles` bootstrap
228 list will drift.
229 - **Identity transport into the DB session.** How does the forwardAuth-verified
230 team reach the app process to be put in `SET LOCAL app.forgejo_team`? A signed
231 header from the RBAC-2 middleware is the obvious channel, but the app must
232 **trust only** the middleware-set header (strip any client-supplied copy) — a
233 spoof here defeats RLS entirely.
234 - **Connection pooling vs. `SET ROLE`.** With a shared `pg` Pool
235 (`_app-template/src/auth.ts:58`), per-request `SET LOCAL` must be transaction-
236 scoped so identity never bleeds across pooled connections. Confirm the app's
237 query pattern wraps authorized reads in transactions, or add a pgbouncer-style
238 session guard.
239 - **better-auth migration ownership.** If a future managed better-auth (its CLI
240 `migrate`) replaces the inline `ensureSchema` (`_app-template/src/auth.ts:70`),
241 re-confirm its tables stay RLS-exempt / owner-owned.
242 - **Does forwardAuth expose team membership at all?** RBAC-2 is not yet in the
243 tree; this design assumes it injects a verified Forgejo-team header. If it only
244 asserts _authenticated_, per-team RLS needs a Forgejo API lookup
245 (`mcp/src/server.ts:899` resolves team membership) — an extra hop to design in.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs