@raiyyan/brisk 0.1.0 → 0.2.0

package/starters/sqlite-auth/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "starter-sqlite-auth",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "node --watch src/main.ts",
+    "start": "node src/main.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "brisk": "brisk",
+    "lint": "oxlint --type-aware",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check"
+  },
+  "dependencies": {
+    "@raiyyan/brisk": "workspace:*",
+    "cors": "^2.8.6",
+    "express": "^5.3.0",
+    "express-rate-limit": "^8.7.4"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
+    "@types/node": "^26.6.6",
+    "oxfmt": "^0.78.0",
+    "oxlint": "^1.93.0",
+    "oxlint-tsgolint": "^7.0.2007",
+    "pino-pretty": "^13.2.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.1.0"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}

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

@@ -0,0 +1,39 @@
+import { createLogger, defineApp, fromExpress } from "@raiyyan/brisk";
+import cors from "cors";
+import express from "express";
+import { rateLimit } from "express-rate-limit";
+import { uniqueViolation } from "./database/errors.ts";
+import { env } from "./env.ts";
+import { controllers } from "./features/index.ts";
+import { AdminSeed } from "./features/users/admin-seed.ts";
+
+export const app = defineApp({
+  prefix: "/api",
+  controllers,
+  providers: [AdminSeed],
+  logger: createLogger({
+    level: env.NODE_ENV === "test" ? "silent" : env.LOG_LEVEL,
+    pretty: env.NODE_ENV === "development",
+  }),
+  openapi: { title: "brisk demo", version: "1.0.0" },
+  errors: {
+    mappers: [uniqueViolation],
+    exposeInternal: env.NODE_ENV === "development",
+  },
+  use: [
+    fromExpress(cors({ origin: env.WEB_ORIGIN, credentials: true })),
+    // Behind a proxy, set http: { settings: { "trust proxy": 1 } } so the limit applies per client, not per proxy.
+    fromExpress(
+      rateLimit({
+        windowMs: 60_000,
+        limit: env.RATE_LIMIT_PER_MINUTE,
+        standardHeaders: "draft-8",
+        legacyHeaders: false,
+      }),
+    ),
+  ],
+  mount: { "/static": express.static("public", { maxAge: "1h" }) },
+});
+
+/** The API's type, for a frontend's typed client: `createClient<Api>(manifest, { baseUrl })`. */
+export type Api = typeof app;

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

