zuplo 7.9.8 → 7.9.11

package/docs/dev-portal/zudoku/configuration/api-reference.md

@@ -399,6 +399,8 @@ different levels of your API documentation.
 ### Operations
 
 - `x-zudoku-playground-enabled`: Control playground visibility for an operation (default: `true`)
+- `x-internal`: Hide an operation from the documentation. Also works on path items and parameters.
+  See [`x-internal`](../openapi-extensions/x-internal)
 - `x-explorer-enabled`: Alias for `x-zudoku-playground-enabled` for compatibility Example:
 
 ```json

package/docs/dev-portal/zudoku/configuration/authentication-openid.md

@@ -28,11 +28,12 @@ Add the `authentication` property to your [Dev Portal configuration](./overview.
 }
 ```
 
-| Option     | Required | Description                                                                                  |
-| ---------- | -------- | -------------------------------------------------------------------------------------------- |
-| `clientId` | Yes      | The OAuth client ID issued by your provider.                                                 |
-| `issuer`   | Yes      | The issuer URL. Dev Portal discovers endpoints from `<issuer>/.well-known/openid-configuration`. |
-| `scopes`   | No       | Scopes to request. Defaults to `["openid", "profile", "email"]`.                             |
+| Option                  | Required | Description                                                                                                                                                 |
+| ----------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `clientId`              | Yes      | The OAuth client ID issued by your provider.                                                                                                                |
+| `issuer`                | Yes      | The issuer URL. Dev Portal discovers endpoints from `<issuer>/.well-known/openid-configuration`.                                                                |
+| `scopes`                | No       | Scopes to request. Defaults to `["openid", "profile", "email"]`.                                                                                            |
+| `allowInsecureRequests` | No       | Allow discovery and token requests against an `http://` issuer. Defaults to `false`. Intended only for local development — never enable this in production. |
 
 ## Provider Setup
 
@@ -126,6 +127,27 @@ After sign-in Dev Portal calls the provider's
 `name`, `email`, `picture`, and `email_verified` from the response. Map these claims in your
 provider if they are not emitted by default.
 
+## Local Development with an HTTP Issuer
+
+`oauth4webapi` (the library Dev Portal uses under the hood) rejects issuers that don't use `https://` by
+default, since OIDC requires TLS in production. If you're running an identity provider locally over
+plain HTTP (e.g. a dockerized Keycloak on `http://localhost:9090`), set `allowInsecureRequests` to
+`true` so discovery and token requests are allowed to use `http://`:
+
+```typescript title="zudoku.config.ts"
+{
+  authentication: {
+    type: "openid",
+    clientId: "<your-client-id>",
+    issuer: "http://localhost:9090/auth/realms/<your-realm>",
+    allowInsecureRequests: true,
+  },
+}
+```
+
+Only enable this for local development. Never set `allowInsecureRequests` to `true` against a
+production issuer.
+
 ## Troubleshooting
 
 - **Discovery fails**: verify `<issuer>/.well-known/openid-configuration` resolves and matches the

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

@@ -214,6 +214,31 @@ fields are used to display the user profile:
 
 If the provider does not return a field, it will be left blank.
 
+## Redirects after sign-in
+
+By default, users return to the page they started from after signing in. For
+[protected routes](./protected-routes.md) that is the path and query string they tried to open; for
+`useAuth().login({ redirectTo })` it is the `redirectTo` you pass.
+
+Setting `redirectToAfterSignIn` overrides that return URL: every sign-in lands on the configured
+path instead. Only set it if you always want users to land on the same page, and leave it unset to
+return users to where they were. `redirectToAfterSignUp` behaves the same way for sign-up.
+
+```typescript title="zudoku.config.ts"
+{
+  authentication: {
+    type: "auth0",
+    // ...
+    // Omit to return users to the page they came from
+    redirectToAfterSignIn: "/docs",
+  },
+}
+```
+
+This applies to all built-in providers. For Supabase social (OAuth) sign-in, the return URL must
+also be allowed under **Redirect URLs** in your Supabase project's authentication settings, and a
+return URL on another origin falls back to your site's root.
+
 ## Protected Routes
 
 Once authentication is configured, you can protect specific routes in your documentation to require

package/docs/dev-portal/zudoku/configuration/footer.mdx

