zuplo 6.68.17 → 6.68.24

package/docs/articles/accounts/roles-and-permissions.mdx

@@ -4,13 +4,6 @@ title: Role Permissions
 
 <EnterpriseFeature name="Role Based Access Control" />
 
-:::info{title="Beta"}
-
-The specific permissions of each role are currently in beta and may change
-without notice.
-
-:::
-
 Accounts in Zuplo can have multiple members with different roles. Each account
 member can be a role that defines the permissions they have in the account.
 

package/docs/articles/certificate-pinning.mdx

@@ -0,0 +1,82 @@
+---
+title: Certificate Pinning
+sidebar_label: Certificate Pinning
+---
+
+Certificate pinning is a security technique where a client validates a server's
+TLS certificate against a known copy (or public key hash) stored locally in the
+client application. While this can mitigate certain classes of man-in-the-middle
+attacks, it's generally not recommended for modern APIs and is
+[especially problematic](https://scotthelme.co.uk/why-we-need-to-do-more-to-reduce-certificate-lifetimes/)
+for services that use short-lived, automatically rotated certificates.
+
+:::warning
+
+Zuplo strongly discourages certificate pinning for APIs running on Zuplo-managed
+custom domains. Certificates are short-lived and rotate automatically on a
+schedule outside of your control, which can break pinned clients without
+warning.
+
+:::
+
+## Why pinning is discouraged on Zuplo
+
+By default, Zuplo manages SSL certificates for your custom domain through
+Cloudflare. These certificates are issued by either Google Trust Services or
+Let's Encrypt and have the following properties:
+
+- Certificates are issued for **90 days**.
+- Certificates are automatically renewed approximately **30 days before
+  expiry**.
+- Rotation is **not guaranteed to follow a strict 90-day cadence**. We may
+  rotate certificates earlier for security, operational, or infrastructure
+  reasons.
+- Rotation happens without advance notification to the gateway owner.
+
+Because rotation is automatic and the exact schedule isn't under your control,
+any client that pins a specific certificate or public key can stop working at
+any time. For most production APIs, this risk far outweighs the marginal
+security benefit pinning provides.
+
+## Recommended alternatives
+
+If you or your clients are concerned about man-in-the-middle attacks or
+unauthorized certificate issuance, use these alternatives instead of pinning:
+
+- **[HTTP Strict Transport Security (HSTS)](https://https.cio.gov/hsts/)** to
+  force HTTPS and prevent protocol downgrade attacks.
+- **[CAA DNS records](./custom-domains.mdx#caa-records)** to restrict which
+  certificate authorities can issue certificates for your domain.
+
+## If a client insists on pinning
+
+Pinning is strongly discouraged, but if a client application insists on it, they
+can self-serve. The public portion of the certificate is returned on every TLS
+handshake, so anyone connecting to your domain can retrieve it using standard
+tools like `openssl` or `curl`. Zuplo doesn't need to send the certificate and
+has no record of who has downloaded it.
+
+If a client goes down this path, they should be aware that:
+
+- Certificates rotate automatically and can change at any time.
+- Pinning the Subject Public Key Info (SPKI) hash is more resilient than pinning
+  the full certificate, but still not guaranteed to survive rotation.
+- The client is responsible for monitoring the certificate and updating their
+  pins before the next rotation breaks their application.
+
+## Using your own long-lived SSL certificate
+
+If you truly need full control over certificate rotation, the only supported
+option is to supply your own SSL certificate for your domain and have Zuplo
+install it. Contact [support@zuplo.com](mailto:support@zuplo.com) to arrange
+this.
+
+:::caution
+
+Using a custom, long-lived SSL certificate shifts all renewal responsibility to
+you. Expired certificates are a common cause of production outages. Before going
+down this path, verify that you have an established process for tracking
+expiration, renewing certificates ahead of time, and delivering the updated
+certificate to Zuplo.
+
+:::

package/docs/articles/custom-domains.mdx

@@ -166,10 +166,9 @@ Certificates are issued for 90 days and are automatically renewed approximately
 
 Certificate pinning isn't recommended for Zuplo APIs as the certificates are
 issued for short periods of time and renewed automatically. If you or your end
-clients require certificate pinning, it's recommended you use a custom,
-long-lived SSL certificate. (Although this is
-[not recommended](https://scotthelme.co.uk/why-we-need-to-do-more-to-reduce-certificate-lifetimes/)
-for most use cases.)
+clients require certificate pinning, see the dedicated
+[Certificate Pinning](./certificate-pinning.mdx) page for the trade-offs,
+alternatives, and options for retrieving or managing your own certificate.
 
 :::
 

package/docs/articles/log-plugin-splunk.mdx

@@ -1,5 +1,5 @@
 ---
-title: Splunk Plugin (Beta)
+title: Splunk Plugin
 sidebar_label: Splunk Logging
 ---
 

package/docs/cli/list.mdx

@@ -23,6 +23,22 @@ sidebar_label: list
     "deprecated": false,
     "hidden": false
   },
+  {
+    "name": "output",
+    "type": "string",
+    "description": "Output format",
+    "default": "default",
+    "required": false,
+    "deprecated": false,
+    "hidden": false,
+    "alias": [
+      "o"
+    ],
+    "choices": [
+      "default",
+      "json"
+    ]
+  },
   {
     "name": "self-hosted-endpoint",
     "type": "string",
@@ -30,6 +46,18 @@ sidebar_label: list
     "required": false,
     "deprecated": false,
     "hidden": false
+  },
+  {
+    "name": "show-details",
+    "type": "boolean",
+    "description": "Include deployment metadata in the output",
+    "default": false,
+    "required": false,
+    "deprecated": false,
+    "hidden": false,
+    "alias": [
+      "d"
+    ]
   }
 ]}
   examples={[
@@ -37,6 +65,14 @@ sidebar_label: list
     "$0 list",
     "List all deployed environments for your project"
   ],
+  [
+    "$0 list --show-details",
+    "List all deployed environments with project and deployment names"
+  ],
+  [
+    "$0 list --output json",
+    "List deployed environments as JSON"
+  ],
   [
     "$0 list --account my-account --project my-project",
     "Explicitly specify the account and project"

package/docs/concepts/api-errors.md

@@ -0,0 +1,294 @@
+---
+title: API Errors
+---
+
+Well-designed API errors are as important as the successful responses your API
+returns. A good error response tells the caller what went wrong, whether the
+problem is on their side or yours, and what they can do about it. Zuplo
+encourages every API to return standard, actionable error messages so that
+developers integrating with your API spend less time guessing and more time
+building.
+
+This page explains the error format Zuplo uses by default, how it shows up in
+the gateway, and how to customize the shape of error responses when your API has
+its own conventions.
+
+## Why standard errors matter
+
+When every endpoint invents its own error shape, client code becomes brittle.
+Developers have to special-case each response, parse ad-hoc fields, and guess at
+whether a failure is retryable. Standardizing errors across your API produces
+three concrete benefits:
+
+- **Faster integration** -- consumers write one error handler that works
+  everywhere.
+- **Better observability** -- logs, dashboards, and tools can parse errors
+  consistently.
+- **Clearer contracts** -- your OpenAPI document can describe errors using the
+  same schema for every operation.
+
+A good error response is short, machine-readable, and specific. It identifies
+the kind of problem, says what happened in human terms, and includes enough
+context (a request ID, a field name, a retry hint) that the caller can take the
+next step without opening a support ticket.
+
+## The Problem Details format
+
+Zuplo defaults to the [Problem Details for HTTP APIs](https://httpproblems.com/)
+format defined by [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807).
+Problem Details is a small, widely adopted JSON schema for representing errors
+from HTTP APIs. Responses use the `application/problem+json` content type and
+follow a consistent shape.
+
+A typical Problem Details response from Zuplo looks like this:
+
+```json
+{
+  "type": "https://httpproblems.com/http-status/401",
+  "title": "Unauthorized",
+  "status": 401,
+  "instance": "/v1/widgets",
+  "trace": {
+    "timestamp": "2026-04-19T17:13:31.352Z",
+    "requestId": "28f2d802-8e27-49c8-970d-39d90ef0ac61",
+    "buildId": "eb9ef87d-b55d-446e-9fdd-13c209c01b95"
+  }
+}
+```
+
+The standard fields are:
+
+- **`type`** -- a URI that identifies the kind of problem. Every occurrence of
+  the same problem should share the same `type`.
+- **`title`** -- a short, human-readable summary that should stay consistent for
+  a given `type`.
+- **`status`** -- the HTTP status code, duplicated in the body so clients that
+  log only the payload still see it.
+- **`detail`** -- a human-readable explanation of this particular occurrence.
+  This is the field that varies from request to request.
+- **`instance`** -- a URI or path that identifies the specific request that
+  produced the error.
+
+Problem Details also allows **extensions** -- arbitrary additional fields that
+carry problem-specific data. Zuplo uses extensions to include a `trace` object
+containing the request ID, build ID, and timestamp on every error, which makes
+support requests easy to correlate with logs.
+
+:::tip
+
+Keep `title` stable for a given error type and put request-specific information
+in `detail` or in extensions. Clients match on `type` and `title`; humans read
+`detail`.
+
+:::
+
+## How Zuplo uses Problem Details
+
+Zuplo's built-in policies, handlers, and system errors all return Problem
+Details responses out of the box. When an inbound policy rejects a request --
+for example, the
+[API Key Authentication policy](../policies/api-key-inbound.mdx) when a key is
+missing, or the [Rate Limiting policy](../policies/rate-limit-inbound.mdx) when
+a caller exceeds their quota -- the response body is a Problem Details object
+with a `type`, `title`, `status`, and `trace`. The same is true for system
+responses like unmatched routes and unsupported HTTP methods.
+
+This means that consumers of a Zuplo-fronted API get a consistent error contract
+for free across gateway errors, even before you write any custom code.
+
+### Returning Problem Details from custom code
+
+When you write a [custom handler](../handlers/custom-handler.mdx) or a
+[custom policy](../articles/policies.mdx), return Problem Details responses
+using the `HttpProblems` helper from `@zuplo/runtime`. The helper has a method
+for every HTTP status code and automatically fills in `type`, `title`, `status`,
+`instance`, and `trace`.
+
+```ts
+import { HttpProblems, ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  if (!request.user) {
+    return HttpProblems.unauthorized(request, context);
+  }
+
+  return request;
+}
+```
+
+For the full list of methods and options, see the
+[HttpProblems helper reference](../programmable-api/http-problems.mdx).
+
+### Adding context with `detail` and extensions
+
+Override the default fields when you have something more useful to say. Use
+`detail` for a human-readable explanation of the specific failure, and use
+extension members for structured data that clients can act on.
+
+```ts
+return HttpProblems.badRequest(request, context, {
+  title: "Invalid value for query parameter 'take'",
+  detail:
+    "The take parameter must be a number less than 100. The provided value was 'hello'.",
+  extensions: {
+    parameter: "take",
+    providedValue: "hello",
+  },
+});
+```
+
+The `title` stays consistent for every instance of this error, while `detail`
+and the `parameter` extension tell the caller exactly what to fix.
+
+### Throwing runtime errors
+
+If your code throws rather than returning a response, use `RuntimeError` and
+`ConfigurationError` to attach structured context that the gateway can surface.
+Thrown errors are converted to Problem Details responses automatically, and any
+`extensionMembers` you attach flow through to the response body.
+
+```ts
+import { RuntimeError } from "@zuplo/runtime";
+
+throw new RuntimeError({
+  message: "Upstream database timed out",
+  extensionMembers: {
+    service: "orders-db",
+    timeoutMs: 5000,
+  },
+});
+```
+
+See [Runtime Errors](../programmable-api/runtime-errors.mdx) for details on both
+error classes and patterns for mapping them to problem responses.
+
+## Customizing the error response format
+
+Problem Details is the default, but it isn't the only option. If your API
+already has an established error schema, or if you want to wrap every error in a
+custom envelope, Zuplo provides two levels of customization.
+
+### Per-response overrides
+
+The simplest customization is to override fields on individual responses.
+`HttpProblems` lets you change `title`, `detail`, `type`, `instance`, and add
+arbitrary extensions without giving up the standard format.
+
+```ts
+return HttpProblems.tooManyRequests(
+  request,
+  context,
+  {
+    type: "https://errors.example.com/rate-limit-exceeded",
+    detail: "You've exceeded the 1000 requests per hour plan limit.",
+    extensions: {
+      plan: "free",
+      upgradeUrl: "https://example.com/upgrade",
+    },
+  },
+  {
+    "Retry-After": "3600",
+  },
+);
+```
+
+This approach keeps the Problem Details shape while letting you customize types,
+link to documentation, and include plan-specific or caller-specific metadata.
+
+### Formatting every error with `ProblemResponseFormatter`
+
+For more control, use the
+[`ProblemResponseFormatter`](../programmable-api/problem-response-formatter.mdx)
+to build problem responses directly. This is useful when you want to compute the
+problem body yourself -- for example, mapping an upstream error payload into
+your own error taxonomy.
+
+```ts
+import { ProblemResponseFormatter } from "@zuplo/runtime";
+
+const problemDetails = {
+  type: "https://errors.example.com/validation-failed",
+  title: "Validation Failed",
+  status: 400,
+  detail: "The request body contains invalid fields.",
+  instance: request.url,
+  extensions: {
+    code: "VAL_001",
+    fields: ["email", "phone"],
+  },
+};
+
+return ProblemResponseFormatter.format(problemDetails, request, context);
+```
+
+### Replacing the error format globally
+
+To change the shape of every error response the gateway returns -- including
+errors raised by built-in policies -- register a global error handler in your
+[runtime extensions](../programmable-api/runtime-extensions.mdx). The handler
+runs for any unhandled error in the pipeline and returns the response of your
+choice.
+
+```ts
+import { RuntimeExtensions } from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.addErrorHandler(async (error, request, context) => {
+    return new Response(
+      JSON.stringify({
+        error: {
+          code: "internal_error",
+          message: error.message,
+          requestId: context.requestId,
+        },
+      }),
+      {
+        status: 500,
+        headers: { "content-type": "application/json" },
+      },
+    );
+  });
+}
+```
+
+Global error handlers let you keep Problem Details internally while projecting a
+different schema to your callers, or replace the format entirely if your API has
+an established error contract.
+
+:::caution
+
+Replacing the default format means you also take responsibility for including
+trace information, preserving status codes, and documenting the new schema in
+your OpenAPI document. Most APIs are best served by customizing Problem Details
+fields rather than replacing the format.
+
+:::
+
+### Customizing specific system errors
+
+Some gateway behaviors have dedicated extension points for error customization.
+For example, you can replace the default 404 response by registering a
+[not-found handler](../programmable-api/not-found-handler.mdx), which is useful
+for serving custom error pages or matching your API's error schema on unmatched
+routes.
+
+## Choosing an approach
+
+| Scenario                                             | Approach                                                       |
+| ---------------------------------------------------- | -------------------------------------------------------------- |
+| Return a one-off error from a handler or policy      | `HttpProblems` with `detail` and extensions                    |
+| Build problem responses from external error payloads | `ProblemResponseFormatter.format()`                            |
+| Attach context to thrown errors                      | `RuntimeError` with `extensionMembers`                         |
+| Replace the error schema for every response          | Global error handler via `runtime.addErrorHandler`             |
+| Customize only the 404 response                      | [Not-found handler](../programmable-api/not-found-handler.mdx) |
+
+## Related resources
+
+- [HttpProblems helper](../programmable-api/http-problems.mdx)
+- [ProblemResponseFormatter](../programmable-api/problem-response-formatter.mdx)
+- [Runtime Errors](../programmable-api/runtime-errors.mdx)
+- [Not-found Handler](../programmable-api/not-found-handler.mdx)
+- [Runtime Extensions](../programmable-api/runtime-extensions.mdx)
+- [Custom Handlers](../handlers/custom-handler.mdx)
+- [Policies](../articles/policies.mdx)
+- [RFC 7807: Problem Details for HTTP APIs](https://datatracker.ietf.org/doc/html/rfc7807)

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

@@ -34,7 +34,10 @@ If you don't have an Auth0 account, you can sign up for a
      - Production: `https://your-site.com/oauth/callback`
      - Preview (wildcard): `https://*.your-domain.com/oauth/callback`
      - Local Development: `http://localhost:3000/oauth/callback`
-   - **Allowed Logout URLs**: Same as callback URLs above
+   - **Allowed Logout URLs**:
+     - Production: `https://your-site.com/oauth/logout-callback`
+     - Preview (wildcard): `https://*.your-domain.com/oauth/logout-callback`
+     - Local Development: `http://localhost:3000/oauth/logout-callback`
 
    - **Allowed Web Origins**:
      - Production: `https://your-site.com`
@@ -112,8 +115,8 @@ To enable logout for your Auth0 application:
 
 1. Ensure your **Allowed Logout URLs** are configured in Auth0 (see
    [Configure Auth0 Application](#setup-steps) above)
-2. The logout URL should match your callback URL pattern (e.g., `https://your-site.com/` for
-   production)
+2. The logout URL must use the `/oauth/logout-callback` path (e.g.,
+   `https://your-site.com/oauth/logout-callback` for production)
 
 For older tenants, you may need to enable **RP-Initiated Logout** in your tenant settings. See the
 [Auth0 logout documentation](https://auth0.com/docs/authenticate/login/logout/log-users-out-of-auth0)

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

@@ -0,0 +1,110 @@
+---
+title: OpenID Connect (OIDC)
+sidebar_label: OpenID Connect
+description:
+  Configure any OpenID Connect compliant identity provider (Okta, Keycloak, Authentik, etc.) as the
+  authentication provider for Zudoku.
+---
+
+Dev Portal supports any identity provider that implements the
+[OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html) protocol via the generic
+`openid` provider type. This includes Okta, Keycloak, Authentik, Ory, ZITADEL, AWS Cognito, Google
+Identity, and most enterprise IdPs.
+
+## Configuration
+
+Add the `authentication` property to your [Dev Portal configuration](./overview.md):
+
+```typescript title="zudoku.config.ts"
+{
+  // ...
+  authentication: {
+    type: "openid",
+    clientId: "<your-client-id>",
+    issuer: "<the-issuer-url>",
+    scopes: ["openid", "profile", "email"], // Optional
+  },
+  // ...
+}
+```
+
+| 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"]`.                             |
+
+## Provider Setup
+
+Register Dev Portal as a public SPA / single page application client in your identity provider and set:
+
+- Callback / Redirect URI to `https://your-site.com/oauth/callback`
+- For local development, add `http://localhost:3000/oauth/callback`
+- If your provider supports wildcards, add `https://*.your-domain.com/oauth/callback` for preview
+  environments
+- Add your site origin to the list of allowed CORS origins
+- Enable the `Authorization Code` grant with PKCE and the `Refresh Token` grant
+
+### Okta
+
+1. In the Okta admin console go to **Applications** → **Applications** → **Create App Integration**.
+2. Select **OIDC - OpenID Connect** and **Single Page Application**.
+3. Set **Sign-in redirect URIs** to `https://your-site.com/oauth/callback` (add
+   `http://localhost:3000/oauth/callback` for local development).
+4. Under **Assignments**, assign the users or groups that should have access.
+5. After creating the app, copy the **Client ID**. Your issuer is your Okta domain, for example
+   `https://your-tenant.okta.com` or a custom authorization server like
+   `https://your-tenant.okta.com/oauth2/default`.
+6. Under **Security** → **API** → **Trusted Origins**, add your site origin for both CORS and
+   Redirect.
+
+```typescript title="zudoku.config.ts"
+{
+  authentication: {
+    type: "openid",
+    clientId: "<your-okta-client-id>",
+    issuer: "https://your-tenant.okta.com/oauth2/default",
+    scopes: ["openid", "profile", "email"],
+  },
+}
+```
+
+### Keycloak
+
+Use the realm issuer URL:
+
+```typescript title="zudoku.config.ts"
+{
+  authentication: {
+    type: "openid",
+    clientId: "zudoku",
+    issuer: "https://keycloak.example.com/realms/<your-realm>",
+  },
+}
+```
+
+In the realm, create a client with **Client type** `OpenID Connect`, **Access type** `public`, and
+enable **Standard Flow** (Authorization Code).
+
+## Verifying the Issuer
+
+You can confirm your issuer URL is correct by opening `<issuer>/.well-known/openid-configuration` in
+a browser. It should return a JSON document listing `authorization_endpoint`, `token_endpoint`,
+`userinfo_endpoint`, and `jwks_uri`.
+
+## User Profile
+
+After sign-in Dev Portal calls the provider's
+[UserInfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) and reads
+`name`, `email`, `picture`, and `email_verified` from the response. Map these claims in your
+provider if they are not emitted by default.
+
+## Troubleshooting
+
+- **Discovery fails**: verify `<issuer>/.well-known/openid-configuration` resolves and matches the
+  `issuer` value in the document.
+- **CORS errors on token / userinfo**: add your site origin to the provider's allowed origins.
+- **Redirect URI mismatch**: the URI registered with the provider must match the Dev Portal origin
+  exactly, including protocol and port.
+- **Missing profile fields**: ensure `profile` and `email` scopes are granted and that the provider
+  includes `name`, `email`, and `picture` claims in the UserInfo response.

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

@@ -15,8 +15,8 @@ authentication provider you use.
 
 ## Authentication Providers
 
-Dev Portal supports Clerk, Auth0, Supabase, Firebase, Azure B2C, and any OpenID provider that supports
-the OpenID Connect protocol (including PingFederate).
+Dev Portal supports Clerk, Auth0, Supabase, Firebase, Azure B2C, and any OpenID Connect provider
+(including Okta, Keycloak, Authentik, and PingFederate).
 
 Not seeing your authentication provider? [Let us know](https://github.com/zuplo/zudoku/issues)
 
@@ -96,6 +96,9 @@ When configuring your OpenID provider, you will need to set the following:
 By default, the scopes "openid", "profile", and "email" are requested. You can customize these by
 providing your own array of scopes.
 
+For provider-specific guides (Okta, Keycloak, etc.), see the
+[OpenID Connect setup page](./authentication-openid.md).
+
 ### Firebase
 
 For Firebase authentication, you will need your Firebase project configuration. You can find this in