studio-engine 0.83.0 → 0.85.0

data/lib/studio/s3/trash.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require "time"
+require "erb"
+require "uri"
+require_relative "../s3" unless defined?(Studio::S3::Error)
+
+module Studio
+  module S3
+    # THE GRACE PERIOD ON A DELETE. R2 has no object versioning, so a delete is
+    # forever the moment it lands: a replaced profile picture, a purged
+    # attachment, a banner swapped in /admin/emails. Trash turns that delete into
+    # a MOVE inside the same bucket:
+    #
+    #   avatars/abc.png  ->  trash/2026-10-01/1759302000123/avatars/abc.png
+    #
+    # and the bucket's lifecycle rule (set on the bucket, not here) expires
+    # everything under trash/ after three days. Until then the object can be put
+    # back with `rake studio:trash:restore[TRASH_KEY]`.
+    #
+    # THE ORDER IS THE SAFETY. Copy first, delete second, and a copy that fails
+    # RAISES before the delete is ever sent. A failure anywhere leaves the
+    # original where it was: a leaked object costs storage, a lost one costs a
+    # user's photo.
+    #
+    # Everything here works on REAL object keys (any Studio.s3_key_prefix
+    # already applied) and an explicit client + bucket, so Studio::S3 and the
+    # Active Storage service (ActiveStorage::Service::StudioTrashS3Service) share
+    # one implementation. trash/ always sits at the bucket ROOT, even for an app
+    # that lives under a key prefix in a shared bucket, so ONE lifecycle rule and
+    # ONE Cloudflare block cover every app in the bucket.
+    module Trash
+      PREFIX = "trash/"
+
+      # A single CopyObject copies at most 5 GiB (S3 and R2 alike). Larger
+      # objects need a multipart copy, which this does not do: it refuses
+      # instead, and leaves the object in place. Nothing in the fleet is near
+      # it (moms-app's audio is ~650 MB).
+      MAX_COPY_BYTES = 5 * 1024**3
+
+      # The metadata trash! writes. restore! strips exactly these back off, so a
+      # restored object carries the metadata it was uploaded with and no more.
+      TRASH_METADATA_KEYS = %w[
+        original-key deleted-at deleted-env
+        blob-content-type blob-byte-size blob-checksum blob-filename
+      ].freeze
+
+      # Header fields a REPLACE copy would otherwise drop.
+      CARRIED_HEADERS = %i[content_type cache_control content_disposition content_encoding content_language].freeze
+
+      class TooLarge < Studio::S3::Error; end
+      class ProductionBucketRefused < Studio::S3::Error; end
+      class NotTrash < Studio::S3::Error; end
+      class RestoreConflict < Studio::S3::Error; end
+
+      TRASH_KEY = %r{\Atrash/(\d{4}-\d{2}-\d{2})/(\d+)/(.+)\z}m
+
+      class << self
+        # Move bucket/key under trash/ and return the trash key. Returns nil,
+        # sending no copy and no delete, when the object is already gone: an
+        # S3 delete of a missing key succeeds, and so does this.
+        def trash!(client:, bucket:, key:, env:, now: Time.now.utc)
+          head = head(client, bucket, key)
+          return nil unless head
+
+          size = head.content_length.to_i
+          if size > MAX_COPY_BYTES
+            raise TooLarge, "#{bucket}/#{key} is #{size} bytes; a single CopyObject moves at most " \
+                            "#{MAX_COPY_BYTES} (5 GiB), so it was NOT trashed and NOT deleted. " \
+                            "Delete it with Studio::S3.purge! if you mean it, or copy it aside by hand first."
+          end
+
+          trash_key = key_for(key, now: now)
+          client.copy_object(
+            bucket: bucket,
+            copy_source: copy_source(bucket, key),
+            key: trash_key,
+            metadata_directive: "REPLACE",
+            metadata: trash_metadata(head, key: key, env: env, now: now),
+            **carried_headers(head)
+          )
+          # Reached only when the copy returned. A raise above never deletes.
+          client.delete_object(bucket: bucket, key: key)
+          trash_key
+        end
+
+        # trash/<UTC date>/<epoch ms>/<original key>. The date makes a day's
+        # deletes easy to browse; the milliseconds keep two deletes of the same
+        # key (a profile picture replaced twice in a day) from colliding.
+        def key_for(key, now: Time.now.utc)
+          now = now.utc
+          "#{PREFIX}#{now.strftime('%Y-%m-%d')}/#{(now.to_r * 1000).floor}/#{key}"
+        end
+
+        # The original key a trash key was moved from. It is read from the trash
+        # key's own path, not from metadata, so it answers even for an object
+        # whose metadata a hand copy dropped.
+        def original_key(trash_key)
+          match = TRASH_KEY.match(trash_key.to_s)
+          raise NotTrash, "#{trash_key.inspect} is not a trash key (trash/<date>/<ms>/<key>)" unless match
+
+          match[3]
+        end
+
+        def trash_key?(key)
+          key.to_s.start_with?(PREFIX)
+        end
+
+        # Every trash key whose original key is `key` (any key when nil),
+        # oldest first. Pages through the whole trash/ prefix: it is three
+        # days deep, so it stays small.
+        def list(client:, bucket:, key: nil)
+          keys = []
+          token = nil
+          loop do
+            params = { bucket: bucket, prefix: PREFIX }
+            params[:continuation_token] = token if token
+            resp = client.list_objects_v2(**params)
+            resp.contents.each do |object|
+              next unless TRASH_KEY.match?(object.key)
+              next if key && original_key(object.key) != key
+
+              keys << object
+            end
+            break unless resp.is_truncated
+
+            token = resp.next_continuation_token
+          end
+          keys.sort_by(&:key)
+        end
+
+        # Copy a trashed object back to its original key and return that key.
+        # The trash copy is left alone (the lifecycle rule expires it), so a
+        # restore can be repeated. Refuses to overwrite a live object unless
+        # overwrite: true, because the original key may already hold a newer
+        # upload. Restores the BYTES only: an Active Storage blob row is gone
+        # by the time its object is trashed; see blob_attributes.
+        def restore!(client:, bucket:, trash_key:, overwrite: false)
+          original = original_key(trash_key)
+          head = head(client, bucket, trash_key)
+          raise NotTrash, "#{bucket}/#{trash_key} does not exist (expired, or never trashed)" unless head
+          if !overwrite && head(client, bucket, original)
+            raise RestoreConflict, "#{bucket}/#{original} already exists; pass overwrite (FORCE=1) to replace it"
+          end
+
+          client.copy_object(
+            bucket: bucket,
+            copy_source: copy_source(bucket, trash_key),
+            key: original,
+            metadata_directive: "REPLACE",
+            metadata: (head.metadata || {}).reject { |name, _| TRASH_METADATA_KEYS.include?(name) },
+            **carried_headers(head)
+          )
+          original
+        end
+
+        # What an Active Storage blob row needs to be rebuilt around a restored
+        # key, as far as the trash copy can say. filename is nil unless the
+        # upload carried a Content-Disposition (Active Storage only sends one
+        # for attachment-disposition blobs); the caller supplies it otherwise.
+        def blob_attributes(client:, bucket:, trash_key:)
+          head = head(client, bucket, trash_key)
+          raise NotTrash, "#{bucket}/#{trash_key} does not exist" unless head
+
+          meta = head.metadata || {}
+          {
+            key: original_key(trash_key),
+            filename: decode(meta["blob-filename"]),
+            content_type: meta["blob-content-type"] || head.content_type,
+            byte_size: (meta["blob-byte-size"] || head.content_length).to_i,
+            checksum: meta["blob-checksum"]
+          }
+        end
+
+        # CopySource is "<bucket>/<url-encoded key>"; each path segment is
+        # escaped and the slashes kept, the form S3 and R2 both accept.
+        def copy_source(bucket, key)
+          require "aws-sdk-s3"
+          "#{bucket}/#{Seahorse::Util.uri_path_escape(key)}"
+        end
+
+        private
+
+        def head(client, bucket, key)
+          client.head_object(bucket: bucket, key: key)
+        rescue Aws::S3::Errors::NotFound, Aws::S3::Errors::NoSuchKey
+          nil
+        end
+
+        def carried_headers(head)
+          CARRIED_HEADERS.each_with_object({}) do |name, out|
+            value = head.public_send(name)
+            out[name] = value unless value.nil? || value.to_s.empty?
+          end
+        end
+
+        # The original object's own metadata first, then the trash record, so a
+        # stale "original-key" from an earlier round trip can never win.
+        def trash_metadata(head, key:, env:, now:)
+          meta = (head.metadata || {}).to_h.dup
+          meta["original-key"] = encode(key)
+          meta["deleted-at"] = now.utc.iso8601
+          meta["deleted-env"] = env.to_s
+          meta["blob-content-type"] = head.content_type.to_s unless head.content_type.to_s.empty?
+          meta["blob-byte-size"] = head.content_length.to_i.to_s
+          checksum = checksum_from_etag(head.etag)
+          meta["blob-checksum"] = checksum if checksum
+          filename = filename_from_disposition(head.content_disposition)
+          meta["blob-filename"] = encode(filename) if filename
+          meta
+        end
+
+        # A single-part upload's ETag is the hex MD5 of its bytes, and Active
+        # Storage's blob checksum is that MD5 in base64. A multipart ETag
+        # ("<hex>-<parts>") is not an MD5 of the object, so it yields nothing.
+        def checksum_from_etag(etag)
+          hex = etag.to_s.delete('"')
+          return nil unless hex.match?(/\A\h{32}\z/)
+
+          [[hex].pack("H*")].pack("m0")
+        end
+
+        def filename_from_disposition(disposition)
+          value = disposition.to_s
+          if (match = value.match(/filename\*=UTF-8''([^;]+)/i))
+            return URI.decode_uri_component(match[1])
+          end
+          match = value.match(/filename="([^"]*)"/i) || value.match(/filename=([^;]+)/i)
+          match && !match[1].strip.empty? ? match[1].strip : nil
+        end
+
+        # S3 metadata travels as HTTP headers, so a value must be ASCII. A key
+        # or filename that is not is stored percent-encoded behind "url:".
+        def encode(value)
+          value = value.to_s
+          value.ascii_only? ? value : "url:#{ERB::Util.url_encode(value)}"
+        end
+
+        def decode(value)
+          return nil if value.nil?
+          return URI.decode_uri_component(value.delete_prefix("url:")) if value.start_with?("url:")
+
+          value
+        end
+      end
+    end
+  end
+end

