atlas_rb 1.8.2 → 1.8.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a0fac04427bc3f23f92da8a5241a263111f45b28fa01cc8829da0de3b6b48f9
-  data.tar.gz: 8e95150d0f2ecd0a33c52179e384f8462546b422dcd6997c69886163215811c8
+  metadata.gz: a319cfd0891ed913d8c08f8138d7e11cc12a3f13d79d1b41d9eab95a45e67824
+  data.tar.gz: a840bfac145c02f79f59b53e226d293d90a89a18466511d4b9dbb9bd90460f59
 SHA512:
-  metadata.gz: 4ced2b3f0f3fee473712f38ae3161ea8f678d9468abaf1250c9577e13261b5688be16ea687a69f6b28931a6e8920ad737d7a2057059c14751cceb683e463c2ef
-  data.tar.gz: 017e1004f59a5529184e3f07f93c815a463da07937863ff72b2063b3e1986f624e5e8ea83c0b5750b57885e7942ef981b32e66f7d3e5931ea6545108c643162d
+  metadata.gz: ba9b973ba96cbf0f132617bafe8d0475c0bba7b3f76328fbd54adfa20175c96f97fab5e6c4a66a025ea92890d3d2d90f00616674d143a7442dc10da763052013
+  data.tar.gz: 0cc2ce817a804eb2925963f8aae21108bd4151e85cf437c0220574c067025a37544212dc298b2a97b197a063ac258ff8d759ee140f957e3e9ba10f7e3f6a15ce

data/.version

@@ -1 +1 @@
-1.8.2
+1.8.4

data/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Changelog
 
+## 1.8.4
+
+### Added — per-tier derivative-visibility policy (`Work.set_derivative_permissions`)
+
+New binding for the departmental "each download rendition has its own permissions"
+model: `AtlasRb::Work.set_derivative_permissions(id, policy:, …)` PATCHes a per-tier
+read policy to `PATCH /works/:id/derivative_permissions`. `policy` is a map of tier
+(`small` / `medium` / `large` / `service`) => array of read-group tokens (the resource
+vocabulary: `"public"`, Grouper group names, `[]` = private). Whole-object replace;
+omitted tiers inherit by cascade (an absent tier inherits the next lower-resolution
+tier; `small` inherits the Work). Atlas enforces two invariants — a tier may not be
+more visible than the Work, and visibility must narrow as resolution grows
+(`service` ⊆ `large` ⊆ `medium` ⊆ `small`).
+
+The effective per-Delegate gate surfaces on `Work.assets` entries as `gated` (must be
+authorized, not linked directly) and `permission` (the effective read-group set;
+`null` for guests). No `assets` change is needed — the new fields flow through the
+existing polymorphic Mash. The gate is advisory: Cerberus and the IIIF auth layer
+enforce it.
+
+A `422` rejection (`tier_exceeds_resource` / `tier_ordering_violation` /
+`unknown_tier`) now raises the typed `AtlasRb::DerivativePermissionsError` (with `code`
+/ `resource_id`) via `RaiseOnResourceError`, mirroring the re-parent / linked-member /
+Compilation mappings; a `403` raises `AtlasRb::ForbiddenError`; a `409` raises
+`AtlasRb::StaleResourceError`.
+
+## 1.8.3
+
+### Changed — `find` is status-aware (stops swallowing Atlas error envelopes)
+
+Every typed single-resource reader — `Resource.find` (the polymorphic resolver)
+and the `Work` / `Collection` / `Community` / `FileSet` / `Person` /
+`Compilation` / `Blob` / `Delegate` overrides — now routes through a shared
+status-aware read path instead of blindly `JSON.parse`-ing the body and
+unwrapping a fixed key.
+
+Previously, any non-2xx that wasn't a re-parent/linked-member/Compilation/upload
+signal (which `RaiseOnResourceError` already translates) passed straight through:
+Atlas renders its auth/validation failures as a JSON envelope (`{ "error" => …}`,
+status 400/401/403/422), so `JSON.parse(body)["work"]` found no `"work"` key and
+returned **`nil`**. Callers then dereferenced that `nil` far from the cause — the
+canonical symptom being `undefined method 'tombstoned' for nil`, a 500 surfaced
+nowhere near the request that actually failed.
+
+Now:
+
+- **`404` → `nil`** — a clean "not found" (and no more `JSON::ParserError` on the
+  empty `head :not_found` body, which is what a missing id used to raise).
+- **any other non-2xx → `AtlasRb::ResourceError`** — a new typed error carrying
+  Atlas's `status`, `body`, and `response`, raised **at the boundary** so the
+  real cause (e.g. `GET /works/abc → 401: {"error":"invalid bearer token"}`) is
+  attributable everywhere `find` is used.
+- **`2xx`** → unchanged (the unwrapped resource).
+
+Authorization failures on the narrow re-parent / linked-member / Compilation
+write paths still surface as `AtlasRb::ForbiddenError` via
+`RaiseOnResourceError`; `ResourceError` is the catch-all for the read path that
+middleware intentionally does not cover.
+
+**Behavior change to note:** `find` of a missing id now returns `nil` rather than
+raising `JSON::ParserError`. Callers that relied on the parse error (none known)
+should nil-check instead.
+
 ## 1.8.0
 
 ### Added — `Work.set_full_text` (full-text search seam)

