atlas_rb 1.9.2 → 1.9.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 235448544b8690ecf3a941cc259ab5f049442f609766666297c571e336ac3eae
-  data.tar.gz: d3dc2e59aab57397176e959eec0a28478d5a15dbc0ebe2be459c775a42ec00ce
+  metadata.gz: 25a2216a5796eae1514b062b18135d9f071c731f006b50e8f72d6064380f9923
+  data.tar.gz: d8d564ef0d476aa32046c5a4294776b73217e0c4a932b5b9895f22f6843c4371
 SHA512:
-  metadata.gz: 786316240b620bed1a107503c2162d0add7979bbc70574a9f0d1b7cbc473e616e28001d8db9abc75edc972c544211207cbd93f1eee93e674f365d2b0cbecc5e0
-  data.tar.gz: aa6f59d62916ce00cb59ae8cca4e8e029ff96ff4c1fcb40041a4c4fd27d675dfcf98b7a2a04cca5a6f9876bdec846415196d09499f91ee170abb636964b22d25
+  metadata.gz: 685a8bf54eeffcf7590a26147455deeca64751e7161155978607c6bf6b68b29b9c982b9b6ffbca1bdbc004dcdeec0b9d1f5fe5955b17e5e9009b74c709e91f51
+  data.tar.gz: ef296b4c28970b3ec6d3b3ec35647a90407636d174d4a6ee9d1663640fd8c9b3853f4b0371ae6c76d89774fcfe7947d86152b6e717d1ae6b0fe8a509ea8392d0

data/.version

@@ -1 +1 @@
-1.9.2
+1.9.3

data/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 1.9.3
+
+### Added — `depositor:` on `Collection.create` and `Community.create`
+
+`AtlasRb::Collection.create(parent_id, depositor: "000000099")` (and the same
+on `Community.create`) stamps a container's intellectual owner, matching what
+`Work.create` has always supported. Atlas already read the param; only the
+bindings couldn't pass it.
+
+The case it unblocks is seeding an institutional tree: the caller acts as an
+admin (the only identity whose wildcard carries a whole seed sequence) while
+attributing the containers to the anonymous NUID, since nobody personally owns
+them and access is via Grouper groups. That matters now that a depositor
+carries edit rights on their own resource — a container stamped with a real
+person's NUID would hand them edit over that whole subtree.
+
+Omitted, the depositor still falls through to the acting user, so existing
+callers are unaffected.
+
+### Added — typed errors for Atlas's container-create `403` and ACL-write `422`
+
+Atlas gained two refusals that the bindings previously swallowed, because
+`RaiseOnResourceError` was scoped to the re-parent / linked-member /
+Compilation / derivative-permissions / upload paths:
+
+- **A refused create.** `POST /{works,collections,communities}` now `403`s when
+  the caller holds no edit rights on the destination container. The binding's
+  `["collection"]` unwrap returned `nil`, so the caller's next `.id` raised
+  `NoMethodError` — an unhandled 500 instead of an authorization failure. Now
+  {AtlasRb::ForbiddenError}, carrying `action: "create_child"` and the parent
+  container's class as `subject`.
+- **A refused ACL write.** `PATCH /{type}/:id` with `metadata[permissions]`
+  now `422`s with `visibility_exceeds_parent` when the read audience would
+  exceed the structural container. The parsed envelope looked like a success
+  payload, so a user's visibility edit was discarded silently. Now
+  {AtlasRb::PermissionsError}, keyed on the `error` code rather than the path —
+  the same endpoint's other `422`s (tombstone's `has_live_children`) still pass
+  through untouched, which a path rule could not distinguish.
+
+The create branch matches the three paths exactly and only on `POST`, so member
+actions under the same prefix and the index `GET` are unaffected.
+
 ## 1.9.2
 
 ### Added — `read_only:` on `System::Token.mint`

data/Gemfile.lock

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

data/README.md