data/lib/studio/s3.rb

@@ -55,15 +55,66 @@ module Studio
         false
       end
 
+      # A RECOVERABLE delete: the object moves under trash/ in the same bucket
+      # (Studio::S3::Trash) and the bucket's lifecycle rule expires it after
+      # three days. Returns the trash key, or nil when there was nothing to
+      # move. Refused outright when a non-production process is pointed at a
+      # production bucket. purge! is the delete that cannot be undone.
       def delete(key:)
-        client.delete_object(bucket: bucket, key: full_key(key))
+        target = bucket
+        guard_production_bucket!(target)
+        Trash.trash!(client: client, bucket: target, key: full_key(key), env: deletion_environment)
+      end
+
+      # The HARD delete, gone at once with no trash copy. For objects with no
+      # value after deletion (regenerable derivatives, a trash copy itself).
+      # The same production-bucket guard as delete.
+      def purge!(key:)
+        target = bucket
+        guard_production_bucket!(target)
+        client.delete_object(bucket: target, key: full_key(key))
       end
 
       # Returns LOGICAL keys (the app's key namespace stripped back off), so a
       # caller can feed any result straight back into download/delete/url.
-      def list(prefix: nil, max: 1000)
+      # Trashed objects are deleted objects, so trash/ keys are left out unless
+      # include_trash: true. The filter runs after S3's max_keys, so a listing
+      # with trash in range can return fewer than max keys.
+      def list(prefix: nil, max: 1000, include_trash: false)
         resp = client.list_objects_v2(bucket: bucket, prefix: full_key(prefix), max_keys: max)
