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}