Otp

• Otp
  • Overview
  • Data Structure
    • State Schema
    • Enums and Types
    • Additional Structures
  • Core Functionality
    • Main Feature Groups
  • API Methods
    • OTP Management
  • Key Features

Overview

The Otp class provides One-Time Password (OTP) record storage and management for authentication flows. It functions as a storage service that manages OTP records and their validation history, enabling other classes to implement secure authentication workflows.

General Purpose:

• OTP record storage and history tracking for authentication workflows
• Instance-based architecture with classKey_entityId instance IDs for entity-specific OTP management
• State-based persistence with comprehensive audit trails for all validation attempts
• Integration point for classes requiring OTP-based authentication (Member registration, verification flows)

Data Structure

State Schema

interface OTPState {
  private: {
    associatedClassKey: ClassKey
    associatedEntityId: string
    records: Array<OTP & { history: OTPCheckHistoryRecord[] }>
  }
  public: object
}

Enums and Types

enum TokenType {
  ALPHA_NUMERIC = 'alphanumeric',
  NUMERIC = 'numeric',
  UUID = 'uuid'
}

enum CheckOTPResult {
  RETRY_LIMIT_EXCEED = 'retry_limit_exceed',
  OTP_LIMIT_EXCEED = 'otp_limit_exceed',
  NO_ACTIVE_OTP = 'no_active_otp',
  INVALID_TOKEN = 'invalid_token'
}

Error Responses:

The OTP class defines the following error responses with proper HTTP status codes and localized messages:

• OTP_LIMIT_EXCEEDED (6001, 429): Thrown when too many OTP creation requests are made within the allowed time window
• OTP_RETRY_LIMIT_EXCEEDED (6002, 429): Thrown when too many failed OTP validation attempts occur within the retry window

These errors are thrown as ErrorResponse objects by the OTPManager service and can be caught and handled by consuming classes like Member.

### Additional Structures

```typescript
interface OTP {
  id: string
  otpType: string
  token: string
  tokenType: TokenType
  createdAt: Date
  usedAt?: Date
  additionalData?: Record<string, any>
}

interface OTPCheckHistoryRecord {
  timestamp: Date
  isSuccessful: boolean
  validationResult?: CheckOTPResult
  requestedBy: string
  requesterDetails: {
    identity: string
    userAgent?: string
    ipAddress?: string
  }
  additionalData?: Record<string, any>
}

interface OTPConfig {
  otpLimit: number
  otpExpireTimeInSeconds: number
  retryLimit: number
  retryExpireTimeInSeconds: number
}

Core Functionality

Main Feature Groups

• OTP Record Storage: Persistent storage of OTP records with comprehensive metadata including token type, creation time, and usage status
• History Tracking: Complete audit trail of all validation attempts with requester details, timestamps, and validation results
• Type-Based Filtering: Ability to retrieve OTP records filtered by type for different authentication workflows
• Entity Association: Each OTP instance is associated with a specific class and entity through the instance ID pattern
• State Management: Centralized state management through OtpStateManager for consistent data handling

Internal Architecture

• OtpStateManager: Core state management service extending StateManager pattern for consistent OTP data handling
• OTP Storage Model: Direct state-based storage using the Rio instance state system
• History Management: Embedded history records within each OTP for complete audit trails

API Methods

OTP Management

• createOtpRecord (QUEUED_WRITE) - Create a new OTP record

  • Stores OTP record with comprehensive metadata (token, type, timestamps)
  • Initializes empty history array for future validation tracking

• createOtpCheckRecord (QUEUED_WRITE) - Create a new OTP check record

  • Adds validation attempt history to existing OTP record
  • Records requester details, success status, and additional metadata

• getOtpRecords (READ) - Retrieve OTP records

  • Filters and returns OTP records by type with complete validation history
  • Enables type-specific OTP retrieval for different authentication flows

Key Features

1. Architecture Pattern: Instance-based with classKey_entityId format for entity-specific OTP management
2. Integration Points: Storage service for classes requiring OTP authentication (Member, ProgramManagementUser)
3. Data Management: State-based persistence with OtpStateManager following established StateManager patterns
4. Security Features: Complete audit trails with validation history and requester tracking
5. Token Support: Supports multiple token types (ALPHA_NUMERIC, NUMERIC, UUID) with flexible metadata
6. Authorization: Restricted access - only ProgramManagementUser and Member class identities can access OTP methods
7. Audit/Logging: Comprehensive history tracking for all validation attempts with timestamps and requester details
8. Performance Features: Type-based filtering for efficient OTP retrieval in authentication workflows
9. Error Handling: Proper error responses with HTTP 429 status codes for rate limiting violations (OTP creation limits and retry limits)

Class Relations

The following diagram illustrates how Otp integrates with other system components: