@rineex/auth-core 0.0.2 → 0.0.3

package/src/domain/identity/entities/identity.entity.ts

@@ -0,0 +1,126 @@
+import { CreateEntityProps, Entity } from '@rineex/ddd';
+
+import { IdentityId } from '../value-objects/identity-id.vo';
+
+/**
+ * Properties owned by the Identity entity.
+ *
+ * IMPORTANT:
+ * - This is NOT a user profile
+ * - This is NOT authorization data
+ * - This represents a stable authentication identity
+ *
+ * Examples:
+ * - Email-based identity
+ * - External IdP subject
+ * - Service or machine identity
+ */
+export interface IdentityCreateProps extends CreateEntityProps<IdentityId> {
+  readonly isActive: boolean;
+}
+
+/**
+ * Identity entity.
+ *
+ * Represents "who is authenticating" in the system.
+ *
+ * This entity is intentionally minimal and stable.
+ * Any additional concerns (profile, roles, permissions)
+ * MUST live in other bounded contexts.
+ */
+export class Identity extends Entity<IdentityId> {
+  // We keep the state private to the class
+  private _isActive: boolean;
+
+  /**
+   * Private constructor forces usage of factory methods.
+   */
+  private constructor({ isActive, ...props }: IdentityCreateProps) {
+    super(props);
+    this._isActive = isActive;
+  }
+
+  /**
+   * Factory method to create a new identity.
+   */
+  static create(id: IdentityId, isActive: boolean = true): Identity {
+    return new Identity({
+      isActive,
+      id,
+    });
+  }
+
+  /**
+   * Getter for the active state
+   */
+  public get isActive(): boolean {
+    return this._isActive;
+  }
+
+  /**
+   * Disables this identity.
+   */
+  public disable(): void {
+    if (!this._isActive) return;
+
+    this.mutate(draft => {
+      draft._isActive = false;
+    });
+  }
+
+  /**
+   * Enables this identity.
+   */
+  public enable(): void {
+    if (this._isActive) return;
+
+    this.mutate(draft => {
+      draft._isActive = true;
+    });
+  }
+
+  /**
+   * Domain invariant validation.
+   */
+  public validate(): void {
+    if (this.id == null) {
+      throw new Error('Identity must have a valid IdentityId');
+    }
+    if (typeof this._isActive !== 'boolean') {
+      throw new Error('Identity.isActive must be a boolean');
+    }
+  }
+
+  /**
+   * Serialization to plain object.
+   */
+  public toObject(): Record<string, unknown> {
+    return {
+      createdAt: this.createdAt.toISOString(),
+      isActive: this._isActive,
+      id: this.id.toString(),
+    };
+  }
+
+  /**
+   * Creates a snapshot of mutable state.
+   * Identity fields MUST NOT be included.
+   *
+   * Used internally for rollback.
+   */
+  protected snapshot(): Record<string, unknown> {
+    return {
+      isActive: this._isActive,
+    };
+  }
+
+  /**
+   * Restores mutable state from a snapshot.
+   * Identity fields MUST NOT be modified.
+   *
+   * @param snapshot - Previously captured state.
+   */
+  protected restore(snapshot: Record<string, unknown>): void {
+    this._isActive = snapshot.isActive as boolean;
+  }
+}

package/src/domain/identity/entities/index.ts

@@ -0,0 +1 @@
+export * from './identity.entity';

package/src/domain/identity/events/index.ts

@@ -0,0 +1,3 @@
+export * from './authentication-failed.event';
+export * from './authentication-started.event';
+export * from './authentication-succeeded.event';

package/src/domain/identity/index.ts

@@ -0,0 +1,4 @@
+export * from './aggregates';
+export * from './entities';
+export * from './events';
+export * from './value-objects';

package/src/domain/identity/value-objects/__tests__/auth-attempt-id.vo.spec.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+
+import { AuthAttemptId } from '../auth-attempt-id.vo';
+
+describe('authAttemptId', () => {
+  const VALID_UUID = '550e8400-e29b-41d4-a716-446655440000';
+
+  it('should create a valid AuthAttemptId with a valid UUID string', () => {
+    const authAttemptId = AuthAttemptId.create(VALID_UUID);
+
+    expect(authAttemptId).toBeInstanceOf(AuthAttemptId);
+    expect(authAttemptId.getValue()).toBe(VALID_UUID);
+  });
+
+  it('should throw an error when creating with an empty string', () => {
+    expect(() => AuthAttemptId.create('')).toThrow(
+      'AuthAttemptId must be a valid non-empty identifier',
+    );
+  });
+
+  it('should throw an error when creating with a string shorter than 16 characters', () => {
+    expect(() => AuthAttemptId.create('short')).toThrow(
+      'AuthAttemptId must be a valid non-empty identifier',
+    );
+  });
+
+  it('should throw an error when creating with null or undefined', () => {
+    expect(() => AuthAttemptId.create(null as any)).toThrow(
+      'AuthAttemptId must be a valid non-empty identifier',
+    );
+    expect(() => AuthAttemptId.create(undefined as any)).toThrow(
+      'AuthAttemptId must be a valid non-empty identifier',
+    );
+  });
+
+  it('should accept a valid string with 16 or more characters', () => {
+    const validId = '1234567890123456';
+    const authAttemptId = AuthAttemptId.create(validId);
+
+    expect(authAttemptId.getValue()).toBe(validId);
+  });
+});

