@fedify/vocab-tools 2.4.0-pr.936.41 → 2.4.0

package/dist/mod.js

@@ -7,7 +7,7 @@ import { parse } from "yaml";
 import { pascalCase } from "es-toolkit";
 //#region deno.json
 var name = "@fedify/vocab-tools";
-var version = "2.4.0-pr.936.41+59c7432c";
+var version = "2.4.0";
 //#endregion
 //#region src/type.ts
 const HEURISTICS_CONTEXTS = [
@@ -185,7 +185,8 @@ const scalarTypes = {
 		dataCheck(v) {
 			return `typeof ${v} === "object" && "@language" in ${v} && "@value" in ${v}
         && typeof ${v}["@language"] === "string"
-        && typeof ${v}["@value"] === "string"`;
+        && typeof ${v}["@value"] === "string"
+        && isValidLanguageTag(${v}["@language"])`;
 		},
 		decoder(v) {
 			return `new LanguageString(${v}["@value"], ${v}["@language"])`;
@@ -316,13 +317,14 @@ const scalarTypes = {
 			return `formatIri(${v})`;
 		},
 		dataCheck(v) {
-			return `typeof ${v} === "object" && "@value" in ${v}
-        && typeof ${v}["@value"] === "string"
-        && ${v}["@value"] !== "" && ${v}["@value"] !== "/"`;
+			return `typeof ${v} === "object" &&
+      ((typeof ${v}["@id"] === "string" && canDecodeIri(${v}["@id"])) ||
+       (typeof ${v}["@value"] === "string" && canDecodeIri(${v}["@value"])))`;
 		},
 		decoder(v) {
-			return `parseIri(${v}["@value"])`;
-		}
+			return `decodeIri(typeof ${v}["@id"] === "string" ? ${v}["@id"] : ${v}["@value"])`;
+		},
+		skipUnparsable: true
 	},
 	"fedify:gatewayUrl": {
 		name: "URL",
@@ -330,10 +332,10 @@ const scalarTypes = {
 			return `${v} instanceof URL && isGatewayUrl(${v})`;
 		},
 		encoder(v) {
-			return `{ "@id": formatIri(${v}) }`;
+			return `{ "@id": ${v}.origin }`;
 		},
 		compactEncoder(v) {
-			return `formatIri(${v})`;
+			return `${v}.origin`;
 		},
 		dataCheck(v) {
 			return `${v} != null && typeof ${v} === "object" &&
@@ -556,6 +558,9 @@ function getDecoder(typeUri, types, variable, optionsVariable, baseUrlVariable)
     )`;
 	throw new Error(`Unknown type: ${typeUri}`);
 }
+function skipsUnparsable(typeUri) {
+	return scalarTypes[typeUri]?.skipUnparsable ?? false;
+}
 function getDataCheck(typeUri, types, variable) {
 	if (typeUri in scalarTypes) return scalarTypes[typeUri].dataCheck(variable);
 	if (typeUri in types) {
@@ -735,6 +740,7 @@ function* generatePreprocessorBlock(property, rangeTypeName, variable, baseUrlEx
             documentLoader: options.documentLoader,
             contextLoader: options.contextLoader,
             tracerProvider: options.tracerProvider,
+            verifyPortableObject: options.verifyPortableObject,
             baseUrl: ${baseUrlExpr},
           });
           if (_result instanceof Error) throw _result;
@@ -783,6 +789,10 @@ async function* generateEncoder(typeUri, types) {
       ...options,
       contextLoader: options.contextLoader ?? getDocumentLoader(),
     };
+    // Joins the enclosing frame's signed-value scope, or starts one when this
+    // frame is the outermost.  Only the owning frame puts retained signed
+    // child documents back in place of their placeholders.
+    const signedValues = enterSignedValueScope(options);
   `;
 	if (isCompactableType(typeUri, types)) {
 		yield `
@@ -813,9 +823,13 @@ async function* generateEncoder(typeUri, types) {
       for (const v of this.${await getFieldName(property.uri)}) {
         const item = (
       `;
-			if (!areAllScalarTypes(property.range, types)) yield "v instanceof URL ? formatIri(v) : ";
+			if (!areAllScalarTypes(property.range, types)) {
+				yield "retainedSignedValueRef(v, signedValues.scope) ?? (";
+				yield "v instanceof URL ? formatIri(v) : ";
+			}
 			const encoders = getEncoders(property.range, types, "v", "options", true);
 			for (const code of encoders) yield code;
+			if (!areAllScalarTypes(property.range, types)) yield ")";
 			yield `
         );
         compactItems.push(item);
@@ -846,7 +860,9 @@ async function* generateEncoder(typeUri, types) {
       ${type.typeless ? "" : `result["type"] = ${JSON.stringify(type.compactName ?? type.uri)};`}
       if (this.id != null) result["id"] = formatIri(this.id);
       result["@context"] = ${JSON.stringify(type.defaultContext)};
-      return result;
+      return signedValues.owner
+        ? resolveSignedValues(result, signedValues.scope)
+        : result;
     }
     `;
 	}
@@ -870,12 +886,21 @@ async function* generateEncoder(typeUri, types) {
 		yield `
     array = [];
     for (const v of this.${await getFieldName(property.uri)}) {
-      const element = (
+      let element = (
     `;
-		if (!areAllScalarTypes(property.range, types)) yield "v instanceof URL ? { \"@id\": formatIri(v) } : ";
+		if (!areAllScalarTypes(property.range, types)) {
+			yield "retainedSignedValueRef(v, signedValues.scope) ?? (";
+			yield "v instanceof URL ? { \"@id\": formatIri(v) } : ";
+		}
 		for (const code of getEncoders(property.range, types, "v", "options")) yield code;
+		if (!areAllScalarTypes(property.range, types)) yield ")";
 		yield `
       );
+      if (Array.isArray(element)) {
+        if (element.length < 1) continue;
+        if (element.length == 1) element = element[0];
+      }
+      if (typeof element === "undefined") continue;
     `;
 		if (isNonFunctionalProperty(property) && property.container === "graph") yield `array.push({ "@graph": element });`;
 		else yield `array.push(element);`;
@@ -903,16 +928,35 @@ async function* generateEncoder(typeUri, types) {
     if (options.format === "expand") {
       return await jsonld.expand(
         values,
-        { documentLoader: options.contextLoader },
+        {
+          documentLoader: options.contextLoader,
+          keepFreeFloatingNodes: true,
+        },
       );
     }
-    const docContext = options.context ??
+    let docContext: Parameters<typeof jsonld.compact>[1] = options.context ??
       ${JSON.stringify(type.defaultContext)};
-    const compacted = await jsonld.compact(
+    let compacted = await jsonld.compact(
       values,
       docContext,
       { documentLoader: options.contextLoader },
     );
+  `;
+	if (Object.values(types).some((t) => t.properties.some((p) => p.extraContext != null))) yield `
+    if (options.context == null) {
+      const currentContexts = Array.isArray(docContext) ? docContext : [docContext];
+      const additionalContexts = getExtraContexts(compacted).filter(
+        context => !currentContexts.includes(context)
+      );
+      if (additionalContexts.length > 0) {
+        docContext = [...currentContexts, ...additionalContexts];
+        compacted = await jsonld.compact(values, docContext, {
+          documentLoader: options.contextLoader,
+        });
+      }
+    }
+    `;
+	yield `
     if (docContext != null) {
       // Embed context
   `;
@@ -936,12 +980,14 @@ async function* generateEncoder(typeUri, types) {
 	}
 	yield `
     }
-    return compacted;
+    return signedValues.owner
+      ? resolveSignedValues(compacted, signedValues.scope)
+      : compacted;
   }
 
   protected ${emitOverride$1(typeUri, types)} isCompactable(): boolean {
 `;
-	for (const property of type.properties) if (!property.range.every((r) => isCompactableType(r, types))) yield `
+	for (const property of type.properties) if (property.extraContext != null || !property.range.every((r) => isCompactableType(r, types))) yield `
       if (
         this.${await getFieldName(property.uri)} != null &&
         this.${await getFieldName(property.uri)}.length > 0
@@ -963,6 +1009,10 @@ async function* generateDecoder(typeUri, types, moduleVarNames) {
    *                - \`contextLoader\`: The loader for remote JSON-LD contexts.
    *                - \`tracerProvider\`: The OpenTelemetry tracer provider to use.
    *                  If omitted, the global tracer provider is used.
+   *                - \`verifyPortableObject\`: The default FEP-ef61 portable
+   *                  object verifier for the property accessors of the
+   *                  returned object and the objects obtained from it.  It
+   *                  does not verify the given \`json\` itself.
    * @returns The object of this type.
    * @throws {TypeError} If the given \`json\` is invalid.
    */
@@ -972,6 +1022,7 @@ async function* generateDecoder(typeUri, types, moduleVarNames) {
       documentLoader?: DocumentLoader,
       contextLoader?: DocumentLoader,
       tracerProvider?: TracerProvider,
+      verifyPortableObject?: PortableObjectVerifier,
       baseUrl?: URL,
     } = {},
   ): Promise<${type.name}> {
@@ -1010,6 +1061,7 @@ async function* generateDecoder(typeUri, types, moduleVarNames) {
       documentLoader?: DocumentLoader,
       contextLoader?: DocumentLoader,
       tracerProvider?: TracerProvider,
+      verifyPortableObject?: PortableObjectVerifier,
       baseUrl?: URL,
     } = {},
   ): Promise<${type.name}> {
@@ -1026,7 +1078,17 @@ async function* generateDecoder(typeUri, types, moduleVarNames) {
     // deno-lint-ignore no-explicit-any
     let values: Record<string, any[]> & { "@id"?: string };
     let expanded: unknown[];
-    if (globalThis.Object.keys(json).length == 0) {
+    if (
+      "_fromSubclass" in options &&
+      options._fromSubclass &&
+      typeof json === "object" &&
+      !Array.isArray(json)
+    ) {
+      values =
+        // deno-lint-ignore no-explicit-any
+        json as (Record<string, any[]> & { "@id"?: string });
+      expanded = [values];
+    } else if (globalThis.Object.keys(json).length == 0) {
       values = {};
       expanded = [values];
     } else {
@@ -1083,8 +1145,9 @@ async function* generateDecoder(typeUri, types, moduleVarNames) {
     );
     `;
 	else yield `
-    delete values["@type"];
-    const instance = await super.fromJsonLd(values, {
+    const superValues = structuredClone(values);
+    delete superValues["@type"];
+    const instance = await super.fromJsonLd(superValues, {
       ...options,
       // @ts-ignore: an internal option
       _fromSubclass: true,
@@ -1093,25 +1156,35 @@ async function* generateDecoder(typeUri, types, moduleVarNames) {
       throw new TypeError("Unexpected type: " + instance.constructor.name);
     }
     `;
+	yield `
+    let shouldCacheJsonLd = instance._shouldCacheJsonLd;
+  `;
 	for (const property of type.properties) {
 		const variable = await getFieldName(property.uri, "");
 		yield await generateField(property, types, "const ");
 		const arrayVariable = `${variable}__array`;
 		yield `
-    let ${arrayVariable} = values[${JSON.stringify(property.uri)}];
+    let ${arrayVariable} = ${property.uri === "https://w3id.org/fep/ef61/gateways" ? "getPortableActorGateways(values) as typeof values[string]" : `values[${JSON.stringify(property.uri)}]`};
     `;
 		if (property.functional && property.redundantProperties != null) for (const prop of property.redundantProperties) yield `
         if (${arrayVariable} == null || ${arrayVariable}.length < 1) {
           ${arrayVariable} = values[${JSON.stringify(prop.uri)}];
         }
         `;
+		let itemsExpression = `${arrayVariable}.length === 1 && "@list" in ${arrayVariable}[0]
+        ? ${arrayVariable}[0]["@list"]
+        : ${arrayVariable}`;
+		if (isNonFunctionalProperty(property) && property.container === "graph") itemsExpression = `(${itemsExpression}).flatMap((item: unknown) =>
+          item != null && typeof item === "object" && "@graph" in item &&
+            Array.isArray((item as { "@graph": unknown })["@graph"])
+            ? (item as { "@graph": unknown[] })["@graph"]
+            : [item]
+        )`;
 		yield `
     for (
       const v of ${arrayVariable} == null
         ? []
-        : ${arrayVariable}.length === 1 && "@list" in ${arrayVariable}[0]
-        ? ${arrayVariable}[0]["@list"]
-        : ${arrayVariable}
+        : ${itemsExpression}
     ) {
       if (v == null) continue;
     `;
@@ -1125,29 +1198,47 @@ async function* generateDecoder(typeUri, types, moduleVarNames) {
         continue;
       }
       `;
-		if (property.range.length == 1) yield `
-      const decoded = ${getDecoder(property.range[0], types, "v", "options", propertyBaseUrl)};
-      if (typeof decoded === "undefined") continue;
-      ${variable}.push(decoded);`;
-		else {
-			yield `
+		yield `
       const decoded =
-      `;
+    `;
+		const lenient = property.range.length == 1 && skipsUnparsable(property.range[0]);
+		if (property.range.length == 1) {
+			if (lenient) {
+				yield getDataCheck(property.range[0], types, "v");
+				yield " ? ";
+			}
+			yield getDecoder(property.range[0], types, "v", "options", propertyBaseUrl);
+			if (lenient) yield " : undefined";
+		} else {
 			const decoders = getDecoders(property.range, types, "v", "options", propertyBaseUrl);
 			for (const code of decoders) yield code;
-			yield `
+		}
+		yield `
       ;
-      if (typeof decoded === "undefined") continue;
+    `;
+		yield `
+      if (typeof decoded === "undefined") {
+        shouldCacheJsonLd = false;
+        continue;
+      }
+    `;
+		yield `
+      if (!this._shouldCacheDecodedJsonLd(decoded)) {
+        shouldCacheJsonLd = false;
+      }
       ${variable}.push(decoded);
-      `;
-		}
+    `;
 		yield `
     }
     instance.${await getFieldName(property.uri)} = ${variable};
     `;
 	}
 	yield `
-    if (!("_fromSubclass" in options) || !options._fromSubclass) {
+    instance._shouldCacheJsonLd = shouldCacheJsonLd;
+    if (
+      shouldCacheJsonLd &&
+      (!("_fromSubclass" in options) || !options._fromSubclass)
+    ) {
       try {
         if (cacheJsonLd != null && cacheJsonLd !== expanded) {
           const compactArray = Array.isArray(json) && json.length === 1;
@@ -1213,6 +1304,7 @@ async function* generateConstructor(typeUri, types) {
       documentLoader?: DocumentLoader,
       contextLoader?: DocumentLoader,
       tracerProvider?: TracerProvider,
+      verifyPortableObject?: PortableObjectVerifier,
     } = {},
   ) {
   `;
@@ -1220,6 +1312,7 @@ async function* generateConstructor(typeUri, types) {
     this.#documentLoader = options.documentLoader;
     this.#contextLoader = options.contextLoader;
     this.#tracerProvider = options.tracerProvider;
+    this.#verifyPortableObject = options.verifyPortableObject;
     const baseUrl = (options as { baseUrl?: URL }).baseUrl;
     this.#_baseUrl = baseUrl == null ? undefined : new URL(baseUrl.href);
     if ("$warning" in options) {
@@ -1314,6 +1407,13 @@ async function* generateCloner(typeUri, types) {
 	yield `
   /**
    * Clones this instance, optionally updating it with the given values.
+   *
+   * A clone never inherits a signed JSON-LD representation retained by
+   * \`signObject()\`: the clone may differ from the document that the proof
+   * covers, so embedding the original secured JSON in a parent document
+   * would be wrong.  Sign the clone again if it has to be embedded as a
+   * secured child.
+   *
    * @param values The values to update the clone with.
    * @param options The options to use for cloning.
    * @returns The cloned instance.
@@ -1327,6 +1427,7 @@ async function* generateCloner(typeUri, types) {
     options: {
       documentLoader?: DocumentLoader,
       contextLoader?: DocumentLoader,
+      verifyPortableObject?: PortableObjectVerifier,
     } = {}
   ): ${type.name} {
     if (this._warning != null) {
@@ -1344,6 +1445,7 @@ async function* generateCloner(typeUri, types) {
       { id: values.id ?? this.id },
       options
     );
+    copyPortableProvenance(this, clone);
     `;
 	else yield `const clone = super.clone(values, options) as unknown as ${type.name};`;
 	for (const property of type.properties) {
@@ -1439,12 +1541,12 @@ async function* generateInspector(typeUri, types) {
         [Symbol.for("Deno.customInspect")]: (
           inspect: typeof Deno.inspect,
           options: Deno.InspectOptions,
-        ): string => "URL " + inspect(this.id!.href, options),
+        ): string => "URL " + inspect(inspectIri(this.id!), options),
         [Symbol.for("nodejs.util.inspect.custom")]: (
           _depth: number,
           options: unknown,
           inspect: (value: unknown, options: unknown) => string,
-        ): string => "URL " + inspect(this.id!.href, options),
+        ): string => "URL " + inspect(inspectIri(this.id!), options),
       };
     }
     `;
@@ -1460,12 +1562,12 @@ async function* generateInspector(typeUri, types) {
               [Symbol.for("Deno.customInspect")]: (
                 inspect: typeof Deno.inspect,
                 options: Deno.InspectOptions,
-              ): string => "URL " + inspect(v.href, options),
+              ): string => "URL " + inspect(inspectIri(v), options),
               [Symbol.for("nodejs.util.inspect.custom")]: (
                 _depth: number,
                 options: unknown,
                 inspect: (value: unknown, options: unknown) => string,
-              ): string => "URL " + inspect(v.href, options),
+              ): string => "URL " + inspect(inspectIri(v), options),
             }
           : v);
     `;
@@ -1535,6 +1637,7 @@ function emitOverride(typeUri, types, property) {
 }
 async function* generateProperty(type, property, types, moduleVarNames) {
 	const override = emitOverride(type.uri, types, property);
+	const trustOwner = type.trustEmbeddedObjects === false ? "null" : "this.id";
 	const doc = `\n/** ${property.description.replaceAll("\n", "\n * ")}\n */\n`;
 	const cachedPropertyBaseUrl = `(options as { baseUrl?: URL }).baseUrl ??
                 this._baseUrl ??
@@ -1575,6 +1678,9 @@ async function* generateProperty(type, property, types, moduleVarNames) {
         suppressError?: boolean,
         tracerProvider?: TracerProvider,
         crossOrigin?: "ignore" | "throw" | "trust";
+        gateways?: readonly (string | URL)[];
+        verifyPortableObject?: PortableObjectVerifier;
+        inheritPortableObjectVerifier?: boolean;
       } = {},
     ): Promise<${getTypeNames(property.range, types)} | null> {
       const documentLoader =
@@ -1587,11 +1693,96 @@ async function* generateProperty(type, property, types, moduleVarNames) {
         ${JSON.stringify(name)},
         ${JSON.stringify(version)},
       );
+      // The fetched object uses the verifier given to this call (which falls
+      // back to the parent's own default) for its accessors by default,
+      // unless the call keeps its verifier to itself:
+      const childVerifier = options.inheritPortableObjectVerifier === false
+        ? this._verifyPortableObject
+        : options.verifyPortableObject;
       return await tracer.startActiveSpan("activitypub.lookup_object", async (span) => {
+        const dereferencePortable = async (
+          portableUrl: URL,
+          extra: {
+            inferredGateways?: readonly URL[];
+            response?: RemoteDocument;
+            contextLoader?: DocumentLoader;
+          } = {},
+        ) => {
+          try {
+            const obj = await dereferencePortableIri(portableUrl, {
+              documentLoader,
+              contextLoader: extra.contextLoader ?? contextLoader,
+              tracerProvider,
+              gateways: options.gateways,
+              inferredGateways: extra.inferredGateways,
+              response: extra.response,
+              verifyPortableObject: options.verifyPortableObject,
+              referrer: {
+                object: this,
+                property: ${JSON.stringify(property.uri)},
+              },
+              suppressError: options.suppressError,
+              crossOrigin: options.crossOrigin,
+              span,
+              parse: (document, parseOptions) =>
+                this.#${property.singularName}_fromJsonLd(document, {
+                  documentLoader,
+                  contextLoader: parseOptions.contextLoader,
+                  tracerProvider,
+                  verifyPortableObject: childVerifier,
+                  baseUrl: parseOptions.baseUrl,
+                }),
+            });
+            if (obj != null) {
+              span.setAttribute(
+                "activitypub.object.id",
+                (obj.id ?? portableUrl).href,
+              );
+              span.setAttribute(
+                "activitypub.object.type",
+                // @ts-ignore: obj.constructor always has a typeId.
+                obj.constructor.typeId.href
+              );
+            }
+            return obj;
+          } catch (e) {
+            span.setStatus({
+              code: SpanStatusCode.ERROR,
+              message: String(e),
+            });
+            throw e;
+          } finally {
+            span.end();
+          }
+        };
+        if (isPortableIri(url)) {
+          // A reference in a portable actor's own document, e.g., its outbox,
+          // has no location hints, so the actor's gateways are used instead:
+          return await dereferencePortable(
+            url,
+            options.gateways == null
+              ? { inferredGateways: getReferrerGateways(this, url) }
+              : {},
+          );
+        }
         const lookupUrl = formatIri(url);
+        const portableMode = isPortableMode(this, options);
+        if (portableMode) {
+          const compatible = parseCompatibleEf61Reference(url);
+          if (compatible === null) {
+            span.end();
+            return rejectMalformedCompatibleReference(lookupUrl, options);
+          } else if (compatible != null) {
+            return await dereferencePortable(compatible.id, {
+              inferredGateways: [compatible.gateway],
+            });
+          }
+        }
         let fetchResult: RemoteDocument;
         try {
-          fetchResult = await documentLoader(lookupUrl);
+          fetchResult = await documentLoader(lookupUrl, {
+            suppressError: options.suppressError,
+          });
         } catch (error) {
           span.setStatus({
             code: SpanStatusCode.ERROR,
@@ -1599,7 +1790,7 @@ async function* generateProperty(type, property, types, moduleVarNames) {
           });
           span.end();
           if (options.suppressError) {
-            getLogger(["fedify", "vocab"]).error(
+            getLogger(["fedify", "vocab"]).warn(
               "Failed to fetch {url}: {error}",
               { error, url: lookupUrl }
             );
@@ -1608,52 +1799,96 @@ async function* generateProperty(type, property, types, moduleVarNames) {
           throw error;
         }
         const { document, documentUrl } = fetchResult;
-        const baseUrl = parseIri(documentUrl);
+        // In portable mode, the document may turn out to be a portable object,
+        // which has to be verified with the same context documents:
+        const snapshot = portableMode
+          ? createSnapshotContextLoader(contextLoader, options.suppressError)
+          : null;
+        const scopedContext = createScopedContextLoader(
+          snapshot?.loader ?? contextLoader,
+          snapshot == null && options.suppressError,
+        );
         try {
-          const obj = await this.#${property.singularName}_fromJsonLd(
-            document,
-            { documentLoader, contextLoader, tracerProvider, baseUrl }
-          );
-          if (obj?.id != null && !isTrustedIriOrigin(options, obj.id, baseUrl)) {
-            if (options.crossOrigin === "throw") {
-              throw new Error(
-                "The object's @id (" + obj.id.href + ") has a different origin " +
-                "than the document URL (" + baseUrl.href + "); refusing to return " +
-                "the object.  If you want to bypass this check and are aware of" +
-                'the security implications, set the crossOrigin option to "trust".'
+          let claim: PortableResponseClaim | null | undefined;
+          try {
+            const baseUrl = parseIri(documentUrl);
+            const obj = await this.#${property.singularName}_fromJsonLd(
+              document,
+              {
+                documentLoader,
+                contextLoader: scopedContext.loader,
+                tracerProvider,
+                verifyPortableObject: childVerifier,
+                baseUrl,
+              }
+            );
+            if (snapshot == null) {
+              markUnverifiedPortableClaim(obj, url, documentUrl);
+            } else {
+              claim = getPortableResponseClaim(documentUrl, obj.id);
+            }
+            if (claim === undefined) {
+              if (
+                obj?.id != null &&
+                !isTrustedIriOrigin(options, obj.id, baseUrl)
+              ) {
+                if (options.crossOrigin === "throw") {
+                  throw new Error(
+                    "The object's @id (" + obj.id.href + ") has a different origin " +
+                    "than the document URL (" + baseUrl.href + "); refusing to return " +
+                    "the object.  If you want to bypass this check and are aware of" +
+                    'the security implications, set the crossOrigin option to "trust".'
+                  );
+                }
+                getLogger(["fedify", "vocab"]).warn(
+                  "The object's @id ({objectId}) has a different origin than the document " +
+                  "URL ({documentUrl}); refusing to return the object.  If you want to " +
+                  "bypass this check and are aware of the security implications, " +
+                  'set the crossOrigin option to "trust".',
+                  { ...fetchResult, objectId: obj.id.href },
+                );
+                span.end();
+                return null;
+              }
+              span.setAttribute("activitypub.object.id", (obj.id ?? url).href);
+              span.setAttribute(
+                "activitypub.object.type",
+                // @ts-ignore: obj.constructor always has a typeId.
+                obj.constructor.typeId.href
               );
+              span.end();
+              return obj;
             }
-            getLogger(["fedify", "vocab"]).warn(
-              "The object's @id ({objectId}) has a different origin than the document " +
-              "URL ({documentUrl}); refusing to return the object.  If you want to " +
-              "bypass this check and are aware of the security implications, " +
-              'set the crossOrigin option to "trust".',
-              { ...fetchResult, objectId: obj.id.href },
-            );
-            return null;
+          } catch (e) {
+            if (options.suppressError) {
+              getLogger(["fedify", "vocab"]).warn(
+                "Failed to parse {url}: {error}",
+                { error: e, url: lookupUrl }
+              );
+              span.end();
+              return null;
+            }
+            span.setStatus({
+              code: SpanStatusCode.ERROR,
+              message: String(e),
+            });
+            span.end();
+            throw e;
           }
-          span.setAttribute("activitypub.object.id", (obj.id ?? url).href);
-          span.setAttribute(
-            "activitypub.object.type",
-            // @ts-ignore: obj.constructor always has a typeId.
-            obj.constructor.typeId.href
-          );
-          return obj;
-        } catch (e) {
-          if (options.suppressError) {
-            getLogger(["fedify", "vocab"]).error(
-              "Failed to parse {url}: {error}",
-              { error: e, url: lookupUrl }
-            );
-            return null;
+          // The document stands for a portable object, so it is verified as
+          // one instead of being trusted because of where it came from:
+          if (claim === null) {
+            span.end();
+            return rejectMalformedCompatibleReference(documentUrl, options);
           }
-          span.setStatus({
-            code: SpanStatusCode.ERROR,
-            message: String(e),
+          return await dereferencePortable(claim.id, {
+            inferredGateways: claim.inferredGateways,
+            response: fetchResult,
+            contextLoader: snapshot?.loader,
           });
-          throw e;
         } finally {
-          span.end();
+          scopedContext.release();
+          snapshot?.release();
         }
       });
     }
@@ -1664,6 +1899,7 @@ async function* generateProperty(type, property, types, moduleVarNames) {
         documentLoader?: DocumentLoader,
         contextLoader?: DocumentLoader,
         tracerProvider?: TracerProvider,
+        verifyPortableObject?: PortableObjectVerifier,
         baseUrl?: URL
       }
     ): Promise<${getTypeNames(property.range, types)}> {
@@ -1674,6 +1910,7 @@ async function* generateProperty(type, property, types, moduleVarNames) {
       const tracerProvider = options.tracerProvider ??
         this._tracerProvider ?? trace.getTracerProvider();
       const baseUrl = options.baseUrl;
+      const verifyPortableObject = options.verifyPortableObject;
     `;
 		if (property.preprocessors != null && property.preprocessors.length > 0) {
 			yield `
@@ -1693,6 +1930,7 @@ async function* generateProperty(type, property, types, moduleVarNames) {
                 documentLoader,
                 contextLoader,
                 tracerProvider,
+                verifyPortableObject,
                 baseUrl,
               });
               if (_result instanceof Error) throw _result;
@@ -1711,7 +1949,13 @@ async function* generateProperty(type, property, types, moduleVarNames) {
         try {
           return await ${types[range].name}.fromJsonLd(
             jsonLd,
-            { documentLoader, contextLoader, tracerProvider, baseUrl },
+            {
+              documentLoader,
+              contextLoader,
+              tracerProvider,
+              verifyPortableObject,
+              baseUrl,
+            },
           );
         } catch (e) {
           if (!(e instanceof TypeError)) throw e;
@@ -1753,6 +1997,21 @@ async function* generateProperty(type, property, types, moduleVarNames) {
           suppressError?: boolean,
           tracerProvider?: TracerProvider,
           crossOrigin?: "ignore" | "throw" | "trust";
+          gateways?: readonly (string | URL)[];
+          verifyPortableObject?: PortableObjectVerifier;
+          /**
+           * Whether objects that this call newly fetches use the
+           * \`verifyPortableObject\` option of this call as their default
+           * verifier.  Defaults to \`true\`.  If \`false\`, the option
+           * applies to this call only, and fetched objects use this object's
+           * own default verifier, if any, as their default instead.  Pass
+           * \`false\` for a temporary verifier, e.g., one that accepts
+           * everything.  Objects that were already cached in this object or
+           * embedded in it keep their defaults either way, and this option
+           * itself is not passed on.
+           * @since 2.4.0
+           */
+          inheritPortableObjectVerifier?: boolean;
         } = {}
       ): Promise<${getTypeNames(property.range, types)} | null> {
         if (this._warning != null) {
@@ -1762,25 +2021,46 @@ async function* generateProperty(type, property, types, moduleVarNames) {
           );
         }
         if (this.${await getFieldName(property.uri)}.length < 1) return null;
+        if (
+          options.verifyPortableObject == null &&
+          this._verifyPortableObject != null
+        ) {
+          options = {
+            ...options,
+            verifyPortableObject: this._verifyPortableObject,
+          };
+        }
         let v = this.${await getFieldName(property.uri)}[0];
         if (!(v instanceof URL) &&
-            v.id != null &&
-            !isTrustedIriOrigin(options, v.id, this.id) &&
             !this.${await getFieldName(property.uri, "#_trust")}.has(0)) {
-          v = v.id;
+          if (v.id == null) {
+            if (isUnsecuredPortableObject(this)) {
+              warnUnverifiableEmbeddedObject(this, ${JSON.stringify(property.uri)});
+              return null;
+            }
+          } else if (
+            !isTrustedIriOrigin(options, v.id, ${trustOwner}) ||
+            isUnsecuredPortableObject(this) ||
+            mustDereferencePortableObject(this, ${trustOwner}, v.id, options)
+          ) {
+            v = v.id;
+          }
         }
         if (v instanceof URL) {
           const fetched =
             await this.#fetch${pascalCase(property.singularName)}(v, options);
           if (fetched == null) return null;
+          // Not cached, so that it is verified when the portable object
+          // policy applies later:
+          if (isUnverifiedPortableClaim(fetched)) return fetched;
           this.${await getFieldName(property.uri)}[0] = fetched;
           this.${await getFieldName(property.uri, "#_trust")}.add(0);
           this._cachedJsonLd = undefined;
+          recordPortableReferrer(this, fetched, ${JSON.stringify(property.uri)});
           return fetched;
         }
       `;
-			if (property.compactName != null) {
-				yield `
+			if (property.compactName != null) yield `
         if (
           this._cachedJsonLd != null &&
           typeof this._cachedJsonLd === "object" &&
@@ -1791,26 +2071,36 @@ async function* generateProperty(type, property, types, moduleVarNames) {
             ${JSON.stringify(property.compactName)}];
           const doc = Array.isArray(prop) ? prop[0] : prop;
           if (doc != null && typeof doc === "object" && "@context" in doc) {
-      `;
-				yield `
-            v = await this.#${property.singularName}_fromJsonLd(doc, {
-              ...options,
-              baseUrl: ${cachedPropertyBaseUrl},
-            });
-      `;
-				yield `
+            try {
+              v = await this.#${property.singularName}_fromJsonLd(doc, {
+                ...options,
+                // Keep the parent default for embedded objects.
+                verifyPortableObject: this._verifyPortableObject,
+                baseUrl: ${cachedPropertyBaseUrl},
+              });
+            } catch (error) {
+              if (!options.suppressError) throw error;
+              getLogger(["fedify", "vocab"]).debug(
+                "Failed to parse embedded value of {property}: {error}",
+                { property: ${JSON.stringify(property.uri)}, error },
+              );
+              return null;
+            }
           }
         }
         `;
-			}
 			yield `
         if (v?.id != null &&
-            this.id != null && !isTrustedIriOrigin(options, v.id, this.id) &&
+            ((${type.trustEmbeddedObjects === false ? "" : "this.id != null && "}!isTrustedIriOrigin(options, v.id, ${trustOwner})) ||
+              isUnsecuredPortableObject(this) ||
+              mustDereferencePortableObject(
+                this, ${trustOwner}, v.id, options,
+              )) &&
             !this.${await getFieldName(property.uri, "#_trust")}.has(0)) {
           if (options.crossOrigin === "throw") {
             throw new Error(
               "The property object's @id (" + v.id.href + ") has a different " +
-              "origin than the property owner's @id (" + this.id.href + "); " +
+              "origin than the property owner's @id (" + ${type.trustEmbeddedObjects === false ? "\"untrusted metadata\"" : "(this.id?.href ?? null)"} + "); " +
               "refusing to return the object.  If you want to bypass this " +
               "check and are aware of the security implications, set the " +
               'crossOrigin option to "trust".'
@@ -1822,10 +2112,11 @@ async function* generateProperty(type, property, types, moduleVarNames) {
             "return the object.  If you want to bypass this check and are " +
             "aware of the security implications, set the crossOrigin option " +
             'to "trust".',
-            { objectId: v.id.href, parentObjectId: this.id.href },
+            { objectId: v.id.href, parentObjectId: ${type.trustEmbeddedObjects === false ? "\"untrusted metadata\"" : "(this.id?.href ?? null)"} },
           );
           return null;
         }
+        recordPortableReferrer(this, v, ${JSON.stringify(property.uri)});
         return v;
       }
       `;
@@ -1858,6 +2149,21 @@ async function* generateProperty(type, property, types, moduleVarNames) {
           suppressError?: boolean,
           tracerProvider?: TracerProvider,
           crossOrigin?: "ignore" | "throw" | "trust";
+          gateways?: readonly (string | URL)[];
+          verifyPortableObject?: PortableObjectVerifier;
+          /**
+           * Whether objects that this call newly fetches use the
+           * \`verifyPortableObject\` option of this call as their default
+           * verifier.  Defaults to \`true\`.  If \`false\`, the option
+           * applies to this call only, and fetched objects use this object's
+           * own default verifier, if any, as their default instead.  Pass
+           * \`false\` for a temporary verifier, e.g., one that accepts
+           * everything.  Objects that were already cached in this object or
+           * embedded in it keep their defaults either way, and this option
+           * itself is not passed on.
+           * @since 2.4.0
+           */
+          inheritPortableObjectVerifier?: boolean;
         } = {}
       ): AsyncIterable<${getTypeNames(property.range, types)}> {
         if (this._warning != null) {
@@ -1866,28 +2172,52 @@ async function* generateProperty(type, property, types, moduleVarNames) {
             this._warning.values
           );
         }
+        if (
+          options.verifyPortableObject == null &&
+          this._verifyPortableObject != null
+        ) {
+          options = {
+            ...options,
+            verifyPortableObject: this._verifyPortableObject,
+          };
+        }
         const vs = this.${await getFieldName(property.uri)};
         for (let i = 0; i < vs.length; i++) {
           let v = vs[i];
           if (!(v instanceof URL) &&
-              v.id != null &&
-              !isTrustedIriOrigin(options, v.id, this.id) &&
               !this.${await getFieldName(property.uri, "#_trust")}.has(i)) {
-            v = v.id;
+            if (v.id == null) {
+              if (isUnsecuredPortableObject(this)) {
+                warnUnverifiableEmbeddedObject(this, ${JSON.stringify(property.uri)});
+                continue;
+              }
+            } else if (
+              !isTrustedIriOrigin(options, v.id, ${trustOwner}) ||
+              isUnsecuredPortableObject(this) ||
+              mustDereferencePortableObject(this, ${trustOwner}, v.id, options)
+            ) {
+              v = v.id;
+            }
           }
           if (v instanceof URL) {
             const fetched =
               await this.#fetch${pascalCase(property.singularName)}(v, options);
             if (fetched == null) continue;
+            // Not cached, so that it is verified when the portable object
+            // policy applies later:
+            if (isUnverifiedPortableClaim(fetched)) {
+              yield fetched;
+              continue;
+            }
             vs[i] = fetched;
             this.${await getFieldName(property.uri, "#_trust")}.add(i);
             this._cachedJsonLd = undefined;
+            recordPortableReferrer(this, fetched, ${JSON.stringify(property.uri)});
             yield fetched;
             continue;
           }
       `;
-			if (property.compactName != null) {
-				yield `
+			if (property.compactName != null) yield `
           if (
             this._cachedJsonLd != null &&
             typeof this._cachedJsonLd === "object" &&
@@ -1898,26 +2228,36 @@ async function* generateProperty(type, property, types, moduleVarNames) {
               ${JSON.stringify(property.compactName)}];
             const obj = Array.isArray(prop) ? prop[i] : prop;
             if (obj != null && typeof obj === "object" && "@context" in obj) {
-      `;
-				yield `
-              v = await this.#${property.singularName}_fromJsonLd(obj, {
-                ...options,
-                baseUrl: ${cachedPropertyBaseUrl},
-              });
-      `;
-				yield `
+              try {
+                v = await this.#${property.singularName}_fromJsonLd(obj, {
+                  ...options,
+                // Keep the parent default for embedded objects.
+                verifyPortableObject: this._verifyPortableObject,
+                  baseUrl: ${cachedPropertyBaseUrl},
+                });
+              } catch (error) {
+                if (!options.suppressError) throw error;
+                getLogger(["fedify", "vocab"]).debug(
+                  "Failed to parse embedded value of {property} at index {index}: {error}",
+                  { property: ${JSON.stringify(property.uri)}, index: i, error },
+                );
+                continue;
+              }
             }
           }
         `;
-			}
 			yield `
           if (v?.id != null &&
-              this.id != null && !isTrustedIriOrigin(options, v.id, this.id) &&
+              ((${type.trustEmbeddedObjects === false ? "" : "this.id != null && "}!isTrustedIriOrigin(options, v.id, ${trustOwner})) ||
+                isUnsecuredPortableObject(this) ||
+                mustDereferencePortableObject(
+                  this, ${trustOwner}, v.id, options,
+                )) &&
               !this.${await getFieldName(property.uri, "#_trust")}.has(i)) {
             if (options.crossOrigin === "throw") {
               throw new Error(
                 "The property object's @id (" + v.id.href + ") has a different " +
-                "origin than the property owner's @id (" + this.id.href + "); " +
+                "origin than the property owner's @id (" + ${type.trustEmbeddedObjects === false ? "\"untrusted metadata\"" : "(this.id?.href ?? null)"} + "); " +
                 "refusing to return the object.  If you want to bypass this " +
                 "check and are aware of the security implications, set the " +
                 'crossOrigin option to "trust".'
@@ -1929,10 +2269,11 @@ async function* generateProperty(type, property, types, moduleVarNames) {
               "return the object.  If you want to bypass this check and are " +
               "aware of the security implications, set the crossOrigin " +
               'option to "trust".',
-              { objectId: v.id.href, parentObjectId: this.id.href },
+              { objectId: v.id.href, parentObjectId: ${type.trustEmbeddedObjects === false ? "\"untrusted metadata\"" : "(this.id?.href ?? null)"} },
             );
             continue;
           }
+          recordPortableReferrer(this, v, ${JSON.stringify(property.uri)});
           yield v;
         }
       }
@@ -1950,10 +2291,35 @@ const XSD_ANY_URI = "http://www.w3.org/2001/XMLSchema#anyURI";
 const FEDIFY_URL = "fedify:url";
 const INTERNAL_RUNTIME_IMPORTS = [
 	"compactJsonLdCache",
+	"createScopedContextLoader",
 	"getJsonLdContext",
+	"getPortableActorGateways",
 	"isTrustedIriOrigin",
 	"normalizeJsonLdIris"
 ].join(",\n    ");
+const PORTABLE_DEREFERENCE_IMPORTS = [
+	"copyPortableProvenance",
+	"createSnapshotContextLoader",
+	"dereferencePortableIri",
+	"getPortableResponseClaim",
+	"getReferrerGateways",
+	"isPortableIri",
+	"isPortableMode",
+	"isUnsecuredPortableObject",
+	"isUnverifiedPortableClaim",
+	"markUnverifiedPortableClaim",
+	"mustDereferencePortableObject",
+	"parseCompatibleEf61Reference",
+	"type PortableResponseClaim",
+	"recordPortableReferrer",
+	"rejectMalformedCompatibleReference",
+	"warnUnverifiableEmbeddedObject"
+].join(",\n    ");
+const SIGNED_REPRESENTATION_IMPORTS = [
+	"enterSignedValueScope",
+	"resolveSignedValues",
+	"retainedSignedValueRef"
+].join(",\n    ");
 const RUNTIME_IMPORTS = [
 	"canParseDecimal",
 	"decodeMultibase",
@@ -1973,6 +2339,7 @@ const RUNTIME_IMPORTS = [
 	"parseGatewayUrl",
 	"parseIri",
 	"parseJsonLdId",
+	"type PortableObjectVerifier",
 	"type RemoteDocument"
 ].join(",\n    ");
 /**
@@ -2008,6 +2375,7 @@ async function* generateClass(typeUri, types, moduleVarNames) {
     readonly #documentLoader?: DocumentLoader;
     readonly #contextLoader?: DocumentLoader;
     readonly #tracerProvider?: TracerProvider;
+    readonly #verifyPortableObject?: PortableObjectVerifier;
     readonly #warning?: {
       category: string[];
       message: string;
@@ -2015,6 +2383,7 @@ async function* generateClass(typeUri, types, moduleVarNames) {
     };
     #cachedJsonLd?: unknown;
     readonly #_baseUrl?: URL;
+    #shouldCacheJsonLd = true;
     readonly id: URL | null;
 
     protected get _documentLoader(): DocumentLoader | undefined {
@@ -2029,6 +2398,10 @@ async function* generateClass(typeUri, types, moduleVarNames) {
         return this.#tracerProvider;
     }
 
+    protected get _verifyPortableObject(): PortableObjectVerifier | undefined {
+      return this.#verifyPortableObject;
+    }
+
     protected get _warning(): {
         category: string[];
         message: string;
@@ -2048,6 +2421,20 @@ async function* generateClass(typeUri, types, moduleVarNames) {
     protected get _baseUrl(): URL | undefined {
       return this.#_baseUrl;
     }
+
+    protected get _shouldCacheJsonLd(): boolean {
+      return this.#shouldCacheJsonLd;
+    }
+
+    protected set _shouldCacheJsonLd(value: boolean) {
+      this.#shouldCacheJsonLd = value;
+    }
+
+    protected static _shouldCacheDecodedJsonLd(value: unknown): boolean {
+      if (value == null || typeof value !== "object") return true;
+      if (!("_shouldCacheJsonLd" in value)) return true;
+      return (value as { _shouldCacheJsonLd: boolean })._shouldCacheJsonLd;
+    }
     `;
 	yield `
     /**
@@ -2134,11 +2521,69 @@ async function* generateClasses(types) {
     from "@opentelemetry/api";\n`;
 	yield `import {\n    ${RUNTIME_IMPORTS}\n} from "@fedify/vocab-runtime";\n`;
 	yield `import {\n    ${INTERNAL_RUNTIME_IMPORTS}\n} from "@fedify/vocab-runtime/internal/jsonld-cache";\n`;
+	yield `import {\n    ${PORTABLE_DEREFERENCE_IMPORTS}\n} from "@fedify/vocab-runtime/internal/portable-dereference";\n`;
+	yield `import {\n    ${SIGNED_REPRESENTATION_IMPORTS}\n} from "@fedify/vocab-runtime/internal/signed-representation";\n`;
 	yield `import {
     isTemporalDuration,
     isTemporalInstant,
 } from "@fedify/vocab-runtime/temporal";\n`;
-	const portableIriKeys = new Set(["@id", "id"]);
+	yield `
+function canDecodeIri(iri: string): boolean {
+  try { parseIri(iri); return true; } catch { return iri.startsWith("at://"); }
+}
+
+function decodeIri(iri: string): URL {
+  return !URL.canParse(iri) && iri.startsWith("at://")
+    ? new URL("at://" + encodeURIComponent(iri.substring(5)))
+    : parseIri(iri);
+}
+
+function inspectIri(iri: URL): string {
+  // Inspecting an object must not throw, even for a URL that cannot be
+  // formatted as an IRI, e.g., a malformed portable ID:
+  try { return formatIri(iri); } catch { return iri.href; }
+}
+`;
+	yield `
+function isValidLanguageTag(language: string): boolean {
+  try {
+    new Intl.Locale(language);
+    return true;
+  } catch (error) {
+    if (error instanceof RangeError) return false;
+    throw error;
+  }
+}
+`;
+	const extraContexts = Object.fromEntries(Object.values(types).flatMap((type) => type.properties.flatMap((property) => property.extraContext == null ? [] : [[property.uri, property.extraContext]])));
+	if (Object.keys(extraContexts).length > 0) yield `
+const extraPropertyContexts: Readonly<Record<string, string>> =
+  ${JSON.stringify(extraContexts)};
+
+function getExtraContexts(document: unknown): string[] {
+  const contexts = new Set<string>();
+  const pending: unknown[] = [document];
+  while (pending.length > 0) {
+    const value = pending.pop();
+    if (value == null || typeof value !== "object") continue;
+    if (Array.isArray(value)) {
+      for (const item of value) pending.push(item);
+      continue;
+    }
+    if ("@value" in value) continue;
+    for (const [key, child] of globalThis.Object.entries(value)) {
+      if (key === "@context") continue;
+      if (globalThis.Object.hasOwn(extraPropertyContexts, key)) {
+        contexts.add(extraPropertyContexts[key]);
+      }
+      pending.push(child);
+    }
+  }
+  return [...contexts];
+}
+`;
+	yield "\n\n";
+	const portableIriKeys = /* @__PURE__ */ new Set(["@id", "id"]);
 	for (const type of Object.values(types)) for (const property of type.properties) addPortableIriKeys(portableIriKeys, property, types);
 	yield "const PORTABLE_IRI_PATTERN = /^ap(?:\\+ef61)?:\\/\\//i;\n";
 	yield `const PORTABLE_IRI_KEYS: ReadonlySet<string> = new Set(${JSON.stringify([...portableIriKeys].sort())});\n\n`;