@mulverse/mulguard-core 1.0.0

package/src/jwt.ts

@@ -0,0 +1,283 @@
+/**
+ *
+ *
+ * This module contains functions and types
+ * to encode and decode {@link https://authjs.dev/concepts/session-strategies#jwt-session JWT}s
+ * issued and used by Auth.js.
+ *
+ * The JWT issued by Auth.js is _encrypted by default_, using the _A256CBC-HS512_ algorithm ({@link https://www.rfc-editor.org/rfc/rfc7518.html#section-5.2.5 JWE}).
+ * It uses the `AUTH_SECRET` environment variable or the passed `secret` property to derive a suitable encryption key.
+ *
+ * :::info Note
+ * Auth.js JWTs are meant to be used by the same app that issued them.
+ * If you need JWT authentication for your third-party API, you should rely on your Identity Provider instead.
+ * :::
+ *
+ * ## Installation
+ *
+ * ```bash npm2yarn
+ * npm install @auth/core
+ * ```
+ *
+ * You can then import this submodule from `@auth/core/jwt`.
+ *
+ * ## Usage
+ *
+ * :::warning Warning
+ * This module *will* be refactored/changed. We do not recommend relying on it right now.
+ * :::
+ *
+ *
+ * ## Resources
+ *
+ * - [What is a JWT session strategy](https://authjs.dev/concepts/session-strategies#jwt-session)
+ * - [RFC7519 - JSON Web Token (JWT)](https://www.rfc-editor.org/rfc/rfc7519)
+ *
+ * @module jwt
+ */
+
+import { hkdf } from "@panva/hkdf"
+import { EncryptJWT, base64url, calculateJwkThumbprint, jwtDecrypt } from "jose"
+import { defaultCookies, SessionStore } from "./lib/utils/cookie.js"
+import { Awaitable } from "./types.js"
+import type { LoggerInstance } from "./lib/utils/logger.js"
+import { MissingSecret } from "./errors.js"
+import * as cookie from "./lib/vendored/cookie.js"
+
+const { parse: parseCookie } = cookie
+const DEFAULT_MAX_AGE = 30 * 24 * 60 * 60 // 30 days
+
+const now = () => (Date.now() / 1000) | 0
+
+const alg = "dir"
+const enc = "A256CBC-HS512"
+type Digest = Parameters<typeof calculateJwkThumbprint>[1]
+
+/** Issues a JWT. By default, the JWT is encrypted using "A256CBC-HS512". */
+export async function encode<Payload = JWT>(params: JWTEncodeParams<Payload>) {
+  const { token = {}, secret, maxAge = DEFAULT_MAX_AGE, salt } = params
+  const secrets = Array.isArray(secret) ? secret : [secret]
+  const encryptionSecret = await getDerivedEncryptionKey(enc, secrets[0], salt)
+
+  const thumbprint = await calculateJwkThumbprint(
+    { kty: "oct", k: base64url.encode(encryptionSecret) },
+    `sha${encryptionSecret.byteLength << 3}` as Digest
+  )
+  // @ts-expect-error `jose` allows any object as payload.
+  return await new EncryptJWT(token)
+    .setProtectedHeader({ alg, enc, kid: thumbprint })
+    .setIssuedAt()
+    .setExpirationTime(now() + maxAge)
+    .setJti(crypto.randomUUID())
+    .encrypt(encryptionSecret)
+}
+
+/** Decodes an Auth.js issued JWT. */
+export async function decode<Payload = JWT>(
+  params: JWTDecodeParams
+): Promise<Payload | null> {
+  const { token, secret, salt } = params
+  const secrets = Array.isArray(secret) ? secret : [secret]
+  if (!token) return null
+  const { payload } = await jwtDecrypt(
+    token,
+    async ({ kid, enc }) => {
+      for (const secret of secrets) {
+        const encryptionSecret = await getDerivedEncryptionKey(
+          enc,
+          secret,
+          salt
+        )
+        if (kid === undefined) return encryptionSecret
+
+        const thumbprint = await calculateJwkThumbprint(
+          { kty: "oct", k: base64url.encode(encryptionSecret) },
+          `sha${encryptionSecret.byteLength << 3}` as Digest
+        )
+        if (kid === thumbprint) return encryptionSecret
+      }
+
+      throw new Error("no matching decryption secret")
+    },
+    {
+      clockTolerance: 15,
+      keyManagementAlgorithms: [alg],
+      contentEncryptionAlgorithms: [enc, "A256GCM"],
+    }
+  )
+  return payload as Payload
+}
+
+type GetTokenParamsBase = {
+  secret?: JWTDecodeParams["secret"]
+  salt?: JWTDecodeParams["salt"]
+}
+
+export interface GetTokenParams<R extends boolean = false>
+  extends GetTokenParamsBase {
+  /** The request containing the JWT either in the cookies or in the `Authorization` header. */
+  req: Request | { headers: Headers | Record<string, string> }
+  /**
+   * Use secure prefix for cookie name, unless URL in `NEXTAUTH_URL` is http://
+   * or not set (e.g. development or test instance) case use unprefixed name
+   */
+  secureCookie?: boolean
+  /** If the JWT is in the cookie, what name `getToken()` should look for. */
+  cookieName?: string
+  /**
+   * `getToken()` will return the raw JWT if this is set to `true`
+   *
+   * @default false
+   */
+  raw?: R
+  decode?: JWTOptions["decode"]
+  logger?: LoggerInstance | Console
+}
+
+/**
+ * Takes an Auth.js request (`req`) and returns either the Auth.js issued JWT's payload,
+ * or the raw JWT string. We look for the JWT in the either the cookies, or the `Authorization` header.
+ */
+export async function getToken<R extends boolean = false>(
+  params: GetTokenParams<R>
+): Promise<R extends true ? string : JWT | null>
+export async function getToken(
+  params: GetTokenParams
+): Promise<string | JWT | null> {
+  const {
+    secureCookie,
+    cookieName = defaultCookies(secureCookie ?? false).sessionToken.name,
+    decode: _decode = decode,
+    salt = cookieName,
+    secret,
+    logger = console,
+    raw,
+    req,
+  } = params
+
+  if (!req) throw new Error("Must pass `req` to JWT getToken()")
+
+  const headers =
+    req.headers instanceof Headers ? req.headers : new Headers(req.headers)
+
+  const sessionStore = new SessionStore(
+    { name: cookieName, options: { secure: secureCookie } },
+    parseCookie(headers.get("cookie") ?? ""),
+    logger
+  )
+
+  let token = sessionStore.value
+
+  const authorizationHeader = headers.get("authorization")
+
+  if (!token && authorizationHeader?.split(" ")[0] === "Bearer") {
+    const urlEncodedToken = authorizationHeader.split(" ")[1]
+    token = decodeURIComponent(urlEncodedToken)
+  }
+
+  if (!token) return null
+
+  if (raw) return token
+
+  if (!secret)
+    throw new MissingSecret("Must pass `secret` if not set to JWT getToken()")
+
+  try {
+    return await _decode({ token, secret, salt })
+  } catch {
+    return null
+  }
+}
+
+async function getDerivedEncryptionKey(
+  enc: string,
+  keyMaterial: Parameters<typeof hkdf>[1],
+  salt: Parameters<typeof hkdf>[2]
+) {
+  let length: number
+  switch (enc) {
+    case "A256CBC-HS512":
+      length = 64
+      break
+    case "A256GCM":
+      length = 32
+      break
+    default:
+      throw new Error("Unsupported JWT Content Encryption Algorithm")
+  }
+  return await hkdf(
+    "sha256",
+    keyMaterial,
+    salt,
+    `Auth.js Generated Encryption Key (${salt})`,
+    length
+  )
+}
+
+export interface DefaultJWT extends Record<string, unknown> {
+  name?: string | null
+  email?: string | null
+  picture?: string | null
+  sub?: string
+  iat?: number
+  exp?: number
+  jti?: string
+}
+
+/**
+ * Returned by the `jwt` callback when using JWT sessions
+ *
+ * [`jwt` callback](https://authjs.dev/reference/core/types#jwt)
+ */
+export interface JWT extends Record<string, unknown>, DefaultJWT {}
+
+export interface JWTEncodeParams<Payload = JWT> {
+  /**
+   * The maximum age of the Auth.js issued JWT in seconds.
+   *
+   * @default 30 * 24 * 60 * 60 // 30 days
+   */
+  maxAge?: number
+  /** Used in combination with `secret`, to derive the encryption secret for JWTs. */
+  salt: string
+  /** Used in combination with `salt`, to derive the encryption secret for JWTs. */
+  secret: string | string[]
+  /** The JWT payload. */
+  token?: Payload
+}
+
+export interface JWTDecodeParams {
+  /** Used in combination with `secret`, to derive the encryption secret for JWTs. */
+  salt: string
+  /**
+   * Used in combination with `salt`, to derive the encryption secret for JWTs.
+   *
+   * @note
+   * You can also pass an array of secrets, in which case the first secret that successfully
+   * decrypts the JWT will be used. This is useful for rotating secrets without invalidating existing sessions.
+   * The newer secret should be added to the start of the array, which will be used for all new sessions.
+   */
+  secret: string | string[]
+  /** The Auth.js issued JWT to be decoded */
+  token?: string
+}
+
+export interface JWTOptions {
+  /**
+   * The secret used to encode/decode the Auth.js issued JWT.
+   * It can be an array of secrets, in which case the first secret that successfully
+   * decrypts the JWT will be used. This is useful for rotating secrets without invalidating existing sessions.
+   * @internal
+   */
+  secret: string | string[]
+  /**
+   * The maximum age of the Auth.js issued JWT in seconds.
+   *
+   * @default 30 * 24 * 60 * 60 // 30 days
+   */
+  maxAge: number
+  /** Override this method to control the Auth.js issued JWT encoding. */
+  encode: (params: JWTEncodeParams) => Awaitable<string>
+  /** Override this method to control the Auth.js issued JWT decoding. */
+  decode: (params: JWTDecodeParams) => Awaitable<JWT | null>
+}

