🔐 Authentication Route Blocks

Authentication route blocks provide pre-configured HTTP endpoints for user authentication and authorization operations in NodeBlocks applications. These routes combine blocks (pure business logic functions), handlers, validators, and middleware to create complete API endpoints for login, registration, token management, and email verification.

---

🎯 Overview

Authentication route blocks are designed to:

• Provide complete API endpoints for user authentication operations
• Combine blocks and handlers with validators for secure operations
• Include authentication and authorization checks
• Support functional composition patterns
• Handle logging and error management automatically

---

📋 Route Structure

Each authentication route follows a consistent pattern:

• HTTP Method: Defines the operation type (GET, POST, PATCH, DELETE)
• Path: Specifies the endpoint URL with parameters
• Handler: Composed function chain using blocks and handlers
• Validators: Authentication and authorization checks

---

🔧 Available Authentication Routes

registerCredentialsRoute

Registers new user credentials with optional invitation processing.

Purpose: Handles user registration with support for invitation acceptance

Route Details:

• Method: POST
• Path: /auth/register
• Authentication: Not required

Handlers:

• With invitation token: buildCheckInvitationTokenPayload, checkToken, getInvitationIdFromTokenInfo, getInvitationById, isPendingInvitation, registerCredentials, buildAcceptInvitationPayload, updateInvitation
• Without token: registerCredentials
• Finally: registerTerminator

Validators: None

Usage:

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

// Register route with Express app
app.use('/api', routes.registerCredentialsRoute);

Note: For invitation-specific functionality, see Invitation Blocks.

---

loginWithCredentialsRoute

Authenticates user credentials and generates access/refresh tokens.

Purpose: Handles user login with credential validation

Route Details:

• Method: POST
• Path: /auth/login
• Authentication: Not required

Handlers: loginWithCredentials, createAccessToken, createRefreshToken, setResponseCookie, loginTerminator

Validators: None

Usage:

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

// Register route with Express app
app.use('/api', routes.loginWithCredentialsRoute);

---

logoutRoute

Logs out user by invalidating their session and clearing tokens.

Purpose: Handles user logout and session cleanup

Route Details:

• Method: POST
• Path: /auth/logout
• Authentication: Required (Bearer token)

Handlers: logout, logoutTerminator

Validators: isAuthenticated

Usage:

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

// Register route with Express app
app.use('/api', routes.logoutRoute);

---

refreshTokenRoute

Refreshes access token using a valid refresh token.

Purpose: Generates new access token from refresh token

Route Details:

• Method: POST
• Path: /auth/token/refresh
• Authentication: Not required

Handlers: refreshToken

Validators: None

Usage:

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

// Register route with Express app
app.use('/api', routes.refreshTokenRoute);

---

checkTokenRoute

Validates an access token and returns its status.

Purpose: Validates token authenticity and status

Route Details:

• Method: POST
• Path: /auth/token/check
• Authentication: Not required

Blocks: checkToken - Validates token using pure business logic

Validators: None

Usage:

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

// Register route with Express app
app.use('/api', routes.checkTokenRoute);

---

deleteRefreshTokensRoute

Deletes refresh tokens for a specific identity via DELETE /auth/:identityId/refresh-tokens.

Purpose: Removes refresh tokens for identity management and security

Route Details:

• Method: DELETE
• Path: /auth/:identityId/refresh-tokens
• Authentication: Required (Bearer token)

Blocks: softDeleteRefreshTokens - Soft-deletes refresh tokens for identity

Validators: isAuthenticated, some(checkIdentityType(['admin']), isSelf(['params', 'requestBody', 'identityId']))

Usage:

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

// Register route with Express app
app.use('/api', routes.deleteRefreshTokensRoute);

---

loginWithOnetimeTokenRoute

Authenticates a user using a one-time token and returns access credentials.

Purpose: Handles OTT-based authentication

Route Details:

• Method: GET
• Path: /auth/ott/login
• Authentication: Not required

Handlers: loginWithOnetimeToken

Validators: None

Usage:

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

// Register route with Express app
app.use('/api', routes.loginWithOnetimeTokenRoute);

---

generateOnetimeTokenRoute

Generates a new one-time token for authentication purposes.

Purpose: Creates OTT for authentication (admin only)

Route Details:

• Method: POST
• Path: /auth/ott/generate
• Authentication: Required (Bearer token)

Handlers: generateOnetimeToken

