@lukoweb/apitogo 0.2.22 → 0.2.24

package/docs/configuration/gateway.md

@@ -1,221 +1,221 @@
----
-title: Protect your API with the gateway
-description:
-  Put the APItoGo gateway in front of an API you already host. What each setting means, where to
-  find the login values (OIDC), and how to write the rules yourself.
-sidebar_icon: shield
----
-
-The **gateway** sits in front of an API you already host. It checks who is calling, limits how
-often, and passes only the calls you allow to your API. You do not move your API.
-
-```
- callers ──► APItoGo gateway ──► your API (stays where it is)
-              │  checks the login token
-              │  limits calls
-              │  allows only the calls in your OpenAPI file
-              └  your real API address stays hidden
-```
-
-You set it up in one file, `apitogo.config.json`, in a `gateway` section.
-
-## The smallest setup
-
-```json
-{
-  "version": 2,
-  "gateway": {
-    "origin": { "mode": "proxy", "url": "https://api.example.com", "healthPath": "/health" },
-    "specs": ["apis/openapi.yaml"],
-    "auth": {
-      "mode": "oidc",
-      "metadataUrl": "https://login.example.com/.well-known/openid-configuration",
-      "issuers": ["https://login.example.com/"],
-      "audiences": ["my-api"]
-    },
-    "policies": {
-      "access": { "jwt": true, "apiKey": false },
-      "rateLimit": { "calls": 60, "periodSeconds": 60 },
-      "operations": { "public": ["GET /health"] }
-    }
-  }
-}
-```
-
-`apitogo add gateway` writes the first part for you. The rest you write yourself, and the sections
-below explain every value.
-
-## 1. Your API (`origin` and `specs`)
-
-| Setting             | What to put there                                                                  | Where to get it                                                  |
-| ------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
-| `origin.mode`       | `proxy`: your API stays where it is.                                               | Always `proxy` for an API you host.                              |
-| `origin.url`        | The address of your API. It must be `https://`.                                    | You already know it. It is where your API answers today.         |
-| `origin.healthPath` | A path the platform can call to see that your API is alive, for example `/health`. | A cheap call on your API that needs no login.                    |
-| `specs`             | The OpenAPI file or files that describe your API.                                  | Your API's `openapi.yaml`, or the file your framework generates. |
-
-The gateway only lets through the calls listed in your OpenAPI file. A call that is not in the file
-is refused, so a forgotten path never leaks.
-
-## 2. Who may call (`auth`)
-
-With `"mode": "oidc"` the caller sends a **login token** (a JWT) with each call:
-`Authorization: Bearer <token>`. The token comes from your own login provider, for example Auth0,
-Microsoft Entra ID, Okta or Keycloak. The gateway checks that the token is genuine, is from your
-provider and is meant for your API.
-
-You must give **all three** of these values. If one is missing, the deploy is blocked, so a settings
-mistake can never leave your API open.
-
-| Setting       | What it is                                                                                            | How to find it                                                |
-| ------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
-| `metadataUrl` | The address where the gateway reads your provider's public keys, so it can check a token's signature. | Your issuer address plus `/.well-known/openid-configuration`. |
-| `issuers`     | Who is allowed to issue tokens. It must match the `iss` value in your tokens **exactly**.             | The `issuer` field inside the metadata document (see below).  |
-| `audiences`   | Who the token is meant for. It must match the `aud` value in your tokens.                             | The identifier you gave your API at your provider.            |
-
-### Find the values in four steps
-
-1. **Find your provider's issuer address.** It is on the provider's dashboard or in its docs.
-   Typical shapes are in the table below.
-2. **Open the metadata address in a browser.** Add `/.well-known/openid-configuration` to the issuer
-   address. You see a JSON document. If you see an error, the address is wrong.
-3. **Copy the `issuer` value from that document** into `issuers`, character for character, including
-   a trailing `/` if it has one.
-4. **Use the identifier of your API as `audiences`.** You create this identifier at your provider
-   when you register your API. It is often called _API identifier_, _audience_ or _application ID
-   URI_.
-
-### Typical values by provider
-
-These are typical shapes. Always confirm them in your provider's dashboard.
-
-| Provider           | Issuer                                                                        | Audience                                                       |
-| ------------------ | ----------------------------------------------------------------------------- | -------------------------------------------------------------- |
-| Auth0              | `https://YOUR-TENANT.auth0.com/` (with the trailing `/`)                      | The _API identifier_ of your API in Auth0                      |
-| Microsoft Entra ID | `https://login.microsoftonline.com/TENANT-ID/v2.0`                            | Your API's _Application ID URI_, for example `api://CLIENT-ID` |
-| Okta               | `https://YOUR-ORG.okta.com/oauth2/default` (or your own authorization server) | The audience set on that authorization server                  |
-| Keycloak           | `https://HOST/realms/YOUR-REALM`                                              | The client or audience you configured for your API             |
-
-In every case the metadata address is the issuer plus `/.well-known/openid-configuration`.
-
-### Check a real token
-
-Ask your provider for a token for your API, then read what is inside it. The values `iss` and `aud`
-must match your `issuers` and `audiences`:
-
-```bash
-node -p "JSON.parse(Buffer.from(process.argv[1].split('.')[1],'base64url').toString())" "PASTE-THE-TOKEN-HERE"
-```
-
-A token is a login credential. Read it on your own computer, as above, and never share it.
-
-### The most common mistakes
-
-| What you see                                                      | Usual cause                                                                                                |
-| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| Every call answers `401` although the token looks right           | `issuers` or `audiences` does not match `iss` or `aud` in the token. A trailing `/` is enough to break it. |
-| `apitogo check` or `deploy` says the auth settings are incomplete | One of `metadataUrl`, `issuers` or `audiences` is empty. All three are needed.                             |
-| The metadata address shows an error in the browser                | The issuer address is wrong, or your provider uses a different path. Check its docs.                       |
-
-> **Not available yet:** `"mode": "identity"` (APItoGo's own sign-up and login for your end users)
-> is a planned service. For now, use `oidc` with your own provider.
-
-## 3. The rules (`policies`)
-
-Rules go in `gateway.policies`. Write them by hand: they are a few lines each.
-
-### `access`: who gets in
-
-```json
-"access": { "jwt": true, "apiKey": false }
-```
-
-| Setting  | Effect                                                                                                                        |
-| -------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `jwt`    | `true`: a valid login token is required.                                                                                      |
-| `apiKey` | `true`: a key in the `Ocp-Apim-Subscription-Key` header is required. Keys need the plans service, which is not available yet. |
-
-Set `access` yourself and do not rely on the default.
-
-### `operations`: open a call to everyone, or close it
-
-```json
-"operations": { "public": ["GET /health"], "deny": ["DELETE /orders"] }
-```
-
-Each entry is `METHOD /path`, exactly as in your OpenAPI file.
-
-| List     | Effect                                                                               |
-| -------- | ------------------------------------------------------------------------------------ |
-| `public` | Anyone can call it, with no token. Use it for a health check or a public price list. |
-| `deny`   | The gateway always refuses it, even with a valid token.                              |
-
-Every other call needs a login.
-
-### `rateLimit` and `quota`: how often
-
-```json
-"rateLimit": { "calls": 60, "periodSeconds": 60 },
-"quota": { "calls": 10000, "periodDays": 30 }
-```
-
-| Setting     | Effect                                                                                                                 |
-| ----------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `rateLimit` | At most `calls` calls in every `periodSeconds` seconds. Extra calls get `429`. Use it to protect your API from bursts. |
-| `quota`     | At most `calls` calls in every `periodDays` days. Use it for a monthly allowance.                                      |
-
-### `cors`: which websites may call from a browser
-
-```json
-"cors": ["https://app.example.com"]
-```
-
-A browser only lets a web page call your API if the API allows that page's site. List each site as
-`https://host` only: no path and no trailing `/`. An entry like `https://app.example.com/` is
-refused by `apitogo check`.
-
-### Keep your API from being called directly
-
-Your API has a public address, so someone could skip the gateway. Make your API accept calls only
-with a secret that only the gateway sends:
-
-```json
-"origin": {
-  "mode": "proxy",
-  "url": "https://api.example.com",
-  "auth": { "type": "header", "name": "X-Gateway-Secret", "value": "secret:GATEWAY_SECRET" }
-}
-```
-
-```bash
-npx apitogo secrets set GATEWAY_SECRET
-```
-
-The value is a reference, never the secret itself. The secret is stored encrypted and never shown
-again. Then make your API refuse any call without that header.
-
-## 4. Try it and check it
-
-Run these before you deploy:
-
-```bash
-npx apitogo check
-npx apitogo plan
-```
-
-`check` finds mistakes in the file, offline. `plan` shows what a deploy would change and changes
-nothing. Then deploy and test the address that `apitogo status` shows:
-
-```bash
-npx apitogo deploy --only gateway
-curl -i https://YOUR-GATEWAY-ADDRESS/health
-curl -i https://YOUR-GATEWAY-ADDRESS/orders
-```
-
-| Answer                          | Meaning                                                       |
-| ------------------------------- | ------------------------------------------------------------- |
-| `200` on a public call          | The call is open and your API answered.                       |
-| `401` on a call without a token | The gateway is protecting that call.                          |
-| `404`                           | The path is not in your OpenAPI file.                         |
-| `429`                           | The rate limit was reached.                                   |
-| `502` or `504`                  | Your API did not answer. Check `origin.url` and `healthPath`. |
+---
+title: Protect your API with the gateway
+description:
+  Put the APItoGo gateway in front of an API you already host. What each setting means, where to
+  find the login values (OIDC), and how to write the rules yourself.
+sidebar_icon: shield
+---
+
+The **gateway** sits in front of an API you already host. It checks who is calling, limits how
+often, and passes only the calls you allow to your API. You do not move your API.
+
+```
+ callers ──► APItoGo gateway ──► your API (stays where it is)
+              │  checks the login token
+              │  limits calls
+              │  allows only the calls in your OpenAPI file
+              └  your real API address stays hidden
+```
+
+You set it up in one file, `apitogo.config.json`, in a `gateway` section.
+
+## The smallest setup
+
+```json
+{
+  "version": 2,
+  "gateway": {
+    "origin": { "mode": "proxy", "url": "https://api.example.com", "healthPath": "/health" },
+    "specs": ["apis/openapi.yaml"],
+    "auth": {
+      "mode": "oidc",
+      "metadataUrl": "https://login.example.com/.well-known/openid-configuration",
+      "issuers": ["https://login.example.com/"],
+      "audiences": ["my-api"]
+    },
+    "policies": {
+      "access": { "jwt": true, "apiKey": false },
+      "rateLimit": { "calls": 60, "periodSeconds": 60 },
+      "operations": { "public": ["GET /health"] }
+    }
+  }
+}
+```
+
+`apitogo add gateway` writes the first part for you. The rest you write yourself, and the sections
+below explain every value.
+
+## 1. Your API (`origin` and `specs`)
+
+| Setting             | What to put there                                                                  | Where to get it                                                  |
+| ------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `origin.mode`       | `proxy`: your API stays where it is.                                               | Always `proxy` for an API you host.                              |
+| `origin.url`        | The address of your API. It must be `https://`.                                    | You already know it. It is where your API answers today.         |
+| `origin.healthPath` | A path the platform can call to see that your API is alive, for example `/health`. | A cheap call on your API that needs no login.                    |
+| `specs`             | The OpenAPI file or files that describe your API.                                  | Your API's `openapi.yaml`, or the file your framework generates. |
+
+The gateway only lets through the calls listed in your OpenAPI file. A call that is not in the file
+is refused, so a forgotten path never leaks.
+
+## 2. Who may call (`auth`)
+
+With `"mode": "oidc"` the caller sends a **login token** (a JWT) with each call:
+`Authorization: Bearer <token>`. The token comes from your own login provider, for example Auth0,
+Microsoft Entra ID, Okta or Keycloak. The gateway checks that the token is genuine, is from your
+provider and is meant for your API.
+
+You must give **all three** of these values. If one is missing, the deploy is blocked, so a settings
+mistake can never leave your API open.
+
+| Setting       | What it is                                                                                            | How to find it                                                |
+| ------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| `metadataUrl` | The address where the gateway reads your provider's public keys, so it can check a token's signature. | Your issuer address plus `/.well-known/openid-configuration`. |
+| `issuers`     | Who is allowed to issue tokens. It must match the `iss` value in your tokens **exactly**.             | The `issuer` field inside the metadata document (see below).  |
+| `audiences`   | Who the token is meant for. It must match the `aud` value in your tokens.                             | The identifier you gave your API at your provider.            |
+
+### Find the values in four steps
+
+1. **Find your provider's issuer address.** It is on the provider's dashboard or in its docs.
+   Typical shapes are in the table below.
+2. **Open the metadata address in a browser.** Add `/.well-known/openid-configuration` to the issuer
+   address. You see a JSON document. If you see an error, the address is wrong.
+3. **Copy the `issuer` value from that document** into `issuers`, character for character, including
+   a trailing `/` if it has one.
+4. **Use the identifier of your API as `audiences`.** You create this identifier at your provider
+   when you register your API. It is often called _API identifier_, _audience_ or _application ID
+   URI_.
+
+### Typical values by provider
+
+These are typical shapes. Always confirm them in your provider's dashboard.
+
+| Provider           | Issuer                                                                        | Audience                                                       |
+| ------------------ | ----------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| Auth0              | `https://YOUR-TENANT.auth0.com/` (with the trailing `/`)                      | The _API identifier_ of your API in Auth0                      |
+| Microsoft Entra ID | `https://login.microsoftonline.com/TENANT-ID/v2.0`                            | Your API's _Application ID URI_, for example `api://CLIENT-ID` |
+| Okta               | `https://YOUR-ORG.okta.com/oauth2/default` (or your own authorization server) | The audience set on that authorization server                  |
+| Keycloak           | `https://HOST/realms/YOUR-REALM`                                              | The client or audience you configured for your API             |
+
+In every case the metadata address is the issuer plus `/.well-known/openid-configuration`.
+
+### Check a real token
+
+Ask your provider for a token for your API, then read what is inside it. The values `iss` and `aud`
+must match your `issuers` and `audiences`:
+
+```bash
+node -p "JSON.parse(Buffer.from(process.argv[1].split('.')[1],'base64url').toString())" "PASTE-THE-TOKEN-HERE"
+```
+
+A token is a login credential. Read it on your own computer, as above, and never share it.
+
+### The most common mistakes
+
+| What you see                                                      | Usual cause                                                                                                |
+| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| Every call answers `401` although the token looks right           | `issuers` or `audiences` does not match `iss` or `aud` in the token. A trailing `/` is enough to break it. |
+| `apitogo check` or `deploy` says the auth settings are incomplete | One of `metadataUrl`, `issuers` or `audiences` is empty. All three are needed.                             |
+| The metadata address shows an error in the browser                | The issuer address is wrong, or your provider uses a different path. Check its docs.                       |
+
+> **Not available yet:** `"mode": "identity"` (APItoGo's own sign-up and login for your end users)
+> is a planned service. For now, use `oidc` with your own provider.
+
+## 3. The rules (`policies`)
+
+Rules go in `gateway.policies`. Write them by hand: they are a few lines each.
+
+### `access`: who gets in
+
+```json
+"access": { "jwt": true, "apiKey": false }
+```
+
+| Setting  | Effect                                                                                                                        |
+| -------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `jwt`    | `true`: a valid login token is required.                                                                                      |
+| `apiKey` | `true`: a key in the `Ocp-Apim-Subscription-Key` header is required. Keys need the plans service, which is not available yet. |
+
+Set `access` yourself and do not rely on the default.
+
+### `operations`: open a call to everyone, or close it
+
+```json
+"operations": { "public": ["GET /health"], "deny": ["DELETE /orders"] }
+```
+
+Each entry is `METHOD /path`, exactly as in your OpenAPI file.
+
+| List     | Effect                                                                               |
+| -------- | ------------------------------------------------------------------------------------ |
+| `public` | Anyone can call it, with no token. Use it for a health check or a public price list. |
+| `deny`   | The gateway always refuses it, even with a valid token.                              |
+
+Every other call needs a login.
+
+### `rateLimit` and `quota`: how often
+
+```json
+"rateLimit": { "calls": 60, "periodSeconds": 60 },
+"quota": { "calls": 10000, "periodDays": 30 }
+```
+
+| Setting     | Effect                                                                                                                 |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `rateLimit` | At most `calls` calls in every `periodSeconds` seconds. Extra calls get `429`. Use it to protect your API from bursts. |
+| `quota`     | At most `calls` calls in every `periodDays` days. Use it for a monthly allowance.                                      |
+
+### `cors`: which websites may call from a browser
+
+```json
+"cors": ["https://app.example.com"]
+```
+
+A browser only lets a web page call your API if the API allows that page's site. List each site as
+`https://host` only: no path and no trailing `/`. An entry like `https://app.example.com/` is
+refused by `apitogo check`.
+
+### Keep your API from being called directly
+
+Your API has a public address, so someone could skip the gateway. Make your API accept calls only
+with a secret that only the gateway sends:
+
+```json
+"origin": {
+  "mode": "proxy",
+  "url": "https://api.example.com",
+  "auth": { "type": "header", "name": "X-Gateway-Secret", "value": "secret:GATEWAY_SECRET" }
+}
+```
+
+```bash
+npx apitogo secrets set GATEWAY_SECRET
+```
+
+The value is a reference, never the secret itself. The secret is stored encrypted and never shown
+again. Then make your API refuse any call without that header.
+
+## 4. Try it and check it
+
+Run these before you deploy:
+
+```bash
+npx apitogo check
+npx apitogo plan
+```
+
+`check` finds mistakes in the file, offline. `plan` shows what a deploy would change and changes
+nothing. Then deploy and test the address that `apitogo status` shows:
+
+```bash
+npx apitogo deploy --only gateway
+curl -i https://YOUR-GATEWAY-ADDRESS/health
+curl -i https://YOUR-GATEWAY-ADDRESS/orders
+```
+
+| Answer                          | Meaning                                                       |
+| ------------------------------- | ------------------------------------------------------------- |
+| `200` on a public call          | The call is open and your API answered.                       |
+| `401` on a call without a token | The gateway is protecting that call.                          |
+| `404`                           | The path is not in your OpenAPI file.                         |
+| `429`                           | The rate limit was reached.                                   |
+| `502` or `504`                  | Your API did not answer. Check `origin.url` and `healthPath`. |

package/docs/configuration/llms.md

@@ -1,90 +1,90 @@
----
-title: LLM-Friendly Documentation Export
-navigation_label: llms.txt
-navigation_icon: bot
----
-
-APIToGo can generate LLM-friendly versions of your documentation following the
-[llms.txt](https://llmstxt.org/) specification.
-
-During build, you can optionally generate:
-
-- **`.md` files** - Individual pages with frontmatter removed (via `publishMarkdown`)
-- **`llms.txt`** - Summary with links to all pages
-- **`llms-full.txt`** - Complete documentation in one file
-
-All options are disabled by default.
-
-## Configuration
-
-LLM features are configured through the `docs` section in your config:
-
-```tsx title="config"
-export default {
-  docs: {
-    files: "pages/**/*.{md,mdx}", // Your markdown files
-    publishMarkdown: true, // Generate .md files
-    llms: {
-      llmsTxt: true, // Generate llms.txt
-      llmsTxtFull: true, // Generate llms-full.txt
-      includeProtected: false, // Exclude protected routes
-    },
-  },
-};
-```
-
-All options are disabled by default.
-
-:::tip
-
-When enabled, markdown files are generated during build and deleted after creating the `llms.txt`
-files unless `publishMarkdown: true` is set (see
-[`publishMarkdown` docs](/docs/configuration/docs#publishmarkdown)).
-
-:::
-
-### `llmsTxt`
-
-**Type:** `boolean` **Default:** `false`
-
-Generates an `llms.txt` file with links to all documentation pages:
-
-```markdown title="llms.txt"
-# Documentation
-
-- [Quickstart](/docs/quickstart.md): Get started with APIToGo
-- [Writing](/docs/writing.md): A guide to writing documentation
-```
-
-### `llmsTxtFull`
-
-**Type:** `boolean` **Default:** `false`
-
-Generates `llms-full.txt` containing the complete content of all pages.
-
-### `includeProtected`
-
-**Type:** `boolean` **Default:** `false`
-
-By default, protected routes are excluded. Set to `true` to include them in the generated files.
-
-## Output
-
-Generated files are available in the output directory after build:
-
-```text
-dist/
-├── llms.txt           # Generated if llmsTxt: true
-├── llms-full.txt      # Generated if llmsTxtFull: true
-└── docs/
-    ├── quickstart.md  # Generated if publishMarkdown: true
-    ├── writing.md
-    └── ...
-```
-
-**Important:** Individual `.md` files are only kept in the final build if `publishMarkdown: true`.
-If only `llmsTxt` or `llmsTxtFull` is enabled, the `.md` files are generated temporarily during the
-build but deleted after the `llms.txt` files are created.
-
-Redirect pages, error pages (400, 404, 500), and protected routes (unless `includeProtected: true`)
-are automatically excluded from all generated files.
+---
+title: LLM-Friendly Documentation Export
+navigation_label: llms.txt
+navigation_icon: bot
+---
+
+APIToGo can generate LLM-friendly versions of your documentation following the
+[llms.txt](https://llmstxt.org/) specification.
+
+During build, you can optionally generate:
+
+- **`.md` files** - Individual pages with frontmatter removed (via `publishMarkdown`)
+- **`llms.txt`** - Summary with links to all pages
+- **`llms-full.txt`** - Complete documentation in one file
+
+All options are disabled by default.
+
+## Configuration
+
+LLM features are configured through the `docs` section in your config:
+
+```tsx title="config"
+export default {
+  docs: {
+    files: "pages/**/*.{md,mdx}", // Your markdown files
+    publishMarkdown: true, // Generate .md files
+    llms: {
+      llmsTxt: true, // Generate llms.txt
+      llmsTxtFull: true, // Generate llms-full.txt
+      includeProtected: false, // Exclude protected routes
+    },
+  },
+};
+```
+
+All options are disabled by default.
+
+:::tip
+
+When enabled, markdown files are generated during build and deleted after creating the `llms.txt`
+files unless `publishMarkdown: true` is set (see
+[`publishMarkdown` docs](/docs/configuration/docs#publishmarkdown)).
+
+:::
+
+### `llmsTxt`
+
+**Type:** `boolean` **Default:** `false`
+
+Generates an `llms.txt` file with links to all documentation pages:
+
+```markdown title="llms.txt"
+# Documentation
+
+- [Quickstart](/docs/quickstart.md): Get started with APIToGo
+- [Writing](/docs/writing.md): A guide to writing documentation
+```
+
+### `llmsTxtFull`
+
+**Type:** `boolean` **Default:** `false`
+
+Generates `llms-full.txt` containing the complete content of all pages.
+
+### `includeProtected`
+
+**Type:** `boolean` **Default:** `false`
+
+By default, protected routes are excluded. Set to `true` to include them in the generated files.
+
+## Output
+
+Generated files are available in the output directory after build:
+
+```text
+dist/
+├── llms.txt           # Generated if llmsTxt: true
+├── llms-full.txt      # Generated if llmsTxtFull: true
+└── docs/
+    ├── quickstart.md  # Generated if publishMarkdown: true
+    ├── writing.md
+    └── ...
+```
+
+**Important:** Individual `.md` files are only kept in the final build if `publishMarkdown: true`.
+If only `llmsTxt` or `llmsTxtFull` is enabled, the `.md` files are generated temporarily during the
+build but deleted after the `llms.txt` files are created.
+
+Redirect pages, error pages (400, 404, 500), and protected routes (unless `includeProtected: true`)
+are automatically excluded from all generated files.