data/Gemfile.lock

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

data/lib/atlas_rb/blob.rb

@@ -23,20 +23,22 @@ module AtlasRb
     # @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
+    # @return [Hash, nil] the `"blob"` object, already unwrapped — typically
     #   includes `"id"`, `"original_filename"`, `"size"`, `"digest"` (the
     #   recorded fixity digest `"sha512:<hex>"`, or `nil` for a Blob with no
     #   held bytes — reconciliation compares this against the v1 manifest
-    #   without re-downloading), and a download URL.
+    #   without re-downloading), and a download URL — or `nil` when the Blob
+    #   does not exist (`404`).
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` (e.g. an
+    #   auth/validation error envelope), carrying Atlas's status + body.
     #
     # @example
     #   AtlasRb::Blob.find("b-321")
     #   # => { "id" => "b-321", "original_filename" => "scan.pdf",
     #   #      "digest" => "sha512:9f86d0…", ... }
     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']
+      body = fetch_resource(ROUTE + id, nuid: nuid, on_behalf_of: on_behalf_of)
+      body && AtlasRb::Mash.new(body)['blob']
     end
 
     # Resolve a content Blob to its parent FileSet and containing Work noids.

data/lib/atlas_rb/collection.rb

@@ -22,16 +22,17 @@ module AtlasRb
     # @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 `"collection"` object, already unwrapped from the
-    #   JSON response.
+    # @return [Hash, nil] the `"collection"` object, already unwrapped from the
+    #   JSON response, or `nil` when the Collection does not exist (`404`).
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` (e.g. an
+    #   auth/validation error envelope), carrying Atlas's status + body.
     #
     # @example
     #   AtlasRb::Collection.find("col-456")
     #   # => { "id" => "col-456", "title" => "Faculty Publications", ... }
     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
-      ))["collection"]
+      body = fetch_resource(ROUTE + id, nuid: nuid, on_behalf_of: on_behalf_of)
+      body && AtlasRb::Mash.new(body)["collection"]
     end
 
     # Create a new Collection under an existing Community.

data/lib/atlas_rb/community.rb

@@ -23,16 +23,17 @@ module AtlasRb
     # @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 `"community"` object from the JSON response,
