otplib API Documentation / @otplib/core / utils / createGuardrails

Function: createGuardrails()

createGuardrails(custom?): OTPGuardrails

Defined in: packages/core/src/utils.ts:223

Create guardrails configuration object

Factory function that merges custom guardrails with defaults and returns an immutable (frozen) object. Validates custom guardrails to ensure they maintain basic safety invariants.

When called without arguments or with undefined, returns the default guardrails singleton (optimized to avoid unnecessary allocations). When called with custom values, creates a new frozen object and internally marks it as overridden.

Parameters

custom?

Partial<OTPGuardrailsConfig>

Optional partial guardrails to override defaults

Returns

OTPGuardrails

Frozen guardrails object

Throws

If custom guardrails violate safety invariants

Examples

Basic usage

import { createGuardrails, hasGuardrailOverrides } from '@otplib/core'

// Returns default singleton (no overrides)
const defaults = createGuardrails();
hasGuardrailOverrides(defaults); // false

// Creates new object with overrides
const custom = createGuardrails({
  MIN_SECRET_BYTES: 8,
  MAX_WINDOW: 200
});
hasGuardrailOverrides(custom); // true

Monitoring custom guardrails

import { createGuardrails, hasGuardrailOverrides } from '@otplib/core';

const guardrails = createGuardrails({ MAX_WINDOW: 20 });

if (hasGuardrailOverrides(guardrails)) {
  logger.warn('Non-default guardrails in use', { guardrails });
}

See

hasGuardrailOverrides to check if guardrails were customized