@podosoft/podokit 0.10.2 → 0.11.0

package/dist/templates/modules/admin-dashboard/files/tests/ui/users.ui.spec.ts

@@ -1,6 +1,8 @@
 import { expect, test } from "@playwright/test";
 import { ready } from "../helpers/hydration";
 
+const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
+
 test("admin can create a user with a custom role @smoke", async ({ page }) => {
   await ready(page, "/admin/users");
   await page.getByRole("button", { name: "Add user" }).click();
@@ -49,3 +51,44 @@ test("row menu exposes admin actions", async ({ page }) => {
   await expect(page.getByRole("menuitem", { name: "Manage" })).toBeVisible();
   await expect(page.getByRole("menuitem", { name: "Impersonate" })).toBeVisible();
 });
+
+test("admin can approve a pending registration from the user list @smoke", async ({ page }) => {
+  const email = `pending-ui-${Date.now()}@example.com`;
+  const created = await page.request.post("/api/auth/admin/create-user", {
+    headers: { origin: base },
+    data: { email, password: "Podokit3e-Str0ng!pw", name: "Pending UI", role: "user" },
+  });
+  expect(created.ok()).toBeTruthy();
+  const userId = ((await created.json()).user?.id ?? "") as string;
+
+  try {
+    expect(userId).toBeTruthy();
+    expect(
+      (await page.request.post("/api/auth/admin/update-user", {
+        headers: { origin: base },
+        data: { userId, data: { signupApproved: false } },
+      })).ok(),
+    ).toBeTruthy();
+
+    await ready(page, "/admin/users");
+    await page.locator("#toolbar-search").fill(email);
+    await page.getByRole("button", { name: "Search", exact: true }).click();
+    const row = page.getByRole("row", { name: new RegExp(email) });
+    await expect(row.getByText("Pending approval")).toBeVisible();
+    await row.getByRole("button").click();
+    const response = page.waitForResponse(
+      (res) => res.url().endsWith("/api/auth/admin/update-user") && res.request().method() === "POST",
+    );
+    await page.getByRole("menuitem", { name: "Approve sign-up" }).click();
+    expect((await response).ok()).toBeTruthy();
+    await expect(page.getByText("Sign-up approved")).toBeVisible();
+    await expect(row.getByText("Active")).toBeVisible();
+  } finally {
+    if (userId) {
+      await page.request.post("/api/auth/admin/remove-user", {
+        headers: { origin: base },
+        data: { userId },
+      });
+    }
+  }
+});

package/dist/templates/modules/admin-dashboard/module.manifest.json

@@ -36,13 +36,13 @@
     {
       "file": "apps/api/src/auth/auth.ts",
       "marker": "// podokit:end:auth-options",
-      "text": "trustedOrigins: (process.env.CORS_ORIGIN ?? \"http://localhost:5001\").split(\",\").map((origin) => origin.trim()),\n  databaseHooks: {\n    user: {\n      create: {\n        before: async (user) => ({\n          data: {\n            ...user,\n            role: (process.env.ADMIN_EMAILS ?? \"\")\n              .split(\",\")\n              .map((email) => email.trim().toLowerCase())\n              .includes(user.email.toLowerCase())\n              ? \"admin\"\n              : \"user\",\n          },\n        }),\n      },\n    },\n  },"
+      "text": "trustedOrigins: (process.env.CORS_ORIGIN ?? \"http://localhost:5001\").split(\",\").map((origin) => origin.trim()),"
     },
     {
       "file": "AGENTS.md",
       "marker": "<!-- podokit:end:agents-modules -->",
       "optional": true,
-      "text": "### admin-dashboard\n- Admin console lives at `/admin/*` (users, sessions, organizations, audit, settings, account). Emails in `ADMIN_EMAILS` become admins on sign-up.\n- **Every list/table MUST use the shared `$lib/components/data-table.svelte` (`DataTable`)** \u2014 it gives sortable headers + a footer pagination. Add search/filters with `$lib/components/table-toolbar.svelte`. Never assemble `Table.Root`/`Table.Header`/`Table.Body` by hand.\n"
+      "text": "### admin-dashboard\n- Admin console lives at `/admin/*` (users, sessions, organizations, audit, settings, account). Emails in `ADMIN_EMAILS` become admins on sign-up. When sign-up approval is enabled, self-registered users stay pending until an administrator approves them on `/admin/users`; administrator-created users bypass the queue.\n- **Every list/table MUST use the shared `$lib/components/data-table.svelte` (`DataTable`)** \u2014 it gives sortable headers + a footer pagination. Add search/filters with `$lib/components/table-toolbar.svelte`. Never assemble `Table.Root`/`Table.Header`/`Table.Body` by hand.\n"
     },
     {
       "file": "apps/api/src/app.module.ts",
@@ -57,9 +57,9 @@
   ],
   "instructions": [
     "Set ADMIN_EMAILS in .env (comma-separated). Those emails become admins on sign-up.",
-    "Re-run the auth migration to add the admin columns:  npx @better-auth/cli migrate -y --config apps/api/src/auth/auth.ts",
+    "Re-run the auth migration to add the admin and sign-up approval columns:  npx @better-auth/cli migrate -y --config apps/api/src/auth/auth.ts",
     "Start the app (npm run dev), open /signup, register an ADMIN_EMAILS address, then sign in.",
-    "Admin pages: /admin/users (list, ban, set role, revoke sessions). Signed-in users manage their profile and security at /account; /admin/account remains available in the admin shell. Admin, account, authentication, maintenance, and API responses include X-Robots-Tag: noindex, nofollow by default.",
+    "Admin pages: /admin/users (list, approve pending registrations, ban, set role, revoke sessions). Signed-in users manage their profile and security at /account; /admin/account remains available in the admin shell. Admin, account, authentication, maintenance, and API responses include X-Robots-Tag: noindex, nofollow by default.",
     "Password reset emails go through the mailer module (installed automatically with auth); in dev without SMTP they are logged to the API console. Configure SMTP in admin settings or via SMTP_* env for production."
   ]
 }

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

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+
+const args = process.argv.slice(2);
+
+function has(flag) {
+  return args.includes(flag);
+}
+
+function value(flag) {
+  const index = args.indexOf(flag);
+  return index >= 0 ? args[index + 1] : undefined;
+}
+
+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 -- --smtp
+  npm run auth:configure -- --check-only --provider google
+
+Required environment for writes:
+  AUTH_SETUP_ORIGIN          Public app origin (or BETTER_AUTH_URL)
+  AUTH_SETUP_ADMIN_EMAIL     Administrator email
+  AUTH_SETUP_ADMIN_PASSWORD  Administrator password
+
+OAuth environment:
+  OAUTH_CLIENT_ID / OAUTH_CLIENT_SECRET
+  OAUTH_REDIRECT_URI (optional)
+  Provider-specific variables such as GOOGLE_CLIENT_ID also work.
+
+SMTP environment (with --smtp):
+  SMTP_HOST, SMTP_PORT, SMTP_SECURE, SMTP_USER, SMTP_PASS, MAIL_FROM
+
+Options:
+  --provider <id>                 Configure a social provider
+  --smtp                          Configure SMTP from environment variables
+  --require-signup-approval       Require admin approval for future registrations
+  --no-require-signup-approval    Auto-approve future registrations
+  --check-only                    Check public capabilities without writing
+  --dry-run                       Print a redacted plan without writing
+`);
+}
+
+function required(name, current) {
+  if (!current) throw new Error(`${name} is required.`);
+  return current;
+}
+
+function providerEnvName(provider, suffix) {
+  return `${provider.toUpperCase().replaceAll("-", "_")}_${suffix}`;
+}
+
+function bool(value, fallback = false) {
+  if (value === undefined) return fallback;
+  return value === "true";
+}
+
+function redactedPlan(body) {
+  return {
+    ...body,
+    ...(body.social
+      ? {
+          social: Object.fromEntries(
+            Object.entries(body.social).map(([id, provider]) => [
+              id,
+              { ...provider, clientSecret: provider.clientSecret ? "<redacted>" : undefined },
+            ]),
+          ),
+        }
+      : {}),
+    ...(body.smtp
+      ? { smtp: { ...body.smtp, pass: body.smtp.pass ? "<redacted>" : undefined } }
+      : {}),
+  };
+}
+
+function cookies(response) {
+  const getSetCookie = response.headers.getSetCookie;
+  const values = typeof getSetCookie === "function"
+    ? getSetCookie.call(response.headers)
+    : [response.headers.get("set-cookie")].filter(Boolean);
+  return values.map((item) => item.split(";", 1)[0]).join("; ");
+}
+
+async function signIn(origin, email, password) {
+  const response = await fetch(`${origin}/api/auth/sign-in/email`, {
+    method: "POST",
+    headers: { "content-type": "application/json", origin },
+    body: JSON.stringify({ email, password }),
+    redirect: "manual",
+  });
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Administrator sign-in failed (${response.status}): ${text}`);
+  }
+  const cookie = cookies(response);
+  if (!cookie) throw new Error("Administrator sign-in returned no session cookie.");
+  return cookie;
+}
+
+async function publicCapabilities(origin) {
+  const response = await fetch(`${origin}/api/account/capabilities`);
+  if (!response.ok) throw new Error(`Capabilities check failed (${response.status}).`);
+  return response.json();
+}
+
+async function main() {
+  if (has("--help") || has("-h")) {
+    usage();
+    return;
+  }
+
+  const rawOrigin = process.env.AUTH_SETUP_ORIGIN ?? process.env.BETTER_AUTH_URL ?? "http://localhost:5002";
+  const origin = new URL(rawOrigin).origin;
+  const provider = value("--provider");
+  const configureSmtp = has("--smtp");
+  const approval = has("--require-signup-approval")
+    ? true
+    : has("--no-require-signup-approval")
+      ? false
+      : undefined;
+
+  if (provider && !/^[a-z0-9-]+$/.test(provider)) throw new Error("Provider id must use lowercase letters, numbers, or hyphens.");
+
+  if (provider) console.log(`OAuth callback URL: ${origin}/api/auth/callback/${provider}`);
+  if (has("--check-only")) {
+    const capabilities = await publicCapabilities(origin);
+    console.log(JSON.stringify(capabilities, null, 2));
+    if (provider && !capabilities.providers?.includes(provider)) {
+      throw new Error(`Provider "${provider}" is not enabled.`);
+    }
+    return;
+  }
+
+  const body = {};
+  if (provider) {
+    const clientId = process.env.OAUTH_CLIENT_ID ?? process.env[providerEnvName(provider, "CLIENT_ID")];
+    const clientSecret = process.env.OAUTH_CLIENT_SECRET ?? process.env[providerEnvName(provider, "CLIENT_SECRET")];
+    body.social = {
+      [provider]: {
+        enabled: true,
+        clientId: required("OAUTH_CLIENT_ID", clientId),
+        clientSecret: required("OAUTH_CLIENT_SECRET", clientSecret),
+        ...(process.env.OAUTH_REDIRECT_URI ? { redirectURI: process.env.OAUTH_REDIRECT_URI } : {}),
+      },
+    };
+  }
+  if (configureSmtp) {
+    body.smtp = {
+      enabled: true,
+      host: required("SMTP_HOST", process.env.SMTP_HOST),
+      port: Number(process.env.SMTP_PORT ?? 587),
+      secure: bool(process.env.SMTP_SECURE),
+      user: process.env.SMTP_USER ?? "",
+      from: process.env.MAIL_FROM ?? "",
+      ...(process.env.SMTP_PASS ? { pass: process.env.SMTP_PASS } : {}),
+    };
+  }
+  if (approval !== undefined) body.server = { requireSignupApproval: approval };
+
+  if (Object.keys(body).length === 0) throw new Error("Choose --provider, --smtp, or a sign-up approval option.");
+  if (has("--dry-run")) {
+    console.log(JSON.stringify(redactedPlan(body), null, 2));
+    return;
+  }
+
+  const email = required("AUTH_SETUP_ADMIN_EMAIL", process.env.AUTH_SETUP_ADMIN_EMAIL);
+  const password = required("AUTH_SETUP_ADMIN_PASSWORD", process.env.AUTH_SETUP_ADMIN_PASSWORD);
+  const cookie = await signIn(origin, email, password);
+  const response = await fetch(`${origin}/api/account/auth-config`, {
+    method: "PUT",
+    headers: { "content-type": "application/json", origin, cookie },
+    body: JSON.stringify(body),
+  });
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Authentication configuration failed (${response.status}): ${text}`);
+  }
+  console.log("Authentication configuration updated.");
+  console.log(JSON.stringify(await publicCapabilities(origin), null, 2));
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});

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

@@ -60,6 +60,7 @@ export class AccountController {
       providers: snapshot.providers,
       deleteAccount: snapshot.allowDelete,
       emailVerification: snapshot.requireEmailVerification,
+      signupApprovalRequired: snapshot.requireSignupApproval,
       passwordBreachCheck: snapshot.passwordBreachCheck,
       auditLog: snapshot.auditLog,
       roles: ROLE_NAMES,

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

@@ -1,4 +1,5 @@
 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 { actionEmail, sendMail } from "../mail/mailer";
 import { sendSms } from "../sms/sms";
@@ -9,12 +10,20 @@ import { type AuthConfig, envAuthConfig, SUPPORTED_PROVIDER_IDS } from "@podosof
 import { apiKey } from "@better-auth/api-key";
 import { passkey } from "@better-auth/passkey";
 import { oauthProvider } from "@better-auth/oauth-provider";
+import { SIGNUP_APPROVAL_REQUIRED } from "@podosoft/podokit-contracts";
 // podokit:begin:auth-imports
 // podokit:end:auth-imports
 
 // 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());
 
+const adminEmails = new Set(
+  (process.env.ADMIN_EMAILS ?? "")
+    .split(",")
+    .map((email) => email.trim().toLowerCase())
+    .filter(Boolean),
+);
+
 // 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
@@ -115,6 +124,47 @@ export function buildAuth(config: AuthConfig) {
   // podokit:begin:auth-plugins
   // podokit:end:auth-plugins
 
+  const databaseHooks: NonNullable<BetterAuthOptions["databaseHooks"]> = {
+    user: {
+      create: {
+        before: async (user, context) => {
+          const adminEmail = adminEmails.has(user.email.toLowerCase());
+          const createdByAdmin = context?.path === "/admin/create-user";
+          return {
+            data: {
+              ...user,
+              // The admin plugin contributes `role` before this hook. Preserve an
+              // explicitly requested admin-created role, while bootstrap emails
+              // always become administrators.
+              ...(Object.prototype.hasOwnProperty.call(user, "role")
+                ? { role: adminEmail ? "admin" : user.role }
+                : {}),
+              // Existing rows are treated as approved through the field default.
+              // Only self-registration while the policy is enabled starts pending.
+              signupApproved: adminEmail || createdByAdmin || !config.requireSignupApproval,
+            },
+          };
+        },
+      },
+    },
+    session: {
+      create: {
+        before: async (session, context) => {
+          if (!context) return;
+          const user = (await context.context.internalAdapter.findUserById(session.userId)) as {
+            signupApproved?: boolean | null;
+          } | null;
+          if (user?.signupApproved === false) {
+            throw APIError.from("FORBIDDEN", {
+              code: SIGNUP_APPROVAL_REQUIRED,
+              message: "Your account is waiting for administrator approval.",
+            });
+          }
+        },
+      },
+    },
+  };
+
   // 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.
@@ -126,6 +176,9 @@ export function buildAuth(config: AuthConfig) {
     database: pool,
     emailAndPassword: {
       enabled: true,
+      // Pending email/password registrations should complete without creating a
+      // session. All later sign-in methods are enforced by the session hook below.
+      autoSignIn: !config.requireSignupApproval,
       requireEmailVerification: config.requireEmailVerification,
       sendResetPassword: async ({ user, url }) => {
         await sendMail({
@@ -163,6 +216,14 @@ export function buildAuth(config: AuthConfig) {
       },
     },
     user: {
+      additionalFields: {
+        signupApproved: {
+          type: "boolean",
+          required: false,
+          defaultValue: true,
+          input: false,
+        },
+      },
       // 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.
@@ -193,6 +254,7 @@ export function buildAuth(config: AuthConfig) {
       // Self-service account deletion — admin-toggleable (auth_config), applied live.
       deleteUser: { enabled: config.allowDelete },
     },
+    databaseHooks,
     // podokit:begin:auth-options
     // podokit:end:auth-options
   });

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

@@ -16,7 +16,7 @@ export type AuthConfigView = {
   /** 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 };
+  server: { requireEmailVerification: boolean; requireSignupApproval: boolean; allowDelete: boolean; hibp: boolean; auditLog: boolean };
 };
 
 type ProviderUpdate = { enabled?: boolean; clientId?: string; clientSecret?: string; redirectURI?: string; delete?: boolean };
@@ -24,7 +24,7 @@ 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 };
+  server?: { requireEmailVerification?: boolean; requireSignupApproval?: boolean; allowDelete?: boolean; hibp?: boolean; auditLog?: boolean };
 };
 
 @Injectable()
@@ -53,7 +53,13 @@ export class AuthConfigService {
     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 };
+    const serverC = (serverRow?.config ?? {}) as {
+      requireEmailVerification?: boolean;
+      requireSignupApproval?: boolean;
+      allowDelete?: boolean;
+      hibp?: boolean;
+      auditLog?: boolean;
+    };
     return {
       social,
       catalog: SUPPORTED_SOCIAL_PROVIDERS,
@@ -68,6 +74,7 @@ export class AuthConfigService {
       },
       server: {
         requireEmailVerification: serverC.requireEmailVerification ?? env.requireEmailVerification,
+        requireSignupApproval: serverC.requireSignupApproval ?? env.requireSignupApproval,
         allowDelete: serverC.allowDelete ?? env.allowDelete,
         hibp: serverC.hibp ?? env.hibp,
         auditLog: serverC.auditLog ?? env.auditLog,
@@ -111,7 +118,9 @@ export class AuthConfigService {
   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];
+    for (const f of ["requireEmailVerification", "requireSignupApproval", "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/dot-claude/skills/podokit-configure-auth/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: podokit-configure-auth
+description: Configure and verify PodoKit social OAuth providers, SMTP delivery, and the administrator sign-up approval policy. Use when enabling Google, Apple, or another Better Auth provider; calculating callback URLs; applying credentials through Admin Settings; configuring outbound mail; or diagnosing why a configured sign-in method is unavailable.
+---
+
+# Configure PodoKit authentication
+
+Use the generated `auth:configure` command so credentials enter the encrypted `auth_config` store through the admin API. Keep provider secrets, SMTP passwords, and administrator passwords out of source files, command arguments, logs, and commits.
+
+## Choose the workflow
+
+- Read [references/google.md](references/google.md) for Google sign-in, including External audience requirements.
+- Read [references/apple.md](references/apple.md) for Apple sign-in and client-secret rotation.
+- Read [references/smtp.md](references/smtp.md) for Google Workspace SMTP relay and DNS authentication.
+- Run the same generated command for other provider IDs. Confirm the provider appears in Admin Settings before applying it.
+
+## Prepare the app
+
+1. Confirm the `auth` and `admin-dashboard` modules are installed with `podo status`.
+2. Confirm `BETTER_AUTH_URL` is the public authentication origin. Production should use HTTPS.
+3. Run Better Auth and TypeORM migrations before configuring a new app:
+
+   ```bash
+   npm run migrate:all -w <app>-api
+   ```
+
+4. Derive the default callback as `<BETTER_AUTH_URL>/api/auth/callback/<provider>`. Only set `OAUTH_REDIRECT_URI` when the provider requires an explicit override.
+
+## Handle secrets safely
+
+Load secrets from the deployment secret manager or prompt for them in the current shell. Do not place secret values directly in command arguments.
+
+```bash
+export AUTH_SETUP_ORIGIN="https://example.com"
+export AUTH_SETUP_ADMIN_EMAIL="admin@example.com"
+printf "Admin password: " >&2
+IFS= read -r -s AUTH_SETUP_ADMIN_PASSWORD
+printf "\n" >&2
+export AUTH_SETUP_ADMIN_PASSWORD
+printf "OAuth client secret: " >&2
+IFS= read -r -s OAUTH_CLIENT_SECRET
+printf "\n" >&2
+export OAUTH_CLIENT_SECRET
+export OAUTH_CLIENT_ID="provider-client-id"
+```
+
+Unset sensitive variables when finished:
+
+```bash
+unset AUTH_SETUP_ADMIN_PASSWORD OAUTH_CLIENT_SECRET SMTP_PASS
+```
+
+## Preview and apply
+
+Preview a redacted plan first:
+
+```bash
+npm run auth:configure -w <app>-api -- --provider google --require-signup-approval --dry-run
+```
+
+Apply OAuth credentials and the approval policy:
+
+```bash
+npm run auth:configure -w <app>-api -- --provider google --require-signup-approval
+```
+
+Configure SMTP separately or in the same run. Passwordless IP-based relays may omit `SMTP_USER` and `SMTP_PASS`.
+
+```bash
+export SMTP_HOST="smtp-relay.example.com"
+export SMTP_PORT="587"
+export SMTP_SECURE="false"
+export MAIL_FROM="Example <noreply@example.com>"
+npm run auth:configure -w <app>-api -- --smtp
+```
+
+## Verify
+
+1. Check the public capability snapshot:
+
+   ```bash
+   npm run auth:configure -w <app>-api -- --provider google --check-only
+   ```
+
+2. Open `/login` and confirm the provider button appears.
+3. With sign-up approval enabled, register a disposable account and confirm it reaches `/pending-approval` without a session.
+4. Open `/admin/users`, filter by **Pending approval**, approve the account, and confirm sign-in succeeds.
+5. Confirm administrator-created users and emails in `ADMIN_EMAILS` do not enter the approval queue.
+6. Send a real verification or password-reset email and inspect SPF, DKIM, and DMARC results in the receiving mailbox.
+
+## Preserve provider independence
+
+Treat approval as a user lifecycle policy, not a provider option. Do not add Google-specific approval checks. New providers such as Apple must use the same user field and session gate automatically. Keep provider-specific setup and rotation details in a reference file while reusing `auth:configure` and Admin Settings.

package/dist/templates/modules/auth/files/dot-claude/skills/podokit-configure-auth/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "PodoKit Auth Setup"
+  short_description: "Configure social login, SMTP, and signup approval"
+  default_prompt: "Use $podokit-configure-auth to configure Google login, SMTP, and sign-up approval safely."

package/dist/templates/modules/auth/files/dot-claude/skills/podokit-configure-auth/references/apple.md

@@ -0,0 +1,18 @@
+# Apple sign-in
+
+Apple uses the same PodoKit provider pipeline and sign-up approval gate, but its credentials have a different lifecycle.
+
+1. Create an App ID with Sign in with Apple enabled.
+2. Create a Services ID for the web application and register the domain and callback `https://example.com/api/auth/callback/apple`.
+3. Create a Sign in with Apple key and retain the Team ID, Key ID, Services ID, and downloaded private key in a secret manager.
+4. Generate the OAuth client secret as a signed JWT. Apple client secrets expire, so automate rotation before expiry and reapply the new value with `auth:configure`.
+5. Configure the provider with `--provider apple`; use the Services ID as `OAUTH_CLIENT_ID` and the signed JWT as `OAUTH_CLIENT_SECRET`.
+6. Test first-time consent carefully because Apple may only provide the user's name on the first authorization.
+
+Do not store the Apple private key or generated client secret in the repository.
+
+Official references:
+
+- https://developer.apple.com/help/account/configure-app-capabilities/configure-sign-in-with-apple-for-the-web/
+- https://developer.apple.com/documentation/signinwithapplerestapi/generate-and-validate-tokens
+- https://better-auth.com/docs/authentication/apple

package/dist/templates/modules/auth/files/dot-claude/skills/podokit-configure-auth/references/google.md

@@ -0,0 +1,19 @@
+# Google sign-in
+
+Use a Google Cloud project owned by the organization, not a personal project.
+
+1. Configure the Google Auth Platform brand, support email, developer contact, privacy policy, and terms links.
+2. Choose **External** when every Google account may sign in. Publish the app to **Production** after testing; test mode restricts users and refresh-token lifetime.
+3. Create a **Web application** OAuth client.
+4. Add the web origin, for example `https://example.com`, to authorized JavaScript origins.
+5. Add the exact callback `https://example.com/api/auth/callback/google` to authorized redirect URIs.
+6. Supply the client ID and secret to `auth:configure`; never commit either value.
+7. Request only the scopes the application uses. Basic sign-in normally needs OpenID, email, and profile.
+
+Google may require verification for an External production app, especially when sensitive scopes or branding are involved. Keep the homepage, privacy policy, terms, and verified domain consistent with the OAuth consent screen.
+
+Official references:
+
+- https://developers.google.com/identity/protocols/oauth2/web-server
+- https://developers.google.com/identity/protocols/oauth2/policies
+- https://better-auth.com/docs/authentication/google

package/dist/templates/modules/auth/files/dot-claude/skills/podokit-configure-auth/references/smtp.md

@@ -0,0 +1,22 @@
+# SMTP delivery
+
+Prefer an organizational SMTP relay over a personal mailbox password.
+
+For Google Workspace SMTP relay:
+
+1. Add an SMTP relay rule in the Google Admin console.
+2. Restrict relay access to the production server's static public IP where possible.
+3. Restrict allowed senders to addresses in the organization's domains.
+4. Use `smtp-relay.gmail.com` on port 587 with STARTTLS (`SMTP_SECURE=false` in Nodemailer-style configuration), and require TLS in the Google Workspace relay policy.
+5. Leave `SMTP_USER` and `SMTP_PASS` empty for an IP-authorized relay.
+6. Set `MAIL_FROM` to an approved organizational sender.
+7. Publish SPF, enable Google DKIM signing, and publish DMARC. Start DMARC conservatively, review reports, then strengthen enforcement.
+8. Send a verification or password-reset message and inspect authentication results at the recipient.
+
+App passwords are a fallback only. They require two-step verification and may be unavailable under organization policies or Advanced Protection.
+
+Official references:
+
+- https://support.google.com/a/answer/2956491
+- https://support.google.com/a/answer/176600
+- https://support.google.com/accounts/answer/185833

package/dist/templates/modules/auth/module.manifest.json

@@ -17,7 +17,8 @@
     "@types/pg": "^8.11.10"
   },
   "scripts": {
-    "migrate:all": "node dist/migrate"
+    "migrate:all": "node dist/migrate",
+    "auth:configure": "node scripts/configure-auth.mjs"
   },
   "env": [
     "# \u2500\u2500 Auth (better-auth) \u2014 the only required secrets \u2500\u2500",
@@ -27,7 +28,7 @@
     "BETTER_AUTH_SECRET=change-me-in-production-min-32-characters",
     "BETTER_AUTH_URL=http://localhost:5002",
     "# Everything below is OPTIONAL. OAuth providers, SMTP, and the server-enforced",
-    "# toggles (email verification, breached-password check, self-delete) \u2014 plus the",
+    "# toggles (email verification, sign-up approval, breached-password check, self-delete) \u2014 plus the",
     "# feature flags \u2014 are configured on the admin Settings page, stored encrypted in",
     "# the DB and applied live (no restart). These env vars still work as a fallback/",
     "# override (e.g. for secrets-manager injection in production); the DB takes",
@@ -38,6 +39,7 @@
     "# SMS_WEBHOOK_URL=http://localhost:8095/sms",
     "# AUTH_HIBP=false",
     "# AUTH_EMAIL_VERIFICATION=false",
+    "# AUTH_REQUIRE_SIGNUP_APPROVAL=false",
     "# AUTH_ALLOW_DELETE=false",
     "# GOOGLE_CLIENT_ID=",
     "# GOOGLE_CLIENT_SECRET=",
@@ -104,7 +106,7 @@
       "file": "AGENTS.md",
       "marker": "<!-- podokit:end:agents-modules -->",
       "optional": true,
-      "text": "### auth (better-auth)\n- The API is **secure by default**: every route needs a session except `/health` and `/api/auth/*`. Opt a route out with `@Public()`; read the user with `@Session()`.\n- Configure OAuth providers, SMTP, and the server toggles on the admin **Settings** page (DB-backed, applied live \u2014 not via env). Only `BETTER_AUTH_SECRET` and `BETTER_AUTH_URL` are required env vars.\n- Development setup: create auth tables with `npx @better-auth/cli migrate -y --config apps/api/src/auth/auth.ts`, then run TypeORM migrations. Production images can run both from compiled output with `npm run migrate:all`.\n"
+      "text": "### auth (better-auth)\n- The API is **secure by default**: every route needs a session except `/health` and `/api/auth/*`. Opt a route out with `@Public()`; read the user with `@Session()`.\n- Configure OAuth providers, SMTP, sign-up approval, and the other server toggles on the admin **Settings** page (DB-backed, applied live \u2014 not via env). Only `BETTER_AUTH_SECRET` and `BETTER_AUTH_URL` are required env vars.\n- Use `npm run auth:configure -w <app>-api -- ...` and `.claude/skills/podokit-configure-auth` to apply OAuth/SMTP credentials without committing secrets. The sign-up approval gate is provider-independent; do not add provider-specific approval checks.\n- Development setup: create auth tables with `npx @better-auth/cli migrate -y --config apps/api/src/auth/auth.ts`, then run TypeORM migrations. Production images can run both from compiled output with `npm run migrate:all`.\n"
     }
   ],
   "instructions": [
@@ -114,6 +116,7 @@
     "After building a production image, run all Better Auth and TypeORM migrations:  npm run migrate:all",
     "Sign up:  curl -c cookies.txt -XPOST localhost:5002/api/auth/sign-up/email -H 'content-type: application/json' -d '{\"email\":\"a@example.com\",\"password\":\"password123\",\"name\":\"A\"}'",
     "Call a protected route with the session:  curl -b cookies.txt localhost:5002/account/me",
-    "Everything is protected by default; mark public routes with @Public(). Configure OAuth (Google/GitHub), SMTP, and server-enforced toggles on the admin Settings page \u2014 stored encrypted in the DB and applied live (no restart). Environment variables (GOOGLE_CLIENT_*, SMTP_*, AUTH_*) still work as an optional fallback/override."
+    "Use npm run auth:configure -w <app>-api -- --help for redacted OAuth, SMTP, and sign-up approval automation.",
+    "Everything is protected by default; mark public routes with @Public(). Configure OAuth providers, SMTP, and server-enforced toggles on the admin Settings page \u2014 stored encrypted in the DB and applied live (no restart). Environment variables (GOOGLE_CLIENT_*, SMTP_*, AUTH_*) still work as an optional fallback/override."
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podosoft/podokit",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "An opinionated but extensible starter toolkit and CLI for full-stack TypeScript apps with NestJS, SvelteKit, TailwindCSS, shadcn-svelte, Docker, and k3s.",
   "license": "Apache-2.0",
   "repository": {