@fedify/vocab-runtime 2.4.0-dev.2056 → 2.4.0-dev.2065

package/dist/portable-comBI05Y.d.cts

@@ -0,0 +1,160 @@
+/// <reference lib="esnext.temporal" />
+import { n as DocumentLoader } from "./docloader-Dr8wEkif.cjs";
+import { TracerProvider } from "@opentelemetry/api";
+
+//#region src/portable.d.ts
+/**
+* Options passed to a {@link PortableObjectVerifier}.
+* @since 2.4.0
+*/
+interface PortableObjectVerifierOptions {
+  /**
+  * The document loader for fetching remote documents, such as verification
+  * methods that are not `did:key` URLs.
+  */
+  readonly documentLoader?: DocumentLoader;
+  /**
+  * The document loader for fetching remote JSON-LD contexts.  During
+  * gateway dereferencing, this loader returns the same context documents
+  * that the vocabulary parser sees.
+  */
+  readonly contextLoader?: DocumentLoader;
+  /**
+  * The OpenTelemetry tracer provider.
+  */
+  readonly tracerProvider?: TracerProvider;
+  /**
+  * The URL the document was finally retrieved from, i.e., the `documentUrl`
+  * of the document loader's result, which may differ from the requested URL
+  * after redirects.  Trust decisions such as the [FEP-ef61] gateway trust
+  * policy for unsecured collections depend on it, so custom document loaders
+  * must report it truthfully.
+  *
+  * [FEP-ef61]: https://w3id.org/fep/ef61
+  * @since 2.4.0
+  */
+  readonly documentUrl?: URL;
+  /**
+  * The gateways that the caller explicitly passed to the accessor through
+  * its `gateways` option, in order.  It is `undefined` if the caller did not
+  * pass the option, and can be empty.
+  * @since 2.4.0
+  */
+  readonly gateways?: readonly URL[];
+  /**
+  * The gateways inferred from the reference, in order, when the caller did
+  * not pass the `gateways` option: the `@gateway` location hints of
+  * a portable IRI, the gateway named by an FEP-ef61 compatible identifier,
+  * or the WebFinger server of a portable actor.  They only tell where the
+  * document and related objects might be retrieved, and must not be
+  * trusted to act for the portable object's DID.
+  * @since 2.4.0
+  */
+  readonly gatewayHints?: readonly URL[];
+  /**
+  * The object whose property referred to the document, if the document was
+  * dereferenced through a property accessor.
+  * @since 2.4.0
+  */
+  readonly referrer?: PortableObjectReferrer;
+}
+/**
+* An object whose property referred to a portable object being verified.
+* Referrers form a chain: {@link PortableObjectReferrer.referrer} is the
+* object through which this referrer itself was obtained, and so on.
+* @since 2.4.0
+*/
+interface PortableObjectReferrer {
+  /**
+  * The referring vocabulary object.
+  */
+  readonly object: unknown;
+  /**
+  * The `@id` of the referring object, if any.
+  */
+  readonly id: URL | null;
+  /**
+  * The expanded URI of the property through which the referring object
+  * referred to the next object in the chain, e.g.,
+  * `https://www.w3.org/ns/activitystreams#outbox`.
+  */
+  readonly property: string;
+  /**
+  * How the referring object itself was accepted by a
+  * {@link PortableObjectVerifier} when it was dereferenced through gateways:
+  *
+  * - `"verified"`: accepted as verified, e.g., with a valid integrity proof.
+  * - `"unsecured"`: accepted without an integrity proof, e.g., as an
+  *   unsecured collection served by a trusted gateway.
+  *
+  * It is `undefined` if the referring object was not dereferenced through
+  * gateways, e.g., if it was embedded in another object or constructed by
+  * the application.
+  */
+  readonly acceptance?: "verified" | "unsecured";
+  /**
+  * The opaque collection context that a {@link PortableObjectVerifier}
+  * attached to the referring object when it accepted it.  See
+  * {@link PortableObjectVerification}.
+  */
+  readonly collectionContext?: unknown;
+  /**
+  * The referrer of the referring object, if any.
+  */
+  readonly referrer?: PortableObjectReferrer;
+  /**
+  * Whether the chain was cut off here because it was too long.  If `true`,
+  * the referring object may have a referrer which is not included.
+  */
+  readonly truncated?: boolean;
+}
+/**
+* The result of a {@link PortableObjectVerifier}.
+* @since 2.4.0
+*/
+type PortableObjectVerification = {
+  /** Whether the document is accepted. */readonly verified: false;
+} | {
+  /** Whether the document is accepted. */readonly verified: true;
+  /**
+  * Whether the document was accepted without an integrity proof, e.g., as
+  * an unsecured [FEP-ef61] collection served by a gateway that its owner
+  * lists.  Objects embedded in such a document are not trusted because of
+  * their origin; property accessors dereference and verify them one by
+  * one instead.
+  *
+  * [FEP-ef61]: https://w3id.org/fep/ef61
+  */
+  readonly unsecured?: boolean;
+  /**
+  * An opaque value that the verifier wants to receive again as
+  * {@link PortableObjectReferrer.collectionContext} when objects referred
+  * to by this document, such as collection pages, are verified.
+  */
+  readonly collectionContext?: unknown;
+};
+/**
+* A function that applies the [FEP-ef61] trust policy to a portable object
+* fetched through a gateway.
+*
+* It receives the fetched JSON-LD document as is, and resolves to an object
+* whose `verified` property tells whether the document is acceptable, e.g.,
+* whether it carries a valid [FEP-8b32] Object Integrity Proof made by the
+* DID in its portable ID.  `verifyPortableObject()` and
+* `verifyPortableObjectProof()` from `@fedify/fedify` satisfy this type, so
+* they can be passed as the `verifyPortableObject` option of generated
+* vocabulary accessors such as `Activity.getObject()`.
+*
+* [FEP-ef61]: https://w3id.org/fep/ef61
+* [FEP-8b32]: https://w3id.org/fep/8b32
+*
+* @param document The fetched JSON-LD document.
+* @param options Loaders, tracing options, and where the document came from.
+* @returns An object whose `verified` property is `true` if and only if the
+*          document satisfies the policy.  Other properties, such as
+*          a failure reason, are logged when verification fails.
+* @since 2.4.0
+*/
+type PortableObjectVerifier = (document: unknown, options: PortableObjectVerifierOptions) => Promise<PortableObjectVerification>;
+//#endregion
+export { PortableObjectVerifierOptions as i, PortableObjectVerification as n, PortableObjectVerifier as r, PortableObjectReferrer as t };

