Add refresh token authentication

Author: BlazOrazem

.gitignore

@@ -1,2 +1,3 @@
 .idea
 *.cache
+/vendor

CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2025-07-13
+### Changes
+- Implemented **OAuth2 Refresh Token Flow** for Dropbox authentication.
+  - Provides a more secure and persistent authentication method.
+  - Eliminates the need for manual token renewal every 4 hours.
+  - Includes a new console command (`php artisan dropboxadapter:setup`) to generate and manage refresh tokens.
+- Introduced **Temporary Token Flow** for quick setup and development environments.
+  - Allows direct use of short-lived access tokens for testing.
+- Enhanced `.env` configuration to support both authentication modes via `DROPBOX_AUTH_MODE`.
+
 ## [1.0.0] - 2025-07-08
 ### Added
 - Initial release of the **DropboxAdapter Plugin**.
@@ -15,7 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Notes
 - **Not compatible** with `media` or `uploads` disks in Winter CMS.
-- Intended for developer-oriented scenarios such as automation, deployment, or remote sync—not general file management.
+- Intended for developer-oriented scenarios such as automation, deployment, or remote sync — not general file management.
 
 ---
 

Plugin.php

@@ -1,6 +1,7 @@
 <?php namespace NumenCode\DropboxAdapter;
 
 use System\Classes\PluginBase;
+use NumenCode\DropboxAdapter\Console\DropboxSetupCommand;
 use NumenCode\DropboxAdapter\Providers\DropboxServiceProvider;
 
 class Plugin extends PluginBase
@@ -20,4 +21,14 @@ public function boot()
     {
         $this->app->register(DropboxServiceProvider::class);
     }
+
+    public function register()
+    {
+        $this->registerConsoleCommands();
+    }
+
+    protected function registerConsoleCommands()
+    {
+        $this->registerConsoleCommand('numencode.dropboxadapter_setup', DropboxSetupCommand::class);
+    }
 }

README.md

@@ -1,7 +1,7 @@
 # Dropbox Adapter Plugin
 
 The **Dropbox Adapter Plugin** provides Dropbox v2 API integration with Winter CMS as a custom filesystem disk driver.
