create-authenik8-app 2.4.12 → 2.4.13

package/templates/fullstack/apps/api/src/modules/admin/admin.routes.ts

@@ -0,0 +1,14 @@
+import { Router } from "express";
+import { authenticate, requireAdmin } from "../../middleware/authenticate.js";
+import { requireCsrf } from "../../middleware/csrf.js";
+import { requireAllowedOrigin } from "../../middleware/origin.js";
+import { auditController, listUsersController, revokeUserSessionsController, updateUserController } from "./admin.controller.js";
+
+export const adminRoutes = Router();
+// authenik8-core's global Redis-backed limiter runs before this router.
+// codeql[js/missing-rate-limiting]
+adminRoutes.use(authenticate, requireAdmin);
+adminRoutes.get("/users", listUsersController);
+adminRoutes.patch("/users/:id", requireAllowedOrigin, requireCsrf, updateUserController);
+adminRoutes.delete("/users/:id/sessions", requireAllowedOrigin, requireCsrf, revokeUserSessionsController);
+adminRoutes.get("/audit", auditController);

package/templates/fullstack/apps/api/src/modules/admin/admin.service.ts

@@ -0,0 +1,54 @@
+import { adminUserUpdateSchema } from "@authenik8/contracts";
+import { prisma } from "../../config/prisma.js";
+import { getAuthenik8 } from "../../auth/authenik8.js";
+import { AppError } from "../../utils/http.js";
+import { presentUser } from "../users/user.presenter.js";
+
+export async function listUsers(page: number) {
+  const pageSize = 20;
+  const safePage = Math.max(1, page);
+  const [items, total] = await prisma.$transaction([
+    prisma.user.findMany({ orderBy: { createdAt: "desc" }, skip: (safePage - 1) * pageSize, take: pageSize }),
+    prisma.user.count(),
+  ]);
+  return { items: items.map(presentUser), total, page: safePage, pageSize };
+}
+
+export async function updateUser(actorId: string, targetId: string, body: unknown, ipAddress: string) {
+  const input = adminUserUpdateSchema.parse(body);
+  if (actorId === targetId && (input.role === "USER" || input.status === "SUSPENDED")) {
+    throw new AppError(400, "SELF_LOCKOUT", "You cannot remove your own administrator access");
+  }
+  const user = await prisma.user.update({ where: { id: targetId }, data: input });
+  await prisma.auditEvent.create({
+    data: { actorId, action: "admin.user.updated", targetType: "User", targetId, metadata: input, ipAddress },
+  });
+  if (input.status === "SUSPENDED") await revokeAllSessions(actorId, targetId, ipAddress, false);
+  return presentUser(user);
+}
+
+export async function revokeAllSessions(actorId: string, targetId: string, ipAddress: string, audit = true) {
+  await prisma.session.updateMany({ where: { userId: targetId, revokedAt: null }, data: { revokedAt: new Date() } });
+  await getAuthenik8().revokeAllSessions(targetId);
+  if (audit) {
+    await prisma.auditEvent.create({
+      data: { actorId, action: "admin.sessions.revoked", targetType: "User", targetId, ipAddress },
+    });
+  }
+}
+
+export async function listAuditEvents() {
+  const events = await prisma.auditEvent.findMany({
+    include: { actor: { select: { email: true } } },
+    orderBy: { createdAt: "desc" },
+    take: 100,
+  });
+  return events.map((event) => ({
+    id: event.id,
+    action: event.action,
+    actorEmail: event.actor?.email ?? null,
+    targetType: event.targetType,
+    targetId: event.targetId,
+    createdAt: event.createdAt.toISOString(),
+  }));
+}

package/templates/fullstack/apps/api/src/modules/projects/project.controller.ts

@@ -0,0 +1,22 @@
+import { asyncHandler } from "../../utils/http.js";
+import { identifierSchema } from "@authenik8/contracts";
+import { createProject, deleteProject, getProject, listProjects, updateProject } from "./project.service.js";
+
+const actor = (user: NonNullable<Express.Request["user"]>) => ({ userId: user.userId, role: user.role });
+
+export const listProjectsController = asyncHandler(async (req, res) => {
+  res.json({ projects: await listProjects(actor(req.user!)) });
+});
+export const getProjectController = asyncHandler(async (req, res) => {
+  res.json({ project: await getProject(actor(req.user!), identifierSchema.parse(req.params.id)) });
+});
+export const createProjectController = asyncHandler(async (req, res) => {
+  res.status(201).json({ project: await createProject(actor(req.user!), req.body) });
+});
+export const updateProjectController = asyncHandler(async (req, res) => {
+  res.json({ project: await updateProject(actor(req.user!), identifierSchema.parse(req.params.id), req.body) });
+});
+export const deleteProjectController = asyncHandler(async (req, res) => {
+  await deleteProject(actor(req.user!), identifierSchema.parse(req.params.id));
+  res.status(204).send();
+});

