@futdevpro/nts-dynamo 1.15.140 → 1.15.141

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,
+    });
+  }
+}

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

@@ -0,0 +1,96 @@
+import { createHash } from 'crypto';
+
+import { DyFM_Error } from '@futdevpro/fsm-dynamo';
+
+import { DyNTS_AccountPassword_ControlService } from './account-password.control-service';
+import {
+  DyNTS_AccountPasswordVerification_Interface
+} from './_models/account-password-verification.interface';
+
+describe('| DyNTS_AccountPassword_ControlService', (): void => {
+  it('| hashes with unique salts and verifies the matching password', async (): Promise<void> => {
+    const service: DyNTS_AccountPassword_ControlService = new DyNTS_AccountPassword_ControlService();
+    const firstHash: string = await service.hashPassword('correct horse battery staple');
+    const secondHash: string = await service.hashPassword('correct horse battery staple');
+    const result: DyNTS_AccountPasswordVerification_Interface = await service.verifyPassword(
+      'correct horse battery staple',
+      firstHash
+    );
+
+    expect(firstHash).not.toBe(secondHash);
+    expect(firstHash).not.toContain('correct horse');
+    expect(result).toEqual({ isValid: true, needsRehash: false });
+  });
+
+  it('| rejects a wrong password without returning credential material', async (): Promise<void> => {
+    const service: DyNTS_AccountPassword_ControlService = new DyNTS_AccountPassword_ControlService();
+    const storedHash: string = await service.hashPassword('correct horse battery staple');
+    const result: DyNTS_AccountPasswordVerification_Interface = await service.verifyPassword(
+      'wrong password value',
+      storedHash
+    );
+
+    expect(result).toEqual({ isValid: false, needsRehash: false });
+    expect(Object.keys(result)).toEqual([ 'isValid', 'needsRehash' ]);
+  });
+
+  it('| performs a safe negative result for malformed or attacker-cost hashes', async (): Promise<void> => {
+    const service: DyNTS_AccountPassword_ControlService = new DyNTS_AccountPassword_ControlService();
+    const malformed: DyNTS_AccountPasswordVerification_Interface = await service.verifyPassword(
+      'candidate password',
+      'dyn-scrypt-v1$1073741824$8$1$c2FsdA$aGFzaA'
+    );
+
+    expect(malformed).toEqual({ isValid: false, needsRehash: false });
+  });
+
+  it('| bounds hostile candidate and stored-hash input before verification work', async (): Promise<void> => {
+    const service: DyNTS_AccountPassword_ControlService = new DyNTS_AccountPassword_ControlService();
+    const result: DyNTS_AccountPasswordVerification_Interface = await service.verifyPassword(
+      'x'.repeat(129),
+      'x'.repeat(2_000)
+    );
+
+    expect(result).toEqual({ isValid: false, needsRehash: false });
+  });
+
+  it('| reports a valid legacy-cost hash as needing rehash', async (): Promise<void> => {
+    const legacy: DyNTS_AccountPassword_ControlService = new DyNTS_AccountPassword_ControlService({
+      scryptCost: 8_192,
+    });
+    const current: DyNTS_AccountPassword_ControlService = new DyNTS_AccountPassword_ControlService();
+    const storedHash: string = await legacy.hashPassword('correct horse battery staple');
+    const result: DyNTS_AccountPasswordVerification_Interface = await current.verifyPassword(
+      'correct horse battery staple',
+      storedHash
+    );
+
+    expect(result).toEqual({ isValid: true, needsRehash: true });
+  });
+
+  it('| rejects configured common passwords with a content-free stable error', (): void => {
+    const commonPassword: string = 'very common password';
+    const digest: string = createHash('sha256')
+      .update(commonPassword)
+      .digest('hex');
+    const service: DyNTS_AccountPassword_ControlService = new DyNTS_AccountPassword_ControlService({
+      commonPasswordSha256: [ digest ],
+    });
+    let capturedError: DyFM_Error | null = null;
+
+    try {
+      service.validatePassword(commonPassword);
+    } catch (error: unknown) {
+      capturedError = error instanceof DyFM_Error ? error : null;
+    }
+
+    expect(capturedError?._errorCode).toContain('PASSWORD_POLICY_COMMON');
+    expect(capturedError?._message).not.toContain(commonPassword);
+  });
+
+  it('| rejects unsafe policy settings before hashing starts', (): void => {
+    expect((): DyNTS_AccountPassword_ControlService => new DyNTS_AccountPassword_ControlService({
+      scryptCost: 15_000,
+    })).toThrowError(DyFM_Error);
+  });
+});