@civic/auth 0.0.1--.tsc.alpha.1

package/src/lib/logger.ts

@@ -0,0 +1,72 @@
+import debug from "debug";
+
+const PACKAGE_NAME = "@civic/auth";
+
+export interface Logger {
+  debug(message: string, ...args: unknown[]): void;
+  info(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+}
+
+class DebugLogger implements Logger {
+  private debugLogger: debug.Debugger;
+  private infoLogger: debug.Debugger;
+  private warnLogger: debug.Debugger;
+  private errorLogger: debug.Debugger;
+
+  constructor(namespace: string) {
+    // Format: @org/package:library:component:level
+    this.debugLogger = debug(`${PACKAGE_NAME}:${namespace}:debug`);
+    this.infoLogger = debug(`${PACKAGE_NAME}:${namespace}:info`);
+    this.warnLogger = debug(`${PACKAGE_NAME}:${namespace}:warn`);
+    this.errorLogger = debug(`${PACKAGE_NAME}:${namespace}:error`);
+
+    this.debugLogger.color = "4";
+    this.infoLogger.color = "2";
+    this.warnLogger.color = "3";
+    this.errorLogger.color = "1";
+  }
+
+  debug(message: string, ...args: unknown[]): void {
+    this.debugLogger(message, ...args);
+  }
+
+  info(message: string, ...args: unknown[]): void {
+    this.infoLogger(message, ...args);
+  }
+
+  warn(message: string, ...args: unknown[]): void {
+    this.warnLogger(message, ...args);
+  }
+
+  error(message: string, ...args: unknown[]): void {
+    this.errorLogger(message, ...args);
+  }
+}
+
+export const createLogger = (namespace: string): Logger =>
+  new DebugLogger(namespace);
+
+// Pre-configured loggers for different parts of your package
+export const loggers = {
+  // Next.js specific loggers
+  nextjs: {
+    routes: createLogger("api:routes"),
+    middleware: createLogger("api:middleware"),
+    handlers: {
+      auth: createLogger("api:handlers:auth"),
+    },
+  },
+  // React specific loggers
+  react: {
+    components: createLogger("react:components"),
+    hooks: createLogger("react:hooks"),
+    context: createLogger("react:context"),
+  },
+  // Shared utilities loggers
+  services: {
+    validation: createLogger("utils:validation"),
+    network: createLogger("utils:network"),
+  },
+} as const;

package/src/lib/oauth.ts

@@ -0,0 +1,83 @@
+import type { DisplayMode, Endpoints, OpenIdConfiguration } from "@/types.js";
+import { v4 as uuid } from "uuid";
+
+const getIssuerVariations = (issuer: string): string[] => {
+  const issuerWithoutSlash = issuer.endsWith("/")
+    ? issuer.slice(0, issuer.length - 1)
+    : issuer;
+
+  const issuerWithSlash = `${issuerWithoutSlash}/`;
+
+  return [issuerWithoutSlash, issuerWithSlash];
+};
+
+const addSlashIfNeeded = (url: string): string =>
+  url.endsWith("/") ? url : `${url}/`;
+
+const getOauthEndpoints = async (oauthServer: string): Promise<Endpoints> => {
+  const openIdConfigResponse = await fetch(
+    `${addSlashIfNeeded(oauthServer)}.well-known/openid-configuration`,
+  );
+  const openIdConfig =
+    (await openIdConfigResponse.json()) as OpenIdConfiguration;
+  return {
+    jwks: openIdConfig.jwks_uri,
+    auth: openIdConfig.authorization_endpoint,
+    token: openIdConfig.token_endpoint,
+    userinfo: openIdConfig.userinfo_endpoint,
+  };
+};
+
+/**
+ * creates a state string for the OAuth2 flow, encoding the display mode too for future use
+ * @param {DisplayMode} displayMode
+ * @returns {string}
+ */
+const generateState = (
+  displayMode: DisplayMode,
+  serverTokenExchange?: boolean,
+): string => {
+  const jsonString = JSON.stringify({
+    uuid: uuid(),
+    displayMode,
+    ...(serverTokenExchange ? { serverTokenExchange } : {}),
+  });
+  return btoa(jsonString);
+};
+
+/**
+ * parses the state string from the OAuth2 flow, decoding the display mode too
+ * @param state
+ * @param sessionDisplayMode
+ * @returns { uuid: string, displayMode: DisplayMode }
+ */
+const displayModeFromState = (
+  state: string,
+  sessionDisplayMode: DisplayMode | undefined,
+): DisplayMode | undefined => {
+  try {
+    const jsonString = atob(state);
+    return JSON.parse(jsonString).displayMode;
+  } catch (e) {
+    console.error("Failed to parse displayMode from state:", state, e);
+    return sessionDisplayMode;
+  }
+};
+
+const serverTokenExchangeFromState = (state: string): boolean | undefined => {
+  try {
+    const jsonString = atob(state);
+    return JSON.parse(jsonString).serverTokenExchange;
+  } catch {
+    console.error("Failed to parse serverTokenExchange from state:", state);
+    return undefined;
+  }
+};
+
+export {
+  serverTokenExchangeFromState,
+  getIssuerVariations,
+  getOauthEndpoints,
+  displayModeFromState,
+  generateState,
+};

package/src/lib/postMessage.ts

@@ -0,0 +1,22 @@
+import type { LoginPostMessage } from "@/types.js";
+
+const validateLoginAppPostMessage = (
+  event: LoginPostMessage,
+  clientId: string,
+): boolean => {
+  const caseEvent = event as LoginPostMessage;
+  console.log("caseEvent", caseEvent);
+  if (
+    !caseEvent.clientId ||
+    !caseEvent.data.url ||
+    !caseEvent.source ||
+    !caseEvent.type ||
+    caseEvent.clientId !== clientId ||
+    caseEvent.source !== "civicloginApp"
+  ) {
+    return false;
+  }
+  return true;
+};
+
+export { validateLoginAppPostMessage };

package/src/lib/windowUtil.ts

@@ -0,0 +1,29 @@
+const isWindowInIframe = (window: Window): boolean => {
+  if (typeof window !== "undefined") {
+    // use the window width to determine if we're in an iframe or not
+    try {
+      if (window?.frameElement?.id === "civic-auth-iframe") {
+        return true;
+      }
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    } catch (_e) {
+      // If we get an error, we're not in an iframe
+      return false;
+    }
+  }
+  return false;
+};
+
+const removeParamsWithoutReload = (paramsToRemove: string[]) => {
+  const url = new URL(window.location.href);
+  paramsToRemove.forEach((param: string) => {
+    url.searchParams.delete(param);
+  });
+  try {
+    window.history.replaceState({}, "", url);
+  } catch (error) {
+    console.warn("window.history.replaceState failed", error);
+  }
+};
+
+export { isWindowInIframe, removeParamsWithoutReload };

package/src/nextjs/GetUser.ts

@@ -0,0 +1,22 @@
+/**
+ * Used on the server-side to get the user object from the cookie
+ */
+import type { User } from "@/types.js";
+import { GenericUserSession } from "@/shared/lib/UserSession.js";
+import { NextjsClientStorage } from "@/nextjs/cookies.js";
+import { retrieveTokens } from "@/shared/lib/util.js";
+
+export const getUser = (): User | null => {
+  const clientStorage = new NextjsClientStorage();
+  const userSession = new GenericUserSession(clientStorage);
+  const tokens = retrieveTokens(clientStorage);
+  const user = userSession.get();
+  if (!user || !tokens) return null;
+
+  return {
+    ...user!,
+    idToken: tokens.id_token,
+    accessToken: tokens.access_token,
+    refreshToken: tokens.refresh_token ?? "",
+  } as User;
+};

package/src/nextjs/client/index.ts

@@ -0,0 +1,4 @@
+export {
+  CivicNextAuthProvider as CivicAuthProvider,
+  type NextCivicAuthProviderProps as AuthProviderProps,
+} from "@/nextjs/providers/NextAuthProvider.jsx";

package/src/nextjs/config.ts

@@ -0,0 +1,203 @@
+/* eslint-disable turbo/no-undeclared-env-vars */
+import type { NextConfig } from "next";
+import { loggers } from "@/lib/logger.js";
+import { withoutUndefined } from "@/utils.js";
+import {
+  CodeVerifier,
+  type CookieConfig,
+  OAuthTokens,
+  type TokensCookieConfig,
+} from "@/shared/lib/types.js";
+import { DEFAULT_AUTH_SERVER } from "@/constants.js";
+
+const logger = loggers.nextjs.handlers.auth;
+
+export type CookiesConfigObject = {
+  tokens: TokensCookieConfig;
+  user: CookieConfig;
+};
+
+export type AuthConfigWithDefaults = {
+  clientId: string;
+  oauthServer: string;
+  callbackUrl: string;
+  loginUrl: string;
+  logoutUrl: string;
+  appUrl?: string;
+  challengeUrl: string;
+  include: string[];
+  exclude: string[];
+  cookies: CookiesConfigObject;
+};
+
+export type AuthConfig = Partial<AuthConfigWithDefaults>;
+
+export type DefinedAuthConfig = AuthConfigWithDefaults;
+
+const appUrl =
+  typeof process !== "undefined" ? process?.env?.NEXT_PUBLIC_APP_URL || "" : "";
+const defaultServerSecure = !appUrl.startsWith("http://localhost");
+
+/**
+ * Default configuration values that will be used if not overridden
+ */
+export const defaultAuthConfig: Omit<AuthConfigWithDefaults, "clientId"> = {
+  oauthServer: DEFAULT_AUTH_SERVER,
+  callbackUrl: "/api/auth/callback",
+  challengeUrl: "/api/auth/challenge",
+  logoutUrl: "/api/auth/logout",
+  loginUrl: "/",
+  include: ["/*"],
+  exclude: [],
+  cookies: {
+    tokens: {
+      [OAuthTokens.ID_TOKEN]: {
+        secure: defaultServerSecure,
+        httpOnly: true,
+        sameSite: "strict",
+        path: "/",
+      },
+      [OAuthTokens.ACCESS_TOKEN]: {
+        secure: defaultServerSecure,
+        httpOnly: true,
+        sameSite: "strict",
+        path: "/",
+      },
+      [OAuthTokens.REFRESH_TOKEN]: {
+        secure: defaultServerSecure,
+        httpOnly: true,
+        sameSite: "strict",
+        path: "/",
+      },
+      [CodeVerifier.COOKIE_NAME]: {
+        secure: defaultServerSecure,
+        httpOnly: true,
+        sameSite: "strict",
+        path: "/",
+      },
+    },
+    user: {
+      secure: defaultServerSecure,
+      httpOnly: false,
+      sameSite: "strict",
+      path: "/",
+      maxAge: 60 * 60, // 1 hour
+    },
+  },
+};
+
+/**
+ * Resolves the authentication configuration by combining:
+ * 1. Default values
+ * 2. Environment variables (set internally by the plugin)
+ * 3. Explicitly passed configuration
+ *
+ * Note: Developers should not set _civic_auth_* environment variables directly.
+ * Instead, pass configuration to the createCivicAuthPlugin in next.config.js:
+ *
+ * @example
+ * ```js
+ * // next.config.js
+ * export default createCivicAuthPlugin({
+ *   callbackUrl: '/custom/callback',
+ * })
+ * ```
+ */
+export const resolveAuthConfig = (
+  config: AuthConfig = {},
+): AuthConfigWithDefaults => {
+  // Read configuration that was set by the plugin via environment variables
+  const configFromEnv = withoutUndefined({
+    clientId: process.env._civic_auth_client_id,
+    oauthServer: process.env._civic_oauth_server,
+    callbackUrl: process.env._civic_auth_callback_url,
+    challengeUrl: process.env._civic_auth_challenge_url,
+    loginUrl: process.env._civic_auth_login_url,
+    appUrl: process.env._civic_auth_app_url,
+    logoutUrl: process.env._civic_auth_logout_url,
+    include: process.env._civic_auth_includes?.split(","),
+    exclude: process.env._civic_auth_excludes?.split(","),
+    cookies: process.env._civic_auth_cookie_config
+      ? JSON.parse(process.env._civic_auth_cookie_config)
+      : undefined,
+  }) as AuthConfig;
+  const mergedConfig = {
+    ...defaultAuthConfig,
+    ...configFromEnv, // Apply plugin-set config
+    ...config, // Override with directly passed config
+    cookies: {
+      tokens: {
+        ...defaultAuthConfig.cookies.tokens,
+        ...(configFromEnv?.cookies?.tokens || {}),
+        ...(config.cookies?.tokens || {}),
+      },
+      user: {
+        ...defaultAuthConfig.cookies.user,
+        ...(configFromEnv?.cookies?.user || {}),
+        ...(config.cookies?.user || {}),
+      },
+    },
+  };
+
+  logger.debug(
+    "Config from environment:",
+    JSON.stringify(configFromEnv, null, 2),
+  );
+  logger.debug("Resolved config:", JSON.stringify(mergedConfig, null, 2));
+  if (mergedConfig.clientId === undefined) {
+    throw new Error("Civic Auth client ID is required");
+  }
+  return mergedConfig as AuthConfigWithDefaults & { clientId: string };
+};
+
+/**
+ * Creates a Next.js plugin that handles auth configuration.
+ *
+ * This is the main configuration point for the auth system.
+ * Do not set _civic_auth_* environment variables directly - instead,
+ * pass your configuration here:
+ *
+ * @example
+ * ```js
+ * // next.config.js
+ * export default createCivicAuthPlugin({
+ *   clientId: 'my-client-id',
+ *   callbackUrl: '/custom/callback',
+ *   loginUrl: '/custom/login',
+ *   logoutUrl: '/custom/logout',
+ *   include: ['/protected/*'],
+ *   exclude: ['/public/*']
+ * })
+ * ```
+ *
+ * The plugin sets internal environment variables that are used by
+ * the auth system. These variables should not be set manually.
+ */
+export const createCivicAuthPlugin = (
+  authConfig: AuthConfig & Pick<Required<AuthConfig>, "clientId">,
+) => {
+  return (nextConfig?: NextConfig) => {
+    logger.debug(
+      "createCivicAuthPlugin nextConfig",
+      JSON.stringify(nextConfig, null, 2),
+    );
+    const resolvedConfig = resolveAuthConfig({ ...authConfig });
+    return {
+      ...nextConfig,
+      env: {
+        ...nextConfig?.env,
+        // Internal environment variables - do not set these manually
+        _civic_auth_client_id: resolvedConfig.clientId,
+        _civic_oauth_server: resolvedConfig.oauthServer,
+        _civic_auth_callback_url: resolvedConfig.callbackUrl,
+        _civic_auth_challenge_url: resolvedConfig.challengeUrl,
+        _civic_auth_login_url: resolvedConfig.loginUrl,
+        _civic_auth_logout_url: resolvedConfig.logoutUrl,
+        _civic_auth_app_url: resolvedConfig.appUrl,
+        _civic_auth_includes: resolvedConfig.include.join(","),
+        _civic_auth_excludes: resolvedConfig.exclude.join(","),
+        _civic_auth_cookie_config: JSON.stringify(resolvedConfig.cookies),
+      },
+    };
+  };
+};

package/src/nextjs/cookies.ts

@@ -0,0 +1,166 @@
+import type { SessionData, UnknownObject, User } from "@/types.js";
+import type { AuthConfig } from "@/nextjs/config.js";
+import { cookies } from "next/headers.js";
+import { GenericUserSession } from "@/shared/lib/UserSession.js";
+import { clearTokens } from "@/shared/lib/util.js";
+import type {
+  CodeVerifier,
+  CookieConfig,
+  OAuthTokens,
+  TokensCookieConfig,
+} from "@/shared/lib/types.js";
+import {
+  CookieStorage,
+  type CookieStorageSettings,
+} from "@/shared/lib/storage.js";
+
+/**
+ * Creates HTTP-only cookies for authentication tokens
+ */
+const createTokenCookies = (
+  response: Response,
+  sessionData: SessionData,
+  config: AuthConfig,
+) => {
+  const maxAge = sessionData.expiresIn ?? 3600;
+  const cookieOptions = {
+    ...config.cookies?.tokens,
+    maxAge,
+  };
+
+  if (sessionData.accessToken) {
+    setCookie(response, "access_token", sessionData.accessToken, {
+      ...cookieOptions,
+      httpOnly: true,
+    });
+  }
+
+  if (sessionData.idToken) {
+    setCookie(response, "id_token", sessionData.idToken, {
+      ...cookieOptions,
+      httpOnly: true,
+    });
+  }
+
+  if (sessionData.refreshToken) {
+    setCookie(response, "refresh_token", sessionData.refreshToken, {
+      ...cookieOptions,
+      httpOnly: true,
+    });
+  }
+};
+
+const setCookie = (
+  response: Response,
+  key: string,
+  value: string,
+  cookieData: CookieConfig,
+) => {
+  response.headers.set(
+    "Set-Cookie",
+    `${key}=${value}; Path=${cookieData.path}; Domain=${cookieData.domain}; Max-Age=${cookieData.maxAge}; Secure; HttpOnly; SameSite=${cookieData.sameSite}`,
+  );
+};
+
+/**
+ * Creates a client-readable cookie with user info
+ */
+const createUserInfoCookie = (
+  response: Response,
+  user: User<UnknownObject> | null,
+  sessionData: SessionData,
+  config: AuthConfig,
+) => {
+  if (!user) {
+    // unset the "user" cookie
+    setCookie(response, "user", "", {
+      ...config.cookies?.user,
+      maxAge: 0,
+    });
+    return;
+  }
+  const maxAge = sessionData.expiresIn ?? 3600;
+
+  // TODO select fields to include in the user cookie
+  const frontendUser = {
+    ...user,
+  };
+
+  // TODO make call to get user info from the
+  // auth server /userinfo endpoint when it's available
+  // then add to the default claims above
+
+  setCookie(response, "user", JSON.stringify(frontendUser), {
+    ...config.cookies?.user,
+    maxAge,
+  });
+};
+
+/**
+ * Clears all authentication cookies
+ */
+const clearAuthCookies = async (config: AuthConfig) => {
+  // clear session, and tokens
+  const cookieStorage = new NextjsCookieStorage(config.cookies?.tokens);
+  clearTokens(cookieStorage);
+
+  // clear user
+  const clientStorage = new NextjsClientStorage();
+  const userSession = new GenericUserSession(clientStorage);
+  userSession.set(null);
+};
+
+type KeySetter = OAuthTokens | CodeVerifier;
+class NextjsCookieStorage extends CookieStorage {
+  constructor(readonly config: Partial<TokensCookieConfig> = {}) {
+    super({
+      secure: true,
+      httpOnly: true,
+    });
+  }
+
+  get(key: string): string | null {
+    return cookies().get(key)?.value || null;
+  }
+
+  set(key: KeySetter, value: string): void {
+    const cookieSettings = this.config?.[key as KeySetter] || {
+      ...this.settings,
+    };
+    console.log(
+      "NextjsCookieStorage.set",
+      JSON.stringify(
+        { key, value, config: this.config, cookieSettings },
+        null,
+        2,
+      ),
+    );
+    cookies().set(key, value, cookieSettings);
+  }
+}
+
+class NextjsClientStorage extends CookieStorage {
+  constructor(config: Partial<CookieStorageSettings> = {}) {
+    super({
+      ...config,
+      secure: false,
+      httpOnly: false,
+    });
+  }
+
+  get(key: string): string | null {
+    return cookies().get(key)?.value || null;
+  }
+
+  set(key: string, value: string): void {
+    cookies().set(key, value, this.settings);
+  }
+}
+
+export {
+  createTokenCookies,
+  createUserInfoCookie,
+  clearAuthCookies,
+  NextjsCookieStorage,
+  NextjsClientStorage,
+};

package/src/nextjs/hooks/index.ts

@@ -0,0 +1 @@
+export { useTokenCookie } from "@/nextjs/hooks/useTokenCookie.js";

package/src/nextjs/hooks/useTokenCookie.ts

@@ -0,0 +1,41 @@
+"use client";
+import { useEffect, useRef } from "react";
+import { useRouter } from "next/navigation.js";
+import { useQuery } from "@tanstack/react-query";
+import { getWindowCookieValue } from "@/lib/cookies.js";
+import type { OAuthTokens } from "@/shared/lib/types.js";
+
+const getTokenFromCookie = (tokenName: OAuthTokens): string => {
+  return getWindowCookieValue({
+    key: tokenName,
+    window: globalThis.window,
+    parseJson: false,
+  });
+};
+
+export const useTokenCookie = (tokenName: OAuthTokens): string | null => {
+  const hasRunRef = useRef(false);
+  const router = useRouter();
+
+  const { data: token } = useQuery({
+    queryKey: ["token", tokenName],
+    queryFn: () => getTokenFromCookie(tokenName) || null,
+    refetchInterval: 2000,
+    refetchIntervalInBackground: true,
+    enabled: !hasRunRef.current,
+    refetchOnWindowFocus: true,
+  });
+
+  useEffect(() => {
+    if (token) {
+      if (!hasRunRef.current) {
+        hasRunRef.current = true;
+        router.refresh();
+      }
+    } else {
+      hasRunRef.current = false;
+    }
+  }, [token, router]);
+
+  return token ?? null;
+};

package/src/nextjs/hooks/useUserCookie.ts

@@ -0,0 +1,41 @@
+"use client";
+import { useEffect, useRef } from "react";
+import { useRouter } from "next/navigation.js";
+import { useQuery } from "@tanstack/react-query";
+import { getWindowCookieValue } from "@/lib/cookies.js";
+import type { EmptyObject, User } from "@/types.js";
+import { UserStorage } from "@/shared/lib/types.js";
+
+const getUserFromCookie = () =>
+  getWindowCookieValue({
+    key: UserStorage.USER,
+    window: globalThis.window,
+    parseJson: true,
+  });
+
+export const useUserCookie = <T extends EmptyObject>() => {
+  const hasRunRef = useRef(false);
+  const router = useRouter();
+
+  const { data: user } = useQuery({
+    queryKey: ["user"],
+    queryFn: () => getUserFromCookie() as User<T> | null,
+    refetchInterval: 2000,
+    refetchIntervalInBackground: true,
+    enabled: !hasRunRef.current,
+    refetchOnWindowFocus: true,
+  });
+
+  useEffect(() => {
+    if (user) {
+      if (!hasRunRef.current) {
+        hasRunRef.current = true;
+        router.refresh();
+      }
+    } else {
+      hasRunRef.current = false;
+    }
+  }, [user, router]);
+
+  return user ?? null;
+};