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;

webui/src/components/ResourceAccessExplanation.tsx

@@ -1,21 +1,62 @@
 import ContentGrid, { FormGrid } from "./ContentGrid";
-import type { ResourceAccessExplanationResponse } from "../api/resourceAccessContracts";
+import FormField from "./FormField";
+import type {
+  ResourceAccessExplanationResponse,
+  ResourceAccessExplanationSubjectsResponse
+} from "../api/resourceAccessContracts";
 
 export type ResourceAccessExplanationProps = {
   loading?: boolean;
   explanation?: ResourceAccessExplanationResponse | null;
+  subjects?: ResourceAccessExplanationSubjectsResponse | null;
+  selectedUserId?: string;
+  onSelectedUserIdChange?: (userId: string) => void;
   fallbackResourceLabel?: string;
 };
 
 export default function ResourceAccessExplanation({
   loading = false,
   explanation,
+  subjects,
+  selectedUserId,
+  onSelectedUserIdChange,
   fallbackResourceLabel = ""
 }: ResourceAccessExplanationProps) {
   if (loading) {
     return <p className="muted small-note">i18n:govoplan-core.loading_access_explanation.04a7c934</p>;
   }
-  if (!explanation) return null;
+  if (!explanation && !subjects) return null;
+
+  const selectable = Boolean(
+    subjects?.can_select_other_users && onSelectedUserIdChange
+  );
+  const selectedSubjectId = selectedUserId || explanation?.user.id || subjects?.users[0]?.id || "";
+
+  const subjectControl = subjects ? (
+    <div data-resource-access-subject-mode={subjects.mode}>
+      {selectable ? (
+        <FormField
+          label="i18n:govoplan-core.explanation_subject.6ff46d22"
+          helpContextId="access.resource-explanation.subject"
+          helpModuleId="access"
+        >
+          <select
+            value={selectedSubjectId}
+            onChange={(event) => onSelectedUserIdChange?.(event.target.value)}
+          >
+            {subjects.users.map((user) => (
+              <option key={user.id} value={user.id}>
+                {user.display_name || user.email || user.id}
+              </option>
+            ))}
+          </select>
+        </FormField>
+      ) : null}
+      <p className="muted small-note">{subjects.reason}</p>
+    </div>
+  ) : null;
+
+  if (!explanation) return subjectControl;
 
   const userLabel = explanation.user.display_name || explanation.user.email || explanation.user.id;
   const resourceLabel = explanation.provenance.find((item) => item.kind === "resource")?.label ||
@@ -24,6 +65,7 @@ export default function ResourceAccessExplanation({
 
   return (
     <>
+      {subjectControl}
       <FormGrid columns={2} collapseAt="wide" className="">
         <div><span className="form-label">i18n:govoplan-core.user.9f8a2389</span><p>{userLabel}</p></div>
         <div><span className="form-label">i18n:govoplan-core.resource.d1c626a9</span><p>{resourceLabel}</p></div>

webui/tests/resource-access-explanation.test.tsx

@@ -47,6 +47,42 @@ assert(explanationMarkup.includes("i18n:govoplan-core.no_source.6dcf9723"), "mis
 assert(!explanationMarkup.includes("govoplan-campaign"), "the shared component does not depend on Campaign wording");
 assert(!explanationMarkup.includes("govoplan-files"), "the shared component does not depend on Files wording");
 
+const selectableSubjectMarkup = renderToStaticMarkup(
+  <ResourceAccessExplanation
+    explanation={null}
+    subjects={{
+      mode: "cross_user",
+      can_select_other_users: true,
+      reason: "Policy permits an administrator diagnostic.",
+      source: "policy.permission",
+      required_scope: "policy:access_explanation:select_user",
+      users: [
+        { id: "user-1", display_name: "Current Reader" },
+        { id: "user-2", email: "other@example.test" }
+      ]
+    }}
+    selectedUserId="user-2"
+    onSelectedUserIdChange={() => undefined}
+  />
+);
+assert(selectableSubjectMarkup.includes("<select"), "the shared component owns the subject picker");
+assert(selectableSubjectMarkup.includes("other@example.test"), "permitted subject metadata is rendered");
+assert(selectableSubjectMarkup.includes("Policy permits"), "the policy reason remains visible");
+
+const currentUserSubjectMarkup = renderToStaticMarkup(
+  <ResourceAccessExplanation
+    subjects={{
+      mode: "current_user",
+      can_select_other_users: false,
+      reason: "Policy limits explanations to the signed-in user.",
+      source: "policy.permission",
+      users: [{ id: "user-1", display_name: "Current Reader" }]
+    }}
+  />
+);
+assert(!currentUserSubjectMarkup.includes("<select"), "current-user mode does not expose a directory picker");
+assert(currentUserSubjectMarkup.includes("signed-in user"), "current-user policy is explained");
+
 const emptyMarkup = renderToStaticMarkup(
   <ResourceAccessExplanation
     fallbackResourceLabel="Fallback resource"