Merge pull request #163 from supertokens/session-claims

feat: session claims

Author: rishabhpoddar

CHANGELOG.md

@@ -7,6 +7,184 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [unreleased]
 
+### Added
+
+- Added support for session claims with related interfaces and classes.
+- Added `EmailVerificationClaim`.
+- `Mode` config is added to `evmodels.TypeInput`
+- `GetEmailForUserID` config is added to `evmodels.TypeInput`
+- Added `OnInvalidClaim` optional error handler to send InvalidClaim error responses.
+- Added `INVALID_CLAIMS` to `SessionErrors`.
+- Added `InvalidClaimStatusCode` optional config to set the status code of InvalidClaim errors.
+- Added `OverrideGlobalClaimValidators` to options of `getSession` and `verifySession`.
+- Added `MergeIntoAccessTokenPayload` to the Session recipe and session objects which should be preferred to the now deprecated `UpdateAccessTokenPayload`.
+- Added `AssertClaims`, `ValidateClaimsForSessionHandle`, `ValidateClaimsInJWTPayload` to the Session recipe to support validation of the newly added `EmailVerificationClaim`.
+- Added `FetchAndSetClaim`, `GetClaimValue`, `SetClaimValue` and `RemoveClaim` to the Session recipe to manage claims.
+- Added `AssertClaims`, `FetchAndSetClaim`, `GetClaimValue`, `SetClaimValue` and `RemoveClaim` to session objects to manage claims.
+- Added sessionContainer to the input of `GenerateEmailVerifyTokenPOST`, `VerifyEmailPOST`, `IsEmailVerifiedGET`.
+- Adds default UserContext for verifySession calls that contains the request object.
+- Added `UserRoleClaim` and `PermissionClaim` to user roles recipe.
+
+### Breaking changes
+- Changed `SignInUp` third party recipe function to accept an email string instead of an object that takes `{ID: string, IsVerified: boolean}`.
+- The frontend SDK should be updated to a version supporting session claims!
+  - supertokens-auth-react: >= 0.25.0
+  - supertokens-web-js: >= 0.2.0
+- `EmailVerification` recipe is now not initialized as part of auth recipes, it should be added to the `recipeList` directly instead.
+- Email verification related overrides (`EmailVerificationFeature` prop of `Override`) moved from auth recipes into the `EmailVerification` recipe config.
+- ThirdParty recipe no longer takes EmailDelivery config -> use Emailverification recipe's EmailDelivery instead.
+- Moved email verification related configs from the `EmailDelivery` config of auth recipes into a separate `EmailVerification` email delivery config.
+- Updated return type of `GetEmailForUserId` in the `EmailVerification` recipe config. It should now return `OK`, `EmailDoesNotExistError` or `UnknownUserIDError` as response.
+- Removed `GetResetPasswordURL`, `GetEmailVerificationURL`, `GetLinkDomainAndPath`. Changing these urls can be done in the email delivery configs instead.
+- Removed `UnverifyEmail`, `RevokeEmailVerificationTokens`, `IsEmailVerified`, `VerifyEmailUsingToken` and `CreateEmailVerificationToken` from auth recipes. These should be called on the `EmailVerification` recipe instead.
+- Changed function signature for email verification APIs to accept a sessionContainer as an input.
+- Changed Session API interface functions:
+  - `RefreshPOST` now returns a Session container object.
+  - `SignOutPOST` now takes in an optional session object as a parameter.
+- `SessionContainer` is renamed to `TypeSessionContainer` and `SessionContainer` is now an alias for `*TypeSessionContainer`. All `*SessionContainer` is now replaced with `SessionContainer`.
+- Removed unused parameter `email` from `thirdpartyemailpassword.GetUserByThirdPartyInfoWithContext` function.
+
+### Migration
+
+Before:
+
+```go
+
+supertokens.Init(supertokens.TypeInput{
+    AppInfo: supertokens.AppInfo{
+        AppName:       "...",
+        APIDomain:     "...",
+        WebsiteDomain: "...",
+    },
+
+    RecipeList: []supertokens.Recipe{
+        emailpassword.Init(&epmodels.TypeInput{
+            EmailVerificationFeature: evmodels.TypeInput{
+                // ...
+            },
+            Override: &epmodels.OverrideStruct{
+                EmailVerificationFeature: &evmodels.OverrideStruct{
+                    // ...
+                },
+            },
+        }),
+    },
+})
+
+```
+
+After the update:
+
+```go
+
+supertokens.Init(supertokens.TypeInput{
+    AppInfo: supertokens.AppInfo{
+        AppName:       "...",
+        APIDomain:     "...",
+        WebsiteDomain: "...",
+    },
+
+    RecipeList: []supertokens.Recipe{
+        emailverification.Init(evmodels.TypeInput{
+            Mode: evmodels.ModeRequired, // or evmodels.ModeOptional
+            // all config should be moved here from the emailVerificationFeature prop of the EmailPassword recipe config
+            Override: &evmodels.OverrideStruct{
+                // move the overrides from the emailVerificationFeature prop of the override config in the EmailPassword init here
+            },
+        }),
+        emailpassword.Init(nil),
+    },
+})
+
+```
+
+### Passwordless users and email verification
+
+If you turn on email verification your email-based passwordless users may be redirected to an email verification screen in their existing session.
+Logging out and logging in again will solve this problem or they could click the link in the email to verify themselves.
+
+You can avoid this by running a script that will:
+
+1. list all users of passwordless
+2. create an emailverification token for each of them if they have email addresses
+3. user the token to verify their address
+
+Something similar to this script:
+
+```go
+package main
+
+import (
+	"github.com/supertokens/supertokens-golang/recipe/emailverification"
+	"github.com/supertokens/supertokens-golang/recipe/emailverification/evmodels"
+	"github.com/supertokens/supertokens-golang/recipe/passwordless"
+	"github.com/supertokens/supertokens-golang/recipe/passwordless/plessmodels"
+	"github.com/supertokens/supertokens-golang/recipe/session"
+	"github.com/supertokens/supertokens-golang/supertokens"
+)
+
+func main() {
+	supertokens.Init(supertokens.TypeInput{
+		AppInfo: supertokens.AppInfo{
+			AppName:       "...",
+			APIDomain:     "...",
+			WebsiteDomain: "...",
+		},
+
+		RecipeList: []supertokens.Recipe{
+			emailverification.Init(evmodels.TypeInput{
+				Mode: evmodels.ModeRequired,
+			}),
+			passwordless.Init(plessmodels.TypeInput{
+				FlowType: "USER_INPUT_CODE_AND_MAGIC_LINK",
+				ContactMethodEmailOrPhone: plessmodels.ContactMethodEmailOrPhoneConfig{
+					Enabled: true,
+				},
+			}),
+			session.Init(nil),
+		},
+	})
+
+	var paginationToken *string
+	recipeList := []string{"passwordless"}
+	limit := 100
+	done := false
+
+	for !done {
+		userList, err := supertokens.GetUsersNewestFirst(paginationToken, &limit, &recipeList)
+		if err != nil {
+			panic(err)
+		}
+
+		for _, user := range userList.Users {
+			if user.RecipeId == "passwordless" && user.User["email"] != nil {
+				token, err := emailverification.CreateEmailVerificationToken(user.User["id"].(string), nil)
+				if err != nil {
+					panic(err)
+				}
+				if token.OK != nil {
+					_, err := emailverification.VerifyEmailUsingToken(token.OK.Token)
+					if err != nil {
+						panic(err)
+					}
+				}
+			}
+
+			done = (userList.NextPaginationToken == nil)
+			paginationToken = userList.NextPaginationToken
+		}
+	}
+}
+```
+
+#### User roles
+
+The UserRoles recipe now adds role and permission information into the access token payload by default. If you are already doing this manually, this will result in duplicate data in the access token.
+
+- You can disable this behaviour by setting `SkipAddingRolesToAccessToken` and `SkipAddingPermissionsToAccessToken` to true in the recipe init.
+- Check how to use the new claims in the updated guide: https://supertokens.com/docs/userroles/protecting-routes
+
+
 ## [0.8.3] - 2022-07-30
 ### Added
 - Adds test to verify that session container uses overridden functions

