@mulverse/mulguard-core 1.0.0

package/src/lib/actions/session.ts

@@ -0,0 +1,167 @@
+import { JWTSessionError, SessionTokenError } from "../../errors.js"
+import { fromDate } from "../utils/date.js"
+
+import type { Adapter } from "../../adapters.js"
+import type { InternalOptions, ResponseInternal, Session } from "../../types.js"
+import type { Cookie, SessionStore } from "../utils/cookie.js"
+
+/** Return a session object filtered via `callbacks.session` */
+export async function session(
+  options: InternalOptions,
+  sessionStore: SessionStore,
+  cookies: Cookie[],
+  isUpdate?: boolean,
+  newSession?: any
+): Promise<ResponseInternal<Session | null>> {
+  const {
+    adapter,
+    jwt,
+    events,
+    callbacks,
+    logger,
+    session: { strategy: sessionStrategy, maxAge: sessionMaxAge },
+  } = options
+
+  const response: ResponseInternal<Session | null> = {
+    body: null,
+    headers: {
+      "Content-Type": "application/json",
+      ...(!isUpdate && {
+        "Cache-Control": "private, no-cache, no-store",
+        Expires: "0",
+        Pragma: "no-cache",
+      }),
+    },
+    cookies,
+  }
+
+  const sessionToken = sessionStore.value
+
+  if (!sessionToken) return response
+
+  if (sessionStrategy === "jwt") {
+    try {
+      const salt = options.cookies.sessionToken.name
+      const payload = await jwt.decode({ ...jwt, token: sessionToken, salt })
+
+      if (!payload) throw new Error("Invalid JWT")
+
+      // @ts-expect-error
+      const token = await callbacks.jwt({
+        token: payload,
+        ...(isUpdate && { trigger: "update" }),
+        session: newSession,
+      })
+
+      const newExpires = fromDate(sessionMaxAge)
+
+      if (token !== null) {
+        // By default, only exposes a limited subset of information to the client
+        // as needed for presentation purposes (e.g. "you are logged in as...").
+        const session = {
+          user: { name: token.name, email: token.email, image: token.picture },
+          expires: newExpires.toISOString(),
+        }
+        // @ts-expect-error
+        const newSession = await callbacks.session({ session, token })
+
+        // Return session payload as response
+        response.body = newSession
+
+        // Refresh JWT expiry by re-signing it, with an updated expiry date
+        const newToken = await jwt.encode({ ...jwt, token, salt })
+
+        // Set cookie, to also update expiry date on cookie
+        const sessionCookies = sessionStore.chunk(newToken, {
+          expires: newExpires,
+        })
+
+        response.cookies?.push(...sessionCookies)
+
+        await events.session?.({ session: newSession, token })
+      } else {
+        response.cookies?.push(...sessionStore.clean())
+      }
+    } catch (e) {
+      logger.error(new JWTSessionError(e as Error))
+      // If the JWT is not verifiable remove the broken session cookie(s).
+      response.cookies?.push(...sessionStore.clean())
+    }
+
+    return response
+  }
+
+  // Retrieve session from database
+  try {
+    const { getSessionAndUser, deleteSession, updateSession } =
+      adapter as Required<Adapter>
+    let userAndSession = await getSessionAndUser(sessionToken)
+
+    // If session has expired, clean up the database
+    if (
+      userAndSession &&
+      userAndSession.session.expires.valueOf() < Date.now()
+    ) {
+      await deleteSession(sessionToken)
+      userAndSession = null
+    }
+
+    if (userAndSession) {
+      const { user, session } = userAndSession
+
+      const sessionUpdateAge = options.session.updateAge
+      // Calculate last updated date to throttle write updates to database
+      // Formula: ({expiry date} - sessionMaxAge) + sessionUpdateAge
+      //     e.g. ({expiry date} - 30 days) + 1 hour
+      const sessionIsDueToBeUpdatedDate =
+        session.expires.valueOf() -
+        sessionMaxAge * 1000 +
+        sessionUpdateAge * 1000
+
+      const newExpires = fromDate(sessionMaxAge)
+      // Trigger update of session expiry date and write to database, only
+      // if the session was last updated more than {sessionUpdateAge} ago
+      if (sessionIsDueToBeUpdatedDate <= Date.now()) {
+        await updateSession({
+          sessionToken: sessionToken,
+          expires: newExpires,
+        })
+      }
+
+      // Pass Session through to the session callback
+      const sessionPayload = await callbacks.session({
+        // TODO: user already passed below,
+        // remove from session object in https://github.com/nextauthjs/next-auth/pull/9702
+        // @ts-expect-error
+        session: { ...session, user },
+        user,
+        newSession,
+        ...(isUpdate ? { trigger: "update" } : {}),
+      })
+
+      // Return session payload as response
+      response.body = sessionPayload
+
+      // Set cookie again to update expiry
+      response.cookies?.push({
+        name: options.cookies.sessionToken.name,
+        value: sessionToken,
+        options: {
+          ...options.cookies.sessionToken.options,
+          expires: newExpires,
+        },
+      })
+
+      // @ts-expect-error
+      await events.session?.({ session: sessionPayload })
+    } else if (sessionToken) {
+      // If `sessionToken` was found set but it's not valid for a session then
+      // remove the sessionToken cookie from browser.
+      response.cookies?.push(...sessionStore.clean())
+    }
+  } catch (e) {
+    logger.error(new SessionTokenError(e as Error))
+  }
+
+  return response
+}

