@acl-identity/react 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,126 @@
+# @acl-identity/react
+
+React integration for the ACL Identity SDK. Provides `AuthProvider`, the `useAuth` hook, and ready-made components for sign-in, sign-out, and OAuth2 callback handling.
+
+## Installation
+
+```bash
+npm install @acl-identity/react
+# or
+pnpm add @acl-identity/react
+```
+
+Requires React 18 or later as a peer dependency.
+
+## Quick start
+
+### 1. Create the client and wrap your app
+
+```tsx
+import { ACLBrowserClient, AuthProvider } from '@acl-identity/react';
+
+const client = new ACLBrowserClient({
+  baseUrl: 'https://auth.example.com',
+  clientId: 'my-client-id',
+  redirectUri: 'https://app.example.com/callback',
+  orgSlug: 'my-org',
+});
+
+function App() {
+  return (
+    <AuthProvider
+      client={client}
+      clientId="my-client-id"
+      redirectUri="https://app.example.com/callback"
+      orgSlug="my-org"
+      onRedirectCallback={(appState) => {
+        // navigate to appState?.returnTo after login
+      }}
+    >
+      <YourApp />
+    </AuthProvider>
+  );
+}
+```
+
+### 2. Use the `useAuth` hook
+
+```tsx
+import { useAuth } from '@acl-identity/react';
+
+function Header() {
+  const { user, isAuthenticated, isLoading, signIn, signOut } = useAuth();
+
+  if (isLoading) return <Spinner />;
+
+  if (!isAuthenticated) {
+    return <button onClick={() => signIn()}>Sign in</button>;
+  }
+
+  return (
+    <div>
+      <span>Welcome, {user?.name}</span>
+      <button onClick={() => signOut()}>Sign out</button>
+    </div>
+  );
+}
+```
+
+### 3. Handle the OAuth2 callback
+
+Add a callback page that renders `<CallbackHandler />`:
+
+```tsx
+import { CallbackHandler } from '@acl-identity/react';
+import { useNavigate } from 'react-router-dom';
+
+export function CallbackPage() {
+  const navigate = useNavigate();
+  return (
+    <CallbackHandler
+      onSuccess={() => navigate('/')}
+      onError={(err) => console.error(err)}
+    />
+  );
+}
+```
+
+## Components
+
+| Component | Description |
+|---|---|
+| `AuthProvider` | Context provider — wraps your app |
+| `CallbackHandler` | Processes the OAuth2 redirect callback |
+| `SignInButton` | Pre-wired sign-in button |
+| `SignOutButton` | Pre-wired sign-out button |
+| `SilentCallbackPage` | Placed at `silentRedirectUri` for iframe-based silent renewal |
+
+## Silent token renewal
+
+Mount `<SilentCallbackPage />` at a dedicated route (e.g. `/silent-callback`) and pass its URL to `AuthProvider`:
+
+```tsx
+<AuthProvider
+  ...
+  silentRedirectUri="https://app.example.com/silent-callback"
+>
+```
+
+Tokens are renewed automatically before they expire without a visible redirect.
+
+## `useAuth` return value
+
+| Field | Type | Description |
+|---|---|---|
+| `user` | `UserClaims \| null` | Decoded JWT claims of the current user |
+| `isAuthenticated` | `boolean` | Whether a valid token exists |
+| `isLoading` | `boolean` | True while the initial session check is in progress |
+| `error` | `Error \| null` | Last auth error |
+| `signIn(options?)` | `Promise<void>` | Redirects to the authorization server |
+| `signOut(options?)` | `Promise<void>` | Clears tokens and optionally revokes them |
+| `getAccessToken()` | `Promise<string \| null>` | Returns the current access token |
+| `handleCallback(url?)` | `Promise<{ appState? }>` | Manually processes a callback URL |
+
+## License
+
+MIT

package/package.json

@@ -1,37 +1,41 @@
 {
   "name": "@acl-identity/react",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "React hooks and provider for ACL Identity — Phase 2",
   "license": "MIT",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs",
       "types": "./dist/index.d.ts"
     }
   },
+  "files": ["dist"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
   "peerDependencies": {
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0"
   },
   "dependencies": {
-    "@acl-identity/types": "0.1.0",
-    "@acl-identity/core": "0.1.0",
-    "@acl-identity/browser": "0.1.0"
+    "@acl-identity/types": "workspace:*",
+    "@acl-identity/core": "workspace:*",
+    "@acl-identity/browser": "workspace:*"
   },
   "devDependencies": {
     "@types/react": "^18.3.3",
     "@types/react-dom": "^18.3.0",
     "tsup": "^8.2.4",
     "typescript": "^5.5.4"
-  },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist"
   }
