@mulverse/mulguard-core 1.0.0

package/src/lib/actions/callback/oauth/callback.ts

@@ -0,0 +1,347 @@
+import * as checks from "./checks.js"
+import * as o from "oauth4webapi"
+import {
+  OAuthCallbackError,
+  OAuthProfileParseError,
+} from "../../../../errors.js"
+
+import type {
+  Account,
+  InternalOptions,
+  LoggerInstance,
+  Profile,
+  RequestInternal,
+  TokenSet,
+  User,
+} from "../../../../types.js"
+import { type OAuthConfigInternal } from "../../../../providers/index.js"
+import type { Cookie } from "../../../utils/cookie.js"
+import { isOIDCProvider } from "../../../utils/providers.js"
+import { conformInternal, customFetch } from "../../../symbols.js"
+import { decodeJwt } from "jose"
+
+function formUrlEncode(token: string) {
+  return encodeURIComponent(token).replace(/%20/g, "+")
+}
+
+/**
+ * Formats client_id and client_secret as an HTTP Basic Authentication header as per the OAuth 2.0
+ * specified in RFC6749.
+ */
+function clientSecretBasic(clientId: string, clientSecret: string) {
+  const username = formUrlEncode(clientId)
+  const password = formUrlEncode(clientSecret)
+  const credentials = btoa(`${username}:${password}`)
+  return `Basic ${credentials}`
+}
+
+/**
+ * Handles the following OAuth steps.
+ * https://www.rfc-editor.org/rfc/rfc6749#section-4.1.1
+ * https://www.rfc-editor.org/rfc/rfc6749#section-4.1.3
+ * https://openid.net/specs/openid-connect-core-1_0.html#UserInfoRequest
+ *
+ * @note Although requesting userinfo is not required by the OAuth2.0 spec,
+ * we fetch it anyway. This is because we always want a user profile.
+ */
+export async function handleOAuth(
+  params: RequestInternal["query"],
+  cookies: RequestInternal["cookies"],
+  options: InternalOptions<"oauth" | "oidc">
+) {
+  const { logger, provider } = options
+
+  let as: o.AuthorizationServer
+
+  const { token, userinfo } = provider
+  // Falls back to authjs.dev if the user only passed params
+  if (
+    (!token?.url || token.url.host === "authjs.dev") &&
+    (!userinfo?.url || userinfo.url.host === "authjs.dev")
+  ) {
+    // We assume that issuer is always defined as this has been asserted earlier
+
+    const issuer = new URL(provider.issuer!)
+    const discoveryResponse = await o.discoveryRequest(issuer, {
+      [o.allowInsecureRequests]: true,
+      [o.customFetch]: provider[customFetch],
+    })
+    as = await o.processDiscoveryResponse(issuer, discoveryResponse)
+
+    if (!as.token_endpoint)
+      throw new TypeError(
+        "TODO: Authorization server did not provide a token endpoint."
+      )
+
+    if (!as.userinfo_endpoint)
+      throw new TypeError(
+        "TODO: Authorization server did not provide a userinfo endpoint."
+      )
+  } else {
+    as = {
+      issuer: provider.issuer ?? "https://authjs.dev", // TODO: review fallback issuer
+      token_endpoint: token?.url.toString(),
+      userinfo_endpoint: userinfo?.url.toString(),
+    }
+  }
+
+  const client: o.Client = {
+    client_id: provider.clientId,
+    ...provider.client,
+  }
+
+  let clientAuth: o.ClientAuth
+
+  switch (client.token_endpoint_auth_method) {
+    // TODO: in the next breaking major version have undefined be `client_secret_post`
+    case undefined:
+    case "client_secret_basic":
+      // TODO: in the next breaking major version use o.ClientSecretBasic() here
+      clientAuth = (_as, _client, _body, headers) => {
+        headers.set(
+          "authorization",
+          clientSecretBasic(provider.clientId, provider.clientSecret!)
+        )
+      }
+      break
+    case "client_secret_post":
+      clientAuth = o.ClientSecretPost(provider.clientSecret!)
+      break
+    case "client_secret_jwt":
+      clientAuth = o.ClientSecretJwt(provider.clientSecret!)
+      break
+    case "private_key_jwt":
+      clientAuth = o.PrivateKeyJwt(provider.token!.clientPrivateKey!, {
+        // TODO: review in the next breaking change
+        [o.modifyAssertion](_header, payload) {
+          payload.aud = [as.issuer, as.token_endpoint!]
+        },
+      })
+      break
+    case "none":
+      clientAuth = o.None()
+      break
+    default:
+      throw new Error("unsupported client authentication method")
+  }
+
+  const resCookies: Cookie[] = []
+
+  const state = await checks.state.use(cookies, resCookies, options)
+
+  let codeGrantParams: URLSearchParams
+  try {
+    codeGrantParams = o.validateAuthResponse(
+      as,
+      client,
+      new URLSearchParams(params),
+      provider.checks.includes("state") ? state : o.skipStateCheck
+    )
+  } catch (err) {
+    if (err instanceof o.AuthorizationResponseError) {
+      const cause = {
+        providerId: provider.id,
+        ...Object.fromEntries(err.cause.entries()),
+      }
+      logger.debug("OAuthCallbackError", cause)
+      throw new OAuthCallbackError("OAuth Provider returned an error", cause)
+    }
+    throw err
+  }
+
+  const codeVerifier = await checks.pkce.use(cookies, resCookies, options)
+
+  let redirect_uri = provider.callbackUrl
+  if (!options.isOnRedirectProxy && provider.redirectProxyUrl) {
+    redirect_uri = provider.redirectProxyUrl
+  }
+
+  let codeGrantResponse = await o.authorizationCodeGrantRequest(
+    as,
+    client,
+    clientAuth,
+    codeGrantParams,
+    redirect_uri,
+    codeVerifier ?? "decoy",
+    {
+      // TODO: move away from allowing insecure HTTP requests
+      [o.allowInsecureRequests]: true,
+      [o.customFetch]: (...args) => {
+        if (!provider.checks.includes("pkce")) {
+          args[1].body.delete("code_verifier")
+        }
+        return (provider[customFetch] ?? fetch)(...args)
+      },
+    }
+  )
+
+  if (provider.token?.conform) {
+    codeGrantResponse =
+      (await provider.token.conform(codeGrantResponse.clone())) ??
+      codeGrantResponse
+  }
+
+  let profile: Profile = {}
+
+  const requireIdToken = isOIDCProvider(provider)
+
+  if (provider[conformInternal]) {
+    switch (provider.id) {
+      case "microsoft-entra-id":
+      case "azure-ad": {
+        /**
+         * These providers return errors in the response body and
+         * need the authorization server metadata to be re-processed
+         * based on the `id_token`'s `tid` claim.
+         * @see: https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow#error-response-1
+         */
+        const responseJson = await codeGrantResponse.clone().json()
+        if (responseJson.error) {
+          const cause = {
+            providerId: provider.id,
+            ...responseJson,
+          }
+          throw new OAuthCallbackError(
+            `OAuth Provider returned an error: ${responseJson.error}`,
+            cause
+          )
+        }
+        const { tid } = decodeJwt(responseJson.id_token)
+        if (typeof tid === "string") {
+          const tenantRe = /microsoftonline\.com\/(\w+)\/v2\.0/
+          const tenantId = as.issuer?.match(tenantRe)?.[1] ?? "common"
+          const issuer = new URL(as.issuer.replace(tenantId, tid))
+          const discoveryResponse = await o.discoveryRequest(issuer, {
+            [o.customFetch]: provider[customFetch],
+          })
+          as = await o.processDiscoveryResponse(issuer, discoveryResponse)
+        }
+        break
+      }
+      default:
+        break
+    }
+  }
+  const processedCodeResponse = await o.processAuthorizationCodeResponse(
+    as,
+    client,
+    codeGrantResponse,
+    {
+      expectedNonce: await checks.nonce.use(cookies, resCookies, options),
+      requireIdToken,
+    }
+  )
+
+  const tokens: TokenSet & Pick<Account, "expires_at"> = processedCodeResponse
+
+  if (requireIdToken) {
+    const idTokenClaims = o.getValidatedIdTokenClaims(processedCodeResponse)!
+    profile = idTokenClaims
+
+    // Apple sends some of the user information in a `user` parameter as a stringified JSON.
+    // It also only does so the first time the user consents to share their information.
+    if (provider[conformInternal] && provider.id === "apple") {
+      try {
+        profile.user = JSON.parse(params?.user)
+      } catch {}
+    }
+
+    if (provider.idToken === false) {
+      const userinfoResponse = await o.userInfoRequest(
+        as,
+        client,
+        processedCodeResponse.access_token,
+        {
+          [o.customFetch]: provider[customFetch],
+          // TODO: move away from allowing insecure HTTP requests
+          [o.allowInsecureRequests]: true,
+        }
+      )
+
+      profile = await o.processUserInfoResponse(
+        as,
+        client,
+        idTokenClaims.sub,
+        userinfoResponse
+      )
+    }
+  } else {
+    if (userinfo?.request) {
+      const _profile = await userinfo.request({ tokens, provider })
+      if (_profile instanceof Object) profile = _profile
+    } else if (userinfo?.url) {
+      const userinfoResponse = await o.userInfoRequest(
+        as,
+        client,
+        processedCodeResponse.access_token,
+        {
+          [o.customFetch]: provider[customFetch],
+          // TODO: move away from allowing insecure HTTP requests
+          [o.allowInsecureRequests]: true,
+        }
+      )
+      profile = await userinfoResponse.json()
+    } else {
+      throw new TypeError("No userinfo endpoint configured")
+    }
+  }
+
+  if (tokens.expires_in) {
+    tokens.expires_at =
+      Math.floor(Date.now() / 1000) + Number(tokens.expires_in)
+  }
+
+  const profileResult = await getUserAndAccount(
+    profile,
+    provider,
+    tokens,
+    logger
+  )
+
+  return { ...profileResult, profile, cookies: resCookies }
+}
+
+/**
+ * Returns the user and account that is going to be created in the database.
+ * @internal
+ */
+export async function getUserAndAccount(
+  OAuthProfile: Profile,
+  provider: OAuthConfigInternal<any>,
+  tokens: TokenSet,
+  logger: LoggerInstance
+) {
+  try {
+    const userFromProfile = await provider.profile(OAuthProfile, tokens)
+    const user = {
+      ...userFromProfile,
+      // The user's id is intentionally not set based on the profile id, as
+      // the user should remain independent of the provider and the profile id
+      // is saved on the Account already, as `providerAccountId`.
+      id: crypto.randomUUID(),
+      email: userFromProfile.email?.toLowerCase(),
+    } satisfies User
+
+    return {
+      user,
+      account: {
+        ...tokens,
+        provider: provider.id,
+        type: provider.type,
+        providerAccountId: userFromProfile.id ?? crypto.randomUUID(),
+      },
+    }
+  } catch (e) {
+    // If we didn't get a response either there was a problem with the provider
+    // response *or* the user cancelled the action with the provider.
+    //
+    // Unfortunately, we can't tell which - at least not in a way that works for
+    // all providers, so we return an empty object; the user should then be
+    // redirected back to the sign up page. We log the error to help developers
+    // who might be trying to debug this when configuring a new provider.
+    logger.debug("getProfile error details", OAuthProfile)
+    logger.error(
+      new OAuthProfileParseError(e as Error, { provider: provider.id })
+    )
+  }
+}

