atlas_rb 1.3.7 → 1.3.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2edc49cf965b1b1489e639b3ae8fd0413d036fe81b07a83c48f851ed975da1a0
-  data.tar.gz: ba269fae419aa13545e9e5c664e7c1b66282bcb4ff9c8e238d1333e2c51f444e
+  metadata.gz: 7f2a9947778ab6d15d96514cdeb949a82ffce8023f6fe0aeee39bfce1c198ce3
+  data.tar.gz: 864fd37a55f2275417dc5f45f1c60466b41baefc3351ed6f712c7f7dfdcda28d
 SHA512:
-  metadata.gz: 5ed3a6c2f5d1934a25654fd0130e4f8bc8cf41e00530dfee5b333d4e09bdf9caacdd25f88eecb88426bbf9ba3a61f870faf2b9fece2fb13b7a066a24818bf4e8
-  data.tar.gz: ea5ddec2aea0f36cfbebc2150035517857beb24a015b19deade470507604d771bd8b9bd50151d8260e425de355bbe7af502e7dd284819207260a5066cad814ff
+  metadata.gz: afef167fa0ed86fb7ebd4d28fe693fb41fe20f2ade2e9b96ce0f1109aec7340038b4a9c9425cf53d3463bc346aa9cf4fa90fd012cf3ad2636dad42784d040fa2
+  data.tar.gz: aec3edc7ce6cb88a6d9421b449e3420521073bd20083c86afa451d74c74d903c5dc222a85f0bff2bd2a87c094f06fe3066bae7f4b814fd367a6c0640e5a6800e

data/.version

@@ -1 +1 @@
-1.3.7
+1.3.8

data/Gemfile.lock

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

@@ -106,6 +106,39 @@ 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 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

@@ -30,9 +30,27 @@ 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
+  # 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.
@@ -151,30 +169,77 @@ 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, 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"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.3.7
+  version: 1.3.8
 platform: ruby
 authors:
 - David Cliff
@@ -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