@futdevpro/nts-dynamo 1.15.151 → 1.15.154

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

@@ -1,288 +1,288 @@
-import {
-  createHash,
-  randomBytes,
-  scrypt,
-  timingSafeEqual
-} from 'crypto';
-
-import { DyFM_Error } from '@futdevpro/fsm-dynamo';
-
-import { DyNTS_global_settings } from '../../_collections/global-settings.const';
-import {
-  DyNTS_AccountPasswordPolicy_Interface
-} from './_models/account-password-policy.interface';
-import {
-  DyNTS_AccountPasswordVerification_Interface
-} from './_models/account-password-verification.interface';
-
-const PASSWORD_HASH_VERSION: string = 'dyn-scrypt-v1';
-const DEFAULT_POLICY: DyNTS_AccountPasswordPolicy_Interface = {
-  minLength: 12,
-  maxLength: 128,
-  scryptCost: 16_384,
-  scryptBlockSize: 8,
-  scryptParallelization: 1,
-  derivedKeyLength: 32,
-  saltLength: 16,
-  commonPasswordSha256: [],
-};
-const MAX_VERIFY_COST: number = 131_072;
-const MAX_VERIFY_BLOCK_SIZE: number = 8;
-const MAX_VERIFY_PARALLELIZATION: number = 2;
-const MAX_VERIFY_KEY_LENGTH: number = 64;
-const MAX_PASSWORD_LENGTH: number = 1_024;
-const MAX_STORED_HASH_LENGTH: number = 1_024;
-
-interface DyNTS_ParsedPasswordHash {
-  cost: number;
-  blockSize: number;
-  parallelization: number;
-  salt: Buffer;
-  derivedKey: Buffer;
-}
-
-interface DyNTS_ScryptDerivationSettings {
-  password: string;
-  salt: Buffer;
-  cost: number;
-  blockSize: number;
-  parallelization: number;
-  keyLength: number;
-}
-
-/**
- * Standalone password capability using versioned Node scrypt hashes.
- * Passwords and derived bytes never enter errors, logs or result objects.
- */
-export class DyNTS_AccountPassword_ControlService {
-  private readonly policy: DyNTS_AccountPasswordPolicy_Interface;
-
-  /** Creates a validated immutable policy snapshot. */
-  constructor(policy?: Partial<DyNTS_AccountPasswordPolicy_Interface>) {
-    this.policy = {
-      ...DEFAULT_POLICY,
-      ...policy,
-      commonPasswordSha256: [
-        ...(policy?.commonPasswordSha256 ?? DEFAULT_POLICY.commonPasswordSha256),
-      ],
-    };
-    this.validatePolicy();
-  }
-
-  /** Validates and hashes one password to a self-describing scrypt record. */
-  public async hashPassword(password: string): Promise<string> {
-    this.validatePassword(password);
-
-    const salt: Buffer = randomBytes(this.policy.saltLength);
-    const derivedKey: Buffer = await this.deriveKey({
-      password: password,
-      salt: salt,
-      cost: this.policy.scryptCost,
-      blockSize: this.policy.scryptBlockSize,
-      parallelization: this.policy.scryptParallelization,
-      keyLength: this.policy.derivedKeyLength,
-    });
-
-    return [
-      PASSWORD_HASH_VERSION,
-      this.policy.scryptCost,
-      this.policy.scryptBlockSize,
-      this.policy.scryptParallelization,
-      salt.toString('base64url'),
-      derivedKey.toString('base64url'),
-    ].join('$');
-  }
-
-  /** Performs constant-time verification and reports whether the stored cost should be upgraded. */
-  public async verifyPassword(
-    password: string,
-    storedHash: string
-  ): Promise<DyNTS_AccountPasswordVerification_Interface> {
-    if (typeof password !== 'string' || Array.from(password).length > this.policy.maxLength) {
-      await this.runDummyDerivation('invalid-password-candidate');
-
-      return { isValid: false, needsRehash: false };
-    }
-
-    const parsed: DyNTS_ParsedPasswordHash | null = this.parseHash(storedHash);
-
-    if (!parsed) {
-      await this.runDummyDerivation(password);
-
-      return { isValid: false, needsRehash: false };
-    }
-
-    let candidate: Buffer;
-
-    try {
-      candidate = await this.deriveKey({
-        password: password,
-        salt: parsed.salt,
-        cost: parsed.cost,
-        blockSize: parsed.blockSize,
-        parallelization: parsed.parallelization,
-        keyLength: parsed.derivedKey.length,
-      });
-    } catch {
-      await this.runDummyDerivation(password);
-
-      return { isValid: false, needsRehash: false };
-    }
-
-    const isValid: boolean = candidate.length === parsed.derivedKey.length
-      && timingSafeEqual(candidate, parsed.derivedKey);
-
-    return {
-      isValid: isValid,
-      needsRehash: isValid && (
-        parsed.cost !== this.policy.scryptCost
-        || parsed.blockSize !== this.policy.scryptBlockSize
-        || parsed.parallelization !== this.policy.scryptParallelization
-        || parsed.derivedKey.length !== this.policy.derivedKeyLength
-        || parsed.salt.length !== this.policy.saltLength
-      ),
-    };
-  }
-
-  /** Rejects weak, oversized and configured common passwords without exposing their content. */
-  public validatePassword(password: string): void {
-    if (typeof password !== 'string') {
-      throw this.buildError('PASSWORD_POLICY_LENGTH', 'Password input must be a string.');
-    }
-
-    const passwordLength: number = Array.from(password).length;
-
-    if (passwordLength < this.policy.minLength || passwordLength > this.policy.maxLength) {
-      throw this.buildError(
-        'PASSWORD_POLICY_LENGTH',
-        `Password length must be between ${this.policy.minLength} and ${this.policy.maxLength} characters.`
-      );
-    }
-
-    const commonDigest: string = createHash('sha256')
-      .update(password.normalize('NFKC').toLocaleLowerCase('en-US'))
-      .digest('hex');
-
-    if (this.policy.commonPasswordSha256.includes(commonDigest)) {
-      throw this.buildError(
-        'PASSWORD_POLICY_COMMON',
-        'The password matches a configured common-password denylist entry.'
-      );
-    }
-  }
-
-  private parseHash(storedHash: string): DyNTS_ParsedPasswordHash | null {
-    if (typeof storedHash !== 'string' || storedHash.length > MAX_STORED_HASH_LENGTH) {
-      return null;
-    }
-
-    const parts: string[] = storedHash.split('$');
-
-    if (parts.length !== 6 || parts[0] !== PASSWORD_HASH_VERSION) {
-      return null;
-    }
-
-    const cost: number = Number(parts[1]);
-    const blockSize: number = Number(parts[2]);
-    const parallelization: number = Number(parts[3]);
-    const salt: Buffer = Buffer.from(parts[4], 'base64url');
-    const derivedKey: Buffer = Buffer.from(parts[5], 'base64url');
-
-    if (
-      !this.isPowerOfTwo(cost)
-      || cost < 2
-      || cost > MAX_VERIFY_COST
-      || !Number.isInteger(blockSize)
-      || blockSize < 1
-      || blockSize > MAX_VERIFY_BLOCK_SIZE
-      || !Number.isInteger(parallelization)
-      || parallelization < 1
-      || parallelization > MAX_VERIFY_PARALLELIZATION
-      || !salt.length
-      || !derivedKey.length
-      || derivedKey.length > MAX_VERIFY_KEY_LENGTH
-    ) {
-      return null;
-    }
-
-    return {
-      cost: cost,
-      blockSize: blockSize,
-      parallelization: parallelization,
-      salt: salt,
-      derivedKey: derivedKey,
-    };
-  }
-
-  private async runDummyDerivation(password: string): Promise<void> {
-    await this.deriveKey({
-      password: password,
-      salt: Buffer.alloc(this.policy.saltLength),
-      cost: this.policy.scryptCost,
-      blockSize: this.policy.scryptBlockSize,
-      parallelization: this.policy.scryptParallelization,
-      keyLength: this.policy.derivedKeyLength,
-    });
-  }
-
-  private deriveKey(set: DyNTS_ScryptDerivationSettings): Promise<Buffer> {
-    return new Promise<Buffer>((resolve: (value: Buffer) => void, reject: (reason: unknown) => void): void => {
-      const maxmem: number = Math.max(32 * 1024 * 1024, 256 * set.cost * set.blockSize);
-
-      scrypt(set.password, set.salt, set.keyLength, {
-        N: set.cost,
-        r: set.blockSize,
-        p: set.parallelization,
-        maxmem: maxmem,
-      }, (error: Error | null, derivedKey: Buffer): void => {
-        if (error) {
-          reject(error);
-
-          return;
-        }
-
-        resolve(derivedKey);
-      });
-    });
-  }
-
-  private validatePolicy(): void {
-    if (
-      !Number.isInteger(this.policy.minLength)
-      || !Number.isInteger(this.policy.maxLength)
-      || this.policy.minLength < 8
-      || this.policy.maxLength < this.policy.minLength
-      || this.policy.maxLength > MAX_PASSWORD_LENGTH
-      || !this.isPowerOfTwo(this.policy.scryptCost)
-      || this.policy.scryptCost > MAX_VERIFY_COST
-      || !Number.isInteger(this.policy.scryptBlockSize)
-      || this.policy.scryptBlockSize < 1
-      || this.policy.scryptBlockSize > MAX_VERIFY_BLOCK_SIZE
-      || !Number.isInteger(this.policy.scryptParallelization)
-      || this.policy.scryptParallelization < 1
-      || this.policy.scryptParallelization > MAX_VERIFY_PARALLELIZATION
-      || !Number.isInteger(this.policy.derivedKeyLength)
-      || this.policy.derivedKeyLength < 16
-      || this.policy.derivedKeyLength > MAX_VERIFY_KEY_LENGTH
-      || !Number.isInteger(this.policy.saltLength)
-      || this.policy.saltLength < 16
-      || this.policy.saltLength > 64
-    ) {
-      throw this.buildError('PASSWORD_POLICY_INVALID', 'The password policy is outside supported safe bounds.');
-    }
-  }
-
-  private isPowerOfTwo(value: number): boolean {
-    return Number.isSafeInteger(value) && value > 0 && (value & (value - 1)) === 0;
-  }
-
-  private buildError(errorCode: string, message: string): DyFM_Error {
-    return new DyFM_Error({
-      status: 400,
-      errorCode: `${DyNTS_global_settings.systemShortCodeName}|ACCOUNT_SECURITY|${errorCode}`,
-      message: message,
-      userMessage: 'The credential does not satisfy the account security policy.',
-      issuerService: this.constructor.name,
-    });
-  }
-}
+import {
+  createHash,
+  randomBytes,
+  scrypt,
+  timingSafeEqual
+} from 'crypto';
+
+import { DyFM_Error } from '@futdevpro/fsm-dynamo';
+
+import { DyNTS_global_settings } from '../../_collections/global-settings.const';
+import {
+  DyNTS_AccountPasswordPolicy_Interface
+} from './_models/account-password-policy.interface';
+import {
+  DyNTS_AccountPasswordVerification_Interface
+} from './_models/account-password-verification.interface';
+
+const PASSWORD_HASH_VERSION: string = 'dyn-scrypt-v1';
+const DEFAULT_POLICY: DyNTS_AccountPasswordPolicy_Interface = {
+  minLength: 12,
+  maxLength: 128,
+  scryptCost: 16_384,
+  scryptBlockSize: 8,
+  scryptParallelization: 1,
+  derivedKeyLength: 32,
+  saltLength: 16,
+  commonPasswordSha256: [],
+};
+const MAX_VERIFY_COST: number = 131_072;
+const MAX_VERIFY_BLOCK_SIZE: number = 8;
+const MAX_VERIFY_PARALLELIZATION: number = 2;
+const MAX_VERIFY_KEY_LENGTH: number = 64;
+const MAX_PASSWORD_LENGTH: number = 1_024;
+const MAX_STORED_HASH_LENGTH: number = 1_024;
+
+interface DyNTS_ParsedPasswordHash {
+  cost: number;
+  blockSize: number;
+  parallelization: number;
+  salt: Buffer;
+  derivedKey: Buffer;
+}
+
+interface DyNTS_ScryptDerivationSettings {
+  password: string;
+  salt: Buffer;
+  cost: number;
+  blockSize: number;
+  parallelization: number;
+  keyLength: number;
+}
+
+/**
+ * Standalone password capability using versioned Node scrypt hashes.
+ * Passwords and derived bytes never enter errors, logs or result objects.
+ */
+export class DyNTS_AccountPassword_ControlService {
+  private readonly policy: DyNTS_AccountPasswordPolicy_Interface;
+
+  /** Creates a validated immutable policy snapshot. */
+  constructor(policy?: Partial<DyNTS_AccountPasswordPolicy_Interface>) {
+    this.policy = {
+      ...DEFAULT_POLICY,
+      ...policy,
+      commonPasswordSha256: [
+        ...(policy?.commonPasswordSha256 ?? DEFAULT_POLICY.commonPasswordSha256),
+      ],
+    };
+    this.validatePolicy();
+  }
+
+  /** Validates and hashes one password to a self-describing scrypt record. */
+  public async hashPassword(password: string): Promise<string> {
+    this.validatePassword(password);
+
+    const salt: Buffer = randomBytes(this.policy.saltLength);
+    const derivedKey: Buffer = await this.deriveKey({
+      password: password,
+      salt: salt,
+      cost: this.policy.scryptCost,
+      blockSize: this.policy.scryptBlockSize,
+      parallelization: this.policy.scryptParallelization,
+      keyLength: this.policy.derivedKeyLength,
+    });
+
+    return [
+      PASSWORD_HASH_VERSION,
+      this.policy.scryptCost,
+      this.policy.scryptBlockSize,
+      this.policy.scryptParallelization,
+      salt.toString('base64url'),
+      derivedKey.toString('base64url'),
+    ].join('$');
+  }
+
+  /** Performs constant-time verification and reports whether the stored cost should be upgraded. */
+  public async verifyPassword(
+    password: string,
+    storedHash: string
+  ): Promise<DyNTS_AccountPasswordVerification_Interface> {
+    if (typeof password !== 'string' || Array.from(password).length > this.policy.maxLength) {
+      await this.runDummyDerivation('invalid-password-candidate');
+
+      return { isValid: false, needsRehash: false };
+    }
+
+    const parsed: DyNTS_ParsedPasswordHash | null = this.parseHash(storedHash);
+
+    if (!parsed) {
+      await this.runDummyDerivation(password);
+
+      return { isValid: false, needsRehash: false };
+    }
+
+    let candidate: Buffer;
+
+    try {
+      candidate = await this.deriveKey({
+        password: password,
+        salt: parsed.salt,
+        cost: parsed.cost,
+        blockSize: parsed.blockSize,
+        parallelization: parsed.parallelization,
+        keyLength: parsed.derivedKey.length,
+      });
+    } catch {
+      await this.runDummyDerivation(password);
+
+      return { isValid: false, needsRehash: false };
+    }
+
+    const isValid: boolean = candidate.length === parsed.derivedKey.length
+      && timingSafeEqual(candidate, parsed.derivedKey);
+
+    return {
+      isValid: isValid,
+      needsRehash: isValid && (
+        parsed.cost !== this.policy.scryptCost
+        || parsed.blockSize !== this.policy.scryptBlockSize
+        || parsed.parallelization !== this.policy.scryptParallelization
+        || parsed.derivedKey.length !== this.policy.derivedKeyLength
+        || parsed.salt.length !== this.policy.saltLength
+      ),
+    };
+  }
+
+  /** Rejects weak, oversized and configured common passwords without exposing their content. */
+  public validatePassword(password: string): void {
+    if (typeof password !== 'string') {
+      throw this.buildError('PASSWORD_POLICY_LENGTH', 'Password input must be a string.');
+    }
+
+    const passwordLength: number = Array.from(password).length;
+
+    if (passwordLength < this.policy.minLength || passwordLength > this.policy.maxLength) {
+      throw this.buildError(
+        'PASSWORD_POLICY_LENGTH',
+        `Password length must be between ${this.policy.minLength} and ${this.policy.maxLength} characters.`
+      );
+    }
+
+    const commonDigest: string = createHash('sha256')
+      .update(password.normalize('NFKC').toLocaleLowerCase('en-US'))
+      .digest('hex');
+
+    if (this.policy.commonPasswordSha256.includes(commonDigest)) {
+      throw this.buildError(
+        'PASSWORD_POLICY_COMMON',
+        'The password matches a configured common-password denylist entry.'
+      );
+    }
+  }
+
+  private parseHash(storedHash: string): DyNTS_ParsedPasswordHash | null {
+    if (typeof storedHash !== 'string' || storedHash.length > MAX_STORED_HASH_LENGTH) {
+      return null;
+    }
+
+    const parts: string[] = storedHash.split('$');
+
+    if (parts.length !== 6 || parts[0] !== PASSWORD_HASH_VERSION) {
+      return null;
+    }
+
+    const cost: number = Number(parts[1]);
+    const blockSize: number = Number(parts[2]);
+    const parallelization: number = Number(parts[3]);
+    const salt: Buffer = Buffer.from(parts[4], 'base64url');
+    const derivedKey: Buffer = Buffer.from(parts[5], 'base64url');
+
+    if (
+      !this.isPowerOfTwo(cost)
+      || cost < 2
+      || cost > MAX_VERIFY_COST
+      || !Number.isInteger(blockSize)
+      || blockSize < 1
+      || blockSize > MAX_VERIFY_BLOCK_SIZE
+      || !Number.isInteger(parallelization)
+      || parallelization < 1
+      || parallelization > MAX_VERIFY_PARALLELIZATION
+      || !salt.length
+      || !derivedKey.length
+      || derivedKey.length > MAX_VERIFY_KEY_LENGTH
+    ) {
+      return null;
+    }
+
+    return {
+      cost: cost,
+      blockSize: blockSize,
+      parallelization: parallelization,
+      salt: salt,
+      derivedKey: derivedKey,
+    };
+  }
+
+  private async runDummyDerivation(password: string): Promise<void> {
+    await this.deriveKey({
+      password: password,
+      salt: Buffer.alloc(this.policy.saltLength),
+      cost: this.policy.scryptCost,
+      blockSize: this.policy.scryptBlockSize,
+      parallelization: this.policy.scryptParallelization,
+      keyLength: this.policy.derivedKeyLength,
+    });
+  }
+
+  private deriveKey(set: DyNTS_ScryptDerivationSettings): Promise<Buffer> {
+    return new Promise<Buffer>((resolve: (value: Buffer) => void, reject: (reason: unknown) => void): void => {
+      const maxmem: number = Math.max(32 * 1024 * 1024, 256 * set.cost * set.blockSize);
+
+      scrypt(set.password, set.salt, set.keyLength, {
+        N: set.cost,
+        r: set.blockSize,
+        p: set.parallelization,
+        maxmem: maxmem,
+      }, (error: Error | null, derivedKey: Buffer): void => {
+        if (error) {
+          reject(error);
+
+          return;
+        }
+
+        resolve(derivedKey);
+      });
+    });
+  }
+
+  private validatePolicy(): void {
+    if (
+      !Number.isInteger(this.policy.minLength)
+      || !Number.isInteger(this.policy.maxLength)
+      || this.policy.minLength < 8
+      || this.policy.maxLength < this.policy.minLength
+      || this.policy.maxLength > MAX_PASSWORD_LENGTH
+      || !this.isPowerOfTwo(this.policy.scryptCost)
+      || this.policy.scryptCost > MAX_VERIFY_COST
+      || !Number.isInteger(this.policy.scryptBlockSize)
+      || this.policy.scryptBlockSize < 1
+      || this.policy.scryptBlockSize > MAX_VERIFY_BLOCK_SIZE
+      || !Number.isInteger(this.policy.scryptParallelization)
+      || this.policy.scryptParallelization < 1
+      || this.policy.scryptParallelization > MAX_VERIFY_PARALLELIZATION
+      || !Number.isInteger(this.policy.derivedKeyLength)
+      || this.policy.derivedKeyLength < 16
+      || this.policy.derivedKeyLength > MAX_VERIFY_KEY_LENGTH
+      || !Number.isInteger(this.policy.saltLength)
+      || this.policy.saltLength < 16
+      || this.policy.saltLength > 64
+    ) {
+      throw this.buildError('PASSWORD_POLICY_INVALID', 'The password policy is outside supported safe bounds.');
+    }
+  }
+
+  private isPowerOfTwo(value: number): boolean {
+    return Number.isSafeInteger(value) && value > 0 && (value & (value - 1)) === 0;
+  }
+
+  private buildError(errorCode: string, message: string): DyFM_Error {
+    return new DyFM_Error({
+      status: 400,
+      errorCode: `${DyNTS_global_settings.systemShortCodeName}|ACCOUNT_SECURITY|${errorCode}`,
+      message: message,
+      userMessage: 'The credential does not satisfy the account security policy.',
+      issuerService: this.constructor.name,
+    });
+  }
+}