zuplo 6.67.32 → 6.68.0

package/docs/dev-portal/zudoku/configuration/authentication-supabase.md

@@ -0,0 +1,225 @@
+---
+title: Supabase Setup
+sidebar_label: Supabase
+description:
+  Learn how to set up Supabase authentication for Zudoku, leveraging Supabase's built-in auth
+  providers for secure documentation access.
+---
+
+Supabase is an open-source Firebase alternative that provides authentication, database, and storage
+services. This guide shows you how to integrate Supabase authentication with your Dev Portal documentation site.
+
+## Prerequisites
+
+You'll need a Supabase project. If you don't have one,
+[create a free Supabase project](https://supabase.com/dashboard) to get started.
+
+## Setup Steps
+
+<Stepper>
+
+1. **Configure Authentication Provider**
+
+   In your [Supabase Dashboard](https://supabase.com/dashboard):
+   - Navigate to **Authentication** → **Providers**
+   - Enable your preferred authentication provider (GitHub, Google, Azure, etc.)
+   - Configure the provider settings:
+     - **Redirect URL**: `https://your-project.supabase.co/auth/v1/callback`
+     - Copy any required credentials (Client ID, Client Secret) from the provider
+
+2. **Get Your Project Credentials**
+
+   From your Supabase project dashboard:
+   - Go to **Settings** → **Data API**
+   - Copy your **Project URL** (looks like `https://your-project.supabase.co`)
+   - Go to **Settings** → **API Keys**
+   - Copy your **anon public** API key
+
+3. **Configure Zudoku**
+
+   Add the Supabase configuration to your [Dev Portal configuration file](./overview.md):
+
+   ```ts title="zudoku.config.ts"
+   export default {
+     // ... other configuration
+     authentication: {
+       type: "supabase",
+       providers: ["github"], // one or more providers
+       supabaseUrl: "https://your-project.supabase.co",
+       supabaseKey: "<your-anon-public-key>",
+     },
+     // ... other configuration
+   };
+   ```
+
+   You can configure multiple providers:
+
+   ```ts title="zudoku.config.ts"
+   export default {
+     // ... other configuration
+     authentication: {
+       type: "supabase",
+       providers: ["github", "google", "azure"],
+       supabaseUrl: "https://your-project.supabase.co",
+       supabaseKey: "<your-anon-public-key>",
+     },
+     // ... other configuration
+   };
+   ```
+
+4. **Install Supabase Dependencies**
+
+   Add `@supabase/supabase-js` to your project dependencies:
+
+   ```bash
+   npm install @supabase/supabase-js @supabase/auth-ui-shared @supabase/auth-ui-react
+   ```
+
+</Stepper>
+
+## Supported Providers
+
+Supabase supports numerous authentication providers. Use any of these values in the `providers`
+array:
+
+- `apple` - Sign in with Apple
+- `azure` - Microsoft Azure AD
+- `bitbucket` - Bitbucket
+- `discord` - Discord
+- `facebook` - Facebook
+- `figma` - Figma
+- `github` - GitHub
+- `gitlab` - GitLab
+- `google` - Google
+- `kakao` - Kakao
+- `keycloak` - Keycloak
+- `linkedin` / `linkedin_oidc` - LinkedIn
+- `notion` - Notion
+- `slack` / `slack_oidc` - Slack
+- `spotify` - Spotify
+- `twitch` - Twitch
+- `twitter` - Twitter/X
+- `workos` - WorkOS
+- `zoom` - Zoom
+- `fly` - Fly.io
+
+:::info
+
+Email/password authentication does not need to be specified as a provider because it is enabled by
+default in Supabase. To disable email/password authentication and only use OAuth providers, set
+`onlyThirdPartyProviders: true` in your configuration.
+
+:::
+
+## Configuration Options
+
+All available configuration options for Supabase authentication:
+
+```ts title="zudoku.config.ts"
+authentication: {
+  type: "supabase",
+
+  // Provider configuration (required)
+  // Array of one or more OAuth providers to enable
+  providers: ["google", "github"],
+
+  // Supabase credentials (required)
+  supabaseUrl: "https://your-project.supabase.co",
+  supabaseKey: "<your-anon-public-key>",
+
+  // Optional: Custom base path for auth routes (default: "/")
+  basePath: "/docs",
+
+  // Optional: Disable email/password authentication, only use OAuth providers
+  onlyThirdPartyProviders: true,
+
+  // Optional: Redirect URLs after authentication events
+  redirectToAfterSignUp: "/welcome",
+  redirectToAfterSignIn: "/dashboard",
+  redirectToAfterSignOut: "/",
+}
+```
+
+### Authentication Routes
+
+The Supabase authentication provider automatically creates the following routes:
+
+- `/signin` - Sign in page with configured providers
+- `/signup` - Sign up page with configured providers
+- `/signout` - Sign out endpoint
+
+If you configure a custom `basePath`, these routes will be prefixed with that path (e.g.,
+`/docs/signin`).
+
+## Advanced Configuration
+
+### User Profile Data
+
+Dev Portal automatically extracts the following user information from Supabase authentication:
+
+- `sub` - User ID from Supabase
+- `email` - User's email address
+- `name` - User's full name (from `user_metadata.full_name` or `user_metadata.name`)
+- `emailVerified` - Whether the email has been confirmed
+- `pictureUrl` - User's avatar URL (from `user_metadata.avatar_url`)
+
+### Additional User Metadata
+
+To store and access additional user information beyond what's provided by Supabase authentication:
+
+1. Create a `profiles` table in your Supabase database
+2. Set up a database trigger to create profile records on user signup
+3. Use the Supabase client to query this data in your application
+
+Example profile table structure:
+
+```sql
+CREATE TABLE profiles (
+  id UUID REFERENCES auth.users ON DELETE CASCADE,
+  username TEXT UNIQUE,
+  bio TEXT,
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  PRIMARY KEY (id)
+);
+
+-- Create trigger to automatically create profile on user signup
+CREATE OR REPLACE FUNCTION public.handle_new_user()
+RETURNS TRIGGER AS $$
+BEGIN
+  INSERT INTO public.profiles (id)
+  VALUES (new.id);
+  RETURN new;
+END;
+$$ LANGUAGE plpgsql SECURITY DEFINER;
+
+CREATE TRIGGER on_auth_user_created
+  AFTER INSERT ON auth.users
+  FOR EACH ROW EXECUTE PROCEDURE public.handle_new_user();
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"At least one provider must be provided" Error**: You must configure the `providers` option in
+   your authentication configuration with at least one authentication provider in the array.
+
+2. **Invalid API Key**: Ensure you're using the `anon public` key, not the `service_role` key from
+   your Supabase project settings.
+
+3. **Provider Not Working**: Verify the provider is enabled in your Supabase dashboard and properly
+   configured with the correct redirect URLs.
+
+4. **Redirect URLs**: For local development, update your redirect URLs in both Supabase and the
+   OAuth provider to include `http://localhost:3000`.
+
+5. **CORS Errors**: Check that your site's domain is properly configured in Supabase's allowed URLs
+   under **Authentication** → **URL Configuration**.
+
+6. **Authentication Not Working**: Make sure you have installed all required dependencies:
+   `@supabase/supabase-js`, `@supabase/auth-ui-react`, and `@supabase/auth-ui-shared`.
+
+## Next Steps
+
+- Explore [Supabase Auth documentation](https://supabase.com/docs/guides/auth) for advanced features
+- Learn about [protecting routes](./authentication.md#protected-routes) in your documentation

package/docs/dev-portal/zudoku/configuration/authentication.md

@@ -0,0 +1,199 @@
+---
+title: Overview
+sidebar_icon: shield-check
+---
+
+If you use a managed authentication service, such as Auth0, Clerk, or OpenID, you can implement this
+into your site and allow users to browse and interact with your documentation and API reference in a
+logged in state.
+
+## Configuration
+
+To implement the authentication option for your site, add the `authentication` property to the
+[Dev Portal Configuration](./overview.md) file. The configuration is slightly different depending on the
+authentication provider you use.
+
+## Authentication Providers
+
+Dev Portal supports Clerk, Auth0, Supabase, Azure B2C, and any OpenID provider that supports the OpenID
+Connect protocol.
+
+Not seeing your authentication provider? [Let us know](https://github.com/zuplo/zudoku/issues)
+
+### Auth0
+
+For Auth0, you will need the `clientId` associated with the domain you are using.
+
+You can find this in the Auth0 dashboard under
+[Application Settings](https://auth0.com/docs/get-started/applications/application-settings).
+
+```typescript
+{
+  // ...
+  authentication: {
+    type: "auth0",
+    domain: "yourdomain.us.auth0.com",
+    clientId: "<your-auth0-clientId>",
+    scopes: ["openid", "profile", "email", "custom_scope"],
+  },
+  // ...
+}
+```
+
+To setup Auth0, create a Single Page Application (SPA) application in the Auth0 dashboard. Set the
+following options:
+
+- Callback URL to `https://your-site.com/oauth/callback`.
+- For development environments only, we recommend configuring your app to allow the a wildcard
+  callback like `https://*.zuplo.app/oauth/callback` to allow for testing each environment.
+- For local development, set the callback url to `http://localhost:3000/oauth/callback`.
+- Add your site hostname (your-site.com) to the list of allowed CORS origins.
+
+### Clerk
+
+For Clerk you will need the publishable key for your application. You can find this in the Clerk
+dashboard on the [API Keys](https://dashboard.clerk.com/last-active?path=api-keys) page.
+
+```typescript
+{
+  // ...
+  authentication: {
+    type: "clerk",
+    clerkPubKey: "<your-clerk-publishable-key>",
+    // Optional. See: https://clerk.com/docs/backend-requests/jwt-templates
+    jwtTemplateName: "dev-portal",
+  },
+  // ...
+}
+```
+
+### OpenID
+
+For authentication services that support OpenID, you will need to supply an `clientId` and `issuer`.
+
+```typescript
+{
+  // ...
+  authentication: {
+    type: "openid",
+    clientId: "<your-client-id>",
+    issuer: "<the-issuer-url>",
+    scopes: ["openid", "profile", "email", "custom_scope"] // Optional custom scopes
+  },
+  // ...
+}
+```
+
+When configuring your OpenID provider, you will need to set the following:
+
+- Callback or Redirect URI to `https://your-site.com/oauth/callback`.
+- If your provider supports wildcard callback urls, we recommend configuring your development
+  identity provider to allow a wildcard callback like `https://*.zuplo.site/oauth/callback` to allow
+  for testing each environment.
+- For local development set the callback url to `http://localhost:3000/oauth/callback`.
+- Add your site hostname (your-site.com) to the list of allowed CORS origins.
+
+By default, the scopes "openid", "profile", and "email" are requested. You can customize these by
+providing your own array of scopes.
+
+### Supabase
+
+To use Supabase as your authentication provider, supply your project's URL, API key, and the OAuth
+provider to use.
+
+```typescript title="zudoku.config.ts"
+{
+  // ...
+  authentication: {
+    type: "supabase",
+    provider: "github",
+    supabaseUrl: "https://your-project.supabase.co",
+    supabaseKey: "<your-supabase-key>",
+    redirectToAfterSignUp: "/",
+    redirectToAfterSignIn: "/",
+    redirectToAfterSignOut: "/",
+  },
+  // ...
+}
+```
+
+The `provider` option can be any of Supabase Auth's supported providers, such as `apple`, `azure`,
+`bitbucket`, `discord`, `facebook`, `figma`, `github`, `gitlab`, `google`, `kakao`, `keycloak`,
+`linkedin`, `linkedin_oidc`, `notion`, `slack`, `slack_oidc`, `spotify`, `twitch`, `twitter`,
+`workos`, `zoom`, or `fly`.
+
+### Azure B2C
+
+For Azure B2C authentication, you will need to provide your Azure B2C tenant name, client ID, and
+policy name.
+
+```typescript title="zudoku.config.ts"
+{
+  // ...
+  authentication: {
+    type: "azureb2c",
+    clientId: "<your-azure-b2c-client-id>",
+    tenantName: "<your-tenant-name>",
+    policyName: "<your-policy-name>",
+    issuer: "<your-issuer-url>",
+    scopes: ["openid", "profile", "email", "custom_scope"]
+  },
+  // ...
+}
+```
+
+When configuring your Azure B2C application, you will need to set the following:
+
+- Redirect URI to `https://your-site.com/oauth/callback`
+- For local development, set the redirect URI to `http://localhost:3000/oauth/callback`
+- Add your site hostname (your-site.com) to the list of allowed CORS origins
+- Configure the appropriate user flows (policies) in your Azure B2C tenant
+
+By default, the scopes "openid", "profile", and "email" are requested. You can customize these by
+providing your own array of scopes.
+
+## User Data
+
+After the user authenticates, the user profile is loaded via the provider's
+[User Info endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo). The following
+fields are used to display the user profile:
+
+- `name` - The user's full name
+- `email` - The user's email address
+- `picture` - The user's profile picture URL
+- `email_verified` - Whether the user's email address has been verified
+
+If the provider does not return a field, it will be left blank.
+
+## Protected Routes
+
+Once authentication is configured, you can protect specific routes in your documentation to require
+users to be authenticated or meet custom authorization requirements. Routes can be protected with a
+simple array of patterns, or with custom callback functions that support reason codes for
+distinguishing between unauthorized and forbidden access.
+
+```typescript title="zudoku.config.ts"
+{
+  // ...
+  // Simple array format: requires authentication
+  protectedRoutes: [
+    "/admin/*",
+    "/settings",
+    "/api/*",
+  ],
+
+  // Or object format: custom authorization with reason codes
+  protectedRoutes: {
+    "/admin/*": ({ auth, reasonCode }) =>
+      !auth.isAuthenticated
+        ? reasonCode.UNAUTHORIZED
+        : auth.profile?.email?.endsWith("@example.com")
+          ? true
+          : reasonCode.FORBIDDEN,
+  },
+  // ...
+}
+```
+
+See the [Protected Routes](./protected-routes.md) documentation for detailed information on
+configuring route protection, reason codes, and navigation behavior.

package/docs/dev-portal/zudoku/configuration/build-configuration.mdx

@@ -0,0 +1,147 @@
+---
+sidebar_icon: pickaxe
+---
+
+# Build Configuration
+
+The `zudoku.build.ts` file allows you to configure build-time settings and processors for your
+Dev Portal project. This file is executed during the build process and can be used to transform your API
+schemas before they are used in the documentation.
+
+:::tip{title="Security Note"}
+
+Unlike `zudoku.config.ts` which runs in both client and server environments, `zudoku.build.ts` runs
+exclusively in Node.js during build time. This means:
+
+- Sensitive operations (like API calls, file system access) can safely be performed
+- No build-time code or data is included in the final client bundle
+- Environment variables and secrets can be safely accessed
+- No browser-specific APIs are available
+
+:::
+
+## File Location
+
+Create a file named `zudoku.build.ts` in the root of your project:
+
+```bash
+your-project/
+├── zudoku.config.ts
+├── zudoku.build.ts    # <-- Add this file
+└── ...
+```
+
+## Basic Configuration
+
+Here's a basic example of a build configuration file:
+
+```ts
+import type { ZudokuBuildConfig } from "zudoku";
+
+const buildConfig: ZudokuBuildConfig = {
+  processors: [
+    async ({ schema }) => {
+      // Transform your schema here
+      return schema;
+    },
+  ],
+  remarkPlugins: [],
+  rehypePlugins: [],
+};
+
+export default buildConfig;
+```
+
+## Configuration Options
+
+### `processors`
+
+An array of functions that transform your API schemas. Each processor receives:
+
+- `file`: The path to the schema file
+- `schema`: The OpenAPI schema object
+- `params`: Query parameters extracted from the input string (see
+  [Splitting Schemas](../guides/processors#using-query-parameters-to-split-schemas))
+- `dereference`: A function to dereference the schema
+
+Processors are executed in order, and each processor receives the output of the previous one.
+
+:::tip
+
+For detailed information about processors and available built-in processors, see the
+[Schema Processors](../guides/processors) guide.
+
+:::
+
+Here's a simple example that adds a description to all operations:
+
+```ts
+async function addDescriptionProcessor({ schema }) {
+  if (!schema.paths) return schema;
+
+  // Add a description to all operations
+  Object.values(schema.paths).forEach((path) => {
+    Object.values(path).forEach((operation) => {
+      if (typeof operation === "object" && operation) {
+        operation.description = "This is a public API endpoint";
+      }
+    });
+  });
+
+  return schema;
+}
+
+export default {
+  processors: [addDescriptionProcessor],
+};
+```
+
+### `remarkPlugins`
+
+An array of [Remark](https://github.com/remarkjs/remark) plugins to transform Markdown content.
+These plugins run before the content is converted to HTML.
+
+```ts
+import remarkContributors from "remark-contributors";
+
+export default {
+  remarkPlugins: [remarkContributors],
+};
+```
+
+### `rehypePlugins`
+
+An array of [Rehype](https://github.com/rehypejs/rehype) plugins to transform HTML content. These
+plugins run after Markdown is converted to HTML.
+
+```ts
+import rehypeKatex from "rehype-katex";
+
+export default {
+  rehypePlugins: [rehypeKatex],
+};
+```
+
+### `prerender`
+
+Configuration for the prerendering process that generates static HTML pages during build time.
+
+- `workers`: Number of parallel workers to use for prerendering. Defaults to 80% of available CPU
+  cores.
+
+```ts
+import os from "node:os";
+
+export default {
+  prerender: {
+    workers: 4, // Fixed number of workers
+  },
+};
+
+// Or use a percentage of available CPU cores
+export default {
+  prerender: {
+    workers: Math.floor(os.cpus().length * 0.75), // Use 75% of available cores
+  },
+};
+```