@lukoweb/apitogo 0.1.67 → 0.1.68

package/docs/configuration/authentication.md

@@ -1,255 +1,156 @@
 ---
-title: Overview
+title: Authentication
 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.
+API products on APItoGo use **`dev-portal`** authentication: the static site delegates sign-in to the
+provisioned portal API; OIDC client secrets stay on the backend.
 
-## Configuration
+For docs-only sites that embed a SPA identity provider directly in the browser, see
+[SPA providers (advanced)](#spa-providers-advanced).
 
-To implement the authentication option for your site, add the `authentication` property to the
-[APIToGo Configuration](./overview.md) file. The configuration is slightly different depending on
-the authentication provider you use.
+## Dev portal (recommended)
 
-## Authentication Providers
+Set authentication in `apitogo.config.json`:
 
-APIToGo supports Clerk, Auth0, Supabase, Azure B2C, any OpenID provider that supports the OpenID
-Connect protocol, and **dev-portal** (backend-delegated OIDC for APItoGo provisioned developer
-portals).
-
-Not seeing your authentication provider?
-[Let us know](https://github.com/lukoweb/apitogo-doc-tool/issues)
-
-### Dev portal (APItoGo)
-
-For sites provisioned through APItoGo MCP, use backend-delegated authentication. The static site
-redirects sign-in to the provisioned dev-portal API; OIDC client credentials stay on the backend
-only.
-
-```typescript
+```json
 {
-  // ...
-  authentication: {
-    type: "dev-portal",
-  },
-  // ...
+  "authentication": {
+    "enabled": true,
+    "type": "dev-portal",
+    "redirectToAfterSignIn": "/account/dashboard",
+    "redirectToAfterSignUp": "/account/dashboard"
+  }
 }
 ```
 
-Set the backend API URL via environment variable (MCP writes this at scaffold/publish):
+Backend API URL (MCP writes this at scaffold/publish):
 
 ```bash
 VITE_APITOGO_AUTHENTICATION_API_BASE_URL=https://your-dev-portal-api.example.com
 ```
 
-You can also set `authentication.apiBaseUrl` in `apitogo.config.json` or
-`APITOGO_CONFIG_AUTHENTICATION__API_BASE_URL` in `.env`.
+Or `authentication.apiBaseUrl` in JSON / `APITOGO_CONFIG_AUTHENTICATION__API_BASE_URL` in `.env`.
 
-**Local demo mode:** In development (`npm run dev`), `demoMode` is enabled by default when the user
-panel is on. You do not need `VITE_APITOGO_AUTHENTICATION_API_BASE_URL`, OIDC, or a running
-dev-portal backend to explore protected account pages locally. Sign in at `/login` with:
+### Local demo mode
+
+In development (`npm run dev`), `demoMode` is on by default when the user panel is enabled. You do
+not need a backend URL or OIDC to explore account pages. Sign in at `/login` with:
 
 ```text
 demo@apitogo.local / password
 ```
 
-Disable with `APITOGO_CONFIG_DEMO_MODE=false` in `.env` or `"demoMode": false` in
-`apitogo.config.json`. Demo mode is never active in production builds.
-
-**Local preview (demo off):** When the backend URL is a placeholder or unreachable and demo mode is
-disabled, the account area shows a message that sign-in unlocks after publish. Docs and API
-reference remain public. Plans on `/pricing` load from `apitogo.config.json` (overridable via `.env`
-— see [Manifest](./manifest.md), including `includedActionKeys` per plan). Plan edits hot-reload
-without restarting the dev server.
+Disable with `APITOGO_CONFIG_DEMO_MODE=false` or `"demoMode": false` in JSON. Demo mode is never
+active in production builds.
 
-### Dev portal configuration files
+When demo is off and the backend URL is a placeholder, the account area explains that sign-in
+unlocks after publish. Docs and API reference stay public. Plans on `/pricing` come from
+`apitogo.config.json` (see [Manifest](./manifest.md)).
 
-| Concern                                                  | File                                                                       |
-| -------------------------------------------------------- | -------------------------------------------------------------------------- |
-| Site, plans, modules, branding, backend/gateway metadata | `apitogo.config.json` (+ `.env` overrides — see [Manifest](./manifest.md)) |
-| Plugins and custom code                                  | `apitogo.config.tsx`                                                       |
-| OIDC and Stripe for publish                              | `.env` via `APITOGO_CONFIG_AUTHENTICATION__*`                              |
+### Config files
 
-**Production:** Register one OIDC app with redirect URI `https://{backend}/signin-oidc` (see MCP
-`manualSteps.oidcRedirectUri`). The frontend uses cookie sessions via `credentials: "include"` on
-`/api/v1/auth/me`.
+| Concern                                      | File                                                          |
+| -------------------------------------------- | ------------------------------------------------------------- |
+| Site, plans, modules, branding, backend      | `apitogo.config.json` (+ `.env` — [Manifest](./manifest.md))  |
+| OIDC and Stripe for publish                  | `.env` via `APITOGO_CONFIG_AUTHENTICATION__*`                 |
 
-### Auth0
+### Production OIDC
 
-For Auth0, you will need the `clientId` associated with the domain you are using.
+Register one OIDC app with redirect URI `https://{backend}/signin-oidc` (MCP returns
+`manualSteps.oidcRedirectUri` after publish). The frontend uses cookie sessions via
+`credentials: "include"` on `/api/v1/auth/me`.
 
-You can find this in the Auth0 dashboard under
-[Application Settings](https://auth0.com/docs/get-started/applications/application-settings).
+Publish secrets (site `.env`, never commit):
 
-```typescript
-{
-  // ...
-  authentication: {
-    type: "auth0",
-    domain: "yourdomain.us.auth0.com",
-    clientId: "<your-auth0-clientId>",
-    scopes: ["openid", "profile", "email", "custom_scope"],
-  },
-  // ...
-}
+```sh
+APITOGO_CONFIG_AUTHENTICATION__OIDC__AUTHORITY=https://login.example.com
+APITOGO_CONFIG_AUTHENTICATION__OIDC__CLIENT_ID=your-client-id
+APITOGO_CONFIG_AUTHENTICATION__OIDC__CLIENT_SECRET=your-client-secret
+APITOGO_CONFIG_AUTHENTICATION__STRIPE__SECRET_KEY=sk_test_...
+APITOGO_CONFIG_AUTHENTICATION__STRIPE__WEBHOOK_SECRET=whsec_...
 ```
 
-To setup Auth0, create a Single Page Application (SPA) application in the Auth0 dashboard. Set the
-following options:
+Stripe is required only when you have **paid** gateway plans. Full flow: [MCP go-live](../mcp/go-live.md).
 
-- 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.
+Auth mode for end users (`native` | `oidc` | `nativeAndOidc`) is shaped via MCP /
+`update_dev_portal_manifest`.
 
-### Clerk
+## Protected routes
 
-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.
+After authentication is configured, protect routes with patterns or callbacks:
 
-```typescript
+```json
 {
-  // ...
-  authentication: {
-    type: "clerk",
-    clerkPubKey: "<your-clerk-publishable-key>",
-    // Optional. See: https://clerk.com/docs/backend-requests/jwt-templates
-    jwtTemplateName: "dev-portal",
-  },
-  // ...
+  "protectedRoutes": ["/admin/*", "/settings", "/api/*"]
 }
 ```
 
-### OpenID
+Or in TSX for custom authorization — see [Protected routes](./protected-routes.md).
 
-For authentication services that support OpenID, you will need to supply an `clientId` and `issuer`.
+## SPA providers (advanced)
 
-```typescript
-{
-  // ...
-  authentication: {
-    type: "openid",
-    clientId: "<your-client-id>",
-    issuer: "<the-issuer-url>",
-    scopes: ["openid", "profile", "email", "custom_scope"] // Optional custom scopes
-  },
-  // ...
-}
-```
+:::caution{title="Portal products use dev-portal"}
 
-When configuring your OpenID provider, you will need to set the following:
+SPA providers (Auth0, Clerk, OpenID, Supabase, Azure B2C, Firebase, PingFederate) run the OAuth
+callback in the browser (`/oauth/callback`). Prefer **`dev-portal`** for APItoGo-hosted API products.
+Use SPA providers only for standalone docs sites that talk to the IdP directly.
 
-- 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.
+Configure `authentication` in JSON or TSX. Provider-specific pages:
 
-### Supabase
+- [Auth0](./authentication-auth0.md)
+- [Clerk](./authentication-clerk.md)
+- [Azure AD / B2C](./authentication-azure-ad.md)
+- [PingFederate](./authentication-pingfederate.md)
+- [Supabase](./authentication-supabase.md)
+- [Firebase](./authentication-firebase.md)
 
-To use Supabase as your authentication provider, supply your project's URL, API key, and the OAuth
-provider to use.
+Typical SPA callback setup:
 
-```typescript title="apitogo.config.ts"
-{
-  // ...
-  authentication: {
-    type: "supabase",
-    provider: "github",
-    supabaseUrl: "https://your-project.supabase.co",
-    supabaseKey: "<your-supabase-key>",
-    redirectToAfterSignUp: "/",
-    redirectToAfterSignIn: "/",
-    redirectToAfterSignOut: "/",
-  },
-  // ...
-}
-```
+- Production: `https://your-site.com/oauth/callback`
+- Local: `http://localhost:3000/oauth/callback`
+- Add your site hostname to allowed CORS origins in the IdP
 
-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`.
+### Auth0 (SPA example)
 
-### Azure B2C
-
-For Azure B2C authentication, you will need to provide your Azure B2C tenant name, client ID, and
-policy name.
-
-```typescript title="apitogo.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"]
-  },
-  // ...
+```ts
+authentication: {
+  type: "auth0",
+  domain: "yourdomain.us.auth0.com",
+  clientId: "<your-auth0-clientId>",
+  scopes: ["openid", "profile", "email"],
 }
 ```
 
