studio-engine 0.84.0 → 0.85.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 440b221a14bf9d80f6e58358f49d7b84f6495361e8d8a1a68e00b3980e02f024
-  data.tar.gz: 1efda067ddfb1277ceb5cfd6b399195689081c3d02b077489e75ff0c756aaf19
+  metadata.gz: 940823449254339d163e66fe93eabdab83cc36e25f4b80600ab02c6552e3d624
+  data.tar.gz: 1ce338c5ba90749bbd3a5217c5dba0bd3813b5be96996c15c734cdacdb1b0f0d
 SHA512:
-  metadata.gz: bde626a90189833853f31e49c8767d72fe48f82f99b06a3c7b3c282a790b55dc8479fcf066c12d7fe5324e7f84e6aa1c2f22536fa2af98908cb6c7cf237f30b2
-  data.tar.gz: 5e5034bebe474a62d7821e9e8cc3efd23f23a2daad1ac709a335bc88f52c8c816e37c121ae710ddc0643d5fad26a0912297dd47c6451835b7af23f0bd294fa14
+  metadata.gz: c322848f2708206583cff895faf563e34b85853494172dfd6f859568a771555a5f5b7859c0ac517a361679a282dbe5af1e5aa91b4bdce9a5e5df57c38a4cbf59
+  data.tar.gz: 70c41c33f57623eee5a8fe63aab6ff5c804a3570f055cca12bde70c8ae0919b20c3026de2100518e01ccab75c79f77afcc21674dede4c76ea7d6b1be4b6d5e0f

data/CHANGELOG.md

@@ -4,6 +4,51 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.85.0 — 2026-10-02
+
+### Changed
+
+- **`Studio::S3.delete` now moves the object to `trash/` instead of deleting
+  it.** The object is copied to `trash/<UTC date>/<epoch ms>/<key>` in the same
+  bucket, then deleted; a failed copy raises and never deletes. It returns the
+  trash key (nil when nothing was there) rather than the S3 response. The
+  bucket's lifecycle rule must expire `trash/` after three days, or trash never
+  expires: set it up before upgrading (README, *Trash and restore*). The
+  `/admin/emails` banner and logo replace and revert paths go through this
+  delete.
+- **`Studio::S3.list` leaves `trash/` keys out.** Pass `include_trash: true` to
+  keep them. The filter runs after `max_keys`, so a page can come back short.
+- **The engine's auth pages speak `Studio.sign_in_label`.** 0.80.0 put the label
+  on the navbar's signed-out buttons only, so an app that set `"Sign in"` still
+  showed "Log in to continue", a "Log In" button and a "Log in" link on its
+  `/login` and `/signup` pages. Those words, the magic-link button, the SSO
+  divider, the magic-link confirm page's button and the link-sent notice now
+  derive from the label (`lib/studio/auth_labels.rb`; README, *Navbar
+  identity*). An app that leaves the label at its default renders those pages
+  byte-identical to before. No routes change.
+
+### Added
+
+- **`Studio::S3.purge!(key:)`**, the hard delete, for objects with no value
+  after deletion.
+- **A production-bucket guard.** `Studio::S3.delete`, `purge!`, and the trash
+  service's `delete` and `delete_prefixed` raise
+  `Studio::S3::Trash::ProductionBucketRefused` before any request when the
+  bucket ends in `-production` and the process is not production (`QA_ENV`
+  first, then `Rails.env`).
+- **`ActiveStorage::Service::StudioTrashS3Service`** (`service: StudioTrashS3`
+  in `config/storage.yml`): Active Storage's S3 service whose `delete` trashes
+  the blob's object, recording the content type, byte size, checksum and
+  filename it can read off the object so a blob row can be rebuilt.
+  `delete_prefixed` (variants) stays a hard delete. Opt-in per app.
+- **`rake studio:trash:list[KEY]` and `studio:trash:restore[TRASH_KEY]`**: find
+  a key's trash copies, and copy one back to its original key (`FORCE=1` to
+  overwrite, `SERVICE=<name>` for an Active Storage bucket). A restore prints the
+  `ActiveStorage::Blob.create!` that re-creates the blob row.
+- **`Studio::S3::Trash`**, the shared copy-then-delete, key mapping, listing and
+  restore. A single CopyObject moves at most 5 GiB, so a larger object raises
+  `TooLarge` and is left in place.
+
 ## 0.84.0 — 2026-10-01
 
 ### Changed

data/README.md

