@dreadkn1ght123/auth-react

React 18/19 adapter for the server-owned VVP authentication flow. It checks the token-free session endpoint with credentials included, redirects signed-out users through /auth/start, and submits logout to /auth/logout. Login is always a browser navigation—never fetch or XHR.

Install the aligned 0.2.0 release alongside @dreadkn1ght123/auth-types, @dreadkn1ght123/auth-core, and @dreadkn1ght123/auth-express. The Express router must be mounted on the same public origin. Custom backend route paths must also be supplied via the corresponding meUrl, loginUrl, and logoutUrl frontend props/options.

React + Vite

import {
  VvpAuthBoundary,
  VvpAuthProvider,
  useVvpAuth,
} from "@dreadkn1ght123/auth-react";
import { createRoot } from "react-dom/client";

function App() {
  const auth = useVvpAuth<{ actor: { displayName: string } }>();

  return (
    <main>
      <p>Signed in as {auth.session?.actor.displayName}</p>
      <button type="button" onClick={() => void auth.logout()}>
        Sign out
      </button>
    </main>
  );
}

createRoot(document.getElementById("root")!).render(
  <VvpAuthProvider meUrl="/auth/me">
    <VvpAuthBoundary>
      <App />
    </VvpAuthBoundary>
  </VvpAuthProvider>,
);

The Express application must mount the VVP auth router on the same origin. There is no application login page: an unauthenticated boundary performs top-level navigation to /auth/start and preserves a validated same-origin returnTo. If iframe escape is blocked, it renders an accessible target="_top" fallback link.

VvpAuthBoundary waits for the session check before deciding. A 401 initiates login; a network/5xx or malformed response renders retry/error fallback instead of redirecting. A short-lived per-tab marker prevents repeated automatic redirects to the same returnTo; if encountered, the boundary renders the manual top-level link. Successful authentication clears that marker.

For an imperative transition, use:

import { redirectToVvpLogin } from "@dreadkn1ght123/auth-react";

redirectToVvpLogin({
  returnTo: window.location.href,
  escapeIframe: true,
});

The imperative helper returns { url, navigated, error? }. If navigated is false, render url only as an ordinary same-origin link with target="_top"; prefer VvpLoginRedirect when the component should manage this fallback.

logoutFromVvp() creates a top-targeted POST form. It intentionally leaves the browser in the server-managed provider logout and /auth/signed-out flow. That signed-out page does not automatically run the boundary or restart SSO; the user explicitly chooses “sign in again”.

VvpLoginRedirect is available when only the navigation/fallback behavior is needed. Its fallback child may customize presentation, but applications must not recreate an SSO provider chooser, construct an IAM authorization URL, or send protocol values to React.