@volidator/react

React hooks for the Volidator embedded audit log widget.

This package handles the JIT (Just-In-Time) Hydration postMessage handshake between your React application and the Volidator embed iframe. It resolves encrypted reference IDs ([REF:userId]) to human-readable display names at render time — without PII ever reaching Volidator's servers.

Install

npm install @volidator/react

React 17+ is required as a peer dependency.

useVolidatorHydration

Drop this hook into the page that embeds the Volidator audit log iframe. It automatically manages the entire postMessage lifecycle.

import { useRef } from "react";
import { useVolidatorHydration } from "@volidator/react";

export function AuditLogPage({ embedUrl }: { embedUrl: string }) {
  const iframeRef = useRef<HTMLIFrameElement>(null);

  useVolidatorHydration({
    iframeRef,
    volidatorOrigin: "https://dash.volidator.com",
    resolveActors: async (ids) => {
      // Called with a deduplicated batch of reference IDs from the decrypted logs.
      // You resolve them against your own user database.
      const res = await fetch("/api/users/resolve", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ ids }),
      });
      return res.json();
      // Expected shape: { "usr_890": { name: "Alice Smith", avatarUrl: "..." } }
    },
  });

  return (
    <iframe
      ref={iframeRef}
      src={embedUrl}
      style={{ width: "100%", height: 600, border: "none" }}
    />
  );
}

Options

| Option | Type | Required | Description | |---|---|---|---| | iframeRef | RefObject<HTMLIFrameElement> | ✅ | Ref pointing to the Volidator embed <iframe>. | | volidatorOrigin | string | ✅ | Exact origin of the Volidator dashboard (e.g. "https://dash.volidator.com"). Wildcard "*" is not accepted. | | resolveActors | (ids: string[]) => Promise<ActorResolutionMap> | ✅ | Callback that resolves reference IDs to display identities. Called with only uncached IDs. | | encryptionKey | string | — | Plaintext DEK to pass to the iframe if using client-side E2EE. |

ActorResolutionMap

type ActorResolutionMap = Record<string, {
  name: string;
  avatarUrl?: string;  // Optional URL shown as an avatar in the dashboard table
}>;

How JIT Hydration works

1. You configure referenceKeys: ["actor"] in VolidatorClient on your server.
2. You pass actor: { id: "usr_890", pii: "[email protected]" } when logging.
3. Volidator stores [REF:usr_890] in the encrypted payload — PII never leaves your server.
4. When the dashboard iframe decrypts a log and finds [REF:usr_890], it sends a VOLIDATOR_RESOLVE_ACTORS postMessage to the parent page.
5. useVolidatorHydration intercepts the message, calls your resolveActors(["usr_890"]) callback, and posts the display name back into the iframe.

→ Full JIT Hydration guide

License

MIT © Volidator Contributors