@fedify/vocab-tools 2.4.0-dev.1962 → 2.4.0-dev.1964

package/README.md

@@ -46,3 +46,21 @@ mise run test:update_snapshots
 
 Review and commit every changed snapshot file.  Updating only one runtime
 leaves the other test suites with stale expectations.
+
+
+Conditional contexts and metadata trust
+---------------------------------------
+
+A property schema can set `extraContext` to a context URL.  The generated
+serializer adds it to its default context when the property's expanded IRI
+appears after compaction, including inside nested objects.  A caller-provided
+context takes precedence.  When populated, such a property uses the JSON-LD
+processor so context container rules, including `@set`, are respected.
+
+A type schema can set `trustEmbeddedObjects: false` when its identifier is
+metadata rather than a resource that establishes an origin.  Its own
+entity-valued accessors then fetch embedded objects with identifiers instead
+of trusting a matching origin.  Locally constructed values, previously fetched
+values, and the explicit `crossOrigin: "trust"` option retain their usual
+behavior.  This does not verify id-less embedded objects or establish publishing
+authority.

package/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/vocab-tools",
-  "version": "2.4.0-dev.1962+8aaa5348",
+  "version": "2.4.0-dev.1964+1d28dc03",
   "license": "MIT",
   "exports": {
     ".": "./src/mod.ts"

package/dist/mod.cjs

@@ -8,7 +8,7 @@ let yaml = require("yaml");
 let es_toolkit = require("es-toolkit");
 //#region deno.json
 var name = "@fedify/vocab-tools";
-var version = "2.4.0-dev.1962+8aaa5348";
+var version = "2.4.0-dev.1964+1d28dc03";
 //#endregion
 //#region src/type.ts
 const HEURISTICS_CONTEXTS = [
@@ -916,13 +916,29 @@ async function* generateEncoder(typeUri, types) {
         },
       );
     }
-    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
   `;
@@ -951,7 +967,7 @@ async function* generateEncoder(typeUri, types) {
 
   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
@@ -1577,6 +1593,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 ??
@@ -1807,7 +1824,7 @@ async function* generateProperty(type, property, types, moduleVarNames) {
         let v = this.${await getFieldName(property.uri)}[0];
         if (!(v instanceof URL) &&
             v.id != null &&
-            !isTrustedIriOrigin(options, v.id, this.id) &&
+            !isTrustedIriOrigin(options, v.id, ${trustOwner}) &&
             !this.${await getFieldName(property.uri, "#_trust")}.has(0)) {
           v = v.id;
         }
@@ -1847,12 +1864,12 @@ async function* generateProperty(type, property, types, moduleVarNames) {
 			}
 			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}) &&
             !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"} + "); " +
               "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".'
@@ -1864,7 +1881,7 @@ 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"} },
           );
           return null;
         }
@@ -1913,7 +1930,7 @@ async function* generateProperty(type, property, types, moduleVarNames) {
           let v = vs[i];
           if (!(v instanceof URL) &&
               v.id != null &&
-              !isTrustedIriOrigin(options, v.id, this.id) &&
+              !isTrustedIriOrigin(options, v.id, ${trustOwner}) &&
               !this.${await getFieldName(property.uri, "#_trust")}.has(i)) {
             v = v.id;
           }
@@ -1954,12 +1971,12 @@ async function* generateProperty(type, property, types, moduleVarNames) {
 			}
 			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}) &&
               !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"} + "); " +
                 "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".'
@@ -1971,7 +1988,7 @@ 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"} },
             );
             continue;
           }
@@ -2205,6 +2222,33 @@ function isValidLanguageTag(language: string): boolean {
     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"]);

package/dist/mod.d.cts

@@ -36,6 +36,13 @@ interface TypeSchema {
   */
   entity: boolean;
   /**
+  * Whether this type's id can establish same-origin trust for its own
+  * embedded entity-valued properties.  Defaults to true.  Set to false for
+  * metadata whose id does not identify an independently fetched resource.
+  * Locally constructed and explicitly trusted values remain trusted.
+  */
+  trustEmbeddedObjects?: boolean;
+  /**
   * Whether the type omits `@type` in JSON-LD serialization.  When `true`,
   * the generated `toJsonLd()` method will not emit `@type` (or `type` in
   * compact form) in the serialized JSON-LD.  The generated `fromJsonLd()`
@@ -61,6 +68,13 @@ interface TypeSchema {
   defaultContext: Context;
 }
 interface PropertySchemaBase {
+  /**
+  * A context URL added to the default serialization context when this
+  * property's expanded IRI appears in the compacted document.  Explicit
+  * caller contexts are unchanged.  Populated properties with this option
+  * use the JSON-LD processor instead of compact serialization heuristics.
+  */
+  extraContext?: string;
   /**
   * The singular form of the property name.  It is used as the name of the
   * generated property accessors.

package/dist/mod.d.ts

@@ -36,6 +36,13 @@ interface TypeSchema {
   */
   entity: boolean;
   /**
+  * Whether this type's id can establish same-origin trust for its own
+  * embedded entity-valued properties.  Defaults to true.  Set to false for
+  * metadata whose id does not identify an independently fetched resource.
+  * Locally constructed and explicitly trusted values remain trusted.
+  */
+  trustEmbeddedObjects?: boolean;
+  /**
   * Whether the type omits `@type` in JSON-LD serialization.  When `true`,
   * the generated `toJsonLd()` method will not emit `@type` (or `type` in
   * compact form) in the serialized JSON-LD.  The generated `fromJsonLd()`
@@ -61,6 +68,13 @@ interface TypeSchema {
   defaultContext: Context;
 }
 interface PropertySchemaBase {
+  /**
+  * A context URL added to the default serialization context when this
+  * property's expanded IRI appears in the compacted document.  Explicit
+  * caller contexts are unchanged.  Populated properties with this option
+  * use the JSON-LD processor instead of compact serialization heuristics.
+  */
+  extraContext?: string;
   /**
   * The singular form of the property name.  It is used as the name of the
   * generated property accessors.

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-dev.1962+8aaa5348";
+var version = "2.4.0-dev.1964+1d28dc03";
 //#endregion
 //#region src/type.ts
 const HEURISTICS_CONTEXTS = [
@@ -915,13 +915,29 @@ async function* generateEncoder(typeUri, types) {
         },
       );
     }
-    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
   `;
