Remove vestigial `username` field from auth/users (collision footgun, no functional purpose)

Abierto
#847 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
30/100
Tipo de issue
Refactorización
Claridad
Bastante claro
Estado de actividad
Tranquilo
Stack tecnológico
typescript

Línea de trabajo

Start in packages/core/src/services/auth-validation.ts and packages/core/src/auth/config.ts to see how username is derived from the email at registration, then check the invitation-accept check in packages/core/src/routes/auth.ts. Phase 1 is a migration that drops the UNIQUE and NOT NULL constraints on users.username plus removing the invitation requirement; confirm with maintainers before attempting Phase 2, which is a multi-file column removal. Done means signup no longer fails on duplicate derived usernames and the invitation flow no longer requires a username.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

area: auth bug maintenance priority: P2

Summary

users.username is vestigial under the current email-based auth. It is not a login credential, it's auto-derived from the email when not supplied, and its only enforced behavior (NOT NULL UNIQUE) is a liability that causes spurious signup failures. It should be removed in the near future.

What username does today

  • Not a login credential. Login is email-only everywhere — loginSchema is { email, password } (packages/core/src/routes/auth.ts) and Better Auth uses signInEmail. There is no path to sign in with a username.
  • Auto-derived, not chosen. On registration it is .optional() (packages/core/src/services/auth-validation.ts); when omitted it is generated from the email local-part: email.split('@')[0] (fallback user<timestamp>). The Better Auth create hook does the same (packages/core/src/auth/config.ts). In practice nobody enters it.
  • Display handle only, largely redundant with email + first_name/last_name (shown in admin-users list/profile).

Why it exists

Legacy CMS convention (username-based logins / @handles). The users.username TEXT NOT NULL UNIQUE column was kept and still populated after login moved to email.

The problem (why this matters)

  1. Collision trap. NOT NULL UNIQUE + email-derived default means [email protected] and [email protected] both derive username = "alice", so the second registration fails with "User with this email or username already exists" — for a field the user never set and cannot see. Different people, different emails, blocked signup.
  2. Inconsistency. Public registration treats username as optional/auto-derived, but the invitation-accept flow explicitly requires the user to type one (if (!token || !username …) → error, with its own uniqueness check) — packages/core/src/routes/auth.ts.

Proposed removal plan

Phase 1 (low-risk, do soon):

  • Drop the UNIQUE (and ideally NOT NULL) constraint on users.username (migration).
  • Stop requiring it in the invitation-accept flow.
  • This alone removes the signup-failure footgun.

Phase 2 (clean removal):

  • Drop the column entirely; remove it from registration, invitation, admin user UI, and the Better Auth additionalFields.
  • Touches ~35 files (templates, admin-users, invitation flow, schema) + a schema migration.

Notes

  • Pairs naturally with the broader legacy-auth cleanup (e.g. retiring the compatibility users.role column).
  • Keep username only if a public @handle profile feature is on the roadmap; otherwise it is dead weight.

Filed from analysis on branch feature/better-auth-poc.

Lenguaje dominante
TypeScript
Estrellas
1.8k
Forks
219
Merge medio
2 d 21 h
PR fusionados (30 d)
67

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de SonicJs-Org/sonicjs

Todos los issues de SonicJs-Org/sonicjs

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.