zuplo 6.70.69 → 6.70.70

package/docs/programmable-api/jwt-service-plugin.mdx

@@ -16,11 +16,13 @@ issued by your API.
 
 ## JWT Token
 
-This service currently issues JWTs using the EdDSA algorithm. This is the
+By default, this service issues JWTs using the EdDSA algorithm. This is the
 recommended algorithm for new applications due to its strong security properties
-and performance characteristics. However, it's important to note that not every
-library supports EdDSA, so you should ensure that your
-[client library](https://jwt.io/libraries) can handle this algorithm.
+and performance characteristics. However, not every library supports EdDSA, so
+you should ensure that your [client library](https://jwt.io/libraries) can
+handle this algorithm. If you need a different algorithm (for example, for
+compatibility with an existing key pair or client library), use the `algorithm`
+configuration option.
 
 ## Use Cases
 
@@ -68,9 +70,9 @@ export function runtimeInit(runtime: RuntimeExtensions) {
     // Custom base path for the issuer endpoint (default: "/__zuplo/issuer")
     basePath: "/custom",
 
-    // Token expiration time (default: 300 seconds)
+    // Token expiration time (default: "1h")
     // Can be a number (seconds) or a time span string
-    tokenExpiration: "5m", // or 300 for seconds
+    expiresIn: "5m", // or 300 for seconds
   };
 
   const jwtService = new JwtServicePlugin(options);
@@ -84,8 +86,16 @@ export function runtimeInit(runtime: RuntimeExtensions) {
   is `"/__zuplo/issuer"`. This affects the issuer URL and OIDC configuration
   endpoints.
 
-- **`tokenExpiration`** (optional): Sets the default expiration time for JWTs.
-  Can be either:
+- **`algorithm`** (optional): The asymmetric signing algorithm used for issued
+  JWTs. Default is `"EdDSA"`. Supported values are `EdDSA`, `RS256`, `RS384`,
+  `RS512`, `PS256`, `PS384`, `PS512`, `ES256`, `ES384`, and `ES512`. The
+  algorithm must match the configured key pair — for example, an RSA key
+  requires an `RS*` or `PS*` value and an Ed25519 key requires `EdDSA`.
+  Symmetric algorithms (like `HS256`) aren't supported because the plugin
+  publishes a JWKS endpoint.
+
+- **`expiresIn`** (optional): Sets the default expiration time for JWTs. Default
+  is `"1h"`. Can be either:
   - A **number**: Direct value in seconds (for example, `300` for 5 minutes)
   - A **string**: Time span format (for example, `"5 minutes"`, `"1 hour"`,
     `"7 days"`)
@@ -101,11 +111,11 @@ export function runtimeInit(runtime: RuntimeExtensions) {
   Examples:
 
   ```ts
-  tokenExpiration: 300; // 300 seconds
-  tokenExpiration: "5 minutes"; // 5 minutes
-  tokenExpiration: "2 hours"; // 2 hours
-  tokenExpiration: "7 days"; // 7 days
-  tokenExpiration: "30 mins"; // 30 minutes
+  expiresIn: 300; // 300 seconds
+  expiresIn: "5 minutes"; // 5 minutes
+  expiresIn: "2 hours"; // 2 hours
+  expiresIn: "7 days"; // 7 days
+  expiresIn: "30 mins"; // 30 minutes
   ```
 
   Note: Individual JWT creation can override this default by specifying
@@ -180,61 +190,44 @@ export default async function (request: ZuploRequest, context: ZuploContext) {
 ## Validating JWTs in Upstream Services
 
 Upstream services can validate the JWTs issued by your Zuplo API by verifying
-the signature and claims. Here's an example of how to validate JWTs in different
-environments:
+the signature and claims. The examples below use `EdDSA`, the plugin's default
+signing algorithm. If you configured a different algorithm using the `algorithm`
+option, use that value in the `algorithms` list instead.
 
 ### Node.js/Express Example
 
-```js title="validate-jwt.js"
-const jwt = require("jsonwebtoken");
-const jwksClient = require("jwks-rsa");
+This example uses the [`jose`](https://github.com/panva/jose) library because
+the popular `jsonwebtoken` library doesn't support the EdDSA algorithm.
+
+```js title="validate-jwt.mjs"
+import { createRemoteJWKSet, jwtVerify } from "jose";
 
 // Replace with your actual Zuplo deployment name or custom domain
 const ISSUER = "https://my-api.zuplo.app/__zuplo/issuer";
 
-// Create a JWKS client to fetch public keys
-const client = jwksClient({
-  jwksUri: `${ISSUER}/.well-known/jwks.json`,
-  cache: true,
-  cacheMaxAge: 600000, // 10 minutes
-});
-
-// Function to get the signing key
-function getKey(header, callback) {
-  client.getSigningKey(header.kid, function (err, key) {
-    if (err) {
-      return callback(err);
-    }
-    const signingKey = key.getPublicKey();
-    callback(null, signingKey);
-  });
-}
+// Create a remote JWK Set that fetches and caches the public keys
+const JWKS = createRemoteJWKSet(new URL(`${ISSUER}/.well-known/jwks.json`));
 
 // Middleware to validate JWT
-function validateJwt(req, res, next) {
+async function validateJwt(req, res, next) {
   const token = req.headers.authorization?.replace("Bearer ", "");
 
   if (!token) {
     return res.status(401).json({ error: "No token provided" });
   }
 
-  jwt.verify(
-    token,
-    getKey,
-    {
+  try {
+    const { payload } = await jwtVerify(token, JWKS, {
       issuer: ISSUER,
-      algorithms: ["RS256"],
-    },
-    (err, decoded) => {
-      if (err) {
-        return res
-          .status(401)
-          .json({ error: "Invalid token", details: err.message });
-      }
-      req.user = decoded;
-      next();
-    },
-  );
+      algorithms: ["EdDSA"],
+    });
+    req.user = payload;
+    next();
+  } catch (err) {
+    return res
+      .status(401)
+      .json({ error: "Invalid token", details: err.message });
+  }
 }
 
 // Example usage
@@ -248,11 +241,18 @@ app.get("/protected", validateJwt, (req, res) => {
 
 ### Python/FastAPI Example
 
+EdDSA validation in PyJWT requires the `cryptography` package. Install PyJWT
+with the crypto extra: `pip install pyjwt[crypto]`.
+
+The keys in Zuplo's JWKS don't include a `kid`, so this example loads the key
+directly from the JWKS document rather than using `PyJWKClient`, which only
+matches keys by `kid`.
+
 ```python title="validate_jwt.py"
 from fastapi import FastAPI, Depends, HTTPException, Security
 from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
 import jwt
-from jwt import PyJWKClient
+from jwt import PyJWK
 import requests
 
 app = FastAPI()
@@ -262,21 +262,21 @@ security = HTTPBearer()
 ISSUER = "https://my-api.zuplo.app/__zuplo/issuer"
 JWKS_URL = f"{ISSUER}/.well-known/jwks.json"
 
-# Initialize JWKS client
-jwks_client = PyJWKClient(JWKS_URL)
+def get_signing_key() -> PyJWK:
+    # Zuplo publishes a single signing key. Consider caching this
+    # response briefly to avoid fetching the JWKS on every request.
+    jwks = requests.get(JWKS_URL, timeout=10).json()
+    return PyJWK.from_dict(jwks["keys"][0])
 
 async def validate_token(credentials: HTTPAuthorizationCredentials = Security(security)):
     token = credentials.credentials
 
     try:
-        # Get the signing key from JWKS
-        signing_key = jwks_client.get_signing_key_from_jwt(token)
-
         # Verify and decode the token
         payload = jwt.decode(
             token,
-            signing_key.key,
-            algorithms=["RS256"],
+            get_signing_key(),
+            algorithms=["EdDSA"],
             issuer=ISSUER,
             options={"verify_exp": True}
         )
@@ -297,9 +297,11 @@ async def protected_route(token_data: dict = Depends(validate_token)):
 
 ### Dynamic OIDC Discovery
 
-For more flexible JWT validation, you can use a library to dynamically discover
-the OIDC configuration based on the issuer claim in the JWT. This example uses
-the [`oauth4webapi`](https://github.com/panva/oauth4webapi) library.
+For more flexible JWT validation, you can dynamically discover the OIDC
+configuration based on the issuer claim in the JWT. This example fetches the
+issuer's OIDC discovery document to find the JWKS endpoint, then verifies the
+token with the same [`jose`](https://github.com/panva/jose) library used in the
+Node.js example above.
 
 :::warning{title="Security Warning"}
 
@@ -310,8 +312,19 @@ ensure you are only allowing tokens from trusted issuers.
 
 :::
 
-```js title="validate-jwt-dynamic.js"
-import * as oauth from "oauth4webapi";
+```ts title="validate-jwt-dynamic.ts"
+import { createRemoteJWKSet, decodeJwt, jwtVerify } from "jose";
+import type { JWTPayload } from "jose";
+import type { NextFunction, Request, Response } from "express";
+
+// Make the verified JWT payload available as req.user
+declare global {
+  namespace Express {
+    interface Request {
+      user?: JWTPayload;
+    }
+  }
+}
 
 const ALLOWED_ISSUERS = [
   "https://my-api.zuplo.app/__zuplo/issuer",
@@ -319,59 +332,66 @@ const ALLOWED_ISSUERS = [
   // Add more allowed issuers as needed
 ];
 
-async function validateJwtDynamic(token) {
-  try {
-    // Decode the JWT header and payload without verification first
-    const parts = token.split(".");
-    if (parts.length !== 3) {
-      throw new Error("Invalid JWT format");
+// Cache the remote JWK Set for each issuer so discovery only runs once.
+// jose handles JWKS caching and key rotation automatically.
+const jwksCache = new Map<string, ReturnType<typeof createRemoteJWKSet>>();
+
+async function getJwks(issuer: string) {
+  let jwks = jwksCache.get(issuer);
+  if (!jwks) {
+    // Discover the OIDC configuration for the issuer
+    const response = await fetch(`${issuer}/.well-known/openid-configuration`);
+    if (!response.ok) {
+      throw new Error(`OIDC discovery failed with status ${response.status}`);
     }
-
-    const payload = JSON.parse(
-      atob(parts[1].replace(/-/g, "+").replace(/_/g, "/")),
-    );
-
-    // Extract the issuer from the token
-    const issuer = payload.iss;
-    if (!issuer) {
-      throw new Error("No issuer claim in token");
+    const metadata = (await response.json()) as {
+      issuer?: string;
+      jwks_uri?: string;
+    };
+    if (metadata.issuer !== issuer) {
+      throw new Error("Discovery document issuer mismatch");
     }
-
-    // Validate the issuer against allowed issuers
-    if (!ALLOWED_ISSUERS.includes(issuer)) {
-      throw new Error(`Issuer ${issuer} isn't allowed`);
+    if (!metadata.jwks_uri) {
+      throw new Error("Issuer metadata is missing jwks_uri");
     }
+    jwks = createRemoteJWKSet(new URL(metadata.jwks_uri));
+    jwksCache.set(issuer, jwks);
+  }
+  return jwks;
+}
+
+async function validateJwtDynamic(token: string): Promise<JWTPayload> {
+  // Read the issuer claim without verifying the signature yet
+  const { iss: issuer } = decodeJwt(token);
+  if (!issuer) {
+    throw new Error("No issuer claim in token");
+  }
 
-    // Discover the OIDC configuration
-    const issuerUrl = new URL(issuer);
-    const as = await oauth
-      .discoveryRequest(issuerUrl)
-      .then((response) => oauth.processDiscoveryResponse(issuerUrl, response));
-
-    // Get the JWKS
-    const jwks = await oauth
-      .jwksRequest(as)
-      .then((response) => oauth.processJwksResponse(response));
-
-    // Import the JWT and validate it
-    const { payload: verifiedPayload, protectedHeader } =
-      await oauth.validateJwt(token, jwks, {
-        issuer: issuer,
-        audience: payload.aud, // Optional: validate audience
-      });
-
-    return verifiedPayload;
-  } catch (error) {
-    throw new Error(`JWT validation failed: ${error.message}`);
+  // Validate the issuer against the allow list before fetching anything
+  if (!ALLOWED_ISSUERS.includes(issuer)) {
+    throw new Error(`Issuer ${issuer} isn't allowed`);
   }
+
+  // Verify the signature and standard claims
+  const { payload } = await jwtVerify(token, await getJwks(issuer), {
+    issuer,
+    algorithms: ["EdDSA"],
+  });
+
+  return payload;
 }
 
 // Express middleware example
-function validateJwtMiddleware(req, res, next) {
+function validateJwtMiddleware(
+  req: Request,
+  res: Response,
+  next: NextFunction,
+) {
   const token = req.headers.authorization?.replace("Bearer ", "");
 
   if (!token) {
-    return res.status(401).json({ error: "No token provided" });
+    res.status(401).json({ error: "No token provided" });
+    return;
   }
 
   validateJwtDynamic(token)
@@ -379,8 +399,10 @@ function validateJwtMiddleware(req, res, next) {
       req.user = payload;
       next();
     })
-    .catch((error) => {
-      res.status(401).json({ error: error.message });
+    .catch((error: Error) => {
+      res
+        .status(401)
+        .json({ error: `JWT validation failed: ${error.message}` });
     });
 }
 

package/docs/programmable-api/runtime-behaviors.mdx

@@ -21,5 +21,7 @@ for `Request.body` specifies that on `GET` and `HEAD` requests the value must be
 `null`. Different APIs, networks, and gateways follow this spec to varying
 degrees. In some cases they allow in others they don't.
 
-By default, Zuplo will return a 500 error in the event that a `GET` or `HEAD`
-request has a body.
+By default, Zuplo removes the body from any `GET` or `HEAD` request and adds a
+`zp-body-removed: true` header so your backend knows the body was removed. The
+request then proceeds as normal. For more details, including an example policy
+that rejects these requests, see [zp-body-removed](./zp-body-removed.mdx).

package/docs/programmable-api/streaming-zone-cache.mdx

@@ -75,12 +75,10 @@ export default async function handler(
   // Cache the response for 1 hour (3600 seconds)
   await cache.put(cacheKey, streamForCache, 3600);
 
-  return new Response(streamForResponse, {
-    headers: {
-      ...response.headers,
-      "X-Cache": "MISS",
-    },
-  });
+  const headers = new Headers(response.headers);
+  headers.set("X-Cache", "MISS");
+
+  return new Response(streamForResponse, { headers });
 }
 ```
 

package/docs/programmable-api/web-crypto-apis.mdx

@@ -96,15 +96,19 @@ async function sign(value: string, secret: string) {
 
   // `mac` is an ArrayBuffer, so you need to make a few changes to get
   // it into a ByteString, and then a Base64-encoded string.
-  let base64Mac = btoa(String.fromCharCode(...new Uint8Array(mac)));
-
-  // must convert "+" to "-" as urls encode "+" as " "
-  base64Mac = base64Mac.replaceAll("+", "-");
-
-  return base64Mac;
+  return btoa(String.fromCharCode(...new Uint8Array(mac)));
 }
 ```
 
+:::note
+
+The signature is standard Base64 and can contain the characters `+`, `/`, and
+`=`. If you transport the signature in a URL — for example, as a query parameter
+— encode it with `encodeURIComponent()` first, or convert it to the URL-safe
+Base64 alphabet on both the signing and verifying sides.
+
+:::
+
 ### Verify a Value
 
 ```ts

package/package.json

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

package/docs/errors/get-head-body-error.mdx

@@ -1,41 +0,0 @@
----
-title: GET/HEAD Body Error (GET_HEAD_BODY_ERROR)
----
-
-A GET or HEAD request included a body, which is not allowed. The
-[Fetch specification](https://fetch.spec.whatwg.org/) defines that GET and HEAD
-requests must not have a request body.
-
-## Why this happens
-
-The HTTP specification states that GET and HEAD requests are intended for
-retrieving resources and should not include a request body. While some HTTP
-clients allow sending a body with GET requests, the Zuplo runtime enforces the
-specification and rejects these requests.
-
-## How to fix
-
-- **Use a different HTTP method** - If the request needs to send data in the
-  body, use `POST`, `PUT`, or `PATCH` instead of `GET` or `HEAD`.
-- **Move data to query parameters** - If the request must remain a `GET`,
-  convert the body data to URL query parameters.
-- **Remove the body** - If the body was included unintentionally, remove it from
-  the request.
-
-## Common causes
-
-- **HTTP client defaults** - Some HTTP client libraries or frameworks
-  automatically attach a body to requests, even for GET methods. Check the
-  client configuration.
-- **Copied request configuration** - A request configuration copied from a POST
-  endpoint may still include a body when adapted for a GET endpoint.
-- **Framework behavior** - Certain frontend frameworks or API testing tools may
-  silently include an empty body or content-type header on GET requests.
-
-:::note
-
-This is a client-side issue. Update the request on the calling side to remove
-the body or change the HTTP method. No changes are needed on the Zuplo gateway
-configuration.
-
-:::