platform-cryptography

Cryptographic building blocks for NestJS applications: bcrypt password hashing, prefixed UUID generation, and TOTP-based multi-factor authentication. All services are @Injectable() and ready for constructor injection.

Package: @breadstone/archipel-platform-cryptography

npm install @breadstone/archipel-platform-cryptography

Quick Start

import { BcryptService, CryptoService } from '@breadstone/archipel-platform-cryptography';

// OTP is a tree-shakable sub-export
import { OtpService, OTP_SERVICE_TOKEN } from '@breadstone/archipel-platform-cryptography/otp';

---

Password Hashing (BcryptService)

Secure password hashing with auto-generated salts.

import { Injectable } from '@nestjs/common';
import { BcryptService } from '@breadstone/archipel-platform-cryptography';

@Injectable()
export class AccountService {
  constructor(private readonly _bcrypt: BcryptService) {}

  async createAccount(password: string): Promise<void> {
    const hashed = await this._bcrypt.hash(password);
    // store hashed password
  }

  async verifyPassword(password: string, hash: string): Promise<boolean> {
    return this._bcrypt.compare(password, hash);
  }
}

Method	Description
hash(data)	Hashes a string with a generated bcrypt salt.
compare(data, encrypted)	Compares plain text against a bcrypt hash.

---

Prefixed UUIDs (CryptoService)

Generates random UUIDs prefixed with a domain identifier for readable, collision-free identifiers.

import { CryptoService } from '@breadstone/archipel-platform-cryptography';

const crypto = new CryptoService();

crypto.getRandomGuid('usr'); // → 'usr-a1b2c3d4-...'
crypto.getRandomGuid('ord'); // → 'ord-e5f6a7b8-...'
crypto.getRandomGuid('inv'); // → 'inv-c9d0e1f2-...'

Method	Description
getRandomGuid(prefix)	Returns {prefix}-{uuid}. Throws if prefix is empty.

---

TOTP Multi-Factor Authentication (OtpService)

TOTP enrollment and verification backed by otplib v13, injected via the OTP_SERVICE_TOKEN symbol.

Injection Setup

import { Module } from '@nestjs/common';
import { OtpService, OTP_SERVICE_TOKEN } from '@breadstone/archipel-platform-cryptography/otp';

@Module({
  providers: [{ provide: OTP_SERVICE_TOKEN, useClass: OtpService }],
  exports: [OTP_SERVICE_TOKEN],
})
export class SecurityModule {}

Usage

import { Inject, Injectable } from '@nestjs/common';
import { OTP_SERVICE_TOKEN, IOtpService } from '@breadstone/archipel-platform-cryptography/otp';

@Injectable()
export class MfaService {
  constructor(@Inject(OTP_SERVICE_TOKEN) private readonly _otp: IOtpService) {}

  enroll(issuer: string, label: string) {
    const secret = this._otp.generateSecret();
    const uri = this._otp.generateUri({ issuer, label, secret });
    return { secret, uri }; // uri → QR code
  }

  verify(token: string, secret: string): boolean {
    return this._otp.verify(token, secret);
  }
}

Tolerance

The default TOTP_EPOCH_TOLERANCE is 30 seconds (±1 time step):

epochTolerance	Accepted range
0	Current step only
30	±1 step (±30 s)
60	±2 steps (±60 s)
90	±3 steps (±90 s)

---

Error Handling

CryptoService throws CryptoValidationError when provided with invalid input (e.g. empty UUID prefix). The error carries a code property set to 'CRYPTO_VALIDATION'.

import { CryptoValidationError } from '@breadstone/archipel-platform-cryptography';

---

API Reference

See the full API documentation for all exported types and classes.