@@ -222,6 +222,11 @@ AtlasRb::FileSet.create("w-789", "primary") # file_set under work w-789, classif
 AtlasRb::Blob.create("w-789", path, name)  # blob under work w-789 with original filename preserved
 ```
 
+`Community.create`, `Collection.create`, and `Work.create` each accept an
+optional `depositor:` kwarg — the NUID to stamp as the resource's intellectual
+owner, independent of who authorizes the call. Omitted, Atlas falls through to
+the acting user.
+
 `Work.create`, `FileSet.create`, and `Blob.create` each accept an optional
 `idempotency_key:` kwarg for retry-safe bulk-deposit jobs. The caller
 generates the UUID; the Atlas server enforces uniqueness scoped to the

data/lib/atlas_rb/collection.rb

@@ -57,14 +57,26 @@ 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.
+    # @param depositor [String, nil] NUID to stamp as the Collection's
+    #   intellectual owner. Omit it and Atlas falls through to the acting user.
+    #   Supply it to attribute a container to someone other than whoever is
+    #   authorizing the call — e.g. seeding an institutional tree as an admin
+    #   while attributing it to the anonymous NUID, since nobody personally owns
+    #   those containers and access to them is via Grouper groups. The depositor
+    #   is immutable post-create; there is no setter on the update surface.
     # @return [Hash] the created Collection payload (post-update if
     #   `xml_path` was supplied).
     #
     # @example A featured showcase collection
     #   AtlasRb::Collection.create("c-123", featured: true)
-    def self.create(id, xml_path = nil, featured: false, nuid: nil, on_behalf_of: nil)
+    #
+    # @example An institutional container owned by nobody
+    #   AtlasRb::Collection.create("c-123", depositor: "000000099")
+    def self.create(id, xml_path = nil, featured: false, nuid: nil, on_behalf_of: nil, depositor: nil)
+      params = { parent_id: id, featured: featured }
+      params[:depositor] = depositor if depositor
       result = AtlasRb::Mash.new(JSON.parse(
-        connection({ parent_id: id, featured: featured }, nuid, on_behalf_of: on_behalf_of).post(ROUTE)&.body
+        connection(params, nuid, on_behalf_of: on_behalf_of).post(ROUTE)&.body
       ))["collection"]
       return result if xml_path.to_s.empty?
 

data/lib/atlas_rb/community.rb

@@ -52,6 +52,13 @@ 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.
+    # @param depositor [String, nil] NUID to stamp as the Community's
+    #   intellectual owner. Omit it and Atlas falls through to the acting user.
+    #   Supply it to attribute a container to someone other than whoever is
+    #   authorizing the call — e.g. seeding an institutional tree as an admin
+    #   while attributing it to the anonymous NUID, since nobody personally owns
+    #   those containers and access to them is via Grouper groups. The depositor
+    #   is immutable post-create; there is no setter on the update surface.
     # @return [Hash] the created Community payload (post-update if `xml_path`
     #   was supplied).
     #
@@ -60,9 +67,14 @@ module AtlasRb
     #
     # @example Sub-community seeded from MODS
     #   AtlasRb::Community.create("c-parent", "/tmp/dept-mods.xml")
-    def self.create(id = nil, xml_path = nil, nuid: nil, on_behalf_of: nil)
+    #
+    # @example An institutional container owned by nobody
+    #   AtlasRb::Community.create("c-parent", depositor: "000000099")
+    def self.create(id = nil, xml_path = nil, nuid: nil, on_behalf_of: nil, depositor: nil)
+      params = { parent_id: id }
+      params[:depositor] = depositor if depositor
       result = AtlasRb::Mash.new(JSON.parse(
-        connection({ parent_id: id }, nuid, on_behalf_of: on_behalf_of).post(ROUTE)&.body
+        connection(params, nuid, on_behalf_of: on_behalf_of).post(ROUTE)&.body
       ))["community"]
       return result if xml_path.to_s.empty?
 

data/lib/atlas_rb/errors.rb

@@ -201,15 +201,58 @@ module AtlasRb
     end
   end
 
-  # Raised when Atlas refuses a re-parent, linked-member, or Compilation
-  # request with an HTTP `403`, whose envelope is
+  # Raised when Atlas refuses an ACL write on a resource
+  # (`PATCH /{works,collections,communities}/:id` with `metadata[permissions]`)
+  # because it breaks a rights invariant. Today the one code is
+  # `visibility_exceeds_parent`: a resource may be no more visible than its
+  # structural container, so opening a Work to `public` inside a restricted
+  # Collection is refused (the fix is to widen the container).
+  #
+  # This is NOT an authorization failure — the caller may well hold full edit
+  # rights on the resource, and a depositor choosing "Public" on their own item
+  # under a private collection trips it in ordinary use. Without the typed
+  # error the binding's `["collection"]` / `["work"]` unwrap returns an envelope
+  # the caller reads as success, so the user's visibility edit is silently
+  # discarded.
+  #
+  #   rescue AtlasRb::PermissionsError => e
+  #     flash.now[:alert] = t("permissions.errors.#{e.code}", default: e.message)
+  #
+  # @note Keyed on the envelope's `error` code, not the request path, so other
+  #   `422`s on the same endpoint (e.g. `tombstone`'s `has_live_children`) pass
+  #   through untouched.
+  class PermissionsError < 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 resource'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 resource'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, Compilation, or
+  # container-create request with an HTTP `403`, whose envelope is
   # `{ "error", "action", "subject" }`. Lets callers distinguish "you may
   # not do this" from a structural rejection ({ReparentError} /
   # {LinkedMemberError} / {CompilationError}) or a not-found.
   #
-  # @note Scoped to the re-parent / linked-member write paths and the
-  #   Compilation surface — `403`s on other endpoints still surface as raw
-  #   responses for the caller's own rescue layer, unchanged.
+  # On a create the `action` is `create_child` and the `subject` is the parent
+  # container's class: the caller holds no edit rights on the container the new
+  # child would land in.
+  #
+  # @note Scoped to the re-parent / linked-member write paths, the Compilation
+  #   surface, and the container-create endpoints — `403`s on other endpoints
+  #   still surface as raw responses for the caller's own rescue layer,
+  #   unchanged.
   class ForbiddenError < Error
     # @return [String, nil] the envelope's `error` value.
     attr_reader :code

data/lib/atlas_rb/middleware/raise_on_resource_error.rb

@@ -17,22 +17,29 @@ 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...`), 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.
+    # write (`.../derivative_permissions`), the container-create endpoints
+    # ({CREATE_PATHS}), 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.
     # Everything else (other paths, other statuses, a `422` whose body uses a
     # different discriminator such as `tombstone`'s `code: "has_live_children"`)
     # passes through untouched, so atlas_rb stays a thin Faraday binding that
     # translates only the wire signals callers genuinely need to discriminate.
     #
