Auth Hooks & Utilities

useSession()

useSession(options?) => Partial<PublicData> & {isLoading: boolean}

Example

import { useSession } from "blitz"

const session = useSession()

Arguments

• options:
  • Optional
  • initialPublicData: PublicData - Use this with SSR to set public data from the server session
  • suspense: boolean - Defaults to true

Returns

• session: Partial<PublicData> & {isLoading: boolean}

useAuthenticatedSession()

useAuthenticatedSession(options?) => PublicData & {isLoading: boolean}

This will throw AuthenticationError if the user is not logged in

Example

import { useAuthenticatedSession } from "blitz"

const session = useAuthenticatedSession()

Arguments

• options:
  • Optional
  • initialPublicData: PublicData - Use this with SSR to set public data from the server session
  • suspense: boolean - Defaults to true

Returns

• session: PublicData & {isLoading: boolean}

useAuthorize()

useAuthorize() => void

This will throw AuthenticationError if the user is not logged in

Example

import { useAuthorize } from "blitz"

useAuthorize()

Arguments

• None

Returns

• Nothing

useRedirectAuthenticated()

useRedirectAuthenticated(to: string) => void

This will redirect a logged in user to the given url path. It does nothing for logged out users.

Example

import { useRedirectAuthenticated } from "blitz"

useRedirectAuthenticated("/dashboard")

Arguments

• to: string
  • Required
  • The url path to redirect logged in users to

Returns

• Nothing

generateToken()

generateToken(numberOfCharacters: number = 32) => string

This is a convenience wrapper around nanoid for generating tokens for things like password resets.

Example Usage

import { generateToken } from "blitz"

const token = generateToken()

hash256()

hash256(value: string) => string

This is a convenience wrapper that uses the node crypto module to hash a string with the sha256 algorithm. It is used for things like hashing password reset tokens before saving them in the database.

Hash256 is also useful for storing strings like API keys in the database because the returned hash will always be the same for a given string. Therefore, you can still verify that an API key exists in the database when the only value you have to reference is the hashed key.

Example Usage

import { hash256 } from "blitz"

const hashedToken = hash256(token)

SecurePassword

SecurePassword is a convenience wrapper around secure-password to provide a nice way to hash passwords and verify password hashes.

import { SecurePassword } from "blitz"

await SecurePassword.hash(password)
await SecurePassword.verify(passwordHash, password)

SecurePassword.hash(password: string) => Promise<string>

This is used when a user sets a new password.

It takes a password string and returns a secure hash for storing in your database.

SecurePassword.hash will return a different hash when given the same string, hence the necessity of SecurePassword.verify to compare hashs.

SecurePassword.verify(passwordHash: string, password: string) => Promise<ResultCode>

This is used when a user logs in to verify they used the correct password.

It takes a password hash from your database and the given password. It will verify the given password is correct and return a result code, or if incorrect, it will throw AuthenticationError.

Result Codes

SecurePassword.VALID

The password was verified and is valid

SecurePassword.VALID_NEEDS_REHASH

The password was verified and is valid, but needs to be rehashed with new parameters

SecurePassword.HASH_BYTES

Size of the hash Buffer returned by hash and hashSync and used by verify and verifySync.

Example Usage

import { SecurePassword, AuthenticationError } from "blitz"
import db from "db"

export const authenticateUser = async (
  email: string,
  password: string
) => {
  const user = await db.user.findFirst({ where: { email } })
  if (!user) throw new AuthenticationError()

  const result = await SecurePassword.verify(
    user.hashedPassword,
    password
  )

  if (result === SecurePassword.VALID_NEEDS_REHASH) {
    // Upgrade hashed password with a more secure hash
    const improvedHash = await SecurePassword.hash(password)
    await db.user.update({
      where: { id: user.id },
      data: { hashedPassword: improvedHash },
    })
  }

  const { hashedPassword, ...rest } = user
  return rest
}

setPublicDataForUser()

setPublicDataForUser(userId: PublicData['userId'], publicData: Record<any, any>) => void

This can be used to update the publicData of a user's sessions. It can be useful when changing a user's role, since the new permissions can be enforced as soon as the user is doing the next request.

Example Usage

import { setPublicDataForUser } from "blitz"
import db from "db"

export const updateUserRole = async (
  userId: PublicData["userId"],
  role: string
) => {
  // update the user's role
  await db.user.update({ where: { id: userId }, data: { role } })
  // update role in all active sessions
  await setPublicDataForUser(userId, { role })
}