atlas_rb 1.8.11 → 1.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6edbe1b05256eaab4d296a11f358bb7c7c3f9eaf439be4d48c41e75cfea4951
-  data.tar.gz: 8e042786b3c7636f7ad3676b9086a7db4ecfa8efed7ed1e91ac8ec4153dbb320
+  metadata.gz: fe879cca7166684164dce3dc7651f22b68c83bd36d4463aaf70d1078147b26f8
+  data.tar.gz: ab88520172776ef649214806b30b2153d1804e960672e7c6ed4237a33ce9eb22
 SHA512:
-  metadata.gz: 44832489abc704196a42b92d85304e886cc3951e711ea33980c9357cb515a4f3e674d7c75db989b7de5c7fbdc9ed36dcfc51a5eceb1d697371d3971227a7e5fa
-  data.tar.gz: 45d0ed33989b889a4a2f3ae3c9932b73f85daa3bc7f5ce9e859f7ea304bf97c71195694322e4e78cdcb537e8f50f37cd1b1d1fe6f7c76bc8458f780688e5c143
+  metadata.gz: 89879f3e03444288baa4e04004bd83e706ace04652eca337cb85d7e665816d49d4ce2d006a598c3505317bff78106e647b477bcbd77fdd0408eda6c0632fa8ca
+  data.tar.gz: de9bf34fe94ff2192733ac5c21040b6b1dc8d1b941270398a8edfa0231d4c41fa5ccc69ba17cb68797b40c1a0c6263b187811200c9de13166543cd4bc9632bd8

data/.version

@@ -1 +1 @@
-1.8.11
+1.9.1

data/Gemfile.lock

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

data/lib/atlas_rb/authentication.rb

@@ -17,7 +17,14 @@ module AtlasRb
 
     # Look up the Atlas user record for an NUID.
     #
+    # A NUID can hold several accounts (a person's staff/student logins). Pass
+    # `email:` to act as — and read back — a specific one; it rides as a signed
+    # `acct` claim so `GET /user` resolves that account. Omit it and Atlas
+    # returns the person's preferred account.
+    #
     # @param nuid [String] the user's Northeastern University ID.
+    # @param email [String, nil] optional account email to act as (the `acct`
+    #   selector); nil resolves the preferred account.
     # @return [Hash] the user record returned by `GET /user`, including at
     #   minimum `"id"`, `"name"`, and `"groups"`.
     # @raise [JSON::ParserError] if the response body is not valid JSON
@@ -26,10 +33,8 @@ module AtlasRb
     # @example
     #   AtlasRb::Authentication.login("001234567")
     #   # => { "id" => 42, "name" => "Jane Doe", "groups" => [...] }
-    def self.login(nuid)
-      # JSON.parse(connection({ nuid: nuid }).post('/token')&.body)["token"]
-      # need hash - id, name, token => ...
-      AtlasRb::Mash.new(JSON.parse(connection({}, nuid).get('/user')&.body))
+    def self.login(nuid, email: nil)
+      AtlasRb::Mash.new(JSON.parse(connection({}, nuid, account: email).get('/user')&.body))
     end
 
     # Fetch only the group memberships for an NUID.

data/lib/atlas_rb/configuration.rb

@@ -3,8 +3,8 @@
 module AtlasRb
   # Holds gem-wide configuration registered via {AtlasRb.configure}.
   #
-  # The configuration model is deliberately tiny: two slots, both of which
-  # accept callables. The gem stays consumer-agnostic — it knows nothing
+  # The configuration model is deliberately tiny: a handful of slots, all of
+  # which accept callables. The gem stays consumer-agnostic — it knows nothing
   # about Rails, Devise, or any host application's request lifecycle — and
   # instead lets the consumer hand it lambdas that resolve the per-request
   # ambient context when a request is about to go out.
@@ -45,6 +45,15 @@ module AtlasRb
     #   to send no `On-Behalf-Of:` header.
     attr_accessor :default_on_behalf_of
 
