Public: anyone can read this; nobody can change it.
workbenchthis machine
RBAC-7: DESIGN Forgejo-identity -> per-app postgres role/RLS (design only) #55
Check · Review · Land done · Live — Landed; nothing deploys from this branch, so this is the end of its path.
feat/rbac-7-postgres-rls-design → main 1 commit
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)). | |
| 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--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. |
new above
offline