zuplo 6.67.32 → 6.68.0

package/docs/policies/openfga-authz-inbound/doc.md

@@ -0,0 +1,207 @@
+This policy integrates with OpenFGA to provide fine-grained authorization for
+your API endpoints. OpenFGA implements Google's Zanzibar authorization model,
+allowing you to define and check complex permission relationships between users
+and resources.
+
+### Usage
+
+To use this policy, you must programmatically set the relationship checks to be
+performed against your OpenFGA store. This is done using the static
+`setContextChecks` method.
+
+The most common way to set the authorization checks are:
+
+1. Creating custom inbound policies for each authorization scenario
+2. Creating a custom inbound policy that reads data from the OpenAPI operation
+   and sets the authorization checks dynamically
+
+### Example: Custom Authorization Policies
+
+Create a file like `modules/openfga-checks.ts` to define your custom
+authorization policies:
+
+```typescript
+import {
+  ZuploRequest,
+  ZuploContext,
+  RuntimeError,
+  HttpProblems,
+  OpenFGAAuthZInboundPolicy,
+} from "@zuplo/runtime";
+
+export async function canReadFolder(
+  request: ZuploRequest,
+  context: ZuploContext
+) {
+  if (!request.params?.folderId) {
+    throw new RuntimeError("Folder ID not found in request");
+  }
+
+  context.log.info("Setting OpenFGA context checks");
+
+  if (!request.user?.sub) {
+    return HttpProblems.forbidden(request, context, {
+      detail: "User not found",
+    });
+  }
+
+  // Set the authorization check to verify if the user has viewer access to the folder
+  OpenFGAAuthZInboundPolicy.setContextChecks(context, {
+    user: `user:${request.user.sub}`,
+    relation: "viewer",
+    object: `folder:${request.params.folderId}`,
+  });
+
+  return request;
+}
+
+export async function canEditDocument(
+  request: ZuploRequest,
+  context: ZuploContext
+) {
+  if (!request.params?.documentId) {
+    throw new RuntimeError("Document ID not found in request");
+  }
+
+  if (!request.user?.sub) {
+    return HttpProblems.forbidden(request, context, {
+      detail: "User not found",
+    });
+  }
+
+  // Set the authorization check to verify if the user has editor access to the document
+  OpenFGAAuthZInboundPolicy.setContextChecks(context, {
+    user: `user:${request.user.sub}`,
+    relation: "editor",
+    object: `document:${request.params.documentId}`,
+  });
+
+  return request;
+}
+```
+
+#### Applying to Routes
+
+In your route configuration, apply both the custom authorization policy and the
+OpenFGA policy:
+
+```json
+{
+  "path": "/folders/:folderId",
+  "methods": ["GET"],
+  "policies": {
+    "inbound": ["jwt-auth", "authz-can-read-folder", "openfga-authz"]
+  }
+}
+```
+
+Then in your `policies.json`:
+
+```json
+{
+  "name": "authz-can-read-folder",
+  "export": "canReadFolder",
+  "module": "$import(./modules/openfga-checks)"
+},
+{
+  "name": "openfga-authz",
+  "export": "OpenFGAAuthZInboundPolicy",
+  "module": "$import(@zuplo/runtime)",
+  "options": {
+    // OpenFGA configuration...
+  }
+}
+```
+
+### Example: Dynamic Authorization Checks
+
+You can make your authorization checks more dynamic by reading data from your
+OpenAPI specification or other sources. This allows you to define authorization
+rules that adapt based on the route, method, or other request properties.
+
+For example, you could access custom data defined in your route:
+
+```typescript
+export async function dynamicAuthCheck(
+  request: ZuploRequest,
+  context: ZuploContext
+) {
+  // Access custom data from the route configuration
+  const data = context.route.raw<{
+    "x-authz": {
+      resourceType: string;
+      permission: string;
+      resourceIdParam: string;
+    };
+  }>();
+  const authzData = data["x-authz"];
+
+  if (!authzData?.resourceType || !authzData?.permission) {
+    throw new RuntimeError(
+      "Missing resource type or permission in route config"
+    );
+  }
+
+  if (!request.user?.sub) {
+    return HttpProblems.forbidden(request, context);
+  }
+
+  // Extract resource ID from request parameters
+  const resourceId = request.params?.[authzData.resourceIdParam];
+
+  if (!resourceId) {
+    throw new RuntimeError(
+      `Resource ID parameter '${authzData.resourceIdParam}' not found`
+    );
+  }
+
+  // Set dynamic authorization check
+  OpenFGAAuthZInboundPolicy.setContextChecks(context, {
+    user: `user:${request.user.sub}`,
+    relation: authzData.permission,
+    object: `${authzData.resourceType}:${resourceId}`,
+  });
+
+  return request;
+}
+```
+
+Then in your OpenAPI document, you would set the custom data on the `x-authz`
+property:
+
+````json
+{
+  "paths": {
+    "/custom-data": {
+      "post": {
+        "x-authz": {
+          "resourceType": "document",
+          "resourceIdParam": "documentId",
+          "permission": "editor"
+        }
+      }
+    }
+  }
+}
+
+### Policy Configuration
+
+To configure the OpenFGA policy, you need to provide connection details to your OpenFGA instance:
+
+```json
+{
+  "name": "openfga-authz",
+  "export": "OpenFGAAuthZInboundPolicy",
+  "module": "$import(@zuplo/runtime)",
+  "options": {
+    "apiScheme": "https",
+    "apiHost": "api.openfga.example.com",
+    "storeId": "YOUR_STORE_ID",
+    "authorizationModelId": "YOUR_MODEL_ID",
+    "credentials": {
+      "method": "api-token",
+      "token": "$env(OPENFGA_API_TOKEN)"
+    }
+  }
+}
+````

package/docs/policies/openfga-authz-inbound/intro.md

@@ -0,0 +1,17 @@
+Implement fine-grained authorization for your API using OpenFGA, a
+high-performance system based on Google's Zanzibar model. This policy verifies
+access permissions by checking relationships between users, objects, and
+actions.
+
+With this policy, you'll benefit from:
+
+- **Fine-Grained Access Control**: Define precise permissions based on complex
+  relationships
+- **Scalable Authorization**: Leverage OpenFGA's high-performance design for
+  enterprise workloads
+- **Flexible Implementation**: Adapt authorization checks dynamically based on
+  request context
+- **Consistent Security**: Apply standardized access control across your entire
+  API
+- **Relationship-Based Model**: Express complex authorization scenarios using
+  intuitive object relationships

package/docs/policies/openfga-authz-inbound/schema.json

@@ -0,0 +1,191 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "OpenFGA Authorization",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": true,
+  "isInternal": false,
+  "isBeta": true,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Authorize requests using OpenFGA.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "OpenFGAAuthZInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "OpenFGAAuthZInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": [
+            "credentials",
+            "apiUrl",
+            "storeId",
+            "authorizationModelId"
+          ],
+          "properties": {
+            "apiUrl": {
+              "type": "string",
+              "description": "The URL of the OpenFGA service.",
+              "examples": ["https://api.us1.fga.dev"]
+            },
+            "storeId": {
+              "type": "string",
+              "description": "The ID of the store.",
+              "examples": ["$env(FGA_STORE_ID)"]
+            },
+            "authorizationModelId": {
+              "type": "string",
+              "description": "The ID of the authorization model.",
+              "examples": ["$env(FGA_MODEL_ID)"]
+            },
+            "allowUnauthorizedRequests": {
+              "type": "boolean",
+              "default": false,
+              "x-show-example": false,
+              "description": "Indicates whether the request should continue if authorization fails. Default is `false` which means unauthorized users will automatically receive a 403 response."
+            },
+            "credentials": {
+              "oneOf": [
+                {
+                  "type": "object",
+                  "description": "No authentication.",
+                  "additionalProperties": false,
+                  "required": ["method"],
+                  "properties": {
+                    "method": {
+                      "type": "string",
+                      "enum": ["none"],
+                      "description": "The type of authentication to use."
+                    }
+                  }
+                },
+                {
+                  "type": "object",
+                  "description": "Authentication options for api token authentication.",
+                  "additionalProperties": false,
+                  "required": ["method", "token"],
+                  "properties": {
+                    "method": {
+                      "type": "string",
+                      "enum": ["api-token"],
+                      "description": "The type of authentication to use."
+                    },
+                    "token": {
+                      "type": "string",
+                      "description": "The token key to use for authentication."
+                    },
+                    "headerName": {
+                      "type": "string",
+                      "description": "The name of the header to use for authentication.",
+                      "default": "Authorization"
+                    },
+                    "headerValuePrefix": {
+                      "type": "string",
+                      "description": "The prefix to use for the header value.",
+                      "default": "Bearer"
+                    }
+                  }
+                },
+                {
+                  "type": "object",
+                  "description": "Request header authentication.",
+                  "required": ["method", "headerName"],
+                  "additionalProperties": false,
+                  "properties": {
+                    "method": {
+                      "type": "string",
+                      "enum": ["header"],
+                      "description": "The type of authentication to use."
+                    },
+                    "headerName": {
+                      "type": "string",
+                      "description": "The name of the header to use for authentication.",
+                      "default": "Authorization"
+                    }
+                  }
+                },
+                {
+                  "type": "object",
+                  "description": "Authentication options for OIDC authentication.",
+                  "additionalProperties": false,
+                  "required": [
+                    "method",
+                    "clientId",
+                    "clientSecret",
+                    "oauthTokenEndpointUrl"
+                  ],
+                  "properties": {
+                    "method": {
+                      "type": "string",
+                      "enum": ["client-credentials"],
+                      "description": "The type of authentication to use."
+                    },
+                    "clientId": {
+                      "type": "string",
+                      "description": "The client ID."
+                    },
+                    "clientSecret": {
+                      "type": "string",
+                      "description": "The client secret."
+                    },
+                    "oauthTokenEndpointUrl": {
+                      "type": "string",
+                      "description": "The oauth endpoint url."
+                    },
+                    "apiAudience": {
+                      "type": "string",
+                      "description": "API Audience."
+                    }
+                  }
+                }
+              ],
+              "examples": [
+                {
+                  "method": "client-credentials",
+                  "clientId": "$env(FGA_CLIENT_ID)",
+                  "clientSecret": "$env(FGA_CLIENT_SECRET)",
+                  "apiAudience": "https://api.us1.fga.dev/",
+                  "oauthTokenEndpointUrl": "https://fga.us.auth0.com/oauth/token"
+                }
+              ]
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "OpenFGAAuthZInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "apiUrl": "https://api.us1.fga.dev",
+            "authorizationModelId": "$env(FGA_MODEL_ID)",
+            "credentials": {
+              "method": "client-credentials",
+              "clientId": "$env(FGA_CLIENT_ID)",
+              "clientSecret": "$env(FGA_CLIENT_SECRET)",
+              "apiAudience": "https://api.us1.fga.dev/",
+              "oauthTokenEndpointUrl": "https://fga.us.auth0.com/oauth/token"
+            },
+            "storeId": "$env(FGA_STORE_ID)"
+          }
+        }
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,163 @@
+## How it works
+
+The policy sends usage events to OpenMeter's API in
+[CloudEvents](https://cloudevents.io/) format whenever a request matches the
+configured status codes. The events include customer identification, event type,
+and custom data that can be used for metering and billing.
+
+Additionally, the policy can check entitlements before allowing access to your
+API. When entitlement checking is enabled, the policy will:
+
+1. Check if the subject has access to the required features
+2. Block the request if the subject doesn't have access to any required feature
+3. Log detailed information about failed entitlements
+
+## Programmatic Meters
+
+You can dynamically set meters for each request using the
+`OpenMeterInboundPolicy.setMeters` method:
+
+```typescript
+import { OpenMeterInboundPolicy } from "@zuplo/runtime";
+
+export default async function (request, context) {
+  // Set a single meter
+  OpenMeterInboundPolicy.setMeters(context, {
+    type: "api-call",
+    data: {
+      endpoint: request.url,
+      method: request.method,
+      tokens: 150,
+    },
+  });
+
+  // Or set multiple meters
+  OpenMeterInboundPolicy.setMeters(context, [
+    {
+      type: "api-call",
+      data: {
+        endpoint: request.url,
+        method: request.method,
+      },
+    },
+    {
+      type: "llm-usage",
+      data: {
+        model: "gpt-4",
+        prompt_tokens: 100,
+        completion_tokens: 50,
+      },
+    },
+  ]);
+
+  return request;
+}
+```
+
+## Examples
+
+### Basic Metering
+
+```json
+{
+  "type": "openmeter-inbound",
+  "handler": "$import(@zuplo/runtime).OpenMeterInboundPolicy",
+  "options": {
+    "apiKey": "your-api-key",
+    "meter": {
+      "type": "api-call",
+      "data": {
+        "service": "payment-api",
+        "tier": "premium"
+      }
+    }
+  }
+}
+```
+
+### Multiple Meters
+
+```json
+{
+  "type": "openmeter-inbound",
+  "handler": "$import(@zuplo/runtime).OpenMeterInboundPolicy",
+  "options": {
+    "apiKey": "your-api-key",
+    "meter": [
+      {
+        "type": "api-call",
+        "data": {
+          "service": "payment-api"
+        }
+      },
+      {
+        "type": "data-transfer",
+        "data": {
+          "bytes": 1024
+        }
+      }
+    ]
+  }
+}
+```
+
+### Metering with Entitlement Checking
+
+```json
+{
+  "type": "openmeter-inbound",
+  "handler": "$import(@zuplo/runtime).OpenMeterInboundPolicy",
+  "options": {
+    "apiKey": "your-api-key",
+    "meter": {
+      "type": "api-call",
+      "data": {
+        "service": "payment-api"
+      }
+    },
+    "requiredEntitlements": ["payment-api-access", "premium-tier"]
+  }
+}
+```
+
+### Custom Status Codes
+
+```json
+{
+  "type": "openmeter-inbound",
+  "handler": "$import(@zuplo/runtime).OpenMeterInboundPolicy",
+  "options": {
+    "apiKey": "your-api-key",
+    "meterOnStatusCodes": "200-299,304",
+    "meter": {
+      "type": "api-call"
+    }
+  }
+}
+```
+
+## CloudEvents Format
+
+The policy sends events to OpenMeter in CloudEvents format. Each event includes:
+
+- `specversion`: Always "1.0"
+- `id`: Unique identifier (combines request ID and meter type)
+- `time`: ISO 8601 timestamp
+- `source`: The configured event source
+- `subject`: The user/customer identifier
+- `type`: The meter type
+- `data`: Custom data from the meter configuration
+
+You can override CloudEvents fields when setting meters dynamically:
+
+```typescript
+OpenMeterInboundPolicy.setMeters(context, {
+  type: "llm-usage",
+  id: "custom-event-id-123",
+  subject: "user-456",
+  data: {
+    model: "gpt-4",
+    tokens: 1500,
+  },
+});
+```

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

@@ -0,0 +1,18 @@
+Send usage metrics to [OpenMeter](https://openmeter.io/) for metering and
+billing. This policy allows you to track API usage by sending events to
+OpenMeter's API in CloudEvents format.
+
+With this policy, you'll benefit from:
+
+- **Usage-Based Billing**: Implement precise metering for pay-as-you-go pricing
+  models
+- **Real-Time Analytics**: Track API usage patterns and customer behavior as
+  they happen
+- **Customizable Event Tracking**: Capture specific metrics that matter to your
+  business
+- **Customer Segmentation**: Identify usage patterns across different customer
+  segments
+- **Flexible Integration**: Works seamlessly with OpenMeter's CloudEvents-based
+  API
+- **Batch Processing**: Efficiently sends events in batches to minimize
+  performance impact