atlas_rb 1.9.0 → 1.9.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9bfa2bcb90b5d30ebbf8a4a2612b1a6aafab5fc4eb07df8b12c3ba904ab1fb48
-  data.tar.gz: 9afb80d4f4cecfdfa5204ad101967fe4360057a2222ca573153e00bfc3a3e281
+  metadata.gz: 235448544b8690ecf3a941cc259ab5f049442f609766666297c571e336ac3eae
+  data.tar.gz: d3dc2e59aab57397176e959eec0a28478d5a15dbc0ebe2be459c775a42ec00ce
 SHA512:
-  metadata.gz: 2dbd56463086ce26fc3380eaee4e850dfe6c66a15d6e716c22271d8a13230fbb9db122195f368b41dad8edf96eb153540c699c567f0d43b50b96bc95e8d5c1b7
-  data.tar.gz: cfba3517bd027ae9ff972b3316da4a3bd941e28a080961a69d16625b874bd6b6f5ececd503327d5f0b9ebc56ffc118bd36c04823e2a94ba07aa45a4179fcdc4b
+  metadata.gz: 786316240b620bed1a107503c2162d0add7979bbc70574a9f0d1b7cbc473e616e28001d8db9abc75edc972c544211207cbd93f1eee93e674f365d2b0cbecc5e0
+  data.tar.gz: aa6f59d62916ce00cb59ae8cca4e8e029ff96ff4c1fcb40041a4c4fd27d675dfcf98b7a2a04cca5a6f9876bdec846415196d09499f91ee170abb636964b22d25

data/.version

@@ -1 +1 @@
-1.9.0
+1.9.2

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.9.2
+
+### Added — `read_only:` on `System::Token.mint`
+
+`AtlasRb::System::Token.mint(nuid:, read_only: true)` mints a token Atlas
+structurally restricts to read-shaped actions, independent of what `nuid`
+could otherwise do — the shape to hand to a non-human caller (e.g. an Atlas
+MCP client) that must never be able to mutate the repository. Omitted, mint
+is unchanged (full-privilege, as before).
+
 ## 1.8.8
 
 ### Added — type-agnostic current MODS (`Resource.mods`)

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    atlas_rb (1.9.0)
+    atlas_rb (1.9.2)
       faraday (~> 2.7)
       faraday-follow_redirects (~> 0.3.0)
       faraday-multipart (~> 1)
@@ -25,7 +25,7 @@ GEM
       net-http (~> 0.5)
     hashie (5.1.0)
       logger
-    json (2.20.0)
+    json (2.21.1)
     jwt (2.10.3)
       base64
     logger (1.7.0)

data/lib/atlas_rb/faraday_helper.rb

@@ -196,11 +196,13 @@ module AtlasRb
     # Used exclusively by classes under {AtlasRb::System}.
     #
     # @param params [Hash] query-string / body params.
+    # @param on_behalf_of [String, nil] optional NUID sent as a plain (not
+    #   signed) `On-Behalf-Of` header — this path is already backend-only.
     # @return [Faraday::Connection] a system-authenticated connection.
     # @raise [RuntimeError] if the credential is not configured.
     # @raise [NameError] if `Rails` is not loaded (the gem assumes a
     #   Rails host for system-path calls).
-    def system_connection(params = {})
+    def system_connection(params = {}, on_behalf_of: nil)
       token = Rails.application.credentials.atlas_system_token ||
               raise("atlas_rb: Rails.application.credentials.atlas_system_token not configured")
 
@@ -209,6 +211,7 @@ module AtlasRb
         "Authorization" => "Bearer #{token}",
         "User"          => "NUID #{AtlasRb::System::NUID}"
       }
+      headers["On-Behalf-Of"] = "NUID #{on_behalf_of}" if on_behalf_of
 
       Faraday.new(
         url: ENV.fetch("ATLAS_URL", nil),
@@ -216,6 +219,10 @@ module AtlasRb
         headers: headers
       ) do |f|
         instrument(f)
+        # Narrowly path-scoped (see each class) — a no-op for System::User /
+        # System::Token, and gives System::Work the same typed errors as #connection.
+        f.use AtlasRb::Middleware::RaiseOnStaleResource
+        f.use AtlasRb::Middleware::RaiseOnResourceError
         f.response :follow_redirects
         f.adapter Faraday.default_adapter
       end

data/lib/atlas_rb/system/token.rb

