Wire provider selection into codegen with just-in-time user provisioning

Author: FranjoMindek

examples/auth-providers/custom-clerk/main.wasp.ts

@@ -1,6 +1,16 @@
-import { action, app, page, query, route, waspAuth } from "@wasp.sh/spec";
+import {
+  action,
+  app,
+  customAuthProvider,
+  page,
+  query,
+  route,
+} from "@wasp.sh/spec";
+import { App } from "./src/App" with { type: "ref" };
 import { MainPage } from "./src/MainPage" with { type: "ref" };
 import { LoginPage } from "./src/auth/LoginPage" with { type: "ref" };
+import { clerkAuthProvider } from "./src/auth/provider" with { type: "ref" };
+import { clientEnvSchema } from "./src/env" with { type: "ref" };
 import { createTask, getMyTasks } from "./src/operations" with { type: "ref" };
 
 export default app({
@@ -11,22 +21,41 @@ export default app({
   auth: {
     userEntity: "User",
     onAuthFailedRedirectTo: "/login",
-    // Wasp's own auth, selected explicitly. Everything that only makes sense
-    // when Wasp runs signup and login -- methods, hooks, the success redirect --
-    // lives inside waspAuth(), so none of it can leak into an app using an
-    // external provider.
-    provider: waspAuth({
-      methods: {
-        usernameAndPassword: {},
+    // Clerk owns signup and login entirely; Wasp has no auth methods of its
+    // own here, and the provider union makes them inexpressible.
+    provider: customAuthProvider({
+      id: "clerk",
+      server: clerkAuthProvider,
+      capabilities: ["session-revocation"],
+      // Rendered into the generated env validation: a missing var fails at
+      // boot with this explanation, not at the first authenticated request.
+      env: {
+        server: [
+          { name: "CLERK_SECRET_KEY", doc: "Clerk dashboard → API keys" },
+          { name: "CLERK_PUBLISHABLE_KEY", doc: "Clerk dashboard → API keys" },
+          {
+            name: "CLERK_JWT_KEY",
+            optional: true,
+            doc: "enables networkless JWT verification",
+          },
+        ],
+        client: [],
       },
-      onAuthSucceededRedirectTo: "/",
     }),
   },
 
+  client: {
+    // Wraps the app in Clerk's provider and bridges its token to Wasp's client.
+    rootComponent: App,
+    envValidationSchema: clientEnvSchema,
+  },
+
   spec: [
+    // Identical to the other two apps.
     route("MainRoute", "/", page(MainPage, { authRequired: true })),
     route("LoginRoute", "/login", page(LoginPage)),
     query(getMyTasks, { entities: ["Task"], auth: true }),
     action(createTask, { entities: ["Task"], auth: true }),
+    // Note: no api() declarations. Clerk contributes no routes and no tables.
   ],
 });

examples/auth-providers/custom-clerk/src/App.tsx

@@ -0,0 +1,55 @@
+import { ClerkProvider, useAuth as useClerkAuth } from "@clerk/clerk-react";
+import { useEffect } from "react";
+import { env } from "wasp/client";
+import { clearSessionId, setSessionId } from "wasp/client/api";
+
+// Wasp's typed client env, declared in `clientEnvSchema` (see main.wasp.ts).
+// Using this rather than `import.meta.env` keeps the file type-checkable.
+const publishableKey = env.REACT_APP_CLERK_PUBLISHABLE_KEY;
+
+/**
+ * Bridges Clerk's session into Wasp's client.
+ *
+ * Wasp sends its credential as `Authorization: Bearer <token>`, so we hand it
+ * Clerk's token whenever Clerk has one. This is the only Wasp-specific glue on
+ * the client side, and it is the mirror image of what the Better Auth example's
+ * login page does after a successful sign-in.
+ *
+ * Clerk's tokens are short-lived (~60s) and its SDK refreshes them on a timer,
+ * so this effect re-runs and keeps Wasp's stored credential fresh.
+ */
+function ClerkToWaspSessionBridge({ children }: { children: React.ReactNode }) {
+  const { isSignedIn, getToken } = useClerkAuth();
+
+  useEffect(() => {
+    let cancelled = false;
+    async function sync() {
+      const token = isSignedIn ? await getToken() : null;
+      if (!cancelled) {
+        // Wasp stores the credential it attaches to every API call. Clearing it
+        // on sign-out is what makes `logout()` uniform across providers.
+        if (token) {
+          setSessionId(token);
+        } else {
+          clearSessionId();
+        }
+      }
+    }
+    void sync();
+    const interval = setInterval(() => void sync(), 30_000);
+    return () => {
+      cancelled = true;
+      clearInterval(interval);
+    };
+  }, [isSignedIn, getToken]);
+
+  return <>{children}</>;
+}
+
+export function App({ children }: { children: React.ReactNode }) {
+  return (
+    <ClerkProvider publishableKey={publishableKey}>
+      <ClerkToWaspSessionBridge>{children}</ClerkToWaspSessionBridge>
+    </ClerkProvider>
+  );
+}

examples/auth-providers/custom-clerk/src/auth/LoginPage.tsx

@@ -1,22 +1,22 @@
-import { useState } from "react";
-import { LoginForm, SignupForm } from "wasp/client/auth";
+import { SignIn } from "@clerk/clerk-react";
 
 /**
- * Identical to `wasp-auth/`'s login page. This is the file that changes when
- * the app adopts its real auth provider -- everything else stays put.
+ * The Clerk login page, and the clearest illustration of where Wasp's uniform
+ * line falls.
+ *
+ * There is no `<LoginForm />` here and there cannot be one. Clerk has no
+ * server-side password endpoint, so Wasp cannot post credentials on the app's
+ * behalf -- the browser must talk to Clerk's Frontend API directly. Clerk's own
+ * component does that.
+ *
+ * Compare `../../../wasp-auth/src/auth/LoginPage.tsx` and
+ * `../../../better-auth/src/auth/LoginPage.tsx`. The login pages differ per
+ * provider. Everything else in these apps does not.
  */
 export function LoginPage() {
-  const [isSignup, setIsSignup] = useState(false);
-
   return (
-    <main
-      style={{ maxWidth: 380, margin: "3rem auto", fontFamily: "system-ui" }}
-    >
-      <h1>{isSignup ? "Sign up" : "Log in"}</h1>
-      {isSignup ? <SignupForm /> : <LoginForm />}
-      <button onClick={() => setIsSignup((v) => !v)}>
-        {isSignup ? "I already have an account" : "I need an account"}
-      </button>
+    <main style={{ display: "grid", placeItems: "center", marginTop: "3rem" }}>
+      <SignIn />
     </main>
   );
 }

examples/auth-providers/custom-clerk/src/auth/provider.ts

@@ -0,0 +1,84 @@
+import { createClerkClient } from "@clerk/backend";
+import type {
+  AuthProvider,
+  VerifiedSession,
+} from "wasp/server/auth/provider/types";
+
+const clerk = createClerkClient({
+  secretKey: process.env.CLERK_SECRET_KEY,
+  publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
+});
+
+/**
+ * Clerk, expressed as a Wasp `AuthProvider`.
+ *
+ * This app hand-writes the adapter and registers it with `customAuthProvider()`
+ * -- the escape hatch for providers nobody has packaged yet. Compare `../clerk`,
+ * where the same provider ships as an npm package instead. Clerk is by far the
+ * least work to integrate: it contributes **no Prisma models and no routes**. It
+ * only ever answers "whose request is this?".
+ *
+ * It is also the adapter that proves why `AuthProvider` and
+ * `SessionIssuingAuthProvider` are separate interfaces. Clerk has **no
+ * server-side password login at all** -- password verification lives on its
+ * Frontend API behind a browser-held `__client` cookie, and its Backend API has
+ * no endpoint that turns credentials into a session. So this object implements
+ * `AuthProvider` and stops there. A uniform `login(email, password)` could only
+ * be implemented for Clerk as something that throws or silently ignores its
+ * arguments; a missing capability is the honest alternative.
+ */
+export const clerkAuthProvider: AuthProvider = {
+  /**
+   * Becomes `AuthIdentity.providerName`, so it must stay stable across deploys.
+   */
+  id: "clerk",
+
+  /**
+   * Wasp hands every adapter a standard web `Request` -- built from the HTTP
+   * request, or synthesized with just an `Authorization` header for websocket
+   * auth. Clerk's SDK consumes one natively, so there is nothing to convert.
+   *
+   * Clerk reads either its `__session` cookie or an `Authorization: Bearer`
+   * header transparently, so the same code serves web and native clients.
+   *
+   * With `jwtKey` set this is local RS256 verification with no network call;
+   * without it, Clerk fetches (and caches) the JWKS.
+   */
+  async authenticate(request: Request): Promise<VerifiedSession | null> {
+    const requestState = await clerk.authenticateRequest(request, {
+      jwtKey: process.env.CLERK_JWT_KEY,
+    });
+
+    if (!requestState.isAuthenticated) {
+      return null;
+    }
+
+    const { userId, sessionId, sessionClaims } = requestState.toAuth();
+    if (!userId || !sessionId) {
+      return null;
+    }
+
+    return {
+      sessionId,
+      subjectId: userId,
+      // The verified JWT's claims, recorded by Wasp when it provisions the
+      // local user. NOTE: Clerk's default session token carries no email --
+      // add one to the token template in the Clerk dashboard if the app's
+      // user entity needs it at provisioning time.
+      claims: sessionClaims as VerifiedSession["claims"],
+    };
+  },
+
+  /**
+   * Clerk sessions are revocable server-side, which is what lets `logout()` stay
+   * uniform across all the example apps.
+   *
+   * Worth knowing: because Clerk's session tokens are short-lived JWTs verified
+   * locally, revocation is not instantaneous -- an already-issued token stays
+   * valid until it expires (~60s by default). Wasp's own auth revokes instantly.
+   * Same API, weaker guarantee.
+   */
+  async revokeSession(sessionId: string): Promise<void> {
+    await clerk.sessions.revokeSession(sessionId);
+  },
+};

examples/auth-providers/custom-clerk/src/env.ts

@@ -0,0 +1,10 @@
+import * as z from "zod";
+
+/**
+ * Clerk's publishable key has to reach the browser, so it goes through Wasp's
+ * client env schema rather than `import.meta.env` -- that keeps it typed and
+ * validated at startup instead of failing at render time.
+ */
+export const clientEnvSchema = z.object({
+  REACT_APP_CLERK_PUBLISHABLE_KEY: z.string().min(1),
+});

waspc/data/Generator/templates/sdk/wasp/auth/user.ts

@@ -125,7 +125,12 @@ function makeAuthUser(data: AuthUserData): AuthUser {
   return {
     ...data,
     getFirstProviderUserId: () => {
-      const identities = Object.values(data.identities).filter(isNotNull);
+      // The cast keeps this working when `identities` is empty, which is the case
+      // for an app using a custom auth provider and no Wasp auth methods: the
+      // generated type is then `{}` and `Object.values` would yield `unknown[]`.
+      const identities = Object.values(
+        data.identities as Record<string, { id: string } | null>
+      ).filter(isNotNull);
       return identities.length > 0 ? identities[0].id : null;
     },
   };

waspc/data/Generator/templates/sdk/wasp/server/auth/provider/index.ts

@@ -1,5 +1,11 @@
-import { waspAuthProvider } from './wasp.js'
+{{={= =}=}}
 import { type AuthProvider } from './types.js'
+{=# isCustomAuthProviderUsed =}
+{=& authProvider.importStatement =}
+{=/ isCustomAuthProviderUsed =}
+{=^ isCustomAuthProviderUsed =}
+import { waspAuthProvider } from './wasp.js'
+{=/ isCustomAuthProviderUsed =}
 
 // PRIVATE API
 export {
@@ -13,9 +19,19 @@ export {
 /**
  * The auth provider this app runs on.
  *
- * There is exactly one today and it is not configurable. This module exists so that
- * everything else in Wasp depends on the `AuthProvider` interface rather than on a
- * concrete implementation -- making the provider selectable is a later, additive
- * change that will not touch any of its consumers.
+ * Everything else in Wasp depends on the `AuthProvider` interface rather than on
+ * a concrete implementation, so selecting a different one here is the only change
+ * needed to authenticate against something other than Wasp's own auth.
+ */
+export const authProvider: AuthProvider =
+  {=# isCustomAuthProviderUsed =}{= authProvider.importIdentifier =}{=/ isCustomAuthProviderUsed =}{=^ isCustomAuthProviderUsed =}waspAuthProvider{=/ isCustomAuthProviderUsed =}
+
+// PRIVATE API
+/**
+ * Whether the provider owns Wasp's auth entity.
+ *
+ * Wasp's own auth writes the `Auth` table itself, so a subject id from it already
+ * identifies a local row. An external provider's subject id is foreign, and Wasp
+ * has to resolve it to a local user -- provisioning one on first sight.
  */
-export const authProvider: AuthProvider = waspAuthProvider
+export const providerOwnsAuthEntity: boolean = {=# isCustomAuthProviderUsed =}false{=/ isCustomAuthProviderUsed =}{=^ isCustomAuthProviderUsed =}true{=/ isCustomAuthProviderUsed =}

waspc/data/Generator/templates/sdk/wasp/server/auth/provider/types.ts

@@ -1,3 +1,6 @@
+import { type AuthProvider } from '@wasp.sh/auth-contract'
+import { type FromRegister } from '../../../types/register.js'
+
 // PRIVATE API
 /**
  * The contract between Wasp and an authentication provider.
@@ -13,3 +16,12 @@ export {
   type SessionIssuingAuthProvider,
   type VerifiedSession,
 } from '@wasp.sh/auth-contract'
+
+// PRIVATE API
+/**
+ * The provider the developer registered via `app.auth.provider`, if any.
+ *
+ * Declared here so that a user-written adapter is type-checked against the
+ * contract at build time rather than failing somewhere inside the session layer.
+ */
+export type RegisteredAuthProvider = FromRegister<'authProvider', AuthProvider>