Validators: isAuthenticated, checkIdentityType(['admin'])

Usage:

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

// Register route with Express app
app.use('/api', routes.generateOnetimeTokenRoute);

---

restoreOnetimeTokenRoute

Restores a previously invalidated one-time token.

Purpose: Re-enables invalidated OTT (admin only)

Route Details:

• Method: POST
• Path: /auth/ott/restore
• Authentication: Required (Bearer token)

Handlers: restoreOnetimeToken

Validators: isAuthenticated, checkIdentityType(['admin'])

Usage:

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

// Register route with Express app
app.use('/api', routes.restoreOnetimeTokenRoute);

---

invalidateOnetimeTokenRoute

Invalidates an existing one-time token.

Purpose: Disables active OTT (admin only)

Route Details:

• Method: POST
• Path: /auth/ott/invalidate
• Authentication: Required (Bearer token)

Handlers: invalidateOnetimeToken

Validators: isAuthenticated, checkIdentityType(['admin'])

Usage:

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

// Register route with Express app
app.use('/api', routes.invalidateOnetimeTokenRoute);

---

sendVerificationEmailRoute

Sends verification emails to users.

Purpose: Triggers email verification process

Route Details:

• Method: POST
• Path: /auth/:identityId/send-verification-email
• Authentication: Required (Bearer token)

Handlers: sendVerificationEmail, sendVerificationEmailTerminator

Validators: isAuthenticated, some(checkIdentityType(['admin']), isSelf(['params', 'requestParams', 'identityId']))

Usage:

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

// Register route with Express app
app.use('/api', routes.sendVerificationEmailRoute);

---

confirmEmailRoute

Confirms user email addresses using verification tokens.

Purpose: Processes email verification tokens

Route Details:

• Method: POST
• Path: /auth/confirm-email
• Authentication: Not required

Handlers: buildCheckConfirmEmailTokenPayload, checkToken, confirmEmail, confirmEmailTerminator

Validators: None

Usage:

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

// Register route with Express app
app.use('/api', routes.confirmEmailRoute);

---

changeEmailRoute

Initiates the email change process for a user by sending a verification email to the new address.

Purpose: Handles email change initiation with token generation and email sending

Route Details:

• Method: PATCH
• Path: /auth/:identityId/change-email
• Authentication: Required (Bearer token)

Blocks:

• assertIdentityExists - Verifies identity exists
• checkEmailIsUniqueInIdentities - Validates email uniqueness
• getFingerprint - Extracts request fingerprint
• buildTokenVerification - Builds security context
• generateOneTimeToken - Generates secure token
• storeOneTimeToken - Stores token in database
• sendEmail - Sends verification email
• normalizeEmptyBody - Normalizes response

Validators: isAuthenticated, some(checkIdentityType(['admin']), isSelf(['params', 'requestParams', 'identityId']))

Usage:

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

// Register route with Express app
app.use('/api', routes.changeEmailRoute);

---

confirmNewEmailRoute

Confirms a user's new email address using a one-time verification token.

Purpose: Processes email change confirmation with token validation

Route Details:

• Method: POST
• Path: /auth/confirm-new-email
• Authentication: Not required

Blocks:

• getFingerprint - Extracts request fingerprint
• buildTokenVerification - Builds security context
• checkOneTimeToken - Validates token
• assertValidOneTimeTokenExists - Verifies token exists
• invalidateOneTimeToken - Marks token as used
• checkEmailIsUniqueInIdentities - Validates email uniqueness
• isEmail - Validates email format
• buildUpdateIdentityEmailAndEmailVerifiedPayload - Builds update payload
• updateIdentity - Updates user identity
• normalizeEmptyBody - Normalizes response

Validators: None

Usage:

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

// Register route with Express app
app.use('/api', routes.confirmNewEmailRoute);

---

sendResetPasswordLinkEmailRoute

Sends a password reset link email to a user based on their email address.

Purpose: Handles password reset email generation and sending

Route Details:

• Method: POST
• Path: /auth/send-reset-password-link-email
• Authentication: Not required

Blocks:

• getIdentityIdByEmail - Retrieves identity by email
• getFingerprint - Extracts request fingerprint
• buildTokenVerification - Builds security context
• generateOneTimeToken - Generates secure token
• storeOneTimeToken - Stores token in database
• sendEmail - Sends password reset email
• normalizeEmptyBody - Normalizes response

