@dunx/create-app 0.4.0 → 0.5.0

package/templates/features/auth/auth.demo.ts

@@ -0,0 +1,173 @@
+import { Auth } from '@dunx/auth';
+import { Logger } from '@dunx/core';
+import { SyncDatabase } from '@dunx/infra/db';
+import { eq } from 'drizzle-orm';
+import * as schema from '../database/schema.js';
+import { user } from '../database/schema.js';
+
+const CREDENTIALS = {
+  email: 'ada@example.com',
+  password: 'correct horse battery',
+  name: 'Ada',
+};
+
+/**
+ * The whole loop over HTTP: better-auth's own mounted endpoints sign a user up and
+ * in, then dunx's `SessionGuard` decides who reaches `/api/profile`. Nothing here
+ * reimplements an auth flow - every `/api/auth/*` call lands in better-auth.
+ */
+export class AuthDemo {
+  constructor(
+    private readonly logger: Logger,
+    private readonly auth: Auth,
+    private readonly db: SyncDatabase<typeof schema>,
+  ) {}
+
+  /** What `Origin` has to be for better-auth's CSRF check - see {@link post}. */
+  #origin = '';
+
+  async demonstrate(url: string): Promise<void> {
+    const base = new URL(url).origin;
+    // `$context` is where the resolved configuration lands; `options.baseURL` is
+    // whatever was passed in, which better-auth also allows to be a function.
+    this.#origin = (await this.auth.$context).baseURL;
+    this.logger.info(
+      `better-auth ${this.auth.options.basePath} mounted, hashing with Bun.password bcrypt`,
+    );
+
+    await this.report(
+      'POST /api/auth/sign-up/email',
+      await this.post(base, 'sign-up/email', CREDENTIALS),
+    );
+
+    const signIn = await this.post(base, 'sign-in/email', {
+      email: CREDENTIALS.email,
+      password: CREDENTIALS.password,
+    });
+    await this.report('POST /api/auth/sign-in/email', signIn);
+
+    // The `bearer` plugin returns the session token in a header, so a server-side
+    // client authenticates without a cookie jar.
+    const token = signIn.headers.get('set-auth-token') ?? '';
+    const cookie = signIn.headers
+      .getSetCookie()
+      .map((entry) => entry.split(';')[0])
+      .join('; ');
+
+    await this.call('GET /api/profile, no credentials', base, '/api/profile');
+    await this.call(
+      'GET /api/profile with the session cookie',
+      base,
+      '/api/profile',
+      {
+        cookie,
+      },
+    );
+    await this.call(
+      'GET /api/profile with a bearer token',
+      base,
+      '/api/profile',
+      {
+        authorization: `Bearer ${token}`,
+      },
+    );
+
+    await this.call(
+      '@Roles("admin") GET /api/profile/audit as "user"',
+      base,
+      '/api/profile/audit',
+      {
+        cookie,
+      },
+    );
+
+    // What an admin console would do. The `admin` plugin's own `setRole` endpoint
+    // needs an existing admin to call it, and there is none yet.
+    this.db
+      .update(user)
+      .set({ role: 'admin' })
+      .where(eq(user.email, CREDENTIALS.email))
+      .run();
+    this.logger.info(
+      'promoted ada@example.com to role "admin" through drizzle',
+    );
+
+    await this.call(
+      '@Roles("admin") GET /api/profile/audit as "admin"',
+      base,
+      '/api/profile/audit',
+      {
+        cookie,
+      },
+    );
+    await this.call(
+      '@Public() GET /api/profile/anonymous, cookie ignored',
+      base,
+      '/api/profile/anonymous',
+      {
+        cookie,
+      },
+    );
+
+    await this.report(
+      'POST /api/auth/sign-out',
+      await this.post(base, 'sign-out', {}, { cookie }),
+    );
+    await this.call(
+      'GET /api/profile after signing out',
+      base,
+      '/api/profile',
+      {
+        cookie,
+      },
+    );
+
+    // The instance is injectable, so a service can ask better-auth directly rather
+    // than going over HTTP.
+    const session = await this.auth.api.getSession({
+      headers: new Headers({ cookie }),
+    });
+    this.logger.info(
+      `auth.api.getSession() after sign-out -> ${session === null ? 'null' : 'still live'}`,
+    );
+  }
+
+  /**
+   * `Origin` is set because better-auth rejects a cookie-bearing state change without
+   * one - `MISSING_OR_NULL_ORIGIN`, its CSRF check. A browser sends it for free; a
+   * server-side client has to, and the value that has to match is `trustedOrigins`,
+   * which defaults to the configured `baseURL`.
+   */
+  private post(
+    base: string,
+    endpoint: string,
+    body: unknown,
+    headers: Record<string, string> = {},
+  ): Promise<Response> {
+    return fetch(`${base}/api/auth/${endpoint}`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        origin: this.#origin,
+        ...headers,
+      },
+      body: JSON.stringify(body),
+    });
+  }
+
+  private async call(
+    label: string,
+    base: string,
+    path: string,
+    headers: Record<string, string> = {},
+  ): Promise<void> {
+    await this.report(label, await fetch(`${base}${path}`, { headers }));
+  }
+
+  private async report(label: string, response: Response): Promise<void> {
+    const text = await response.text();
+    this.logger.info(
+      `${label} -> ${response.status} ${text.length > 220 ? `${text.slice(0, 220)}…` : text}`,
+    );
+  }
+}

