zuplo 6.67.32 → 6.68.0

package/docs/articles/securing-backend-mtls.mdx

@@ -0,0 +1,268 @@
+---
+title: mTLS Authentication
+---
+
+<EnterpriseFeature name="mTLS Client Certificates" />
+
+Mutual TLS (mTLS) authentication establishes a trust relationship between your
+Zuplo API Gateway and your backend services using client certificates. With
+mTLS, both the client (Zuplo Gateway) and the server (your backend) authenticate
+each other, creating a "Zero Trust" security model.
+
+This is particularly useful for enterprise customers who need to ensure that
+both parties in a connection verify each other's identity before exchanging
+data.
+
+## How mTLS Works
+
+When Zuplo makes an outbound request to your backend service:
+
+1. Your backend service presents its SSL/TLS certificate to Zuplo (standard TLS)
+2. Zuplo presents a client certificate to your backend (the mutual part)
+3. Both parties verify each other's certificates against a trusted Certificate
+   Authority (CA)
+4. Only after mutual verification does the secure connection establish
+
+This ensures that your backend only accepts requests from authorized Zuplo
+gateways, and Zuplo can verify it's connecting to the correct backend service.
+
+## Prerequisites
+
+Before you begin, you need:
+
+- A client certificate and private key generated from a Certificate Authority
+  (CA) that your backend trusts
+- Your backend service configured to require and validate client certificates
+- The Zuplo CLI installed (see [CLI documentation](../cli/overview.mdx))
+
+## 1/ Upload Your Certificate
+
+Use the Zuplo CLI to upload your client certificate and private key to your
+project. You can upload multiple certificates, each with a unique name.
+
+```bash
+zuplo mtls-certificate create \
+  --cert cert.pem \
+  --key key.pem \
+  --name my-backend-cert \
+  --account your-account \
+  --project your-project \
+  --environment-type development \
+  --environment-type preview \
+  --environment-type production
+```
+
+:::note
+
+The certificate name must follow JavaScript's variable naming constraints since
+you will use the name later in your code. The CLI will validate these
+constraints when you create the certificate.
+
+:::
+
+**Parameters:**
+
+- `--cert`: Path to your PEM-encoded client certificate file
+- `--key`: Path to your PEM-encoded private key file
+- `--name`: A unique name to identify this certificate in your project
+- `--account`: Your Zuplo account name
+- `--project`: Your Zuplo project name
+- `--environment-type`: Specify which environments can use this certificate (can
+  be specified multiple times)
+
+## 2/ Use the Certificate in Your Code
+
+Once uploaded, you can use the certificate when making outbound requests from
+your Zuplo Gateway.
+
+### Using mTLS in a Request Handler
+
+Reference the certificate by name in the `zuplo` options object when making
+fetch requests:
+
+```ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  const response = await fetch("https://secure-backend.example.com/api", {
+    zuplo: {
+      mtlsCertificate: "my-backend-cert",
+    },
+  });
+
+  return response;
+}
+```
+
+### Using mTLS in a Policy
+
+You can also configure mTLS in the URL Forward Handler or URL Rewrite Handler
+that make outbound requests:
+
+```json
+{
+  "export": "UrlForwardHandler",
+  "module": "$import(@zuplo/runtime)",
+  "options": {
+    "baseUrl": "https://secure-backend.example.com",
+    "mtlsCertificate": "my-backend-cert"
+  }
+}
+```
+
+## 3/ Using Environment Variables
+
+For better flexibility across environments, store the certificate name as an
+[environment variable](./environment-variables.mdx):
+
+**Production environment:**
+
+```text
+BACKEND_MTLS_CERT=my-backend-prod-cert
+```
+
+**Staging environment:**
+
+```text
+BACKEND_MTLS_CERT=my-backend-staging-cert
+```
+
+Then reference it in your code:
+
+```ts
+import { ZuploContext, ZuploRequest, environment } from "@zuplo/runtime";
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  const response = await fetch("https://secure-backend.example.com/api", {
+    zuplo: {
+      mtlsCertificate: environment.BACKEND_MTLS_CERT,
+    },
+  });
+
+  return response;
+}
+```
+
+Or in your policy configuration:
+
+```json
+{
+  "export": "UrlForwardHandler",
+  "module": "$import(@zuplo/runtime)",
+  "options": {
+    "baseUrl": "https://secure-backend.example.com",
+    "mtlsCertificate": "$env(BACKEND_MTLS_CERT)"
+  }
+}
+```
+
+## Managing Certificates
+
+### Listing Certificates
+
+To view all certificates in your project:
+
+```bash
+zuplo mtls-certificate list \
+  --account your-account \
+  --project your-project
+```
+
+### Deleting Certificates
+
+To remove a certificate:
+
+```bash
+zuplo mtls-certificate delete \
+  --cert-id my-cert-id \
+  --account your-account \
+  --project your-project
+```
+
+:::caution
+
+You can't delete a certificate that's referenced by any of your deployments in
+your project. This is to prevent your deployments from failing if the
+certificate that's being referenced is no longer available.
+
+First, disable the certificate by using the CLI with
+`zuplo mtls-certificate disable`. Then redeploy the deployments in your project
+that reference it. Once there are no more references to the certificate, you can
+delete it.
+
+:::
+
+### Certificate Rotation
+
+When your certificates need to be rotated (due to expiration or security
+policies):
+
+1. Upload the new certificate with a different name
+2. Update your environment variables or code to reference the new certificate
+   name
+3. Use the CLI `zuplo mtls-certificate disable` command to disable the old
+   certificate.
+4. Deploy your changes to all environments that reference the old certificate.
+5. After verifying the new certificate works, you may delete the old
+   certificate.
+
+The order of operations is important so that your services continue to work as
+you rotate the certificate.
+
+## Local Development
+
+:::warning
+
+mTLS bindings aren't currently available in local development environments. Your
+code using mTLS will only work when deployed to Zuplo's edge infrastructure.
+
+:::
+
+For local development, consider:
+
+- Using conditional logic to bypass mTLS when running locally
+- Setting up a separate backend endpoint that doesn't require mTLS for
+  development
+- Testing mTLS functionality in a preview environment
+
+## Troubleshooting
+
+### Certificate Validation Errors
+
+If your backend rejects the certificate, verify:
+
+- The certificate is signed by a CA that your backend trusts
+- The certificate hasn't expired
+- The certificate name in your code matches the uploaded certificate name
+
+### Connection Failures
+
+If requests fail to connect:
+
+- Ensure your backend is configured to accept mTLS connections
+- Verify the certificate is uploaded to the correct environment (development,
+  preview, production)
+- Check that your backend's CA certificate is properly configured
+
+### Runtime Errors
+
+If you see errors about missing certificates:
+
+- Confirm the certificate was uploaded successfully using
+  `zuplo mtls-certificate list`
+- Ensure the environment type was specified correctly during upload
+- Verify your code references the correct certificate name
+
+## Additional Resources
+
+For more information on securing your backend, see:
+
+- [Securing your Backend](./securing-your-backend.mdx) - Overview of all backend
+  security options
+- [Shared Secret / API Key](./securing-your-backend.mdx#1-shared-secret--api-key) -
+  Alternative approach using shared secrets
+- [Secure Tunnels](./secure-tunnel.mdx) - Connect to private backends without
+  exposing them to the internet
+
+If you need assistance configuring mTLS for your project, contact us at
+[support@zuplo.com](mailto:support@zuplo.com).

package/docs/articles/securing-your-backend.mdx

@@ -0,0 +1,148 @@
+---
+title: Securing your backend
+---
+
+When using a gateway, it's important to ensure that your backend API is only
+receiving traffic via the gateway to be confident that your policies are being
+correctly applied to all traffic.
+
+![Zuplo as an API gateway](../../public/media/securing-your-backend/b7290dd1-43fa-49f8-8629-6b4899e2e9f3.png)
+
+To do this, we need to secure the communication between Zuplo and your backend
+APIs (origin). There are several options to do this securely.
+
+## 1/ Shared secret / API Key
+
+This is the most popular option and is used by companies like Supabase,
+Firebase, and Stripe to secure their own APIs. In this solution the backend
+requires a secret that's known only by the gateway. This is usually an opaque
+key sent as a header on every request to the origin. Zuplo adds this to the
+request - the client is never aware of the secret.
+
+### Step 1: Set an environment variable
+
+Set an [environment variable](./environment-variables.mdx) in your Zuplo
+project. This variable is a secret that only your Zuplo project and your backend
+know. It is sent as a header on every request to your backend API.
+
+Open the **Settings** section of your project and select **Environment
+Variables**. Create a new variable and name it `BACKEND_SECRET`. Set the value
+to a secure, random value. Ensure that the value is marked as a secret.
+
+![Set Environment Variable](../../public/media/securing-backend-shared-secret/image.png)
+
+### Step 2: Create a set header policy
+
+Create a policy that sets the `BACKEND_SECRET` as a header on the request to
+your backend API. This policy is an inbound policy that runs before the request
+is sent to your backend.
+
+Navigate to the route you want to secure and add a new policy. Select the **Add
+or Set Request Headers** policy type and configure it as follows:
+
+![Set Header Policy](../../public/media/securing-backend-shared-secret/image-1.png)
+
+The configuration uses the environment variable via the `$env(BACKEND_SECRET)`
+selector as shown below.
+
+```json
+{
+  "name": "set-backend-secret",
+  "policyType": "set-headers-inbound",
+  "handler": {
+    "export": "SetHeadersInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "headers": [
+        {
+          "name": "backend-secret",
+          "value": "$env(BACKEND_SECRET)"
+        }
+      ]
+    }
+  }
+}
+```
+
+Add this policy to any of the routes in your API that call your secure backend.
+
+### Step 3: Verify the secret on your backend
+
+Verify the secret on your backend. The implementation depends on the framework
+and language you use, but the typical pattern is to use middleware to check the
+header value. If the header does not match the secret, return a 401 Unauthorized
+response.
+
+An example using a Node.js Express middleware:
+
+```js
+const express = require("express");
+const app = express();
+
+app.use((req, res, next) => {
+  if (req.headers["backend-secret"] !== process.env.BACKEND_SECRET) {
+    return res.status(401).send("Unauthorized");
+  }
+  next();
+});
+```
+
+## 2/ Federated Authentication
+
+This is a new option where you can configure your cloud service (for example,
+GCP or AWS) to trust a JWT token created by the Zuplo runtime. If you're
+interested in using this option please contact us at `support@zuplo.com`.
+
+## 3/ Upstream Service Authentication
+
+Utilize the IAM controls provided by your Cloud host to secure inbound requests
+and allow only authorized service principals access to your service.
+
+- For Azure users, you can user our
+  [Upstream Azure AD Service Auth](../policies/upstream-azure-ad-service-auth-inbound.mdx)
+  policy. This uses Azure AD App registrations to create a token that Zuplo will
+  send to requests to Azure.
+
+- For GCP users, you can use our
+  [Upstream GCP Service AUth](../policies/upstream-gcp-service-auth-inbound.mdx)
+  or [Upstream GCP JWT](../policies/upstream-gcp-jwt-inbound.mdx) policies.
+  These use a `service.json` credential to create or issue JWT tokens that Zuplo
+  will send to requests to GCP.
+
+## 4/ mTLS Authentication
+
+Mutual TLS (mTLS) authentication allows the configuration of a trust
+relationship between your Zuplo gateway and your backend API using client
+certificates. With mTLS, both your gateway and backend authenticate each other,
+providing a "Zero Trust" security model that's popular with enterprise
+customers.
+
+To learn how to set up mTLS with client certificates, see the
+[Securing your Backend with mTLS](./securing-backend-mtls.mdx) article. This is
+an [enterprise feature](https://zuplo.com/pricing).
+
+## 5/ Secure Tunneling
+
+Used by some of our larger customers, our [secure tunnels](./secure-tunnel.mdx)
+allow you to create a WireGuard based tunnel from your VPC or private
+data-center that connects directly to your Zuplo gateway. This option is useful
+when running workloads in a non-cloud provider (for example, bare metal, on
+premises, etc.) that don't have IAM or mTLS capabilities. In this solution, your
+backend API doesn't need to be exposed to the internet at all. This is a more
+complex setup and is only available on our
+[enterprise plan](https://zuplo.com/pricing).
+
+To discuss security and connectivity options, our
+[discord channel](https://discord.zuplo.com) is a great community, with active
+participation from the Zuplo team.
+
+## 6/ Custom Networking (Managed Dedicated Only)
+
+For customers on our managed dedicated plan, we can provide custom networking to
+connect your backend to Zuplo. This can include using VPC connectivity
+capabilities from your cloud provider (for example AWS, Azure, GCP, etc.) such
+as AWS Transit Gateway, PrivateLink, or VPC Peering to connect to your backend
+services.
+
+For more details on networking options for managed dedicated customers, see our
+[Networking documentation](../dedicated/networking.mdx).

package/docs/articles/security.mdx

@@ -0,0 +1,105 @@
+---
+title: Security
+---
+
+Zuplo hosts mission-critical infrastructure for our customers and as such we
+take our security and your security very seriously. Zuplo was started with a
+security mindset and all team members are responsible for ensuring our services
+and infrastructure are secure. Services are designed with security in mind from
+the beginning and we rely on best-in-class security tooling to ensure our
+infrastructure is safe and secure.
+
+:::tip
+
+**Reporting Issues**: If you have a security concern or believe you have found a
+vulnerability in any part of Zuplo please contact us immediately by emailing us
+at [security@zuplo.com](mailto:security@zuplo.com). For full terms see our
+[Security Policy](https://zuplo.com/legal/security-policy).
+
+:::
+
+## Security Practices
+
+### Corporate Security
+
+Zuplo implements a number of security controls to ensure that only authorized
+Zuplo team members have access to company infrastructure. This section is
+intended to give a high level of our security practices.
+
+- Access to services, applications, and infrastructure is controlled via SSO
+  using our corporate identity provider.
+- We require strong, phishing-resistant 2FA on all identity accounts.
+- We rely on identity and device policy-enforced access controls for all
+  services.
+- No access is the default, when access to systems is granted the least
+  privilege required is granted. When possible temporary permission escalation
+  is used.
+- Access controls are centralized, employee onboarding/offboarding is automated,
+  and audit logs are kept for all business-critical services. Access grants are
+  regularly audited.
+
+### Network and Infrastructure Security
+
+Zuplo implements many layers of security to ensure our networks and
+infrastructure remain secure.
+
+- Our infrastructure runs on Google Cloud Platform and Cloudflare.
+- Zuplo only exposes traffic directly to the internet through Cloudflare.
+  Internal infrastructure and services don't have public IP addresses and
+  instead are connected to Cloudflare using outbound secure tunnels.
+- Each service that's exposed is protected by DDoS, Firewall, WAF, and other
+  security measures.
+- Internal and external APIs are protected by Zuplo API Gateway.
+- Internal services can only be connected to by Zuplo employees using an
+  identity and device policy-enforced proxy using secure tunnels.
+- Interconnected Zuplo services utilize mTLS authentication or gateway
+  authorization for access control.
+- Traffic between Zuplo services or services Zuplo uses is encrypted in transit.
+- Customer data and compute is isolated in multiple ways (secure Kubernetes
+  virtualization, V8 Isolates, etc.)
+- Logging data is centralized and configured for monitoring and alerting.
+- Customer data is encrypted at rest.
+
+### Application Security
+
+At Zuplo, application security is considered at every phase of software
+development. We utilize multiple layers and tools to help us build secure
+software.
+
+- Changes are done via pull requests with code reviews.
+- Infrastructure is managed via Terraform, changes go through code reviews.
+- Third-party dependencies are continually scanned for vulnerabilities and
+  patches are applied using automated tools whenever possible.
+- Containers are automatically scanned using GCP Container Scanning.
+- Penetration testing is performed regularly.
+- Builds and deployments are fully automated.
+
+### Disaster Recovery
+
+We understand that if we go down, our customers' APIs go down too. While Zuplo
+has an excellent track record of uptime serving billions and billions of
+requests with zero downtime, the team also plans for the worst. We maintain a
+variety of measures to ensure we can quickly recover from any type of disaster.
+
+- Full data backups occur on regular schedules (usually every 6 hours)
+- Incremental backups occur frequently (usually every hour)
+- Event-based backups occur for customer APIs - for example, we save each
+  production Gateway build/configuration so everything needed to recover
+  customer services to a particular point in time is available.
+- Data recovery is tested regularly with full disaster recovery testing done
+  every year.
+- Business critical configuration is managed via source code (mostly Terraform)
+  to ensure that in the event portions of our infrastructure are taken offline
+  they can be quickly restored.
+- Business critical services used by Zuplo have enterprise SLAs with at least
+  99.95% uptime guarantees.
+
+### Compliance
+
+See our [Trust & Compliance Report](https://trust.zuplo.com/) for details on
+compliance including our SOC2 Type II accreditation status.
+
+### Security Questionnaire
+
+If you have a custom security questionnaire, send it to us and we will get
+responses back to you as soon as possible.