atlas_rb 1.3.9 → 1.4.0

data/lib/atlas_rb/compilation.rb

@@ -32,9 +32,9 @@ module AtlasRb
     # non-grantee raises {AtlasRb::ForbiddenError}.
     #
     # @param id [String] the Compilation ID (NOID).
-    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
-    #   `User:` header. Required for cerberus-token requests; legacy bearer
-    #   tokens still resolve without it.
+    # @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).
     # @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.
@@ -66,9 +66,9 @@ module AtlasRb
     # @param q [String, nil] case-insensitive title substring filter.
     # @param page [Integer, nil] 1-indexed page number.
     # @param per_page [Integer, nil] page size override.
-    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
-    #   `User:` header. Required for cerberus-token requests; legacy bearer
-    #   tokens still resolve without it.
+    # @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).
     # @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.
@@ -103,9 +103,8 @@ module AtlasRb
     #
     # @param title [String] the Set's title (required; blank is a 422).
     # @param description [String, nil] optional free-text description.
-    # @param nuid [String, nil] the acting user's NUID, forwarded as the
-    #   `User:` header — the created Set's owner. Required for
-    #   cerberus-token requests.
+    # @param nuid [String, nil] the acting user's NUID — signed into the
+    #   assertion `sub` on the relay-signing path, and the created Set's owner.
     # @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.
@@ -140,9 +139,9 @@ module AtlasRb
     # @param description [String, nil] new description.
     # @param permissions [Hash, nil] ACL replacement, e.g.
     #   `{ read: ["public"], edit: [], edit_users: ["000000003"] }`.
-    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
-    #   `User:` header. Required for cerberus-token requests; legacy bearer
-    #   tokens still resolve without it.
+    # @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).
     # @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.
@@ -175,9 +174,9 @@ module AtlasRb
     # not a container.
     #
     # @param id [String] the Compilation ID.
-    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
-    #   `User:` header. Required for cerberus-token requests; legacy bearer
-    #   tokens still resolve without it.
+    # @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).
     # @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.
@@ -199,9 +198,9 @@ module AtlasRb
     #
     # @param id [String] the Compilation ID.
     # @param collection_id [String] the Collection NOID to include.
-    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
-    #   `User:` header. Required for cerberus-token requests; legacy bearer
-    #   tokens still resolve without it.
+    # @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).
     # @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.
@@ -226,9 +225,9 @@ module AtlasRb
     #
     # @param id [String] the Compilation ID.
     # @param collection_id [String] the Collection NOID to remove.
-    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
-    #   `User:` header. Required for cerberus-token requests; legacy bearer
-    #   tokens still resolve without it.
+    # @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).
     # @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.
@@ -250,9 +249,9 @@ module AtlasRb
     #
     # @param id [String] the Compilation ID.
     # @param work_id [String] the Work NOID to include.
-    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
-    #   `User:` header. Required for cerberus-token requests; legacy bearer
-    #   tokens still resolve without it.
+    # @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).
     # @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.
@@ -273,9 +272,9 @@ module AtlasRb
     #
     # @param id [String] the Compilation ID.
     # @param work_id [String] the Work NOID to remove.
-    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
-    #   `User:` header. Required for cerberus-token requests; legacy bearer
-    #   tokens still resolve without it.
+    # @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).
     # @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.
@@ -300,9 +299,9 @@ module AtlasRb
     #
     # @param id [String] the Compilation ID.
     # @param work_id [String] the Work NOID to set aside.
-    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
-    #   `User:` header. Required for cerberus-token requests; legacy bearer
-    #   tokens still resolve without it.
+    # @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).
     # @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.
@@ -323,9 +322,9 @@ module AtlasRb
     #
     # @param id [String] the Compilation ID.
     # @param work_id [String] the Work NOID to restore to the resolved set.
-    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
-    #   `User:` header. Required for cerberus-token requests; legacy bearer
-    #   tokens still resolve without it.
+    # @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).
     # @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.
@@ -353,9 +352,9 @@ module AtlasRb
     # @param id [String] the Compilation ID.
     # @param page [Integer, nil] 1-indexed page number (default 1).
     # @param per_page [Integer, nil] page size (default 25, capped at 100).
