Viardex Libs

Shared NestJS infrastructure for Viardex services.

Argon

@viardex/viardex-libs provides a shared Argon2id hashing module for passwords, passcodes, and transaction PINs.

import { ArgonModule, ArgonService } from '@viardex/viardex-libs';

@Module({
  imports: [ArgonModule],
})
export class AppModule {}

Example:

constructor(private readonly argonService: ArgonService) {}

const hash = await this.argonService.hash(password);
const isValid = await this.argonService.verify(hash, password);
const shouldRotate = await this.argonService.needsRehash(hash);

ArgonService.verify() safely returns false for malformed hashes instead of leaking low-level argon exceptions into auth flows.

Auth

@viardex/viardex-libs provides the shared JWT verifier module.

import { AuthModule } from '@viardex/viardex-libs';

@Module({
  imports: [AuthModule],
})
export class AppModule {}

Decorators

Use the shared barrel:

import {
  AuthModule,
  CurrentAuth,
  Permissions,
  Public,
  Roles,
} from '@viardex/viardex-libs';

• @Public() marks a route as bypassing the global JWT guard.
• @Roles(...roles) declares allowed staff roles for a route.
• @Permissions(...permissions) declares required permissions for a route.
• @CurrentAuth() returns the verified JWT principal from the request.

Guards

Guard classes live under src/auth/guards and are exported through the shared barrel:

import { PermissionsGuard, RolesGuard } from '@viardex/viardex-libs';

Example:

@UseGuards(RolesGuard, PermissionsGuard)
@Roles('admin', 'support')
@Permissions('tickets.read', 'tickets.resolve')
@Get('tickets')
listTickets() {}

JWT Config

Services should expose:

JWT_ALGORITHM=RS256
JWT_ISSUER=viardex-user-service
JWT_AUDIENCE=viardex-api
JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"

The shared auth module verifies JWTs globally. Role and permission guards are opt-in at the route or controller level.

Logger

LoggerModule is global and wraps nestjs-pino.

• development uses pino-pretty
• non-HTTP contexts are ignored by LoggingInterceptor
• request logging keeps request id, method, URL, status code, and duration

Health

HealthModule exposes:

• GET /health for lightweight liveness
• GET /health/ready for readiness checks

Readiness currently checks storage, memory, and NATS connectivity.

Cache

CacheModule.register() exposes a Redis-backed CacheService.

Preferred APIs:

• set() / get()
• setJson() / getJson()
• setIfNotExists() for idempotency / locks
• scan() instead of keys() for production-safe pattern reads
• ping() for lightweight health checks

Common

@viardex/viardex-libs also exposes shared DTOs, pipes, response helpers, and safe formatting utilities through the root barrel.

Response Shape

Use the shared response helpers to keep HTTP payloads consistent across Nest services.

import { AppResponse } from '@viardex/viardex-libs';

return AppResponse.success('User fetched successfully', user);

For paginated endpoints:

return AppResponse.paginated('Users fetched successfully', items, {
  page,
  limit,
  totalItems,
  totalPages,
});

Shared response exports include:

• ApiResponse
• PaginationMeta
• ResponseMeta
• ErrorDetail
• AppResponse
• ResponseInterceptor
• HttpExceptionFilter

DTOs And Pipes

Shared request helpers include:

• PaginationQueryDto
• PaginationQueryCleanerPipe
• FileValidationPipe

Cards

Shared card-safe helpers are available for masking and display use cases:

• maskPan
• extractLast4
• extractBin
• formatCardExpiry
• normalizeCardExpiry
• formatCardLabel

These are for safe formatting and display only. Sensitive authentication data like CVV must never be stored or handled through shared helpers.

Crypto

Shared crypto helpers are intentionally limited to generic amount and formatting concerns:

• toAtomicUnits
• fromAtomicUnits
• formatCryptoAmount
• normalizeTxHash
• isHexTxHash
• isPositiveAmount

They are useful for asset formatting and validation, but custody, compliance, signing, and chain-specific business logic should stay inside the owning service.

Nest And Go Mapping

The Go shared package in viardex-go follows the same auth concepts, but uses middleware and request context instead of Nest metadata and guards.

| Nest (viardex-libs) | Go (viardex-go) | | --- | --- | | AuthModule | auth package setup in service bootstrap | | AuthService | auth.NewService(...) / auth.Service | | AuthPrincipal | auth.Principal | | AuthTokenType | auth.TokenType | | AuthGuard | middlewares.Auth(...) | | RolesGuard | middlewares.RequireRoles(...) | | PermissionsGuard | middlewares.RequirePermissions(...) | | AuthTokenTypes(...) | middlewares.RequireTokenTypes(...) | | Public() | keep route/group outside auth middleware | | Roles(...) | wrap route/group with middlewares.RequireRoles(...) | | Permissions(...) | wrap route/group with middlewares.RequirePermissions(...) | | CurrentAuth() | auth.PrincipalFromContext(r.Context()) |

Example Comparison

Nest:

@UseGuards(PermissionsGuard)
@Permissions('ledger.read')
@Get('/ledger')

Go:

r.With(middlewares.RequirePermissions("ledger.read")).Get("/ledger", handler)

Nest:

@Public()
@Get('/health')

Go:

r.Get("/health", handler)

Nest:

const principal = request.user;

Go:

principal, ok := auth.PrincipalFromContext(r.Context())