atlas_rb 1.3.9 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf2f8c7f9ef316468a2544efe2f4471c23c547ae36d50b9abfee2efd03db38c8
-  data.tar.gz: 9da90557d04f84ddad26c05b6c50eab0d9a7378ccf57fbb37ba6b3e7e4355cd4
+  metadata.gz: 31c36891a34eef17727397e17017db5eb1acea6cdfae4dfbba76b93e6f32954a
+  data.tar.gz: 3871ca6703afa2ecccf780f089b22e8ff6fdcbcdaf5aaafb82e51bbf606e95a1
 SHA512:
-  metadata.gz: 640d113ae6693aacb7d7d2a943634561281ebb5324d7db5284429673a48ff1ae9cbedda4d55b058710c497573e4c7c379dee18b08119925c5a0e7e73f7105088
-  data.tar.gz: 8e7209552ebc5b7b8db138809bd89ef077ac282342c39d483f1c125f68d757c155ff12865f7a1c24bb65040bf287eb13c7ecd81549117cb0cf01d3a1bf58cc79
+  metadata.gz: 84f906c748bd98acb961eb403950d98e1c46be9084ae21fde55b949bc1af6f2bc9f72c567c0bb826b854209b75f51d437196d7e7d0b1031d9f2497e132d305f8
+  data.tar.gz: bac7488013b6d12db98806447405c27ae52d4fed86608c2fc96f2180cea48a931d0d43b1421b914de3218a742fb5bb53cfa46dc9d59f41ee3a92670571a52aee

data/.version

@@ -1 +1 @@
-1.3.9
+1.4.0

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 1.4.0
+
+### Removed — legacy `ATLAS_TOKEN` relay
+
+The shared-secret relay (`ATLAS_TOKEN` bearer + `User: NUID` / `On-Behalf-Of`
+headers) has been removed. **Relay-signing is now the only relay path:** set
+`AtlasRb.config.assertion_signing_key` / `assertion_signing_kid` and the
+transport signs a short-lived ES256 assertion (`sub` = acting NUID; acting-as
+rides a signed `obo` claim). `ATLAS_JWT` (BYO-JWT) still takes precedence.
+
+With neither a signing key nor `ATLAS_JWT` configured, `connection` /
+`multipart` now raise the new `AtlasRb::ConfigurationError` rather than falling
+back to `ATLAS_TOKEN`. The `ATLAS_TOKEN` environment variable is no longer read.
+
+**Migration:** hosts must configure a signing key (Cerberus already does via its
+`atlas_rb` initializer). This is a breaking change for any caller still relying
+on `ATLAS_TOKEN`.
+
 ## 1.3.5
 
 ### Added — `Compilation.list(q:)` title filter

data/Gemfile.lock

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

data/README.md

@@ -30,21 +30,24 @@ 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` | 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). |
 
+The default relay path authenticates by **signing** a short-lived assertion (see
+[Relay-signing](#relay-signing-the-default-relay-path)); configure a signing key
+for it. `ATLAS_JWT`, if set, takes precedence.
+
 ```ruby
-ENV["ATLAS_URL"]   = "https://atlas.example.edu"
-ENV["ATLAS_TOKEN"] = "..."
+ENV["ATLAS_URL"] = "https://atlas.example.edu"
+# + a configured signing key (relay) or ENV["ATLAS_JWT"] (BYO-JWT)
 ```
 
 ### Ambient identity (`default_nuid` / `default_on_behalf_of`)
 
 Every resource method that talks to Atlas accepts a `nuid:` kwarg (the
 acting user) and an `on_behalf_of:` kwarg (the user the call is being
-made *for*, used by acting-as / view-as flows). Both are forwarded as
-`User: NUID <nuid>` and `On-Behalf-Of: NUID <nuid>` headers
-respectively.
+made *for*, used by acting-as / view-as flows). On the relay-signing path
+`nuid` is signed into the assertion `sub` and `on_behalf_of` rides as a
+signed `obo` claim.
 
 Rather than threading them at every call site, register callables
 once on app boot and let the gem read them as defaults:
@@ -74,17 +77,17 @@ AtlasRb::Work.find("w-789")
 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).
+On the relay-signing path the acting `nuid` is required (it becomes the
+assertion `sub`): if neither the call site nor the registered `default_nuid`
+supplies one, the transport raises `AtlasRb::ConfigurationError`.
 
 ### 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:
+The relay-signing path above is what a Rails host (Cerberus) uses: a signed
+assertion 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"
@@ -96,7 +99,7 @@ AtlasRb::Work.find("w-789")
 
 In BYO-JWT mode:
 
-- The JWT is the bearer, **taking precedence over `ATLAS_TOKEN`**.
+- The JWT is the bearer, **taking precedence over relay-signing**.
 - **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
@@ -106,14 +109,12 @@ 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)
+### Relay-signing (the default relay path)
 
-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.
+The relay authenticates with a **proven** identity: it **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 `User:` header — identity is the signed `sub`.
 
 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:
@@ -125,10 +126,8 @@ AtlasRb.configure do |config|
 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).
+With no signing key configured (and no `ATLAS_JWT`), the relay has no credential
+and `connection` / `multipart` raise `AtlasRb::ConfigurationError`.
 
 Two things to know:
 
@@ -136,8 +135,6 @@ Two things to know:
   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.
 
@@ -188,7 +185,7 @@ radius and the kind of authentication they need:
 
 | Namespace            | What it does                                                                       | Auth                                                | Friction                              |
 |----------------------|------------------------------------------------------------------------------------|-----------------------------------------------------|---------------------------------------|
-| `AtlasRb::*`         | Regular CRUD (find / list / create / update / tombstone / metadata, etc.)          | User token (`ATLAS_TOKEN`) + acting user's NUID     | None — these are the daily-use paths. |
+| `AtlasRb::*`         | Regular CRUD (find / list / create / update / tombstone / metadata, etc.)          | Relay-signing (signed assertion, `sub` = acting NUID) | None — these are the daily-use paths. |
 | `AtlasRb::Admin::*`  | Hard delete (`destroy`) and un-tombstone (`restore`) for Work / Collection / Community. | Same as regular — a real operator is acting.        | `destroy` requires `confirm: :i_understand`. |
 | `AtlasRb::System::*` | System-context provisioning (currently just SSO user find-or-create).              | System token (`Rails.application.credentials.atlas_system_token`) + `User: NUID 000000000`. | The namespace itself is the marker — there is no way to call these as a non-system principal. |
 
@@ -446,8 +443,8 @@ string-keyed callers keep working.
 ```ruby
 require "atlas_rb"
 
-ENV["ATLAS_URL"]   = "https://atlas.example.edu"
-ENV["ATLAS_TOKEN"] = "..."
+ENV["ATLAS_URL"] = "https://atlas.example.edu"
+# + a configured signing key (relay) or ENV["ATLAS_JWT"] (BYO-JWT)
 
 # 1. Build the org structure (each create can optionally seed MODS metadata).
 community  = AtlasRb::Community.create(nil,           "/tmp/community-mods.xml")

data/lib/atlas_rb/authentication.rb

@@ -3,15 +3,15 @@
 module AtlasRb
   # User-facing identity lookups against the Atlas API.
   #
-  # Unlike the resource classes, {Authentication} threads a real NUID into the
-  # `User` header via {FaradayHelper#connection}'s second positional argument.
-  # The Atlas server uses that NUID — combined with the bearer token from
-  # `ATLAS_TOKEN` — to resolve the acting user and their group memberships.
+  # Unlike the resource classes, {Authentication} threads a real NUID into
+  # {FaradayHelper#connection}'s second positional argument. On the relay-signing
+  # path that NUID is signed into the assertion `sub`; Atlas resolves the acting
+  # user and their group memberships from the proven `sub`.
   #
-  # No login round-trip happens here today; the bearer token is assumed to be
-  # already provisioned out-of-band. The commented-out code in this file
-  # reflects an older flow where a `/token` endpoint exchanged an NUID for a
-  # session token.
+  # No login round-trip happens here today; auth is assumed to be already
+  # provisioned out-of-band (a configured signing key, or `ATLAS_JWT`). The
+  # commented-out code in this file reflects an older flow where a `/token`
+  # endpoint exchanged an NUID for a session token.
   class Authentication
     extend AtlasRb::FaradayHelper
 

data/lib/atlas_rb/blob.rb

@@ -17,9 +17,9 @@ module AtlasRb
     # Fetch a single Blob's metadata record (not its bytes — see {.content}).
     #
     # @param id [String] the Blob 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.
@@ -43,9 +43,9 @@ module AtlasRb
     # returned so callers can inspect `Content-Type`, `Content-Length`, etc.
     #
     # @param id [String] the Blob 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.
@@ -82,9 +82,9 @@ module AtlasRb
     # @param idempotency_key [String, nil] optional UUID. A repeat call with
     #   the same key returns the originally-created Blob 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.
@@ -114,9 +114,9 @@ module AtlasRb
     # Delete a Blob (the bytes *and* the metadata record).
     #
     # @param id [String] the Blob 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.
@@ -136,9 +136,9 @@ module AtlasRb
     #
     # @param id [String] the Blob ID.
     # @param blob_path [String] path to the replacement binary 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.

data/lib/atlas_rb/collection.rb

@@ -16,9 +16,9 @@ module AtlasRb
     # Fetch a single Collection by ID.
     #
     # @param id [String] the Collection 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.
@@ -44,9 +44,9 @@ module AtlasRb
     # @param xml_path [String, nil] optional path to a MODS XML file used to
     #   seed metadata. When given, the Collection is created and immediately
     #   patched with the metadata in the file.
-    # @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.
@@ -77,9 +77,9 @@ module AtlasRb
     #
     # @param id [String] the Collection ID to move.
     # @param new_parent_id [String] the destination Community 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.
@@ -132,9 +132,9 @@ module AtlasRb
     # {Resource.find} (or {Work.find}) when a full payload is needed.
     #
     # @param id [String] the Collection 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.
@@ -153,9 +153,9 @@ module AtlasRb
     #
     # @param id [String] the Collection ID.
     # @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.
@@ -181,9 +181,9 @@ module AtlasRb
     #
     # @param id [String] the Collection ID.
     # @param values [Hash] field-level metadata updates.
-    # @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.
@@ -208,9 +208,9 @@ module AtlasRb
     # @param thumbnail [String, nil] IIIF URI for the ~85² thumbnail.
     # @param thumbnail_2x [String, nil] IIIF URI for the ~170² 2x thumbnail.
     # @param preview [String, nil] IIIF URI for the ~500w preview image.
-    # @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] the parsed JSON response.
     # @raise [AtlasRb::StaleResourceError] if Atlas reports an optimistic-lock
     #   conflict that exhausted its internal retry budget (HTTP 409 with
@@ -236,9 +236,9 @@ module AtlasRb
     # @param id [String] the Collection ID.
     # @param kind [String, nil] one of `"json"` (default), `"html"`, or
     #   `"xml"`.
-    # @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/community.rb

@@ -17,9 +17,9 @@ module AtlasRb
     # Fetch a single Community by ID.
     #
     # @param id [String] the Community 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.
@@ -45,9 +45,9 @@ module AtlasRb
     # @param xml_path [String, nil] optional path to a MODS XML file. When
     #   given, the Community is created and immediately patched with the
     #   metadata in the file; the returned Hash reflects the patched state.
-    # @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.
@@ -84,9 +84,9 @@ module AtlasRb
     # @param id [String] the Community ID to move.
     # @param new_parent_id [String, nil] the destination Community ID, or
     #   `nil` to move the Community to the top of the tree.
-    # @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.
@@ -142,9 +142,9 @@ module AtlasRb
     # needed.
     #
     # @param id [String] the parent Community 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.
@@ -163,9 +163,9 @@ module AtlasRb
     #
     # @param id [String] the Community ID.
     # @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.
@@ -192,9 +192,9 @@ module AtlasRb
     # @param id [String] the Community ID.
     # @param values [Hash] field-level metadata updates (shape determined by
     #   the Atlas server, typically a mapping from MODS field name to value).
-    # @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.
@@ -219,9 +219,9 @@ module AtlasRb
     # @param thumbnail [String, nil] IIIF URI for the ~85² thumbnail.
     # @param thumbnail_2x [String, nil] IIIF URI for the ~170² 2x thumbnail.
     # @param preview [String, nil] IIIF URI for the ~500w preview image.
-    # @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] the parsed JSON response.
     # @raise [AtlasRb::StaleResourceError] if Atlas reports an optimistic-lock
     #   conflict that exhausted its internal retry budget (HTTP 409 with
@@ -248,9 +248,9 @@ module AtlasRb
     # @param kind [String, nil] one of `"json"` (default when omitted),
     #   `"html"`, or `"xml"`. When `nil`, Atlas returns its default
     #   representation.
-    # @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.