-    #   already unwrapped.
+    # @return [Hash, nil] the `"community"` object from the JSON response,
+    #   already unwrapped, or `nil` when the Community does not exist (`404`).
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` (e.g. an
+    #   auth/validation error envelope), carrying Atlas's status + body.
     #
     # @example
     #   AtlasRb::Community.find("c-123")
     #   # => { "id" => "c-123", "title" => "College of Engineering", ... }
     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
-      ))["community"]
+      body = fetch_resource(ROUTE + id, nuid: nuid, on_behalf_of: on_behalf_of)
+      body && AtlasRb::Mash.new(body)["community"]
     end
 
     # Create a new Community, optionally seeded with MODS metadata.

data/lib/atlas_rb/compilation.rb

@@ -38,19 +38,20 @@ module AtlasRb
     # @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 `"compilation"` object, already unwrapped — `id`,
+    # @return [Hash, nil] the `"compilation"` object, already unwrapped — `id`,
     #   `title`, `description`, `depositor`, the three recipe arrays
     #   (`included_collections`, `included_works`, `excluded_works`), the
-    #   ACL arrays, and timestamps.
+    #   ACL arrays, and timestamps — or `nil` when the Set does not exist (`404`).
     # @raise [AtlasRb::ForbiddenError] if the caller may not read this Set.
+    # @raise [AtlasRb::ResourceError] on any other non-2xx (e.g. `401`),
+    #   carrying Atlas's status + body.
     #
     # @example
     #   AtlasRb::Compilation.find("c-123", nuid: "000000002")
     #   # => { "id" => "c-123", "title" => "Course readings", ... }
     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
-      ))["compilation"]
+      body = fetch_resource(ROUTE + id, nuid: nuid, on_behalf_of: on_behalf_of)
+      body && AtlasRb::Mash.new(body)["compilation"]
     end
 
     # List Compilations, paginated (newest first), in one of three modes.

data/lib/atlas_rb/delegate.rb

@@ -29,16 +29,18 @@ module AtlasRb
     # @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 [AtlasRb::Mash] the `"delegate"` object, already unwrapped —
+    # @return [AtlasRb::Mash, nil] the `"delegate"` object, already unwrapped —
     #   includes `id`, `valkyrie_id`, `use`, `uri`, `mime_type`,
-    #   `original_filename`, `label`, and tombstone fields.
+    #   `original_filename`, `label`, and tombstone fields — or `nil` when the
+    #   Delegate does not exist (`404`).
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` (e.g. an
+    #   auth/validation error envelope), carrying Atlas's status + body.
     #
     # @example
     #   AtlasRb::Delegate.find("d-555")
     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
-      ))["delegate"]
+      body = fetch_resource(ROUTE + id, nuid: nuid, on_behalf_of: on_behalf_of)
+      body && AtlasRb::Mash.new(body)["delegate"]
     end
   end
 end

data/lib/atlas_rb/errors.rb

@@ -169,6 +169,38 @@ module AtlasRb
     end
   end
 
+  # Raised when Atlas rejects a per-tier derivative-visibility policy
+  # (`PATCH /works/:id/derivative_permissions`) with a `422` carrying a
+  # machine-readable `error` discriminator — `tier_exceeds_resource` (a tier
+  # more visible than its Work), `tier_ordering_violation` (visibility not
+  # narrowing as resolution grows), or `unknown_tier`.
+  #
+  # The derivative-permissions sibling of {ReparentError} / {LinkedMemberError};
+  # same shape, same rationale (the binding's `["work"]` unwrap would otherwise
+  # discard the envelope on the 422). Atlas rejects before persisting.
+  #
+  #   rescue AtlasRb::DerivativePermissionsError => e
+  #     flash.now[:alert] = t("derivative_permissions.errors.#{e.code}", default: e.message)
+  #
+  # @note Authorization failures surface as {ForbiddenError} (HTTP 403).
+  class DerivativePermissionsError < Error
+    # @return [String, nil] the machine-readable error code from the envelope,
+    #   suitable for keying an i18n map.
+    attr_reader :code
+
+    # @return [String, nil] the rejected Work's ID, from the envelope.
+    attr_reader :resource_id
+
+    # @param message [String] human-readable rejection description.
+    # @param code [String, nil] the envelope's `error` discriminator.
+    # @param resource_id [String, nil] the rejected Work's ID.
+    def initialize(message, code: nil, resource_id: nil)
+      super(message)
+      @code = code
+      @resource_id = resource_id
+    end
+  end
+
   # Raised when Atlas refuses a re-parent, linked-member, or Compilation
   # request with an HTTP `403`, whose envelope is
   # `{ "error", "action", "subject" }`. Lets callers distinguish "you may