package/src/domain/identity/value-objects/__tests__/auth-factor.vo.spec.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+
+import { AuthFactor } from '../auth-factor.vo';
+
+describe('authFactor', () => {
+  it('should create a valid AuthFactor with a valid identifier', () => {
+    const factor = AuthFactor.create('password');
+
+    expect(factor.toString()).toBe('password');
+  });
+
+  it('should create a valid AuthFactor with different factor types', () => {
+    const factors = ['mfa', 'biometric', 'email', 'sms'];
+
+    factors.forEach(factorType => {
+      const factor = AuthFactor.create(factorType as any);
+
+      expect(factor.toString()).toBe(factorType);
+    });
+  });
+
+  it('should throw an error when created with empty value', () => {
+    expect(() => AuthFactor.create('' as any)).toThrow(
+      'AuthFactor must be a valid identifier',
+    );
+  });
+
+  it('should throw an error when created with null value', () => {
+    expect(() => AuthFactor.create(null as any)).toThrow(
+      'AuthFactor must be a valid identifier',
+    );
+  });
+
+  it('should throw an error when created with undefined value', () => {
+    expect(() => AuthFactor.create(undefined as any)).toThrow(
+      'AuthFactor must be a valid identifier',
+    );
+  });
+});

package/src/domain/{value-objects → identity/value-objects}/auth-attempt-id.vo.ts

@@ -16,4 +16,8 @@ export class AuthAttemptId extends UUID {
       throw new Error('AuthAttemptId must be a valid non-empty identifier');
     }
   }
+
+  public static create(value: string): AuthAttemptId {
+    return new AuthAttemptId(value);
+  }
 }

package/src/domain/identity/value-objects/auth-factor.vo.ts

@@ -0,0 +1,17 @@
+import { AuthFactorName } from '@/types/auth-factor.type';
+import { PrimitiveValueObject } from '@rineex/ddd';
+
+/**
+ * Represents an authentication factor.
+ */
+export class AuthFactor extends PrimitiveValueObject<AuthFactorName> {
+  protected validate(value: AuthFactorName): void {
+    if (!value) {
+      throw new Error('AuthFactor must be a valid identifier');
+    }
+  }
+
+  public static create(value: AuthFactorName): AuthFactor {
+    return new AuthFactor(value);
+  }
+}

package/src/domain/identity/value-objects/auth-method.vo.ts

@@ -0,0 +1,34 @@
+import { AuthMethodName } from '@/types/auth-method.type';
+import { PrimitiveValueObject } from '@rineex/ddd';
+
+/**
+ * Represents the authentication method requested or used.
+ *
+ * Examples:
+ * - passwordless
+ * - otp
+ * - oauth
+ * - oidc
+ * - passkey
+ *
+ * This is a value object, NOT a strategy.
+ */
+export class AuthMethod extends PrimitiveValueObject<AuthMethodName> {
+  protected validate(value: AuthMethodName): void {
+    if (!value) {
+      throw new Error('AuthMethod cannot be empty');
+    }
+  }
+
+  public static create(value: AuthMethodName): AuthMethod {
+    return new AuthMethod(value);
+  }
+
+  public is(method: AuthMethodName): boolean {
+    return this.value === method;
+  }
+
+  public isNot(method: AuthMethodName): boolean {
+    return this.value !== method;
+  }
+}

package/src/domain/identity/value-objects/auth-policy.vo.ts

@@ -0,0 +1,19 @@
+import { AuthPolicyName } from '@/types/auth-policy.type';
+import { PrimitiveValueObject } from '@rineex/ddd';
+
+/**
+ * Represents a policy applied during authentication orchestration.
+ *
+ * Policies influence decisions but do not authenticate users.
+ */
+export class AuthPolicy extends PrimitiveValueObject<AuthPolicyName> {
+  protected validate(value: AuthPolicyName): void {
+    if (!value) {
+      throw new Error('AuthPolicy must be a valid identifier');
+    }
+  }
+
+  public static create(value: AuthPolicyName): AuthPolicy {
+    return new AuthPolicy(value);
+  }
+}