package/templates/fullstack/apps/api/src/modules/projects/project.policy.ts

@@ -0,0 +1,14 @@
+type Actor = { userId: string; role: "USER" | "ADMIN" };
+type Resource = { ownerId: string };
+
+export function canReadProject(actor: Actor, project: Resource): boolean {
+  return actor.role === "ADMIN" || project.ownerId === actor.userId;
+}
+
+export function canWriteProject(actor: Actor, project: Resource): boolean {
+  return actor.role === "ADMIN" || project.ownerId === actor.userId;
+}
+
+export function projectListScope(actor: Actor) {
+  return actor.role === "ADMIN" ? {} : { ownerId: actor.userId };
+}

package/templates/fullstack/apps/api/src/modules/projects/project.repository.ts

@@ -0,0 +1,20 @@
+import type { Prisma, Project } from "@prisma/client";
+import { prisma } from "../../config/prisma.js";
+
+export const projectRepository = {
+  list(where: Prisma.ProjectWhereInput): Promise<Project[]> {
+    return prisma.project.findMany({ where, orderBy: { updatedAt: "desc" } });
+  },
+  findById(id: string): Promise<Project | null> {
+    return prisma.project.findUnique({ where: { id } });
+  },
+  create(data: Prisma.ProjectUncheckedCreateInput): Promise<Project> {
+    return prisma.project.create({ data });
+  },
+  update(id: string, data: Prisma.ProjectUpdateInput): Promise<Project> {
+    return prisma.project.update({ where: { id }, data });
+  },
+  remove(id: string): Promise<Project> {
+    return prisma.project.delete({ where: { id } });
+  },
+};

package/templates/fullstack/apps/api/src/modules/projects/project.routes.ts

@@ -0,0 +1,21 @@
+import { Router } from "express";
+import { authenticate } from "../../middleware/authenticate.js";
+import { requireCsrf } from "../../middleware/csrf.js";
+import { requireAllowedOrigin } from "../../middleware/origin.js";
+import {
+  createProjectController,
+  deleteProjectController,
+  getProjectController,
+  listProjectsController,
+  updateProjectController,
+} from "./project.controller.js";
+
+export const projectRoutes = Router();
+// authenik8-core's global Redis-backed limiter runs before this router.
+// codeql[js/missing-rate-limiting]
+projectRoutes.use(authenticate);
+projectRoutes.get("/", listProjectsController);
+projectRoutes.post("/", requireAllowedOrigin, requireCsrf, createProjectController);
+projectRoutes.get("/:id", getProjectController);
+projectRoutes.patch("/:id", requireAllowedOrigin, requireCsrf, updateProjectController);
+projectRoutes.delete("/:id", requireAllowedOrigin, requireCsrf, deleteProjectController);

package/templates/fullstack/apps/api/src/modules/projects/project.service.ts

@@ -0,0 +1,41 @@
+import { projectCreateSchema, projectUpdateSchema } from "@authenik8/contracts";
+import type { Project } from "@prisma/client";
+import { AppError } from "../../utils/http.js";
+import { canReadProject, canWriteProject, projectListScope } from "./project.policy.js";
+import { projectRepository } from "./project.repository.js";
+
+type Actor = { userId: string; role: "USER" | "ADMIN" };
+
+function present(project: Project) {
+  return { ...project, createdAt: project.createdAt.toISOString(), updatedAt: project.updatedAt.toISOString() };
+}
+
+async function authorizedProject(actor: Actor, id: string, write = false) {
+  const project = await projectRepository.findById(id);
+  const allowed = project && (write ? canWriteProject(actor, project) : canReadProject(actor, project));
+  if (!project || !allowed) throw new AppError(404, "PROJECT_NOT_FOUND", "Project not found");
+  return project;
+}
+
+export async function listProjects(actor: Actor) {
+  return (await projectRepository.list(projectListScope(actor))).map(present);
+}
+
+export async function getProject(actor: Actor, id: string) {
+  return present(await authorizedProject(actor, id));
+}
+
+export async function createProject(actor: Actor, body: unknown) {
+  const input = projectCreateSchema.parse(body);
+  return present(await projectRepository.create({ ...input, ownerId: actor.userId }));
+}
+
+export async function updateProject(actor: Actor, id: string, body: unknown) {
+  await authorizedProject(actor, id, true);
+  return present(await projectRepository.update(id, projectUpdateSchema.parse(body)));
+}
+
+export async function deleteProject(actor: Actor, id: string) {
+  await authorizedProject(actor, id, true);
+  await projectRepository.remove(id);
+}

