⚙️ Authentication Handler Blocks

Authentication handler blocks provide core business logic functions for user authentication and authorization operations in Nodeblocks applications. These handlers encapsulate common patterns for login, registration, token management, and email verification.

---

🎯 Overview

Authentication handler blocks are designed to:

• Handle user authentication with credentials and tokens
• Manage user registration with validation and security
• Process token operations including creation, refresh, and validation
• Support email verification workflows
• Ensure security with proper token validation and fingerprinting

---

📋 Authentication Handler Types

Authentication Async Handlers

Functions that perform asynchronous authentication operations (database calls, token generation, etc.).

Authentication Sync Handlers

Functions that perform synchronous authentication operations (token validation, response formatting, etc.).

Authentication Terminator Handlers

Functions that format and return the final authentication response.

---

🔧 Available Authentication Handlers

loginWithCredentials

Authenticates a user with email and password credentials.

Purpose: Handles user login with credential validation and account security

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • params.requestBody.email or context.data.email: User email
  • params.requestBody.password or context.data.password: User password
  • context.db: Database connection
  • context.configuration.maxFailedLoginAttempts: Maximum failed attempts (default: 5)

Returns: Result<RouteHandlerPayload, Error> - Success with identity or error

Payload Requirements:

• Email and password must be provided in request body or context data
• context.db must be available for database operations
• context.configuration should contain maxFailedLoginAttempts setting

Key Features:

• Validates email and password are provided
• Checks user identity exists in database
• Compares password hash for authentication
• Handles account locking after failed attempts
• Resets failed attempts on successful login
• Returns identity data on success
• Handles database errors gracefully

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { loginWithCredentials } = handlers;

// Use in composition
const authPipeline = compose(loginWithCredentials, createAccessToken, createRefreshToken, setResponseCookie, loginTerminator);

---

createAccessToken

Generates a user access token for authenticated sessions.

Purpose: Creates secure access tokens with fingerprint validation

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • params.requestBody.fingerprint or context.data.fingerprint: Security fingerprint
  • params.requestBody.id or context.data.id or context.identity.id: User ID
  • context.request: Express request object
  • context.configuration.authSecrets: Authentication secrets
  • context.configuration.jwtOpts: JWT options

Returns: Result<RouteHandlerPayload, Error> - Success with accessToken or error

Payload Requirements:

• User ID must be available from request body, context data, or identity
• context.request must contain IP and headers for token verification
• context.configuration.authSecrets and jwtOpts must be available

Key Features:

• Extracts user ID from multiple sources (request body, context data, identity)
• Builds token verification with domain, fingerprint, IP, and user agent
• Generates secure user access token with JWT
• Returns access token on success
• Handles token generation errors gracefully

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { createAccessToken } = handlers;

// Use in composition
const authPipeline = compose(loginWithCredentials, createAccessToken, createRefreshToken, setResponseCookie, loginTerminator);

---

createRefreshToken

Generates a refresh token for token renewal.

Purpose: Creates secure refresh tokens with database storage

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • params.requestBody.fingerprint or context.data.fingerprint: Security fingerprint
  • params.requestBody.id or context.data.id or context.identity.id: User ID
  • context.request: Express request object
  • context.db: Database connection
  • context.configuration.authSecrets: Authentication secrets
  • context.configuration.refreshTokenOpts: Refresh token options
  • context.configuration.refreshTokenExpireTime: Refresh token expiration

Returns: Result<RouteHandlerPayload, Error> - Success with refreshToken or error

Payload Requirements:

• User ID must be available from request body, context data, or identity
• context.request must contain IP and headers for token verification
• context.db must be available for token storage
• context.configuration must contain auth secrets and refresh token options

Key Features:

• Extracts user ID and fingerprint from multiple sources
• Builds token verification with domain, fingerprint, IP, and user agent
• Generates secure refresh token with JWT
• Stores token in database with expiration
• Returns refresh token on success
• Handles token generation and storage errors

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { createRefreshToken } = handlers;

