active_storage_authorization 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 053ec2ae3fec299ec341ae8699d65fdfc141dd7fb6f802eefd1ef680d365ce92
+  data.tar.gz: 463bd945a98c7f8ee72e7da2305c7001b03e43308a272cec985bd99fc236e625
+SHA512:
+  metadata.gz: c1d11e3aac7c3dd8eb907d11769302dc51ccf965a9b0b0f7f180a340cd9d7ecb94e0cbc5df6cab059facf585f3c1e0ef76f226081263c2a302d99e1863d0a637
+  data.tar.gz: f8ce24cdb7cee24a9cfd4829ef0a84cbfc5c4da4f703c1ae4adc7b5163430cec7221ec99c9cb89fb6d6c4c89c29a2ad31cfe0dc6a782edfe46595b0251de6558

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-15
+
+- Default-deny serving for blobs and representations, with records opting in
+  through `active_storage_publicly_accessible?` and
+  `active_storage_accessible_to?(user, session:)`.
+- `Cache-Control: no-store` on private responses.
+- Files embedded in rich text inherit the access of the owning record.
+- Direct uploads: `:signed_in` (stamps the uploader, who alone can read the
+  blob until it is attached) or `:deny`, with a per-IP rate limit.
+- Optional refusal of requests that carry an `Authorization` header.

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2026 Yaroslav Shmarov
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,109 @@
+# active_storage_authorization
+
+Default-deny file serving for Active Storage.
+
+Out of the box, Rails serves any Active Storage file to anyone who has its URL, and URLs leak: browser history, shared links, emails, logs. This gem flips the default. A file is served only when a record it is attached to says so:
+
+```ruby
+class Invoice < ApplicationRecord
+  has_one_attached :pdf
+
+  def active_storage_accessible_to?(user, session:)
+    user.present? && organization.members.include?(user)
+  end
+end
+
+class User < ApplicationRecord
+  has_one_attached :avatar
+
+  def active_storage_publicly_accessible? = true
+end
+```
+
+A blob is served when **any** record it's attached to returns true from `active_storage_publicly_accessible?`, or from `active_storage_accessible_to?(current_user, session:)`. Otherwise the response is `403`.
+
+What else it does:
+
+- **Private responses are never cached.** They get `Cache-Control: no-store`, so neither the bytes (proxy mode) nor the signed storage URL (redirect mode) outlive the access check. Public files keep Rails' long-lived public caching.
+- **Rich text follows its owner.** A file embedded in Action Text or [Lexxy](https://github.com/basecamp/lexxy) is attached to an `ActionText::RichText` row; it takes the access of the model that owns that rich text.
+- **Direct uploads require a signed-in user**, are rate limited per IP, and record who uploaded each blob. Until the form is saved, a direct upload has no attachment, so only its uploader can read it (editors preview uploads immediately). Or turn direct uploads off entirely.
+- **Optionally refuses requests that carry an `Authorization` header**, so an API bearer token can never ride on a browser session cookie to reach a file.
+
+Works with Rails 7.2+ and both proxy and redirect serving.
+
+## Install
+
+```ruby
+# Gemfile
+gem "active_storage_authorization"
+```
+
+```ruby
+# config/initializers/active_storage_authorization.rb
+ActiveStorageAuthorization.configure do |config|
+  # Required. Runs inside the Active Storage controller (cookies, session and
+  # request are available) and returns the signed-in user or nil. Active Storage
+  # controllers don't inherit from your ApplicationController, so resolve the
+  # user here the way your authentication does.
+  config.current_user = -> { Current.user || Session.find_by(id: cookies.signed[:session_id])&.user }
+
+  # :signed_in (default) or :deny.
+  # config.direct_uploads = :deny
+
+  # Per-IP limit on minting direct uploads. nil turns it off. Read at boot.
+  # Uses the controller cache store, so it needs a real cache (not :null_store).
+  # config.direct_upload_rate_limit = { to: 60, within: 10.minutes }
+
+  # config.reject_authorization_header = true
+end
+```
+
+Then opt records in. Until a record defines one of the two methods, its files are refused, which is the point, but check your public assets (avatars, logos, banners, Open Graph images) before deploying.
+
+## The record API
+
+| Method | Called with | Return true to |
+|---|---|---|
+| `active_storage_publicly_accessible?` | nothing | serve to everyone, with public caching |
+| `active_storage_accessible_to?(user, session:)` | the result of `config.current_user` (may be nil), and the Rails session | serve to this viewer, uncached |
+
+Define either, both, or neither. `session:` exists for access that isn't tied to a user account, such as an anonymous reporter holding a case key in their session. Use `**` if you don't need it:
+
+```ruby
+def active_storage_accessible_to?(user, **) = user == author
+```
+
+## Settings
+
+| Setting | Default | |
+|---|---|---|
+| `current_user` | `-> {}` | Resolves the viewer. With the default, only public files are served. |
+| `direct_uploads` | `:signed_in` | `:deny` refuses every direct upload (forms that upload with the record still work). |
+| `direct_upload_rate_limit` | `{ to: 60, within: 10.minutes }` | `nil` turns it off. |
+| `reject_authorization_header` | `false` | `true` refuses any Active Storage request carrying an `Authorization` header. Leave it off if HTTP basic auth protects a staging site, or every file there becomes a 403. |
+
+## Adding your own guards
+
+`ActiveStorageAuthorization.serving_controllers` lists the four controllers that serve or redirect to blob bytes. Add checks of your own to the same list, for example to hold back files a virus scan hasn't cleared. They run after the access check:
+
+```ruby
+module VirusScanGuard
+  extend ActiveSupport::Concern
+
+  included { before_action -> { head :forbidden if @blob.metadata["scan"] == "pending" } }
+end
+
+Rails.application.config.to_prepare do
+  ActiveStorageAuthorization.serving_controllers.each { it.include(VirusScanGuard) }
+end
+```
+
+## What it does not cover
+
+- **Service URLs you generate yourself.** `blob.url` and `rails_storage_redirect` hand out a signed URL to the storage service; whoever holds that URL can fetch the file until it expires (`config.active_storage.service_urls_expire_in`, 5 minutes by default). The access check happens before the redirect, not after.
+- **Public services.** On a `public: true` service the redirect still checks access, but it points at a permanent, unsigned bucket URL that anyone can reuse.
+- **`ActiveStorage::DiskController`.** It serves signed, expiring keys that a check above already issued.
+
+## License
+
+MIT

data/SECURITY.md

@@ -0,0 +1,7 @@
+# Security policy
+
+Security fixes are released for the latest version.
+
+Please do not open a public issue for a vulnerability. Use
+[GitHub private vulnerability reporting](https://github.com/yshmarov/active_storage_authorization/security/advisories/new)
+with the affected version, a minimal reproduction, and the impact.

data/lib/active_storage_authorization/attachment.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module ActiveStorageAuthorization
+  module Attachment
+    def active_storage_publicly_accessible?
+      authorizing_record.try(:active_storage_publicly_accessible?)
+    end
+
+    def active_storage_accessible_to?(user, session:)
+      authorizing_record.try(:active_storage_accessible_to?, user, session: session)
+    end
+
+    private
+
+    # Files embedded in rich text are attached to the ActionText::RichText row,
+    # not to the model that owns it, so they take that model's access.
+    def authorizing_record
+      if defined?(ActionText::RichText) && record.is_a?(ActionText::RichText)
+        record.record
+      else
+        record
+      end
+    end
+  end
+end

data/lib/active_storage_authorization/authorization_header_guard.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ActiveStorageAuthorization
+  module AuthorizationHeaderGuard
+    extend ActiveSupport::Concern
+
+    included do
+      prepend_before_action :reject_authorization_header
+    end
+
+    private
+
+    def reject_authorization_header
+      return unless ActiveStorageAuthorization.reject_authorization_header && request.authorization.present?
+
+      no_store
+      head :forbidden
+    end
+  end
+end

data/lib/active_storage_authorization/blob.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ActiveStorageAuthorization
+  module Blob
+    def active_storage_publicly_accessible?
+      attachments.includes(:record).any?(&:active_storage_publicly_accessible?)
+    end
+
+    def active_storage_accessible_to?(user, session:)
+      attachments.includes(:record).any? do |attachment|
+        attachment.active_storage_accessible_to?(user, session: session)
+      end
+    end
+
+    def active_storage_uploaded_by?(user)
+      user.present? && attachments.none? && metadata[UPLOADER_METADATA_KEY].to_s == user.id.to_s
+    end
+  end
+end

data/lib/active_storage_authorization/current_user.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ActiveStorageAuthorization
+  module CurrentUser
+    private
+
+    def active_storage_user
+      return @active_storage_user if defined?(@active_storage_user)
+
+      @active_storage_user = instance_exec(&ActiveStorageAuthorization.current_user)
+    end
+  end
+end

data/lib/active_storage_authorization/direct_upload_guard.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module ActiveStorageAuthorization
+  module DirectUploadGuard
+    extend ActiveSupport::Concern
+    include CurrentUser
+
+    included do
+      if (limit = ActiveStorageAuthorization.direct_upload_rate_limit)
+        rate_limit to: limit.fetch(:to), within: limit.fetch(:within), only: :create,
+                   by: -> { request.remote_ip }, with: -> { head :too_many_requests }
+      end
+
+      before_action :authorize_direct_upload, only: :create
+      prepend UploaderStamp
+    end
+
+    private
+
+    def authorize_direct_upload
+      head :forbidden if ActiveStorageAuthorization.direct_uploads == :deny || active_storage_user.nil?
+    end
+
+    # Prepended so it wraps the controller's own blob_args, and merged last so
+    # a client can't claim someone else as the uploader.
+    module UploaderStamp
+      private
+
+      def blob_args
+        super.deep_merge(metadata: { UPLOADER_METADATA_KEY => active_storage_user.id })
+      end
+    end
+  end
+end

data/lib/active_storage_authorization/railtie.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module ActiveStorageAuthorization
+  class Railtie < Rails::Railtie
+    initializer 'active_storage_authorization.models' do
+      ActiveSupport.on_load(:active_storage_blob) { include ActiveStorageAuthorization::Blob }
+      ActiveSupport.on_load(:active_storage_attachment) { include ActiveStorageAuthorization::Attachment }
+    end
+
+    # Registered before the app's own to_prepare blocks, so these guards run
+    # ahead of any the app adds to the same controllers.
+    config.to_prepare { ActiveStorageAuthorization.install! }
+  end
+end

data/lib/active_storage_authorization/serving_guard.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ActiveStorageAuthorization
+  module ServingGuard
+    extend ActiveSupport::Concern
+    include CurrentUser
+
+    included do
+      before_action :authorize_active_storage_blob
+    end
+
+    private
+
+    def authorize_active_storage_blob
+      return if @blob.active_storage_publicly_accessible?
+
+      # Private bytes and the signed URL a redirect carries must not outlive
+      # this access check in a browser or shared cache.
+      no_store
+      return if @blob.active_storage_accessible_to?(active_storage_user, session: session)
+      # A direct upload has no attachment until its form is saved, but editors
+      # like Lexxy preview it right away, so its uploader may read it.
+      return if @blob.active_storage_uploaded_by?(active_storage_user)
+
+      head :forbidden
+    end
+
+    def http_cache_forever(public: false, &)
+      return yield if response.cache_control[:no_store]
+
+      super
+    end
+
+    def expires_in(...)
+      super unless response.cache_control[:no_store]
+    end
+  end
+end

data/lib/active_storage_authorization/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ActiveStorageAuthorization
+  VERSION = '0.1.0'
+end

data/lib/active_storage_authorization.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/core_ext/numeric/time'
+require 'active_storage_authorization/version'
+
+# Default-deny file serving for Active Storage. A blob is served only when a
+# record it is attached to opts in, and direct uploads require a signed-in
+# user (or are switched off). See README.md.
+module ActiveStorageAuthorization
+  DIRECT_UPLOAD_MODES = %i[signed_in deny].freeze
+  UPLOADER_METADATA_KEY = 'uploaded_by_user_id'
+
+  autoload :Blob, 'active_storage_authorization/blob'
+  autoload :Attachment, 'active_storage_authorization/attachment'
+  autoload :CurrentUser, 'active_storage_authorization/current_user'
+  autoload :ServingGuard, 'active_storage_authorization/serving_guard'
+  autoload :DirectUploadGuard, 'active_storage_authorization/direct_upload_guard'
+  autoload :AuthorizationHeaderGuard, 'active_storage_authorization/authorization_header_guard'
+
+  # Evaluated inside the Active Storage controller (so `cookies`, `request`
+  # and `session` are available); returns the signed-in user or nil.
+  mattr_accessor :current_user, default: -> {}
+
+  # :signed_in lets signed-in users mint direct uploads and stamps them as the
+  # uploader; :deny refuses every direct upload.
+  mattr_accessor :direct_uploads, default: :signed_in
+
+  # Per-IP limit on minting direct uploads; nil turns it off. Read once at
+  # boot, unlike the other settings.
+  mattr_accessor :direct_upload_rate_limit, default: { to: 60, within: 10.minutes }
+
+  # Refuse any Active Storage request that carries an Authorization header, so
+  # an API bearer token can never fall back to a browser session cookie. Off by
+  # default: browsers send HTTP basic auth on every request to a protected
+  # staging site, which would make every file a 403.
+  mattr_accessor :reject_authorization_header, default: false
+
+  def self.configure
+    yield self
+  end
+
+  # The controllers that serve blob bytes or redirect to them. Include extra
+  # guards (virus scan status, processing state) into these.
+  def self.serving_controllers
+    [
+      ActiveStorage::Blobs::RedirectController,
+      ActiveStorage::Blobs::ProxyController,
+      ActiveStorage::Representations::RedirectController,
+      ActiveStorage::Representations::ProxyController
+    ]
+  end
+
+  def self.install!
+    unless DIRECT_UPLOAD_MODES.include?(direct_uploads)
+      raise ArgumentError, "direct_uploads must be one of #{DIRECT_UPLOAD_MODES.inspect}, got #{direct_uploads.inspect}"
+    end
+
+    ActiveStorage::BaseController.include(AuthorizationHeaderGuard)
+    serving_controllers.each { |controller| controller.include(ServingGuard) }
+    ActiveStorage::DirectUploadsController.include(DirectUploadGuard)
+  end
+end
+
+require 'active_storage_authorization/railtie' if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification
+name: active_storage_authorization
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yaroslav Shmarov
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activestorage
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+description: |
+  Rails serves any Active Storage file to anyone holding its URL. This gem
+  flips that: a file is served only when a record it is attached to says the
+  current user may see it (or that it is public). Private responses are never
+  cached, direct uploads require a signed-in user and are rate limited, and
+  files embedded in rich text inherit their owning record's access.
+email:
+- yaroslav.shmarov@clickfunnels.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- SECURITY.md
+- lib/active_storage_authorization.rb
+- lib/active_storage_authorization/attachment.rb
+- lib/active_storage_authorization/authorization_header_guard.rb
+- lib/active_storage_authorization/blob.rb
+- lib/active_storage_authorization/current_user.rb
+- lib/active_storage_authorization/direct_upload_guard.rb
+- lib/active_storage_authorization/railtie.rb
+- lib/active_storage_authorization/serving_guard.rb
+- lib/active_storage_authorization/version.rb
+homepage: https://github.com/yshmarov/active_storage_authorization
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/yshmarov/active_storage_authorization
+  source_code_uri: https://github.com/yshmarov/active_storage_authorization
+  changelog_uri: https://github.com/yshmarov/active_storage_authorization/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/yshmarov/active_storage_authorization/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: 'Default-deny file serving for Active Storage: records opt in to who may
+  download their files.'
+test_files: []