-}
+}

package/.turbo/turbo-build.log

@@ -1,82 +0,0 @@
-
-> @acl-identity/react@0.1.0 build /Users/lanreyusuf/Developer/personal/acl-identity-sdk/packages/react
-> tsup
-
-▲ [WARNING] The condition "types" here will never be used as it comes after both "import" and "require" [package.json]
-
-    package.json:13:6:
-      13 │       "types": "./dist/index.d.ts"
-         ╵       ~~~~~~~
-
-  The "import" condition comes earlier and will be used for all "import" statements:
-
-    package.json:11:6:
-      11 │       "import": "./dist/index.js",
-         ╵       ~~~~~~~~
-
-  The "require" condition comes earlier and will be used for all "require" calls:
-
-    package.json:12:6:
-      12 │       "require": "./dist/index.cjs",
-         ╵       ~~~~~~~~~
-
-CLI Building entry: {"index":"src/index.ts"}
-CLI Using tsconfig: tsconfig.json
-CLI tsup v8.5.1
-CLI Using tsup config: /Users/lanreyusuf/Developer/personal/acl-identity-sdk/packages/react/tsup.config.ts
-CLI Target: es2020
-CLI Cleaning output folder
-ESM Build start
-CJS Build start
-
- WARN  ▲ [WARNING] The condition "types" here will never be used as it comes after both "import" and "require" [package.json] 7:52:29 PM
-
-    package.json:13:6:
-      13 │       "types": "./dist/index.d.ts"
-         ╵       ~~~~~~~
-
-  The "import" condition comes earlier and will be used for all "import" statements:
-
-    package.json:11:6:
-      11 │       "import": "./dist/index.js",
-         ╵       ~~~~~~~~
-
-  The "require" condition comes earlier and will be used for all "require" calls:
-
-    package.json:12:6:
-      12 │       "require": "./dist/index.cjs",
-         ╵       ~~~~~~~~~
-
-
-
-
- WARN  ▲ [WARNING] The condition "types" here will never be used as it comes after both "import" and "require" [package.json] 7:52:29 PM
-
-    package.json:13:6:
-      13 │       "types": "./dist/index.d.ts"
-         ╵       ~~~~~~~
-
-  The "import" condition comes earlier and will be used for all "import" statements:
-
-    package.json:11:6:
-      11 │       "import": "./dist/index.js",
-         ╵       ~~~~~~~~
-
-  The "require" condition comes earlier and will be used for all "require" calls:
-
-    package.json:12:6:
-      12 │       "require": "./dist/index.cjs",
-         ╵       ~~~~~~~~~
-
-
-
-ESM dist/index.mjs     7.33 KB
-ESM dist/index.mjs.map 18.09 KB
-ESM ⚡️ Build success in 78ms
-CJS dist/index.js     8.65 KB
-CJS dist/index.js.map 17.71 KB
-CJS ⚡️ Build success in 85ms
-DTS Build start
-DTS ⚡️ Build success in 440ms
-DTS dist/index.d.mts 4.58 KB
-DTS dist/index.d.ts  4.58 KB

package/src/components/callback-handler.tsx

@@ -1,53 +0,0 @@
-import { useEffect, useRef } from 'react';
-import { useAuth } from '../hooks/use-auth';
-
-export interface CallbackHandlerProps {
-  /** Called after tokens are stored and auth state is updated. Use this to navigate away. */
-  onSuccess?: (appState?: unknown) => void;
-  /** Called if the code exchange fails. */
-  onError?: (error: Error) => void;
-  /** Rendered while the code exchange is in progress. */
-  loading?: React.ReactNode;
-}
-
-/**
- * Place this component on the route that matches your `redirectUri`.
- * It reads the `?code=` and `?state=` from the URL, exchanges them for
- * tokens, then calls `onSuccess`. The URL is cleaned up automatically.
- *
- * @example
- * // app/callback/page.tsx
- * 'use client';
- * import { CallbackHandler } from '@acl-identity/react';
- * import { useRouter } from 'next/navigation';
- *
- * export default function CallbackPage() {
- *   const router = useRouter();
- *   return (
- *     <CallbackHandler
- *       onSuccess={(appState) => router.replace(appState?.returnTo ?? '/dashboard')}
- *       onError={() => router.replace('/login?error=callback_failed')}
- *     />
- *   );
- * }
- */
-export function CallbackHandler({ onSuccess, onError, loading = null }: CallbackHandlerProps) {
-  const { handleCallback } = useAuth();
-  const called = useRef(false);
-
-  useEffect(() => {
-    if (called.current) return;
-    called.current = true;
-
-    handleCallback()
-      .then(({ appState }) => {
-        window.history.replaceState({}, document.title, window.location.pathname);
-        onSuccess?.(appState);
-      })
-      .catch((err: Error) => {
-        onError?.(err);
-      });
-  }, []); // eslint-disable-line react-hooks/exhaustive-deps
-
-  return <>{loading}</>;
-}