package/src/lib/actions/signin/authorization-url.ts

@@ -0,0 +1,123 @@
+import * as checks from "../callback/oauth/checks.js"
+import * as o from "oauth4webapi"
+
+import type { InternalOptions, RequestInternal } from "../../../types.js"
+import type { Cookie } from "../../utils/cookie.js"
+import { customFetch } from "../../symbols.js"
+
+/**
+ * Generates an authorization/request token URL.
+ *
+ * [OAuth 2](https://www.oauth.com/oauth2-servers/authorization/the-authorization-request/)
+ */
+export async function getAuthorizationUrl(
+  query: RequestInternal["query"],
+  options: InternalOptions<"oauth" | "oidc">
+) {
+  const { logger, provider } = options
+
+  let url = provider.authorization?.url
+  let as: o.AuthorizationServer | undefined
+
+  // Falls back to authjs.dev if the user only passed params
+  if (!url || url.host === "authjs.dev") {
+    // If url is undefined, we assume that issuer is always defined
+    // We check this in assert.ts
+
+    const issuer = new URL(provider.issuer!)
+    const discoveryResponse = await o.discoveryRequest(issuer, {
+      [o.customFetch]: provider[customFetch],
+      // TODO: move away from allowing insecure HTTP requests
+      [o.allowInsecureRequests]: true,
+    })
+    const as = await o
+      .processDiscoveryResponse(issuer, discoveryResponse)
+      .catch((error) => {
+        if (!(error instanceof TypeError) || error.message !== "Invalid URL")
+          throw error
+        throw new TypeError(
+          `Discovery request responded with an invalid issuer. expected: ${issuer}`
+        )
+      })
+
+    if (!as.authorization_endpoint) {
+      throw new TypeError(
+        "Authorization server did not provide an authorization endpoint."
+      )
+    }
+
+    url = new URL(as.authorization_endpoint)
+  }
+
+  const authParams = url.searchParams
+
+  let redirect_uri: string = provider.callbackUrl
+  let data: string | undefined
+  if (!options.isOnRedirectProxy && provider.redirectProxyUrl) {
+    redirect_uri = provider.redirectProxyUrl
+    data = provider.callbackUrl
+    logger.debug("using redirect proxy", { redirect_uri, data })
+  }
+
+  const params = Object.assign(
+    {
+      response_type: "code",
+      // clientId can technically be undefined, should we check this in assert.ts or rely on the Authorization Server to do it?
+      client_id: provider.clientId,
+      redirect_uri,
+      // @ts-expect-error TODO:
+      ...provider.authorization?.params,
+    },
+    Object.fromEntries(provider.authorization?.url.searchParams ?? []),
+    query
+  )
+
+  for (const k in params) authParams.set(k, params[k])
+
+  const cookies: Cookie[] = []
+
+  if (
+    // Otherwise "POST /redirect_uri" wouldn't include the cookies
+    provider.authorization?.url.searchParams.get("response_mode") ===
+    "form_post"
+  ) {
+    options.cookies.state.options.sameSite = "none"
+    options.cookies.state.options.secure = true
+    options.cookies.nonce.options.sameSite = "none"
+    options.cookies.nonce.options.secure = true
+  }
+
+  const state = await checks.state.create(options, data)
+  if (state) {
+    authParams.set("state", state.value)
+    cookies.push(state.cookie)
+  }
+
+  if (provider.checks?.includes("pkce")) {
+    if (as && !as.code_challenge_methods_supported?.includes("S256")) {
+      // We assume S256 PKCE support, if the server does not advertise that,
+      // a random `nonce` must be used for CSRF protection.
+      if (provider.type === "oidc") provider.checks = ["nonce"]
+    } else {
+      const { value, cookie } = await checks.pkce.create(options)
+      authParams.set("code_challenge", value)
+      authParams.set("code_challenge_method", "S256")
+      cookies.push(cookie)
+    }
+  }
+
+  const nonce = await checks.nonce.create(options)
+  if (nonce) {
+    authParams.set("nonce", nonce.value)
+    cookies.push(nonce.cookie)
+  }
+
+  // TODO: This does not work in normalizeOAuth because authorization endpoint can come from discovery
+  // Need to make normalizeOAuth async
+  if (provider.type === "oidc" && !url.searchParams.has("scope")) {
+    url.searchParams.set("scope", "openid profile email")
+  }
+
+  logger.debug("authorization url is ready", { url, cookies, provider })
+  return { redirect: url.toString(), cookies }
+}