// Use in composition
const authPipeline = compose(loginWithCredentials, createAccessToken, createRefreshToken, setResponseCookie, loginTerminator);

---

setResponseCookie

Sets authentication cookies in the HTTP response.

Purpose: Configures secure cookies for access and refresh tokens

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • context.response: Express response object
  • context.cookieOpts: Cookie configuration options
  • context.data.accessToken: Access token to set in cookie
  • context.data.refreshToken: Refresh token to set in cookie

Returns: Result<RouteHandlerPayload, Error> - Success with updated payload or error

Payload Requirements:

• context.response must be available for cookie setting
• context.cookieOpts should contain cookie configuration
• Access and/or refresh tokens should be available in context data

Key Features:

• Validates response object is available
• Sets Access-Control-Allow-Credentials header
• Configures secure cookies for access token
• Configures secure cookies for refresh token
• Uses provided cookie options for security
• Returns updated payload on success

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { setResponseCookie } = handlers;

// Use in composition
const authPipeline = compose(loginWithCredentials, createAccessToken, createRefreshToken, setResponseCookie, loginTerminator);

---

registerCredentials

Registers a new user with email and password.

Purpose: Handles user registration with validation and password hashing

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • params.requestBody.email: User email address
  • params.requestBody.password: User password
  • context.data.invitation.email: Email from invitation (optional)
  • context.db: Database connection

Returns: Result<RouteHandlerPayload, Error> - Success with identity or error

Payload Requirements:

• Email and password must be provided in request body
• context.db must be available for database operations

Key Features:

• Validates email and password are provided
• Checks for existing identity to prevent duplicates
• Hashes password securely before storage
• Creates base entity with timestamps and ID
• Inserts new identity into database
• Returns identity data on success
• Handles database errors gracefully

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { registerCredentials } = handlers;

// Use in composition
const authPipeline = compose(registerCredentials, registerTerminator);

---

refreshToken

Refreshes an access token using a valid refresh token.

Purpose: Rotates tokens and generates new access/refresh token pair

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • params.requestBody.fingerprint or context.data.fingerprint or context.fingerprint: Security fingerprint
  • context.request: Express request object with cookies and body
  • context.db: Database connection
  • context.configuration.authSecrets: Authentication secrets
  • context.configuration.jwtOpts: JWT options

Returns: Result<RouteHandlerPayload, Error> - Success with new tokens or error

Payload Requirements:

• context.request must contain refresh token in cookies or body
• context.db must be available for token invalidation
• context.configuration must contain auth secrets and JWT options

Key Features:

• Extracts fingerprint from multiple sources
• Validates refresh token from cookies and body
• Compares cookie and body tokens for consistency
• Invalidates old refresh token in database
• Generates new access and refresh tokens
• Returns new token pair on success
• Handles token validation and generation errors

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { refreshToken } = handlers;

// Use in composition
const authPipeline = compose(refreshToken, setResponseCookie, loginTerminator);

---

logout

Logs out a user by invalidating refresh tokens and clearing cookies.

Purpose: Handles secure user logout with token cleanup

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • context.request: Express request object with cookies
  • context.response: Express response object
  • context.db: Database connection
  • context.configuration.authSecrets: Authentication secrets

Returns: Result<RouteHandlerPayload, Error> - Success with updated payload or error

Payload Requirements:

• context.request must contain refresh token in cookies
• context.response must be available for cookie clearing
• context.db must be available for token invalidation
• context.configuration.authSecrets must be available

Key Features:

• Extracts refresh token from cookies
• Validates and decrypts refresh token
• Invalidates token in database with deletion timestamp
• Clears access and refresh token cookies
• Returns updated payload on success
• Handles token validation and cleanup errors

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { logout } = handlers;

// Use in composition
const authPipeline = compose(logout, logoutTerminator);