package/templates/fullstack/apps/api/src/modules/users/user.controller.ts

@@ -0,0 +1,26 @@
+import { clearRefreshCookie } from "../../auth/cookies.js";
+import { identifierSchema } from "@authenik8/contracts";
+import { asyncHandler } from "../../utils/http.js";
+import { changePassword, listProviders, listSessions, revokeSession, updateProfile } from "./user.service.js";
+
+export const updateProfileController = asyncHandler(async (req, res) => {
+  res.json({ user: await updateProfile(req.user!.userId, req.body) });
+});
+
+export const changePasswordController = asyncHandler(async (req, res) => {
+  await changePassword(req.user!.userId, req.body);
+  res.json({ message: "Password updated" });
+});
+
+export const sessionsController = asyncHandler(async (req, res) => {
+  res.json({ sessions: await listSessions(req.user!.userId, req) });
+});
+
+export const revokeSessionController = asyncHandler(async (req, res) => {
+  if (await revokeSession(req.user!.userId, identifierSchema.parse(req.params.id), req)) clearRefreshCookie(res);
+  res.json({ message: "Session revoked" });
+});
+
+export const providersController = asyncHandler(async (req, res) => {
+  res.json({ providers: await listProviders(req.user!.userId) });
+});

package/templates/fullstack/apps/api/src/modules/users/user.presenter.ts

@@ -0,0 +1,13 @@
+import type { User } from "@prisma/client";
+
+export function presentUser(user: User) {
+  return {
+    id: user.id,
+    email: user.email,
+    name: user.name,
+    role: user.role,
+    status: user.status,
+    verified: user.emailVerifiedAt !== null,
+    createdAt: user.createdAt.toISOString(),
+  };
+}

package/templates/fullstack/apps/api/src/modules/users/user.routes.ts

@@ -0,0 +1,21 @@
+import { Router } from "express";
+import { authenticate } from "../../middleware/authenticate.js";
+import { requireCsrf } from "../../middleware/csrf.js";
+import { requireAllowedOrigin } from "../../middleware/origin.js";
+import {
+  changePasswordController,
+  providersController,
+  revokeSessionController,
+  sessionsController,
+  updateProfileController,
+} from "./user.controller.js";
+
+export const userRoutes = Router();
+// authenik8-core's global Redis-backed limiter runs before this router.
+// codeql[js/missing-rate-limiting]
+userRoutes.use(authenticate);
+userRoutes.patch("/profile", requireAllowedOrigin, requireCsrf, updateProfileController);
+userRoutes.put("/password", requireAllowedOrigin, requireCsrf, changePasswordController);
+userRoutes.get("/sessions", sessionsController);
+userRoutes.delete("/sessions/:id", requireAllowedOrigin, requireCsrf, revokeSessionController);
+userRoutes.get("/providers", providersController);

package/templates/fullstack/apps/api/src/modules/users/user.service.ts