examples/with-chi-oso/main.go

@@ -8,6 +8,8 @@ import (
 	"github.com/go-chi/cors"
 	"github.com/supertokens/supertokens-golang/examples/with-chi-oso/database"
 	"github.com/supertokens/supertokens-golang/examples/with-chi-oso/service"
+	"github.com/supertokens/supertokens-golang/recipe/emailverification"
+	"github.com/supertokens/supertokens-golang/recipe/emailverification/evmodels"
 	"github.com/supertokens/supertokens-golang/recipe/session"
 	"github.com/supertokens/supertokens-golang/recipe/thirdparty"
 	"github.com/supertokens/supertokens-golang/recipe/thirdparty/tpmodels"
@@ -32,6 +34,9 @@ func main() {
 			WebsiteDomain: "http://localhost:3000",
 		},
 		RecipeList: []supertokens.Recipe{
+			emailverification.Init(evmodels.TypeInput{
+				Mode: evmodels.ModeRequired,
+			}),
 			thirdpartyemailpassword.Init(&tpepmodels.TypeInput{
 				Providers: []tpmodels.TypeProvider{
 					// We have provided you with development keys which you can use for testsing.

examples/with-chi/main.go

@@ -6,6 +6,8 @@ import (
 
 	"github.com/go-chi/chi/v5"
 	"github.com/go-chi/cors"
+	"github.com/supertokens/supertokens-golang/recipe/emailverification"
+	"github.com/supertokens/supertokens-golang/recipe/emailverification/evmodels"
 	"github.com/supertokens/supertokens-golang/recipe/session"
 	"github.com/supertokens/supertokens-golang/recipe/thirdparty"
 	"github.com/supertokens/supertokens-golang/recipe/thirdparty/tpmodels"
@@ -25,6 +27,9 @@ func main() {
 			WebsiteDomain: "http://localhost:3000",
 		},
 		RecipeList: []supertokens.Recipe{
+			emailverification.Init(evmodels.TypeInput{
+				Mode: evmodels.ModeRequired,
+			}),
 			thirdpartyemailpassword.Init(&tpepmodels.TypeInput{
 				/*
 				   We use different credentials for different platforms when required. For example the redirect URI for Github

examples/with-fiber/main.go

@@ -7,6 +7,8 @@ import (
 	"github.com/gofiber/adaptor/v2"
 	"github.com/gofiber/fiber/v2"
 	"github.com/gofiber/fiber/v2/middleware/cors"
+	"github.com/supertokens/supertokens-golang/recipe/emailverification"
+	"github.com/supertokens/supertokens-golang/recipe/emailverification/evmodels"
 	"github.com/supertokens/supertokens-golang/recipe/session"
 	"github.com/supertokens/supertokens-golang/recipe/session/sessmodels"
 	"github.com/supertokens/supertokens-golang/recipe/thirdparty"
@@ -28,6 +30,9 @@ func main() {
 			WebsiteDomain: "http://localhost:3000",
 		},
 		RecipeList: []supertokens.Recipe{
+			emailverification.Init(evmodels.TypeInput{
+				Mode: evmodels.ModeRequired,
+			}),
 			thirdpartyemailpassword.Init(&tpepmodels.TypeInput{
 				/*
 				   We use different credentials for different platforms when required. For example the redirect URI for Github
@@ -113,7 +118,7 @@ func main() {
 	log.Fatal(app.Listen(":3001"))
 }
 
-//wrapper of the original implementation of verify session to match the required function signature
+// wrapper of the original implementation of verify session to match the required function signature
 func verifySession(options *sessmodels.VerifySessionOptions) fiber.Handler {
 	return func(c *fiber.Ctx) error {
 		return adaptor.HTTPHandlerFunc(http.HandlerFunc(session.VerifySession(options, func(rw http.ResponseWriter, r *http.Request) {
@@ -156,7 +161,7 @@ func sessioninfo(c *fiber.Ctx) error {
 	} else {
 		counter = int(counter.(float64) + 1)
 	}
-	err = sessionContainer.UpdateAccessTokenPayload(map[string]interface{}{
+	err = sessionContainer.MergeIntoAccessTokenPayload(map[string]interface{}{
 		"counter": counter.(int),
 	})
 	if err != nil {
@@ -170,7 +175,7 @@ func sessioninfo(c *fiber.Ctx) error {
 	})
 }
 
-//utility funtion to help convert an array of string to convert to comma separeted string format
+// utility funtion to help convert an array of string to convert to comma separeted string format
 func stringArrayToStringConvertor(stringArray []string) string {
 	var stringToBeReturned string
 	for _, val := range stringArray {

examples/with-gin/config/config.go

@@ -4,6 +4,8 @@ import (
 	"log"
 
 	"github.com/spf13/viper"
+	"github.com/supertokens/supertokens-golang/recipe/emailverification"
+	"github.com/supertokens/supertokens-golang/recipe/emailverification/evmodels"
 	"github.com/supertokens/supertokens-golang/recipe/session"
 	"github.com/supertokens/supertokens-golang/recipe/thirdparty"
 	"github.com/supertokens/supertokens-golang/recipe/thirdparty/tpmodels"
@@ -38,6 +40,9 @@ func Init() {
 			WebsiteDomain: "http://localhost" + config.GetString("server.websitePort"),
 		},
 		RecipeList: []supertokens.Recipe{
+			emailverification.Init(evmodels.TypeInput{
+				Mode: evmodels.ModeRequired,
+			}),
 			thirdpartyemailpassword.Init(&tpepmodels.TypeInput{
 				/*
 				   We use different credentials for different platforms when required. For example the redirect URI for Github

examples/with-go-zero/main.go

@@ -6,6 +6,8 @@ import (
 	"net/http"
 	"strings"
 
+	"github.com/supertokens/supertokens-golang/recipe/emailverification"
+	"github.com/supertokens/supertokens-golang/recipe/emailverification/evmodels"
 	"github.com/supertokens/supertokens-golang/recipe/session"
 	"github.com/supertokens/supertokens-golang/recipe/thirdparty"
 	"github.com/supertokens/supertokens-golang/recipe/thirdparty/tpmodels"
@@ -26,6 +28,9 @@ func main() {
 			WebsiteDomain: "http://localhost:3000",
 		},
 		RecipeList: []supertokens.Recipe{
+			emailverification.Init(evmodels.TypeInput{
+				Mode: evmodels.ModeRequired,
+			}),
 			thirdpartyemailpassword.Init(&tpepmodels.TypeInput{
 				/*
 				   We use different credentials for different platforms when required. For example the redirect URI for Github
@@ -95,7 +100,7 @@ func main() {
 	server := rest.MustNewServer(
 		rest.RestConf{
 			Host: "0.0.0.0",
-			Port: 8000,
+			Port: 3001,
 		},
 	)
 	defer server.Stop()
@@ -105,11 +110,20 @@ func main() {
 	addSupertokensRoutes("/auth", server) // go-zero doesn't execute middlewares if matching routes are not found
 	server.AddRoute(rest.Route{
 		Method: http.MethodGet,
-		Path:   "/sessionInfo",
+		Path:   "/sessioninfo",
 		Handler: func(rw http.ResponseWriter, r *http.Request) {
 			session.VerifySession(nil, sessioninfo).ServeHTTP(rw, r)
 		},
 	})
+
+	// go-zero does not honour middlewares for CORS requests unless we explicitly add a route for it.
+	server.AddRoute(rest.Route{
+		Method: http.MethodOptions,
+		Path:   "/sessioninfo",
+		Handler: func(rw http.ResponseWriter, r *http.Request) {
+			rw.WriteHeader(http.StatusOK)
+		},
+	})
 	server.Start()
 }
 
@@ -148,12 +162,11 @@ func sessioninfo(w http.ResponseWriter, r *http.Request) {
 
 func corsMiddleware(next http.HandlerFunc) http.HandlerFunc {
 	return func(response http.ResponseWriter, r *http.Request) {
-		response.Header().Set("Access-Control-Allow-Origin", "localhost:8000")
+		response.Header().Set("Access-Control-Allow-Origin", "http://localhost:3000")
 		response.Header().Set("Access-Control-Allow-Credentials", "true")
 		if r.Method == "OPTIONS" {
 			response.Header().Set("Access-Control-Allow-Headers", strings.Join(append([]string{"Content-Type"}, supertokens.GetAllCORSHeaders()...), ","))
-			response.Header().Set("Access-Control-Allow-Methods", "*")
-			response.Write([]byte(""))
+			response.Header().Set("Access-Control-Allow-Methods", "GET,POST,PUT,HEAD,OPTIONS")
 		} else {
 			next.ServeHTTP(response, r)
 		}

examples/with-http/main.go

@@ -5,6 +5,8 @@ import (
 	"net/http"
 	"strings"
 
+	"github.com/supertokens/supertokens-golang/recipe/emailverification"
+	"github.com/supertokens/supertokens-golang/recipe/emailverification/evmodels"
 	"github.com/supertokens/supertokens-golang/recipe/session"
 	"github.com/supertokens/supertokens-golang/recipe/thirdparty"
 	"github.com/supertokens/supertokens-golang/recipe/thirdparty/tpmodels"
@@ -24,6 +26,9 @@ func main() {
 			WebsiteDomain: "http://localhost:3000",
 		},
 		RecipeList: []supertokens.Recipe{
+			emailverification.Init(evmodels.TypeInput{
+				Mode: evmodels.ModeRequired,
+			}),
 			thirdpartyemailpassword.Init(&tpepmodels.TypeInput{
 				/*
 				   We use different credentials for different platforms when required. For example the redirect URI for Github

examples/with-labstack-echo/main.go

@@ -7,6 +7,8 @@ import (
 	"strings"
 
 	"github.com/labstack/echo/v4"
+	"github.com/supertokens/supertokens-golang/recipe/emailverification"
+	"github.com/supertokens/supertokens-golang/recipe/emailverification/evmodels"
 	"github.com/supertokens/supertokens-golang/recipe/session"
 	"github.com/supertokens/supertokens-golang/recipe/session/sessmodels"
 	"github.com/supertokens/supertokens-golang/recipe/thirdparty"
@@ -27,6 +29,9 @@ func main() {
 			WebsiteDomain: "http://localhost:3000",
 		},
 		RecipeList: []supertokens.Recipe{
+			emailverification.Init(evmodels.TypeInput{
+				Mode: evmodels.ModeRequired,
+			}),
 			thirdpartyemailpassword.Init(&tpepmodels.TypeInput{
 				/*
 				   We use different credentials for different platforms when required. For example the redirect URI for Github
@@ -144,7 +149,7 @@ func verifySession(options *sessmodels.VerifySessionOptions) echo.MiddlewareFunc
 }
 
 func sessioninfo(c echo.Context) error {
-	sessionContainer := c.Get("session").(*sessmodels.SessionContainer)
+	sessionContainer := c.Get("session").(sessmodels.SessionContainer)
 
 	if sessionContainer == nil {
 		return errors.New("no session found")