@podosoft/podokit 0.4.0 → 0.5.1

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

@@ -1,59 +1,204 @@
 import { betterAuth, type BetterAuthOptions, type BetterAuthPlugin } from "better-auth";
-import { twoFactor } from "better-auth/plugins";
-import { Pool } from "pg";
-// podokit:auth-imports
+import { twoFactor, haveIBeenPwned, magicLink, emailOTP, username, multiSession, phoneNumber, organization, jwt, bearer } from "better-auth/plugins";
+import { actionEmail, sendMail } from "../mail/mailer";
+import { sendSms } from "../sms/sms";
+import { createFeatureGate } from "./feature-gate";
+import { orgAc, orgRoles } from "./org-permissions";
+import { pool } from "./db";
+import { type AuthConfig, envAuthConfig, SUPPORTED_PROVIDER_IDS } from "@podosoft/podokit-auth";
+import { apiKey } from "@better-auth/api-key";
+import { passkey } from "@better-auth/passkey";
+import { oauthProvider } from "@better-auth/oauth-provider";
+// podokit:begin:auth-imports
+// podokit:end:auth-imports
 
-// OAuth providers are enabled only when their credentials are present.
-function socialProviders(): NonNullable<BetterAuthOptions["socialProviders"]> {
-  const providers: NonNullable<BetterAuthOptions["socialProviders"]> = {};
-  if (process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET) {
-    providers.google = {
-      clientId: process.env.GOOGLE_CLIENT_ID,
-      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
-    };
-  }
-  if (process.env.GITHUB_CLIENT_ID && process.env.GITHUB_CLIENT_SECRET) {
-    providers.github = {
-      clientId: process.env.GITHUB_CLIENT_ID,
-      clientSecret: process.env.GITHUB_CLIENT_SECRET,
-    };
+// Web origin(s) where the browser runs (WebAuthn ceremonies must match these).
+const webOrigins = (process.env.CORS_ORIGIN ?? "http://localhost:5001").split(",").map((o) => o.trim());
+
+// Enabled social providers, from the resolved config (DB-first, env fallback).
+// Admins add/edit/remove providers dynamically (Settings page), so this maps the
+// whole config.social record. Secrets arrive already decrypted; a provider needs
+// enabled + id + secret, and must be a better-auth-supported provider id (the
+// allowlist guards betterAuth() from an unknown key). The provider option shape
+// (clientId/clientSecret/redirectURI) is common to every supported provider.
+function buildSocial(config: AuthConfig): NonNullable<BetterAuthOptions["socialProviders"]> {
+  const providers: Record<string, { clientId: string; clientSecret: string; redirectURI?: string }> = {};
+  for (const [id, p] of Object.entries(config.social)) {
+    if (!SUPPORTED_PROVIDER_IDS.has(id) || !p.enabled || !p.clientId || !p.clientSecret) continue;
+    providers[id] = { clientId: p.clientId, clientSecret: p.clientSecret, ...(p.redirectURI ? { redirectURI: p.redirectURI } : {}) };
   }
-  return providers;
+  return providers as NonNullable<BetterAuthOptions["socialProviders"]>;
 }
 
-// Plugins are collected here so other PodoKit modules can add their own.
-const plugins: BetterAuthPlugin[] = [];
-if (process.env.AUTH_TWO_FACTOR === "true") {
-  plugins.push(twoFactor());
-}
-// podokit:auth-plugins
+// Build a better-auth instance from resolved config. Called at boot and rebuilt by
+// auth-provider.ts when the DB config changes, so admin edits (OAuth credentials,
+// server-enforced toggles) apply without a restart. Everything below the injection
+// markers is contributed by other PodoKit modules (admin-dashboard, audit-log).
+export function buildAuth(config: AuthConfig) {
+  const plugins: BetterAuthPlugin[] = [
+    twoFactor(),
+    magicLink({
+      sendMagicLink: async ({ email, url }: { email: string; url: string; token: string }) => {
+        await sendMail({
+          to: email,
+          subject: "Your sign-in link",
+          text: `Sign in: ${url}`,
+          html: actionEmail("Sign in to your account", "Click the button below to sign in. This link expires shortly.", url, "Sign in"),
+        });
+      },
+    }),
+    emailOTP({
+      sendVerificationOTP: async ({ email, otp }: { email: string; otp: string; type: string }) => {
+        await sendMail({
+          to: email,
+          subject: "Your sign-in code",
+          text: `Your one-time code is ${otp}. It expires shortly.`,
+          html: `<p>Your one-time sign-in code is:</p><p style="font-size:24px;font-weight:bold;letter-spacing:3px">${otp}</p><p>It expires shortly.</p>`,
+        });
+      },
+    }),
+    // Adds username/displayUsername columns; lets users sign in with a username.
+    username(),
+    // Let one browser hold several signed-in accounts and switch between them.
+    multiSession(),
+    // Phone-number sign-in/verification. SMS delivery is a dev stub (logs the code);
+    // wire a real provider in sendOTP for production.
+    phoneNumber({
+      sendOTP: async ({ phoneNumber: to, code }: { phoneNumber: string; code: string }) => {
+        await sendSms({ to, body: `Your verification code is ${code}` });
+      },
+    }),
+    // User-issued API keys (DB-backed). Distinct from the static X-API-Key module.
+    apiKey(),
+    // Passwordless sign-in with WebAuthn passkeys. The ceremony runs at the web
+    // origin, so expected origins are the CORS origins and rpID is their host.
+    // Change rpName to your product name (shown in the browser passkey prompt).
+    passkey({ rpName: "PodoKit", rpID: new URL(webOrigins[0]).hostname, origin: webOrigins }),
+    // Multi-tenant organizations: teams with members, roles, and email invitations.
+    organization({
+      // Custom member roles (adds "manager") and a parent-organization link so orgs
+      // can form a hierarchy. See org-permissions.ts.
+      ac: orgAc,
+      roles: orgRoles,
+      schema: { organization: { additionalFields: { parentOrganizationId: { type: "string", required: false, input: true } } } },
+      sendInvitationEmail: async (data: { email: string; id: string; organization: { name: string }; inviter: { user: { name: string; email: string } } }) => {
+        const url = `${webOrigins[0]}/accept-invitation/${data.id}`;
+        await sendMail({
+          to: data.email,
+          subject: `You are invited to ${data.organization.name}`,
+          text: `${data.inviter.user.name} invited you to ${data.organization.name}. Accept: ${url}`,
+          html: actionEmail(
+            `Join ${data.organization.name}`,
+            `${data.inviter.user.name} (${data.inviter.user.email}) invited you to join ${data.organization.name}.`,
+            url,
+            "Accept invitation",
+          ),
+        });
+      },
+    }),
+    // Accept the session token via `Authorization: Bearer <token>` (returned in the
+    // `set-auth-token` response header on sign-in) instead of a cookie — for API and
+    // mobile clients. Infrastructure plugin (always on), like jwt(); no UI toggle.
+    bearer(),
+    // JWT/JWKS signing keys — required by the OAuth provider to sign id_tokens.
+    jwt(),
+    // Act as an OAuth2/OIDC identity provider: other apps can "Sign in with this app".
+    // 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" }),
+  ];
+  // Reject passwords found in known breaches (Have I Been Pwned, k-anonymity range
+  // API). Admin-toggleable (auth_config), applied live on the next request.
+  if (config.hibp) {
+    plugins.push(haveIBeenPwned());
+  }
+  // podokit:begin:auth-plugins
+  // podokit:end:auth-plugins
+
+  // Request-time hooks. The feature gate turns the admin Settings toggles into a
+  // real server boundary (disabled features 404). Other PodoKit modules add their
+  // own hooks below the marker.
+  const hooks: NonNullable<BetterAuthOptions["hooks"]> = { before: createFeatureGate(pool) };
+  // podokit:begin:auth-hooks
+  // podokit:end:auth-hooks
 
-export const auth = betterAuth({
-  database: new Pool({
-    host: process.env.POSTGRES_HOST ?? "localhost",
-    port: Number(process.env.POSTGRES_PORT ?? 5432),
-    user: process.env.POSTGRES_USER ?? "podokit",
-    password: process.env.POSTGRES_PASSWORD ?? "podokit",
-    database: process.env.POSTGRES_DB ?? "podokit",
-  }),
-  emailAndPassword: {
-    enabled: true,
-    // podokit:auth-email-password
-  },
-  socialProviders: socialProviders(),
-  plugins,
-  secret: process.env.BETTER_AUTH_SECRET ?? "change-me-in-production-min-32-characters",
-  baseURL: process.env.BETTER_AUTH_URL ?? "http://localhost:3000",
-  advanced: {
-    ipAddress: {
-      // The API sits behind the SvelteKit server proxy, which forwards the
-      // resolved client IP as x-forwarded-for; trust it so sessions record an IP.
-      ipAddressHeaders: ["x-forwarded-for"],
+  return betterAuth({
+    database: pool,
+    emailAndPassword: {
+      enabled: true,
+      requireEmailVerification: config.requireEmailVerification,
+      sendResetPassword: async ({ user, url }) => {
+        await sendMail({
+          to: user.email,
+          subject: "Reset your password",
+          text: `Reset your password: ${url}`,
+          html: actionEmail("Reset your password", "Click the button below to choose a new password.", url, "Reset password"),
+        });
+      },
+      // podokit:begin:auth-email-password
+      // podokit:end:auth-email-password
     },
-  },
-  user: {
-    // Self-service account deletion — opt in with AUTH_ALLOW_DELETE=true.
-    deleteUser: { enabled: process.env.AUTH_ALLOW_DELETE === "true" },
-  },
-  // podokit:auth-options
-});
+    emailVerification: {
+      sendOnSignUp: config.requireEmailVerification,
+      autoSignInAfterVerification: true,
+      sendVerificationEmail: async ({ user, url }) => {
+        await sendMail({
+          to: user.email,
+          subject: "Verify your email",
+          text: `Verify your email: ${url}`,
+          html: actionEmail("Verify your email", "Confirm your address to finish setting up your account.", url, "Verify email"),
+        });
+      },
+    },
+    socialProviders: buildSocial(config),
+    plugins,
+    hooks,
+    secret: process.env.BETTER_AUTH_SECRET ?? "change-me-in-production-min-32-characters",
+    baseURL: process.env.BETTER_AUTH_URL ?? "http://localhost:5002",
+    advanced: {
+      ipAddress: {
+        // The API sits behind the SvelteKit server proxy, which forwards the
+        // resolved client IP as x-forwarded-for; trust it so sessions record an IP.
+        ipAddressHeaders: ["x-forwarded-for"],
+      },
+    },
+    user: {
+      // Self-service email change. When email verification is on, better-auth sends
+      // an approval link to the current address before switching; otherwise it
+      // changes immediately.
+      changeEmail: {
+        enabled: true,
+        sendChangeEmailVerification: async ({
+          user,
+          newEmail,
+          url,
+        }: {
+          user: { email: string };
+          newEmail: string;
+          url: string;
+        }) => {
+          await sendMail({
+            to: user.email,
+            subject: "Approve your email change",
+            text: `Approve changing your email to ${newEmail}: ${url}`,
+            html: actionEmail(
+              "Approve email change",
+              `Confirm changing your email address to ${newEmail}.`,
+              url,
+              "Approve change",
+            ),
+          });
+        },
+      },
+      // Self-service account deletion — admin-toggleable (auth_config), applied live.
+      deleteUser: { enabled: config.allowDelete },
+    },
+    // podokit:begin:auth-options
+    // podokit:end:auth-options
+  });
+}
+
+// Bootstrap instance from environment config. Used by the better-auth CLI
+// (`--config auth.ts`) and as the guaranteed last-good fallback. The runtime
+// mount (auth-provider.ts) rebuilds from DB config on top of this.
+export const auth = buildAuth(envAuthConfig());

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

@@ -0,0 +1,12 @@
+import { Pool } from "pg";
+
+// One shared pg connection pool, in its own module so it can be imported by
+// auth.ts, the mailer, and the config store without an import cycle (auth.ts
+// imports the mailer, which needs the pool for runtime SMTP config).
+export const pool = new Pool({
+  host: process.env.POSTGRES_HOST ?? "localhost",
+  port: Number(process.env.POSTGRES_PORT ?? 5432),
+  user: process.env.POSTGRES_USER ?? "podokit",
+  password: process.env.POSTGRES_PASSWORD ?? "podokit",
+  database: process.env.POSTGRES_DB ?? "podokit",
+});

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

@@ -0,0 +1,56 @@
+import { APIError, createAuthMiddleware } from "better-auth/api";
+import type { Pool } from "pg";
+import { FLAG_DEFAULTS, type FeatureFlag } from "../settings/flag-defaults";
+
+/** Auth-relative path prefixes owned by each admin-toggleable feature. A path is
+ *  gated when it equals a prefix or starts with a prefix ending in "/". */
+const FEATURE_PATHS: Array<{ flag: FeatureFlag; prefixes: string[] }> = [
+  { flag: "twoFactor", prefixes: ["/two-factor/"] },
+  { flag: "magicLink", prefixes: ["/sign-in/magic-link", "/magic-link/"] },
+  { flag: "emailOtp", prefixes: ["/email-otp/", "/sign-in/email-otp"] },
+  { flag: "username", prefixes: ["/sign-in/username"] },
+  { flag: "multiSession", prefixes: ["/multi-session/"] },
+  { flag: "phoneNumber", prefixes: ["/phone-number/", "/sign-in/phone-number"] },
+  { flag: "apiKey", prefixes: ["/api-key/"] },
+  { flag: "passkey", prefixes: ["/passkey/", "/sign-in/passkey"] },
+  { flag: "organization", prefixes: ["/organization"] },
+  { flag: "oidcProvider", prefixes: ["/oauth2/", "/.well-known/openid-configuration", "/.well-known/oauth-authorization-server", "/.well-known/oauth-protected-resource"] },
+];
+
+const CACHE_TTL_MS = 3_000;
+
+/** Server-side enforcement for the admin Settings toggles: requests to a disabled
+ *  feature's endpoints are rejected with 404, so "off" is a real boundary rather
+ *  than hidden UI. Flags are read from app_setting through a small TTL cache
+ *  (a toggle takes effect within ~CACHE_TTL_MS); before the migration has run,
+ *  the shipped defaults apply. */
+export function createFeatureGate(pool: Pool) {
+  let cache: Record<FeatureFlag, boolean> = { ...FLAG_DEFAULTS };
+  let fetchedAt = 0;
+
+  async function flags(): Promise<Record<FeatureFlag, boolean>> {
+    if (Date.now() - fetchedAt < CACHE_TTL_MS) return cache;
+    try {
+      const res = await pool.query<{ key: string; value: string }>(
+        'SELECT "key", "value" FROM "app_setting" WHERE "key" = ANY($1)',
+        [Object.keys(FLAG_DEFAULTS)],
+      );
+      const next = { ...FLAG_DEFAULTS };
+      for (const row of res.rows) next[row.key as FeatureFlag] = row.value === "true";
+      cache = next;
+    } catch {
+      cache = { ...FLAG_DEFAULTS };
+    }
+    fetchedAt = Date.now();
+    return cache;
+  }
+
+  return createAuthMiddleware(async (ctx) => {
+    const feature = FEATURE_PATHS.find((f) =>
+      f.prefixes.some((p) => ctx.path === p || ctx.path.startsWith(p)),
+    );
+    if (!feature) return;
+    const enabled = (await flags())[feature.flag];
+    if (!enabled) throw new APIError("NOT_FOUND", { message: "This feature is disabled." });
+  });
+}

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

@@ -0,0 +1,22 @@
+import { createAccessControl } from "better-auth/plugins/access";
+import { defaultStatements, adminAc, ownerAc, memberAc } from "better-auth/plugins/organization/access";
+
+/** Access-control for organization MEMBERS (separate from the app-level roles in
+ *  permissions.ts). Adds a "manager" role alongside the built-in owner/admin/member
+ *  — any number of members can hold it, so an org can have several managers. A
+ *  manager runs the org (members, invitations, settings) but can't delete it. */
+export const orgAc = createAccessControl(defaultStatements);
+
+export const orgRoles = {
+  owner: ownerAc,
+  admin: adminAc,
+  manager: orgAc.newRole({
+    organization: ["update"],
+    member: ["create", "update", "delete"],
+    invitation: ["create", "cancel"],
+  }),
+  member: memberAc,
+};
+
+/** Assignable org role names, surfaced to the admin UI. */
+export const ORG_ROLE_NAMES = Object.keys(orgRoles);

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

@@ -0,0 +1,23 @@
+import { createAccessControl } from "better-auth/plugins/access";
+import { defaultStatements, adminAc, userAc } from "better-auth/plugins/admin/access";
+
+/** Access-control statement: the admin plugin's built-in resources (user, session)
+ *  plus an example "content" resource. Add your own resources and actions here. */
+export const statement = {
+  ...defaultStatements,
+  content: ["read", "create", "update", "delete"],
+} as const;
+
+export const ac = createAccessControl(statement);
+
+/** Roles and what each may do. `admin` keeps full user/session control and all
+ *  content actions; `moderator` manages content only; `user` can read content.
+ *  Assign roles from the Users admin page; check them with the permission guard. */
+export const roles = {
+  admin: ac.newRole({ ...adminAc.statements, content: ["read", "create", "update", "delete"] }),
+  moderator: ac.newRole({ content: ["read", "create", "update", "delete"] }),
+  user: ac.newRole({ ...userAc.statements, content: ["read"] }),
+};
+
+/** Assignable role names, surfaced to the admin UI via /account/capabilities. */
+export const ROLE_NAMES = Object.keys(roles);

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

@@ -0,0 +1,33 @@
+import { Body, Controller, ForbiddenException, Get, Put } from "@nestjs/common";
+import { Session, type UserSession } from "@thallesp/nestjs-better-auth";
+import { ApiTags } from "@nestjs/swagger";
+import { AuthConfigService, type AuthConfigView, type AuthConfigUpdate } from "./auth-config.service";
+
+function isAdmin(session: UserSession): boolean {
+  const role = session.user?.role;
+  const roles = Array.isArray(role) ? role : (role ?? "").split(",").map((r: string) => r.trim());
+  return roles.includes("admin");
+}
+
+// Admin-only management of DB-backed auth config (OAuth providers, SMTP,
+// server-enforced toggles). GET returns non-secret fields + `hasSecret`; PUT
+// encrypts and stores secrets, and the change applies live (the auth instance
+// rebuilds on the next request — see auth/auth-provider.ts). Secrets are never
+// returned to the client.
+@ApiTags("account")
+@Controller("account")
+export class AuthConfigController {
+  constructor(private readonly service: AuthConfigService) {}
+
+  @Get("auth-config")
+  async get(@Session() session: UserSession): Promise<AuthConfigView> {
+    if (!isAdmin(session)) throw new ForbiddenException("Admins only");
+    return this.service.describe();
+  }
+
+  @Put("auth-config")
+  async put(@Session() session: UserSession, @Body() body: AuthConfigUpdate): Promise<AuthConfigView> {
+    if (!isAdmin(session)) throw new ForbiddenException("Admins only");
+    return this.service.update(body);
+  }
+}

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

@@ -0,0 +1,26 @@
+import { Column, Entity, PrimaryColumn, UpdateDateColumn } from "typeorm";
+
+/** Admin-managed auth configuration, one row per section: one `social.<id>` row
+ *  per configured OAuth provider (added/removed dynamically — "social.google",
+ *  "social.github", "social.apple", …), plus "smtp" and "server". Non-secret
+ *  fields live in `config` (jsonb); secrets (OAuth client secret, SMTP password)
+ *  are stored encrypted in `secret` (AES-256-GCM envelope — see auth/secret.ts).
+ *  The runtime reads this table through auth/config-store.ts (raw pool) to
+ *  (re)build better-auth. */
+@Entity({ name: "auth_config" })
+export class AuthConfigRow {
+  @PrimaryColumn({ type: "text" })
+  key!: string;
+
+  @Column({ type: "boolean", default: false })
+  enabled!: boolean;
+
+  @Column({ type: "jsonb", default: {} })
+  config!: Record<string, unknown>;
+
+  @Column({ type: "text", nullable: true })
+  secret!: string | null;
+
+  @UpdateDateColumn()
+  updatedAt!: Date;
+}

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

@@ -0,0 +1,12 @@
+import { Module } from "@nestjs/common";
+import { TypeOrmModule } from "@nestjs/typeorm";
+import { AuthConfigRow } from "./auth-config.entity";
+import { AuthConfigService } from "./auth-config.service";
+import { AuthConfigController } from "./auth-config.controller";
+
+@Module({
+  imports: [TypeOrmModule.forFeature([AuthConfigRow])],
+  controllers: [AuthConfigController],
+  providers: [AuthConfigService],
+})
+export class AuthConfigModule {}

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

@@ -0,0 +1,118 @@
+import { BadRequestException, Injectable } from "@nestjs/common";
+import { InjectRepository } from "@nestjs/typeorm";
+import { Repository } from "typeorm";
+import { AuthConfigRow } from "./auth-config.entity";
+import { encryptSecret, envAuthConfig, socialKey, SUPPORTED_PROVIDER_IDS, SUPPORTED_SOCIAL_PROVIDERS } from "@podosoft/podokit-auth";
+
+/** One configured social provider as shown to the admin (no secret — just a
+ *  `hasSecret` flag). */
+export type SocialProviderView = { id: string; enabled: boolean; clientId: string; redirectURI: string; hasSecret: boolean };
+
+/** Admin-facing view — non-secret fields plus a `hasSecret` flag. Never exposes
+ *  the stored client secret / SMTP password. Social providers are dynamic: the
+ *  map holds one entry per configured provider (google, github, apple, …). */
+export type AuthConfigView = {
+  social: Record<string, SocialProviderView>;
+  /** Catalog of addable providers (id + display label) for the "add provider" picker. */
+  catalog: ReadonlyArray<{ id: string; label: string }>;
+  smtp: { enabled: boolean; host: string; port: number; secure: boolean; user: string; from: string; hasSecret: boolean };
+  server: { requireEmailVerification: boolean; allowDelete: boolean; hibp: boolean; auditLog: boolean };
+};
+
+type ProviderUpdate = { enabled?: boolean; clientId?: string; clientSecret?: string; redirectURI?: string; delete?: boolean };
+export type AuthConfigUpdate = {
+  /** Per-provider upsert (keyed by provider id); `{ delete: true }` removes it. */
+  social?: Record<string, ProviderUpdate>;
+  smtp?: { enabled?: boolean; host?: string; port?: number; secure?: boolean; user?: string; pass?: string; from?: string };
+  server?: { requireEmailVerification?: boolean; allowDelete?: boolean; hibp?: boolean; auditLog?: boolean };
+};
+
+@Injectable()
+export class AuthConfigService {
+  constructor(@InjectRepository(AuthConfigRow) private readonly repo: Repository<AuthConfigRow>) {}
+
+  async describe(): Promise<AuthConfigView> {
+    const rows = await this.repo.find();
+    const byKey = new Map(rows.map((r) => [r.key, r]));
+    const env = envAuthConfig();
+
+    const social: Record<string, SocialProviderView> = {};
+    for (const row of rows) {
+      if (!row.key.startsWith("social.")) continue;
+      const id = row.key.slice("social.".length);
+      if (!SUPPORTED_PROVIDER_IDS.has(id)) continue;
+      const c = (row.config ?? {}) as { clientId?: string; redirectURI?: string };
+      social[id] = { id, enabled: row.enabled, clientId: c.clientId ?? "", redirectURI: c.redirectURI ?? "", hasSecret: !!row.secret };
+    }
+    // Surface env-configured providers (google/github) that have no DB row yet, so
+    // the admin sees them as already-active rather than missing.
+    for (const [id, p] of Object.entries(env.social)) {
+      if (!social[id]) social[id] = { id, enabled: p.enabled, clientId: p.clientId, redirectURI: p.redirectURI ?? "", hasSecret: !!p.clientSecret };
+    }
+
+    const smtpRow = byKey.get("smtp");
+    const smtpC = (smtpRow?.config ?? {}) as { host?: string; port?: number; secure?: boolean; user?: string; from?: string };
+    const serverRow = byKey.get("server");
+    const serverC = (serverRow?.config ?? {}) as { requireEmailVerification?: boolean; allowDelete?: boolean; hibp?: boolean; auditLog?: boolean };
+    return {
+      social,
+      catalog: SUPPORTED_SOCIAL_PROVIDERS,
+      smtp: {
+        enabled: smtpRow?.enabled ?? false,
+        host: smtpC.host ?? "",
+        port: smtpC.port ?? 587,
+        secure: smtpC.secure ?? false,
+        user: smtpC.user ?? "",
+        from: smtpC.from ?? "",
+        hasSecret: !!smtpRow?.secret,
+      },
+      server: {
+        requireEmailVerification: serverC.requireEmailVerification ?? env.requireEmailVerification,
+        allowDelete: serverC.allowDelete ?? env.allowDelete,
+        hibp: serverC.hibp ?? env.hibp,
+        auditLog: serverC.auditLog ?? env.auditLog,
+      },
+    };
+  }
+
+  async update(dto: AuthConfigUpdate): Promise<AuthConfigView> {
+    for (const [id, u] of Object.entries(dto.social ?? {})) {
+      if (!SUPPORTED_PROVIDER_IDS.has(id)) throw new BadRequestException(`Unsupported social provider: ${id}`);
+      if (u.delete) await this.repo.delete({ key: socialKey(id) });
+      else await this.upsertProvider(socialKey(id), u);
+    }
+    if (dto.smtp) await this.upsertSmtp(dto.smtp);
+    if (dto.server) await this.upsertServer(dto.server);
+    return this.describe();
+  }
+
+  private async upsertProvider(key: string, u: ProviderUpdate): Promise<void> {
+    const row = (await this.repo.findOneBy({ key })) ?? this.repo.create({ key, enabled: false, config: {}, secret: null });
+    const config = { ...(row.config as { clientId?: string; redirectURI?: string }) };
+    if (u.clientId !== undefined) config.clientId = u.clientId;
+    if (u.redirectURI !== undefined) config.redirectURI = u.redirectURI;
+    if (u.enabled !== undefined) row.enabled = u.enabled;
+    // Replace the secret only when a non-empty value is supplied; otherwise keep it.
+    if (u.clientSecret) row.secret = encryptSecret(u.clientSecret);
+    row.config = config;
+    await this.repo.save(row);
+  }
+
+  private async upsertSmtp(u: NonNullable<AuthConfigUpdate["smtp"]>): Promise<void> {
+    const row = (await this.repo.findOneBy({ key: "smtp" })) ?? this.repo.create({ key: "smtp", enabled: false, config: {}, secret: null });
+    const config = { ...(row.config as Record<string, unknown>) };
+    for (const f of ["host", "port", "secure", "user", "from"] as const) if (u[f] !== undefined) config[f] = u[f];
+    if (u.enabled !== undefined) row.enabled = u.enabled;
+    if (u.pass) row.secret = encryptSecret(u.pass);
+    row.config = config;
+    await this.repo.save(row);
+  }
+
+  private async upsertServer(u: NonNullable<AuthConfigUpdate["server"]>): Promise<void> {
+    const row = (await this.repo.findOneBy({ key: "server" })) ?? this.repo.create({ key: "server", enabled: true, config: {}, secret: null });
+    const config = { ...(row.config as Record<string, unknown>) };
+    for (const f of ["requireEmailVerification", "allowDelete", "hibp", "auditLog"] as const) if (u[f] !== undefined) config[f] = u[f];
+    row.config = config;
+    await this.repo.save(row);
+  }
+}

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

@@ -0,0 +1,65 @@
+import nodemailer, { type Transporter } from "nodemailer";
+import { pool } from "../auth/db";
+import { createConfigStore, type SmtpConfig } from "@podosoft/podokit-auth";
+
+// SMTP is admin-configurable in the DB (auth_config), falling back to SMTP_* env,
+// and applied live: the transport is rebuilt when the config changes (short TTL),
+// so no restart is needed. With neither DB nor env config, fall back to a transport
+// that just logs the message so nothing crashes for lack of mail config.
+const store = createConfigStore(pool);
+const TTL_MS = 3_000;
+
+function buildTransport(smtp: SmtpConfig | null): Transporter {
+  if (!smtp) return nodemailer.createTransport({ jsonTransport: true });
+  return nodemailer.createTransport({
+    host: smtp.host,
+    port: smtp.port,
+    secure: smtp.secure,
+    auth: smtp.user ? { user: smtp.user, pass: smtp.pass ?? "" } : undefined,
+  });
+}
+
+let transport = buildTransport(null);
+let transportFrom = process.env.MAIL_FROM ?? "PodoKit <no-reply@example.com>";
+let hasSmtp = false;
+let checkedAt = 0;
+let signature = "";
+
+async function getTransport(): Promise<Transporter> {
+  if (checkedAt !== 0 && Date.now() - checkedAt < TTL_MS) return transport;
+  checkedAt = Date.now();
+  try {
+    const smtp = await store.smtpConfig();
+    const next = JSON.stringify(smtp ?? null);
+    if (next !== signature) {
+      transport = buildTransport(smtp);
+      transportFrom = smtp?.from ?? process.env.MAIL_FROM ?? "PodoKit <no-reply@example.com>";
+      hasSmtp = !!smtp;
+      signature = next;
+    }
+  } catch {
+    /* keep the last-good transport */
+  }
+  return transport;
+}
+
+export type Mail = { to: string; subject: string; text: string; html?: string };
+
+export async function sendMail(mail: Mail): Promise<void> {
+  const t = await getTransport();
+  const info = await t.sendMail({ from: transportFrom, ...mail });
+  if (!hasSmtp) {
+    // JSON transport: surface the message so the link is grabbable from logs.
+    console.log(`[mailer] no SMTP configured; message not delivered:\n${info.message as string}`);
+  }
+}
+
+// Minimal HTML wrapper for a titled call-to-action email.
+export function actionEmail(title: string, body: string, url: string, cta: string): string {
+  return `<div style="font-family:system-ui,sans-serif;max-width:480px;margin:0 auto">
+  <h1 style="font-size:20px">${title}</h1>
+  <p>${body}</p>
+  <p><a href="${url}" style="display:inline-block;padding:10px 16px;background:#111;color:#fff;border-radius:8px;text-decoration:none">${cta}</a></p>
+  <p style="color:#666;font-size:13px">Or paste this link into your browser:<br>${url}</p>
+</div>`;
+}