@@ -200,6 +232,50 @@ module AtlasRb
     end
   end
 
+  # Raised by the typed single-resource readers ({Resource.find} and the
+  # `Work` / `Collection` / `Community` / `FileSet` / `Person` / `Compilation`
+  # / `Blob` / `Delegate` overrides) when Atlas answers the `GET` with a
+  # non-2xx that is **not** a `404` — i.e. an error envelope
+  # (`{ "error" => ... }`, status 400/401/403/422) on what the caller treated
+  # as a plain read.
+  #
+  # Before this existed, `find` unwrapped the success body by a fixed key
+  # (`["work"]`, `["collection"]`, …); on an error envelope that key is
+  # absent, so `find` returned `nil` and silently discarded Atlas's status and
+  # message. The caller then dereferenced the `nil` far from the cause (the
+  # canonical symptom: `undefined method 'tombstoned' for nil`). This error
+  # keeps the failure **at the boundary**, carrying the status and body so the
+  # real cause (e.g. `… → 401: {"error":"invalid bearer token"}`) is
+  # attributable everywhere `find` is used.
+  #
+  # A genuine `404` is **not** this — it stays a clean `nil` return, since
+  # "not found" is a normal `find` outcome callers already nil-check.
+  #
+  # @note Authorization failures on the narrow re-parent / linked-member /
+  #   Compilation write paths surface as {ForbiddenError} via
+  #   {Middleware::RaiseOnResourceError}; this is the catch-all for the read
+  #   path, which that middleware intentionally does not cover.
+  class ResourceError < Error
+    # @return [Faraday::Response, nil] the originating response, when available.
+    attr_reader :response
+
+    # @return [Integer, nil] Atlas's HTTP status.
+    attr_reader :status
+
+    # @return [String, nil] Atlas's raw response body (the error envelope).
+    attr_reader :body
+
+    # @param message [String] human-readable failure description.
+    # @param response [Faraday::Response, nil] the originating response; its
+    #   status and body are captured for callers that rescue this.
+    def initialize(message, response: nil)
+      super(message)
+      @response = response
+      @status = response&.status
+      @body = response&.body
+    end
+  end
+
   # Raised when the transport has no way to authenticate a relay request:
   # neither `ATLAS_JWT` (BYO-JWT mode) nor a signing key
   # ({AtlasRb.config#assertion_signing_key}, relay-signing mode) is configured.

data/lib/atlas_rb/file_set.rb

@@ -23,14 +23,16 @@ module AtlasRb
     # @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 `"file_set"` object, already unwrapped.