package/src/components/sign-in-button.tsx

@@ -1,55 +0,0 @@
-import { type ButtonHTMLAttributes } from 'react';
-import { useAuth } from '../hooks/use-auth';
-import type { SignOutOptions } from '../context';
-
-export interface SignInButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
-  appState?: unknown;
-}
-
-export function SignInButton({ children = 'Sign in', appState, onClick, ...props }: SignInButtonProps) {
-  const { signIn } = useAuth();
-
-  const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {
-    onClick?.(e);
-    if (!e.defaultPrevented) {
-      signIn({ appState });
-    }
-  };
-
-  return (
-    <button type="button" onClick={handleClick} {...props}>
-      {children}
-    </button>
-  );
-}
-
-export interface SignOutButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
-  returnTo?: string;
-  revokeToken?: boolean;
-}
-
-export function SignOutButton({
-  children = 'Sign out',
-  returnTo,
-  revokeToken,
-  onClick,
-  ...props
-}: SignOutButtonProps) {
-  const { signOut } = useAuth();
-
-  const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {
-    onClick?.(e);
-    if (!e.defaultPrevented) {
-      const options: SignOutOptions = {};
-      if (returnTo) options.returnTo = returnTo;
-      if (revokeToken !== undefined) options.revokeToken = revokeToken;
-      signOut(options);
-    }
-  };
-
-  return (
-    <button type="button" onClick={handleClick} {...props}>
-      {children}
-    </button>
-  );
-}

package/src/components/silent-callback-page.tsx

@@ -1,32 +0,0 @@
-import { useEffect } from 'react';
-
-/**
- * Render this component (and nothing else) at the route matching your
- * `silentRedirectUri`. It posts the current URL back to the parent window
- * so the hidden iframe used by silent renew can complete the token exchange.
- *
- * The route must be registered as an allowed redirect URI on your OAuth client.
- *
- * @example
- * // app/silent-callback/page.tsx  (Next.js App Router)
- * 'use client';
- * import { SilentCallbackPage } from '@acl-identity/react';
- * export default SilentCallbackPage;
- *
- * @example
- * // pages/silent-callback.tsx  (Next.js Pages Router)
- * import { SilentCallbackPage } from '@acl-identity/react';
- * export default SilentCallbackPage;
- */
-export function SilentCallbackPage() {
-  useEffect(() => {
-    if (window.parent !== window) {
-      window.parent.postMessage(
-        { type: 'acl:silent_callback', url: window.location.href },
-        window.location.origin
-      );
-    }
-  }, []);
-
-  return null;
-}

package/src/context.ts

@@ -1,30 +0,0 @@
-import { createContext } from 'react';
-import type { ACLBrowserClient } from '@acl-identity/browser';
-import type { UserClaims } from '@acl-identity/types';
-
-export interface SignInOptions {
-  appState?: unknown;
-}
-
-export interface SignOutOptions {
-  returnTo?: string;
-  revokeToken?: boolean;
-}
-
-export interface AuthContextValue {
-  user: UserClaims | null;
-  isAuthenticated: boolean;
-  isLoading: boolean;
-  error: Error | null;
-  client: ACLBrowserClient;
-  clientId: string;
-  redirectUri: string;
-  orgSlug?: string;
-  scopes?: string;
-  signIn(options?: SignInOptions): Promise<void>;
-  signOut(options?: SignOutOptions): Promise<void>;
-  getAccessToken(): Promise<string | null>;
-  handleCallback(callbackUrl?: string): Promise<{ appState?: unknown }>;
-}
-
-export const AuthContext = createContext<AuthContextValue | null>(null);

package/src/hooks/use-auth.ts

@@ -1,13 +0,0 @@
-import { useContext } from 'react';
-import { AuthContext, type AuthContextValue } from '../context';
-
-export function useAuth(): AuthContextValue {
-  const ctx = useContext(AuthContext);
-  if (!ctx) {
-    throw new Error(
-      'useAuth must be used within an <AuthProvider>. ' +
-        'Wrap your app (or the relevant subtree) with <AuthProvider client={...} clientId={...} redirectUri={...} />.'
-    );
-  }
-  return ctx;
-}

package/src/index.ts

@@ -1,20 +0,0 @@
-export { AuthProvider } from './provider';
-export type { AuthProviderProps } from './provider';
-
-export { useAuth } from './hooks/use-auth';
-
-export { SignInButton, SignOutButton } from './components/sign-in-button';
-export type { SignInButtonProps, SignOutButtonProps } from './components/sign-in-button';
-
-export { CallbackHandler } from './components/callback-handler';
-export type { CallbackHandlerProps } from './components/callback-handler';
-
-export { SilentCallbackPage } from './components/silent-callback-page';
-
-export type { AuthContextValue, SignInOptions, SignOutOptions } from './context';
-
-// Re-export the browser client so consumers need only one install
-export { ACLBrowserClient } from '@acl-identity/browser';
-export type { ACLBrowserClientConfig } from '@acl-identity/browser';
-// Re-export useful types
-export type { UserClaims, OrgContext } from '@acl-identity/types';

package/src/provider.tsx

@@ -1,221 +0,0 @@
-import {
-  useCallback,
-  useEffect,
-  useRef,
-  useState,
-  type ReactNode,
-} from 'react';
-import type { ACLBrowserClient } from '@acl-identity/browser';
-import { tokenExpiresAt } from '@acl-identity/core';
-import type { UserClaims } from '@acl-identity/types';
-import { AuthContext, type SignInOptions, type SignOutOptions } from './context';
-
-export interface AuthProviderProps {
-  client: ACLBrowserClient;
-  /** OAuth2 client_id — passed to buildAuthorizationUrl and silentRenew */
-  clientId: string;
-  /** Redirect URI registered with the auth server for the main auth flow */
-  redirectUri: string;
-  /** Organization slug for multi-tenant routing */
-  orgSlug?: string;
-  /** Space-separated OAuth2 scopes. Defaults to 'openid profile email' */
-  scopes?: string;
-  /**
-   * Redirect URI for silent token renewal via hidden iframe.
-   * Must be registered with the auth server. The page at this URI
-   * must render <SilentCallbackPage />.
-   */
-  silentRedirectUri?: string;
-  /**
-   * Called after the OAuth2 redirect callback is processed.
-   * Use this to navigate the user to their intended destination.
-   */
-  onRedirectCallback?: (appState?: unknown) => void;
-  children: ReactNode;
-}
-
-interface AuthState {
-  user: UserClaims | null;
-  isAuthenticated: boolean;
-  isLoading: boolean;
-  error: Error | null;
-}
-
-const PKCE_KEY_PREFIX = 'acl:pkce:';
-
-export function AuthProvider({
-  client,
-  clientId,
-  redirectUri,
-  orgSlug,
-  scopes,
-  silentRedirectUri,
-  onRedirectCallback,
-  children,
-}: AuthProviderProps) {
-  const [state, setState] = useState<AuthState>({
-    user: null,
-    isAuthenticated: false,
-    isLoading: true,
-    error: null,
-  });
-
-  const initialized = useRef(false);
-
-  const syncAuthState = useCallback(async () => {
-    const [user, isAuthenticated] = await Promise.all([
-      client.auth.parseCurrentUser(),
-      client.auth.isAuthenticated(),
-    ]);
-    setState({ user, isAuthenticated, isLoading: false, error: null });
-  }, [client]);
-
-  const handleSilentRenew = useCallback(async () => {
-    if (!silentRedirectUri) {
-      setState((s) => ({ ...s, isLoading: false }));
-      return;
-    }
-    try {
-      await client.auth.silentRenew(silentRedirectUri, clientId, { orgSlug, scope: scopes });
-      await syncAuthState();
-    } catch {
-      setState({ user: null, isAuthenticated: false, isLoading: false, error: null });
-    }
-  }, [client, silentRedirectUri, clientId, orgSlug, scopes, syncAuthState]);
-
-  // Initial session check — runs once on mount
-  useEffect(() => {
-    if (initialized.current) return;
-    initialized.current = true;
-
-    const url = new URL(window.location.href);
-    const isCallbackUrl = url.searchParams.has('code') && url.searchParams.has('state');
-
-    if (isCallbackUrl) {
-      // Stay loading while CallbackHandler processes the code exchange
-      return;
-    }
-
-    client.auth.isAuthenticated().then((isAuth) => {
-      if (isAuth) {
-        syncAuthState();
-      } else {
-        handleSilentRenew();
-      }
-    });
-  }, []); // eslint-disable-line react-hooks/exhaustive-deps
-
-  // Schedule proactive silent renew before the current token expires
-  useEffect(() => {
-    if (!state.user || !silentRedirectUri) return;
-
-    let timer: ReturnType<typeof setTimeout>;
-
-    client.auth.getAccessToken().then((token) => {
-      if (!token) return;
-      const expiresAtMs = tokenExpiresAt(token);
-      if (!expiresAtMs) return;
-
-      const msUntilRenew = expiresAtMs - Date.now() - 30_000;
-      if (msUntilRenew <= 0) {
-        handleSilentRenew();
-        return;
-      }
-      timer = setTimeout(handleSilentRenew, msUntilRenew);
-    });
-
-    return () => clearTimeout(timer);
-  }, [state.user, silentRedirectUri, handleSilentRenew, client]);
-
-  const signIn = useCallback(
-    async (options?: SignInOptions) => {
-      const { url, state: authState, codeVerifier } = await client.auth.buildAuthorizationUrl({
-        clientId,
-        redirectUri,
-        orgSlug,
-        scope: scopes,
-      });
-      sessionStorage.setItem(
-        `${PKCE_KEY_PREFIX}${authState}`,
-        JSON.stringify({ codeVerifier, appState: options?.appState ?? null })
-      );
-      window.location.href = url;
-    },
-    [client, clientId, redirectUri, orgSlug, scopes]
-  );
-
-  const signOut = useCallback(
-    async (options?: SignOutOptions) => {
-      await client.auth.logout({ revokeToken: options?.revokeToken });
-      setState({ user: null, isAuthenticated: false, isLoading: false, error: null });
-      if (options?.returnTo) {
-        window.location.href = options.returnTo;
-      }
-    },
-    [client]
-  );
-
-  const getAccessToken = useCallback(() => client.auth.getAccessToken(), [client]);
-
-  const handleCallback = useCallback(
-    async (callbackUrl?: string): Promise<{ appState?: unknown }> => {
-      const url = new URL(callbackUrl ?? window.location.href);
-      const error = url.searchParams.get('error');
-
-      if (error) {
-        const desc = url.searchParams.get('error_description') ?? error;
-        const err = new Error(desc);
-        setState((s) => ({ ...s, error: err, isLoading: false }));
-        throw err;
-      }
-
-      const code = url.searchParams.get('code');
-      const authState = url.searchParams.get('state');
-
-      if (!code || !authState) {
-        const err = new Error('Missing code or state in callback URL');
-        setState((s) => ({ ...s, error: err, isLoading: false }));
-        throw err;
-      }
-
-      const stored = sessionStorage.getItem(`${PKCE_KEY_PREFIX}${authState}`);
-      if (!stored) {
-        const err = new Error('Auth session expired or state mismatch. Please sign in again.');
-        setState((s) => ({ ...s, error: err, isLoading: false }));
-        throw err;
-      }
-
-      const { codeVerifier, appState } = JSON.parse(stored) as {
-        codeVerifier: string;
-        appState?: unknown;
-      };
-      sessionStorage.removeItem(`${PKCE_KEY_PREFIX}${authState}`);
-
-      await client.auth.exchangeCode(code, codeVerifier, redirectUri);
-      await syncAuthState();
-
-      onRedirectCallback?.(appState);
-      return { appState };
-    },
-    [client, redirectUri, syncAuthState, onRedirectCallback]
-  );
-
-  return (
-    <AuthContext.Provider
-      value={{
-        ...state,
-        client,
-        clientId,
-        redirectUri,
-        orgSlug,
-        scopes,
-        signIn,
-        signOut,
-        getAccessToken,
-        handleCallback,
-      }}
-    >
-      {children}
-    </AuthContext.Provider>
-  );
-}

package/tsconfig.json

@@ -1,10 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "compilerOptions": {
-    "outDir": "dist",
-    "rootDir": "src",
-    "jsx": "react-jsx",
-    "lib": ["ES2020", "DOM", "DOM.Iterable"]
-  },
-  "include": ["src"]
-}

package/tsup.config.ts

@@ -1,11 +0,0 @@
-import { defineConfig } from 'tsup';
-
-export default defineConfig({
-  entry: { index: 'src/index.ts' },
-  format: ['esm', 'cjs'],
-  dts: true,
-  splitting: true,
-  sourcemap: true,
-  clean: true,
-  external: ['react', 'react-dom'],
-});