@raiyyan/brisk 0.1.0 → 0.2.0

package/starters/sqlite-auth/src/features/users/users.service.ts

@@ -0,0 +1,80 @@
+import { randomBytes, randomUUID, scrypt, timingSafeEqual } from "node:crypto";
+import { inject, Logger } from "@raiyyan/brisk";
+import { Clock } from "../../database/clock.ts";
+import { EmailTakenError, UserNotFoundError } from "./users.errors.ts";
+import { UsersRepository, type User } from "./users.repository.ts";
+import type { CreateUserBody, ListUsersQuery, UpdateUserBody } from "./users.schema.ts";
+
+/** Business rules for users. Throws errors the client understands; knows nothing about Express. */
+export class UsersService {
+  readonly #users = inject(UsersRepository);
+  readonly #now = inject(Clock);
+  readonly #log = inject(Logger);
+
+  list(query: ListUsersQuery): User[] {
+    return this.#users.findMany(query);
+  }
+
+  get(id: string): User {
+    const user = this.#users.findById(id);
+    if (!user) throw new UserNotFoundError(id);
+    return user;
+  }
+
+  async create({ email, name, password, role }: CreateUserBody): Promise<User> {
+    this.#assertEmailFree(email);
+    const user = this.#users.insert({
+      id: randomUUID(),
+      email,
+      name,
+      role,
+      passwordHash: await hashPassword(password),
+      createdAt: this.#now(),
+    });
+    this.#log.info({ userId: user.id, role }, "user created");
+    return user;
+  }
+
+  update(id: string, { email, name }: UpdateUserBody): User {
+    const user = this.get(id);
+    if (email !== undefined && email !== user.email) this.#assertEmailFree(email);
+    return this.#users.update({ ...user, email: email ?? user.email, name: name ?? user.name });
+  }
+
+  remove(id: string): void {
+    if (!this.#users.delete(id)) throw new UserNotFoundError(id);
+  }
+
+  /** The user these credentials belong to, or `undefined`; takes the same time whether or not the email exists. */
+  async authenticate(email: string, password: string): Promise<User | undefined> {
+    const user = this.#users.findByEmail(email.toLowerCase());
+    const matches = await verifyPassword(password, user?.passwordHash ?? DUMMY_HASH);
+    return user && matches ? user : undefined;
+  }
+
+  #assertEmailFree(email: string): void {
+    if (this.#users.findByEmail(email)) throw new EmailTakenError(email);
+  }
+}
+
+const KEY_LENGTH = 64;
+/** Compared against when the email is unknown, so timing does not reveal which emails exist. */
+const DUMMY_HASH = `${"0".repeat(32)}:${"0".repeat(KEY_LENGTH * 2)}`;
+
+function derive(password: string, salt: Buffer): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    scrypt(password, salt, KEY_LENGTH, (error, key) => (error ? reject(error) : resolve(key)));
+  });
+}
+
+async function hashPassword(password: string): Promise<string> {
+  const salt = randomBytes(16);
+  return `${salt.toString("hex")}:${(await derive(password, salt)).toString("hex")}`;
+}
+
+async function verifyPassword(password: string, stored: string): Promise<boolean> {
+  const [salt = "", hash = ""] = stored.split(":");
+  const expected = Buffer.from(hash, "hex");
+  const actual = await derive(password, Buffer.from(salt, "hex"));
+  return expected.length === actual.length && timingSafeEqual(expected, actual);
+}

package/starters/sqlite-auth/src/main.ts

@@ -0,0 +1,4 @@
+import { app } from "./app.ts";
+import { env } from "./env.ts";
+
+await app.listen(env.PORT);

package/starters/sqlite-auth/src/middlewares/authenticate.ts