-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
+### Clerk (SPA example)
 
-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:
+```ts
+authentication: {
+  type: "clerk",
+  clerkPubKey: "<your-clerk-publishable-key>",
+  jwtTemplateName: "dev-portal", // optional
+}
+```
 
-- `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
+### OpenID (SPA example)
 
-If the provider does not return a field, it will be left blank.
+```ts
+authentication: {
+  type: "openid",
+  clientId: "<your-client-id>",
+  issuer: "<the-issuer-url>",
+  scopes: ["openid", "profile", "email"],
+}
+```
 
-## Protected Routes
+### Supabase / Azure B2C
 
-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.
+See the provider pages for full options. Default scopes are `openid`, `profile`, and `email` unless
+you override them.
 
-```typescript title="apitogo.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,
-  },
-  // ...
-}
-```
+## User profile fields
 
-See the [Protected Routes](./protected-routes.md) documentation for detailed information on
-configuring route protection, reason codes, and navigation behavior.
+After SPA login, the profile comes from the provider UserInfo endpoint: `name`, `email`, `picture`,
+`email_verified`. Missing fields are left blank. Dev-portal sessions use the portal API instead.

package/docs/configuration/build-configuration.mdx

@@ -10,7 +10,7 @@ API schemas before they are used in the documentation.
 
 :::tip{title="Security Note"}
 
-Unlike `apitogo.config.ts` which runs in both client and server environments, `apitogo.build.ts`
+Unlike your site config which runs in both client and server environments, `apitogo.build.ts`
 runs exclusively in Node.js during build time. This means:
 
 - Sensitive operations (like API calls, file system access) can safely be performed
@@ -26,7 +26,7 @@ Create a file named `apitogo.build.ts` in the root of your project:
 
 ```bash
 your-project/