package/templates/features/auth/auth.module.ts

@@ -0,0 +1,54 @@
+import { AuthModule, bunPassword } from '@dunx/auth';
+import { drizzleDatabase } from '@dunx/auth/drizzle';
+import { Module } from '@dunx/core';
+import { DbConnection } from '@dunx/infra/db';
+import { admin, bearer } from 'better-auth/plugins';
+import { AppConfigService } from '../config.js';
+import { AuthDemo } from './auth.demo.js';
+import { AuthTables } from './auth.tables.js';
+import { Audit } from './audit.service.js';
+import { ProfileController } from './profile.controller.js';
+
+/** Named for the feature rather than the package, so `AuthModule` still means `@dunx/auth`'s. */
+@Module({
+  imports: [
+    // `forRootAsync` because the secret and the base URL come from the validated
+    // config, and the database from the connection `DatabaseModule` already opened -
+    // none of which a zero-argument factory could reach.
+    AuthModule.forRootAsync(
+      {
+        useFactory: (config: AppConfigService, connection: DbConnection) => ({
+          secret: config.get('auth').secret,
+          baseURL: `http://localhost:${config.get('port')}`,
+          // What better-auth matches an incoming pathname against. `app.setGlobalPrefix('api')`
+          // is what makes the mounted `/auth` route answer here.
+          basePath: '/api/auth',
+          // The app's one drizzle handle. No second pool, no second SQLite file, and
+          // the connection still closes exactly once, last.
+          database: drizzleDatabase(connection),
+          // `password: bunPassword` is what `AuthModule` would apply anyway when
+          // `emailAndPassword` is on and no hasher is given - named here so it is
+          // visible. better-auth's own default is a pure-JavaScript scrypt;
+          // `bunPassword` is `Bun.password`'s native bcrypt, which is Rule 1's
+          // first half. Bun pre-hashes, so bcrypt's 72-byte cap is a non-issue.
+          emailAndPassword: {
+            enabled: true,
+            minPasswordLength: 8,
+            password: bunPassword,
+          },
+          // `admin` puts `role` on the user, which `@Roles()` then reads. `bearer`
+          // lets a non-browser client send `Authorization: Bearer <token>` instead of
+          // a cookie - which is what the tour does.
+          plugins: [admin(), bearer()],
+        }),
+        inject: [AppConfigService, DbConnection] as const,
+      },
+      // The route path. The global prefix turns it into `/api/auth`, the `basePath`
+      // above - see AuthOptions.mountAt.
+      '/auth',
+    ),
+  ],
+  controllers: [ProfileController],
+  providers: [AuthTables, Audit, AuthDemo],
+})
+export class AccountsModule {}

package/templates/features/auth/auth.tables.ts

