🔍 Authentication Schemas

Authentication schemas provide JSON Schema definitions for authentication data validation in Nodeblocks applications. These schemas ensure secure authentication flows and provide clear contracts for authentication-related API endpoints.

---

🎯 Overview

Authentication schemas are designed to:

• Validate authentication data before processing
• Support multiple auth methods (OAuth, email/password)
• Ensure secure authentication with proper validation
• Enable email verification workflows
• Support device fingerprinting for enhanced security

---

📋 Authentication Schema Types

Provider Authentication Schemas

OAuth and third-party authentication validation.

Credentials Authentication Schemas

Email/password authentication validation.

Identity Schemas

Flexible authentication with support for multiple methods.

Email Verification Schemas

Email verification and confirmation workflows.

---

🔧 Available Authentication Schemas

passwordSchema

Password validation schema with security requirements and pattern matching.

Purpose: Serves as a base schema for password validation, used by other authentication schemas

Schema Details:

• Type: object
• Required Fields: None
• Additional Properties: false
• Properties:
  • password: string — 8-24 chars; at least one lowercase letter and one number; allows ?/_-

Usage:

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

const { passwordSchema } = schemas;

const validate = ajv.compile(passwordSchema as SchemaDefinition);
const isValid = validate({ password: 'securePass123' });

---

providerSchema

Provider authentication schema for OAuth and third-party authentication.

Purpose: Validates OAuth provider authentication data

Schema Details:

• Type: object
• Required Fields: provider, providerId
• Additional Properties: false (strict validation)
• Properties:
  • provider: string - OAuth provider name
  • providerId: string - Provider-specific user ID

Usage:

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

const { providerSchema } = schemas;
const validate = ajv.compile(providerSchema as SchemaDefinition);
const isValid = validate({ provider: 'google', providerId: '12345' });

---

credentialsSchema

Credentials authentication schema for email/password authentication.

Purpose: Validates email/password authentication data

Schema Details:

• Type: object
• Required Fields: email, password
• Additional Properties: false (strict validation)
• Properties:
  • email: string - Identity email address
  • emailVerified: boolean - Email verification status (default: false)
  • password: string - User password

Usage:

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

const { credentialsSchema } = schemas;
const validate = ajv.compile(credentialsSchema as SchemaDefinition);
const isValid = validate({ email: 'identity@example.com', password: 'password123' });

---

changePasswordSchema

Password change schema with current and new password validation for user accounts.

Purpose: Validates password change requests with security requirements

Schema Details:

• Type: object
• Required Fields: password, newPassword
• Additional Properties: false (strict validation)
• Parameters: identityId (path parameter)
• Content-Type: application/json
• Request Body: required
• Properties:
  • password: string - Current password for verification
  • newPassword: string - New password with security requirements

New Password Requirements:

• Length: 8-24 characters
• Pattern: Must contain at least one lowercase letter and one number
• Allowed characters: Letters, numbers, and special characters (?/_-)
• Validation: Regex pattern enforces security requirements for newPassword
• Identity ID: Required as path parameter for identity identification

Usage:

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

const { changePasswordSchema } = schemas;

// Apply to feature composition:
export const changePasswordFeature = compose(changePasswordSchema, changePasswordRoute);

---

completePasswordResetSchema

Password reset completion schema with password validation for account recovery.

Purpose: Validates password reset completion requests with security requirements

Schema Details:

• Type: object
• Required Fields: password
• Additional Properties: false (strict validation)
• Content-Type: application/json
• Request Body: required
• Properties:
  • password: string - New password with security requirements

Password Requirements:

• Length: 8-24 characters
• Pattern: Must contain at least one lowercase letter and one number
• Allowed characters: Letters, numbers, and special characters (?/_-)
• Validation: Inherits from passwordSchema security requirements
• Workflow: Used in password reset workflow after receiving reset link

Usage:

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

const { completePasswordResetSchema } = schemas;

