atlas_rb 1.8.5 → 1.8.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b34244827cff750075d39c45f1fd628840b6b1637a06f6bfefc876f285eafbe
-  data.tar.gz: d3f429989a1b983ed13a39c8363b17f1eff439d829f3694244327a38cfc2ca7e
+  metadata.gz: 88e591bc06be2edcf972e7df8490f57656f0562680d3546598f7461b1ad25bc3
+  data.tar.gz: 997084c70c482d78cbc4627d7dcf65b91a1687b8bf6ed1855c0f46613b007389
 SHA512:
-  metadata.gz: 70c4cce5eacaabca34495bee0cd8ed0ada54998e7a90f3b39b26b601d4d20be9e16355d64ac68e75fe39fce8f28d3e25e275d5627afd3644e296c18fdca3453e
-  data.tar.gz: b46212f70bfbec6a343654f89e73e33a13a372abb2e42ff0bf88a0a667d2d5033cee6e221dbdc63022b9feca6f0fd7000c12eb90172a76feaa11540696c04daa
+  metadata.gz: 87d74362da0a1b9fe6655c675fe834dce9c1ea824012d9f482c1828fbe6f299495793836c6840528d350aad020a1a28bf3a53f52136c336c114a3e41afb61096
+  data.tar.gz: b02aac392fa82e3f64c5a391e23215aa2eb6577285ddb0517ac2653ae67f33603dc05e4af018acb73c5a2d9859fc2b137309f51525db6b40aa36897cbe957cfa

data/.version

@@ -1 +1 @@
-1.8.5
+1.8.7

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 1.8.7
+
+### Added — personal-access token lifecycle (`System::Token.mint` / `.revoke`)
+
+New system-context binding for the `POST /nuid` / `DELETE /nuid` endpoints so a
+host app can mint and revoke a user's personal-access JWT (`ATLAS_JWT`, BYO-JWT
+mode). Both are :system-gated on Atlas ("minting for an arbitrary NUID is
+'become anyone'"), so they authenticate via `FaradayHelper#system_connection`
+(hard-pinned system token + `User: NUID` header) — never the ambient-user
+relay-signing path — mirroring `System::User`.
+
+- `AtlasRb::System::Token.mint(nuid:)` → the JWT (`String`), or `nil` when the
+  NUID has no Atlas User row (404). The token is full-privilege for that user,
+  1-week TTL, single-jti.
+- `AtlasRb::System::Token.revoke(nuid:)` → `true` on success (204), `false` on
+  404. Rotates the user's jti (single-jti model → all outstanding tokens die at
+  once). "Regenerate" is `revoke` followed by a fresh `mint`.
+
+Unblocks Cerberus's "My DRS → Programmatic access" section (generate / regenerate
+/ revoke), gated to the `northeastern:drs:repository:api` Grouper group.
+
 ## 1.8.5
 
 ### Fixed — `find` returns a tombstone (`410`) instead of raising

data/Gemfile.lock

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

data/lib/atlas_rb/system/token.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module AtlasRb
+  module System
+    # Personal-access token lifecycle — mint and revoke the 1-week JWT a real
+    # person exports as `ATLAS_JWT` to drive atlas_rb / curl against Atlas
+    # headless (BYO-JWT mode, see {AtlasRb::FaradayHelper}). Cerberus's "My DRS
+    # → Programmatic access" section calls these post-SSO and hands the token
+    # to the librarian; the token is never persisted by Cerberus.
+    #
+    # ## Why a separate class from {System::User}
+    #
+    # Token lifecycle is a distinct concern from SSO user provisioning: minting
+    # a bearer credential for someone is "become anyone," which is exactly why
+    # both Atlas endpoints are :system-gated (`authorize! :mint_token, User`).
+    # Keeping it in its own class keeps that carve-out legible rather than
+    # burying it among provisioning methods.
+    #
+    # Both methods authenticate via {FaradayHelper#system_connection} — the
+    # hard-pinned system token + `User: NUID` header — so there is no way to
+    # issue them as a regular user. This is never the ambient-user
+    # relay-signing path.
+    class Token
+      extend AtlasRb::FaradayHelper
+
+      # Mint a personal-access JWT for a real person (`POST /nuid`).
+      # System-gated. The returned token authenticates as `nuid` in BYO-JWT
+      # mode (Atlas resolves identity from the token's `sub`, ignores any
+      # `User:` / `On-Behalf-Of` header, and refuses `:system`/`:anonymous`).
+      # Full-privilege for that user, 1-week TTL, single-jti.
+      #
+      # @param nuid [String] the NUID the token will act as.
+      # @return [String, nil] the JWT, or nil when the NUID has no Atlas User
+      #   row (404) — a clean "no such user" signal for the caller to surface.
+      def self.mint(nuid:)
+        response = system_connection.post("/nuid", { nuid: nuid }.to_json)
+        return nil if response.status == 404
+
+        AtlasRb::Mash.new(JSON.parse(response.body))["token"]
+      end
+
+      # Revoke every outstanding token for a user (`DELETE /nuid`) by rotating
+      # its jti. System-gated. Single-jti model → all-or-nothing: every token
+      # the user holds dies at once. "Regenerate" on the Cerberus side is
+      # {.revoke} followed by a fresh {.mint}.
+      #
+      # The NUID rides as a query param (`system_connection`'s params hash) so
+      # this sidesteps DELETE-with-body handling; Atlas reads it from
+      # `params[:nuid]` either way.
+      #
+      # @param nuid [String] the NUID whose tokens to invalidate.
+      # @return [Boolean] true on success (204), false when the NUID has no
+      #   Atlas User row (404).
+      def self.revoke(nuid:)
+        system_connection({ nuid: nuid }).delete("/nuid").status == 204
+      end
+    end
+  end
+end