package/src/lib/actions/signin/index.ts

@@ -0,0 +1,37 @@
+import { getAuthorizationUrl } from "./authorization-url.js"
+import { sendToken } from "./send-token.js"
+
+import type { Cookie } from "../../utils/cookie.js"
+import type {
+  InternalOptions,
+  RequestInternal,
+  ResponseInternal,
+} from "../../../types.js"
+
+export async function signIn(
+  request: RequestInternal,
+  cookies: Cookie[],
+  options: InternalOptions
+): Promise<ResponseInternal> {
+  const signInUrl = `${options.url.origin}${options.basePath}/signin`
+
+  if (!options.provider) return { redirect: signInUrl, cookies }
+
+  switch (options.provider.type) {
+    case "oauth":
+    case "oidc": {
+      const { redirect, cookies: authCookies } = await getAuthorizationUrl(
+        request.query,
+        options
+      )
+      if (authCookies) cookies.push(...authCookies)
+      return { redirect, cookies }
+    }
+    case "email": {
+      const response = await sendToken(request, options)
+      return { ...response, cookies }
+    }
+    default:
+      return { redirect: signInUrl, cookies }
+  }
+}

package/src/lib/actions/signin/send-token.ts

@@ -0,0 +1,124 @@
+import { createHash, randomString, toRequest } from "../../utils/web.js"
+import { AccessDenied } from "../../../errors.js"
+
+import type { InternalOptions, RequestInternal } from "../../../types.js"
+import type { Account } from "../../../types.js"
+
+/**
+ * Starts an e-mail login flow, by generating a token,
+ * and sending it to the user's e-mail (with the help of a DB adapter).
+ * At the end, it returns a redirect to the `verify-request` page.
+ */
+export async function sendToken(
+  request: RequestInternal,
+  options: InternalOptions<"email">
+) {
+  const { body } = request
+  const { provider, callbacks, adapter } = options
+  const normalizer = provider.normalizeIdentifier ?? defaultNormalizer
+  const email = normalizer(body?.email)
+
+  const defaultUser = { id: crypto.randomUUID(), email, emailVerified: null }
+  const user = (await adapter!.getUserByEmail(email)) ?? defaultUser
+
+  const account = {
+    providerAccountId: email,
+    userId: user.id,
+    type: "email",
+    provider: provider.id,
+  } satisfies Account
+
+  let authorized
+  try {
+    authorized = await callbacks.signIn({
+      user,
+      account,
+      email: { verificationRequest: true },
+    })
+  } catch (e) {
+    throw new AccessDenied(e as Error)
+  }
+  if (!authorized) throw new AccessDenied("AccessDenied")
+  if (typeof authorized === "string") {
+    return {
+      redirect: await callbacks.redirect({
+        url: authorized,
+        baseUrl: options.url.origin,
+      }),
+    }
+  }
+
+  const { callbackUrl, theme } = options
+  const token =
+    (await provider.generateVerificationToken?.()) ?? randomString(32)
+
+  const ONE_DAY_IN_SECONDS = 86400
+  const expires = new Date(
+    Date.now() + (provider.maxAge ?? ONE_DAY_IN_SECONDS) * 1000
+  )
+
+  const secret = provider.secret ?? options.secret
+
+  const baseUrl = new URL(options.basePath, options.url.origin)
+
+  const sendRequest = provider.sendVerificationRequest({
+    identifier: email,
+    token,
+    expires,
+    url: `${baseUrl}/callback/${provider.id}?${new URLSearchParams({
+      callbackUrl,
+      token,
+      email,
+    })}`,
+    provider,
+    theme,
+    request: toRequest(request),
+  })
+
+  const createToken = adapter!.createVerificationToken?.({
+    identifier: email,
+    token: await createHash(`${token}${secret}`),
+    expires,
+  })
+
+  await Promise.all([sendRequest, createToken])
+
+  return {
+    redirect: `${baseUrl}/verify-request?${new URLSearchParams({
+      provider: provider.id,
+      type: provider.type,
+    })}`,
+  }
+}
+
+function defaultNormalizer(email?: string) {
+  if (!email) throw new Error("Missing email from request body.")
+
+  const trimmedEmail = email.toLowerCase().trim()
+
+  // Reject email addresses with quotes to prevent address parser confusion
+  // This prevents attacks like "attacker@evil.com"@victim.com
+  if (trimmedEmail.includes('"')) {
+    throw new Error("Invalid email address format.")
+  }
+
+  // Get the first two elements only,
+  // separated by `@` from user input.
+  let [local, domain] = trimmedEmail.split("@")
+
+  // Validate that we have exactly 2 parts (local and domain)
+  if (!local || !domain || trimmedEmail.split("@").length !== 2) {
+    throw new Error("Invalid email address format.")
+  }
+
+  // The part before "@" can contain a ","
+  // but we remove it on the domain part
+  domain = domain.split(",")[0]
+
+  // Additional validation: domain should not be empty after comma split
+  if (!domain) {
+    throw new Error("Invalid email address format.")
+  }
+
+  return `${local}@${domain}`
+}