+    # @return [Hash, nil] the `"file_set"` object, already unwrapped, or `nil`
+    #   when the FileSet does not exist (`404`).
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` (e.g. an
+    #   auth/validation error envelope), carrying Atlas's status + body.
     #
     # @example
     #   AtlasRb::FileSet.find("fs-001")
     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
-      ))["file_set"]
+      body = fetch_resource(ROUTE + id, nuid: nuid, on_behalf_of: on_behalf_of)
+      body && AtlasRb::Mash.new(body)["file_set"]
     end
 
     # Create a new FileSet under a Work.

data/lib/atlas_rb/middleware/raise_on_resource_error.rb

@@ -16,8 +16,9 @@ module AtlasRb
     #
     # It is intentionally narrow — it only fires on the re-parent
     # (`.../parent`) and linked-member (`.../linked_members...`) write paths,
-    # the Compilation surface (`/compilations...`), and binary uploads
-    # (`/files...`, `/file_sets...`), and only on `403` / `422` bodies carrying
+    # the Compilation surface (`/compilations...`), the derivative-permissions
+    # write (`.../derivative_permissions`), and binary uploads (`/files...`,
+    # `/file_sets...`), and only on `403` / `422` bodies carrying
     # an `error` discriminator. The upload branch is further gated on a fixity
     # discriminator ({FIXITY_CODES}), so a `422` on those paths with any other
     # `error` (or `403`s on uploads, which stay raw) passes through untouched.
@@ -27,10 +28,11 @@ module AtlasRb
     # translates only the wire signals callers genuinely need to discriminate.
     #
     # Mapping:
-    # - `403` on a re-parent/linked/Compilation path → {AtlasRb::ForbiddenError}
+    # - `403` on a re-parent/linked/Compilation/derivative-permissions path → {AtlasRb::ForbiddenError}
     # - `422` on `.../parent` → {AtlasRb::ReparentError} (`error`/`resource_id`)
     # - `422` on `.../linked_members...` → {AtlasRb::LinkedMemberError}
     # - `422` on `/compilations...` → {AtlasRb::CompilationError}
+    # - `422` on `.../derivative_permissions` → {AtlasRb::DerivativePermissionsError}
     # - `422` + a fixity discriminator on `/files...` / `/file_sets...` →
     #   {AtlasRb::FixityMismatchError}
     class RaiseOnResourceError < Faraday::Middleware
@@ -43,6 +45,7 @@ module AtlasRb
       # @raise [AtlasRb::ReparentError] on a 422 to a re-parent path.
       # @raise [AtlasRb::LinkedMemberError] on a 422 to a linked-member path.
       # @raise [AtlasRb::CompilationError] on a 422 to a Compilation path.
+      # @raise [AtlasRb::DerivativePermissionsError] on a 422 to a derivative-permissions path.
       # @raise [AtlasRb::FixityMismatchError] on a 422 + fixity discriminator to an upload path.
       # @return [void]
       def on_complete(env)
@@ -52,15 +55,16 @@ module AtlasRb
         reparent    = path.end_with?("/parent")
         linked      = path.include?("/linked_members")
         compilation = path.start_with?("/compilations")
+        deriv_perms = path.end_with?("/derivative_permissions")
         upload      = path.start_with?("/files") || path.start_with?("/file_sets")
-        return unless reparent || linked || compilation || upload
+        return unless reparent || linked || compilation || deriv_perms || upload
 
         body = parse_json(env.body)
         return unless body.is_a?(Hash) && body["error"]
 
         if env.status == 403
           # 403s on upload paths stay raw — acting-as/authz isn't an upload concern here.
-          return unless reparent || linked || compilation
+          return unless reparent || linked || compilation || deriv_perms
 
           raise AtlasRb::ForbiddenError.new(
             body["message"] || "Atlas refused the request",
@@ -86,6 +90,12 @@ module AtlasRb
             code: body["error"],
             resource_id: body["resource_id"]
           )
+        elsif deriv_perms
+          raise AtlasRb::DerivativePermissionsError.new(
+            body["message"] || "Atlas rejected the derivative-permissions policy",
+            code: body["error"],
+            resource_id: body["resource_id"]
+          )
         elsif FIXITY_CODES.include?(body["error"])
           raise AtlasRb::FixityMismatchError.new(
             body["message"] || "Atlas rejected the upload (fixity)",

data/lib/atlas_rb/person.rb

@@ -33,13 +33,15 @@ module AtlasRb
     # @param id [String] the person's NOID.
     # @param nuid [String, nil] acting principal (signed into the assertion sub).
     # @param on_behalf_of [String, nil] acting-as target.
-    # @return [AtlasRb::Mash] the unwrapped `"person"` object (carries the
+    # @return [AtlasRb::Mash, nil] the unwrapped `"person"` object (carries the
     #   server-side `nuid` for callers that need it, e.g. depositor gating, and
-    #   `personal_root_id` for the publish-conduit parent).
+    #   `personal_root_id` for the publish-conduit parent), or `nil` when the
+    #   Person does not exist (`404`).
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` (e.g. an
+    #   auth/validation error envelope), carrying Atlas's status + body.
     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
-      ))["person"]
+      body = fetch_resource(ROUTE + id, nuid: nuid, on_behalf_of: on_behalf_of)
+      body && AtlasRb::Mash.new(body)["person"]
     end
 
     # List people — the NOID-keyed People-index source. Returns the page's