@@ -0,0 +1,41 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { z } from "@raiyyan/brisk";
+import { env } from "../env.ts";
+
+export const Role = z.enum(["user", "admin"]);
+export type Role = z.infer<typeof Role>;
+
+const Claims = z.object({ sub: z.string(), role: Role, exp: z.number() });
+export type Claims = z.infer<typeof Claims>;
+
+const HEADER = Buffer.from(JSON.stringify({ alg: "HS256", typ: "JWT" })).toString("base64url");
+
+/** Signs and verifies HS256 JSON Web Tokens with `AUTH_SECRET`. */
+export class Tokens {
+  readonly #key = Buffer.from(env.AUTH_SECRET);
+
+  sign(subject: string, role: Role, ttlSeconds = env.AUTH_TOKEN_TTL_SECONDS): string {
+    const claims: Claims = { sub: subject, role, exp: Math.floor(Date.now() / 1000) + ttlSeconds };
+    const body = `${HEADER}.${Buffer.from(JSON.stringify(claims)).toString("base64url")}`;
+    return `${body}.${this.#signature(body)}`;
+  }
+
+  /** The token's claims, or `undefined` when it is malformed, forged or expired. */
+  verify(token: string): Claims | undefined {
+    const [header, payload, signature, ...rest] = token.split(".");
+    if (!header || !payload || !signature || rest.length > 0 || header !== HEADER) return undefined;
+    const expected = Buffer.from(this.#signature(`${header}.${payload}`));
+    const actual = Buffer.from(signature);
+    if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) return undefined;
+    try {
+      const claims = Claims.parse(JSON.parse(Buffer.from(payload, "base64url").toString("utf8")));
+      return claims.exp > Date.now() / 1000 ? claims : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
+  #signature(body: string): string {
+    return createHmac("sha256", this.#key).update(body).digest("base64url");
+  }
+}

package/starters/sqlite-auth/src/database/clock.ts

@@ -0,0 +1,4 @@
+import { defineToken } from "@raiyyan/brisk";
+
+/** The current time as a dependency, so tests can freeze it with `provide(Clock, () => fixedDate)`. */
+export const Clock = defineToken<() => Date>("Clock", () => () => new Date());

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

@@ -0,0 +1,29 @@
+import { DatabaseSync } from "node:sqlite";
+import { inject, Logger, type OnInit, type OnShutdown } from "@raiyyan/brisk";
+import { env } from "../env.ts";
+import { migrate } from "./migrations.ts";
+
+/**
+ * The app's SQLite connection (Node's built-in `node:sqlite`), opened at boot and closed on shutdown.
+ * Repositories inject it: `readonly #db = inject(Database)`, then `this.#db.sql.prepare(...)`.
+ */
+export class Database implements OnInit, OnShutdown {
+  readonly #log = inject(Logger);
+  #connection: DatabaseSync | undefined;
+
+  get sql(): DatabaseSync {
+    if (!this.#connection) throw new Error("Database used before the app booted");
+    return this.#connection;
+  }
+
+  onInit(): void {
+    this.#connection = new DatabaseSync(env.DATABASE_PATH);
+    this.#connection.exec("PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON; PRAGMA busy_timeout = 5000;");
+    migrate(this.#connection);
+    this.#log.info({ path: env.DATABASE_PATH }, "database opened");
+  }
+
+  onShutdown(): void {
+    this.#connection?.close();
+  }
+}

package/starters/sqlite-auth/src/database/errors.ts

@@ -0,0 +1,11 @@
+import { ConflictError, type ErrorMapper } from "@raiyyan/brisk";
+
+/** A unique constraint failed, here or in an error the driver wrapped: answer 409 instead of 500. */
+export const uniqueViolation: ErrorMapper = (error) => {
+  for (let current: unknown = error; current instanceof Error; current = current.cause) {
+    if ("errcode" in current && (current.errcode === 2067 || current.errcode === 1555)) {
+      return new ConflictError("Already exists", { code: "ALREADY_EXISTS", cause: error });
+    }
+  }
+  return undefined;
+};

package/starters/sqlite-auth/src/database/migrations.ts

@@ -0,0 +1,29 @@
+import type { DatabaseSync } from "node:sqlite";
+
+/** Schema changes in order. Append new ones (`brisk g feature` does); never edit one that has shipped. */
+const MIGRATIONS: readonly string[] = [
+  `CREATE TABLE users (
+    id TEXT PRIMARY KEY,
+    email TEXT NOT NULL UNIQUE,
+    name TEXT NOT NULL,
+    role TEXT NOT NULL CHECK (role IN ('user', 'admin')),
+    password_hash TEXT NOT NULL,
+    created_at TEXT NOT NULL
+  )`,
+  `CREATE TABLE notes (
+    id TEXT PRIMARY KEY,
+    name TEXT NOT NULL,
+    created_at TEXT NOT NULL
+  )`,
+  // @brisk:migrations
+];
+
+/** Applies the migrations this database has not seen, tracked with SQLite's `user_version`. */
+export function migrate(sql: DatabaseSync): void {
+  const row = sql.prepare("PRAGMA user_version").get();
+  const applied = typeof row?.["user_version"] === "number" ? row["user_version"] : 0;
+  for (const [index, migration] of MIGRATIONS.entries()) {
+    if (index < applied) continue;
+    sql.exec(`BEGIN; ${migration}; PRAGMA user_version = ${index + 1}; COMMIT;`);
+  }
+}

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

@@ -0,0 +1,17 @@
+import { defineEnv, z } from "@raiyyan/brisk";
+
+export const env = defineEnv({
+  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
+  PORT: z.coerce.number().int().positive().default(3000),
+  LOG_LEVEL: z.enum(["fatal", "error", "warn", "info", "debug", "trace", "silent"]).default("info"),
+  DATABASE_PATH: z.string().min(1).default("data.db"),
+  /** HMAC key for access tokens: 32+ random characters (`openssl rand -base64 48`). */
+  AUTH_SECRET: z.string().min(32),
+  AUTH_TOKEN_TTL_SECONDS: z.coerce.number().int().positive().default(3600),
+  /** Browser origin allowed to call the API, such as http://localhost:5173. */
+  WEB_ORIGIN: z.url().default("http://localhost:5173"),
+  RATE_LIMIT_PER_MINUTE: z.coerce.number().int().positive().default(300),
+  /** First admin, created at boot when no user has this email. Leave unset to skip. */
+  ADMIN_EMAIL: z.email().optional(),
+  ADMIN_PASSWORD: z.string().min(12).optional(),
+});

package/starters/sqlite-auth/src/features/auth/auth.controller.ts

@@ -0,0 +1,28 @@
+import { defineController, inject, UnauthorizedError, z } from "@raiyyan/brisk";
+import { Tokens } from "../../auth/tokens.ts";
+import { env } from "../../env.ts";
+import { UsersService } from "../users/users.service.ts";
+
+const LoginBody = z.object({ email: z.email(), password: z.string().min(1) });
+const TokenResponse = z.object({ token: z.string(), tokenType: z.literal("Bearer"), expiresIn: z.number() });
+
+export const authController = defineController({ prefix: "/auth" }, (route) => {
+  const users = inject(UsersService);
+  const tokens = inject(Tokens);
+
+  return {
+    login: route.post(
+      "/login",
+      { body: LoginBody, response: TokenResponse, status: 200 },
+      async ({ body }) => {
+        const user = await users.authenticate(body.email, body.password);
+        if (!user) throw new UnauthorizedError("Wrong email or password", { code: "INVALID_CREDENTIALS" });
+        return {
+          token: tokens.sign(user.id, user.role),
+          tokenType: "Bearer" as const,
+          expiresIn: env.AUTH_TOKEN_TTL_SECONDS,
+        };
+      },
+    ),
+  };
+});

package/starters/sqlite-auth/src/features/index.ts

@@ -0,0 +1,12 @@
+import { authController } from "./auth/auth.controller.ts";
+import { usersController } from "./users/users.controller.ts";
+import { notesController } from "./notes/notes.controller.ts";
+// @brisk:imports
+
+/** Every controller by name. The names are the typed client's top level: `api.users.get(...)`. */
+export const controllers = {
+  auth: authController,
+  users: usersController,
+  notes: notesController,
+  // @brisk:controllers
+};

package/starters/sqlite-auth/src/features/notes/notes.controller.ts

@@ -0,0 +1,39 @@
+import { defineController, inject } from "@raiyyan/brisk";
+import { authenticate } from "../../middlewares/authenticate.ts";
+import { page } from "../../schemas.ts";
+import {
+  CreateNoteBody,
+  NoteIdParams,
+  NoteResponse,
+  ListNotesQuery,
+  UpdateNoteBody,
+} from "./notes.schema.ts";
+import { NotesService } from "./notes.service.ts";
+
+export const notesController = defineController({ prefix: "/notes", use: [authenticate] }, (route) => {
+  const notes = inject(NotesService);
+
+  return {
+    list: route.get("/", { query: ListNotesQuery, response: page(NoteResponse) }, ({ query }) =>
+      notes.list(query),
+    ),
+
+    get: route.get("/:id", { params: NoteIdParams, response: NoteResponse }, ({ params }) =>
+      notes.get(params.id),
+    ),
+
+    create: route.post("/", { body: CreateNoteBody, response: NoteResponse }, ({ body }) =>
+      notes.create(body),
+    ),
+
+    update: route.patch(
+      "/:id",
+      { params: NoteIdParams, body: UpdateNoteBody, response: NoteResponse },
+      ({ params, body }) => notes.update(params.id, body),
+    ),
+
+    remove: route.delete("/:id", { params: NoteIdParams }, async ({ params }) => {
+      await notes.remove(params.id);
+    }),
+  };
+});

package/starters/sqlite-auth/src/features/notes/notes.repository.ts

@@ -0,0 +1,47 @@
+import { inject, z } from "@raiyyan/brisk";
+import { Database } from "../../database/database.ts";
+
+export interface Note {
+  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): Note => ({ id: row.id, name: row.name, createdAt: new Date(row.created_at) }));
+
+/** Data access only: SQL in, note rows out. No HTTP and no business rules. */
+export class NotesRepository {
+  readonly #db = inject(Database);
+
+  async list({ page, limit }: { page: number; limit: number }): Promise<{ items: Note[]; total: number }> {
+    const rows = this.#db.sql
+      .prepare("SELECT * FROM notes 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 notes").get();
+    return { items: rows.map((row) => Row.parse(row)), total: Number(counted?.["total"] ?? 0) };
+  }
+
+  async findById(id: string): Promise<Note | undefined> {
+    const row = this.#db.sql.prepare("SELECT * FROM notes WHERE id = ?").get(id);
+    return row === undefined ? undefined : Row.parse(row);
+  }
+
+  async insert(row: Note): Promise<Note> {
+    this.#db.sql
+      .prepare("INSERT INTO notes (id, name, created_at) VALUES (?, ?, ?)")
+      .run(row.id, row.name, row.createdAt.toISOString());
+    return row;
+  }
+
+  async update(row: Note): Promise<Note> {
+    this.#db.sql.prepare("UPDATE notes 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 notes WHERE id = ?").run(id).changes) > 0;
+  }
+}

package/starters/sqlite-auth/src/features/notes/notes.schema.ts

@@ -0,0 +1,24 @@
+import { z } from "@raiyyan/brisk";
+import { isoDate, PageQuery } from "../../schemas.ts";
+
+export const CreateNoteBody = 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 UpdateNoteBody = CreateNoteBody.partial();
+
+export const NoteIdParams = z.object({ id: z.uuid() });
+
+export const ListNotesQuery = PageQuery;
+
+/** What clients see of a note: fields not listed here never leave the server. */
+export const NoteResponse = z.object({
+  id: z.string(),
+  name: z.string(),
+  createdAt: isoDate(),
+});
+
+export type CreateNoteBody = z.infer<typeof CreateNoteBody>;
+export type UpdateNoteBody = z.infer<typeof UpdateNoteBody>;
+export type ListNotesQuery = z.infer<typeof ListNotesQuery>;

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

@@ -0,0 +1,33 @@
+import { randomUUID } from "node:crypto";
+import { inject, NotFoundError } from "@raiyyan/brisk";
+import { NotesRepository, type Note } from "./notes.repository.ts";
+import type { CreateNoteBody, ListNotesQuery, UpdateNoteBody } from "./notes.schema.ts";
+
+/** Business rules for notes. Throws errors the client understands; knows nothing about Express. */
+export class NotesService {
+  readonly #repository = inject(NotesRepository);
+
+  async list(query: ListNotesQuery) {
+    const { items, total } = await this.#repository.list(query);
+    return { items, total, page: query.page, limit: query.limit };
+  }
+
+  async get(id: string): Promise<Note> {
+    const row = await this.#repository.findById(id);
+    if (!row) throw new NotFoundError("Note not found", { details: { id } });
+    return row;
+  }
+
+  create(input: CreateNoteBody): Promise<Note> {
+    return this.#repository.insert({ id: randomUUID(), name: input.name, createdAt: new Date() });
+  }
+
+  async update(id: string, { name }: UpdateNoteBody): Promise<Note> {
+    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("Note not found", { details: { id } });
+  }
+}

package/starters/sqlite-auth/src/features/users/admin-seed.ts

@@ -0,0 +1,21 @@
+import { inject, Logger, type OnReady } from "@raiyyan/brisk";
+import { env } from "../../env.ts";
+import { UsersRepository } from "./users.repository.ts";
+import { UsersService } from "./users.service.ts";
+
+/**
+ * Creates the first admin from `ADMIN_EMAIL` and `ADMIN_PASSWORD` once the database is ready, unless that user
+ * exists. A provider class listed in `defineApp({ providers })`, so it runs even though nothing injects it.
+ */
+export class AdminSeed implements OnReady {
+  readonly #users = inject(UsersService);
+  readonly #repository = inject(UsersRepository);
+  readonly #log = inject(Logger);
+
+  async onReady(): Promise<void> {
+    const { ADMIN_EMAIL: email, ADMIN_PASSWORD: password } = env;
+    if (!email || !password || this.#repository.findByEmail(email.toLowerCase())) return;
+    await this.#users.create({ email, password, name: "Admin", role: "admin" });
+    this.#log.info({ email }, "admin created");
+  }
+}

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

@@ -0,0 +1,42 @@
+import { defineController, inject } from "@raiyyan/brisk";
+import { authenticate, requireRole } from "../../middlewares/authenticate.ts";
+import {
+  CreateUserBody,
+  ListUsersQuery,
+  UpdateUserBody,
+  UserIdParams,
+  UserResponse,
+} from "./users.schema.ts";
+import { UsersService } from "./users.service.ts";
+
+const admin = requireRole("admin");
+
+export const usersController = defineController({ prefix: "/users", use: [authenticate] }, (route) => {
+  const users = inject(UsersService);
+
+  return {
+    me: route.get("/me", { response: UserResponse }, ({ user }) => users.get(user.id)),
+
+    list: route.get("/", { query: ListUsersQuery, response: UserResponse.array() }, ({ query }) =>
+      users.list(query),
+    ),
+
+    get: route.get("/:id", { params: UserIdParams, response: UserResponse }, ({ params }) =>
+      users.get(params.id),
+    ),
+
+    create: route.post("/", { use: [admin], body: CreateUserBody, response: UserResponse }, ({ body }) =>
+      users.create(body),
+    ),
+
+    update: route.patch(
+      "/:id",
+      { use: [admin], params: UserIdParams, body: UpdateUserBody, response: UserResponse },
+      ({ params, body }) => users.update(params.id, body),
+    ),
+
+    remove: route.delete("/:id", { use: [admin], params: UserIdParams }, ({ params }) => {
+      users.remove(params.id);
+    }),
+  };
+});

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

@@ -0,0 +1,13 @@
+import { ConflictError, NotFoundError } from "@raiyyan/brisk";
+
+export class UserNotFoundError extends NotFoundError {
+  constructor(id: string) {
+    super("User not found", { code: "USER_NOT_FOUND", details: { id } });
+  }
+}
+
+export class EmailTakenError extends ConflictError {
+  constructor(email: string) {
+    super("Email already registered", { code: "EMAIL_TAKEN", details: { email } });
+  }
+}

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

@@ -0,0 +1,77 @@
+import { inject, z } from "@raiyyan/brisk";
+import { Role } from "../../auth/tokens.ts";
+import { Database } from "../../database/database.ts";
+
+export interface User {
+  id: string;
+  email: string;
+  name: string;
+  role: Role;
+  passwordHash: string;
+  createdAt: Date;
+}
+
+/** A row as SQLite returns it, checked once at the boundary instead of cast. */
+const Row = z
+  .object({
+    id: z.string(),
+    email: z.string(),
+    name: z.string(),
+    role: Role,
+    password_hash: z.string(),
+    created_at: z.string(),
+  })
+  .transform((row): User => ({
+    id: row.id,
+    email: row.email,
+    name: row.name,
+    role: row.role,
+    passwordHash: row.password_hash,
+    createdAt: new Date(row.created_at),
+  }));
+
+/** Data access only: SQL in, users out. No HTTP and no business rules. */
+export class UsersRepository {
+  readonly #db = inject(Database);
+
+  findMany({ search, limit }: { search?: string | undefined; limit: number }): User[] {
+    const term = `%${(search ?? "").toLowerCase()}%`;
+    const rows = this.#db.sql
+      .prepare("SELECT * FROM users WHERE lower(name) LIKE ? OR email LIKE ? ORDER BY created_at, id LIMIT ?")
+      .all(term, term, limit);
+    return rows.map((row) => Row.parse(row));
+  }
+
+  findById(id: string): User | undefined {
+    return this.#one("SELECT * FROM users WHERE id = ?", id);
+  }
+
+  findByEmail(email: string): User | undefined {
+    return this.#one("SELECT * FROM users WHERE email = ?", email);
+  }
+
+  insert(user: User): User {
+    this.#db.sql
+      .prepare(
+        "INSERT INTO users (id, email, name, role, password_hash, created_at) VALUES (?, ?, ?, ?, ?, ?)",
+      )
+      .run(user.id, user.email, user.name, user.role, user.passwordHash, user.createdAt.toISOString());
+    return user;
+  }
+
+  update(user: User): User {
+    this.#db.sql
+      .prepare("UPDATE users SET email = ?, name = ? WHERE id = ?")
+      .run(user.email, user.name, user.id);
+    return user;
+  }
+
+  delete(id: string): boolean {
+    return Number(this.#db.sql.prepare("DELETE FROM users WHERE id = ?").run(id).changes) > 0;
+  }
+
+  #one(query: string, value: string): User | undefined {
+    const row = this.#db.sql.prepare(query).get(value);
+    return row === undefined ? undefined : Row.parse(row);
+  }
+}

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

@@ -0,0 +1,35 @@
+import { z } from "@raiyyan/brisk";
+import { isoDate } from "../../schemas.ts";
+import { Role } from "../../auth/tokens.ts";
+
+export const CreateUserBody = z.object({
+  email: z.email().toLowerCase(),
+  name: z.string().trim().min(1).max(100),
+  password: z.string().min(12).max(128),
+  role: Role.default("user"),
+});
+
+export const UpdateUserBody = z.object({
+  email: z.email().toLowerCase().optional(),
+  name: z.string().trim().min(1).max(100).optional(),
+});
+
+export const UserIdParams = z.object({ id: z.uuid() });
+
+export const ListUsersQuery = z.object({
+  search: z.string().trim().max(100).optional(),
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+});
+
+/** Public shape of a user. Anything not listed, such as the password hash, never reaches a client. */
+export const UserResponse = z.object({
+  id: z.string(),
+  email: z.string(),
+  name: z.string(),
+  role: Role,
+  createdAt: isoDate(),
+});
+
+export type CreateUserBody = z.infer<typeof CreateUserBody>;
+export type UpdateUserBody = z.infer<typeof UpdateUserBody>;
+export type ListUsersQuery = z.infer<typeof ListUsersQuery>;