@percepta/create 4.1.12 → 4.1.14

package/templates/monorepo/auth/src/auth.ts

@@ -1,12 +1,30 @@
 import { createLazyAuth, createPerceptaAuth } from "@percepta/auth/better-auth";
+import type { BetterAuthOptions } from "better-auth";
+import { admin } from "better-auth/plugins";
+import { genericOAuth, okta } from "better-auth/plugins/generic-oauth";
 import { db } from "./drizzle/db";
 import { accounts } from "./drizzle/schema/auth/accounts";
 import { sessions } from "./drizzle/schema/auth/sessions";
 import { verifications } from "./drizzle/schema/auth/verifications";
 import { users } from "./drizzle/schema/users";
 
+type AuthMode = "username-password" | "google" | "okta";
+
+const DEFAULT_AUTH_MODE: AuthMode = "__AUTH_MODE__" as AuthMode;
 const isBuildPhase = process.env.NEXT_PHASE === "phase-production-build";
 
+function isAuthMode(value: string | undefined): value is AuthMode {
+  return (
+    value === "username-password" || value === "google" || value === "okta"
+  );
+}
+
+function getAuthMode(): AuthMode {
+  return isAuthMode(process.env.AUTH_MODE)
+    ? process.env.AUTH_MODE
+    : DEFAULT_AUTH_MODE;
+}
+
 function requiredEnv(name: string): string {
   const value = process.env[name];
   if (value == null || value.length === 0) {
@@ -15,6 +33,11 @@ function requiredEnv(name: string): string {
   return value;
 }
 
+function optionalEnv(name: string): string | undefined {
+  const value = process.env[name];
+  return value == null || value.length === 0 ? undefined : value;
+}
+
 function getSecret(): string {
   if (isBuildPhase) {
     return "build-placeholder-not-used-at-runtime";
@@ -31,10 +54,59 @@ function getBaseUrl(): string {
   );
 }
 
+function getSocialProviders(
+  authMode: AuthMode,
+): BetterAuthOptions["socialProviders"] {
+  if (authMode !== "google") return undefined;
+
+  const clientId = optionalEnv("GOOGLE_CLIENT_ID");
+  const clientSecret = optionalEnv("GOOGLE_CLIENT_SECRET");
+  if (clientId == null || clientSecret == null) return undefined;
+
+  const hostedDomain = optionalEnv("GOOGLE_HOSTED_DOMAIN");
+  return {
+    google: {
+      clientId,
+      clientSecret,
+      ...(hostedDomain == null ? {} : { hd: hostedDomain }),
+    },
+  };
+}
+
+function getPlugins(authMode: AuthMode): BetterAuthOptions["plugins"] {
+  if (authMode !== "okta") return undefined;
+
+  const clientId = optionalEnv("OKTA_CLIENT_ID");
+  const clientSecret = optionalEnv("OKTA_CLIENT_SECRET");
+  const issuer = optionalEnv("OKTA_ISSUER");
+  if (clientId == null || clientSecret == null || issuer == null) {
+    return undefined;
+  }
+
+  return [
+    admin(),
+    genericOAuth({
+      config: [
+        okta({
+          clientId,
+          clientSecret,
+          issuer,
+        }),
+      ],
+    }),
+  ];
+}
+
 function createAuth() {
+  const authMode = getAuthMode();
+
   return createPerceptaAuth({
     baseURL: getBaseUrl(),
     database: db,
+    emailAndPassword: {
+      enabled: authMode === "username-password",
+    },
+    plugins: getPlugins(authMode),
     schema: {
       user: users,
       session: sessions,
@@ -42,6 +114,7 @@ function createAuth() {
       verification: verifications,
     },
     secret: getSecret(),
+    socialProviders: getSocialProviders(authMode),
   });
 }
 

package/templates/webapp/AGENTS.md

@@ -16,7 +16,7 @@ Next.js 16 full-stack application scaffolded from the Mosaic webapp template via
 - `pnpm db:generate` — generate Drizzle migrations
 - `pnpm db:migrate` — apply migrations
 - `pnpm db:studio` — run migrations, then open Drizzle Studio
-- `pnpm db:seed` — seed shared-auth dev users and local grants for customer admin, app admin, app user, and app non-user personas (all use password)
+- `pnpm db:seed` — seed shared-auth dev users and local grants for customer admin, app admin, app user, and app non-user personas; username/password scaffolds set the dev password to `password`
 
 **Package manager**: Always use `pnpm`, never `npm` or `yarn`.
 

package/templates/webapp/README.md

@@ -7,7 +7,7 @@ Design theme: `__MOSAIC_DESIGN_THEME__`
 ## Features
 
 - **Next.js 16** with App Router
-- **Authentication** via Better Auth with email/password credentials
+- **Authentication** via Better Auth (__AUTH_MODE_LABEL__)
 - **Database** with PostgreSQL, Drizzle ORM, and migrations
 - **Access Control** with SpiceDB schema authoring and manifest validation
 - **Logging** with Pino and structured safe/unsafe data separation
@@ -147,27 +147,60 @@ logger.error({ safe: { documentId } }, "Processing failed", error);
 
 This app consumes the customer monorepo's shared [Better Auth](https://better-auth.com) package, `@__REPO_NAME__/auth`. The app still serves local development auth routes, but the users, sessions, accounts, groups, and group memberships live in the shared customer auth database. Deployed apps should receive that shared database through `AUTH_DATABASE_URL` from the monorepo auth Secret; `DATABASE_URL` is reserved for this app's own database.
 
-Required auth environment variables:
+This app was scaffolded with `__AUTH_MODE_LABEL__` as its auth setup. New apps
+inherit the customer monorepo's workspace auth setup from
+`.mosaic-workspace.json` by default, and individual apps can override that
+default with `AUTH_MODE`.
+
+Every app requires:
 
 ```bash
+AUTH_MODE=__AUTH_MODE__
 BETTER_AUTH_SECRET=generate-with-openssl-rand-base64-32
 ```
 
 Auth uses `BETTER_AUTH_URL`, `APP_BASE_URL`, or `http://localhost:3000`, in
 that order, for its base URL.
 
+For username/password auth, local setup creates credential users and app access
+grants. Google OAuth sign-in requires `GOOGLE_CLIENT_ID` and
+`GOOGLE_CLIENT_SECRET`; optionally set `GOOGLE_HOSTED_DOMAIN`. Register these
+redirect URIs in the Google OAuth client:
+
+```text
+http://localhost:3000/api/auth/callback/google
+https://<app-host>/api/auth/callback/google
+```
+
+Okta OIDC sign-in requires `OKTA_CLIENT_ID`, `OKTA_CLIENT_SECRET`, and
+`OKTA_ISSUER`. The issuer usually looks like
+`https://dev-xxxxx.okta.com/oauth2/default`. Register these redirect URIs in
+the Okta app integration:
+
+```text
+http://localhost:3000/api/auth/oauth2/callback/okta
+https://<app-host>/api/auth/oauth2/callback/okta
+```
+
+OAuth users still pass through the app's SpiceDB access gate after sign-in. In
+local development, `pnpm db:seed` creates access principals for the example
+emails; provider sign-ins with the same verified email can link to those users.
+For other emails, grant app access from the settings UI or seed/apply an access
+grant before expecting the protected app pages to load.
+
 Remote deployments should also set `AUTH_DATABASE_URL` from the shared auth
 database Secret. Local development can omit it and use the root-created local
 `auth` database.
 
-To create dev users:
+To create dev users and local app access grants:
 
 ```bash
 pnpm db:seed
-# Creates customer-admin@example.com / password as a customer admin
-# Creates app-admin@example.com / password as an app admin
-# Creates app-user@example.com / password as an app user
-# Creates non-user@example.com / password with no app access
+# Creates customer-admin@example.com as a customer admin
+# Creates app-admin@example.com as an app admin
+# Creates app-user@example.com as an app user
+# Creates non-user@example.com with no app access
+# Username/password scaffolds also set each password to: password
 ```
 
 ## Access Control

package/templates/webapp/env.example.template

@@ -7,7 +7,18 @@ APP_BASE_URL=http://localhost:3000
 DATABASE_URL=postgresql://postgres:postgres@localhost:5434/__DB_NAME__
 
 # Authentication (Better Auth)
+# App auth setup selected by @percepta/create: __AUTH_MODE_LABEL__
+# Defaults to the workspace auth setup unless this app was scaffolded with an override.
+AUTH_MODE=__AUTH_MODE__
 BETTER_AUTH_SECRET=generate-with-openssl-rand-base64-32
+# Google OAuth apps should fill these:
+# GOOGLE_CLIENT_ID=
+# GOOGLE_CLIENT_SECRET=
+# GOOGLE_HOSTED_DOMAIN=
+# Okta OIDC apps should fill these:
+# OKTA_CLIENT_ID=
+# OKTA_CLIENT_SECRET=
+# OKTA_ISSUER=
 
 # Shared Auth Database
 # Deployed apps should set this from the customer monorepo auth database Secret.

package/templates/webapp/scripts/seed.ts

@@ -47,8 +47,35 @@ const SEEDED_USERS = [
   },
 ] as const;
 
+type AuthMode = "username-password" | "google" | "okta";
+interface AdminCreateUserApi {
+  createUser(input: {
+    body: {
+      email: string;
+      name: string;
+      password?: string;
+    };
+  }): Promise<{ user: { id: string } }>;
+}
+
+const DEFAULT_AUTH_MODE: AuthMode = "__AUTH_MODE__" as AuthMode;
+
+function isAuthMode(value: string | undefined): value is AuthMode {
+  return (
+    value === "username-password" || value === "google" || value === "okta"
+  );
+}
+
+function getAuthMode(): AuthMode {
+  return isAuthMode(process.env.AUTH_MODE)
+    ? process.env.AUTH_MODE
+    : DEFAULT_AUTH_MODE;
+}
+
 async function main(): Promise<void> {
   nextEnv.loadEnvConfig(process.cwd());
+  const authMode = getAuthMode();
+  process.env.AUTH_MODE = authMode;
   // oxlint-disable-next-line typescript/no-explicit-any
   (globalThis as any).AsyncLocalStorage = AsyncLocalStorage;
 
@@ -80,36 +107,46 @@ async function main(): Promise<void> {
 
     let userId: string;
     if (existing != null) {
-      await authDb
-        .update(users)
-        .set({ role: seededUser.role })
-        .where(eq(users.id, existing.id));
       userId = existing.id;
       console.log(
-        `Seed user "${seededUser.email}" already exists (id: ${existing.id}). Ensured ${seededUser.role} role.`,
+        `Seed user "${seededUser.email}" already exists (id: ${existing.id}).`,
       );
     } else {
-      // Use Better Auth's signUpEmail API to create the user with a hashed password
-      const res = await auth.api.signUpEmail({
-        body: {
-          email: seededUser.email,
-          name: seededUser.name,
-          password: seededUser.password,
-        },
-      });
-
-      await authDb
-        .update(users)
-        .set({ role: seededUser.role })
-        .where(eq(users.id, res.user.id));
-
-      userId = res.user.id;
-      console.log(
-        `Seed user created: ${seededUser.email} (id: ${res.user.id})`,
-      );
-      console.log(`  Password: ${seededUser.password}`);
+      if (authMode === "username-password") {
+        // Use Better Auth's signUpEmail API to create the user with a hashed password.
+        const res = await auth.api.signUpEmail({
+          body: {
+            email: seededUser.email,
+            name: seededUser.name,
+            password: seededUser.password,
+          },
+        });
+        userId = res.user.id;
+      } else {
+        // The admin plugin can create local access principals when this app
+        // starts with an external OAuth provider instead of credentials.
+        const adminApi = auth.api as typeof auth.api & AdminCreateUserApi;
+        const res = await adminApi.createUser({
+          body: {
+            email: seededUser.email,
+            name: seededUser.name,
+          },
+        });
+        userId = res.user.id;
+      }
+
+      console.log(`Seed user created: ${seededUser.email} (id: ${userId})`);
+      if (authMode === "username-password") {
+        console.log(`  Password: ${seededUser.password}`);
+      }
     }
 
+    await authDb
+      .update(users)
+      .set({ role: seededUser.role })
+      .where(eq(users.id, userId));
+    console.log(`  Ensured role: ${seededUser.role}`);
+
     const subject = toUserSubject(userId);
     switch (seededUser.access) {
       case "customer_admin":

package/templates/webapp/src/app/(auth)/auth/signin/CredentialsSignInForm.tsx

@@ -5,7 +5,7 @@ import { Button, Input } from "@percepta/design";
 import { ArrowRight } from "lucide-react";
 import Link from "next/link";
 import { useRouter, useSearchParams } from "next/navigation";
-import React, { useCallback } from "react";
+import React, { useCallback, useState } from "react";
 import { Controller, useForm } from "react-hook-form";
 import { toast } from "sonner";
 import z from "zod";
@@ -19,6 +19,7 @@ const CREDENTIALS_SCHEMA = z.object({
 });
 
 type Credentials = z.infer<typeof CREDENTIALS_SCHEMA>;
+type AuthMode = "username-password" | "google" | "okta";
 
 // Defaults are empty in production so deployed instances don't suggest seeded
 // credentials. In dev we prefill with the seeded user from `pnpm db:seed` so a
@@ -27,9 +28,10 @@ const DEFAULTS: Credentials = IS_DEV
   ? { email: "app-admin@example.com", password: "password" }
   : { email: "", password: "" };
 
-export function CredentialsSignInForm() {
+export function CredentialsSignInForm({ authMode }: { authMode: AuthMode }) {
   const router = useRouter();
   const searchParams = useSearchParams();
+  const [isProviderSubmitting, setIsProviderSubmitting] = useState(false);
 
   const {
     control,
@@ -41,6 +43,8 @@ export function CredentialsSignInForm() {
   });
 
   const callbackUrl = searchParams.get("callbackUrl") ?? "/";
+  const usesCredentials = authMode === "username-password";
+  const providerName = authMode === "google" ? "Google" : "Okta";
 
   const submit = useCallback(
     async ({ email, password }: Credentials): Promise<void> => {
@@ -64,6 +68,28 @@ export function CredentialsSignInForm() {
     [callbackUrl, router],
   );
 
+  const signInWithProvider = useCallback(async (): Promise<void> => {
+    setIsProviderSubmitting(true);
+    try {
+      const { error } =
+        authMode === "google"
+          ? await authClient.signIn.social({
+              provider: "google",
+              callbackURL: callbackUrl,
+            })
+          : await authClient.signIn.oauth2({
+              providerId: "okta",
+              callbackURL: callbackUrl,
+            });
+
+      if (error != null) {
+        toast.error(error.message ?? `Unable to sign in with ${providerName}.`);
+      }
+    } finally {
+      setIsProviderSubmitting(false);
+    }
+  }, [authMode, callbackUrl, providerName]);
+
   return (
     <div className="grid gap-8">
       <div className="grid gap-3">
@@ -72,60 +98,82 @@ export function CredentialsSignInForm() {
           <span>Sign in</span>
         </p>
         <h1 className="app-auth-title">Welcome back.</h1>
-        <p className="app-auth-copy text-sm">
-          Need an account?{" "}
-          <Link
-            className="app-auth-link"
-            href={`/auth/signup?callbackUrl=${encodeURIComponent(callbackUrl)}`}
-          >
-            Create one
-          </Link>
-        </p>
+        {usesCredentials ? (
+          <p className="app-auth-copy text-sm">
+            Need an account?{" "}
+            <Link
+              className="app-auth-link"
+              href={`/auth/signup?callbackUrl=${encodeURIComponent(callbackUrl)}`}
+            >
+              Create one
+            </Link>
+          </p>
+        ) : (
+          <p className="app-auth-copy text-sm">
+            Use your {providerName} account to continue.
+          </p>
+        )}
       </div>
-      <form className="app-auth-form" onSubmit={handleSubmit(submit)}>
-        <div className="app-auth-fields">
-          <Controller
-            control={control}
-            name="email"
-            render={({ field, fieldState }) => (
-              <FormItem
-                className="app-auth-field"
-                label="Email"
-                fieldState={fieldState}
-              >
-                <Input {...field} type="email" autoComplete="email" />
-              </FormItem>
-            )}
-          />
-          <Controller
-            control={control}
-            name="password"
-            render={({ field, fieldState }) => (
-              <FormItem
-                className="app-auth-field"
-                label="Password"
-                fieldState={fieldState}
-              >
-                <Input
-                  {...field}
-                  type="password"
-                  autoComplete="current-password"
-                />
-              </FormItem>
-            )}
-          />
-        </div>
-        <div className="flex justify-end">
-          <Button
-            className="app-auth-submit"
-            type="submit"
-            loading={isSubmitting}
-          >
-            <span>Sign In</span>
-            <ArrowRight aria-hidden={true} />
-          </Button>
+      {usesCredentials ? (
+        <form className="app-auth-form" onSubmit={handleSubmit(submit)}>
+          <div className="app-auth-fields">
+            <Controller
+              control={control}
+              name="email"
+              render={({ field, fieldState }) => (
+                <FormItem
+                  className="app-auth-field"
+                  label="Email"
+                  fieldState={fieldState}
+                >
+                  <Input {...field} type="email" autoComplete="email" />
+                </FormItem>
+              )}
+            />
+            <Controller
+              control={control}
+              name="password"
+              render={({ field, fieldState }) => (
+                <FormItem
+                  className="app-auth-field"
+                  label="Password"
+                  fieldState={fieldState}
+                >
+                  <Input
+                    {...field}
+                    type="password"
+                    autoComplete="current-password"
+                  />
+                </FormItem>
+              )}
+            />
+          </div>
+          <div className="flex justify-end">
+            <Button
+              className="app-auth-submit"
+              type="submit"
+              loading={isSubmitting}
+            >
+              <span>Sign In</span>
+              <ArrowRight aria-hidden={true} />
+            </Button>
+          </div>
+        </form>
+      ) : (
+        <div className="app-auth-form">
+          <div className="flex justify-end">
+            <Button
+              className="app-auth-submit"
+              type="button"
+              loading={isProviderSubmitting}
+              onClick={signInWithProvider}
+            >
+              <span>Continue with {providerName}</span>
+              <ArrowRight aria-hidden={true} />
+            </Button>
+          </div>
         </div>
-      </form>
+      )}
     </div>
   );
 }

package/templates/webapp/src/app/(auth)/auth/signin/page.tsx

@@ -1,7 +1,7 @@
 import type { Metadata } from "next";
 import { redirect } from "next/navigation";
 import { Suspense } from "react";
-import { getServerSession } from "../../../../lib/auth";
+import { AUTH_MODE, getServerSession } from "../../../../lib/auth";
 import { CredentialsSignInForm } from "./CredentialsSignInForm";
 
 export const metadata: Metadata = {
@@ -21,7 +21,7 @@ export default async function SignInPage() {
         <p className="text-center text-sm text-muted-foreground">Loading…</p>
       }
     >
-      <CredentialsSignInForm />
+      <CredentialsSignInForm authMode={AUTH_MODE} />
     </Suspense>
   );
 }

package/templates/webapp/src/app/(auth)/auth/signup/page.tsx

@@ -1,20 +1,46 @@
 import type { Metadata } from "next";
 import { redirect } from "next/navigation";
 import { Suspense } from "react";
-import { getServerSession } from "../../../../lib/auth";
+import { AUTH_MODE, getServerSession } from "../../../../lib/auth";
 import { CredentialsSignUpForm } from "./CredentialsSignUpForm";
 
+type SearchParamValue = string | string[] | undefined;
+
 export const metadata: Metadata = {
   title: "Create Account — __APP_TITLE__",
 };
 
-export default async function SignUpPage() {
+function getFirstSearchParam(value: SearchParamValue): string | undefined {
+  return Array.isArray(value) ? value[0] : value;
+}
+
+function getSignInPath(searchParams: Record<string, SearchParamValue>): string {
+  const callbackUrl = getFirstSearchParam(searchParams.callbackUrl);
+  if (callbackUrl == null || callbackUrl.length === 0) {
+    return "/auth/signin";
+  }
+
+  return `/auth/signin?callbackUrl=${encodeURIComponent(callbackUrl)}`;
+}
+
+export default async function SignUpPage({
+  searchParams,
+}: {
+  searchParams?:
+    | Promise<Record<string, SearchParamValue>>
+    | Record<string, SearchParamValue>;
+} = {}) {
+  const resolvedSearchParams = (await searchParams) ?? {};
   const session = await getServerSession();
 
   if (session?.user != null) {
     redirect("/");
   }
 
+  if (AUTH_MODE !== "username-password") {
+    redirect(getSignInPath(resolvedSearchParams));
+  }
+
   return (
     <Suspense
       fallback={

package/templates/webapp/src/lib/auth/app-auth-mode.ts

@@ -0,0 +1,20 @@
+export type AuthMode = "username-password" | "google" | "okta";
+
+const APP_AUTH_MODE: AuthMode = "__AUTH_MODE__" as AuthMode;
+
+function isAuthMode(value: string | undefined): value is AuthMode {
+  return (
+    value === "username-password" || value === "google" || value === "okta"
+  );
+}
+
+export function ensureAppAuthModeEnv(): AuthMode {
+  if (isAuthMode(process.env.AUTH_MODE)) {
+    return process.env.AUTH_MODE;
+  }
+
+  process.env.AUTH_MODE = APP_AUTH_MODE;
+  return APP_AUTH_MODE;
+}
+
+export const AUTH_MODE = ensureAppAuthModeEnv();

package/templates/webapp/src/lib/auth/index.ts

@@ -1,7 +1,8 @@
-import { auth } from "@__REPO_NAME__/auth";
+import { auth, type BetterAuthSession } from "@__REPO_NAME__/auth";
 import { headers } from "next/headers";
+import { AUTH_MODE, type AuthMode } from "./app-auth-mode";
 
-export { auth, type BetterAuthSession } from "@__REPO_NAME__/auth";
+export { AUTH_MODE, auth, type AuthMode, type BetterAuthSession };
 
 export async function getServerSession() {
   return auth.api.getSession({

package/templates/webapp/src/lib/auth-client.ts

@@ -1,10 +1,12 @@
 import type { BetterAuthClientOptions } from "better-auth";
-import { adminClient } from "better-auth/client/plugins";
+import { adminClient, genericOAuthClient } from "better-auth/client/plugins";
 import { createAuthClient } from "better-auth/react";
 
 const adminPlugin: ReturnType<typeof adminClient> = adminClient();
+const genericOAuthPlugin: ReturnType<typeof genericOAuthClient> =
+  genericOAuthClient();
 const options = {
-  plugins: [adminPlugin],
+  plugins: [adminPlugin, genericOAuthPlugin],
 } satisfies BetterAuthClientOptions;
 export const authClient: ReturnType<typeof createAuthClient<typeof options>> =
   createAuthClient(options);