-        resp.contents.map { |object| logical_key(object.key) }
+        keys = resp.contents.map(&:key)
+        keys = keys.reject { |key| Trash.trash_key?(key) } unless include_trash
+        keys.map { |key| logical_key(key) }
+      end
+
+      # Whether this process is real production, by the SAME resolution that
+      # picks the bucket half (QA_ENV first, then Rails.env). Public because the
+      # Active Storage trash service guards on it too.
+      def production_environment?
+        environment == "production"
+      end
+
+      # A non-production process (a laptop, a QA app, CI) may never delete from
+      # a bucket named "*-production", whoever handed it the bucket name or the
+      # key. Studio::S3 derives its bucket from the same environment, so here it
+      # is a backstop; for an Active Storage service, whose bucket comes from
+      # storage.yml, it is the guard.
+      def guard_production_bucket!(bucket_name)
+        return unless bucket_name.to_s.end_with?("-production")
+        return if production_environment?
+
+        raise Trash::ProductionBucketRefused,
+              "refusing to delete from #{bucket_name}: this process resolves to a non-production " \
+              "environment (#{deletion_environment}); only production deletes production objects"
+      end
+
+      # The environment a trash copy records in its deleted-env metadata:
+      # "qa" for a QA app (which runs Rails as production), else Rails.env.
+      def deletion_environment
+        return "qa" if EnvironmentBanner.qa_environment?
+        return Rails.env.to_s if defined?(Rails) && Rails.respond_to?(:env) && Rails.env
+
+        "unknown"
       end
 
       def bucket