package/src/domain/{value-objects → identity/value-objects}/identity-id.vo.ts

@@ -19,4 +19,8 @@ export class IdentityId extends PrimitiveValueObject<string> {
       throw new Error('IdentityId must be a valid identifier');
     }
   }
+
+  public static create(value: string): IdentityId {
+    return new IdentityId(value);
+  }
 }

package/src/domain/identity/value-objects/identity-provider.vo.ts

@@ -0,0 +1,13 @@
+import { IdentityProviderName } from '@/types/identity-provider.type';
+import { PrimitiveValueObject } from '@rineex/ddd';
+
+/**
+ * Represents an external or internal identity provider.
+ */
+export class IdentityProvider extends PrimitiveValueObject<IdentityProviderName> {
+  protected validate(value: IdentityProviderName): void {
+    if (!value) {
+      throw new Error('IdentityProvider must be a valid identifier');
+    }
+  }
+}

package/src/domain/identity/value-objects/index.ts

@@ -0,0 +1,8 @@
+export * from './auth-attempt-id.vo';
+export * from './auth-factor.vo';
+export * from './auth-method.vo';
+export * from './auth-policy.vo';
+export * from './auth-status.vo';
+export * from './identity-id.vo';
+export * from './identity-provider.vo';
+export * from './risk-signal.vo';

package/src/domain/identity/value-objects/risk-signal.vo.ts

@@ -0,0 +1,17 @@
+import { RiskSignalName } from '@/types/risk-signal.type';
+import { PrimitiveValueObject } from '@rineex/ddd';
+
+/**
+ * Represents a detected risk signal during authentication.
+ */
+export class RiskSignal extends PrimitiveValueObject<RiskSignalName> {
+  protected validate(value: RiskSignalName): void {
+    if (!value) {
+      throw new Error('RiskSignal must be a valid identifier');
+    }
+  }
+
+  public static create(value: RiskSignalName): RiskSignal {
+    return new RiskSignal(value);
+  }
+}

package/src/domain/index.ts

@@ -0,0 +1,5 @@
+export * from './identity/aggregates';
+export * from './identity/entities';
+export * from './identity/events';
+export * from './identity/value-objects';
+export * from './policy';

package/src/domain/mfa/aggregates/mfa-session.aggregate.ts

@@ -0,0 +1,84 @@
+import { AggregateRoot, CreateEntityProps } from '@rineex/ddd';
+import { defaultIfBlank } from '@/utils/default-if-blank.util';
+import { IdentityId } from '@/index';
+
+import { MfaActiveChallengeExistsViolation } from '../violations/mfa-active-challenge-exists.violation';
+import { MfaAttemptsExceededViolation } from '../violations/mfa-attempts-exceeded.violation';
+import { MfaAlreadyVerifiedViolation } from '../violations/mfa-already-verified.violation';
+import { MfaSessionId } from '../value-objects/mfa-session-id.vo';
+import { MFAChallenge } from '../entities/mfa-challenge.entity';
+
+export interface MfaSessionProps extends CreateEntityProps<MfaSessionId> {
+  readonly identityId: IdentityId;
+  challenges: MFAChallenge[];
+  maxAttempts: number;
+  attemptsUsed: number;
+  verifiedAt?: Date;
+}
+
+export class MFASession extends AggregateRoot<MfaSessionId> {
+  constructor(public readonly props: MfaSessionProps) {
+    super(props);
+  }
+
+  toObject(): Record<string, unknown> {
+    return {
+      verifiedAt: defaultIfBlank(this.props.verifiedAt?.toISOString(), null),
+      challenges: this.props.challenges.map(c => c.toObject()),
+      identityId: this.props.identityId.toString(),
+      attemptsUsed: this.props.attemptsUsed,
+      maxAttempts: this.props.maxAttempts,
+      id: this.id.toString(),
+    };
+  }
+
+  validate(): void {
+    if (this.props.attemptsUsed > this.props.maxAttempts) {
+      throw MfaAttemptsExceededViolation.create(
+        this.props.attemptsUsed,
+        this.props.maxAttempts,
+      );
+    }
+
+    if (this.props.verifiedAt && this.props.challenges.length > 0) {
+      throw new Error('Verified MFA session cannot have active challenges');
+    }
+  }
+
+  get isVerified(): boolean {
+    return this.props.verifiedAt !== undefined;
+  }
+
+  issueChallenge(challenge: MFAChallenge, now: Date): void {
+    if (this.isVerified) throw MfaAlreadyVerifiedViolation.create();
+
+    const hasActive = this.props.challenges.some(c => !c.isExpired(now));
+
+    if (hasActive) {
+      throw MfaActiveChallengeExistsViolation.create();
+    }
+
+    this.props.challenges.push(challenge);
+  }
+
+  markAttempt(): void {
+    this.props.attemptsUsed += 1;
+    this.validate();
+  }
+
+  verify(now: Date): void {
+    if (this.isVerified) throw MfaAlreadyVerifiedViolation.create();
+
+    this.mutate(draft => {
+      draft.props.challenges = draft.props.challenges.filter(
+        c => !c.isExpired(now),
+      );
+
+      if (draft.props.challenges.length === 0) {
+        throw new Error('No valid MFA challenges to verify');
+      }
+
+      draft.props.verifiedAt = now;
+    });
+  }
+}

