feat: centralize access explanation subject selection

webui/src/api/resourceAccess.ts

@@ -4,12 +4,16 @@ import type {
   AccessDecisionProvenanceItem,
   ResourceAccessExplanationOptions,
   ResourceAccessExplanationResponse,
+  ResourceAccessExplanationSubjectsOptions,
+  ResourceAccessExplanationSubjectsResponse,
   ResourceAccessExplanationUser
 } from "./resourceAccessContracts";
 export type {
   AccessDecisionProvenanceItem,
   ResourceAccessExplanationOptions,
   ResourceAccessExplanationResponse,
+  ResourceAccessExplanationSubjectsOptions,
+  ResourceAccessExplanationSubjectsResponse,
   ResourceAccessExplanationUser
 } from "./resourceAccessContracts";
 
@@ -33,3 +37,20 @@ export function fetchResourceAccessExplanation<
     tenant_id: options.tenantId
   }));
 }
+
+/**
+ * Returns only the explanation subjects the active policy permits the actor to
+ * inspect. A current-user-only response deliberately contains no directory
+ * metadata for other users.
+ */
+export function fetchResourceAccessExplanationSubjects<
+  TUser extends ResourceAccessExplanationUser = ResourceAccessExplanationUser
+>(
+  settings: ApiSettings,
+  options: ResourceAccessExplanationSubjectsOptions = {}
+): Promise<ResourceAccessExplanationSubjectsResponse<TUser>> {
+  return apiFetch(settings, apiPath("/api/v1/admin/access/resource-explanation/subjects", {
+    tenant_id: options.tenantId,
+    query: options.query
+  }));
+}

webui/src/api/resourceAccessContracts.ts

@@ -25,6 +25,22 @@ export type ResourceAccessExplanationResponse<
   provenance: TProvenance[];
 };
 
+export type ResourceAccessExplanationSubjectsResponse<
+  TUser extends ResourceAccessExplanationUser = ResourceAccessExplanationUser
+> = {
+  mode: "current_user" | "cross_user";
+  can_select_other_users: boolean;
+  reason: string;
+  source: string;
+  required_scope?: string | null;
+  users: TUser[];
+};
+
+export type ResourceAccessExplanationSubjectsOptions = {
+  tenantId?: string | null;
+  query?: string | null;
+};
+
 export type ResourceAccessExplanationOptions = {
   userId: string;
   resourceType: string;