data/lib/atlas_rb/resource.rb

@@ -32,17 +32,20 @@ module AtlasRb
     # @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{String => String, Hash}] hash with two keys:
+    # @return [Hash{String => String, Hash}, nil] hash with two keys, or `nil`
+    #   when the id resolves to nothing (`404`):
     #   - `"klass"` — the resource type, capitalized (e.g. `"Work"`).
     #   - `"resource"` — the resource payload as a Hash.
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` (e.g. an
+    #   auth/validation error envelope), carrying Atlas's status + body.
     #
     # @example Polymorphic lookup
     #   AtlasRb::Resource.find("abc123")
     #   # => { "klass" => "Work", "resource" => { "id" => "abc123", "title" => "..." } }
     def self.find(id, nuid: nil, on_behalf_of: nil)
-      result = JSON.parse(
-        connection({}, nuid, on_behalf_of: on_behalf_of).get('/resources/' + id)&.body
-      )
+      result = fetch_resource('/resources/' + id, nuid: nuid, on_behalf_of: on_behalf_of)
+      return nil if result.nil?
+
       AtlasRb::Mash.new("klass" => result.first[0].capitalize,
                         "resource" => result.first[1])
     end
@@ -242,5 +245,40 @@ module AtlasRb
           (kind.present? ? ".#{kind}" : '')
       )&.body
     end
+
+    # Shared read path behind every typed `find`: perform a single-resource
+    # `GET` and return the parsed JSON envelope, or `nil` when Atlas reports
+    # the resource is absent (`404`).
+    #
+    # Its job is to stop `find` from silently coercing an error *envelope*
+    # into `nil`. Atlas renders auth/validation failures as a JSON body
+    # (`{ "error" => ... }`, status 400/401/403/422); a naive
+    # `JSON.parse(body)["work"]` returns `nil` for the missing `"work"` key —
+    # losing the status and message, and surfacing as a baffling
+    # `NoMethodError` far from the cause. Mapping:
+    #
+    # - `404`             → `nil` (clean "not found"; also avoids the
+    #   `JSON::ParserError` the old code raised on the empty `head :not_found`
+    #   body).
+    # - any other non-2xx → {AtlasRb::ResourceError} carrying Atlas's status +
+    #   body, so the failure is attributable at the boundary.
+    # - `2xx`             → the parsed JSON Hash, for the caller to unwrap.
+    #
+    # @param path [String] the resource path to GET (e.g. `"/works/abc123"`).
+    # @param nuid [String, nil] optional acting user's NUID (see {find}).
+    # @param on_behalf_of [String, nil] optional `On-Behalf-Of` NUID (see {find}).
+    # @return [Hash, nil] the parsed JSON envelope, or `nil` on `404`.
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404`.
+    # @api private
+    def self.fetch_resource(path, nuid: nil, on_behalf_of: nil)
+      resp = connection({}, nuid, on_behalf_of: on_behalf_of).get(path)
+      return nil if resp.status == 404
+      unless resp.success?
+        raise AtlasRb::ResourceError.new("GET #{path} → #{resp.status}: #{resp.body}", response: resp)
+      end
+
+      JSON.parse(resp.body)
+    end
+    private_class_method :fetch_resource
   end
 end

data/lib/atlas_rb/work.rb