package/src/domain/mfa/entities/mfa-challenge.entity.ts

@@ -0,0 +1,70 @@
+import { AuthDomainViolation } from '@/domain/violations/auth-domain.violation';
+import { CreateEntityProps, Entity } from '@rineex/ddd';
+import { IdentityId } from '@/index';
+
+import { MfaChallengeId } from '../value-objects/mfa-challenge-id.vo';
+import { MfaChallengeType } from '../types/mfa-challenge-registry';
+
+export interface Props extends CreateEntityProps<MfaChallengeId> {
+  /**
+   * Authentication identity this challenge is bound to.
+   * This is NOT an application user.
+   */
+  readonly identityId: IdentityId;
+
+  readonly challengeType: MfaChallengeType;
+
+  /**
+   * Challenge issue time.
+   */
+  readonly issuedAt: Date;
+
+  /**
+   * Absolute expiration timestamp.
+   */
+  readonly expiresAt: Date;
+}
+
+class MfaChallengeExpiredViolation extends AuthDomainViolation {
+  readonly code = 'MFA_CHALLENGE_EXPIRED';
+  readonly message = 'MFA challenge has expired';
+
+  static create(reason: string) {
+    return new MfaChallengeExpiredViolation({ reason });
+  }
+}
+
+export class MFAChallenge extends Entity<MfaChallengeId> {
+  constructor(public readonly props: Props) {
+    super(props);
+  }
+
+  toObject(): Record<string, unknown> {
+    return {
+      identityId: this.props.identityId.toString(),
+      challengeType: this.props.challengeType,
+      expiresAt: this.props.expiresAt,
+      issuedAt: this.props.issuedAt,
+      id: this.id.toString(),
+    };
+  }
+
+  validate(): void {
+    if (this.props.expiresAt <= this.props.issuedAt) {
+      throw MfaChallengeExpiredViolation.create(
+        'MFA challenge expiration must be after issue time',
+      );
+    }
+  }
+
+  public static create(props: Props): MFAChallenge {
+    return new MFAChallenge(props);
+  }
+
+  /**
+   * Checks whether the challenge is expired.
+   */
+  isExpired(now: Date): boolean {
+    return now > this.props.expiresAt;
+  }
+}

package/src/domain/mfa/types/mfa-challenge-registry.ts

@@ -0,0 +1,21 @@
+/**
+ * Registry for MFA challenge mechanisms.
+ *
+ * This registry is intentionally open for module augmentation.
+ * Each MFA-related package can extend it safely.
+ */
+export type MfaChallengeTypeRegistry = {
+  readonly authenticator_app: true;
+  readonly email: true;
+  readonly sms: true;
+};
+
+/**
+ * Union of all registered MFA challenge types.
+ *
+ * Provides:
+ * - IDE autocomplete
+ * - Type safety
+ * - Extension without modifying core
+ */
+export type MfaChallengeType = keyof MfaChallengeTypeRegistry;

package/src/domain/mfa/value-objects/mfa-challenge-id.vo.ts

@@ -0,0 +1,19 @@
+import { AuthDomainViolation } from '@/domain/violations/auth-domain.violation';
+import { PrimitiveValueObject } from '@rineex/ddd';
+
+class InvalidMfaChallengeIdViolation extends AuthDomainViolation {
+  readonly code = 'MFA_CHALLENGE_ID_INVALID';
+  readonly message = 'MFA challenge ID is invalid';
+
+  static create(props: { value: string }) {
+    return new InvalidMfaChallengeIdViolation(props);
+  }
+}
+
+export class MfaChallengeId extends PrimitiveValueObject<string> {
+  protected validate(value: string): void {
+    if (!value || value.length < 16) {
+      throw InvalidMfaChallengeIdViolation.create({ value });
+    }
+  }
+}