// Apply to feature composition:
export const completePasswordResetFeature = compose(completePasswordResetSchema, completePasswordResetRoute);

---

activateSchema

Identity activation schema with identity validation for account activation.

Purpose: Validates identity activation requests with identity ID validation

Schema Details:

• Type: object
• Required Fields: identityId
• Additional Properties: false (strict validation)
• Content-Type: application/json
• Request Body: required
• Properties:
  • identityId: string - User identity identifier for activation

Usage:

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

const { activateSchema } = schemas;

// Apply to feature composition:
export const activateFeature = compose(activateSchema, activateRoute);

---

deactivateSchema

Identity deactivation schema with identity validation for account deactivation.

Purpose: Validates identity deactivation requests with identity ID validation

Schema Details:

• Type: object
• Required Fields: identityId
• Additional Properties: false (strict validation)
• Content-Type: application/json
• Request Body: required
• Properties:
  • identityId: string - User identity identifier for deactivation

Usage:

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

const { deactivateSchema } = schemas;

// Apply to feature composition:
export const deactivateFeature = compose(deactivateSchema, deactivateRoute);

---

identitySchema

Identity schema that supports both provider and credentials authentication.

Purpose: Validates authentication data with support for multiple auth methods

Schema Details:

• Type: object
• Required Fields: Either provider+providerId OR email+password
• Additional Properties: false (strict validation)
• Validation: Requires either provider+providerId OR email+password
• Content-Type: application/json
• Request Body: required

Usage:

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

const { identitySchema } = schemas;

const identitySchema = identitySchema({});
const validate = ajv.compile(identitySchema.schemas as SchemaDefinition);

// Provider auth
const isValidProvider = validate({ provider: 'google', providerId: '12345' });

// Credentials auth
const isValidCredentials = validate({ email: 'identity@example.com', password: 'password123' });

---

loginWithCredentialsSchema

Login credentials schema for identity authentication.

Purpose: Validates login request data with optional device fingerprinting

Schema Details:

• Type: object
• Required Fields: email, password
• Optional Fields: fingerprint
• Additional Properties: false (strict validation)
• Content-Type: application/json
• Request Body: required

Usage:

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

const { loginWithCredentialsSchema } = schemas;

const loginSchema = loginWithCredentialsSchema({});
const validate = ajv.compile(loginSchema.schemas as SchemaDefinition);
const isValid = validate({
  email: 'identity@example.com',
  password: 'password123',
  fingerprint: 'device-fingerprint-hash'
});

---

resendMfaCodeSchema

MFA code resend schema with token validation for authentication.

Purpose: Validates MFA code resend requests for users who need a new verification code

Schema Details:

• Type: object
• Required Fields: token
• Additional Properties: false (strict validation)
• Content-Type: application/json
• Request Body: required
• Properties:
  • token: string - MFA challenge token from initial login attempt

Use Cases:

• User didn't receive initial MFA code email
• MFA code expired before user could enter it
• Email delivery delay or failure
• User accidentally deleted email

Security Features:

• Invalidates previous MFA token
• Generates new MFA code for security
• Issues new MFA token
• Maintains token-based verification flow

Usage:

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

const { resendMfaCodeSchema } = schemas;

// Apply to feature composition:
export const resendMfaCodeFeature = compose(resendMfaCodeSchema, resendMfaCodeRoute);

// Example valid request:
const validRequest = {
  token: 'encrypted-mfa-challenge-token'
};

Request Example:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response Example (Success):

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

---

verifyMfaCodeSchema

MFA code verification schema with token and code validation.

Purpose: Validates MFA code verification requests with MFA token and user-provided code

Schema Details:

• Type: object
• Required Fields: token, code
• Additional Properties: false (strict validation)
• Content-Type: application/json
• Request Body: required
• Properties:
  • token: string - MFA challenge token returned from login endpoint
  • code: string - User-provided MFA verification code (from email)

