Skip to main content
Version: 🚧 Canary

🔐 Authentication Utilities

The Nodeblocks SDK provides comprehensive authentication utilities for token management, validation, and security. These utilities handle bearer tokens, cookie-based authentication, and various token types for different use cases.

🎯 Overview​

Authentication utilities provide secure token generation, validation, and management for both user and application authentication. They support multiple token types and security validation mechanisms.

Key Features​

  • Multiple Token Types: User access, app access, refresh, and one-time tokens
  • Security Validation: Fingerprint, IP, and user agent validation
  • Flexible Authentication: Bearer token and cookie-based authentication
  • JWT Integration: JSON Web Token signing and verification

🔑 Token Generation​

generateUserAccessToken​

Creates encrypted user access tokens with security validation metadata.

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

const { generateUserAccessToken } = utils;

const token = generateUserAccessToken(
  authSecrets,
  { jwtSignOptions: { expiresIn: '24h' }, stateful: true },
  identityId,
  {
    fingerprint: 'device-fingerprint',
    ip: '192.168.1.1',
    domain: 'example.com',
    userAgent: 'Mozilla/5.0...'
  }
);

Parameters:

  • authSecrets: Authentication secrets for encryption/signing
  • opts: JWT options and stateful configuration
  • identityId: Identity identifier
  • tokenVerification: Security context for validation

generateAppAccessToken​

Creates encrypted app access tokens for service-to-service communication.

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

const { generateAppAccessToken } = utils;

const token = generateAppAccessToken(authSecrets, 'app-service-id');

Parameters:

  • authSecrets: Authentication secrets
  • appId: Application identifier

generateRefreshToken​

Creates encrypted refresh tokens for session management.

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

const { generateRefreshToken } = utils;

const token = generateRefreshToken(
  authSecrets,
  'jwt-token-id',
  identityId,
  {
    fingerprint: 'device-fingerprint',
    ip: '192.168.1.1',
    domain: 'example.com',
    userAgent: 'Mozilla/5.0...'
  },
  { jwtSignOptions: { expiresIn: '7d' } }
);

generateOnetimeToken​

Creates one-time tokens for temporary access.

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

const { generateOnetimeToken } = utils;

const token = generateOnetimeToken(
  authSecrets,
  { identityId: 'id-123', action: 'password-reset' },
  {
    fingerprint: 'device-fingerprint',
    ip: '192.168.1.1',
    domain: 'example.com',
    userAgent: 'Mozilla/5.0...'
  },
  { expiresIn: '1h' }
);

🔍 Token Validation​

getBearerTokenInfo​

Extracts token information from request authorization header. Default authentication function for bearer tokens.

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

const { getBearerTokenInfo } = utils;

const tokenInfo = await getBearerTokenInfo(payload);

Process:

  1. Extracts token from Authorization: Bearer <token> header
  2. Decrypts and verifies JWT signature
  3. Validates token type (user or app)
  4. Performs security checks for user tokens
  5. Returns token information

getCookieTokenInfo​

Extracts token information from the cookies. Authentication function for cookie-based tokens.

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

const { getCookieTokenInfo } = utils;

const tokenInfo = await getCookieTokenInfo(payload);

Use cases:

  • Web applications with cookie-based authentication
  • Different security validation rules (IP checks disabled)
  • Server-side session management

defaultRefreshTokenBodyAuth​

Default authentication function for refresh tokens fetched from the request body. Validates refresh tokens sent in the request body along with fingerprint validation.

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

const { defaultRefreshTokenBodyAuth } = utils;

const { token, tokenInfo } = await defaultRefreshTokenBodyAuth(
  authSecrets,
  request,
  true, // decryptToken
  logger
);

Parameters:

  • authSecrets: Authentication secrets for token decryption
  • request: HTTP request object containing the refresh token
  • decryptToken: Whether to decrypt and validate the token (default: false)
  • logger: Optional logger for security check logging

Process:

  1. Extracts refresh token from request.body.refreshToken
  2. Retrieves token verification context (fingerprint, IP, user agent)
  3. Validates token format and presence
  4. Decrypts and verifies JWT signature (if decryptToken is true)
  5. Validates token type is refresh token
  6. Performs security checks with IP validation enabled
  7. Returns token and token information

defaultRefreshTokenCookieAuth​

Default authentication function for refresh tokens fetched from cookies. Validates refresh tokens stored in cookies with fingerprint validation. Note that when decryptToken=true, the function returns both token and tokenInfo.

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

const { defaultRefreshTokenCookieAuth } = utils;

const { token, tokenInfo } = await defaultRefreshTokenCookieAuth(
  authSecrets,
  request,
  true, // decryptToken
  logger
);

Parameters:

  • authSecrets: Authentication secrets for token decryption
  • request: HTTP request object containing the refresh token in cookies
  • decryptToken: Whether to decrypt and validate the token (default: false)
  • logger: Optional logger for security check logging

Process:

  1. Extracts refresh token from request.cookies.refreshToken
  2. Retrieves token verification context (fingerprint, IP, user agent)
  3. Validates token format and presence
  4. Decrypts and verifies JWT signature (if decryptToken is true)
  5. Validates token type is refresh token
  6. Performs security checks with IP validation disabled
  7. Returns token and token information (when decryptToken is true)

Key Differences from Body Auth:

  • Source: Reads from cookies instead of request body
  • IP Validation: Disabled (checkIp: false) for cookie-based tokens
  • Return Value: When decryptToken=true, returns {token, tokenInfo} for additional processing

🛡️ Security Functions​

tokenPassesSecurityCheck​

Validates token security context.

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

const { tokenPassesSecurityCheck } = utils;

const isValid = tokenPassesSecurityCheck(
  tokenInfo,
  {
    fingerprint: 'device-fingerprint',
    ip: '192.168.1.1',
    userAgent: 'Mozilla/5.0...'
  },
  logger,
  { checkIp: true }
);

Validation checks:

  • Fingerprint: Device fingerprint matching
  • IP Address: IP address validation (optional)
  • User Agent: Browser/client identification

decryptAndVerifyJWT​

Decrypts and verifies JWT tokens.

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

const { decryptAndVerifyJWT } = utils;

const tokenInfo = decryptAndVerifyJWT(authSecrets, encryptedToken);

🔧 Helper Functions​

getBearerToken​

Extracts bearer token from request headers.

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

const { getBearerToken } = utils;

const token = getBearerToken(request.headers);
// Returns: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

getFingerprint​

Extracts device fingerprint from headers.

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

const { getFingerprint } = utils;

const fingerprint = getFingerprint(request.headers, 'x-nb-fingerprint');

getUserAgent​

Extracts user agent from request headers.

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

const { getUserAgent } = utils;

const userAgent = getUserAgent(request.headers);

getRequestInfo​

Extracts request metadata for token validation.

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

const { getRequestInfo } = utils;

const requestInfo = getRequestInfo(request);
// Returns: { host, ip, method, path, url }

getExpiresIn​

Normalizes token expiration time values. Converts various input formats to a standardized expiration time format.

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

const { getExpiresIn } = utils;

const expiresIn = getExpiresIn('24h');     // Returns: '24h'
const expiresIn2 = getExpiresIn(3600000);  // Returns: 3600000
const expiresIn3 = getExpiresIn();         // Returns: '48h' (default)

Parameters:

  • expirationTime: Optional expiration time as string or number

Returns:

  • number | string: Normalized expiration time (default: '48h')

Behavior:

  • If expirationTime is null or undefined: returns default '48h'
  • If expirationTime is a valid number: returns the number
  • If expirationTime is a string: returns the string as-is

getExpirationDate​

Calculates the absolute expiration date based on a duration string or milliseconds.

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

const { getExpirationDate } = utils;

const expirationDate = getExpirationDate('7d');     // Returns: Date object 7 days from now
const expirationDate2 = getExpirationDate(3600000); // Returns: Date object 1 hour from now
const expirationDate3 = getExpirationDate();        // Returns: Date object 7 days from now (default)

Parameters:

  • expiresIn: Duration string (e.g., '7d', '24h', '30m') or milliseconds (default: '7d')

Returns:

  • Date: Absolute expiration date and time

Supported Duration Formats:

  • '7d' - 7 days
  • '24h' - 24 hours
  • '30m' - 30 minutes
  • '60s' - 60 seconds
  • Numeric values in milliseconds

isAccessToken​

Checks if a token is an access token (user or app) and can be used as a simple type guard.

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

const { isAccessToken } = utils;

if (isAccessToken(tokenInfo)) {
  // tokenInfo is AccessTokenInfo (accessType: 'user' | 'app')
}

Parameters:

  • tokenInfo: Token information object to check

Returns:

  • boolean: true if the token is an access token, otherwise false

isUserAccessToken​

Checks if a token is specifically a user access token.

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

const { isUserAccessToken } = utils;

if (isUserAccessToken(tokenInfo)) {
  // tokenInfo is UserAccessTokenInfo
  console.log(tokenInfo.identityId);
}

Parameters:

  • tokenInfo: Token information object to check

Returns:

  • boolean: true if the token is a user access token, otherwise false

isAppAccessToken​

Checks if a token is specifically an app access token.

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

const { isAppAccessToken } = utils;

if (isAppAccessToken(tokenInfo)) {
  // tokenInfo is AppAccessTokenInfo
  console.log(tokenInfo.appId);
}

Parameters:

  • tokenInfo: Token information object to check

Returns:

  • boolean: true if the token is an app access token, otherwise false

isRefreshToken​

Checks if a token is a refresh token.

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

const { isRefreshToken } = utils;

if (isRefreshToken(tokenInfo)) {
  // tokenInfo is RefreshTokenInfo
  console.log(tokenInfo.jti);
}

Parameters:

  • tokenInfo: Token information object to check

Returns:

  • boolean: true if the token is a refresh token, otherwise false

isOnetimeToken​

Checks if a token is a one-time token.

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

const { isOnetimeToken } = utils;

if (isOnetimeToken(tokenInfo)) {
  // tokenInfo is OnetimeTokenInfo
  console.log(tokenInfo.data);
}

Parameters:

  • tokenInfo: Token information object to check

Returns:

  • boolean: true if the token is a one-time token, otherwise false

isValidAppAccessToken​

Checks that an app access token has an appId present.

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

const { isValidAppAccessToken } = utils;

if (isValidAppAccessToken(tokenInfo)) {
  // tokenInfo is AppAccessTokenInfo with appId present
}

Parameters:

  • tokenInfo: Token information object to check

Returns:

  • boolean: true if token is an app access token with appId present, otherwise false

isValidUserAccessToken​

Checks that a user access token has an identityId present.

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

const { isValidUserAccessToken } = utils;

if (isValidUserAccessToken(tokenInfo)) {
  // tokenInfo is UserAccessTokenInfo with identityId present
}

Parameters:

  • tokenInfo: Token information object to check

Returns:

  • boolean: true if token is a user access token with identityId present, otherwise false

retrieveTokenVerification​

Create token verification metadata from an Express Request.

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

const { retrieveTokenVerification } = utils;

const verification = retrieveTokenVerification(request);
// { domain, fingerprint, ip, userAgent }

validateAuthSecrets​

Validate required auth secrets and throw if missing/too short.

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

const { validateAuthSecrets } = utils;

validateAuthSecrets(authSecrets); // throws on invalid configuration

generateMailBody​

Interpolate a URL and options into an email template.

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

const { generateMailBody } = utils;

const body = generateMailBody(
  'Click here: ${url}',
  'https://example.com/reset?token=${token}',
  { token: 'abc' }
);

authSecretsValidationErrorMessage​

Return a human-readable error for invalid auth secrets (temporary helper).

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

const { authSecretsValidationErrorMessage } = utils;

const msg = authSecretsValidationErrorMessage(authSecrets);
if (msg) throw new Error(msg);

🔐 Encryption Functions​

encrypt​

Encrypts data.

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

const { encrypt } = utils;

const encrypted = encrypt(secret, 'sensitive-data');

decrypt​

Decrypts encrypted data.

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

const { decrypt } = utils;

const decrypted = decrypt(secret, encryptedData);

🔑 Password Functions​

hash​

Hashes passwords using bcrypt.

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

const { hash } = utils;

const hashedPassword = await hash('user-password');

compareHash​

Compares password with hash.

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

const { compareHash } = utils;

const isValid = await compareHash('user-password', hashedPassword);

📊 Token Types​

User Access Token​

interface UserAccessTokenInfo {
  accessType: 'user';
  identityId: string;
  type: 'access';
  stateful: boolean;
  fingerprint?: string;
  ip?: string;
  domain?: string;
  target?: string;
  userAgent?: string;
}

App Access Token​

interface AppAccessTokenInfo {
  accessType: 'app';
  appId: string;
  type: 'access';
}

Refresh Token​

interface RefreshTokenInfo {
  type: 'refresh';
  jti: string;
  identityId: string;
  stateful: true;
  fingerprint?: string;
  ip?: string;
  domain?: string;
  userAgent?: string;
}

One-time Token​

interface OnetimeTokenInfo {
  type: 'onetime';
  data: object;
  stateful: true;
  fingerprint?: string;
  ip?: string;
  domain?: string;
  target?: string;
  userAgent?: string;
}