@civic/auth 0.0.1-beta.3 → 0.0.1-beta.30

package/src/shared/lib/util.ts

@@ -0,0 +1,217 @@
+// Utility functions shared by auth server and client integrations
+// Typically these functions should be used inside AuthenticationInitiator and AuthenticationResolver implementations
+import type {
+  AuthStorage,
+  Endpoints,
+  JWTPayload,
+  OIDCTokenResponseBody,
+  ParsedTokens,
+} from "@/types.js";
+import { CodeVerifier, OAuthTokens } from "./types.js";
+import { OAuth2Client } from "oslo/oauth2";
+import { getIssuerVariations, getOauthEndpoints } from "@/lib/oauth.js";
+import * as jose from "jose";
+import { withoutUndefined } from "@/utils.js";
+import type { PKCEConsumer, PKCEProducer } from "@/services/types.js";
+import { GenericUserSession } from "@/shared/lib/UserSession.js";
+
+/**
+ * Given a PKCE code verifier, derive the code challenge using SHA
+ */
+export async function deriveCodeChallenge(
+  codeVerifier: string,
+  method: "Plain" | "S256" = "S256",
+): Promise<string> {
+  if (method === "Plain") {
+    console.warn("Using insecure plain code challenge method");
+    return codeVerifier;
+  }
+
+  const encoder = new TextEncoder();
+  const data = encoder.encode(codeVerifier);
+  const digest = await crypto.subtle.digest("SHA-256", data);
+  return btoa(String.fromCharCode(...new Uint8Array(digest)))
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+export async function getEndpointsWithOverrides(
+  oauthServer: string,
+  endpointOverrides: Partial<Endpoints> = {},
+): Promise<Endpoints> {
+  const endpoints = await getOauthEndpoints(oauthServer);
+  return {
+    ...endpoints,
+    ...endpointOverrides,
+  };
+}
+
+export async function generateOauthLoginUrl(config: {
+  clientId: string;
+  scopes: string[];
+  state: string;
+  redirectUrl: string;
+  oauthServer: string;
+  nonce?: string;
+  endpointOverrides?: Partial<Endpoints>;
+  // used to get the PKCE challenge
+  pkceConsumer: PKCEConsumer;
+}): Promise<URL> {
+  const endpoints = await getEndpointsWithOverrides(
+    config.oauthServer,
+    config.endpointOverrides,
+  );
+  const oauth2Client = buildOauth2Client(
+    config.clientId,
+    config.redirectUrl,
+    endpoints,
+  );
+  const challenge = await config.pkceConsumer.getCodeChallenge();
+  const oAuthUrl = await oauth2Client.createAuthorizationURL({
+    state: config.state,
+    scopes: config.scopes,
+  });
+  // The OAuth2 client supports PKCE, but does not allow passing in a code challenge from some other source
+  // It only allows passing in a code verifier which it then hashes itself.
+  oAuthUrl.searchParams.append("code_challenge", challenge);
+  oAuthUrl.searchParams.append("code_challenge_method", "S256");
+  if (config.nonce) {
+    // nonce isn't supported by oslo, so we add it manually
+    oAuthUrl.searchParams.append("nonce", config.nonce);
+  }
+  // Required by the auth server for offline_access scope
+  oAuthUrl.searchParams.append("prompt", "consent");
+
+  return oAuthUrl;
+}
+
+export async function generateOauthLogoutUrl(config: {
+  clientId: string;
+  scopes: string[];
+  oauthServer: string;
+  endpointOverrides?: Partial<Endpoints>;
+  // used to get the PKCE challenge
+  pkceConsumer: PKCEConsumer;
+}): Promise<URL> {
+  // TODO TECH-676: Implement logout
+  console.log("generateOauthLogoutUrl not implemented", config);
+  return new URL("http://localhost");
+}
+
+export function buildOauth2Client(
+  clientId: string,
+  redirectUri: string,
+  endpoints: Endpoints,
+): OAuth2Client {
+  return new OAuth2Client(clientId, endpoints.auth, endpoints.token, {
+    redirectURI: redirectUri,
+  });
+}
+
+export async function exchangeTokens(
+  code: string,
+  state: string,
+  pkceProducer: PKCEProducer,
+  oauth2Client: OAuth2Client,
+  oauthServer: string,
+  endpoints: Endpoints,
+) {
+  const codeVerifier = await pkceProducer.getCodeVerifier();
+  if (!codeVerifier) throw new Error("Code verifier not found in state");
+
+  const tokens =
+    await oauth2Client.validateAuthorizationCode<OIDCTokenResponseBody>(code, {
+      codeVerifier,
+    });
+
+  // Validate relevant tokens
+  try {
+    await validateOauth2Tokens(tokens, endpoints, oauth2Client, oauthServer);
+  } catch (error) {
+    console.error("tokenExchange error", { error, tokens });
+    throw new Error(
+      `OIDC tokens validation failed: ${(error as Error).message}`,
+    );
+  }
+
+  return tokens;
+}
+
+export async function storeTokens(
+  storage: AuthStorage,
+  tokens: OIDCTokenResponseBody,
+) {
+  // store tokens in storage ( TODO we should probably store them against the state to allow multiple logins )
+  await storage.set(OAuthTokens.ID_TOKEN, tokens.id_token);
+  await storage.set(OAuthTokens.ACCESS_TOKEN, tokens.access_token);
+  if (tokens.refresh_token) {
+    await storage.set(OAuthTokens.REFRESH_TOKEN, tokens.refresh_token);
+  }
+}
+
+export async function clearTokens(storage: AuthStorage) {
+  const clearOAuthPromises = Object.values(OAuthTokens).map((cookie) => {
+    storage.set(cookie, "");
+  });
+  const clearCodeVerifierPromises = Object.values(CodeVerifier.COOKIE_NAME).map(
+    (cookie) => {
+      storage.set(cookie, "");
+    },
+  );
+  await Promise.all([...clearOAuthPromises, ...clearCodeVerifierPromises]);
+}
+export async function clearUser(storage: AuthStorage) {
+  const userSession = new GenericUserSession(storage);
+  await userSession.set(null);
+}
+
+export async function retrieveTokens(
+  storage: AuthStorage,
+): Promise<OIDCTokenResponseBody | null> {
+  const idToken = await storage.get(OAuthTokens.ID_TOKEN);
+  const accessToken = await storage.get(OAuthTokens.ACCESS_TOKEN);
+  const refreshToken = await storage.get(OAuthTokens.REFRESH_TOKEN);
+
+  if (!idToken || !accessToken) return null;
+
+  return {
+    id_token: idToken,
+    access_token: accessToken,
+    refresh_token: refreshToken ?? undefined,
+  };
+}
+
+export async function validateOauth2Tokens(
+  tokens: OIDCTokenResponseBody,
+  endpoints: Endpoints,
+  oauth2Client: OAuth2Client,
+  issuer: string,
+): Promise<ParsedTokens> {
+  const JWKS = jose.createRemoteJWKSet(new URL(endpoints.jwks));
+
+  // validate the ID token
+  const idTokenResponse = await jose.jwtVerify<JWTPayload>(
+    tokens.id_token,
+    JWKS,
+    {
+      issuer: getIssuerVariations(issuer),
+      audience: oauth2Client.clientId,
+    },
+  );
+
+  // validate the access token
+  const accessTokenResponse = await jose.jwtVerify<JWTPayload>(
+    tokens.access_token,
+    JWKS,
+    {
+      issuer: getIssuerVariations(issuer),
+    },
+  );
+
+  return withoutUndefined({
+    id_token: idTokenResponse.payload,
+    access_token: accessTokenResponse.payload,
+    refresh_token: tokens.refresh_token,
+  });
+}

package/src/shared/providers/AuthContext.tsx

@@ -0,0 +1,11 @@
+import { createContext } from "react";
+import type { DisplayMode } from "@/types.js";
+
+export type AuthContextType = {
+  signIn: (displayMode?: DisplayMode) => Promise<void>;
+  isAuthenticated: boolean;
+  isLoading: boolean;
+  error: Error | null;
+  signOut: () => Promise<void>;
+};
+export const AuthContext = createContext<AuthContextType | null>(null);

package/src/shared/providers/AuthProvider.tsx

@@ -0,0 +1,390 @@
+"use client";
+
+import React, {
+  type ReactNode,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import type { Config, DisplayMode, SessionData } from "@/types.js";
+import { CivicAuthIframeContainer } from "@/shared/components/CivicAuthIframeContainer.js";
+import { TokenProvider } from "@/shared/providers/TokenProvider.js";
+import { SessionProvider } from "@/shared/providers/SessionProvider.js";
+import { DEFAULT_SCOPES } from "@/constants.js";
+import { authConfig } from "@/config.js";
+import { LoadingIcon } from "@/shared/components/LoadingIcon.js";
+import { isWindowInIframe } from "@/lib/windowUtil.js";
+import { AuthContext } from "@/shared/providers/AuthContext.js";
+import {
+  BrowserAuthenticationInitiator,
+  BrowserAuthenticationService,
+} from "@/services/AuthenticationService.js";
+import type { AuthenticationResolver, PKCEConsumer } from "@/services/types.js";
+import { PopupError } from "@/services/types.js";
+import { ConfidentialClientPKCEConsumer } from "@/services/PKCE.js";
+import { generateState } from "@/lib/oauth.js";
+import { LocalStorageAdapter } from "@/browser/storage.js";
+import { ConfigProvider } from "@/shared/providers/ConfigProvider.js";
+import { getUser } from "../lib/session.js";
+import { GenericUserSession } from "../lib/UserSession.js";
+import { IframeProvider } from "@/shared/providers/IframeProvider.js";
+
+// Global this object setup
+let globalThisObject;
+if (typeof window !== "undefined") {
+  globalThisObject = window;
+} else if (typeof global !== "undefined") {
+  globalThisObject = global;
+} else {
+  globalThisObject = Function("return this")();
+}
+globalThisObject.globalThis = globalThisObject;
+
+export type AuthProviderProps = {
+  children: ReactNode;
+  clientId: string;
+  nonce?: string;
+  onSignIn?: (error?: Error) => void;
+  onSignOut?: () => Promise<void>;
+  modalIframe?: boolean; // set to false if the iframe is being embedded in the client app
+  config?: Config;
+  redirectUrl?: string;
+};
+
+export type InternalAuthProviderProps = AuthProviderProps & {
+  sessionData?: SessionData;
+  pkceConsumer?: PKCEConsumer;
+};
+
+function BlockDisplay({ children }: { children: ReactNode }) {
+  return (
+    <div
+      style={{
+        position: "relative",
+        left: 0,
+        top: 0,
+        zIndex: 50,
+        display: "flex",
+        height: "100vh",
+        width: "100vw",
+        alignItems: "center",
+        justifyContent: "center",
+        backgroundColor: "white",
+      }}
+    >
+      <div
+        style={{
+          position: "absolute",
+          inset: 0,
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          backgroundColor: "white",
+        }}
+      >
+        {children}
+      </div>
+    </div>
+  );
+}
+
+const AuthProvider = ({
+  children,
+  clientId,
+  redirectUrl: inputRedirectUrl,
+  config = authConfig,
+  onSignIn,
+  onSignOut,
+  pkceConsumer,
+  nonce,
+  modalIframe = true,
+  sessionData: inputSessionData,
+}: InternalAuthProviderProps) => {
+  const [iframeUrl, setIframeUrl] = useState<string | null>(null);
+  const [currentUrl, setCurrentUrl] = useState<string | null>(null);
+  const [isInIframe, setIsInIframe] = useState(false);
+  const [authResponseUrl, setAuthResponseUrl] = useState<string | null>(null);
+  const [tokenExchangeError, setTokenExchangeError] = useState<Error>();
+  const [displayMode, setDisplayMode] = useState<DisplayMode>("iframe");
+  const [browserAuthenticationInitiator, setBrowserAuthenticationInitiator] =
+    useState<BrowserAuthenticationInitiator | null>();
+  const [showIFrame, setShowIFrame] = useState(false);
+  const [isRedirecting, setIsRedirecting] = useState(false);
+  const queryClient = useQueryClient();
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+
+  // TODO maybe we want to support or derive serverTokenExchange another way?
+  const serverTokenExchange =
+    pkceConsumer instanceof ConfidentialClientPKCEConsumer;
+  // check if the current window is in an iframe with the iframe id, and set an isInIframe state
+  useEffect(() => {
+    if (typeof globalThis.window !== "undefined") {
+      setCurrentUrl(globalThis.window.location.href);
+      const isInIframeVal = isWindowInIframe(globalThis.window);
+      setIsInIframe(isInIframeVal);
+    }
+  }, []);
+
+  const redirectUrl = useMemo(
+    () => (inputRedirectUrl || currentUrl || "").split("?")[0],
+    [currentUrl, inputRedirectUrl],
+  );
+
+  const [authService, setAuthService] = useState<AuthenticationResolver>();
+
+  useEffect(() => {
+    if (!currentUrl || !redirectUrl) return;
+    BrowserAuthenticationService.build({
+      clientId,
+      redirectUrl,
+      oauthServer: config.oauthServer,
+      scopes: DEFAULT_SCOPES,
+      displayMode,
+    }).then(setAuthService);
+  }, [currentUrl, clientId, redirectUrl, config, displayMode]);
+
+  const {
+    data: session,
+    isLoading,
+    error,
+  } = useQuery({
+    queryKey: [
+      "session",
+      authResponseUrl,
+      iframeUrl,
+      currentUrl,
+      isInIframe,
+      authService,
+    ],
+    queryFn: async () => {
+      if (!authService) {
+        return { authenticated: false };
+      }
+      if (inputSessionData) {
+        return inputSessionData;
+      }
+      const url = new URL(
+        authResponseUrl
+          ? authResponseUrl
+          : globalThis.window.location.href || "",
+      );
+      // if we have existing tokens, then validate them and return the session data
+      // otherwise check if we have a code in the url and exchange it for tokens
+      // if we have neither, return undefined
+      const existingSessionData = await authService.validateExistingSession();
+      if (existingSessionData.authenticated) {
+        return existingSessionData;
+      }
+      const code = url.searchParams.get("code");
+      const state = url.searchParams.get("state");
+      if (!serverTokenExchange && code && state && !isInIframe) {
+        try {
+          await authService.tokenExchange(code, state);
+          const clientStorage = new LocalStorageAdapter();
+          const user = await getUser(clientStorage);
+          if (!user) {
+            throw new Error("Failed to get user info");
+          }
+
+          const userSession = new GenericUserSession(clientStorage);
+          userSession.set(user);
+
+          onSignIn?.(); // Call onSignIn without an error if successful
+          return authService.getSessionData();
+        } catch (error) {
+          setTokenExchangeError(error as Error);
+          onSignIn?.(
+            error instanceof Error ? error : new Error("Failed to sign in"),
+          ); // Pass the error to onSignIn
+          return { authenticated: false };
+        }
+      }
+
+      return existingSessionData;
+    },
+  });
+
+  const signOutMutation = useMutation({
+    mutationFn: async () => {
+      await onSignOut?.();
+      // Implement signOut logic here
+      const authInitiator = getAuthInitiator();
+      await authInitiator?.signOut();
+      setIframeUrl(null);
+      setShowIFrame(false);
+      setAuthResponseUrl(null);
+    },
+    onSuccess: () => {
+      queryClient.setQueryData(
+        [
+          "session",
+          authResponseUrl,
+          iframeUrl,
+          currentUrl,
+          isInIframe,
+          authService,
+        ],
+        null,
+      );
+    },
+  });
+
+  const getAuthInitiator = useCallback(
+    (overrideDisplayMode?: DisplayMode) => {
+      const useDisplayMode = overrideDisplayMode || displayMode;
+      if (!pkceConsumer || !redirectUrl) {
+        return null;
+      }
+      return (
+        browserAuthenticationInitiator ||
+        new BrowserAuthenticationInitiator({
+          pkceConsumer, // generate and retrieve the challenge client-side
+          clientId,
+          redirectUrl,
+          state: generateState(useDisplayMode, serverTokenExchange),
+          scopes: DEFAULT_SCOPES,
+          displayMode: useDisplayMode,
+          oauthServer: config.oauthServer,
+          // the endpoints to use for the login (if not obtained from the auth server
+          endpointOverrides: config.endpoints,
+          nonce,
+        })
+      );
+    },
+    [
+      serverTokenExchange,
+      displayMode,
+      browserAuthenticationInitiator,
+      clientId,
+      redirectUrl,
+      config.oauthServer,
+      config.endpoints,
+      pkceConsumer,
+      nonce,
+    ],
+  );
+
+  const signIn = useCallback(
+    async (overrideDisplayMode: DisplayMode = "iframe") => {
+      setDisplayMode(overrideDisplayMode);
+      const authInitiator = getAuthInitiator(overrideDisplayMode);
+      setBrowserAuthenticationInitiator(authInitiator);
+      if (overrideDisplayMode === "iframe") {
+        setShowIFrame(true);
+      } else if (overrideDisplayMode === "redirect") {
+        setIsRedirecting(true);
+      }
+      authInitiator?.signIn(iframeRef.current).catch((error) => {
+        console.log("signIn error", {
+          error,
+          isPopupError: error instanceof PopupError,
+        });
+        // if we've tried to open a popup and it has failed, then fallback to redirect mode
+        if (error instanceof PopupError) {
+          signIn("redirect");
+        }
+      });
+    },
+    [getAuthInitiator],
+  );
+
+  // remove event listeners when the component unmounts
+  useEffect(() => {
+    return () => {
+      if (browserAuthenticationInitiator) {
+        browserAuthenticationInitiator.cleanup();
+      }
+    };
+  }, [browserAuthenticationInitiator]);
+
+  const isAuthenticated = useMemo(
+    () => (session ? session.authenticated : false),
+    [session],
+  );
+
+  useQuery({
+    queryKey: ["autoSignIn", modalIframe, redirectUrl, isAuthenticated],
+    queryFn: async () => {
+      if (
+        !modalIframe &&
+        redirectUrl &&
+        !isAuthenticated &&
+        iframeRef.current
+      ) {
+        signIn("iframe");
+      }
+      return true;
+    },
+    refetchOnWindowFocus: false,
+  });
+
+  const value = useMemo(
+    () => ({
+      isLoading,
+      error: error as Error | null,
+      signOut: async () => {
+        await signOutMutation.mutateAsync();
+      },
+      isAuthenticated,
+      signIn,
+    }),
+    [isLoading, error, signOutMutation, isAuthenticated, signIn],
+  );
+
+  if (!redirectUrl) return null;
+
+  return (
+    <AuthContext.Provider value={value}>
+      <ConfigProvider
+        config={config}
+        redirectUrl={redirectUrl}
+        modalIframe={modalIframe}
+        serverTokenExchange={serverTokenExchange}
+      >
+        <IframeProvider
+          setAuthResponseUrl={setAuthResponseUrl}
+          iframeRef={iframeRef}
+        >
+          <SessionProvider session={session}>
+            <TokenProvider>
+              {modalIframe && !isInIframe && !session?.authenticated && (
+                <div
+                  style={
+                    showIFrame ? { display: "block" } : { display: "none" }
+                  }
+                >
+                  <CivicAuthIframeContainer
+                    onClose={() => setShowIFrame(false)}
+                  />
+                </div>
+              )}
+
+              {modalIframe &&
+                (isInIframe ||
+                  isRedirecting ||
+                  (isLoading && !serverTokenExchange)) && (
+                  <BlockDisplay>
+                    <LoadingIcon />
+                  </BlockDisplay>
+                )}
+
+              {(tokenExchangeError || error) && (
+                <BlockDisplay>
+                  <div>
+                    Error: {(tokenExchangeError || (error as Error)).message}
+                  </div>
+                </BlockDisplay>
+              )}
+              {children}
+            </TokenProvider>
+          </SessionProvider>
+        </IframeProvider>
+      </ConfigProvider>
+    </AuthContext.Provider>
+  );
+};
+
+export { AuthProvider };

package/src/shared/providers/CivicAuthProvider.tsx

@@ -0,0 +1,31 @@
+"use client";
+import React from "react";
+import {
+  AuthProvider,
+  type AuthProviderProps,
+} from "@/shared/providers/AuthProvider.js";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { BrowserPublicClientPKCEProducer } from "@/services/PKCE.js";
+import { UserProvider } from "./UserProvider.js";
+import { LocalStorageAdapter } from "@/browser/storage.js";
+
+const queryClient = new QueryClient();
+
+type CivicAuthProviderProps = Omit<AuthProviderProps, "pkceConsumer">;
+
+const CivicAuthProvider = ({ children, ...props }: CivicAuthProviderProps) => {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <AuthProvider
+        {...props}
+        pkceConsumer={new BrowserPublicClientPKCEProducer()}
+      >
+        <UserProvider storage={new LocalStorageAdapter()}>
+          {children}
+        </UserProvider>
+      </AuthProvider>
+    </QueryClientProvider>
+  );
+};
+
+export { CivicAuthProvider, type CivicAuthProviderProps };

package/src/shared/providers/ConfigProvider.tsx

@@ -0,0 +1,50 @@
+"use client";
+import { authConfig } from "@/config.js";
+import type { Config } from "@/types.js";
+import type { ReactNode } from "react";
+import React, { createContext } from "react";
+
+export type ConfigProviderOutput = {
+  config: Config;
+  redirectUrl: string;
+  modalIframe: boolean;
+  serverTokenExchange: boolean;
+};
+const defaultConfig: ConfigProviderOutput = {
+  config: authConfig,
+  redirectUrl: "",
+  modalIframe: true,
+  serverTokenExchange: false,
+};
+// Context for exposing Config specifically to the TokenProvider
+const ConfigContext = createContext<ConfigProviderOutput>(defaultConfig);
+
+type ConfigContextType = {
+  children: ReactNode;
+  config: Config;
+  redirectUrl: string;
+  modalIframe?: boolean;
+  serverTokenExchange: boolean;
+};
+
+const ConfigProvider = ({
+  children,
+  config,
+  redirectUrl,
+  modalIframe,
+  serverTokenExchange,
+}: ConfigContextType) => (
+  <ConfigContext.Provider
+    value={{
+      config,
+      redirectUrl,
+      modalIframe: !!modalIframe,
+      serverTokenExchange,
+    }}
+  >
+    {children}
+  </ConfigContext.Provider>
+);
+
+export type { ConfigContextType };
+export { ConfigProvider, ConfigContext };