zudoku 0.0.0-feat-bundled-types.71f1034 → 0.0.0-feat-openapi-docs-redesign.dab3fc6a

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,44 @@
+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 "firebase": {
+      return config.authentication.authDomain;
+    }
+    case undefined: {
+      return undefined;
+    }
+    default: {
+      throw new Error(`Unsupported authentication type`);
+    }
+  }
+};

package/src/lib/authentication/AuthenticationPlugin.tsx

@@ -1,8 +1,8 @@
 import { LogOutIcon } from "lucide-react";
-import {
-  type CommonPlugin,
-  type NavigationPlugin,
-  type ProfileMenuPlugin,
+import type {
+  CommonPlugin,
+  NavigationPlugin,
+  ProfileMenuPlugin,
 } from "../core/plugins.js";
 import { SignIn } from "./components/SignIn.js";
 import { SignOut } from "./components/SignOut.js";

package/src/lib/authentication/authentication.ts

@@ -1,13 +1,31 @@
+import type { NavigateFunction } from "react-router";
+import type { ZudokuContext } from "../core/ZudokuContext.js";
+
+export type AuthActionContext = { navigate: NavigateFunction };
+export type AuthActionOptions = { redirectTo?: string; replace?: boolean };
+
 export interface AuthenticationPlugin {
-  signUp(options?: { redirectTo?: string }): Promise<void>;
-  signIn(options?: { redirectTo?: string }): Promise<void>;
-  signOut(): Promise<void>;
-  // @deprecated use signRequest instead
-  getAccessToken(): Promise<string>;
+  initialize?(context: ZudokuContext): Promise<void>;
+  setNavigate?(navigate: NavigateFunction): void;
+
+  signUp(
+    { navigate }: AuthActionContext,
+    options?: AuthActionOptions,
+  ): Promise<void>;
+  signIn(
+    { navigate }: AuthActionContext,
+    options?: AuthActionOptions,
+  ): Promise<void>;
+
+  signOut({ navigate }: AuthActionContext): Promise<void>;
+  /**
+   * @deprecated use signRequest instead
+   */
+  getAccessToken?(): Promise<string>;
   onPageLoad?(): void;
   signRequest(request: Request): Promise<Request>;
 }
 
-export interface AuthenticationProviderInitializer<TConfig> {
-  (config: TConfig): AuthenticationPlugin;
-}
+export type AuthenticationProviderInitializer<TConfig> = (
+  config: TConfig,
+) => AuthenticationPlugin;

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

@@ -1,9 +1,9 @@
 import { useSuspenseQuery } from "@tanstack/react-query";
 import { Navigate } from "react-router";
 import { useZudoku } from "zudoku/components";
-import { ZudokuError } from "../../util/invariant.js";
 import { joinUrl } from "../../util/joinUrl.js";
 import { normalizeRedirectUrl } from "../../util/url.js";
+import { OAuthAuthorizationError, type OAuthErrorType } from "../errors.js";
 
 export function CallbackHandler({
   handleCallback,
@@ -15,24 +15,31 @@ export function CallbackHandler({
     retry: false,
     queryKey: ["oauth-callback"],
     queryFn: async () => {
-      try {
-        return joinUrl(
-          normalizeRedirectUrl(
-            await handleCallback(),
-            window.location.origin,
-            options.basePath,
-          ),
+      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,
+          },
         );
-      } 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.",
-        });
       }
+      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,6 +1,6 @@
 import { useEffect } from "react";
-import { Link, useSearchParams } from "react-router";
-import { Button } from "zudoku/ui/Button.js";
+import { useSearchParams } from "react-router";
+import { Spinner } from "zudoku/components";
 import {
   Card,
   CardContent,
@@ -8,16 +8,19 @@ import {
   CardHeader,
   CardTitle,
 } from "zudoku/ui/Card.js";
-import { useZudoku } from "../../components/context/ZudokuContext.js";
+import { useAuth } from "../hook.js";
 
 export const SignIn = () => {
-  const context = useZudoku();
+  const auth = useAuth();
   const [search] = useSearchParams();
+  const redirectTo = search.get("redirect") ?? undefined;
+
   useEffect(() => {
-    void context.authentication?.signIn({
-      redirectTo: search.get("redirect") ?? undefined,
+    void auth.login({
+      redirectTo,
+      replace: true,
     });
-  }, [context.authentication, search]);
+  }, [auth, redirectTo]);
 
   return (
     <div className="flex items-center justify-center mt-8">
@@ -30,16 +33,8 @@ export const SignIn = () => {
           </CardDescription>
         </CardHeader>
         <CardContent>
-          <div className="flex flex-col gap-2 justify-center">
-            <Button
-              onClick={() => context.authentication?.signIn()}
-              variant="default"
-            >
-              Login
-            </Button>
-            <Button variant="link" className="text-muted-foreground" asChild>
-              <Link to="/">Go home</Link>
-            </Button>
+          <div className="flex items-center text-sm font-medium gap-2">
+            <Spinner /> Redirecting...
           </div>
         </CardContent>
       </Card>

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

@@ -1,14 +1,15 @@
 import { useEffect } from "react";
-import { useNavigate } from "react-router";
-import { useZudoku } from "../../components/context/ZudokuContext.js";
+import { useLatest } from "../../util/useLatest.js";
+import { useAuth } from "../hook.js";
 
 export const SignOut = () => {
-  const context = useZudoku();
-  const navigate = useNavigate();
+  const auth = useAuth();
+
+  const logout = useLatest(auth.logout);
 
   useEffect(() => {
-    void context.authentication?.signOut().then(() => navigate("/"));
-  }, []);
+    void logout.current();
+  }, [logout]);
 
   return null;
 };

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

@@ -7,14 +7,14 @@ import {
   CardHeader,
   CardTitle,
 } from "zudoku/ui/Card.js";
-import { useZudoku } from "../../components/context/ZudokuContext.js";
+import { useAuth } from "../hook.js";
 
 export const SignUp = () => {
-  const context = useZudoku();
+  const auth = useAuth();
 
   useEffect(() => {
-    void (context.authentication?.signUp() ?? context.authentication?.signIn());
-  }, [context.authentication]);
+    void auth.signup();
+  }, [auth]);
 
   return (
     <div className="flex items-center justify-center mt-8">
@@ -28,10 +28,7 @@ export const SignUp = () => {
         </CardHeader>
         <CardContent>
           <div className="flex flex-col gap-2 justify-center">
-            <Button
-              onClick={() => context.authentication?.signIn()}
-              variant="default"
-            >
+            <Button onClick={() => auth.signup()} variant="default">
               Register
             </Button>
             <Button variant="link" className="text-muted-foreground" asChild>

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,23 +1,32 @@
+import { useNavigate } from "react-router";
 import { useZudoku } from "../components/context/ZudokuContext.js";
+import type { AuthActionOptions } from "./authentication.js";
 import { useAuthState } from "./state.js";
 
+export type UseAuthReturn = ReturnType<typeof useAuth>;
+
 export const useAuth = () => {
   const { authentication } = useZudoku();
   const authState = useAuthState();
   const isAuthEnabled = typeof authentication !== "undefined";
+  const navigate = useNavigate();
 
   return {
     isAuthEnabled,
     ...authState,
 
-    login: async () => {
+    login: async (options?: AuthActionOptions) => {
       if (!isAuthEnabled) {
         throw new Error("Authentication is not enabled.");
       }
       // TODO: Should handle errors/state
-      await authentication.signIn({
-        redirectTo: window.location.href,
-      });
+      await authentication.signIn(
+        { navigate },
+        {
+          ...options,
+          redirectTo: options?.redirectTo ?? window.location.href,
+        },
+      );
     },
 
     logout: async () => {
@@ -25,19 +34,23 @@ export const useAuth = () => {
         throw new Error("Authentication is not enabled.");
       }
       // TODO: Should handle errors/state
-      await authentication.signOut();
+      await authentication.signOut({ navigate });
 
       // Redirect to home
-      window.location.href = "/";
+      void navigate("/", { replace: true });
     },
 
-    signup: async () => {
+    signup: async (options?: AuthActionOptions) => {
       if (!isAuthEnabled) {
         throw new Error("Authentication is not enabled.");
       }
-      await authentication.signUp({
-        redirectTo: window.location.href,
-      });
+      await authentication.signUp(
+        { navigate },
+        {
+          ...options,
+          redirectTo: options?.redirectTo ?? window.location.href,
+        },
+      );
     },
   };
 };