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}