@@ -22,16 +22,17 @@ module AtlasRb
     # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
     #   header (acting-as / view-as). Falls through to
     #   {AtlasRb.config}.default_on_behalf_of when omitted.
-    # @return [Hash] the `"work"` object, already unwrapped from the JSON
-    #   response.
+    # @return [Hash, nil] the `"work"` object, already unwrapped from the JSON
+    #   response, or `nil` when the Work does not exist (`404`).
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` (e.g. an
+    #   auth/validation error envelope), carrying Atlas's status + body.
     #
     # @example
     #   AtlasRb::Work.find("w-789")
     #   # => { "id" => "w-789", "title" => "An Article", ... }
     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
-      ))["work"]
+      body = fetch_resource(ROUTE + id, nuid: nuid, on_behalf_of: on_behalf_of)
+      body && AtlasRb::Mash.new(body)["work"]
     end
 
     # List Works, paginated.
@@ -344,6 +345,53 @@ module AtlasRb
       ))
     end
 
+    # Replace a Work's per-tier derivative-visibility policy.
+    #
+    # Sets which read groups may fetch the Work's sized image derivatives —
+    # the `small` / `medium` / `large` / `service` (deep-zoom) tiers — reusing
+    # the resource read-group vocabulary (`"public"`, Grouper group names,
+    # `[]` = private). Unlike {.set_image_derivatives} (which upserts URIs) this
+    # is a whole-object REPLACE: the map you pass is the complete policy;
+    # omitted tiers inherit by cascade (an absent tier inherits the next
+    # lower-resolution tier; `small` inherits the Work's own visibility). Pass a
+    # tier as `[]` to make it private.
+    #
+    # Atlas enforces two invariants: a tier may not be more visible than the
+    # Work, and visibility must narrow as resolution grows
+    # (`service` ⊆ `large` ⊆ `medium` ⊆ `small`). The gate is advisory — it
+    # surfaces per Delegate on {.assets} as `gated` / `permission` for the
+    # display layer (Cerberus / the IIIF auth service) to enforce.
+    #
+    # @param id [String] the Work ID.
+    # @param policy [Hash] tier => Array(read groups), e.g.
+    #   `{ large: ["northeastern:drs:repository:archives"], service: [...] }`.
+    #   Keys may be strings or symbols; only `small` / `medium` / `large` /
+    #   `service` are recognized.
+    # @param nuid [String, nil] optional acting user's NUID. On the relay-signing
+    #   path it is signed into the assertion `sub`; on the BYO-JWT (`ATLAS_JWT`)
+    #   path it is ignored (identity lives in the token).
+    # @param on_behalf_of [String, nil] optional On-Behalf-Of NUID.
+    # @return [AtlasRb::Mash] the updated Work; the stored map echoes back under
+    #   `derivative_permissions`.
+    # @raise [AtlasRb::DerivativePermissionsError] if Atlas rejects the policy
+    #   (422) — `tier_exceeds_resource` / `tier_ordering_violation` /
+    #   `unknown_tier` (see {#code}).
+    # @raise [AtlasRb::StaleResourceError] on an optimistic-lock conflict (409).
+    #
+    # @example
+    #   AtlasRb::Work.set_derivative_permissions(
+    #     "w-789",
+    #     policy: { small:   ["public"],
+    #               large:   ["northeastern:drs:repository:archives"],
+    #               service: ["northeastern:drs:repository:archives"] }
+    #   )
+    def self.set_derivative_permissions(id, policy:, nuid: nil, on_behalf_of: nil)
+      AtlasRb::Mash.new(JSON.parse(
+        connection({}, nuid, on_behalf_of: on_behalf_of)
+          .patch(ROUTE + id + '/derivative_permissions', JSON.dump(policy))&.body
+      ))
+    end
+
     # Store a Work's derived full-document text for search indexing.
     #
     # Purpose-specific PATCH in the same "machine-set derived metadata" family

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.8.2
+  version: 1.8.4
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-26 00:00:00.000000000 Z
+date: 2026-07-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday