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}