@futdevpro/nts-dynamo 1.15.139 → 1.15.141

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

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

package/src/_modules/account-security/index.ts

@@ -0,0 +1,31 @@
+export { DyNTS_AccountPassword_ControlService } from './account-password.control-service';
+export { DyNTS_AccountChallenge_ControlService } from './account-challenge.control-service';
+export { DyNTS_AccountSession_ControlService } from './account-session.control-service';
+export { DyNTS_AccountChallengePurpose_Type } from './_enums/account-challenge-purpose.type-enum';
+export { DyNTS_AccountRefreshTokenState_Type } from './_enums/account-refresh-token-state.type-enum';
+export { DyNTS_AccountSessionState_Type } from './_enums/account-session-state.type-enum';
+export {
+  DyNTS_AccountRefreshTokenRecord_Interface
+} from './_models/account-refresh-token-record.interface';
+export { DyNTS_AccountChallengeAdapter_Interface } from './_models/account-challenge-adapter.interface';
+export { DyNTS_AccountChallengeIssued_Interface } from './_models/account-challenge-issued.interface';
+export { DyNTS_AccountChallengeRecord_Interface } from './_models/account-challenge-record.interface';
+export { DyNTS_AccountChallengeResult_Interface } from './_models/account-challenge-result.interface';
+export { DyNTS_AccountChallengeSettings_Interface } from './_models/account-challenge-settings.interface';
+export {
+  DyNTS_AccountSessionAdapter_Interface
+} from './_models/account-session-adapter.interface';
+export { DyNTS_AccountSessionCreate_Interface } from './_models/account-session-create.interface';
+export { DyNTS_AccountSessionRotate_Interface } from './_models/account-session-rotate.interface';
+export { DyNTS_AccountSessionClaims_Interface } from './_models/account-session-claims.interface';
+export { DyNTS_AccountSessionContext_Interface } from './_models/account-session-context.interface';
+export { DyNTS_AccountSessionRecord_Interface } from './_models/account-session-record.interface';
+export { DyNTS_AccountSessionSettings_Interface } from './_models/account-session-settings.interface';
+export { DyNTS_AccountSessionTokenPair_Interface } from './_models/account-session-token-pair.interface';
+export { DyNTS_AccountSessionView_Interface } from './_models/account-session-view.interface';
+export {
+  DyNTS_AccountPasswordPolicy_Interface
+} from './_models/account-password-policy.interface';
+export {
+  DyNTS_AccountPasswordVerification_Interface
+} from './_models/account-password-verification.interface';

package/src/_modules/privacy-lifecycle/_enums/privacy-consent-decision.type-enum.ts

@@ -0,0 +1,5 @@
+/** Append-only consent decisions. Withdrawal is a new event, never mutation of history. */
+export enum DyNTS_PrivacyConsentDecision_Type {
+  granted = 'granted',
+  withdrawn = 'withdrawn',
+}

package/src/_modules/privacy-lifecycle/_enums/privacy-contributor-action.type-enum.ts

@@ -0,0 +1,10 @@
+/** Contributor action selected during privacy-request planning. */
+export enum DyNTS_PrivacyContributorAction_Type {
+  export = 'export',
+  delete = 'delete',
+  anonymize = 'anonymize',
+  rectify = 'rectify',
+  restrict = 'restrict',
+  retainWithBasis = 'retain-with-basis',
+  noData = 'no-data',
+}

package/src/_modules/privacy-lifecycle/_enums/privacy-contributor-outcome.type-enum.ts

@@ -0,0 +1,7 @@
+/** Durable result state for one contributor execution. */
+export enum DyNTS_PrivacyContributorOutcome_Type {
+  succeeded = 'succeeded',
+  retainedWithBasis = 'retained-with-basis',
+  noData = 'no-data',
+  failed = 'failed',
+}

package/src/_modules/privacy-lifecycle/_enums/privacy-request-state.type-enum.ts