@@ -27,13 +27,21 @@ module AtlasRb
       # System-gated. The returned token authenticates as `nuid` in BYO-JWT
       # mode (Atlas resolves identity from the token's `sub`, ignores any
       # `User:` / `On-Behalf-Of` header, and refuses `:system`/`:anonymous`).
-      # Full-privilege for that user, 1-week TTL, single-jti.
+      # Full-privilege for that user, 1-week TTL, single-jti — unless
+      # `read_only` is set, in which case Atlas structurally restricts the
+      # token to read-shaped actions regardless of what `nuid` could
+      # otherwise do. That's the shape to hand to a non-human caller (e.g.
+      # an MCP client) that must never be able to mutate the repository.
       #
       # @param nuid [String] the NUID the token will act as.
+      # @param read_only [Boolean] mint a token restricted to read-shaped
+      #   actions only.
       # @return [String, nil] the JWT, or nil when the NUID has no Atlas User
       #   row (404) — a clean "no such user" signal for the caller to surface.
-      def self.mint(nuid:)
-        response = system_connection.post("/nuid", { nuid: nuid }.to_json)
+      def self.mint(nuid:, read_only: false)
+        body = { nuid: nuid }
+        body[:read_only] = true if read_only
+        response = system_connection.post("/nuid", body.to_json)
         return nil if response.status == 404
 
         AtlasRb::Mash.new(JSON.parse(response.body))["token"]

data/lib/atlas_rb/system/work.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module AtlasRb
+  module System
+    # Showcase publishing: link a freshly-created Work into a depositor's
+    # featured showcase Collection on their behalf, without granting the
+    # depositor themselves standing edit rights on that shared Collection.
+    #
+    # Atlas scopes this narrowly on both sides (see Atlas's `Ability`): the
+    # target Collection must be `featured`, and the Work must belong to the
+    # `on_behalf_of` NUID — never an arbitrary or private Work. Cerberus's
+    # `WorkDeposit#create_published` ("Publish to my community") is the one
+    # caller today.
+    #
+    # Always authenticates via {FaradayHelper#system_connection}, so there is
+    # no way to issue this as a regular user.
+    class Work
+      extend AtlasRb::FaradayHelper
+
+      # @param work_id [String] the Work ID to link.
+      # @param collection_id [String] the (must-be-featured) showcase
+      #   Collection to link the Work into.
+      # @param on_behalf_of [String] the depositor NUID this write is
+      #   attributed to — required (unlike the regular, human-facing
+      #   {AtlasRb::Work.add_linked_member}), since a :system call with no
+      #   attribution defeats the point of this path, and Atlas's Ability
+      #   grant is itself conditioned on it matching the Work's depositor.
+      # @return [Array<String>] the Work's full set of linked Collection
+      #   noids after the add.
+      # @raise [AtlasRb::StaleResourceError] optimistic-lock conflict.
+      # @raise [AtlasRb::LinkedMemberError] structural rejection (HTTP 422) —
+      #   non-Collection target, tombstoned work/target, already a structural
+      #   member.
+      # @raise [AtlasRb::ForbiddenError] Atlas refused the link (HTTP 403) —
+      #   e.g. the target Collection isn't featured, or on_behalf_of doesn't
+      #   own the Work.
+      #
+      # @example From Cerberus's publish-to-showcase deposit branch
+      #   AtlasRb::System::Work.add_linked_member(work.id, showcase.id, on_behalf_of: depositor_nuid)
+      def self.add_linked_member(work_id, collection_id, on_behalf_of:)
+        JSON.parse(
+          system_connection({ collection_id: collection_id }, on_behalf_of: on_behalf_of)
+            .post("/works/#{work_id}/linked_members")&.body
+        )
+      end
+    end
+  end
+end

data/lib/atlas_rb.rb

@@ -31,6 +31,7 @@ require_relative "atlas_rb/admin/community"
 require_relative "atlas_rb/system"
 require_relative "atlas_rb/system/user"
 require_relative "atlas_rb/system/token"
+require_relative "atlas_rb/system/work"
 require_relative "atlas_rb/audit_event"
 
 # Ruby client for the Atlas API — Northeastern University's institutional

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.9.0
+  version: 1.9.2
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-11 00:00:00.000000000 Z
+date: 2026-07-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -152,6 +152,7 @@ files:
 - lib/atlas_rb/system.rb
 - lib/atlas_rb/system/token.rb
 - lib/atlas_rb/system/user.rb
+- lib/atlas_rb/system/work.rb
 - lib/atlas_rb/user.rb
 - lib/atlas_rb/version.rb
 - lib/atlas_rb/work.rb