001/* 002 * Copyright 2026 Revetware LLC. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016package com.revetsec.password; 017 018import org.jspecify.annotations.NonNull; 019 020import javax.annotation.concurrent.Immutable; 021 022import static java.util.Objects.requireNonNull; 023 024/** Complete local password-verification result. Only {@link Matched} proves that the submitted 025 * password matches the selected stored verifier; the application still owns account admission, 026 * credential-version checks, and the remaining login flow. 027 * @since 1.0.0 */ 028@Immutable 029public abstract sealed class PasswordVerificationResult permits PasswordVerificationResult.Matched, 030 PasswordVerificationResult.NotMatched, PasswordVerificationResult.Rejected, 031 PasswordVerificationResult.Unavailable { 032 private static final @NonNull NotMatched NOT_MATCHED = new NotMatched(); 033 PasswordVerificationResult() { } 034 035 static @NonNull PasswordVerificationResult matched(boolean rehashRecommended) { return new Matched(rehashRecommended); } 036 static @NonNull PasswordVerificationResult notMatched() { return NOT_MATCHED; } 037 static @NonNull PasswordVerificationResult rejected(@NonNull PasswordRejectionReason reason) { return new Rejected(reason); } 038 static @NonNull PasswordVerificationResult unavailable(@NonNull PasswordUnavailableReason reason) { return new Unavailable(reason); } 039 040 /** @return a fixed redacted description 041 * @since 1.0.0 */ 042 @Override public final @NonNull String toString() { return "PasswordVerificationResult{<redacted>}"; } 043 044 /** The submitted complete password matched the selected stored verifier. 045 * @since 1.0.0 */ 046 @Immutable 047 public static final class Matched extends PasswordVerificationResult { 048 private final boolean rehashRecommended; 049 private Matched(boolean rehashRecommended) { this.rehashRecommended = rehashRecommended; } 050 /** Whether the application should generate a current-policy hash and atomically replace 051 * the exact current credential. This method does not perform or establish a write. 052 * @return whether an upgrade is recommended 053 * @since 1.0.0 */ 054 public @NonNull Boolean isRehashRecommended() { return rehashRecommended; } 055 } 056 057 /** The submitted password did not match. 058 * @since 1.0.0 */ 059 @Immutable 060 public static final class NotMatched extends PasswordVerificationResult { 061 private NotMatched() { } 062 } 063 064 /** An input or stored verifier was invalid or unsupported under this operation. 065 * @since 1.0.0 */ 066 @Immutable 067 public static final class Rejected extends PasswordVerificationResult { 068 private final @NonNull PasswordRejectionReason reason; 069 private Rejected(@NonNull PasswordRejectionReason reason) { this.reason = requireNonNull(reason); } 070 /** Returns the reason this input was rejected. 071 * @return fixed rejection reason 072 * @since 1.0.0 */ 073 public @NonNull PasswordRejectionReason getReason() { return reason; } 074 } 075 076 /** Work or a required dependency was unavailable; no password match was established. 077 * @since 1.0.0 */ 078 @Immutable 079 public static final class Unavailable extends PasswordVerificationResult { 080 private final @NonNull PasswordUnavailableReason reason; 081 private Unavailable(@NonNull PasswordUnavailableReason reason) { this.reason = requireNonNull(reason); } 082 /** Returns the reason verification was unavailable. 083 * @return fixed unavailability reason 084 * @since 1.0.0 */ 085 public @NonNull PasswordUnavailableReason getReason() { return reason; } 086 } 087}