zuplo 6.73.27 → 6.73.28

package/docs/cli/create-zuplo-api.mdx

@@ -16,8 +16,11 @@ npx create-zuplo-api@latest
 `create-zuplo-api` comes with the following options:
 
 - `-v, --version` - Output the current version of create-zuplo-api
-- `--eslint` - Initialize with ESLint configuration
-- `--prettier` - Initialize with Prettier configuration
+- `--linter <linter>` - The linter to configure (`eslint`, `biome`, `oxlint`, or
+  `none`). See
+  [Choosing a linter and formatter](#choosing-a-linter-and-formatter)
+- `--formatter <formatter>` - The formatter to configure (`prettier`, `biome`,
+  `oxfmt`, or `none`)
 - `--empty` - Initialize an empty project
 - `--use-npm` - Explicitly tell the CLI to bootstrap the application using npm
 - `--use-pnpm` - Explicitly tell the CLI to bootstrap the application using pnpm
@@ -38,6 +41,9 @@ npx create-zuplo-api@latest
 - `--agents <agents>` - Comma-separated list of AI coding agents to configure
   (`claude`, `copilot`, `cursor`, `windsurf`, `codex`), or `none` to skip agent
   setup. See [Configuring AI coding agents](#configuring-ai-coding-agents)
+- `--template <template-name>` - A built-in template to bootstrap the API with
+  (`default`, `default-empty`, or `ai-gateway-v2`). Can't be combined with
+  `--example` or `--empty`. See [Choosing a template](#choosing-a-template)
 - `-e, --example <example-name|github-url>` - An example to bootstrap the API
   with. You can use an example name from the official Zuplo repository or a
   public GitHub URL. The URL can use any branch and/or subdirectory
@@ -53,8 +59,6 @@ Each boolean option also accepts a `--no-` form that turns the feature off:
 
 | Opt-out flag          | Effect                                              |
 | --------------------- | --------------------------------------------------- |
-| `--no-eslint`         | Skip ESLint configuration                           |
-| `--no-prettier`       | Skip Prettier configuration                         |
 | `--no-git`            | Don't initialize the project as a git repository    |
 | `--no-install`        | Don't install packages                              |
 | `--no-version-check`  | Don't check for an outdated version                 |
@@ -62,19 +66,84 @@ Each boolean option also accepts a `--no-` form that turns the feature off:
 
 These flags matter most in CI and scripted use. `--yes` accepts whatever is
 saved in your preferences for any option you didn't pass, so a value you chose
-once on a workstation can carry into a later run. A `--no-` flag ignores saved
-preferences and suppresses the prompt outright, which makes the result the same
-on every machine:
+once on a workstation can carry into a later run. A `--no-` flag, or an explicit
+value such as `--linter none`, ignores saved preferences and suppresses the
+prompt outright, which makes the result the same on every machine:
 
 ```bash
-npx create-zuplo-api@latest my-api --yes --no-eslint --no-prettier --no-install --no-git
+npx create-zuplo-api@latest my-api --yes --linter none --formatter none --no-install --no-git
 ```
 
 If you pass both spellings of the same option, the affirmative flag wins — so
-`--eslint --no-eslint` initializes ESLint. `--no-server-project` is the
+`--git --no-git` initializes a git repository. `--no-server-project` is the
 exception: it always wins, even when combined with `--server-project` or
 `--account`.
 
+### Choosing a template
+
+`--template` selects which built-in template the CLI scaffolds from. Without the
+flag you get the `default` template.
+
+| Value           | What it scaffolds                                                                             |
+| --------------- | --------------------------------------------------------------------------------------------- |
+| `default`       | Sample `/todos` routes, a `hello-world` module, a dev portal in `docs/`, and VS Code settings |
+| `default-empty` | The same project with no routes defined and no VS Code settings                               |
+| `ai-gateway-v2` | An [AI Gateway](../ai-gateway/introduction.mdx) project, without a dev portal                 |
+
+`--empty` is shorthand for `--template default-empty`.
+
+The `ai-gateway-v2` template scaffolds `config/ai.oas.json`, which routes
+`/:app_id/v1/*` to the AI Gateway handler, and `config/policies.json`, which
+declares the policies an application's policy chain can select. It ships no
+`docs/` directory, so the CLI skips the
+[dev portal](../dev-portal/introduction.mdx) workspace:
+
+```bash
+npx create-zuplo-api@latest my-gateway --template ai-gateway-v2
+```
+
+`--template` names a built-in template, which is why it can't be combined with
+`--example` (a project pulled from GitHub) or with `--empty` (use
+`--template default-empty`). Either combination stops the CLI before it writes
+any files, as does a template name that isn't in the table above.
+
+### Choosing a linter and formatter
+
+`--linter` and `--formatter` pick the tools the CLI sets up. Without either flag
+the CLI asks, with ESLint and Prettier preselected.
+
+| `--linter` | Config file        | Dev dependencies                            |
+| ---------- | ------------------ | ------------------------------------------- |
+| `eslint`   | `eslint.config.js` | `eslint`, `@eslint/js`, `typescript-eslint` |
+| `biome`    | `biome.json`       | `@biomejs/biome`                            |
+| `oxlint`   | `.oxlintrc.json`   | `oxlint`                                    |
+| `none`     | None               | None                                        |
+
+| `--formatter`     | Config file        | Dev dependencies |
+| ----------------- | ------------------ | ---------------- |
+| `prettier`        | `.prettierrc.json` | `prettier`       |
+| `biome`           | `biome.json`       | `@biomejs/biome` |
+| `oxfmt` (in beta) | `.oxfmtrc.json`    | `oxfmt`          |
+| `none`            | None               | None             |
+
+A linter adds `lint` and `lint:fix` scripts to `package.json`, and a formatter
+adds `format` and `format:check`. The dev portal workspace in `docs/` gets the
+same `lint` script. The CLI also writes a `.vscode/extensions.json` that
+recommends the editor extensions for the tools you picked.
+
+Biome fills both roles from one dependency and a single `biome.json`:
+
+```bash
+npx create-zuplo-api@latest my-api --linter biome --formatter biome
+```
+
+Picking Biome as the linter preselects it as the formatter in the interactive
+prompt. Pairing ESLint with Prettier also installs `eslint-config-prettier`, so
+the linter doesn't fight the formatter.
+
+An unrecognized value is an error and prints the valid values. With `--yes` or in
+CI, the CLI uses your saved preferences, or ESLint and Prettier if you have none.
+
 ### Configuring AI coding agents
 
 Pass `--agents` to write instruction files and MCP configuration for the coding
@@ -171,8 +240,16 @@ The CLI asks the following questions:
 ```text
 ? What is your project named? › my-api
 ? Create a matching project on portal.zuplo.com? › No / Yes
-? Would you like to use ESLint? › No / Yes
-? Would you like to use Prettier? › No / Yes
+? Which linter would you like to use? › - Use arrow-keys. Return to submit.
+❯   ESLint
+    Biome
+    Oxlint
+    None
+? Which formatter would you like to use? › - Use arrow-keys. Return to submit.
+❯   Prettier
+    Biome
+    Oxfmt
+    None
 ? Which AI coding agents would you like to configure? › - Space to select. Return to submit
 ◯   Claude Code
 ◯   GitHub Copilot

package/docs/policies/_index.md

@@ -101,6 +101,7 @@
 | upstream-gcp-federated-auth-inbound | Upstream GCP Federated Auth | Authenticates with GCP resources or Google services using Workload Identity Federation allowing secure access to these resources without requiring the use of a service account private key. | api-gateway |
 | upstream-gcp-jwt-inbound | Upstream GCP Self-Signed JWT | Creates a self-signed JWT token (generated using a Google Service Account JSON) and attaches it to the outgoing request. Useful when calling GCP services like Cloud Endpoints / ESPv2 | api-gateway |
 | upstream-gcp-service-auth-inbound | Upstream GCP Service Auth | Creates an ID Token from Google's OAuth service and attaches it to the outgoing request. Useful when calling GCP services or Google APIs that are secured with GCP IAM. | api-gateway |
+| upstream-oauth-client-credentials-inbound | Upstream OAuth 2.0 Client Credentials Auth | Fetches an access token from any OAuth 2.0 token endpoint using the client credentials grant and adds it to a header (`Authorization` by default) on the upstream request. Tokens are cached until shortly before they expire. | api-gateway |
 | upstream-zuplo-jwt-auth-inbound | Upstream Zuplo JWT | Generates a Zuplo JWT token and attaches it to the outgoing request. This policy creates a self-signed JWT using the Zuplo JWT plugin and adds it to the specified header for upstream authentication. | api-gateway |
 | web-bot-auth-inbound | Web Bot Auth | Authenticate bots using web-bot-auth HTTP Message Signatures. | api-gateway |
 | xml-to-json-outbound | XML to JSON | Parses XML and converts it to JSON. | api-gateway |

package/docs/policies/upstream-oauth-client-credentials-inbound/doc.md

@@ -0,0 +1,124 @@
+This policy authenticates your Zuplo gateway to OAuth 2.0-protected backend
+services by automatically adding an access token to the `Authorization` header
+(or a custom header) of upstream requests. It uses the OAuth 2.0 client
+credentials grant against any token endpoint you configure, so it works with
+Auth0, Okta, Keycloak, Microsoft Entra ID, and any other standards-compliant
+identity provider.
+
+### How It Works
+
+The policy performs the following operations:
+
+1. Requests an access token from the configured token endpoint using the client
+   credentials grant
+2. Caches the token for subsequent requests until it nears expiration
+3. Adds the token to the configured header (default `Authorization`) using the
+   `token_type` returned by the token endpoint, falling back to the configured
+   `headerScheme` (default `Bearer`)
+4. Automatically handles token renewal when needed
+
+Tokens are cached for `expires_in - expirationOffsetSeconds` seconds. If the
+token endpoint doesn't return an `expires_in` value, the policy caches the token
+conservatively as if it expired after 10 minutes (5 minutes with the default
+`expirationOffsetSeconds` of 300) rather than caching it indefinitely.
+
+### Policy Configuration
+
+Configure the policy with your identity provider's token endpoint and client
+credentials:
+
+```json
+{
+  "name": "upstream-oauth-client-credentials",
+  "export": "UpstreamOAuthClientCredentialsInboundPolicy",
+  "module": "$import(@zuplo/runtime)",
+  "options": {
+    "tokenUrl": "https://your-tenant.us.auth0.com/oauth/token",
+    "clientId": "$env(OAUTH_CLIENT_ID)",
+    "clientSecret": "$env(OAUTH_CLIENT_SECRET)",
+    "audience": "https://api.example.com",
+    "scope": "read:orders write:orders"
+  }
+}
+```
+
+### Sending Client Credentials
+
+By default (`credentialsIn: "body"`), the client credentials are sent as
+`client_id` and `client_secret` form parameters in the token request body. While
+[RFC 6749 section 2.3.1](https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1)
+recommends HTTP Basic authentication, `body` is the default because it's the
+method most widely accepted across identity providers (including Auth0, Okta,
+Entra ID, and Keycloak) and avoids credential-encoding differences between
+providers' Basic authentication implementations.
+
+Set `credentialsIn` to `header` to send the credentials with HTTP Basic
+authentication instead:
+
+```json
+{
+  "options": {
+    "tokenUrl": "https://idp.example.com/oauth2/token",
+    "clientId": "$env(OAUTH_CLIENT_ID)",
+    "clientSecret": "$env(OAUTH_CLIENT_SECRET)",
+    "credentialsIn": "header"
+  }
+}
+```
+
+### Provider-Specific Parameters
+
+Some identity providers require extra form parameters on the token request. Use
+`additionalParameters` to send them, for example the `resource` parameter:
+
+```json
+{
+  "options": {
+    "tokenUrl": "https://idp.example.com/oauth2/token",
+    "clientId": "$env(OAUTH_CLIENT_ID)",
+    "clientSecret": "$env(OAUTH_CLIENT_SECRET)",
+    "additionalParameters": {
+      "resource": "https://api.example.com"
+    }
+  }
+}
+```
+
+The `grant_type` parameter is always `client_credentials` and the dedicated
+`clientId`, `clientSecret`, `scope`, and `audience` options always take
+precedence over entries in `additionalParameters`.
+
+### Usage Example
+
+Apply the policy to routes that need to call your OAuth-protected backend:
+
+```json
+{
+  "paths": {
+    "/api/orders": {
+      "get": {
+        "x-zuplo-route": {
+          "policies": {
+            "inbound": ["jwt-auth", "upstream-oauth-client-credentials"]
+          },
+          "handler": {
+            "export": "forwardToOrigin",
+            "module": "$import(@zuplo/runtime)",
+            "options": {
+              "baseUrl": "https://api.internal.example.com"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Security Considerations
+
+- Store the client secret as an environment variable using `$env(VARIABLE_NAME)`
+  syntax
+- Grant the OAuth client the minimum scopes required to access your backend
+  services
+- Regularly rotate your client secrets according to your security policies

package/docs/policies/upstream-oauth-client-credentials-inbound/intro.md

@@ -0,0 +1,18 @@
+Secure your origin server with OAuth 2.0 authentication by automatically adding
+an `Authorization` header to upstream requests. This policy enables your Zuplo
+gateway to authenticate with any OAuth 2.0 identity provider that supports the
+client credentials grant — such as Auth0, Okta, Keycloak, Microsoft Entra ID, or
+your own authorization server.
+
+With this policy, you'll benefit from:
+
+- **Enhanced Backend Security**: Restrict access to your origin servers to only
+  your Zuplo gateway
+- **Simplified Authentication**: Delegate authentication and authorization to
+  your gateway without backend code changes
+- **Automatic Token Management**: Handle token acquisition, caching, and renewal
+  automatically
+- **Provider Flexibility**: Works with any standards-compliant OAuth 2.0 token
+  endpoint, no provider-specific policy required
+- **Credential Security**: Store sensitive client credentials securely in your
+  Zuplo environment

package/docs/policies/upstream-oauth-client-credentials-inbound/schema.json

@@ -0,0 +1,126 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "https://cdn.zuplo.com/policies/runtime/schemas/upstream-oauth-client-credentials-inbound.json",
+  "type": "object",
+  "title": "Upstream OAuth 2.0 Client Credentials Auth",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "requiresAI": false,
+  "products": ["api-gateway"],
+  "description": "Fetches an access token from any OAuth 2.0 token endpoint using the client credentials grant and adds it to a header (`Authorization` by default) on the upstream request. Tokens are cached until shortly before they expire.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "UpstreamOAuthClientCredentialsInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "UpstreamOAuthClientCredentialsInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": ["tokenUrl", "clientId", "clientSecret"],
+          "properties": {
+            "tokenUrl": {
+              "type": "string",
+              "examples": ["https://your-tenant.us.auth0.com/oauth/token"],
+              "description": "The URL of the OAuth 2.0 token endpoint that issues the access token."
+            },
+            "clientId": {
+              "type": "string",
+              "examples": ["my-client-id"],
+              "description": "The client ID used to authenticate with the token endpoint."
+            },
+            "clientSecret": {
+              "type": "string",
+              "examples": ["$env(OAUTH_CLIENT_SECRET)"],
+              "description": "The client secret used to authenticate with the token endpoint."
+            },
+            "scope": {
+              "type": "string",
+              "examples": ["read:orders write:orders"],
+              "description": "Space-delimited list of scopes to request. When not set, the `scope` parameter is omitted from the token request."
+            },
+            "audience": {
+              "type": "string",
+              "examples": ["https://api.example.com"],
+              "description": "The value of the `audience` form parameter sent to the token endpoint. Required by some identity providers such as Auth0. When not set, the parameter is omitted from the token request."
+            },
+            "credentialsIn": {
+              "type": "string",
+              "title": "OAuthClientCredentialsLocation",
+              "default": "body",
+              "enum": ["body", "header"],
+              "x-advanced": true,
+              "description": "Where the client credentials are sent on the token request. `body` sends `client_id` and `client_secret` as form parameters. `header` sends them with HTTP Basic authentication as described in RFC 6749 section 2.3.1."
+            },
+            "additionalParameters": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "string"
+              },
+              "x-advanced": true,
+              "description": "Additional form parameters to include in the token request, for example `resource` for identity providers that require it."
+            },
+            "headerName": {
+              "type": "string",
+              "default": "Authorization",
+              "x-advanced": true,
+              "description": "The name of the header on the upstream request that the access token is set on."
+            },
+            "headerScheme": {
+              "type": "string",
+              "default": "Bearer",
+              "x-advanced": true,
+              "description": "The scheme that prefixes the access token in the header. When the token response includes a `token_type`, that value is used instead."
+            },
+            "tokenRetries": {
+              "type": "number",
+              "default": 3,
+              "x-advanced": true,
+              "description": "The number of times to retry fetching the token in the event of a failure."
+            },
+            "expirationOffsetSeconds": {
+              "type": "number",
+              "default": 300,
+              "x-advanced": true,
+              "description": "The number of seconds less than the token expiration to cache the token."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "UpstreamOAuthClientCredentialsInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "audience": "https://api.example.com",
+            "clientId": "my-client-id",
+            "clientSecret": "$env(OAUTH_CLIENT_SECRET)",
+            "credentialsIn": "body",
+            "expirationOffsetSeconds": 300,
+            "headerName": "Authorization",
+            "headerScheme": "Bearer",
+            "scope": "read:orders write:orders",
+            "tokenRetries": 3,
+            "tokenUrl": "https://your-tenant.us.auth0.com/oauth/token"
+          }
+        }
+      ]
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "6.73.27",
+  "version": "6.73.28",
   "type": "module",
   "description": "The programmable API Gateway",
   "author": "Zuplo, Inc.",
@@ -19,9 +19,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "6.73.27",
-    "@zuplo/core": "6.73.27",
-    "@zuplo/runtime": "6.73.27",
+    "@zuplo/cli": "6.73.28",
+    "@zuplo/core": "6.73.28",
+    "@zuplo/runtime": "6.73.28",
     "@zuplo/test": "1.4.0"
   }
 }