mulguard 1.1.7 → 1.1.8

package/src/lib/client.ts

@@ -0,0 +1,245 @@
+"use client"
+
+import * as React from "react"
+import type { ProviderId, ProviderType } from "@mulverse/mulguard-core/providers"
+import type { LoggerInstance, Session } from "@mulverse/mulguard-core/types"
+import { AuthError } from "@mulverse/mulguard-core/errors"
+
+/** @todo */
+class ClientFetchError extends AuthError {}
+
+/** @todo */
+export class ClientSessionError extends AuthError {}
+
+export interface AuthClientConfig {
+  baseUrl: string
+  basePath: string
+  baseUrlServer: string
+  basePathServer: string
+  /** Stores last session response */
+  _session?: Session | null | undefined
+  /** Used for timestamp since last sycned (in seconds) */
+  _lastSync: number
+  /**
+   * Stores the `SessionProvider`'s session update method to be able to
+   * trigger session updates from places like `signIn` or `signOut`
+   */
+  _getSession: (...args: any[]) => any
+}
+
+export interface UseSessionOptions<R extends boolean> {
+  required: R
+  /** Defaults to `signIn` */
+  onUnauthenticated?: () => void
+}
+
+export interface ClientSafeProvider {
+  id: ProviderId
+  name: string
+  type: ProviderType
+  signinUrl: string
+  callbackUrl: string
+  redirectTo: string
+}
+
+export interface SignInOptions<Redirect extends boolean = true>
+  extends Record<string, unknown> {
+  /** @deprecated Use `redirectTo` instead. */
+  callbackUrl?: string
+  /**
+   * Specify where the user should be redirected to after a successful signin.
+   *
+   * By default, it is the page the sign-in was initiated from.
+   */
+  redirectTo?: string
+  /**
+   * You might want to deal with the signin response on the same page, instead of redirecting to another page.
+   * For example, if an error occurs (like wrong credentials given by the user), you might want to show an inline error message on the input field.
+   *
+   * For this purpose, you can set this to option `redirect: false`.
+   */
+  redirect?: Redirect
+}
+
+export interface SignInResponse {
+  error: string | undefined
+  code: string | undefined
+  status: number
+  ok: boolean
+  url: string | null
+}
+
+/**
+ * Match `inputType` of `new URLSearchParams(inputType)`
+ * @internal
+ */
+export type SignInAuthorizationParams =
+  | string
+  | string[][]
+  | Record<string, string>
+  | URLSearchParams
+
+/** [Documentation](https://next-auth.js.org/getting-started/client#using-the-redirect-false-option-1) */
+export interface SignOutResponse {
+  url: string
+}
+
+export interface SignOutParams<Redirect extends boolean = true> {
+  /** @deprecated Use `redirectTo` instead. */
+  callbackUrl?: string
+  /**
+   * If you pass `redirect: false`, the page will not reload.
+   * The session will be deleted, and `useSession` is notified, so any indication about the user will be shown as logged out automatically.
+   * It can give a very nice experience for the user.
+   */
+  redirectTo?: string
+  /** [Documentation](https://next-auth.js.org/getting-started/client#using-the-redirect-false-option-1 */
+  redirect?: Redirect
+}
+
+/**
+ 
+ * If you have session expiry times of 30 days (the default) or more, then you probably don't need to change any of the default options.
+ *
+ * However, if you need to customize the session behavior and/or are using short session expiry times, you can pass options to the provider to customize the behavior of the {@link useSession} hook.
+ */
+export interface SessionProviderProps {
+  children: React.ReactNode
+  session?: Session | null
+  baseUrl?: string
+  basePath?: string
+  /**
+   * A time interval (in seconds) after which the session will be re-fetched.
+   * If set to `0` (default), the session is not polled.
+   */
+  refetchInterval?: number
+  /**
+   * `SessionProvider` automatically refetches the session when the user switches between windows.
+   * This option activates this behaviour if set to `true` (default).
+   */
+  refetchOnWindowFocus?: boolean
+  /**
+   * Set to `false` to stop polling when the device has no internet access offline (determined by `navigator.onLine`)
+   *
+   * [`navigator.onLine` documentation](https://developer.mozilla.org/en-US/docs/Web/API/NavigatorOnLine/onLine)
+   */
+  refetchWhenOffline?: false
+}
+
+// ------------------------ Internal ------------------------
+
+/**
+ * If passed 'appContext' via getInitialProps() in _app.js
+ * then get the req object from ctx and use that for the
+ * req value to allow `fetchData` to
+ * work seemlessly in getInitialProps() on server side
+ * pages *and* in _app.js.
+ * @internal
+ */
+export async function fetchData<T = any>(
+  path: string,
+  __NEXTAUTH: AuthClientConfig,
+  logger: LoggerInstance,
+  req: any = {}
+): Promise<T | null> {
+  const url = `${apiBaseUrl(__NEXTAUTH)}/${path}`
+  try {
+    const options: RequestInit = {
+      headers: {
+        "Content-Type": "application/json",
+        ...(req?.headers?.cookie ? { cookie: req.headers.cookie } : {}),
+      },
+    }
+
+    if (req?.body) {
+      options.body = JSON.stringify(req.body)
+      options.method = "POST"
+    }
+
+    const res = await fetch(url, options)
+    const data = await res.json()
+    if (!res.ok) throw data
+    return data
+  } catch (error) {
+    logger.error(new ClientFetchError((error as Error).message, error as any))
+    return null
+  }
+}
+
+/** @internal */
+export function apiBaseUrl(__NEXTAUTH: AuthClientConfig) {
+  if (typeof window === "undefined") {
+    // Return absolute path when called server side
+    return `${__NEXTAUTH.baseUrlServer}${__NEXTAUTH.basePathServer}`
+  }
+  // Return relative path when called client side
+  return __NEXTAUTH.basePath
+}
+
+/** @internal  */
+export function useOnline() {
+  const [isOnline, setIsOnline] = React.useState(
+    typeof navigator !== "undefined" ? navigator.onLine : false
+  )
+
+  const setOnline = () => setIsOnline(true)
+  const setOffline = () => setIsOnline(false)
+
+  React.useEffect(() => {
+    window.addEventListener("online", setOnline)
+    window.addEventListener("offline", setOffline)
+
+    return () => {
+      window.removeEventListener("online", setOnline)
+      window.removeEventListener("offline", setOffline)
+    }
+  }, [])
+
+  return isOnline
+}
+
+/**
+ * Returns the number of seconds elapsed since January 1, 1970 00:00:00 UTC.
+ * @internal
+ */
+export function now() {
+  return Math.floor(Date.now() / 1000)
+}
+
+/**
+ * Returns an `URL` like object to make requests/redirects from server-side
+ * @internal
+ */
+export function parseUrl(url?: string): {
+  /** @default "http://localhost:3000" */
+  origin: string
+  /** @default "localhost:3000" */
+  host: string
+  /** @default "/api/auth" */
+  path: string
+  /** @default "http://localhost:3000/api/auth" */
+  base: string
+  /** @default "http://localhost:3000/api/auth" */
+  toString: () => string
+} {
+  const defaultUrl = new URL("http://localhost:3000/api/auth")
+
+  if (url && !url.startsWith("http")) {
+    url = `https://${url}`
+  }
+
+  const _url = new URL(url || defaultUrl)
+  const path = (_url.pathname === "/" ? defaultUrl.pathname : _url.pathname)
+    // Remove trailing slash
+    .replace(/\/$/, "")
+
+  const base = `${_url.origin}${path}`
+
+  return {
+    origin: _url.origin,
+    host: _url.host,
+    path,
+    base,
+    toString: () => base,
+  }
+}

