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 */
016
017package com.revetsec.scim;
018
019import com.google.errorprone.annotations.CheckReturnValue;
020import org.jspecify.annotations.NonNull;
021import org.jspecify.annotations.Nullable;
022import javax.annotation.concurrent.Immutable;
023import javax.annotation.concurrent.NotThreadSafe;
024import java.net.URI;
025import java.util.Objects;
026import java.util.Optional;
027import java.util.Set;
028
029/**
030 * Immutable description of an application authentication scheme; it performs no authentication.
031 * Specification and documentation links are trusted bounded HTTP(S) URIs and are never fetched.
032 * @since 1.0.0
033 */
034@Immutable
035@CheckReturnValue
036public final class ScimAuthenticationScheme {
037    private final @NonNull String type;
038    private final @NonNull String name;
039    private final @NonNull String description;
040    private final boolean primary;
041    private final @Nullable URI specUri;
042    private final @Nullable URI documentationUri;
043
044    private ScimAuthenticationScheme(@NonNull Builder builder) {
045        if (builder.name == null || builder.description == null)
046            throw new IllegalStateException("A SCIM authentication scheme requires name and description.");
047        type = builder.type;
048        name = builder.name;
049        description = builder.description;
050        primary = Boolean.TRUE.equals(builder.primary);
051        specUri = builder.specUri;
052        documentationUri = builder.documentationUri;
053    }
054
055    /**
056     * Starts a standard authentication scheme with its exact SCIM type spelling.
057     * @param type oauth, oauth2, oauthbearertoken, httpbasic or httpdigest
058     * @return a new builder
059     * @since 1.0.0
060     */
061    public static @NonNull Builder withType(@NonNull String type) {
062        ScimSchemas.requireName(Objects.requireNonNull(type));
063        if (!Set.of("oauth", "oauth2", "oauthbearertoken", "httpbasic", "httpdigest").contains(type))
064            throw new IllegalArgumentException("Unsupported standard SCIM authentication scheme type.");
065        return new Builder(type);
066    }
067
068    /**
069     * Returns the exact standard scheme type.
070     * @return the exact standard scheme type
071     * @since 1.0.0
072     */
073    public @NonNull String getType() { return type; }
074
075    /**
076     * Returns the human-readable scheme name.
077     * @return the human-readable scheme name
078     * @since 1.0.0
079     */
080    public @NonNull String getName() { return name; }
081
082    /**
083     * Returns the scheme description.
084     * @return the scheme description
085     * @since 1.0.0
086     */
087    public @NonNull String getDescription() { return description; }
088
089    /**
090     * Returns whether this is the preferred scheme.
091     * @return whether this is the preferred scheme
092     * @since 1.0.0
093     */
094    public @NonNull Boolean isPrimary() { return primary; }
095
096    /**
097     * Returns the optional specification URI.
098     * @return the optional specification URI
099     * @since 1.0.0
100     */
101    public @NonNull Optional<@NonNull URI> getSpecUri() { return Optional.ofNullable(specUri); }
102
103    /**
104     * Returns the optional documentation URI.
105     * @return the optional documentation URI
106     * @since 1.0.0
107     */
108    public @NonNull Optional<@NonNull URI> getDocumentationUri() { return Optional.ofNullable(documentationUri); }
109
110    /**
111     * Compares all scheme description characteristics.
112     * @param other the comparison value
113     * @return whether descriptions are equal
114     * @since 1.0.0
115     */
116    @Override public boolean equals(@Nullable Object other) {
117        return this == other || (other instanceof ScimAuthenticationScheme value && primary == value.primary
118                && type.equals(value.type) && name.equals(value.name) && description.equals(value.description)
119                && Objects.equals(specUri, value.specUri) && Objects.equals(documentationUri, value.documentationUri));
120    }
121
122    /**
123     * Returns the scheme description hash.
124     * @return the description hash
125     * @since 1.0.0
126     */
127    @Override public int hashCode() { return Objects.hash(type, name, description, primary, specUri, documentationUri); }
128
129    /**
130     * Returns a fixed redacted description.
131     * @return a fixed redacted description
132     * @since 1.0.0
133     */
134    @Override public @NonNull String toString() { return "ScimAuthenticationScheme{<redacted>}"; }
135
136    /**
137     * Mutable, non-thread-safe authentication-scheme description configuration.
138     * @since 1.0.0
139     */
140    @NotThreadSafe
141    @CheckReturnValue
142    public static final class Builder {
143        private final @NonNull String type;
144        private @Nullable String name;
145        private @Nullable String description;
146        private @Nullable Boolean primary;
147        private @Nullable URI specUri;
148        private @Nullable URI documentationUri;
149        private Builder(@NonNull String type) { this.type = type; }
150
151        /**
152         * Sets name; null restores unset.
153         * @param value the setting, or null to restore its default
154         * @return this builder
155         * @since 1.0.0
156         */
157        public @NonNull Builder name(@Nullable String value) { name = value == null ? null : ScimSchemas.requireName(value); return this; }
158
159        /**
160         * Sets description; null restores unset.
161         * @param value the setting, or null to restore its default
162         * @return this builder
163         * @since 1.0.0
164         */
165        public @NonNull Builder description(@Nullable String value) { description = value == null ? null : ScimSchemas.requireText(value, true); return this; }
166
167        /**
168         * Sets primary; null restores false.
169         * @param value the setting, or null to restore its default
170         * @return this builder
171         * @since 1.0.0
172         */
173        public @NonNull Builder primary(@Nullable Boolean value) { primary = value; return this; }
174
175        /**
176         * Sets specUri; null restores absent.
177         * @param value the setting, or null to restore its default
178         * @return this builder
179         * @since 1.0.0
180         */
181        public @NonNull Builder specUri(@Nullable URI value) { specUri = value == null ? null : ScimSchemas.requireDocumentationUri(value); return this; }
182
183        /**
184         * Sets documentationUri; null restores absent.
185         * @param value the setting, or null to restore its default
186         * @return this builder
187         * @since 1.0.0
188         */
189        public @NonNull Builder documentationUri(@Nullable URI value) { documentationUri = value == null ? null : ScimSchemas.requireDocumentationUri(value); return this; }
190
191        /**
192         * Validates required descriptions and creates an immutable scheme.
193         * @return the authentication-scheme description
194         * @since 1.0.0
195         */
196        public @NonNull ScimAuthenticationScheme build() { return new ScimAuthenticationScheme(this); }
197    }
198}