---

checkToken

Validates and processes authentication tokens.

Purpose: Verifies token authenticity and extracts user information

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • params.requestBody.token: Token to validate
  • context.data.checkToken.target: Token target (optional)
  • context.request: Express request object
  • context.db: Database connection for onetime tokens
  • context.configuration.authSecrets: Authentication secrets

Returns: Result<RouteHandlerPayload, Error> - Success with token info or error

Payload Requirements:

• Token must be provided in request body
• context.request must be available for request info extraction
• context.db must be available for onetime token validation
• context.configuration.authSecrets must be available

Key Features:

• Extracts token and fingerprint from request
• Validates token using JWT verification
• Handles both user access tokens and onetime tokens
• Performs security checks for access tokens
• Validates onetime token target and state
• Invalidates onetime tokens after use
• Returns token info or user ID on success
• Handles token validation errors gracefully

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { checkToken } = handlers;

// Use in composition
const authPipeline = compose(checkToken, someOtherHandler);

---

deleteToken

Deletes user tokens and invalidates sessions.

Purpose: Handles token deletion with security validation

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • context.data.id or params.requestBody.id or params.requestQuery.id: User ID to delete tokens for
  • context.request: Express request object with cookies and headers
  • context.db: Database connection
  • context.configuration.authSecrets: Authentication secrets

Returns: Result<RouteHandlerPayload, Error> - Success with updated payload or error

Payload Requirements:

• User ID must be provided in context data, request body, or query params
• context.request must be available for token extraction
• context.db must be available for token invalidation
• context.configuration.authSecrets must be available

Key Features:

• Extracts user ID from multiple sources
• Validates tokens from cookies and bearer headers
• Compares cookie and bearer tokens for consistency
• Handles app access token super permissions
• Validates user can only delete their own tokens
• Invalidates tokens in database with deletion timestamp
• Returns updated payload on success
• Handles token validation and deletion errors

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { deleteToken } = handlers;

// Use in composition
const authPipeline = compose(deleteToken, someTerminator);

---

loginWithOnetimeToken

Authenticates a user using a one-time token.

Purpose: Handles authentication with temporary one-time tokens

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • params.requestBody.onetimeToken: One-time token for authentication
  • context.db: Database connection
  • context.configuration.authSecrets: Authentication secrets

Returns: Result<RouteHandlerPayload, Error> - Success with updated payload or error

Payload Requirements:

• One-time token must be provided in request body
• context.db must be available for token validation
• context.configuration.authSecrets must be available

Key Features:

• Validates onetime token from request body
• Decrypts and verifies token using JWT
• Validates token type is 'onetime'
• Checks token exists and is valid in database
• Invalidates token after successful use
• Validates token purpose is 'onetime-login'
• Returns updated payload on success
• Handles token validation and database errors

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { loginWithOnetimeToken } = handlers;

// Use in composition
const authPipeline = compose(loginWithOnetimeToken, createAccessToken, createRefreshToken, setResponseCookie, loginTerminator);

---

generateOnetimeToken

Generates a one-time token for temporary access.

Purpose: Creates secure one-time tokens with database storage

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • params.requestBody.fingerprint or context.data.fingerprint or context.fingerprint: Security fingerprint
  • params.requestBody.target or context.data.target or context.target: Token target
  • params.requestBody.tokenData or context.data.tokenData or context.tokenData: Token data object
  • context.request: Express request object
  • context.db: Database connection
  • context.configuration.authSecrets: Authentication secrets

Returns: Result<RouteHandlerPayload, Error> - Success with generated token or error

Payload Requirements:

• Token data must be provided as an object
• context.request must be available for request info
• context.db must be available for token storage
• context.configuration.authSecrets must be available

Key Features:

• Validates token data is provided as object
• Extracts fingerprint, target, and token data from multiple sources
• Builds token verification with domain, fingerprint, IP, and target
• Generates secure onetime token with JWT
• Stores token in database with invalidation flag
• Returns generated token on success
• Handles token generation and storage errors

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { generateOnetimeToken } = handlers;