package/src/lib/actions/callback/oauth/checks.ts

@@ -0,0 +1,258 @@
+import * as o from "oauth4webapi"
+import { InvalidCheck } from "../../../../errors.js"
+
+// NOTE: We use the default JWT methods here because they encrypt/decrypt the payload, not just sign it.
+import { decode, encode } from "../../../../jwt.js"
+
+import type {
+  CookiesOptions,
+  InternalOptions,
+  RequestInternal,
+  User,
+} from "../../../../types.js"
+import type { Cookie } from "../../../utils/cookie.js"
+import type { WebAuthnProviderType } from "../../../../providers/webauthn.js"
+
+interface CookiePayload {
+  value: string
+}
+
+const COOKIE_TTL = 60 * 15 // 15 minutes
+
+/** Returns a cookie with a JWT encrypted payload. */
+async function sealCookie(
+  name: keyof CookiesOptions,
+  payload: string,
+  options: InternalOptions<"oauth" | "oidc" | WebAuthnProviderType>
+): Promise<Cookie> {
+  const { cookies, logger } = options
+  const cookie = cookies[name]
+  const expires = new Date()
+  expires.setTime(expires.getTime() + COOKIE_TTL * 1000)
+
+  logger.debug(`CREATE_${name.toUpperCase()}`, {
+    name: cookie.name,
+    payload,
+    COOKIE_TTL,
+    expires,
+  })
+
+  const encoded = await encode({
+    ...options.jwt,
+    maxAge: COOKIE_TTL,
+    token: { value: payload } satisfies CookiePayload,
+    salt: cookie.name,
+  })
+  const cookieOptions = { ...cookie.options, expires }
+  return { name: cookie.name, value: encoded, options: cookieOptions }
+}
+
+async function parseCookie(
+  name: keyof CookiesOptions,
+  value: string | undefined,
+  options: InternalOptions
+): Promise<string> {
+  try {
+    const { logger, cookies, jwt } = options
+    logger.debug(`PARSE_${name.toUpperCase()}`, { cookie: value })
+
+    if (!value) throw new InvalidCheck(`${name} cookie was missing`)
+    const parsed = await decode<CookiePayload>({
+      ...jwt,
+      token: value,
+      salt: cookies[name].name,
+    })
+    if (parsed?.value) return parsed.value
+    throw new Error("Invalid cookie")
+  } catch (error) {
+    throw new InvalidCheck(`${name} value could not be parsed`, {
+      cause: error,
+    })
+  }
+}
+
+function clearCookie(
+  name: keyof CookiesOptions,
+  options: InternalOptions,
+  resCookies: Cookie[]
+) {
+  const { logger, cookies } = options
+  const cookie = cookies[name]
+  logger.debug(`CLEAR_${name.toUpperCase()}`, { cookie })
+  resCookies.push({
+    name: cookie.name,
+    value: "",
+    options: { ...cookies[name].options, maxAge: 0 },
+  })
+}
+
+function useCookie(
+  check: "state" | "pkce" | "nonce",
+  name: keyof CookiesOptions
+) {
+  return async function (
+    cookies: RequestInternal["cookies"],
+    resCookies: Cookie[],
+    options: InternalOptions<"oidc">
+  ) {
+    const { provider, logger } = options
+    if (!provider?.checks?.includes(check)) return
+    const cookieValue = cookies?.[options.cookies[name].name]
+    logger.debug(`USE_${name.toUpperCase()}`, { value: cookieValue })
+    const parsed = await parseCookie(name, cookieValue, options)
+    clearCookie(name, options, resCookies)
+    return parsed
+  }
+}
+
+/**
+ * @see https://www.rfc-editor.org/rfc/rfc7636
+ * @see https://danielfett.de/2020/05/16/pkce-vs-nonce-equivalent-or-not/#pkce
+ */
+export const pkce = {
+  /** Creates a PKCE code challenge and verifier pair. The verifier in stored in the cookie. */
+  async create(options: InternalOptions<"oauth">) {
+    const code_verifier = o.generateRandomCodeVerifier()
+    const value = await o.calculatePKCECodeChallenge(code_verifier)
+    const cookie = await sealCookie("pkceCodeVerifier", code_verifier, options)
+    return { cookie, value }
+  },
+  /**
+   * Returns code_verifier if the provider is configured to use PKCE,
+   * and clears the container cookie afterwards.
+   * An error is thrown if the code_verifier is missing or invalid.
+   */
+  use: useCookie("pkce", "pkceCodeVerifier"),
+}
+
+interface EncodedState {
+  origin?: string
+  random: string
+}
+
+const STATE_MAX_AGE = 60 * 15 // 15 minutes in seconds
+const encodedStateSalt = "encodedState"
+
+/**
+ * @see https://www.rfc-editor.org/rfc/rfc6749#section-10.12
+ * @see https://www.rfc-editor.org/rfc/rfc6749#section-4.1.1
+ */
+export const state = {
+  /** Creates a state cookie with an optionally encoded body. */
+  async create(options: InternalOptions<"oauth">, origin?: string) {
+    const { provider } = options
+    if (!provider.checks.includes("state")) {
+      if (origin) {
+        throw new InvalidCheck(
+          "State data was provided but the provider is not configured to use state"
+        )
+      }
+      return
+    }
+
+    // IDEA: Allow the user to pass data to be stored in the state
+    const payload = {
+      origin,
+      random: o.generateRandomState(),
+    } satisfies EncodedState
+    const value = await encode({
+      secret: options.jwt.secret,
+      token: payload,
+      salt: encodedStateSalt,
+      maxAge: STATE_MAX_AGE,
+    })
+    const cookie = await sealCookie("state", value, options)
+
+    return { cookie, value }
+  },
+  /**
+   * Returns state if the provider is configured to use state,
+   * and clears the container cookie afterwards.
+   * An error is thrown if the state is missing or invalid.
+   */
+  use: useCookie("state", "state"),
+  /** Decodes the state. If it could not be decoded, it throws an error. */
+  async decode(state: string, options: InternalOptions) {
+    try {
+      options.logger.debug("DECODE_STATE", { state })
+      const payload = await decode<EncodedState>({
+        secret: options.jwt.secret,
+        token: state,
+        salt: encodedStateSalt,
+      })
+      if (payload) return payload
+      throw new Error("Invalid state")
+    } catch (error) {
+      throw new InvalidCheck("State could not be decoded", { cause: error })
+    }
+  },
+}
+
+export const nonce = {
+  async create(options: InternalOptions<"oidc">) {
+    if (!options.provider.checks.includes("nonce")) return
+    const value = o.generateRandomNonce()
+    const cookie = await sealCookie("nonce", value, options)
+    return { cookie, value }
+  },
+  /**
+   * Returns nonce if the provider is configured to use nonce,
+   * and clears the container cookie afterwards.
+   * An error is thrown if the nonce is missing or invalid.
+   * @see https://openid.net/specs/openid-connect-core-1_0.html#NonceNotes
+   * @see https://danielfett.de/2020/05/16/pkce-vs-nonce-equivalent-or-not/#nonce
+   */
+  use: useCookie("nonce", "nonce"),
+}
+
+const WEBAUTHN_CHALLENGE_MAX_AGE = 60 * 15 // 15 minutes in seconds
+
+interface WebAuthnChallengePayload {
+  challenge: string
+  registerData?: User
+}
+
+const webauthnChallengeSalt = "encodedWebauthnChallenge"
+export const webauthnChallenge = {
+  async create(
+    options: InternalOptions<WebAuthnProviderType>,
+    challenge: string,
+    registerData?: User
+  ) {
+    return {
+      cookie: await sealCookie(
+        "webauthnChallenge",
+        await encode({
+          secret: options.jwt.secret,
+          token: { challenge, registerData } satisfies WebAuthnChallengePayload,
+          salt: webauthnChallengeSalt,
+          maxAge: WEBAUTHN_CHALLENGE_MAX_AGE,
+        }),
+        options
+      ),
+    }
+  },
+  /** Returns WebAuthn challenge if present. */
+  async use(
+    options: InternalOptions<WebAuthnProviderType>,
+    cookies: RequestInternal["cookies"],
+    resCookies: Cookie[]
+  ): Promise<WebAuthnChallengePayload> {
+    const cookieValue = cookies?.[options.cookies.webauthnChallenge.name]
+
+    const parsed = await parseCookie("webauthnChallenge", cookieValue, options)
+
+    const payload = await decode<WebAuthnChallengePayload>({
+      secret: options.jwt.secret,
+      token: parsed,
+      salt: webauthnChallengeSalt,
+    })
+
+    // Clear the WebAuthn challenge cookie after use
+    clearCookie("webauthnChallenge", options, resCookies)
+
+    if (!payload) throw new InvalidCheck("WebAuthn challenge was missing")
+
+    return payload
+  },
+}

