@futdevpro/nts-dynamo 1.15.139 → 1.15.141

package/src/_modules/account-security/_enums/account-challenge-purpose.type-enum.ts

@@ -0,0 +1,5 @@
+/** Supported one-time account challenge purposes. */
+export enum DyNTS_AccountChallengePurpose_Type {
+  emailVerification = 'email-verification',
+  passwordReset = 'password-reset',
+}

package/src/_modules/account-security/_enums/account-refresh-token-state.type-enum.ts

@@ -0,0 +1,6 @@
+/** One-time refresh-token ledger states. */
+export enum DyNTS_AccountRefreshTokenState_Type {
+  active = 'active',
+  used = 'used',
+  revoked = 'revoked',
+}

package/src/_modules/account-security/_enums/account-session-state.type-enum.ts

@@ -0,0 +1,6 @@
+/** Persisted standalone account-session states. */
+export enum DyNTS_AccountSessionState_Type {
+  active = 'active',
+  revoked = 'revoked',
+  expired = 'expired',
+}

package/src/_modules/account-security/_models/account-challenge-adapter.interface.ts

@@ -0,0 +1,17 @@
+import { DyNTS_AccountChallengePurpose_Type } from '../_enums/account-challenge-purpose.type-enum';
+import { DyNTS_AccountChallengeRecord_Interface } from './account-challenge-record.interface';
+
+/** Atomic persistence contract for replacing and consuming one-time account challenges. */
+export interface DyNTS_AccountChallengeAdapter_Interface {
+  replaceActiveChallenge(record: DyNTS_AccountChallengeRecord_Interface): Promise<void>;
+  consumeActiveChallenge(
+    tokenHash: string,
+    purpose: DyNTS_AccountChallengePurpose_Type,
+    consumedAt: string
+  ): Promise<DyNTS_AccountChallengeRecord_Interface | null>;
+  revokeSubjectChallenges(
+    subjectId: string,
+    purpose: DyNTS_AccountChallengePurpose_Type,
+    revokedAt: string
+  ): Promise<void>;
+}

package/src/_modules/account-security/_models/account-challenge-issued.interface.ts

@@ -0,0 +1,6 @@
+/** Raw one-time challenge returned once after its hash is persisted. */
+export interface DyNTS_AccountChallengeIssued_Interface {
+  challengeId: string;
+  token: string;
+  expiresAt: string;
+}

package/src/_modules/account-security/_models/account-challenge-record.interface.ts

@@ -0,0 +1,13 @@
+import { DyNTS_AccountChallengePurpose_Type } from '../_enums/account-challenge-purpose.type-enum';
+
+/** Server-only one-time account challenge record containing a credential hash only. */
+export interface DyNTS_AccountChallengeRecord_Interface {
+  challengeId: string;
+  subjectId: string;
+  purpose: DyNTS_AccountChallengePurpose_Type;
+  tokenHash: string;
+  createdAt: string;
+  expiresAt: string;
+  consumedAt: string;
+  revokedAt: string;
+}

package/src/_modules/account-security/_models/account-challenge-result.interface.ts

@@ -0,0 +1,8 @@
+import { DyNTS_AccountChallengePurpose_Type } from '../_enums/account-challenge-purpose.type-enum';
+
+/** Trusted identity binding returned after an atomic one-time challenge consumption. */
+export interface DyNTS_AccountChallengeResult_Interface {
+  challengeId: string;
+  subjectId: string;
+  purpose: DyNTS_AccountChallengePurpose_Type;
+}

package/src/_modules/account-security/_models/account-challenge-settings.interface.ts

@@ -0,0 +1,9 @@
+import { DyNTS_AccountChallengeAdapter_Interface } from './account-challenge-adapter.interface';
+
+/** Runtime settings for one-time account challenges. */
+export interface DyNTS_AccountChallengeSettings_Interface {
+  adapter: DyNTS_AccountChallengeAdapter_Interface;
+  ttlMs?: number;
+  tokenBytes?: number;
+  clock?: () => Date;
+}

