mulguard 1.1.7 → 1.1.9

package/src/index.ts

@@ -0,0 +1,430 @@
+/**
+ * MulGuard - Authentication for Next.js with Backend-First Architecture
+ *
+ * ## Installation
+ *
+ * ```bash npm2yarn
+ * npm install mulguard
+ * ```
+ *
+ * ## Environment variable inference
+ *
+ * `MULGUARD_URL` and `MULGUARD_SECRET` are automatically inferred.
+ *
+ * MulGuard can also automatically infer environment variables that are prefixed with `AUTH_`.
+ *
+ * For example `AUTH_GITHUB_ID` and `AUTH_GITHUB_SECRET` will be used as the `clientId` and `clientSecret` options for the GitHub provider.
+ *
+ * :::tip
+ * The environment variable name inferring has the following format for OAuth providers: `AUTH_{PROVIDER}_{ID|SECRET}`.
+ *
+ * `PROVIDER` is the uppercase snake case version of the provider's id, followed by either `ID` or `SECRET` respectively.
+ * :::
+ *
+ * `AUTH_SECRET` and `AUTH_URL` are also supported for backward compatibility.
+ *
+ * To add social login to your app, the configuration becomes:
+ *
+ * ```ts title="auth.ts"
+ * import MulGuard from "mulguard"
+ * import GitHub from "mulguard/providers/github"
+ * export const { handlers, auth } = MulGuard({ providers: [ GitHub ] })
+ * ```
+ *
+ * And the `.env.local` file:
+ *
+ * ```sh title=".env.local"
+ * AUTH_GITHUB_ID=...
+ * AUTH_GITHUB_SECRET=...
+ * AUTH_SECRET=...
+ * ```
+ *
+ * :::tip
+ * In production, `AUTH_SECRET` is a required environment variable - if not set, MulGuard will throw an error. See [MissingSecretError](https://authjs.dev/reference/core/errors#missingsecret) for more details.
+ * :::
+ *
+ * If you need to override the default values for a provider, you can still call it as a function `GitHub({...})` as before.
+ *
+ * ## Lazy initialization
+ * You can also initialize MulGuard lazily, which allows you to access the request context in the configuration in some cases, like Route Handlers, Middleware, API Routes or `getServerSideProps`.
+ * The above example becomes:
+ *
+ * ```ts title="auth.ts"
+ * import MulGuard from "mulguard"
+ * import GitHub from "mulguard/providers/github"
+ * export const { handlers, auth } = MulGuard(req => {
+ *  if (req) {
+ *   console.log(req) // do something with the request
+ *  }
+ *  return { providers: [ GitHub ] }
+ * })
+ * ```
+ *
+ * :::tip
+ * This is useful if you want to customize the configuration based on the request, for example, to add a different provider in staging/dev environments.
+ * :::
+ *
+ * @module mulguard
+ */
+
+import { Auth, customFetch } from "@mulverse/mulguard-core"
+import { reqWithEnvURL, setEnvDefaults } from "./lib/env.js"
+import { initAuth } from "./lib/index.js"
+import { signIn, signOut, update } from "./lib/actions.js"
+
+import type { Awaitable, Session } from "@mulverse/mulguard-core/types"
+import type { ProviderId } from "@mulverse/mulguard-core/providers"
+import type {
+  GetServerSidePropsContext,
+  NextApiRequest,
+  NextApiResponse,
+} from "next"
+import type {
+  AppRouteHandlerFn,
+  AppRouteHandlerFnContext,
+} from "./lib/types.js"
+// @ts-expect-error Next.js does not yet correctly use the `package.json#exports` field
+import type { NextRequest, NextMiddleware } from "next/server"
+import type {
+  MulGuardConfig,
+  MulGuardRequest,
+  MulGuardMiddleware,
+} from "./lib/index.js"
+// Type aliases for backward compatibility (exported and available in scope)
+type NextAuthConfig = MulGuardConfig
+type NextAuthRequest = MulGuardRequest
+type NextAuthMiddleware = MulGuardMiddleware
+
+export type { MulGuardConfig, MulGuardRequest, MulGuardMiddleware }
+export type { NextAuthConfig, NextAuthRequest, NextAuthMiddleware } // Backward compatibility
+export { AuthError, CredentialsSignin } from "@mulverse/mulguard-core/errors"
+
+export { customFetch }
+
+export type {
+  Session,
+  Account,
+  Profile,
+  DefaultSession,
+  User,
+} from "@mulverse/mulguard-core/types"
+export type { ServerActionsAdapter } from "@mulverse/mulguard-core/adapters"
+
+type AppRouteHandlers = Record<
+  "GET" | "POST",
+  (req: NextRequest) => Promise<Response>
+>
+
+/**
+ * The result of invoking {@link MulGuard|MulGuard}, initialized with the {@link MulGuardConfig}.
+ * It contains methods to set up and interact with MulGuard in your Next.js app.
+ */
+export interface MulGuardResult {
+  /**
+   * The MulGuard [Route Handler](https://beta.nextjs.org/docs/routing/route-handlers) methods. These are used to expose an endpoint for OAuth/Email providers,
+   * as well as REST API endpoints (such as `/api/auth/session`) that can be contacted from the client.
+   *
+   * After initializing MulGuard in `auth.ts`,
+   * re-export these methods.
+   *
+   * In `app/api/auth/[...mulguard]/route.ts`:
+   *
+   * ```ts title="app/api/auth/[...mulguard]/route.ts"
+   * export { GET, POST } from "../../../../auth"
+   * export const runtime = "edge" // optional
+   * ```
+   * Then `auth.ts`:
+   * ```ts title="auth.ts"
+   * // ...
+   * export const { handlers: { GET, POST }, auth } = MulGuard({...})
+   * ```
+   */
+  handlers: AppRouteHandlers
+  /**
+   * A universal method to interact with MulGuard in your Next.js app.
+   * After initializing MulGuard in `auth.ts`, use this method in Middleware, Server Components, Route Handlers (`app/`), and Edge or Node.js API Routes (`pages/`).
+   *
+   * ##### In Middleware
+   *
+   * :::info
+   * Adding `auth` to your Middleware is optional, but recommended to keep the user session alive.
+   * :::
+   *
+   * Authentication is done by the {@link MulGuardConfig.callbacks|callbacks.authorized} callback.
+   * @example
+   * ```ts title="middleware.ts"
+   * export { auth as middleware } from "./auth"
+   * ```
+   *
+   * Alternatively you can wrap your own middleware with `auth`, where `req` is extended with `auth`:
+   * @example
+   * ```ts title="middleware.ts"
+   * import { auth } from "./auth"
+   * export default auth((req) => {
+   *   // req.auth
+   * })
+   * ```
+   *
+   * ```ts
+   * // Optionally, don't invoke Middleware on some paths
+   * // Read more: https://nextjs.org/docs/app/building-your-application/routing/middleware#matcher
+   * export const config = {
+   *   matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"],
+   * }
+   * ```
+   *
+   * ##### In Server Components
+   *
+   * @example
+   * ```ts title="app/page.ts"
+   * import { auth } from "../auth"
+   *
+   * export default async function Page() {
+   *   const { user } = await auth()
+   *   return <p>Hello {user?.name}</p>
+   * }
+   * ```
+   *
+   * ##### In Route Handlers
+   * @example
+   * ```ts title="app/api/route.ts"
+   * import { auth } from "../../auth"
+   *
+   * export const POST = auth((req) => {
+   *   // req.auth
+   * })
+   * ```
+   *
+   * ##### In Edge API Routes
+   *
+   * @example
+   * ```ts title="pages/api/protected.ts"
+   * import { auth } from "../../auth"
+   *
+   * export default auth((req) => {
+   *   // req.auth
+   * })
+   *
+   * export const config = { runtime: "edge" }
+   * ```
+   *
+   * ##### In API Routes
+   *
+   * @example
+   * ```ts title="pages/api/protected.ts"
+   * import { auth } from "../auth"
+   * import type { NextApiRequest, NextApiResponse } from "next"
+   *
+   * export default async (req: NextApiRequest, res: NextApiResponse) => {
+   *   const session = await auth(req, res)
+   *   if (session) {
+   *     // Do something with the session
+   *     return res.json("This is protected content.")
+   *   }
+   *   res.status(401).json("You must be signed in.")
+   * }
+   * ```
+   *
+   * ##### In `getServerSideProps`
+   *
+   * @example
+   * ```ts title="pages/protected-ssr.ts"
+   * import { auth } from "../auth"
+   *
+   * export const getServerSideProps: GetServerSideProps = async (context) => {
+   *   const session = await auth(context)
+   *
+   *   if (session) {
+   *     // Do something with the session
+   *     return { props: { session, content: (await res.json()).content } }
+   *   }
+   *
+   *   return { props: {} }
+   * }
+   * ```
+   */
+  auth: ((
+    ...args: [NextApiRequest, NextApiResponse]
+  ) => Promise<Session | null>) &
+    ((...args: []) => Promise<Session | null>) &
+    ((...args: [GetServerSidePropsContext]) => Promise<Session | null>) &
+    ((
+      ...args: [
+        (
+          req: NextAuthRequest,
+          ctx: AppRouteHandlerFnContext
+        ) => ReturnType<AppRouteHandlerFn>,
+      ]
+    ) => AppRouteHandlerFn) &
+    ((...args: [NextAuthMiddleware]) => NextMiddleware)
+  /**
+   * Sign in with a provider. If no provider is specified, the user will be redirected to the sign in page.
+   *
+   * By default, the user is redirected to the current page after signing in. You can override this behavior by setting the `redirectTo` option with a relative path.
+   *
+   * @example
+   * ```ts title="app/layout.tsx"
+   * import { signIn } from "../auth"
+   *
+   * export default function Layout() {
+   *  return (
+   *   <form action={async () => {
+   *     "use server"
+   *     await signIn("github")
+   *   }}>
+   *    <button>Sign in with GitHub</button>
+   *   </form>
+   * )
+   * ```
+   *
+   * If an error occurs during signin, an instance of {@link AuthError} will be thrown. You can catch it like this:
+   * ```ts title="app/layout.tsx"
+   * import { AuthError } from "mulguard"
+   * import { signIn } from "../auth"
+   *
+   * export default function Layout() {
+   *  return (
+   *    <form action={async (formData) => {
+   *      "use server"
+   *      try {
+   *        await signIn("credentials", formData)
+   *     } catch(error) {
+   *       if (error instanceof AuthError) // Handle auth errors
+   *       throw error // Rethrow all other errors
+   *     }
+   *    }}>
+   *     <button>Sign in</button>
+   *   </form>
+   *  )
+   * }
+   * ```
+   *
+   */
+  signIn: <P extends ProviderId, R extends boolean = true>(
+    /** Provider to sign in to */
+    provider?: P, // See: https://github.com/microsoft/TypeScript/issues/29729
+    options?:
+      | FormData
+      | ({
+          /** The relative path to redirect to after signing in. By default, the user is redirected to the current page. */
+          redirectTo?: string
+          /** If set to `false`, the `signIn` method will return the URL to redirect to instead of redirecting automatically. */
+          redirect?: R
+        } & Record<string, any>),
+    authorizationParams?:
+      | string[][]
+      | Record<string, string>
+      | string
+      | URLSearchParams
+  ) => Promise<R extends false ? any : never>
+  /**
+   * Sign out the user. If the session was created using a database strategy, the session will be removed from the database and the related cookie is invalidated.
+   * If the session was created using a JWT, the cookie is invalidated.
+   *
+   * By default the user is redirected to the current page after signing out. You can override this behavior by setting the `redirectTo` option with a relative path.
+   *
+   * @example
+   * ```ts title="app/layout.tsx"
+   * import { signOut } from "../auth"
+   *
+   * export default function Layout() {
+   *  return (
+   *   <form action={async () => {
+   *     "use server"
+   *     await signOut()
+   *   }}>
+   *    <button>Sign out</button>
+   *   </form>
+   * )
+   * ```
+   *
+   *
+   */
+  signOut: <R extends boolean = true>(options?: {
+    /** The relative path to redirect to after signing out. By default, the user is redirected to the current page. */
+    redirectTo?: string
+    /** If set to `false`, the `signOut` method will return the URL to redirect to instead of redirecting automatically. */
+    redirect?: R
+  }) => Promise<R extends false ? any : never>
+  unstable_update: (
+    data: Partial<Session | { user: Partial<Session["user"]> }>
+  ) => Promise<Session | null>
+}
+
+/**
+ *  Initialize MulGuard.
+ *
+ *  @example
+ * ```ts title="auth.ts"
+ * import MulGuard from "mulguard"
+ * import GitHub from "@mulverse/mulguard-core/providers/github"
+ *
+ * export const { handlers, auth } = MulGuard({ providers: [GitHub] })
+ * ```
+ *
+ * Lazy initialization:
+ *
+ * @example
+ * ```ts title="auth.ts"
+ * import MulGuard from "mulguard"
+ * import GitHub from "@mulverse/mulguard-core/providers/github"
+ *
+ * export const { handlers, auth } = MulGuard(async (req) => {
+ *   console.log(req) // do something with the request
+ *   return {
+ *     providers: [GitHub],
+ *   },
+ * })
+ * ```
+ */
+export default function MulGuard(
+  config:
+    | MulGuardConfig
+    | ((request: NextRequest | undefined) => Awaitable<MulGuardConfig>)
+): MulGuardResult {
+  if (typeof config === "function") {
+    const httpHandler = async (req: NextRequest) => {
+      const _config = await config(req)
+      setEnvDefaults(_config)
+      return Auth(reqWithEnvURL(req), _config)
+    }
+
+    return {
+      handlers: { GET: httpHandler, POST: httpHandler } as const,
+      // @ts-expect-error
+      auth: initAuth(config, (c) => setEnvDefaults(c)),
+
+      signIn: async (provider, options, authorizationParams) => {
+        const _config = await config(undefined)
+        setEnvDefaults(_config)
+        return signIn(provider, options, authorizationParams, _config)
+      },
+      signOut: async (options) => {
+        const _config = await config(undefined)
+        setEnvDefaults(_config)
+        return signOut(options, _config)
+      },
+      unstable_update: async (data) => {
+        const _config = await config(undefined)
+        setEnvDefaults(_config)
+        return update(data, _config)
+      },
+    }
+  }
+  setEnvDefaults(config)
+  const httpHandler = (req: NextRequest) => Auth(reqWithEnvURL(req), config)
+  return {
+    handlers: { GET: httpHandler, POST: httpHandler } as const,
+    // @ts-expect-error
+    auth: initAuth(config),
+    signIn: (provider, options, authorizationParams) => {
+      return signIn(provider, options, authorizationParams, config)
+    },
+    signOut: (options) => {
+      return signOut(options, config)
+    },
+    unstable_update: (data) => {
+      return update(data, config)
+    },
+  }
+}

package/src/jwt.ts

@@ -0,0 +1,9 @@
+/**
+ * :::warning Not recommended
+ * In NextAuth.js v5 or newer, we recommend other authentication methods server-side. Read more at: https://authjs.dev/getting-started/migrating-to-v5#authenticating-server-side
+ * :::
+ *
+ * @module jwt
+ */
+
+export * from "@mulverse/mulguard-core/jwt"

package/src/lib/actions.ts

@@ -0,0 +1,144 @@
+import { Auth, raw, skipCSRFCheck, createActionURL } from "@mulverse/mulguard-core"
+// @ts-expect-error Next.js does not yet correctly use the `package.json#exports` field
+import { headers as nextHeaders, cookies } from "next/headers"
+// @ts-expect-error Next.js does not yet correctly use the `package.json#exports` field
+import { redirect } from "next/navigation"
+
+import type { MulGuardConfig } from "./index.js"
+import type { MulGuardResult, Session } from "../index.js"
+import type { ProviderType } from "@mulverse/mulguard-core/providers"
+
+type SignInParams = Parameters<MulGuardResult["signIn"]>
+export async function signIn(
+  provider: SignInParams[0],
+  options: SignInParams[1] = {},
+  authorizationParams: SignInParams[2],
+  config: MulGuardConfig
+) {
+  const headers = new Headers(await nextHeaders())
+  const {
+    redirect: shouldRedirect = true,
+    redirectTo,
+    ...rest
+  } = options instanceof FormData ? Object.fromEntries(options) : options
+
+  const callbackUrl = redirectTo?.toString() ?? headers.get("Referer") ?? "/"
+  const signInURL = createActionURL(
+    "signin",
+    // @ts-expect-error `x-forwarded-proto` is not nullable, next.js sets it by default
+    headers.get("x-forwarded-proto"),
+    headers,
+    process.env,
+    config
+  )
+
+  if (!provider) {
+    signInURL.searchParams.append("callbackUrl", callbackUrl)
+    if (shouldRedirect) redirect(signInURL.toString())
+    return signInURL.toString()
+  }
+
+  let url = `${signInURL}/${provider}?${new URLSearchParams(
+    authorizationParams
+  )}`
+  let foundProvider: { id?: SignInParams[0]; type?: ProviderType } = {}
+
+  for (const providerConfig of config.providers) {
+    const { options, ...defaults } =
+      typeof providerConfig === "function" ? providerConfig() : providerConfig
+    const id = (options?.id as string | undefined) ?? defaults.id
+    if (id === provider) {
+      foundProvider = {
+        id,
+        type: (options?.type as ProviderType | undefined) ?? defaults.type,
+      }
+      break
+    }
+  }
+
+  if (!foundProvider.id) {
+    const url = `${signInURL}?${new URLSearchParams({ callbackUrl })}`
+    if (shouldRedirect) redirect(url)
+    return url
+  }
+
+  if (foundProvider.type === "credentials") {
+    url = url.replace("signin", "callback")
+  }
+
+  headers.set("Content-Type", "application/x-www-form-urlencoded")
+  const body = new URLSearchParams({ ...rest, callbackUrl })
+  const req = new Request(url, { method: "POST", headers, body })
+  const res = await Auth(req, { ...config, raw, skipCSRFCheck })
+
+  const cookieJar = await cookies()
+  for (const c of res?.cookies ?? []) cookieJar.set(c.name, c.value, c.options)
+
+  const responseUrl =
+    res instanceof Response ? res.headers.get("Location") : res.redirect
+
+  // NOTE: if for some unexpected reason the responseUrl is not set,
+  // we redirect to the original url
+  const redirectUrl = responseUrl ?? url
+
+  if (shouldRedirect) return redirect(redirectUrl)
+
+  return redirectUrl as any
+}
+
+type SignOutParams = Parameters<MulGuardResult["signOut"]>
+export async function signOut(
+  options: SignOutParams[0],
+  config: MulGuardConfig
+) {
+  const headers = new Headers(await nextHeaders())
+  headers.set("Content-Type", "application/x-www-form-urlencoded")
+
+  const url = createActionURL(
+    "signout",
+    // @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 callbackUrl = options?.redirectTo ?? headers.get("Referer") ?? "/"
+  const body = new URLSearchParams({ callbackUrl })
+  const req = new Request(url, { method: "POST", headers, body })
+
+  const res = await Auth(req, { ...config, raw, skipCSRFCheck })
+
+  const cookieJar = await cookies()
+  for (const c of res?.cookies ?? []) cookieJar.set(c.name, c.value, c.options)
+
+  if (options?.redirect ?? true) return redirect(res.redirect!)
+
+  return res as any
+}
+
+type UpdateParams = Parameters<MulGuardResult["unstable_update"]>
+export async function update(
+  data: UpdateParams[0],
+  config: MulGuardConfig
+): Promise<Session | null> {
+  const headers = new Headers(await nextHeaders())
+  headers.set("Content-Type", "application/json")
+
+  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 body = JSON.stringify({ data })
+  const req = new Request(url, { method: "POST", headers, body })
+
+  const res: any = await Auth(req, { ...config, raw, skipCSRFCheck })
+
+  const cookieJar = await cookies()
+  for (const c of res?.cookies ?? []) cookieJar.set(c.name, c.value, c.options)
+
+  return res.body
+}