package/src/lib/env.ts

@@ -0,0 +1,36 @@
+// @ts-expect-error Next.js does not yet correctly use the `package.json#exports` field
+import { NextRequest } from "next/server"
+import type { MulGuardConfig } from "./index.js"
+import { setEnvDefaults as coreSetEnvDefaults } from "@mulverse/mulguard-core"
+
+/** If `MULGUARD_URL`, `AUTH_URL`, or `NEXTAUTH_URL` is defined, override the request's URL. */
+export function reqWithEnvURL(req: NextRequest): NextRequest {
+  const url = process.env.MULGUARD_URL ?? process.env.AUTH_URL ?? process.env.NEXTAUTH_URL
+  if (!url) return req
+  const { origin: envOrigin } = new URL(url)
+  const { href, origin } = req.nextUrl
+  return new NextRequest(href.replace(origin, envOrigin), req)
+}
+
+/**
+ * MulGuard checks for `MULGUARD_URL` and `MULGUARD_SECRET` first.
+ * For backwards compatibility, it also checks for `AUTH_URL`/`AUTH_SECRET` and `NEXTAUTH_URL`/`NEXTAUTH_SECRET`.
+ * The `basePath` by default is `/api/auth` instead of `/auth`
+ * (which is the default for all other Auth.js integrations).
+ */
+export function setEnvDefaults(config: MulGuardConfig) {
+  try {
+    config.secret ??= process.env.MULGUARD_SECRET ?? process.env.AUTH_SECRET ?? process.env.NEXTAUTH_SECRET
+    const url = process.env.MULGUARD_URL ?? process.env.AUTH_URL ?? process.env.NEXTAUTH_URL
+    if (!url) return
+    const { pathname } = new URL(url)
+    if (pathname === "/") return
+    config.basePath ||= pathname
+  } catch {
+    // Catching and swallowing potential URL parsing errors, we'll fall
+    // back to `/api/auth` below.
+  } finally {
+    config.basePath ||= "/api/auth"
+    coreSetEnvDefaults(process.env, config, true)
+  }
+}

package/src/lib/index.ts

@@ -0,0 +1,313 @@
+import { Auth, createActionURL, type AuthConfig } from "@mulverse/mulguard-core"
+// @ts-expect-error Next.js does not yet correctly use the `package.json#exports` field
+import { headers } from "next/headers"
+// @ts-expect-error Next.js does not yet correctly use the `package.json#exports` field
+import { NextResponse } from "next/server"
+import { reqWithEnvURL } from "./env.js"
+
+import type { AuthAction, Awaitable, Session } from "@mulverse/mulguard-core/types"
+import type {
+  GetServerSidePropsContext,
+  NextApiRequest,
+  NextApiResponse,
+} from "next"
+import type { AppRouteHandlerFn } from "./types.js"
+// @ts-expect-error Next.js does not yet correctly use the `package.json#exports` field
+import type { NextFetchEvent, NextMiddleware, NextRequest } from "next/server"
+
+/** Configure MulGuard. */
+export interface MulGuardConfig extends Omit<AuthConfig, "raw"> {
+  /**
+   * Callbacks are asynchronous functions you can use to control what happens when an auth-related action is performed.
+   * Callbacks **allow you to implement access controls without a database** or to **integrate with external databases or APIs**.
+   */
+  callbacks?: AuthConfig["callbacks"] & {
+    /**
+     * Invoked when a user needs authorization, using [Middleware](https://nextjs.org/docs/advanced-features/middleware).
+     *
+     * You can override this behavior by returning a {@link NextResponse}.
+     *
+     * @example
+     * ```ts title="app/auth.ts"
+     * async authorized({ request, auth }) {
+     *   const url = request.nextUrl
+     *
+     *   if(request.method === "POST") {
+     *     const { authToken } = (await request.json()) ?? {}
+     *     // If the request has a valid auth token, it is authorized
+     *     const valid = await validateAuthToken(authToken)
+     *     if(valid) return true
+     *     return NextResponse.json("Invalid auth token", { status: 401 })
+     *   }
+     *
+     *   // Logged in users are authenticated, otherwise redirect to login page
+     *   return !!auth.user
+     * }
+     * ```
+     *
+     * :::warning
+     * If you are returning a redirect response, make sure that the page you are redirecting to is not protected by this callback,
+     * otherwise you could end up in an infinite redirect loop.
+     * :::
+     */
+    authorized?: (params: {
+      /** The request to be authorized. */
+      request: NextRequest
+      /** The authenticated user or token, if any. */
+      auth: Session | null
+    }) => Awaitable<boolean | NextResponse | Response | undefined>
+  }
+}
+
+async function getSession(headers: Headers, config: MulGuardConfig) {
+  const url = createActionURL(
+    "session",
+    // @ts-expect-error `x-forwarded-proto` is not nullable, next.js sets it by default
+    headers.get("x-forwarded-proto"),
+    headers,
+    process.env,
+    config
+  )
+  const request = new Request(url, {
+    headers: { cookie: headers.get("cookie") ?? "" },
+  })
+
+  return Auth(request, {
+    ...config,
+    callbacks: {
+      ...config.callbacks,
+      // Since we are server-side, we don't need to filter out the session data
+      // See https://authjs.dev/getting-started/migrating-to-v5#authenticating-server-side
+      // TODO: Taint the session data to prevent accidental leakage to the client
+      // https://react.dev/reference/react/experimental_taintObjectReference
+      async session(...args) {
+        const session =
+          // If the user defined a custom session callback, use that instead
+          (await config.callbacks?.session?.(...args)) ?? {
+            ...args[0].session,
+            expires:
+              args[0].session.expires?.toISOString?.() ??
+              args[0].session.expires,
+          }
+        const user = args[0].user ?? args[0].token
+        return { user, ...session } satisfies Session
+      },
+    },
+  }) as Promise<Response>
+}
+
+export interface MulGuardRequest extends NextRequest {
+  auth: Session | null
+}
+
+export type MulGuardMiddleware = (
+  request: MulGuardRequest,
+  event: NextFetchEvent
+) => ReturnType<NextMiddleware>
+
+export type WithAuthArgs =
+  | [MulGuardRequest, any]
+  | [MulGuardMiddleware]
+  | [AppRouteHandlerFn]
+  | [NextApiRequest, NextApiResponse]
+  | [GetServerSidePropsContext]
+  | []
+
+function isReqWrapper(arg: any): arg is MulGuardMiddleware | AppRouteHandlerFn {
+  return typeof arg === "function"
+}
+
+export function initAuth(
+  config:
+    | MulGuardConfig
+    | ((request: NextRequest | undefined) => Awaitable<MulGuardConfig>),
+  onLazyLoad?: (config: MulGuardConfig) => void // To set the default env vars
+) {
+  if (typeof config === "function") {
+    return async (...args: WithAuthArgs) => {
+      if (!args.length) {
+        // React Server Components
+        const _headers = await headers()
+        const _config = await config(undefined) // Review: Should we pass headers() here instead?
+        onLazyLoad?.(_config)
+
+        return getSession(_headers, _config).then((r) => r.json())
+      }
+
+      if (args[0] instanceof Request) {
+        // middleware.ts inline
+        // export { auth as default } from "auth"
+        const req = args[0]
+        const ev = args[1]
+        const _config = await config(req)
+        onLazyLoad?.(_config)
+
+        // args[0] is supposed to be NextRequest but the instanceof check is failing.
+        return handleAuth([req, ev], _config)
+      }
+
+      if (isReqWrapper(args[0])) {
+        // middleware.ts wrapper/route.ts
+        // import { auth } from "auth"
+        // export default auth((req) => { console.log(req.auth) }})
+        const userMiddlewareOrRoute = args[0]
+        return async (
+          ...args: Parameters<MulGuardMiddleware | AppRouteHandlerFn>
+        ) => {
+          const _config = await config(args[0])
+          onLazyLoad?.(_config)
+          return handleAuth(args, _config, userMiddlewareOrRoute)
+        }
+      }
+      // API Routes, getServerSideProps
+      const request = "req" in args[0] ? args[0].req : args[0]
+      const response: any = "res" in args[0] ? args[0].res : args[1]
+      const _config = await config(request)
+      onLazyLoad?.(_config)
+
+      // @ts-expect-error -- request is NextRequest
+      return getSession(new Headers(request.headers), _config).then(
+        async (authResponse) => {
+          const auth = await authResponse.json()
+
+          for (const cookie of authResponse.headers.getSetCookie())
+            if ("headers" in response)
+              response.headers.append("set-cookie", cookie)
+            else response.appendHeader("set-cookie", cookie)
+
+          return auth satisfies Session | null
+        }
+      )
+    }
+  }
+  return (...args: WithAuthArgs) => {
+    if (!args.length) {
+      // React Server Components
+      return Promise.resolve(headers()).then((h: Headers) =>
+        getSession(h, config).then((r) => r.json())
+      )
+    }
+    if (args[0] instanceof Request) {
+      // middleware.ts inline
+      // export { auth as default } from "auth"
+      const req = args[0]
+      const ev = args[1]
+      return handleAuth([req, ev], config)
+    }
+
+    if (isReqWrapper(args[0])) {
+      // middleware.ts wrapper/route.ts
+      // import { auth } from "auth"
+      // export default auth((req) => { console.log(req.auth) }})
+      const userMiddlewareOrRoute = args[0]
+      return async (
+        ...args: Parameters<MulGuardMiddleware | AppRouteHandlerFn>
+      ) => {
+        return handleAuth(args, config, userMiddlewareOrRoute).then((res) => {
+          return res
+        })
+      }
+    }
+
+    // API Routes, getServerSideProps
+    const request = "req" in args[0] ? args[0].req : args[0]
+    const response: any = "res" in args[0] ? args[0].res : args[1]
+
+    return getSession(
+      // @ts-expect-error
+      new Headers(request.headers),
+      config
+    ).then(async (authResponse) => {
+      const auth = await authResponse.json()
+
+      for (const cookie of authResponse.headers.getSetCookie())
+        if ("headers" in response) response.headers.append("set-cookie", cookie)
+        else response.appendHeader("set-cookie", cookie)
+
+      return auth satisfies Session | null
+    })
+  }
+}
+
+async function handleAuth(
+  args: Parameters<NextMiddleware | AppRouteHandlerFn>,
+  config: MulGuardConfig,
+  userMiddlewareOrRoute?: MulGuardMiddleware | AppRouteHandlerFn
+) {
+  const request = reqWithEnvURL(args[0])
+  const sessionResponse = await getSession(request.headers, config)
+  const auth = await sessionResponse.json()
+
+  let authorized: boolean | NextResponse | Response | undefined = true
+
+  if (config.callbacks?.authorized) {
+    authorized = await config.callbacks.authorized({ request, auth })
+  }
+
+  let response: any = NextResponse.next?.()
+
+  if (authorized instanceof Response) {
+    // User returned a custom response, like redirecting to a page or 401, respect it
+    response = authorized
+
+    const redirect = authorized.headers.get("Location")
+    const { pathname } = request.nextUrl
+    // If the user is redirecting to the same MulGuard action path as the current request,
+    // don't allow the redirect to prevent an infinite loop
+    if (
+      redirect &&
+      isSameAuthAction(pathname, new URL(redirect).pathname, config)
+    ) {
+      authorized = true
+    }
+  } else if (userMiddlewareOrRoute) {
+    // Execute user's middleware/handler with the augmented request
+    const augmentedReq = request as MulGuardRequest
+    augmentedReq.auth = auth
+    response =
+      (await userMiddlewareOrRoute(augmentedReq, args[1])) ??
+      NextResponse.next()
+  } else if (!authorized) {
+    const signInPage = config.pages?.signIn ?? `${config.basePath}/signin`
+    if (request.nextUrl.pathname !== signInPage) {
+      // Redirect to signin page by default if not authorized
+      const signInUrl = request.nextUrl.clone()
+      signInUrl.pathname = signInPage
+      signInUrl.searchParams.set("callbackUrl", request.nextUrl.href)
+      response = NextResponse.redirect(signInUrl)
+    }
+  }
+
+  const finalResponse = new Response(response?.body, response)
+
+  // Preserve cookies from the session response
+  for (const cookie of sessionResponse.headers.getSetCookie())
+    finalResponse.headers.append("set-cookie", cookie)
+
+  return finalResponse
+}
+
+function isSameAuthAction(
+  requestPath: string,
+  redirectPath: string,
+  config: MulGuardConfig
+) {
+  const action = redirectPath.replace(`${requestPath}/`, "") as AuthAction
+  const pages = Object.values(config.pages ?? {})
+
+  return (
+    (actions.has(action) || pages.includes(redirectPath)) &&
+    redirectPath === requestPath
+  )
+}
+
+const actions = new Set<AuthAction>([
+  "providers",
+  "session",
+  "csrf",
+  "signin",
+  "signout",
+  "callback",
+  "verify-request",
+  "error",
+])

