atlas_rb 1.3.6 → 1.3.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e15c24fddbec1fba3da8aef5e85d769ddf4861e9bccad136957b342515e34dab
-  data.tar.gz: 2044a925120234a5e3fa1553fc3fc4ec2b3dad05c4215af58697c157fc84cdff
+  metadata.gz: 7f2a9947778ab6d15d96514cdeb949a82ffce8023f6fe0aeee39bfce1c198ce3
+  data.tar.gz: 864fd37a55f2275417dc5f45f1c60466b41baefc3351ed6f712c7f7dfdcda28d
 SHA512:
-  metadata.gz: a62880ec96483584dc82cacd3a186822ec7af2f64893ede345ccc73f071462106f21b753579dcb6eb9c391018860f828881d4fa7cbe191da4f3e8a76b27d6574
-  data.tar.gz: b4f66124c5b5c51e550a13b3c60a01a4ce9d6efaa771577be41d46d8f4172967d5124441db1a2a55c44717b92898175643c35d74afe550405a5d57a75fe73767
+  metadata.gz: afef167fa0ed86fb7ebd4d28fe693fb41fe20f2ade2e9b96ce0f1109aec7340038b4a9c9425cf53d3463bc346aa9cf4fa90fd012cf3ad2636dad42784d040fa2
+  data.tar.gz: aec3edc7ce6cb88a6d9421b449e3420521073bd20083c86afa451d74c74d903c5dc222a85f0bff2bd2a87c094f06fe3066bae7f4b814fd367a6c0640e5a6800e

data/.version

@@ -1 +1 @@
-1.3.6
+1.3.8

data/Gemfile.lock

@@ -1,15 +1,17 @@
 PATH
   remote: .
   specs:
-    atlas_rb (1.3.6)
+    atlas_rb (1.3.8)
       faraday (~> 2.7)
       faraday-follow_redirects (~> 0.3.0)
       faraday-multipart (~> 1)
       hashie (~> 5.0)
+      jwt (~> 2.7)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    base64 (0.3.0)
     diff-lcs (1.6.1)
     faraday (2.14.2)
       faraday-net_http (>= 2.0, < 3.5)
@@ -24,6 +26,8 @@ GEM
     hashie (5.1.0)
       logger
     json (2.19.9)
+    jwt (2.10.3)
+      base64
     logger (1.7.0)
     multipart-post (2.4.1)
     net-http (0.9.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,68 @@ 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).
+
+### Relay-signing mode (the `ATLAS_TOKEN` replacement)
+
+The default relay authenticates with the shared `ATLAS_TOKEN` and *asserts* the
+acting user via a `User: NUID` header. Relay-signing replaces that with a
+**proven** identity: the relay **signs** a short-lived assertion with its own
+private key (`iss=cerberus`, `aud=atlas`, `sub` = the acting nuid, ES256), which
+Atlas verifies against the matching public key. No shared secret, no asserted
+header.
+
+Configure a signing key (and the `kid` Atlas indexes its public key by) — value
+or callable, so a Rails host reads it from credentials at request time:
+
+```ruby
+AtlasRb.configure do |config|
+  config.assertion_signing_key = -> { Rails.application.credentials.cerberus_signing_key }
+  config.assertion_signing_kid = -> { Rails.application.credentials.cerberus_signing_kid }
+end
+```
+
+When a signing key is configured, the regular relay (`connection` / `multipart`)
+signs instead of sending `ATLAS_TOKEN` + `User:`. Otherwise it behaves exactly as
+before — so signing **coexists with `ATLAS_TOKEN` during cutover** (turn it on by
+configuring the key; roll back by clearing it).
+
+Two carve-outs keep the boundaries safe:
+
+- **Acting-as auto-falls-back to the `ATLAS_TOKEN` relay.** An `on_behalf_of`
+  request is *not* signed — Atlas rejects `On-Behalf-Of` on the assertion path
+  (403) until a signed `obo` claim ships, so the gem keeps acting-as on the
+  legacy relay rather than letting it 403.
+- **`ATLAS_JWT` still wins.** A personal token (BYO-JWT) takes precedence over
+  relay-signing.
+
 ### System-path credentials
 
 Calls under `AtlasRb::System::*` (currently just SSO user provisioning)

data/lib/atlas_rb/configuration.rb

@@ -44,5 +44,28 @@ module AtlasRb
     # @return [Proc, nil] callable returning the on-behalf-of NUID, or nil
     #   to send no `On-Behalf-Of:` header.
     attr_accessor :default_on_behalf_of
+
+    # Relay signing (the cerberus_token replacement). When set, the regular
+    # relay path *signs* a short-lived assertion (ES256, `sub` = acting nuid)
+    # instead of sending `ATLAS_TOKEN` + a `User:` header — identity becomes
+    # proven, not asserted. Leave nil (the default) to keep the legacy relay.
+    #
+    # Accepts either a value or a callable (resolved per request, so a Rails
+    # host can read it from request-scoped state / credentials). The value may
+    # be a PEM string or an `OpenSSL::PKey`; a PEM is parsed for you.
+    #
+    # @example Rails host (initializer), reading the EC private key from credentials
+    #   AtlasRb.configure do |config|
+    #     config.assertion_signing_key = -> { Rails.application.credentials.cerberus_signing_key }
+    #     config.assertion_signing_kid = -> { Rails.application.credentials.cerberus_signing_kid }
+    #   end
+    #
+    # @return [String, OpenSSL::PKey, Proc, nil] EC private key (PEM/key/callable), or nil.
+    attr_accessor :assertion_signing_key
+
+    # @return [String, Proc, nil] the `kid` stamped in the assertion header so
+    #   Atlas selects the matching public key. Value or callable. Required when
+    #   {#assertion_signing_key} is set.
+    attr_accessor :assertion_signing_kid
   end
 end

