zudoku 0.0.0-ed94abf → 0.0.0-edf4a635

package/src/lib/auth/issuer.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from "vitest";
+import type { ZudokuConfig } from "../../config/validators/validate.js";
+import { getIssuer } from "./issuer.js";
+
+describe("getIssuer", () => {
+  it("should return clerk frontend API for clerk authentication", async () => {
+    // Using a valid base64 encoded string: "example.example$test" -> "ZXhhbXBsZS5leGFtcGxlJHRlc3Q="
+    const config: ZudokuConfig = {
+      authentication: {
+        type: "clerk",
+        clerkPubKey:
+          "pk_test_dG9sZXJhbnQtaG9ybmV0LTQ2LmNsZXJrLmFjY291bnRzLmRldiQ",
+      },
+    };
+
+    const result = await getIssuer(config);
+    expect(result).toBe("https://tolerant-hornet-46.clerk.accounts.dev");
+  });
+
+  it("should throw error for invalid clerk public key format", async () => {
+    const config: ZudokuConfig = {
+      authentication: {
+        type: "clerk",
+        clerkPubKey: "pk_test_invalid",
+      },
+    };
+
+    await expect(getIssuer(config)).rejects.toThrow(
+      "Clerk public key is invalid",
+    );
+  });
+
+  it("should throw error for clerk key with invalid base64", async () => {
+    const config: ZudokuConfig = {
+      authentication: {
+        type: "clerk",
+        clerkPubKey: "pk_test_invalid_base64",
+      },
+    };
+
+    await expect(getIssuer(config)).rejects.toThrow(
+      "Clerk public key is invalid",
+    );
+  });
+
+  it("should return auth0 issuer URL for auth0 authentication", async () => {
+    const config: ZudokuConfig = {
+      authentication: {
+        type: "auth0",
+        domain: "example.auth0.com",
+        clientId: "test-client-id",
+      },
+    };
+
+    const result = await getIssuer(config);
+    expect(result).toBe("https://example.auth0.com/");
+  });
+
+  it("should return openid issuer for openid authentication", async () => {
+    const config: ZudokuConfig = {
+      authentication: {
+        type: "openid",
+        issuer: "https://example.com/auth",
+        clientId: "test-client-id",
+      },
+    };
+
+    const result = await getIssuer(config);
+    expect(result).toBe("https://example.com/auth");
+  });
+
+  it("should return azureb2c issuer for azureb2c authentication", async () => {
+    const config: ZudokuConfig = {
+      authentication: {
+        type: "azureb2c",
+        tenantName: "example",
+        policyName: "B2C_1_SignUpSignIn",
+        issuer: "https://example.b2clogin.com/example.onmicrosoft.com/v2.0/",
+        clientId: "test-client-id",
+      },
+    };
+    const result = await getIssuer(config);
+    expect(result).toBe(
+      "https://example.b2clogin.com/example.onmicrosoft.com/v2.0/",
+    );
+  });
+
+  it("should return supabase URL for supabase authentication", async () => {
+    const config: ZudokuConfig = {
+      authentication: {
+        type: "supabase",
+        supabaseUrl: "https://project.supabase.co",
+        supabaseKey: "test-anon-key",
+        provider: "github",
+      },
+    };
+
+    const result = await getIssuer(config);
+    expect(result).toBe("https://project.supabase.co");
+  });
+
+  it("should return undefined for no authentication", async () => {
+    const config: ZudokuConfig = {};
+
+    const result = await getIssuer(config);
+    expect(result).toBeUndefined();
+  });
+
+  it("should throw error for unsupported authentication type", async () => {
+    const config = {
+      authentication: {
+        // biome-ignore lint/suspicious/noExplicitAny: Allow any type
+        type: "unsupported" as any,
+      },
+    } as ZudokuConfig;
+
+    await expect(getIssuer(config)).rejects.toThrow(
+      "Unsupported authentication type",
+    );
+  });
+});

package/src/lib/auth/issuer.ts

