zuplo 6.67.32 → 6.68.0

package/docs/policies/curity-phantom-token-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": "Curity Phantom Token Auth",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Authenticate users using the Curity Phantom Token Pattern.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "CurityPhantomTokenInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "CurityPhantomTokenInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": ["clientId", "clientSecret", "introspectionUrl"],
+          "properties": {
+            "clientId": {
+              "type": "string",
+              "description": "The client ID of the Curity application."
+            },
+            "clientSecret": {
+              "type": "string",
+              "description": "The client secret of the Curity application."
+            },
+            "introspectionUrl": {
+              "type": "string",
+              "description": "The introspection URL of the Curity application."
+            },
+            "cacheDurationSeconds": {
+              "type": "number",
+              "description": "The duration in seconds to cache the introspected response.",
+              "default": 600
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "CurityPhantomTokenInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "cacheDurationSeconds": 600
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/custom-code-inbound/doc.md

@@ -0,0 +1,267 @@
+## Writing A Policy
+
+Custom policies can be written to extend the functionality of your gateway. This
+document is about inbound policies that can intercept the request and, if
+required, modify it before passing down the chain.
+
+Policies have a similar but subtly different signature to a
+[request handler](/docs/handlers/custom-handler.mdx).
+
+They also accept a `ZuploRequest` parameter but they must return either a
+`ZuploRequest` or a `Response`.
+
+:::tip
+
+Note that both `ZuploRequest` and `Response` are based on the web standards
+[Request](https://developer.mozilla.org/en-US/docs/Web/API/request) and
+[Response](https://developer.mozilla.org/en-US/docs/Web/API/Response).
+ZuploRequest adds a few additional properties for convenience, like `user` and
+`params`.
+
+:::
+
+Returning a `ZuploRequest` is a signal to continue the request pipeline and what
+you return will be passed to the next policy, and finally the request handler.
+
+If you return a `Response` that tells Zuplo to short-circuit this request and
+immediately respond to the client.
+
+```ts
+export type InboundPolicyHandler<TOptions = any> = (
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: TOptions,
+  policyName: string,
+) => Promise<ZuploRequest | Response>;
+```
+
+A common use case for policies is authentication. In the following example we'll
+create a simple auth policy that checks for an `api-key` header:
+
+## A simple auth policy
+
+```ts
+// my-first-policy.ts
+import { ZuploRequest } from "@zuplo/runtime";
+
+export default async function(
+	request: ZuploRequest,
+	context: ZuploContext
+	options: any,
+	policyName: string) {
+  	const apiKeyHeader = request.headers.get("api-key");
+	if (!apiKeyHeader) {
+		return new Response(`No api-key header`, { status: 401});
+	}
+	if (apiKeyHeader !== `magic-password`) {
+		return new Response(`Incorrect API Key`, { status: 401});
+	}
+	// TODO - lets set the user property on the request for
+	// downstream consumption
+	return request;
+}
+```
+
+This policy checks for an `api-key` header and rejects requests that don't have
+one. If such a header is found, it then checks the content of the header for a
+magic password. This example shouldn't be used in a real API but is
+demonstrative of how you might build custom authentication.
+
+## Wiring up the policy on routes
+
+Policies are activated by specifying them on routes in the route.oas.json file.
+Here's how we could wire up our new auth route:
+
+```json
+// /config/policies.json
+{
+  "policies": [
+    {
+      "name": "my-first-policy",
+      "policyType": "custom-code-inbound",
+      "handler": {
+        "export": "default",
+        "module": "$import(./modules/my-first-policy)"
+      }
+    }
+  ]
+}
+```
+
+```json
+// /config/routes.oas.json
+{
+  ...
+  "paths": {
+  "/redirect-test": {
+    "x-zuplo-path": {
+      "pathMode": "open-api"
+    },
+    "get": {
+      "summary": "Testing rewrite handler",
+      "x-zuplo-route": {
+        "corsPolicy": "none",
+        "handler": {
+          "module": "$import(@zuplo/runtime)",
+          "export": "redirectHandler",
+          "options": {
+            "location": "/docs"
+          }
+        }
+      },
+      "policies": {
+        "inbound": ["my-first-policy"]
+      }
+    }
+  }
+}
+
+}
+```
+
+## Policy Options
+
+In your policy configuration, you can specify additional information to
+configure your policy on the options property. In the example below we set an
+example object with some properties of type string and number. Note these
+objects can be as complicated as you like.
+
+```json
+{
+  "name": "my-first-policy",
+  "policyType": "custom-code-inbound",
+  "handler": {
+    "export": "default",
+    "module": "$import(./modules/my-first-policy)",
+    "options": {
+      "you": "can",
+      "specify": "anything",
+      "here": 0
+    }
+  }
+}
+```
+
+The value of this property will be passed to your policy's handler as the
+`options` parameter. Sometimes it's useful to create a type as shown below.
+
+```ts
+type MyPolicyOptionsType = {
+  you: string;
+  specify: string;
+  here: number;
+};
+export default async function (
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: MyPolicyOptionsType,
+  policyName: string,
+) {
+  // your policy code goes here, and can use the options to perform any
+  // configuration
+  context.log.info(options.you);
+}
+```
+
+You can also use the `any` type if you prefer not to create a type.
+
+## Setting the user property
+
+When building a policy it's common to modify the request object in some way
+before passing control downstream. The `ZuploRequest` type has a `user` property
+that isn't set for unauthenticated requests. Authenticated requests should have
+a valid `user` property. Since this is an authentication policy, we should set
+that property before passing control to the next in line.
+
+The user object should have a `sub` property which is a unique user id. Let's
+use Zuplo's policy `options` to extend our example.
+
+You can pass options to a policy from the policies.json file. In this case,
+we'll create a dictionary of API keys to `sub` ids.
+
+```json
+"policies": [
+    {
+      "name": "my-first-policy",
+      "policyType": "custom-code-inbound",
+      "handler": {
+        "export": "default",
+        "module": "$import(./modules/my-first-policy)",
+				// some options that will be passed to our Policy
+				"options": {
+					"123" : "sub-1",
+					"abc" : "sub-2"
+				}
+      }
+    }
+  ]
+```
+
+Now let's update the policy to read these options and use the dictionary keys as
+the `api-key` and to map the sub identifier.
+
+```ts
+import { ZuploRequest, ZuploContext } from "@zuplo/runtime";
+
+export default async function (
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: any,
+  policyName: string,
+) {
+  const apiKeyHeader = request.headers.get("api-key");
+  if (!apiKeyHeader) {
+    return new Response(`No api-key header`, { status: 401 });
+  }
+
+  const matchedKey = options[apiKeyHeader];
+
+  if (matchedKey === undefined) {
+    return new Response(`Incorrect API Key`, { status: 401 });
+  }
+
+  request.user = { sub: matchedKey };
+
+  return request;
+}
+```
+
+We can then use this user object in the request handler
+
+```ts
+import { ZuploRequest } from "@zuplo/runtime";
+
+export default async function (request: ZuploRequest) {
+  // let's return the user sub to the client as proof it's working
+  return `User sub ${request.user.sub}`;
+}
+```
+
+Here is this example working as a gif
+
+![Policy in action](../../public/media/policies/2021-11-21_21.44.35.gif)
+
+## Modifying the request headers
+
+Sometimes we need to modify the request more significantly, and this will
+require creating a new request object. In this case, let's imagine we want to
+convert incoming parameters to headers.
+
+```ts
+export default async function (request: ZuploRequest) {
+  // create a new request based on the old one,
+  // this is required because the original request's
+  // headers are immutable
+  const newRequest = new ZuploRequest(request);
+  // enumerate over the params object and copy to the new
+  // request
+  Object.keys(request.params).forEach((param) => {
+    newRequest.headers.set(param, request.params[param]);
+  });
+
+  return newRequest;
+}
+```
+
+For a more complex example, check out the
+[custom logging implementation](/docs/articles/custom-logging-example.mdx).

package/docs/policies/custom-code-inbound/intro.md

@@ -0,0 +1,2 @@
+Add your own custom inbound policy coded in TypeScript. See below for more
+details on how to build your own policy.

package/docs/policies/custom-code-inbound/schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/custom-code-inbound.json",
+  "type": "object",
+  "title": "Custom Code Inbound",
+  "products": ["api-gateway"],
+  "description": "Enables a custom code policy written in TypeScript. Change YOUR_MODULE to the name of your module (without .ts extension)",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "YOUR_EXPORT",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(./modules/YOUR_MODULE)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "type": "object",
+          "description": "Options to be passed to the custom policy",
+          "required": [],
+          "properties": {
+            "*": {
+              "type": "object",
+              "description": "Any object your custom policy consumes"
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "_name": "basic",
+          "export": "default",
+          "module": "$import(./modules/YOUR_MODULE)",
+          "options": {
+            "config1": "YOUR_VALUE",
+            "config2": true
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/custom-code-outbound/doc.md

@@ -0,0 +1,235 @@
+:::tip{title="The outbound policy will only execute if the response status code
+is 'ok'"}
+
+(e.g. `response.ok === true` or the status code is 200-299) - see
+[response.ok on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Response/ok).
+
+:::
+
+### Writing A Policy
+
+Custom policies can be written to extend the functionality of your gateway. This
+document is about outbound policies that can intercept the request and, if
+required, modify it before passing down the chain.
+
+The outbound custom policy is similar to the inbound custom policy but also
+accepts a `Response` parameter. The outbound policy must return a valid
+`Response` (or throw an error, which will result in a 500 Internal Server Error
+for your consumer, not recommended).
+
+:::tip
+
+Note that both `ZuploRequest` and `Response` are based on the web standards
+[Request](https://developer.mozilla.org/en-US/docs/Web/API/request) and
+[Response](https://developer.mozilla.org/en-US/docs/Web/API/Response).
+ZuploRequest adds a few additional properties for convenience, like `user` and
+`params`.
+
+:::
+
+```ts
+export type OutboundPolicyHandler<TOptions = any> = (
+  response: Response,
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: TOptions,
+  policyName: string,
+) => Promise<ZuploRequest | Response>;
+```
+
+A common use case for outbound policies is to change the body of the response.
+In this example, we'll imagine we are proxying the `/todos` example api at
+[https://jsonplaceholder.typicode.com/todos](https://jsonplaceholder.typicode.com/todos).
+
+The format of the /todos response looks like this
+
+```json
+[
+  {
+    "userId": 1,
+    "id": 1,
+    "title": "delectus aut autem",
+    "completed": false
+  },
+  {
+    "userId": 1,
+    "id": 2,
+    "title": "quis ut nam facilis et officia qui",
+    "completed": false
+  },
+```
+
+We will write an outbound policy that does two things
+
+1. Removes the `userId` property
+2. Adds a new outbound header called `color`
+
+Here's the code:
+
+```ts
+// /modules/my-first-policy.ts
+export default async function (
+  response: Response,
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: any,
+  policyName: string,
+) {
+  if (response.status !== 200) {
+    // if we get an unexpected response code, something went wrong, just let the response flow
+    return response;
+  }
+
+  const data = (await response.json()) as any[]; // we know this is JSON and an array
+  data.forEach((item) => {
+    delete item.userId;
+  });
+
+  // create a new response
+  const newResponse = new Response(JSON.stringify(data), {
+    status: response.status,
+    headers: response.headers,
+  });
+
+  // let's add an additional header as an example, for good measure
+  newResponse.headers.set("color", "yellow");
+
+  return newResponse;
+}
+```
+
+:::tip
+
+Note, that because we're not using the original response here (we just use the
+new one called `newResponse`) we didn't need to `clone` the original response
+before reading the body with `.json()`. If you need to read the body and use
+that same instance you must first `clone()` to avoid runtime errors such as
+"Body is unusable".
+
+:::
+
+## Wiring up the policy on routes
+
+Policies are activated by specifying them on routes in the route.oas.json file.
+Here's how we could wire up our new route:
+
+```json
+// /config/policies.json
+{
+  "policies": [
+    {
+      "name": "my-first-policy",
+      "policyType": "custom-code-outbound",
+      "handler": {
+        "export": "default",
+        "module": "$import(./modules/my-first-policy)"
+      }
+    }
+  ]
+}
+```
+
+```json
+// /config/routes.oas.json
+{
+  ...
+  "paths": {
+  "x-zuplo-path": {
+    "pathMode": "open-api"
+  },
+  "get": {
+    "summary": "New Route",
+    "description": "",
+    "x-zuplo-route": {
+      "corsPolicy": "none",
+      "handler": {
+        "export": "urlForwardHandler",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "baseUrl": "https://getting-started.zuplo.io"
+        }
+      },
+      "policies": {
+        "inbound": [],
+        "outbound": [
+          "my-first-policy",
+        ]
+      }
+    },
+}
+
+}
+```
+
+### Custom Policy Options
+
+In your policy configuration, you can specify additional information to
+configure your policy on the options property. In the example below we set an
+example object with some properties of type string and number. Note these
+objects can be as complicated as you like.
+
+```json
+{
+  "name": "my-first-policy",
+  "policyType": "custom-code-outbound",
+  "handler": {
+    "export": "default",
+    "module": "$import(./modules/my-first-policy)",
+    "options": {
+      "you": "can",
+      "specify": "anything",
+      "here": 0
+    }
+  }
+}
+```
+
+The value of this property will be passed to your policy's handler as the
+`options` parameter. Sometimes it's useful to create a type as shown below.
+
+```ts
+type MyPolicyOptionsType = {
+  you: string;
+  specify: string;
+  here: number;
+};
+export default async function (
+  response: Response,
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: MyPolicyOptionsType,
+  policyName: string,
+) {
+  // your policy code goes here, and can use the options to perform any
+  // configuration
+  context.log.info(options.you);
+}
+```
+
+You can also use the `any` type if you prefer not to create a type.
+
+## Adding headers
+
+Note if you just need to add headers, it more efficient not read the body stream
+and reuse it, e.g.
+
+```ts
+export default async function (
+  response: Response,
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: any,
+  policyName: string,
+) {
+  // create a new response
+  const newResponse = new Response(response.body, {
+    status: response.status,
+    headers: response.headers,
+  });
+
+  // let's add an additional header as an example, for good measure
+  newResponse.headers.set("color", "yellow");
+
+  return newResponse;
+}
+```

package/docs/policies/custom-code-outbound/intro.md

@@ -0,0 +1,2 @@
+Add your own custom outbound policy coded in TypeScript. See below for more
+details on how to build your own policy.

package/docs/policies/custom-code-outbound/schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/custom-code-outbound.json",
+  "type": "object",
+  "title": "Custom Code Outbound",
+  "products": ["api-gateway"],
+  "description": "A custom outbound response policy.",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "YOUR_EXPORT",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(./modules/YOUR_MODULE)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "type": "object",
+          "description": "Options to be passed to the custom policy",
+          "required": [],
+          "properties": {}
+        }
+      },
+      "examples": [
+        {
+          "_name": "basic",
+          "export": "default",
+          "module": "$import(./modules/YOUR_MODULE)",
+          "options": {
+            "config1": "YOUR_VALUE",
+            "config2": true
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/firebase-jwt-inbound/intro.md

@@ -0,0 +1,6 @@
+Authenticate requests with JWT tokens issued by Firebase. The payload of the JWT
+token, if successfully authenticated, with be on the `request.user.data` object
+accessible to the runtime.
+
+See [this document](https://zuplo.com/docs/articles/oauth-authentication) for
+more information about OAuth authorization in Zuplo.