+    # @return [Proc, nil] callable returning the ambient account email when a
+    #   call is made without an explicit `account:` kwarg. A person's NUID can
+    #   hold several accounts (staff/student logins); this names which one is
+    #   acting, signed into the assertion as an `acct` claim (companion to
+    #   {#default_nuid}). Typically `-> { Current.account_email }` in a Rails
+    #   host. `nil` (the default) signs no `acct` — Atlas then resolves the
+    #   person's preferred account.
+    attr_accessor :default_account
+
     # 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

data/lib/atlas_rb/faraday_helper.rb

@@ -76,6 +76,10 @@ module AtlasRb
     #   claim (acting-as / view-as). When `nil`, falls through to
     #   `AtlasRb.config.default_on_behalf_of&.call`; if that is also nil, no
     #   `obo` claim is added.
+    # @param account [String, nil] optional account email carried as a signed
+    #   `acct` claim, naming which of the NUID's accounts is acting. When `nil`,
+    #   falls through to `AtlasRb.config.default_account&.call`; if that is also
+    #   nil, no `acct` claim is added and Atlas resolves the preferred account.
     # @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
@@ -92,8 +96,8 @@ module AtlasRb
     #
     # @example Fetching a community
     #   AtlasRb::Community.connection({}).get('/communities/abc123')
-    def connection(params, nuid=nil, on_behalf_of: nil, idempotency_key: nil, auth: :required)
-      headers = auth_headers(nuid, on_behalf_of, optional: auth == :optional)
+    def connection(params, nuid=nil, on_behalf_of: nil, account: nil, idempotency_key: nil, auth: :required)
+      headers = auth_headers(nuid, on_behalf_of, account: account, optional: auth == :optional)
                 .merge("Content-Type" => "application/json")
       headers["Idempotency-Key"] = idempotency_key if idempotency_key
 
@@ -135,8 +139,8 @@ module AtlasRb
     #                                               "scan.pdf")
     #   }
     #   AtlasRb::Blob.multipart.post('/files/', payload)
-    def multipart(nuid=nil, on_behalf_of: nil, idempotency_key: nil)
-      headers = auth_headers(nuid, on_behalf_of)
+    def multipart(nuid=nil, on_behalf_of: nil, account: nil, idempotency_key: nil)
+      headers = auth_headers(nuid, on_behalf_of, account: account)
       headers["Idempotency-Key"] = idempotency_key if idempotency_key
 
       Faraday.new(
@@ -192,11 +196,13 @@ module AtlasRb
     # Used exclusively by classes under {AtlasRb::System}.
     #
     # @param params [Hash] query-string / body params.
+    # @param on_behalf_of [String, nil] optional NUID sent as a plain (not
+    #   signed) `On-Behalf-Of` header — this path is already backend-only.
     # @return [Faraday::Connection] a system-authenticated connection.
     # @raise [RuntimeError] if the credential is not configured.
     # @raise [NameError] if `Rails` is not loaded (the gem assumes a
     #   Rails host for system-path calls).
-    def system_connection(params = {})
+    def system_connection(params = {}, on_behalf_of: nil)
       token = Rails.application.credentials.atlas_system_token ||
               raise("atlas_rb: Rails.application.credentials.atlas_system_token not configured")
 
@@ -205,6 +211,7 @@ module AtlasRb
         "Authorization" => "Bearer #{token}",
         "User"          => "NUID #{AtlasRb::System::NUID}"
       }
+      headers["On-Behalf-Of"] = "NUID #{on_behalf_of}" if on_behalf_of
 
       Faraday.new(
         url: ENV.fetch("ATLAS_URL", nil),
@@ -212,6 +219,10 @@ module AtlasRb
         headers: headers
       ) do |f|
         instrument(f)
+        # Narrowly path-scoped (see each class) — a no-op for System::User /
+        # System::Token, and gives System::Work the same typed errors as #connection.
+        f.use AtlasRb::Middleware::RaiseOnStaleResource
+        f.use AtlasRb::Middleware::RaiseOnResourceError
         f.response :follow_redirects
         f.adapter Faraday.default_adapter
       end
@@ -243,14 +254,15 @@ module AtlasRb
     # is only for endpoints Atlas serves with `require_auth` skipped (`GET
     # /reset`); every normal endpoint leaves `optional` false so a
     # misconfiguration fails loudly rather than silently going unauthenticated.
