@nexauthxyz/react 0.1.2

package/dist/tab-sync.js

@@ -0,0 +1,105 @@
+const STORAGE_EVENT_PREFIX = 'nexauth:tab-sync';
+function isTabEvent(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const record = value;
+    return (record.type === 'logout' &&
+        typeof record.source === 'string' &&
+        typeof record.timestamp === 'number');
+}
+function createSourceId() {
+    if (globalThis.crypto && typeof globalThis.crypto.randomUUID === 'function') {
+        return globalThis.crypto.randomUUID();
+    }
+    return `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}
+export class NexAuthTabSync {
+    source = createSourceId();
+    channelName;
+    storageKey;
+    onEvent;
+    channel;
+    constructor(channelName, onEvent) {
+        this.channelName = channelName;
+        this.storageKey = `${STORAGE_EVENT_PREFIX}:${channelName}`;
+        this.onEvent = onEvent;
+        if (typeof globalThis.BroadcastChannel === 'function') {
+            this.channel = new BroadcastChannel(channelName);
+            this.channel.addEventListener('message', this.handleBroadcastMessage);
+        }
+        else {
+            this.channel = null;
+        }
+        if (typeof window !== 'undefined') {
+            window.addEventListener('storage', this.handleStorageEvent);
+        }
+    }
+    publishLogout() {
+        const event = {
+            source: this.source,
+            type: 'logout',
+            timestamp: Date.now(),
+        };
+        if (this.channel) {
+            try {
+                this.channel.postMessage(event);
+                return;
+            }
+            catch {
+                /*
+                 * Fall through to the localStorage transport.
+                 */
+            }
+        }
+        if (typeof window === 'undefined' || window.localStorage === undefined) {
+            return;
+        }
+        try {
+            window.localStorage.setItem(this.storageKey, JSON.stringify(event));
+            /*
+             * The storage event is sent to other tabs only. Removing the
+             * temporary value keeps localStorage free of stale SDK data.
+             */
+            window.localStorage.removeItem(this.storageKey);
+        }
+        catch {
+            /*
+             * Cross-tab synchronization is best-effort. Authentication
+             * and logout must still work when localStorage is unavailable.
+             */
+        }
+    }
+    close() {
+        if (this.channel) {
+            this.channel.removeEventListener('message', this.handleBroadcastMessage);
+            this.channel.close();
+        }
+        if (typeof window !== 'undefined') {
+            window.removeEventListener('storage', this.handleStorageEvent);
+        }
+    }
+    handleBroadcastMessage = (message) => {
+        this.receive(message.data);
+    };
+    handleStorageEvent = (event) => {
+        if (event.key !== this.storageKey || event.newValue === null) {
+            return;
+        }
+        try {
+            this.receive(JSON.parse(event.newValue));
+        }
+        catch {
+            /*
+             * Ignore malformed cross-tab events.
+             */
+        }
+    };
+    receive(value) {
+        if (!isTabEvent(value) || value.source === this.source) {
+            return;
+        }
+        this.onEvent(value.type);
+    }
+}
+//# sourceMappingURL=tab-sync.js.map

package/dist/tab-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tab-sync.js","sourceRoot":"","sources":["../src/tab-sync.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,87 @@
+import type { ReactNode } from 'react';
+import type { AuthenticationStatus, AuthorizationCallbackInput, AuthorizationCallbackResult, LoginOptions, LogoutOptions, NexAuthBrowserClient, NexAuthBrowserClientOptions, NexAuthError, NexAuthSession, NexAuthUser } from '@nexauthxyz/browser';
+export type NexAuthReactClient = Pick<NexAuthBrowserClient, 'getSession' | 'login' | 'handleCallback' | 'logout' | 'clearLocalSession'>;
+export interface NexAuthProviderProps {
+    readonly children: ReactNode;
+    readonly options: NexAuthBrowserClientOptions;
+    /**
+     * Synchronize logout across tabs on the same origin.
+     *
+     * Defaults to true.
+     */
+    readonly syncTabs?: boolean;
+    /**
+     * Optional BroadcastChannel name.
+     *
+     * Defaults to a client-specific NexAuth channel.
+     */
+    readonly tabSyncChannel?: string;
+    /**
+     * Optional compatible client instance.
+     *
+     * Useful for testing or advanced dependency injection.
+     */
+    readonly client?: NexAuthReactClient;
+    readonly onError?: (error: NexAuthError) => void;
+}
+export interface NexAuthContextValue {
+    readonly status: AuthenticationStatus;
+    readonly session: NexAuthSession | null;
+    readonly user: NexAuthUser | null;
+    readonly accessToken: string | null;
+    readonly error: NexAuthError | null;
+    readonly isLoading: boolean;
+    readonly isAuthenticated: boolean;
+    login(options?: LoginOptions): Promise<void>;
+    handleCallback(input?: AuthorizationCallbackInput): Promise<AuthorizationCallbackResult>;
+    logout(options?: LogoutOptions): Promise<void>;
+    /**
+     * Re-read the session currently held by the browser SDK.
+     */
+    refreshSession(): NexAuthSession | null;
+    /**
+     * Remove only local authentication state.
+     */
+    clearLocalSession(): void;
+    /**
+     * Remove the current SDK error without changing the session.
+     */
+    clearError(): void;
+}
+export interface NexAuthCallbackProps {
+    readonly url?: string;
+    /**
+     * When true, returnTo is opened after callback completion.
+     *
+     * Defaults to true.
+     */
+    readonly redirect?: boolean;
+    readonly loadingFallback?: ReactNode;
+    readonly errorFallback?: ReactNode | ((error: NexAuthError) => ReactNode);
+    readonly onSuccess?: (result: AuthorizationCallbackResult) => void | Promise<void>;
+    readonly onError?: (error: NexAuthError) => void;
+}
+export interface AuthenticationBoundaryProps {
+    readonly children: ReactNode;
+    readonly fallback?: ReactNode;
+}
+export interface RequireAuthProps {
+    readonly children: ReactNode;
+    /**
+     * Content rendered while authentication state is loading.
+     */
+    readonly loadingFallback?: ReactNode;
+    /**
+     * Content rendered before the browser is redirected for sign-in.
+     */
+    readonly unauthenticatedFallback?: ReactNode;
+    /**
+     * Automatically begin login when no session exists.
+     *
+     * Defaults to true.
+     */
+    readonly autoLogin?: boolean;
+    readonly loginOptions?: LoginOptions;
+    readonly onUnauthenticated?: () => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@nexauthxyz/react",
+  "version": "0.1.2",
+  "description": "Official React SDK for NexAuth authentication using OpenID Connect and PKCE.",
+  "author": {
+    "name": "NexAuth",
+    "url": "https://nexauth.xyz"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run --config vitest.config.ts"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.2",
+    "@testing-library/jest-dom": "^7.0.1",
+    "@testing-library/react": "^16.3.3",
+    "@testing-library/user-event": "^14.6.7",
+    "@types/react": "^19.1.12",
+    "@types/react-dom": "^19.1.9",
+    "jsdom": "^29.1.1",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "nexauth",
+    "react",
+    "authentication",
+    "authorization",
+    "oauth2",
+    "oidc",
+    "openid-connect",
+    "pkce"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nexauthxyz/browser": "0.1.2"
+  }
+}

package/readme.md

@@ -0,0 +1,400 @@
+# `@nexauthxyz/react`
+
+Official React integration for NexAuth. It provides a context provider, hooks, callback handling, authentication boundaries, protected-content helpers, session-expiration handling, and cross-tab logout synchronization.
+
+This package is built on `@nexauthxyz/browser`; it does not replace the browser SDK or duplicate the OIDC protocol implementation.
+
+## Features
+
+- `NexAuthProvider` for application-wide authentication state.
+- `useNexAuth()` for session, user, token, login, callback, and logout access.
+- `NexAuthCallback` for authorization callback processing.
+- `Authenticated` and `Unauthenticated` rendering boundaries.
+- `RequireAuth` for protected content and optional automatic login.
+- Existing-session restoration during provider initialization.
+- Automatic local logout when the stored session expires.
+- Session revalidation when a tab becomes active again.
+- Cross-tab logout synchronization using `BroadcastChannel` with a storage-event fallback.
+- Structured NexAuth errors with support request IDs.
+
+## Requirements
+
+- React 18 or React 19.
+- React DOM 18 or React DOM 19 for browser applications.
+- A supported version of `@nexauthxyz/browser`.
+- A configured NexAuth application and exact registered redirect URI.
+- An active NexAuth organization subscription/entitlement.
+
+## Installation
+
+```bash
+npm install @nexauthxyz/react @nexauthxyz/browser
+```
+
+`@nexauthxyz/browser` may be installed automatically as a runtime dependency, but explicitly installing compatible versions makes the dependency relationship visible in the application manifest.
+
+## Dependencies and peer dependencies
+
+| Package                | Relationship                | Purpose                                                                                              |
+| ---------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `@nexauthxyz/browser` | Runtime dependency          | OIDC discovery, PKCE, token exchange, ID-token validation, UserInfo, storage, and logout.            |
+| `react`                | Peer dependency             | Context, state, effects, callbacks, hooks, and rendering.                                            |
+| `react-dom`            | Peer dependency             | Browser React rendering in the consuming application.                                                |
+| NexAuth OIDC server    | External service dependency | Authorization, tokens, UserInfo, JWKS, logout, application validation, and subscription enforcement. |
+
+The React SDK should not bundle its own copy of React. Keeping React as a peer dependency prevents duplicate React runtimes and invalid-hook errors.
+
+## Provider setup
+
+Mount one provider near the root of the application:
+
+```tsx
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { BrowserRouter } from 'react-router-dom';
+import { NexAuthProvider } from '@nexauthxyz/react';
+
+import { App } from './App.js';
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <BrowserRouter>
+      <NexAuthProvider
+        options={{
+          issuer: import.meta.env.VITE_NEXAUTH_ISSUER,
+          clientId: import.meta.env.VITE_NEXAUTH_CLIENT_ID,
+          redirectUri: `${window.location.origin}/auth/callback`,
+          scope: 'openid profile email',
+        }}
+        onError={(error) => {
+          console.error(error.code, error.requestId);
+        }}
+      >
+        <App />
+      </NexAuthProvider>
+    </BrowserRouter>
+  </StrictMode>,
+);
+```
+
+Example Vite environment configuration:
+
+```dotenv
+VITE_NEXAUTH_ISSUER=https://api.nexauth.xyz
+VITE_NEXAUTH_CLIENT_ID=nxa_your_public_client_id
+```
+
+These values are public identifiers, not secrets.
+
+## Provider properties
+
+| Property         | Required | Default              | Description                                           |
+| ---------------- | -------- | -------------------- | ----------------------------------------------------- |
+| `children`       | Yes      | —                    | React application subtree.                            |
+| `options`        | Yes      | —                    | Options accepted by `NexAuthBrowserClient`.           |
+| `onError`        | No       | —                    | Receives normalized SDK errors.                       |
+| `syncTabs`       | No       | `true`               | Synchronizes logout across tabs.                      |
+| `tabSyncChannel` | No       | Client-specific name | Overrides the authentication synchronization channel. |
+
+Treat provider options as immutable. If issuer or client ID must change, remount the provider with a new React key.
+
+## Using the hook
+
+```tsx
+import { useNexAuth } from '@nexauthxyz/react';
+
+export function AccountMenu() {
+  const {
+    status,
+    user,
+    session,
+    accessToken,
+    error,
+    isLoading,
+    isAuthenticated,
+    login,
+    logout,
+  } = useNexAuth();
+
+  if (isLoading) {
+    return <p>Loading authentication…</p>;
+  }
+
+  if (!isAuthenticated) {
+    return (
+      <button onClick={() => void login({ returnTo: '/dashboard' })}>
+        Sign in
+      </button>
+    );
+  }
+
+  return (
+    <section>
+      <p>Signed in as {user?.email ?? user?.name ?? user?.sub}</p>
+      <p>Status: {status}</p>
+      <button onClick={() => void logout()}>Sign out</button>
+      {error?.requestId ? <small>Reference: {error.requestId}</small> : null}
+    </section>
+  );
+}
+```
+
+## Callback route
+
+With React Router:
+
+```tsx
+import { Route, Routes, useNavigate } from 'react-router-dom';
+import { NexAuthCallback } from '@nexauthxyz/react';
+
+function AuthCallbackPage() {
+  const navigate = useNavigate();
+
+  return (
+    <NexAuthCallback
+      loading={<p>Completing secure sign-in…</p>}
+      onSuccess={(result) => {
+        navigate(result.returnTo ?? '/dashboard', {
+          replace: true,
+        });
+      }}
+      onError={(error) => {
+        console.error(error.code, error.requestId);
+      }}
+    />
+  );
+}
+
+export function AppRoutes() {
+  return (
+    <Routes>
+      <Route path="/auth/callback" element={<AuthCallbackPage />} />
+    </Routes>
+  );
+}
+```
+
+Register the resulting full callback URI in NexAuth. For local development:
+
+```text
+http://localhost:5173/auth/callback
+```
+
+For production:
+
+```text
+https://shop.example.com/auth/callback
+```
+
+## Authentication boundaries
+
+```tsx
+import { Authenticated, Unauthenticated } from '@nexauthxyz/react';
+
+export function HomePage() {
+  return (
+    <>
+      <Authenticated>
+        <p>Private account content</p>
+      </Authenticated>
+
+      <Unauthenticated>
+        <p>Sign in to continue.</p>
+      </Unauthenticated>
+    </>
+  );
+}
+```
+
+## Protected content
+
+```tsx
+import { RequireAuth } from '@nexauthxyz/react';
+
+export function DashboardPage() {
+  return (
+    <RequireAuth
+      loading={<p>Checking session…</p>}
+      fallback={<p>Authentication is required.</p>}
+      loginOptions={{ returnTo: '/dashboard' }}
+    >
+      <Dashboard />
+    </RequireAuth>
+  );
+}
+```
+
+Depending on your `RequireAuth` implementation, automatic login can be enabled for unauthenticated users. Avoid repeatedly starting login during an error state; show a retry action instead.
+
+## Calling protected APIs
+
+```tsx
+import { useNexAuth } from '@nexauthxyz/react';
+
+export function OrdersButton() {
+  const { accessToken } = useNexAuth();
+
+  const loadOrders = async () => {
+    if (!accessToken) {
+      return;
+    }
+
+    const response = await fetch('https://api.example.com/orders', {
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+      },
+    });
+
+    if (!response.ok) {
+      throw new Error(`Unable to load orders (${response.status}).`);
+    }
+  };
+
+  return <button onClick={() => void loadOrders()}>Load orders</button>;
+}
+```
+
+The protected API must independently validate access tokens. UI boundaries improve user experience but are not a backend authorization control.
+
+## Context API
+
+The `useNexAuth()` value includes:
+
+| Member                   | Description                                                               |
+| ------------------------ | ------------------------------------------------------------------------- |
+| `status`                 | `loading`, `authenticated`, `unauthenticated`, or `error`.                |
+| `session`                | Current validated local session or `null`.                                |
+| `user`                   | Current user profile or `null`.                                           |
+| `accessToken`            | Current bearer token or `null`.                                           |
+| `error`                  | Latest normalized `NexAuthError` or `null`.                               |
+| `isLoading`              | Convenience loading flag.                                                 |
+| `isAuthenticated`        | True only with authenticated status and a current session.                |
+| `login(options?)`        | Starts Authorization Code + PKCE login.                                   |
+| `handleCallback(input?)` | Completes callback processing.                                            |
+| `logout(options?)`       | Clears local state and optionally invokes provider logout.                |
+| `refreshSession()`       | Reloads the current session from SDK storage. This does not renew tokens. |
+| `clearLocalSession()`    | Removes only local authentication state.                                  |
+| `clearError()`           | Clears the current React error state.                                     |
+
+## Session lifecycle
+
+The provider restores a valid stored session on initialization. It also:
+
+- clears expired local sessions;
+- schedules logout for the session expiry time;
+- rechecks the session when the page regains focus or visibility;
+- optionally propagates logout to other tabs.
+
+`refreshSession()` means “reload local session state”; it does not call an OAuth refresh-token endpoint.
+
+## Cross-tab synchronization
+
+Cross-tab synchronization is enabled by default:
+
+```tsx
+<NexAuthProvider options={options} syncTabs>
+  <App />
+</NexAuthProvider>
+```
+
+Disable it when required:
+
+```tsx
+<NexAuthProvider options={options} syncTabs={false}>
+  <App />
+</NexAuthProvider>
+```
+
+Only a small logout event is transmitted. Tokens, user profiles, and complete sessions must never be broadcast between tabs.
+
+## Error handling
+
+```tsx
+<NexAuthProvider
+  options={options}
+  onError={(error) => {
+    reportAuthenticationFailure({
+      code: error.code,
+      requestId: error.requestId,
+    });
+  }}
+>
+  <App />
+</NexAuthProvider>
+```
+
+Avoid sending access tokens, ID tokens, authorization codes, PKCE verifiers, or raw error causes to analytics services. The request ID is designed to correlate a safe user-facing support reference with server audit logs.
+
+## Security and commercial access
+
+The npm package can be public. Downloading it does not provide access to paid NexAuth services. The backend must validate:
+
+- Client ID and active application status
+- Active organization subscription/entitlement
+- Exact registered redirect URI
+- Allowed browser origin
+- PKCE S256
+- Authorization-code ownership, expiry, and single use
+- User organization/application membership
+- Token audience and requested permissions
+
+Never embed client secrets, JWT signing keys, database credentials, or administrative keys in a React application. Browser-delivered values can always be inspected.
+
+## Package relationship
+
+```text
+React application
+  └─ @nexauthxyz/react
+       ├─ peer: react
+       ├─ peer: react-dom
+       └─ dependency: @nexauthxyz/browser
+            └─ dependency: jose
+```
+
+Publish packages in this order:
+
+1. `@nexauthxyz/browser`
+2. `@nexauthxyz/react`
+
+The browser version referenced by the React package must already exist in the npm registry before publishing React.
+
+## Package validation
+
+```bash
+npm run test --workspace @nexauthxyz/react
+npm run typecheck --workspace @nexauthxyz/react
+npm run build --workspace @nexauthxyz/react
+npm pack --workspace @nexauthxyz/react --dry-run
+```
+
+Verify that the tarball contains only intended public files such as `dist`, `README.md`, and `LICENSE`.
+
+## Troubleshooting
+
+### `useNexAuth` used outside the provider
+
+Ensure the component is rendered below `NexAuthProvider`.
+
+### Callback works locally but fails in production
+
+Register the production callback separately and ensure it exactly matches `window.location.origin + '/auth/callback'`.
+
+### Vercel or Netlify returns 404 on callback
+
+Configure an SPA rewrite so `/auth/callback` serves `index.html` while preserving the query string.
+
+### Login works in one tab but another tab stays authenticated after logout
+
+Leave `syncTabs` enabled and verify the browser supports `BroadcastChannel` or storage events.
+
+### Application does not have an active plan
+
+This response comes from backend entitlement enforcement. The organization subscription must be active; no frontend SDK setting should bypass it.
+
+### Session expires without renewal
+
+This is expected until NexAuth supports a secure refresh-token grant with rotation and replay protection. The React SDK should not fabricate renewal locally.
+
+## License
+
+MIT