zuplo 7.7.16 → 7.8.0

package/docs/ai-gateway/bedrock-runtime.mdx

@@ -0,0 +1,317 @@
+---
+title: Using Bedrock Runtime
+sidebar_label: Bedrock Runtime
+description:
+  Put the AI Gateway in front of Amazon Bedrock's native API without changing
+  your code. Point your AWS SDK client at your app and keep every call site.
+---
+
+**Bedrock Runtime** is
+[Amazon Bedrock's native API](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_Operations_Amazon_Bedrock_Runtime.html)—the
+one the AWS SDKs call when you use `bedrock-runtime` from `@aws-sdk/*`, `boto3`,
+or the Go and Java SDKs. Adding it as a provider lets those clients keep working
+exactly as they are, with the gateway in the path for authentication, model
+filtering, usage metering, and cost tracking.
+
+This provider exists for one job: **you change the client's configuration, not
+your code.** Point the client's `endpoint` at your app's URL, give it the app's
+API key instead of AWS credentials, and every `ConverseCommand`,
+`InvokeModelCommand`, and streaming call you already wrote keeps running.
+
+Requests reach your own AWS account on your own AWS billing, signed by the
+gateway with an IAM key pair you configure once.
+
+## Bedrock Runtime or Bedrock Mantle?
+
+Zuplo supports two Amazon Bedrock providers. Both reach your own AWS account—
+what separates them is the API your client speaks.
+
+|                   | Bedrock Runtime                                 | [Bedrock Mantle](./bedrock-mantle.mdx) |
+| ----------------- | ----------------------------------------------- | -------------------------------------- |
+| API your app uses | Bedrock's native API                            | OpenAI- or Anthropic-shaped            |
+| Client            | an AWS SDK                                      | any OpenAI or Anthropic client         |
+| Gateway path      | `/{app_id}/model/{modelId}/{operation}`         | `/{app_id}/v1/...`                     |
+| Credential        | long-term IAM access key pair                   | long-term Bedrock API key (`ABSK`)     |
+| Best for          | existing AWS SDK code you don't want to rewrite | new code, or one API across providers  |
+
+Choose **Bedrock Runtime** when you already have AWS SDK code. Choose **Bedrock
+Mantle** when you want Bedrock models through the same
+[Universal API](./universal-api.mdx) as every other provider.
+
+The two need separate provider configurations even for the same AWS account: a
+provider holds exactly one credential, and a Bedrock API key can't be used as an
+IAM access key pair.
+
+## Supported operations
+
+The gateway serves the four Bedrock Runtime operations at their AWS paths:
+
+| Operation                       | Path                                           | Streaming |
+| ------------------------------- | ---------------------------------------------- | --------- |
+| `Converse`                      | `/model/{modelId}/converse`                    | No        |
+| `ConverseStream`                | `/model/{modelId}/converse-stream`             | Yes       |
+| `InvokeModel`                   | `/model/{modelId}/invoke`                      | No        |
+| `InvokeModelWithResponseStream` | `/model/{modelId}/invoke-with-response-stream` | Yes       |
+
+Your request and response bodies pass through unchanged, so anything these
+operations support works—tool use, guardrail configuration,
+`additionalModelRequestFields`, and model-native `InvokeModel` bodies the
+gateway has no knowledge of. Streaming responses keep Bedrock's
+`application/vnd.amazon.eventstream` framing, so the SDK's own decoder reads
+them as it always has.
+
+Your request headers reach Bedrock as well, including the `x-amzn-bedrock-*`
+headers and the `x-amz-*` ones your SDK sets. The gateway removes only what it
+owns: the `Authorization` header carrying your app's API key, the SigV4 headers
+it replaces with its own signature (`x-amz-date`, `x-amz-content-sha256`, and
+`x-amz-security-token`), cookies, the hop-by-hop headers, and the `zp-` and
+`cf-` headers added on the way in. It sets `content-type` itself.
+
+`CountTokens` and `InvokeModelWithBidirectionalStream` aren't served. Calling
+either returns a `400 ValidationException` naming the operations that are.
+
+:::note
+
+A Bedrock Runtime provider serves only these native paths. It doesn't serve the
+[Universal API](./universal-api.mdx) endpoints (`/v1/chat/completions`,
+`/v1/messages`, `/v1/responses`, `/v1/embeddings`), and its models don't appear
+in an app's `GET /v1/models` listing. Add [Bedrock Mantle](./bedrock-mantle.mdx)
+alongside it if you want both.
+
+:::
+
+## Before you begin
+
+You need:
+
+- An AWS account with access to Amazon Bedrock in the region you plan to use.
+- A **long-term IAM user access key pair**—an access key ID starting with `AKIA`
+  and its secret. Temporary STS credentials (`ASIA…`, or any pair with a session
+  token) are rejected: provider secrets are baked into the deployed gateway, so
+  a credential that expires in hours would break the gateway between redeploys.
+- Two IAM permissions on the models you plan to call, in that region:
+  `bedrock:InvokeModel` and `bedrock:InvokeModelWithResponseStream`. That's the
+  whole list—`bedrock:Converse` and `bedrock:ConverseStream` aren't IAM actions,
+  and the Converse operations are authorized by the InvokeModel pair.
+- An AI Gateway project in the Zuplo Portal, and an [app](./apps.mdx) to call
+  from. The app page shows its API URL, and its API key lives on the app's **API
+  Key** tab.
+
+## Add the provider
+
+Adding or editing providers requires the **Edit** permission, granted to Zuplo
+account and project **Admins**—see
+[Managing Providers](./managing-providers.mdx).
+
+<Stepper>
+
+1. Open
+   [**Settings → AI Providers**](https://portal.zuplo.com/+/account/project/ai/settings/data-models)
+   in your AI Gateway project in the Zuplo Portal.
+
+1. Click the **Add Provider** button.
+
+1. In the **AI Provider** list, select **Bedrock Runtime**.
+
+1. Review the **Provider Name**, which fills in as `bedrockruntime`. You can
+   replace it with your own name, but only now—the name is permanent after
+   creation, and it's the prefix in every model reference.
+
+1. In **AWS Region**, enter the lowercase code of the region you use Bedrock in,
+   such as `us-east-1`. The gateway sends this provider's requests to
+   `https://bedrock-runtime.<region>.amazonaws.com`—the standard endpoint
+   family, not the FIPS or dual-stack ones. Regions in the China partition
+   (`cn-`) aren't supported.
+
+1. In **Access Key ID**, enter the key ID, which starts with `AKIA`. In **Secret
+   Access Key**, enter the secret. AWS shows the secret only once, when the key
+   is created.
+
+1. Select the models to enable, then click **Create**.
+
+</Stepper>
+
+:::note
+
+Saving provider settings triggers an automatic production deployment of your
+gateway, because provider credentials are part of the deployed gateway. The
+change is live once the deployment completes.
+
+:::
+
+## Point your AWS SDK at the gateway
+
+Two configuration changes, and **both are required**:
+
+1. Set `endpoint` to your app's API URL.
+2. Make the client send the app's API key as a bearer token.
+
+The second one matters more than it looks. An existing client usually has AWS
+credentials available—in the environment, in a shared profile, or from an
+instance role—and the SDK signs with SigV4 whenever it finds any. It would then
+never send your gateway key, and the request would fail with a `401`. Setting
+the auth scheme explicitly is what prevents that.
+
+```ts
+import {
+  BedrockRuntimeClient,
+  ConverseCommand,
+} from "@aws-sdk/client-bedrock-runtime";
+
+const apiKey = process.env.ZUPLO_APP_API_KEY;
+if (!apiKey) {
+  throw new Error("Set ZUPLO_APP_API_KEY to your app's API key.");
+}
+
+const client = new BedrockRuntimeClient({
+  region: "us-east-1",
+  // Your app's API URL—no /v1, no trailing path.
+  endpoint:
+    "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e",
+  // Send the app's API key as a bearer token instead of signing with SigV4.
+  authSchemePreference: ["httpBearerAuth"],
+  // `token` requires a string, so the check above is what makes this compile.
+  token: { token: apiKey },
+});
+
+// Unchanged from here down.
+const response = await client.send(
+  new ConverseCommand({
+    modelId: "bedrockruntime/us.anthropic.claude-haiku-4-5-20251001-v1:0",
+    messages: [{ role: "user", content: [{ text: "Say hi" }] }],
+  }),
+);
+```
+
+Any AWS SDK that supports bearer-token authentication for Bedrock works the same
+way—set the endpoint, supply the token, and make sure the client prefers bearer
+auth over SigV4. Bearer-token support arrived in AWS SDK for JavaScript 3.840,
+boto3 1.39, AWS SDK for Go 1.35, and AWS SDK for Java 2.31.74; use those
+versions or later.
+
+The gateway is the credential boundary: your client never holds AWS credentials,
+and the gateway signs the upstream request with the IAM key pair you configured.
+
+## Model references
+
+Apps reference models as `providerName/modelId`, where `providerName` is the
+name you gave the provider configuration:
+
+```
+bedrockruntime/us.anthropic.claude-haiku-4-5-20251001-v1:0
+```
+
+The gateway strips its own prefix and sends AWS the model ID exactly as you
+wrote it, so **anything Bedrock accepts works**—published model IDs,
+cross-region inference profiles, and provisioned-throughput ARNs alike.
+
+:::tip{title="Many models need an inference profile ID"}
+
+Bedrock refuses a bare model ID for models it serves only through cross-region
+inference:
+
+```
+ValidationException: Invocation of model ID
+anthropic.claude-haiku-4-5-20251001-v1:0 with on-demand throughput isn't
+supported. Retry your request with the ID or ARN of an inference profile that
+contains this model.
+```
+
+Use the inference profile ID—usually the model ID with a regional prefix such as
+`us.`, `eu.`, or `apac.`. AWS lists them under
+[Supported Regions and models for inference profiles](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html).
+
+:::
+
+## Pricing and budgets
+
+The gateway prices Bedrock Runtime requests from the model catalog by exact
+model ID, the same as every other provider. Cross-region inference profiles are
+priced too: the `us.`, `eu.`, `apac.`, `au.`, and `global.` IDs are catalog rows
+in their own right. A model with no catalog row, such as a
+provisioned-throughput ARN or an inference profile AWS added after the catalog,
+is still served and still counts toward token and request
+[budgets](./usage-limits.mdx), but is priced at zero. It doesn't count toward
+spending budgets, and its response carries no `X-Cost-USD` header.
+
+When a budget is exhausted, these routes answer
+`400 ServiceQuotaExceededException`—not the `429` the Universal API returns. AWS
+SDKs treat any `429` as throttling and retry it, and a spent budget doesn't
+refill between retries, so the gateway uses the status Bedrock itself uses for
+an exhausted quota. Your client sees the refusal immediately instead of retrying
+into it.
+
+## Policies on Bedrock Runtime routes
+
+These routes run your app's [policy chain](./policy-chains.mdx) like any other.
+What changes is that the request body is Bedrock's shape rather than one the
+gateway parses, so a policy that reads the body applies its `onUnknownShape`
+setting instead. Each policy's default follows from its job: a guardrail fails
+closed, while an observer or an optimization fails open.
+
+| Policy                                                                                                                        | On Bedrock Runtime routes                                                                                                                              |
+| ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [Authentication](../policies/ai-gateway-auth-v2-inbound.mdx)                                                                  | Works. Reads the app key from `Authorization: Bearer`                                                                                                  |
+| [Model Filtering](../policies/ai-gateway-model-filtering-v2-inbound.mdx)                                                      | Works. Refuses a model outside the allow list before any AWS call                                                                                      |
+| [Metering and budgets](../policies/ai-gateway-metering-v2-inbound.mdx)                                                        | Works. Meters tokens and cost on all four operations, streamed or not                                                                                  |
+| [DLP](../policies/ai-gateway-dlp-inbound.mdx) and content guardrails                                                          | **Blocks by default.** The gateway can't read these bodies, so the policy denies the request. Set `onUnknownShape` to `skip` to forward it uninspected |
+| [Galileo](../policies/galileo-tracing-v2-inbound.mdx) and [Comet Opik](../policies/comet-opik-tracing-v2-inbound.mdx) tracing | **Skipped by default.** The request goes through untraced. Set `onUnknownShape` to `deny` to make a trace a hard requirement                           |
+| Semantic Cache                                                                                                                | Skipped                                                                                                                                                |
+
+The table lists every policy the gateway supports on these routes. It audits the
+chain and refuses any other policy, such as a custom policy, Smart Router, or
+[Fallback Model](./fallback.mdx), with a `400 ValidationException` that names
+the policy. Remove it from the chain to use Bedrock Runtime through that app.
+
+If you need content inspection on Bedrock traffic, use
+[Bedrock's own guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html)
+through `guardrailConfig` in the request body—the gateway forwards it untouched.
+
+Errors the gateway raises on these routes carry an `x-amzn-ErrorType` header, so
+your SDK surfaces them as typed exceptions rather than as deserialization
+failures.
+
+## Troubleshooting
+
+**Every request returns `401`.** The client is signing with SigV4 instead of
+sending the app's API key. Set `authSchemePreference` (or your SDK's equivalent)
+to prefer bearer authentication, and confirm the token is the app's API key from
+the app's **API Key** tab.
+
+**`ValidationException` about on-demand throughput.** The model needs a
+cross-region inference profile ID rather than the bare model ID—see
+[Model references](#model-references).
+
+**`403` from AWS that reads like a bad key.** Check that the IAM user has
+`bedrock:InvokeModel` and `bedrock:InvokeModelWithResponseStream` on that model
+_in the provider's region_, and that the model is enabled for your AWS account.
+
+**The provider dialog rejects your key pair.** An access key ID starting with
+`ASIA` is a temporary credential and is refused on purpose—it would expire while
+baked into the deployed gateway. The dialog also rejects an access key ID that
+isn't 16 to 128 uppercase letters and digits, a secret containing spaces or line
+breaks, and either field filled in without the other.
+
+**A `400` naming the supported operations.** You called `CountTokens` or
+`InvokeModelWithBidirectionalStream`, which the gateway doesn't serve.
+
+**`ServiceQuotaExceededException` you can't find in AWS.** It's a Zuplo budget,
+not an AWS service quota. An exhausted [budget](./usage-limits.mdx) refuses
+these routes with that exception—check the app's usage limits before you open a
+quota ticket with AWS.
+
+**Your app's model list is empty of Bedrock models.** Expected—Bedrock Runtime
+models don't appear in `GET /v1/models`, because model IDs here are open-ended
+(inference profiles and ARNs are valid and aren't catalog entries).
+
+## Next steps
+
+- [AI Providers](./providers.mdx)—the capability matrix across every supported
+  provider.
+- [Using Bedrock Mantle](./bedrock-mantle.mdx)—the other Amazon Bedrock
+  provider, for OpenAI- and Anthropic-shaped clients.
+- [Managing Providers](./managing-providers.mdx)—edit models, keys, and the
+  region, and understand when changes deploy.
+- [AI Gateway Apps](./apps.mdx)—create the apps that call your models.
+- [Model Filtering policy](../policies/ai-gateway-model-filtering-v2-inbound.mdx)—control
+  which models each app can call.

package/docs/ai-gateway/providers.mdx

@@ -23,6 +23,8 @@ Zuplo currently supports the following AI providers:
   serving Claude and every Foundry model family from your own Azure subscription
 - [Bedrock Mantle](./bedrock-mantle.mdx)—Amazon Bedrock's compatible-APIs
   endpoint, serving Claude models and models from many other vendors
+- [Bedrock Runtime](./bedrock-runtime.mdx)—Amazon Bedrock's native API, for code
+  that already calls Bedrock with an AWS SDK
 - [Vertex AI](./vertex-ai.mdx)—Google Cloud's managed model platform, serving
   Gemini and Model Garden models on your own Google Cloud project
 - [Zuplo Demo](#zuplo-demo)—a free, keyless provider for trying the gateway
@@ -40,6 +42,7 @@ The following capabilities are supported across providers:
 | xAI                        | ✅               | ✅         | ❌        | ❌       |
 | Azure AI                   | ✅               | ✅         | ✅        | ✅       |
 | Bedrock Mantle             | ✅               | ❌         | ✅        | ✅       |
+| Bedrock Runtime            | ❌               | ❌         | ❌        | ❌       |
 | Vertex AI                  | ✅               | ✅         | ❌        | ✅       |
 | Zuplo Demo                 | ✅               | ❌         | ❌        | ❌       |
 | OpenAI-compatible (Custom) | ✅               | ✅         | ❌        | ❌       |
@@ -54,6 +57,13 @@ Messages (plus chat completions through translation), while its other models
 serve chat completions and—per model—Responses. See
 [Using Bedrock Mantle](./bedrock-mantle.mdx#supported-endpoints-by-model-family).
 
+Bedrock Runtime is the one provider with no Universal API capabilities, and the
+table above says so. It serves Amazon Bedrock's **native** API instead, at its
+own paths, so your existing AWS SDK code keeps working with the gateway in front
+of it. See [Using Bedrock Runtime](./bedrock-runtime.mdx#supported-operations)
+for the operations it serves, and add Bedrock Mantle alongside it if you also
+want Bedrock models on the Universal API.
+
 Azure AI's capabilities split by model family, and within the OpenAI-compatible
 family they split per deployed model: a chat model serves chat completions and—
 per model and version—Responses, while an embedding model serves embeddings and
@@ -119,6 +129,26 @@ instead of an endpoint URL, and it accepts only long-term Bedrock API keys,
 which start with `ABSK`. For prerequisites, setup steps, code examples, and
 troubleshooting, see [Using Bedrock Mantle](./bedrock-mantle.mdx).
 
+## Bedrock Runtime
+
+**Bedrock Runtime** is Amazon Bedrock's native API—the one the AWS SDKs call.
+Unlike every other provider, it doesn't serve the
+[Universal API](./universal-api.mdx): it serves Bedrock's own operations
+(`Converse`, `ConverseStream`, `InvokeModel`, and
+`InvokeModelWithResponseStream`) at Bedrock's own paths.
+
+That makes it the provider to choose when you already have code calling Bedrock
+with an AWS SDK. You point the client's endpoint at your app and give it the
+app's API key; every call site stays as it is, and the gateway adds
+authentication, model filtering, and usage metering in front of your own AWS
+account.
+
+It authenticates to AWS with a long-term IAM access key pair rather than a
+Bedrock API key, so it needs its own provider configuration even if you also use
+Bedrock Mantle on the same account. For prerequisites, setup steps, code
+examples, and troubleshooting, see
+[Using Bedrock Runtime](./bedrock-runtime.mdx).
+
 ## Vertex AI
 
 **Vertex AI** is Google Cloud's managed model platform. One provider

package/docs/ai-gateway/universal-api.mdx

@@ -69,3 +69,33 @@ list—so clients that can't set a model still work.
 | `/v1/embeddings`       | Embeddings for the providers marked in the [capability matrix](./providers.mdx#supported-providers)                                                             |
 | `/v1/responses`        | OpenAI Responses API: OpenAI, and the OpenAI-compatible models that serve it on [Azure AI](./azure-ai.mdx) and [Bedrock Mantle](./bedrock-mantle.mdx)           |
 | `/v1/messages`         | Anthropic Messages API: Anthropic, and the Claude models of [Azure AI](./azure-ai.mdx), [Bedrock Mantle](./bedrock-mantle.mdx) and [Vertex AI](./vertex-ai.mdx) |
+
+## Request headers
+
+The gateway forwards your request headers to the provider. A header your client
+or your own policies set—a session ID, a trace header, a feature flag—arrives
+with the request.
+
+The gateway removes what it owns first:
+
+| Removed                                                                                         | Why                                                                                                                                   |
+| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `authorization`, `x-api-key`, `api-key`, `proxy-authorization`, and cookies                     | Credentials addressed to the gateway. The provider gets its own credential from your provider configuration instead.                  |
+| `content-type`, `accept`, `anthropic-version`, `anthropic-beta`                                 | The gateway controls the wire format it sends upstream, which isn't always the one your client asked for.                             |
+| `openai-organization`, `openai-project`, `x-goog-api-key`, `x-goog-user-project`                | Another vendor's credentials and tenant selectors. They cause a `401` as soon as a request routes to a provider they don't belong to. |
+| `host`, `connection`, `transfer-encoding`, `content-length`, and the rest of the hop-by-hop set | They describe the connection to the gateway, not the one to the provider.                                                             |
+| `cdn-loop`, and anything starting with `zp-`, `cf-`, or `x-amz-`                                | They describe the path your request took to reach the gateway.                                                                        |
+
+Everything else reaches the provider, including `user-agent`, `x-forwarded-for`,
+`true-client-ip`, `idempotency-key`, `x-request-id`, and the `x-stainless-*`
+headers the OpenAI and Anthropic SDKs set.
+
+To change what the provider receives, add a header policy—`set-headers-inbound`,
+`remove-headers-inbound`, or `clear-headers-inbound`—to the app's
+[policy chain](./policy-chains.mdx). Headers are copied after the chain runs, so
+a policy that adds one puts it on the provider request too. Setting
+`Authorization`, `x-api-key`, or `api-key` in a policy doesn't override the
+credential from your provider configuration.
+
+[Bedrock Runtime](./bedrock-runtime.mdx) isn't part of the Universal API and
+forwards a different set, described on its own page.

package/docs/ai-gateway/usage-limits.mdx

@@ -228,6 +228,40 @@ the top of the hour. Every distinct `x-organization` value gets its own $50 per
 day, resetting at 00:00 UTC. The `app` rule caps the whole app at $2,500 per
 month, warning at $2,000, resetting on the first of the month.
 
+### Checking what a rule resolved to
+
+A **By metadata** rule whose expression resolves to nothing budgets nothing, and
+the request still succeeds. A rule that silently does nothing therefore looks
+exactly like a rule that's working. Your gateway's request logs say which it is.
+
+Every request that runs at least one **By metadata** rule logs
+`AI Gateway budget dimensions resolved`, listing the rules that resolved and the
+rules that didn't. Each rule that didn't carries a reason:
+
+| Reason                                        | What to change                                                                                                                                                           |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `no-such-property`                            | The expression is valid but found no value. The message names the property that broke the chain—check that the header or claim is really on the request.                 |
+| `invalid-syntax`                              | The expression is outside the grammar. The message gives the position of the problem.                                                                                    |
+| `per-request-identifier`                      | The value is unique to every request, so no two requests share a budget and no threshold is ever reached. Key on something that repeats, like a user or an organization. |
+| `internal-field`                              | The value comes from a field the proxy populates, such as client certificate material.                                                                                   |
+| `value-not-scalar` / `value-not-safe-integer` | The value isn't a string or a whole number.                                                                                                                              |
+| `value-too-long`                              | The value is longer than 256 bytes.                                                                                                                                      |
+| `value-has-control-characters`                | The value contains control characters.                                                                                                                                   |
+
+Resolved entries record the length of each value, not the value itself. A rule
+whose expression names a credential—anything whose text contains `token`,
+`secret`, `authorization`, `password`, `cookie`, `credential`, `bearer`, or
+`api_key` in any spelling—never logs its value at all. Budgeting per API key is
+a reasonable thing to do, and the key stays out of the log.
+
+A rule that can never work, because its expression is unusable or the rule fails
+validation, also logs a warning. Those warnings arrive once per configuration
+rather than once per request, so a broken rule doesn't flood the log.
+
+Verdicts name their rule too. A block or warning from a **By metadata** rule
+carries the expression and its `ruleId`; one from an app-wide budget carries
+neither. That's how you tell which rule refused a request.
+
 ## Setting team and gateway limits
 
 A team budget covers the combined usage of its apps and sub-teams. A gateway

package/docs/dev-portal/zudoku/components/stepper.mdx

@@ -41,7 +41,7 @@ Wrap Markdown lists with the `Stepper` component to create a vertical stepper li
   </div>
   <div className="flex-1">
 
-    <Stepper>
+    <Stepper toc={false}>
 
 1. **Identify the Problem**
 1. **Plan Your Project**
@@ -52,6 +52,39 @@ Wrap Markdown lists with the `Stepper` component to create a vertical stepper li
   </div>
 </div>
 
+## Table of Contents
+
+Steps are anchorable and show up in the "On this page" sidebar, nested one level below the heading
+they follow:
+
+| Stepper placed after…                 | Steps appear as…                                |
+| ------------------------------------- | ----------------------------------------------- |
+| The page title (or no heading at all) | Top-level entries                               |
+| An `h2`                               | Sub-entries of that `h2`                        |
+| An `h3` or deeper                     | Nothing — the same cut-off an `h4` heading hits |
+
+That means a page that is nothing but a stepper (a tutorial, for example) gets a usable table of
+contents automatically, while a stepper buried inside an existing section doesn't flood it.
+
+Each step's title — the first line of the list item — becomes the entry. A step whose first block
+isn't text (a code block, for instance) is skipped.
+
+### Opting out
+
+Set `toc={false}` for a stepper that is a quick checklist rather than a section of the page worth
+linking to:
+
+<!-- prettier-ignore -->
+```tsx
+<Stepper toc={false}>
+
+1. **Find the reason code**
+1. **Look up the code**
+1. **Re-file**
+
+</Stepper>
+```
+
 ## Advanced Example
 
 <Stepper>

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

@@ -112,6 +112,10 @@ dist/
     └── ...
 ```
 
+::if{mode=opensource}
+
+::
+
 **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.

package/docs/policies/ai-gateway-auth-v2-inbound/doc.md

@@ -1,5 +1,3 @@
-# AI Gateway Authentication
-
 The AI Gateway Authentication policy authenticates requests with an AI Gateway
 application API key. After a key is accepted, the calling application is
 identified on `request.user` — `sub` is the application name and `data` its
@@ -114,6 +112,11 @@ curl https://gateway.example.com/v1/chat/completions \
 Authentication scheme matching is case-insensitive. A missing key, an invalid
 scheme, or a key that is not authorized receives a `401 Unauthorized` response.
 
+Once the key is accepted, the policy removes the `authHeader` header from the
+request. The application key never reaches an upstream provider or a policy
+later in the chain, whatever header name it arrived in. Read the caller's
+identity from `request.user` instead.
+
 ## Use a custom header
 
 Set `authHeader` to accept the key from another header. Set `authScheme` to an

package/docs/policies/ai-gateway-configuration-executor-v2-inbound/doc.md

@@ -1,5 +1,3 @@
-# AI Gateway Configuration Executor
-
 The AI Gateway Configuration Executor loads each application's configuration
 (when auth or `ai-gateway-configuration-loader-v2-inbound` has not already) and
 runs its ordered inbound policy chain. Configuration comes from route-level
@@ -408,6 +406,32 @@ The corresponding expression is `request.headers.get("x-budget-customer")`.
 Configuration code should create that ordinary string and pass the enclosing
 object to `JSON.stringify`; the serializer adds the JSON transport escaping.
 
+Headers you set or remove in the inbound chain control what reaches your AI
+provider. For example, you can add a session header or remove an internal
+customer header before sending the request. Gateway-owned headers are excluded,
+including credentials, `Content-Type`, `Accept`, and headers starting with `zp-`
+or `cf-`; setting a credential header does not override your configured provider
+credential.
+
+That includes headers you add only for the gateway's own use. The
+`x-budget-customer` header above carries the caller's user id, and unless you
+remove it after the metering policy has read it, the provider receives it on
+every request. Add a `remove-headers-inbound` entry after the metering entry:
+
+```json
+[
+  { "name": "set-budget-dimension" },
+  { "name": "ai-gateway-metering-v2-inbound" },
+  {
+    "name": "remove-headers-inbound",
+    "options": { "headers": ["x-budget-customer"] }
+  }
+]
+```
+
+Declare `remove-headers-inbound` in `config/policies.json` so the chain can
+select it.
+
 Invalid budget rules and unsupported expressions are logged and skipped. Other
 valid rules continue to apply.
 

package/docs/policies/ai-gateway-configuration-loader-v2-inbound/doc.md

@@ -1,5 +1,3 @@
-# AI Gateway Configuration Loader
-
 The AI Gateway Configuration Loader loads each application's configuration into
 the request-scoped app-configuration channel. Configuration comes from
 route-level `ai-gateway-auth-v2-inbound` when that policy already ran, otherwise

package/docs/policies/ai-gateway-dlp-inbound/schema.json

@@ -43,16 +43,28 @@
                   "pii": {
                     "action": "mask"
                   },
-                  "secret": {
-                    "action": "block"
+                  "contact-email": {
+                    "action": "off"
+                  },
+                  "finance-credit-card": {
+                    "action": "mask"
+                  },
+                  "finance-iban": {
+                    "action": "mask"
                   }
                 },
                 "outbound": {
                   "pii": {
-                    "action": "block"
+                    "action": "mask"
                   },
-                  "secret": {
-                    "action": "block"
+                  "contact-email": {
+                    "action": "off"
+                  },
+                  "finance-credit-card": {
+                    "action": "mask"
+                  },
+                  "finance-iban": {
+                    "action": "mask"
                   }
                 }
               }
@@ -6349,16 +6361,28 @@
                 "pii": {
                   "action": "mask"
                 },
-                "secret": {
-                  "action": "block"
+                "contact-email": {
+                  "action": "off"
+                },
+                "finance-credit-card": {
+                  "action": "mask"
+                },
+                "finance-iban": {
+                  "action": "mask"
                 }
               },
               "outbound": {
                 "pii": {
-                  "action": "block"
+                  "action": "mask"
                 },
-                "secret": {
-                  "action": "block"
+                "contact-email": {
+                  "action": "off"
+                },
+                "finance-credit-card": {
+                  "action": "mask"
+                },
+                "finance-iban": {
+                  "action": "mask"
                 }
               }
             }

package/docs/policies/ai-gateway-fallback-model-v2-inbound/doc.md

@@ -1,5 +1,3 @@
-# AI Gateway Fallback Model
-
 Use this policy to add resilience to a model selection created by Model
 Filtering or a custom routing policy. Place it after Model Filtering:
 

package/docs/policies/ai-gateway-metering-v2-inbound/doc.md

@@ -1,5 +1,3 @@
-# AI Gateway Metering
-
 AI Gateway Metering records application usage and configures the app's own
 budgets before the provider request runs. It meters spend, tokens, and requests.
 Budget rules can cover the whole application or each distinct value of an

package/docs/policies/ai-gateway-model-filtering-v2-inbound/doc.md

@@ -1,5 +1,3 @@
-# AI Gateway Model Filtering
-
 Use this policy when an AI Gateway route must restrict which models clients may
 select. Without it, an application can use any available model from the
 providers configured for the Zuplo project. The policy is optional.

package/docs/policies/ai-gateway-semantic-cache-v2-inbound/doc.md

@@ -1,5 +1,3 @@
-# AI Gateway Semantic Cache
-
 AI Gateway Semantic Cache answers a request from a previous response when the
 new prompt is semantically similar to one already seen. A hit skips the provider
 call. One inbound policy handles both directions: it checks the cache on the way

package/docs/policies/ai-gateway-smart-router-inbound/doc.md

@@ -1,5 +1,3 @@
-# AI Gateway Smart Router
-
 Use this policy to classify the last user prompt on Chat Completions, Responses,
 and Anthropic Messages requests. Using the classification results, configure
 where to route the request based on its complexity.
@@ -268,3 +266,10 @@ Invalid options, classifier timeouts, empty classifier responses, and smart
 routing catalog errors are logged and the original request continues. Chat
 Completions, Responses, and Anthropic Messages are classified automatically.
 Embeddings and other non-AI paths are skipped.
+
+One shape is refused rather than skipped. A Bedrock Runtime request
+(`/model/{modelId}/{operation}`) carries a model-native body that the gateway
+does not parse, so there is no prompt to classify, and letting it continue would
+present your routing as in effect when it was not. The policy answers a
+`400 ValidationException` in the AWS error envelope, naming the policy. Remove
+the policy from that route to use Bedrock Runtime through it.

package/docs/policies/akamai-ai-firewall-v2-inbound/doc.md

@@ -1,5 +1,3 @@
-# Akamai AI Firewall
-
 The Akamai AI Firewall policy sends prompts and completions to
 [Akamai Firewall for AI](https://www.akamai.com/products/firewall-for-ai) and
 blocks content that your Akamai configuration denies. One inbound policy covers

package/docs/policies/auth0-jwt-auth-inbound/doc.md

@@ -111,7 +111,7 @@ is working as expected.
 
 You have now set up Auth0 JWT Authentication on your API Gateway.
 
-## OAuth 2.0 Protected Resource Metadata
+### OAuth 2.0 Protected Resource Metadata
 
 The Auth0 JWT Auth policy supports OAuth protected resource metadata discovery.
 To enable this feature, set the `oAuthResourceMetadataEnabled` option to `true`

package/docs/policies/comet-opik-tracing-v2-inbound/doc.md

@@ -1,5 +1,3 @@
-# Comet Opik Tracing
-
 The Comet Opik Tracing policy integrates
 [Comet Opik](https://www.comet.com/docs/opik/) with the AI Gateway. It captures
 LLM inputs, outputs, model information, token usage, request metadata, and

package/docs/policies/galileo-tracing-v2-inbound/doc.md

@@ -1,5 +1,3 @@
-# Galileo Tracing
-
 The Galileo Tracing policy integrates [Galileo](https://www.galileo.ai/) with
 the AI Gateway. It automatically records LLM inputs, outputs, model information,
 token usage, request metadata, and timing so you can debug applications and

package/docs/policies/mcp-auth0-oauth-inbound/doc.md

@@ -1,5 +1,3 @@
-# MCP Auth0 OAuth Inbound
-
 Authenticate MCP gateway requests using a gateway-issued OAuth access token,
 with browser login delegated to Auth0.
 

package/docs/policies/mcp-auth0-oauth-inbound/schema.json

@@ -52,7 +52,7 @@
             },
             "clientSecret": {
               "type": "string",
-              "examples": ["$env(MCP_AUTH0_CLIENT_SECRET)"],
+              "examples": ["$env(AUTH0_CLIENT_SECRET)"],
               "description": "The Auth0 client\\_secret. Use $env(...) to source from a secret environment variable."
             },
             "scope": {
@@ -209,7 +209,7 @@
               "sessionTtlSeconds": 28800,
               "stateTtlSeconds": 900
             },
-            "clientSecret": "$env(MCP_AUTH0_CLIENT_SECRET)",
+            "clientSecret": "$env(AUTH0_CLIENT_SECRET)",
             "gateway": {
               "accessTokenTtlSeconds": 900,
               "cimdEnabled": true,

package/docs/policies/mcp-clerk-oauth-inbound/doc.md

@@ -1,5 +1,3 @@
-# MCP Clerk OAuth
-
 Authenticates MCP clients with gateway-issued OAuth tokens and delegates browser
 login to a Clerk OAuth application.
 

package/docs/policies/mcp-cognito-oauth-inbound/doc.md

@@ -1,5 +1,3 @@
-# MCP Amazon Cognito OAuth Inbound
-
 Authenticate MCP gateway requests using a gateway-issued OAuth access token,
 with browser login delegated to Amazon Cognito.
 

package/docs/policies/mcp-entra-oauth-inbound/doc.md

@@ -1,5 +1,3 @@
-# MCP Microsoft Entra OAuth Inbound
-
 Authenticate MCP gateway requests using a gateway-issued OAuth access token,
 with browser login delegated to Microsoft Entra ID.
 

package/docs/policies/mcp-google-oauth-inbound/doc.md

@@ -1,5 +1,3 @@
-# MCP Google OAuth Inbound
-
 Authenticate MCP gateway requests using a gateway-issued OAuth access token,
 with browser login delegated to Google.
 

package/docs/policies/mcp-keycloak-oauth-inbound/doc.md

@@ -1,5 +1,3 @@
-# MCP Keycloak OAuth
-
 The MCP Keycloak OAuth policy is a provider-specific wrapper around the generic
 MCP OAuth inbound policy. It keeps the gateway OAuth behavior the same, but lets
 you configure Keycloak with the values an administrator normally has:

package/docs/policies/mcp-logto-oauth-inbound/doc.md

@@ -1,5 +1,3 @@
-# MCP Logto OAuth Inbound
-
 Authenticate MCP gateway requests using a gateway-issued OAuth access token,
 with browser login delegated to Logto.
 

package/docs/policies/mcp-oauth-inbound/doc.md

@@ -1,5 +1,3 @@
-# MCP OAuth Inbound
-
 Authenticate MCP gateway requests using a gateway-issued OAuth access token.
 
 ## How it works

package/docs/policies/mcp-oauth-inbound/schema.json

@@ -73,7 +73,7 @@
                   "type": "string",
                   "format": "uri",
                   "examples": ["https://my-tenant.us.auth0.com/authorize"],
-                  "description": "The IdP /authorize endpoint to redirect the user to. For local development on loopback, use http://127.0.0.1:9000/oauth/dev-login."
+                  "description": "The IdP /authorize endpoint to redirect the user to. For local development on loopback, use http://127.0.0.1:9000/\\_\\_zuplo/oauth/dev-login (the gateway's default basePath is /\\_\\_zuplo; adjust if the plugin is configured with a different one)."
                 },
                 "tokenUrl": {
                   "type": "string",

package/docs/policies/mcp-okta-oauth-inbound/doc.md

@@ -1,5 +1,3 @@
-# MCP Okta OAuth Inbound
-
 Authenticate MCP gateway requests using a gateway-issued OAuth access token,
 with browser login delegated to Okta.
 

package/docs/policies/mcp-onelogin-oauth-inbound/doc.md

@@ -1,5 +1,3 @@
-# MCP OneLogin OAuth Inbound
-
 Authenticate MCP gateway requests using a gateway-issued OAuth access token,
 with browser login delegated to OneLogin.
 

package/docs/policies/mcp-ping-oauth-inbound/doc.md

@@ -1,5 +1,3 @@
-# MCP Ping OAuth Inbound
-
 Authenticate MCP gateway requests using a gateway-issued OAuth access token,
 with browser login delegated to PingOne.
 

package/docs/policies/mcp-token-exchange-inbound/doc.md

@@ -108,6 +108,52 @@ as Entra tenant admin consent. If connections start requiring frequent
 reauthorization after setting `prompt: false`, remove the option so the consent
 grant is requested again.
 
+## Authorization Server Issuer Mismatch
+
+Some providers publish inconsistent OAuth metadata: the protected-resource
+document advertises a path-scoped authorization server, but that server's own
+metadata reports a different (usually root-origin) `issuer`. ServiceNow is one —
+its protected-resource metadata names
+`https://<instance>.service-now.com/sncapps/...` while the metadata served there
+reports `https://<instance>.service-now.com`. Atlassian and Okta
+org-versus-custom authorization servers publish the same shape.
+
+RFC 8414 section 3.3 requires a client to reject a metadata document whose
+`issuer` differs from the identifier the well-known URL was built from, so the
+gateway hard-fails discovery against these providers. Set
+`skipIssuerMetadataValidation` to `true` on that connection to proceed anyway:
+
+```json
+{
+  "name": "mcp-token-exchange-servicenow",
+  "policyType": "mcp-token-exchange-inbound",
+  "handler": {
+    "module": "$import(@zuplo/runtime/mcp-gateway)",
+    "export": "McpTokenExchangeInboundPolicy",
+    "options": {
+      "displayName": "ServiceNow",
+      "authMode": "user-oauth",
+      "skipIssuerMetadataValidation": true
+    }
+  }
+}
+```
+
+**Warning**: this puts the connection out of spec. The issuer check is an
+unqualified MUST in both RFC 8414 section 3.3 and the MCP authorization spec,
+whose own example is the attack it prevents — a document served from
+`https://attacker.example/.well-known/oauth-authorization-server` claiming
+`"issuer": "https://honest.example"` must be rejected. The check binds the
+metadata to the TLS-authenticated host it came from, and with it off the gateway
+trusts the authorization, token and JWKS endpoints from a document that never
+proved it speaks for that issuer.
+
+Only enable it for a specific upstream known to publish a mismatched issuer, and
+only when the metadata URL's host is itself trusted. Never enable it as a
+default. It relaxes the discovery-time check only: the RFC 9207
+authorization-response check and the callback-leg authorization-server binding
+still apply.
+
 ## ID-JAG Token Exchange (Cross-App Access)
 
 Set `authMode` to `id-jag` when the upstream is protected by an Identity
@@ -128,8 +174,8 @@ Use this mode in enterprise deployments where the gateway and the upstream trust
 the same identity provider (for example, Okta Cross-App Access), so upstream
 access follows the caller's identity without a per-user upstream consent flow.
 The `user-oauth`/`shared-oauth` options — `scopes`, `scopeDelimiter`, `prompt`,
-and `clientRegistration` — do not apply; the `id-jag` mode is configured
-entirely through the `idJag` option.
+`skipIssuerMetadataValidation`, and `clientRegistration` — do not apply; the
+`id-jag` mode is configured entirely through the `idJag` option.
 
 ```json
 {

package/docs/policies/mcp-token-exchange-inbound/schema.json

@@ -56,6 +56,9 @@
                 {
                   "required": ["prompt"]
                 },
+                {
+                  "required": ["skipIssuerMetadataValidation"]
+                },
                 {
                   "required": ["clientRegistration"]
                 }
@@ -120,6 +123,11 @@
                 }
               ]
             },
+            "skipIssuerMetadataValidation": {
+              "type": "boolean",
+              "x-advanced": true,
+              "description": "Skips the RFC 8414 section 3.3 issuer-echo check when discovering the upstream authorization server. That check requires the `issuer` in the authorization server's metadata to equal the `authorization_servers` entry the protected-resource metadata advertised. Some providers publish a path-scoped authorization server whose metadata reports the root origin instead — for example ServiceNow advertises `https://<instance>.service-now.com/sncapps/...` but its metadata reports `https://<instance>.service-now.com` — so discovery hard-fails without this option. Warning: enabling this puts the connection out of spec. The check is an unqualified MUST in both RFC 8414 section 3.3 and the MCP authorization spec, which require rejecting a metadata document whose `issuer` differs from the identifier the well-known URL was built from; the spec's own example is a document served from `https://attacker.example/.well-known/oauth-authorization-server` claiming `\"issuer\": \"https://honest.example\"`. The echo check binds the metadata to the TLS-authenticated host it came from, and with it off the gateway trusts the authorization, token and JWKS endpoints from a document that never proved it speaks for that issuer. Only enable it for a specific upstream known to publish a mismatched issuer, and only when the metadata URL's host is itself trusted. It relaxes the discovery-time check only — the RFC 9207 authorization-response check and the callback-leg authorization-server binding still apply."
+            },
             "clientRegistration": {
               "x-advanced": true,
               "description": "OAuth client registration mode. Defaults to `auto`, which uses Client ID Metadata Documents when the upstream advertises support and falls back to Dynamic Client Registration otherwise.",

package/docs/policies/mcp-workos-oauth-inbound/doc.md

@@ -1,5 +1,3 @@
-# MCP WorkOS OAuth Inbound
-
 Authenticate MCP gateway requests using a gateway-issued OAuth access token,
 with browser login delegated to WorkOS.
 

package/docs/policies/monetization-inbound/doc.md

@@ -1,5 +1,3 @@
-# Monetization Metering Policy
-
 The Monetization policy validates subscriptions and records usage. Meter usage
 is sent in a final response hook after status-code filtering.
 
@@ -9,6 +7,16 @@ is sent in a final response hook after status-code filtering.
 - `meterOnStatusCodes`: status codes/ranges that trigger metering.
 - auth/cache settings: `authHeader`, `authScheme`, `cacheTtlSeconds`.
 
+## Error responses
+
+- Missing, malformed, invalid, or expired API-key credentials return
+  `401 Unauthorized`. When `authScheme` is set, the response includes a
+  `WWW-Authenticate` challenge for that scheme. An empty `authScheme` is
+  raw-header mode: the entire header value is the key, and `WWW-Authenticate` is
+  omitted.
+- A valid API key whose subscription, payment status, or entitlements deny
+  access returns `403 Forbidden`.
+
 ### Static meter configuration
 
 ```json

package/docs/policies/propel-auth-jwt-inbound/doc.md

@@ -74,7 +74,7 @@ is working as expected.
 
 You have now setup PropelAuth JWT Authentication on your API Gateway.
 
-## OAuth 2.0 Protected Resource Metadata
+### OAuth 2.0 Protected Resource Metadata
 
 The Propel JWT Auth policy supports OAuth protected resource metadata discovery.
 To enable this feature, set the `oAuthResourceMetadataEnabled` option to `true`

package/docs/policies/secret-masking-outbound/doc.md

@@ -34,7 +34,7 @@ Apply this policy to outbound requests in your route configuration:
 }
 ```
 
-# Masked secrets
+## Masked secrets
 
 - Zuplo API keys (i.e. `zpka_xxx`)
 - GitHub Tokens and Personal Access Tokens (i.e. `ghp_xxx`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "7.7.16",
+  "version": "7.8.0",
   "type": "module",
   "description": "The official Zuplo CLI for local development and platform management",
   "homepage": "https://zuplo.com/docs/cli/overview",
@@ -32,9 +32,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "7.7.16",
-    "@zuplo/core": "7.7.16",
-    "@zuplo/runtime": "7.7.16",
-    "@zuplo/test": "7.7.16"
+    "@zuplo/cli": "7.8.0",
+    "@zuplo/core": "7.8.0",
+    "@zuplo/runtime": "7.8.0",
+    "@zuplo/test": "7.8.0"
   }
 }