zuplo 6.67.32 → 6.68.0

package/docs/concepts/api-keys.md

@@ -0,0 +1,146 @@
+---
+title: API Keys
+---
+
+Zuplo includes a fully managed API key system with global edge validation,
+self-serve developer access, and leak detection. This page explains how the
+system works.
+
+## Core objects
+
+The API key system has three core objects:
+
+- **Buckets** group consumers for an environment. Each Zuplo project has buckets
+  for production, preview, and development. Buckets can be shared across
+  projects so consumers can authenticate to multiple APIs with a single key.
+- **Consumers** are the identities that own API keys. Each consumer has a unique
+  name within its bucket, optional metadata (available at runtime), and optional
+  tags (for management queries).
+- **API Keys** are the credential strings used to authenticate. Each consumer
+  can have multiple keys. All keys for a consumer share the same identity and
+  metadata.
+
+See [API Key Management](../articles/api-key-management.mdx) for a full
+overview, and [API Key Administration](../articles/api-key-administration.mdx)
+for managing consumers in the portal.
+
+## How validation works
+
+When a request includes an API key, the
+[API Key Authentication](../policies/api-key-inbound.mdx) policy validates it
+against Zuplo's globally distributed key service. Validation happens at the edge
+in 300+ data centers, keeping latency low and load off your backend.
+
+Key changes (creation, revocation, deletion) replicate globally in seconds.
+
+After successful validation, the policy populates `request.user`:
+
+- `request.user.sub` is set to the consumer's name
+- `request.user.data` contains the consumer's metadata (plan, customerId, etc.)
+
+This lets downstream policies and handlers make authorization decisions, apply
+per-consumer [rate limits](./rate-limiting.md), or forward identity to your
+backend.
+
+See [Authentication](./authentication.mdx) for how `request.user` works across
+all auth methods, and [RequestUser](../programmable-api/request-user.mdx) for
+the full type reference.
+
+## Consumer metadata
+
+Metadata is a JSON object stored on each consumer that is available at runtime
+when the consumer's key is used. Common uses:
+
+- **Plan/tier**: `{"plan": "gold"}` for per-plan rate limiting or feature gating
+- **Customer ID**: `{"customerId": "cust_123"}` for forwarding identity to your
+  backend
+- **Organization**: `{"orgId": 456}` for multi-tenant routing
+
+Metadata is set when creating a consumer via the
+[portal](../articles/api-key-administration.mdx),
+[Developer API](../articles/api-key-api.mdx), or
+[developer portal self-serve](#self-serve-key-management).
+
+## Tags vs metadata
+
+**Metadata** is sent to the runtime on every request and is used for
+authorization and routing. Keep it small.
+
+**Tags** are key-value pairs used only for management (querying, filtering,
+organizing consumers via the API). Tags are not sent to the runtime.
+
+## API key format and leak detection
+
+Zuplo API keys use a structured format prefixed with `zpka_` followed by
+cryptographically random characters and a signature. This format enables
+automatic [leak detection](../articles/api-key-leak-detection.mdx): if one of
+your keys appears in a public GitHub repository, Zuplo sends an alert with the
+token and the URL where it was found.
+
+Leak detection is enabled automatically for all keys using the standard format.
+
+See [API Key Leak Detection](../articles/api-key-leak-detection.mdx) for
+details.
+
+## Self-serve key management
+
+The [Developer Portal](../dev-portal/introduction.mdx) includes built-in
+self-serve API key management. Your API consumers can sign in to the portal and
+create, view, and delete their own keys without contacting your team.
+
+To enable self-serve access, assign a **manager** to a consumer. Managers are
+identified by email and identity provider subject. This can be done in the
+portal, via the [Developer API](../articles/api-key-api.mdx), or automatically
+when a user signs in using
+[Auth0](../dev-portal/dev-portal-create-consumer-on-auth.mdx) or another
+identity provider.
+
+You can also embed the key management UI directly in your own application using
+the [API Key React Component](../articles/api-key-react-component.mdx).
+
+## Buckets and environments
+
+Each project has separate buckets for production, preview, and working copy
+environments. This means API keys created in production don't work in preview,
+and vice versa.
+
+For testing, you can specify a custom bucket name on the
+[API Key Authentication](../policies/api-key-inbound.mdx) policy to share keys
+across environments. Enterprise customers can share buckets across projects or
+accounts.
+
+See [API Key Buckets](../articles/api-key-buckets.mdx) for details on bucket
+configuration and [Service Limits](../articles/api-key-service-limits.mdx) for
+limits on consumers and keys.
+
+## Managing keys programmatically
+
+The [Zuplo Developer API](../articles/api-key-api.mdx) provides full CRUD
+operations for buckets, consumers, keys, and managers. Use it to:
+
+- Create consumers and keys as part of your onboarding flow
+- Sync consumers with your billing system
+- Bulk-create keys for migration
+- Query consumers by tags
+
+See the [API Reference](/docs/api) for the complete endpoint documentation.
+
+## Related documentation
+
+- [API Key Management](../articles/api-key-management.mdx) -- Overview and
+  getting started
+- [API Key Authentication Policy](../policies/api-key-inbound.mdx) -- Policy
+  configuration reference
+- [API Key Administration](../articles/api-key-administration.mdx) -- Managing
+  keys in the portal
+- [Using the API Key API](../articles/api-key-api.mdx) -- Programmatic
+  management
+- [End User Access](../articles/api-key-end-users.mdx) -- Self-serve in the
+  developer portal
+- [React Component](../articles/api-key-react-component.mdx) -- Embed key
+  management in your app
+- [Leak Detection](../articles/api-key-leak-detection.mdx) -- GitHub secret
+  scanning
+- [Buckets](../articles/api-key-buckets.mdx) -- Bucket configuration
+- [Service Limits](../articles/api-key-service-limits.mdx) -- Rate limits and
+  quotas

package/docs/concepts/authentication.mdx

@@ -0,0 +1,109 @@
+---
+title: Authentication
+---
+
+Zuplo supports multiple authentication methods through inbound policies. All
+authentication policies follow the same pattern: validate credentials, then
+populate `request.user` with the authenticated identity.
+
+## How authentication works
+
+Authentication policies are inbound policies that run before your handler. When
+a request arrives:
+
+1. The auth policy extracts credentials (API key, JWT token, etc.)
+2. It validates the credentials against the configured provider
+3. On success, it populates `request.user` with the identity
+4. On failure, it returns a 401 Unauthorized response (short-circuiting the
+   pipeline)
+
+After authentication, all downstream policies and handlers can access
+`request.user` to make authorization decisions, apply per-user rate limits, or
+forward identity to your backend.
+
+## The `request.user` object
+
+All authentication methods populate the same interface:
+
+```ts
+interface RequestUser {
+  sub: string; // Unique subject identifier
+  data: Record<string, unknown>; // Provider-specific claims or metadata
+}
+```
+
+For **JWT/OAuth** authentication, `sub` comes from the token's `sub` claim and
+`data` contains the remaining token claims (email, roles, org, etc.).
+
+For **API key** authentication, `sub` is the consumer identifier and `data`
+contains the metadata you set when creating the consumer (plan, customerId,
+etc.).
+
+See [RequestUser](../programmable-api/request-user.mdx) for the full type
+reference.
+
+## Supported methods
+
+### API key authentication
+
+Zuplo's built-in [API key management](../articles/api-key-management.mdx)
+provides a complete system for issuing, managing, and validating API keys.
+Consumers (API key holders) can be created via the portal, API, or developer
+portal self-serve.
+
+Best for: B2B APIs, developer platforms, and any API where you manage consumer
+access.
+
+### JWT / OAuth authentication
+
+Zuplo validates JWTs from any OpenID Connect-compatible identity provider.
+Built-in policies exist for common providers:
+
+- [Auth0](../policies/auth0-jwt-auth-inbound.mdx)
+- [Clerk](../policies/clerk-jwt-auth-inbound.mdx)
+- [Okta](../policies/okta-jwt-auth-inbound.mdx)
+- [AWS Cognito](../policies/cognito-jwt-auth-inbound.mdx)
+- [Firebase](../policies/firebase-jwt-inbound.mdx)
+- [Supabase](../policies/supabase-jwt-auth-inbound.mdx)
+- [PropelAuth](../policies/propel-auth-jwt-inbound.mdx)
+- [OpenID Connect (generic)](../policies/open-id-jwt-auth-inbound.mdx)
+
+Best for: APIs consumed by your own frontend, mobile apps, or services where
+users already authenticate with an identity provider.
+
+### Other methods
+
+- [Basic Auth](../policies/basic-auth-inbound.mdx) - Username/password
+  authentication
+- [mTLS](../policies/mtls-auth-inbound.mdx) - Mutual TLS certificate
+  authentication
+- [LDAP](../policies/ldap-auth-inbound.mdx) - LDAP directory authentication
+- [HMAC](../policies/hmac-auth-inbound.mdx) - Hash-based message authentication
+
+## Combining authentication methods
+
+You can support multiple auth methods on the same route (e.g., both API keys and
+JWT tokens). The pattern is:
+
+1. Add each auth policy to the route's inbound policies
+2. Set `allowUnauthenticatedRequests: true` on each so they don't immediately
+   return 401
+3. Add a custom policy after them that checks `request.user` and returns 401 if
+   no method succeeded
+
+See [Multiple Auth Policies](../articles/multiple-auth-policies.mdx) for a
+detailed walkthrough.
+
+## Choosing an authentication method
+
+| Method                   | Use Case                                       |
+| ------------------------ | ---------------------------------------------- |
+| API Keys                 | B2B APIs, developer platforms, metered access  |
+| JWT (Auth0, Clerk, etc.) | User-facing APIs, SPAs, mobile apps            |
+| mTLS                     | Service-to-service, high-security environments |
+| Basic Auth               | Internal APIs, simple integrations             |
+| HMAC                     | Webhook verification, signed requests          |
+
+For most API products, **API key authentication** is the recommended starting
+point. It provides self-serve key management, per-consumer rate limiting, and
+usage tracking out of the box.

package/docs/concepts/how-zuplo-works.mdx

@@ -0,0 +1,120 @@
+---
+title: How Zuplo Works
+---
+
+Zuplo is a programmable API gateway that runs at the edge. This page explains
+the architecture, runtime, and deployment model.
+
+## Architecture
+
+Zuplo sits between your clients and your backend APIs. Clients send requests to
+Zuplo, which applies policies (authentication, rate limiting, validation, etc.),
+then forwards the request to your backend. Responses pass back through outbound
+policies before reaching the client.
+
+<Diagram height="h-96">
+  <DiagramNode id="clients">Clients</DiagramNode>
+  <DiagramGroup id="zuplo" label="Zuplo API Gateway">
+    <DiagramNode id="inbound" variant="zuplo">
+      Inbound Policies
+    </DiagramNode>
+    <DiagramNode id="handler" variant="zuplo">
+      Handler
+    </DiagramNode>
+    <DiagramNode id="outbound" variant="zuplo">
+      Outbound Policies
+    </DiagramNode>
+  </DiagramGroup>
+  <DiagramNode id="backend">Your Backend API</DiagramNode>
+  <DiagramEdge from="clients" to="zuplo" />
+  <DiagramEdge from="inbound" to="handler" fromSide="bottom" toSide="top" />
+  <DiagramEdge from="handler" to="outbound" fromSide="bottom" toSide="top" />
+  <DiagramEdge from="zuplo" to="backend" />
+</Diagram>
+
+Zuplo is cloud-agnostic. It works with backends running on any cloud provider or
+private infrastructure. Multiple
+[secure connectivity options](../articles/securing-your-backend.mdx) are
+available including mTLS, shared secrets, and secure tunnels.
+
+## Edge runtime
+
+Zuplo's runtime is based on Web Worker technology, the same foundational
+approach used by platforms like Deno Deploy, Vercel Edge Functions, and
+Cloudflare Workers. Code runs in lightweight V8 isolates rather than containers
+or virtual machines.
+
+This architecture provides:
+
+- **Near-zero cold starts** - isolates start in milliseconds, not seconds
+- **High throughput** - tested at over 10,000 requests per second with policies
+  enabled
+- **Low latency** - the gateway typically adds 20-30ms for basic request
+  processing
+- **Web Standards** - built on familiar browser APIs like
+  [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API),
+  [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request),
+  [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response), and
+  [Web Crypto](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API)
+
+Custom code is written in TypeScript or JavaScript. Your backend can be written
+in any language that speaks HTTP.
+
+See [Web Standard APIs](../programmable-api/web-standard-apis.mdx) and
+[Platform Limits](../articles/limits.mdx) for specifics on available APIs and
+constraints.
+
+## Deployment model
+
+Zuplo offers three hosting options:
+
+- **[Managed Edge](../managed-edge/overview.md)** - Runs in 300+ data centers
+  worldwide. Deploys in seconds via Git. Best for most use cases.
+- **[Managed Dedicated](../dedicated/overview.mdx)** - Dedicated infrastructure
+  in your preferred cloud region. For teams with compliance, data residency, or
+  performance isolation requirements.
+- **[Self-Hosted](../self-hosted/overview.md)** - Run Zuplo in your own
+  infrastructure.
+
+All hosting options use the same runtime, configuration, and APIs. Your project
+code works identically across all three.
+
+## GitOps workflow
+
+Everything in Zuplo is defined as code and stored in source control. The typical
+workflow is:
+
+1. **Develop** locally or in the Zuplo Portal
+2. **Push** to your Git repository (GitHub, GitLab, Bitbucket, or Azure DevOps)
+3. **Deploy** automatically - Zuplo builds and deploys your gateway globally
+
+Deployments complete in seconds. Each Git branch gets its own isolated
+environment with its own URL, making it easy to test changes before merging to
+production.
+
+See [Environments](../articles/environments.mdx) and
+[Source Control](../articles/source-control.mdx) for details.
+
+## Protocols
+
+Zuplo can proxy any HTTP traffic including REST, GraphQL, WebSockets, and other
+HTTP-based protocols. HTTP/2 is fully supported.
+
+## Programmability
+
+While most API gateways limit you to configuration, Zuplo lets you write custom
+logic that runs in-process at the gateway layer:
+
+- **[Custom policies](../policies/custom-code-inbound.mdx)** - intercept
+  requests and responses with TypeScript
+- **[Custom handlers](../handlers/custom-handler.mdx)** - implement entire
+  request handlers in code
+- **[Runtime extensions](../programmable-api/runtime-extensions.mdx)** - add
+  global hooks that run on every request
+
+Custom code has access to the full
+[Programming API](../programmable-api/overview.mdx) including caching, logging,
+environment variables, and more.
+
+See [Request Lifecycle](./request-lifecycle.md) for details on how these
+extension points compose together.

package/docs/concepts/project-structure.mdx

@@ -0,0 +1,174 @@
+---
+title: Project Structure
+---
+
+A Zuplo project is a standard Node.js-style project managed via Git. Here is the
+typical layout:
+
+```
+my-api/
+├── config/
+│   ├── routes.oas.json     # Route definitions (OpenAPI format)
+│   └── policies.json       # Policy configuration
+├── modules/
+│   └── my-handler.ts       # Custom handlers and policies
+├── docs/                   # Developer portal (optional)
+│   └── zudoku.config.ts
+├── zuplo.jsonc             # Project configuration
+├── package.json
+├── .env                    # Local environment variables (do not commit)
+└── .env.zuplo              # Generated by `zuplo link` (do not commit)
+```
+
+## Core files
+
+### `config/routes.oas.json`
+
+This is an OpenAPI 3.1 specification that defines your API routes. Each route
+specifies the HTTP method, path, handler, and which policies to apply. Zuplo
+extends the OpenAPI spec with `x-zuplo-route` to attach handlers and policies to
+each operation.
+
+```json
+{
+  "paths": {
+    "/users/{userId}": {
+      "get": {
+        "operationId": "get-user",
+        "x-zuplo-route": {
+          "corsPolicy": "anything-goes",
+          "handler": {
+            "export": "urlForwardHandler",
+            "module": "$import(@zuplo/runtime)",
+            "options": {
+              "baseUrl": "https://api.example.com"
+            }
+          },
+          "policies": {
+            "inbound": ["api-key-inbound", "rate-limit-inbound"]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+You can have multiple OpenAPI files. They are processed in alphabetical order
+during route matching.
+
+See [OpenAPI](../articles/openapi.mdx) and [Routing](../articles/routing.mdx)
+for details.
+
+### `config/policies.json`
+
+This file defines policy instances by name, type, and configuration. Routes
+reference policies by name in their `policies.inbound` and `policies.outbound`
+arrays.
+
+```json
+{
+  "policies": [
+    {
+      "name": "api-key-inbound",
+      "policyType": "api-key-inbound",
+      "handler": {
+        "export": "ApiKeyInboundPolicy",
+        "module": "$import(@zuplo/runtime)"
+      }
+    },
+    {
+      "name": "rate-limit-inbound",
+      "policyType": "rate-limit-inbound",
+      "handler": {
+        "export": "RateLimitInboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "rateLimitBy": "ip",
+          "requestsAllowed": 100,
+          "timeWindowMinutes": 1
+        }
+      }
+    }
+  ]
+}
+```
+
+### `zuplo.jsonc`
+
+Project-level configuration including the runtime compatibility date and
+deployment type.
+
+```json
+{
+  "version": 1,
+  "compatibilityDate": "2025-02-06",
+  "projectType": "managed-edge"
+}
+```
+
+The `projectType` can be `managed-edge`, `managed-dedicated`, or `self-hosted`.
+The `compatibilityDate` locks runtime behavior so updates don't break your
+project unexpectedly.
+
+See [Project Configuration](../programmable-api/zuplo-json.mdx) for all options.
+
+### `modules/`
+
+Contains your custom TypeScript code for handlers and policies. These modules
+are referenced from `routes.oas.json` and `policies.json` using
+`$import(./modules/...)`.
+
+```json
+{
+  "handler": {
+    "export": "default",
+    "module": "$import(./modules/my-handler)"
+  }
+}
+```
+
+### `docs/` (optional)
+
+If you use the Zuplo Developer Portal, this directory contains the portal
+configuration and custom pages. See
+[Developer Portal](../dev-portal/introduction.mdx) for details.
+
+## How the files relate
+
+1. **`zuplo.jsonc`** sets project-wide configuration (runtime version,
+   deployment type)
+2. **`config/routes.oas.json`** defines API routes and wires each route to a
+   handler and policies by name
+3. **`config/policies.json`** defines the named policy instances with their
+   configuration and points to either built-in modules (`@zuplo/runtime`) or
+   custom modules in `./modules`
+4. **`modules/`** contains the TypeScript implementations for custom handlers
+   and policies
+
+All of this lives in Git and deploys automatically when you push.
+
+## The `$import()` syntax
+
+JSON configuration files (`routes.oas.json` and `policies.json`) use the
+`$import()` syntax to reference code modules. This is a Zuplo-specific syntax
+that resolves module references at build time.
+
+```json
+{
+  "module": "$import(@zuplo/runtime)"
+}
+```
+
+References starting with `@zuplo/runtime` point to built-in Zuplo modules
+(policies, handlers, and utilities).
+
+```json
+{
+  "module": "$import(./modules/my-handler)"
+}
+```
+
+References starting with `./modules/` point to your custom TypeScript files in
+the `modules/` directory. The `export` field specifies which named export to use
+from that module.