Scope step 5 of the calendar migration, and gate it on step 4 being live

Step 5 removes the legacy path, so it removes the fallback step 4 still leans
on: the join that renders the author of every pre-cutover event, and the
routes an old cached bundle talks to. Building it before step 4 has been
deployed and watched turns a recoverable deploy into an unrecoverable one, so
this records the shape rather than implementing it.

Two decisions worth having in the runbook rather than in someone's memory.
The legacy calendar user module gets deleted outright rather than unmounted -
a survey confirmed nothing outside that directory imports it, and it is the
API's last unauthenticated account-creation and mail-sending endpoint. The
users and sessions tables get renamed aside rather than dropped: the display
names are already snapshotted so nothing visible depends on those rows, but
they still hold e-mail addresses and password hashes, and a rename makes them
unreachable without destroying anything.

Also notes the two consequences worth accepting deliberately: activation links
already in inboxes become 404s, and createdById leaves the wire format.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.env.example

@@ -1,5 +1,11 @@
 # Values containing #, ", \ or surrounding spaces must be single-quoted
 # (dotenv 16 treats an unquoted # as a comment): DB_PASSWORD='abc#def'
+# REQUIRED. The admin module treats anything other than "development" or "test"
+# as production: strict secrets, cross-subdomain cookies, no relaxed CORS.
+# Leaving it unset is therefore safe-by-default but will refuse to boot without
+# the admin secrets below. Set it to development for local work.
+NODE_ENV=development
+
 PORT=3000
 
 DB_HOST=
@@ -25,6 +31,41 @@ TICKETS_DB=
 TICKETS_RATE_LIMIT_MAX=10
 TICKETS_RATE_LIMIT_WINDOW_MIN=10
 
+ADMIN_DB=
+# 32+ random bytes, e.g. `openssl rand -base64 48`. Mandatory outside
+# development/test - there is deliberately no fallback, since a hardcoded one
+# would be a published signing key. Rotating it signs everyone out and
+# invalidates outstanding password-reset links.
+BETTER_AUTH_SECRET=
+API_BASE_URL=http://localhost:3000
+ADMIN_APP_URL=http://localhost:3002
+# Comma-separated origins of the apps that may call /admin/* with credentials.
+APP_ORIGINS=http://localhost:3001
+# nachklang.art in production; passkeys are bound to this value.
+PASSKEY_RP_ID=localhost
+# On start-up, makes sure this address can get in (invite, or grant admin if the
+# user already exists). Idempotent, safe to leave set.
+ADMIN_BOOTSTRAP_EMAIL=
+
+# The header the reverse proxy puts the real client IP in, and the proxy hops to
+# trust. Get these right or better-auth cannot resolve a client IP and every
+# request shares ONE rate-limit bucket (/sign-in/* allows 3 per 10 seconds, so
+# one noisy client locks everyone out). Check with:
+#   SELECT `key` FROM rateLimit;  -- a "no-trusted-ip" row means it is happening.
+# The header the reverse proxy puts the real client IP in. Must be one the proxy
+# actually overwrites - trusting a header it does not set lets any client send its
+# own value and bypass the sign-in rate limit entirely.
+# Set to "none" to trust no header at all: every request then shares one rate-limit
+# bucket, which is the safe fallback if the check below fails. Verify after deploy
+# with: SELECT ipAddress FROM session ORDER BY createdAt DESC LIMIT 3;
+CLIENT_IP_HEADERS=x-real-ip
+TRUSTED_PROXY_IPS=
+
+# Writes invitation links to the log. That link is a live account-creation
+# credential, so this is refused outside development. Needed locally, where the
+# mail relay is off and only the token's hash is stored.
+ADMIN_LOG_INVITE_LINKS=true
+
 MEMBER_CREDENTIAL=123
 CHOIR_CREDENTIAL=123
 MANAGEMENT_CREDENTIAL=123

CLAUDE.md

@@ -10,6 +10,7 @@ npm run start    # Build and start (tsc && node ./dist/app.js)
 npm run debug    # Start with DEBUG=* environment variable
 npm run test     # Run the vitest suite once with coverage (lcov + testResults/sonar-report.xml)
 npm run test:watch  # vitest in watch mode
+npm run test:integration  # Admin-module tests against a throwaway MariaDB (needs docker or podman)
 ```
 
 Run a single test file:
@@ -19,10 +20,12 @@ npx vitest run test/some.test.ts
 
 ## Architecture
 
-Express.js REST API in TypeScript with a service-oriented layering. Domains: `Calendar` (events, users) and `Feedback` (concert feedback forms, mounted at `/feedback`, backed by its own `FEEDBACK_DB` — see `src/models/feedback/`: public submission flow, admin CRUD, reporting, and a Salesforce newsletter-sync integration).
+Express.js REST API in TypeScript with a service-oriented layering. Domains: `Calendar` (events, users), `Feedback` (concert feedback forms, mounted at `/feedback`, backed by its own `FEEDBACK_DB` — see `src/models/feedback/`: public submission flow, admin CRUD, reporting, and a Salesforce newsletter-sync integration), `Tickets` (mounted at `/tickets`), and `Admin` (identity and permissions, mounted at `/admin`, backed by `ADMIN_DB` — see below).
+
+`src/app.factory.ts` builds the Express app; `app.ts` only starts it. The split exists so the integration tests drive the real wiring.
 
 **Request path:**
-1. `app.ts` mounts `Calendar.router.ts` at `/calendar`
+1. `src/app.factory.ts` mounts `Calendar.router.ts` at `/calendar`
 2. `Calendar.router.ts` delegates to `events.router.ts` and `users.router.ts`
 3. Routers call services; services call the MariaDB pool in `Calendar.db.ts`
 
@@ -35,7 +38,43 @@ Express.js REST API in TypeScript with a service-oriented layering. Domains: `Ca
 | DB pool | `src/models/calendar/Calendar.db.ts` (MariaDB, pool size 5) |
 | Shared | `src/common/` (base route class, nodemailer wrapper), `src/middleware/logger.ts` (Winston) |
 
-**Auth model:** Users must have a `@nachklang.art` email. After activation they receive a session token (30-day window); the token hash + IP are stored in the DB. Credentials for non-user calendar access (`MEMBER_CREDENTIAL`, `CHOIR_CREDENTIAL`, `MANAGEMENT_CREDENTIAL`) come from `.env`.
+**Auth model:** Two of them, on purpose.
+
+*Admin module (`src/models/admin/`)* — the current one, used by feedback, tickets and the
+admin app. better-auth 1.7 on its own `nachklang_admin` database (Kysely + mysql2; every
+other domain keeps the `mariadb` driver), mounted at `/admin/auth/*` for the auth handler
+and `/admin` for the JSON routes. Sessions are httpOnly cookies scoped to
+`.nachklang.art`, so one sign-in covers every app. Accounts are **invite-only** — public
+sign-up is disabled, and `invitations.plugin.ts` is the only code that creates users.
+A permission is **(app, role)** in `user_app_permissions`, keyed on
+`(user_id, app, role)` so one user can hold several roles per app. `access` is the only role
+today and means "may use this app at all"; `APP_ROLES` in `admin.schema.ts` is the contract,
+and a role not listed there is rejected rather than written. `requireAppAccess(app)` in
+`admin.middleware.ts` is the single authenticator - it takes an optional second argument to
+narrow to one role, and queries the database on every request (no cookie cache) so disabling
+a user takes effect at once. Two things to know before touching this: any count of admins
+must count **distinct users**, not permission rows, or a single admin with two roles reads as
+two and the last-admin guard stops guarding; and both write endpoints accept
+`{permissions: [{app, role}]}` as well as the older `{apps: ['tickets']}`, which means the
+same at the `access` role. `ADMIN_BOOTSTRAP_EMAIL`
+makes sure someone can always get in on a fresh database.
+
+*Legacy calendar* — unchanged: users need a `@nachklang.art` email, and after activation
+get a session token (30-day window, hash + IP stored in the DB), passed as query
+parameters. Migration is planned but not started: `docs/calendar-auth-migration.md`.
+Credentials for non-user calendar access (`MEMBER_CREDENTIAL`, `CHOIR_CREDENTIAL`,
+`MANAGEMENT_CREDENTIAL`) come from `.env`.
+
+**Admin database driver:** the admin pool is the **callback-style** `mysql2`, never
+`mysql2/promise`. Kysely's `MysqlDialect` calls `pool.getConnection((err, conn) => ...)`;
+the promise wrapper ignores that callback, so every Kysely query hangs forever with no
+error. Only the integration tests catch this.
+
+**Admin schema changes:** `sql/admin/NNN_*.sql`, hand-maintained and mirrored in
+`docker/init/`. The better-auth tables must match what the configured version derives from
+`admin.auth.ts` — on every better-auth upgrade, re-derive them (`getAuthTables` from
+`better-auth/db`, called with `auth.options`), diff, and add a numbered migration. Do not
+use the published `@better-auth/cli`; it lags the library.
 
 **Event versioning:** Events have a companion `event_versions` table. `events.service.ts` manages writes to both.
 
@@ -52,13 +91,31 @@ backslash escapes inside double quotes are expanded. Wrap any value containing `
 surrounding spaces in single quotes (`DB_PASSWORD='abc#def'`), which are taken literally.
 A truncated password shows up as MariaDB "Access denied ... (using password: YES)".
 
+**`NODE_ENV` is load-bearing for the admin module.** Only the explicit values
+`development` and `test` relax anything; everything else, *including unset*, is treated as
+production (strict secrets, cross-subdomain cookies, no localhost CORS). That direction is
+deliberate: a Plesk vhost does not set `NODE_ENV`, and the inverse arrangement would
+silently degrade the signing key, the cookie domain and the CORS list at once. Local work
+needs `NODE_ENV=development`.
+
 Copy `.env.example` (or create `.env`) with:
 ```
+NODE_ENV=
 PORT=
 DB_HOST=
 DB_USER=
 DB_PASSWORD=
 CALENDAR_DB=
+ADMIN_DB=
+BETTER_AUTH_SECRET=
+API_BASE_URL=
+ADMIN_APP_URL=
+APP_ORIGINS=
+PASSKEY_RP_ID=
+ADMIN_BOOTSTRAP_EMAIL=
+CLIENT_IP_HEADERS=
+TRUSTED_PROXY_IPS=
+ADMIN_LOG_INVITE_LINKS=
 FEEDBACK_DB=
 FEEDBACK_IP_SALT=
 FEEDBACK_RATE_LIMIT_MAX=

DEFERRED_SECURITY.md

@@ -5,15 +5,28 @@ These items were identified during a security review on 2026-05-02 and conscious
 
 ---
 
-## 1. Session credentials in URL query parameters (logged-in users)
+## 1. Session credentials in URL query parameters (logged-in users) — CLOSED 2026-09-06
 
 **Files:** `src/models/calendar/events/events.router.ts` — all GET/PUT/DELETE handlers
 
-`sessionId` and `sessionKey` are currently read from query parameters, which means they appear in server access logs, browser history, proxy logs, and `Referer` headers.
+`sessionId` and `sessionKey` were read from query parameters, which meant they appeared in
+server access logs, browser history, proxy logs, and `Referer` headers.
 
-**Fix:** Move to request headers (`X-Session-Id` / `X-Session-Key`) or the request body. Requires a corresponding frontend update.
+**Fixed** by step 4 of `docs/calendar-auth-migration.md`: the calendar's write routes now sit
+behind `requireAppAccess('calendar')` against the better-auth session cookie, and the read
+routes resolve the same cookie optionally. No route reads `sessionId`/`sessionKey` any more,
+and the Angular frontend sends `withCredentials` instead of appending them to every URL. That
+closed the item outright rather than moving the credential somewhere safer.
 
-> Note: the shared calendar `password` parameter in query params is intentional (iCal clients don't support headers) and is acceptable for the current setup.
+Two things this did *not* change, both deliberate:
+
+- The shared calendar `password` parameter stays. An iCal client cannot send a cookie, so
+  this is the one caller that genuinely needs a credential in the URL. It grants read access
+  to one calendar and nothing else - `test/calendar/events.router.test.ts` pins that it can
+  never be used to write.
+- The legacy `/calendar/users/*` routes still exist. Nothing calls them any more, and a
+  legacy session they mint no longer opens anything, but they are still live
+  password-accepting endpoints. Step 5 removes them.
 
 ---
 
@@ -24,14 +37,21 @@ These items were identified during a security review on 2026-05-02 and conscious
 - `PUT /move/:eventId` (move)
 - `DELETE /:eventId` (delete)
 
-Currently any active user can edit, move, or delete any event regardless of who created it. This is acceptable while all users are trusted admins.
+Currently any account holding the `calendar` permission can edit, move, or delete any event regardless of who created it. This is acceptable while everyone holding it is a trusted admin.
 
-**Fix:** When non-admin users are introduced, fetch the event first and verify `event.createdById === user.userId` before allowing the mutation. Add an `isAdmin` flag to the user model to let admins bypass the check.
+**Fix (updated 2026-09-06):** fetch the event first and verify `event.createdByUserId === res.locals.admin.id` before allowing the mutation — `createdById`, the legacy INT, is no longer written and is gone at step 5. Rather than an `isAdmin` flag, the bypass belongs in the permission model that already exists: `requireAppAccess('calendar', 'manage')` alongside the current `access` role, which needs a row in `APP_ROLES` on both sides and nothing else.
 
 ---
 
 ## 3. Activation token has no expiry
 
+> **Superseded for new accounts (2026-09-05).** The admin module
+> (`src/models/admin/`) replaced account creation for the feedback, tickets and admin
+> apps: accounts now come from `invitations`, whose tokens expire after 7 days and are
+> stored only as a SHA-256 hash. The item below still stands for the legacy calendar
+> `users` table, which the admin module deliberately left alone - see
+> `docs/calendar-auth-migration.md`.
+
 **File:** `src/models/calendar/users/users.service.ts` — `createUser` / `activateUser`
 
 The email activation link is valid indefinitely. Acceptable for a small, trusted userbase.
@@ -45,6 +65,10 @@ The email activation link is valid indefinitely. Acceptable for a small, trusted
 
 ## 4. Password reset token has no expiry
 
+> **Superseded for new accounts (2026-09-05).** Password resets for admin-module accounts
+> go through better-auth, whose reset tokens expire after one hour. As with item 3, the
+> text below still applies to the legacy calendar `users` table.
+
 **File:** `src/models/calendar/users/users.service.ts` — `initiatePasswordReset` / `finalizePasswordReset`
 
 The reset token stored in `pw_reset_token_hash` never expires. Acceptable for a small, trusted userbase.

app.ts

@@ -1,16 +1,8 @@
-import express from 'express';
 import * as http from 'http';
 import * as dotenv from 'dotenv';
-import swaggerUi from 'swagger-ui-express';
-import swaggerJSDoc from 'swagger-jsdoc';
-import cors from 'cors';
 import logger from './src/middleware/logger.js';
-
-// Router imports
-import {calendarRouter} from './src/models/calendar/Calendar.router.js';
-import {feedbackRouter} from './src/models/feedback/Feedback.router.js';
-import {ticketsRouter} from './src/models/tickets/Tickets.router.js';
-
+import {createApp} from './src/app.factory.js';
+import {bootstrapAdmin} from './src/models/admin/admin.bootstrap.js';
 
 dotenv.config();
 
@@ -21,97 +13,11 @@ if (!process.env.PORT) {
 
 const port: number = parseInt(process.env.PORT, 10);
 
-const app: express.Application = express();
+const app = createApp();
 const server: http.Server = http.createServer(app);
 
-// Behind Plesk's nginx, req.ip is the proxy unless we trust the forwarded header.
-// Verify the resolved client IP is correct in staging before relying on it
-// (used by the feedback rate limiter).
-app.set('trust proxy', 1);
-
-// here we are adding middleware to parse all incoming requests as JSON
-app.use(express.json());
-
-// Configure CORS
-let allowedHosts = [
-	'https://www.nachklang.art',
-	'https://calendar.nachklang.art',
-	'https://feedback.nachklang.art',
-	'https://tickets.nachklang.art'
-];
-const isDev = process.env.NODE_ENV !== 'production';
-const localhostRegex = /^http:\/\/localhost:\d+$/;
-// Matches http://<private-LAN-IPv4>:<port> - needed so the feedback form can
-// be reached from a real phone over WiFi during dev (the phone's Origin is
-// the dev machine's LAN IP, never "localhost"). Dev-only, same as above.
-const lanIpRegex = /^http:\/\/(192\.168\.\d{1,3}\.\d{1,3}|10\.\d{1,3}\.\d{1,3}\.\d{1,3}|172\.(1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3}):\d+$/;
-app.use(cors({
-	allowedHeaders: ['Content-Type', 'X-Session-Id', 'X-Session-Key'],
-	origin: function (origin: any, callback: any) {
-		// Allow requests with no origin
-		if (!origin) return callback(null, true);
-
-		// Any localhost port, or a private-LAN IP, is fine outside production -
-		// dev servers pick whatever port is free (Next.js falls back from 3000
-		// if it's taken), and real-device testing hits the dev machine by IP.
-		if (isDev && (localhostRegex.test(origin) || lanIpRegex.test(origin))) {
-			return callback(null, true);
-		}
-
-		// Block requests with wrong origin
-		if (allowedHosts.indexOf(origin) === -1) {
-			return callback(new Error('The CORS policy doesn\'t allow access for your origin.'), false);
-		}
-
-		// Allow all other requests
-		return callback(null, true);
-	}
-}));
-
-// Swagger documentation
-const swaggerDefinition = {
-	openapi: '3.0.0',
-	info: {
-		title: 'Nachklang e.V. REST API',
-		version: '0.1.0',
-		license: {
-			name: 'Licensed Under MIT',
-			url: 'https://spdx.org/licenses/MIT.html'
-		},
-		contact: {
-			name: 'Nachklang e.V.',
-			url: 'https://www.nachklang.art'
-		}
-	}
-};
-
-const options = {
-	swaggerDefinition,
-	// Paths to files containing OpenAPI definitions
-	apis: [
-		'./src/models/**/*.interface.ts',
-		'./src/models/**/*.router.ts'
-	]
-};
-
-const swaggerSpec = swaggerJSDoc(options);
-
-app.use(
-	'/docs',
-	swaggerUi.serve,
-	swaggerUi.setup(swaggerSpec)
-);
-
-// Add routers
-app.use('/calendar', calendarRouter);
-app.use('/feedback', feedbackRouter);
-app.use('/tickets', ticketsRouter);
-
-// this is a simple route to make sure everything is working properly
-app.get('/', (req: express.Request, res: express.Response) => {
-	res.status(200).send('Welcome to the Nachklang e.V. REST API!');
-});
-
 server.listen(port, () => {
 	logger.info('Server listening on Port ' + port);
+	// Makes sure ADMIN_BOOTSTRAP_EMAIL can always get in. Never throws.
+	void bootstrapAdmin();
 });

docker-compose.test.yml

@@ -0,0 +1,31 @@
+# Manual alternative for bringing up the admin tests' database by hand.
+#
+# `npm run test:integration` does NOT use this file: test/integration/setup.ts
+# starts the container directly, because `podman compose` needs a separate
+# compose provider that neither podman nor docker ships, and one container needs
+# no orchestration. Keep the two in step, or delete this file if nobody uses it.
+#
+# Port 3307 and a throwaway data directory on purpose: it must never collide
+# with, or outlive, the dev database from docker-compose.dev.yml.
+services:
+  mariadb-test:
+    image: mariadb:11
+    environment:
+      MARIADB_ROOT_PASSWORD: roottestpassword
+      MARIADB_DATABASE: nachklang_admin
+      MARIADB_USER: nachklang
+      MARIADB_PASSWORD: testpassword
+    ports:
+      - "3307:3306"
+    tmpfs:
+      - /var/lib/mysql
+    volumes:
+      # Applied by the entrypoint on first boot, against MARIADB_DATABASE.
+      # This is the very migration production runs, so a mistake in it fails
+      # the test run rather than the deploy.
+      - ./sql/admin/001_init.sql:/docker-entrypoint-initdb.d/001_init.sql:ro
+    healthcheck:
+      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
+      interval: 2s
+      timeout: 5s
+      retries: 30

docker/init/00-databases.sql

@@ -1,10 +1,12 @@
--- Local dev only. Creates the three databases + a dev user with full access.
+-- Local dev only. Creates the four databases + a dev user with full access.
 CREATE DATABASE IF NOT EXISTS nachklang_calendar CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
 CREATE DATABASE IF NOT EXISTS nachklang_feedback CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
 CREATE DATABASE IF NOT EXISTS nachklang_tickets CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+CREATE DATABASE IF NOT EXISTS nachklang_admin CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
 
 CREATE USER IF NOT EXISTS 'nachklang'@'%' IDENTIFIED BY 'devpassword';
 GRANT ALL PRIVILEGES ON nachklang_calendar.* TO 'nachklang'@'%';
 GRANT ALL PRIVILEGES ON nachklang_feedback.* TO 'nachklang'@'%';
 GRANT ALL PRIVILEGES ON nachklang_tickets.* TO 'nachklang'@'%';
+GRANT ALL PRIVILEGES ON nachklang_admin.* TO 'nachklang'@'%';
 FLUSH PRIVILEGES;

docker/init/01-calendar-schema-dev.sql

@@ -1,5 +1,8 @@
 -- Local dev only. Real schema, provided directly by the repo owner
 -- (calendars, events, event_versions, sessions, users) - not a guess.
+-- Columns added by this repo's own migrations under sql/calendar/ are folded
+-- in here rather than appended, so a fresh dev container matches production
+-- after every migration has been applied. Keep the two in step.
 USE nachklang_calendar;
 
 CREATE TABLE `calendars` (
@@ -38,10 +41,16 @@ CREATE TABLE `events` (
   `calendar_id` int(11) NOT NULL,
   `uuid` text NOT NULL,
   `created_date` datetime DEFAULT current_timestamp(),
-  `created_by_id` int(11) NOT NULL,
+  -- Nullable since the cutover; see sql/calendar/003_allow_null_legacy_creator.sql.
+  `created_by_id` int(11) DEFAULT NULL,
+  -- Bridge to the admin module's user ids; see sql/calendar/001_add_admin_user_bridge.sql.
+  `created_by_user_id` varchar(36) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL,
+  -- Archived creator name; see sql/calendar/002_snapshot_legacy_creator_names.sql.
+  `created_by_name` varchar(255) DEFAULT NULL,
   PRIMARY KEY (`event_id`),
   KEY `events_calendars_calendar_id_fk` (`calendar_id`),
   KEY `events_users_user_id_fk` (`created_by_id`),
+  KEY `events_created_by_user_idx` (`created_by_user_id`),
   CONSTRAINT `events_calendars_calendar_id_fk` FOREIGN KEY (`calendar_id`) REFERENCES `calendars` (`calendar_id`),
   CONSTRAINT `events_users_user_id_fk` FOREIGN KEY (`created_by_id`) REFERENCES `users` (`user_id`)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
@@ -58,11 +67,16 @@ CREATE TABLE `event_versions` (
   `location` text DEFAULT NULL,
   `url` text DEFAULT NULL,
   `version_created_by_id` int(11) DEFAULT NULL,
+  -- Bridge to the admin module's user ids; see sql/calendar/001_add_admin_user_bridge.sql.
+  `version_created_by_user_id` varchar(36) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL,
+  -- Archived editor name; see sql/calendar/002_snapshot_legacy_creator_names.sql.
+  `version_created_by_name` varchar(255) DEFAULT NULL,
   `status` text DEFAULT NULL,
   `version_created_at` datetime DEFAULT current_timestamp(),
   PRIMARY KEY (`event_version_id`),
   KEY `event_versions_events_event_id_fk` (`event_id`),
   KEY `event_versions_users_user_id_fk` (`version_created_by_id`),
+  KEY `event_versions_created_by_user_idx` (`version_created_by_user_id`),
   CONSTRAINT `event_versions_events_event_id_fk` FOREIGN KEY (`event_id`) REFERENCES `events` (`event_id`) ON DELETE CASCADE ON UPDATE CASCADE,
   CONSTRAINT `event_versions_users_user_id_fk` FOREIGN KEY (`version_created_by_id`) REFERENCES `users` (`user_id`)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
@@ -78,12 +92,16 @@ INSERT INTO calendars (calendar_id, name, includes_calendars) VALUES
 INSERT INTO users (email, password_hash, full_name, is_active) VALUES
     ('dev@nachklang.art', '$2b$10$vmj7POS/68SGE.eI7pGjMegrw0vNNZ2HVSUTra5NRsl8iOLwiMgZK', 'Dev Admin', 1);
 
-INSERT INTO events (calendar_id, uuid, created_by_id) VALUES
-    (1, UUID(), 1),
-    (1, UUID(), 1),
-    (1, UUID(), 1);
+-- Two rows are left on the legacy path and one carries an admin user id, so
+-- dev exercises both branches of the step 3 dual-read rather than only the
+-- happy one. It is deliberately a PUBLIC event, so the anonymous listing the
+-- website uses covers both. The id is the dev admin from 04-admin-schema.sql.
+INSERT INTO events (calendar_id, uuid, created_by_id, created_by_user_id, created_by_name) VALUES
+    (1, UUID(), 1, NULL, 'Dev Admin'),
+    (1, UUID(), 1, 'dev-user-0000-0000-0000-000000000001', NULL),
+    (1, UUID(), 1, NULL, 'Dev Admin');
 
-INSERT INTO event_versions (event_id, name, description, start_datetime, end_datetime, whole_day, location, url, status, version_created_by_id) VALUES
-    (1, 'Frühlingskonzert 2026', 'Erstes Konzert der Reihe', '2026-04-18 19:00:00', '2026-04-18 21:00:00', 0, 'Musikhochschule, Karlsruhe', 'https://www.nachklang.art/events/fruehlingskonzert-2026', 'PUBLIC', 1),
-    (2, 'Sommerkonzert 2026', 'Zweites Konzert der Reihe', '2026-07-11 19:00:00', '2026-07-11 21:00:00', 0, 'Christuskirche, Karlsruhe', 'https://www.nachklang.art/events/sommerkonzert-2026', 'PUBLIC', 1),
-    (3, 'Adventskonzert 2026', 'Drittes Konzert der Reihe', '2026-12-05 19:00:00', '2026-12-05 21:00:00', 0, 'Stadtkirche, Karlsruhe', 'https://www.nachklang.art/events/adventskonzert-2026', 'DRAFT', 1);
+INSERT INTO event_versions (event_id, name, description, start_datetime, end_datetime, whole_day, location, url, status, version_created_by_id, version_created_by_user_id, version_created_by_name) VALUES
+    (1, 'Frühlingskonzert 2026', 'Erstes Konzert der Reihe', '2026-04-18 19:00:00', '2026-04-18 21:00:00', 0, 'Musikhochschule, Karlsruhe', 'https://www.nachklang.art/events/fruehlingskonzert-2026', 'PUBLIC', 1, NULL, 'Dev Admin'),
+    (2, 'Sommerkonzert 2026', 'Zweites Konzert der Reihe', '2026-07-11 19:00:00', '2026-07-11 21:00:00', 0, 'Christuskirche, Karlsruhe', 'https://www.nachklang.art/events/sommerkonzert-2026', 'PUBLIC', 1, 'dev-user-0000-0000-0000-000000000001', NULL),
+    (3, 'Adventskonzert 2026', 'Drittes Konzert der Reihe', '2026-12-05 19:00:00', '2026-12-05 21:00:00', 0, 'Stadtkirche, Karlsruhe', 'https://www.nachklang.art/events/adventskonzert-2026', 'DRAFT', 1, NULL, 'Dev Admin');

docker/init/04-admin-schema.sql

@@ -0,0 +1,170 @@
+-- Local dev only. Mirrors the table definitions in sql/admin/001_init.sql -
+-- keep the two in step - and seeds a ready-to-use dev account on top.
+USE nachklang_admin;
+
+CREATE TABLE IF NOT EXISTS `user` (
+	`id`            VARCHAR(36)  NOT NULL,
+	`name`          VARCHAR(255) NOT NULL,
+	`email`         VARCHAR(255) NOT NULL,
+	`emailVerified` TINYINT(1)   NOT NULL DEFAULT 0,
+	`image`         TEXT         DEFAULT NULL,
+	`createdAt`     DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
+	`updatedAt`     DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
+	-- Nachklang addition, declared through better-auth's additionalFields so
+	-- the adapter knows about it. Disabling also revokes the user's sessions.
+	`disabled`      TINYINT(1)   NOT NULL DEFAULT 0,
+	PRIMARY KEY (`id`),
+	UNIQUE KEY `user_email` (`email`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+CREATE TABLE IF NOT EXISTS `session` (
+	`id`        VARCHAR(36)  NOT NULL,
+	`expiresAt` DATETIME     NOT NULL,
+	`token`     VARCHAR(255) NOT NULL,
+	`createdAt` DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
+	`updatedAt` DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
+	`ipAddress` VARCHAR(255) DEFAULT NULL,
+	`userAgent` TEXT         DEFAULT NULL,
+	`userId`    VARCHAR(36)  NOT NULL,
+	PRIMARY KEY (`id`),
+	UNIQUE KEY `session_token` (`token`),
+	KEY `session_user` (`userId`),
+	CONSTRAINT `session_user_fk` FOREIGN KEY (`userId`) REFERENCES `user` (`id`) ON DELETE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+CREATE TABLE IF NOT EXISTS `account` (
+	`id`                    VARCHAR(36)  NOT NULL,
+	-- 1.7 addition: distinguishes a local credential account
+	-- ("local:credential") from an OAuth issuer. Written by better-auth.
+	`issuer`                VARCHAR(255) NOT NULL,
+	`accountId`             VARCHAR(255) NOT NULL,
+	`providerId`            VARCHAR(255) NOT NULL,
+	`userId`                VARCHAR(36)  NOT NULL,
+	`accessToken`           TEXT         DEFAULT NULL,
+	`refreshToken`          TEXT         DEFAULT NULL,
+	`idToken`               TEXT         DEFAULT NULL,
+	`accessTokenExpiresAt`  DATETIME     DEFAULT NULL,
+	`refreshTokenExpiresAt` DATETIME     DEFAULT NULL,
+	`scope`                 TEXT         DEFAULT NULL,
+	`password`              TEXT         DEFAULT NULL,
+	`createdAt`             DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
+	`updatedAt`             DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
+	PRIMARY KEY (`id`),
+	KEY `account_user` (`userId`),
+	KEY `account_provider` (`providerId`, `accountId`),
+	CONSTRAINT `account_user_fk` FOREIGN KEY (`userId`) REFERENCES `user` (`id`) ON DELETE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- Password-reset and e-mail-verification tokens.
+CREATE TABLE IF NOT EXISTS `verification` (
+	`id`         VARCHAR(36)  NOT NULL,
+	`identifier` VARCHAR(255) NOT NULL,
+	`value`      TEXT         NOT NULL,
+	`expiresAt`  DATETIME     NOT NULL,
+	`createdAt`  DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
+	`updatedAt`  DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
+	PRIMARY KEY (`id`),
+	KEY `verification_identifier` (`identifier`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+CREATE TABLE IF NOT EXISTS `passkey` (
+	`id`           VARCHAR(36)  NOT NULL,
+	`name`         VARCHAR(255) DEFAULT NULL,
+	`publicKey`    TEXT         NOT NULL,
+	`userId`       VARCHAR(36)  NOT NULL,
+	`credentialID` VARCHAR(255) NOT NULL,
+	`counter`      INT          NOT NULL DEFAULT 0,
+	`deviceType`   VARCHAR(255) NOT NULL,
+	`backedUp`     TINYINT(1)   NOT NULL DEFAULT 0,
+	`transports`   VARCHAR(255) DEFAULT NULL,
+	`createdAt`    DATETIME     DEFAULT CURRENT_TIMESTAMP,
+	`aaguid`       VARCHAR(255) DEFAULT NULL,
+	PRIMARY KEY (`id`),
+	KEY `passkey_user` (`userId`),
+	KEY `passkey_credential` (`credentialID`),
+	CONSTRAINT `passkey_user_fk` FOREIGN KEY (`userId`) REFERENCES `user` (`id`) ON DELETE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- Required by rateLimit.storage = 'database' in admin.auth.ts. Passenger may
+-- run several API instances, and an in-memory limiter would give each of them
+-- its own budget.
+CREATE TABLE IF NOT EXISTS `rateLimit` (
+	`id`          VARCHAR(36)  NOT NULL,
+	`key`         VARCHAR(255) NOT NULL,
+	`count`       INT          NOT NULL DEFAULT 0,
+	-- Epoch milliseconds, not a DATETIME: better-auth stores a number here.
+	`lastRequest` BIGINT       NOT NULL DEFAULT 0,
+	PRIMARY KEY (`id`),
+	UNIQUE KEY `rate_limit_key` (`key`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- ---------------------------------------------------------------------------
+-- Nachklang-owned tables
+-- ---------------------------------------------------------------------------
+
+-- Which apps a user may administer. `admin` is just another app: holding it is
+-- what lets someone manage users and invitations. A permission is (app, role);
+-- `access` is the only role today, and the key admits several per app so finer
+-- ones can be added by inserting rows rather than by migrating this table.
+CREATE TABLE IF NOT EXISTS `user_app_permissions` (
+	`user_id`    VARCHAR(36) NOT NULL,
+	`app`        ENUM('calendar','feedback','tickets','admin') NOT NULL,
+	-- One row per (user, app, role). `access` means "may use this app at all"
+	-- and is the only role today; the key allows several per app so a finer
+	-- permission can be added later by inserting rows, not by migrating.
+	`role`       VARCHAR(32) NOT NULL DEFAULT 'access',
+	`granted_by` VARCHAR(36) DEFAULT NULL,
+	`granted_at` DATETIME    NOT NULL DEFAULT CURRENT_TIMESTAMP,
+	-- (user_id, app) is the leftmost prefix of this key, so the per-request
+	-- permission lookup needs no separate index.
+	PRIMARY KEY (`user_id`, `app`, `role`),
+	CONSTRAINT `uap_user_fk` FOREIGN KEY (`user_id`) REFERENCES `user` (`id`) ON DELETE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- The only route to a new account: there is no public sign-up. Only the
+-- SHA-256 of the token is stored, so a dump of this table hands out no access.
+CREATE TABLE IF NOT EXISTS `invitations` (
+	`id`          INT AUTO_INCREMENT PRIMARY KEY,
+	`email`       VARCHAR(255) NOT NULL,
+	`name`        VARCHAR(255) NOT NULL,
+	`token_hash`  CHAR(64)     NOT NULL,
+	`permissions` JSON         NOT NULL,
+	`invited_by`  VARCHAR(36)  DEFAULT NULL,
+	`created_at`  DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
+	`expires_at`  DATETIME     NOT NULL,
+	`accepted_at` DATETIME     DEFAULT NULL,
+	`revoked_at`  DATETIME     DEFAULT NULL,
+	UNIQUE KEY `inv_token_hash` (`token_hash`),
+	KEY `inv_email` (`email`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- ---------------------------------------------------------------------------
+-- Dev seed: dev@nachklang.art / devpassword, with every app permission.
+-- Local only - this account exists nowhere but in this container.
+--
+-- The password hash is better-auth's own scrypt format (salt:hash), produced
+-- with better-auth 1.7.2's hashPassword(). Regenerate it if better-auth ever
+-- changes that format; a hash it cannot parse shows up as "invalid password"
+-- on an otherwise correct sign-in.
+--
+-- `issuer` must be exactly 'local:credential' - it is how better-auth 1.7
+-- recognises a local password account when signing in.
+-- ---------------------------------------------------------------------------
+INSERT INTO `user` (`id`, `name`, `email`, `emailVerified`, `disabled`)
+VALUES ('dev-user-0000-0000-0000-000000000001', 'Dev Admin', 'dev@nachklang.art', 1, 0);
+
+INSERT INTO `account` (`id`, `issuer`, `accountId`, `providerId`, `userId`, `password`)
+VALUES (
+	'dev-acct-0000-0000-0000-000000000001',
+	'local:credential',
+	'dev-user-0000-0000-0000-000000000001',
+	'credential',
+	'dev-user-0000-0000-0000-000000000001',
+	'e6a0485feb04b8fa64453db87badd8e1:85aaffd845e1e44fabc5be97d684c0f533845ed11088bd3f4d533ef277ead71da8372b5c6a72c7eae2d48e3270c50e2d13cffa4fcfb0b5cec456100b8f007ed2'
+);
+
+INSERT INTO `user_app_permissions` (`user_id`, `app`, `role`) VALUES
+	('dev-user-0000-0000-0000-000000000001', 'calendar', 'access'),
+	('dev-user-0000-0000-0000-000000000001', 'feedback', 'access'),
+	('dev-user-0000-0000-0000-000000000001', 'tickets',  'access'),
+	('dev-user-0000-0000-0000-000000000001', 'admin',    'access');

docs/calendar-auth-migration.md

@@ -0,0 +1,265 @@
+# Migrating the Calendar domain onto the admin identity module
+
+Status: **steps 1-4 implemented 2026-09-06, not yet merged or deployed.** Step 2 dropped by
+decision, part of step 5 brought forward. Only step 5, the removal of the legacy path, is
+left to write.
+
+> Read the deploy checklist under step 4 before applying anything. "Done" below means the
+> code exists on a branch, **not** that production has it - and in particular production has
+> none of the three migrations. Step 5 is scoped but deliberately unstarted: it must not be
+> built on top of a step 4 that has not been deployed and watched.
+
+Written 2026-09-05 alongside the admin module (step 2 of `docs/plan-admin-auth.md` in the
+nachklang-admin repo), which deliberately left the calendar alone. Steps 1-4 of that plan
+are now live, so the calendar is the last module still on the legacy query-parameter
+sessions.
+
+## Why the calendar was left out
+
+The admin module replaced authentication for feedback and tickets by swapping one
+middleware. The calendar cannot be done that way, because its user identity is woven into
+its data:
+
+- `users`/`sessions` live in the **calendar** database and are the same tables the
+  feedback and tickets admin areas used to authenticate against.
+- `events.created_by_id` is an **INT** foreign key into `users.user_id`. The admin module's
+  user ids are **VARCHAR(36)** strings. Migrating identity means migrating that column and
+  every query that joins it.
+- The Angular frontend passes `sessionId`/`sessionKey` as **query parameters**
+  (`DEFERRED_SECURITY.md` item 1). Cookie sessions remove the parameters entirely, so
+  every calendar route signature and the frontend's HTTP layer change together.
+- `credentials.service.ts` implements a second, parallel authorisation model: the
+  `MEMBER_CREDENTIAL` / `CHOIR_CREDENTIAL` / `MANAGEMENT_CREDENTIAL` shared secrets that
+  let non-users read specific calendars. That has no equivalent in the admin module and is
+  not a per-user permission at all.
+
+What already exists today: `calendar` is a value in the `user_app_permissions.app` enum, so
+permissions can be granted before anything else moves.
+
+## What is in place to build on
+
+- Cookie sessions across `*.nachklang.art`, and `requireAppAccess('calendar')` in
+  `src/models/admin/admin.middleware.ts` - usable the moment a calendar route wants it.
+- `res.locals.admin` is `{id, email, displayName, apps}`; `id` is the string user id.
+- Invitations, disable/enable and session revocation already cover calendar users, because
+  they are properties of the account rather than of an app.
+
+## Suggested sequence
+
+Each step is meant to leave production working on its own.
+
+1. **Add a bridging column.** ~~`ALTER TABLE events ADD COLUMN created_by_user_id
+   VARCHAR(36) NULL`, indexed. Nothing reads it yet.~~ **Done 2026-09-06**, as
+   `sql/calendar/001_add_admin_user_bridge.sql` - the first migration this repo owns for the
+   calendar schema, mirrored into `docker/init/01-calendar-schema-dev.sql`. It covers both
+   `events.created_by_user_id` and `event_versions.version_created_by_user_id`, and carries
+   no foreign key (see "What the code actually looks like" below). The dev seed leaves two
+   events on the legacy path and gives one an admin id, so step 3's dual-read has both cases
+   to exercise. Verified by applying the pre-migration schema and then the migration to a
+   throwaway MariaDB 11 container, and diffing `SHOW CREATE TABLE` against a fresh dev
+   schema: identical. Applied to the running dev database on the same day; a dev container
+   created before then needs it applied, or recreating.
+2. ~~**Map the accounts.**~~ **Dropped 2026-09-06.** There is no backfill: since the
+   creator is only ever a display name (see below), old events keep resolving through the
+   legacy join until step 5 and then simply lose the name. Re-inviting the people who
+   actually still need calendar access remains an operational task, but it is no longer a
+   migration step and nothing is blocked on it.
+3. **Dual-read.** ~~Change `events.service.ts` to prefer `created_by_user_id` and fall back
+   to `created_by_id`. Writes fill both.~~ **Done 2026-09-06.** `events.service.ts` now reads
+   both columns and prefers the admin one, resolving the name through a single
+   `findDisplayNames` lookup against the admin database per result set (added to
+   `users.admin.service.ts` for this). Four copies of the same SELECT and four copies of the
+   row mapper were collapsed into one of each first - the dual read would otherwise have had
+   to be written four times.
+
+   A name now has three possible sources, tried weakest first: the legacy join, then the
+   `created_by_name` snapshot from migration 002, then the live admin lookup - which wins
+   because it is the only one that follows an account being renamed. An admin id that no
+   longer resolves falls back rather than blanking, and a failure to reach the admin database
+   is caught and logged rather than propagated, so an anonymous read of the public calendar
+   never depends on the admin database being up. Covered by
+   `test/calendar/events.service.test.ts`.
+
+   **Writes are not dual-written**, contrary to the original plan: before the cutover the
+   request only ever carries a legacy session, so there is no admin id available to write.
+   Writes start filling `created_by_user_id` (and stop filling `created_by_id`) in step 4.
+4. **Switch the routes.** ~~Replace the query-parameter session checks in `events.router.ts`
+   and `users.router.ts` with `requireAppAccess('calendar')`, and change the Angular frontend
+   to `withCredentials: true`.~~ **Done 2026-09-06.** `DEFERRED_SECURITY.md` item 1 is closed:
+   no route reads `sessionId`/`sessionKey` any more.
+
+   How it came out, route by route:
+
+   - The four write routes sit behind `requireAppAccess('calendar')` as middleware. They
+     answer 401 when signed out and 403 without the permission, where they used to answer 403
+     for both.
+   - The three read routes cannot use middleware - the same URL serves an anonymous visitor,
+     an iCal subscription holding a shared password, and a signed-in editor who should see
+     drafts. They call `resolveAccess` optionally instead (`signedInEditor` in the router),
+     and a signed-in user *without* the calendar permission is treated as anonymous rather
+     than refused, so they keep their access to the public calendar.
+   - `credentials.service.ts` lost its session half entirely and is now just the password
+     table. `hasAccess(calendar, password)`.
+   - `/calendar/users/*` was left alone. Nothing calls it and a session it mints opens
+     nothing, but they are live password-accepting endpoints - step 5 removes them.
+
+   Also: `calendar.nachklang.art` joined `DEFAULT_APP_ORIGINS` (better-auth `trustedOrigins`,
+   without which sign-out from the calendar fails while everything else works), and
+   `localhost:4200` joined the dev origins for the same reason.
+
+   Two things this step had to carry that the original sequence put in step 5:
+
+   - **`sql/calendar/003_allow_null_legacy_creator.sql` makes `events.created_by_id` nullable**
+     (`MODIFY created_by_id INT NULL`). It is `NOT NULL` today, so the first event created after the
+     cutover would otherwise fail to insert - there is no legacy int id to write any more.
+     `event_versions.version_created_by_id` is already nullable. The foreign key can stay
+     until step 5; it permits NULL. It also re-runs 002's idempotent name backfill, to catch
+     anything created between the two migrations. Applying it early is safe - widening a
+     column to accept NULL cannot break the running pre-cutover build.
+   - **The public calendar stays anonymous.** `hasAccess('public')` returns true before any
+     credential check, and nachklang.art reads `/calendar/events/public/json` and
+     `/public/json/next` with no session at all. Pinned at both levels - the password table in
+     `test/calendar/credentials.service.test.ts`, the routes themselves in
+     `test/calendar/events.router.test.ts` - so this cannot regress quietly.
+
+   ### Deploy checklist
+
+   Production has **none** of the three migrations: 001 and 002 were only ever applied to the
+   dev database. The API build below selects `created_by_user_id` and `created_by_name` on
+   every read, so deploying it against a database missing them fails every calendar request
+   including the anonymous public feed the website uses. In order:
+
+   1. **Apply `sql/calendar/001`, `002`, `003`, in that order**, against `CALENDAR_DB`. All
+      three are re-runnable, so applying one that is already applied is a no-op. Verify
+      before continuing:
+      `SHOW COLUMNS FROM events LIKE '%by_user%'; SHOW COLUMNS FROM events LIKE '%by_name%';`
+      - four rows across the two tables, and `created_by_id` nullable.
+   2. **Check `APP_ORIGINS` on the API vhost.** `calendar.nachklang.art` is in the code's
+      default list, but the environment variable *replaces* that list rather than adding to
+      it - so if it is set at all (the tickets/feedback cutover may have set it), append
+      `https://calendar.nachklang.art` or the calendar's sign-out will 403 while everything
+      else works. That is the failure mode the comment in `admin.config.ts` warns about.
+   3. **Deploy the API.**
+   4. **Deploy the calendar frontend immediately after.** Do not leave a gap - see below.
+   5. **Re-run 002's two `UPDATE` statements.** Between step 1 and step 3 the old API was
+      still writing `created_by_id` with no snapshot; those few rows would otherwise lose
+      their author at step 5.
+   6. **Rebuild the admin app** if `NEXT_PUBLIC_ALLOWED_REDIRECT_ORIGINS` does not already
+      contain `https://calendar.nachklang.art`. It is a **build-time** value, so a restart
+      does nothing.
+
+   **The window between steps 3 and 4 does not look broken, which is the danger.** The old
+   Angular bundle starts by calling `POST /calendar/users/checkSessionValid`, and those
+   legacy routes are untouched - so it still succeeds and the page renders as signed in. What
+   the user then sees is an empty event table and saves that silently do nothing. It looks
+   like the calendar lost its data, not like a deploy in progress. Keep the gap to minutes,
+   or take the frontend offline for it.
+
+   **One-way door:** any iCal subscription whose URL carries `?sessionId=&sessionKey=` rather
+   than `?password=` stops working permanently. The shared-password URLs are unaffected.
+5. **Drop the legacy path.** Not started - and deliberately not started until step 4 has been
+   deployed and watched, because it removes the fallback step 4 still leans on. Scoped and
+   decided 2026-09-06; what follows is the agreed shape, not a suggestion.
+
+   **Prerequisite: step 4 live in production and behaving.** Until then the legacy join is
+   what renders the author of every pre-cutover event, and the legacy routes are what an old
+   cached bundle talks to. Doing this first turns a recoverable deploy into an unrecoverable
+   one.
+
+   Code, in one branch:
+
+   - **Delete `src/models/calendar/users/` entirely** - `users.router.ts`, `users.service.ts`,
+     `session.interface.ts`, `user.interface.ts` - and the `calendarRouter.use('/users', ...)`
+     line in `Calendar.router.ts`. *(Decided: delete outright rather than unmount.)* This
+     removes the last unauthenticated account-creation and mail-sending endpoint in the API.
+     A survey on 2026-09-06 confirmed nothing outside that directory imports it, and nothing
+     outside it touches the `users`/`sessions` tables except the two joins below.
+   - **Drop the legacy half of the read** in `events.service.ts`: the two
+     `LEFT OUTER JOIN users` clauses, the `legacy_*` aliases, and `created_by_id` /
+     `version_created_by_id` from the SELECT and the row mapper. The snapshot fallback stays -
+     it is what makes this safe. Remove `createdById` / `lastModifiedById` from
+     `event.interface.ts` and their (already deprecated) swagger properties.
+   - **Remove `X-Session-Id` / `X-Session-Key`** from the CORS `allowedHeaders` in
+     `src/app.factory.ts`. Nothing has sent them since the tickets and feedback frontends were
+     redeployed.
+   - **Drop the obsolete test mocks**: `test/feedback/feedback.auth.test.ts`,
+     `test/tickets/tickets.auth.test.ts` and `test/admin/auth-binding.ts` each mock
+     `calendar/users/users.service.js` and assert `checkSession` is never called. That
+     tripwire is meaningless once the module does not exist; remove the mock and the
+     assertion, keep the rest.
+
+   Database, as `sql/calendar/004_*.sql`:
+
+   - Drop the foreign keys `events_users_user_id_fk` and `event_versions_users_user_id_fk`,
+     then the `created_by_id` and `version_created_by_id` columns.
+   - **`RENAME TABLE users TO users_legacy_archive`**, same for `sessions`. *(Decided: rename
+     rather than drop.)* The reasoning: the display names are already snapshotted so nothing
+     visible depends on these rows, but they still hold the old e-mail addresses and password
+     hashes, and a rename makes the tables unreachable without destroying anything. Dropping
+     them later is one statement, at a moment when nobody is mid-deploy.
+   - Mirror all of it in `docker/init/01-calendar-schema-dev.sql` (the archive tables need no
+     mirror - a fresh dev database has nothing to archive).
+
+   Documentation: `DEFERRED_SECURITY.md` items **3** (activation token has no expiry) and
+   **4** (password reset token has no expiry) close outright - both describe code that ceases
+   to exist. Item 2 (no event ownership check) stays open.
+
+   Two consequences to accept explicitly rather than discover:
+
+   - Any activation or password-reset e-mail already sent points at
+     `api.nachklang.art/calendar/users/activate` and becomes a 404. Those links were only ever
+     valid for legacy accounts, which no longer open anything.
+   - `Event.createdById` disappears from the API response. The Angular frontend never read it
+     (its `Event` model has only `createdBy`, the name), so this is not a breaking change for
+     the only known consumer - but it is a wire-format removal, so check anything else that
+     reads `/calendar/events/*/json` first.
+
+## What the code actually looks like (surveyed 2026-09-06)
+
+Four things found while doing step 1 that change how the later steps should be built:
+
+- **`created_by_id` is display-only.** Nothing authorises on it. `events.router.ts` gates
+  PUT, POST, DELETE and `/move` on `user?.isActive` alone - there is no "only the creator may
+  edit" rule anywhere - and the column is read back solely to render `created_by_name` and
+  `last_modified_by_name`. That de-risks steps 2, 3 and 5 considerably: an event whose
+  creator never gets re-invited loses a name in the UI, it does not become uneditable or
+  invisible. It also means the step 2 backfill is best-effort, not a precondition.
+- **The two schemas are separate databases.** `nachklang_calendar` and `nachklang_admin`
+  have their own connection pools (`Calendar.db.ts` vs the admin module's Kysely instance).
+  So the bridging columns get no foreign key, and - the part the original sequence missed -
+  **the `LEFT OUTER JOIN users` that produces the creator's name cannot simply be repointed**.
+  It would have to become a cross-schema join, which hardcodes the admin database name into
+  calendar SQL and ties the two schemas together exactly as an FK would. Recommendation for
+  step 3: drop the join for the new path and resolve names in the service layer instead -
+  collect the distinct ids from the result set and do one lookup against the admin users
+  service. One extra query per listing, no coupling, and it keeps working if the admin
+  database ever moves.
+- **`events.created_by_id` is `NOT NULL`.** Step 5 cannot simply stop writing it; that step
+  has to drop the column (and its FK to `users`) in the same migration that stops the writes,
+  or make it nullable first.
+- **Every calendar read already hits the session table.** `/:calendar/json` calls
+  `UserService.checkSession` before falling back to `credentials.service.ts`, so the shared
+  credentials are the *fallback*, not the primary path. Step 4 replaces the first half of
+  that with `requireAppAccess('calendar')` and has to decide what happens to the second half
+  - which is the first open question below.
+
+## Open questions to settle before starting
+
+**Settled 2026-09-06:**
+
+- **The shared calendar credentials keep working, but only for iCal.** The web app goes
+  cookie-only at step 4; `MEMBER_CREDENTIAL` and friends survive on
+  `GET /calendar/events/{calendar}/ical`, which is the one case where the client genuinely
+  cannot send a cookie. Everything else in `credentials.service.ts` goes with step 5.
+  `public` stays anonymous everywhere - see the note under step 4.
+- **The iCal export keeps its own scheme.** Same reasoning; it is the reason the shared
+  credentials survive at all rather than an exception to their removal.
+- **No account backfill.** See step 2 above.
+- **Pre-cutover authorship is archived, not discarded.** `events.created_by_name` and
+  `event_versions.version_created_by_name`, backfilled once by migration 002 and never
+  written again. This was originally listed as a step 5 question; it was brought forward so
+  the data is safe well before the table that holds it is dropped.
+
+**Nothing is open.** The last one - ~~`event_versions.version_created_by_id`~~, the same INT
+reference on the version rows - was handled in passing: step 1 gave it a sibling bridging
+column, step 2 a sibling snapshot, and step 3 reads it exactly like `events`.

package.json

@@ -12,25 +12,32 @@
 		"build": "tsc",
 		"debug": "export DEBUG=* && npm run start",
 		"test": "vitest run --coverage",
-		"test:watch": "vitest"
+		"test:watch": "vitest",
+		"test:integration": "vitest run --config vitest.integration.config.ts"
 	},
 	"keywords": [],
 	"author": "",
 	"license": "ISC",
 	"dependencies": {
+		"@better-auth/core": "^1.7.2",
+		"@better-auth/passkey": "^1.7.2",
 		"app-root-path": "^3.0.0",
 		"axios": "^1.20.0",
 		"bcrypt": "^5.0.1",
+		"better-auth": "^1.7.2",
 		"cors": "^2.8.5",
 		"debug": "^4.3.1",
 		"dotenv": "^16.6.1",
 		"express": "^4.18.2",
 		"guid-typescript": "^1.0.9",
+		"kysely": "^0.29.5",
 		"mariadb": "^3.0.2",
+		"mysql2": "^3.24.3",
 		"random-words": "^1.1.1",
 		"swagger-jsdoc": "^6.1.0",
 		"swagger-ui-express": "^4.3.0",
-		"winston": "^3.3.3"
+		"winston": "^3.3.3",
+		"zod": "^4.5.4"
 	},
 	"devDependencies": {
 		"@types/app-root-path": "^1.2.4",
@@ -40,14 +47,21 @@
 		"@types/express": "^4.17.15",
 		"@types/node": "^26.4.1",
 		"@types/random-words": "^1.1.2",
+		"@types/supertest": "^7.2.1",
 		"@types/swagger-jsdoc": "^6.0.1",
 		"@types/swagger-ui-express": "^4.1.3",
 		"@types/winston": "^2.4.4",
 		"@vitest/coverage-v8": "^5.0.0",
 		"is-number": "^7.0.0",
 		"source-map-support": "^0.5.19",
+		"supertest": "^7.2.2",
 		"typescript": "^5.9.3",
 		"vitest": "^5.0.0",
 		"vitest-sonar-reporter": "^3.0.0"
+	},
+	"overrides": {
+		"better-auth": {
+			"vitest": "$vitest"
+		}
 	}
 }

sql/admin/001_init.sql

@@ -0,0 +1,150 @@
+-- nachklang_admin: identity, sessions and per-app permissions for every
+-- *.nachklang.art app.
+--
+-- The better-auth tables below (user, session, account, verification, passkey,
+-- rateLimit) mirror what better-auth 1.7.2 derives from the configuration in
+-- src/models/admin/admin.auth.ts, including the `disabled` additionalField on
+-- `user` and the `rateLimit` table that rateLimit.storage='database' requires.
+-- On every better-auth upgrade: re-derive the table list, diff it against this
+-- file, and add a numbered migration - never edit this one in place.
+--
+-- Table and column names are better-auth's own ("camel" casing, so `rateLimit`
+-- and `userId`). MariaDB on Linux compares table names case-sensitively, so the
+-- casing here is load-bearing. The two Nachklang-owned tables at the bottom use
+-- the snake_case convention of the rest of this repo's SQL.
+
+CREATE TABLE IF NOT EXISTS `user` (
+	`id`            VARCHAR(36)  NOT NULL,
+	`name`          VARCHAR(255) NOT NULL,
+	`email`         VARCHAR(255) NOT NULL,
+	`emailVerified` TINYINT(1)   NOT NULL DEFAULT 0,
+	`image`         TEXT         DEFAULT NULL,
+	`createdAt`     DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
+	`updatedAt`     DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
+	-- Nachklang addition, declared through better-auth's additionalFields so
+	-- the adapter knows about it. Disabling also revokes the user's sessions.
+	`disabled`      TINYINT(1)   NOT NULL DEFAULT 0,
+	PRIMARY KEY (`id`),
+	UNIQUE KEY `user_email` (`email`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+CREATE TABLE IF NOT EXISTS `session` (
+	`id`        VARCHAR(36)  NOT NULL,
+	`expiresAt` DATETIME     NOT NULL,
+	`token`     VARCHAR(255) NOT NULL,
+	`createdAt` DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
+	`updatedAt` DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
+	`ipAddress` VARCHAR(255) DEFAULT NULL,
+	`userAgent` TEXT         DEFAULT NULL,
+	`userId`    VARCHAR(36)  NOT NULL,
+	PRIMARY KEY (`id`),
+	UNIQUE KEY `session_token` (`token`),
+	KEY `session_user` (`userId`),
+	CONSTRAINT `session_user_fk` FOREIGN KEY (`userId`) REFERENCES `user` (`id`) ON DELETE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+CREATE TABLE IF NOT EXISTS `account` (
+	`id`                    VARCHAR(36)  NOT NULL,
+	-- 1.7 addition: distinguishes a local credential account
+	-- ("local:credential") from an OAuth issuer. Written by better-auth.
+	`issuer`                VARCHAR(255) NOT NULL,
+	`accountId`             VARCHAR(255) NOT NULL,
+	`providerId`            VARCHAR(255) NOT NULL,
+	`userId`                VARCHAR(36)  NOT NULL,
+	`accessToken`           TEXT         DEFAULT NULL,
+	`refreshToken`          TEXT         DEFAULT NULL,
+	`idToken`               TEXT         DEFAULT NULL,
+	`accessTokenExpiresAt`  DATETIME     DEFAULT NULL,
+	`refreshTokenExpiresAt` DATETIME     DEFAULT NULL,
+	`scope`                 TEXT         DEFAULT NULL,
+	`password`              TEXT         DEFAULT NULL,
+	`createdAt`             DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
+	`updatedAt`             DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
+	PRIMARY KEY (`id`),
+	KEY `account_user` (`userId`),
+	KEY `account_provider` (`providerId`, `accountId`),
+	CONSTRAINT `account_user_fk` FOREIGN KEY (`userId`) REFERENCES `user` (`id`) ON DELETE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- Password-reset and e-mail-verification tokens.
+CREATE TABLE IF NOT EXISTS `verification` (
+	`id`         VARCHAR(36)  NOT NULL,
+	`identifier` VARCHAR(255) NOT NULL,
+	`value`      TEXT         NOT NULL,
+	`expiresAt`  DATETIME     NOT NULL,
+	`createdAt`  DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
+	`updatedAt`  DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
+	PRIMARY KEY (`id`),
+	KEY `verification_identifier` (`identifier`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+CREATE TABLE IF NOT EXISTS `passkey` (
+	`id`           VARCHAR(36)  NOT NULL,
+	`name`         VARCHAR(255) DEFAULT NULL,
+	`publicKey`    TEXT         NOT NULL,
+	`userId`       VARCHAR(36)  NOT NULL,
+	`credentialID` VARCHAR(255) NOT NULL,
+	`counter`      INT          NOT NULL DEFAULT 0,
+	`deviceType`   VARCHAR(255) NOT NULL,
+	`backedUp`     TINYINT(1)   NOT NULL DEFAULT 0,
+	`transports`   VARCHAR(255) DEFAULT NULL,
+	`createdAt`    DATETIME     DEFAULT CURRENT_TIMESTAMP,
+	`aaguid`       VARCHAR(255) DEFAULT NULL,
+	PRIMARY KEY (`id`),
+	KEY `passkey_user` (`userId`),
+	KEY `passkey_credential` (`credentialID`),
+	CONSTRAINT `passkey_user_fk` FOREIGN KEY (`userId`) REFERENCES `user` (`id`) ON DELETE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- Required by rateLimit.storage = 'database' in admin.auth.ts. Passenger may
+-- run several API instances, and an in-memory limiter would give each of them
+-- its own budget.
+CREATE TABLE IF NOT EXISTS `rateLimit` (
+	`id`          VARCHAR(36)  NOT NULL,
+	`key`         VARCHAR(255) NOT NULL,
+	`count`       INT          NOT NULL DEFAULT 0,
+	-- Epoch milliseconds, not a DATETIME: better-auth stores a number here.
+	`lastRequest` BIGINT       NOT NULL DEFAULT 0,
+	PRIMARY KEY (`id`),
+	UNIQUE KEY `rate_limit_key` (`key`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- ---------------------------------------------------------------------------
+-- Nachklang-owned tables
+-- ---------------------------------------------------------------------------
+
+-- Which apps a user may administer. `admin` is just another app: holding it is
+-- what lets someone manage users and invitations. A permission is (app, role);
+-- `access` is the only role today, and the key admits several per app so finer
+-- ones can be added by inserting rows rather than by migrating this table.
+CREATE TABLE IF NOT EXISTS `user_app_permissions` (
+	`user_id`    VARCHAR(36) NOT NULL,
+	`app`        ENUM('calendar','feedback','tickets','admin') NOT NULL,
+	-- One row per (user, app, role). `access` means "may use this app at all"
+	-- and is the only role today; the key allows several per app so a finer
+	-- permission can be added later by inserting rows, not by migrating.
+	`role`       VARCHAR(32) NOT NULL DEFAULT 'access',
+	`granted_by` VARCHAR(36) DEFAULT NULL,
+	`granted_at` DATETIME    NOT NULL DEFAULT CURRENT_TIMESTAMP,
+	-- (user_id, app) is the leftmost prefix of this key, so the per-request
+	-- permission lookup needs no separate index.
+	PRIMARY KEY (`user_id`, `app`, `role`),
+	CONSTRAINT `uap_user_fk` FOREIGN KEY (`user_id`) REFERENCES `user` (`id`) ON DELETE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- The only route to a new account: there is no public sign-up. Only the
+-- SHA-256 of the token is stored, so a dump of this table hands out no access.
+CREATE TABLE IF NOT EXISTS `invitations` (
+	`id`          INT AUTO_INCREMENT PRIMARY KEY,
+	`email`       VARCHAR(255) NOT NULL,
+	`name`        VARCHAR(255) NOT NULL,
+	`token_hash`  CHAR(64)     NOT NULL,
+	`permissions` JSON         NOT NULL,
+	`invited_by`  VARCHAR(36)  DEFAULT NULL,
+	`created_at`  DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
+	`expires_at`  DATETIME     NOT NULL,
+	`accepted_at` DATETIME     DEFAULT NULL,
+	`revoked_at`  DATETIME     DEFAULT NULL,
+	UNIQUE KEY `inv_token_hash` (`token_hash`),
+	KEY `inv_email` (`email`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

sql/calendar/001_add_admin_user_bridge.sql

@@ -0,0 +1,38 @@
+-- Nachklang e.V. Calendar module — step 1 of docs/calendar-auth-migration.md.
+-- Adds the bridging columns that let an event record who created it as an
+-- *admin* user id (VARCHAR(36)) alongside the legacy calendar users.user_id
+-- (INT). Apply manually against the CALENDAR_DB database:
+--   mysql -h <DB_HOST> -u <DB_USER> -p <CALENDAR_DB> < 001_add_admin_user_bridge.sql
+--
+-- Numbered 001 because this is the first migration this repo owns for the
+-- calendar schema: the tables themselves predate it and were provided by the
+-- repo owner (mirrored for dev in docker/init/01-calendar-schema-dev.sql).
+--
+-- Nothing reads these columns yet — step 3 introduces the dual-read. Adding
+-- them first means the backfill in step 2 has somewhere to write, and this
+-- migration can be applied to production on its own without any code change.
+--
+-- No foreign key, on purpose. The admin `user` table lives in a *different*
+-- database (nachklang_admin) behind a different connection pool, and a
+-- cross-schema FK would tie the two schemas' lifecycles together: you could no
+-- longer dump, restore or move one without the other. The reference is
+-- enforced in application code, which is also where the legacy/new fallback
+-- lives.
+--
+-- The collation is pinned to the admin database's (utf8mb4_unicode_ci) rather
+-- than inherited from the calendar tables' utf8mb4_general_ci. These columns
+-- hold ids that only ever compare against nachklang_admin.user.id, and a
+-- mismatched collation makes any such comparison fail at runtime with
+-- "Illegal mix of collations" instead of at review time.
+
+ALTER TABLE `events`
+    ADD COLUMN IF NOT EXISTS `created_by_user_id` VARCHAR(36)
+        CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci
+        NULL DEFAULT NULL AFTER `created_by_id`,
+    ADD KEY IF NOT EXISTS `events_created_by_user_idx` (`created_by_user_id`);
+
+ALTER TABLE `event_versions`
+    ADD COLUMN IF NOT EXISTS `version_created_by_user_id` VARCHAR(36)
+        CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci
+        NULL DEFAULT NULL AFTER `version_created_by_id`,
+    ADD KEY IF NOT EXISTS `event_versions_created_by_user_idx` (`version_created_by_user_id`);

sql/calendar/002_snapshot_legacy_creator_names.sql

@@ -0,0 +1,42 @@
+-- Nachklang e.V. Calendar module — step 5 preparation, brought forward.
+-- Apply manually against the CALENDAR_DB database, after 001:
+--   mysql -h <DB_HOST> -u <DB_USER> -p <CALENDAR_DB> < 002_snapshot_legacy_creator_names.sql
+--
+-- Snapshots the creator's and last editor's *name* onto the event itself.
+--
+-- Why: the creator is only ever rendered as a name (nothing authorises on it),
+-- and today that name comes from joining the calendar's own `users` table.
+-- Step 5 drops that table, which would silently erase the authorship of every
+-- event created before the cutover. There is no account backfill to save them
+-- either - that was dropped deliberately, see docs/calendar-auth-migration.md.
+-- One text column per reference keeps the history at no ongoing cost.
+--
+-- These columns are an archive, not a source of truth. Nothing writes them
+-- after this backfill: events created from the cutover onwards carry an admin
+-- user id, whose name is resolved live so that renaming an account updates
+-- everywhere. The read path prefers the live admin name, falls back to this
+-- snapshot, and falls back again to the join until step 5 removes it.
+--
+-- The whole file is re-runnable: IF NOT EXISTS on the columns, and the backfill
+-- only touches rows with no snapshot yet. Step 4's migration re-runs the
+-- backfill, to catch anything created between this migration and the cutover.
+--
+-- No charset clause: unlike 001's id columns these hold display text that is
+-- only ever compared against other calendar data, so they inherit the tables'
+-- utf8mb4_general_ci like the columns they are copied from.
+
+ALTER TABLE `events`
+    ADD COLUMN IF NOT EXISTS `created_by_name` VARCHAR(255) NULL DEFAULT NULL AFTER `created_by_user_id`;
+
+ALTER TABLE `event_versions`
+    ADD COLUMN IF NOT EXISTS `version_created_by_name` VARCHAR(255) NULL DEFAULT NULL AFTER `version_created_by_user_id`;
+
+UPDATE `events` e
+    JOIN `users` u ON u.user_id = e.created_by_id
+    SET e.created_by_name = u.full_name
+    WHERE e.created_by_name IS NULL;
+
+UPDATE `event_versions` v
+    JOIN `users` u ON u.user_id = v.version_created_by_id
+    SET v.version_created_by_name = u.full_name
+    WHERE v.version_created_by_name IS NULL;

sql/calendar/003_allow_null_legacy_creator.sql

@@ -0,0 +1,32 @@
+-- Nachklang e.V. Calendar module — step 4 of docs/calendar-auth-migration.md,
+-- the cutover. Apply manually against the CALENDAR_DB database, after 002,
+-- and BEFORE deploying the API build that goes with it:
+--   mysql -h <DB_HOST> -u <DB_USER> -p <CALENDAR_DB> < 003_allow_null_legacy_creator.sql
+--
+-- From the cutover on, an event's creator is an admin-module user id. There is
+-- no legacy calendar user id to write any more, and `events.created_by_id` is
+-- NOT NULL - so without this the very first event created after the deploy
+-- fails to insert. `event_versions.version_created_by_id` is already nullable.
+--
+-- The foreign key to `users` is kept: it permits NULL, so it costs nothing
+-- until step 5 drops the column and the table together.
+--
+-- Applying this early is harmless. Widening a column to accept NULL cannot
+-- break the running pre-cutover build, which always supplies a value, so this
+-- can go out ahead of the deploy rather than during it.
+
+ALTER TABLE `events`
+    MODIFY COLUMN `created_by_id` INT(11) NULL DEFAULT NULL;
+
+-- Re-run of 002's backfill, to catch anything created between the two
+-- migrations while the legacy path was still writing events. Idempotent by
+-- construction: it only touches rows that have no snapshot yet.
+UPDATE `events` e
+    JOIN `users` u ON u.user_id = e.created_by_id
+    SET e.created_by_name = u.full_name
+    WHERE e.created_by_name IS NULL;
+
+UPDATE `event_versions` v
+    JOIN `users` u ON u.user_id = v.version_created_by_id
+    SET v.version_created_by_name = u.full_name
+    WHERE v.version_created_by_name IS NULL;

src/app.factory.ts

@@ -0,0 +1,172 @@
+import express from 'express';
+import * as dotenv from 'dotenv';
+import swaggerUi from 'swagger-ui-express';
+import swaggerJSDoc from 'swagger-jsdoc';
+import cors from 'cors';
+import {toNodeHandler} from 'better-auth/node';
+import logger from './middleware/logger.js';
+
+// Router imports
+import {calendarRouter} from './models/calendar/Calendar.router.js';
+import {feedbackRouter} from './models/feedback/Feedback.router.js';
+import {ticketsRouter} from './models/tickets/Tickets.router.js';
+import {adminRouter} from './models/admin/Admin.router.js';
+import {auth} from './models/admin/admin.auth.js';
+import {ADMIN_ALLOWED_ORIGINS, isProd} from './models/admin/admin.config.js';
+
+
+dotenv.config();
+
+
+/**
+ * Builds the Express app with every router and middleware in place.
+ *
+ * Separate from app.ts so the integration tests can drive the *real* wiring
+ * with supertest instead of a hand-rolled copy of it. The order below is not
+ * cosmetic - CORS has to precede the better-auth handler so preflights get
+ * their headers, and the better-auth handler has to precede express.json()
+ * because it reads the raw body stream itself.
+ */
+export const createApp = (): express.Application => {
+	const app: express.Application = express();
+
+	// Behind Plesk's nginx, req.ip is the proxy unless we trust the forwarded header.
+	// Verify the resolved client IP is correct in staging before relying on it
+	// (used by the feedback rate limiter).
+	app.set('trust proxy', 1);
+
+	// Configure CORS. This has to run before the better-auth handler below, so
+	// that preflights for /admin/auth/* get their headers, which is why it now
+	// sits above express.json() instead of after it.
+	let allowedHosts = [
+		'https://www.nachklang.art',
+		'https://calendar.nachklang.art',
+		'https://feedback.nachklang.art',
+		'https://tickets.nachklang.art',
+		'https://admin.nachklang.art',
+		// The admin app's origin comes from ADMIN_APP_URL, so a rename or a
+		// staging host does not need a code change here.
+		...ADMIN_ALLOWED_ORIGINS
+	];
+	// `isProd` from admin.config, NOT `NODE_ENV !== 'production'`. The two are not
+	// the same when NODE_ENV is unset, which is exactly what a fresh Plesk vhost
+	// gives you: the old test called that "dev" and opened the loopback and
+	// private-LAN exceptions below. With `credentials: true` on this CORS config
+	// and a session cookie scoped to .nachklang.art, that let any page served
+	// from localhost read a signed-in admin's data cross-origin. admin.config
+	// treats anything but an explicit 'development'/'test' as production, so an
+	// unset value now fails closed.
+	const isDev = !isProd;
+	const localhostRegex = /^http:\/\/localhost:\d+$/;
+	// Matches http://<private-LAN-IPv4>:<port> - needed so the feedback form can
+	// be reached from a real phone over WiFi during dev (the phone's Origin is
+	// the dev machine's LAN IP, never "localhost"). Dev-only, same as above.
+	const lanIpRegex = /^http:\/\/(192\.168\.\d{1,3}\.\d{1,3}|10\.\d{1,3}\.\d{1,3}\.\d{1,3}|172\.(1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3}):\d+$/;
+	app.use(cors({
+		// X-Session-* are no longer read by anything on this side, and no longer
+		// sent by anything either: the tickets and feedback cutover took the last
+		// two readers off them, and the calendar cutover removed the last legacy
+		// credential path in the API (its session used to travel in query
+		// parameters - DEFERRED_SECURITY.md item 1, now closed). They stay allowed
+		// only so a browser still running a pre-cutover tickets or feedback bundle
+		// gets a clean 401 rather than a CORS preflight failure. Drop them once
+		// those have aged out - see docs/calendar-auth-migration.md step 5.
+		allowedHeaders: ['Content-Type', 'X-Session-Id', 'X-Session-Key'],
+		// The admin session lives in a cookie, so browsers must be allowed to send
+		// it cross-origin - this is what makes credentials: 'include' work.
+		credentials: true,
+		origin: function (origin: any, callback: any) {
+			// Allow requests with no origin
+			if (!origin) return callback(null, true);
+
+			// Any localhost port, or a private-LAN IP, is fine outside production -
+			// dev servers pick whatever port is free (Next.js falls back from 3000
+			// if it's taken), and real-device testing hits the dev machine by IP.
+			if (isDev && (localhostRegex.test(origin) || lanIpRegex.test(origin))) {
+				return callback(null, true);
+			}
+
+			// Block requests with wrong origin
+			if (allowedHosts.indexOf(origin) === -1) {
+				return callback(new Error('The CORS policy doesn\'t allow access for your origin.'), false);
+			}
+
+			// Allow all other requests
+			return callback(null, true);
+		}
+	}));
+
+	// better-auth's own handler, mounted before express.json(): it reads the raw
+	// request body stream itself and a parsed body would leave it hanging.
+	//
+	// Wrapped, because Express 4 does not await an async handler: a rejected
+	// promise escapes as an unhandled rejection instead of becoming a response.
+	// Nearly every better-auth route touches the admin database, so a database
+	// blip would leave the request hanging with no answer at all while the
+	// process logged an uncaughtException - observed by pointing ADMIN_DB at a
+	// database the user cannot open. Answer 503 instead: the caller learns, and
+	// the other domains keep serving.
+	const authHandler = toNodeHandler(auth);
+	app.all('/admin/auth/*', (req, res) => {
+		Promise.resolve(authHandler(req, res)).catch((e: any) => {
+			logger.error('Admin auth handler failed', {path: req.path, detail: e?.message});
+			if (!res.headersSent) {
+				res.status(503).send({
+					status: 'SERVICE_UNAVAILABLE',
+					message: 'Die Anmeldung ist derzeit nicht verfügbar. Bitte versuche es später erneut.'
+				});
+			}
+		});
+	});
+
+	// here we are adding middleware to parse all incoming requests as JSON
+	app.use(express.json());
+
+	// Swagger documentation
+	const swaggerDefinition = {
+		openapi: '3.0.0',
+		info: {
+			title: 'Nachklang e.V. REST API',
+			version: '1.0.0',
+			license: {
+				name: 'Licensed Under MIT',
+				url: 'https://spdx.org/licenses/MIT.html'
+			},
+			contact: {
+				name: 'Nachklang e.V.',
+				url: 'https://www.nachklang.art'
+			}
+		}
+	};
+
+	const options = {
+		swaggerDefinition,
+		// Paths to files containing OpenAPI definitions
+		apis: [
+			'./src/models/**/*.interface.ts',
+			'./src/models/**/*.router.ts'
+		]
+	};
+
+	const swaggerSpec = swaggerJSDoc(options);
+
+	app.use(
+		'/docs',
+		swaggerUi.serve,
+		swaggerUi.setup(swaggerSpec)
+	);
+
+	// Add routers
+	app.use('/calendar', calendarRouter);
+	app.use('/feedback', feedbackRouter);
+	app.use('/tickets', ticketsRouter);
+	// JSON routes only; the auth handler above is mounted separately.
+	app.use('/admin', adminRouter);
+
+	// this is a simple route to make sure everything is working properly
+	app.get('/', (req: express.Request, res: express.Response) => {
+		res.status(200).send('Welcome to the Nachklang e.V. REST API!');
+	});
+
+	return app;
+};

src/models/admin/Admin.db.ts

@@ -0,0 +1,55 @@
+import * as dotenv from 'dotenv';
+import mysql from 'mysql2';
+import {Kysely, MysqlDialect} from 'kysely';
+import {AdminDatabase} from './admin.schema.js';
+import logger from '../../middleware/logger.js';
+
+dotenv.config();
+
+/**
+ * The admin module is the one place in this API that does not use the
+ * `mariadb` driver: better-auth talks to the database through Kysely, whose
+ * MySQL dialect expects a mysql2 pool. The other domains keep their own
+ * `mariadb` pools (see Feedback.db.ts) - this is an addition, not a migration.
+ *
+ * The pool is the callback-style `mysql2` one, NOT `mysql2/promise`: Kysely's
+ * MysqlDialect calls `pool.getConnection((err, conn) => ...)`. The promise
+ * wrapper ignores that callback and returns a Promise instead, so every query
+ * through Kysely would hang forever with no error - which is exactly what it
+ * did until the integration tests caught it.
+ *
+ * timezone 'Z' matters: better-auth computes session and token expiry in UTC.
+ * Without it mysql2 would write and read those DATETIMEs in the process's local
+ * zone, so sessions would expire an hour early or late depending on DST.
+ */
+
+export namespace NachklangAdminDB {
+	export const pool = mysql.createPool({
+		host: process.env.DB_HOST,
+		user: process.env.DB_USER,
+		password: process.env.DB_PASSWORD,
+		database: process.env.ADMIN_DB,
+		// The other modules' pools default to 3306. This one is configurable so
+		// the integration tests can point at a throwaway container on another
+		// port without touching a developer's real .env.
+		port: parseInt(process.env.DB_PORT || '3306', 10),
+		connectionLimit: 5,
+		timezone: 'Z'
+	});
+
+	// mysql2 emits connection trouble as an event on the pool, not only as a
+	// rejected query. Without a listener Node turns that into an
+	// uncaughtException, so a database restart would take the whole API - and
+	// with it the calendar, feedback and tickets domains - down with it.
+	// Individual queries still reject, and their callers still answer 500.
+	pool.on('error', (err: unknown) => {
+		logger.error('Admin database pool error', {detail: (err as any)?.message});
+	});
+
+	// Handed to better-auth as `database: {dialect, type: 'mysql'}`.
+	export const dialect = new MysqlDialect({pool});
+
+	// Used by this module's own services for the two custom tables and for
+	// permission lookups that join better-auth's `user`.
+	export const db = new Kysely<AdminDatabase>({dialect});
+}

src/models/admin/Admin.router.ts

@@ -0,0 +1,48 @@
+import express, {Request, Response} from 'express';
+import {requireAppAccess, requireSignedIn} from './admin.middleware.js';
+import {usersAdminRouter} from './users/users.admin.router.js';
+import {invitationsRouter} from './invitations/invitations.router.js';
+
+/**
+ * The admin module's JSON routes. Deliberately *not* the better-auth handler:
+ * that one is mounted separately in app.ts, ahead of express.json(), because it
+ * needs the raw request body stream.
+ *
+ * Mounted at /admin, so the tree is:
+ *   /admin/me            any signed-in account
+ *   /admin/users/*       admin permission
+ *   /admin/invitations/* admin permission
+ */
+export const adminRouter = express.Router();
+
+/**
+ * @swagger
+ * /admin/me:
+ *      get:
+ *          summary: The current user's identity and app permissions
+ *          description: Used by every frontend to decide what to show. The API remains the real gate.
+ *          tags: [admin]
+ *          responses:
+ *              200:
+ *                  description: Success
+ *              401:
+ *                  description: Not signed in
+ *              403:
+ *                  description: Account disabled
+ */
+adminRouter.get('/me', requireSignedIn, (req: Request, res: Response) => {
+	res.status(200).send({
+		id: res.locals.admin.id,
+		email: res.locals.admin.email,
+		fullName: res.locals.admin.displayName,
+		// `permissions` is the full (app, role) truth; `apps` is the distinct
+		// apps within it. Both are sent because the three frontends only ever ask
+		// "may I show this app?", and keeping `apps` means a finer permission can
+		// land here without a coordinated deploy of all of them.
+		permissions: res.locals.admin.permissions,
+		apps: res.locals.admin.apps
+	});
+});
+
+adminRouter.use('/users', requireAppAccess('admin'), usersAdminRouter);
+adminRouter.use('/invitations', requireAppAccess('admin'), invitationsRouter);

src/models/admin/admin.auth.ts

@@ -0,0 +1,166 @@
+import {betterAuth} from 'better-auth';
+import {APIError} from 'better-auth/api';
+import {passkey, getAuthenticatorName} from '@better-auth/passkey';
+import {NachklangAdminDB} from './Admin.db.js';
+import {invitationsPlugin} from './invitations/invitations.plugin.js';
+import {sendPasswordResetMail} from './admin.mail.js';
+import * as UsersService from './users/users.admin.service.js';
+import logger from '../../middleware/logger.js';
+import {
+	ADMIN_ALLOWED_ORIGINS,
+	API_BASE_URL,
+	BETTER_AUTH_SECRET,
+	CLIENT_IP_HEADERS,
+	PASSKEY_RP_ID,
+	TRUSTED_PROXY_IPS,
+	isProd
+} from './admin.config.js';
+
+/**
+ * The single better-auth instance for all *.nachklang.art apps. Mounted in
+ * app.ts at /admin/auth/* with better-auth's own node handler, ahead of
+ * express.json() (it needs the raw body stream).
+ *
+ * The session cookie is what every app trusts. Everything else in this module -
+ * permissions, invitations, the admin UI - hangs off it.
+ */
+
+const DAY = 60 * 60 * 24;
+
+// Dev runs the apps on plain localhost ports; cookies ignore the port, so
+// single-sign-on across them works without fake subdomains or mkcert.
+const localhostOrigins = [
+	'http://localhost:3000',
+	'http://localhost:3001',
+	'http://localhost:3002',
+	'http://localhost:3003',
+	// The Angular calendar frontend; `ng serve` defaults to 4200. Missing from
+	// this list, sign-out from the calendar answers 403 in dev only, which is a
+	// confusing thing to debug against a production config that is fine.
+	'http://localhost:4200'
+];
+
+const trustedOrigins = isProd
+	? ADMIN_ALLOWED_ORIGINS
+	: Array.from(new Set([...ADMIN_ALLOWED_ORIGINS, ...localhostOrigins]));
+
+export const auth = betterAuth({
+	appName: 'Nachklang',
+	database: {
+		dialect: NachklangAdminDB.dialect,
+		type: 'mysql'
+	},
+	basePath: '/admin/auth',
+	// Mandatory once crossSubDomainCookies is on: better-auth derives the
+	// cookie domain and its own absolute URLs from this.
+	baseURL: API_BASE_URL,
+	secret: BETTER_AUTH_SECRET,
+	trustedOrigins,
+
+	emailAndPassword: {
+		enabled: true,
+		// There is no public sign-up: accounts exist only through an
+		// invitation (see invitations.plugin.ts). This also makes
+		// auth.api.signUpEmail throw, which is intended.
+		disableSignUp: true,
+		sendResetPassword: async ({user, url}) => {
+			await sendPasswordResetMail(user.email, user.name, url);
+		}
+	},
+
+	user: {
+		additionalFields: {
+			// Not `returned`, and not settable through the API: disabling is an
+			// admin action on /admin/users/:id/disable, never something a
+			// session owner can flip on themselves.
+			disabled: {
+				type: 'boolean',
+				defaultValue: false,
+				input: false,
+				returned: false
+			}
+		}
+	},
+
+	session: {
+		expiresIn: 30 * DAY,
+		updateAge: DAY
+		// Deliberately no cookieCache: requireAppAccess hits the database on
+		// every request anyway, and a cached session would keep a disabled
+		// user or a revoked session alive for the cache's lifetime.
+	},
+
+	advanced: {
+		// Fixes the cookie name across releases so the frontends' middleware can
+		// check for it: "nachklang.session_token", or
+		// "__Secure-nachklang.session_token" over https.
+		cookiePrefix: 'nachklang',
+		crossSubDomainCookies: isProd
+			? {enabled: true, domain: '.nachklang.art'}
+			: {enabled: false},
+		ipAddress: {
+			// better-auth reads the request itself and does not know about
+			// Express's `trust proxy`, so both the header and the trusted hops
+			// have to be named here. Getting this wrong does not fail loudly -
+			// it collapses every client into one rate-limit bucket. See the
+			// commentary on CLIENT_IP_HEADERS in admin.config.ts.
+			ipAddressHeaders: CLIENT_IP_HEADERS,
+			...(TRUSTED_PROXY_IPS.length > 0 ? {trustedProxies: TRUSTED_PROXY_IPS} : {})
+		}
+	},
+
+	rateLimit: {
+		enabled: true,
+		// Passenger may run more than one instance; an in-memory limiter would
+		// then give each of them its own budget.
+		storage: 'database'
+	},
+
+	plugins: [
+		passkey({
+			rpID: PASSKEY_RP_ID,
+			rpName: 'Nachklang',
+			origin: ADMIN_ALLOWED_ORIGINS,
+
+			registration: {
+				// Without this, every passkey is stored with name = NULL and the
+				// account page can only label them all "Passkey" - useless at the
+				// one moment that list matters, when someone has to remove the
+				// passkey on the device they just lost.
+				//
+				// The AAGUID identifies the authenticator *model* (not a device
+				// and not a person), and better-auth ships the lookup table, so
+				// this yields "1Password", "iCloud Keychain", "Windows Hello".
+				// It only fills a blank: a name the client sent always wins, and
+				// an unknown AAGUID leaves the column NULL as before.
+				afterVerification: async ({verification}) => {
+					const name = getAuthenticatorName(verification.registrationInfo?.aaguid);
+					return name ? {name} : undefined;
+				}
+			}
+		}),
+		invitationsPlugin()
+	],
+
+	databaseHooks: {
+		session: {
+			create: {
+				before: async session => {
+					const access = await UsersService.loadAccess(session.userId);
+					if (access?.disabled) {
+						logger.warn('Admin: sign-in attempt by a disabled account', {userId: session.userId});
+						// Throwing rather than returning false: `false` aborts
+						// the session write silently and the caller sees a
+						// confusing success-shaped response with no cookie.
+						throw new APIError('FORBIDDEN', {
+							code: 'ACCOUNT_DISABLED',
+							message: 'Dieses Konto ist deaktiviert.'
+						});
+					}
+				}
+			}
+		}
+	}
+});
+
+export type AdminAuth = typeof auth;

src/models/admin/admin.bootstrap.ts

@@ -0,0 +1,68 @@
+import * as UsersService from './users/users.admin.service.js';
+import * as InvitationsService from './invitations/invitations.service.js';
+import {sendInvitationMail} from './admin.mail.js';
+import {ACCESS_ROLE} from './admin.schema.js';
+import {ADMIN_APP_URL, ADMIN_BOOTSTRAP_EMAIL, LOG_INVITE_LINKS} from './admin.config.js';
+import logger from '../../middleware/logger.js';
+
+/**
+ * Solves the empty-database problem: with invite-only accounts and no public
+ * sign-up, a fresh nachklang_admin has nobody who can invite anybody. Rather
+ * than a CLI script somebody has to remember to run against production, the API
+ * makes sure on every start that ADMIN_BOOTSTRAP_EMAIL can get in.
+ *
+ * Idempotent by design - it is safe on every restart:
+ *   - an active admin already exists  -> do nothing
+ *   - the address exists as a user    -> grant it `admin`
+ *   - an open invitation exists       -> do nothing (do not re-mail on restart)
+ *   - otherwise                       -> invite, and mail the link
+ *
+ * Never throws: a database blip at boot must not stop the API from serving the
+ * calendar, feedback and tickets domains.
+ */
+export const bootstrapAdmin = async (): Promise<void> => {
+	try {
+		if (!ADMIN_BOOTSTRAP_EMAIL) {
+			return;
+		}
+
+		const email = ADMIN_BOOTSTRAP_EMAIL.trim().toLowerCase();
+
+		if ((await UsersService.countActiveAdmins()) > 0) {
+			return;
+		}
+
+		const existing = await UsersService.findUserByEmail(email);
+		if (existing) {
+			await UsersService.grantPermission(existing.id, 'admin', null);
+			logger.info('Admin bootstrap: granted the admin permission to the existing bootstrap user', {email});
+			return;
+		}
+
+		// An expired invitation is not "open", so the next restart re-issues
+		// one - which is the recovery path if the first mail never arrived.
+		if (await InvitationsService.hasOpenInvitationFor(email)) {
+			logger.info('Admin bootstrap: an open invitation already exists', {email});
+			return;
+		}
+
+		const invitation = await InvitationsService.createInvitation(
+			email,
+			'Nachklang Admin',
+			[{app: 'admin', role: ACCESS_ROLE}],
+			null
+		);
+
+		const mailed = await sendInvitationMail(email, 'Nachklang Admin', invitation.token, invitation.expiresAt);
+		logger.info('Admin bootstrap: invitation created', {email, mailed});
+
+		// With the mail relay off, the logged link is how a local setup gets its
+		// first admin. Explicit opt-in (see LOG_INVITE_LINKS): the link is a
+		// live credential, so this must never depend on NODE_ENV alone.
+		if (LOG_INVITE_LINKS) {
+			logger.info(`Admin bootstrap: ${ADMIN_APP_URL}/accept-invite?token=${invitation.token}`);
+		}
+	} catch (e: any) {
+		logger.error('Admin bootstrap failed', {detail: e?.message});
+	}
+};

src/models/admin/admin.config.ts

@@ -0,0 +1,191 @@
+import * as crypto from 'crypto';
+import * as dotenv from 'dotenv';
+import logger from '../../middleware/logger.js';
+
+dotenv.config();
+
+/**
+ * One place that reads the admin module's environment. Both admin.auth.ts
+ * (better-auth trustedOrigins, passkey origins) and app.ts (CORS) need the
+ * same origin list, and a second parser would drift from this one.
+ *
+ * Read this before changing the environment handling below: several security
+ * properties depend on it, and they are deliberately arranged to fail *safe*.
+ *
+ * `NODE_ENV` is opt-in to relaxed behaviour, not opt-in to strict behaviour.
+ * Only the explicit values 'development' and 'test' relax anything; anything
+ * else - including NODE_ENV being unset, which is exactly what a fresh Plesk
+ * vhost gives you - is treated as production. The inverse arrangement is a
+ * trap: it degrades the cookie domain, the CORS origin list and the signing
+ * key all at once, and every one of those failures is silent.
+ *
+ * The signing key is never allowed to be a known constant. In dev, an unset
+ * BETTER_AUTH_SECRET becomes a random per-process value: sessions do not
+ * survive a restart, which is mildly annoying and much better than a default
+ * secret that can be copied out of this file and used against production.
+ */
+
+const nodeEnv = process.env.NODE_ENV;
+
+// Explicitly relaxed environments. Everything else, unset included, is strict.
+const isRelaxedEnv = nodeEnv === 'development' || nodeEnv === 'test';
+
+export const isProd = !isRelaxedEnv;
+
+const required = (name: string, devDefault: string): string => {
+	const value = process.env[name];
+	if (value) {
+		return value;
+	}
+	if (isProd) {
+		logger.error(
+			`Admin module: ${name} is not set (NODE_ENV=${nodeEnv ?? 'unset'}, so strict mode applies; ` +
+			'set NODE_ENV=development for local work)'
+		);
+		throw new Error(`${name} must be set unless NODE_ENV is development or test`);
+	}
+	return devDefault;
+};
+
+export const API_BASE_URL = required('API_BASE_URL', 'http://localhost:3000');
+export const ADMIN_APP_URL = required('ADMIN_APP_URL', 'http://localhost:3002');
+
+// 32+ random bytes; better-auth signs cookies and reset tokens with it.
+// Rotating it invalidates every session, which is why it is not derived.
+// There is no hardcoded fallback on purpose: a constant committed here would
+// be a published signing key the moment someone deploys without setting it.
+export const BETTER_AUTH_SECRET = required(
+	'BETTER_AUTH_SECRET',
+	crypto.randomBytes(48).toString('base64')
+);
+
+// Passkeys are bound to this: a credential registered for "nachklang.art"
+// works on every *.nachklang.art host, one registered for "localhost" only
+// works in dev. Changing it invalidates every registered passkey.
+export const PASSKEY_RP_ID = process.env.PASSKEY_RP_ID || (isProd ? 'nachklang.art' : 'localhost');
+
+const parseList = (value: string | undefined, fallback: string[]): string[] => {
+	const parsed = (value || '')
+		.split(',')
+		.map(entry => entry.trim())
+		.filter(entry => entry.length > 0);
+
+	return parsed.length > 0 ? parsed : fallback;
+};
+
+/**
+ * The apps whose frontends may talk to /admin/* with credentials.
+ *
+ * They feed better-auth's `trustedOrigins`, which is what lets the tickets and
+ * feedback admin areas call /admin/auth/sign-out from their own origin. That
+ * became load-bearing with the step 4 cutover: before it, the only browser
+ * origin that ever reached /admin/auth was the admin app itself. The calendar
+ * joined them with its own cutover (docs/calendar-auth-migration.md step 4).
+ *
+ * Hence the production default rather than an empty list. An origin missing
+ * here fails in a way that is easy to misread - sign-in works, the app works,
+ * and only sign-out returns an origin error - so the two frontends we know
+ * about are named here and APP_ORIGINS overrides them for a staging host.
+ * Dev adds the localhost ports separately (see admin.auth.ts).
+ */
+const DEFAULT_APP_ORIGINS = [
+	'https://tickets.nachklang.art',
+	'https://feedback.nachklang.art',
+	'https://calendar.nachklang.art'
+];
+
+export const APP_ORIGINS = parseList(process.env.APP_ORIGINS, DEFAULT_APP_ORIGINS)
+	.map(origin => origin.replace(/\/$/, ''));
+
+// Kept in sync by construction rather than by three separate lists: the admin
+// app itself always counts, and dev adds the local ports.
+export const ADMIN_ALLOWED_ORIGINS = Array.from(new Set([
+	ADMIN_APP_URL.replace(/\/$/, ''),
+	...APP_ORIGINS
+]));
+
+/**
+ * The header the reverse proxy puts the real client IP in, and the proxy hops
+ * to trust when reading it.
+ *
+ * This matters more than it looks. better-auth does not know about Express's
+ * `trust proxy`; it reads the request itself. If it cannot resolve a client IP
+ * it falls back to a single shared bucket ("no-trusted-ip") for the whole
+ * process - and /sign-in/* carries a default of 3 requests per 10 seconds, so
+ * one noisy client would lock every user out of every app.
+ *
+ * Without TRUSTED_PROXY_IPS, better-auth rejects a multi-value
+ * x-forwarded-for outright (it cannot tell which hop is the client), which is
+ * exactly the case that produces that shared bucket. Set it to the address or
+ * CIDR of Plesk's nginx. Conversely, listing a header the proxy does not
+ * overwrite lets a client set its own IP and mint itself an unlimited
+ * brute-force budget - so the default is the single header nginx sets, not a
+ * permissive list.
+ */
+
+/**
+ * `CLIENT_IP_HEADERS=none` trusts no header at all.
+ *
+ * This is the escape hatch for the one case where the wrong setting is worse
+ * than no setting: if the proxy turns out NOT to overwrite the header we are
+ * trusting, any client can send it and mint itself an unlimited brute-force
+ * budget against /sign-in. Falling back to the shared bucket is bad (one noisy
+ * client can lock the organisation out for ten seconds at a time) but it is
+ * bad in a way that fails closed, and it can be reverted from the environment
+ * without a deploy.
+ *
+ * Reach for it only after a check has actually failed - `SELECT ipAddress FROM
+ * session ORDER BY createdAt DESC` showing 127.0.0.1 or NULL for a real remote
+ * sign-in - and take it back out once the header is configured.
+ *
+ * An empty or unset value still means "use the default", not "trust nothing":
+ * a stray blank line in a .env must not silently change how requests are
+ * bucketed. Only the explicit word does that.
+ */
+const TRUST_NO_HEADER = 'none';
+
+export const TRUST_NO_CLIENT_IP_HEADER =
+	(process.env.CLIENT_IP_HEADERS || '').trim().toLowerCase() === TRUST_NO_HEADER;
+
+// An empty array is what better-auth reads as "no headers": it only falls back
+// to its own default when the option is absent, and `[]` is truthy.
+export const CLIENT_IP_HEADERS = TRUST_NO_CLIENT_IP_HEADER
+	? []
+	: parseList(process.env.CLIENT_IP_HEADERS, ['x-real-ip']);
+
+export const TRUSTED_PROXY_IPS = parseList(process.env.TRUSTED_PROXY_IPS, []);
+
+if (isProd && TRUST_NO_CLIENT_IP_HEADER) {
+	logger.warn(
+		'Admin module: CLIENT_IP_HEADERS=none - no client-IP header is trusted, so every ' +
+		'request shares one rate-limit bucket and /sign-in allows 3 attempts per 10 seconds ' +
+		'for everyone combined. This is the safe fallback, not a destination: configure the ' +
+		'header the proxy actually sets and remove it.'
+	);
+} else if (isProd && TRUSTED_PROXY_IPS.length === 0) {
+	logger.warn(
+		'Admin module: TRUSTED_PROXY_IPS is not set. If the proxy sends a multi-value ' +
+		`${CLIENT_IP_HEADERS.join('/')}, better-auth cannot resolve a client IP and every ` +
+		'request shares one rate-limit bucket. Verify with: SELECT `key` FROM rateLimit - ' +
+		'a "no-trusted-ip" row means this is happening. A single-value header needs no ' +
+		'trusted proxies, so this warning is expected on a plain single-proxy setup.'
+	);
+}
+
+export const ADMIN_BOOTSTRAP_EMAIL = process.env.ADMIN_BOOTSTRAP_EMAIL || '';
+
+/**
+ * Whether to write invitation links to the log. An invitation link is a live
+ * account-creation credential, so this is an explicit opt-in rather than
+ * something inferred from NODE_ENV: local work needs it (the mail relay is
+ * usually off, and only the token's hash is stored, so there is otherwise no
+ * way to walk the accept flow), and production must never have it.
+ *
+ * Refused outright in strict mode, so setting it in a production .env by
+ * accident fails at boot instead of quietly filling the log with credentials.
+ */
+export const LOG_INVITE_LINKS = process.env.ADMIN_LOG_INVITE_LINKS === 'true' && !isProd;
+
+if (process.env.ADMIN_LOG_INVITE_LINKS === 'true' && isProd) {
+	logger.error('Admin module: ADMIN_LOG_INVITE_LINKS is set outside development - refusing to log invitation tokens');
+}

src/models/admin/admin.errors.ts

@@ -0,0 +1,17 @@
+import {Response} from 'express';
+import {Guid} from 'guid-typescript';
+import logger from '../../middleware/logger.js';
+
+/**
+ * Same catch-block convention as the feedback and tickets modules: log with a
+ * reference guid, never hand the real error message to the client.
+ */
+export const sendServerError = (res: Response, e: any): void => {
+	const errorGuid = Guid.create().toString();
+	logger.error('Error handling a request: ' + e.message, {reference: errorGuid});
+	res.status(500).send({
+		status: 'PROCESSING_ERROR',
+		message: 'Internal Server Error. Try again later.',
+		reference: errorGuid
+	});
+};

src/models/admin/admin.interface.ts

@@ -0,0 +1,120 @@
+/**
+ * Swagger component definitions for the admin module. Picked up by
+ * swagger-jsdoc through the `src/models/**\/*.interface.ts` glob in
+ * app.factory.ts.
+ *
+ * Note what is *not* documented here: the better-auth routes under
+ * /admin/auth/* (sign-in, sign-out, reset-password, passkey ceremonies, and
+ * the invitation preview/accept endpoints). better-auth owns those paths and
+ * their shapes; duplicating them by hand would only drift on the next upgrade.
+ */
+
+/**
+ * @swagger
+ * components:
+ *   securitySchemes:
+ *     AdminSessionCookie:
+ *       type: apiKey
+ *       in: cookie
+ *       name: nachklang.session_token
+ *       description: >
+ *         Set by /admin/auth/sign-in/email. Over https the name is
+ *         __Secure-nachklang.session_token and the cookie is scoped to
+ *         .nachklang.art, so one sign-in covers every *.nachklang.art app.
+ *   schemas:
+ *     AdminApp:
+ *       type: string
+ *       enum: [calendar, feedback, tickets, admin]
+ *       description: Holding "admin" is what allows managing users and invitations.
+ *     AdminMe:
+ *       type: object
+ *       properties:
+ *         id:
+ *           type: string
+ *         email:
+ *           type: string
+ *         fullName:
+ *           type: string
+ *         apps:
+ *           type: array
+ *           items:
+ *             $ref: '#/components/schemas/AdminApp'
+ *     AdminUserSession:
+ *       type: object
+ *       properties:
+ *         id:
+ *           type: string
+ *         createdAt:
+ *           type: string
+ *           format: date-time
+ *         expiresAt:
+ *           type: string
+ *           format: date-time
+ *         ipAddress:
+ *           type: string
+ *           nullable: true
+ *         userAgent:
+ *           type: string
+ *           nullable: true
+ *     AdminUser:
+ *       type: object
+ *       properties:
+ *         id:
+ *           type: string
+ *         email:
+ *           type: string
+ *         name:
+ *           type: string
+ *         apps:
+ *           type: array
+ *           items:
+ *             $ref: '#/components/schemas/AdminApp'
+ *         status:
+ *           type: string
+ *           enum: [aktiv, deaktiviert]
+ *           description: Derived - there is no status column.
+ *         createdAt:
+ *           type: string
+ *           format: date-time
+ *         lastSignInAt:
+ *           type: string
+ *           format: date-time
+ *           nullable: true
+ *           description: Newest session's creation time; null once every session has expired.
+ *     AdminUserDetail:
+ *       allOf:
+ *         - $ref: '#/components/schemas/AdminUser'
+ *         - type: object
+ *           properties:
+ *             sessions:
+ *               type: array
+ *               items:
+ *                 $ref: '#/components/schemas/AdminUserSession'
+ *             passkeyCount:
+ *               type: integer
+ *     AdminInvitation:
+ *       type: object
+ *       description: An open invitation. The token itself is never returned by any endpoint.
+ *       properties:
+ *         id:
+ *           type: integer
+ *         email:
+ *           type: string
+ *         name:
+ *           type: string
+ *         apps:
+ *           type: array
+ *           items:
+ *             $ref: '#/components/schemas/AdminApp'
+ *         invitedBy:
+ *           type: string
+ *           nullable: true
+ *           description: Null for the invitation created by the ADMIN_BOOTSTRAP_EMAIL bootstrap.
+ *         createdAt:
+ *           type: string
+ *           format: date-time
+ *         expiresAt:
+ *           type: string
+ *           format: date-time
+ */
+export {};

src/models/admin/admin.mail.ts

@@ -0,0 +1,124 @@
+import {MailService} from '../../common/common.mail.js';
+import {ADMIN_APP_URL} from './admin.config.js';
+
+/**
+ * The two transactional mails the admin module sends. Both go out through the
+ * shared MailService (Salesforce relay, see common.mail.ts), which never throws
+ * on a delivery failure - the invitation row and the reset token are already
+ * committed by the time we get here.
+ *
+ * HTML plus a plain-text body: the text part is not a fallback afterthought,
+ * it is what allowlist-based receivers and text-only clients actually show.
+ */
+
+const escapeHtml = (value: string): string => {
+	return value
+		.replace(/&/g, '&')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
+		.replace(/"/g, '&quot;');
+};
+
+// `heading` is escaped here; `paragraphs` are not, because callers pass markup
+// (a <strong> around the expiry date) and escape their own interpolations.
+const layout = (heading: string, paragraphs: string[], buttonLabel: string, buttonUrl: string): string => {
+	const body = paragraphs.map(p => `<p style="margin:0 0 16px;">${p}</p>`).join('');
+	return `<!doctype html>
+<html lang="de">
+<body style="margin:0;padding:24px;background:#f5f5f4;font-family:Helvetica,Arial,sans-serif;color:#1c1917;">
+<div style="max-width:520px;margin:0 auto;background:#ffffff;border-radius:8px;padding:32px;">
+<h1 style="margin:0 0 24px;font-size:20px;">${escapeHtml(heading)}</h1>
+${body}
+<p style="margin:24px 0;">
+<a href="${escapeHtml(buttonUrl)}" style="display:inline-block;background:#1c1917;color:#ffffff;text-decoration:none;padding:12px 20px;border-radius:6px;">${escapeHtml(buttonLabel)}</a>
+</p>
+<p style="margin:0;font-size:13px;color:#57534e;">Falls der Button nicht funktioniert, kopiere diesen Link in deinen Browser:<br>
+<span style="word-break:break-all;">${escapeHtml(buttonUrl)}</span></p>
+</div>
+</body>
+</html>`;
+};
+
+/**
+ * Invitation mail. The link carries the raw token in the query string; the
+ * admin app strips it from the URL as soon as it has read it (see the plan's
+ * §3b - the token must never reach an API access log or a Referer header).
+ */
+export const sendInvitationMail = async (
+	recipientAddress: string,
+	name: string,
+	token: string,
+	expiresAt: Date
+): Promise<boolean> => {
+	const url = `${ADMIN_APP_URL}/accept-invite?token=${encodeURIComponent(token)}`;
+	const expiry = expiresAt.toLocaleDateString('de-DE', {day: '2-digit', month: '2-digit', year: 'numeric'});
+	const subject = 'Dein Zugang zu Nachklang';
+
+	const text = [
+		`Hallo ${name},`,
+		'',
+		'du wurdest eingeladen, ein Nachklang-Konto anzulegen. Über diesen Link vergibst du dein Passwort:',
+		'',
+		url,
+		'',
+		`Der Link ist bis zum ${expiry} gültig.`,
+		'',
+		'Wenn du damit nichts anfangen kannst, ignoriere diese E-Mail einfach.',
+		'',
+		'Viele Grüße',
+		'Nachklang e.V.'
+	].join('\n');
+
+	const html = layout(
+		`Hallo ${name},`,
+		[
+			'du wurdest eingeladen, ein Nachklang-Konto anzulegen. Über den Button vergibst du dein Passwort.',
+			`Der Link ist bis zum <strong>${escapeHtml(expiry)}</strong> gültig.`,
+			'Wenn du damit nichts anfangen kannst, ignoriere diese E-Mail einfach.'
+		],
+		'Konto einrichten',
+		url
+	);
+
+	return MailService.sendMail(recipientAddress, subject, text, {html});
+};
+
+/**
+ * Password reset. better-auth builds the URL (it embeds its own token and the
+ * redirectTo the admin app passed), so this only wraps it in our templates.
+ */
+export const sendPasswordResetMail = async (
+	recipientAddress: string,
+	name: string,
+	url: string
+): Promise<boolean> => {
+	const subject = 'Passwort zurücksetzen';
+
+	const text = [
+		`Hallo ${name},`,
+		'',
+		'über diesen Link kannst du ein neues Passwort vergeben:',
+		'',
+		url,
+		'',
+		'Der Link ist eine Stunde gültig.',
+		'',
+		'Wenn du kein neues Passwort angefordert hast, ist nichts passiert - ignoriere diese E-Mail.',
+		'',
+		'Viele Grüße',
+		'Nachklang e.V.'
+	].join('\n');
+
+	const html = layout(
+		`Hallo ${name},`,
+		[
+			'über den Button kannst du ein neues Passwort vergeben.',
+			'Der Link ist eine Stunde gültig.',
+			'Wenn du kein neues Passwort angefordert hast, ist nichts passiert - ignoriere diese E-Mail.'
+		],
+		'Neues Passwort vergeben',
+		url
+	);
+
+	return MailService.sendMail(recipientAddress, subject, text, {html});
+};

src/models/admin/admin.middleware.ts

@@ -0,0 +1,140 @@
+import express from 'express';
+import {fromNodeHeaders} from 'better-auth/node';
+import {auth} from './admin.auth.js';
+import * as UsersService from './users/users.admin.service.js';
+import {AppName, AppPermission, AppRole} from './admin.schema.js';
+import {sendServerError} from './admin.errors.js';
+
+/**
+ * The one authenticator for every admin area in this API. It replaces
+ * feedback.auth.ts and tickets.auth.ts, which each re-implemented the same
+ * header-session check against the calendar users table.
+ *
+ * Two things are checked on every request, deliberately without any caching:
+ * that the session cookie is valid (better-auth), and that the user is still
+ * enabled and still holds the permission for this app (one database query).
+ * That is what makes "disable a user" and "revoke a session" take effect
+ * immediately rather than whenever a cached session happens to expire.
+ */
+
+// The shape the feedback and tickets services already expect - unchanged, so
+// nothing downstream of the authenticator needs to know this file replaced
+// their own.
+export interface AdminIdentity {
+	id: string;
+	email: string;
+	displayName: string;
+}
+
+export interface AdminAccess extends AdminIdentity {
+	disabled: boolean;
+	/** Every (app, role) grant. */
+	permissions: AppPermission[];
+	/** The distinct apps those grants cover. */
+	apps: AppName[];
+}
+
+const unauthorized = (res: express.Response): void => {
+	res.status(401).send({status: 'UNAUTHORIZED', message: 'Anmeldung erforderlich.'});
+};
+
+const forbidden = (res: express.Response, message: string): void => {
+	res.status(403).send({status: 'FORBIDDEN', message});
+};
+
+/**
+ * Resolves the session cookie to a user with their permissions, or null.
+ * One database query, no cache. Throws only on infrastructure errors.
+ */
+export const resolveAccess = async (req: express.Request): Promise<AdminAccess | null> => {
+	const session = await auth.api.getSession({headers: fromNodeHeaders(req.headers)});
+	if (!session?.user) {
+		return null;
+	}
+
+	const access = await UsersService.loadAccess(session.user.id);
+	if (!access) {
+		return null;
+	}
+
+	return {
+		id: access.id,
+		email: access.email,
+		displayName: access.displayName,
+		disabled: access.disabled,
+		permissions: access.permissions,
+		apps: access.apps
+	};
+};
+
+/**
+ * Any signed-in account, no permission required. Used by /admin/me and the
+ * account-management routes: a user with no app permissions at all still has
+ * to be able to see that, and to manage their own password and passkeys.
+ *
+ * The disabled check is not redundant with the session-create hook: that hook
+ * stops a disabled user from signing in, this stops one who was disabled while
+ * holding a live cookie. Disabling revokes sessions, so the window is small -
+ * but "small" is not "closed".
+ */
+export const requireSignedIn: express.RequestHandler = async (req, res, next) => {
+	try {
+		const access = await resolveAccess(req);
+		if (!access) {
+			unauthorized(res);
+			return;
+		}
+		if (access.disabled) {
+			forbidden(res, 'Dieses Konto ist deaktiviert.');
+			return;
+		}
+
+		res.locals.admin = access;
+		next();
+	} catch (e: any) {
+		sendServerError(res, e);
+	}
+};
+
+/**
+ * The gate every admin area sits behind. `requireAppAccess('feedback')` is
+ * what feedback.auth.ts's requireAdminAuth used to be, except that it now
+ * answers 403 for a signed-in user without that app's permission instead of
+ * letting any activated @nachklang.art account in.
+ *
+ * The optional second argument narrows it to one role within the app. Nothing
+ * passes it today - every app has exactly the `access` role - but it is the
+ * seam a finer permission arrives through.
+ */
+export const requireAppAccess = (app: AppName, role?: AppRole): express.RequestHandler => {
+	return async (req, res, next) => {
+		try {
+			const access = await resolveAccess(req);
+			if (!access) {
+				unauthorized(res);
+				return;
+			}
+			if (access.disabled) {
+				forbidden(res, 'Dieses Konto ist deaktiviert.');
+				return;
+			}
+
+			// Without a role this asks "may they open this app at all?", which is
+			// any grant on it. With one it asks for that specific grant - the hook
+			// a finer permission plugs into, without touching existing call sites.
+			const allowed = role === undefined
+				? access.apps.includes(app)
+				: access.permissions.some(permission => permission.app === app && permission.role === role);
+
+			if (!allowed) {
+				forbidden(res, 'Für diesen Bereich fehlt dir die Berechtigung.');
+				return;
+			}
+
+			res.locals.admin = access;
+			next();
+		} catch (e: any) {
+			sendServerError(res, e);
+		}
+	};
+};

src/models/admin/admin.schema.ts

@@ -0,0 +1,179 @@
+import {Generated} from 'kysely';
+
+/**
+ * Kysely table types for `nachklang_admin`. Only the columns this module
+ * actually reads or writes are declared - better-auth owns the full shape of
+ * its own tables and does not use this interface, it is here so the users and
+ * invitations services get compile-time checking instead of `any`.
+ *
+ * Column names follow better-auth's default "camel" casing for its tables
+ * (`emailVerified`, `userId`, `createdAt`); our own two tables use the
+ * snake_case convention of the rest of the repo's SQL.
+ */
+
+export type AppName = 'calendar' | 'feedback' | 'tickets' | 'admin';
+
+export const APP_NAMES: AppName[] = ['calendar', 'feedback', 'tickets', 'admin'];
+
+export const isAppName = (value: unknown): value is AppName => {
+	return typeof value === 'string' && (APP_NAMES as string[]).includes(value);
+};
+
+/**
+ * A permission is (app, role), not just an app. Today every app has exactly one
+ * role - `access`, "may use this app at all" - so the model looks like a plain
+ * list of apps and the UI renders one checkbox each. It is written this way
+ * anyway because the alternative gets expensive fast: `user_app_permissions`
+ * has primary key (user_id, app, role), so a user can hold several roles for
+ * the same app, and adding one later is a string in APP_ROLES plus rows - never
+ * a schema migration and never a change to the shape on the wire.
+ *
+ * Note the role is deliberately NOT called `admin`, which is what the column
+ * defaulted to before: on a `tickets` row that reads as "tickets administrator"
+ * when it only ever meant "has access", and once real roles exist there would
+ * be no way to tell the two apart.
+ */
+export const ACCESS_ROLE = 'access';
+
+export type AppRole = string;
+
+/** Every role that exists, per app, in display order. Extend to add one. */
+export const APP_ROLES: Record<AppName, readonly AppRole[]> = {
+	calendar: [ACCESS_ROLE],
+	feedback: [ACCESS_ROLE],
+	tickets: [ACCESS_ROLE],
+	admin: [ACCESS_ROLE]
+};
+
+export interface AppPermission {
+	app: AppName;
+	role: AppRole;
+}
+
+export const isAppRole = (app: AppName, role: unknown): role is AppRole => {
+	return typeof role === 'string' && APP_ROLES[app].includes(role);
+};
+
+export const isAppPermission = (value: unknown): value is AppPermission => {
+	if (typeof value !== 'object' || value === null) {
+		return false;
+	}
+	const candidate = value as {app?: unknown; role?: unknown};
+	return isAppName(candidate.app) && isAppRole(candidate.app, candidate.role);
+};
+
+/**
+ * Normalises whatever a caller sent into a valid, duplicate-free permission
+ * list. Accepts the richer `{app, role}` form and the plain `AppName` form,
+ * because `{apps: ['tickets']}` is still what the older callers send and it
+ * means exactly "tickets at the access role".
+ */
+export const toPermissions = (value: unknown): AppPermission[] | null => {
+	if (!Array.isArray(value)) {
+		return null;
+	}
+
+	const permissions: AppPermission[] = [];
+	for (const entry of value) {
+		if (isAppName(entry)) {
+			permissions.push({app: entry, role: ACCESS_ROLE});
+		} else if (isAppPermission(entry)) {
+			permissions.push({app: entry.app, role: entry.role});
+		} else {
+			return null;
+		}
+	}
+
+	const seen = new Set<string>();
+	return permissions.filter(permission => {
+		const key = `${permission.app}:${permission.role}`;
+		if (seen.has(key)) {
+			return false;
+		}
+		seen.add(key);
+		return true;
+	});
+};
+
+/** The distinct apps a permission list grants any access to. */
+export const appsOf = (permissions: AppPermission[]): AppName[] => {
+	return APP_NAMES.filter(app => permissions.some(permission => permission.app === app));
+};
+
+export interface UserTable {
+	id: string;
+	name: string;
+	email: string;
+	emailVerified: boolean;
+	image: string | null;
+	createdAt: Date;
+	updatedAt: Date;
+	// Added via better-auth `additionalFields` (see admin.auth.ts).
+	disabled: boolean;
+}
+
+export interface SessionTable {
+	id: string;
+	token: string;
+	userId: string;
+	expiresAt: Date;
+	createdAt: Date;
+	updatedAt: Date;
+	ipAddress: string | null;
+	userAgent: string | null;
+}
+
+export interface PasskeyTable {
+	id: string;
+	name: string | null;
+	userId: string;
+	createdAt: Date;
+}
+
+export interface UserAppPermissionTable {
+	user_id: string;
+	app: AppName;
+	role: AppRole;
+	granted_by: string | null;
+	granted_at: Generated<Date>;
+}
+
+export interface InvitationTable {
+	// AUTO_INCREMENT: present on select, never supplied on insert.
+	id: Generated<number>;
+	email: string;
+	name: string;
+	token_hash: string;
+	// JSON column holding an AppPermission[]. Older rows may hold a plain
+	// AppName[]; `parsePermissions` reads both.
+	permissions: string;
+	invited_by: string | null;
+	created_at: Generated<Date>;
+	expires_at: Date;
+	accepted_at: Date | null;
+	revoked_at: Date | null;
+}
+
+export interface VerificationTable {
+	id: string;
+	identifier: string;
+	value: string;
+	expiresAt: Date;
+}
+
+export interface RateLimitTable {
+	id: string;
+	key: string;
+	count: number;
+	lastRequest: number;
+}
+
+export interface AdminDatabase {
+	user: UserTable;
+	session: SessionTable;
+	passkey: PasskeyTable;
+	verification: VerificationTable;
+	rateLimit: RateLimitTable;
+	user_app_permissions: UserAppPermissionTable;
+	invitations: InvitationTable;
+}

src/models/admin/invitations/invitations.plugin.ts

@@ -0,0 +1,196 @@
+import * as z from 'zod';
+import {APIError, createAuthEndpoint} from 'better-auth/api';
+import {setSessionCookie} from 'better-auth/cookies';
+import {createLocalAccountIssuer} from 'better-auth/db';
+import {runWithTransaction} from '@better-auth/core/context';
+import type {BetterAuthPlugin} from 'better-auth';
+import * as InvitationsService from './invitations.service.js';
+import * as UsersService from '../users/users.admin.service.js';
+import logger from '../../../middleware/logger.js';
+
+/**
+ * The two public endpoints of the invitation flow, implemented as a better-auth
+ * plugin rather than as plain Express routes on the admin router.
+ *
+ * Why a plugin: `emailAndPassword.disableSignUp` is on, which makes
+ * `auth.api.signUpEmail` refuse - deliberately, there is no public sign-up.
+ * Accepting an invitation still has to create a user, hash a password, write a
+ * credential account and sign the person in. All four are better-auth
+ * internals reachable only from inside an endpoint's context, so this is where
+ * account creation lives. Nothing outside this file may create users.
+ *
+ * Because they are plugin endpoints they sit under better-auth's basePath:
+ *   POST /admin/auth/invitations/preview
+ *   POST /admin/auth/invitations/accept
+ *
+ * The token travels in the request *body*, never in the path or query, so it
+ * cannot end up in an access log or a Referer header.
+ */
+
+// Unknown, expired, revoked and already-accepted tokens must be
+// indistinguishable to the caller: one shared error, one shared message.
+const invalidToken = (): APIError => {
+	return new APIError('BAD_REQUEST', {
+		code: 'INVALID_INVITATION',
+		message: 'Diese Einladung ist nicht mehr gültig.'
+	});
+};
+
+export const invitationsPlugin = () => {
+	return {
+		id: 'nachklang-invitations',
+		endpoints: {
+			/**
+			 * Lets the accept-invite page show who the invitation is for before
+			 * asking for a password. Returns only name and email - never the
+			 * granted apps, which is information the invitee has no need for
+			 * and an attacker with a stolen link should not get either.
+			 */
+			previewInvitation: createAuthEndpoint(
+				'/invitations/preview',
+				{
+					method: 'POST',
+					body: z.object({
+						token: z.string().min(1)
+					})
+				},
+				async ctx => {
+					const invitation = await InvitationsService.findByToken(ctx.body.token);
+					if (!invitation) {
+						throw invalidToken();
+					}
+
+					return ctx.json({email: invitation.email, name: invitation.name});
+				}
+			),
+
+			/**
+			 * Redeems the invitation: creates the user, its credential account
+			 * and its permissions, then signs the person straight in so they
+			 * land in the app instead of on a login form.
+			 */
+			acceptInvitation: createAuthEndpoint(
+				'/invitations/accept',
+				{
+					method: 'POST',
+					body: z.object({
+						token: z.string().min(1),
+						password: z.string().min(8).max(128)
+					})
+				},
+				async ctx => {
+					const invitation = await InvitationsService.findByToken(ctx.body.token);
+					if (!invitation) {
+						throw invalidToken();
+					}
+
+					// An account for this address already exists: the right fix
+					// is for an admin to grant permissions on the existing user,
+					// not to create a second one. Reported distinctly because
+					// the person holds a valid token - this leaks nothing they
+					// do not already know about their own mailbox.
+					const existing = await UsersService.findUserByEmail(invitation.email);
+					if (existing) {
+						throw new APIError('CONFLICT', {
+							code: 'USER_ALREADY_EXISTS',
+							message: 'Für diese E-Mail-Adresse gibt es bereits ein Konto. Melde dich stattdessen an.'
+						});
+					}
+
+					// Claim the invitation before creating anything. The update
+					// is conditional on it still being open, so two concurrent
+					// submissions of the same link cannot both end up creating a
+					// user.
+					const claimed = await InvitationsService.markAccepted(invitation.id);
+					if (!claimed) {
+						throw invalidToken();
+					}
+
+					// The user and its credential account go in one better-auth
+					// transaction, the way better-auth's own sign-up route does
+					// it: a half-created account with no password is not
+					// recoverable through any route this API exposes.
+					//
+					// It cannot cover everything, though. `user_app_permissions`
+					// and `invitations` are written through this module's own
+					// Kysely pool, which is a different connection, so no single
+					// transaction spans both. What follows is therefore
+					// compensated by hand rather than rolled back.
+					let user: Awaited<ReturnType<typeof ctx.context.internalAdapter.createUser>> | null = null;
+					try {
+						user = await runWithTransaction(ctx.context.adapter, async () => {
+							const created = await ctx.context.internalAdapter.createUser(
+								{
+									email: invitation.email,
+									name: invitation.name,
+									// Accepting a link sent to that mailbox *is*
+									// the proof of address ownership, so there is
+									// no separate verification mail (plan
+									// decision 15).
+									emailVerified: true,
+									disabled: false
+								},
+								{method: 'email-password'}
+							);
+
+							// Same call better-auth's own sign-up route makes,
+							// down to the synthetic issuer - a credential account
+							// written any other way is not found on sign-in.
+							await ctx.context.internalAdapter.linkAccount({
+								userId: created.id,
+								providerId: 'credential',
+								issuer: createLocalAccountIssuer('credential'),
+								accountId: created.id,
+								password: await ctx.context.password.hash(ctx.body.password)
+							});
+
+							return created;
+						});
+
+						await UsersService.setPermissions(user.id, invitation.permissions, null);
+
+						const session = await ctx.context.internalAdapter.createSession(user.id);
+						await setSessionCookie(ctx, {session, user});
+
+						return ctx.json({
+							user: {id: user.id, email: user.email, name: user.name}
+						});
+					} catch (e: any) {
+						// Undo what committed, so the invitee can use their link
+						// again instead of being stranded with a burnt token, an
+						// account they cannot sign into, and an admin who cannot
+						// re-invite them (the create route 409s on an existing
+						// user, and there is no delete route by design).
+						//
+						// Deleting the user is safe here: it was created moments
+						// ago in this request, and acceptance already established
+						// that no account for this address existed before.
+						try {
+							if (user) {
+								await ctx.context.internalAdapter.deleteUser(user.id);
+							}
+							await InvitationsService.unmarkAccepted(invitation.id);
+						} catch (compensationError: any) {
+							// Now the state really is inconsistent, and only a
+							// human can sort it out. Say so loudly and precisely.
+							logger.error('Admin: invitation acceptance failed AND its rollback failed', {
+								invitationId: invitation.id,
+								email: invitation.email,
+								userId: user?.id,
+								detail: e?.message,
+								compensationDetail: compensationError?.message
+							});
+							throw e;
+						}
+
+						logger.error('Admin: invitation acceptance failed and was rolled back', {
+							invitationId: invitation.id,
+							detail: e?.message
+						});
+						throw e;
+					}
+				}
+			)
+		}
+	} satisfies BetterAuthPlugin;
+};

src/models/admin/invitations/invitations.router.ts

@@ -0,0 +1,208 @@
+import express, {Request, Response} from 'express';
+import * as InvitationsService from './invitations.service.js';
+import * as UsersService from '../users/users.admin.service.js';
+import {toPermissions} from '../admin.schema.js';
+import {sendInvitationMail} from '../admin.mail.js';
+import {ADMIN_APP_URL, LOG_INVITE_LINKS} from '../admin.config.js';
+import {sendServerError} from '../admin.errors.js';
+import logger from '../../../middleware/logger.js';
+
+export const invitationsRouter = express.Router();
+
+/**
+ * The admin-facing half of invitations (create, resend, revoke). The public
+ * half - preview and accept - lives in invitations.plugin.ts, because
+ * redeeming an invitation has to create a user through better-auth internals.
+ *
+ * Mounted behind requireAppAccess('admin').
+ */
+
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+/**
+ * With the mail relay off (the normal local setup) the invitation mail never
+ * arrives, and only the token's hash is stored, so there would be no way to
+ * walk through the accept flow. Logging the link closes that.
+ *
+ * Gated on an explicit opt-in rather than on NODE_ENV: the link is a live
+ * account-creation credential, and "not production" is too weak a condition to
+ * hang that on. See LOG_INVITE_LINKS in admin.config.ts.
+ */
+const logInviteLinkInDev = (token: string): void => {
+	if (LOG_INVITE_LINKS) {
+		logger.info(`Admin: invitation link ${ADMIN_APP_URL}/accept-invite?token=${encodeURIComponent(token)}`);
+	}
+};
+
+/**
+ * @swagger
+ * /admin/invitations:
+ *      get:
+ *          summary: List open (unaccepted, unrevoked, unexpired) invitations
+ *          tags: [admin]
+ *          responses:
+ *              200:
+ *                  description: Success
+ */
+invitationsRouter.get('/', async (req: Request, res: Response) => {
+	try {
+		res.status(200).send(await InvitationsService.listOpenInvitations());
+	} catch (e: any) {
+		sendServerError(res, e);
+	}
+});
+
+/**
+ * @swagger
+ * /admin/invitations:
+ *      post:
+ *          summary: Invite someone and mail them an acceptance link
+ *          tags: [admin]
+ *          requestBody:
+ *              required: true
+ *              content:
+ *                  application/json:
+ *                      schema:
+ *                          type: object
+ *                          required: [email, name, permissions]
+ *                          properties:
+ *                              email:
+ *                                  type: string
+ *                              name:
+ *                                  type: string
+ *                              permissions:
+ *                                  type: array
+ *                                  description: >
+ *                                      One entry per (app, role). A plain array of app names is
+ *                                      accepted too and means the same at the `access` role.
+ *                                  items:
+ *                                      type: object
+ *                                      properties:
+ *                                          app:
+ *                                              type: string
+ *                                          role:
+ *                                              type: string
+ *          responses:
+ *              201:
+ *                  description: Invitation created and mailed
+ *              400:
+ *                  description: Invalid input
+ *              409:
+ *                  description: A user with this address already exists
+ */
+invitationsRouter.post('/', async (req: Request, res: Response) => {
+	try {
+		const email = String(req.body?.email || '').trim().toLowerCase();
+		const name = String(req.body?.name || '').trim();
+
+		// Same two accepted shapes as PUT /admin/users/:id/permissions.
+		const permissions = toPermissions(req.body?.permissions ?? req.body?.apps);
+
+		if (!EMAIL_PATTERN.test(email) || name.length === 0 || !permissions) {
+			res.status(400).send({
+				status: 'BAD_REQUEST',
+				message: 'E-Mail, Name und Berechtigungen sind erforderlich.'
+			});
+			return;
+		}
+
+		// Inviting someone who already has an account would strand them on an
+		// accept page that can only fail. Granting permissions on the existing
+		// user is the operation they actually want.
+		if (await UsersService.findUserByEmail(email)) {
+			res.status(409).send({
+				status: 'CONFLICT',
+				message: 'Für diese E-Mail-Adresse gibt es bereits ein Konto. Vergib dort die Berechtigungen.'
+			});
+			return;
+		}
+
+		const invitation = await InvitationsService.createInvitation(
+			email,
+			name,
+			permissions,
+			res.locals.admin.id
+		);
+
+		const mailed = await sendInvitationMail(email, name, invitation.token, invitation.expiresAt);
+		if (!mailed) {
+			logger.warn('Admin: invitation created but the mail was not accepted', {email});
+		}
+		logInviteLinkInDev(invitation.token);
+
+		res.status(201).send({id: invitation.id, email, name, expiresAt: invitation.expiresAt, mailed});
+	} catch (e: any) {
+		sendServerError(res, e);
+	}
+});
+
+/**
+ * @swagger
+ * /admin/invitations/{invitationId}/resend:
+ *      post:
+ *          summary: Issue a new token for an open invitation and mail it again
+ *          description: The previous link stops working.
+ *          tags: [admin]
+ *          responses:
+ *              200:
+ *                  description: Resent
+ *              404:
+ *                  description: No open invitation with this id
+ */
+invitationsRouter.post('/:invitationId/resend', async (req: Request, res: Response) => {
+	try {
+		const invitationId = parseInt(req.params.invitationId, 10);
+		if (Number.isNaN(invitationId)) {
+			res.status(400).send({status: 'BAD_REQUEST', message: 'Ungültige Einladungs-ID.'});
+			return;
+		}
+
+		const resent = await InvitationsService.resendInvitation(invitationId);
+		if (!resent) {
+			res.status(404).send({status: 'NOT_FOUND', message: 'Einladung nicht gefunden.'});
+			return;
+		}
+
+		const mailed = await sendInvitationMail(resent.email, resent.name, resent.token, resent.expiresAt);
+		if (!mailed) {
+			logger.warn('Admin: invitation resent but the mail was not accepted', {email: resent.email});
+		}
+		logInviteLinkInDev(resent.token);
+
+		res.status(200).send({id: invitationId, expiresAt: resent.expiresAt, mailed});
+	} catch (e: any) {
+		sendServerError(res, e);
+	}
+});
+
+/**
+ * @swagger
+ * /admin/invitations/{invitationId}:
+ *      delete:
+ *          summary: Revoke an open invitation
+ *          tags: [admin]
+ *          responses:
+ *              204:
+ *                  description: Revoked
+ *              404:
+ *                  description: No open invitation with this id
+ */
+invitationsRouter.delete('/:invitationId', async (req: Request, res: Response) => {
+	try {
+		const invitationId = parseInt(req.params.invitationId, 10);
+		if (Number.isNaN(invitationId)) {
+			res.status(400).send({status: 'BAD_REQUEST', message: 'Ungültige Einladungs-ID.'});
+			return;
+		}
+
+		const revoked = await InvitationsService.revokeInvitation(invitationId);
+		if (!revoked) {
+			res.status(404).send({status: 'NOT_FOUND', message: 'Einladung nicht gefunden.'});
+			return;
+		}
+
+		res.status(204).send();
+	} catch (e: any) {
+		sendServerError(res, e);
+	}
+});

src/models/admin/invitations/invitations.service.ts

@@ -0,0 +1,239 @@
+import * as crypto from 'crypto';
+import {NachklangAdminDB} from '../Admin.db.js';
+import {AppPermission, isAppName, isAppPermission, ACCESS_ROLE} from '../admin.schema.js';
+
+const db = NachklangAdminDB.db;
+
+/**
+ * Invitations are this API's only path to a new account (there is no public
+ * sign-up). The raw token exists exactly twice: in the mail we send and in the
+ * request body when it comes back. What we store is its SHA-256 hash, so a
+ * database dump does not hand out account access - the same reasoning as the
+ * calendar module's session key hashing, and the reason lookups go through
+ * `findByToken` rather than any query on a plaintext column.
+ */
+
+export const INVITATION_TTL_DAYS = 7;
+
+export interface OpenInvitation {
+	id: number;
+	email: string;
+	name: string;
+	permissions: AppPermission[];
+	invitedBy: string | null;
+	createdAt: Date;
+	expiresAt: Date;
+}
+
+export interface AcceptableInvitation {
+	id: number;
+	email: string;
+	name: string;
+	permissions: AppPermission[];
+}
+
+const hashToken = (token: string): string => {
+	return crypto.createHash('sha256').update(token).digest('hex');
+};
+
+const generateToken = (): string => {
+	// 32 bytes, url-safe: it travels in a mail link's query string.
+	return crypto.randomBytes(32).toString('base64url');
+};
+
+/**
+ * Reads the stored permission list. Two shapes are accepted: the current
+ * `[{app, role}]`, and a bare `['tickets', ...]` from before roles existed,
+ * which means the same thing at the `access` role. Invitations live for seven
+ * days, so a deploy that changes the shape has in-flight rows in the old one -
+ * tolerating both is what stops those invitees from being stranded.
+ *
+ * mysql2 hands back a JSON column already parsed; a driver or column-type
+ * change that turns it into a string must not break the read path either.
+ */
+const parsePermissions = (value: unknown): AppPermission[] => {
+	const raw = typeof value === 'string' ? JSON.parse(value) : value;
+	if (!Array.isArray(raw)) {
+		return [];
+	}
+
+	return raw.flatMap((entry): AppPermission[] => {
+		if (isAppName(entry)) {
+			return [{app: entry, role: ACCESS_ROLE}];
+		}
+		return isAppPermission(entry) ? [{app: entry.app, role: entry.role}] : [];
+	});
+};
+
+const expiryFromNow = (): Date => {
+	return new Date(Date.now() + INVITATION_TTL_DAYS * 24 * 60 * 60 * 1000);
+};
+
+/**
+ * Creates an invitation and returns the raw token for the mail. Any earlier
+ * open invitation for the same address is revoked first: two valid links for
+ * one mailbox is a needless second live credential, and "resend" would
+ * otherwise quietly accumulate them.
+ */
+export const createInvitation = async (
+	email: string,
+	name: string,
+	permissions: AppPermission[],
+	invitedBy: string | null
+): Promise<{id: number; token: string; expiresAt: Date}> => {
+	const token = generateToken();
+	const expiresAt = expiryFromNow();
+	const valid = permissions.filter(isAppPermission);
+
+	const id = await db.transaction().execute(async trx => {
+		await trx
+			.updateTable('invitations')
+			.set({revoked_at: new Date()})
+			.where('email', '=', email)
+			.where('accepted_at', 'is', null)
+			.where('revoked_at', 'is', null)
+			.execute();
+
+		const result = await trx
+			.insertInto('invitations')
+			.values({
+				email,
+				name,
+				token_hash: hashToken(token),
+				permissions: JSON.stringify(valid),
+				invited_by: invitedBy,
+				created_at: new Date(),
+				expires_at: expiresAt
+			})
+			.executeTakeFirst();
+
+		return Number(result.insertId);
+	});
+
+	return {id, token, expiresAt};
+};
+
+/**
+ * Looks up a still-usable invitation by raw token. Callers must not
+ * distinguish "unknown", "expired", "revoked" and "already accepted" to the
+ * client: all four answer with the same shape, so a stranger cannot probe which
+ * tokens ever existed.
+ */
+export const findByToken = async (token: string): Promise<AcceptableInvitation | null> => {
+	const row = await db
+		.selectFrom('invitations')
+		.select(['id', 'email', 'name', 'permissions'])
+		.where('token_hash', '=', hashToken(token))
+		.where('accepted_at', 'is', null)
+		.where('revoked_at', 'is', null)
+		.where('expires_at', '>', new Date())
+		.executeTakeFirst();
+
+	if (!row) {
+		return null;
+	}
+
+	return {id: row.id, email: row.email, name: row.name, permissions: parsePermissions(row.permissions)};
+};
+
+/** Marks the invitation accepted. Conditional on it still being open so two
+ *  concurrent accepts of the same link cannot both create an account. */
+export const markAccepted = async (invitationId: number): Promise<boolean> => {
+	const result = await db
+		.updateTable('invitations')
+		.set({accepted_at: new Date()})
+		.where('id', '=', invitationId)
+		.where('accepted_at', 'is', null)
+		.where('revoked_at', 'is', null)
+		.executeTakeFirst();
+
+	return Number(result.numUpdatedRows) > 0;
+};
+
+/**
+ * Reverses markAccepted. Used only to compensate a failed acceptance: the user
+ * could not be created, so the link must become usable again rather than
+ * stranding the invitee with a burnt token and no account.
+ */
+export const unmarkAccepted = async (invitationId: number): Promise<void> => {
+	await db
+		.updateTable('invitations')
+		.set({accepted_at: null})
+		.where('id', '=', invitationId)
+		.execute();
+};
+
+export const listOpenInvitations = async (): Promise<OpenInvitation[]> => {
+	const rows = await db
+		.selectFrom('invitations')
+		.select(['id', 'email', 'name', 'permissions', 'invited_by', 'created_at', 'expires_at'])
+		.where('accepted_at', 'is', null)
+		.where('revoked_at', 'is', null)
+		.where('expires_at', '>', new Date())
+		.orderBy('created_at', 'desc')
+		.execute();
+
+	return rows.map(row => ({
+		id: row.id,
+		email: row.email,
+		name: row.name,
+		permissions: parsePermissions(row.permissions),
+		invitedBy: row.invited_by,
+		createdAt: row.created_at,
+		expiresAt: row.expires_at
+	}));
+};
+
+export const getOpenInvitation = async (invitationId: number): Promise<OpenInvitation | null> => {
+	const all = await listOpenInvitations();
+	return all.find(invitation => invitation.id === invitationId) ?? null;
+};
+
+/** Resend issues a *new* token and expiry and invalidates the old one, rather
+ *  than re-mailing the existing link: if the first mail leaked, resending it
+ *  would extend the leak's lifetime. */
+export const resendInvitation = async (
+	invitationId: number
+): Promise<{token: string; email: string; name: string; expiresAt: Date} | null> => {
+	const invitation = await getOpenInvitation(invitationId);
+	if (!invitation) {
+		return null;
+	}
+
+	const token = generateToken();
+	const expiresAt = expiryFromNow();
+
+	await db
+		.updateTable('invitations')
+		.set({token_hash: hashToken(token), expires_at: expiresAt, created_at: new Date()})
+		.where('id', '=', invitationId)
+		.execute();
+
+	return {token, email: invitation.email, name: invitation.name, expiresAt};
+};
+
+export const revokeInvitation = async (invitationId: number): Promise<boolean> => {
+	const result = await db
+		.updateTable('invitations')
+		.set({revoked_at: new Date()})
+		.where('id', '=', invitationId)
+		.where('accepted_at', 'is', null)
+		.where('revoked_at', 'is', null)
+		.executeTakeFirst();
+
+	return Number(result.numUpdatedRows) > 0;
+};
+
+/** Used by the bootstrap to stay idempotent across restarts. */
+export const hasOpenInvitationFor = async (email: string): Promise<boolean> => {
+	const row = await db
+		.selectFrom('invitations')
+		.select('id')
+		.where('email', '=', email)
+		.where('accepted_at', 'is', null)
+		.where('revoked_at', 'is', null)
+		.where('expires_at', '>', new Date())
+		.executeTakeFirst();
+
+	return Boolean(row);
+};

src/models/admin/users/users.admin.router.ts

@@ -0,0 +1,247 @@
+import express, {Request, Response} from 'express';
+import * as UsersService from './users.admin.service.js';
+import {toPermissions} from '../admin.schema.js';
+import {sendServerError} from '../admin.errors.js';
+
+export const usersAdminRouter = express.Router();
+
+/**
+ * User administration. Mounted behind requireAppAccess('admin'), so every
+ * handler here can assume res.locals.admin is an admin.
+ *
+ * The guards below exist because this API can lock its own operators out: the
+ * only way to grant a permission is through these routes, so an admin who
+ * removes the last `admin` permission leaves nobody who can put it back short
+ * of a manual SQL statement in production.
+ */
+
+const conflict = (res: Response, message: string): void => {
+	res.status(409).send({status: 'CONFLICT', message});
+};
+
+const notFound = (res: Response): void => {
+	res.status(404).send({status: 'NOT_FOUND', message: 'Benutzer nicht gefunden.'});
+};
+
+/**
+ * @swagger
+ * /admin/users:
+ *      get:
+ *          summary: List all users with their app permissions and status
+ *          tags: [admin]
+ *          responses:
+ *              200:
+ *                  description: Success
+ *              401:
+ *                  description: Not signed in
+ *              403:
+ *                  description: Missing the admin permission
+ */
+usersAdminRouter.get('/', async (req: Request, res: Response) => {
+	try {
+		res.status(200).send(await UsersService.listUsers());
+	} catch (e: any) {
+		sendServerError(res, e);
+	}
+});
+
+/**
+ * @swagger
+ * /admin/users/{userId}:
+ *      get:
+ *          summary: One user with their active sessions and passkey count
+ *          tags: [admin]
+ *          parameters:
+ *              - in: path
+ *                name: userId
+ *                required: true
+ *                schema:
+ *                    type: string
+ *          responses:
+ *              200:
+ *                  description: Success
+ *              404:
+ *                  description: Unknown user
+ */
+usersAdminRouter.get('/:userId', async (req: Request, res: Response) => {
+	try {
+		const detail = await UsersService.getUserDetail(req.params.userId);
+		if (!detail) {
+			notFound(res);
+			return;
+		}
+		res.status(200).send(detail);
+	} catch (e: any) {
+		sendServerError(res, e);
+	}
+});
+
+/**
+ * @swagger
+ * /admin/users/{userId}/permissions:
+ *      put:
+ *          summary: Replace a user's app permissions
+ *          description: Refuses to remove the caller's own admin permission or the last remaining active admin.
+ *          tags: [admin]
+ *          requestBody:
+ *              required: true
+ *              content:
+ *                  application/json:
+ *                      schema:
+ *                          type: object
+ *                          properties:
+ *                              permissions:
+ *                                  type: array
+ *                                  description: >
+ *                                      One entry per (app, role). `access` is the only role today.
+ *                                      A plain array of app names is also accepted and means the
+ *                                      same at the `access` role.
+ *                                  items:
+ *                                      type: object
+ *                                      properties:
+ *                                          app:
+ *                                              type: string
+ *                                              enum: [calendar, feedback, tickets, admin]
+ *                                          role:
+ *                                              type: string
+ *                                              enum: [access]
+ *          responses:
+ *              200:
+ *                  description: Success
+ *              400:
+ *                  description: Invalid app or role
+ *              409:
+ *                  description: Would lock the last admin out
+ */
+usersAdminRouter.put('/:userId/permissions', async (req: Request, res: Response) => {
+	try {
+		const userId = req.params.userId;
+
+		// `permissions: [{app, role}]` is the real shape; `apps: ['tickets']` is
+		// accepted as shorthand for the same thing at the `access` role, so a
+		// caller that predates roles keeps working.
+		const permissions = toPermissions(req.body?.permissions ?? req.body?.apps);
+
+		if (!permissions) {
+			res.status(400).send({status: 'BAD_REQUEST', message: 'Ungültige Berechtigungsliste.'});
+			return;
+		}
+
+		if (!(await UsersService.userExists(userId))) {
+			notFound(res);
+			return;
+		}
+
+		const target = await UsersService.loadAccess(userId);
+		const keepsAdmin = permissions.some(permission => permission.app === 'admin');
+		const losesAdmin = Boolean(target?.apps.includes('admin')) && !keepsAdmin;
+
+		// Self-lockout is checked here because it needs the caller's identity,
+		// which the service has no business knowing. The last-admin check is
+		// NOT done here: it has to be inside the write transaction to survive
+		// two admins acting at the same time (see setPermissionsGuarded).
+		if (losesAdmin && userId === res.locals.admin.id) {
+			conflict(res, 'Du kannst dir die Admin-Berechtigung nicht selbst entziehen.');
+			return;
+		}
+
+		const result = await UsersService.setPermissionsGuarded(userId, permissions, res.locals.admin.id);
+		if (result === 'last-admin') {
+			conflict(res, 'Die letzte Admin-Berechtigung kann nicht entzogen werden.');
+			return;
+		}
+
+		res.status(200).send(await UsersService.getUserDetail(userId));
+	} catch (e: any) {
+		sendServerError(res, e);
+	}
+});
+
+/**
+ * @swagger
+ * /admin/users/{userId}/disable:
+ *      post:
+ *          summary: Disable a user and revoke all of their sessions
+ *          tags: [admin]
+ *          responses:
+ *              200:
+ *                  description: Success
+ *              409:
+ *                  description: Would disable the caller or the last admin
+ */
+usersAdminRouter.post('/:userId/disable', async (req: Request, res: Response) => {
+	try {
+		const userId = req.params.userId;
+
+		if (userId === res.locals.admin.id) {
+			conflict(res, 'Du kannst dich nicht selbst deaktivieren.');
+			return;
+		}
+
+		const target = await UsersService.loadAccess(userId);
+		if (!target) {
+			notFound(res);
+			return;
+		}
+
+		const result = await UsersService.disableUserGuarded(userId);
+		if (result === 'last-admin') {
+			conflict(res, 'Der letzte aktive Admin kann nicht deaktiviert werden.');
+			return;
+		}
+
+		res.status(200).send(await UsersService.getUserDetail(userId));
+	} catch (e: any) {
+		sendServerError(res, e);
+	}
+});
+
+/**
+ * @swagger
+ * /admin/users/{userId}/enable:
+ *      post:
+ *          summary: Re-enable a disabled user
+ *          description: Does not restore sessions - the user signs in again.
+ *          tags: [admin]
+ *          responses:
+ *              200:
+ *                  description: Success
+ */
+usersAdminRouter.post('/:userId/enable', async (req: Request, res: Response) => {
+	try {
+		if (!(await UsersService.userExists(req.params.userId))) {
+			notFound(res);
+			return;
+		}
+
+		await UsersService.enableUser(req.params.userId);
+		res.status(200).send(await UsersService.getUserDetail(req.params.userId));
+	} catch (e: any) {
+		sendServerError(res, e);
+	}
+});
+
+/**
+ * @swagger
+ * /admin/users/{userId}/sessions/{sessionId}:
+ *      delete:
+ *          summary: Revoke one session of a user
+ *          tags: [admin]
+ *          responses:
+ *              204:
+ *                  description: Revoked
+ *              404:
+ *                  description: Unknown session for this user
+ */
+usersAdminRouter.delete('/:userId/sessions/:sessionId', async (req: Request, res: Response) => {
+	try {
+		const revoked = await UsersService.revokeSession(req.params.userId, req.params.sessionId);
+		if (!revoked) {
+			res.status(404).send({status: 'NOT_FOUND', message: 'Sitzung nicht gefunden.'});
+			return;
+		}
+		res.status(204).send();
+	} catch (e: any) {
+		sendServerError(res, e);
+	}
+});

src/models/admin/users/users.admin.service.ts

@@ -0,0 +1,466 @@
+import {Transaction} from 'kysely';
+import {NachklangAdminDB} from '../Admin.db.js';
+import {
+	AdminDatabase,
+	AppName,
+	AppPermission,
+	AppRole,
+	ACCESS_ROLE,
+	appsOf,
+	isAppName,
+	isAppRole
+} from '../admin.schema.js';
+
+const db = NachklangAdminDB.db;
+
+/**
+ * Everything that reads or writes permissions. Two callers with very different
+ * hot-path requirements share this file: admin.middleware.ts runs
+ * `loadAccess` on *every* admin-authenticated request (which is why it is one
+ * query joining `user.disabled` and the permission rows - see the plan's
+ * decision to run without better-auth's cookieCache), and the /admin/users
+ * routes run the rest.
+ */
+
+export interface UserAccess {
+	id: string;
+	email: string;
+	displayName: string;
+	disabled: boolean;
+	/** Every (app, role) grant this user holds. */
+	permissions: AppPermission[];
+	/** The distinct apps the above grants any access to. Derived, kept because
+	 *  most callers only ever ask "may they open this app at all?". */
+	apps: AppName[];
+}
+
+export type UserStatus = 'aktiv' | 'deaktiviert';
+
+export interface UserListEntry {
+	id: string;
+	email: string;
+	name: string;
+	permissions: AppPermission[];
+	apps: AppName[];
+	status: UserStatus;
+	createdAt: Date;
+	lastSignInAt: Date | null;
+}
+
+export interface UserSessionEntry {
+	id: string;
+	createdAt: Date;
+	expiresAt: Date;
+	ipAddress: string | null;
+	userAgent: string | null;
+}
+
+export interface UserDetail extends UserListEntry {
+	sessions: UserSessionEntry[];
+	passkeyCount: number;
+}
+
+/**
+ * The single per-request lookup behind requireAppAccess. Returns null when the
+ * user row is gone; `disabled` is returned rather than filtered so the
+ * middleware can answer 403 (account deactivated) instead of a misleading 401.
+ */
+export const loadAccess = async (userId: string): Promise<UserAccess | null> => {
+	const rows = await db
+		.selectFrom('user')
+		.leftJoin('user_app_permissions', 'user_app_permissions.user_id', 'user.id')
+		.where('user.id', '=', userId)
+		.select([
+			'user.id as id',
+			'user.email as email',
+			'user.name as name',
+			'user.disabled as disabled',
+			'user_app_permissions.app as app',
+			'user_app_permissions.role as role'
+		])
+		.execute();
+
+	if (rows.length === 0) {
+		return null;
+	}
+
+	const permissions = toPermissionRows(rows);
+
+	return {
+		id: rows[0].id,
+		email: rows[0].email,
+		displayName: rows[0].name,
+		// MySQL TINYINT(1) comes back as 0/1 through mysql2.
+		disabled: Boolean(rows[0].disabled),
+		permissions,
+		apps: appsOf(permissions)
+	};
+};
+
+/**
+ * Turns joined permission rows into AppPermission[]. The left join produces one
+ * row with a null app for a user who holds nothing, and a role written directly
+ * into the database that no longer appears in APP_ROLES is dropped rather than
+ * trusted - the table is the store, APP_ROLES is the contract.
+ */
+const toPermissionRows = (rows: {app: AppName | null; role: string | null}[]): AppPermission[] => {
+	return rows
+		.filter((row): row is {app: AppName; role: string} =>
+			isAppName(row.app) && isAppRole(row.app, row.role))
+		.map(row => ({app: row.app, role: row.role}));
+};
+
+export const listUsers = async (): Promise<UserListEntry[]> => {
+	const users = await db
+		.selectFrom('user')
+		.select(['id', 'email', 'name', 'disabled', 'createdAt'])
+		.orderBy('name', 'asc')
+		.execute();
+
+	const permissions = await db
+		.selectFrom('user_app_permissions')
+		.select(['user_id', 'app', 'role'])
+		.execute();
+
+	// Last sign-in is derived from the newest session rather than stored: a
+	// session row is created on every sign-in and we never update its
+	// createdAt, so max(createdAt) is exactly that, with no extra column to
+	// keep in sync.
+	//
+	// The expiry filter must match getUserDetail's. better-auth only deletes an
+	// expired session when someone actually presents it, so expired rows linger
+	// - without this, the list would report a last sign-in for someone the
+	// detail view shows as never having signed in.
+	const lastSessions = await db
+		.selectFrom('session')
+		.where('expiresAt', '>', new Date())
+		.select(({fn}) => ['userId', fn.max('createdAt').as('lastSignInAt')])
+		.groupBy('userId')
+		.execute();
+
+	const permissionsByUser = new Map<string, AppPermission[]>();
+	for (const row of permissions) {
+		if (!isAppRole(row.app, row.role)) {
+			continue;
+		}
+		const held = permissionsByUser.get(row.user_id) || [];
+		held.push({app: row.app, role: row.role});
+		permissionsByUser.set(row.user_id, held);
+	}
+
+	const lastSignInByUser = new Map<string, Date | null>(
+		lastSessions.map(row => [row.userId, row.lastSignInAt as Date | null])
+	);
+
+	return users.map(user => {
+		const held = permissionsByUser.get(user.id) || [];
+		return {
+			id: user.id,
+			email: user.email,
+			name: user.name,
+			permissions: held,
+			apps: appsOf(held),
+			status: user.disabled ? ('deaktiviert' as const) : ('aktiv' as const),
+			createdAt: user.createdAt,
+			lastSignInAt: lastSignInByUser.get(user.id) ?? null
+		};
+	});
+};
+
+export const getUserDetail = async (userId: string): Promise<UserDetail | null> => {
+	const user = await db
+		.selectFrom('user')
+		.select(['id', 'email', 'name', 'disabled', 'createdAt'])
+		.where('id', '=', userId)
+		.executeTakeFirst();
+
+	if (!user) {
+		return null;
+	}
+
+	const [permissions, sessions, passkeys] = await Promise.all([
+		db
+			.selectFrom('user_app_permissions')
+			.select(['app', 'role'])
+			.where('user_id', '=', userId)
+			.execute(),
+		db
+			.selectFrom('session')
+			.select(['id', 'createdAt', 'expiresAt', 'ipAddress', 'userAgent'])
+			.where('userId', '=', userId)
+			.where('expiresAt', '>', new Date())
+			.orderBy('createdAt', 'desc')
+			.execute(),
+		db
+			.selectFrom('passkey')
+			.select(({fn}) => fn.countAll<number>().as('count'))
+			.where('userId', '=', userId)
+			.executeTakeFirst()
+	]);
+
+	const held = toPermissionRows(permissions);
+
+	return {
+		id: user.id,
+		email: user.email,
+		name: user.name,
+		permissions: held,
+		apps: appsOf(held),
+		status: user.disabled ? 'deaktiviert' : 'aktiv',
+		createdAt: user.createdAt,
+		lastSignInAt: sessions.length > 0 ? sessions[0].createdAt : null,
+		sessions,
+		passkeyCount: Number(passkeys?.count ?? 0)
+	};
+};
+
+/**
+ * Replaces a user's permission set. Written as delete-then-insert inside one
+ * transaction rather than a diff: the set is at most four rows, and a diff
+ * would only add branches for no measurable gain.
+ */
+
+/** The rows a permission list becomes. One row per (app, role). */
+const permissionRows = (
+	userId: string,
+	permissions: AppPermission[],
+	grantedBy: string | null
+) => {
+	return permissions.map(permission => ({
+		user_id: userId,
+		app: permission.app,
+		role: permission.role,
+		granted_by: grantedBy,
+		granted_at: new Date()
+	}));
+};
+
+/** Drops anything not in APP_ROLES and de-duplicates on (app, role). */
+const validPermissions = (permissions: AppPermission[]): AppPermission[] => {
+	const seen = new Set<string>();
+	return permissions.filter(permission => {
+		if (!isAppName(permission.app) || !isAppRole(permission.app, permission.role)) {
+			return false;
+		}
+		const key = `${permission.app}:${permission.role}`;
+		if (seen.has(key)) {
+			return false;
+		}
+		seen.add(key);
+		return true;
+	});
+};
+
+export const setPermissions = async (
+	userId: string,
+	permissions: AppPermission[],
+	grantedBy: string | null
+): Promise<void> => {
+	const valid = validPermissions(permissions);
+
+	await db.transaction().execute(async trx => {
+		await trx.deleteFrom('user_app_permissions').where('user_id', '=', userId).execute();
+		if (valid.length > 0) {
+			await trx
+				.insertInto('user_app_permissions')
+				.values(permissionRows(userId, valid, grantedBy))
+				.execute();
+		}
+	});
+};
+
+/**
+ * Why the guards live down here rather than in the router: they are
+ * check-then-act, and the check has to happen inside the same transaction as
+ * the write, over locked rows. Two admins each removing the other's `admin`
+ * permission at the same moment would otherwise both read a count of 2, both
+ * pass, and both commit - leaving nobody who can administer anything, with
+ * ADMIN_BOOTSTRAP_EMAIL at the next restart as the only way back in.
+ *
+ * `SELECT ... FOR UPDATE` makes the second transaction wait and re-read the
+ * count the first one just changed.
+ */
+export type LastAdminGuardResult = 'ok' | 'last-admin';
+
+const countActiveAdminsForUpdate = async (trx: Transaction<AdminDatabase>): Promise<number> => {
+	const row = await trx
+		.selectFrom('user_app_permissions')
+		.innerJoin('user', 'user.id', 'user_app_permissions.user_id')
+		.where('user_app_permissions.app', '=', 'admin')
+		.where('user.disabled', '=', false)
+		// countDistinct, not countAll: with (user_id, app, role) as the key one
+		// user can hold several roles on `admin`, and counting rows would make a
+		// single admin with two roles look like two admins - defeating the guard
+		// at exactly the moment it matters.
+		.select(({fn}) => fn.count<number>('user_app_permissions.user_id').distinct().as('count'))
+		.forUpdate()
+		.executeTakeFirst();
+
+	return Number(row?.count ?? 0);
+};
+
+/**
+ * Replaces a user's permissions, refusing to remove the last active admin.
+ * Returns 'last-admin' instead of throwing so the router can answer 409.
+ */
+export const setPermissionsGuarded = async (
+	userId: string,
+	permissions: AppPermission[],
+	grantedBy: string | null
+): Promise<LastAdminGuardResult> => {
+	const valid = validPermissions(permissions);
+	const keepsAdmin = valid.some(permission => permission.app === 'admin');
+
+	return db.transaction().execute(async trx => {
+		const target = await trx
+			.selectFrom('user_app_permissions')
+			.innerJoin('user', 'user.id', 'user_app_permissions.user_id')
+			.where('user_app_permissions.user_id', '=', userId)
+			.where('user_app_permissions.app', '=', 'admin')
+			.select(['user.disabled as disabled'])
+			.limit(1)
+			.forUpdate()
+			.executeTakeFirst();
+
+		const losesAdmin = Boolean(target) && !keepsAdmin;
+		if (losesAdmin && !target?.disabled && (await countActiveAdminsForUpdate(trx)) <= 1) {
+			return 'last-admin';
+		}
+
+		await trx.deleteFrom('user_app_permissions').where('user_id', '=', userId).execute();
+		if (valid.length > 0) {
+			await trx
+				.insertInto('user_app_permissions')
+				.values(permissionRows(userId, valid, grantedBy))
+				.execute();
+		}
+
+		return 'ok';
+	});
+};
+
+/**
+ * Disables a user and revokes every session, refusing to disable the last
+ * active admin. Same locking rationale as setPermissionsGuarded.
+ */
+export const disableUserGuarded = async (userId: string): Promise<LastAdminGuardResult> => {
+	return db.transaction().execute(async trx => {
+		const isAdmin = await trx
+			.selectFrom('user_app_permissions')
+			.innerJoin('user', 'user.id', 'user_app_permissions.user_id')
+			.where('user_app_permissions.user_id', '=', userId)
+			.where('user_app_permissions.app', '=', 'admin')
+			.where('user.disabled', '=', false)
+			.select('user_app_permissions.user_id')
+			.limit(1)
+			.forUpdate()
+			.executeTakeFirst();
+
+		if (isAdmin && (await countActiveAdminsForUpdate(trx)) <= 1) {
+			return 'last-admin';
+		}
+
+		await trx.updateTable('user').set({disabled: true}).where('id', '=', userId).execute();
+		await trx.deleteFrom('session').where('userId', '=', userId).execute();
+
+		return 'ok';
+	});
+};
+
+export const grantPermission = async (
+	userId: string,
+	app: AppName,
+	grantedBy: string | null,
+	role: AppRole = ACCESS_ROLE
+): Promise<void> => {
+	await db
+		.insertInto('user_app_permissions')
+		.values({user_id: userId, app, role, granted_by: grantedBy, granted_at: new Date()})
+		// The row already existing is the success case - this is "make sure they
+		// hold it", not "re-grant it" - so nothing is overwritten and granted_by
+		// keeps naming whoever granted it first.
+		.onDuplicateKeyUpdate({role})
+		.execute();
+};
+
+/** Disabling revokes every session: a disabled user must lose access now, not
+ *  when their 30-day cookie happens to expire. */
+export const disableUser = async (userId: string): Promise<void> => {
+	await db.transaction().execute(async trx => {
+		await trx.updateTable('user').set({disabled: true}).where('id', '=', userId).execute();
+		await trx.deleteFrom('session').where('userId', '=', userId).execute();
+	});
+};
+
+export const enableUser = async (userId: string): Promise<void> => {
+	await db.updateTable('user').set({disabled: false}).where('id', '=', userId).execute();
+};
+
+export const revokeSession = async (userId: string, sessionId: string): Promise<boolean> => {
+	const result = await db
+		.deleteFrom('session')
+		.where('id', '=', sessionId)
+		.where('userId', '=', userId)
+		.executeTakeFirst();
+
+	return Number(result.numDeletedRows) > 0;
+};
+
+/**
+ * Guard input for the self-lockout rules: how many enabled users still hold the
+ * `admin` permission. Disabled admins do not count - they cannot sign in, so
+ * leaving only disabled admins is the same lockout as leaving none.
+ */
+export const countActiveAdmins = async (): Promise<number> => {
+	const row = await db
+		.selectFrom('user_app_permissions')
+		.innerJoin('user', 'user.id', 'user_app_permissions.user_id')
+		.where('user_app_permissions.app', '=', 'admin')
+		.where('user.disabled', '=', false)
+		.select(({fn}) => fn.countAll<number>().as('count'))
+		.executeTakeFirst();
+
+	return Number(row?.count ?? 0);
+};
+
+export const userExists = async (userId: string): Promise<boolean> => {
+	const row = await db.selectFrom('user').select('id').where('id', '=', userId).executeTakeFirst();
+	return Boolean(row);
+};
+
+export const findUserByEmail = async (email: string): Promise<{id: string; email: string} | null> => {
+	const row = await db
+		.selectFrom('user')
+		.select(['id', 'email'])
+		.where('email', '=', email)
+		.executeTakeFirst();
+
+	return row ?? null;
+};
+
+/**
+ * Display names for a set of user ids, as an id -> name map. Ids that no
+ * longer exist are simply absent from the map rather than mapping to a
+ * placeholder, so callers can distinguish "deleted account" from "never had
+ * one" and choose their own fallback.
+ *
+ * This exists for the calendar migration (docs/calendar-auth-migration.md
+ * step 3): the calendar lives in a different database, so it cannot join
+ * against `user` to render "created by". One lookup per result set keeps that
+ * cheap without coupling the two schemas.
+ */
+export const findDisplayNames = async (ids: readonly string[]): Promise<Map<string, string>> => {
+	const distinct = Array.from(new Set(ids.filter(id => id)));
+	if (distinct.length === 0) {
+		// Kysely renders `in ()` for an empty list, which MariaDB rejects.
+		return new Map();
+	}
+
+	const rows = await db
+		.selectFrom('user')
+		.select(['id', 'name'])
+		.where('id', 'in', distinct)
+		.execute();
+
+	return new Map(rows.map(row => [row.id, row.name]));
+};

src/models/calendar/events/credentials.service.ts

@@ -1,73 +1,55 @@
 import * as dotenv from 'dotenv';
-import * as UserService from '../users/users.service.js';
-
 
 dotenv.config();
 
 /**
- * Checks if the password gives admin privileges (view / create / edit / delete)
- * @param password
+ * The shared calendar passwords, and nothing else.
+ *
+ * Before the step 4 cutover each function here also took a sessionId/sessionKey
+ * pair and checked it against the calendar's own sessions table, so "is this a
+ * signed-in user?" and "did they send the right shared password?" were tangled
+ * together in five places. Signed-in access is now decided by
+ * requireAppAccess('calendar') before the handler runs; what is left is the
+ * fallback for people who have no account at all.
+ *
+ * That fallback survives on purpose, for one reason: an iCal client subscribing
+ * to a calendar URL cannot send a cookie. Everything the Angular app does goes
+ * through the session cookie instead. See docs/calendar-auth-migration.md.
+ *
+ * `public` is deliberately open to everyone with no credential of any kind -
+ * nachklang.art reads it anonymously to show the next upcoming event. Pinned by
+ * test/calendar/credentials.service.test.ts.
  */
-export const checkAdminPrivileges = async (sessionId: string, sessionKey: string, ip: string) => {
-	if(sessionId) {
-		let user = await UserService.checkSession(sessionId, sessionKey, ip);
-		return user?.isActive ?? false;
-	}
-	return false;
-}
 
-/**
- * Checks if the password gives member view privileges
- * @param password
- */
-export const checkMemberPrivileges = async (sessionId: string, sessionKey: string, password: string, ip: string) => {
-	if(sessionId) {
-		let user = await UserService.checkSession(sessionId, sessionKey, ip);
-		return user?.isActive ?? false;
-	}
-
-	return password == process.env.MEMBER_CREDENTIAL;
-}
-
-/**
- * Checks if the password gives choir view privileges
- * @param password
- */
-export const checkChoirPrivileges = async (sessionId: string, sessionKey: string, password: string, ip: string) => {
-	if(sessionId) {
-		let user = await UserService.checkSession(sessionId, sessionKey, ip);
-		return user?.isActive ?? false;
-	}
-
-	return password == process.env.CHOIR_CREDENTIAL;
-}
-
-/**
- * Checks if the password gives management view privileges
- * @param password
- */
-export const checkManagementPrivileges = async (sessionId: string, sessionKey: string, password: string, ip: string) => {
-	if(sessionId) {
-		let user = await UserService.checkSession(sessionId, sessionKey, ip);
-		return user?.isActive ?? false;
-	}
-
-	return password == process.env.MANAGEMENT_CREDENTIAL;
-}
-
-export const hasAccess = async (calendarName: string, sessionId: string, sessionKey: string, password: string, ip: string) => {
+const credentialFor = (calendarName: string): string | undefined => {
 	switch (calendarName) {
-		case 'public':
-			return true;
 		case 'members':
-			return await checkMemberPrivileges(sessionId, sessionKey, password, ip);
+			return process.env.MEMBER_CREDENTIAL;
 		case 'choir':
-			return await checkChoirPrivileges(sessionId, sessionKey, password, ip);
+		case 'birthdays':
+			return process.env.CHOIR_CREDENTIAL;
 		case 'management':
-			return await checkManagementPrivileges(sessionId, sessionKey, password, ip);
-        case 'birthdays':
-            return await checkChoirPrivileges(sessionId, sessionKey, password, ip);
+			return process.env.MANAGEMENT_CREDENTIAL;
 		default:
-			return false;
+			return undefined;
 	}
-}
+};
+
+/**
+ * Whether the given shared password opens the given calendar. Answers false
+ * for an unknown calendar, and - importantly - for a calendar whose credential
+ * is not configured at all: an unset MEMBER_CREDENTIAL must not turn into
+ * "everyone with an empty password gets in".
+ */
+export const hasAccess = async (calendarName: string, password: string): Promise<boolean> => {
+	if (calendarName === 'public') {
+		return true;
+	}
+
+	const expected = credentialFor(calendarName);
+	if (!expected) {
+		return false;
+	}
+
+	return password === expected;
+};

src/models/calendar/events/event.interface.ts

@@ -67,16 +67,35 @@
  *           example: "John Doe"
  *         createdById:
  *           type: integer
- *           description: The ID of the user who created the event
+ *           deprecated: true
+ *           description: >
+ *             The legacy calendar user id of the creator. Being replaced by
+ *             createdByUserId; see docs/calendar-auth-migration.md. Null on
+ *             events created after the cutover.
+ *           nullable: true
  *           example: 456
+ *         createdByUserId:
+ *           type: string
+ *           nullable: true
+ *           description: The admin-module user id of the creator, once it has one
+ *           example: "8f1c0f2e-0f1a-4b9e-9a7c-2d5f1b3c4d5e"
  *         lastModifiedBy:
  *           type: string
  *           description: The name of the user who last modified the event
  *           example: "John Doe"
  *         lastModifiedById:
  *           type: integer
- *           description: The ID of the user who last modified the event
+ *           deprecated: true
+ *           nullable: true
+ *           description: >
+ *             The legacy calendar user id of the last editor. Being replaced
+ *             by lastModifiedByUserId.
  *           example: 456
+ *         lastModifiedByUserId:
+ *           type: string
+ *           nullable: true
+ *           description: The admin-module user id of the last editor, once it has one
+ *           example: "8f1c0f2e-0f1a-4b9e-9a7c-2d5f1b3c4d5e"
  *         url:
  *           type: string
  *           description: A URL with more information about the event
@@ -102,10 +121,15 @@ export interface Event {
 	createdDate: Date;
 	lastModifiedDate?: Date;
 	location: string;
+	/** Display name of the creator, from whichever id below resolved. */
 	createdBy?: string;
-	createdById: number;
+	createdById?: number | null;
+	/** Set once the event's creator exists in the admin module. Preferred over
+	 *  createdById when both are present; see docs/calendar-auth-migration.md. */
+	createdByUserId?: string | null;
 	lastModifiedBy?: string;
-	lastModifiedById?: number;
+	lastModifiedById?: number | null;
+	lastModifiedByUserId?: string | null;
 	url: string;
 	wholeDay: boolean;
     repeatFrequency: string;

src/models/calendar/events/events.router.ts

@@ -7,7 +7,7 @@ import {Event} from './event.interface.js';
 import * as EventService from './events.service.js';
 import * as iCalService from './icalgenerator.service.js';
 import * as CredentialService from './credentials.service.js';
-import * as UserService from '../users/users.service.js';
+import {requireAppAccess, resolveAccess, AdminAccess} from '../../admin/admin.middleware.js';
 import {Guid} from 'guid-typescript';
 import logger from '../../../middleware/logger.js';
 
@@ -29,6 +29,44 @@ export const calendarNames = new Map<string, any>([
     ['birthdays', {id: 5, name: 'Nachklang_birthday_calendar'}]
 ]);
 
+/**
+ * The gate on everything that writes. Step 4 of
+ * docs/calendar-auth-migration.md replaced a sessionId/sessionKey pair in the
+ * query string (DEFERRED_SECURITY.md item 1) with the same session cookie the
+ * other three apps use, and "any activated @nachklang.art account" with an
+ * explicit per-user calendar permission.
+ */
+const requireCalendarAccess = requireAppAccess('calendar');
+
+/** Set by requireCalendarAccess; the writer's admin identity. */
+const adminOf = (res: Response): AdminAccess => res.locals.admin as AdminAccess;
+
+/**
+ * Resolves a signed-in calendar user for the *read* routes, or null.
+ *
+ * Reads cannot use the middleware: the same URL serves an anonymous visitor
+ * (the public calendar the website polls), someone holding a shared password
+ * (an iCal subscription), and a signed-in editor who should see drafts. So it
+ * answers "who is this, if anyone?" instead of refusing the request, and each
+ * handler decides what that means.
+ *
+ * A failure to reach the admin database is swallowed for the same reason the
+ * name lookup in events.service.ts swallows one: it must not be able to take
+ * the anonymous public calendar down.
+ */
+const signedInEditor = async (req: Request): Promise<AdminAccess | null> => {
+	try {
+		const access = await resolveAccess(req);
+		if (!access || access.disabled || !access.apps.includes('calendar')) {
+			return null;
+		}
+		return access;
+	} catch (e: any) {
+		logger.warn('Calendar: could not resolve the session, continuing as anonymous: ' + e.message);
+		return null;
+	}
+};
+
 
 /**
  * Controller Definitions
@@ -39,7 +77,10 @@ export const calendarNames = new Map<string, any>([
  * /calendar/events/{calendar}/json:
  *      get:
  *          summary: Get all events from a specific calendar in JSON format
- *          description: Returns all events from the specified calendar in JSON format. Authentication required.
+ *          description: >
+ *              Returns the calendar's events. The public calendar is open to everyone; the
+ *              others need either a signed-in account with the calendar permission - which
+ *              also unlocks drafts - or the calendar's shared password.
  *          tags:
  *              - calendar
  *          parameters:
@@ -48,23 +89,13 @@ export const calendarNames = new Map<string, any>([
  *                required: true
  *                schema:
  *                    type: string
- *                    enum: [public, members, choir, management]
+ *                    enum: [public, members, choir, management, birthdays]
  *                description: The name of the calendar to get events from
  *              - in: query
- *                name: sessionId
- *                schema:
- *                    type: string
- *                description: Session ID for authentication
- *              - in: query
- *                name: sessionKey
- *                schema:
- *                    type: string
- *                description: Session key for authentication
- *              - in: query
  *                name: password
  *                schema:
  *                    type: string
- *                description: Password for calendar access (if not using session authentication)
+ *                description: The calendar's shared password, for callers with no account
  *          responses:
  *              200:
  *                  description: Success
@@ -109,10 +140,7 @@ eventsRouter.get('/:calendar/json', async (req: Request, res: Response) => {
 	try {
 		// Get request params
 		let calendarName: string = req.params.calendar as string ?? '';
-		let sessionId: string = req.query.sessionId as string ?? '';
-		let sessionKey: string = req.query.sessionKey as string ?? '';
 		let password: string = req.query.password as string ?? '';
-		let ip: string = req.socket.remoteAddress ?? '';
 
 		if (calendarName.length < 1) {
 			res.status(400).send({'message': 'Please state the name of the calendar you want events from.'});
@@ -126,23 +154,19 @@ eventsRouter.get('/:calendar/json', async (req: Request, res: Response) => {
 
 		let calendarId: number = calendarNames.get(calendarName)!.id;
 
-		let user = await UserService.checkSession(sessionId, sessionKey, ip);
+		const editor = await signedInEditor(req);
 
-		// If no user was found, check if the password gives access to the calendar
-		if(user === null || !user.isActive) {
-			if (! await CredentialService.hasAccess(calendarName, sessionId, sessionKey, password, ip)) {
-				res.status(403).send({'message': 'You do not have access to the specified calendar.'});
-				return;
-			}
+		// Not signed in: fall back to the shared password for this calendar.
+		if (!editor && ! await CredentialService.hasAccess(calendarName, password)) {
+			res.status(403).send({'message': 'You do not have access to the specified calendar.'});
+			return;
 		}
 
-		let events: Event[];
-
-		if(user?.isActive) {
-			events = await EventService.getAllEventsAdmin(calendarId);
-		} else {
-			events = await EventService.getAllEvents(calendarId);
-		}
+		// Editors get the admin view (drafts included, calendar includes ignored);
+		// everyone else gets published events only.
+		let events: Event[] = editor
+			? await EventService.getAllEventsAdmin(calendarId)
+			: await EventService.getAllEvents(calendarId);
 
 		// Send the events back
 		res.status(200).send(events);
@@ -158,7 +182,10 @@ eventsRouter.get('/:calendar/json', async (req: Request, res: Response) => {
  * /calendar/events/{calendar}/json/next:
  *      get:
  *          summary: Get the next upcoming event from a calendar
- *          description: Returns the next upcoming event from the specified calendar. Authentication required.
+ *          description: >
+ *              The next upcoming event. The public calendar is open to everyone; the
+ *              others need either a signed-in account with the calendar permission or the
+ *              calendar's shared password.
  *          tags:
  *              - calendar
  *          parameters:
@@ -167,23 +194,13 @@ eventsRouter.get('/:calendar/json', async (req: Request, res: Response) => {
  *                required: true
  *                schema:
  *                    type: string
- *                    enum: [public, members, choir, management]
+ *                    enum: [public, members, choir, management, birthdays]
  *                description: The name of the calendar to get the next event from
  *              - in: query
- *                name: sessionId
- *                schema:
- *                    type: string
- *                description: Session ID for authentication
- *              - in: query
- *                name: sessionKey
- *                schema:
- *                    type: string
- *                description: Session key for authentication
- *              - in: query
  *                name: password
  *                schema:
  *                    type: string
- *                description: Password for calendar access (if not using session authentication)
+ *                description: The calendar's shared password, for callers with no account
  *          responses:
  *              200:
  *                  description: Success
@@ -242,10 +259,7 @@ eventsRouter.get('/:calendar/json/next', async (req: Request, res: Response) =>
 	try {
 		// Get request params
 		let calendarName: string = req.params.calendar as string ?? '';
-		let sessionId: string = req.query.sessionId as string ?? '';
-		let sessionKey: string = req.query.sessionKey as string ?? '';
 		let password: string = req.query.password as string ?? '';
-		let ip: string = req.socket.remoteAddress ?? '';
 
 		if (calendarName.length < 1) {
 			res.status(400).send({'message': 'Please state the name of the calendar you want events from.'});
@@ -259,7 +273,19 @@ eventsRouter.get('/:calendar/json/next', async (req: Request, res: Response) =>
 
 		let calendarId: number = calendarNames.get(calendarName)!.id;
 
-		if (! await CredentialService.hasAccess(calendarName, sessionId, sessionKey, password, ip)) {
+		// Holding the calendar's shared password, or signed in. The password path
+		// is what keeps iCal subscriptions working - a calendar client cannot
+		// send a cookie.
+		//
+		// The password is checked FIRST so that `public`, which needs no
+		// credential at all, short-circuits before signedInEditor runs. Otherwise
+		// every request from a browser that happens to hold a .nachklang.art
+		// cookie - which is any signed-in user on any of the four apps - would put
+		// an admin-database query in front of the anonymous public feed, with no
+		// timeout. Both operands are side-effect free, so the order is free to
+		// choose; this order is the one that keeps the public calendar
+		// independent of the admin database.
+		if (! await CredentialService.hasAccess(calendarName, password) && !await signedInEditor(req)) {
 			res.status(403).send({'message': 'You do not have access to the specified calendar.'});
 			return;
 		}
@@ -290,7 +316,10 @@ eventsRouter.get('/:calendar/json/next', async (req: Request, res: Response) =>
  * /calendar/events/{calendar}/ical:
  *      get:
  *          summary: Get all events from a specific calendar in iCal format
- *          description: Returns all events from the specified calendar in iCal format for calendar applications. Authentication required.
+ *          description: >
+ *              The calendar in iCal format. The public calendar is open to everyone; the
+ *              others take the calendar's shared password in the query string, which is
+ *              why that mechanism survives - an iCal client cannot send a cookie.
  *          tags:
  *              - calendar
  *          parameters:
@@ -299,23 +328,13 @@ eventsRouter.get('/:calendar/json/next', async (req: Request, res: Response) =>
  *                required: true
  *                schema:
  *                    type: string
- *                    enum: [public, members, choir, management]
+ *                    enum: [public, members, choir, management, birthdays]
  *                description: The name of the calendar to get events from
  *              - in: query
- *                name: sessionId
- *                schema:
- *                    type: string
- *                description: Session ID for authentication
- *              - in: query
- *                name: sessionKey
- *                schema:
- *                    type: string
- *                description: Session key for authentication
- *              - in: query
  *                name: password
  *                schema:
  *                    type: string
- *                description: Password for calendar access (if not using session authentication)
+ *                description: The calendar's shared password, for callers with no account
  *          responses:
  *              200:
  *                  description: Success - returns iCal file
@@ -365,10 +384,7 @@ eventsRouter.get('/:calendar/ical', async (req: Request, res: Response) => {
 	try {
 		// Get request params
 		let calendarName: string = req.params.calendar as string ?? '';
-		let sessionId: string = req.query.sessionId as string ?? '';
-		let sessionKey: string = req.query.sessionKey as string ?? '';
 		let password: string = req.query.password as string ?? '';
-		let ip: string = req.socket.remoteAddress ?? '';
 
 		if (calendarName.length < 1) {
 			res.status(400).send({'message': 'Please state the name of the calendar you want events from.'});
@@ -382,7 +398,19 @@ eventsRouter.get('/:calendar/ical', async (req: Request, res: Response) => {
 
 		let calendarId: number = calendarNames.get(calendarName)!.id;
 
-		if (! await CredentialService.hasAccess(calendarName, sessionId, sessionKey, password, ip)) {
+		// Holding the calendar's shared password, or signed in. The password path
+		// is what keeps iCal subscriptions working - a calendar client cannot
+		// send a cookie.
+		//
+		// The password is checked FIRST so that `public`, which needs no
+		// credential at all, short-circuits before signedInEditor runs. Otherwise
+		// every request from a browser that happens to hold a .nachklang.art
+		// cookie - which is any signed-in user on any of the four apps - would put
+		// an admin-database query in front of the anonymous public feed, with no
+		// timeout. Both operands are side-effect free, so the order is free to
+		// choose; this order is the one that keeps the public calendar
+		// independent of the admin database.
+		if (! await CredentialService.hasAccess(calendarName, password) && !await signedInEditor(req)) {
 			res.status(403).send({'message': 'You do not have access to the specified calendar.'});
 			return;
 		}
@@ -413,22 +441,11 @@ eventsRouter.get('/:calendar/ical', async (req: Request, res: Response) => {
  * /calendar/events:
  *      post:
  *          summary: Create a new event
- *          description: Creates a new event in the specified calendar. Authentication required.
+ *          description: Creates a new event. Requires a signed-in account with the calendar permission.
  *          tags:
  *              - calendar
- *          parameters:
- *              - in: query
- *                name: sessionId
- *                required: true
- *                schema:
- *                    type: string
- *                description: Session ID for authentication
- *              - in: query
- *                name: sessionKey
- *                required: true
- *                schema:
- *                    type: string
- *                description: Session key for authentication
+ *          security:
+ *              - AdminSessionCookie: []
  *          requestBody:
  *              required: true
  *              content:
@@ -495,16 +512,32 @@ eventsRouter.get('/:calendar/ical', async (req: Request, res: Response) => {
  *                                  message:
  *                                      type: string
  *                                      example: Required parameters missing
- *              403:
- *                  description: Forbidden - no access to create events
+ *              401:
+ *                  description: Unauthorized - not signed in
  *                  content:
  *                      application/json:
  *                          schema:
  *                              type: object
  *                              properties:
+ *                                  status:
+ *                                      type: string
+ *                                      example: UNAUTHORIZED
  *                                  message:
  *                                      type: string
- *                                      example: You do not have access to the specified calendar.
+ *                                      example: Anmeldung erforderlich.
+ *              403:
+ *                  description: Forbidden - the account lacks the calendar permission
+ *                  content:
+ *                      application/json:
+ *                          schema:
+ *                              type: object
+ *                              properties:
+ *                                  status:
+ *                                      type: string
+ *                                      example: FORBIDDEN
+ *                                  message:
+ *                                      type: string
+ *                                      example: "Für diesen Bereich fehlt dir die Berechtigung."
  *              500:
  *                  description: Server error
  *                  content:
@@ -522,19 +555,9 @@ eventsRouter.get('/:calendar/ical', async (req: Request, res: Response) => {
  *                                      type: string
  *                                      example: 6ec1361c-4175-4e81-b2ef-a0792a9a1dc3
  */
-eventsRouter.post('/', async (req: Request, res: Response) => {
+eventsRouter.post('/', requireCalendarAccess, async (req: Request, res: Response) => {
 	try {
-		// Get params
-		let sessionId: string = req.query.sessionId as string ?? '';
-		let sessionKey: string = req.query.sessionKey as string ?? '';
-		let ip: string = req.socket.remoteAddress ?? '';
-
-		let user = await UserService.checkSession(sessionId, sessionKey, ip);
-
-		if (!user?.isActive) {
-			res.status(403).send({'message': 'You do not have access to the specified calendar.'});
-			return;
-		}
+		const admin = adminOf(res);
 
 		if (
 			req.body.calendarId === undefined ||
@@ -556,7 +579,9 @@ eventsRouter.post('/', async (req: Request, res: Response) => {
 			endDateTime: new Date(req.body.endDateTime),
 			createdDate: new Date(),
 			location: req.body.location ?? '',
-			createdById: user.userId ?? -1,
+			// LEGACY createdById is deliberately not set: there is no calendar
+			// user id any more, and migration 003 made the column nullable.
+			createdByUserId: admin.id,
 			url: req.body.url ?? '',
 			wholeDay: req.body.wholeDay ?? false,
             repeatFrequency: req.body.repeatFrequency ?? '',
@@ -585,9 +610,11 @@ eventsRouter.post('/', async (req: Request, res: Response) => {
  * /calendar/events/{eventId}:
  *      put:
  *          summary: Update an existing event
- *          description: Updates an existing event with the provided data. Authentication required.
+ *          description: Updates an existing event. Requires a signed-in account with the calendar permission.
  *          tags:
  *              - calendar
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
  *              - in: path
  *                name: eventId
@@ -595,18 +622,6 @@ eventsRouter.post('/', async (req: Request, res: Response) => {
  *                schema:
  *                    type: integer
  *                description: The ID of the event to update
- *              - in: query
- *                name: sessionId
- *                required: true
- *                schema:
- *                    type: string
- *                description: Session ID for authentication
- *              - in: query
- *                name: sessionKey
- *                required: true
- *                schema:
- *                    type: string
- *                description: Session key for authentication
  *          requestBody:
  *              required: true
  *              content:
@@ -639,9 +654,6 @@ eventsRouter.post('/', async (req: Request, res: Response) => {
  *                              location:
  *                                  type: string
  *                                  example: "Musikhochschule, Karlsruhe"
- *                              createdBy:
- *                                  type: string
- *                                  example: "John Doe"
  *                              url:
  *                                  type: string
  *                                  example: "https://www.nachklang.art/events/concert"
@@ -673,16 +685,32 @@ eventsRouter.post('/', async (req: Request, res: Response) => {
  *                                  message:
  *                                      type: string
  *                                      example: Required parameters missing
- *              403:
- *                  description: Forbidden - no access to update events
+ *              401:
+ *                  description: Unauthorized - not signed in
  *                  content:
  *                      application/json:
  *                          schema:
  *                              type: object
  *                              properties:
+ *                                  status:
+ *                                      type: string
+ *                                      example: UNAUTHORIZED
  *                                  message:
  *                                      type: string
- *                                      example: You do not have access to the specified calendar.
+ *                                      example: Anmeldung erforderlich.
+ *              403:
+ *                  description: Forbidden - the account lacks the calendar permission
+ *                  content:
+ *                      application/json:
+ *                          schema:
+ *                              type: object
+ *                              properties:
+ *                                  status:
+ *                                      type: string
+ *                                      example: FORBIDDEN
+ *                                  message:
+ *                                      type: string
+ *                                      example: "Für diesen Bereich fehlt dir die Berechtigung."
  *              500:
  *                  description: Server error
  *                  content:
@@ -700,19 +728,9 @@ eventsRouter.post('/', async (req: Request, res: Response) => {
  *                                      type: string
  *                                      example: 6ec1361c-4175-4e81-b2ef-a0792a9a1dc3
  */
-eventsRouter.put('/:eventId', async (req: Request, res: Response) => {
+eventsRouter.put('/:eventId', requireCalendarAccess, async (req: Request, res: Response) => {
 	try {
-		// Get params
-		let sessionId: string = req.query.sessionId as string ?? '';
-		let sessionKey: string = req.query.sessionKey as string ?? '';
-		let ip: string = req.socket.remoteAddress ?? '';
-
-		let user = await UserService.checkSession(sessionId, sessionKey, ip);
-
-		if (!user?.isActive) {
-			res.status(403).send({'message': 'You do not have access to the specified calendar.'});
-			return;
-		}
+		const admin = adminOf(res);
 
 		if (
 			req.params.eventId === undefined ||
@@ -735,8 +753,9 @@ eventsRouter.put('/:eventId', async (req: Request, res: Response) => {
 			endDateTime: new Date(req.body.endDateTime),
 			createdDate: new Date(),
 			location: req.body.location ?? '',
-			createdBy: req.body.createdBy ?? '',
-			createdById: user.userId ?? -1,
+			// LEGACY createdById is deliberately not set: there is no calendar
+			// user id any more, and migration 003 made the column nullable.
+			createdByUserId: admin.id,
 			url: req.body.url ?? '',
 			wholeDay: req.body.wholeDay ?? false,
             repeatFrequency: req.body.repeatFrequency ?? '',
@@ -768,9 +787,11 @@ eventsRouter.put('/:eventId', async (req: Request, res: Response) => {
  * /calendar/events/move/{eventId}:
  *      put:
  *          summary: Move an event to a different calendar
- *          description: Moves an existing event to a different calendar. Authentication required.
+ *          description: Moves an event to a different calendar. Requires a signed-in account with the calendar permission.
  *          tags:
  *              - calendar
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
  *              - in: path
  *                name: eventId
@@ -778,18 +799,6 @@ eventsRouter.put('/:eventId', async (req: Request, res: Response) => {
  *                schema:
  *                    type: integer
  *                description: The ID of the event to move
- *              - in: query
- *                name: sessionId
- *                required: true
- *                schema:
- *                    type: string
- *                description: Session ID for authentication
- *              - in: query
- *                name: sessionKey
- *                required: true
- *                schema:
- *                    type: string
- *                description: Session key for authentication
  *          requestBody:
  *              required: true
  *              content:
@@ -820,9 +829,6 @@ eventsRouter.put('/:eventId', async (req: Request, res: Response) => {
  *                              location:
  *                                  type: string
  *                                  example: "Musikhochschule, Karlsruhe"
- *                              createdBy:
- *                                  type: string
- *                                  example: "John Doe"
  *                              url:
  *                                  type: string
  *                                  example: "https://www.nachklang.art/events/concert"
@@ -854,16 +860,32 @@ eventsRouter.put('/:eventId', async (req: Request, res: Response) => {
  *                                  message:
  *                                      type: string
  *                                      example: Required parameters missing
- *              403:
- *                  description: Forbidden - no access to move events
+ *              401:
+ *                  description: Unauthorized - not signed in
  *                  content:
  *                      application/json:
  *                          schema:
  *                              type: object
  *                              properties:
+ *                                  status:
+ *                                      type: string
+ *                                      example: UNAUTHORIZED
  *                                  message:
  *                                      type: string
- *                                      example: You do not have access to the specified calendar.
+ *                                      example: Anmeldung erforderlich.
+ *              403:
+ *                  description: Forbidden - the account lacks the calendar permission
+ *                  content:
+ *                      application/json:
+ *                          schema:
+ *                              type: object
+ *                              properties:
+ *                                  status:
+ *                                      type: string
+ *                                      example: FORBIDDEN
+ *                                  message:
+ *                                      type: string
+ *                                      example: "Für diesen Bereich fehlt dir die Berechtigung."
  *              500:
  *                  description: Server error
  *                  content:
@@ -881,19 +903,9 @@ eventsRouter.put('/:eventId', async (req: Request, res: Response) => {
  *                                      type: string
  *                                      example: 6ec1361c-4175-4e81-b2ef-a0792a9a1dc3
  */
-eventsRouter.put('/move/:eventId', async (req: Request, res: Response) => {
+eventsRouter.put('/move/:eventId', requireCalendarAccess, async (req: Request, res: Response) => {
 	try {
-		// Get params
-		let sessionId: string = req.query.sessionId as string ?? '';
-		let sessionKey: string = req.query.sessionKey as string ?? '';
-		let ip: string = req.socket.remoteAddress ?? '';
-
-		let user = await UserService.checkSession(sessionId, sessionKey, ip);
-
-		if (!user?.isActive) {
-			res.status(403).send({'message': 'You do not have access to the specified calendar.'});
-			return;
-		}
+		const admin = adminOf(res);
 
 		if (
 			req.params.eventId === undefined ||
@@ -913,8 +925,9 @@ eventsRouter.put('/move/:eventId', async (req: Request, res: Response) => {
 			endDateTime: new Date(req.body.endDateTime),
 			createdDate: new Date(),
 			location: req.body.location ?? '',
-			createdBy: req.body.createdBy ?? '',
-			createdById: user.userId ?? -1,
+			// LEGACY createdById is deliberately not set: there is no calendar
+			// user id any more, and migration 003 made the column nullable.
+			createdByUserId: admin.id,
 			url: req.body.url ?? '',
 			wholeDay: req.body.wholeDay ?? false,
             repeatFrequency: req.body.repeatFrequency ?? '',
@@ -944,9 +957,11 @@ eventsRouter.put('/move/:eventId', async (req: Request, res: Response) => {
  * /calendar/events/{eventId}:
  *      delete:
  *          summary: Delete an event
- *          description: Deletes an existing event. Authentication required.
+ *          description: Deletes an event. Requires a signed-in account with the calendar permission.
  *          tags:
  *              - calendar
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
  *              - in: path
  *                name: eventId
@@ -954,18 +969,6 @@ eventsRouter.put('/move/:eventId', async (req: Request, res: Response) => {
  *                schema:
  *                    type: integer
  *                description: The ID of the event to delete
- *              - in: query
- *                name: sessionId
- *                required: true
- *                schema:
- *                    type: string
- *                description: Session ID for authentication
- *              - in: query
- *                name: sessionKey
- *                required: true
- *                schema:
- *                    type: string
- *                description: Session key for authentication
  *          responses:
  *              200:
  *                  description: Event deleted successfully
@@ -987,16 +990,32 @@ eventsRouter.put('/move/:eventId', async (req: Request, res: Response) => {
  *                                  message:
  *                                      type: string
  *                                      example: Required parameters missing
- *              403:
- *                  description: Forbidden - no access to delete events
+ *              401:
+ *                  description: Unauthorized - not signed in
  *                  content:
  *                      application/json:
  *                          schema:
  *                              type: object
  *                              properties:
+ *                                  status:
+ *                                      type: string
+ *                                      example: UNAUTHORIZED
  *                                  message:
  *                                      type: string
- *                                      example: You do not have access to the specified calendar.
+ *                                      example: Anmeldung erforderlich.
+ *              403:
+ *                  description: Forbidden - the account lacks the calendar permission
+ *                  content:
+ *                      application/json:
+ *                          schema:
+ *                              type: object
+ *                              properties:
+ *                                  status:
+ *                                      type: string
+ *                                      example: FORBIDDEN
+ *                                  message:
+ *                                      type: string
+ *                                      example: "Für diesen Bereich fehlt dir die Berechtigung."
  *              500:
  *                  description: Server error
  *                  content:
@@ -1014,19 +1033,9 @@ eventsRouter.put('/move/:eventId', async (req: Request, res: Response) => {
  *                                      type: string
  *                                      example: 6ec1361c-4175-4e81-b2ef-a0792a9a1dc3
  */
-eventsRouter.delete('/:eventId', async (req: Request, res: Response) => {
+eventsRouter.delete('/:eventId', requireCalendarAccess, async (req: Request, res: Response) => {
 	try {
-		// Get params
-		let sessionId: string = req.query.sessionId as string ?? '';
-		let sessionKey: string = req.query.sessionKey as string ?? '';
-		let ip: string = req.socket.remoteAddress ?? '';
-
-		let user = await UserService.checkSession(sessionId, sessionKey, ip);
-
-		if (!user?.isActive) {
-			res.status(403).send({'message': 'You do not have access to the specified calendar.'});
-			return;
-		}
+		const admin = adminOf(res);
 
 		if (
 			req.params.eventId === undefined
@@ -1046,7 +1055,9 @@ eventsRouter.delete('/:eventId', async (req: Request, res: Response) => {
 			createdDate: new Date(),
 			location: '',
 			createdBy: '',
-			createdById: user.userId ?? -1,
+			// LEGACY createdById is deliberately not set: there is no calendar
+			// user id any more, and migration 003 made the column nullable.
+			createdByUserId: admin.id,
 			url: '',
 			wholeDay: false,
             repeatFrequency: '',

src/models/calendar/events/events.service.ts

@@ -2,28 +2,56 @@ import * as dotenv from 'dotenv';
 import {Guid} from 'guid-typescript';
 import {Event} from './event.interface.js';
 import {NachklangCalendarDB} from '../Calendar.db.js';
+import * as AdminUsersService from '../../admin/users/users.admin.service.js';
+import logger from '../../../middleware/logger.js';
 
 
 dotenv.config();
 
 /**
- * Returns all events for the given calendar
- * @param calendarId The calendar Id
+ * Step 3 of docs/calendar-auth-migration.md: the dual read.
+ *
+ * An event records its creator twice - `created_by_id`, the legacy INT into
+ * the calendar database's own `users` table, and `created_by_user_id`, the
+ * admin module's VARCHAR(36) id. Old rows have only the first, rows written
+ * after the step 4 cutover will have only the second, and the two live in
+ * different databases, so this file has to read both and prefer the new one.
+ *
+ * The one thing the creator is used for is a display name. Nothing authorises
+ * on it - there is no "only the creator may edit" rule anywhere - which is why
+ * a name that cannot be resolved degrades to blank instead of to an error.
+ *
+ * That name has three possible sources, and they are tried weakest first:
+ *
+ *   1. LEGACY - joining the calendar's own `users` table on `created_by_id`.
+ *   2. `created_by_name`, the snapshot migration 002 took of exactly that join,
+ *      so the authorship of pre-cutover events survives step 5 dropping the
+ *      table. An archive: nothing writes it after the backfill.
+ *   3. The admin module's `user.name`, looked up live for rows that carry an
+ *      admin id. It wins because it is the only one that follows a rename.
+ *
+ * Writes only ever set the admin id: since the step 4 cutover there is no
+ * calendar user id to write, which is why migration 003 made `created_by_id`
+ * nullable. The reads below still handle rows that predate that.
+ *
+ * Removal note: everything marked LEGACY below comes out in step 5, together
+ * with the `users`/`sessions` tables and the `created_by_id` columns. The
+ * snapshot stays - it is the reason step 5 can drop them.
  */
-export const getAllEvents = async (calendarId: number): Promise<Event[]> => {
-	let conn = await NachklangCalendarDB.getConnection();
-	let eventRows: Event[] = [];
-	try {
-		const calendarQuery = 'SELECT calendar_id, includes_calendars FROM calendars WHERE calendar_id = ?';
-		const calendarRes = await conn.query(calendarQuery, calendarId);
-		let calendarsToFetch: number[] = [calendarId];
-		for(let row of calendarRes) {
-			let includes: number[] = JSON.parse(row.includes_calendars);
-			calendarsToFetch = [...calendarsToFetch, ...includes];
-		}
 
-		const eventsQuery = `
-		SELECT e.calendar_id, e.uuid, e.created_date, e.created_by_id, u.full_name as created_by_name, u2.full_name as last_modified_by_name, v.* FROM events e
+/**
+ * The one SELECT the four read paths share. It was copied out four times
+ * before, which is precisely why the dual read had to be added in four
+ * places; callers append their own WHERE and ORDER BY.
+ *
+ * `v.*` carries `version_created_by_user_id` and `version_created_by_name`
+ * along with the rest of the version row, so only the `events` columns need
+ * naming. The two joined names are aliased `legacy_*` because the unprefixed
+ * names are now real columns.
+ */
+const EVENT_SELECT = `
+		SELECT e.calendar_id, e.uuid, e.created_date, e.created_by_id, e.created_by_user_id, e.created_by_name,
+			u.full_name as legacy_created_by_name, u2.full_name as legacy_last_modified_by_name, v.* FROM events e
 			INNER JOIN (
   				SELECT event_id, MAX(event_version_id) AS latest_version
 			  	FROM event_versions
@@ -33,34 +61,124 @@ export const getAllEvents = async (calendarId: number): Promise<Event[]> => {
 			INNER JOIN event_versions v
 			ON v.event_id = latest_versions.event_id AND v.event_version_id = latest_versions.latest_version
 			LEFT OUTER JOIN users u ON u.user_id = e.created_by_id
-		    LEFT OUTER JOIN users u2 ON u2.user_id = v.version_created_by_id
-			WHERE e.calendar_id IN (?) AND v.status = 'PUBLIC'
-			ORDER BY e.event_id`;
-		const eventsRes = await conn.query(eventsQuery, [calendarsToFetch]);
+			LEFT OUTER JOIN users u2 ON u2.user_id = v.version_created_by_id`;
 
-		for (let row of eventsRes) {
-			eventRows.push({
-				eventId: row.event_id,
-				calendarId: row.calendar_id,
-				uuid: row.uuid,
-				name: row.name,
-				description: row.description,
-				startDateTime: row.start_datetime,
-				endDateTime: row.end_datetime,
-				createdDate: row.created_date,
-				lastModifiedDate: row.version_created_at,
-				location: row.location,
-				createdBy: row.created_by_name,
-				createdById: row.created_by_id,
-				lastModifiedBy: row.last_modified_by_name,
-				lastModifiedById: row.version_created_by_id,
-				url: row.url,
-				wholeDay: row.whole_day,
-                repeatFrequency: row.repeat_frequency
-			});
+/**
+ * Maps a result row to an Event. `status` is included only where it always
+ * was: the admin views and the by-id lookup return it, the two public listings
+ * do not.
+ */
+const toEvent = (row: any, includeStatus: boolean): Event => {
+	const event: Event = {
+		eventId: row.event_id,
+		calendarId: row.calendar_id,
+		uuid: row.uuid,
+		name: row.name,
+		description: row.description,
+		startDateTime: row.start_datetime,
+		endDateTime: row.end_datetime,
+		createdDate: row.created_date,
+		lastModifiedDate: row.version_created_at,
+		location: row.location,
+		// Name resolution, weakest first: the LEGACY join against the calendar
+		// users table, then the snapshot taken in migration 002, then - in
+		// resolveAdminNames below - the live admin name, which wins because it
+		// is the only one that follows an account being renamed.
+		createdBy: row.created_by_name ?? row.legacy_created_by_name,
+		createdById: row.created_by_id,
+		createdByUserId: row.created_by_user_id ?? null,
+		lastModifiedBy: row.version_created_by_name ?? row.legacy_last_modified_by_name,
+		lastModifiedById: row.version_created_by_id,
+		lastModifiedByUserId: row.version_created_by_user_id ?? null,
+		url: row.url,
+		wholeDay: row.whole_day,
+		repeatFrequency: row.repeat_frequency
+	};
+
+	if (includeStatus) {
+		event.status = row.status;
+	}
+
+	return event;
+};
+
+/**
+ * Fills in creator/editor names for rows that carry an admin user id, by way
+ * of a single lookup against the admin database. The calendar cannot join
+ * against `user` - it is a different schema behind a different pool - and
+ * making it one would tie the two schemas together as tightly as a foreign key
+ * would.
+ *
+ * A failure here is swallowed on purpose. These endpoints include the public
+ * calendar the website reads anonymously, and a name is decoration: if the
+ * admin database is unreachable, an event should still render with whatever
+ * the legacy join produced rather than 500 the whole listing. The alternative
+ * would widen the public calendar's blast radius to include the admin
+ * database, which it has never depended on before.
+ */
+const resolveAdminNames = async (events: Event[]): Promise<void> => {
+	const ids = events
+		.flatMap(event => [event.createdByUserId, event.lastModifiedByUserId])
+		.filter((id): id is string => Boolean(id));
+
+	if (ids.length === 0) {
+		return;
+	}
+
+	let names: Map<string, string>;
+	try {
+		names = await AdminUsersService.findDisplayNames(ids);
+	} catch (e: any) {
+		logger.warn('Calendar: could not resolve creator names from the admin database: ' + e.message);
+		return;
+	}
+
+	for (const event of events) {
+		const createdBy = event.createdByUserId ? names.get(event.createdByUserId) : undefined;
+		if (createdBy) {
+			event.createdBy = createdBy;
 		}
 
-		return eventRows;
+		const lastModifiedBy = event.lastModifiedByUserId ? names.get(event.lastModifiedByUserId) : undefined;
+		if (lastModifiedBy) {
+			event.lastModifiedBy = lastModifiedBy;
+		}
+	}
+};
+
+/**
+ * The calendars a listing has to cover: the requested one plus whatever it
+ * declares in `includes_calendars`.
+ */
+const calendarsToFetch = async (conn: any, calendarId: number): Promise<number[]> => {
+	const calendarQuery = 'SELECT calendar_id, includes_calendars FROM calendars WHERE calendar_id = ?';
+	const calendarRes = await conn.query(calendarQuery, calendarId);
+	let calendars: number[] = [calendarId];
+	for (let row of calendarRes) {
+		let includes: number[] = JSON.parse(row.includes_calendars);
+		calendars = [...calendars, ...includes];
+	}
+	return calendars;
+};
+
+/**
+ * Returns all events for the given calendar
+ * @param calendarId The calendar Id
+ */
+export const getAllEvents = async (calendarId: number): Promise<Event[]> => {
+	let conn = await NachklangCalendarDB.getConnection();
+	try {
+		const calendars = await calendarsToFetch(conn, calendarId);
+
+		const eventsQuery = `${EVENT_SELECT}
+			WHERE e.calendar_id IN (?) AND v.status = 'PUBLIC'
+			ORDER BY e.event_id`;
+		const eventsRes = await conn.query(eventsQuery, [calendars]);
+
+		const events = eventsRes.map((row: any) => toEvent(row, false));
+		await resolveAdminNames(events);
+
+		return events;
 	} catch (err) {
 		throw err;
 	} finally {
@@ -76,48 +194,16 @@ export const getAllEvents = async (calendarId: number): Promise<Event[]> => {
  */
 export const getAllEventsAdmin = async (calendarId: number): Promise<Event[]> => {
 	let conn = await NachklangCalendarDB.getConnection();
-	let eventRows: Event[] = [];
 	try {
-		const eventsQuery = `
-        SELECT e.calendar_id, e.uuid, e.created_date, e.created_by_id, u.full_name as created_by_name, u2.full_name as last_modified_by_name, v.* FROM events e
-			INNER JOIN (
-  				SELECT event_id, MAX(event_version_id) AS latest_version
-			  	FROM event_versions
-			  	GROUP BY event_id
-			) latest_versions
-			ON e.event_id = latest_versions.event_id
-			INNER JOIN event_versions v
-			ON v.event_id = latest_versions.event_id AND v.event_version_id = latest_versions.latest_version
-			LEFT OUTER JOIN users u ON u.user_id = e.created_by_id
-			LEFT OUTER JOIN users u2 ON u2.user_id = v.version_created_by_id
+		const eventsQuery = `${EVENT_SELECT}
 			WHERE e.calendar_id = ?
 			ORDER BY e.event_id`;
 		const eventsRes = await conn.query(eventsQuery, calendarId);
 
-		for (let row of eventsRes) {
-			eventRows.push({
-				eventId: row.event_id,
-				calendarId: row.calendar_id,
-				uuid: row.uuid,
-				name: row.name,
-				description: row.description,
-				startDateTime: row.start_datetime,
-				endDateTime: row.end_datetime,
-				createdDate: row.created_date,
-				lastModifiedDate: row.version_created_at,
-				location: row.location,
-				createdBy: row.created_by_name,
-				createdById: row.created_by_id,
-				lastModifiedBy: row.last_modified_by_name,
-				lastModifiedById: row.version_created_by_id,
-				url: row.url,
-				wholeDay: row.whole_day,
-                repeatFrequency: row.repeat_frequency,
-				status: row.status
-			});
-		}
+		const events = eventsRes.map((row: any) => toEvent(row, true));
+		await resolveAdminNames(events);
 
-		return eventRows;
+		return events;
 	} catch (err) {
 		throw err;
 	} finally {
@@ -136,18 +222,7 @@ export const getAllEventsAdmin = async (calendarId: number): Promise<Event[]> =>
 export const getEventById = async (eventId: number): Promise<Event | null> => {
 	let conn = await NachklangCalendarDB.getConnection();
 	try {
-		const eventsQuery = `
-		SELECT e.calendar_id, e.uuid, e.created_date, e.created_by_id, u.full_name as created_by_name, u2.full_name as last_modified_by_name, v.* FROM events e
-			INNER JOIN (
-  				SELECT event_id, MAX(event_version_id) AS latest_version
-			  	FROM event_versions
-			  	GROUP BY event_id
-			) latest_versions
-			ON e.event_id = latest_versions.event_id
-			INNER JOIN event_versions v
-			ON v.event_id = latest_versions.event_id AND v.event_version_id = latest_versions.latest_version
-			LEFT OUTER JOIN users u ON u.user_id = e.created_by_id
-		    LEFT OUTER JOIN users u2 ON u2.user_id = v.version_created_by_id
+		const eventsQuery = `${EVENT_SELECT}
 			WHERE e.event_id = ?`;
 		const eventsRes = await conn.query(eventsQuery, eventId);
 
@@ -155,27 +230,10 @@ export const getEventById = async (eventId: number): Promise<Event | null> => {
 			return null;
 		}
 
-		const row = eventsRes[0];
-		return {
-			eventId: row.event_id,
-			calendarId: row.calendar_id,
-			uuid: row.uuid,
-			name: row.name,
-			description: row.description,
-			startDateTime: row.start_datetime,
-			endDateTime: row.end_datetime,
-			createdDate: row.created_date,
-			lastModifiedDate: row.version_created_at,
-			location: row.location,
-			createdBy: row.created_by_name,
-			createdById: row.created_by_id,
-			lastModifiedBy: row.last_modified_by_name,
-			lastModifiedById: row.version_created_by_id,
-			url: row.url,
-			wholeDay: row.whole_day,
-            repeatFrequency: row.repeat_frequency,
-			status: row.status
-		} as Event;
+		const event = toEvent(eventsRes[0], true);
+		await resolveAdminNames([event]);
+
+		return event;
 	} catch (err) {
 		throw err;
 	} finally {
@@ -193,11 +251,11 @@ export const createEvent = async (event: Event): Promise<number> => {
 	try {
 		await conn.beginTransaction();
 		let eventUUID = Guid.create().toString();
-		const eventsQuery = 'INSERT INTO events (calendar_id, uuid, created_by_id) VALUES (?,?,?) RETURNING event_id';
-		const eventsRes = await conn.execute(eventsQuery, [event.calendarId, eventUUID, event.createdById]);
+		const eventsQuery = 'INSERT INTO events (calendar_id, uuid, created_by_user_id) VALUES (?,?,?) RETURNING event_id';
+		const eventsRes = await conn.execute(eventsQuery, [event.calendarId, eventUUID, event.createdByUserId ?? null]);
 
-		const versionQuery = 'INSERT INTO event_versions (event_id, name, description, start_datetime, end_datetime, whole_day, repeat_frequency, location, url, status, version_created_by_id) VALUES (?,?,?,?,?,?,?,?,?,?,?);'
-		await conn.execute(versionQuery, [eventsRes[0].event_id, event.name, event.description, event.startDateTime, event.endDateTime, event.wholeDay, event.repeatFrequency, event.location, event.url, event.status, event.createdById]);
+		const versionQuery = 'INSERT INTO event_versions (event_id, name, description, start_datetime, end_datetime, whole_day, repeat_frequency, location, url, status, version_created_by_user_id) VALUES (?,?,?,?,?,?,?,?,?,?,?);'
+		await conn.execute(versionQuery, [eventsRes[0].event_id, event.name, event.description, event.startDateTime, event.endDateTime, event.wholeDay, event.repeatFrequency, event.location, event.url, event.status, event.createdByUserId ?? null]);
 
 		await conn.commit();
 
@@ -218,8 +276,8 @@ export const updateEvent = async (event: Event): Promise<number> => {
 	let conn = await NachklangCalendarDB.getConnection();
 	try {
 		await conn.beginTransaction();
-		const versionQuery = 'INSERT INTO event_versions (event_id, name, description, start_datetime, end_datetime, whole_day, repeat_frequency, location, url, status, version_created_by_id) VALUES (?,?,?,?,?,?,?,?,?,?,?);'
-		const versionRes = await conn.execute(versionQuery, [event.eventId, event.name, event.description, event.startDateTime, event.endDateTime, event.wholeDay, event.repeatFrequency, event.location, event.url, event.status, event.createdById]);
+		const versionQuery = 'INSERT INTO event_versions (event_id, name, description, start_datetime, end_datetime, whole_day, repeat_frequency, location, url, status, version_created_by_user_id) VALUES (?,?,?,?,?,?,?,?,?,?,?);'
+		const versionRes = await conn.execute(versionQuery, [event.eventId, event.name, event.description, event.startDateTime, event.endDateTime, event.wholeDay, event.repeatFrequency, event.location, event.url, event.status, event.createdByUserId ?? null]);
 
 		await conn.commit();
 
@@ -240,8 +298,8 @@ export const deleteEvent = async (event: Event): Promise<boolean> => {
 	let conn = await NachklangCalendarDB.getConnection();
 	try {
 		await conn.beginTransaction();
-		const versionQuery = 'INSERT INTO event_versions (event_id, status, version_created_by_id) VALUES (?,?,?);'
-		const versionRes = await conn.execute(versionQuery, [event.eventId, 'DELETED', event.createdById]);
+		const versionQuery = 'INSERT INTO event_versions (event_id, status, version_created_by_user_id) VALUES (?,?,?);'
+		const versionRes = await conn.execute(versionQuery, [event.eventId, 'DELETED', event.createdByUserId ?? null]);
 
 		await conn.commit();
 
@@ -283,56 +341,23 @@ export const moveEvent = async (event: Event): Promise<boolean> => {
 export const getNextUpcomingEvent = async (calendarId: number): Promise<Event | null> => {
 	let conn = await NachklangCalendarDB.getConnection();
 	try {
-		const calendarQuery = 'SELECT calendar_id, includes_calendars FROM calendars WHERE calendar_id = ?';
-		const calendarRes = await conn.query(calendarQuery, calendarId);
-		let calendarsToFetch: number[] = [calendarId];
-		for(let row of calendarRes) {
-			let includes: number[] = JSON.parse(row.includes_calendars);
-			calendarsToFetch = [...calendarsToFetch, ...includes];
-		}
+		const calendars = await calendarsToFetch(conn, calendarId);
 
 		const now = new Date();
-		const eventsQuery = `
-		SELECT e.calendar_id, e.uuid, e.created_date, e.created_by_id, u.full_name as created_by_name, u2.full_name as last_modified_by_name, v.* FROM events e
-			INNER JOIN (
-  				SELECT event_id, MAX(event_version_id) AS latest_version
-			  	FROM event_versions
-			  	GROUP BY event_id
-			) latest_versions
-			ON e.event_id = latest_versions.event_id
-			INNER JOIN event_versions v
-			ON v.event_id = latest_versions.event_id AND v.event_version_id = latest_versions.latest_version
-			LEFT OUTER JOIN users u ON u.user_id = e.created_by_id
-			LEFT OUTER JOIN users u2 ON u2.user_id = v.version_created_by_id
+		const eventsQuery = `${EVENT_SELECT}
 			WHERE e.calendar_id IN (?) AND v.status = 'PUBLIC' AND v.start_datetime > ?
 			ORDER BY v.start_datetime ASC
 			LIMIT 1`;
-		const eventsRes = await conn.query(eventsQuery, [calendarsToFetch, now]);
+		const eventsRes = await conn.query(eventsQuery, [calendars, now]);
 
 		if (eventsRes.length === 0) {
 			return null;
 		}
 
-		const row = eventsRes[0];
-		return {
-			eventId: row.event_id,
-			calendarId: row.calendar_id,
-			uuid: row.uuid,
-			name: row.name,
-			description: row.description,
-			startDateTime: row.start_datetime,
-			endDateTime: row.end_datetime,
-			createdDate: row.created_date,
-			lastModifiedDate: row.version_created_at,
-			location: row.location,
-			createdBy: row.created_by_name,
-			createdById: row.created_by_id,
-			lastModifiedBy: row.last_modified_by_name,
-			lastModifiedById: row.version_created_by_id,
-			url: row.url,
-			wholeDay: row.whole_day,
-            repeatFrequency: row.repeat_frequency
-		} as Event;
+		const event = toEvent(eventsRes[0], false);
+		await resolveAdminNames([event]);
+
+		return event;
 	} catch (err) {
 		throw err;
 	} finally {

src/models/feedback/admin/admin.interface.ts

@@ -1,19 +1,6 @@
 /**
  * @swagger
  * components:
- *   parameters:
- *     SessionIdHeader:
- *       in: header
- *       name: X-Session-Id
- *       required: true
- *       schema:
- *         type: string
- *     SessionKeyHeader:
- *       in: header
- *       name: X-Session-Key
- *       required: true
- *       schema:
- *         type: string
  *   schemas:
  *     EventAdminSummary:
  *       type: object

src/models/feedback/admin/admin.router.ts

@@ -26,9 +26,8 @@ adminRouter.use(requireAdminAuth);
  *          summary: Validate the current admin session
  *          description: Used by the Next.js middleware/proxy to gate /admin. Returns the authenticated admin's identity.
  *          tags: [feedback-admin]
- *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
+ *          security:
+ *              - AdminSessionCookie: []
  *          responses:
  *              200:
  *                  description: Success
@@ -43,6 +42,8 @@ adminRouter.use(requireAdminAuth);
  *                                      type: string
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  */
 adminRouter.get('/me', (req: Request, res: Response) => {
 	res.status(200).send({email: res.locals.admin.email, fullName: res.locals.admin.displayName});
@@ -55,9 +56,9 @@ adminRouter.get('/me', (req: Request, res: Response) => {
  *          summary: Delete a single submission
  *          description: Removes the submission and everything under it (its answers, guest book entry, newsletter signup) - for removing an individual abusive or inappropriate entry. Not a bulk moderation tool.
  *          tags: [feedback-admin]
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
  *              - in: path
  *                name: submissionId
  *                required: true
@@ -70,6 +71,8 @@ adminRouter.get('/me', (req: Request, res: Response) => {
  *                  description: Unknown submission
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  */
 adminRouter.delete('/submissions/:submissionId', async (req: Request, res: Response) => {
 	try {

src/models/feedback/admin/events.admin.router.ts

@@ -18,9 +18,8 @@ export const eventsAdminRouter = express.Router();
  *          summary: List all events (admin)
  *          description: All events, published or not, past or future, with submission counts.
  *          tags: [feedback-admin]
- *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
+ *          security:
+ *              - AdminSessionCookie: []
  *          responses:
  *              200:
  *                  description: Success
@@ -32,13 +31,14 @@ export const eventsAdminRouter = express.Router();
  *                                  $ref: '#/components/schemas/EventAdminSummary'
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  *      post:
  *          summary: Create an event
  *          description: Auto-generates the slug from the name and event year; defaults feedback_deadline to event_date + 14 days 23:59:59 unless supplied.
  *          tags: [feedback-admin]
- *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
+ *          security:
+ *              - AdminSessionCookie: []
  *          requestBody:
  *              required: true
  *              content:
@@ -68,6 +68,8 @@ export const eventsAdminRouter = express.Router();
  *                  description: Missing required fields
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  */
 eventsAdminRouter.get('/', async (req: Request, res: Response) => {
 	try {
@@ -101,9 +103,9 @@ eventsAdminRouter.post('/', async (req: Request, res: Response) => {
  *          summary: Get one event (admin)
  *          description: Full event detail including setlist and assigned questions.
  *          tags: [feedback-admin]
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
  *              - in: path
  *                name: eventId
  *                required: true
@@ -120,12 +122,14 @@ eventsAdminRouter.post('/', async (req: Request, res: Response) => {
  *                  description: Unknown event
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  *      put:
  *          summary: Update an event
  *          tags: [feedback-admin]
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
  *              - in: path
  *                name: eventId
  *                required: true
@@ -138,13 +142,15 @@ eventsAdminRouter.post('/', async (req: Request, res: Response) => {
  *                  description: Unknown event
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  *      delete:
  *          summary: Delete an event
  *          description: Refuses with 409 if submissions exist unless ?force=true is passed.
  *          tags: [feedback-admin]
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
  *              - in: path
  *                name: eventId
  *                required: true
@@ -163,6 +169,8 @@ eventsAdminRouter.post('/', async (req: Request, res: Response) => {
  *                  description: Submissions exist and force was not set
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  */
 eventsAdminRouter.get('/:eventId', async (req: Request, res: Response) => {
 	try {
@@ -214,9 +222,9 @@ eventsAdminRouter.delete('/:eventId', async (req: Request, res: Response) => {
  *      get:
  *          summary: Get an event's setlist
  *          tags: [feedback-admin]
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
  *              - in: path
  *                name: eventId
  *                required: true
@@ -227,12 +235,14 @@ eventsAdminRouter.delete('/:eventId', async (req: Request, res: Response) => {
  *                  description: Success
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  *      post:
  *          summary: Add a song to an event's setlist
  *          tags: [feedback-admin]
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
  *              - in: path
  *                name: eventId
  *                required: true
@@ -257,6 +267,8 @@ eventsAdminRouter.delete('/:eventId', async (req: Request, res: Response) => {
  *                  description: Missing title
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  */
 eventsAdminRouter.get('/:eventId/songs', async (req: Request, res: Response) => {
 	try {
@@ -292,9 +304,9 @@ eventsAdminRouter.post('/:eventId/songs', async (req: Request, res: Response) =>
  *          summary: Bulk reorder an event's setlist
  *          description: Rewrites song positions as a dense 0..n-1 sequence in one transaction.
  *          tags: [feedback-admin]
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
  *              - in: path
  *                name: eventId
  *                required: true
@@ -317,6 +329,8 @@ eventsAdminRouter.post('/:eventId/songs', async (req: Request, res: Response) =>
  *                  description: Reordered
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  */
 eventsAdminRouter.put('/:eventId/songs/order', async (req: Request, res: Response) => {
 	try {
@@ -334,9 +348,9 @@ eventsAdminRouter.put('/:eventId/songs/order', async (req: Request, res: Respons
  *      get:
  *          summary: Get an event's assigned questions
  *          tags: [feedback-admin]
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
  *              - in: path
  *                name: eventId
  *                required: true
@@ -347,13 +361,15 @@ eventsAdminRouter.put('/:eventId/songs/order', async (req: Request, res: Respons
  *                  description: Success
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  *      put:
  *          summary: Bulk-set an event's assigned questions
  *          description: One transaction - inserts new, updates existing, deletes removed. Keeps the admin UI a simple save-the-whole-list form.
  *          tags: [feedback-admin]
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
  *              - in: path
  *                name: eventId
  *                required: true
@@ -383,6 +399,8 @@ eventsAdminRouter.put('/:eventId/songs/order', async (req: Request, res: Respons
  *                  description: Saved
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  */
 eventsAdminRouter.get('/:eventId/questions', async (req: Request, res: Response) => {
 	try {

src/models/feedback/admin/questions.admin.router.ts

@@ -16,9 +16,9 @@ export const questionsAdminRouter = express.Router();
  *      get:
  *          summary: List the question library
  *          tags: [feedback-admin]
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
  *              - in: query
  *                name: includeArchived
  *                schema:
@@ -34,12 +34,13 @@ export const questionsAdminRouter = express.Router();
  *                                  $ref: '#/components/schemas/AdminQuestion'
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  *      post:
  *          summary: Create a question
  *          tags: [feedback-admin]
- *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
+ *          security:
+ *              - AdminSessionCookie: []
  *          requestBody:
  *              required: true
  *              content:
@@ -61,6 +62,8 @@ export const questionsAdminRouter = express.Router();
  *                  description: Missing or invalid fields
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  */
 questionsAdminRouter.get('/', async (req: Request, res: Response) => {
 	try {
@@ -94,9 +97,9 @@ questionsAdminRouter.post('/', async (req: Request, res: Response) => {
  *          summary: Edit a question's label/help text
  *          description: question_type is immutable after creation - the admin UI offers "archive and create new" instead.
  *          tags: [feedback-admin]
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
  *              - in: path
  *                name: questionId
  *                required: true
@@ -123,13 +126,15 @@ questionsAdminRouter.post('/', async (req: Request, res: Response) => {
  *                  description: Unknown question
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  *      delete:
  *          summary: Archive (or hard-delete) a question
  *          description: Archives the question if it has ever been used; hard-deletes it if it has never been assigned to any event.
  *          tags: [feedback-admin]
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
  *              - in: path
  *                name: questionId
  *                required: true
@@ -142,6 +147,8 @@ questionsAdminRouter.post('/', async (req: Request, res: Response) => {
  *                  description: Unknown question
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  */
 questionsAdminRouter.put('/:questionId', async (req: Request, res: Response) => {
 	try {

src/models/feedback/admin/reports.admin.router.ts

@@ -19,9 +19,9 @@ export const reportsAdminRouter = express.Router();
  *          summary: Aggregated feedback report for one event
  *          description: Song-pick vote counts, song-rating averages, capped free-text list, guest book count, and newsletter sync counts.
  *          tags: [feedback-admin]
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
  *              - in: path
  *                name: eventId
  *                required: true
@@ -34,6 +34,8 @@ export const reportsAdminRouter = express.Router();
  *                  description: Unknown event
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  */
 reportsAdminRouter.get('/:eventId/report', async (req: Request, res: Response) => {
 	try {
@@ -55,9 +57,9 @@ reportsAdminRouter.get('/:eventId/report', async (req: Request, res: Response) =
  *          summary: Guest Book entries for one event
  *          description: Newest first, paginated.
  *          tags: [feedback-admin]
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
  *              - in: path
  *                name: eventId
  *                required: true
@@ -81,6 +83,8 @@ reportsAdminRouter.get('/:eventId/report', async (req: Request, res: Response) =
  *                  description: Success
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  */
 reportsAdminRouter.get('/:eventId/guestbook', async (req: Request, res: Response) => {
 	try {
@@ -101,9 +105,9 @@ reportsAdminRouter.get('/:eventId/guestbook', async (req: Request, res: Response
  *          summary: Newsletter signups for one event
  *          description: Includes sync_status, so failures can be handled manually. Newest first, paginated.
  *          tags: [feedback-admin]
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
  *              - in: path
  *                name: eventId
  *                required: true
@@ -127,6 +131,8 @@ reportsAdminRouter.get('/:eventId/guestbook', async (req: Request, res: Response
  *                  description: Success
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  */
 reportsAdminRouter.get('/:eventId/newsletter', async (req: Request, res: Response) => {
 	try {
@@ -147,9 +153,9 @@ reportsAdminRouter.get('/:eventId/newsletter', async (req: Request, res: Respons
  *          summary: CSV export of all answers for one event
  *          description: Long format, one row per answer. UTF-8 BOM, `;` separator, RFC 4180 escaping, formula-injection guard.
  *          tags: [feedback-admin]
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
  *              - in: path
  *                name: eventId
  *                required: true
@@ -162,6 +168,8 @@ reportsAdminRouter.get('/:eventId/newsletter', async (req: Request, res: Respons
  *                      text/csv: {}
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  */
 reportsAdminRouter.get('/:eventId/export/responses.csv', async (req: Request, res: Response) => {
 	try {
@@ -187,9 +195,9 @@ reportsAdminRouter.get('/:eventId/export/responses.csv', async (req: Request, re
  *      get:
  *          summary: CSV export of Guest Book entries for one event
  *          tags: [feedback-admin]
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
  *              - in: path
  *                name: eventId
  *                required: true
@@ -202,6 +210,8 @@ reportsAdminRouter.get('/:eventId/export/responses.csv', async (req: Request, re
  *                      text/csv: {}
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  */
 reportsAdminRouter.get('/:eventId/export/guestbook.csv', async (req: Request, res: Response) => {
 	try {

src/models/feedback/admin/songs.admin.router.ts

@@ -16,9 +16,9 @@ export const songsAdminRouter = express.Router();
  *      put:
  *          summary: Edit a song's title/composer
  *          tags: [feedback-admin]
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
  *              - in: path
  *                name: songId
  *                required: true
@@ -45,13 +45,15 @@ export const songsAdminRouter = express.Router();
  *                  description: Unknown song
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  *      delete:
  *          summary: Remove a song
  *          description: Past answers keep their song_title_snapshot even after the song is removed.
  *          tags: [feedback-admin]
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
  *              - in: path
  *                name: songId
  *                required: true
@@ -64,6 +66,8 @@ export const songsAdminRouter = express.Router();
  *                  description: Unknown song
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  */
 songsAdminRouter.put('/:songId', async (req: Request, res: Response) => {
 	try {

src/models/feedback/feedback.auth.ts

@@ -1,78 +1,38 @@
-import express from 'express';
-import * as UserService from '../calendar/users/users.service.js';
-import {sendServerError} from './feedback.errors.js';
+import {requireAppAccess} from '../admin/admin.middleware.js';
 
 /**
  * This file is the ONLY place in the feedback module that knows how admin
- * authentication works today. No route handler and no service outside this
- * file may import users.service, read session headers, or touch bcrypt.
+ * authentication works. No route handler and no service outside this file may
+ * read session headers or resolve a user itself.
  *
- * Today: reuses the existing Calendar users/sessions mechanism. Any
- * activated @nachklang.art account may administer feedback — no roles.
- * Migrating to Keycloak later means writing a keycloakJwtAuthenticator
- * below and changing the one `activeAuthenticator` binding (plus the
- * frontend's login route handler) — nothing else in the feedback module
- * needs to change.
+ * Today: the shared admin identity in `src/models/admin/`. A session cookie
+ * set by /admin/auth on admin.nachklang.art, plus a `feedback` permission on
+ * the account. Both are re-checked on every request, so disabling a user or
+ * taking their feedback permission away takes effect immediately.
  *
- * Explicitly forbidden: accepting sessionId/sessionKey from query
- * parameters, even "temporarily". That is the exact mistake documented in
- * DEFERRED_SECURITY.md item 1 for the Calendar domain, where credentials
- * end up in access logs, browser history, proxy logs, and Referer headers.
- * Headers only.
+ * Before 2026-09-06 this was a header session against the calendar users
+ * table, and any activated @nachklang.art account could administer feedback.
+ * That is why the swap is a one-line binding: everything downstream only ever
+ * saw `requireAdminAuth` and `res.locals.admin`, and both still mean what
+ * they meant. What changed is that access is now granted per user rather than
+ * implied by having an account.
+ *
+ * Explicitly forbidden: accepting session credentials from query parameters,
+ * even "temporarily". That is the exact mistake documented in
+ * DEFERRED_SECURITY.md item 1 for the Calendar domain, where credentials end
+ * up in access logs, browser history, proxy logs, and Referer headers.
  */
 
-// The only thing the rest of the feedback module knows about an admin.
+// The only thing the rest of the feedback module knows about an admin. The
+// shared middleware puts a superset of this on res.locals.admin.
 export interface AdminIdentity {
 	id: string;
 	email: string;
 	displayName: string;
 }
 
-// Pluggable strategy: extract + verify credentials from a request.
-// Returns the identity, or null if unauthenticated. Throws only on
-// infrastructure errors (e.g. the DB being unreachable).
-export type AdminAuthenticator = (req: express.Request) => Promise<AdminIdentity | null>;
-
-// Current implementation: reads X-Session-Id / X-Session-Key headers,
-// delegates to the existing calendar UserService.checkSession(...).
-export const sessionHeaderAuthenticator: AdminAuthenticator = async (req) => {
-	const sessionId = req.header('X-Session-Id');
-	const sessionKey = req.header('X-Session-Key');
-	if (!sessionId || !sessionKey) {
-		return null;
-	}
-
-	const ip = req.ip || '';
-	const user = await UserService.checkSession(sessionId, sessionKey, ip);
-
-	// Mirrors the Calendar domain's own convention: a valid session on an
-	// inactive (not yet activated) account is not sufficient.
-	if (!user || !user.isActive) {
-		return null;
-	}
-
-	return {
-		id: String(user.userId),
-		email: user.email,
-		displayName: user.fullName
-	};
-};
-
-// Swap point: change this one binding to migrate to Keycloak.
-export const activeAuthenticator: AdminAuthenticator = sessionHeaderAuthenticator;
-
 // Express middleware used by every admin route. On success:
-// res.locals.admin = AdminIdentity, calls next(). On failure: 401.
-export const requireAdminAuth: express.RequestHandler = async (req, res, next) => {
-	try {
-		const identity = await activeAuthenticator(req);
-		if (!identity) {
-			res.status(401).send({status: 'UNAUTHORIZED', message: 'Anmeldung erforderlich.'});
-			return;
-		}
-		res.locals.admin = identity;
-		next();
-	} catch (e: any) {
-		sendServerError(res, e);
-	}
-};
+// res.locals.admin = AdminAccess (an AdminIdentity plus permissions), calls
+// next(). On failure: 401 when not signed in, 403 when signed in without the
+// feedback permission.
+export const requireAdminAuth = requireAppAccess('feedback');

src/models/tickets/admin/admin.router.ts

@@ -16,14 +16,15 @@ adminRouter.use(requireAdminAuth);
  *      get:
  *          summary: Validate the current admin session
  *          tags: [tickets-admin]
- *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
+ *          security:
+ *              - AdminSessionCookie: []
  *          responses:
  *              200:
  *                  description: Success
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  */
 adminRouter.get('/me', (req: Request, res: Response) => {
 	res.status(200).send({email: res.locals.admin.email, fullName: res.locals.admin.displayName});

src/models/tickets/admin/events.admin.router.ts

@@ -11,14 +11,15 @@ export const eventsAdminRouter = express.Router();
  *          summary: List concerts for the admin event picker
  *          description: Wraps the Calendar module's public-calendar admin listing (includes DRAFT events).
  *          tags: [tickets-admin]
- *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
+ *          security:
+ *              - AdminSessionCookie: []
  *          responses:
  *              200:
  *                  description: Success
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  */
 eventsAdminRouter.get('/', async (req: Request, res: Response) => {
 	try {
@@ -35,14 +36,15 @@ eventsAdminRouter.get('/', async (req: Request, res: Response) => {
  *          summary: List public-calendar events not yet added to the ticket shop
  *          description: Source list for the "add a concert" picker - the public calendar holds more than concerts, so events only appear in the ticket shop once explicitly added.
  *          tags: [tickets-admin]
- *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
+ *          security:
+ *              - AdminSessionCookie: []
  *          responses:
  *              200:
  *                  description: Success
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  */
 eventsAdminRouter.get('/available', async (req: Request, res: Response) => {
 	try {
@@ -58,9 +60,9 @@ eventsAdminRouter.get('/available', async (req: Request, res: Response) => {
  *      get:
  *          summary: Get a concert's voucher/capacity stats
  *          tags: [tickets-admin]
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
  *              - in: path
  *                name: eventId
  *                required: true
@@ -75,6 +77,8 @@ eventsAdminRouter.get('/available', async (req: Request, res: Response) => {
  *                              $ref: '#/components/schemas/EventStats'
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  */
 eventsAdminRouter.get('/:eventId/stats', async (req: Request, res: Response) => {
 	try {
@@ -91,9 +95,9 @@ eventsAdminRouter.get('/:eventId/stats', async (req: Request, res: Response) =>
  *          summary: Set a concert's voucher settings
  *          description: Upserts capacity (null = uncapped), redemption deadline (null = none), and whether to collect a mailing address.
  *          tags: [tickets-admin]
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
  *              - in: path
  *                name: eventId
  *                required: true
@@ -123,6 +127,8 @@ eventsAdminRouter.get('/:eventId/stats', async (req: Request, res: Response) =>
  *                  description: Saved
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  */
 eventsAdminRouter.put('/:eventId/settings', async (req: Request, res: Response) => {
 	try {
@@ -149,9 +155,9 @@ eventsAdminRouter.put('/:eventId/settings', async (req: Request, res: Response)
  *          summary: Remove an event from the ticket shop
  *          description: Deletes its settings row, so it drops out of the picker and reappears in the "add" list. Refused with 409 if vouchers already reference the event - existing vouchers/redemptions stay valid either way.
  *          tags: [tickets-admin]
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
  *              - in: path
  *                name: eventId
  *                required: true
@@ -164,6 +170,8 @@ eventsAdminRouter.put('/:eventId/settings', async (req: Request, res: Response)
  *                  description: Vouchers already reference this event
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  */
 eventsAdminRouter.delete('/:eventId/settings', async (req: Request, res: Response) => {
 	try {

src/models/tickets/admin/redemptions.admin.router.ts

@@ -11,9 +11,9 @@ export const redemptionsAdminRouter = express.Router();
  *          summary: List redemptions (admin)
  *          description: Filterable by event and status (ACTIVE/UNDONE).
  *          tags: [tickets-admin]
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
  *              - in: query
  *                name: eventId
  *                schema:
@@ -33,6 +33,8 @@ export const redemptionsAdminRouter = express.Router();
  *                                  $ref: '#/components/schemas/RedemptionSummary'
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  */
 redemptionsAdminRouter.get('/', async (req: Request, res: Response) => {
 	try {
@@ -50,9 +52,9 @@ redemptionsAdminRouter.get('/', async (req: Request, res: Response) => {
  *      get:
  *          summary: Get a single redemption (admin)
  *          tags: [tickets-admin]
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
  *              - in: path
  *                name: redemptionId
  *                required: true
@@ -65,13 +67,15 @@ redemptionsAdminRouter.get('/', async (req: Request, res: Response) => {
  *                  description: Unknown redemption
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  *      patch:
  *          summary: Edit a redemption's contact info and/or guest list
  *          description: Only fields present in the body are changed. Growing the guest count is re-checked against the voucher's max guests and the event's remaining capacity. Logs to the audit trail with an optional admin-supplied reason.
  *          tags: [tickets-admin]
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
  *              - in: path
  *                name: redemptionId
  *                required: true
@@ -105,6 +109,8 @@ redemptionsAdminRouter.get('/', async (req: Request, res: Response) => {
  *                  description: Not active, exceeds max guests, or exceeds remaining capacity
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  */
 redemptionsAdminRouter.get('/:redemptionId', async (req: Request, res: Response) => {
 	try {
@@ -161,9 +167,9 @@ redemptionsAdminRouter.patch('/:redemptionId', async (req: Request, res: Respons
  *          summary: Undo a redemption
  *          description: Reopens the code (back to UNUSED) and marks the redemption UNDONE. Guest data is kept for the audit trail; a later re-redemption creates a new redemption record.
  *          tags: [tickets-admin]
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
  *              - in: path
  *                name: redemptionId
  *                required: true
@@ -186,6 +192,8 @@ redemptionsAdminRouter.patch('/:redemptionId', async (req: Request, res: Respons
  *                  description: Redemption is not active
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  */
 redemptionsAdminRouter.post('/:redemptionId/undo', async (req: Request, res: Response) => {
 	try {
@@ -211,9 +219,9 @@ redemptionsAdminRouter.post('/:redemptionId/undo', async (req: Request, res: Res
  *          summary: Resend the redemption confirmation email
  *          description: Rebuilds the confirmation email from the stored redemption data and sends it again, then records the outcome on the redemption. Intended for redemptions whose original confirmation email failed.
  *          tags: [tickets-admin]
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
  *              - in: path
  *                name: redemptionId
  *                required: true
@@ -230,6 +238,8 @@ redemptionsAdminRouter.post('/:redemptionId/undo', async (req: Request, res: Res
  *                  description: The email relay rejected the send
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  */
 redemptionsAdminRouter.post('/:redemptionId/resend-confirmation', async (req: Request, res: Response) => {
 	try {
@@ -259,9 +269,9 @@ redemptionsAdminRouter.post('/:redemptionId/resend-confirmation', async (req: Re
  *      get:
  *          summary: Get a voucher's admin-action audit trail
  *          tags: [tickets-admin]
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
  *              - in: path
  *                name: code
  *                required: true
@@ -278,6 +288,8 @@ redemptionsAdminRouter.post('/:redemptionId/resend-confirmation', async (req: Re
  *                                  $ref: '#/components/schemas/AuditLogEntry'
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  */
 export const voucherHistoryRouter = express.Router();
 voucherHistoryRouter.get('/:code/history', async (req: Request, res: Response) => {

src/models/tickets/admin/vouchers.admin.router.ts

@@ -11,9 +11,9 @@ export const vouchersAdminRouter = express.Router();
  *          summary: List vouchers (admin)
  *          description: Filterable by event and status.
  *          tags: [tickets-admin]
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
  *              - in: query
  *                name: eventId
  *                schema:
@@ -33,6 +33,8 @@ export const vouchersAdminRouter = express.Router();
  *                                  $ref: '#/components/schemas/VoucherCode'
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  */
 vouchersAdminRouter.get('/', async (req: Request, res: Response) => {
 	try {
@@ -51,9 +53,8 @@ vouchersAdminRouter.get('/', async (req: Request, res: Response) => {
  *          summary: Batch-generate wildcard codes
  *          description: Generates `quantity` codes sharing the same eligible events and max-guest count, grouped under one batchId.
  *          tags: [tickets-admin]
- *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
+ *          security:
+ *              - AdminSessionCookie: []
  *          requestBody:
  *              required: true
  *              content:
@@ -87,6 +88,8 @@ vouchersAdminRouter.get('/', async (req: Request, res: Response) => {
  *                  description: Invalid input
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  */
 vouchersAdminRouter.post('/wildcard', async (req: Request, res: Response) => {
 	try {
@@ -112,9 +115,8 @@ vouchersAdminRouter.post('/wildcard', async (req: Request, res: Response) => {
  *          summary: Bulk-create personalized codes
  *          description: One code per row (name, email, eligible events, max guests), grouped under one batchId.
  *          tags: [tickets-admin]
- *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
+ *          security:
+ *              - AdminSessionCookie: []
  *          requestBody:
  *              required: true
  *              content:
@@ -147,6 +149,8 @@ vouchersAdminRouter.post('/wildcard', async (req: Request, res: Response) => {
  *                  description: Invalid input
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  */
 vouchersAdminRouter.post('/personalized', async (req: Request, res: Response) => {
 	try {
@@ -169,9 +173,9 @@ vouchersAdminRouter.post('/personalized', async (req: Request, res: Response) =>
  *      get:
  *          summary: Get a single voucher (admin)
  *          tags: [tickets-admin]
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
  *              - in: path
  *                name: code
  *                required: true
@@ -184,6 +188,8 @@ vouchersAdminRouter.post('/personalized', async (req: Request, res: Response) =>
  *                  description: Unknown code
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  */
 vouchersAdminRouter.get('/:code', async (req: Request, res: Response) => {
 	try {
@@ -205,9 +211,9 @@ vouchersAdminRouter.get('/:code', async (req: Request, res: Response) => {
  *          summary: Void an unredeemed code
  *          description: Only allowed while the code is UNUSED. Logs to the voucher's audit trail.
  *          tags: [tickets-admin]
+ *          security:
+ *              - AdminSessionCookie: []
  *          parameters:
- *              - $ref: '#/components/parameters/SessionIdHeader'
- *              - $ref: '#/components/parameters/SessionKeyHeader'
  *              - in: path
  *                name: code
  *                required: true
@@ -230,6 +236,8 @@ vouchersAdminRouter.get('/:code', async (req: Request, res: Response) => {
  *                  description: Code is not in UNUSED status
  *              401:
  *                  description: Unauthorized
+ *              403:
+ *                  description: Signed in without the permission for this app, or account disabled
  */
 vouchersAdminRouter.post('/:code/void', async (req: Request, res: Response) => {
 	try {

src/models/tickets/tickets.auth.ts

@@ -1,20 +1,23 @@
-import express from 'express';
-import * as UserService from '../calendar/users/users.service.js';
-import {sendServerError} from './tickets.errors.js';
+import {requireAppAccess} from '../admin/admin.middleware.js';
 
 /**
  * Mirrors the Feedback module's feedback.auth.ts: this is the ONLY place in
  * the tickets module that knows how admin authentication works. No route
- * handler and no service outside this file may import users.service, read
- * session headers, or touch bcrypt.
+ * handler and no service outside this file may read session headers or
+ * resolve a user itself.
  *
- * Today: reuses the existing Calendar users/sessions mechanism. Any
- * activated @nachklang.art account may administer vouchers - no roles, same
- * policy as Feedback (see docs/plan-ticket-shop.md). A dedicated
- * roles/permissions model is explicitly out of scope for v1.
+ * Today: the shared admin identity in `src/models/admin/`. A session cookie
+ * set by /admin/auth on admin.nachklang.art, plus a `tickets` permission on
+ * the account. Both are re-checked on every request, so disabling a user or
+ * taking their tickets permission away takes effect immediately.
  *
- * Explicitly forbidden: accepting sessionId/sessionKey from query
- * parameters - headers only (see DEFERRED_SECURITY.md item 1).
+ * Before 2026-09-06 this was a header session against the calendar users
+ * table, and any activated @nachklang.art account could administer vouchers
+ * (see docs/plan-ticket-shop.md, which called a roles model out of scope for
+ * v1). It is in scope now, and lives in the admin module rather than here.
+ *
+ * Explicitly forbidden: accepting session credentials from query parameters -
+ * see DEFERRED_SECURITY.md item 1.
  */
 
 export interface AdminIdentity {
@@ -23,41 +26,6 @@ export interface AdminIdentity {
 	displayName: string;
 }
 
-export type AdminAuthenticator = (req: express.Request) => Promise<AdminIdentity | null>;
-
-export const sessionHeaderAuthenticator: AdminAuthenticator = async (req) => {
-	const sessionId = req.header('X-Session-Id');
-	const sessionKey = req.header('X-Session-Key');
-	if (!sessionId || !sessionKey) {
-		return null;
-	}
-
-	const ip = req.ip || '';
-	const user = await UserService.checkSession(sessionId, sessionKey, ip);
-
-	if (!user || !user.isActive) {
-		return null;
-	}
-
-	return {
-		id: String(user.userId),
-		email: user.email,
-		displayName: user.fullName
-	};
-};
-
-export const activeAuthenticator: AdminAuthenticator = sessionHeaderAuthenticator;
-
-export const requireAdminAuth: express.RequestHandler = async (req, res, next) => {
-	try {
-		const identity = await activeAuthenticator(req);
-		if (!identity) {
-			res.status(401).send({status: 'UNAUTHORIZED', message: 'Anmeldung erforderlich.'});
-			return;
-		}
-		res.locals.admin = identity;
-		next();
-	} catch (e: any) {
-		sendServerError(res, e);
-	}
-};
+// On failure: 401 when not signed in, 403 when signed in without the tickets
+// permission.
+export const requireAdminAuth = requireAppAccess('tickets');

test/admin/admin.bootstrap.test.ts

@@ -0,0 +1,96 @@
+import {vi, describe, it, expect, beforeEach, type Mock} from 'vitest';
+
+vi.mock('../../src/models/admin/users/users.admin.service.js', () => ({
+	countActiveAdmins: vi.fn(),
+	findUserByEmail: vi.fn(),
+	grantPermission: vi.fn()
+}));
+vi.mock('../../src/models/admin/invitations/invitations.service.js', () => ({
+	hasOpenInvitationFor: vi.fn(),
+	createInvitation: vi.fn()
+}));
+vi.mock('../../src/models/admin/admin.mail.js', () => ({
+	sendInvitationMail: vi.fn()
+}));
+vi.mock('../../src/models/admin/admin.config.js', () => ({
+	ADMIN_BOOTSTRAP_EMAIL: 'boss@nachklang.art',
+	ADMIN_APP_URL: 'http://localhost:3002',
+	isProd: false
+}));
+
+import * as UsersService from '../../src/models/admin/users/users.admin.service.js';
+import * as InvitationsService from '../../src/models/admin/invitations/invitations.service.js';
+import {sendInvitationMail} from '../../src/models/admin/admin.mail.js';
+import {bootstrapAdmin} from '../../src/models/admin/admin.bootstrap.js';
+
+const countActiveAdmins = UsersService.countActiveAdmins as Mock;
+const findUserByEmail = UsersService.findUserByEmail as Mock;
+const grantPermission = UsersService.grantPermission as Mock;
+const hasOpenInvitationFor = InvitationsService.hasOpenInvitationFor as Mock;
+const createInvitation = InvitationsService.createInvitation as Mock;
+const mockMail = sendInvitationMail as Mock;
+
+beforeEach(() => {
+	countActiveAdmins.mockReset();
+	findUserByEmail.mockReset();
+	grantPermission.mockReset();
+	hasOpenInvitationFor.mockReset();
+	createInvitation.mockReset();
+	mockMail.mockReset();
+	mockMail.mockResolvedValue(true);
+	createInvitation.mockResolvedValue({id: 1, token: 'raw-token', expiresAt: new Date()});
+});
+
+describe('bootstrapAdmin', () => {
+	it('does nothing when an active admin already exists', async () => {
+		countActiveAdmins.mockResolvedValue(1);
+
+		await bootstrapAdmin();
+
+		expect(createInvitation).not.toHaveBeenCalled();
+		expect(grantPermission).not.toHaveBeenCalled();
+	});
+
+	it('grants admin directly when the bootstrap address is already a user', async () => {
+		countActiveAdmins.mockResolvedValue(0);
+		findUserByEmail.mockResolvedValue({id: 'u9', email: 'boss@nachklang.art'});
+
+		await bootstrapAdmin();
+
+		expect(grantPermission).toHaveBeenCalledWith('u9', 'admin', null);
+		expect(createInvitation).not.toHaveBeenCalled();
+	});
+
+	it('does not re-invite (or re-mail) while an open invitation exists', async () => {
+		countActiveAdmins.mockResolvedValue(0);
+		findUserByEmail.mockResolvedValue(null);
+		hasOpenInvitationFor.mockResolvedValue(true);
+
+		await bootstrapAdmin();
+
+		expect(createInvitation).not.toHaveBeenCalled();
+		expect(mockMail).not.toHaveBeenCalled();
+	});
+
+	it('invites with the admin permission when there is nothing to work with', async () => {
+		countActiveAdmins.mockResolvedValue(0);
+		findUserByEmail.mockResolvedValue(null);
+		hasOpenInvitationFor.mockResolvedValue(false);
+
+		await bootstrapAdmin();
+
+		expect(createInvitation).toHaveBeenCalledWith(
+			'boss@nachklang.art',
+			'Nachklang Admin',
+			[{app: 'admin', role: 'access'}],
+			null
+		);
+		expect(mockMail).toHaveBeenCalled();
+	});
+
+	it('never throws when the database is unreachable at boot', async () => {
+		countActiveAdmins.mockRejectedValue(new Error('connect ECONNREFUSED'));
+
+		await expect(bootstrapAdmin()).resolves.toBeUndefined();
+	});
+});

test/admin/admin.config.test.ts

@@ -0,0 +1,144 @@
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+
+// admin.config calls dotenv.config(), which would read the repo's own .env and
+// quietly reintroduce NODE_ENV=development - the exact value several of these
+// cases exist to remove. Stub it so the tests see only what they set.
+vi.mock('dotenv', () => ({config: vi.fn()}));
+
+/**
+ * admin.config reads the environment once at import, so every case here has to
+ * reset the module registry and re-import it. The two things worth pinning are
+ * the ones that are silent when wrong: which client-IP header is trusted, and
+ * whether an unset NODE_ENV counts as production.
+ */
+
+const ORIGINAL_ENV = {...process.env};
+
+const loadConfig = async () => {
+	vi.resetModules();
+	return import('../../src/models/admin/admin.config.js');
+};
+
+beforeEach(() => {
+	process.env = {...ORIGINAL_ENV};
+	// dotenv.config() in admin.config does not overwrite what is already set,
+	// so setting these here is enough to keep the local .env out of the test.
+	process.env.NODE_ENV = 'test';
+	delete process.env.CLIENT_IP_HEADERS;
+	delete process.env.TRUSTED_PROXY_IPS;
+});
+
+afterEach(() => {
+	process.env = {...ORIGINAL_ENV};
+});
+
+describe('CLIENT_IP_HEADERS', () => {
+	it('defaults to the single header Plesk nginx sets', async () => {
+		const config = await loadConfig();
+		expect(config.CLIENT_IP_HEADERS).toEqual(['x-real-ip']);
+		expect(config.TRUST_NO_CLIENT_IP_HEADER).toBe(false);
+	});
+
+	it('reads a comma-separated list', async () => {
+		process.env.CLIENT_IP_HEADERS = 'x-real-ip, cf-connecting-ip';
+		const config = await loadConfig();
+		expect(config.CLIENT_IP_HEADERS).toEqual(['x-real-ip', 'cf-connecting-ip']);
+	});
+
+	it('trusts nothing when set to "none"', async () => {
+		// The escape hatch. An empty list is what better-auth reads as "no
+		// headers" - it only falls back to its own default when the option is
+		// absent - so this really does stop any header being believed.
+		process.env.CLIENT_IP_HEADERS = 'none';
+		const config = await loadConfig();
+		expect(config.CLIENT_IP_HEADERS).toEqual([]);
+		expect(config.TRUST_NO_CLIENT_IP_HEADER).toBe(true);
+	});
+
+	it('accepts the hatch case-insensitively and with stray whitespace', async () => {
+		process.env.CLIENT_IP_HEADERS = '  NONE  ';
+		const config = await loadConfig();
+		expect(config.CLIENT_IP_HEADERS).toEqual([]);
+	});
+
+	it('treats an empty value as "use the default", not as the hatch', async () => {
+		// A blank line in a .env must not silently change how requests are
+		// bucketed - only the explicit word does that.
+		process.env.CLIENT_IP_HEADERS = '';
+		const config = await loadConfig();
+		expect(config.CLIENT_IP_HEADERS).toEqual(['x-real-ip']);
+		expect(config.TRUST_NO_CLIENT_IP_HEADER).toBe(false);
+	});
+
+	it('does not mistake a header actually named none-ish for the hatch', async () => {
+		process.env.CLIENT_IP_HEADERS = 'x-none';
+		const config = await loadConfig();
+		expect(config.CLIENT_IP_HEADERS).toEqual(['x-none']);
+		expect(config.TRUST_NO_CLIENT_IP_HEADER).toBe(false);
+	});
+});
+
+describe('APP_ORIGINS', () => {
+	beforeEach(() => {
+		delete process.env.APP_ORIGINS;
+	});
+
+	// These reach better-auth's trustedOrigins, and the step 4 cutover made the
+	// tickets and feedback origins load-bearing: without them their sign-out
+	// call is rejected while everything else still works.
+	it('defaults to the three production frontends', async () => {
+		const config = await loadConfig();
+		expect(config.APP_ORIGINS).toEqual([
+			'https://tickets.nachklang.art',
+			'https://feedback.nachklang.art',
+			'https://calendar.nachklang.art'
+		]);
+	});
+
+	it('is overridden wholesale by the environment, for a staging host', async () => {
+		process.env.APP_ORIGINS = 'https://tickets.staging.example, https://feedback.staging.example/';
+		const config = await loadConfig();
+		expect(config.APP_ORIGINS).toEqual([
+			'https://tickets.staging.example',
+			// Trailing slash stripped: an origin with one never matches.
+			'https://feedback.staging.example'
+		]);
+	});
+
+	it('always includes the admin app itself in ADMIN_ALLOWED_ORIGINS', async () => {
+		process.env.ADMIN_APP_URL = 'https://admin.nachklang.art';
+		const config = await loadConfig();
+		expect(config.ADMIN_ALLOWED_ORIGINS).toContain('https://admin.nachklang.art');
+		expect(config.ADMIN_ALLOWED_ORIGINS).toContain('https://tickets.nachklang.art');
+	});
+});
+
+describe('isProd', () => {
+	it('is false only for the explicit relaxed environments', async () => {
+		process.env.NODE_ENV = 'development';
+		expect((await loadConfig()).isProd).toBe(false);
+
+		process.env.NODE_ENV = 'test';
+		expect((await loadConfig()).isProd).toBe(false);
+	});
+
+	it('treats an unset NODE_ENV as production, which is what a bare vhost gives', async () => {
+		delete process.env.NODE_ENV;
+		// Strict mode refuses to boot without these; supply them so the import
+		// gets far enough to answer the question being asked.
+		process.env.BETTER_AUTH_SECRET = 'x'.repeat(48);
+		process.env.API_BASE_URL = 'https://api.nachklang.art';
+		process.env.ADMIN_APP_URL = 'https://admin.nachklang.art';
+
+		expect((await loadConfig()).isProd).toBe(true);
+	});
+
+	it('refuses to start without a signing key outside development', async () => {
+		delete process.env.NODE_ENV;
+		delete process.env.BETTER_AUTH_SECRET;
+		process.env.API_BASE_URL = 'https://api.nachklang.art';
+		process.env.ADMIN_APP_URL = 'https://admin.nachklang.art';
+
+		await expect(loadConfig()).rejects.toThrow(/BETTER_AUTH_SECRET/);
+	});
+});

test/admin/admin.mail.test.ts

@@ -0,0 +1,71 @@
+import {vi, describe, it, expect, beforeEach, type Mock} from 'vitest';
+
+vi.mock('../../src/common/common.mail.js', () => ({
+	MailService: {sendMail: vi.fn()}
+}));
+vi.mock('../../src/models/admin/admin.config.js', () => ({
+	ADMIN_APP_URL: 'https://admin.nachklang.art'
+}));
+
+import {MailService} from '../../src/common/common.mail.js';
+import {sendInvitationMail, sendPasswordResetMail} from '../../src/models/admin/admin.mail.js';
+
+const sendMail = MailService.sendMail as Mock;
+
+beforeEach(() => {
+	sendMail.mockReset();
+	sendMail.mockResolvedValue(true);
+});
+
+describe('sendInvitationMail', () => {
+	it('points at the admin app and carries the token in the query string', async () => {
+		await sendInvitationMail('a@nachklang.art', 'Anna', 'tok-en_123', new Date('2026-09-12T10:00:00Z'));
+
+		const [to, subject, text, options] = sendMail.mock.calls[0];
+		expect(to).toBe('a@nachklang.art');
+		expect(subject).toBeTruthy();
+		expect(text).toContain('https://admin.nachklang.art/accept-invite?token=tok-en_123');
+		expect(options.html).toContain('https://admin.nachklang.art/accept-invite?token=tok-en_123');
+	});
+
+	it('url-encodes a token containing url-significant characters', async () => {
+		await sendInvitationMail('a@nachklang.art', 'Anna', 'a+b/c=d', new Date());
+
+		const [, , text] = sendMail.mock.calls[0];
+		expect(text).toContain('token=a%2Bb%2Fc%3Dd');
+	});
+
+	it('sends both a text and an html part', async () => {
+		await sendInvitationMail('a@nachklang.art', 'Anna', 'tok', new Date());
+
+		const [, , text, options] = sendMail.mock.calls[0];
+		expect(text.length).toBeGreaterThan(0);
+		expect(options.html).toContain('<html');
+	});
+
+	it('escapes a name that contains html', async () => {
+		await sendInvitationMail('a@nachklang.art', '<script>alert(1)</script>', 'tok', new Date());
+
+		const [, , , options] = sendMail.mock.calls[0];
+		expect(options.html).not.toContain('<script>');
+		expect(options.html).toContain('&lt;script&gt;');
+	});
+
+	it('reports a delivery failure to the caller rather than throwing', async () => {
+		sendMail.mockResolvedValue(false);
+
+		await expect(sendInvitationMail('a@nachklang.art', 'Anna', 'tok', new Date())).resolves.toBe(false);
+	});
+});
+
+describe('sendPasswordResetMail', () => {
+	it('uses the url better-auth generated, unchanged', async () => {
+		const url = 'https://api.nachklang.art/admin/auth/reset-password/abc?callbackURL=x';
+
+		await sendPasswordResetMail('a@nachklang.art', 'Anna', url);
+
+		const [, , text, options] = sendMail.mock.calls[0];
+		expect(text).toContain(url);
+		expect(options.html).toContain('https://api.nachklang.art/admin/auth/reset-password/abc');
+	});
+});

test/admin/admin.middleware.test.ts

@@ -0,0 +1,222 @@
+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,
+	permissions: [
+		{app: 'feedback', role: 'access'},
+		{app: 'admin', role: 'access'}
+	],
+	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,
+			permissions: [
+				{app: 'feedback', role: 'access'},
+				{app: 'admin', role: 'access'}
+			],
+			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,
+			permissions: [{app: 'feedback', role: 'access'}],
+			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();
+	});
+
+	// The seam a finer per-app permission arrives through. Nothing passes a role
+	// today, so these two pin the behaviour before there is anything to break.
+	it('403s when a specific role is required and the user only holds another', async () => {
+		mockGetSession.mockResolvedValue({user: {id: 'u1'}});
+		mockLoadAccess.mockResolvedValue({
+			...activeUser,
+			permissions: [{app: 'tickets', role: 'access'}],
+			apps: ['tickets']
+		});
+		const res = makeRes();
+		const next = vi.fn();
+
+		await requireAppAccess('tickets', 'refund')(makeReq(), res, next);
+
+		expect(res.status).toHaveBeenCalledWith(403);
+		expect(next).not.toHaveBeenCalled();
+	});
+
+	it('passes when the user holds exactly the required role', async () => {
+		mockGetSession.mockResolvedValue({user: {id: 'u1'}});
+		mockLoadAccess.mockResolvedValue({
+			...activeUser,
+			permissions: [
+				{app: 'tickets', role: 'access'},
+				{app: 'tickets', role: 'refund'}
+			],
+			apps: ['tickets']
+		});
+		const res = makeRes();
+		const next = vi.fn();
+
+		await requireAppAccess('tickets', 'refund')(makeReq(), res, next);
+
+		expect(next).toHaveBeenCalled();
+	});
+});

test/admin/admin.schema.test.ts

@@ -0,0 +1,99 @@
+import {describe, expect, it} from 'vitest';
+import {
+	ACCESS_ROLE,
+	appsOf,
+	isAppPermission,
+	isAppRole,
+	toPermissions
+} from '../../src/models/admin/admin.schema.js';
+
+/**
+ * The permission model is (app, role). These tests pin the two properties the
+ * rest of the module leans on: that the older `['tickets']` shape still means
+ * "tickets at the access role", and that nothing outside APP_ROLES gets in.
+ */
+
+describe('toPermissions', () => {
+	it('reads the full (app, role) form', () => {
+		expect(toPermissions([{app: 'tickets', role: 'access'}])).toEqual([
+			{app: 'tickets', role: 'access'}
+		]);
+	});
+
+	it('reads a plain app list as that app at the access role', () => {
+		expect(toPermissions(['feedback', 'admin'])).toEqual([
+			{app: 'feedback', role: ACCESS_ROLE},
+			{app: 'admin', role: ACCESS_ROLE}
+		]);
+	});
+
+	it('accepts the two forms mixed, which is what a half-migrated caller sends', () => {
+		expect(toPermissions(['feedback', {app: 'tickets', role: 'access'}])).toEqual([
+			{app: 'feedback', role: ACCESS_ROLE},
+			{app: 'tickets', role: ACCESS_ROLE}
+		]);
+	});
+
+	it('drops duplicates of the same (app, role)', () => {
+		expect(toPermissions(['tickets', {app: 'tickets', role: 'access'}])).toEqual([
+			{app: 'tickets', role: ACCESS_ROLE}
+		]);
+	});
+
+	it('rejects rather than silently dropping an unknown app', () => {
+		// Silently ignoring it would let "grant calendar + nonsense" look like a
+		// success while granting less than the caller asked for.
+		expect(toPermissions(['calendar', 'nonsense'])).toBeNull();
+	});
+
+	it('rejects an unknown role', () => {
+		expect(toPermissions([{app: 'tickets', role: 'refund'}])).toBeNull();
+	});
+
+	it('rejects anything that is not a list', () => {
+		expect(toPermissions('admin')).toBeNull();
+		expect(toPermissions(null)).toBeNull();
+		expect(toPermissions({app: 'admin', role: 'access'})).toBeNull();
+	});
+
+	it('reads an empty list as "no permissions", not as invalid', () => {
+		expect(toPermissions([])).toEqual([]);
+	});
+});
+
+describe('isAppRole', () => {
+	it('accepts the access role for every app', () => {
+		expect(isAppRole('admin', ACCESS_ROLE)).toBe(true);
+		expect(isAppRole('calendar', ACCESS_ROLE)).toBe(true);
+	});
+
+	it('rejects a role that does not exist yet', () => {
+		expect(isAppRole('tickets', 'refund')).toBe(false);
+	});
+});
+
+describe('isAppPermission', () => {
+	it('needs both halves to be valid', () => {
+		expect(isAppPermission({app: 'tickets', role: ACCESS_ROLE})).toBe(true);
+		expect(isAppPermission({app: 'tickets'})).toBe(false);
+		expect(isAppPermission({role: ACCESS_ROLE})).toBe(false);
+		expect(isAppPermission(null)).toBe(false);
+	});
+});
+
+describe('appsOf', () => {
+	it('collapses several roles on one app to a single entry', () => {
+		// The point of the derived list: a user with two roles on tickets has
+		// access to tickets once, not twice.
+		const apps = appsOf([
+			{app: 'tickets', role: ACCESS_ROLE},
+			{app: 'tickets', role: 'future-role'},
+			{app: 'admin', role: ACCESS_ROLE}
+		]);
+		expect(apps).toEqual(['tickets', 'admin']);
+	});
+
+	it('is empty for no permissions', () => {
+		expect(appsOf([])).toEqual([]);
+	});
+});

test/admin/auth-binding.ts

@@ -0,0 +1,118 @@
+import {vi, describe, it, expect, beforeEach, type Mock} from 'vitest';
+import express, {Request, Response} from 'express';
+
+/**
+ * Shared body for the two cutover tests (2026-09-06). feedback.auth.ts and
+ * tickets.auth.ts used to carry their own header-session authenticator against
+ * the calendar users table; both are now one binding to the shared admin gate.
+ *
+ * What is worth asserting is not how that gate works - admin.middleware.test.ts
+ * owns that - but that each module is bound to *its own* app, and that neither
+ * consults the calendar users service any more. The mocks live in the calling
+ * file because vi.mock is per-module-graph; only the assertions are shared.
+ */
+
+export interface BindingMocks {
+	/** auth.api.getSession from the mocked admin.auth.js */
+	getSession: Mock;
+	/** loadAccess from the mocked users.admin.service.js */
+	loadAccess: Mock;
+	/** checkSession from the mocked calendar users.service.js */
+	checkSession: 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 userWith = (...apps: string[]) => ({
+	id: 'u1',
+	email: 'a@nachklang.art',
+	displayName: 'Anna Admin',
+	disabled: false,
+	permissions: apps.map(app => ({app, role: 'access'})),
+	apps
+});
+
+export const describeAdminBinding = (
+	app: string,
+	otherApp: string,
+	middleware: express.RequestHandler,
+	mocks: () => BindingMocks
+): void => {
+	describe(`${app} requireAdminAuth`, () => {
+		let m: BindingMocks;
+
+		const run = async () => {
+			const res = makeRes();
+			const next = vi.fn();
+			await middleware(makeReq(), res, next);
+			return {res, next};
+		};
+
+		beforeEach(() => {
+			m = mocks();
+			m.getSession.mockReset();
+			m.loadAccess.mockReset();
+			m.checkSession.mockReset();
+		});
+
+		it('responds 401 and does not call next() without a session', async () => {
+			m.getSession.mockResolvedValue(null);
+
+			const {res, next} = await run();
+
+			expect(res.status).toHaveBeenCalledWith(401);
+			expect(next).not.toHaveBeenCalled();
+		});
+
+		it(`responds 403 for a signed-in user who only has ${otherApp}`, async () => {
+			m.getSession.mockResolvedValue({user: {id: 'u1'}});
+			m.loadAccess.mockResolvedValue(userWith(otherApp));
+
+			const {res, next} = await run();
+
+			expect(res.status).toHaveBeenCalledWith(403);
+			expect(next).not.toHaveBeenCalled();
+		});
+
+		it('responds 403 for a disabled user who still holds the permission', async () => {
+			m.getSession.mockResolvedValue({user: {id: 'u1'}});
+			m.loadAccess.mockResolvedValue({...userWith(app), disabled: true});
+
+			const {res, next} = await run();
+
+			expect(res.status).toHaveBeenCalledWith(403);
+			expect(next).not.toHaveBeenCalled();
+		});
+
+		it('sets res.locals.admin and calls next() with the permission', async () => {
+			m.getSession.mockResolvedValue({user: {id: 'u1'}});
+			m.loadAccess.mockResolvedValue(userWith(app));
+
+			const {res, next} = await run();
+
+			expect(next).toHaveBeenCalled();
+			expect(res.locals.admin).toMatchObject({id: 'u1', email: 'a@nachklang.art', displayName: 'Anna Admin'});
+		});
+
+		// Weaker than it looks and kept deliberately: neither module imports
+		// checkSession any more, so this cannot fail today. It is a tripwire for
+		// the change that would matter - someone reintroducing a header-session
+		// fallback "just for the calendar users who have not been invited yet",
+		// which is exactly the shortcut the cutover exists to close.
+		it('never falls back to a calendar header session', async () => {
+			m.getSession.mockResolvedValue(null);
+
+			await run();
+
+			expect(m.checkSession).not.toHaveBeenCalled();
+		});
+	});
+};

test/admin/users.admin.router.test.ts

@@ -0,0 +1,199 @@
+import {vi, describe, it, expect, beforeEach, type Mock} from 'vitest';
+import express from 'express';
+import request from 'supertest';
+
+vi.mock('../../src/models/admin/users/users.admin.service.js', () => ({
+	listUsers: vi.fn(),
+	getUserDetail: vi.fn(),
+	loadAccess: vi.fn(),
+	setPermissions: vi.fn(),
+	setPermissionsGuarded: vi.fn(),
+	disableUser: vi.fn(),
+	disableUserGuarded: vi.fn(),
+	enableUser: vi.fn(),
+	revokeSession: vi.fn(),
+	countActiveAdmins: vi.fn(),
+	userExists: vi.fn()
+}));
+
+import * as UsersService from '../../src/models/admin/users/users.admin.service.js';
+import {usersAdminRouter} from '../../src/models/admin/users/users.admin.router.js';
+
+const service = UsersService as unknown as Record<string, Mock>;
+
+// The router always runs behind requireAppAccess('admin'), which is what puts
+// res.locals.admin there; this stands in for it.
+const makeApp = (callerId = 'me') => {
+	const app = express();
+	app.use(express.json());
+	app.use((req, res, next) => {
+		res.locals.admin = {id: callerId, email: 'me@nachklang.art', displayName: 'Me', apps: ['admin']};
+		next();
+	});
+	app.use('/admin/users', usersAdminRouter);
+	return app;
+};
+
+beforeEach(() => {
+	for (const fn of Object.values(service)) {
+		if (typeof fn?.mockReset === 'function') {
+			fn.mockReset();
+		}
+	}
+	service.getUserDetail.mockResolvedValue({id: 'other', apps: []});
+	service.userExists.mockResolvedValue(true);
+	service.setPermissionsGuarded.mockResolvedValue('ok');
+	service.disableUserGuarded.mockResolvedValue('ok');
+});
+
+describe('PUT /admin/users/:id/permissions', () => {
+	it('rejects an unknown app name', async () => {
+		const res = await request(makeApp()).put('/admin/users/other/permissions').send({apps: ['calendar', 'nope']});
+
+		expect(res.status).toBe(400);
+		expect(service.setPermissionsGuarded).not.toHaveBeenCalled();
+	});
+
+	it('rejects a non-array body', async () => {
+		const res = await request(makeApp()).put('/admin/users/other/permissions').send({apps: 'admin'});
+
+		expect(res.status).toBe(400);
+	});
+
+	it('404s for an unknown user', async () => {
+		service.userExists.mockResolvedValue(false);
+
+		const res = await request(makeApp()).put('/admin/users/ghost/permissions').send({apps: []});
+
+		expect(res.status).toBe(404);
+		expect(service.setPermissionsGuarded).not.toHaveBeenCalled();
+	});
+
+	it('refuses to remove the caller\'s own admin permission', async () => {
+		service.loadAccess.mockResolvedValue({id: 'me', disabled: false, apps: ['admin']});
+		service.countActiveAdmins.mockResolvedValue(5);
+
+		const res = await request(makeApp('me')).put('/admin/users/me/permissions').send({apps: ['feedback']});
+
+		expect(res.status).toBe(409);
+		expect(service.setPermissionsGuarded).not.toHaveBeenCalled();
+	});
+
+	// The last-admin decision is made inside the write transaction (so two
+	// admins acting at once cannot both pass a check-then-act); the router's
+	// job is only to turn that verdict into a 409.
+	it('answers 409 when the service reports the last admin would be removed', async () => {
+		service.loadAccess.mockResolvedValue({id: 'other', disabled: false, apps: ['admin']});
+		service.setPermissionsGuarded.mockResolvedValue('last-admin');
+
+		const res = await request(makeApp('me')).put('/admin/users/other/permissions').send({apps: []});
+
+		expect(res.status).toBe(409);
+	});
+
+	it('allows removing an admin while another active admin remains', async () => {
+		service.loadAccess.mockResolvedValue({id: 'other', disabled: false, apps: ['admin']});
+
+		const res = await request(makeApp('me')).put('/admin/users/other/permissions').send({apps: ['tickets']});
+
+		expect(res.status).toBe(200);
+		expect(service.setPermissionsGuarded).toHaveBeenCalledWith(
+			'other',
+			[{app: 'tickets', role: 'access'}],
+			'me'
+		);
+	});
+
+	it('accepts the richer {permissions} body', async () => {
+		service.loadAccess.mockResolvedValue({id: 'other', disabled: false, apps: []});
+
+		const res = await request(makeApp('me'))
+			.put('/admin/users/other/permissions')
+			.send({permissions: [{app: 'tickets', role: 'access'}]});
+
+		expect(res.status).toBe(200);
+		expect(service.setPermissionsGuarded).toHaveBeenCalledWith(
+			'other',
+			[{app: 'tickets', role: 'access'}],
+			'me'
+		);
+	});
+
+	it('rejects a role that does not exist', async () => {
+		service.loadAccess.mockResolvedValue({id: 'other', disabled: false, apps: []});
+
+		const res = await request(makeApp('me'))
+			.put('/admin/users/other/permissions')
+			.send({permissions: [{app: 'tickets', role: 'refund'}]});
+
+		expect(res.status).toBe(400);
+		expect(service.setPermissionsGuarded).not.toHaveBeenCalled();
+	});
+
+	it('allows granting permissions to someone who has none', async () => {
+		service.loadAccess.mockResolvedValue({id: 'other', disabled: false, apps: []});
+
+		const res = await request(makeApp('me')).put('/admin/users/other/permissions').send({apps: ['feedback', 'tickets']});
+
+		expect(res.status).toBe(200);
+		expect(service.setPermissionsGuarded).toHaveBeenCalledWith(
+			'other',
+			[{app: 'feedback', role: 'access'}, {app: 'tickets', role: 'access'}],
+			'me'
+		);
+	});
+});
+
+describe('POST /admin/users/:id/disable', () => {
+	it('refuses to disable the caller', async () => {
+		const res = await request(makeApp('me')).post('/admin/users/me/disable');
+
+		expect(res.status).toBe(409);
+		expect(service.disableUserGuarded).not.toHaveBeenCalled();
+	});
+
+	it('answers 409 when the service reports the last active admin would be disabled', async () => {
+		service.loadAccess.mockResolvedValue({id: 'other', disabled: false, apps: ['admin']});
+		service.disableUserGuarded.mockResolvedValue('last-admin');
+
+		const res = await request(makeApp('me')).post('/admin/users/other/disable');
+
+		expect(res.status).toBe(409);
+	});
+
+	it('disables a non-admin user', async () => {
+		service.loadAccess.mockResolvedValue({id: 'other', disabled: false, apps: ['feedback']});
+
+		const res = await request(makeApp('me')).post('/admin/users/other/disable');
+
+		expect(res.status).toBe(200);
+		expect(service.disableUserGuarded).toHaveBeenCalledWith('other');
+	});
+
+	it('404s for an unknown user', async () => {
+		service.loadAccess.mockResolvedValue(null);
+
+		const res = await request(makeApp('me')).post('/admin/users/ghost/disable');
+
+		expect(res.status).toBe(404);
+	});
+});
+
+describe('DELETE /admin/users/:id/sessions/:sid', () => {
+	it('404s when the session does not belong to that user', async () => {
+		service.revokeSession.mockResolvedValue(false);
+
+		const res = await request(makeApp()).delete('/admin/users/other/sessions/s1');
+
+		expect(res.status).toBe(404);
+	});
+
+	it('204s on a successful revoke', async () => {
+		service.revokeSession.mockResolvedValue(true);
+
+		const res = await request(makeApp()).delete('/admin/users/other/sessions/s1');
+
+		expect(res.status).toBe(204);
+		expect(service.revokeSession).toHaveBeenCalledWith('other', 's1');
+	});
+});

test/calendar/credentials.service.test.ts

@@ -0,0 +1,49 @@
+import {describe, expect, it, beforeEach} from 'vitest';
+
+import * as CredentialService from '../../src/models/calendar/events/credentials.service.js';
+
+/**
+ * The public calendar is read anonymously by nachklang.art to show the next
+ * upcoming event. That is a load-bearing property, not an accident: the step 4
+ * cutover moved every signed-in path onto session cookies and left these shared
+ * passwords behind only for iCal subscriptions, and the failure mode of getting
+ * it wrong is the public website silently losing its events feed.
+ *
+ * So this pins both halves: public needs nothing, and the restricted calendars
+ * still need something.
+ */
+describe('hasAccess', () => {
+	beforeEach(() => {
+		process.env.MEMBER_CREDENTIAL = 'member-secret';
+		process.env.CHOIR_CREDENTIAL = 'choir-secret';
+		process.env.MANAGEMENT_CREDENTIAL = 'management-secret';
+	});
+
+	it('lets anyone read the public calendar with no password at all', async () => {
+		await expect(CredentialService.hasAccess('public', '')).resolves.toBe(true);
+	});
+
+	it.each([
+		['members', 'member-secret'],
+		['choir', 'choir-secret'],
+		['management', 'management-secret'],
+		['birthdays', 'choir-secret']
+	])('refuses %s without the credential and allows it with one', async (calendar, secret) => {
+		await expect(CredentialService.hasAccess(calendar, '')).resolves.toBe(false);
+		await expect(CredentialService.hasAccess(calendar, 'wrong')).resolves.toBe(false);
+		await expect(CredentialService.hasAccess(calendar, secret)).resolves.toBe(true);
+	});
+
+	it('refuses an unknown calendar outright', async () => {
+		await expect(CredentialService.hasAccess('nope', 'member-secret')).resolves.toBe(false);
+	});
+
+	it('refuses a calendar whose credential is not configured', async () => {
+		// An unset MEMBER_CREDENTIAL must not become "any password works", and in
+		// particular must not become "an absent password works".
+		delete process.env.MEMBER_CREDENTIAL;
+
+		await expect(CredentialService.hasAccess('members', '')).resolves.toBe(false);
+		await expect(CredentialService.hasAccess('members', undefined as any)).resolves.toBe(false);
+	});
+});

test/calendar/events.router.test.ts

@@ -0,0 +1,224 @@
+import {describe, expect, it, vi, beforeEach} from 'vitest';
+import express from 'express';
+import request from 'supertest';
+
+vi.mock('../../src/models/calendar/events/events.service.js', () => ({
+	getAllEvents: vi.fn(),
+	getAllEventsAdmin: vi.fn(),
+	getEventById: vi.fn(),
+	createEvent: vi.fn(),
+	updateEvent: vi.fn(),
+	deleteEvent: vi.fn(),
+	moveEvent: vi.fn(),
+	getNextUpcomingEvent: vi.fn()
+}));
+
+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 * as EventService from '../../src/models/calendar/events/events.service.js';
+import {auth} from '../../src/models/admin/admin.auth.js';
+import * as UsersService from '../../src/models/admin/users/users.admin.service.js';
+import {eventsRouter} from '../../src/models/calendar/events/events.router.js';
+
+/**
+ * Step 4 of docs/calendar-auth-migration.md at the route level. The unit test
+ * on credentials.service covers the password table; this covers the thing that
+ * table is wired into, which is where the interesting mistakes live:
+ *
+ *   - the public calendar has to stay readable with no session and no password,
+ *   - the shared password has to keep working for the restricted calendars,
+ *     because iCal clients cannot send a cookie,
+ *   - and every write has to be behind the session cookie *and* an explicit
+ *     calendar permission, not merely behind "is signed in".
+ */
+
+const app = express();
+app.use(express.json());
+app.use('/calendar/events', eventsRouter);
+
+const signedInAs = (apps: string[], disabled = false) => {
+	(auth.api.getSession as any).mockResolvedValue({user: {id: 'admin-1'}});
+	(UsersService.loadAccess as any).mockResolvedValue({
+		id: 'admin-1',
+		email: 'a@nachklang.art',
+		displayName: 'A',
+		disabled,
+		permissions: apps.map(app => ({app, role: 'access'})),
+		apps
+	});
+};
+
+const signedOut = () => {
+	(auth.api.getSession as any).mockResolvedValue(null);
+};
+
+const validEvent = {
+	calendarId: 1,
+	name: 'Konzert',
+	startDateTime: '2026-04-18T19:00:00Z',
+	endDateTime: '2026-04-18T21:00:00Z'
+};
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	process.env.MEMBER_CREDENTIAL = 'member-secret';
+	(EventService.getAllEvents as any).mockResolvedValue([]);
+	(EventService.getAllEventsAdmin as any).mockResolvedValue([]);
+	(EventService.getNextUpcomingEvent as any).mockResolvedValue({eventId: 1, name: 'Konzert'});
+	(EventService.createEvent as any).mockResolvedValue(1);
+	(EventService.updateEvent as any).mockResolvedValue(1);
+	(EventService.moveEvent as any).mockResolvedValue(true);
+	(EventService.deleteEvent as any).mockResolvedValue(true);
+	signedOut();
+});
+
+describe('reading', () => {
+	it('serves the public calendar anonymously', async () => {
+		// The property nachklang.art depends on. No cookie, no password.
+		await request(app).get('/calendar/events/public/json').expect(200);
+
+		// And as the non-admin view: an anonymous caller must not see drafts.
+		expect(EventService.getAllEvents).toHaveBeenCalled();
+		expect(EventService.getAllEventsAdmin).not.toHaveBeenCalled();
+	});
+
+	it('refuses a restricted calendar with neither session nor password', async () => {
+		await request(app).get('/calendar/events/members/json').expect(403);
+	});
+
+	it('serves a restricted calendar to a shared password, without drafts', async () => {
+		await request(app)
+			.get('/calendar/events/members/json')
+			.query({password: 'member-secret'})
+			.expect(200);
+
+		expect(EventService.getAllEvents).toHaveBeenCalled();
+		expect(EventService.getAllEventsAdmin).not.toHaveBeenCalled();
+	});
+
+	it('gives a signed-in editor the admin view instead', async () => {
+		signedInAs(['calendar']);
+
+		await request(app).get('/calendar/events/members/json').expect(200);
+
+		expect(EventService.getAllEventsAdmin).toHaveBeenCalled();
+		expect(EventService.getAllEvents).not.toHaveBeenCalled();
+	});
+
+	it('treats a signed-in user without the calendar permission as anonymous', async () => {
+		// Not a 403: they may still read the public calendar like anyone else.
+		signedInAs(['tickets']);
+
+		await request(app).get('/calendar/events/public/json').expect(200);
+		expect(EventService.getAllEvents).toHaveBeenCalled();
+		expect(EventService.getAllEventsAdmin).not.toHaveBeenCalled();
+
+		await request(app).get('/calendar/events/members/json').expect(403);
+	});
+
+	it('still serves the public calendar when the admin database is down', async () => {
+		(auth.api.getSession as any).mockRejectedValue(new Error('ECONNREFUSED'));
+
+		await request(app).get('/calendar/events/public/json').expect(200);
+	});
+
+	// The endpoint www.nachklang.art actually calls for its next-event teaser.
+	// Tested separately from /json because it takes a different code path - it
+	// has no admin view and no editor branch - so covering /json proves nothing
+	// about it, and its failure is invisible until someone notices the website
+	// has gone quiet.
+	it('serves the next upcoming event anonymously on the public calendar', async () => {
+		await request(app).get('/calendar/events/public/json/next').expect(200);
+
+		// And without asking the admin database who the caller is: the public
+		// feed must not acquire a dependency it has never had.
+		expect(auth.api.getSession).not.toHaveBeenCalled();
+	});
+
+	it('refuses the next upcoming event on a restricted calendar without a credential', async () => {
+		await request(app).get('/calendar/events/members/json/next').expect(403);
+	});
+
+	it('serves the next upcoming event to a shared password', async () => {
+		await request(app)
+			.get('/calendar/events/members/json/next')
+			.query({password: 'member-secret'})
+			.expect(200);
+	});
+
+	it('serves the next upcoming event to a signed-in editor', async () => {
+		signedInAs(['calendar']);
+
+		await request(app).get('/calendar/events/members/json/next').expect(200);
+	});
+
+	it('does not consult the admin database for the anonymous public iCal export', async () => {
+		await request(app).get('/calendar/events/public/ical').expect(200);
+
+		expect(auth.api.getSession).not.toHaveBeenCalled();
+	});
+
+	it('keeps the shared password working on the iCal export', async () => {
+		(EventService.getAllEvents as any).mockResolvedValue([]);
+
+		await request(app).get('/calendar/events/public/ical').expect(200);
+		await request(app).get('/calendar/events/members/ical').expect(403);
+		await request(app)
+			.get('/calendar/events/members/ical')
+			.query({password: 'member-secret'})
+			.expect(200);
+	});
+});
+
+describe('writing', () => {
+	it.each([
+		['post', '/calendar/events'],
+		['put', '/calendar/events/1'],
+		['put', '/calendar/events/move/1'],
+		['delete', '/calendar/events/1']
+	])('%s %s answers 401 when signed out', async (method, path) => {
+		await (request(app) as any)[method](path).send(validEvent).expect(401);
+	});
+
+	it.each([
+		['post', '/calendar/events'],
+		['put', '/calendar/events/1'],
+		['put', '/calendar/events/move/1'],
+		['delete', '/calendar/events/1']
+	])('%s %s answers 403 without the calendar permission', async (method, path) => {
+		signedInAs(['tickets', 'feedback', 'admin']);
+		await (request(app) as any)[method](path).send(validEvent).expect(403);
+	});
+
+	it('answers 403 for a disabled account that still holds the permission', async () => {
+		signedInAs(['calendar'], true);
+		await request(app).post('/calendar/events').send(validEvent).expect(403);
+	});
+
+	it('records the writer as an admin user id, never a legacy one', async () => {
+		signedInAs(['calendar']);
+
+		await request(app).post('/calendar/events').send(validEvent).expect(201);
+
+		const written = (EventService.createEvent as any).mock.calls[0][0];
+		expect(written.createdByUserId).toBe('admin-1');
+		// Migration 003 made the legacy column nullable precisely so this can be unset.
+		expect(written.createdById).toBeUndefined();
+	});
+
+	it('refuses the shared password as a way to write', async () => {
+		// The passwords are a read fallback for clients that cannot hold a
+		// session. They must never become an editing credential.
+		await request(app)
+			.post('/calendar/events')
+			.query({password: 'member-secret'})
+			.send(validEvent)
+			.expect(401);
+	});
+});

test/calendar/events.service.test.ts

@@ -0,0 +1,191 @@
+import {describe, expect, it, vi, beforeEach} from 'vitest';
+
+const connection = {
+	query: vi.fn(),
+	execute: vi.fn(),
+	beginTransaction: vi.fn(),
+	commit: vi.fn(),
+	rollback: vi.fn(),
+	end: vi.fn()
+};
+
+vi.mock('../../src/models/calendar/Calendar.db.js', () => ({
+	NachklangCalendarDB: {getConnection: vi.fn(async () => connection)}
+}));
+
+vi.mock('../../src/models/admin/users/users.admin.service.js', () => ({
+	findDisplayNames: vi.fn()
+}));
+
+import {NachklangCalendarDB} from '../../src/models/calendar/Calendar.db.js';
+import * as AdminUsersService from '../../src/models/admin/users/users.admin.service.js';
+import * as EventService from '../../src/models/calendar/events/events.service.js';
+
+/**
+ * Step 3 of docs/calendar-auth-migration.md. The property under test is that
+ * an event's creator resolves from whichever of its three possible sources is
+ * strongest - the live admin name, then the snapshot from migration 002, then
+ * the legacy join - and that a failure to reach the admin database costs a name
+ * rather than the whole response: the public calendar is read anonymously by
+ * the website and has never depended on the admin database being up.
+ */
+
+// One row of the shape the shared SELECT produces.
+const row = (over: Record<string, unknown> = {}) => ({
+	event_id: 1,
+	calendar_id: 1,
+	uuid: 'uuid-1',
+	name: 'Konzert',
+	description: '',
+	start_datetime: new Date('2026-04-18T19:00:00Z'),
+	end_datetime: new Date('2026-04-18T21:00:00Z'),
+	created_date: new Date('2026-01-01T00:00:00Z'),
+	version_created_at: new Date('2026-01-02T00:00:00Z'),
+	location: '',
+	created_by_id: 7,
+	created_by_user_id: null,
+	created_by_name: null,
+	legacy_created_by_name: 'Legacy Person',
+	version_created_by_id: 7,
+	version_created_by_user_id: null,
+	version_created_by_name: null,
+	legacy_last_modified_by_name: 'Legacy Person',
+	url: '',
+	whole_day: 0,
+	repeat_frequency: '',
+	status: 'PUBLIC',
+	...over
+});
+
+/** getAllEvents runs the calendars lookup first, then the events query. */
+const givenEvents = (...rows: unknown[]) => {
+	connection.query.mockReset();
+	connection.query
+		.mockResolvedValueOnce([{calendar_id: 1, includes_calendars: '[]'}])
+		.mockResolvedValueOnce(rows);
+};
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	connection.end.mockResolvedValue(undefined);
+	(NachklangCalendarDB.getConnection as any).mockResolvedValue(connection);
+});
+
+describe('creator names', () => {
+	it('uses the legacy join when the row has no admin id', async () => {
+		givenEvents(row());
+
+		const events = await EventService.getAllEvents(1);
+
+		expect(events[0].createdBy).toBe('Legacy Person');
+		expect(events[0].createdById).toBe(7);
+		expect(events[0].createdByUserId).toBeNull();
+		// Nothing to resolve, so the admin database is not touched at all.
+		expect(AdminUsersService.findDisplayNames).not.toHaveBeenCalled();
+	});
+
+	it('prefers the admin name when the row carries an admin id', async () => {
+		givenEvents(row({
+			created_by_user_id: 'admin-1',
+			version_created_by_user_id: 'admin-2'
+		}));
+		(AdminUsersService.findDisplayNames as any).mockResolvedValue(
+			new Map([['admin-1', 'Neue Person'], ['admin-2', 'Andere Person']])
+		);
+
+		const events = await EventService.getAllEvents(1);
+
+		expect(events[0].createdBy).toBe('Neue Person');
+		expect(events[0].lastModifiedBy).toBe('Andere Person');
+		// The legacy id is still reported during the transition.
+		expect(events[0].createdById).toBe(7);
+		expect(events[0].createdByUserId).toBe('admin-1');
+	});
+
+	it('prefers the snapshot over the legacy join', async () => {
+		givenEvents(row({
+			created_by_name: 'Archived Person',
+			version_created_by_name: 'Archived Person'
+		}));
+
+		const events = await EventService.getAllEvents(1);
+
+		expect(events[0].createdBy).toBe('Archived Person');
+		expect(events[0].lastModifiedBy).toBe('Archived Person');
+	});
+
+	it('prefers the live admin name over the snapshot', async () => {
+		// A renamed account has to win over an archive that was correct when it
+		// was taken - otherwise renaming someone would leave stale names behind.
+		givenEvents(row({created_by_user_id: 'admin-1', created_by_name: 'Archived Person'}));
+		(AdminUsersService.findDisplayNames as any).mockResolvedValue(new Map([['admin-1', 'Neue Person']]));
+
+		const events = await EventService.getAllEvents(1);
+
+		expect(events[0].createdBy).toBe('Neue Person');
+	});
+
+	it('keeps the snapshot when step 5 has removed the legacy join', async () => {
+		// What a post-step-5 row looks like: no legacy id, no join, snapshot only.
+		givenEvents(row({
+			created_by_id: null,
+			legacy_created_by_name: undefined,
+			legacy_last_modified_by_name: undefined,
+			created_by_name: 'Archived Person',
+			version_created_by_name: 'Archived Person'
+		}));
+
+		const events = await EventService.getAllEvents(1);
+
+		expect(events[0].createdBy).toBe('Archived Person');
+		expect(events[0].lastModifiedBy).toBe('Archived Person');
+	});
+
+	it('falls back to the legacy name when the admin account is gone', async () => {
+		givenEvents(row({created_by_user_id: 'deleted'}));
+		(AdminUsersService.findDisplayNames as any).mockResolvedValue(new Map());
+
+		const events = await EventService.getAllEvents(1);
+
+		expect(events[0].createdBy).toBe('Legacy Person');
+	});
+
+	it('resolves a mixed result set in a single lookup', async () => {
+		givenEvents(
+			row({event_id: 1}),
+			row({event_id: 2, created_by_user_id: 'admin-1', version_created_by_user_id: 'admin-1'}),
+			row({event_id: 3, created_by_user_id: 'admin-1', version_created_by_user_id: 'admin-1'})
+		);
+		(AdminUsersService.findDisplayNames as any).mockResolvedValue(new Map([['admin-1', 'Neue Person']]));
+
+		const events = await EventService.getAllEvents(1);
+
+		expect(events.map(e => e.createdBy)).toEqual(['Legacy Person', 'Neue Person', 'Neue Person']);
+		expect(AdminUsersService.findDisplayNames).toHaveBeenCalledTimes(1);
+	});
+
+	it('still returns the events when the admin database is unreachable', async () => {
+		givenEvents(row({created_by_user_id: 'admin-1'}));
+		(AdminUsersService.findDisplayNames as any).mockRejectedValue(new Error('ECONNREFUSED'));
+
+		const events = await EventService.getAllEvents(1);
+
+		expect(events).toHaveLength(1);
+		expect(events[0].name).toBe('Konzert');
+		// Degrades to the legacy name rather than failing the request.
+		expect(events[0].createdBy).toBe('Legacy Person');
+	});
+});
+
+describe('status', () => {
+	it('is omitted from the public listing and present in the admin one', async () => {
+		givenEvents(row());
+		const publicEvents = await EventService.getAllEvents(1);
+		expect(publicEvents[0].status).toBeUndefined();
+
+		connection.query.mockReset();
+		connection.query.mockResolvedValueOnce([row()]);
+		const adminEvents = await EventService.getAllEventsAdmin(1);
+		expect(adminEvents[0].status).toBe('PUBLIC');
+	});
+});

test/feedback/feedback.auth.test.ts

@@ -1,88 +1,23 @@
-import {vi, describe, it, expect, beforeEach, type Mock} from 'vitest';
-import {Request, Response} from 'express';
+import {vi, type Mock} from 'vitest';
 
 vi.mock('../../src/models/calendar/users/users.service.js', () => ({
 	checkSession: vi.fn()
 }));
+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 * as UserService from '../../src/models/calendar/users/users.service.js';
-import {requireAdminAuth, sessionHeaderAuthenticator} from '../../src/models/feedback/feedback.auth.js';
+import {auth} from '../../src/models/admin/admin.auth.js';
+import * as UsersService from '../../src/models/admin/users/users.admin.service.js';
+import {requireAdminAuth} from '../../src/models/feedback/feedback.auth.js';
+import {describeAdminBinding} from '../admin/auth-binding.js';
 
-const mockCheckSession = UserService.checkSession as Mock;
-
-const makeReq = (headers: Record<string, string>): Request => {
-	return {
-		header: (name: string) => headers[name],
-		ip: '203.0.113.42'
-	} 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;
-};
-
-describe('sessionHeaderAuthenticator', () => {
-	beforeEach(() => mockCheckSession.mockReset());
-
-	it('returns null when headers are missing', async () => {
-		const identity = await sessionHeaderAuthenticator(makeReq({}));
-		expect(identity).toBeNull();
-		expect(mockCheckSession).not.toHaveBeenCalled();
-	});
-
-	it('returns null when checkSession finds no user', async () => {
-		mockCheckSession.mockResolvedValue(null);
-		const identity = await sessionHeaderAuthenticator(makeReq({'X-Session-Id': '1', 'X-Session-Key': 'k'}));
-		expect(identity).toBeNull();
-	});
-
-	it('returns null for a valid session on an inactive account', async () => {
-		mockCheckSession.mockResolvedValue({userId: 1, email: 'a@nachklang.art', fullName: 'A', isActive: false});
-		const identity = await sessionHeaderAuthenticator(makeReq({'X-Session-Id': '1', 'X-Session-Key': 'k'}));
-		expect(identity).toBeNull();
-	});
-
-	it('returns the identity for a valid session on an active account', async () => {
-		mockCheckSession.mockResolvedValue({userId: 1, email: 'a@nachklang.art', fullName: 'Anna Admin', isActive: true});
-		const identity = await sessionHeaderAuthenticator(makeReq({'X-Session-Id': '1', 'X-Session-Key': 'k'}));
-		expect(identity).toEqual({id: '1', email: 'a@nachklang.art', displayName: 'Anna Admin'});
-	});
-
-	it('passes the session id and key from headers through to checkSession, never from query params', async () => {
-		mockCheckSession.mockResolvedValue({userId: 1, email: 'a@nachklang.art', fullName: 'A', isActive: true});
-		await sessionHeaderAuthenticator(makeReq({'X-Session-Id': '42', 'X-Session-Key': 'sekret'}));
-		expect(mockCheckSession).toHaveBeenCalledWith('42', 'sekret', '203.0.113.42');
-	});
-});
-
-describe('requireAdminAuth', () => {
-	beforeEach(() => mockCheckSession.mockReset());
-
-	it('responds 401 and does not call next() when unauthenticated', async () => {
-		mockCheckSession.mockResolvedValue(null);
-		const req = makeReq({});
-		const res = makeRes();
-		const next = vi.fn();
-
-		await requireAdminAuth(req, res, next);
-
-		expect(res.status).toHaveBeenCalledWith(401);
-		expect(next).not.toHaveBeenCalled();
-	});
-
-	it('sets res.locals.admin and calls next() when authenticated', async () => {
-		mockCheckSession.mockResolvedValue({userId: 1, email: 'a@nachklang.art', fullName: 'Anna Admin', isActive: true});
-		const req = makeReq({'X-Session-Id': '1', 'X-Session-Key': 'k'});
-		const res = makeRes();
-		const next = vi.fn();
-
-		await requireAdminAuth(req, res, next);
-
-		expect(next).toHaveBeenCalled();
-		expect(res.locals.admin).toEqual({id: '1', email: 'a@nachklang.art', displayName: 'Anna Admin'});
-	});
-});
+describeAdminBinding('feedback', 'tickets', requireAdminAuth, () => ({
+	getSession: auth.api.getSession as unknown as Mock,
+	loadAccess: UsersService.loadAccess as Mock,
+	checkSession: UserService.checkSession as Mock
+}));

test/integration/admin.auth.test.ts

@@ -0,0 +1,289 @@
+import {describe, it, expect, beforeAll, beforeEach, afterAll} from 'vitest';
+import request from 'supertest';
+import type {Application} from 'express';
+import {createApp} from '../../src/app.factory.js';
+import * as InvitationsService from '../../src/models/admin/invitations/invitations.service.js';
+import * as UsersService from '../../src/models/admin/users/users.admin.service.js';
+import {
+	closeDatabase,
+	createAndAcceptInvitation,
+	resetDatabase,
+	sessionCookieFrom,
+	SESSION_COOKIE,
+	accessTo
+} from './helpers.js';
+
+/**
+ * End-to-end against a real MariaDB (docker-compose.test.yml) and the real
+ * Express wiring from app.factory.ts. Mocks would not catch what this module
+ * can actually get wrong: the Kysely MySQL dialect, cookie attributes, and the
+ * middleware order that lets better-auth read the raw request body.
+ */
+
+let app: Application;
+
+beforeAll(() => {
+	app = createApp();
+});
+
+beforeEach(async () => {
+	await resetDatabase();
+});
+
+afterAll(async () => {
+	await closeDatabase();
+});
+
+describe('sign-up is closed', () => {
+	it('refuses the public sign-up endpoint', async () => {
+		const res = await request(app)
+			.post('/admin/auth/sign-up/email')
+			.send({email: 'stranger@example.com', password: 'password123', name: 'Stranger'});
+
+		expect(res.status).toBeGreaterThanOrEqual(400);
+		expect(await UsersService.findUserByEmail('stranger@example.com')).toBeNull();
+	});
+});
+
+describe('invitation acceptance', () => {
+	it('creates the user, its permissions and a session cookie', async () => {
+		const {agent, userId} = await createAndAcceptInvitation(
+			app,
+			'anna@nachklang.art',
+			'Anna',
+			['feedback', 'tickets']
+		);
+
+		const access = await UsersService.loadAccess(userId);
+		expect(access?.email).toBe('anna@nachklang.art');
+		expect(access?.apps.sort()).toEqual(['feedback', 'tickets']);
+		expect(access?.disabled).toBe(false);
+
+		// The cookie works on a subsequent request.
+		const me = await agent.get('/admin/me');
+		expect(me.status).toBe(200);
+		expect(me.body.email).toBe('anna@nachklang.art');
+		expect(me.body.apps.sort()).toEqual(['feedback', 'tickets']);
+	});
+
+	it('sets the session cookie under the configured prefix', async () => {
+		const invitation = await InvitationsService.createInvitation('b@nachklang.art', 'B', accessTo('feedback'), null);
+
+		const res = await request(app)
+			.post('/admin/auth/invitations/accept')
+			.send({token: invitation.token, password: 'devpassword123'});
+
+		const cookie = sessionCookieFrom(res);
+		expect(cookie).toBeDefined();
+		expect(cookie).toContain('HttpOnly');
+	});
+
+	it('lets the new account sign in with the password it just set', async () => {
+		await createAndAcceptInvitation(app, 'c@nachklang.art', 'C', ['feedback'], 'my-password-1');
+
+		const res = await request(app)
+			.post('/admin/auth/sign-in/email')
+			.send({email: 'c@nachklang.art', password: 'my-password-1'});
+
+		expect(res.status).toBe(200);
+		expect(sessionCookieFrom(res)).toBeDefined();
+	});
+
+	it('previews an invitation without revealing the granted apps', async () => {
+		const invitation = await InvitationsService.createInvitation('d@nachklang.art', 'D', accessTo('admin'), null);
+
+		const res = await request(app)
+			.post('/admin/auth/invitations/preview')
+			.send({token: invitation.token});
+
+		expect(res.status).toBe(200);
+		expect(res.body).toEqual({email: 'd@nachklang.art', name: 'D'});
+	});
+
+	it('answers an unknown token exactly like an expired one', async () => {
+		const invitation = await InvitationsService.createInvitation('e@nachklang.art', 'E', accessTo('feedback'), null);
+		await InvitationsService.revokeInvitation(invitation.id);
+
+		const unknown = await request(app).post('/admin/auth/invitations/preview').send({token: 'no-such-token'});
+		const revoked = await request(app).post('/admin/auth/invitations/preview').send({token: invitation.token});
+
+		expect(unknown.status).toBe(revoked.status);
+		expect(unknown.body).toEqual(revoked.body);
+	});
+
+	it('cannot be redeemed twice', async () => {
+		const invitation = await InvitationsService.createInvitation('f@nachklang.art', 'F', accessTo('feedback'), null);
+
+		const first = await request(app)
+			.post('/admin/auth/invitations/accept')
+			.send({token: invitation.token, password: 'devpassword123'});
+		const second = await request(app)
+			.post('/admin/auth/invitations/accept')
+			.send({token: invitation.token, password: 'devpassword123'});
+
+		expect(first.status).toBe(200);
+		expect(second.status).toBeGreaterThanOrEqual(400);
+	});
+
+	it('rejects an expired invitation', async () => {
+		const invitation = await InvitationsService.createInvitation('g@nachklang.art', 'G', accessTo('feedback'), null);
+		// Reach past the service to age it: there is deliberately no API for this.
+		const {NachklangAdminDB} = await import('../../src/models/admin/Admin.db.js');
+		await NachklangAdminDB.db
+			.updateTable('invitations')
+			.set({expires_at: new Date(Date.now() - 1000)})
+			.where('id', '=', invitation.id)
+			.execute();
+
+		const res = await request(app)
+			.post('/admin/auth/invitations/accept')
+			.send({token: invitation.token, password: 'devpassword123'});
+
+		expect(res.status).toBeGreaterThanOrEqual(400);
+	});
+
+	it('rejects a password below the minimum length', async () => {
+		const invitation = await InvitationsService.createInvitation('h@nachklang.art', 'H', accessTo('feedback'), null);
+
+		const res = await request(app)
+			.post('/admin/auth/invitations/accept')
+			.send({token: invitation.token, password: 'short'});
+
+		expect(res.status).toBeGreaterThanOrEqual(400);
+		expect(await UsersService.findUserByEmail('h@nachklang.art')).toBeNull();
+	});
+});
+
+describe('sessions', () => {
+	it('signs out and stops accepting the cookie', async () => {
+		const {agent} = await createAndAcceptInvitation(app, 'i@nachklang.art', 'I', ['feedback']);
+
+		expect((await agent.get('/admin/me')).status).toBe(200);
+
+		const signOut = await agent.post('/admin/auth/sign-out').send({});
+		expect(signOut.status).toBe(200);
+
+		expect((await agent.get('/admin/me')).status).toBe(401);
+	});
+
+	it('rejects a disabled user who still holds a valid cookie', async () => {
+		const {agent, userId} = await createAndAcceptInvitation(app, 'j@nachklang.art', 'J', ['feedback']);
+
+		// Strip the permission check out of the picture: disable without going
+		// through disableUser's session revocation, so the cookie stays live.
+		const {NachklangAdminDB} = await import('../../src/models/admin/Admin.db.js');
+		await NachklangAdminDB.db.updateTable('user').set({disabled: true}).where('id', '=', userId).execute();
+
+		const res = await agent.get('/admin/me');
+		expect(res.status).toBe(403);
+	});
+
+	it('disabling a user revokes their sessions immediately', async () => {
+		const {agent, userId} = await createAndAcceptInvitation(app, 'k@nachklang.art', 'K', ['feedback']);
+
+		await UsersService.disableUser(userId);
+
+		const res = await agent.get('/admin/me');
+		expect(res.status).toBe(401);
+	});
+
+	it('refuses to sign a disabled user back in', async () => {
+		const {userId} = await createAndAcceptInvitation(app, 'l@nachklang.art', 'L', ['feedback'], 'my-password-1');
+		await UsersService.disableUser(userId);
+
+		const res = await request(app)
+			.post('/admin/auth/sign-in/email')
+			.send({email: 'l@nachklang.art', password: 'my-password-1'});
+
+		expect(res.status).toBeGreaterThanOrEqual(400);
+		expect(sessionCookieFrom(res)).toBeUndefined();
+	});
+});
+
+describe('requireAppAccess', () => {
+	it('401s an anonymous request', async () => {
+		expect((await request(app).get('/admin/me')).status).toBe(401);
+		expect((await request(app).get('/admin/users')).status).toBe(401);
+	});
+
+	it('403s a signed-in user without the admin permission', async () => {
+		const {agent} = await createAndAcceptInvitation(app, 'm@nachklang.art', 'M', ['feedback']);
+
+		const res = await agent.get('/admin/users');
+		expect(res.status).toBe(403);
+	});
+
+	it('lets an admin through', async () => {
+		const {agent} = await createAndAcceptInvitation(app, 'n@nachklang.art', 'N', ['admin']);
+
+		const res = await agent.get('/admin/users');
+		expect(res.status).toBe(200);
+		expect(Array.isArray(res.body)).toBe(true);
+	});
+
+	// The step 4 cutover (2026-09-06): the feedback and tickets admin areas now
+	// sit behind this same gate, so one sign-in reaches every app the user has a
+	// permission for - and reaches no further. Until step 4 these two returned
+	// 401 for an admin cookie, because each module still ran its own header
+	// session against the calendar users table.
+	it('lets an admin cookie into the feedback and tickets admin areas', async () => {
+		const user = await createAndAcceptInvitation(app, 'o@nachklang.art', 'O', ['feedback', 'tickets']);
+
+		expect((await user.agent.get('/feedback/admin/me')).status).toBe(200);
+		expect((await user.agent.get('/tickets/admin/me')).status).toBe(200);
+	});
+
+	it('403s each app separately for a user who only holds the other one', async () => {
+		const user = await createAndAcceptInvitation(app, 'q@nachklang.art', 'Q', ['feedback']);
+
+		expect((await user.agent.get('/feedback/admin/me')).status).toBe(200);
+		expect((await user.agent.get('/tickets/admin/me')).status).toBe(403);
+	});
+
+	it('401s the feedback and tickets admin areas for a legacy header session', async () => {
+		const res = await request(app)
+			.get('/feedback/admin/me')
+			.set('X-Session-Id', '1')
+			.set('X-Session-Key', 'whatever');
+
+		expect(res.status).toBe(401);
+	});
+});
+
+describe('origin checks', () => {
+	it('rejects a cookie-bearing request from an untrusted origin', async () => {
+		const {agent} = await createAndAcceptInvitation(app, 'p@nachklang.art', 'P', ['admin']);
+
+		const res = await agent
+			.post('/admin/auth/sign-out')
+			.set('Origin', 'https://evil.example')
+			.send({});
+
+		expect(res.status).toBeGreaterThanOrEqual(400);
+	});
+
+	it('accepts the admin app origin', async () => {
+		const {agent} = await createAndAcceptInvitation(app, 'q@nachklang.art', 'Q', ['admin']);
+
+		const res = await agent
+			.post('/admin/auth/sign-out')
+			.set('Origin', 'http://localhost:3002')
+			.send({});
+
+		expect(res.status).toBe(200);
+	});
+});
+
+describe('the session cookie is not readable by scripts', () => {
+	it('is HttpOnly and SameSite=Lax', async () => {
+		const invitation = await InvitationsService.createInvitation('r@nachklang.art', 'R', accessTo('feedback'), null);
+		const res = await request(app)
+			.post('/admin/auth/invitations/accept')
+			.send({token: invitation.token, password: 'devpassword123'});
+
+		const cookie = sessionCookieFrom(res) || '';
+		expect(cookie).toContain(SESSION_COOKIE);
+		expect(cookie).toContain('HttpOnly');
+		expect(cookie.toLowerCase()).toContain('samesite=lax');
+	});
+});

test/integration/admin.users.test.ts

@@ -0,0 +1,255 @@
+import {describe, it, expect, beforeAll, beforeEach, afterAll} from 'vitest';
+import request from 'supertest';
+import type {Application} from 'express';
+import {createApp} from '../../src/app.factory.js';
+import * as InvitationsService from '../../src/models/admin/invitations/invitations.service.js';
+import * as UsersService from '../../src/models/admin/users/users.admin.service.js';
+import {bootstrapAdmin} from '../../src/models/admin/admin.bootstrap.js';
+import {accessTo, closeDatabase, createAndAcceptInvitation, resetDatabase} from './helpers.js';
+
+let app: Application;
+
+beforeAll(() => {
+	app = createApp();
+});
+
+beforeEach(async () => {
+	await resetDatabase();
+});
+
+afterAll(async () => {
+	await closeDatabase();
+});
+
+/** Most tests here need somebody who may administer. */
+const signedInAdmin = async (email = 'admin@nachklang.art') => {
+	return createAndAcceptInvitation(app, email, 'Admin', ['admin']);
+};
+
+describe('GET /admin/users', () => {
+	it('lists users with their permissions and derived status', async () => {
+		const {agent} = await signedInAdmin();
+		await createAndAcceptInvitation(app, 'user@nachklang.art', 'User', ['feedback']);
+
+		const res = await agent.get('/admin/users');
+
+		expect(res.status).toBe(200);
+		const listed = res.body.find((u: any) => u.email === 'user@nachklang.art');
+		expect(listed.apps).toEqual(['feedback']);
+		expect(listed.status).toBe('aktiv');
+		expect(listed.lastSignInAt).not.toBeNull();
+	});
+
+	it('shows a disabled user as deaktiviert', async () => {
+		const {agent} = await signedInAdmin();
+		const other = await createAndAcceptInvitation(app, 'user@nachklang.art', 'User', ['feedback']);
+		await UsersService.disableUser(other.userId);
+
+		const res = await agent.get('/admin/users');
+		const listed = res.body.find((u: any) => u.email === 'user@nachklang.art');
+		expect(listed.status).toBe('deaktiviert');
+	});
+});
+
+describe('GET /admin/users/:id', () => {
+	it('returns active sessions and the passkey count', async () => {
+		const {agent} = await signedInAdmin();
+		const other = await createAndAcceptInvitation(app, 'user@nachklang.art', 'User', ['feedback']);
+
+		const res = await agent.get(`/admin/users/${other.userId}`);
+
+		expect(res.status).toBe(200);
+		expect(res.body.sessions.length).toBe(1);
+		expect(res.body.passkeyCount).toBe(0);
+	});
+
+	it('404s for an unknown id', async () => {
+		const {agent} = await signedInAdmin();
+		expect((await agent.get('/admin/users/does-not-exist')).status).toBe(404);
+	});
+});
+
+describe('permission changes', () => {
+	it('replaces the permission set', async () => {
+		const {agent} = await signedInAdmin();
+		const other = await createAndAcceptInvitation(app, 'user@nachklang.art', 'User', ['feedback']);
+
+		const res = await agent
+			.put(`/admin/users/${other.userId}/permissions`)
+			.send({apps: ['tickets', 'calendar']});
+
+		expect(res.status).toBe(200);
+		const access = await UsersService.loadAccess(other.userId);
+		expect(access?.apps.sort()).toEqual(['calendar', 'tickets']);
+	});
+
+	it('takes effect on the next request the affected user makes', async () => {
+		const {agent} = await signedInAdmin();
+		const other = await createAndAcceptInvitation(app, 'user@nachklang.art', 'User', ['admin']);
+
+		expect((await other.agent.get('/admin/users')).status).toBe(200);
+
+		await agent.put(`/admin/users/${other.userId}/permissions`).send({apps: ['feedback']});
+
+		// No cookie cache: the very next request is already denied, on the same
+		// still-valid session cookie.
+		expect((await other.agent.get('/admin/users')).status).toBe(403);
+	});
+
+	it('refuses to strip the last admin', async () => {
+		const {agent, userId} = await signedInAdmin();
+
+		const res = await agent.put(`/admin/users/${userId}/permissions`).send({apps: ['feedback']});
+
+		expect(res.status).toBe(409);
+		expect((await UsersService.loadAccess(userId))?.apps).toContain('admin');
+	});
+
+	it('refuses to disable the caller themselves', async () => {
+		const {agent, userId} = await signedInAdmin();
+
+		const res = await agent.post(`/admin/users/${userId}/disable`);
+
+		expect(res.status).toBe(409);
+		expect((await UsersService.loadAccess(userId))?.disabled).toBe(false);
+	});
+
+	it('allows disabling a second admin', async () => {
+		const {agent} = await signedInAdmin();
+		const second = await createAndAcceptInvitation(app, 'admin2@nachklang.art', 'Admin2', ['admin']);
+
+		expect((await agent.post(`/admin/users/${second.userId}/disable`)).status).toBe(200);
+		expect((await second.agent.get('/admin/me')).status).toBe(401);
+	});
+
+	it('re-enables a disabled user without restoring their old sessions', async () => {
+		const {agent} = await signedInAdmin();
+		const other = await createAndAcceptInvitation(app, 'user@nachklang.art', 'User', ['feedback']);
+		await agent.post(`/admin/users/${other.userId}/disable`);
+
+		expect((await agent.post(`/admin/users/${other.userId}/enable`)).status).toBe(200);
+		expect((await UsersService.loadAccess(other.userId))?.disabled).toBe(false);
+		// The revoked session stays revoked; they sign in again.
+		expect((await other.agent.get('/admin/me')).status).toBe(401);
+	});
+});
+
+describe('session revocation', () => {
+	it('revokes one session of another user', async () => {
+		const {agent} = await signedInAdmin();
+		const other = await createAndAcceptInvitation(app, 'user@nachklang.art', 'User', ['feedback']);
+
+		const detail = await agent.get(`/admin/users/${other.userId}`);
+		const sessionId = detail.body.sessions[0].id;
+
+		const res = await agent.delete(`/admin/users/${other.userId}/sessions/${sessionId}`);
+		expect(res.status).toBe(204);
+
+		expect((await other.agent.get('/admin/me')).status).toBe(401);
+	});
+});
+
+describe('invitations', () => {
+	it('creates one and lists it as open', async () => {
+		const {agent} = await signedInAdmin();
+
+		const created = await agent
+			.post('/admin/invitations')
+			.send({email: 'new@nachklang.art', name: 'New', apps: ['feedback']});
+
+		expect(created.status).toBe(201);
+		// Mail is disabled in tests, and the token must never be returned.
+		expect(created.body.token).toBeUndefined();
+
+		const list = await agent.get('/admin/invitations');
+		expect(list.body.map((i: any) => i.email)).toContain('new@nachklang.art');
+	});
+
+	it('refuses to invite an address that already has an account', async () => {
+		const {agent} = await signedInAdmin();
+		await createAndAcceptInvitation(app, 'user@nachklang.art', 'User', ['feedback']);
+
+		const res = await agent
+			.post('/admin/invitations')
+			.send({email: 'user@nachklang.art', name: 'User', apps: ['feedback']});
+
+		expect(res.status).toBe(409);
+	});
+
+	it('rejects an invalid email or app name', async () => {
+		const {agent} = await signedInAdmin();
+
+		expect((await agent.post('/admin/invitations').send({email: 'nope', name: 'X', apps: []})).status).toBe(400);
+		expect((await agent.post('/admin/invitations').send({email: 'a@b.de', name: 'X', apps: ['nope']})).status).toBe(400);
+	});
+
+	it('invalidates the previous link on resend', async () => {
+		const {agent} = await signedInAdmin();
+		const original = await InvitationsService.createInvitation('new@nachklang.art', 'New', accessTo('feedback'), null);
+
+		const resent = await agent.post(`/admin/invitations/${original.id}/resend`);
+		expect(resent.status).toBe(200);
+
+		const oldLink = await request(app)
+			.post('/admin/auth/invitations/preview')
+			.send({token: original.token});
+		expect(oldLink.status).toBeGreaterThanOrEqual(400);
+	});
+
+	it('revokes an invitation', async () => {
+		const {agent} = await signedInAdmin();
+		const invitation = await InvitationsService.createInvitation('new@nachklang.art', 'New', accessTo('feedback'), null);
+
+		expect((await agent.delete(`/admin/invitations/${invitation.id}`)).status).toBe(204);
+		expect((await agent.delete(`/admin/invitations/${invitation.id}`)).status).toBe(404);
+
+		const preview = await request(app)
+			.post('/admin/auth/invitations/preview')
+			.send({token: invitation.token});
+		expect(preview.status).toBeGreaterThanOrEqual(400);
+	});
+});
+
+describe('bootstrap', () => {
+	it('creates an admin invitation on an empty database', async () => {
+		await bootstrapAdmin();
+
+		expect(await InvitationsService.hasOpenInvitationFor('boot@nachklang.art')).toBe(true);
+	});
+
+	it('is idempotent across restarts', async () => {
+		await bootstrapAdmin();
+		await bootstrapAdmin();
+
+		const open = await InvitationsService.listOpenInvitations();
+		expect(open.filter(i => i.email === 'boot@nachklang.art').length).toBe(1);
+	});
+
+	it('grants admin to an address that already has an account', async () => {
+		const user = await createAndAcceptInvitation(app, 'boot@nachklang.art', 'Boot', ['feedback']);
+
+		await bootstrapAdmin();
+
+		expect((await UsersService.loadAccess(user.userId))?.apps).toContain('admin');
+	});
+
+	it('does nothing once an active admin exists', async () => {
+		await signedInAdmin();
+
+		await bootstrapAdmin();
+
+		expect(await InvitationsService.hasOpenInvitationFor('boot@nachklang.art')).toBe(false);
+	});
+});
+
+describe('passkey endpoints', () => {
+	it('requires a session to list passkeys', async () => {
+		const anonymous = await request(app).get('/admin/auth/passkey/list-user-passkeys');
+		expect(anonymous.status).toBeGreaterThanOrEqual(400);
+
+		const {agent} = await signedInAdmin();
+		const res = await agent.get('/admin/auth/passkey/list-user-passkeys');
+		expect(res.status).toBe(200);
+		expect(res.body).toEqual([]);
+	});
+});

test/integration/helpers.ts

@@ -0,0 +1,77 @@
+import {expect} from 'vitest';
+import type {Application} from 'express';
+import request from 'supertest';
+import {NachklangAdminDB} from '../../src/models/admin/Admin.db.js';
+import * as InvitationsService from '../../src/models/admin/invitations/invitations.service.js';
+import {ACCESS_ROLE, AppName, AppPermission, toPermissions} from '../../src/models/admin/admin.schema.js';
+
+const db = NachklangAdminDB.db;
+
+// Dev/test cookie name: advanced.cookiePrefix is 'nachklang', and the __Secure-
+// prefix is only added over https.
+export const SESSION_COOKIE = 'nachklang.session_token';
+
+/**
+ * Wipes every table between test files. Child tables first - the FKs to `user`
+ * are ON DELETE CASCADE, but the rest are not.
+ *
+ * `rateLimit` matters more than it looks: the limiter is enabled during the
+ * suite, and better-auth caps /sign-in/* at 3 requests per 10 seconds. All
+ * tests resolve to the same client IP, so they share one bucket - without this
+ * reset the suite would start failing with 429s that look like auth bugs as
+ * soon as a third sign-in assertion is added.
+ */
+export const resetDatabase = async (): Promise<void> => {
+	await db.deleteFrom('session').execute();
+	await db.deleteFrom('user_app_permissions').execute();
+	await db.deleteFrom('passkey').execute();
+	await db.deleteFrom('invitations').execute();
+	await db.deleteFrom('verification').execute();
+	await db.deleteFrom('rateLimit').execute();
+	await db.deleteFrom('user').execute();
+};
+
+export const closeDatabase = async (): Promise<void> => {
+	await db.destroy();
+};
+
+/**
+ * Creates an invitation straight through the service (so the test gets the raw
+ * token, which the API deliberately never returns) and redeems it through the
+ * public endpoint. Returns an agent that carries the resulting session cookie.
+ */
+export const createAndAcceptInvitation = async (
+	app: Application,
+	email: string,
+	name: string,
+	// Takes the shorthand as well as the full form: most tests only care that
+	// someone can open an app, and `['tickets']` says that with less noise.
+	grants: (AppName | AppPermission)[],
+	password = 'devpassword123'
+) => {
+	const permissions = toPermissions(grants) ?? [];
+	const invitation = await InvitationsService.createInvitation(email, name, permissions, null);
+
+	const agent = request.agent(app);
+	const res = await agent
+		.post('/admin/auth/invitations/accept')
+		.send({token: invitation.token, password});
+
+	expect(res.status).toBe(200);
+	return {agent, userId: res.body.user.id, token: invitation.token};
+};
+
+export const cookieHeader = (res: request.Response): string[] => {
+	const raw = res.headers['set-cookie'];
+	return Array.isArray(raw) ? raw : raw ? [raw] : [];
+};
+
+export const sessionCookieFrom = (res: request.Response): string | undefined => {
+	return cookieHeader(res).find(cookie => cookie.startsWith(SESSION_COOKIE));
+};
+
+/** `accessTo('feedback')` reads better than the (app, role) literal in tests
+ *  that only care that someone can open an app. */
+export const accessTo = (...apps: AppName[]): AppPermission[] => {
+	return apps.map(app => ({app, role: ACCESS_ROLE}));
+};

test/integration/setup.ts

@@ -0,0 +1,107 @@
+import {execFile} from 'child_process';
+import {promisify} from 'util';
+import {createRequire} from 'module';
+
+const run = promisify(execFile);
+const require = createRequire(import.meta.url);
+
+/**
+ * vitest globalSetup for the admin integration tests: starts a throwaway
+ * MariaDB before the suite and removes it afterwards, so a run leaves nothing
+ * behind and never touches a shared database.
+ *
+ * The container is started directly rather than through compose, because
+ * `podman compose` needs a separate compose provider that neither podman nor
+ * docker ships. One container needs no orchestration, and this works with
+ * whichever of the two runtimes is installed.
+ */
+
+export const CONTAINER_NAME = 'nachklang-admin-test-db';
+export const TEST_DB_PORT = 3307;
+
+const IMAGE = 'docker.io/library/mariadb:11';
+
+const runtime = async (): Promise<string> => {
+	for (const candidate of ['docker', 'podman']) {
+		try {
+			await run(candidate, ['info'], {timeout: 60_000});
+			return candidate;
+		} catch {
+			// Not installed, or its daemon/machine is not running - try the next.
+		}
+	}
+	throw new Error(
+		'The admin integration tests need a container runtime. Install docker or podman ' +
+		'(with podman: `podman machine start`), then re-run npm run test:integration.'
+	);
+};
+
+/**
+ * Ready means "the entrypoint has applied 001_init.sql", not just "the port
+ * answers": MariaDB accepts connections while it is still running its init
+ * scripts, and a test that started then would fail on a missing table.
+ */
+const waitForSchema = async (): Promise<void> => {
+	const mysql = require('mysql2/promise');
+	const deadline = Date.now() + 120_000;
+	let lastError: unknown;
+
+	while (Date.now() < deadline) {
+		try {
+			const connection = await mysql.createConnection({
+				host: '127.0.0.1',
+				port: TEST_DB_PORT,
+				user: 'nachklang',
+				password: 'testpassword',
+				database: 'nachklang_admin',
+				connectTimeout: 5_000
+			});
+			const [rows] = await connection.query(
+				"SELECT COUNT(*) AS n FROM information_schema.tables " +
+				"WHERE table_schema = 'nachklang_admin' AND table_name IN ('user', 'user_app_permissions', 'invitations')"
+			);
+			await connection.end();
+			if (Number((rows as any[])[0]?.n) === 3) {
+				return;
+			}
+			lastError = new Error('schema not applied yet');
+		} catch (e) {
+			lastError = e;
+		}
+		await new Promise(resolve => setTimeout(resolve, 1_000));
+	}
+
+	throw new Error(`Test database never became ready: ${(lastError as any)?.message}`);
+};
+
+export const setup = async () => {
+	const engine = await runtime();
+
+	// A container left behind by an interrupted run would still hold the old
+	// schema and rows, so always start from scratch.
+	await run(engine, ['rm', '-f', CONTAINER_NAME], {timeout: 60_000}).catch(() => undefined);
+
+	await run(engine, [
+		'run', '-d',
+		'--name', CONTAINER_NAME,
+		'-e', 'MARIADB_ROOT_PASSWORD=roottestpassword',
+		'-e', 'MARIADB_DATABASE=nachklang_admin',
+		'-e', 'MARIADB_USER=nachklang',
+		'-e', 'MARIADB_PASSWORD=testpassword',
+		'-p', `${TEST_DB_PORT}:3306`,
+		// The very migration production runs, applied by the entrypoint on first
+		// boot - so a mistake in it fails the test run rather than the deploy.
+		'-v', `${process.cwd()}/sql/admin/001_init.sql:/docker-entrypoint-initdb.d/001_init.sql:ro`,
+		// Data lives in the container layer and dies with it.
+		IMAGE
+	], {timeout: 300_000});
+
+	await waitForSchema();
+};
+
+export const teardown = async () => {
+	const engine = await runtime().catch(() => null);
+	if (engine) {
+		await run(engine, ['rm', '-f', CONTAINER_NAME], {timeout: 60_000}).catch(() => undefined);
+	}
+};

test/tickets/tickets.auth.test.ts

@@ -0,0 +1,23 @@
+import {vi, type Mock} from 'vitest';
+
+vi.mock('../../src/models/calendar/users/users.service.js', () => ({
+	checkSession: vi.fn()
+}));
+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 * as UserService from '../../src/models/calendar/users/users.service.js';
+import {auth} from '../../src/models/admin/admin.auth.js';
+import * as UsersService from '../../src/models/admin/users/users.admin.service.js';
+import {requireAdminAuth} from '../../src/models/tickets/tickets.auth.js';
+import {describeAdminBinding} from '../admin/auth-binding.js';
+
+describeAdminBinding('tickets', 'feedback', requireAdminAuth, () => ({
+	getSession: auth.api.getSession as unknown as Mock,
+	loadAccess: UsersService.loadAccess as Mock,
+	checkSession: UserService.checkSession as Mock
+}));

vitest.config.ts

@@ -3,6 +3,9 @@ import {defineConfig} from 'vitest/config';
 export default defineConfig({
 	test: {
 		include: ['test/**/*.test.ts'],
+		// The integration suite needs a Docker MariaDB and runs separately via
+		// npm run test:integration (vitest.integration.config.ts).
+		exclude: ['test/integration/**'],
 		environment: 'node',
 		// feedback.ratelimit throws at import time without a salt (see
 		// test/feedback/ratelimit.salt-guard.test.ts). Set one here so the suite

vitest.integration.config.ts

@@ -0,0 +1,38 @@
+import {defineConfig} from 'vitest/config';
+
+/**
+ * The admin module's integration tests. Separate from vitest.config.ts because
+ * these need Docker: they run against a real MariaDB (see
+ * docker-compose.test.yml) rather than mocks, which is the only way to catch
+ * the Kysely/MariaDB dialect and cookie-attribute problems this module can have.
+ *
+ * Run with: npm run test:integration
+ */
+export default defineConfig({
+	test: {
+		include: ['test/integration/**/*.test.ts'],
+		environment: 'node',
+		globalSetup: ['test/integration/setup.ts'],
+		// One database, shared state: parallel files would fight over the same
+		// user and invitation rows.
+		fileParallelism: false,
+		testTimeout: 30_000,
+		hookTimeout: 180_000,
+		env: {
+			NODE_ENV: 'test',
+			FEEDBACK_IP_SALT: 'vitest-salt',
+			DB_HOST: '127.0.0.1',
+			DB_PORT: '3307',
+			DB_USER: 'nachklang',
+			DB_PASSWORD: 'testpassword',
+			ADMIN_DB: 'nachklang_admin',
+			API_BASE_URL: 'http://localhost:3000',
+			ADMIN_APP_URL: 'http://localhost:3002',
+			APP_ORIGINS: 'http://localhost:3001',
+			BETTER_AUTH_SECRET: 'integration-test-secret-not-used-anywhere-else',
+			PASSKEY_RP_ID: 'localhost',
+			ADMIN_BOOTSTRAP_EMAIL: 'boot@nachklang.art',
+			SALESFORCE_ENABLED: 'false'
+		}
+	}
+});