@@ -190,3 +241,5 @@ module Studio
     end
   end
 end
+
+require_relative "s3/trash"

data/lib/studio/site_footer.rb

@@ -94,6 +94,16 @@ module Studio
       nil
     end
 
+    # True on the app's OWN booking page (Studio.booking_path), which keeps the
+    # footer for a signed-in viewer as the engine's page does. Matched by the
+    # request's path, because the app's controller could be named anything.
+    def booking_page?(view, booking_path)
+      return false if booking_path.nil?
+      return false unless view.respond_to?(:request) && view.request.respond_to?(:path)
+
+      Studio::Booking.same_path?(view.request.path, booking_path)
+    end
+
     def validate!(declared)
       return if declared.nil? || declared.is_a?(Hash) || declared.respond_to?(:call)
 
@@ -106,7 +116,7 @@ module Studio
     #
     #   name:         the site name the engine resolved (the site identity's title)
     #   logo:         the logo the engine resolved (the navbar logo), or nil
-    #   booking_path: the booking page's path when the engine draws it, or nil
+    #   booking_path: the booking page's path (Studio.booking_path_for), or nil
     def resolve(declared, view, name: nil, logo: nil, booking_path: nil)
       raw = declared.respond_to?(:call) ? declared.call(view) : declared
       return nil if raw.nil?
@@ -149,8 +159,16 @@ module Studio
     #   config.site_footer_visible = ->(view) {
     #     Studio::SiteFooter.default_visible?(view) && !view.controller_path.start_with?("app/")
     #   }
-    def default_visible?(view, controllers: nil)
+    #
+    # `booking_path` is the app's own booking page (Studio.booking_path, resolved
+    # for this view); the engine's page is exempt by its controller instead.
+    def default_visible?(view, controllers: nil, booking_path: nil)
       controllers = Studio.site_footer_controllers if controllers.nil? && defined?(Studio.site_footer_controllers)
+      if booking_path.nil? && Studio.respond_to?(:booking_path) && Studio.booking_path
+        booking_path = Studio.booking_path_for(view)
+      end
+      return true if booking_page?(view, booking_path)
+
       visible?(
         logged_in: view.respond_to?(:logged_in?) && view.logged_in? ? true : false,
         controller_name: view.respond_to?(:controller_name) ? view.controller_name : nil,
@@ -235,12 +253,14 @@ module Studio
         unlinked: !text(url).nil? && safe_href(url, "social url").nil? }
     end
 
-    # [ heading, links ] or { heading:, links: }.
+    # [ heading, links ], [ heading, links, { width: 1.5 } ] or { heading:,
+    # links:, width: }. `width` is an optional hint: this column's share of the
+    # row against the others' 1 (see `tracks`).
     def column(row, booking_path)
-      heading, links =
+      heading, links, options =
         if row.respond_to?(:to_h) && !row.is_a?(Array)
           hash = symbolize(row)
-          [hash[:heading] || hash[:title], hash[:links]]
+          [hash[:heading] || hash[:title], hash[:links], hash]
         else
           Array(row)
         end
@@ -248,12 +268,48 @@ module Studio
       links = Array(links).filter_map { |link_row| link(link_row, booking_path) }
       return nil if heading.nil? && links.empty?
 