package/src/_modules/account-security/_models/account-password-policy.interface.ts

@@ -0,0 +1,11 @@
+/** Password-hashing and validation policy for the standalone Dynamo account capability. */
+export interface DyNTS_AccountPasswordPolicy_Interface {
+  minLength: number;
+  maxLength: number;
+  scryptCost: number;
+  scryptBlockSize: number;
+  scryptParallelization: number;
+  derivedKeyLength: number;
+  saltLength: number;
+  commonPasswordSha256: string[];
+}

package/src/_modules/account-security/_models/account-password-verification.interface.ts

@@ -0,0 +1,5 @@
+/** Content-free password verification result; never carries the password or derived bytes. */
+export interface DyNTS_AccountPasswordVerification_Interface {
+  isValid: boolean;
+  needsRehash: boolean;
+}

package/src/_modules/account-security/_models/account-refresh-token-record.interface.ts

@@ -0,0 +1,13 @@
+import { DyNTS_AccountRefreshTokenState_Type } from '../_enums/account-refresh-token-state.type-enum';
+
+/** Server-only one-time refresh-token ledger record. */
+export interface DyNTS_AccountRefreshTokenRecord_Interface {
+  tokenHash: string;
+  sessionId: string;
+  familyId: string;
+  subjectId: string;
+  generation: number;
+  state: DyNTS_AccountRefreshTokenState_Type;
+  expiresAt: string;
+  usedAt: string;
+}

package/src/_modules/account-security/_models/account-session-adapter.interface.ts

@@ -0,0 +1,19 @@
+import { DyNTS_AccountRefreshTokenRecord_Interface } from './account-refresh-token-record.interface';
+import { DyNTS_AccountSessionCreate_Interface } from './account-session-create.interface';
+import { DyNTS_AccountSessionRecord_Interface } from './account-session-record.interface';
+import { DyNTS_AccountSessionRotate_Interface } from './account-session-rotate.interface';
+
+/**
+ * Persistence contract. Implementations must make create and rotate atomic and apply compare-and-set semantics.
+ */
+export interface DyNTS_AccountSessionAdapter_Interface {
+  createSession(set: DyNTS_AccountSessionCreate_Interface): Promise<void>;
+  findSessionById(sessionId: string): Promise<DyNTS_AccountSessionRecord_Interface | null>;
+  findSessionByAccessTokenHash(accessTokenHash: string): Promise<DyNTS_AccountSessionRecord_Interface | null>;
+  findRefreshTokenByHash(tokenHash: string): Promise<DyNTS_AccountRefreshTokenRecord_Interface | null>;
+  rotateSession(set: DyNTS_AccountSessionRotate_Interface): Promise<boolean>;
+  revokeSession(sessionId: string, revokedAt: string, reasonCode: string): Promise<void>;
+  revokeFamily(familyId: string, revokedAt: string, reasonCode: string): Promise<void>;
+  revokeSubject(subjectId: string, revokedAt: string, reasonCode: string): Promise<void>;
+  listSubjectSessions(subjectId: string): Promise<DyNTS_AccountSessionRecord_Interface[]>;
+}

package/src/_modules/account-security/_models/account-session-claims.interface.ts

@@ -0,0 +1,7 @@
+/** Authenticated server-side subject projection derived from an opaque access token. */
+export interface DyNTS_AccountSessionClaims_Interface {
+  subjectId: string;
+  sessionId: string;
+  familyId: string;
+  authorizationVersion: number;
+}

package/src/_modules/account-security/_models/account-session-context.interface.ts

@@ -0,0 +1,6 @@
+/** Minimal, pre-redacted session context persisted for user-facing session recognition. */
+export interface DyNTS_AccountSessionContext_Interface {
+  deviceName: string;
+  ipAddressHash: string;
+  userAgentHash: string;
+}