package/dist/tests/{body-wkL-XGhe.mjs → body-CNO0jMV8.mjs}

@@ -1,4 +1,4 @@
-import { t as FetchError } from "./request-Ytm0xyZH.mjs";
+import { t as FetchError } from "./request-dpFdQKXr.mjs";
 import { getLogger } from "@logtape/logtape";
 //#region src/body.ts
 /** Decoded JSON body limit: 16 MiB.  @internal */

package/dist/tests/{body-h9zUR79f.cjs → body-DXHOazEl.cjs}

@@ -1,4 +1,4 @@
-const require_request = require("./request-ClFs0ePp.cjs");
+const require_request = require("./request-BOLanqAd.cjs");
 let _logtape_logtape = require("@logtape/logtape");
 //#region src/body.ts
 /** Decoded JSON body limit: 16 MiB.  @internal */

package/dist/tests/body.test.cjs

@@ -1,4 +1,4 @@
-const require_body = require("./body-h9zUR79f.cjs");
+const require_body = require("./body-DXHOazEl.cjs");
 let node_assert_strict = require("node:assert/strict");
 let node_test = require("node:test");
 let node_zlib = require("node:zlib");

package/dist/tests/body.test.mjs

@@ -1,4 +1,4 @@
-import { r as readBoundedText, t as BodyTooLargeError } from "./body-wkL-XGhe.mjs";
+import { r as readBoundedText, t as BodyTooLargeError } from "./body-CNO0jMV8.mjs";
 import { deepStrictEqual, ok, rejects } from "node:assert/strict";
 import { test } from "node:test";
 import { gunzipSync, gzipSync } from "node:zlib";

package/dist/tests/decimal.test.cjs

@@ -1,5 +1,5 @@
 require("./url-BqlldzT8.cjs");