-      { heading: heading, links: links }
+      options = options.respond_to?(:to_h) && !options.is_a?(Array) ? symbolize(options) : {}
+      { heading: heading, links: links, width: column_width(options[:width]) }
+    end
+
+    # A column's width hint, or nil for the default share. Anything that is not a
+    # number between MIN_COLUMN_WIDTH and MAX_COLUMN_WIDTH is no hint.
+    MIN_COLUMN_WIDTH = 0.5
+    MAX_COLUMN_WIDTH = 4
+
+    def column_width(value)
+      return nil unless value.is_a?(Numeric) && value.respond_to?(:finite?) && value.finite?
+      return nil unless value >= MIN_COLUMN_WIDTH && value <= MAX_COLUMN_WIDTH
+
+      value.to_f
+    end
+
+    # True for a label that is an address rather than words: no space in it, and
+    # an "@", a "." or a "/". It is kept on one line (.ftr-link-solid).
+    def solid_label?(label)
+      string = label.to_s
+      !string.match?(/\s/) && string.match?(%r{[@./]})
+    end
+
+    # THE LINK COLUMNS' GRID TRACKS from 768px, one per column: its `width:`
+    # hint as an fr share, else FIRST_COLUMN_WIDTH for the first (the one that
+    # usually holds an email address) and 1 for the rest. nil when there are no
+    # columns, or more than MAX_ROW_COLUMNS: those wrap as equal tracks.
+    FIRST_COLUMN_WIDTH = 1.5
+    MAX_ROW_COLUMNS = 4
+
+    def tracks(columns)
+      columns = Array(columns)
+      return nil if columns.empty? || columns.size > MAX_ROW_COLUMNS
+
+      columns.each_with_index.map do |column, index|
+        "#{format('%g', column[:width] || (index.zero? ? FIRST_COLUMN_WIDTH : 1))}fr"
+      end.join(" ")
     end
 
     # [ label, href ], [ label, href, { booking: true } ] or { label:, href:,
     # booking: }. A nil href is a disabled label; an http(s) href opens in a new
-    # tab; `booking: true`, or an href equal to the engine's booking page, opens
+    # tab; `booking: true`, or an href equal to the booking page's path, opens
     # the booking popup (the href stays as the fallback).
     def link(row, booking_path = nil)
       label, href, options =

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.83.0"
+  VERSION = "0.85.0"
 end

data/lib/studio.rb

@@ -17,6 +17,7 @@ require "studio/site_footer"
 require "studio/booking"
 require "studio/navbar_links"
 require "studio/navbar_identity"
+require "studio/auth_labels"
 require "studio/profile_sections"
 require "studio/profile_image"
 require "studio/oauth_identity"
@@ -201,6 +202,7 @@ module Studio
   # The name the signed-in user nav prints, and the signed-out button's label.
   # Both defaults render the navbar byte-identical to before. The engine has no
   # I18n catalogue, so the label is plain config rather than a locale key.
+  # The label also words the engine's auth pages (lib/studio/auth_labels.rb).
   # Rules: lib/studio/navbar_identity.rb.
   #
   #   config.navbar_user_name = :player_name                          # a method on the user
@@ -565,7 +567,7 @@ module Studio
   # The public site's footer: brand and social profiles, link columns, an
   # optional Location band with a live map, and a legal line. And the booking
   # primitives: Google Calendar's appointment page inline, in a popup, and on a
-  # page. See docs/SITE_FOOTER.md.
+  # page. See docs/SITE_FOOTER.md and docs/BOOKING.md.
 
   # The footer's facts: a Hash, or a callable receiving the view. nil (the
   # default) means this app has no footer, and `studio_site_footer` renders
@@ -590,7 +592,8 @@ module Studio
   # controller name ("landing") or path ("admin/reports"). A visitor gets the
   # footer on every page; a signed-in viewer gets it only here, because every
   # other signed-in page is a working surface (a board, a queue, an editor) and
-  # stays full height. The engine's own booking page is always included.
+  # stays full height. The booking page (the engine's, or the app's own at
+  # Studio.booking_path) is always included.
   #
   #   config.site_footer_controllers = %w[landing packages contact_submissions]
   mattr_accessor :site_footer_controllers, default: []
@@ -634,6 +637,44 @@ module Studio
   #   config.draw_booking_routes = true
   mattr_accessor :draw_booking_routes, default: false
 