package/src/domain/mfa/value-objects/mfa-challenge-status.vo.ts

@@ -0,0 +1,31 @@
+import { AuthDomainViolation } from '@/domain/violations/auth-domain.violation';
+import { PrimitiveValueObject } from '@rineex/ddd';
+
+const AllowedStatuses = ['pending', 'verified', 'expired', 'failed'] as const;
+
+type MfaChallengeStatusValue = (typeof AllowedStatuses)[number];
+
+class InvalidMfaChallengeStatusViolation extends AuthDomainViolation {
+  readonly code = 'MFA_CHALLENGE_STATUS_INVALID';
+  readonly message = 'MFA challenge status is invalid';
+
+  static create(props: { value: MfaChallengeStatusValue }) {
+    return new InvalidMfaChallengeStatusViolation(props);
+  }
+}
+
+export class MfaChallengeStatus extends PrimitiveValueObject<MfaChallengeStatusValue> {
+  protected validate(value: MfaChallengeStatusValue): void {
+    if (!AllowedStatuses.includes(value)) {
+      throw InvalidMfaChallengeStatusViolation.create({ value });
+    }
+  }
+
+  static pending() {
+    return new MfaChallengeStatus('pending');
+  }
+
+  static verified() {
+    return new MfaChallengeStatus('verified');
+  }
+}

package/src/domain/mfa/value-objects/mfa-session-id.vo.ts

@@ -0,0 +1,19 @@
+import { AuthDomainViolation } from '@/domain/violations/auth-domain.violation';
+import { PrimitiveValueObject } from '@rineex/ddd';
+
+class InvalidMfaSessionIdViolation extends AuthDomainViolation {
+  readonly code = 'MFA_SESSION_ID_INVALID';
+  readonly message = 'MFA session ID is invalid';
+
+  static create(props: { value: string }) {
+    return new InvalidMfaSessionIdViolation(props);
+  }
+}
+
+export class MfaSessionId extends PrimitiveValueObject<string> {
+  protected validate(value: string): void {
+    if (!value || value.length < 16) {
+      throw InvalidMfaSessionIdViolation.create({ value });
+    }
+  }
+}

package/src/domain/mfa/violations/mfa-active-challenge-exists.violation.ts

@@ -0,0 +1,10 @@
+import { DomainViolation } from '@rineex/ddd';
+
+export class MfaActiveChallengeExistsViolation extends DomainViolation {
+  readonly code = 'MFA_ACTIVE_CHALLENGE_EXISTS';
+  readonly message = 'An active MFA challenge already exists';
+
+  static create(): MfaActiveChallengeExistsViolation {
+    return new MfaActiveChallengeExistsViolation();
+  }
+}

package/src/domain/mfa/violations/mfa-already-verified.violation.ts

@@ -0,0 +1,10 @@
+import { DomainViolation } from '@rineex/ddd';
+
+export class MfaAlreadyVerifiedViolation extends DomainViolation {
+  readonly code = 'MFA_ALREADY_VERIFIED';
+  readonly message = 'MFA session is already verified';
+
+  static create(): MfaAlreadyVerifiedViolation {
+    return new MfaAlreadyVerifiedViolation();
+  }
+}

package/src/domain/mfa/violations/mfa-attempts-exceeded.violation.ts

@@ -0,0 +1,17 @@
+import { DomainViolation } from '@rineex/ddd';
+
+export class MfaAttemptsExceededViolation extends DomainViolation {
+  readonly code = 'MFA_ATTEMPTS_EXCEEDED';
+  readonly message = 'Maximum MFA verification attempts exceeded';
+
+  protected constructor(attemptsUsed: number, maxAttempts: number) {
+    super({ attemptsUsed, maxAttempts });
+  }
+
+  static create(
+    attemptsUsed: number,
+    maxAttempts: number,
+  ): MfaAttemptsExceededViolation {
+    return new MfaAttemptsExceededViolation(attemptsUsed, maxAttempts);
+  }
+}

package/src/domain/mfa/violations/mfa-expired.violation.ts

@@ -0,0 +1,10 @@
+import { DomainViolation } from '@rineex/ddd';
+
+export class MfaExpiredViolation extends DomainViolation {
+  readonly code = 'MFA_EXPIRED';
+  readonly message = 'MFA challenge or session has expired';
+
+  static create() {
+    return new MfaExpiredViolation();
+  }
+}