Enforce OTP domain invariants and safe restoration

payguard-identity-service/src/main/java/dev/amg/payguard/identity/customer/domain/value_object/CustomerId.java

@@ -0,0 +1,40 @@
+package dev.amg.payguard.identity.customer.domain.value_object;
+
+import domain.ValueObject;
+import org.jspecify.annotations.Nullable;
+import org.springframework.modulith.NamedInterface;
+
+@NamedInterface
+public final class CustomerId implements ValueObject {
+  private static final String CUSTOMER_ID_PREFIX = "cus_";
+  private final String value;
+
+  private CustomerId(String value) {
+    this.value = PrefixedIdValidator.validateAndReturn(value, CUSTOMER_ID_PREFIX);
+  }
+
+  public static CustomerId parse(String value) {
+    return new CustomerId(value);
+  }
+
+  @Override
+  public boolean equals(@Nullable Object o) {
+    if (!(o instanceof CustomerId that)) return false;
+
+    return getValue().equals(that.getValue());
+  }
+
+  @Override
+  public int hashCode() {
+    return getValue().hashCode();
+  }
+
+  public String getValue() {
+    return value;
+  }
+
+  @Override
+  public boolean sameValueAs(@Nullable ValueObject otherCustomerId) {
+    return equals(otherCustomerId);
+  }
+}

payguard-identity-service/src/main/java/dev/amg/payguard/identity/customer/domain/value_object/OtpId.java

@@ -0,0 +1,43 @@
+package dev.amg.payguard.identity.customer.domain.value_object;
+
+import domain.ValueObject;
+import java.util.Objects;
+import org.jspecify.annotations.Nullable;
+
+/** Immutable identifier. Parsing validateAndReturns syntax, not existence or authorization. */
+public final class OtpId implements ValueObject {
+  private static final String OTP_ID_PREFIX = "otp_";
+  private final String value;
+
+  private OtpId(String value) {
+    this.value = PrefixedIdValidator.validateAndReturn(value, OTP_ID_PREFIX);
+  }
+
+  public static OtpId parse(String value) {
+    return new OtpId(value);
+  }
+
+  public String value() {
+    return value;
+  }
+
+  @Override
+  public boolean equals(@Nullable Object other) {
+    return this == other || (other instanceof OtpId that && value.equals(that.value));
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hashCode(value);
+  }
+
+  @Override
+  public String toString() {
+    return value;
+  }
+
+  @Override
+  public boolean sameValueAs(@Nullable ValueObject otherOtpId) {
+    return equals(otherOtpId);
+  }
+}

payguard-identity-service/src/main/java/dev/amg/payguard/identity/customer/domain/value_object/PrefixedIdValidator.java

@@ -0,0 +1,33 @@
+package dev.amg.payguard.identity.customer.domain.value_object;
+
+import java.util.Objects;
+
+final class PrefixedIdValidator {
+  private static final int RANDOM_SUFFIX_LENGTH = 22;
+  private static final String BASE62_ALPHABET =
+      "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+
+  private PrefixedIdValidator() {}
+
+  static String validateAndReturn(String identifier, String expectedPrefix) {
+    Objects.requireNonNull(identifier);
+    Objects.requireNonNull(expectedPrefix);
+
+    if (identifier.length() != (expectedPrefix.length() + RANDOM_SUFFIX_LENGTH)
+        || !identifier.startsWith(expectedPrefix)) {
+      throw new IllegalArgumentException(
+          "invalid identifier format: expected "
+              + expectedPrefix
+              + " followed by 22 Base62 characters");
+    }
+
+    for (int index = expectedPrefix.length(); index < identifier.length(); index++) {
+      char character = identifier.charAt(index);
+      boolean isBase62Character = BASE62_ALPHABET.indexOf(character) >= 0;
+      if (!isBase62Character) {
+        throw new IllegalArgumentException("invalid identifier suffix: expected Base62 characters");
+      }
+    }
+    return identifier;
+  }
+}

payguard-identity-service/src/main/java/dev/amg/payguard/identity/customer/domain/value_object/package-info.java

@@ -0,0 +1,4 @@
+@NullMarked
+package dev.amg.payguard.identity.customer.domain.value_object;
+
+import org.jspecify.annotations.NullMarked;

payguard-identity-service/src/main/java/dev/amg/payguard/identity/verification/domain/enums/OtpChannel.java

@@ -0,0 +1,8 @@
+package dev.amg.payguard.identity.verification.domain.enums;
+
+public enum OtpChannel {
+  SMS,
+  EMAIL,
+  PUSH,
+  AUTHENTICATOR_APP
+}

payguard-identity-service/src/main/java/dev/amg/payguard/identity/verification/domain/enums/OtpPurpose.java

