domma-cms 0.82.0 → 0.83.0

package/server/routes/api/auth.js

@@ -6,8 +6,14 @@
  * GET  /api/auth/me            - return current user from token
  * POST /api/auth/me/avatar     - upload your picture (multipart `file`); DELETE removes it
  * GET  /api/auth/avatar/:name  - an avatar image (public: an <img> cannot send the token)
- * POST /api/auth/refresh       - { refreshToken } → { token }
- * POST /api/auth/logout        - { refreshToken } → { ok: true } - blacklists the refresh token
+ * POST /api/auth/login/verify  - { ticket, response } → tokens, when a sign-in check asked a question (2FA)
+ * POST /api/auth/refresh       - { refreshToken } → { token } - only while its session is live
+ * POST /api/auth/logout        - { refreshToken } → { ok: true } - ends the session
+ * GET  /api/auth/sessions      - your sessions; DELETE /api/auth/sessions/:sid; POST /api/auth/sessions/revoke-others
+ *
+ * Sign-in checks and password checks come from plugins (services/authChecks.js);
+ * sessions live in services/sessions.js. Events: auth:loginFailed, auth:loginSucceeded,
+ * auth:loggedOut, auth:passwordChanged, auth:rateLimited (and user:loggedIn, as before).
  */
 import crypto from 'node:crypto';
 import {config, getConfig} from '../../config.js';
@@ -37,31 +43,29 @@ import nodePath from 'node:path';
 import {buildClearedSessionCookie, buildSessionCookie} from '../../services/viewerSession.js';
 import {createTransport, sendEmail} from '../../services/email.js';
 import {loginFailed, loginRateLimited} from '../../services/notification-sources.js';
+import {afterIndexOf, checkPassword, runLoginChecks, verifyChallenge} from '../../services/authChecks.js';
+import {createSession, isLegacyTokenRevoked, listSessions, revokeLegacyToken, revokeSession, revokeUserSessions, useSession} from '../../services/sessions.js';
 
 const { accessTokenExpiry, refreshTokenExpiry } = config.auth;
 
-/** In-memory blacklist of invalidated refresh tokens (cleared on server restart). */
-const blacklistedRefreshTokens = new Set();
-
 /** Guards the setup endpoint against concurrent first-admin creation requests. */
 let setupInProgress = false;
 
-// Purge expired tokens every 15 minutes to avoid unbounded growth.
+/**
+ * Sign-in tickets: a sign-in waiting on a challenge (two-factor). Single use,
+ * five minutes, five tries. In memory: a restart just means signing in again.
+ */
+const tickets = new Map();
+const TICKET_TRIES = 5;
 setInterval(() => {
-  for (const token of blacklistedRefreshTokens) {
-    try {
-      fastifyRef.jwt.verify(token);
-    } catch {
-      blacklistedRefreshTokens.delete(token);
-    }
-  }
-}, 15 * 60 * 1000);
+    const now = Date.now();
+    for (const [jti, t] of tickets) if (t.expires < now) tickets.delete(jti);
+}, 60_000).unref?.();
 
