@mulverse/mulguard-core 1.0.0

package/src/lib/utils/assert.ts

@@ -0,0 +1,259 @@
+import { defaultCookies } from "./cookie.js"
+import {
+  AuthError,
+  DuplicateConditionalUI,
+  ExperimentalFeatureNotEnabled,
+  InvalidCallbackUrl,
+  InvalidEndpoints,
+  MissingAdapter,
+  MissingAdapterMethods,
+  MissingAuthorize,
+  MissingSecret,
+  MissingWebAuthnAutocomplete,
+  UnsupportedStrategy,
+  UntrustedHost,
+} from "../../errors.js"
+
+import type { RequestInternal, SemverString } from "../../types.js"
+import type { WarningCode } from "../../warnings.js"
+import { Adapter } from "../../adapters.js"
+import type { AuthConfig } from "../../index.js"
+import { createServerActionsAdapter } from "../../adapters/server-actions-helpers.js"
+
+type ConfigError =
+  | InvalidCallbackUrl
+  | InvalidEndpoints
+  | MissingAdapter
+  | MissingAdapterMethods
+  | MissingAuthorize
+  | MissingSecret
+  | UnsupportedStrategy
+
+let warned = false
+
+function isValidHttpUrl(url: string, baseUrl: string) {
+  try {
+    return /^https?:/.test(
+      new URL(url, url.startsWith("/") ? baseUrl : undefined).protocol
+    )
+  } catch {
+    return false
+  }
+}
+
+function isSemverString(version: string): version is SemverString {
+  return /^v\d+(?:\.\d+){0,2}$/.test(version)
+}
+
+let hasCredentials = false
+let hasEmail = false
+let hasWebAuthn = false
+
+const emailMethods: (keyof Adapter)[] = [
+  "createVerificationToken",
+  "useVerificationToken",
+  "getUserByEmail",
+]
+
+const sessionMethods: (keyof Adapter)[] = [
+  "createUser",
+  "getUser",
+  "getUserByEmail",
+  "getUserByAccount",
+  "updateUser",
+  "linkAccount",
+  "createSession",
+  "getSessionAndUser",
+  "updateSession",
+  "deleteSession",
+]
+
+const webauthnMethods: (keyof Adapter)[] = [
+  "createUser",
+  "getUser",
+  "linkAccount",
+  "getAccount",
+  "getAuthenticator",
+  "createAuthenticator",
+  "listAuthenticatorsByUserId",
+  "updateAuthenticatorCounter",
+]
+
+/**
+ * Verify that the user configured Auth.js correctly.
+ * Good place to mention deprecations as well.
+ *
+ * This is invoked before the init method, so default values are not available yet.
+ */
+export function assertConfig(
+  request: RequestInternal,
+  options: AuthConfig
+): ConfigError | WarningCode[] {
+  const { url } = request
+  const warnings: WarningCode[] = []
+
+  if (!warned && options.debug) warnings.push("debug-enabled")
+
+  if (!options.trustHost) {
+    return new UntrustedHost(`Host must be trusted. URL was: ${request.url}`)
+  }
+
+  if (!options.secret?.length) {
+    return new MissingSecret("Please define a `secret`")
+  }
+
+  const callbackUrlParam = request.query?.callbackUrl as string | undefined
+
+  if (callbackUrlParam && !isValidHttpUrl(callbackUrlParam, url.origin)) {
+    return new InvalidCallbackUrl(
+      `Invalid callback URL. Received: ${callbackUrlParam}`
+    )
+  }
+
+  const { callbackUrl: defaultCallbackUrl } = defaultCookies(
+    options.useSecureCookies ?? url.protocol === "https:"
+  )
+  const callbackUrlCookie =
+    request.cookies?.[
+      options.cookies?.callbackUrl?.name ?? defaultCallbackUrl.name
+    ]
+
+  if (callbackUrlCookie && !isValidHttpUrl(callbackUrlCookie, url.origin)) {
+    return new InvalidCallbackUrl(
+      `Invalid callback URL. Received: ${callbackUrlCookie}`
+    )
+  }
+
+  // Keep track of webauthn providers that use conditional UI
+  let hasConditionalUIProvider = false
+
+  for (const p of options.providers) {
+    const provider = typeof p === "function" ? p() : p
+    if (
+      (provider.type === "oauth" || provider.type === "oidc") &&
+      !(provider.issuer ?? provider.options?.issuer)
+    ) {
+      const { authorization: a, token: t, userinfo: u } = provider
+
+      let key
+      if (typeof a !== "string" && !a?.url) key = "authorization"
+      else if (typeof t !== "string" && !t?.url) key = "token"
+      else if (typeof u !== "string" && !u?.url) key = "userinfo"
+
+      if (key) {
+        return new InvalidEndpoints(
+          `Provider "${provider.id}" is missing both \`issuer\` and \`${key}\` endpoint config. At least one of them is required`
+        )
+      }
+    }
+
+    if (provider.type === "credentials") hasCredentials = true
+    else if (provider.type === "email") hasEmail = true
+    else if (provider.type === "webauthn") {
+      hasWebAuthn = true
+
+      // Validate simpleWebAuthnBrowserVersion
+      if (
+        provider.simpleWebAuthnBrowserVersion &&
+        !isSemverString(provider.simpleWebAuthnBrowserVersion)
+      ) {
+        return new AuthError(
+          `Invalid provider config for "${provider.id}": simpleWebAuthnBrowserVersion "${provider.simpleWebAuthnBrowserVersion}" must be a valid semver string.`
+        )
+      }
+
+      if (provider.enableConditionalUI) {
+        // Make sure only one webauthn provider has "enableConditionalUI" set to true
+        if (hasConditionalUIProvider) {
+          return new DuplicateConditionalUI(
+            `Multiple webauthn providers have 'enableConditionalUI' set to True. Only one provider can have this option enabled at a time`
+          )
+        }
+        hasConditionalUIProvider = true
+
+        // Make sure at least one formField has "webauthn" in its autocomplete param
+        const hasWebauthnFormField = Object.values(provider.formFields).some(
+          (f) =>
+            f.autocomplete && f.autocomplete.toString().indexOf("webauthn") > -1
+        )
+        if (!hasWebauthnFormField) {
+          return new MissingWebAuthnAutocomplete(
+            `Provider "${provider.id}" has 'enableConditionalUI' set to True, but none of its formFields have 'webauthn' in their autocomplete param`
+          )
+        }
+      }
+    }
+  }
+
+  if (hasCredentials) {
+    const dbStrategy = options.session?.strategy === "database"
+    const onlyCredentials = !options.providers.some(
+      (p) => (typeof p === "function" ? p() : p).type !== "credentials"
+    )
+    if (dbStrategy && onlyCredentials) {
+      return new UnsupportedStrategy(
+        "Signing in with credentials only supported if JWT strategy is enabled"
+      )
+    }
+
+    const credentialsNoAuthorize = options.providers.some((p) => {
+      const provider = typeof p === "function" ? p() : p
+      return provider.type === "credentials" && !provider.authorize
+    })
+    if (credentialsNoAuthorize) {
+      return new MissingAuthorize(
+        "Must define an authorize() handler to use credentials authentication provider"
+      )
+    }
+  }
+
+  const { adapter, serverActions, session } = options
+  
+  // Convert serverActions to adapter if provided and no adapter exists
+  const effectiveAdapter = adapter || (serverActions ? createServerActionsAdapter(serverActions) : undefined)
+
+  const requiredMethods: (keyof Adapter)[] = []
+
+  if (
+    hasEmail ||
+    session?.strategy === "database" ||
+    (!session?.strategy && effectiveAdapter)
+  ) {
+    if (hasEmail) {
+      if (!effectiveAdapter) return new MissingAdapter("Email login requires an adapter or serverActions")
+      requiredMethods.push(...emailMethods)
+    } else {
+      if (!effectiveAdapter)
+        return new MissingAdapter("Database session requires an adapter or serverActions")
+      requiredMethods.push(...sessionMethods)
+    }
+  }
+
+  if (hasWebAuthn) {
+    // Log experimental warning
+    if (options.experimental?.enableWebAuthn) {
+      warnings.push("experimental-webauthn")
+    } else {
+      return new ExperimentalFeatureNotEnabled(
+        "WebAuthn is an experimental feature. To enable it, set `experimental.enableWebAuthn` to `true` in your config"
+      )
+    }
+
+    if (!effectiveAdapter) return new MissingAdapter("WebAuthn requires an adapter or serverActions")
+    requiredMethods.push(...webauthnMethods)
+  }
+
+  if (effectiveAdapter) {
+    const missing = requiredMethods.filter((m) => !(m in effectiveAdapter))
+
+    if (missing.length) {
+      return new MissingAdapterMethods(
+        `Required adapter methods were missing: ${missing.join(", ")}`
+      )
+    }
+  }
+
+  if (!warned) warned = true
+
+  return warnings
+}