@@ -0,0 +1,71 @@
+import bcrypt from "bcryptjs";
+import type { Request } from "express";
+import { changePasswordSchema, profileSchema } from "@authenik8/contracts";
+import { readRefreshCookie } from "../../auth/cookies.js";
+import { prisma } from "../../config/prisma.js";
+import { getAuthenik8 } from "../../auth/authenik8.js";
+import { hashToken } from "../../utils/crypto.js";
+import { AppError } from "../../utils/http.js";
+import { presentUser } from "./user.presenter.js";
+
+export async function updateProfile(userId: string, body: unknown) {
+  const input = profileSchema.parse(body);
+  return presentUser(await prisma.user.update({ where: { id: userId }, data: { name: input.name } }));
+}
+
+export async function changePassword(userId: string, body: unknown) {
+  const input = changePasswordSchema.parse(body);
+  const user = await prisma.user.findUniqueOrThrow({ where: { id: userId } });
+  if (!user.passwordHash || !(await bcrypt.compare(input.currentPassword, user.passwordHash))) {
+    throw new AppError(400, "PASSWORD_INCORRECT", "Current password is incorrect");
+  }
+  const now = new Date();
+  await prisma.$transaction([
+    prisma.user.update({
+      where: { id: userId },
+      data: { passwordHash: await bcrypt.hash(input.newPassword, 12), passwordUpdatedAt: now },
+    }),
+    prisma.session.updateMany({
+      where: { userId, revokedAt: null },
+      data: { revokedAt: now },
+    }),
+  ]);
+  await getAuthenik8().revokeAllSessions(userId);
+}
+
+export async function listSessions(userId: string, req: Request) {
+  const refreshToken = readRefreshCookie(req);
+  const currentHash = refreshToken ? hashToken(refreshToken) : "";
+  const sessions = await prisma.session.findMany({
+    where: { userId, revokedAt: null, expiresAt: { gt: new Date() } },
+    orderBy: { lastUsedAt: "desc" },
+  });
+  return sessions.map((session) => ({
+    id: session.id,
+    userAgent: session.userAgent,
+    ipAddress: session.ipAddress,
+    createdAt: session.createdAt.toISOString(),
+    lastUsedAt: session.lastUsedAt.toISOString(),
+    expiresAt: session.expiresAt.toISOString(),
+    current: session.refreshHash === currentHash,
+  }));
+}
+
+export async function revokeSession(userId: string, sessionId: string, req: Request) {
+  const session = await prisma.session.findFirst({ where: { id: sessionId, userId, revokedAt: null } });
+  if (!session) throw new AppError(404, "SESSION_NOT_FOUND", "Session not found");
+  await prisma.session.update({ where: { id: session.id }, data: { revokedAt: new Date() } });
+  const refreshToken = readRefreshCookie(req);
+  const current = refreshToken && session.refreshHash === hashToken(refreshToken);
+  await getAuthenik8().revokeSession(userId, session.coreSessionId);
+  return Boolean(current);
+}
+
+export async function listProviders(userId: string) {
+  const providers = await prisma.oAuthAccount.findMany({ where: { userId }, orderBy: { createdAt: "asc" } });
+  return providers.map((account) => ({
+    provider: account.provider as "google" | "github",
+    providerEmail: account.providerEmail,
+    linkedAt: account.createdAt.toISOString(),
+  }));
+}

package/templates/fullstack/apps/api/src/openapi.ts

@@ -0,0 +1,32 @@
+export const openApiDocument = {
+  openapi: "3.1.0",
+  info: { title: "Authenik8 Full-stack API", version: "1.0.0" },
+  servers: [{ url: "/api" }],
+  components: {
+    securitySchemes: {
+      bearerAuth: { type: "http", scheme: "bearer", bearerFormat: "JWT" },
+      csrfToken: { type: "apiKey", in: "header", name: "X-CSRF-Token" },
+    },
+    schemas: {
+      Error: { type: "object", properties: { error: { type: "object", properties: { code: { type: "string" }, message: { type: "string" } } }, requestId: { type: "string" } } },
+    },
+  },
+  paths: {
+    "/auth/csrf": { get: { summary: "Issue a signed CSRF token", responses: { "200": { description: "CSRF token and protected cookie" } } } },
+    "/auth/register": { post: { summary: "Register with email and password", security: [{ csrfToken: [] }], responses: { "201": { description: "Verification requested" }, "422": { description: "Validation error" } } } },
+    "/auth/login": { post: { summary: "Create a refresh session", security: [{ csrfToken: [] }], responses: { "200": { description: "Access token and user" }, "401": { description: "Invalid credentials" } } } },
+    "/auth/refresh": { post: { summary: "Rotate the refresh cookie", security: [{ csrfToken: [] }], responses: { "200": { description: "Rotated session" }, "401": { description: "Replay or invalid session" } } } },
+    "/auth/logout": { post: { summary: "Revoke the current refresh session", security: [{ csrfToken: [] }], responses: { "200": { description: "Signed out" } } } },
+    "/projects": {
+      get: { summary: "List authorized projects", security: [{ bearerAuth: [] }], responses: { "200": { description: "Project list" } } },
+      post: { summary: "Create an owned project", security: [{ bearerAuth: [], csrfToken: [] }], responses: { "201": { description: "Project created" } } },
+    },
+    "/projects/{id}": {
+      get: { summary: "Read an authorized project", security: [{ bearerAuth: [] }], parameters: [{ in: "path", name: "id", required: true, schema: { type: "string", format: "uuid" } }], responses: { "200": { description: "Project" }, "404": { description: "Not found or not authorized" } } },
+      patch: { summary: "Update an authorized project", security: [{ bearerAuth: [], csrfToken: [] }], responses: { "200": { description: "Project updated" } } },
+      delete: { summary: "Delete an authorized project", security: [{ bearerAuth: [], csrfToken: [] }], responses: { "204": { description: "Project deleted" } } },
+    },
+    "/admin/users": { get: { summary: "List users", security: [{ bearerAuth: [] }], responses: { "200": { description: "Paginated users" }, "403": { description: "Administrator required" } } } },
+    "/health/ready": { get: { summary: "Check database and Redis readiness", responses: { "200": { description: "Ready" } } } },
+  },
+} as const;