package/src/lib/actions/signout.ts

@@ -0,0 +1,38 @@
+import { SignOutError } from "../../errors.js"
+
+import type { InternalOptions, ResponseInternal } from "../../types.js"
+import type { Cookie, SessionStore } from "../utils/cookie.js"
+
+/**
+ * Destroys the session.
+ * If the session strategy is database,
+ * The session is also deleted from the database.
+ * In any case, the session cookie is cleared and
+ * {@link AuthConfig["events"].signOut} is emitted.
+ */
+export async function signOut(
+  cookies: Cookie[],
+  sessionStore: SessionStore,
+  options: InternalOptions
+): Promise<ResponseInternal> {
+  const { jwt, events, callbackUrl: redirect, logger, session } = options
+  const sessionToken = sessionStore.value
+  if (!sessionToken) return { redirect, cookies }
+
+  try {
+    if (session.strategy === "jwt") {
+      const salt = options.cookies.sessionToken.name
+      const token = await jwt.decode({ ...jwt, token: sessionToken, salt })
+      await events.signOut?.({ token })
+    } else {
+      const session = await options.adapter?.deleteSession(sessionToken)
+      await events.signOut?.({ session })
+    }
+  } catch (e) {
+    logger.error(new SignOutError(e as Error))
+  }
+
+  cookies.push(...sessionStore.clean())
+
+  return { redirect, cookies }
+}

package/src/lib/actions/webauthn-options.ts

@@ -0,0 +1,100 @@
+import type {
+  InternalOptions,
+  RequestInternal,
+  ResponseInternal,
+  User,
+} from "../../types.js"
+import type { Cookie, SessionStore } from "../utils/cookie.js"
+import { getLoggedInUser } from "../utils/session.js"
+import {
+  assertInternalOptionsWebAuthn,
+  inferWebAuthnOptions,
+  getAuthenticationResponse,
+  getRegistrationResponse,
+} from "../utils/webauthn-utils.js"
+
+/**
+ * Returns authentication or registration options for a WebAuthn flow
+ * depending on the parameters provided.
+ */
+export async function webAuthnOptions(
+  request: RequestInternal,
+  options: InternalOptions,
+  sessionStore: SessionStore,
+  cookies: Cookie[]
+  // @ts-expect-error issue with returning from a switch case
+): Promise<ResponseInternal> {
+  // Return an error if the adapter is missing or if the provider
+  // is not a webauthn provider.
+  const narrowOptions = assertInternalOptionsWebAuthn(options)
+  const { provider } = narrowOptions
+
+  // Extract the action from the query parameters
+  const { action } = (request.query ?? {}) as Record<string, unknown>
+
+  // Action must be either "register", "authenticate", or undefined
+  if (
+    action !== "register" &&
+    action !== "authenticate" &&
+    typeof action !== "undefined"
+  ) {
+    return {
+      status: 400,
+      body: { error: "Invalid action" },
+      cookies,
+      headers: {
+        "Content-Type": "application/json",
+      },
+    }
+  }
+
+  // Get the user info from the session
+  const sessionUser = await getLoggedInUser(options, sessionStore)
+
+  // Extract user info from request
+  // If session user exists, we don't need to call getUserInfo
+  const getUserInfoResponse = sessionUser
+    ? {
+        user: sessionUser,
+        exists: true,
+      }
+    : await provider.getUserInfo(options, request)
+
+  const userInfo = getUserInfoResponse?.user
+
+  // Make a decision on what kind of webauthn options to return
+  const decision = inferWebAuthnOptions(
+    action,
+    !!sessionUser,
+    getUserInfoResponse
+  )
+
+  switch (decision) {
+    case "authenticate":
+      return getAuthenticationResponse(
+        narrowOptions,
+        request,
+        userInfo,
+        cookies
+      )
+    case "register":
+      if (typeof userInfo?.email === "string") {
+        return getRegistrationResponse(
+          narrowOptions,
+          request,
+          userInfo as User & { email: string },
+          cookies
+        )
+      }
+      break
+    default:
+      return {
+        status: 400,
+        body: { error: "Invalid request" },
+        cookies,
+        headers: {
+          "Content-Type": "application/json",
+        },
+      }
+  }
+}

