zudoku 0.0.0-eeace45 → 0.0.0-efc60ba6

package/src/app/main.tsx

@@ -1,4 +1,4 @@
-import { type RouteObject } from "react-router";
+import type { RouteObject } from "react-router";
 import { configuredApiKeysPlugin } from "virtual:zudoku-api-keys-plugin";
 import {
   configuredApiCatalogPlugins,
@@ -6,102 +6,117 @@ import {
 } from "virtual:zudoku-api-plugins";
 import { configuredAuthProvider } from "virtual:zudoku-auth";
 import { configuredCustomPagesPlugin } from "virtual:zudoku-custom-pages-plugin";
-import { configuredDocsPlugins } from "virtual:zudoku-docs-plugins";
+import { configuredDocsPlugin } from "virtual:zudoku-docs-plugin";
+import { configuredNavigation } from "virtual:zudoku-navigation";
 import { configuredRedirectPlugin } from "virtual:zudoku-redirect-plugin";
 import { configuredSearchPlugin } from "virtual:zudoku-search-plugin";
-import { configuredSidebar } from "virtual:zudoku-sidebar";
+import { registerShiki } from "virtual:zudoku-shiki-register";
 import "virtual:zudoku-theme.css";
-import { Layout, RouterError, Zudoku } from "zudoku/components";
+import {
+  BuildCheck,
+  Layout,
+  RouteGuard,
+  RouterError,
+  StatusPage,
+  Zudoku,
+} from "zudoku/components";
 import type { ZudokuConfig } from "../config/config.js";
 import type { ZudokuContextOptions } from "../lib/core/ZudokuContext.js";
 import { isNavigationPlugin } from "../lib/core/plugins.js";
+import { highlighter } from "../lib/shiki.js";
+import { ZuploEnv } from "./env.js";
+import "./main.css";
+
+await registerShiki(highlighter);
 
 export const convertZudokuConfigToOptions = (
   config: ZudokuConfig,
 ): ZudokuContextOptions => {
-  const fallbackLogoLight =
-    config.page?.logoUrl ??
-    "https://cdn.zudoku.dev/logos/zudoku-logo-full-light.svg";
-  const fallbackLogoDark =
-    config.page?.logoUrl ??
-    "https://cdn.zudoku.dev/logos/zudoku-logo-full-dark.svg";
-
-  const isUsingFallback =
-    !config.page?.logoUrl &&
-    !config.page?.logo?.src?.light &&
-    !config.page?.logo?.src?.dark;
-
   return {
-    page: {
-      ...config.page,
-      logo: {
-        ...(isUsingFallback ? { width: "130px" } : {}),
-        ...config.page?.logo,
-        src: {
-          light: config.page?.logo?.src?.light ?? fallbackLogoLight,
-          dark: config.page?.logo?.src?.dark ?? fallbackLogoDark,
-        },
-      },
+    basePath: config.basePath,
+    canonicalUrlOrigin: config.canonicalUrlOrigin,
+    protectedRoutes: config.protectedRoutes,
+    site: {
+      ...config.site,
+      showPoweredBy:
+        ZuploEnv.buildConfig?.entitlements.devPortalZuploBranding ??
+        config.site?.showPoweredBy,
+      logo: config.site?.logo,
     },
-    slotlets: config.UNSAFE_slotlets,
+    slots: config.slots,
     metadata: {
       favicon: "https://cdn.zudoku.dev/logos/favicon.svg",
       title: "%s - Zudoku",
       ...config.metadata,
     },
-    sidebars: configuredSidebar,
-    topNavigation: config.topNavigation,
+    navigation: configuredNavigation,
     mdx: config.mdx,
-    authentication: configuredAuthProvider,
     plugins: [
-      ...configuredDocsPlugins,
+      ...(configuredAuthProvider ? [configuredAuthProvider] : []),
+      ...(configuredDocsPlugin ? [configuredDocsPlugin] : []),
       ...configuredApiPlugins,
       ...(configuredSearchPlugin ? [configuredSearchPlugin] : []),
       ...(configuredRedirectPlugin ? [configuredRedirectPlugin] : []),
       ...(configuredApiKeysPlugin ? [configuredApiKeysPlugin] : []),
       ...(configuredCustomPagesPlugin ? [configuredCustomPagesPlugin] : []),
       ...configuredApiCatalogPlugins,
-      ...(configuredAuthProvider?.getAuthenticationPlugin
-        ? [configuredAuthProvider.getAuthenticationPlugin()]
-        : []),
       ...(config.plugins ?? []),
     ],
+    syntaxHighlighting: {
+      highlighter,
+      themes: config.syntaxHighlighting?.themes,
+    },
   };
 };
 
-export const getRoutesByOptions = (options: ZudokuContextOptions) => {
+export const getRoutesByOptions = (
+  options: ZudokuContextOptions,
+  enableStatusPages = true,
+) => {
   const allPlugins = [
-    ...(options.plugins ? options.plugins : []),
-    ...(options.authentication?.getAuthenticationPlugin
-      ? [options.authentication.getAuthenticationPlugin()]
-      : []),
+    ...(options.plugins ?? []),
+    ...(options.authentication ? [options.authentication] : []),
   ];
 
   const routes = allPlugins
     .flatMap((plugin) => (isNavigationPlugin(plugin) ? plugin.getRoutes() : []))
-    .concat({
-      path: "*",
-      loader: () => {
-        throw new Response("Not Found", { status: 404 });
-      },
-    });
+    .concat(
+      enableStatusPages
+        ? [400, 404, 500].map((statusCode) => ({
+            path: `/${statusCode}`,
+            element: <StatusPage statusCode={statusCode} />,
+          }))
+        : [],
+    )
+    .concat([{ path: "*", element: <StatusPage statusCode={404} /> }]);
+
+  // @TODO Detect conflicts in routes and log warning
 
   return routes;
 };
 
 export const getRoutesByConfig = (config: ZudokuConfig): RouteObject[] => {
   const options = convertZudokuConfigToOptions(config);
-  const routes = getRoutesByOptions(options);
+  const routes = getRoutesByOptions(
+    options,
+    import.meta.env.IS_ZUPLO || config.enableStatusPages,
+  );
 
   return [
     {
       element: (
         <Zudoku {...options}>
+          <BuildCheck
+            buildId={import.meta.env.ZUPLO_BUILD_ID}
+            environmentType={import.meta.env.ZUPLO_ENVIRONMENT_TYPE}
+          />
           <Layout />
         </Zudoku>
       ),
+      hydrateFallbackElement: <div>Loading...</div>,
       children: [
         {
+          element: <RouteGuard />,
           errorElement: <RouterError />,
           children: routes,
         },

package/src/app/standalone.tsx

@@ -13,14 +13,14 @@ if (!root) {
 }
 
 const apiUrl = root.getAttribute("data-api-url");
-const pageTitle = document.getElementsByTagName("title")[0]!.innerText;
+const title = document.getElementsByTagName("title")[0]!.innerText;
 const logoUrl = root.getAttribute("data-logo-url");
 
 // IMPORTANT: This component must not contain tailwind classes
 // This directory is not processed by the tailwind plugin
 
 const config = {
-  page: {
+  site: {
     logo: logoUrl
       ? {
           src: {
@@ -29,12 +29,13 @@ const config = {
           },
         }
       : undefined,
-    pageTitle,
+    title,
   },
-  topNavigation: [
+  navigation: [
     {
-      id: "/",
+      type: "link",
       label: "API Reference",
+      to: "/",
     },
   ],
   plugins: [
@@ -42,8 +43,7 @@ const config = {
     openApiPlugin({
       type: "url",
       input: apiUrl!,
-      navigationId: "/",
-      inMemory: true,
+      path: "/",
     }),
   ],
 } satisfies ZudokuConfig;

package/src/lib/MissingIcon.tsx

@@ -0,0 +1,22 @@
+import { CircleDashed, LucideProps } from "lucide-react";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "./ui/Tooltip.js";
+
+export const MissingIcon = (props: LucideProps) => {
+  return (
+    <TooltipProvider>
+      <Tooltip>
+        <TooltipTrigger className="text-red-500">
+          <CircleDashed {...props} />
+        </TooltipTrigger>
+        <TooltipContent>
+          Icon not found, see: https://lucide.dev/icons/
+        </TooltipContent>
+      </Tooltip>
+    </TooltipProvider>
+  );
+};

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

@@ -0,0 +1,120 @@
+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: {
+        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,8 +1,8 @@
 import { LogOutIcon } from "lucide-react";
 import {
-  CommonPlugin,
-  NavigationPlugin,
-  ProfileMenuPlugin,
+  type CommonPlugin,
+  type NavigationPlugin,
+  type ProfileMenuPlugin,
 } from "../core/plugins.js";
 import { SignIn } from "./components/SignIn.js";
 import { SignOut } from "./components/SignOut.js";
@@ -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,14 +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;
+  (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: any }) {
+  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.",
+};