001/*
002 * Syncany, www.syncany.org
003 * Copyright (C) 2011-2016 Philipp C. Heckel <philipp.heckel@gmail.com>
004 *
005 * This program is free software: you can redistribute it and/or modify
006 * it under the terms of the GNU General Public License as published by
007 * the Free Software Foundation, either version 3 of the License, or
008 * (at your option) any later version.
009 *
010 * This program is distributed in the hope that it will be useful,
011 * but WITHOUT ANY WARRANTY; without even the implied warranty of
012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
013 * GNU General Public License for more details.
014 *
015 * You should have received a copy of the GNU General Public License
016 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
017 */
018package org.syncany.plugins.transfer.oauth;
019
020import java.net.URI;
021
022import org.syncany.plugins.transfer.StorageException;
023import org.syncany.plugins.transfer.TransferPlugin;
024import org.syncany.plugins.transfer.TransferSettings;
025
026/**
027 * For {@link TransferPlugin}s that base their authentication on OAuth,
028 * a generator class can be used to create the authentication URL and
029 * check the user-provided token. The concrete implementation of this
030 * interface should be provided to the {@link TransferSettings} class
031 * via the {@link OAuth} annotation.<br>
032 * A generator can be extended with {@link OAuthGenerator.WithInterceptor},
033 * {@link OAuthGenerator.WithExtractor} and
034 * {@link OAuthGenerator.WithNoRedirectMode}.
035 *
036 * @author Philipp Heckel (philipp.heckel@gmail.com)
037 * @author Christian Roth (christian.roth@port17.de)
038 */
039public interface OAuthGenerator {
040        /**
041         * Generate a URL which can be accessed by a user to authorize Syncany
042         *
043         * @param redirectUri The URL to which the OAuth provider should redirect in any case (either success or failure)
044         * @return A URL to authorize Syncany using the provided redirectUri
045         * @throws StorageException
046         */
047        URI generateAuthUrl(URI redirectUri) throws StorageException;
048
049        /**
050         * Validate the given token and (optional) csrf parameter.
051         *
052         * @param token Token provided by {@link OAuthTokenWebListener}.
053         * @param csrfState Content of the state parameter (optional).
054         * @throws StorageException
055         */
056        void checkToken(String token, /*@Nullable*/ String csrfState) throws StorageException;
057
058        // Annotation don't support concrete instances of objects, only classes. Thus we need to add two additional interfaces
059        // if a plugin requires custom interceptors or extractors
060
061        /**
062         * Use a custom {@link OAuthTokenInterceptor} instead of the default one which depends on the {@link OAuthMode} in use.
063         *
064         * See: {@link OAuthTokenInterceptor}
065         */
066        interface WithInterceptor {
067                OAuthTokenInterceptor getInterceptor();
068        }
069
070        /**
071         * Use a custom {@link OAuthTokenExtractor} instead of the default one which depends on the {@link OAuthMode} in use.
072         *
073         * See: {@link OAuthTokenExtractor}
074         */
075        interface WithExtractor {
076                OAuthTokenExtractor getExtractor();
077        }
078
079        /**
080         * If an OAuth based plugin also supports copy&amp;pasting a token from a website it should extend this interface.
081         */
082        interface WithNoRedirectMode {
083                /**
084                 * Called if Syncany is started in headless mode which does not support redirect_to URLs.<br>
085                 * The website should output a token which can be copied over to Syncany's repo wizard.
086                 *
087                 * @return A URL with no redirect URL
088                 * @throws StorageException
089                 */
090                URI generateAuthUrl() throws StorageException;
091        }
092}