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.saml;
017
018import org.jspecify.annotations.NonNull;
019import org.jspecify.annotations.Nullable;
020
021import javax.annotation.concurrent.Immutable;
022import java.util.Optional;
023
024/**
025 * One checked SAML AttributeValue. Nilled values and XML with unrecognized element
026 * content are retained as {@link Kind#COMPLEX} without exposing a flattened
027 * string or an untrusted DOM node. A leaf's signed text is exposed independent
028 * of its {@code xsi:type} prefix binding, which exclusive XML canonicalization
029 * need not sign. Applications interpret any domain-specific type themselves.
030 *
031 * @since 1.0.0
032 */
033@Immutable
034public final class SamlAttributeValue {
035    /**
036     * The supported shape of this value.
037     *
038     * @since 1.0.0
039     */
040    @Immutable
041    public enum Kind {
042        /** An element-free text value. */
043        TEXT,
044        /** A nested SAML NameID. */
045        NAME_ID,
046        /** Element content whose shape is not mapped to a scalar. */
047        COMPLEX
048    }
049
050    private final @NonNull Kind kind;
051    private final @Nullable String text;
052    private final @Nullable SamlNameId nameId;
053
054    private SamlAttributeValue(@NonNull Kind kind, @Nullable String text, @Nullable SamlNameId nameId) {
055        this.kind = kind;
056        this.text = text;
057        this.nameId = nameId;
058    }
059
060    static @NonNull SamlAttributeValue text(@NonNull String value) {
061        return new SamlAttributeValue(Kind.TEXT, value, null);
062    }
063
064    static @NonNull SamlAttributeValue nameId(@NonNull SamlNameId value) {
065        return new SamlAttributeValue(Kind.NAME_ID, null, value);
066    }
067
068    static @NonNull SamlAttributeValue complex() {
069        return new SamlAttributeValue(Kind.COMPLEX, null, null);
070    }
071
072    /**
073     * Reports whether this value is text, a nested NameID, or opaque complex content.
074     *
075     * @return the value shape
076     * @since 1.0.0
077     */
078    public @NonNull Kind getKind() { return kind; }
079
080    /**
081     * Reads a scalar value without flattening nested XML.
082     *
083     * @return text only for an element-free, non-nilled value
084     * @since 1.0.0
085     */
086    public @NonNull Optional<@NonNull String> getText() { return Optional.ofNullable(text); }
087
088    /**
089     * Reads a recognized nested NameID with its qualifiers.
090     *
091     * @return a nested SAML NameID when it is the sole well-formed child
092     * @since 1.0.0
093     */
094    public @NonNull Optional<@NonNull SamlNameId> getNameId() { return Optional.ofNullable(nameId); }
095
096    /**
097     * @return a redacted description
098     * @since 1.0.0
099     */
100    @Override public @NonNull String toString() { return "SamlAttributeValue{" + kind + ", <redacted>}"; }
101}