npm - zuplo - Versions diffs - 6.71.11 → 6.71.13 - Mend

zuplo 6.71.11 → 6.71.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/docs/articles/monetization/monetization-policy.md CHANGED Viewed

@@ -61,13 +61,14 @@ reads the API key from the `Authorization` header, validates it, and sets
 ## Configuration options
-| Option               | Type               | Default           | Description                                       |
-| -------------------- | ------------------ | ----------------- | ------------------------------------------------- |
-| `meters`             | object             | _(none)_          | Map of meter keys to increment values             |
-| `meterOnStatusCodes` | string or number[] | `"200-299"`       | Status code range to meter                        |
-| `authHeader`         | string             | `"authorization"` | Header to read the API key from                   |
-| `authScheme`         | string             | `"Bearer"`        | Expected auth scheme prefix                       |
-| `cacheTtlSeconds`    | number             | `60`              | How long to cache subscription data (minimum 60s) |
+| Option                 | Type               | Default           | Description                                           |
+| ---------------------- | ------------------ | ----------------- | ----------------------------------------------------- |
+| `meters`               | object             | _(none)_          | Map of meter keys to increment values                 |
+| `requiredEntitlements` | string[]           | _(none)_          | Entitlement keys the subscription must have access to |
+| `meterOnStatusCodes`   | string or number[] | `"200-299"`       | Status code range to meter                            |
+| `authHeader`           | string             | `"authorization"` | Header to read the API key from                       |
+| `authScheme`           | string             | `"Bearer"`        | Expected auth scheme prefix                           |
+| `cacheTtlSeconds`      | number             | `60`              | How long to cache subscription data (minimum 60s)     |
 ### `meters`
@@ -91,6 +92,23 @@ see the [Dynamic Metering](./dynamic-metering.md) guide.
 { "meters": { "api_credits": 10 } }
 ```
+### `requiredEntitlements`
+A list of [entitlement](./features.mdx) keys the caller's subscription must have
+access to before the request is allowed. Use it to gate a route on a feature —
+for example, restrict it to plans that include `custom_domains` — without
+writing code.
+```json
+{ "requiredEntitlements": ["custom_domains"] }
+```
+The request is allowed only when **every** listed entitlement is present with
+`hasAccess` set to `true`. If any is missing, disabled, or has exhausted its
+quota, the policy returns `403 Forbidden` before the request reaches your
+backend. For access checks that need runtime logic, gate in code instead — see
+[Programmatic Monetization](./programmatic-monetization.md).
 ### `meterOnStatusCodes`
 Controls which responses count toward metering. By default, only successful
@@ -256,22 +274,23 @@ the RFC 7807 Problem Details format:
 Common error details:
-| Condition                        | `detail` message                                                    |
-| -------------------------------- | ------------------------------------------------------------------- |
-| No auth header                   | `"No Authorization Header"`                                         |
-| Wrong auth scheme                | `"Invalid Authorization Scheme"`                                    |
-| Empty key after the auth scheme  | `"No key present"`                                                  |
-| Cached invalid key or 401        | `"Authorization Failed"`                                            |
-| Invalid API key                  | `"API Key is invalid or does not have access to the API"`           |
-| Expired API key                  | `"API Key has expired."`                                            |
-| Expired subscription             | `"API Key has an expired subscription."`                            |
-| Subscription has no payment      | `"Subscription payment status is not available."`                   |
-| Payment not made                 | `"Payment has not been made."`                                      |
-| Payment overdue                  | `"Payment is overdue. Please update your payment method."`          |
-| Subscription has no entitlements | `"Subscription entitlements are not available."`                    |
-| Meter not in subscription        | `"API Key does not have \"X\" meter provided by the subscription."` |
-| Quota exhausted                  | `"API Key has exceeded the allowed limit for \"X\" meter."`         |
-| Meter access denied              | `"API Key does not have access to \"X\" meter."`                    |
+| Condition                        | `detail` message                                                                   |
+| -------------------------------- | ---------------------------------------------------------------------------------- |
+| No auth header                   | `"No Authorization Header"`                                                        |
+| Wrong auth scheme                | `"Invalid Authorization Scheme"`                                                   |
+| Empty key after the auth scheme  | `"No key present"`                                                                 |
+| Cached invalid key or 401        | `"Authorization Failed"`                                                           |
+| Invalid API key                  | `"API Key is invalid or does not have access to the API"`                          |
+| Expired API key                  | `"API Key has expired."`                                                           |
+| Expired subscription             | `"API Key has an expired subscription."`                                           |
+| Subscription has no payment      | `"Subscription payment status is not available."`                                  |
+| Payment not made                 | `"Payment has not been made."`                                                     |
+| Payment overdue                  | `"Payment is overdue. Please update your payment method."`                         |
+| Subscription has no entitlements | `"Subscription entitlements are not available."`                                   |
+| Meter not in subscription        | `"API Key does not have \"X\" meter provided by the subscription."`                |
+| Quota exhausted                  | `"API Key has exceeded the allowed limit for \"X\" meter."`                        |
+| Meter access denied              | `"API Key does not have access to \"X\" meter."`                                   |
+| Required entitlement missing     | `"The required \"X\" entitlement is not allowed or its quota has been exhausted."` |
 ## Pipeline ordering

package/docs/articles/monetization/programmatic-monetization.md CHANGED Viewed

@@ -74,6 +74,35 @@ if (!advancedSearch?.hasAccess) {
 }
 ```
+:::tip
+If you only need to check that a feature's entitlement has access — with no
+other runtime logic — skip the custom code and use the policy's
+[`requiredEntitlements`](./monetization-policy.md#requiredentitlements) option
+instead. It rejects the request with `403 Forbidden` when any listed entitlement
+is missing or out of quota:
+```json
+// config/policies.json
+{
+  "name": "monetization-inbound",
+  "policyType": "monetization-inbound",
+  "handler": {
+    "export": "MonetizationInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "meters": { "api_requests": 1 },
+      "requiredEntitlements": ["advanced_search"]
+    }
+  }
+}
+```
+Reach for the code path below when the decision needs more than a presence check
+— inspecting the plan key, reading the request, or combining conditions.
+:::
 Register the policy and apply it after `monetization-inbound` on the routes you
 want to protect:

package/docs/dev-portal/zudoku/configuration/navigation.mdx CHANGED Viewed

@@ -143,7 +143,10 @@ type NavigationCategory = {
   collapsible?: boolean;
   collapsed?: boolean;
   stack?: boolean; // open the category's items as a stacked sub-nav
-  link?: string | { type: "doc"; file: string; label?: string; path?: string };
+  link?:
+    | string
+    | { type: "doc"; file: string; label?: string; path?: string }
+    | { type: "link"; to: string; label?: string };
   display?:
     | "auth"
     | "anon"
@@ -158,9 +161,11 @@ type NavigationCategory = {
 #### Category links
 A category can have a `link` property that makes the category label itself clickable, navigating to
-a document. This is useful when you want a category that acts as both a group and a landing page.
+a document, a path, or an external URL. This is useful when you want a category that acts as both a
+group and a landing page.
-The `link` can be a simple string pointing to a file path, or an object for more control:
+The `link` can be a simple string pointing to a file path, a `doc` object for more control, or a
+`link` object that points the category label at an arbitrary path or external URL:
 ```tsx title="String shorthand"
 {
@@ -190,7 +195,7 @@ The `link` can be a simple string pointing to a file path, or an object for more
 }
 ```
-The object form supports these properties:
+The `doc` object form supports these properties:
 | Property | Type     | Description                                              |
 | -------- | -------- | -------------------------------------------------------- |
@@ -199,6 +204,29 @@ The object form supports these properties:
 | `label`  | `string` | Override the label (defaults to the document title)      |
 | `path`   | `string` | Custom URL path (overrides the default file-based route) |
+```tsx title="Link form pointing to a path or external URL"
+{
+  type: "category",
+  label: "API Reference",
+  link: {
+    type: "link",
+    to: "/api",
+  },
+  items: [
+    "guides/authentication",
+    "guides/rate-limits",
+  ],
+}
+```
+The `link` object form supports these properties:
+| Property | Type     | Description                         |
+| -------- | -------- | ----------------------------------- |
+| `type`   | `"link"` | Must be `"link"`                    |
+| `to`     | `string` | Path or external URL to navigate to |
+| `label`  | `string` | Override the category label         |
 ### `type: doc`
 Doc is used to reference markdown files. The `label` is the text that will be displayed, and the

package/docs/mcp-gateway/cross-app-access/overview.mdx ADDED Viewed

@@ -0,0 +1,204 @@
+---
+title: "Cross App Access (XAA)"
+sidebar_label: "Overview"
+description: |
+  What Cross App Access (XAA) and the Identity Assertion JWT Authorization Grant
+  (ID-JAG) are, the problem they solve for AI agents and MCP, and how the Zuplo
+  MCP Gateway performs the token exchange so your MCP servers and clients don't
+  have to.
+---
+:::note{title="Beta"}
+Cross App Access support is in beta and builds on the
+[MCP Gateway](../introduction.mdx), which is also in beta. The configuration
+model and policy options may change before general availability.
+:::
+Cross App Access (XAA) lets one application reach another application's API on a
+user's behalf **through the identity provider both apps already trust** —
+instead of running a separate, point-to-point OAuth connection between them. For
+AI agents and MCP, that means an agent can call a protected upstream MCP server
+for a user without the user re-consenting to every app pair, and without
+credentials sprawling outside the identity provider's view.
+The Zuplo MCP Gateway sits in the middle of this flow and runs the XAA token
+exchange for you. An MCP client connects to the gateway with ordinary MCP OAuth;
+the gateway, acting as the XAA _requesting app_, mints the cross-app grant from
+your identity provider and redeems it at the upstream's authorization server.
+Neither the MCP client nor the upstream MCP server has to implement XAA itself.
+## The problem XAA solves
+Single sign-on (SSO) solves _login_: a user authenticates once with an identity
+provider (Okta, Microsoft Entra, Auth0) and gets into every connected app. SSO
+does **not** solve _app-to-app API access_. When one app needs to call another
+app's API on the user's behalf, the two apps today run a direct OAuth flow
+between themselves. The
+[IETF draft](https://datatracker.ietf.org/doc/draft-ietf-oauth-identity-assertion-authz-grant/)
+describes this as a connection that "bypasses the trusted identity provider" and
+is "invisible to the identity provider managing the ecosystem."
+AI agents make this gap urgent. An agent in one app increasingly needs to reach
+into other SaaS apps' data on the user's behalf. The naive approach produces:
+- **Consent-screen sprawl** — the user re-authorizes every agent against every
+  downstream app individually.
+- **Credential sprawl** — long-lived tokens scattered per app pair, invisible to
+  IT.
+- **No central governance** — security teams can't see or control what connects
+  to what, and offboarding means hunting access down service by service.
+XAA routes app-to-app access back through the identity provider both apps
+already trust. The IdP becomes the single place where IT decides which app can
+talk to which app, enforces conditional-access policy, and audits every
+delegation — while the upstream app's authorization server stays the
+access-token issuer. The trust boundary isn't broken; it's brokered.
+## How the flow works
+XAA is defined by the **Identity Assertion JWT Authorization Grant (ID-JAG)** —
+`draft-ietf-oauth-identity-assertion-authz-grant`. It chains two OAuth exchanges
+across two authorization servers:
+1. **Identity assertion → ID-JAG**, at the identity provider, using
+   [RFC 8693 token exchange](https://www.rfc-editor.org/rfc/rfc8693). The
+   requesting app presents the user's ID token (the identity assertion) and asks
+   for a grant scoped to one specific target authorization server. The IdP
+   evaluates policy and returns a short-lived, audience-restricted **ID-JAG** —
+   a signed JWT with the header `typ: oauth-id-jag+jwt`.
+2. **ID-JAG → access token**, at the upstream's resource authorization server,
+   using the
+   [RFC 7523 JWT bearer grant](https://www.rfc-editor.org/rfc/rfc7523). The
+   requesting app presents the ID-JAG as an `assertion` and receives a normal
+   access token for the upstream API.
+The ID-JAG is a _grant_, not an access token — it can't call an API directly. It
+exists only to be redeemed in the second exchange.
+When the Zuplo gateway fronts an XAA-protected upstream, the gateway plays the
+**requesting app** for both exchanges:
+<Diagram height="h-80">
+  <DiagramNode id="client">MCP Client</DiagramNode>
+  <DiagramGroup id="gateway" label="Zuplo MCP Gateway (requesting app)">
+    <DiagramNode id="inbound" variant="zuplo">
+      OAuth 2.1 server
+    </DiagramNode>
+    <DiagramNode id="requestor" variant="zuplo">
+      XAA requestor
+    </DiagramNode>
+  </DiagramGroup>
+  <DiagramNode id="idp">Identity Provider</DiagramNode>
+  <DiagramGroup id="upstream" label="Upstream app">
+    <DiagramNode id="ras">Resource AS</DiagramNode>
+    <DiagramNode id="mcp">MCP server</DiagramNode>
+  </DiagramGroup>
+  <DiagramEdge from="client" to="inbound" label="MCP OAuth (no XAA)" />
+  <DiagramEdge from="requestor" to="idp" label="1. ID token → ID-JAG" />
+  <DiagramEdge from="requestor" to="ras" label="2. ID-JAG → access token" />
+  <DiagramEdge from="requestor" to="mcp" label="3. Bearer token" />
+</Diagram>
+Step by step, for a tool call to an XAA-protected upstream route:
+1. The MCP client connects to the gateway route with **ordinary MCP OAuth** —
+   discovery, PKCE, and a bearer token issued by the gateway. This leg is _not_
+   XAA. During the gateway's browser-login step, the user authenticates with the
+   identity provider, and the gateway captures the user's IdP identity
+   assertion.
+2. On a tool call, the gateway exchanges the user's ID token at the IdP for an
+   **ID-JAG** audience-restricted to the upstream's resource authorization
+   server (RFC 8693 token exchange).
+3. The gateway redeems the ID-JAG at the upstream resource authorization server
+   for an upstream **access token** (RFC 7523 JWT bearer grant).
+4. The gateway forwards the tool call to the upstream MCP server with
+   `Authorization: Bearer <upstream access token>` and caches the upstream token
+   per user for subsequent calls.
+:::note{title="In requesting-app mode, the client → gateway leg is plain OAuth"}
+This is the most common point of confusion. In the flow above, the MCP client
+never speaks XAA — it runs the standard MCP authorization flow against the
+gateway, and all ID-JAG exchanges happen on the gateway's _outbound_ side. A
+client doesn't need any XAA support to benefit from it.
+:::
+## What the gateway does for you
+In the XAA flow the gateway plays the requesting app, so the MCP client and the
+upstream MCP server are each insulated from the protocol:
+- **The MCP client** does nothing new. It runs the same MCP OAuth flow it would
+  for any gateway route. Claude, Cursor, ChatGPT, VS Code, and any
+  spec-compliant client work unchanged.
+- **The two-exchange dance** — the RFC 8693 token exchange at the IdP and the
+  RFC 7523 JWT-bearer redemption at the upstream — runs inside the gateway. You
+  configure endpoints and credentials; the gateway mints, redeems, caches, and
+  refreshes.
+- **Per-user identity** is preserved end to end. The IdP sees the specific user,
+  the upstream sees a token minted for that user, and gateway analytics record
+  the same subject.
+## Glossary
+- **Identity assertion** — Proof the IdP authenticated the user, carried as an
+  OIDC ID token (`urn:ietf:params:oauth:token-type:id_token`) or SAML 2.0
+  assertion. It's the _input_ to the XAA flow.
+- **ID-JAG (Identity Assertion JWT Authorization Grant)** — A short-lived signed
+  JWT the IdP mints, audience-restricted to one resource authorization server.
+  Used once to obtain an access token there. JWT header `typ: oauth-id-jag+jwt`;
+  token type `urn:ietf:params:oauth:token-type:id-jag`. It is **not** an access
+  token.
+- **Identity provider (IdP)** — The SSO authority both apps trust (Okta, Entra,
+  Auth0). In XAA it also brokers cross-app access by issuing ID-JAGs after
+  evaluating policy. Identified by `iss` in the ID-JAG.
+- **Resource authorization server** — The _target_ app's OAuth server. It
+  consumes the ID-JAG via the JWT-bearer grant and issues the real access token.
+  Identified by `aud` in the ID-JAG. In Zuplo's outbound flow, this is the
+  upstream's server, not the gateway.
+- **Requesting app** — The party that obtains and redeems the ID-JAG. When the
+  gateway fronts an XAA-protected upstream, the gateway is the requesting app.
+- **Token exchange (RFC 8693)** — The grant used at the IdP to swap the identity
+  assertion for the ID-JAG.
+- **JWT bearer grant (RFC 7523)** — The grant used at the resource authorization
+  server to redeem the ID-JAG for an access token.
+## When to use XAA
+Reach for XAA when:
+- An upstream MCP server is protected by an **enterprise resource authorization
+  server** that accepts ID-JAGs (the "enterprise-managed authorization"
+  pattern), and you want the gateway to broker access through your IdP rather
+  than running a separate OAuth client per upstream.
+- You need **central governance** — one place in the IdP to grant, audit, and
+  revoke which apps can reach which APIs on a user's behalf.
+For an upstream that uses plain per-user or shared OAuth (Linear, Notion,
+Stripe, and most SaaS MCP servers today), use
+[upstream OAuth](../auth/upstream-oauth.mdx) instead — XAA isn't required.
+## Try it and configure it
+- [Quickstart](./quickstart.mdx) — see XAA work end to end in minutes using
+  Okta's hosted [xaa.dev](https://xaa.dev) playground, with no identity tenant
+  required.
+- [Configuration reference](./policy-reference.mdx) — every `idJag` option on
+  the token-exchange policy.
+## Learn more
+- [Identity Assertion JWT Authorization Grant (IETF draft)](https://datatracker.ietf.org/doc/draft-ietf-oauth-identity-assertion-authz-grant/)
+  — the ID-JAG specification. Note this is an active draft, not yet a finalized
+  RFC.
+- [MCP authorization spec](https://modelcontextprotocol.io/specification/latest/basic/authorization)
+  and the
+  [Enterprise-Managed Authorization extension](https://modelcontextprotocol.io/extensions/auth/enterprise-managed-authorization)
+  — where ID-JAG plugs into MCP.
+- [Okta — Cross App Access](https://developer.okta.com/blog/2025/09/03/cross-app-access)
+  — Okta's explainer and walkthrough.
+- [How the MCP Gateway works](../how-it-works.mdx) — the gateway's two OAuth
+  surfaces and request lifecycle.

package/docs/mcp-gateway/cross-app-access/policy-reference.mdx ADDED Viewed

@@ -0,0 +1,161 @@
+---
+title: "Cross App Access configuration reference"
+sidebar_label: "Configuration reference"
+description: |
+  Every configuration option for Cross App Access (XAA) on the Zuplo MCP Gateway
+  — the id-jag mode on the token-exchange policy, where the gateway acts as the
+  XAA requesting app.
+---
+Cross App Access is configured on the
+[`mcp-token-exchange-inbound`](#gateway-as-requesting-app) policy. Setting
+`authMode: "id-jag"` and providing an `idJag` block makes the gateway act as the
+XAA **requesting app**: it mints an ID-JAG from your IdP and redeems it at an
+upstream resource authorization server. This is the configuration the
+[quickstart](./quickstart.mdx) uses.
+:::note
+The authoritative source for these options is the policy's runtime schema. The
+generated `mcp-token-exchange-inbound` reference page predates `id-jag` mode;
+the options below reflect the runtime behavior.
+:::
+## Gateway as requesting app
+Set `authMode: "id-jag"` on a `mcp-token-exchange-inbound` policy and provide an
+`idJag` block. Attach the policy to the upstream route after the inbound MCP
+OAuth policy.
+```jsonc title="config/policies.json"
+{
+  "name": "id-jag-upstream",
+  "policyType": "mcp-token-exchange-inbound",
+  "handler": {
+    "module": "$import(@zuplo/runtime/mcp-gateway)",
+    "export": "McpTokenExchangeInboundPolicy",
+    "options": {
+      "displayName": "Upstream",
+      "authMode": "id-jag",
+      "idJag": {
+        "scopes": ["mcp:tools"],
+        "scopeDelimiter": " ",
+        "idp": {
+          "tokenUrl": "https://idp.example.com/token",
+          "clientAuth": {
+            "method": "client_secret_post",
+            "clientId": "$env(IDP_CLIENT_ID)",
+            "clientSecret": "$env(IDP_CLIENT_SECRET)",
+          },
+        },
+        "resourceAs": {
+          "tokenUrl": "https://upstream.example.com/token",
+          "audience": "https://upstream.example.com",
+          "resource": "https://upstream.example.com/mcp",
+          "clientAuth": {
+            "method": "client_secret_post",
+            "clientId": "$env(RESOURCE_AS_CLIENT_ID)",
+            "clientSecret": "$env(RESOURCE_AS_CLIENT_SECRET)",
+          },
+        },
+      },
+    },
+  },
+}
+```
+### idJag options
+| Option           | Type       | Default | Description                                                          |
+| ---------------- | ---------- | ------- | -------------------------------------------------------------------- |
+| `scopes`         | `string[]` | `[]`    | Scopes requested in both exchanges.                                  |
+| `scopeDelimiter` | `string`   | `" "`   | Delimiter used to join scopes.                                       |
+| `idp`            | object     | —       | Where the gateway mints the ID-JAG (RFC 8693 token exchange).        |
+| `resourceAs`     | object     | —       | Where the gateway redeems the ID-JAG for an access token (RFC 7523). |
+### idp
+The identity provider that issues the ID-JAG.
+| Option       | Type   | Description                                           |
+| ------------ | ------ | ----------------------------------------------------- |
+| `tokenUrl`   | string | The IdP token endpoint.                               |
+| `clientAuth` | object | How the gateway authenticates to the IdP (see below). |
+### resourceAs
+The upstream's resource authorization server that issues the access token.
+| Option       | Type   | Description                                                                                                           |
+| ------------ | ------ | --------------------------------------------------------------------------------------------------------------------- |
+| `tokenUrl`   | string | The resource authorization server's token endpoint.                                                                   |
+| `audience`   | string | **Required.** The resource AS identifier; sent as the token-exchange `audience` and becomes the ID-JAG `aud`.         |
+| `resource`   | string | Optional [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707) resource indicator. Defaults to the route's upstream URL. |
+| `clientAuth` | object | How the gateway authenticates to the resource AS (see below).                                                         |
+### clientAuth
+Both `idp.clientAuth` and `resourceAs.clientAuth` take the same shape. The
+`method` selects how the gateway authenticates:
+```jsonc
+// client_secret_post (or client_secret_basic)
+"clientAuth": {
+  "method": "client_secret_post",
+  "clientId": "...",
+  "clientSecret": "$env(...)"
+}
+```
+```jsonc
+// private_key_jwt
+"clientAuth": {
+  "method": "private_key_jwt",
+  "clientId": "...",
+  "privateKeyPem": "$env(...)",
+  "algorithm": "RS256",
+  "keyId": "...",
+  "expiresInSeconds": 300
+}
+```
+| Option             | Type   | Default | Applies to        | Description                                                        |
+| ------------------ | ------ | ------- | ----------------- | ------------------------------------------------------------------ |
+| `method`           | enum   | —       | all               | `client_secret_post`, `client_secret_basic`, or `private_key_jwt`. |
+| `clientId`         | string | —       | all               | The OAuth client ID.                                               |
+| `clientSecret`     | string | —       | secret methods    | The OAuth client secret.                                           |
+| `privateKeyPem`    | string | —       | `private_key_jwt` | PEM private key used to sign the client-assertion JWT.             |
+| `algorithm`        | enum   | `RS256` | `private_key_jwt` | `RS256`/`RS384`/`RS512`/`ES256`/`ES384`/`ES512`.                   |
+| `keyId`            | string | —       | `private_key_jwt` | Optional `kid` header on the client assertion.                     |
+| `audience`         | string | —       | `private_key_jwt` | Optional audience override for the client assertion.               |
+| `expiresInSeconds` | number | `300`   | `private_key_jwt` | Client-assertion lifetime, max `3600`.                             |
+### What the gateway does at request time
+On a tool call to the route, the gateway:
+1. Resolves the user's stored IdP identity assertion (bound during the inbound
+   browser login). If absent or expired, it returns a connect-required error and
+   refreshes the subject token when it can.
+2. Runs an RFC 8693 token exchange at `idp.tokenUrl`, requesting an ID-JAG
+   audience-restricted to `resourceAs.audience`.
+3. Redeems the ID-JAG at `resourceAs.tokenUrl` as an RFC 7523 JWT-bearer grant
+   to get the upstream access token.
+4. Caches the upstream token per user and forwards the tool call with
+   `Authorization: Bearer <upstream token>`.
+## Notes and limitations
+- The gateway issues **opaque** access tokens, not JWTs.
+- **DPoP is not supported.** Requests with a `DPoP` header are rejected.
+- XAA requires a prior inbound browser login so the gateway has an IdP identity
+  assertion to exchange.
+## Related
+- [Overview](./overview.mdx) — the protocol and the gateway's role.
+- [Quickstart](./quickstart.mdx) — a working `id-jag` configuration on the
+  playground.
+- [`mcp-token-exchange-inbound` policy](/policies/mcp-token-exchange-inbound) —
+  the base token-exchange policy reference.

package/docs/mcp-gateway/cross-app-access/quickstart.mdx ADDED Viewed

@@ -0,0 +1,330 @@
+---
+title: "Cross App Access quickstart"
+sidebar_label: "Quickstart"
+description: |
+  Build a Zuplo MCP Gateway that reaches an XAA-protected MCP server in the
+  Zuplo Portal — no repository to clone. The gateway fronts Okta's hosted
+  xaa.dev Todo0 server and performs the Cross App Access (XAA) token exchange on
+  every request.
+---
+This quickstart builds a working Cross App Access (XAA) gateway entirely in the
+Zuplo Portal. An MCP client connects to the gateway with ordinary OAuth; the
+gateway then performs the XAA token exchange against
+[Okta's hosted xaa.dev playground](https://xaa.dev) and reaches the protected
+Todo0 MCP server on the user's behalf.
+There is no repository to clone and no identity tenant to stand up. Everything
+runs in the portal against the public xaa.dev playground.
+## Why xaa.dev
+[xaa.dev](https://xaa.dev) is Okta's hosted Cross App Access playground: a
+public identity provider, resource authorization server, and Todo0 MCP server
+that are already wired together for the XAA token exchange. Standing up your own
+XAA stack means provisioning an IdP, a resource authorization server, and a
+protected MCP server — and configuring the trust relationships between all
+three. The playground gives you all of that for free, so today it's the fastest
+way to see a real Cross App Access flow end to end. Once the gateway works
+against xaa.dev, swapping in your own identity provider and upstream is just a
+change of endpoints and credentials.
+## What you'll build
+A single gateway route with two policies does all the work:
+- An **MCP OAuth** policy (`mcp-oauth-inbound`) secures the client → gateway
+  leg. The client authenticates to the gateway with plain MCP OAuth — this leg
+  is not XAA.
+- A **token-exchange** policy (`mcp-token-exchange-inbound`) in `id-jag` mode
+  performs the outbound XAA exchange to the upstream: it mints an ID-JAG at the
+  playground identity provider (IdenX), redeems it at the resource authorization
+  server, and calls the Todo0 MCP server with the resulting access token.
+The XAA exchange happens entirely on the gateway's outbound side. See
+[the overview](./overview.mdx#how-the-flow-works) for the full sequence.
+## Prerequisites
+- A [Zuplo account](https://portal.zuplo.com)
+- A free account on [xaa.dev](https://xaa.dev)
+- [MCP Jam](https://www.mcpjam.com) — a browser-based MCP client used to drive
+  the flow. Any MCP client that supports OAuth works.
+## Steps
+<Stepper>
+1. **Create a Zuplo project.**
+   In the [Zuplo Portal](https://portal.zuplo.com/+/account/projects), select
+   **New Project** and create an empty **API Gateway** project. Name it
+   `xaa-quick-start`.
+   On the project **Overview** page, copy the deployment URL shown at the top
+   (for example, `https://xaa-quick-start-main-abc1234.d2.zuplo.dev`). This is
+   your gateway's public origin — you'll need it for the next two steps.
+   :::note
+   Throughout this guide, replace `https://your-gateway.zuplo.dev` with your
+   project's actual deployment URL.
+   :::
+2. **Register a requesting app on xaa.dev.**
+   Sign in to [xaa.dev](https://xaa.dev) and open
+   [the developer registration page](https://xaa.dev/developer/register). Enter
+   your email, then select **Register New App** and fill in:
+   - **Application Name** — anything, for example `xaa-quick-start gateway`.
+   - **Redirect URIs** — your gateway's OAuth callback:
+     ```text
+     https://your-gateway.zuplo.dev/__zuplo/oauth/callback
+     ```
+   Under **Resource Connections**, select **Todo0 MCP Server**, keep both scopes
+   (`todos.read` and `mcp.access`) checked, and select **Add Connection**. Then
+   select **Register App**.
+   <BrowserScreenshot url="https://xaa.dev/developer/register">
+   ![Registered requesting app on xaa.dev](../../../public/media/cross-app-access/xaa-playground.png)
+   </BrowserScreenshot>
+   Registration shows four values. Copy all of them — the secrets are shown only
+   once:
+   | xaa.dev value          | Used for                        |
+   | ---------------------- | ------------------------------- |
+   | Client ID              | `XAA_CLIENT_ID`                 |
+   | Client Secret          | `XAA_CLIENT_SECRET`             |
+   | Resource Client ID     | `XAA_RESOURCE_AS_CLIENT_ID`     |
+   | Resource Client Secret | `XAA_RESOURCE_AS_CLIENT_SECRET` |
+   :::tip
+   The playground identity provider (IdenX) accepts any email with no password,
+   so you can sign in as any test user when you drive the flow.
+   :::
+3. **Add the gateway configuration.**
+   Open the project's code editor (the **Code** tab). The gateway needs three
+   files.
+   First, define the two policies. Open `config/policies.json` (use the raw
+   `policies.json` tab, not the visual Policy List) and replace its contents:
+   ```json title="config/policies.json"
+   {
+     "policies": [
+       {
+         "name": "xaa-inbound",
+         "policyType": "mcp-oauth-inbound",
+         "handler": {
+           "module": "$import(@zuplo/runtime/mcp-gateway)",
+           "export": "McpOAuthInboundPolicy",
+           "options": {
+             "oidc": {
+               "issuer": "https://idp.xaa.dev",
+               "jwksUrl": "https://idp.xaa.dev/jwks",
+               "audience": "$env(GATEWAY_AUDIENCE)"
+             },
+             "browserLogin": {
+               "url": "https://idp.xaa.dev/authorize",
+               "tokenUrl": "https://idp.xaa.dev/token",
+               "clientId": "$env(XAA_CLIENT_ID)",
+               "clientSecret": "$env(XAA_CLIENT_SECRET)",
+               "scope": "openid profile email",
+               "audience": "$env(GATEWAY_AUDIENCE)",
+               "pkce": "S256"
+             }
+           }
+         }
+       },
+       {
+         "name": "id-jag-upstream",
+         "policyType": "mcp-token-exchange-inbound",
+         "handler": {
+           "module": "$import(@zuplo/runtime/mcp-gateway)",
+           "export": "McpTokenExchangeInboundPolicy",
+           "options": {
+             "id": "id-jag-upstream",
+             "displayName": "Todo0",
+             "summary": "xaa.dev Todo0 MCP server, reached via Cross App Access (ID-JAG).",
+             "authMode": "id-jag",
+             "idJag": {
+               "scopes": ["todos.read", "mcp.access"],
+               "idp": {
+                 "tokenUrl": "https://idp.xaa.dev/token",
+                 "clientAuth": {
+                   "method": "client_secret_post",
+                   "clientId": "$env(XAA_CLIENT_ID)",
+                   "clientSecret": "$env(XAA_CLIENT_SECRET)"
+                 }
+               },
+               "resourceAs": {
+                 "tokenUrl": "https://auth.resource.xaa.dev/token",
+                 "audience": "https://auth.resource.xaa.dev",
+                 "resource": "https://mcp.xaa.dev/mcp",
+                 "clientAuth": {
+                   "method": "client_secret_post",
+                   "clientId": "$env(XAA_RESOURCE_AS_CLIENT_ID)",
+                   "clientSecret": "$env(XAA_RESOURCE_AS_CLIENT_SECRET)"
+                 }
+               }
+             }
+           }
+         }
+       }
+     ]
+   }
+   ```
+   The IdP, resource authorization server, and upstream endpoints are wired to
+   the playground here. Only the credentials and the gateway audience are
+   environment-driven, so you can plug in your own xaa.dev app. For every
+   option, see the [configuration reference](./policy-reference.mdx).
+   Next, add the route that exposes the gateway. Open `config/routes.oas.json`
+   (the raw `routes.oas.json` tab) and replace its contents:
+   ```json title="config/routes.oas.json"
+   {
+     "openapi": "3.1.0",
+     "info": {
+       "version": "1.0.0",
+       "title": "XAA MCP Gateway",
+       "description": "MCP gateway that bridges to the xaa.dev Todo0 MCP server via Cross App Access (ID-JAG)."
+     },
+     "paths": {
+       "/mcp/todo0": {
+         "post": {
+           "operationId": "todo0Bridge",
+           "summary": "Bridge to the xaa.dev Todo0 MCP server",
+           "x-zuplo-route": {
+             "corsPolicy": "none",
+             "handler": {
+               "module": "$import(@zuplo/runtime/mcp-gateway)",
+               "export": "McpProxyHandler",
+               "options": {
+                 "rewritePattern": "https://mcp.xaa.dev/mcp"
+               }
+             },
+             "policies": {
+               "inbound": ["xaa-inbound", "id-jag-upstream"]
+             }
+           }
+         }
+       }
+     }
+   }
+   ```
+   The `McpProxyHandler` forwards the request to the upstream Todo0 server, and
+   both policies run inbound — first the MCP OAuth check, then the XAA exchange.
+   Finally, register the MCP Gateway plugin. In the file tree, right-click the
+   `modules` folder, select **New Runtime Extension**, and replace the generated
+   file's contents:
+   ```typescript title="modules/zuplo.runtime.ts"
+   import { RuntimeExtensions } from "@zuplo/runtime";
+   import { McpGatewayPlugin } from "@zuplo/runtime/mcp-gateway";
+   // Registers the MCP Gateway, which adds the OAuth and upstream-connection
+   // routes used to expose and secure MCP servers through your gateway.
+   // Docs: https://zuplo.com/docs/mcp-server/introduction
+   export function runtimeInit(runtime: RuntimeExtensions) {
+     runtime.addPlugin(new McpGatewayPlugin());
+   }
+   ```
+   Save each file. The build fails until the environment variables exist —
+   that's the next step.
+4. **Set the environment variables.**
+   Open **Settings →
+   [Environment Variables](https://portal.zuplo.com/+/account/project/settings/environment-variables)**
+   and add each variable below with **Add variable**. Mark the two `*_SECRET`
+   values as **Secret** so they're encrypted and hidden after saving. Leave all
+   three environments (Production, Preview, Development) selected.
+   | Variable                        | Value                                                                         | Secret |
+   | ------------------------------- | ----------------------------------------------------------------------------- | ------ |
+   | `GATEWAY_AUDIENCE`              | Your gateway's deployment URL (for example, `https://your-gateway.zuplo.dev`) | No     |
+   | `XAA_CLIENT_ID`                 | Client ID from the xaa.dev app                                                | No     |
+   | `XAA_CLIENT_SECRET`             | Client Secret from the xaa.dev app                                            | Yes    |
+   | `XAA_RESOURCE_AS_CLIENT_ID`     | Resource Client ID from the Todo0 connection                                  | No     |
+   | `XAA_RESOURCE_AS_CLIENT_SECRET` | Resource Client Secret from the Todo0 connection                              | Yes    |
+   Saving an environment variable triggers a new deployment. Once it finishes,
+   the gateway is live.
+5. **Connect with MCP Jam and list the todos.**
+   Open the [MCP Jam web inspector](https://www.mcpjam.com), go to **Connect**,
+   and select **Add Server**:
+   - **Server Name** — `xaa-quick-start`
+   - **Connection Type** — `HTTPS`, with the route URL
+     `https://your-gateway.zuplo.dev/mcp/todo0`
+   - **Authentication** — `OAuth`
+   <ModalScreenshot>
+   ![Add the gateway as an MCP server in MCP Jam](../../../public/media/cross-app-access/add-mcp-server.png)
+   </ModalScreenshot>
+   Select **Add Server**. MCP Jam starts the OAuth flow and redirects you to
+   sign in. Sign in at the IdenX screen (any email, no password) and approve the
+   consent screen. MCP Jam returns to the inspector and the server shows as
+   **Connected**.
+   <Framed>
+   ![The gateway connected in MCP Jam](../../../public/media/cross-app-access/connected-card.png)
+   </Framed>
+   Open the **Resources** panel and select **List all todos**. The todos come
+   back as JSON — the agent never touched the XAA protocol. Behind the scenes
+   the gateway minted an ID-JAG from the playground IdP, redeemed it at the
+   resource authorization server, and called the Todo0 MCP server with the
+   resulting access token.
+   <Framed>
+   ![Todo0 resources and todos returned through the gateway in MCP Jam](../../../public/media/cross-app-access/todo-resources.png)
+   </Framed>
+</Stepper>
+## Verify from the command line (optional)
+To confirm the gateway is deployed and secured without a client, check its OAuth
+metadata and the protected route:
+```bash
+# Protected-resource metadata is published for the route (expect 200)
+curl -s https://your-gateway.zuplo.dev/.well-known/oauth-protected-resource/mcp/todo0
+# The MCP route rejects unauthenticated calls (expect 401)
+curl -s -o /dev/null -w "%{http_code}\n" -X POST \
+  https://your-gateway.zuplo.dev/mcp/todo0 \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1.0.0"}}}'
+```
+## Next steps
+- [Configuration reference](./policy-reference.mdx) — the full `idJag` option
+  set.
+- [Overview](./overview.mdx) — the protocol and the gateway's role explained.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "6.71.11",
+  "version": "6.71.13",
   "type": "module",
   "description": "The programmable API Gateway",
   "author": "Zuplo, Inc.",
@@ -19,9 +19,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "6.71.11",
-    "@zuplo/core": "6.71.11",
-    "@zuplo/runtime": "6.71.11",
+    "@zuplo/cli": "6.71.13",
+    "@zuplo/core": "6.71.13",
+    "@zuplo/runtime": "6.71.13",
     "@zuplo/test": "1.4.0"
   }
 }