Module Access Control

An interactive, zoomable version of this diagram is available at module-access-control.html.

This document explains how a signed-in user is matched to a module. Authentication Flow covers how you sign in and how tokens are minted. This document covers the next question: once signed in, what can you reach?

The core fact

The Better Auth users table has no module column. Nothing on a user row says “this person belongs to leave management” or “this person belongs to rental”. Module access is decided at request time by combining four independent mechanisms. Each module picks a different combination.

The four mechanisms

#	Mechanism	Storage	Question it answers
1	Platform role	`users.role` — a single text value	Are you `user` / `admin` / `superadmin` / `landlord`?
2	Organization role	`members.role` — one row per (user, org)	Inside org X, are you `owner` / `admin` / `staff` / `member` / `viewer` / `field_team`?
3	Feature flags	`admin_feature_flags` (global) + `org_feature_flags` (per-org)	Is this module switched on for this organization?
4	Participation rows	Module-owned tables	Is this your row? e.g. `rental_properties.landlord_user_id`, `dw_agent_managers`

users.role holds one value only. An account cannot be both landlord and admin. This is a constraint of Better Auth’s admin plugin, and several guards exist purely to protect it.

How roles reach the backends

The Bun backend mints the app-JWT and flattens the org role and the platform role into one flat array:

// backend/bun/apps/monolith/src/services/auth/api.ts
export function buildRoles(orgRole, platformRole) {
  const roles = [];
  if (orgRole) roles.push(orgRole);
  if (platformRole && platformRole !== orgRole) roles.push(platformRole);
  if (roles.length === 0) roles.push('user');   // Go requires >= 1 role
  return roles;
}

Ordering is a contract: element 0 is always the org role, the platform role follows. The Go backend’s AuthMiddleware puts that array into the Echo context as user_roles (backend/go/internal/api/http/middleware/auth_middleware.go), and RequireJWTRole matches against it.

buildRoles is re-implemented on both sides — once in Bun (services/auth/api.ts) and once in Go (internal/api/http/middleware/better_auth_validator.go). They sit across a trust boundary and cannot share code, so the behaviour is pinned by a shared fixture at contracts/auth/role-revocation-vectors.json.Change one side without the other and TestAuthGoldenVectors (Go) or auth-golden.test.ts (Bun) will fail. This is intentional.

Two styles of authorization check

The codebase deliberately uses two different seams. Know which one you are reaching for.

	`RequireJWTRole`	`BetterAuthRBAC`
Source of truth	the token claim	the database
DB lookup	none	yes, via `PermissionService`
Cost	free	a query (5-min cached)
Staleness	up to token TTL (7d default)	immediate
File	`internal/api/http/middleware/jwt_role.go`	`internal/api/http/middleware/better_auth_rbac.go`

Use RequireJWTRole for coarse gates. Use BetterAuthRBAC when a stale role would be unacceptable.

Per-module breakdown

1. Platform admin

Gate: users.role ∈ . Not organization-scoped.
Bun: adminOnlyMiddleware — apps/monolith/src/api-gateway/middleware/admin.middleware.ts
Go: RequirePlatformRole (DB-backed) or RequireJWTRole("admin","superadmin") (trusts the token)
Frontend: isPlatformAdmin in apps/panel/src/app.tsx

2. Leave management

No module gate and no feature flag. internal/modules/leave/module.go mounts every route behind plain AuthMiddleware.
Differentiation comes entirely from permissions derived from members.role, resolved in internal/modules/organizations/application/usecase/permission_service.go:

Org role	Permissions
`owner`, `admin`	`leave:approve`, `leave:request`, `data:read/write`, `member:*`, `org:manage`
`staff`, `member`	`leave:request`, `data:read/write`
`viewer`	`data:read`

Any organization member automatically has leave access. Leave is the default module.

3. Fieldforce

Org-scoped: routes are /api/v1/organizations/:org_id/fieldforce (internal/modules/fieldforce/module.go)
Feature flag fieldforce, two-tier and fail-open — a missing row means enabled, so a database hiccup never takes fieldforce down (adapter/inbound/http/feature_flag_middleware.go)
The field worker is a dedicated org role field_team, checked inline in handlers (briefing_handler.go, risk_intervention_handler.go). It can see tasks but is blocked from briefings and risk data.

4. Digital workers

Org-scoped + feature flag digital_worker. This one returns 404, not 403 — the feature is not acknowledged at all until enabled — and the global flag is seeded OFF (internal/modules/digitalworker/adapter/inbound/http/feature_flag_middleware.go).
Org membership is not enough. Access requires a dw_agent_managers row OR org owner/admin, via CanAccessLearning in application/usecase/learning_authz.go. A plain member or field_team is excluded.
Sensitive approvals stay owner/admin-only even when an Agent Manager exists.

5. Rental platform

The odd one out — see Rental: landlord vs tenant below.

Not organization-scoped at all. Routes are /api/rental/... with no :org_id. Landlords have no organization ID in context.
No feature flag.
Landlord = the platform role token users.role = 'landlord', gated by RequireLandlord().
Tenant = any authenticated user, with no role at all.
Admin review queue = admin / superadmin only; even the owning landlord gets 403.

