@avantmedia/id-react 0.0.1

package/package.json

@@ -0,0 +1,29 @@
+{
+    "name": "@avantmedia/id-react",
+    "version": "0.0.1",
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "private": false,
+    "publishConfig": {
+        "access": "public"
+    },
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        }
+    },
+    "scripts": {
+        "build": "tsc",
+        "dev": "tsc --watch"
+    },
+    "peerDependencies": {
+        "react": "^18.0.0 || ^19.0.0"
+    },
+    "devDependencies": {
+        "@types/react": "^18.3.0",
+        "react": "^18.3.0",
+        "typescript": "^5.7.3"
+    }
+}

package/src/hooks.ts

@@ -0,0 +1,27 @@
+import { useAuthContext } from "./provider";
+import type { AuthState } from "./types";
+
+/**
+ * Hook to access auth state and actions
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const { user, isLoading, login, logout } = useAuth();
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *   if (!user) return <button onClick={login}>Login</button>;
+ *
+ *   return (
+ *     <div>
+ *       Hello {user.email}!
+ *       <button onClick={logout}>Logout</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useAuth(): AuthState {
+  const { config, ...authState } = useAuthContext();
+  return authState;
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+// Components
+export { AvantIdProvider } from "./provider";
+
+// Hooks
+export { useAuth } from "./hooks";
+
+// Types
+export type {
+  AvantIdConfig,
+  User,
+  TokenResponse,
+  AuthState,
+} from "./types";
+
+// PKCE utilities (for advanced use cases)
+export {
+  generateCodeVerifier,
+  generateCodeChallenge,
+} from "./pkce";

package/src/pkce.ts

@@ -0,0 +1,78 @@
+/**
+ * PKCE (Proof Key for Code Exchange) utilities
+ * Used to secure the OAuth2 authorization code flow for SPAs
+ */
+
+/**
+ * Generate a cryptographically random code verifier
+ * Must be between 43 and 128 characters
+ */
+export function generateCodeVerifier(): string {
+  const array = new Uint8Array(32);
+  crypto.getRandomValues(array);
+  return base64UrlEncode(array);
+}
+
+/**
+ * Generate code challenge from verifier using S256 method
+ * SHA256 hash of verifier, base64url encoded
+ */
+export async function generateCodeChallenge(verifier: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(verifier);
+  const hash = await crypto.subtle.digest("SHA-256", data);
+  return base64UrlEncode(new Uint8Array(hash));
+}
+
+/**
+ * Base64url encode (URL-safe base64 without padding)
+ */
+function base64UrlEncode(buffer: Uint8Array): string {
+  const base64 = btoa(String.fromCharCode(...buffer));
+  return base64
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+/**
+ * Storage keys for PKCE state
+ */
+const VERIFIER_KEY = "avant_id_pkce_verifier";
+const STATE_KEY = "avant_id_oauth_state";
+
+/**
+ * Store code verifier in sessionStorage for later retrieval
+ */
+export function storeCodeVerifier(verifier: string): void {
+  sessionStorage.setItem(VERIFIER_KEY, verifier);
+}
+
+/**
+ * Retrieve and clear stored code verifier
+ */
+export function retrieveCodeVerifier(): string | null {
+  const verifier = sessionStorage.getItem(VERIFIER_KEY);
+  sessionStorage.removeItem(VERIFIER_KEY);
+  return verifier;
+}
+
+/**
+ * Generate and store OAuth state parameter for CSRF protection
+ */
+export function generateState(): string {
+  const array = new Uint8Array(16);
+  crypto.getRandomValues(array);
+  const state = base64UrlEncode(array);
+  sessionStorage.setItem(STATE_KEY, state);
+  return state;
+}
+
+/**
+ * Verify state parameter matches stored value
+ */
+export function verifyState(state: string): boolean {
+  const storedState = sessionStorage.getItem(STATE_KEY);
+  sessionStorage.removeItem(STATE_KEY);
+  return storedState === state;
+}

package/src/provider.tsx

@@ -0,0 +1,282 @@
+import { createContext, useContext, useState, useEffect, useCallback, type ReactNode } from "react";
+import type { AvantIdConfig, User, TokenResponse, AuthContextState } from "./types";
+import {
+  generateCodeVerifier,
+  generateCodeChallenge,
+  storeCodeVerifier,
+  retrieveCodeVerifier,
+  generateState,
+  verifyState,
+} from "./pkce";
+
+const AuthContext = createContext<AuthContextState | null>(null);
+
+// Token storage keys
+const ACCESS_TOKEN_KEY = "avant_id_access_token";
+const REFRESH_TOKEN_KEY = "avant_id_refresh_token";
+const TOKEN_EXPIRY_KEY = "avant_id_token_expiry";
+
+interface AvantIdProviderProps {
+  children: ReactNode;
+  config: AvantIdConfig;
+}
+
+export function AvantIdProvider({ children, config }: AvantIdProviderProps) {
+  const [user, setUser] = useState<User | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [accessToken, setAccessToken] = useState<string | null>(null);
+  const [refreshToken, setRefreshToken] = useState<string | null>(null);
+  const [tokenExpiry, setTokenExpiry] = useState<number | null>(null);
+
+  // Normalize domain to ensure it has protocol
+  const baseUrl = config.domain.startsWith("http")
+    ? config.domain
+    : `https://${config.domain}`;
+
+  // Default redirect URI
+  const redirectUri = config.redirectUri || `${window.location.origin}/callback`;
+
+  // Store tokens
+  const storeTokens = useCallback((tokens: TokenResponse) => {
+    const expiry = Date.now() + tokens.expires_in * 1000;
+
+    setAccessToken(tokens.access_token);
+    setRefreshToken(tokens.refresh_token);
+    setTokenExpiry(expiry);
+
+    // Always store access token in memory, optionally persist refresh token
+    if (config.persistSession) {
+      localStorage.setItem(REFRESH_TOKEN_KEY, tokens.refresh_token);
+      localStorage.setItem(TOKEN_EXPIRY_KEY, expiry.toString());
+    }
+  }, [config.persistSession]);
+
+  // Clear tokens
+  const clearTokens = useCallback(() => {
+    setAccessToken(null);
+    setRefreshToken(null);
+    setTokenExpiry(null);
+    setUser(null);
+
+    localStorage.removeItem(ACCESS_TOKEN_KEY);
+    localStorage.removeItem(REFRESH_TOKEN_KEY);
+    localStorage.removeItem(TOKEN_EXPIRY_KEY);
+  }, []);
+
+  // Fetch user profile with access token
+  const fetchUser = useCallback(async (token: string): Promise<User | null> => {
+    try {
+      const response = await fetch(`${baseUrl}/auth/me`, {
+        headers: { Authorization: `Bearer ${token}` },
+      });
+
+      if (!response.ok) {
+        return null;
+      }
+
+      return await response.json();
+    } catch {
+      return null;
+    }
+  }, [baseUrl]);
+
+  // Refresh access token using refresh token
+  const refreshAccessToken = useCallback(async (token: string): Promise<TokenResponse | null> => {
+    try {
+      const response = await fetch(`${baseUrl}/auth/refresh`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ refreshToken: token }),
+      });
+
+      if (!response.ok) {
+        return null;
+      }
+
+      return await response.json();
+    } catch {
+      return null;
+    }
+  }, [baseUrl]);
+
+  // Get access token, refreshing if needed
+  const getAccessToken = useCallback(async (): Promise<string | null> => {
+    // Check if current token is still valid (with 30s buffer)
+    if (accessToken && tokenExpiry && Date.now() < tokenExpiry - 30000) {
+      return accessToken;
+    }
+
+    // Try to refresh
+    if (refreshToken) {
+      const tokens = await refreshAccessToken(refreshToken);
+      if (tokens) {
+        storeTokens(tokens);
+        return tokens.access_token;
+      }
+    }
+
+    // No valid token
+    clearTokens();
+    return null;
+  }, [accessToken, tokenExpiry, refreshToken, refreshAccessToken, storeTokens, clearTokens]);
+
+  // Exchange authorization code for tokens
+  const exchangeCode = useCallback(async (code: string, codeVerifier: string): Promise<boolean> => {
+    try {
+      const response = await fetch(`${baseUrl}/oauth/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          grant_type: "authorization_code",
+          code,
+          code_verifier: codeVerifier,
+          client_id: config.clientId,
+          redirect_uri: redirectUri,
+        }),
+      });
+
+      if (!response.ok) {
+        console.error("Token exchange failed:", await response.text());
+        return false;
+      }
+
+      const tokens: TokenResponse = await response.json();
+      storeTokens(tokens);
+
+      // Fetch user profile
+      const userProfile = await fetchUser(tokens.access_token);
+      if (userProfile) {
+        setUser(userProfile);
+      }
+
+      return true;
+    } catch (err) {
+      console.error("Token exchange error:", err);
+      return false;
+    }
+  }, [baseUrl, config.clientId, redirectUri, storeTokens, fetchUser]);
+
+  // Login - redirect to Avant ID
+  const login = useCallback(async () => {
+    const verifier = generateCodeVerifier();
+    const challenge = await generateCodeChallenge(verifier);
+    const state = generateState();
+
+    // Store verifier for later
+    storeCodeVerifier(verifier);
+
+    // Build authorization URL
+    const params = new URLSearchParams({
+      client_id: config.clientId,
+      redirect_uri: redirectUri,
+      response_type: "code",
+      code_challenge: challenge,
+      code_challenge_method: "S256",
+      state,
+    });
+
+    window.location.href = `${baseUrl}/oauth/authorize?${params.toString()}`;
+  }, [config.clientId, redirectUri, baseUrl]);
+
+  // Logout
+  const logout = useCallback(async () => {
+    // Optionally call logout endpoint to revoke refresh token
+    if (refreshToken) {
+      try {
+        await fetch(`${baseUrl}/auth/logout`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ refreshToken }),
+        });
+      } catch {
+        // Ignore errors, still clear local state
+      }
+    }
+
+    clearTokens();
+  }, [refreshToken, baseUrl, clearTokens]);
+
+  // Handle OAuth callback on mount
+  useEffect(() => {
+    const handleCallback = async () => {
+      const params = new URLSearchParams(window.location.search);
+      const code = params.get("code");
+      const state = params.get("state");
+      const error = params.get("error");
+
+      if (error) {
+        console.error("OAuth error:", error, params.get("error_description"));
+        setIsLoading(false);
+        return;
+      }
+
+      if (code && state) {
+        // Verify state
+        if (!verifyState(state)) {
+          console.error("State mismatch - possible CSRF attack");
+          setIsLoading(false);
+          return;
+        }
+
+        // Get stored code verifier
+        const codeVerifier = retrieveCodeVerifier();
+        if (!codeVerifier) {
+          console.error("No code verifier found");
+          setIsLoading(false);
+          return;
+        }
+
+        // Exchange code for tokens
+        const success = await exchangeCode(code, codeVerifier);
+
+        // Clean up URL
+        window.history.replaceState({}, "", window.location.pathname);
+
+        setIsLoading(false);
+        return;
+      }
+
+      // No callback params - check for existing session
+      if (config.persistSession) {
+        const storedRefresh = localStorage.getItem(REFRESH_TOKEN_KEY);
+        if (storedRefresh) {
+          setRefreshToken(storedRefresh);
+          const tokens = await refreshAccessToken(storedRefresh);
+          if (tokens) {
+            storeTokens(tokens);
+            const userProfile = await fetchUser(tokens.access_token);
+            if (userProfile) {
+              setUser(userProfile);
+            }
+          } else {
+            clearTokens();
+          }
+        }
+      }
+
+      setIsLoading(false);
+    };
+
+    handleCallback();
+  }, [config.persistSession, exchangeCode, refreshAccessToken, storeTokens, fetchUser, clearTokens]);
+
+  const value: AuthContextState = {
+    user,
+    isLoading,
+    isAuthenticated: !!user,
+    login,
+    logout,
+    getAccessToken,
+    config,
+  };
+
+  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
+}
+
+export function useAuthContext(): AuthContextState {
+  const context = useContext(AuthContext);
+  if (!context) {
+    throw new Error("useAuth must be used within an AvantIdProvider");
+  }
+  return context;
+}

package/src/types.ts

@@ -0,0 +1,59 @@
+/**
+ * Configuration for the AvantIdProvider
+ */
+export interface AvantIdConfig {
+  /** The domain of the Avant ID server (e.g., "auth.example.com" or "http://localhost:16000") */
+  domain: string;
+  /** The client ID of your application */
+  clientId: string;
+  /** The redirect URI for OAuth callbacks (defaults to current origin + /callback) */
+  redirectUri?: string;
+  /** Whether to persist refresh token in localStorage (default: false) */
+  persistSession?: boolean;
+}
+
+/**
+ * User object returned by the auth context
+ */
+export interface User {
+  id: string;
+  email: string;
+  name?: string;
+  emailVerified?: boolean;
+  permissions?: Record<string, string>;
+}
+
+/**
+ * Token response from the OAuth token endpoint
+ */
+export interface TokenResponse {
+  access_token: string;
+  refresh_token: string;
+  token_type: string;
+  expires_in: number;
+}
+
+/**
+ * Auth state exposed by useAuth hook
+ */
+export interface AuthState {
+  /** Current user or null if not authenticated */
+  user: User | null;
+  /** Whether the SDK is initializing/checking auth state */
+  isLoading: boolean;
+  /** Whether the user is authenticated */
+  isAuthenticated: boolean;
+  /** Redirect to Avant ID login page */
+  login: () => Promise<void>;
+  /** Clear local auth state and optionally revoke tokens */
+  logout: () => Promise<void>;
+  /** Get the current access token (refreshes if expired) */
+  getAccessToken: () => Promise<string | null>;
+}
+
+/**
+ * Internal auth context state
+ */
+export interface AuthContextState extends AuthState {
+  config: AvantIdConfig;
+}

package/tsconfig.json

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