m365_active_storage 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 248f6e95435a9737f6aa06db40f6d758a59a4d6355ad4399a12d5dbc0d24efde
+  data.tar.gz: c93ea5f7c16c419e2cfadbc9ce6a679b1a0abb533bb9863b9a75f8b7aed7d17d
+SHA512:
+  metadata.gz: 91d7ddd980e2959d4c834847affd9b515f1544c307fa00d562bf6c15b3754fa3c1d657ed648c03eb285eb7cd3a98daf75dc23c5c888bc88d1914fc19cd249528
+  data.tar.gz: d8cedd464a2fb9946f778b79b3113e1176aa4d444d56b271bfda1378a386a3765c21850279325a78b3af1a3c5547b5f85a3fe42857652e9b002e3d814cace891

data/.ruby-version

@@ -0,0 +1 @@
+3.4.8

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-01-13
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,19 @@
+GNU GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+Copyright (c) 2026 Óscar León
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Full license text available at: https://www.gnu.org/licenses/gpl-3.0.txt

data/README.md

@@ -0,0 +1,82 @@
+# m365-active-storage
+
+Rails ActiveStorage in M365 Sharepoint
+
+## Install the gem
+
+```ruby
+gem install m365_active_storage
+```
+or add to the Gemfile:
+
+```ruby
+gem "m365_active_storage"
+```
+
+## Configure ActiveStorage
+
+### Configure Active Storage and auth
+#### Rails credentials
+```yaml
+sharepoint:
+  ms_graph_url:
+  ms_graph_version:
+  auth_host:
+  oauth_tenant:
+  oauth_app_id:
+  oauth_secret:
+  sharepoint_site_id:
+  sharepoint_drive_id:
+```
+#### -- or --
+
+#### ENV
+```shell
+MS_GRAPH_URL=
+MS_GRAPH_VERSION=
+AUTH_HOST=
+OAUTH_TENANT=
+OAUTH_APP_ID=
+OAUTH_SECRET=
+SHAREPOINT_SITE_ID=
+SHAREPOINT_DRIVE_ID=
+```
+
+### Set active storage to sharepoint service
+In the app config/environments/`<environment>`.rb
+
+```ruby
+  config.active_storage.service = :sharepoint
+```
+
+### Run the check generator
+```
+$ rails g m365_active_storage:check
+```
+
+## Move files from local to sharepoint with the migrate generator
+```shell
+g m365_active_storage:migrate
+```
+
+```shell
+5 blobs to migrate
+filename_1 done
+filename_2 done
+filename_3 done
+filename_4 failed: ActiveStorage::FileNotFoundError
+filename_5 done
+...
+```
+
+> [!NOTE]
+>
+> The local files are still in the storage folder.
+>
+> You must delete them manually after validating the data has been correctly moved.
+>
+
+> [!NOTE]
+>
+> Don't forget to restart your server, if running
+>

data/Rakefile

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+require "rdoc/task"
+
+Minitest::TestTask.create do |t|
+  t.framework = %(require "test/test_helper.rb")
+  t.test_globs = ["test/**/*_test.rb"]
+end
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+# RDoc task for generating API documentation
+RDoc::Task.new do |rdoc|
+  rdoc.title = "M365 Active Storage - SharePoint Storage for Rails"
+  rdoc.main = "README.md"
+  rdoc.rdoc_files.include("README.md", "CHANGELOG.md", "LICENSE.txt", "lib/**/*.rb")
+  rdoc.rdoc_files.exclude("test/**/*", "spec/**/*")
+  rdoc.options = [
+    "--markup=markdown",
+    "--line-numbers",
+    "--all",
+    "--hyperlink-all"
+  ]
+  rdoc.rdoc_dir = "doc"
+end
+
+task default: %i[test rubocop]
+

data/config/routes.rb

@@ -0,0 +1,5 @@
+Rails.application.routes.draw do
+  # Override default Active Storage blob route to use our authenticated controller
+  # This must come BEFORE the default activeStorage routes
+  get "/rails/active_storage/blobs/:signed_id/:filename", to: "m365_active_storage/blobs#show"
+end

data/config/storage.yml

