refactor(api): collapse /admin/account and /player/account onto /auth/me/account
All checks were successful
PR Checks / bot-tests (pull_request) Successful in 26s
PR Checks / client-build (pull_request) Successful in 27s
PR Checks / server-tests (pull_request) Successful in 10m32s

Self-service account security had three URL surfaces onto one controller. All
three mounted the same `admin/account.controller.js` handlers; each of the three
router files carried a header comment apologising for the arrangement.

`/auth/me/account` was already a strict superset, which settles which to keep:

  /admin/account   6 routes  noindex, isLoggedIn, staffOnly
  /player/account  8 routes  noindex, requireAuth
  /auth/me/account 10 routes noindex, requireAuth

Neither of the deleted surfaces carried recovery codes, and /admin/account
carried no username or password change at all — so client.js already called
/auth/me/account/recovery-codes/* for two operations on a screen it otherwise
served from /admin/account. The split was leaking before this change.

Gating is equivalent where it overlapped: /player and /auth/me apply identical
`noindex, requireAuth`, and `staffOnly` on /admin/account was strictly narrower
while buying nothing, since every handler is self-scoped to req.user.id. There
is no CSRF layer to differ.

  - 14 routes deleted, 0 added, no handler changed.
  - account.controller.js moves router/v1/admin/ -> router/v1/auth/, beside the
    one router that still reaches it.
  - Web client: 14 call sites move onto a root-level api.myAccount /
    api.changeUsername / ... group, matching the /auth/me methods already there.
  - Android app: no change. MeApi.kt was already 100% /auth/me/account/*.
  - Two swagger tags, `Admin · Account` and `Player`, were declared only by the
    deleted routes and go with them. The orphaned `AccountStatus` schema goes
    too; `PlayerAccount` is re-described as the any-role /auth/me/account shape
    (the name is kept so existing $refs resolve).

Breaking to the published OpenAPI surface, accepted deliberately: both consumers
are in this org, and deprecate-then-delete would leave the next phase deciding
whether to add routes to surfaces already marked for removal.

Verification: routes.manifest.json shows exactly 14 deletions and 0 additions.
The OpenAPI spec loses the same 14 paths with zero surviving path definitions
changed; its large textual diff is pure reordering, because removing the
first-mounted router shifts every later path. 1203 server tests, 288 client
tests, 53 bot tests green; check:modules, check:hosts and routes:manifest
--check all pass.

Design of record: docs/website/ENGAGEMENT.md Phase 1a. This lands ahead of
engagement Phase 1b, which adds a self-service email field — written once here
rather than three times.

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
2026-08-29 00:49:25 -05:00
parent f5aa32e0ed
commit 6e61146678
20 changed files with 89 additions and 1428 deletions

View File

@@ -156,9 +156,9 @@ function buildCtx(id, moduleRoot) {
// one store, and one place a breach is logged.
//
// `accountChangeLimiter` is handed over whole because it is genuinely
// shared policy: core's `/auth/me`, `/player/account` and
// `/player/appeals` are behind the same counter, and a module's
// account-change route has to land in it rather than beside it.
// shared policy: core's `/auth/me/account/*` and `/player/appeals` are
// behind the same counter, and a module's account-change route has to land
// in it rather than beside it.
rateLimit: makeLimiter,
accountChangeLimiter,
},

View File

@@ -1,87 +0,0 @@
// Admin · Account — self-service account security for staff.
//
// Mounted at /api/v1/admin/account by admin/index.js, which already applied
// `noindex, isLoggedIn, staffOnly`. Deliberately NOT behind adminOnly: an editor
// or moderator manages their own 2FA and linked identities here, exactly as a
// player does under /player. Every handler keys off req.user.id.
const express = require('express')
const { body, param } = require('express-validator')
const account = require('./account.controller')
const validate = require('../../../middleware/validate')
const accountRouter = express.Router()
accountRouter.get(
'/',
// #swagger.tags = ['Admin · Account']
// #swagger.summary = 'Get the current account (self)'
// #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
/* #swagger.responses[200] = { description: 'The account', content: { "application/json": { schema: { $ref: "#/components/schemas/AccountStatus" } } } } */
/* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
account.getAccount,
)
accountRouter.post(
'/totp/setup',
// #swagger.tags = ['Admin · Account']
// #swagger.summary = 'Begin 2FA enrollment (returns secret + QR)'
// #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
/* #swagger.responses[200] = { description: 'otpauth URL and QR data to scan', content: { "application/json": { schema: { $ref: "#/components/schemas/TotpSetup" } } } } */
/* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
/* #swagger.responses[409] = { description: 'Two-factor already enabled', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
account.totpSetup,
)
accountRouter.post(
'/totp/enable',
// #swagger.tags = ['Admin · Account']
// #swagger.summary = 'Enable 2FA by confirming a code'
// #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
/* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/TotpCodeRequest" } } } } */
/* #swagger.responses[200] = { description: '2FA enabled', content: { "application/json": { schema: { $ref: "#/components/schemas/TotpState" } } } } */
/* #swagger.responses[400] = { description: 'Setup not started, or invalid code', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
/* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
/* #swagger.responses[409] = { description: 'Two-factor already enabled', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
body('code').isString().trim().isLength({ min: 6, max: 8 }),
validate,
account.totpEnable,
)
accountRouter.post(
'/totp/disable',
// #swagger.tags = ['Admin · Account']
// #swagger.summary = 'Disable 2FA by confirming a code'
// #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
/* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/TotpCodeRequest" } } } } */
/* #swagger.responses[200] = { description: '2FA disabled', content: { "application/json": { schema: { $ref: "#/components/schemas/TotpState" } } } } */
/* #swagger.responses[400] = { description: 'Not enabled, or invalid code', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
/* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
body('code').isString().trim().isLength({ min: 6, max: 8 }),
validate,
account.totpDisable,
)
// Linked SSO identities (self-service — any logged-in role manages their own).
accountRouter.get(
'/identities',
// #swagger.tags = ['Admin · Account']
// #swagger.summary = 'List linked SSO identities (self)'
// #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
/* #swagger.responses[200] = { description: 'Linked identities', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/LinkedIdentity" } } } } } */
/* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
account.listIdentities,
)
accountRouter.delete(
'/identities/:provider',
// #swagger.tags = ['Admin · Account']
// #swagger.summary = 'Unlink an SSO identity (self)'
// #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
// #swagger.parameters['provider'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Provider id.' }
/* #swagger.responses[200] = { description: 'Unlinked', content: { "application/json": { schema: { $ref: "#/components/schemas/UnlinkedFlag" } } } } */
/* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
/* #swagger.responses[404] = { description: 'No linked account for that provider', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
param('provider').matches(/^[a-z0-9-]+$/),
validate,
account.unlinkIdentity,
)
module.exports = accountRouter

View File

@@ -16,7 +16,6 @@ const express = require('express')
const { isLoggedIn, requireRole } = require('../../../utils/auth')
const noindex = require('../../../middleware/noindex')
const accountRouter = require('./account.router')
const usersRouter = require('./users.router')
const invitesRouter = require('./invites.router')
const authProvidersRouter = require('./authProviders.router')
@@ -48,7 +47,6 @@ const adminRouter = express.Router()
const staffOnly = requireRole('admin', 'editor', 'moderator')
adminRouter.use(noindex, isLoggedIn, staffOnly)
adminRouter.use('/account', accountRouter)
adminRouter.use('/users', usersRouter)
adminRouter.use('/invites', invitesRouter)
// Mounted at /auth, not /auth/providers: /admin/auth is the capability, and the

View File

@@ -1,6 +1,13 @@
// Self-service account security for the logged-in user (any role). Mounted under
// the admin router (so isLoggedIn has already run and req.user is the fresh DB
// row), but NOT behind the admin-only gate — editors manage their own 2FA too.
// Self-service account security for the logged-in user (any role): username,
// password, TOTP, linked identities, device sessions, trusted devices and
// recovery codes.
//
// Reached through exactly one router — me.routes.js at /auth/me — which applies
// `noindex, requireAuth`, so req.user is the fresh DB row and the status +
// session-cutoff checks have already run. Every handler keys off req.user.id and
// none of them consults a role: this file lived under router/v1/admin/ while it
// also served /admin/account/* and /player/account/*, and moved here when those
// two surfaces were deleted.
const users = require('../../../model/users/users.model')
const activity = require('../../../model/activity/activity.model')
@@ -9,7 +16,7 @@ const mobileSessions = require('../../../model/mobileSessions/mobileSessions.mod
const trustedDevices = require('../../../model/trustedDevices/trustedDevices.model')
const recoveryCodes = require('../../../model/recoveryCodes/recoveryCodes.model')
const sessionService = require('../../../auth/session.service')
const { establishTrust } = require('../auth/trustDevice.helper')
const { establishTrust } = require('./trustDevice.helper')
const { setAuthCookie, setTrustCookie, clearTrustCookie } = require('../../../auth/token')
const usernamePolicy = require('../../../auth/usernamePolicy')
const loginProtection = require('../../../middleware/loginProtection')

View File

@@ -38,10 +38,10 @@ authRouter.use('/mobile', mobileRouter)
// middleware, so passing through it is a no-op for every other route.
authRouter.use(ssoRouter)
// Role-agnostic self-service ("me") — /auth/me/account*, reusing the same
// account.controller handlers as /player/account/* and /admin/account/* behind
// requireAuth (any role). Additive; gives the app one self surface that never
// touches /admin.
// Role-agnostic self-service ("me") — /auth/me/account*, behind requireAuth (any
// role). The single self surface: /player/account/* and /admin/account/* were
// deleted in favour of it, so the app and the web client share one set of URLs
// and neither has to touch /admin.
authRouter.use('/me', meRouter)
// Push-notification self-service — /auth/me/devices*, /auth/me/notifications/*.

View File

@@ -1,14 +1,17 @@
// ── Role-agnostic self-service ("me") under /auth/me ───────────────────────
//
// The canonical self surface for EVERY authenticated role (player and staff
// alike). It reuses the exact same account.controller handlers as
// /player/account/* and /admin/account/* — no logic duplication — but gates on
// requireAuth ONLY (any authenticated, active account), never on a specific role.
// The ONLY self surface, for every authenticated role (player and staff alike).
// It gates on requireAuth ONLY (any authenticated, active account), never on a
// specific role.
//
// Why it exists: the Android app wants one self surface it can call regardless of
// role, and it must never touch /admin (docs/android/PLAN.md §6.4). The older
// /player/account/* and /admin/account/* routes stay for web back-compat; these
// /auth/me/* routes are the additive, role-agnostic canonical form.
// role, and it must never touch /admin (docs/android/PLAN.md §6.4).
//
// It used to be the third of three URL surfaces onto account.controller, beside
// /player/account/* and /admin/account/*. Those were deleted: both were strictly
// smaller than this one (neither carried recovery codes, and /admin/account
// carried no username or password change), so the web client already had to reach
// in here for part of one screen. New self-service fields go here and only here.
//
// requireAuth sets req.user to the fresh DB row and enforces the status + session
// cutoff/revocation checks on every request, exactly as the account handlers
@@ -17,7 +20,7 @@
const express = require('express')
const { body, param } = require('express-validator')
const account = require('../admin/account.controller')
const account = require('./account.controller')
const { requireAuth } = require('../../../auth/session.middleware')
const noindex = require('../../../middleware/noindex')
const validate = require('../../../middleware/validate')
@@ -76,8 +79,8 @@ meRouter.patch(
account.changePassword,
)
// TOTP self-enrollment — identical to the player/admin account flow (disable
// requires a valid current code; it does not take a password).
// TOTP self-enrollment (disable requires a valid current code; it does not take
// a password).
meRouter.post(
'/account/totp/setup',
// #swagger.tags = ['Auth · Me']

View File

@@ -11,7 +11,7 @@
// limiters below are what stop the endpoints being used as an oracle by volume.
//
// Changing a password while signed in is a different route —
// PATCH /player/account/password (and its /auth/me and /admin twins).
// PATCH /auth/me/account/password.
const express = require('express')
const { body, param } = require('express-validator')

View File

@@ -1,130 +0,0 @@
// Player · Account — self-service credentials, 2FA and linked identities for the
// signed-in account.
//
// Mounted at /api/v1/player/account by player/index.js, which already applied
// `noindex, requireAuth`. No extra gate: every handler is self-scoped to
// req.user.id, and staff are a superset of players (see player/index.js).
//
// The handlers are admin/account.controller — the same code serving
// /admin/account/* and /auth/me/account/*. Three URL surfaces, one implementation;
// this file must not grow a fourth copy of the logic.
//
// The swagger tag stays 'Player', matching the committed spec.
const express = require('express')
const { body, param } = require('express-validator')
const account = require('../admin/account.controller')
const validate = require('../../../middleware/validate')
const { accountChangeLimiter } = require('../../../middleware/rateLimit')
const accountRouter = express.Router()
accountRouter.get(
'/',
// #swagger.tags = ['Player']
// #swagger.summary = 'Get the current player account (self)'
// #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
/* #swagger.responses[200] = { description: 'The player account', content: { "application/json": { schema: { $ref: "#/components/schemas/PlayerAccount" } } } } */
/* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
/* #swagger.responses[403] = { description: 'Account not active (disabled/banned)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
account.getAccount,
)
accountRouter.patch(
'/username',
// #swagger.tags = ['Player']
// #swagger.summary = 'Change the current players username'
// #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
/* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ChangeUsernameRequest" } } } } */
/* #swagger.responses[200] = { description: 'Updated username (session cookie re-issued)', content: { "application/json": { schema: { type: "object", properties: { username: { type: "string" } } } } } } */
/* #swagger.responses[400] = { description: 'Validation error or unavailable username', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
/* #swagger.responses[403] = { description: 'Account not active (disabled/banned)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
/* #swagger.responses[409] = { description: 'Username already taken', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
/* #swagger.responses[429] = { description: 'Too many changes (rate limited)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
accountChangeLimiter,
body('username').isString().trim().isLength({ min: 3, max: 32 }),
validate,
account.changeUsername,
)
accountRouter.patch(
'/password',
// #swagger.tags = ['Player']
// #swagger.summary = 'Change or set the current players password'
// #swagger.description = 'If the account already has a password, currentPassword is required and verified. SSO-provisioned accounts with no password may set an initial one without a current password. On success the callers session is re-issued (they stay logged in) while all other sessions are revoked.'
// #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
/* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ChangePasswordRequest" } } } } */
/* #swagger.responses[200] = { description: 'Password changed', content: { "application/json": { schema: { $ref: "#/components/schemas/OkFlag" } } } } */
/* #swagger.responses[400] = { description: 'Validation error or wrong current password', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
/* #swagger.responses[403] = { description: 'Account not active (disabled/banned)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
/* #swagger.responses[429] = { description: 'Too many changes (rate limited)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
accountChangeLimiter,
body('newPassword').isString().isLength({ min: 8, max: 64 }),
body('currentPassword').optional({ values: 'falsy' }).isString(),
validate,
account.changePassword,
)
// TOTP self-enrollment — identical to the admin account flow (disable requires a
// valid current code; it does not take a password).
accountRouter.post(
'/totp/setup',
// #swagger.tags = ['Player']
// #swagger.summary = 'Begin 2FA enrollment (returns secret + QR)'
// #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
/* #swagger.responses[200] = { description: 'otpauth URL and QR data to scan', content: { "application/json": { schema: { $ref: "#/components/schemas/TotpSetup" } } } } */
/* #swagger.responses[409] = { description: 'Two-factor already enabled', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
account.totpSetup,
)
accountRouter.post(
'/totp/enable',
// #swagger.tags = ['Player']
// #swagger.summary = 'Enable 2FA by confirming a code'
// #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
/* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/TotpCodeRequest" } } } } */
/* #swagger.responses[200] = { description: '2FA enabled', content: { "application/json": { schema: { $ref: "#/components/schemas/TotpState" } } } } */
/* #swagger.responses[400] = { description: 'Setup not started, or invalid code', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
/* #swagger.responses[409] = { description: 'Two-factor already enabled', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
body('code').isString().trim().isLength({ min: 6, max: 8 }),
validate,
account.totpEnable,
)
accountRouter.post(
'/totp/disable',
// #swagger.tags = ['Player']
// #swagger.summary = 'Disable 2FA by confirming a code'
// #swagger.description = 'Requires a valid current authenticator code (proves control of the authenticator); it does not take a password.'
// #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
/* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/TotpCodeRequest" } } } } */
/* #swagger.responses[200] = { description: '2FA disabled', content: { "application/json": { schema: { $ref: "#/components/schemas/TotpState" } } } } */
/* #swagger.responses[400] = { description: 'Not enabled, or invalid code', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
body('code').isString().trim().isLength({ min: 6, max: 8 }),
validate,
account.totpDisable,
)
// Linked SSO identities (self-service). Linking itself starts at
// GET /auth/sso/:provider/link (already behind requireAuth; works for players).
accountRouter.get(
'/identities',
// #swagger.tags = ['Player']
// #swagger.summary = 'List linked SSO identities (self)'
// #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
/* #swagger.responses[200] = { description: 'Linked identities', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/LinkedIdentity" } } } } } */
account.listIdentities,
)
accountRouter.delete(
'/identities/:provider',
// #swagger.tags = ['Player']
// #swagger.summary = 'Unlink an SSO identity (self)'
// #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
// #swagger.parameters['provider'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Provider id.' }
/* #swagger.responses[200] = { description: 'Unlinked', content: { "application/json": { schema: { $ref: "#/components/schemas/UnlinkedFlag" } } } } */
/* #swagger.responses[404] = { description: 'No linked account for that provider', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
param('provider').matches(/^[a-z0-9-]+$/),
validate,
account.unlinkIdentity,
)
module.exports = accountRouter

View File

@@ -3,19 +3,19 @@
//
// This file owns exactly two things: the gate every player route shares, and the
// mount table. No route is declared here. Each capability router mounts at the
// prefix it already owned inside the old monolithic player.routes.js, so the
// emitted URL set is byte-identical — proved by a zero-line diff in
// server/routes.manifest.json (`npm run routes:manifest`).
// prefix it already owned inside the old monolithic player.routes.js.
//
// Self-service account security (`/player/account/*`) used to be mounted here. It
// is gone: `/auth/me/account/*` is the single canonical self surface for every
// role, and this group's copy was a strictly smaller duplicate of it.
//
// **Staff are a superset of players.** This group is open to any authenticated
// account, not just role 'player': every read/write is self-scoped to req.user.id,
// and a staff member has every player ability plus their staff tools on top.
// Adding a requireRole('player') here would 403 an admin off their own characters
// (it happened once — see docs/website/BACKEND_DESIGN.md). Staff also reach the
// identical self-scoped handlers under /admin/shard and /auth/me/account; those
// are alternative URLs onto the same controllers, not duplicated logic — and
// both of those live in module-uo now, which changes where they are defined and
// nothing about which URLs answer.
// identical self-scoped handlers under /admin/shard, which lives in module-uo now
// — that changes where they are defined and nothing about which URLs answer.
//
// See docs/website/API_V2_PLAN.md § Phase 2 for the split.
@@ -24,7 +24,6 @@ const express = require('express')
const { requireAuth } = require('../../../auth/session.middleware')
const noindex = require('../../../middleware/noindex')
const accountRouter = require('./account.router')
const appealsRouter = require('./appeals.router')
const teamsRouter = require('./teams.router')
const teamForumRouter = require('./teamForum.router')
@@ -39,7 +38,6 @@ const playerRouter = express.Router()
// silently ship without it.
playerRouter.use(noindex, requireAuth)
playerRouter.use('/account', accountRouter)
playerRouter.use('/appeals', appealsRouter)
playerRouter.use('/teams', teamsRouter)
// Same prefix, second router. The forum and the leader-exercised grant flow are a