paliad/docs/design-permissions-vs-roles.md

Design: Separate Job Title from Global Permissions

Status: Draft for review (m + head) Author: cronus (mai inventor) Date: 2026-04-27 Task: t-paliad-051

Problem

Three orthogonal concepts share one column today:

1. Job title — Partner / Counsel / Associate / PA / Trainee / Sekretariat / "Counsel Knowledge Lawyer" / … . Free-text since migration 015. Display only.
2. Global permissions — currently "is the user a global admin?" piggy-backed on the same column with paliad.users.role = 'admin' checks across Go, SQL, and JS.
3. Per-project role — paliad.project_teams.role ∈ {lead, associate, pa, of_counsel, local_counsel, expert, observer, admin}. Already separated, fine, out of scope.

The collision bites whenever someone tries to record their real job title without losing admin access. Concrete trigger: m's job title is "Counsel Knowledge Lawyer". If he sets that as his role, he loses every role='admin' gate in the codebase. Today the admin-team page (t-paliad-050) actually hard-rejects setting role='admin' from the UI (AdminUpdateUser raises ErrAdminBootstrapOnly), so any UI-driven edit of m's row would silently demote him.

Live state confirmed 2026-04-27 14:25 against 100.99.98.201:11833:

email	role	display_name
matthias.siebels@hoganlovells.com	admin	Matthias
tester@hlc.de	admin	Test Tester
29 stub colleagues	associate	…

So: 31 rows total, 2 admins, 29 associates. No partner rows in production today even though the gate exists in code.

Goal

Split paliad.users.role into:

• paliad.users.job_title — free text, display only. Replaces today's role.
• paliad.users.global_role — enum-via-CHECK, currently 'standard' | 'global_admin'. New column, drives every role='admin'-style permission check.

Per-project paliad.project_teams.role is untouched.

After the change m can carry job_title='Counsel Knowledge Lawyer' AND global_role='global_admin' simultaneously.

Decisions

1. Naming

• Rename paliad.users.role → paliad.users.job_title.
• Add paliad.users.global_role text NOT NULL DEFAULT 'standard' with CHECK (global_role IN ('standard','global_admin')).

2. Why enum-via-CHECK over a permissions text[]

	text-with-CHECK	text[] permissions
New permission	edit one CHECK constraint	none
Code surface	u.global_role = 'global_admin'	'global_admin' = ANY(u.permissions)
Multi-grant	impossible by construction	natural
Validation	DB-level	service-level only
Today's needs (1 permission)	trivial	over-engineered

We have one permission today and m's brief says "possibly more later, design with that in mind". An enum keeps every call site short and DB-validated; growing the CHECK to add billing_admin is a one-line migration and IN (...) checks compose fine. If we ever genuinely need to grant 2+ permissions to one user, swap the column type to text[] in a future migration — call sites change from = to ANY(...), mechanical. Nothing about today's choice forecloses that.

Lean: enum-via-CHECK. Matches m's stated lean. Ships smaller. Easy to widen later.

3. Why not "global_admin is just another job_title value"

Considered: keep role free-text, just normalize so job_title='global_admin' means both the title and the permission. Rejected because (a) the title Counsel Knowledge Lawyer and the permission global_admin are independent — a user can have one without the other (m wants both); (b) the admin-team UI restriction (ErrAdminBootstrapOnly) is exactly the symptom of trying to overload one column for two concerns. We're solving the conflation, not preserving it under a new name.