@@ -950,7 +966,7 @@ async function* generateEncoder(typeUri, types) {
 
   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
@@ -1576,6 +1592,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 ??
@@ -1806,7 +1823,7 @@ async function* generateProperty(type, property, types, moduleVarNames) {
         let v = this.${await getFieldName(property.uri)}[0];
         if (!(v instanceof URL) &&
             v.id != null &&
-            !isTrustedIriOrigin(options, v.id, this.id) &&
+            !isTrustedIriOrigin(options, v.id, ${trustOwner}) &&
             !this.${await getFieldName(property.uri, "#_trust")}.has(0)) {
           v = v.id;
         }
@@ -1846,12 +1863,12 @@ async function* generateProperty(type, property, types, moduleVarNames) {
 			}
 			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}) &&
             !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"} + "); " +
               "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".'
@@ -1863,7 +1880,7 @@ 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"} },
           );
           return null;
         }
@@ -1912,7 +1929,7 @@ async function* generateProperty(type, property, types, moduleVarNames) {
           let v = vs[i];
           if (!(v instanceof URL) &&
               v.id != null &&
-              !isTrustedIriOrigin(options, v.id, this.id) &&
+              !isTrustedIriOrigin(options, v.id, ${trustOwner}) &&
               !this.${await getFieldName(property.uri, "#_trust")}.has(i)) {
             v = v.id;
           }
@@ -1953,12 +1970,12 @@ async function* generateProperty(type, property, types, moduleVarNames) {
 			}
 			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}) &&
               !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"} + "); " +
                 "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".'
@@ -1970,7 +1987,7 @@ 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"} },
             );
             continue;
           }
@@ -2204,6 +2221,33 @@ function isValidLanguageTag(language: string): boolean {
     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"]);

package/dist/schema.yaml

@@ -72,6 +72,14 @@ $defs:
   property-base:
     type: object
     properties:
+      extraContext:
+        description: >-
+          A context URL added to default serialization when this property's
+          expanded IRI appears in the compacted document. Explicit caller
+          contexts are unchanged. Populated properties use the JSON-LD
+          processor instead of compact serialization heuristics.
+        type: string
+        format: uri
       singularName:
         description: >-
           The singular form of the property name.  It is used as the name of the
@@ -250,6 +258,13 @@ properties:
 
       The extended subtypes must have the consistent value of this flag.
     type: boolean
+  trustEmbeddedObjects:
+    description: >-
+      Whether this type's id establishes same-origin trust for its own
+      embedded entity-valued properties. Defaults to true. Set to false
+      for metadata ids that do not identify independently fetched resources.
+      Locally constructed and explicitly trusted values remain trusted.
+    type: boolean
   typeless:
     description: >-
       Whether the type omits @type in JSON-LD serialization.  When true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/vocab-tools",
-  "version": "2.4.0-dev.1962+8aaa5348",
+  "version": "2.4.0-dev.1964+1d28dc03",
   "description": "Code generator for Activity Vocabulary APIs",
   "homepage": "https://fedify.dev/",
   "repository": {