@@ -629,7 +629,8 @@ Studio.configure do |config|
   config.navbar_user_name = :player_name                        # a method on the user
   # config.navbar_user_name = ->(user, view) { user.player_name } # or a callable
 
-  # The signed-out button in layouts/_navbar and components/_user_nav.
+  # The signed-out button in layouts/_navbar and components/_user_nav, and the
+  # sign-in wording on the engine's own auth pages (below).
   config.sign_in_label = "Sign in"                              # default "Log in"
 end
 ```
@@ -646,6 +647,24 @@ end
 - The engine has no I18n catalogue, so the label is plain config, not a locale
   key. A blank or non-String label, or a `navbar_user_name` of any other type,
   raises `Studio::NavbarIdentity::InvalidConfig` at assignment.
+- The label also sets the sign-in words on the engine's own auth pages, so the
+  navbar and `/login` never disagree. Rules: `lib/studio/auth_labels.rb`.
+
+  | Where | `"Log in"` (default) | `"Sign in"` |
+  |-------|----------------------|-------------|
+  | `/login` prompt | Log in to continue | Sign in to continue |
+  | `/login` password button | Log In | Sign In |
+  | `/login` magic-link button | Send sign-in link | Send sign-in link |
+  | `/login` SSO divider | or sign in below | or sign in below |
+  | `/signup` link back to `/login` | Log in | Sign in |
+  | Magic-link confirm page button | Sign in to *App* | Sign in to *App* |
+  | Link-sent notice | …emailed you a sign-in link. | …emailed you a sign-in link. |
+
+  The default reproduces the pages' earlier wording byte for byte, including the
+  four places that already said "sign in". Any other label derives every form:
+  `"Log on"` gives *Log On*, *Log on to continue*, *or log on below* and
+  *log-on link*. The "Sign in with Google" and "Sign up" buttons are not
+  sign-in labels and do not change.
 
 ### User nav slots
 
@@ -920,6 +939,9 @@ set as a pair. R2 serves nothing anonymously from its S3 endpoint, so with an
 endpoint and no `s3_public_url`, `Studio::S3.url` raises `NotConfigured` and
 `upload` writes but returns `nil`; serve private objects with `signed_url`.
 
+`Studio::S3.delete` moves the object to `trash/` for three days rather than
+deleting it; see [Trash and restore](#trash-and-restore).
+
 An app with **no** bucket configured does not error — `/admin/emails` renders
 read-only, showing the inherited defaults it is genuinely sending and naming the
 one setting that turns uploads on.
@@ -932,6 +954,137 @@ Add it to the app's admin sidebar section:
 { label: "Emails", href: admin_emails_path, emoji: "✉️", desc: "Transactional email banners" }
 ```
 