-    def auth_headers(nuid, on_behalf_of, optional: false)
+    def auth_headers(nuid, on_behalf_of, account: nil, optional: false)
       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
+      account      ||= AtlasRb.config.default_account&.call
 
-      headers = signed_relay_headers(nuid, on_behalf_of)
+      headers = signed_relay_headers(nuid, on_behalf_of, account)
       return headers if headers
       return {} if optional
 
@@ -262,14 +274,16 @@ module AtlasRb
     # 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)
+    # honours it on the assertion path; a header obo is ignored there). When a
+    # NUID holds several accounts, `account` (email) rides as a signed `acct`
+    # claim naming which one is acting; absent, Atlas picks the preferred.
+    def signed_relay_headers(nuid, on_behalf_of, account = nil)
       return nil unless nuid
 
       key = assertion_signing_key
       return nil unless key
 
-      { "Authorization" => "Bearer #{signed_assertion(nuid.to_s, key, on_behalf_of)}" }
+      { "Authorization" => "Bearer #{signed_assertion(nuid.to_s, key, on_behalf_of, account)}" }
     end
 
     # Mint a Cerberus relay assertion for `nuid`, signed ES256 with `key`. The
@@ -278,11 +292,12 @@ module AtlasRb
     # 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)
+    def signed_assertion(nuid, key, on_behalf_of = nil, account = 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
+                  "obo"  => on_behalf_of&.to_s, # obo only when acting-as
+                  "acct" => account&.to_s }.compact # acct only when a specific account is named
       JWT.encode(payload, key, "ES256", { kid: assertion_signing_kid })
     end
 

data/lib/atlas_rb/system/user.rb

@@ -27,9 +27,10 @@ module AtlasRb
     NUID = "000000000"
 
     # SSO-callback user provisioning. Finds the Atlas `User` row keyed on
-    # the supplied NUID (creating it if missing) and replaces its
-    # `groups` with the IdP-asserted set. Full replace, not merge —
-    # the IdP assertion is authoritative.
+    # the supplied email — the account key — (creating it if missing) and
+    # replaces its `groups` with the IdP-asserted set. Full replace, not
+    # merge — the IdP assertion is authoritative. Keying on email keeps a
+    # person's staff/student logins as distinct accounts under one NUID.
     #
     # Always authenticates via {FaradayHelper#system_connection}, so the
     # caller has no way to act as a non-system principal. Atlas allows
@@ -37,32 +38,40 @@ module AtlasRb
     class User
       extend AtlasRb::FaradayHelper
 
-      # Find-or-create the User keyed on NUID and replace its groups.
+      # Find-or-create the User keyed on email and replace its groups.
       #
-      # @param nuid [String] the NUID of the user being provisioned.
-      #   This is the *subject* of the operation, not the actor — the
-      #   actor is always the system fixture.
+      # Email is the account key: a person's staff and student logins share a
+      # NUID but present a different email each, so keying on email keeps them
+      # as distinct accounts instead of collapsing (last-write-wins) on NUID.
+      #
+      # @param email [String] the account key — the login's `mail`.
+      #   This is the *subject* of the operation, not the actor; the actor is
+      #   always the system fixture.
+      # @param nuid [String, nil] the person's NUID (the grouping thread that
+      #   ties a person's accounts together). Forwarded when available.
       # @param groups [Array<String>] full group set; replaces, not merges.
       # @param name [String, nil] forwarded if the SSO callback has it;
       #   Atlas treats this field as optional.
-      # @param email [String, nil] forwarded if available; optional in
-      #   Atlas.
+      # @param affiliation [String, nil] the login's unscoped-affiliation, a
+      #   human label for the account (e.g. "staff"/"student"); optional.
       # @return [AtlasRb::Mash] the resulting User record (`id`, `nuid`,
-      #   `name`, `email`, `role`, `groups`).
+      #   `name`, `email`, `role`, `groups`, `affiliation`, `preferred`).
       #
       # @example From Cerberus's SSO callback
       #   AtlasRb::System::User.find_or_create(
