001/*
002 *  Copyright 2022 Anyware Services
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 org.ametys.core.captcha;
017
018import java.util.Collection;
019import java.util.List;
020import java.util.regex.Pattern;
021
022import org.apache.excalibur.source.SourceException;
023
024import org.ametys.runtime.i18n.I18nizableText;
025
026/**
027 * Interface for Captchas
028 */
029public interface Captcha
030{    
031    /**
032     * Get the Captcha type label
033     * @return the label
034     */
035    public I18nizableText getLabel();
036    
037    /**
038     * Get the Captcha type id
039     * @return the id
040     */
041    public String getId();
042    
043    /**
044     * Get the list of config parameters referenced by this captcha implementation
045     * @return list of parameters
046     */
047    public Collection<String> getConfigParameters();
048
049    /**
050     * Check if the Captcha is correct
051     * @param key the key
052     * @param value the value
053     * @return true if correct
054     */
055    public boolean checkAndInvalidateCaptcha(String key, String value);
056
057    /**
058     * Get the helper xsl file
059     * @return the source
060     * @throws SourceException if an error occurred while reading the xsl file
061     */
062    public String getXSLHelperURL() throws SourceException;
063    
064    /**
065     * Get the scss file
066     * @return the source
067     * @throws SourceException if an error occurred while reading the xsl file
068     */
069    public String getLoginSCSSURL() throws SourceException;
070
071    /**
072     * Get the label to display when login has failed with this captcha
073     * @return the label
074     */
075    public I18nizableText getLoginFailedBecauseCaptchaFailedLabel();
076    
077    /**
078     * Get the label to display when too many attempt have been done
079     * @return the label
080     */
081    public I18nizableText getLoginFailedBecauseTooManyAttemptLabel();
082
083    /**
084     * Get the minimal url patterns used by the captcha implementation. 
085     * This is necessary to grant those url even when the user is not authentified (in particular to set a catpcha on the login page). 
086     * Do no put a too wide range (such as ^.*$) since it may introduce security issues.
087     * @return The minimal url patterns used by the captcha implementation.
088     */
089    public List<Pattern> getUsedUrlPatterns();
090    
091    /**
092     * Indicate if the captcha requires user interaction and should be displayed as a form entry
093     * @return true if the captcha requires user interaction
094     */
095    public default boolean requireUserInteraction()
096    {
097        // Most implementation will require user interaction
098        return true;
099    }
100}