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

package/src/nextjs/index.ts

@@ -0,0 +1,24 @@
+export {
+  createCivicAuthPlugin,
+  defaultAuthConfig,
+  resolveAuthConfig,
+} 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);
+    };
+  };
+}

package/src/nextjs/providers/NextAuthProvider.tsx

@@ -0,0 +1,89 @@
+"use client";
+/**
+ * A very small context provider for the user object - it takes the user object from the cookie and provides it to the app.
+ */
+import React, { useEffect, useState } from "react";
+import type { AuthProviderProps } from "@/shared/providers/AuthProvider.js";
+import { AuthProvider } from "@/shared/providers/AuthProvider.js";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type { User } from "@/types.js";
+import { resolveAuthConfig } from "@/nextjs/config.js";
+import { resolveCallbackUrl } from "@/nextjs/utils.js";
+import { ConfidentialClientPKCEConsumer } from "@/services/PKCE.js";
+import { NextjsClientStorage } from "@/nextjs/cookies.js";
+import { UserProvider } from "@/shared/providers/UserProvider.js";
+import { OAuthTokens } from "@/shared/lib/types.js";
+import { useUserCookie } from "@/nextjs/hooks/useUserCookie.js";
+import { useTokenCookie } from "@/nextjs/hooks/index.js";
+
+// adding the styles import here to be added to the bundle
+// import "../../styles.css";
+
+const queryClient = new QueryClient();
+
+type NextCivicAuthProviderProps = Omit<AuthProviderProps, "clientId">;
+
+const CivicNextAuthProviderInternal = ({
+  children,
+  ...props
+}: NextCivicAuthProviderProps) => {
+  const [redirectUrl, setRedirectUrl] = useState<string>("");
+  const resolvedConfig = resolveAuthConfig();
+  const { clientId, oauthServer, callbackUrl, challengeUrl, logoutUrl } =
+    resolvedConfig;
+
+  useEffect(() => {
+    if (typeof globalThis.window !== "undefined") {
+      const currentUrl = globalThis.window.location.href;
+      setRedirectUrl(resolveCallbackUrl(resolvedConfig, currentUrl));
+    }
+  }, [callbackUrl, resolvedConfig]);
+
+  const user = useUserCookie();
+  const idToken = useTokenCookie(OAuthTokens.ID_TOKEN);
+  const combinedUser = user ? ({ ...(user || {}), idToken } as User) : null;
+  const sessionData = {
+    authenticated: !!user,
+    ...(idToken ? { idToken } : {}),
+  };
+  const signOut = async (): Promise<void> => {
+    if (props.onSignOut) {
+      await props.onSignOut();
+    }
+    window.location.href = logoutUrl;
+    return;
+  };
+  return (
+    <AuthProvider
+      {...props}
+      redirectUrl={redirectUrl}
+      config={{ oauthServer }}
+      clientId={clientId}
+      pkceConsumer={new ConfidentialClientPKCEConsumer(challengeUrl)}
+      sessionData={sessionData}
+    >
+      <UserProvider
+        storage={new NextjsClientStorage()}
+        user={combinedUser}
+        signOut={signOut}
+      >
+        {children}
+      </UserProvider>
+    </AuthProvider>
+  );
+};
+
+const CivicNextAuthProvider = ({
+  children,
+  ...props
+}: NextCivicAuthProviderProps) => {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <CivicNextAuthProviderInternal {...props}>
+        {children}
+      </CivicNextAuthProviderInternal>
+    </QueryClientProvider>
+  );
+};
+
+export { CivicNextAuthProvider, type NextCivicAuthProviderProps };

package/src/nextjs/routeHandler.ts

