zuplo 6.71.6 → 6.71.8

package/docs/articles/monetization/subscription-data.md

@@ -0,0 +1,153 @@
+---
+title: Reading Subscription Data
+sidebar_label: Subscription Data
+---
+
+When the `MonetizationInboundPolicy` authenticates a request, it looks up the
+caller's subscription — their plan, entitlements, payment status, and billing
+dates — and stores it on the request context. Read that data from your own code
+with the static `MonetizationInboundPolicy.getSubscriptionData` method to make
+decisions, personalize responses, or log which plan a request ran on.
+
+## Where you can call it
+
+`getSubscriptionData` returns data that the monetization policy puts on the
+context, so it only returns a value **after** the `monetization-inbound` policy
+has run. Call it from:
+
+- A **custom code inbound policy** placed _after_ `monetization-inbound` in the
+  route's inbound pipeline.
+- The **route handler**, which always runs after inbound policies.
+
+On a route without the monetization policy — or in a policy that runs before it
+— the method returns `undefined`. Always handle that case.
+
+:::note
+
+The `monetization-inbound` policy must come before any policy that reads the
+subscription. If your policy runs first, the subscription data isn't on the
+context yet. See
+[pipeline ordering](./monetization-policy.md#pipeline-ordering).
+
+:::
+
+## Basic usage
+
+```ts
+import {
+  MonetizationInboundPolicy,
+  HttpProblems,
+  ZuploContext,
+  ZuploRequest,
+} from "@zuplo/runtime";
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  const subscription = MonetizationInboundPolicy.getSubscriptionData(context);
+
+  if (!subscription) {
+    return HttpProblems.forbidden(request, context, {
+      detail: "No active subscription",
+    });
+  }
+
+  context.log.info(`Request on plan: ${subscription.plan.key}`);
+  return request;
+}
+```
+
+## The subscription object
+
+`getSubscriptionData` returns a `MonetizationSubscription`. The fields you reach
+for most are the plan and the entitlements map:
+
+```ts
+interface MonetizationSubscription {
+  id: string;
+  customerId: string;
+  name: string;
+  status: string;
+  currency: string;
+
+  plan: {
+    id: string;
+    name: string;
+    key: string; // Stable identifier — switch on this in code
+    version: number;
+    description?: string;
+  };
+
+  // Keyed by meter or feature key
+  entitlements: Record<
+    string,
+    {
+      balance: number; // Remaining allowance this period
+      hasAccess: boolean; // false when no access or quota spent
+      overage: number; // Usage beyond the included allowance
+      usage: number; // Consumed this period
+    }
+  >;
+
+  paymentStatus?: {
+    status: "paid" | "not_required" | "pending" | "failed" | "uncollectible";
+    isFirstPayment: boolean;
+    lastPaymentFailedAt?: string;
+    lastPaymentSucceededAt?: string;
+  };
+
+  billingCadence: string; // ISO 8601 duration, e.g. "P1M" for monthly
+  billingAnchor: string;
+  nextBillingDate: string;
+  activeFrom: string;
+  activeTo?: string;
+
+  maxPaymentOverdueDays: number;
+  accessBlocked?: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+```
+
+Switch on `plan.key` rather than `plan.name` in your logic — the key is a stable
+identifier, while the name is a display label that can change.
+
+## Reading entitlements
+
+Each entry in `entitlements` describes one metered feature or static feature on
+the subscription. The key is the meter or feature key; the value reports the
+caller's standing against it:
+
+```ts
+const subscription = MonetizationInboundPolicy.getSubscriptionData(context);
+
+const apiCalls = subscription?.entitlements["api_requests"];
+if (apiCalls) {
+  context.log.info(
+    `api_requests — used ${apiCalls.usage}, ${apiCalls.balance} remaining`,
+  );
+}
+```
+
+- `hasAccess` is the quickest check for "can this caller use this feature" —
+  it's `false` when the plan doesn't include the feature or the quota has run
+  out.
+- `balance` is the remaining allowance. A balance of `0` or less means no
+  allowance remains.
+- `usage` and `overage` report consumption this billing period.
+
+## Caveats
+
+- **Returns `undefined`** when the monetization policy hasn't run. Guard every
+  call.
+- **The policy caches the data.** Subscription and entitlement data is cached
+  for up to `cacheTtlSeconds` (60 seconds minimum), so `balance`, `usage`, and
+  `overage` can lag real-time consumption by the length of the cache window.
+  Treat them as recent, not exact.
+
+## Next steps
+
+- [Programmatic Monetization](./programmatic-monetization.md) — gate operations
+  by plan and meter requests based on the response.
+- [Dynamic Metering](./dynamic-metering.md) — set meter values at runtime from
+  code.
+- [Monetization Policy Reference](./monetization-policy.md) — every policy
+  configuration option.

package/docs/articles/openapi-string-format-validation-warnings.mdx

@@ -0,0 +1,142 @@
+---
+title: OpenAPI Format Validation Warnings in Local Development
+sidebar_label: Format Validation Warnings
+description:
+  Understand the "unknown format ... ignored" warnings the Zuplo CLI prints
+  during local development, why they appear, and why they are safe to ignore.
+tags:
+  - openapi
+  - local-development
+  - validation
+---
+
+When you run a Zuplo project locally with `npm run dev` (or `zuplo dev`), the
+console may print one or more warnings like this:
+
+```text
+unknown format "date-time" ignored in schema at path "#/properties/createdAt"
+```
+
+These warnings are informational. They do not stop the development server, fail
+schema validation, or change how your gateway behaves once deployed. This page
+explains what the warning means and what, if anything, to do about it.
+
+:::tip
+
+**Short answer: the warnings are safe to ignore.** They report that a `format`
+keyword in your OpenAPI document is not being actively checked — the field is
+still validated against its `type` and every other constraint you defined.
+
+:::
+
+## What the warning means
+
+Zuplo validates requests against your OpenAPI schema using
+[Ajv](https://ajv.js.org/), a standard JSON Schema validator. In JSON Schema and
+OpenAPI, the
+[`format` keyword](https://json-schema.org/understanding-json-schema/reference/string#format)
+(for example `date-time`, `email`, or `uuid`) is an _annotation_. A validator
+only enforces a format if it has a validator registered for that specific
+format. For any format it does not recognize, the standard behavior is to skip
+the format check and log a message like the one above.
+
+When you see `unknown format "date-time" ignored in schema at path "…"`, it
+means:
+
+- The validator found a `format: "date-time"` (or similar) in your schema.
+- It has no registered check for that format in local development, so it
+  **ignores the format** and moves on.
+- The field is **still validated** against its `type` and any other keywords you
+  set, such as `pattern`, `enum`, `minimum`, `maxLength`, or `required`.
+
+The `path` in the message (for example `#/properties/createdAt`, or a path or
+query parameter location) points to where the format appears in the schema, so
+you can locate it.
+
+## Are the warnings safe to ignore?
+
+Yes. The warning is purely informational. It does **not**:
+
+- Stop or crash the local development server.
+- Cause a build or deployment to fail.
+- Reject any request, or change the response your API returns.
+- Change validation behavior in deployed environments.
+
+Type checking and every other constraint in your schema continue to work exactly
+as written. An enforced `format` validates the _shape_ of a value — for example,
+that a string looks like an RFC 3339 date-time. When a format is ignored, you
+lose only that one extra check; the field's `type` and all other constraints are
+unaffected.
+
+## Why some formats warn and others don't
+
+You may notice the warning for some formats but not others, and on some fields
+but not others. A few things drive this:
+
+- **`format` is advisory in JSON Schema.** Validators are free to enforce only
+  the formats they choose to register. Which formats are actively checked is an
+  internal detail of the validator and can differ between CLI versions, so treat
+  the set as subject to change rather than a fixed contract.
+- **Path and query parameters are validated separately from request bodies.**
+  Parameter schemas and body schemas are generally compiled independently, so
+  the same `format` can produce a warning in one place but not the other.
+
+Because the warning is harmless, you do not need to determine exactly which
+formats are checked. The guidance below applies to any format that warns.
+
+## How to remove the warnings
+
+You have two options, depending on whether you rely on that format for
+validation.
+
+**Option 1 — Leave the `format` keyword in place (recommended).** Keeping
+`format` annotations is good practice: they document intent, drive code
+generation and the developer portal, and are useful to consumers of your API
+even when the gateway does not enforce them. The warning is the only cost, and
+it is cosmetic.
+
+**Option 2 — Enforce the value with a constraint that _is_ checked.** If you
+want the gateway to actively reject malformed values, replace or supplement the
+`format` with explicit constraints that the validator always enforces, such as
+`pattern`, `enum`, `minLength`/`maxLength`, or `minimum`/`maximum`. For example,
+to enforce a date-time-like string with a regular expression instead of relying
+on `format`:
+
+```json
+{
+  "createdAt": {
+    "type": "string",
+    "format": "date-time",
+    "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$"
+  }
+}
+```
+
+Here `format` stays for documentation, and `pattern` does the actual
+enforcement. The regular expression above is an illustrative RFC 3339-style
+example, not a Zuplo-mandated pattern — adjust it to match the values you
+expect. The warning may still appear for the ignored `format`, but the value is
+now strictly validated.
+
+:::caution
+
+The [Request Validation policy](../policies/request-validation-inbound.mdx)
+options control _what_ is validated (`validateBody`, `validateQueryParameters`,
+`validatePathParameters`, `validateHeaders`) and how failures are handled, but
+they do not let you register additional formats or silence individual format
+warnings. To guarantee a value's shape, use enforced constraints like `pattern`
+as shown above.
+
+:::
+
+## Related
+
+- [Request Validation Policy](../policies/request-validation-inbound.mdx) —
+  validate request bodies, query parameters, path parameters, and headers
+  against your OpenAPI schema.
+- [Schema Validation Failed (SCHEMA_VALIDATION_FAILED)](../errors/schema-validation-failed.mdx)
+  — the runtime error returned when a request does not pass schema validation.
+- [OpenAPI Support in Zuplo](./openapi.mdx) — how Zuplo uses your OpenAPI
+  document to configure the gateway.
+- [Local Development](./local-development.mdx) — run and test your gateway
+  locally with the Zuplo CLI.

package/docs/articles/troubleshooting-deployments-and-git-sync.mdx

@@ -0,0 +1,222 @@
+---
+title: Troubleshooting Stuck Deployments and Git Sync Errors
+sidebar_label: Troubleshooting Deployments
+description:
+  Diagnose Zuplo deployments that hang at "Deploying api" or "Building Developer
+  Portal" and fix Git source-control sync errors such as Bitbucket 410 Gone
+  responses on branch retrieval.
+---
+
+When a deploy seems to hang at `Deploying api…` or `Building Developer Portal…`,
+or your Git provider stops returning branches with a `Bad Request` or `410 Gone`
+error, the cause is usually one of a few known issues. This guide helps you tell
+a genuinely stuck deploy from a slow-but-progressing one, fix Git source-control
+sync failures, and gather the right details before contacting support.
+
+## How a Zuplo deploy progresses
+
+Every deploy, whether triggered by a Git push, the Zuplo CLI, or a save in the
+Portal, runs through two stages in order:
+
+1. **`Deploying api…`**: Zuplo builds your gateway configuration (routes,
+   policies, and modules) and rolls it out to the edge.
+2. **`Building Developer Portal…`**: Zuplo builds the Developer Portal site from
+   your OpenAPI document and portal configuration.
+
+Each stage produces its own build logs. Zuplo separates logs by stage: `api` for
+the gateway build and `dev-portal` for the Developer Portal build. Knowing which
+stage a deploy stalled in tells you where to look.
+
+:::note
+
+A deploy can finish the `api` stage successfully and still be working on the
+`dev-portal` stage. If your gateway is already serving traffic but the deploy
+status hasn't flipped to complete, the Developer Portal build is the most likely
+place it's still working. See
+[The Developer Portal build never finishes](#the-developer-portal-build-never-finishes).
+
+:::
+
+## Is the deploy stuck, or still working?
+
+A deploy that looks frozen in the terminal is often still running on Zuplo's
+side. The Zuplo CLI doesn't run the build itself. It starts the deploy and then
+_polls_ for the result. The build continues on the server even if the CLI stops
+waiting.
+
+### Confirm the server-side status first
+
+Before assuming a deploy failed, check whether it actually completed:
+
+1. Open your [project](https://portal.zuplo.com/+/account/project/) in the Zuplo
+   Portal.
+2. Check the environment you deployed to. If the build finished, the environment
+   shows the new deployment and its URL responds to requests.
+3. Send a request to the environment URL (or its
+   [health check route](./health-checks.mdx), if you have one) to confirm the
+   gateway is live.
+
+If the environment is updated and serving traffic, the deploy succeeded. The CLI
+simply stopped waiting before the build reported back.
+
+:::tip
+
+The CLI prints `Deployed to https://...` on success. If you never saw that line
+but the Portal shows the environment updated, the deploy completed after the CLI
+timed out. Capture the URL from the Portal rather than constructing it from the
+branch name. The hostname uses a normalized, truncated form of the environment
+name plus a unique identifier.
+
+:::
+
+### Extend the CLI polling timeout
+
+By default the CLI polls every second for up to 250 attempts, a little over four
+minutes. Large projects can take longer to build, and when the CLI's poll budget
+runs out it stops waiting even though the deploy keeps running on the server.
+
+Increase the timeout with the `POLL_INTERVAL` and `MAX_POLL_RETRIES` environment
+variables:
+
+```bash
+# Poll every 5 seconds for up to 300 attempts (25 minutes)
+POLL_INTERVAL=5000 MAX_POLL_RETRIES=300 zuplo deploy
+```
+
+- **`POLL_INTERVAL`**: Milliseconds between polls. Default `1000` (1 second).
+- **`MAX_POLL_RETRIES`**: Maximum number of polls before the CLI times out.
+  Default `250`.
+
+For the full command reference, see [CLI: deploy](../cli/deploy.mdx).
+
+:::caution
+
+Raising the polling timeout only changes how long the CLI _waits_. It does not
+make the build faster, and it does not fix a build that is genuinely failing. If
+the deploy never completes server-side no matter how long you wait, treat it as
+a failed build and read the logs for the stage that stalled.
+
+:::
+
+## The Developer Portal build never finishes
+
+If the gateway (`api` stage) deploys but the overall deploy hangs at
+`Building Developer Portal…`, the problem is in the Developer Portal build, not
+your routes or policies.
+
+Common causes:
+
+- **Invalid OpenAPI document**: The portal is generated from your OpenAPI
+  document. A malformed `routes.oas.json`, an unresolved `$ref`, or invalid
+  schema can stall or fail the portal build. Validate your OpenAPI document and
+  fix any errors.
+- **A legacy `config/dev-portal.json` file**: Projects migrated from the old
+  Developer Portal can carry a stale `config/dev-portal.json` that breaks the
+  build. See the [Dev Portal Migration Guide](../dev-portal/migration.mdx) for
+  the exact cleanup steps.
+- **Custom portal configuration errors**: Errors in your `zudoku.config.tsx` (or
+  other portal configuration) can prevent the site from building.
+
+Read the `dev-portal` stage build logs to see the specific error, then redeploy
+after fixing it.
+
+## Git source-control sync errors
+
+Zuplo connects to GitHub, GitLab, Bitbucket, and Azure DevOps for source
+control. The integration pushes and pulls code between the Portal and your
+repository, and it lists branches so you can map them to environments. When that
+authorization breaks, branch retrieval fails, often with a `Bad Request` or
+`410 Gone` error.
+
+### Why branch retrieval returns `Bad Request` or `410 Gone`
+
+These errors come from the Git provider, not from Zuplo, and they almost always
+mean the connection is no longer authorized:
+
+- The OAuth authorization Zuplo uses to reach the provider has **expired or been
+  revoked**.
+- The repository was **renamed or moved**, which breaks the existing connection.
+- The Git app was **uninstalled** or lost access to the repository in the
+  provider's settings.
+
+`410 Gone` in particular signals that the resource Zuplo asked for (the branch
+list) is no longer available at that location, typically because the
+authorization or repository link behind it is stale.
+
+### Reconnect the integration
+
+To restore branch sync, re-authorize the connection:
+
+1. Open your
+   [project settings](https://portal.zuplo.com/+/account/project/settings/general)
+   in the Zuplo Portal and select **Source Control**.
+2. Disconnect the current repository connection.
+3. Reconnect and complete the provider's authorization flow again, granting
+   access to the repository that holds your Zuplo project.
+
+After reconnecting, retrieving branches should succeed again.
+
+:::caution
+
+Renaming a repository breaks the Zuplo connection. If you renamed or moved the
+repository, disconnect and reconnect to restore the link. See
+[Rename or Move Project](./rename-or-move-project.mdx) for details.
+
+:::
+
+### Bitbucket-specific notes
+
+Bitbucket integration is available on
+[enterprise plans](https://zuplo.com/pricing) and provides push/pull source
+control without automatic deployments. You deploy with the Zuplo CLI through
+[Bitbucket Pipelines](./custom-ci-cd-bitbucket.mdx).
+
+If reconnecting from the Portal doesn't clear the sync error:
+
+- **Confirm Bitbucket is still enabled for your account.** For
+  [bitbucket.org](https://bitbucket.org), Zuplo support enables the integration.
+  Contact [support@zuplo.com](mailto:support@zuplo.com) with your Bitbucket
+  Workspace ID (found on your Workspace Settings page).
+- **For self-hosted Bitbucket, check the OAuth app.** If the OAuth app's client
+  secret was rotated or its callback URL or permissions changed, branch
+  retrieval fails until the app is reconfigured. The callback URL must be
+  `https://portal.zuplo.com` and the app must grant the `repo`, `user`, and
+  `read:org` permissions. See
+  [Bitbucket Setup](./source-control-setup-bitbucket.mdx).
+
+## Decision tree
+
+Use this to route yourself to the right fix:
+
+| Symptom                                              | Most likely cause                               | First action                                                                                   |
+| ---------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| CLI hangs at `Deploying api…` then times out         | Build took longer than the CLI's poll budget    | Check the environment in the Portal; raise `MAX_POLL_RETRIES`                                  |
+| CLI reported timeout, but the environment is updated | Deploy completed after the CLI stopped waiting  | None; capture the URL from the Portal                                                          |
+| Deploy hangs at `Building Developer Portal…`         | Developer Portal build error                    | Read the `dev-portal` build logs; validate OpenAPI; check for a stale `config/dev-portal.json` |
+| Branch list fails with `Bad Request` or `410 Gone`   | Git authorization expired, revoked, or stale    | Reconnect the integration in **Source Control** settings                                       |
+| Bitbucket still fails after reconnecting             | Account not enabled, or OAuth app misconfigured | Contact support with your Workspace ID; check the self-hosted OAuth app                        |
+
+## When to contact support
+
+If you've worked through the relevant section above and the deploy or sync still
+fails, contact [support@zuplo.com](mailto:support@zuplo.com). Include these
+details so support can investigate without a round-trip:
+
+- Your **account** and **project** names.
+- The **environment** (branch) you're deploying to.
+- The **stage** where it stalls (`api` or `dev-portal`) and the exact message
+  you see.
+- For sync errors: your **Git provider**, the **repository**, and the exact
+  error text (for example, `410 Gone` on branch retrieval).
+- The **approximate time** of the failed deploy, in UTC.
+
+## Next steps
+
+- [Source Control & Deployments](./source-control.mdx): how source control and
+  deployments fit together across providers.
+- [Branch-Based Deployments](./branch-based-deployments.mdx): how branches map
+  to environments and how environment URLs are named.
+- [Deploying Zuplo from a Monorepo](./monorepo-deployment.mdx): CI/CD
+  configuration, schema validation, and health-check timeouts.
+- [Troubleshooting (local development)](./local-development-troubleshooting.mdx):
+  local dev server, ports, and certificate issues.

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

@@ -177,6 +177,12 @@
                   "type": "integer",
                   "minimum": 1,
                   "default": 28800
+                },
+                "pkce": {
+                  "type": "string",
+                  "enum": ["S256", "none"],
+                  "default": "none",
+                  "description": "Whether to send S256 PKCE on the federated browser-login authorization request and replay the verifier at the token exchange. Defaults to \"none\". Set to \"S256\" when the identity provider mandates PKCE on the authorization-code flow."
                 }
               }
             }
@@ -191,6 +197,7 @@
             "audience": "https://gateway.example.com",
             "auth0Domain": "my-tenant.us.auth0.com",
             "browserLoginOverrides": {
+              "pkce": "none",
               "remoteTimeoutMs": 10000,
               "sessionTtlSeconds": 28800,
               "stateTtlSeconds": 900

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

@@ -117,6 +117,12 @@
                   "type": "integer",
                   "minimum": 1,
                   "default": 28800
+                },
+                "pkce": {
+                  "type": "string",
+                  "enum": ["S256", "none"],
+                  "default": "none",
+                  "description": "Whether to send S256 PKCE on the federated browser-login authorization request and replay the verifier at the token exchange. Defaults to \"none\". Set to \"S256\" when the identity provider mandates PKCE on the authorization-code flow."
                 }
               }
             }
@@ -130,6 +136,7 @@
           "options": {
             "awsRegion": "us-east-1",
             "browserLoginOverrides": {
+              "pkce": "none",
               "remoteTimeoutMs": 10000,
               "sessionTtlSeconds": 28800,
               "stateTtlSeconds": 900

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

@@ -98,6 +98,12 @@
                   "type": "integer",
                   "minimum": 1,
                   "default": 28800
+                },
+                "pkce": {
+                  "type": "string",
+                  "enum": ["S256", "none"],
+                  "default": "none",
+                  "description": "Whether to send S256 PKCE on the federated browser-login authorization request and replay the verifier at the token exchange. Defaults to \"none\". Set to \"S256\" when the identity provider mandates PKCE on the authorization-code flow."
                 }
               }
             }
@@ -110,6 +116,7 @@
           "module": "$import(@zuplo/runtime)",
           "options": {
             "browserLoginOverrides": {
+              "pkce": "none",
               "remoteTimeoutMs": 10000,
               "sessionTtlSeconds": 28800,
               "stateTtlSeconds": 900

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

@@ -93,6 +93,12 @@
                   "type": "integer",
                   "minimum": 1,
                   "default": 28800
+                },
+                "pkce": {
+                  "type": "string",
+                  "enum": ["S256", "none"],
+                  "default": "none",
+                  "description": "Whether to send S256 PKCE on the federated browser-login authorization request and replay the verifier at the token exchange. Defaults to \"none\". Set to \"S256\" when the identity provider mandates PKCE on the authorization-code flow."
                 }
               }
             }
@@ -105,6 +111,7 @@
           "module": "$import(@zuplo/runtime)",
           "options": {
             "browserLoginOverrides": {
+              "pkce": "none",
               "remoteTimeoutMs": 10000,
               "sessionTtlSeconds": 28800,
               "stateTtlSeconds": 900

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

@@ -106,6 +106,12 @@
                   "type": "integer",
                   "minimum": 1,
                   "default": 28800
+                },
+                "pkce": {
+                  "type": "string",
+                  "enum": ["S256", "none"],
+                  "default": "none",
+                  "description": "Whether to send S256 PKCE on the federated browser-login authorization request and replay the verifier at the token exchange. Defaults to \"none\". Set to \"S256\" when the identity provider mandates PKCE on the authorization-code flow."
                 }
               }
             }