@@ -143,7 +143,8 @@ footer: {
       dark: "/path/to/dark-logo.png"
     },
     alt: "Company Logo",
-    width: "120px" // optional width
+    width: 120, // optional intrinsic width
+    height: 24 // optional intrinsic height; set both to prevent layout shift
   }
 }
 ```
@@ -208,7 +209,8 @@ footer: {
       dark: "/images/logo-dark.svg"
     },
     alt: "Company Logo",
-    width: "100px"
+    width: 100,
+    height: 24
   }
 }
 ```

package/docs/dev-portal/zudoku/configuration/protected-routes.md

@@ -45,7 +45,15 @@ authenticated to access these routes.
 
 When a user tries to access a protected route, a login dialog will appear prompting them to sign in
 or register. After logging in, they are automatically redirected back to the route they were trying
-to access.
+to access, including its query string.
+
+:::caution{title="redirectToAfterSignIn takes precedence"}
+
+If `authentication.redirectToAfterSignIn` is set, users are sent to that path after every sign-in
+instead of the page they were trying to open. Leave it unset to return users to where they were. See
+[Redirects after sign-in](./authentication.md#redirects-after-sign-in).
+
+:::
 
 ## Object Format
 

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

@@ -58,7 +58,8 @@ Configure the site's logo with different versions for light and dark themes:
         dark: "/dark-logo.png"
       },
       alt: "Company Logo",
-      width: "120px", // optional width
+      width: 120, // optional intrinsic width
+      height: 32, // optional intrinsic height; set both to prevent layout shift
       href: "/", // optional link target (defaults to "/")
       reloadDocument: true, // optional, defaults to true
     }

package/docs/dev-portal/zudoku/guides/processors.mdx

@@ -19,6 +19,14 @@ For information on how to configure processors in your project, see the
 
 Dev Portal provides several built-in processors that you can use to transform your schemas:
 
+:::note
+
+Items marked with [`x-internal`](../openapi-extensions/x-internal) are removed automatically in
+every build, so you don't need to configure `removePaths` or `removeParameters` for that. The
+`x-internal` examples below show how the processors work.
+
+:::
+
 ### `removeExtensions`
 
 Removes OpenAPI extensions (`x-` prefixed properties) from your schema:

package/docs/dev-portal/zudoku/openapi-extensions/x-internal.md

