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.

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.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 })
}