@@ -0,0 +1,10 @@
+package dev.amg.payguard.identity.verification.domain.enums;
+
+public enum OtpPurpose {
+  LOGIN,
+  TRANSFER_CONFIRM,
+  LOAN_DISBURSE,
+  COLLATERAL_RELEASE,
+  CARD_ISSUANCE,
+  PROFILE_CHANGE
+}

payguard-identity-service/src/main/java/dev/amg/payguard/identity/verification/domain/enums/OtpStatus.java

@@ -0,0 +1,9 @@
+package dev.amg.payguard.identity.verification.domain.enums;
+
+public enum OtpStatus {
+  ACTIVE,
+  USED,
+  EXPIRED,
+  LOCKED,
+  INVALIDATED
+}

payguard-identity-service/src/main/java/dev/amg/payguard/identity/verification/domain/enums/OtpVerificationMode.java

@@ -0,0 +1,6 @@
+package dev.amg.payguard.identity.verification.domain.enums;
+
+public enum OtpVerificationMode {
+  RANDOM_NUMERIC,
+  TOTP
+}

payguard-identity-service/src/main/java/dev/amg/payguard/identity/verification/domain/enums/OtpVerificationResult.java

@@ -0,0 +1,12 @@
+package dev.amg.payguard.identity.verification.domain.enums;
+
+public enum OtpVerificationResult {
+  VERIFIED,
+  INVALID_CODE,
+  EXPIRED,
+  ALREADY_USED,
+  LOCKED,
+  INVALIDATED,
+  PURPOSE_MISMATCH,
+  DEVICE_MISMATCH
+}

payguard-identity-service/src/main/java/dev/amg/payguard/identity/verification/domain/event/OtpEvent.java

@@ -0,0 +1,18 @@
+package dev.amg.payguard.identity.verification.domain.event;
+
+import dev.amg.payguard.identity.customer.domain.value_object.CustomerId;
+import dev.amg.payguard.identity.customer.domain.value_object.OtpId;
+import dev.amg.payguard.identity.verification.domain.enums.OtpChannel;
+import dev.amg.payguard.identity.verification.domain.enums.OtpPurpose;
+import dev.amg.payguard.identity.verification.domain.enums.OtpVerificationResult;
+import java.time.Instant;
+
+public record OtpEvent(
+    String type,
+    OtpId challengeId,
+    CustomerId customerId,
+    OtpPurpose purpose,
+    OtpChannel channel,
+    OtpVerificationResult result,
+    Instant occurredAt,
+    String reason) {}

payguard-identity-service/src/main/java/dev/amg/payguard/identity/verification/domain/event/OtpEventPublisher.java

@@ -0,0 +1,6 @@
+package dev.amg.payguard.identity.verification.domain.event;
+
+@FunctionalInterface
+public interface OtpEventPublisher {
+  void publish(OtpEvent event);
+}

payguard-identity-service/src/main/java/dev/amg/payguard/identity/verification/domain/exception/InvalidOtpAttemptLimitException.java

@@ -0,0 +1,14 @@
+package dev.amg.payguard.identity.verification.domain.exception;
+
+import java.io.Serial;
+
+public final class InvalidOtpAttemptLimitException extends RuntimeException {
+
+  @Serial private static final long serialVersionUID = 1L;
+  private static final String MESSAGE =
+      "OTP max attempts must be greater than or equal to %d, but was %d.";
+
+  public InvalidOtpAttemptLimitException(int maxAttempts, int minAttempts) {
+    super(MESSAGE.formatted(maxAttempts, minAttempts));
+  }
+}

payguard-identity-service/src/main/java/dev/amg/payguard/identity/verification/domain/exception/OtpAttemptCountOutOfRangeException.java

@@ -0,0 +1,13 @@
+package dev.amg.payguard.identity.verification.domain.exception;
+
+import java.io.Serial;
+
+public final class OtpAttemptCountOutOfRangeException extends RuntimeException {
+
+  @Serial private static final long serialVersionUID = 1L;
+  public static final String MESSAGE = "OTP attempts must be between 0 and %d, but was %d.";
+
+  public OtpAttemptCountOutOfRangeException(int attempts, int maxAttempts) {
+    super(MESSAGE.formatted(maxAttempts, attempts));
+  }
+}

payguard-identity-service/src/main/java/dev/amg/payguard/identity/verification/domain/exception/OtpCodeHashMustNotBeBlankException.java

@@ -0,0 +1,13 @@
+package dev.amg.payguard.identity.verification.domain.exception;
+
+import java.io.Serial;
+
+public final class OtpCodeHashMustNotBeBlankException extends RuntimeException {
+
+  @Serial private static final long serialVersionUID = 1L;
+  public static final String MESSAGE = "OTP code hash must not be blank.";
+
+  public OtpCodeHashMustNotBeBlankException() {
+    super(MESSAGE);
+  }
+}

payguard-identity-service/src/main/java/dev/amg/payguard/identity/verification/domain/exception/OtpCodeHashRequiredForRandomNumericVerificationException.java