@@ -0,0 +1,88 @@
+---
+title: x-internal
+sidebar_icon: eye-off
+---
+
+Use `x-internal` to hide internal endpoints and parameters from your API documentation. Anything
+marked with `x-internal: true` is removed from the schema before Dev Portal renders it, so it doesn't
+show up in the navigation, on operation pages, in the playground, or in documents published with
+[`publish`](/dev-portal/zudoku/configuration/api-reference#publish-a-canonical-openapi-document).
+
+`x-internal` is built in and applies to every Dev Portal project. You don't need to add a
+[schema processor](/dev-portal/zudoku/guides/processors) for it.
+
+:::warning
+
+`x-internal` only affects the documentation. The endpoints still exist on your API and can still be
+called. Don't rely on it to secure anything.
+
+:::
+
+## Location
+
+The extension can be added at the following levels:
+
+| Level                | Effect                                                            |
+| -------------------- | ----------------------------------------------------------------- |
+| **Path Item Object** | Removes the whole path, including all of its operations.          |
+| **Operation Object** | Removes only that operation. Other methods on the same path stay. |
+| **Parameter Object** | Removes the parameter from the path item or operation.            |
+
+| Option       | Type      | Description                                          |
+| ------------ | --------- | ---------------------------------------------------- |
+| `x-internal` | `boolean` | Set to `true` to remove the item from documentation. |
+
+`$ref`s are not resolved, so add `x-internal` to the parameter where it is used rather than to a
+shared `components.parameters` entry.
+
+Other objects such as tags, schemas, schema properties and responses are not covered. Use a custom
+[schema processor](/dev-portal/zudoku/guides/processors#custom-processors) if you need to hide those.
+
+## Example
+
+```yaml
+paths:
+  /admin:
+    x-internal: true # hides the entire path
+    get:
+      summary: Admin dashboard
+      responses:
+        "200":
+          description: OK
+  /users:
+    get:
+      summary: List users
+      parameters:
+        - name: limit
+          in: query
+          schema:
+            type: integer
+        - name: debug
+          in: query
+          x-internal: true # hides only this parameter
+          schema:
+            type: boolean
+      responses:
+        "200":
+          description: OK
+    delete:
+      summary: Delete all users
+      x-internal: true # hides only this operation
+      responses:
+        "204":
+          description: Deleted
+```
+
+In this example, the documentation shows `GET /users` with only the `limit` parameter. The `/admin`
+path, the `DELETE /users` operation, and the `debug` parameter are all hidden.
+
+## Notes
+
+- `x-internal` applies to APIs loaded from files (`type: "file"`), the same as other
+  [schema processors](/dev-portal/zudoku/guides/processors). Schemas loaded from a URL are not processed.
+- Your own schema processors in `zudoku.build.ts` run first, so they can add `x-internal` to items
+  programmatically.
+- The [`schemaDownload`](/dev-portal/zudoku/configuration/api-reference#options) option serves your original
+  schema file, which still contains the items marked with `x-internal`.
+- There is currently no option to turn this behavior off. If you need to keep an item in your
+  documentation, remove its `x-internal` flag.

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

@@ -114,6 +114,9 @@ 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.
+The 401 carries a `WWW-Authenticate` challenge that names the expected scheme
+and, when it is not `Authorization`, the header. See
+[Unauthorized responses](#unauthorized-responses).
 
 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
@@ -221,6 +224,28 @@ applies: `authHeader` and `authScheme` select the Zuplo key, and providers use
 their configured credentials. Moving the gateway key to an arbitrary custom
 header alone does not enable passthrough.
 
+## Unauthorized responses
+
+Every 401 from this policy carries a `WWW-Authenticate` challenge built from the
+policy options, so a client learns where the key goes without seeing the
+configuration. The scheme is `authScheme`, or `ApiKey` when `authScheme` is
+empty and the header carries only the key. A `header` parameter names
+`authHeader` when it is not `Authorization`. This policy's own 403 responses
+carry no challenge. On a User App route, the fail-closed 403 carries the same
+`WWW-Authenticate` challenge when this policy refused the key.
+
+| Options                                           | `WWW-Authenticate`                                  |
+| ------------------------------------------------- | --------------------------------------------------- |
+| `{}`                                              | `Bearer realm="ai-gateway"`                         |
+| `{ "authScheme": "Token" }`                       | `Token realm="ai-gateway"`                          |
+| `{ "authHeader": "x-gateway-key" }`               | `Bearer realm="ai-gateway", header="x-gateway-key"` |
+| `{ "authHeader": "x-api-key", "authScheme": "" }` | `ApiKey realm="ai-gateway", header="x-api-key"`     |
+
+With `credentialPassthrough` enabled, the challenge adds
+`passthrough="Authorization"` to say the provider credential goes in
+`Authorization`, for example
+`ApiKey realm="ai-gateway", header="zp-gateway-api-key", passthrough="Authorization"`.
+
 ## Choose a cache duration
 
 `cacheTtlSeconds` controls how long an authentication result can be reused. The

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

@@ -73,7 +73,8 @@
               "default": "Bearer",
               "x-show-example": false,
               "x-advanced": true,
-              "description": "The scheme that prefixes the key in the authHeader header, for example Bearer. Set to an empty string when the header contains only the key."
+              "pattern": "^(\\$env\\([^)]+\\)|[!#$%&'*+.^_`|~0-9A-Za-z-]*)$",
+              "description": "The scheme that prefixes the key in the authHeader header, for example Bearer. Set to an empty string when the header contains only the key. The scheme must be a single HTTP token such as Bearer, or empty for a bare key. $env(NAME) is accepted and validated after substitution."
             },
             "credentialPassthrough": {
               "type": "boolean",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "7.9.8",
+  "version": "7.9.11",
   "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.9.8",
-    "@zuplo/core": "7.9.8",
-    "@zuplo/runtime": "7.9.8",
-    "@zuplo/test": "7.9.8"
+    "@zuplo/cli": "7.9.11",
+    "@zuplo/core": "7.9.11",
+    "@zuplo/runtime": "7.9.11",
+    "@zuplo/test": "7.9.11"
   }
 }