@fedify/vocab-runtime 2.3.15-dev.2482 → 2.3.15

package/dist/public-fetch-DBpt3xxf.d.cts

@@ -0,0 +1,143 @@
+/// <reference lib="esnext.temporal" />
+//#region src/url.d.ts
+/**
+* An address returned by a DNS lookup.  It has the same shape as
+* `ResolvedAddress` of `node:dns`, without depending on its type declarations.
+* @internal
+*/
+interface ResolvedAddress {
+  /** An IPv4 or IPv6 address. */
+  readonly address: string;
+  /** The IP family of the address: `4` or `6`. */
+  readonly family: number;
+}
+declare class UrlError extends Error {
+  /**
+  * The failure category. Defaults to `"disallowed"`.
+  * `"dns"` includes lookup errors and results with no usable IP addresses.
+  * @since 2.0.29
+  */
+  readonly reason: "dns" | "disallowed";
+  constructor(message: string, options?: {
+    cause?: unknown;
+    reason?: "dns" | "disallowed";
+  });
+}
+/**
+* Validates a URL to prevent SSRF attacks.
+*
+* This function only checks the addresses that the hostname currently
+* resolves to; it does not pin the connection to those addresses.  A request
+* made after this check resolves the hostname again, so this function alone
+* does not prevent DNS rebinding.
+*/
+declare function validatePublicUrl(url: string): Promise<void>;
+declare function isValidPublicIPv4Address(address: string): boolean;
+declare function isValidPublicIPv6Address(address: string): boolean;
+declare function expandIPv6Address(address: string): string;
+//#endregion
+//#region src/public-fetch.d.ts
+/**
+* Options for {@link openPublicFetch} and {@link withPublicFetch}.
+*/
+interface PublicFetchOptions {
+  /**
+  * An `AbortSignal` for cancelling the DNS lookup.
+  */
+  readonly signal?: AbortSignal;
+  /**
+  * A function that resolves all addresses of a hostname, used instead of
+  * `node:dns.lookup()`.  The addresses it returns are validated in the same
+  * way as the default lookup's.
+  */
+  readonly lookup?: (hostname: string) => Promise<readonly ResolvedAddress[]>;
+}
+/**
+* A session for fetching resources from a single origin.  Its `fetch()`
+* connects only to the addresses validated when the session was opened, on
+* runtimes that support it.
+*/
+interface PublicFetchSession {
+  /**
+  * A copy of the URL the session was opened for.
+  */
+  readonly url: URL;
+  /**
+  * Fetches a resource from the session's origin.  Redirects are never
+  * followed; the redirect mode is always `"manual"`.
+  * @throws {TypeError} If the input's origin differs from the session's, or
+  *                     if the session is closed.
+  */
+  fetch(input: Request | URL | string, init?: RequestInit): Promise<Response>;
+  /**
+  * Closes the session.  The cancellation of response bodies that have been
+  * neither consumed nor cancelled is started (without waiting for it), and
+  * the session can no longer fetch.  Calling this more than once has no
+  * effect.
+  */
+  close(): Promise<void>;
+}
+/**
+* The functions created by {@link createPublicFetch}.
+*/
+interface PublicFetch {
+  /**
+  * Validates the URL, resolves its hostname, checks that every resolved
+  * address is public, and opens a session that connects only to those
+  * addresses.
+  * @param url The URL to open a session for.
+  * @param options The options.
+  * @returns The session.  It must be closed.
+  * @throws {UrlError} If the URL is not allowed, or its hostname cannot be
+  *                    resolved (with `reason: "dns"`).
+  */
+  openPublicFetch(url: URL | string, options?: PublicFetchOptions): Promise<PublicFetchSession>;
+  /**
+  * Opens a session with {@link PublicFetch.openPublicFetch}, runs the given
+  * function with its `fetch()`, and closes the session afterwards.
+  * @param url The URL to open a session for.
+  * @param fn The function to run.  It must not return a `Response`, since
+  *           the response bodies are cancelled when the session is closed.
+  * @param options The options.
+  * @returns The value returned by `fn`.
+  * @throws {UrlError} If the URL is not allowed.
+  * @throws {TypeError} If `fn` returns a `Response`.
+  */
+  withPublicFetch<T>(url: URL | string, fn: (fetch: PublicFetchSession["fetch"]) => Promise<T>, options?: PublicFetchOptions): Promise<T>;
+}
+/**
+* Validates the URL, resolves its hostname, checks that every resolved
+* address is public, and opens a session that connects only to those
+* addresses.  Connections are pinned on Node.js and Bun.  On other runtimes,
+* the session uses the global `fetch()` after the check.
+* @param url The URL to open a session for.
+* @param options The options.
+* @returns The session.  It must be closed.
+* @throws {UrlError} If the URL is not allowed, or its hostname cannot be
+*                    resolved (with `reason: "dns"`).
+*/
+declare const openPublicFetch: PublicFetch["openPublicFetch"];
+/**
+* Opens a session with {@link openPublicFetch}, runs the given function with
+* its `fetch()`, and closes the session afterwards.
+* @param url The URL to open a session for.
+* @param fn The function to run.  It must not return a `Response`, since
+*           the response bodies are cancelled when the session is closed.
+* @param options The options.
+* @returns The value returned by `fn`.
+* @throws {UrlError} If the URL is not allowed.
+* @throws {TypeError} If `fn` returns a `Response`.
+*/
+declare const withPublicFetch: PublicFetch["withPublicFetch"];
+/**
+* Opens a session that neither validates nor pins addresses, for callers that
+* allow private addresses.  It has the same rules as {@link openPublicFetch}
+* sessions otherwise: requests are limited to the URL's origin, redirects are
+* never followed, and unconsumed response bodies are cancelled on close.
+* It grants nothing beyond calling the global `fetch()` directly.
+* @param url The URL to open a session for.
+* @returns The session.  It must be closed.
+*/
+declare function openDirectFetch(url: URL | string): Promise<PublicFetchSession>;
+//#endregion
+export { withPublicFetch as a, isValidPublicIPv4Address as c, openPublicFetch as i, isValidPublicIPv6Address as l, PublicFetchSession as n, UrlError as o, openDirectFetch as r, expandIPv6Address as s, PublicFetchOptions as t, validatePublicUrl as u };