@podosoft/podokit 0.17.4 → 1.0.2

package/dist/templates/modules/audit-log/files/apps/api/src/audit/README.md

@@ -12,20 +12,21 @@ which the better-auth hook (`audit-hook.ts`) maps to semantic action codes like
 `user.create` and `auth.login`. Everything else is **opt-in** — you decide what
 matters.
 
-## Audit your own routes with `@Audit`
+## Audit your own Elysia routes
 
 ```ts
-import { Audit } from "../audit/audit.decorator";
-
-@Post()
-@Audit("todo.create", (_req, todo) => ({ type: "todo", id: todo.id, label: todo.title }))
-create(@Body() dto: CreateTodoDto) {
-  return this.todos.create(dto);
-}
+const session = await auth.requireSession(request);
+const todo = await todos.create(body);
+await audit.recordRequest("todo.create", request, session, {
+  type: "todo",
+  id: todo.id,
+  label: todo.title,
+});
+return todo;
 ```
 
-The interceptor resolves the acting user (name + email), attaches the target you
-return, and writes one entry when the handler succeeds.
+Call `recordRequest` only after the operation succeeds. It attaches the actor and
+request address, then writes the target metadata through the shared pipeline.
 
 ## Record from anywhere in code
 
@@ -40,8 +41,8 @@ await recordAudit({
 });
 ```
 
-Or inject `AuditService` in a Nest provider and call `audit.record({ ... })`.
-Both never throw — a failed audit write never breaks the request.
+Resolve `AUDIT` from the application service registry to call
+`audit.record({ ... })`. Audit writes never break the request.
 
 ## Fields (`AuditEntry`)
 
@@ -52,8 +53,8 @@ survives renames/deletes), `targetType/targetId/targetLabel`, `ip`, `metadata`
 ## Customize
 
 - **Auth actions:** edit the `ACTIONS` map in `audit-hook.ts`.
-- **Your routes:** add `@Audit("your.action")` where you want a trail.
-- **Schema:** add columns to `audit-log.entity.ts` + a migration, and keep the
+- **Your routes:** call `AuditService.recordRequest()` after successful operations.
+- **Schema:** add columns with a migration, and keep the
   `AuditEntry` type in `audit-events.ts` in sync.
-- **Reading:** `GET /audit-logs` returns the latest 50 (admin only); extend
-  `audit.controller.ts` for filtering/pagination.
+- **Reading:** `GET /audit-logs` returns the latest 50 (admin only); extend the
+  Elysia plugin in `audit.module.ts` for filtering or pagination.

package/dist/templates/modules/audit-log/files/apps/api/src/audit/audit-events.ts

@@ -1,5 +1,5 @@
-// One audit pipeline for the whole app. Every source — the @Audit decorator, the
-// better-auth hook, and your own code — records through here, so all entries
+// One audit pipeline for the whole app. Better Auth hooks and application code
+// record through here, so all entries
 // share the actor/action/target shape and one write path (audit_logs).
 
 export type AuditEntry = {
@@ -18,11 +18,13 @@ export type AuditEntry = {
 type Recorder = (entry: AuditEntry) => Promise<void>;
 let recorder: Recorder | null = null;
 
-// AuditService registers the real recorder on startup. The registry lives outside
-// Nest's DI so code that runs outside the container (the better-auth hook,
-// background jobs, ...) can still write through the one pipeline.
-export function setAuditRecorder(fn: Recorder): void {
+// AuditService registers the recorder during Elysia configuration. The registry
+// stays available to Better Auth hooks and background jobs.
+export function setAuditRecorder(fn: Recorder): () => void {
   recorder = fn;
+  return () => {
+    if (recorder === fn) recorder = null;
+  };
 }
 
 // Record a custom audit event from anywhere. Awaits the write; a no-op until the

package/dist/templates/modules/audit-log/files/apps/api/src/audit/audit-hook.ts

@@ -3,8 +3,8 @@ import { recordAudit } from "./audit-events";
 import { auditEnabled } from "./audit-enabled";
 
 // Map mutating auth/admin endpoints to semantic action codes. better-auth is
-// mounted as middleware and bypasses the NestJS interceptor, so these security
-// events are caught here and recorded through the same pipeline.
+// mounted directly in Elysia, so these security events are recorded through the
+// same application audit pipeline.
 const ACTIONS: Record<string, string> = {
   "/sign-in/email": "auth.login",
   "/sign-up/email": "auth.signup",

package/dist/templates/modules/audit-log/files/apps/api/src/audit/audit.module.ts

@@ -1,14 +1,33 @@
-import { Module } from "@nestjs/common";
-import { APP_INTERCEPTOR } from "@nestjs/core";
-import { TypeOrmModule } from "@nestjs/typeorm";
-import { AuditController } from "./audit.controller";
-import { AuditInterceptor } from "./audit.interceptor";
+import { Elysia } from "elysia";
+import { AUTH } from "../auth/auth.module";
+import {
+  DATABASE,
+  type AppPlugin,
+  type PodokitModule,
+  type ServiceKey,
+} from "../core/services";
 import { AuditService } from "./audit.service";
-import { AuditLog } from "./audit-log.entity";
 
-@Module({
-  imports: [TypeOrmModule.forFeature([AuditLog])],
-  controllers: [AuditController],
-  providers: [AuditService, { provide: APP_INTERCEPTOR, useClass: AuditInterceptor }],
-})
-export class AuditModule {}
+export const AUDIT = Symbol("audit") as ServiceKey<AuditService>;
+
+const auditPlugin: AppPlugin = ({ services }) => {
+  const auth = services.resolve(AUTH);
+  const audit = services.resolve(AUDIT);
+  return new Elysia({ name: "podokit.audit" })
+    .get("/audit-logs", async ({ request }) => {
+      await auth.requireAdmin(request);
+      return audit.recent();
+    }, {
+      detail: { tags: ["audit"], summary: "List recent audit entries" },
+    });
+};
+
+export const auditModule: PodokitModule = {
+  name: "audit-log",
+  configure: (_env, services): void => {
+    const audit = new AuditService(services.resolve(DATABASE).sql);
+    services.register(AUDIT, audit, () => audit.close());
+    services.onStart(() => audit.connect());
+  },
+  plugin: auditPlugin,
+};

package/dist/templates/modules/audit-log/files/apps/api/src/audit/audit.service.spec.ts

@@ -0,0 +1,48 @@
+import { describe, expect, mock, test } from "bun:test";
+import type { SQL } from "bun";
+import { recordAudit } from "./audit-events";
+import { AuditService } from "./audit.service";
+
+function sqlRecorder(rows: unknown[] = []): { sql: SQL; values: unknown[][] } {
+  const values: unknown[][] = [];
+  const tag = mock((_strings: TemplateStringsArray, ...parameters: unknown[]) => {
+    values.push(parameters);
+    return Promise.resolve(rows);
+  });
+  return { sql: tag as unknown as SQL, values };
+}
+
+describe("AuditService", () => {
+  test("writes global audit events through one recorder", async () => {
+    const recorder = sqlRecorder();
+    const service = new AuditService(recorder.sql);
+    service.connect();
+    try {
+      await recordAudit({
+        action: "invoice.paid",
+        actorId: "user-1",
+        metadata: { amount: 42 },
+      });
+      expect(recorder.values).toHaveLength(1);
+      expect(recorder.values[0]).toContain("invoice.paid");
+      expect(recorder.values[0]).toContain('{"amount":42}');
+    } finally {
+      service.close();
+    }
+  });
+
+  test("returns recent entries with serialized timestamps", async () => {
+    const recorder = sqlRecorder([{
+      id: "audit-1",
+      action: "auth.login",
+      createdAt: new Date("2026-01-02T03:04:05.000Z"),
+    }]);
+    const entries = await new AuditService(recorder.sql).recent();
+    expect(entries[0]?.createdAt).toBe("2026-01-02T03:04:05.000Z");
+  });
+
+  test("does not propagate persistence failures", async () => {
+    const sql = mock(() => Promise.reject(new Error("database unavailable"))) as unknown as SQL;
+    await expect(new AuditService(sql).record({ action: "auth.login" })).resolves.toBeUndefined();
+  });
+});

package/dist/templates/modules/audit-log/files/apps/api/src/audit/audit.service.ts

@@ -1,36 +1,87 @@
-import { Injectable, type OnModuleInit } from "@nestjs/common";
-import { InjectRepository } from "@nestjs/typeorm";
-import { Repository } from "typeorm";
-import { AuditLog } from "./audit-log.entity";
+import type { SQL } from "bun";
+import type { AuthSession } from "../auth/auth.service";
+import { auditEnabled } from "./audit-enabled";
 import { setAuditRecorder, type AuditEntry } from "./audit-events";
 
-// The one place audit entries are written. Inject it to record from Nest code,
-// or call recordAudit() from anywhere else — both end up here.
-@Injectable()
-export class AuditService implements OnModuleInit {
-  constructor(@InjectRepository(AuditLog) private readonly logs: Repository<AuditLog>) {}
+export interface AuditLogView extends AuditEntry {
+  id: string;
+  createdAt: string;
+}
+
+interface AuditLogRow extends Omit<AuditLogView, "createdAt"> {
+  createdAt: Date;
+}
+
+export interface AuditTarget {
+  type?: string;
+  id?: string;
+  label?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export class AuditService {
+  private unregister?: () => void;
+
+  constructor(private readonly sql: SQL) {}
 
-  onModuleInit(): void {
-    setAuditRecorder((entry) => this.record(entry));
+  connect(): void {
+    this.unregister ??= setAuditRecorder((entry) => this.record(entry));
+  }
+
+  close(): void {
+    this.unregister?.();
+    this.unregister = undefined;
   }
 
   async record(entry: AuditEntry): Promise<void> {
     try {
-      await this.logs.save(
-        this.logs.create({
-          action: entry.action,
-          actorId: entry.actorId ?? null,
-          actorName: entry.actorName ?? null,
-          actorEmail: entry.actorEmail ?? null,
-          targetType: entry.targetType ?? null,
-          targetId: entry.targetId ?? null,
-          targetLabel: entry.targetLabel ?? null,
-          ip: entry.ip ?? null,
-          metadata: entry.metadata ?? null,
-        }),
-      );
+      const metadata = entry.metadata === undefined || entry.metadata === null
+        ? null
+        : JSON.stringify(entry.metadata);
+      await this.sql`
+        INSERT INTO "audit_logs" (
+          "action", "actorId", "actorName", "actorEmail",
+          "targetType", "targetId", "targetLabel", "ip", "metadata"
+        ) VALUES (
+          ${entry.action}, ${entry.actorId ?? null}, ${entry.actorName ?? null},
+          ${entry.actorEmail ?? null}, ${entry.targetType ?? null},
+          ${entry.targetId ?? null}, ${entry.targetLabel ?? null}, ${entry.ip ?? null},
+          ${metadata}::jsonb
+        )
+      `;
     } catch {
-      // An audit write must never break the request it describes.
+      // Audit persistence must never break the operation it describes.
     }
   }
+
+  async recent(limit = 50): Promise<AuditLogView[]> {
+    const rows = await this.sql<AuditLogRow[]>`
+      SELECT "id", "action", "actorId", "actorName", "actorEmail",
+             "targetType", "targetId", "targetLabel", "ip", "metadata", "createdAt"
+      FROM "audit_logs"
+      ORDER BY "createdAt" DESC
+      LIMIT ${limit}
+    `;
+    return rows.map((row) => ({ ...row, createdAt: row.createdAt.toISOString() }));
+  }
+
+  async recordRequest(
+    action: string,
+    request: Request,
+    session: AuthSession,
+    target: AuditTarget = {},
+  ): Promise<void> {
+    if (!(await auditEnabled())) return;
+    await this.record({
+      action,
+      actorId: session.user.id,
+      actorName: typeof session.user.name === "string" ? session.user.name : null,
+      actorEmail: typeof session.user.email === "string" ? session.user.email : null,
+      targetType: target.type ?? null,
+      targetId: target.id ?? null,
+      targetLabel: target.label ?? null,
+      metadata: target.metadata ?? null,
+      ip: request.headers.get("x-forwarded-for") ?? null,
+    });
+  }
 }

package/dist/templates/modules/audit-log/module.manifest.json

@@ -1,27 +1,23 @@
 {
   "name": "audit-log",
-  "description": "Audit logging: records who did each mutating request (who/method/path/status) to an audit_logs table \u2014 a NestJS interceptor for your own API routes plus a better-auth hook for auth/admin actions (login, ban, role changes, ...). Requires auth.",
-  "requires": [
-    "auth"
-  ],
+  "description": "Audit logging for Elysia and Better Auth: stores semantic actor/action/target events in audit_logs, including login, ban, role, session, and user lifecycle actions. Requires auth.",
+  "requires": ["auth"],
   "targetApp": "api",
   "env": [
-    "# audit-log: on/off is managed on the admin Settings page (stored in the DB,",
-    "# applied live, no restart). This env var is the fallback default used until an",
-    "# admin sets it \u2014 leave it 'true' so the trail is on out of the box; the DB value",
-    "# (Settings page) overrides it once set.",
+    "# audit-log: managed on the admin Settings page, stored in the DB,",
+    "# and applied without restart. This environment value is the fallback.",
     "AUDIT_LOG_ENABLED=true"
   ],
   "inject": [
     {
-      "file": "apps/api/src/app.module.ts",
+      "file": "apps/api/src/app.ts",
       "marker": "// podokit:end:imports",
-      "text": "import { AuditModule } from \"./audit/audit.module\";"
+      "text": "import { auditModule } from \"./audit/audit.module\";"
     },
     {
-      "file": "apps/api/src/app.module.ts",
-      "marker": "// podokit:end:module-imports",
-      "text": "AuditModule,"
+      "file": "apps/api/src/app.ts",
+      "marker": "// podokit:end:modules",
+      "text": "auditModule,"
     },
     {
       "file": "apps/api/src/auth/auth.ts",
@@ -35,9 +31,9 @@
     }
   ],
   "instructions": [
-    "Run migrations to create the audit_logs table:  npm run migration:run -w <app>-api",
-    "Auth/admin actions (login, ban, role changes, session revocation, user CRUD) are recorded via a better-auth hook; your own mutating NestJS routes are recorded by the interceptor.",
-    "List recent entries (admin session required):  curl -b cookies.txt localhost:5002/audit-logs"
+    "Run migrations to create the audit_logs table: {{apiRun}} migration:run{{apiWorkspaceArg}}",
+    "Auth/admin actions are recorded by a Better Auth hook. Record semantic application events with AuditService.recordRequest() or recordAudit().",
+    "List recent entries (admin session required): curl -b cookies.txt localhost:5002/audit-logs"
   ],
   "dependencies": {
     "@podosoft/podokit-auth": "^0.3.0"

package/dist/templates/modules/auth/files/apps/api/scripts/configure-auth.mjs

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env bun
 
 const args = process.argv.slice(2);
 
@@ -15,10 +15,10 @@ function usage() {
   console.log(`Configure PodoKit authentication through the admin API.
 
 Usage:
-  npm run auth:configure -- --provider google --require-signup-approval
-  npm run auth:configure -- --provider google --redirect-only
-  npm run auth:configure -- --smtp
-  npm run auth:configure -- --check-only --provider google
+  {{apiRun}} auth:configure -- --provider google --require-signup-approval
+  {{apiRun}} auth:configure -- --provider google --redirect-only
+  {{apiRun}} auth:configure -- --smtp
+  {{apiRun}} auth:configure -- --check-only --provider google
 
 Required environment for writes:
   AUTH_SETUP_ORIGIN          Public app origin (or BETTER_AUTH_URL)

package/dist/templates/modules/auth/files/apps/api/scripts/run-migrations.mjs

@@ -0,0 +1,14 @@
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const compiledEntry = new URL("../dist/migrate.js", import.meta.url);
+const sourceEntry = new URL("../src/migrate.ts", import.meta.url);
+const useCompiled = process.env.NODE_ENV === "production" && existsSync(compiledEntry);
+const entry = useCompiled ? compiledEntry : sourceEntry;
+const subprocess = Bun.spawn([process.execPath, fileURLToPath(entry)], {
+  stdin: "inherit",
+  stdout: "inherit",
+  stderr: "inherit",
+});
+
+process.exitCode = await subprocess.exited;

