atlas_rb 1.2.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30f433b53fc97128762eadbf01f12f975111c2b6e597469acc19831e3ef02bba
-  data.tar.gz: 3604a876f6061a2a4bf45953abae93faca9b7fdae27a9b264ec5e10526acaa0c
+  metadata.gz: d65fea7329731bd0fa0a397a19f5764a05e88397c522baf28721e4a08282e2d3
+  data.tar.gz: 7b2db70c9e1a7d9e8fad5194bcb045baeed562561b1c36a60c174e2c1fc5d0aa
 SHA512:
-  metadata.gz: 62376e2b252c0269420ca89661bf7bb864b198f820076bd0c01210dc129adde111f218f2f33e7b3f88365a8b944cd5d2fda0758de050b9585c84ded5a1694309
-  data.tar.gz: d498f94bff1f2e13fcdacbca9ca05dce38bbcfe80209de0f3339f31b69aff8e47492980079096f2f141748845aab30e271ba54fa19639368c005a37d1cc0a9d7
+  metadata.gz: 335c7d4bd02d6bdb6f297cf86857c042d515680fb8e36991d98a7a7bf4fdd1e52470f0dda4b40605f79d0618c7260a64f2125af2a3100a693c920b51ebc1c1f5
+  data.tar.gz: ce1bc4b16ce482975af0785138574aa6b42fc2cc05ddfee777adbef2834b733bdb93df5390cfc4e9a5012af4b9483cf5676f7213edc8e79afc0fd886d2b84545

data/.version

@@ -1 +1 @@
-1.2.1
+1.3.0

data/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Changelog
 
+## 1.3.0
+
+### Added — `AtlasRb::Resource.find_many` (batch resolve by NOID)
+
+A binding for Atlas's `POST /resources/find_many`. Resolves a set of NOIDs
+to lightweight digests in **one** round-trip, replacing the `find`-per-id
+fan-out that several Cerberus surfaces (breadcrumbs, linked-member lists,
+load-destination pickers) paid on every render.
+
+```ruby
+nodes   = AtlasRb::Resource.find_many(["col-456", "col-457", "missing"])
+by_noid = nodes.index_by { |n| n["noid"] }
+by_noid["col-456"].title   # => "Some Collection"
+```
+
+- Each digest is `{ "id", "noid", "klass", "title", "thumbnail",
+  "tombstoned" }` — not the full typed payload. `title` / `thumbnail` are
+  `null` for resources off the Modsable backbone (FileSet/Blob).
+- The ids ride in the request **body**, so the list isn't bounded by URL
+  length. Returns one `AtlasRb::Mash` per resolved resource.
+- The result is **unordered** and **may be shorter than the input**:
+  unresolvable ids are dropped, tombstoned ones come back flagged
+  (`"tombstoned" => true`). Index by `"noid"` — don't assume positional
+  correspondence with the input.
+- Resolves NOIDs (alternate ids) only; raw Valkyrie ids are not a supported
+  input.
+
+## 1.2.2
+
+### Added — `AtlasRb::AuditEvent.emit` (session-scoped audit events)
+
+A new binding for Atlas's `POST /audit_events` endpoint, which records an
+AuditEvent with a **null `resource_id`** — an event not tied to any
+resource write. This is the gem's half of the impersonation audit trail
+(acting-as / view-as): the session lifecycle lives entirely in the calling
+application, and a view-as session performs no writes, so neither leaves a
+per-resource event for `Resource.history` to surface.
+
+```ruby
+AtlasRb::AuditEvent.emit(
+  action:            "impersonation_started",  # or "impersonation_ended"
+  actor_nuid:        admin_nuid,
+  on_behalf_of_nuid: target_nuid,
+  mode:              "acting_as"               # or "view_as"
+)
+```
+
+- The recorded principals (`actor_nuid`, `on_behalf_of_nuid`), `mode`, and
+  an optional free-form `payload:` travel in the request **body**, not in
+  ambient headers — so the call is self-describing even when fired as a
+  session is being torn down (e.g. `impersonation_ended`).
+- The request authenticates via the standard `connection` (system token),
+  with the `User: NUID` header pinned to `actor_nuid` so the server-side
+  admin gate holds regardless of ambient `Current` state.
+- `on_behalf_of_nuid`, `mode`, and `payload` are omitted from the body when
+  blank, leaving room for future, mode-less session events. Atlas stamps
+  `occurred_at` server-side.
+- Authorization errors (`401` / `403`) surface as raw Faraday responses,
+  matching `Resource.history`.
+
+Depends on the matching Atlas-side `POST /audit_events` emit endpoint
+(nullable resource scope, admin-gated); see the impersonation gap report.
+
 ## 1.2.1
 
 ### Added — typed errors for re-parent / linked-member rejections