// Use in composition
const authPipeline = compose(generateOnetimeToken, someTerminator);

---

restoreOnetimeToken

Restores a previously invalidated one-time token.

Purpose: Re-enables a one-time token for reuse

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • params.requestBody.token: Token to restore
  • context.db: Database connection
  • context.configuration.authSecrets: Authentication secrets

Returns: Result<RouteHandlerPayload, Error> - Success with restored token or error

Payload Requirements:

• Token must be provided in request body
• context.db must be available for token updates
• context.configuration.authSecrets must be available

Key Features:

• Validates token is provided in request body
• Decrypts and verifies token using JWT
• Validates token is stateful (onetime token)
• Updates token invalidation status in database
• Returns restored token on success
• Handles token validation and database errors

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { restoreOnetimeToken } = handlers;

// Use in composition
const authPipeline = compose(restoreOnetimeToken, someTerminator);

---

invalidateOnetimeToken

Invalidates a one-time token.

Purpose: Disables a one-time token permanently

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • params.requestBody.token or context.data.token or context.token: Token to invalidate
  • params.requestBody.fingerprint or context.data.fingerprint or context.fingerprint: Security fingerprint
  • context.db: Database connection
  • context.configuration.authSecrets: Authentication secrets

Returns: Result<RouteHandlerPayload, Error> - Success with invalidated token or error

Payload Requirements:

• Token and fingerprint must be provided
• context.db must be available for token updates
• context.configuration.authSecrets must be available

Key Features:

• Validates token and fingerprint are provided
• Decrypts and verifies token using JWT
• Validates token is stateful (onetime token)
• Updates token invalidation status in database
• Returns invalidated token on success
• Handles token validation and database errors

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { invalidateOnetimeToken } = handlers;

// Use in composition
const authPipeline = compose(invalidateOnetimeToken, someTerminator);

---

confirmEmail

Confirms a user's email address using a verification token.

Purpose: Verifies email addresses through token validation

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • context.data.tokenInfo.userId: User ID from token
  • context.db: Database connection

Returns: Result<RouteHandlerPayload, Error> - Success with confirmation result or error

Payload Requirements:

• User ID must be available in context.data.tokenInfo.userId
• context.db must be available for user updates

Key Features:

• Extracts user ID from token info in context
• Validates user ID is a string
• Updates user's email verification status in database
• Checks if user exists before updating
• Validates email was not already verified
• Returns confirmation result on success
• Handles database errors gracefully

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { confirmEmail } = handlers;

// Use in composition
const authPipeline = compose(checkToken, confirmEmail, confirmEmailTerminator);

---

buildCheckConfirmEmailTokenPayload

Builds payload for email confirmation token validation.

Purpose: Configures token validation for email confirmation workflow

Parameters:

• payload: RouteHandlerPayload - Contains request context and data

Returns: Result<RouteHandlerPayload, Error> - Success with checkToken configuration

Payload Requirements:

• No specific requirements - this handler always succeeds

Key Features:

• Merges checkToken configuration with email confirmation target
• Sets target to TARGET_CONFIRM_EMAIL constant
• Always succeeds (no error conditions)
• Returns updated payload with checkToken configuration
• Used as preparation step for email confirmation workflow

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { buildCheckConfirmEmailTokenPayload } = handlers;

// Use in composition
const authPipeline = compose(buildCheckConfirmEmailTokenPayload, checkToken, confirmEmail, confirmEmailTerminator);

---

sendVerificationEmail

Sends a verification email to a user's email address.

Purpose: Initiates email verification workflow with token generation

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • context.data.userId or params.requestParams.userId or context.data.identity.id: User ID
  • params.requestBody.fingerprint or context.data.fingerprint: Security fingerprint
  • context.db: Database connection
  • context.mailService: Mail service for sending emails
  • context.configuration.verifyEmailConfig: Email verification configuration
  • context.configuration.authSecrets: Authentication secrets
  • context.configuration.jwtOpts: JWT options