package/src/lib/actions/callback/oauth/csrf-token.ts

@@ -0,0 +1,60 @@
+import { createHash, randomString } from "../../../utils/web.js"
+
+import type { AuthAction, InternalOptions } from "../../../../types.js"
+import { MissingCSRF } from "../../../../errors.js"
+interface CreateCSRFTokenParams {
+  options: InternalOptions
+  cookieValue?: string
+  isPost: boolean
+  bodyValue?: string
+}
+
+/**
+ * Ensure CSRF Token cookie is set for any subsequent requests.
+ * Used as part of the strategy for mitigation for CSRF tokens.
+ *
+ * Creates a cookie like 'next-auth.csrf-token' with the value 'token|hash',
+ * where 'token' is the CSRF token and 'hash' is a hash made of the token and
+ * the secret, and the two values are joined by a pipe '|'. By storing the
+ * value and the hash of the value (with the secret used as a salt) we can
+ * verify the cookie was set by the server and not by a malicious attacker.
+ *
+ * For more details, see the following OWASP links:
+ * https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html#double-submit-cookie
+ * https://owasp.org/www-chapter-london/assets/slides/David_Johansson-Double_Defeat_of_Double-Submit_Cookie.pdf
+ */
+export async function createCSRFToken({
+  options,
+  cookieValue,
+  isPost,
+  bodyValue,
+}: CreateCSRFTokenParams) {
+  if (cookieValue) {
+    const [csrfToken, csrfTokenHash] = cookieValue.split("|")
+
+    const expectedCsrfTokenHash = await createHash(
+      `${csrfToken}${options.secret}`
+    )
+
+    if (csrfTokenHash === expectedCsrfTokenHash) {
+      // If hash matches then we trust the CSRF token value
+      // If this is a POST request and the CSRF Token in the POST request matches
+      // the cookie we have already verified is the one we have set, then the token is verified!
+      const csrfTokenVerified = isPost && csrfToken === bodyValue
+
+      return { csrfTokenVerified, csrfToken }
+    }
+  }
+
+  // New CSRF token
+  const csrfToken = randomString(32)
+  const csrfTokenHash = await createHash(`${csrfToken}${options.secret}`)
+  const cookie = `${csrfToken}|${csrfTokenHash}`
+
+  return { cookie, csrfToken }
+}
+
+export function validateCSRF(action: AuthAction, verified?: boolean) {
+  if (verified) return
+  throw new MissingCSRF(`CSRF token was missing during an action ${action}`)
+}

package/src/lib/actions/index.ts

@@ -0,0 +1,5 @@
+export { callback } from "./callback/index.js"
+export { session } from "./session.js"
+export { signIn } from "./signin/index.js"
+export { signOut } from "./signout.js"
+export { webAuthnOptions } from "./webauthn-options.js"