atlas_rb 1.4.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31c36891a34eef17727397e17017db5eb1acea6cdfae4dfbba76b93e6f32954a
-  data.tar.gz: 3871ca6703afa2ecccf780f089b22e8ff6fdcbcdaf5aaafb82e51bbf606e95a1
+  metadata.gz: decab10cfb0c67c68615a9695a8c5084aa1bd349e199dccd77a76d024a3e7ba3
+  data.tar.gz: 90c4db9a3ffd80e9f226334f4862b9982534e431a3a6eb58746bfa96442ee701
 SHA512:
-  metadata.gz: 84f906c748bd98acb961eb403950d98e1c46be9084ae21fde55b949bc1af6f2bc9f72c567c0bb826b854209b75f51d437196d7e7d0b1031d9f2497e132d305f8
-  data.tar.gz: bac7488013b6d12db98806447405c27ae52d4fed86608c2fc96f2180cea48a931d0d43b1421b914de3218a742fb5bb53cfa46dc9d59f41ee3a92670571a52aee
+  metadata.gz: 7fc789c2d47882f6d93664de27f7ab2f2a0d7d43957f4244436600e4247a332c5f8b3df030a5b11fb064187bd55439c0417a04974ca321df88861d47e0da2f15
+  data.tar.gz: 7189e8bcc3b4d483f623cfdc7a0881f41735646ef085f05a1418436b927fc84c2be514844ea44572c0d2c85f48e057be3a86d5774ac55bf8e09ae3ac4238fc4a

data/.version

@@ -1 +1 @@
-1.4.0
+1.6.0

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.5.0
+
+### Added — optional auth for `Reset.clean`
+
+`AtlasRb::Reset.clean` now uses **optional auth**: it signs an assertion when a
+credential is available and sends no `Authorization` header otherwise, instead
+of raising `AtlasRb::ConfigurationError`. Atlas serves `GET /reset` with
+`require_auth` skipped (env-gated), so the call no longer needs an acting nuid
+or a configured signer just to satisfy the client-side header builder — fixing
+test `before(:suite)` resets that run before any acting principal is set.
+
+`FaradayHelper#connection` gains an `auth:` keyword (`:required` default,
+`:optional`) to support this; every other endpoint stays strict and still
+raises on a missing credential.
+
 ## 1.4.0
 
 ### Removed — legacy `ATLAS_TOKEN` relay

data/Gemfile.lock

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

data/lib/atlas_rb/blob.rb

@@ -24,11 +24,15 @@ module AtlasRb
     #   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.
+    #   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.
     #
     # @example
     #   AtlasRb::Blob.find("b-321")
-    #   # => { "id" => "b-321", "original_filename" => "scan.pdf", ... }
+    #   # => { "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
@@ -82,33 +86,44 @@ module AtlasRb
     # @param idempotency_key [String, nil] optional UUID. A repeat call with
     #   the same key returns the originally-created Blob instead of creating
     #   a new one. See {AtlasRb::Work.create} for full semantics.
+    # @param expected_digest [String, nil] optional verify-on-ingest checksum,
+    #   `"<algorithm>:<hexvalue>"` (sha512/sha256/sha1/md5, e.g.
+    #   `"sha256:abc…"`). Atlas hashes the uploaded bytes **before** persisting
+    #   and raises {AtlasRb::FixityMismatchError} (HTTP 422) on a mismatch or an
+    #   unsupported algorithm — nothing is left behind on rejection.
     # @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 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"`.
+    # @return [Hash] the created `"blob"` payload, including its `"id"` and
+    #   `"digest"` (the recorded fixity digest, `"sha512:<hex>"`).
+    # @raise [AtlasRb::FixityMismatchError] if `expected_digest` was supplied and
+    #   the uploaded bytes did not match (or the algorithm is unsupported).
+    #
+    # @note Streams the file (FD closed deterministically); a multi-GB upload is
+    #   not buffered in memory. See {AtlasRb::FaradayHelper#with_file_part}.
     #
     # @example
     #   AtlasRb::Blob.create("w-789", "/tmp/upload.tmp", "final_thesis.pdf")
     #   # => { "id" => "b-321", "original_filename" => "final_thesis.pdf", ... }
     #
