atlas_rb 0.0.101 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 94b1cf416b2dbd60cd0e87960302dc5bb4be7207576608ecbe521cdb28d20255
-  data.tar.gz: d3d716929b9d246d761385142858e95e628f4e50510a3c583dd90ae8e70613c4
+  metadata.gz: 7f8b62042df9f4d715469ba7cf23dcf352485552aa9d73c55290312c3055800c
+  data.tar.gz: d435ed7a4fb953f2d82dd6f304232731802b2e8fe68a5e055fecd51e972c560a
 SHA512:
-  metadata.gz: 1c232e3e98c972d7c551106e5befb4b52f0b5befcba7ae15eeaf32ac1f2471062a90f4034a04e63caa3991625b6a5f4ca95de15cc395b0abaca8e62ad92ee5d3
-  data.tar.gz: 660c2326caa5f323fb83236144f6f41318e3b375d8e1d7a39ab48742c2acc86567686fef8cd2bf01136e91a8a300a53762c1ad9f2d3f449195a592a6dfa43178
+  metadata.gz: 3dffc895e6bee5bce6dbe907488a72a240c55b7d5ae5a506bff61d81a451a97490090d576c575fa07cf82ffbaf023109a9938aa66adf872e892b3a2fc37f3e13
+  data.tar.gz: 7076d8304048de5f20b8560875fbaddcac8ab29a4c3cf3d37ac54b95c3bac4cb6aff56bc503967ec3a5e41289bf4173055b9d8ced278ac9b63849231e0e09ea2

data/.version

@@ -1 +1 @@
-0.0.101
+1.0.0

data/CHANGELOG.md

@@ -0,0 +1,131 @@
+# Changelog
+
+## 1.0.0 — major restructure: namespace gradient + ambient identity
+
+This release reshapes the gem's API surface. Downstream consumers
+(Cerberus) need to update call sites — see the migration section
+below.
+
+### Added
+
+- **`AtlasRb.configure { |c| ... }`** — configurable defaults for
+  ambient identity:
+  - `config.default_nuid` — callable invoked when a resource method
+    is called without an explicit `nuid:` kwarg. Lets host apps
+    register `-> { Current.nuid }` once instead of threading
+    `nuid: Current.nuid` at every call site.
+  - `config.default_on_behalf_of` — callable for the
+    `On-Behalf-Of:` header, used by acting-as / view-as flows.
+- **`on_behalf_of:` kwarg** on every resource method that already
+  took `nuid:`. Sent as the `On-Behalf-Of: NUID <nuid>` header when
+  set. Falls through to `config.default_on_behalf_of` when omitted.
+- **`AtlasRb::Admin::*` namespace** — destructive lifecycle ops:
+  - `AtlasRb::Admin::Work.destroy` / `.restore`
+  - `AtlasRb::Admin::Collection.destroy` / `.restore`
+  - `AtlasRb::Admin::Community.destroy` / `.restore`
+
+  Every `destroy` requires `confirm: :i_understand`. Missing or
+  wrong value raises `ArgumentError` before any wire request.
+- **`AtlasRb::System::*` namespace** — system-context calls:
+  - `AtlasRb::System::User.find_or_create` (moved from
+    `AtlasRb::User.find_or_create`).
+  - `AtlasRb::System::NUID` constant — the seeded `:system` fixture's
+    NUID (`"000000000"`).
+- **`FaradayHelper#system_connection`** — Faraday factory that
+  authenticates with `Rails.application.credentials.atlas_system_token`
+  and the system NUID. Never consults the configured defaults. Used
+  exclusively by `AtlasRb::System::*`.
+
+### Removed (breaking)
+
+- `AtlasRb::Work.destroy`, `AtlasRb::Work.restore` → move to
+  `AtlasRb::Admin::Work`.
+- `AtlasRb::Collection.destroy`, `AtlasRb::Collection.restore` →
+  move to `AtlasRb::Admin::Collection`.
+- `AtlasRb::Community.destroy`, `AtlasRb::Community.restore` →
+  move to `AtlasRb::Admin::Community`.
+- `AtlasRb::User.find_or_create` → moves to
+  `AtlasRb::System::User.find_or_create`. The class
+  `AtlasRb::User` is gone.
+
+### Changed
+
+- `Work.tombstone`, `Collection.tombstone`, `Community.tombstone`
+  relax `nuid:` from required-kwarg to `nuid: nil`. The fall-through
+  resolution in `FaradayHelper#connection` handles the lookup. Atlas
+  still requires a real NUID on the wire for tombstone audit; if
+  neither the call site nor the configured default supplies one, the
+  request will hit Atlas without a `User:` header and Atlas will
+  reject it.
+
+### Migration
+
+For consumers (Cerberus piece 6):
+
+1. Register the ambient defaults in `config/initializers/atlas_rb.rb`:
+
+   ```ruby
+   AtlasRb.configure do |config|
+     config.default_nuid         = -> { Current.nuid }
+     config.default_on_behalf_of = -> { Current.on_behalf_of }
+   end
+   ```
+
+2. Drop `nuid: Current.nuid` from regular call sites:
+
+   ```ruby
+   # Before
+   AtlasRb::Work.find(id, nuid: Current.nuid)
+   AtlasRb::Blob.create(work_id, path, name, nuid: Current.nuid)
+
+   # After
+   AtlasRb::Work.find(id)
+   AtlasRb::Blob.create(work_id, path, name)
+   ```
+
+   Sites that need a *different* NUID than `Current.nuid` keep their
+   explicit kwarg — caller value always wins.
+
+3. Rewrite destructive call sites:
+
+   ```ruby
+   # Before
+   AtlasRb::Work.destroy(id, nuid: Current.nuid)
+   AtlasRb::Work.restore(id, nuid: Current.nuid)
+
+   # After
+   AtlasRb::Admin::Work.destroy(id, confirm: :i_understand)
+   AtlasRb::Admin::Work.restore(id)
+   ```
+
+4. Rewrite the SSO callback's user-provisioning call:
+
+   ```ruby
+   # Before
+   AtlasRb::User.find_or_create(nuid: ..., groups: ...)
+
+   # After
+   AtlasRb::System::User.find_or_create(nuid: ..., groups: ...)
+   ```
+
+5. Add the system token to encrypted credentials:
+
+   ```yaml
+   # config/credentials.yml.enc
+   atlas_system_token: <value Atlas's require_auth recognises as :system>
+   ```
+
+   This is paired on the Atlas side with
+   `Rails.application.credentials.system_token` (Atlas 0.6.20+).
+
+## 0.0.101
+
+- Threaded `nuid:` through the remaining gaps in `Work` / `Collection`
+  / `Community` / `FileSet` / `Delegate`.
+- Fixed `multipart({})` bug at `file_set.rb:83` — the literal `{}`
+  bound to the `nuid` positional arg, so the gem emitted
+  `User: NUID {}` on the wire for `FileSet.update`.
+
+## 0.0.100 and earlier
+
+See `git log` for pre-1.0 history.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    atlas_rb (0.0.101)
+    atlas_rb (1.0.0)
       faraday (~> 2.7)
       faraday-follow_redirects (~> 0.3.0)
       faraday-multipart (~> 1)

