zuplo 6.72.1 → 6.72.3

package/docs/articles/accounts/audit-logs.mdx

@@ -1,5 +1,5 @@
 ---
-title: Audit Logs
+title: Account Audit Logs
 sidebar_label: Audit Logs
 ---
 
@@ -211,8 +211,8 @@ exceed 30 days. The start date must be before the end date.
 
 :::tip
 
-Account audit logs track administrative activities. To log API request and
-response data flowing through the gateway, see the
-[Audit Log Plugin](../../programmable-api/audit-log.mdx).
+Account audit logs track administrative activities in your Zuplo account. To
+record an audit trail of the requests flowing through your gateway, see
+[Audit Logging](../audit-logging.mdx).
 
 :::

package/docs/articles/audit-logging.mdx

@@ -0,0 +1,65 @@
+---
+title: Audit Logging
+sidebar_label: Overview
+---
+
+Audit logs answer the question "who did what through your API, and when?" —
+providing a structured, searchable record of every request and business event
+that flows through your gateway. This page explains why audit logging matters
+and the options Zuplo gives you for capturing an audit trail.
+
+## Why audit logging?
+
+Audit logging plays a critical role in API security: it lets you detect and
+investigate issues such as unauthorized access or permission elevation, and
+reconstruct exactly what happened to a resource after the fact. It's also a hard
+requirement for many compliance certifications (SOC 2, ISO 27001, HIPAA, PCI
+DSS) and a common buying criterion for enterprise customers of your API.
+
+Unlike request logs — which are optimized for debugging and operational
+visibility — audit logs are structured business records: each event identifies
+an actor, an action, and the resources affected, in a stable format you can
+retain, search, and hand to an auditor.
+
+## Options for audit logging
+
+Zuplo supports two approaches, depending on where you want your audit trail to
+live:
+
+1. **[Zuplo Audit Logs](./audit-logs.mdx)** — the recommended approach for most
+   APIs. Add a single policy and Zuplo records, stores, and indexes a structured
+   audit event for every request. You can search the events in the Zuplo Portal,
+   query them through the Zuplo API, and export them to a SIEM. No code or
+   infrastructure required.
+2. **[Custom audit logs](./custom-audit-logs.mdx)** — write a small custom
+   policy that sends audit events to any external audit provider (for example,
+   WorkOS Audit Logs). Full control over the event format and destination.
+
+|              | Zuplo Audit Logs          | Custom audit logs     |
+| ------------ | ------------------------- | --------------------- |
+| Setup        | Add a policy              | Write policy code     |
+| Storage      | Managed by Zuplo          | Your provider         |
+| Viewing      | Zuplo Portal + Zuplo API  | Your provider's tools |
+| Availability | Enterprise (free to test) | All plans             |
+
+Zuplo Audit Logs is an enterprise feature, but anyone can use it for free for
+development and testing purposes.
+
+## Gateway audit logs versus account audit logs
+
+Zuplo has two separate audit trails — the options above all concern the first:
+
+- **Gateway audit logs** record traffic through _your API_: requests from your
+  API's consumers and custom events emitted by your gateway code.
+- **[Account audit logs](./accounts/audit-logs.mdx)** record administrative
+  activity in _your Zuplo account_: project changes, team member management,
+  deployments, and other portal and API operations.
+
+## Next steps
+
+- [Zuplo Audit Logs](./audit-logs.mdx) — enable the built-in feature and start
+  recording events
+- [Custom audit logs](./custom-audit-logs.mdx) — send audit events to an
+  external provider
+- [Audit Logs policy reference](../policies/audit-log-inbound.mdx) — all
+  configuration options and the full event shape

package/docs/articles/audit-logs.mdx