Summary table

Module	Org-scoped	Feature flag	Who gets in
Platform admin	No	—	`users.role` = `admin` / `superadmin`
Leave	Yes	none	any org member
Fieldforce	Yes	`fieldforce` (fail-open)	org member; `field_team` restricted
Digital workers	Yes	`digital_worker` (404, off by default)	owner/admin or `dw_agent_managers` row
Rental	No	none	`landlord` platform role (owner side) / any signed-in user (tenant side)

Rental: landlord vs tenant

Rental is worth its own section because it does not follow the organization model.

The design is asymmetric

There is no tenant role. Only the landlord has a role. A tenant is identified purely by row data. From apps/panel/src/routes/tenant.tsx:

No role is checked here because the backend has no tenant role — the backend’s row-level tenant_user_id check is the real boundary.

Layer 1 — route gate: “is a landlord calling?”

// internal/modules/rental/adapter/inbound/http/require_landlord.go
func RequireLandlord() echo.MiddlewareFunc {
	return middleware.RequireJWTRole(entity.RoleLandlord)
}

Applied to exactly two groups in internal/modules/rental/module.go:

owner         := protected.Group("/properties", rentalhttp.RequireLandlord())
ownerListings := protected.Group("/listings",   rentalhttp.RequireLandlord())

Everything else — contacts, viewing requests, offers, agreements, tenancies, payments, handover — mounts on the bare protected group and is reachable by any signed-in user.

Layer 2 — row-level party check: “is it this landlord / this tenant?”

The tables carry both ids side by side:

CREATE TABLE rental_tenancies (
  landlord_user_id  TEXT NOT NULL,
  tenant_user_id    TEXT NOT NULL,
  ...
)

And the use case derives your role from which column your id sits in:

// internal/modules/rental/application/usecase/handover.go
isLandlord := tenancy.LandlordID == sessionUserID
isTenant   := tenancy.TenantID   == sessionUserID
if !isLandlord && !isTenant {
    return nil, ErrForbidden
}

Your role is per row, not per account. For one-sided landlord rows (properties, listings) the guard is EnsureOwner in internal/modules/rental/application/ownership.go. It maps to 404, never 403, so a cross-landlord probe cannot confirm that a row exists.

How the ids get planted

Landlord calls POST /rental/landlord/promote  → users.role = 'landlord'
Landlord creates a property                   → rental_properties.owner_user_id
Any signed-in user requests a viewing         → viewing_request.tenant_user_id = caller
                                                   viewing_request.owner_user_id  = property owner
Offer accepted                                → rental_offers { tenant_user_id, landlord_user_id }
Agreement signed                              → rental_tenancies { landlord_user_id, tenant_user_id }

Tenant identity is created by the act of requesting a viewing — no role assignment, no approval. Self-booking is blocked by comparing the two ids (ErrSelfBooking).

Same row, different rights

Action	Who	Check
Create payment draft	tenant	`tenancy.TenantID != sessionUserID` → reject
Confirm / reject / reverse payment	landlord	`tenancy.LandlordID != sessionUserID` → reject
Stream payment proof	either party	both ids checked
Confirm viewing while `pending`	owner only
Confirm viewing while `countered`	tenant only

The stored recorded_by_role and actor_role columns (CHECK IN ('tenant','landlord')) are records of who acted, not permissions.

Becoming a landlord

Promotion is self-service and instant — there is no verification step. apps/panel/src/routes/owner/sign-up.tsx:

await authClient.signUp.email({ name, email, password });  // creates users row, role='user'
await promoteToLandlord();                                  // → role='landlord'
navigate('/owner');

The request path is:

POST /api/rental/landlord/promote
   → SolidStart proxy (apps/panel/src/routes/api/rental/[...path].ts)
   → Go :8080 /api/rental/landlord/promote
   → UPDATE "users" SET role='landlord'
       WHERE id = <session user>
         AND COALESCE(role,'') NOT IN ('admin','superadmin')

Notes:

The endpoint takes no user id. You can only promote yourself; an admin cannot promote someone else through it.
The NOT IN ('admin','superadmin') clause is the only guard. It exists to stop a promotion from destroying a staff role, not to verify identity.
The response returns token_refresh_required: true. The role lands in Postgres immediately, but the caller’s current JWT still carries the old role, so landlord routes keep refusing until a new token is minted.

Verification does exist, but one level lower — on publishing a listing, not on the account:

draft ──[Submit]──> pending_review ──[admin review]──> live
                                   └──────────────────> rejected

Submit refuses unless an ownership proof document exists for the property (ErrNoOwnershipProof) and the declaration is ticked (ErrDeclarationNotAccepted). A human admin / superadmin then reviews it. So the role is cheap, but a fake landlord can never get a listing in front of a tenant.

There is currently no UI path for an existing user to become a landlord. /owner/sign-up redirects away anyone who already has a session, and /owner then shows “Access Denied”. The API itself works fine for any signed-in non-staff account — this is a missing button, not a missing capability. Adding it requires forcing a session refresh after promotion so the new role reaches the token.

