zuplo 6.67.32 → 6.68.0

package/docs/policies/caching-inbound/doc.md

@@ -0,0 +1,209 @@
+The Caching Inbound policy allows you to cache responses from your API
+endpoints, significantly improving performance and reducing load on your backend
+services. This policy stores responses in a distributed cache and serves them
+directly from the cache for subsequent identical requests.
+
+## How It Works
+
+When a request is received, the policy checks if a cached response exists for
+that request:
+
+1. The policy generates a unique cache key based on the request method, URL,
+   query parameters, and optionally specified headers
+2. If a valid cached response is found and not expired:
+   - The cached response is returned immediately
+   - The request never reaches your backend services
+3. If no cached response is found or the cache has expired:
+   - The request proceeds to your backend services normally
+   - The response is stored in the cache for future use
+   - The TTL (time-to-live) is set according to your configuration
+
+This process dramatically reduces response times for frequently requested
+resources and minimizes the load on your backend infrastructure.
+
+### expirationSecondsTtl
+
+This setting determines how long (in seconds) a cached response remains valid
+before it expires. Choose a value based on how frequently your data changes:
+
+- For static content: Consider longer TTLs (3600+ seconds)
+- For semi-dynamic content: Moderate TTLs (300-3600 seconds)
+- For frequently changing data: Shorter TTLs (60-300 seconds)
+
+### cachedId
+
+An optional string identifier that becomes part of the cache key. This is
+primarily used for cache-busting purposes (see the Cache-Busting section below).
+
+### headers
+
+An array of header names that should be included when generating the cache key.
+By default, only the request method, URL, and query parameters are used. Adding
+headers to this array allows for more granular caching based on header values.
+
+Common headers to consider including:
+
+- `Accept` - To cache different response formats separately
+- `Accept-Language` - To cache language-specific responses
+- `User-Agent` - To cache device-specific responses
+
+### dangerouslyIgnoreAuthorizationHeader
+
+When set to `false` (default), the Authorization header is included in the cache
+key, ensuring that cached responses are only served to users with the same
+authorization level. Setting this to `true` will ignore the Authorization header
+when generating the cache key, which could potentially expose sensitive data to
+unauthorized users.
+
+**Security Warning**: Only use `dangerouslyIgnoreAuthorizationHeader: true` when
+you're certain that the cached responses don't contain user-specific or
+sensitive information.
+
+## Example Configuration
+
+```json
+{
+  "export": "CachingInboundPolicy",
+  "module": "$import(@zuplo/runtime)",
+  "options": {
+    "cachedId": "$env(CACHE_ID)", // this is reading an env var
+    "expirationSecondsTtl": 60,
+    "dangerouslyIgnoreAuthorizationHeader": false,
+    "headers": ["header_used_as_part_of_cache_key"]
+  }
+}
+```
+
+Advanced configuration with cache-busting and header-based caching:
+
+```json
+{
+  "export": "CachingInboundPolicy",
+  "module": "$import(@zuplo/runtime)",
+  "options": {
+    "cachedId": "$env(CACHE_ID)",
+    "expirationSecondsTtl": 300,
+    "headers": ["Accept", "Accept-Language"],
+    "dangerouslyIgnoreAuthorizationHeader": false
+  }
+}
+```
+
+## Cache Key Generation
+
+By default, the cache key is generated based on the request method, URL, and
+query parameters. You can also include specific headers in the cache key by
+listing them in the `headers` option.
+
+The cache key is a unique identifier generated for each request. By default, it
+includes:
+
+1. Request method (GET, POST, etc.)
+2. URL path
+3. Query parameters
+4. Authorization header (unless explicitly ignored)
+5. Any additional headers specified in the `headers` option
+6. The `cachedId` value (if provided)
+
+This ensures that only identical requests receive the same cached response.
+
+## Cache-Busting
+
+If you need to support cache-busting on demand, we recommend applying a
+`cacheId` property based on an Environment Variable. Ensure all your cache
+policies are using a cachedId based on a variable and then change that variable
+(and trigger a redeploy) to clear the cache.
+
+Then you would setup an env var for this, we recommend using the current date it
+was set, e.g. `2023-07-05-11-57` and then simply change this value and trigger a
+redeploy to bust your cache.
+
+![Env Var](https://cdn.zuplo.com/uploads/CleanShot%202023-07-05%20at%2011.57.48%402x.png)
+
+### Additional Cache-Busting Strategies
+
+#### Using Environment Variables
+
+The recommended approach for cache-busting is to use an environment variable for
+the `cachedId` option:
+
+1. Set up an environment variable (e.g., `CACHE_ID`) with a value that includes
+   a timestamp
+2. Configure your policy to use this variable: `"cachedId": "$env(CACHE_ID)"`
+3. When you need to invalidate all cached responses:
+   - Update the environment variable value (e.g., to the current timestamp)
+   - Trigger a redeploy of your API
+
+#### Using Query Parameters
+
+For more targeted cache-busting, you can instruct clients to include a version
+or timestamp query parameter in their requests. Since query parameters are part
+of the cache key by default, this will result in a cache miss and a fresh
+response.
+
+## Best Practices
+
+1. **Identify Cacheable Endpoints**: Focus on caching endpoints that:
+   - Receive frequent identical requests
+   - Return responses that don't change frequently
+   - Have computationally expensive backend operations
+
+2. **Set Appropriate TTLs**: Balance freshness against performance:
+   - Too short: Underutilizes caching benefits
+   - Too long: Risks serving stale data
+
+3. **Use Cache-Busting Wisely**: Have a strategy for invalidating caches when
+   data changes unexpectedly
+
+4. **Monitor Cache Performance**: Keep track of cache hit rates and response
+   times to optimize your caching strategy
+
+5. **Consider Security Implications**: Be careful with caching authenticated
+   responses, especially when they contain user-specific data
+
+## Common Use Cases
+
+- **Public Data Endpoints**: Weather data, stock prices, public statistics
+- **Product Catalogs**: Product listings, category pages, search results
+- **Content Delivery**: Blog posts, documentation, static assets
+- **API Responses**: Third-party API responses that don't change frequently
+
+## Limitations
+
+- The policy only caches successful responses (status codes 200-299)
+- Very large responses may not be suitable for caching
+- Streaming responses are not cached
+
+## Security Considerations
+
+By default, the Authorization header is included in the cache key to ensure that
+cached responses are only served to users with the same authorization level. If
+you set `dangerouslyIgnoreAuthorizationHeader` to `true`, the Authorization
+header will be ignored when generating the cache key.
+
+**Warning**: Setting `dangerouslyIgnoreAuthorizationHeader` to `true` could
+potentially expose sensitive data to unauthorized users if your responses
+contain user-specific information. Only use this option when you're certain that
+the cached responses don't contain user-specific or sensitive information.
+
+## Troubleshooting
+
+If you're experiencing issues with the caching policy:
+
+1. **Responses Not Being Cached**:
+   - Verify the request method is cacheable (GET, HEAD are most common)
+   - Check that the response status code is in the 200-299 range
+   - Ensure the request doesn't include headers that vary the response but
+     aren't included in your cache key
+
+2. **Cache Not Being Invalidated**:
+   - Verify your cache-busting strategy is working correctly
+   - Check that the `cachedId` is being updated properly
+   - Confirm that your TTL settings are appropriate
+
+3. **Unexpected Behavior**:
+   - Review which headers are included in your cache key
+   - Check if `dangerouslyIgnoreAuthorizationHeader` is set correctly for your
+     use case
+   - Verify that query parameters that should affect caching are properly
+     included in requests

package/docs/policies/caching-inbound/intro.md

@@ -0,0 +1,23 @@
+The Caching Inbound policy allows you to cache responses from your API
+endpoints, significantly improving performance and reducing load on your backend
+services.
+
+With this policy, you'll benefit from:
+
+- **Improved Performance**: Dramatically reduce response times by serving cached
+  content
+- **Reduced Backend Load**: Minimize the number of requests that reach your
+  backend services
+- **Cost Optimization**: Lower infrastructure costs by reducing compute and
+  database load
+- **Scalability**: Handle traffic spikes more effectively without scaling
+  backend resources
+- **Configurable TTL**: Set appropriate cache expiration times based on your
+  data's volatility
+- **Selective Caching**: Include specific headers in cache keys for more
+  granular control
+- **Cache Busting**: Easily invalidate all cached responses when needed
+
+The policy stores responses in a distributed cache and serves them directly for
+subsequent identical requests, bypassing your backend services entirely when a
+valid cached response exists.

package/docs/policies/caching-inbound/schema.json

@@ -0,0 +1,98 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Caching",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Respond to matched incoming requests with cached content",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "CachingInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "CachingInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": [],
+          "properties": {
+            "cacheId": {
+              "type": "string",
+              "examples": ["my-key"],
+              "x-show-example": false,
+              "description": "Specifies an id or 'key' for this policy to store cache. This is useful for cache-busting. For example, set this property to an env var and if you change that env var value, you invalidate the cache."
+            },
+            "dangerouslyIgnoreAuthorizationHeader": {
+              "type": "boolean",
+              "x-show-example": false,
+              "default": false,
+              "description": "By default, the Authorization header is always considered in the caching policy. You can disable by setting this to `true`."
+            },
+            "headers": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "examples": ["content-type"],
+              "default": [],
+              "description": "The headers to be considered when caching."
+            },
+            "cacheHttpMethods": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "enum": ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"]
+              },
+              "default": ["GET"],
+              "description": "HTTP Methods to be cached. Valid methods are: GET, POST, PUT, PATCH, DELETE, HEAD."
+            },
+            "expirationSecondsTtl": {
+              "type": "number",
+              "default": 60,
+              "description": "The timeout of the cache in seconds."
+            },
+            "statusCodes": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              },
+              "examples": [[200, 201, 404]],
+              "default": [[200, 206, 301, 302, 303, 404, 410]],
+              "description": "Response status codes to be cached."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "CachingInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "cacheHttpMethods": ["GET"],
+            "expirationSecondsTtl": 60,
+            "headers": "content-type",
+            "statusCodes": [200, 201, 404]
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/change-method-inbound/schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Change Method",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Changes the HTTP method of the incoming request.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "ChangeMethodInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "ChangeMethodInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": ["method"],
+          "properties": {
+            "method": {
+              "type": "string",
+              "examples": ["POST"],
+              "description": "The HTTP Method to be used, e.g. POST, GET, PUT, PATCH, etc."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "ChangeMethodInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "method": "POST"
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/clear-headers-inbound/schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Clear Request Headers",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Removes all headers from the incoming request except for those in the exclude list.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "ClearHeadersInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "ClearHeadersInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": [],
+          "properties": {
+            "exclude": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "examples": [["my-header", "aws-request-id"]],
+              "description": "The headers that should not be removed."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "ClearHeadersInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "exclude": ["my-header", "aws-request-id"]
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/clear-headers-outbound/schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Clear Response Headers",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Removes all headers from the response except for those in the exclude list.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "ClearHeadersOutboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "ClearHeadersOutboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": [],
+          "properties": {
+            "exclude": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "examples": [["my-header", "aws-request-id"]],
+              "description": "The headers that should not be removed."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "ClearHeadersOutboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "exclude": ["my-header", "aws-request-id"]
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/clerk-jwt-auth-inbound/doc.md

@@ -0,0 +1,85 @@
+Adding Clerk authentication to your route takes just a few steps. Follow the
+instructions below to setup Clerk and the Clerk policy.
+
+## Setup Clerk
+
+If you haven't already done so, create a Clerk account and follow one of their
+[Quickstarts](https://clerk.com/docs/quickstarts/overview) to create a client
+app that can obtain an access token.
+
+In order to setup your policy in the API, you'll need to navigate to the
+[Clerk Dashboard](https://dashboard.clerk.com/) and Navigate to the
+[API Keys](https://dashboard.clerk.com/last-active?path=api-keys) section. Click
+**Advanced** at the bottom of the page and copy the value of the **Frontend API
+URL**. You'll use this value later in your API policy configuration.
+
+### Set Environment Variables
+
+Before adding the policy, you'll need to create an environment variable to store
+the Clerk Frontend API URL.
+
+1. In the [Zuplo Portal](https://portal.zuplo.com) open the **Environment
+   Variables** section in the **Settings** tab.
+
+2. Click **Add new Variable** and enter the name `CLERK_FRONTEND_API_URL` in the
+   name field. Set the value to the value you copied previously from the Clerk
+   dashboard.
+
+### Add the Clerk Policy
+
+The next step is to add the Clerk JWT Auth policy to a route in your project.
+
+1. In the [Zuplo Portal](https://portal.zuplo.com) open the **Route Designer**
+   in the **Files** tab then click **routes.oas.json**.
+
+2. Select or create a route that you want to authenticate with Clerk. Expand the
+   **Policies** section and click **Add Policy**. Search for and select the
+   Clerk JWT Auth policy.
+
+   <Screenshot src="https://cdn.zuplo.com/assets/c4bab517-1e42-4f68-83ce-b0ee4adca713.png" />
+
+3. With the policy selected, notice that there is a property `frontendApiUrl`
+   that are pre-populated with environment variable names that you set in the
+   previous section.
+
+  <Screenshot src="https://cdn.zuplo.com/assets/85d90802-d919-47c6-b944-c6ec3574a714.png" size="md" />
+ 
+4. Click **OK** to save the policy.
+
+### Test the Policy
+
+Finally, you'll make two API requests to your route to test that authentication
+is working as expected.
+
+1. In the route designer on the route you added the policy, click the **Test**
+   button. In the dialog that opens, click **Test** to make a request.
+
+2. The API Gateway should respond with a **401 Unauthorized** response.
+
+  <Screenshot src="https://cdn.zuplo.com/assets/626e10a2-2350-439a-9081-1ccf1fe90cad.png" size="md" />
+
+3. Now to make an authenticated request, add a header to the request called
+   `Authorization`. Set the value of the header to `Bearer YOUR_ACCESS_TOKEN`
+   replacing `YOUR_ACCESS_TOKEN` with the value of the Clerk access token
+   retrieved from your client app.
+
+  <Screenshot src="https://cdn.zuplo.com/assets/1486821b-cade-4041-b05b-80d3366327a5.png" size="lg" />
+
+4. Click the **Test** button and a **200 OK** response should be returned.
+
+  <Screenshot src="https://cdn.zuplo.com/assets/8182f932-8db6-4456-842f-f65158b174c0.png" size="md" />
+
+You have now setup Clerk JWT Authentication on your API Gateway.
+
+## OAuth 2.0 Protected Resource Metadata
+
+The Clerk JWT Auth policy supports OAuth protected resource metadata discovery.
+To enable this feature, set the `oAuthResourceMetadataEnabled` option to `true`
+and add the
+[`OAuthProtectedResourcePlugin` to `modules/zuplo.runtime.ts`](/docs/programmable-api/oauth-protected-resource-plugin).
+When configured, this enables OAuth clients to find metadata information about
+how to interact with your OAuth 2.0 protected resources according to
+[`RFC 9728`](https://datatracker.ietf.org/doc/html/rfc9728).
+
+See [this document](/docs/articles/oauth-authentication) for more information
+about OAuth authorization in Zuplo.

package/docs/policies/clerk-jwt-auth-inbound/intro.md

@@ -0,0 +1,4 @@
+Authenticate requests with JWT tokens issued by Clerk. This is a customized
+version of the
+[OpenId JWT Policy](https://zuplo.com/docs/policies/open-id-jwt-auth-inbound)
+specifically for Clerk.

package/docs/policies/clerk-jwt-auth-inbound/schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Clerk JWT Auth",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Authenticate users using Clerk issued JWT tokens.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "ClerkJwtInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "ClerkJwtInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": ["frontendApiUrl"],
+          "properties": {
+            "allowUnauthenticatedRequests": {
+              "type": "boolean",
+              "default": false,
+              "description": "Allow unauthenticated requests to proceed. This is use useful if you want to use multiple authentication policies or if you want to allow both authenticated and non-authenticated traffic."
+            },
+            "frontendApiUrl": {
+              "type": "string",
+              "examples": ["https://sensible-skunk-49.clerk.accounts.dev"],
+              "description": "Your Clerk frontend api url, i.e. `https://sensible-skunk-49.clerk.accounts.dev`. Can be found in the Clerk portal: https://dashboard.clerk.com/last-active?path=api-keys."
+            },
+            "oAuthResourceMetadataEnabled": {
+              "type": "boolean",
+              "default": false,
+              "description": "Flag that determines whether OAuth protected resource metadata is enabled."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "ClerkJwtInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "allowUnauthenticatedRequests": false,
+            "frontendApiUrl": "https://sensible-skunk-49.clerk.accounts.dev",
+            "oAuthResourceMetadataEnabled": false
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/cognito-jwt-auth-inbound/intro.md

@@ -0,0 +1,7 @@
+Authenticate requests with JWT tokens issued by AWS Cognito. This is a
+customized version of the
+[OpenId JWT Policy](https://zuplo.com/docs/policies/open-id-jwt-auth-inbound)
+specifically for AWS Cognito.
+
+See [this document](https://zuplo.com/docs/articles/oauth-authentication) for
+more information about OAuth authorization in Zuplo.