+## Trash and restore
+
+A delete through the engine is recoverable for three days. R2 has no object
+versioning, so instead of deleting, the engine **moves** the object under
+`trash/` in the same bucket, and a lifecycle rule on the bucket expires
+`trash/` after three days:
+
+```text
+avatars/abc.png  ->  trash/2026-10-01/1759302000123/avatars/abc.png
+                     trash/<UTC date>/<epoch ms>/<original key>
+```
+
+The copy goes first and the delete second. A copy that fails raises and the
+delete is never sent, so a failure leaves the original in place. The trash copy
+keeps the object's content type, cache headers and metadata, and adds
+`original-key`, `deleted-at`, `deleted-env`, and what an Active Storage blob row
+needs to be rebuilt (`blob-content-type`, `blob-byte-size`, `blob-checksum`
+from a single-part ETag, and `blob-filename` when the upload carried a
+Content-Disposition). A single CopyObject moves at most 5 GiB, so a larger
+object raises `Studio::S3::Trash::TooLarge` and stays where it is.
+
+`trash/` always sits at the bucket **root**, even for an app under a
+`s3_key_prefix` in a shared bucket, so one lifecycle rule and one Cloudflare
+rule cover every app in the bucket.
+
+### What deletes, and what purges
+
+| Call | Effect |
+|------|--------|
+| `Studio::S3.delete(key:)` | Moves to trash; returns the trash key (nil if nothing was there) |
+| `Studio::S3.purge!(key:)` | Hard delete, gone at once |
+| `Studio::S3.list` | Leaves `trash/` keys out; `include_trash: true` keeps them |
+| Active Storage `service: StudioTrashS3`, `delete` | Moves the blob's object to trash (`Blob#purge`, a replaced attachment) |
+| Active Storage `service: StudioTrashS3`, `delete_prefixed` | Hard delete: Active Storage calls it for `variants/<key>/`, which regenerate from the original |
+
+**The production guard.** All four destructive paths refuse a bucket whose name
+ends in `-production` when the process is not production, by `Studio::S3`'s own
+resolution (`QA_ENV` first, so a QA app running Rails as production is NOT
+production, then `Rails.env`). They raise
+`Studio::S3::Trash::ProductionBucketRefused` before sending any request. The
+guard reads the bucket NAME, so it protects only buckets that follow the
+`<app>-production` convention.
+
+### Set up the bucket (once per bucket, before an app adopts)
+
+Without the lifecycle rule, trash never expires. In the Cloudflare dashboard:
+R2 → the bucket → Settings → Object lifecycle rules → add a rule for prefix
+`trash/` that deletes objects 3 days after upload. A trash copy is a new object,
+so "uploaded" is the moment it was deleted. The same rule as S3 lifecycle JSON
+(R2's S3 API and AWS both take it). `aws s3api
+put-bucket-lifecycle-configuration` REPLACES the bucket's whole lifecycle
+configuration, R2's default abort-incomplete-multipart rule included, so read
+the current rules first (`get-bucket-lifecycle-configuration`) and send them
+together with this one, or use the dashboard:
+
+```json
+{
+  "Rules": [
+    {
+      "ID": "expire-trash-3d",
+      "Status": "Enabled",
+      "Filter": { "Prefix": "trash/" },
+      "Expiration": { "Days": 3 }
+    }
+  ]
+}
+```
+
+A public bucket also serves `trash/` from its custom domain unless it is
+blocked, which would keep a "deleted" profile picture reachable by URL for three
+days. Add a Cloudflare WAF custom rule on the zone, action **Block**:
+
+```text
+(http.host in {"assets.example.com"} and starts_with(http.request.uri.path, "/trash/"))
+```
+
+Name every `assets.<domain>` host the bucket answers on. If the bucket has the
+`r2.dev` public URL enabled, turn it off; a WAF rule cannot cover it.
+
+### Adopt it in an app
+
+Active Storage: change the R2 service in `config/storage.yml` from `service: S3`
+to `service: StudioTrashS3`. Every other key stays as it is:
+
+```yaml
+r2:
+  service: StudioTrashS3
+  bucket: my-app-production
+  endpoint: <%= ENV["R2_ENDPOINT"] %>
+  region: auto
+  access_key_id: <%= ENV["R2_ACCESS_KEY_ID"] %>
+  secret_access_key: <%= ENV["R2_SECRET_ACCESS_KEY"] %>
+```
+
+An app with its own S3 service subclass (turf-monster's
+`ActiveStorage::Service::R2PublicService`) inherits from the trash service
+instead:
+
+```ruby
+require "active_storage/service/studio_trash_s3_service"
+
+module ActiveStorage
+  class Service::R2PublicService < Service::StudioTrashS3Service
+    # ...
+  end
+end
+```
+
+`Studio::S3` callers need no change: `delete` trashes from this release on. Call
+`purge!` where an object truly has no value after deletion.
+
+### Find and restore a deleted object
+
+```bash
+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]"
+```
+
+Both read `Studio::S3`'s bucket. `SERVICE=<storage.yml service name>` reads an
+Active Storage service's bucket instead, e.g. `SERVICE=r2`. A restore copies the
+object back to its original key and leaves the trash copy for the lifecycle rule
+to expire. It refuses to overwrite an object already at the original key unless
+`FORCE=1`.
+
+Restoring an Active Storage object restores its **bytes only**. The blob row was
+destroyed before the object was trashed, so the task prints the
+`ActiveStorage::Blob.create!(...)` to run, filled from the trash copy's metadata,
+and the record must be re-attached by hand. `filename` is known only when the
+upload carried a Content-Disposition; supply it otherwise.
+
 ## Overriding Views
 
 This is a non-isolated engine -- app views at the same path automatically override engine views. For example, placing `app/views/sessions/new.html.erb` in the consuming app replaces the engine's login page.

data/app/controllers/magic_links_controller.rb

@@ -28,7 +28,7 @@ class MagicLinksController < ApplicationController
     end
     respond_to do |format|
       format.json { render json: { success: true } }
-      format.html { redirect_to login_path, notice: "Check your inbox — we just emailed you a sign-in link." }
+      format.html { redirect_to login_path, notice: "Check your inbox — we just emailed you a #{Studio::AuthLabels.link_noun(Studio.sign_in_label)}." }
     end
   end
 

data/app/controllers/registrations_controller.rb

@@ -18,7 +18,7 @@ class RegistrationsController < ApplicationController
         token = issue_magic_link(email, nil)
         Studio::Email.deliver(UserMailer, :magic_link, email, token, to: email)
       end
-      return redirect_to login_path, notice: "Check your inbox — we just emailed you a sign-in link."
+      return redirect_to login_path, notice: "Check your inbox — we just emailed you a #{Studio::AuthLabels.link_noun(Studio.sign_in_label)}."
     end
 
     @user = User.new(user_params)

data/app/views/registrations/new.html.erb

@@ -73,7 +73,7 @@
 
       <p class="text-center text-secondary text-sm mt-6">
         Already have an account?
-        <%= link_to "Log in", login_path, class: "text-primary hover:text-primary-300 font-medium underline underline-offset-2" %>
+        <%= link_to Studio::AuthLabels.link(Studio.sign_in_label), login_path, class: "text-primary hover:text-primary-300 font-medium underline underline-offset-2" %>
       </p>
     </div>
   </div>

data/app/views/sessions/_sso_continue.html.erb

@@ -11,7 +11,7 @@
 
     <div class="flex items-center gap-3 mt-5">
       <div class="flex-1 h-px border-t border-subtle"></div>
-      <span class="text-muted text-xs uppercase tracking-wider">or sign in below</span>
+      <span class="text-muted text-xs uppercase tracking-wider"><%= Studio::AuthLabels.or_below(Studio.sign_in_label) %></span>
       <div class="flex-1 h-px border-t border-subtle"></div>
     </div>
   </div>

data/app/views/sessions/new.html.erb

@@ -4,6 +4,9 @@
   words = Studio.app_name.split
   last_word = words.pop
   prefix = words.join(" ")
+  # The sign-in wording follows Studio.sign_in_label, as the navbar does
+  # (lib/studio/auth_labels.rb); the default label prints the wording these pages always had.
+  sign_in_label = Studio.sign_in_label
 %>
 
 <div class="min-h-[70vh] flex items-center justify-center">
@@ -13,7 +16,7 @@
         <img src="<%= logo_path %>" alt="<%= Studio.app_name %>" class="w-20 h-20 rounded-full shadow-lg mx-auto mb-4">
       <% end %>
       <h1 class="text-3xl font-extrabold text-heading tracking-tight"><%= prefix %> <span class="text-primary"><%= last_word %></span></h1>
-      <p class="text-secondary mt-2">Log in to continue</p>
+      <p class="text-secondary mt-2"><%= Studio::AuthLabels.prompt(sign_in_label) %></p>
     </div>
 
     <% if has_sso %>
@@ -57,7 +60,7 @@
           </div>
 
           <button type="submit" class="btn btn-primary btn-lg w-full">
-            Log In
+            <%= Studio::AuthLabels.button(sign_in_label) %>
           </button>
         <% end %>
       <% elsif Studio.auth_method?(:magic_link) %>
@@ -71,7 +74,7 @@
           </div>
 
           <button type="submit" class="btn btn-primary btn-lg w-full">
-            Send sign-in link
+            Send <%= Studio::AuthLabels.link_noun(sign_in_label) %>
           </button>
         <% end %>
       <% end %>

data/app/views/studio/_confirm_interstitial.html.erb

@@ -75,7 +75,7 @@
               method: :post,
               form: { id: "magic-consume-form", data: { turbo: "false" } },
               class: "magic-submit" do %>
-          Sign in to <%= Studio.app_name %>
+          <%= Studio::AuthLabels.to_app(Studio.sign_in_label, Studio.app_name) %>
         <% end %>
       </div>
     </main>

data/lib/active_storage/service/studio_trash_s3_service.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "active_storage/service/s3_service"
+require_relative "../../studio/s3"
+
+module ActiveStorage
+  # Active Storage's S3 service with a three-day grace period on delete. An app
+  # opts in from config/storage.yml by naming it instead of S3:
+  #
+  #   r2_production:
+  #     service: StudioTrashS3
+  #     bucket: turf-monster-production
+  #     endpoint: <%= ENV["R2_ENDPOINT"] %>
+  #     ...
+  #
+  # Active Storage resolves `service: StudioTrashS3` by requiring
+  # "active_storage/service/studio_trash_s3_service", which is why this file
+  # lives at lib/active_storage/service/ on the gem's load path. Nothing
+  # autoloads it; Zeitwerk never sees lib/.
+  #
+  # delete(key) — what Blob#purge and a replaced attachment end in — MOVES the
+  # object under trash/ (Studio::S3::Trash) instead of deleting it. By the time
+  # it runs the blob row is already destroyed, so what the trash copy records
+  # about the blob (content type, byte size, checksum, filename when the upload
+  # carried one) is read back off the object itself.
+  #
+  # delete_prefixed(prefix) stays a HARD delete. Active Storage calls it for
+  # "variants/<key>/": derived images, regenerated on demand from the original,
+  # which is the object that matters and the one trashed.
+  #
+  # Both refuse a "*-production" bucket from a non-production process.
+  class Service::StudioTrashS3Service < Service::S3Service
+    def delete(key)
+      instrument :delete, key: key do
+        Studio::S3.guard_production_bucket!(bucket.name)
+        Studio::S3::Trash.trash!(client: client.client, bucket: bucket.name, key: key,
+                                 env: Studio::S3.deletion_environment)
+      rescue StandardError => error
+        # Logged, then RE-RAISED. Blob#purge has already destroyed the row, so a
+        # raise here leaks the object rather than losing it: the failure that
+        # costs storage, never the one that costs a user's file.
+        log_trash_failure(key, error)
+        raise
+      end
+    end
+
+    def delete_prefixed(prefix)
+      Studio::S3.guard_production_bucket!(bucket.name)
+      super
+    end
+
+    private
+
+    def log_trash_failure(key, error)
+      message = "[StudioTrashS3] trash of #{bucket.name}/#{key} failed, object left in place: " \
+                "#{error.class}: #{error.message}"
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.error(message)
+      else
+        warn message
+      end
+    end
+  end
+end

data/lib/studio/auth_labels.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+# The words the engine's own auth pages say for "sign in", derived from the one
+# setting the navbar already reads, Studio.sign_in_label (default "Log in";
+# lib/studio/navbar_identity.rb). An app that says "Sign in" in its navbar gets
+# "Sign in" on /login, /signup and the magic-link pages too, never a mix.
+#
+# Every form is derived from the label as written:
+#
+#   label "Sign in"   link "Sign in"   button "Sign In"
+#                     prompt "Sign in to continue"
+#                     to_app "Sign in to Cyvasse"
+#                     or_below "or sign in below"
+#                     link_noun "sign-in link"
+#
+# THE DEFAULT IS PINNED, NOT DERIVED. With the default label the pages print
+# exactly what they printed before this setting reached them, and that text was
+# itself mixed: "Log in to continue" and "Log In" beside "Sign in to <App>",
+# "or sign in below" and "sign-in link". So the three forms that said "sign in"
+# under the default keep saying it while the label is the default, and follow the
+# label only once an app configures another one. An app that never configures
+# the label renders byte-identical pages (test/integration/auth_page_labels_render_test.rb).
+#
+# Pure Ruby, so the unit suite covers it without the dummy app.
+require_relative "navbar_identity"
+
+module Studio
+  module AuthLabels
+    DEFAULT = NavbarIdentity::DEFAULT_SIGN_IN_LABEL
+
+    module_function
+
+    def configured?(label)
+      label.to_s != DEFAULT
+    end
+
+    # The sign-up page's "Already have an account?" link.
+    def link(label)
+      label.to_s
+    end
+
+    # The login form's submit button, in title case: "Log In", "Sign In".
+    def button(label)
+      label.to_s.split(" ").map { |word| capitalize_first(word) }.join(" ")
+    end
+
+    # The login page's line under the app name.
+    def prompt(label)
+      "#{label} to continue"
+    end
+
+    # The magic-link confirm page's fallback button.
+    def to_app(label, app_name)
+      "#{configured?(label) ? label : 'Sign in'} to #{app_name}"
+    end
+
+    # The divider under the SSO "Continue as" button.
+    def or_below(label)
+      configured?(label) ? "or #{label.to_s.downcase} below" : "or sign in below"
+    end
+
+    # The emailed link's noun: the magic-link button and the "sent" notice.
+    def link_noun(label)
+      configured?(label) ? "#{label.to_s.downcase.tr(' ', '-')} link" : "sign-in link"
+    end
+
+    # Only the first letter changes, so an already-capital word is untouched.
+    def capitalize_first(word)
+      word.sub(/\A\p{Ll}/) { |c| c.upcase }
+    end
+  end
+end

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/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.84.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

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.84.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