UmbraTrans/umbratrans_web/migrations/README.md

Phase-1 identity migrations

Status: proposed, never applied, awaiting review.

The SQL in this directory has not been executed against any database, including any development database. It exists so a reviewer can assess the phase-1 identity change before an operator runs it under a change ticket.

File	Purpose
0001_phase1_identity.sql	Forward migration: users.username, user_credentials, organizations, additive sessions columns
0001_phase1_identity_rollback.sql	Destructive rollback with prerequisites and verification queries

What the forward migration changes

Exactly four things, matching docs/umbratrans-backend-design.md:

1. users.username — nullable, unique, citext (case-insensitive). Existing rows stay NULL until an operator supplies an explicit mapping.
2. user_credentials — one credential row per user, with credential_type in (local_password, oidc), an Argon2id password_hash that is required for local_password and forbidden for oidc, must_change_password, failed_login_count, locked_until, last_login_at, password_changed_at, and timestamps.
3. organizations — created with CREATE TABLE IF NOT EXISTS and the slug constraint attached, so it is a no-op when the control plane already owns the table. The application's phase-1 service validates users.organization_id against it, so without it that column referenced nothing.
4. sessions — additive columns mfa_verified_at, idle_deadline_at, last_seen_at. Nothing is dropped, renamed, or retyped.

It creates no credential rows, backfills no username, inserts no organization, and changes no project, role, permission, invitation, or audit table.

Review questions the file cannot answer itself

These are BLOCKER-level unknowns. This workspace has no access to the production schema, so the file states its assumptions instead of guessing.

• Membership model divergence (the important one). The control plane derives organization membership from user_roles with scope = 'organization', and supports a project-scoped membership the application slice does not model. The application currently stores membership as a column on the user record. One of these has to change before the PostgreSQL adapter is written:

  • keep the column and accept that a user has at most one organization and no project membership, or
  • move the service onto user_roles, which means reading and writing role assignments and reconciling RoleName with the roles table.

  This migration deliberately does not decide it. It creates the organizations table and adds no membership column, so the choice stays open and reviewable.

• Does users have a uuid primary key named id, and no existing column named username?

• Does organizations already exist in the control plane, and if so does its status check constraint already allow archived? The rollback keys on that constraint, and a mismatch would make the guarded drop fall through to the RAISE NOTICE branch and leave the table in place.

• What is the name of the "current user" RLS helper (app.current_user_id(), a request-scoped GUC, or something else), and can a client influence it?

• Are users and sessions already under RLS, and with FORCE?

• What are the migration role and application role names?

• Is citext available to the migration role? If not, use a lower(...) unique index instead of a case-sensitive text column.

• Are the roles rows the application needs present, with the right scope? The adapter resolves a role by name from public.roles and requires platform_admin at scope platform, and organization_admin and member at scope organization. app.validate_user_role_scope() enforces the pairing, so a missing or wrongly scoped role makes account creation fail. Check before provisioning, not during:

  SELECT name, scope FROM public.roles
   WHERE name IN ('platform_admin', 'organization_admin', 'member')
   ORDER BY name;
  

• Does any row carry users.mfa_required = true? The adapter refuses to resolve an account that requires a second factor, because this phase cannot satisfy one. Until MFA is implemented, every row must be false or those accounts are unusable:

  SELECT count(*) FROM public.users WHERE mfa_required;
  

• Does every user hold at most one active user_roles row? The adapter refuses to resolve a user with more than one active assignment rather than pick one, because the organization on the assignment becomes the scope of every administrative decision:

  SELECT user_id, count(*) FROM public.user_roles
   WHERE status = 'active' GROUP BY 1 HAVING count(*) > 1;
  

• Do all existing users have an email? It is NOT NULL, so any row added by another system already has one; the check confirms the constraint the application depends on is the live one.

• Does a generic set_updated_at() trigger helper exist, or does the application maintain updated_at?

• Is sessions large enough that CREATE INDEX must be replaced with CREATE INDEX CONCURRENTLY outside the transaction?

• Which existing sessions column should backfill last_seen_at, if any?

Gates that must pass before approval

• Logical backup taken, checksummed, and restore-tested on a scratch database.
• Migration role and application role privileges verified.
• RLS tests covering two organizations and two projects, including FORCE ROW LEVEL SECURITY and a client-controlled-GUC escalation attempt.
• Account-management tests passing against an isolated PostgreSQL database with the PostgreSQL adapter implemented.
• Rollback rehearsed on the scratch database.

Until then, production PostgreSQL stays untouched and the application runs against a development repository.

Data classification

• user_credentials.password_hash — authentication secret (hash only). Never selected into a report, an endpoint response, or a log.
• sessions.token_hash — authentication secret (hash only), unchanged by this migration.
• users.username and users.email — personal data. Included in data-export and retention reviews for the control plane.