@@ -0,0 +1,222 @@
+---
+title: Zuplo Audit Logs
+sidebar_label: Zuplo Audit Logs
+---
+
+Zuplo's Audit Logs feature gives you a complete
+[audit trail](./audit-logging.mdx) of your API with a single policy: the gateway
+records a structured event for every request, stores the events for you, and
+makes them available in the Zuplo Portal and through the Zuplo API.
+
+<EnterpriseFeature name="Audit Logs" />
+
+## How it works
+
+<Diagram height="h-56">
+  <DiagramNode id="client">Client</DiagramNode>
+  <DiagramGroup id="zuplo" label="Zuplo">
+    <DiagramNode id="gateway" variant="zuplo">
+      Gateway (Audit Logs policy)
+    </DiagramNode>
+    <DiagramNode id="store">Audit log storage</DiagramNode>
+  </DiagramGroup>
+  <DiagramNode id="consumers">Portal / API / SIEM</DiagramNode>
+  <DiagramEdge from="client" to="gateway" />
+  <DiagramEdge from="gateway" to="store" label="events" />
+  <DiagramEdge from="store" to="consumers" />
+</Diagram>
+
+Add the [Audit Logs policy](../policies/audit-log-inbound.mdx) to any route and
+the gateway records one structured audit event per request — who made the
+request, what they called, and the outcome. You can also emit your own custom
+events (for example, "account deleted") from handlers and custom policies. Every
+event follows the [CloudEvents](https://cloudevents.io/) 1.0 format.
+
+Zuplo stores the events for you, grouped by environment — production, preview,
+and working copy environments each write to their own bucket. You don't need a
+database, logging service, or any other infrastructure of your own.
+
+## Recording audit events
+
+### Automatic request events
+
+Add the policy to the routes you want audited. Typically that's any route that
+modifies data, though depending on your API you may want it on sensitive read
+operations as well (for example, retrieving a secret).
+
+```json title="config/policies.json"
+{
+  "name": "audit-logs",
+  "policyType": "audit-log-inbound",
+  "handler": {
+    "export": "AuditLogInboundPolicy",
+    "module": "$import(@zuplo/runtime)"
+  }
+}
+```
+
+Each request through the policy produces an event of type
+`com.zuplo.api.request` capturing the actor, HTTP method and path, response
+status, caller IP address, and geolocation.
+
+Audit events can contain personal or sensitive data. The policy's `include`
+options let you turn off individual fields (query parameters, user identity, IP
+address, geolocation) to satisfy your own data-handling and personally
+identifiable information (PII) policies, and `samplingRate` lets you capture
+only a fraction of requests on high-volume routes. See the
+[policy reference](../policies/audit-log-inbound.mdx) for all options.
+
+### Custom events
+
+Beyond the automatic per-request event, record your own domain events from a
+handler or custom policy with the static `AuditLogInboundPolicy.log()` method.
+Only `type` is required — Zuplo fills in the actor, timestamp, request ID, and
+other context fields automatically from the request:
+
+```ts title="modules/handlers.ts"
+import {
+  AuditLogInboundPolicy,
+  ZuploContext,
+  ZuploRequest,
+} from "@zuplo/runtime";
+
+export async function deleteAccount(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  const accountId = request.params.accountId;
+
+  // ...perform the delete...
+
+  AuditLogInboundPolicy.log(context, {
+    type: "com.acme.account.deleted",
+    subject: `account|${accountId}`,
+    resources: [{ type: "account", id: accountId }],
+    success: true,
+  });
+
+  return new Response(null, { status: 204 });
+}
+```
+
+Audit logging is best-effort by design: `log()` never throws and never blocks or
+fails the request, even if an event can't be recorded.
+
+## Viewing audit logs in the portal
+
+To browse and search your audit logs, open your project's
+[**Services**](https://portal.zuplo.com/+/account/project/services) page in the
+Zuplo Portal and select the **Audit Logs** tile for the environment you want to
+inspect.
+
+The events view lets you:
+
+- Filter events by time range, event type, actor, and subject
+- See the top event types and most active actors for the selected window
+- Select any event to inspect the full event payload
+
+## Querying audit logs with the API
+
+Everything in the portal is backed by the Zuplo API, so you can query audit logs
+programmatically — for scripting, custom dashboards, or exporting to other
+systems. Authenticate with a [Zuplo API key](./accounts/zuplo-api-keys.mdx) and
+query events by bucket name. Your bucket name is shown on the **Services** page
+in the portal (it's the same bucket used by the API Key Service).
+
+```bash
+curl "https://dev.zuplo.com/v1/audit-logs/$BUCKET_NAME/events?type=com.zuplo.api.request&startDate=2026-07-01T00:00:00Z&endDate=2026-07-07T00:00:00Z" \
+  -H "Authorization: Bearer $ZUPLO_API_KEY"
+```
+
+```json
+{
+  "data": [
+    {
+      "specversion": "1.0",
+      "id": "e6c8b1f2-2c3d-4a5b-9e10-1f2a3b4c5d6e",
+      "type": "com.zuplo.api.request",
+      "time": "2026-07-05T18:12:04.123Z",
+      "actorsub": "user|12356",
+      "actortype": "user",
+      "requestid": "b1a2c3d4-e5f6-7890-abcd-ef1234567890",
+      "httpmethod": "GET",
+      "httpurl": "/customers/12345?expand=orders",
+      "httpstatus": 200,
+      "success": true,
+      "ipaddress": "203.0.113.7",
+      "useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...",
+      "country": "US",
+      "region": "Washington",
+      "city": "Seattle"
+    }
+  ],
+  "pagination": { "limit": 20, "offset": 0, "total": 1, "hasMore": false }
+}
+```
+
+Two endpoints are available:
+
+- **Query events** — `GET /v1/audit-logs/{bucketId}/events` returns matching
+  events, filterable by `type`, `actorSub`, `subject`, and time range.
+- **Aggregated stats** — `GET /v1/audit-logs/{bucketId}/stats` returns top-N
+  event counts grouped by event type or actor.
+
+The `bucketId` path parameter accepts either the bucket ID or the bucket name.
+Each query is limited to a 30-day window between `startDate` and `endDate`. See
+the [Audit Logs API reference](../api/audit-logs) for all parameters and
+response schemas.
+
+## Exporting audit logs to a SIEM
+
+Many organizations centralize audit trails in a SIEM (Splunk, Microsoft
+Sentinel, Datadog Cloud SIEM, and so on) to correlate API activity with other
+security signals, drive alerting, and meet long-term retention requirements. The
+events API is designed for this: run a scheduled job that pulls new events since
+its last checkpoint and forwards them to your SIEM.
+
+```ts
+const BASE_URL = "https://dev.zuplo.com/v1/audit-logs";
+
+// Run on a schedule (e.g. every 5 minutes). `startDate` is the checkpoint
+// saved by the previous run; `endDate` is the current time.
+async function exportAuditLogs(
+  bucketName: string,
+  startDate: string,
+  endDate: string,
+) {
+  let offset = 0;
+  let hasMore = true;
+  while (hasMore) {
+    const url = new URL(`${BASE_URL}/${bucketName}/events`);
+    url.searchParams.set("startDate", startDate);
+    url.searchParams.set("endDate", endDate);
+    url.searchParams.set("limit", "100");
+    url.searchParams.set("offset", String(offset));
+    const response = await fetch(url, {
+      headers: { Authorization: `Bearer ${process.env.ZUPLO_API_KEY}` },
+    });
+    const { data, pagination } = await response.json();
+    await sendToSiem(data); // e.g. Splunk HEC, Datadog Logs API, S3
+    offset += data.length;
+    hasMore = pagination.hasMore;
+  }
+}
+```
+
+Because every event is a CloudEvents document, most SIEMs can ingest the payload
+directly without transformation.
+
+Alternatively, if you'd rather send audit events to an external audit provider
+directly from the gateway instead of storing them in Zuplo, see
+[Custom Audit Logs](./custom-audit-logs.mdx).
+
+## Related resources
+
+- [Audit logging overview](./audit-logging.mdx) — why audit logging matters and
+  how the options compare
+- [Audit Logs policy reference](../policies/audit-log-inbound.mdx) — all
+  configuration options, custom event fields, and the full event shape
+- [Audit Logs API reference](../api/audit-logs) — query events and stats
+  programmatically
+- [Account audit logs](./accounts/audit-logs.mdx) — the audit trail of your
+  Zuplo account itself

package/docs/articles/{custom-audit-log-policy.mdx → custom-audit-logs.mdx}

@@ -1,29 +1,22 @@
 ---
-title: Custom Audit Logging Policy
-sidebar_label: Audit Logging
+title: Custom Audit Logs
+sidebar_label: Custom Audit Logs
 ---
 
-This guide explains how to add custom audit logging beyond the scope of the
-`AuditLogsInboundPolicy`.
+[Zuplo Audit Logs](./audit-logs.mdx) stores your audit trail in Zuplo and gives
+you a portal viewer and query API out of the box. If your organization uses an
+external audit logging service instead, you can send events to it directly from
+the gateway with a [custom policy](../policies/custom-code-inbound.mdx) that
+uses [runtime hooks](../programmable-api/runtime-extensions.mdx). This approach
+works on any plan — it's just custom code — and gives you full control over
+which events are recorded, the event format, and the destination.
 
-Audit logging is an important part of API security that plays a critical role in
-detecting and correcting issues such as unauthorized access or permission
-elevations within your system. Audit logging is also a requirement for many
-compliance certifications as well as part of the buying criteria for larger
-enterprises.
-
-Adding Audit Logging to your APIs that are secured with Zuplo is as easy as
-adding a custom policy. Typically you want to add audit logs to any API that
-modifies data, however depending on the API you may want it on read operations
-as well (for example retrieve a secret key, etc.)
-
-## Example Policy: WorkOS Audit Logs
+## Example: WorkOS Audit Logs
 
 [WorkOS](https://workos.com/) provides various services that help enable
-enterprise features on your service such as SSO and Audit Logs. With Zuplo it's
-easy to create a [custom policy](../policies/custom-code-inbound.mdx) that uses
-[runtime hooks](../programmable-api/runtime-extensions.mdx) to log API calls
-using their API.
+enterprise features on your service such as SSO and Audit Logs. The following
+custom policy logs API calls to the WorkOS Audit Logs API after each response is
+sent:
 
 ```ts
 import { ZuploContext, ZuploRequest, environment } from "@zuplo/runtime";
@@ -34,7 +27,7 @@ export async function auditLogPlugin(
   policyName: string,
 ) {
   // Clone the request so the body can be read in the hook
-  // note: remove this is you don't need content from the body
+  // note: remove this if you don't need content from the body
   const cloned = request.clone();
   context.addResponseSendingFinalHook(async (response) => {
     const incomingBody = await cloned.json();
@@ -48,7 +41,7 @@ export async function auditLogPlugin(
         version: 1,
         actor: {
           type: "user",
-          // Add the use the user sub for authenticated users
+          // Use the user sub for authenticated users
           id: request.user.sub,
           metadata: {
             role: "user",
@@ -93,3 +86,14 @@ export async function auditLogPlugin(
   return request;
 }
 ```
+
+The same pattern works for any provider with an HTTP API — swap the event shape
+and endpoint for your provider's, and store credentials in
+[environment variables](./environment-variables.mdx).
+
+## Related resources
+
+- [Audit logging overview](./audit-logging.mdx) — why audit logging matters and
+  how the options compare
+- [Zuplo Audit Logs](./audit-logs.mdx) — the built-in feature with portal
+  viewing and a query API

package/docs/policies/_index.md

@@ -91,6 +91,7 @@
 | request-size-limit-inbound | Request Size Limit | Enforces a maximum size in bytes of the incoming request. | api-gateway |
 | request-validation-inbound | Request Validation | Validates incoming requests against your OpenAPI specification. Checks query parameters, path parameters, headers, and request body to ensure they match the defined schema before processing. | api-gateway |
 | require-origin-inbound | Require Origin | Sets an allow-list for an origin header | api-gateway |
+| require-user-claims-inbound | Require User Claims | Authorizes requests by validating claims on the authenticated user (`request.user`) against a configurable rule of `and`/`or` combinators and per-claim `eq`, `in`, and `startsWith` checks. Run it after any authentication policy that populates `request.user` — a JWT auth policy, API key auth, mTLS, and so on — to allow only specific callers (service accounts, OAuth clients, tenants, groups) without writing custom code.  Every check fails closed: a missing or non-primitive claim never matches, comparisons are strict and type-sensitive, and requests without an authenticated user receive a 401 response. Denied requests receive a 403 response that does not echo claim values or expected values; the failing checks are written to the request log instead.  Validation of the options runs lazily inside the policy constructor, which the runtime caches per policy name. Misconfigured options therefore fail on first use with a customer-facing `ConfigurationError` instead of failing at module load. | api-gateway |
 | secret-masking-outbound | Secret Masking | Masks common secrets like Zuplo API keys, GitHub tokens, or SSH private key in the response body. | api-gateway |
 | semantic-cache-inbound | Semantic Cache | Respond to matched incoming requests with semantically cached content  The Semantic Cache Inbound policy caches responses based on semantic similarity of cache keys rather than exact matches. This allows for more flexible caching where similar requests can return cached responses even if the cache key is not exactly the same.  The policy uses Large Language Model (LLM) embeddings to determine semantic similarity between cache keys based on a configurable similarity tolerance.  Options: - semanticTolerance: The semantic similarity threshold for semantic cache matches (0-1, default: 0.2). Values closer to 0 require higher similarity. Can be overridden by custom functions. - expirationSecondsTtl: The timeout of the cache in seconds (default: 3600, 1 hour). Can be overridden by custom functions. - namespace: Optional namespace to isolate cache entries (default: "default"). Useful for multi-tenant scenarios or different cache contexts. - cacheBy: Determines how cache keys are generated: 'function' for custom logic or 'propertyPath' to extract from JSON body. | ai-gateway |
 | set-body-inbound | Set Body | Sets the body of the request in the inbound pipeline - make sure to convert a GET/HEAD request to another method when using this policy. | api-gateway |

package/docs/policies/audit-log-inbound/doc.md

@@ -16,14 +16,14 @@ requests).
 ## Controlling What's Logged
 
 Audit events can contain personal or sensitive data. To keep audit logging
-compliant with your own data-handling and PII policies, use the `include`
-option to turn individual fields off. Everything is captured by default; set a
-flag to `false` to omit it:
+compliant with your own data-handling and PII policies, use the `include` option
+to turn individual fields off. Everything is captured by default; set a flag to
+`false` to omit it:
 
 - `queryParams` — the request's query-string parameters (in the logged URL).
-- `user` — the authenticated user / actor identity (subject, email,
-  connection). The `user` vs `anonymous` classification is always kept, but the
-  identifying values are omitted when disabled.
+- `user` — the authenticated user / actor identity (subject, email, connection).
+  The `user` vs `anonymous` classification is always kept, but the identifying
+  values are omitted when disabled.
 - `ipAddress` — the caller's IP address.
 - `geolocation` — the caller's country, region, and city.
 
@@ -87,7 +87,8 @@ export async function deleteAccount(
 The event object passed to `log()` supports the following fields. Only `type` is
 required.
 
-- `type` — the event type, in reverse-DNS form (e.g. `com.acme.account.deleted`).
+- `type` — the event type, in reverse-DNS form (e.g.
+  `com.acme.account.deleted`).
 - `subject` — the primary entity the event is about.
 - `resources` — an array of `{ type, id, metadata? }` describing the resources
   the event affected.
@@ -95,9 +96,8 @@ required.
 - `data` — any additional structured data to attach to the event.
 - `actor` — override the automatically-derived actor
   (`{ sub, type, email, connection }`).
-- `country`, `region`, `city` — override the caller's geolocation. These
-  default to the current request's location, so you normally don't need to set
-  them.
+- `country`, `region`, `city` — override the caller's geolocation. These default
+  to the current request's location, so you normally don't need to set them.
 
 Audit logging is best-effort: `log()` never throws and never blocks or fails the
 request, even if an event cannot be recorded.
@@ -134,4 +134,9 @@ pass, and the remaining fields are populated from the request context.
 
 ## Viewing Audit Logs
 
-In-portal viewing and retrieval of audit logs is coming soon.
+Audit logs are available in the [Zuplo portal](https://portal.zuplo.com) under
+your project's Audit Log service, where you can browse and search the events
+recorded by this policy.
+
+You can also query audit logs programmatically using the
+[Zuplo API](https://zuplo.com/docs/api).

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

@@ -7,7 +7,7 @@
   "isPaidAddOn": false,
   "isEnterprise": true,
   "isInternal": false,
-  "isBeta": true,
+  "isBeta": false,
   "isHidden": false,
   "requiresAI": false,
   "products": ["api-gateway"],

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

@@ -7,7 +7,7 @@
   "isPaidAddOn": false,
   "isEnterprise": true,
   "isInternal": false,
-  "isBeta": true,
+  "isBeta": false,
   "isHidden": false,
   "requiresAI": false,
   "products": ["api-gateway"],

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

@@ -1,7 +1,44 @@
-This policy verifies client mTLS results supplied by Zuplo's edge proxy. It
-checks the incoming mTLS verification status and, when enforcement is enabled,
-rejects requests where no client certificate was presented, certificate
-verification failed, or the certificate metadata cannot be parsed.
+The `mtls-auth-inbound` policy is the enforcement step of client mutual TLS
+(mTLS). It reads the verification result that Zuplo's edge proxy attaches to
+each request and, when enforcement is enabled, rejects requests that don't
+present a valid client certificate signed by a CA you trust. It is one part of a
+complete client mTLS setup: you first upload the signing CA to your account,
+then add this policy to the routes you want to protect.
+
+For the full walkthrough — CA upload, configuration, testing with `curl`,
+rotation, and troubleshooting (including the common
+`FAILED to get issuer certificate` error) — see the
+[Client mTLS authentication guide](https://zuplo.com/docs/articles/securing-the-gateway-with-client-mtls).
+
+## Setting up client mTLS
+
+This policy only enforces a result; it does not, on its own, make Zuplo verify
+client certificates. The end-to-end setup is:
+
+1. **Upload your CA certificate** to your account with the
+   [Zuplo CLI](https://zuplo.com/docs/cli/ca-certificate-create):
+   `zuplo ca-certificate create --name my_ca --cert ./ca.pem --account your-account`.
+   Upload the self-signed **root** CA that anchors the chain, not an
+   intermediate. CA certificates are scoped to your **account**, so once
+   uploaded, every gateway domain on the account verifies presented client
+   certificates against it.
+2. **Add this policy** (`mtls-auth-inbound`) to each route that should require a
+   verified client certificate, and set `certIssuerDN` to pin the issuer (see
+   the options described below).
+3. **Read the certificate** in your request handler or downstream policies from
+   `request.user.data.mtlsAuth`.
+4. **Test** with a client certificate issued by (or chained to) your CA:
+   `curl --cert ./client.pem --key ./client.key https://your-gateway.zuplo.app/v1/example`.
+
+See the
+[full guide](https://zuplo.com/docs/articles/securing-the-gateway-with-client-mtls)
+for CA management, custom domains, rotation, and troubleshooting.
+
+## How the policy behaves
+
+When enforcement is enabled, the policy rejects requests where no client
+certificate was presented, certificate verification failed, or the certificate
+metadata cannot be parsed.
 
 When verification passes, the policy parses the client certificate metadata and
 sets it on `request.user.data.mtlsAuth`. The metadata includes `subject`,
@@ -30,5 +67,15 @@ inspect `request.user.data.mtlsAuth.issuer` from a request signed by the desired
 CA.
 
 Note: this policy does not work with local development since it relies on
-metadata from the upstream reverse proxy, it is recommended to test this using a
+metadata from the upstream reverse proxy. It is recommended to test this using a
 working-copy or preview environment.
+
+## Learn more
+
+- [Client mTLS authentication guide](https://zuplo.com/docs/articles/securing-the-gateway-with-client-mtls)
+  — full end-to-end setup, CA management, and troubleshooting
+- [`ca-certificate` CLI reference](https://zuplo.com/docs/cli/ca-certificate-create)
+  — upload, list, describe, rename, and delete account CA certificates
+- [Gateway to Origin mTLS](https://zuplo.com/docs/articles/securing-backend-mtls)
+  — the reverse direction, where Zuplo authenticates to your backend with a
+  client certificate

package/docs/policies/okta-fga-authz-inbound/schema.json

@@ -7,7 +7,7 @@
   "isPaidAddOn": false,
   "isEnterprise": true,
   "isInternal": false,
-  "isBeta": true,
+  "isBeta": false,
   "isHidden": false,
   "requiresAI": false,
   "products": ["api-gateway"],

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

@@ -7,7 +7,7 @@
   "isPaidAddOn": false,
   "isEnterprise": true,
   "isInternal": false,
-  "isBeta": true,
+  "isBeta": false,
   "isHidden": false,
   "requiresAI": false,
   "products": ["api-gateway"],