@@ -118,6 +124,7 @@
           "module": "$import(@zuplo/runtime)",
           "options": {
             "browserLoginOverrides": {
+              "pkce": "none",
               "remoteTimeoutMs": 10000,
               "sessionTtlSeconds": 28800,
               "stateTtlSeconds": 900

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

@@ -98,6 +98,12 @@
                   "type": "integer",
                   "minimum": 1,
                   "default": 28800
+                },
+                "pkce": {
+                  "type": "string",
+                  "enum": ["S256", "none"],
+                  "default": "none",
+                  "description": "Whether to send S256 PKCE on the federated browser-login authorization request and replay the verifier at the token exchange. Defaults to \"none\". Set to \"S256\" when the identity provider mandates PKCE on the authorization-code flow."
                 }
               }
             }
@@ -110,6 +116,7 @@
           "module": "$import(@zuplo/runtime)",
           "options": {
             "browserLoginOverrides": {
+              "pkce": "none",
               "remoteTimeoutMs": 10000,
               "sessionTtlSeconds": 28800,
               "stateTtlSeconds": 900

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

@@ -98,6 +98,12 @@
                   "type": "string",
                   "description": "Optional audience parameter for the IdP authorization request (Auth0-style API audiences)."
                 },
+                "pkce": {
+                  "type": "string",
+                  "enum": ["S256", "none"],
+                  "default": "none",
+                  "description": "Whether to send S256 PKCE on the federated browser-login authorization request and replay the verifier at the token exchange. Defaults to \"none\". Set to \"S256\" when the identity provider mandates PKCE on the authorization-code flow (e.g. OAuth 2.1 IdPs, hardened Okta/Entra tenants). Leave as \"none\" for IdPs that may reject unexpected PKCE parameters."
+                },
                 "remoteTimeoutMs": {
                   "type": "integer",
                   "minimum": 1,
@@ -227,6 +233,7 @@
           "options": {
             "browserLogin": {
               "clientSecret": "$env(MCP_OAUTH_CLIENT_SECRET)",
+              "pkce": "none",
               "remoteTimeoutMs": 10000,
               "scope": "openid profile email",
               "sessionTtlSeconds": 28800,