@@ -0,0 +1,276 @@
+import type { NextRequest } from "next/server.js";
+import { NextResponse } from "next/server.js";
+import { revalidatePath } from "next/cache.js";
+import type { AuthConfig } from "@/nextjs/config.js";
+import { resolveAuthConfig } from "@/nextjs/config.js";
+import { loggers } from "@/lib/logger.js";
+import {
+  clearAuthCookies,
+  NextjsClientStorage,
+  NextjsCookieStorage,
+} from "@/nextjs/cookies.js";
+import { GenericPublicClientPKCEProducer } from "@/services/PKCE.js";
+import { resolveOAuthAccessCode } from "@/server/login.js";
+import { getUser } from "@/shared/lib/session.js";
+import { resolveCallbackUrl } from "@/nextjs/utils.js";
+import { GenericUserSession } from "@/shared/lib/UserSession.js";
+import {
+  TOKEN_EXCHANGE_SUCCESS_TEXT,
+  TOKEN_EXCHANGE_TRIGGER_TEXT,
+} from "@/constants.js";
+import { serverTokenExchangeFromState } from "@/lib/oauth.js";
+import { cookies } from "next/headers.js";
+import { CodeVerifier } from "@/shared/lib/types.js";
+
+const logger = loggers.nextjs.handlers.auth;
+
+class AuthError extends Error {
+  constructor(
+    message: string,
+    public readonly status: number = 401,
+  ) {
+    super(message);
+    this.name = "AuthError";
+  }
+}
+
+/**
+ * create a code verifier and challenge for PKCE
+ * saving the verifier in a cookie for later use
+ * @returns {Promise<NextResponse>}
+ */
+async function handleChallenge(config: AuthConfig): Promise<NextResponse> {
+  const cookieStorage = new NextjsCookieStorage(config.cookies?.tokens ?? {});
+  const pkceProducer = new GenericPublicClientPKCEProducer(cookieStorage);
+
+  const challenge = await pkceProducer.getCodeChallenge();
+
+  return NextResponse.json({ status: "success", challenge });
+}
+
+async function performTokenExchangeAndSetCookies(
+  request: NextRequest,
+  config: AuthConfig,
+  code: string,
+  state: string,
+) {
+  const resolvedConfigs = resolveAuthConfig(config);
+  const cookieStorage = new NextjsCookieStorage(resolvedConfigs.cookies.tokens);
+
+  const callbackUrl = resolveCallbackUrl(resolvedConfigs, request.url);
+  try {
+    await resolveOAuthAccessCode(code, state, cookieStorage, {
+      ...resolvedConfigs,
+      redirectUrl: callbackUrl,
+    });
+  } catch (error) {
+    logger.error("Token exchange failed:", error);
+    throw new AuthError("Failed to authenticate user", 401);
+  }
+
+  const user = await getUser(cookieStorage);
+  if (!user) {
+    throw new AuthError("Failed to get user info", 401);
+  }
+
+  const clientStorage = new NextjsClientStorage();
+  const userSession = new GenericUserSession(clientStorage);
+  userSession.set(user);
+}
+async function handleCallback(
+  request: NextRequest,
+  config: AuthConfig,
+): Promise<NextResponse> {
+  const resolvedConfigs = resolveAuthConfig(config);
+  console.log("handleCallback", { request, resolvedConfigs });
+  const code = request.nextUrl.searchParams.get("code");
+  const state = request.nextUrl.searchParams.get("state") || "";
+  if (!code || !state) throw new AuthError("Bad parameters", 400);
+
+  // If we have a code_verifier cookie, we can do a token exchange.
+  // Otherwise, just render an empty page.
+  // The initial redirect back from the auth server does not send cookies, because the redirect is from a 3rd-party domain.
+  // The client will make an additional call to this route with cookies included, at which point we do the token exchange.
+  console.log("handleCallback", { code, state, cookies: cookies() });
+  if (!request.cookies.get(CodeVerifier.COOKIE_NAME)) {
+    console.log("handleCallback no code_verifier found", {
+      state,
+      serverTokenExchange: serverTokenExchangeFromState(`${state}`),
+    });
+    let response = new NextResponse(
+      `<html><body><span style="display:none">${TOKEN_EXCHANGE_TRIGGER_TEXT}</span></body></html>`,
+    );
+    // in server-side token exchange mode we need to launch a page that will trigger the token exchange
+    // from the same domain, allowing it access to the code_verifier cookie
+    // we only need to do this in redirect mode, as the iframe already triggers a client-side token exchange
+    // if no code-verifier cookie is found
+    if (state && serverTokenExchangeFromState(state)) {
+      console.log(
+        "handleCallback serverTokenExchangeFromState, launching redirect page...",
+        {
+          requestUrl: request.url,
+          configCallbackUrl: resolvedConfigs.callbackUrl,
+        },
+      );
+      // we need to replace the URL with resolved config in case the server is hosted
+      // behind a reverse proxy or load balancer
+      const requestUrl = new URL(request.url);
+      const fetchUrl = `${resolvedConfigs.callbackUrl}?${requestUrl.searchParams.toString()}&sameDomainServerTokenExchange=true`;
+      response = new NextResponse(
+        `<html>
+            <body>
+                <span style="display:none">
+                    <script>
+                        window.onload = function () {
+                            fetch('${fetchUrl}').then((response) => {
+                                response.json().then((jsonResponse) => {
+                                    console.log('fetch jsonResponse', jsonResponse);
+                                    if (jsonResponse.redirectUrl) {
+                                        console.log('handleCallback serverTokenExchangeFromState, redirecting');
+                                        window.location.href = jsonResponse.redirectUrl;
+                                    }
+                                });
+                            });
+                        };
+                    </script>
+                </span>
+            </body>
+        </html>
+        `,
+      );
+    }
+    response.headers.set("Content-Type", "text/html; charset=utf-8");
+    console.log(
+      `handleCallback no code_verifier found, returning ${TOKEN_EXCHANGE_TRIGGER_TEXT}`,
+    );
+    return response;
+  }
+
+  await performTokenExchangeAndSetCookies(
+    request,
+    resolvedConfigs,
+    code,
+    state,
+  );
+
+  if (request.url.includes("sameDomainServerTokenExchange=true")) {
+    console.log(
+      "handleCallback sameDomainServerTokenExchange = true, returnining redirectUrl",
+      resolvedConfigs.appUrl,
+    );
+    return NextResponse.json({
+      status: "success",
+      redirectUrl: resolvedConfigs.appUrl,
+    });
+  }
+
+  // this is the case where a 'normal' redirect is happening
+  if (serverTokenExchangeFromState(state)) {
+    console.log(
+      "handleCallback serverTokenExchangeFromState, redirect to config.appUrl",
+      resolvedConfigs.appUrl,
+    );
+    if (!resolvedConfigs.appUrl) {
+      throw new Error("appUrl not defined in config. Cannot redirect.");
+    }
+    return NextResponse.redirect(`${resolvedConfigs.appUrl}`);
+  }
+  // return an empty HTML response so the iframe doesn't show any response
+  // in the short moment between the redirect and the parent window
+  // acknowledging the redirect and closing the iframe
+  const response = new NextResponse(
+    `<html><span style="display:none">${TOKEN_EXCHANGE_SUCCESS_TEXT}</span></html>`,
+  );
+  response.headers.set("Content-Type", "text/html; charset=utf-8");
+  return response;
+}
+
+/**
+ * If redirectPath is an absolute path, return it as-is.
+ * Otherwise for relative paths, append it to the current domain.
+ * @param redirectPath
+ * @returns
+ */
+const getAbsoluteRedirectPath = (
+  redirectPath: string,
+  currentBasePath: string,
+) => {
+  // Check if the redirectPath is an absolute URL
+  if (/^(https?:\/\/|www\.).+/i.test(redirectPath)) {
+    return redirectPath; // Return as-is if it's an absolute URL
+  }
+  return new URL(redirectPath, currentBasePath).href;
+};
+
+export async function handleLogout(
+  request: NextRequest,
+  config: AuthConfig,
+): Promise<NextResponse> {
+  const resolvedConfigs = resolveAuthConfig(config);
+  const defaultRedirectPath = resolvedConfigs.loginUrl ?? "/";
+  const redirectTarget =
+    new URL(request.url).searchParams.get("redirect") || defaultRedirectPath;
+  const isAbsoluteRedirect = /^(https?:\/\/|www\.).+/i.test(redirectTarget);
+  const finalRedirectUrl = getAbsoluteRedirectPath(
+    redirectTarget,
+    new URL(resolvedConfigs.appUrl ?? request.url).origin,
+  );
+
+  const response = NextResponse.redirect(finalRedirectUrl);
+
+  clearAuthCookies(config);
+
+  try {
+    revalidatePath(isAbsoluteRedirect ? finalRedirectUrl : redirectTarget);
+  } catch (error) {
+    logger.warn("Failed to revalidate path after logout:", error);
+  }
+
+  return response;
+}
+
+/**
+ * Creates an authentication handler for Next.js API routes
+ *
+ * Usage:
+ * ```ts
+ * // app/api/auth/[...civicauth]/route.ts
+ * import { handler } from '@civic/auth/nextjs'
+ * export const GET = handler({
+ *   // optional config overrides
+ * })
+ * ```
+ */
+export const handler =
+  (authConfig = {}) =>
+  async (request: NextRequest): Promise<NextResponse> => {
+    const config = resolveAuthConfig(authConfig);
+
+    try {
+      const pathname = request.nextUrl.pathname;
+      const pathSegments = pathname.split("/");
+      const lastSegment = pathSegments[pathSegments.length - 1];
+
+      switch (lastSegment) {
+        case "challenge":
+          return await handleChallenge(config);
+        case "callback":
+          return await handleCallback(request, config);
+        case "logout":
+          return await handleLogout(request, config);
+        default:
+          throw new AuthError(`Invalid auth route: ${pathname}`, 404);
+      }
+    } catch (error) {
+      logger.error("Auth handler error:", error);
+
+      const status = error instanceof AuthError ? error.status : 500;
+      const message =
+        error instanceof Error ? error.message : "Authentication failed";
+
+      const response = NextResponse.json({ error: message }, { status });
+
+      clearAuthCookies(config);
+      return response;
+    }
+  };