package/src/lib/types.ts

@@ -0,0 +1,30 @@
+// @ts-expect-error Next.js does not yet correctly use the `package.json#exports` field
+import type { NextRequest } from "next/server"
+
+/**
+ * AppRouteHandlerFnContext is the context that is passed to the handler as the
+ * second argument.
+ */
+export type AppRouteHandlerFnContext = {
+  params: Promise<any>
+}
+/**
+ * Handler function for app routes. If a non-Response value is returned, an error
+ * will be thrown.
+ */
+export type AppRouteHandlerFn = (
+  /**
+   * Incoming request object.
+   */
+  req: NextRequest,
+  /**
+   * Context properties on the request (including the parameters if this was a
+   * dynamic route).
+   */
+  ctx: AppRouteHandlerFnContext
+) => void | Response | Promise<void | Response>
+
+export type AppRouteHandlers = Record<
+  "GET" | "POST",
+  (req: NextRequest) => Promise<Response>
+>

package/src/middleware.ts

@@ -0,0 +1,16 @@
+/**
+ * :::warning Deprecated
+ * This module is replaced in v5. Read more at: https://authjs.dev/getting-started/migrating-to-v5#authenticating-server-side
+ * :::
+ *
+ * @module middleware
+ */
+
+throw new ReferenceError(
+  [
+    '"mulguard/middleware" is deprecated. If you are not ready to migrate, keep using "next-auth@4".',
+    "Read more on https://mulverse.com",
+  ].join("\n")
+)
+
+export {}

