Auth Hooks

waspc/ChangeLog.md

@@ -1,11 +1,23 @@
 # Changelog
 
-## 0.14.0 (2024-04-22)
+## 0.14.0 (TBD)
 
 ### 🎉 New Features
 
 - Simplified Auth User API: Introduced a simpler API for accessing user auth fields (for example `username`, `email`, `isEmailVerified`) directly on the `user` object, eliminating the need for helper functions.
 - Improved API for calling Operations (Queries and Actions) directly.
+- Auth Hooks: you can now hook into the auth process with `onBeforeSignup`, `onAfterSignup` hooks. You can also modify the OAuth redirect URL with `onBeforeOAuthRedirect` hook.
+
+  ```wasp
+  app myApp {
+    ...
+    auth: {
+      onBeforeSignup: import { onBeforeSignup } from "...",
+      onAfterSignup: import { onAfterSignup } from "...",
+      onBeforeOAuthRedirect: import { onBeforeOAuthRedirect } from "...",
+    },
+  }
+  ```
 
 ### ⚠️ Breaking Changes & Migration Guide
 

waspc/data/Generator/templates/sdk/wasp/server/auth/hooks.ts

@@ -0,0 +1,87 @@
+import type { Request as ExpressRequest } from 'express'
+import type { ProviderId, createUser } from '../../auth/utils.js'
+import { prisma } from '../index.js'
+import { Expand } from '../../universal/types.js'
+
+// PUBLIC API
+export type OnBeforeSignupHook = (
+  params: Expand<OnBeforeSignupHookParams>,
+) => void | Promise<void>
+
+// PUBLIC API
+export type OnAfterSignupHook = (
+  params: Expand<OnAfterSignupHookParams>,
+) => void | Promise<void>
+
+// PUBLIC API
+/**
+ * @returns Object with a URL that the OAuth flow should redirect to.
+ */
+export type OnBeforeOAuthRedirectHook = (
+  params: Expand<OnBeforeOAuthRedirectHookParams>,
+) => { url: URL } | Promise<{ url: URL }>
+
+// PRIVATE API (used in the SDK and the server)
+export type InternalAuthHookParams = {
+  /**
+   * Prisma instance that can be used to interact with the database.
+   */
+  prisma: typeof prisma
+}
+
+// NOTE: We should be exporting types that can be reached by users via other
+// exported types (e.g. using the Parameters<T> Typescript helper).
+// However, we are not exporting this type to keep the API surface smaller.
+// This type is only used internally by the SDK. Exporting it might confuse
+// users since the name is too similar to the exported function type.
+// Same goes for all other *Params types in this file.
+type OnBeforeSignupHookParams = {
+  /**
+   * Provider ID object that contains the provider name and the provide user ID.
+   */
+  providerId: ProviderId
+  /**
+   * Request object that can be used to access the incoming request.
+   */
+  req: ExpressRequest
+} & InternalAuthHookParams
+
+type OnAfterSignupHookParams = {
+  /**
+   * Provider ID object that contains the provider name and the provide user ID.
+   */
+  providerId: ProviderId
+  /**
+   * User object that was created during the signup process.
+   */
+  user: Awaited<ReturnType<typeof createUser>>
+  oauth?: {
+    /**
+     * Access token that was received during the OAuth flow.
+     */
+    accessToken: string
+    /**
+     * Unique request ID that was generated during the OAuth flow.
+     */
+    uniqueRequestId: string
+  },
+  /**
+   * Request object that can be used to access the incoming request.
+   */
+  req: ExpressRequest
+} & InternalAuthHookParams
+
+type OnBeforeOAuthRedirectHookParams = {
+  /**
+   * URL that the OAuth flow should redirect to.
+   */
+  url: URL
+  /**
+   * Unique request ID that was generated during the OAuth flow.
+   */
+  uniqueRequestId: string
+  /**
+   * Request object that can be used to access the incoming request.
+   */
+  req: ExpressRequest
+} & InternalAuthHookParams

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

@@ -23,6 +23,13 @@ export {
   ensureTokenIsPresent,
 } from '../../auth/validation.js'
 