@@ -0,0 +1,29 @@
+import {
+  defineMiddleware,
+  ForbiddenError,
+  inject,
+  UnauthorizedError,
+  type SecuritySchemes,
+} from "@raiyyan/brisk";
+import { Tokens, type Role } from "../auth/tokens.ts";
+
+/** How clients authenticate, as OpenAPI documents it on every route behind these middlewares. */
+const bearer = { bearer: { type: "http", scheme: "bearer", bearerFormat: "JWT" } } satisfies SecuritySchemes;
+
+/** Requires `Authorization: Bearer <token>` and adds `user` to ctx; request logs gain the user id. */
+export const authenticate = defineMiddleware({ security: bearer }, ({ req, log }) => {
+  const header = req.get("authorization");
+  const token = header?.startsWith("Bearer ") ? header.slice(7) : undefined;
+  const claims = token ? inject(Tokens).verify(token) : undefined;
+  if (!claims) throw new UnauthorizedError("Valid bearer token required", { challenge: "Bearer" });
+  const user = { id: claims.sub, role: claims.role };
+  return { user, log: log.child({ userId: user.id }) };
+});
+
+/** Requires a signed-in user with `role`; use it instead of, or after, `authenticate`. */
+export const requireRole = (role: Role) =>
+  defineMiddleware({ security: bearer }, async (ctx) => {
+    const { user } = await authenticate.run(ctx);
+    if (user.role !== role) throw new ForbiddenError(`Requires the ${role} role`);
+    return { user };
+  });

package/starters/sqlite-auth/src/schemas.ts

@@ -0,0 +1,26 @@
+import { z } from "@raiyyan/brisk";
+
+/**
+ * A response field for a timestamp: accepts a `Date` or an ISO string and always sends an ISO 8601 string,
+ * so clients type it as `string` and OpenAPI documents it as `date-time`.
+ */
+export const isoDate = () =>
+  z
+    .union([z.date(), z.string()])
+    .transform((value) => (value instanceof Date ? value : new Date(value)).toISOString())
+    .pipe(z.iso.datetime());
+
+/** Query fields for paged lists: `page` from 1, and `limit` up to 100. */
+export const PageQuery = z.object({
+  page: z.coerce.number().int().min(1).default(1),
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+});
+
+/** A page of `item`s, with the total across all pages. */
+export const page = <Item extends z.ZodType>(item: Item) =>
+  z.object({
+    items: z.array(item),
+    page: z.number().int(),
+    limit: z.number().int(),
+    total: z.number().int(),
+  });

package/starters/sqlite-auth/templates/feature/src/database/migrations.ts.migrations.insert

@@ -0,0 +1,5 @@
+  `CREATE TABLE {{snake}} (
+    id TEXT PRIMARY KEY,
+    name TEXT NOT NULL,
+    created_at TEXT NOT NULL
+  )`,

package/starters/sqlite-auth/templates/feature/src/features/index.ts.controllers.insert

@@ -0,0 +1 @@
+  {{camel}}: {{camel}}Controller,

package/starters/sqlite-auth/templates/feature/src/features/index.ts.imports.insert

@@ -0,0 +1 @@
+import { {{camel}}Controller } from "./{{kebab}}/{{kebab}}.controller.ts";

package/starters/sqlite-auth/templates/feature/src/features/{{kebab}}/{{kebab}}.controller.ts

@@ -0,0 +1,39 @@
+import { defineController, inject } from "@raiyyan/brisk";
+import { authenticate } from "../../middlewares/authenticate.ts";
+import { page } from "../../schemas.ts";
+import {
+  Create{{entity}}Body,
+  {{entity}}IdParams,
+  {{entity}}Response,
+  List{{pascal}}Query,
+  Update{{entity}}Body,
+} from "./{{kebab}}.schema.ts";
+import { {{pascal}}Service } from "./{{kebab}}.service.ts";
+
+export const {{camel}}Controller = defineController({ prefix: "/{{kebab}}", use: [authenticate] }, (route) => {
+  const {{camel}} = inject({{pascal}}Service);
+
+  return {
+    list: route.get("/", { query: List{{pascal}}Query, response: page({{entity}}Response) }, ({ query }) =>
+      {{camel}}.list(query),
+    ),
+
+    get: route.get("/:id", { params: {{entity}}IdParams, response: {{entity}}Response }, ({ params }) =>
+      {{camel}}.get(params.id),
+    ),
+
+    create: route.post("/", { body: Create{{entity}}Body, response: {{entity}}Response }, ({ body }) =>
+      {{camel}}.create(body),
+    ),
+
+    update: route.patch(
+      "/:id",
+      { params: {{entity}}IdParams, body: Update{{entity}}Body, response: {{entity}}Response },
+      ({ params, body }) => {{camel}}.update(params.id, body),
+    ),
+
+    remove: route.delete("/:id", { params: {{entity}}IdParams }, async ({ params }) => {
+      await {{camel}}.remove(params.id);
+    }),
+  };
+});