package/templates/fullstack/apps/api/src/server.ts

@@ -0,0 +1,29 @@
+import { initAuthenik8, redis } from "./auth/authenik8.js";
+import { createApp } from "./app.js";
+import { env } from "./config/env.js";
+import { logger } from "./config/logger.js";
+import { prisma } from "./config/prisma.js";
+
+async function start() {
+  await initAuthenik8();
+  await prisma.$connect();
+  const server = createApp().listen(env.PORT, () => {
+    logger.info({ port: env.PORT }, `API running on http://localhost:${env.PORT}`);
+  });
+
+  const shutdown = async (signal: string) => {
+    logger.info({ signal }, "Shutting down");
+    server.close(async () => {
+      await Promise.all([prisma.$disconnect(), redis.quit()]);
+      process.exit(0);
+    });
+    setTimeout(() => process.exit(1), 10_000).unref();
+  };
+  process.once("SIGINT", () => void shutdown("SIGINT"));
+  process.once("SIGTERM", () => void shutdown("SIGTERM"));
+}
+
+start().catch((error) => {
+  logger.fatal({ err: error }, "API failed to start");
+  process.exit(1);
+});

package/templates/fullstack/apps/api/src/types.ts

@@ -0,0 +1,15 @@
+declare global {
+  namespace Express {
+    interface Request {
+      id: string;
+      user?: {
+        userId: string;
+        email: string;
+        name: string;
+        role: "USER" | "ADMIN";
+      };
+    }
+  }
+}
+
+export {};

package/templates/fullstack/apps/api/src/utils/crypto.ts

@@ -0,0 +1,4 @@
+import { createHash, randomBytes } from "node:crypto";
+
+export const randomToken = () => randomBytes(32).toString("hex");
+export const hashToken = (value: string) => createHash("sha256").update(value).digest("hex");

package/templates/fullstack/apps/api/src/utils/http.ts

@@ -0,0 +1,33 @@
+import type { NextFunction, Request, RequestHandler, Response } from "express";
+import { ZodError } from "zod";
+
+export class AppError extends Error {
+  constructor(public status: number, public code: string, message: string) {
+    super(message);
+  }
+}
+
+export function asyncHandler(handler: (req: Request, res: Response, next: NextFunction) => Promise<unknown>): RequestHandler {
+  return (req, res, next) => void handler(req, res, next).catch(next);
+}
+
+export function errorHandler(error: unknown, req: Request, res: Response, _next: NextFunction) {
+  if (error instanceof ZodError) {
+    return res.status(422).json({
+      error: { code: "VALIDATION_ERROR", message: "Check the submitted fields", fields: error.flatten().fieldErrors },
+      requestId: req.id,
+    });
+  }
+  if (error instanceof AppError) {
+    return res.status(error.status).json({ error: { code: error.code, message: error.message }, requestId: req.id });
+  }
+  req.log?.error({ err: error }, "Unhandled request error");
+  return res.status(500).json({
+    error: { code: "INTERNAL_ERROR", message: "The request could not be completed" },
+    requestId: req.id,
+  });
+}
+
+export function notFound(req: Request, res: Response) {
+  return res.status(404).json({ error: { code: "NOT_FOUND", message: "Route not found" }, requestId: req.id });
+}

package/templates/fullstack/apps/api/src/utils/sealed-value.ts