@@ -0,0 +1,10 @@
+sharepoint:
+  service: Sharepoint
+  ms_graph_url: <%= Rails.application.credentials.dig(:sharepoint, :ms_graph_url) || ENV["MS_GRAPH_URL"] %>
+  ms_graph_version: <%= Rails.application.credentials.dig(:sharepoint, :ms_graph_version) || ENV["MS_GRAPH_VERSION"] %>
+  auth_host: <%= Rails.application.credentials.dig(:sharepoint, :auth_host) || ENV["AUTH_HOST"] %>
+  tenant_id: <%= Rails.application.credentials.dig(:sharepoint, :oauth_tenant) || ENV["OAUTH_TENANT"] %>
+  app_id: <%= Rails.application.credentials.dig(:sharepoint, :oauth_app_id) || ENV["OAUTH_APP_ID"] %>
+  secret: <%= Rails.application.credentials.dig(:sharepoint, :oauth_secret) || ENV["OAUTH_SECRET"] %>
+  site_id: <%= Rails.application.credentials.dig(:sharepoint, :sharepoint_site_id) || ENV["SHAREPOINT_SITE_ID"] %>
+  drive_id: <%= Rails.application.credentials.dig(:sharepoint, :sharepoint_drive_id) || ENV["SHAREPOINT_DRIVE_ID"] %>

data/lib/active_storage/authentication.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module M365ActiveStorage
+  # == OAuth2 Authentication Handler
+  #
+  # Manages OAuth2 authentication with Microsoft Azure AD to obtain and maintain
+  # access tokens for Microsoft Graph API calls.
+  #
+  # === Responsibilities
+  #
+  # * Obtain OAuth2 access tokens using client credentials flow
+  # * Cache tokens and automatically refresh when expired
+  # * Handle authentication errors and retries
+  # * Manage token lifecycle and expiration
+  #
+  # === Architecture
+  #
+  # The Authentication class implements the OAuth2 Client Credentials flow:
+  # 1. Exchanges client ID and secret for an access token
+  # 2. Caches the token with its expiration time
+  # 3. Automatically refreshes tokens before expiration
+  # 4. Provides token to HTTP requests for API calls
+  #
+  # === Example Usage
+  #
+  #   config = M365ActiveStorage::Configuration.new(**config_params)
+  #   auth = M365ActiveStorage::Authentication.new(config)
+  #   
+  #   # Ensure we have a valid token before making API calls
+  #   auth.ensure_valid_token
+  #   
+  #   # Token is now available for HTTP requests
+  #   token = auth.token
+  #
+  # @attr_reader [Configuration] config The SharePoint configuration
+  # @attr_reader [String] token The current OAuth2 access token
+  # @attr_reader [Time] token_expires_at The expiration time of the current token
+  #
+  # @see M365ActiveStorage::Configuration
+  # @see M365ActiveStorage::Http
+  class Authentication
+    attr_reader :config, :token, :token_expires_at
+
+    # Initialize the Authentication handler
+    #
+    # @param [Configuration] config The SharePoint configuration object containing
+    #                                authentication parameters (auth_host, tenant_id, app_id, secret)
+    def initialize(config)
+      @config = config
+      @token = nil
+      @token_expires_at = nil
+    end
+
+    # Ensure a valid, non-expired token is available
+    #
+    # Checks if the current token is nil or expired. If so, obtains a new token
+    # from the Azure AD authentication endpoint. This method is called automatically
+    # before making API requests.
+    #
+    # If a valid token already exists and hasn't expired, this method returns immediately.
+    #
+    # @return [void]
+    # @raise [StandardError] if token retrieval fails
+    # @example
+    #   auth.ensure_valid_token  # Obtains token if needed
+    #   puts auth.token  # Token is now available
+    #
+    # @see #token_expired?
+    def ensure_valid_token
+      return unless token.blank? || token_expired?
+
+      obtain_app_token
+    end
+
+    # Force immediate token expiration
+    #
+    # Manually expires the current token by setting the expiration time to the past.
+    # This is useful for testing or forcing a token refresh.
+    #
+    # @return [Time] The new expiration time (1 minute in the past)
+    # @example
+    #   auth.expire_token!
+    #   auth.ensure_valid_token  # Will fetch a new token
+    #
+    # @see #ensure_valid_token
+    def expire_token!
+      @token_expires_at = Time.current - 1.minute
+    end
+
+    private
+
+    # Build the authentication URL for Azure AD
+    #
+    # Constructs the OAuth2 token endpoint URL from the configured auth host and tenant ID.
+    #
+    # @return [String] The complete authentication URL
+    # @example
+    #   # Returns: "https://login.microsoftonline.com/tenant-id/oauth2/v2.0/token"
+    def auth_url
+      "#{config.auth_host}/#{config.tenant_id}/oauth2/v2.0/token"
+    end
+
+    # Parse the authentication URL into a URI object
+    #
+    # @return [URI] The parsed URI for the authentication endpoint
+    def auth_uri
+      URI(auth_url)
+    end
+
+    # Build the OAuth2 request body
+    #
+    # Constructs the form-encoded request body for the client credentials flow,
+    # including:
+    # * Grant type: "client_credentials"
+    # * Client ID from configuration
+    # * Client secret from configuration
+    # * Scope: Microsoft Graph API default scope
+    #
+    # @return [String] URL-encoded form data
+    # @example
+    #   # Returns: "grant_type=client_credentials&client_id=...&client_secret=...&scope=..."
+    def request_body
+      URI.encode_www_form(
+        grant_type: "client_credentials",
+        client_id: config.app_id,
+        client_secret: config.secret,
+        scope: "#{config.ms_graph_url}/.default"
+      )
+    end
+
+    # Obtain a new OAuth2 application token
+    #
+    # Makes an HTTP request to the Azure AD token endpoint using client credentials.
+    # Parses the response and updates the token and expiration time.
+    #
+    # @return [void]
+    # @raise [StandardError] if the token request fails (non-200 response)
+    # @example
+    #   # Automatically called by ensure_valid_token
+    #   auth.send(:obtain_app_token)
+    #
+    # @see #fetch_token_response
+    # @see #parse_token_response
+    def obtain_app_token
+      response = fetch_token_response
+      raise "Failed to obtain SharePoint token" unless response.code.to_i == 200
+
+      parse_token_response(response)
+    end
+
+    # Fetch the token response from Azure AD
+    #
+    # Makes an HTTPS POST request to the Azure AD OAuth2 token endpoint
+    # with client credentials.
+    #
+    # @return [Net::HTTPResponse] The response from the token endpoint
+    # @raise [StandardError] if the HTTP request fails
+    def fetch_token_response
+      http = Net::HTTP.new(auth_uri.host, auth_uri.port)
+      http.use_ssl = true
+      http.post(auth_uri.request_uri, request_body, { "Content-Type" => "application/x-www-form-urlencoded" })
+    end
+
+    # Parse and store the token response from Azure AD
+    #
+    # Extracts the access token and expiration time from the JSON response.
+    # Automatically subtracts 5 minutes from the expiration time as a safety margin
+    # to prevent using nearly-expired tokens.
+    #
+    # @param [Net::HTTPResponse] response The HTTP response from the token endpoint
+    # @return [void]
+    # @example
+    #   response = fetch_token_response
+    #   parse_token_response(response)  # Sets @token and @token_expires_at
+    def parse_token_response(response)
+      token_data = JSON.parse(response.body)
+      expires_in = token_data["expires_in"].to_i
+      @token = token_data["access_token"]
+      @token_expires_at = Time.current + expires_in.seconds - 5.minutes
+    end
+
+    # Check if the current token is expired
+    #
+    # @return [Boolean] true if the token is nil or the expiration time has passed
+    def token_expired?
+      token_expires_at.nil? || Time.current >= token_expires_at
+    end
+  end
+end

