001// License: GPL. For details, see LICENSE file.
002package org.openstreetmap.josm.io.auth;
003
004import java.awt.Component;
005import java.net.Authenticator.RequestorType;
006import java.net.PasswordAuthentication;
007
008import org.openstreetmap.josm.data.oauth.IOAuthToken;
009
010import jakarta.annotation.Nullable;
011
012/**
013 * A CredentialsAgent manages two credentials:
014 * <ul>
015 *   <li>the credential for {@link RequestorType#SERVER} which is equal to the OSM API credentials
016 *   in JOSM</li>
017 *   <li>the credential for {@link RequestorType#PROXY} which is equal to the credentials for an
018 *   optional HTTP proxy server a user may use</li>
019 *  </ul>
020 *
021 *  In addition, it manages an OAuth Access Token for accessing the OSM server.
022 */
023public interface CredentialsAgent {
024
025    /**
026     * Looks up the credentials for a given type.
027     *
028     * @param requestorType the type of service. {@link RequestorType#SERVER} for the OSM API server, {@link RequestorType#PROXY}
029     * for a proxy server
030     * @param host the hostname for these credentials
031     * @return the credentials
032     * @throws CredentialsAgentException if a problem occurs in a implementation of this interface
033     */
034    PasswordAuthentication lookup(RequestorType requestorType, String host) throws CredentialsAgentException;
035
036    /**
037     * Saves the credentials in <code>credentials</code> for the given service type.
038     *
039     * @param requestorType the type of service. {@link RequestorType#SERVER} for the OSM API server, {@link RequestorType#PROXY}
040     * for a proxy server
041     * @param host the hostname for these credentials
042     * @param credentials the credentials
043     * @throws CredentialsAgentException if a problem occurs in a implementation of this interface
044     */
045    void store(RequestorType requestorType, String host, PasswordAuthentication credentials) throws CredentialsAgentException;
046
047    /**
048     * Returns the credentials needed to to access host.
049     * @param requestorType the type of service. {@link RequestorType#SERVER} for the OSM API server, {@link RequestorType#PROXY}
050     * for a proxy server
051     * @param host the hostname for these credentials
052     * @param noSuccessWithLastResponse true, if the last request with the supplied credentials failed; false otherwise.
053     * If true, implementations of this interface are advised to prompt the user for new credentials.
054     * @return the credentials
055     * @throws CredentialsAgentException if a problem occurs in a implementation of this interface
056     */
057    CredentialsAgentResponse getCredentials(RequestorType requestorType, String host, boolean noSuccessWithLastResponse)
058            throws CredentialsAgentException;
059
060    /**
061     * Lookup the current OAuth Access Token to access the specified server. Replies null, if no
062     * Access Token is currently managed by this CredentialAgent.
063     *
064     * @param host The host to get OAuth credentials for
065     * @return the current OAuth Access Token to access the specified server.
066     * @throws CredentialsAgentException if something goes wrong
067     * @since 18650
068     */
069    @Nullable
070    IOAuthToken lookupOAuthAccessToken(String host) throws CredentialsAgentException;
071
072    /**
073     * Stores the OAuth Access Token <code>accessToken</code>.
074     *
075     * @param host The host the access token is for
076     * @param accessToken the access Token. null, to remove the Access Token. This will remove all IOAuthTokens <i>not</i> managed by
077     *                    {@link #storeOAuthAccessToken(String, IOAuthToken)}.
078     * @throws CredentialsAgentException if something goes wrong
079     * @since 18650
080     */
081    void storeOAuthAccessToken(String host, IOAuthToken accessToken) throws CredentialsAgentException;
082
083    /**
084     * Purges the internal credentials cache for the given requestor type.
085     * @param requestorType the type of service.
086     * {@link RequestorType#PROXY} for a proxy server, {@link RequestorType#SERVER} for other servers.
087     * @since 12992
088     */
089    void purgeCredentialsCache(RequestorType requestorType);
090
091    /**
092     * Purges the internal credentials cache for the given requestor type and host.
093     * @param requestorType the type of service.
094     * @param host the host.
095     * {@link RequestorType#PROXY} for a proxy server, {@link RequestorType#SERVER} for other servers.
096     */
097    default void purgeCredentialsCache(RequestorType requestorType, String host) {
098        purgeCredentialsCache(requestorType);
099    }
100
101    /**
102     * Provide a Panel that is shown below the API password / username fields
103     * in the JOSM Preferences. (E.g. a warning that password is saved unencrypted.)
104     * @return Panel
105     */
106    Component getPreferencesDecorationPanel();
107}