@@ -0,0 +1,15 @@
+/** Persisted lifecycle states for a GDPR data-subject request. */
+export enum DyNTS_PrivacyRequestState_Type {
+  received = 'received',
+  identityVerified = 'identity-verified',
+  scoped = 'scoped',
+  planned = 'planned',
+  executing = 'executing',
+  verifying = 'verifying',
+  completed = 'completed',
+  partiallyCompleted = 'partially-completed',
+  rejectedWithReason = 'rejected-with-reason',
+  cancelled = 'cancelled',
+  failedRetryable = 'failed-retryable',
+  failedTerminal = 'failed-terminal',
+}

package/src/_modules/privacy-lifecycle/_enums/privacy-request.type-enum.ts

@@ -0,0 +1,9 @@
+/** GDPR data-subject request categories supported by the shared lifecycle. */
+export enum DyNTS_PrivacyRequest_Type {
+  access = 'access',
+  export = 'export',
+  erasure = 'erasure',
+  rectification = 'rectification',
+  restriction = 'restriction',
+  objection = 'objection',
+}

package/src/_modules/privacy-lifecycle/_models/privacy-consent-input.interface.ts

@@ -0,0 +1,12 @@
+import { DyNTS_PrivacyConsentDecision_Type } from '../_enums/privacy-consent-decision.type-enum';
+
+/** Input for one purpose-specific consent grant or withdrawal event. */
+export interface DyNTS_PrivacyConsentInput_Interface {
+  subjectId: string;
+  organizationId: string;
+  purposeCode: string;
+  policyVersion: string;
+  decision: DyNTS_PrivacyConsentDecision_Type;
+  sourceCode: string;
+  idempotencyKey: string;
+}

package/src/_modules/privacy-lifecycle/_models/privacy-consent-persistence-result.interface.ts

@@ -0,0 +1,7 @@
+import { DyNTS_PrivacyConsentRecord_Interface } from './privacy-consent-record.interface';
+
+/** Adapter-only append result retaining consent-event persistence metadata. */
+export interface DyNTS_PrivacyConsentPersistenceResult_Interface {
+  consent: DyNTS_PrivacyConsentRecord_Interface;
+  created: boolean;
+}

package/src/_modules/privacy-lifecycle/_models/privacy-consent-record.interface.ts

@@ -0,0 +1,15 @@
+import { DyNTS_PrivacyConsentDecision_Type } from '../_enums/privacy-consent-decision.type-enum';
+
+/** Immutable purpose- and policy-version-specific consent event. */
+export interface DyNTS_PrivacyConsentRecord_Interface {
+  consentId: string;
+  subjectId: string;
+  organizationId: string;
+  purposeCode: string;
+  policyVersion: string;
+  decision: DyNTS_PrivacyConsentDecision_Type;
+  sourceCode: string;
+  idempotencyHash: string;
+  requestFingerprint: string;
+  occurredAt: string;
+}

package/src/_modules/privacy-lifecycle/_models/privacy-consent-result.interface.ts

@@ -0,0 +1,7 @@
+import { DyNTS_PrivacyConsentView_Interface } from './privacy-consent-view.interface';
+
+/** Atomic append-or-replay result for one consent event. */
+export interface DyNTS_PrivacyConsentResult_Interface {
+  consent: DyNTS_PrivacyConsentView_Interface;
+  created: boolean;
+}

package/src/_modules/privacy-lifecycle/_models/privacy-consent-view.interface.ts

@@ -0,0 +1,13 @@
+import { DyNTS_PrivacyConsentDecision_Type } from '../_enums/privacy-consent-decision.type-enum';
+
+/** User-safe consent event without persistence idempotency metadata. */
+export interface DyNTS_PrivacyConsentView_Interface {
+  consentId: string;
+  subjectId: string;
+  organizationId: string;
+  purposeCode: string;
+  policyVersion: string;
+  decision: DyNTS_PrivacyConsentDecision_Type;
+  sourceCode: string;
+  occurredAt: string;
+}