data/lib/active_storage/configuration.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module M365ActiveStorage
+  # == SharePoint Configuration Manager
+  #
+  # Manages and validates all configuration parameters needed to connect to Microsoft 365 SharePoint
+  # via the Microsoft Graph API.
+  #
+  # === Responsibilities
+  #
+  # * Load and parse configuration parameters
+  # * Validate that all required parameters are present
+  # * Provide convenient accessors for configuration values
+  # * Raise informative errors for missing or invalid configurations
+  #
+  # === Required Configuration Parameters
+  #
+  # * +ms_graph_url+ - The Microsoft Graph API base URL (typically https://graph.microsoft.com)
+  # * +ms_graph_version+ - The Graph API version (e.g., "v1.0", "beta")
+  # * +auth_host+ - The OAuth2 authentication endpoint (typically https://login.microsoftonline.com)
+  # * +tenant_id+ - Your Azure AD tenant ID (directory ID from Azure Portal)
+  # * +app_id+ - Your Azure AD application ID (client ID from your app registration)
+  # * +secret+ - Your Azure AD client secret
+  # * +site_id+ - The target SharePoint site ID
+  # * +drive_id+ - The target SharePoint drive ID within the site
+  #
+  # === Configuration Sources
+  #
+  # Configuration can be provided via:
+  # * Rails credentials (config/credentials.yml.enc)
+  # * Environment variables
+  # * Direct parameter passing
+  #
+  # Example in config/storage.yml:
+  #
+  #   sharepoint:
+  #     ms_graph_url: <%= Rails.application.credentials.sharepoint[:ms_graph_url] %>
+  #     ms_graph_version: <%= Rails.application.credentials.sharepoint[:ms_graph_version] %>
+  #     auth_host: <%= Rails.application.credentials.sharepoint[:auth_host] %>
+  #     tenant_id: <%= Rails.application.credentials.sharepoint[:oauth_tenant] %>
+  #     app_id: <%= Rails.application.credentials.sharepoint[:oauth_app_id] %>
+  #     secret: <%= Rails.application.credentials.sharepoint[:oauth_secret] %>
+  #     site_id: <%= Rails.application.credentials.sharepoint[:sharepoint_site_id] %>
+  #     drive_id: <%= Rails.application.credentials.sharepoint[:sharepoint_drive_id] %>
+  #
+  # === Example Usage
+  #
+  #   config = M365ActiveStorage::Configuration.new(
+  #     ms_graph_url: "https://graph.microsoft.com",
+  #     ms_graph_version: "v1.0",
+  #     auth_host: "https://login.microsoftonline.com",
+  #     tenant_id: "your-tenant-id",
+  #     app_id: "your-app-id",
+  #     secret: "your-client-secret",
+  #     site_id: "your-site-id",
+  #     drive_id: "your-drive-id"
+  #   )
+  #
+  #   puts config.ms_graph_endpoint  # => "https://graph.microsoft.com/v1.0"
+  #
+  # @attr_reader [String] ms_graph_url The Microsoft Graph API base URL
+  # @attr_reader [String] ms_graph_version The Graph API version
+  # @attr_reader [String] ms_graph_endpoint The complete Graph API endpoint (url + version)
+  # @attr_reader [String] auth_host The OAuth2 authentication host
+  # @attr_reader [String] tenant_id The Azure AD tenant ID
+  # @attr_reader [String] app_id The Azure AD application ID
+  # @attr_reader [String] secret The Azure AD client secret
+  # @attr_reader [String] site_id The SharePoint site ID
+  # @attr_reader [String] drive_id The SharePoint drive ID
+  class Configuration
+    attr_reader :ms_graph_url, :ms_graph_version, :ms_graph_endpoint,
+                :auth_host, :tenant_id,
+                :app_id, :secret, :site_id, :drive_id
+
+    # Initialize Configuration with the provided parameters
+    #
+    # All parameters are required. Missing parameters will raise a KeyError
+    # with a detailed message listing which parameters are missing.
+    #
+    # @param [Hash] options The configuration parameters
+    # @option options [String] :ms_graph_url The Microsoft Graph API base URL
+    # @option options [String] :ms_graph_version The Graph API version
+    # @option options [String] :auth_host The OAuth2 authentication host
+    # @option options [String] :tenant_id The Azure AD tenant ID
+    # @option options [String] :app_id The Azure AD application ID
+    # @option options [String] :secret The Azure AD client secret
+    # @option options [String] :site_id The SharePoint site ID
+    # @option options [String] :drive_id The SharePoint drive ID
+    #
+    # @raise [KeyError] if any required parameter is missing or empty
+    #
+    # @example
+    #   config = M365ActiveStorage::Configuration.new(
+    #     ms_graph_url: "https://graph.microsoft.com",
+    #     ms_graph_version: "v1.0",
+    #     # ... other required parameters
+    #   )
+    #
+    # @see #validate_configuration!
+    def initialize(**options)
+      fetch_configuration_params(options)
+      validate_configuration!
+    rescue KeyError => e
+      raise KeyError, "Configuration error: #{e.message}"
+    end
+
+    private
+
+    # Extract and store configuration parameters from the options hash
+    #
+    # Accepts keys in any case (string or symbol) and stores them as instance variables.
+    #
+    # @param [Hash] options The configuration options hash
+    # @return [void]
+    # @raise [KeyError] if any required parameter is missing
+    def fetch_configuration_params(options)
+      options = options.with_indifferent_access
+      @auth_host = options.fetch(:auth_host)
+      @tenant_id = options.fetch(:tenant_id)
+      @app_id = options.fetch(:app_id)
+      @secret = options.fetch(:secret)
+      @ms_graph_url = options.fetch(:ms_graph_url)
+      @ms_graph_version = options.fetch(:ms_graph_version)
+      @site_id = options.fetch(:site_id)
+      @drive_id = options.fetch(:drive_id)
+      @ms_graph_endpoint = "#{@ms_graph_url}/#{@ms_graph_version}"
+    end
+
+    # Validate that all required configuration parameters are present and non-empty
+    #
+    # Checks each configuration parameter and raises a detailed KeyError if any are missing
+    # or empty (nil or whitespace-only strings).
+    #
+    # @return [void]
+    # @raise [KeyError] with a detailed message listing all missing parameters
+    #
+    # @example
+    #   # If tenant_id, app_id, and secret are missing:
+    #   # Raises:
+    #   # KeyError: SharePoint service configuration is incomplete. Missing required parameters::
+    #   # - @tenant_id
+    #   # - @app_id
+    #   # - @secret
+    def validate_configuration!
+      missing_params = []
+      instance_variables.each do |var|
+        missing_params << var.to_s.gsub("@", "- ") unless instance_variable_get(var).present?
+      end
+      return unless missing_params.any?
+
+      missing_params.unshift("SharePoint service configuration is incomplete. Missing required parameters::")
+      raise KeyError, missing_params.join("\n")
+    end
+  end
+end