@podosoft/podokit 0.17.3 → 1.0.1

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");

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

@@ -0,0 +1,52 @@
+import { describe, expect, test } from "bun:test";
+import { AccessPolicy } from "../core/services";
+import type { SettingsService } from "../settings/settings.service";
+import { AuthService, rolesOf, type AuthSession } from "./auth.service";
+
+function settings(require2fa: boolean): SettingsService {
+  return { getBool: () => require2fa } as unknown as SettingsService;
+}
+
+function session(overrides: Partial<AuthSession["user"]> = {}): AuthSession {
+  return { user: { id: "user-1", ...overrides }, session: {} };
+}
+
+describe("AuthService", () => {
+  test("normalizes string and array roles", () => {
+    expect(rolesOf(session({ role: "user, admin" }).user)).toEqual(["user", "admin"]);
+    expect(rolesOf(session({ role: ["owner"] }).user)).toEqual(["owner"]);
+  });
+
+  test("keeps explicitly public routes unauthenticated", async () => {
+    const policy = new AccessPolicy();
+    policy.register("GET", "/public", "public");
+    const service = new AuthService(settings(false), policy, async () => null);
+    await expect(service.guard(new Request("http://localhost/public"))).resolves.toBeUndefined();
+  });
+
+  test("requires a session by default", async () => {
+    const service = new AuthService(settings(false), new AccessPolicy(), async () => null);
+    const result = service.guard(new Request("http://localhost/private"));
+    await expect(result).rejects.toMatchObject({ code: "AUTH_REQUIRED", statusCode: 401 });
+  });
+
+  test("requires two-factor enrolment when the policy is enabled", async () => {
+    const service = new AuthService(
+      settings(true),
+      new AccessPolicy(),
+      async () => session({ twoFactorEnabled: false }),
+    );
+    const result = service.guard(new Request("http://localhost/private"));
+    await expect(result).rejects.toMatchObject({ code: "TWO_FACTOR_REQUIRED", statusCode: 403 });
+  });
+
+  test("requires the admin role for admin operations", async () => {
+    const service = new AuthService(
+      settings(false),
+      new AccessPolicy(),
+      async () => session({ role: "user" }),
+    );
+    await expect(service.requireAdmin(new Request("http://localhost/account/settings")))
+      .rejects.toMatchObject({ code: "ADMIN_REQUIRED", statusCode: 403 });
+  });
+});

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

@@ -0,0 +1,78 @@
+import { AppException } from "@podosoft/podokit-contracts";
+import type { AccessPolicy } from "../core/services";
+import type { SettingsService } from "../settings/settings.service";
+import { getAuth, refreshIfStale } from "./auth-provider";
+import { pool } from "./db";
+
+export interface AuthUser extends Record<string, unknown> {
+  id: string;
+  role?: string | string[] | null;
+  twoFactorEnabled?: boolean;
+}
+
+export interface AuthSession {
+  user: AuthUser;
+  session: Record<string, unknown>;
+}
+
+export type SessionResolver = (headers: Headers) => Promise<AuthSession | null>;
+
+function defaultSessionResolver(headers: Headers): Promise<AuthSession | null> {
+  return refreshIfStale()
+    .then(() => getAuth().api.getSession({ headers }))
+    .then((session) => session as AuthSession | null);
+}
+
+export function rolesOf(user: AuthUser): string[] {
+  if (Array.isArray(user.role)) return user.role;
+  return (user.role ?? "").split(",").map((role) => role.trim()).filter(Boolean);
+}
+
+export class AuthService {
+  private readonly sessions = new WeakMap<Request, Promise<AuthSession | null>>();
+
+  constructor(
+    private readonly settings: SettingsService,
+    private readonly accessPolicy: AccessPolicy,
+    private readonly resolveSession: SessionResolver = defaultSessionResolver,
+  ) {}
+
+  session(request: Request): Promise<AuthSession | null> {
+    const cached = this.sessions.get(request);
+    if (cached) return cached;
+    const result = this.resolveSession(request.headers);
+    this.sessions.set(request, result);
+    return result;
+  }
+
+  async requireSession(request: Request): Promise<AuthSession> {
+    const session = await this.session(request);
+    if (!session) throw new AppException("AUTH_REQUIRED", "Authentication is required", 401);
+    return session;
+  }
+
+  async requireAdmin(request: Request): Promise<AuthSession> {
+    const session = await this.requireSession(request);
+    if (!rolesOf(session.user).includes("admin")) {
+      throw new AppException("ADMIN_REQUIRED", "Administrator access is required", 403);
+    }
+    return session;
+  }
+
+  async guard(request: Request): Promise<void> {
+    if (this.accessPolicy.resolve(request) !== "session") return;
+    const session = await this.requireSession(request);
+    if (!this.settings.getBool("require2fa") || session.user.twoFactorEnabled) return;
+    const path = new URL(request.url).pathname;
+    if (path === "/account/require-2fa" || path === "/account/settings") return;
+    throw new AppException(
+      "TWO_FACTOR_REQUIRED",
+      "Two-factor enrolment is required.",
+      403,
+    );
+  }
+
+  async close(): Promise<void> {
+    await pool.end();
+  }
+}

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

