Add admin identity module: better-auth, per-app permissions, invitations

Introduces src/models/admin/, a dedicated identity and permissions module on its own nachklang_admin database, and the shared authenticator that feedback and tickets will move onto in the cutover step. Nothing swaps over yet: feedback.auth.ts and tickets.auth.ts still authenticate against the legacy calendar sessions, so production behaviour is unchanged. - better-auth 1.7 mounted at /admin/auth/*, sessions as httpOnly cookies scoped to .nachklang.art so one sign-in covers every *.nachklang.art app. - Accounts are invite-only: public sign-up is disabled, and the invitations plugin is the only code that creates users. Tokens are stored as SHA-256 hashes and travel in the request body, never in a URL. - Per-app permissions in user_app_permissions; requireAppAccess(app) queries the database on every request (no cookie cache) so disabling a user or revoking a session takes effect immediately. - ADMIN_BOOTSTRAP_EMAIL guarantees a way in on an empty database, idempotently and without crashing the API if the database is unreachable at boot. - Guards prevent an admin from removing their own admin permission, disabling themselves, or stripping the last active admin. The admin pool uses the callback-style mysql2, not mysql2/promise: Kysely's MysqlDialect drives the pool with callbacks, and the promise wrapper ignores them, so every query hangs silently. Only the integration tests caught this. Schema in sql/admin/001_init.sql, derived from getAuthTables() on the installed better-auth rather than the published CLI, which lags the library and omits account.issuer. app.ts is split into src/app.factory.ts so the integration tests drive the real middleware order rather than a copy of it. Tests: 131 unit, plus 41 integration tests against a throwaway MariaDB started by test/integration/setup.ts (docker or podman). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-05 18:03:08 +02:00
parent bf7f45acce
commit 7aac07a013
37 changed files with 5620 additions and 320 deletions
@@ -0,0 +1,174 @@
+import {vi, describe, it, expect, beforeEach, type Mock} from 'vitest';
+import {Request, Response} from 'express';
+
+vi.mock('../../src/models/admin/admin.auth.js', () => ({
+	auth: {api: {getSession: vi.fn()}}
+}));
+vi.mock('../../src/models/admin/users/users.admin.service.js', () => ({
+	loadAccess: vi.fn()
+}));
+
+import {auth} from '../../src/models/admin/admin.auth.js';
+import * as UsersService from '../../src/models/admin/users/users.admin.service.js';
+import {requireAppAccess, requireSignedIn, resolveAccess} from '../../src/models/admin/admin.middleware.js';
+
+const mockGetSession = auth.api.getSession as unknown as Mock;
+const mockLoadAccess = UsersService.loadAccess as Mock;
+
+const makeReq = (): Request => ({headers: {cookie: 'nachklang.session_token=abc'}} as unknown as Request);
+
+const makeRes = (): Response => {
+	const res: any = {};
+	res.status = vi.fn().mockReturnValue(res);
+	res.send = vi.fn().mockReturnValue(res);
+	res.locals = {};
+	return res as Response;
+};
+
+const activeUser = {
+	id: 'u1',
+	email: 'a@nachklang.art',
+	displayName: 'A',
+	disabled: false,
+	apps: ['feedback', 'admin']
+};
+
+describe('resolveAccess', () => {
+	beforeEach(() => {
+		mockGetSession.mockReset();
+		mockLoadAccess.mockReset();
+	});
+
+	it('returns null without a valid session', async () => {
+		mockGetSession.mockResolvedValue(null);
+		expect(await resolveAccess(makeReq())).toBeNull();
+		expect(mockLoadAccess).not.toHaveBeenCalled();
+	});
+
+	it('returns null when the session points at a user row that is gone', async () => {
+		mockGetSession.mockResolvedValue({user: {id: 'u1'}});
+		mockLoadAccess.mockResolvedValue(null);
+		expect(await resolveAccess(makeReq())).toBeNull();
+	});
+
+	it('resolves identity and permissions in a single permission query', async () => {
+		mockGetSession.mockResolvedValue({user: {id: 'u1'}});
+		mockLoadAccess.mockResolvedValue(activeUser);
+
+		expect(await resolveAccess(makeReq())).toEqual({
+			id: 'u1',
+			email: 'a@nachklang.art',
+			displayName: 'A',
+			disabled: false,
+			apps: ['feedback', 'admin']
+		});
+		// No cookieCache: exactly one lookup per request, never zero.
+		expect(mockLoadAccess).toHaveBeenCalledTimes(1);
+	});
+});
+
+describe('requireSignedIn', () => {
+	beforeEach(() => {
+		mockGetSession.mockReset();
+		mockLoadAccess.mockReset();
+	});
+
+	it('401s without a session', async () => {
+		mockGetSession.mockResolvedValue(null);
+		const res = makeRes();
+		const next = vi.fn();
+
+		await requireSignedIn(makeReq(), res, next);
+
+		expect(res.status).toHaveBeenCalledWith(401);
+		expect(next).not.toHaveBeenCalled();
+	});
+
+	it('403s a disabled user that still holds a valid cookie', async () => {
+		mockGetSession.mockResolvedValue({user: {id: 'u1'}});
+		mockLoadAccess.mockResolvedValue({...activeUser, disabled: true});
+		const res = makeRes();
+		const next = vi.fn();
+
+		await requireSignedIn(makeReq(), res, next);
+
+		expect(res.status).toHaveBeenCalledWith(403);
+		expect(next).not.toHaveBeenCalled();
+	});
+
+	it('admits a signed-in user with no app permissions at all', async () => {
+		mockGetSession.mockResolvedValue({user: {id: 'u1'}});
+		mockLoadAccess.mockResolvedValue({...activeUser, apps: []});
+		const res = makeRes();
+		const next = vi.fn();
+
+		await requireSignedIn(makeReq(), res, next);
+
+		expect(next).toHaveBeenCalled();
+		expect(res.locals.admin.apps).toEqual([]);
+	});
+});
+
+describe('requireAppAccess', () => {
+	beforeEach(() => {
+		mockGetSession.mockReset();
+		mockLoadAccess.mockReset();
+	});
+
+	it('401s without a session', async () => {
+		mockGetSession.mockResolvedValue(null);
+		const res = makeRes();
+		const next = vi.fn();
+
+		await requireAppAccess('feedback')(makeReq(), res, next);
+
+		expect(res.status).toHaveBeenCalledWith(401);
+	});
+
+	it('403s a signed-in user without that app permission', async () => {
+		mockGetSession.mockResolvedValue({user: {id: 'u1'}});
+		mockLoadAccess.mockResolvedValue({...activeUser, apps: ['feedback']});
+		const res = makeRes();
+		const next = vi.fn();
+
+		await requireAppAccess('tickets')(makeReq(), res, next);
+
+		expect(res.status).toHaveBeenCalledWith(403);
+		expect(next).not.toHaveBeenCalled();
+	});
+
+	it('403s a disabled user even when they hold the permission', async () => {
+		mockGetSession.mockResolvedValue({user: {id: 'u1'}});
+		mockLoadAccess.mockResolvedValue({...activeUser, disabled: true});
+		const res = makeRes();
+		const next = vi.fn();
+
+		await requireAppAccess('feedback')(makeReq(), res, next);
+
+		expect(res.status).toHaveBeenCalledWith(403);
+	});
+
+	it('passes through and exposes the identity the feedback/tickets services expect', async () => {
+		mockGetSession.mockResolvedValue({user: {id: 'u1'}});
+		mockLoadAccess.mockResolvedValue(activeUser);
+		const res = makeRes();
+		const next = vi.fn();
+
+		await requireAppAccess('feedback')(makeReq(), res, next);
+
+		expect(next).toHaveBeenCalled();
+		expect(res.locals.admin).toMatchObject({id: 'u1', email: 'a@nachklang.art', displayName: 'A'});
+	});
+
+	it('500s (never allows through) when the permission query throws', async () => {
+		mockGetSession.mockResolvedValue({user: {id: 'u1'}});
+		mockLoadAccess.mockRejectedValue(new Error('db down'));
+		const res = makeRes();
+		const next = vi.fn();
+
+		await requireAppAccess('feedback')(makeReq(), res, next);
+
+		expect(res.status).toHaveBeenCalledWith(500);
+		expect(next).not.toHaveBeenCalled();
+	});
+});