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 result of generating a new password hash.
025 * @since 1.0.0 */
026@Immutable
027public abstract sealed class PasswordHashResult permits PasswordHashResult.Succeeded,
028        PasswordHashResult.Rejected, PasswordHashResult.Unavailable {
029    PasswordHashResult() { }
030
031    static @NonNull PasswordHashResult succeeded(@NonNull PasswordHash hash) { return new Succeeded(hash); }
032    static @NonNull PasswordHashResult rejected(@NonNull PasswordRejectionReason reason) { return new Rejected(reason); }
033    static @NonNull PasswordHashResult unavailable(@NonNull PasswordUnavailableReason reason) { return new Unavailable(reason); }
034
035    /** @return a fixed redacted description
036     * @since 1.0.0 */
037    @Override public final @NonNull String toString() { return "PasswordHashResult{<redacted>}"; }
038
039    /** A new hash is ready for application-owned persistence.
040     * @since 1.0.0 */
041    @Immutable
042    public static final class Succeeded extends PasswordHashResult {
043        private final @NonNull PasswordHash passwordHash;
044        private Succeeded(@NonNull PasswordHash passwordHash) { this.passwordHash = requireNonNull(passwordHash); }
045        /** Returns the generated password hash.
046         * @return the generated hash
047         * @since 1.0.0 */
048        public @NonNull PasswordHash getPasswordHash() { return passwordHash; }
049    }
050
051    /** Input was refused without hashing.
052     * @since 1.0.0 */
053    @Immutable
054    public static final class Rejected extends PasswordHashResult {
055        private final @NonNull PasswordRejectionReason reason;
056        private Rejected(@NonNull PasswordRejectionReason reason) { this.reason = requireNonNull(reason); }
057        /** Returns the reason this input was rejected.
058         * @return fixed rejection reason
059         * @since 1.0.0 */
060        public @NonNull PasswordRejectionReason getReason() { return reason; }
061    }
062
063    /** Work or a required dependency was unavailable; no hash was generated.
064     * @since 1.0.0 */
065    @Immutable
066    public static final class Unavailable extends PasswordHashResult {
067        private final @NonNull PasswordUnavailableReason reason;
068        private Unavailable(@NonNull PasswordUnavailableReason reason) { this.reason = requireNonNull(reason); }
069        /** Returns the reason hashing was unavailable.
070         * @return fixed unavailability reason
071         * @since 1.0.0 */
072        public @NonNull PasswordUnavailableReason getReason() { return reason; }
073    }
074}