-    # @example Retry-safe bulk-deposit create
+    # @example Retry-safe bulk-deposit create with fixity verification
     #   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, on_behalf_of: nil)
-      payload = { work_id: id,
-                  original_filename: original_filename,
-                  binary: Faraday::Multipart::FilePart.new(File.open(blob_path),
-                                                          "application/octet-stream",
-                                                          File.basename(blob_path)) }
+    #                        idempotency_key: key, expected_digest: "sha256:#{sha}")
+    def self.create(id, blob_path, original_filename, expected_digest: nil,
+                    idempotency_key: nil, nuid: nil, on_behalf_of: nil)
+      with_file_part(blob_path) do |part|
+        payload = { work_id: id, original_filename: original_filename, binary: part }
+        payload[:expected_digest] = expected_digest if expected_digest
 
-      AtlasRb::Mash.new(JSON.parse(
-        multipart(nuid, on_behalf_of: on_behalf_of, idempotency_key: idempotency_key)
-          .post(ROUTE, payload)&.body
-      ))['blob']
+        AtlasRb::Mash.new(JSON.parse(
+          multipart(nuid, on_behalf_of: on_behalf_of, idempotency_key: idempotency_key)
+            .post(ROUTE, payload)&.body
+        ))['blob']
+      end
     end
 
     # Delete a Blob (the bytes *and* the metadata record).
@@ -136,23 +151,32 @@ module AtlasRb
     #
     # @param id [String] the Blob ID.
     # @param blob_path [String] path to the replacement binary on disk.
+    # @param expected_digest [String, nil] optional verify-on-ingest checksum,
+    #   `"<algorithm>:<hexvalue>"`. 422 ({AtlasRb::FixityMismatchError}) on mismatch.
     # @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 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.
+    # @return [Hash] the parsed JSON response from the patch (the updated
+    #   `"blob"`, with a refreshed `"digest"` for the new revision).
+    # @raise [AtlasRb::FixityMismatchError] if `expected_digest` was supplied and
+    #   the uploaded bytes did not match (or the algorithm is unsupported).
+    #
+    # @note Streams the file with the FD closed deterministically — see {.create}.
     #
     # @example
     #   AtlasRb::Blob.update("b-321", "/tmp/revised.pdf")
-    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, on_behalf_of: on_behalf_of).patch(ROUTE + id, payload)&.body
-      ))
+    def self.update(id, blob_path, expected_digest: nil, nuid: nil, on_behalf_of: nil)
+      with_file_part(blob_path) do |part|
+        payload = { binary: part }
+        payload[:expected_digest] = expected_digest if expected_digest
+
+        AtlasRb::Mash.new(JSON.parse(
+          multipart(nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id, payload)&.body
+        ))
+      end
     end
   end
 end

data/lib/atlas_rb/errors.rb

@@ -134,6 +134,41 @@ module AtlasRb
     end
   end
 
+  # Raised when Atlas rejects a binary upload's verify-on-ingest check with a
+  # `422` carrying a fixity discriminator — `fixity_mismatch` (the uploaded
+  # bytes don't match the supplied `expected_digest`) or
+  # `unsupported_digest_algorithm` (a malformed/unknown `expected_digest`).
+  # Fires on `POST /files`, `PATCH /files/:id`, and `PATCH /file_sets/:id`.
+  #
+  # The upload sibling of {ReparentError} / {LinkedMemberError}; same shape,
+  # same rationale — without it the `["blob"]` / `["file_set"]` unwrap would
+  # return `nil` on the 422 and discard the signal a migration needs to tell a
+  # corrupted transfer from a clean one. Atlas rejects *before* persisting, so
+  # nothing is left behind to clean up.
+  #
+  #   rescue AtlasRb::FixityMismatchError => e
+  #     # e.code == "fixity_mismatch": re-fetch the source, retry, or quarantine
+  #
+  # @note Authorization failures surface as {ForbiddenError} (HTTP 403).
+  class FixityMismatchError < Error
+    # @return [String, nil] the machine-readable error code from the envelope
+    #   (`"fixity_mismatch"` or `"unsupported_digest_algorithm"`).
+    attr_reader :code
+
+    # @return [String, nil] the rejected resource's ID, from the envelope (the
+    #   FileSet on the attach path; may be nil on `POST /files`).
+    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, or Compilation
   # request with an HTTP `403`, whose envelope is
   # `{ "error", "action", "subject" }`. Lets callers distinguish "you may