Validators: None

Usage:

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

// Register route with Express app
app.use('/api', routes.sendResetPasswordLinkEmailRoute);

---

changePasswordRoute

Changes user password via PATCH /auth/:identityId/change-password.

Purpose: Handles password change with current password verification and new password hashing

Route Details:

• Method: PATCH
• Path: /auth/:identityId/change-password
• Authentication: Required (Bearer token)

Blocks:

• getIdentityById - Retrieves the identity by ID
• compareStringAgainstHash - Verifies the current password
• hash - Hashes the new password
• buildUpdateIdentityPasswordPayload - Builds the update payload
• updateIdentity - Updates the identity password in the database
• sendEmail - Sends a notification email
• normalizeEmptyBody - Normalizes the response body
• orThrow - Throws mapped errors or returns the normalized identity

Validators: isAuthenticated, some(checkIdentityType(['admin']), isSelf(['params', 'requestParams', 'identityId']))

Usage:

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

// Use in feature composition:
export const changePasswordFeature = compose(changePasswordSchema, changePasswordRoute);

// Register route with Express app
app.use('/api', routes.changePasswordRoute);

---

activateRoute

Activates a user account via POST /auth/activate.

Purpose: Handles account activation with email verification and identity status update

Route Details:

• Method: POST
• Path: /auth/activate
• Authentication: Required (Bearer token)

Blocks:

• getIdentityById - Retrieves identity by ID
• isEmailVerified - Checks if email is verified
• buildUpdateIdentityActivatedPayload - Builds activation payload
• updateIdentity - Updates identity as activated
• normalizeEmptyBody - Normalizes response body
• orThrow - Throws mapped errors or returns 204 No Content

Validators: isAuthenticated, checkIdentityType(['admin'])

Usage:

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

// Use in feature composition:
export const activateFeature = compose(activateSchema, activateRoute);

// Register route with Express app
app.use('/api', routes.activateRoute);

---

deactivateRoute

Deactivates a user identity via POST /auth/deactivate.

Purpose: Handles account deactivation with email verification, identity status update, and token invalidation

Route Details:

• Method: POST
• Path: /auth/deactivate
• Authentication: Required (Bearer token)

Blocks:

• getIdentityById - Retrieves identity by ID
• isEmailVerified - Checks if email is verified
• buildUpdateIdentityDeactivatedPayload - Builds deactivation payload
• updateIdentity - Updates identity as deactivated
• softDeleteRefreshTokens - Soft-deletes refresh tokens for identity
• extractTokenFromAuthorizationHeader - Extracts Bearer token from request
• checkToken - Validates access token and user permissions
• sendEmail - Sends deactivation notification email
• normalizeEmptyBody - Normalizes response body
• orThrow - Throws mapped errors or returns 204 No Content

Validators: isAuthenticated, some(checkIdentityType(['admin']), isSelf(['params', 'requestParams', 'identityId']))

Usage:

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

// Use in feature composition:
export const deactivateFeature = compose(deactivateSchema, routes.deactivateRoute);

// Register route with Express app
app.use('/api', routes.deactivateRoute);

---

completePasswordResetRoute

Completes the password reset process by validating the token and updating the user's password.

Purpose: Handles password reset completion with token validation and password update

Route Details:

• Method: POST
• Path: /auth/reset-password
• Authentication: Not required

Blocks:

• getResetPasswordTokenTarget - Gets reset password token target
• getFingerprint - Extracts request fingerprint
• buildTokenVerification - Builds security context
• extractTokenFromAuthorizationHeader - Extracts Bearer token from request
• checkOneTimeToken - Validates one-time token
• assertValidOneTimeTokenExists - Verifies token exists in database
• invalidateOneTimeToken - Marks token as used
• hash - Hashes the new password
• buildUpdateIdentityPasswordPayload - Builds password update payload
• updateIdentity - Updates user identity with new password
• getIdentityById - Retrieves updated identity
• sendEmail - Sends password reset success email
• normalizeEmptyBody - Normalizes response body
• orThrow - Throws mapped errors or returns 204 No Content

Validators: None

Usage:

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

// Route registration:
app.use('/api', routes.completePasswordResetRoute);

// POST /auth/reset-password
// Headers:
//   Authorization: Bearer <one-time-token>
// Request body:
// {
//   "password": "newStrongPassword123"
// }
// Response: 204 No Content (success)

---