atlas_rb 1.3.6 → 1.3.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e15c24fddbec1fba3da8aef5e85d769ddf4861e9bccad136957b342515e34dab
-  data.tar.gz: 2044a925120234a5e3fa1553fc3fc4ec2b3dad05c4215af58697c157fc84cdff
+  metadata.gz: 2edc49cf965b1b1489e639b3ae8fd0413d036fe81b07a83c48f851ed975da1a0
+  data.tar.gz: ba269fae419aa13545e9e5c664e7c1b66282bcb4ff9c8e238d1333e2c51f444e
 SHA512:
-  metadata.gz: a62880ec96483584dc82cacd3a186822ec7af2f64893ede345ccc73f071462106f21b753579dcb6eb9c391018860f828881d4fa7cbe191da4f3e8a76b27d6574
-  data.tar.gz: b4f66124c5b5c51e550a13b3c60a01a4ce9d6efaa771577be41d46d8f4172967d5124441db1a2a55c44717b92898175643c35d74afe550405a5d57a75fe73767
+  metadata.gz: 5ed3a6c2f5d1934a25654fd0130e4f8bc8cf41e00530dfee5b333d4e09bdf9caacdd25f88eecb88426bbf9ba3a61f870faf2b9fece2fb13b7a066a24818bf4e8
+  data.tar.gz: ea5ddec2aea0f36cfbebc2150035517857beb24a015b19deade470507604d771bd8b9bd50151d8260e425de355bbe7af502e7dd284819207260a5066cad814ff

data/.version

@@ -1 +1 @@
-1.3.6
+1.3.7

data/Gemfile.lock

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

data/README.md

@@ -25,12 +25,13 @@ Then `bundle install`, or install standalone with `gem install atlas_rb`.
 
 ### Environment variables
 
-Every regular-path request reads two environment variables:
+Every regular-path request reads these environment variables:
 
 | Variable      | Purpose                                                       |
 |---------------|---------------------------------------------------------------|
 | `ATLAS_URL`   | Base URL of the Atlas API (e.g. `https://atlas.example.edu`). |
-| `ATLAS_TOKEN` | Bearer token used in the `Authorization` header.              |
+| `ATLAS_TOKEN` | Cerberus-relay bearer token used in the `Authorization` header (relay mode). |
+| `ATLAS_JWT`   | *Optional.* A personal-access JWT minted by Atlas's `POST /nuid`. When set, switches to [BYO-JWT mode](#byo-jwt-mode-standalone-scripts). |
 
 ```ruby
 ENV["ATLAS_URL"]   = "https://atlas.example.edu"
@@ -76,6 +77,35 @@ AtlasRb::Work.find("w-789", nuid: "X")
 If neither the call site nor the registered default supplies a value,
 no header is sent (legacy bearer-only path preserved).
 
+### BYO-JWT mode (standalone scripts)
+
+The relay path above is what a Rails host (Cerberus) uses: a shared
+`ATLAS_TOKEN` plus a `User: NUID` header naming the acting person. For
+**standalone scripts** — a librarian automating their own workflow — Atlas
+also accepts a *personal-access JWT*, minted by Cerberus post-SSO via
+`POST /nuid` and handed to the user. Set it as `ATLAS_JWT` and the gem
+switches transport modes:
+
+```ruby
+ENV["ATLAS_URL"] = "https://atlas.example.edu"
+ENV["ATLAS_JWT"] = "<token minted for you by Cerberus>"   # 1-week TTL
+
+# Identity is carried by the token — no nuid plumbing needed:
+AtlasRb::Work.find("w-789")
+```
+
+In BYO-JWT mode:
+
+- The JWT is the bearer, **taking precedence over `ATLAS_TOKEN`**.
+- **No `User:` header is sent** — the token already encodes the acting
+  user, and any `nuid:` kwarg or `default_nuid` is ignored on this path.
+- **`On-Behalf-Of` is suppressed** — acting-as is a Cerberus-relay-only
+  concept; Atlas rejects it on the JWT path with a 403. Any `on_behalf_of:`
+  kwarg or `default_on_behalf_of` is dropped.
+
+To rotate or revoke, ask Cerberus to regenerate your token (Atlas rotates
+the user's `jti`, invalidating outstanding tokens — single-token model).
+
 ### System-path credentials
 
 Calls under `AtlasRb::System::*` (currently just SSO user provisioning)

data/lib/atlas_rb/faraday_helper.rb

@@ -3,18 +3,32 @@
 module AtlasRb
   # HTTP transport helpers shared by every resource class.
   #
-  # Every Atlas request reads two environment variables:
+  # Every Atlas request reads these environment variables:
   #
   # - `ATLAS_URL`   — base URL of the Atlas API (e.g. `https://atlas.example.edu`).
-  # - `ATLAS_TOKEN` — bearer token used in the `Authorization` header.
+  # - `ATLAS_TOKEN` — Cerberus-relay bearer token used in the `Authorization`
+  #   header on the default (relay) path.
+  # - `ATLAS_JWT`   — *optional* personal-access JWT (minted by Atlas's
+  #   `POST /nuid`, Cerberus-delegated post-SSO). When set, it switches the
+  #   transport into **bring-your-own-JWT mode** (see below).
   #
-  # Most calls also identify the acting user via a `User: NUID <nuid>` header,
-  # and optionally an `On-Behalf-Of: NUID <nuid>` header for acting-as / view-as
-  # flows. When `nuid` / `on_behalf_of` are omitted (positional arg `nil`,
-  # kwarg `nil`), the helper falls through to {AtlasRb.config}'s
+  # ## Two transport modes
+  #
+  # **Relay mode (default, `ATLAS_JWT` unset).** Authenticates with
+  # `ATLAS_TOKEN` and identifies the acting user via a `User: NUID <nuid>`
+  # header, optionally an `On-Behalf-Of: NUID <nuid>` header for acting-as /
+  # view-as flows. When `nuid` / `on_behalf_of` are omitted (positional arg
+  # `nil`, kwarg `nil`), the helper falls through to {AtlasRb.config}'s
   # `default_nuid` / `default_on_behalf_of` callables — host applications wire
   # those up to their request-scoped `Current.*` source. Caller-passed values