Returns: Result<RouteHandlerPayload, Error> - Success with email result and token or error

Payload Requirements:

• User ID must be provided
• context.db must be available for user lookup and token storage
• context.mailService must be available for email sending
• context.configuration.verifyEmailConfig must be enabled and configured
• context.configuration.authSecrets and jwtOpts must be available

Key Features:

• Validates user ID is provided from multiple sources
• Checks email verification feature is enabled in configuration
• Validates mail service is available
• Validates email configuration (bodyTemplate, subject, urlTemplate)
• Retrieves user from database and validates email exists
• Generates secure onetime verification token
• Stores token in database with invalidation flag
• Sends verification email using mail service
• Returns email result and token on success
• Handles configuration and email sending errors

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { sendVerificationEmail } = handlers;

// Use in composition
const authPipeline = compose(sendVerificationEmail, sendVerificationEmailTerminator);

---

🎯 Authentication Terminator Handlers

loginTerminator

Terminates login process with proper response formatting.

Purpose: Formats successful login response with tokens and user info

Parameters:

• result: Result<RouteHandlerPayload, Error> - Result containing payload or error
  • context.data.accessToken: Access token from previous handlers
  • context.data.refreshToken: Refresh token from previous handlers
  • context.data.identity: User identity information

Returns: Formatted login response object

Payload Requirements:

• context.data.accessToken, refreshToken, and identity must be available from previous handlers

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { loginTerminator } = handlers;

// Use in composition
const authPipeline = compose(loginWithCredentials, createAccessToken, createRefreshToken, setResponseCookie, loginTerminator);

---

logoutTerminator

Terminates logout process with proper status code.

Purpose: Formats successful logout response with 204 status

Parameters:

• result: Result<RouteHandlerPayload, Error> - Result containing payload or error

Returns: Response object with 204 statusCode

Payload Requirements:

• No specific requirements - this terminator always returns 204

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { logoutTerminator } = handlers;

// Use in composition
const authPipeline = compose(logout, logoutTerminator);

---

registerTerminator

Terminates registration process with proper response formatting.

Purpose: Formats successful registration response with user info

Parameters:

• result: Result<RouteHandlerPayload, Error> - Result containing payload or error
  • context.data.email: User email from previous handler
  • context.data.id: User ID from previous handler

Returns: Formatted registration response object

Payload Requirements:

• context.data.email and id must be available from previous handler

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { registerTerminator } = handlers;

// Use in composition
const authPipeline = compose(registerCredentials, registerTerminator);

---

confirmEmailTerminator

Terminates email confirmation process with proper status code.

Purpose: Formats successful email confirmation response with 204 status

Parameters:

• result: Result<RouteHandlerPayload, Error> - Result containing payload or error
  • context.data.confirmEmail: Confirmation result from previous handler

Returns: Response object with 204 statusCode

Payload Requirements:

• context.data.confirmEmail must be available from previous handler

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { confirmEmailTerminator } = handlers;

// Use in composition
const authPipeline = compose(checkToken, confirmEmail, confirmEmailTerminator);

---

sendVerificationEmailTerminator

Terminates email sending process with proper status code.

Purpose: Formats successful email sending response with 204 status

Parameters:

• result: Result<RouteHandlerPayload, Error> - Result containing payload or error
  • context.data.sendVerificationEmail: Email sending result from previous handler
  • context.data.token: Generated token from previous handler

Returns: Response object with 204 statusCode

Payload Requirements:

• context.data.sendVerificationEmail and token must be available from previous handler

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { sendVerificationEmailTerminator } = handlers;

// Use in composition
const authPipeline = compose(sendVerificationEmail, sendVerificationEmailTerminator);

---