package/dist/templates/modules/auth/files/apps/api/src/auth/auth-provider.ts

@@ -4,12 +4,9 @@ import { authConfigStore } from "./auth-config-store";
 // Runtime auth instance that rebuilds when the DB config changes, so admin edits
 // (OAuth credentials, SMTP, server-enforced toggles) apply WITHOUT a restart.
 //
-// @thallesp/nestjs-better-auth reads `auth.handler` exactly once (via toNodeHandler)
-// and `auth.api` per request. We hand it a Proxy: `.handler` is a STABLE delegating
-// function (so the adapter's captured reference stays valid) that redispatches each
-// request to the currently-built instance; every other access forwards to the
-// current instance too. The guard/session behavior is unchanged (session tokens are
-// signed with the stable BETTER_AUTH_SECRET; trustedOrigins is baked into every build).
+// Elysia mounts `auth.handler` once. The proxy exposes a stable delegating handler
+// that refreshes the DB-backed configuration and dispatches to the current Better
+// Auth instance. Session tokens remain valid because BETTER_AUTH_SECRET is stable.
 
 const TTL_MS = 3_000;
 

package/dist/templates/modules/auth/files/apps/api/src/auth/auth.module.ts

@@ -0,0 +1,176 @@
+import type { Capabilities } from "@podosoft/podokit-contracts";
+import { Elysia, t } from "elysia";
+import {
+  ACCESS_POLICY,
+  DATABASE,
+  OPENAPI,
+  REQUEST_GUARDS,
+  REQUEST_IDENTITY,
+  type AppPlugin,
+  type PodokitModule,
+  type ServiceKey,
+} from "../core/services";
+import {
+  AuthConfigService,
+  type AuthConfigUpdate,
+} from "../auth-config/auth-config.service";
+import { FEATURE_FLAGS, SettingsService, type FeatureFlag } from "../settings/settings.service";
+import { authConfigStore } from "./auth-config-store";
+import { getAuth, authRuntime, primeAuth } from "./auth-provider";
+import { generateAuthOpenApiDocument } from "./auth.openapi";
+import { ROLE_NAMES } from "./permissions";
+import { AuthService } from "./auth.service";
+
+export const AUTH = Symbol("auth") as ServiceKey<AuthService>;
+export const SETTINGS = Symbol("settings") as ServiceKey<SettingsService>;
+export const AUTH_CONFIG = Symbol("auth-config") as ServiceKey<AuthConfigService>;
+
+const providerUpdateSchema = t.Object({
+  enabled: t.Optional(t.Boolean()),
+  clientId: t.Optional(t.String()),
+  clientSecret: t.Optional(t.String()),
+  redirectURI: t.Optional(t.String()),
+  delete: t.Optional(t.Boolean()),
+});
+
+const authConfigUpdateSchema = t.Object({
+  social: t.Optional(t.Record(t.String(), providerUpdateSchema)),
+  smtp: t.Optional(t.Object({
+    enabled: t.Optional(t.Boolean()),
+    host: t.Optional(t.String()),
+    port: t.Optional(t.Number()),
+    secure: t.Optional(t.Boolean()),
+    user: t.Optional(t.String()),
+    pass: t.Optional(t.String()),
+    from: t.Optional(t.String()),
+  })),
+  server: t.Optional(t.Object({
+    requireEmailVerification: t.Optional(t.Boolean()),
+    requireSignupApproval: t.Optional(t.Boolean()),
+    allowDelete: t.Optional(t.Boolean()),
+    hibp: t.Optional(t.Boolean()),
+    auditLog: t.Optional(t.Boolean()),
+    sessionIdleTimeoutMinutes: t.Optional(t.Nullable(t.Number())),
+  })),
+});
+
+const accountPlugin: AppPlugin = ({ services }) => {
+  const authService = services.resolve(AUTH);
+  const settings = services.resolve(SETTINGS);
+  const authConfig = services.resolve(AUTH_CONFIG);
+
+  return new Elysia({ name: "podokit.auth" })
+    .mount(authRuntime.handler)
+    .get("/account/me", async ({ request }) => {
+      const session = await authService.requireSession(request);
+      return session.user;
+    }, {
+      detail: { tags: ["account"], summary: "Get the current account" },
+    })
+    .get("/account/require-2fa", () => ({ require2fa: settings.getBool("require2fa") }), {
+      detail: { tags: ["account"], summary: "Get the two-factor enrolment policy" },
+    })
+    .get("/account/capabilities", async (): Promise<Capabilities> => {
+      const flags = settings.flags();
+      const snapshot = await authConfigStore.capabilitiesSnapshot();
+      return {
+        twoFactor: flags.twoFactor,
+        magicLink: flags.magicLink,
+        emailOtp: flags.emailOtp,
+        username: flags.username,
+        multiSession: flags.multiSession,
+        phoneNumber: flags.phoneNumber,
+        apiKey: flags.apiKey,
+        passkey: flags.passkey,
+        organization: flags.organization,
+        oidcProvider: flags.oidcProvider,
+        providers: snapshot.providers,
+        deleteAccount: snapshot.allowDelete,
+        emailVerification: snapshot.requireEmailVerification,
+        signupApprovalRequired: snapshot.requireSignupApproval,
+        passwordBreachCheck: snapshot.passwordBreachCheck,
+        auditLog: snapshot.auditLog,
+        sessionIdleTimeoutMinutes: snapshot.sessionIdleTimeoutMinutes,
+        roles: ROLE_NAMES,
+      };
+    }, {
+      detail: { tags: ["account"], summary: "Get authentication capabilities" },
+    })
+    .put("/account/settings", async ({ request, body }) => {
+      await authService.requireAdmin(request);
+      const update: Partial<Record<FeatureFlag, boolean>> = {};
+      for (const flag of FEATURE_FLAGS) {
+        const value = body[flag];
+        if (typeof value === "boolean") update[flag] = value;
+      }
+      return settings.setMany(update);
+    }, {
+      body: t.Record(t.String(), t.Boolean()),
+      detail: { tags: ["account"], summary: "Update authentication feature flags" },
+    })
+    .get("/account/auth-config", async ({ request }) => {
+      await authService.requireAdmin(request);
+      return authConfig.describe();
+    }, {
+      detail: { tags: ["account"], summary: "Get authentication configuration" },
+    })
+    .put("/account/auth-config", async ({ request, body }) => {
+      await authService.requireAdmin(request);
+      return authConfig.update(body as AuthConfigUpdate);
+    }, {
+      body: authConfigUpdateSchema,
+      detail: { tags: ["account"], summary: "Update authentication configuration" },
+    })
+    .post("/account/org-member", async ({ request, body, set }) => {
+      await authService.requireSession(request);
+      const api = getAuth().api as unknown as {
+        addMember: (options: {
+          body: { organizationId: string; userId: string; role: string };
+          headers: Headers;
+        }) => Promise<unknown>;
+      };
+      const result = await api.addMember({ body, headers: request.headers });
+      set.status = 201;
+      return result;
+    }, {
+      body: t.Object({
+        organizationId: t.String({ minLength: 1 }),
+        userId: t.String({ minLength: 1 }),
+        role: t.String({ minLength: 1 }),
+      }),
+      detail: { tags: ["account"], summary: "Add an organization member" },
+    });
+};
+
+export const authModule: PodokitModule = {
+  name: "auth",
+  configure: (_env, services): void => {
+    const database = services.resolve(DATABASE);
+    const accessPolicy = services.resolve(ACCESS_POLICY);
+    const settings = new SettingsService(database.sql);
+    const authService = new AuthService(settings, accessPolicy);
+    services.register(SETTINGS, settings);
+    services.register(AUTH_CONFIG, new AuthConfigService(database.sql));
+    services.register(AUTH, authService, () => authService.close());
+    services.onStart(async () => {
+      await settings.refresh();
+      await primeAuth();
+    });
+    services.override(REQUEST_IDENTITY, {
+      userId: async (request) => (await authService.session(request))?.user.id,
+    });
+    accessPolicy.register("*", "/api/auth", "public");
+    accessPolicy.register("*", "/api/auth/*", "public");
+    accessPolicy.register("GET", "/account/capabilities", "public");
+    services.resolve(OPENAPI).register("better-auth", async () => {
+      await primeAuth();
+      const document = await generateAuthOpenApiDocument(getAuth().api);
+      return {
+        document,
+        pathPrefix: "/api/auth",
+      };
+    });
+    services.resolve(REQUEST_GUARDS).register(({ request }) => authService.guard(request));
+  },
+  plugin: accountPlugin,
+};