@@ -0,0 +1,84 @@
+import { Logger, type OnInit } from '@dunx/core';
+import { SyncDatabase } from '@dunx/infra/db';
+import { sql } from 'drizzle-orm';
+import * as schema from '../database/schema.js';
+
+/**
+ * better-auth's tables, created at `onInit` for the same reason `Ledger` creates its
+ * own: a `:memory:` database has nowhere to keep a migration journal. A real app runs
+ * `bunx @better-auth/cli generate` and then `drizzle-kit`, which own the SQL.
+ *
+ * The column names are drizzle's defaults for the schema in `database/auth.schema.ts`
+ * - camelCase, because that file passes no explicit names.
+ */
+/**
+ * One statement per entry, not one template with four. `db.run` goes through
+ * `bun:sqlite`'s `prepare`, which compiles a single statement and silently drops
+ * whatever follows the first semicolon - the table after it simply never exists.
+ */
+const TABLES = [
+  sql`CREATE TABLE IF NOT EXISTS user (
+    id TEXT PRIMARY KEY NOT NULL,
+    name TEXT NOT NULL,
+    email TEXT NOT NULL UNIQUE,
+    emailVerified INTEGER NOT NULL DEFAULT 0,
+    image TEXT,
+    role TEXT,
+    banned INTEGER,
+    banReason TEXT,
+    banExpires INTEGER,
+    createdAt INTEGER NOT NULL,
+    updatedAt INTEGER NOT NULL
+  )`,
+  sql`CREATE TABLE IF NOT EXISTS session (
+    id TEXT PRIMARY KEY NOT NULL,
+    token TEXT NOT NULL UNIQUE,
+    userId TEXT NOT NULL REFERENCES user(id) ON DELETE CASCADE,
+    expiresAt INTEGER NOT NULL,
+    ipAddress TEXT,
+    userAgent TEXT,
+    impersonatedBy TEXT,
+    createdAt INTEGER NOT NULL,
+    updatedAt INTEGER NOT NULL
+  )`,
+  sql`CREATE TABLE IF NOT EXISTS account (
+    id TEXT PRIMARY KEY NOT NULL,
+    accountId TEXT NOT NULL,
+    providerId TEXT NOT NULL,
+    userId TEXT NOT NULL REFERENCES user(id) ON DELETE CASCADE,
+    accessToken TEXT,
+    refreshToken TEXT,
+    idToken TEXT,
+    accessTokenExpiresAt INTEGER,
+    refreshTokenExpiresAt INTEGER,
+    scope TEXT,
+    password TEXT,
+    createdAt INTEGER NOT NULL,
+    updatedAt INTEGER NOT NULL
+  )`,
+  sql`CREATE TABLE IF NOT EXISTS verification (
+    id TEXT PRIMARY KEY NOT NULL,
+    identifier TEXT NOT NULL,
+    value TEXT NOT NULL,
+    expiresAt INTEGER NOT NULL,
+    createdAt INTEGER NOT NULL,
+    updatedAt INTEGER NOT NULL
+  )`,
+];
+
+export class AuthTables implements OnInit {
+  constructor(
+    private readonly db: SyncDatabase<typeof schema>,
+    private readonly logger: Logger,
+  ) {}
+
+  /**
+   * `onInit`, not the module factory: `betterAuth()` opens no connection and issues
+   * no query when it is built, so the tables only have to exist before the first
+   * request - and this runs before `listen()` binds.
+   */
+  onInit(): void {
+    for (const table of TABLES) this.db.run(table);
+    this.logger.info(`better-auth tables created (${TABLES.length})`);
+  }
+}

package/templates/features/auth/profile.controller.ts

@@ -0,0 +1,37 @@
+import { Controller, Get, Public, Roles, UseGuards } from '@dunx/http';
+import { SessionGuard } from '@dunx/auth';
+import { Audit } from './audit.service.js';
+
+/**
+ * `@UseGuards(SessionGuard)` at class scope rather than global middleware, exactly as
+ * `ReportsController` does with its hand-rolled guard: every other route in this app
+ * is meant to be reachable without credentials.
+ *
+ * Nothing here is handed a user. `Audit` reads the caller out of `AuthContext`, which
+ * is `AsyncLocalStorage` - so a service two hops from the request sees the principal
+ * without it being threaded through a signature.
+ */
+@UseGuards(SessionGuard)
+@Controller('profile')
+export class ProfileController {
+  constructor(private readonly audit: Audit) {}
+
+  @Get('/')
+  me(): { email: string; roles: readonly string[]; sessionId: string } {
+    return this.audit.whoami();
+  }
+
+  /** The class guard reads this and 403s unless the caller holds `admin`. */
+  @Roles('admin')
+  @Get('/audit')
+  entries(): { caller: string; entries: readonly string[] } {
+    return this.audit.report();
+  }
+
+  /** The class guard reads this and skips: no session looked up, no rejection. */
+  @Public()
+  @Get('/anonymous')
+  anonymous(): { caller: string | null } {
+    return { caller: this.audit.caller() };
+  }
+}

