@futdevpro/nts-dynamo 1.15.151 → 1.15.153

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

@@ -1,376 +1,376 @@
-import {
-  createHash,
-  randomBytes,
-  randomUUID
-} from 'crypto';
-
-import { DyFM_Error } from '@futdevpro/fsm-dynamo';
-
-import { DyNTS_global_settings } from '../../_collections/global-settings.const';
-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_AccountSessionRotate_Interface } from './_models/account-session-rotate.interface';
-import { DyNTS_AccountSessionClaims_Interface } from './_models/account-session-claims.interface';
-import { DyNTS_AccountSessionContext_Interface } from './_models/account-session-context.interface';
-import { DyNTS_AccountSessionRecord_Interface } from './_models/account-session-record.interface';
-import { DyNTS_AccountSessionSettings_Interface } from './_models/account-session-settings.interface';
-import { DyNTS_AccountSessionTokenPair_Interface } from './_models/account-session-token-pair.interface';
-import { DyNTS_AccountSessionView_Interface } from './_models/account-session-view.interface';
-
-const DEFAULT_ACCESS_TTL_MS: number = 15 * 60 * 1000;
-const DEFAULT_REFRESH_TTL_MS: number = 30 * 24 * 60 * 60 * 1000;
-const DEFAULT_TOKEN_BYTES: number = 32;
-const DEFAULT_MAX_REFRESH_ROTATIONS: number = 100;
-
-interface DyNTS_NewSessionMaterial {
-  rawAccessToken: string;
-  rawRefreshToken: string;
-  session: DyNTS_AccountSessionRecord_Interface;
-  refreshToken: DyNTS_AccountRefreshTokenRecord_Interface;
-}
-
-/**
- * Opaque, server-revocable account session families with one-time refresh rotation and replay detection.
- */
-export class DyNTS_AccountSession_ControlService {
-  private readonly adapter: DyNTS_AccountSessionAdapter_Interface;
-  private readonly accessTtlMs: number;
-  private readonly refreshTtlMs: number;
-  private readonly tokenBytes: number;
-  private readonly maxRefreshRotations: number;
-  private readonly clock: () => Date;
-
-  /** Creates a validated session service over an atomic persistence adapter. */
-  constructor(set: DyNTS_AccountSessionSettings_Interface) {
-    this.adapter = set.adapter;
-    this.accessTtlMs = set.accessTtlMs ?? DEFAULT_ACCESS_TTL_MS;
-    this.refreshTtlMs = set.refreshTtlMs ?? DEFAULT_REFRESH_TTL_MS;
-    this.tokenBytes = set.tokenBytes ?? DEFAULT_TOKEN_BYTES;
-    this.maxRefreshRotations = set.maxRefreshRotations ?? DEFAULT_MAX_REFRESH_ROTATIONS;
-    this.clock = set.clock ?? ((): Date => new Date());
-    this.validateSettings();
-  }
-
-  /** Atomically persists a new session family before returning its raw credentials. */
-  public async issueSession(
-    subjectId: string,
-    authorizationVersion: number,
-    context: DyNTS_AccountSessionContext_Interface
-  ): Promise<DyNTS_AccountSessionTokenPair_Interface> {
-    if (
-      !subjectId
-      || subjectId.length > 256
-      || !Number.isSafeInteger(authorizationVersion)
-      || authorizationVersion < 0
-    ) {
-      throw this.buildUnauthorized('SESSION_SUBJECT_MISSING');
-    }
-
-    this.validateContext(context);
-
-    const now: Date = this.clock();
-    const material: DyNTS_NewSessionMaterial = this.createMaterial({
-      subjectId: subjectId,
-      sessionId: randomUUID(),
-      familyId: randomUUID(),
-      generation: 0,
-      revision: 0,
-      authorizationVersion: authorizationVersion,
-      createdAt: now.toISOString(),
-      refreshExpiresAt: new Date(now.getTime() + this.refreshTtlMs).toISOString(),
-      materialCreatedAt: now.toISOString(),
-      context: context,
-    });
-
-    await this.adapter.createSession({
-      session: material.session,
-      refreshToken: material.refreshToken,
-    });
-
-    return this.toTokenPair(material);
-  }
-
-  /** Resolves an opaque access token through the server-side active-session record. */
-  public async authenticateAccessToken(
-    accessToken: string
-  ): Promise<DyNTS_AccountSessionClaims_Interface> {
-    if (!accessToken || accessToken.length > 512) {
-      throw this.buildUnauthorized('ACCESS_TOKEN_INVALID');
-    }
-
-    const now: Date = this.clock();
-    const session: DyNTS_AccountSessionRecord_Interface | null =
-      await this.adapter.findSessionByAccessTokenHash(this.hashToken(accessToken));
-
-    if (
-      session?.state !== DyNTS_AccountSessionState_Type.active
-      || session.accessTokenHash !== this.hashToken(accessToken)
-      || !this.isFutureDate(session.accessExpiresAt, now)
-      || !session.subjectId
-      || !session.sessionId
-      || !session.familyId
-      || !Number.isSafeInteger(session.authorizationVersion)
-      || session.authorizationVersion < 0
-    ) {
-      throw this.buildUnauthorized('ACCESS_TOKEN_INVALID');
-    }
-
-    return {
-      subjectId: session.subjectId,
-      sessionId: session.sessionId,
-      familyId: session.familyId,
-      authorizationVersion: session.authorizationVersion,
-    };
-  }
-
-  /** Rotates a one-time refresh token; replay revokes the complete token family. */
-  public async rotateRefreshToken(
-    refreshToken: string,
-    context: DyNTS_AccountSessionContext_Interface
-  ): Promise<DyNTS_AccountSessionTokenPair_Interface> {
-    if (!refreshToken || refreshToken.length > 512) {
-      throw this.buildUnauthorized('REFRESH_TOKEN_INVALID');
-    }
-
-    this.validateContext(context);
-    const now: Date = this.clock();
-    const tokenHash: string = this.hashToken(refreshToken);
-    const token: DyNTS_AccountRefreshTokenRecord_Interface | null =
-      await this.adapter.findRefreshTokenByHash(tokenHash);
-
-    if (!token) {
-      throw this.buildUnauthorized('REFRESH_TOKEN_INVALID');
-    }
-
-    if (token.state !== DyNTS_AccountRefreshTokenState_Type.active) {
-      await this.adapter.revokeFamily(token.familyId, now.toISOString(), 'refresh-token-reuse');
-
-      throw this.buildUnauthorized('REFRESH_TOKEN_REUSE');
-    }
-
-    const session: DyNTS_AccountSessionRecord_Interface | null =
-      await this.adapter.findSessionById(token.sessionId);
-
-    if (
-      session?.state !== DyNTS_AccountSessionState_Type.active
-      || session.familyId !== token.familyId
-      || session.subjectId !== token.subjectId
-      || session.generation !== token.generation
-      || token.tokenHash !== tokenHash
-      || !this.isFutureDate(token.expiresAt, now)
-      || !this.isFutureDate(session.refreshExpiresAt, now)
-    ) {
-      await this.adapter.revokeFamily(token.familyId, now.toISOString(), 'refresh-token-invalid-state');
-
-      throw this.buildUnauthorized('REFRESH_TOKEN_INVALID');
-    }
-
-    if (session.generation >= this.maxRefreshRotations) {
-      await this.adapter.revokeFamily(token.familyId, now.toISOString(), 'refresh-rotation-limit');
-
-      throw this.buildUnauthorized('REFRESH_ROTATION_LIMIT');
-    }
-
-    const material: DyNTS_NewSessionMaterial = this.createMaterial({
-      subjectId: session.subjectId,
-      sessionId: session.sessionId,
-      familyId: session.familyId,
-      generation: session.generation + 1,
-      revision: session.revision + 1,
-      authorizationVersion: session.authorizationVersion,
-      createdAt: session.createdAt,
-      refreshExpiresAt: session.refreshExpiresAt,
-      materialCreatedAt: now.toISOString(),
-      context: context,
-    });
-    const rotation: DyNTS_AccountSessionRotate_Interface = {
-      expectedSessionRevision: session.revision,
-      currentRefreshTokenHash: tokenHash,
-      usedAt: now.toISOString(),
-      replacementSession: material.session,
-      replacementRefreshToken: material.refreshToken,
-    };
-    const didRotate: boolean = await this.adapter.rotateSession(rotation);
-
-    if (!didRotate) {
-      const winner: DyNTS_AccountRefreshTokenRecord_Interface | null =
-        await this.adapter.findRefreshTokenByHash(tokenHash);
-
-      if (winner?.state === DyNTS_AccountRefreshTokenState_Type.used) {
-        await this.adapter.revokeFamily(token.familyId, now.toISOString(), 'refresh-token-reuse-race');
-
-        throw this.buildUnauthorized('REFRESH_TOKEN_REUSE');
-      }
-
-      throw this.buildUnauthorized('REFRESH_TOKEN_CONFLICT');
-    }
-
-    return this.toTokenPair(material);
-  }
-
-  /** Revokes one server-side session. */
-  public async revokeSession(sessionId: string, reasonCode: string): Promise<void> {
-    this.validateRevocation(sessionId, reasonCode);
-    await this.adapter.revokeSession(sessionId, this.clock().toISOString(), reasonCode);
-  }
-
-  /** Revokes every session belonging to one subject. */
-  public async revokeAllSubjectSessions(subjectId: string, reasonCode: string): Promise<void> {
-    this.validateRevocation(subjectId, reasonCode);
-    await this.adapter.revokeSubject(subjectId, this.clock().toISOString(), reasonCode);
-  }
-
-  /** Returns a user-safe session projection without token hashes. */
-  public async listSubjectSessions(subjectId: string): Promise<DyNTS_AccountSessionView_Interface[]> {
-    if (!subjectId || subjectId.length > 256) {
-      throw this.buildUnauthorized('SESSION_SUBJECT_MISSING');
-    }
-
-    const sessions: DyNTS_AccountSessionRecord_Interface[] =
-      await this.adapter.listSubjectSessions(subjectId);
-
-    return sessions.map((session: DyNTS_AccountSessionRecord_Interface): DyNTS_AccountSessionView_Interface => ({
-      sessionId: session.sessionId,
-      state: session.state,
-      createdAt: session.createdAt,
-      lastRotatedAt: session.lastRotatedAt,
-      accessExpiresAt: session.accessExpiresAt,
-      refreshExpiresAt: session.refreshExpiresAt,
-      context: { ...session.context },
-    }));
-  }
-
-  private createMaterial(set: {
-    subjectId: string;
-    sessionId: string;
-    familyId: string;
-    generation: number;
-    revision: number;
-    authorizationVersion: number;
-    createdAt: string;
-    refreshExpiresAt: string;
-    materialCreatedAt: string;
-    context: DyNTS_AccountSessionContext_Interface;
-  }): DyNTS_NewSessionMaterial {
-    const rawAccessToken: string = randomBytes(this.tokenBytes).toString('base64url');
-    const rawRefreshToken: string = randomBytes(this.tokenBytes).toString('base64url');
-    const materialCreatedAt: Date = new Date(set.materialCreatedAt);
-    const accessExpiresAt: string = new Date(materialCreatedAt.getTime() + this.accessTtlMs).toISOString();
-    const session: DyNTS_AccountSessionRecord_Interface = {
-      sessionId: set.sessionId,
-      familyId: set.familyId,
-      subjectId: set.subjectId,
-      accessTokenHash: this.hashToken(rawAccessToken),
-      accessExpiresAt: accessExpiresAt,
-      refreshExpiresAt: set.refreshExpiresAt,
-      state: DyNTS_AccountSessionState_Type.active,
-      generation: set.generation,
-      revision: set.revision,
-      authorizationVersion: set.authorizationVersion,
-      createdAt: set.createdAt,
-      lastRotatedAt: set.materialCreatedAt,
-      revokedAt: '',
-      revocationReason: '',
-      context: { ...set.context },
-    };
-    const refreshTokenRecord: DyNTS_AccountRefreshTokenRecord_Interface = {
-      tokenHash: this.hashToken(rawRefreshToken),
-      sessionId: set.sessionId,
-      familyId: set.familyId,
-      subjectId: set.subjectId,
-      generation: set.generation,
-      state: DyNTS_AccountRefreshTokenState_Type.active,
-      expiresAt: set.refreshExpiresAt,
-      usedAt: '',
-    };
-
-    return {
-      rawAccessToken: rawAccessToken,
-      rawRefreshToken: rawRefreshToken,
-      session: session,
-      refreshToken: refreshTokenRecord,
-    };
-  }
-
-  private toTokenPair(material: DyNTS_NewSessionMaterial): DyNTS_AccountSessionTokenPair_Interface {
-    return {
-      sessionId: material.session.sessionId,
-      accessToken: material.rawAccessToken,
-      refreshToken: material.rawRefreshToken,
-      accessExpiresAt: material.session.accessExpiresAt,
-      refreshExpiresAt: material.session.refreshExpiresAt,
-    };
-  }
-
-  private hashToken(token: string): string {
-    return createHash('sha256').update(token).digest('hex');
-  }
-
-  private validateSettings(): void {
-    if (
-      !this.adapter
-      || !Number.isSafeInteger(this.accessTtlMs)
-      || this.accessTtlMs < 1_000
-      || this.accessTtlMs > 24 * 60 * 60 * 1000
-      || !Number.isSafeInteger(this.refreshTtlMs)
-      || this.refreshTtlMs <= this.accessTtlMs
-      || this.refreshTtlMs > 366 * 24 * 60 * 60 * 1000
-      || !Number.isSafeInteger(this.tokenBytes)
-      || this.tokenBytes < 32
-      || this.tokenBytes > 128
-      || !Number.isSafeInteger(this.maxRefreshRotations)
-      || this.maxRefreshRotations < 1
-      || this.maxRefreshRotations > 10_000
-    ) {
-      throw new DyFM_Error({
-        status: 500,
-        errorCode: `${DyNTS_global_settings.systemShortCodeName}|ACCOUNT_SECURITY|SESSION_SETTINGS_INVALID`,
-        message: 'The account session settings are outside supported safe bounds.',
-        userMessage: 'The account security service is unavailable.',
-        issuerService: this.constructor.name,
-      });
-    }
-  }
-
-  private validateContext(context: DyNTS_AccountSessionContext_Interface): void {
-    if (
-      !context
-      || typeof context.deviceName !== 'string'
-      || typeof context.ipAddressHash !== 'string'
-      || typeof context.userAgentHash !== 'string'
-      || context.deviceName.length > 160
-      || context.ipAddressHash.length > 128
-      || context.userAgentHash.length > 128
-    ) {
-      throw this.buildUnauthorized('SESSION_CONTEXT_INVALID');
-    }
-  }
-
-  private validateRevocation(targetId: string, reasonCode: string): void {
-    if (!targetId || !reasonCode || reasonCode.length > 128) {
-      throw this.buildUnauthorized('SESSION_REVOCATION_INVALID');
-    }
-  }
-
-  private isFutureDate(value: string, now: Date): boolean {
-    const timestamp: number = new Date(value).getTime();
-
-    return Number.isFinite(timestamp) && timestamp > now.getTime();
-  }
-
-  private buildUnauthorized(errorCode: string): DyFM_Error {
-    return new DyFM_Error({
-      status: 401,
-      errorCode: `${DyNTS_global_settings.systemShortCodeName}|ACCOUNT_SECURITY|${errorCode}`,
-      message: 'Opaque account credential validation failed.',
-      userMessage: 'The session is invalid or has expired. Please sign in again.',
-      issuerService: this.constructor.name,
-    });
-  }
-}
+import {
+  createHash,
+  randomBytes,
+  randomUUID
+} from 'crypto';
+
+import { DyFM_Error } from '@futdevpro/fsm-dynamo';
+
+import { DyNTS_global_settings } from '../../_collections/global-settings.const';
+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_AccountSessionRotate_Interface } from './_models/account-session-rotate.interface';
+import { DyNTS_AccountSessionClaims_Interface } from './_models/account-session-claims.interface';
+import { DyNTS_AccountSessionContext_Interface } from './_models/account-session-context.interface';
+import { DyNTS_AccountSessionRecord_Interface } from './_models/account-session-record.interface';
+import { DyNTS_AccountSessionSettings_Interface } from './_models/account-session-settings.interface';
+import { DyNTS_AccountSessionTokenPair_Interface } from './_models/account-session-token-pair.interface';
+import { DyNTS_AccountSessionView_Interface } from './_models/account-session-view.interface';
+
+const DEFAULT_ACCESS_TTL_MS: number = 15 * 60 * 1000;
+const DEFAULT_REFRESH_TTL_MS: number = 30 * 24 * 60 * 60 * 1000;
+const DEFAULT_TOKEN_BYTES: number = 32;
+const DEFAULT_MAX_REFRESH_ROTATIONS: number = 100;
+
+interface DyNTS_NewSessionMaterial {
+  rawAccessToken: string;
+  rawRefreshToken: string;
+  session: DyNTS_AccountSessionRecord_Interface;
+  refreshToken: DyNTS_AccountRefreshTokenRecord_Interface;
+}
+
+/**
+ * Opaque, server-revocable account session families with one-time refresh rotation and replay detection.
+ */
+export class DyNTS_AccountSession_ControlService {
+  private readonly adapter: DyNTS_AccountSessionAdapter_Interface;
+  private readonly accessTtlMs: number;
+  private readonly refreshTtlMs: number;
+  private readonly tokenBytes: number;
+  private readonly maxRefreshRotations: number;
+  private readonly clock: () => Date;
+
+  /** Creates a validated session service over an atomic persistence adapter. */
+  constructor(set: DyNTS_AccountSessionSettings_Interface) {
+    this.adapter = set.adapter;
+    this.accessTtlMs = set.accessTtlMs ?? DEFAULT_ACCESS_TTL_MS;
+    this.refreshTtlMs = set.refreshTtlMs ?? DEFAULT_REFRESH_TTL_MS;
+    this.tokenBytes = set.tokenBytes ?? DEFAULT_TOKEN_BYTES;
+    this.maxRefreshRotations = set.maxRefreshRotations ?? DEFAULT_MAX_REFRESH_ROTATIONS;
+    this.clock = set.clock ?? ((): Date => new Date());
+    this.validateSettings();
+  }
+
+  /** Atomically persists a new session family before returning its raw credentials. */
+  public async issueSession(
+    subjectId: string,
+    authorizationVersion: number,
+    context: DyNTS_AccountSessionContext_Interface
+  ): Promise<DyNTS_AccountSessionTokenPair_Interface> {
+    if (
+      !subjectId
+      || subjectId.length > 256
+      || !Number.isSafeInteger(authorizationVersion)
+      || authorizationVersion < 0
+    ) {
+      throw this.buildUnauthorized('SESSION_SUBJECT_MISSING');
+    }
+
+    this.validateContext(context);
+
+    const now: Date = this.clock();
+    const material: DyNTS_NewSessionMaterial = this.createMaterial({
+      subjectId: subjectId,
+      sessionId: randomUUID(),
+      familyId: randomUUID(),
+      generation: 0,
+      revision: 0,
+      authorizationVersion: authorizationVersion,
+      createdAt: now.toISOString(),
+      refreshExpiresAt: new Date(now.getTime() + this.refreshTtlMs).toISOString(),
+      materialCreatedAt: now.toISOString(),
+      context: context,
+    });
+
+    await this.adapter.createSession({
+      session: material.session,
+      refreshToken: material.refreshToken,
+    });
+
+    return this.toTokenPair(material);
+  }
+
+  /** Resolves an opaque access token through the server-side active-session record. */
+  public async authenticateAccessToken(
+    accessToken: string
+  ): Promise<DyNTS_AccountSessionClaims_Interface> {
+    if (!accessToken || accessToken.length > 512) {
+      throw this.buildUnauthorized('ACCESS_TOKEN_INVALID');
+    }
+
+    const now: Date = this.clock();
+    const session: DyNTS_AccountSessionRecord_Interface | null =
+      await this.adapter.findSessionByAccessTokenHash(this.hashToken(accessToken));
+
+    if (
+      session?.state !== DyNTS_AccountSessionState_Type.active
+      || session.accessTokenHash !== this.hashToken(accessToken)
+      || !this.isFutureDate(session.accessExpiresAt, now)
+      || !session.subjectId
+      || !session.sessionId
+      || !session.familyId
+      || !Number.isSafeInteger(session.authorizationVersion)
+      || session.authorizationVersion < 0
+    ) {
+      throw this.buildUnauthorized('ACCESS_TOKEN_INVALID');
+    }
+
+    return {
+      subjectId: session.subjectId,
+      sessionId: session.sessionId,
+      familyId: session.familyId,
+      authorizationVersion: session.authorizationVersion,
+    };
+  }
+
+  /** Rotates a one-time refresh token; replay revokes the complete token family. */
+  public async rotateRefreshToken(
+    refreshToken: string,
+    context: DyNTS_AccountSessionContext_Interface
+  ): Promise<DyNTS_AccountSessionTokenPair_Interface> {
+    if (!refreshToken || refreshToken.length > 512) {
+      throw this.buildUnauthorized('REFRESH_TOKEN_INVALID');
+    }
+
+    this.validateContext(context);
+    const now: Date = this.clock();
+    const tokenHash: string = this.hashToken(refreshToken);
+    const token: DyNTS_AccountRefreshTokenRecord_Interface | null =
+      await this.adapter.findRefreshTokenByHash(tokenHash);
+
+    if (!token) {
+      throw this.buildUnauthorized('REFRESH_TOKEN_INVALID');
+    }
+
+    if (token.state !== DyNTS_AccountRefreshTokenState_Type.active) {
+      await this.adapter.revokeFamily(token.familyId, now.toISOString(), 'refresh-token-reuse');
+
+      throw this.buildUnauthorized('REFRESH_TOKEN_REUSE');
+    }
+
+    const session: DyNTS_AccountSessionRecord_Interface | null =
+      await this.adapter.findSessionById(token.sessionId);
+
+    if (
+      session?.state !== DyNTS_AccountSessionState_Type.active
+      || session.familyId !== token.familyId
+      || session.subjectId !== token.subjectId
+      || session.generation !== token.generation
+      || token.tokenHash !== tokenHash
+      || !this.isFutureDate(token.expiresAt, now)
+      || !this.isFutureDate(session.refreshExpiresAt, now)
+    ) {
+      await this.adapter.revokeFamily(token.familyId, now.toISOString(), 'refresh-token-invalid-state');
+
+      throw this.buildUnauthorized('REFRESH_TOKEN_INVALID');
+    }
+
+    if (session.generation >= this.maxRefreshRotations) {
+      await this.adapter.revokeFamily(token.familyId, now.toISOString(), 'refresh-rotation-limit');
+
+      throw this.buildUnauthorized('REFRESH_ROTATION_LIMIT');
+    }
+
+    const material: DyNTS_NewSessionMaterial = this.createMaterial({
+      subjectId: session.subjectId,
+      sessionId: session.sessionId,
+      familyId: session.familyId,
+      generation: session.generation + 1,
+      revision: session.revision + 1,
+      authorizationVersion: session.authorizationVersion,
+      createdAt: session.createdAt,
+      refreshExpiresAt: session.refreshExpiresAt,
+      materialCreatedAt: now.toISOString(),
+      context: context,
+    });
+    const rotation: DyNTS_AccountSessionRotate_Interface = {
+      expectedSessionRevision: session.revision,
+      currentRefreshTokenHash: tokenHash,
+      usedAt: now.toISOString(),
+      replacementSession: material.session,
+      replacementRefreshToken: material.refreshToken,
+    };
+    const didRotate: boolean = await this.adapter.rotateSession(rotation);
+
+    if (!didRotate) {
+      const winner: DyNTS_AccountRefreshTokenRecord_Interface | null =
+        await this.adapter.findRefreshTokenByHash(tokenHash);
+
+      if (winner?.state === DyNTS_AccountRefreshTokenState_Type.used) {
+        await this.adapter.revokeFamily(token.familyId, now.toISOString(), 'refresh-token-reuse-race');
+
+        throw this.buildUnauthorized('REFRESH_TOKEN_REUSE');
+      }
+
+      throw this.buildUnauthorized('REFRESH_TOKEN_CONFLICT');
+    }
+
+    return this.toTokenPair(material);
+  }
+
+  /** Revokes one server-side session. */
+  public async revokeSession(sessionId: string, reasonCode: string): Promise<void> {
+    this.validateRevocation(sessionId, reasonCode);
+    await this.adapter.revokeSession(sessionId, this.clock().toISOString(), reasonCode);
+  }
+
+  /** Revokes every session belonging to one subject. */
+  public async revokeAllSubjectSessions(subjectId: string, reasonCode: string): Promise<void> {
+    this.validateRevocation(subjectId, reasonCode);
+    await this.adapter.revokeSubject(subjectId, this.clock().toISOString(), reasonCode);
+  }
+
+  /** Returns a user-safe session projection without token hashes. */
+  public async listSubjectSessions(subjectId: string): Promise<DyNTS_AccountSessionView_Interface[]> {
+    if (!subjectId || subjectId.length > 256) {
+      throw this.buildUnauthorized('SESSION_SUBJECT_MISSING');
+    }
+
+    const sessions: DyNTS_AccountSessionRecord_Interface[] =
+      await this.adapter.listSubjectSessions(subjectId);
+
+    return sessions.map((session: DyNTS_AccountSessionRecord_Interface): DyNTS_AccountSessionView_Interface => ({
+      sessionId: session.sessionId,
+      state: session.state,
+      createdAt: session.createdAt,
+      lastRotatedAt: session.lastRotatedAt,
+      accessExpiresAt: session.accessExpiresAt,
+      refreshExpiresAt: session.refreshExpiresAt,
+      context: { ...session.context },
+    }));
+  }
+
+  private createMaterial(set: {
+    subjectId: string;
+    sessionId: string;
+    familyId: string;
+    generation: number;
+    revision: number;
+    authorizationVersion: number;
+    createdAt: string;
+    refreshExpiresAt: string;
+    materialCreatedAt: string;
+    context: DyNTS_AccountSessionContext_Interface;
+  }): DyNTS_NewSessionMaterial {
+    const rawAccessToken: string = randomBytes(this.tokenBytes).toString('base64url');
+    const rawRefreshToken: string = randomBytes(this.tokenBytes).toString('base64url');
+    const materialCreatedAt: Date = new Date(set.materialCreatedAt);
+    const accessExpiresAt: string = new Date(materialCreatedAt.getTime() + this.accessTtlMs).toISOString();
+    const session: DyNTS_AccountSessionRecord_Interface = {
+      sessionId: set.sessionId,
+      familyId: set.familyId,
+      subjectId: set.subjectId,
+      accessTokenHash: this.hashToken(rawAccessToken),
+      accessExpiresAt: accessExpiresAt,
+      refreshExpiresAt: set.refreshExpiresAt,
+      state: DyNTS_AccountSessionState_Type.active,
+      generation: set.generation,
+      revision: set.revision,
+      authorizationVersion: set.authorizationVersion,
+      createdAt: set.createdAt,
+      lastRotatedAt: set.materialCreatedAt,
+      revokedAt: '',
+      revocationReason: '',
+      context: { ...set.context },
+    };
+    const refreshTokenRecord: DyNTS_AccountRefreshTokenRecord_Interface = {
+      tokenHash: this.hashToken(rawRefreshToken),
+      sessionId: set.sessionId,
+      familyId: set.familyId,
+      subjectId: set.subjectId,
+      generation: set.generation,
+      state: DyNTS_AccountRefreshTokenState_Type.active,
+      expiresAt: set.refreshExpiresAt,
+      usedAt: '',
+    };
+
+    return {
+      rawAccessToken: rawAccessToken,
+      rawRefreshToken: rawRefreshToken,
+      session: session,
+      refreshToken: refreshTokenRecord,
+    };
+  }
+
+  private toTokenPair(material: DyNTS_NewSessionMaterial): DyNTS_AccountSessionTokenPair_Interface {
+    return {
+      sessionId: material.session.sessionId,
+      accessToken: material.rawAccessToken,
+      refreshToken: material.rawRefreshToken,
+      accessExpiresAt: material.session.accessExpiresAt,
+      refreshExpiresAt: material.session.refreshExpiresAt,
+    };
+  }
+
+  private hashToken(token: string): string {
+    return createHash('sha256').update(token).digest('hex');
+  }
+
+  private validateSettings(): void {
+    if (
+      !this.adapter
+      || !Number.isSafeInteger(this.accessTtlMs)
+      || this.accessTtlMs < 1_000
+      || this.accessTtlMs > 24 * 60 * 60 * 1000
+      || !Number.isSafeInteger(this.refreshTtlMs)
+      || this.refreshTtlMs <= this.accessTtlMs
+      || this.refreshTtlMs > 366 * 24 * 60 * 60 * 1000
+      || !Number.isSafeInteger(this.tokenBytes)
+      || this.tokenBytes < 32
+      || this.tokenBytes > 128
+      || !Number.isSafeInteger(this.maxRefreshRotations)
+      || this.maxRefreshRotations < 1
+      || this.maxRefreshRotations > 10_000
+    ) {
+      throw new DyFM_Error({
+        status: 500,
+        errorCode: `${DyNTS_global_settings.systemShortCodeName}|ACCOUNT_SECURITY|SESSION_SETTINGS_INVALID`,
+        message: 'The account session settings are outside supported safe bounds.',
+        userMessage: 'The account security service is unavailable.',
+        issuerService: this.constructor.name,
+      });
+    }
+  }
+
+  private validateContext(context: DyNTS_AccountSessionContext_Interface): void {
+    if (
+      !context
+      || typeof context.deviceName !== 'string'
+      || typeof context.ipAddressHash !== 'string'
+      || typeof context.userAgentHash !== 'string'
+      || context.deviceName.length > 160
+      || context.ipAddressHash.length > 128
+      || context.userAgentHash.length > 128
+    ) {
+      throw this.buildUnauthorized('SESSION_CONTEXT_INVALID');
+    }
+  }
+
+  private validateRevocation(targetId: string, reasonCode: string): void {
+    if (!targetId || !reasonCode || reasonCode.length > 128) {
+      throw this.buildUnauthorized('SESSION_REVOCATION_INVALID');
+    }
+  }
+
+  private isFutureDate(value: string, now: Date): boolean {
+    const timestamp: number = new Date(value).getTime();
+
+    return Number.isFinite(timestamp) && timestamp > now.getTime();
+  }
+
+  private buildUnauthorized(errorCode: string): DyFM_Error {
+    return new DyFM_Error({
+      status: 401,
+      errorCode: `${DyNTS_global_settings.systemShortCodeName}|ACCOUNT_SECURITY|${errorCode}`,
+      message: 'Opaque account credential validation failed.',
+      userMessage: 'The session is invalid or has expired. Please sign in again.',
+      issuerService: this.constructor.name,
+    });
+  }
+}