@rineex/auth-core 0.1.0 → 0.1.1

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

@@ -1,126 +0,0 @@
-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

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

package/src/domain/identity/events/authentication-failed.event.ts

@@ -1,24 +0,0 @@
-import { DomainEvent } from '@rineex/ddd';
-
-import { AuthAttemptId } from '../value-objects/auth-attempt-id.vo';
-
-/**
- * Emitted when an authentication attempt failed.
- */
-export class AuthenticationFailedEvent extends DomainEvent {
-  public get eventName(): string {
-    return 'authentication.auth_attempt.failed';
-  }
-
-  constructor(public readonly attemptId: AuthAttemptId) {
-    super({
-      payload: {
-        attemptId: attemptId.toString(),
-      },
-      aggregateId: attemptId.toString(),
-      id: crypto.randomUUID(),
-      occurredAt: Date.now(),
-      schemaVersion: 1,
-    });
-  }
-}

package/src/domain/identity/events/authentication-started.event.ts

@@ -1,29 +0,0 @@
-import { DomainEvent } from '@rineex/ddd';
-
-import { AuthAttemptId } from '../value-objects/auth-attempt-id.vo';
-import { AuthMethod } from '../value-objects/auth-method.vo';
-
-/**
- * Emitted when an authentication attempt begins.
- */
-export class AuthenticationStartedEvent extends DomainEvent {
-  public get eventName(): string {
-    return 'authentication.authentication_started';
-  }
-
-  constructor(
-    public readonly attemptId: AuthAttemptId,
-    public readonly method: AuthMethod,
-  ) {
-    super({
-      payload: {
-        attemptId: attemptId.toString(),
-        method: method.toString(),
-      },
-      aggregateId: attemptId.toString(),
-      id: crypto.randomUUID(),
-      occurredAt: Date.now(),
-      schemaVersion: 1,
-    });
-  }
-}

package/src/domain/identity/events/authentication-succeeded.event.ts

@@ -1,24 +0,0 @@
-import { DomainEvent } from '@rineex/ddd';
-
-import { AuthAttemptId } from '../value-objects/auth-attempt-id.vo';
-
-/**
- * Emitted when an authentication attempt succeeds.
- */
-export class AuthenticationSucceededEvent extends DomainEvent {
-  public get eventName(): string {
-    return 'authentication.auth_attempt.succeeded';
-  }
-
-  constructor(public readonly attemptId: AuthAttemptId) {
-    super({
-      payload: {
-        attemptId: attemptId.toString(),
-      },
-      aggregateId: attemptId.toString(),
-      id: crypto.randomUUID(),
-      occurredAt: Date.now(),
-      schemaVersion: 1,
-    });
-  }
-}

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

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

package/src/domain/identity/index.ts

@@ -1,4 +0,0 @@
-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

@@ -1,42 +0,0 @@
-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

@@ -1,39 +0,0 @@
-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/identity/value-objects/auth-attempt-id.vo.ts

@@ -1,23 +0,0 @@
-import { UUID } from '@rineex/ddd';
-
-/**
- * Represents a globally unique identifier for an authentication attempt.
- *
- * This ID is used for:
- * - Correlation across logs
- * - Event causation
- * - Security auditing
- *
- * Must be generated externally (UUIDv7 recommended).
- */
-export class AuthAttemptId extends UUID {
-  protected validate(value: string): void {
-    if (!value || value.length < 16) {
-      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

@@ -1,17 +0,0 @@
-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

@@ -1,34 +0,0 @@
-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

@@ -1,19 +0,0 @@
-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/identity/value-objects/auth-status.vo.ts

@@ -1,38 +0,0 @@
-import { PrimitiveValueObject } from '@rineex/ddd';
-
-type AuthStatusType = 'FAILED' | 'PENDING' | 'SUCCEEDED';
-
-/**
- * Represents the lifecycle state of an authentication attempt.
- *
- * This is intentionally restrictive to avoid invalid transitions.
- */
-export class AuthStatus extends PrimitiveValueObject<AuthStatusType> {
-  protected validate(value: AuthStatusType): void {
-    if (!['FAILED', 'PENDING', 'SUCCEEDED'].includes(value)) {
-      throw new Error(`Invalid AuthStatus: ${value}`);
-    }
-  }
-
-  /**
-   * Checks if the current auth status matches the provided value.
-   * @param value - The auth status type to compare against
-   * @returns True if the current status matches the provided value, false otherwise
-   */
-  public is(value: AuthStatusType): boolean {
-    return this.value === value;
-  }
-
-  /**
-   * Checks if the current authentication status is not equal to the provided value.
-   * @param value - The authentication status type to compare against
-   * @returns True if the current status differs from the provided value, false otherwise
-   */
-  public isNot(value: AuthStatusType): boolean {
-    return this.value !== value;
-  }
-
-  static create(value: AuthStatusType): AuthStatus {
-    return new AuthStatus(value);
-  }
-}

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

@@ -1,26 +0,0 @@
-import { PrimitiveValueObject } from '@rineex/ddd';
-
-/**
- * Represents the canonical identity identifier in the auth domain.
- *
- * This does NOT imply:
- * - user
- * - account
- * - profile
- *
- * It is intentionally abstract to support:
- * - enterprise SSO
- * - external IdPs
- * - service identities
- */
-export class IdentityId extends PrimitiveValueObject<string> {
-  protected validate(value: string): void {
-    if (!value || value.length < 8) {
-      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

@@ -1,13 +0,0 @@
-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

@@ -1,8 +0,0 @@
-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

@@ -1,17 +0,0 @@
-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

@@ -1,5 +0,0 @@
-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

@@ -1,84 +0,0 @@
-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

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