package/dist/templates/modules/auth/files/apps/api/src/auth/auth.openapi.spec.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "bun:test";
+import { generateAuthOpenApiDocument, isAuthOpenApiApi } from "./auth.openapi";
+
+describe("Better Auth OpenAPI integration", () => {
+  it("accepts the generated OpenAPI API without weakening the auth type", async () => {
+    const api: unknown = {
+      generateOpenAPISchema: () => ({ openapi: "3.1.0", paths: {} }),
+    };
+
+    expect(isAuthOpenApiApi(api)).toBe(true);
+    expect(await generateAuthOpenApiDocument(api)).toEqual({ openapi: "3.1.0", paths: {} });
+  });
+
+  it("rejects missing and malformed OpenAPI integrations", async () => {
+    expect(isAuthOpenApiApi({})).toBe(false);
+    expect(generateAuthOpenApiDocument({ generateOpenAPISchema: () => null })).rejects.toThrow(
+      "invalid OpenAPI document",
+    );
+  });
+});

package/dist/templates/modules/auth/files/apps/api/src/auth/auth.openapi.ts

@@ -0,0 +1,22 @@
+interface AuthOpenApiApi {
+  generateOpenAPISchema: () => unknown;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function isAuthOpenApiApi(value: unknown): value is AuthOpenApiApi {
+  return isRecord(value) && typeof value.generateOpenAPISchema === "function";
+}
+
+export async function generateAuthOpenApiDocument(api: unknown): Promise<Record<string, unknown>> {
+  if (!isAuthOpenApiApi(api)) {
+    throw new Error("Better Auth OpenAPI plugin is unavailable");
+  }
+  const document: unknown = await api.generateOpenAPISchema();
+  if (!isRecord(document)) {
+    throw new Error("Better Auth returned an invalid OpenAPI document");
+  }
+  return document;
+}

package/dist/templates/modules/auth/files/apps/api/src/auth/auth.runtime.spec.ts

@@ -1,4 +1,4 @@
-import { afterEach, describe, expect, it } from "@jest/globals";
+import { afterEach, describe, expect, test } from "bun:test";
 import { authBaseUrl, authSecret } from "./auth-environment";
 
 const originalEnvironment = {
@@ -15,7 +15,7 @@ afterEach(() => {
 });
 
 describe("authentication production environment", () => {
-  it("rejects missing and placeholder production secrets", () => {
+  test("rejects missing and placeholder production secrets", () => {
     process.env.NODE_ENV = "production";
     delete process.env.BETTER_AUTH_SECRET;
     expect(() => authSecret()).toThrow("must be set");
@@ -23,7 +23,7 @@ describe("authentication production environment", () => {
     expect(() => authSecret()).toThrow("non-placeholder");
   });
 
-  it("requires an HTTPS production origin", () => {
+  test("requires an HTTPS production origin", () => {
     process.env.NODE_ENV = "production";
     delete process.env.BETTER_AUTH_URL;
     expect(() => authBaseUrl()).toThrow("must be set");