package/src/lib/utils/callback-url.ts

@@ -0,0 +1,42 @@
+import type { InternalOptions } from "../../types.js"
+
+interface CreateCallbackUrlParams {
+  options: InternalOptions
+  /** Try reading value from request body (POST) then from query param (GET) */
+  paramValue?: string
+  cookieValue?: string
+}
+
+/**
+ * Get callback URL based on query param / cookie + validation,
+ * and add it to `req.options.callbackUrl`.
+ */
+export async function createCallbackUrl({
+  options,
+  paramValue,
+  cookieValue,
+}: CreateCallbackUrlParams) {
+  const { url, callbacks } = options
+
+  let callbackUrl = url.origin
+
+  if (paramValue) {
+    // If callbackUrl form field or query parameter is passed try to use it if allowed
+    callbackUrl = await callbacks.redirect({
+      url: paramValue,
+      baseUrl: url.origin,
+    })
+  } else if (cookieValue) {
+    // If no callbackUrl specified, try using the value from the cookie if allowed
+    callbackUrl = await callbacks.redirect({
+      url: cookieValue,
+      baseUrl: url.origin,
+    })
+  }
+
+  return {
+    callbackUrl,
+    // Save callback URL in a cookie so that it can be used for subsequent requests in signin/signout/callback flow
+    callbackUrlCookie: callbackUrl !== cookieValue ? callbackUrl : undefined,
+  }
+}

