@civic/auth 0.0.1-beta.9.1 → 0.0.1-tsc.alpha.2

package/src/services/types.ts

@@ -0,0 +1,54 @@
+import type { OIDCTokenResponseBody, SessionData } from "@/types.js";
+
+// A PKCEConsumer can get a code challenge to use in the login process
+// A PKCEProducer can also generate and store verifiers. The producer must also be a consumer in order to get the challenge from an existing flow
+// Examples:
+// - Client-only SPA: The SPA generates the code challenge and verifier, stores the verifier in state and returns the code challenge
+// Note - The SPA should use PKCEProducer instead to do both
+// - Client-side of a client/server app: The client calls the backend to get the challenge.
+// - Server-side: The server should generate a new stored verifier and derive the challenge from it.
+export interface PKCEConsumer {
+  // Retrieve a new PKCE challenge
+  getCodeChallenge(): Promise<string>;
+}
+
+// All producers are consumers, because the producer can get its own challenge
+export interface PKCEProducer extends PKCEConsumer {
+  // Retrieve the PKCE challenge from the session if one exists
+  getCodeVerifier(): Promise<string | null>;
+}
+
+// A service that can initiate requests to login or log out
+export interface AuthenticationInitiator {
+  // trigger a new login
+  signIn(iframeRef: HTMLIFrameElement | null): Promise<URL>;
+
+  // trigger a new logout
+  signOut(): Promise<URL>;
+}
+
+// A service that can resolve an authentication request according to the OAuth Auth Code grant types
+export interface AuthenticationResolver {
+  // Given an auth code, get the tokens from the auth server and store them. works in PKCE and non-PKCE environments
+  // Note, if we choose later to implement other grants, this method would move into a subinterface specifically
+  // for the authorization code grant type.
+  // The return type is just for convenience and can be ignored, as the same data would be provided by getSessionData
+  tokenExchange(code: string, state: string): Promise<OIDCTokenResponseBody>;
+
+  // If the tokens have already been retrieved, return them
+  getSessionData(): Promise<SessionData | null>;
+
+  // If an existing session is found, validate it and return the session data
+  validateExistingSession(): Promise<SessionData>;
+}
+
+export interface AuthenticationRefresher {
+  refreshTokens: () => Promise<OIDCTokenResponseBody>;
+}
+
+export class PopupError extends Error {
+  constructor(message: string) {
+    super(message);
+    Object.setPrototypeOf(this, PopupError.prototype);
+  }
+}

package/src/shared/components/CivicAuthIframe.tsx

@@ -0,0 +1,26 @@
+"use client";
+import { IFRAME_ID } from "@/constants.js";
+import React, { forwardRef } from "react";
+
+type CivicAuthIframeProps = {
+  onLoad?: () => void;
+};
+
+const CivicAuthIframe = forwardRef<HTMLIFrameElement, CivicAuthIframeProps>(
+  ({ onLoad }, ref) => {
+    return (
+      <iframe
+        id={IFRAME_ID}
+        ref={ref}
+        style={{ height: "26rem", width: "100%", border: "none" }}
+        onLoad={onLoad}
+      />
+    );
+  },
+);
+
+CivicAuthIframe.displayName = "CivicAuthIframe";
+
+export type { CivicAuthIframeProps };
+
+export { CivicAuthIframe };

package/src/shared/components/CivicAuthIframeContainer.tsx