@@ -0,0 +1,41 @@
+import type { ZudokuConfig } from "../../config/validators/validate.js";
+import invariant from "../util/invariant.js";
+
+export const getIssuer = async (config: ZudokuConfig) => {
+  switch (config.authentication?.type) {
+    case "clerk": {
+      const frontendApiEncoded = config.authentication.clerkPubKey
+        .split("_")
+        .at(-1);
+      invariant(frontendApiEncoded, "Clerk public key is invalid");
+      const frontendApiParts = atob(frontendApiEncoded).split("$");
+
+      if (frontendApiParts.length !== 2) {
+        throw new Error("Clerk public key is invalid");
+      }
+
+      const frontendApi = frontendApiParts.at(0);
+      invariant(frontendApi, "Clerk public key is invalid");
+
+      return `https://${frontendApi}`;
+    }
+    case "auth0": {
+      return `https://${config.authentication.domain}/`;
+    }
+    case "openid": {
+      return config.authentication.issuer;
+    }
+    case "supabase": {
+      return config.authentication.supabaseUrl;
+    }
+    case "azureb2c": {
+      return config.authentication.issuer;
+    }
+    case undefined: {
+      return undefined;
+    }
+    default: {
+      throw new Error(`Unsupported authentication type`);
+    }
+  }
+};

package/src/lib/authentication/AuthenticationPlugin.tsx

@@ -1,5 +1,5 @@
 import { LogOutIcon } from "lucide-react";
