atlas_rb 1.8.11 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6edbe1b05256eaab4d296a11f358bb7c7c3f9eaf439be4d48c41e75cfea4951
-  data.tar.gz: 8e042786b3c7636f7ad3676b9086a7db4ecfa8efed7ed1e91ac8ec4153dbb320
+  metadata.gz: 9bfa2bcb90b5d30ebbf8a4a2612b1a6aafab5fc4eb07df8b12c3ba904ab1fb48
+  data.tar.gz: 9afb80d4f4cecfdfa5204ad101967fe4360057a2222ca573153e00bfc3a3e281
 SHA512:
-  metadata.gz: 44832489abc704196a42b92d85304e886cc3951e711ea33980c9357cb515a4f3e674d7c75db989b7de5c7fbdc9ed36dcfc51a5eceb1d697371d3971227a7e5fa
-  data.tar.gz: 45d0ed33989b889a4a2f3ae3c9932b73f85daa3bc7f5ce9e859f7ea304bf97c71195694322e4e78cdcb537e8f50f37cd1b1d1fe6f7c76bc8458f780688e5c143
+  metadata.gz: 2dbd56463086ce26fc3380eaee4e850dfe6c66a15d6e716c22271d8a13230fbb9db122195f368b41dad8edf96eb153540c699c567f0d43b50b96bc95e8d5c1b7
+  data.tar.gz: cfba3517bd027ae9ff972b3316da4a3bd941e28a080961a69d16625b874bd6b6f5ececd503327d5f0b9ebc56ffc118bd36c04823e2a94ba07aa45a4179fcdc4b

data/.version

@@ -1 +1 @@
-1.8.11
+1.9.0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    atlas_rb (1.8.11)
+    atlas_rb (1.9.0)
       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(
@@ -243,14 +247,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 +267,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 +285,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/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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.8.11
+  version: 1.9.0
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-08 00:00:00.000000000 Z
+date: 2026-07-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday