atlas_rb 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31c36891a34eef17727397e17017db5eb1acea6cdfae4dfbba76b93e6f32954a
-  data.tar.gz: 3871ca6703afa2ecccf780f089b22e8ff6fdcbcdaf5aaafb82e51bbf606e95a1
+  metadata.gz: 7e6020b2b0ed84ff61541cdcc4ac4ef2634a4ee4573540c5e10888cab26ec2df
+  data.tar.gz: e18077da93ef29644e95cd94bc231bd42497d7bc21e05b5f97cd27df92346a6f
 SHA512:
-  metadata.gz: 84f906c748bd98acb961eb403950d98e1c46be9084ae21fde55b949bc1af6f2bc9f72c567c0bb826b854209b75f51d437196d7e7d0b1031d9f2497e132d305f8
-  data.tar.gz: bac7488013b6d12db98806447405c27ae52d4fed86608c2fc96f2180cea48a931d0d43b1421b914de3218a742fb5bb53cfa46dc9d59f41ee3a92670571a52aee
+  metadata.gz: '068bedce232453c430a4e55c3f252f24a11b3710bc6870cc3061f9d3ec183c39600a5c814147d26ec054684afa5e3a7bc07ffc7d98a676b63904e5a11fc36343'
+  data.tar.gz: 546dd7050f56a82cd66f54bc38d0d003cc1099f1b998b64255a06ba31ee54d9fbb84a799d56bc46a635b68dd97bb9b87abbb5a94f09bcf2c539220bbb40278c8

data/.version

@@ -1 +1 @@
-1.4.0
+1.5.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.5.0)
       faraday (~> 2.7)
       faraday-follow_redirects (~> 0.3.0)
       faraday-multipart (~> 1)

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(
@@ -167,18 +174,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.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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - David Cliff