@@ -0,0 +1,194 @@
+"use client";
+
+import React, { useCallback, useEffect, useRef, useState } from "react";
+import { LoadingIcon } from "@/shared/components/LoadingIcon.js";
+import { CloseIcon } from "@/shared/components/CloseIcon.js";
+import { CivicAuthIframe } from "@/shared/components/CivicAuthIframe.js";
+import { useAuth, useConfig, useIframe } from "@/shared/hooks/index.js";
+import { TOKEN_EXCHANGE_TRIGGER_TEXT } from "@/constants.js";
+
+type CivicAuthIframeContainerProps = {
+  onClose?: () => void;
+  closeOnRedirect?: boolean;
+};
+
+function NoChrome({
+  children,
+}: {
+  children: React.ReactNode;
+  onClose?: () => void;
+}) {
+  return <div style={{ position: "relative" }}>{children}</div>;
+}
+
+function IframeChrome({
+  children,
+  onClose,
+}: {
+  children: React.ReactNode;
+  onClose?: () => void;
+}) {
+  return (
+    <div
+      style={{
+        position: "absolute",
+        left: 0,
+        top: 0,
+        zIndex: 50,
+        display: "flex",
+        height: "100vh",
+        width: "100vw",
+        minWidth: "18rem",
+        alignItems: "center",
+        justifyContent: "center",
+        backgroundColor: "rgba(17, 24, 39, 0.5)",
+      }}
+      onClick={onClose}
+    >
+      <div
+        style={{
+          position: "relative",
+          overflow: "hidden",
+          borderRadius: "1.5rem",
+          backgroundColor: "white",
+          padding: "1.5rem",
+          boxShadow:
+            "0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05)",
+        }}
+        onClick={(e) => e.stopPropagation()}
+      >
+        <button
+          style={{
+            position: "absolute",
+            right: "1rem",
+            top: "1rem",
+            display: "flex",
+            cursor: "pointer",
+            alignItems: "center",
+            justifyContent: "center",
+            border: "none",
+            backgroundColor: "transparent",
+            padding: "0.25rem",
+            color: "#9ca3af",
+          }}
+          onClick={onClose}
+        >
+          <CloseIcon />
+        </button>
+
+        {children}
+      </div>
+    </div>
+  );
+}
+const CivicAuthIframeContainer = ({
+  onClose,
+  closeOnRedirect = true,
+}: CivicAuthIframeContainerProps) => {
+  const [isLoading, setIsLoading] = useState(true);
+  const { isLoading: isAuthLoading } = useAuth();
+  const config = useConfig();
+  const { setAuthResponseUrl, iframeRef } = useIframe();
+  const processIframeUrl = useCallback(() => {
+    if (iframeRef && iframeRef.current && iframeRef.current.contentWindow) {
+      try {
+        const iframeUrl = iframeRef.current.contentWindow.location.href;
+        // we know that oauth has finished when the iframe redirects to our redirectUrl
+        if (iframeUrl.startsWith(config.redirectUrl)) {
+          // we still want to show the spinner during redirect
+          setIsLoading(true);
+          const iframeBody =
+            iframeRef.current.contentWindow.document.body.innerHTML;
+
+          // If we're doing a server token exchange, we need to call the server a second time
+          // using a fetch so that we're on the same domain and cookies can be sent and read
+          // The server will use the presence of the code_verifier cookie to determine whether to do a token exchange or not.
+          // On the initial (3rd party) redirect from the auth server, the cookie won't be sent, so the server-side callback route will just render a blank page,
+          // and we'll do the exchange request from here, which will include the cookies.
+          if (iframeBody.includes(TOKEN_EXCHANGE_TRIGGER_TEXT)) {
+            console.log(
+              `${TOKEN_EXCHANGE_TRIGGER_TEXT}, calling callback URL again...`,
+            );
+            const params = new URL(iframeUrl).searchParams;
+            const appUrl = globalThis.window?.location?.origin;
+            fetch(
+              `${config.redirectUrl}?${params.toString()}&appUrl=${appUrl}`,
+            );
+          } else {
+            // if we're doing token-exchange in the client, we can just set the authResponseUrl
+            // to be handled by the auth provider
+            setAuthResponseUrl(iframeUrl);
+          }
+
+          if (closeOnRedirect) onClose?.();
+          return true; // Successfully processed the URL
+        }
+      } catch {
+        // If we get here, the iframe hasn't redirected to our origin yet
+        console.log("Waiting for redirect...");
+      }
+    }
+    return false; // Haven't processed the URL yet
+  }, [
+    closeOnRedirect,
+    config.redirectUrl,
+    iframeRef,
+    onClose,
+    setAuthResponseUrl,
+  ]);
+
+  const intervalId = useRef<NodeJS.Timeout>();
+
+  const handleEscape = useCallback(
+    (event: KeyboardEvent) => {
+      if (event.key === "Escape") {
+        onClose?.();
+      }
+    },
+    [onClose],
+  );
+
+  // handle Escape
+  useEffect(() => {
+    window.addEventListener("keydown", handleEscape);
+
+    return () => window.removeEventListener("keydown", handleEscape);
+  });
+
+  const handleIframeLoad = () => {
+    setIsLoading(false);
+    console.log("handleIframeLoad");
+    if (processIframeUrl() && intervalId.current) {
+      clearInterval(intervalId.current);
+    }
+  };
+  const showLoadingIcon =
+    isLoading || isAuthLoading || !iframeRef?.current?.getAttribute("src");
+
+  const WrapperComponent = config.modalIframe ? IframeChrome : NoChrome;
+
+  return (
+    <WrapperComponent onClose={onClose}>
+      {showLoadingIcon && (
+        <div
+          style={{
+            position: "absolute",
+            inset: 0,
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            backgroundColor: "white",
+          }}
+        >
+          <LoadingIcon />
+        </div>
+      )}
+
+      <CivicAuthIframe ref={iframeRef} onLoad={handleIframeLoad} />
+    </WrapperComponent>
+  );
+};
+
+export type { CivicAuthIframeContainerProps };
+
+export { CivicAuthIframeContainer };

