feat(react): make session requireable in useSession (#2236)

A living session could be a requirement for specific pages (like dashboards). If it doesn’t exist, the user should be redirected to a page asking them to sign in again.

Sometimes, a user might log out by accident, or by deleting cookies on purpose. If that happens (e.g. on a separate tab), then `useSession({ required: true })` should detect the absence of a session cookie and always return a non-nullable Session object type.

When `required: true` is set, the default behavior will be to redirect the user to the sign-in page. This can be overridden by an `action()` callback:

```js
const session = useSession({
  required: true,
  action() {
    // ....
  }
})
if (session.status === "Loading") return "Loading or not authenticated..."

// session.data is always defined here.
```

Co-authored-by: Kristóf Poduszló <kripod@protonmail.com>
Co-authored-by: Lluis Agusti <hi@llu.lu>

BREAKING CHANGE:

The `useSession` hook now returns an object. Here is how to accommodate for this change:

```diff
- const [ session, loading ] = useSession()
+ const { data: session, status } = useSession()
+ const loading = status === "loading"
```

With the new `status` option, you can test states much more clearly.

README.md

@@ -67,15 +67,15 @@ NextAuth.js can be used with or without a database.
 
 ### Secure by default
 
-- Promotes the use of passwordless sign in mechanisms
-- Designed to be secure by default and encourage best practice for safeguarding user data
-- Uses Cross Site Request Forgery Tokens on POST routes (sign in, sign out)
+- Promotes the use of passwordless sign-in mechanisms
+- Designed to be secure by default and encourage best practices for safeguarding user data
+- Uses Cross-Site Request Forgery (CSRF) Tokens on POST routes (sign in, sign out)
 - Default cookie policy aims for the most restrictive policy appropriate for each cookie
 - When JSON Web Tokens are enabled, they are signed by default (JWS) with HS512
 - Use JWT encryption (JWE) by setting the option `encryption: true` (defaults to A256GCM)
 - Auto-generates symmetric signing and encryption keys for developer convenience
-- Features tab/window syncing and keepalive messages to support short lived sessions
-- Attempts to implement the latest guidance published by [Open Web Application Security Project](https://owasp.org/)
+- Features tab/window syncing and session polling to support short lived sessions
+- Attempts to implement the latest guidance published by [Open Web Application Security Project](https://owasp.org)
 
 Advanced options allow you to define your own routines to handle controlling what accounts are allowed to sign in, for encoding and decoding JSON Web Tokens and to set custom cookie security policies and session properties, so you can control who is able to sign in and how often sessions have to be re-validated.
 
@@ -90,6 +90,7 @@ The package at `@types/next-auth` is now deprecated.
 ### Add API Route
 
 ```javascript
+// pages/api/auth/[...nextauth].js
 import NextAuth from "next-auth"
 import Providers from "next-auth/providers"
 
@@ -113,13 +114,15 @@ export default NextAuth({
 })
 ```
 
-### Add React Component
+### Add React Hook
+
+The `useSession()` React Hook in the NextAuth.js client is the easiest way to check if someone is signed in.
 
 ```javascript
 import { useSession, signIn, signOut } from "next-auth/react"
 
 export default function Component() {
-  const [session, loading] = useSession()
+  const { data: session } = useSession()
   if (session) {
     return (
       <>
@@ -137,7 +140,26 @@ export default function Component() {
 }
 ```
 
-## Acknowledgements
+### Share/configure session state
+
+Use the `<SessionProvider>` to allows instances of `useSession()` to share the session object across components. It also takes care of keeping the session updated and synced between tabs/windows.
+
+```jsx title="pages/_app.js"
+import { SessionProvider } from "next-auth/react"
+
+export default function App({
+  Component, 
+  pageProps: { session, ...pageProps }
+}) {
+  return (
+    <SessionProvider session={session}>
+      <Component {...pageProps} />
+    </SessionProvider>
+  )
+}
+```
+
+## Acknowledgments
 
 [NextAuth.js is made possible thanks to all of its contributors.](https://next-auth.js.org/contributors)
 

app/components/header.js

@@ -6,7 +6,7 @@ import styles from "./header.module.css"
 // component that works on pages which support both client and server side
 // rendering, and avoids any flash incorrect content on initial page load.
 export default function Header() {
-  const [session, loading] = useSession()
+  const { data: session, status } = useSession()
 
   return (
     <header>
@@ -16,7 +16,7 @@ export default function Header() {
       <div className={styles.signedInStatus}>
         <p
           className={`nojs-show ${
-            !session && loading ? styles.loading : styles.loaded
+            !session && status === "loading" ? styles.loading : styles.loaded
           }`}
         >
           {!session && (

app/pages/_app.js

@@ -1,31 +1,12 @@
 import { SessionProvider } from "next-auth/react"
 import "./styles.css"
 
-// Use the <SessionProvider> to improve performance and allow components that call
-// `useSession()` anywhere in your application to access the `session` object.
 export default function App({
   Component,
   pageProps: { session, ...pageProps },
 }) {
   return (
-    <SessionProvider
-      // SessionProvider options are not required but can be useful in situations where
-      // you have a short session maxAge time. Shown here with default values.
-      // Client Max Age controls how often the useSession in the client should
-      // contact the server to sync the session state. Value in seconds.
-      // e.g.
-      // * 0  - Disabled (always use cache value)
-      // * 60 - Sync session state with server if it's older than 60 seconds
-      staleTime={0}
-      // Keep Alive tells windows / tabs that are signed in to keep sending
-      // a keep alive request (which extends the current session expiry) to
-      // prevent sessions in open windows from expiring. Value in seconds.
-      //
-      // Note: If a session has expired when keep alive is triggered, all open
-      // windows / tabs will be updated to reflect the user is signed out.
-      refetchInterval={0}
-      session={session}
-    >
+    <SessionProvider session={session}>
       <Component {...pageProps} />
     </SessionProvider>
   )

app/pages/credentials.js

@@ -21,7 +21,7 @@ export default function Page() {
     setResponse(response)
   }
 
-  const [session] = useSession()
+  const { data: session } = useSession()
 
   if (session) {
     return (

app/pages/email.js

@@ -29,7 +29,7 @@ export default function Page() {
     setResponse(response)
   }
 
-  const [session] = useSession()
+  const { data: session } = useSession()
 
   if (session) {
     return (

app/pages/protected.js

@@ -1,14 +1,16 @@
 import { useState, useEffect } from "react"
 import { useSession } from "next-auth/react"
 import Layout from "../components/layout"
-import AccessDenied from "../components/access-denied"
 
 export default function Page() {
-  const [session, loading] = useSession()
+  const { status } = useSession({
+    required: true,
+  })
   const [content, setContent] = useState()
 
   // Fetch content from protected route
   useEffect(() => {
+    if (status === "loading") return
     const fetchData = async () => {
       const res = await fetch("/api/examples/protected")
       const json = await res.json()
@@ -17,19 +19,9 @@ export default function Page() {
       }
     }
     fetchData()
-  }, [session])
+  }, [status])
 
-  // When rendering client side don't display anything until loading is complete
-  if (typeof window !== "undefined" && loading) return null
-
-  // If no session exists, display access denied message
-  if (!session) {
-    return (
-      <Layout>
-        <AccessDenied />
-      </Layout>
-    )
-  }
+  if (status === "loading") return <Layout>Loading...</Layout>
 
   // If session exists, display content
   return (

package.json

@@ -42,7 +42,8 @@
     "prepublishOnly": "npm run build",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
-    "version:pr": "node ./config/version-pr"
+    "version:pr": "node ./config/version-pr",
+    "website": "cd www && npm run start"
   },
   "files": [
     "dist",

src/client/__tests__/client-provider.test.js

@@ -16,6 +16,22 @@ afterAll(() => {
   server.close()
 })
 
+test("it won't allow to fetch the session in isolation without a session context", () => {
+  function App() {
+    useSession()
+    return null
+  }
+
+  jest.spyOn(console, "error")
+  console.error.mockImplementation(() => {})
+
+  expect(() => render(<App />)).toThrow(
+    "useSession must be wrapped in a SessionProvider"
+  )
+
+  console.error.mockRestore()
+})
+
 test("fetches the session once and re-uses it for different consumers", async () => {
   const sessionRouteCall = jest.fn()
 
@@ -66,21 +82,19 @@ test("when there's an existing session, it won't initialize as loading", async (
 
 function ProviderFlow({ options = {} }) {
   return (
-    <>
-      <SessionProvider {...options}>
-        <SessionConsumer />
-        <SessionConsumer testId="2" />
-      </SessionProvider>
-    </>
+    <SessionProvider {...options}>
+      <SessionConsumer />
+      <SessionConsumer testId="2" />
+    </SessionProvider>
   )
 }
 
 function SessionConsumer({ testId = 1 }) {
-  const [session, loading] = useSession()
+  const { data: session, status } = useSession()
 
   return (
     <div data-testid={`session-consumer-${testId}`}>
-      {loading ? "loading" : JSON.stringify(session)}
+      {status === "loading" ? "loading" : JSON.stringify(session)}
     </div>
   )
 }

src/client/react.js

@@ -43,8 +43,33 @@ const logger = proxyLogger(_logger, __NEXTAUTH.basePath)
 /** @type {import("types/internals/react").SessionContext} */
 const SessionContext = React.createContext()
 
-export function useSession() {
-  return React.useContext(SessionContext)
+export function useSession(options = {}) {
+  const value = React.useContext(SessionContext)
+
+  if (process.env.NODE_ENV !== "production" && !value) {
+    throw new Error("useSession must be wrapped in a SessionProvider")
+  }
+
+  const { required, onUnauthenticated } = options
+
+  const requiredAndNotLoading = required && value.status === "unauthenticated"
+
+  React.useEffect(() => {
+    if (requiredAndNotLoading) {
+      const url = `/api/auth/signin?${new URLSearchParams({
+        error: "SessionRequired",
+        callbackUrl: window.location.href,
+      })}`
+      if (onUnauthenticated) onUnauthenticated()
+      else window.location.replace(url)
+    }
+  }, [requiredAndNotLoading, onUnauthenticated])
+
+  if (requiredAndNotLoading) {
+    return { data: value.data, status: "loading" }
+  }
+
+  return value
 }
 
 export async function getSession(ctx) {
@@ -269,7 +294,17 @@ export function SessionProvider(props) {
     }
   }, [props.refetchInterval])
 
-  const value = React.useMemo(() => [session, loading], [session, loading])
+  const value = React.useMemo(
+    () => ({
+      data: session,
+      status: loading
+        ? "loading"
+        : session
+        ? "authenticated"
+        : "unauthenticated",
+    }),
+    [session, loading]
+  )
 
   return (
     <SessionContext.Provider value={value}>{children}</SessionContext.Provider>

src/server/index.js

@@ -210,6 +210,7 @@ async function NextAuthHandler(req, res, userOptions) {
               "OAuthAccountNotLinked",
               "EmailSignin",
               "CredentialsSignin",
+              "SessionRequired",
             ].includes(error)
           ) {
             return res.redirect(`${baseUrl}${basePath}/signin?error=${error}`)

src/server/pages/signin.js

@@ -32,6 +32,7 @@ export default function signin({
     EmailSignin: "Check your email inbox.",
     CredentialsSignin:
       "Sign in failed. Check the details you provided are correct.",
+    SessionRequired: "Please sign in to access this page.",
     default: "Unable to sign in.",
   }
 

types/internals/react.d.ts

@@ -26,4 +26,12 @@ export interface NextAuthConfig {
   _getSession: any
 }
 
-export type SessionContext = React.Context<Session>
+export type SessionContextValue<R extends boolean = false> = R extends true
+  ?
+      | { data: Session; status: "authenticated" }
+      | { data: null; status: "loading" }
+  :
+      | { data: Session; status: "authenticated" }
+      | { data: null; status: "unauthenticated" | "loading" }
+
+export type SessionContext = React.Context<SessionContextValue>

types/react-client.d.ts

@@ -2,6 +2,7 @@ import * as React from "react"
 import { IncomingMessage } from "http"
 import { Session } from "."
 import { ProviderType } from "./providers"
+import { SessionContextValue } from "internals/react"
 
 export interface CtxOrReq {
   req?: IncomingMessage
@@ -17,21 +18,22 @@ export type GetSessionOptions = CtxOrReq & {
   triggerEvent?: boolean
 }
 
+export interface UseSessionOptions<R extends boolean> {
+  required: R
+  /** Defaults to `signIn` */
+  action?(): void
+}
+
 /**
  * React Hook that gives you access
  * to the logged in user's session data.
  *
  * [Documentation](https://next-auth.js.org/getting-started/client#usesession)
  */
-export function useSession(): [Session | null, boolean]
+export function useSession<R extends boolean>(
+  options?: UseSessionOptions<R>
+): SessionContextValue<R>
 
-/**
- * Can be called client or server side to return a session asynchronously.
- * It calls `/api/auth/session` and returns a promise with a session object,
- * or null if no session exists.
- *
- * [Documentation](https://next-auth.js.org/getting-started/client#getsession)
- */
 export function getSession(options?: GetSessionOptions): Promise<Session | null>
 
 /*******************

types/tests/react.test.ts

@@ -11,9 +11,25 @@ const clientSession = {
   expires: "1234",
 }
 
-// $ExpectType [Session | null, boolean]
+/**
+ * $ExpectType
+ * | { data: Session; status: "authenticated"; }
+ * | { data: null; status: "unauthenticated" | "loading"; }
+ * | { //// data: Session; status: "authenticated"; }
+ * | { data: null; status: "loading"; }
+ */
 client.useSession()
 
+// $ExpectType { data: Session; status: "authenticated"; } | { data: null; status: "loading"; }
+const session = client.useSession({ required: true })
+if (session.status === "loading") {
+  // $ExpectType null
+  session.data
+} else {
+  // $ExpectType Session
+  session.data
+}
+
 // $ExpectType Promise<Session | null>
 client.getSession({ req: nextReq })