-  # always win over the configured defaults.
+  # always win over the configured defaults. This is the path Cerberus uses.
+  #
+  # **BYO-JWT mode (`ATLAS_JWT` set).** Authenticates with the JWT, which
+  # already encodes the acting user — so **no `User:` header is sent**, and
+  # `On-Behalf-Of` is **suppressed** (Atlas rejects acting-as on the JWT path
+  # with a 403; acting-as is a relay-only concept). `ATLAS_JWT` takes
+  # precedence over `ATLAS_TOKEN`. This is the standalone-script path: a
+  # librarian exports their minted token and runs headless against the API.
   #
   # The module is mixed in via `extend`, so its methods become class methods on
   # the host (e.g. `AtlasRb::Work.connection({})`).
@@ -43,15 +57,7 @@ module AtlasRb
     # @example Fetching a community
     #   AtlasRb::Community.connection({}).get('/communities/abc123')
     def connection(params, nuid=nil, on_behalf_of: nil, idempotency_key: nil)
-      nuid         ||= AtlasRb.config.default_nuid&.call
-      on_behalf_of ||= AtlasRb.config.default_on_behalf_of&.call
-
-      headers = {
-        "Content-Type" => "application/json",
-        "Authorization" => "Bearer #{ENV.fetch("ATLAS_TOKEN", nil)}"
-      }
-      headers["User"]            = "NUID #{nuid}" if nuid
-      headers["On-Behalf-Of"]    = "NUID #{on_behalf_of}" if on_behalf_of
+      headers = auth_headers(nuid, on_behalf_of).merge("Content-Type" => "application/json")
       headers["Idempotency-Key"] = idempotency_key if idempotency_key
 
       Faraday.new(
@@ -91,14 +97,7 @@ module AtlasRb
     #   }
     #   AtlasRb::Blob.multipart.post('/files/', payload)
     def multipart(nuid=nil, on_behalf_of: nil, idempotency_key: nil)
-      nuid         ||= AtlasRb.config.default_nuid&.call
-      on_behalf_of ||= AtlasRb.config.default_on_behalf_of&.call
-
-      headers = {
-        "Authorization" => "Bearer #{ENV.fetch("ATLAS_TOKEN", nil)}"
-      }
-      headers["User"]            = "NUID #{nuid}" if nuid
-      headers["On-Behalf-Of"]    = "NUID #{on_behalf_of}" if on_behalf_of
+      headers = auth_headers(nuid, on_behalf_of)
       headers["Idempotency-Key"] = idempotency_key if idempotency_key
 
       Faraday.new(
@@ -149,5 +148,33 @@ module AtlasRb
         f.adapter Faraday.default_adapter
       end
     end
+
+    private
+
+    # Build the auth + identity headers shared by {#connection} and
+    # {#multipart}. BYO-JWT mode (`ATLAS_JWT` set) sends only the bearer — the
+    # token carries the acting user, so no `User:` header, and `On-Behalf-Of`
+    # is suppressed (Atlas 403s acting-as on the JWT path). Relay mode uses
+    # `ATLAS_TOKEN` and names the acting user, falling through to the
+    # configured `default_nuid` / `default_on_behalf_of` callables when the
+    # caller passes neither.
+    def auth_headers(nuid, on_behalf_of)
+      jwt = ENV.fetch("ATLAS_JWT", nil)
+      return { "Authorization" => "Bearer #{jwt}" } if jwt
+
+      relay_headers(nuid, on_behalf_of)
+    end
+
+    # Relay-path headers: ATLAS_TOKEN bearer + the acting-user identity headers,
+    # falling through to the configured default_nuid / default_on_behalf_of.
+    def relay_headers(nuid, on_behalf_of)
+      nuid         ||= AtlasRb.config.default_nuid&.call
+      on_behalf_of ||= AtlasRb.config.default_on_behalf_of&.call
+
+      headers = { "Authorization" => "Bearer #{ENV.fetch("ATLAS_TOKEN", nil)}" }
+      headers["User"]         = "NUID #{nuid}" if nuid
+      headers["On-Behalf-Of"] = "NUID #{on_behalf_of}" if on_behalf_of
+      headers
+    end
   end
 end

data/lib/atlas_rb.rb

@@ -32,10 +32,15 @@ require_relative "atlas_rb/audit_event"
 #
 # ## Configuration
 #
-# Two environment variables drive every request:
+# Environment variables drive every request:
 #
 # - `ATLAS_URL`   — base URL of the Atlas API (e.g. `https://atlas.example.edu`).
-# - `ATLAS_TOKEN` — bearer token sent in the `Authorization` header.
+# - `ATLAS_TOKEN` — Cerberus-relay bearer token sent in the `Authorization`
+#   header on the default path.
+# - `ATLAS_JWT`   — optional personal-access JWT (minted by Atlas's
+#   `POST /nuid`). When set, the transport runs in bring-your-own-JWT mode:
+#   the JWT is the bearer and no `User:` / `On-Behalf-Of:` headers are sent.
+#   See {AtlasRb::FaradayHelper} for the mode semantics.
 #
 # {AtlasRb::Authentication} additionally accepts an NUID (Northeastern
 # University ID) which is forwarded in a `User: NUID <nuid>` header so the

metadata

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