package/templates/features/cache/cache.controller.ts

@@ -0,0 +1,85 @@
+import {
+  Controller,
+  Delete,
+  Get,
+  HttpError,
+  HttpStatusCode,
+  Put,
+  type Input,
+} from '@dunx/http';
+import { z } from 'zod';
+import { Sessions } from './sessions.service.js';
+
+const SessionKey = z
+  .object({ id: z.string().min(1).max(80) })
+  .meta({ id: 'SessionKey', title: 'A session id' });
+
+const StoreSession = z
+  .object({
+    data: z.record(z.string(), z.unknown()),
+    ttl: z.coerce.number().int().min(1).max(3600).default(60),
+  })
+  .meta({ id: 'StoreSession', title: 'Session payload and its lifetime' });
+
+const oneSession = { params: SessionKey } as const;
+const putSession = { params: SessionKey, body: StoreSession } as const;
+
+/**
+ * Every route here answers **503 with the connection error's own message** when
+ * no Redis is running, rather than 500 - a cache that is not up is a degraded
+ * service, not a bug, and `bun start` must still boot without one.
+ */
+@Controller('cache')
+export class CacheController {
+  constructor(private readonly sessions: Sessions) {}
+
+  @Get('/', {})
+  async status(): Promise<{ url: string; reachable: boolean; note?: string }> {
+    return this.sessions.status();
+  }
+
+  @Get('/:id', oneSession)
+  async read(
+    input: Input<typeof oneSession>,
+  ): Promise<{ id: string; data: unknown; ttl: number }> {
+    const found = await this.degrades(() =>
+      this.sessions.read(input.params.id),
+    );
+    if (found === null) {
+      throw new HttpError(
+        HttpStatusCode.NOT_FOUND,
+        `No session "${input.params.id}"`,
+      );
+    }
+    return found;
+  }
+
+  @Put('/:id', putSession)
+  store(
+    input: Input<typeof putSession>,
+  ): Promise<{ id: string; ttl: number; visits: number }> {
+    return this.degrades(() =>
+      this.sessions.store(input.params.id, input.body.data, input.body.ttl),
+    );
+  }
+
+  @Delete('/:id', oneSession)
+  remove(input: Input<typeof oneSession>): Promise<{ removed: number }> {
+    return this.degrades(() => this.sessions.remove(input.params.id));
+  }
+
+  private async degrades<T>(run: () => Promise<T>): Promise<T> {
+    try {
+      return await run();
+    } catch (error) {
+      // Bun raises some of these synchronously, which is why the wrapper catches
+      // around the call rather than relying on the promise rejecting.
+      if (error instanceof HttpError) throw error;
+      if (!this.sessions.isDown(error)) throw error;
+      throw new HttpError(
+        HttpStatusCode.SERVICE_UNAVAILABLE,
+        `Cache unavailable: ${(error as Error).message}`,
+      );
+    }
+  }
+}

package/templates/features/cache/cache.module.ts