data/Gemfile.lock

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

data/README.md

@@ -113,6 +113,7 @@ Community  →  Collection  →  Work
 | `AtlasRb::Blob`        | The binary bytes; supports streaming downloads.                           |
 | `AtlasRb::Authentication` | NUID → user record / group lookup.                                     |
 | `AtlasRb::Resource`    | Generic resolver, permissions lookup, and audit-event history.            |
+| `AtlasRb::AuditEvent`  | Emit a session-scoped (resource-less) audit event, e.g. impersonation.    |
 | `AtlasRb::Reset`       | Test-only — wipes Atlas state via `GET /reset`.                           |
 
 ## Namespace gradient: regular / Admin / System
@@ -205,6 +206,45 @@ result["events"].first["action"] # => "update"
 Authorization errors (`401` / `403`) are not caught here — they surface as
 raw Faraday responses for the calling application's rescue layer.
 
+### Session-scoped audit events
+
+`Resource.history` only reads events that hang off a resource write. Some
+auditable events have no resource to attach to — most notably impersonation
+sessions (acting-as / view-as): the session lifecycle lives in the calling
+app, and a view-as session performs no writes at all, so it would otherwise
+leave no audit trail. `AtlasRb::AuditEvent.emit` wraps Atlas's
+`POST /audit_events` endpoint, which records an event with a **null
+`resource_id`**.
+
+The principals and metadata travel in the request body — not inferred from
+ambient headers — so the call is self-describing even when fired as a
+session is being torn down. The request is admin-gated server-side; the
+`User: NUID` header is pinned to the `actor_nuid` you pass.
+
+```ruby
+# An admin starts acting as another user:
+AtlasRb::AuditEvent.emit(
+  action:            "impersonation_started",
+  actor_nuid:        Current.nuid,   # the admin (also the User: header)
+  on_behalf_of_nuid: target_nuid,    # the impersonated user
+  mode:              "acting_as"      # or "view_as"
+)
+
+# …and later ends the session:
+AtlasRb::AuditEvent.emit(
+  action:            "impersonation_ended",
+  actor_nuid:        admin_nuid,
+  on_behalf_of_nuid: target_nuid,
+  mode:              "acting_as"
+)
+```
+
+`on_behalf_of_nuid`, `mode`, and `payload:` (free-form metadata) are
+omitted from the body when blank, so `emit` can also carry future,
+mode-less session events. Atlas stamps `occurred_at` server-side.
+Authorization errors (`401` / `403`) surface as raw Faraday responses,
+matching `Resource.history`.
+
 ### Re-parenting
 
 `reparent` moves a resource to a new structural parent, binding Atlas's
