zuplo 6.67.32 → 6.68.0

package/docs/policies/archive-response-azure-storage-outbound/schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/archive-response-azure-storage-outbound.json",
+  "type": "object",
+  "title": "Archive Response to Azure Storage",
+  "isCustom": true,
+  "products": ["api-gateway"],
+  "description": "Archive the outgoing response to Azure blob storage.",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "default",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(./modules/YOUR_MODULE)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "type": "object",
+          "description": "The options for this policy",
+          "required": [],
+          "properties": {
+            "blobCreateSas": {
+              "type": "string",
+              "description": "The Azure shared access token with permission to write to the bucket"
+            },
+            "blobContainerPath": {
+              "type": "string",
+              "description": "The path to the Azure blob container"
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "_name": "basic",
+          "export": "default",
+          "module": "$import(./modules/YOUR_MODULE)",
+          "options": {
+            "blobCreateSas": "$env(BLOB_CREATE_SAS)",
+            "blobContainerPath": "$env(BLOB_CONTAINER_PATH)"
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/audit-log-inbound/doc.md

@@ -0,0 +1,78 @@
+## Adding Custom Metadata
+
+You can add any additional data to the audit logs with a custom function.
+
+:::note
+
+Custom metadata functions cannot be asynchronous. Due to the frequency of their
+calls, asynchronous functions will add significant latency to your API.
+
+:::
+
+```ts
+//module - ./modules/audit-logs.ts
+
+import { ZuploRequest } from "@zuplo/runtime";
+
+export function auditLogMetadata(request: ZuploRequest): any {
+  const metadata = {
+    accountId: request.user.data.account,
+    customTraceId: request.headers.get("custom-trace-id"),
+  };
+  return metadata;
+}
+```
+
+## Log Data
+
+The structure of an audit log is shown below.
+
+```json
+{
+  "route": "/customers/:customerId",
+  "method": "GET",
+  "query": {
+    "a": 1,
+    "b": 2
+  },
+  "params": {
+    "customerId": "12345"
+  },
+  "headers": {
+    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.41 Safari/537.36"
+  },
+  "user": {
+    "sub": "user|12356"
+  },
+  "geolocation": {
+    "country": "US",
+    "city": "Seattle",
+    "continent": "NA",
+    "latitude": "1.123",
+    "longitude": "4.567",
+    "postalCode": "29700",
+    "metroCode": "100",
+    "region": "Washington",
+    "timezone": "America/LosAngeles"
+  },
+  "metadata": {
+    // Custom data
+  }
+}
+```
+
+## Audit Logs in the Portal
+
+Audit logs are not currently surfaced in the Zuplo portal, but the feature is
+planned soon.
+
+## Audit Log API
+
+Audit logs can be retrieved using the Zuplo Management API. Logs can be
+retrieved by time span and can be filtered by `tenant`.
+
+```http
+GET /deployments/:deploymentId/auditlogs?tenant=TENANT
+content-type: application/json
+authorization: Bearer YOUR_TOKEN
+```

package/docs/policies/audit-log-inbound/intro.md

@@ -0,0 +1,10 @@
+Audit logging is an important part of API security that plays a critical role in
+detecting and correcting issues such as unauthorized access or permission
+elevations within your system. Audit logging is also a requirement for many
+compliance certifications as well as part of the buying criteria for larger
+enterprises.
+
+Adding Audit Logging to your APIs that are secured with Zuplo is as easy as
+adding a policy. Typically you want to add audit logs to any API that modifies
+data, however depending on the API you may want it on read operations as well
+(i.e. retrieve a secret key, etc.)

package/docs/policies/audit-log-inbound/schema.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Audit Logs",
+  "isDeprecated": false,
+  "isPaidAddOn": true,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Capture detailed logs of requests for auditing purposes.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "AuditLogsInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "AuditLogsInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": ["blockScoresBelow"],
+          "properties": {
+            "logIpAddress": {
+              "default": true,
+              "description": "if the IP address should be logged."
+            },
+            "logUser": {
+              "default": true,
+              "description": "if the user's `sub` should be logged."
+            },
+            "logGeolocation": {
+              "default": true,
+              "description": "if the geolocation information should be logged (i.e. state, country, longitude, latitude, etc.)."
+            },
+            "logQueryParameters": {
+              "default": true,
+              "description": "log the values of query parameters."
+            },
+            "logRouteParameters": {
+              "default": true,
+              "description": "The parameters in the route to log."
+            },
+            "tenant": {
+              "description": "if the route parameters should be logged (i.e. the value of `customerId` in the route `/customers/:customerId`)."
+            },
+            "metadata": {
+              "description": "A function to add additional data to the audit logs."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "AuditLogsInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "logGeolocation": true,
+            "logIpAddress": true,
+            "logQueryParameters": true,
+            "logRouteParameters": true,
+            "logUser": true
+          }
+        }
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,125 @@
+Adding Auth0 to your route takes just a few steps, but before you can add the
+policy you'll need to have Auth0 set up for API Authentication.
+
+### Set Up Auth0
+
+To use Auth0 as an API authentication provider, you'll need to create both an
+Application and an API in the Auth0 dashboard. The steps below cover the basics,
+but if you need more details see the Auth0 links throughout this document.
+
+1. Create the Auth0 API
+   ([Auth0 Doc](https://auth0.com/docs/get-started/auth0-overview/set-up-apis))
+
+   In the Auth0 dashboard, select **APIs** on the sidebar, then click the **+
+   Create API** button.
+
+   Enter the **Name** and **Identifier** of your application. The identifier is
+   usually a URI such as `https://api.example.com/`. The URL used in the
+   identifier does NOT have to be the URL of your actual API. A common practice
+   is to use the URL of your production API. Save this value, you'll use it in
+   the next section.
+
+2. Get the Auth0 Domain
+
+   On your newly created Auth0 API, click the **Test** tab. This tab shows how
+   to create a
+   [Machine-to-Machine](https://auth0.com/docs/get-started/authentication-and-authorization-flow/call-your-api-using-the-client-credentials-flow)
+   access token from a test application that Auth0 automatically created for
+   your API.
+
+   From the first code block on this page, find the URL value as shown below.
+   Copy the **hostname** portion (outlined in red) of this URL (not the
+   `https://` or the trailing `/oauth/token` parts). For example
+   `your-account.us.auth0.com`. Save this value, you'll use it in the next
+   section.
+
+   <Screenshot src="https://cdn.zuplo.com/assets/53f91f6d-17c2-469d-9e23-ac3beb9a804b.png" alt="Auth0 Access Token" />
+
+3. Get an Access Token
+
+   Find the code block that contains the `access_token` and copy the **entire**
+   token value (without the quotes) and save it. You'll use this later to test
+   your Auth0 JWT policy in Zuplo.
+
+   <Screenshot src="https://cdn.zuplo.com/assets/991dbd66-2bb9-4bc1-8ae0-8d928b5dcb7e.png" alt="Auth0 Access Token" />
+
+### Set Environment Variables
+
+Before adding the policy, there are a few environment variables that will need
+to be set that will be used in the Auth0 JWT Policy.
+
+:::caution
+
+It is very important in the next steps that the values match **EXACTLY** as they
+are found in Auth0.
+
+:::
+
+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 `AUTH0_DOMAIN` in the name
+   field. Set the value to your Auth0 domain.
+
+3. Click **Add new Variable** again and enter the name `AUTH0_AUDIENCE` in the
+   name field. Set the value to the **identifier** URI you used when creating
+   the Auth0 API in the section above (i.e. `https://api.example.com/`).
+
+### Add the Auth0 Policy
+
+The next step is to add the Auth0 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 Auth0. Expand the
+   **Policies** section and click **Add Policy**. Search for and select the
+   Auth0 JWT Auth policy.
+
+   <Screenshot src="https://cdn.zuplo.com/assets/40c72bc5-be30-4246-809c-58d4ecb18f9e.png" />
+
+3. With the policy selected, notice that there are two properties, `auth0Domain`
+   and `audience` that are pre-populated with environment variable names that
+   you set in the previous section.
+
+   <Screenshot src="https://cdn.zuplo.com/assets/2aa3fc6a-0e9c-47f6-b08d-c1cc446e54b9.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 Auth0 access token you
+   saved from the first section of this tutorial.
+
+   <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 set up Auth0 JWT Authentication on your API Gateway.
+
+## OAuth 2.0 Protected Resource Metadata
+
+The Auth0 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/auth0-jwt-auth-inbound/intro.md

@@ -0,0 +1,17 @@
+Authenticate requests with JWT tokens issued by Auth0. This is a customized
+version of the
+[OpenId JWT Policy](https://zuplo.com/docs/policies/open-id-jwt-auth-inbound)
+specifically for Auth0.
+
+With this policy, you'll benefit from:
+
+- **Seamless Auth0 Integration**: Pre-configured to work with Auth0's JWT format
+  and signature validation
+- **Enhanced Security**: Protect your APIs with industry-standard authentication
+  backed by Auth0's robust identity platform
+- **Simplified Implementation**: Reduce development time with ready-to-use Auth0
+  validation logic
+- **Flexible Configuration**: Easily customize claims validation, token sources,
+  and audience verification
+- **Comprehensive User Context**: Access user claims and metadata directly in
+  your request handlers

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

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Auth0 JWT Auth",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Authenticate users using Auth0 issued JWT tokens.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "Auth0JwtInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "Auth0JwtInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": ["auth0Domain"],
+          "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."
+            },
+            "auth0Domain": {
+              "type": "string",
+              "examples": ["my-company.auth0.com"],
+              "description": "Your Auth0 domain. For example, `my-company.auth0.com`."
+            },
+            "audience": {
+              "type": "string",
+              "examples": ["https://api.example.com/"],
+              "description": "The Auth0 audience of your API, for example `https://api.example.com/`."
+            },
+            "oAuthResourceMetadataEnabled": {
+              "type": "boolean",
+              "default": false,
+              "description": "Flag that determines whether OAuth protected resource metadata is enabled."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "Auth0JwtInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "allowUnauthenticatedRequests": false,
+            "audience": "https://api.example.com/",
+            "auth0Domain": "my-company.auth0.com",
+            "oAuthResourceMetadataEnabled": false
+          }
+        }
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,24 @@
+By default, the policy will use the `subject`, `resource`, and `action`
+properties from the policy options file, with the special `$authzen-prop()`
+syntax to reference dynamic values.
+
+However, you can also have programmatic control over the payload sent to the PDP
+by setting the payload wholly or partially using the `setAuthorizationContext`
+method in a custom policy _before_ the AuthZenInboundPolicy.
+
+```ts
+AuthZenInboundPolicy.setAuthorizationPayload(context, {
+  subject: {
+    type: "user",
+    id: request.user.data.organization,
+  },
+  resource: {
+    type: "pizza",
+    id: ContextData.get(context, "pizza-size"),
+  },
+  action: { name: request.method },
+});
+```
+
+This object will be combined with the one generated by the options with this
+authorization payload set on context taking priority.

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

@@ -0,0 +1,31 @@
+This policy will authorize requests using a PDP (Policy Decision Point) service
+that is compatible with the AuthZen standard. Read more about the
+[AuthZen working group](https://openid.net/wg/authzen/).
+
+It is designed to be extremely simple to configure, with a default configuration
+that can dynamically read the `subject`, `resource` and `action` id from the
+Zuplo request or context objects using the special
+`$authzen-prop(request.headers.user-id)` syntax.
+
+Example options:
+
+```json
+{
+  "authorizerHostname": "authzen.example.com",
+  "subject": {
+    "type": "identity",
+    "id": "$authzen-prop(request.user.sub)"
+  },
+  "resource": {
+    "type": "route",
+    "id": "$authzen-prop(context.route.path)"
+  },
+  "action": {
+    "name": "$authzen-prop(request.method)"
+  },
+  "throwOnError": true // defaults to true if not specified
+}
+```
+
+Note, the `$authzen-prop` syntax only works on this policy and on the `id` and
+`name` properties.

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

@@ -0,0 +1,126 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "AuthZEN Authorization",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": true,
+  "isInternal": false,
+  "isBeta": true,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Authorize requests using an AuthZEN compatible PDP",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "AuthZenInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "AuthZenInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": ["authorizerHostname", "subject", "resource", "action"],
+          "properties": {
+            "authorizerHostname": {
+              "type": "string",
+              "description": "The hostname of the AuthZen PDP service.",
+              "examples": ["authzen.example.com"]
+            },
+            "authorizerAuthorizationHeader": {
+              "type": "string",
+              "description": "The authorization header to use when communicating with the AuthZen PDP service.",
+              "examples": ["Bearer $env(AUTHZEN_PDP_TOKEN)"]
+            },
+            "subject": {
+              "type": "object",
+              "description": "The subject of the request.",
+              "required": ["type", "id"],
+              "properties": {
+                "type": {
+                  "type": "string",
+                  "description": "The type of the resource.",
+                  "examples": ["identity"]
+                },
+                "id": {
+                  "type": "string",
+                  "description": "The id of the resource. Note you can use the `$authzen-prop()` syntax to reference the resource id.",
+                  "examples": ["$authzen-prop(request.user.sub)"]
+                }
+              }
+            },
+            "resource": {
+              "type": "object",
+              "description": "The resource of the request. Note you can use the `$authzen-prop()` syntax to reference the resource id.",
+              "required": ["type", "id"],
+              "properties": {
+                "type": {
+                  "type": "string",
+                  "description": "The type of the resource.",
+                  "examples": ["route"]
+                },
+                "id": {
+                  "type": "string",
+                  "description": "The id of the resource. Note you can use the `$authzen-prop()` syntax to reference the resource id.",
+                  "examples": ["$authzen-prop(context.route.path)"]
+                }
+              }
+            },
+            "action": {
+              "type": "object",
+              "description": "The action of the request. Note you can use the `$authzen-prop()` syntax to reference the action.",
+              "required": ["name"],
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "description": "The name of the action. Note you can use the `$authzen-prop()` syntax to reference the action name.",
+                  "examples": ["$authzen-prop(request.method)"]
+                }
+              }
+            },
+            "throwOnError": {
+              "type": "boolean",
+              "description": "If explicitly set to false, the policy will not throw an error if there is any problem communicating with the AuthZen PDP service and allow calls through. By default throwOnError is assumed to be on/true.",
+              "default": true,
+              "examples": [true]
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "AuthZenInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "action": {
+              "name": "$authzen-prop(request.method)"
+            },
+            "authorizerAuthorizationHeader": "Bearer $env(AUTHZEN_PDP_TOKEN)",
+            "authorizerHostname": "authzen.example.com",
+            "resource": {
+              "id": "$authzen-prop(context.route.path)",
+              "type": "route"
+            },
+            "subject": {
+              "id": "$authzen-prop(request.user.sub)",
+              "type": "identity"
+            },
+            "throwOnError": true
+          }
+        }
+      ]
+    }
+  }
+}