package/src/shared/components/CloseIcon.tsx

@@ -0,0 +1,21 @@
+import React from "react";
+
+const CloseIcon = () => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    width="24"
+    height="24"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    className="lucide lucide-x"
+  >
+    <path d="M18 6 6 18" />
+    <path d="m6 6 12 12" />
+  </svg>
+);
+
+export { CloseIcon };

package/src/shared/components/LoadingIcon.tsx

@@ -0,0 +1,45 @@
+import React from "react";
+
+const LoadingIcon = () => (
+  <div role="status">
+    <svg
+      aria-hidden="true"
+      style={{
+        display: "inline",
+        height: "2rem",
+        width: "2rem",
+        animation: "spin 1s linear infinite",
+        fill: "#4b5563",
+        color: "#e5e7eb",
+      }}
+      viewBox="0 0 100 101"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      <path
+        d="M100 50.5908C100 78.2051 77.6142 100.591 50 100.591C22.3858 100.591 0 78.2051 0 50.5908C0 22.9766 22.3858 0.59082 50 0.59082C77.6142 0.59082 100 22.9766 100 50.5908ZM9.08144 50.5908C9.08144 73.1895 27.4013 91.5094 50 91.5094C72.5987 91.5094 90.9186 73.1895 90.9186 50.5908C90.9186 27.9921 72.5987 9.67226 50 9.67226C27.4013 9.67226 9.08144 27.9921 9.08144 50.5908Z"
+        fill="currentColor"
+      />
+      <path
+        d="M93.9676 39.0409C96.393 38.4038 97.8624 35.9116 97.0079 33.5539C95.2932 28.8227 92.871 24.3692 89.8167 20.348C85.8452 15.1192 80.8826 10.7238 75.2124 7.41289C69.5422 4.10194 63.2754 1.94025 56.7698 1.05124C51.7666 0.367541 46.6976 0.446843 41.7345 1.27873C39.2613 1.69328 37.813 4.19778 38.4501 6.62326C39.0873 9.04874 41.5694 10.4717 44.0505 10.1071C47.8511 9.54855 51.7191 9.52689 55.5402 10.0491C60.8642 10.7766 65.9928 12.5457 70.6331 15.2552C75.2735 17.9648 79.3347 21.5619 82.5849 25.841C84.9175 28.9121 86.7997 32.2913 88.1811 35.8758C89.083 38.2158 91.5421 39.6781 93.9676 39.0409Z"
+        fill="currentFill"
+      />
+    </svg>
+    <span
+      style={{
+        position: "absolute",
+        width: "1px",
+        height: "1px",
+        padding: 0,
+        margin: "-1px",
+        overflow: "hidden",
+        clip: "rect(0, 0, 0, 0)",
+        border: 0,
+      }}
+    >
+      Loading...
+    </span>
+  </div>
+);
+
+export { LoadingIcon };

package/src/shared/hooks/index.ts

@@ -0,0 +1,4 @@
+export { useToken } from "@/shared/hooks/useToken.js";
+export { useAuth } from "@/shared/hooks/useAuth.js";
+export { useConfig } from "@/shared/hooks/useConfig.js";
+export { useIframe } from "@/shared/hooks/useIframe.js";

package/src/shared/hooks/useAuth.ts

@@ -0,0 +1,15 @@
+"use client";
+import { useContext } from "react";
+import { AuthContext } from "@/shared/providers/AuthContext.js";
+
+const useAuth = () => {
+  const context = useContext(AuthContext);
+
+  if (!context) {
+    throw new Error("useAuth must be used within an AuthProvider");
+  }
+
+  return context;
+};
+
+export { useAuth };

package/src/shared/hooks/useConfig.ts

@@ -0,0 +1,14 @@
+"use client";
+import { useContext } from "react";
+import { ConfigContext } from "@/shared/providers/ConfigProvider.js";
+
+// TokenProvider will use this internal context to access Config
+const useConfig = () => {
+  const context = useContext(ConfigContext);
+  if (!context) {
+    throw new Error("useConfig must be used within an ConfigProvider");
+  }
+  return context;
+};
+
+export { useConfig };

package/src/shared/hooks/useIframe.ts

@@ -0,0 +1,14 @@
+"use client";
+import { useContext } from "react";
+import { IframeContext } from "@/shared/providers/IframeProvider.js";
+
+// TokenProvider will use this internal context to access Iframe
+const useIframe = () => {
+  const context = useContext(IframeContext);
+  if (!context) {
+    throw new Error("useIframe must be used within an IframeProvider");
+  }
+  return context;
+};
+
+export { useIframe };

package/src/shared/hooks/useSession.ts

@@ -0,0 +1,14 @@
+"use client";
+import { useContext } from "react";
+import { SessionContext } from "@/shared/providers/SessionProvider.js";
+
+// TokenProvider will use this internal context to access session
+const useSession = () => {
+  const context = useContext(SessionContext);
+  if (!context) {
+    throw new Error("useSession must be used within an SessionProvider");
+  }
+  return context;
+};
+
+export { useSession };

package/src/shared/hooks/useToken.ts

@@ -0,0 +1,15 @@
+"use client";
+import { useContext } from "react";
+import { TokenContext } from "@/shared/providers/TokenProvider.js";
+
+const useToken = () => {
+  const context = useContext(TokenContext);
+
+  if (!context) {
+    throw new Error("useToken must be used within a TokenProvider");
+  }
+
+  return context;
+};
+
+export { useToken };

package/src/shared/lib/GenericAuthenticationRefresher.ts

@@ -0,0 +1,75 @@
+import type { AuthenticationRefresher } from "@/services/types.js";
+import type { AuthStorage, Endpoints, OIDCTokenResponseBody } from "@/types.js";
+import {
+  getEndpointsWithOverrides,
+  retrieveTokens,
+  storeTokens,
+} from "@/shared/lib/util.js";
+import type { AuthConfig } from "@/server/config.js";
+import { OAuth2Client } from "oslo/oauth2";
+
+export class GenericAuthenticationRefresher implements AuthenticationRefresher {
+  private oauth2client: OAuth2Client | undefined;
+  private endpoints: Endpoints | undefined;
+
+  private constructor(
+    private authConfig: AuthConfig,
+    private storage: AuthStorage,
+    private endpointOverrides?: Partial<Endpoints>,
+  ) {
+    console.log("GenericAuthenticationRefresher constructor", {
+      authConfig,
+      endpointOverrides,
+    });
+  }
+
+  async init(): Promise<this> {
+    // resolve oauth config
+    this.endpoints = await getEndpointsWithOverrides(
+      this.authConfig.oauthServer,
+      this.endpointOverrides,
+    );
+    this.oauth2client = new OAuth2Client(
+      this.authConfig.clientId,
+      this.endpoints.auth,
+      this.endpoints.token,
+      {
+        redirectURI: this.authConfig.redirectUrl,
+      },
+    );
+
+    return this;
+  }
+
+  static async build(
+    authConfig: AuthConfig,
+    storage: AuthStorage,
+    endpointOverrides?: Partial<Endpoints>,
+  ): Promise<GenericAuthenticationRefresher> {
+    const refresher = new GenericAuthenticationRefresher(
+      authConfig,
+      storage,
+      endpointOverrides,
+    );
+    await refresher.init();
+
+    return refresher;
+  }
+
+  async refreshTokens() {
+    if (!this.oauth2client) await this.init();
+
+    const tokens = retrieveTokens(this.storage);
+    if (!tokens?.refresh_token) throw new Error("No refresh token available");
+
+    const oauth2Client = this.oauth2client!;
+    const refreshedTokens =
+      await oauth2Client.refreshAccessToken<OIDCTokenResponseBody>(
+        tokens.refresh_token,
+      );
+
+    storeTokens(this.storage, refreshedTokens);
+
+    return tokens;
+  }
+}

