@futdevpro/nts-dynamo 1.15.139 → 1.15.141

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

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

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

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

@@ -0,0 +1,294 @@
+import { createHash } from 'crypto';
+
+import { DyFM_Error } from '@futdevpro/fsm-dynamo';
+
+import { DyNTS_AccountSession_ControlService } from './account-session.control-service';
+import { DyNTS_AccountRefreshTokenState_Type } from './_enums/account-refresh-token-state.type-enum';
+import { DyNTS_AccountSessionState_Type } from './_enums/account-session-state.type-enum';
+import { DyNTS_AccountRefreshTokenRecord_Interface } from './_models/account-refresh-token-record.interface';
+import { DyNTS_AccountSessionAdapter_Interface } from './_models/account-session-adapter.interface';
+import { DyNTS_AccountSessionClaims_Interface } from './_models/account-session-claims.interface';
+import { DyNTS_AccountSessionContext_Interface } from './_models/account-session-context.interface';
+import { DyNTS_AccountSessionCreate_Interface } from './_models/account-session-create.interface';
+import { DyNTS_AccountSessionRecord_Interface } from './_models/account-session-record.interface';
+import { DyNTS_AccountSessionRotate_Interface } from './_models/account-session-rotate.interface';
+import { DyNTS_AccountSessionTokenPair_Interface } from './_models/account-session-token-pair.interface';
+import { DyNTS_AccountSessionView_Interface } from './_models/account-session-view.interface';
+
+class DyNTS_TestSessionAdapter implements DyNTS_AccountSessionAdapter_Interface {
+  public readonly sessions: Map<string, DyNTS_AccountSessionRecord_Interface> = new Map();
+  public readonly refreshTokens: Map<string, DyNTS_AccountRefreshTokenRecord_Interface> = new Map();
+
+  /** Stores a new session and its first refresh credential atomically in memory. */
+  public async createSession(set: DyNTS_AccountSessionCreate_Interface): Promise<void> {
+    this.sessions.set(set.session.sessionId, this.cloneSession(set.session));
+    this.refreshTokens.set(set.refreshToken.tokenHash, { ...set.refreshToken });
+  }
+
+  /** Finds a test session by its stable identifier. */
+  public async findSessionById(sessionId: string): Promise<DyNTS_AccountSessionRecord_Interface | null> {
+    const session: DyNTS_AccountSessionRecord_Interface | undefined = this.sessions.get(sessionId);
+
+    return session ? this.cloneSession(session) : null;
+  }
+
+  /** Finds a test session by its hashed access credential. */
+  public async findSessionByAccessTokenHash(
+    accessTokenHash: string
+  ): Promise<DyNTS_AccountSessionRecord_Interface | null> {
+    const session: DyNTS_AccountSessionRecord_Interface | undefined = Array.from(this.sessions.values())
+      .find((item: DyNTS_AccountSessionRecord_Interface): boolean => item.accessTokenHash === accessTokenHash);
+
+    return session ? this.cloneSession(session) : null;
+  }
+
+  /** Finds a one-time refresh ledger record by credential hash. */
+  public async findRefreshTokenByHash(
+    tokenHash: string
+  ): Promise<DyNTS_AccountRefreshTokenRecord_Interface | null> {
+    const token: DyNTS_AccountRefreshTokenRecord_Interface | undefined = this.refreshTokens.get(tokenHash);
+
+    return token ? { ...token } : null;
+  }
+
+  /** Performs an in-memory compare-and-set rotation without yielding between checks and writes. */
+  public async rotateSession(set: DyNTS_AccountSessionRotate_Interface): Promise<boolean> {
+    const session: DyNTS_AccountSessionRecord_Interface | undefined =
+      this.sessions.get(set.replacementSession.sessionId);
+    const currentToken: DyNTS_AccountRefreshTokenRecord_Interface | undefined =
+      this.refreshTokens.get(set.currentRefreshTokenHash);
+
+    if (
+      session?.revision !== set.expectedSessionRevision
+      || currentToken?.state !== DyNTS_AccountRefreshTokenState_Type.active
+    ) {
+      return false;
+    }
+
+    currentToken.state = DyNTS_AccountRefreshTokenState_Type.used;
+    currentToken.usedAt = set.usedAt;
+    this.sessions.set(set.replacementSession.sessionId, this.cloneSession(set.replacementSession));
+    this.refreshTokens.set(set.replacementRefreshToken.tokenHash, { ...set.replacementRefreshToken });
+
+    return true;
+  }
+
+  /** Revokes the family belonging to one test session. */
+  public async revokeSession(sessionId: string, revokedAt: string, reasonCode: string): Promise<void> {
+    const session: DyNTS_AccountSessionRecord_Interface | undefined = this.sessions.get(sessionId);
+
+    if (session) {
+      this.revokeMatching(session.familyId, revokedAt, reasonCode);
+    }
+  }
+
+  /** Revokes one complete test token family. */
+  public async revokeFamily(familyId: string, revokedAt: string, reasonCode: string): Promise<void> {
+    this.revokeMatching(familyId, revokedAt, reasonCode);
+  }
+
+  /** Revokes every test session belonging to one subject. */
+  public async revokeSubject(subjectId: string, revokedAt: string, reasonCode: string): Promise<void> {
+    Array.from(this.sessions.values())
+      .filter((session: DyNTS_AccountSessionRecord_Interface): boolean => session.subjectId === subjectId)
+      .forEach((session: DyNTS_AccountSessionRecord_Interface): void => {
+        this.revokeMatching(session.familyId, revokedAt, reasonCode);
+      });
+  }
+
+  /** Lists cloned test sessions belonging to one subject. */
+  public async listSubjectSessions(subjectId: string): Promise<DyNTS_AccountSessionRecord_Interface[]> {
+    return Array.from(this.sessions.values())
+      .filter((session: DyNTS_AccountSessionRecord_Interface): boolean => session.subjectId === subjectId)
+      .map((session: DyNTS_AccountSessionRecord_Interface): DyNTS_AccountSessionRecord_Interface => (
+        this.cloneSession(session)
+      ));
+  }
+
+  private revokeMatching(familyId: string, revokedAt: string, reasonCode: string): void {
+    Array.from(this.sessions.values())
+      .filter((session: DyNTS_AccountSessionRecord_Interface): boolean => session.familyId === familyId)
+      .forEach((session: DyNTS_AccountSessionRecord_Interface): void => {
+        session.state = DyNTS_AccountSessionState_Type.revoked;
+        session.revokedAt = revokedAt;
+        session.revocationReason = reasonCode;
+      });
+    Array.from(this.refreshTokens.values())
+      .filter((token: DyNTS_AccountRefreshTokenRecord_Interface): boolean => token.familyId === familyId)
+      .forEach((token: DyNTS_AccountRefreshTokenRecord_Interface): void => {
+        token.state = DyNTS_AccountRefreshTokenState_Type.revoked;
+      });
+  }
+
+  private cloneSession(
+    session: DyNTS_AccountSessionRecord_Interface
+  ): DyNTS_AccountSessionRecord_Interface {
+    return { ...session, context: { ...session.context } };
+  }
+}
+
+describe('| DyNTS_AccountSession_ControlService', (): void => {
+  const context: DyNTS_AccountSessionContext_Interface = {
+    deviceName: 'Test browser',
+    ipAddressHash: 'ip-hash',
+    userAgentHash: 'agent-hash',
+  };
+  let now: Date;
+  let adapter: DyNTS_TestSessionAdapter;
+  let service: DyNTS_AccountSession_ControlService;
+
+  beforeEach((): void => {
+    now = new Date('2026-08-18T10:00:00.000Z');
+    adapter = new DyNTS_TestSessionAdapter();
+    service = new DyNTS_AccountSession_ControlService({
+      adapter: adapter,
+      accessTtlMs: 60_000,
+      refreshTtlMs: 600_000,
+      clock: (): Date => new Date(now),
+    });
+  });
+
+  it('| persists only token hashes and authenticates an active access credential', async (): Promise<void> => {
+    const pair: DyNTS_AccountSessionTokenPair_Interface = await service.issueSession('subject-1', 3, context);
+    const stored: DyNTS_AccountSessionRecord_Interface | undefined = adapter.sessions.get(pair.sessionId);
+    const claims: DyNTS_AccountSessionClaims_Interface = await service.authenticateAccessToken(pair.accessToken);
+
+    expect(stored?.accessTokenHash).toBe(hashToken(pair.accessToken));
+    expect(JSON.stringify(Array.from(adapter.sessions.values()))).not.toContain(pair.accessToken);
+    expect(JSON.stringify(Array.from(adapter.refreshTokens.values()))).not.toContain(pair.refreshToken);
+    expect(claims).toEqual({
+      subjectId: 'subject-1',
+      sessionId: pair.sessionId,
+      familyId: stored?.familyId,
+      authorizationVersion: 3,
+    });
+  });
+
+  it('| rejects an expired access credential with a content-free error', async (): Promise<void> => {
+    const pair: DyNTS_AccountSessionTokenPair_Interface = await service.issueSession('subject-1', 1, context);
+
+    now = new Date('2026-08-18T10:01:00.001Z');
+    const error: DyFM_Error = await captureError(service.authenticateAccessToken(pair.accessToken));
+
+    expect(error._errorCode).toContain('ACCESS_TOKEN_INVALID');
+    expect(error._message).not.toContain(pair.accessToken);
+  });
+
+  it('| rejects a corrupt access expiry instead of treating it as unbounded', async (): Promise<void> => {
+    const pair: DyNTS_AccountSessionTokenPair_Interface = await service.issueSession('subject-1', 1, context);
+    const stored: DyNTS_AccountSessionRecord_Interface | undefined = adapter.sessions.get(pair.sessionId);
+
+    if (stored) {
+      stored.accessExpiresAt = 'not-a-date';
+    }
+
+    await expectAsync(service.authenticateAccessToken(pair.accessToken)).toBeRejectedWithError(DyFM_Error);
+  });
+
+  it('| rotates a refresh credential once without extending its absolute expiry', async (): Promise<void> => {
+    const first: DyNTS_AccountSessionTokenPair_Interface = await service.issueSession('subject-1', 1, context);
+
+    now = new Date('2026-08-18T10:00:30.000Z');
+    const second: DyNTS_AccountSessionTokenPair_Interface = await service.rotateRefreshToken(
+      first.refreshToken,
+      context
+    );
+    const oldToken: DyNTS_AccountRefreshTokenRecord_Interface | undefined =
+      adapter.refreshTokens.get(hashToken(first.refreshToken));
+
+    expect(second.refreshToken).not.toBe(first.refreshToken);
+    expect(second.refreshExpiresAt).toBe(first.refreshExpiresAt);
+    expect(oldToken?.state).toBe(DyNTS_AccountRefreshTokenState_Type.used);
+    expect((await service.authenticateAccessToken(second.accessToken)).subjectId).toBe('subject-1');
+  });
+
+  it('| treats refresh replay as compromise and revokes the complete family', async (): Promise<void> => {
+    const first: DyNTS_AccountSessionTokenPair_Interface = await service.issueSession('subject-1', 1, context);
+    const second: DyNTS_AccountSessionTokenPair_Interface = await service.rotateRefreshToken(
+      first.refreshToken,
+      context
+    );
+    const replayError: DyFM_Error = await captureError(service.rotateRefreshToken(first.refreshToken, context));
+    const accessError: DyFM_Error = await captureError(service.authenticateAccessToken(second.accessToken));
+
+    expect(replayError._errorCode).toContain('REFRESH_TOKEN_REUSE');
+    expect(accessError._errorCode).toContain('ACCESS_TOKEN_INVALID');
+  });
+
+  it('| permits one concurrent rotation winner then revokes the raced family', async (): Promise<void> => {
+    const first: DyNTS_AccountSessionTokenPair_Interface = await service.issueSession('subject-1', 1, context);
+    const results: PromiseSettledResult<DyNTS_AccountSessionTokenPair_Interface>[] = await Promise.allSettled([
+      service.rotateRefreshToken(first.refreshToken, context),
+      service.rotateRefreshToken(first.refreshToken, context),
+    ]);
+    const winners: PromiseFulfilledResult<DyNTS_AccountSessionTokenPair_Interface>[] = results.filter(
+      (result: PromiseSettledResult<DyNTS_AccountSessionTokenPair_Interface>):
+      result is PromiseFulfilledResult<DyNTS_AccountSessionTokenPair_Interface> => result.status === 'fulfilled'
+    );
+
+    expect(winners.length).toBe(1);
+    expect(results.filter((result: PromiseSettledResult<DyNTS_AccountSessionTokenPair_Interface>): boolean => (
+      result.status === 'rejected'
+    )).length).toBe(1);
+    await expectAsync(service.authenticateAccessToken(winners[0].value.accessToken)).toBeRejectedWithError(
+      DyFM_Error
+    );
+  });
+
+  it('| revokes one session or every subject session without affecting another subject', async (): Promise<void> => {
+    const first: DyNTS_AccountSessionTokenPair_Interface = await service.issueSession('subject-1', 1, context);
+    const second: DyNTS_AccountSessionTokenPair_Interface = await service.issueSession('subject-1', 1, context);
+    const other: DyNTS_AccountSessionTokenPair_Interface = await service.issueSession('subject-2', 1, context);
+
+    await service.revokeSession(first.sessionId, 'user-sign-out');
+    await expectAsync(service.authenticateAccessToken(first.accessToken)).toBeRejectedWithError(DyFM_Error);
+    expect((await service.authenticateAccessToken(second.accessToken)).subjectId).toBe('subject-1');
+    await service.revokeAllSubjectSessions('subject-1', 'password-change');
+    await expectAsync(service.authenticateAccessToken(second.accessToken)).toBeRejectedWithError(DyFM_Error);
+    expect((await service.authenticateAccessToken(other.accessToken)).subjectId).toBe('subject-2');
+  });
+
+  it('| exposes only the user-safe session projection', async (): Promise<void> => {
+    await service.issueSession('subject-1', 1, context);
+    const sessions: DyNTS_AccountSessionView_Interface[] = await service.listSubjectSessions('subject-1');
+    const serialized: string = JSON.stringify(sessions);
+
+    expect(sessions.length).toBe(1);
+    expect(serialized).not.toContain('accessTokenHash');
+    expect(serialized).not.toContain('familyId');
+    expect(serialized).not.toContain('subjectId');
+    expect(sessions[0].context).toEqual(context);
+  });
+
+  it('| rejects unsafe runtime settings before issuing credentials', (): void => {
+    expect((): DyNTS_AccountSession_ControlService => new DyNTS_AccountSession_ControlService({
+      adapter: adapter,
+      tokenBytes: 16,
+    })).toThrowError(DyFM_Error);
+  });
+
+  it('| rejects malformed authorization versions and oversized context before persistence', async (): Promise<void> => {
+    await expectAsync(service.issueSession('subject-1', -1, context)).toBeRejectedWithError(DyFM_Error);
+    await expectAsync(service.issueSession('subject-1', 1, {
+      ...context,
+      deviceName: 'x'.repeat(161),
+    })).toBeRejectedWithError(DyFM_Error);
+    expect(adapter.sessions.size).toBe(0);
+  });
+});
+
+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.');
+}