-/** Holds the fastify instance once routes are registered (needed by the cleanup interval). */
-let fastifyRef;
+const uaOf = (request) => String(request.headers?.['user-agent'] ?? '').slice(0, 300);
+const passwordProblems = (problems) => problems.join(' ');
 
 export async function authRoutes(fastify) {
-  fastifyRef = fastify;
     // GET /api/auth/setup-status
     fastify.get('/auth/setup-status', async () => {
         const count = await countUsers();
@@ -89,10 +93,14 @@ export async function authRoutes(fastify) {
             return reply.status(400).send({ error: 'Password must be at least 8 characters' });
         }
 
+        const problems = await checkPassword(password, {email, name}, {log: fastify.log});
+        if (problems.length) return reply.status(400).send({error: passwordProblems(problems), problems});
+
         setupInProgress = true;
         try {
             const user = await createUser({name, email, password, role: 'super-admin'});
-            const {token, refreshToken} = signTokens(fastify, user);
+            const sid = await createSession({userId: user.id, ip: request.ip, ua: uaOf(request), ttlMs: parseDuration(refreshTokenExpiry)});
+            const {token, refreshToken} = signTokens(fastify, user, sid);
             return reply.status(201).send({token, refreshToken, user});
         } finally {
             setupInProgress = false;
@@ -100,31 +108,112 @@ export async function authRoutes(fastify) {
     });
 
     // POST /api/auth/login
-    fastify.post('/auth/login', { config: { rateLimit: { max: 5, timeWindow: '1 minute', onExceeded: (req) => { loginRateLimited(req.ip); } } } }, async (request, reply) => {
+    fastify.post('/auth/login', { config: { rateLimit: { max: 5, timeWindow: '1 minute', onExceeded: (req) => {
+        loginRateLimited(req.ip);
+        hooks.emit('auth:rateLimited', {ip: req.ip, ua: uaOf(req), route: '/api/auth/login'});
+    } } } }, async (request, reply) => {
         const { email, password } = request.body || {};
         if (!email || !password) {
             return reply.status(400).send({ error: 'email and password are required' });
         }
+        const ip = request.ip;
+        const ua = uaOf(request);
+        const failed = (reason, extra = {}) => {
+            loginFailed(email, ip);
+            hooks.emit('auth:loginFailed', {email: String(email).toLowerCase().trim(), ip, ua, reason, ...extra});
+        };
 
         const user = await getUserByEmail(email);
+        // Before the password is looked at: a lockout refuses right or wrong alike.
+        const pre = await runLoginChecks('before', {email, user: user && user.isActive ? user : null, request, ip, ua}, {log: fastify.log});
+        if (pre.deny) {
+            failed('denied', {by: pre.by, userId: user?.id ?? null});
+            return reply.status(pre.status).send({error: pre.message});
+        }
+
         if (!user || !user.isActive) {
-            loginFailed(email, request.ip);
+            failed(user ? 'inactive' : 'unknown');
             return reply.status(401).send({ error: 'Invalid credentials' });
         }
 
         const valid = await validatePassword(password, user.password);
         if (!valid) {
-            loginFailed(email, request.ip);
+            failed('password', {userId: user.id});
             return reply.status(401).send({ error: 'Invalid credentials' });
         }
 
-        await touchLastLogin(user.id);
+        return continueLogin(user, request, reply, 0);
+    });
 
+    /**
+     * The password was right: the 'after' checks from `start`, then tokens - or a
+     * challenge, answered at /auth/login/verify.
+     */
+    async function continueLogin(user, request, reply, start) {
+        const ip = request.ip;
+        const ua = uaOf(request);
+        const after = await runLoginChecks('after', {email: user.email, user, request, ip, ua}, {start, log: fastify.log});
+        if (after.deny) {
+            loginFailed(user.email, ip);
+            hooks.emit('auth:loginFailed', {email: user.email, ip, ua, reason: 'denied', by: after.by, userId: user.id});
+            return reply.status(after.status).send({error: after.message});
+        }
+        if (after.challenge) {
+            const jti = crypto.randomBytes(12).toString('hex');
+            tickets.set(jti, {userId: user.id, by: after.by, index: after.index, tries: 0, expires: Date.now() + 5 * 60_000});
+            const ticket = fastify.jwt.sign({type: 'login-ticket', id: user.id, jti}, {expiresIn: '5m'});
+            const c = after.challenge;
+            return {challenge: {kind: String(c.kind || 'code'), label: String(c.label || 'Code'), help: String(c.help || ''),
+                inputMode: c.inputMode === 'text' ? 'text' : 'numeric', recovery: c.recovery === true, trust: c.trust === true}, ticket};
+        }
+        return finishLogin(user, request, reply);
+    }
+
+    /** Signed in: a session, tokens, the events. */
+    async function finishLogin(user, request, reply) {
+        const ip = request.ip;
+        const ua = uaOf(request);
+        await touchLastLogin(user.id);
+        const sid = await createSession({userId: user.id, ip, ua, ttlMs: parseDuration(refreshTokenExpiry)});
         const safeUser = { id: user.id, name: user.name, email: user.email, role: user.role, additionalRoles: user.additionalRoles || [], level: getRoleLevel(user.role) };
         hooks.emit('user:loggedIn', {userId: user.id, email: user.email, role: user.role});
-        const { token, refreshToken } = signTokens(fastify, safeUser);
+        hooks.emit('auth:loginSucceeded', {userId: user.id, email: user.email, role: user.role, ip, ua, sid});
+        const { token, refreshToken } = signTokens(fastify, safeUser, sid);
         setSessionCookie(request, reply, token);
-        return { token, refreshToken, user: safeUser };
+        return { token, refreshToken, user: {...safeUser, ...(user.avatar && {avatar: user.avatar})} };
+    }
+
+    // POST /api/auth/login/verify - the answer to a sign-in challenge (two-factor)
+    fastify.post('/auth/login/verify', {config: {rateLimit: {max: 10, timeWindow: '1 minute'}}}, async (request, reply) => {
+        const {ticket, response, trust, mode} = request.body || {};
+        let payload;
+        try {
+            payload = fastify.jwt.verify(String(ticket || ''));
+        } catch {
+            return reply.status(401).send({error: 'This sign-in has timed out. Sign in again.'});
+        }
+        const t = payload?.type === 'login-ticket' ? tickets.get(payload.jti) : null;
+        if (!t || t.userId !== payload.id) return reply.status(401).send({error: 'This sign-in has timed out. Sign in again.'});
+        const user = await getUserById(t.userId);
+        if (!user || !user.isActive) {
+            tickets.delete(payload.jti);
+            return reply.status(401).send({error: 'Invalid credentials'});
+        }
+        const out = await verifyChallenge(t.by, {user, request, response: String(response ?? '').slice(0, 200), mode: mode === 'recovery' ? 'recovery' : 'code', trust: trust === true, ip: request.ip, ua: uaOf(request)});
+        if (!out.ok) {
+            t.tries++;
+            loginFailed(user.email, request.ip);
+            hooks.emit('auth:loginFailed', {email: user.email, ip: request.ip, ua: uaOf(request), reason: 'challenge', by: t.by, userId: user.id});
+            if (t.tries >= TICKET_TRIES) {
+                tickets.delete(payload.jti);
+                return reply.status(401).send({error: 'Too many tries. Sign in again.'});
+            }
+            return reply.status(401).send({error: out.message, triesLeft: TICKET_TRIES - t.tries});
+        }
+        tickets.delete(payload.jti);
+        const next = afterIndexOf(t.by);
+        if (out.trust) reply.header('set-cookie', out.trust);
+        return continueLogin(user, request, reply, next < 0 ? 0 : next + 1);
     });
 
     // GET /api/auth/permissions - returns the raw permissions array for the authenticated user's role
@@ -183,6 +272,11 @@ export async function authRoutes(fastify) {
         if (password && password.length < 8) {
             return reply.status(400).send({error: 'Password must be at least 8 characters'});
         }
+        if (password) {
+            const me = await getUserById(id);
+            const problems = await checkPassword(password, {email: email || me?.email, name: name || me?.name, userId: id, request}, {log: fastify.log});
+            if (problems.length) return reply.status(400).send({error: passwordProblems(problems), problems});
+        }
 
         const coreUpdates = {};
         if (name) coreUpdates.name = name;
@@ -200,11 +294,38 @@ export async function authRoutes(fastify) {
         if (profile && typeof profile === 'object') {
             await updateProfile(id, profile);
         }
+        if (password) {
+            // A new password ends every other session - the old one may be why it changed.
+            await revokeUserSessions(id, {except: request.user.sid || null});
+            hooks.emit('auth:passwordChanged', {userId: id, by: id, ip: request.ip, ua: uaOf(request)});
+        }
 
         const profileEntry = await getProfile(id);
         return {...user, profile: profileEntry?.data || {}};
     });
 
+    // GET /api/auth/sessions - your sessions (the one you are using marked)
+    fastify.get('/auth/sessions', {preHandler: [authenticate]}, async (request) => {
+        const list = await listSessions({userId: request.user.id});
+        return list.map(s => ({sid: s.sid, createdAt: s.createdAt, lastUsedAt: s.lastUsedAt, expiresAt: s.expiresAt,
+            ip: s.ip, ua: s.ua, current: s.sid === request.user.sid}));
+    });
+
+    // DELETE /api/auth/sessions/:sid - end one of your sessions
+    fastify.delete('/auth/sessions/:sid', {preHandler: [authenticate]}, async (request, reply) => {
+        const ok = await revokeSession(String(request.params.sid), {userId: request.user.id});
+        if (!ok) return reply.status(404).send({error: 'Session not found'});
+        hooks.emit('auth:loggedOut', {userId: request.user.id, sid: request.params.sid, ip: request.ip, by: request.user.id});
+        return {ok: true};
+    });
+
+    // POST /api/auth/sessions/revoke-others - sign out everywhere else
+    fastify.post('/auth/sessions/revoke-others', {preHandler: [authenticate]}, async (request) => {
+        const n = await revokeUserSessions(request.user.id, {except: request.user.sid || null});
+        hooks.emit('auth:loggedOut', {userId: request.user.id, all: true, ip: request.ip, by: request.user.id});
+        return {ok: true, ended: n};
+    });
+
     // POST /api/auth/me/avatar - your picture: any common image, stored as a 256 px WebP
     fastify.post('/auth/me/avatar', {preHandler: [authenticate], config: {rateLimit: {max: 20, timeWindow: '10 minutes'}}}, async (request, reply) => {
         const upload = await request.file({limits: {fileSize: AVATAR_MAX_BYTES, files: 1}}).catch(() => null);
@@ -336,18 +457,32 @@ export async function authRoutes(fastify) {
             return reply.status(400).send({error: 'Invalid or expired reset link'});
         }
 
+        const problems = await checkPassword(password, {email: user.email, name: user.name, userId: user.id, request}, {log: fastify.log});
+        if (problems.length) return reply.status(400).send({error: passwordProblems(problems), problems});
+
         await updateUser(user.id, {password});
         await clearResetToken(user.id);
+        await revokeUserSessions(user.id);
+        hooks.emit('auth:passwordChanged', {userId: user.id, by: 'reset', ip: request.ip, ua: uaOf(request)});
         return {ok: true};
     });
 
-  // POST /api/auth/logout - blacklists the refresh token (fire-and-forget safe: no auth required)
-  fastify.post('/auth/logout', async (request, reply) => {
-    const {refreshToken} = request.body || {};
-    if (refreshToken) blacklistedRefreshTokens.add(refreshToken);
-    reply.header('set-cookie', buildClearedSessionCookie({secure: request.protocol === 'https'}));
-    return {ok: true};
-  });
+    // POST /api/auth/logout - ends the session (fire-and-forget safe: no auth required)
+    fastify.post('/auth/logout', async (request, reply) => {
+        const {refreshToken} = request.body || {};
+        if (refreshToken) {
+            try {
+                const p = fastify.jwt.verify(String(refreshToken));
+                if (p?.type === 'refresh') {
+                    if (p.sid) await revokeSession(p.sid, {userId: p.id});
+                    else await revokeLegacyToken(refreshToken, p.exp);
+                    hooks.emit('auth:loggedOut', {userId: p.id, sid: p.sid || null, ip: request.ip, by: p.id});
+                }
+            } catch { /* expired or not ours: nothing to end */ }
+        }
+        reply.header('set-cookie', buildClearedSessionCookie({secure: request.protocol === 'https'}));
+        return {ok: true};
+    });
 
     // POST /api/auth/refresh
     fastify.post('/auth/refresh', async (request, reply) => {
@@ -356,10 +491,6 @@ export async function authRoutes(fastify) {
             return reply.status(400).send({ error: 'refreshToken is required' });
         }
 
-      if (blacklistedRefreshTokens.has(refreshToken)) {
-        return reply.status(401).send({error: 'Refresh token has been revoked'});
-      }
-
         let payload;
         try {
             payload = fastify.jwt.verify(refreshToken);
@@ -371,13 +502,22 @@ export async function authRoutes(fastify) {
             return reply.status(401).send({ error: 'Invalid token type' });
         }
 
+        // The session behind it must still be live (signed out, "everywhere", a new password end it).
+        if (payload.sid) {
+            if (!await useSession(payload.sid, {userId: payload.id, ip: request.ip, ua: uaOf(request)})) {
+                return reply.status(401).send({error: 'This session has ended. Sign in again.'});
+            }
+        } else if (await isLegacyTokenRevoked(refreshToken)) {
+            return reply.status(401).send({error: 'Refresh token has been revoked'});
+        }
+
         const user = await getUserById(payload.id);
         if (!user || !user.isActive) {
             return reply.status(401).send({ error: 'User not found or inactive' });
         }
 
         const safeUser = { id: user.id, name: user.name, email: user.email, role: user.role, additionalRoles: user.additionalRoles || [], level: getRoleLevel(user.role) };
-        const token = fastify.jwt.sign({ ...safeUser, type: 'access' }, { expiresIn: accessTokenExpiry });
+        const token = fastify.jwt.sign({ ...safeUser, type: 'access', ...(payload.sid && {sid: payload.sid}) }, { expiresIn: accessTokenExpiry });
         setSessionCookie(request, reply, token);
         return { token };
     });
@@ -427,10 +567,11 @@ function parseDuration(str) {
  *
  * @param {object} fastify
  * @param {object} payload
+ * @param {string|null} [sid] - the session (services/sessions.js) both tokens belong to
  * @returns {{ token: string, refreshToken: string }}
  */
-function signTokens(fastify, payload) {
-    const token = fastify.jwt.sign({ ...payload, type: 'access' }, { expiresIn: accessTokenExpiry });
-    const refreshToken = fastify.jwt.sign({ id: payload.id, type: 'refresh' }, { expiresIn: refreshTokenExpiry });
+function signTokens(fastify, payload, sid = null) {
+    const token = fastify.jwt.sign({ ...payload, type: 'access', ...(sid && {sid}) }, { expiresIn: accessTokenExpiry });
+    const refreshToken = fastify.jwt.sign({ id: payload.id, type: 'refresh', ...(sid && {sid}) }, { expiresIn: refreshTokenExpiry });
     return { token, refreshToken };
 }

package/server/routes/api/users.js

@@ -13,6 +13,9 @@ import {createUser, deleteUser, getUserById, listUsers, updateUser} from '../../
 import {getProfile, listProfiles, updateProfile} from '../../services/userProfiles.js';
 import {ago, clip, plural} from '../../services/sidebarBadges.js';
 import * as notices from '../../services/notification-sources.js';
+import {checkPassword} from '../../services/authChecks.js';
+import {revokeUserSessions} from '../../services/sessions.js';
+import {hooks} from '../../services/hooks.js';
 
 /**
  * The sidebar badge on Users (its countUrl, GET /api/users/_count). The number
@@ -105,6 +108,9 @@ export async function usersRoutes(fastify) {
             return reply.status(400).send({ error: 'Password must be at least 8 characters' });
         }
 
+        const problems = await checkPassword(password, {email, name, request}, {log: request.log});
+        if (problems.length) return reply.status(400).send({error: problems.join(' '), problems});
+
         const targetRole = role || 'user';
         // Pass the full actor object so multi-role privilege is evaluated;
         // for the prospective target we only have a primary role here.
@@ -177,6 +183,14 @@ export async function usersRoutes(fastify) {
             updates.additionalRoles = updates.additionalRoles.filter(r => r && r !== primary);
         }
 
+        if (updates.password !== undefined) {
+            if (typeof updates.password !== 'string' || updates.password.length < 8) {
+                return reply.status(400).send({error: 'Password must be at least 8 characters'});
+            }
+            const problems = await checkPassword(updates.password, {email: updates.email || target.email, name: updates.name || target.name, userId: id, request}, {log: request.log});
+            if (problems.length) return reply.status(400).send({error: problems.join(' '), problems});
+        }
+
         // Strip profile from core updates and handle separately
         const {profile, ...coreUpdates} = updates;
         let user;
@@ -191,6 +205,12 @@ export async function usersRoutes(fastify) {
             await updateProfile(id, profile);
         }
 
+        // A new password, or a switched-off account: their sessions end (yours, on a self-edit, stays).
+        if (updates.password || (updates.isActive === false && target.isActive !== false)) {
+            await revokeUserSessions(id, {except: isSelf ? (actor.sid || null) : null});
+            if (updates.password) hooks.emit('auth:passwordChanged', {userId: id, by: actor.id, ip: request.ip});
+        }
+
         // Admin rights given (not kept): the Super Admins hear about it.
         const adminRoles = (u) => [u?.role, ...(Array.isArray(u?.additionalRoles) ? u.additionalRoles : [])]
             .filter(r => r === 'admin' || r === 'super-admin');

package/server/server.js

@@ -29,6 +29,7 @@ import {seedDefaultBlocks} from './services/blocks.js';
 import {seedDefaultComponents} from './services/components.js';
 import {refreshComponentTagAllowlist} from './services/markdown.js';
 import * as cache from './services/cache/index.js';
+import {isGenuinelyLocal, parseTrustProxy} from './services/network.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, '..');
@@ -83,10 +84,11 @@ function resolveLogLevel() {
 
 const app = Fastify({
     logger: {level: resolveLogLevel()},
-    // When running behind a reverse proxy (e.g. domma-cms-manager), trust the
-    // X-Forwarded-For header so @fastify/rate-limit keys on the real client IP
-    // rather than the proxy's loopback address.
-    trustProxy: !!process.env.TRUST_PROXY,
+    // Behind a reverse proxy (Apache, domma-cms-manager), trust the proxy so
+    // request.ip is the visitor, not the proxy's loopback. TRUST_PROXY=loopback
+    // is the right value (right-most X-Forwarded-For entry a local proxy did not
+    // add); 1 / true still trusts every hop - see services/network.js.
+    trustProxy: parseTrustProxy(process.env.TRUST_PROXY),
 });
 
 // Register process error handlers immediately so startup errors are captured
@@ -148,9 +150,10 @@ await app.register(rateLimit, {
     global: true, // apply default limit to all routes; stricter per-route limits override this
     max: 500,
     timeWindow: '1 minute',
-    // Loopback is always exempt - local admin use should never be rate-limited.
-    // When behind a reverse proxy (TRUST_PROXY), the proxy's loopback is also exempt.
-    allowList: ['127.0.0.1', '::1', '::ffff:127.0.0.1'],
+    // Only a genuinely local call is exempt (loopback socket, no X-Forwarded-For).
+    // A static loopback list exempted every visitor relayed by a proxy that is
+    // not trusted - on dcm, everyone, the login included. See services/network.js.
+    allowList: (request) => isGenuinelyLocal(request),
 });
 
 // Negotiates brotli/gzip/deflate per Accept-Encoding. Skips already-compressed
@@ -367,6 +370,21 @@ app.addHook('onResponse', async (request, reply) => {
         app.log.warn(`[cache] Admin change did not clear the cache: ${err.message}`);
     }
 });
+
+// Audit: every successful signed-in change through the API becomes an `audit`
+// event (services/audit.js). Core keeps nothing; Security Pro stores the trail.
+{
+    const {auditEventFor} = await import('./services/audit.js');
+    const {hooks: auditHooks} = await import('./services/hooks.js');
+    app.addHook('onResponse', async (request, reply) => {
+        try {
+            const event = auditEventFor(request, reply);
+            if (event) auditHooks.emit('audit', event);
+        } catch (err) {
+            app.log.warn(`[audit] event not raised: ${err.message}`);
+        }
+    });
+}
 console.log(`[cache] driver=${cache.isEnabled() ? config.cache.driver : 'disabled'}`);
 
 // Docs are rendered at request time from the shipped admin templates; clear any

package/server/services/audit.js

@@ -0,0 +1,63 @@
+/**
+ * Audit events - every change a signed-in person makes through the API.
+ *
+ * One `onResponse` hook (server.js) turns each successful POST / PUT / PATCH /
+ * DELETE under /api/ by a signed-in user into `hooks.emit('audit', event)`.
+ * Core stores nothing; Security Pro keeps the trail. Done once, here, rather
+ * than route by route, so a new route - or a plugin's - is covered without
+ * anyone remembering to.
+ *
+ * An event carries the NAMES of the fields sent, never their values: bodies hold
+ * passwords, SMTP credentials and API keys.
+ */
+
+const MUTATING = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+
+/** Routes with events of their own (auth:*), or that are not someone changing something. */
+const SKIP = [
+    /^\/api\/auth\/(login|login\/verify|refresh|logout|forgot-password|reset-password|setup)$/,
+    /^\/api\/analytics\//,
+    /^\/api\/notifications\/(read|seen|dismiss)/,
+    /\/(preview|render|validate|search)$/
+];
+
+const VERB = {POST: 'created', PUT: 'updated', PATCH: 'updated', DELETE: 'deleted'};
+
+/**
+ * The event for a finished request, or null when it is not one.
+ *
+ * @param {{method: string, url: string, routeOptions?: {url?: string}, params?: object, body?: any, user?: object, ip?: string, headers?: object}} request
+ * @param {{statusCode: number}} reply
+ * @returns {null | {at: string, actor: {id: string, name: string, email: string, role: string}, action: string,
+ *                   method: string, route: string, path: string, target: object, fields: string[], status: number, ip: string}}
+ */
+export function auditEventFor(request, reply) {
+    if (!MUTATING.has(request.method)) return null;
+    const status = reply.statusCode;
+    if (status < 200 || status >= 300) return null;
+    const path = String(request.url || '').split('?')[0];
+    if (!path.startsWith('/api/')) return null;
+    const route = String(request.routeOptions?.url || path);
+    if (SKIP.some(re => re.test(route))) return null;
+    const u = request.user;
+    if (!u?.id) return null;
+
+    // "/api/plugins/blog/posts/:id" -> resource "plugins/blog/posts".
+    const resource = route.replace(/^\/api\//, '').split('/').filter(p => p && !p.startsWith(':')).join('/') || 'api';
+    const body = request.body;
+    const fields = body && typeof body === 'object' && !Array.isArray(body) && !Buffer.isBuffer(body)
+        ? Object.keys(body).slice(0, 40)
+        : [];
+    return {
+        at: new Date().toISOString(),
+        actor: {id: String(u.id), name: String(u.name || ''), email: String(u.email || ''), role: String(u.role || '')},
+        action: `${resource} ${VERB[request.method]}`,
+        method: request.method,
+        route,
+        path: path.slice(0, 300),
+        target: {...(request.params || {})},
+        fields,
+        status,
+        ip: String(request.ip || '')
+    };
+}

package/server/services/authChecks.js

@@ -0,0 +1,128 @@
+/**
+ * Sign-in and password checks that plugins add (Security, Security Pro).
+ *
+ * Login checks run in two phases:
+ *   - `before`: before the password is looked at, with the email and request
+ *     (the user if one exists). A lockout lives here, so a locked-out attacker
+ *     learns nothing - not even whether the password was right.
+ *   - `after`: once the password is right, with the user. Two-factor lives here.
+ * A check answers:
+ *   {allow: true}                              - carry on
+ *   {deny: true, message, status?}              - refuse, with this message (429/403/401)
+ *   {challenge: {kind, label, help, ...}}        - ask for something more ('after' only)
+ * A challenge makes the login answer `{challenge, ticket}`; the admin posts
+ * `{ticket, response}` to /api/auth/login/verify, the check's `verify()` decides,
+ * and the remaining checks run from the next one.
+ *
+ * Password checks run wherever a password is set (setup, create user, update
+ * user, My Profile, reset). Each returns '' or a message; every message is shown.
+ *
+ * A check that THROWS is logged and skipped (sign-in must not break because a
+ * plugin did) - except in `verify()`, where a throw is a refusal.
+ */
+
+const loginChecks = [];
+const passwordChecks = [];
+
+const errOf = (err) => (err && err.message) || String(err);
+
+/**
+ * @param {string} owner - the plugin's name
+ * @param {{id: string, phase?: 'before'|'after', check: Function, verify?: Function}} def
+ */
+export function registerLoginCheck(owner, def) {
+    if (!def || typeof def.check !== 'function' || !def.id) throw new Error('registerLoginCheck needs {id, check}');
+    const id = `${owner}:${def.id}`;
+    const at = loginChecks.findIndex(c => c.id === id);
+    const entry = {...def, id, owner, phase: def.phase === 'before' ? 'before' : 'after'};
+    if (at >= 0) loginChecks[at] = entry;
+    else loginChecks.push(entry);
+}
+
+/**
+ * @param {string} owner
+ * @param {{id: string, check: (password: string, ctx: object) => Promise<string>|string}} def
+ */
+export function registerPasswordCheck(owner, def) {
+    if (!def || typeof def.check !== 'function' || !def.id) throw new Error('registerPasswordCheck needs {id, check}');
+    const id = `${owner}:${def.id}`;
+    const at = passwordChecks.findIndex(c => c.id === id);
+    if (at >= 0) passwordChecks[at] = {...def, id, owner};
+    else passwordChecks.push({...def, id, owner});
+}
+
+/** Plugins unloading (tests, a disabled plugin on restart): forget their checks. */
+export function clearChecks(owner = null) {
+    for (const list of [loginChecks, passwordChecks]) {
+        for (let i = list.length - 1; i >= 0; i--) if (!owner || list[i].owner === owner) list.splice(i, 1);
+    }
+}
+
+export const loginCheckIds = () => loginChecks.map(c => c.id);
+
+/**
+ * Run the login checks of a phase, from `start` (an index into that phase's list).
+ *
+ * @param {'before'|'after'} phase
+ * @param {object} ctx - {email, user, request, ip, ua}
+ * @param {{start?: number, log?: {warn: Function}}} [opts]
+ * @returns {Promise<{allow: true} | {deny: true, message: string, status: number, by: string}
+ *                   | {challenge: object, by: string, index: number}>}
+ */
+export async function runLoginChecks(phase, ctx, {start = 0, log = console} = {}) {
+    const list = loginChecks.filter(c => c.phase === phase);
+    for (let i = start; i < list.length; i++) {
+        const c = list[i];
+        let out;
+        try {
+            out = await c.check(ctx);
+        } catch (err) {
+            log.warn?.(`[auth] login check ${c.id} failed, skipped: ${errOf(err)}`);
+            continue;
+        }
+        if (!out || out.allow) continue;
+        if (out.deny) return {deny: true, message: String(out.message || 'Sign-in refused.'), status: Number(out.status) || 403, by: c.id};
+        if (out.challenge && phase === 'after' && typeof c.verify === 'function') {
+            return {challenge: {...out.challenge}, by: c.id, index: i};
+        }
+    }
+    return {allow: true};
+}
+
+/**
+ * A challenge answered: the check that asked verifies it.
+ *
+ * @returns {Promise<{ok: boolean, message?: string, trust?: object}>}
+ */
+export async function verifyChallenge(by, ctx) {
+    const c = loginChecks.find(x => x.id === by && x.phase === 'after');
+    if (!c || typeof c.verify !== 'function') return {ok: false, message: 'This sign-in step is no longer available. Sign in again.'};
+    try {
+        const out = await c.verify(ctx);
+        return out && out.ok ? {ok: true, ...(out.trust && {trust: out.trust})} : {ok: false, message: String(out?.message || 'That did not match.')};
+    } catch (err) {
+        return {ok: false, message: 'That could not be checked. Try again.'};
+    }
+}
+
+/** The index, among the 'after' checks, of a check by id (-1 when gone). */
+export const afterIndexOf = (by) => loginChecks.filter(c => c.phase === 'after').findIndex(c => c.id === by);
+
+/**
+ * Every password check's objection, in order ([] = fine).
+ *
+ * @param {string} password
+ * @param {{email?: string, name?: string, userId?: string, request?: object}} ctx
+ */
+export async function checkPassword(password, ctx = {}, {log = console} = {}) {
+    const problems = [];
+    for (const c of passwordChecks) {
+        try {
+            const msg = await c.check(password, ctx);
+            if (msg) problems.push(String(msg));
+        } catch (err) {
+            log.warn?.(`[auth] password check ${c.id} failed, skipped: ${errOf(err)}`);
+        }
+    }
+    return problems;
+}