@@ -272,6 +312,27 @@ The two mutations raise the same way `reparent` does — `LinkedMemberError`
 on a structural `422` (carrying the envelope's `error` code as `#code`) and
 `ForbiddenError` on a `403` — instead of swallowing the envelope.
 
+### Batch resolve (`Resource.find_many`)
+
+When you have a *set* of NOIDs and only need each one's title / klass /
+thumbnail — breadcrumb chains, linked-member lists, load-destination
+pickers — resolve them in one round-trip instead of a `find`-per-id
+fan-out:
+
+```ruby
+nodes   = AtlasRb::Resource.find_many(["col-456", "col-457", "missing"])
+by_noid = nodes.index_by { |n| n["noid"] }
+by_noid["col-456"].title   # => "Some Collection"
+```
+
+Each entry is a lightweight digest — `{ "id", "noid", "klass", "title",
+"thumbnail", "tombstoned" }` — not the full typed payload. The ids travel
+in the request body (no URL-length ceiling). The result is **unordered**
+and **may be shorter than the input**: unresolvable ids are dropped and
+tombstoned resources come back flagged (`"tombstoned" => true`), so index
+by `"noid"` rather than assuming positional correspondence. NOIDs only —
+raw Valkyrie ids are not a supported input.
+
 ## End-to-end example
 
 JSON responses come back as `AtlasRb::Mash` (a `Hashie::Mash` subclass), so

data/lib/atlas_rb/audit_event.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module AtlasRb
+  # Session-scoped AuditEvent emit — record an audit event that is **not**
+  # tied to a resource write.
+  #
+  # ## Why this exists
+  #
+  # Every other AuditEvent in Atlas is a side effect of a resource mutation
+  # (`create`, `update`, `tombstone`, …) and is read back per-resource via
+  # {AtlasRb::Resource.history} (`GET /resources/<id>/history`). Some
+  # auditable events have **no resource to hang on**: impersonation sessions.
+  # An admin starting/ending an acting-as or view-as session is a security
+  # event worth recording, but view-as performs no writes at all, and the
+  # session lifecycle lives entirely in the calling application (a cookie),
+  # so there is no resource mutation to attach the event to.
+  #
+  # This binding wraps Atlas's `POST /audit_events` emit endpoint, which
+  # writes an AuditEvent with a **null `resource_id`** (a session-scoped
+  # event). The recorded principals are passed explicitly in the body rather
+  # than inferred from request headers, so the call is self-describing and
+  # does not depend on the ambient {AtlasRb.config} identity being intact at
+  # emit time (it may not be — e.g. an `impersonation_ended` emit fires as
+  # the session is being torn down).
+  #
+  # ## Authorization
+  #
+  # The endpoint is system-token + admin-gated. The request authenticates via
+  # the standard {FaradayHelper#connection} — the `Authorization: Bearer`
+  # token plus a `User: NUID <admin>` header pinned to `actor_nuid` — and
+  # Atlas gates the emit to admin operators. `actor_nuid` is passed
+  # explicitly (rather than left to {AtlasRb.config}.default_nuid) so the
+  # admin gate holds even when the ambient session identity is mid-teardown,
+  # as it is for an `impersonation_ended` emit. The same `actor_nuid` is the
+  # principal recorded on the event.
+  #
+  # @example Recording the start of an acting-as session (from Cerberus)
+  #   AtlasRb::AuditEvent.emit(
+  #     action:            "impersonation_started",
+  #     actor_nuid:        Current.nuid,          # the admin
+  #     on_behalf_of_nuid: target_nuid,           # the impersonated user
+  #     mode:              "acting_as"
+  #   )
+  #
+  # @example Recording the end of a view-as session
+  #   AtlasRb::AuditEvent.emit(
+  #     action:            "impersonation_ended",
+  #     actor_nuid:        admin_nuid,
+  #     on_behalf_of_nuid: target_nuid,
+  #     mode:              "view_as"
+  #   )
+  class AuditEvent
+    extend AtlasRb::FaradayHelper
+
+    # Atlas REST endpoint for the session-scoped emit.
+    # @api private
+    ROUTE = "/audit_events"
+
+    # Emit a session-scoped AuditEvent (one with no resource scope).
+    #
+    # Wraps `POST /audit_events`. The principals and metadata travel in the
+    # JSON body — not in request headers — so the recorded event does not
+    # depend on the ambient {AtlasRb.config} identity. The request still
+    # authenticates as the configured caller (system token + the admin
+    # `User:` header); Atlas admin-gates the endpoint server-side.
+    #
+    # Atlas stamps `occurred_at` server-side, so it is not part of the body.
+    #
+    # Authorization errors (`401` / `403`) are intentionally **not** caught
+    # here — they surface as raw Faraday responses for the calling
+    # application's rescue layer to translate, matching
+    # {AtlasRb::Resource.history}.
+    #
+    # @param action [String] the audit action, e.g. `"impersonation_started"`
+    #   or `"impersonation_ended"`.
+    # @param actor_nuid [String] NUID of the principal performing the action
+    #   (the admin, in the impersonation flow).
+    # @param on_behalf_of_nuid [String, nil] NUID of the attribution target
+    #   (the impersonated user). Omitted from the body when `nil`.
+    # @param mode [String, nil] session mode, e.g. `"acting_as"` or
+    #   `"view_as"`. Omitted from the body when `nil` so the binding can also
+    #   carry future, mode-less session events.
+    # @param payload [Hash] optional free-form metadata to record alongside
+    #   the event. Omitted from the body when empty.
+    # @return [AtlasRb::Mash] the parsed envelope returned by
+    #   `POST /audit_events` (the created event).
+    #
+    # @example
+    #   AtlasRb::AuditEvent.emit(
+    #     action:            "impersonation_started",
+    #     actor_nuid:        "000000001",
+    #     on_behalf_of_nuid: "000000123",
+    #     mode:              "acting_as"
+    #   )
+    def self.emit(action:, actor_nuid:, on_behalf_of_nuid: nil, mode: nil, payload: {})
+      body = {
+        action: action,
+        actor_nuid: actor_nuid,
+        on_behalf_of_nuid: on_behalf_of_nuid,
+        mode: mode,
+        payload: (payload unless payload.nil? || payload.empty?)
+      }.compact
+
+      AtlasRb::Mash.new(JSON.parse(
+        connection({}, actor_nuid).post(ROUTE, JSON.dump(body))&.body
+      ))
+    end
+  end
+end

data/lib/atlas_rb/resource.rb

@@ -47,6 +47,44 @@ module AtlasRb
                         "resource" => result.first[1])
     end
 