-    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
-    #   `User:` header. Required for cerberus-token requests; legacy bearer
-    #   tokens still resolve without it.
+    # @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).
     # @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.

data/lib/atlas_rb/configuration.rb

@@ -45,10 +45,10 @@ module AtlasRb
     #   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.
+    # Relay signing. When set, the regular relay path *signs* a short-lived
+    # assertion (ES256, `sub` = acting nuid) — identity is proven, not asserted.
+    # This is the relay credential: with no signing key configured (and no
+    # `ATLAS_JWT`), the transport raises {AtlasRb::ConfigurationError}.
     #
     # 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

data/lib/atlas_rb/delegate.rb

@@ -23,9 +23,9 @@ module AtlasRb
     # Fetch a single Delegate by NOID or `valkyrie_id`.
     #
     # @param id [String] the Delegate's NOID or `valkyrie_id`.
-    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
-    #   `User:` header. Required for cerberus-token requests; legacy bearer
-    #   tokens still resolve without it.
+    # @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).
     # @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.

data/lib/atlas_rb/errors.rb

@@ -164,4 +164,11 @@ module AtlasRb
       @subject = subject
     end
   end
+
+  # Raised when the transport has no way to authenticate a relay request:
+  # neither `ATLAS_JWT` (BYO-JWT mode) nor a signing key
+  # ({AtlasRb.config#assertion_signing_key}, relay-signing mode) is configured.
+  # This is a host-misconfiguration error surfaced at request-build time, not a
+  # wire response — fix the configuration rather than rescuing it.
+  class ConfigurationError < Error; end
 end

data/lib/atlas_rb/faraday_helper.rb

@@ -6,45 +6,35 @@ module AtlasRb
   # Every Atlas request reads these environment variables:
   #
   # - `ATLAS_URL`   — base URL of the Atlas API (e.g. `https://atlas.example.edu`).
-  # - `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).
   #
   # ## 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. This is the path Cerberus uses.
+  # **Relay-signing mode (default).** 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 against the
+  # matching 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). 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. The key is configured via
+  # {AtlasRb.config#assertion_signing_key} / `assertion_signing_kid`. 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
+  # precedence over relay-signing. 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.
+  # If neither a signing key nor `ATLAS_JWT` is configured there is no relay
+  # credential, so the transport raises {AtlasRb::ConfigurationError}.
   #
   # The module is mixed in via `extend`, so its methods become class methods on
   # the host (e.g. `AtlasRb::Work.connection({})`).
@@ -60,14 +50,13 @@ module AtlasRb
     # @param params [Hash] query-string / body params to attach to the request.
     #   Resource classes use this to pass things like `parent_id:`, `work_id:`,
     #   or `metadata:` without manually serializing.
-    # @param nuid [String, nil] optional Northeastern University ID to send in
-    #   the `User` header. When `nil`, falls through to
-    #   `AtlasRb.config.default_nuid&.call`; if that is also nil, no `User:`
-    #   header is sent (legacy bearer-only path).
-    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
-    #   header. When `nil`, falls through to
+    # @param nuid [String, nil] optional Northeastern University ID. On the
+    #   relay-signing path it is signed into the assertion `sub`. When `nil`,
+    #   falls through to `AtlasRb.config.default_nuid&.call`.
+    # @param on_behalf_of [String, nil] optional NUID carried as a signed `obo`
+    #   claim (acting-as / view-as). When `nil`, falls through to
     #   `AtlasRb.config.default_on_behalf_of&.call`; if that is also nil, no
-    #   `On-Behalf-Of:` header is sent. Used by acting-as / view-as flows.
+    #   `obo` claim is added.
     # @param idempotency_key [String, nil] optional UUID to send in the
     #   `Idempotency-Key` header. Used by retry-safe create flows (currently
     #   `POST /works`, `POST /file_sets`, `POST /files`) to deduplicate replays
@@ -96,15 +85,16 @@ module AtlasRb
 
     # Build a multipart Faraday connection used for binary and XML uploads.
     #
-    # The same `ATLAS_URL` / `ATLAS_TOKEN` env vars apply. Unlike {#connection},
+    # The same `ATLAS_URL` env var and auth modes apply. Unlike {#connection},
     # the `Content-Type` is set automatically by the multipart middleware, and
     # callers pass a payload hash whose values may include
     # `Faraday::Multipart::FilePart` instances. Fall-through semantics for
     # `nuid` / `on_behalf_of` match {#connection}.
     #