package/src/_modules/account-security/_models/account-session-create.interface.ts

@@ -0,0 +1,8 @@
+import { DyNTS_AccountRefreshTokenRecord_Interface } from './account-refresh-token-record.interface';
+import { DyNTS_AccountSessionRecord_Interface } from './account-session-record.interface';
+
+/** Atomic session creation payload for a concrete Dynamo DataService adapter. */
+export interface DyNTS_AccountSessionCreate_Interface {
+  session: DyNTS_AccountSessionRecord_Interface;
+  refreshToken: DyNTS_AccountRefreshTokenRecord_Interface;
+}

package/src/_modules/account-security/_models/account-session-record.interface.ts

@@ -0,0 +1,21 @@
+import { DyNTS_AccountSessionState_Type } from '../_enums/account-session-state.type-enum';
+import { DyNTS_AccountSessionContext_Interface } from './account-session-context.interface';
+
+/** Server-only session record. It stores token hashes, never bearer credentials. */
+export interface DyNTS_AccountSessionRecord_Interface {
+  sessionId: string;
+  familyId: string;
+  subjectId: string;
+  accessTokenHash: string;
+  accessExpiresAt: string;
+  refreshExpiresAt: string;
+  state: DyNTS_AccountSessionState_Type;
+  generation: number;
+  revision: number;
+  authorizationVersion: number;
+  createdAt: string;
+  lastRotatedAt: string;
+  revokedAt: string;
+  revocationReason: string;
+  context: DyNTS_AccountSessionContext_Interface;
+}

package/src/_modules/account-security/_models/account-session-rotate.interface.ts

@@ -0,0 +1,11 @@
+import { DyNTS_AccountRefreshTokenRecord_Interface } from './account-refresh-token-record.interface';
+import { DyNTS_AccountSessionRecord_Interface } from './account-session-record.interface';
+
+/** Atomic one-time refresh rotation payload for a concrete Dynamo DataService adapter. */
+export interface DyNTS_AccountSessionRotate_Interface {
+  expectedSessionRevision: number;
+  currentRefreshTokenHash: string;
+  usedAt: string;
+  replacementSession: DyNTS_AccountSessionRecord_Interface;
+  replacementRefreshToken: DyNTS_AccountRefreshTokenRecord_Interface;
+}

package/src/_modules/account-security/_models/account-session-settings.interface.ts

@@ -0,0 +1,11 @@
+import { DyNTS_AccountSessionAdapter_Interface } from './account-session-adapter.interface';
+
+/** Runtime settings for opaque access credentials and rotating one-time refresh families. */
+export interface DyNTS_AccountSessionSettings_Interface {
+  adapter: DyNTS_AccountSessionAdapter_Interface;
+  accessTtlMs?: number;
+  refreshTtlMs?: number;
+  tokenBytes?: number;
+  maxRefreshRotations?: number;
+  clock?: () => Date;
+}

package/src/_modules/account-security/_models/account-session-token-pair.interface.ts

@@ -0,0 +1,8 @@
+/** Raw credentials returned exactly once to the transport layer after an atomic persistence commit. */
+export interface DyNTS_AccountSessionTokenPair_Interface {
+  sessionId: string;
+  accessToken: string;
+  refreshToken: string;
+  accessExpiresAt: string;
+  refreshExpiresAt: string;
+}

package/src/_modules/account-security/_models/account-session-view.interface.ts

@@ -0,0 +1,13 @@
+import { DyNTS_AccountSessionState_Type } from '../_enums/account-session-state.type-enum';
+import { DyNTS_AccountSessionContext_Interface } from './account-session-context.interface';
+
+/** User-safe session list item without access or refresh token hashes. */
+export interface DyNTS_AccountSessionView_Interface {
+  sessionId: string;
+  state: DyNTS_AccountSessionState_Type;
+  createdAt: string;
+  lastRotatedAt: string;
+  accessExpiresAt: string;
+  refreshExpiresAt: string;
+  context: DyNTS_AccountSessionContext_Interface;
+}

