Available context

Gateway passes context as the second argument to GatewayMiddleware.handle(request, context, next). Context describes the original request when Gateway selects a Forward policy. Modifying the Request does not update context.

Field names use camelCase. Optional fields are omitted when unavailable, and empty metadata lists are omitted. Availability depends on the connection method, destination, and authenticated session. Check optional values before using them.

Install @cloudflare/zt-types ↗︎ version 2026.10.1 or later in your Worker project:

npm i -D @cloudflare/zt-types

yarn add -D @cloudflare/zt-types

pnpm add -D @cloudflare/zt-types

bun add -d @cloudflare/zt-types

Use import type for Gateway types, as shown in the example and each Worker template. These imports are removed when TypeScript compiles and add no runtime dependency. JavaScript examples omit the type imports and annotations and do not need this package. The package exports the following Gateway types:

context.uri includes the scheme and authority. Normalization removes default ports and fragments, sorts query parameters, and normalizes encoding. It can differ from request.url. Use request.url when operating on the request itself and context.uri when comparing normalized metadata.

Use standard Request APIs to access the method, headers, cookies, and body. Context does not include custom function results, DLP match details, or raw internal device records.

Call await context.identity() only when your script needs identity associated with the Gateway session. Its return type is Promise<GatewayIdentity | null>.

The awaited call behaves as follows:

• Returns an identity object when the user is identified.
• Returns null when there is no identified user.
• Throws an error if Gateway cannot retrieve identity.

Use Gateway-provided identity for user-aware logic. Client-supplied identity headers are not an authoritative substitute.

Check for a missing identity (!identity) to explicitly allow or deny anonymous traffic.

Call await context.devicePosture() to retrieve passed posture check identifiers:

{
	"checks": {
		"passed": ["<POSTURE_CHECK_UUID>"]
	}
}

checks.passed is a read-only list of posture check UUIDs. An empty array means no checks passed. When no device is registered, the getter resolves to { checks: { passed: [] } }. A Worker that requires a specific passed check must deny this request.

If Gateway cannot retrieve device posture, awaiting devicePosture() throws an error. Handle this separately from a session with no passed checks.

The getter does not return raw test results or a list of failed checks.

Gateway still invokes the Worker if it cannot retrieve identity or device posture. If either awaited call throws and your Worker does not catch the error, Gateway returns HTTP 500.

Use try/catch to choose how your Worker handles these errors. The example returns HTTP 503 for retrieval errors and HTTP 403 when identity or a required posture check is missing.

If your application deliberately allows traffic when Gateway cannot retrieve identity or posture, return next(request) from the catch block. This continues the request without requiring the missing result.

Only use this approach before calling next(). Call next() at most once per invocation.

This script requires an identity email and a specific passed posture check before continuing. Anonymous traffic and devices without the required check receive a synthetic 403 response.

Identity or posture retrieval errors receive 503. Replace <POSTURE_CHECK_UUID> with a check in your account.

import { WorkerEntrypoint } from "cloudflare:workers";

export class GatewayMiddleware extends WorkerEntrypoint {
	async handle(request, context, next) {
		try {
			const identity = await context.identity();
			if (!identity?.email) {
				return new Response(null, { status: 403 });
			}
			const passed = (await context.devicePosture())?.checks.passed ?? [];
			if (!passed.includes("<POSTURE_CHECK_UUID>")) {
				return new Response(null, { status: 403 });
			}
		} catch {
			return new Response(null, { status: 503 });
		}
		return next(request);
	}
}

import { WorkerEntrypoint } from "cloudflare:workers";
import type {
	GatewayMiddlewareContext,
	GatewayMiddlewareNext,
} from "@cloudflare/zt-types";

export class GatewayMiddleware extends WorkerEntrypoint {
	async handle(
		request: Request,
		context: GatewayMiddlewareContext,
		next: GatewayMiddlewareNext,
	): Promise<Response> {
		try {
			const identity = await context.identity();
			if (!identity?.email) {
				return new Response(null, { status: 403 });
			}
			const passed = (await context.devicePosture())?.checks.passed ?? [];
			if (!passed.includes("<POSTURE_CHECK_UUID>")) {
				return new Response(null, { status: 403 });
			}
		} catch {
			return new Response(null, { status: 503 });
		}
		return next(request);
	}
}

When the requirement can be expressed using built-in identity selectors or device posture selectors, configure it in your Gateway filtering policy. Use Worker logic for requirements that need custom code.

Gateway combines repeated Cookie headers with semicolons and other repeated headers with commas. Set-Cookie values retain separate entries. Use response.headers.getSetCookie() to read the individual response cookies. When modifying headers, copy them with new Headers(response.headers) to preserve their representation.