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.saml;
018
019import org.jspecify.annotations.NonNull;
020import org.jspecify.annotations.Nullable;
021
022import javax.annotation.concurrent.Immutable;
023import java.util.Optional;
024
025/**
026 * A validated NameID with its identity-significant qualifiers. The value alone is not a stable
027 * cross-tenant account key. Transient and unspecified formats never yield a {@link SamlSubjectKey}.
028 *
029 * @since 1.0.0
030 */
031@Immutable
032public final class SamlNameId {
033    static final String PERSISTENT = "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent";
034    static final String TRANSIENT = "urn:oasis:names:tc:SAML:2.0:nameid-format:transient";
035
036    private final @NonNull String value;
037    private final @Nullable String format;
038    private final @Nullable String nameQualifier;
039    private final @Nullable String spNameQualifier;
040    private final @Nullable String spProvidedId;
041
042    SamlNameId(@NonNull String value, @Nullable String format, @Nullable String nameQualifier,
043            @Nullable String spNameQualifier) {
044        this(value, format, nameQualifier, spNameQualifier, null);
045    }
046
047    SamlNameId(@NonNull String value, @Nullable String format, @Nullable String nameQualifier,
048            @Nullable String spNameQualifier, @Nullable String spProvidedId) {
049        this.value = value;
050        this.format = format;
051        this.nameQualifier = nameQualifier;
052        this.spNameQualifier = spNameQualifier;
053        this.spProvidedId = spProvidedId;
054    }
055
056    /**
057     * Returns the validated NameID text.
058     *
059     * @return value
060     * @since 1.0.0
061     */
062    public @NonNull String getValue() { return value; }
063    /**
064     * Returns the format URI when present.
065     *
066     * @return optional format
067     * @since 1.0.0
068     */
069    public @NonNull Optional<@NonNull String> getFormat() { return Optional.ofNullable(format); }
070    /**
071     * Returns the NameQualifier when present.
072     *
073     * @return optional qualifier
074     * @since 1.0.0
075     */
076    public @NonNull Optional<@NonNull String> getNameQualifier() { return Optional.ofNullable(nameQualifier); }
077    /**
078     * Returns the SPNameQualifier when present.
079     *
080     * @return optional qualifier
081     * @since 1.0.0
082     */
083    public @NonNull Optional<@NonNull String> getSpNameQualifier() { return Optional.ofNullable(spNameQualifier); }
084    /**
085     * Returns the SPProvidedID when the IdP supplied one. This attribute is retained for
086     * exact NameID matching and outbound Single Logout.
087     *
088     * @return optional SPProvidedID
089     * @since 1.0.0
090     */
091    public @NonNull Optional<@NonNull String> getSpProvidedId() { return Optional.ofNullable(spProvidedId); }
092    /**
093     * Reports whether the format explicitly marks this identifier transient.
094     *
095     * @return true for transient
096     * @since 1.0.0
097     */
098    public @NonNull Boolean isTransient() { return TRANSIENT.equals(format); }
099    /**
100     * Redacts the subject.
101     *
102     * @return redacted description
103     * @since 1.0.0
104     */
105    @Override public @NonNull String toString() { return "SamlNameId{<redacted>}"; }
106
107    boolean persistent() { return PERSISTENT.equals(format); }
108    @Nullable String rawFormat() { return format; }
109    @Nullable String rawNameQualifier() { return nameQualifier; }
110    @Nullable String rawSpNameQualifier() { return spNameQualifier; }
111    @Nullable String rawSpProvidedId() { return spProvidedId; }
112}