package/src/_modules/account-security/account-challenge.control-service.spec.ts

@@ -0,0 +1,195 @@
+import { createHash } from 'crypto';
+
+import { DyFM_Error } from '@futdevpro/fsm-dynamo';
+
+import { DyNTS_AccountChallenge_ControlService } from './account-challenge.control-service';
+import { DyNTS_AccountChallengePurpose_Type } from './_enums/account-challenge-purpose.type-enum';
+import { DyNTS_AccountChallengeAdapter_Interface } from './_models/account-challenge-adapter.interface';
+import { DyNTS_AccountChallengeIssued_Interface } from './_models/account-challenge-issued.interface';
+import { DyNTS_AccountChallengeRecord_Interface } from './_models/account-challenge-record.interface';
+import { DyNTS_AccountChallengeResult_Interface } from './_models/account-challenge-result.interface';
+
+class DyNTS_TestChallengeAdapter implements DyNTS_AccountChallengeAdapter_Interface {
+  public readonly challenges: Map<string, DyNTS_AccountChallengeRecord_Interface> = new Map();
+
+  /** Revokes the predecessor and persists the replacement atomically in memory. */
+  public async replaceActiveChallenge(record: DyNTS_AccountChallengeRecord_Interface): Promise<void> {
+    Array.from(this.challenges.values())
+      .filter((item: DyNTS_AccountChallengeRecord_Interface): boolean => (
+        item.subjectId === record.subjectId
+        && item.purpose === record.purpose
+        && !item.consumedAt
+        && !item.revokedAt
+      ))
+      .forEach((item: DyNTS_AccountChallengeRecord_Interface): void => {
+        item.revokedAt = record.createdAt;
+      });
+    this.challenges.set(record.tokenHash, { ...record });
+  }
+
+  /** Consumes one active and unexpired test challenge with compare-and-set semantics. */
+  public async consumeActiveChallenge(
+    tokenHash: string,
+    purpose: DyNTS_AccountChallengePurpose_Type,
+    consumedAt: string
+  ): Promise<DyNTS_AccountChallengeRecord_Interface | null> {
+    const record: DyNTS_AccountChallengeRecord_Interface | undefined = this.challenges.get(tokenHash);
+
+    if (
+      record?.purpose !== purpose
+      || !!record.consumedAt
+      || !!record.revokedAt
+      || new Date(record.expiresAt).getTime() <= new Date(consumedAt).getTime()
+    ) {
+      return null;
+    }
+
+    record.consumedAt = consumedAt;
+
+    return { ...record };
+  }
+
+  /** Revokes active test challenges for one subject-purpose pair. */
+  public async revokeSubjectChallenges(
+    subjectId: string,
+    purpose: DyNTS_AccountChallengePurpose_Type,
+    revokedAt: string
+  ): Promise<void> {
+    Array.from(this.challenges.values())
+      .filter((item: DyNTS_AccountChallengeRecord_Interface): boolean => (
+        item.subjectId === subjectId && item.purpose === purpose && !item.consumedAt
+      ))
+      .forEach((item: DyNTS_AccountChallengeRecord_Interface): void => {
+        item.revokedAt = revokedAt;
+      });
+  }
+}
+
+describe('| DyNTS_AccountChallenge_ControlService', (): void => {
+  let now: Date;
+  let adapter: DyNTS_TestChallengeAdapter;
+  let service: DyNTS_AccountChallenge_ControlService;
+
+  beforeEach((): void => {
+    now = new Date('2026-08-18T10:00:00.000Z');
+    adapter = new DyNTS_TestChallengeAdapter();
+    service = new DyNTS_AccountChallenge_ControlService({
+      adapter: adapter,
+      ttlMs: 60_000,
+      clock: (): Date => new Date(now),
+    });
+  });
+
+  it('| persists only the token hash and consumes the subject binding once', async (): Promise<void> => {
+    const issued: DyNTS_AccountChallengeIssued_Interface = await service.issueChallenge(
+      'subject-1',
+      DyNTS_AccountChallengePurpose_Type.emailVerification
+    );
+    const stored: DyNTS_AccountChallengeRecord_Interface | undefined =
+      adapter.challenges.get(hashToken(issued.token));
+    const result: DyNTS_AccountChallengeResult_Interface = await service.consumeChallenge(
+      issued.token,
+      DyNTS_AccountChallengePurpose_Type.emailVerification
+    );
+
+    expect(stored?.tokenHash).toBe(hashToken(issued.token));
+    expect(JSON.stringify(Array.from(adapter.challenges.values()))).not.toContain(issued.token);
+    expect(result.subjectId).toBe('subject-1');
+    await expectAsync(service.consumeChallenge(
+      issued.token,
+      DyNTS_AccountChallengePurpose_Type.emailVerification
+    )).toBeRejectedWithError(DyFM_Error);
+  });
+
+  it('| replaces the previous active challenge for the same purpose', async (): Promise<void> => {
+    const first: DyNTS_AccountChallengeIssued_Interface = await service.issueChallenge(
+      'subject-1',
+      DyNTS_AccountChallengePurpose_Type.passwordReset
+    );
+    const second: DyNTS_AccountChallengeIssued_Interface = await service.issueChallenge(
+      'subject-1',
+      DyNTS_AccountChallengePurpose_Type.passwordReset
+    );
+
+    await expectAsync(service.consumeChallenge(
+      first.token,
+      DyNTS_AccountChallengePurpose_Type.passwordReset
+    )).toBeRejectedWithError(DyFM_Error);
+    expect((await service.consumeChallenge(
+      second.token,
+      DyNTS_AccountChallengePurpose_Type.passwordReset
+    )).subjectId).toBe('subject-1');
+  });
+
+  it('| rejects purpose confusion and expiry without exposing token content', async (): Promise<void> => {
+    const issued: DyNTS_AccountChallengeIssued_Interface = await service.issueChallenge(
+      'subject-1',
+      DyNTS_AccountChallengePurpose_Type.emailVerification
+    );
+    const purposeError: DyFM_Error = await captureError(service.consumeChallenge(
+      issued.token,
+      DyNTS_AccountChallengePurpose_Type.passwordReset
+    ));
+
+    now = new Date('2026-08-18T10:01:00.001Z');
+    const expiryError: DyFM_Error = await captureError(service.consumeChallenge(
+      issued.token,
+      DyNTS_AccountChallengePurpose_Type.emailVerification
+    ));
+
+    expect(purposeError._message).not.toContain(issued.token);
+    expect(expiryError._errorCode).toContain('CHALLENGE_INVALID');
+  });
+
+  it('| revokes outstanding challenges for a subject and purpose', async (): Promise<void> => {
+    const issued: DyNTS_AccountChallengeIssued_Interface = await service.issueChallenge(
+      'subject-1',
+      DyNTS_AccountChallengePurpose_Type.passwordReset
+    );
+
+    await service.revokeSubjectChallenges('subject-1', DyNTS_AccountChallengePurpose_Type.passwordReset);
+
+    await expectAsync(service.consumeChallenge(
+      issued.token,
+      DyNTS_AccountChallengePurpose_Type.passwordReset
+    )).toBeRejectedWithError(DyFM_Error);
+  });
+
+  it('| rejects a corrupt expiry and oversized hostile input', async (): Promise<void> => {
+    const issued: DyNTS_AccountChallengeIssued_Interface = await service.issueChallenge(
+      'subject-1',
+      DyNTS_AccountChallengePurpose_Type.passwordReset
+    );
+    const stored: DyNTS_AccountChallengeRecord_Interface | undefined =
+      adapter.challenges.get(hashToken(issued.token));
+
+    if (stored) {
+      stored.expiresAt = 'not-a-date';
+    }
+
+    await expectAsync(service.consumeChallenge(
+      issued.token,
+      DyNTS_AccountChallengePurpose_Type.passwordReset
+    )).toBeRejectedWithError(DyFM_Error);
+    await expectAsync(service.consumeChallenge(
+      'x'.repeat(513),
+      DyNTS_AccountChallengePurpose_Type.passwordReset
+    )).toBeRejectedWithError(DyFM_Error);
+  });
+});
+
+function hashToken(token: string): string {
+  return createHash('sha256').update(token).digest('hex');
+}
+
+async function captureError(promise: Promise<unknown>): Promise<DyFM_Error> {
+  try {
+    await promise;
+  } catch (error: unknown) {
+    if (error instanceof DyFM_Error) {
+      return error;
+    }
+  }
+
+  throw new Error('Expected a DyFM_Error rejection.');
+}