+      #     email: "j.doe@northeastern.edu",
       #     nuid: "001234567",
       #     groups: ["northeastern:staff", "drs:editors"],
       #     name: "Jane Doe",
-      #     email: "j.doe@example.edu"
+      #     affiliation: "staff"
       #   )
-      def self.find_or_create(nuid:, groups:, name: nil, email: nil)
+      def self.find_or_create(email:, nuid: nil, groups: [], name: nil, affiliation: nil)
         body = { groups: groups }
-        body[:name]  = name  if name
-        body[:email] = email if email
+        body[:nuid]        = nuid        if nuid
+        body[:name]        = name        if name
+        body[:affiliation] = affiliation if affiliation
 
-        response = system_connection.put("/users/by_nuid/#{nuid}", body.to_json)
+        response = system_connection.put("/users/by_email/#{email}", body.to_json)
         AtlasRb::Mash.new(JSON.parse(response.body))["user"]
       end
     end

data/lib/atlas_rb/system/work.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module AtlasRb
+  module System
+    # Showcase publishing: link a freshly-created Work into a depositor's
+    # featured showcase Collection on their behalf, without granting the
+    # depositor themselves standing edit rights on that shared Collection.
+    #
+    # Atlas scopes this narrowly on both sides (see Atlas's `Ability`): the
+    # target Collection must be `featured`, and the Work must belong to the
+    # `on_behalf_of` NUID — never an arbitrary or private Work. Cerberus's
+    # `WorkDeposit#create_published` ("Publish to my community") is the one
+    # caller today.
+    #
+    # Always authenticates via {FaradayHelper#system_connection}, so there is
+    # no way to issue this as a regular user.
+    class Work
+      extend AtlasRb::FaradayHelper
+
+      # @param work_id [String] the Work ID to link.
+      # @param collection_id [String] the (must-be-featured) showcase
+      #   Collection to link the Work into.
+      # @param on_behalf_of [String] the depositor NUID this write is
+      #   attributed to — required (unlike the regular, human-facing
+      #   {AtlasRb::Work.add_linked_member}), since a :system call with no
+      #   attribution defeats the point of this path, and Atlas's Ability
+      #   grant is itself conditioned on it matching the Work's depositor.
+      # @return [Array<String>] the Work's full set of linked Collection
+      #   noids after the add.
+      # @raise [AtlasRb::StaleResourceError] optimistic-lock conflict.
+      # @raise [AtlasRb::LinkedMemberError] structural rejection (HTTP 422) —
+      #   non-Collection target, tombstoned work/target, already a structural
+      #   member.
+      # @raise [AtlasRb::ForbiddenError] Atlas refused the link (HTTP 403) —
+      #   e.g. the target Collection isn't featured, or on_behalf_of doesn't
+      #   own the Work.
+      #
+      # @example From Cerberus's publish-to-showcase deposit branch
+      #   AtlasRb::System::Work.add_linked_member(work.id, showcase.id, on_behalf_of: depositor_nuid)
+      def self.add_linked_member(work_id, collection_id, on_behalf_of:)
+        JSON.parse(
+          system_connection({ collection_id: collection_id }, on_behalf_of: on_behalf_of)
+            .post("/works/#{work_id}/linked_members")&.body
+        )
+      end
+    end
+  end
+end

data/lib/atlas_rb/user.rb

@@ -1,22 +1,26 @@
 # frozen_string_literal: true
 
 module AtlasRb
-  # Read-only user directory lookups — typeahead search and NUID → name
-  # resolution.
+  # User directory lookups (typeahead search, NUID → name resolution) plus a
+  # person's own account management — enumerating the accounts that share their
+  # NUID and choosing a preferred (default) one.
   #
   # This is a **user-context** binding: calls authenticate as the acting
   # 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.
+  # system-token calls ({System::User.find_or_create}), and these are ordinary
+  # logged-in-user capabilities.
   #