data/lib/atlas_rb/faraday_helper.rb

@@ -62,13 +62,20 @@ module AtlasRb
     #   `POST /works`, `POST /file_sets`, `POST /files`) to deduplicate replays
     #   against the originally-created resource. Generated by the caller —
     #   this gem does not mint keys.
+    # @param auth [:required, :optional] auth strictness. `:required` (default)
+    #   raises {AtlasRb::ConfigurationError} when no credential can be built —
+    #   the right behaviour for every endpoint behind `require_auth`. `:optional`
+    #   signs when it can but sends no `Authorization` header otherwise, for the
+    #   handful of endpoints Atlas serves with auth skipped (currently only
+    #   `GET /reset`).
     # @return [Faraday::Connection] a connection that follows redirects and
     #   uses Faraday's default adapter.
     #
     # @example Fetching a community
     #   AtlasRb::Community.connection({}).get('/communities/abc123')
-    def connection(params, nuid=nil, on_behalf_of: nil, idempotency_key: nil)
-      headers = auth_headers(nuid, on_behalf_of).merge("Content-Type" => "application/json")
+    def connection(params, nuid=nil, on_behalf_of: nil, idempotency_key: nil, auth: :required)
+      headers = auth_headers(nuid, on_behalf_of, optional: auth == :optional)
+                .merge("Content-Type" => "application/json")
       headers["Idempotency-Key"] = idempotency_key if idempotency_key
 
       Faraday.new(
@@ -117,11 +124,38 @@ module AtlasRb
         headers: headers
       ) do |f|
         f.use AtlasRb::Middleware::RaiseOnStaleResource
+        # Translate Atlas's verify-on-ingest 422 (fixity_mismatch /
+        # unsupported_digest_algorithm) into a typed FixityMismatchError —
+        # the JSON-connection path already carries this; uploads need it too.
+        f.use AtlasRb::Middleware::RaiseOnResourceError
         f.request :multipart
         f.request :url_encoded
       end
     end
 
+    # Build a streaming multipart FilePart for `blob_path`, run the request
+    # inside the block, and close the underlying File handle deterministically
+    # afterward (on success or exception). The handle must stay open *during*
+    # the request — Faraday reads it while posting — so it can't be closed
+    # before the call; an unclosed handle leaks a descriptor per upload, which
+    # exhausts FDs across a TB migration of millions of files.
+    #
+    # Streaming/memory: faraday-multipart wraps the part in a streaming
+    # CompositeReadIO and the default net_http adapter sends it via
+    # `request.body_stream` (Content-Length known), so a multi-GB file uploads
+    # without being buffered into a String in memory. (Swapping the host app's
+    # default Faraday adapter to a buffering one would regress this.)
+    #
+    # @param blob_path [String] path to the binary on disk.
+    # @yieldparam part [Faraday::Multipart::FilePart] the streaming part.
+    # @return the block's return value.
+    def with_file_part(blob_path)
+      File.open(blob_path, "rb") do |io|
+        yield Faraday::Multipart::FilePart.new(io, "application/octet-stream",
+                                               File.basename(blob_path))
+      end
+    end
+
     # Build a Faraday connection authenticated as the Atlas `:system`
     # fixture for system-context calls (SSO user provisioning, etc.).
     #
@@ -167,18 +201,26 @@ module AtlasRb
     # Precedence: ATLAS_JWT (BYO-JWT) > relay-signing. The acting nuid /
     # on_behalf_of fall through to the configured `default_nuid` /
     # `default_on_behalf_of` callables here, once, for whichever mode applies.
-    # Raises {ConfigurationError} when neither credential is configured.
-    def auth_headers(nuid, on_behalf_of)
+    #
+    # Raises {ConfigurationError} when no credential can be built — unless
+    # `optional:` is set, in which case it returns no auth headers instead. That
+    # is only for endpoints Atlas serves with `require_auth` skipped (`GET
+    # /reset`); every normal endpoint leaves `optional` false so a
+    # misconfiguration fails loudly rather than silently going unauthenticated.
+    def auth_headers(nuid, on_behalf_of, optional: false)
       jwt = ENV.fetch("ATLAS_JWT", nil)
       return { "Authorization" => "Bearer #{jwt}" } if jwt
 
       nuid         ||= AtlasRb.config.default_nuid&.call
       on_behalf_of ||= AtlasRb.config.default_on_behalf_of&.call
 