-require("./docloader-CBLgaVPd.cjs");
+require("./docloader-4Txefi7y.cjs");
 require("./key-8Qg2SbZi.cjs");
 require("./multibase-B5Mea7Ip.cjs");
 require("./digest-3FeH2Y-Q.cjs");

package/dist/tests/decimal.test.mjs

@@ -1,5 +1,5 @@
 import "./url-DgJM9WJn.mjs";
-import "./docloader-DMGssPEX.mjs";
+import "./docloader-C-nWtUWo.mjs";
 import "./key-C7MNhlkO.mjs";
 import "./multibase-BPnF_L4e.mjs";
 import "./digest-COC7xDiQ.mjs";

package/dist/tests/{docloader-CBLgaVPd.cjs → docloader-4Txefi7y.cjs}

@@ -1,5 +1,5 @@
-const require_request = require("./request-ClFs0ePp.cjs");
-const require_body = require("./body-h9zUR79f.cjs");
+const require_request = require("./request-BOLanqAd.cjs");
+const require_body = require("./body-DXHOazEl.cjs");
 const require_contexts = require("./contexts-Ch3v2Cgu.cjs");
 const require_link = require("./link-DlKm8bEr.cjs");
 const require_url = require("./url-BqlldzT8.cjs");

package/dist/tests/{docloader-DMGssPEX.mjs → docloader-C-nWtUWo.mjs}

@@ -1,5 +1,5 @@
-import { a as name, i as logRequest, n as createActivityPubRequest, o as version, t as FetchError } from "./request-Ytm0xyZH.mjs";
-import { n as MAX_BODY_SIZE, r as readBoundedText, t as BodyTooLargeError } from "./body-wkL-XGhe.mjs";
+import { a as name, i as logRequest, n as createActivityPubRequest, o as version, t as FetchError } from "./request-dpFdQKXr.mjs";
+import { n as MAX_BODY_SIZE, r as readBoundedText, t as BodyTooLargeError } from "./body-CNO0jMV8.mjs";
 import { t as preloadedContexts } from "./contexts-BBX_qhBL.mjs";
 import { t as HttpHeaderLink } from "./link-Cevmc87v.mjs";
 import { t as UrlError, v as validatePublicUrl } from "./url-DgJM9WJn.mjs";

package/dist/tests/docloader.test.cjs

@@ -1,8 +1,8 @@
 const require_rolldown_runtime = require("./rolldown-runtime-emK7D4bc.cjs");
-const require_request = require("./request-ClFs0ePp.cjs");
+const require_request = require("./request-BOLanqAd.cjs");
 const require_contexts = require("./contexts-Ch3v2Cgu.cjs");
 const require_url = require("./url-BqlldzT8.cjs");
-const require_docloader = require("./docloader-CBLgaVPd.cjs");
+const require_docloader = require("./docloader-4Txefi7y.cjs");
 let node_test = require("node:test");
 let node_zlib = require("node:zlib");
 let node_assert = require("node:assert");

package/dist/tests/docloader.test.mjs

@@ -1,7 +1,7 @@
-import { t as FetchError } from "./request-Ytm0xyZH.mjs";
+import { t as FetchError } from "./request-dpFdQKXr.mjs";
 import { n as cid_v1_default, t as preloadedContexts } from "./contexts-BBX_qhBL.mjs";
 import { t as UrlError } from "./url-DgJM9WJn.mjs";
-import { n as getRemoteDocument, t as getDocumentLoader } from "./docloader-DMGssPEX.mjs";
+import { n as getRemoteDocument, t as getDocumentLoader } from "./docloader-C-nWtUWo.mjs";
 import { test } from "node:test";
 import { gzipSync } from "node:zlib";
 import { deepStrictEqual, ok, rejects } from "node:assert";

package/dist/tests/internal/portable-dereference.test.cjs

@@ -1,3 +1,4 @@
+const require_contexts = require("../contexts-Ch3v2Cgu.cjs");
 const require_url = require("../url-BqlldzT8.cjs");
 require("../jsonld-CmDhHNTx.cjs");
 let node_assert_strict = require("node:assert/strict");
