zuplo 7.9.14 → 7.9.16

package/docs/policies/ai-gateway-smart-router-inbound/schema.json

@@ -61,8 +61,24 @@
             },
             {
               "classifier": {
-                "jev": {
-                  "apiKey": "$env(TYPESAFE_API_KEY)"
+                "app": {
+                  "appId": "$env(CLASSIFIER_APP_ID)",
+                  "adapter": "systemOne",
+                  "model": "jev/jev-latest"
+                }
+              },
+              "modelsByComplexity": {
+                "low": "openai/gpt-4o-mini",
+                "medium": "openai/gpt-4o",
+                "high": "openai/gpt-5"
+              }
+            },
+            {
+              "classifier": {
+                "app": {
+                  "appId": "$env(CLASSIFIER_APP_ID)",
+                  "adapter": "systemOne",
+                  "model": "jev/jev-latest"
                 }
               },
               "smartRoutingEnabled": true,
@@ -71,13 +87,27 @@
                 "medium": "openai/gpt-4o",
                 "high": "openai/gpt-5"
               }
+            },
+            {
+              "classifier": {
+                "app": {
+                  "appId": "$env(CLASSIFIER_APP_ID)",
+                  "adapter": "chatCompletions",
+                  "model": "openai/gpt-4o-mini"
+                }
+              },
+              "modelsByComplexity": {
+                "low": "openai/gpt-4o-mini",
+                "medium": "openai/gpt-4o",
+                "high": "openai/gpt-5"
+              }
             }
           ],
           "properties": {
             "classifier": {
               "type": "object",
               "title": "Classifier",
-              "description": "Where the user's prompt is classified. Required unless the deprecated `classifierAppID` and `classifierModel` are set. Set exactly one of `app`, `chatCompletions`, or `jev`; setting more than one is a configuration error.",
+              "description": "Where the prompt is classified. Set exactly one of `app`, `chatCompletions`, or `jev`. `app.adapter` selects the API that classifier app exposes. Setting more than one section is a configuration error.",
               "additionalProperties": false,
               "minProperties": 1,
               "maxProperties": 1,
@@ -98,23 +128,30 @@
                     "model": {
                       "type": "string",
                       "title": "Classifier Model",
-                      "description": "The model (`providerName/model`) the classifier app uses to evaluate the user's request. E.g. `openai/gpt-4o-mini`.",
+                      "description": "The model (`providerName/model`) the classifier app uses to evaluate the user's request. `providerName` is the name of the provider as configured on the classifier app, not a fixed vendor id. E.g. `openai/gpt-4o-mini`, or `jev/jev-latest` when the Jev provider is named `jev`.",
                       "pattern": "^[^/\\s]+/.+$",
                       "examples": ["openai/gpt-4o-mini"]
                     },
                     "apiKey": {
                       "type": "string",
                       "title": "Classifier App API Key",
-                      "description": "API key sent as `Authorization: Bearer` when invoking the classifier app. Omit it when the classifier app runs the Ensure Gateway Internal Invocation Only policy: the classifier call never leaves the gateway, so that policy accepts it and rejects everything arriving over the network, and no credential is sent. Set it only when the classifier app authenticates callers with API keys.",
+                      "description": "API key sent as `Authorization: Bearer` when invoking the classifier app. Omit it when the classifier app runs the Internal Only policy: the classifier call never leaves the gateway, so that policy accepts it and rejects everything arriving over the network, and no credential is sent. Set it only when the classifier app authenticates callers with API keys.",
                       "examples": ["$env(CLASSIFIER_APP_API_KEY)"],
                       "x-advanced": true
+                    },
+                    "adapter": {
+                      "type": "string",
+                      "enum": ["chatCompletions", "systemOne"],
+                      "default": "chatCompletions",
+                      "title": "Classifier App Adapter",
+                      "description": "API contract exposed by the classifier app. chatCompletions calls /v1/chat/completions; systemOne calls /v1/systemone for models such as Jev. The app owns provider credentials, pricing, metering and analytics."
                     }
                   }
                 },
                 "chatCompletions": {
                   "type": "object",
                   "title": "Chat Completions API",
-                  "description": "Classify by calling an OpenAI-compatible Chat Completions API directly, outside the gateway. The model must support structured outputs (`response_format` with a JSON schema).",
+                  "description": "Deprecated: use `classifier.app` instead. Classify by calling an OpenAI-compatible Chat Completions API directly, outside the gateway. The model must support structured outputs (`response_format` with a JSON schema).",
                   "additionalProperties": false,
                   "required": ["apiKey", "model"],
                   "properties": {
@@ -137,12 +174,14 @@
                       "default": "https://api.openai.com/v1",
                       "x-advanced": true
                     }
-                  }
+                  },
+                  "deprecated": true,
+                  "doNotSuggest": true
                 },
                 "jev": {
                   "type": "object",
                   "title": "Jev (TypeSafe)",
-                  "description": "Classify with Jev, TypeSafe's classification model, by calling a System One API directly: TypeSafe's by default, or another host such as OpenRouter through `baseUrl`. Jev answers typed questions instead of generating text, so it takes no `classifierPrompt`.",
+                  "description": "Deprecated: use `classifier.app` with `adapter` `systemOne` instead. Classify with Jev, TypeSafe's classification model, by calling a System One API directly: TypeSafe's by default, or another host such as OpenRouter through `baseUrl`. Jev answers typed questions instead of generating text, so it takes no `classifierPrompt`.",
                   "additionalProperties": false,
                   "required": ["apiKey"],
                   "properties": {
@@ -166,7 +205,9 @@
                       "default": "https://api.typesafe.ai",
                       "x-advanced": true
                     }
-                  }
+                  },
+                  "deprecated": true,
+                  "doNotSuggest": true
                 }
               }
             },