-      signed_relay_headers(nuid, on_behalf_of) ||
-        raise(ConfigurationError,
-              "atlas_rb: no auth configured — set ATLAS_JWT or " \
-              "AtlasRb.config.assertion_signing_key (with an acting nuid to sign)")
+      headers = signed_relay_headers(nuid, on_behalf_of)
+      return headers if headers
+      return {} if optional
+
+      raise(ConfigurationError,
+            "atlas_rb: no auth configured — set ATLAS_JWT or " \
+            "AtlasRb.config.assertion_signing_key (with an acting nuid to sign)")
     end
 
     # A signed-assertion Authorization header (sub = acting nuid), or nil when

data/lib/atlas_rb/file_set.rb

@@ -98,30 +98,52 @@ module AtlasRb
     # Attach (or replace) the binary content backing this FileSet.
     #
     # The body is uploaded as `application/octet-stream` regardless of the
-    # file's true type — Atlas inspects the content server-side. To upload
-    # a binary blob *plus* an original filename, use {Blob.create} directly
-    # against the underlying `/files/` endpoint.
+    # file's true type — Atlas inspects the content server-side. This is the
+    # ordered/classified-slot attach used after {.create} cuts the slot.
     #
     # @param id [String] the FileSet ID.
     # @param blob_path [String] path to the binary file on disk.
+    # @param original_filename [String, nil] the user-facing filename Atlas
+    #   should record on the resulting Blob (e.g. the v1 `"page-0001.tif"`);
+    #   preserved separately from the temp `File.basename(blob_path)`.
+    # @param expected_digest [String, nil] optional verify-on-ingest checksum,
+    #   `"<algorithm>:<hexvalue>"`. 422 ({AtlasRb::FixityMismatchError}) on mismatch.
+    # @param idempotency_key [String, nil] optional UUID. A repeat call with the
+    #   same key returns the FileSet with its already-attached Blob **without
+    #   recopying the bytes** (and 410 if it was tombstoned in the interim). See
+    #   {AtlasRb::Work.create} for full semantics.
     # @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 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.
+    # @return [Hash] the parsed JSON response from the patch (the `"file_set"`).
+    # @raise [AtlasRb::FixityMismatchError] if `expected_digest` was supplied and
+    #   the uploaded bytes did not match (or the algorithm is unsupported).
+    #
+    # @note Streams the file with the FD closed deterministically — see
+    #   {Blob.create} / {AtlasRb::FaradayHelper#with_file_part}.
     #
     # @example
     #   AtlasRb::FileSet.update("fs-001", "/tmp/article.pdf")
-    def self.update(id, blob_path, nuid: nil, on_behalf_of: nil)
-      # Need to figure out blob vs XML
-      payload = { binary: Faraday::Multipart::FilePart.new(File.open(blob_path),
-                                                          "application/octet-stream",
-                                                          File.basename(blob_path)) }
-      AtlasRb::Mash.new(JSON.parse(
-        multipart(nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id, payload)&.body
-      ))
+    #
+    # @example Resumable, filename-preserving migration attach
+    #   AtlasRb::FileSet.update(page["id"], "/tmp/p1.tif",
+    #                           original_filename: "page-0001.tif",
+    #                           idempotency_key: key)
+    def self.update(id, blob_path, original_filename: nil, expected_digest: nil,
+                    idempotency_key: nil, nuid: nil, on_behalf_of: nil)
+      with_file_part(blob_path) do |part|
+        payload = { binary: part }
+        payload[:original_filename] = original_filename if original_filename
+        payload[:expected_digest]   = expected_digest   if expected_digest
+
+        AtlasRb::Mash.new(JSON.parse(
+          multipart(nuid, on_behalf_of: on_behalf_of, idempotency_key: idempotency_key)
+            .patch(ROUTE + id, payload)&.body
+        ))
+      end
     end
 
     # Persist the per-page IIIF image-service pointer on a FileSet.

data/lib/atlas_rb/middleware/raise_on_resource_error.rb