@@ -0,0 +1,16 @@
+package dev.amg.payguard.identity.verification.domain.exception;
+
+import dev.amg.payguard.identity.verification.domain.enums.OtpVerificationMode;
+import java.io.Serial;
+
+public final class OtpCodeHashRequiredForRandomNumericVerificationException
+    extends RuntimeException {
+  @Serial private static final long serialVersionUID = 1L;
+
+  public static final String MESSAGE = "OTP code hash is required for %s verification mode.";
+
+  public OtpCodeHashRequiredForRandomNumericVerificationException(
+      OtpVerificationMode verificationMode) {
+    super(MESSAGE.formatted(verificationMode));
+  }
+}

payguard-identity-service/src/main/java/dev/amg/payguard/identity/verification/domain/exception/OtpConsumedTimeMustMatchUsedStatusException.java

@@ -0,0 +1,18 @@
+package dev.amg.payguard.identity.verification.domain.exception;
+
+import java.io.Serial;
+import java.time.Instant;
+
+public final class OtpConsumedTimeMustMatchUsedStatusException extends RuntimeException {
+
+  @Serial private static final long serialVersionUID = 1L;
+  public static final String MESSAGE =
+      """
+            OTP consumption time must be within the challenge validity period. \
+           consumedAt=%s, createdAt=%s, expiresAt=%s.""";
+
+  public OtpConsumedTimeMustMatchUsedStatusException(
+      Instant consumedAt, Instant createdAt, Instant expiresAt) {
+    super(MESSAGE.formatted(consumedAt, createdAt, expiresAt));
+  }
+}

payguard-identity-service/src/main/java/dev/amg/payguard/identity/verification/domain/exception/OtpConsumedTimeOutsideValidityPeriodException.java

@@ -0,0 +1,18 @@
+package dev.amg.payguard.identity.verification.domain.exception;
+
+import java.io.Serial;
+import java.time.Instant;
+
+public final class OtpConsumedTimeOutsideValidityPeriodException extends RuntimeException {
+
+  @Serial private static final long serialVersionUID = 1L;
+  public static final String MESSAGE =
+      """
+           OTP consumption time must be within the validity period. \
+           consumedAt=%s, createdAt=%s, expiresAt=%s""";
+
+  public OtpConsumedTimeOutsideValidityPeriodException(
+      Instant consumedAt, Instant createdAt, Instant expiresAt) {
+    super(MESSAGE.formatted(consumedAt, createdAt, expiresAt));
+  }
+}

payguard-identity-service/src/main/java/dev/amg/payguard/identity/verification/domain/exception/OtpDeviceBindingHashMustNotBeBlankException.java

@@ -0,0 +1,13 @@
+package dev.amg.payguard.identity.verification.domain.exception;
+
+import java.io.Serial;
+
+public final class OtpDeviceBindingHashMustNotBeBlankException extends RuntimeException {
+
+  @Serial private static final long serialVersionUID = 1L;
+  public static final String MESSAGE = "OTP device binding hash must not be blank.";
+
+  public OtpDeviceBindingHashMustNotBeBlankException() {
+    super(MESSAGE);
+  }
+}

payguard-identity-service/src/main/java/dev/amg/payguard/identity/verification/domain/exception/OtpExpirationTimeMustBeAfterCreationTimeException.java

@@ -0,0 +1,13 @@
+package dev.amg.payguard.identity.verification.domain.exception;
+
+import java.io.Serial;
+
+public final class OtpExpirationTimeMustBeAfterCreationTimeException extends RuntimeException {
+
+  @Serial private static final long serialVersionUID = 1L;
+  private static final String MESSAGE = "OTP expiration time must be after the creation time.";
+
+  public OtpExpirationTimeMustBeAfterCreationTimeException() {
+    super(MESSAGE);
+  }
+}

payguard-identity-service/src/main/java/dev/amg/payguard/identity/verification/domain/exception/OtpRetentionPeriodMustNotPrecedeExpirationException.java

@@ -0,0 +1,19 @@
+package dev.amg.payguard.identity.verification.domain.exception;
+
+import java.io.Serial;
+import java.time.Instant;
+
+public class OtpRetentionPeriodMustNotPrecedeExpirationException extends RuntimeException {
+
+  @Serial private static final long serialVersionUID = 1L;
+
+  public static final String MESSAGE =
+      "OTP retention period is invalid: retentionUntil must be after expiresAt. "
+          + "The OTP record cannot be scheduled for removal before or at the same time as its expiration. "
+          + "retentionUntil=%s, expiresAt=%s";
+
+  public OtpRetentionPeriodMustNotPrecedeExpirationException(
+      Instant retentionUntil, Instant expiresAt) {
+    super(MESSAGE.formatted(retentionUntil, expiresAt));
+  }
+}