@lukoweb/apitogo 0.2.56 → 0.2.57

package/docs/configuration/authentication.md

@@ -1,159 +1,118 @@
----
-title: Authentication
-sidebar_icon: shield-check
----
-
-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.
-
-For docs-only sites that embed a SPA identity provider directly in the browser, see
-[SPA providers (advanced)](#spa-providers-advanced).
-
-## Dev portal (recommended)
-
-Set authentication in `apitogo.config.json` (enabled by default on new scaffolds):
-
-```json
-{
-  "authentication": {
-    "enabled": true,
-    "type": "dev-portal",
-    "redirectToAfterSignIn": "/account/dashboard",
-    "redirectToAfterSignUp": "/account/dashboard"
-  }
-}
-```
-
-Backend API URL (`npx apitogo deploy` writes this to `.env` after the portal backend is
-provisioned):
-
-```bash
-VITE_APITOGO_AUTHENTICATION_API_BASE_URL=https://your-dev-portal-api.example.com
-```
-
-You do not need to enter this URL in `npx apitogo config`. Or set `authentication.apiBaseUrl` in
-JSON / `APITOGO_CONFIG_AUTHENTICATION__API_BASE_URL` in `.env` manually.
-
-### Local demo mode
-
-In development (`npx apitogo run`), `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` or `"demoMode": false` in JSON. Demo mode is never
-active in production builds.
-
-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)).
-
-### Config files
-
-| Concern                                 | File                                                         |
-| --------------------------------------- | ------------------------------------------------------------ |
-| Site, plans, modules, branding, backend | `apitogo.config.json` (+ `.env` — [Manifest](./manifest.md)) |
-| OIDC and Stripe for publish             | `.env` via `APITOGO_CONFIG_AUTHENTICATION__*`                |
-
-### Production OIDC
-
-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`.
-
-Publish secrets (site `.env`, never commit):
-
-```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_...
-```
-
-Stripe is required only when you have **paid** gateway plans. Full flow:
-[MCP go-live](../mcp/go-live.md).
-
-Auth mode for end users (`native` | `oidc` | `nativeAndOidc`) is shaped via MCP /
-`update_dev_portal_manifest`.
-
-## Protected routes
-
-After authentication is configured, protect routes with patterns or callbacks:
-
-```json
-{
-  "protectedRoutes": ["/admin/*", "/settings", "/api/*"]
-}
-```
-
-Or in TSX for custom authorization — see [Protected routes](./protected-routes.md).
-
-## SPA providers (advanced)
-
-:::caution{title="Portal products use dev-portal"}
-
-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.
-
-:::
-
-Configure `authentication` in JSON or TSX. Provider-specific pages:
-
-- [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)
-
-Typical SPA callback setup:
-
-- Production: `https://your-site.com/oauth/callback`
-- Local: `http://localhost:3000/oauth/callback`
-- Add your site hostname to allowed CORS origins in the IdP
-
-### Auth0 (SPA example)
-
-```ts
-authentication: {
-  type: "auth0",
-  domain: "yourdomain.us.auth0.com",
-  clientId: "<your-auth0-clientId>",
-  scopes: ["openid", "profile", "email"],
-}
-```
-
-### Clerk (SPA example)
-
-```ts
-authentication: {
-  type: "clerk",
-  clerkPubKey: "<your-clerk-publishable-key>",
-  jwtTemplateName: "dev-portal", // optional
-}
-```
-
-### OpenID (SPA example)
-
-```ts
-authentication: {
-  type: "openid",
-  clientId: "<your-client-id>",
-  issuer: "<the-issuer-url>",
-  scopes: ["openid", "profile", "email"],
-}
-```
-
-### Supabase / Azure B2C
-
-See the provider pages for full options. Default scopes are `openid`, `profile`, and `email` unless
-you override them.
-
-## User profile fields
-
-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.
+---
+title: Sign-in
+sidebar_icon: shield-check
+description: >-
+  The identity section of apitogo.config.json: how the people who use your portal sign up and sign
+  in, with APItoGo's sign-in service or your own OpenID Connect provider.
+---
+
+The `identity` section gives your portal sign-in: accounts, the sign-up and sign-in pages, password
+reset and email verification. The console (plans, API keys, usage) needs it.
+
+```json title=apitogo.config.json
+{
+  "identity": {}
+}
+```
+
+`"identity": {}` uses **APItoGo's sign-in service**. `apitogo deploy` sets it up for your project,
+with its own address (`https://id.apitogo.com/<project>`), and connects the portal to it. Nothing
+else is needed.
+
+## Settings
+
+| Setting              | Default   | What it does                                                               |
+| -------------------- | --------- | -------------------------------------------------------------------------- |
+| `provider`           | `apitogo` | `apitogo` (the hosted sign-in service) or `oidc` (your own provider)       |
+| `native`             | `true`    | People can create an account with an email address and a password          |
+| `connections`        | none      | Sign in with another provider too, such as Microsoft or Google             |
+| `providerOptions`    | none      | Passwords, sign-up, MFA, branding ([below](#provider-options))             |
+| `clients`            | none      | Extra apps that sign people in with the same accounts                      |
+| `issuer`, `clientId` | none      | With `provider: "oidc"`: your provider's issuer and the portal's client id |
+| `enabled`            | `true`    | `false` keeps the section but leaves sign-in out of deploys                |
+
+## Provider options
+
+```json
+"identity": {
+  "providerOptions": {
+    "signup": { "mode": "open", "allowedEmailDomains": ["example.com"] },
+    "password": { "minLength": 12, "checkBreached": true },
+    "mfa": { "mode": "optional" },
+    "branding": { "logo": "https://example.com/logo.svg", "color": "#0d9488" }
+  }
+}
+```
+
+- `signup.mode`: `open` (anyone), `invite` (people you invite) or `closed` (nobody new).
+  `allowedEmailDomains` limits sign-up to those domains.
+- `password`: the shortest password allowed (8 to 128), and whether known-breached passwords are
+  refused.
+- `mfa.mode`: `off`, `optional` or `required`.
+- `branding`: the logo and color of the sign-in pages and emails.
+- `customDomain`: a hostname of your own for the sign-in pages, such as `id.example.com`.
+
+## Sign in with another provider
+
+Add an OpenID Connect provider next to email and password. Its client secret is a project secret:
+
+```json
+"identity": {
+  "connections": [
+    {
+      "id": "microsoft",
+      "type": "oidc",
+      "authority": "https://login.microsoftonline.com/<tenant>/v2.0",
+      "clientId": "<client id>",
+      "clientSecret": "secret:MICROSOFT_CLIENT_SECRET",
+      "displayName": "Microsoft"
+    }
+  ]
+}
+```
+
+```bash
+npx apitogo secrets set MICROSOFT_CLIENT_SECRET
+```
+
+Set `"native": false` to offer only the connections.
+
+## Your own OpenID Connect provider
+
+If your users already have accounts somewhere else, point the portal at that provider instead:
+
+```json
+"identity": {
+  "provider": "oidc",
+  "issuer": "https://login.example.com",
+  "clientId": "portal"
+}
+```
+
+Register the portal in your provider with the redirect address
+`https://<your-portal>/oauth/callback`.
+
+## Use the same sign-in for your API
+
+By default the gateway checks API keys. To have it check the signed-in person's token as well, set
+`gateway.auth`:
+
+```json
+"gateway": {
+  "auth": { "mode": "identity" }
+}
+```
+
+The API reference's Try it then also offers **Signed-in user**, which sends that token. See
+[Gateway](./gateway.md).
+
+## Local preview
+
+`npx apitogo run` before the first deploy has no sign-in service yet. The console then signs in with
+a demo account, so you can try every page:
+
+```text
+demo@apitogo.local / password
+```
+
+The demo account exists only in a local preview, never in a deployed portal.

package/docs/configuration/footer.mdx

@@ -1,118 +1,89 @@
----
-sidebar_label: Footer
-sidebar_icon: panel-bottom-dashed
-description:
-  Configure the site footer via modules.landing.content.footer in apitogo.config.json, or
-  site.footer for advanced layouts.
----
-
-# Footer Configuration
-
-Portal sites (MCP / `apitogo init` scaffolds) render a global footer from **`apitogo.config.json`**
-→ `modules.landing.content.footer`. That footer appears on home, docs, API reference, pricing, and
-auth pages, and replaces the default “Built with APIToGo” line.
-
-## Recommended: landing content footer (JSON)
-
-Ask for real link columns, social URLs, copyright, and optional brand/tagline before inventing copy.
-Example:
-
-```json title=config.json
-{
-  "modules": {
-    "landing": {
-      "enabled": true,
-      "path": "/",
-      "layout": "landing",
-      "content": {
-        "footer": {
-          "columns": [
-            {
-              "title": "Product",
-              "links": [
-                { "label": "Features", "href": "/features" },
-                { "label": "Pricing", "href": "/pricing" },
-                { "label": "Documentation", "href": "/docs" }
-              ]
-            },
-            {
-              "title": "Company",
-              "links": [
-                { "label": "About", "href": "/about" },
-                { "label": "Contact", "href": "/contact" }
-              ]
-            }
-          ],
-          "social": [
-            { "icon": "github", "href": "https://github.com/your-org" },
-            { "icon": "linkedin", "href": "https://www.linkedin.com/company/apitogo" }
-          ],
-          "copyright": "© 2026 Your Company. All rights reserved."
-        }
-      }
-    }
-  }
-}
-```
-
-With MCP connected, prefer asking the user for footer content, then editing JSON (there is no
-dedicated footer MCP tool). See [MCP overview](../mcp/overview.md).
-
-## Advanced: `site.footer` (engine)
-
-For custom layouts you can still configure `site.footer` (often from TSX when you need dynamic
-values):
-
-```tsx title=config
-export default {
-  site: {
-    footer: {
-      position: "center", // "start" | "center" | "end"
-      copyright: `© ${new Date().getFullYear()} YourCompany LLC. All rights reserved.`,
-      columns: [
-        {
-          title: "Product",
-          links: [
-            { label: "Features", href: "/features" },
-            { label: "Pricing", href: "/pricing" },
-          ],
-        },
-      ],
-      social: [
-        { icon: "github", href: "https://github.com/yourusername" },
-        { icon: "x", href: "https://x.com/yourhandle", label: "Follow us" },
-      ],
-      logo: {
-        src: { light: "/logo-light.svg", dark: "/logo-dark.svg" },
-        alt: "Company Logo",
-        width: "100px",
-      },
-    },
-  },
-};
-```
-
-### Social icons
-
-Supported `icon` values include: `reddit`, `discord`, `github`, `x`, `linkedin`, `facebook`,
-`instagram`, `youtube`, `tiktok`, `twitch`, `pinterest`, `snapchat`, `whatsapp`, `telegram` — or a
-custom React component.
-
-## Slots
-
-Insert content around the footer with `footer-before` and `footer-after` in site config `slots`:
-
-```tsx
-slots: {
-  "footer-before": () => (
-    <div>
-      <h3>Custom pre-footer content</h3>
-    </div>
-  ),
-}
-```
-
-## Related
-
-- [Manifest](./manifest.md)
-- [Site](./site.md)
+---
+title: Footer
+sidebar_label: Footer
+sidebar_icon: panel-bottom-dashed
+description: >-
+  The portal's footer is a React file you own, named by portal.footer. It shows under every page
+  except the console's.
+---
+
+The footer is a React file in your folder, **`apitogo/portal/footer/Footer.tsx`**, named by
+`portal.footer` in `apitogo.config.json`:
+
+```json title=apitogo.config.json
+{
+  "portal": {
+    "footer": "apitogo/portal/footer/Footer.tsx"
+  }
+}
+```
+
+It shows under the home page, the docs, the API reference and the pricing page. It is not shown on
+the console's pages (`/account`, `/login`, `/signup`).
+
+`apitogo add portal` writes a starter footer and the setting. Remove `portal.footer` to have no
+footer.
+
+## The starter footer
+
+The starter uses `FooterSection` from `@lukoweb/apitogo-module-landing`, so it matches the home
+page. Change anything in it:
+
+```tsx title=apitogo/portal/footer/Footer.tsx
+import { FooterSection } from "@lukoweb/apitogo-module-landing";
+
+const NAME = "Books API";
+
+export default function Footer() {
+  return (
+    <FooterSection
+      footer={{
+        brand: { name: NAME, tagline: "Documentation, API keys and plans for the Books API." },
+        columns: [
+          {
+            title: "Developers",
+            links: [
+              { label: "Documentation", href: "/introduction" },
+              { label: "API Reference", href: "/api" },
+              { label: "Pricing", href: "/pricing" },
+            ],
+          },
+          {
+            title: "Company",
+            links: [{ label: "Contact", href: "mailto:hello@example.com" }],
+          },
+        ],
+        social: [{ icon: "github", href: "https://github.com/example", label: "GitHub" }],
+        copyright: `© ${new Date().getFullYear()} ${NAME}`,
+      }}
+    />
+  );
+}
+```
+
+`FooterSection` takes:
+
+| Field       | What it is                                                                  |
+| ----------- | --------------------------------------------------------------------------- |
+| `brand`     | `name`, an optional `tagline`, and an optional `logoSrc` (an image address) |
+| `columns`   | Link columns: a `title` and `links` of `{ label, href }`                    |
+| `social`    | Icon links: `icon` (`github`, `x`), `href` and an optional `label`          |
+| `copyright` | The last line; by default `© <year> <name>. All rights reserved.`           |
+
+## Your own footer
+
+The file can render anything: it is a React component, and its default export is the footer. Use the
+theme's classes (`bg-background`, `text-muted-foreground`, `border-t`) so it follows light and dark
+mode:
+
+```tsx title=apitogo/portal/footer/Footer.tsx
+export default function Footer() {
+  return (
+    <footer className="border-t bg-background py-8 text-center text-sm text-muted-foreground">
+      © {new Date().getFullYear()} Books API · <a href="/pricing">Pricing</a>
+    </footer>
+  );
+}
+```
+
+`apitogo check` reports a `portal.footer` that names a file that does not exist.

package/docs/configuration/make-config.mdx

@@ -2,7 +2,7 @@
 title: Make config (CLI)
 navigation_label: Make config
 sidebar_icon: file-cog
-description:
+description: >-
   Change a config version 2 project from the CLI: portal name, API code, OpenAPI files, docs pages
   and plans.
 ---
@@ -95,6 +95,6 @@ npx apitogo config --patch '{"portal":{"search":"none"}}'
 
 ## See also
 
-- [Manifest (`apitogo.config.json`)](./manifest.md)
+- [Manifest (`apitogo.config.json`)](./overview.md)
 - [Gateway plans](./plans.md)
 - [Shape with CLI](../cli/shape.md)