@@ -238,7 +279,7 @@
             },
             "classifierPrompt": {
               "title": "Classifier Prompt",
-              "description": "Prompt used to analyze and classify the user message with `classifier.app` or `classifier.chatCompletions`. Omit to use the built-in classifier prompt. Jev takes no prompt, so setting this with `classifier.jev` is a configuration error.",
+              "description": "Prompt for classifier.app (its default or chatCompletions adapter) and classifier.chatCompletions. Omit to use the built-in prompt. classifier.app.adapter systemOne and classifier.jev take no prompt; combining them with classifierPrompt is a configuration error.",
               "oneOf": [
                 {
                   "type": "string",
@@ -308,6 +349,24 @@
               "x-show-example": false,
               "x-advanced": true
             }
+          },
+          "not": {
+            "required": ["classifierPrompt", "classifier"],
+            "properties": {
+              "classifier": {
+                "required": ["app"],
+                "properties": {
+                  "app": {
+                    "required": ["adapter"],
+                    "properties": {
+                      "adapter": {
+                        "const": "systemOne"
+                      }
+                    }
+                  }
+                }
+              }
+            }
           }
         }
       },
@@ -335,8 +394,28 @@
           "module": "$import(@zuplo/runtime)",
           "options": {
             "classifier": {
-              "jev": {
-                "apiKey": "$env(TYPESAFE_API_KEY)"
+              "app": {
+                "appId": "$env(CLASSIFIER_APP_ID)",
+                "adapter": "systemOne",
+                "model": "jev/jev-latest"
+              }
+            },
+            "modelsByComplexity": {
+              "low": "openai/gpt-4o-mini",
+              "medium": "openai/gpt-4o",
+              "high": "openai/gpt-5"
+            }
+          }
+        },
+        {
+          "export": "AIGatewaySmartRouterInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "classifier": {
+              "app": {
+                "appId": "$env(CLASSIFIER_APP_ID)",
+                "adapter": "systemOne",
+                "model": "jev/jev-latest"
               }
             },
             "smartRoutingEnabled": true,
@@ -346,6 +425,24 @@
               "high": "openai/gpt-5"
             }
           }
+        },
+        {
+          "export": "AIGatewaySmartRouterInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "classifier": {
+              "app": {
+                "appId": "$env(CLASSIFIER_APP_ID)",
+                "adapter": "chatCompletions",
+                "model": "openai/gpt-4o-mini"
+              }
+            },
+            "modelsByComplexity": {
+              "low": "openai/gpt-4o-mini",
+              "medium": "openai/gpt-4o",
+              "high": "openai/gpt-5"
+            }
+          }
         }
       ]
     }

package/docs/policies/internal-only-inbound/doc.md