@@ -0,0 +1,36 @@
+import { Module } from '@dunx/core';
+import { RedisModule } from '@dunx/infra/redis';
+import { AppConfigService } from '../config.js';
+import { CacheController } from './cache.controller.js';
+import { Sessions } from './sessions.service.js';
+
+@Module({
+  imports: [
+    // Without a url Bun's own chain decides it - $VALKEY_URL, then $REDIS_URL,
+    // then valkey://localhost:6379. Connections are lazy, so nothing is dialled
+    // here and an unavailable cache cannot stop the process from booting.
+    // `eager: true` would opt into finding out at startup, which is the opposite
+    // of the point: the cache routes report themselves degraded instead.
+    //
+    // `maxRetries: 0` is not just impatience: measured on Bun 1.3.14, a client
+    // that failed to connect with `maxRetries > 0` keeps a retry timer alive even
+    // after `close()`, and the process never exits. With 0 it exits cleanly.
+    RedisModule.forRootAsync({
+      useFactory: (config: AppConfigService) => {
+        // Destructured first: `exactOptionalPropertyTypes` will not let a
+        // `string | undefined` reach a `url?: string`, even inside the branch
+        // that has already ruled `undefined` out.
+        const { url } = config.get('redis');
+        return {
+          ...(url === undefined ? {} : { url }),
+          connectionTimeout: 500,
+          maxRetries: 0,
+        };
+      },
+      inject: [AppConfigService] as const,
+    }),
+  ],
+  controllers: [CacheController],
+  providers: [Sessions],
+})
+export class CacheModule {}

package/templates/features/cache/sessions.service.ts

@@ -0,0 +1,90 @@
+import { Logger } from '@dunx/core';
+import {
+  isConnectionError,
+  RedisConnection,
+  RedisOptions,
+} from '@dunx/infra/redis';
+
+export class Sessions {
+  // Namespaced by pid so one run cannot read another run's keys.
+  readonly #prefix = `dunx-full:${process.pid}`;
+
+  constructor(
+    private readonly redis: RedisConnection,
+    private readonly options: RedisOptions,
+    private readonly logger: Logger,
+  ) {}
+
+  /** Whether a thrown value means "the cache is down" rather than "the call was wrong". */
+  isDown(error: unknown): boolean {
+    return isConnectionError(error);
+  }
+
+  async status(): Promise<{ url: string; reachable: boolean; note?: string }> {
+    try {
+      await this.redis.ping();
+      return { url: this.options.url, reachable: true };
+    } catch (error) {
+      if (!this.isDown(error)) throw error;
+      return {
+        url: this.options.url,
+        reachable: false,
+        note: `${(error as Error).message}. A cache that is not running must not fail the app.`,
+      };
+    }
+  }
+
+  async read(
+    id: string,
+  ): Promise<{ id: string; data: unknown; ttl: number } | null> {
+    const key = this.#key(id);
+    const raw = await this.redis.get(key);
+    if (raw === null) return null;
+    return { id, data: JSON.parse(raw), ttl: await this.redis.ttl(key) };
+  }
+
+  /** SET takes an options object rather than Bun's positional overloads. */
+  async store(
+    id: string,
+    data: Record<string, unknown>,
+    ttl: number,
+  ): Promise<{ id: string; ttl: number; visits: number }> {
+    await this.redis.set(this.#key(id), JSON.stringify(data), { ex: ttl });
+    const visits = await this.redis.incr(`${this.#prefix}:visits`);
+    return { id, ttl, visits };
+  }
+
+  async remove(id: string): Promise<{ removed: number }> {
+    return { removed: await this.redis.del(this.#key(id)) };
+  }
+
+  async demonstrate(): Promise<void> {
+    const { redis, logger } = this;
+    const session = this.#key('demo');
+    const visits = `${this.#prefix}:visits`;
+
+    try {
+      logger.info(`PING ${this.options.url} -> ${await redis.ping()}`);
+
+      await redis.set(session, JSON.stringify({ user: 'ada' }), { ex: 60 });
+      logger.info(
+        `SET/GET session -> ${await redis.get(session)}, ` +
+          `ttl ${await redis.ttl(session)}s`,
+      );
+      logger.info(`INCR visits -> ${await redis.incr(visits)}`);
+      logger.info(`DEL -> ${await redis.del(session, visits)} keys removed`);
+    } catch (error) {
+      // Bun raises some of these synchronously, so the wrapper catches around
+      // the call and a caller only ever sees a rejection.
+      if (!this.isDown(error)) throw error;
+      logger.warn(
+        `skipping redis at ${this.options.url}: ${(error as Error).message}`,
+      );
+      logger.info('a cache that is not running must not fail the app');
+    }
+  }
+
+  #key(id: string): string {
+    return `${this.#prefix}:session:${id}`;
+  }
+}