-This allows limited usage of Dropbox with Laravel's Storage facade—primarily for custom logic and backup tools such as
+This allows limited usage of Dropbox with Laravel's Storage facade — primarily for custom logic and backup tools such as
 [`NumenCode.SyncOps`](https://github.com/numencode/wn-syncops-plugin).
 
 [![Version](https://img.shields.io/github/v/release/numencode/wn-dropboxadapter-plugin?style=flat-square&color=0099FF)](https://github.com/numencode/wn-dropboxadapter-plugin/releases)
@@ -21,6 +21,8 @@ Laravel’s filesystem abstraction, especially for automation, remote syncing, a
 > filesystem for core `media` or `uploads` disks. This plugin is not intended for direct media asset management,
 > but rather for use cases like backup transport, cloud storage sync, or custom plugin integration (e.g. [`NumenCode.SyncOps`](https://github.com/numencode/wn-syncops-plugin)).
 
+---
+
 ## Installation
 
 This plugin is available for installation via [Composer](http://getcomposer.org/).
@@ -37,38 +39,123 @@ php artisan winter:up
 
 ## Requirements
 
-* [Winter CMS](https://wintercms.com/) version 1.2.7 or newer
-* PHP 8.0 or later
-* A Dropbox API access token
+- [Winter CMS](https://wintercms.com) version 1.2.7 or newer
+- PHP 8.0 or later
+- A Dropbox App (created in the [Dropbox App Console](https://www.dropbox.com/developers/apps))
+    - For **Refresh Token Flow**: You'll need your `App key` and `App secret`.
+    - For **Temporary Token Flow**: You'll need a manually generated `Access token`.
 
-## Configuration
+## Configuration and Authentication
 
-1. Create a Dropbox App in the [Dropbox App Console](https://www.dropbox.com/developers/apps) and generate an access token.
-2. Define a new filesystem disk in your `config/filesystems.php` file:
-    ```php
-    'dropbox' => [
-        'driver' => 'dropbox',
-        'authorization_token' => env('DROPBOX_AUTH_TOKEN'),
-    ],
-    ```
-3. Add the token to your `.env` file:
+This plugin offers two methods for authenticating with the Dropbox API: the **Refresh Token Flow** (recommended for
+production and long-term use) and the **Temporary Token Flow** (ideal for quick development or testing).
+You can switch between these modes in your `.env` file.
+
+### 1. Create a Dropbox App
+
+Regardless of the authentication method, you need to [create a Dropbox App](https://www.dropbox.com/developers/apps).
+
+When creating your app:
+
+- Choose **"Scoped access"** and select the permissions your application needs (e.g.,
+  `files.content.write`, `files.content.read` for read/write access).
+
+### 2. Choose your authentication method
+
+You specify the authentication method in your `.env` file using the `DROPBOX_AUTH_MODE` variable.
+You can choose between `refresh_token` and `temp_token` modes.
+
+#### a. Refresh Token Flow (recommended for production)
+
+This is the **secure and persistent** way to authenticate. It uses a long-lived **refresh token** to automatically
+obtain new, short-lived **access tokens** as needed, eliminating the need for manual intervention when tokens expire.
+
+###### Setup Steps:
+
+1. **Add Dropbox App credentials to `.env`**:
+
+   You'll need your Dropbox `App key` and `App secret`.
     ```dotenv
-    DROPBOX_AUTH_TOKEN=your_generated_token
+    DROPBOX_AUTH_MODE=refresh_token
+    DROPBOX_APP_KEY=
+    DROPBOX_APP_SECRET=
+    DROPBOX_REFRESH_TOKEN=
+    ```
+
+2. **Generate your refresh token**:
+
+   Use the provided console command to go through the OAuth2 authorization process and obtain your refresh token:
+    ```bash
+    php artisan dropboxadapter:setup
     ```
-    You can now interact with Dropbox programmatically using the Storage facade in Laravel:
-    ```php
-    Storage::disk('dropbox')->put('backups/site.zip', $contents);
+
+   Follow the on-screen prompts:
+    - It will ask for your **Dropbox App key**.
+    - It will provide a URL to open in your browser. Authorize your app on Dropbox. After authorization, Dropbox will
+      provide an "authorization code" (often in the URL parameters if no redirect URI is set, or directly on the
+      success page). Copy this `code`.
+    - Paste the `authorization code` back into the console.
+    - Enter your **Dropbox App secret**.
+    - The command will then exchange this code for a refresh token and display it.
+
+3. **Update `.env` with refresh token**:
+
+   Copy the generated refresh token and add it to your `.env` file.
+
+#### b. Temporary Token Flow (for development/testing only)
+
+This method is quick and easy for **temporary testing**, but the token will **expire after 4 hours** and requires
+manual renewal. **Do not use this in production.**
+
+###### Setup Steps:
+
+1. **Generate a temporary access token:**
+
+   - Go to your [Dropbox App Console](https://www.dropbox.com/developers/apps).
+   - Navigate to your app's settings.
+   - Under "OAuth 2", find the "Generated access token" section and click "Generate". Copy this token.
+
+2. **Add temporary token to `.env`:**
+
+    ```dotenv
+    DROPBOX_AUTH_MODE=temp_token
+    DROPBOX_TEMP_TOKEN=
     ```
-   This is especially useful for custom automation (e.g., deployment scripts or remote backup workflows).
+
+    **Important:** If using this mode, the `DROPBOX_APP_KEY`, `DROPBOX_APP_SECRET`,
+    and `DROPBOX_REFRESH_TOKEN` variables are ignored by the plugin.
+
+### 3. Define the dropbox disk
+
+Once you have configured your chosen authentication method in `.env`,
+define a new filesystem disk in your `config/filesystems.php` file:
+
+```php
+'dropbox' => [
+    'driver' => 'dropbox',
+],
+```
+
+### 4. Usage with Storage Facade
+
+You can now interact with Dropbox programmatically using the Storage facade in Laravel:
+
+```php
+Storage::disk('dropbox')->put('backups/site.zip', $contents);
+```
+
+This is especially useful for custom automation (e.g., deployment scripts or remote backup workflows).
 
 ## Limitations
+
 - **Not compatible with Winter CMS native `media` or `uploads` disks.**
 - **Not suitable for asset serving or file uploading through the CMS backend UI.**
 
 Use Dropbox through this plugin **only for custom filesystem operations** that are manually invoked or triggered
 via automation (e.g., within the [`NumenCode.SyncOps`](https://github.com/numencode/wn-syncops-plugin) plugin or similar).
 
 ## Example Use Case
+
 This plugin was created to support [`NumenCode.SyncOps`](https://github.com/numencode/wn-syncops-plugin),
 a Winter CMS plugin for managing deployments, backups, and environment synchronization. Dropbox serves as a
 remote storage destination for sync packages or archive backups.

composer.json

@@ -19,7 +19,7 @@
     ],
     "require": {
         "php": "^8.0.2",
-        "winter/storm": "^1.2.7",
+        "winter/storm": "^1.2",
         "spatie/flysystem-dropbox": "^3.0",
         "composer/installers": "~1.0"
     },

config/config.php

@@ -0,0 +1,30 @@
+<?php
+
+return [
+    /*
+     * The authentication mode for Dropbox.
+     * Can be 'refresh_token' (recommended for production) or 'temp_token' (for quick testing).
+     */
+    'auth_mode' => env('DROPBOX_AUTH_MODE', 'refresh_token'),
+
+    /*
+     * Your Dropbox App Key
+     */
+    'app_key' => env('DROPBOX_APP_KEY'),
+
+    /*
+     * Your Dropbox App Secret
+     */
+    'app_secret' => env('DROPBOX_APP_SECRET'),
+
+    /*
+     * The Dropbox refresh token obtained via the `dropbox:setup` command.
+     */
+    'refresh_token' => env('DROPBOX_REFRESH_TOKEN'),
+
+    /*
+     * A temporary Dropbox access token for testing purposes.
+     * Only used if 'auth_mode' is set to 'temp_token'.
+     */
+    'temp_token' => env('DROPBOX_TEMP_TOKEN'),
+];

console/DropboxSetupCommand.php

@@ -0,0 +1,76 @@
+<?php
+
+namespace NumenCode\DropboxAdapter\Console;
+
+use Winter\Storm\Console\Command;
+use Illuminate\Support\Facades\Http;
+
+class DropboxSetupCommand extends Command
+{
+    protected $signature = 'dropboxadapter:setup';
+
+    protected $description = 'Performs the initial setup to get a Dropbox refresh token.';
+
+    public function handle()
+    {
+        $this->info("--- Dropbox API Initial Setup ---\n");
+        $this->line("This command will guide you through getting your permanent refresh token.");
+
+        // --- Step 1: Get App Key and construct the authorization URL ---
+        $appKey = $this->ask('First, enter your Dropbox App Key');
+
+        if (!$appKey) {
+            $this->error('App Key is required. Aborting.');
+            return;
+        }
+
+        $authUrl = 'https://www.dropbox.com/oauth2/authorize?client_id=' . $appKey . '&response_type=code&token_access_type=offline';
+
+        $this->line("\nGreat. Now, open the following URL in your browser, authorize the app, and then copy the 'code' you receive after being redirected:");
+        $this->comment($authUrl); // Display the URL in a distinct color
+
+        // --- Step 2: Get the temporary code and the App Secret from the user ---
+        $authCode = $this->ask("\nPaste the 'authorization code' here");
+        $appSecret = $this->secret('Enter your Dropbox App Secret (input will be hidden)');
+
+        if (!$authCode || !$appSecret) {
+            $this->error('Authorization Code and App Secret are required. Aborting.');
+            return;
+        }
+
+        $this->line("\nAttempting to exchange the authorization code for a refresh token...");
+
+        // --- Step 3: Make the API call to Dropbox using Laravel's HTTP Client ---
+        $response = Http::asForm()->post('https://api.dropbox.com/oauth2/token', [
+            'grant_type'    => 'authorization_code',
+            'code'          => $authCode,
+            'client_id'     => $appKey,
+            'client_secret' => $appSecret,
+        ]);
+
+        // --- Step 4: Process the response ---
+        if ($response->failed()) {
+            $this->error("\n[API Error] Failed to get the refresh token.");
+            $this->line("Dropbox said: " . $response->body());
+            $this->line("\nPlease double-check your credentials and try again.");
+            return;
+        }
+
+        $refreshToken = $response->json('refresh_token');
+
+        $this->info("\n✔ Success! Your refresh token has been generated.");
+        $this->line("\nCopy the token below and add it to your .env file as DROPBOX_REFRESH_TOKEN:");
+
+        // Display the token in a prominent block
+        $this->line('+----------------------------------------------------------------+');
+        $this->line('| ');
+        $this->line('|   ' . $refreshToken);
+        $this->line('| ');
+        $this->line('+----------------------------------------------------------------+');
+
+        $this->line("\nAlso, make sure your .env file contains your App Key and Secret:\n");
+        $this->comment("DROPBOX_APP_KEY=" . $appKey);
+        $this->comment("DROPBOX_APP_SECRET=" . $appSecret);
+        $this->comment("DROPBOX_REFRESH_TOKEN=" . $refreshToken);
+    }
+}

providers/DropboxServiceProvider.php

@@ -1,6 +1,9 @@
 <?php namespace NumenCode\DropboxAdapter\Providers;
 
 use League\Flysystem\Filesystem;
+use Illuminate\Support\Facades\Http;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\Config;
 use Illuminate\Support\Facades\Storage;
 use Illuminate\Support\ServiceProvider;
 use Spatie\Dropbox\Client as DropboxClient;
@@ -12,8 +15,48 @@ class DropboxServiceProvider extends ServiceProvider
     public function boot()
     {
         Storage::extend('dropbox', function ($app, $config) {
+            // Read from plugin config, which reads from .env by default
+            $authMode = Config::get('numencode.dropboxadapter::auth_mode', 'refresh_token');
+
+            $accessToken = null;
+
+            if ($authMode === 'temp_token') {
+                $accessToken = Config::get('numencode.dropboxadapter::temp_token');
+
+                if (!$accessToken) {
+                    throw new \InvalidArgumentException('DROPBOX_TEMP_TOKEN is required when DROPBOX_AUTH_MODE is set to \'temp_token\'.');
+                }
+            } else {
+                if (!$accessToken = Cache::get('dropbox_access_token')) {
+                    $appKey = Config::get('numencode.dropboxadapter::app_key');
+                    $appSecret = Config::get('numencode.dropboxadapter::app_secret');
+                    $refreshToken = Config::get('numencode.dropboxadapter::refresh_token');
+
+                    if (empty($refreshToken) || empty($appKey) || empty($appSecret)) {
+                        throw new \InvalidArgumentException('Missing Dropbox configuration for refresh token flow (DROPBOX_REFRESH_TOKEN, DROPBOX_APP_KEY, or DROPBOX_APP_SECRET).');
+                    }
+
+                    $response = Http::asForm()->post('https://api.dropboxapi.com/oauth2/token', [
+                        'grant_type'    => 'refresh_token',
+                        'refresh_token' => $refreshToken,
+                        'client_id'     => $appKey,
+                        'client_secret' => $appSecret,
+                    ]);
+
+                    $response->throw();
+                    $data = $response->json();
+                    $accessToken = $data['access_token'];
+
+                    Cache::put('dropbox_access_token', $accessToken, 12600);
+                }
+            }
+
+            if (!$accessToken) {
+                throw new \RuntimeException('Failed to obtain a Dropbox access token.');
+            }
+
             $adapter = new DropboxAdapter(
-                new DropboxClient($config['authorization_token'])
+                new DropboxClient($accessToken)
             );
 
             return new FilesystemAdapter(