-import {
+import type {
   CommonPlugin,
   NavigationPlugin,
   ProfileMenuPlugin,
@@ -10,7 +10,7 @@ import { SignUp } from "./components/SignUp.js";
 
 type PluginInterface = NavigationPlugin & CommonPlugin & ProfileMenuPlugin;
 
-export class AuthenticationPlugin implements PluginInterface {
+export class CoreAuthenticationPlugin implements PluginInterface {
   getRoutes() {
     return [
       {

package/src/lib/authentication/authentication.ts

@@ -1,16 +1,13 @@
-import { ZudokuPlugin } from "../core/plugins.js";
-
-export interface AuthenticationProvider {
-  signUp(options?: { redirectTo?: string }): Promise<void>;
-  signIn(options?: { redirectTo?: string }): Promise<void>;
+export interface AuthenticationPlugin {
+  signUp(options?: { redirectTo?: string; replace?: boolean }): Promise<void>;
+  signIn(options?: { redirectTo?: string; replace?: boolean }): Promise<void>;
   signOut(): Promise<void>;
   // @deprecated use signRequest instead
   getAccessToken(): Promise<string>;
-  getAuthenticationPlugin?(): ZudokuPlugin;
   onPageLoad?(): void;
   signRequest(request: Request): Promise<Request>;
 }
 
-export interface AuthenticationProviderInitializer<TConfig> {
-  (config: TConfig): AuthenticationProvider;
-}
+export type AuthenticationProviderInitializer<TConfig> = (
+  config: TConfig,
+) => AuthenticationPlugin;

package/src/lib/authentication/components/CallbackHandler.tsx

@@ -1,28 +1,45 @@
 import { useSuspenseQuery } from "@tanstack/react-query";
 import { Navigate } from "react-router";
-import { ZudokuError } from "../../util/invariant.js";
+import { useZudoku } from "zudoku/components";
+import { joinUrl } from "../../util/joinUrl.js";
+import { normalizeRedirectUrl } from "../../util/url.js";
+import { OAuthAuthorizationError, type OAuthErrorType } from "../errors.js";
 
 export function CallbackHandler({
   handleCallback,
 }: {
   handleCallback: () => Promise<string>;
 }) {
+  const { options } = useZudoku();
   const executeCallback = useSuspenseQuery({
     retry: false,
     queryKey: ["oauth-callback"],
     queryFn: async () => {
-      try {
-        return await handleCallback();
-      } catch (error) {
-        throw new ZudokuError("Could not validate user", {
-          cause: error,
-          title: "Authentication Error",
-          developerHint:
-            "Check the configuration of your authorization provider and ensure all settings such as the callback URL are configured correctly.",
-        });
+      const url = new URL(window.location.href);
+
+      const errorParam = url.searchParams.get("error");
+      const errorDescription =
+        url.searchParams.get("error_description") ?? undefined;
+      const errorUri = url.searchParams.get("error_uri") ?? undefined;
+      if (errorParam) {
+        throw new OAuthAuthorizationError(
+          `OAuth error '${errorParam}': ${errorDescription}`,
+          {
+            error: errorParam as OAuthErrorType,
+            error_description: errorDescription,
+            error_uri: errorUri,
+          },
+        );
       }
+      return joinUrl(
+        normalizeRedirectUrl(
+          await handleCallback(),
+          window.location.origin,
+          options.basePath,
+        ),
+      );
     },
   });
 
-  return <Navigate to={executeCallback.data} />;
+  return <Navigate to={executeCallback.data} replace />;
 }

package/src/lib/authentication/components/OAuthErrorPage.tsx

@@ -0,0 +1,171 @@
+import { HomeIcon } from "lucide-react";
+import { Link } from "react-router";
+import { Heading } from "../../components/Heading.js";
+import { Typography } from "../../components/Typography.js";
+import { Button } from "../../ui/Button.js";
+import { OAuthAuthorizationError } from "../errors.js";
+import { useAuth } from "../hook.js";
+
+const errorDetailsMap: Record<string, { message: string }> = {
+  invalid_request: {
+    message:
+      "The authentication request was invalid. Please try signing in again.",
+  },
+  unauthorized_client: {
+    message:
+      "This application is not authorized to access your account. Please contact support.",
+  },
+  access_denied: {
+    message:
+      "You denied access to this application. To continue, please sign in and grant access.",
+  },
+  unsupported_response_type: {
+    message:
+      "The authentication method is not supported. Please contact support.",
+  },
+  invalid_scope: {
+    message: "The requested permissions are invalid. Please contact support.",
+  },
+  server_error: {
+    message:
+      "The authentication server encountered an error. Please try again in a few moments.",
+  },
+  temporarily_unavailable: {
+    message:
+      "The authentication service is temporarily unavailable. Please try again in a few moments.",
+  },
+  // Token errors
+  invalid_client: {
+    message: "Invalid application credentials. Please contact support.",
+  },
+  invalid_grant: {
+    message:
+      "The authentication code has expired or is invalid. Please sign in again.",
+  },
+  unsupported_grant_type: {
+    message:
+      "The authentication method is not supported. Please contact support.",
+  },
+  // Custom errors
+  invalid_state: {
+    message:
+      "Security validation failed. This may be due to a potential security attack. Please try signing in again.",
+  },
+  missing_code_verifier: {
+    message:
+      "Authentication security information is missing. Please clear your browser cache and try again.",
+  },
+  network_error: {
+    message:
+      "A network error occurred during authentication. Please check your connection and try again.",
+  },
+  token_expired: {
+    message: "Your authentication session has expired. Please sign in again.",
+  },
+  configuration_error: {
+    message:
+      "There is an issue with the authentication configuration. Please contact support.",
+  },
+  unknown_error: {
+    message:
+      "An unexpected error occurred during authentication. Please try again or contact support.",
+  },
+};
+
+export function OAuthErrorPage({ error }: { error: unknown }) {
+  const { login } = useAuth();
+
+  if (!(error instanceof OAuthAuthorizationError)) {
+    throw error;
+  }
+
+  const oauthError = error.error;
+  const type = oauthError.error;
+
+  const details = errorDetailsMap[type] ?? errorDetailsMap.unknown_error;
+
+  return (
+    <div className="min-h-[400px] flex items-center justify-center p-4">
+      <div className="max-w-md w-full text-center space-y-6">
+        <div className="space-y-4 items-center">
+          <Heading level={2} className="text-2xl inline-block font-bold">
+            {titles[type] || "Authentication Error"}
+          </Heading>
+
+          <Typography className="text-gray-600 dark:text-gray-300 leading-relaxed">
+            {details?.message}
+          </Typography>
+
+          {/* Technical details for developers (only in development) */}
+        </div>
+
+        {/* Action Buttons */}
+        <div className="space-y-3 pt-4">
+          <div className="space-y-2">
+            {(type === "access_denied" ||
+              type === "invalid_grant" ||
+              type === "token_expired") && (
+              <Button
+                onClick={login}
+                className="w-full capitalize"
+                variant={"default"}
+              >
+                Sign in again
+              </Button>
+            )}
+          </div>
+
+          <div className="flex gap-2">
+            <Button asChild className="flex-1" variant="outline">
+              <Link to="/">
+                <HomeIcon className="w-4 h-4 mr-2" />
+                Go Home
+              </Link>
+            </Button>
+          </div>
+        </div>
+
+        {/* Additional Help */}
+        {helpMessages[type] && (
+          <Typography className="text-sm text-gray-500 dark:text-gray-400">
+            {helpMessages[type]}
+          </Typography>
+        )}
+      </div>
+    </div>
+  );
+}
+
+const titles: Record<string, string> = {
+  access_denied: "Access Denied",
+  invalid_request: "Invalid Request",
+  unauthorized_client: "Unauthorized Application",
+  unsupported_response_type: "Unsupported Method",
+  invalid_scope: "Invalid Permissions",
+  server_error: "Server Error",
+  temporarily_unavailable: "Service Unavailable",
+  invalid_client: "Invalid Credentials",
+  invalid_grant: "Authentication Expired",
+  unsupported_grant_type: "Unsupported Authentication",
+  invalid_state: "Security Check Failed",
+  missing_code_verifier: "Security Information Missing",
+  network_error: "Network Error",
+  token_expired: "Session Expired",
+  configuration_error: "Configuration Error",
+  unknown_error: "Authentication Failed",
+};
+
+const helpMessages: Record<string, string> = {
+  access_denied:
+    "If you changed your mind, you can try signing in again to grant access.",
+  invalid_state:
+    "This error can occur if you have multiple tabs open or if your session was compromised.",
+  missing_code_verifier:
+    "Try clearing your browser's cache and cookies for this site.",
+  network_error:
+    "Check your internet connection and ensure you can access other websites.",
+  server_error:
+    "The issue is on our end. Our team has been notified and is working to fix it.",
+  temporarily_unavailable:
+    "This is usually temporary. Try again in a few minutes.",
+};

package/src/lib/authentication/components/SignIn.tsx

@@ -1,5 +1,13 @@
 import { useEffect } from "react";
 import { useSearchParams } from "react-router";
+import { Spinner } from "zudoku/components";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "zudoku/ui/Card.js";
 import { useZudoku } from "../../components/context/ZudokuContext.js";
 
 export const SignIn = () => {
@@ -8,8 +16,26 @@ export const SignIn = () => {
   useEffect(() => {
     void context.authentication?.signIn({
       redirectTo: search.get("redirect") ?? undefined,
+      replace: true,
     });
   }, [context.authentication, search]);
 
-  return null;
+  return (
+    <div className="flex items-center justify-center mt-8">
+      <Card className="max-w-md w-full">
+        <CardHeader>
+          <CardTitle className="text-lg">Sign in</CardTitle>
+          <CardDescription>
+            You're being redirected to our secure login provider to complete
+            your sign-in process.
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          <div className="flex items-center text-sm font-medium gap-2">
+            <Spinner /> Redirecting...
+          </div>
+        </CardContent>
+      </Card>
+    </div>
+  );
 };

package/src/lib/authentication/components/SignOut.tsx

@@ -8,7 +8,7 @@ export const SignOut = () => {
 
   useEffect(() => {
     void context.authentication?.signOut().then(() => navigate("/"));
-  }, []);
+  }, [context.authentication, navigate]);
 
   return null;
 };

package/src/lib/authentication/components/SignUp.tsx

@@ -1,11 +1,45 @@
 import { useEffect } from "react";
+import { Button, Link } from "zudoku/components";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "zudoku/ui/Card.js";
 import { useZudoku } from "../../components/context/ZudokuContext.js";
 
 export const SignUp = () => {
   const context = useZudoku();
+
   useEffect(() => {
     void (context.authentication?.signUp() ?? context.authentication?.signIn());
   }, [context.authentication]);
 
-  return null;
+  return (
+    <div className="flex items-center justify-center mt-8">
+      <Card className="max-w-md w-full">
+        <CardHeader>
+          <CardTitle className="text-lg">Sign up</CardTitle>
+          <CardDescription>
+            You're being redirected to our secure login provider to complete
+            your sign up process.
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          <div className="flex flex-col gap-2 justify-center">
+            <Button
+              onClick={() => context.authentication?.signIn()}
+              variant="default"
+            >
+              Register
+            </Button>
+            <Button variant="link" className="text-muted-foreground" asChild>
+              <Link to="/">Go home</Link>
+            </Button>
+          </div>
+        </CardContent>
+      </Card>
+    </div>
+  );
 };

package/src/lib/authentication/errors.ts

@@ -1,21 +1,35 @@
-export class AuthorizationError extends Error {}
+import type { OAuth2Error } from "oauth4webapi";
+import { ZudokuError, type ZudokuErrorOptions } from "../util/invariant.js";
 
-interface OAuthError {
-  readonly error: string;
-  readonly error_description?: string;
-  readonly error_uri?: string;
-  readonly algs?: string;
-  readonly scope?: string;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  readonly [parameter: string]: any | undefined;
-}
+export class AuthorizationError extends Error {}
 
-export class OAuthAuthorizationError extends AuthorizationError {
+export class OAuthAuthorizationError extends ZudokuError {
   constructor(
     message: string,
-    public error: OAuthError,
-    options?: ErrorOptions,
+    public error: OAuth2Error,
+    options?: ZudokuErrorOptions,
   ) {
     super(message, options);
   }
 }
+
+export type OAuthErrorType =
+  // Authorization errors
+  | "invalid_request"
+  | "unauthorized_client"
+  | "access_denied"
+  | "unsupported_response_type"
+  | "invalid_scope"
+  | "server_error"
+  | "temporarily_unavailable"
+  // Token errors
+  | "invalid_client"
+  | "invalid_grant"
+  | "unsupported_grant_type"
+  // Custom errors
+  | "invalid_state"
+  | "missing_code_verifier"
+  | "network_error"
+  | "token_expired"
+  | "configuration_error"
+  | "unknown_error";

package/src/lib/authentication/hook.ts

@@ -1,6 +1,8 @@
 import { useZudoku } from "../components/context/ZudokuContext.js";
 import { useAuthState } from "./state.js";
 
+export type UseAuthReturn = ReturnType<typeof useAuth>;
+
 export const useAuth = () => {
   const { authentication } = useZudoku();
   const authState = useAuthState();

package/src/lib/authentication/providers/auth0.tsx

@@ -1,14 +1,20 @@
-import { type Auth0AuthenticationConfig } from "../../../config/config.js";
-import { type AuthenticationProviderInitializer } from "../authentication.js";
+import type { Auth0AuthenticationConfig } from "../../../config/config.js";
+import type {
+  AuthenticationPlugin,
+  AuthenticationProviderInitializer,
+} from "../authentication.js";
 import { useAuthState } from "../state.js";
 import { OpenIDAuthenticationProvider } from "./openid.js";
 
-class Auth0AuthenticationProvider extends OpenIDAuthenticationProvider {
+class Auth0AuthenticationProvider
+  extends OpenIDAuthenticationProvider
+  implements AuthenticationPlugin
+{
   constructor(config: Auth0AuthenticationConfig) {
     super({
       ...config,
       type: "openid",
-      issuer: `https://${config.domain}`,
+      issuer: `https://${config.domain}/`,
       clientId: config.clientId,
       audience: config.audience,
       scopes: config.scopes,
@@ -37,7 +43,7 @@ class Auth0AuthenticationProvider extends OpenIDAuthenticationProvider {
     });
 
     const redirectUrl = new URL(window.location.origin);
-    redirectUrl.pathname = this.logoutRedirectUrlPath;
+    redirectUrl.pathname = this.redirectToAfterSignOut;
 
     // SEE: https://auth0.com/docs/authenticate/login/logout/log-users-out-of-auth0
     // For Auth0 tenants created on or after 14 November 2023, RP-Initiated
@@ -58,7 +64,7 @@ class Auth0AuthenticationProvider extends OpenIDAuthenticationProvider {
 
       // window.location.href = logoutUrl.toString();
     } else {
-      const logoutUrl = new URL(
+      const _logoutUrl = new URL(
         `${this.issuer.replace(/\/$/, "")}/oidc/logout`,
       );
       // window.location.href = logoutUrl.toString();