zuplo 6.67.32 → 6.68.0

package/docs/programmable-api/web-crypto-apis.mdx

@@ -0,0 +1,219 @@
+---
+title: Web Crypto
+sidebar_label: Web Crypto
+original: https://github.com/cloudflare/cloudflare-docs/blob/production/content/workers/runtime-apis/web-crypto.md
+license: https://github.com/cloudflare/cloudflare-docs/blob/production/LICENSE
+---
+
+<style type="text/css">{`
+/* This is here to make the table not scroll on full screen */
+table th, table td {
+  padding: 6px;
+}
+`}</style>
+
+The Web Crypto API provides a set of low-level functions for common
+cryptographic tasks. The Workers Runtime implements the full surface of this
+API, but with some differences in the
+[supported algorithms](#supported-algorithms) compared to those implemented in
+most browsers.
+
+Performing cryptographic operations using the Web Crypto API is significantly
+faster than performing them purely in JavaScript. If you want to perform
+CPU-intensive cryptographic operations, you should consider using the Web Crypto
+API.
+
+The Web Crypto API is implemented through the `SubtleCrypto` interface,
+accessible via the global `crypto.subtle` binding. A simple example of
+calculating a digest (also known as a hash) is:
+
+```js
+const myText = new TextEncoder().encode("Hello world!");
+
+const myDigest = await crypto.subtle.digest(
+  {
+    name: "SHA-256",
+  },
+  myText, // The data you want to hash as an ArrayBuffer
+);
+
+console.log(new Uint8Array(myDigest));
+```
+
+:::caution
+
+The Web Crypto API differs significantly from Node’s Crypto API. If you want to
+port JavaScript code that relies on Node’s Crypto API, you will need to adapt it
+to use Web Crypto primitives.
+
+:::
+
+## Methods
+
+### `Crypto.getRandomValues()`
+
+The `Crypto.getRandomValues()` method lets you get cryptographically strong
+random values.
+
+[Refer to the MDN documentation for more information](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues)
+
+### `Crypto.randomUUID()`
+
+Generates a v4 UUID using a cryptographically secure random number generator.
+
+[Refer to the MDN documentation for more information](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID)
+
+```ts
+const uuid = crypto.randomUUID();
+```
+
+## HMAC Signatures
+
+The following code blocks show how to sign and verify a string using HMAC.
+
+### Sign a Value
+
+```ts
+/**
+ * Creates a signature for a value and a given secret
+ * @param value - The value to check
+ * @param secret - the secret
+ * @returns The base64 encoded signature
+ **/
+async function sign(value: string, secret: string) {
+  // You will need some super-secret data to use as a symmetric key.
+  const encoder = new TextEncoder();
+  const secretKeyData = encoder.encode(secret);
+  const key = await crypto.subtle.importKey(
+    "raw",
+    secretKeyData,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+
+  const mac = await crypto.subtle.sign("HMAC", key, encoder.encode(value));
+
+  // `mac` is an ArrayBuffer, so you need to make a few changes to get
+  // it into a ByteString, and then a Base64-encoded string.
+  let base64Mac = btoa(String.fromCharCode(...new Uint8Array(mac)));
+
+  // must convert "+" to "-" as urls encode "+" as " "
+  base64Mac = base64Mac.replaceAll("+", "-");
+
+  return base64Mac;
+}
+```
+
+### Verify a Value
+
+```ts
+/**
+ * Verifies a value against a signature and secret
+ * @param signature - The base64 encoded signature
+ * @param value - The value to check
+ * @param secret - the secret
+ * @returns true if the signature is value against the given value and secret
+ **/
+async function verify(signature: string, value: string, secret: string) {
+  // You will need some super-secret data to use as a symmetric key.
+  const encoder = new TextEncoder();
+  const secretKeyData = encoder.encode(secret);
+
+  // Convert a ByteString (a string whose code units are all in the range
+  // [0, 255]), to a Uint8Array. If you pass in a string with code units larger
+  // than 255, their values will overflow.
+  function byteStringToUint8Array(byteString) {
+    const ui = new Uint8Array(byteString.length);
+    for (let i = 0; i < byteString.length; ++i) {
+      ui[i] = byteString.charCodeAt(i);
+    }
+    return ui;
+  }
+
+  const key = await crypto.subtle.importKey(
+    "raw",
+    secretKeyData,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["verify"],
+  );
+
+  // The received MAC is Base64-encoded, so you have to go to some trouble to
+  // get it into a buffer type that crypto.subtle.verify() can read.
+  const receivedMac = byteStringToUint8Array(atob(signature));
+
+  // Use crypto.subtle.verify() to guard against timing attacks. Since HMACs use
+  // symmetric keys, you could implement this by calling crypto.subtle.sign() and
+  // then doing a string comparison -- this is insecure, as string comparisons
+  // bail out on the first mismatch, which leaks information to potential
+  // attackers.
+  const verified = await crypto.subtle.verify(
+    "HMAC",
+    key,
+    receivedMac,
+    encoder.encode(value),
+  );
+
+  return verified;
+}
+```
+
+## Supported algorithms
+
+The runtime implements all operations of the
+[WebCrypto standard](https://www.w3.org/TR/WebCryptoAPI/), as shown in the
+following table.
+
+A checkmark (✓) indicates that this feature is believed to be fully supported
+according to the spec.
+
+An x (✘) indicates that this feature is part of the specification but not
+implemented.
+
+If a feature only implements the operation partially, details are listed.
+
+| Algorithm         | sign()<br/>verify() | encrypt()<br/>decrypt() | digest() | deriveBits()<br/>deriveKey() | generateKey() | wrapKey()<br/>unwrapKey() | exportKey() | importKey() |
+| :---------------- | :------------------ | :---------------------- | :------- | :--------------------------- | :------------ | :------------------------ | :---------- | :---------- |
+| RSASSA PKCS1 v1.5 | ✓                   |                         |          |                              | ✓             |                           | ✓           | ✓           |
+| RSA PSS           | ✓                   |                         |          |                              | ✓             |                           | ✓           | ✓           |
+| RSA OAEP          |                     | ✓                       |          |                              | ✓             | ✓                         | ✓           | ✓           |
+| ECDSA             | ✓                   |                         |          |                              | ✓             |                           | ✓           | ✓           |
+| ECDH              |                     |                         |          | ✓                            | ✓             |                           | ✓           | ✓           |
+| Ed25519[^1]       | ✓                   |                         |          |                              | ✓             |                           | ✓           | ✓           |
+| X25519[^1]        |                     |                         |          | ✓                            | ✓             |                           | ✓           | ✓           |
+| NODE ED25519[^2]  | ✓                   |                         |          |                              | ✓             |                           | ✓           | ✓           |
+| AES CTR           |                     | ✓                       |          |                              | ✓             | ✓                         | ✓           | ✓           |
+| AES CBC           |                     | ✓                       |          |                              | ✓             | ✓                         | ✓           | ✓           |
+| AES GCM           |                     | ✓                       |          |                              | ✓             | ✓                         | ✓           | ✓           |
+| AES KW            |                     |                         |          |                              | ✓             | ✓                         | ✓           | ✓           |
+| HMAC              | ✓                   |                         |          |                              | ✓             |                           | ✓           | ✓           |
+| SHA 1             |                     |                         | ✓        |                              |               |                           |             |             |
+| SHA 256           |                     |                         | ✓        |                              |               |                           |             |             |
+| SHA 384           |                     |                         | ✓        |                              |               |                           |             |             |
+| SHA 512           |                     |                         | ✓        |                              |               |                           |             |             |
+| MD5[^3]           |                     |                         | ✓        |                              |               |                           |             |             |
+| HKDF              |                     |                         |          | ✓                            |               |                           |             | ✓           |
+| PBKDF2            |                     |                         |          | ✓                            |               |                           |             | ✓           |
+
+[^1]:
+    Algorithms as specified in the
+    [Secure Curves API](https://wicg.github.io/webcrypto-secure-curves).
+
+[^2]:
+    Legacy non-standard EdDSA is supported for the Ed25519 curve in addition to
+    the Secure Curves version. Since this algorithm is non-standard, note the
+    following while using it:
+
+    - Use `NODE-ED25519` as the algorithm and `namedCurve` parameters.
+    - Unlike NodeJS, Cloudflare won't support raw import of private keys.
+    - The algorithm implementation may change over time. While Cloudflare can't
+      guarantee it at this time, Cloudflare will strive to maintain backward
+      compatibility and compatibility with NodeJS's behavior. Any notable
+      compatibility notes will be communicated in release notes and via this
+      developer documentation.
+
+[^3]:
+    MD5 isn't part of the WebCrypto standard but is supported in Cloudflare
+    Workers for interacting with legacy systems that require MD5. MD5 is
+    considered a weak algorithm. Don't rely upon MD5 for security.

package/docs/programmable-api/web-standard-apis.mdx

@@ -0,0 +1,109 @@
+---
+title: Web Standard APIs
+sidebar_label: Web Standard APIs
+---
+
+Zuplo's runtime supports the standards
+[Web Workers API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API).
+This means that you can rely on the same set of JavaScript APIs you would find
+in a browser environment.
+
+## Built-In Objects
+
+All of the
+[standard built-in objects](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference)
+supported by the current Google Chrome stable release are supported, with a few
+notable exceptions:
+
+- `eval()` isn't allowed for security reasons.
+- `new Function` isn't allowed for security reasons.
+- `Date.now()` returns the time of the last I/O; it doesn't advance during code
+  execution.
+
+## ​​Compression Streams
+
+The CompressionStream and DecompressionStream classes support gzip and deflate
+compression methods.
+
+[Refer to the MDN documentation for more information](https://developer.mozilla.org/en-US/docs/Web/API/Compression_Streams_API)
+
+## Cryptography
+
+The
+[Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API)
+enables the use cryptographic primitives in order to build systems using
+cryptography.
+
+For more details see the [Web Crypto documentation](./web-crypto-apis.mdx)
+
+## Encoding API
+
+Both `TextEncoder` and `TextDecoder` support UTF-8 encoding/decoding.
+
+[Refer to the MDN documentation for more information.](https://developer.mozilla.org/en-US/docs/Web/API/Encoding_API)
+
+## Encoding: Base64
+
+- [`atob()`](https://developer.mozilla.org/en-US/docs/web/api/atob): Decodes a
+  string of data which has been encoded using base-64 encoding.
+- [`btoa()`](https://developer.mozilla.org/en-US/docs/web/api/btoa): Creates a
+  base-64 encoded ASCII string from a string of binary data.
+
+## Fetch
+
+The [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)
+provides an interface for fetching resources (including across the network).
+
+[Refer to the MDN documentation for more information](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)
+
+```ts
+const response = await fetch("https://echo.zuplo.io");
+const body = await response.json();
+```
+
+The Fetch API includes standard objects like
+[`Headers`](https://developer.mozilla.org/en-US/docs/Web/API/Headers),
+[`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request), and
+[`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response).
+
+See Also: [`ZuploRequest`](./zuplo-request.mdx)
+
+## Streams API
+
+The Streams API allows JavaScript to programmatically access streams of data
+received over the network and process them as desired by the developer.
+
+- [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream)
+- [`ReadableStream BYOBReader`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamBYOBReader)
+- [`ReadableStream DefaultReader`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamDefaultReader)
+- [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream)
+- [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream)
+- [`WritableStream DefaultWriter`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStreamDefaultWriter)
+
+## ​​Timers
+
+- [`setInterval()`](https://developer.mozilla.org/en-US/docs/web/api/setinterval):
+  Schedules a function to execute every time a given number of milliseconds
+  elapses.
+- [`clearInterval()`](https://developer.mozilla.org/en-US/docs/web/api/clearinterval):
+  Cancels the repeated execution set using setInterval().
+- [`setTimeout()`](https://developer.mozilla.org/en-US/docs/web/api/settimeout):
+  Schedules a function to execute in a given amount of time.
+- [`clearTimeout()`](https://developer.mozilla.org/en-US/docs/web/api/cleartimeout):
+  Cancels the delayed execution set using setTimeout().
+
+## URL
+
+The [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) interface is
+used to parse, construct, normalize, and encode URLs. It works by providing
+properties which allow you to easily read and modify the components of a URL.
+
+[Refer to the MDN documentation for more information](https://developer.mozilla.org/en-US/docs/Web/API/URL)
+
+## URLPattern API
+
+The
+[URLPattern API](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern)
+provides a mechanism for matching URLs based on a convenient pattern syntax.
+
+[Refer to the MDN documentation for more information.](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern)

package/docs/programmable-api/zone-cache.mdx

@@ -0,0 +1,131 @@
+---
+title: ZoneCache
+sidebar_label: ZoneCache
+---
+
+The ZoneCache stores data in a shared cache. This cache is in the same zone (the
+same data center or cluster) as your API - it's not globally distributed, but
+rather designed to be low-latency. Common uses include caching configuration,
+session, or other data that needs to be frequently accessed with low latency.
+
+The ZoneCache can store any JSON serializable data. Each cached item has a
+time-to-live (TTL) after which it expires and is removed from the cache. Each
+cached object can be up to 512 MB in size.
+
+There's an demonstration of ZoneCache use in the
+[Per User Rate Limits Using a Database](../articles/per-user-rate-limits-using-db.mdx)
+example.
+
+## Constructor
+
+```ts
+new ZoneCache<T = unknown>(name: string, context: ZuploContext)
+```
+
+Creates a new cache instance for the specified zone.
+
+- `name` - A unique identifier for the cache
+- `context` - The [ZuploContext](./zuplo-context.mdx) object
+- `T` - The type of data stored in the cache (defaults to `unknown`)
+
+## Methods
+
+**`get`**
+
+Retrieves a value from the cache. Returns `undefined` if the key doesn't exist
+or has expired.
+
+```ts
+get(key: string): Promise<T | undefined>
+```
+
+**`put`**
+
+Stores a value in the cache with a time-to-live (TTL) in seconds. The data will
+be JSON serialized.
+
+```ts
+put(key: string, data: T, ttlSeconds: number): Promise<void>
+```
+
+:::note
+
+Objects that don't serialize cleanly to JSON (like the `Headers` object) won't
+be readable after storage.
+
+:::
+
+**`delete`**
+
+Removes a value from the cache.
+
+```ts
+delete(key: string): Promise<void>
+```
+
+## Example
+
+```ts
+import { ZoneCache, ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+interface UserData {
+  id: string;
+  name: string;
+  email: string;
+}
+
+export default async function handler(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  const cache = new ZoneCache<UserData>("user-cache", context);
+
+  // Try to get user from cache
+  const userId = request.params.userId;
+  let userData = await cache.get(userId);
+
+  if (!userData) {
+    // Not in cache, fetch from API
+    const response = await fetch(`https://api.example.com/users/${userId}`);
+    userData = await response.json();
+
+    // Cache for 5 minutes
+    await cache.put(userId, userData, 300);
+  }
+
+  return new Response(JSON.stringify(userData));
+}
+```
+
+## Performance tips
+
+When writing to the cache, you may not want to `await` the operation to
+complete. This can improve response times:
+
+```ts
+// Fire and forget pattern - don't wait for cache write
+cache.put("key", data, 60).catch((err) => context.log.error(err));
+```
+
+Always catch errors when using the fire-and-forget pattern to avoid unhandled
+promise rejections.
+
+## When to use ZoneCache
+
+Use ZoneCache when you need low-latency access to frequently used data that's
+stored in a single zone. It's ideal for caching configuration data, session
+information, or results from external API calls that are expensive or slow to
+retrieve.
+
+Avoid using ZoneCache for large datasets or data that needs to be globally
+distributed, as it's designed for small, simple objects within a single zone. It
+is also not suitable to be used as an OLTP to read/write important data, it's
+just a cache - very useful but not a database or key/value store.
+
+## Limits
+
+For full Zuplo platform limits see the
+[Zuplo Limits documentation](../articles/limits.mdx).
+
+- Maximum size per cached item: 512 MB
+- Maximum cache calls per request: 1000

package/docs/programmable-api/zp-body-removed.mdx

@@ -0,0 +1,32 @@
+---
+title: zp-body-removed
+sidebar_label: zp-body-removed
+---
+
+Zuplo doesn't support GET or HEAD requests with bodies. This is because the
+product is based on web standards and our stack makes heavy use of
+[fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) which
+explicitly doesn't support GET, HEAD requests with a body.
+
+For this reason, any body of a GET/HEAD request is stripped on entry into Zuplo
+infrastructure and a header `zp-body-removed` is added to the request.
+
+This allows your origin/backend server to know that a body was removed. If you
+want to enforce this and reject such requests it's easy to write a custom policy
+that looks for a `zp-body-removed` header and return a response. An example is
+below:
+
+```ts
+import { HttpProblems, ZuploContext, ZuploRequest } from "@zuplo/runtime";
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  const bodyRemoved = request.headers.get("zp-body-removed");
+
+  if (bodyRemoved) {
+    return HttpProblems.badRequest(request, context, {
+      detail: `GET or HEAD requests can't have a body.`,
+    });
+  }
+
+  return request;
+}
+```