+    # The ACL branch is keyed on the `error` code ({PERMISSIONS_CODES}) rather
+    # than a path, because the write it guards is the plain resource `PATCH`
+    # whose other rejections (tombstone's `has_live_children`) must keep passing
+    # through — a path rule couldn't tell them apart.
+    #
     # Mapping:
-    # - `403` on a re-parent/linked/Compilation/derivative-permissions path → {AtlasRb::ForbiddenError}
+    # - `403` on a re-parent/linked/Compilation/derivative-permissions/create 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` + an ACL discriminator anywhere → {AtlasRb::PermissionsError}
     # - `422` + a fixity discriminator on `/files...` / `/file_sets...` →
     #   {AtlasRb::FixityMismatchError}
     class RaiseOnResourceError < Faraday::Middleware
@@ -40,12 +47,25 @@ module AtlasRb
       # `error` on those paths passes through (Atlas owns these as a wire contract).
       FIXITY_CODES = %w[fixity_mismatch unsupported_digest_algorithm].freeze
 
+      # ACL-invariant `422` discriminators, translated wherever they appear:
+      # Atlas raises them from the shared metadata-PATCH funnel, so they can
+      # arrive on any resource's `PATCH /{type}/:id`.
+      PERMISSIONS_CODES = %w[visibility_exceeds_parent].freeze
+
+      # The container-create endpoints, matched exactly (no trailing id) and only
+      # on `POST`, so neither a member action under the same prefix
+      # (`/collections/:id/tombstone`, whose `422` must pass through) nor the
+      # index `GET` on the same path can be caught by mistake. A `403` here means
+      # the caller holds no edit rights on the destination container.
+      CREATE_PATHS = %w[/works /collections /communities].freeze
+
       # @param env [Faraday::Env] the completed response environment.
-      # @raise [AtlasRb::ForbiddenError] on a 403 to a re-parent/linked/Compilation path.
+      # @raise [AtlasRb::ForbiddenError] on a 403 to a re-parent/linked/Compilation/create path.
       # @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::PermissionsError] on a 422 carrying an ACL-invariant discriminator.
       # @raise [AtlasRb::FixityMismatchError] on a 422 + fixity discriminator to an upload path.
       # @return [void]
       def on_complete(env)
@@ -56,15 +76,27 @@ module AtlasRb
         linked      = path.include?("/linked_members")
         compilation = path.start_with?("/compilations")
         deriv_perms = path.end_with?("/derivative_permissions")
+        create      = env.method.to_s == "post" && CREATE_PATHS.include?(path.chomp("/"))
         upload      = path.start_with?("/files") || path.start_with?("/file_sets")
-        return unless reparent || linked || compilation || deriv_perms || upload
 
         body = parse_json(env.body)
         return unless body.is_a?(Hash) && body["error"]
 
+        # Path-independent: the ACL invariants ride the shared metadata PATCH,
+        # so the code is the only reliable signal.
+        if env.status == 422 && PERMISSIONS_CODES.include?(body["error"])
+          raise AtlasRb::PermissionsError.new(
+            body["message"] || "Atlas rejected the permissions write",
+            code: body["error"],
+            resource_id: body["resource_id"]
+          )
+        end
+
+        return unless reparent || linked || compilation || deriv_perms || create || upload
+
         if env.status == 403
           # 403s on upload paths stay raw — acting-as/authz isn't an upload concern here.
-          return unless reparent || linked || compilation || deriv_perms
+          return unless reparent || linked || compilation || deriv_perms || create
 
           raise AtlasRb::ForbiddenError.new(
             body["message"] || "Atlas refused the request",

metadata

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