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;
020import javax.annotation.concurrent.Immutable;
021import java.util.List;
022import java.util.Optional;
023
024/**
025 * An attribute from the covered Assertion. Text values are exposed separately from complex
026 * values so callers cannot mistake nested XML for a scalar identifier.
027 * <p>
028 * Login accepts at most 128 Attribute elements and 256 AttributeValue elements in total across
029 * every AttributeStatement in the assertion. Duplicate names, empty attributes and complex
030 * values count toward those totals. Each exposed text value is limited to 4,096 UTF-16 code
031 * units ({@link String#length()}); Name, NameFormat and FriendlyName are each limited to 2,048
032 * code units, with a nonempty Name required. These fixed limits apply in addition to XML input
033 * and structure limits. If attribute validation is reached, exceeding one rejects the entire login with
034 * {@link SamlAuthenticationResult.Reason#ASSERTION_SHAPE}; attributes are never truncated.
035 * The text limit does not describe opaque complex content or nested NameID validation.
036 *
037 * @since 1.0.0
038 */
039@Immutable
040public final class SamlAttribute {
041    private final @NonNull String name;
042    private final @Nullable String nameFormat;
043    private final @Nullable String friendlyName;
044    private final @NonNull List<@NonNull String> values;
045    private final @NonNull List<@NonNull SamlAttributeValue> typedValues;
046
047    SamlAttribute(@NonNull String name, @Nullable String nameFormat, @Nullable String friendlyName,
048            @NonNull List<@NonNull SamlAttributeValue> typedValues) {
049        this.name = name;
050        this.nameFormat = nameFormat;
051        this.friendlyName = friendlyName;
052        this.typedValues = List.copyOf(typedValues);
053        this.values = List.copyOf(typedValues.stream()
054                .flatMap(value -> value.getText().stream()).toList());
055    }
056
057    /**
058     * Returns the exact attribute Name.
059     *
060     * @return name
061     * @since 1.0.0
062     */
063    public @NonNull String getName() { return name; }
064    /**
065     * Returns the optional NameFormat URI.
066     *
067     * @return optional format
068     * @since 1.0.0
069     */
070    public @NonNull Optional<@NonNull String> getNameFormat() { return Optional.ofNullable(nameFormat); }
071    /**
072     * Returns the optional friendly name for display only.
073     *
074     * @return optional friendly name
075     * @since 1.0.0
076     */
077    public @NonNull Optional<@NonNull String> getFriendlyName() { return Optional.ofNullable(friendlyName); }
078    /**
079     * Returns immutable text values in assertion order.
080     *
081     * @return text values
082     * @since 1.0.0
083     */
084    public @NonNull List<@NonNull String> getValues() { return values; }
085    /**
086     * Returns all values in assertion order, including nested NameID and opaque complex values.
087     *
088     * @return immutable typed values
089     * @since 1.0.0
090     */
091    public @NonNull List<@NonNull SamlAttributeValue> getTypedValues() { return typedValues; }
092    /**
093     * Redacts values and names.
094     *
095     * @return redacted description
096     * @since 1.0.0
097     */
098    @Override public @NonNull String toString() { return "SamlAttribute{<redacted>}"; }
099}