data/lib/atlas_rb/faraday_helper.rb

@@ -3,22 +3,54 @@
 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.
+  #
+  # **Relay-signing mode ({AtlasRb.config#assertion_signing_key} set).** The
+  # cryptographic replacement for the `ATLAS_TOKEN` relay: instead of a shared
+  # secret + an asserted `User:` header, the regular relay path **signs** a
+  # short-lived assertion (ES256, `iss=cerberus`, `aud=atlas`, `sub` = the
+  # acting nuid) with Cerberus's private key — Atlas verifies it with the
+  # public key. No `User:` header; identity is the proven `sub`. **Acting-as
+  # auto-falls-back to the legacy relay**: an `on_behalf_of` request is NOT
+  # signed (Atlas 403s `On-Behalf-Of` on the assertion path until a signed
+  # `obo` claim ships), so the boundary cannot be violated by a caller. Off
+  # unless a signing key is configured (so it coexists with `ATLAS_TOKEN`
+  # during cutover). `ATLAS_JWT`, if set, still wins over signing.
   #
   # The module is mixed in via `extend`, so its methods become class methods on
   # the host (e.g. `AtlasRb::Work.connection({})`).
   module FaradayHelper
+    # Wire contract Atlas enforces for relay-signing assertions (see Atlas
+    # ApplicationController#verify_cerberus_assertion). iss/aud are fixed; the
+    # short TTL bounds replay (Atlas allows 30s leeway on exp).
+    ASSERTION_ISSUER   = "cerberus"
+    ASSERTION_AUDIENCE = "atlas"
+    ASSERTION_TTL      = 30 # seconds
     # Build a JSON-content Faraday connection to the Atlas API.
     #
     # @param params [Hash] query-string / body params to attach to the request.
@@ -43,15 +75,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 +115,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 +166,80 @@ module AtlasRb
         f.adapter Faraday.default_adapter
       end
     end
+
+    private
+
+    # Build the auth + identity headers shared by {#connection} and {#multipart}.
+    # Precedence: ATLAS_JWT (BYO-JWT) > relay-signing > ATLAS_TOKEN relay. The
+    # acting nuid / on_behalf_of fall through to the configured `default_nuid` /
+    # `default_on_behalf_of` callables here, once, for whichever mode applies.
+    def auth_headers(nuid, on_behalf_of)
+      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) || relay_headers(nuid, on_behalf_of)
+    end
+
+    # A signed-assertion Authorization header (sub = acting nuid), or nil to
+    # defer to the legacy relay. nil when signing isn't configured, there is no
+    # acting nuid to put in `sub`, or this is an acting-as request — On-Behalf-Of
+    # stays on the cerberus_token relay (Atlas 403s it on the assertion path),
+    # so the boundary can't be violated by a caller.
+    def signed_relay_headers(nuid, on_behalf_of)
+      return nil unless nuid && on_behalf_of.nil?
+
+      key = assertion_signing_key
+      return nil unless key
+
+      { "Authorization" => "Bearer #{signed_assertion(nuid.to_s, key)}" }
+    end
+
+    # Legacy relay headers: ATLAS_TOKEN bearer + acting-user identity headers.
+    # `nuid` / `on_behalf_of` are already resolved by {#auth_headers}.
+    def relay_headers(nuid, on_behalf_of)
+      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
+
+    # Mint a Cerberus relay assertion for `nuid`, signed ES256 with `key`. The
+    # `kid` header tells Atlas which public key to verify against; iss/aud are
+    # the fixed contract; the short TTL bounds replay; `jti` is forward-compat
+    # for an Atlas-side one-time cache.
+    def signed_assertion(nuid, key)
+      now = Time.now.to_i
+      payload = {
+        "iss" => ASSERTION_ISSUER,
+        "aud" => ASSERTION_AUDIENCE,
+        "sub" => nuid,
+        "iat" => now,
+        "exp" => now + ASSERTION_TTL,
+        "jti" => SecureRandom.uuid
+      }
+      JWT.encode(payload, key, "ES256", { kid: assertion_signing_kid })
+    end
+
+    # Resolve the configured signing key to an OpenSSL::PKey, or nil if signing
+    # is not configured. Accepts a callable (resolved per request), a PEM
+    # string (parsed), or an already-built key.
+    def assertion_signing_key
+      raw = config_value(AtlasRb.config.assertion_signing_key)
+      return nil if raw.nil?
+
+      raw.is_a?(OpenSSL::PKey::PKey) ? raw : OpenSSL::PKey.read(raw)
+    end
+
+    def assertion_signing_kid
+      config_value(AtlasRb.config.assertion_signing_kid)
+    end
+
+    # Config slots may hold a value or a callable resolved at request time.
+    def config_value(value)
+      value.respond_to?(:call) ? value.call : value
+    end
   end
 end

data/lib/atlas_rb.rb

@@ -3,6 +3,9 @@
 require "faraday"
 require "faraday/multipart"
 require "faraday/follow_redirects"
+require "jwt"
+require "openssl"
+require "securerandom"
 require_relative "atlas_rb/version"
 require_relative "atlas_rb/errors"
 require_relative "atlas_rb/configuration"
@@ -32,10 +35,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.8
 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
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
 - !ruby/object:Gem::Dependency
   name: faraday-multipart
   requirement: !ruby/object:Gem::Requirement