+    # Resolve many resources by NOID in a single round-trip.
+    #
+    # Wraps Atlas's `POST /resources/find_many`, which returns one lightweight
+    # digest per resolvable resource — `{ "id", "noid", "klass", "title",
+    # "thumbnail", "tombstoned" }` — rather than full typed payloads. Use it
+    # anywhere a set of ids would otherwise be resolved with a `find`-per-id
+    # fan-out (breadcrumb chains, linked-member lists, load-destination
+    # pickers): one HTTP call instead of N.
+    #
+    # The ids travel in the request **body**, so the list is not bounded by
+    # URL length. The result is **unordered** and **may be shorter than the
+    # input** — unresolvable ids are dropped silently, and tombstoned
+    # resources come back flagged (`"tombstoned" => true`) rather than
+    # omitted. Index the result by `"noid"`; do not assume positional
+    # correspondence with `ids`.
+    #
+    # @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 on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
+    #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
+    #   omitted.
+    # @return [Array<AtlasRb::Mash>] one digest Mash per resolved resource
+    #   (dot- or string-keyed access); empty when nothing resolved.
+    #
+    # @example Resolve a set of collection titles in one call
+    #   nodes  = AtlasRb::Resource.find_many(["col-456", "col-457", "missing"])
+    #   by_noid = nodes.index_by { |n| n["noid"] }
+    #   by_noid["col-456"].title   # => "Some Collection"
+    def self.find_many(ids, nuid: nil, on_behalf_of: nil)
+      JSON.parse(
+        connection({}, nuid, on_behalf_of: on_behalf_of)
+          .post('/resources/find_many', JSON.dump(ids: Array(ids)))&.body
+      ).map { |node| AtlasRb::Mash.new(node) }
+    end
+
     # Validate a MODS XML document against Atlas's schema *without* persisting it.
     #
     # Useful for surfacing validation errors in UIs before the user commits.

data/lib/atlas_rb.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.3.0
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-03 00:00:00.000000000 Z
+date: 2026-06-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -119,6 +119,7 @@ files:
 - lib/atlas_rb/admin/collection.rb
 - lib/atlas_rb/admin/community.rb
 - lib/atlas_rb/admin/work.rb
+- lib/atlas_rb/audit_event.rb
 - lib/atlas_rb/authentication.rb
 - lib/atlas_rb/blob.rb
 - lib/atlas_rb/collection.rb