@ulexid/react 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,13 @@
-# Temporary Holding Version
+# @ulexid/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Version `0.1.1` — [Ulexid Documentation](https://docs.ulexid.com)
+
+React hooks and `<AuthProvider>` components for [Ulexid](https://www.ulexid.com).
+
+```bash
+npm install @ulexid/react
+```
+
+## License
+
+Proprietary (`UNLICENSED`). Copyright (c) Ulexid. All rights reserved.

package/dist/index.d.ts

@@ -0,0 +1,103 @@
+/**
+ * `@ulexid/react` — React 18/19 context, hooks, and components for ulex.
+ *
+ * Provides CIAM user sign-in, Workforce organization switching, and RFC 8693
+ * scoped agent token delegation on top of `@ulexid/js` PKCE `S256`.
+ */
+import { type ReactNode } from 'react';
+import { UlexClient, type FetchLike, type TokenSet, type UserInfo } from '@ulexid/js';
+export { UlexOAuthError, type TokenSet, type UserInfo } from '@ulexid/js';
+export interface AuthStateStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+export interface SignInOptions {
+    readonly organization?: string;
+    readonly connection?: string;
+    readonly loginHint?: string;
+    readonly scopes?: readonly string[];
+    readonly redirectUri?: string;
+}
+export interface UlexAuthContextValue {
+    readonly client: UlexClient;
+    readonly isLoaded: boolean;
+    readonly isSignedIn: boolean;
+    readonly user: UserInfo | null;
+    readonly organizationId: string | null;
+    readonly scopes: readonly string[];
+    readonly error: Error | null;
+    buildSignInUrl(options?: SignInOptions): Promise<string>;
+    signInWithRedirect(options?: SignInOptions): Promise<void>;
+    handleRedirectCallback(callbackUrl: string): Promise<UserInfo>;
+    getAccessToken(options?: {
+        forceRefresh?: boolean;
+    }): Promise<string | null>;
+    switchOrganization(organizationId: string): Promise<void>;
+    signOut(options?: {
+        postLogoutRedirectUri?: string;
+    }): string;
+}
+export interface UlexProviderProps {
+    readonly issuer: string;
+    readonly clientId: string;
+    readonly redirectUri: string;
+    readonly defaultScopes?: readonly string[];
+    readonly initialTokens?: TokenSet | null;
+    readonly initialUser?: UserInfo | null;
+    readonly storage?: AuthStateStorage;
+    readonly fetch?: FetchLike;
+    readonly onNavigate?: (url: string) => void;
+    readonly children: ReactNode;
+}
+export declare function createUlexAuthController(config: {
+    readonly issuer: string;
+    readonly clientId: string;
+    readonly redirectUri: string;
+    readonly defaultScopes?: readonly string[];
+    readonly storage?: AuthStateStorage;
+    readonly fetch?: FetchLike;
+}): {
+    client: UlexClient;
+    storage: AuthStateStorage;
+    prepareAuthorizeUrl: (options?: SignInOptions) => Promise<{
+        url: string;
+        state: string;
+    }>;
+    completeCallback: (callbackUrl: string) => Promise<{
+        tokens: TokenSet;
+        user: UserInfo;
+    }>;
+};
+export declare function UlexProvider(props: UlexProviderProps): import("react").JSX.Element;
+export declare function useUlex(): UlexAuthContextValue;
+export declare function useAuth(): {
+    isLoaded: boolean;
+    isSignedIn: boolean;
+    userId: string | null;
+    orgId: string | null;
+    scopes: readonly string[];
+    getAccessToken: (options?: {
+        forceRefresh?: boolean;
+    }) => Promise<string | null>;
+    signInWithRedirect: (options?: SignInOptions) => Promise<void>;
+    signOut: (options?: {
+        postLogoutRedirectUri?: string;
+    }) => string;
+};
+export declare function useUser(): {
+    isLoaded: boolean;
+    isSignedIn: boolean;
+    user: UserInfo | null;
+};
+export declare function useOrganization(): {
+    isLoaded: boolean;
+    organizationId: string | null;
+    switchOrganization: (organizationId: string) => Promise<void>;
+};
+export declare function SignedIn({ children }: {
+    readonly children: ReactNode;
+}): import("react").JSX.Element | null;
+export declare function SignedOut({ children }: {
+    readonly children: ReactNode;
+}): import("react").JSX.Element | null;

package/dist/index.js

@@ -0,0 +1,268 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * `@ulexid/react` — React 18/19 context, hooks, and components for ulex.
+ *
+ * Provides CIAM user sign-in, Workforce organization switching, and RFC 8693
+ * scoped agent token delegation on top of `@ulexid/js` PKCE `S256`.
+ */
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, } from 'react';
+import { generatePkcePair, generateState, UlexClient, UlexOAuthError, } from '@ulexid/js';
+export { UlexOAuthError } from '@ulexid/js';
+class MemoryStateStorage {
+    store = new Map();
+    getItem(key) {
+        return this.store.get(key) ?? null;
+    }
+    setItem(key, value) {
+        this.store.set(key, value);
+    }
+    removeItem(key) {
+        this.store.delete(key);
+    }
+}
+function defaultStorage() {
+    if (typeof window !== 'undefined' && window.sessionStorage) {
+        return window.sessionStorage;
+    }
+    return new MemoryStateStorage();
+}
+const UlexContext = createContext(null);
+const PKCE_STORAGE_PREFIX = 'ulex:pkce:';
+export function createUlexAuthController(config) {
+    const storage = config.storage ?? defaultStorage();
+    const client = new UlexClient({
+        issuer: config.issuer,
+        clientId: config.clientId,
+        redirectUri: config.redirectUri,
+        fetch: config.fetch,
+    });
+    async function prepareAuthorizeUrl(options = {}) {
+        const pkce = await generatePkcePair();
+        const state = generateState();
+        const redirectUri = options.redirectUri ?? config.redirectUri;
+        storage.setItem(`${PKCE_STORAGE_PREFIX}${state}`, JSON.stringify({
+            verifier: pkce.verifier,
+            redirectUri,
+            createdAt: Date.now(),
+        }));
+        const url = client.buildAuthorizeUrl({
+            codeChallenge: pkce.challenge,
+            state,
+            redirectUri,
+            scopes: options.scopes ?? config.defaultScopes ?? ['openid', 'profile', 'email'],
+            organization: options.organization,
+            connection: options.connection,
+            loginHint: options.loginHint,
+        });
+        return { url, state };
+    }
+    async function completeCallback(callbackUrl) {
+        const parsed = new URL(callbackUrl);
+        const oauthErr = parsed.searchParams.get('error');
+        if (oauthErr) {
+            throw new UlexOAuthError(oauthErr, 400, parsed.searchParams.get('error_description') ?? undefined);
+        }
+        const code = parsed.searchParams.get('code');
+        const state = parsed.searchParams.get('state');
+        if (!code || !state) {
+            throw new UlexOAuthError('invalid_callback', 400, 'Callback URL is missing `code` or `state`.');
+        }
+        const storedRaw = storage.getItem(`${PKCE_STORAGE_PREFIX}${state}`);
+        storage.removeItem(`${PKCE_STORAGE_PREFIX}${state}`);
+        if (!storedRaw) {
+            throw new UlexOAuthError('state_mismatch', 400, 'Unknown or replayed OAuth `state` parameter.');
+        }
+        const stored = JSON.parse(storedRaw);
+        const tokens = await client.exchangeAuthorizationCode({
+            code,
+            codeVerifier: stored.verifier,
+            redirectUri: stored.redirectUri,
+        });
+        const user = await client.getUserInfo(tokens.access_token);
+        return { tokens, user };
+    }
+    return { client, storage, prepareAuthorizeUrl, completeCallback };
+}
+export function UlexProvider(props) {
+    const storageRef = useRef(props.storage ?? defaultStorage());
+    const controller = useMemo(() => createUlexAuthController({
+        issuer: props.issuer,
+        clientId: props.clientId,
+        redirectUri: props.redirectUri,
+        defaultScopes: props.defaultScopes,
+        storage: storageRef.current,
+        fetch: props.fetch,
+    }), [props.issuer, props.clientId, props.redirectUri, props.defaultScopes, props.fetch]);
+    const [tokens, setTokens] = useState(props.initialTokens ?? null);
+    const [tokenExpiresAt, setTokenExpiresAt] = useState(props.initialTokens ? Date.now() + props.initialTokens.expires_in * 1000 : 0);
+    const [user, setUser] = useState(props.initialUser ?? null);
+    const [isLoaded, setIsLoaded] = useState(Boolean(props.initialUser || !props.initialTokens));
+    const [error, setError] = useState(null);
+    useEffect(() => {
+        let cancelled = false;
+        if (props.initialTokens && !props.initialUser) {
+            controller.client
+                .getUserInfo(props.initialTokens.access_token)
+                .then((u) => {
+                if (!cancelled) {
+                    setUser(u);
+                    setIsLoaded(true);
+                }
+            })
+                .catch((err) => {
+                if (!cancelled) {
+                    setError(err instanceof Error ? err : new Error(String(err)));
+                    setIsLoaded(true);
+                }
+            });
+        }
+        return () => {
+            cancelled = true;
+        };
+    }, [controller.client, props.initialTokens, props.initialUser]);
+    const navigate = useCallback((url) => {
+        if (props.onNavigate) {
+            props.onNavigate(url);
+        }
+        else if (typeof window !== 'undefined') {
+            window.location.assign(url);
+        }
+    }, [props]);
+    const buildSignInUrl = useCallback(async (options = {}) => {
+        const { url } = await controller.prepareAuthorizeUrl(options);
+        return url;
+    }, [controller]);
+    const signInWithRedirect = useCallback(async (options = {}) => {
+        const url = await buildSignInUrl(options);
+        navigate(url);
+    }, [buildSignInUrl, navigate]);
+    const handleRedirectCallback = useCallback(async (callbackUrl) => {
+        try {
+            const result = await controller.completeCallback(callbackUrl);
+            setTokens(result.tokens);
+            setTokenExpiresAt(Date.now() + result.tokens.expires_in * 1000);
+            setUser(result.user);
+            setError(null);
+            setIsLoaded(true);
+            return result.user;
+        }
+        catch (err) {
+            const wrapped = err instanceof Error ? err : new Error(String(err));
+            setError(wrapped);
+            setIsLoaded(true);
+            throw wrapped;
+        }
+    }, [controller]);
+    const getAccessToken = useCallback(async (options = {}) => {
+        if (!tokens)
+            return null;
+        const needsRefresh = options.forceRefresh || tokenExpiresAt - Date.now() < 30_000;
+        if (!needsRefresh) {
+            return tokens.access_token;
+        }
+        if (!tokens.refresh_token) {
+            return tokens.access_token;
+        }
+        const rotated = await controller.client.refreshTokens({
+            refreshToken: tokens.refresh_token,
+        });
+        setTokens(rotated);
+        setTokenExpiresAt(Date.now() + rotated.expires_in * 1000);
+        return rotated.access_token;
+    }, [controller.client, tokenExpiresAt, tokens]);
+    const switchOrganization = useCallback(async (organizationId) => {
+        await signInWithRedirect({ organization: organizationId });
+    }, [signInWithRedirect]);
+    const signOut = useCallback((options = {}) => {
+        const idTokenHint = tokens?.id_token;
+        setTokens(null);
+        setUser(null);
+        setTokenExpiresAt(0);
+        const logoutUrl = controller.client.buildLogoutUrl({
+            idTokenHint,
+            postLogoutRedirectUri: options.postLogoutRedirectUri,
+        });
+        if (props.onNavigate) {
+            props.onNavigate(logoutUrl);
+        }
+        return logoutUrl;
+    }, [controller.client, props, tokens?.id_token]);
+    const scopes = useMemo(() => (tokens?.scope ? tokens.scope.split(/\s+/).filter(Boolean) : []), [tokens?.scope]);
+    const value = useMemo(() => ({
+        client: controller.client,
+        isLoaded,
+        isSignedIn: Boolean(tokens && user),
+        user,
+        organizationId: typeof user?.org_id === 'string' ? user.org_id : null,
+        scopes,
+        error,
+        buildSignInUrl,
+        signInWithRedirect,
+        handleRedirectCallback,
+        getAccessToken,
+        switchOrganization,
+        signOut,
+    }), [
+        buildSignInUrl,
+        controller.client,
+        error,
+        getAccessToken,
+        handleRedirectCallback,
+        isLoaded,
+        scopes,
+        signInWithRedirect,
+        signOut,
+        switchOrganization,
+        tokens,
+        user,
+    ]);
+    return _jsx(UlexContext.Provider, { value: value, children: props.children });
+}
+export function useUlex() {
+    const ctx = useContext(UlexContext);
+    if (!ctx) {
+        throw new Error('`useUlex` must be called inside a `<UlexProvider>`.');
+    }
+    return ctx;
+}
+export function useAuth() {
+    const ctx = useUlex();
+    return {
+        isLoaded: ctx.isLoaded,
+        isSignedIn: ctx.isSignedIn,
+        userId: ctx.user?.sub ?? null,
+        orgId: ctx.organizationId,
+        scopes: ctx.scopes,
+        getAccessToken: ctx.getAccessToken,
+        signInWithRedirect: ctx.signInWithRedirect,
+        signOut: ctx.signOut,
+    };
+}
+export function useUser() {
+    const ctx = useUlex();
+    return {
+        isLoaded: ctx.isLoaded,
+        isSignedIn: ctx.isSignedIn,
+        user: ctx.user,
+    };
+}
+export function useOrganization() {
+    const ctx = useUlex();
+    return {
+        isLoaded: ctx.isLoaded,
+        organizationId: ctx.organizationId,
+        switchOrganization: ctx.switchOrganization,
+    };
+}
+export function SignedIn({ children }) {
+    const { isLoaded, isSignedIn } = useAuth();
+    if (!isLoaded || !isSignedIn)
+        return null;
+    return _jsx(_Fragment, { children: children });
+}
+export function SignedOut({ children }) {
+    const { isLoaded, isSignedIn } = useAuth();
+    if (!isLoaded || isSignedIn)
+        return null;
+    return _jsx(_Fragment, { children: children });
+}

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@ulexid/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "license": "UNLICENSED",
+  "type": "module",
+  "description": "Official React 18/19 hooks, provider, and organization-aware auth components for Ulexid.",
+  "homepage": "https://www.ulexid.com",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@ulexid/js": "0.1.1"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0 || >=19.0.0"
+  }
+}