-├── apitogo.config.ts
+├── apitogo.config.json
 ├── apitogo.build.ts    # <-- Add this file
 └── ...
 ```

package/docs/configuration/docs.md

@@ -42,7 +42,7 @@ its original file-based path.
 
 ### Navigation Configuration
 
-```tsx {5-6,13-14} title="apitogo.config.tsx" showLineNumbers
+```tsx {5-6,13-14} title="config" showLineNumbers
 export default {
   navigation: [
     {
@@ -75,7 +75,7 @@ In this example:
 
 Configure docs routing and behavior through the `docs` section in your config:
 
-```tsx title="apitogo.config.tsx"
+```tsx title="config"
 export default {
   docs: {
     files: ["/pages/**/*.{md,mdx}"],
@@ -100,7 +100,7 @@ export default {
 Glob patterns that specify which files to include as documentation pages. You can provide a single
 pattern or an array of patterns.
 
-```tsx title="apitogo.config.tsx"
+```tsx title="config"
 // Single pattern
 docs: {
   files: "/content/**/*.md";
@@ -124,7 +124,7 @@ using frontmatter.
 
 Whether to show the table of contents (TOC) by default.
 
-```tsx title="apitogo.config.tsx"
+```tsx title="config"
 docs: {
   defaultOptions: {
     toc: false; // Hide TOC by default
@@ -139,7 +139,7 @@ docs: {
 
 Whether to disable the previous/next page navigation by default.
 
-```tsx title="apitogo.config.tsx"
+```tsx title="config"
 docs: {
   defaultOptions: {
     disablePager: true; // Disable pager by default
@@ -154,7 +154,7 @@ docs: {
 
 Whether to show the last modified date by default.
 
-```tsx title="apitogo.config.tsx"
+```tsx title="config"
 docs: {
   defaultOptions: {
     showLastModified: true; // Show last modified date
@@ -169,7 +169,7 @@ docs: {
 
 Configuration for the "Edit this page" link.
 
-```tsx title="apitogo.config.tsx"
+```tsx title="config"
 docs: {
   defaultOptions: {
     suggestEdit: {
@@ -191,7 +191,7 @@ in a `docs/pages/` directory, the URL might be
 Whether to show a copy button in the page header that allows users to copy the page markdown. This
 feature requires `publishMarkdown` to be enabled (see below).
 
-```tsx title="apitogo.config.tsx"
+```tsx title="config"
 docs: {
   defaultOptions: {
     copyPage: true; // Enable copy button for all pages
@@ -218,7 +218,7 @@ The copy button provides:
 When enabled, generates `.md` files for each documentation page during build. Pages can then be
 accessed at their URL path with the `.md` extension appended (e.g., `/docs/quickstart.md`).
 
-```tsx title="apitogo.config.tsx"
+```tsx title="config"
 docs: {
   publishMarkdown: true,
 }
@@ -238,7 +238,7 @@ The generated markdown files:
 Configuration for generating LLM-friendly documentation files. See the
 [llms.txt configuration](/docs/configuration/llms) page for complete documentation.
 
-```tsx title="apitogo.config.tsx"
+```tsx title="config"
 docs: {
   llms: {
     llmsTxt: true,        // Generate llms.txt summary file