@@ -0,0 +1,37 @@
+import { createCipheriv, createDecipheriv, createHmac, randomBytes } from "node:crypto";
+import { z } from "zod";
+
+const sealedValueSchema = z.string()
+  .max(16_384)
+  .regex(/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/);
+
+function encryptionKey(secret: string): Buffer {
+  return createHmac("sha256", secret).update("authenik8:sealed-value:v1").digest();
+}
+
+export function sealValue(value: string, secret: string): string {
+  const iv = randomBytes(12);
+  const cipher = createCipheriv("aes-256-gcm", encryptionKey(secret), iv);
+  const ciphertext = Buffer.concat([cipher.update(value, "utf8"), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return [iv, tag, ciphertext].map((part) => part.toString("base64url")).join(".");
+}
+
+export function openSealedValue(value: unknown, secret: string): string | undefined {
+  const parsed = sealedValueSchema.safeParse(value);
+  if (!parsed.success) return undefined;
+
+  try {
+    const [ivValue, tagValue, ciphertextValue] = parsed.data.split(".");
+    const iv = Buffer.from(ivValue!, "base64url");
+    const tag = Buffer.from(tagValue!, "base64url");
+    const ciphertext = Buffer.from(ciphertextValue!, "base64url");
+    if (iv.length !== 12 || tag.length !== 16 || ciphertext.length === 0) return undefined;
+
+    const decipher = createDecipheriv("aes-256-gcm", encryptionKey(secret), iv);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
+  } catch {
+    return undefined;
+  }
+}

package/templates/fullstack/apps/api/tests/project.policy.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import { canReadProject, canWriteProject, projectListScope } from "../src/modules/projects/project.policy.js";
+
+describe("Project ownership policy", () => {
+  const owner = { userId: "user-1", role: "USER" as const };
+  const stranger = { userId: "user-2", role: "USER" as const };
+  const admin = { userId: "admin-1", role: "ADMIN" as const };
+  const project = { ownerId: "user-1" };
+
+  it("allows the owner to read and write", () => {
+    expect(canReadProject(owner, project)).toBe(true);
+    expect(canWriteProject(owner, project)).toBe(true);
+  });
+
+  it("rejects another normal user", () => {
+    expect(canReadProject(stranger, project)).toBe(false);
+    expect(canWriteProject(stranger, project)).toBe(false);
+    expect(projectListScope(stranger)).toEqual({ ownerId: "user-2" });
+  });
+
+  it("allows an administrator through the explicit policy", () => {
+    expect(canReadProject(admin, project)).toBe(true);
+    expect(canWriteProject(admin, project)).toBe(true);
+    expect(projectListScope(admin)).toEqual({});
+  });
+});

package/templates/fullstack/apps/api/tests/registration.test.ts

@@ -0,0 +1,69 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  findUnique: vi.fn(),
+  create: vi.fn(),
+  sendVerificationEmail: vi.fn(),
+  hash: vi.fn(async () => "hashed-password"),
+}));
+
+vi.mock("../src/config/prisma.js", () => ({
+  prisma: {
+    user: {
+      findUnique: mocks.findUnique,
+      create: mocks.create,
+    },
+  },
+}));
+vi.mock("../src/config/mailer.js", () => ({
+  sendPasswordResetEmail: vi.fn(),
+  sendVerificationEmail: mocks.sendVerificationEmail,
+}));
+vi.mock("../src/auth/authenik8.js", () => ({
+  getAuthenik8: vi.fn(),
+  redis: { del: vi.fn(), setex: vi.fn() },
+}));
+vi.mock("bcryptjs", () => ({
+  default: { compare: vi.fn(), hash: mocks.hash },
+}));
+
+import { register } from "../src/auth/auth.service.js";
+
+describe("registration service", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.findUnique.mockResolvedValue(null);
+    mocks.create.mockResolvedValue({ id: "user-1" });
+    mocks.sendVerificationEmail.mockResolvedValue(undefined);
+  });
+
+  it("creates a validated account and sends its verification message", async () => {
+    const result = await register({
+      name: "Jane Example",
+      email: "jane@example.com",
+      password: "SecurePass1",
+    });
+
+    expect(mocks.create).toHaveBeenCalledWith({
+      data: expect.objectContaining({
+        name: "Jane Example",
+        email: "jane@example.com",
+        passwordHash: "hashed-password",
+        verificationTokens: { create: expect.objectContaining({ tokenHash: expect.any(String) }) },
+      }),
+    });
+    expect(mocks.sendVerificationEmail).toHaveBeenCalledWith("jane@example.com", expect.any(String));
+    expect(result).toMatchObject({ message: "Check your inbox to continue" });
+  });
+
+  it("returns the same response for an existing address", async () => {
+    mocks.findUnique.mockResolvedValue({ id: "existing-user" });
+
+    await expect(register({
+      name: "Jane Example",
+      email: "jane@example.com",
+      password: "SecurePass1",
+    })).resolves.toEqual({ message: "Check your inbox to continue" });
+    expect(mocks.create).not.toHaveBeenCalled();
+  });
+});