atlas_rb 1.3.7 → 1.3.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2edc49cf965b1b1489e639b3ae8fd0413d036fe81b07a83c48f851ed975da1a0
-  data.tar.gz: ba269fae419aa13545e9e5c664e7c1b66282bcb4ff9c8e238d1333e2c51f444e
+  metadata.gz: cf2f8c7f9ef316468a2544efe2f4471c23c547ae36d50b9abfee2efd03db38c8
+  data.tar.gz: 9da90557d04f84ddad26c05b6c50eab0d9a7378ccf57fbb37ba6b3e7e4355cd4
 SHA512:
-  metadata.gz: 5ed3a6c2f5d1934a25654fd0130e4f8bc8cf41e00530dfee5b333d4e09bdf9caacdd25f88eecb88426bbf9ba3a61f870faf2b9fece2fb13b7a066a24818bf4e8
-  data.tar.gz: ea5ddec2aea0f36cfbebc2150035517857beb24a015b19deade470507604d771bd8b9bd50151d8260e425de355bbe7af502e7dd284819207260a5066cad814ff
+  metadata.gz: 640d113ae6693aacb7d7d2a943634561281ebb5324d7db5284429673a48ff1ae9cbedda4d55b058710c497573e4c7c379dee18b08119925c5a0e7e73f7105088
+  data.tar.gz: 8e7209552ebc5b7b8db138809bd89ef077ac282342c39d483f1c125f68d757c155ff12865f7a1c24bb65040bf287eb13c7ecd81549117cb0cf01d3a1bf58cc79

data/.version

@@ -1 +1 @@
-1.3.7
+1.3.9

data/Gemfile.lock

@@ -1,15 +1,17 @@
 PATH
   remote: .
   specs:
-    atlas_rb (1.3.7)
+    atlas_rb (1.3.9)
       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

@@ -106,6 +106,41 @@ In BYO-JWT mode:
 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 things to know:
+
+- **Acting-as rides a signed `obo` claim.** An `on_behalf_of` request is signed
+  with `sub` = the operator and `obo` = the target, inside the signature — so the
+  target can't be forged onto a stolen assertion, and no `On-Behalf-Of` header is
+  sent. Atlas admin-gates the operator and ignores any header obo on this path.
+  (Requires an Atlas on the signed-obo release; older Atlas would silently ignore
+  the claim — don't enable signing for acting-as traffic until Atlas is current.)
+- **`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

@@ -30,9 +30,31 @@ module AtlasRb
   # 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
+  # rides a signed `obo` claim** inside the assertion (the target can't be forged
+  # onto a stolen assertion; Atlas admin-gates the operator and ignores any
+  # header obo on this path) — it is no longer punted to the legacy relay. Off
+  # unless a signing key is configured (so it coexists with `ATLAS_TOKEN`
+  # during cutover). `ATLAS_JWT`, if set, still wins over signing.
+  #
+  # Requires an Atlas that verifies the signed `obo` claim (the signed-obo
+  # release); against an older Atlas an `obo` would be silently ignored, so
+  # don't enable signing for acting-as traffic until Atlas is on that version.
+  #
   # 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.
@@ -151,30 +173,74 @@ module AtlasRb
 
     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.
+    # 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
 
-      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
 
+      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 or there is no
+    # acting nuid to put in `sub`. Acting-as is carried IN the assertion as a
+    # signed `obo` claim (Atlas honours it on the assertion path as of the
+    # signed-obo release), so it is no longer punted to the cerberus_token relay.
+    def signed_relay_headers(nuid, on_behalf_of)
+      return nil unless nuid
+
+      key = assertion_signing_key
+      return nil unless key
+
+      { "Authorization" => "Bearer #{signed_assertion(nuid.to_s, key, on_behalf_of)}" }
+    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. When `on_behalf_of` is given, it rides as
+    # a SIGNED `obo` claim — acting-as that can't be forged onto a stolen
+    # assertion (Atlas admin-gates the operator and ignores any header obo here).
+    def signed_assertion(nuid, key, on_behalf_of = nil)
+      now = Time.now.to_i
+      payload = { "iss" => ASSERTION_ISSUER, "aud" => ASSERTION_AUDIENCE, "sub" => nuid,
+                  "iat" => now, "exp" => now + ASSERTION_TTL, "jti" => SecureRandom.uuid,
+                  "obo" => on_behalf_of&.to_s }.compact # obo only when acting-as
+      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"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.3.7
+  version: 1.3.9
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-14 00:00:00.000000000 Z
+date: 2026-06-15 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