package/starters/sqlite-auth/templates/feature/src/features/{{kebab}}/{{kebab}}.repository.ts

@@ -0,0 +1,47 @@
+import { inject, z } from "@raiyyan/brisk";
+import { Database } from "../../database/database.ts";
+
+export interface {{entity}} {
+  id: string;
+  name: string;
+  createdAt: Date;
+}
+
+/** A row as SQLite returns it, checked once at the boundary instead of cast. */
+const Row = z
+  .object({ id: z.string(), name: z.string(), created_at: z.string() })
+  .transform((row): {{entity}} => ({ id: row.id, name: row.name, createdAt: new Date(row.created_at) }));
+
+/** Data access only: SQL in, {{entityCamel}} rows out. No HTTP and no business rules. */
+export class {{pascal}}Repository {
+  readonly #db = inject(Database);
+
+  async list({ page, limit }: { page: number; limit: number }): Promise<{ items: {{entity}}[]; total: number }> {
+    const rows = this.#db.sql
+      .prepare("SELECT * FROM {{snake}} ORDER BY created_at DESC, id DESC LIMIT ? OFFSET ?")
+      .all(limit, (page - 1) * limit);
+    const counted = this.#db.sql.prepare("SELECT count(*) AS total FROM {{snake}}").get();
+    return { items: rows.map((row) => Row.parse(row)), total: Number(counted?.["total"] ?? 0) };
+  }
+
+  async findById(id: string): Promise<{{entity}} | undefined> {
+    const row = this.#db.sql.prepare("SELECT * FROM {{snake}} WHERE id = ?").get(id);
+    return row === undefined ? undefined : Row.parse(row);
+  }
+
+  async insert(row: {{entity}}): Promise<{{entity}}> {
+    this.#db.sql
+      .prepare("INSERT INTO {{snake}} (id, name, created_at) VALUES (?, ?, ?)")
+      .run(row.id, row.name, row.createdAt.toISOString());
+    return row;
+  }
+
+  async update(row: {{entity}}): Promise<{{entity}}> {
+    this.#db.sql.prepare("UPDATE {{snake}} SET name = ? WHERE id = ?").run(row.name, row.id);
+    return row;
+  }
+
+  async delete(id: string): Promise<boolean> {
+    return Number(this.#db.sql.prepare("DELETE FROM {{snake}} WHERE id = ?").run(id).changes) > 0;
+  }
+}

package/starters/sqlite-auth/templates/feature/src/features/{{kebab}}/{{kebab}}.schema.ts

@@ -0,0 +1,24 @@
+import { z } from "@raiyyan/brisk";
+import { isoDate, PageQuery } from "../../schemas.ts";
+
+export const Create{{entity}}Body = z.object({
+  name: z.string().trim().min(1).max(200),
+});
+
+// Keep .default() out of the create schema: .partial() keeps defaults, and a PATCH would reset omitted fields.
+export const Update{{entity}}Body = Create{{entity}}Body.partial();
+
+export const {{entity}}IdParams = z.object({ id: z.uuid() });
+
+export const List{{pascal}}Query = PageQuery;
+
+/** What clients see of a {{entityCamel}}: fields not listed here never leave the server. */
+export const {{entity}}Response = z.object({
+  id: z.string(),
+  name: z.string(),
+  createdAt: isoDate(),
+});
+
+export type Create{{entity}}Body = z.infer<typeof Create{{entity}}Body>;
+export type Update{{entity}}Body = z.infer<typeof Update{{entity}}Body>;
+export type List{{pascal}}Query = z.infer<typeof List{{pascal}}Query>;

package/starters/sqlite-auth/templates/feature/src/features/{{kebab}}/{{kebab}}.service.ts

@@ -0,0 +1,33 @@
+import { randomUUID } from "node:crypto";
+import { inject, NotFoundError } from "@raiyyan/brisk";
+import { {{pascal}}Repository, type {{entity}} } from "./{{kebab}}.repository.ts";
+import type { Create{{entity}}Body, List{{pascal}}Query, Update{{entity}}Body } from "./{{kebab}}.schema.ts";
+
+/** Business rules for {{camel}}. Throws errors the client understands; knows nothing about Express. */
+export class {{pascal}}Service {
+  readonly #repository = inject({{pascal}}Repository);
+
+  async list(query: List{{pascal}}Query) {
+    const { items, total } = await this.#repository.list(query);
+    return { items, total, page: query.page, limit: query.limit };
+  }
+
+  async get(id: string): Promise<{{entity}}> {
+    const row = await this.#repository.findById(id);
+    if (!row) throw new NotFoundError("{{entity}} not found", { details: { id } });
+    return row;
+  }
+
+  create(input: Create{{entity}}Body): Promise<{{entity}}> {
+    return this.#repository.insert({ id: randomUUID(), name: input.name, createdAt: new Date() });
+  }
+
+  async update(id: string, { name }: Update{{entity}}Body): Promise<{{entity}}> {
+    const row = await this.get(id);
+    return this.#repository.update({ ...row, name: name ?? row.name });
+  }
+
+  async remove(id: string): Promise<void> {
+    if (!(await this.#repository.delete(id))) throw new NotFoundError("{{entity}} not found", { details: { id } });
+  }
+}

package/starters/sqlite-auth/templates/feature/test/{{kebab}}.service.test.ts

@@ -0,0 +1,20 @@
+import { randomUUID } from "node:crypto";
+import { Container, NotFoundError } from "@raiyyan/brisk";
+import { afterAll, describe, expect, it } from "vitest";
+import { {{pascal}}Service } from "../src/features/{{kebab}}/{{kebab}}.service.ts";
+
+const container = new Container();
+const {{camel}} = container.get({{pascal}}Service);
+await container.init();
+afterAll(() => container.shutdown(() => {}));
+
+describe("{{pascal}}Service", () => {
+  it("creates a {{entityCamel}} and finds it again", async () => {
+    const created = await {{camel}}.create({ name: "unit" });
+    expect(await {{camel}}.get(created.id)).toEqual(created);
+  });
+
+  it("throws NotFoundError for an id that does not exist", async () => {
+    await expect({{camel}}.get(randomUUID())).rejects.toBeInstanceOf(NotFoundError);
+  });
+});

package/starters/sqlite-auth/templates/feature/test/{{kebab}}.test.ts

@@ -0,0 +1,41 @@
+import { randomUUID } from "node:crypto";
+import { createTestClient } from "@raiyyan/brisk/testing";
+import { afterAll, describe, expect, it } from "vitest";
+import { app } from "../src/app.ts";
+import { signIn } from "./helpers.ts";
+
+const api = await createTestClient(app);
+afterAll(() => api.close());
+const headers = await signIn(api);
+
+describe("{{kebab}} API", () => {
+  it("creates, reads, lists, updates and deletes", async () => {
+    const created = await api.call.{{camel}}.create({ headers, body: { name: "first" } });
+    const params = { id: created.id };
+    expect(created).toMatchObject({ name: "first" });
+
+    expect(await api.call.{{camel}}.get({ headers, params })).toEqual(created);
+    expect((await api.call.{{camel}}.list({ headers, query: { limit: 100 } })).items).toContainEqual(created);
+    expect(await api.call.{{camel}}.update({ headers, params, body: { name: "second" } })).toMatchObject({
+      id: created.id,
+      name: "second",
+    });
+
+    await api.call.{{camel}}.remove({ headers, params });
+    await expect(api.call.{{camel}}.get({ headers, params })).rejects.toMatchObject({ status: 404 });
+  });
+
+  it("rejects invalid input with the field that failed", async () => {
+    expect((await api.post("/api/{{kebab}}", { headers, body: { name: "" } })).status).toBe(400);
+  });
+
+  it("answers 404 for an id that does not exist", async () => {
+    await expect(api.call.{{camel}}.get({ headers, params: { id: randomUUID() } })).rejects.toMatchObject({
+      status: 404,
+    });
+  });
+
+  it("requires a signed-in user", async () => {
+    await expect(api.call.{{camel}}.list()).rejects.toMatchObject({ status: 401 });
+  });
+});

package/starters/sqlite-auth/templates/middleware/src/middlewares/{{kebab}}.ts

@@ -0,0 +1,12 @@
+import { BadRequestError, defineMiddleware } from "@raiyyan/brisk";
+
+/**
+ * Reads the `x-{{kebab}}` header and adds `{{camel}}` to the ctx of every route that uses it. Replace the check
+ * with your own; return nothing for a check-only middleware. To validate path params or a query first,
+ * declare them: `defineMiddleware({ params: z.object({ ... }) }, ({ params }) => ...)`.
+ */
+export const {{camel}} = defineMiddleware(({ req }) => {
+  const value = req.get("x-{{kebab}}");
+  if (!value) throw new BadRequestError("Missing x-{{kebab}} header");
+  return { {{camel}}: value };
+});

package/starters/sqlite-auth/test/auth.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import { Container } from "@raiyyan/brisk";
+import { Tokens } from "../src/auth/tokens.ts";
+
+const tokens = new Container().get(Tokens);
+
+describe("tokens", () => {
+  it("round-trips claims", () => {
+    expect(tokens.verify(tokens.sign("u1", "admin"))).toMatchObject({ sub: "u1", role: "admin" });
+  });
+
+  it("rejects forged, malformed and expired tokens", () => {
+    const [header, payload] = tokens.sign("u1", "user").split(".");
+    expect(tokens.verify(`${header}.${payload}.forged`)).toBeUndefined();
+    expect(tokens.verify("not-a-token")).toBeUndefined();
+    expect(tokens.verify(tokens.sign("u1", "user", -1))).toBeUndefined();
+  });
+});

package/starters/sqlite-auth/test/helpers.ts

@@ -0,0 +1,13 @@
+import type { TestClient } from "@raiyyan/brisk/testing";
+import type { app } from "../src/app.ts";
+import { env } from "../src/env.ts";
+
+/** Signs in as the admin `vitest.config.ts` seeds; returns the headers that authenticate as them. */
+export async function signIn(api: TestClient<typeof app>): Promise<{ authorization: string }> {
+  if (!env.ADMIN_EMAIL || !env.ADMIN_PASSWORD)
+    throw new Error("vitest.config.ts must set ADMIN_EMAIL and ADMIN_PASSWORD");
+  const { token } = await api.call.auth.login({
+    body: { email: env.ADMIN_EMAIL, password: env.ADMIN_PASSWORD },
+  });
+  return { authorization: `Bearer ${token}` };
+}

package/starters/sqlite-auth/test/notes.service.test.ts

@@ -0,0 +1,20 @@
+import { randomUUID } from "node:crypto";
+import { Container, NotFoundError } from "@raiyyan/brisk";
+import { afterAll, describe, expect, it } from "vitest";
+import { NotesService } from "../src/features/notes/notes.service.ts";
+
+const container = new Container();
+const notes = container.get(NotesService);
+await container.init();
+afterAll(() => container.shutdown(() => {}));
+
+describe("NotesService", () => {
+  it("creates a note and finds it again", async () => {
+    const created = await notes.create({ name: "unit" });
+    expect(await notes.get(created.id)).toEqual(created);
+  });
+
+  it("throws NotFoundError for an id that does not exist", async () => {
+    await expect(notes.get(randomUUID())).rejects.toBeInstanceOf(NotFoundError);
+  });
+});

package/starters/sqlite-auth/test/notes.test.ts

@@ -0,0 +1,41 @@
+import { randomUUID } from "node:crypto";
+import { createTestClient } from "@raiyyan/brisk/testing";
+import { afterAll, describe, expect, it } from "vitest";
+import { app } from "../src/app.ts";
+import { signIn } from "./helpers.ts";
+
+const api = await createTestClient(app);
+afterAll(() => api.close());
+const headers = await signIn(api);
+
+describe("notes API", () => {
+  it("creates, reads, lists, updates and deletes", async () => {
+    const created = await api.call.notes.create({ headers, body: { name: "first" } });
+    const params = { id: created.id };
+    expect(created).toMatchObject({ name: "first" });
+
+    expect(await api.call.notes.get({ headers, params })).toEqual(created);
+    expect((await api.call.notes.list({ headers, query: { limit: 100 } })).items).toContainEqual(created);
+    expect(await api.call.notes.update({ headers, params, body: { name: "second" } })).toMatchObject({
+      id: created.id,
+      name: "second",
+    });
+
+    await api.call.notes.remove({ headers, params });
+    await expect(api.call.notes.get({ headers, params })).rejects.toMatchObject({ status: 404 });
+  });
+
+  it("rejects invalid input with the field that failed", async () => {
+    expect((await api.post("/api/notes", { headers, body: { name: "" } })).status).toBe(400);
+  });
+
+  it("answers 404 for an id that does not exist", async () => {
+    await expect(api.call.notes.get({ headers, params: { id: randomUUID() } })).rejects.toMatchObject({
+      status: 404,
+    });
+  });
+
+  it("requires a signed-in user", async () => {
+    await expect(api.call.notes.list()).rejects.toMatchObject({ status: 401 });
+  });
+});

package/starters/sqlite-auth/test/users.service.test.ts

@@ -0,0 +1,25 @@
+import { Container, provide } from "@raiyyan/brisk";
+import { describe, expect, it } from "vitest";
+import { Clock } from "../src/database/clock.ts";
+import { UsersService } from "../src/features/users/users.service.ts";
+
+describe("UsersService", () => {
+  it("is testable without HTTP: a container, a frozen clock and an in-memory database", async () => {
+    const container = new Container([provide(Clock, () => new Date("2030-05-05T00:00:00Z"))]);
+    const users = container.get(UsersService);
+    await container.init();
+
+    const user = await users.create({
+      email: "a@b.co",
+      name: "A",
+      password: "long-enough-password",
+      role: "user",
+    });
+    expect(user.createdAt.toISOString()).toBe("2030-05-05T00:00:00.000Z");
+    expect(user.passwordHash).toMatch(/^[0-9a-f]{32}:[0-9a-f]{128}$/);
+    expect(await users.authenticate("A@B.CO", "long-enough-password")).toMatchObject({ id: user.id });
+    expect(await users.authenticate("a@b.co", "wrong-password")).toBeUndefined();
+
+    await container.shutdown(() => {});
+  });
+});

package/starters/sqlite-auth/test/users.test.ts

@@ -0,0 +1,164 @@
+import { provide } from "@raiyyan/brisk";
+import { ApiError } from "@raiyyan/brisk/client";
+import { createTestClient, readError } from "@raiyyan/brisk/testing";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { app } from "../src/app.ts";
+import { Clock } from "../src/database/clock.ts";
+
+const api = await createTestClient(app, {
+  providers: [provide(Clock, () => new Date("2026-01-01T00:00:00Z"))],
+});
+const { auth, users } = api.call;
+afterAll(() => api.close());
+
+const ada = { email: "Ada@Example.com", name: "  Ada ", password: "correct-horse-battery" };
+const bearer = (token: string) => ({ authorization: `Bearer ${token}` });
+
+let admin: Record<string, string>;
+let member: Record<string, string>;
+beforeAll(async () => {
+  admin = bearer(
+    (await auth.login({ body: { email: "admin@example.com", password: "admin-password-for-tests" } })).token,
+  );
+  await users.create({
+    headers: admin,
+    body: { email: "member@example.com", name: "Member", password: "member-password-1" },
+  });
+  member = bearer(
+    (await auth.login({ body: { email: "member@example.com", password: "member-password-1" } })).token,
+  );
+});
+
+describe("auth", () => {
+  it("issues a bearer token for valid credentials only", async () => {
+    const login = await auth.login({
+      body: { email: "ADMIN@example.com", password: "admin-password-for-tests" },
+    });
+    expect(login).toMatchObject({ tokenType: "Bearer", expiresIn: 3600 });
+    await expect(
+      auth.login({ body: { email: "admin@example.com", password: "wrong" } }),
+    ).rejects.toMatchObject({
+      status: 401,
+      code: "INVALID_CREDENTIALS",
+    });
+    await expect(auth.login({ body: { email: "nobody@example.com", password: "x" } })).rejects.toMatchObject({
+      status: 401,
+    });
+  });
+
+  it("requires a valid bearer token", async () => {
+    const missing = await api.get("/api/users");
+    expect(missing.headers.get("www-authenticate")).toBe("Bearer");
+    expect(readError(missing)).toMatchObject({ code: "UNAUTHORIZED" });
+    await expect(users.list({ headers: bearer("forged.token.value") })).rejects.toMatchObject({
+      status: 401,
+    });
+  });
+});
+
+describe("users", () => {
+  it("creates a user, normalizing input and hiding the password hash", async () => {
+    const user = await users.create({ headers: admin, body: ada });
+    expect(user).toEqual({
+      id: user.id,
+      email: "ada@example.com",
+      name: "Ada",
+      role: "user",
+      createdAt: "2026-01-01T00:00:00.000Z",
+    });
+  });
+
+  it("returns field-level validation errors", async () => {
+    const res = await api.post("/api/users", {
+      headers: admin,
+      body: { email: "nope", name: "", password: "short" },
+    });
+    expect(res.status).toBe(400);
+    expect(readError(res).details).toMatchObject({
+      location: "body",
+      issues: [{ path: "email" }, { path: "name" }, { path: "password" }],
+    });
+    expect((await api.get("/api/users/not-a-uuid", { headers: admin })).status).toBe(400);
+    await expect(users.list({ headers: admin, query: { limit: 500 } })).rejects.toMatchObject({
+      status: 400,
+    });
+  });
+
+  it("lists with search and limit", async () => {
+    await users.create({ headers: admin, body: { ...ada, email: "grace@example.com", name: "Grace" } });
+    expect(await users.list({ headers: member, query: { limit: 1 } })).toHaveLength(1);
+    expect(await users.list({ headers: member, query: { search: "GRACE" } })).toEqual([
+      expect.objectContaining({ name: "Grace" }),
+    ]);
+  });
+
+  it("restricts writes to admins", async () => {
+    const forbidden = await users.create({ headers: member, body: ada }).catch((error: unknown) => error);
+    expect(forbidden).toBeInstanceOf(ApiError);
+    expect(forbidden).toMatchObject({ status: 403, code: "FORBIDDEN", message: "Requires the admin role" });
+  });
+
+  it("updates, conflicts and deletes", async () => {
+    const { id } = await users.create({ headers: admin, body: { ...ada, email: "lin@example.com" } });
+    const params = { id };
+
+    expect(await users.update({ headers: admin, params, body: { name: "Lin" } })).toMatchObject({
+      name: "Lin",
+      email: "lin@example.com",
+    });
+    await expect(
+      users.update({ headers: admin, params, body: { email: "ada@example.com" } }),
+    ).rejects.toMatchObject({
+      status: 409,
+      code: "EMAIL_TAKEN",
+      details: { email: "ada@example.com" },
+    });
+
+    await users.remove({ headers: admin, params });
+    await expect(users.get({ headers: admin, params })).rejects.toMatchObject({
+      code: "USER_NOT_FOUND",
+      details: { id },
+    });
+    await expect(users.remove({ headers: admin, params })).rejects.toMatchObject({ status: 404 });
+  });
+
+  it("lets the database settle a race the service check cannot see", async () => {
+    const body = { ...ada, email: "race@example.com" };
+    const results = await Promise.allSettled([
+      users.create({ headers: admin, body }),
+      users.create({ headers: admin, body }),
+    ]);
+    expect(results.map((result) => result.status).toSorted()).toEqual(["fulfilled", "rejected"]);
+    const lost = results.find((result) => result.status === "rejected");
+    expect(lost?.reason).toMatchObject({ status: 409, code: "ALREADY_EXISTS" });
+  });
+
+  it("returns the authenticated user", async () => {
+    expect(await users.me({ headers: member })).toMatchObject({ email: "member@example.com", role: "user" });
+  });
+});
+
+describe("OpenAPI", () => {
+  it("documents the API, with route names as operation ids", async () => {
+    expect((await api.get("/openapi.json")).body).toMatchObject({
+      openapi: "3.1.1",
+      paths: {
+        "/api/auth/login": { post: { operationId: "auth.login" } },
+        "/api/users/{id}": {
+          get: {
+            operationId: "users.get",
+            responses: {
+              "200": {
+                content: {
+                  "application/json": {
+                    schema: { properties: { createdAt: { type: "string", format: "date-time" } } },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    });
+  });
+});