zuplo 6.67.32 → 6.68.0

package/docs/policies/transform-body-inbound/policy.ts

@@ -0,0 +1,16 @@
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  // Get the incoming body as an Object
+  const obj = await request.json();
+
+  // Modify the object as required
+  obj.myNewProperty = "Hello World";
+
+  // Stringify the object
+  const body = JSON.stringify(obj);
+
+  // Return a new request based on the
+  // original but with the new body
+  return new ZuploRequest(request, { body });
+}

package/docs/policies/transform-body-inbound/schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/transform-body-inbound.json",
+  "type": "object",
+  "title": "Transform Request Body",
+  "isCustom": true,
+  "products": ["api-gateway"],
+  "description": "Transform the body of an incoming request.",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module"],
+      "properties": {
+        "export": {
+          "const": "default",
+          "description": "The export from the custom policy"
+        },
+        "module": {
+          "const": "$import(./modules/YOUR_MODULE)",
+          "description": "The module containing the policy"
+        }
+      }
+    }
+  }
+}

package/docs/policies/transform-body-outbound/intro.md

@@ -0,0 +1,8 @@
+This example policy shows how to use `response.json()` to read the outgoing
+response as a JSON object. The object can then be modified as appropriate. It's
+then converted back to a string and a new `Response` is returned in the policy
+with the new body.
+
+If the incoming response body isn't JSON, you can use `response.text()` or
+`response.blob()` to access the contents as raw text or a
+[blob](https://developer.mozilla.org/en-US/docs/Web/API/Response/blob).

package/docs/policies/transform-body-outbound/policy.ts

@@ -0,0 +1,19 @@
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function (
+  response: Response,
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  // Get the outgoing body as an Object
+  const obj = await response.json();
+
+  // Modify the object as required
+  obj.myNewProperty = "Hello World";
+
+  // Stringify the object
+  const body = JSON.stringify(obj);
+
+  // Return a new response with the new body
+  return new Response(body, request);
+}

package/docs/policies/transform-body-outbound/schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/transform-body-outbound.json",
+  "type": "object",
+  "title": "Transform Response Body",
+  "isCustom": true,
+  "products": ["api-gateway"],
+  "description": "Transform the body of an outgoing response.",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module"],
+      "properties": {
+        "export": {
+          "const": "default",
+          "description": "The export from the custom policy"
+        },
+        "module": {
+          "const": "$import(./modules/YOUR_MODULE)",
+          "description": "The module containing the policy"
+        }
+      }
+    }
+  }
+}

package/docs/policies/upstream-azure-ad-service-auth-inbound/doc.md

@@ -0,0 +1,82 @@
+This policy authenticates your Zuplo gateway to Azure AD-protected backend
+services by automatically adding an OAuth 2.0 Bearer token to the
+`Authorization` header of upstream requests. It uses the Azure AD client
+credentials flow to obtain access tokens.
+
+### How It Works
+
+The policy performs the following operations:
+
+1. Requests an access token from Azure AD using the configured client
+   credentials
+2. Caches the token for subsequent requests until it nears expiration
+3. Adds the token to the `Authorization` header as a Bearer token
+4. Automatically handles token renewal when needed
+
+### Policy Configuration
+
+Configure the policy with your Azure AD application credentials:
+
+```json
+{
+  "name": "azure-ad-service-auth",
+  "export": "UpstreamAzureAdServiceAuthInboundPolicy",
+  "module": "$import(@zuplo/runtime)",
+  "options": {
+    "activeDirectoryTenantId": "YOUR_TENANT_ID",
+    "activeDirectoryClientId": "YOUR_CLIENT_ID",
+    "activeDirectoryClientSecret": "$env(AZURE_CLIENT_SECRET)",
+    "tokenRetries": 3,
+    "expirationOffsetSeconds": 300
+  }
+}
+```
+
+### Usage Example
+
+#### Securing Azure Function App Access
+
+Apply the policy to routes that need to access your Azure Function App:
+
+```json
+{
+  "paths": {
+    "/api/data": {
+      "get": {
+        "x-zuplo-route": {
+          "policies": {
+            "inbound": ["jwt-auth", "azure-ad-service-auth"]
+          },
+          "handler": {
+            "export": "forwardToOrigin",
+            "module": "$import(@zuplo/runtime)",
+            "options": {
+              "baseUrl": "https://your-function-app.azurewebsites.net"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Azure AD Configuration
+
+To use this policy, you need to:
+
+1. Create an Azure AD app registration for your Zuplo gateway
+2. Generate a client secret for the app registration
+3. Configure your backend service (e.g., Azure Functions, App Service) to use
+   Azure AD authentication
+4. Grant the necessary permissions for your app registration to access your
+   backend service
+
+### Security Considerations
+
+- Store the client secret as an environment variable using `$env(VARIABLE_NAME)`
+  syntax
+- Ensure your Azure AD app has the minimum required permissions to access your
+  backend services
+- Consider using managed identities for Azure resources when possible
+- Regularly rotate your client secrets according to your security policies

package/docs/policies/upstream-azure-ad-service-auth-inbound/intro.md

@@ -0,0 +1,20 @@
+Secure your origin server with Azure Active Directory authentication by
+automatically adding an `Authorization` header to upstream requests. This policy
+enables your Zuplo gateway to authenticate with Azure AD-protected services
+using client credentials flow.
+
+With this policy, you'll benefit from:
+
+- **Enhanced Backend Security**: Restrict access to your origin servers to only
+  your Zuplo gateway
+- **Simplified Authentication**: Delegate authentication and authorization to
+  your gateway without backend code changes
+- **Automatic Token Management**: Handle token acquisition, caching, and renewal
+  automatically
+- **Azure Integration**: Seamlessly connect with Azure App Services, Functions,
+  and other Azure AD-protected resources
+- **Credential Security**: Store sensitive Azure AD credentials securely in your
+  Zuplo environment
+
+For instructions on configuring Azure AD authentication, see
+[Configure your App Service or Azure Functions app to use Azure AD login](https://learn.microsoft.com/en-us/azure/app-service/configure-authentication-provider-aad).

package/docs/policies/upstream-azure-ad-service-auth-inbound/schema.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Upstream Azure AD Service Auth",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": true,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Uses Azure Active Directory to add an Authorization header to the request in order to authenticate requests using Azure identity.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "UpstreamAzureAdServiceAuthInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "UpstreamAzureAdServiceAuthInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": [
+            "activeDirectoryTenantId",
+            "activeDirectoryClientId",
+            "activeDirectoryClientSecret"
+          ],
+          "properties": {
+            "activeDirectoryTenantId": {
+              "type": "string",
+              "examples": ["b8e4141e-31f4-43e3-9a96-f97f3eba1eea"],
+              "description": "Azure Active Directory Tenant ID."
+            },
+            "activeDirectoryClientId": {
+              "type": "string",
+              "examples": ["20edbb34-13e9-42d0-a63c-1b6a0a20d02d"],
+              "description": "The Application (client) ID of the Azure AD App Registration."
+            },
+            "activeDirectoryClientSecret": {
+              "type": "string",
+              "examples": ["$env(ACTIVE_DIRECTORY_CLIENT_SECRET)"],
+              "description": "The client secret of the Azure AD App Registration."
+            },
+            "tokenRetries": {
+              "type": "number",
+              "default": 3,
+              "description": "The number of times to retry fetching the token in the event of a failure.."
+            },
+            "expirationOffsetSeconds": {
+              "type": "number",
+              "default": 300,
+              "description": "The number of seconds less than the token expiration to cache the token."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "UpstreamAzureAdServiceAuthInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "activeDirectoryClientId": "20edbb34-13e9-42d0-a63c-1b6a0a20d02d",
+            "activeDirectoryClientSecret": "$env(ACTIVE_DIRECTORY_CLIENT_SECRET)",
+            "activeDirectoryTenantId": "b8e4141e-31f4-43e3-9a96-f97f3eba1eea",
+            "expirationOffsetSeconds": 300,
+            "tokenRetries": 3
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/upstream-firebase-admin-auth-inbound/intro.md

@@ -0,0 +1,10 @@
+This policy adds a Firebase Admin token to the outgoing `Authentication` header
+allowing requests to Firebase using Service Account admin permissions. This can
+be useful for calling Firebase services such as Firestore through a Zuplo
+endpoint that is secured with other means of Authentication such as API keys.
+Additionally, this policy can be useful for service content to all API users
+(for example serving a specific Firestore document containing configuration
+data)
+
+We recommend reading the `serviceAccountJson` from environment variables (so it
+is not checked in to source control) using the `$env(ENV_VAR)` syntax.

package/docs/policies/upstream-firebase-admin-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": "Upstream Firebase Admin Auth",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Creates a Firebase Admin token and attaches it to the outgoing request. Useful when calling Firebase services as an administrator.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "UpstreamFirebaseAdminAuthInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "UpstreamFirebaseAdminAuthInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": ["serviceAccountJson"],
+          "properties": {
+            "serviceAccountJson": {
+              "type": "string",
+              "examples": ["$env(SERVICE_ACCOUNT_JSON)"],
+              "description": "The Google Service Account key in JSON format. Note you can load this from environment variables using the $env(ENV\\_VAR) syntax."
+            },
+            "tokenRetries": {
+              "type": "number",
+              "default": 3,
+              "description": "The number of times to retry fetching the token in the event of a failure."
+            },
+            "expirationOffsetSeconds": {
+              "type": "number",
+              "default": 300,
+              "description": "The number of seconds less than the token expiration to cache the token."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "UpstreamFirebaseAdminAuthInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "expirationOffsetSeconds": 300,
+            "serviceAccountJson": "$env(SERVICE_ACCOUNT_JSON)",
+            "tokenRetries": 3
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/upstream-firebase-user-auth-inbound/intro.md

@@ -0,0 +1,2 @@
+This policy adds a Firebase user token to the outgoing `Authentication` header
+allowing requests to Firebase using the provided user's permissions.

package/docs/policies/upstream-firebase-user-auth-inbound/schema.json

@@ -0,0 +1,113 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Upstream Firebase User Auth",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Creates a Firebase custom user token and attaches it to the outgoing request. Useful when calling Firebase services as user.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "UpstreamFirebaseUserAuthInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "UpstreamFirebaseUserAuthInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": ["serviceAccountJson", "webApiKey"],
+          "properties": {
+            "serviceAccountJson": {
+              "type": "string",
+              "examples": ["$env(SERVICE_ACCOUNT_JSON)"],
+              "description": "The Google Service Account key in JSON format. Note you can load this from environment variables using the $env(ENV\\_VAR) syntax."
+            },
+            "userId": {
+              "type": "string",
+              "examples": ["1234"],
+              "description": "The userId to use as the custom token's subject."
+            },
+            "userIdPropertyPath": {
+              "type": "string",
+              "description": "The property on the incoming request.user object to retrieve the value of the userId."
+            },
+            "developerClaims": {
+              "type": "object",
+              "tsType": "Record<string, string | number | boolean | null>",
+              "additionalItems": {
+                "oneOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "boolean"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "examples": [
+                {
+                  "premium": true
+                }
+              ],
+              "description": "Additional claims to include in the custom token's payload."
+            },
+            "webApiKey": {
+              "type": "string",
+              "examples": ["$env(WEB_API_KEY)"],
+              "description": "The Firebase Web API Key (found in project settings)"
+            },
+            "tokenRetries": {
+              "type": "number",
+              "default": 3,
+              "description": "The number of times to retry fetching the token in the event of a failure."
+            },
+            "expirationOffsetSeconds": {
+              "type": "number",
+              "default": 300,
+              "description": "The number of seconds less than the token expiration to cache the token."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "UpstreamFirebaseUserAuthInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "developerClaims": {
+              "premium": true
+            },
+            "expirationOffsetSeconds": 300,
+            "serviceAccountJson": "$env(SERVICE_ACCOUNT_JSON)",
+            "tokenRetries": 3,
+            "userId": "1234",
+            "webApiKey": "$env(WEB_API_KEY)"
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/upstream-gcp-federated-auth-inbound/doc.md

@@ -0,0 +1,139 @@
+Before you can use this policy, you will need to have configured the following:
+
+- Setup Workload Identity Federation in your GCP project
+- Create a GCP service account with the appropriate permissions.
+
+### Setup GCP Workload Identity Federation
+
+Setting up Workload Identity Federation for Zuplo follows the instructions for
+setting up a standard OIDC Identity Provider. Refer to
+[Google's Documentation for additional details](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#configure).
+
+To begin, navigate to the
+[Workload Identity page of Google Cloud Console](https://console.cloud.google.com/iam-admin/workload-identity-pools).
+You will find this in the **IAM** section on the menu.
+
+If you don't already have one, create a new Workload Identity Pool. Then create
+a new provider and select **OpenID Connect** as the provider type.
+
+Complete the following values in the form:
+
+- **Provider name**: Any Value
+- **Provider ID**: Any Value
+- **Issuer (URL)**:
+  `https://dev.zuplo.com/v1/client-auth/auth_o8PUdhKxSTOiB794GWPwLQCD`
+- **JWK File**: Do not set this value, GCP will perform automatic discovery of
+  the OAuth configuration.
+- **Audiences**: Select "Default Audience"
+
+Copy the URL value for the **Default Audience** and record it for later use.
+
+Click **Continue** and set the follow provider attribute mappings.
+
+- `google.subject` =>
+  `"zuplo::" + assertion.account + "::" + assertion.project + "::" + assertion.deployment`
+- `attributes.account` => `assertion.account`
+- `attributes.project` => `assertion.project`
+- `attributes.deployment` => `assertion.deployment`
+
+You can read about all the claims in the
+[Zuplo Identity Token](https://zuplo.com/docs/articles/zuplo-id-token)
+documentation.
+
+Set **Attribute Conditions**
+
+:::caution Important Security Step
+
+It is critical that you set at minimum the `attribute.account == "my-account"`
+attribute condition. Without this restriction ANY Zuplo API would be able to
+call your resources.
+
+:::
+
+Set the attribute conditions you want to use to restrict access to this Workload
+Identity Pool. Generally, you only need to set this to restrict the account. You
+will use IAM bindings to grant specific permissions in later steps.
+
+To set the account condition set the following value.
+
+```
+attribute.account == "my-account"
+```
+
+If you want to set further conditions, you can do so as desired, for example to
+restrict access to all environments in a project set the following.
+
+```txt
+attribute.account == "my-account" && attribute.project == "my-project"
+```
+
+### Create a Service Account
+
+You Zuplo Identity Token will be granted access to act as if it where a service
+account in your Google project. As such, you will need to create a service
+account.
+
+You can do so in the Google console or using the Google CLI:
+
+```shell
+gcloud iam service-accounts create zuplo-api \
+  –-description="zuplo api sa"  \
+  –-display-name="zuplo-api"
+```
+
+Next you need to create role binding for the Zuplo principal to impersonate the
+service account:
+
+- `SERVICE_ACCOUNT_EMAIL` is the email address of the service account.
+- `PROJECT_NUMBER` is your numeric Google project number.
+- `POOL_ID` is the id of the Workload Identity Pool you created earlier, for
+  example `zuplo-pool`.
+- `SUBJECT` is the same the concatenated value we set to the value of
+  `google.subject` earlier. For example,
+  `zuplo::my-account::my-project::my-deployment-1235`
+
+```shell
+gcloud iam service-accounts add-iam-policy-binding $SERVICE_ACCOUNT_EMAIL \
+    --role roles/iam.workloadIdentityUser \
+    --member "principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/subject/$SUBJECT
+```
+
+Finally, grant your service account the permissions desired. For example, to
+invoke Cloud Run services grant the `roles/run.invoker`
+
+- `SERVICE_ACCOUNT_EMAIL` is the email address of the service account.
+- `SERVICE_NAME` is the name of your Cloud Run service.
+
+```shell
+gcloud run services add-iam-policy-binding $SERVICE_NAME
+  --member-"serviceAccount:$SERVICE_ACCOUNT_EMAIL" \
+  --role="roles/run.invoker"
+```
+
+### Set the Policy Options
+
+With GCP Workload Federation setup, you can add the policy to your Zuplo API.
+
+- `audience`: Set this to the resource you are planning to call, for example,
+  the Cloud Run URL.
+- `serviceAccountEmail` - Set this value to the email address of the service
+  account previously created.
+- `workloadIdentityProvider` - Set this to the value that was copied when
+  setting up your Workload Identity Pool (called **Default Audience**). Remove
+  the beginning `https://iam.googleapis.com/` part of the string.
+
+```json
+{
+  "name": "gcp-federated-auth",
+  "policyType": "upstream-gcp-federated-auth-inbound-policy",
+  "handler": {
+    "module": "$import(@zuplo/runtime)",
+    "export": "UpstreamGcpFederatedAuthInboundPolicy",
+    "options": {
+      "audience": "https://test-basic-vhpkl3cvtq-uc.a.run.app",
+      "serviceAccountEmail": "zup-api@my-project.iam.gserviceaccount.com",
+      "workloadIdentityProvider": "projects/932049231233/locations/global/workloadIdentityPools/my-pool/providers/my-provider"
+    }
+  }
+}
+```

package/docs/policies/upstream-gcp-federated-auth-inbound/intro.md

@@ -0,0 +1,21 @@
+This policy allows you to delegate authentication and authorization to your
+gateway without writing any code on your origin service by adding an
+authentication token to outgoing header allowing the service to be secured with
+GCP IAM.
+
+The tokens are issued using Zuplo's internal OAuth services and exchanged with
+GCP using
+[Workflow Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation).
+This allows you to authenticate your Zuplo API to your origin without saving any
+secrets in Zuplo.
+
+This is a useful means of securing your origin server so that only your Zuplo
+gateway can make requests against it.
+
+This policy works with
+[GCP Identity Aware Proxy](https://zuplo.com/docs/articles/gke-with-upstream-auth-policy)
+or services like [Cloud Run](https://cloud.google.com/iap/docs/managing-access)
+that natively support IAM authorization.
+
+For information on how Google's service based auth works see
+[Authenticating for invocation](https://cloud.google.com/functions/docs/securing/authenticating)