@@ -0,0 +1,206 @@
+Add this policy first in the inbound policies of each route that only your
+gateway calls. With no options it rejects requests from outside the gateway with
+`403 Forbidden`; set `status`, `statusText`, and `detail` to change the
+response.
+
+## How it works
+
+`context.invokeRoute` runs a route on this gateway without leaving the process,
+and the runtime marks the request it creates by setting `context.parentContext`
+to the calling request's context. Nothing else sets that property. A request
+that arrives over the network never has one, whatever headers, URL, or body it
+carries. This policy passes a request when `context.parentContext` is present
+and rejects it otherwise.
+
+| Request origin                                                                 | Result   |
+| ------------------------------------------------------------------------------ | -------- |
+| Any HTTP client, with or without credentials                                   | Rejected |
+| `context.invokeRoute` from a policy, handler, or custom module on this gateway | Passes   |
+| The MCP Server handler calling the route as a tool                             | Passes   |
+| An AI Gateway application calling another application on the same gateway      | Passes   |
+
+The policy does not authenticate the caller and does not set `request.user`.
+
+## Choose the response
+
+By default, a rejected request gets a `403 Forbidden` problem response with no
+`detail`, so the caller learns nothing about how your gateway works. The policy
+writes the reason to the request log at debug level, where you can see it and
+the caller can't.
+
+Set `status` to answer with any client error status from `400` to `499`,
+`statusText` to replace the status text, and `detail` to add a message:
+
+| `options`                                          | Response to a request from outside the gateway                       |
+| -------------------------------------------------- | -------------------------------------------------------------------- |
+| `{}`                                               | `403 Forbidden` with no `detail`                                     |
+| `{ "status": 404 }`                                | `404 Not Found` with no `detail`, as for a route that does not exist |
+| `{ "status": 401 }`                                | `401 Unauthorized` with no `detail`                                  |
+| `{ "status": 401, "statusText": "Access Denied" }` | `401 Access Denied` with no `detail`                                 |
+| `{ "detail": "Access denied." }`                   | `403 Forbidden` with your `detail`                                   |
+
+Every caller outside the gateway receives your `detail`, so don't use it to
+explain how the route is called or what protects it.
+
+`statusText` replaces only the status text; the problem's `title` stays the
+standard one, such as `Unauthorized`. Clients don't always receive it: HTTP/2
+and HTTP/3 have no status text, and Managed Dedicated and self-hosted gateways
+always send the standard text.
+
+## Hide REST routes behind an MCP server
+
+The MCP Server handler calls each tool's route with `context.invokeRoute`, so
+the tools keep working while direct calls to those REST routes get the same
+`404` as a route that does not exist. Declare the policy with `"status": 404`:
+
+```json
+{
+  "name": "internal-only-inbound",
+  "policyType": "internal-only-inbound",
+  "handler": {
+    "export": "InternalOnlyInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "status": 404
+    }
+  }
+}
+```
+
+Put it first in the inbound policies of each REST route that the MCP server
+exposes, so nothing else runs for a rejected request. Mark the route
+[`x-internal`](/docs/articles/openapi#x-internal) to keep it out of your
+developer portal as well:
+
+```json
+"/orders/{orderId}": {
+  "get": {
+    "operationId": "get-order",
+    "x-internal": true,
+    "parameters": [
+      {
+        "name": "orderId",
+        "in": "path",
+        "required": true,
+        "schema": { "type": "string" }
+      }
+    ],
+    "x-zuplo-route": {
+      "corsPolicy": "none",
+      "handler": {
+        "export": "urlForwardHandler",
+        "module": "$import(@zuplo/runtime)",
+        "options": { "baseUrl": "https://orders.example.com" }
+      },
+      "policies": {
+        "inbound": ["internal-only-inbound"]
+      }
+    }
+  }
+}
+```
+
+The policy's `404` is the gateway's standard not-found problem. Two things can
+still tell a hidden route from one that doesn't exist:
+
+- Preflight `OPTIONS` requests skip inbound policies, so a route with a CORS
+  policy still answers them. Set `corsPolicy` to `none` on hidden routes, as in
+  the example.
+- If you set `runtime.notFoundHandler` in your
+  [runtime extensions](/docs/programmable-api/runtime-extensions), paths that
+  don't exist answer with your handler's response instead.
+
+The MCP server route lists the operation as a tool and authenticates its own
+callers:
+
+```json
+"/mcp": {
+  "post": {
+    "x-zuplo-route": {
+      "handler": {
+        "export": "mcpServerHandler",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "operations": [{ "file": "./config/routes.oas.json", "id": "get-order" }]
+        }
+      },
+      "policies": {
+        "inbound": ["api-key-inbound"]
+      }
+    }
+  }
+}
+```
+
+## Protect an AI Gateway application
+
+New AI Gateway projects declare this policy as `internal-only-inbound`. Select
+it in an application's `inboundPolicyChain` in place of
+`ai-gateway-auth-inbound`, and put it first so nothing else runs for a rejected
+request:
+
+```json
+{
+  "inboundPolicyChain": [
+    { "name": "internal-only-inbound" },
+    { "name": "ai-gateway-model-filtering-inbound" },
+    { "name": "ai-gateway-metering-inbound" }
+  ]
+}
+```
+
+A chain entry's `options` replace the declared options for that application
+only:
+
+```json
+{ "name": "internal-only-inbound", "options": { "status": 404 } }
+```
+
+AWS Bedrock Runtime requests get the AWS error envelope instead of a problem
+response, so the AWS SDKs can parse the error: `AccessDeniedException` for a
+`401` or `403`, and `ResourceNotFoundException` for a `404`. Its `message` is
+your `detail`, or the status title, such as `Forbidden`, when you set none. That
+holds in an application's chain and on the AI Gateway route itself, ahead of the
+configuration loader.
+
+Metering records these requests against the application with no consumer, and a
+budget rule keyed on `request.user` has no value to accumulate for them. Attach
+per-consumer budgets to the calling application instead.
+
+The Smart Router and Prompt Injection Protection policies call their classifier
+applications this way.
+
+## Call a protected route
+
+Call the route from a policy or handler on the same gateway. No credentials are
+needed:
+
+```ts
+const response = await context.invokeRoute("/orders/1234");
+```
+
+A direct call from outside the gateway is rejected:
+
+```bash
+curl https://gateway.example.com/orders/1234
+```
+
+With the default options the response is `403 Forbidden` with no `detail`. The
+request log records why the policy rejected it.
+
+## What it does not check
+
+This policy asserts that a request originated inside this gateway deployment,
+not that the caller is trusted. Any route on the same gateway that forwards
+requests through `context.invokeRoute`, including an MCP server that exposes the
+route as a tool, reaches it. Protect those routes with their own authentication,
+exactly as you would an internal URL.
+
+## Deprecated names
+
+This policy began in the AI Gateway as Ensure Gateway Internal Invocation Only.
+Its earlier names are deprecated: the `AIGatewayInternalOnlyInboundPolicy`
+export, the `ai-gateway-internal-only` policy type, and the
+`ai-gateway-internal-only-inbound` chain-entry name. Configurations that use
+them keep working unchanged, but new configurations should use
+`InternalOnlyInboundPolicy` and `internal-only-inbound`.

package/docs/policies/internal-only-inbound/intro.md

@@ -0,0 +1,10 @@
+The Internal Only policy admits a request only when this gateway made it with
+`context.invokeRoute`, and rejects every request that arrived over the network.
+
+Use it on routes that only other routes, handlers, and policies on the same
+gateway call: REST routes that an MCP server exposes as tools, or the classifier
+application behind the Smart Router or Prompt Injection Protection policies.
+Those calls never leave the gateway, so an API key on them protects nothing. A
+rejected request gets `403 Forbidden` by default; set `status` to `404` to
+answer as if the route did not exist. The policy makes no network calls and
+never reads the request body.

package/docs/policies/internal-only-inbound/schema.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "https://cdn.zuplo.com/policies/runtime/schemas/internal-only-inbound.json",
+  "type": "object",
+  "title": "Internal Only",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "requiresAI": false,
+  "policyType": "internal-only-inbound",
+  "products": ["api-gateway", "ai-gateway"],
+  "description": "Accepts only requests that this gateway made itself with `context.invokeRoute`, and rejects every request that arrived over the network.\n\nUse it on a route that only other routes, handlers, and policies on the same gateway call: a REST endpoint that an MCP server exposes as a tool, or the classifier application behind the Smart Router or Prompt Injection Protection policies. Those calls never leave the gateway, so an API key on them protects nothing. This policy asserts the one thing that matters: the request originated inside the deployment.\n\nThe check reads `context.parentContext`, which the runtime sets only on the child context that `context.invokeRoute` creates. A client cannot supply it through a header, the URL, or the body. The policy makes no network calls, reads no body, and leaves `request.user` unset.\n\nA rejected request gets a `403 Forbidden` problem response with no `detail` by default, so the caller learns nothing about how the gateway works; the reason goes to the request log. Set `status` to answer with another client error, such as `404` to hide the route or `401`, `statusText` to change the status text, and `detail` to add a message.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "InternalOnlyInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "InternalOnlyInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": [],
+          "properties": {
+            "status": {
+              "type": "integer",
+              "minimum": 400,
+              "maximum": 499,
+              "default": 403,
+              "description": "The HTTP status code returned to a request that did not come from inside the gateway. Any client error status from 400 to 499 is allowed. Use `404` to answer as if the route did not exist, or `401` to answer as an authentication policy does."
+            },
+            "statusText": {
+              "type": "string",
+              "minLength": 1,
+              "pattern": "^[\\t\\x20-\\x7E\\x80-\\xFF]+$",
+              "examples": ["Not Found", "Unauthorized"],
+              "x-advanced": true,
+              "description": "The status text returned with `status`, such as `Not Found`. When it is omitted, the response uses the standard text for the status. Clients don't always receive it: HTTP/2 and HTTP/3 have no status text, and Managed Dedicated and self-hosted gateways always send the standard text."
+            },
+            "detail": {
+              "type": "string",
+              "minLength": 1,
+              "x-advanced": true,
+              "description": "The `detail` of the problem response returned to a rejected request. Every caller outside the gateway receives it, so don't describe how the route is called. When it is omitted, the response has no `detail`, and a `404` matches the response for a route that does not exist."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "InternalOnlyInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "status": 403,
+            "statusText": "Not Found"
+          }
+        }
+      ]
+    }
+  }
+}