Gotchas for developers

users.role is single-valued. A user cannot be both landlord and platform admin. PromoteToLandlord explicitly refuses accounts holding a staff role.
A landlord can be an organization member. Org role lives in members.role, a different column, so a landlord who is also a leave-management employee gets roles: ['member', 'landlord'] and both work.
The rental role is named landlord, not owner, on purpose. RequireOrgRole already uses owner for organization owners, and buildRoles flattens org and platform roles into one array — reusing owner would make the two meanings indistinguishable inside a token. See internal/modules/rental/domain/entity/role.go.
Role changes are not instant for JWT-trust gates. RequireJWTRole does no DB lookup. A promotion needs a token refresh; a demotion stays effective until the token expires or is revoked. Server-side revocation exists in backend/bun/apps/monolith/src/services/auth/revocation.ts.
?role=owner on GET /rental/requests is a view selector, not authorization. It picks ListOwnerRequests vs ListTenantRequests; both filter by your own user id. Passing it grants nothing.
Feature-flag failure policy differs by module and is deliberate. Fieldforce fails open (a DB hiccup must not stop field work). Digital workers fails closed with a 404 (the feature is not acknowledged until enabled). Do not “normalize” these.
The rental party check is duplicated. isLandlord/isTenant appears roughly seven times in handover.go plus variants in payment.go. Unlike EnsureOwner, there is no shared EnsureParty helper — a future rule change must be applied to every copy.

Adding a new module

Pick your combination deliberately:

If the module is…	Use
Sold per organization	org-scoped routes + `members.role` + a feature-flag pair
A platform-wide capability for individuals	a platform role token in `users.role` (like `landlord`)
Rolled out gradually	the two-tier flag pattern via `middleware.GlobalFeatureFlagEnabled`
Holding rows with two counterparties	store both ids on the row and derive the role from them

Always keep the coarse gate in middleware and the row-level check in the use case. Middleware proves a valid caller; only the use case can prove it is this caller.

Concern	Path
Better Auth schema	`backend/bun/packages/auth-adapter/schema.ts`
App-token claims	`backend/bun/apps/monolith/src/services/auth/api.ts`
Platform admin gate (Bun)	`backend/bun/apps/monolith/src/api-gateway/middleware/admin.middleware.ts`
Token validation (Go)	`backend/go/internal/api/http/middleware/better_auth_validator.go`
JWT-trust role gate	`backend/go/internal/api/http/middleware/jwt_role.go`
DB-backed RBAC	`backend/go/internal/api/http/middleware/better_auth_rbac.go`
Permission resolution	`backend/go/internal/modules/organizations/application/usecase/permission_service.go`
Feature-flag helpers	`backend/go/internal/api/http/middleware/feature_flag.go`
Rental landlord gate	`backend/go/internal/modules/rental/adapter/inbound/http/require_landlord.go`
Rental row ownership	`backend/go/internal/modules/rental/application/ownership.go`
Cross-process auth contract	`contracts/auth/role-revocation-vectors.json`
Frontend role resolution	`frontend/solidstart/apps/panel/src/lib/platform-role.ts`

Authentication Flow — sign-up, sign-in, token minting
CLI Auth Architecture — device flow and API keys
Organization Permissions v3 — custom roles and teams
Permission Service Integration — using PermissionService in Go
Role Assignment — assigning roles in practice
ADR-0006 — Better Auth read-only consumer (Go never writes roles)

Overview

Development Tools

Authentication

Guides

Module Access Control

The core fact

The four mechanisms

How roles reach the backends

Two styles of authorization check

Per-module breakdown

1. Platform admin

2. Leave management

3. Fieldforce

4. Digital workers

5. Rental platform

Summary table

Rental: landlord vs tenant

The design is asymmetric

Layer 1 — route gate: “is a landlord calling?”

Layer 2 — row-level party check: “is it this landlord / this tenant?”

How the ids get planted

Same row, different rights

Becoming a landlord

Gotchas for developers

Adding a new module

​The core fact

​The four mechanisms

​How roles reach the backends

​Two styles of authorization check

​Per-module breakdown

​1. Platform admin

​2. Leave management

​3. Fieldforce

​4. Digital workers

​5. Rental platform

​Summary table

​Rental: landlord vs tenant

​The design is asymmetric

​Layer 1 — route gate: “is a landlord calling?”

​Layer 2 — row-level party check: “is it this landlord / this tenant?”

​How the ids get planted

​Same row, different rights

​Becoming a landlord

​Gotchas for developers

​Adding a new module

​Related files

​Related documents

The core fact

The four mechanisms

How roles reach the backends

Two styles of authorization check

Per-module breakdown

1. Platform admin

2. Leave management

3. Fieldforce

4. Digital workers

5. Rental platform

Summary table

Rental: landlord vs tenant

The design is asymmetric

Layer 1 — route gate: “is a landlord calling?”

Layer 2 — row-level party check: “is it this landlord / this tenant?”

How the ids get planted

Same row, different rights

Becoming a landlord

Gotchas for developers

Adding a new module

Related files

Related documents