package/src/_modules/privacy-lifecycle/_models/privacy-contributor-context.interface.ts

@@ -0,0 +1,9 @@
+import { DyNTS_PrivacyRequest_Type } from '../_enums/privacy-request.type-enum';
+
+/** Minimal execution context passed to a product-owned privacy contributor. */
+export interface DyNTS_PrivacyContributorContext_Interface {
+  requestId: string;
+  subjectId: string;
+  organizationId: string;
+  type: DyNTS_PrivacyRequest_Type;
+}

package/src/_modules/privacy-lifecycle/_models/privacy-contributor-outcome.interface.ts

@@ -0,0 +1,14 @@
+import { DyNTS_PrivacyContributorAction_Type } from '../_enums/privacy-contributor-action.type-enum';
+import { DyNTS_PrivacyContributorOutcome_Type } from '../_enums/privacy-contributor-outcome.type-enum';
+
+/** Durable content-free result of one idempotent contributor execution. */
+export interface DyNTS_PrivacyContributorOutcome_Interface {
+  contributorId: string;
+  action: DyNTS_PrivacyContributorAction_Type;
+  outcome: DyNTS_PrivacyContributorOutcome_Type;
+  retentionBasisCode: string;
+  artifactChecksum: string;
+  processedRecordCount: number;
+  errorCode: string;
+  completedAt: string;
+}

package/src/_modules/privacy-lifecycle/_models/privacy-contributor-plan.interface.ts

@@ -0,0 +1,8 @@
+import { DyNTS_PrivacyContributorAction_Type } from '../_enums/privacy-contributor-action.type-enum';
+
+/** Non-sensitive, auditable action plan returned by a data-domain contributor. */
+export interface DyNTS_PrivacyContributorPlan_Interface {
+  contributorId: string;
+  action: DyNTS_PrivacyContributorAction_Type;
+  retentionBasisCode: string;
+}

package/src/_modules/privacy-lifecycle/_models/privacy-contributor.interface.ts

@@ -0,0 +1,17 @@
+import { DyNTS_PrivacyContributorContext_Interface } from './privacy-contributor-context.interface';
+import { DyNTS_PrivacyContributorOutcome_Interface } from './privacy-contributor-outcome.interface';
+import { DyNTS_PrivacyContributorPlan_Interface } from './privacy-contributor-plan.interface';
+
+/** Product-domain adapter whose execute operation must be idempotent for a request and contributor pair. */
+export interface DyNTS_PrivacyContributor_Interface {
+  readonly contributorId: string;
+  plan(context: DyNTS_PrivacyContributorContext_Interface): Promise<DyNTS_PrivacyContributorPlan_Interface>;
+  execute(
+    context: DyNTS_PrivacyContributorContext_Interface,
+    plan: DyNTS_PrivacyContributorPlan_Interface
+  ): Promise<DyNTS_PrivacyContributorOutcome_Interface>;
+  verify(
+    context: DyNTS_PrivacyContributorContext_Interface,
+    outcome: DyNTS_PrivacyContributorOutcome_Interface
+  ): Promise<boolean>;
+}

package/src/_modules/privacy-lifecycle/_models/privacy-ledger-adapter.interface.ts

@@ -0,0 +1,21 @@
+import { DyNTS_PrivacyConsentRecord_Interface } from './privacy-consent-record.interface';
+import {
+  DyNTS_PrivacyConsentPersistenceResult_Interface
+} from './privacy-consent-persistence-result.interface';
+import { DyNTS_PrivacyLegalAcceptance_Interface } from './privacy-legal-acceptance.interface';
+import {
+  DyNTS_PrivacyLegalAcceptancePersistenceResult_Interface
+} from './privacy-legal-acceptance-persistence-result.interface';
+
+/** Append-only persistence contract for legal acceptance and consent history. */
+export interface DyNTS_PrivacyLedgerAdapter_Interface {
+  appendLegalAcceptance(
+    acceptance: DyNTS_PrivacyLegalAcceptance_Interface
+  ): Promise<DyNTS_PrivacyLegalAcceptancePersistenceResult_Interface>;
+  appendConsent(
+    record: DyNTS_PrivacyConsentRecord_Interface
+  ): Promise<DyNTS_PrivacyConsentPersistenceResult_Interface>;
+  listLegalAcceptances(subjectId: string, organizationId: string): Promise<DyNTS_PrivacyLegalAcceptance_Interface[]>;
+  /** Returns consent events in durable append order, oldest first. */
+  listConsentHistory(subjectId: string, organizationId: string): Promise<DyNTS_PrivacyConsentRecord_Interface[]>;
+}