data/lib/atlas_rb/work.rb

@@ -345,28 +345,37 @@ module AtlasRb
       ))
     end
 
-    # Replace a Work's per-tier derivative-visibility policy.
+    # Replace a Work's per-asset derivative-visibility policy.
     #
-    # Sets which read groups may fetch the Work's sized image derivatives —
-    # the `small` / `medium` / `large` / `service` (deep-zoom) tiers — reusing
-    # the resource read-group vocabulary (`"public"`, Grouper group names,
-    # `[]` = private). Unlike {.set_image_derivatives} (which upserts URIs) this
-    # is a whole-object REPLACE: the map you pass is the complete policy;
-    # omitted tiers inherit by cascade (an absent tier inherits the next
-    # lower-resolution tier; `small` inherits the Work's own visibility). Pass a
-    # tier as `[]` to make it private.
+    # Sets which read groups may fetch each of the Work's downloadable
+    # renditions, reusing the resource read-group vocabulary (`"public"`,
+    # Grouper group names, `[]` = private). Two media families:
+    #
+    # * the image ladder `small` / `medium` / `large` / `service` (deep-zoom) /
+    #   `master` (the original image), and
+    # * independent media `audio` / `video` / `pdf`.
     #
-    # Atlas enforces two invariants: a tier may not be more visible than the
-    # Work, and visibility must narrow as resolution grows
-    # (`service` ⊆ `large` ⊆ `medium` ⊆ `small`). The gate is advisory — it
-    # surfaces per Delegate on {.assets} as `gated` / `permission` for the
-    # display layer (Cerberus / the IIIF auth service) to enforce.
+    # Unlike {.set_image_derivatives} (which upserts URIs) this is a whole-object
+    # REPLACE: the map you pass is the complete policy. Within the image ladder
+    # omitted tiers inherit by cascade (an absent tier inherits the next
+    # lower-resolution tier; `small` inherits the Work's own visibility).
+    # Independent media do NOT cascade — an absent `audio`/`video`/`pdf` key
+    # rides the Work. Pass a tier as `[]` to make it private.
+    #
+    # Atlas enforces: a tier may not be more visible than the Work, and — within
+    # the image ladder — visibility must narrow as resolution grows
+    # (`master` ⊆ `service` ⊆ `large` ⊆ `medium` ⊆ `small`; independent media
+    # impose no ordering). The gate is advisory — it surfaces on {.assets} as
+    # `gated` / `permission` for BOTH Delegate (image tier) and Blob (master /
+    # pdf / audio / video, classified by media type) entries, for the display
+    # layer (Cerberus / the IIIF auth service; Cerberus's download :read check)
+    # to enforce.
     #
     # @param id [String] the Work ID.
     # @param policy [Hash] tier => Array(read groups), e.g.
-    #   `{ large: ["northeastern:drs:repository:archives"], service: [...] }`.
-    #   Keys may be strings or symbols; only `small` / `medium` / `large` /
-    #   `service` are recognized.
+    #   `{ large: ["northeastern:drs:repository:archives"], master: [...] }`.
+    #   Keys may be strings or symbols; recognized keys are `small` / `medium` /
+    #   `large` / `service` / `master` / `audio` / `video` / `pdf`.
     # @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).
@@ -437,6 +446,11 @@ module AtlasRb
     # duck-type on the field they need rather than expecting a single
     # schema.
     #
+    # Every entry (Blob and Delegate) also carries the advisory read gate set
+    # via {.set_derivative_permissions}: `gated` (true if the asset must be
+    # authorized rather than fetched directly) and `permission` (the effective
+    # read-group set, or `nil` for guests, to whom group names are withheld).
+    #
     # @param id [String] the Work ID.
     # @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`)

data/lib/atlas_rb.rb

@@ -30,6 +30,7 @@ require_relative "atlas_rb/admin/collection"
 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/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.5
+  version: 1.8.7
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-02 00:00:00.000000000 Z
+date: 2026-07-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -150,6 +150,7 @@ files:
 - lib/atlas_rb/person.rb
 - lib/atlas_rb/resource.rb
 - lib/atlas_rb/system.rb
+- lib/atlas_rb/system/token.rb
 - lib/atlas_rb/system/user.rb
 - lib/atlas_rb/user.rb
 - lib/atlas_rb/version.rb