package/src/shared/lib/UserSession.ts

@@ -0,0 +1,25 @@
+import type { AuthStorage, ForwardedTokensJWT, User } from "@/types.js";
+import { UserStorage } from "@/shared/lib/types.js";
+import { convertForwardedTokenFormat } from "@/lib/jwt.js";
+
+export interface UserSession {
+  get(): User | null;
+  set(user: User): void;
+}
+
+export class GenericUserSession implements UserSession {
+  constructor(readonly storage: AuthStorage) {}
+
+  get(): User | null {
+    const user = this.storage.get(UserStorage.USER);
+    return user ? JSON.parse(user) : null;
+  }
+
+  set(user: User | null): void {
+    const forwardedTokens = user?.forwardedTokens
+      ? convertForwardedTokenFormat(user?.forwardedTokens as ForwardedTokensJWT)
+      : null;
+    const value = user ? JSON.stringify({ ...user, forwardedTokens }) : "";
+    this.storage.set(UserStorage.USER, value);
+  }
+}

package/src/shared/lib/session.ts

@@ -0,0 +1,11 @@
+import { retrieveTokens } from "@/shared/lib/util.js";
+import { parseJWT } from "oslo/jwt";
+import type { AuthStorage, User } from "@/types.js";
+
+export async function getUser(storage: AuthStorage): Promise<User | null> {
+  const tokens = retrieveTokens(storage);
+  if (!tokens) return null;
+
+  // Assumes all information is in the ID token
+  return (parseJWT(tokens.id_token)?.payload as User) ?? null;
+}

package/src/shared/lib/storage.ts

@@ -0,0 +1,40 @@
+import type { AuthStorage, SessionData, UnknownObject, User } from "@/types.js";
+
+type SameSiteOption = "strict" | "lax" | "none";
+
+export interface SessionStorage {
+  get(): SessionData;
+  getUser(): User<UnknownObject> | null;
+  set(data: Partial<SessionData>): void;
+  setUser(data: User<UnknownObject> | null): void;
+  clear(): void;
+}
+
+export type CookieStorageSettings = {
+  httpOnly: boolean;
+  secure: boolean;
+  sameSite: SameSiteOption;
+  expires: Date;
+  path: string;
+};
+
+export const DEFAULT_COOKIE_DURATION = 60 * 15; // 15 minutes
+
+export abstract class CookieStorage implements AuthStorage {
+  protected settings: CookieStorageSettings;
+  protected constructor(settings: Partial<CookieStorageSettings> = {}) {
+    this.settings = {
+      httpOnly: settings.httpOnly ?? true,
+      secure: settings.secure ?? true,
+      // the callback request comes the auth server
+      // 'lax' ensures the code_verifier cookie is sent with the request
+      sameSite: settings.sameSite ?? "lax",
+      expires:
+        settings.expires ??
+        new Date(Date.now() + 1000 * DEFAULT_COOKIE_DURATION),
+      path: settings.path ?? "/",
+    };
+  }
+  abstract get(key: string): string | null;
+  abstract set(key: string, value: string): void;
+}

package/src/shared/lib/types.ts

@@ -0,0 +1,26 @@
+export enum OAuthTokens {
+  ID_TOKEN = "id_token",
+  ACCESS_TOKEN = "access_token",
+  REFRESH_TOKEN = "refresh_token",
+}
+
+export enum CodeVerifier {
+  COOKIE_NAME = "code_verifier",
+  APP_URL = "app_url",
+}
+export enum UserStorage {
+  USER = "user",
+}
+export interface CookieConfig {
+  secure?: boolean;
+  sameSite?: "strict" | "lax" | "none";
+  domain?: string;
+  path?: string;
+  maxAge?: number;
+  httpOnly?: boolean;
+}
+
+export type TokensCookieConfig = Record<
+  OAuthTokens | CodeVerifier,
+  CookieConfig
+>;