@fedify/vocab-runtime 2.5.0-dev.2446 → 2.5.0-dev.2492

package/deno.json

@@ -1,12 +1,13 @@
 {
   "name": "@fedify/vocab-runtime",
-  "version": "2.5.0-dev.2446+2014cb03",
+  "version": "2.5.0-dev.2492+4648c04e",
   "license": "MIT",
   "exports": {
     ".": "./src/mod.ts",
     "./internal/jsonld-cache": "./src/internal/jsonld-cache.ts",
     "./internal/portable-dereference": "./src/internal/portable-dereference.ts",
     "./internal/signed-representation": "./src/internal/signed-representation.ts",
+    "./internal": "./src/internal.ts",
     "./jsonld": "./src/jsonld.ts",
     "./temporal": "./src/temporal.ts"
   },
@@ -22,7 +23,8 @@
     "byte-encodings": "npm:byte-encodings@^1.0.11",
     "fetch-mock": "npm:fetch-mock@^12.5.4",
     "jsonld": "npm:jsonld@^9.0.0",
-    "pkijs": "npm:pkijs@^3.2.5"
+    "pkijs": "npm:pkijs@^3.2.5",
+    "undici": "npm:undici@^7.30.1"
   },
   "exclude": [
     "dist",
@@ -31,6 +33,7 @@
   "publish": {
     "exclude": [
       "**/*.test.ts",
+      "src/**/testdata/",
       "tsdown.config.ts"
     ]
   },

package/dist/{docloader-BBnBpbsG.d.cts → docloader-DD6binpN.d.cts}

@@ -221,7 +221,9 @@ type AuthenticatedDocumentLoaderFactory = (identity: {
 * Gets a {@link RemoteDocument} from the given response.
 * @param url The URL of the document to load.
 * @param response The response to get the document from.
-* @param fetch The function to fetch the document.
+* @param fetch The function to fetch the document.  It is called with the URL
+*              of an alternate document, if any, after the response body has
+*              been either read or its cancellation has been started.
 * @param options The options for loading the document.
 * @returns The loaded remote document.
 * @throws {FetchError} If the response is not OK.
@@ -292,12 +294,6 @@ interface GetDocumentLoaderOptions extends DocumentLoaderFactoryOptions {
 * @returns The document loader.
 * @since 1.3.0
 */
-declare function getDocumentLoader({
-  allowPrivateAddress,
-  maxRedirection,
-  skipPreloadedContexts,
-  timeout,
-  userAgent
-}?: GetDocumentLoaderOptions): DocumentLoader;
+declare function getDocumentLoader(options?: GetDocumentLoaderOptions): DocumentLoader;
 //#endregion
 export { isTransientFetchError as _, DocumentLoaderOptions as a, getDocumentLoader as c, withDocumentLoaderTimeout as d, CreateRequestOptions as f, getUserAgent as g, createActivityPubRequest as h, DocumentLoaderFactoryOptions as i, getRemoteDocument as l, GetUserAgentOptions as m, DocumentLoader as n, GetDocumentLoaderOptions as o, FetchError as p, DocumentLoaderFactory as r, RemoteDocument as s, AuthenticatedDocumentLoaderFactory as t, resolveDocumentLoaderTimeout as u, logRequest as v };

package/dist/{docloader-BBnBpbsG.d.ts → docloader-DD6binpN.d.ts}

@@ -221,7 +221,9 @@ type AuthenticatedDocumentLoaderFactory = (identity: {
 * Gets a {@link RemoteDocument} from the given response.
 * @param url The URL of the document to load.
 * @param response The response to get the document from.
-* @param fetch The function to fetch the document.
+* @param fetch The function to fetch the document.  It is called with the URL
+*              of an alternate document, if any, after the response body has
+*              been either read or its cancellation has been started.
 * @param options The options for loading the document.
 * @returns The loaded remote document.
 * @throws {FetchError} If the response is not OK.
@@ -292,12 +294,6 @@ interface GetDocumentLoaderOptions extends DocumentLoaderFactoryOptions {
 * @returns The document loader.
 * @since 1.3.0
 */
-declare function getDocumentLoader({
-  allowPrivateAddress,
-  maxRedirection,
-  skipPreloadedContexts,
-  timeout,
-  userAgent
-}?: GetDocumentLoaderOptions): DocumentLoader;
+declare function getDocumentLoader(options?: GetDocumentLoaderOptions): DocumentLoader;
 //#endregion
 export { isTransientFetchError as _, DocumentLoaderOptions as a, getDocumentLoader as c, withDocumentLoaderTimeout as d, CreateRequestOptions as f, getUserAgent as g, createActivityPubRequest as h, DocumentLoaderFactoryOptions as i, getRemoteDocument as l, GetUserAgentOptions as m, DocumentLoader as n, GetDocumentLoaderOptions as o, FetchError as p, DocumentLoaderFactory as r, RemoteDocument as s, AuthenticatedDocumentLoaderFactory as t, resolveDocumentLoaderTimeout as u, logRequest as v };

package/dist/internal/jsonld-cache.cjs

@@ -1,6 +1,6 @@
 
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_url = require("../url-DrGTR8yv.cjs");
+const require_url = require("../url-DIKZnaJv.cjs");
 const require_jsonld = require("../jsonld.cjs");
 //#region src/internal/jsonld-cache.ts
 /**

package/dist/internal/jsonld-cache.d.cts

@@ -1,5 +1,5 @@
 /// <reference lib="esnext.temporal" />
-import { n as DocumentLoader } from "../docloader-BBnBpbsG.cjs";
+import { n as DocumentLoader } from "../docloader-DD6binpN.cjs";
 
 //#region src/internal/jsonld-cache.d.ts
 /**

package/dist/internal/jsonld-cache.d.ts

@@ -1,5 +1,5 @@
 /// <reference lib="esnext.temporal" />
-import { n as DocumentLoader } from "../docloader-BBnBpbsG.js";
+import { n as DocumentLoader } from "../docloader-DD6binpN.js";
 
 //#region src/internal/jsonld-cache.d.ts
 /**

package/dist/internal/jsonld-cache.js

@@ -1,5 +1,5 @@
 
-import { _ as parseIri, c as getFe34Origin, d as haveSameIriOrigin, o as formatIri, s as fromCompatibleEf61Id, u as haveSameFe34Origin } from "../url-Dzyp-NsC.js";
+import { b as parseIri, c as fromCompatibleEf61Id, d as haveSameFe34Origin, f as haveSameIriOrigin, l as getFe34Origin, s as formatIri } from "../url-mWveR5GA.js";
 import jsonld_default from "../jsonld.js";
 //#region src/internal/jsonld-cache.ts
 /**

package/dist/internal/portable-dereference.cjs

@@ -1,7 +1,7 @@
 
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_contexts = require("../contexts-B09jb9Pi.cjs");
-const require_url = require("../url-DrGTR8yv.cjs");
+const require_url = require("../url-DIKZnaJv.cjs");
 const require_jsonld = require("../jsonld.cjs");
 const require_internal_jsonld_cache = require("./jsonld-cache.cjs");
 let _logtape_logtape = require("@logtape/logtape");
@@ -497,6 +497,35 @@ var PortableObjectRejectedError = class extends Error {
 		this.name = "PortableObjectRejectedError";
 	}
 };
+/**
+* Asks an observer whether to accept a candidate.  A refusal, including an
+* error thrown by the observer, is reported to the observer as an `accept`
+* failure.
+* @returns `true` if there is no observer, or it accepted the candidate.
+* @internal Not part of the public API contract.
+*/
+async function acceptCandidate(observer, candidate) {
+	if (observer?.accept == null) return true;
+	let accepted;
+	try {
+		accepted = await observer.accept(candidate);
+	} catch (error) {
+		observer.failed?.({
+			operation: "accept",
+			error
+		});
+		return false;
+	}
+	if (!accepted) observer.failed?.({ operation: "accept" });
+	return accepted;
+}
+/** Wraps an error that has already been reported to the observer. */
+var ObservedFailure = class {
+	error;
+	constructor(error) {
+		this.error = error;
+	}
+};
 var PortableObjectRejection = class {
 	message;
 	values;
@@ -592,6 +621,10 @@ async function dereferencePortableIri(url, options) {
 					requestUrl,
 					error
 				});
+				options.observer?.failed?.({
+					operation: "fetch",
+					error
+				});
 				attempts.push({
 					type: "error",
 					error
@@ -622,11 +655,33 @@ async function dereferencePortableIri(url, options) {
 					throw new PortableObjectRejection("the proof verifier failed: {error}", { error });
 				}
 				if (!result.verified) throw new PortableObjectRejection("it does not satisfy the FEP-ef61 proof policy: {result}", { result });
-				const object = await options.parse(document, {
-					contextLoader,
-					baseUrl: url
-				});
+				let object;
+				try {
+					object = await options.parse(document, {
+						contextLoader,
+						baseUrl: url
+					});
+				} catch (error) {
+					options.observer?.failed?.({
+						operation: "parse",
+						error
+					});
+					throw new ObservedFailure(error);
+				}
 				signal?.throwIfAborted();
+				if (!await acceptCandidate(options.observer, {
+					document,
+					documentUrl: remoteDocument.documentUrl,
+					baseUrl: url,
+					contextLoader,
+					object
+				})) {
+					attempts.push({
+						type: "rejected",
+						source: requestUrl
+					});
+					continue;
+				}
 				if (object != null && typeof object === "object") provenances.set(object, {
 					acceptance: result.unsecured === true ? "unsecured" : "verified",
 					...result.collectionContext === void 0 ? {} : { collectionContext: result.collectionContext },
@@ -642,20 +697,29 @@ async function dereferencePortableIri(url, options) {
 						url: lookupUrl,
 						requestUrl
 					});
+					options.observer?.failed?.({
+						operation: "verify",
+						error: error.values.error
+					});
 					attempts.push({
 						type: "rejected",
 						source: requestUrl
 					});
 					continue;
 				}
+				const cause = error instanceof ObservedFailure ? error.error : error;
+				if (!(error instanceof ObservedFailure)) options.observer?.failed?.({
+					operation: "verify",
+					error
+				});
 				logger.debug("Failed to parse {url} from {requestUrl}: {error}", {
 					url: lookupUrl,
 					requestUrl,
-					error
+					error: cause
 				});
 				attempts.push({
 					type: "error",
-					error
+					error: cause
 				});
 			}
 		}
@@ -701,6 +765,7 @@ async function checkPortableObjectId(document, expectedId, contextLoader) {
 }
 //#endregion
 exports.PortableObjectRejectedError = PortableObjectRejectedError;
+exports.acceptCandidate = acceptCandidate;
 exports.copyPortableProvenance = copyPortableProvenance;
 exports.createSnapshotContextLoader = createSnapshotContextLoader;
 exports.dereferencePortableIri = dereferencePortableIri;

package/dist/internal/portable-dereference.d.cts

@@ -1,6 +1,6 @@
 /// <reference lib="esnext.temporal" />
-import { n as DocumentLoader, s as RemoteDocument } from "../docloader-BBnBpbsG.cjs";
-import { r as PortableObjectVerifier } from "../portable-Dfvcg_Wy.cjs";
+import { n as DocumentLoader, s as RemoteDocument } from "../docloader-DD6binpN.cjs";
+import { r as PortableObjectVerifier } from "../portable-Cr7NwZwb.cjs";
 import { Span, TracerProvider } from "@opentelemetry/api";
 
 //#region src/internal/portable-dereference.d.ts
@@ -311,6 +311,58 @@ interface DereferencePortableIriOptions<T> {
     baseUrl: URL;
   }) => Promise<T>;
   span?: Span;
+  /**
+  * Observes each candidate document, and may refuse a candidate that was
+  * otherwise acceptable, in which case the next gateway is tried.
+  */
+  observer?: DereferenceObserver<T>;
+}
+/**
+* A candidate document that a lookup or a dereference was about to return.
+*
+* @internal Not part of the public API contract.
+*/
+interface DereferenceCandidate<T> {
+  /** The document as it was retrieved. */
+  readonly document: unknown;
+  /** The URL the document was finally retrieved from. */
+  readonly documentUrl: string;
+  /** The `baseUrl` option the document was parsed with. */
+  readonly baseUrl: URL;
+  /**
+  * The context loader the document was parsed with.  It keeps serving the
+  * same context documents until the {@link DereferenceObserver.accept}
+  * call settles.
+  */
+  readonly contextLoader: DocumentLoader;
+  /** The parsed object. */
+  readonly object: T;
+}
+/**
+* Observes the candidates and the swallowed failures of a lookup or
+* a dereference.
+*
+* @internal Not part of the public API contract.
+*/
+interface DereferenceObserver<T> {
+  /**
+  * Called for each candidate whose parse succeeded, right before it would be
+  * returned.  If it resolves to `false`, the candidate is refused, and the
+  * next one is tried.  An error it throws is treated as a refusal, and is
+  * reported to {@link failed}.
+  */
+  accept?(candidate: DereferenceCandidate<T>): Promise<boolean>;
+  /** Called for each failure that does not propagate by itself. */
+  failed?(failure: DereferenceFailure): void;
+}
+/**
+* A failure observed by {@link DereferenceObserver.failed}.
+*
+* @internal Not part of the public API contract.
+*/
+interface DereferenceFailure {
+  readonly operation: "fetch" | "verify" | "parse" | "origin" | "accept";
+  readonly error?: unknown;
 }
 /**
 * The error thrown by {@link dereferencePortableIri} under
@@ -323,6 +375,14 @@ declare class PortableObjectRejectedError extends Error {
   constructor(message: string);
 }
 /**
+* Asks an observer whether to accept a candidate.  A refusal, including an
+* error thrown by the observer, is reported to the observer as an `accept`
+* failure.
+* @returns `true` if there is no observer, or it accepted the candidate.
+* @internal Not part of the public API contract.
+*/
+declare function acceptCandidate<T>(observer: DereferenceObserver<T> | undefined, candidate: DereferenceCandidate<T>): Promise<boolean>;
+/**
 * Dereferences an FEP-ef61 portable IRI through its gateways.
 *
 * Gateways are tried one by one until one of them returns a single-node
@@ -346,4 +406,4 @@ declare function dereferencePortableIri<T extends {
   id: URL | null;
 }>(url: URL, options: DereferencePortableIriOptions<T>): Promise<T | null>;
 //#endregion
-export { DereferencePortableIriOptions, PortableObjectRejectedError, PortableReferrerLink, PortableResponseClaim, copyPortableProvenance, createSnapshotContextLoader, dereferencePortableIri, getPortableGatewayCandidates, getPortableResponseClaim, getReferrerGateways, isCompatibleEf61Iri, isInPortableChain, isPortableIri, isPortableMode, isUnsecuredPortableObject, isUnverifiedPortableClaim, markUnverifiedPortableClaim, mustDereferencePortableObject, parseCompatibleEf61Reference, recordPortableReferrer, rejectMalformedCompatibleReference, warnUnverifiableEmbeddedObject };
+export { DereferenceCandidate, DereferenceFailure, DereferenceObserver, DereferencePortableIriOptions, PortableObjectRejectedError, PortableReferrerLink, PortableResponseClaim, acceptCandidate, copyPortableProvenance, createSnapshotContextLoader, dereferencePortableIri, getPortableGatewayCandidates, getPortableResponseClaim, getReferrerGateways, isCompatibleEf61Iri, isInPortableChain, isPortableIri, isPortableMode, isUnsecuredPortableObject, isUnverifiedPortableClaim, markUnverifiedPortableClaim, mustDereferencePortableObject, parseCompatibleEf61Reference, recordPortableReferrer, rejectMalformedCompatibleReference, warnUnverifiableEmbeddedObject };

package/dist/internal/portable-dereference.d.ts

@@ -1,6 +1,6 @@
 /// <reference lib="esnext.temporal" />
-import { n as DocumentLoader, s as RemoteDocument } from "../docloader-BBnBpbsG.js";
-import { r as PortableObjectVerifier } from "../portable-BDydjp5H.js";
+import { n as DocumentLoader, s as RemoteDocument } from "../docloader-DD6binpN.js";
+import { r as PortableObjectVerifier } from "../portable-1VSnSJFj.js";
 import { Span, TracerProvider } from "@opentelemetry/api";
 
 //#region src/internal/portable-dereference.d.ts
@@ -311,6 +311,58 @@ interface DereferencePortableIriOptions<T> {
     baseUrl: URL;
   }) => Promise<T>;
   span?: Span;
+  /**
+  * Observes each candidate document, and may refuse a candidate that was
+  * otherwise acceptable, in which case the next gateway is tried.
+  */
+  observer?: DereferenceObserver<T>;
+}
+/**
+* A candidate document that a lookup or a dereference was about to return.
+*
+* @internal Not part of the public API contract.
+*/
+interface DereferenceCandidate<T> {
+  /** The document as it was retrieved. */
+  readonly document: unknown;
+  /** The URL the document was finally retrieved from. */
+  readonly documentUrl: string;
+  /** The `baseUrl` option the document was parsed with. */
+  readonly baseUrl: URL;
+  /**
+  * The context loader the document was parsed with.  It keeps serving the
+  * same context documents until the {@link DereferenceObserver.accept}
+  * call settles.
+  */
+  readonly contextLoader: DocumentLoader;
+  /** The parsed object. */
+  readonly object: T;
+}
+/**
+* Observes the candidates and the swallowed failures of a lookup or
+* a dereference.
+*
+* @internal Not part of the public API contract.
+*/
+interface DereferenceObserver<T> {
+  /**
+  * Called for each candidate whose parse succeeded, right before it would be
+  * returned.  If it resolves to `false`, the candidate is refused, and the
+  * next one is tried.  An error it throws is treated as a refusal, and is
+  * reported to {@link failed}.
+  */
+  accept?(candidate: DereferenceCandidate<T>): Promise<boolean>;
+  /** Called for each failure that does not propagate by itself. */
+  failed?(failure: DereferenceFailure): void;
+}
+/**
+* A failure observed by {@link DereferenceObserver.failed}.
+*
+* @internal Not part of the public API contract.
+*/
+interface DereferenceFailure {
+  readonly operation: "fetch" | "verify" | "parse" | "origin" | "accept";
+  readonly error?: unknown;
 }
 /**
 * The error thrown by {@link dereferencePortableIri} under
@@ -323,6 +375,14 @@ declare class PortableObjectRejectedError extends Error {
   constructor(message: string);
 }
 /**
+* Asks an observer whether to accept a candidate.  A refusal, including an
+* error thrown by the observer, is reported to the observer as an `accept`
+* failure.
+* @returns `true` if there is no observer, or it accepted the candidate.
+* @internal Not part of the public API contract.
+*/
+declare function acceptCandidate<T>(observer: DereferenceObserver<T> | undefined, candidate: DereferenceCandidate<T>): Promise<boolean>;
+/**
 * Dereferences an FEP-ef61 portable IRI through its gateways.
 *
 * Gateways are tried one by one until one of them returns a single-node
@@ -346,4 +406,4 @@ declare function dereferencePortableIri<T extends {
   id: URL | null;
 }>(url: URL, options: DereferencePortableIriOptions<T>): Promise<T | null>;
 //#endregion
-export { DereferencePortableIriOptions, PortableObjectRejectedError, PortableReferrerLink, PortableResponseClaim, copyPortableProvenance, createSnapshotContextLoader, dereferencePortableIri, getPortableGatewayCandidates, getPortableResponseClaim, getReferrerGateways, isCompatibleEf61Iri, isInPortableChain, isPortableIri, isPortableMode, isUnsecuredPortableObject, isUnverifiedPortableClaim, markUnverifiedPortableClaim, mustDereferencePortableObject, parseCompatibleEf61Reference, recordPortableReferrer, rejectMalformedCompatibleReference, warnUnverifiableEmbeddedObject };
+export { DereferenceCandidate, DereferenceFailure, DereferenceObserver, DereferencePortableIriOptions, PortableObjectRejectedError, PortableReferrerLink, PortableResponseClaim, acceptCandidate, copyPortableProvenance, createSnapshotContextLoader, dereferencePortableIri, getPortableGatewayCandidates, getPortableResponseClaim, getReferrerGateways, isCompatibleEf61Iri, isInPortableChain, isPortableIri, isPortableMode, isUnsecuredPortableObject, isUnverifiedPortableClaim, markUnverifiedPortableClaim, mustDereferencePortableObject, parseCompatibleEf61Reference, recordPortableReferrer, rejectMalformedCompatibleReference, warnUnverifiableEmbeddedObject };

package/dist/internal/portable-dereference.js

@@ -1,6 +1,6 @@
 
 import { t as preloadedContexts } from "../contexts-DWrj4AGR.js";
-import { _ as parseIri, h as parseGatewayOrigin, i as canonicalizePortableUri, o as formatIri, s as fromCompatibleEf61Id, t as GATEWAY_HINT_PARAMETER, u as haveSameFe34Origin, y as toCompatibleEf61Id } from "../url-Dzyp-NsC.js";
+import { C as toCompatibleEf61Id, a as canonicalizePortableUri, b as parseIri, c as fromCompatibleEf61Id, d as haveSameFe34Origin, s as formatIri, t as GATEWAY_HINT_PARAMETER, v as parseGatewayOrigin } from "../url-mWveR5GA.js";
 import jsonld_default from "../jsonld.js";
 import { createScopedContextLoader, registerDocumentLoaderWrapper, unwrapReleasedDocumentLoader } from "./jsonld-cache.js";
 import { getLogger } from "@logtape/logtape";
@@ -496,6 +496,35 @@ var PortableObjectRejectedError = class extends Error {
 		this.name = "PortableObjectRejectedError";
 	}
 };
+/**
+* Asks an observer whether to accept a candidate.  A refusal, including an
+* error thrown by the observer, is reported to the observer as an `accept`
+* failure.
+* @returns `true` if there is no observer, or it accepted the candidate.
+* @internal Not part of the public API contract.
+*/
+async function acceptCandidate(observer, candidate) {
+	if (observer?.accept == null) return true;
+	let accepted;
+	try {
+		accepted = await observer.accept(candidate);
+	} catch (error) {
+		observer.failed?.({
+			operation: "accept",
+			error
+		});
+		return false;
+	}
+	if (!accepted) observer.failed?.({ operation: "accept" });
+	return accepted;
+}
+/** Wraps an error that has already been reported to the observer. */
+var ObservedFailure = class {
+	error;
+	constructor(error) {
+		this.error = error;
+	}
+};
 var PortableObjectRejection = class {
 	message;
 	values;
@@ -591,6 +620,10 @@ async function dereferencePortableIri(url, options) {
 					requestUrl,
 					error
 				});
+				options.observer?.failed?.({
+					operation: "fetch",
+					error
+				});
 				attempts.push({
 					type: "error",
 					error
@@ -621,11 +654,33 @@ async function dereferencePortableIri(url, options) {
 					throw new PortableObjectRejection("the proof verifier failed: {error}", { error });
 				}
 				if (!result.verified) throw new PortableObjectRejection("it does not satisfy the FEP-ef61 proof policy: {result}", { result });
-				const object = await options.parse(document, {
-					contextLoader,
-					baseUrl: url
-				});
+				let object;
+				try {
+					object = await options.parse(document, {
+						contextLoader,
+						baseUrl: url
+					});
+				} catch (error) {
+					options.observer?.failed?.({
+						operation: "parse",
+						error
+					});
+					throw new ObservedFailure(error);
+				}
 				signal?.throwIfAborted();
+				if (!await acceptCandidate(options.observer, {
+					document,
+					documentUrl: remoteDocument.documentUrl,
+					baseUrl: url,
+					contextLoader,
+					object
+				})) {
+					attempts.push({
+						type: "rejected",
+						source: requestUrl
+					});
+					continue;
+				}
 				if (object != null && typeof object === "object") provenances.set(object, {
 					acceptance: result.unsecured === true ? "unsecured" : "verified",
 					...result.collectionContext === void 0 ? {} : { collectionContext: result.collectionContext },
@@ -641,20 +696,29 @@ async function dereferencePortableIri(url, options) {
 						url: lookupUrl,
 						requestUrl
 					});
+					options.observer?.failed?.({
+						operation: "verify",
+						error: error.values.error
+					});
 					attempts.push({
 						type: "rejected",
 						source: requestUrl
 					});
 					continue;
 				}
+				const cause = error instanceof ObservedFailure ? error.error : error;
+				if (!(error instanceof ObservedFailure)) options.observer?.failed?.({
+					operation: "verify",
+					error
+				});
 				logger.debug("Failed to parse {url} from {requestUrl}: {error}", {
 					url: lookupUrl,
 					requestUrl,
-					error
+					error: cause
 				});
 				attempts.push({
 					type: "error",
-					error
+					error: cause
 				});
 			}
 		}
@@ -699,4 +763,4 @@ async function checkPortableObjectId(document, expectedId, contextLoader) {
 	if (actualId !== expectedId) throw new PortableObjectRejection("its @id ({objectId}) does not match the requested portable ID", { objectId: id });
 }
 //#endregion
-export { PortableObjectRejectedError, copyPortableProvenance, createSnapshotContextLoader, dereferencePortableIri, getPortableGatewayCandidates, getPortableResponseClaim, getReferrerGateways, isCompatibleEf61Iri, isInPortableChain, isPortableIri, isPortableMode, isUnsecuredPortableObject, isUnverifiedPortableClaim, markUnverifiedPortableClaim, mustDereferencePortableObject, parseCompatibleEf61Reference, recordPortableReferrer, rejectMalformedCompatibleReference, warnUnverifiableEmbeddedObject };
+export { PortableObjectRejectedError, acceptCandidate, copyPortableProvenance, createSnapshotContextLoader, dereferencePortableIri, getPortableGatewayCandidates, getPortableResponseClaim, getReferrerGateways, isCompatibleEf61Iri, isInPortableChain, isPortableIri, isPortableMode, isUnsecuredPortableObject, isUnverifiedPortableClaim, markUnverifiedPortableClaim, mustDereferencePortableObject, parseCompatibleEf61Reference, recordPortableReferrer, rejectMalformedCompatibleReference, warnUnverifiableEmbeddedObject };

package/dist/internal.cjs

@@ -0,0 +1,6 @@
+
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_public_fetch = require("./public-fetch-Dvfvawei.cjs");
+exports.openDirectFetch = require_public_fetch.openDirectFetch;
+exports.openPublicFetch = require_public_fetch.openPublicFetch;
+exports.withPublicFetch = require_public_fetch.withPublicFetch;

package/dist/internal.d.cts

@@ -0,0 +1,108 @@
+/// <reference lib="esnext.temporal" />
+import { t as ResolvedAddress } from "./url-4EE56sNP.cjs";
+
+//#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 { type PublicFetchOptions, type PublicFetchSession, openDirectFetch, openPublicFetch, withPublicFetch };