package/src/next.ts

@@ -0,0 +1,16 @@
+/**
+ * :::warning Deprecated
+ * This module is replaced in v5. Read more at: https://authjs.dev/getting-started/migrating-to-v5#authenticating-server-side
+ * :::
+ *
+ * @module next
+ */
+
+throw new ReferenceError(
+  [
+    '"mulguard/next" is deprecated. If you are not ready to migrate, keep using "next-auth@4".',
+    "Read more on https://mulverse.com",
+  ].join("\n")
+)
+
+export {}

package/src/providers/42-school.ts

@@ -0,0 +1,2 @@
+export * from "@mulverse/mulguard-core/providers/42-school"
+export { default } from "@mulverse/mulguard-core/providers/42-school"

package/src/providers/apple.ts

@@ -0,0 +1,2 @@
+export * from "@mulverse/mulguard-core/providers/apple"
+export { default } from "@mulverse/mulguard-core/providers/apple"

package/src/providers/asgardeo.ts

@@ -0,0 +1,2 @@
+export * from "@mulverse/mulguard-core/providers/asgardeo"
+export { default } from "@mulverse/mulguard-core/providers/asgardeo"

package/src/providers/atlassian.ts

@@ -0,0 +1,2 @@
+export * from "@mulverse/mulguard-core/providers/atlassian"
+export { default } from "@mulverse/mulguard-core/providers/atlassian"

package/src/providers/auth0.ts

@@ -0,0 +1,2 @@
+export * from "@mulverse/mulguard-core/providers/auth0"
+export { default } from "@mulverse/mulguard-core/providers/auth0"

package/src/providers/authentik.ts

@@ -0,0 +1,2 @@
+export * from "@mulverse/mulguard-core/providers/authentik"
+export { default } from "@mulverse/mulguard-core/providers/authentik"

package/src/providers/azure-ad-b2c.ts

@@ -0,0 +1,2 @@
+export * from "@mulverse/mulguard-core/providers/azure-ad-b2c"
+export { default } from "@mulverse/mulguard-core/providers/azure-ad-b2c"

package/src/providers/azure-ad.ts

@@ -0,0 +1,2 @@
+export * from "@mulverse/mulguard-core/providers/azure-ad"
+export { default } from "@mulverse/mulguard-core/providers/azure-ad"