-    # @param nuid [String, nil] optional NUID for the `User` header.
-    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
-    #   header.
+    # @param nuid [String, nil] optional acting NUID (signed into the assertion
+    #   `sub` on the relay-signing path).
+    # @param on_behalf_of [String, nil] optional NUID carried as a signed `obo`
+    #   claim (acting-as / view-as).
     # @param idempotency_key [String, nil] optional UUID to send in the
     #   `Idempotency-Key` header. See {#connection} for semantics; the
     #   `POST /files` (Blob) create flow uses this transport.
@@ -174,9 +164,10 @@ module AtlasRb
     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` /
+    # 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)
       jwt = ENV.fetch("ATLAS_JWT", nil)
       return { "Authorization" => "Bearer #{jwt}" } if jwt
@@ -184,14 +175,16 @@ module AtlasRb
       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)
+      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)")
     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.
+    # A signed-assertion Authorization header (sub = acting nuid), or 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; a header obo is ignored there).
     def signed_relay_headers(nuid, on_behalf_of)
       return nil unless nuid
 
@@ -201,15 +194,6 @@ module AtlasRb
       { "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

data/lib/atlas_rb/file_set.rb

@@ -17,9 +17,9 @@ module AtlasRb
     # Fetch a single FileSet by ID.
     #
     # @param id [String] the FileSet ID.
-    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
-    #   `User:` header. Required for cerberus-token requests; legacy bearer
-    #   tokens still resolve without it.
+    # @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).
     # @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.
@@ -48,9 +48,9 @@ module AtlasRb
     # @param idempotency_key [String, nil] optional UUID. A repeat call with
     #   the same key returns the originally-created FileSet instead of
     #   creating a new one. See {AtlasRb::Work.create} for full semantics.
-    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
-    #   `User:` header. Required for cerberus-token requests; legacy bearer
-    #   tokens still resolve without it.
+    # @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).
     # @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.
@@ -81,9 +81,9 @@ module AtlasRb
     # Delete a FileSet.
     #
     # @param id [String] the FileSet ID.
-    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
-    #   `User:` header. Required for cerberus-token requests; legacy bearer
-    #   tokens still resolve without it.
+    # @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).
     # @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.
@@ -104,9 +104,9 @@ module AtlasRb
     #
     # @param id [String] the FileSet ID.
     # @param blob_path [String] path to the binary file on disk.
-    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
-    #   `User:` header. Required for cerberus-token requests; legacy bearer
-    #   tokens still resolve without it.
+    # @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).
     # @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.
@@ -138,9 +138,9 @@ module AtlasRb
     #
     # @param id [String] the FileSet ID.
     # @param uri [String] the IIIF image-service base URI for the page.
-    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
-    #   `User:` header. Required for cerberus-token requests; legacy bearer
-    #   tokens still resolve without it.
+    # @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).
     # @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.

data/lib/atlas_rb/resource.rb

@@ -26,9 +26,9 @@ module AtlasRb
     # pair so callers can dispatch on type.
     #
     # @param id [String] an Atlas resource ID of any type.
-    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
-    #   `User:` header. Required for cerberus-token requests; legacy bearer
-    #   tokens still resolve without it.
+    # @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).
     # @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.
@@ -65,9 +65,9 @@ module AtlasRb
     #
     # @param ids [Array<String>] resource NOIDs to resolve. (Raw Valkyrie ids
     #   are not a supported input — the endpoint resolves alternate ids only.)
-    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
-    #   `User:` header. Required for cerberus-token requests; legacy bearer
-    #   tokens still resolve without it.
+    # @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).
     # @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.
@@ -90,9 +90,9 @@ module AtlasRb
     # Useful for surfacing validation errors in UIs before the user commits.
     #
     # @param xml_path [String] path to a MODS XML file on disk.
-    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
-    #   `User:` header. Required for cerberus-token requests; legacy bearer
-    #   tokens still resolve without it.
+    # @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).
     # @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.
@@ -111,9 +111,9 @@ module AtlasRb
     # Fetch the access-control entries for a resource.
     #
     # @param id [String] an Atlas resource ID.
-    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
-    #   `User:` header. Required for cerberus-token requests; legacy bearer
-    #   tokens still resolve without it.
+    # @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).
     # @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.
@@ -146,9 +146,9 @@ module AtlasRb
     #   history in one shot.
     #
     # @param id [String] an Atlas resource ID.
-    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
-    #   `User:` header. Required for cerberus-token requests; legacy bearer
-    #   tokens still resolve without it.
+    # @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).
     # @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.
@@ -187,9 +187,9 @@ module AtlasRb
     # responses, matching {history}.
     #
     # @param id [String] an Atlas resource ID.
-    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
-    #   `User:` header. Required for cerberus-token requests; legacy bearer
-    #   tokens still resolve without it.
+    # @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).
     # @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.
@@ -225,9 +225,9 @@ module AtlasRb
     #   e.g. `"v3"`.
     # @param kind [String, nil] response format extension. Omit (or pass
     #   `"xml"`) for the historical XML — the only format the server retains.
-    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
-    #   `User:` header. Required for cerberus-token requests; legacy bearer
-    #   tokens still resolve without it.
+    # @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).
     # @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.

data/lib/atlas_rb/system/user.rb

@@ -10,10 +10,10 @@ module AtlasRb
   #
   # The `:system` principal needs a different bearer token (carried in
   # `Rails.application.credentials.atlas_system_token`, not the user-side
-  # `ENV["ATLAS_TOKEN"]`) and pairs with a different `User:` header (always
-  # {NUID}, never the acting user). Atlas's `require_auth` enforces the
-  # pairing — a user token paired with the system NUID, or the system token
-  # paired with a real user NUID, both 401.
+  # relay-signing / `ATLAS_JWT` credentials) and pairs with a hard-pinned
+  # `User:` header (always {NUID}, never the acting user). Atlas's
+  # `require_auth` enforces the pairing — the system token paired with a
+  # real-user NUID is a 401.
   #
   # Routing system calls through their own class makes the carve-out
   # structural: there is no kwarg that flips a regular call into a system

data/lib/atlas_rb/user.rb

@@ -5,8 +5,9 @@ module AtlasRb
   # resolution.
   #
   # This is a **user-context** binding: calls authenticate as the acting
-  # user via the standard `ATLAS_TOKEN` + `User:` header pairing, like every
-  # other top-level class. It is deliberately *not* part of
+  # user via the standard relay-signing path (the acting NUID is signed into
+  # the assertion `sub`), like every other top-level class. It is
+  # deliberately *not* part of
   # {AtlasRb::System} — that namespace is structurally reserved for
   # system-token calls ({System::User.find_or_create}), and directory
   # lookups are an ordinary logged-in-user capability.
@@ -30,9 +31,9 @@ module AtlasRb
     # it by name; a blank query resolves to an empty list.
     #
     # @param query [String] name fragment or NUID prefix to match.
-    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
-    #   `User:` header. Required for cerberus-token requests; legacy bearer
-    #   tokens still resolve without it.
+    # @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).
     # @return [Array<AtlasRb::Mash>] matching directory entries, each
     #   carrying `nuid` and `name`.
     #
@@ -49,9 +50,9 @@ module AtlasRb
     #
     # @param target_nuid [String] the NUID being looked up — the *subject*
     #   of the call, distinct from the acting `nuid:` kwarg.
-    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
-    #   `User:` header. Required for cerberus-token requests; legacy bearer
-    #   tokens still resolve without it.
+    # @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).
     # @return [AtlasRb::Mash, nil] the `nuid` + `name` entry, or `nil` when
     #   Atlas reports the NUID as absent (unknown, or held by an excluded
     #   role — the two are indistinguishable on the wire by design).
@@ -73,9 +74,9 @@ module AtlasRb
     # input — callers index by `nuid`. Atlas caps the batch at 100.
     #
     # @param nuids [Array<String>, String] the NUIDs to resolve.
-    # @param nuid [String, nil] optional acting user's NUID, forwarded as the
-    #   `User:` header. Required for cerberus-token requests; legacy bearer
-    #   tokens still resolve without it.
+    # @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).
     # @return [Array<AtlasRb::Mash>] resolved entries, each carrying `nuid`
     #   and `name`, ordered by name.
     #