package/src/nextjs/utils.ts

@@ -0,0 +1,10 @@
+import type { AuthConfigWithDefaults } from "@/nextjs/config.js";
+
+export const resolveCallbackUrl = (
+  config: AuthConfigWithDefaults,
+  alternativeUrl?: string,
+): string => {
+  const baseUrl = config.appUrl ?? alternativeUrl;
+  const callbackUrl = new URL(config?.callbackUrl, baseUrl).toString();
+  return callbackUrl.toString();
+};

package/src/reactjs/components/SignInButton.tsx

@@ -0,0 +1,30 @@
+"use client";
+import React from "react";
+import { cn } from "@/utils.js";
+import type { DisplayMode } from "@/types.js";
+import { useUser } from "@/reactjs/hooks/useUser.js";
+
+const SignInButton = ({
+  displayMode,
+  className,
+}: {
+  displayMode?: DisplayMode;
+  className?: string;
+}) => {
+  const { signIn } = useUser();
+
+  return (
+    <button
+      data-testid="sign-in-button"
+      className={cn(
+        "cac-rounded-full cac-border cac-border-neutral-500 cac-px-3 cac-py-2 cac-transition-colors hover:cac-bg-neutral-200 hover:cac-bg-opacity-50",
+        className,
+      )}
+      onClick={() => signIn(displayMode)}
+    >
+      Sign In
+    </button>
+  );
+};
+
+export { SignInButton };

package/src/reactjs/components/SignOutButton.tsx

@@ -0,0 +1,22 @@
+"use client";
+import React from "react";
+import { cn } from "@/utils.js";
+import { useUser } from "@/reactjs/hooks/useUser.js";
+
+const SignOutButton = ({ className }: { className?: string }) => {
+  const { signOut } = useUser();
+
+  return (
+    <button
+      className={cn(
+        "cac-rounded-full cac-border cac-border-neutral-500 cac-px-3 cac-py-2 cac-transition-colors hover:cac-bg-neutral-200 hover:cac-bg-opacity-50",
+        className,
+      )}
+      onClick={() => signOut()}
+    >
+      Sign Out
+    </button>
+  );
+};
+
+export { SignOutButton };