@cohesionauth/react

Save humanity by keeping human judgment alive in the age of AI.

Official React bindings for the COHESION Judgment Independence Score API. Presentation-only components and hooks for live AI-decision review, queue dashboards, and audit drawers -- fully accessible (WCAG 2.1 AA), Tailwind-agnostic, edge-isolate compatible.

Status

v0.2.0 -- implementation landed 2026-05-13. 7 named exports shipped, axe-clean, StrictMode-safe. Publish is operator-gated (npm publish --access public after npm run build generates dist/).

Install

npm install @cohesionauth/react @cohesionauth/sdk react react-dom

@cohesionauth/sdk, react, and react-dom are peer dependencies. focus-trap-react is bundled as a runtime dep for <CohesionAuditDrawer>.

Surface (v0.2.0)

| Export | Type | Purpose | |---|---|---| | <CohesionProvider client> | Component | Wraps the tree with a shared Cohesion client. | | useCohesionClient(override?) | Hook | Reads the client from context; per-call prop overrides. | | useCohesionScore(decisionId, options?) | Hook | Fetches one decision via client.getDecision. | | useCohesionQueue(options?) | Hook | Cursor-paginated queue via client.decisionQueue. | | <CohesionRiskBadge> | Component | Stateless tier badge. | | <CohesionReviewPanel> | Component | Composes badge + score; approve/reject callbacks. | | <CohesionAuditDrawer> | Component | Slide-over with paginated queue; native <dialog>. | | CohesionContextError | Error class | Thrown when no provider + no override is in scope. |

Quick start

Security -- never ship a COHESION org API key to a browser. The @cohesionauth/sdk client sends an org-scoped X-API-Key on every request. Inlining that key into a React bundle (NEXT_PUBLIC_*, VITE_*, build-time process.env.*, etc.) leaks it to every end user and lets anyone read your org's review queue. Always proxy through your own backend (Next.js Route Handler, Express, Hono, Cloudflare Worker, ...) and inject the COHESION key server-side. The examples below show the supported pattern.

1. Browser -- point the SDK client at your own backend proxy

import { Cohesion } from "@cohesionauth/sdk";
import {
  CohesionProvider,
  CohesionReviewPanel,
  CohesionAuditDrawer,
} from "@cohesionauth/react";

// `baseUrl` points at YOUR backend proxy (next step). The `apiKey`
// value is required by the client's input validator but is NEVER read on
// the wire when the request is intercepted server-side -- your proxy
// injects the real key. Treat the placeholder as opaque, not a secret.
const client = new Cohesion({
  apiKey: "browser-proxy",
  baseUrl: "/api/cohesion",
});

export function App() {
  const [drawerOpen, setDrawerOpen] = useState(false);
  const triggerRef = useRef<HTMLButtonElement>(null);

  return (
    <CohesionProvider client={client}>
      <CohesionReviewPanel
        decisionId="dec_01HX..."
        onApprove={(decision) => fetch("/api/commit", { method: "POST", body: JSON.stringify(decision) })}
        onReject={(decision, reason) => fetch("/api/reject", { method: "POST", body: JSON.stringify({ decision, reason }) })}
      />

      <button ref={triggerRef} onClick={() => setDrawerOpen(true)}>
        Open audit log
      </button>

      <CohesionAuditDrawer
        open={drawerOpen}
        onOpenChange={setDrawerOpen}
        triggerRef={triggerRef}
        description="Recent decisions awaiting human review."
        limit={25}
      />
    </CohesionProvider>
  );
}

2. Server -- proxy with the COHESION key injected (Next.js example)

// app/api/cohesion/[...path]/route.ts
export const runtime = "nodejs"; // or "edge" -- both work

async function proxy(req: Request, ctx: { params: { path: string[] } }) {
  // Apply YOUR app's auth here (session cookie, OAuth, RBAC, ...) before
  // forwarding. The COHESION key authorizes your *org*; your proxy is the
  // boundary that authorizes the *user* hitting it.
  const upstream = `https://api.cohesionauth.com/${ctx.params.path.join("/")}`;
  const body = req.method === "GET" ? undefined : await req.text();
  const headers: Record<string, string> = {
    "Content-Type": "application/json",
    "X-API-Key": process.env.COHESION_API_KEY!, // server-side env var only
  };
  const reqId = req.headers.get("X-Request-ID");
  if (reqId) headers["X-Request-ID"] = reqId; // preserve correlation
  const res = await fetch(upstream, { method: req.method, headers, body });
  return new Response(res.body, { status: res.status, headers: res.headers });
}

export { proxy as GET, proxy as POST };

Equivalent patterns work for Express, Hono, and Cloudflare Workers. The COHESION API key must live in a server-side environment variable (process.env.COHESION_API_KEY on Node, env.COHESION_API_KEY on Workers) -- never in code that ships to a browser bundle.

Hooks

useCohesionScore(decisionId, options?)

Fetches a single decision envelope. StrictMode-safe; AbortError results are dropped silently.

const { status, data, error, refetch } = useCohesionScore(decisionId, {
  refetchInterval: 10_000,            // ms; floor 5000
  refetchOnWindowFocus: true,         // default
  refetchIntervalInBackground: false, // default
});

if (status === "loading") return <Spinner />;
if (status === "error") return <Error err={error} />;
return <CohesionReviewPanel decisionId={decisionId} />;

useCohesionQueue(options?)

Cursor-paginated review queue. loadMore() is idempotent -- calling it while a page is in flight is silently ignored.

const { status, data, loadMore, isLoadingMore } = useCohesionQueue({
  tier: "high",
  limit: 25,
});

// Multi-page audit trail; each row preserves its original request_id.
data?.rows.forEach((row) => console.log(row.id, row.request_id));

Multi-tenant escape hatch

Every hook and component accepts an optional client prop. When provided, it wins over the <CohesionProvider> context -- useful for per-call tenant switches inside an admin UI:

<CohesionReviewPanel
  decisionId="dec_01HX..."
  client={tenantBClient} // overrides context client for this panel only
/>

Accessibility

• <CohesionRiskBadge> uses role="status" + aria-atomic="true"; the tier label is always present in the accessibility tree (visually-hidden when showScore: false). Score is clamped to [0, 100].
• <CohesionReviewPanel> is a role="region" with an aria-labelledby heading. Action buttons are type="button" and disabled while loading regardless of readOnly. Errors render with role="alert".
• <CohesionAuditDrawer> uses the native <dialog> element with aria-modal="true", focus-trapped via focus-trap-react, body scroll locked while open, Escape closes the dialog, and focus returns to triggerRef.current on close.
• axe-core vitest assertions cover every render path of every component (zero violations required to land).

Why presentation-only

The COHESION methodology, scoring engine, and intervention protocol live server-side at api.cohesionauth.com and in @cohesionauth/sdk. This package fires callbacks; consumers wire mutations. No scoring math runs client-side. Patent scope, audit integrity, and tamper resistance all depend on this discipline.

Peer dependencies

• react >=18.0.0
• react-dom >=18.0.0
• @cohesionauth/sdk >=1.5.0 <2.0.0

License

Apache-2.0. Copyright 2026 COHESION AUTH LLC. The COHESION methodology is subject to provisional patent filed 2026-04-13.