@@ -15,39 +15,53 @@ module AtlasRb
     # {RaiseOnStaleResource}.
     #
     # It is intentionally narrow — it only fires on the re-parent
-    # (`.../parent`) and linked-member (`.../linked_members...`) write paths
-    # and the Compilation surface (`/compilations...`), and only on
-    # `403` / `422` bodies carrying an `error` discriminator.
+    # (`.../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
+    # 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.
     #
     # Mapping:
-    # - `403` (any covered path) → {AtlasRb::ForbiddenError} (`error`/`action`/`subject`)
+    # - `403` on a re-parent/linked/Compilation path → {AtlasRb::ForbiddenError}
     # - `422` on `.../parent` → {AtlasRb::ReparentError} (`error`/`resource_id`)
     # - `422` on `.../linked_members...` → {AtlasRb::LinkedMemberError}
     # - `422` on `/compilations...` → {AtlasRb::CompilationError}
+    # - `422` + a fixity discriminator on `/files...` / `/file_sets...` →
+    #   {AtlasRb::FixityMismatchError}
     class RaiseOnResourceError < Faraday::Middleware
+      # Upload-path `422` discriminators this middleware translates; any other
+      # `error` on those paths passes through (Atlas owns these as a wire contract).
+      FIXITY_CODES = %w[fixity_mismatch unsupported_digest_algorithm].freeze
+
       # @param env [Faraday::Env] the completed response environment.
-      # @raise [AtlasRb::ForbiddenError] on a 403 to a covered path.
+      # @raise [AtlasRb::ForbiddenError] on a 403 to a re-parent/linked/Compilation 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::FixityMismatchError] on a 422 + fixity discriminator to an upload path.
       # @return [void]
       def on_complete(env)
-        return unless env.status == 403 || env.status == 422
+        return unless [403, 422].include?(env.status)
 
         path        = env.url&.path.to_s
         reparent    = path.end_with?("/parent")
         linked      = path.include?("/linked_members")
         compilation = path.start_with?("/compilations")
-        return unless reparent || linked || compilation
+        upload      = path.start_with?("/files") || path.start_with?("/file_sets")
+        return unless reparent || linked || compilation || 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
+
           raise AtlasRb::ForbiddenError.new(
             body["message"] || "Atlas refused the request",
             code: body["error"],
@@ -66,12 +80,18 @@ module AtlasRb
             code: body["error"],
             resource_id: body["resource_id"]
           )
-        else
+        elsif compilation
           raise AtlasRb::CompilationError.new(
             body["message"] || "Atlas rejected the compilation write",
             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)",
+            code: body["error"],
+            resource_id: body["resource_id"]
+          )
         end
       end
 

data/lib/atlas_rb.rb

@@ -123,20 +123,23 @@ module AtlasRb
 
     # Reset the connected Atlas instance to a clean state.
     #
-    # @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). Atlas's
-    #   `MaintenanceController#reset` runs through the standard `require_auth`
-    #   filter like any other endpoint.
-    # @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.
+    # Atlas serves `GET /reset` with `require_auth` **skipped** (it is env-gated,
+    # not principal-gated), so this call uses **optional auth**: it signs an
+    # assertion when a credential is available, and sends no `Authorization`
+    # header otherwise — never raising {AtlasRb::ConfigurationError} for lack of
+    # one. That lets a test `before(:suite)` reset before any acting nuid is set.
+    #
+    # @param nuid [String, nil] optional acting user's NUID. When a signing key
+    #   is configured it is signed into the assertion `sub`; otherwise it is
+    #   unused (Atlas ignores it on this endpoint). Mostly here for symmetry.
+    # @param on_behalf_of [String, nil] optional NUID. Falls through to
+    #   {AtlasRb.config}.default_on_behalf_of when omitted.
     # @return [String, nil] the raw response body from `GET /reset`.
     #
     # @example
-    #   AtlasRb::Reset.clean(nuid: "000000000")
+    #   AtlasRb::Reset.clean
     def self.clean(nuid: nil, on_behalf_of: nil)
-      connection({}, nuid, on_behalf_of: on_behalf_of).get("/reset")&.body
+      connection({}, nuid, on_behalf_of: on_behalf_of, auth: :optional).get("/reset")&.body
     end
   end
 end

metadata

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