data/README.md

@@ -23,22 +23,77 @@ Then `bundle install`, or install standalone with `gem install atlas_rb`.
 
 ## Configuration
 
-Every request reads two environment variables:
+### Environment variables
+
+Every regular-path request reads two environment variables:
 
 | Variable      | Purpose                                                       |
 |---------------|---------------------------------------------------------------|
 | `ATLAS_URL`   | Base URL of the Atlas API (e.g. `https://atlas.example.edu`). |
-| `ATLAS_TOKEN` | Bearer token used in the `Authorization` header.             |
-
-User-scoped calls (currently only `AtlasRb::Authentication`) additionally
-accept an NUID — the Northeastern University ID — which is forwarded in a
-`User: NUID <nuid>` header.
+| `ATLAS_TOKEN` | Bearer token used in the `Authorization` header.              |
 
 ```ruby
 ENV["ATLAS_URL"]   = "https://atlas.example.edu"
 ENV["ATLAS_TOKEN"] = "..."
 ```
 
+### Ambient identity (`default_nuid` / `default_on_behalf_of`)
+
+Every resource method that talks to Atlas accepts a `nuid:` kwarg (the
+acting user) and an `on_behalf_of:` kwarg (the user the call is being
+made *for*, used by acting-as / view-as flows). Both are forwarded as
+`User: NUID <nuid>` and `On-Behalf-Of: NUID <nuid>` headers
+respectively.
+
+Rather than threading them at every call site, register callables
+once on app boot and let the gem read them as defaults:
+
+```ruby
+# config/initializers/atlas_rb.rb (Rails)
+AtlasRb.configure do |config|
+  config.default_nuid         = -> { Current.nuid }
+  config.default_on_behalf_of = -> { Current.on_behalf_of }
+end
+```
+
+The lambdas run **at request time** in whatever thread / fiber is
+making the call, so they pick up per-request `Current.*` values that
+`ApplicationController` set up via Devise + Rails 7's
+`ActiveSupport::CurrentAttributes`. Background jobs work the same way
+(ActiveJob ↔ CurrentAttributes integration restores the values on
+`perform`).
+
+Caller-passed kwargs always win over the configured defaults:
+
+```ruby
+# Uses Current.nuid:
+AtlasRb::Work.find("w-789")
+
+# Uses "X" — explicit kwarg overrides the default:
+AtlasRb::Work.find("w-789", nuid: "X")
+```
+
+If neither the call site nor the registered default supplies a value,
+no header is sent (legacy bearer-only path preserved).
+
+### System-path credentials
+
+Calls under `AtlasRb::System::*` (currently just SSO user provisioning)
+authenticate as the seeded Atlas `:system` fixture, not as a real user.
+They use a **separate** bearer token, looked up from
+`Rails.application.credentials.atlas_system_token`. Storing it in
+encrypted credentials rather than `ENV` halves the blast radius of a
+`.env` leak — the user token and the system token can't both leak
+through the same channel.
+
+```yaml
+# config/credentials.yml.enc (Cerberus side)
+atlas_system_token: <token-Atlas-side-recognises-as-:system>
+```
+
+The system NUID itself is hardcoded as `AtlasRb::System::NUID =
+"000000000"`, matching Atlas's seeded `:system` fixture row.
+
 ## Resource hierarchy
 
 ```
@@ -60,6 +115,37 @@ Community  →  Collection  →  Work
 | `AtlasRb::Resource`    | Generic resolver and permissions lookup.                                  |
 | `AtlasRb::Reset`       | Test-only — wipes Atlas state via `GET /reset`.                           |
 
+## Namespace gradient: regular / Admin / System
+
+Operations are split across three namespaces, calibrated to the blast
+radius and the kind of authentication they need:
+
+| Namespace            | What it does                                                                       | Auth                                                | Friction                              |
+|----------------------|------------------------------------------------------------------------------------|-----------------------------------------------------|---------------------------------------|
+| `AtlasRb::*`         | Regular CRUD (find / list / create / update / tombstone / metadata, etc.)          | User token (`ATLAS_TOKEN`) + acting user's NUID     | None — these are the daily-use paths. |
+| `AtlasRb::Admin::*`  | Hard delete (`destroy`) and un-tombstone (`restore`) for Work / Collection / Community. | Same as regular — a real operator is acting.        | `destroy` requires `confirm: :i_understand`. |
+| `AtlasRb::System::*` | System-context provisioning (currently just SSO user find-or-create).              | System token (`Rails.application.credentials.atlas_system_token`) + `User: NUID 000000000`. | The namespace itself is the marker — there is no way to call these as a non-system principal. |
+
+```ruby
+# Regular daily use — picks up Current.nuid via the configured default:
+AtlasRb::Work.find("w-789")
+AtlasRb::Work.tombstone("w-789")     # withdrawal (reversible)
+
+# Operator-only, with a friction marker:
+AtlasRb::Admin::Work.destroy("w-789", confirm: :i_understand)
+AtlasRb::Admin::Work.restore("w-789")
+
+# System-only — authenticates as Atlas's :system fixture:
+AtlasRb::System::User.find_or_create(
+  nuid: "001234567",
+  groups: ["northeastern:staff", "drs:editors"]
+)
+```
+
+The `AtlasRb::System::*` path never consults `AtlasRb.config.default_nuid`
+or `default_on_behalf_of` — there is no ambient user context on system
+calls.
+
 ### A note on `create` argument shapes
 
 The CRUD-twin classes look the same but pass different parent IDs:

data/lib/atlas_rb/admin/collection.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module AtlasRb
+  module Admin
+    # Destructive lifecycle operations on a {AtlasRb::Collection}.
+    #
+    # See {AtlasRb::Admin} for the rationale behind the namespace and the
+    # `confirm: :i_understand` friction marker.
+    class Collection
+      extend AtlasRb::FaradayHelper
+
+      # Atlas REST endpoint prefix.
+      # @api private
+      ROUTE = "/collections/"
+
+      # Hard-delete a Collection.
+      #
+      # Unrecoverable — prefer {AtlasRb::Collection.tombstone} for
+      # user-visible withdrawal. Operator-only.
+      #
+      # @param id [String] the Collection ID.
+      # @param confirm [Symbol] must be `:i_understand`. Any other value
+      #   raises `ArgumentError`.
+      # @param nuid [String, nil] optional acting user's NUID.
+      # @param on_behalf_of [String, nil] optional `On-Behalf-Of` NUID.
+      # @return [Faraday::Response] the raw delete response.
+      # @raise [ArgumentError] if `confirm:` is missing or not the
+      #   sentinel value.
+      #
+      # @example
+      #   AtlasRb::Admin::Collection.destroy("col-456", confirm: :i_understand)
+      def self.destroy(id, confirm:, nuid: nil, on_behalf_of: nil)
+        unless confirm == :i_understand
+          raise ArgumentError,
+                "AtlasRb::Admin::Collection.destroy requires confirm: :i_understand"
+        end
+        connection({}, nuid, on_behalf_of: on_behalf_of).delete(ROUTE + id)
+      end
+
+      # Restore a previously-tombstoned Collection.
+      #
+      # @param id [String] the Collection ID.
+      # @param nuid [String, nil] optional acting user's NUID.
+      # @param on_behalf_of [String, nil] optional `On-Behalf-Of` NUID.
+      # @return [Faraday::Response] the raw response.
+      #
+      # @example
+      #   AtlasRb::Admin::Collection.restore("col-456")
+      def self.restore(id, nuid: nil, on_behalf_of: nil)
+        connection({}, nuid, on_behalf_of: on_behalf_of).post(ROUTE + id + '/restore')
+      end
+    end
+  end
+end

data/lib/atlas_rb/admin/community.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module AtlasRb
+  module Admin
+    # Destructive lifecycle operations on a {AtlasRb::Community}.
+    #
+    # See {AtlasRb::Admin} for the rationale behind the namespace and the
+    # `confirm: :i_understand` friction marker.
+    class Community
+      extend AtlasRb::FaradayHelper
+
+      # Atlas REST endpoint prefix.
+      # @api private
+      ROUTE = "/communities/"
+
+      # Hard-delete a Community.
+      #
+      # Unrecoverable — prefer {AtlasRb::Community.tombstone} for
+      # user-visible withdrawal. Operator-only.
+      #
+      # @param id [String] the Community ID.
+      # @param confirm [Symbol] must be `:i_understand`. Any other value
+      #   raises `ArgumentError`.
+      # @param nuid [String, nil] optional acting user's NUID.
+      # @param on_behalf_of [String, nil] optional `On-Behalf-Of` NUID.
+      # @return [Faraday::Response] the raw delete response.
+      # @raise [ArgumentError] if `confirm:` is missing or not the
+      #   sentinel value.
+      #
+      # @example
+      #   AtlasRb::Admin::Community.destroy("c-123", confirm: :i_understand)
+      def self.destroy(id, confirm:, nuid: nil, on_behalf_of: nil)
+        unless confirm == :i_understand
+          raise ArgumentError,
+                "AtlasRb::Admin::Community.destroy requires confirm: :i_understand"
+        end
+        connection({}, nuid, on_behalf_of: on_behalf_of).delete(ROUTE + id)
+      end
+
+      # Restore a previously-tombstoned Community.
+      #
+      # @param id [String] the Community ID.
+      # @param nuid [String, nil] optional acting user's NUID.
+      # @param on_behalf_of [String, nil] optional `On-Behalf-Of` NUID.
+      # @return [Faraday::Response] the raw response.
+      #
+      # @example
+      #   AtlasRb::Admin::Community.restore("c-123")
+      def self.restore(id, nuid: nil, on_behalf_of: nil)
+        connection({}, nuid, on_behalf_of: on_behalf_of).post(ROUTE + id + '/restore')
+      end
+    end
+  end
+end

data/lib/atlas_rb/admin/work.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module AtlasRb
+  module Admin
+    # Destructive lifecycle operations on a {AtlasRb::Work}.
+    #
+    # See {AtlasRb::Admin} for the rationale behind the namespace and the
+    # `confirm: :i_understand` friction marker.
+    class Work
+      extend AtlasRb::FaradayHelper
+
+      # Atlas REST endpoint prefix.
+      # @api private
+      ROUTE = "/works/"
+
+      # Hard-delete a Work.
+      #
+      # Removes the Work, its FileSets, and their Blobs from Atlas
+      # storage. Unrecoverable — prefer {AtlasRb::Work.tombstone} for
+      # the user-visible withdrawal path. This is operator-only.
+      #
+      # @param id [String] the Work ID.
+      # @param confirm [Symbol] must be `:i_understand`. Any other value
+      #   (including the kwarg being omitted) raises `ArgumentError`.
+      # @param nuid [String, nil] optional acting user's NUID. Falls
+      #   through to {AtlasRb.config}.default_nuid when omitted.
+      # @param on_behalf_of [String, nil] optional NUID for the
+      #   `On-Behalf-Of` header. Falls through to
+      #   {AtlasRb.config}.default_on_behalf_of when omitted.
+      # @return [Faraday::Response] the raw delete response.
+      # @raise [ArgumentError] if `confirm:` is missing or not the
+      #   sentinel value.
+      #
+      # @example
+      #   AtlasRb::Admin::Work.destroy("w-789", confirm: :i_understand)
+      def self.destroy(id, confirm:, nuid: nil, on_behalf_of: nil)
+        unless confirm == :i_understand
+          raise ArgumentError,
+                "AtlasRb::Admin::Work.destroy requires confirm: :i_understand"
+        end
+        connection({}, nuid, on_behalf_of: on_behalf_of).delete(ROUTE + id)
+      end
+
+      # Restore a previously-tombstoned Work.
+      #
+      # Reverses a withdrawal: search and show pages stop returning a
+      # withdrawn stub. Operator-only; typically driven from a Rails
+      # console or a future admin panel after the library has decided a
+      # withdrawn Work should come back.
+      #
+      # @param id [String] the Work ID.
+      # @param nuid [String, nil] optional acting user's NUID. Falls
+      #   through to {AtlasRb.config}.default_nuid when omitted.
+      # @param on_behalf_of [String, nil] optional NUID for the
+      #   `On-Behalf-Of` header. Falls through to
+      #   {AtlasRb.config}.default_on_behalf_of when omitted.
+      # @return [Faraday::Response] the raw response.
+      #
+      # @example
+      #   AtlasRb::Admin::Work.restore("w-789")
+      def self.restore(id, nuid: nil, on_behalf_of: nil)
+        connection({}, nuid, on_behalf_of: on_behalf_of).post(ROUTE + id + '/restore')
+      end
+    end
+  end
+end

data/lib/atlas_rb/admin.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module AtlasRb
+  # Operator-only destructive lifecycle operations.
+  #
+  # Houses methods whose blast radius warrants more friction than the
+  # regular CRUD surface: `destroy` (hard delete — content and metadata
+  # are unrecoverable) and `restore` (un-tombstone — reverses a withdraw,
+  # typically driven from a Rails console session or a future admin UI).
+  #
+  # ## Why a separate namespace
+  #
+  # The class itself is the marker: `AtlasRb::Admin::Work.destroy(...)`
+  # is structurally distinct from `AtlasRb::Work.update(...)`. Mass-edits
+  # and code-search across a consumer codebase can quickly find every
+  # destructive call site by grepping `AtlasRb::Admin::`.
+  #
+  # ## `confirm: :i_understand`
+  #
+  # Every `destroy` method requires a `confirm: :i_understand` kwarg.
+  # Forgetting (or misspelling) it raises `ArgumentError` before any
+  # request goes out. The value is arbitrary — the point is that
+  # boilerplate-generated or copy-pasted call sites can't accidentally
+  # delete production data. `restore` does **not** require the marker;
+  # restoring tombstoned content is reversible (by tombstoning again)
+  # so the same friction isn't warranted.
+  module Admin
+  end
+end

data/lib/atlas_rb/blob.rb

@@ -20,14 +20,19 @@ module AtlasRb
     # @param nuid [String, nil] optional acting user's NUID, forwarded as the
     #   `User:` header. Required for cerberus-token requests; legacy bearer
     #   tokens still resolve without it.
+    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
+    #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
+    #   omitted.
     # @return [Hash] the `"blob"` object, already unwrapped — typically
     #   includes `"id"`, `"original_filename"`, `"size"`, and a download URL.
     #
     # @example
     #   AtlasRb::Blob.find("b-321")
     #   # => { "id" => "b-321", "original_filename" => "scan.pdf", ... }
-    def self.find(id, nuid: nil)
-      AtlasRb::Mash.new(JSON.parse(connection({}, nuid).get(ROUTE + id)&.body))['blob']
+    def self.find(id, nuid: nil, on_behalf_of: nil)
+      AtlasRb::Mash.new(JSON.parse(
+        connection({}, nuid, on_behalf_of: on_behalf_of).get(ROUTE + id)&.body
+      ))['blob']
     end
 
     # Stream the Blob's binary content through a caller-supplied block.
@@ -41,6 +46,9 @@ module AtlasRb
     # @param nuid [String, nil] optional acting user's NUID, forwarded as the
     #   `User:` header. Required for cerberus-token requests; legacy bearer
     #   tokens still resolve without it.
+    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
+    #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
+    #   omitted.
     # @yieldparam chunk [String] the next chunk of binary data.
     # @return [Hash] the response headers from `GET /files/<id>/content`.
     #
@@ -49,9 +57,9 @@ module AtlasRb
     #     headers = AtlasRb::Blob.content("b-321") { |chunk| f.write(chunk) }
     #     puts headers["content-type"]
     #   end
-    def self.content(id, nuid: nil, &chunk_handler)
+    def self.content(id, nuid: nil, on_behalf_of: nil, &chunk_handler)
       headers = {}
-      connection({}, nuid).get("#{ROUTE}#{id}/content") do |req|
+      connection({}, nuid, on_behalf_of: on_behalf_of).get("#{ROUTE}#{id}/content") do |req|
         req.options.on_data = proc do |chunk, _bytes_received, env|
           headers = env.response_headers if headers.empty? && env
           chunk_handler.call(chunk)
@@ -77,6 +85,9 @@ module AtlasRb
     # @param nuid [String, nil] optional acting user's NUID, forwarded as the
     #   `User:` header. Required for cerberus-token requests; legacy bearer
     #   tokens still resolve without it.
+    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
+    #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
+    #   omitted.
     # @return [Hash] the created `"blob"` payload, including its `"id"`.
     #
     # @example
@@ -87,7 +98,7 @@ module AtlasRb
     #   key = SecureRandom.uuid
     #   AtlasRb::Blob.create("w-789", "/tmp/upload.tmp", "thesis.pdf",
     #                        idempotency_key: key)
-    def self.create(id, blob_path, original_filename, idempotency_key: nil, nuid: nil)
+    def self.create(id, blob_path, original_filename, idempotency_key: nil, nuid: nil, on_behalf_of: nil)
       payload = { work_id: id,
                   original_filename: original_filename,
                   binary: Faraday::Multipart::FilePart.new(File.open(blob_path),
@@ -95,7 +106,8 @@ module AtlasRb
                                                           File.basename(blob_path)) }
 
       AtlasRb::Mash.new(JSON.parse(
-        multipart(nuid, idempotency_key: idempotency_key).post(ROUTE, payload)&.body
+        multipart(nuid, on_behalf_of: on_behalf_of, idempotency_key: idempotency_key)
+          .post(ROUTE, payload)&.body
       ))['blob']
     end
 
@@ -105,12 +117,15 @@ module AtlasRb
     # @param nuid [String, nil] optional acting user's NUID, forwarded as the
     #   `User:` header. Required for cerberus-token requests; legacy bearer
     #   tokens still resolve without it.
+    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
+    #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
+    #   omitted.
     # @return [Faraday::Response] the raw delete response.
     #
     # @example
     #   AtlasRb::Blob.destroy("b-321")
-    def self.destroy(id, nuid: nil)
-      connection({}, nuid).delete(ROUTE + id)
+    def self.destroy(id, nuid: nil, on_behalf_of: nil)
+      connection({}, nuid, on_behalf_of: on_behalf_of).delete(ROUTE + id)
     end
 
     # Replace the bytes of an existing Blob in-place.
@@ -124,15 +139,20 @@ module AtlasRb
     # @param nuid [String, nil] optional acting user's NUID, forwarded as the
     #   `User:` header. Required for cerberus-token requests; legacy bearer
     #   tokens still resolve without it.
+    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
+    #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
+    #   omitted.
     # @return [Hash] the parsed JSON response from the patch.
     #
     # @example
     #   AtlasRb::Blob.update("b-321", "/tmp/revised.pdf")
-    def self.update(id, blob_path, nuid: nil)
+    def self.update(id, blob_path, nuid: nil, on_behalf_of: nil)
       payload = { binary: Faraday::Multipart::FilePart.new(File.open(blob_path),
                                                           "application/octet-stream",
                                                           File.basename(blob_path)) }
-      AtlasRb::Mash.new(JSON.parse(multipart(nuid).patch(ROUTE + id, payload)&.body))
+      AtlasRb::Mash.new(JSON.parse(
+        multipart(nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id, payload)&.body
+      ))
     end
   end
 end