package/src/lib/index.ts

@@ -0,0 +1,97 @@
+import { UnknownAction } from "../errors.js"
+import { SessionStore } from "./utils/cookie.js"
+import { init } from "./init.js"
+import renderPage from "./pages/index.js"
+import * as actions from "./actions/index.js"
+import { validateCSRF } from "./actions/callback/oauth/csrf-token.js"
+
+import type { RequestInternal, ResponseInternal } from "../types.js"
+import type { AuthConfig } from "../index.js"
+import { skipCSRFCheck } from "./symbols.js"
+
+export { customFetch, raw, skipCSRFCheck } from "./symbols.js"
+
+/** @internal */
+export async function AuthInternal(
+  request: RequestInternal,
+  authOptions: AuthConfig
+): Promise<ResponseInternal> {
+  const { action, providerId, error, method } = request
+
+  const csrfDisabled = authOptions.skipCSRFCheck === skipCSRFCheck
+
+  const { options, cookies } = await init({
+    authOptions,
+    action,
+    providerId,
+    url: request.url,
+    callbackUrl: request.body?.callbackUrl ?? request.query?.callbackUrl,
+    csrfToken: request.body?.csrfToken,
+    cookies: request.cookies,
+    isPost: method === "POST",
+    csrfDisabled,
+  })
+
+  const sessionStore = new SessionStore(
+    options.cookies.sessionToken,
+    request.cookies,
+    options.logger
+  )
+
+  if (method === "GET") {
+    const render = renderPage({ ...options, query: request.query, cookies })
+    switch (action) {
+      case "callback":
+        return await actions.callback(request, options, sessionStore, cookies)
+      case "csrf":
+        return render.csrf(csrfDisabled, options, cookies)
+      case "error":
+        return render.error(error)
+      case "providers":
+        return render.providers(options.providers)
+      case "session":
+        return await actions.session(options, sessionStore, cookies)
+      case "signin":
+        return render.signin(providerId, error)
+      case "signout":
+        return render.signout()
+      case "verify-request":
+        return render.verifyRequest()
+      case "webauthn-options":
+        return await actions.webAuthnOptions(
+          request,
+          options,
+          sessionStore,
+          cookies
+        )
+      default:
+    }
+  } else {
+    const { csrfTokenVerified } = options
+    switch (action) {
+      case "callback":
+        if (options.provider.type === "credentials")
+          // Verified CSRF Token required for credentials providers only
+          validateCSRF(action, csrfTokenVerified)
+        return await actions.callback(request, options, sessionStore, cookies)
+      case "session":
+        validateCSRF(action, csrfTokenVerified)
+        return await actions.session(
+          options,
+          sessionStore,
+          cookies,
+          true,
+          request.body?.data
+        )
+      case "signin":
+        validateCSRF(action, csrfTokenVerified)
+        return await actions.signIn(request, cookies, options)
+
+      case "signout":
+        validateCSRF(action, csrfTokenVerified)
+        return await actions.signOut(cookies, sessionStore, options)
+      default:
+    }
+  }
+  throw new UnknownAction(`Cannot handle action: ${action}`)
+}