@@ -1,6 +1,6 @@
 import { betterAuth, type BetterAuthOptions, type BetterAuthPlugin } from "better-auth";
 import { APIError } from "better-auth/api";
-import { twoFactor, haveIBeenPwned, magicLink, emailOTP, username, multiSession, phoneNumber, organization, jwt, bearer } from "better-auth/plugins";
+import { twoFactor, haveIBeenPwned, magicLink, emailOTP, username, multiSession, phoneNumber, organization, jwt, bearer, openAPI } from "better-auth/plugins";
 import { actionEmail, sendMail } from "../mail/mailer";
 import { sendSms } from "../sms/sms";
 import { assertUserCreationAllowed, createFeatureGate, createSignupOpenCheck } from "./feature-gate";
@@ -118,6 +118,9 @@ export function buildAuth(config: AuthConfig) {
     // Register clients at /api/auth/oauth2/create-client; discovery at
     // /api/auth/.well-known/openid-configuration. See docs/modules.md.
     oauthProvider({ loginPage: "/login", consentPage: "/oauth2/consent" }),
+    // Makes the dynamic Better Auth route contract available for the generated
+    // OpenAPI parity check in addition to the Elysia application schema.
+    openAPI(),
   ];
   // Reject passwords found in known breaches (Have I Been Pwned, k-anonymity range
   // API). Admin-toggleable (auth_config), applied live on the next request.

package/dist/templates/modules/auth/files/apps/api/src/auth/user-delete-handlers.spec.ts

@@ -1,4 +1,4 @@
-import { afterEach, describe, expect, it, jest } from "@jest/globals";
+import { afterEach, describe, expect, mock, spyOn, test } from "bun:test";
 import {
   registerUserDeletedHandler,
   runUserDeletedHandlers,
@@ -10,15 +10,15 @@ describe("user deletion handlers", () => {
 
   afterEach(() => {
     for (const remove of unregister.splice(0)) remove();
-    jest.restoreAllMocks();
+    mock.restore();
   });
 
   function register(handler: UserDeletedHandler): void {
     unregister.push(registerUserDeletedHandler(handler));
   }
 
-  it("runs registered module cleanup with the deleted user", async () => {
-    const handler: UserDeletedHandler = jest.fn(async () => undefined);
+  test("runs registered module cleanup with the deleted user", async () => {
+    const handler: UserDeletedHandler = mock(async () => undefined);
     register(handler);
     const user = { id: "user-1", image: "/api/profile-images/avatar.png" };
 
@@ -27,8 +27,8 @@ describe("user deletion handlers", () => {
     expect(handler).toHaveBeenCalledWith(user);
   });
 
-  it("does not fail account deletion when one cleanup rejects", async () => {
-    jest.spyOn(console, "error").mockImplementation(() => undefined);
+  test("does not fail account deletion when one cleanup rejects", async () => {
+    spyOn(console, "error").mockImplementation(() => undefined);
     register(async () => {
       throw new Error("storage unavailable");
     });