Workflow:

1. User attempts login with credentials
2. System sends MFA code via email and returns MFA token
3. User receives MFA code in email
4. User submits MFA token and code for verification
5. System validates code and returns access/refresh tokens

Security Features:

• Token-based verification prevents replay attacks
• One-time tokens invalidated after use
• Time-limited tokens prevent stale code usage
• Strict schema validation

Usage:

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

const { verifyMfaCodeSchema } = schemas;

// Apply to feature composition:
export const verifyMfaCodeFeature = compose(verifyMfaCodeSchema, verifyMfaCodeRoute);

// Example valid request:
const validRequest = {
  token: 'encrypted-mfa-challenge-token',
  code: '123456'
};

Request Example:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "code": "123456"
}

Response Example (Success):

{
  "id": "identity-uuid",
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

---

loginWithOnetimeTokenSchema

One-time token login schema with token validation for secure authentication.

Purpose: Validates one-time token login requests for passwordless authentication

Schema Details:

• Type: object
• Required Fields: token
• Additional Properties: false (strict validation)
• Content-Type: application/json
• Request Body: required
• Properties:
  • token: string - One-time authentication token (typically from magic link)

Use Cases:

• Magic link authentication
• Email-based passwordless login
• Secure account access without password
• Time-limited authentication tokens

Security Features:

• Token must have type: 'onetime'
• Token must have target: 'login'
• Tokens are one-time use (invalidated after login)
• Tokens include identity ID for user lookup
• Token validation includes fingerprint and request info

Usage:

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

const { loginWithOnetimeTokenSchema } = schemas;

// Apply to feature composition:
export const loginWithOnetimeTokenFeature = compose(
  loginWithOnetimeTokenSchema, 
  loginWithOnetimeTokenRoute
);

// Example valid request:
const validRequest = {
  token: 'encrypted-onetime-authentication-token'
};

Request Example:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response Example (Success):

{
  "id": "identity-uuid",
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Typical Flow:

1. User requests magic link (separate endpoint)
2. System generates one-time token with target: 'login'
3. System sends magic link to user's email
4. User clicks link and submits token
5. System validates token and returns authentication tokens

---

registerCredentialsSchema

Identity registration schema with email/password or token/password validation.

Purpose: Schema validator for identity registration requests

Schema Details:

• Type: object
• Required Fields: password (always required)
• Optional Fields: email, token
• Validation: Requires either email+password OR token+password
• Content-Type: application/json
• Request Body: required

Usage:

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

const { registerCredentialsSchema } = schemas;

const registerSchema = registerCredentialsSchema({});
const validate = ajv.compile(registerSchema.schemas as SchemaDefinition);
const isValid = validate({ 
  email: 'identity@example.com', 
  password: 'password123' 
});

---

sendVerificationEmailSchema

JSON Schema for validating send verification email requests.

Purpose: Validates the request body for the send verification email endpoint

Schema Details:

• Type: object
• Required Fields: None (all fields optional)
• Additional Properties: false (strict validation)
• Parameters: identityId (path parameter)
• Content-Type: application/json
• Request Body: required
• Properties:
  • fingerprint?: string - Optional device fingerprinting

Usage:

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

const { sendVerificationEmailSchema } = schemas;

const verificationSchema = sendVerificationEmailSchema({});
const validate = ajv.compile(verificationSchema.schemas as SchemaDefinition);
const isValid = validate({ 
  fingerprint: 'device-fingerprint-hash' 
});

---

confirmEmailSchema

Email confirmation schema with token validation for email verification.

Purpose: Schema validator for email confirmation requests

Schema Details:

• Type: object
• Required Fields: token
• Additional Properties: false (strict validation)
• Content-Type: application/json
• Request Body: required
• Properties:
  • token: string - Verification token from email

Usage:

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

const { confirmEmailSchema } = schemas;

const confirmSchema = confirmEmailSchema({});
const validate = ajv.compile(confirmSchema.schemas as SchemaDefinition);
const isValid = validate({ 
  token: 'verification-token-123' 
});

---

changeEmailSchema

Email change schema with identity validation for user email updates.

Purpose: Schema validator for email change requests

Schema Details:

• Type: object
• Required Fields: email
• Additional Properties: false (strict validation)
• Content-Type: application/json
• Request Body: required
• Parameters: identityId (path parameter)
• Properties:
  • email: string - New email address for identity account

Usage:

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

const { changeEmailSchema } = schemas;

const changeEmailSchema = changeEmailSchema({});
const validate = ajv.compile(changeEmailSchema.schemas as SchemaDefinition);
const isValid = validate({ 
  email: 'newemail@example.com' 
});

---

checkTokenSchema

Token validation schema with required token and optional target parameters.

Purpose: Schema validator for token validation requests

Schema Details:

• Type: object
• Required Fields: token
• Optional Fields: target
• Additional Properties: false (strict validation)
• Content-Type: application/json
• Request Body: required
• Properties:
  • token: string - JWT token string to validate
  • target?: string - Target context for token validation (e.g., 'confirm-email', 'change-email')

Usage:

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

const { checkTokenSchema } = schemas;

const checkTokenSchema = checkTokenSchema({});
const validate = ajv.compile(checkTokenSchema.schemas as SchemaDefinition);
const isValid = validate({ 
  token: 'jwt-token-here',
  target: 'confirm-email'
});

---

confirmNewEmailSchema

New email confirmation schema with token validation for email change verification.

Purpose: Schema validator for new email confirmation requests

Schema Details:

• Type: object
• Required Fields: token
• Additional Properties: false (strict validation)
• Content-Type: application/json
• Request Body: required
• Properties:
  • token: string - Verification token from new email

Usage:

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

const { confirmNewEmailSchema } = schemas;

const confirmNewEmailSchema = confirmNewEmailSchema({});
const validate = ajv.compile(confirmNewEmailSchema.schemas as SchemaDefinition);
const isValid = validate({ 
  token: 'verification-token-123' 
});

---

sendResetPasswordLinkEmailSchema

Password reset email schema with email validation for password recovery.

Purpose: Schema validator for password reset email requests

Schema Details:

• Type: object
• Required Fields: email
• Additional Properties: false (strict validation)
• Content-Type: application/json
• Request Body: required
• Properties:
  • email: string - User email address for password reset

Usage:

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

const { sendResetPasswordLinkEmailSchema } = schemas;

const resetPasswordSchema = sendResetPasswordLinkEmailSchema({});
const validate = ajv.compile(resetPasswordSchema.schemas as SchemaDefinition);
const isValid = validate({ 
  email: 'identity@example.com' 
});

---

refreshTokenSchema

Token refresh schema with refresh token validation for token renewal requests.

Purpose: Schema validator for token refresh requests

Schema Details:

• Type: object
• Required Fields: refreshToken
• Additional Properties: false (strict validation)
• Content-Type: application/json
• Request Body: required
• Properties:
  • refreshToken: string - Refresh token for authentication renewal

Usage:

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

const { refreshTokenSchema } = schemas;

// Apply to feature composition:
export const refreshTokenFeature = compose(refreshTokenSchema, refreshTokenRoute);

---

deleteRefreshTokensSchema

Refresh token deletion schema with identity path parameter validation.

Purpose: Schema validator for refresh token deletion requests

Schema Details:

• Type: object
• Required Fields: identityId (path parameter)
• Additional Properties: false (strict validation)
• Parameters: identityId path parameter

Usage:

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

const { deleteRefreshTokensSchema } = schemas;

// Apply to feature composition:
export const deleteRefreshTokensFeature = compose(deleteRefreshTokensSchema, deleteRefreshTokensRoute);

---

🔗 Related Documentation

• Authentication Domain Overview - Authentication domain overview