zuplo 6.67.32 → 6.68.0

package/docs/policies/graphql-introspection-filter-outbound/doc.md

@@ -0,0 +1,148 @@
+This policy filters GraphQL introspection responses to selectively hide types
+and fields from your schema. It intercepts introspection query responses and
+removes configured types and fields, allowing you to expose a subset of your
+GraphQL schema to external clients (like MCP servers or AI agents).
+
+### How It Works
+
+The policy processes responses from GraphQL introspection queries, which are
+typically made by GraphQL clients and development tools to discover your API's
+schema structure. When an introspection response is detected (containing
+`__schema` as a top level key), the policy filters out:
+
+- Entire types specified in `excludeTypes`
+- Specific fields on types specified in `excludeTypeFields`
+
+This allows you to hide internal types, sensitive fields, or admin-only
+operations from public consumers while keeping them available for internal use.
+
+### Policy Configuration
+
+Configure the policy with optional `excludeTypes` and `excludeTypeFields`
+options:
+
+```json
+{
+  "name": "filter-introspection",
+  "policyType": "graphql-introspection-filter-outbound",
+  "handler": {
+    "export": "GraphQLIntrospectionFilterOutboundPolicy",
+    "module": "$import(@zuplo/graphql)",
+    "options": {
+      "excludeTypes": ["UserInternal", "AdminType", "DebugInfo"],
+      "excludeTypeFields": {
+        "User": ["password", "ssn"],
+        "Query": ["adminUsers", "debugInfo"]
+      }
+    }
+  }
+}
+```
+
+### Configuration Options
+
+- **excludeTypes** (optional): Array of GraphQL type names to completely remove
+  from the schema. Types must match exactly.
+
+- **excludeTypeFields** (optional): Object mapping type names to arrays of field
+  names to remove. Only specified fields on the given types will be filtered.
+
+### Usage Examples
+
+#### Hiding Internal Types
+
+Remove internal implementation types from the public schema:
+
+```json
+{
+  "name": "hide-internal-types",
+  "policyType": "graphql-introspection-filter-outbound",
+  "handler": {
+    "export": "GraphQLIntrospectionFilterOutboundPolicy",
+    "module": "$import(@zuplo/graphql)",
+    "options": {
+      "excludeTypes": ["InternalMetadata", "DebugInfo", "SystemStatus"]
+    }
+  }
+}
+```
+
+#### Filtering Sensitive Fields
+
+Hide sensitive fields like passwords and admin operations:
+
+```json
+{
+  "name": "filter-sensitive-fields",
+  "policyType": "graphql-introspection-filter-outbound",
+  "handler": {
+    "export": "GraphQLIntrospectionFilterOutboundPolicy",
+    "module": "$import(@zuplo/graphql)",
+    "options": {
+      "excludeTypeFields": {
+        "User": ["password", "ssn", "creditCard"],
+        "Query": ["adminUsers", "systemDiagnostics"],
+        "Mutation": ["deleteAllUsers", "resetDatabase"]
+      }
+    }
+  }
+}
+```
+
+#### Complete Example with URL Rewrite
+
+Apply filtering on a route that forwards to a GraphQL endpoint:
+
+```json
+{
+  "paths": {
+    "/graphql": {
+      "x-zuplo-path": {
+        "pathMode": "open-api"
+      },
+      "post": {
+        "summary": "GraphQL API",
+        "x-zuplo-route": {
+          "corsPolicy": "anything-goes",
+          "handler": {
+            "export": "urlRewriteHandler",
+            "module": "$import(@zuplo/runtime)",
+            "options": {
+              "rewritePattern": "https://api.example.com/graphql"
+            }
+          },
+          "policies": {
+            "outbound": ["filter-introspection"]
+          }
+        },
+        "responses": {}
+      }
+    }
+  }
+}
+```
+
+### Important Notes
+
+- This policy only filters introspection responses - it does not enforce
+  authorization on the actual GraphQL operations. You must still implement
+  proper authorization in your GraphQL resolvers.
+- If a client tries to query a filtered field or type directly, that will be
+  handled by your GraphQL server's validation, not by this policy.
+- The policy only processes successful (200 OK) JSON responses that contain
+  `__schema` in the response body.
+- If the response cannot be parsed as JSON or is not an introspection response,
+  the original response is returned unchanged.
+- Non-introspection GraphQL queries and mutations pass through without
+  modification.
+
+### Security Considerations
+
+- Filtering introspection is a form of security through obscurity - always
+  implement proper authentication and authorization at the resolver level
+- Consider combining this policy with authentication policies to control who can
+  access your GraphQL endpoint
+- Use this policy to reduce information disclosure about your API's internal
+  structure, but don't rely on it as your only security measure
+- Keep in mind that determined attackers may still discover hidden fields
+  through other means

package/docs/policies/graphql-introspection-filter-outbound/schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "GraphQL Introspection Filter",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Filters GraphQL introspection responses to exclude specific types and fields.\n\nThis policy intercepts GraphQL introspection query responses and removes configured types and fields from the schema. Useful for hiding internal types or sensitive fields from the public schema.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "GraphQLIntrospectionFilterOutboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/graphql)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "GraphQLIntrospectionFilterOutboundPolicyOptions",
+          "type": "object",
+          "description": "The options for the GraphQL introspection filtering outbound policy.",
+          "required": [],
+          "additionalProperties": false,
+          "properties": {
+            "excludeTypes": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "GraphQL Types to exclude from the schema (exact match).",
+              "examples": ["UserInternal", "Admin", "DebugInfo"]
+            },
+            "excludeTypeFields": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "description": "Fields on specific GraphQL Types to exclude.",
+              "examples": [
+                {
+                  "User": ["password", "email"],
+                  "Query": ["adminUsers"]
+                }
+              ]
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "GraphQLIntrospectionFilterOutboundPolicy",
+          "module": "$import(@zuplo/graphql)",
+          "options": {
+            "excludeTypeFields": {
+              "User": ["password", "email"],
+              "Query": ["adminUsers"]
+            },
+            "excludeTypes": "UserInternal"
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/hmac-auth-inbound/doc.md

@@ -0,0 +1,30 @@
+The example below demonstrates how you could sign a value in order to create an
+HMAC signature for use with this policy.
+
+```ts
+const token = await sign("my data", environment.MY_SECRET);
+
+async function sign(
+  key: string | ArrayBuffer,
+  val: string,
+): Promise<ArrayBuffer> {
+  const encoder = new TextEncoder();
+  const cryptoKey = await crypto.subtle.importKey(
+    "raw",
+    typeof key === "string" ? encoder.encode(key) : key,
+    { name: "HMAC", hash: { name: "SHA-256" } },
+    false,
+    ["sign"],
+  );
+  const token = await crypto.subtle.sign(
+    "HMAC",
+    cryptoKey,
+    encoder.encode(val),
+  );
+  return Array.prototype.map
+    .call(new Uint8Array(token), function (x) {
+      return ("0" + x.toString(16)).slice(-2);
+    })
+    .join("");
+}
+```

package/docs/policies/hmac-auth-inbound/intro.md

@@ -0,0 +1,10 @@
+This example policy demonstrates how to use a shared secret to create an
+[HMAC](https://en.wikipedia.org/wiki/HMAC) signature to sign a payload (in this
+case the body). When the request is sent, the signature is sent in the request
+header. The policy can then verify that the signature matches the payload - thus
+ensuring that the sender had the same shared secret.
+
+This policy is configured with the value of the `secret`. Normally, you would
+store this as an environment variable secret. Additionally, the policy option
+`headerName` is used to set the header that will be used by the client to send
+the signature.

package/docs/policies/hmac-auth-inbound/policy.ts

@@ -0,0 +1,70 @@
+import { HttpProblems, ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+interface PolicyOptions {
+  secret: string;
+  headerName: string;
+}
+
+export default async function (
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: PolicyOptions,
+  policyName: string,
+) {
+  // Validate the policy options
+  if (typeof options.secret !== "string") {
+    throw new Error(
+      `The option 'secret' on policy '${policyName}' must be a string. Received ${typeof options.secret}.`,
+    );
+  }
+  if (typeof options.headerName !== "string") {
+    throw new Error(
+      `The option 'headerName' on policy '${policyName}' must be a string. Received ${typeof options.headerName}.`,
+    );
+  }
+
+  // Get the authorization header
+  const token = request.headers.get(options.headerName);
+
+  // No auth header, unauthorized
+  if (!token) {
+    return HttpProblems.unauthorized(request, context);
+  }
+
+  // Convert the hex encoded token to an Uint8Array
+  const tokenData = new Uint8Array(
+    token.match(/../g)!.map((h) => parseInt(h, 16)),
+  );
+
+  // Get the data to verify
+  // This could be anything (headers, query parameter, etc.)
+  // For this example, we will just verify the entire body value
+  const data = await request.text();
+
+  // Create a crypto key from a secret stored as an environment variable
+  const encoder = new TextEncoder();
+  const encodedSecret = encoder.encode(options.secret);
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encodedSecret,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["verify"],
+  );
+
+  // Verify that the data
+  const verified = await crypto.subtle.verify(
+    "HMAC",
+    key,
+    tokenData,
+    encoder.encode(data),
+  );
+
+  // Check if the data is verified, if not return unauthorized
+  if (!verified) {
+    return HttpProblems.unauthorized(request, context);
+  }
+
+  // Request is authorized, continue
+  return request;
+}

package/docs/policies/hmac-auth-inbound/schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/hmac-auth-inbound.json",
+  "type": "object",
+  "title": "HMAC Auth",
+  "isCustom": true,
+  "products": ["api-gateway"],
+  "description": "Authenticate requests using the HMAC-SHA256 authentication scheme.",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "default",
+          "description": "The export from the custom policy"
+        },
+        "module": {
+          "const": "$import(./modules/YOUR_MODULE)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "type": "object",
+          "description": "The options for this policy",
+          "required": ["secret", "headerName"],
+          "properties": {
+            "secret": {
+              "type": "string",
+              "description": "The secret to use for HMAC authentication"
+            },
+            "headerName": {
+              "type": "string",
+              "description": "The header where the HMAC signature is send"
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "_name": "basic",
+          "export": "default",
+          "module": "$import(./modules/YOUR_MODULE)",
+          "options": {
+            "secret": "$env(MY_SECRET)",
+            "headerName": "signed-request"
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/http-deprecation-outbound/doc.md

@@ -0,0 +1,73 @@
+This policy adds HTTP deprecation headers to outgoing responses following the
+[IETF HTTP Deprecation Header](https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-deprecation-header)
+standard. It supports the `Deprecation`, `Sunset`, and `Link` headers to signal
+to API consumers that an endpoint is deprecated.
+
+## Configuration
+
+- `deprecation` **(required)**: The deprecation value. Use `true` to indicate
+  the endpoint is already deprecated, an ISO 8601 date string with timezone
+  offset (e.g. `"2024-12-31T23:59:59Z"`) for a specific deprecation date, or a
+  Unix timestamp number.
+- `sunset`: An ISO 8601 date string with timezone offset indicating when the
+  endpoint will be removed. Sets the `Sunset` header.
+- `link`: A URL to documentation about the deprecation or a migration guide.
+  Sets the `Link` header.
+
+## Usage
+
+Apply this policy to outbound responses in your route configuration:
+
+```json
+{
+  "policies": [
+    {
+      "name": "http-deprecation-policy",
+      "policyType": "http-deprecation-outbound",
+      "handler": {
+        "export": "HttpDeprecationOutboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "deprecation": "2025-01-15T00:00:00Z",
+          "sunset": "2025-06-30T23:59:59Z",
+          "link": "https://example.com/docs/v2-migration"
+        }
+      }
+    }
+  ]
+}
+```
+
+If the endpoint is already deprecated and you don't need a specific date, you
+can set `deprecation` to `true`:
+
+```json
+{
+  "policies": [
+    {
+      "name": "http-deprecation-policy",
+      "policyType": "http-deprecation-outbound",
+      "handler": {
+        "export": "HttpDeprecationOutboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "deprecation": true,
+          "link": "https://example.com/docs/v2-migration"
+        }
+      }
+    }
+  ]
+}
+```
+
+## Response Headers
+
+Based on the configuration above, the policy sets the following headers on the
+response:
+
+- **`Deprecation`** - Set to the string `"true"` when input is `true`, an
+  HTTP-date when input is an ISO 8601 string, or an RFC 9651 timestamp
+  (`@epoch`) when input is a Unix timestamp number.
+- **`Sunset`** - An HTTP-date indicating when the endpoint will be removed.
+- **`Link`** - A link to deprecation documentation, formatted as
+  `<URL>; rel="deprecation"; type="text/html"`.

package/docs/policies/http-deprecation-outbound/schema.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "HTTP Deprecation",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Sets HTTP deprecation headers on the outgoing response following the IETF HTTP Deprecation Header standard. Supports the Deprecation, Sunset, and Link headers.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "HttpDeprecationOutboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "HttpDeprecationOutboundPolicyOptions",
+          "type": "object",
+          "description": "The options for the HTTP Deprecation outbound policy.",
+          "additionalProperties": false,
+          "required": ["deprecation"],
+          "properties": {
+            "deprecation": {
+              "oneOf": [
+                {
+                  "type": "boolean",
+                  "const": true,
+                  "description": "Set to true to indicate the endpoint is deprecated without a specific date."
+                },
+                {
+                  "type": "string",
+                  "description": "An ISO 8601 date string indicating when the endpoint was or will be deprecated. Converted to an HTTP-date in the header."
+                },
+                {
+                  "type": "number",
+                  "description": "A Unix timestamp indicating when the endpoint was or will be deprecated. Formatted as an RFC 9651 date in the header."
+                }
+              ],
+              "description": "The deprecation value. Use `true` for already deprecated, an ISO 8601 date string for a specific date, or a Unix timestamp number.",
+              "examples": [true, "2024-12-31T23:59:59Z", 1735689599]
+            },
+            "sunset": {
+              "type": "string",
+              "description": "An ISO 8601 date string indicating when the endpoint will be removed. Sets the Sunset header.",
+              "examples": ["2025-06-30T23:59:59Z"]
+            },
+            "link": {
+              "type": "string",
+              "format": "uri",
+              "description": "A URL to documentation about the deprecation or migration guide. Sets the Link header.",
+              "examples": ["https://example.com/docs/v2-migration"]
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "HttpDeprecationOutboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "deprecation": true,
+            "link": "https://example.com/docs/v2-migration",
+            "sunset": "2025-06-30T23:59:59Z"
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/ip-restriction-inbound/intro.md

@@ -0,0 +1,8 @@
+This custom policy allows you to specify a set of IP addresses that are allowed
+or blocked from making requests on your API. This can be useful for adding
+light-weight security to your API in non-critical scenarios. For example, if you
+want to ensure only employees on your corporate VPN can't access development
+environments.
+
+Generally, this policy shouldn't be relied upon as the only security for
+protecting sensitive workloads.

package/docs/policies/ip-restriction-inbound/policy.ts

@@ -0,0 +1,40 @@
+import { HttpProblems, ZuploContext, ZuploRequest } from "@zuplo/runtime";
+import ipRangeCheck from "ip-range-check";
+
+interface PolicyOptions {
+  allowedIpAddresses?: string[];
+  blockedIpAddresses?: string[];
+}
+
+export default async function (
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: PolicyOptions,
+  policyName: string,
+) {
+  // TODO: Validate the policy options. Skipping in the example for brevity
+
+  // Get the incoming IP address
+  const ip = request.headers.get("true-client-ip");
+
+  // If the allowed IP addresses are set, then the incoming IP
+  // must be in that list
+  if (options.allowedIpAddresses) {
+    const allowed = ipRangeCheck(ip, options.allowedIpAddresses);
+    if (!allowed) {
+      return HttpProblems.unauthorized(request, context);
+    }
+  }
+
+  // If the blocked IP addresses are set, then the incoming IP
+  // can't be in that list
+  if (options.blockedIpAddresses) {
+    const blocked = ipRangeCheck(ip, options.allowedIpAddresses);
+    if (blocked) {
+      return HttpProblems.unauthorized(request, context);
+    }
+  }
+
+  // If we made it this far, the IP address is allowed, continue
+  return request;
+}

package/docs/policies/ip-restriction-inbound/schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/ip-restriction-inbound.json",
+  "type": "object",
+  "title": "IP Restriction",
+  "isCustom": true,
+  "products": ["api-gateway"],
+  "description": "Block or allow requests based on their IP address.",
+  "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": {
+            "allowedIpAddresses": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "The IP addresses or CIDR ranges to allow"
+            },
+            "blockedIpAddresses": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "The IP addresses or CIDR ranges to allow"
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "_name": "basic",
+          "export": "default",
+          "module": "$import(./modules/YOUR_MODULE)",
+          "options": {
+            "allowedIpAddresses": ["184.42.1.4", "102.1.5.2/24"]
+          }
+        }
+      ]
+    }
+  }
+}