@rineex/auth-core 0.0.2 → 0.0.3

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @rineex/auth-core
 
+## 0.0.3
+
+### Patch Changes
+
+- Updated dependencies
+  [[`b1e8e3a`](https://github.com/rineex/core/commit/b1e8e3a4e02644118af82b8f068259d3e5bb2f24)]:
+  - @rineex/ddd@1.5.2
+
 ## 0.0.2
 
 ### Patch Changes

package/eslint.config.mjs

@@ -7,6 +7,7 @@ export default [
 
   {
     rules: {
+      '@typescript-eslint/class-literal-property-style': ['off'],
       '@typescript-eslint/consistent-type-definitions': ['off'],
       '@typescript-eslint/consistent-type-imports': 'off',
       '@typescript-eslint/no-extraneous-class': 'off',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rineex/auth-core",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Authentication Core package for Rineex core modules",
   "author": "Rineex Team",
   "main": "./dist/index.js",
@@ -22,6 +22,8 @@
   },
   "devDependencies": {
     "@changesets/cli": "2.29.8",
+    "@types/lodash.isempty": "4.4.9",
+    "@types/lodash.isnil": "4.0.9",
     "@types/node": "24.10.4",
     "@vitest/ui": "4.0.16",
     "tslib": "2.8.1",
@@ -40,6 +42,8 @@
   },
   "license": "Apache-2.0",
   "dependencies": {
+    "lodash.isempty": "4.4.0",
+    "lodash.isnil": "4.0.0",
     "@rineex/ddd": "1.5.1"
   },
   "scripts": {

package/src/application/mfa/events/challenge-issue-observability.event.ts

@@ -0,0 +1,18 @@
+import { ObservabilityEvent } from '@/types/observability-event';
+
+export class ChallengeIssueObservabilityEvent extends ObservabilityEvent {
+  constructor(params: {
+    sessionId: string;
+    challengeType: string;
+    success?: boolean;
+  }) {
+    super({
+      payload: {
+        challengeType: params.challengeType,
+        sessionId: params.sessionId,
+        success: params.success,
+      },
+      name: 'authentication.mfa.challenge.issued',
+    });
+  }
+}

package/src/application/mfa/events/session-started-observability.event.ts

@@ -0,0 +1,18 @@
+import { ObservabilityEvent } from '@/types/observability-event';
+
+export class SessionStartedObservabilityEvent extends ObservabilityEvent {
+  constructor(params: {
+    sessionId: string;
+    identityId: string;
+    reused?: boolean;
+  }) {
+    super({
+      payload: {
+        reused: params.reused ?? false,
+        identityId: params.identityId,
+        sessionId: params.sessionId,
+      },
+      name: 'authentication.mfa.session.started',
+    });
+  }
+}

package/src/application/mfa/events/verification-failed-observability.event.ts

@@ -0,0 +1,14 @@
+import { ObservabilityEvent } from '@/types/observability-event';
+
+export class VerificationFailedObservabilityEvent extends ObservabilityEvent {
+  constructor(sessionId: string, reasonCode: string) {
+    super({
+      payload: {
+        reasonCode,
+        sessionId,
+      },
+      name: 'authentication.mfa.verification_failed',
+      occurredAt: new Date(),
+    });
+  }
+}

package/src/application/mfa/events/verification-succeeded-observibility.event.ts

@@ -0,0 +1,12 @@
+import { ObservabilityEvent } from '@/types/observability-event';
+
+export class VerificationSucceededObservabilityEvent extends ObservabilityEvent {
+  constructor(params: { sessionId: string }) {
+    super({
+      payload: {
+        sessionId: params.sessionId,
+      },
+      name: 'authentication.mfa.verification.succeeded',
+    });
+  }
+}

package/src/application/mfa/issue-mfa-challenge.application-service.ts

@@ -0,0 +1,75 @@
+import { ObservabilityEventPort } from '@/ports/observability/observability-event.port';
+import { MfaSessionRepository } from '@/ports/mfa/mfa-session-repository.port';
+import { MfaSessionId } from '@/domain/mfa/value-objects/mfa-session-id.vo';
+import { MFAChallenge } from '@/domain/mfa/entities/mfa-challenge.entity';
+import { ApplicationServicePort, Result } from '@rineex/ddd';
+import { MfaClock } from '@/ports/mfa/mfa-clock.port';
+import { LoggerPort } from '@/ports/log/log.port';
+
+import { ChallengeIssueObservabilityEvent } from './events/challenge-issue-observability.event';
+
+type IssueMfaChallengeInput = {
+  sessionId: MfaSessionId;
+  challenge: MFAChallenge;
+};
+
+type IssueMfaChallengeOutput = Result<void, never>;
+
+export class IssueMfaChallengeApplicationService implements ApplicationServicePort<
+  IssueMfaChallengeInput,
+  IssueMfaChallengeOutput
+> {
+  constructor(
+    private readonly repository: MfaSessionRepository,
+    private readonly clock: MfaClock,
+    private readonly logger: LoggerPort,
+    private readonly events: ObservabilityEventPort,
+  ) {}
+
+  async execute({
+    challenge,
+    sessionId,
+  }: IssueMfaChallengeInput): Promise<IssueMfaChallengeOutput> {
+    try {
+      const session = await this.repository.findById(sessionId);
+
+      if (!session) {
+        this.logger.warn('MFA session not found', { sessionId });
+        throw new Error('MFA session not found'); // app-layer error
+      }
+
+      session.issueChallenge(challenge, this.clock.now());
+
+      await this.repository.save(session);
+
+      this.logger.info('MFA challenge issued', {
+        sessionId: sessionId.toString(),
+        challengeType: challenge,
+      });
+
+      this.events.emit(
+        new ChallengeIssueObservabilityEvent({
+          challengeType: challenge.props.challengeType,
+          sessionId: sessionId.toString(),
+          success: true,
+        }),
+      );
+
+      return Result.ok(undefined);
+    } catch (error) {
+      this.events.emit(
+        new ChallengeIssueObservabilityEvent({
+          challengeType: challenge.props.challengeType,
+          sessionId: sessionId.toString(),
+          success: false,
+        }),
+      );
+
+      this.logger.error('Error issuing MFA challenge', {
+        sessionId: sessionId.toString(),
+        error,
+      });
+      return Result.fail(error as never);
+    }
+  }
+}

package/src/application/mfa/start-mfa-session.application-service.ts

@@ -0,0 +1,90 @@
+import { ObservabilityEventPort } from '@/ports/observability/observability-event.port';
+import { MfaSessionIdGenerator } from '@/ports/mfa/mfa-session-id-generator.port';
+import { MfaSessionRepository } from '@/ports/mfa/mfa-session-repository.port';
+import { MFASession } from '@/domain/mfa/aggregates/mfa-session.aggregate';
+import { ApplicationServicePort, Result } from '@rineex/ddd';
+import { LoggerPort } from '@/ports/log/log.port';
+import { IdentityId } from '@/index';
+
+import { VerificationFailedObservabilityEvent } from './events/verification-failed-observability.event';
+import { SessionStartedObservabilityEvent } from './events/session-started-observability.event';
+
+type StartMFASessionInput = {
+  identityId: IdentityId;
+  maxAttempts: number;
+};
+
+type StartMFASessionOutput = Result<MFASession, never>;
+
+export class StartMfaSessionApplicationService implements ApplicationServicePort<
+  StartMFASessionInput,
+  StartMFASessionOutput
+> {
+  constructor(
+    private readonly repository: MfaSessionRepository,
+    private readonly idGenerator: MfaSessionIdGenerator,
+    private readonly logger: LoggerPort,
+    private readonly events: ObservabilityEventPort,
+  ) {}
+
+  async execute(args: StartMFASessionInput): Promise<StartMFASessionOutput> {
+    try {
+      const existing = await this.repository.findActiveByIdentity(
+        args.identityId,
+      );
+
+      if (existing) {
+        this.logger.info('MFA session reused', {
+          identityId: args.identityId.toString(),
+        });
+
+        this.events.emit(
+          new SessionStartedObservabilityEvent({
+            identityId: args.identityId.toString(),
+            sessionId: existing.id.toString(),
+            reused: true,
+          }),
+        );
+
+        return Result.ok(existing);
+      }
+
+      const session = new MFASession({
+        id: this.idGenerator.generate(),
+        maxAttempts: args.maxAttempts,
+        identityId: args.identityId,
+        attemptsUsed: 0,
+        challenges: [],
+      });
+
+      await this.repository.save(session);
+
+      this.logger.info('MFA session started', {
+        identityId: args.identityId.toString(),
+        sessionId: session.id.toString(),
+      });
+
+      this.events.emit(
+        new SessionStartedObservabilityEvent({
+          identityId: args.identityId.toString(),
+          sessionId: session.id.toString(),
+          reused: false,
+        }),
+      );
+
+      return Result.ok(session);
+    } catch (violation) {
+      this.events.emit(
+        new VerificationFailedObservabilityEvent(
+          args.identityId.toString(),
+          violation instanceof Error
+            ? violation.message
+            : 'START_MFA_SESSION_ERROR',
+        ),
+      );
+
+      this.logger.error('Error starting MFA session', { violation, ...args });
+      return Result.fail(violation as never);
+    }
+  }
+}

package/src/application/mfa/verify-mfa.application-service.ts

@@ -0,0 +1,61 @@
+import { ObservabilityEventPort } from '@/ports/observability/observability-event.port';
+import { MfaSessionRepository } from '@/ports/mfa/mfa-session-repository.port';
+import { MfaSessionId } from '@/domain/mfa/value-objects/mfa-session-id.vo';
+import { ApplicationServicePort, Result } from '@rineex/ddd';
+import { MfaClock } from '@/ports/mfa/mfa-clock.port';
+import { LoggerPort } from '@/ports/log/log.port';
+
+import { VerificationSucceededObservabilityEvent } from './events/verification-succeeded-observibility.event';
+import { VerificationFailedObservabilityEvent } from './events/verification-failed-observability.event';
+
+type VerifyMFAInput = {
+  sessionId: MfaSessionId;
+};
+
+type VerifyMFAOutput = Result<void, never>;
+
+export class VerifyMfaApplicationService implements ApplicationServicePort<
+  VerifyMFAInput,
+  VerifyMFAOutput
+> {
+  constructor(
+    private readonly repository: MfaSessionRepository,
+    private readonly clock: MfaClock,
+    private readonly events: ObservabilityEventPort,
+
+    private readonly logger: LoggerPort,
+  ) {}
+
+  async execute({ sessionId }: VerifyMFAInput): Promise<VerifyMFAOutput> {
+    try {
+      const session = await this.repository.findById(sessionId);
+
+      if (!session) {
+        throw new Error('MFA session not found');
+      }
+
+      session.markAttempt();
+      session.verify(this.clock.now());
+
+      await this.repository.save(session);
+
+      this.events.emit(
+        new VerificationSucceededObservabilityEvent({
+          sessionId: session.id.toString(),
+        }),
+      );
+
+      return Result.ok(undefined);
+    } catch (error) {
+      this.events.emit(
+        new VerificationFailedObservabilityEvent(
+          sessionId.toString(),
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
+          (error as any).code ?? 'UNKNOWN',
+        ),
+      );
+      this.logger?.error('Error verifying MFA session', { sessionId, error });
+      return Result.fail(error as never);
+    }
+  }
+}

package/src/application/services/auth-orchestrator.service.ts

@@ -0,0 +1,77 @@
+import { AuthenticationAttemptRepositoryPort } from '@/ports/outbound/authentication-attempt.repository.port';
+import { DomainEventPublisherPort } from '@/ports/outbound/domain-event-publisher.port';
+import { StartAuthenticationCommand } from '@/ports/inbound/start-auth.command';
+import { AuthAttemptId, AuthenticationAttempt, AuthMethod } from '@/domain';
+import { AuthMethodPort } from '@/ports/inbound/auth-method.port';
+import { AuthMethodName } from '@/types/auth-method.type';
+import { ApplicationServicePort } from '@rineex/ddd';
+
+/**
+ * Application service responsible for orchestrating authentication flows.
+ *
+ * This service:
+ * - Coordinates domain objects
+ * - Delegates authentication to method modules
+ * - Remains stateless and deterministic
+ *
+ * It is safe to use in:
+ * - HTTP servers
+ * - Workers
+ * - Serverless
+ * - CLI tools
+ */
+export class AuthOrchestratorService implements ApplicationServicePort<
+  StartAuthenticationCommand,
+  AuthAttemptId
+> {
+  constructor(
+    private readonly authMethods: readonly AuthMethodPort[],
+    private readonly attemptRepository: AuthenticationAttemptRepositoryPort,
+    private readonly eventPublisher: DomainEventPublisherPort,
+    private readonly idGenerator: () => AuthAttemptId,
+  ) {}
+
+  /**
+   * Starts a new authentication flow.
+   *
+   * @throws Error if method is not registered
+   */
+  async execute({
+    identityId,
+    context,
+    method,
+  }: StartAuthenticationCommand): Promise<AuthAttemptId> {
+    const authMethod = this.resolveAuthMethod(method);
+
+    const attemptId = this.idGenerator();
+
+    const attempt = AuthenticationAttempt.start(
+      attemptId,
+      AuthMethod.create(method),
+      identityId,
+    );
+
+    await this.attemptRepository.save(attempt);
+
+    await this.eventPublisher.publish(attempt.pullDomainEvents());
+
+    await authMethod.authenticate(context);
+
+    return attemptId;
+  }
+
+  /**
+   * Resolves an authentication method implementation.
+   *
+   * Fail-fast behavior is intentional for security reasons.
+   */
+  private resolveAuthMethod(method: AuthMethodName): AuthMethodPort {
+    const resolved = this.authMethods.find(m => m.method.is(method));
+
+    if (!resolved) {
+      throw new Error(`Authentication method not registered: ${method}`);
+    }
+
+    return resolved;
+  }
+}

package/src/application/services/oauth-authorize.service.ts

@@ -0,0 +1,12 @@
+import { ApplicationServicePort } from '@rineex/ddd';
+
+export class OAuthAuthorizeService implements ApplicationServicePort<any, any> {
+  constructor(
+    private readonly authorizationRepository: AuthorizationRepository,
+    private readonly clientRepository: ClientRepository,
+  ) {}
+
+  async execute(command: any): Promise<any> {
+    // Implementation goes here
+  }
+}

package/src/domain/{aggregates → identity/aggregates}/authentication-attempt.aggregate.ts

@@ -1,4 +1,4 @@
-import { AggregateRoot } from '@rineex/ddd';
+import { AggregateRoot, CreateEntityProps } from '@rineex/ddd';
 
 import { AuthenticationSucceededEvent } from '../events/authentication-succeeded.event';
 import { AuthenticationStartedEvent } from '../events/authentication-started.event';
@@ -8,11 +8,11 @@ import { AuthStatus } from '../value-objects/auth-status.vo';
 import { AuthMethod } from '../value-objects/auth-method.vo';
 import { IdentityId } from '../value-objects/identity-id.vo';
 
-type Props = {
+interface AuthenticationAttemptProps extends CreateEntityProps<AuthAttemptId> {
   status: AuthStatus;
   method: AuthMethod;
   identityId?: IdentityId;
-};
+}
 
 /**
  * Aggregate Root representing a single authentication attempt.
@@ -27,18 +27,38 @@ type Props = {
  * - Talk to infrastructure
  * - Know about HTTP or sessions
  */
-export class AuthenticationAttempt extends AggregateRoot<Props> {
-  private constructor(id: AuthAttemptId, props: Props) {
+export class AuthenticationAttempt extends AggregateRoot<AuthAttemptId> {
+  /**
+   * Current status of the authentication attempt.
+   */
+  private _status: AuthStatus;
+  /**
+   * Method used for authentication.
+   */
+  private _method: AuthMethod;
+  /**
+   * Optional identity being authenticated.
+   */
+  private _identityId?: IdentityId;
+
+  private constructor({ createdAt, id, ...props }: AuthenticationAttemptProps) {
     super({
-      createdAt: new Date(),
-      props,
+      createdAt,
       id,
     });
+    this._status = props.status;
+    this._method = props.method;
+    this._identityId = props.identityId;
   }
 
-  // This "casts" the ID for this specific class only
-  public override get id(): AuthAttemptId {
-    return super.id as AuthAttemptId;
+  toObject(): Record<string, unknown> {
+    return {
+      identityId: this._identityId.getValue(),
+      createdAt: this.createdAt,
+      id: this.id.getValue(),
+      status: this._status,
+      method: this._method,
+    };
   }
 
   /**
@@ -49,10 +69,11 @@ export class AuthenticationAttempt extends AggregateRoot<Props> {
     method: AuthMethod,
     identityId?: IdentityId,
   ): AuthenticationAttempt {
-    const attempt = new AuthenticationAttempt(id, {
+    const attempt = new AuthenticationAttempt({
       status: AuthStatus.create('PENDING'),
       identityId,
       method,
+      id,
     });
 
     attempt.addEvent(new AuthenticationStartedEvent(id, method));
@@ -66,18 +87,15 @@ export class AuthenticationAttempt extends AggregateRoot<Props> {
    * @throws Error if already completed
    */
   succeed(): void {
-    if (this.props.status.isNot('PENDING')) {
+    if (this._status.isNot('PENDING')) {
       throw new Error('Authentication attempt already completed');
     }
 
-    this.updateProps(props => ({
-      ...props,
-      status: AuthStatus.create('SUCCEEDED'),
-    }));
-
-    const ev = new AuthenticationSucceededEvent(this.id);
+    this.mutate(draft => {
+      draft._status = AuthStatus.create('SUCCEEDED');
+    });
 
-    this.addEvent(ev);
+    this.addEvent(new AuthenticationSucceededEvent(this.id));
   }
 
   /**
@@ -86,7 +104,7 @@ export class AuthenticationAttempt extends AggregateRoot<Props> {
    * @throws Error if already completed
    */
   fail(reason: string): void {
-    if (this.props.status.isNot('PENDING')) {
+    if (this._status.isNot('PENDING')) {
       throw new Error('Authentication attempt already completed');
     }
 
@@ -94,10 +112,9 @@ export class AuthenticationAttempt extends AggregateRoot<Props> {
       throw new Error('Failure reason must be provided');
     }
 
-    this.updateProps(props => ({
-      ...props,
-      status: AuthStatus.create('FAILED'),
-    }));
+    this.mutate(draft => {
+      draft._status = AuthStatus.create('FAILED');
+    });
 
     this.addEvent(new AuthenticationFailedEvent(this.id));
   }
@@ -108,11 +125,11 @@ export class AuthenticationAttempt extends AggregateRoot<Props> {
    * Called automatically before domain events are added.
    */
   validate(): void {
-    if (!this.props.method) {
+    if (!this._method) {
       throw new Error('AuthenticationAttempt must have a method');
     }
 
-    if (!this.props.status) {
+    if (!this._status) {
       throw new Error('AuthenticationAttempt must have a status');
     }
   }

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

@@ -0,0 +1 @@
+export * from './authentication-attempt.aggregate';