+export type {
+  OnBeforeSignupHook,
+  OnAfterSignupHook,
+  OnBeforeOAuthRedirectHook,
+  InternalAuthHookParams,
+} from './hooks.js'
+
 {=# isEmailAuthEnabled =}
 export * from './email/index.js'
 {=/ isEmailAuthEnabled =}

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

@@ -17,7 +17,7 @@ export type AuthUser = AuthUserData & {
 }
 
 // PRIVATE API
-/**
+/*
  * Ideally, we'd do something like this:
  * ```
  * export type AuthUserData = ReturnType<typeof createAuthUserData>

waspc/data/Generator/templates/server/src/auth/hooks.ts

@@ -0,0 +1,80 @@
+{{={= =}=}}
+import { prisma } from 'wasp/server'
+import type {
+  OnAfterSignupHook,
+  OnBeforeOAuthRedirectHook,
+  OnBeforeSignupHook,
+  InternalAuthHookParams,
+} from 'wasp/server/auth'
+{=# onBeforeSignupHook.isDefined =}
+{=& onBeforeSignupHook.importStatement =}
+{=/ onBeforeSignupHook.isDefined =}
+{=# onAfterSignupHook.isDefined =}
+{=& onAfterSignupHook.importStatement =}
+{=/ onAfterSignupHook.isDefined =}
+{=# onBeforeOAuthRedirectHook.isDefined =}
+{=& onBeforeOAuthRedirectHook.importStatement =}
+{=/ onBeforeOAuthRedirectHook.isDefined =}
+
+/*
+  These are "internal hook functions" based on the user defined hook functions.
+
+  In the server code (e.g. email signup) we import these functions and call them.
+
+  We want to pass extra params to the user defined hook functions, but we don't want to
+  pass them when we call them in the server code.
+*/
+
+{=# onBeforeSignupHook.isDefined =}
+export const onBeforeSignupHook: InternalFunctionForHook<OnBeforeSignupHook> = (params) =>
+  {= onBeforeSignupHook.importIdentifier =}({
+    prisma,
+    ...params,
+  })
+{=/ onBeforeSignupHook.isDefined =}
+{=^ onBeforeSignupHook.isDefined =}
+/**
+ * This is a no-op function since the user didn't define the onBeforeSignup hook.
+ */
+export const onBeforeSignupHook: InternalFunctionForHook<OnBeforeSignupHook> = async (params) => {}
+{=/ onBeforeSignupHook.isDefined =}
+
+{=# onAfterSignupHook.isDefined =}
+export const onAfterSignupHook: InternalFunctionForHook<OnAfterSignupHook> = (params) =>
+  {= onAfterSignupHook.importIdentifier =}({
+    prisma,
+    ...params,
+  })
+{=/ onAfterSignupHook.isDefined =}
+{=^ onAfterSignupHook.isDefined =}
+/**
+ * This is a no-op function since the user didn't define the onAfterSignup hook.
+ */
+export const onAfterSignupHook: InternalFunctionForHook<OnAfterSignupHook> = async (params) => {}
+{=/ onAfterSignupHook.isDefined =}
+
+{=# onBeforeOAuthRedirectHook.isDefined =}
+export const onBeforeOAuthRedirectHook: InternalFunctionForHook<OnBeforeOAuthRedirectHook> = (params) =>
+  {= onBeforeOAuthRedirectHook.importIdentifier =}({
+    prisma,
+    ...params,
+  })
+{=/ onBeforeOAuthRedirectHook.isDefined =}
+{=^ onBeforeOAuthRedirectHook.isDefined =}
+/**
+ * This is an identity function since the user didn't define the onBeforeOAuthRedirect hook.
+ */
+export const onBeforeOAuthRedirectHook: InternalFunctionForHook<OnBeforeOAuthRedirectHook> = async (params) => params
+{=/ onBeforeOAuthRedirectHook.isDefined =}
+
+/*
+  We pass extra params to the user defined hook functions, but we don't want to
+  pass the extra params (e.g. 'prisma') when we call the hooks in the server code.
+  So, we need to remove the extra params from the params object which is used to define the
+  internal hook functions.
+*/
+type InternalFunctionForHook<Fn extends (args: never) => unknown | Promise<unknown>> = Fn extends (
+  params: infer P,
+) => infer R
+  ? (args: Omit<P, keyof InternalAuthHookParams>) => R
+  : never

waspc/data/Generator/templates/server/src/auth/providers/config/github.ts

@@ -77,13 +77,11 @@ const _waspConfig: ProviderConfig = {
 
         return createOAuthProviderRouter({
             provider,
-            stateTypes: ['state'],
+            oAuthType: 'OAuth2',
             userSignupFields: _waspUserSignupFields,
             getAuthorizationUrl: ({ state }) => github.createAuthorizationURL(state, config),
-            getProviderInfo: async ({ code }) => {
-                const { accessToken } = await github.validateAuthorizationCode(code);
-                return getGithubProfile(accessToken);
-            },
+            getProviderTokens: ({ code }) => github.validateAuthorizationCode(code),
+            getProviderInfo: ({ accessToken }) => getGithubProfile(accessToken),
         });
     },
 }

waspc/data/Generator/templates/server/src/auth/providers/config/google.ts

@@ -66,13 +66,11 @@ const _waspConfig: ProviderConfig = {
 
         return createOAuthProviderRouter({
             provider,
-            stateTypes: ['state', 'codeVerifier'],
+            oAuthType: 'OAuth2WithPKCE',
             userSignupFields: _waspUserSignupFields,
             getAuthorizationUrl: ({ state, codeVerifier }) => google.createAuthorizationURL(state, codeVerifier, config),
-            getProviderInfo: async ({ code, codeVerifier }) => {
-                const { accessToken } = await google.validateAuthorizationCode(code, codeVerifier);
-                return getGoogleProfile(accessToken);
-            },
+            getProviderTokens: ({ code, codeVerifier }) => google.validateAuthorizationCode(code, codeVerifier),
+            getProviderInfo: ({ accessToken }) => getGoogleProfile(accessToken),
         });
     },
 }

waspc/data/Generator/templates/server/src/auth/providers/config/keycloak.ts

@@ -68,13 +68,11 @@ const _waspConfig: ProviderConfig = {
 
         return createOAuthProviderRouter({
             provider,
-            stateTypes: ['state', 'codeVerifier'],
+            oAuthType: 'OAuth2WithPKCE',
             userSignupFields: _waspUserSignupFields,
             getAuthorizationUrl: ({ state, codeVerifier }) => keycloak.createAuthorizationURL(state, codeVerifier, config),
-            getProviderInfo: async ({ code, codeVerifier }) => {
-                const { accessToken } = await keycloak.validateAuthorizationCode(code, codeVerifier);
-                return getKeycloakProfile(accessToken);
-            },
+            getProviderTokens: ({ code, codeVerifier }) => keycloak.validateAuthorizationCode(code, codeVerifier),
+            getProviderInfo: ({ accessToken }) => getKeycloakProfile(accessToken),
         });
     },
 }