package/src/lib/actions/callback/handle-login.ts

@@ -0,0 +1,334 @@
+import { AccountNotLinked, OAuthAccountNotLinked } from "../../../errors.js"
+import { fromDate } from "../../utils/date.js"
+
+import type {
+  AdapterAccount,
+  AdapterSession,
+  AdapterUser,
+} from "../../../adapters.js"
+import type { Account, InternalOptions, User } from "../../../types.js"
+import type { JWT } from "../../../jwt.js"
+import type { OAuthConfig } from "../../../providers/index.js"
+import type { SessionToken } from "../../utils/cookie.js"
+
+/**
+ * This function handles the complex flow of signing users in, and either creating,
+ * linking (or not linking) accounts depending on if the user is currently logged
+ * in, if they have account already and the authentication mechanism they are using.
+ *
+ * It prevents insecure behaviour, such as linking OAuth accounts unless a user is
+ * signed in and authenticated with an existing valid account.
+ *
+ * All verification (e.g. OAuth flows or email address verification flows) are
+ * done prior to this handler being called to avoid additional complexity in this
+ * handler.
+ */
+export async function handleLoginOrRegister(
+  sessionToken: SessionToken,
+  _profile: User | AdapterUser | { email: string },
+  _account: AdapterAccount | Account | null,
+  options: InternalOptions
+) {
+  // Input validation
+  if (!_account?.providerAccountId || !_account.type)
+    throw new Error("Missing or invalid provider account")
+  if (!["email", "oauth", "oidc", "webauthn"].includes(_account.type))
+    throw new Error("Provider not supported")
+
+  const {
+    adapter,
+    jwt,
+    events,
+    session: { strategy: sessionStrategy, generateSessionToken },
+  } = options
+
+  // If no adapter is configured then we don't have a database and cannot
+  // persist data; in this mode we just return a dummy session object.
+  if (!adapter) {
+    return { user: _profile as User, account: _account as Account }
+  }
+
+  const profile = _profile as AdapterUser
+  let account = _account as AdapterAccount
+
+  const {
+    createUser,
+    updateUser,
+    getUser,
+    getUserByAccount,
+    getUserByEmail,
+    linkAccount,
+    createSession,
+    getSessionAndUser,
+    deleteSession,
+  } = adapter
+
+  let session: AdapterSession | JWT | null = null
+  let user: AdapterUser | null = null
+  let isNewUser = false
+
+  const useJwtSession = sessionStrategy === "jwt"
+
+  if (sessionToken) {
+    if (useJwtSession) {
+      try {
+        const salt = options.cookies.sessionToken.name
+        session = await jwt.decode({ ...jwt, token: sessionToken, salt })
+        if (session && "sub" in session && session.sub) {
+          user = await getUser(session.sub)
+        }
+      } catch {
+        // If session can't be verified, treat as no session
+      }
+    } else {
+      const userAndSession = await getSessionAndUser(sessionToken)
+      if (userAndSession) {
+        session = userAndSession.session
+        user = userAndSession.user
+      }
+    }
+  }
+
+  if (account.type === "email") {
+    // If signing in with an email, check if an account with the same email address exists already
+    const userByEmail = await getUserByEmail(profile.email)
+    if (userByEmail) {
+      // If they are not already signed in as the same user, this flow will
+      // sign them out of the current session and sign them in as the new user
+      if (user?.id !== userByEmail.id && !useJwtSession && sessionToken) {
+        // Delete existing session if they are currently signed in as another user.
+        // This will switch user accounts for the session in cases where the user was
+        // already logged in with a different account.
+        await deleteSession(sessionToken)
+      }
+
+      // Update emailVerified property on the user object
+      user = await updateUser({
+        id: userByEmail.id,
+        emailVerified: new Date(),
+      })
+      await events.updateUser?.({ user })
+    } else {
+      // Create user account if there isn't one for the email address already
+      user = await createUser({ ...profile, emailVerified: new Date() })
+      await events.createUser?.({ user })
+      isNewUser = true
+    }
+
+    // Create new session
+    session = useJwtSession
+      ? {}
+      : await createSession({
+          sessionToken: generateSessionToken(),
+          userId: user.id,
+          expires: fromDate(options.session.maxAge),
+        })
+
+    return { session, user, isNewUser }
+  } else if (account.type === "webauthn") {
+    // Check if the account exists
+    const userByAccount = await getUserByAccount({
+      providerAccountId: account.providerAccountId,
+      provider: account.provider,
+    })
+    if (userByAccount) {
+      if (user) {
+        // If the user is already signed in with this account, we don't need to do anything
+        if (userByAccount.id === user.id) {
+          const currentAccount: AdapterAccount = { ...account, userId: user.id }
+          return { session, user, isNewUser, account: currentAccount }
+        }
+        // If the user is currently signed in, but the new account they are signing in
+        // with is already associated with another user, then we cannot link them
+        // and need to return an error.
+        throw new AccountNotLinked(
+          "The account is already associated with another user",
+          { provider: account.provider }
+        )
+      }
+      // If there is no active session, but the account being signed in with is already
+      // associated with a valid user then create session to sign the user in.
+      session = useJwtSession
+        ? {}
+        : await createSession({
+            sessionToken: generateSessionToken(),
+            userId: userByAccount.id,
+            expires: fromDate(options.session.maxAge),
+          })
+
+      const currentAccount: AdapterAccount = {
+        ...account,
+        userId: userByAccount.id,
+      }
+      return {
+        session,
+        user: userByAccount,
+        isNewUser,
+        account: currentAccount,
+      }
+    } else {
+      // If the account doesn't exist, we'll create it
+      if (user) {
+        // If the user is already signed in and the account isn't already associated
+        // with another user account then we can go ahead and link the accounts safely.
+        await linkAccount({ ...account, userId: user.id })
+        await events.linkAccount?.({ user, account, profile })
+
+        // As they are already signed in, we don't need to do anything after linking them
+        const currentAccount: AdapterAccount = { ...account, userId: user.id }
+        return { session, user, isNewUser, account: currentAccount }
+      }
+
+      // If the user is not signed in and it looks like a new account then we
+      // check there also isn't an user account already associated with the same
+      // email address as the one in the request.
+      const userByEmail = profile.email
+        ? await getUserByEmail(profile.email)
+        : null
+      if (userByEmail) {
+        // We don't trust user-provided email addresses, so we don't want to link accounts
+        // if the email address associated with the new account is already associated with
+        // an existing account.
+        throw new AccountNotLinked(
+          "Another account already exists with the same e-mail address",
+          { provider: account.provider }
+        )
+      } else {
+        // If the current user is not logged in and the profile isn't linked to any user
+        // accounts (by email or provider account id)...
+        //
+        // If no account matching the same [provider].id or .email exists, we can
+        // create a new account for the user, link it to the OAuth account and
+        // create a new session for them so they are signed in with it.
+        user = await createUser({ ...profile })
+      }
+      await events.createUser?.({ user })
+
+      await linkAccount({ ...account, userId: user.id })
+      await events.linkAccount?.({ user, account, profile })
+
+      session = useJwtSession
+        ? {}
+        : await createSession({
+            sessionToken: generateSessionToken(),
+            userId: user.id,
+            expires: fromDate(options.session.maxAge),
+          })
+
+      const currentAccount: AdapterAccount = { ...account, userId: user.id }
+      return { session, user, isNewUser: true, account: currentAccount }
+    }
+  }
+
+  // If signing in with OAuth account, check to see if the account exists already
+  const userByAccount = await getUserByAccount({
+    providerAccountId: account.providerAccountId,
+    provider: account.provider,
+  })
+  if (userByAccount) {
+    if (user) {
+      // If the user is already signed in with this account, we don't need to do anything
+      if (userByAccount.id === user.id) {
+        return { session, user, isNewUser }
+      }
+      // If the user is currently signed in, but the new account they are signing in
+      // with is already associated with another user, then we cannot link them
+      // and need to return an error.
+      throw new OAuthAccountNotLinked(
+        "The account is already associated with another user",
+        { provider: account.provider }
+      )
+    }
+    // If there is no active session, but the account being signed in with is already
+    // associated with a valid user then create session to sign the user in.
+    session = useJwtSession
+      ? {}
+      : await createSession({
+          sessionToken: generateSessionToken(),
+          userId: userByAccount.id,
+          expires: fromDate(options.session.maxAge),
+        })
+
+    return { session, user: userByAccount, isNewUser }
+  } else {
+    const { provider: p } = options as InternalOptions<"oauth" | "oidc">
+    const { type, provider, providerAccountId, userId, ...tokenSet } = account
+    const defaults = { providerAccountId, provider, type, userId }
+    account = Object.assign(p.account(tokenSet) ?? {}, defaults)
+
+    if (user) {
+      // If the user is already signed in and the OAuth account isn't already associated
+      // with another user account then we can go ahead and link the accounts safely.
+      await linkAccount({ ...account, userId: user.id })
+      await events.linkAccount?.({ user, account, profile })
+
+      // As they are already signed in, we don't need to do anything after linking them
+      return { session, user, isNewUser }
+    }
+
+    // If the user is not signed in and it looks like a new OAuth account then we
+    // check there also isn't an user account already associated with the same
+    // email address as the one in the OAuth profile.
+    //
+    // This step is often overlooked in OAuth implementations, but covers the following cases:
+    //
+    // 1. It makes it harder for someone to accidentally create two accounts.
+    //    e.g. by signin in with email, then again with an oauth account connected to the same email.
+    // 2. It makes it harder to hijack a user account using a 3rd party OAuth account.
+    //    e.g. by creating an oauth account then changing the email address associated with it.
+    //
+    // It's quite common for services to automatically link accounts in this case, but it's
+    // better practice to require the user to sign in *then* link accounts to be sure
+    // someone is not exploiting a problem with a third party OAuth service.
+    //
+    // OAuth providers should require email address verification to prevent this, but in
+    // practice that is not always the case; this helps protect against that.
+    const userByEmail = profile.email
+      ? await getUserByEmail(profile.email)
+      : null
+    if (userByEmail) {
+      const provider = options.provider as OAuthConfig<any>
+      if (provider?.allowDangerousEmailAccountLinking) {
+        // If you trust the oauth provider to correctly verify email addresses, you can opt-in to
+        // account linking even when the user is not signed-in.
+        user = userByEmail
+        isNewUser = false
+      } else {
+        // We end up here when we don't have an account with the same [provider].id *BUT*
+        // we do already have an account with the same email address as the one in the
+        // OAuth profile the user has just tried to sign in with.
+        //
+        // We don't want to have two accounts with the same email address, and we don't
+        // want to link them in case it's not safe to do so, so instead we prompt the user
+        // to sign in via email to verify their identity and then link the accounts.
+        throw new OAuthAccountNotLinked(
+          "Another account already exists with the same e-mail address",
+          { provider: account.provider }
+        )
+      }
+    } else {
+      // If the current user is not logged in and the profile isn't linked to any user
+      // accounts (by email or provider account id)...
+      //
+      // If no account matching the same [provider].id or .email exists, we can
+      // create a new account for the user, link it to the OAuth account and
+      // create a new session for them so they are signed in with it.
+      user = await createUser({ ...profile, emailVerified: null })
+      isNewUser = true
+    }
+    await events.createUser?.({ user })
+
+    await linkAccount({ ...account, userId: user.id })
+    await events.linkAccount?.({ user, account, profile })
+
+    session = useJwtSession
+      ? {}
+      : await createSession({
+          sessionToken: generateSessionToken(),
+          userId: user.id,
+          expires: fromDate(options.session.maxAge),
+        })
+
+    return { session, user, isNewUser }
+  }
+}