@fedify/vocab-runtime 2.4.0-dev.2035 → 2.4.0-dev.2054

package/deno.json

@@ -1,10 +1,11 @@
 {
   "name": "@fedify/vocab-runtime",
-  "version": "2.4.0-dev.2035+d1f8f8e2",
+  "version": "2.4.0-dev.2054+1756e190",
   "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",
     "./jsonld": "./src/jsonld.ts",
     "./temporal": "./src/temporal.ts"

package/dist/internal/portable-dereference.cjs

@@ -0,0 +1,315 @@
+
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_contexts = require("../contexts-2hEbs3Qk.cjs");
+const require_url = require("../url-Cke4irYD.cjs");
+const require_jsonld = require("../jsonld.cjs");
+let _logtape_logtape = require("@logtape/logtape");
+let _opentelemetry_api = require("@opentelemetry/api");
+//#region src/internal/portable-dereference.ts
+const logger = (0, _logtape_logtape.getLogger)([
+	"fedify",
+	"vocab",
+	"gateway"
+]);
+/**
+* The maximum number of `@gateway` location hints to try for one reference.
+* Hints come from possibly untrusted documents, so they are bounded to keep
+* a single accessor call from fanning out to many servers.
+*/
+const MAX_GATEWAY_HINTS = 5;
+const LOCATION_HINT_PARAMETER = "@gateway";
+const BASELINE_CONTEXT_URLS = /* @__PURE__ */ new Set([
+	"https://w3id.org/identity/v1",
+	"https://www.w3.org/ns/activitystreams",
+	"https://w3id.org/security/v1",
+	"https://w3id.org/security/data-integrity/v1"
+]);
+/**
+* Checks whether a URL is an FEP-ef61 portable ActivityPub IRI.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+function isPortableIri(url) {
+	return url.protocol === "ap+ef61:" || url.protocol === "ap:";
+}
+/**
+* Picks the ordered list of FEP-ef61 gateways to fetch a portable IRI from.
+*
+* If `gateways` is given, it is used as is (even when empty), and `@gateway`
+* location hints in the IRI are ignored.  Otherwise, up to
+* {@link MAX_GATEWAY_HINTS} valid `@gateway` hints are used.  Duplicate
+* gateways are dropped in both cases.
+*
+* @throws {TypeError} If an explicit gateway is not an HTTP(S) origin.
+* @internal
+*/
+function getPortableGatewayCandidates(url, gateways) {
+	const candidates = [];
+	const seen = /* @__PURE__ */ new Set();
+	const add = (gateway) => {
+		if (seen.has(gateway.href)) return;
+		seen.add(gateway.href);
+		candidates.push(gateway);
+	};
+	if (gateways != null) {
+		for (const gateway of gateways) {
+			const parsed = parseGatewayOrigin(gateway);
+			if (parsed == null) throw new TypeError("FEP-ef61 gateways must be HTTP(S) origins with no credentials, path, query, or fragment: " + String(gateway));
+			add(parsed);
+		}
+		return candidates;
+	}
+	for (const hint of new URLSearchParams(url.search).getAll(LOCATION_HINT_PARAMETER)) {
+		if (candidates.length >= MAX_GATEWAY_HINTS) break;
+		const parsed = parseGatewayOrigin(hint);
+		if (parsed == null) {
+			logger.debug("Ignoring an invalid FEP-ef61 gateway hint {hint} in {url}.", {
+				hint,
+				url: require_url.formatIri(url)
+			});
+			continue;
+		}
+		add(parsed);
+	}
+	return candidates;
+}
+function parseGatewayOrigin(gateway) {
+	let url;
+	if (gateway instanceof URL) url = new URL(gateway.href);
+	else if (typeof gateway === "string" && URL.canParse(gateway)) url = new URL(gateway);
+	else return null;
+	if (url.protocol !== "http:" && url.protocol !== "https:" || url.href !== `${url.origin}/`) return null;
+	return url;
+}
+/**
+* Creates a context loader that returns the same context documents for the
+* whole dereference operation, so that the identity check, the proof
+* verifier, and the parser interpret the fetched document identically even
+* if the underlying loader is nondeterministic.  Failed loads are not
+* remembered, so a transient failure does not affect the next gateway.
+*
+* The parsed object keeps the loader for its own later dereferences, so
+* `release()` turns it into a plain pass-through to the underlying loader
+* once the operation is over.
+*/
+function createSnapshotContextLoader(contextLoader) {
+	const cache = /* @__PURE__ */ new Map();
+	let released = false;
+	const release = () => {
+		released = true;
+		cache.clear();
+	};
+	const loader = async (url, options) => {
+		if (released) return await contextLoader(url, options);
+		const key = URL.canParse(url) ? new URL(url).href : url;
+		if (BASELINE_CONTEXT_URLS.has(key)) return {
+			contextUrl: null,
+			document: structuredClone(require_contexts.preloadedContexts[key]),
+			documentUrl: key
+		};
+		let promise = cache.get(key);
+		if (promise == null) {
+			const loading = contextLoader(url, options).then((document) => structuredClone(document));
+			promise = loading;
+			cache.set(key, loading);
+			loading.catch(() => {
+				if (cache.get(key) === loading) cache.delete(key);
+			});
+		}
+		return structuredClone(await promise);
+	};
+	return {
+		loader,
+		release
+	};
+}
+/**
+* The error thrown by {@link dereferencePortableIri} under
+* `crossOrigin: "throw"` when gateways returned objects but none of them
+* satisfied the identity and proof checks.
+*
+* @internal Not part of the public API contract.
+*/
+var PortableObjectRejectedError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "PortableObjectRejectedError";
+	}
+};
+var PortableObjectRejection = class {
+	message;
+	values;
+	constructor(message, values = {}) {
+		this.message = message;
+		this.values = values;
+	}
+};
+/**
+* Dereferences an FEP-ef61 portable IRI through its gateways.
+*
+* Gateways are tried one by one until one of them returns a single-node
+* document whose `@id`, if any, canonically matches the requested IRI and
+* which passes `verifyPortableObject`.  When there is no gateway to try, the document
+* loader is asked for the portable IRI itself, and its result is validated
+* the same way.
+*
+* @returns The parsed object, or `null` if no valid object was retrieved and
+*          `suppressError` is set or the failure was a rejected object
+*          (unless `crossOrigin` is `"throw"`).
+* @throws {TypeError} If `gateways` has an invalid entry (always), if no
+*                     verifier is given, or if the IRI cannot be turned into
+*                     a gateway URL (unless `suppressError` is set).
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+async function dereferencePortableIri(url, options) {
+	url = require_url.parseIri(url);
+	const lookupUrl = require_url.formatIri(url);
+	const { span } = options;
+	const gateways = getPortableGatewayCandidates(url, options.gateways);
+	const fail = (error) => {
+		span?.setStatus({
+			code: _opentelemetry_api.SpanStatusCode.ERROR,
+			message: String(error)
+		});
+		if (options.suppressError) {
+			logger.error("Failed to dereference {url}: {error}", {
+				url: lookupUrl,
+				error
+			});
+			return null;
+		}
+		throw error;
+	};
+	const verify = options.verifyPortableObject;
+	if (verify == null) return fail(/* @__PURE__ */ new TypeError("Dereferencing the portable object " + lookupUrl + " requires the verifyPortableObject option, e.g., verifyPortableObjectProof() from @fedify/fedify."));
+	const requestUrls = [];
+	let expectedId;
+	try {
+		expectedId = require_url.canonicalizePortableUri(lookupUrl);
+		for (const gateway of gateways) requestUrls.push({
+			url: require_url.toCompatibleEf61Id(url, gateway).href,
+			gateway
+		});
+	} catch (error) {
+		return fail(error);
+	}
+	if (requestUrls.length < 1) requestUrls.push({
+		url: lookupUrl,
+		gateway: null
+	});
+	const snapshot = createSnapshotContextLoader(options.contextLoader);
+	const contextLoader = snapshot.loader;
+	const attempts = [];
+	const { signal } = options;
+	try {
+		for (const { url: requestUrl, gateway } of requestUrls) {
+			signal?.throwIfAborted();
+			let remoteDocument;
+			try {
+				remoteDocument = await options.documentLoader(requestUrl, signal == null ? void 0 : { signal });
+			} catch (error) {
+				signal?.throwIfAborted();
+				logger.debug("Failed to fetch {url} from {requestUrl}: {error}", {
+					url: lookupUrl,
+					requestUrl,
+					error
+				});
+				attempts.push({
+					type: "error",
+					error
+				});
+				continue;
+			}
+			const { document } = remoteDocument;
+			try {
+				await checkPortableObjectId(document, expectedId, contextLoader);
+				let result;
+				try {
+					result = await verify(document, {
+						documentLoader: options.documentLoader,
+						contextLoader,
+						tracerProvider: options.tracerProvider
+					});
+				} catch (error) {
+					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
+				});
+				signal?.throwIfAborted();
+				if (gateway != null) span?.setAttribute("activitypub.gateway", gateway.href);
+				return object;
+			} catch (error) {
+				signal?.throwIfAborted();
+				if (error instanceof PortableObjectRejection) {
+					logger.warn("Rejected the portable object {url} served from {requestUrl}, because " + error.message, {
+						...error.values,
+						url: lookupUrl,
+						requestUrl
+					});
+					attempts.push({
+						type: "rejected",
+						source: requestUrl
+					});
+					continue;
+				}
+				logger.debug("Failed to parse {url} from {requestUrl}: {error}", {
+					url: lookupUrl,
+					requestUrl,
+					error
+				});
+				attempts.push({
+					type: "error",
+					error
+				});
+			}
+		}
+	} finally {
+		snapshot.release();
+	}
+	const rejected = attempts.filter((a) => a.type === "rejected");
+	if (rejected.length > 0) {
+		const message = "No gateway returned a valid portable object for " + lookupUrl + "; refusing to return the object.  Objects retrieved from: " + rejected.map((a) => a.source).join(", ") + ".";
+		if (options.suppressError || options.crossOrigin !== "throw") {
+			span?.setStatus({
+				code: _opentelemetry_api.SpanStatusCode.ERROR,
+				message
+			});
+			logger.warn(message);
+			return null;
+		}
+		throw new PortableObjectRejectedError(message);
+	}
+	const errors = attempts.flatMap((a) => a.type === "error" ? [a.error] : []);
+	return fail(errors.length === 1 ? errors[0] : new AggregateError(errors, "Failed to dereference " + lookupUrl + " through any of its gateways: " + requestUrls.map((r) => r.url).join(", ")));
+}
+async function checkPortableObjectId(document, expectedId, contextLoader) {
+	if (document == null || typeof document !== "object" || Array.isArray(document)) throw new PortableObjectRejection("it is not a single JSON object");
+	const expanded = await require_jsonld.expand(document, {
+		documentLoader: contextLoader,
+		keepFreeFloatingNodes: true
+	});
+	if (expanded.length !== 1) throw new PortableObjectRejection("it does not have exactly one top-level node");
+	const id = expanded[0]["@id"];
+	if (id == null) return;
+	if (typeof id !== "string") throw new PortableObjectRejection("it has an invalid @id");
+	let actualId;
+	try {
+		actualId = require_url.canonicalizePortableUri(id);
+	} catch (error) {
+		if (!(error instanceof TypeError)) throw error;
+		actualId = null;
+	}
+	if (actualId !== expectedId) throw new PortableObjectRejection("its @id ({objectId}) does not match the requested portable ID", { objectId: id });
+}
+//#endregion
+exports.PortableObjectRejectedError = PortableObjectRejectedError;
+exports.dereferencePortableIri = dereferencePortableIri;
+exports.getPortableGatewayCandidates = getPortableGatewayCandidates;
+exports.isPortableIri = isPortableIri;

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

@@ -0,0 +1,87 @@
+/// <reference lib="esnext.temporal" />
+import { n as DocumentLoader } from "../docloader-Dr8wEkif.cjs";
+import { t as PortableObjectVerifier } from "../portable-DxF2Ut-Z.cjs";
+import { Span, TracerProvider } from "@opentelemetry/api";
+
+//#region src/internal/portable-dereference.d.ts
+/**
+* Checks whether a URL is an FEP-ef61 portable ActivityPub IRI.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function isPortableIri(url: URL): boolean;
+/**
+* Picks the ordered list of FEP-ef61 gateways to fetch a portable IRI from.
+*
+* If `gateways` is given, it is used as is (even when empty), and `@gateway`
+* location hints in the IRI are ignored.  Otherwise, up to
+* {@link MAX_GATEWAY_HINTS} valid `@gateway` hints are used.  Duplicate
+* gateways are dropped in both cases.
+*
+* @throws {TypeError} If an explicit gateway is not an HTTP(S) origin.
+* @internal
+*/
+declare function getPortableGatewayCandidates(url: URL, gateways?: readonly (string | URL)[]): URL[];
+/**
+* Options for {@link dereferencePortableIri}.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+interface DereferencePortableIriOptions<T> {
+  documentLoader: DocumentLoader;
+  contextLoader: DocumentLoader;
+  tracerProvider: TracerProvider;
+  gateways?: readonly (string | URL)[];
+  verifyPortableObject?: PortableObjectVerifier;
+  suppressError?: boolean;
+  crossOrigin?: "ignore" | "throw" | "trust";
+  /**
+  * The signal for cancelling the dereference.  It is passed to the document
+  * loader for requests to gateways, and checked between attempts.  Requests
+  * for JSON-LD contexts and verification methods may not be cancelled.
+  */
+  signal?: AbortSignal;
+  parse: (document: unknown, options: {
+    contextLoader: DocumentLoader;
+    baseUrl: URL;
+  }) => Promise<T>;
+  span?: Span;
+}
+/**
+* The error thrown by {@link dereferencePortableIri} under
+* `crossOrigin: "throw"` when gateways returned objects but none of them
+* satisfied the identity and proof checks.
+*
+* @internal Not part of the public API contract.
+*/
+declare class PortableObjectRejectedError extends Error {
+  constructor(message: string);
+}
+/**
+* Dereferences an FEP-ef61 portable IRI through its gateways.
+*
+* Gateways are tried one by one until one of them returns a single-node
+* document whose `@id`, if any, canonically matches the requested IRI and
+* which passes `verifyPortableObject`.  When there is no gateway to try, the document
+* loader is asked for the portable IRI itself, and its result is validated
+* the same way.
+*
+* @returns The parsed object, or `null` if no valid object was retrieved and
+*          `suppressError` is set or the failure was a rejected object
+*          (unless `crossOrigin` is `"throw"`).
+* @throws {TypeError} If `gateways` has an invalid entry (always), if no
+*                     verifier is given, or if the IRI cannot be turned into
+*                     a gateway URL (unless `suppressError` is set).
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function dereferencePortableIri<T extends {
+  id: URL | null;
+}>(url: URL, options: DereferencePortableIriOptions<T>): Promise<T | null>;
+//#endregion
+export { DereferencePortableIriOptions, PortableObjectRejectedError, dereferencePortableIri, getPortableGatewayCandidates, isPortableIri };

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

@@ -0,0 +1,87 @@
+/// <reference lib="esnext.temporal" />
+import { n as DocumentLoader } from "../docloader-Dr8wEkif.js";
+import { t as PortableObjectVerifier } from "../portable-CduElToy.js";
+import { Span, TracerProvider } from "@opentelemetry/api";
+
+//#region src/internal/portable-dereference.d.ts
+/**
+* Checks whether a URL is an FEP-ef61 portable ActivityPub IRI.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function isPortableIri(url: URL): boolean;
+/**
+* Picks the ordered list of FEP-ef61 gateways to fetch a portable IRI from.
+*
+* If `gateways` is given, it is used as is (even when empty), and `@gateway`
+* location hints in the IRI are ignored.  Otherwise, up to
+* {@link MAX_GATEWAY_HINTS} valid `@gateway` hints are used.  Duplicate
+* gateways are dropped in both cases.
+*
+* @throws {TypeError} If an explicit gateway is not an HTTP(S) origin.
+* @internal
+*/
+declare function getPortableGatewayCandidates(url: URL, gateways?: readonly (string | URL)[]): URL[];
+/**
+* Options for {@link dereferencePortableIri}.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+interface DereferencePortableIriOptions<T> {
+  documentLoader: DocumentLoader;
+  contextLoader: DocumentLoader;
+  tracerProvider: TracerProvider;
+  gateways?: readonly (string | URL)[];
+  verifyPortableObject?: PortableObjectVerifier;
+  suppressError?: boolean;
+  crossOrigin?: "ignore" | "throw" | "trust";
+  /**
+  * The signal for cancelling the dereference.  It is passed to the document
+  * loader for requests to gateways, and checked between attempts.  Requests
+  * for JSON-LD contexts and verification methods may not be cancelled.
+  */
+  signal?: AbortSignal;
+  parse: (document: unknown, options: {
+    contextLoader: DocumentLoader;
+    baseUrl: URL;
+  }) => Promise<T>;
+  span?: Span;
+}
+/**
+* The error thrown by {@link dereferencePortableIri} under
+* `crossOrigin: "throw"` when gateways returned objects but none of them
+* satisfied the identity and proof checks.
+*
+* @internal Not part of the public API contract.
+*/
+declare class PortableObjectRejectedError extends Error {
+  constructor(message: string);
+}
+/**
+* Dereferences an FEP-ef61 portable IRI through its gateways.
+*
+* Gateways are tried one by one until one of them returns a single-node
+* document whose `@id`, if any, canonically matches the requested IRI and
+* which passes `verifyPortableObject`.  When there is no gateway to try, the document
+* loader is asked for the portable IRI itself, and its result is validated
+* the same way.
+*
+* @returns The parsed object, or `null` if no valid object was retrieved and
+*          `suppressError` is set or the failure was a rejected object
+*          (unless `crossOrigin` is `"throw"`).
+* @throws {TypeError} If `gateways` has an invalid entry (always), if no
+*                     verifier is given, or if the IRI cannot be turned into
+*                     a gateway URL (unless `suppressError` is set).
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function dereferencePortableIri<T extends {
+  id: URL | null;
+}>(url: URL, options: DereferencePortableIriOptions<T>): Promise<T | null>;
+//#endregion
+export { DereferencePortableIriOptions, PortableObjectRejectedError, dereferencePortableIri, getPortableGatewayCandidates, isPortableIri };