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

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 = async (): Promise<User | null> => {
+  const clientStorage = new NextjsClientStorage();
+  const userSession = new GenericUserSession(clientStorage);
+  const tokens = await retrieveTokens(clientStorage);
+  const user = await 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/config.ts

@@ -0,0 +1,205 @@
+/* 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;
+  challengeUrl: string;
+  include: string[];
+  exclude: string[];
+  cookies: CookiesConfigObject;
+};
+
+export type AuthConfig = Partial<AuthConfigWithDefaults>;
+
+export type DefinedAuthConfig = AuthConfigWithDefaults;
+
+const isDevelopment = process.env.NODE_ENV === "development";
+
+const defaultServerSecure = isDevelopment ? false : true;
+/**
+ * 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: "/",
+      },
+      [CodeVerifier.APP_URL]: {
+        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,
+    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_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,162 @@
+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);
+  await clearTokens(cookieStorage);
+
+  // clear user
+  const clientStorage = new NextjsClientStorage();
+  const userSession = new GenericUserSession(clientStorage);
+  await userSession.set(null);
+};
+
+type KeySetter = OAuthTokens | CodeVerifier;
+class NextjsCookieStorage extends CookieStorage {
+  constructor(readonly config: Partial<TokensCookieConfig> = {}) {
+    super({
+      secure: true,
+      httpOnly: true,
+    });
+  }
+
+  async get(key: string): Promise<string | null> {
+    const cookieStore = await cookies();
+    return cookieStore.get(key)?.value || null;
+  }
+
+  async set(key: KeySetter, value: string): Promise<void> {
+    const cookieStore = await cookies();
+    const cookieSettings = this.config?.[key as KeySetter] || {
+      ...this.settings,
+    };
+    cookieStore.set(key, value, cookieSettings);
+  }
+}
+
+class NextjsClientStorage extends CookieStorage {
+  constructor(config: Partial<CookieStorageSettings> = {}) {
+    super({
+      ...config,
+      secure: false,
+      httpOnly: false,
+    });
+  }
+
+  async get(key: string): Promise<string | null> {
+    const cookieStore = await cookies();
+    return cookieStore.get(key)?.value || null;
+  }
+
+  async set(key: string, value: string): Promise<void> {
+    const cookieStore = await cookies();
+    cookieStore.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;
+};

package/src/nextjs/index.ts

@@ -0,0 +1,20 @@
+export { createCivicAuthPlugin } from "@/nextjs/config.js";
+export { getUser } from "@/nextjs/GetUser.js";
+export { handler } from "@/nextjs/routeHandler.js";
+export {
+  createTokenCookies,
+  createUserInfoCookie,
+  clearAuthCookies,
+  NextjsCookieStorage,
+  NextjsClientStorage,
+} from "@/nextjs/cookies.js";
+export type {
+  AuthConfig,
+  CookiesConfigObject,
+  AuthConfigWithDefaults,
+  DefinedAuthConfig,
+} from "@/nextjs/config.js";
+export {
+  CivicNextAuthProvider as CivicAuthProvider,
+  type NextCivicAuthProviderProps as AuthProviderProps,
+} from "@/nextjs/providers/NextAuthProvider.js";

package/src/nextjs/middleware/index.ts

@@ -0,0 +1 @@
+export { authMiddleware, auth, withAuth } from "@/nextjs/middleware.js";

package/src/nextjs/middleware.ts

@@ -0,0 +1,155 @@
+/**
+ * Authenticates the user on all requests by checking the token cookie
+ *
+ * Usage:
+ * Option 1: use if no other middleware (e.g. no next-intl etc)
+ * export default authMiddleware();
+ *
+ * Option 2: use if other middleware is needed - default auth config
+ * export default withAuth((request) => {
+ *    console.log('in custom middleware', request.nextUrl.pathname);
+ *    return NextResponse.next();
+ * })
+ *
+ * Option 3: use if other middleware is needed - specifying auth config
+ * const withCivicAuth = auth({ loginUrl: '/login', include: ['/[.*]/user'] })
+ * export default withCivicAuth((request) => {
+ *   console.log('in custom middleware', request.url);
+ *   return NextResponse.next();
+ * })
+ *
+ */
+import type { NextRequest } from "next/server.js";
+import { NextResponse } from "next/server.js";
+import picomatch from "picomatch";
+import type { AuthConfig } from "@/nextjs/config.js";
+import { resolveAuthConfig } from "@/nextjs/config.js";
+
+type Middleware = (
+  request: NextRequest,
+) => Promise<NextResponse> | NextResponse;
+
+// Matches globs:
+// Examples:
+// /user
+// /user/*
+// /user/**/info
+const matchGlob = (pathname: string, globPattern: string) => {
+  const matches = picomatch(globPattern);
+  return matches(pathname);
+};
+
+// Matches globs:
+// Examples:
+// /user
+// /user/*
+// /user/**/info
+const matchesGlobs = (pathname: string, patterns: string[]) =>
+  patterns.some((pattern) => {
+    if (!pattern) return false;
+    console.log("matching", {
+      pattern,
+      pathname,
+      match: matchGlob(pathname, pattern),
+    });
+    return matchGlob(pathname, pattern);
+  });
+
+// internal - used by all exported functions
+const applyAuth = async (
+  authConfig: AuthConfig,
+  request: NextRequest,
+): Promise<NextResponse | undefined> => {
+  const authConfigWithDefaults = resolveAuthConfig(authConfig);
+  // Check for any valid auth token
+  const isAuthenticated = !!request.cookies.get("id_token");
+
+  // skip auth check for redirect to login url
+  if (
+    request.nextUrl.pathname === authConfigWithDefaults.loginUrl &&
+    request.method === "GET"
+  ) {
+    console.log("→ Skipping auth check - this is the login URL");
+    return undefined;
+  }
+
+  if (!matchesGlobs(request.nextUrl.pathname, authConfigWithDefaults.include)) {
+    console.log("→ Skipping auth check - path not in include patterns");
+    return undefined;
+  }
+
+  if (matchesGlobs(request.nextUrl.pathname, authConfigWithDefaults.exclude)) {
+    console.log("→ Skipping auth check - path in exclude patterns");
+    return undefined;
+  }
+
+  // Check for either token type
+  if (!isAuthenticated) {
+    const loginUrl = new URL(authConfigWithDefaults.loginUrl, request.url);
+    console.log("→ No valid token found - redirecting to login", loginUrl);
+    return NextResponse.redirect(loginUrl);
+  }
+
+  console.log("→ Auth check passed");
+  return undefined;
+};
+
+/**
+ *
+ * Use this when auth is the only middleware you need.
+ * Usage:
+ *
+ * export default authMiddleware({ loginUrl = '/login' }); // or just authMiddleware();
+ *
+ */
+export const authMiddleware =
+  (authConfig: Partial<AuthConfig> = {}) =>
+  async (request: NextRequest): Promise<NextResponse> => {
+    const response = await applyAuth(authConfig, request);
+    if (response) return response;
+
+    // NextJS doesn't do middleware chaining yet, so this does not mean
+    // "call the next middleware" - it means "continue to the route handler"
+    return NextResponse.next();
+  };
+
+/**
+ * Usage:
+ *
+ * export default withAuth(async (request) => {
+ *    console.log('my middleware');
+ *    return NextResponse.next();
+ *  })
+ */
+// use this when you have your own middleware to chain
+export function withAuth(
+  middleware: Middleware,
+): (request: NextRequest) => Promise<NextResponse> {
+  return auth()(middleware);
+}
+
+/**
+ * Use this when you want to configure the middleware here (an alternative is to do it in the next.config file)
+ *
+ * Usage:
+ *
+ * const withAuth = auth({ loginUrl = '/login' }); // or just auth();
+ *
+ * export default withAuth(async (request) => {
+ *    console.log('my middleware');
+ *    return NextResponse.next();
+ *  })
+ *
+ */
+export function auth(authConfig: AuthConfig = {}) {
+  return (
+    middleware: Middleware,
+  ): ((request: NextRequest) => Promise<NextResponse>) => {
+    return async (request: NextRequest): Promise<NextResponse> => {
+      const response = await applyAuth(authConfig, request);
+      if (response) return response;
+
+      return middleware(request);
+    };
+  };
+}