@@ -17,6 +18,12 @@ const logger = (0, _logtape_logtape.getLogger)([
 */
 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.
 *
@@ -76,6 +83,60 @@ function parseGatewayOrigin(gateway) {
 	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.
+*
+* @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 createSnapshotContextLoader(contextLoader) {
+	for (let wrapped = snapshotLoaders.get(contextLoader); wrapped?.released; wrapped = snapshotLoaders.get(contextLoader)) contextLoader = wrapped.base;
+	const cache = /* @__PURE__ */ new Map();
+	let released = false;
+	const release = () => {
+		released = true;
+		state.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);
+	};
+	const state = {
+		base: contextLoader,
+		released: false
+	};
+	snapshotLoaders.set(loader, state);
+	return {
+		loader,
+		release
+	};
+}
+const snapshotLoaders = /* @__PURE__ */ new WeakMap();
 //#endregion
 //#region src/internal/portable-dereference.test.ts
 const hrefs = (urls) => urls.map((url) => url.href);
@@ -120,4 +181,30 @@ const hrefs = (urls) => urls.map((url) => url.href);
 		4
 	].map((i) => `https://g${i}.example/`));
 });
+(0, node_test.test)("createSnapshotContextLoader() does not nest released snapshots", async () => {
+	const calls = [];
+	const base = (url) => {
+		calls.push(url);
+		return Promise.resolve({
+			contextUrl: null,
+			documentUrl: url,
+			document: { "@context": {} }
+		});
+	};
+	let loader = base;
+	for (let i = 0; i < 1e4; i++) {
+		const snapshot = createSnapshotContextLoader(loader);
+		snapshot.release();
+		loader = snapshot.loader;
+	}
+	await loader("https://example.com/context");
+	(0, node_assert_strict.deepStrictEqual)(calls, ["https://example.com/context"]);
+	const outer = createSnapshotContextLoader(base);
+	await outer.loader("https://example.com/context");
+	const inner = createSnapshotContextLoader(outer.loader);
+	await inner.loader("https://example.com/context");
+	(0, node_assert_strict.deepStrictEqual)(calls.length, 2);
+	inner.release();
+	outer.release();
+});
 //#endregion

package/dist/tests/internal/portable-dereference.test.mjs

@@ -1,3 +1,4 @@
+import { t as preloadedContexts } from "../contexts-BBX_qhBL.mjs";
 import { a as formatIri, m as parseIri } from "../url-DgJM9WJn.mjs";
 import "../jsonld-DweIJ07b.mjs";
 import { deepStrictEqual, ok, throws } from "node:assert/strict";
@@ -17,6 +18,12 @@ const logger = getLogger([
 */
 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.
 *
@@ -76,6 +83,60 @@ function parseGatewayOrigin(gateway) {
 	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.
+*
+* @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 createSnapshotContextLoader(contextLoader) {
+	for (let wrapped = snapshotLoaders.get(contextLoader); wrapped?.released; wrapped = snapshotLoaders.get(contextLoader)) contextLoader = wrapped.base;
+	const cache = /* @__PURE__ */ new Map();
+	let released = false;
+	const release = () => {
+		released = true;
+		state.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(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);
+	};
+	const state = {
+		base: contextLoader,
+		released: false
+	};
+	snapshotLoaders.set(loader, state);
+	return {
+		loader,
+		release
+	};
+}
+const snapshotLoaders = /* @__PURE__ */ new WeakMap();
 //#endregion
 //#region src/internal/portable-dereference.test.ts
 const hrefs = (urls) => urls.map((url) => url.href);
@@ -120,5 +181,31 @@ test("getPortableGatewayCandidates() reads @gateway hints", () => {
 		4
 	].map((i) => `https://g${i}.example/`));
 });
+test("createSnapshotContextLoader() does not nest released snapshots", async () => {
+	const calls = [];
+	const base = (url) => {
+		calls.push(url);
+		return Promise.resolve({
+			contextUrl: null,
+			documentUrl: url,
+			document: { "@context": {} }
+		});
+	};
+	let loader = base;
+	for (let i = 0; i < 1e4; i++) {
+		const snapshot = createSnapshotContextLoader(loader);
+		snapshot.release();
+		loader = snapshot.loader;
+	}
+	await loader("https://example.com/context");
+	deepStrictEqual(calls, ["https://example.com/context"]);
+	const outer = createSnapshotContextLoader(base);
+	await outer.loader("https://example.com/context");
+	const inner = createSnapshotContextLoader(outer.loader);
+	await inner.loader("https://example.com/context");
+	deepStrictEqual(calls.length, 2);
+	inner.release();
+	outer.release();
+});
 //#endregion
 export {};

package/dist/tests/{request-ClFs0ePp.cjs → request-BOLanqAd.cjs}

@@ -3,7 +3,7 @@ let node_process = require("node:process");
 node_process = require_rolldown_runtime.__toESM(node_process, 1);
 //#region deno.json
 var name = "@fedify/vocab-runtime";
-var version = "2.4.0-dev.2056+e6394f3b";
+var version = "2.4.0-dev.2065+b09fdd33";
 //#endregion
 //#region src/request.ts
 /**

package/dist/tests/{request-Ytm0xyZH.mjs → request-dpFdQKXr.mjs}

@@ -1,7 +1,7 @@
 import process from "node:process";
 //#region deno.json
 var name = "@fedify/vocab-runtime";
-var version = "2.4.0-dev.2056+e6394f3b";
+var version = "2.4.0-dev.2065+b09fdd33";
 //#endregion
 //#region src/request.ts
 /**

package/dist/tests/request.test.cjs

@@ -1,5 +1,5 @@
 const require_rolldown_runtime = require("./rolldown-runtime-emK7D4bc.cjs");
-const require_request = require("./request-ClFs0ePp.cjs");
+const require_request = require("./request-BOLanqAd.cjs");
 let node_test = require("node:test");
 let node_process = require("node:process");
 node_process = require_rolldown_runtime.__toESM(node_process, 1);

package/dist/tests/request.test.mjs

@@ -1,4 +1,4 @@
-import { n as createActivityPubRequest, o as version, r as getUserAgent } from "./request-Ytm0xyZH.mjs";
+import { n as createActivityPubRequest, o as version, r as getUserAgent } from "./request-dpFdQKXr.mjs";
 import { test } from "node:test";
 import process from "node:process";
 import { deepStrictEqual } from "node:assert";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/vocab-runtime",
-  "version": "2.4.0-dev.2056+e6394f3b",
+  "version": "2.4.0-dev.2065+b09fdd33",
   "homepage": "https://fedify.dev/",
   "repository": {
     "type": "git",

package/src/internal/portable-dereference.test.ts

@@ -1,7 +1,9 @@
 import { deepStrictEqual, ok, throws } from "node:assert/strict";
 import { test } from "node:test";
+import type { DocumentLoader } from "../docloader.ts";
 import { parseIri } from "../url.ts";
 import {
+  createSnapshotContextLoader,
   getPortableGatewayCandidates,
   isPortableIri,
 } from "./portable-dereference.ts";
@@ -72,3 +74,33 @@ test("getPortableGatewayCandidates() reads @gateway hints", () => {
     [0, 1, 2, 3, 4].map((i) => `https://g${i}.example/`),
   );
 });
+
+test("createSnapshotContextLoader() does not nest released snapshots", async () => {
+  const calls: string[] = [];
+  const base: DocumentLoader = (url) => {
+    calls.push(url);
+    return Promise.resolve({
+      contextUrl: null,
+      documentUrl: url,
+      document: { "@context": {} },
+    });
+  };
+  let loader = base;
+  for (let i = 0; i < 10000; i++) {
+    const snapshot = createSnapshotContextLoader(loader);
+    snapshot.release();
+    loader = snapshot.loader;
+  }
+  // A deep chain of wrappers would overflow the stack here:
+  await loader("https://example.com/context");
+  deepStrictEqual(calls, ["https://example.com/context"]);
+
+  // Snapshots still in use are kept, so a nested snapshot sees their cache:
+  const outer = createSnapshotContextLoader(base);
+  await outer.loader("https://example.com/context");
+  const inner = createSnapshotContextLoader(outer.loader);
+  await inner.loader("https://example.com/context");
+  deepStrictEqual(calls.length, 2);
+  inner.release();
+  outer.release();
+});