package/src/_modules/account-security/account-challenge.control-service.ts

@@ -0,0 +1,164 @@
+import {
+  createHash,
+  randomBytes,
+  randomUUID
+} from 'crypto';
+
+import { DyFM_Error } from '@futdevpro/fsm-dynamo';
+
+import { DyNTS_global_settings } from '../../_collections/global-settings.const';
+import { DyNTS_AccountChallengePurpose_Type } from './_enums/account-challenge-purpose.type-enum';
+import { DyNTS_AccountChallengeAdapter_Interface } from './_models/account-challenge-adapter.interface';
+import { DyNTS_AccountChallengeIssued_Interface } from './_models/account-challenge-issued.interface';
+import { DyNTS_AccountChallengeRecord_Interface } from './_models/account-challenge-record.interface';
+import { DyNTS_AccountChallengeResult_Interface } from './_models/account-challenge-result.interface';
+import { DyNTS_AccountChallengeSettings_Interface } from './_models/account-challenge-settings.interface';
+
+const DEFAULT_CHALLENGE_TTL_MS: number = 15 * 60 * 1000;
+const DEFAULT_TOKEN_BYTES: number = 32;
+
+/** Issues and atomically consumes opaque email-verification and password-reset credentials. */
+export class DyNTS_AccountChallenge_ControlService {
+  private readonly adapter: DyNTS_AccountChallengeAdapter_Interface;
+  private readonly ttlMs: number;
+  private readonly tokenBytes: number;
+  private readonly clock: () => Date;
+
+  /** Creates a challenge service over an atomic persistence adapter. */
+  constructor(set: DyNTS_AccountChallengeSettings_Interface) {
+    this.adapter = set.adapter;
+    this.ttlMs = set.ttlMs ?? DEFAULT_CHALLENGE_TTL_MS;
+    this.tokenBytes = set.tokenBytes ?? DEFAULT_TOKEN_BYTES;
+    this.clock = set.clock ?? ((): Date => new Date());
+    this.validateSettings();
+  }
+
+  /** Replaces any active subject-purpose challenge before returning the new raw credential once. */
+  public async issueChallenge(
+    subjectId: string,
+    purpose: DyNTS_AccountChallengePurpose_Type
+  ): Promise<DyNTS_AccountChallengeIssued_Interface> {
+    if (
+      !subjectId
+      || subjectId.length > 256
+      || !Object.values(DyNTS_AccountChallengePurpose_Type).includes(purpose)
+    ) {
+      throw this.buildInvalid('CHALLENGE_REQUEST_INVALID');
+    }
+
+    const now: Date = this.clock();
+    const token: string = randomBytes(this.tokenBytes).toString('base64url');
+    const record: DyNTS_AccountChallengeRecord_Interface = {
+      challengeId: randomUUID(),
+      subjectId: subjectId,
+      purpose: purpose,
+      tokenHash: this.hashToken(token),
+      createdAt: now.toISOString(),
+      expiresAt: new Date(now.getTime() + this.ttlMs).toISOString(),
+      consumedAt: '',
+      revokedAt: '',
+    };
+
+    await this.adapter.replaceActiveChallenge(record);
+
+    return {
+      challengeId: record.challengeId,
+      token: token,
+      expiresAt: record.expiresAt,
+    };
+  }
+
+  /** Atomically consumes one unexpired challenge and returns its trusted subject binding. */
+  public async consumeChallenge(
+    token: string,
+    purpose: DyNTS_AccountChallengePurpose_Type
+  ): Promise<DyNTS_AccountChallengeResult_Interface> {
+    if (
+      !token
+      || token.length > 512
+      || !Object.values(DyNTS_AccountChallengePurpose_Type).includes(purpose)
+    ) {
+      throw this.buildInvalid('CHALLENGE_INVALID');
+    }
+
+    const now: Date = this.clock();
+    const tokenHash: string = this.hashToken(token);
+    const record: DyNTS_AccountChallengeRecord_Interface | null = await this.adapter.consumeActiveChallenge(
+      tokenHash,
+      purpose,
+      now.toISOString()
+    );
+
+    if (
+      record?.purpose !== purpose
+      || record.tokenHash !== tokenHash
+      || !record.consumedAt
+      || !!record.revokedAt
+      || !this.isFutureDate(record.expiresAt, now)
+    ) {
+      throw this.buildInvalid('CHALLENGE_INVALID');
+    }
+
+    return {
+      challengeId: record.challengeId,
+      subjectId: record.subjectId,
+      purpose: record.purpose,
+    };
+  }
+
+  /** Revokes every active challenge for a subject-purpose pair. */
+  public async revokeSubjectChallenges(
+    subjectId: string,
+    purpose: DyNTS_AccountChallengePurpose_Type
+  ): Promise<void> {
+    if (
+      !subjectId
+      || subjectId.length > 256
+      || !Object.values(DyNTS_AccountChallengePurpose_Type).includes(purpose)
+    ) {
+      throw this.buildInvalid('CHALLENGE_REQUEST_INVALID');
+    }
+
+    await this.adapter.revokeSubjectChallenges(subjectId, purpose, this.clock().toISOString());
+  }
+
+  private hashToken(token: string): string {
+    return createHash('sha256').update(token).digest('hex');
+  }
+
+  private validateSettings(): void {
+    if (
+      !this.adapter
+      || !Number.isSafeInteger(this.ttlMs)
+      || this.ttlMs < 60_000
+      || this.ttlMs > 24 * 60 * 60 * 1000
+      || !Number.isSafeInteger(this.tokenBytes)
+      || this.tokenBytes < 32
+      || this.tokenBytes > 128
+    ) {
+      throw new DyFM_Error({
+        status: 500,
+        errorCode: `${DyNTS_global_settings.systemShortCodeName}|ACCOUNT_SECURITY|CHALLENGE_SETTINGS_INVALID`,
+        message: 'The account challenge settings are outside supported safe bounds.',
+        userMessage: 'The account security service is unavailable.',
+        issuerService: this.constructor.name,
+      });
+    }
+  }
+
+  private isFutureDate(value: string, now: Date): boolean {
+    const timestamp: number = new Date(value).getTime();
+
+    return Number.isFinite(timestamp) && timestamp > now.getTime();
+  }
+
+  private buildInvalid(errorCode: string): DyFM_Error {
+    return new DyFM_Error({
+      status: 401,
+      errorCode: `${DyNTS_global_settings.systemShortCodeName}|ACCOUNT_SECURITY|${errorCode}`,
+      message: 'Opaque one-time account challenge validation failed.',
+      userMessage: 'The verification request is invalid or has expired. Please request a new one.',
+      issuerService: this.constructor.name,
+    });
+  }
+}