@mmgt-cloud/auth-react

Headless React bindings for @mmgt-cloud/auth-client. The package provides a single session provider and small hooks for common auth flows while keeping all wire-level API behavior in the framework-agnostic auth client.

Install

pnpm add @mmgt-cloud/auth-client @mmgt-cloud/auth-react

Requires React 19 and a configured AuthClient or clientOptions. No .npmrc, GitHub account, or access token is required. Public exports include AuthProvider, authentication/session/action hooks, the observable token store, and their types. Licensed under MIT.

import {
  AuthProvider,
  useLogin,
  useSession
} from "@mmgt-cloud/auth-react";
import { createUnsafeBrowserLocalStorageTokenStore } from "@mmgt-cloud/auth-client";

const baseUrl = "https://api.example.invalid/auth";
const appId = "00000000-0000-4000-8000-000000000001";
const clientOptions = {
  baseUrl,
  appId,
  tokenStore: createUnsafeBrowserLocalStorageTokenStore({
    key: `mmgt.auth:${encodeURIComponent(baseUrl)}:${appId}`
  })
};

function Root() {
  return (
    <AuthProvider
      clientOptions={clientOptions}
      loadProfileOnStart
    >
      <App />
    </AuthProvider>
  );
}

function App() {
  const { status, profile, isAuthenticated } = useSession();
  const login = useLogin();

  if (status === "loading") return null;
  if (!isAuthenticated) {
    return <>
      <button disabled={login.pending} onClick={() => {
        void login.submit({ email: "[email protected]", password: "user-entered-password" }).catch(() => {});
      }}>Sign in</button>
      {login.error ? <p>Sign-in failed.</p> : null}
      {login.result && login.result.kind !== "success" ? <p>Continue: {login.result.kind}</p> : null}
    </>;
  }
  return <span>{profile?.email}</span>;
}

Replace the demonstration credentials with form input and render the appropriate MFA, enrollment or password-reset flow from login.result. Enrollment credentials do not create an authenticated provider session. Complete setup with a separate memory-only AuthClient, then sign in again and complete MFA; see the auth-client README. Create stable client options per environment/application, and recreate account-owned consumers on account changes. The unsafe browser store explicitly opts into localStorage; a BFF/httpOnly-cookie strategy can avoid that storage choice.

Hooks

• useAuth() returns the full context: client, tokens, profile, status, profile refresh, token setters, and session clearing.
• useSession() returns the stable session snapshot for rendering.
• useLogin(), useLogout(), useRegister(), useMagicLink(), and usePasswordReset() wrap common account actions.
• usePasskeyLogin() and usePasskeyRegistration() delegate WebAuthn work to @mmgt-cloud/auth-client.
• useOAuthRedirect() parses callback URLs, exchanges one-time OAuth callback codes when present, stores returned tokens, and can optionally clear the URL.
• useRequireAuth() exposes route guard state without coupling to a router.

Design Notes

This package does not render UI, does not own routing, and does not replace @mmgt-cloud/auth-client. It only centralizes React lifecycle concerns: stable client construction, token store subscription via useSyncExternalStore, profile loading, session expiry handling, and cleanup-safe hook actions.