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

package/src/class.ts

@@ -14,10 +14,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",
@@ -31,10 +56,13 @@ const RUNTIME_IMPORTS = [
   "importMultibaseKey",
   "importPem",
   "isDecimal",
+  "isGatewayUrl",
   "LanguageString",
   "parseDecimal",
+  "parseGatewayUrl",
   "parseIri",
   "parseJsonLdId",
+  "type PortableObjectVerifier",
   "type RemoteDocument",
 ].join(",\n    ");
 
@@ -84,6 +112,7 @@ async function* generateClass(
     readonly #documentLoader?: DocumentLoader;
     readonly #contextLoader?: DocumentLoader;
     readonly #tracerProvider?: TracerProvider;
+    readonly #verifyPortableObject?: PortableObjectVerifier;
     readonly #warning?: {
       category: string[];
       message: string;
@@ -91,6 +120,7 @@ async function* generateClass(
     };
     #cachedJsonLd?: unknown;
     readonly #_baseUrl?: URL;
+    #shouldCacheJsonLd = true;
     readonly id: URL | null;
 
     protected get _documentLoader(): DocumentLoader | undefined {
@@ -105,6 +135,10 @@ async function* generateClass(
         return this.#tracerProvider;
     }
 
+    protected get _verifyPortableObject(): PortableObjectVerifier | undefined {
+      return this.#verifyPortableObject;
+    }
+
     protected get _warning(): {
         category: string[];
         message: string;
@@ -124,6 +158,20 @@ async function* generateClass(
     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 `
@@ -251,10 +299,79 @@ export async function* generateClasses(
     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`;
+  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;
+  }
+}
+`;
+  // Contexts are activated by expanded property IRIs left after compaction.
+  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 = new Set(["@id", "id"]);
   for (const type of Object.values(types)) {
     for (const property of type.properties) {

package/src/codec.ts

@@ -6,12 +6,14 @@ import {
   areAllScalarTypes,
   emitOverride,
   getAllProperties,
+  getDataCheck,
   getDecoder,
   getDecoders,
   getEncoders,
   getSubtypes,
   getTypeNames,
   isCompactableType,
+  skipsUnparsable,
 } from "./type.ts";
 
 function* generatePreprocessorBlock(
@@ -43,6 +45,7 @@ function* generatePreprocessorBlock(
             documentLoader: options.documentLoader,
             contextLoader: options.contextLoader,
             tracerProvider: options.tracerProvider,
+            verifyPortableObject: options.verifyPortableObject,
             baseUrl: ${baseUrlExpr},
           });
           if (_result instanceof Error) throw _result;
@@ -95,6 +98,10 @@ export async function* generateEncoder(
       ...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 `
@@ -127,6 +134,7 @@ export async function* generateEncoder(
         const item = (
       `;
       if (!areAllScalarTypes(property.range, types)) {
+        yield "retainedSignedValueRef(v, signedValues.scope) ?? (";
         yield "v instanceof URL ? formatIri(v) : ";
       }
       const encoders = getEncoders(
@@ -137,6 +145,7 @@ export async function* generateEncoder(
         true,
       );
       for (const code of encoders) yield code;
+      if (!areAllScalarTypes(property.range, types)) yield ")";
       yield `
         );
         compactItems.push(item);
@@ -180,7 +189,9 @@ export async function* generateEncoder(
     }
       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;
     }
     `;
   }
@@ -207,16 +218,23 @@ export async function* generateEncoder(
     yield `
     array = [];
     for (const v of this.${await getFieldName(property.uri)}) {
-      const element = (
+      let element = (
     `;
     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 });`;
@@ -254,16 +272,41 @@ export async function* generateEncoder(
     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
   `;
@@ -295,13 +338,18 @@ export async function* generateEncoder(
   }
   yield `
     }
-    return compacted;
+    return signedValues.owner
+      ? resolveSignedValues(compacted, signedValues.scope)
+      : compacted;
   }
 
   protected ${emitOverride(typeUri, types)} isCompactable(): boolean {
 `;
   for (const property of type.properties) {
-    if (!property.range.every((r) => isCompactableType(r, types))) {
+    if (
+      property.extraContext != null ||
+      !property.range.every((r) => isCompactableType(r, types))
+    ) {
       yield `
       if (
         this.${await getFieldName(property.uri)} != null &&
@@ -331,6 +379,10 @@ export async function* generateDecoder(
    *                - \`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.
    */
@@ -340,6 +392,7 @@ export async function* generateDecoder(
       documentLoader?: DocumentLoader,
       contextLoader?: DocumentLoader,
       tracerProvider?: TracerProvider,
+      verifyPortableObject?: PortableObjectVerifier,
       baseUrl?: URL,
     } = {},
   ): Promise<${type.name}> {
@@ -378,6 +431,7 @@ export async function* generateDecoder(
       documentLoader?: DocumentLoader,
       contextLoader?: DocumentLoader,
       tracerProvider?: TracerProvider,
+      verifyPortableObject?: PortableObjectVerifier,
       baseUrl?: URL,
     } = {},
   ): Promise<${type.name}> {
@@ -394,7 +448,17 @@ export async function* generateDecoder(
     // 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 {
@@ -455,8 +519,9 @@ export async function* generateDecoder(
     `;
   } 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,
@@ -466,12 +531,18 @@ export async function* generateDecoder(
     }
     `;
   }
+  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`;
+    const propertyValues = property.uri === "https://w3id.org/fep/ef61/gateways"
+      ? "getPortableActorGateways(values) as typeof values[string]"
+      : `values[${JSON.stringify(property.uri)}]`;
     yield `
-    let ${arrayVariable} = values[${JSON.stringify(property.uri)}];
+    let ${arrayVariable} = ${propertyValues};
     `;
     if (property.functional && property.redundantProperties != null) {
       for (const prop of property.redundantProperties) {
@@ -482,13 +553,25 @@ export async function* generateDecoder(
         `;
       }
     }
+    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;
     `;
@@ -510,23 +593,25 @@ export async function* generateDecoder(
       }
       `;
     }
+    yield `
+      const decoded =
+    `;
+    const lenient = property.range.length == 1 &&
+      skipsUnparsable(property.range[0]);
     if (property.range.length == 1) {
-      yield `
-      const decoded = ${
-        getDecoder(
-          property.range[0],
-          types,
-          "v",
-          "options",
-          propertyBaseUrl,
-        )
-      };
-      if (typeof decoded === "undefined") continue;
-      ${variable}.push(decoded);`;
+      if (lenient) {
+        yield getDataCheck(property.range[0], types, "v");
+        yield " ? ";
+      }
+      yield getDecoder(
+        property.range[0],
+        types,
+        "v",
+        "options",
+        propertyBaseUrl,
+      );
+      if (lenient) yield " : undefined";
     } else {
-      yield `
-      const decoded =
-      `;
       const decoders = getDecoders(
         property.range,
         types,
@@ -535,19 +620,33 @@ export async function* generateDecoder(
         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;

package/src/constructor.ts

@@ -89,6 +89,7 @@ export async function* generateConstructor(
       documentLoader?: DocumentLoader,
       contextLoader?: DocumentLoader,
       tracerProvider?: TracerProvider,
+      verifyPortableObject?: PortableObjectVerifier,
     } = {},
   ) {
   `;
@@ -97,6 +98,7 @@ export async function* generateConstructor(
     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) {
@@ -208,6 +210,13 @@ export async function* generateCloner(
   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.
@@ -221,6 +230,7 @@ export async function* generateCloner(
     options: {
       documentLoader?: DocumentLoader,
       contextLoader?: DocumentLoader,
+      verifyPortableObject?: PortableObjectVerifier,
     } = {}
   ): ${type.name} {
     if (this._warning != null) {
@@ -239,6 +249,7 @@ export async function* generateCloner(
       { id: values.id ?? this.id },
       options
     );
+    copyPortableProvenance(this, clone);
     `;
   } else {
     yield `const clone = super.clone(values, options) as unknown as ${type.name};`;

package/src/inspector.ts

@@ -21,12 +21,12 @@ export async function* generateInspector(
         [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),
       };
     }
     `;
@@ -44,12 +44,12 @@ export async function* generateInspector(
               [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);
     `;