package/src/lib/utils/cookie.ts

@@ -0,0 +1,248 @@
+import type {
+  CookieOption,
+  CookiesOptions,
+  LoggerInstance,
+  RequestInternal,
+} from "../../types.js"
+
+// Uncomment to recalculate the estimated size
+// of an empty session cookie
+// import * as cookie from "../vendored/cookie.js"
+// const { serialize } = cookie
+// console.log(
+//   "Cookie estimated to be ",
+//   serialize(`__Secure.authjs.session-token.0`, "", {
+//     expires: new Date(),
+//     httpOnly: true,
+//     maxAge: Number.MAX_SAFE_INTEGER,
+//     path: "/",
+//     sameSite: "strict",
+//     secure: true,
+//     domain: "example.com",
+//   }).length,
+//   " bytes"
+// )
+
+const ALLOWED_COOKIE_SIZE = 4096
+// Based on commented out section above
+const ESTIMATED_EMPTY_COOKIE_SIZE = 160
+const CHUNK_SIZE = ALLOWED_COOKIE_SIZE - ESTIMATED_EMPTY_COOKIE_SIZE
+
+// REVIEW: Is there any way to defer two types of strings?
+
+/** Stringified form of `JWT`. Extract the content with `jwt.decode` */
+export type JWTString = string
+
+export type SetCookieOptions = Partial<CookieOption["options"]> & {
+  expires?: Date | string
+  encode?: (val: unknown) => string
+}
+
+/**
+ * If `options.session.strategy` is set to `jwt`, this is a stringified `JWT`.
+ * In case of `strategy: "database"`, this is the `sessionToken` of the session in the database.
+ */
+export type SessionToken<T extends "jwt" | "database" = "jwt"> = T extends "jwt"
+  ? JWTString
+  : string
+
+/**
+ * Use secure cookies if the site uses HTTPS
+ * This being conditional allows cookies to work non-HTTPS development URLs
+ * Honour secure cookie option, which sets 'secure' and also adds '__Secure-'
+ * prefix, but enable them by default if the site URL is HTTPS; but not for
+ * non-HTTPS URLs like http://localhost which are used in development).
+ * For more on prefixes see https://googlechrome.github.io/samples/cookie-prefixes/
+ *
+ * @TODO Review cookie settings (names, options)
+ */
+export function defaultCookies(useSecureCookies: boolean) {
+  const cookiePrefix = useSecureCookies ? "__Secure-" : ""
+  return {
+    // default cookie options
+    sessionToken: {
+      name: `${cookiePrefix}authjs.session-token`,
+      options: {
+        httpOnly: true,
+        sameSite: "lax",
+        path: "/",
+        secure: useSecureCookies,
+      },
+    },
+    callbackUrl: {
+      name: `${cookiePrefix}authjs.callback-url`,
+      options: {
+        httpOnly: true,
+        sameSite: "lax",
+        path: "/",
+        secure: useSecureCookies,
+      },
+    },
+    csrfToken: {
+      // Default to __Host- for CSRF token for additional protection if using useSecureCookies
+      // NB: The `__Host-` prefix is stricter than the `__Secure-` prefix.
+      name: `${useSecureCookies ? "__Host-" : ""}authjs.csrf-token`,
+      options: {
+        httpOnly: true,
+        sameSite: "lax",
+        path: "/",
+        secure: useSecureCookies,
+      },
+    },
+    pkceCodeVerifier: {
+      name: `${cookiePrefix}authjs.pkce.code_verifier`,
+      options: {
+        httpOnly: true,
+        sameSite: "lax",
+        path: "/",
+        secure: useSecureCookies,
+        maxAge: 60 * 15, // 15 minutes in seconds
+      },
+    },
+    state: {
+      name: `${cookiePrefix}authjs.state`,
+      options: {
+        httpOnly: true,
+        sameSite: "lax",
+        path: "/",
+        secure: useSecureCookies,
+        maxAge: 60 * 15, // 15 minutes in seconds
+      },
+    },
+    nonce: {
+      name: `${cookiePrefix}authjs.nonce`,
+      options: {
+        httpOnly: true,
+        sameSite: "lax",
+        path: "/",
+        secure: useSecureCookies,
+      },
+    },
+    webauthnChallenge: {
+      name: `${cookiePrefix}authjs.challenge`,
+      options: {
+        httpOnly: true,
+        sameSite: "lax",
+        path: "/",
+        secure: useSecureCookies,
+        maxAge: 60 * 15, // 15 minutes in seconds
+      },
+    },
+  } as const satisfies CookiesOptions
+}
+
+export interface Cookie extends CookieOption {
+  value: string
+}
+
+type Chunks = Record<string, string>
+
+export class SessionStore {
+  #chunks: Chunks = {}
+  #option: CookieOption
+  #logger: LoggerInstance | Console
+
+  constructor(
+    option: CookieOption,
+    cookies: RequestInternal["cookies"],
+    logger: LoggerInstance | Console
+  ) {
+    this.#logger = logger
+    this.#option = option
+    if (!cookies) return
+
+    const { name: sessionCookiePrefix } = option
+
+    for (const [name, value] of Object.entries(cookies)) {
+      if (!name.startsWith(sessionCookiePrefix) || !value) continue
+      this.#chunks[name] = value
+    }
+  }
+
+  /**
+   * The JWT Session or database Session ID
+   * constructed from the cookie chunks.
+   */
+  get value() {
+    // Sort the chunks by their keys before joining
+    const sortedKeys = Object.keys(this.#chunks).sort((a, b) => {
+      const aSuffix = parseInt(a.split(".").pop() || "0")
+      const bSuffix = parseInt(b.split(".").pop() || "0")
+
+      return aSuffix - bSuffix
+    })
+
+    // Use the sorted keys to join the chunks in the correct order
+    return sortedKeys.map((key) => this.#chunks[key]).join("")
+  }
+
+  /** Given a cookie, return a list of cookies, chunked to fit the allowed cookie size. */
+  #chunk(cookie: Cookie): Cookie[] {
+    const chunkCount = Math.ceil(cookie.value.length / CHUNK_SIZE)
+
+    if (chunkCount === 1) {
+      this.#chunks[cookie.name] = cookie.value
+      return [cookie]
+    }
+
+    const cookies: Cookie[] = []
+    for (let i = 0; i < chunkCount; i++) {
+      const name = `${cookie.name}.${i}`
+      const value = cookie.value.substr(i * CHUNK_SIZE, CHUNK_SIZE)
+      cookies.push({ ...cookie, name, value })
+      this.#chunks[name] = value
+    }
+
+    this.#logger.debug("CHUNKING_SESSION_COOKIE", {
+      message: `Session cookie exceeds allowed ${ALLOWED_COOKIE_SIZE} bytes.`,
+      emptyCookieSize: ESTIMATED_EMPTY_COOKIE_SIZE,
+      valueSize: cookie.value.length,
+      chunks: cookies.map((c) => c.value.length + ESTIMATED_EMPTY_COOKIE_SIZE),
+    })
+
+    return cookies
+  }
+
+  /** Returns cleaned cookie chunks. */
+  #clean(): Record<string, Cookie> {
+    const cleanedChunks: Record<string, Cookie> = {}
+    for (const name in this.#chunks) {
+      delete this.#chunks?.[name]
+      cleanedChunks[name] = {
+        name,
+        value: "",
+        options: { ...this.#option.options, maxAge: 0 },
+      }
+    }
+    return cleanedChunks
+  }
+
+  /**
+   * Given a cookie value, return new cookies, chunked, to fit the allowed cookie size.
+   * If the cookie has changed from chunked to unchunked or vice versa,
+   * it deletes the old cookies as well.
+   */
+  chunk(value: string, options: Partial<Cookie["options"]>): Cookie[] {
+    // Assume all cookies should be cleaned by default
+    const cookies: Record<string, Cookie> = this.#clean()
+
+    // Calculate new chunks
+    const chunked = this.#chunk({
+      name: this.#option.name,
+      value,
+      options: { ...this.#option.options, ...options },
+    })
+
+    // Update stored chunks / cookies
+    for (const chunk of chunked) {
+      cookies[chunk.name] = chunk
+    }
+
+    return Object.values(cookies)
+  }
+
+  /** Returns a list of cookies that should be cleaned. */
+  clean(): Cookie[] {
+    return Object.values(this.#clean())
+  }
+}