package/src/_modules/privacy-lifecycle/_models/privacy-ledger-result.interface.ts

@@ -0,0 +1,9 @@
+import { DyNTS_PrivacyConsentView_Interface } from './privacy-consent-view.interface';
+import { DyNTS_PrivacyLegalAcceptanceView_Interface } from './privacy-legal-acceptance-view.interface';
+
+/** Subject-owned privacy-center ledger with immutable legal and consent history. */
+export interface DyNTS_PrivacyLedgerResult_Interface {
+  legalAcceptances: DyNTS_PrivacyLegalAcceptanceView_Interface[];
+  consentHistory: DyNTS_PrivacyConsentView_Interface[];
+  currentConsents: DyNTS_PrivacyConsentView_Interface[];
+}

package/src/_modules/privacy-lifecycle/_models/privacy-ledger-settings.interface.ts

@@ -0,0 +1,7 @@
+import { DyNTS_PrivacyLedgerAdapter_Interface } from './privacy-ledger-adapter.interface';
+
+/** Dependencies and deterministic time source for the privacy ledger. */
+export interface DyNTS_PrivacyLedgerSettings_Interface {
+  adapter: DyNTS_PrivacyLedgerAdapter_Interface;
+  clock?: () => Date;
+}

package/src/_modules/privacy-lifecycle/_models/privacy-legal-acceptance-input.interface.ts

@@ -0,0 +1,10 @@
+/** Input for accepting an exact legal document without carrying document content. */
+export interface DyNTS_PrivacyLegalAcceptanceInput_Interface {
+  subjectId: string;
+  organizationId: string;
+  documentType: string;
+  documentVersion: string;
+  documentChecksum: string;
+  sourceCode: string;
+  idempotencyKey: string;
+}

package/src/_modules/privacy-lifecycle/_models/privacy-legal-acceptance-persistence-result.interface.ts

@@ -0,0 +1,7 @@
+import { DyNTS_PrivacyLegalAcceptance_Interface } from './privacy-legal-acceptance.interface';
+
+/** Adapter-only append result retaining legal-event persistence metadata. */
+export interface DyNTS_PrivacyLegalAcceptancePersistenceResult_Interface {
+  acceptance: DyNTS_PrivacyLegalAcceptance_Interface;
+  created: boolean;
+}

package/src/_modules/privacy-lifecycle/_models/privacy-legal-acceptance-result.interface.ts

@@ -0,0 +1,7 @@
+import { DyNTS_PrivacyLegalAcceptanceView_Interface } from './privacy-legal-acceptance-view.interface';
+
+/** Atomic append-or-replay result for one legal acceptance. */
+export interface DyNTS_PrivacyLegalAcceptanceResult_Interface {
+  acceptance: DyNTS_PrivacyLegalAcceptanceView_Interface;
+  created: boolean;
+}

package/src/_modules/privacy-lifecycle/_models/privacy-legal-acceptance-view.interface.ts

@@ -0,0 +1,11 @@
+/** User-safe immutable legal acceptance without persistence idempotency metadata. */
+export interface DyNTS_PrivacyLegalAcceptanceView_Interface {
+  acceptanceId: string;
+  subjectId: string;
+  organizationId: string;
+  documentType: string;
+  documentVersion: string;
+  documentChecksum: string;
+  sourceCode: string;
+  acceptedAt: string;
+}