+  # WHERE THE APP'S OWN BOOKING PAGE LIVES, for an app that renders
+  # `studio_booking_frame` in a view of its own instead of drawing the engine's
+  # /schedule: a path ("/schedule"), or a callable receiving the view
+  # (`->(view) { view.schedule_path }`). nil (the default) leaves the engine's
+  # page, when drawn, as the booking page. With it set, the page is treated as
+  # the engine's own is: a footer link to it opens the popup, `studio_booking_link`
+  # falls back to it, and it keeps the footer for a signed-in viewer. It wins
+  # over the engine's page when both are declared. It is written into hrefs, so
+  # it must be a local path (one leading "/"); see Studio::Booking.local_path?.
+  #
+  #   config.booking_path = "/schedule"
+  mattr_reader :booking_path, default: nil
+
+  def self.booking_path=(declared)
+    @@booking_path = Booking.normalize_path(declared)
+  end
+
+  # The booking page's path for a view: Studio.booking_path, else the engine's
+  # /schedule when it is drawn, else nil.
+  def self.booking_path_for(view)
+    Booking.path_for(booking_path, view, drawn: draw_booking_routes)
+  end
+
+  # THE FRAME'S CROP AT REST: nil or false (the default) shows Google's whole
+  # page; a Hash of the schedule's measured box crops the frame to the slot
+  # picker until it is used. The numbers belong to ONE schedule, so there is no
+  # default crop: measure with `bin/booking-crop-measure <booking url>` and paste
+  # what it prints. Keys and derivation: lib/studio/booking.rb.
+  #
+  #   config.booking_crop = { top: 200, bottom: 600, frame_height: 720 }
+  mattr_reader :booking_crop, default: nil
+
+  def self.booking_crop=(declared)
+    Booking.validate_crop!(declared)
+    Booking.crop(declared) # reports a crop that cannot be one, at boot
+    @@booking_crop = declared || nil
+  end
+
   # THE APP'S IDENTITY COPY, resolved: { title:, description:, image_url: }.
   # The operator's saved value (Studio::SiteIdentity, edited at
   # /admin/link_preview) wins, then the drafted Studio.site_title /
@@ -1140,9 +1181,8 @@ module Studio
   def self.site_footer_for(view)
     return nil if site_footer.nil?
 
-    booking_path = draw_booking_routes && view.respond_to?(:studio_booking_path) ? view.studio_booking_path : nil
-    SiteFooter.resolve(site_footer, view,
-                       name: site_identity[:title], logo: logo_for("Footer Logo"), booking_path: booking_path)
+    SiteFooter.resolve(site_footer, view, name: site_identity[:title], logo: logo_for("Footer Logo"),
+                                          booking_path: booking_path_for(view))
   end
 
   # Navbar links resolved for a view context (lib/studio/navbar_links.rb).

data/lib/tasks/studio_trash.rake

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# Find and restore objects Studio::S3.delete or the StudioTrashS3 Active Storage
+# service moved under trash/. The bucket's lifecycle rule expires trash/ after
+# three days; after that there is nothing to restore.
+#
+#   bin/rails "studio:trash:list"                       # everything in trash
+#   bin/rails "studio:trash:list[avatars/abc.png]"      # one key's trash copies
+#   bin/rails "studio:trash:restore[trash/2026-10-01/1759302000123/avatars/abc.png]"
+#
+# The bucket is Studio::S3's. SERVICE=<storage.yml service name> reads an Active
+# Storage service's bucket instead (e.g. SERVICE=r2_production). FORCE=1 lets a
+# restore overwrite an object that already sits at the original key.
+#
+# Logic lives in Studio::S3::Trash (unit-tested); these tasks only resolve the
+# bucket and print.
+# Guarded like studio_email.rake and studio_ses.rake: an app that also loads
+# this file must not register a second copy of each action.
+unless Rake::Task.task_defined?("studio:trash:restore")
+  namespace :studio do
+    namespace :trash do
+      def studio_trash_target
+        name = ENV["SERVICE"].to_s.strip
+        if name.empty?
+          { client: Studio::S3.client, bucket: Studio::S3.bucket, key_prefix: Studio::S3.key_prefix }
+        else
+          service = ActiveStorage::Blob.services.fetch(name.to_sym)
+          { client: service.client.client, bucket: service.bucket.name, key_prefix: "" }
+        end
+      end
+
+      desc "List trashed objects, optionally only those deleted from KEY"
+      task :list, [:key] => :environment do |_task, args|
+        target = studio_trash_target
+        key = args[:key].to_s.strip
+        # A Studio::S3 caller thinks in LOGICAL keys; the trash records the real
+        # one. Match either, so the key you passed to delete finds its copy.
+        wanted = key.empty? ? nil : [key, "#{target[:key_prefix]}#{key}"].uniq
+        objects = Studio::S3::Trash.list(client: target[:client], bucket: target[:bucket])
+        objects = objects.select { |object| wanted.include?(Studio::S3::Trash.original_key(object.key)) } if wanted
+
+        puts "#{objects.size} trashed object(s) in #{target[:bucket]}#{" for #{key}" if wanted}"
+        objects.each do |object|
+          puts "#{object.key}  #{object.size} bytes  #{object.last_modified&.utc&.iso8601}"
+        end
+      end
+
+      desc "Copy TRASH_KEY back to its original key (FORCE=1 overwrites)"
+      task :restore, [:trash_key] => :environment do |_task, args|
+        trash_key = args[:trash_key].to_s.strip
+        abort "usage: studio:trash:restore[trash/<date>/<ms>/<key>]" if trash_key.empty?
+
+        target = studio_trash_target
+        overwrite = %w[1 true yes].include?(ENV["FORCE"].to_s.downcase)
+        begin
+          original = Studio::S3::Trash.restore!(client: target[:client], bucket: target[:bucket],
+                                                trash_key: trash_key, overwrite: overwrite)
+          attributes = Studio::S3::Trash.blob_attributes(client: target[:client], bucket: target[:bucket],
+                                                         trash_key: trash_key)
+        rescue Studio::S3::Error => error
+          abort "studio:trash:restore: #{error.message}"
+        end
+
+        puts "Restored #{target[:bucket]}/#{original}"
+        puts
+        puts "If this was an Active Storage object, its blob row is gone. Recreate it and re-attach:"
+        puts
+        puts "  blob = ActiveStorage::Blob.create!("
+        puts "    key: #{attributes[:key].inspect},"
+        puts "    filename: #{(attributes[:filename] || 'FILENAME').inspect},"
+        puts "    content_type: #{attributes[:content_type].inspect},"
+        puts "    byte_size: #{attributes[:byte_size]},"
+        puts "    checksum: #{attributes[:checksum].inspect},"
+        puts "    service_name: #{(ENV['SERVICE'].to_s.strip.empty? ? 'SERVICE_NAME' : ENV['SERVICE'].strip).inspect}"
+        puts "  )"
+        puts "  record.photo.attach(blob)   # the record and attachment it belonged to"
+        puts
+        puts "A nil checksum means a multipart upload, whose ETag is not an MD5. Compute it"
+        puts "from the restored bytes: Digest::MD5.base64digest(<downloaded bytes>)."
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.83.0
+  version: 0.85.0
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-01 00:00:00.000000000 Z
+date: 2026-10-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -584,9 +584,11 @@ files:
 - db/migrate/20260902000001_create_studio_knowledge_expectations.rb
 - db/migrate/20260902000002_add_expectation_to_studio_knowledge_docs.rb
 - db/migrate/20260930120000_create_studio_site_identities.rb
+- lib/active_storage/service/studio_trash_s3_service.rb
 - lib/generators/studio/site_identity/site_identity_generator.rb
 - lib/studio-engine.rb
 - lib/studio.rb
+- lib/studio/auth_labels.rb
 - lib/studio/booking.rb
 - lib/studio/cable.rb
 - lib/studio/color_scale.rb
@@ -617,6 +619,7 @@ files:
 - lib/studio/public_user.rb
 - lib/studio/redis.rb
 - lib/studio/s3.rb
+- lib/studio/s3/trash.rb
 - lib/studio/session_fingerprint.rb
 - lib/studio/session_state.rb
 - lib/studio/sidebar_sections.rb
@@ -627,6 +630,7 @@ files:
 - lib/studio/version.rb
 - lib/tasks/studio_email.rake
 - lib/tasks/studio_ses.rake
+- lib/tasks/studio_trash.rake
 - studio-engine.gemspec
 - tailwind/studio.tailwind.config.js
 homepage: https://github.com/McRitchie-Studio/studio-engine