atlas_rb 1.8.3 → 1.8.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d25a6bf4fdadf6bacf1de67390aeb15343547dba8384c511d8c34b62c1fb058e
-  data.tar.gz: f002dfcb1638bd8c5c5cb668121b9a8515f85765aaab4b229770d8d7b6b3587c
+  metadata.gz: a319cfd0891ed913d8c08f8138d7e11cc12a3f13d79d1b41d9eab95a45e67824
+  data.tar.gz: a840bfac145c02f79f59b53e226d293d90a89a18466511d4b9dbb9bd90460f59
 SHA512:
-  metadata.gz: 9b7f605825d8d4ebb6c44c93c16bc8a7f16a6ee5cb3d7a83c2cba05c7de59e9c25fc92811f35a332ff326dc929b63c057c2743ed8d5fdeb807288f49f2cb2c79
-  data.tar.gz: 20066bd2c7f096a70d3ace6d3c36ed888d135f91e2e31dec7f7828f6eb1f0298e46e4fb0b06fe112be840846675240f6a026787f2479e8e7c73599414f3830d9
+  metadata.gz: ba9b973ba96cbf0f132617bafe8d0475c0bba7b3f76328fbd54adfa20175c96f97fab5e6c4a66a025ea92890d3d2d90f00616674d143a7442dc10da763052013
+  data.tar.gz: 0cc2ce817a804eb2925963f8aae21108bd4151e85cf437c0220574c067025a37544212dc298b2a97b197a063ac258ff8d759ee140f957e3e9ba10f7e3f6a15ce

data/.version

@@ -1 +1 @@
-1.8.3
+1.8.4

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # 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)

data/Gemfile.lock

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

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

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

@@ -345,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.3
+  version: 1.8.4
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-27 00:00:00.000000000 Z
+date: 2026-07-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday