zuplo 6.67.32 → 6.68.0

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

@@ -0,0 +1,144 @@
+### Authorization Attributes
+
+There are a few different ways authorization attributes are set on the
+authorization request.
+
+#### Default Attributes
+
+By default the policy will set the following attributes on the authorization
+request:
+
+- `request.user.sub` - (AccessSubject) The subject of the user making the
+  request. Only set if the user is authenticated.
+- `request.method` - (Action) The HTTP method of the request.
+- `request.scheme` - (Resource) The scheme of the request URL.
+- `request.host` - (Resource) The host of the request URL.
+- `request.pathname` - (Resource) The pathname of the request URL.
+- `request.query.*` - (Resource) The value of each query parameter in the
+  request URL. For example `?foo=baz` would set `request.query.foo=baz`.
+- `request.params.*` - (Resource) The value of each path parameter in the
+  request URL. For example the route pattern `/accounts/:id` would set
+  `request.params.accounts=value`.
+
+The default attributes can be disabled by setting the policy options that start
+with `includeDefault` to `false`, for example
+`includeDefaultResourceAttributes: false` will disable the Resource category
+attributes.
+
+Below is an example of the default authorization request.
+
+```json
+{
+  "Request": {
+    "AccessSubject": [
+      {
+        "Attribute": [
+          {
+            "AttributeId": "request.user.sub",
+            "Value": "nate"
+          }
+        ]
+      }
+    ],
+    "Action": [
+      {
+        "Attribute": [
+          {
+            "AttributeId": "request.method",
+            "Value": "GET"
+          }
+        ]
+      }
+    ],
+    "Resource": [
+      {
+        "Attribute": [
+          {
+            "AttributeId": "request.scheme",
+            "Value": "https"
+          },
+          {
+            "AttributeId": "request.host",
+            "Value": "my-api-main-bdeec51.d2.zuplo.dev"
+          },
+          {
+            "AttributeId": "request.pathname",
+            "Value": "/test"
+          },
+          {
+            "AttributeId": "request.params.id",
+            "Value": "123"
+          },
+          {
+            "AttributeId": "request.query.param",
+            "Value": "1"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+#### Hard Coded Attributes
+
+In some cases it cane be useful to set hard coded attributes on the policy
+itself. On case for this might be to set the environment the API is running in
+so that different policies can be applied to say a staging or development
+environment.
+
+An example of how you could set the `custom.environment` attribute to an
+environment variable is shown below.
+
+```json
+"resourceAttributes": [
+  {
+    "attributeId": "custom.environment",
+    "value": "$env(CUSTOM_ENVIRONMENT)"
+  }
+]
+```
+
+#### Programmatically Setting Attributes
+
+For the more robust customization of the authorization request, you can set
+authorization attributes programmatically. This is done by running a custom
+inbound policy before the authorization policy. The custom policy can set any
+attribute on the authorization request.
+
+Below is an example of how you could set the `custom.resourceId` attribute to
+the value of a property in the request body.
+
+```ts title="custom-attributes.ts"
+import {
+  ZuploContext,
+  ZuploRequest,
+  AxiomaticsAuthZInboundPolicy,
+} from "@zuplo/runtime";
+
+export default async function policy(
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: MyPolicyOptionsType,
+  policyName: string
+) {
+  // Get the body of the request
+  const body = await request.json();
+
+  // Set the custom attribute
+  AxiomaticsAuthZInboundPolicy.setAuthAttributes(context, {
+    Resource: [
+      {
+        Attribute: [
+          {
+            AttributeId: "custom.recordId",
+            Value: body.recordId,
+          },
+        ],
+      },
+    ],
+  });
+
+  return request;
+}
+```

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

@@ -0,0 +1,11 @@
+This policy will authorize requests using Axiomatics Policy Server. If the
+request is not authorized, a 403 response will be returned.
+
+This policy is designed to be highly customizable in order to tailor the
+authorization requests to the specific needs of your application. You can add
+default attributes on the policy that are included in every request, or you can
+programmatically add attributes to the request using the `setAuthAttributes`
+method.
+
+Using this policy in conjunction with an authorization policy will automatically
+set AttributeSubject attributes for the user in the request.

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

@@ -0,0 +1,161 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Axiomatics Authorization",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": true,
+  "isInternal": false,
+  "isBeta": true,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Authorize requests using Axiomatics Policy Server.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "AxiomaticsAuthZInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "AxiomaticsAuthZInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": ["pdpUrl", "pdpUsername", "pdpPassword"],
+          "properties": {
+            "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."
+            },
+            "pdpUrl": {
+              "type": "string",
+              "examples": ["https://pdp.example.com"],
+              "description": "The URL to which the plugin will make a JSON POST request before proxying the original request."
+            },
+            "pdpUsername": {
+              "type": "string",
+              "examples": ["pdp-user"],
+              "description": "The username to use when authenticating with the PDP."
+            },
+            "pdpPassword": {
+              "type": "string",
+              "examples": ["$env(PDP_PASSWORD)"],
+              "description": "The password to use when authenticating with the PDP."
+            },
+            "includeDefaultActionAttributes": {
+              "type": "boolean",
+              "default": true,
+              "x-show-example": false,
+              "description": "Indicates whether the plugin should include default action attributes in the authorization request."
+            },
+            "includeDefaultResourceAttributes": {
+              "type": "boolean",
+              "default": true,
+              "x-show-example": false,
+              "description": "Indicates whether the plugin should include default resource attributes in the authorization request."
+            },
+            "includeDefaultSubjectAttributes": {
+              "type": "boolean",
+              "default": true,
+              "x-show-example": false,
+              "description": "Indicates whether the plugin should include default subject attributes in the authorization request."
+            },
+            "tokenHeaderName": {
+              "type": "string",
+              "default": "Authorization",
+              "x-show-example": false,
+              "description": "The name of the header that carries the JWT."
+            },
+            "accessSubjectAttributes": {
+              "x-show-example": false,
+              "type": "array",
+              "description": "A list of attributes that will be included in the authorization request.",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["attributeId", "value"],
+                "properties": {
+                  "attributeId": {
+                    "type": "string",
+                    "examples": ["user.subject"],
+                    "description": "The attribute ID that will be used in the PDP request."
+                  },
+                  "value": {
+                    "type": "string",
+                    "description": "The value of the attribute."
+                  }
+                }
+              }
+            },
+            "resourceAttributes": {
+              "x-show-example": false,
+              "type": "array",
+              "description": "A list of attributes that will be included in the authorization request.",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["attributeId", "value"],
+                "properties": {
+                  "attributeId": {
+                    "type": "string",
+                    "examples": ["user.subject"],
+                    "description": "The attribute ID that will be used in the PDP request."
+                  },
+                  "value": {
+                    "type": "string",
+                    "description": "The value of the attribute."
+                  }
+                }
+              }
+            },
+            "actionAttributes": {
+              "x-show-example": false,
+              "type": "array",
+              "description": "A list of attributes that will be included in the authorization request.",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["attributeId", "value"],
+                "properties": {
+                  "attributeId": {
+                    "type": "string",
+                    "examples": ["user.subject"],
+                    "description": "The attribute ID that will be used in the PDP request."
+                  },
+                  "value": {
+                    "type": "string",
+                    "description": "The value of the attribute."
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "AxiomaticsAuthZInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "pdpPassword": "$env(PDP_PASSWORD)",
+            "pdpUrl": "https://pdp.example.com",
+            "pdpUsername": "pdp-user"
+          }
+        }
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,9 @@
+The Basic Authentication policy allows you to authenticate incoming requests
+using the Basic authentication standard. You can configure multiple accounts
+with different passwords and a different bucket of user 'data'.
+
+The API will expect a Basic Auth header (you can generate samples
+[using this tool](https://www.debugbear.com/basic-auth-header-generator)).
+Requests with invalid credentials (or no header) will not be authenticated.
+Authenticated requests will populate the `user` property of the `ZuploRequest`
+parameter on your RequestHandler.

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

@@ -0,0 +1,99 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Basic Auth",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Authenticate requests using basic auth (i.e. username and password)",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "BasicAuthInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "BasicAuthInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": ["accounts"],
+          "properties": {
+            "accounts": {
+              "type": "array",
+              "description": "An array of account objects (username, password and data properties).",
+              "items": {
+                "type": "object",
+                "title": "BasicAuthAccount",
+                "description": "An account object.",
+                "additionalProperties": false,
+                "required": ["username", "password"],
+                "properties": {
+                  "username": {
+                    "type": "string",
+                    "description": "The username for the account (this will be the `sub` property on `request.user`.",
+                    "examples": ["$env(ACCOUNT_JOHN_USERNAME)"]
+                  },
+                  "password": {
+                    "type": "string",
+                    "description": "The password for the account - note we recommend storing this in environment variables.",
+                    "examples": ["$env(ACCOUNT_JOHN_PASSWORD)"]
+                  },
+                  "data": {
+                    "type": "object",
+                    "description": "The data payload you want associated with this account (this will be the `data` property on `request.user`).",
+                    "examples": [
+                      {
+                        "name": "John Doe",
+                        "email": "john.doe@gmail.com"
+                      }
+                    ]
+                  }
+                }
+              }
+            },
+            "allowUnauthenticatedRequests": {
+              "type": "boolean",
+              "default": false,
+              "description": "If 'true' allows the request to continue even if authenticated. When 'false' (the default) any unauthenticated request is automatically rejected with a 401."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "BasicAuthInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "accounts": [
+              {
+                "data": {
+                  "name": "John Doe",
+                  "email": "john.doe@gmail.com"
+                },
+                "password": "$env(ACCOUNT_JOHN_PASSWORD)",
+                "username": "$env(ACCOUNT_JOHN_USERNAME)"
+              }
+            ],
+            "allowUnauthenticatedRequests": false
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/bot-detection-inbound/intro.md

@@ -0,0 +1,4 @@
+The bot detection inbound policy provides a bot score for every request that can
+be used to determine the likelihood the request came from a bot. The policy can
+be configured to automatically block traffic with a set score or simply pass
+along the score for you to respond in other policies or handlers.

package/docs/policies/bot-detection-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": "Bot Detection",
+  "isDeprecated": false,
+  "isPaidAddOn": true,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Detect known and suspected bots based on sophisticated traffic analysis.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "BotDetectionInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "BotDetectionInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": ["blockScoresBelow"],
+          "properties": {
+            "blockScoresBelow": {
+              "type": "number",
+              "examples": [80],
+              "description": "The threshold at which bots are automatically blocked."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "BotDetectionInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "blockScoresBelow": 80
+          }
+        }
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,55 @@
+## Cron Schedules
+
+This policy accepts a single cron schedule or an array of cron schedules. Any
+time a requests falls withing that schedule the brownout response will be set.
+
+Example schedules could be:
+
+**Every Day between 2am and 3am**
+
+```json
+"cronSchedule": "* 2 * * *"
+```
+
+**Every Hour on the hour, and the 15th, 30th, and 45th minutes**
+
+```json
+"cronSchedule": ["0 * * * *", "15 * * * *", "30 * * * *", "45 * * * *"]
+```
+
+This can also be written as:
+
+```json
+"cronSchedule": ["0/15 * * * *"]
+```
+
+## Cron Expression Format
+
+This policy uses the
+[linux cron syntax](https://man7.org/linux/man-pages/man5/crontab.5.html) with
+the addition that you can optionally specify seconds by prepending the minute
+field with another field.
+
+```txt
+┌───────────── second (0 - 59, optional)
+│ ┌───────────── minute (0 - 59)
+│ │ ┌───────────── hour (0 - 23)
+│ │ │ ┌───────────── day of month (1 - 31)
+│ │ │ │ ┌───────────── month (1 - 12)
+│ │ │ │ │ ┌───────────── weekday (0 - 7)
+* * * * * *
+```
+
+All linux cron features are supported, including
+
+- lists
+- ranges
+- ranges in lists
+- step values
+- month names (jan,feb,... - case insensitive)
+- weekday names (mon,tue,... - case insensitive)
+- time nicknames (@yearly, @annually, @monthly, @weekly, @daily, @hourly - case
+  insensitive)
+
+To test out cron patterns try using a tool like
+[crontab.guru](https://crontab.guru/).

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

@@ -0,0 +1,12 @@
+The brownout policy allows performing scheduled downtime on your API. This can
+be useful for helping notify clients of an impending deprecation or for
+scheduling maintenance.
+
+This policy uses [cron schedules](https://crontab.guru) to check if a request
+should experience a brownout or not. When a request falls into a scheduled
+brownout an error response will be return. The error response can be customized
+by setting the `problem` properties.
+
+For more information using brownouts to alert clients on impending API
+changes/deprecations see our blog post
+[How to version an API](https://zuplo.com/blog/2022/05/17/how-to-version-an-api)

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

@@ -0,0 +1,115 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Brown Out",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "The brownout policy allows performing scheduled downtime on your API",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "BrownoutInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "BrownoutInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": ["cronSchedule"],
+          "properties": {
+            "cronSchedule": {
+              "oneOf": [
+                {
+                  "type": "string",
+                  "examples": ["* 2 * * *"]
+                },
+                {
+                  "type": "array",
+                  "examples": [["15 * * * *", "20 * * * *"]],
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              ],
+              "description": "The cron schedule for when this policy is enabled. This can be a single cron string or an array of multiple cron strings."
+            },
+            "problem": {
+              "type": "object",
+              "description": "The problem that is returned in the response body when this policy is enabled.",
+              "additionalProperties": true,
+              "properties": {
+                "type": {
+                  "type": "string",
+                  "examples": [
+                    "https://example.com/problems/deprecation-announcement"
+                  ],
+                  "description": "The type of problem."
+                },
+                "title": {
+                  "type": "string",
+                  "examples": ["Deprecation Test"],
+                  "description": "The title of problem."
+                },
+                "detail": {
+                  "type": "string",
+                  "examples": [
+                    "This is a temporary brownout to alert of an upcoming deprecation."
+                  ],
+                  "description": "The detail of problem."
+                },
+                "status": {
+                  "type": "number",
+                  "examples": ["400"],
+                  "description": "Http status code of the problem."
+                }
+              }
+            }
+          },
+          "examples": [
+            {
+              "cronSchedule": "* 2 * * *",
+              "problem": {
+                "type": "https://example.com/problems/deprecation-announcement",
+                "title": "Deprecation Test",
+                "detail": "This is a temporary brownout every day between 02:00-03:00 to alert of an upcoming deprecation.",
+                "status": 400
+              }
+            }
+          ]
+        }
+      },
+      "examples": [
+        {
+          "export": "BrownoutInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "cronSchedule": "* 2 * * *",
+            "problem": {
+              "type": "https://example.com/problems/deprecation-announcement",
+              "title": "Deprecation Test",
+              "detail": "This is a temporary brownout every day between 02:00-03:00 to alert of an upcoming deprecation.",
+              "status": 400
+            }
+          }
+        }
+      ]
+    }
+  }
+}