Skip to content
rachel/workerd
File

Blob: types/defines/cf.d.ts

typescript1075 lines
1interface BasicImageTransformations {
2  /**
3   * Maximum width in image pixels. The value must be an integer.
4   */
5  width?: number;
6  /**
7   * Maximum height in image pixels. The value must be an integer.
8   */
9  height?: number;
10  /**
11   * Resizing mode as a string. It affects interpretation of width and height
12   * options:
13   *  - scale-down: Similar to contain, but the image is never enlarged. If
14   *    the image is larger than given width or height, it will be resized.
15   *    Otherwise its original size will be kept.
16   *  - contain: Resizes to maximum size that fits within the given width and
17   *    height. If only a single dimension is given (e.g. only width), the
18   *    image will be shrunk or enlarged to exactly match that dimension.
19   *    Aspect ratio is always preserved.
20   *  - cover: Resizes (shrinks or enlarges) to fill the entire area of width
21   *    and height. If the image has an aspect ratio different from the ratio
22   *    of width and height, it will be cropped to fit.
23   *  - crop: The image will be shrunk and cropped to fit within the area
24   *    specified by width and height. The image will not be enlarged. For images
25   *    smaller than the given dimensions it's the same as scale-down. For
26   *    images larger than the given dimensions, it's the same as cover.
27   *    See also trim.
28   *  - pad: Resizes to the maximum size that fits within the given width and
29   *    height, and then fills the remaining area with a background color
30   *    (white by default). Use of this mode is not recommended, as the same
31   *    effect can be more efficiently achieved with the contain mode and the
32   *    CSS object-fit: contain property.
33   *  - squeeze: Stretches and deforms to the width and height given, even if it
34   *    breaks aspect ratio
35   */
36  fit?: "scale-down" | "contain" | "cover" | "crop" | "pad" | "squeeze";
37  /**
38   * Image segmentation using artificial intelligence models. Sets pixels not
39   * within selected segment area to transparent e.g "foreground" sets every
40   * background pixel as transparent.
41   */
42  segment?: "foreground";
43  /**
44   * When cropping with fit: "cover", this defines the side or point that should
45   * be left uncropped. The value is either a string
46   * "left", "right", "top", "bottom", "auto", or "center" (the default),
47   * or an object {x, y} containing focal point coordinates in the original
48   * image expressed as fractions ranging from 0.0 (top or left) to 1.0
49   * (bottom or right), 0.5 being the center. {fit: "cover", gravity: "top"} will
50   * crop bottom or left and right sides as necessary, but won’t crop anything
51   * from the top. {fit: "cover", gravity: {x:0.5, y:0.2}} will crop each side to
52   * preserve as much as possible around a point at 20% of the height of the
53   * source image.
54   */
55  gravity?:
56    | 'face'
57    | 'left'
58    | 'right'
59    | 'top'
60    | 'bottom'
61    | 'center'
62    | 'auto'
63    | 'entropy'
64    | BasicImageTransformationsGravityCoordinates;
65  /**
66   * Background color to add underneath the image. Applies only to images with
67   * transparency (such as PNG). Accepts any CSS color (#RRGGBB, rgba(…),
68   * hsl(…), etc.)
69   */
70  background?: string;
71  /**
72   * Number of degrees (90, 180, 270) to rotate the image by. width and height
73   * options refer to axes after rotation.
74   */
75  rotate?: 0 | 90 | 180 | 270 | 360;
76}
77 
78interface BasicImageTransformationsGravityCoordinates {
79  x?: number;
80  y?: number;
81  mode?: 'remainder' | 'box-center';
82}
83 
84/**
85 * In addition to the properties you can set in the RequestInit dict
86 * that you pass as an argument to the Request constructor, you can
87 * set certain properties of a `cf` object to control how Cloudflare
88 * features are applied to that new Request.
89 *
90 * Note: Currently, these properties cannot be tested in the
91 * playground.
92 */
93interface RequestInitCfProperties extends Record<string, unknown> {
94  cacheEverything?: boolean;
95  /**
96   * A request's cache key is what determines if two requests are
97   * "the same" for caching purposes. If a request has the same cache key
98   * as some previous request, then we can serve the same cached response for
99   * both. (e.g. 'some-key')
100   *
101   * Only available for Enterprise customers.
102   */
103  cacheKey?: string;
104  /**
105   * This allows you to append additional Cache-Tag response headers
106   * to the origin response without modifications to the origin server.
107   * This will allow for greater control over the Purge by Cache Tag feature
108   * utilizing changes only in the Workers process.
109   *
110   * Only available for Enterprise customers.
111   */
112  cacheTags?: string[];
113  /**
114   * Force response to be cached for a given number of seconds. (e.g. 300)
115   */
116  cacheTtl?: number;
117  /**
118   * Force response to be cached for a given number of seconds based on the Origin status code.
119   * (e.g. { '200-299': 86400, '404': 1, '500-599': 0 })
120   */
121  cacheTtlByStatus?: Record<string, number>;
122  /**
123   * Explicit Cache-Control header value to set on the response stored in cache.
124   * This gives full control over cache directives (e.g. 'public, max-age=3600, s-maxage=86400').
125   *
126   * Cannot be used together with `cacheTtl` or the `cache` request option (`no-store`/`no-cache`),
127   * as these are mutually exclusive cache control mechanisms. Setting both will throw a TypeError.
128   *
129   * Can be used together with `cacheTtlByStatus`.
130   */
131  cacheControl?: string;
132  /**
133   * Whether the response should be eligible for Cache Reserve storage.
134   */
135  cacheReserveEligible?: boolean;
136  /**
137   * Whether to respect strong ETags (as opposed to weak ETags) from the origin.
138   */
139  respectStrongEtag?: boolean;
140  /**
141   * Whether to strip ETag headers from the origin response before caching.
142   */
143  stripEtags?: boolean;
144  /**
145   * Whether to strip Last-Modified headers from the origin response before caching.
146   */
147  stripLastModified?: boolean;
148  /**
149   * Whether to enable Cache Deception Armor, which protects against web cache
150   * deception attacks by verifying the Content-Type matches the URL extension.
151   */
152  cacheDeceptionArmor?: boolean;
153  /**
154   * Minimum file size in bytes for a response to be eligible for Cache Reserve storage.
155   */
156  cacheReserveMinimumFileSize?: number;
157  scrapeShield?: boolean;
158  apps?: boolean;
159  image?: RequestInitCfPropertiesImage;
160  minify?: RequestInitCfPropertiesImageMinify;
161  mirage?: boolean;
162  polish?: "lossy" | "lossless" | "off";
163  r2?: RequestInitCfPropertiesR2;
164  /**
165   * Redirects the request to an alternate origin server. You can use this,
166   * for example, to implement load balancing across several origins.
167   * (e.g.us-east.example.com)
168   *
169   * Note - For security reasons, the hostname set in resolveOverride must
170   * be proxied on the same Cloudflare zone of the incoming request.
171   * Otherwise, the setting is ignored. CNAME hosts are allowed, so to
172   * resolve to a host under a different domain or a DNS only domain first
173   * declare a CNAME record within your own zone’s DNS mapping to the
174   * external hostname, set proxy on Cloudflare, then set resolveOverride
175   * to point to that CNAME record.
176   */
177  resolveOverride?: string;
178}
179 
180interface RequestInitCfPropertiesImageDraw extends BasicImageTransformations {
181  /**
182   * Absolute URL of the image file to use for the drawing. It can be any of
183   * the supported file formats. For drawing of watermarks or non-rectangular
184   * overlays we recommend using PNG or WebP images.
185   */
186  url: string;
187  /**
188   * Floating-point number between 0 (transparent) and 1 (opaque).
189   * For example, opacity: 0.5 makes overlay semitransparent.
190   */
191  opacity?: number;
192  /**
193   * - If set to true, the overlay image will be tiled to cover the entire
194   *   area. This is useful for stock-photo-like watermarks.
195   * - If set to "x", the overlay image will be tiled horizontally only
196   *   (form a line).
197   * - If set to "y", the overlay image will be tiled vertically only
198   *   (form a line).
199   */
200  repeat?: true | "x" | "y";
201  /**
202   * Position of the overlay image relative to a given edge. Each property is
203   * an offset in pixels. 0 aligns exactly to the edge. For example, left: 10
204   * positions left side of the overlay 10 pixels from the left edge of the
205   * image it's drawn over. bottom: 0 aligns bottom of the overlay with bottom
206   * of the background image.
207   *
208   * Setting both left & right, or both top & bottom is an error.
209   *
210   * If no position is specified, the image will be centered.
211   */
212  top?: number;
213  left?: number;
214  bottom?: number;
215  right?: number;
216}
217 
218interface RequestInitCfPropertiesImage extends BasicImageTransformations {
219  /**
220   * Device Pixel Ratio. Default 1. Multiplier for width/height that makes it
221   * easier to specify higher-DPI sizes in <img srcset>.
222   */
223  dpr?: number;
224  /**
225   * Allows you to trim your image. Takes dpr into account and is performed before
226   * resizing or rotation.
227   *
228   * It can be used as:
229   * - left, top, right, bottom - it will specify the number of pixels to cut
230   *   off each side
231   * - width, height - the width/height you'd like to end up with - can be used
232   *   in combination with the properties above
233   * - border - this will automatically trim the surroundings of an image based on
234   *   it's color. It consists of three properties:
235   *    - color: rgb or hex representation of the color you wish to trim (todo: verify the rgba bit)
236   *    - tolerance: difference from color to treat as color
237   *    - keep: the number of pixels of border to keep
238   */
239  trim?: "border" | {
240    top?: number;
241    bottom?: number;
242    left?: number;
243    right?: number;
244    width?: number;
245    height?: number;
246    border?:
247      | boolean
248      | {
249          color?: string;
250          tolerance?: number;
251          keep?: number;
252        };
253  };
254  /**
255   * Quality setting from 1-100 (useful values are in 60-90 range). Lower values
256   * make images look worse, but load faster. The default is 85. It applies only
257   * to JPEG and WebP images. It doesn’t have any effect on PNG.
258   */
259  quality?: number | "low" | "medium-low" | "medium-high" | "high";
260  /**
261   * Output format to generate. It can be:
262   *  - avif: generate images in AVIF format.
263   *  - webp: generate images in Google WebP format. Set quality to 100 to get
264   *    the WebP-lossless format.
265   *  - json: instead of generating an image, outputs information about the
266   *    image, in JSON format. The JSON object will contain image size
267   *    (before and after resizing), source image’s MIME type, file size, etc.
268   * - jpeg: generate images in JPEG format.
269   * - png: generate images in PNG format.
270   */
271  format?: "avif" | "webp" | "json" | "jpeg" | "png" | "baseline-jpeg" | "png-force" | "svg";
272  /**
273   * Whether to preserve animation frames from input files. Default is true.
274   * Setting it to false reduces animations to still images. This setting is
275   * recommended when enlarging images or processing arbitrary user content,
276   * because large GIF animations can weigh tens or even hundreds of megabytes.
277   * It is also useful to set anim:false when using format:"json" to get the
278   * response quicker without the number of frames.
279   */
280  anim?: boolean;
281  /**
282   * What EXIF data should be preserved in the output image. Note that EXIF
283   * rotation and embedded color profiles are always applied ("baked in" into
284   * the image), and aren't affected by this option. Note that if the Polish
285   * feature is enabled, all metadata may have been removed already and this
286   * option may have no effect.
287   *  - keep: Preserve most of EXIF metadata, including GPS location if there's
288   *    any.
289   *  - copyright: Only keep the copyright tag, and discard everything else.
290   *    This is the default behavior for JPEG files.
291   *  - none: Discard all invisible EXIF metadata. Currently WebP and PNG
292   *    output formats always discard metadata.
293   */
294  metadata?: "keep" | "copyright" | "none";
295  /**
296   * Strength of sharpening filter to apply to the image. Floating-point
297   * number between 0 (no sharpening, default) and 10 (maximum). 1.0 is a
298   * recommended value for downscaled images.
299   */
300  sharpen?: number;
301  /**
302   * Radius of a blur filter (approximate gaussian). Maximum supported radius
303   * is 250.
304   */
305  blur?: number;
306  /**
307   * Overlays are drawn in the order they appear in the array (last array
308   * entry is the topmost layer).
309   */
310  draw?: RequestInitCfPropertiesImageDraw[];
311  /**
312   * Fetching image from authenticated origin. Setting this property will
313   * pass authentication headers (Authorization, Cookie, etc.) through to
314   * the origin.
315   */
316  "origin-auth"?: "share-publicly";
317  /**
318   * Adds a border around the image. The border is added after resizing. Border
319   * width takes dpr into account, and can be specified either using a single
320   * width property, or individually for each side.
321   */
322  border?:
323    | {
324        color: string;
325        width: number;
326      }
327    | {
328        color: string;
329        top: number;
330        right: number;
331        bottom: number;
332        left: number;
333      };
334  /**
335   * Increase brightness by a factor. A value of 1.0 equals no change, a value
336   * of 0.5 equals half brightness, and a value of 2.0 equals twice as bright.
337   * 0 is ignored.
338   */
339  brightness?: number;
340  /**
341   * Increase contrast by a factor. A value of 1.0 equals no change, a value of
342   * 0.5 equals low contrast, and a value of 2.0 equals high contrast. 0 is
343   * ignored.
344   */
345  contrast?: number;
346  /**
347   * Increase exposure by a factor. A value of 1.0 equals no change, a value of
348   * 0.5 darkens the image, and a value of 2.0 lightens the image. 0 is ignored.
349   */
350  gamma?: number;
351 
352  /**
353   * Increase contrast by a factor. A value of 1.0 equals no change, a value of
354   * 0.5 equals low contrast, and a value of 2.0 equals high contrast. 0 is
355   * ignored.
356   */
357  saturation?: number;
358 
359  /**
360   * Flips the images horizontally, vertically, or both. Flipping is applied before
361   * rotation, so if you apply flip=h,rotate=90 then the image will be flipped
362   * horizontally, then rotated by 90 degrees.
363   */
364  flip?: 'h' | 'v' | 'hv',
365 
366  /**
367   * Slightly reduces latency on a cache miss by selecting a
368   * quickest-to-compress file format, at a cost of increased file size and
369   * lower image quality. It will usually override the format option and choose
370   * JPEG over WebP or AVIF. We do not recommend using this option, except in
371   * unusual circumstances like resizing uncacheable dynamically-generated
372   * images.
373   */
374  compression?: "fast";
375}
376 
377interface RequestInitCfPropertiesImageMinify {
378  javascript?: boolean;
379  css?: boolean;
380  html?: boolean;
381}
382 
383interface RequestInitCfPropertiesR2 {
384  /**
385   * Colo id of bucket that an object is stored in
386   */
387  bucketColoId?: number;
388}
389 
390/**
391 * Request metadata provided by Cloudflare's edge.
392 */
393type IncomingRequestCfProperties<HostMetadata = unknown> =
394  IncomingRequestCfPropertiesBase &
395    IncomingRequestCfPropertiesBotManagementEnterprise &
396    IncomingRequestCfPropertiesCloudflareForSaaSEnterprise<HostMetadata> &
397    IncomingRequestCfPropertiesGeographicInformation &
398    IncomingRequestCfPropertiesCloudflareAccessOrApiShield;
399 
400interface IncomingRequestCfPropertiesBase extends Record<string, unknown> {
401  /**
402   * [ASN](https://www.iana.org/assignments/as-numbers/as-numbers.xhtml) of the incoming request.
403   *
404   * @example 395747
405   */
406  asn?: number;
407  /**
408   * The organization which owns the ASN of the incoming request.
409   *
410   * @example "Google Cloud"
411   */
412  asOrganization?: string;
413  /**
414   * The original value of the `Accept-Encoding` header if Cloudflare modified it.
415   *
416   * @example "gzip, deflate, br"
417   */
418  clientAcceptEncoding?: string;
419  /**
420   * The number of milliseconds it took for the request to reach your worker.
421   *
422   * @example 22
423   */
424  clientTcpRtt?: number;
425  /**
426   * The three-letter [IATA](https://en.wikipedia.org/wiki/IATA_airport_code)
427   * airport code of the data center that the request hit.
428   *
429   * @example "DFW"
430   */
431  colo: string;
432  /**
433   * Represents the upstream's response to a
434   * [TCP `keepalive` message](https://tldp.org/HOWTO/TCP-Keepalive-HOWTO/overview.html)
435   * from cloudflare.
436   *
437   * For workers with no upstream, this will always be `1`.
438   *
439   * @example 3
440   */
441  edgeRequestKeepAliveStatus: IncomingRequestCfPropertiesEdgeRequestKeepAliveStatus;
442  /**
443   * The HTTP Protocol the request used.
444   *
445   * @example "HTTP/2"
446   */
447  httpProtocol: string;
448  /**
449   * The browser-requested prioritization information in the request object.
450   *
451   * If no information was set, defaults to the empty string `""`
452   *
453   * @example "weight=192;exclusive=0;group=3;group-weight=127"
454   * @default ""
455   */
456  requestPriority: string;
457  /**
458   * The TLS version of the connection to Cloudflare.
459   * In requests served over plaintext (without TLS), this property is the empty string `""`.
460   *
461   * @example "TLSv1.3"
462   */
463  tlsVersion: string;
464  /**
465   * The cipher for the connection to Cloudflare.
466   * In requests served over plaintext (without TLS), this property is the empty string `""`.
467   *
468   * @example "AEAD-AES128-GCM-SHA256"
469   */
470  tlsCipher: string;
471  /**
472   * Metadata containing the [`HELLO`](https://www.rfc-editor.org/rfc/rfc5246#section-7.4.1.2) and [`FINISHED`](https://www.rfc-editor.org/rfc/rfc5246#section-7.4.9) messages from this request's TLS handshake.
473   *
474   * If the incoming request was served over plaintext (without TLS) this field is undefined.
475   */
476  tlsExportedAuthenticator?: IncomingRequestCfPropertiesExportedAuthenticatorMetadata;
477}
478 
479interface IncomingRequestCfPropertiesBotManagementBase {
480  /**
481   * Cloudflare’s [level of certainty](https://developers.cloudflare.com/bots/concepts/bot-score/) that a request comes from a bot,
482   * represented as an integer percentage between `1` (almost certainly a bot) and `99` (almost certainly human).
483   *
484   * @example 54
485   */
486  score: number;
487  /**
488   * A boolean value that is true if the request comes from a good bot, like Google or Bing.
489   * Most customers choose to allow this traffic. For more details, see [Traffic from known bots](https://developers.cloudflare.com/firewall/known-issues-and-faq/#how-does-firewall-rules-handle-traffic-from-known-bots).
490   */
491  verifiedBot: boolean;
492  /**
493   * A boolean value that is true if the request originates from a
494   * Cloudflare-verified proxy service.
495   */
496  corporateProxy: boolean;
497  /**
498   * A boolean value that's true if the request matches [file extensions](https://developers.cloudflare.com/bots/reference/static-resources/) for many types of static resources.
499   */
500  staticResource: boolean;
501  /**
502   * List of IDs that correlate to the Bot Management heuristic detections made on a request (you can have multiple heuristic detections on the same request).
503   */
504  detectionIds: number[];
505}
506 
507interface IncomingRequestCfPropertiesBotManagement {
508  /**
509   * Results of Cloudflare's Bot Management analysis
510   */
511  botManagement: IncomingRequestCfPropertiesBotManagementBase;
512  /**
513   * Duplicate of `botManagement.score`.
514   *
515   * @deprecated
516   */
517  clientTrustScore: number;
518}
519 
520interface IncomingRequestCfPropertiesBotManagementEnterprise
521  extends IncomingRequestCfPropertiesBotManagement {
522  /**
523   * Results of Cloudflare's Bot Management analysis
524   */
525  botManagement: IncomingRequestCfPropertiesBotManagementBase & {
526    /**
527     * A [JA3 Fingerprint](https://developers.cloudflare.com/bots/concepts/ja3-fingerprint/) to help profile specific SSL/TLS clients
528     * across different destination IPs, Ports, and X509 certificates.
529     */
530    ja3Hash: string;
531  };
532}
533 
534interface IncomingRequestCfPropertiesCloudflareForSaaSEnterprise<HostMetadata> {
535  /**
536   * Custom metadata set per-host in [Cloudflare for SaaS](https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/).
537   *
538   * This field is only present if you have Cloudflare for SaaS enabled on your account
539   * and you have followed the [required steps to enable it]((https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/domain-support/custom-metadata/)).
540   */
541  hostMetadata?: HostMetadata;
542}
543 
544interface IncomingRequestCfPropertiesCloudflareAccessOrApiShield {
545  /**
546   * Information about the client certificate presented to Cloudflare.
547   *
548   * This is populated when the incoming request is served over TLS using
549   * either Cloudflare Access or API Shield (mTLS)
550   * and the presented SSL certificate has a valid
551   * [Certificate Serial Number](https://ldapwiki.com/wiki/Certificate%20Serial%20Number)
552   * (i.e., not `null` or `""`).
553   *
554   * Otherwise, a set of placeholder values are used.
555   *
556   * The property `certPresented` will be set to `"1"` when
557   * the object is populated (i.e. the above conditions were met).
558   */
559  tlsClientAuth:
560    | IncomingRequestCfPropertiesTLSClientAuth
561    | IncomingRequestCfPropertiesTLSClientAuthPlaceholder;
562}
563 
564/**
565 * Metadata about the request's TLS handshake
566 */
567interface IncomingRequestCfPropertiesExportedAuthenticatorMetadata {
568  /**
569   * The client's [`HELLO` message](https://www.rfc-editor.org/rfc/rfc5246#section-7.4.1.2), encoded in hexadecimal
570   *
571   * @example "44372ba35fa1270921d318f34c12f155dc87b682cf36a790cfaa3ba8737a1b5d"
572   */
573  clientHandshake: string;
574  /**
575   * The server's [`HELLO` message](https://www.rfc-editor.org/rfc/rfc5246#section-7.4.1.2), encoded in hexadecimal
576   *
577   * @example "44372ba35fa1270921d318f34c12f155dc87b682cf36a790cfaa3ba8737a1b5d"
578   */
579  serverHandshake: string;
580  /**
581   * The client's [`FINISHED` message](https://www.rfc-editor.org/rfc/rfc5246#section-7.4.9), encoded in hexadecimal
582   *
583   * @example "084ee802fe1348f688220e2a6040a05b2199a761f33cf753abb1b006792d3f8b"
584   */
585  clientFinished: string;
586  /**
587   * The server's [`FINISHED` message](https://www.rfc-editor.org/rfc/rfc5246#section-7.4.9), encoded in hexadecimal
588   *
589   * @example "084ee802fe1348f688220e2a6040a05b2199a761f33cf753abb1b006792d3f8b"
590   */
591  serverFinished: string;
592}
593 
594/**
595 * Geographic data about the request's origin.
596 */
597interface IncomingRequestCfPropertiesGeographicInformation {
598  /**
599   * The [ISO 3166-1 Alpha 2](https://www.iso.org/iso-3166-country-codes.html) country code the request originated from.
600   *
601   * If your worker is [configured to accept TOR connections](https://support.cloudflare.com/hc/en-us/articles/203306930-Understanding-Cloudflare-Tor-support-and-Onion-Routing), this may also be `"T1"`, indicating a request that originated over TOR.
602   *
603   * If Cloudflare is unable to determine where the request originated this property is omitted.
604   *
605   * The country code `"T1"` is used for requests originating on TOR.
606   *
607   * @example "GB"
608   */
609  country?: Iso3166Alpha2Code | "T1";
610  /**
611   * If present, this property indicates that the request originated in the EU
612   *
613   * @example "1"
614   */
615  isEUCountry?: "1";
616  /**
617   * A two-letter code indicating the continent the request originated from.
618   *
619   * @example "AN"
620   */
621  continent?: ContinentCode;
622  /**
623   * The city the request originated from
624   *
625   * @example "Austin"
626   */
627  city?: string;
628  /**
629   * Postal code of the incoming request
630   *
631   * @example "78701"
632   */
633  postalCode?: string;
634  /**
635   * Latitude of the incoming request
636   *
637   * @example "30.27130"
638   */
639  latitude?: string;
640  /**
641   * Longitude of the incoming request
642   *
643   * @example "-97.74260"
644   */
645  longitude?: string;
646  /**
647   * Timezone of the incoming request
648   *
649   * @example "America/Chicago"
650   */
651  timezone?: string;
652  /**
653   * If known, the ISO 3166-2 name for the first level region associated with
654   * the IP address of the incoming request
655   *
656   * @example "Texas"
657   */
658  region?: string;
659  /**
660   * If known, the ISO 3166-2 code for the first-level region associated with
661   * the IP address of the incoming request
662   *
663   * @example "TX"
664   */
665  regionCode?: string;
666  /**
667   * Metro code (DMA) of the incoming request
668   *
669   * @example "635"
670   */
671  metroCode?: string;
672}
673 
674/** Data about the incoming request's TLS certificate */
675interface IncomingRequestCfPropertiesTLSClientAuth {
676  /** Always `"1"`, indicating that the certificate was presented */
677  certPresented: "1";
678  /**
679   * Result of certificate verification.
680   *
681   * @example "FAILED:self signed certificate"
682   */
683  certVerified: Exclude<CertVerificationStatus, "NONE">;
684  /** The presented certificate's revokation status.
685   *
686   * - A value of `"1"` indicates the certificate has been revoked
687   * - A value of `"0"` indicates the certificate has not been revoked
688   */
689  certRevoked: "1" | "0";
690  /**
691   * The certificate issuer's [distinguished name](https://knowledge.digicert.com/generalinformation/INFO1745.html)
692   *
693   * @example "CN=cloudflareaccess.com, C=US, ST=Texas, L=Austin, O=Cloudflare"
694   */
695  certIssuerDN: string;
696  /**
697   * The certificate subject's [distinguished name](https://knowledge.digicert.com/generalinformation/INFO1745.html)
698   *
699   * @example "CN=*.cloudflareaccess.com, C=US, ST=Texas, L=Austin, O=Cloudflare"
700   */
701  certSubjectDN: string;
702  /**
703   * The certificate issuer's [distinguished name](https://knowledge.digicert.com/generalinformation/INFO1745.html) ([RFC 2253](https://www.rfc-editor.org/rfc/rfc2253.html) formatted)
704   *
705   * @example "CN=cloudflareaccess.com, C=US, ST=Texas, L=Austin, O=Cloudflare"
706   */
707  certIssuerDNRFC2253: string;
708  /**
709   * The certificate subject's [distinguished name](https://knowledge.digicert.com/generalinformation/INFO1745.html) ([RFC 2253](https://www.rfc-editor.org/rfc/rfc2253.html) formatted)
710   *
711   * @example "CN=*.cloudflareaccess.com, C=US, ST=Texas, L=Austin, O=Cloudflare"
712   */
713  certSubjectDNRFC2253: string;
714  /** The certificate issuer's distinguished name (legacy policies) */
715  certIssuerDNLegacy: string;
716  /** The certificate subject's distinguished name (legacy policies) */
717  certSubjectDNLegacy: string;
718  /**
719   * The certificate's serial number
720   *
721   * @example "00936EACBE07F201DF"
722   */
723  certSerial: string;
724  /**
725   * The certificate issuer's serial number
726   *
727   * @example "2489002934BDFEA34"
728   */
729  certIssuerSerial: string;
730  /**
731   * The certificate's Subject Key Identifier
732   *
733   * @example "BB:AF:7E:02:3D:FA:A6:F1:3C:84:8E:AD:EE:38:98:EC:D9:32:32:D4"
734   */
735  certSKI: string;
736  /**
737   * The certificate issuer's Subject Key Identifier
738   *
739   * @example "BB:AF:7E:02:3D:FA:A6:F1:3C:84:8E:AD:EE:38:98:EC:D9:32:32:D4"
740   */
741  certIssuerSKI: string;
742  /**
743   * The certificate's SHA-1 fingerprint
744   *
745   * @example "6b9109f323999e52259cda7373ff0b4d26bd232e"
746   */
747  certFingerprintSHA1: string;
748  /**
749   * The certificate's SHA-256 fingerprint
750   *
751   * @example "acf77cf37b4156a2708e34c4eb755f9b5dbbe5ebb55adfec8f11493438d19e6ad3f157f81fa3b98278453d5652b0c1fd1d71e5695ae4d709803a4d3f39de9dea"
752   */
753  certFingerprintSHA256: string;
754  /**
755   * The effective starting date of the certificate
756   *
757   * @example "Dec 22 19:39:00 2018 GMT"
758   */
759  certNotBefore: string;
760  /**
761   * The effective expiration date of the certificate
762   *
763   * @example "Dec 22 19:39:00 2018 GMT"
764   */
765  certNotAfter: string;
766}
767 
768/** Placeholder values for TLS Client Authorization */
769interface IncomingRequestCfPropertiesTLSClientAuthPlaceholder {
770  certPresented: "0";
771  certVerified: "NONE";
772  certRevoked: "0";
773  certIssuerDN: "";
774  certSubjectDN: "";
775  certIssuerDNRFC2253: "";
776  certSubjectDNRFC2253: "";
777  certIssuerDNLegacy: "";
778  certSubjectDNLegacy: "";
779  certSerial: "";
780  certIssuerSerial: "";
781  certSKI: "";
782  certIssuerSKI: "";
783  certFingerprintSHA1: "";
784  certFingerprintSHA256: "";
785  certNotBefore: "";
786  certNotAfter: "";
787}
788 
789/** Possible outcomes of TLS verification */
790declare type CertVerificationStatus =
791  /** Authentication succeeded */
792  | "SUCCESS"
793  /** No certificate was presented */
794  | "NONE"
795  /** Failed because the certificate was self-signed */
796  | "FAILED:self signed certificate"
797  /** Failed because the certificate failed a trust chain check */
798  | "FAILED:unable to verify the first certificate"
799  /** Failed because the certificate not yet valid */
800  | "FAILED:certificate is not yet valid"
801  /** Failed because the certificate is expired */
802  | "FAILED:certificate has expired"
803  /** Failed for another unspecified reason */
804  | "FAILED";
805 
806/**
807 * An upstream endpoint's response to a TCP `keepalive` message from Cloudflare.
808 */
809declare type IncomingRequestCfPropertiesEdgeRequestKeepAliveStatus =
810  | 0 /** Unknown */
811  | 1 /** no keepalives (not found) */
812  | 2 /** no connection re-use, opening keepalive connection failed */
813  | 3 /** no connection re-use, keepalive accepted and saved */
814  | 4 /** connection re-use, refused by the origin server (`TCP FIN`) */
815  | 5; /** connection re-use, accepted by the origin server */
816 
817/** ISO 3166-1 Alpha-2 codes */
818declare type Iso3166Alpha2Code =
819  | "AD"
820  | "AE"
821  | "AF"
822  | "AG"
823  | "AI"
824  | "AL"
825  | "AM"
826  | "AO"
827  | "AQ"
828  | "AR"
829  | "AS"
830  | "AT"
831  | "AU"
832  | "AW"
833  | "AX"
834  | "AZ"
835  | "BA"
836  | "BB"
837  | "BD"
838  | "BE"
839  | "BF"
840  | "BG"
841  | "BH"
842  | "BI"
843  | "BJ"
844  | "BL"
845  | "BM"
846  | "BN"
847  | "BO"
848  | "BQ"
849  | "BR"
850  | "BS"
851  | "BT"
852  | "BV"
853  | "BW"
854  | "BY"
855  | "BZ"
856  | "CA"
857  | "CC"
858  | "CD"
859  | "CF"
860  | "CG"
861  | "CH"
862  | "CI"
863  | "CK"
864  | "CL"
865  | "CM"
866  | "CN"
867  | "CO"
868  | "CR"
869  | "CU"
870  | "CV"
871  | "CW"
872  | "CX"
873  | "CY"
874  | "CZ"
875  | "DE"
876  | "DJ"
877  | "DK"
878  | "DM"
879  | "DO"
880  | "DZ"
881  | "EC"
882  | "EE"
883  | "EG"
884  | "EH"
885  | "ER"
886  | "ES"
887  | "ET"
888  | "FI"
889  | "FJ"
890  | "FK"
891  | "FM"
892  | "FO"
893  | "FR"
894  | "GA"
895  | "GB"
896  | "GD"
897  | "GE"
898  | "GF"
899  | "GG"
900  | "GH"
901  | "GI"
902  | "GL"
903  | "GM"
904  | "GN"
905  | "GP"
906  | "GQ"
907  | "GR"
908  | "GS"
909  | "GT"
910  | "GU"
911  | "GW"
912  | "GY"
913  | "HK"
914  | "HM"
915  | "HN"
916  | "HR"
917  | "HT"
918  | "HU"
919  | "ID"
920  | "IE"
921  | "IL"
922  | "IM"
923  | "IN"
924  | "IO"
925  | "IQ"
926  | "IR"
927  | "IS"
928  | "IT"
929  | "JE"
930  | "JM"
931  | "JO"
932  | "JP"
933  | "KE"
934  | "KG"
935  | "KH"
936  | "KI"
937  | "KM"
938  | "KN"
939  | "KP"
940  | "KR"
941  | "KW"
942  | "KY"
943  | "KZ"
944  | "LA"
945  | "LB"
946  | "LC"
947  | "LI"
948  | "LK"
949  | "LR"
950  | "LS"
951  | "LT"
952  | "LU"
953  | "LV"
954  | "LY"
955  | "MA"
956  | "MC"
957  | "MD"
958  | "ME"
959  | "MF"
960  | "MG"
961  | "MH"
962  | "MK"
963  | "ML"
964  | "MM"
965  | "MN"
966  | "MO"
967  | "MP"
968  | "MQ"
969  | "MR"
970  | "MS"
971  | "MT"
972  | "MU"
973  | "MV"
974  | "MW"
975  | "MX"
976  | "MY"
977  | "MZ"
978  | "NA"
979  | "NC"
980  | "NE"
981  | "NF"
982  | "NG"
983  | "NI"
984  | "NL"
985  | "NO"
986  | "NP"
987  | "NR"
988  | "NU"
989  | "NZ"
990  | "OM"
991  | "PA"
992  | "PE"
993  | "PF"
994  | "PG"
995  | "PH"
996  | "PK"
997  | "PL"
998  | "PM"
999  | "PN"
1000  | "PR"
1001  | "PS"
1002  | "PT"
1003  | "PW"
1004  | "PY"
1005  | "QA"
1006  | "RE"
1007  | "RO"
1008  | "RS"
1009  | "RU"
1010  | "RW"
1011  | "SA"
1012  | "SB"
1013  | "SC"
1014  | "SD"
1015  | "SE"
1016  | "SG"
1017  | "SH"
1018  | "SI"
1019  | "SJ"
1020  | "SK"
1021  | "SL"
1022  | "SM"
1023  | "SN"
1024  | "SO"
1025  | "SR"
1026  | "SS"
1027  | "ST"
1028  | "SV"
1029  | "SX"
1030  | "SY"
1031  | "SZ"
1032  | "TC"
1033  | "TD"
1034  | "TF"
1035  | "TG"
1036  | "TH"
1037  | "TJ"
1038  | "TK"
1039  | "TL"
1040  | "TM"
1041  | "TN"
1042  | "TO"
1043  | "TR"
1044  | "TT"
1045  | "TV"
1046  | "TW"
1047  | "TZ"
1048  | "UA"
1049  | "UG"
1050  | "UM"
1051  | "US"
1052  | "UY"
1053  | "UZ"
1054  | "VA"
1055  | "VC"
1056  | "VE"
1057  | "VG"
1058  | "VI"
1059  | "VN"
1060  | "VU"
1061  | "WF"
1062  | "WS"
1063  | "YE"
1064  | "YT"
1065  | "ZA"
1066  | "ZM"
1067  | "ZW";
1068 
1069/** The 2-letter continent codes Cloudflare uses */
1070declare type ContinentCode = "AF" | "AN" | "AS" | "EU" | "NA" | "OC" | "SA";
1071 
1072type CfProperties<HostMetadata = unknown> =
1073  | IncomingRequestCfProperties<HostMetadata>
1074  | RequestInitCfProperties;