feat(webui): centralize resource access explanations

webui/src/api/resourceAccess.ts

@@ -0,0 +1,35 @@
+import type { ApiSettings } from "../types";
+import { apiFetch, apiPath } from "./client";
+import type {
+  AccessDecisionProvenanceItem,
+  ResourceAccessExplanationOptions,
+  ResourceAccessExplanationResponse,
+  ResourceAccessExplanationUser
+} from "./resourceAccessContracts";
+export type {
+  AccessDecisionProvenanceItem,
+  ResourceAccessExplanationOptions,
+  ResourceAccessExplanationResponse,
+  ResourceAccessExplanationUser
+} from "./resourceAccessContracts";
+
+/**
+ * Fetches the platform's optional resource-access explanation endpoint.
+ * Core owns the transport contract without requiring the Access module that
+ * contributes the endpoint at runtime.
+ */
+export function fetchResourceAccessExplanation<
+  TUser extends ResourceAccessExplanationUser = ResourceAccessExplanationUser,
+  TProvenance extends AccessDecisionProvenanceItem = AccessDecisionProvenanceItem
+>(
+  settings: ApiSettings,
+  options: ResourceAccessExplanationOptions
+): Promise<ResourceAccessExplanationResponse<TUser, TProvenance>> {
+  return apiFetch(settings, apiPath("/api/v1/admin/access/resource-explanation", {
+    user_id: options.userId,
+    resource_type: options.resourceType,
+    resource_id: options.resourceId,
+    action: options.action,
+    tenant_id: options.tenantId
+  }));
+}

webui/src/api/resourceAccessContracts.ts

@@ -0,0 +1,34 @@
+export type ResourceAccessExplanationUser = {
+  id: string;
+  account_id?: string | null;
+  email?: string | null;
+  display_name?: string | null;
+};
+
+export type AccessDecisionProvenanceItem = {
+  kind: string;
+  id?: string | null;
+  label?: string | null;
+  tenant_id?: string | null;
+  source?: string | null;
+  details?: Record<string, unknown>;
+};
+
+export type ResourceAccessExplanationResponse<
+  TUser extends ResourceAccessExplanationUser = ResourceAccessExplanationUser,
+  TProvenance extends AccessDecisionProvenanceItem = AccessDecisionProvenanceItem
+> = {
+  user: TUser;
+  resource_type: string;
+  resource_id: string;
+  action: string;
+  provenance: TProvenance[];
+};
+
+export type ResourceAccessExplanationOptions = {
+  userId: string;
+  resourceType: string;
+  resourceId: string;
+  action: string;
+  tenantId?: string | null;
+};