4. The "partner" gate — DROPPED entirely (m's three-axis principle)

Mid-implementation m clarified the principle: "firm roles are not project roles are not tool roles". Several places gated on user.Role IN ('partner','admin'):

• internal/services/party_service.go:100 — delete party
• internal/services/note_service.go:195 — note ops
• internal/services/appointment_service.go:199 — appointment update/delete
• internal/services/project_service.go:617 — project ops
• internal/services/checklist_instance_service.go:301 — checklist ops
• internal/services/deadline_service.go:437 — delete deadline
• migrations 018 / 021 RLS policies — users.role IN ('partner','admin') on projects_delete, project_teams_delete
• frontend/src/client/projects-detail.ts:555,1206, deadlines-detail.ts:194,208, deadlines.ts:69, notes.ts:104 — UI gates

These conflate "Partner" (a firm role / job title) with permission-to-mutate (a tool role). m: firm role and tool role must be orthogonal; the firm role is display only and must never gate ops.

Decision: drop the partner half of every gate. Each of these checks becomes "global_admin only". Production impact is zero — no prod row has role='partner' today, so nobody loses a capability they actually had.

After-rename gate shape:

// before
if user.Role != "partner" && user.Role != "admin" { return ErrForbidden }
// after
if user.GlobalRole != "global_admin" { return ErrForbidden }

If a future tool-role system grants partner-level mutations to specific users, it adds a fresh dimension cleanly (text[] permissions or named enums) without touching job_title. YAGNI for now — there are no rows that need it.

Helper deleted: the design's first draft kept an IsPartnerOrGlobalAdmin(u) helper. It's gone — the gate is just user.GlobalRole == "global_admin" everywhere.

5. Data migration

Single up migration (023). Idempotent. No backfill data shape worth keeping in code beyond:

-- 023_split_job_title_and_global_role.up.sql

BEGIN;

-- Add new column with default so existing rows pick up 'standard'.
ALTER TABLE paliad.users
    ADD COLUMN IF NOT EXISTS global_role text NOT NULL DEFAULT 'standard';

ALTER TABLE paliad.users
    DROP CONSTRAINT IF EXISTS users_global_role_check;

ALTER TABLE paliad.users
    ADD CONSTRAINT users_global_role_check
    CHECK (global_role IN ('standard','global_admin'));

-- Promote anyone who currently has role='admin'.
UPDATE paliad.users SET global_role = 'global_admin' WHERE role = 'admin';

-- Wipe role='admin' to NULL (admins no longer carry a job title — they didn't
-- pick one, the column was overloaded). Real job titles for the 2 current
-- admins (m + tester) get fixed up by a separate manual UPDATE inside the
-- same transaction, since we know them and the migration ran end-to-end is
-- the right place to do it.
UPDATE paliad.users SET role = NULL WHERE role = 'admin';

UPDATE paliad.users
   SET role = 'Counsel Knowledge Lawyer'
 WHERE email = 'matthias.siebels@hoganlovells.com';
-- tester@hlc.de stays role=NULL — it's a synthetic admin account, no real
-- job title. Admin-team UI will render NULL as "—".

-- Rename the column. Doing this last so the explicit UPDATEs above stay
-- readable; if the rename were first, every UPDATE would refer to job_title
-- and the diff is harder to review.
ALTER TABLE paliad.users
    RENAME COLUMN role TO job_title;

-- The CHECK (role <> '') from migration 015 must come along to job_title,
-- but with a tweak: NULL is now allowed (admins without a job title).
ALTER TABLE paliad.users
    DROP CONSTRAINT IF EXISTS users_role_check;

ALTER TABLE paliad.users
    ADD CONSTRAINT users_job_title_check
    CHECK (job_title IS NULL OR job_title <> '');

-- can_see_project must follow.
DROP FUNCTION IF EXISTS paliad.can_see_project(uuid) CASCADE;

CREATE FUNCTION paliad.can_see_project(_project_id uuid)
RETURNS boolean
LANGUAGE sql STABLE SECURITY DEFINER
SET search_path = paliad, public
AS $$
    SELECT EXISTS (
        SELECT 1 FROM paliad.users u
         WHERE u.id = auth.uid() AND u.global_role = 'global_admin'
    )
    OR EXISTS (
        SELECT 1
          FROM paliad.projects      target
          JOIN paliad.project_teams pt
            ON pt.user_id = auth.uid()
           AND pt.project_id = ANY(string_to_array(target.path, '.')::uuid[])
         WHERE target.id = _project_id
    );
$$;

-- Rebuild RLS policies that the CASCADE drops. Identical to migration 021
-- except every `u.role = 'admin'` becomes `u.global_role = 'global_admin'`
-- and every `u.role IN ('partner','admin')` becomes
-- `(u.job_title = 'partner' OR u.global_role = 'global_admin')`.
-- (Full body in the migration file; not reprinted here for brevity.)

COMMIT;

Down migration is the symmetric reverse: rename job_title → role, copy global_admin rows back to role='admin', drop global_role, restore the original can_see_project body. Ugly but tractable; ~31 rows, no realistic reason to roll back.

6. Code surface — where every 'admin' lives

Inventoried grep -rn "'admin'\\|\\\"admin\\\"\\|user.Role" --include="*.go" --include="*.sql" --include="*.ts" --include="*.tsx" and bucketed:

A. Global-admin gates (these MUST migrate)

Go services

• internal/services/dashboard_service.go:154,211,241,270 — SQL $2 = 'admin', callers pass user.Role as $2 at lines 186, 219, 250, 279
• internal/services/agenda_service.go:135,201 — same pattern
• internal/services/appointment_service.go:487 — same pattern, caller line 492
• internal/services/project_service.go:725,736,747 — three visibilityPredicate* helpers
• internal/services/deadline_service.go:405 — if user.Role == "admin" short-circuit
• internal/services/department_service.go:304 — requireAdmin
• internal/services/user_service.go:149,232,346,388,500,638,641 — bootstrap + IsAdmin + assignment guards

Go handlers

• internal/handlers/onboarding.go:63 — error message
• internal/handlers/users.go:91 — error message
• internal/handlers/admin_users.go:75,113 — error message (twice)

Auth

• internal/auth/require_admin.go:19 — comment only

SQL migrations (existing — for awareness; only migration 023 touches these)

• internal/db/migrations/006_visibility.up.sql:33 — historical, superseded
• internal/db/migrations/007_rls_policies.up.sql:44,58 — historical, superseded
• internal/db/migrations/018_projects_v2.up.sql:414,497,530,544,548,560,565 — historical, superseded
• internal/db/migrations/021_fix_function_bodies_after_rename.up.sql:46,126,155 — current live state of can_see_project + RLS; migration 023 replaces

Frontend

• frontend/src/client/sidebar.ts:299,309 — sidebar admin-section reveal
• frontend/src/client/settings.ts:572,582 — admin-only controls on settings page
• frontend/src/client/admin-team.ts:117,156,177,179,220,221 — table render + sort
• frontend/src/client/deadlines-detail.ts:190,193,207 — admin/partner gate on UI
• frontend/src/client/projects-detail.ts:555,1206 — admin/partner gate on UI

B. Job-title labels (these stay as job_title)

• frontend/src/admin-team.tsx:74,121 — table header / form label "Rolle"
• frontend/src/admin-team.tsx:122 — direct-add input still says "role" (rename to job_title server-side, label stays "Rolle / Job title")
• frontend/src/onboarding.tsx:48,52,53,57 — onboarding form label / field name
• frontend/src/client/admin-team.ts:170,179,309,365,372 — datalist + form handling
• frontend/src/client/i18n.ts — every admin.team.col.role / onboarding.role.* string

The form FIELD NAMES on the wire ({display_name, office, role, ...}) become job_title after the rename. Both client and server change in one commit.

C. Per-project role (NOT touched)

• internal/services/deadline_service.go:417 — pt.role IN ('admin', 'lead') — this is project_teams.role, unrelated.
• All other pt.role references in handlers/services.

7. API surface

/api/me payload before:

{ "id": "…", "email": "…", "role": "admin", … }

After:

{ "id": "…", "email": "…", "job_title": "Counsel Knowledge Lawyer", "global_role": "global_admin", … }

/api/admin/users and /api/admin/users/{id} similarly expose both fields. PATCH /api/me accepts {job_title} (no role); PATCH /api/admin/users/{id} accepts {job_title, global_role} — server enforces that only existing global_admins can change global_role, and refuses to demote the last global_admin (mirror of the existing last-admin protection in AdminDeleteUser).

POST /api/admin/users accepts {email, display_name, office, job_title, dezernat, lang} only — global_role defaults to 'standard'. Promotion is a separate PATCH action so it can't be smuggled into create.

Self-service POST /api/onboarding accepts {display_name, office, job_title, dezernat} — global_role defaults to 'standard'. The bootstrap path (first row of paliad.users) flips global_role='global_admin' instead of setting role='admin'. Same pg_advisory_xact_lock(7346298141) guard.

8. UI surface

Onboarding (/onboarding)

• Field label: "Berufsbezeichnung / Job title" (was "Rolle")
• Field name in DOM: job_title
• Datalist suggestions stay (Partner / Associate / PA / Of Counsel / Referendar/in / Trainee / wiss. Mitarbeiter/in / Sekretariat). Add: Counsel, Knowledge Lawyer, Counsel Knowledge Lawyer.
• No global_role field — that defaults to 'standard'.

Settings (/einstellungen)

• "Rolle" → "Berufsbezeichnung / Job title", same input.
• New read-only "Berechtigung / Permission" line below: shows Standard or Global Admin. Not editable from settings (must use admin page).

Admin team (/admin/team)

• New column header (after Office, before Dezernat): "Berechtigung / Permission".
• Cell content: badge — Standard (neutral) or Global Admin (lime, the brand accent).
• Cell behavior: click toggles a dropdown with the two enum values. Saving issues PATCH /api/admin/users/{id} with {global_role}.
• "Rolle" column heading + cell content stays — but the cell now renders job_title (free text, may be NULL → render as "—").
• Direct-add modal: rename "Rolle" input to "Berufsbezeichnung / Job title", drop the special "Associate" default (keep the placeholder), bind name="job_title".
• Sort: existing "admins first" sort key flips to global_role='global_admin' first.
• Last-global_admin protection: dropdown disabled (with tooltip) when the row is the last surviving global_admin.

Sidebar

• The admin-section reveal in sidebar.ts:initAdminGroup() flips the predicate from me.role === "admin" to me.global_role === "global_admin".

Deadline / project detail pages

• The me.role === "admin" || me.role === "partner" gates become me.global_role === "global_admin" || me.job_title === "partner" (preserving today's broken-but-harmless behavior; see §4).

9. Bootstrap rule

Today: first paliad.users row may self-assign role='admin', guarded by pg_advisory_xact_lock(7346298141).

After: first paliad.users row may set global_role='global_admin'. Same lock, same constant, new column. Onboarding payload includes no global_role — the service decides based on the row count and overrides the default 'standard' for the first inserter.

10. Backwards compat

Decision: clean rename, no compat shim. Justification:

• 31 production rows, all in our control.
• Wire format changes (role → job_title, new global_role) cross client + server simultaneously in one merge. No staged rollout needed for an internal tool.
• Old session cookies with cached me.role values get refreshed on the next /api/me call, which the client makes on every page load.
• The paliad.users.role column stops existing after migration 023. Any ad-hoc query / report keyed on role='admin' breaks loudly — that's the point.

If future me wants compat-during-deploy: add a generated column role text GENERATED ALWAYS AS (job_title) STORED for one release, drop in the next. Not doing that now.

11. Test plan

Unit

• internal/services/user_service_test.go
  • Create with count=0 → global_role='global_admin' AND job_title=<input> (or NULL if empty)
  • Create with count>0 → global_role='standard'
  • UpdateProfile cannot set global_role (field absent from UpdateProfileInput)
  • AdminUpdateUser can set global_role; rejects when caller is not global_admin (handler-level test); rejects demotion of last global_admin (service-level test, mirror of AdminDeleteUser's last-admin protection)
  • IsAdmin reads global_role
• internal/auth/require_admin_test.go — already covers the IsAdmin surface; no changes needed beyond the swap of test fixture's seeded column.

Integration / smoke

• Manual: log in as tester@hlc.de — confirm sidebar /admin/team entry appears, page loads, table shows m as global_admin + "Counsel Knowledge Lawyer" job title.
• Manual: set m's job_title via admin page to something else, confirm global_role is unchanged.
• Manual: try to demote tester (last global_admin in this case if you've already demoted m) — expect rejection.
• DB-level: SELECT email, job_title, global_role FROM paliad.users after migration. Expected:
  • 2 rows global_admin (m, tester), m.job_title='Counsel Knowledge Lawyer', tester.job_title IS NULL
  • 29 rows standard with job_title='associate'
• go build ./... && go vet ./... && go test ./... clean.
• cd frontend && bun run build clean.

Out of scope (recap)

• Fine-grained permissions (partner, billing_admin) — design leaves room (CHECK can grow; or migrate to text[] later) but ships only global_admin.
• Cleaning up the "partner" gate conflation (§4) — gate stays job-title-driven for now. File follow-up.
• Permission inheritance from project_teams to global — explicitly orthogonal.
• Role-based UI customization beyond hide/show — defer.

Open questions for m

1. m's job_title value — task brief says "Counsel Knowledge Lawyer". Confirmed? (Migration writes that exact string.)
2. tester's job_title — migration sets NULL. Alternative: 'Admin' literal. Lean: NULL — tester is a synthetic admin without a real title; "Admin" as a job title perpetuates the conflation we're solving.
3. Default global_role on new sign-ups beyond the bootstrap — confirmed 'standard'.
4. The 'partner' job-title gate — leave as-is for this PR? (My recommendation: yes, file follow-up.)

Implementation phase plan (after greenlight)

Single mai/cronus/separate-job-title-from branch, single PR, single merge to main.

1. internal/db/migrations/023_split_job_title_and_global_role.{up,down}.sql — schema + data + can_see_project + RLS rebuild.
2. internal/models/models.go — User.Role → User.JobTitle (keep db:"job_title" json:"job_title"); add User.GlobalRole string \db:"global_role" json:"global_role"`. Make JobTitlea*string` since admins may have NULL.
3. internal/services/user_service.go — every role reference, including userColumns, the bootstrap branch (assign global_role), IsAdmin (reads global_role), UpdateProfileInput/AdminUpdateInput (drop Role, add JobTitle *string and GlobalRole *string for admin-only).
4. internal/services/{dashboard,agenda,appointment,project,deadline,department,party,note,checklist_instance}_service.go — swap the SQL $N = 'admin' → $N = 'global_admin' and the call sites pass user.GlobalRole instead of user.Role. Partner gates change to user.JobTitle != "partner" && user.GlobalRole != "global_admin" (per §4).
5. internal/handlers/{onboarding,users,admin_users}.go — update error messages; payload field renames.
6. internal/auth/require_admin.go — comment update only (the AdminLookup.IsAdmin interface is unchanged because it abstracts behind the boolean).
7. frontend/src/admin-team.tsx, frontend/src/onboarding.tsx — labels + field names (role → job_title); add Permission column on admin-team.
8. frontend/src/client/admin-team.ts, frontend/src/client/onboarding.ts, frontend/src/client/sidebar.ts, frontend/src/client/settings.ts, frontend/src/client/deadlines-detail.ts, frontend/src/client/projects-detail.ts — every me.role === "admin" → me.global_role === "global_admin"; every form-field role → job_title; add the global_role dropdown widget.
9. frontend/src/client/i18n.ts — DE+EN strings for "Berufsbezeichnung", "Berechtigung", "Standard", "Global Admin".
10. Tests — update fixtures + add the cases in §11.

Self-merge to main authorized once go build/vet/test ./... and bun run build are clean and a smoke pass against ydb confirms acceptance §1–§9 of the task brief.