-  # Atlas enforces minimal disclosure: every entry carries `nuid` + `name`
-  # only (no email, role, or groups), and rows with role `anonymous`,
-  # `guest`, or `system` are never returned. Per the layering principle the
-  # gem adds nothing on top — no caching, no name parsing, no result
-  # shaping; presentation belongs to the host application.
+  # The directory lookups enforce minimal disclosure: every entry carries
+  # `nuid` + `name` only (no email, role, or groups), and rows with role
+  # `anonymous`, `guest`, or `system` are never returned. The account methods
+  # ({.accounts} / {.set_preferred}) *do* disclose email/groups/affiliation, so
+  # Atlas limits them to the person themselves (matching NUID), an admin, or the
+  # system principal. Per the layering principle the gem adds nothing on top —
+  # no caching, no name parsing, no result shaping; presentation belongs to the
+  # host application.
   class User
     extend AtlasRb::FaradayHelper
 
@@ -88,5 +92,47 @@ module AtlasRb
         connection({ nuids: Array(nuids).join(",") }, nuid).get(ROUTE)&.body
       ).map { |entry| AtlasRb::Mash.new(entry) }
     end
+
+    # List the accounts sharing a NUID — a person's staff/student logins.
+    #
+    # Unlike the directory lookups this discloses each account's email,
+    # affiliation label, role, stored group set, and which one is preferred —
+    # the data the login "you have more than one account" check and the My DRS
+    # accounts panel render from. Atlas limits it to the person themselves, an
+    # admin, or the system principal; others get a `403`.
+    #
+    # @param target_nuid [String] the NUID whose accounts to list — the
+    #   *subject*, distinct from the acting `nuid:` kwarg.
+    # @param nuid [String, nil] optional acting user's NUID (signed into the
+    #   assertion `sub`); on the BYO-JWT path identity lives in the token.
+    # @return [AtlasRb::Mash] the envelope: `nuid` plus an `accounts` array,
+    #   each entry carrying `email`, `name`, `affiliation`, `role`, `groups`,
+    #   and `preferred`.
+    #
+    # @example Login-time multi-account detection
+    #   AtlasRb::User.accounts("001234567", nuid: "001234567")["accounts"].size # => 2
+    def self.accounts(target_nuid, nuid: nil)
+      AtlasRb::Mash.new(JSON.parse(
+        connection({}, nuid).get("#{ROUTE}/by_nuid/#{target_nuid}/accounts")&.body
+      ))
+    end
+
+    # Set the preferred (default) account for a NUID — the account chosen when
+    # a login names no specific one. Same self/admin/system scope as {.accounts}.
+    #
+    # @param target_nuid [String] the NUID whose default is being set.
+    # @param email [String] the account to make preferred; must be one of the
+    #   NUID's accounts (else Atlas returns `404`).
+    # @param nuid [String, nil] optional acting user's NUID (signed into `sub`).
+    # @return [AtlasRb::Mash] the updated account record under `"user"`.
+    #
+    # @example
+    #   AtlasRb::User.set_preferred("001234567", email: "j.doe@husky.neu.edu",
+    #                               nuid: "001234567")
+    def self.set_preferred(target_nuid, email:, nuid: nil)
+      response = connection({}, nuid)
+                 .put("#{ROUTE}/by_nuid/#{target_nuid}/preferred_account", { email: email }.to_json)
+      AtlasRb::Mash.new(JSON.parse(response.body))["user"]
+    end
   end
 end

data/lib/atlas_rb.rb

@@ -31,6 +31,7 @@ require_relative "atlas_rb/admin/community"
 require_relative "atlas_rb/system"
 require_relative "atlas_rb/system/user"
 require_relative "atlas_rb/system/token"
+require_relative "atlas_rb/system/work"
 require_relative "atlas_rb/audit_event"
 
 # Ruby client for the Atlas API — Northeastern University's institutional

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.8.11
+  version: 1.9.1
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-08 00:00:00.000000000 Z
+date: 2026-07-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -152,6 +152,7 @@ files:
 - lib/atlas_rb/system.rb
 - lib/atlas_rb/system/token.rb
 - lib/atlas_rb/system/user.rb
+- lib/atlas_rb/system/work.rb
 - lib/atlas_rb/user.rb
 - lib/atlas_rb/version.rb
 - lib/atlas_rb/work.rb