package/src/lib/utils/date.ts

@@ -0,0 +1,8 @@
+/**
+ * Takes a number in seconds and returns the date in the future.
+ * Optionally takes a second date parameter. In that case
+ * the date in the future will be calculated from that date instead of now.
+ */
+export function fromDate(time: number, date = Date.now()) {
+  return new Date(date + time * 1000)
+}

package/src/lib/utils/email.ts

@@ -0,0 +1,65 @@
+import type { Theme } from "../../types.js"
+
+/**
+ * Email HTML body
+ * Insert invisible space into domains from being turned into a hyperlink by email
+ * clients like Outlook and Apple mail, as this is confusing because it seems
+ * like they are supposed to click on it to sign in.
+ *
+ * @note We don't add the email address to avoid needing to escape it, if you do, remember to sanitize it!
+ */
+export function html(params: { url: string; host: string; theme: Theme }) {
+  const { url, host, theme } = params
+
+  const escapedHost = host.replace(/\./g, "​.")
+
+  const brandColor = theme.brandColor || "#346df1"
+
+  const buttonText = theme.buttonText || "#fff"
+
+  const color = {
+    background: "#f9f9f9",
+    text: "#444",
+    mainBackground: "#fff",
+    buttonBackground: brandColor,
+    buttonBorder: brandColor,
+    buttonText,
+  }
+
+  return `
+<body style="background: ${color.background};">
+  <table width="100%" border="0" cellspacing="20" cellpadding="0"
+    style="background: ${color.mainBackground}; max-width: 600px; margin: auto; border-radius: 10px;">
+    <tr>
+      <td align="center"
+        style="padding: 10px 0px; font-size: 22px; font-family: Helvetica, Arial, sans-serif; color: ${color.text};">
+        Sign in to <strong>${escapedHost}</strong>
+      </td>
+    </tr>
+    <tr>
+      <td align="center" style="padding: 20px 0;">
+        <table border="0" cellspacing="0" cellpadding="0">
+          <tr>
+            <td align="center" style="border-radius: 5px;" bgcolor="${color.buttonBackground}"><a href="${url}"
+                target="_blank"
+                style="font-size: 18px; font-family: Helvetica, Arial, sans-serif; color: ${color.buttonText}; text-decoration: none; border-radius: 5px; padding: 10px 20px; border: 1px solid ${color.buttonBorder}; display: inline-block; font-weight: bold;">Sign
+                in</a></td>
+          </tr>
+        </table>
+      </td>
+    </tr>
+    <tr>
+      <td align="center"
+        style="padding: 0px 0px 10px 0px; font-size: 16px; line-height: 22px; font-family: Helvetica, Arial, sans-serif; color: ${color.text};">
+        If you did not request this email you can safely ignore it.
+      </td>
+    </tr>
+  </table>
+</body>
+`
+}
+
+/** Email Text body (fallback for email clients that don't render HTML, e.g. feature phones) */
+export function text({ url, host }: { url: string; host: string }) {
+  return `Sign in to ${host}\n${url}\n\n`
+}