001/*
002 * Copyright © 2025 CUI-OpenSource-Software (info@cuioss.de)
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 de.cuioss.http.security.core;
017
018/**
019 * Enumeration of different types of HTTP components that require validation.
020 * Each validation type may have different security requirements and validation rules.
021 *
022 * <h3>Design Principles</h3>
023 * <ul>
024 *   <li><strong>Type Safety</strong> - Provides compile-time safety for validation contexts</li>
025 *   <li><strong>Context Awareness</strong> - Different validation rules per component type</li>
026 *   <li><strong>Performance</strong> - Enables optimized validation strategies per type</li>
027 *   <li><strong>Extensibility</strong> - Easy to add new HTTP component types</li>
028 * </ul>
029 *
030 * <h3>Usage Example</h3>
031 * <pre>
032 * // Validate URL path component
033 * validator.validate("/api/users", ValidationType.URL_PATH);
034 *
035 * // Validate query parameter name
036 * validator.validate("userId", ValidationType.PARAMETER_NAME);
037 *
038 * // Validate HTTP header value
039 * validator.validate("Bearer token123", ValidationType.HEADER_VALUE);
040 * </pre>
041 *
042 * Supports: Task B2 from HTTP verification specification
043 *
044 * @since 1.0
045 */
046public enum ValidationType {
047
048    /** URL path segments (e.g., "/api/users/123") */
049    URL_PATH,
050
051    /** Query parameter names (e.g., "userId" in "?userId=123") */
052    PARAMETER_NAME,
053
054    /** Query parameter values (e.g., "123" in "?userId=123") */
055    PARAMETER_VALUE,
056
057    /** HTTP header names (e.g., "Authorization", "Content-Type") */
058    HEADER_NAME,
059
060    /** HTTP header values (e.g., "Bearer token123", "application/json") */
061    HEADER_VALUE,
062
063    /** Cookie names (e.g., "JSESSIONID", "auth_token") */
064    COOKIE_NAME,
065
066    /** Cookie values (e.g., session identifiers, authentication tokens) */
067    COOKIE_VALUE,
068
069    /** Request/response body content */
070    BODY;
071
072    /**
073     * Determines if this validation type requires URL decoding during processing.
074     * URL decoding is typically needed for components that may contain percent-encoded sequences.
075     *
076     * @return true if URL decoding should be applied before validation
077     */
078    public boolean requiresDecoding() {
079        return this == URL_PATH ||
080                this == PARAMETER_NAME ||
081                this == PARAMETER_VALUE;
082    }
083
084    /**
085     * Determines if this validation type represents a key/name component.
086     * Key components typically have more restrictive character sets and length limits.
087     *
088     * @return true if this type represents a key/name component
089     */
090    public boolean isKey() {
091        return this == PARAMETER_NAME ||
092                this == HEADER_NAME ||
093                this == COOKIE_NAME;
094    }
095
096    /**
097     * Determines if this validation type represents a value component.
098     * Value components may allow a broader range of characters and content.
099     *
100     * @return true if this type represents a value component
101     */
102    public boolean isValue() {
103        return this == PARAMETER_VALUE ||
104                this == HEADER_VALUE ||
105                this == COOKIE_VALUE;
106    }
107
108    /**
109     * Determines if this validation type represents HTTP body content.
110     * Body content has special handling for different content types and encodings.
111     *
112     * @return true if this type represents body content
113     */
114    public boolean isBody() {
115        return this == BODY;
116    }
117
118    /**
119     * Determines if this validation type represents a path component.
120     * Path components have specific rules for traversal detection and normalization.
121     *
122     * @return true if this type represents a path component
123     */
124    public boolean isPath() {
125        return this == URL_PATH;
126    }
127
128    /**
129     * Determines if this validation type represents HTTP header content.
130     * Header components (names and values) have RFC-specific formatting rules.
131     *
132     * @return true if this type represents header content
133     */
134    public boolean isHeader() {
135        return this == HEADER_NAME || this == HEADER_VALUE;
136    }
137
138    /**
139     * Determines if this validation type represents cookie content.
140     * Cookie components have specific encoding and security requirements.
141     *
142     * @return true if this type represents cookie content
143     */
144    public boolean isCookie() {
145        return this == COOKIE_NAME || this == COOKIE_VALUE;
146    }
147
148    /**
149     * Determines if this validation type represents parameter content.
150     * Parameter components are commonly targeted in injection attacks.
151     *
152     * @return true if this type represents parameter content
153     */
154    public boolean isParameter() {
155        return this == PARAMETER_NAME || this == PARAMETER_VALUE;
156    }
157}