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

Introduces src/models/admin/, a dedicated identity and permissions module on its own nachklang_admin database, and the shared authenticator that feedback and tickets will move onto in the cutover step. Nothing swaps over yet: feedback.auth.ts and tickets.auth.ts still authenticate against the legacy calendar sessions, so production behaviour is unchanged. - better-auth 1.7 mounted at /admin/auth/*, sessions as httpOnly cookies scoped to .nachklang.art so one sign-in covers every *.nachklang.art app. - Accounts are invite-only: public sign-up is disabled, and the invitations plugin is the only code that creates users. Tokens are stored as SHA-256 hashes and travel in the request body, never in a URL. - Per-app permissions in user_app_permissions; requireAppAccess(app) queries the database on every request (no cookie cache) so disabling a user or revoking a session takes effect immediately. - ADMIN_BOOTSTRAP_EMAIL guarantees a way in on an empty database, idempotently and without crashing the API if the database is unreachable at boot. - Guards prevent an admin from removing their own admin permission, disabling themselves, or stripping the last active admin. The admin pool uses the callback-style mysql2, not mysql2/promise: Kysely's MysqlDialect drives the pool with callbacks, and the promise wrapper ignores them, so every query hangs silently. Only the integration tests caught this. Schema in sql/admin/001_init.sql, derived from getAuthTables() on the installed better-auth rather than the published CLI, which lags the library and omits account.issuer. app.ts is split into src/app.factory.ts so the integration tests drive the real middleware order rather than a copy of it. Tests: 131 unit, plus 41 integration tests against a throwaway MariaDB started by test/integration/setup.ts (docker or podman). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-05 18:03:08 +02:00
parent bf7f45acce
commit 7aac07a013
37 changed files with 5620 additions and 320 deletions
@@ -0,0 +1,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 {};